Skip to content

fix(agent): a non-default KIROCREW_HOME never rewrites the shared ~/.kiro/agents specs - #9797

Closed
CrysisDeu wants to merge 1 commit into
mainfrom
fix/9690-home-override-agents-dir
Closed

CrysisDeu wants to merge 1 commit into
mainfrom
fix/9690-home-override-agents-dir

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Start any kirocrew verb with a non-default KIROCREW_HOME (a pod, a .kirocrew-dev checkout, 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.

Part What it does
Own kiro home — config/paths.py adopt_isolated_kiro_home(), called from the cli.py and mcp_gateway/gatewayd.py prologues; hooks.py re-primes its agents-root memo when KIROCREW_HOME is non-default and no KIRO_HOME is set, exports KIRO_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, the export KIRO_HOME=~/.kiro opt-out, and the caveat that transcripts already migrated stay in the adopted home
Write-guard hardening — agent.py; apps/bridges.py for app-registered MCP servers the shared-write guard already on the base (its provenance arm refuses rewriting specs another home owns) is the backstop; this PR hardens its private-target exemption — on platforms with descriptor-relative filesystem walks the exemption is decided on a held directory descriptor's device/inode identity and the spec write goes through that same descriptor, so a planted or swapped <data home>/kiro symlink gets no exemption and no write window; the isolated agents directory itself is created by one descriptor-carrying walk (create_and_open_dir_pinned_deep pins the resolved home root once and creates/opens kiro and agents relative 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.json register/deregister/prune) in apps/bridges.py on 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 own
Lazy per-session transcript migration — session_map.py; session_allocation.py resolves resume through it; a slack/gateway.py comment notes why the startup prune stays safe a session's transcript pair moves from the host ~/.kiro sessions 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 is resolve_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; guarded get() only detects (one lstat; 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 through pinned_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 via pinned_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 .jsonl stays 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, and fsync), defaults unchanged for its existing callers. The adopted-home gate canonicalizes KIRO_HOME the way doctor does (expanduser then resolve), 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.py all honor the deferral, and identity retirement keeps its own branch ahead of the withheld check). Durability flushes open the file writable (O_RDWR) because Windows os.fsync needs write access — identity checks unchanged. Both stale checks (get() and prune()) treat a transcript still host-side — or one they cannot inspect — as live, so no failure path drops a mapping or a byte
Doctor — new doctor_spec_home.py, wired in cli_doctor.py "Agent Spec Data Home" names any spec KIROCREW_HOME pin that disagrees with the data home doctor runs on: a managed spec is a fixable issues entry with the kirocrew setup --agent-only remedy (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 more overflow line); the Data Home section prints the kiro home: line, what the host ~/.kiro still holds, and the opt-out. The host-home probes never resolve an attacker-influenced name: ~/.kiro is opened once through pinned_fs (no-follow, fstat-identified), its child subtrees are listed from descriptor-relative no-follow opens, and the shared kirocrew.json is 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 abort
Resolver — config/paths.py _explicit_kiro_home() (module-private; kiro_home() is its one consumer) applies kiro_home()'s own validity test to the raw KIRO_HOME, memoizes successful resolutions on the raw string; invalid or unresolvable values are never cached
Hand-rolled copies — pod/runtime.py, testing/harness.py now derive KIRO_HOME from the shared isolated_kiro_home() recipe instead of spelling it by hand

Why this shape: kiro-cli has no agents-dir switch — KIRO_HOME is 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 pinning KIROCREW_HOME from 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=~/.kiro from 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 at src/kiro_crew/builtin_skills/kirocrew-dev/kirocrew-worktree-dev/SKILL.md.

Backwards compatibility

Breaking: an install that relocated its data home via KIROCREW_HOME now has its kiro-cli children read agents/sessions/steering/skills/settings from <data home>/kiro instead of ~/.kiro, and its writes to the shared ~/.kiro/agents are refused. Writer sweep on origin/main @ 1d81193: agent.rebuild_agent_config (guarded on the base, exemption hardened here) and the apps/bridges.py register/deregister/prune writers (guarded here); the isolated target is admitted for both, pod/runtime.py and testing/harness.py (already exported KIRO_HOME by hand; both now share the recipe), and no other writer of ambient_agents_dir() exists — test_only_the_ownership_guard_consults_the_ambient_agents_dir pins that. export KIRO_HOME=$HOME/.kiro restores the old reads; docker's stock image uses the default home and is unaffected. kiro-cli login state lives under ~/.local/share/kiro-cli and does not move.

Tests

test/test_agent_home_override_9690.py (new), plus updates to test_agent_spec_hardened_reads.py:

  • Resolver: valid/invalid/unsafe overrides; success memoized on the raw string, failures never cached.
  • Adoption: export + follow-through of kiro_home()/ambient_agents_dir()/kiro_sessions_dir(), idempotence, INFO line with the opt-out.
  • Write guard: the reproduction shape refused and SEL-audited; explicit KIRO_HOME is not write authorization; a planted symlink gets no exemption; default home unchanged.
  • Migration invariants: gateway startup does no transcript work (source ratchet); opening one session moves exactly that pair; guarded 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.
  • Crash and recovery: a durable one-file orphan, a truncated journal, and a truncated or empty state file are all cleared and republished from the host on the next open; a journal residue carrying live appends withholds the open and is never deleted; a divergent journal or state withholds and preserves both pairs; rollback never removes a journal that grew; the serve/withhold verdict is pinned to the one host-pair predicate, and the removed longer-journal promotion helper is structurally pinned absent.
  • Gate canonicalization: a trailing-separator and a literal-~ KIRO_HOME spelling both keep the mapping and resume (parametrized); the tilde variant fails without the gate's expanduser.
  • Pinned publish: both transcript files are created relative to ONE pinned destination descriptor (recorded per copy call); the by-name helper is structurally pinned absent; fixtures write journal bytes with write_bytes so Windows compares byte-exact.
  • Withheld resume: the fresh session served in place of a withheld conversation never overwrites the mapping — at registration, at shutdown, or on provider-switch replay — and the next open resumes the mapped sid once the residue is reconciled; the durability flush works where fsync needs write access (Windows-CRT emulation).
  • Prune/get fences: a host-side or uninspectable transcript is live to both; a corrupt sid (embedded NUL) is dropped without aborting the pass.
  • Doctor: managed/foreign split, bounding and overflow (managed drift admitted before foreign rows fill the cap), zero-managed line, terminal-control neutralization, unreadable-subtree probes; a planted link at a host subtree or the shared spec is never followed or counted, a spec swapped in after root pinning never reaches a by-name reader, a platform without pinned walks omits the probes, and a read-time I/O error is silence, not a crash.

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 as foreign_data_home() and pinned by test_only_the_ownership_guard_consults_the_ambient_agents_dir.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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

@CrysisDeu
CrysisDeu requested review from a team and dwu96 September 9, 2026 23:32
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 9, 2026
@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of 4e92402560469e1dcf1d86520ab69d1ccd1f9651 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • The adoption is announced only via a gateway INFO line: a permanently-relocated install upgrades → adopt_isolated_kiro_home() exports KIRO_HOME=<data home>/kiro → its kiro-cli children silently stop reading the operator's ~/.kiro steering/skills/settings, while the dashboard keeps showing and editing the host copies (the paths.py docstring itself calls this "the visible cost… routing those readers through this resolver is the follow-up"). An operator who doesn't read boot logs sees only unexplained behavior drift.
    Clears when: the split readers are routed through kiro_home() in the named follow-up, or doctor's Data Home section flags edited-but-unread host subtrees as an actionable row rather than an inventory line.
  • The KIRO_HOME=~/.kiro opt-out restores reads but not state: "Transcripts already moved into %s remain there" means sessions migrated before the flip lose resume (host state witness retired), with no repatriation path or doctor remedy — a one-way residue inside an otherwise reversible switch.
    Clears when: a reverse-migration exists, or doctor names stranded adopted-home transcripts with a concrete remedy when the opt-out is active.

[DESIGN-REVIEWED] 4e92402

@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 4e92402560469e1dcf1d86520ab69d1ccd1f9651 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 4e92402

Verdict parsed from the review's SHA-scoped output markers for commit 4e92402560469e1dcf1d86520ab69d1ccd1f9651.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 4e92402560469e1dcf1d86520ab69d1ccd1f9651: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 4e92402560469e1dcf1d86520ab69d1ccd1f9651 — 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

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 ships

Inventory (10 items) — 9 justified

Intent: FIX — a non-default KIROCREW_HOME rewrote the machine-wide ~/.kiro/agents specs and broke the real install's MCP identity (#9690); provenance: referenced issue plus tests added that fail on base.

  1. Non-default KIROCREW_HOME automatically gets its own kiro-cli home (KIRO_HOME export in every CLI/gatewayd prologue) — inherited premise for permanently relocated installs (see above)
  2. Five app-spec/MCP writers in bridges.py now refuse and SEL-audit shared-dir writes from a foreign home — justified
  3. Ownership decision and spec writes share one held directory descriptor, so a planted <data home>/kiro symlink gets no write window — justified
  4. Host-side transcripts migrate lazily per session; a failed move withholds resume instead of forking the conversation — justified
  5. A fresh session over a withheld mapping never promotes its sid (allocation, shutdown, replay) — justified
  6. Two new doctor sections name the drift shape with the one-command remedy — justified
  7. An unresolvable KIRO_HOME now falls back to ~/.kiro with a warning, memoized — rides along
  8. pinned_fs grows a deep pinned-create walk (2 consumers counted: agent.py:404, session_map.py:210) and three copier hooks consumed by the new callers — justified
  9. register_app's "0 of N agents" error names the refusal instead of blaming the agent source — justified
  10. Worktree skill doc, pod env and E2E harness re-spelled through isolated_kiro_home() — justified

[FIRST-PRINCIPLES-REVIEWED] 4e92402

@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 4e92402560469e1dcf1d86520ab69d1ccd1f9651 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4e92402

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 4e92402560469e1dcf1d86520ab69d1ccd1f9651: <one-sentence reason>

@CrysisDeu
CrysisDeu force-pushed the fix/9690-home-override-agents-dir branch from ff34f63 to 47e5a56 Compare September 9, 2026 23:44
@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 9, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/9690-home-override-agents-dir branch from 47e5a56 to 4655981 Compare September 10, 2026 00:10
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

Addressed the round-1 findings in 465598170 (single commit, amended):

GPT (3 blocking)

  • Invalid KIRO_HOME bypass → explicit_kiro_home() (same validity test as kiro_home()) now gates both the adoption and the write-guard opt-in. KIRO_HOME=/etc is replaced with the isolated home (WARNING) and the shared write is still refused.
  • Doctor spec read → routed through agent_discovery._read_agent_spec(operation="doctor", source="cli"); call-site ratchet inventory updated; symlink-to-protected-target test added.
  • Stale UNC memo → hooks.prime_unc_agents_root(), called synchronously from both prologues right after adoption when hooks is already imported.

First Principles (CONCERNS)

  • The contradictory paragraph in _decline_shared_agent_home's docstring is rewritten; the worktree-dev SKILL.md section is rewritten to describe the isolated form; kiro_home()'s SCOPE note now names the one residual reader that does not follow KIRO_HOME (~/.kiro/settings/mcp.json) and why it is inert for spec-declared servers (includeMcpJson is pinned off). The pod/runtime.py note about the settings registry is accurate as written, so it stays.

Design (CONCERNS)

  • Upgrade path: the first adoption on a data home (adopted dir not yet present) is now a WARNING that names the move and the export KIRO_HOME=~/.kiro opt-out; later starts log INFO. I did not fold detection into doctor — under adoption doctor inspects <home>/kiro/agents, not the shared dir, so it has nothing to compare there; the adoption-time WARNING fires earlier and costs a single exists().

@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 10, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/9690-home-override-agents-dir branch from 4655981 to 1593673 Compare September 10, 2026 00:31
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

Round-2 findings addressed in 159367312:

GPT (blocking, security) — spec pins were canonicalised with Path.resolve(), which on Windows opens a UNC pin (\\attacker\share) and authenticates to it during the doctor walk. Replaced with _lexical(): expanduser + normpath + normcase only, no filesystem access; the expected side is folded the same way (_expected_forms: our data home raw + resolved + raw KIROCREW_HOME). Cost accepted: a symlink-spelled pin of our own home now reads as drift (one doctor line) instead of probing a host. Test test_a_pin_is_compared_lexically_and_never_touches_the_filesystem spies os.stat for the attacker path and pins the normaliser body filesystem-free.

First Principles (CONCERNS) — the "one residual" claim was an undercount. kiro_home()'s SCOPE note now lists what does NOT follow KIRO_HOME: settings/mcp.json (registry; inert for spec-declared servers since includeMcpJson is pinned off), and skills / hooks / steering / prompts (dashboard shows and edits the host copies while a redirected kiro-cli loads its own) — with KIRO_HOME=~/.kiro as the opt-out and routing those readers as the follow-up.

Design (CONCERNS) — transition surfaced where the operator looks: kirocrew doctor's Data Home section now has a kiro home: line, and on an adopted (isolated) home it lists which of sessions/steering/skills/prompts the host ~/.kiro still holds that this instance does not read, with the export KIRO_HOME=~/.kiro opt-out. Informational (no issue appended) — a scratch instance wants the isolation. Copying/linking the host subtrees into the adopted home was considered and rejected: it would silently import the operator's real transcripts and steering into every scratch/dev instance, which is the opposite direction from the one this fix exists to enforce. The beacon.is_default_home() unification is noted as a follow-up in the description.

@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 10, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

Design round 3 (159367312):

  • Fold the re-prime into adopt_isolated_kiro_home() — agreed, done locally: config.paths._reprime_kiro_home_memos() reaches kiro_crew.hooks via sys.modules.get (keeps paths a stdlib leaf) and is called inside adopt_isolated_kiro_home() right after the export, so no entrypoint can adopt without re-priming; cli.py / gatewayd.py are back to a bare adopt_isolated_kiro_home() and the source-level ratchet became a behavioral test (memo key flips to the adopted home). Lands with the next push — holding it so the backend shards on 159367312 finish first (this branch has not had a full backend verdict yet).
  • Promote the doctor "host home still holds…" line to an issues entry — not doing that, deliberately. Every pod (build_pod_env sets the same isolated KIRO_HOME) and every dev/scratch instance on a machine that has ever run kiro-cli would then exit kirocrew doctor nonzero for a state that is exactly what those instances want. The population the CONCERN is about (a permanently relocated install) is real but is not distinguishable from those at doctor time; the WARNING at first adoption plus the doctor line are the honest surfaces until the remaining ~/.kiro readers route through kiro_home() (the named follow-up), at which point the split — and the note — go away.

@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 10, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/9690-home-override-agents-dir branch from 1593673 to f08cbdf Compare September 10, 2026 01:06
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

Round-3 findings addressed in f08cbdff1 (also carries the Design-suggested re-prime fold-in):

GPT (blocking, machine-flagged edge) — _doctor_kiro_home probed the host ~/.kiro/{sessions,steering,skills,prompts} with iterdir() unguarded, so a searchable-but-unreadable subtree would abort doctor. Each probe is now wrapped in except OSError: continue (matching the sibling probes in _doctor_data_home); test test_an_unreadable_host_subtree_does_not_abort_doctor injects a PermissionError on one subtree and asserts the others are still reported.

GPT (finding) — managed in the drift report required only an owned spec file, so a user-added custom server inside kirocrew.json with a drifted pin would be reported as managed and doctor would recommend setup --agent-only, which preserves that entry. managed now requires BOTH an owned spec AND a Kiro Crew server name (mcp_cleanup.KIROCREW_BIN_MCP_SERVERS, the set already ratchet-pinned to agent._MANAGED_MCP_SERVERS); such entries are reported as edit-by-hand. Test test_a_custom_server_inside_an_owned_spec_is_not_managed.

Design — adopt_isolated_kiro_home() now re-primes the KIRO_HOME-keyed memo itself (config.paths._reprime_kiro_home_memos, via sys.modules.get("kiro_crew.hooks") so paths stays a stdlib leaf); cli.py / gatewayd.py are back to a bare call, and the source ratchet became a behavioral test (test_adoption_reprimes_the_loaded_unc_agents_root).

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.

@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 10, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

Design round 4 (f08cbdff1):

  • Tracked follow-up filed: Route remaining host ~/.kiro readers (skills/steering/prompts/settings) through kiro_home() #9816 — route the remaining host ~/.kiro readers (skills / hooks / steering / prompts / settings/mcp.json) through kiro_home(); linked from the PR description's follow-ups. It also carries the beacon.is_default_home() → foreign_data_home() unification.
  • Ratchet for future ambient_agents_dir() writers: added test_only_the_ownership_guard_consults_the_ambient_agents_dir — every src/kiro_crew consumer of the override-blind resolver must be agent._decline_shared_agent_home (the one place the ownership question is asked); a new direct caller fails the test. Committed locally; it rides on the next push rather than restarting CI on f08cbdff1 by itself.

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Sep 10, 2026
@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=3fba5890493a — adoption leaves config subtrees (steering/skills/prompts/hooks) empty on a relocated install

Accepted; same underlying gap as the host-copy-readers item tracked in
#9816 (deferred-finding label, assigned, due
2026-10-31): the follow-up routes the remaining readers through kiro_home() or seeds the
subtrees at adoption, either of which satisfies this item's Clears-when. Out of round-0 scope
for this PR — the #9690 fix is the shared agents-dir write isolation; the shared-write backstop
on base holds while the follow-up lands.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=bb080c9d4833 — opt-out after partial migration strands adopted-home transcripts (one-way transition)

Accepted; identical substance to the item already tracked in
#13114 (deferred-finding label, assigned, due
2026-10-31): a reverse-reclaim path, or doctor naming the stranded adopted-home transcripts
under the opt-out configuration. Deferred rather than grown in this PR to keep the migration
mechanism at the completed descriptor recipe the retrospectives bound it to.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=7fdb6008fb41 — suggestion: bounded one-time copy of the config subtrees at first adoption

Accepted as the preferred implementation shape for the tracked follow-up; recorded on
#9816 so the implementer weighs it first (a
one-time seeded copy reusing the pinned_fs machinery closes the Watch gap far cheaper than
reader routing). Not grown into this PR: adoption-time seeding is new behavior with its own
review surface, and the shared-write backstop holds meanwhile.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • fixed span=c7a51793eff5 — black-baseline line for test_knowledge.py rides along

Resolved by rebase in 095d4fe: base commit a118ae7 carries the same baseline prune, so the
hunk no longer exists in this PR's diff — the item's subject left the change set entirely.

@NicholasRBowers

Copy link
Copy Markdown
Contributor

self-added: yes
mechanism: app MCP config writers run on the held agents-directory descriptor end to end

  • fixed span=0f85d21f9c88 — app MCP writers lose directory ownership after validation (bridges.py:3000/:3233)

Fixed in b5eceaa: _register_mcp_servers, _deregister_mcp_servers, and the MCP half of
_prune_stale_app_resources now enter the same held agents-directory target the agent-spec
writers use (_held_mcp_target reuses agent.py's thread-local descriptor contract), and the
lock sidecar, the strict read (openat(O_NOFOLLOW), S_ISREG-gated), and the atomic write
(atomic_write_at, dir_fd) are all descriptor-relative — no by-name hop remains between the
ownership decision and the kirocrew.json write, including across _live_port_for and
_maybe_provision_backendless_deps. Platforms without dir_fd and the pin-refusal arm keep the
ownership-checked by-name residual. Class-pinned by a regression that swaps the agents dir
inside the window and asserts the shared config stays byte-identical — proven red pre-fix
(the shared file received the write). A blind cross-family verifier enumerated the window's
path resolutions and closed all six questions, including guard-outside-lock ordering.

@NicholasRBowers

Copy link
Copy Markdown
Contributor

self-added: yes
mechanism: post-denial directory assertions re-pinned to exact entry sets

  • fixed span=3b83fb60c54a — agent-directory side-effect ratchet was weakened (test_app_bridges.py:828/:851)

Fixed in b5eceaa: both post-denial assertions now enumerate the directory's exact entries with
set equality — {p.name for p in agents_dir.iterdir()} == {".kirocrew-agents.lock"} — naming
only the intentional lockfile, per the anchor's own allowance of re-pinning to the new true
value. Non-JSON residue can no longer satisfy the check.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=81e3c8b7fbcb — withheld transcript migrations are invisible to the operator

Accepted; tracked in #13114, whose doctor fix-it
surface for migration residue now explicitly includes enumerating withheld/unreconciled
transcript migrations (scope note posted on the issue). Deferred rather than grown here to
keep this PR's migration mechanism at the completed descriptor recipe; every withheld case is
already logged with its cause, and nothing is deleted while withheld.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=2cea8541ef1e — relocated install's config readers flip to an empty adopted home

Accepted; the reader-routing follow-up is filed and linked:
#9816 (deferred-finding label, assigned, due
2026-10-31), which also carries the adoption-time one-time-copy implementation note. Doctor's
Data Home section lists what the host ~/.kiro still holds; flagging it actively is part of
the tracked follow-up. Out of round-0 scope — the #9690 fix is the shared agents-dir write
isolation, and the shared-write backstop on base holds meanwhile.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • fixed span=ef21297af07a — stale "Formatting baseline" row in the description

Fixed in b5eceaa: the row is removed from the PR description — .github/black-baseline.txt left
this diff when the base landed the identical prune via #13151.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • needs-a-decision span=17ff257de7f2 — inherited: the same isolation default lands on permanently relocated installs

Maintainer ruling required; this restates the adoption-scope question already open on this
thread (not a new ping). The question: should the KIRO_HOME auto-export cover every
non-default KIROCREW_HOME (as shipped), or only ephemeral/scratch homes, leaving
deliberately relocated installs reading the shared ~/.kiro? The shared-write backstop on
base holds either way. Clears via
/ai-review override first-principles 095d4fe4dff1a79f6e1df75ad88bda500a25679c: <decision> or a
non-draft RFC covering default-on adoption merging to base.

@NicholasRBowers

Copy link
Copy Markdown
Contributor

self-added: yes
mechanism: isolated agents directory created by one descriptor-carrying walk

  • fixed span=954823a62c41 — closing the parent descriptor permits path traversal (agent.py:408)

Fixed in c1862e5: _open_private_agent_spec_target no longer creates the two path
components with independent by-name calls; it derives the relative tail and makes one
create_and_open_dir_pinned_deep call, which pins the resolved home root once and
creates/opens kiro and agents relative to the held parent descriptor (O_NOFOLLOW,
dir_fd-relative mkdir) — no ancestor is re-resolved by name after its descriptor exists, so a
symlink swapped in mid-call can no longer land the agents mkdir outside the isolated home
before the fd_real_path witness refuses. The precheck and the witness are unchanged.
Class-pinned red-before-green: on the prior code the swap regression created T/agents
outside the home before the refusal, and a structural test pins that the two-shot by-name
primitive is not called from this site. A blind cross-family verifier enumerated every path
resolution and creation step in the function and confirmed containment.

@NicholasRBowers

Copy link
Copy Markdown
Contributor

self-added: yes
mechanism: retirement removes only the .json witness; the host journal is retained

  • fixed span=4d2233f90259 — revalidation does not protect the subsequent unlink (session_map.py:683)

The race is real and a point fix cannot close it: the journal writer is kiro-cli, a separate
process, the migration lock is in-process only, and rename-verify cannot stop an append to an
already-open inode. Per the prepare-pr skill's iteration-budget retrospective (third round in
this mechanism ⇒ simplification weighed first), the retire path is now SMALLER in c1862e5:
it still revalidates both files and unlinks the host .json — the sole witness
_pending_in_host_dir and _serve_verdict key on, so convergence and serving are
unchanged — and it no longer unlinks the host .jsonl journal, whose removal was already
best-effort and which nothing keys on. A turn appended in the lstat→unlink window now
survives on disk by construction; the cost is one inert orphan journal per migrated session.
Red-before-green: on the prior code the windowed append existed in neither the adopted copy
nor on disk; post-fix it is recoverable, and a convergence test pins pending=False plus the
sid being served with the journal retained. The blind verifier traced every predicate that
could key on the host journal and confirmed none does.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=8f4dc18e8ba5 — adopted install: dashboard edits host copies while kiro-cli reads its own

Accepted; this is the reader-routing follow-up already filed and linked:
#9816 (deferred-finding label, assigned, due
2026-10-31), which routes steering/skills/prompts/settings readers through kiro_home() and
carries the adoption-time one-time-copy note. Doctor's Data Home section names what the host
~/.kiro still holds meanwhile. Out of round-0 scope — the #9690 fix is the shared
agents-dir write isolation.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=4d2effd89c00 — opt-out strands migrated transcripts with no reverse path

Accepted; the doctor Data Home surface tracked in
#13114 is extended to name stranded
adopted-home transcripts when KIRO_HOME is pointed back at the shared home (scope note on
the issue). The one-way direction itself is deliberate — migration is lazy and per-session, a
reverse mover would need the same race analysis in the opposite direction, and the retained
host journals plus the INFO caveat keep the data recoverable meanwhile.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • needs-a-decision span=169f576afba8 — item 2 rides along: every non-default home is isolated, not only scratch homes

Maintainer ruling required; this restates the adoption-scope question already open on this
thread (not a new ping). The question: should the KIRO_HOME auto-export cover every
non-default KIROCREW_HOME (as shipped), or only ephemeral/scratch homes, leaving
deliberately relocated installs reading the shared ~/.kiro? The shared-write backstop on
base holds either way, and the #9816 reader routing removes the named cost when it lands.
Clears via /ai-review override first-principles b5eceaa6eb7c0caca442013b7c035263ecf6acfd: <decision> or that follow-up merging.

@NicholasRBowers

Copy link
Copy Markdown
Contributor

self-added: yes
mechanism: serve verdict fail-withholds when the host witness vanished without a published adopted pair

  • fixed span=4d2233f90259 — concurrent migrations can orphan the adopted journal (session_map.py:963)

The named two-process case is refuted while the end-state is real and now closed. Two Kiro
Crew writers on one KIROCREW_HOME cannot coexist: GatewayLock holds an exclusive
process-lifetime flock on the home and its lock file (sole acquisition at gateway boot),
and SessionMap's own SCOPE contract depends on that singleton — the suggested cross-process
per-SID lock is the wrong layer and, for the only genuine cross-process case, would require a
lock inside the shared ~/.kiro (cross-instance coordination the design avoids). The genuine
residual is two DIFFERENT pods adopting the same host sessions dir and racing on retiring the
shared pair; the loser rolls back its copy and the old verdict then served a sid with an empty
adopted directory. Fixed in f93dc00 at the serve boundary: _serve_verdict serves only when a
complete pair exists at the location kiro-cli reads, or the host state witness still exists
beside a provably non-resumable pair (nothing to lose); a witness retired out from under the
attempt with nothing published is withheld, so the fresh session cannot silently overwrite the
mapping, and the next open retires the entry through the audited stale path. No single-process
failure path removes the witness, so the withhold branch detects exactly concurrency.
Lock-free, pure lstat, same predicates as the liveness reads. Red-proven in both directions:
the prior code served after an injected peer retirement, and an over-broad unconditional
withhold wedged the pre-existing nothing-to-lose serves — both pinned by tests. A blind
cross-family verifier walked every failure path and closed all five properties.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=e1cae29a3a4b — adoption covers every non-default install; dashboard edits host copies while kiro-cli reads its own

Accepted; this is the reader-unification follow-up already filed and linked:
#9816 (deferred-finding label, assigned, due
2026-10-31) — routing steering/skills/prompts/hooks readers through kiro_home(). Doctor's
Data Home section names what the host ~/.kiro still holds meanwhile.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=58a837deb438 — one-way migration: opting out strands already-migrated sessions

Accepted; the doctor Data Home surface tracked in
#13114 names stranded adopted-home transcripts
under the opt-out (scope note on the issue), and the retire path retains every host journal,
so the manual copy-back has its bytes on disk. A reverse mover needs the same race analysis in
the opposite direction and stays out of round-0 scope.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • needs-a-decision span=970269eb1fc8 — item 2 inherited: the isolation default for permanently-relocated installs

Maintainer ruling required; this restates the adoption-scope question already open on this
thread (not a new ping): should the KIRO_HOME auto-export cover every non-default
KIROCREW_HOME (as shipped) or only ephemeral homes? The shared-write backstop on base
holds either way, and the #9816 reader routing removes the named cost when it lands. Clears
via /ai-review override first-principles c1862e51ea360cf96deb675e5e9fd3cff1460537: <decision> or that follow-up merging.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • not-a-duplicate span=fabfe189a3e7 — item 7: two detectors of the drifted shared-spec pin

The named scenario where the default-side check cannot reach the operator: it runs only when
doctor is invoked FROM the default home (doctor_spec_home_drift is wired into that
instance's check list), while the operator who created the drift is on the relocated instance
and diagnoses from there — the probe in the relocated instance's Data Home section
(cli_doctor.py, _spec_home_pinned over _MANAGED_MCPS) is the only surface that reaches
them at the moment of diagnosis, and it names the failure the default instance would see. The
two share the predicate helpers rather than duplicating logic; each reports on a different
side of the same drift.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • justified span=b7067c52d67b — item 10: kiro_home() warn-and-fall-back plus memoized resolution

Both behaviors are load-bearing for this change, not rides-along. The warn-and-fall-back
mirrors _valid_override_home's unsafe-target rejection so the two resolvers agree
(config/paths.py, the docstring names the filesystem-root scatter this prevents), and
degrading a malformed override to the DEFAULT home lands where the base's shared-write guard
protects — raising instead would turn a bad env var into a boot failure for every session.
The memoized resolution is what keeps the adopted-home canonicalization computed once per
configuration, which the transcript map's contract depends on: no path resolution runs on the
event loop or under the map lock.

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 5.6 flagged blocking issues on f93dc00595e20d87d3a713b4ba95612326793da0; Opus 5 adjudication downgraded every one of them to advisory. Adjudication downgraded all 1 blocking finding(s) to advisory: the remedy each one requires is disproportionate to the harm it prevents. Read them as advice, not as merge conditions.

This comment is updated in place on each push.

Review details

BLOCKING -- src/kiro_crew/session_map.py:98 -- adopted-home resolution blocks the gateway event loop

configured_kiro_home = Path(key[0] or "").expanduser().resolve()
Network-backed home -> start_pool() -> SessionMap.prune() -> synchronous resolution under _MAP_LOCK -> chat and heartbeat freeze.
Anchor: no-blocking-call-on-event-loop
Fix: Prime the adopted-source cache during the synchronous process prologue.
[BLOCK-MERGE-DOWNGRADED] f93dc00
[GPT-REVIEWED] f93dc00

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

Harm: LOW — a once-per-process event-loop stall of two Path.resolve() calls, visible as startup/reload latency, no loss.
Conditions confirmed: foreign data home required (session_map.py:86-88, config/paths.py:954-968 — None and zero I/O on default/legacy/re-spelled homes); line 98 sits only in the cache-MISS branch, memoized per (KIRO_HOME, own_home) at session_map.py:90-93,107; a failed resolution returns None rather than raising (session_map.py:100-101); loop entry is session_pool.py:257, whose same guarded prune() already pays N inline network .exists() stats per entry at session_map.py:2170 — a pre-existing cost this PR did not add, stated as accepted in the class threading contract at session_map.py:1280-1284.
Real fix cost: the proposed prologue priming creates a new cross-module ordering contract every entrypoint (gateway, each CLI verb, pods, eval runner) must honour or silently regress, and it moves the round-trip ahead of the socket bind — exactly what config/paths.py:1051-1057 and 914-917 declare the prologue must never do; the alternative is an async-only twin of a sync @_guarded method with a dozen sync call sites. Either way the mechanism exists solely for this path and does not remove the stall class, since the N inline stats at session_map.py:2170 remain.

[ADJUDICATION] f93dc00595e20d87d3a713b4ba95612326793da0 total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/session_map.py:98 reason=disproportionate-remedy
[GPT-ADJUDICATED] f93dc00595e20d87d3a713b4ba95612326793da0

False positive or not applicable? A repository writer can comment:
/ai-review override gpt f93dc00595e20d87d3a713b4ba95612326793da0: <one-sentence reason>

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • justified span=4d2233f90259 — adopted-home resolution blocks the gateway event loop (session_map.py:98)

The resolution is memoized: _adopted_transcript_source caches its answer keyed on
(KIRO_HOME, data home) and every call after the first is a tuple compare under a narrow
lock — no path resolution runs per open. Only the first miss after a configuration change
pays the two resolve() calls, a bounded handful of syscalls on local paths, and the same
canonicalization would otherwise run per-open inside SessionMap.get's stale check, which
is the cost this cache removes. The adjudicator did not fence this instance and the lane
completed clean.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=2ab57f412284 — adopted installs: dashboard edits host copies while kiro-cli loads its own

Accepted; the reader-routing follow-up is filed and linked:
#9816 (deferred-finding label, assigned, due
2026-10-31) — routing steering/skills/prompts/hooks readers through kiro_home(). Doctor's
Data Home section names what the host ~/.kiro still holds meanwhile.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=6a5468a207ff — opting out strands already-migrated transcripts

Accepted; the doctor Data Home surface tracked in
#13114 names stranded adopted-home transcripts
under the opt-out (scope note on the issue), which is the doctor-named manual recipe the
finding asks for — and the retire path retains every host journal, so the copy-back has its
bytes on disk.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • accepted-and-deferred span=97907b1c8e7f — withheld-open residue is doctor-invisible

Accepted; enumerating withheld sids in the doctor Data Home section is already in scope on
#13114 (scope note on the issue), which is
exactly the surface this suggestion names.

@NicholasRBowers

Copy link
Copy Markdown
Contributor
  • needs-a-decision span=63600c1f7c15 — item 1 inherited: the isolation default is argued only by the description

Maintainer ruling required; this restates the adoption-scope question already open on this
thread (not a new ping): should the KIRO_HOME auto-export cover every non-default
KIROCREW_HOME (as shipped) or only ephemeral homes? The shared-write backstop on base
holds either way, and the #9816 reader routing removes the named cost when it lands. Clears
via /ai-review override first-principles f93dc00595e20d87d3a713b4ba95612326793da0: <decision> or that follow-up merging.

…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

5 participants