doom-runner

# doom-runner `bash` supervises what it starts. A command that outlives the background threshold keeps running instead of blocking the turn. Use the `doom-runner` CLI to manage it without adding another model tool. ## Backgrounding - A command still running after 60 seconds (`DOOM_RUNNER_BG_THRESHOLD_MS`) is moved to the background automatically. You get its unique ID and streaming log path. - Pass `background: true` for commands you already know will not finish: dev servers, watchers, `tail -f`. Waiting out the threshold first wastes a turn. - Pass `interactive: true` when the command will prompt for confirmation or input. It runs under a terminal and backgrounds immediately. Answer it with `doom-runner input <id> --text <text> --enter`, or use Runner Space. - Pass `timeout` (seconds) when you want a command killed rather than supervised. A timeout above the threshold has no effect: the command is promoted first. - Pass `name` to choose the runner name. A name already in use gets a numbered suffix. ## CLI Run the CLI directly, without starting it through another supervised runner. It inherits `PI_SESSION_ID` from the active Pi session and only accesses that session's runners. A manual shell without `PI_SESSION_ID` fails closed. Use the unique runner ID returned by `bash`: | Command | Purpose | | -------------------------------------------------- | ---------------------------------------------- | | `doom-runner list [--all]` | List active runners, or include completed ones | | `doom-runner status <id>` | Show command, state, backend, and log path | | `doom-runner logs <id> [--lines N] [--follow]` | Read or stream the saved log | | `doom-runner stop <id> [--reason <text>]` | Stop one runner and keep its log | | `doom-runner stop-all [--reason <text>]` | Stop active runners owned by this Pi session | | `doom-runner input <id> [--text <text>] [--enter]` | Send input to an interactive RMUX runner | ## Rules - **Read the log, do not re-run the command.** When output is truncated, the full text is already on disk. Use `doom-runner logs <id>` or standard file search tools against the reported path. - **Read the truncation notice before reading the file.** It states the real file size and line count, so you do not read past the end. - **CLI access is session-scoped.** `list`, direct ID commands, and `stop-all` only access runners owned by the inherited Pi session. - **`input` needs `interactive: true`.** A normal runner does not expose stdin. - **Stop what you no longer need.** Everything still running is stopped when the session ends, but a forgotten dev server holds a port until then. - **You are told when a runner exits.** A completion message with the exit status and log path arrives on its own. Never sleep, poll, or pgrep to wait for one. Check a runner when you have a reason to, not on a loop. - **Do not pipe to head or tail.** Results are already bounded and the full log is on disk. A tail pipe also leaves the live log empty until the command exits, which blanks the log pane in Runner Space. ## Where things live Run metadata and logs sit under `$PI_CODING_AGENT_DIR/doom-runner/<session-id>/{runs,logs}`. Without an override, `$PI_CODING_AGENT_DIR` defaults to `~/.pi/agent`. Completed metadata and complete raw logs remain readable for seven days. RMUX is bundled for supported macOS and Linux platforms. Non-interactive runs fall back to a supervised subprocess when RMUX is unavailable; interactive runs require RMUX. Eligible simple commands use a command-specific RTK stdin filter after completion. Compound shell commands and unsupported formats keep bounded raw output. `SPC r l` opens Runner Space. Escape returns from logs or an attached terminal.