Skip to content

Latest commit

 

History

History
2953 lines (2677 loc) · 276 KB

cli.md

File metadata and controls

2953 lines (2677 loc) · 276 KB

CLI Module

Overview

The CLI module (kiro_crew/cli.py) provides the kirocrew command using stdlib argparse.

Module layout

kiro_crew/cli.py is the entry point and the one import path callers and tests use. main() keeps the prologue, the top-level parser with the gateway command's own arguments (pod.runtime_boot.target_supports_flag reads them from this file's text) and the internal mcp-* server verbs, the boot steps, and the dispatch chain. The rest lives in sibling modules, and new work for each part goes to its module:

Module Owns
cli_parser_gateway.py the argparse registrars of the Start here, Run the gateway and Set it up commands, all but gateway
cli_parser_agent.py the registrars of the Work with the agent, Memory and knowledge and Extend it commands
cli_parser_admin.py the registrars of the Security and privacy, Move it and back it up and Develop Kiro Crew itself commands, but bench, perf and desktop, which register from cli_bench.py, cli_perf.py and cli_desktop.py
cli_logging.py console and gateway.log logging: _setup_cli_logging, the log queue listener and its drains
cli_jail.py the process-isolation jail gate: _JAILED_COMMANDS, _jail_reexec_gate
cli_gateway_boot.py what the gateway branch prepares before asyncio.run: _resolve_gateway_args, _install_child_watcher, the lock-refusal diagnostics
cli_knowledge.py the knowledge and consolidate handlers

A registrar is one register_<command>_parser(sub) function per command (chat, run, eval and consolidate also take the shared --no-jail parent parser), in the module of the command's cli_help.COMMAND_GROUPS section. main() calls every registrar in registration order between the parser preamble and cli_help.hide_internal_commands, so a new command gets a registrar, a call in main() and its section row. The registrars build parsers only and read no name a test patches through kiro_crew.cli. bench, perf and desktop keep their registrars in cli_bench.py, cli_perf.py and cli_desktop.py, beside their handlers. The owner-only log file handlers that the slim mcp-* entry (kiro_crew.mcp_entry) shares stay in cli_log_files.py; the wiring that attaches them for a command goes in cli_logging.py.

kiro_crew.cli is a mirror facade (kiro_crew._facade_mirror) over the last four modules, its owners. Every name cli.py held before the split still resolves as kiro_crew.cli.<name> and is the same object, and a patch through it (monkeypatch.setattr, mock.patch) reaches every owner that binds the name. No owner imports kiro_crew.cli or another owner, the owners log as kiro_crew.cli, and the facade declares no exclusion. test/test_cli_split_facade.py pins the contract.

cli_commands.py and its owners

main() takes the handlers of cron, spawn, learn, artifact, memory, app, eval, security, policy, tailnet, telemetry, secrets, pod, agent and workspace, and the mcp-<app> server of a built-in app, from kiro_crew/cli_commands.py, through a function-local import (see Import Weight Contract). That module keeps the tailnet, telemetry, secrets and pod handlers and the config-shape guards tailnet runs first. Each of the others lives in a cli_commands_<command>.py module beside it, and new work for one of those commands goes to its module:

Module Owns
cli_commands_workspace.py workspace, and _locked_config_write, the locked config.json write that workspace and agent delete share
cli_commands_memory.py memory, and _finding_store_suffix, the named-store label security audit prints too
cli_commands_gateway_api.py spawn and artifact, which call the running gateway's internal API with the local secret
cli_commands_app.py app
cli_commands_agent.py agent
cli_commands_cron.py cron
cli_commands_security.py security and policy
cli_commands_eval.py eval
cli_commands_learn.py learn

kiro_crew.cli_commands is a mirror facade (kiro_crew._facade_mirror) over those nine owners, lowest layer first in the order of the table. It keeps its whole import block, so every name it held before the split still resolves as kiro_crew.cli_commands.<name> and is the same object, and a patch through it reaches every owner that binds the name. An owner never imports the facade, and imports another owner only from a row above its own: agent takes the locked write from workspace, and security takes _finding_store_suffix from memory. The moved handlers log as kiro_crew.cli_commands, _CliConflict keeps that module name, and the facade declares no exclusion. test/test_cli_commands_split_facade.py pins the contract and freezes the facade's import block, so a new import goes in the owner that reads it. A new command's handler goes in a new cli_commands_<command>.py owner, added to the facade's _OWNERS, to OWNERS in that test and to _BANNED_AFTER_CLI_IMPORT in test/test_cli_lazy_imports.py.

kiro_crew/cli_server.py holds the server-lifecycle commands main() dispatches to. It keeps status, gateway, run, service, sandbox and logs; the gateway peer proof, the owner requests (token, logout, update approve), stop, restart and update live in its owners, and new work for each goes to its module:

Module Owns
cli_server_peer.py the proven route to the gateway every local-secret send takes: _owner_verified_secret_urlopen and its connected-peer proofs, and _CLI_LOOPBACK
cli_server_requests.py the commands that make one owner request of the running dashboard with the local secret: token (with the session URLs it prints), logout, update approve
cli_server_stop.py finding and stopping this home's gateway (stop, gateway-pid): the authenticated shutdown, the pid verification, and the service-alias and lock-holder refusals restart shares
cli_server_restart.py restart: the wait for the incumbent to exit, the detached spawn, the readiness probe and its deadline, the gateway.log relay, the printed sign-in URL
cli_server_update.py update: the git, wheel and managed-venv paths, the memory snapshot taken first, the agent-config refresh after

kiro_crew.cli_server is a mirror facade over those five owners, lowest layer first. Every name cli_server.py held before the split still resolves as kiro_crew.cli_server.<name> and is the same object, and a patch through it reaches every owner that binds the name. An owner imports only the owners listed before it, never the facade, and the owners log as kiro_crew.cli_server. test/test_cli_server_facade.py pins the contract.

Member memory commands

kirocrew agent create --name <name> explicitly creates a stable member identity and its empty member-scoped V2 SQLite database, and a workspace of the member's own (member-<slug>, printed as Workspace: …). --workspace <name> instead binds the member to that workspace as given, sharing it. A member cannot share or rebind its store through a template, display-name change or arbitrary database path. This development-stage V2 contract has no old V2 data migration or compatibility mode. Global and named V1 memory retain their existing behavior independently.

--kiro-agent on agent create names the starting template and accepts only kirocrew, the built-in worker and the default. Any other value exits 1 with "Mates start from the built-in worker; create it, then add abilities from that agent in its editor." before anything is written (mate_config.start_template_refusal, the rule POST /api/agents answers 400 mate_template_unsupported with). A value equal to the crew's own key is refused as a template of the same name.

--model <id> on agent create and agent update writes the member's agents.<name>.model, the field _session_model reads first. Omitted, update leaves the pin alone; "" or auto stores "" (inherit), through normalize_agent_model. An update publishes only the fields it was given (persist_member_config(changed_fields=...)), so a concurrent edit to another field survives. An agent update given no --kiro-agent, --workspace (a blank one counts as none), --display-name or --model, and a workspace update given no --dir, change nothing, so each warns nothing to update on stderr, writes nothing, logs no success event, and exits 0 as it did before. The value is judged on shape (validation._MODEL_NAME_RE, as the cron job --model flag is), then, unless the provider is claude_code, refused when model_registry.acp_id_correction maps it to another served id or when _model_rejected_reason finds it display-only for the harness _pin_entitlement_backend picks, or, when that harness shares kiro-cli's acp namespace, when model_registry.lacks_acp_id finds a registered model with no kiro id. These are the three checks the crew editor's _model_pin_rejected runs: the first two before entitlement, the third in its place when it has no live catalog, so a canonical key the harness translates is accepted here as it is there. Entitlement needs a live session's advertised list, which the offline CLI does not have, so an unknown id is accepted, as _validate_role_model accepts with no evidence. agent list prints a MODEL column: the pin, or (inherit).

kirocrew doctor reports the configured member, store and integrity failures without provisioning, repairing or replacing databases. A missing, corrupt or wrong-member database requires explicit recovery; ordinary opening never creates an empty replacement or falls back to Global. SQLite reads can create transient WAL coordination files without changing learning records. See the memory contract.

Import Weight Contract

cli.py is the shared dispatcher for every subcommand — including the long-lived MCP stdio servers (for example kirocrew mcp-core / mcp-cron / mcp-computer; mcp-dashboard, mcp-work, mcp-crew-log, mcp-debug, mcp-panel and mcp-guide are dispatched the same way), which hold its module-scope imports resident for their whole lifetime. Its module scope therefore stays light: cli_commands, cli_server (which pulls slack.gateway) and dashboard.state (which pulls vector_memory → numpy) are imported inside the one main() dispatch branch that uses each name, never at module scope. Deferring them cuts a fresh import kiro_crew.cli from ~1.3 s / ~112 MB to ~0.5 s / ~54 MB, paid per CLI invocation and per MCP backend process. test/test_cli_lazy_imports.py ratchets the contract: after import kiro_crew.cli in a fresh interpreter, none of those modules may be present in sys.modules, and every deferred dispatch import must resolve.

Bare kirocrew --version (exactly one argv entry) is answered by pre-dispatch fast-path guards — _bootstrap.main (which then skips importing cli on the console-script path) and __main__ (same for the python -m path, which also covers the desktop launchers) — printing kiro_crew.version_line() and exiting 0. It is the one invocation that never reaches cli.main(): no platform boot, no sandbox hygiene, no project-dir resolution, no logging or data-home setup, and no editable-install self-heal (a broken checkout answers --version instead of healing or exiting 1). Only the bare form fast-paths — artifact show --version N reuses the flag name for an artifact version int, so every other argv shape falls through to argparse unchanged.

The entry point itself is not negotiable: every command invocation (kirocrew <sub>, python -m kiro_crew <sub>, and the frozen desktop binary) lands in cli.main(), whose prelude runs boot_platform() (fail-closed for non-standalone profiles), sandbox env hygiene, and KIROCREW_PROJECT_DIR resolution before any dispatch.

Gateway mise environment

Before starting services, cli_server._gateway() calls env.activate_mise(). It loads the user's global mise environment even when a daemon starts without shell startup files. Binary lookup prefers the inherited PATH, then ~/.local/bin/mise. On macOS it next checks /opt/homebrew/bin/mise and /usr/local/bin/mise, in that order. Each fallback must resolve to an executable file; the Homebrew paths are not probed on other platforms. No shell is started, and locating mise does not add any directory to the gateway's PATH.

The selected binary runs mise env --json from the user's home with a ten-second timeout. Returned string values are merged into the gateway environment for later child processes. KIROCREW_NO_MISE skips discovery and activation. Missing mise or a failed invocation remains non-fatal, and so does a candidate whose probe raises (env._mise_bin skips a path whose stat or access check raises OSError, such as EACCES, like a missing one). Registered MCP search directories remain separate from the runtime PATH; this lookup does not change that contract.

Source Checkout Launcher

The POSIX wrapper at bin/kirocrew resolves symlinks to find the real checkout, sets KIROCREW_PROJECT_DIR to that checkout unless the caller already supplied one, and delegates every argument to .venv/bin/kirocrew. The virtualenv entry point comes from the editable install created by the setup scripts, so it makes src/kiro_crew importable without adding the source tree to PYTHONPATH. Any caller-provided PYTHONPATH is inherited unchanged.

If .venv/bin/kirocrew is unavailable, the wrapper exits with source-install guidance instead of falling through to a different Python environment.

Standalone Wheel Installer Trust Contract

cli.sh installs channel or pinned-version wheels only from an authenticated manifest. This distribution trust boundary is independent of the runtime CLI and of macOS signing/notarization.

  • Schema: kirocrew-cli-artifact-manifest-v1.
  • Algorithm: RSASSA_PKCS1_V1_5_SHA_256.
  • Key identity: sha256: plus the lowercase SHA-256 digest of the public SubjectPublicKeyInfo DER bytes.
  • Signed fields: algorithm, channel, key_id, pub_date, python_requires, schema, sha256, version, and wheel_url.
  • Optional signed field: min_version — the forced-update floor for a breaking release, declared in packaging/MIN_VERSION at publish time. Must be a bare release (0.6.0, no prerelease suffix) and must not exceed the manifest's own version; both are enforced by packaging/signing/cli-manifest.py before signing. The installer verifies its format but does not act on it (it always installs the signed version); running gateways read it from the channel feed and mark the update REQUIRED when their own version sits below the floor — but only after platform/feed_trust.py verifies the manifest signature against the same pinned key, because the floor coerces the dashboard UI and an unverified one must degrade to the ordinary dismissible prompt. That module's verification core is shared: the hosted feature-video manifest is signed by the SAME offline key and verified through verify_document_signature, which differs only in allowing a nested payload and its own size cap. One trust root, and the two documents stay non-interchangeable because each carries a distinct schema inside the signed payload that its consumer requires. Absent means no floor, and the canonical payload omits the key entirely so no-floor manifests stay byte-identical to the pre-floor format.
  • Signature field: base64 RSA signature over sorted, compact UTF-8 JSON of all signed fields; signature itself is excluded.
  • Channel source: feed/<channel>/latest-cli.json. Pinned-version source: cli/<channel>/<version>/cli-manifest.json; pinned installs do not resolve through the mutable channel feed.

The installer embeds the public key and expected key id. Before any network request, it requires OpenSSL, rejects an unconfigured pin, materializes the key, and verifies its DER fingerprint. It then applies bounded input/object sizes, duplicate-key and exact-field-set rejection, printable-ASCII/string checks, canonical URL and digest validation, requested channel/version matching, and pinned-key signature verification. Artifact fields are not consumed and wheel bytes are not fetched until the signature succeeds. The downloaded wheel must then match the authenticated SHA-256 digest before pipx install runs.

Any unavailable trust root, malformed or unsigned legacy feed, unknown field, wrong schema/algorithm/key id, signature failure, metadata mismatch, network failure, or wheel digest mismatch terminates installation. There is no unsigned, SHA256SUMS, or trust-on-first-use fallback. Until the operational public key is pinned, the repository's explicit UNCONFIGURED state therefore makes stock cli.sh non-installing by design. Provisioning and rollout are specified in packaging/signing/README.md.

The publication gate in .github/workflows/publish-installer.yml checks every live channel feed with packaging/signing/cli-manifest.py verify before it replaces the live cli.sh. That is a second implementation of the contract above, so what holds between them is a direction rather than equality: whatever the gate accepts, the installer must also accept. The gate is deliberately stricter in three places — a 16 KiB payload cap against the installer's 64 KiB, a 2048-character cap per field, and refusing a min_version above the version the manifest ships — because rejecting a feed the installer would have taken costs a publisher one loud failure, while the opposite direction publishes a feed that bricks installs and reports success while doing it. Both sides therefore normalize the artifact base identically, stripping at most ONE trailing slash (${ARTIFACT_BASE%/} in cli.sh), and the gate refuses a base with repeated trailing slashes instead of normalizing to a URL no installer reproduces. test/test_cli_manifest_signature.py holds the direction by driving one shared fixture set — valid, wrong-channel, wrong-host, tampered, legacy — through the gate and through a real cli.sh run.

Project Directory Detection

At startup, main() auto-detects the project root and sets KIROCREW_PROJECT_DIR:

  1. If KIROCREW_PROJECT_DIR env var is already set, use it
  2. Walk up from CWD looking for a directory with both skills/ and src/kiro_crew/ (_PROJECT_MARKERS). Agent config lives under src/kiro_crew/config/, so _PROJECT_MARKERS requires only those two directories and not a project-level agents/ one.
  3. Read saved path from ~/.kiro/crew/project_dir (written by kirocrew setup); the saved path is re-validated against the same markers

This allows kirocrew to find project-level agent config and skills from any directory.

Commands

Top-level help

kirocrew --help (and a bare kirocrew, which prints the banner first) does NOT use argparse's own subcommand block. With ~40 commands that block is one flat list in registration order, so the three commands a new install needs — gateway, service, doctor — land in the middle of it, and the {chat,doctor,gateway,…} choice blob makes the usage line unreadable.

cli_help.py owns the taxonomy instead:

  • COMMAND_GROUPS is an ordered list of sections, each an ordered list of (command, one-line summary). It is the single source of truth for what the top-level help lists and in what order; Start here is first and holds exactly gateway, service, doctor.
  • Its notes answer the two questions the flat list never did: how gateway (foreground, dies with the terminal) differs from service install (systemd unit / launchd agent, detached, restarts on crash, starts at boot, only one at a time), and that the dashboard on loopback 5476 is the only port opened — messaging channels connect outbound.
  • cli.py sets help=argparse.SUPPRESS on the subparsers action to hide argparse's listing, passes cli_help.TOP_USAGE as the top-level usage= (the suppressed action would otherwise drop the placeholder), and pins prog="kirocrew" on the action so each subcommand's own usage line is usage: kirocrew <cmd> … rather than the whole top-level usage string.
  • Every user-facing command is registered with cli_help.add_command(sub, name), which raises KeyError for a name that is in no section — a new command cannot be added without appearing in the help. The section summary becomes the subparser's description, which is what kirocrew <cmd> --help prints, so the sentence is not duplicated. A caller may pass its own longer description (bench does).
  • Internal mcp-* servers call sub.add_parser(name) with no help, which keeps them out of both listings. They are also kept out of argparse's invalid choice: 'x' (choose from …) message: cli_help.hide_internal_commands swaps the subparsers action's choices for a live Mapping view over the same parser map that ITERATES only user-facing commands, in the help's section order. Membership is unfiltered and _name_parser_map is untouched, so kirocrew mcp-core still dispatches — the filter changes what argparse prints, never what it accepts. It must be installed after the last add_parser and before parse_args.
  • test/test_cli_help.py pins offered-vs-listed parity by reading that same message, and pins that a hidden command still resolves.
Command Description
kirocrew chat -m "msg" Send a single message, print streaming response
kirocrew chat Interactive chat mode (readline, exit with Ctrl+D)
kirocrew chat --model X Override model for this session
kirocrew chat --agent <name> Chat as a crew member or a kiro agent. A config.agents key is a crew member and is resolved first through resolve_agent_bindings, as the dashboard and cron do: the session starts the member's bound kiro agent (the built-in kirocrew when it binds none) under the member's crew identity, with --model first and then the member's model pin. A member whose memory store is unusable is refused with a one-line error before anything spawns. Any other name is passed to kiro-cli as a kiro agent, unchanged. agent.default_agent is a template name and is never member-resolved. The tool gate keeps the name typed. The member's private memory store is not bound: every CLI chat shares the cli_chat session key.
kirocrew gateway Start the Kiro Crew server (dashboard + messaging channels)
kirocrew gateway --slack-only Start without dashboard or SSH tunnel instructions
kirocrew gateway --no-crons Start without cron scheduler (use when another instance handles crons)
kirocrew gateway --no-tunnel Never publish a tunnel: refuses to start or provision one for the life of the process, whatever tunnel.enabled says. SCOPED TO TUNNELS — it does not change where the dashboard binds, so a config that widens dashboard.url off loopback still does, with token auth as the control there; do not read publish_disabled() as "no published surface of any kind". Reach the instance on the loopback port it binds (ssh -L from another host). A Dev Fleet pod boots with this whenever its own checkout declares the flag — the pod's argv is built by the control plane but executed by the target worktree's gateway, so pod.runtime_boot.target_supports_flag probes that checkout first and DROPS the flag when it is absent (passing it would make argparse exit 2, which the unit's Restart=on-failure/RestartSec=5 turns into a 5s restart loop). Such a checkout keeps the tunnel behaviour it had before this flag existed and is not given the guarantee — see security.md for why no config-side substitute is applied.
kirocrew setup Install agent config, save project dir, configure credentials
kirocrew setup --agent-only Only install agent config (skip credentials)
kirocrew setup --slack Run the guided Slack credential + slash-command setup (opt-in)
kirocrew setup --whatsapp Run the guided WhatsApp opt-in: report the optional whatsapp extra and the pairing state, then enable the channel (opt-in)
kirocrew doctor Verify kiro-cli is installed and config is valid. MCP counts are host-probe results, not confirmation of session tool loading; strict-identity routing is reported as configuration, not a verified live channel.
kirocrew ledger-sweep List the session and conductor-work ledgers that look finished — kind, store directory, ledger key, phase or item counts, age and why each qualified. A DRY RUN: it deletes nothing.
kirocrew ledger-sweep --purge [--older-than-days N] [--purge-unreadable] Delete the ledgers the dry run listed. Irreversible, explicit, and never automatic — no gateway hook, no history-delete path and no MCP tool reaches it. Each delete is re-decided under the store's own lock and refused if the ledger came back to life. Default idle window 30 days, which must be a finite non-negative number (nan and inf are refused, because every comparison against nan is false and would admit every ledger). An unreadable record is listed but kept unless --purge-unreadable is given, and a store is never purged when its slot_key breadcrumb is absent or names a key that resolves to a different directory — a copied store is reported for a human instead of aiming the delete at the canonical ledger. The sweep infers nothing about sessions: an in-flight session ledger and a conductor holding no items are kept at any age. A ledger's age is its last write, not its terminal stamp alone, so a finished record that was written to recently is left alone too. Its own command rather than a doctor mode: doctor is read-only by contract, and a flag that belongs to this command is an argparse error under doctor, so kirocrew doctor --purge cannot look like a purge that found nothing. For the same reason --purge-unreadable without --purge is refused with exit 2 on stderr, not run as a dry run. A delete that fails does not stop the others: the sweep finishes, names each store it could not delete on stderr, and exits 1. Rules and rationale: session-work-ledger.
kirocrew cron add/list/remove Manage cron jobs. add registers every job kind the store accepts — an agent prompt, --script FILE.py:FUNC (a zero-token Python function that must already live under <config_dir>/crons/; the CLI registers, it does not copy) or --command SHELL — on exactly one of --every, --cron or one-shot --at (--timezone applies to --cron and --at, and is refused with --every), plus --timeout/--timeout-secs, --auto-pause-after N (consecutive failures before auto-pause, 0 = never, which, once the job keeps failing, waits 5 minutes before each further run, doubling per failure up to one hour; also on cron update), --alert-after N (consecutive failures before the failure message is sent, default 1; the bell still records every failure; also on cron update), --model, --[no-]persistent-session, --[no-]minimal-context and --hide-in-chat. Every field is forwarded into ONE locked CronService.add_job (no post-create mutation + second _save()), a script body or command is vetted at registration by the same _vet_script_file/_vet_shell_command gates cron_add uses, and any refusal prints on stderr and exits non-zero with nothing written (2 for an argparse flag-combination error, 1 for a validation, security or store refusal) — the headless contract an installer relies on. The capabilities.cron governance gate is applied at authoring (_vet_cron_capability_governance, keyed cron:cli_add) as cron_add does, so a job authored under a disabled capability is refused rather than stored unrunnable. Session-shape defaults are CronService.add_job's own (persistent_session=True, minimal_context=False); pass --no-persistent-session --minimal-context for a script/command job. --managed-by KEY records an installer's provenance key on the job (CronJob.managed_by, ASCII [A-Za-z0-9][A-Za-z0-9._:/@+-]{0,199}, create-only, persisted only when set so an unmanaged store keeps its bytes). The key is unique: CronService.add_managed_job checks it through the shared locked check-then-append core (_persist_add_if_absent_locked with a key predicate) and refuses a second add under it, so an installer that re-runs never duplicates its job. An explicit empty --managed-by "" is refused, never read as "unmanaged", so an installer whose key variable is unset cannot store a keyless job on every run. remove --managed-by KEY is the matching uninstall; it validates the key first (every unmanaged job carries an empty key, so --managed-by "" must never match) and probes raise_if_store_unreadable so an unreadable store refuses instead of reporting nothing to remove. A re-install is remove then add, which mints a fresh id. There is deliberately no replace-in-place: every run-driven removal (a script raising Done, a one-shot consumed on completion, a deferred removal) deletes its row by id with no record of the definition the run started from, so a same-id replacement would be deleted by the run it replaced. Replace-in-place needs a definition-generation fence on those removals first. add --every 0 and a blank --cron are refused with a reason naming that flag (the parser already refuses two schedule flags together, exit 2); on update they name no schedule, so it warns on stderr, leaves the schedule unchanged and applies any other field, and an unknown id still fails Job not found (an unreadable store refuses on raise_if_store_unreadable first, so it never reads as a missing id). remove <id> with an unknown id writes Job not found: <id> to stderr and exits 1, so cron remove x && next stops. An unknown id on update, pause or resume, any failed trigger request, and a script preview refuses before running it write their line to stderr the same way and exit 1. remove --managed-by KEY that matches no job prints No job is managed by: KEY and exits 0: an uninstall with nothing left to remove has done its job.
kirocrew spawn run/list Manage background subagents; list also shows accepted spawns that have not started (🕒, with why they wait) or wait to resume
kirocrew app install/list/enable/disable/uninstall Manage App Kit apps. Uninstall preserves apps/<name>/data/ by default. install, enable, disable and uninstall are sent to a running gateway over its owner-only dashboard socket (app_lifecycle_client), so the change is live at once; install sends the source directory as an absolute path. With no gateway reachable they edit the files alone and the change lands at the next gateway start. kirocrew app import --install stays file-only on purpose: it leaves the converted app off and unregistered, and the later app enable is the step that reaches the gateway. disable and uninstall check the name first: an empty name, ., or one holding .., / or \ exits 1 before the gateway is asked and before any cleanup runs. A deregistration that reports errors prints each one and exits 1. uninstall still removes the app's files first, since it has no --force and stopping would leave such an app impossible to remove.
kirocrew app uninstall NAME --purge-data Explicitly uninstall an app and permanently delete its app data.
kirocrew app dev <name> [--off] [--confirm-out-of-install-root] Toggle an installed app into/out of dev mode (no-store UI serving + live reload on file change). See App Dev Mode.
kirocrew app import <package-dir> [--out DIR] [--name NAME] [--install] Convert a manifest-declared plugin package into an app directory, reporting every kind that has no target. Reads and copies only; nothing in the package is executed. See plugin-import.md.
kirocrew app info <name> Show app details
kirocrew app init <name> [--dir DIR] [--backend] [--ui] [--cron] Scaffold a new app (name in kebab-case) into --dir (default: current directory). --backend includes a backend stub, --ui a UI frontend (ESM + Vite), --cron a sample cron job
kirocrew learn add/list/remove Manage learned corrections. remove <query> that matches no lesson writes No lessons match: <query> to stderr and exits 1, so a script can tell a miss from a delete. add refused because memory.persistence_enabled or memory.writes_enabled is off writes Lesson NOT saved: ... to stderr and exits 1, like a store refusal.
kirocrew run TASK.md Run an autonomous task from a spec file
kirocrew token Print a dashboard access URL with auth token
kirocrew open [SESSION] [--print] Open the Kiro Crew desktop app on a session through its kirocrew://chat?sid=<key> URL scheme, or bring the app forward with no session. --print writes the URL and opens nothing. The key is checked against the same grammar as the desktop resolver (website/electron/deep-link.js) and a refused key exits 2. On macOS and Linux the URL goes to /usr/bin/open / /usr/bin/xdg-open and the command exits 1 when the launcher reports that no application handles the scheme; Windows uses os.startfile. The scheme is registered by the desktop app's installer.
kirocrew logout Revoke all active dashboard sessions, refresh chains included
kirocrew manifest Generate Slack manifest with user alias auto-populated
kirocrew update Update to latest version (git fetch, pin the upstream commit, refuse a revision whose requires-python this venv fails, hard reset to the pinned commit + rebuild; a diverged checkout is refused — --force discards its local commits; a successful update ends with the restart hint on every install layout)
kirocrew status Show runtime stats from running gateway
kirocrew stop Stop a running gateway (service-aware: stops the systemd/launchd service if active, otherwise terminates the gateway found by a cross-platform port lookup — lsof on POSIX, netstat on Windows). When no managed unit is active but kirocrew.service resolves to a RUNNING alias of another unit (a systemd Alias= an operator declared on their own unit), it refuses before the foreground path — exit 1, nothing signalled — printing that unit, its scope, and the scope-correct remedy (systemctl --user stop <unit> for a user-scope alias, sudo systemctl stop <unit> for system), and audits reason=service_name_is_alias. A stopped (inactive/failed) alias is not refused, since its down target cannot be the thing to stop. Pass --port N to bypass the service short-circuit AND the alias refusal and target a specific gateway. When the desktop app supervises this home's gateway (the gateway.lock holder runs from the app's backend-dist bundle and its first ancestor outside the bundle runs from the same app install), it refuses before the port lookup — exit 1, nothing signalled — says to quit the app, and audits reason=desktop_app_supervised; with --port N this applies only when that gateway listens on N, and --expect-pid (the app's own stop) is never refused. Any probe miss keeps the existing path.
kirocrew restart Restart a running gateway (service-aware: restarts the systemd/launchd service if active — on Linux in whichever scope runs the unit, confirming it stays up afterwards and reporting a unit that lands in activating (auto-restart) as a failed restart — otherwise terminates the foreground gateway and respawns it detached). When no managed unit is active but kirocrew.service resolves to a RUNNING alias of another unit, it refuses before the foreground path — exit 1, nothing signalled or spawned — printing that unit, its scope, and the scope-correct remedy (restart verb), and audits reason=service_name_is_alias. A stopped alias is not refused. Pass --port N to bypass the service short-circuit AND the alias refusal and target a specific gateway. A gateway the desktop app supervises is refused the same way stop refuses it (nothing signalled or spawned, reason=desktop_app_supervised), naming the in-app restart (Settings → About → Restart gateway) or quitting the app first.
kirocrew service install Install gateway as a system-level systemd service (Linux, requires sudo for tee + systemctl only) or launchd LaunchAgent (macOS, no sudo). Auto-restarts on crash, auto-starts on boot.
kirocrew service uninstall Stop and remove the systemd unit / launchd plist. On Linux this covers both systemd scopes — the system unit (sudo) and a per-user unit (systemctl --user, never sudo) — and prints one line per scope saying removed (<unit file>), not installed, left in place (…) (an alias, a unit running under any load state but loaded, or a definition that is not ours is never acted on), or not reachable from this shell (…); nothing installed in either scope exits 0 with that report. In either scope the order is stop → disable → verify inactive → unlink → daemon-reload; a step the manager refuses (or a unit still running after stop returned 0) leaves the file in place and the line reads left in place (\… stop kirocrew.service` failed: …; the unit file was not removed); a closing daemon-reloadthe manager rejects (exit non-zero) leaves the scope unfinished and out ofremoved(exit 1, so the headline never readsstopped and removedwhile the manager still holds the old definition), its line readingremoved (), but `sudo systemctl daemon-reload` failed: …; run it by hand(user scope:systemctl --user daemon-reload) — except on a host not booted with systemd, where there is no system manager to hold it; a system unit on a host without sudoreadsleft in place (privilege unavailable: …)while the user unit is still torn down. An alias, and a unit that is running under any load state butloaded(a runtime mask, an unparseable edit, a file removed under it), are refused whole before any verb:left in place (an active unit whose load state is masked: unmask and stop it first, then run `kirocrew service uninstall` again). Every verb rests on one ownership decision: the unit is Kiro Crew's when the file holding its definition (the reported FragmentPath, followed through a symlink to its source) is the file the installer writes for that scope or carries the installer's marker line Environment="KIROCREW_SERVICE_MANAGED=1"; anything else under our name — a distribution's unit under /usr/lib, an operator's unit systemctl --user linked under our name, a definition under another name — reads left untouched (not installed by Kiro Crew: …)with nothing stopped, disabled or unlinked, and exits 0. A unit of ours reached through a link loses only its link entries —removed (the link to ; the linked unit file itself was kept)— and a direct file of ours is unlinked. A unit file of ours at the installer's path that the manager does not have loaded and that is not running (a file dropped without adaemon-reload, an unparseable edit) is removed without those verbs, in either scope; a mask of the unit name at that path (systemctl mask's symlink to /dev/null, placed by name at exactly the path the installer writes) is ours by name and is unlinked, removed (the mask …; kirocrew.service is unmasked), while a mask elsewhere (systemctl mask --runtime, under /run) is left in place (load state masked, …); a system manager the shell cannot reach removes the file only on a host not booted with systemd (/run/systemd/systemabsent), and otherwise readsleft in place (the system manager is not reachable from this shell: …). The system scope is decided by the manager, not by the unit file: with no file at /etc/systemd/system/kirocrew.servicethe manager is still asked (an unprivilegedshow, no password prompt), so a unit of ours still loaded and running after its file was deleted under it is stopped and daemon-reloaded (stopped (its unit file … was already gone, so nothing was disabled or unlinked; daemon-reload run)— the unit is gone, so the headline reads✅ kirocrew service stopped and removed.), a loaded unit that is not ours (a vendor unit with no file of ours shadowing it) is left untouched and not stopped, one a daemon-reloadleftnot-foundbut running is refused whole like the user scope's, and an unreachable manager on a systemd host readsnot reachable from this shell (…)rather thannot installed. The headline (✅ … stopped and removed./ℹ️ No kirocrew service was removed.) follows the report's removedset, never a line's wording. Thoseleft in placelines (exit 1 whenever a unit may still be running, or the module's own file stays at/etc/systemd/system/kirocrew.service`; a system refusal with no file there and nothing running — an inactive alias provided from another directory — exits 0 like the user scope's), or a unit file that cannot be removed after a successful stop, are marked ⚠️ on their own scope line, the AppArmor profile is still removed, and the exit code is 1.
kirocrew service status Show service status. No sudo required. On Linux it names both scopes: system scope: … then user scope: …, each not installed, not reachable from this shell (…), or the unit's ActiveState (SubState), followed by the systemctl status block for every scope that has a unit — a scope with no unit never reads inactive (dead). Exit 0 only when the unit is UP in either scope — ActiveState active (or reloading), what systemctl is-active exits 0 for; a crash-looping unit in activating (auto-restart) and a failed one exit 1 while the headline prints that state, so a script gating on the exit code reads a gateway that never started as down. macOS: launchctl list.
kirocrew logs Tail gateway logs from the systemd journal (the user journal, journalctl --user, when the gateway is the per-user unit), launchd stdout file, or ~/.kiro/crew/gateway.log. Hosts without systemd/launchd, including Windows, read the UTF-8 fallback file in Python without requiring tail. Read failures exit with file-access/retry guidance instead of an exception traceback.
kirocrew logs -f Follow logs live. The Python fallback reopens the log by name on each poll, permits Windows rename-based rotation even during reads, streams appended UTF-8 text, and stops on Ctrl+C. A replacement file or detected truncation resets the read offset; a temporary missing path during rotation is retried on the next poll. Rotated backup files are not replayed.
kirocrew cloud launch/list/status/connect/tunnel/login/logout/stop/start/destroy/iam-policy/iam-boundary/doctor Provision, connect to, and manage a Kiro Crew EC2 instance in the user's AWS account. iam-boundary is the one-time admin step that pre-creates the immutable EC2 and Fargate crew permissions boundaries — see cloud.md.
kirocrew security events Show recent SEL audit events (-n N for count, default 20; N must be 1 or more, so 0 or a negative exits 2 rather than reporting an empty log)
kirocrew security verify Verify SEL HMAC chain integrity
kirocrew security deny-list Show active deny patterns. The deny planes those patterns feed: security.md
kirocrew snapshot [output_dir] Create a .tar.gz snapshot of all Kiro Crew state, into output_dir or the data home's snapshots dir. A bare list or ls as output_dir is refused (exit 1, nothing written, a hint naming --list) unless a directory of that name already exists; a path spelling such as ./list is taken as written
kirocrew snapshot --keep N Auto-prune to N most recent snapshots (default 7). Recency is the UTC stamp in the bundle name (snapshot_order.newest_first), not the file mtime, so an older bundle copied back in does not outrank the one just written; a name without a stamp falls back to its mtime. The bundle the run just wrote always holds the first kept slot, so a clock set back after a future-stamped run cannot prune it
kirocrew snapshot --strict Exit 3 (not 0) when the written bundle omits entries it was asked to carry; see the retention note below
kirocrew snapshot --list List existing snapshots, newest first by the same order as --keep
kirocrew restore <file> Restore from a snapshot (auto-detects replace vs merge)
kirocrew restore <file> --mode replace|merge Force restore mode; merge skips malformed incoming or local cron JSON with a file-specific warning, and never overwrites a config file the destination already has -- it names each settings file it kept (↩️ <file>: kept the existing file ..., pointing at --mode replace --components config) instead of printing ✅ config, while host state (session_map.json, project_dir, workspace_dir) keeps this machine's copy silently; a bundle ui-prefs.json / notification_settings.json its own reader would refuse stops a replace before anything is installed, and stops a merge only where the destination has no such file (otherwise the destination's file is kept); a bundle's config.local.json is never installed even where the destination has none (↩️ config.local.json: not applied ...), since that overlay outranks config.json
kirocrew restore <file> --components X,Y Selective component restore
kirocrew restore <file> --dry-run Preview restore without writing
kirocrew restore --list-components Show available component names
kirocrew snapshot --allow-unpinned-staging Stage by path name where a directory cannot be pinned by descriptor
kirocrew restore <file> --allow-unpinned-staging Same, for the restore side
kirocrew snapshot --max-archive-gib N Set the bound on a bundle's uncompressed content to N GiB (1-1024; default 4) for this run. Without it, a selection whose staged content is past the bound is refused before any tarball is written, nothing is pruned, and the message names the largest entry, --components and this flag
kirocrew restore <file> --max-archive-gib N Restore a bundle written with --max-archive-gib M, for any N >= M. The member-header walk still refuses an archive that declares more than N GiB, or more than the free space of the extraction directory, before anything is extracted
kirocrew agent list/create/update/delete/reset-model Manage Kiro Crew agent definitions (kiro_agent, workspace, memory_store bindings). update --display-name relabels a crew without moving its key (see the members routes in learn-cron-dashboard.md). reset-model clears a spec's pinned model, the narrow way back to the shipped default — see providers.md.
kirocrew artifact list/show/save/update/versions/delete Manage saved artifacts (LLM-generated UI). Same store the MCP tools and dashboard use — see artifacts.md.
kirocrew consolidate [session_key] [--all] Force history consolidation, which triggers skill extraction. Consolidation drains in bounded passes, so a large backlog can end with partially consolidated, N message(s) remain instead of done; run it again for the rest (see history). A key that fails, stops part-way or records no completed pass gets one stderr line (an error shows only its type), and the command then exits 1; finished keys and skipped ones (nothing to consolidate, or a sensitive session) keep exit 0. Omit the key to list sessions with unconsolidated messages.
kirocrew eval [scenarios…] [--all] [--judge] Run multi-session evaluation scenarios; a bare invocation is the ~30s smoke test — see knowledge.md. An unknown scenario name runs nothing: it prints the error and the available names to stderr and exits 1. Any failed scenario also exits 1, after the report and JSON summary are written; exit 0 means every scenario passed.
kirocrew perf sample [--seconds N] [--interval S] [--pid PID] [--call MODULE:CALLABLE] [--output PATH] Sample stacks into a folded-stack profile. Debug-only: requires KIROCREW_DEBUG=1. With no --call it attaches to the running gateway (or --pid) using py-spy; with --call it profiles that callable in this process. Writes ./kirocrew-profile.folded by default
kirocrew sandbox install-profile/status/remove-profile Manage the AppArmor profile the agent sandbox needs (Linux) — see security.md.
kirocrew kas install/status/remove Install, inspect or delete Kiro Crew's own KAS engine bundle (<data home>/engines/kas/<version>/: a sha256-pinned @kiro/agent build plus its Node runtime). install installs this release's pinned version (acp/kas_pin.py) and refuses a manifest that does not hash to the pin; it takes --version and --unpinned (another version, for testing), --url (an https base; default agent.kas_bundle_url), --from DIR (a local manifest and its artifacts, for offline installs) and --force. A version the data home already holds is a success with no fetch, so re-running an installer passes (cli.sh and install.sh run kirocrew kas install by default once Kiro Crew is installed, warn and print this command when it fails, and skip it with --no-kas; neither turns agent.kas_bundle on); --force replaces it. That check is by version name only: a copy an earlier --unpinned install laid down under the pin's name also counts, and --force is how to swap it for the pinned manifest's engine. status shows the pin, the version that runs and every version on disk; remove --version V deletes one. Operator-facing like doctor: it runs outside the sandbox, which is the only place the engines leaf is writable. The route itself is agent.kas_bundle — see acp-client.md § KAS bundle route.
kirocrew kas login/whoami/logout/route Crew's own Kiro sign-in from a shell (cli_kas_login.py), for a host with no browser and no dashboard session -- the remote crew signed in over SSM by kirocrew cloud login, a headless host reached by ssh. login [--provider builder_id|idc|google|github] [--start-url U] [--region R] runs the device-code flow and prints Open <URL> + code: XXXX-XXXX, polling until approved (exit 0 once the vault holds the credential; already signed in, exit 0, over a usable stored identity). whoami [--format json] exits 0 with the identity (the kiro-cli whoami --format json document, never a token) or 1 when signed out. logout removes every stored identity; a gateway on the host retires its agent processes on its next turn. route prints kas-bundle when agent.acp_backend is kas AND agent.kas_bundle is on, kiro-cli otherwise -- the remote sign-in scripts read it on the box. Not an MCP tool: a sign-in moves a credential and the agent must never choose whose. kas-auth.md § Sign-in from a shell.
kirocrew tailnet status/up/down Publish the dashboard on your tailnet (Tailscale) and trust its origin, or stop publishing — see remote-and-mobile.
kirocrew telemetry status/disable/enable Inspect exactly what the anonymous beacon sends, or turn it off permanently — see metrics.md and governance.md.

Staging is descriptor-pinned, and refuses rather than degrading silently

Snapshot and restore stage through kiro_crew.pinned_fs: the parent chain is resolved once, pinned component by component with openat + O_NOFOLLOW, and everything downstream is addressed through the descriptor already held. A validated path and the inode later opened are otherwise not the same thing, and anything running as the user — which in this product includes an agent — can plant the swap between the two.

pinned_fs.py stays the import path. It keeps the tree operations -- stage_tree_pinned and the verified scan, removal and put-back of a tree -- the two openers under a pinned parent (open_in_pinned_parent, open_dir_pinned) and its hand-written __all__, and is a kiro_crew._facade_mirror facade over three owners: pinned_fs_primitives.py (the refusal type, skip reasons, platform probes, pinning a parent, a descriptor's real path), pinned_fs_dirs.py (creating and opening directories under a pinned ancestor) and pinned_fs_files.py (copying, writing, reading and unlinking one file). New work goes to the owner of its responsibility.

os.supports_dir_fd is empty and O_NOFOLLOW does not exist on Windows, so pinning is unavailable there. The decision, recorded here rather than only in the pull request that made it: staging is refused on such a platform unless --allow-unpinned-staging is passed, and when it is, the archive's MANIFEST.json carries "staging": "unpinned" and kirocrew restore --dry-run prints that the archive was staged by name. The refusal is the default because a by-name walk is not a slightly weaker version of a pinned one; it is the mechanism whose failure closed two earlier attempts at this change. The flag is a permission for a platform that cannot pin, not a switch that turns pinning off where it works.

MANIFEST.json also carries "skipped": any file omitted during staging (a hardlink alias, a symlink, an entry that vanished mid-walk, or an entry present but refused for permission -- unreadable_entry) with its reason, so an incomplete archive says so in its own record instead of only in the console output of whoever ran the command.

unreadable_entry is the one reason that is a TOLERANCE rather than a screen, and it is narrow in three ways. It belongs to snapshot creation only -- restore and merge still stop, because there the unreadable name is the archive's own content and skipping it would drop data the operator asked to have put back. It covers only the permission class, so a failing device still ends the command instead of producing a backup that quietly omits whatever the disk refused. And it covers only reads of the operator's own file: a refusal to WRITE the staged copy is never recorded as the source being unreadable. A data home can hold a platform-protected path that no retry will make readable, and refusing to produce any backup over one file is worse than a bundle whose manifest names the gap. Files a component DECLARES are not covered: those are product-owned state, and a bundle that silently shipped without config.json would be worse than a refusal, so that loop still fails hard.

Retention reads those reasons as a class, not by name, through one predicate, pinned_fs.omits_wanted_data(). symlink and not_regular are screened on every run by design, so a bundle that screened one is complete; everything else means the archive lacks something it was asked to carry. --keep does not prune after a run in the second class, and prints which reasons applied. A reason code the split does not know counts as incomplete, because the alternative is pruning the operator's last complete backup on the strength of a code nobody has classified yet.

The exit status follows the same predicate, but only on request. By default a run that wrote a bundle exits 0 whether or not it is complete, because existing unattended callers (the AWS Control app's off-host backup among them) treat any non-zero exit as a failed backup and would stop uploading a bundle that is written and restorable. kirocrew snapshot --strict exits 3 instead when omits_wanted_data() is true for any skipped entry; the bundle is still kept and the prune is still held. Exit 1 keeps meaning no usable bundle was produced.

SQLite databases are out of scope for the pinned staging described here: they keep the sqlite3.backup() path they already had, which reopens the live name. Capturing a live database without reopening its name is a genuine conflict of requirements — SQLite accepts only a path and cannot be pointed at a held descriptor — so it is tracked separately rather than solved alongside the tree walk. The exposure is unchanged from before this staging work, not introduced by it.

A refusal to stage is a permission decision and is written to the SEL audit log — snapshot_rejected or state_restore_rejected, both with reason=unpinnable_staging.

The restore's notification merge (_merge_notifications) resolves each name once: where the platform can pin, source and destination are each opened through pinned_fs.open_in_pinned_parent (the parent chain walked with O_NOFOLLOW from a caller-resolved root, so an ancestor swap is refused too), the descriptor is judged with fstat (S_ISREG) plus pinned_fs.refuse_hardlink_alias — a hardlinked alias is a regular file that no link screen can see, only the inode's link count — and the validation pass and the copy loop read that same held descriptor — the source rewound with seek(0), the destination one O_RDWR|O_APPEND handle for both its scan and the append. Validating a name and then re-opening it are two resolutions of the same string, and the staging tree is agent-writable, so a swap between them used to append the link target's bytes into the live notifications.jsonl under a validation that had vouched for a different file. O_NONBLOCK is load-bearing, not hygiene: without it a name that became a FIFO blocks the open forever, converting a refused restore into a hung one. Where the platform has no O_NOFOLLOW (no atomic no-reparse open for the O_RDWR|O_APPEND destination handle), the merge raises NotificationCopyUnsupported — the same type _install_notifications raises there — which both merge call sites catch and degrade to a loud SKIP of that one component, exactly as the copy branch does, rather than aborting the whole restore. A by-name reparse check followed by a by-name open is a check-to-open window, and fstat/S_ISREG does not close it because a reparse point to a regular file passes it; a link, FIFO or hardlink refusal on a capable platform still raises OSError and aborts, because that is a hostile or corrupt source.

The merge's core-file installs resolve each name once as well. memory.db, memory_index.db and crons.json (and, on the dashboard import, hooks.json) are installed only where the data home has none, through snapshot_merge._install_core_file_if_absent — pinned_fs.copy_file_pinned with skip_existing=True, the config component's existing install path. The source is opened once with O_NOFOLLOW (where the platform has none, through platform_compat.open_file_no_reparse, handed over as src_fd) and judged on its descriptor (regular, one link); the destination is created O_CREAT|O_EXCL|O_NOFOLLOW. A by-name is_file() followed by shutil.copy2 was two resolutions: a dangling link at the live name passed the check and was then followed out of the data home, and a hardlink alias in the staging tree was installed as the core file. A skipped install is printed and the component loses its tick; the line names which cause it was (an occupied live name, or a refused bundle copy already reported above), via snapshot_merge._core_file_not_installed. An existing memory_index.db beside a freshly installed memory.db is kept, never overwritten, and reported as memory_index.db: existing index kept, not replaced; the gateway rebuilds it on its next start (the dashboard import lists memory search index (kept the existing one; rebuilt when the gateway restarts) in items, an opener the Portability tab counts as not applied, and adds memory_index to refused_merges), because until the gateway's startup rebuild_index runs that index does not match the imported memory and search misses its rows. The cron merge (_merge_crons) opens each store once, judges and reads the descriptor (regular, one link; the live store's parent pinned where the platform can), and rewrites the live store with an atomic replace in that same pinned directory, carrying its mode and access-control xattrs from the still-open read descriptor, only after re-checking the name still holds that regular inode; a mismatch imports nothing. Holding the descriptor keeps the inode alive, so its number cannot be reused by a planted entry. The replace stages a temporary by name inside the data home, as the cron store's own save does, so a same-UID writer that can replace that temporary is not stopped. A rename replaces the entry and never follows it. Where the store can be pinned but its access control cannot be carried onto a fresh inode (macOS: its native ACLs are not exposed through the xattr API, atomic_write.ACCESS_CONTROL_XATTRS_SUPPORTED is False), _cron_rewrite_in_place makes the merge open the live store read-write and truncate and rewrite that same validated inode instead, after the same identity re-check, so a hand-set ACL survives exactly as it did when the merge wrote by name. Residual, macOS only: that rewrite is not atomic, so a crash or a full disk mid-write can leave a torn crons.json. The memory merge's ATTACH of the staged database is not covered: SQLite accepts only a path, so it needs its own decision.

The dashboard's import path (portability.apply_import_zip) is the exception, and deliberately: it has no flag and no consent surface, so refusing there would not mean "ask the user", it would mean deleting import on that platform. It therefore proceeds with a by-name traversal where pinning is unavailable and records "staging": "unpinned" in its returned summary, with a logged warning. Snapshot and restore keep refusing, because --allow-unpinned-staging lets them ask. The per-entry screens apply on both paths — the copy opens O_NOFOLLOW and the walk rejects links and reparse points — so what the import path gives up is ancestor-swap resistance, not link resistance.

The import's cron sanitizer (portability._sanitize_imported_crons) resolves the staged crons.json once in the same way: its parent is pinned where the platform can, the store is opened O_NOFOLLOW|O_NONBLOCK (through platform_compat.open_file_no_reparse where there is no pinning) and read through that descriptor, and anything that is not one regular file — a link, a FIFO, a hardlink alias — is reported as an unreadable store and replaced with an empty one. Every rewrite is an atomic_write into the pinned directory, so a link or hardlink alias swapped in after the read is replaced, never written through. A missing store, or a directory at that name, is left alone as before. The staged notification_settings.json in the same directory is rewritten by atomic_write too, for the same reason. The merge that consumes the sanitized store reads it again by name; closing that second resolution is the merge's job, not the sanitizer's.

kirocrew restore applies the same rule to its staged bundle before either mode reads it (snapshot._hold_back_executables), so a bundle restored from the CLI cannot start running commands on the next gateway start: a command or script cron is restored paused (user_paused, enabled false) and a command failing _vet_shell_command is dropped, through _sanitize_imported_crons(..., drop_malformed=False) — the restore keeps its own shape handling (merge skips an unusable store, replace validates it), so only the vet and the pause are applied. A hook in the staged hooks.json that has a command is restored with enabled false by portability_vetting._disable_imported_script_hooks, which keeps every other top-level key (webhook resume contexts) and leaves skill-only hooks alone; the dashboard import calls it too and lists the names in disabled_hooks. The restore prints the paused, disabled and dropped names, and where to switch each back on (Schedules, Hooks). A merge into a home that already has a hooks.json keeps that file, so no bundle hook is named. Message-only crons are restored as they are.

The dashboard import's Merge follows the same never-overwrite rule as kirocrew restore --mode merge for the settings documents (config.json, config.local.json, ui-prefs.json, notification_settings.json): it installs one only where the destination has none, never installs the config.local.json overlay, and names each document it kept in the summary (settings_kept). Its Replace restores all four, backing up the replaced documents into pre-restore-<ts>/ first. The rule and its writers are in config.

Each rule above has one owner. kiro_crew.snapshot is the command and API facade: it holds snapshot_main and restore_main and the outbound redaction seam. restore_main sequences extraction and the bundle-shape refusals, and writes their state_restore_rejected audits. The facade re-exports the owners' names, so every existing import keeps resolving. The owners read the helpers, drivers and limits a test replaces (_copytree_safe, _do_replace_mutations, sqlite3, _MAX_ARCHIVE_MEMBERS and the rest of LATE_BOUND in test/test_snapshot_refactor_seams.py) through kiro_crew.snapshot when they use them, via snapshot_components._facade(), so a patch of one of those names on the facade reaches the owners' call sites too, and the facade stays a plain module. Every other name an owner uses resolves in that owner's own globals, so a test patches it on the owner module. The same test file scans test/ and every tests package under src/kiro_crew and fails on a patch no call site sees: a facade patch of a name an owner reads from its own globals, an owner patch of a LATE_BOUND name, and a patch of either whose name it cannot resolve outside the sites it lists. No owner imports the facade: _facade() reads it from sys.modules, since the facade imports every owner and is loaded before any of them runs. test_snapshot_refactor_ownership.py pins both halves: no owner imports the facade, and no module outside the snapshot family imports an owner.

  • kiro_crew.snapshot_components owns the component table, the never-ship and host-local rules, and the tree-root check safe_tree_root.
  • kiro_crew.snapshot_archive owns staging and the bundle format. That covers the pinned tree copy with its refusal (_staging_is_pinned), the consistent SQLite capture, the extraction filter, the archive bound and the manifest readers.
  • kiro_crew.snapshot_restore supplies the bundle predicates those refusals rest on (_component_payload_absent, _components_absent_from_bundle, _trees_absent_from_bundle), the content-soundness refusal (_refuse_corrupt_source_databases), the destination guards, and the replace transaction with its rollback.
  • kiro_crew.snapshot_merge owns the merge algorithms: memory rows, cron jobs, notification records and no-overwrite trees.
  • kiro_crew.snapshot_build builds a bundle: the size estimate (_estimate_selected_bytes) and the MANIFEST.json writer (_build_snapshot), which stages the selected components and publishes the owner-only tarball.
  • kiro_crew.snapshot_merge_driver owns the merge-mode driver (_do_merge), which runs each selected component through those algorithms, and the notification copy (_copy_notifications).

| kirocrew config get [key] | Print full config or a dot-path value | | kirocrew config set <key> <val> | Set a config value (auto type detection). A key the loaded config does not hold and the schema does not declare exits 1 with Unknown key, on --local too. --local also accepts the slack keys to_dict() writes from outside the section (slack.dm_activation), type-checked against the field they come from. A --local write of a whole object (or a scalar) over an overlay section replaces it; when that removes keys the section held, a stderr hint after the write names each dropped dotted key and the dotted-leaf form that keeps siblings (_overlay_keys_dropped). The write itself is unchanged. A key whose schema declares an enum refuses a value outside it on every write (exit 1, naming the selectable values), because the load path answers such a value by degrading it with a warning rather than rejecting it — the write is the last point where the mistake is still attributable to the command. What is written is the enum's own spelling: a case variant is canonicalised (agent.log_level debug stores DEBUG), and a key with a loader-side alias table (stt.model, through stt.models.canonical_name) stores the row the alias names (turbo stores large-v3-turbo). Only declared enums on concrete registry paths are checked; a wildcard path (slack_channels.*.activation) keeps reaching the loader's own degrade rule. Type is checked only on a declared leaf's first write (_declared_type_error); the enum check has no stored value to stand in for it. A list-typed key (declared array in the registry, wildcard paths matched segment by segment) never goes through the scalar parser: _parse_list_value accepts a JSON array and nothing else, and otherwise exits 1 before anything is written, on --local too. The case it exists for is Windows PowerShell 5.1, which strips the inner quotes of '["a","b"]' so the CLI receives [a,b]; the scalar parser stored that as a string and the loader then dropped the whole list field to its default (agent.apps_trusted un-trusting its apps). No comma-list spelling is accepted, because a list field's item type (list[int] or list[str]) is not known at the write. The refusal prints retry forms that survive PowerShell 7.3+, Windows PowerShell 5.1 and sh. The loader is unchanged. --value-base64=<token> carries the value as standard Base64 of its UTF-8 text, as ONE attached argument, in place of the positional VALUE. After a strict decode (base64.b64decode(validate=True), then UTF-8) the text goes through the same list/scalar parser and the same writer as a positional value, so the stored config is identical. It exists because Windows PowerShell 5.1 drops a separate empty-string argument before a .cmd shim and rewrites quotes, so no positional spelling is safe in every shell; an attached token has no quotes and no empty argument. The empty token (--value-base64=) is the empty string, detected with is not None (never truthiness) and so is a value, not a missing one: a scalar key stores empty text, and a list key refuses it as not a JSON array (an empty list is the token W10=, the text []). Combined with a positional VALUE or with --file it exits 1 before any write; a malformed alphabet, bad padding or non-UTF-8 bytes exit 1 with a --value-base64: message and write nothing. --local and the key argument work as before. The Settings command rows (see learn-cron-dashboard) generate only this form. | | kirocrew config set --file <path> | Replace config from a JSON file | | kirocrew config edit | Open config in $EDITOR | | kirocrew config defaults [keys…] [--adopt \| --keep] | Review stored values that still hold a superseded default, limited to the named dotted keys when given. --adopt removes the stored keys so the current defaults apply; --keep records the stored values as intentional and stops reporting them. See config.md | | kirocrew memory list/search/stats/audit | Inspect vector memory (entries, semantic search, counts, suspicious-content scan) | | kirocrew memory show [preferences\|projects\|history] | Read the markdown memory layer (all three when no target given); --format md\|json, --since YYYY-MM-DD for history | | kirocrew memory export/import/migrate | Export one store's rows to JSON, import them back, or migrate legacy markdown memory into the vector store. Both export and import take --store <name> (default: the default store), so a named store's rows are reachable in either direction as they already are for backups, restore and carve. --include-markdown adds the markdown layer and is DEFAULT-STORE ONLY: a named store's markdown root is under the fenced memory_stores/ subtree, whose refusal markdown_snapshot cannot distinguish from an empty file, so the combination is refused on stderr with exit 1 rather than reported as empty. export writes at most 10,000 episodes and 1,000 events (_EXPORT_EPISODIC_LIMIT, _EXPORT_EVENTS_LIMIT) and warns on stderr when it stops at a cap. A semantic row's stored vector ships as base64 of its float32 bytes; when any ships, the payload ends with embedding_space_sig and embedding_model ({"model_id", "dim"}, or null when this process cannot name the model). import keeps such a vector only on a store with no embedder (the CLI's) whose recorded space, the active backend's space and the payload's declared model all give the same signature; any other row lands without a vector for the gateway's re-embed sweep. import checks its input before any store opens: a missing argument, an absent file, a file that is not JSON, a payload that is not an export object, or a semantic / episodic collection that is not a list writes one line to stderr and exits 1, with nothing imported. An import into a private V2 store is refused the same way, because it cannot carry the rows' facets. An import that created a named store's database and landed no row removes that database (or says it could not) and exits 1 | | kirocrew memory backup/backups/restore | Take hot copies of Global, declared named V1 and actively owned V2 stores (--keep <n>), list a store's copies newest-first (--store), or stage a restore (--store, --from <file>, defaulting to that store's newest). Both V1 and V2 activate restoration at gateway restart. Archived V2 stores are excluded from routine backups. restore --store <member-store> --cancel-pending cancels a staged intent while preserving current memory and its backup; it is mutually exclusive with --from. A failed activation still requires restart after cancellation. All three dispatch BEFORE the shared vector store is opened, because opening it raises on exactly the corrupt file these verbs recover. backup exits 1 when any store failed to copy (a skipped store is not a failure), and backups --store exits 1 for a name that is not a declared store. See memory-skills-hooks | | kirocrew memory retired | List the episodes a semantic write superseded and restore one (--restore <id>, --limit, default 20 and at least 1: SQLite would read LIMIT -1 as no limit). --restore exits 1 when the id is not a retired episode. Default store only — it has no --store, so restoring a retirement inside a silo is a dashboard action. See memory-skills-hooks | | kirocrew memory forget <key> | Delete one semantic key from the default store. It prints the value, asks you to type the key again, then sends DELETE /api/memory/semantic/{key} to the running gateway over its owner-only dashboard socket with a credential from /api/token/local. Both connections send nothing unless the kernel-reported peer pid is the gateway pid recorded for that port, with its recorded start identity. So the delete passes the same owner gate as a dashboard delete (_memory_write_gate); with no gateway reachable it deletes nothing. The request carries the shown value as expect_value_json, so a value that changed after it was shown is kept. --superseded-by <key> records the winner and is refused when it is not live or is the key itself. An absent key exits 1. Before any store opens the verb also refuses from an agent session's shell (mcp_caller.resolve_own_identity() names a session or cannot answer) and without an interactive terminal. Those two keep an agent from running the verb; they do not authorize the delete. Not on Windows (no dashboard socket): use the dashboard Memory page | | kirocrew memory create-store <name> | Create the directory of a named V1 store declared in memory_stores (memory_stores.create_declared_store). This is the only creator of such a directory: use never creates one, because require_memory_store refuses a missing directory before ensure_memory_store_dir is reached, so a deleted store stays missing rather than coming back empty. An existing directory is left untouched. Refuses the default store, an undeclared name and a V2 member store (provisioned with its member). kirocrew doctor names this command for a declared V1 binding whose only defect is the missing directory. It does not move a pre-memory_stores/ tree; that stays a manual step | | kirocrew memory carve --store <name> | Filter or count a crew store's rows by their carve facets: one flag per facet (--scope/--surface/--crew/--session-key/--derived-from), --kind, --count-by <axis> for grouped counts, --limit/--offset. Facets exist only on a crew memory store, so the default store answers with a named refusal rather than an empty list. See memory-skills-hooks | | kirocrew policy show/validate/explain/profile | Inspect the effective enterprise security policy, load-check it and all profiles, explain one tool/scope decision for a surface, or print a profile. explain with a scope not in the catalog lists the known scopes on stderr and exits 1. show also summarizes the built-in denied-command catalog as grouped counts (--ids lists each category's rule ids), on every install regardless of whether an enterprise policy is active — the one place an agent can learn a class of work is hard-denied before planning around it. | | kirocrew policy source | Show whether this host fetches its policy from a central source. See governance.md and the enterprise governance guide | | kirocrew policy fetch [--force] | Fetch the central policy now and apply it if it is usable. --force ignores the cached validators and re-downloads the whole document. See governance.md | | kirocrew pod up/down/ls/prune/status/token/url/scenarios/api/logs/exec/install/provision | Isolated worktree test gateways. pod prune reclaims orphaned pod HOMEs in bulk (--older-than, default 3d; --all; --dry-run; --json); see dev-fleet. Three per-user, no-elevation backends: Linux systemd --user, macOS launchd, Windows Task Scheduler (schtasks.exe). On a host with none of them every service-manager-touching verb refuses with a one-line message. pod api is additionally Linux + macOS only, because its authenticated request goes over an AF_UNIX socket with no TCP fallback and CPython on Windows has none. See src/kiro_crew/pod/README.md → Platform for the per-backend capability table and the two ceilings (memory/CPU, crash restart) that only systemd enforces. | | kirocrew pod scenarios [--json] | List packaged seed scenarios in deterministic name order. Human output shortens each description to the last complete sentence that fits, cutting between words with an ellipsis when none does; --json emits an array of {name, description} rows with each fixture manifest's complete description: scalar; literal (|) blocks preserve newlines, while folded (>) blocks normalize to one paragraph. Extraction stays dependency-free without requiring PyYAML at runtime. An empty registry returns success with [] in JSON mode or an explicit human diagnostic. | | kirocrew pod api | api <wt> <METHOD> <path> [--data JSON] [--allow-write] makes one authenticated request and prints {name, method, path, status, ok, body}; GET/HEAD are the default surface and other methods require --allow-write. It refuses caller-supplied token query parameters without echoing them, authenticates with the dashboard's query-token contract, caps response reads, and mints only after the pod PID record agrees with systemd MainPID (listener tools are optional corroboration). The authenticated request goes over the pod's private dashboard-<port>.sock in the pod's own home with no TCP fallback, so the minted token cannot reach a process that took the pod's port; an absent socket refuses through the envelope before minting. See src/kiro_crew/pod/README.md. | | kirocrew pod up --seed <scenario\|dir> | Pre-populate the isolated home. A bare name is a packaged fixture and populates the whole home; a path contributes only its sanitized config.json. Unknown names are refused with the available list. Named fixtures copy directly into the final home through pinned source/destination directory descriptors; config/workspace setup uses the same held home, and the manifest lands last as the completion marker. Populated homes are never overwritten: a named-seed request against one refuses before start even when its marker matches; use plain pod up to restart it unchanged. Seeded config disables channel enablement and restores the sandbox floor. A per-instance systemd drop-in runs the checkout's own venv binary, post-health marker readback detects a seed that did not land, and pod down removes the drop-in with the home. Pod homes provide operational/state isolation, not protection from arbitrary same-UID host processes; Controller v1 invokes seeding from the host control plane and does not support nested pod control. | | kirocrew pod up --no-token | Boot the pod without minting its member token: the pod.token audit row records skipped with reason=no-token, and --json reports an empty token. See dev-fleet. | | kirocrew pod up --no-embeddings | Boot the pod without the embedding model. Records EMBEDDINGS='0' in the per-pod env file, which makes boot export KIROCREW_SKIP_MODEL_DOWNLOAD=1 into the pod's env only — never the operator's shell, profile or real data home, which keep whatever model they already had. The pod downloads no GGUF and computes no vector; memory and knowledge search answer through the documented keyword fallback, so the instance stays usable rather than degraded. Exists for load-testing ingestion, which embeds per chunk: without the model, chunk count grows while embed compute does not, so a bundle that previously hit a 30-minute wall is drivable and any residual slowness is attributable elsewhere. The setting reaches pod exec through the same pod_context seam, so a command run against an embedding-light pod cannot start the download either; build_pod_env also drops any inherited KIROCREW_EMBED_MODEL_PATH / KIROCREW_EMBED_MODEL_URL alongside the switch, since the switch gates only the download and a custom model path would otherwise load and embed anyway. boot announces the mode in the journal from the env the pod actually runs with (an inherited KIROCREW_SKIP_MODEL_DOWNLOAD=1 is announced as such), and the pod.up audit row keys embeddings=off on the merged env file plus that inherited switch, not on the flag alone. The switch is subsystem-wide, so the pod skips its speech-to-text (whisper) model download too. Read once at boot (recording it against a live pod applies on the next one, and pod up says so) and re-validated from the hand-editable env file, where an unrecognised value leaves embeddings ON — the pre-existing behavior. Because that file is hand-editable, a pod kept around for other work can be flipped persistently by editing its EMBEDDINGS= line and bringing it up again. Deliberately NOT an unreachable KIROCREW_EMBED_MODEL_URL: that spends the downloader's whole attempt budget on requests chosen to fail, and a non-https:// value is ignored in favour of the real CDN, so a malformed sentinel downloads the model the option exists to avoid. | | kirocrew pod up --wait-secs <SECS> | Readiness budget in seconds before pod up gives up (default 90 — a first boot does config migration, CLI staging and .local_secret minting on top of serving, so the default carries margin for a loaded host). Ready means serving and credentialled: a gateway publishes its internal-API credential only after its listener is bound, so an answering /api/health is not yet a usable pod, and up mints immediately after this wait — one budget covers both, so this flag still bounds the whole thing. A pod that was just started must publish a credential that is not the one found on disk beforehand, because a crashed pod's home keeps its predecessor's secret (nothing clears it) and that stale value would otherwise satisfy the wait on its first poll; an already-active pod is not a new generation, so its current credential is accepted as is. Resolution is flag > KIROCREW_POD_HEALTH_SECS env var > default; a malformed env value warns on stderr and falls back to the default rather than making pod up unbootable, and values are clamped to the 5..3600 range so a misconfigured tiny budget cannot fail every boot instantly and an absurd one cannot wedge pod up for hours. Exhaustion is attributed from the LAST observation, not from anything seen once, and the credential verdict additionally requires the serving state to have survived a contiguous poll interval so a gateway that bound in the final second is not blamed for a write it never had time to attempt: still serving with no credential reports that the gateway published none and names BOTH remedies — the journal for a write error, --wait-secs / the env var for a publish that merely landed late; alive but not yet answering says gateway still starting after Ns and names both raise paths — and a gateway that WAS serving on the final poll but for less than that contiguous interval reports the same slow boot, carried as its own verdict rather than as a bare status, since a bare 0 also means "nothing ever answered" and would be resolved from the unit, whose cumulative restart count is non-zero for every pod that ever auto-restarted; and the never became healthy verdict stays reserved for a gateway that actually died. A failed readiness wait has three outcomes, keyed on whether this invocation's own start_pod succeeded and whether the home held state beforehand: started here on a fresh home, the pod is torn down (stop_pod, which deletes the isolated home); started here on a populated home, it is halted — the service stops and the home is KEPT, because pod down's cleanup would delete state nothing restores; not started here, it is left alone. Deliberately not keyed on a liveness probe — is-active is false for a unit in activating or restart backoff, so a pre-existing crash-looping pod would read as one this command created — and such a pod is reported and left for pod down to retire deliberately. Every verdict says so, not just the credential one: the teardown is verdict-independent, so announcing it on one exit would leave the operator of a foreign-port, crashed or slow-booting pod believing up had cleaned up after itself. The notice says which of the three happened — torn down, stopped with its home kept, or NOT stopped — and never that a spared pod is running, because a spared pod whose unit has genuinely failed is not. Both teardown calls have their return code inspected, because the notice is the only evidence for what they did: a stop or a keep-the-home halt that failed leaves the gateway possibly still holding the port, and an operator told it was handled would rerun against a port they believe is free. | | kirocrew knowledge dedup [--apply] | Collapse cross-source duplicate knowledge documents. Without --apply it is a dry run that lists the collapses and writes nothing: it opens the database with SQLite mode=ro (KnowledgeStore.open_read_only), so the constructor's schema migration and orphan sweep do not run, and a library behind the schema is reported (SEL schema_behind), not migrated. --apply takes the ordinary migrating open and performs the deletes. | | kirocrew knowledge stats [--json] | Count the knowledge library: sources, documents and items in total and per source. Read-only: it opens the database with SQLite mode=ro (KnowledgeStore.open_read_only), so it never runs the constructor's schema migration or orphan sweep, and a library behind the schema is reported, not migrated. There is deliberately no flush/rebuild/repair verb beside it. Its LLM-facing twin is knowledge_list_sources, which renders the same aggregate_stats() call (see knowledge §6 and mcp § The MCP-first rule) | | kirocrew desktop metrics/tunnel | Desktop-app helpers. metrics prints the app's recorded per-process CPU and memory metrics (--json, --top, and --path to read a specific artifact; a leading ~ in it is expanded, and an unreadable path or unknown ~user is reported as not found). tunnel --host --local-port --remote-port keeps the app's SSH forward to a remote crew alive in client-only mode; the app spawns it, it exits 2 on a refused host or ports and 0 on SIGTERM, SIGINT or stdin EOF. | | kirocrew cron pause/resume/trigger <id> | Pause, resume or immediately run one job. pause and resume exit 1 with Job not found for an unknown id; trigger exits 1 when the request to the running gateway fails or is refused. | | kirocrew cron preview <script> | Run a script cron locally with real MCP tools; notifications are captured and printed instead of delivered | | kirocrew workspace create/update --dir <name> | --dir is a directory NAME that must resolve to a strict descendant of the data home (~ is expanded first); anything landing outside — and the home root itself, in any spelling — is refused with a SEL denied audit event. Containment, not an absolute-path ban: an absolute path under the home resolves where the relative form would and is accepted. The strict-descendant test is what closes the root case for tilde paths, since the per-call-site root-equality checks compare un-expanded config_dir() / ws_dir. A symlink or junction at the final directory name is refused (CLI exit 1; dashboard 409 workspace_dir_not_a_directory), while linked parent directories are followed. Deliberately stricter than the dashboard's POST /api/workspaces, which accepts an absolute dir anywhere, screened by is_sensitive_path. | | Workspace directory materialization | The declared directory is materialized before its configuration entry is committed. Create does this with one atomic mkdir immediately before the config write, in the same locked section, made relative to the pinned parent (pinned_fs discipline: each parent component is opened O_NOFOLLOW from the path as validation resolved it, so a component swapped for a link between validation and the mkdir is refused rather than followed; where the platform cannot pin, Windows, the create is by name). An existing directory is adopted (pointing a new workspace at a folder the owner already keeps is supported, and is the normal case for an absolute dir); a path that exists and is not a directory is refused, as is a missing parent, rather than fabricating a tree. The created directory is not rolled back when the config write fails: it is reachable only through the entry written in that same section, so a failure leaves an empty directory nothing references, and deleting it would race a concurrent create that has adopted and registered the same path. The same rule holds for a --copy-from create whose config write fails after the copied tree was installed: the tree is left in place and its path is reported (CLI stderr note; handler warning log), because a concurrent create can already have adopted and registered it and deleting it would leave that workspace declared with no directory. Update does the opposite half: it REFUSES a dir that is missing or is not a directory (workspace_dir_unusable; CLI exit 1) instead of creating one, because it names a destination the owner already chose and its transaction carries no rollback. Consequence: "rebind first, create the folder after" is no longer a valid sequence — create makes its own directory, update binds one that exists. Residual, tracked in #10156 rather than chased here: writers that reach the workspaces section without going through these two commands (config edit, keyed config set workspaces.<name>.dir, a backup restore) can still commit an entry naming a missing directory; config set --file refuses a new or changed one (ConfigWriteRefused, exit 1). | | kirocrew computer doctor [--json] | Report computer-use availability: platform support, the keystone primary-enable state, and the advisory macOS Accessibility / Screen Recording probe with a responsible_hint. See Computer Use Commands. | | kirocrew computer apps | List on-screen applications the accessibility layer can address (human-facing twin of the computer_list_apps MCP tool). Gated by the same chokepoint as call — refused while the feature is off or the session is unattended. | | kirocrew computer call <tool> [k=v ...] | Run ONE computer-use tool through the same gated chokepoint the agent uses, and print its reply (debug / reproduction) | | kirocrew computer call --calls '[…]' | Run a JSON array of tool calls in a SINGLE process, so element_index values from an earlier computer_get_state are still resolvable | | kirocrew mcp-cron | MCP server for cron tools (spawned by kiro-cli) | | kirocrew mcp-core | MCP server for spawn, learn, task tools (spawned by kiro-cli) | | kirocrew mcp-computer | MCP server for computer-use tools (spawned by kiro-cli; hidden — registered with no help, so it is in neither listing). A thin shim — it forwards to the gateway over loopback and does no accessibility work itself. | | kirocrew --version | Print version. Every entry (both fast paths and argparse) prints kiro_crew.version_line(): kirocrew <version>, followed by (source checkout, not a release build) when the package resolves inside <repo>/src/kiro_crew (a setup.cfg two levels up) and carries no BUILD_VERSION stamp. There the number is the tree's own literal, which no release lane rewrote, so the note travels with it into a pasted bug report. |

Memory Store Refusals

A kirocrew memory verb that refuses a store writes one line to stderr and exits 1, so a script chaining it with && cannot read the refusal as a success. This covers the store admission that export, import and carve share (an undeclared or malformed store, a path that is not the store's own file, a named store whose database is missing on a read), and the two carve refusals: a store that cannot record facets, and an unknown --kind. Nothing is read or written on any of these paths.

Token Command Output Streams

kirocrew token has a machine-readable stdout contract: stdout carries only the dashboard URL(s), and every failure reason (invalid TTL, gateway not running, gateway not verified on this port, gateway unreachable, gateway refused, empty token) goes to stderr. "Gateway not verified on this port" means the listener on the resolved port could not be proven to be this install's gateway, so the token-minting secret is withheld — distinct from "gateway not running", which means no listener was reachable at all.

A gateway that ANSWERS with an HTTP error is reported as a refusal carrying the gateway's own reason (Gateway refused the token request (HTTP 403): <error body>), never as Could not reach gateway: the 403 /api/token/local returns when it cannot prove the caller's host provenance (a sandboxed caller, an unresolvable peer pid, a different namespace on Linux — see security) names its remedy in the body, and reporting it as a network failure sent the operator to the wrong fix.

/api/token/local refuses at three gates and names the one that refused in a code beside the error. When the code is one the CLI knows, a second stderr line names it and the remedy for that gate (_TOKEN_REFUSAL_REMEDIES): loopback_only -> run on the gateway host as the user that runs the gateway, where the gateway can confirm that user on its socket; invalid_secret -> the secret read is stale, so re-run, and if refused again a second gateway shares the data home: stop it or restart this one; member_owner_token_refused -> run inside the gateway's own host or container (for example docker exec), not from an agent's shell or a sandbox. The gateway's own text for that last gate gives the same remedy rather than pointing back to the command that was refused, so a remote mint, which keeps only the first 300 characters of stderr, still carries that remedy on the first line; the other two remedies are short enough that both lines fit in it. An unknown, missing or non-string code adds no line: the CLI does not guess which gate refused.

A gateway that takes the request but does not answer within the 20 s budget (_TOKEN_REQUEST_TIMEOUT) is reported as busy (Gateway on port N is up but did not answer within 20 s (busy)), also never as Could not reach gateway. A read timeout and a URLError wrapping a timeout both count as busy; a refused connection stays Could not reach gateway, followed by a second line naming the remedy (kirocrew gateway for this login, kirocrew service install for a gateway that survives logout) — nothing is listening, and on a host an installer provisioned without starting a gateway this line, carried back by a remote mint, is the first thing the operator sees. Only the refused class carries it: a gateway that answered 403 or is busy is running. A loop thread starved of the GIL answers in 12-14 s while healthy, and calling that unreachable sends the operator to restart a gateway that works.

The same busy-vs-unreachable split applies to the other CLI calls that reach the local gateway (TimeoutError is an OSError, so a timeout must be told apart from a refused connection or a slow live gateway reads as down). kirocrew spawn list/spawn run, kirocrew logout, kirocrew update approve, kirocrew cron trigger and kirocrew status classify a timeout through the one public loopback_http.deadline_expired seam (beside loopback_urlopen): a read timeout or a URLError wrapping a connect timeout reports the gateway as up but busy, and only a refused connection keeps the not-running remedy. The two kirocrew doctor gateway reads — the Connectivity gateway row and the adaptive-controller row — use a short 2 s timeout, which on native Windows coincides with the SYN-retry delay before a closed loopback port reports a refusal; so they count only a bare read TimeoutError (the connection was accepted and the gateway then stalled) as busy and report a connect-phase timeout as not running, rather than reading a stopped gateway as busy. A call whose request is not idempotent does not advise a blind retry: spawn run and cron trigger carry a request the gateway may act on after the client times out (spawn points at kirocrew spawn list), and update approve carries a single-use nonce the gateway may already have consumed, so its busy line points at the dashboard rather than inviting a re-run.

The contract exists because stdout is parsed, not just read by a human. The remote-mint path (kiro_crew.instances.token_mint.mint_remote_token) runs kirocrew token on a remote host over SSH and regex-extracts the JWT from its stdout. Error prose on stdout would both break the Unix convention and hide the reason from a caller that captures stderr.

Legacy remote handling. Older remotes predate this split and still print their failure reasons to stdout, which made a stderr-only error message degrade to a bare <no stderr>. mint_remote_token therefore also carries a bounded, redacted stdout tail in TokenMintError — appended only when stdout was non-empty, so a current remote keeps the single-stream message shape. Because stdout is the one stream that legitimately carries a token, the tail is token-scrubbed (URL-borne and bare forms) before the generic credential and exfiltration redactors run.

Setup Command

kirocrew setup performs:

  1. Saves KIROCREW_PROJECT_DIR to ~/.kiro/crew/project_dir
  2. Installs agent config to ~/.kiro/agents/kirocrew.json
  3. Prompts for Slack credentials and the slash-command name only when --slack is passed; the default wizard configures no messaging channels and prints a pointer to connect them later
  4. Offers to set up custom domain kirocrew.localhost (macOS/Linux)

The saved project dir enables running kirocrew from any directory.

Slack credentials are checked before they are stored

kirocrew setup --slack asks Slack about each value as it is pasted, so a typo, a revoked token, or a channel ID pasted where the member ID belongs is reported at the prompt instead of surfacing later as a "Slack disabled" line in the gateway log. The app-level token is checked with apps.connections.open (the call the gateway itself makes at startup) and the bot token with auth.test, which also names the workspace — the same two calls, and the same rules, as the dashboard's Slack credential save. The member ID is format-checked against validation.USER_ID_RE first (so C…/B… is refused with no network, and Enterprise Grid's W… is admitted) and then confirmed with users.info; only user_not_found / users_not_found (cli_setup._SLACK_OWNER_REJECTIONS) indict the ID, because any other Slack error (a missing users:read scope, a rate limit) indicts the check.

Three verdicts, and only one of them refuses a value:

  • Accepted — saved, with the workspace or member name printed.
  • Rejected by Slack — reported with Slack's own error code and re-asked, up to three times; if all three are refused the step writes nothing, so a working credential already in .env is never replaced by a broken one.
  • Unverifiable (Slack unreachable, transport error) — a warning, and the value is saved as typed. Being offline never costs the operator the credentials they just typed.

The check runs only when stdin and stdout are both a terminal. Off one, nobody can see a verdict and re-asking would consume the next line of a piped answer file and misassign every remaining answer, so an automated run (kirocrew update re-runs setup with its output captured and stdin on /dev/null) behaves exactly as it did before the check existed. After a successful write the step PRINTS Restart the gateway to pick them up: kirocrew restart, since Slack credentials are read once at startup and tokens written here stay inert until a running gateway restarts. It deliberately does not offer to perform the restart: doing so would drop every in-flight session, and probing whether a gateway is up in order to decide costs a service-manager query and a port probe that can each fail in ways the wizard then has to degrade around — all to save one command the line already names.

First-run Kiro CLI prerequisite onboarding

KiroCrew exposes the same two-step readiness contract on every supported platform: an executable candidate must answer kiro-cli --version, then kiro-cli whoami must confirm authentication. Candidate discovery includes supported fixed locations in addition to inherited PATH; unusable candidates are reported for repair. Setup probes the same first executable candidate ACP will launch, so a stale earlier candidate cannot produce a false-ready result from a different later installation.

  • Missing CLI: the setup page offers an explicit install action on macOS, Linux, and Windows. macOS/Linux download the fixed https://cli.kiro.dev/install; Windows downloads the fixed https://cli.kiro.dev/install.ps1. Every redirect and the final response must remain on the exact cli.kiro.dev:443 endpoint and expected path, with no userinfo, query, or fragment. Redirect destinations are resolved and validated before any request is sent, and the chain is limited to three redirects. Responses are size-bounded and must match a release-pinned SHA-256 digest plus the platform-specific official installer marker. A changed upstream script therefore fails closed until a KiroCrew release updates the pin; the manual official guide remains available. The exact validated bytes stay in memory and run through the fixed system interpreter's standard input. The installer receives a system-only PATH plus explicit HTTP(S) proxy variables, never user-writable executable directories or ambient application credentials. The official installer additionally verifies its downloaded package manifest and artifact checksum.
  • Unusable CLI candidates: the same page identifies that Kiro CLI needs repair instead of treating a spawn failure as a signed-out session. If the upstream POSIX installer would require an interactive /dev/tty replacement prompt (an existing macOS app bundle or Linux ~/.local/bin/kiro-cli), automatic repair is disabled and the user is directed to the official guide. A candidate that already runs is directly usable for sign-in regardless of install source; the post-installer attestation file is now write-only bookkeeping and does not gate credential access.
  • Installed but signed out: the setup page names the commands the USER runs and runs nothing itself — kiro-cli login for a personal account (Builder ID, Google, or GitHub), or kiro-cli login --use-device-flow --license pro for organization SSO, which prompts for the organization's start URL and region. Both are backend code constants rendered verbatim in a <code>, never catalog values, because a translated command cannot be typed. Both tiers are named because the browser portal the bare command opens presents a free Builder ID as a peer of organization SSO; Kiro Crew does not detect which tier applies, so the gate describes the choice and the user makes it. Sign-in completion is observed only through the read-only kiro-cli whoami probe.
  • Browser dashboard: the authenticated SPA gate operates on the gateway host, not the browser host. This covers native Windows source installs, Linux gateways, and browsers connected to another machine.
  • Desktop shell: the shell starts or reuses the gateway first, then displays the same gateway-served setup gate as a browser. Remote gateways are therefore checked on the remote host rather than the desktop host.
  • Offline test harness: the explicit gateway --test-mode bundle injects a ready prerequisite state so deterministic fake-ACP smoke and Playwright suites do not depend on a developer machine's Kiro installation, identity, or Linux sandbox capabilities. Ordinary gateway invocations always use the real probe/install/login service.

The setup client cannot supply a command, URL, argument, or output path. The web API exposes only fixed install/login mutations to the configured owner (or the signed local-app / local-startup identities before an owner exists). Authenticated non-owner dashboard users receive only a redacted readiness bit: they enter the dashboard once ready but cannot see host state/output or operate setup. App tokens remain denied. Electron has no separate installer/login IPC or subprocess implementation. Filesystem discovery runs off the event loop. Version probes use a minimal noninteractive environment with no proxy credentials or desktop-session IPC. They use the strict OS sandbox and additionally hide the configured data home, ~/.kiro/crew, ~/.kirocrew, and every known Kiro identity store. Any candidate that runs --version is eligible for whoami and device login — trust is "it runs, and it has a valid login", not install source, owner, or fixed path (KiroCrew is not the authority on where Kiro CLI is installed, and its self-updater rewrites its own bytes as the user). Auth calls execute the user's installed binary IN PLACE, never a private copy of its bytes — a multi-call Kiro CLI resolves its sibling subcommand executable relative to its own path, so a copy strands it (see security.md). Sign-in itself is delegated to Kiro CLI: login --use-device-flow runs in the standard sandbox against the user's real home, with only the Kiro Crew data homes hidden, and the CLI writes its own credential store exactly as it does from a terminal. KiroCrew stages nothing and publishes nothing, so no staged state has to be reconciled after a failure, timeout, or cancellation. The credential-minimal temporary home populated only with Kiro identity JSON and SQLite files survives as an opt-in read-only mode — one that also hides unrelated AWS, SSH, GitHub, and Kubernetes state — and its temporary directory is removed on every exit path. Any allowlisted live identity artifact that is a symlink, non-regular, oversized, unreadable, or disappears while being captured aborts that mode before the command runs. Every probe emits a critical invoked SEL event before spawn and a best-effort terminal event without argv, candidate paths, output, or environment values. Installer and login timeouts cover process exit and output-pipe draining. On POSIX, a private supervisor remains the process-group leader after the real command exits and keeps the group safely addressable until all descendants close or are terminated. Windows cleanup opens an exact primary-process handle before yielding after spawn and completes an initial descendant snapshot even when the launcher exits immediately. It then retains exact child handles and continues discovery from every live child, so late helpers remain supervised and identifier reuse cannot target an unrelated process. Numeric parent edges are accepted only when exact-handle creation and exit times prove that the child was created during the parent's lifetime, and the check is repeated across both tree snapshots. The primary root and each retained child root receive one final snapshot after becoming inactive, so a child spawned immediately before its parent exits is not lost between polls. Failure to anchor or validate the primary process, create a Toolhelp snapshot, or complete any process enumeration fails the operation closed. Ordinary pipe/task errors follow the same terminate, reap, cancel, and cleanup path before another action can start.

An auto-created config.json alone does not mark first-run setup complete; a successful authenticated probe writes the setup marker, while existing session/history state preserves established-install migration behavior. Fresh installs receive the full-screen flow. Established dashboards remain navigable and fully usable when signed out — no controls are paused. Readiness is probed once at gateway boot and thereafter only on explicit user action, so no path runs a subprocess probe on the message hot path; the authoritative logout signal is the ACP attempt's AcpAuthRequired. The SPA refreshes ready status every 30 seconds, retains cached readiness across transient refetch errors, and invalidates prerequisite state after access-cookie refresh. POSIX group membership ignores zombie records, which cannot retain pipes or perform work, so an unreaping PID 1 cannot hold the supervisor forever. The supervisor source is captured eagerly at import for replacement resistance; if it is missing or unreadable, gateway import still succeeds and each affected POSIX setup operation fails cleanly before spawning a command. Sandbox launcher/profile preparation and cleanup are worker-thread operations and do not stall the asyncio gateway loop.

Setup and ACP launch share the side-effect-free kiro_cli resolver on every OS. Status requests never publish a discovered path by mutating KIROCREW_KIRO_BIN. Both setup discovery and ACP launch enumerate the same candidates — inherited PATH, the interpreter Scripts directory, package-manager dirs (incl. the Windows Program Files Kiro-Cli tree and winget/scoop/user installs on PATH), and an operator override — and accept a runnable candidate wherever it lives, since trust is "the CLI runs". ACP launch runs the resolved candidate in place on every platform — never a copy of its bytes. Setup discovery and ACP resolution therefore agree on Windows, so a winget/scoop install is never sent to a redundant reinstall.

When a previously completed setup is no longer ready, the dashboard remains fully navigable and fully usable — nothing is paused and no sign-in chrome is shown. A signed-out CLI is reported by the turn itself as an actionable kiro-cli login error card (see modules/learn-cron-dashboard.md § "The dashboard does not guide the user to sign in"). Only the endpoints that act BEFORE a turn still return 503: the poll-driven kiro-cli spawn sites (/api/models, /api/sessions/usage) and the destructive reruns (regenerate, edit-resend, rewind), which rewrite persisted history up front.

Custom Domain

After credentials, kirocrew setup offers to add 127.0.0.1 kirocrew.localhost to the system hosts file so the dashboard is accessible at http://kirocrew.localhost:5476:

  • macOS/Linux: Uses sudo tee -a /etc/hosts for safe append

Skipped if kirocrew.localhost is already present or user declines.

Cloud Command

kirocrew cloud is a human installer/control-plane surface for running KiroCrew on the user's own AWS EC2 instance. Provisioning and teardown are not LLM-facing tools. AWS credentials are resolved by the AWS CLI; KiroCrew stores only profile, region, and the most recent instance tag in cloud.json.

kirocrew cloud launch runs a six-step wizard: check AWS reachability, explain permissions, choose whether to keep an existing deployment or create a new one, choose an instance size when creating a new stack, deploy or resume the CloudFormation stack, sign in the remote kiro-cli, and open the dashboard through SSM port forwarding. Launch is resume-safe by default: if cloud.json contains a last_tag whose stack still exists in the same saved profile/region, rerunning interactive launch offers to keep/resume that stack or create a new installation. If cloud.json is missing or stale, launch discovers existing kirocrew-* CloudFormation stacks with cloudformation:ListStacks and offers a choice to resume one or create a new installation. kirocrew cloud launch --new is the explicit escape hatch for creating a separate new stack. --yes keeps a single or saved existing stack; if multiple unsaved stacks exist it fails closed instead of choosing one arbitrarily. For a new launch, the generated tag is written to cloud.json before the long CloudFormation deploy starts, so an interrupted provisioning run can be found on the next launch attempt.

Launch and connect require the local AWS Session Manager plugin for AWS-StartPortForwardingSession. If session-manager-plugin is missing, cloud launch prompts to install AWS's official package for the current local platform (macOS .pkg, Debian/Ubuntu .deb, or RPM Linux .rpm) before the wizard reaches sign-in/dashboard tunneling. --yes accepts this installer prompt. cloud connect performs the same check and installer prompt before opening the dashboard tunnel. If installation is declined or fails, the command exits non-zero and tells the user to retry after fixing the local prerequisite.

The instance-size picker supports arrow keys in an interactive terminal (↑/↓, j/k, digit shortcuts, Enter to select) and falls back to the numbered prompt for non-TTY input. Ctrl-C must interrupt prompts and long AWS subprocesses; unhandled cloud-command interrupts return exit code 130.

Remote Kiro sign-in prefers the device-code flow over SSM. The launcher starts kiro-cli login --use-device-flow as a background process on the instance, captures the URL/code from its log, and leaves that same process alive while the wizard polls for completion. It must not kill that process after scraping the prompt or start a second hidden device-code flow. If device-code startup does not produce an actionable URL, launch falls back to the Google/GitHub callback flow automatically: it starts kiro-cli login on the instance with FIFO-backed stdin, captures the printed loopback callback port, opens an AWS-StartPortForwardingSession from the same local port to the remote port, sends the Enter continuation back to the remote CLI, then opens or prints the local browser URL. The temporary callback tunnel is closed after the sign-in poll completes. In headless local terminals, browser auto-open is skipped and the URL is printed for manual opening.

kirocrew cloud connect mints a dashboard token over SSM, opens an AWS-StartPortForwardingSession, waits for the local tunnel port to accept TCP connections, and opens or prints the local dashboard URL. If the tunnel port does not become reachable, the command reports failure, does not present the dashboard URL as usable, and does not keep a dead tunnel process open. If final dashboard opening fails during cloud launch, the instance remains running but launch returns non-zero and tells the user to rerun kirocrew cloud connect after fixing the local SSM tunnel issue.

Config Command

kirocrew config manages ~/.kiro/crew/config.json:

  • get — prints full effective config (with defaults resolved) or a single dot-path value
  • set key value — sets a value with auto type detection (bool/int/float/JSON/string). Rejects unknown leaf keys.
  • set --file path — replaces entire config from a JSON file. File read routed through hooks.safe_read_file() (blocks sensitive paths).
  • edit — opens config in $EDITOR (supports args like code --wait via shlex.split). Creates default config if missing.

All write paths emit SEL audit events (config_get, config_set, config_set_file, config_edit).

Gateway Auto-Create

kirocrew gateway creates ~/.kiro/crew/config.json with defaults if the file doesn't exist. Does nothing if it already exists.

Secrets Command

kirocrew secrets maintains the encrypted secret vault. The vault's store/list/delete surface is the dashboard Settings → Secrets tab (the /api/secrets routes); the CLI carries only the migration importer:

  • import — migrate plaintext credential lines from the data-home .env into the vault. Dry-run by default (reports what would migrate, changes nothing); pass --apply to store the secret(s) and rewrite each migrated .env line to a secret://KEY reference. Only the credential keys whose every reader resolves a reference are migrated: the Jira tokens (JIRA_API_TOKEN and per-host JIRA_TOKEN_<HEX>) and the channel secrets (loader.VAULT_CHANNEL_CREDENTIAL_KEYS); every other key is left untouched. There is no --file option — the importer reads only the data-home .env, so a caller cannot point it at an attacker-controlled file.

Once stored, a secret is referenced from mcp.json as secret://NAME and resolved into the bound server's environment at spawn time. See secrets-env.md for the end-to-end flow. Secret values are write-only — there is deliberately no command that reads a stored value back.

Verbosity

Flag Level What you see
(none) WARNING Errors only
-v INFO Session lifecycle, context %, compaction
-vv DEBUG ACP events, message updates, full traces

Interactive Mode

  • Prompt: you>
  • Exit: exit, quit, /exit, /quit, :q, Ctrl+D
  • Streaming output printed as chunks arrive

Tool permission requests

A backend that routes tool decisions over ACP holds the turn open until it gets an answer, so the stream consumer must respond — an ignored request is not a missed prompt, it is a turn that never ends.

Answering one is an authorization decision, so the CLI is a security surface, not just a prompt. Every request runs the same ladder, in this order:

permission_request
  → HookManager.on_tool_call        (sensitive paths, denied commands, ceiling ∩ profile)
      deny → SEL "denied" → reject_tool → stderr notice          [not overridable]
  → may this invocation ask?        (command mode AND both streams a TTY)
      no   → SEL "denied" → reject_tool → stderr notice
  → prompt the human
      exactly "y" (or legacy "a") → SEL "approval_pending" (critical) → approve_tool(always=False)
                  → SEL "allowed", or "rejected_transport_floor" when the transport refused it
      "t" → stdout notice (no session trust here) → SEL "denied" → reject_tool
      "o" + a typed reply → SEL "denied" (user_replied) → reply steered into the turn → reject_tool
      anything else → SEL "denied" → reject_tool

The gate is fed the event's non-model-authored fields (tool_kind, raw_tool_params, shell_command, is_shell, mcp_server_name, tool_name), not just title: for a shell tool the title may be an LLM-authored description, so a dangerous command behind a benign label is exactly what keying on the title alone lets through. The CLI identifies itself as session_key="cli_chat" (SEL source cli) with the resolved agent, which is what lets the gate resolve ceiling ∩ profile rather than the ceiling alone. No second copy of the sensitive-path or denied-command rules lives in the CLI.

The hook result is used as a deny ceiling only: TOOL_DENY rejects, and both TOOL_ALLOW and TOOL_AUTO_APPROVE still ask the human. This consumer answers permission requests; it does not carry the dashboard's trust and auto-approval semantics, and honouring TOOL_AUTO_APPROVE here would add a second execution path with no human confirmation. Asking more often than the dashboard is the safe direction.

Mode stdin+stdout TTY Behaviour
interactive REPL yes Prompt. Exactly y (or the legacy a) allows once; exactly o denies with a typed reply to the agent; anything else denies.
interactive REPL no Deny automatically, notice on stderr, stdin untouched.
-m single message either Deny automatically, notice on stderr, stdin untouched.

Both conditions are required, and neither implies the other. -m is documented as Single message (non-interactive), so a terminal does not license a prompt there — a script wrapped in a pty would otherwise block on a question nobody is watching for. And a prompt nobody can see is a hang, not consent, so the REPL still needs a real terminal on both ends. The mode is passed explicitly rather than inferred from a TTY check, because only the caller knows which mode runs.

The keys match Kiro CLI's own prompt. kiro-cli chat asks [y/n/t] (crates/chat-cli/src/cli/chat/mod.rs), so this prompt uses the same y to allow and n to deny, and a person moving between the two tools does not have a habitual y read as a refusal. Matching is exact and case-insensitive after trimming: y (or the legacy a) allows, and yes, yank or a blank line deny.

Answer Result
y Allow this call once
n, blank, EOF, anything unrecognised Deny
a Allow once. The pre-Kiro-CLI key, honoured but not advertised; removal after one release is tracked in #23475
d Deny. The pre-Kiro-CLI key; it needs no special case because every unrecognised answer denies
t Deny, with a notice that trusting a tool for the session is not available here
o Deny, and send a typed reply to the agent (see below)

Kiro CLI's t approves the call and trusts that tool for the rest of the session. The CLI has no such grant on purpose (see below: no persistent approval), so t denies rather than silently approving once, which would leave the person believing later calls are trusted. The notice tells them to answer y per call.

A shell call shows the command it is asking about:

Permission required: Run a helpful script
Command: git status --short
   [y] allow once  [n] deny (default)  [o] other (reply to the agent):

o answers with a typed reply instead of a bare approve or deny. Exactly o (case-insensitive, surrounding whitespace ignored) asks a second question, Your reply (the tool will not run; blank to just deny):, and the call is then refused with the person's words attached ("use the staging bucket instead", "show me the diff first"). It never approves. The order is the deny path's:

  1. SEL audit as denied with error="user_replied" (a blank reply or EOF is an ordinary user_denied). The reply text itself is not audited — it is the person's message, not a decision.
  2. The reply is steered into the running turn while the request is still unanswered, on the same channel as the host deny notice (kiro_crew.deny_notice), gated on supports_refusal_steer. ACP's permission response carries only an option id, so free text cannot ride on the answer itself. The message opens with [Kiro Crew: the user replied to your permission request], not the [Kiro Crew host notice] tag: this one is a user action. The tool title is redacted; the reply is passed as typed.
  3. reject_tool. kiro-cli's "User denied tool execution" is true here, so no host notice is owed.

If the backend has no refusal-steer channel, or the steer fails or exceeds STEER_NOTICE_BOUND_SECS, the reply is not dropped: _send_and_print prints a one-line stderr notice and sends it as the next message once the turn ends. Only a real prompt can produce a reply, so -m and non-TTY runs are unchanged.

title is LLM-authored prose, so approving on it alone is consent to a description rather than to what runs — the same reason the gate keys on shell_command. The command is redacted with the two security helpers, collapsed to one line, and capped with an explicit ... [truncated]. Local paths are deliberately not redacted here: this is the operator's own terminal, and seeing the real path is part of the consent.

A call that names a file discloses that file. A trusted tool identity says WHICH tool runs, not what it runs against, so fs_write under a benign title is consent to a verb:

Permission required: Tidy up the notes
Tool: fs_write
Path: /home/tester/thesis.md
   [y] allow once  [n] deny (default)  [o] other (reply to the agent):

The path is read from the request's own raw_tool_params, under the same path / file_path / filePath spellings hooks._SEARCH_DENY_ARG_KEYS accepts. Sharing the spellings is the point: the gate already denies a sensitive path or a write-protected config path read from those keys, so what is left for a human to judge is exactly the ordinary valuable file no rule speaks for — and a prompt reading a different field than the gate inspects would let the two disagree about what the target is. Rendered like the command (sanitised, one line, capped), and shown for any call that carries a path rather than only an edit-kind one, because the kind is agent-influenced and disclosure can only inform the decision.

Absence of a path is not a refusal. Most builtin calls legitimately act on no file — a memory write, a tag creation — so denying whenever a path cannot be found would refuse them all to close a gap that exists only for tools which name one. A non-string value is treated as absent rather than raised on: raising would leave the request unanswered, which is the hang this path exists to end.

Beyond the command and the path, the whole tool input is still not shown — this is the question, not a detail panel.

Terminal controls are neutralised on this surface. Every untrusted string the permission UI prints — the title, the command, and a gate reason — goes through _for_consent, which redacts as above and then replaces ESC, the C0 set (U+0000–U+001F), DEL (U+007F), and the C1 set (U+0080–U+009F) with spaces before collapsing whitespace, so the result is always a single line. Lone UTF-16 surrogate code points (U+D800–U+DFFF) are removed by the same boundary: they are not Unicode scalar values, so even a strict UTF-8 stream cannot encode them. The result is then round-tripped through the destination stream's codec with backslashreplace. UTF-8 terminals retain ordinary Unicode; a strict cp1252 or other legacy Windows stream sees inert ASCII escapes for characters it cannot represent. This is an authorization surface: OSC 52 writes the clipboard, and CSI can move the cursor and erase what is drawn, so a model-authored title could otherwise repaint the question a human is answering and hide what is being approved. Scope is the permission prompt only — ordinary streamed model output is printed raw by _send_and_print and is unchanged, which is a surface-wide rendering question rather than part of answering a permission request.

An authorization-boundary failure is itself a refusal. If the shared gate raises, the CLI records gate_failed best-effort and rejects the request. If TTY detection, prompt rendering, or prompt reading raises, it records prompt_failed best-effort and rejects. The transport response is sent before any explanatory notice, so a closed or unencodable output stream cannot leave the backend waiting. This does not change cancellation: Ctrl-C still aborts the session and provider teardown owns the pending request, because waiting on a possibly wedged rejection transport would swallow the cancellation.

The audit write never runs on the event loop. sel() opens the audit log and replays it to recover the running HMAC chain, so the first permission of a fresh chat pays a filesystem cost inside the call — an unbounded one on slow or corrupt storage. The decision coroutine shares its loop with the ACP reader and stderr-drain tasks, exactly as the gate call does, so the audit is awaited through asyncio.to_thread for the same reason: a blocking write here would stop draining the backend and freeze the turn the audit is about. The one exception is the cancellation teardown, which keeps the synchronous call because awaiting anything there would swallow the CancelledError being delivered.

There is no "always allow". A persistent approval asks the backend to stop sending permission requests for matching calls, and a request that is never sent is a call this ladder never runs and never audits. The dashboard offers it because its tool pipeline re-gates every call; this consumer does not.

The answer is matched exactly, not by first letter: a prefix match reads abort as an allow. Blank line, EOF, and any unrecognised word all deny.

Denial is not an error: the request is answered, the turn runs to completion, and the exit code is unchanged. Only the existing transport failures (AcpTimeoutError, AcpError) exit non-zero. A turn the backend never finished (stop reason timeout or stale_recover) is one of them: the text was already printed as it streamed, so the timeout notice follows it and the exit code is 1.

Every decision is written to the SEL log before the matching approve_tool/reject_tool, so a transport failure cannot erase a decision already made. For an allow, that record is the critical approval_pending row; the outcome row follows approve_tool:

decision outcome error
gate denied denied hook_deny
gate raised before a verdict denied gate_failed
execute-kind request has no verified command denied unverified_shell
nobody to ask denied noninteractive
prompt availability/render/read failed denied prompt_failed
user allowed (before approve_tool) approval_pending —
user allowed, transport accepted allowed —
user allowed, transport refused the approval rejected_transport_floor —
user allowed but the critical approval_pending audit failed denied audit_unwritable
user denied / blank / EOF / unrecognised denied user_denied
session cancelled with the question open denied session_aborted

error is a stable machine code, never the gate's reason: a reason names the path or command that triggered it, and an audit record must not restate the thing it protects (log_tool_invocation does not redact for its callers). The audited tool_name is the canonical _meta.kiro identity when the backend supplies one, falling back to a redacted title — an audit trail keyed on prose the model wrote can be steered by the model being audited.

Responses go through provider.approve_tool() / provider.reject_tool(). The CLI never reads the advertised options: those ids are backend-specific and the ACP layer owns the mapping.

stdin ownership

The prompt is read on an owned daemon thread through a private duplicate of the stdin descriptor, not on the event loop and not through sys.stdin. The turn is parked inside an active stream — the ACP runtime holds a reader task on the backend's stdout and a drain task on its stderr — so a read on the loop thread would stop draining those pipes until the human answers.

A cancelled prompt ends the session. A blocking terminal read cannot be retracted: cancelling the await frees the coroutine, not the thread, and that reader stays parked and takes the next line the user types. So cancellation marks stdin poisoned and propagates; _require_usable_stdin then refuses at every later entry point — a second permission prompt and the REPL's own you> alike — rather than racing the abandoned reader for keystrokes. There is no input broker and no recovery path: the abandoned reader can only outlive the session, never compete with a live prompt.

Teardown must not await the backend. The request in flight is left unanswered and audited as session_aborted, because answering it means awaiting a transport: CancelledError has already been raised once and nothing re-delivers it, so a wedged reject_tool would leave the Ctrl-C that asked for the teardown unable to land. The provider is shut down with the session, so the unanswered request dies with it. StdinPoisonedError carries the same rule.

That last sentence is a guarantee, not an expectation: provider.start() hands back a live backend process, so _chat runs the whole message/REPL lifecycle under try and calls provider.shutdown() from finally. A normal return, an exception, and a cancellation raised through a permission prompt all tear the backend down; without it a Ctrl-C at the prompt would exit leaving the backend running with nothing owning it. Cleanup never swallows the cancellation — a failing shutdown() is logged rather than raised, because replacing the exception already propagating would discard the very CancelledError the teardown exists to clean up after — and gc.collect() is nested inside its own finally so a raising shutdown cannot skip it.

Before provider.start(), _chat runs the bundled audit hook's size sweep once (shell_audit_log.rotate_shell_audit_log on the resolved data home, via asyncio.to_thread). The default postToolUse hook appends every execute_bash call to <data home>/audit.log from inside kiro-cli, whichever process launched it, and the sweep that bounds that file otherwise runs only on the gateway's session cleanup loop (see session.md, "Shell audit log cap") — which this process never starts, so an install that only ever runs kirocrew chat would never rotate it. Running the sweep at chat start, before the backend that will append is spawned, bounds the live file on entry to every session; on such an install it overshoots the cap by at most one session's shell activity. The sweep never raises by contract, a file under the cap costs one stat and creates nothing, and the data home is resolved in this process — with data_home(), the resolve-only helper, since config_dir() re-runs start-of-process maintenance and is barred from async code (#1057, guarded by test/test_no_config_dir_in_async.py) — because KIROCREW_HOME is what the hook's own path expansion reads.

Context Tracking

After each message, checks provider.context_usage_pct():

  • >= autocompact_pct (default 70%): compact → shutdown → restart provider, reset counter. The compact step is skipped when messaging.commands.compact_unsupported_backend(provider) names the backend (it cannot serve /compact); the shutdown and restart still run
  • >= autocompact_pct - CONTEXT_WARN_MARGIN_PCT: warning printed to stderr. Relative, not absolute: the compact arm is tested first, so an absolute warn level at or above the threshold would be unreachable

CLI compaction is blocking (single-user, acceptable).

Entry Point

console_scripts in setup.cfg maps kirocrew → kiro_crew._bootstrap:main.

Gateway asyncio child watcher

_install_child_watcher() runs once on the gateway command path only (not chat, doctor, or any other subcommand) and must be called before asyncio.run, on the main thread. It replaces CPython's default thread-per-child ThreadedChildWatcher — whose os.waitpid reaper threads can starve the event loop when many kiro-cli/MCP children die at once — with a single-descriptor alternative:

Runtime Installed watcher
Linux, os.pidfd_open probe succeeds (kernel ≥ 5.3) PidfdChildWatcher
Linux, probe raises OSError/AttributeError SafeChildWatcher (SIGCHLD)
macOS / other non-Linux Unix SafeChildWatcher (SIGCHLD)
Python ≥ 3.14 (child-watcher API removed) none — no-op
SafeChildWatcher unavailable (e.g. Windows) none — default retained

Python 3.14+ is a deliberate no-op. CPython 3.14 removed set_child_watcher, PidfdChildWatcher, SafeChildWatcher, and ThreadedChildWatcher; the Unix event loop reaps children itself with a single non-thread reaper, so the loop-starvation wedge this installer exists to prevent cannot occur. The function short-circuits on hasattr(asyncio, "set_child_watcher") — probed by capability, not sys.version_info, so a runtime that still ships the API keeps the mitigation. Without that guard the Linux pidfd branch raised AttributeError and kirocrew gateway died before binding its port, while every other subcommand kept working.

Gateway stdout is line-buffered off a terminal

platform_compat.ensure_line_buffered_stdout() runs once on the gateway command path only, as the first statement of the dispatch branch, before the first status line prints. The gateway's 👻 status lines (Checking for updates…, Probing MCP servers…, Kiro Crew gateway running — press Ctrl+C to stop, the update-check outcome, Shutting down…) are plain print() calls. CPython line-buffers sys.stdout only when it is a terminal; a pipe or a file gets a block buffer that drains when it fills or when the interpreter exits cleanly. Every service launcher hands the gateway that kind of stdout — the journal socket under systemd, the launchd gateway.log file, the Desktop supervisor's log descriptor, _spawn_detached_gateway's own gateway.log — so without this seam a status line reaches the log when the process stops, stamped with the stop time, or never after a SIGKILL or an in-app os.execv (which flushes nothing), while logging records from the same process arrive on time.

The contract:

  • When sys.stdout.isatty() is false, the stream is reconfigured with line_buffering=True. Each print() reaches the launcher's log as it is printed, so the log stamps it with the time it was printed, and a kill or an exec loses nothing already printed. One write(2) per line; the gateway prints a few dozen lines per lifetime.
  • A terminal is not touched. It is line-buffered already, and the seam skips even the flush reconfigure would do.
  • sys.stderr needs nothing: CPython line-buffers it on every attachment, and ensure_utf8_console()'s Windows fallback wrapper is built line-buffered.
  • A stream that cannot be reconfigured — absent under pythonw, closed, or not a TextIOWrapper (a plain object a launcher left up a spawn chain, a test's StringIO) — is left as it is. The gateway never fails to boot over its console.
  • Independent of ensure_utf8_console(), which keeps the encoding job and runs first, at the top of main(). Whichever shape it leaves stdout in on Windows (reconfigured in place, or re-wrapped — the re-wrap is already line-buffered), this seam reconfigures or finds nothing to do.
  • ONE seam, deliberately: flush=True on each print() is a rule every new print has to remember; PYTHONUNBUFFERED=1 in service_environment() reaches newly generated Linux units only, while installed units, launchd, the Desktop app and a detached gateway keep block buffering; and converting the prints to logging changes what the log carries. What is printed, and where, does not change.

Pinned by test_platform_compat.py::TestLineBufferedStdout (a non-tty TextIOWrapper holds the bytes of one unflushed print(); a tty stream is not reconfigured; a stream without reconfigure does not raise) and test_cli_main_entry.py::TestSeedDispatch::test_gateway_dispatch_line_buffers_stdout_before_the_gateway_starts (the dispatch calls the seam once, before the gateway coroutine exists).

Linux gateway heap reclamation

The event-loop heartbeat offers a self-gating maintenance object a tick every five seconds. At most once every ten minutes on Linux, it reads current RSS directly from procfs. When RSS is at least 1.5 GiB, it asks glibc malloc_trim(0) to return wholly-free heap pages to the OS and logs reductions of at least 16 MiB. The probe and allocator call run in a worker thread, after the dashboard socket has bound, so maintenance cannot delay readiness or block the event loop. Healthy gateways remain below the threshold and do no allocator-wide work.

The heartbeat waits at most two seconds for a pass. A timed-out worker keeps the single in-flight slot until it exits, preventing repeated submissions or a watchdog-triggering wait when the executor is saturated. Missing ctypes, non-glibc libc, failed current-RSS probes, and rejected trim calls are best-effort no-ops: reclamation must never stop the liveness heartbeat or make the gateway unavailable. macOS and Windows are unchanged.

Live-target bootstrap

On the gateway command path only, immediately after _JAILED_COMMANDS attestation and before the --seed handler:

if args.command == "gateway":
    from kiro_crew.service.live_target import maybe_reexec
    maybe_reexec(sys.argv[1:])

maybe_reexec reads the live-target pointer (config_dir() / "live_target.json") and, when it names a different checkout, os.execves into that checkout's own kirocrew binary. This runs before anything is written to $KIROCREW_HOME, before the gateway lock is acquired, and before any socket is bound — so exec'ing away leaves nothing half-done. It is fail-safe: an absent, unreadable, malformed, or stale pointer (missing binary, same image already running, or KIROCREW_LIVE_EXECED marker already in env) causes the function to return, and the currently-installed build boots normally. A bad pointer can never leave the host with no gateway.

Gateway only — a plain CLI invocation (kirocrew doctor, kirocrew chat, etc.) keeps running the install the user typed, not a worktree someone made live.

Environment Variables

Variable Purpose
KIROCREW_HOME Override config/data directory (default ~/.kiro/crew)
KIROCREW_PORT Override dashboard port (default 5476, validated as int at CLI startup)
KIROCREW_PROJECT_DIR Override agent config/skills directory
KIROCREW_WORKSPACE Override workspace root directory

For local dev:

  • macOS/Linux: bin/kirocrew (POSIX shell wrapper); source setup.sh adds bin/ to PATH

The wrapper sets KIROCREW_PROJECT_DIR and routes to the right runtime based on install type:

  • One-liner install (install.sh clones the repo into ~/.kirocrew-app/): if a sibling .venv/bin/kirocrew exists, the wrapper execs it directly.
  • pip editable install (pip install -e .): the console_scripts entry point resolves directly.

Setup Scripts (First-Time Bootstrap)

setup.sh (macOS/Linux) auto-installs all dependencies from scratch using public tooling only.

Note: Windows is not supported.

Install order:

  1. Node.js (via ensure-node.sh)
  2. Optional tools (git-lfs, ffmpeg for voice)
  3. kiro-cli (npm i -g)
  4. kiro-cli login (guided authentication)
  5. Frontend build (npm install && npm run build)
  6. Backend build (pip install -e .)
  7. PATH setup + shell profile persistence
  8. kirocrew setup --agent-only (install kiro-cli agent config)
  9. Optional Slack credential configuration (kirocrew setup --slack)

Each step checks if the tool is already installed and skips if present.

Doctor Checks

The list below is an index of what doctor checks, not its print order; the print order is the one test_cli_doctor_refactor_report.py freezes.

  1. kiro-cli binary in PATH. On the KAS bundle route (agent_sdk.kas_bundle.kas_bundle_route(): KAS selected AND agent.kas_bundle on) an absent kiro-cli is ⏭ not installed; not needed with no install hint, never an issue, because nothing on that route spawns it; the engine the route runs is reported in the KAS backend section (_report_kas_bundle: version, pin: against this release's KAS_PIN_VERSION -- ⚠️ only when KIROCREW_KAS_VERSION picked another, other installed versions listed for rollback -- the install.json path and its two entry points, the spawn argv, the vault as the only auth owner with Crew's own sign-in remedy). The per-harness kas auth: row (doctor_checks/agents._doctor_agent_auth) follows the same route: the vault's state decides it and it never falls through to the kiro-cli store, so a bundle host without kiro-cli reads ⏹ Kiro Crew vault; not signed in plus that remedy rather than could not check. The relay route keeps every kiro-cli row unchanged.

  2. Node.js: node on PATH at or above MIN_NODE_VERSION (22.12.0, constants.py); below it doctor prints ❌ with the remedy and records the node issue, so doctor exits 1

  3. Source directory (Kiro Crew checkout) and git repo. A missing git binary is an issue only when derive_capability() says git updates this install; a wheel updates by re-running its installer, so there it prints ⏭

  4. Agent config installed. A missing kirocrew.json prints ⏭ only when gateway_lock.lock_holder positively reports that no gateway holds the lock, because the gateway writes the spec at start; a running gateway, or a lock probe that cannot answer, keeps it an issue

  5. Config values (provider, model, approval mode, dashboard port)

  6. MCP tools: @kirocrew-cron and @kirocrew-core in tools, allowedTools, and mcpServers — auto-fixes missing entries, except from an instance that must not own the shared agent home (_decline_shared_agent_home), which writes nothing and reports the skipped repairs and any ceiling-forbidden grant as issues

  7. Python environment: verifies the running interpreter (the venv interpreter for a pip install -e . install) and that the gateway's core dependencies (websockets, slack_sdk, aiohttp) import; the supported interpreter floor is pyproject.toml's requires-python. Every install command this step prints names the RUNNING interpreter and is gated the same way as step 8's (extras.pip_install_command_for behind extras.pip_install_channel_available), because each one is for a module this process imports, so a bare pip can resolve to an interpreter the gateway never imports from. The sqlite fts5 remedy is the one place the gate hides only part of the message: the pip command is withheld where it cannot run, while "use a Python whose SQLite was built with FTS5" always prints, since that is the only remaining fix in exactly those environments. The import path row reports whether the standard library resolves from the interpreter's own tree: stdlib_shadow.find_shadowed_stdlib() locates each probed stdlib name with find_spec (never an import) and reports one that a launch-directory, PYTHONPATH or site-packages entry supplied — a ~/concurrent/ directory in the home the service unit runs from, an unpacked backport on PYTHONPATH, a stdlib-named pip package. A shadow IS an issue and names the module, the resolved file and the sys.path entry with its class, because the failure it otherwise produces is a TypeError from deep inside asyncio with nothing pointing at the directory. The same probe runs at both process entries (python -m kiro_crew and the kirocrew console script) BEFORE the CLI is imported and refuses to start with exit 2 on a shadow, so doctor normally reaches this row only clean; the row then says whether the launch entry is on sys.path at all (-P / PYTHONSAFEPATH keeps it off, and every bundled launcher passes -P), which is the note that tells an operator why the same stray directory is harmless from one cwd and fatal from another. Detection is fail-closed towards "not shadowed": an entry the classifier does not recognise as one of those three roots is never reported, so an unusual layout can only escape the check, never be refused by it. The tz data row reads the timezone rules behaviourally, because a system zoneinfo tree exposes no version the stdlib can read: it resolves America/Vancouver with ZoneInfo.no_cache at a December 2026 instant, where IANA tzdb 2026b and later give UTC-7 and older data gives UTC-8. Older data is an issue (cron expressions and clock-time at_time values in that zone resolve an hour late, and nothing else notices, since every zone name still resolves); missing data is an issue too. The remedy names the data source in use: a zone file on zoneinfo.TZPATH means the operating system's timezone package, otherwise the tzdata Python package (setup.cfg declares tzdata>=2026.2 on every platform, the first release built from 2026b), and it ends with a gateway restart because a running gateway keeps every zone it already loaded

  8. Vector memory (in-process embeddings): vendored llama-cpp-python runtime importable, embedding model file present (downloads in background on gateway start; when absent, a light HTTPS-reachability probe of the resolved model URL runs); embeddings are always-on (embeddings: ✅ always-on). On platforms with no vendored native libs (_platform_libs_dirname() returns None, e.g. linux/armv7l or win32/arm64 — Intel Macs are supported via macos_x86_64), the runtime line reports ⏹ unsupported platform … — memory uses keyword search and is NOT counted as an issue (designed degradation per embeddings_native.py); only a load failure on a supported platform flags embedding runtime. When that failure is an INCOMPLETE shipped payload, doctor additionally names the absent files (Missing native libs for <platform>: …, from embeddings.verify_vendored_libs()) and says it is a packaging defect rather than an unsupported platform — the two are indistinguishable in ctypes' own Shared library with base name 'llama' not found, which reads as an architecture problem and misdirects diagnosis. When LLAMA_CPP_LIB_PATH holds an operator override (embeddings.operator_lib_path_override() — set, non-empty, and not shaped like a Kiro Crew install's bundled directory), doctor reports THAT directory as the thing to check instead (mirroring the loader's exemption): the libs load from there, so blaming the bundled tree would send the operator to reinstall a package they are deliberately not loading from. A bundled-shaped value is one inherited from another Kiro Crew process, so the entry prelude removes and records it before any thread or child exists. Doctor reports the bundled tree and adds a lib path: note naming the value (likewise for an empty value) with the remedy "point it at a directory of your own" — a note, never an issue. It reads the live environment first and falls back to dropped_inherited_lib_path() when the prelude has already removed the variable; a process that skips the prelude leaves the value in the environment, where the loader ignores it without writing the environment. A faiss: line reports whether the optional FAISS accelerator is importable — never an issue on any platform (episodic recall falls back to the stdlib cosine scan); when absent it suggests installing faiss-cpu and prints an Install: line naming the RUNNING interpreter (extras.pip_install_command_for), because a bare pip on a packaged or minimal install resolves to an interpreter the gateway never imports from, so the wheel lands out of reach and the next run repeats the same advice. That line is printed only where the command can actually run (extras.pip_install_channel_available, shared with the dashboard's install card): on the bundled desktop interpreter, on an interpreter with no pip module, and on a PEP 668 externally-managed interpreter outside a venv, doctor names no command at all, because a pip install into the code-signed bundle breaks later launches and is discarded on the next app update

  9. Speech-to-Text (optional): recognizer, selected model and audio-decoder presence when STT is enabled. Supported desktop releases bundle and build-gate the recognizer plus the pinned audio-only FFmpeg executable; a missing decoder there is a corrupt payload whose remedy is reinstalling Kiro Crew, never Homebrew/Winget/Apt. The macOS Intel release bundles no decoder, so stt.decoder.bundle_carries_decoder() is false there and doctor prints the brew install ffmpeg hint a source install gets. Source installs use kirocrew[voice] for the recognizer and a fixed system FFmpeg path for compressed audio. Windows preserves its non-fatal ⚠️ marker for an optional-extra gap so enabled-by-default STT cannot block gateway startup; on macOS/Linux a missing active runtime still flags an issue.

  10. Slack credentials (optional)

  11. Discord (optional): the channel's enabled flag, whether a bot token is present (never any part of its value), the three allow-lists, the privileged Message Content intent, the live connection, and the install URL. Blocking issues are enabled-without-a-token, an empty discord.allowed_user_ids (the transport fails closed, so every message is denied while it is empty), a thread or channel allow-list with Message Content OFF, and a reachable gateway whose Discord connection recorded a connect_error. The intent state comes from discord/intent_probe.py: one read-only GET /oauth2/applications/@me that decodes Discord's application-flags bitfield as a tri-state per intent PAIR (enabled / limited / disabled, since a limited grant still delivers the data) and degrades to unknown on any failure rather than aborting the report. Granted-but-unused Server Members / Presence intents are hardening notes, never issues. The install URL comes from discord/install_url.py, the OAuth-authorize analogue of Slack's app manifest: named permission bits OR'd to 309237711936 for a thread-capable install (the number discord-integration.md publishes), and none at all for the recommended DM-only install

  12. WhatsApp (optional): printed whether or not the channel is enabled, because a channel that is invisible in the preflight is the failure this section exists to catch. When enabled it reports the optional neonize extra, checked with find_spec and never imported (importing it loads a ~19 MB ctypes CDLL plus protobuf descriptors, and a health check must not initialize the subsystem it inspects, nor construct a client), and whether the linked-device session store exists at <data home>/whatsapp/session.db, resolved from the same expression the channel opens it with so the two can never describe different files. A missing extra IS an issue: the channel is enabled, cannot start, and the fix is one offline pip install. An absent store is a ⚠️ note and never an issue, because pairing is a QR scan served BY the running gateway, so failing here would break the documented kirocrew doctor && kirocrew gateway chain at the one moment the operator has to start the gateway to make progress. Group membership is not knowable offline, so the section reports the configured count and the gateway logs the unmatched JIDs on connect

  13. kiro-cli connectivity (kiro-cli --version). On the KAS bundle route the row is engine: instead -- the installed engine's version and Node (agent_sdk.kas_bundle.installed_engine_label(), the same spelling the diagnostics bundle's versions.txt kas_engine: line uses) -- and kiro-cli is not spawned, present or not.

  14. Gateway running status. When the gateway answers, a running: row prints the version the gateway process serves next to the on-disk version (kiro_crew.__version__, the same value as the Runtime section's kiro_crew: row, which prints on venv and non-venv installs alike). The running version comes from token-exempt GET /api/health, whose version field handlers.core._liveness_payload adds for a direct-local caller with a served Host (the doctor's 127.0.0.1:<port> request); /api/status cannot supply it because it requires the dashboard token. A mismatch is an issue (gateway restart needed) with kirocrew restart as the remedy; an absent or unreadable version prints the row as unknown and is not an issue

  15. Loop-stall crash dump attribution: when a dump with thread stacks is less than 7 days old, the section prints the wedged main-thread frames and then an attribution: block from stall_attribution.attribute_dump(dump, config_dir()), read from disk with no gateway involved: the surface the loop was serving (named by the OUTERMOST recognised frame of the wedged stack, so a cron turn that passes through the Slack gateway module still reads as cron), the gate frame when the stall is inside the permission gate, and — for a cron surface — the job, joined by PID to the in-flight markers under <data home>/cron-running/ (cron_inflight: written when a run starts executing, cleared on every finally, so a surviving marker whose PID is dead is a run a hard exit interrupted). Markers are counted per JOB, not per file (the newest start is kept for each job): markers of exactly one job matching the dump's # PID: name that job and yield recommended: kirocrew cron pause <id> plus the job's current pause state from crons.json (job_pause_state_from_disk); markers of several jobs list the candidates and say one cannot be named; none says so; a non-cron surface is named and implicates no job. Every line is evidence or the one action it supports — the check never guesses a job. An attributed job is also added to the issues summary, unless the dump is superseded (below).

    A dump is superseded when a later LOCAL session's own pre-created, still-header-only file sits after it (crash_dump_store.dump_superseded): that session started and has not wedged, so the stall describes a past incident rather than the running gateway. A superseded dump prints its stacks and attribution unchanged and adds one line saying a later session started after it, but contributes NOTHING to the issues summary — neither the dump line nor an attributed job — so one stall stops producing a ❌ Fix these issues verdict for the following week on a gateway that has been healthy since. Ordering alone does not decide it, because the shipped Restart=always unit replaces a wedged gateway within seconds and its successor's header file would supersede every stall almost immediately: the downgrade additionally requires the stall to be at least _STALL_CURRENT_SECS (24 h) old and to be the ONLY stack-bearing dump on record (dumps_with_stacks() < 2), so a recent stall and a repeating wedge both stay current faults. A successor counts only when it is readable, header-only, and names this PID domain — a newer dump carrying stacks is a second stall, and a shared data home's foreign-domain file says nothing about a local restart.

  16. Cron job health: names cron jobs that auto-paused after repeated failures (Fix: kirocrew cron resume <id>) and jobs whose last run errored while still scheduled (Fix: kirocrew cron trigger <id>), with an aggregate count each and the named list capped at 5 plus a +N more tail. Read-only — doctor never resumes or triggers a job, because an auto-pause after the job's auto_pause_limit() consecutive failures (default 5, 0 = never) is usually load-bearing and lifting it silently would hide the problem the run is meant to find. The scan is cron.unhealthy_jobs_from_disk(), which reads crons.json directly rather than via the gateway API: the dashboard's per-job err badge and the gateway's hourly failure re-alert both run inside the gateway, so neither can report a wedged one, and that out-of-process property is the point of this check. A job the user paused explicitly is never reported (only auto_paused is a health signal, and both flags can be set at once since pausing an auto-paused job preserves auto_paused). Silent on a healthy store and on a fresh install with no crons.json. A store that EXISTS but yields no readable job list — unparseable, non-UTF-8, wrong shape, or holding no usable record — is reported instead, because the scheduler can load nothing from it and every job has stopped; reporting that as a clean bill of health would reproduce the silence this check exists to break. Before either, the section names every copy gateway startup moved aside (cron.cron_store_quarantine_copies(), the crons.json.corrupt-<stamp> files under cron-history/quarantine/) as a quarantine: row with the restore steps (fix the copy, kirocrew stop, move it back over crons.json, which replaces tasks added since, start again), and counts it as an issue. No corruption aborts the run

  17. Pod user-bus reachability (optional): on Linux, runs the same systemctl --user is-system-running probe used by runtime.require_backend() at pod verb entry. Low-level unit queries keep cheap in-process gates and do not re-run the probe. Probe and unit operations resolve systemctl through platform_compat.trusted_system_bin() and spawn only that absolute path; a PATH executable is ignored, and no trusted executable is an unclassified fail-closed error. A provably absent bus address returns no user session bus without spawning systemctl; this pre-spawn check is the only source of backend absence. Every spawned failure is an unclassified operational error except a positive permission-denied match, which reports sandboxed away. Neither may become PodBackendAbsent. The row retains any raw systemctl diagnostic. Permission denied names a generic outer sandbox and tells the operator to run pod commands from a host shell. The check is advisory and never changes doctor's exit code because pods are an optional development feature. On macOS, Windows, or a host without systemctl, the row is not applicable.

  18. Live-target pointer (Linux only, silent when fit): reports a live_target.json that will make the launcher REFUSE every agent spawn — a symlink (dangling or resolving), a non-regular file, or a second hard link. sandbox._materialize_live_target_mask_target is fail-closed on those shapes because a bind mask covers a NAME rather than an inode, so any of them leaves a writable path to the bytes the gateway execves into inside every agent namespace (the full contract is in security, Live-target pointer). This section exists because that refusal is correct but arrives too late and in the wrong place: the operator's only notice was a failed spawn plus a logger.warning in the gateway log, and the shapes are ORDINARY operation for something else on the host — cp -al, rsnapshot and other hard-link snapshot tools raise link counts on config files, and a dotfile manager may keep the pointer as a link into its own tree — so nobody did anything wrong and the first symptom is that every agent stops starting. The read is sandbox.live_target_pointer_unfitness(), which classifies the pointer the way a spawn would WITHOUT spawning, and doctor prints that function's own sentence rather than a paraphrase, so an operator who sees this line and later hits the refusal reads one diagnosis instead of two (pinned by the drift guard in test_live_target_pointer_visibility.py). An unfit pointer IS an issue and changes doctor's exit code — but only on a host that actually confines a spawn: _materialize_live_target_mask_target runs on the launcher path, which wrap_argv reaches only when it WRAPS the child, so on a host that hands back an unwrapped command the pointer is unfit and NOTHING is currently refused. The question is asked with sandbox.credential_mask_applies, which lives beside those branches so a caller whose argument depends on the mask cannot drift from them, and which counts BOTH unwrapped outcomes — the off tier and a host with no available backend — where reading the configured mode alone sees only the first. Doctor still reports the pointer there, as a latent outage that begins the moment the host starts confining spawns, but drops the "spawns will be REFUSED" wording, says only that this pointer is not what stops a spawn here and points at the Sandbox section for whether agents start at all — the predicate answers False for a host that hands the command over unwrapped AND for one with no backend, which may be refusing every spawn for its own reason, so claiming "nothing is refused" would be a second false statement in place of the first — and does not count it as an issue; claiming a current outage there would be the same false promise as reporting this on macOS, and confinement is simply the second axis of that one rule. A predicate this process cannot evaluate fails towards reporting the refusal. A probe that itself fails reports could not check and is not an issue, because doctor must not turn its own failure into a verdict about the host — that includes a pointer that EXISTS but cannot be lstat'd, whose OSError propagates out of the probe rather than reading as fit, so an unclassifiable pointer is never rendered as silence the operator would read as a clean bill of health. Every value doctor prints in this section is terminal-escaped by the formatter that built it (see security, Live-target pointer), because a symlink target is attacker-chosen bytes. Linux only: a macOS Seatbelt profile denies by path rule and needs no mount target, so naming it there would promise a spawn outage that cannot happen. Absent is fit — the launcher publishes the absent-equivalent stub for it.

  19. Masked credential leaves (Linux and macOS, silent when clean): reports a masked leaf whose bytes are a credential and which carries a second HARD LINK, because the launcher refuses every agent spawn on that shape — a mask binds a PATH rather than an inode, so the second name reaches the same bytes unmasked for reading and for writing (the full contract is in security, the masked-leaf alias pass). It exists for the same reason as the Live-target pointer section above and answers the same objection: cp -al, rsnapshot and other hard-link snapshot tools raise link counts on files in the home as ordinary operation, so the condition arrives without anybody doing anything wrong and the first symptom is that agents stop starting. The read is sandbox.masked_credential_leaf_aliases(), which stats the leaves without spawning and reports a data home it cannot resolve as nothing rather than as a fault. A leaf whose every other name was LOCATED is masked for each spawn and nothing is refused, so doctor prints the find -samefile remedy alone (sandbox._masked_leaf_alias_search_hint); a leaf with a name the pass could not locate is the one a spawn refuses on, and doctor prints that leaf's own refusal sentence from sandbox._masked_leaf_multilink_detail rather than a paraphrase, so an operator who reads this line and later meets the refusal reads one diagnosis instead of two. Both go through _print_wrapped so the remedy survives on one line. An aliased leaf IS an issue and changes doctor's exit code only on a host that actually confines a spawn (sandbox.credential_mask_applies, which counts both unwrapped outcomes — the off tier and a host with no backend — exactly as the pointer's section does) AND only for an unlocated name in the live data home; elsewhere it is reported as a latent outage that begins the moment the host starts confining spawns, without the "will be REFUSED" wording and without counting as an issue. An unreadable mode reports the leaf rather than hiding it. A probe that itself fails prints could not check and is not an issue, because doctor must not turn its own failure into a verdict about the host. Linux and macOS, because both launch paths run the refusal: a Seatbelt profile denies by PATH rule, which says nothing about a second hard link to the same inode, so sandbox_exec_argv calls the same pass the namespace launcher does and a macOS operator meets the same refusal. Windows has no confining launcher, so the probe is skipped there rather than promising an outage that cannot happen.

  20. Agents directory: reports the aged orphaned atomic-write temps and stale backups a sweep would reclaim in the shared kiro agents directory, plus the skill-view census (doctor_checks/resources._doctor_agents_janitor; see acp-client). Report only: deletion is left to the boot sweep, and backups are counted only when agent.sweep_agents_backups is on.

  21. Installed skill currency: names installed skills that are behind the source tree the sync selects for them, edited locally, or unverifiable (doctor_checks/install._doctor_skill_currency). It makes no network call, so "behind" means out of step with this install's own source, never with a remote revision. Bytecode caches (__pycache__) are left out of that comparison, so a copy synced by a source checkout and checked by an app build of the same sources reads in step. POSIX only; on Windows the check does not run.

  22. Cron script sources (silent when nothing deployed has a source): for each crons/*.py that an installed skill ships under scripts/ by the same name, reports whether the deployed copy agrees with that asset, diverged from it, or could not be compared (doctor_checks/install._doctor_cron_script_sources over skills_builtin_provenance.deployed_cron_script_sources). A deployed script with no asset of its name is left out: most script crons are authored in place, and whether one ought to have a source is not a doctor finding. Divergence is an issue but has no direction, since a stale deploy and a deliberate local edit look the same on disk, so doctor overwrites neither side and the hint says what each side is (the path printed after DIVERGED is the installed skill's copy, whichever installed skill it came from, and the crons/ file is what the cron runs) rather than naming a copy recipe, which no built-in skill documents. When several skills ship the name, agreement with any of them is in sync. Names and paths print through _safe_display.

  23. Hook auto-approve platform scope: reports whether a name-based auto-approve can be satisfied on this host, read off the same name_grant.platform_scope_notice and name_grant.windows_environment_refusal helpers name_grant.name_grant_refusal consults, so the row cannot describe a posture the check does not hold. Three answers, all printed with the source explanation because the only other trace is a decline line in gateway.log per invocation and what a user would have to read to tell the states apart is the source of name_grant: ⏹ declined on this host (windows_lookup_not_modelled) when platform_scope_notice names the one Windows host state the model cannot run in — Windows could not report where the user's Documents folder is, so whether a PowerShell profile runs before the command cannot be established, a property of the host and not the user's configuration; ⚠ declined while a PowerShell profile exists (ambiguous_env) when a per-user PowerShell profile is present at one of the paths derived from Documents, printed with the file that is doing it so the user can act on it (kiro-cli starts the shell without -NoProfile, so that profile runs before every command and a function it defines resolves ahead of any program on PATH — the same threat BASH_ENV poses on POSIX); and ✅ name grants can be satisfied on this platform otherwise, which is what macOS and Linux always print because neither can enter the Windows-only refusals above. Never an issue and never part of the exit code: each fail-closed answer is the intended posture, since the POSIX tokenizer does not preserve a backslash path and cmd.exe searches the command's own directory before PATH, so resolving names loosely there is the planted-shim attack the refusal exists to stop. The same platform-scope classification bounds the log on the surfaces that consult it: name_grant.should_log_decline gates the human-facing warning to once per session, for a code that describes the platform rather than the command, at the agent hook webhook, the dashboard chat runner, llm_helpers, the messaging driver, the Slack handler, the shared tool_permission ladder that the subagent runner and the task runner go through, and the Slack gateway's reads-mode and heartbeat auto-approve (slack/gateway_runtime/turn_approvals.py). channel writes no warning line, only the audit row. name_grant.log_decline itself writes the SEL audit row for every decline on every surface, because declining is a security decision and only the human-facing line is ever deduplicated.

  24. ACP runtimes (Linux only, advisory): how many ACP runtimes are alive, whether the running gateway owns them, and what their backends cost in CPU, so a runtime that outlives its session and keeps a core busy is named in the health pass instead of found with ps once the host is overloaded (doctor_checks/resources._doctor_acp_runtimes). A runtime is a root kiro_session_pids.txt records (session_pid.tracked_session_roots), counted only while a process with that pid and the recorded start identity is alive, plus a harness outside every recorded root that the reaper's own report calls untracked (session_pid._is_untracked_managed_agent_orphan against both pid files) and that names this data home in KIROCREW_SPAWN_HOME, the pairing the leaked-runtime reclaim makes, so a pod's or a second install's runtimes and a user's own kiro-cli are left out. An untracked runtime the running gateway is still an ancestor of counts as that gateway's. Its backend is the root plus each path from it down through wrappers into a run of harness processes (session_pid._cmdline_names_a_harness): the sandbox launcher and the kiro-cli/kiro-cli-chat pair, never the tool commands or MCP servers below the harness, so a session running a build does not read as a spinning backend. CPU is the change in each backend's stat utime+stime (ProcStat.cpu_ticks) across a one-second window, and a process that exits or is replaced inside the window adds nothing. Owner is the running gateway when it recorded the runtime; another live process when the recorder is not the gateway but is still the runtime's ancestor (kirocrew chat records its own runtime under its own pid, and asking the tree rather than whether the pid exists keeps a recycled recorder pid from reading as an owner); and nobody when the recorder is not an ancestor, or for an untracked runtime the running gateway does not parent. A backend at or above 25% of a core is named by pid, share, age and owner; one nobody owns is also named on a no owner: row, because no turn can be in flight on it. Doctor cannot see whether a turn is in flight on a runtime the running gateway owns, and says so. No command line is printed, since argv can carry a token. The census reads at most 65,536 processes from the host table and walks at most 4,096 per runtime, the tree cap checked at every insertion; anything past either cap is counted on a read cap: or tree cap: row, and a process a capped walk refused is still recognised as inside its runtime by its parent edges. Never an issue and never part of the exit code; an unreadable registry or process table, or a probe that raises, prints a skipped line. Off Linux the row says it was not measured.

  25. Ledgers (advisory): one count of every entry kirocrew ledger-sweep lists with its default 30-day window (ledger_sweep.DEFAULT_OLDER_THAN_DAYS): finished stores plus unreadable, linked or unaddressable stores listed for a human. The ledgers: row says the command lists N ledgers (or nothing), without claiming every entry is finished or idle, and names the command to review them (doctor_checks/workload._doctor_ledger_backlog). It calls the read-only ledger_sweep.scan(), never purges and prints no per-ledger detail, which stays in the dry run. It takes no issues list, so a listed ledger never fails doctor, and a ledger root that cannot be read prints one could not check row instead of ending the run.

  26. Service launch (advisory): the service runs: row follows the installed service definition (service.controller.installed_unit_path) to the program it finally executes, the first word of the systemd unit file's last ExecStart= (an operator's drop-in is not read) or, on macOS, the exec target of the launcher the plist's ProgramArguments[0] runs, and prints its resolved path (doctor_checks/install._doctor_service_launch). A definition whose program is, or leads through, the shared ~/.local/bin/kirocrew launcher follows whatever a source clone's install.sh or kirocrew setup repoints it at, so the service runs that clone from its next restart. When the resolved program lies in a Kiro Crew source checkout (a directory with both .git and src/kiro_crew) and the host also has the managed wheel install (crew-venv-current/bin/kirocrew, or the legacy crew-venv, from wheel_engine_layout.managed_venv_layout), the row warns, names both paths and says to run service install with the wheel install's kirocrew, or to use Dev Fleet's Make live for a deliberate checkout. A checkout with the Dev Fleet live-target pointer set is reported as one and not warned on, and so is a checkout on a host with no managed wheel install, which is a development host. Silent when no service is installed; a definition whose program cannot be read prints a could not read row. Read-only, never an issue and never part of the exit code.

One flag is a MODE rather than a check and short-circuits before the list above runs, because it does not answer "is this install healthy": --bundle collects the redacted diagnostics zip and prints no health report. It ends with a prefilled Open a GitHub issue link whose version, channel dropdown answer and create-time channel: label all come from ONE resolver, release_channel.provenance() (shared with the dashboard's Report-a-problem link, which prints the same fields plus the free-form ones): the version is the PUBLIC release version — a repackager's four-part BUILD_VERSION stamp such as 0.7.0.5 is folded onto 0.7.0 (changelog.release_of_build), while the release pipeline's own spellings (0.7.0-insider.4, 0.7.0rc7, a nightly stamp) are the public identity and stay — and the channel is the lane the build can PROVE from three sources that must agree: the $KIROCREW_HOME/channel record when it names a lane, a prerelease marker in the installed distribution's metadata version when it describes the same release (a repackaged insider build keeps its rc marker there after the stamp has removed it from __version__; PLAIN metadata proves nothing, because the desktop lanes pip-install the checkout and stamp only __version__, leaving pyproject.toml's bare version in the dist-info of every lane), and __version__ itself unless it is a build stamp, which says nothing about its lane. No claim, or claims that disagree (a stable record over a promoted rc build, a lane switch not yet updated onto), prefills the form's own Not sure and attaches NO channel: label, because a create-time label outlives whatever the reporter later picks and a guessed Stable is exactly how packaged insider reports arrived mislabelled (#13168). The raw stamp, the distribution version and the record are recorded in the bundle's private versions.txt and manifest.json instead. Doctor is otherwise read-only, which is why the ledger cleanup sweep is its own command (kirocrew ledger-sweep, see the command table and session-work-ledger) rather than a second mode here.

Where each row lives. cli_doctor._doctor is the orchestrator: it prints its sections in one fixed order, threads one issues list through every section, and turns that list into the closing ❌ Fix these issues: line with exit status 1, or ✅ Kiro Crew is ready!. Sections print as they run rather than being collected first, so on an interactive terminal a probe that hangs still leaves every earlier row on screen. Most rows live in kiro_crew.doctor_checks, one module per family: render (the escaping, indent and wrapping helpers the sections share), agents, mcp, confinement (the sandbox verdict and the shapes that refuse a spawn), access (session signing, hook auto-approve, credentials), install, services, resources, workload, channels and features (vector memory, speech-to-text). cli_doctor.py keeps the rows the orchestrator composes itself (Platform, and the Dependencies, Agent, Runtime and Connectivity rows built from the values it threads onward, among them the venv-interpreter and kiro-cli --version probes test/test_spawn_audit.py keys by cli_doctor.py::_doctor), the embedding-model URL probe the redactor registry names, the constants the rows share, and every import they read, the ACP imports the agent-sdk boundary baseline counts among them. The Model section and the model-pin audit live in cli_doctor_parts/model_section.py, MCP Tools and MCP Governance in cli_doctor_parts/mcp_sections.py, the host probes the families and the orchestrator call in cli_doctor_parts/host_probes.py, and the KAS relay rows in cli_doctor_parts/kas_relay.py; new work for each goes to its module, and the spawn-audit keys and the hardened-reads inventory name the owner file that holds each probe and read. kiro_crew._facade_compose.compose runs every function those owners define on cli_doctor's module globals, so its __module__ stays kiro_crew.cli_doctor and a patch of cli_doctor.<name> reaches it; an owner imports the facade only for type checking, holds no module-level value and carries no agent-sdk boundary edge, and test/test_cli_doctor_parts.py pins the composition. kiro_crew.cli_doctor stays the one import path and patch target: a family reads every function, class, value and project module the facade binds through the facade at call time (a family binds no project module by name but cli_doctor and its sibling families either: it loads on its first read through the facade, which can fall inside a test's rebind of that module, and test/test_cli_doctor_refactor_family_reads.py pins it; a section that imported a name inside its own body keeps doing so), every name the module held before the move still resolves on the facade (a moved one as the family's own object, with a write there forwarded to the family, so mock.patch(..., create=True) must not target one), and a section this move extracted from _doctor is patched on its own family module. The families load only when a health report runs, never on import kiro_crew.cli or for --bundle; the cli_doctor_parts owners load, composed, with the facade.

Update Command

kirocrew update pulls the latest source and rebuilds:

  1. git fetch, then git reset --hard <oid> from KIROCREW_PROJECT_DIR, where <oid> is origin/<branch> resolved ONCE right after the fetch (git rev-parse --verify origin/<branch>^{commit}). Every later judgment — "already up to date", the divergence counts, the interpreter floor below — and the reset itself name that pinned commit rather than the ref, so a fetch run concurrently from another terminal can move the ref but never what this command checked and applies. A pin that cannot be resolved (or times out) is refused with a non-zero exit before anything else is judged. The reset only runs for a FAST-FORWARDABLE checkout — behind its upstream and not ahead of it (git rev-list --count --left-right HEAD...<oid> shows behind > 0, ahead = 0) — mirroring the dashboard check's verdict, because the hard reset discards committed local work and the uncommitted-changes prompt does not cover it. A DIVERGED checkout (both sides non-zero) is refused with a non-zero exit and a rebase-or-merge instruction; --force is the explicit opt-in that lets the reset discard the local commits. An ahead-only checkout has nothing to pull and is reported as up to date without resetting (even under --force — the flag lets a real update discard diverged work, it does not delete commits when there is nothing to update to). An unreadable comparison refuses (fail closed). Uncommitted tracked changes still prompt before being discarded — and because that prompt makes the gap to the reset unbounded, the divergence count is re-taken immediately before the reset and refuses commits that appeared while the update was waiting (committing the listed edits in another terminal to rescue them is the natural response to the prompt, and is exactly what would otherwise be reset away). Only HEAD can move in that window, so the re-check needs no second fetch.

    Interpreter floor of the pinned revision, judged before the tree moves. After the fast-forwardable verdict and before the uncommitted-changes prompt, dep_sync.incoming_python_floor_breach() reads requires-python out of the pinned commit itself (git show <oid>:pyproject.toml, then setup.cfg — never the working tree, which is still the OLD revision) and compares it to the interpreter this command runs under. A floor the venv does not meet refuses with a non-zero exit and a remedy naming the venv, the interpreter the revision wants (uv venv --python <floor> --seed <venv>) and the reinstall command, and the checkout is left where it was. Step 3's pip install -e . enforces the same floor, but by then the reset has already moved the tree to code this interpreter cannot import — the running gateway keeps serving the old revision from memory while every lazy import reads the new files, and every later run repeats the reset and the refusal. A revision with no floor file does not fire; a floor file git could not READ (IncomingFloorUnreadable: unresolvable ref, git failing, timeout) refuses too, because on a pinned revision "could not read" is the one way left for that stranded state to be re-admitted. The same gate guards POST /api/update and the gateway's unattended auto-apply.

  2. Rebuilds the dashboard via build_frontend_sync() (npm; non-fatal on failure). Non-fatal also means non-destructive: npm ci deletes node_modules before it installs, so the tree is moved aside and restored unless the install succeeds (node_modules_txn.NodeModulesBackup). A failed install therefore costs the rebuild, not the dependency tree -- which matters because the registry needed to rebuild one is usually what was unavailable. The gateway's unattended auto-apply takes the async sibling and is protected the same way. Before the rebuild, the optional kiro-cli backend is self-updated (kiro-cli update, pinned to a known install directory, best-effort) -- except on the KAS bundle route (agent_sdk.kas_bundle.kas_bundle_route(): KAS selected AND agent.kas_bundle on), where kiro-cli is not part of what runs, so the step is skipped and the printed line says so. The engine is Kiro Crew's own install, laid down by kirocrew kas install and not by this update, so the line also names kirocrew kas install for a release that changes the pin; the unattended auto-apply logs the same reason and command, and the gateway's boot-time "kiro-cli is outdated" warning (_warn_if_kiro_cli_outdated) is skipped on that route for the same reason. The relay route and every other harness keep the step as it was.

  3. Reinstalls backend via pip install -e .

  4. Refreshes the agent config, then, best-effort, asks a running gateway to re-check for updates (POST /api/update/revalidate) so its update badge reconciles at once. The local secret rides _owner_verified_secret_urlopen (see Owner-verified secret sends), so it is written only after the connected peer is proven to be this install's recorded gateway; there is no separate port-ownership pre-check. This runs on every platform, Windows included (TCP arm). No gateway, a refused peer (_GatewayPeerRefused), a refusal or an error prints at most one line and never changes the exit code.

A wheel install (no git checkout) takes a different path by install shape (cli_server._update_wheel): a managed venv updates through its own engine; a pipx install re-runs the installer (not supported on Windows); a plain pip install in an environment the user manages is refused with exit 1 and the in-place upgrade command plus a gateway-restart command to run instead, or a note when no signed upgrade command can be named (platform/update_layout.non_managed_pip_update_hint), because re-running the installer would add a second copy.

Client Port Resolution

kirocrew token / status / logout / stop / restart / spawn / artifact must find the port the gateway is actually bound to. port_resolution.resolve_client_port() (re-exported by cli_server) resolves it in this order, first hit wins. The MCP stdio servers (mcp_core / mcp_computer) resolve their gateway API base through the same helper — lazily, on the first gateway call, and cached for the process lifetime — so a loopback callback and a client CLI command always agree on which gateway they are talking to:

  1. An explicit --port N flag (0 counts — the check is is not None).
  2. KIROCREW_PORT, when it parses as an int. Deliberately above the bound export: an explicitly-set KIROCREW_PORT is how a caller retargets a child at a DIFFERENT gateway — pod exec builds a client env with KIROCREW_PORT=<pod-port> while the inherited KIROCREW_BOUND_PORT still names the spawning live gateway, and the bound value outranking it would walk pod token/status/logout into the live plane. (build_pod_env additionally scrubs KIROCREW_BOUND_PORT outright.)
  3. KIROCREW_BOUND_PORT, when it parses as an int — the port the parent gateway actually bound, exported once, the moment the port is reserved (dashboard.server._reserve_dashboard_port); only the headless start_api_server path exports it after listening. Never persisted — service_environment() deliberately does not capture it.
  4. A port explicitly written in dashboard.url. A portless URL (http://my.host) is not a port choice: parse_dashboard_url() substitutes 5476 for the server's benefit, so the client re-splits the URL and only accepts the port when it was actually named.
  5. The sole gateway-owned run-marker. A running gateway records <data-home>/run/gateway-<port>.bin (see kiro_crew.instances.run_marker, written for the SSH token-mint), so its filename already advertises the port. A client with nothing configured reads the marker names — never the file contents — and uses that port. Two guards keep it from being a guess:
    • Ownership, not reachability — clear_marker() only runs on graceful shutdown, so a crash leaves a stale marker behind and an unrelated process may since have bound that port. Discovery only picks the port; the secret-bearing sends then prove the connected peer on their own (Owner-verified secret sends), so this guard is not what keeps the local secret from a squatter. It keeps discovery from naming a port that a squatter now holds, which a bare "is something listening" probe would do. A command-line check is not enough either — argv is attacker-chosen, so a listener started as /tmp/kirocrew gateway would pass it. _gateway_owns_port() therefore requires three things, none sufficient alone:

      1. the pid recorded in run/gateway-<port>.pid (written 0600 inside the 0700 run/ dir, which is on the is_sensitive_path floor, so neither another local user nor an agent file tool can write it);
      2. that pid must be among the pids listening on the port (platform_compat.find_listening_pids), which is what makes a stale recorded pid harmless;
      3. that pid must be owned by the calling uid (platform_compat.process_owner_uid) and look like a KiroCrew process. The uid check is what closes pid recycling into a foreign user's process; argv is retained only as defense in depth.

      It fails closed at every step: no sidecar, an unparseable pid, a pid that does not hold the port, an unresolvable uid, a missing lsof / netstat, or a throwing lookup all deny, and discovery is skipped. A same-user attacker is out of scope by construction — they can already read .local_secret under their own uid.

      On non-POSIX platforms the step denies outright. process_owner_uid cannot report an owner on Windows, and a KIROCREW_HOME writable by another user would let them replace both the marker and the sidecar with a forged listener — the file-permission argument that carries requirement 1 stops holding there. So discovery is skipped rather than approximated: Windows users keep --port / KIROCREW_PORT, exactly where they were before this fallback existed, so nothing regresses.

    • Ambiguity — with several gateways up there is no basis to pick one, so the step refuses, prints the candidate ports and the --port / KIROCREW_PORT hint to stderr, and falls through.

  6. _DEFAULT_PORT (5476).

Steps 3 and 5 are what make a single gateway started on a non-default port (kirocrew gateway --port 6776) reachable from a bare kirocrew token with zero configuration; before it existed, the client hit a dead 5476 while the marker naming the live gateway sat unread. Config-load, URL-parse (including a non-string dashboard.url, which raises TypeError rather than ValueError), and discovery failures all degrade to the next step — a client command never dies on a bad config or an unreadable data home.

Because restart resolves a port and then polls it for readiness, it passes the resolved port to the detached replacement (_spawn_detached_gateway(port)). The child re-resolves independently, so without that the replacement could bind 5476 while the parent waited on the discovered port.

The marker is written for every dashboard-serving gateway, including a source-tree python -m kiro_crew launch with no console script beside sys.executable: in that case the .bin file is written empty, which is inert for the token mint (its shell clause requires a non-empty executable path) but still advertises the port for discovery. The pid always goes to the separate .pid sidecar — never into the marker, whose contents mint cats and execs. A --slack-only gateway serves no dashboard, so it writes no marker — there is no client port to discover.

Writing a marker also prunes markers naming other ports. A gateway is a singleton per data home (gateway.lock), so any other port's marker is residue from a run that crashed before clear_marker() could fire. Unpruned, they accumulate one per port ever used and each costs every client command an extra listener lookup, making discovery slower the longer a dev box churns ports. The live gateway is the only writer and knows which port is current, so it is the right place to reap them; pruning is best-effort, and the ownership check still rejects anything it misses.

CLI→gateway requests are built against the literal 127.0.0.1, never the name localhost. On a dual-stack host localhost can resolve to ::1 first, and the listener verification is address-agnostic (lsof -ti TCP:<port> cannot tell an IPv6 squatter from the real IPv4 gateway), so a name-based URL could deliver X-Local-Secret to a socket other than the one that was verified. The URL printed for the browser still uses resolve_dashboard_host() (localhost) — that must not change, because the SPA's per-origin localStorage is keyed on it.

Owner-verified secret sends

Six CLI sends carry X-Local-Secret: kirocrew token (_token), the post-restart token URL (_print_token_url), kirocrew logout (_logout), kirocrew update approve (_update_approve), the stop API fallback (_request_gateway_shutdown) and the post-update badge poke (_revalidate_gateway_update_check). All six go through cli_server._owner_verified_secret_urlopen. It runs a verify_peer hook on the CONNECTED socket, after connect and before the first byte is written, so the proof and the send share one connection. A peer cannot be swapped between the check and the send, which a port snapshot taken on a separate connection (the old _gateway_owns_port pre-check) could not rule out.

Both arms start from the same record: _recorded_gateway_pid(port) reads run/gateway-<port>.pid and its .start token, and returns the pid only when the token still matches the live pid's (run_marker.pid_start_token). A missing record, an empty token or a recycled pid gives no pid, and the send is refused.

  • Unix arm — taken whenever dashboard_socket_path(port) exists. The send uses unix_socket_urlopen, which has no TCP handler, so a stale or refused socket raises URLError and is never retried over TCP. The hook requires check_peer_is_self to return MATCH (SO_PEERCRED on Linux, LOCAL_PEERCRED on macOS; UNVERIFIABLE refuses) AND the socket's peer pid (get_peer_pid) to equal the recorded pid (_connected_unix_peer_is_recorded_gateway).
  • TCP arm — taken when there is no socket (a TCP-only gateway, native Windows, which has no AF_UNIX). The send uses tcp_verified_urlopen (ProxyHandler({}), so no proxy is consulted), and the hook runs inside connect(); on any exception the fd is closed. _connected_peer_verdict resolves the pid that owns the GATEWAY's end of this exact 4-tuple via platform_compat.get_tcp_peer_pid (/proc on Linux, lsof on macOS, GetExtendedTcpTable on Windows), retrying for up to 1 s while the connection is still in the accept queue. That pid must equal the recorded pid and be owned by this account: uid on POSIX, access-token owner SID on Windows. Every other outcome, including any exception, is MISMATCH.

Refusal on mismatch. A failed proof emits a SEL denied event and raises _GatewayPeerRefused before the secret is written; a passed proof emits SEL allowed. _GatewayPeerRefused is not an OSError, so urllib does not wrap it into URLError and the caller never reports a live-but-refused gateway as "not running". Each refusal message ends with the remedy to restart the gateway so it re-publishes run/gateway-<port>.pid. Callers:

Caller On refusal
_token, _logout, _update_approve ownership message on stderr, exit 1
_print_token_url caught in its retry loop, then the kirocrew token hint
_request_gateway_shutdown returns False; stop keeps its no-target diagnostic
_revalidate_gateway_update_check prints its one fallback line

Fails closed. These all refuse rather than send: no socket on Windows plus an unresolvable TCP peer; a missing pid record or start token (for example, the marker lock was busy at boot); get_peer_pid returning None (FreeBSD and other platforms); macOS with no trusted lsof; /proc restricted by hidepid, or a socket inode held by more than one process; a failed SID read; a peer still in the accept queue after 1 s.

Gateway side. /api/logout, /api/shutdown and /api/update/revalidate admit a kernel-attested same-user unix peer (_unix_peer_is_self, kernel MATCH only), as /api/token/local already did. The X-Local-Secret comparison is unchanged.

Upgrade window. A gateway still running pre-change code admits only loopback peers on those three routes, and a unix request has no remote address. Until it restarts, a new CLI gets HTTP 403 from logout, the stop API fallback reports its no-target diagnostic, and the badge poke prints its fallback line. This fails closed and ends at the next gateway restart.

Internal-secret senders. The same value is also the gateway's X-Internal-Secret. The CLI senders below prove their peer before the first byte:

Sender Transport and proof On refusal
kirocrew spawn list / spawn run, kirocrew artifact (cli_commands_gateway_api._gateway_send) _owner_verified_secret_urlopen, both arms Error: gateway ownership not verified: …, exit 1 (artifact prints it on stderr)
spawn run's result poll (_gateway_send, operation cli_spawn_poll) _owner_verified_secret_urlopen, both arms; every poll is audited the same message on stderr, exit 1
kirocrew doctor adaptive-controller read (doctor_checks.workload._gateway_adaptive_state) _owner_verified_secret_urlopen, both arms one not read line naming the unproven peer
app_lifecycle_client (mint and action) owner-only unix socket only; verify_peer requires _connected_unix_peer_is_recorded_gateway AppGatewayError (not an OSError), so the CLI never drops to its file-only path
memory_forget_client (mint and delete) owner-only unix socket only; _gateway_peer_verifier wraps _connected_unix_peer_is_recorded_gateway and refuses up front when _recorded_gateway_pid has no pid ForgetRefused
pod/runtime_client.mint_token on Windows tcp_verified_urlopen; _attested_gateway_tcp_verifier requires _connected_tcp_peer_pid (the 4-tuple resolver _connected_peer_verdict also uses) to equal the pod's attested gateway pid PodError

The pod check reads the pod's own pid record, not this home's, which is why it shares the resolver rather than _recorded_gateway_pid. The app-lifecycle, memory-forget and pod hooks emit the same SEL allowed / denied events (_audit_peer_allowed, _audit_peer_denied) as the proof above, under the operations app_lifecycle, memory_forget and pod_token_mint.

Not yet covered. cron_trigger.trigger_cron_job sends the value over plain loopback_urlopen. It serves both kirocrew cron trigger and the agent-side mcp_cron tool, which runs inside the sandbox, so it shares the open design question for the agent-side senders: whether the pid proof can run there. That is tracked in #23270.

Gateway PID Command

kirocrew gateway-pid is a read-only probe that prints who holds this home's gateway.lock as one line of JSON on stdout. It resolves the holder through gateway_lock.lock_holder, the same non-destructive oracle stop --expect-pid and restart use, so the answer does not depend on the listener socket: it names a draining gateway that has released its socket but still holds the lock. The desktop app runs it during liveness and adopt-time drain recovery when its socket lookup names no incumbent (see website/electron/runtime/gateway/home-lock.js, probeLockHolderPid). It sends no signal, starts nothing and takes no lock.

stdout exit meaning desktop verdict
{"holder": "process", "pid": N, "alive": true, "source": "flock_owner"|"recorded_pid"|"home_anchor"} 0 a live process holds the lock captured: wait for pid N to exit
{"holder": "nobody"} 0 the lock is free, or its recorded holder is dead released: spawn
{"holder": "held", "reason": "..."} 0 the lock is positively held and its stamped pid is unreadable (a gateway under a Windows mandatory lock) held: poll until the lock is released
{"holder": "indeterminate", "reason": "..."} 2 the lock state could not be established, or a forked inheritor holds it refused: show the probe-failed error

held is reported only for the LockProbeError.held shape. Every other LockProbeError (an unopenable lock file, an unmeasurable filesystem, a dead kernel-named acquirer, a readable stamp naming a dead pid, a home anchor the lock file does not name) is indeterminate, because nothing guarantees that lock is ever released.

The desktop caller treats a probe that produces no JSON by how it ended. A probe killed at its timeout (or reporting ETIMEDOUT) is unverified and is retried on the recovery backoff. A probe that could not be started (a spawn error code such as ENOENT or EACCES) or that exited without printing JSON is refused, since every later attempt gets the same result.

Stop Command

kirocrew stop [--port PORT] stops a running gateway:

kirocrew stop --port PORT --expect-pid PID is a narrower stop for a caller that already identified the gateway (the desktop app's stuck-gateway restart). It skips the steps below: it opens a pidfd on PID, checks that PID is the sole listener on PORT, looks like a Kiro Crew gateway and is the live holder of this home's gateway.lock, re-checks the listener, then sends SIGTERM through the pidfd. Any failed check, and any host without both os.pidfd_open and signal.pidfd_send_signal (macOS, Windows), refuses with no signal and exit 1. Without --expect-pid the command is unchanged:

  1. If a systemd/launchd service is active and the caller did not pass --port explicitly (see Service Management), stop it via the service manager and return — without this branch, SIGTERM-by-port would be racing the manager's auto-restart. Then, with or without --port, refuse a gateway the desktop app supervises (_refuse_desktop_supervised): the app is another manager and starts its gateway again after a stop. Exit 1, nothing signalled, reason=desktop_app_supervised. With --port N it applies only when this home's gateway listens on N; any probe miss continues below.
  2. Otherwise (no service active, or --port was passed explicitly to target a non-default dev gateway): platform_compat.find_listening_pids(port) to find PIDs — lsof -ti TCP:{port} -sTCP:LISTEN on POSIX, netstat -ano parsing on Windows (there is no lsof there; this previously made kirocrew stop a no-op on Windows). Both binaries are resolved through platform_compat.trusted_system_bin() — the fixed system directories, never PATH, which on a gateway can lead with same-uid-writable dirs — and a name that does not resolve there counts as absent rather than falling back. listening_pid_tool_available() performs the same pinned resolution, so it distinguishes "no listener" from "lookup tool missing" without disagreeing with the lookup it describes. The pinned set is the FHS directories plus /run/current-system/sw/bin, which is root-owned and rewritten only by a system rebuild. A tool installed anywhere else — a Homebrew or conda prefix — still reads as absent, and deliberately so: those prefixes are writable by the invoking user, which is the exposure the pin exists to close. trusted_system_bin() logs a warning once per name when the tool is on PATH but not resolvable under the pin, and tool_outside_trusted_dirs() lets stop name where the tool actually is rather than tell an operator who already has it to install it. That case carries SEL reason=<tool>_outside_trusted_dirs, distinct from <tool>_not_found, so the two are separable in the audit log. When the trusted lookup tool exists but returns no pid, stop makes one POST /api/shutdown request carrying the gateway generation's local secret, through _owner_verified_secret_urlopen (Owner-verified secret sends). It prefers the gateway's owner-only unix socket with the connected-peer proof, which needs no port tool; with no socket it falls back to loopback TCP with the connected-peer proof. A peer that cannot be proven gets nothing and the request returns False. The handler independently requires a same-machine peer (a loopback address, or a kernel-attested same-user unix peer via _unix_peer_is_self) and a constant-time secret match, then triggers the same graceful shutdown event as SIGTERM. The acknowledgement body is capped at 4 KiB before JSON parsing; excessive nesting is treated as malformed input. A successful acknowledgement ends the stop command; a missing secret, refusal, malformed response, or transport failure retains the ordinary no-gateway diagnostic. This fallback never converts the pid sidecar into authority to signal a process.
  3. platform_compat.process_command_line(pid) to verify it's a KiroCrew process — /proc/<pid>/cmdline (Linux), ps -o command= (macOS), Win32_Process.CommandLine via WMI (Windows). The Windows venv kirocrew.exe re-execs python.exe, so the match is on the command line (-m kiro_crew gateway / \Scripts\kirocrew.exe gateway), not the image name. _args_look_like_kirocrew parses the command line structurally and keys on a server subcommand plus a recognised module name. The module name is matched against port_resolution._gateway_module_roots(): always kiro_crew, plus the top-level module of every installed kirocrew.plugins entry point, so a composed edition whose launcher execs its own module with -m classifies without the core knowing any edition's name. The desktop launcher's own port-owner matcher (isKirocrewCommand in website/electron/gateway-stop.js) has no view of the Python environment's entry points, so it matches the companion naming convention instead — -m kiro_crew or an exact top-level -m kirocrew_<edition>, each followed by one of the same server subcommands — which is what lets the app reuse a composed edition's gateway rather than refuse it as a foreign holder. The legacy dotted spawn (-m kiro_crew.gateway) is recognised by stop only; the desktop launcher does not match it and never has, so a service unit spelled that way reads as a foreign holder on the desktop. test/test_cli_stop.py::TestDesktopGatewayIdentityParity pins the desktop copy of the subcommand set and module pattern to the Python side, so widening one without the other fails a test instead of a user. When a listener exists but none of the pids classify, stop names the pid(s) — with the cmdline basename when cheap — and exits 1 with SEL reason=unrecognized_listener, rather than reporting "no gateway running" for a port that is occupied. Before that refusal, the authenticated shutdown is tried once more, with SEL reason=argv_declined_listener (the empty-lookup attempt above carries reason=listener_lookup_empty, so the two paths stay separable). argv is the weakest identity a gateway has — every spawn shape has to be taught to the patterns, and the desktop app's is not among them — while the per-generation secret is published by the gateway at startup whatever its command line reads. Answering the request shuts down the answerer, so no pid is guessed or signalled on that path, and a listener that does not answer keeps the unrecognized_listener refusal exactly as before. The request is made only once the process that will RECEIVE the secret is proven to be this port's gateway (_verified_loopback_gateway_pids), because the secret mints owner tokens and reachability is not identity. The proof is the one port_resolution._gateway_owns_port documents, minus its argv step — which that contract itself keeps as defense in depth rather than proof — plus the start identity and the address: the pid and .start token recorded in run/gateway-<port>.pid (0600 inside the 0700 run/ dir, on the is_sensitive_path floor), that token still matching the live pid's, that pid among the ones a 127.0.0.1 connect actually reaches (platform_compat.loopback_owner_pids, which mirrors the kernel's most-specific-bind dispatch, so a gateway bound to another address cannot vouch for a process squatting loopback), and the pid owned by this account. Every step fails closed, and the path denies outright off POSIX where process_owner_uid reports no owner — the same boundary _gateway_owns_port draws. restart reuses that proof: when a listener was found but the argv filter named no incumbent, it resolves the answering pid BEFORE the stop (afterwards the identity is gone) and waits for it, since who must release the port before a replacement can bind is answered by who answered, not by argv.
  4. Terminate each verified PID: os.kill(SIGTERM) on POSIX; taskkill /T /F (via platform_compat.kill_process_tree) on Windows so the gateway's detached children are reaped too. Liveness is probed with platform_compat.pid_exists (a raw os.kill(pid, 0) would terminate the process on Windows).
  5. Waits up to 1s for exit.
  6. SEL audit event logged.

Restart Command

kirocrew restart [--port PORT] restarts a running gateway. Mirrors stop's service-aware structure:

  1. If a systemd/launchd service is active and the caller did not pass --port explicitly, ask the platform to restart it. On Linux: systemctl restart kirocrew.service in every scope whose unit is running — sudo systemctl for the system unit, systemctl --user (never sudo) for the per-user one (single atomic operation, smaller down-window than stop+start, and the supervisor stays in charge of the lifecycle the whole time). The exit code of systemctl restart is not the verdict: the unit is Type=simple, whose start job completes the moment the process is forked, so a gateway that exits on start still gets exit 0. service.linux.restart() therefore re-reads the unit (systemctl show) for _RESTART_SETTLE_SECS (2 s, one read per 0.25 s; each read also carries ExecMainStartTimestampMonotonic, and a stamp that changes inside the window is a death and re-exec the reads fell between — a RestartSec shorter than the read interval — reported as NOT UP; a manager answering 0 or no stamp leaves that check off) and returns a per-scope RestartReport: a scope is restarted only if the unit is active at the end of the window; one seen in activating (auto-restart), failed, inactive or deactivating inside it is reported at once with that state and its Result (exit-code, start-limit-hit, …); activating (start) is waited for until the deadline. A non-zero systemctl restart is classified by the unit's state right after it — still up or unreadable: a REFUSAL (the manager did not run the job), reported with the manager's diagnostic and the restart command for THAT scope (common.system_restart_command_hint() / common.user_restart_command_hint(), sudo systemctl restart kirocrew / systemctl --user restart kirocrew); otherwise the job ran and failed (failed, activating (auto-restart)), reported as NOT UP with that scope's journal command. The shared common.restart_command_hint() the update path, the Slack restart-failure hint and the install-time credential warning print picks the same way, by two stats and no spawn: only the system unit file present → the system command; only the per-user unit file at the remedy's location → the user command; neither, or both (a file says nothing about which scope runs) → the service-aware kirocrew restart. The gateway's async update-failure handler awaits it in a worker thread (asyncio.to_thread): the per-user location is under the account's home, which can be a network mount whose stat blocks for as long as the mount is disconnected, and on the loop thread that wait would freeze chat and the liveness heartbeat together. controller.manual_restart_hint() stays the unconditional system command on systemd (it must never answer the kirocrew restart that just failed). When the report is not ok and a unit is still there, the command exits 1 with one line per scope acted on — a scope that restarted reads restarted, a refusal names its hint, a unit that did not stay up names that scope's journal command — and never falls through to the listener path. The headline is per scope too: with a unit in both scopes (a stale crash-looping system unit beside the working per-user one) it reads Restarted kirocrew service in the user scope; the restart did not take in the system scope, never "the gateway was NOT restarted", which is false for the gateway the operator uses; the exit code is still 1 because a scope needs a hand, the shape service uninstall gives a teardown that finished in one scope. On macOS: launchctl kickstart -k <domain>/<label> over gui/<uid> then user/<uid> (service.macos.restart), so launchd performs the kill and the respawn itself and the call is safe from inside the gateway being restarted. launchctl unload + load is not used: run from the gateway its unload half SIGTERMs the caller before load runs, leaving the agent down. The deprecated launchctl restart behaves like stop under KeepAlive (SIGTERM then immediate respawn of the loaded job) and never re-reads the plist.
  2. Otherwise (foreground gateway, no service, or --port passed explicitly to target a non-default dev gateway):
    • First refuse a gateway the desktop app supervises, as stop does (nothing signalled or spawned, exit 1, reason=desktop_app_supervised), naming the in-app restart. Dev Fleet's foreground restart asks the same check (desktop_app_supervisor) before it spawns, so it never reports a restart that is then refused.
    • platform_compat.find_listening_pids(port) (lsof on POSIX, netstat on Windows) to detect a running gateway. If found — OR if the lookup tool is absent (not listening_pid_tool_available(), so a missing tool is not mistaken for a dead gateway) — run the existing _stop path. When the trusted lookup tool exists but returns no pid, restart independently attempts the authenticated shutdown request. An acknowledged request always refuses the immediate replacement and tells the operator to retry after shutdown completes: neither an absent pid sidecar nor a live same-user pid from that sidecar can prove singleton-lock release, because a stale pid may be recycled and exit before the incumbent. The second restart sees no incumbent and safely starts the replacement.
    • If no incumbent evidence exists (e.g. the user runs restart after a crash), skip the stop step rather than erroring — the user expects to end up with a running gateway either way. The _stop call is wrapped in a try / except SystemExit so a TOCTOU race (gateway exits between the listener check and _stop's own lookup → _stop calls sys.exit(1)) does not abort the restart before the spawn.
    • When a listener IS present but none of the pids classify as a Kiro Crew gateway, _stop declines it (see step 3 above) and the incumbent list is empty, so restart resolves the incumbent through gateway.lock instead (_incumbent_from_lock_holder): a live holder that did not acknowledge the shutdown is refused by _refuse_lock_holder and no replacement is spawned. A gateway booted from a module the classifier does not recognise lands exactly there — it holds the lock and stop could not signal it — so recognition, not the restart path, is what makes the ordinary stop → wait → spawn path run. A foreign listener that holds no lock still leaves the spawn to proceed and fail on its own bind.
    • Spawn a detached kirocrew gateway via subprocess.Popen, stdin set to subprocess.DEVNULL, and stdout + stderr redirected to ~/.kiro/crew/gateway.log (the same file the kirocrew logs command tails for foreground gateways). Detach is per-platform: POSIX uses start_new_session=True; Windows uses creationflags=DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP (there is no setsid) — both via platform_compat. The spawn returns immediately, the command then waits for readiness (next bullet), and the user can follow logs via kirocrew logs -f.
    • Report success only once the replacement answers /api/ready and its run marker records a pid that differs from the previous gateway's pid when one is known (_wait_gateway_ready). Only this fork path verifies readiness before printing success. A replacement that exits prints Replacement gateway (pid N) died immediately (exit status S) and exits 1 at once. It says Nothing is serving port P only when a probe of /api/ready gets no HTTP answer; when the port still answers HTTP (even a 404 from an unrelated server), it prints Replacement gateway (pid N) exited at once (exit status S). Port P still answers HTTP. without claiming the listener is a gateway, names the live gateway.lock holder when the lock names one, and calls it the desktop app when it runs from the backend-dist bundle (_died_replacement_message). Exit code and audit record are the same in both cases. One still running at the deadline prints Replacement gateway (pid N) did not become ready within Ns. It is still running but not serving port P. and exits 1. The readiness deadline is read from the environment each time the fork path runs: it defaults to 60 s because a loaded install can take 25-35 s to boot; KIROCREW_RESTART_READY_TIMEOUT overrides it, fractional values round up to whole seconds, the result is clamped to 15..180 s, and an unset, non-numeric, non-finite, zero or negative value falls back to the default. A set value that falls back or gets clamped prints one KIROCREW_RESTART_READY_TIMEOUT='V' ...; using Ns. line to stderr. When the deadline exceeds 15 s, the wait prints one Still starting (Ns elapsed), continuing to wait... line on the first check after 15 s. The service path (step 1) does not use this deadline and is unchanged. On both paths, the token-URL wait after a successful restart keeps its fixed 15 s budget.
  3. SEL audit event logged with via=service or via=fork pid=<n> so the audit trail distinguishes the two paths.

Service Management

kirocrew service {install,uninstall,status} registers the gateway with the OS service manager so it survives SSH disconnects, restarts on crash, and starts on boot. Implemented in src/kiro_crew/service/.

On Linux, service/linux.py keeps the verbs that read and drive an installed unit: user_unit_installed, user_unit_active, user_unit_path, is_active, is_up, alias_holder, stop, restart with its settle window, and status. The rest lives in its owners, and new work for each part goes to its module:

Module Owns
service/linux_unit.py the unit and overrides-file paths (UNIT_PATH, ENV_FILE_PATH), the service account (user, group, uid, home, linger) and render_unit
service/linux_systemctl.py privilege (_privilege_prefix, _sudo_run, ServiceInstallError), _systemctl in either scope, and one scope's unit state (_UnitState, _unit_state, _stale_unit_line)
service/linux_install.py install: the root-owned unit and overrides-file writes, the SELinux refusal and its user-unit remedy, and the AppArmor profile install and removal
service/linux_uninstall.py uninstall: the ownership decision _owned_unit, the per-scope teardown arms and UninstallReport

kiro_crew.service.linux is a mirror facade over those four owners, lowest layer first. Every name linux.py held before the split still resolves as kiro_crew.service.linux.<name> and is the same object, and a patch through it reaches every owner that binds the name. An owner imports only the owners listed before it, never the facade, and the owners log as kiro_crew.service.linux. test/test_linux_facade.py pins the contract.

  • Linux (current_platform() == SYSTEMD):
    • Unit file: /etc/systemd/system/kirocrew.service (root-owned).
    • Install: sudo install writes the unit, then sudo systemctl daemon-reload && sudo systemctl enable --now kirocrew.service. Privilege is resolved per call: already-root (euid 0) skips sudo entirely — required on minimal container / root-login images that ship no sudo binary — and a non-root caller with no sudo fails with a clear ServiceInstallError rather than an uncaught FileNotFoundError.
    • The gateway runs as User=$USER Group=$(id -gn). Every elevated executable is a stock system program, not a kirocrew one; the module docstring in service/linux.py names the current set for the whole family, and records what escalating the AppArmor step's interpreter does and does not guarantee. security carries the reasoning behind that step's four tools.
    • Environment: values are captured from the installer's environment into the unit's Environment= lines at install time (service_environment() in service/common.py) — this is how KIROCREW_PORT=5477 kirocrew service install binds a non-default port. The unit also reads EnvironmentFile=-/etc/kirocrew/kirocrew.env, an operator-editable file the installer seeds create-if-absent (a reinstall never clobbers edits). systemd applies the file AFTER — and overriding — the baked Environment= lines, so editing it and running sudo systemctl restart kirocrew changes a value (e.g. the port) without reinstalling. Uninstall removes the file and its /etc/kirocrew directory.
    • Credentials are deliberately NOT captured. Both baked locations are world-readable — the unit lives in root-owned /etc/systemd/system and the override file is installed 0644 — so a model credential placed there would be readable by every local user on the host. service_environment() therefore carries no credential — its only installer-derived values are PATH, KIROCREW_KIRO_BIN and KIROCREW_PORT (it also returns HOME, LANG and LC_ALL) — and a test pins the absence so a future "just propagate it" change fails. Consequence: a KIRO_API_KEY exported in the installing shell does not reach the service, the readiness probe (which forwards that variable from the gateway's own environment) sees no credential, and unless a kiro-cli login credential store under the baked HOME supplies one instead, the dashboard reports a signed-out state on a host where kiro-cli itself is authenticated. install_service() prints a warning naming the variable and the remedy when it detects that case, and ~/.kiro/crew/.env is the supported home — load_credentials() reads every key from that file into the gateway environment at boot and forces 0600 on it first. The warning is diagnostic only: it is non-fatal by construction, since the unit is already written and started by the time it runs. kirocrew doctor reports the same condition next to its kiro login line — the one output where the contradiction is visible, since that line runs whoami with the inherited environment and reports signed in. Doctor's report is gated on a service definition existing (installed_unit_path() — the system unit file, or, when it is absent, the per-user unit the calling account's own manager has loaded, read from the FragmentPath it reports via linux.user_unit_path(), which answers only for a LOADED unit whose canonical Id is kirocrew.service — a blank or malformed show answer, a mask, an unparseable unit (bad-setting / error) and an alias yield nothing, so doctor never reads as the definition a file the manager runs nothing from; the same gate feeds doctor's managed-marker check, since render_unit(user_scope=True) bakes the same Environment= lines): without one the gateway runs in the foreground and inherits the invoking shell, so the credential does reach it and a warning would be a false positive. It is advisory only — never appended to doctor's issues, which is the exit-code channel — since that gate establishes a definition on disk, not that the serving gateway lacks a credential; a fall-back login store, or a stopped unit beside a foreground kirocrew gateway, both leave the host healthy while the check fires.
    • Boot survival of the GATEWAY via WantedBy=multi-user.target needs no linger — the gateway is a system-level unit, and linger is a user-service concept. The AGENT RUNTIMES are a separate matter: the unit bakes XDG_RUNTIME_DIR/DBUS_SESSION_BUS_ADDRESS for the service account, so each runtime scope is created under that account's user@<uid>.service, which logind stops when the account's last login session ends unless linger is on — killing in-flight scoped runtimes and dropping later spawns to the unscoped path (no cgroup ceilings). install_service() therefore prints a non-fatal warning naming loginctl enable-linger <user> when it detects linger off for the service account, beside the headless-auth warning above; it is advisory and never changes the install outcome.
    • Crash-loop safety: StartLimitBurst=3 StartLimitIntervalSec=300.
    • A home another gateway already serves is not retried. kirocrew gateway takes <home>/gateway.lock before it binds anything. One predicate decides whether a refusal is the kind a restart cannot heal: GatewayLock._serving_verdict in gateway_lock.py, the serving-holder predicate, asked about the process /proc/locks positively identifies as the lock's acquirer (of the lock file, or of the home directory when the file has been deleted or replaced) and never about the pid the lock file merely records. It carries four conjuncts, each measured once: that acquirer is alive; it holds the configured dashboard port (one listener enumeration, platform_compat.find_port_listeners, filtered to the owner's own sockets); it holds it AT the address the probe reaches — the address this gateway is configured to bind (KIROCREW_BIND when it parses as an IP address; an absent override or the IPv4 wildcard 0.0.0.0 is probed at 127.0.0.1, the IPv6 wildcard :: at ::1 because the dashboard binds it IPV6_V6ONLY and a v4 connect never reaches it) — with the owner's wildcard binds covering that address by family only (0.0.0.0 covers any v4 host, :: covers v6 hosts and not v4 ones), and an unreported address or family counting as unknowable, never as covering; and it answers HTTP there. The address conjunct is what ties port ownership and HTTP health to ONE process: port ownership alone is address-agnostic, so without it a stranger answering at the probe address on the same port would be credited to a lock owner bound elsewhere. Only all four make GatewayLockError.live_holder True — a sibling gateway serving the home, which this one can displace on neither front while it lives — and then the process exits gateway_lock.LIVE_HOLDER_EXIT_CODE (78, EX_CONFIG: two supervisors pointed at one home is a host configuration, and the remedy is to change it); the unit's RestartPreventExitStatus= names that code, so a Restart=always unit goes failed once with the refusal line in the journal instead of relaunching every RestartSec against a refusal the sibling keeps permanent (bounded by StartLimit* on the shipped unit, unbounded on a unit without them). Every other refusal exits 1, which the unit's Restart=always relaunches, because a later attempt can find it cleared or because the evidence for standing down is missing: a lock file replaced faster than it can be locked, a gateway.lock that is not a regular file (a symbolic link, including one a dotfile manager placed, a junction, a directory, a FIFO or a socket; the lock never opens through a link, so the refusal says to remove it, and stop/restart read the same entry as indeterminate rather than as nothing running; a regular file with another hard link is still locked, but its pid stamp is not written, and a stamp is distrusted only while the file has another link: once that link is removed the stamp left in it is trusted again, on every platform, until the next acquire stamps over it, and a chmod, chown, xattr or ACL change never revokes trust; on Windows a regular file carrying a non-link reparse tag, such as a cloud-files placeholder, is locked as usual), a lock file that cannot be opened or measured or a home that cannot be created (a permission gap, a read-only or full filesystem; kirocrew app uninstall reports this as a failed pointer clear, never as a running gateway), a home that cannot be opened or measured for directory locks, an flock whose acquirer is gone (a wedged inheritor holds it until that process dies), a live acquirer that does not hold the port (a sibling still starting, or one shutting down that has closed its listener and releases the lock next), a live acquirer on the port but silent at the probed address — a wedged gateway (a hung process keeps its listening socket bound, and a terminal exit would leave the unit failed with nothing left to relaunch once that process dies) or, the residual row the predicate leaves unasserted by design, a gateway that holds the port only at another address than this one would bind, or whose socket addresses the platform could not report (probing the holder's own listener address instead is the follow-up tracked in the PR's deferred-finding issue, not a guess made here); the message names what was measured (holds port N, not answering HTTP at 127.0.0.1, or holds port N at ::1, not at 127.0.0.1) and says the refusal is not treated as permanent — and a holder no surface could identify — no /proc/locks (macOS, Windows), or a Linux filesystem whose device numbers never match the lock table (btrfs subvolumes, overlayfs) — where the pid the lock file records may be alive and on the port and still be a reused number rather than the process that holds the lock; the predicate is never asked about it, and that refusal's message says the holder cannot be confirmed and that a supervisor, if one manages the gateway, will retry it (the same message on every platform, since macOS and Windows reach this branch on every refusal). On the identified-acquirer paths one listener enumeration and at most one HTTP probe (its own 1.5 s budget) feed both the message and the exit status, so they cannot disagree; the orphaned-lock path (a dead acquirer, candidate openers) keeps its own per-candidate facts. With no port to weigh (--port auto, --slack-only) the verdict cannot be reached and every refusal stays restartable. The constant is defined once, beside the refusal in gateway_lock.py, and both cli.py (the exit) and render_unit() (the exemption) import it; test_service.py pins the rendered directive to the constant and the constant to 78, because the value is baked into installed units, which service install writes once and no upgrade re-renders — a unit written by an earlier build keeps relaunching on this refusal until it is re-rendered. An existing install picks the directive up by re-running kirocrew service install, and kirocrew service status says so: for each scope whose unit is loaded and ours it asks the manager for the LOADED value (systemctl show --all -p RestartPreventExitStatus, so drop-ins count and a file edited without a daemon-reload still reads as missing) and, when that value does not name 78, prints one line under that scope's headline naming the directive and the remedy (sudo kirocrew service install for the system unit; for the per-user unit, add it under [Service] in the reported FragmentPath and systemctl --user daemon-reload, never sudo). An answer with no such property line makes no claim. It is read-only: nothing is rewritten and no daemon-reload runs. Rewriting the unit in place is not done.
    • Two scopes, both visible. install writes the system unit only, but the SELinux refusal hands the operator a per-user unit (render_unit(user_scope=True), managed with systemctl --user), so every OTHER verb accounts for both scopes and names the one it reports on: status prints system scope: … then user scope: …. One guard is shared by every verb that acts on the name (_UnitState.ours): the canonical Id show answers must be kirocrew.service. An operator's Alias=kirocrew.service on their own unit makes show, stop, restart, disable and the unlink on our name act on THAT unit, so an alias is refused whole by uninstall, is never selected by stop() / restart(), and is not counted by is_active() / is_up() — the headline still names it (active (running), an alias of shared.service). Because those predicates fail closed on an alias, the kirocrew stop / kirocrew restart CLI commands cannot tell "no managed unit here" apart from "the name is a RUNNING alias of another unit's process" — so before their foreground fallback (which would SIGTERM, and for restart respawn over, the alias target's process) they ask service_alias_holder() and, on a hit, REFUSE: exit 1, nothing signalled, nothing spawned, printing the resolved unit, its scope, and the scope-correct remedy (systemctl --user vs sudo systemctl, stop vs restart), and auditing the denial with reason=service_name_is_alias. The holder is reported only for an alias whose target is RUNNING (is_alias and running); a stopped (inactive / failed) alias has no supervised process to protect and would misdirect the remedy, so it is not refused and the fallback proceeds. kirocrew stop --port N / kirocrew restart --port N explicitly target a foreground gateway and bypass both the managed-service short-circuit and this alias refusal. Two predicates, deliberately distinct: is_active() is the REACH predicate — true when either scope RUNS our unit, any ActiveState but inactive / failed, so a unit crash-looping through activating (auto-restart) counts — and stop() / restart() act on each scope that satisfies it, selected by the same systemctl show the status verbs read rather than an is-active probe, which answers non-zero for activating and would let kirocrew stop issue nothing at a flapping unit (kirocrew stop / kirocrew restart therefore reach a user-scope gateway through its own manager, with no sudo; a stopped unit in the other scope is never started on the side, which selecting on "installed" would do). is_up() is the HEALTH predicate — ActiveState active or reloading in either scope, exactly what systemctl is-active exits 0 for — and the kirocrew service status exit code follows it, not is_active(): a crash-looping unit is one stop must reach and one status must report as down (exit 1, headline activating (auto-restart)), because a script gating on that exit code would otherwise read a gateway that never started as healthy. restart() returns a RestartReport — per scope, ok only when the unit is active at the end of a 2 s settle window (the Type=simple start job succeeds at the fork, so systemctl restart exiting 0 says nothing about the process), a refusal carrying the manager's diagnostic and that scope's own restart command; see the Restart Command section. uninstall() tears down the system unit under sudo and the user unit through systemctl --user, and returns an UninstallReport naming what each scope got. Every verb in either scope rests on ONE decision, _owned_unit(): the unit the manager reports under our name is Kiro Crew's when the file that holds its definition — the reported FragmentPath, followed through a symlink to its source — is the file the installer writes for that scope (/etc/systemd/system/kirocrew.service; ~/.config/systemd/user/kirocrew.service) or carries the installer's own marker line, Environment="KIROCREW_SERVICE_MANAGED=1" (the line every rendered unit has, and the one kirocrew doctor reads); a definition under another name is never ours. A unit that is not ours — a distribution's unit under /usr/lib loaded because no file of ours shadows it, an operator's own unit systemctl --user linked under our name, a link at the installer's path to a file the manager reports by its resolved target — reads left untouched (not installed by Kiro Crew: …) with nothing stopped, disabled or unlinked, and the scope finishes (exit 0). A unit of ours reached through a link — the fragment itself a symlink, or the installer's path a symlink resolving to it — loses its link entries and keeps its definition: `removed (the link to ; the linked unit file itself was kept)`; a direct file of ours is unlinked. The order in either scope is stop → disable → verify inactive (a second `show`) → remove → `daemon-reload`, the system scope's removal an `rm -f` under sudo (which removes a symlink's entry, never its target) and the user scope's an `os.unlink` as the calling user. A closing `daemon-reload` the manager rejects (exit non-zero) leaves the scope unfinished and NOT in `removed` until the reload takes — the file is gone but the manager still holds the old definition — its line reading `removed (), but \`sudo systemctl daemon-reload\` failed: ; run it by hand` (user scope: `systemctl --user daemon-reload`), and the controller exits 1; on a host not booted with systemd (`/run/systemd/system` absent) no system manager exists to hold it, so that reload failing is not one. A step the manager refuses (`RefuseManualStop=yes`, a bus that went away mid-run, a declined sudo), or a unit still running after `stop` returned 0, ends that scope's teardown before anything is unlinked, its line reads `left in place (\`… stop kirocrew.service\` failed: …; the unit file was not removed)`, and the controller marks that line and exits 1 — deleting the file would leave a unit that is still loaded, possibly still running, with no unit to find it by while the report read `removed`. Two shapes are refused WHOLE, before any verb: an alias (in either scope — `show ` answers for the unit the name resolves to, so `stop` / `disable` / unlink on our name would act on that unit) and a unit that is RUNNING under any load state but `loaded` — masked at runtime (`systemctl mask` leaves a running unit running and reports its fragment as the mask), edited into an unparseable state, or `not-found` with its file removed under it — reported as `left in place (an active unit whose load state is masked: unmask and stop it first, then run \`kirocrew service uninstall\` again)`. A refusal is unfinished (exit 1) when it leaves a running unit or the module's own file at `/etc/systemd/system/kirocrew.service` behind; one that leaves neither — an inactive alias in the user scope, or in the system scope with no file at that path — is a report (exit 0). A system unit file the manager answers for but does not have loaded and that is NOT running (a file dropped without a `daemon-reload`, an inactive mask, an unparseable unit) runs nothing and is removed outright — the mask (`systemctl mask`'s symlink to `/dev/null` at exactly that path, a mask of OUR name) by unlinking the entry, which unmasks the name. A system manager the shell cannot reach is decided by `sd_booted(3)`'s test, `/run/systemd/system`: absent, no manager runs on this host (a container where systemd is not PID 1, where `install()` leaves the file behind when its `daemon-reload` fails) and the stale file is removed; present, the unit may well be running and the line reads `left in place (the system manager is not reachable from this shell: …)`. The absence of the unit file is not the manager's word either: `uninstall()` asks the system manager (an unprivileged `show`) before calling that scope `not installed`, so a unit still LOADED and running after `rm /etc/systemd/system/kirocrew.service` is stopped (checked) and `daemon-reload`ed — with no file there is nothing for `disable` to read or for the unlink to remove, and the line reads `stopped (its unit file … was already gone, so nothing was disabled or unlinked; daemon-reload run)` — one a `daemon-reload` left `not-found` but running is refused whole as above, a not-loaded, not-running one with no file (a runtime mask) is reported as `left in place (load state …)`, and an unreachable manager on a systemd host reads `not reachable from this shell (…)` (nothing left behind, so not unfinished). The report carries its outcome as structure — `removed`, the scopes whose unit is gone from the manager (file unlinked, link removed, or the fileless unit stopped and `daemon-reload`ed), and `unfinished` — and the controller's headline reads `removed`, never a line's prefix. A host without `sudo` does not abort the call: the system line reads `left in place (privilege unavailable: …)` and the user scope is still torn down. A unit file that cannot be removed after a successful stop is reported the same way on its own scope's line. The user-scope teardown rests on the same ownership decision: a definition that is neither the file at `~/.config/systemd/user/kirocrew.service` nor one carrying the marker is `left untouched (not installed by Kiro Crew: …)`, a not-loaded file of ours at that path is removed, a mask of the name at that path (`systemctl --user mask`) is unlinked — `removed (the mask …; kirocrew.service is unmasked)` — and a mask or an unparseable unit anywhere else is the operator's to inspect, reported as `left in place (…)` with nothing in that scope stopped, disabled or deleted. Load state comes from `systemctl show -p Id -p LoadState -p ActiveState -p SubState -p FragmentPath -p Result` (parsed as `Key=value`, which systemd 219 supports — `--value` does not exist there), because `is-active` answers `inactive` both for a stopped unit and for a scope with no unit, which is what makes a running user-scope gateway read as `inactive (dead)` in a report that asks the system scope alone. Every `systemctl --user` the module spawns runs with `service.common.systemctl_user_env()`, the one resolver the pod runtime's `systemctl --user` spawns also use: it backfills `XDG_RUNTIME_DIR` and, when the bus socket exists, `DBUS_SESSION_BUS_ADDRESS` from the account's runtime directory (never overriding a value the caller set), so a shell descended from a system unit — the gateway's own — reaches the account's manager and a `not reachable` reading is a host fact, not a missing-variable artifact. A user scope this process cannot see is reported as `not reachable from this shell ()`, never as inactive, and `uninstall` leaves it alone: a root process whose `SUDO_USER` names a human is decided in-process without spawning (`systemctl --user` there would answer for root's manager, not the human's), and any other failure — no session bus, a stripped environment, a sandbox — is systemd's own non-zero exit with no `LoadState` printed, reported with its diagnostic and never classified by stderr text.
    • Logs are read from the journal: a per-user unit logs to journalctl --user -u kirocrew, which kirocrew logs prefers; the system unit to sudo journalctl -u kirocrew -f, or unprivileged if the user is in systemd-journal / adm. See Logs Command.
  • macOS (current_platform() == LAUNCHD):
    • Plist: ~/Library/LaunchAgents/dev.kirocrew.gateway.plist
    • Install: launchctl enable gui/<uid>/<label> then launchctl bootstrap gui/<uid> <plist>. RunAtLoad=true and KeepAlive ensure auto-start and crash recovery. KeepAlive relaunches EVERY exit, including the live-holder refusal (exit 78); the exemption for that exit (RestartPreventExitStatus) is systemd-only.
    • Stdout and stderr are written to ~/Library/Logs/KiroCrew/gateway.{log,err}.
    • Install, restart, stop and uninstall name the domain explicitly, so an install from SSH lands where restart and stop address it; the legacy load/unload verbs act on the caller's domain (user/<uid> from SSH). is_active and status still read the caller's domain with launchctl list, so from SSH they do not see a gui/<uid> job. With nobody logged in at the desktop, there is no gui/<uid> domain: when bootstrap gui/<uid> answers 125: Domain does not support specified action, install enables and bootstraps into user/<uid> instead and logs which domain it used. Any other bootstrap refusal fails the install. Reinstall first boots out an agent an older load -w left in gui/<uid> or user/<uid> and waits for it to leave (bootout is asynchronous); enable clears the persistent disabled override an older uninstall's unload -w wrote.
    • Restart, stop and uninstall: launchctl kickstart -k / bootout on <domain>/<label>, trying gui/<uid> then user/<uid>; a domain that answers "not found" or 125 holds no job and the next one is tried. Removing the job leaves nothing for KeepAlive to respawn; stop keeps the plist and its enabled state for the next login. stop() returns whether launchd accepted the bootout and stop_service() passes that on, so kirocrew stop never reports a refused bootout as a stop.
    • Uninstall removes the plist and the launcher whatever launchd answers. When no bootout was accepted (refused, never loaded, or the plist was already gone), uninstall() asks launchctl print <domain>/<label> over gui/<uid> then user/<uid> and returns the domain that still holds the job (exit 0 only). uninstall_service() then prints ❌ launchd did not unload … and the launchctl bootout <domain>/<label> to run by hand on stderr and exits 1, as Linux does for a unit left running. An accepted bootout is not probed, since it is asynchronous.
    • restart_service() gates on is_loaded() (launchctl print <domain>/<label> over gui/<uid> then user/<uid>), not on the caller-domain is_active(), so kirocrew restart over SSH kickstarts the service job instead of falling to the foreground SIGTERM-and-spawn path beside it.
  • Other platforms: install/uninstall return exit code 2 with a message pointing to manual setup.

Persisted service launch paths follow the managed-venv stable link: the shared service.common.kirocrew_bin resolver rewrites every automatic answer through tree_liveness.through_stable_link. The explicit KIROCREW_SERVICE_BIN override remains operator-owned and is only made absolute. Without it the resolver names the console script beside the running interpreter — the install performing the service install — before it consults PATH, because ~/.local/bin/kirocrew is shared and any other install may repoint it later; a service persisting it would silently start that other install on its next restart. A script in a linked git worktree or an AppImage mount is skipped, since either is reaped from under a persisted path; PATH and then sys.argv[0] remain the fallbacks. The macOS missing-launcher repair uses that override or the console script beside the running interpreter, with the same stable-link rewrite for the latter; it never consults PATH.

kirocrew stop is service-aware: if the service is active it calls the platform's stop instead of SIGTERM, so the manager does not immediately restart the gateway under us.

Logs Command

kirocrew logs [-n LINES] [-f] (LINES defaults to 100 and must be 0 or more; -n 0 -f shows only new lines, and a negative exits 2) tails the gateway log from whichever source is most appropriate:

  1. the USER journal (journalctl --user -u kirocrew.service) when the calling account's own manager has the unit loaded (service.linux.user_unit_installed()) and it is either the only unit or the one running (user_unit_active(), asked only when a system unit file also exists — a stopped system unit left by an earlier install must not win over the per-user gateway that replaced it). Read without privilege; there is no sudo rung, because the user journal never needs one, so an empty probe falls through to the next source. The user probe runs journalctl --user … --quiet -n 1: a journal with no matching entries prints -- No entries -- on stdout with exit 0 (systemd 252), which is not a row and must not exec a tail of nothing — quiet suppresses the notice so an empty journal reads empty.
  2. systemd journal if the system service is installed on Linux. Tries unprivileged journalctl first; falls back to sudo journalctl only if the unprivileged probe returns no rows. Unchanged from before the user-journal source above was added: a probe that printed anything — the unit's rows, or journalctl's own notices — is exec'd unprivileged, and only a probe that printed nothing takes the sudo rung (a TTY prompt, or the "stdin is not a TTY" refusal).
  3. launchd stdout file if a plist exists on macOS and that file is non-empty. Both conditions matter: the platform probe reports launchd on any macOS host, and an install that never started the agent leaves a 0-byte log behind, so either check alone would capture the command and tail nothing.
  4. ~/.kiro/crew/gateway.log for foreground gateways

gateway.log itself is opened by cli_logging._setup_cli_logging. Only the gateway command rotates it (2 MiB, three backups). At boot it also moves a non-empty gateway.log to gateway.log.prev (_rotate_boot_logs) in two renames, each into a name nothing else holds: first the old .prev to logs/gateway-boots/gateway.log.<n> (n one more than the largest kept, so order never depends on the clock; cli_log_files.older_boot_logs), then gateway.log to the freed .prev. Boot lists only that directory, never the data home, so its cost stays fixed. Rotation runs only once the start holds the gateway lock (_start_gateway_log_after_lock, called right after GatewayLock.acquire): logging is set up long before the lock, and a start the lock refuses must never move, size-roll or prune a running gateway's log. Until then the start appends to gateway.log with the size rollover off, so its own lines, a refusal's included, land in the running log and the lines a winning start wrote before the lock stay at the end of the new .prev, where the restart relay reads them. The handler's stream is closed for the rename, since Windows cannot rename a file this process holds open. Nothing is ever moved back: if either rename fails (a file held open on Windows), boot stops, leaves every file where it is and appends to gateway.log, so a failed boot loses no kept log and never writes over a gateway.log another process recreated. Only after both succeed are older boots past three, or past 16 MiB in total newest first (BOOT_LOG_GENERATIONS_MAX_BYTES), deleted; gateway.log.prev never is. A run's log therefore survives four restarts, and after a successful rotation gateway.log.prev is the boot just before this one, which the restart relay reads. kirocrew doctor --bundle includes every kept boot. Every other process that logs there — the mcp-* stdio servers, kirocrew chat, short CLI verbs — writes through _AppendOnlyLogFileHandler, which opens the file for one record, closes it again and never rotates. Windows refuses to rename a file while another process holds it open, so a child that kept its own handle for its lifetime made every gateway rollover fail. A size rollover whose rename still fails (_OwnerOnlyRotatingFileHandler in cli_log_files.py) reopens the live file in append mode, writes one line into it naming the failure, and tries again only after _ROLLOVER_RETRY_SECS (60 s), so records keep landing past the 2 MiB cap instead of being dropped. A gateway whose boot rotation to gateway.log.prev fails logs one warning and keeps appending to the previous run's file. A foreground gateway whose log file cannot be opened warns and continues with console logging only; a detached gateway, whose stdout and stderr point at that file, raises instead. If a size rollover's reopen fails, the detached handler prints its first traceback only, and on a non-retryable errno (_LOG_FATAL_ERRNOS: ENOSYS, EPERM, EACCES, EROFS) or after three consecutive errors (_LOG_ERROR_STREAK_LIMIT) it stops file logging: it writes one line to stderr, drops later records, and points fds 1 and 2 at os.devnull. So a gateway.log that stopped growing after a rollover means file logging was stopped, not that the gateway is idle.

A host override of member_memory_auth.protected_member_session_for_pid must return None when a binding is missing or unreadable and "" only for an explicit invalid or revoked record; mcp_caller treats "", and an override that raises, as a hard refusal that never falls through to KIROCREW_SESSION_KEY.

Uses os.execvp so signals (Ctrl+C) propagate naturally to the underlying journalctl/tail process.

Dashboard Self-Update

On gateway startup and every 12 hours, a background task runs git fetch and reports an update when EITHER the checkout can be FAST-FORWARDED (git rev-list --count --left-right HEAD...@{u} shows commits behind and none ahead) OR the pull already landed and only a restart is missing (HEAD equals its upstream while the on-disk __version__ outranks the one this process imported).

Commit distance is the primary signal because __version__ is bumped only at a release: comparing version strings alone reported "you're on the latest version" to a checkout hundreds of commits behind main, for as long as the next bump took.

Both conditions are narrower than "is it behind", because available is also read by an unattended apply. GatewayOrchestrator._auto_apply_update applies git fetch + git reset --hard <oid> with no prompt — <oid> being origin/<branch> resolved once after the fetch, the same pin kirocrew update takes, so what it floor-checks is what it resets to — so:

  • "Behind" alone is true both for a checkout that is purely behind and for a DIVERGED one carrying its own commits, and the second would have those commits reset away. Only a fast-forwardable checkout is offered an update.
  • The version signal is required to come with HEAD == @{u}. A checkout that pulled a version bump and then committed on top is ahead, so its upstream still reads newer than the imported version; without that requirement the same reset would drop those commits.

The unattended apply is triggered by the version, not by commit distance. The check reports version_newer beside available, and the git branch of the auto_update path requires both. available is what the dashboard shows, and on commit distance alone that would mean any upstream commit — resetting a source checkout within 12 hours of one, where the version-only verdict only did so at a release. Requiring both keeps that path firing no more often than before. Commit distance without a version bump lights the dashboard badge, and POST /api/update is the non-destructive way to apply it.

What auto_update does on this install is derived once. update_capability.auto_update_effect() answers install (with the switch on, an available update is installed and the gateway restarts), notify (the switch cannot install here, or policy turns unattended installs off, so it only notifies), or mandatory (a policy floor this build is below installs it whatever the switch says). It is read from install shape and policy alone, before any check runs: a policy provider owns the update and installs only with an apply_command it can run; a git checkout installs only past the unattended git apply's static gates (a trusted git, a primary branch, no repository-named exec driver, tracking origin/<branch>, the pinned source); a managed venv only past the shadow apply's (POSIX, a trusted openssl, the managed venv itself, a safe HTTPS CDN, the pinned source); anything else is updated by its own updater. The gateway's update loop branches on that answer, and notify never reaches _prepare_auto_update_apply, so admission is not paused for an update the install will not apply (a provider with no apply_command, a feature-branch checkout). notify is also what a source pin produces, and no badge then points at a kirocrew update the same pin refuses. A policy with updates.unattended_apply: false turns every remaining install into notify but keeps the route, the path a person's Update takes: the provider path reads can_apply (the Update button) off it, so About disables the switch and shows its note for an install that updates only when asked. A build below the floor still answers mandatory. The effect is derived before the check and the wait for idle, so each routine install reads the pin again with nothing awaited between that read and the change: the provider path before and after its memory copy, the last of the git route's refusals before reset --hard (they run before and after its copy too), and the managed venv before and after the memory copy at the swap (run_wheel_apply's refuse_if_unattended_off), where a refusal ends deferred and the next cycle notifies. Dynamic conditions stay with the update itself: the git route still requires version_newer, the managed-venv route a newer build. A voluntary install is also withheld for a version the user put off: the update prompt's "Remind me tomorrow" (or any dismissal) and "Skip this version" write dashboard.update_nudge, and update_deferral.user_deferred_update reads it for the version the check found, so that version notifies instead of being installed and restarted unattended. When the snooze runs out the prompt opens again, and the deferral holds for one more window (REPROMPT_WINDOW_SECS, the snooze's own 24 h) so "Later" never becomes a silent install; only a prompt left unanswered for that window lets it install. A managed-venv restart already queued (_pending_update_respawn) reads the same record for _pending_update_version on every retry and waits while it holds (the git and provider routes leave that field empty: their code is already replaced on disk, and the git route reloads kiro_crew, so their queued restart is never held); a held cycle still runs the update check, so a policy floor raised meanwhile or a newer release is applied and replaces the held respawn. The record names one version, so a newer release is offered again; mandatory ignores it. With auto_update on, the managed-venv route still builds on first detection, before the user has seen a prompt; only its restart waits for an answer. The managed-venv route does not pause admission before it builds; only its restart does, through _retry_pending_update_restart, which calls _prepare_auto_update_apply. _auto_apply_wheel_update makes the first attempt, and while _pending_update_respawn is set every _run_update_checks cycle retries that restart on the short cadence instead of checking again. The status frame carries the same answer as update_auto_effect, re-derived off the loop at most once every five minutes once the update loop's first cycle has armed that refresh. A frame served BEFORE that derivation answers for itself wherever no git subprocess is needed — the packaged shapes from their baked stamp, a policy provider from the boot-frozen pins, the managed venv from its own layout — so only a checkout reads unknown, its branch and remote being what git alone can report. That matters because the update modal opens on the first boot after an app update, before any check has run. GET /api/update/check derives and records it too, and returns it: the user asked, so its git probes are warranted where a status frame could not afford them. A policy provider the CHECK resolves after the derivation (a live policy refresh) downgrades the cycle to notify: a provider owns the update, so no built-in route applies it.

The frame also carries update_bundled_by_app, the baked packaging stamp's answer to "is this the backend the desktop app bundles and launches" (bundled_by_desktop_app). It is independent of update_managed_by, which reads command on that same bundle once a policy updates provider is configured, because the provider is resolved before the desktop deferral. On such a bundle update_auto_effect reports the provider's answer (install, mandatory, or notify without a runnable apply_command), since the provider is what the gateway's loop runs; on a bundle with no provider it reports notify, the app's own updater owning the update.

auto_update is validated on read and on write. Validation and the loader run it through fields._coerce_bool(..., False): a recognized spelling is honoured ("false"/"off"/"0" read OFF, "true"/"on"/"1" read ON) and anything else unreadable reads OFF rather than being repaired to the ON default; an absent key still defaults ON. And POST /api/update/auto refuses a non-boolean enabled with 400 invalid_enabled (and a non-object body with 400 invalid_json) instead of storing it. That endpoint writes config.json, which config.local.json deep-merges OVER, so when the overlay sets auto_update it refuses with 409 auto_update_overlay_owned and writes nothing — the same refusal the trust-settings and MCP writers give an overlay-owned key — rather than a 200 the next load would undo. A successful response carries the EFFECTIVE value read back after the merge, the requested one beside it, and overlay_override, the flag (and the best-effort read, config.loader.overlay_pins) the telemetry switches share. GET /api/update/check and the channel switch carry overlay_override too, since those are where the UI reads auto_update, and GET /api/update/auto returns it alone (one overlay read, no check), which the switch reads on every mount and window focus so a pinned install shows it held with its note before any click. The POST sends a refresh frame so a second open tab stops showing the old position. A check that fails unexpectedly carries can_arm the way the feed-failure paths do, so one transient raise cannot make a managed venv look notify-only. test_every_unattended_apply_consults_the_effect_first pins that every apply branch reads it before pausing admission.

POST /api/update refuses before it moves the tree, and fast-forwards to a pinned commit rather than pulling. In order: a dirty tracked tree is 409 dirty_tree; a pre-apply git fetch that fails is 409 git_fetch_failed (500 on timeout); a divergence count it cannot read is 409 git_read_failed; a diverged checkout is 409 checkout_diverged; then @{u} is resolved ONCE to a commit OID (git rev-parse --verify @{u}^{commit} — unresolvable is 409 git_read_failed, a timeout 500 git_read_failed); then the interpreter floor of THAT commit is read with git show <oid>:pyproject.toml (then setup.cfg) and compared to the gateway's own interpreter — a floor the venv fails is 409 python_floor with the remedy in error, and a floor git could not read is 409 git_read_failed, never waved through. Only then does the handler answer {"ok": true, "status": "updating"} and start the worker, which runs git merge --ff-only <oid> — the same OID, so the revision that was floor-checked is the revision that lands, and an upstream rewritten in the window fails the merge instead of minting a merge commit — then rebuilds, pip install -e ., and restarts. A merge that fails or times out ends the worker with an error step whose detail names the command and the pinned OID; that detail is what the overlay's failure card shows and what its "Ask the agent" hand-off sends. The unattended auto-apply and kirocrew update apply the same floor gate (see the Update Command above); all three refuse with the checkout untouched.

  • Topbar shows a 📦 v<version> badge (the live __version__) — click to check and view changelog
  • If newer version found: badge turns into "📦 Update Available"
  • Clicking opens a dismissible changelog modal with rendered markdown and the update switches (components/WhatsNewAutoUpdateToggle.tsx). When a policy command owns updates (update_managed_by == "command", which the gateway publishes on every provider check, "already latest" included), the modal shows the policy note above the rows. The gateway switch reads the saved value each time the modal opens.
  • "Update Now" button: POST /api/update → fast-forward to the pinned commit → rebuild → os.execv() restart. A 409 renders inline in the modal through ErrorNotice; on a voluntary update the notice offers "Ask the agent" (the hand-off closes the modal for this page session and opens chat with the refusal), on a mandatory one it does not (the modal's enforcement is staying up) and the installer command remains the way out
  • Health indicator shows "Updating…" during the process. A failed or error progress step is terminal for both the modal and the full-screen overlay: the modal drops its restarting latch and shows the reason in the same slot a synchronous 409 uses; the overlay replaces the spinner with a failure card (ErrorNotice, "Ask the agent" + Dismiss) instead of stalling until the five-minute stuck timer
  • SSE auto-reconnects when the new process starts

Status Command

kirocrew status queries the running gateway's /api/status endpoint and prints uptime, sessions, messages, tool calls, subagents, crons, lessons, and a memory line: the gateway's own resident set (gateway_rss_mb) and the per-session tree ceiling the cleanup watchdog recycles at (watchdog_rss_max_mb, spelled out as disabled when 0). Both fields are published by /api/status for this line; kirocrew doctor prints the same two readings at the top of its Memory Pressure section, on every platform.

It exits 1 when nothing answers the resolved port (a refused connection, printed as "not running"), so a script or health check can gate on $? without parsing stdout. It exits 0 whenever a gateway answers: the stats view, a token-auth 401/403, another HTTP error, a busy timeout or an unexpected body.

App Dev Mode

kirocrew app dev <name> [--off] [--confirm-out-of-install-root] toggles an installed App Kit app into (or, with --off, out of) dev mode, which speeds the app-UI edit loop by serving UI files uncached and live-reloading the dashboard on file change. The command writes the flag out-of-process; the running gateway's watcher picks it up within one poll interval, so no gateway restart is needed. Full App Kit developer docs live in docs/app-kit/api-reference.md; the durable contract surfaces this feature introduces are:

  • Persisted schema — installed.json dev: bool (default false): a per-app flag in each app's ~/.kiro/crew/apps/<name>/installed.json. Tolerant on read (absent ⇒ false), reversible, no migration. This field is the authoritative source of truth for watching and no-store serving; enabling also records a gateway-owned operator grant binding the ui root's resolved path, which is what authorizes serving a ui root outside the install directory (see api-reference.md). Builtin apps cannot enter dev mode.
  • Endpoint — POST /api/apps/{name}/dev, body {"enabled": <bool>}, returns {"name": <name>, "dev": <bool>}. Behind standard gateway auth; emits an app_dev_mode SEL audit event. 400 for a non-boolean body, a builtin app, an unsafe app name, or a refused grant (a sensitive ui root is never grantable; an out-of-install root always answers 400 over HTTP — only the CLI flag, run on the gateway host, supplies the confirmation, because a request-body flag from the dashboard origin is app-controllable); 404 when the app is not installed. The flag is additionally operator-only against agent shells through three tiers: the builtin rule self-protection-dev-mode-out-of-root-confirm (literal text plus its argv floor) refuses any agent shell command carrying it; the flag's consumption point performs a runtime human-vs-agent check that refuses a process showing evidence of agent-shell confinement (dev_mode_operator_attestation_required) — closing runtime flag synthesis, which no command-text scan can see; and the grant record (~/.kiro/crew/apps/.dev-grants.json) is sealed read-only inside the agent OS sandbox (materialized at gateway startup so the seal always has a target), so a sandboxed process cannot write a grant at all — any grant-touching toggle from such a process is refused up front (dev_mode_grant_record_readonly; use the dashboard toggle instead). Only the operator's own terminal can supply the attestation — and both the confirmed grant and each refusal emit a SEL event (dev_mode_out_of_install_grant for the permission decision, dev_mode_grant_write for the sealed-record refusal).
  • WebSocket event — app_reload, payload {"app": <name>, "ts": <float>}, broadcast when a dev-mode app's ui/ tree changes; the dashboard reloads that app so edits appear immediately.
  • Serving behavior: while an app is in dev mode the gateway serves its UI with Cache-Control: no-store; otherwise the standard revalidation header applies.

An internal, unstable sentinel cache under ~/.kiro/crew/apps/ mirrors the set of dev-mode apps so the zero-dev-apps steady state costs one stat() per second. It is a derived cache reconciled from installed.json at watcher init (under a cross-process lock, atomic with concurrent toggles), not part of the App Kit contract — its path and format are internal and may change without notice.

Computer Use Commands

kirocrew computer {doctor [--json] | apps | call} — hand-rolled dispatch rather than argparse subparsers, because the parent CLI forwards REMAINDER (see computer-use.md).

doctor reports, in order: whether the platform is supported (macOS today; Windows and Linux report a typed refusal), whether the keystone primary enable at ~/.kiro/crew/computer_use.json is on, and the macOS TCC probe (AXIsProcessTrusted() + CGPreflightScreenCaptureAccess()). The probe is advisory and never a gate: macOS attributes a grant to the responsible parent of the process tree, so both rows can read missing while a full-fidelity capture succeeds — observed live. doctor therefore prints a responsible_hint naming the process a user should actually grant (the packaged app, or the terminal that launched a dev gateway) and says outright that "not detected" does not always mean unavailable. It never calls CGRequestScreenCaptureAccess, which would pop a system dialog from a background process.

--json is the machine form the gateway shells out to for the Settings permission rows. That indirection is deliberate: a short-lived subprocess keeps native ctypes out of the gateway, so a native fault cannot take down the gateway and with it cron, Slack and the dashboard WebSocket.

apps lists on-screen applications resolved from CGWindowListCopyWindowInfo (layer-0 windows only, never pgrep — a pgrep -n lookup returns short-lived helper pids whose accessibility tree is empty). It runs computer_list_apps through the SAME gated dispatcher as call, so it is refused while the feature is disabled, in an unattended session, or under a policy that bans computer use — the agent can run this command with bash, so an ungated version was an unauthorized read of every window title.

call runs one tool — call computer_get_state app=Finder — or a whole sequence in ONE process: call --calls '[{"tool":"computer_get_state","args": {"app":"Finder"}},{"tool":"computer_click","args":{"app":"Finder", "element_index":12}}]'. The batch form exists because element_index values only resolve against the per-process snapshot cache that produced them, so two separate invocations cannot share them. key=value arguments are JSON-decoded when they can be (element_index=3 → int, screenshot=false → bool) and kept as text otherwise (app=Finder). --json emits [{tool, text}, …]; the exit code is non-zero if any reply carries the Error: prefix, and a batch runs to completion rather than aborting at the first refusal.

call goes through computer_use.tools.dispatch_tool, the same chokepoint an agent call traverses, so the primary enable, the target policy and the secure-field floors all apply — it is a reproduction tool, not a bypass. Its session key is the attended cli_chat surface, which is what the SEL audit records. There is no separate diagnostics opt-in and no identity proof: the unattended-surface refusal that made one necessary was removed along with the rest of the computer-use governance model.

All three are human-facing. apps has an MCP twin (computer_list_apps) per the MCP-first rule; doctor is a permission diagnostic rather than a capability, so the rule does not bind it; and call adds no capability at all — it is a harness over the eleven existing MCP tools, and deliberately has no MCP twin, because a tool that runs other tools would let a model launder one per-call gate decision into many. There is deliberately no kirocrew computer state <app> — that would be a second, CLI-shaped spelling of an LLM-facing capability and would have to be an MCP tool instead (it is: computer_get_state).

Gateway Test Harness

Four composable flags let an integration test or eval harness boot a gateway deterministically, with no model and no developer-machine state:

kirocrew gateway --test-mode          # bundle: ephemeral port + json-ready + reads approval
kirocrew gateway --port auto          # OS-assigned port, avoiding a collision with a real gateway
kirocrew gateway --json-ready         # print KIROCREW_READY:{port,token,pid,home} once listening
kirocrew gateway --approval reads     # auto-approve read-only tools
kirocrew gateway --approval yolo      # auto-approve ALL tools

--json-ready is what makes the harness race-free: the caller waits for the KIROCREW_READY line instead of polling a port, and reads the token from it rather than minting one.

--approval yolo refuses to start unless KIROCREW_HOME is explicitly set to a non-default path. The flag disables every per-call approval, so pointing it at the real data home would let a test drive an operator's live sessions and credentials. The guard is a startup refusal rather than a warning because a warning in CI output is not read.