feat(core): a shell that remembers what the last command did

[oratis]

Sixth and last implementation PR from docs/DSH_ADOPTION_PLAN.md §1.4.

The gap

Every Bash call is a fresh process. cd, export, source venv/bin/activate — all forgotten the moment it returns. The model's workaround is re-pasting the whole prefix into every command: long, easy to get wrong, and still unable to hold a running dev server.

ShellOpen / ShellRun / ShellClose / ShellList give it a shell that stays alive, keeping its working directory, environment, shell functions, and background jobs.

Deliberately not a PTY

dsh uses one. A PTY means node-pty — a native dependency needing a build for every platform the desktop ships to, which is a real release risk for a Mac-first product. The benefit it buys (full-screen programs: vim, top, less) is a small share of what makes a persistent shell useful.

So this runs over ordinary pipes, detecting command completion with a per-session random sentinel. Full-screen programs do not work, and ShellOpen's description says so plainly rather than letting the model find out by hanging.

Two consequences of that choice, both deliberate and both tested:

• Commands run with stdin from /dev/null. Otherwise cat swallows the sentinel and the session hangs until its deadline.
• stderr is merged at the shell, so the two streams interleave in the order they were actually written, the way a terminal shows them.

Interrupting without losing the shell

The first implementation signalled the process group. That kills the shell too — a non-interactive bash terminates on SIGINT — so every overrunning command would have destroyed the session. I probed the actual behaviour rather than guessing: signalling only the shell's children stops the command, bash reports exit 130, and the session survives with its state intact. There is a test asserting a shell is still usable, and still holds its variables, after a sleep 30 is interrupted.

exit still closes the shell, because that is what exit does. The caller is told the shell is gone rather than handed a dead id — there is a test pinning that, since it is the sort of thing one is tempted to paper over.

Lifetime is guaranteed, not remembered

The opponent case was leaks: a crashed session leaving orphaned shells on the machine. So the guarantee does not rest on the loop reaching its normal exit — runAgent wraps the run in a try/finally and closes every shell it opened even when the loop throws. There is a test that captures the registry from inside a tool, explodes the provider, and asserts the registry is empty afterwards.

Beyond that: idle shells close themselves (30 min, on an unref'd timer so an idle shell never holds the process open), there is a cap on how many can be open at once, and closing a shell kills what it started — tested by backgrounding a sleep 60 and asserting its pid is gone afterwards.

A host that owns its own registry (a REPL session) keeps its shells across runs; that path is tested too.

Sandbox

Confinement is resolved once, when the shell starts, and ShellOpen says so in its result. A later settings change does not re-arm a running shell — stating that is better than a policy that silently means something different than the user thinks.

Verification

pnpm typecheck, lint, format:check clean. Full suite green — core 1066 passed / 28 skipped, cli 242, desktop 104, server 49, protocol 34, lsp 13, vscode 12, scripts 42.

32 new tests against real shell processes, not mocks: cd persisting, export persisting, functions persisting, stderr interleaving, multi-line commands, a command printing sentinel-shaped text, cat not stealing the sentinel, interrupt-and-survive, child cleanup on close, the idle timeout and its reset, and the concurrency cap.

Not included

Wiring a session-scoped registry into the CLI REPL, so shells survive between turns rather than between tool calls within one run. The capability and its lifetime guarantees land here; the REPL ownership is a small follow-up that touches a different surface.