Repository navigation
fix: share one $KIROCREW_SCRATCH across a session tree - #12782
Conversation
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Dropped shared window fails open at debug level, silently recreating the unreadable-brief blockage this PR exists to fix. Watch
SuggestionsThe [DESIGN-REVIEWED] 6885791 |
|
Intent: A parent session and every process spawned on its behalf (dedicated sub-agent, companion runtime, a recycled runtime's replacement) read and write one |
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: |
Opus 4.8 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) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the warm-pool trade: every parented dedicated sub-agent now cold-starts (~3–5 s), so the fan-out this fixes also pays that 42×. What this change shipsInventory (10 items) — 10 justifiedIntent: FIX — a parent's staged files under
[FIRST-PRINCIPLES-REVIEWED] 6885791 |
6b842dc to
11b31b9
Compare
|
|
|
|
|
|
|
GPT 5.6 Review —
|
|
|
|
Rebased: main moved 30 commits since 27db263, including #12865 (drops the stale 501-until-diag premise in |
|
|
|
/ai-review override gpt 53ea9a6: False positive (span 033f2bc5b901, 5th round): a process that can write a dead pid into the shared .owner already holds rw on the same mount and can delete the tree's files directly; the marker confers no new capability, the sweep still needs an idle hour, and parent+child are one trust domain. Owner metadata outside the window is tracked in #12802. |
Human judgment recorded@bolichen97 marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Rebased: main moved 8 commits since 53ea9a6, including #12914 (the macOS skip for |
|
|
|
|
|
|
|
Rebased: main moved 15 commits since 95027ea, overlapping |
|
|
|
Rebased: main +1 (no overlap); CI re-running on c5c829d. Inherited red to expect until #12943 lands: |
|
|
Scratch is allocated per process and the sandbox masks the whole scratch root, re-exposing each process only its own directory. A dedicated subagent process and a companion runtime therefore got an empty $KIROCREW_SCRATCH and could not read a brief the parent staged there, and a _bg runtime recycled for age or RSS handed every session it took over an empty directory mid-task. A spawn made on behalf of an existing session tree now receives the tree's work directory as a second private window (shared_scratch on AcpRuntime/AcpClient, threaded through AcpProvider and the provider factory) and names it as KIROCREW_SCRATCH, while TMPDIR and the kiro-cli log stay per process. Companion runtimes take it from the parent kwargs, dedicated subagents from run.py (which also bypasses the warm pool, whose mounts were fixed at pre-spawn), and the _bg runtime's replacement inherits its predecessor's directory and adopts its owner marker. A child never adopts: its parent is alive. The inherited path is re-validated at spawn and dropped when swept, never re-created.
|
Rebased: main +4 since c5c829d, including #12943 (the |
|
|
Problem / Motivation
A parent session stages a brief or a manifest under
$KIROCREW_SCRATCHandfans out sub-agents. Every dedicated sub-agent process reports the path is not
mounted. Then the parent's own
$KIROCREW_SCRATCHchanges underneath it and thefiles it wrote a few minutes ago are gone from its view.
Both happened in one real fan-out: 42 sub-agents, all BLOCKED on an unreadable
brief, and the parent's inventory lost mid-task when its runtime was recycled.
Why it matters
Fan-out is how big jobs run here. If a child cannot read what the parent
staged, every wave must inline its inputs into the prompt, and a runtime
recycle silently destroys in-flight work.
What changed (motivation → approach → change)
TMPDIRand the kiro-cli log, but$KIROCREW_SCRATCHfollows the session tree$KIROCREW_SCRATCH$KIROCREW_SCRATCHnames it_bgruntime's replacement starts an empty directoryRoot cause:
agent_scratchallocates per process andsandboxmasks the scratchroot as a whole, so nothing carried the parent's directory to a spawn made on its
behalf, nor a runtime's directory to its replacement.
src/kiro_crew/agent_scratch.pyscratch_env(shared=…),shared_scratch_window,adopt_owner(multi-pid marker; sweep keeps a dir while ANY owner lives)src/kiro_crew/acp/runtime.py,src/kiro_crew/acp/client.py,src/kiro_crew/acp/session_provider.pyshared_scratchparam, second window,work_scratch_dirsrc/kiro_crew/providers/base.py,src/kiro_crew/providers/acp.py,src/kiro_crew/config/loader.pywork_scratch_dirdeclared on theLLMProviderABC (H14);AcpProviderthreadsshared_scratchtoAcpClientAND to theAcpRuntimeit builds on the kiro pathsrc/kiro_crew/session_allocation.py,src/kiro_crew/session.pyparent_work_scratch_dir,bypass_shared_scratchsrc/kiro_crew/session_background.py_bgsuccessor inherits + adoptssrc/kiro_crew/subagent_manager/run.pyshared_scratchsrc/kiro_crew/sandbox.py,src/kiro_crew/config/prompt*.md,src/kiro_crew/docs/troubleshooting.md, docsOne window and one env value.
scratch_env(own, shared=…)names the tree'sdirectory as
KIROCREW_SCRATCH; the temp triple andKIRO_CHAT_LOG_FILEstay onthe process's own directory (two processes appending to one kiro-cli log is what
the log pin prevents).
shared_scratch_windowre-validates the inherited path atspawn (a plain directory under the managed root, never a link, never re-created
when swept) and refreshes its mtime under the sweep's lock, so the sweep's own idle rule
holds a crash-recovery inherit for the grace window while the spawn joins the marker.
AcpRuntime(shared_scratch=…)andAcpClient(shared_scratch=…)mount it beside their own window and expose
work_scratch_dir, a capability onthe
LLMProviderABC (Nonedefault) answered from the live process.AcpProviderpasses it to theAcpRuntimethat_start_kiro_runtime_implconstructs in place of the placeholder client, then records the tree the live
runtime exposes, so a restart re-joins that directory rather than a swept one.
Who passes it:
_collect_parent_runtime_kwargsfor a companion runtime;subagent_manager/run.pyfor a dedicated process, which skips the warm pool(
bypass_shared_scratch: pooled mounts were fixed at pre-spawn);get_bg_sessionhands the replacement runtime its predecessor's directory,kept on runtime state so retries and failed spawns still hand it on, and a tree
whose marker cannot be joined (
SharedScratchJoinError, raised only at the adoptsite) is abandoned so the slot always gets a runtime. A
root that respawns (client
ensure_ready, runtime restart) joins its previousdirectory as the tree.
session.pyexposesparent_work_scratch_dir.Ownership names every user. Each process that mounts a tree it did not allocate
ADDS itself to the tree's
.ownermarker once live (adopt_owner; one pid perline under a process-wide lock, dead pids pruned; the sweep keeps a directory
while any named process group lives), so a parent crashing under its children or
a successor failing beside its predecessor never leaves a dead-only marker over a
live one. The marker sits in a directory the agent writes, so it is read as a
bounded regular file (lstat-refused when linked,
O_NOFOLLOW,O_NONBLOCKso aplanted FIFO cannot park the reader,
fstat, 4 KiB cap, read to EOF); absent is left absent, garbled is left as-is.refused(a link)and
stalereap the spawn;unwritableandgarbledleave the tree unowned,which is never swept. Only work products chain across a
_bgrecycle (TMPDIRand the kiro-cli log stay per process), so the tree lives as long as the session
tree — the spec states the trade and calls out the
_bgtree's gateway lifetime.The scratch mask stays a whole-root mask: other session trees stay hidden. The
private window widens to the tree the spawn belongs to, which already gets the
parent's
sandbox_mode,extra_env, memory and project;sandbox.pychangesonly its comment. The prompts (
config/prompt.md,config/prompt-orchestrator.md) say sub-agents see the same$KIROCREW_SCRATCHand
$TMPDIRis per-process; specs updated in-commit(
docs/system-specs/modules/subagent.md,docs/architecture/context-management.md).Backwards compatibility
Compatible: every new parameter defaults to
None/False, a spawn with no parentkeeps today's shape exactly, and a swept or invalid inherited path is dropped
rather than refused. The one behaviour change is deliberate: a dedicated sub-agent
cold-starts instead of claiming a warm-pool process, so it pays the ~3–5 s start
the pool used to hide.
Tests
test/test_subagent_shared_scratch.py(54 tests):scratch_env(shared=…)names the tree's directory and keeps temp + log private;no
sharedis the first-process shape.shared_scratch_window: live allocation returned;None, a swept dir (notre-created), a file, a symlink under the root, and a dir outside the root all
answer
None.AcpRuntime.spawn,AcpClient._spawn) pass twoextra_private_dirswindows, setKIROCREW_SCRATCHto the tree andTMPDIRtotheir own dir, report
work_scratch_dir; a swept tree dir is dropped._collect_parent_runtime_kwargscarriesshared_scratch(and neveradopt_shared_scratch);parent_work_scratch_dirreads provider or client andanswers
Nonefor a non-Path.shared_scratchbypasses the warm pool and reachesthe factory with it;
run.pyhands a dedicated child the parent's directory andnothing when the parent has none.
adopt_owner: names both pids; the sweep keeps the tree while either lives andreclaims it once both are dead; idempotent; dead pids are pruned so a chained
tree stays bounded; 40 concurrent adopters all land; a linked marker is
refused; a marker linked to
/dev/zerois never read; an oversized or garbledmarker is refused and left for a human (the sweep leaves it too); a pid no
process can have (non-positive or past the C int) is refused, not probed; an unowned
tree stays unowned; a failed append leaves the tree unowned, not
predecessor-owned.
AcpRuntimecallsadopt_owneronce its process is live and thenreleases the sweep reservation; a
staleoutcome reaps the spawn and releasestoo. A dead-idle validated window survives the sweep for the grace window; two
heirs both refresh it; a touch landing between the sweep's idle reading and its
rmtree still wins; validation never takes the marker-I/O lock.
AcpProvider._start_kiro_runtimebuilds itsAcpRuntimewith the inheritedshared_scratch, and theprovider's
work_scratch_diranswers the live process's directory; thecapability is a property on the
LLMProviderABC answeringNoneby default.get_bg_session: a stale runtime's successor is built withshared_scratch=<predecessor dir>; a runtime thatdies inside
create_sessionstill hands its directory to the retry'sreplacement; a replacement that fails to spawn does not lose it for the next
call; the gateway's first runtime gets
None.Local gates: black / isort / flake8 / mypy (1685 files clean) /
check_subprocess_encoding/check_comment_history/scripts/docs-lint.shpass.
scripts/local-gate.pybackend shards: green except two host-dependentreds (
tmp_pathplaced under the live~/.kiro/crew/scratch, and anorder-dependent
crew_log.lease._heldassertion) that pass in isolation and withTMPDIRoutside the data home; frontend shard 1/3 green, 2/3 and 3/3 hit thelocal time budget and are left to CI (no frontend file changes).
test/test_sandbox_private_window_in_caller_mask.pygains a two-window case (owndir + tree dir inside the masked scratch root) on both the Linux launcher and
the Seatbelt profile builder, so the exact shape this PR emits is pinned on the
platform lanes.
A structural pin scans
src/for everyAcpRuntime(/AcpClient(construction:each threads
shared_scratchor is a listed standalone process with its reason,so a future seam that forgets fails loudly.
test/test_secc_poc_scratch_owner_symlink.pyregistersgarbledas a deliberatelynon-fatal outcome in its owner-outcome ratchet, with the reason.
Manual verification
N/A — unit coverage exercises both spawners' sandbox arguments and env; the
Linux bind-mount primitive (
extra_private_dirs) is unchanged and alreadypinned by
test/test_sandbox_private_window_in_caller_mask.py. Not verifiedhere: macOS Seatbelt and Windows, where the second window rides the same primitive
(the delegated-sandbox path ignores private windows and does not mask the scratch
root at all).
Related Issues
no linked issue: found during a live fan-out on 2026-09-22, no tracker entry exists.
Pattern harvest
Rule candidate: agents-md
Pattern: "a per-process resource handed to a spawn made on behalf of a session must be threaded to every process that serves that session (companion runtime, dedicated process, recycled successor), or the session sees it vanish"
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)