Skip to content

feat(cli): add kirocrew app update <name> mirroring App Store Sync - #14255

Closed
ash663 wants to merge 1 commit into
kirodotdev:mainfrom
ash663:feat/app-update-cli
Closed

ash663 wants to merge 1 commit into
kirodotdev:mainfrom
ash663:feat/app-update-cli

Conversation

@ash663

@ash663 ash663 commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

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}/update inside 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 app has install, enable,
disable and uninstall, but no update — so after every merged app change a human
still 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-running install — swaps
the 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 the
process 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's
direction 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 command job, which
mcp_cron._vet_shell_command vets with the same is_denied at authoring -- so an agent
that wants an app updated asks a human, exactly as it does for Sync today.

Not a goal

  • Flooring the sibling app verbs, or shipping an MCP twin. install / enable / disable / uninstall stay reachable from an agent shell exactly as today; only app update joins 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 a permissions.sessionApproval widening 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 + install of 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.
  • Any update path that bypasses the running gateway. There is no CLI-side or installed.json-only fallback when no gateway answers, so the verb is unavailable without an AF_UNIX transport (Windows, sandboxed shells) — the dashboard's Sync stays the way there.
  • Updating an app from a registry entry other than its own. The bare verb re-clones the registry source recorded at install; there is no flag naming another entry.
  • Changing 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 the expected_name guard's error code.

What changed (motivation → approach → change)

Piece What it does
kirocrew app update <name> [--source PATH] The App Store's Sync from a terminal. Goes through the running gateway over the owner-only socket, the way enable/disable/uninstall already do (app_lifecycle_client.toggle_app, action update). Without --source the gateway updates from the source it recorded at install — a directory, or the registry entry a registry install recorded, which it re-clones.
No file-only fallback With no gateway reachable it exits 3 and changes nothing, and says why. update_app alone would leave the live gateway stale, so unlike enable/disable there is deliberately no installed.json-only path. The request travels over the gateway's owner-only Unix socket and nothing else, so without an AF_UNIX transport (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.
Exit codes 0 updated · 3 no gateway answered · 4 the source's app.json names a different app · 5 not installed / lifecycle not the gateway's · 1 any other refusal, a --source that 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 says gateway refused: only for an answer that carries a code; a codeless failure -- an older gateway's prose-only answer, or a socket that dropped after the request went out -- reads update did not complete: so an operator does not take an unknown outcome for an answer.
Gateway codes The update route's refusals carry a machine-readable code (app_not_installed, app_lifecycle_not_gateway; the expected_name guard in update_app gains app_source_name_mismatch). The CLI switches on the code, never on the prose. error-code-baseline.json regenerated for the two sites that gained codes.
Route behaviour change: registry source naming another app handle_update_app now refuses, for every caller (dashboard Sync included), a registry:<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).
Route behaviour change: a local source update_app is going to refuse is refused BEFORE the teardown handle_update_app answers, inside the lifecycle lock but before stop_app_backend / deregistration and off the loop through subprocess_executor() (the path is caller-supplied), what update_app would refuse anyway: a --source that is not a directory (400, code: source_not_directory, the install preflight's code), one whose app.json is 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_app re-reads the same file after the teardown and raises there, past its own rollback branch. And should update_app still 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 --source is the likeliest input the new flag admits -- stopped the app's backend, deregistered its MCP servers/agents/skills/crons, hit update_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 as app.json would otherwise block the read under the lock).
Response fields A successful update answers 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.0 for a swap that went 2.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.
Self-protection floor: kirocrew app update <name> from an agent shell is refused _is_self_app_update in security/argv_floor.py matches the product CLI as the argv's own program with app update <name> as its leading operands (direct and python -m kiro_crew forms, through the same shell de-escaping the sibling floors see; _operands_lead_with gains a None element meaning "any operand"), wired into the ungated loop in security/__init__.py::is_denied as self-protection-app-update, with its id in _SELF_PROTECTION_UNGATED_FLOOR_IDS and 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 bare kirocrew app update is an argparse usage error and kirocrew app update --help prints 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 -- --help and app update <(: …), hand argparse a word that can never be an installed app, so the gateway answers app_not_installed and 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_wildcards pads a spec's missing all-wildcard tail when the CLI is the command such a launcher runs; the piped `echo name

The 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-side update_app() call was rejected as the
primary path for that reason. --source is resolved to an absolute path in the CLI's
own 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-3
message is platform-aware: on a host without AF_UNIX it says the verb is unavailable
and 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 both
the 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). AppGatewayError carries the gateway's
code, and a transport failure during the credential mint — a socket that exists but
never answers — is AppGatewayUnreachable, so it lands on exit 3 with the other
"nothing was changed" cases instead of on the generic 1. enable/disable/uninstall
keep 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 update beside
Sync), 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, and
that 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 in
src/kiro_crew/cli_commands.py (_handle_app_update), the socket client in
src/kiro_crew/app_lifecycle_client.py, the route codes, the pre-teardown
refusal and the response fields in src/kiro_crew/apps/routes.py, the guard's code in
src/kiro_crew/apps/manager.py, the floor in src/kiro_crew/security/argv_floor.py
(_is_self_app_update) with its wiring in security/__init__.py and its id and note
in security/denied_rules.py, and the user-facing page at src/kiro_crew/docs/apps.md.

Backwards compatibility

Compatible: update is a new subcommand; the route's refusals and success body only
gain fields (code, previousVersion, version) beside the ones they already carry,
and the dashboard reads none of the new ones. AppGatewayError(message) still
constructs 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_app was going to refuse -- not a directory, no or invalid app.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_directory and app_source_invalid, where update_app's prose carried
none). 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 for update and
    --source, the required name, and that --registry is not a flag; the happy path
    against a faked owner-only socket (request shape, no body without an override,
    rendered version transition and counts, nothing registered locally); --source
    travelling as an absolute path; a --source whose resolution raises (a symlink
    loop) refusing on exit 1 with no request sent, and an empty or blank --source
    refusing 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 pointing
    at Sync, not "start the gateway") when socket.AF_UNIX is absent; the disabled-app
    rendering;
    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 and
    on an ok: false body), 1 (an unclassified refusal, a prose-only answer, a
    timeout); that AppGatewayError carries code while a transport failure
    DURING 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 reads
    update did not complete: gateway stopped answering … check the dashboard).
  • test/test_apps_routes_coverage.py: the two refusals carry their codes; an
    end-to-end local update through the route reports previousVersion/version,
    keeps a file under data/, lands the new version in the installed record, and
    performs 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 from
    where the first ended -- and the installed record ends where the second did (fails
    against the handler-entry snapshot: both answered previousVersion: 1.0.0); a
    source naming another app is refused with app_source_name_mismatch, leaves the
    installed version untouched, never calls stop_app_backend or
    _deregister_app_off_loop (verified to fail against a handler without the
    preflight), and reads the manifest off the loop thread (verified to fail against an
    on-loop call); a directory without app.json and a path that does not exist are
    refused the same way -- app_source_invalid / source_not_directory, update_app's
    words, 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_file raising PermissionError) is refused the same way with
    nothing stopped; an OSError out of update_app itself after the teardown still
    runs 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_app would give for another app's tree, an empty directory,
    a missing path, a plain file, a non-JSON, non-object and nameless manifest, None
    for a matching source, never a traceback, and never opens an app.json that is
    not a regular file -- pinned with a DIRECTORY named app.json, which is_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 before
    install_from_registry is called at all; and the pre-existing stop-before-deregister
    ordering 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-pinned
    27,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_CHECKING block (test_security_facade.py pins that
    the two lists agree); the per-file cap and the facade share are untouched.
  • test/test_denied_commands_security.py: self-protection-app-update joins the
    ungated-floor enumerations the suite already pins (template walk with every
    interposed global flag, shell-dressing walk on the app update operands, the
    floor-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
    --source forms and python -m kiro_crew app update, each with the id on the
    refusal'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 the
    module form, with a redirection and a pipe), the two nameless-by-grammar forms
    (-- --help, <(: --help )), the xargs/parallel-launched nameless forms as
    REFUSED (here-string, -a file, < file, -n1 -P4, a path-spelled xargs, under
    sudo, the module form, and the piped form) with a sibling verb under xargs and
    xargs on another command before the usage form still allowed, and echo/grep/cat/ls commands mentioning the
    words stay allowed, while every form carrying a name is refused: plain, quoted,
    $'…'-quoted, after --, with --source, in bash -c and cd … &&, beside
    --help / --help=1 / -hx / --source=--help, beside the substitution decoys
    ($(: --help ), `: --help `, "$(: --help)", ${H:---help}), and as a
    shell variable ($H). Checked against argparse and bash: the help forms exit 0
    before the handler runs, -- --help dispatches for a name no app can have, and the
    $(: --help ) and backtick decoys hand the program no --help at 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 form
    and every sibling verb unchanged. A second new test pins the inline surface:
    python -c programs importing kiro_crew.cli_commands or
    kiro_crew.app_lifecycle_client (the import … as, from kiro_crew import …,
    stdin python3 - and importlib.import_module forms) are refused by
    credential-exfil-kirocrew-token, while kiro_crew.apps.manager /
    kiro_crew.cli_helpers imports, grep/cat of those files, pytest on the
    verb'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 \ path
    spelling) stay allowed.
  • test/test_app_manager.py: the expected_name guard'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): install
v1.0.0 of a demo app, enable it, write a file under its data/, update from a v1.1.0
tree; 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.

# isolated gateway from this branch: KIROCREW_HOME=/tmp/kc-verify/home, kirocrew gateway --port 43590 --no-tunnel --no-crons
$ kirocrew app enable demo-sync-app
… applying enable for demo-sync-app through the running gateway (may take up to 5 minutes)
✅ enabled demo-sync-app
   Agents registered: 0
   Skills registered: 1
exit=0

$ echo keep-me > $KIROCREW_HOME/apps/demo-sync-app/data/notes.txt

$ kirocrew app update demo-sync-app --source /tmp/kc-verify/src-1.1.0/demo-sync-app
… applying update for demo-sync-app through the running gateway (may take up to 5 minutes)
✅ updated demo-sync-app v1.0.0 -> v1.1.0
   Version: 1.0.0 -> 1.1.0
   Agents registered: 0
   Skills registered: 1
   MCP servers registered: 0
   Crons registered: 0
exit=0

$ kirocrew app list | grep demo
demo-sync-app             1.1.0      enabled    Demo Sync App
$ cat $KIROCREW_HOME/apps/demo-sync-app/data/notes.txt
keep-me
$ head -3 $KIROCREW_HOME/apps/demo-sync-app/skills/demo-skill/SKILL.md
---
name: demo-skill
description: demo skill v1.1.0

$ kirocrew app update ghost-app
… applying update for ghost-app through the running gateway (may take up to 5 minutes)
❌ gateway refused: app 'ghost-app' not installed
exit=5

$ kirocrew app update demo-sync-app --source /tmp/kc-verify/src-other/other-app
… applying update for demo-sync-app through the running gateway (may take up to 5 minutes)
❌ gateway refused: source manifest name 'other-app' does not match app 'demo-sync-app'
exit=4

$ kirocrew app list | grep demo   # untouched after the refused update
demo-sync-app             1.1.0      enabled    Demo Sync App

$ # what the gateway did, from its SEL audit log: the successful update deregisters and re-registers around
$ # "app_update completed"; the refused request is ONE "app_update failed" line -- nothing was stopped or deregistered
$ jq -r 'select(.resources|test("demo-sync-app")) | select(.operation|test("skills|app_update")) | "\(.timestamp[11:19]) \(.operation) \(.outcome) \(.error // "")"' $KIROCREW_HOME/security_events.jsonl | tail -4
20:53:20 deregister_skills completed 
20:53:20 register_skills completed 
20:53:20 app_update completed 
20:53:24 app_update failed source manifest name 'other-app' does not match app 'demo-sync-app'
$ # for contrast, the same refused request in the same log from a tree WITHOUT the pre-teardown check: torn down and rolled back first
19:05:04 deregister_skills completed 
19:05:04 register_skills completed 
19:05:04 app_update failed source manifest name 'other-app' does not match app 'demo-sync-app'

# throwaway gateway stopped, then:
$ kirocrew app update demo-sync-app
❌ no running gateway was reached, so demo-sync-app was not updated. An update has to run inside the gateway -- it stops the app's backend, swaps the files with data/ preserved and re-registers the new manifest's resources -- so there is no file-only fallback. Start the gateway and run this again -- or, if it is running and this shell is sandboxed away from its socket, use Sync in the dashboard.
exit=3

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_denied over the built-in
rules, the same call the shell tool's approval hook makes):

$ kirocrew app update demo-sync-app --source /tmp/kc-verify/src-1.1.0/demo-sync-app
-> Blocked by security policy: self-protection-app-update
   Matched structurally on the command's argv: the product CLI is the argv's own program and its leading subcommands are 'app update', which replaces an installed app's code inside this gateway (the App Store's Sync). This floor has no catalog row and no opt-out; the update is the operator's to run, from their own terminal or the dashboard's Sync button.

$ kirocrew app enable demo-sync-app
-> ALLOWED

$ kirocrew app list
-> ALLOWED

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

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

@ash663
ash663 requested review from a team and chenmingwei23 September 26, 2026 16:19
@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Sep 26, 2026
@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

Intent: Give kirocrew app an update <name> verb that is the App Store's Sync from a terminal — the same POST /api/apps/{name}/update inside the running gateway, with exit codes a script can switch on — so an app change can be finished without a dashboard click.
Not a goal: No file-only update path (the gateway must own the swap); no change to what enable/disable/uninstall do or print; no new denied rule or MCP tool — whether agents should hold this verb, and how, is left to the maintainers as asked in the body.

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Sep 26, 2026
@ash663
ash663 force-pushed the feat/app-update-cli branch from 1a76671 to bce4528 Compare September 26, 2026 17:20
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 26, 2026
@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 16754d4c1d9f2558c287814565fc8f809595223f via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Confirm the deferred maintainer call: that repository-bound trust adequately fences the uninstall+install same-name path the PR leaves off the floor.

Suggestions

  • The registry-source mismatch guard fixes a live pre-existing bug (Sync with registry:<other> swapped a different app's files under this app's lock); consider flagging it for changelog visibility at release, since it affects the dashboard path independently of the new verb.

[DESIGN-REVIEWED] 16754d4

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of 16754d4c1d9f2558c287814565fc8f809595223f via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The --help exemption in the new floor buys nothing its siblings have — and it alone forces the xargs/parallel padding machinery.

Not justified as shipped

  • Item 10 — oversized: the None spec element, _OPERAND_APPENDING_LAUNCHERS and _operands_with_appended_wildcards exist only so "the nameless usage form app update --help is not floored" — but every sibling floor already denies its help form (kirocrew restart --help matches spec ("restart",), flags skipped by _self_cli_operands), and the exemption is what opened the operand-appending evasion this machinery then closes, plus the fail-closed --help-beside-a-name test surface.
    Subtraction: shrink the spec to ("app", "update") and delete _operands_with_appended_wildcards + _OPERAND_APPENDING_LAUNCHERS in argv_floor.py; the help form is refused exactly as restart's is today.
    Clears when: the deletion is made, or a maintainer states agents need app update --help output and keeps the exemption deliberately.

What this change ships

Inventory (10 items) — 9 justified

Intent: update an installed app from a terminal exactly as the App Store's Sync does — an ADDITION.

  1. New kirocrew app update <name> [--source PATH] verb — justified
  2. No file-only fallback; exit 3 with nothing changed when no gateway answers — justified
  3. Script-facing exit codes (0/3/4/5/1; 2 left to argparse) switched on the gateway's code — justified
  4. Update-route refusals gain machine-readable codes; baseline regenerated — justified
  5. registry:<other> source now refused for every caller, dashboard Sync included — justified
  6. A bad --source refused before the teardown, so a typo no longer bounces the app — justified
  7. update_app raising after teardown now rolls back and answers 400, not a 500 with the app down — justified
  8. Success responses carry previousVersion/version, both read under the lifecycle lock — justified
  9. Verb is operator-only: self-protection-app-update argv floor plus cli_commands/app_lifecycle_client on the inline mint surface — justified
  10. app update --help exempted from the floor via a wildcard operand plus xargs/parallel padding — oversized (see above)

More than 10 differences exist; dropped: same-commit spec/doc updates (mandated), the stale security.md prose gaining file-delivery approve (harm-free rides along), the deliberate _PACKAGE_LINE_BUDGET re-pin.

[FIRST-PRINCIPLES-REVIEWED] 16754d4

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — 🔴 changes requested (blocking)

Reviewed 16754d4c1d9f2558c287814565fc8f809595223f via the fork AI-review pipeline; updated in place on each push.

1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

BLOCKING -- src/kiro_crew/security/init.py:1438 -- interpreter subprocess calls bypass the operator-only floor
("self-protection-app-update", _argv._is_self_app_update),
python -c "import subprocess; subprocess.run(['kirocrew','app','update','trusted-app','--source','/tmp/evil'])" -> shell gate sees only Python’s argv -> attacker-controlled app code is installed and restarted.
Anchor: residual/security
Fix: Extend the interpreter execution-sink matcher to deny literal kirocrew app update <name> subprocess argv and shell-string calls.
[BLOCK-MERGE] 16754d4
[GPT-REVIEWED] 16754d4

Adjudication (Opus 5) — is blocking on each finding proportionate?

F1 — harm: unbounded class as written (attacker code under the gateway), but the capability is not created or widened by this PR.
Conditions confirmed: .local_secret is a sandbox-VISIBLE leaf, read-write in every mode (src/kiro_crew/sandbox.py:750); toggle_app mints a dashboard token from it over the owner socket with plain urllib (src/kiro_crew/app_lifecycle_client.py:110–120); POST /api/apps/{name}/update already existed on the base and already accepts an arbitrary source directory, stops the backend, swaps files and restarts (src/kiro_crew/apps/routes.py:884, :906, :931). In-sandbox code is an established caller of that socket-plus-secret pattern (src/kiro_crew/mcp_core.py:489–494). Recovery path: none — the swap is applied and the backend restarted.
Real fix cost: the demanded interpreter-argv matcher buys nothing, because the same in-sandbox payload reaches the identical route by raw HTTP naming no product module and no kirocrew argv, so no command-text matcher can see it — and the floor the finding calls bypassed has no interpreter companion for any of its siblings either (src/kiro_crew/security/argv_floor.py:1169–1191; the only interpreter-argv rules are scoped to the token mint and the process kill, src/kiro_crew/security/denied_rules.py:349, :408).

[ADJUDICATION] 16754d4 total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] 16754d4

[ADJUDICATION-FENCED] 16754d4 fenced=1 flagged=1
FLAG F1 src/kiro_crew/security/init.py:1438 -- The named outcome is already reachable on the base tree from an in-sandbox shell (VISIBLE .local_secret at sandbox.py:750, socket token mint at app_lifecycle_client.py:110, pre-existing arbitrary-source route at apps/routes.py:884) by a raw-HTTP payload no command matcher can see, so the requested interpreter-argv matcher closes one spelling of a capability this PR neither creates nor widens, and every sibling floor carries the identical documented residual.
[GPT-ADJUDICATED-FENCED] 16754d4

🏷️ Fenced finding(s) machine-flagged as likely edge case

The security fence keeps these findings blocking regardless of adjudication; the only clearance path is a human override recorded by a repository writer, who must independently verify a rationale before recording it — it is machine-authored, and a wrong override on a security-class finding ships exactly the class the fence exists to stop. (This lane's comment deliberately carries no override command.)

  • F1 src/kiro_crew/security/__init__.py:1438 — The named outcome is already reachable on the base tree from an in-sandbox shell (VISIBLE .local_secret at sandbox.py:750, socket token mint at app_lifecycle_client.py:110, pre-existing arbitrary-source route at apps/routes.py:884) by a raw-HTTP payload no command matcher can see, so the requested interpreter-argv matcher closes one spelling of a capability this PR neither creates nor widens, and every sibling floor carries the identical documented residual.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 26, 2026
@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 16754d4c1d9f2558c287814565fc8f809595223f via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 16754d4

@ash663
ash663 force-pushed the feat/app-update-cli branch from bce4528 to f7ecffc Compare September 26, 2026 18:13
@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author
  • Agent can replace trusted app code through the owner socket span=e0fecac8beaa

disposition: needs-a-decision
Question for a maintainer, put directly: should kirocrew app update sit on the self-protection floor beside the restart and token verbs, or is agent access accepted -- and if accepted, does the MCP-first rule want an MCP twin? The PR body asks exactly this and the code pre-empts neither answer.
Not a new capability: enable/disable/uninstall already mint the same local credential and drive the same owner socket from an agent shell (cli_commands.py _run_app_action_through_gateway), and the installed app tree under apps// is writable by a plain open() from that shell today, so the verb adds a one-line spelling, not reach.
The suggested deny-floor entry matches command TEXT for an endpoint the same shell reaches with urlopen -- the subject error AGENTS.md names as a review smell -- so it is not added here without a ruling; a governed MCP tool is the alternative the maintainers may prefer.

@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author
  • Registry override updates the wrong app span=e0fecac8beaa

disposition: fixed in f7ecffc
The --registry NAME flag is deleted: the handler treats registry:<name> as both the entry to clone and the app to install, so the only legitimate value was the app's own name, which the bare verb already sends (that is the source a registry install records).
The route now also refuses a registry source naming another app with app_source_name_mismatch (400) before taking the lock or touching the requested app, so no client can reach the wrong-app swap; test_apps_routes_coverage.py pins that nothing is stopped or deregistered for the refused request.

@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author
  • Symlink-loop source crashes the CLI span=e0fecac8beaa

disposition: fixed in f7ecffc
--source resolution catches OSError/RuntimeError and exits 1 with a one-line refusal naming the path; nothing is sent to the gateway. test_app_update_cli.py drives a real symlink loop and asserts the exit and that toggle_app is never called.

@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author
  • --registry B re-installs app B while reporting success for A span=ff504e891d6b

disposition: fixed in f7ecffc
Both halves of the suggested fix: the --registry flag is deleted (its only legitimate value was the app's own name, which the bare verb already sends), and handle_update_app refuses a registry:<other> source with app_source_name_mismatch (400) before the lifecycle lock, the same identity guard the local branch gets from update_app(..., expected_name=name).
Pinned by test_apps_routes_coverage.py (install_from_registry must not run; nothing of the requested app is stopped or deregistered) and test_app_update_cli.py (--registry is an argparse usage error).

@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author
  • Exit 2 collides with argparse's usage error span=8aefccc152d8

disposition: fixed in f7ecffc
Not-updatable (app_not_installed / app_lifecycle_not_gateway) moved to exit 5; 2 is left to argparse, and the constants' comment plus cli.md / apps.md say so. Tests assert 5.

@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author
  • Governance of an agent-runnable app-swap verb is left to a maintainer span=529fd0206ebf

disposition: needs-a-decision
This is the ruling the PR body requests, put directly to the maintainers: add kirocrew app update to the self-protection floor, or accept agent access (and settle whether an MCP twin is wanted under the MCP-first rule). Merging is the decision, and nothing in the diff makes it for them.
Context for the ruling: the existing app verbs already mint and drive the same owner socket from an agent shell and none sits on the floor; the installed app tree is writable by a plain open() from that shell; the deny-floor spelling would match command text for an endpoint urlopen reaches.

@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author
  • Exit code 2 collides with argparse's own usage-error exit span=3c4c794ac8fb

disposition: fixed in f7ecffc
Not-updatable moved to exit 5 before anyone depends on the contract; 2 stays argparse's, stated in the code comment and in both doc rows, so a script can tell a bad flag from a refusal.

@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 3: --registry NAME names no harm span=f96f3731ab85

disposition: fixed in f7ecffc
Subtraction taken: the --registry flag, its SOURCE_REGISTRY_PREFIX branch and the mutually-exclusive group are deleted; --source stays. A registry-installed app updates from its recorded registry:<name> source with the bare verb, and the docs say so.

@ash663

ash663 commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 7: AppGatewayError.status has zero non-test readers span=2379cac80903

disposition: fixed in f7ecffc
Subtraction taken: the status attribute and constructor argument are deleted at all three raise sites; code stays, and it is what the CLI switches on.

@ash663
ash663 force-pushed the feat/app-update-cli branch from f7ecffc to 59d37e4 Compare September 26, 2026 18:43
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 26, 2026
@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 7 -- symptom-level: the floor's justification describes app install exactly span=8e3a72d55057

disposition: fixed in b2b6d4b
The rationale is restated as a harm reachable only through app update, in the spec (app-kit-platform.md floor paragraph), the floor's own docstring and the description: an update 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 shell rides existing grants; a fresh install is a new store entry whose execution the third-party policy denies until the operator grants that app trust, and its grant is repository-bound. The uninstall && install <evil-tree> path the item names is acknowledged in ## Not a goal as the reason the sibling question is real, and it is left, explicitly, to the maintainers -- flooring existing verbs is product shape this PR does not carry.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Preflight failures still tear down the running app (an unreadable app.json returns None, then raises inside update_app after the teardown, skipping the rollback) span=eced7998a0df

disposition: fixed in 0b3c6b4
Two changes, both in the local branch of handle_update_app. First, the preflight no longer answers None for a read failure: an OSError (EACCES / EIO), a parser failure _validate_source_path did not catch, or a home directory that will not expand is returned as a refusal -- 400, code: app_source_invalid, source ... could not be read: <exc> -- so the backend is never stopped and nothing is deregistered; None now means exactly one thing, the source validates and names this app. Second, an exception out of update_app itself after the teardown (the manifest becoming unreadable between the two reads, a copy failure it did not catch) is caught and turned into a failed AppResult, so the existing rollback branch re-registers and restarts the app and the answer is a 400 naming the error, not a 500 with the app left down.
Pinned in test_an_unreadable_manifest_is_refused_before_the_teardown (from_json_file raising PermissionError: refused with the code, no stop, no deregister, version untouched) and test_an_exception_out_of_update_app_still_rolls_back (update_app raising OSError: stop -> deregister -> register -> start, 400 with the error, version untouched); both fail against the previous head.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 10 -- undeclared: security.md's ungated-floor list also gains the pre-existing self-protection-file-delivery span=95704fec5dd6

disposition: rebutted
It is in the diff because this PR rewrote those exact sentences: adding self-protection-app-update to the _SELF_PROTECTION_UNGATED_FLOOR_IDS enumeration and the two lifecycle-command lists in security.md is this PR's own doc change, and the Opus lane on 5dfef72 (comment 5848403583) found that the rewritten enumeration then named a count over a set it did not list in full, because self-protection-file-delivery was already missing from it. Leaving a list this PR edits knowingly incomplete, or keeping a wrong count word, would be the worse outcome; the fix is confined to the lines the PR was already touching, adds no floor, and changes no behaviour. The description's ## What changed names "the security spec (the self-protection floor lists)" among the docs touched; the pre-existing id joining the enumeration is that item's content, not a separate change.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Suggestion: a tracking issue at merge for the deferred uninstall→install-same-name residual span=56192e99c08e

disposition: needs-a-decision
Agreed that the deferral should not evaporate. The residual and its reasoning are recorded in the description (## Not a goal, the siblings bullet, and the "why update alone" differential) and in the spec's floor paragraph, so a maintainer reading either has the full question. Whether the answer is "floor uninstall/install too" or "leave them as they are" is a product ruling on verbs this PR does not touch, so the tracking issue is the maintainers' to open at merge with that ruling in it; a fork author filing it ahead of the ruling would fix the framing before the people who decide have read the differential. Happy to open it on request.

@ash663

ash663 commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor Author
  • explicit --source '' is treated as absent by if source:, updating from the recorded checkout span=c0812d82d748

disposition: fixed in 758e4f3
Fixed after the Opus lane named the case that makes it a footgun rather than a convention (--source "$BUILD_DIR" with the variable unset: the override is dropped, the app is updated from the recorded checkout, and the exit is 0 with a version-transition line). _handle_app_update now tests source is not None; an empty or blank value is refused on exit 1 with no request sent, the same exit the unresolvable-path branch uses, so only an ABSENT flag means the recorded source. Pinned in test_an_empty_source_is_refused_not_read_as_the_recorded_source ("" and " "; fails against the previous head); the exit-codes row of the description names it. (This record first read rebutted; edited to fixed when the change landed.)

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • The trailing wildcard lets an xargs-launched nameless app update through span=71f170d22fd9

disposition: fixed in 758e4f3
Real: xargs kirocrew app update <<< my-app, xargs -a names kirocrew app update and xargs kirocrew app update < names all ran kirocrew app update <name> with operands ["app", "update"] in the argv the floor read, so the spec's None was never reached. _operands_with_appended_wildcards in security/argv_floor.py now pads a spec's missing all-wildcard tail when the product CLI is the command an operand-appending launcher (xargs, parallel; _OPERAND_APPENDING_LAUNCHERS) in the same simple command will run -- that operand arrives at exec time from stdin or a file, so the nameless argv counts as carrying it. Only an all-wildcard tail is padded (a missing NAMED word is a different command), so xargs kirocrew app list < names, xargs on another command before the usage form, and the plain kirocrew app update --help stay allowed. The piped echo my-app | xargs … form was already rebuilt with its words by the normalizer. Pinned in test_app_update_floor_refuses_only_the_verb_that_swaps_running_code: here-string, -a file, < file, -n1 -P4, a path-spelled xargs, under sudo, the module form and parallel -a are refused with the floor id; the sibling-under-xargs and mention forms are allowed. The floor test fails against the previous head. Documented in the floor's docstring, security.md, cli.md and app-kit-platform.md.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • The docs claim a guarantee the argv tier does not have span=9bd349c75d61

disposition: fixed in 758e4f3
The three sentences (apps.md, the cli.md row, the app-kit-platform.md floor paragraph) and the description now say what the floor is: an argv-tier guard, the same tier kirocrew restart sits on, that judges the command line the shell is about to run -- however quoted, wrapped, or fed a name through xargs -- and, like every argv-tier floor, not every program that command may itself go on to spawn; a guard against a prompt-injected shell, not a sandbox. security.md describes the wildcard and launcher rule beside the other floor properties. The behaviour named in the finding (python -c "import os; os.system('kirocrew app update …')") is the sibling floors' shape too (os.system('kirocrew restart') is likewise outside the tier), so the fix here is the honest scope statement rather than a new inline scan -- an inline scan for the console-script literal plus the verb would refuse data mentions of the words, which the scope lane's corpus protects.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • if source: cannot tell an absent --source from an empty one span=8aefccc152d8

disposition: fixed in 758e4f3
Agreed -- --source "$BUILD_DIR" with the variable unset is the case that makes this a footgun rather than a convention: the override the operator meant to apply was dropped, the app was updated from the recorded checkout, and the exit was 0 with a version-transition line. _handle_app_update now tests source is not None; an empty or blank value is refused on exit 1 (--source was given but is empty; omit it to update from the recorded source, or pass the directory.) with no request sent, the same exit the unresolvable-path branch uses. Only an ABSENT flag means the recorded source. Pinned in test_an_empty_source_is_refused_not_read_as_the_recorded_source ("" and " "; fails against the previous head), and the exit-codes row of the description names it. This supersedes the rebutted disposition the GPT lane's same finding (span c0812d82d748) carried on this head; that record is edited to fixed as well.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author

Maintainer decision needed -- the Security Scope Review red (0b3c6b4e0, and 758e4f33c if it re-confirms the same rows) is a conflict between two lanes, not a defect I can fix from this side.

The two rows the scope classifier confirms as newly refused (posix):

  • python -c "import kiro_crew.cli_commands"
  • python -c "import kiro_crew.app_lifecycle_client as m; print(m.__file__)"

They are the intended consequence of the tightening the GPT lane required on c68b97653 (fenced, security-class, BLOCKING: an inline program that imports _handle_app_update / toggle_app drives the update with no kirocrew argv for the new floor to read). The fix that cleared that finding puts the two modules on the inline credential-mint surface, in the dotted import spelling only -- the previous scope round's rows (open('src/kiro_crew/cli_commands.py') and the Windows path spelling) are allowed again on this head, and kirocrew app update itself is not one of the lane's rows. What remains is the bare import of the two modules, which is exactly how the base already treats python -c "import kiro_crew.cli": refused, with no corpus row asking otherwise. The lane's own previous review pointed at this narrow spelling as the fix; its new candidates are one token further in.

I am not pushing another head for this, because no inline tightening can be regression-free against a model-proposed corpus: allowing the bare import while refusing every invocation through it (an AST walk over calls, decorators, with items and class bases -- I have the shape ready) would clear these two rows and immediately confirm the next one-token-off candidate (print(dir(c)), inspect.getsourcefile(c)), and any allow-list of "read-only" calls is a judgment that belongs to the people who own the corpus. Three rulings clear the PR; whichever you want, I will carry:

  1. Keep the tightening, accept the two rows as the same class as the existing kiro_crew.cli refusal (corpus-side or by overriding this check for the head).
  2. Drop the inline tightening (_MINT_SURFACE_RE back to the base set) and record the GPT inline-dispatch finding as an accepted residual -- the argv floor then covers the console script and python -m kiro_crew only, like today's restart floor does for its module.
  3. Narrow to import-without-invocation as sketched above, with a named allow-list of read-only calls you are willing to own.

Everything else on 0b3c6b4e0 was green -- CI, GPT (no blocking findings), Opus (no blocking findings, three advisories fixed in 758e4f33c), Design PASS, First Principles PASS, UX -- and 758e4f33c is the last head this side pushes: the author set a four-round budget, and this was the fourth.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Script-file indirection bypasses the operator-only update floor span=7670520e57b3

disposition: needs-a-decision
The finding is correct about the tier and asks for a different product: the argv floor judges the command line a shell is about to run, and a script file it cannot read (bash ./s.sh) is outside it -- exactly as the adjudication confirms for the pre-existing restart and update floors, and exactly what the description and the three docs now state. The proposed fix, operator-only authorization at the socket/gateway boundary that tells an operator's CLI from an agent-spawned child presenting the same local secret, is a capability-boundary concept that does not exist for ANY lifecycle action today (install, enable, uninstall included) and would be new product shape, not a repair of this verb; the adjudication itself puts the cost at "large" with no override rationale available, and the author's round budget for this PR is spent. The maintainers' call: (1) accept the argv-tier floor as the same posture restart has and merge with the documented residual, (2) drop the floor and ship the verb with the restart-style residual only in docs, or (3) hold the PR for a socket-boundary authorization design, which I would file as its own issue on request rather than inside this change.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 3 -- one consumer, generalized: the launcher enumeration exists only to spare the nameless usage form span=35b8a34411d7

disposition: needs-a-decision
The item's premise is right and the deletion it proposes is the simpler floor: spec ("app", "update") with no wildcard refuses every launcher without naming any (xe, rush, BSD apply included), and its only cost is kirocrew app update --help from an agent shell. That cost is exactly what the Security Scope Review lane BLOCKED on head 5dfef72 -- kirocrew app update --help newly refused, script-confirmed by deny_diff.py as a lost legitimate operation -- which is why the wildcard and then the launcher rule exist. The two lanes want opposite things from the same line, so this is the ruling the item itself names: record that agent-readable app update --help is worth an open launcher enumeration (keep the wildcard; xe/rush/apply can join the set when they are wanted), or accept the --help refusal and delete the wildcard and the launcher rule together (_operands_with_appended_wildcards, _OPERAND_APPENDING_LAUNCHERS, the six-line docstring and the security.md sentence). The author's round budget for this PR is spent, so whichever you choose lands on your say, not on another guess.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 9 -- undeclared: security.md lists file-delivery approve among the ungated floors span=73fd9ae1ffab

disposition: rebutted
It is in the diff because this PR rewrote those exact sentences: adding self-protection-app-update to the _SELF_PROTECTION_UNGATED_FLOOR_IDS enumeration and the two lifecycle-command lists in security.md is this PR's own doc change, and the Opus lane on 5dfef72 (comment 5848403583) found that the rewritten enumeration then named a count over a set it did not list in full, because self-protection-file-delivery was already missing from it. Leaving a list this PR edits knowingly incomplete would be the worse outcome; the fix is confined to the lines the PR was already touching, adds no floor and changes no behaviour, and the description's ## What changed names "the security spec (the self-protection floor lists)" among the docs touched. Same disposition as on 08c8703 and 0b3c6b4 (comments 5857955733 and its predecessor).

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 10 -- rides along: getting-started.md renames the store action "Update" to "Sync" span=125d4f617f63

disposition: rebutted
Declared, not riding along: the description's ## What changed says of the App Kit publishing/getting-started guides that "the latter now names the store action by its actual button label, Sync", and the guides are in the diff because this PR adds the sentence that the verb is the terminal form of that button -- a sentence that would have pointed at a button label the dashboard does not show. This lane's own inventory on b2b6d4b listed the same change as item 10, justified ("getting-started's 'Update' action corrected to the button's real label 'Sync', plus verb docs").

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Suggestion: one shared source-validation function for _local_source_refusal and update_app span=09a4b0d3dddf

disposition: needs-a-decision
Agreed on the risk it names: a refusal added later only to update_app would fire after the teardown again. The preflight already delegates the shared half to the manager (_validate_source_path, the same function update_app calls, so the words and the code are one source), and what it duplicates is the is-directory and name-match checks around it. Folding those into one manager function that both call is a refactor of update_app's own validation -- a file this PR otherwise touches only to add the expected_name code -- and the author's round budget for this PR is spent. Your call whether it lands here on your say, or as a follow-up after merge (I will open it on request).

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author

Follow-up to the Security Scope Review note above (5858415616): on the rebased head 06f0ed749 the lane classified 17 candidates with 0 confirmed newly refused (verdict CONCERNS, check green), so the two bare-import rows from 0b3c6b4e0 are no longer a blocking item and the rulings listed there are not needed for readiness. The inline tightening is unchanged.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Source-loaded lifecycle client bypasses the operator-only floor span=685d0ad14a85

disposition: needs-a-decision
Correct as a reading of the regex: the two modules were put on the mint surface in the dotted spelling only, because the Security Scope Review lane script-confirmed the path spelling as a lost legitimate operation on b2b6d4b (open('src/kiro_crew/cli_commands.py') for a syntax check, a line count, a patch script) and blocked on it. runpy.run_path(<abs path>/kiro_crew/app_lifecycle_client.py) is the one place the path spelling IS an execution: run_path is already a _DYNAMIC_RUNNER_NAMES member whose arguments _names_the_mint inspects, but _PACKAGE_LITERAL_RE excludes a /-bounded kiro_crew, so the loader argument reads as data. The narrow repair is confined to that runner-argument check -- match kiro_crew[/\\](?:cli_commands|app_lifecycle_client)(?![a-z0-9_]) inside a run_path/exec/compile argument, never in the payload at large -- which keeps every scope-lane row allowed (open() is not a runner) and refuses exactly the loader form named here. It is a five-line change with one test, and the author's round budget for this PR is spent, so it lands on the maintainers' say: fold it in here (I will push it on request), merge with the residual recorded beside the script-file one already in the docs, or hold.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author
  • Watch: the floor's harm claim stays reachable through un-floored siblings; the deferred decision is security-load-bearing span=b2156a400e78

disposition: needs-a-decision
Agreed that uninstall → install → enable under the same name reaches the same outcome on a permissive standalone default, and that the deferral is load-bearing rather than cosmetic -- the description's ## Not a goal says so in as many words, and the docs scope "operator-only" to this one verb with the reason (an update replaces code the operator already trusted, with no new consent moment; a fresh install is a new entry the third-party policy denies until trusted -- which the permissive default weakens exactly as the Watch says). The item's own clearing condition is a maintainer record: floor the siblings too, or write down why the admission/trust defaults make reinstall-under-same-name an operator act. Either is a ruling on verbs this PR does not touch; the first is a small follow-up I will open and implement on request, the second belongs in docs/decisions/ under a maintainer's name. The author's round budget for this PR is spent, so nothing here moves without that ruling.

@ash663

ash663 commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author

Security Scope Review on 5eaa84181: one script-confirmed row, all three legs -- python3 -c "import importlib.util as u; print(u.find_spec('kiro_crew.app_lifecycle_client').origin)". Same class as the two bare-import rows on 0b3c6b4e0 (5858415616): the module's dotted name inside an inline program, no execution, refused because the dotted spelling is the inline credential-mint surface the GPT lane required. Note the two lanes now box that surface from both sides on this head: GPT blocks because the PATH spelling is not refused inside run_path (5859220648), Scope blocks because the DOTTED spelling is refused in a find_spec string. No inline rule satisfies both without a corpus decision, so the rulings listed in 5858415616 stand; the author's round budget is spent and nothing moves without one.

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.
@ash663

ash663 commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author
  • New skip weakens the ratchet span=93a0355177f8

disposition: fixed in 16754d4
The skipif is gone. test_source_preflight_never_opens_a_manifest_that_is_not_a_regular_file now pins the regular-file gate with a DIRECTORY named app.json -- is_file() rejects it on every platform, so the assertion runs on the Windows shard too -- and keeps the FIFO as a second assertion inside the same always-running test where the host has os.mkfifo. The parser stays patched to raise, so either double proves the manifest is never opened; with the gate removed (_validate_source_path reporting nothing) the directory case fails with must not be opened, checked locally before the push. The description's Tests section says the same. Same head also rebases the branch onto current main (the /api/models route-sweep red on the previous head was main's own between de25db1 and cd783d2 and is gone with the rebase); the interdiff is this test plus the two rebase re-pins (error-code baseline, line budget 27,761 → 27,828).

@ash663

ash663 commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author
  • Interpreter child bypasses the operator-only floor span=7670520e57b3

disposition: needs-a-decision
Same span as the script-file form on 06f0ed7, one indirection over: python -c "subprocess.run(['kirocrew','app','update',...])" is a child the argv floor never sees, exactly as it never sees the children of the pre-existing restart / update / gateway restart floors built on the same _matches_self_subcommand (argv_floor.py:1186-1191). The adjudication FLAGS it as no new reach: the path needs the operator's explicit non-default agent.sandbox: "off", where the spawn is already genuinely unconfined and can rewrite the app tree through a plain open() that routes no gate at all, so the bypass grants nothing its own precondition did not -- and the description and the three docs state that residual for this verb in those words. The asked-for fix, refusing update requests whose Unix peer belongs to an agent process tree, is operator-vs-agent authorization at the socket boundary: a capability that exists for NO lifecycle action today (install, enable, uninstall included), so it is new product shape rather than a repair of this verb. The security fence keeps the finding blocking regardless of the flag, and the author's push budget on this PR is spent, so it lands on a repository writer: (1) record the override and merge with the residual documented, matching the posture the sibling floors already ship with; (2) drop the floor and ship the verb with the restart-style residual in docs only; or (3) hold for a socket-boundary authorization design, which I will file as its own issue on request rather than inside this change.

@ash663

ash663 commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author
  • interpreter subprocess calls bypass the operator-only floor span=236d69c2bf66

disposition: needs-a-decision
The same F1 as on f8b8043 (7670520e57b3, argv_floor.py:1235), re-anchored to the floor's row in is_denied. The adjudication FLAGS it as no new reach and its trace is the whole answer: POST /api/apps/{name}/update with an arbitrary source pre-exists this PR (routes.py:884), .local_secret is sandbox-visible in every mode (sandbox.py:750), and an in-sandbox payload reaches that route by raw HTTP naming no product module and no kirocrew argv, so the requested interpreter-argv matcher closes one spelling of a capability this PR neither creates nor widens -- and no sibling floor (restart, update, gateway restart, cloud, file-delivery approve) has an interpreter companion either (argv_floor.py:1169-1191). The description and the three docs state this residual for the verb in those words. The fence keeps it blocking regardless, and the author's push budget on this PR is spent, so it lands on a repository writer: (1) record the override and merge with the residual documented, the posture the sibling floors ship with today; (2) drop the floor and ship the verb with the restart-style residual in docs only; or (3) hold for a socket-boundary operator-vs-agent authorization design, which I will file as its own issue on request rather than inside this change.

@ash663

ash663 commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 10 — the --help exemption in the new floor and the xargs/parallel padding it forces span=43569a1e3a1c

disposition: needs-a-decision
Correct that the sibling floors refuse their help forms (kirocrew restart --help matches ("restart",)), and correct that the None spec element plus _OPERAND_APPENDING_LAUNCHERS / _operands_with_appended_wildcards exist only to keep kirocrew app update --help readable. The exemption is not a preference: the Security Scope Review lane script-confirmed kirocrew app update --help as a LOST legitimate operation on b2b6d4b and blocked on it, and the two lanes now ask for opposite shapes of the same floor -- FP: refuse the help form like restart and delete the launcher rule; Scope: keep the usage form readable. Both are coherent; only one can ship, and the choice is which lane's rule governs a self-protection floor's usage form. I did not delete the rule: the author's push budget on this PR is spent, and either shape is a five-line change with its tests already in place (test_denied_commands_security.py pins both the allowed help forms and the refused launcher forms, so the deletion flips known assertions rather than inventing coverage). The maintainers' call, in this lane's own clear-when terms: (1) rule that agents need app update --help output and keep the exemption deliberately -- the record here is that statement; or (2) rule for the restart shape, and the deletion lands on request (spec ("app", "update"), both helpers removed, the help-form tests inverted, the line budget re-pinned down).

@ash663

ash663 commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author
  • Flag the registry-source mismatch guard for changelog visibility at release span=bb0c32cb5ded

disposition: needs-a-decision
Agreed on the fact: the registry:<other> guard closes a live pre-existing defect on the dashboard's own Sync path (a Sync naming another registry app swapped that app's files under this app's lock), independent of the new verb, and the description's Backwards compatibility section names it as the one behaviour change every caller sees. Where it is recorded is the maintainers' call, not this PR's: docs/build/changelog.md says a feature PR never touches CHANGELOG.md -- the release PR writes the section from what shipped -- so the visibility this suggestion asks for lives in that release write-up (or a label on this PR), which a repository writer places. The description is written so the release author can lift the sentence as-is.

@NicholasRBowers

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]: This PR has been inactive for 7+ days. I reviewed the blockers but they require your input:

  • The GPT 5.6 Review block is security-class and fenced from adjudication, so no push or disposition clears it (src/kiro_crew/security/__init__.py:1438, span 236d69c2bf66). The adjudication on this same head records that POST /api/apps/{name}/update with an arbitrary source pre-exists this PR and that the demanded interpreter-argv matcher does not close the raw-HTTP path to that route. Adding the matcher anyway, dropping the self-protection-app-update floor, or holding for a socket-boundary authorization design is a denylist-policy call a repository writer has to make.
  • First Principles and Security Scope Review ask for opposite shapes of the same floor. First Principles Item 10 (span 43569a1e3a1c) asks for the spec to shrink to ("app", "update") with _operands_with_appended_wildcards and _OPERAND_APPENDING_LAUNCHERS deleted; Security Scope Review earlier script-confirmed kirocrew app update --help as a lost legitimate operation and blocked on it. Only one shape can ship, and choosing between the two lanes is not a call automation should make.
  • Where the registry:<other> guard gets release visibility (Design Review suggestion, span bb0c32cb5ded) — that placement is a maintainer's.

The mechanical part is separable, and I have pushed nothing. The branch conflicts with main, and both Backend Tests (… 4) reds are test_pid_reader_ratchet counting 160 pid-reader sites against a recorded 158. This diff adds no pid-reader lines and main now records 143, so that shard red and the downstream Coverage Gate look like stale-base artifacts a rebase would clear — they are not what is holding this PR.

When you've addressed these, the pipeline will re-assess on its next cycle.

Copy link
Copy Markdown
Contributor

PR triage (2026-10-05): OVERLAPPING with main, rebase needed. No duplicate, no breaking change, no P0.

Checked against origin/main @ cc7e79894e. Merge base is b5dcaaa6c, 1166 commits behind. git merge-tree reports conflicts in src/kiro_crew/apps/routes.py, test/test_apps_routes_coverage.py, test/test_security_gate_liveness.py, error-code-baseline.json and docs/app-kit/publishing-guide.md.

handle_update_app has changed on main since the last note here:

Open overlap: #12645 (open) adds _close_event_log_sockets calls inside both branches of handle_update_app. The two PRs have different goals and could both land, but they edit the same function and whichever lands second will hit a textual conflict. Whoever goes second should keep both the preflight/version-transition code and the socket-close points.

The fenced GPT finding (security/__init__.py:1438) and the First Principles vs Security Scope disagreement over --help are still for a maintainer to decide, as the 10-01 note says. This triage does not treat them as a P0 introduced by this PR: the adjudication shows that the raw-HTTP path to the existing update route predates this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge needs-author-decision PR blocked on author input

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants