Repository navigation
Conversation
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Relocated installs get a split-brain kiro home on upgrade: dashboard edits host steering/skills/prompts the redirected kiro-cli never reads, and opt-out strands migrated transcripts. Watch
[DESIGN-REVIEWED] 4e92402 |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Auto-adoption also fires for permanently relocated installs — the population the rewritten pin called "not throwaway" — silently moving kiro-cli off their host steering/skills/settings. Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: FIX — a non-default
[FIRST-PRINCIPLES-REVIEWED] 4e92402 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
ff34f63 to
47e5a56
Compare
47e5a56 to
4655981
Compare
|
Addressed the round-1 findings in GPT (3 blocking)
First Principles (CONCERNS)
Design (CONCERNS)
|
4655981 to
1593673
Compare
|
Round-2 findings addressed in GPT (blocking, security) — spec pins were canonicalised with First Principles (CONCERNS) — the "one residual" claim was an undercount. Design (CONCERNS) — transition surfaced where the operator looks: |
|
Design round 3 (
|
1593673 to
f08cbdf
Compare
|
Round-3 findings addressed in GPT (blocking, machine-flagged edge) — GPT (finding) — Design — Backend on the previous SHA before this push: all 4 Windows shards, namespace-sandbox and E2E green; the 4 Linux 3.12 shards had not finished. |
|
Design round 4 (
|
|
|
|
|
self-added: yes
|
|
self-added: yes
|
|
|
|
|
self-added: yes
|
|
self-added: yes
|
|
|
|
|
self-added: yes
|
|
|
|
|
|
GPT 5.6 Review — ✅ no blocking findings (all downgraded on adjudication)GPT 5.6 flagged blocking issues on This comment is updated in place on each push. Review detailsBLOCKING -- src/kiro_crew/session_map.py:98 -- adopted-home resolution blocks the gateway event loop
Adjudication (Opus 5) — is blocking on each finding proportionate?Harm: LOW — a once-per-process event-loop stall of two False positive or not applicable? A repository writer can comment: |
|
|
|
|
|
…kiro/agents specs Fixes #9690 Original change by CrysisDeu (Zezhen Xu). Review-round hardening of the transcript migration: the symlink walk now lstats the migration root itself, the transcript publish uses an O_CREAT|O_EXCL descriptor instead of mkstemp+os.link so homes without hard-link support still migrate, and the doctor/spec wording of the opt-out contract is narrowed to what the ownership guard actually enforces. Co-authored-by: Kiro Crew <noreply@kirodotdev.github.io>
Problem / Motivation
Start any
kirocrewverb with a non-defaultKIROCREW_HOME(a pod, a.kirocrew-devcheckout, a docker volume) and it rewrote the machine-wide~/.kiro/agents/*.json, pinning its own scratch home into the specs every OTHER install's kiro-cli reads. The operator's primary gateway then refuses every session with strict-identity 403s — and the scratch run is long gone by the time the damage shows.Why it matters
One throwaway instance silently breaks the real install's MCP tools, and the failure surfaces later, on the healthy gateway, with no pointer back to the cause.
What changed (motivation → approach → change)
A non-default data home gets its own kiro-cli home — isolation is the durable fix; the base's shared-write guard is the backstop for anything that bypasses it.
config/paths.pyadopt_isolated_kiro_home(), called from thecli.pyandmcp_gateway/gatewayd.pyprologues;hooks.pyre-primes its agents-root memoKIROCREW_HOMEis non-default and noKIRO_HOMEis set, exportsKIRO_HOME=<data home>/kiro, so the gateway and every kiro-cli child it spawns agree on one private home; the adoption INFO line names the move, theexport KIRO_HOME=~/.kiroopt-out, and the caveat that transcripts already migrated stay in the adopted homeagent.py;apps/bridges.pyfor app-registered MCP servers<data home>/kirosymlink gets no exemption and no write window; the isolated agents directory itself is created by one descriptor-carrying walk (create_and_open_dir_pinned_deeppins the resolved home root once and creates/openskiroandagentsrelative to the held parent descriptor, no component re-resolved by name), so a symlink swapped in mid-create cannot redirect even the directory creation outside the isolated home; elsewhere the link-free, directory-shaped path check applies — and runs the register/deregister/prune app-spec writers AND the app MCP config writers (kirocrew.jsonregister/deregister/prune) inapps/bridges.pyon that same held descriptor end to end — ownership authorization, prior-config reads, writes and pruning all descriptor-relative on pinned platforms, refused, warned and SEL-audited when the target is not this instance's ownsession_map.py;session_allocation.pyresolves resume through it; aslack/gateway.pycomment notes why the startup prune stays safe~/.kirosessions dir into the adopted home when THAT session is opened — never as a startup scan, so gateway readiness does no data-sized work. The open path isresolve_resume_sid→resolve_host_transcript, which attempts the move and decides serve-or-withhold in one per-session critical section, off the event loop and outside the map lock; guardedget()only detects (onelstat; the adopted-home canonicalization it needs is computed once per configuration and cached, so no path resolution runs on the event loop or under the map lock). Per-session migration locks are reference-counted and evicted when a migration reaches its terminal state, so the registry is bounded by in-flight migrations, not by history. The move opens the destination directory once throughpinned_fs.create_and_open_dir_pinned_deep, which pins the destination root once and creates/opens every descendant component relative to the held parent descriptor — no component is ever re-resolved by name, then publishes journal first, state file last, each an exclusive create relative to that held descriptor viapinned_fs.copy_file_pinned(the read side tolerates a multi-hard-link source — a host home under rsnapshot-style hardlink backups still migrates — while the destination screen never relaxes) — the destination is never re-resolved by name between validation and publish — with file fsync and a directory sync through the same descriptor, and retires the host pair only after both copies are durable and only after re-verifying each host file against the stats captured at validation (inode, size, mtime), so a source that changed mid-copy is left intact and the open withheld; retirement removes only the state witness (.json) — the sole name the pending and serve checks key on — and deliberately retains the host journal on disk, because kiro-cli is a separate process that can append a turn between the final revalidation and the removal, and a retained journal keeps that turn recoverable while a lone.jsonlstays inert to convergence, serving, and kiro-cli alike. Windows, which cannot express a descriptor-relative walk, keeps the prior by-name checks and their stated look/open residual. A rollback removes only the exact inodes this attempt created (identity witnessed at create time), never whatever later answers to the name —pinned_fs.py's central copier grew two keyword-only hooks for this (on_opened, the create-time identity witness, andfsync), defaults unchanged for its existing callers. The adopted-home gate canonicalizesKIRO_HOMEthe way doctor does (expanduserthenresolve), so an equivalent spelling — trailing separator, literal~— never makes the map treat a live host-side mapping as stale. One predicate decides serving (_host_pair_complete): a sid is served only when its transcript is provably at the adopted location kiro-cli reads, or there is provably nothing to lose — a host pair that was never resumable while its state witness is still in place; when that witness is retired out from under an attempt by another adopted instance and nothing was published, the open is withheld so the fresh session cannot silently overwrite the mapping, and the next open retires the entry through the audited stale path. While a complete host pair sits unmoved — however the attempt failed — the open is withheld, the mapping is never overwritten, and the next open retries; the attempt's failed/migrated label is diagnostic only. Recovery is clear-and-republish from the immutable host pair, inspecting and unlinking residue through the same pinned destination descriptor (unlink_verified) rather than by name: an adopted leftover that is byte-equal to or a strict prefix of its host file is deleted and republished fresh; a longer or divergent residue (live appends from a session that raced the move) is preserved byte-for-byte and the open withheld for a human; only plain regular files are ever removed, and a rollback never touches a journal that grew after this attempt's copy. A withheld open is typed apart from "no mapping" (ResumeLookup), so the fresh session that serves the user never promotes its sid over the withheld conversation — not at registration, not at shutdown, not on a provider-switch replay (session.py,session_lifecycle.py,session_allocation.pyall honor the deferral, and identity retirement keeps its own branch ahead of the withheld check). Durability flushes open the file writable (O_RDWR) because Windowsos.fsyncneeds write access — identity checks unchanged. Both stale checks (get()andprune()) treat a transcript still host-side — or one they cannot inspect — as live, so no failure path drops a mapping or a bytedoctor_spec_home.py, wired incli_doctor.pyKIROCREW_HOMEpin that disagrees with the data home doctor runs on: a managed spec is a fixableissuesentry with thekirocrew setup --agent-onlyremedy (managed drift is admitted to the capped list before foreign rows can fill it), a foreign spec is named but never an issue; output is bounded (5 rows, clamped strings, a+N moreoverflow line); the Data Home section prints thekiro home:line, what the host~/.kirostill holds, and the opt-out. The host-home probes never resolve an attacker-influenced name:~/.kirois opened once throughpinned_fs(no-follow, fstat-identified), its child subtrees are listed from descriptor-relative no-follow opens, and the sharedkirocrew.jsonis parsed from bytes read under that pinned root — on a platform without descriptor-relative opens (Windows) the advisory probes are omitted rather than downgraded to a by-name walk, and a read-time I/O failure is silence, never an abortconfig/paths.py_explicit_kiro_home()(module-private;kiro_home()is its one consumer)kiro_home()'s own validity test to the rawKIRO_HOME, memoizes successful resolutions on the raw string; invalid or unresolvable values are never cachedpod/runtime.py,testing/harness.pyKIRO_HOMEfrom the sharedisolated_kiro_home()recipe instead of spelling it by handWhy this shape: kiro-cli has no agents-dir switch —
KIRO_HOMEis the only lever and it moves the whole~/.kiro, which Kiro Crew's own readers (kiro_agents_dir(),kiro_sessions_dir()) already follow. The alternative (never pinningKIROCREW_HOMEfrom a non-default instance) would break every non-default install's MCP tools to protect the default one. The guard has no environment opt-in:KIRO_HOME=~/.kirofrom a foreign home makes kiro-cli read the shared specs, never write them. Migration is per-session-on-open because a bulk move has no safe moment: before readiness it stalls the gateway, after readiness it races every open; one file at the moment its own session needs it does neither.Docs updated in the same commit:
docs/system-specs/modules/config.md(the whole mechanism),cli.md(doctor items 20–21),session.md(the transcript migration),app-kit-platform.md(the bridges ownership rule), and the worktree-dev guidance atsrc/kiro_crew/builtin_skills/kirocrew-dev/kirocrew-worktree-dev/SKILL.md.Backwards compatibility
Breaking: an install that relocated its data home via
KIROCREW_HOMEnow has its kiro-cli children read agents/sessions/steering/skills/settings from<data home>/kiroinstead of~/.kiro, and its writes to the shared~/.kiro/agentsare refused. Writer sweep on origin/main @ 1d81193:agent.rebuild_agent_config(guarded on the base, exemption hardened here) and theapps/bridges.pyregister/deregister/prune writers (guarded here); the isolated target is admitted for both,pod/runtime.pyandtesting/harness.py(already exportedKIRO_HOMEby hand; both now share the recipe), and no other writer ofambient_agents_dir()exists —test_only_the_ownership_guard_consults_the_ambient_agents_dirpins that.export KIRO_HOME=$HOME/.kirorestores the old reads; docker's stock image uses the default home and is unaffected. kiro-cli login state lives under~/.local/share/kiro-cliand does not move.Tests
test/test_agent_home_override_9690.py(new), plus updates totest_agent_spec_hardened_reads.py:kiro_home()/ambient_agents_dir()/kiro_sessions_dir(), idempotence, INFO line with the opt-out.KIRO_HOMEis not write authorization; a planted symlink gets no exemption; default home unchanged.get()never copies; the copy runs off the loop thread outside the map lock; two concurrent opens of one sid publish once and cannot consume a stale verdict; a failed move with the host pair intact withholds, keeps the mapping, and retries next open.~KIRO_HOMEspelling both keep the mapping and resume (parametrized); the tilde variant fails without the gate'sexpanduser.write_bytesso Windows compares byte-exact.Manual verification
Doctor output shapes (drift-cap overflow, zero-managed line) and the migration's fsync-failure arms were exercised by scripted scratch runs; the pod path exercises adopted-home session resume end to end.
Related Issues
Fixes #9690
Pattern harvest
Rule candidate: architectural ratchet (test), not semgrep
Pattern: an instance-scoped value written into a machine-scoped location — a resolver for a shared path (
kiro_home()→~/.kiro) sits beside a resolver for a per-instance path (config_dir()→KIROCREW_HOME), and a writer stamps the per-instance value into the shared file. The generalizable check is "does the writer of<shared>own<shared>?", expressed asforeign_data_home()and pinned bytest_only_the_ownership_guard_consults_the_ambient_agents_dir.Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)