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）
碰到的具體症狀：
- main tree 被別 session parked 在它的 feature branch：我（session A）在
main 上 commit #1059；稍後另一 session 在同一個 main working tree checkout 了 idd/cluster-... branch → 我回來時 git status 跟前一次檢查結果不同（檔案在兩次 git status 間出現/消失）。
- 兩個 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 沒混進去）。
- 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（建議：是，正交）
Current Status
Phase: closed
Last updated: 2026-06-10 by idd-close
Key Decisions
Scope Changes
- (none — FM-1 only，per diagnosis split)
Blocking
Commits
82af476 feat: concurrent-session tree-lock — asymmetric escalationa0f91a1 chore: archive spectra change
Problem
多個 IDD agent session 並行對同一個 repo跑
idd-implement的 direct-commit-on-main 路徑時，它們共用同一個 working tree，互相踩踏。Type
enhancement（design FR：並行 session 的 working-tree 隔離策略）
Evidence（real incident，2026-06-03，
ai_martech_global_scripts上連續 ~3 個並行 agent session）碰到的具體症狀：
main上 commit #1059；稍後另一 session 在同一個 main working tree checkout 了idd/cluster-...branch → 我回來時git status跟前一次檢查結果不同（檔案在兩次git status間出現/消失）。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 沒混進去）。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 statusrace。這正是 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（並行碰撞）
idd-implement都idd-worktree.sh create #N，在自己的 worktree 工作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（我的「更好方法」）
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）Decision points（留給 diagnose / discuss）
Current Status
Phase: closed
Last updated: 2026-06-10 by idd-close
Key Decisions
$PPID（持久）非$$（ephemeral，會讓 lock 變 no-op）；scope = cross-terminal，同 instance 並行留 Case Aconcurrent-session-tree-lock（8/8 tasks，archived 2026-06-10）Scope Changes
Blocking
Commits
82af476feat: concurrent-session tree-lock — asymmetric escalationa0f91a1chore: archive spectra change