shiro-neko/.hermes/plans/background-bash.md

# Background bash — run long-lived commands without blocking the turn

Status: spec (implemented)
Date: 2026-09-11

## Problem

Running a dev server (or any long-lived command) via `bash` blocks the tool
until the process exits or the 120 s default timeout fires. A dev server never
exits, so the model burns the turn waiting, then gets a killed-by-timeout error
in which the server may or may not still be running. Dev workflows inside the
agent are effectively impossible.

## Design

Add an optional `background: true` mode to `bash`. Background commands:

- spawn detached (new process group / session) so the agent process can exit
  without taking them down, and so ctrl-c in the agent never kills them.
- return immediately with a `handle` (small integer), a `started` marker, and
  the first few lines of output (when available).
- keep streaming output into a per-handle ring buffer (capped) in memory;
  `bash_status` returns recent output and the current running/finished state.
- are reaped on agent shutdown — the module saves a `~/.shiro-neko/backgrounds.json`
  journal and kills live children on exit (kill `Bun.spawn` process).
- can be killed explicitly via `bash_stop` (the tool), or ctrl-c while focused,
  or `/bash` (the command).

### Why a handle + tools, not a long-lived "bash" result

Background processes are by definition not one-shot, so a single tool result
cannot represent them. Separating into `bash` (start/one-shot) + `bash_status`
(poll) + `bash_stop` (kill) keeps each tool's contract small and lets the agent
poll while continuing to work. The model is instructed to poll and stop when
done; otherwise the process lingers until shutdown reaps it.

### Why detached

`Bun.spawn(..., {detached: true})` (a.k.a. setsid) is required so that:
- killing the agent does not SIGKILL the dev server (kill process-group on exit
  is deliberate, see below);
- ctrl-c in the agent (which kills the agent's own process group) does not
  signal the dev server;
- `interruptBash()` keeps working for foreground commands only.

On Windows, process groups work differently (`detached` behaves differently in
Bun; the kill is best-effort). Document that background is primarily for
Unix-like dev servers.

## Tool changes

### `bash` — add `background?: boolean` and `name?: string`

- `background` default false (foreground = existing behavior, backward compat).
- `name` optional label used for /bash listing.
- When background:
  - spawn `bash -lc '<cmd>'` with `detached: true` (or `cmd /c` + best-effort on
    win32), pipes captured for streaming, no tool timeout (the process decides
    its own lifetime).
  - register in the module-level `backgrounds` map keyed by an incrementing
    handle.
  - return `running <handle>: <cmd> (background pid N)` — the model learns the
    handle and can poll.
- The `running` map (foreground, `interruptBash`) is untouched: foreground
  commands still behave exactly as today.

### `bash_status` — new `nav`/`core` read tool

- Input: `handle: number`.
- Output: one of:
  - `running`: `status: running (pid N)\n<recent output, tail capped>`
  - `finished`: `status: finished, exit: <code>\n<tail of captured output>`
  - `not found`: `status: no such handle`
- Implementation reuses `bashListener` streaming (sessions get live progress
  while a background command runs) and keeps a tail buffer per handle
  (`MAX_OUTPUT`-capped, so the model never burns context).

### `bash_stop` — new mutating tool

- Input: `handle: number`.
- Returns which command was killed (`killed <handle>: <cmd>`), or
  `no such handle` when absent. Reuses `killTree` (process-group aware) on the
  background process, awaited so the process really is gone.

### Tool registrations

- `bash_status`: `withMeta({ set: 'core', mutating: false })`, read tool, no
  approval needed (like `read_file`).
- `bash_stop`: `withMeta({ set: 'core', mutating: true })` — mutating requires
  a `DEFAULT_PERMISSIONS` entry + `subjectOf` case in `src/permission.ts`
  (falls back to `ask` on `*` otherwise, bypassing command gating).
- `bash` remains `mutating: true`; `bash_stop` and `bash` share the bash
  permission subject (`bash` subjectOf: `bash_stop` command = `bash <cmd>`),
  so an approved `bash` rule can also cover `bash_stop` (subject-derived).
- `MUTATING_TOOLS`/`TOOL_SETS` derive automatically via `_meta`.

### Default permissions

- `bash_stop` added to the mutating loop list (`src/permission.ts:223`).
- `subjectOf` (`src/permission.ts:306`) maps `bash_stop` → `'bash'` so existing
  bash rules apply (e.g. a blanket allow on `bash` covers stop).

## Session / UI

- `src/session.ts` streams background command output through the existing
  `onBashOutput` listener (live output panel in interactive mode, same as a
  foreground command's streaming).
- `src/ui/App.tsx`: render the `[bg N]` prefix from the `bash` tool result and
  make ctrl-c while no foreground command is running stop the most recently
  started background command (mirror of `interruptBash`). Keeps esc semantics:
  with a foreground command running, esc still kills it first.
- `src/commands.ts`: `/bash` command — `list` (default) shows
  `handle: cmd (running|exit N)`, `stop <id>` kills, `stop all` kills all.
  Parser case in `commands.ts`, UI switch in `App.tsx`.
- `src/cli.tsx` shutdown: before `process.exit`, call
  `shutdownBackgrounds()` (async kill live children + write journal).
  Best-effort — must not throw or delay exit. Journal written to
  `~/.shiro-neko/backgrounds.json` (SHIRO_HOME-aware via `store.ts` patterns).

### Prompt guidance

- `src/prompt.ts` bash tool descriptions: note that long-lived commands
  (dev servers, watchers, tests that run forever, `bun dev`) should use
  `background: true` and then be polled with `bash_status` and stopped with
  `bash_stop` when done. Instruct the model to always stop what it starts.

## Files touched

- `src/tools.ts` — bash background branch, `bash_status`, `bash_stop`,
  registry entries, `bgHandle` counter, `backgrounds` map, `killBackground`.
- `src/tool-utils.ts` — no change (meta derives).
- `src/permission.ts` — mutating list + `subjectOf` + DEFAULT_PERMISSIONS.
- `src/prompt.ts` — tool descriptions / guidance (bash description + status/stop).
- `src/session.ts` — listener wiring (streaming bg output) if not already
  covered by `onBashOutput`; nothing else needed.
- `src/commands.ts` — `/bash` command definition + parser case.
- `src/ui/App.tsx` — `/bash` switch case + ctrl-c background fallback.
- `src/cli.tsx` — shutdown reaping + journal.
- `test/tools.test.ts` — bg tests.
- `test/permission.test.ts` — auto (bash_stop mutating coverage).
- `test/commands.test.ts` — `/bash` parse + list/stop.

## Verification

- `bun test` (665+ tests, new ones included: `sleep 30` background returns
  immediately; status shows running then finished after `exit 0`; stop kills;
  journal + reap on shutdown; `/bash list/stop` parse).
- `bun run typecheck`.
- `bun run build` (must pass `--production`; `dist/shiro --version`).
- Manual: `SHIRO_HOME=$(mktemp -d) bun run src/cli.tsx -p "run a dev server in
  the background and check it is up, then stop it" --yolo --json`.

## Risks / notes

- Old journal entries (from crashed sessions) are reaped on next boot: at
  startup, kill stale PIDs or ignore missing ones. Do not leak orphan dev
  servers across sessions.
- `bash_status` poll output is capped (context safety).
- Windows: background is best-effort (no process group / setsid semantics);
  foreground behavior unchanged.
- Background processes are not snapshot / undo targets; killing on shutdown
  is deliberate to avoid orphan servers the user cannot see.