bug(launcher): on exit, gentle-shell suggests `pi --session <id>`, which cannot find the session

[matraket]

Before submitting

• I searched open and closed issues and did not find a report of this problem.
• I reviewed this report and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem

When you quit an interactive session started with gentle-shell, Pi prints:

To resume this session: pi --session <id>

That command does not work: Pi answers No session found matching '<id>'. The hint sends users into an error at the exact moment they want to get back to their work.

Cause. The launcher starts Pi with PI_CODING_AGENT_DIR pointing at the gentle-shell home (~/.gentle-shell/agent in isolated mode, the default), and that is where sessions are stored. Pi builds the hint in formatResumeCommand (dist/modes/interactive/interactive-mode.js in 0.87.1) using its own binary name (pi). Because the session lives in the default session directory of that home, Pi adds no --session-dir and never mentions PI_CODING_AGENT_DIR. As a result, pi --session <id> looks in ~/.pi/agent and finds nothing.

What does work today is gentle-shell --session <id>, because the launcher passes --session through to Pi. Nothing tells the user that, though.

The clean fix belongs in Pi, and the community has already tried twice. Pi generates the hint, so Pi is the right place to fix it. Both community attempts were closed without a fix:

1. Resume message does not include PI_CODING_AGENT_DIR override earendil-works/pi#8048 (0.84.1, 2026-08-12): proposes including PI_CODING_AGENT_DIR in the hint when it is set. It was auto-closed as not planned by Pi's new-contributor policy. The author offered to implement it and got no reply.
2. InteractiveMode SDK option for application-specific resume commands earendil-works/pi#9750 and its PR Allow SDK callers to customize the interactive resume command earendil-works/pi#9749 (2026-09-18): propose an InteractiveModeOptions.formatResumeCommand option so embedders can show their own command. That is exactly what gentle-shell would need. Both the issue and the PR were auto-closed under the same policy.

Neither has been reopened, and formatResumeCommand is unchanged on Pi's current main. Pi does not look likely to fix this soon.

So I propose a workaround in gentle-shell. It is not the ideal fix: gentle-shell would be correcting, from the outside, a message that Pi writes. But it keeps users out of the error until Pi fixes it. If Pi ever accepts either proposal, the workaround can be removed in favor of Pi's mechanism. I explain how I built it in a comment.

Steps to reproduce

1. Start gentle-shell in isolated mode (the default, without --link).
2. Send a prompt and wait for the answer, so the session is saved.
3. Quit with /quit or Ctrl+D.
4. Pi prints To resume this session: pi --session <id>.
5. Run that command as printed.

Expected and actual behavior

Expected: on exit, a command that resumes the gentle-shell session, for example gentle-shell --session <id> (with --link or --home <dir> if the session was started that way).

Actual: the hint suggests pi --session <id>, which ends with:

No session found matching '01a0e27a-82f7-7588-a9d8-f62d61259f66'

The session exists under ~/.gentle-shell/agent/sessions/<cwd>/, and gentle-shell --session <id> opens it without problems.

gentle-pi version

3.7.0

Pi version

0.87.1

Operating system

Windows (WSL)

Relevant logs or error output (optional)

$ pi --session 01a0e27a-82f7-7588-a9d8-f62d61259f66
No session found matching '01a0e27a-82f7-7588-a9d8-f62d61259f66'

[matraket]

I already have the fix developed and tested locally. I will open the PRs once this issue is approved.

As I said in the issue, this is a workaround: the clean fix would live in Pi (earendil-works/pi#8048 or #9750). That is why I built it as an isolated piece that is easy to remove: one extension plus one block in the launcher, touching nothing else. If Pi accepts either proposal, it can simply be removed in favor of Pi's mechanism.

How it works

The gentle-pi extension and the launcher pass the session through a temporary file:

1. The launcher creates a private handoff file and passes its path to Pi in GENTLE_SHELL_RESUME_HANDOFF.
2. On quit in the TUI, a new extension writes the session id to that file. It does so only under the same conditions in which Pi prints its hint (persisted session, existing session file).
3. When Pi exits, the launcher erases Pi's line with ANSI sequences (climbing as many rows as it used, wrap included) and prints gentle-shell [--link | --home <dir>] [--session-dir <dir>] --session <id> in its place.

Whenever anything is unclear, it leaves the terminal alone and keeps Pi's original line. Specifically, it does not rewrite when stdout is not a TTY, when Pi exits with a non-zero code, when a signal is involved, when the handoff is invalid, or when the line is not printable ASCII (its width could not be measured).

Details I took care of

• The extension claims the variable on load, so neither subagents nor tool shells inherit it. It survives /reload.
• SIGTERM/SIGHUP listeners are registered only in the TUI. In print mode Pi handles only SIGTERM, and an extra SIGHUP listener would keep Node from terminating when the terminal closes.
• Handoff values are validated against Pi's own session id charset and must be free of control characters, so they cannot inject terminal sequences.
• The mirror of Pi's command is pinned by a test against Pi's real formatResumeCommand and SessionManager. If a Pi bump changes the format, the test fails instead of the row count going wrong.
• End-to-end tests run in a real pseudo-terminal (via python3 pty; skipped on Windows or when python is missing).

Known limit

The launcher trusts that nothing writes to the terminal between Pi's hint and Pi's exit. Pi prints the hint right before exit(0), but an orphaned grandchild that inherited the terminal could write in that gap, and that line would be replaced instead. This is documented in the code.

Delivery

Three stacked PRs:

main
 └─ PR 1  pure logic (lib + tests)          330 lines  no effect yet
     └─ PR 2  extension (+ tests)            233 lines  inert without the launcher
         └─ PR 3  launcher (+ bin/PTY tests)  359 lines  this is where it turns on

Each PR passes the full suite (pnpm test), the typecheck, and the runtime and package checks on its own. The change went through 5 rounds of native review (RDD), all approved, and I tested it by hand in a real isolated gentle-shell session.

Heads-up in case it shows up in CI: tests/history-session-scan-extract.test.ts fails now and then in the tests that depend on a file's mtime. It is unrelated to this change and passes on retry.

[barbatdev]

Approved for implementation. I reproduced the misleading resume hint locally with Pi 0.87.1 using an isolated agent home: the suggested pi --session <id> could not find the session.

Thanks for the clear report and upstream investigation. Please link the stacked PRs so we can review them in order. We’ll evaluate the terminal-line replacement and its fallback behavior in the PR review; approving the issue doesn’t pre-approve that approach.

[Alan-TheGentleman]

Thanks for the thorough write-up and for chasing the upstream attempts. The diagnosis is spot on: formatResumeCommand builds pi --session <id> without knowing about PI_CODING_AGENT_DIR, so it can never resolve a gentle-shell session.

Before you open the stack, one request on the approach: we'd prefer appending a line instead of replacing Pi's line with ANSI sequences. Something like:

To resume this session: pi --session <id>
To resume in gentle-shell: gentle-shell --session <id>

Keep the handoff design (extension writes the id, launcher reads it), it's well thought out. What we want to drop is the cursor-up/erase part. Rewriting output another process wrote means measuring wrap, restricting to printable ASCII, and accepting the "wrong line gets erased" risk you documented. Appending avoids all of that. It leaves nothing to undo when Pi fixes this upstream, and it should shrink the change a lot (probably most of the PTY row-count tests go away).

Please keep the test that pins the format against Pi's real formatResumeCommand, that one is valuable either way. With that change, a single PR may be enough; if it still lands over 400 lines, the stacked plan is fine.

Separately, could you open an issue for the flaky mtime tests in tests/history-session-scan-extract.test.ts? Worth tracking on its own.

[matraket]

Thanks to you both. I applied the approach you proposed, @Alan-TheGentleman: append the gentle-shell line below Pi's instead of replacing it. The handoff and the test pinned against Pi's real formatResumeCommand stay, and the ANSI escapes and everything that depended on measuring the line are gone.

Here are the stacked PRs, to review in order, @barbatdev:

1. feat(shell): add the gentle-shell resume hint logic and extension #1515: logic and extension (inert on its own)
2. fix(shell): print a gentle-shell resume command when it exits #1516: launcher wiring (closes this issue)

Since I work from a fork, both target main; I explain it in each PR's stacking note.

I also opened #1514 for the flaky mtime tests in tests/history-session-scan-extract.test.ts. I found the cause: the test's 5 ms margin is smaller than the granularity of the kernel's file clock. If you approve it, I can open a PR with the fix.