並行 IDD session 共用 working tree 互撞（branch parking / 同檔 WIP / orphan commit）— worktree 隔離策略 + merge-completeness gate

[kiki830621]

Problem

多個 IDD agent session 並行對同一個 repo跑 idd-implement 的 direct-commit-on-main 路徑時，它們共用同一個 working tree，互相踩踏。

Original (user, 2026-06-03)：
「可以在 idd 裡面開問題嗎？像你發現會撞，我覺得就是預設沒開 worktree 的結果，或者你覺得有什麼更好的方法嗎」

Type

enhancement（design FR：並行 session 的 working-tree 隔離策略）

Evidence（real incident，2026-06-03，ai_martech_global_scripts 上連續 ~3 個並行 agent session）

碰到的具體症狀：

1. main tree 被別 session parked 在它的 feature branch：我（session A）在 main 上 commit #1059；稍後另一 session 在同一個 main working tree checkout 了 idd/cluster-... branch → 我回來時 git status 跟前一次檢查結果不同（檔案在兩次 git status 間出現/消失）。
2. 兩個 session 改同一個檔案：union_production_test.R 同時有我的 #1059 footer hunk（line ~600）和別 session 的 #1067 default-product-line hunk（line ~429）。git add <file> 會把對方未完成的 hunk 一起 commit → 我被迫用 git add -p 外科式只 stage 自己的 hunk（leak check 確認 #1067 沒混進去）。
3. orphaned commit（最毒）：#1066 的 crash fix commit 在 cluster branch（c2cc7b5），但 PR #1076 merge 的是不含它的版本 → 一個 live Shiny crash（positionKFE AI 按鈕 object 'ns' not found）留在 main 上沒被發現，直到我用 git cherry -v origin/main <branch> patch-id 比對才抓到 orphan。

Root Cause（兩個正交的失敗模式）

FM-1 — 共享 working tree 並行碰撞：direct-commit-on-main 路徑（many repos / 慣例如此）沒有預設 worktree 隔離，N 個並行 session 共用一個 tree → branch parking、同檔 WIP 混合、git status race。這正是 user 的 hypothesis。

FM-2 — orphan commit：branch 上的 commit 沒進 main（PR merge 了 partial 版本 / branch 分歧）。worktree 救不了 FM-2 —— 反而 branch-per-issue 工作流（worktree 鼓勵的）放大了它：每條 branch 都要 merge 回去，merge 不完整就 orphan。

Design options

FM-1（並行碰撞）

選項	做法	Trade-off
A. 無條件 worktree-default	每個 idd-implement 都 idd-worktree.sh create #N，在自己的 worktree 工作	結構解，但每 session 一份 checkout（~200-500ms + disk）；跟 direct-commit-on-main 慣例衝突（worktree 各自要 branch → 失去「直接 commit main」的簡單性，且每條都要 merge 回去 → 放大 FM-2）
B. 條件式 worktree（偵測並行才隔離）	solo session 維持輕量 direct-commit；偵測到 ≥2 active IDD worktree/session（或 lock）時，才強制 worktree 隔離	best-of-both：solo 不被課稅，並行才付隔離成本。需要可靠的 concurrency-detect signal（worktree registry / lock file / process scan）
C. 共享樹 lock/guard	pre-commit / pre-checkout guard 偵測「另一 IDD session 正在這個 tree 活動」→ refuse/warn before parking branch 或 staging 進 dirty shared tree	最輕，但不解結構問題，只 surface

FM-2（orphan commit）—— 獨立 fix，跟 worktree 正交

merge-completeness gate：在 idd-close（或 PR-merge 後）跑 git cherry -v origin/main <branch>（patch-id 比對），確認 branch 每個 commit 的 content 都到了 main 才算 done。+（patch-id 不在 origin）的 commit 須逐一驗證 content 已在 origin（merge context 造成 sha 不同的 false-positive）或 genuinely orphan。這會抓到 #1066。 成本低、跟 worktree 決策無關、價值高。

Recommendation（我的「更好方法」）

• FM-1 → 選 B（條件式 worktree），不是 A。無條件 worktree-default 對 solo session 是 dead-weight 且跟 direct-commit 慣例打架；只在偵測到並行時強制隔離，兩全。
• FM-2 → 加 merge-completeness gate 到 idd-close，獨立於 worktree 決策。這是這次 incident 真正救命的東西（FM-1 只是讓人不舒服，FM-2 是 live customer crash 漏到 main）。

Impact

• idd-implement（Step 0.5 PR/direct-commit path resolution + worktree acquisition）
• idd-worktree.sh / references/worktree-isolation.md（concurrency-detect signal）
• idd-close（新增 merge-completeness gate — FM-2）
• 影響所有用 IDD 的 repo，不只 ai_martech

Decision points（留給 diagnose / discuss）

• FM-1 走 A / B / C？（我推 B）
• B 的 concurrency-detect signal 怎麼定義（worktree count / lock / process scan）？
• FM-2 的 gate 放 idd-close 還是也放 idd-verify（PR mode）？
• FM-1 + FM-2 是否拆兩個 change / 兩條 PR（建議：是，正交）

---

Linked-Context Siblings Filed (Step 4.7)

• idd-close 缺 merge-completeness gate：branch commit 沒進 main 的 orphan 漏不掉（git cherry patch-id check）(sister concern from #183) #184 — FM-2 (orphan commit → merge-completeness gate) 拆出獨立追蹤（正交於 worktree 決策、獨立可做、抓到 #1066 live crash 的根因）

---

Current Status

Phase: diagnosed
Last updated: 2026-06-03 by idd-diagnose

Key Decisions

• Complexity = Spectra（published plugin behavior contract + cross-skill impact）；spectra change 在 plugin repo clone 做，非 ai_martech cwd
• 收斂為 Option D（lock-based 非對稱 escalation）（spectra-discuss 2026-06-03，supersedes 原「建議 B」）：先到者持 lock 佔 main tree（direct-commit 零稅）、後到者偵測 lock 自我 escalate 進 worktree；配 idd-close 缺 merge-completeness gate：branch commit 沒進 main 的 orphan 漏不掉（git cherry patch-id check）(sister concern from #183) #184 gate。詳見 discuss conclusion comment
• FM-2 orphan gate 拆 idd-close 缺 merge-completeness gate：branch commit 沒進 main 的 orphan 漏不掉（git cherry patch-id check）(sister concern from #183) #184（正交，獨立 PR）

Blocking

• 待 discuss 對齊 A/B/C + concurrency-detect signal 定義

Sister Issues

• idd-close 缺 merge-completeness gate：branch commit 沒進 main 的 orphan 漏不掉（git cherry patch-id check）(sister concern from #183) #184 — FM-2 merge-completeness gate（orphan，正交）

[kiki830621]

Diagnosis

Type

feature（design FR：並行 IDD session 的 working-tree 隔離策略）

Analysis — 需求拆解

Scope split：本 issue（#183）= FM-1（並行碰撞）；FM-2（orphan commit）已拆到 #184 獨立追蹤（正交於 worktree 決策）。

FM-1 需求：當 N 個 agent session 並行對同一 repo 跑 IDD 時，不該共用一個 working tree。可選策略：

選項	核心	主要 trade-off
A. 無條件 worktree-default	每個 idd-implement 都進自己的 worktree	結構乾淨，但 solo session 被課 checkout 稅 + 跟 direct-commit-on-main 慣例衝突 + 放大 FM-2
B. 條件式 worktree（偵測並行才隔離）	solo 維持輕量 direct-commit；偵測 ≥2 active session/worktree（或 lock）才強制隔離	best-of-both，但需可靠的 concurrency-detect signal
C. 共享樹 lock/guard	偵測「另一 session 在此 tree 活動」→ pre-checkout/pre-commit refuse/warn	最輕，但不解結構、只 surface

Impact

• idd-implement Step 0.5（PR/direct-commit path resolution + worktree acquisition）
• idd-worktree.sh + references/worktree-isolation.md（concurrency-detect signal、managed worktree 生命週期）
• references/pr-flow.md（concurrent-session isolation 段落，目前是 advisory「prefer worktree」）
• 影響所有用 IDD 的 repo

Strategy（建議 B，待 discuss 對齊）

• 定義 concurrency-detect signal（git worktree list job-worktree count / lock file / process scan）— 注意 idle ≠ done（這次 incident 親身驗證：watcher 等 quiet 等不到，因 session turn 之間沒 process 但沒結束）
• idd-implement Step 0.5：偵測到並行 → 強制 idd-worktree.sh create #N；solo → 維持現狀
• 更新 worktree-isolation.md / pr-flow.md 的 normative 行為
• FM-2 orphan gate → 見 idd-close 缺 merge-completeness gate：branch commit 沒進 main 的 orphan 漏不掉（git cherry patch-id check）(sister concern from #183) #184（獨立 PR）

Complexity

Spectra

• Layer 1：非 narrative / 非 ad-hoc / 非獨立多檔 → 不命中
• Layer 2（必要）：命中 — 改的是 published plugin skill（idd-implement）對 future callers 的 behavior contract（path resolution / worktree acquisition），且該 contract 已是 documented spec（pr-flow.md / worktree-isolation.md）
• Layer 3（確認）：命中 — 修改既有 published spec 的 normative behavior + 影響 2+ specs（idd-implement / idd-worktree / pr-flow）+ 架構性長期決定（並行模型）
• → Spectra

跨 repo caveat：#183 的 spectra change + 實作 在 PsychQuant/issue-driven-development 的 clone 裡做（plugin repo 有自己的 openspec/），不是 ai_martech cwd。ai_martech 的 /spectra-* skills 操作 ai_martech 的 openspec/ —— 要在 plugin repo dev clone 跑對應流程。

Cross-Company Sweep (IC_R012)

Outcome: silent skip — #183 在 PsychQuant/issue-driven-development（plugin repo），不在 5-公司 commercial scope（QEF_DESIGN/D_RACING/MAMBA/WISER/kitchenMAMA）。per override opt-out table「repo not in commercial-project scope → silent skip」。本 FR 影響「所有用 IDD 的 repo」是 plugin-level，非 per-company 分流。

Risks

• 改 default 行為會打破既有 caller 的肌肉記憶（direct-commit-on-main 的簡單性）
• concurrency-detect signal 不可靠（idle ≠ done；本 incident 的 watcher timeout 即此）→ 誤判會在沒並行時也課 worktree 稅，或在有並行時沒隔離到
• 無條件 worktree（選項 A）放大 FM-2 orphan 風險（每條 branch 都要 merge 回去）
• worktree setup 成本（~200-500ms + disk per session）

Residue

更大的 horizon：「多 agent session 並行的 IDD orchestration 該長怎樣」不只是 worktree 機制——還有 session 生命週期、誰擁有 main tree、quiescence 如何判定（這次 watcher 證明 process-quiet ≠ session-done）。本 issue 能 operationalize 的是 working-tree 隔離機制；「並行 session 的協調模型」這個跨 session 的設計問題接不進單一 change，標記留待後續（可能一條 meta-principle 或 idd-orchestration spec 承接）。

Vagueness Pre-check

• V1 (vague WHAT): 2 — 交付物清楚（並行 session 不共用 working tree）；開放性是「A/B/C 哪個」= 列舉好的 decision point，非 vagueness
• V4 (vague ACCEPTANCE): 3 — 可測（並行不撞 + solo 不被課稅），策略選擇待 discuss
• Triggered: no — both ≤ 3（decision point ≠ 模糊；Spectra discuss 即用來對齊 A/B/C）

[kiki830621]

Discuss Conclusion (spectra-discuss, 2026-06-03) — supersedes the body's "建議 B"

A focused discuss reframed the problem and converged on a better design than the original Option B.

Reframe (codebase scout)

• Worktree isolation is already the documented PR-path default (references/pr-flow.md #947 rule 1) + scripts/idd-worktree.sh managed helper exists.
• FM-1 actually happened on the direct-commit-on-main path, which has zero concurrency protection (the repo commits straight to main, no PR).
• Deeper tension: direct-commit-on-main is fundamentally incompatible with concurrency — two sessions can't both commit to main in one working tree. Any fix must either serialize (lock) or branch (worktree).

The constraint that selected the design

User: 「我剛開始開一個視窗的時候其實不知道自己會不會再開一個」
(When I open the first window, I don't yet know whether I'll open a second.)

This kills naive Option B (detect-"am-I-concurrent"-at-start): session 1 starts alone, can't detect future concurrency, and can't retroactively re-isolate once it's already chosen direct-commit in the shared tree. By the time session 2 appears, session 1 is already parked in the shared tree. This is exactly the incident's order (#1059 session on main → another session checked out a cluster branch in the same main tree → collision).

Decision: Option D — lock-based asymmetric escalation

Flip the detection question from "am I concurrent?" (unknowable for session 1) to "is the shared tree already held?" (knowable by every later session):

• Each session at idd-implement Step 0.5 tries to acquire a lock on the shared working tree (holder id + PID/heartbeat + timestamp; e.g. .git/idd-tree.lock or .claude/.idd/tree-lock).
• Lock acquired (first-come / solo) → stay on main tree, direct-commit-on-main, zero worktree tax, convention preserved.
• Lock held by another live session → self-escalate via idd-worktree.sh create <N>, work in own worktree+branch, merge back at close (solo FF → looks like direct-commit; genuine divergence → real-merge).
• Lock released at idd-close / session end; stale-lock (dead holder) reclaimed via PID liveness / heartbeat TTL.
• Ships together with idd-close 缺 merge-completeness gate：branch commit 沒進 main 的 orphan 漏不掉（git cherry patch-id check）(sister concern from #183) #184 (merge-completeness gate) — escalated sessions branch+merge, so the orphan defense is required, not optional.

Why D resolves the trilemma

• Asymmetric: first-comer holds the tree for free (no prediction needed); later-comers detect the lock and isolate themselves. No session ever predicts the future or retroactively changes its tree.
• Solo (the common case) keeps pure direct-commit-on-main, zero cost.
• Concurrency is handled by whoever shows up second+, at their own cost.
• idle ≠ done sidestepped: the later session does NOT wait for the holder to finish — it just isolates immediately. The lock only answers "is someone else live in this tree?", reclaimed by liveness, never by "are they done?".

Validated against the real incident

• session A (#1059) holds lock on main; session B starts → detects lock → goes to its own worktree instead of checking out a cluster branch in the shared main tree → FM-1 prevented.
• #1066 orphan caught by idd-close 缺 merge-completeness gate：branch commit 沒進 main 的 orphan 漏不掉（git cherry patch-id check）(sister concern from #183) #184 gate → FM-2 prevented.
• Both failure modes covered by D + idd-close 缺 merge-completeness gate：branch commit 沒進 main 的 orphan 漏不掉（git cherry patch-id check）(sister concern from #183) #184.

Interface depth (Step 4)

• Seam: idd-implement Step 0.5 path-resolution (the lock acquire / escalate decision).
• Adapter: single — idd-worktree.sh (already exists); new logic is detect+dispatch, not a new adapter.
• Deletion test: remove the lock-detect → back to FM-1 shared-tree collision. Meaningful.

Open question for /spectra-propose (in the plugin clone)

Stale-lock reclaim: normal close releases the lock, but a crashed/abandoned session leaves a stale lock. Reclaim via PID liveness check vs heartbeat TTL? (Extension of the idle≠done lesson — judge "holder still alive?", never "holder done?".)

Next

/spectra-propose — must run in the PsychQuant/issue-driven-development dev clone (its own openspec/), not the ai_martech cwd. design.md captures Option D + the stale-lock open question; #184 is a separate companion change/PR.

[kiki830621]

Verify: #183 (local uncommitted diff — Spectra change concurrent-session-tree-lock)

Result: FAIL — design-fork, do not merge. The mechanics are clean, but the lock is a no-op for its stated purpose (FM-1 prevention), and the green tests are false assurance.

Engine

5 general-purpose Agents (requirements / logic / security / regression / devil's-advocate). Codex cross-model lens skipped (HTTP 401, all session) — recorded, not silent.

Findings

#	Severity	Finding	Source	Action
1	CRITICAL	The lock never holds. idd-implement Step 0.4 calls acquire with no --pid → helper defaults to $$ (its own subprocess PID, dead the instant it returns) → every later acquire sees a dead holder and reclaims → a second concurrent session always steals the lock (100% reproducible), exit 3 → self-escalate never fires. FM-1 is not prevented.	logic (B1) + devil's-advocate	Blocking (design)
2	HIGH	PID-liveness is mismatched to the invocation model. No single persistent probeable process == "this IDD session is live" at the right granularity: $$ is ephemeral (the helper), $PPID is immortal within a claude instance (over-isolates), IDD_SESSION_ID is never exported anywhere (0 occurrences), and the heartbeat is written once at acquire, never refreshed (active operator goes stale → wrongful reclaim → the "idle ≠ done" the design swore to avoid). Fixing the --pid source hits this pincer.	devil's-advocate	Blocking (design)
3	HIGH	Green tests are false assurance. The spec acceptance criterion uses the test's own $$, which in the harness is the always-alive runner — so 10/10 fixtures pass while production (where $$ = dying helper) is broken. The wrong abstraction is baked into the contract.	devil's-advocate (M3)	Blocking (spec)
4	MEDIUM	mkdir-win → write_info steal window: between the atomic mkdir and write_info, info is absent → a competitor reads empty pid → holder_is_live false → double-holder.	logic (B2)	In-scope (if salvaged)
5	MEDIUM	Destructive reclaim TOCTOU: stale path does rm -rf "$LOCK"; mkdir with no recheck → a late rm -rf can wipe a valid fresh lock another session legitimately took → double-holder.	logic (B3)	In-scope (if salvaged)
6	MEDIUM	Missing .gitignore self-add: .claude/.idd/tree-lock/info (holder/pid/heartbeat) is git-trackable → violates spec Req 1 "not under version control" SHALL. Needs acquire-path self-add like idd-worktree.sh (plugin-distributed → downstream repos lack a hand-written rule).	requirements (F-1) + DA (M4)	In-scope
7	LOW	Planted pid=0 → kill -0 0 always succeeds → lock wedged un-reclaimable. Add [ "$hpid" -gt 0 ].	security (S-1)	In-scope
8	LOW	IDD_SESSION_ID never set → acquire/release run in different processes with different fallback ids → holder-scoped release no-ops → lock leaks (only "self-heals" if the lock worked, which #1 shows it doesn't).	regression	In-scope

Verdict

The helper's plumbing (atomic mkdir, sanitized id, holder-scoped release, exit-code contract) is correct in isolation — but #1 shows the lock provides zero concurrency isolation in the real wiring, and #2/#3 show no --pid choice fixes it without a redesign + spec re-debate. Only the Devil's Advocate caught the fatality; the other lenses reached PASS via safety nets (green fixtures / fail-open / reclaim-self-healing) that all presuppose the lock has a function.

Not merged (uncommitted). Returns to design — see the fork in the next step.

[kiki830621]

Verify R2: #183 — PASS (after design-fork rescope + R2 fixes)

Result: PASS. R1's fatal no-op (B1) is fixed by the rescope; R2's two residual concurrency findings are fixed and stress-verified.

Engine

R2: 2 adversarial Claude reviewers (logic + devil's-advocate). Codex skipped (HTTP 401, all session).

R1 → rescoped (cross-terminal, $PPID-keyed)

• B1 (was FATAL no-op) → records $PPID (the persistent harness shell — DA confirmed it's the claude node process itself: one stable pid per instance, dies on instance exit), not the ephemeral helper $$. Two separate instances now genuinely isolate (2nd → exit 3 → escalate). ✅ empirically confirmed by both R2 reviewers.
• B2 → atomic noclobber file (set -C), no mkdir-then-write window. ✅
• B3 + S-1 + F-1 → mv-reclaim (later replaced, see R2-1) / pid > 0 guard / .gitignore self-add. ✅
• M3 false-assurance → fixtures now use real killable background processes as holders (not the always-alive runner pid); the broken $$ helper would now FAIL fixture f4b. Spec acceptance criterion corrected.

R2 findings → fixed

• R2-1 (logic, MEDIUM): the mv-aside reclaim had a lap window (a late reclaimer's mv could move the winner's fresh lock → double-acquire, 10% at 8-wide). Fixed: reclaim now runs inside an atomic mkdir mutex (serialized critical section). Stress: 0/50 double-acquire, exactly 1 winner/trial (was ~10%).
• F1 (devil's-advocate, MEDIUM): sequential same-instance self-wedge — an aborted issue (no idd-close) left the lock held by the live shared $PPID, so the same instance starting the next issue saw its own pid as a "live other" → spurious self-escalation. Fixed: re-entrant self-check (holder id == mine → re-own + refresh, never escalate against myself).

Verdict

20 falsifiable fixtures (incl. B1 / B2 / S-1 / F1 / mutex-reclaim regressions) + the 8-wide concurrent-reclaim stress all green. The lock now genuinely isolates separate claude instances; same-instance concurrency stays the already-deferred Case A. Remaining items (cross-instance close leaks → reclaimed by liveness; cosmetic .claude bare-rule recognition) are fail-safe toward over-isolation, with #184 as the orphan backstop. Mergeable.
Commits pending (uncommitted). R1 trail: #issuecomment-4618508112.