The App Store's Sync button (POST /api/apps/{name}/update inside the
running gateway) was the only way to update an installed app from its
source checkout, so every merged app change still needed a human click;
a deploy script, or a person at a terminal, could not finish the job.
`kirocrew app` had install/enable/disable/uninstall but no `update`.
Add `kirocrew app update <name> [--source PATH]`. It goes through the
running gateway over the owner-only socket the way enable/disable/
uninstall already do, because only the process that owns the old
manifest's MCP servers, agents and backend can run the swap in order
(stop, deregister, copy with data/ preserved, re-register, restart).
Unlike enable/disable it has no file-only fallback: with no gateway
reachable it exits 3 and changes nothing, since update_app alone would
leave the live gateway serving the old manifest. Without --source the
gateway updates from the source it recorded at install, a directory or
the registry entry a registry install recorded; no flag names a registry
entry, because the handler treats registry:<name> as both the entry to
clone and the app to install, so any other value would swap a second
app's files under the first one's lifecycle lock.
The verb is operator-only. It sits on the ungated argv self-protection
floor beside the gateway's own restart and self-update verbs
(self-protection-app-update, argv_floor._is_self_app_update): an agent
shell is refused before the process starts, with no catalog row and no
opt-out, because a prompt-injected turn with the sandbox off could
otherwise mint the owner credential and install and launch
attacker-authored code under the gateway. The sibling app verbs are not
floored; only this one swaps a RUNNING app's tree. People and deploy
scripts outside the gateway keep the verb; inside Kiro Crew a cron
command job is vetted by the same gate at authoring and refused. The
floor matches the dispatching shape, app update <name>: a bare `app
update` or `app update --help` is answered by argparse before the
handler runs and is not refused, and an installed app's name is
kebab-case, so it is always a plain operand and always refused however
it is quoted or surrounded. Launched through xargs or parallel the name
is appended at exec time from stdin or a file, so there the nameless
argv counts as carrying it (`xargs kirocrew app update <<< name`,
`xargs -a names ...`, `... < names` are refused; the piped form was
already rebuilt with its words). It is an argv-tier guard like the
restart floor, over the command the shell is about to run, not a sandbox
over what a program that shell starts may itself spawn; the docs say so.
An inline program has no such argv, so kiro_crew.cli_commands (the
dispatch's handler half) and kiro_crew.app_lifecycle_client (which mints
the local dashboard token every app action rides on) join the inline
credential-mint surface, in the dotted module spelling only: `python -c`
importing either is judged by the existing mint floor, the way
kiro_crew.cli already is, while reading or patching the source files by
path stays ordinary inline work.
Exit codes are switched on the gateway's machine-readable `code`, never
its prose: 0 updated, 3 no gateway answered, 4 app_source_name_mismatch
(the source's app.json names another app), 5 app_not_installed /
app_lifecycle_not_gateway, 1 any other refusal, an empty or unresolvable
--source (only an ABSENT flag means the recorded source: `--source
"$BUILD_DIR"` with the variable unset must not silently update from the
recorded checkout and exit 0) or a timeout whose outcome is unknown; 2 stays argparse's usage error.
The update route's two early refusals gain those codes and the manager's
expected_name guard gains its own; error-code-baseline.json is
regenerated, and the security package's line budget is re-pinned
(27,761 -> 27,828) with the reason recorded where that test asks for it. A success answers previousVersion / version beside the
registration counts -- both read from the installed record under the
lifecycle lock, the previous one right after it is taken and the new one
before it is released, because two updates of one app serialize on that
lock and a pair assembled from the handler-entry snapshot named the
version the other update started from -- and the CLI prints both plus
the re-registered agent, skill, MCP server and cron counts.
AppGatewayError now carries `code`; a transport failure during the
credential mint is AppGatewayUnreachable.
The route refuses, before it tears anything down, what update_app was
going to refuse anyway. For a registry:<other> source it refuses before
taking the lock. For a local source it runs the same validation inside
the lifecycle lock but before stop_app_backend and the deregistration,
off the loop since the path is caller-supplied: a source that is not a
directory (source_not_directory), one whose app.json is missing, cannot
be read or does not parse or validate (app_source_invalid, with
update_app's own words), or one whose manifest names another app
(app_source_name_mismatch). Should update_app still raise after the
teardown, the exception is a failed result: the rollback branch
re-registers and restarts the app and the answer is a 400, not a 500
with the app left down. A mistyped --source therefore leaves the running
app untouched instead of stopping its backend, deregistering its
resources, hitting update_app's refusal and rolling back for a request
that is never applied; update_app's own checks stay authoritative under
the lock, and only a regular file is opened -- pinned on every platform
with a directory named app.json, and with a FIFO where the host has one,
in a test that never skips. Every refusal carries a code and the same
SEL audit line.
The verb's only transport is the gateway's Unix socket, so without
AF_UNIX (Windows, sandboxed shells that cannot reach the socket) it is
unavailable: the exit-3 message says so and names the dashboard's Sync
on a host without AF_UNIX, and says "start the gateway, or use Sync from
a sandboxed shell" elsewhere. The docs say the same.
Docs: cli.md table, app-kit-platform.md (two front doors of Update, the
response contract, the pre-teardown refusal, the floor), security.md
(the self-protection floor lists), the user-facing apps page, and the
App Kit publishing and getting-started guides.
Problem / Motivation
Goal: An installed app can be updated from its source checkout with one terminal command,
kirocrew app update <name>, that does exactly what the App Store's Sync button does.The App Store's Sync button is the only way to update an installed app from its
source checkout. It is
POST /api/apps/{name}/updateinside the running gateway,and only that process can do the swap correctly: stop the app's backend, deregister
the old manifest's MCP servers, agents, skills and crons, copy the new tree with
data/preserved, re-register, restart.kirocrew apphas install, enable,disable and uninstall, but no
update— so after every merged app change a humanstill has to open the dashboard and click. A deploy script, or a person at a
terminal, that just merged the change cannot finish the job.
Why it matters
Every app iteration ends in a manual click, and the alternative people reach for —
calling
kiro_crew.apps.manager.update_app()directly, or re-runninginstall— swapsthe files while the gateway keeps serving the old manifest, which is exactly the
half-updated state Sync exists to prevent. With the verb,
kirocrew app update <name>is one scriptable step with exit codes a caller can switch on.
The verb is operator-only. It sits on the ungated argv self-protection floor
beside the gateway's own restart and self-update verbs (
self-protection-app-update,security/argv_floor.py::_is_self_app_update): an agent shell is refused before theprocess starts, with no catalog row and no opt-out -- an argv-tier guard like
restart's,reading the command line the shell hands over (however quoted, wrapped, or fed a name
through
xargs), not a sandbox over what a program that shell starts may itself spawn. The reason, applied at the author'sdirection after the GPT lane raised it on every head: an update is the one verb that
replaces the code of an app the operator has ALREADY trusted and enabled and restarts
its backend on the new code with no new consent moment, so a prompt-injected turn with
the sandbox off could ride those existing grants to launch attacker-authored code under
the gateway -- where a fresh install is a new store entry whose execution stays denied
until the operator grants that app trust. People and deploy scripts outside the
gateway (a CI job, the system's own cron) keep the verb; inside Kiro Crew it is refused
wherever the gate runs -- an agent's shell, and a cron
commandjob, whichmcp_cron._vet_shell_commandvets with the sameis_deniedat authoring -- so an agentthat wants an app updated asks a human, exactly as it does for Sync today.
Not a goal
appverbs, or shipping an MCP twin.install/enable/disable/uninstallstay reachable from an agent shell exactly as today; onlyapp updatejoins the floor. Why this verb alone: an update swaps a RUNNING app's tree under the trust and enable grants the operator already gave it and restarts the backend on the new code with no new consent moment (only apermissions.sessionApprovalwidening parks it disabled), whereas a fresh install is a new store entry whose execution the third-party policy denies until the operator grants that app trust, and whose grant is repository-bound. Whether the siblings should follow anyway --uninstall+installof an evil tree under the same name is the path a reviewer named -- is the maintainers' call, and an MCP tool for a verb agents are not meant to run would be the wrong shape.installed.json-only fallback when no gateway answers, so the verb is unavailable without anAF_UNIXtransport (Windows, sandboxed shells) — the dashboard's Sync stays the way there.enable/disable/uninstall, the base install/update entry, or sibling handlers. They keep their exact behaviour and output; this PR touches only the update verb, the update route's refusals and response fields, and theexpected_nameguard's error code.What changed (motivation → approach → change)
kirocrew app update <name> [--source PATH]enable/disable/uninstallalready do (app_lifecycle_client.toggle_app, actionupdate). Without--sourcethe gateway updates from the source it recorded at install — a directory, or the registry entry a registry install recorded, which it re-clones.update_appalone would leave the live gateway stale, so unlikeenable/disablethere is deliberately noinstalled.json-only path. The request travels over the gateway's owner-only Unix socket and nothing else, so without anAF_UNIXtransport (Windows, sandboxed shells that cannot reach the socket) the verb is unavailable: the exit-3 message on such a host says so and names the dashboard's Sync instead of "start the gateway", which there could never help.app.jsonnames a different app · 5 not installed / lifecycle not the gateway's · 1 any other refusal, a--sourcethat is empty (what--source "$BUILD_DIR"sends with the variable unset -- refused rather than read as "use the recorded source") or cannot be resolved, a timeout, or a transport failure mid-action whose outcome is unknown. 2 is left to argparse's own usage error so a script can tell a bad flag from a refusal. The line saysgateway refused:only for an answer that carries acode; a codeless failure -- an older gateway's prose-only answer, or a socket that dropped after the request went out -- readsupdate did not complete:so an operator does not take an unknown outcome for an answer.codescode(app_not_installed,app_lifecycle_not_gateway; theexpected_nameguard inupdate_appgainsapp_source_name_mismatch). The CLI switches on the code, never on the prose.error-code-baseline.jsonregenerated for the two sites that gained codes.handle_update_appnow refuses, for every caller (dashboard Sync included), aregistry:<other>source whose entry name is not the app being updated — 400,code: app_source_name_mismatch, before the lifecycle lock is taken. Before,install_from_registry(<other>)ran under this app's lock, swapped the OTHER app's files, and the response reported this app unchanged. Both branches refuse before anything is stopped (next row).update_appis going to refuse is refused BEFORE the teardownhandle_update_appanswers, inside the lifecycle lock but beforestop_app_backend/ deregistration and off the loop throughsubprocess_executor()(the path is caller-supplied), whatupdate_appwould refuse anyway: a--sourcethat is not a directory (400,code: source_not_directory, the install preflight's code), one whoseapp.jsonis missing, cannot be read (EACCES / EIO) or does not parse or validate -- a nameless manifest included -- (400,code: app_source_invalid, with_validate_source_path's own words), and one whose manifest names another app (400,code: app_source_name_mismatch, exit 4). A read failure is a refusal too, not a fall-through:update_appre-reads the same file after the teardown and raises there, past its own rollback branch. And shouldupdate_appstill raise after the teardown, the handler treats the exception as a failed result, so the same rollback branch re-registers and restarts the app and the answer is a 400 naming the error rather than a 500 with the app left down. Without this every such request -- and a mistyped--sourceis the likeliest input the new flag admits -- stopped the app's backend, deregistered its MCP servers/agents/skills/crons, hitupdate_app's refusal, and rolled back: a take-down for a request that is never applied, and an app left down if the rollback's re-register or restart fails.update_app's own checks stay as the authoritative ones under the lock. Only a regular file is opened (a FIFO or a device asapp.jsonwould otherwise block the read under the lock).previousVersion/version, both read from the installed record on the executor and both under the lifecycle lock -- the previous one right after the lock is taken, the new one before it is released. Two updates of one app serialize on that lock, so a pair assembled from the handler-entry snapshot and a post-lock read named the version the OTHER update started from (1.0.0 -> 2.0.0for a swap that went2.0.0 -> 2.0.0). The CLI prints them plus the re-registered agent, skill, MCP server and cron counts, or one line saying nothing was re-registered when the update left the app disabled.kirocrew app update <name>from an agent shell is refused_is_self_app_updateinsecurity/argv_floor.pymatches the product CLI as the argv's own program withapp update <name>as its leading operands (direct andpython -m kiro_crewforms, through the same shell de-escaping the sibling floors see;_operands_lead_withgains aNoneelement meaning "any operand"), wired into the ungated loop insecurity/__init__.py::is_deniedasself-protection-app-update, with its id in_SELF_PROTECTION_UNGATED_FLOOR_IDSand a structural note in_SELF_PROTECTION_FLOOR_NOTES. No catalog row, so no toggle. The spec demands the name operand because that is the dispatching shape: a barekirocrew app updateis an argparse usage error andkirocrew app update --helpprints usage, both before the handler runs, so the usage form stays readable with no flag parsing in the floor. An installed app's name is kebab-case, so it is always a plain operand and always refused -- quoted,$'…'-quoted, after--, or beside any substitution or help-flag noise (app update evil-app $(: --help )is refused). The only nameless-by-grammar forms,app update -- --helpandapp update <(: …), hand argparse a word that can never be an installed app, so the gateway answersapp_not_installedand nothing is stopped or swapped. A launcher that APPENDS the name at exec time --xargs kirocrew app update <<< my-app,xargs -a names …,xargs … < names,parallel -a …-- counts as supplying it (_operands_with_appended_wildcardspads a spec's missing all-wildcard tail when the CLI is the command such a launcher runs; the piped `echo nameThe verb goes through the gateway because the swap is a sequence only the process
owning the old resources can run in order: stop the backend, deregister, copy with
data/kept, re-register, restart. A CLI-sideupdate_app()call was rejected as theprimary path for that reason.
--sourceis resolved to an absolute path in the CLI'sown process (the gateway would resolve a relative path against its cwd); a path
that cannot be resolved is a one-line refusal rather than a traceback, and so is an
empty
--source, since only an ABSENT flag means the recorded source. The exit-3message is platform-aware: on a host without
AF_UNIXit says the verb is unavailableand names Sync; elsewhere it says start the gateway, or use Sync from a sandboxed
shell that cannot reach its socket. There is no
flag naming a registry entry: the handler treats a
registry:<name>source as boththe entry to clone and the app to install, so the only legitimate value is the app's
own name, which the bare verb already sends — and the route now refuses any other
(the table row above).
AppGatewayErrorcarries the gateway'scode, and a transport failure during the credential mint — a socket that exists butnever answers — is
AppGatewayUnreachable, so it lands on exit 3 with the other"nothing was changed" cases instead of on the generic 1.
enable/disable/uninstallkeep their exact behaviour and output.
Docs: the CLI spec table, the app-kit platform spec (the two front doors of Update,
the response contract, the pre-teardown refusal, the floor), the security spec (the
self-protection floor lists), the user-facing apps page (
kirocrew app updatebesideSync), and the App Kit publishing/getting-started guides — the latter now names the
store action by its actual button label, Sync. All of them say where the verb is
unavailable (no
AF_UNIX: Windows, sandboxed shells), that Sync is the way there, andthat the verb is operator-only: an agent's shell is refused from running it.
Where it lives: the parser in
src/kiro_crew/cli.py, the verb insrc/kiro_crew/cli_commands.py(_handle_app_update), the socket client insrc/kiro_crew/app_lifecycle_client.py, the route codes, the pre-teardownrefusal and the response fields in
src/kiro_crew/apps/routes.py, the guard's code insrc/kiro_crew/apps/manager.py, the floor insrc/kiro_crew/security/argv_floor.py(
_is_self_app_update) with its wiring insecurity/__init__.pyand its id and notein
security/denied_rules.py, and the user-facing page atsrc/kiro_crew/docs/apps.md.Backwards compatibility
Compatible:
updateis a new subcommand; the route's refusals and success body onlygain fields (
code,previousVersion,version) beside the ones they already carry,and the dashboard reads none of the new ones.
AppGatewayError(message)stillconstructs with one positional argument. Two behaviour changes on the route: the
registry-source guard (a request that used to swap a different app's files and answer
"unchanged" is now a 400 with a code) and the local-source refusal before the teardown
(a source
update_appwas going to refuse -- not a directory, no or invalidapp.json,another app's name -- is refused with the same 400 before the app's backend and
registrations are stopped and rolled back; the two non-mismatch classes gain codes,
source_not_directoryandapp_source_invalid, whereupdate_app's prose carriednone). No caller can rely on the take-down: the response is a refusal either way. The
self-protection floor is new and matches only the new verb, so no command that runs
from an agent shell today is refused by it.
Tests
test/test_app_update_cli.py(new): the real argparse hop forupdateand--source, the required name, and that--registryis not a flag; the happy pathagainst a faked owner-only socket (request shape, no body without an override,
rendered version transition and counts, nothing registered locally);
--sourcetravelling as an absolute path; a
--sourcewhose resolution raises (a symlinkloop) refusing on exit 1 with no request sent, and an empty or blank
--sourcerefusing the same way instead of being read as the recorded source; the exit-3 message naming both
remedies on a host with
AF_UNIX, and saying the verb is unavailable (and pointingat Sync, not "start the gateway") when
socket.AF_UNIXis absent; the disabled-apprendering;
terminal-control sanitisation of gateway strings; each exit — 5
(
app_not_installed,app_lifecycle_not_gateway), 3 (no local secret, no socket,a socket that will not mint), 4 (
app_source_name_mismatch, on an HTTP error andon an
ok: falsebody), 1 (an unclassified refusal, a prose-only answer, atimeout); that
AppGatewayErrorcarriescodewhile a transport failureDURING the action is not classified as unreachable; and that neither a prose-only
answer nor a mid-action socket drop is printed as
refused(the drop readsupdate did not complete: gateway stopped answering … check the dashboard).test/test_apps_routes_coverage.py: the two refusals carry their codes; anend-to-end local update through the route reports
previousVersion/version,keeps a file under
data/, lands the new version in the installed record, andperforms every post-swap read of that record off the loop thread (verified to fail
against an on-loop read); two concurrent updates of one app (v2 and v3 sources under
asyncio.gather) report transitions that CHAIN -- one from 1.0.0, the other fromwhere the first ended -- and the installed record ends where the second did (fails
against the handler-entry snapshot: both answered
previousVersion: 1.0.0); asource naming another app is refused with
app_source_name_mismatch, leaves theinstalled version untouched, never calls
stop_app_backendor_deregister_app_off_loop(verified to fail against a handler without thepreflight), and reads the manifest off the loop thread (verified to fail against an
on-loop call); a directory without
app.jsonand a path that does not exist arerefused the same way --
app_source_invalid/source_not_directory,update_app'swords, nothing stopped or deregistered, version untouched (fails against the
previous head, which tore down and rolled back); a present-but-unreadable
app.json(from_json_fileraisingPermissionError) is refused the same way withnothing stopped; an
OSErrorout ofupdate_appitself after the teardown stillruns stop → deregister → register → start and answers 400 with the error (both fail
against the previous head: teardown with no rollback behind a 500); the preflight itself answers the
(code, detail)update_appwould give for another app's tree, an empty directory,a missing path, a plain file, a non-JSON, non-object and nameless manifest,
Nonefor a matching source, never a traceback, and never opens an
app.jsonthat isnot a regular file -- pinned with a DIRECTORY named
app.json, whichis_file()rejects on every platform so the test runs on Windows too (no platform skip),
plus a real FIFO as a second assertion where the host has
os.mkfifo;a
registry:<other>source is refused with the mismatch code beforeinstall_from_registryis called at all; and the pre-existing stop-before-deregisterordering test drives the teardown with a source that passes the preflight.
test/test_security_gate_liveness.py: the security package's line budget is re-pinned27,761 → 27,828 with the reason written above the number, as that test requires --
the 67 lines are the floor predicate and launcher rule, the floor note and id, the
two mint-surface modules with their comment, and one row each in the floor loop, the
facade owner table and its
TYPE_CHECKINGblock (test_security_facade.pypins thatthe two lists agree); the per-file cap and the facade share are untouched.
test/test_denied_commands_security.py:self-protection-app-updatejoins theungated-floor enumerations the suite already pins (template walk with every
interposed global flag, shell-dressing walk on the
app updateoperands, thefloor-id set equals the test's map and stays disjoint from the catalog); the
genuine-cases walk refuses
kirocrew app update my-app, the flagged and--sourceforms andpython -m kiro_crew app update, each with the id on therefusal's first line and the structural note on the second; the no-opt-out check
refuses it with every built-in rule disabled; and a new test pins that the sibling
verbs (
list/info/enable/disable/install/uninstall),kirocrew app --help,the nameless forms (bare
app update,--help/-h/--hel, with-v, in themodule form, with a redirection and a pipe), the two nameless-by-grammar forms
(
-- --help,<(: --help )), the xargs/parallel-launched nameless forms asREFUSED (here-string,
-a file,< file,-n1 -P4, a path-spelledxargs, undersudo, the module form, and the piped form) with a sibling verb under xargs andxargs on another command before the usage form still allowed, and
echo/grep/cat/lscommands mentioning thewords stay allowed, while every form carrying a name is refused: plain, quoted,
$'…'-quoted, after--, with--source, inbash -candcd … &&, beside--help/--help=1/-hx/--source=--help, beside the substitution decoys(
$(: --help ),`: --help `,"$(: --help)",${H:---help}), and as ashell variable (
$H). Checked against argparse and bash: the help forms exit 0before the handler runs,
-- --helpdispatches for a name no app can have, and the$(: --help )and backtick decoys hand the program no--helpat all.scripts/deny_diff.py(upstream main vs this head) over 17 probes: newly refused =the named verb (with and without
--help) and the two decoys; every nameless formand every sibling verb unchanged. A second new test pins the inline surface:
python -cprograms importingkiro_crew.cli_commandsorkiro_crew.app_lifecycle_client(theimport … as,from kiro_crew import …,stdin
python3 -andimportlib.import_moduleforms) are refused bycredential-exfil-kirocrew-token, whilekiro_crew.apps.manager/kiro_crew.cli_helpersimports,grep/catof those files,pyteston theverb's tests, and inline programs that
open()/Path()the two source files(
ast.parse, a line count, a patch script, in the/and the Windows\pathspelling) stay allowed.
test/test_app_manager.py: theexpected_nameguard's result carries the code.Manual verification
Run end to end against a live gateway booted from this head with an isolated
KIROCREW_HOME(kirocrew gateway --port 43590 --no-tunnel --no-crons): installv1.0.0 of a demo app, enable it, write a file under its
data/, update from a v1.1.0tree; then each refusal exit, reading the gateway's own SEL audit log to show what the
refused request did and did not do; then stop the gateway and run the verb again.
The data file survived, the new skill text is on disk, the installed record moved to
1.1.0, the refused update left the version untouched and stopped and deregistered
nothing (the audit log shows the contrast with a tree lacking the check), and with no
gateway nothing changed. The transcript above was taken from the previous head; this
head changes what the refused-source and version paths do only in the ways the route
tests pin (the typo'd-source refusal before the teardown, both versions read under the
lock), and the mismatch refusal it shows is unchanged.
The floor, evaluated by this tree's own gate (
security.is_deniedover the built-inrules, the same call the shell tool's approval hook makes):
Related Issues
no linked issue: opened from a workflow need (finishing an app update from the
terminal or a deploy script that just merged it), not from a tracked issue.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)