同機多個 ltm mcp 行程（bg-spare 預熱 session）各自在首查時併入語料、爭同一把 build lock（sister concern from #64）

[kiki830621]

Problem

2026-09-03 實測：本機同時有 14 個 /Users/che/bin/ltm mcp 行程，全部掛在 Claude Code 的 claude bg-spare 預熱 session 之下（ps -axo pid,ppid,command 對照 parent），存活 2 分鐘到 19 小時不等，其中 7 個仍是 v0.3.0 的舊映像（binary 換 inode 後舊行程照跑）。

每個行程在第一次 ltm_query 時都會跑 refreshIncrementally()（Sources/LTMService/LTMService.swift:819，無條件）。語料一有大量新檔（本日 174 MB／11,935 chunk），第一個拿到 build lock 的行程花 2 分 32 秒併入；其餘行程的首查若在同一窗口，會排隊等鎖（#53 決定鎖全程持有）。同一份工作只會被做一次（後到者拿到鎖時語料已是新的），但等待本身會讓那些 session 的第一次 MCP 呼叫卡住數分鐘，而 MCP client 端看到的只是沒有回應。

更正（2026-09-07 diagnose）：建置鎖是 flock(LOCK_EX | LOCK_NB)，拿不到鎖的行程不等，立即用既有索引作答並附警告（fixture 實測 0.10 s）。「排隊等鎖數分鐘」不會發生；剩下的問題是 MCP 路徑首查的併入無界（見 Diagnosis）。

Type

bug（多行程情境下的延遲放大；不涉及正確性——鎖語意是對的）

Expected

1. 先量：同時 N 個 ltm mcp 首查時，第 2..N 個的等待分佈（可用 fixture 語料＋人為 backlog 重現，不對真實索引做實驗）。
2. 決定是否需要：(a) 查詢前併入加有界等待（拿不到鎖就用既有索引作答並在回應附「索引落後」警告——MCP 回應仍缺 sourcesUnreadable 與 skipped——與 CLI 的 refresh 診斷只對齊了一半 #54 已有警告通道）；(b) 或 主動回想（proactive recall）：要不要用 hook 讓 ltm 自動提醒或自動查詢——設計決定 #64 討論中的 --no-refresh／--max-refresh-seconds 同時服務這裡。
3. 不變式 2 不動：任何「用舊索引作答」都要在回應裡說明，不得靜默。

Actual

所有行程無條件併入、無界等鎖；多 session 機器上第一次呼叫的延遲取決於別的 session 有沒有先付過那筆成本。

相關

• 主動回想（proactive recall）：要不要用 hook 讓 ltm 自動提醒或自動查詢——設計決定 #64（proactive recall）：hook 每輪查詢會把這件事放大 N 倍。
• #44 Expected ② 未實作：批次邊界不釋放寫鎖，查詢路徑的併入窗口是 0% #53（鎖全程持有的決定）、MCP 回應仍缺 sourcesUnreadable 與 skipped——與 CLI 的 refresh 診斷只對齊了一半 #54（MCP 回應的警告通道）、查詢剩餘 ~1.0–1.3s 的 profile——「1 秒以內」的下一步落點 #58／每 build 固定項改維護式記帳——#44 閘的 Q1 逐列探查與 chunkCount() 全表 COUNT 隨索引總量成長（設計決定） #61（併入成本的來源）。

Source: surfaced during /idd-diagnose #64 sister concern surfacing (Step 3.6)

---

Current Status

• Phase: diagnosed
• Updated: 2026-09-07（diagnosis 已 post；前提更正；Complexity Plan；Conflict Class A）
• Dashboard: (見 dashboard comment)

Tasks

• 1. ltm_query MCP 加 max_refresh_seconds（0＝不限），預設有界；回應附落後行
• 2. lockHeld 警告維持，tool description 說明兩種警告
• 3. ltm-cli spec lock-frequency 段補 MCP 預設一句
• 4. MCP 測試：bounded／0 無界／並行 deferred
• 5. docs/measurements/2026-09-xx-mcp-first-merge.md
• 6. CHANGELOG

[kiki830621]

備註：#64 的 hook 改變了寫鎖的頻率（記錄，不是新問題）

proactive-recall hook（43bf30b）每一個閘門放行的 prompt 都跑一次 ltm query --max-refresh-seconds 15，而查詢前的增量併入要拿 ~/.claude-ltm/derived 的寫鎖。先前寫鎖只在明確 ltm build 或查詢時有 backlog 才被拿；現在是每輪放行（實測本機打字 prompt 的放行率 0–2%，docs/measurements/2026-09-04-proactive-recall.md §3）。

對本 issue 的含意：

• 同時開著 MCP ltm_query 與 hook 的 session 裡，MCP 查詢撞到 hook 持有的鎖 → 走既有的 lockHeld 延後、用現有索引作答（行為不變，頻率變高）。
• hook 為自己的查詢設 LTM_BUILD_BATCH_CHUNKS=200，一輪最多併約五批（~13 s）；backlog 大時鎖會被連續幾輪持有。
• ltm-cli spec 那句「staleness 以 build 時長為上界」已收窄（openspec/changes/proactive-recall-cued-hook/specs/ltm-cli/spec.md 的 MODIFIED）：有界併入的上界是各次預算總和。

沒有量競爭的實際發生率；要量的話 LTM_RECALL_STATS_FILE 只記閘門結果，鎖的延後要看 ltm query 的 stderr。

[kiki830621]

Dashboard — #65

現況：已 diagnose（2026-09-07）。前提更正：鎖是 LOCK_NB，拿不到的行程 0.10 s 就回、附警告，不會排隊。真正的問題是 MCP 首查併入無界（首個行程獨付整個 backlog，真實案例 2 分 32 秒）。Complexity Plan，Conflict Class A。

你該做什麼：審 diagnosis；同意的話 idd-all 會接 /idd-plan #65（決定 MCP 預設預算與 max_refresh_seconds 參數）。

[kiki830621]

Diagnosis

Type

bug（延遲；正確性不受影響）——但 issue 的核心前提要更正：多行程並不會「排隊等鎖數分鐘」。

Root Cause / Analysis

前提檢驗（先做，因為 Strategy 取決於它）：索引的建置鎖是 flock(LOCK_EX | LOCK_NB)（Sources/LTMIndex/IndexBuilder.swift:1322），拿不到就丟 lockHeld；LTMService.refreshIncrementally 只 catch lockHeld（LTMService.swift:982，#51 的決定）→ 不併入、用既有索引作答、RefreshReport.mergeDeferredForConcurrentBuild = true；MCP 回應附一行 ⚠ 有另一個 ltm build 正在跑，本輪未併入新內容（答案來自既有索引）（RetrievalTool.swift:87）。沒有任何路徑會阻塞在鎖上。

重現（fixture 語料，不碰真實索引）：base 200 chunk 已索引，加入 1,500 chunk 的 backlog，兩個 .build/debug/ltm query 相隔 1 s 啟動：

行程	牆鐘	行為
A（先到）	21.55 s	拿到鎖、併入 1,500 chunk（≈70 chunk/s，與 §2 量測的 78 同量級）、作答
B（1 s 後）	0.10 s	lockHeld → 不等、用舊索引作答 3 筆、stderr 一行警告

查法：fixture 與兩支 stderr 在 job tmp repro65.*；重跑形狀是「ltm build 基底 → 複製 backlog 檔進語料 → 兩個 query --all-projects --k 3 背景並行，/usr/bin/time -p」。

現場（2026-09-07）：17 個 ~/bin/ltm mcp 行程，全部掛在 claude bg-spare 之下，每個 RSS 7 MB、閒置（沒被查詢前不載索引、不併入）；全部已是同一個 binary inode（issue 建立當天看到的 7 個 v0.3.0 舊映像已隨 session 輪替消失）。17 個閒置行程的成本可忽略。

所以我認為真正的 root cause 是：MCP 路徑的查詢前併入沒有上界。RetrievalTool 呼叫 service.query(text:limit:scope:)（RetrievalTool.swift:64）不帶 refreshBudget——#64 把有界併入做進 LTMService 但明列「MCP 預設行為不變」並把多行程議題留給本 issue。結果是：N 個行程裡第一個被查到的那個要獨自付完整 backlog（真實案例 2 分 32 秒，#64 diagnosis），其餘行程在那個窗口內查詢會立刻拿到舊索引＋警告——這是設計好的降級，不是 bug；但那個警告沒有量（落後幾個來源不知道），而第一個行程的呼叫者只看到 MCP 沒回應兩分半。多行程只是讓「誰付那筆錢」變隨機，並沒有讓總成本變 N 倍。

Impact

• 影響的檔案：Sources/LTMMCP/RetrievalTool.swift（傳 refreshBudget、新增可選參數）、openspec/specs/ltm-cli/spec.md（主動回想（proactive recall）：要不要用 hook 讓 ltm 自動提醒或自動查詢——設計決定 #64 已寫的 lock-frequency 段要對齊 MCP 預設）、Tests/LTMMCPTests/、docs/measurements/、CHANGELOG。LTMService 已有 refreshBudget／unmergedSources，不必動。
• 影響的使用者流程：多 session 機器上任一 session 的第一次 ltm_query（付 backlog 的那一次）；hook 路徑已用 --max-refresh-seconds，不受影響。

Strategy

• ltm_query MCP tool 加可選參數 max_refresh_seconds（整數 ≥ 0；0＝不限），預設給一個有界值（建議與 hook 同源：15 s；在 plan 階段決定並寫進 tool description），RetrievalTool 把它傳給 service.query(refreshBudget:)；預算用完時回應附 ⚠ 索引落後 N 個來源（有界併入未涵蓋，跑一次 ltm build 補齊）（沿用 主動回想（proactive recall）：要不要用 hook 讓 ltm 自動提醒或自動查詢——設計決定 #64 的 unmergedSources 與措辭）
• lockHeld 路徑的警告保持現狀（不加掃描去數落後量——那會把被 lockHeld 省下的成本再花回去）；在 tool description 說明兩種警告的差別
• ltm-cli spec 的 lock-frequency 段補一句：MCP 預設也是有界併入；--max-refresh-seconds 0／max_refresh_seconds: 0 才是無界
• 測試：MCP 端 bounded（stub 慢 embedder＋stepping clock 或 fixture backlog）→ 回應含落後行；max_refresh_seconds: 0 → 無界、無落後行；兩個 service 並行 → 第二個 mergeDeferredForConcurrentBuild（現有測試若已涵蓋則引用）
• docs/measurements/2026-09-xx-mcp-first-merge.md：本 diagnosis 的 A/B 表 + 真實 backlog 首查（~/bin/ltm 匯出密鑰、唯讀）前後對照；明寫「多行程總成本不放大」這個更正
• issue body 的 Problem 段加一則更正註（不改原文，append）：排隊不存在，LOCK_NB

Conflict Class

A_parallel_safe —— 只動 RetrievalTool.swift、MCP 測試、spec 一句、量測與 CHANGELOG；LTMService 的 refreshBudget 路徑已存在不改。與 #62（RetrievalEngine／LTMService 過濾）、#66（hook／RecallBlock）、#61（IndexBuilder）不同檔。

Complexity

Plan

• Layer 1 未命中。Layer 2 命中（MCP ltm_query 是 published tool surface，加參數＋改預設）但 Layer 3 不命中：沒有修改既有 spec 的 normative 句（主動回想（proactive recall）：要不要用 hook 讓 ltm 自動提醒或自動查詢——設計決定 #64 已把有界併入的語意寫進 ltm-cli spec，這裡只是把 MCP 的預設對齊、補一句），也不是新的架構決定——所以不到 Spectra。
• Layer P：decision-heavy（預設預算給多少、0 的語意、要不要對 lockHeld 路徑補量）＋risk-sensitive 邊界（並發、多行程）。
• Hard-gate: triggered — 單一概念（MCP 有界併入預設）散佈 RetrievalTool.swift／MCP tests／ltm-cli spec／measurement／CHANGELOG ≥ 5 檔。結論與 Layer P 一致：Plan。

→ /idd-plan #65
→ 建議 pre-implementation staging: superpowers:brainstorming（非綁定）

Risks

• 預設有界會讓 MCP 首查在大 backlog 時回「落後 N 個來源」而不是等兩分半——這是刻意的取捨，但使用者若期待「第一次查就是最新」會覺得變差；tool description 要寫清楚，且 0 可回到舊行為。
• 與 每 build 固定項改維護式記帳——#44 閘的 Q1 逐列探查與 chunkCount() 全表 COUNT 隨索引總量成長（設計決定） #61 的關係：每 build 固定項改維護式記帳——#44 閘的 Q1 逐列探查與 chunkCount() 全表 COUNT 隨索引總量成長（設計決定） #61 在處理每 build 的固定成本，有界併入不改變那筆固定成本（掃描不可中斷、計入預算——主動回想（proactive recall）：要不要用 hook 讓 ltm 自動提醒或自動查詢——設計決定 #64 R3 已定）。
• 「多行程不放大總成本」這個更正依賴 LOCK_NB；若日後有人把鎖改成阻塞，本 issue 的前提會回來——spec 的 lock 段已明寫 LOCK_NB，不另加測試（concurrentBuildsAreRefused 類的既有測試涵蓋）。

Residue

「多 session 機器上 MCP 首查應該多快才算可接受」沒有量測能裁定——沒有使用者層的延遲預算資料，15 s 是沿用 hook 的工程判斷，不是量出來的。這層留著。

Vagueness Pre-check

• V1: 2 — 要做什麼明確：量多行程首查等待、決定要不要有界等待／--max-refresh-seconds。
• V4: 3 — 完成定義是「量測＋決定＋不變式 2 的說明」，沒有量化門檻；屬結構性限制（見 Residue）。
• Triggered: no — both axes ≤ 3

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

• Not filed: 「binary 換 inode 後舊映像行程繼續跑」——MCP server 生命週期由 Claude Code 管理，本 repo 無執行點；現場已無舊映像，記錄即可。
• Not filed: 「lockHeld 警告沒有落後量」——併入本 issue Strategy 第 2 項的決定（刻意不補掃描），不另開。