Skip to content

feat(cli): kirocrew chat --headless for unattended runs - #37768

Merged
bolichen97 merged 1 commit into
mainfrom
feat/chat-headless
Nov 16, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/chat-headless

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let one Crew task run unattended from the command line, in chat or conductor mode, and end with a result code and a JSON summary, so evals can drive Crew the way they drive Claude Code and Codex through their CLIs.

kirocrew chat -m answers one turn in-process, waits on the terminal for y / n / o at every tool prompt, and prints no structured result. It cannot run conductor mode, cannot outlast the first turn through the ledger patrol and worker wakes, and cannot say whether the run asked a person. That is the first missing piece of docs/request-for-change/rfc-builtin-eval.md §12 (merged in #37669).

Why it matters

The built-in eval compares Crew chat, Crew conductor mode, kiro-cli V3, Claude Code and Codex, where any ask of a person fails the run. Claude Code (claude -p) and Codex (codex exec) have headless CLIs; without one, Crew can only be driven through private gateway calls in an out-of-tree bench, which is not a like-for-like comparison and nobody else can rerun.

Not a goal

  • The eval runner, case suites and harvest (later PRs per the RFC's phases).
  • Starting a gateway from the CLI; it attaches to the running gateway of the current data home (no gateway is exit 8).
  • --on-ask continue, --effort and --resume (listed as later in §12.2).
  • Any change to a gateway route, caller rule or approval policy.

What changed (motivation → approach → change)

  • Goal → extend kirocrew chat with --headless rather than add a command: kirocrew run is already the TASK.md runner, and chat already owns agent resolution.
  • Approach: drive the running gateway as its owner (a one-minute owner token over the peer-verified local transport, the kirocrew token path), open one chat slot, optionally set Trust on that slot (POST /api/chat/mode, audited by the existing handler), send the seed and poll. Owner reads used: /api/chat/slots?crew=all, /api/chat/slots/{slot}, /api/ask-question/pending, /api/agents/catalog, /api/crew-board?conductor=, /api/autonudge/slot/{slot}.
  • One gateway change, by the repository owner's decision of 2026-11-16 (relayed by the conductor in this PR's thread): a conductor waits at its plan gate in any turn a person typed, and an owner /api/chat send is such a turn, so the conductor arm could never run unattended. POST /api/chat with "unattended": true and a run_id, from the dashboard owner only, now opens the turn with the gateway's own honest marker [headless run cli:<run_id>] and writes a chat_headless_run SEL row; the goal-conductor skill lists [headless run with its other nobody-typed openers. Every caller's typed copy of the marker is defanged to [quoted: headless run (the rule a forged [sent by session already gets). Non-owner callers get 403, a bad run_id 400, and an unattended seed that opens with / or @ 400 unattended_command_seed (the marker opens the turn, so a command or saved prompt would not run; the CLI refuses it first, exit 2). No other route, caller rule or approval policy changes.
  • Change:
    • src/kiro_crew/cli_chat_headless.py (new): options, conductor agent resolution, gateway client, the run loop, the --json result and exit codes.
    • src/kiro_crew/dashboard/headless_marker.py (new) and its hook in chat_api/chat_send.py; [headless run in builtin_skills/goal-conductor/SKILL.md "Skip the gate".
    • --mode conductor: the agent is the gateway's crew_mode_agent (catalog), so a fallback the gateway applied (set_unusable) is honoured; --agent is refused with it; --json records the agent and its source.
    • --approval-mode trust (the one choice): Trust on the chat this run opens; workers inherit it at session_create.
    • Asks: a pending approval or needs-input on any chat of the run (root, ledger workers, chats it created with gateway-minted lineage), an ask_question card for one of them, a ledger item the board reads as awaiting the person, or an idle root turn whose [OPTIONS:] parses to choices. The run stops at the first one (exit 3).
    • Every exit after the chat exists, a clean done included, deletes the run's automation loops and stops its turns (a declined stop is pressed again with force), root first, cancels each chat's background agents (POST /api/spawn/stop-all), then re-reads the slot list and stops any chat created since the last poll, then closes the chats; a chat the gateway refuses to close is named in the result's unclosed. Running or queued background subagents keep the run busy. Trust is left on the stopped chats: the owner route's normal would also end a process-wide YOLO.
    • --until-done, --idle-grace, --cwd, --timeout (exit 4), --budget in credits (exit 5; spend includes workers closed between polls, found from their transcripts' created_by, and finished background agents the run's chats started, read from GET /api/spawn; a turn or agent counts when it ends), --message-file, --json. An error or gateway system refusal row ends as error (sign-in exit 6, sandbox exit 7). No gateway is exit 8, a conductor that goes quiet with items still open is exit 9 (incomplete), interrupt 130. --cwd sets the run's chat project (POST /api/chat/slots/{slot}/project), so no folder is left behind. A background agent that finished in the last 60 s (the gateway's report wait) keeps the run open, so its result reaches the parent before the chat is closed. While work_ledger.remote_dispatch is on, a run exits 1 before opening a chat: a remote crew's worker could not be stopped by the CLI.
    • cli_parser_agent.py flags, cli.py dispatch (a headless-only flag without --headless exits 2), docs/system-specs/modules/cli.md.
    • docs/request-for-change/rfc-builtin-eval.md: status accepted (owner decision); §5 and §12 describe what ships, including the marker and its boundary.

Backwards compatibility

Compatible: kirocrew chat without --headless is unchanged; every new flag is optional and refused without --headless; POST /api/chat without unattended behaves as before except that a typed [headless run opener is rewritten to [quoted: headless run.

Reader: src/kiro_crew/dashboard/chat_api/chat_send.py:_api_chat_send -- chat -- a typed [headless run… opener in any send is rewritten before dispatch; no existing caller sends that text (test/test_headless_marker.py::test_a_typed_marker_is_defanged_for_every_caller, test/test_e2e_smoke.py::test_a_typed_headless_marker_is_defanged)

Tests

  • test/test_cli_chat_headless.py: every flag and bad flag set; conductor agent from the gateway (default, config, fallback); the run loop for done, trust only on its own slot, --cwd, conductor slot checks, --until-done waiting for items and surviving a wake, busy and asking workers (only listed with crew=all), chat-created children, ledger asks, options parsing, question cards, timeout, budget (incl. workers closed between polls), error and refusal rows, sign-in failures, interrupts and failed polls stopping the run's chats, automation disarm and forced stop on every exit, children made after the last poll, queued subagents, a non-UTF-8 or sensitive-path --message-file, the empty-turn notice as an error, spend counted again after the chats close; the gateway client; the board read; main exit codes and --json.
  • test/test_headless_marker.py: owner gets the marker and an audit row; no flag, no marker; typed copies defanged (fullwidth, zero-width, case); app, internal and non-owner refused; bad run ids; command seeds refused; the skill lists the marker as nobody-typed.
  • test/test_e2e_smoke.py: a real gateway with the fake ACP backend: --mode conductor --approval-mode trust --until-done --json opens a trusted Crew Mode chat, the seed row opens with [headless run cli:, the run keeps polling while a ledger item is open and exits 0 once it is accepted; a person's typed copy of the marker reads [quoted: headless run.

Proof: not provable -- other: new feature, no fix to revert; the new tests fail on main because the module and flags do not exist

Manual verification

Ran locally under the shared test lock: the new suites, the conductor-skill and work-ledger suites, the chat CLI suites and both headless e2e tests; flake ratchet, subprocess-encoding gate, comment-history gate, scripts/docs_lint.py, mypy. The plan-gate skip itself is model behaviour on the skill text: pinned by the skill-text test and the marker e2e, not by a signed-in model run.

Related Issues

Implements the first part of §12 of docs/request-for-change/rfc-builtin-eval.md (#37669).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 16, 2026 02:51
@iamwhatever
iamwhatever requested a review from buluoray November 16, 2026 02:51
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision bf049b3a0a037bf846c46d942f07c556e6a1c97a touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of bf049b3a0a037bf846c46d942f07c556e6a1c97a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The gateway marker is owner-only and audited, and every caller's typed copy is defanged. Skipping the plan gate gives no more than a person typing "just do it" already gets.

Notes

  • The defang runs only on POST /api/chat. Channel and queued inputs can still carry a typed [headless run opener. That only skips the plan gate, which the sender could already skip by saying "go ahead", so it is no escalation. It does make the marker's "only the gateway writes it" claim weaker than the one for [sent by session.
  • An unattended seed that opens with / or @ is refused (unattended_command_seed), so eval cases cannot drive saved prompts. If evals need them later, move the marker after command parsing rather than adding exceptions to this check.

[DESIGN-REVIEWED] bf049b3

Description read

[DESCRIPTION-READ] 50afbbba9726e93440277ec54dd343bf95905cbf5245908c86e9cd61703be2d4

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of bf049b3a0a037bf846c46d942f07c556e6a1c97a — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

This adds a new headless path next to unchanged kirocrew chat. The conductor's plan-gate skip is already covered by rfc-reroute-first-ask-policy (implemented), so no item changes a default without a recorded decision.

Notes

  • Item 9 — inherited: the diff changes status: draft → status: accepted in rfc-builtin-eval.md, citing a decision "relayed by the conductor in this PR's thread". The base list reads draft, so this PR is proposing that decision, not recording it. Subtraction: take the status, Status-line and README-row edits out of this PR and leave the RFC's acceptance to its own record.

What this change ships

Inventory (9 items) — 8 justified

Intent: let an eval run one Crew task (chat or conductor mode) with nobody at the terminal and get back an exit code and a JSON summary. ADDITION.

  1. kirocrew chat --headless drives the running gateway as the owner and stops at the first ask (exit 3) — justified
  2. --mode conductor uses the agent the gateway resolves; --agent is refused with it — justified
  3. --approval-mode trust turns on Trust for the run's own chat only — justified
  4. --until-done, --idle-grace, --timeout, --budget, --cwd, --message-file, --json, and exit codes 0–9 and 130 — justified
  5. On every exit, the run stops its automation, turns and background agents, then closes its chats — justified
  6. An owner's POST /api/chat with unattended: true gets the gateway's [headless run cli:<id>] marker and an audit row; other callers get 403 — justified
  7. A typed [headless run opener is rewritten to [quoted: headless run for every caller — justified
  8. The goal-conductor skill counts [headless run as a turn nobody typed, so the plan gate is skipped — justified
  9. The RFC is flipped from draft to accepted inside this PR — undeclared

[FIRST-PRINCIPLES-REVIEWED] bf049b3

Description read

[DESCRIPTION-READ] 3d8ddfbe02ecf0b0d0ea80e72ade77d060d9d970bef1bc1cf8bafa546de51e86

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed bf049b3a0a037bf846c46d942f07c556e6a1c97a — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] bf049b3

Verdict parsed from the review's SHA-scoped output markers for commit bf049b3a0a037bf846c46d942f07c556e6a1c97a.

False positive or not applicable? A repository writer can comment:
/ai-review override fable bf049b3a0a037bf846c46d942f07c556e6a1c97a false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of bf049b3a0a037bf846c46d942f07c556e6a1c97a and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] bf049b3

False positive or not applicable? A repository writer can comment:
/ai-review override gpt bf049b3a0a037bf846c46d942f07c556e6a1c97a false-positive: <reason, 20 to 500 characters>

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Findings on 58dc554, all addressed in 4fa44eb (one amended commit):

  • First Principles blocker (second ledger reader): ledger_items now calls work_ledger_store.list_work_items; item_counts / worker_slots read WorkItem.is_terminal / .worker_session_key. Test: test_ledger_items_uses_the_store_reader.
  • FP note 9 (reply-text matching): sign-in / sandbox are now read only from an error row, never from agent text. Test: test_not_signed_in_only_from_an_error_row.
  • FP note 7 (--approval-mode trust): kept as the RFC spelling the owner chose, so later modes slot in without a new flag.
  • Workers hidden from the poll (Opus, GPT F1): the poll reads /api/chat/slots?crew=all. Tests: test_a_busy_worker_keeps_the_run_alive, test_a_worker_approval_is_an_ask.
  • Gateway-side fallback (GPT F2): the conductor name is read from GET /api/agents/catalog crew_mode_agent, so set_unusable in the gateway is honoured. Test: test_conductor_mode_takes_the_gateway_fallback.
  • Error rows read as done (GPT F3): an error row ends the run with status error (exit 1), or the sign-in / sandbox codes. Test: test_an_error_row_is_a_failure_not_done.
  • Ctrl-C leaves chats running (GPT F4): run() catches the interrupt, stops every chat of the run and returns interrupted with the slot. Test: test_interrupt_stops_the_run_chats.
  • Fixed sleep in the e2e (Opus, GPT F5, Semgrep): removed. The CLI prints one stderr line per poll; the test waits for a poll that saw the root idle with one item open, then asserts the process is alive.
  • Child cwd (GPT F6): both subprocesses run with cwd=tmp_path.
  • Notes: approval text from pending_approval_info.tool, card text from questions[0].question; the stale comment above _OPTIONS_MARK is fixed.
  • Lint / Flake ratchet: isort fixed; duration literals moved off call keywords (ratchet passes locally against the merge base).

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Findings on 4fa44eb, addressed in ecb34d6 (one amended commit), each with a test in test/test_cli_chat_headless.py:

  • Opus: a failed poll left trusted chats running -> from slot create on, every exit (error, lost gateway, Ctrl-C) stops the run's chats; main has a last-resort handler so --json always prints. Tests: test_a_failed_poll_stops_the_run_chats (3 cases), test_main_prints_text_and_maps_run_errors.
  • Opus: a refused sign-in read as exit 8 -> HTTP errors from /api/token/local raise error (exit 1) with the code. Test: test_client_errors.
  • Opus note: docs/system-specs/modules/cli.md now lists --headless, its flags and exit codes.
  • GPT F1: _stop now deletes the chat's automation loop (GET /api/autonudge/slot/{key} -> DELETE /api/autonudge/{id}) and presses stop again with ?force=true when the first stop is declined for compaction. Test: test_stop_disarms_automation_and_forces_a_declined_stop.
  • GPT F2: the seed send is inside the cleanup scope. Test: test_interrupt_during_the_seed_still_stops.
  • GPT F3: chats created by the run's chats (gateway-minted created_by lineage only) are part of the run in both modes. Tests: test_a_chat_created_child_is_part_of_the_run, test_unminted_lineage_is_not_trusted.
  • GPT F4: an open ledger item with a recorded ask counts as an ask. Test: test_a_ledger_ask_is_an_ask.
  • GPT F5: options use the dashboard's own _parse_options; a mention with no choices is not an ask. Test: test_a_literal_options_mention_is_not_an_ask.
  • GPT F6: the sandbox producer's text maps to exit 7. Test: test_sandbox_producer_text_maps_to_exit_7.
  • CI: Windows path assert fixed; e2e Popen pins encoding="utf-8"; the ledger read goes through the kiro_crew.work_ledger facade; the CLI dispatch imports names from kiro_crew.cli_chat_headless (test_cli_lazy_imports).

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Round 3 on ecb34d6, addressed in 1ac5c00:

  • Opus / GPT F1 (normal completion skipped cleanup): every exit after the chat exists now goes through _stop, a clean done included: the chat's automation loop is deleted, the turn stopped, and Trust the run granted is set back to normal. Tests: test_a_clean_done_disarms_automation_too, test_approval_mode_trust_sets_trust_on_own_slot_only.
  • GPT F2 (refused seed read as done): a system row the gateway writes when it refuses a turn (blocked @prompt) ends the run as error. Test: test_a_refused_seed_is_not_done.
  • Backend shards (test_work_ledger, test_state_parts_facade): the CLI no longer imports the work-ledger store or a state_parts owner. Ledger items come from the owner board read GET /api/crew-board?conductor=KEY (awaits_person is the ledger ask), and _parse_options comes through kiro_crew.dashboard.state. The e2e drives the board read end to end.
  • First Principles note (RFC status in this PR): the repository owner chose to record acceptance in this PR (decision of 2026-11-16, relayed by the conductor); the Status line says only §12's first part ships. Left as is.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Opus finding on 1ac5c00 (conductor seed hits the plan gate), addressed in 7e6c242 per the repository owner's decision of 2026-11-16 (relayed by the conductor): no forged [sent by session; the gateway writes its own honest marker.

  • POST /api/chat with "unattended": true and a run_id, from the dashboard owner only, opens the turn with [headless run cli:<run_id>] and writes a chat_headless_run SEL row (run id, slot). An app, internal or non-owner caller gets 403 unattended_not_owner; a bad run_id gets 400 invalid_run_id (src/kiro_crew/dashboard/chat_api/headless_marker.py).
  • Every caller's own text has a marker-shaped opener defanged to [quoted: headless run (normalize-then-match, the rule a forged [sent by session gets), so typing the prefix skips nothing.
  • The goal-conductor skill lists [headless run with the other nobody-typed openers in "Skip the gate"; a person's ordinary turn is unchanged.
  • The CLI sends the flag and a per-run run_id (in --json).
  • Tests: test/test_headless_marker.py (owner gets the marker + audit row; no flag, no marker; typed copies defanged incl. fullwidth / zero-width / case; app, internal, non-owner refused; bad run ids; the skill lists the marker as nobody-typed). e2e: the conductor seed row opens with [headless run cli:; a person's typed copy reads [quoted: headless run. The plan-gate skip itself is model behaviour on the skill text, so it is pinned by the skill-text test rather than a live model run.
  • RFC §5 and §12.3 describe the marker and its boundary; cli.md updated.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Round on 7e6c242, addressed in fcbb555:

  • Opus (Trust reset ends a process-wide YOLO): _stop no longer sends normal. The run's chats are stopped and their automation deleted, so their Trust starts no turn; a global override is left alone. Test: test_approval_mode_trust_sets_trust_on_own_slot_only pins that only trust is sent.
  • GPT F1 (worker closed between polls escapes the budget): spend now also counts every chat whose transcript (written since the run began) names one of the run's chats as created_by, transitively. A forged claim can only add spend, so it stops a run sooner, never later. Test: test_spend_counts_a_worker_closed_between_polls.
  • Source Gates (comment history): "round 1" in the marker module docstring reworded.
  • First Principles (description vs diff): "What changed", "Backwards compatibility" and "Tests" now describe the one gateway change (the [headless run marker, owner-only, audited, typed copies defanged) and the skill entry, with a Reader line. The frozen "Not a goal" bullet "Any change to a gateway route, caller rule or approval policy" predates the repository owner's decision to add the marker; amending a frozen section is left to a human.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Round on fcbb555, addressed in 1ade30f (rebased on main):

  • GPT F1 (child option lists): an idle run chat other than the root whose gateway row has has_options is an ask, recorded with its slot and choices. Test: test_a_child_chat_option_list_is_an_ask.
  • GPT F2 (advisory-only turns): a notice row that is_harness_advisory_row matches reads as the turn's answer; other notices do not. Test: test_a_harness_advisory_row_is_the_turn_answer.
  • Backend Ratchets (file line cap): chat_send.py stays at 2,000 lines: the hook is one call plus one import, and two nearby comments were tightened with no change in meaning.
  • Backend Tests (test_chat_handlers_composition_contract): the marker module moved out of the chat_api owner package to src/kiro_crew/dashboard/headless_marker.py; chat_send imports it in-function.
  • Real Adapter Contract Tests (crew_tool_bytes_ceiling for codex): not touched by this diff (no tool spec changes); the same lane passed on main run 43814579403, so it is read as base drift and re-checked after the rebase.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Real Adapter Contract Tests, evidence:

  • On fcbb555 (base cfaffc7) test_crew_tool_specs_on_a_request_stay_under_the_ceiling[codex] failed: codex's largest request carried 12446 bytes of kirocrew* tool specs, under the 40000 target. Every other harness passed the same probe in that run.
  • The diff does not touch src/kiro_crew/acp/, src/kiro_crew/mcp*, any tool spec or generated code, or test/real_adapters/.
  • On main, run 43814579403 (head 6b2c74d) passed the lane, including "Require every contract test to have executed".
  • After rebasing onto main (66be1f3), the lane passed on this PR at 1ade30f.
    So the red was not produced by this diff; expectations.json is left unchanged.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

GPT F1 on 1ade30f (background subagents outlive the run), addressed in 8ccd8fb: a row with subagents_running counts as busy, so an idle parent with a running child is not done; and every exit now stops each run chat and then closes it (DELETE /api/chat/slots/{key}, children first, root last), which tears down its background subagents and a conductor's workers and saves the history the transcript path names. Test: test_running_subagents_keep_the_run_busy_and_every_exit_closes_the_chats. On 1ade30f every Linux shard, E2E and Real Adapter passed before this push.

@iamwhatever
iamwhatever force-pushed the feat/chat-headless branch 2 times, most recently from 30904b3 to df6ee34 Compare November 16, 2026 08:06
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 16, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

GPT 6.1 findings on 8ccd8fb: all three fixed in df6ee34 (rebased on 31cc202).

  • F1, cleanup misses children made since the last poll (cli_chat_headless.py _stop): _stop now halts the root first (automation loop, then turn), re-reads GET /api/chat/slots?crew=all, widens the set with descendant_slots, and halts each new chat, repeating until no new chat shows up (capped at 5 reads), before closing children then the root. Test: test_stop_reads_the_slot_list_again_for_children_made_since_the_last_poll (interrupt before any poll saw the child; the child is stopped after the root and closed).
  • F2, queued background work counted as done (busy()): subagents_queued now counts as busy. Test: test_queued_subagents_keep_the_run_busy (--until-done --idle-grace 1 does not finish while work is queued).
  • F3, non-UTF-8 --message-file (options_from_args): UnicodeDecodeError becomes a UsageError (exit 2, "--message-file must be UTF-8 text"). Test: a UTF-16 file in test_message_file_is_read.

Also from the First Principles note (item 5): the second "nobody typed" list, now in goal-conductor/references/rare-cases.md after main moved it, gains [headless run; test_conductor_agent.py pins it.

Local: touched tests plus every goal-conductor test (979 passed), headless e2e (2 passed), isort/black/flake8/mypy, line cap, comment history, docs lint, flake ratchet.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=39e5f7f0b1ae

  • Fixed: cleanup misses children created since the last poll; queued background work cancelled as done; non-UTF-8 seed files escape usage-error handling (src/kiro_crew/cli_chat_headless.py, all three share this span)

Fixed in df6ee34. _stop halts the root first, re-reads the slot list and halts any chat created since the last poll (until none is new, at most 5 reads), then closes them. busy() counts subagents_queued. A UnicodeDecodeError on --message-file is a usage error (exit 2).
Tests: test_stop_reads_the_slot_list_again_for_children_made_since_the_last_poll, test_queued_subagents_keep_the_run_busy, UTF-16 case in test_message_file_is_read. Details in comment 6910906793.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 16, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 16, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own.

This PR adds kirocrew chat --headless, which drives the running gateway with owner requests that already exist. It makes one gateway change: an owner-only, audited unattended send that opens with a [headless run cli:<id>] marker the conductor skill treats as nobody-typed, and every caller's typed copy of that marker is defanged. I checked the owner gate (is_owner_dashboard_request, internal and app callers refused), that the rewrite runs once before the card, queue and steer paths, that the trust change goes through the existing /api/chat/mode governance and audit, and that every exit path stops loops, turns and background agents and then closes the chats. Plain chat is unchanged, unit and end-to-end tests cover the new behaviour, and CI is green. The remaining issues are minor or match existing patterns, so they are non-blocking notes.

Tier: 2, held for a person: design-doc-gate: D.

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 bf049b3a0a · 2508 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This adds a new concept, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here.

The review found no blocking defect on this head. It checked that every gateway route and slot field the new CLI uses exists, that headless_marker.apply refuses any caller that is not the dashboard owner (app tokens, teammates and internal auth), that it checks run_id against a strict pattern and refuses / and @ seeds, and that every allow and deny writes a SEL row. The cleanup in _stop closes the automation loop, the turn and every descendant worker, and both the unit suite and a real-gateway e2e test pin it. That cleanup is done well.

The decision stays with the owner and a security reviewer, because the new [headless run marker lets the conductor skip its plan gate. Two things in the thread need their answer:

  • The PR flips its own RFC to accepted and credits a decision by the repository owner. No comment from the owner on this PR records that decision.
  • The frozen ## Not a goal rules out "any change to a gateway route, caller rule or approval policy", but the diff adds owner-only unattended/run_id handling and new 403/400 refusals to POST /api/chat. Only a person may amend that line, with the reason in a PR comment.

For the security review:

  • The marker gives the owner nothing they cannot already type (a reply like "go ahead" already passes the plan gate), and non-owner callers get a 403.
  • Every caller's typed [headless run opener is defanged, so a teammate, app or agent cannot forge the marker.
  • The CLI mints its owner token the same way the existing local owner bootstrap does, and --message-file reads go through the sensitive-path gate.

Optional:

  • If the RFC stays draft until the owner records the acceptance, keep the section wording edits. The README row still lists --approval-mode auto, which this PR renamed to trust.
  • _seed_and_poll in cli_chat_headless.py sends unattended/run_id in chat mode too, so chat-mode seeds carry the marker and / or @ seeds are refused there. Only the conductor mode needs it.
  • One handler-level test that posts [headless run through POST /api/chat as an app token and as an agent-origin body would pin the defang at the route, not only inside apply().

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 16, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 16, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=39e5f7f0b1ae

  • Fixed: failed chat closure leaves background agents running after exit (src/kiro_crew/cli_chat_headless.py)

Fixed in 09401c0. _halt now cancels each run chat's running and queued background agents with POST /api/spawn/stop-all {"slot": key} after the turn stop and before the close, so a close the gateway refuses (history_write_running) no longer leaves them running. A close that fails for any reason other than 404 (already gone) is no longer swallowed: the chat is listed in the result's new unclosed field and named in error (RFC §12.4 and cli.md document it).
Tests: test_a_refused_close_still_cancels_agents_and_is_reported (HTTP 500 on close: stop-all ran first, unclosed == [root]), test_an_already_closed_chat_is_not_reported.

One unattended run on the local gateway with a result: --mode conductor opens the chat in conductor mode on the agent the gateway's crew_mode_agent resolves, --approval-mode trust puts the chat this run opens in Trust through the audited POST /api/chat/mode, --until-done stays through patrol and worker wakes until every work-ledger item is terminal, plus --cwd, --timeout, --budget, --idle-grace, --message-file and --json (asks, wall, credits, completed, transcript, resolved agent and its source). One exit code per outcome. Any ask of a person stops the run with exit 3, and every exit stops the run's chats and their automation. The gateway opens an owner's unattended send with its own [headless run cli:<id>] marker (audited, owner only, typed copies defanged), which the goal-conductor skill lists as a nobody-typed opener. rfc-builtin-eval.md: status accepted; sections 5 and 12 describe what ships.
@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=39e5f7f0b1ae

  • Fixed: background activity hides a completed turn's request for input (src/kiro_crew/cli_chat_headless.py)

Fixed in bf049b3 as suggested. A new turn_busy() (running, preparing, compacting) gates both options checks: the root's [OPTIONS: parse (root_idle) and a child chat's has_options. busy() is turn_busy() plus running or queued background agents and still decides whether the run is finished.
Test: test_a_choice_list_asks_even_while_a_background_agent_runs (root with a running agent; child with a queued agent; both end asked).

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 16, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving bf049b3a0a. One deep pass over all 14 files, focused on unattended safety.

What I checked

  • No silent auto-approval. Without --approval-mode trust nothing is pre-approved: a pending approval, needs_input, an ask_question card, a ledger item awaiting the person, or an [OPTIONS:] turn on any run chat ends the run as asked (exit 3) and stops every chat (cli_chat_headless.py asks_now / _poll). trust goes through the normal POST /api/chat/mode handler, so it stays per-slot and under the approval_modes governance scope; a refused mode raises and the run stops before the seed is sent. YOLO is never sent, and _stop no longer resets to normal, so a process-wide YOLO is not cleared by accident.
  • Identity matches interactive. The run is the dashboard owner through the kirocrew token path (1-minute owner token over the peer-verified loopback transport). headless_marker.apply admits unattended only for the owner (app, internal, member and teammate get 403), checks run_id against a strict word shape, writes a SEL row, and defangs a typed [headless run (any Ps opener, case-folded) for every caller. Skipping the plan gate gives nothing a person typing "go ahead" does not already get.
  • Exit codes and timeouts. Codes 0-9 and 130 are one table (STATUS_EXIT), and --json always prints one object. Every exit after the chat exists goes through _stop (automation deleted, turn stopped and forced if declined, spawn/stop-all, chats closed root last, unclosed chats named).
  • Secrets. Output is status, counts, slot, transcript path and error text only. The token is never printed. --message-file goes through safe_read_file, so a credential path is refused.

Optional, not blocking

  • --timeout defaults to 0 (no limit). A root turn that never goes idle keeps the CLI waiting forever. That matches interactive chat, but an eval runner should always pass --timeout; worth one line in cli.md.
  • The defang runs only on POST /api/chat; channel and queued inputs can still carry a typed opener. Design Review already rated this harmless, and I agree.

Local results (worktree on bf049b3a0a)

  • test_cli_chat_headless.py, test_conductor_agent.py, test_e2e_smoke.py, test_headless_marker.py: 164 passed, 14 skipped (e2e gated). With KIROCREW_E2E=1, both headless e2e tests passed.
  • flake8 clean on changed sources; mypy: no issues.
  • CI: 79 pass, 18 skipped, none failing.

Design note: the Captain's sign-off ask is about the RFC's status moving to accepted. Joe asked the core group to review this PR, and the code matches RFC §12 as written.

AI-assisted, sent by Bolin Review bot

@bolichen97
bolichen97 merged commit 5ff3fed into main Nov 16, 2026
154 of 155 checks passed
@bolichen97
bolichen97 deleted the feat/chat-headless branch November 16, 2026 23:20
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 16, 2026
@buluoray

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]: Reviewed at bf049b3. This merged before the review was posted, so the findings are in #38170 instead of a review. None of them blocks; the main ones are an agent shell starting a Trust run on hosts where the local mint is open, and no default wall cap.

@bolichen97

Copy link
Copy Markdown
Contributor

Maintainer design sign-off from @bolichen97, recorded after the merge because this PR merged before it was posted (my bot approved it without waiting for this step, sorry about that).

On the two points Crew Captain left for the owner:

  1. RFC status: the RFC moving to accepted stands, and this comment is the owner's decision it credits.
  2. The ## Not a goal line: amended. The line ruled out "any change to a gateway route, caller rule or approval policy". It now allows the one change this PR makes: owner-only unattended/run_id handling on POST /api/chat, with its new 403/400 refusals. The reason is that a headless run needs the gateway to know the turn has no person to answer a plan gate. Limiting that to the dashboard owner, checking run_id against a strict pattern, and writing a SEL row for every allow and deny keeps it from widening anyone else's access. Every other route, caller rule and approval policy stays out of scope.

The [headless run marker skipping the conductor's plan gate is accepted on those terms. If a later change lets any caller other than the owner set it, that change needs its own security review.

AI-assisted, sent by Bolin Review bot on behalf of @bolichen97

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.

4 participants