Skip to content

Add background mode for shell commands so long runs don't hold steers - #836

Merged
TheGreatAxios merged 1 commit into
mainfrom
cl-7517-background-mode-for-shell-commands-so-long-runs-dont-hold
Sep 10, 2026
Merged

Add background mode for shell commands so long runs don't hold steers#836
TheGreatAxios merged 1 commit into
mainfrom
cl-7517-background-mode-for-shell-commands-so-long-runs-dont-hold

Conversation

@TheGreatAxios

Copy link
Copy Markdown
Collaborator

Summary

  • run_shell accepts background: true: shell-guard starts the command in a detached process group via a bounded registry (8 running, 8 completed ring) and returns {shell_id, status: "running"} immediately, so the turn ends and queued steers land while builds, test suites, and dev servers run
  • On process exit the result (exit status, timed-out marker, ~2KB output preview, tool-output:/// spill URI when truncated) is delivered to the orchestrator on a later turn via the existing continuation channel, wired in all three loop hosts (TUI, exec, sub-agent); the message is system-originated and never counts as operator input
  • New shell_collect tool ({shell_id, action: "collect"|"cancel", wait_ms?}) retrieves status/output or kills the process group; timeout kills the group with exit 124 + timed_out; background runs never mutate the retained shell cwd; the permission chain still evaluates the start call, so a denied command spawns nothing; unwired sessions fail closed; foreground behavior is unchanged when background is unset
  • Tool watchdog exempts background starts and shell_collect; toolset dispose kills every live background process group before the posix teardown (/clear, interrupt, reload)
  • Prompts, docs/ARCHITECTURE.md, and docs/IMPLEMENTATION.md updated

Verification

  • bun run check passes (lint, typecheck, build, full test suite under the projects-dir guard: 6302 pass, 0 fail)
  • New tests pin: immediate handle return, later-turn exit delivery (system-originated message shape), cancel and timeout process-group kills, ring eviction, registry/toolset dispose teardown, permission deny spawns nothing, foreground unchanged, background cd not retained

Fixes CL-7517

@linear-code

linear-code Bot commented Sep 8, 2026

Copy link
Copy Markdown

CL-7517

run_shell accepts background:true: shell-guard starts the command in a
detached process group via a bounded registry and returns a shell_id at
once, so the turn ends, tool.boundary fires, and queued steers land
while the process runs. On exit the host delivers the exit status and
output preview on a later turn through the existing continuation
channel (TUI, exec, and sub-agent loops); truncated output spills to a
tool-output URI. A new shell_collect tool collects or cancels by id.
Timeout kills the group with exit 124 and a timed-out marker; a
background run never mutates the retained shell cwd; unwired sessions
fail closed; foreground behavior is unchanged when background is
unset.
@TheGreatAxios
TheGreatAxios force-pushed the cl-7517-background-mode-for-shell-commands-so-long-runs-dont-hold branch from f2a94f5 to c356bda Compare September 10, 2026 01:11
@TheGreatAxios
TheGreatAxios merged commit df7bc49 into main Sep 10, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant