You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
If KIROCREW_PROJECT_DIR env var is already set, use it
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.
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.
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
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.
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.
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 — ActiveStateactive (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.
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
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.
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.
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
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=1into 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:
Saves KIROCREW_PROJECT_DIR to ~/.kiro/crew/project_dir
Installs agent config to ~/.kiro/agents/kirocrew.json
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
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:
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.
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.
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:
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:
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.
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.
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.
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
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 ⏭
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
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
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
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
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.
Slack credentials (optional)
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
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
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.txtkas_engine: line uses) -- and kiro-cli is not spawned, present or not.
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
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
Reinstalls backend via pip install -e .
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:
An explicit --port N flag (0 counts — the check is is not None).
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.)
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.
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.
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:
the pid recorded in run/gateway-<port>.pid (written 0600 inside the
0700run/ dir, which is on the is_sensitive_path floor, so neither
another local user nor an agent file tool can write it);
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;
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.
_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)
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:
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.
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.
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.
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).
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.
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.
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.
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 Idshow 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 — ActiveStateactive 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.
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:
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.
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).
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.
~/.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.jsondev: 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 nokirocrew 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.