From 6142153c37f0483eff37e91cf70c15a7456e98fd Mon Sep 17 00:00:00 2001 From: Roberto Cano <3525807+robercano@users.noreply.github.com> Date: Wed, 1 Jul 2026 21:41:15 +0200 Subject: [PATCH 1/2] docs(architecture): document concurrent config-write safety (#5) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "Concurrent config-write safety" subsection to ARCHITECTURE.md → Limits: links anthropics/claude-code#29217, the probe finding (didn't repro on v2.1.153), mitigations (max_parallel_workers 2-3, no concurrent sessions, keep updated), and the residual settings.json-staging risk mitigated by the explicit-staging rule. Docs-module slice of #5; the implementer staging rule already landed in #21. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_011HosUeuSvhetARboEfDW6K --- docs/ARCHITECTURE.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 43e20a0..2fced28 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -55,3 +55,21 @@ only the adapter changes. - **2–4 parallel workers** is the practical ceiling before human review/merge becomes the bottleneck. - Token cost scales with agent count — see [`TOKEN_BUDGET.md`](TOKEN_BUDGET.md). - Remove worktrees on merge (`git worktree list` / `git worktree remove`). + +### Concurrent config-write safety +This template fans out to **parallel worktree-isolated workers**, and upstream +[anthropics/claude-code#29217](https://github.com/anthropics/claude-code/issues/29217) reported that +`~/.claude.json` (global config) can be **corrupted by non-atomic concurrent writes** from multiple +processes. That's the access pattern the template encourages, so it's worth naming — with the caveat that it's +an **upstream Claude Code** concern the template can only document + mitigate, not fix: + +- **What was measured:** a probe on v2.1.153/WSL2 (6+ parallel subagents, ~50 tool calls in a few seconds) did + **not** reproduce it — `~/.claude.json` stayed valid JSON, zero `.corrupted.*` files. #29217 was a + v2.1.59–62 / Windows report, now closed-stale. So it appears safe at modest concurrency but is + version/platform-dependent. +- **Mitigations:** keep `max_parallel_workers` at **2–3** (already advised); don't run other Claude Code + sessions / the Desktop app from the same home dir during a run; keep Claude Code updated. +- **Residual risk this template owns:** the harness rewrites the *working-tree* `.claude/settings.json` mid-run + with its session grant list, so a worker doing `git add -A` could stage a grant-drifted `settings.json` into + its PR. Mitigated by the pre-approved allow-list **and** the implementer rule to stage explicit paths only + (never `git add -A`) — see `.claude/agents/implementer.md`. From 9e18db42f193dd9ce2ed9b42eef2253838f4eaf8 Mon Sep 17 00:00:00 2001 From: Roberto Cano <3525807+robercano@users.noreply.github.com> Date: Wed, 1 Jul 2026 21:46:01 +0200 Subject: [PATCH 2/2] docs(architecture): align max_parallel_workers guidance (#5 review) Reviewer nit (both lenses, non-blocking): "keep max_parallel_workers at 2-3 (already advised)" was imprecise vs the repo's other figures. Reword to point at the 2-4 ceiling stated earlier in the same section and note the self-adapter ships 2. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_011HosUeuSvhetARboEfDW6K --- docs/ARCHITECTURE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2fced28..79a8a9f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -67,8 +67,9 @@ an **upstream Claude Code** concern the template can only document + mitigate, n **not** reproduce it — `~/.claude.json` stayed valid JSON, zero `.corrupted.*` files. #29217 was a v2.1.59–62 / Windows report, now closed-stale. So it appears safe at modest concurrency but is version/platform-dependent. -- **Mitigations:** keep `max_parallel_workers` at **2–3** (already advised); don't run other Claude Code - sessions / the Desktop app from the same home dir during a run; keep Claude Code updated. +- **Mitigations:** keep `max_parallel_workers` at the low end of the **2–4** ceiling advised above (the + self-adapter ships `2`); don't run other Claude Code sessions / the Desktop app from the same home dir + during a run; keep Claude Code updated. - **Residual risk this template owns:** the harness rewrites the *working-tree* `.claude/settings.json` mid-run with its session grant list, so a worker doing `git add -A` could stage a grant-drifted `settings.json` into its PR. Mitigated by the pre-approved allow-list **and** the implementer rule to stage explicit paths only