Repository navigation
feat: add background_run to wake a chat when a command ends - #26455
Yangxinyee wants to merge 1 commit into
Conversation
Sensitive Change ReviewSensitive files changed:
How to clear this check:
Only the author's comment counts this way. A reviewer can instead |
Sensitive change review
|
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks. The tool reuses the workflow host-run substrate instead of adding a new registry, and none of the take-aways I checked has a reader that breaks outside the patch. Notes
[DESIGN-REVIEWED] 6c2bedb Description read[DESCRIPTION-READ] 99080cd920f39f4712ed327fc016a69ca12d0759255c6529d82ab73af8582ef3 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — 🔴 BLOCKPremise-level review of First-Principles-Verdict: BLOCK Retained output and the wake prompt are redacted by chaining two redaction passes by hand. What this change shipsInventory (10 items) — 9 justifiedIntent: an agent hands a long command to the gateway, ends its turn, and its chat is woken with the outcome, even across a restart. ADDITION.
BlockersSecond spelling of [FIRST-PRINCIPLES-REVIEWED] 6c2bedb Description read[DESCRIPTION-READ] fa6a5c6c76f6ac49230e3d0bf980463ca9b3cdfd8f45550b5b7a87f7af2d396a That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — 🔴 changes requested (blocking)GPT 6.1 found at least one blocking issue that must be resolved before merging This comment is updated in place on each push. BLOCKING -- src/kiro_crew/dashboard/handlers/workflows.py:1029 -- Background commands bypass prefixed operator deny patterns
[BLOCK-MERGE] 6c2bedb Adjudication (Opus 5.5) — is blocking on each finding proportionate?The adjudicable block is empty. For the one fenced finding, F1, my ruling is UPHOLD-FENCED. That ruling cannot unblock anything, and F1 keeps blocking the merge. F1: I checked the bypass against the code and it holds:
[ADJUDICATION] 6c2bedb total=0 uphold=0 downgrade=0 [ADJUDICATION-FENCED] 6c2bedb fenced=1 flagged=0 False positive or not applicable? A repository writer can comment: |
Security Scope Review -- ✅ PASSWhich legitimate operations does Verdict basis: adjudicated, zero confirmed regressions. Security scope review -- adjudicated candidates
No candidate flipped from allowed to refused. Scope-Verdict: PASS Reason: The diff doesn't touch any of the three shell deny tiers. It only makes three places stricter: the auto-approval predicate ( TIGHTENING: auto-approval predicate, plus the write-protected and read-only path lists -- the threat is a prompt-injected agent auto-approving ADJUDICATED: 18 candidates, 0 confirmed newly-refused PLATFORM COVERAGE: I wrote posix rows for:
I wrote windows rows for:
The diff assumes POSIX in one place: UNADJUDICATED:
[SCOPE-REVIEWED] a1fe31b |
acc7d33 to
115df84
Compare
Sensitive change review
|
115df84 to
21d0fad
Compare
Sensitive change review
|
|
Round on
The |
Sensitive change review
|
|
Rebased: main moved in docs/architecture/mcp.md, docs/feature-map/README.md, docs/system-specs/common/injected-messages.md, docs/system-specs/modules/security.md, src/kiro_crew/dashboard/chat_runner.py, src/kiro_crew/dashboard/chat_turn/queue_drain.py, src/kiro_crew/dashboard/server_runtime/mcp_routes.py, src/kiro_crew/dashboard/state_parts/dashboard_state.py, src/kiro_crew/data/mcp_tool_titles.json, src/kiro_crew/security_posture_sinks_delivery.py, test/test_dashboard_server_composition_contract_reach.py and test/test_json_object_body_guard.py since this head went green (0f1dd2b -> 7f11b5c); CI re-running. Against |
Sensitive change review
|
|
Rebased: main moved in docs/architecture/mcp.md, docs/feature-map/README.md, docs/system-specs/common/injected-messages.md, docs/system-specs/modules/security.md, docs/system-specs/modules/workflows.md, src/kiro_crew/agent_materialization/worker_agent.py, src/kiro_crew/agent_parts/spec_grants.py, src/kiro_crew/agent_sdk/agent_specs.py, src/kiro_crew/constants.py, src/kiro_crew/dashboard/chat_runner.py, src/kiro_crew/dashboard/chat_turn/queue_drain.py, src/kiro_crew/dashboard/chat_turn/steer_queue.py, src/kiro_crew/dashboard/chat_utils.py, src/kiro_crew/dashboard/chat_utils_injected_rows.py, src/kiro_crew/dashboard/handlers/workflows.py, src/kiro_crew/dashboard/server_runtime/mcp_routes.py, src/kiro_crew/dashboard/server_runtime/workflow_startup.py, src/kiro_crew/dashboard/state_parts/dashboard_state.py, src/kiro_crew/data/mcp_tool_titles.json, src/kiro_crew/docs/agent-spec-fields.md, src/kiro_crew/sandbox.py, src/kiro_crew/sandbox_leaves.py, src/kiro_crew/sandbox_precreate.py, src/kiro_crew/sandbox_tiers.py, src/kiro_crew/security/paths_lists.py, src/kiro_crew/security_posture_sinks_delivery.py, src/kiro_crew/workflows/registry.py, src/kiro_crew/workflows/service.py and 11 test files (the pinned-count, composition-contract, sandbox and worker-agent tests) since this head went green (7f11b5c -> 01fcf6d); CI re-running. Against
The AI review lanes on |
resolution: narrowed -- an undelivered outcome holds its chat's slot only while a delivery task is in flight; the record stays unsettled so the next boot still re-delivers |
Sensitive change review
|
resolution: narrowed -- background_run is refused in a Bot's worker session, whose effective spec is merged per session, instead of judging that merged spec |
Sensitive change review
|
Sensitive change review
|
Sensitive change review
|
Code change approver recommendation: A person should decideAutomated, not a person, and not a review: a maintainer still decides.
Why: the decider approves but is not confident enough to auto-approve (p_defect 0.2 > 0.12). Adds background_run: a gateway-owned shell command on the workflow host-run substrate that wakes the chat with its outcome and survives a restart. I checked the key boundaries and found no blocking defects. The tool sits on kirocrew-cron, which no shipped allowedTools auto-approves, so kiro-cli asks first. The route refuses non-internal callers, private chats and agents with any shell restriction or PreToolUse hook, then runs the same HookManager gate as execute_bash. The sandbox never drops below standard, and the working directory is pinned and refused if it sits inside a mask or seal; the new background folder is sealed read-only. Host runs register with completion_injection=False, so the generic completion hook never double-posts. delivery_pending is written only when set, and every path releases it, so eviction of existing runs is unchanged. Reconcile runs before admission and retries with admission closed, and shutdown leaves commands running for the next boot to re-adopt. The new kind drains as a gateway inject row. Tests are extensive and deterministic. The remaining risks are unverified behaviour under real systemd and launchd restarts, and CI jobs still pending. If this recommendation is wrong, reply here; the replies are how the approver is evaluated. |
resolution: narrowed -- background_run is never auto-approved by any grant, on every writer and the KAS projection; a covering grant is narrowed to the cron server's other declared verbs |
Sensitive change review
|
Code change approver recommendation: Request changesWhy: the decider found 1 problem and estimates an 82% chance that this change introduces a defect, at or above the 80% level where it asks for changes. The background_run feature is carefully built, but the rule that it must never be auto-approved shrinks a Problems found:
An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
Sensitive change review
|
Sensitive change review
|
Sensitive change review
|
resolution: narrowed -- background_run is refused by the shared gate-skip predicate every grant writer and projection consults, instead of by each writer |
Sensitive change review
|
Sensitive change review
|
Sensitive change review
|
|
Stale-PR cleanup check: held for a maintainer. The linked issue #12681 carries |
An agent waiting on CI, a build or a training run had only a blind sleep, an in-turn wait capped at 30 minutes, or a turn-per-interval loop. background_run starts the command in the gateway at the agent shell's sandbox tier, lets the turn end, and wakes the chat with the exit code and output tail through workflow completion injection. The command is a host run on the workflow substrate (driver "command"), so workflow_status and workflow_cancel read and stop it. Output goes to a file and a wrapper records the exit status, so a gateway restart re-adopts a live command by its pid start identity, settles one that exited meanwhile, and reports the rest interrupted. The tool lives on kirocrew-cron, which is granted tool by tool, so kiro-cli asks before it runs; the gateway then judges the command with the same shell gate as execute_bash. Closes #12681
Problem / Motivation
Goal: An agent runs
background_run(command), ends its turn, and the chat is woken with the exit code and output tail. The wake survives a gateway restart (an update or a crash restarts it), because the waits this replaces are the long ones: CI, builds and training runs that outlast a restart. The command itself survives whenever the gateway's exit does not take it along: it runs in its own session, so a gateway process that crashes or is stopped leaves it running, and on Linux a service whose spawn gets its own systemd scope (cgroup v2 delegation) keeps it across a service restart. On Linux without delegation the service manager stops it with the service, and it is reportedinterrupted. Under launchd on macOS this is not verified (see Manual verification).An agent that has to wait on CI, a build, a test suite or a model training run has three options today, and none of them lets it start the work, end its turn, and be woken when the work finishes:
waitholds the turn open for at most 1800 s, and then the agent checks for itself.monitor_startruns a full LLM turn on every interval.monitor_watchis limited to PR review readiness, one per session.So agents fall back to blind
sleep Nplus polling, which is the behavior #12681 reports.Why it matters
Blind sleeps are wrong in both directions: too short and the agent reads a half-finished run, too long and it idles after CI is already green. They also cannot tell a failure from a job that is still queued, and to the user they look like a hang. For multi-hour work such as training, the only existing option spends an LLM turn per interval. A primitive where the harness waits and the model does not makes waiting free, and the agent resumes the moment the outcome is known.
Not a goal
background_run_private_chat: their run is never saved, while the command's record and log would be on disk. The check reads the chat's live memory mode before any run is registered, since a registration at the run cap evicts the oldest finished run.workflow-<id>fallback slot.What changed (motivation → approach → change)
An agent can now hand a shell command to the gateway with
background_run, end its turn, and be woken in the same chat with the exit status and the last lines of output. The harness does the waiting, as in Claude Code's background tasks: the agent writes the condition as a command (gh pr checks <n> --watch --fail-fast,until grep -qE 'done|Error' train.log; do sleep 30; done).Approach. The command is a host run on the workflow substrate (
WorkflowService.begin_host_run, the API TaskRunner already uses), not a new registry. It reuses run ids, durable status,workflow_status/workflow_cancel, the Runs view, the finished-workflow card and the chat's own queue drain, so it adds one tool and no polling driver. The design and the alternatives set aside are in the comments on #12681.src/kiro_crew/mcp_cron.py,src/kiro_crew/mcp_cron_tool_list.py,src/kiro_crew/validation_parts/cron_schemas.py,src/kiro_crew/constants.py,src/kiro_crew/data/mcp_tool_titles.jsonbackground_run(command, cwd?, timeout_secs?, label?)onkirocrew-cron, so kiro-cli asks before it runs, as forexecute_bashandcron_addsrc/kiro_crew/dashboard/handlers/workflows.py,src/kiro_crew/dashboard/server_runtime/mcp_routes.py,src/kiro_crew/agent_sdk/agent_specs.pyPOST /api/workflows/background: dashboard chats only; refused (background_run_shell_restricted) for an agent whose shell is restricted in any way or whose spec cannot be read; otherwise the same shell gate as the agent's ownexecute_bash; Shared Crew admissionsrc/kiro_crew/background_commands.pysrc/kiro_crew/dashboard/workflow_inject.py,src/kiro_crew/dashboard/server_runtime/workflow_startup.py,src/kiro_crew/dashboard/chat_turn/queue_drain.py,src/kiro_crew/dashboard/chat_turn/steer_queue.py,src/kiro_crew/dashboard/chat_utils.py,src/kiro_crew/dashboard/chat_utils_injected_rows.py,src/kiro_crew/dashboard/chat_runner.py,src/kiro_crew/dashboard/state_parts/dashboard_state.pysrc/kiro_crew/workflows/registry.py,src/kiro_crew/workflows/service.pyRunHandle.delivery_pendingkeeps an undelivered run from eviction;fail/cancel_host_runtake an optionalresultsrc/kiro_crew/sandbox_leaves.py,src/kiro_crew/sandbox_precreate.py,src/kiro_crew/sandbox.py,src/kiro_crew/sandbox_tiers.py,src/kiro_crew/security/paths_lists.py,src/kiro_crew/security_posture_sinks_delivery.pybackgrounddata-home leaf is read-only to every sandboxed process; a cwd under a masked or sealed path is refused (path_within_tier_mask)src/kiro_crew/shared_crew/containment.pyis_principal_slice, so a stop kills a command's whole systemd scope only inside this instance's slicessrc/kiro_crew/agent_parts/spec_grants.py,src/kiro_crew/agent_materialization/worker_agent.py,src/kiro_crew/docs/agent-spec-fields.md,docs/system-specs/modules/workflows.md,docs/architecture/mcp.mdbackground_run(_WORKER_EXCLUDED_GRANTS); the spec gains a "Background commands" sectionWhat holds, in one line each (the full mechanism list is
docs/system-specs/modules/workflows.md§ Background commands):head -c, never a pipe, and a watchdog in the wrapper keeps the deadline with no gateway watching.permissionsshell deny or ask,deniedCommands,denyByDefault, a tool list without the shell, or a PreToolUse hook that can match it refusesbackground_runon every harness); then the same gate, the same sandbox tier (never belowstandard), the calling harness's credential mask, and a cwd that is never inside a mask or seal.exited,timed_out,output_limit,stoppedorinterrupted.Backwards compatibility
Compatible. Every signature change adds an optional keyword with the old behavior as its default (
result=Noneonfailandcancel_host_run), andRunHandle.delivery_pendingdefaults to False and is absent from records that never set it, so eviction of every existing run is unchanged. The tool, the route and the data-home directory are new, and nothing main accepts is rejected or renamed.Two take-aways, both on surfaces this PR adds;
git grep origin/mainfinds no other reader of<data home>/backgroundand no other caller of the new spawn:Reader: src/kiro_crew/background_commands.py:BackgroundCommandService._spawn -- chat -- the
extra_hidden_dirsmask is the calling chat's own harness mask (empty for kiro), so a command sees no more than that chat's shell; test_the_command_runs_under_its_chats_harness_credential_maskReader: src/kiro_crew/background_commands.py:_wrapper -- chat -- the wrapper's record handshake reads
background/, which the enforced masks leave readable and the sealed leaf keeps read-only; test_an_enforced_harness_mask_hides_the_secrets_but_not_the_command_recordsTests
test/test_background_commands.py(spawn, settle, stop, re-adoption) andtest/test_background_run_chat.py(the card, the wake, the MCP tool and the route), 88 tests, split to stay under the 2,000-line file cap. The sandbox chokepoint is replaced by an identity wrapper (through_floor_monkeypatch, D11) so the tests pin the lifecycle rather than the host's sandbox backend; the processes are real/bin/shprocess groups. No test waits on a fixed sleep or asserts a wall-clock bound: they wait on a marker file or the supervisor's own poll count, set exit-status mtimes and inject the service clock, and the regex-linearity check runs in a child under a lost-run bound.workflow_cancelstops the command and cancels the run; output past the cap stops the command; a fast exit past the cap fails the run and the log is cut to the cap; a cancel during settlement still settles the run; the watchdog stops a command no gateway watches; a command that ended unwatched past its deadline is a timeout; a re-adopted command past its deadline is stopped at once; only a scope in this instance's slice is ever killed; settling kills everything left in the command's scope; withoutcgroup.kill, the scope unit is stopped.injectrow the gateway is credited for, never the person's row; a wake is acknowledged only once the runner reports it consumed, not while queued or once its row is written, and an end-of-turn report only once its turn has ended; a wake that never runs is given up after its wait with the card delivered and the wake left queued; a wake a signed-out CLI refused is queued again and acknowledged after sign-in; a wake its user removed or Stopped is not queued again; an unsaved or declined wake is not acknowledged.runningright afterreconcile, then settles with the real exit code); a command that finished during the restart settles from its exit status; a command lost without an exit status is reportedinterruptedand delivered; a result the run store did not save is reported again after a restart; a command whose run cannot be saved is never started; an Incognito or Temporary chat never starts one; reconciling before admission keeps a restored command's run from eviction; a supervised command, a re-adopted one included, is in the sweeps' protected set until it settles; a live command with no run to report to is stopped on boot.allowedToolsentry (whole-server, glob or per-tool, in the built default or any packaged agent spec) covers it.HookManagerrefusesrm -rf /and a--data-binary @exfiltration and passespytest -q; an agent whose shell is restricted in any way (19 shapes, on the KAS, kiro-cli, claude and codex backends), whose spec cannot be read, or that cannot be named is refused withbackground_run_shell_restrictedbefore anything starts, and the bundled default agent is admitted on every backend;cwddefaults to the project and refuses non-directories, and a cwd inside a tier or harness mask is refused before any run; non-internal callers get 403; the success path starts the command for the caller's own chat with the harness read from that chat's live session (else the configured one through the crewmate pincrewmate_backend_pin, whose unstartable pin is refused with 409); a denied command gets 403 and a session with no chat gets 409, and neither starts anything..local_secretbut leavesbackground/readable for the wrapper's handshake; the record keeps no session key, and re-adoption restores the owner; an outcome published but never delivered (the gateway stopped, or the chat refused every attempt) is delivered on the next boot with the same card, and an acknowledged one is not delivered again; a refused delivery is asked again in the same gateway and given up only past retention; a run whose outcome is undelivered is never evicted (the hold is saved with it) and is evictable once delivered; a held run no record will deliver is released on boot; an outcome whose run is gone is not marked delivered; a command outcome counts as delivered only once its wake has run and is saved (not while it only sits queued behind a busy turn), an idle chat holding an unrun wake after a restart has that entry run, neither the card nor the wake is posted twice, and a wake its user removed is not queued again; a boot-time delivery waits for the open tabs but not forever; the tail never carries a private key's body, whether the line cut or the read window drops its header; the log stays bounded while no gateway watches; a group whose leader nobody watched is never signalled; a record from another boot is never alive; a job left by a command that ended unwatched is not signalled; a start cancelled during the spawn leaves no run; one record that fails to re-adopt does not stop the rest; records that cannot be listed keep admission closed; the working directory is pinned and re-checked by descriptor; concurrent starts cannot pass one cap check together; the record keeps no cleanup path and pins its files by identity; a replaced or symlinked log is never read; settling prunes settled folders past retention; command output containing fences cannot close the completion message's fence, and a multi-line label cannot forge a card header.test_hooks.py::TestHookGateKwargs(the route splatshook_gate_kwargs),test_security_posture.py(the sink is registered),test_spawn_audit.py(the new spawn site is routed and limited),test_sandbox_governance_mask.py(backgroundis sealed in every mode and edit-refused by the file gate),test_json_object_body_guard.py(the route's body cap is registered),test_sandbox_protected_name_holds.py(thebackgroundroot leaf is three more leaf-only names per tier, recorded with its reason like the other data-home root leaves),test_dashboard_server_composition_contract.py(the MCP route table gains the background route, re-measured on currentmain(301 rows; lazy imports 90), the lazy-import table gains the in-function imports, and the workflow-service hooks test stubs the background service and checks the command wake prompt (with its run id) through the service'sdeliver), andtest_transcript_derivation_seam.py(the delivery's yes/no transcript read is named as plumbing),test_slot_running_readers.py(the queued-wake wait and its dispatch read the reservation, like the parked-queue drain), anddata/mcp_tool_titles.json(background_rungets its display title).test_sandbox_refactor_facade.pylists the two newsandbox_tiersnames (_tier_mask_dirs,path_within_tier_mask), which thesandboxfacade forwards and itsTYPE_CHECKINGblock names.test_security_gate_liveness.pyraises the package budget by the onebackgroundwrite-protect line, with its reason.Locally, on
8e85d1cb04(rebased onto currentmain): the 450 test files matchingbackground,workflow,mcp_cron,cron_folder,queue,drain,auth_req,sandbox,security_gate,slot_running,transcript_deriv,composition,injected,containment,facadeand the pin tests: 18,017 passed. The 2 failures were facade-boundary gates the rebase tripped (test_mcp_cron_facade.py,test_chat_runner_composition_contract.py); they are fixed, and the 1,396 runner, facade and PR tests pass on a rerun, as do the pin tests after the latest rebase. Each new delivery test fails with its fix reverted. Also passing:mypy --platform linux src/kiro_crew, flake8, isort, black on the touched files, the line cap, sync-io, subprocess-encoding, comment-history, harness parity and docs lint.One host note, not caused by this diff:
/bin/ps, soprocess_start_timereadsNonethere; the local run read the start identity throughget_process_start_idwith a test-only plugin. CI runs the realps.I did not run the full
run_scoped_tests.py --surface backendset locally (2,134 targets); CI runs it.Manual verification
Earlier round: ran
BackgroundCommandServiceagainst the real sandbox path (sandbox-exec, macOS, isolatedKIROCREW_HOME):echo hello; exit 0→ finished 0,exit 5→ failed 5,gh --version→ finished 0 (ghworks at the standard tier). With the sealed folder, a command writing another run'sexit_statusor planting a file inbackground/getsOperation not permitted, while its own exit status and output are still recorded correctly. With the watchdog (timeout 1s, margin 0, gateway stopped), the whole group was gone about 6s later and the status readtimeout.Ran
test/test_background_commands.pywith the wrapper pointed at/bin/dashas well as/bin/sh, several times each under-n 6: all pass. The earlier Linux-only failures came from dash rejecting a two-digit fd in>&12.Not verified:
--userservice restart on Linux;sandbox-exec/namespace backend: this host's own shell runs inside a sandbox, sosandbox-execcannot nest (sandbox_apply: Operation not permitted); both are covered by unit tests and the wrapper probe above.The restart logic is covered by the unit tests above, but not against real service managers.
Related Issues
Closes #12681.
Supersedes #13180: the same change, moved from a fork branch to this repository so
Sensitive Change Reviewcan be cleared. Its review history stays on #13180.Refs #12693: a running command keeps
has_pending_work_fortrue, which gives a completion contract a deterministic "work in flight" signal. Refs #12876: command runs appear in the Runs view; the inline task chip is not in this PR.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
N/A — the CLA text is still a template placeholder. I agree to license this contribution under the repository's license (Apache-2.0).