Research: bash tool has no story for long-running / background processes

[samkeen]

Status: research / forward-looking. Not blocking today.

Context

Tilth's bash tool runs synchronously — a call blocks the inner loop until the process exits. Today's targets (small Python CLIs/libraries) don't need a process that outlives a single tool call, so this hasn't bitten. Real features eventually will: "start a dev server, hit an endpoint, assert the response," a file watcher, a queue worker, or a DB the tests need running.

The gap

• A synchronous bash call can't host a process that never exits (a server) without & + manual PID juggling inside one call — fragile.
• Each task is a fresh conversation but shares the same worktree and OS process space, so a backgrounded process started in one task/iteration can leak into the next. Nothing reaps it.
• Caps interact awkwardly: a backgrounded process burns wall-clock but no tokens, so the token cap can't catch it; the wall-clock cap and the empty_responses / no_case backstops have to remain the safety net.

Prior art / what does and doesn't transfer

• Pi explicitly rejects background-bash in favour of tmux — but that's so a human can join and co-debug, which doesn't apply to an unattended run (Pi-harness considerations doc, §0). The tmux mechanism doesn't transfer; the underlying need — manage a process whose lifetime exceeds one tool call — does.
• The autonomy-friendly shape is closer to Claude Code's "run in background → poll/tail output → terminate": bash starts a process, returns a handle immediately, and later iterations read its output or kill it.

Guidance (current thinking, not a spec)

• Keep synchronous bash the default; background is opt-in per call.
• Make the process registry harness-owned and session-scoped, not worker-owned — the worker can't guarantee cleanup across a fresh-conversation boundary.
• Guarantee teardown at task end, run end, cap hit, and tilth reset.
• Emit hook_run-style events on background start/stop/output (telemetry separate from agent-visible output, per the hook contract).
• Do not adopt tmux.

Source

Pi-harness considerations doc, background-bash gap (surfaced reviewing the Pi article — the article rejects background bash; Tilth's autonomy reframes the requirement).