Skip to content

fix: share one $KIROCREW_SCRATCH across a session tree - #12782

Merged
bolichen97 merged 1 commit into
mainfrom
fix/subagent-shared-scratch
Sep 23, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/subagent-shared-scratch

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A parent session stages a brief or a manifest under $KIROCREW_SCRATCH and
fans out sub-agents. Every dedicated sub-agent process reports the path is not
mounted. Then the parent's own $KIROCREW_SCRATCH changes underneath it and the
files 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)

Before After
scratch is per process; the sandbox masks the whole scratch root and re-exposes each process only its own dir scratch stays per process for TMPDIR and the kiro-cli log, but $KIROCREW_SCRATCH follows the session tree
a dedicated sub-agent / companion runtime gets an empty $KIROCREW_SCRATCH it gets the parent's directory mounted as a second private window, and $KIROCREW_SCRATCH names it
a recycled _bg runtime's replacement starts an empty directory it inherits its predecessor's directory; every process mounting a tree joins its owner marker

Root cause: agent_scratch allocates per process and sandbox masks the scratch
root 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.

Area Change
src/kiro_crew/agent_scratch.py scratch_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.py shared_scratch param, second window, work_scratch_dir
src/kiro_crew/providers/base.py, src/kiro_crew/providers/acp.py, src/kiro_crew/config/loader.py work_scratch_dir declared on the LLMProvider ABC (H14); AcpProvider threads shared_scratch to AcpClient AND to the AcpRuntime it builds on the kiro path
src/kiro_crew/session_allocation.py, src/kiro_crew/session.py companion kwargs, parent_work_scratch_dir, bypass_shared_scratch
src/kiro_crew/session_background.py _bg successor inherits + adopts
src/kiro_crew/subagent_manager/run.py dedicated child gets shared_scratch
src/kiro_crew/sandbox.py, src/kiro_crew/config/prompt*.md, src/kiro_crew/docs/troubleshooting.md, docs comment, prompt wording, a troubleshooting entry for the scratch tree's disk use, specs

One window and one env value. scratch_env(own, shared=…) names the tree's
directory as KIROCREW_SCRATCH; the temp triple and KIRO_CHAT_LOG_FILE stay on
the process's own directory (two processes appending to one kiro-cli log is what
the log pin prevents). shared_scratch_window re-validates the inherited path at
spawn (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=…) and AcpClient(shared_scratch=…)
mount it beside their own window and expose work_scratch_dir, a capability on
the LLMProvider ABC (None default) answered from the live process.
AcpProvider passes it to the AcpRuntime that _start_kiro_runtime_impl
constructs 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_kwargs for a companion runtime;
subagent_manager/run.py for a dedicated process, which skips the warm pool
(bypass_shared_scratch: pooled mounts were fixed at pre-spawn);
get_bg_session hands 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 adopt
site) is abandoned so the slot always gets a runtime. A
root that respawns (client ensure_ready, runtime restart) joins its previous
directory as the tree. session.py exposes parent_work_scratch_dir.

Ownership names every user. Each process that mounts a tree it did not allocate
ADDS itself to the tree's .owner marker once live (adopt_owner; one pid per
line 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_NONBLOCK so a
planted 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 stale reap the spawn; unwritable and garbled leave the tree unowned,
which is never swept. Only work products chain across a _bg recycle (TMPDIR
and 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 _bg tree'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.py changes
only its comment. The prompts (config/prompt.md,
config/prompt-orchestrator.md) say sub-agents see the same $KIROCREW_SCRATCH
and $TMPDIR is 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 parent
keeps 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 shared is the first-process shape.
  • shared_scratch_window: live allocation returned; None, a swept dir (not
    re-created), a file, a symlink under the root, and a dir outside the root all
    answer None.
  • Both spawners (AcpRuntime.spawn, AcpClient._spawn) pass two
    extra_private_dirs windows, set KIROCREW_SCRATCH to the tree and TMPDIR to
    their own dir, report work_scratch_dir; a swept tree dir is dropped.
  • _collect_parent_runtime_kwargs carries shared_scratch (and never
    adopt_shared_scratch); parent_work_scratch_dir reads provider or client and
    answers None for a non-Path.
  • A dedicated sub-agent with shared_scratch bypasses the warm pool and reaches
    the factory with it; run.py hands a dedicated child the parent's directory and
    nothing when the parent has none.
  • adopt_owner: names both pids; the sweep keeps the tree while either lives and
    reclaims 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/zero is never read; an oversized or garbled
    marker 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.
  • An inheriting AcpRuntime calls adopt_owner once its process is live and then
    releases the sweep reservation; a stale outcome reaps the spawn and releases
    too. 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.
  • The kiro dedicated path: AcpProvider._start_kiro_runtime builds its
    AcpRuntime with the inherited shared_scratch, and the
    provider's work_scratch_dir answers the live process's directory; the
    capability is a property on the LLMProvider ABC answering None by default.
  • get_bg_session: a stale runtime's successor is built with
    shared_scratch=<predecessor dir>; a runtime that
    dies inside create_session still hands its directory to the retry's
    replacement; 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.sh
pass. scripts/local-gate.py backend shards: green except two host-dependent
reds (tmp_path placed under the live ~/.kiro/crew/scratch, and an
order-dependent crew_log.lease._held assertion) that pass in isolation and with
TMPDIR outside the data home; frontend shard 1/3 green, 2/3 and 3/3 hit the
local time budget and are left to CI (no frontend file changes).

test/test_sandbox_private_window_in_caller_mask.py gains a two-window case (own
dir + 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 every AcpRuntime(/AcpClient( construction:
each threads shared_scratch or is a listed standalone process with its reason,
so a future seam that forgets fails loudly.

test/test_secc_poc_scratch_owner_symlink.py registers garbled as a deliberately
non-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 already
pinned by test/test_sandbox_private_window_in_caller_mask.py. Not verified
here: 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

  • 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

@bolichen97
bolichen97 requested review from a team and patrigao September 22, 2026 10:56
@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: checking Automated validation is still running labels Sep 22, 2026
@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

Dropped shared window fails open at debug level, silently recreating the unreadable-brief blockage this PR exists to fix.

Watch

shared_scratch_window answering None (path outside root, swept, not a plain dir) is a deliberate fail-open — "losing the shared window costs the child visibility, not the spawn" — but the child then gets its own empty $KIROCREW_SCRATCH, which is byte-for-byte the motivating incident (42 children BLOCKED on an unreadable brief), now reachable with only a logger.debug line to explain it; only the unrefreshable-dead-owner branch warns. An operator hitting this degradation has less signal than the original bug produced.
Clears when: every branch that drops an inherited window the caller actually passed logs at warning (or marks the spawn record), so a fan-out degrading to per-child scratch is operator-visible.

Suggestions

The getattr(runtime, "work_scratch_dir", None) / getattr(..., "parent_work_scratch_dir", None) duck-typed reads at the session_background and subagent_manager seams could lean on the _BackgroundRuntime Protocol / provider ABC you already declared, so a renamed capability fails mypy instead of silently reading None and starting empty trees.

[DESIGN-REVIEWED] 6885791

@bolichen97

Copy link
Copy Markdown
Contributor Author

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 $KIROCREW_SCRATCH, so a brief the parent stages there is readable by every child and survives a runtime recycle.
Not a goal: changing how scratch is reclaimed (liveness-keyed sweep stays), lifting the scratch-root mask for other session trees, sharing TMPDIR or the kiro-cli log between processes, or altering the per-session AcpClient recycle path.

@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 22, 2026
@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 688579162584175c69687089878884b99589cf69 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6885791

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

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 688579162584175c69687089878884b99589cf69 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6885791

Verdict parsed from the review's SHA-scoped output markers for commit 688579162584175c69687089878884b99589cf69.

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

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 688579162584175c69687089878884b99589cf69 — 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: 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 ships

Inventory (10 items) — 10 justified

Intent: FIX — a parent's staged files under $KIROCREW_SCRATCH become readable by every process of its session tree, and survive runtime recycles.

  1. A dedicated sub-agent process now reads/writes the parent's $KIROCREW_SCRATCH — justified
  2. A companion runtime spawned for a parent's sub-agents shares that same directory — justified
  3. A recycled _bg runtime's replacement keeps the sessions' scratch instead of starting empty — justified
  4. A respawned root (client ensure_ready, runtime restart) rejoins its previous directory — justified
  5. A parented dedicated sub-agent skips the warm pool and pays a ~3–5 s cold start — justified
  6. The _bg scratch tree now lives as long as the gateway; disk accumulates, with a troubleshooting remedy — justified
  7. $TMPDIR is no longer the same place as $KIROCREW_SCRATCH for child processes; prompts say so — justified
  8. The .owner marker names every live user (multi-pid adopt, new garbled outcome); the sweep keeps a tree while any lives — justified
  9. work_scratch_dir capability on the LLMProvider ABC (counted 3+ consumers: session_allocation, session_background, providers/acp) — justified
  10. A tampered inherited marker abandons the inherit so the _bg slot always gets a runtime — justified

[FIRST-PRINCIPLES-REVIEWED] 6885791

@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 22, 2026
@bolichen97
bolichen97 force-pushed the fix/subagent-shared-scratch branch from 6b842dc to 11b31b9 Compare September 22, 2026 11:25
@bolichen97

bolichen97 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor Author
  • The runtime-backed provider drops shared scratch span=25513d154ea8 — fixed in 11b31b9

AcpProvider now keeps shared_scratch on the provider and passes it to BOTH AcpRuntime constructions in _start_kiro_runtime_impl (first spawn and resume respawn), which is the process a dedicated subagent runs in.
Pinned by TestTheKiroDedicatedPathCarriesTheTree::test_the_runtime_the_provider_spawns_is_built_with_the_tree: the constructor kwargs carry the tree and no adoption; provider.work_scratch_dir answers the live process's directory after the swap.

@bolichen97

bolichen97 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor Author
  • The retry loop loses its predecessor’s scratch span=95ff99ff15ec — fixed in 11b31b9

inherited_scratch is now held OUTSIDE the for attempt loop and refreshed only when the slot holds a runtime with a Path, so the iteration after AcpRuntimeDead cleared _bg_runtime still spawns the replacement with the dead runtime's directory.
Pinned by test_a_runtime_that_dies_in_create_session_still_hands_its_tree_on; the mutation (per-iteration reset) fails exactly that test.

@bolichen97

bolichen97 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Adoption can leave a live tree owned by a dead process span=60eee5df9fed — fixed in 11b31b9

Replacement is gone: agent_scratch.adopt_owner APPENDS the successor pid to the marker (one pid per line) and sweep_dead_scratch keeps a directory while ANY named pgroup lives, so a busy predecessor stays represented until it drains and a successor that later fails leaves no dead-only marker.
"stale" now reaps the successor spawn like "refused"; "unwritable" discards the marker so the tree is UNOWNED (never swept) instead of predecessor-only. Pinned by TestAdoptOwner (both-alive/one-alive/none-alive sweep, idempotence, linked marker refused, failed append leaves unowned).

@bolichen97

bolichen97 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor Author
  • The new provider capability is absent from the ABC span=25513d154ea8 — fixed in 11b31b9

work_scratch_dir is declared on LLMProvider with a None default (same shape as tool_search_settings, H14), and session_allocation.parent_work_scratch_dir reads provider.work_scratch_dir directly instead of probing client/_client.
Pinned by test_the_capability_is_declared_on_the_provider_contract and test_the_capability_is_read_off_the_provider_not_probed_on_its_client.

@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 22, 2026
@bolichen97

bolichen97 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor Author
  • bypass_shared_scratch forces a cold spawn for every parented dedicated subagent span=4a6641984c43 — rebutted (disproportional to change; cost stated)

The pool is not expected to serve parented spawns. Before this PR a dedicated subagent already bypassed the pool on cwd (its parent's project differs from _pool_cwd), extra_env, member context and a crew effort pin, and a per-spawn model/effort override only hits the pool when it equals the pool agent's model — so the warm hit a parented dedicated spawn could get was already the exception, not the rule.
The default path for a parented subagent is session sharing (~200 ms, no process at all); the dedicated path is opt-in by model/reasoning_effort/keep/bare/member launch and its ~3–5 s is the cost of a distinct process, which a pooled process with the wrong mounts cannot honour: a pre-spawned child cannot be given the parent's window after the fact, so serving it from the pool would silently reproduce the invisible-brief bug. Stated in the PR body's Backwards compatibility section.

@bolichen97

bolichen97 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor Author
  • prompt.md still says $KIROCREW_SCRATCH is also TMPDIR, which is false in a child span=0347c1400de7 — fixed in 11b31b9

Both prompts drop the "(also your TMPDIR)" clause and state it the other way round: $TMPDIR is a per-PROCESS temp dir a sub-agent does not see, so anything another process must read goes under $KIROCREW_SCRATCH by name. prompt-orchestrator.md stays at its 23,448-byte ceiling (test_prompt_compact_contract).

@bolichen97

bolichen97 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Point patch with an unfixed sibling: shared_scratch never reached the runtime _start_kiro_runtime_impl spawns span=d9e4446d2423 — fixed in 11b31b9

AcpProvider now carries shared_scratch and hands it to both AcpRuntime constructions on the kiro path (first spawn and resume respawn). End-to-end test on the kiro dedicated path: TestTheKiroDedicatedPathCarriesTheTree::test_the_runtime_the_provider_spawns_is_built_with_the_tree drives AcpProvider._start_kiro_runtime and asserts the constructor kwargs carry the tree, no adoption, and work_scratch_dir answers the live process's directory.
The sibling set is now closed by construction rather than by enumeration: the capability is read off the LLMProvider ABC and every process class that can serve a session (AcpClient, AcpRuntime via provider or companion or _bg successor) takes the same shared_scratch parameter.

@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 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for 27db263abde721e4f4b5f3e8cb135b565e383350; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

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

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The warm pool no longer serves dedicated children under bypass_shared_scratch span=0de57f947562 — accepted-and-deferred

The follow-up the Clears-when names — pool_decision telemetry / a measured fan-out, or a warm path for tree-joined children (a pool keyed by parent tree) — is #12791 (label deferred-finding, assignee bolichen97, Due 2026-10-20). A pooled child's mounts are fixed at pre-spawn, before any parent exists, so nothing in this PR can hand it a tree after the fact; the run that motivated the PR took the shared-session arm, which spawns no process.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Suggestion: one manual fan-out on a real macOS host before the next release span=614b36973a84 — accepted-and-deferred

Tracked as #12802 (label deferred-finding, assignee bolichen97, Due before the next release): a parent-staged file read by a dedicated child through the second window on macOS and Windows. In-tree, TestTwoWindowsInTheScratchMask pins the exact two-window shape on both the Linux launcher and the Seatbelt profile builder and runs on the macOS lane.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved 30 commits since 27db263, including #12865 (drops the stale 501-until-diag premise in test_mcp_debug) that was the inherited shard-1 red on the previous head, and overlapping acp/client.py, providers/acp.py, providers/base.py (no conflicts). Scoped tests for the overlapping areas plus test_mcp_debug pass locally; CI re-running on 53ea9a6. No code change in this PR since the last reviewed head.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Writable owner marker can delete a live session tree span=033f2bc5b901 — rebutted (no new capability; retrospective at ×5 on this span)

The premise is right: .owner sits inside the tree, and the tree is mounted read-write into every agent process that belongs to it. The conclusion does not follow, because the process that could write a dead pid into the marker already holds rm -rf "$KIROCREW_SCRATCH"/* on the same mount — the marker route deletes the same files an hour later and only if nothing in the tree was touched meanwhile (the sweep needs dead-owner AND idle ≥ _UNOWNED_GRACE_SECONDS, then a locked idle recheck). A child and its parent share one trust domain by construction — the child is already handed the parent's sandbox_mode, extra_env, memory and project — so the marker widens nothing; other session trees stay behind the whole-root mask. Masking .owner from agents would need a per-file mask inside an rw window (a Linux bind over one file, a Seatbelt path deny, nothing on Windows) for a defence that does not change what the attacker can already do.
Retrospective, this span having been raised in rounds 2, 3, 4, 10 and now 16: every round's finding was about trusting bytes from a directory the agent writes, and every round's fix hardened the READ (lstat-refused links, O_NOFOLLOW, fstat regular-file check, 4 KiB cap, read to EOF, pid range, non-fatal garbled). Those defences protect the GATEWAY from a planted link steering an unsandboxed write, and they are complete for that purpose (test_secc_poc_scratch_owner_symlink.py). They were never meant to make the marker's pid list trustworthy against its own owner — that is main's design for every per-process scratch dir today, and moving ownership metadata out of the window is a separate change to main's layout (and to the S5 ratchet), tracked as a follow-up under #12802, not a fix this PR owes.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Suggestion: shrink or lazily arm the warm pool if bypass_shared_scratch dominates span=a5d8ca1a945c — accepted-and-deferred

Exactly the decision #12791 (label deferred-finding, assignee bolichen97, Due 2026-10-20) is filed to take once _record_pool_decision telemetry is in: keep, shrink, lazily arm, or make the pool tree-aware.

@bolichen97

Copy link
Copy Markdown
Contributor Author

/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.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the gpt AI finding as false positive, not applicable, or explicitly accepted for 53ea9a6d174f09ddb78b83154b4f76c8b039c96e.

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.

This decision applies only to this commit. A new push requires a new judgment.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved 8 commits since 53ea9a6, including #12914 (the macOS skip for test_subprocess_pool::…not_utf8, the only red on the previous head). Overlap in docs/system-specs/modules/subagent.md, the two prompt files and troubleshooting.md (docs only, no conflicts; prompt-orchestrator.md stays under its 23,448-byte ceiling at 23,445). No code change in this PR since the head GPT/Opus last judged; scoped tests (1526) pass locally. CI re-running on 23dec27.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Every dedicated child of a scratch-bearing parent bypasses the pool; a 42-child fan-out pays 42 cold spawns span=6d4741494d08 — accepted-and-deferred

The follow-up that names the pool's future shape and the fan-out-scale measurement is #12791 (label deferred-finding, assignee bolichen97, Due 2026-10-20). A pooled child's mounts are fixed at pre-spawn, before any parent exists, so nothing in this PR can hand it a tree after the fact; the run that motivated the PR took the shared-session arm, which spawns no process.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Suggestion: record a pool-bypass counter so the pool's residual value is observable span=ef052062c522 — accepted-and-deferred

_record_pool_decision already receives pool_decision="bypass_shared_scratch" on this path, so the signal is emitted today; surfacing it as a counter / reading it post-merge is the first step of #12791 before any per-tree pooling is built.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • A FIFO planted at .owner parks the marker reader forever span=2e3d4413a0d0 — fixed in 95027ea

Right: _refuse_linked and O_NOFOLLOW see only links, and the S_ISREG check ran after an open that, on a FIFO with no writer, never returns — from the sweep or from a spawn's adopt_owner, on an executor thread. _read_owner_pids now opens O_RDONLY | O_NONBLOCK | O_NOFOLLOW: the open returns at once and the existing fstat rejects the FIFO as "not a regular file" (adopt_owner → "garbled", sweep skips); a no-op for the regular-file case. Pinned by test_a_fifo_planted_at_the_marker_does_not_park_the_reader (POSIX only): the read runs on a daemon thread with a 5 s join so a regression FAILS fast instead of hanging the worker; dropping O_NONBLOCK fails it in ~6 s. Spec updated.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • A dropped inherited window remains cached across runtime restarts span=25513d154ea8 — fixed in 4ec0f2c

Right: the runtime drops an inherited window that was swept and falls back to its own directory, but AcpProvider._shared_scratch kept the constructor's value, so a restart re-sent the swept path, the runtime dropped it again and started a third tree — losing what the first runtime staged. _start_kiro_runtime_impl now records runtime.work_scratch_dir off the LIVE runtime once it takes over as the client, so the restart joins the directory this session actually has. Pinned by test_a_swept_inherited_tree_is_replaced_by_the_live_one_for_the_restart (first build gets the swept path, the provider records the live tree, the restart's build gets that tree); removing the record fails it. Spec paragraph updated.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The pool's primary fan-out consumer never claims again while the pool keeps pre-warming span=960b69b174ae — accepted-and-deferred

The follow-up to re-key warm pre-spawns per session tree (or retire/shrink the pool on measured hit rate) is #12791 (label deferred-finding, assignee bolichen97, Due 2026-10-20). A pooled child's mounts are fixed at pre-spawn, before any parent exists; the run that motivated this PR took the shared-session arm, which spawns no process.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The _bg tree lives for the gateway lifetime with only a troubleshooting entry as its bound span=fb3e7101e27a — needs-a-decision (documented trade; follow-up filed)

The spec states the trade; src/kiro_crew/docs/troubleshooting.md names the path, the du one-liner and the remedy. A size/age report in the gateway's own diagnostics (observe-only line from sweep_dead_scratch) and session-scoped pruning inside the tree are tracked as #12802 (label deferred-finding, assignee bolichen97). Not done here: which session "ended" is a lifecycle the sweep cannot read, and a wrong guess deletes live work — the failure this PR exists to stop.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved 15 commits since 95027ea, overlapping acp/client.py, acp/runtime.py, config/loader.py, providers/acp.py (no conflicts). Scoped tests for those areas (1946) pass locally; CI re-running on 4ec0f2c. The Windows shard-4 red on the previous head was test_diag_procs.py::test_an_unchanged_process_still_gets_its_rate (main #12745; the CPU-rate assertion folds the real time between two scans into a rewound 10 s window — 48.3% vs 50%±1 on a slow runner), not this PR.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Failed refresh leaves inherited scratch exposed to deletion span=033f2bc5b901 — fixed in fd99ef3

Right: when os.utime raised, shared_scratch_window still returned the path, so a dead-owner idle tree could be mounted with no hold and swept under the mount before the spawn adopted it. The failure branch now asks whether the sweep could take the tree on its owner alone (_sweep_could_reclaim: a readable marker naming no live pgroup — absent/linked/garbled markers are the cases the sweep skips for good, so they read as safe): a live-owner or unowned tree is handed out as before; a dead-owner tree is refused with a warning and the spawn falls back to its own directory — visibility lost, not files. Pinned by test_a_failed_refresh_refuses_only_a_tree_the_sweep_could_take (utime patched to raise: dead → None, live → path, unowned → path, dead tree still on disk); disabling the check fails it. Spec updated.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved 5 commits since 4ec0f2c, overlapping acp/client.py (no conflict). Scoped tests (1269) pass locally; CI re-running on fd99ef3.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Fresh background tree is not retained for backend switches span=95ff99ff15ec — fixed in c5c829d

Right: the tree was recorded only when a LATER acquisition read the slot's runtime as a predecessor, and _retire_stale_backend_bg_runtime retires it without that read, so the tree nobody remembered was swept an hour after the runtime exited and switching back started empty. get_bg_session now records replacement.work_scratch_dir on BackgroundRuntimeState.inherited_scratch the moment the replacement takes the slot — which is also the truth when the inherit was dropped (swept) or abandoned. Pinned by test_the_live_runtimes_tree_is_recorded_at_the_slot_not_at_the_next_read (first runtime's tree is on the state right after the acquisition; with the slot cleared by a path that never re-reads it, the next replacement is built with that tree); removing the record fails it. Spec sentence updated.
Note: I re-ran this lane on fd99ef3 by mistake alongside the quota-failed runs and cancelled it once I saw the failure was this finding, not the rate limit.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main +1 (no overlap); CI re-running on c5c829d. Inherited red to expect until #12943 lands: test_crew_log_exc_info_sites.py::test_no_exc_info_site_anywhere_in_kiro_crew_holds_a_crew_log_handle flags two exc_info=True sites in apps/builtins/issue_radar/backend/crew_store.py (#12303 vs the #12812 ratchet); this PR does not touch that module.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The warm pool stops serving its primary workload under bypass_shared_scratch span=824f0f4f6263 — accepted-and-deferred

The follow-up the Clears-when names — measure fan-out wall-clock with the bypass, or make pooled pre-spawns tree-aware / shrink / retire the pool — is #12791 (label deferred-finding, assignee bolichen97, Due 2026-10-20). A pooled child's mounts are fixed at pre-spawn, before any parent exists; the run that motivated this PR took the shared-session arm, which spawns no process.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Two require-not windows in one Seatbelt deny has never run on a real macOS host span=58fb5f3c4876 — accepted-and-deferred

The manual two-window subagent spawn on a macOS host is #12802 (label deferred-finding, assignee bolichen97, Due before the next release). In-tree, TestTwoWindowsInTheScratchMask pins the profile builder's output for the exact two-window shape AND runs on the macOS lane (macOS Tests (on demand), green on this PR since #12914), so the builder's macOS behaviour is exercised there; what remains unproven is the kernel's evaluation of the emitted profile, which only the manual spawn covers.

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

Copy link
Copy Markdown
Contributor Author

Rebased: main +4 since c5c829d, including #12943 (the crew_store.py exc_info fix that was the inherited shard-7 red on the previous head); overlap in sandbox.py (comment-only change on this side, no conflict). test_crew_log_exc_info_sites and the scoped suites (1272 + 1182 sandbox tests) pass locally. No code change in this PR since the head GPT and Opus last judged clean; CI re-running on 6885791.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Dropping an inherited window the caller passed is only debug-logged, so a fan-out degrading to per-child scratch is not operator-visible span=6315df84254b — accepted-and-deferred

Agreed on the shape: the two shared_scratch_window branches that drop a path the caller actually passed ("not under the managed root", "gone or not a plain dir") log at debug today; the refresh-failure branch already warns. Raising those two to warning is a two-line follow-up filed under #12802 (operability items for this feature, label deferred-finding, assignee bolichen97) rather than another head here: this PR's code has now been judged clean by GPT and Opus on two consecutive heads, and each new head re-runs the full review round. The swept case is the one that matters for the motivating fan-out and it is already covered — a swept tree means the parent's own allocation was reclaimed, which the sweep logs at info with the directory count.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Suggestion: lean on the _BackgroundRuntime Protocol / provider ABC instead of getattr at the seams span=5acaa4040a16 — accepted-and-deferred

The getattr reads at session_background and subagent_manager/run.py mirror the adjacent reads those seams already do for acp_backend and _pool_cwd (a mocked or non-ACP provider must not fail the spawn), and LLMProvider.work_scratch_dir / the _BackgroundRuntime Protocol already declare the capability, so a rename is caught by mypy where the Protocol is used and by TestEveryProcessSpawnSeamIsAccountedFor at the seams. Tightening the two remaining reads to the declared types is folded into #12802.

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

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants