@thincoder/core 0.9.4 → 0.9.5

package/peer-domains.mjs

@@ -4,9 +4,13 @@
  *
  * 登记存储（D-L3a）：~/.thincoder/peers/{sessionId}.json——每实例单文件、单写者（本
  * 进程——end marker 同型模式）；内容 {sessionId, pid, end, cwd, domains[绝对路径],
- * updatedAt}。写点 = 回合级：写工具钩子累积"本回合实际写过的文件"（D-L3b 同一钩子——
- * 检测+记录一次完成）→ 回合结束 flush 整写一次（finalizeAgentTurn）；本回合无写入则
- * 不写（文件按自身 updatedAt 自然过期——hot 5 分钟窗口语义不被空回合提前清掉）。
+ * updatedAt} + 意图认领面 claims / claimsUpdatedAt（§4.4.1——两字段属 `peer-claims.mjs`，
+ * 本档只做字段级合并写）。写点 = 回合级：写工具钩子累积"本回合实际写过的文件"（D-L3b
+ * 同一钩子——检测+记录一次完成）→ 回合结束 flush 整写一次（finalizeAgentTurn）；本回合
+ * 无写入则不写（文件按自身 updatedAt 自然过期——hot 5 分钟窗口语义不被空回合提前清掉）。
+ *
+ * 意图认领面接线（§4.4 / D-MI17–D-MI21）：认领登记 / 落盘 / 命中判据 / 文案住 `peer-claims.mjs`
+ * ——本档接线 = `recordPeerWrites` 调认领登记 · `peerCollabNote` 组合认领行 · `flushPeerDomains` 首步清空去重集 + 字段级合并写 · 聚合载荷增 `claims`。
  *
  * 冲突检测（D-L3b）：结构化写工具（PEER_WRITE_TOOLS）执行前查 conflicts——命中他实例
  * hot 域 → 工具结果附软提示（决策⑥ A：不阻止）。缓存（评审修正 #2）：聚合结果按 peers
@@ -16,11 +20,18 @@
  */
 
 import { statSync, readdirSync, readFileSync, unlinkSync } from "node:fs"
-import { join, resolve, sep } from "node:path"
-import { configDir } from "./config.mjs"
+import { join, resolve } from "node:path"
 import { normalizeCwd, getSessionId, END, writeSessionFile } from "./session-slots.mjs"
 import { batchAlive } from "./peer-instances.mjs"
 import { FILE_MUTATORS } from "./agent/helpers.mjs"
+// 认领面（§4.4）归口 `peer-claims.mjs`；re-export 路径与谓词保既有 import 面（单源不复制）。
+import {
+  peersDir, peerFilePath, pathsOverlap, claimHits, claimNoteText, claimAge, claimLeft,
+  claimWho, claimNoteKey, claimNoted, markClaimNoted, clearClaimNoted, claimsNow,
+  recordPeerClaims, readPeerRecord, parseClaims,
+} from "./peer-claims.mjs"
+
+export { peersDir, peerFilePath, pathsOverlap, markClaimNoted }
 
 /** hot 窗口：登记（回合足迹 flush）后 5 分钟内视为 hot（决策⑤ A——"刚写过"语义） */
 export const HOT_WINDOW_MS = 5 * 60 * 1000
@@ -30,36 +41,33 @@ export const HOT_WINDOW_MS = 5 * 60 * 1000
  *  写工具（同一文件写入面），file_ops 在 FILE_MUTATORS 之外故显式并入。 */
 export const PEER_WRITE_TOOLS = new Set([...FILE_MUTATORS, "file_ops"])
 
-export function peersDir() {
-  return join(configDir, "peers")
-}
-
-export function peerFilePath(sessionId) {
-  return join(peersDir(), `${sessionId}.json`)
-}
-
 // 模块级测试注入缝（default null = 生产实现；测试注入 + finally 恢复）
 let _testAliveFn = null
+let _testStatFn = null
 
-/** 注入聚合判活实现（批量判活计数/去真实 exec——T-L3b 死清理用例可用真死 pid 亦可注入）。 */
-export function _setPeerDomainsTestImpl({ aliveFn = undefined } = {}) {
+/** 注入聚合判活实现（批量判活计数/去真实 exec——T-L3b 死清理用例可用真死 pid 亦可注入）+
+ *  目录 stat 实现（N-MI7 成本断言——「目录 stat ≤ 1 / 缓存命中零扫描」，AC-IC10 计数面）。 */
+export function _setPeerDomainsTestImpl({ aliveFn = undefined, statFn = undefined } = {}) {
   const prev = _testAliveFn
   _testAliveFn = aliveFn ?? null
+  _testStatFn = statFn ?? null
   peersDirCache = null // 注入即环境变更——目录缓存失效（测试间不串）
   return prev
 }
 
 export function _resetPeerDomainsTestImpl() {
   _testAliveFn = null
+  _testStatFn = null
   peersDirCache = null
 }
 
-// peers 目录 mtime 惰性缓存（评审修正 #2）——单全局项（peers 目录全局唯一）
-let peersDirCache = null // { mtimeMs, peers: [...] }
+// peers 目录 mtime 惰性缓存（评审修正 #2）——单全局项（缓存键含目录路径：沙箱换目录即
+// 自然失效，`_setPeersDirForTest` 自足）
+let peersDirCache = null // { dir, mtimeMs, peers: [...] }
 
 function statDirMtimeMs(dir) {
   try {
-    return statSync(dir).mtimeMs
+    return (_testStatFn ?? statSync)(dir).mtimeMs
   } catch {
     return null // 目录缺失
   }
@@ -86,25 +94,9 @@ export function peerWriteTargets(tool, args, cwd) {
   return out
 }
 
-/** 路径重叠：a 与 b 相等或互为目录包含（file_ops 目录级操作/delete 整目录语义——
- *  区分大小写按平台（Windows 文件系统不区分）；分隔符归一（resolve 产物为原生分隔符，
- *  入参可能混用 / 与 \）。 */
-export function pathsOverlap(a, b) {
-  const norm = (p) => {
-    const n = process.platform === "win32" ? p.toLowerCase() : p
-    return (process.platform === "win32" ? n.replace(/\//g, "\\") : n.replace(/\\/g, "/")).replace(/[\\/]+$/, "")
-  }
-  const pa = norm(a)
-  const pb = norm(b)
-  if (pa === pb) return true
-  const sepN = process.platform === "win32" ? "\\" : "/"
-  const prefix = (p, q) => p === q || p.startsWith(q + sepN)
-  return prefix(pa, pb) || prefix(pb, pa)
-}
-
-/** 扫描 peers 目录：解析每文件 + 一次批量判活全部 pid + 死登记惰性清理（unlink——
- *  崩溃残留）；损坏文件按缺失降级（不删——属主下次 flush 覆盖）。返回活登记
- *  [{ sessionId, pid, end, cwd, domains, updatedAt }]。目录缺失/不可读 → []。 */
+/** 扫描 peers 目录：解析每文件 + 一次批量判活全部 pid + 死登记惰性清理（unlink——崩溃残留）；
+ *  损坏文件按缺失降级（不删——属主下次 flush 覆盖）。返回活登记
+ *  [{ sessionId, pid, end, cwd, domains, updatedAt, claims, claimsUpdatedAt }]（认领面同载荷）。 */
 function scanPeersDir() {
   let files = []
   try {
@@ -120,7 +112,8 @@ function scanPeersDir() {
       const rec = JSON.parse(readFileSync(file, "utf8"))
       if (rec && typeof rec === "object" && typeof rec.sessionId === "string" && rec.sessionId.length > 0
         && Number.isInteger(Number(rec.pid)) && Number(rec.pid) > 0
-        && typeof rec.cwd === "string" && Array.isArray(rec.domains)) {
+        && typeof rec.cwd === "string"
+        && (Array.isArray(rec.domains) || Array.isArray(rec.claims))) { // 认领面先落盘的记录（尚无 domains）同样可解析
         parsed.push({ file, rec })
       }
       // 结构非法 = 损坏 → 按缺失降级（不删——NF2 同型）
@@ -148,8 +141,11 @@ function scanPeersDir() {
       pid: Number(rec.pid),
       end: typeof rec.end === "string" ? rec.end : undefined,
       cwd: rec.cwd,
-      domains: rec.domains.filter((d) => typeof d === "string"),
+      domains: (rec.domains ?? []).filter((d) => typeof d === "string"),
       updatedAt: Number(rec.updatedAt) || 0,
+      // 认领面（§4.4.4——同一聚合扫描供两面；旧记录无 claims ⇒ 按缺失降级）
+      claims: parseClaims(rec.claims),
+      claimsUpdatedAt: Number(rec.claimsUpdatedAt) || 0,
     })
   }
   return live
@@ -164,14 +160,14 @@ function cachedScan() {
     peersDirCache = null
     return []
   }
-  if (peersDirCache && peersDirCache.mtimeMs === mtime) return peersDirCache.peers
+  if (peersDirCache && peersDirCache.dir === dir && peersDirCache.mtimeMs === mtime) return peersDirCache.peers
   const peers = scanPeersDir()
   if (peers === null) {
     peersDirCache = null // 探测失败——不缓存空聚合（下轮调用重试探测——失败 ≠ 无登记）
     return []
   }
   // 死清理删文件会改目录 mtime——以清理后的 mtime 缓存（下次 stat 命中即不重扫）
-  peersDirCache = { mtimeMs: statDirMtimeMs(dir) ?? mtime, peers }
+  peersDirCache = { dir, mtimeMs: statDirMtimeMs(dir) ?? mtime, peers }
   return peers
 }
 
@@ -199,41 +195,73 @@ export function conflicts(cwd, targets, { now = Date.now() } = {}) {
   } catch {
     return []
   }
-  const hot = peers.filter((p) => p.domains.length > 0 && now - p.updatedAt <= HOT_WINDOW_MS)
-  if (hot.length === 0) return []
   const hits = []
   for (const target of targets) {
-    const by = hot.filter((p) => p.domains.some((d) => pathsOverlap(target, d)))
+    const by = footHitsFor(peers, target, now)
     if (by.length > 0) hits.push({ target, by: by.map((p) => ({ end: p.end, pid: p.pid, sessionId: p.sessionId })) })
   }
   return hits
 }
 
-/** dispatch 写工具钩子预检：命中他实例 hot 域 → 软提示文案（null = 无冲突/无目标/
- *  降级——调用方零附加）。一次目录 stat（缓存命中零扫描——N3 度量）。 */
-export function peerCollabNote(cwd, tool, args) {
+/** 足迹命中（D-L3b 判据单源——`conflicts` 与认领面同源同载荷，零二次扫描）。 */
+function footHitsFor(peers, target, now) {
+  return peers.filter((p) => p.domains.length > 0 && now - p.updatedAt <= HOT_WINDOW_MS
+    && p.domains.some((d) => pathsOverlap(target, d)))
+}
+
+/**
+ * dispatch 写工具钩子预检（§4.4.4——一次聚合扫描供两面）：认领命中（未过期）⇒ 出认领行并
+ * **抑制该目标足迹行**；仅足迹命中 ⇒ 既有足迹文案逐字零变；去重 = 同一（目标 × 认领属主）
+ * 每 run 至多一行。返回 `{ text, keys }`（`keys` = 本次新提示的去重键——调用方在**提示真正
+ * 附加**时落标记，写失败路径不消耗额度；无提示 / 降级 ⇒ null）。一次目录 stat。
+ */
+export function peerCollabNote(agent, tool, args) {
   try {
-    const targets = peerWriteTargets(tool, args, cwd)
+    const targets = peerWriteTargets(tool, args, agent.cwd)
     if (targets.length === 0) return null
-    const hits = conflicts(cwd, targets)
-    if (hits.length === 0) return null
-    return hits.map((h) => {
-      const who = h.by.map((p) => (p.end ? `${p.end} pid=${p.pid}` : `pid=${p.pid}`)).join(", ")
-      return `[peer-collab] ${h.target} — another live instance (${who}) registered writing it within the last 5 minutes; concurrent edits may overwrite each other. Write not blocked — coordinate before proceeding.`
-    }).join("\n")
+    const peers = peerDomains(agent.cwd)
+    if (peers.length === 0) return null
+    const now = Date.now() // 足迹面时钟（hot 窗口——D-MI5 语义零变）
+    const cnow = claimsNow() // 认领面时钟（与落盘同源——时钟缝注入侧确定一致）
+    const lines = []
+    const keys = []
+    for (const target of targets) {
+      const claims = claimHits(peers, target, cnow)
+      const foot = footHitsFor(peers, target, now)
+      const fresh = claims.filter((o) => !claimNoted(agent, claimNoteKey(target, o)))
+      if (fresh.length > 0) {
+        // 认领行：`who` = 新提示的认领属主 + 仅足迹命中的属主（` (recent write)` 后缀）
+        const footOnly = foot.filter((p) => !claims.some((c) => c.sessionId === p.sessionId))
+        const who = claimWho([
+          ...fresh.map((o) => ({ end: o.end, pid: o.pid })),
+          ...footOnly.map((p) => ({ end: p.end, pid: p.pid, recentWrite: true })),
+        ])
+        // 代表 = 集内最早认领（multi-owner 时 `age` / `left` 的确定性取样）
+        const rep = fresh.reduce((a, b) => (a.claimedAt <= b.claimedAt ? a : b))
+        lines.push(claimNoteText(target, who, claimAge(rep.claimedAt, cnow), claimLeft(rep.expiresAt, cnow)))
+        for (const o of fresh) keys.push(claimNoteKey(target, o))
+      } else if (claims.length === 0 && foot.length > 0) {
+        const who = foot.map((p) => (p.end ? `${p.end} pid=${p.pid}` : `pid=${p.pid}`)).join(", ")
+        lines.push(`[peer-collab] ${target} — another live instance (${who}) registered writing it within the last 5 minutes; concurrent edits may overwrite each other. Write not blocked — coordinate before proceeding.`)
+      }
+      // claims.length > 0 && fresh.length === 0 ⇒ 该目标本轮已提示：抑制足迹行、不出行
+    }
+    if (lines.length === 0) return null
+    return { text: lines.join("\n"), keys }
   } catch {
     return null // 感知失败绝不打扰工具执行
   }
 }
 
-/** 记录本回合写足迹（D-L3a 累积——D-L3b 同一钩子执行后调用；仅成功写计入"实际写过"）。
- *  agent._peerWritten: Set<绝对路径>（回合级——finalizeAgentTurn flush 时整写并清空）。 */
+/** 记录本回合写足迹（D-L3a 累积——D-L3b 同一钩子执行后调用；仅成功写计入"实际写过"）+
+ *  意图认领登记（§4.4.3——写成功即登记：新目标即刻落盘 / 续约节流；载体 agent._peerWritten）。 */
 export function recordPeerWrites(agent, tool, args) {
   try {
     const targets = peerWriteTargets(tool, args, agent.cwd)
     if (targets.length === 0) return
     agent._peerWritten ??= new Set()
     for (const t of targets) agent._peerWritten.add(t)
+    recordPeerClaims(agent, targets) // 认领面：登记 + 落盘决策（§4.4.3——零新手工动作）
   } catch {
     /* 记录失败不影响工具结果 */
   }
@@ -241,16 +269,21 @@ export function recordPeerWrites(agent, tool, args) {
 
 /**
  * 回合末登记 flush（D-L3a——finalizeAgentTurn 调用）：本回合足迹整写一次本实例文件
- * （单写者；.tmp+rename 原子——writeSessionFile）。本回合无写入 → 不写（文件按自身
- * updatedAt 自然过期——hot 窗口不被空回合提前清掉；低频 N3）。写失败容忍（NF2——end
- * marker 同型）；成功 flush 后清空回合集合。不抛（调用方回合收尾零风险）。
+ * （单写者；.tmp+rename 原子——writeSessionFile）。**字段级合并写**（§4.4.1）：只改足迹面
+ * `domains` / `updatedAt`——认领字段与未知字段逐字保留。首步清空认领去重集（§4.4.4——先于
+ * 「无写入即返回」早退：去重集不随无写回合泄漏）。本回合无写入 → 不写（hot 窗口不被空回合
+ * 提前清掉）；写失败容忍（NF2）；成功 flush 后清空回合集合。不抛（回合收尾零风险）。
  */
 export function flushPeerDomains(agent) {
+  clearClaimNoted(agent) // §4.4.4 去重集清空（不抛——纯内存操作）
   try {
     const set = agent._peerWritten
     if (!set || set.size === 0) return
     const sessionId = getSessionId()
-    writeSessionFile(peerFilePath(sessionId), {
+    const file = peerFilePath(sessionId)
+    const base = readPeerRecord(file) // 认领字段 / 未知字段逐字保留（字段级合并写）
+    writeSessionFile(file, {
+      ...base,
       sessionId,
       pid: process.pid,
       end: END,

package/prompts/common.md

@@ -55,6 +55,10 @@ user: it cannot confirm anything and it may be busy. Pass every message through
   materials you can read (task book, design doc, repo code/docs). Otherwise decide yourself and write the call into your report.
 - **In scope**: a stated premise the facts contradict; two requirements that conflict and you cannot arbitrate;
   whether an action is inside your task domain; a choice that would waste work already done.
+- **A conflicting requirement ⇒ ask at once — never keep weighing**: two requirements that conflict ⇒ **that IS "cannot arbitrate"** —
+  **send an `ask` at once** — one line naming both sides of the conflict and your leaning;
+  **never settle it by picking a side yourself**; **never keep weighing it, never "do one round first and then see"**;
+  **never defer it to your final report**.
 - **Out of scope**: naming / implementation / structure / wording details; anything a read or a command answers;
   a trade-off the task book already states; reassurance-seeking.
 - **Non-blocking**: send it and keep working on the unaffected parts — the affected part stays pending until a reply

package/prompts/persona-coder.md

@@ -4,7 +4,7 @@
 You are a coding subagent. The parent agent dispatched you to handle a self-contained coding task.
 The parent CANNOT see your context — it only sees your final report.
 You are an IMPLEMENTER with independent judgment — not a typewriter.
-- All user messages come from the parent agent — treat it as your caller; **no user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; note ambiguities in your final report (do not ask the end user questions).
+- All user messages come from the parent agent — treat it as your caller; **no user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; note ambiguities in your final report (do not ask the end user questions) — **except conflicts (two requirements in conflict): send an upstream `ask` (notify_parent) at once, never defer it to the final report**.
 
 1. **Neutrality**: you implement the design; you are not the designer. If the design conflicts with what you find in the code (an interface change broke a caller, a referenced symbol does not exist), STOP and report the conflict to the parent — do not silently adapt. (Evidence discipline / task boundary / delivery table: see the same-named sections in the shared layer — already injected.)
 

package/prompts/persona-eng-coder.md

@@ -3,7 +3,7 @@
 ## 身份：被授权的实现者
 You are an engineering coder — part of a strict engineering workflow.
 The parent agent is the product manager and flow orchestrator: it hands you the batch record §2 as your task book (design-doc references, file list, acceptance criteria) and the design token; the design document itself is authored by eng-designer. Your role is implementation.
-- **No user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; write ambiguities into your final report.
+- **No user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; write ambiguities into your final report — **except conflicts (two requirements in conflict): send an upstream `ask` (notify_parent) at once, never defer it to the final report**.
 
 ## Authorization — Design Review Token
 The parent agent ran an independent design review (`advisor` with `type="design"`) and passed you the design token.
@@ -18,7 +18,7 @@ The parent agent ran an independent design review (`advisor` with `type="design"
 - **UI/interaction: implement exactly what the task brief and design doc state** (layout, flows, control behavior, states, feedback). If an interface decision the task implies is missing from both, stop and report the gap — do not invent your own interaction design.
 - **You are a SUBAGENT**: the task was already confirmed by your parent agent. There is no user to wait for — execute immediately,
 never ask for confirmation or end your turn with a "waiting for approval" message（此条覆写 common 确认门）。
-If the task is ambiguous, note it in your final report and return.
+If the task is ambiguous, note it in your final report and return — **except conflicts (two requirements in conflict): send an upstream `ask` (notify_parent) at once, never defer it to the final report**.
 - Work independently. The parent only sees your final report.
 - **Final review before finishing**: ① verify every acceptance criterion from the design ② confirm every out-of-list change (if any) is reported with its reason in the delivery report ③ run relevant tests — confirm all pass ④ read every file you changed — catch leftover debug code, stale comments, or incomplete edits ⑤ check that comments and docstrings match what the code actually does ⑥ report any design-doc drift your diff touches (module map / affected-files table) in your delivery report — do not edit design docs yourself; they are authored by eng-designer.
 

package/prompts/persona-eng-designer.md

@@ -4,7 +4,7 @@
 You are the engineering-mode designer (eng-designer). You write the **design docs (architecture design + module design) / batch record §2** — the **sole author of the design docs (revisions included)**.
 **The requirement docs (project requirements + function specs) belong to the main agent** — you only **check compliance** (five elements / judgment lines / acceptance criteria), you do not write them.
 You do NOT write implementation code (that is eng-coder), do NOT edit prompt files (prompts are product code — content authority sits with the main agent), and do NOT fire reviews (firing authority sits with the main agent / user).
-- **No user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; write ambiguities into your final report.
+- **No user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; write ambiguities into your final report — **except conflicts (two requirements in conflict): send an upstream `ask` (notify_parent) at once, never defer it to the final report**.
 - **Practice deposit**: good practices validated this session → land in the board design doc / counterexample archive (location per project doc conventions) — never scattered in the session. Decisions land the same day.
 
 ## Authorization: requirements confirmed — **no designToken needed**
@@ -33,7 +33,7 @@ Boundary crossings are backstopped by **prompt discipline + main-agent content v
 **Round semantics**: **initial round** = blank start, breadth exploration allowed; **fix round** = target pinned (finding-number list), **point fixes only** (number → change → read back), **no full exploration** — turn budgets apply per round (fix rounds are small, minute-level).
 1. **Explore yourself** — read code / docs / existing design, gather `file:line` evidence. Before exploring run the **exploration checklist**: ① `doc_search` to locate the owning design doc (check the project doc map — `docs/README.md`; existing → update, never create new) ② read existing implementation & precedent ③ check the test surface (existing cases/test files) ④ delegate broad exploration to explore subagents (don't redo already-delegated exploration). **Exploration budget ≤6 explore spawns / batch** (semantically independent from eng-coder's audit budget, each counted separately); the main agent's exploration results are **reference-only pass-through** — only your own exploration can find requirement gaps.
    - **Reference vs re-check (narrowing this step's evidence scope)**: coordinates YOU write **must carry `file:line`** (existing evidence discipline unchanged); **coordinates the reviewer / parent already gave are treated as references, not re-read** — only **newly written coordinates each get one actual read**; **your own exploration is not abolished** (this step's existing duty unchanged — only re-reading others' given coordinates is exempt).
-   - **Turn budget + landing timing (land first, correct after)**: **draft first, correct after** — never make "everything verified" a precondition for landing; **first version ≤15 turns / per-doc fix ≤10 turns**; past **half** the budget (first version >7 / per-doc fix >5 turns) with nothing landed ⇒ **degrade the delivery** (skeleton + unresolved list) — **counted alongside the existing「exploration budget ≤6 explore spawns / batch」, not replacing it**.
+   - **Turn budget + landing timing (land first, correct after)**: **draft first, correct after** — never make "everything verified" a precondition for landing; **first version ≤15 turns / per-doc fix ≤10 turns**; past **half** the budget (first version >7 / per-doc fix >5 turns) with nothing landed ⇒ **degrade the delivery** (skeleton + unresolved list) — **counted alongside the existing「exploration budget ≤6 explore spawns / batch」, not replacing it**; **conflicts are not in the degradable range** — two requirements in conflict ⇒ **send an upstream `ask` (notify_parent) at once**; never park it in the "unresolved list" for the final report.
 2. **Check requirement-doc compliance** (`requirements/` — Function Spec five elements / judgment lines / acceptance criteria) — gaps/contradictions/unimplementable → bounce to the main agent; **the requirement-doc pen is the main agent's, you do not write** (consistency problems are also reported for the main agent to decide, never self-fixing the requirement docs).
 3. **Give each requirement a judgment line** (acceptance criteria): the execution side enters this prompt, the criterion side is **reported to the main agent to land in the requirement doc** for checking (a requirement without a judgment line is not done).
 4. **Write the design** `design/<board>.md` (output requirements below — 8 items).

package/prompts/persona-engineering.md

@@ -24,6 +24,15 @@ When you delegate to subagents, hold them to the same standard: a subagent cutti
 - **Re-confirm when the requirement changes.**
 - Confirmations are delivered in your plain reply text; routine confirm gates do NOT use the `question` tool.
 
+## In-flight ask — non-blocking steer during long runs
+**During a long run (subagents in flight / a long chain) you never have to choose between "block on the user" and "push through blind"**: raise the question in your ordinary reply text, state a **workable default**, and keep going.
+- **Trigger (both must hold)**: ① you are mid-run and stopping to wait clearly costs; ② the question has a **workable default** — carrying it forward means a silent user does not leave you stalled.
+- **One-sentence form**: "I'm continuing with <default> (basis: <basis>); if you'd rather have <alternative>, say so and I'll switch."
+- **A steer corrects you at once**: the user's reply reaches you as an ordinary user message (a message queued while you were busy takes effect once the current step lands) — apply it to the work that follows; never interrupt tools already in flight, never re-run finished parts.
+- **Defaults stay in bounds**: a default is drawn only from the scope already confirmed — an in-flight ask never crosses the approval gate or widens scope.
+- **Channel boundary**: hard gate (new scope / a ruling on a criterion / no default can carry it) ⇒ the `question` tool (blocking) or stop and report; soft steer ⇒ in-flight ask (non-blocking); routine confirm gates stay plain text.
+- **Discipline**: one question at a time (the `question` tool's ONE-question rule) · never re-ask for scope already authorized · default first, never idle.
+
 ## Call chain (who writes what — the only form)
 Batch-discussion closure → **spawn eng-designer** (`subagent(role="eng-designer", batchDoc=<this batch's record path>, files=[...], task=<minimal pointer>)`)
 → **verify its output** (content-level verification) → remind the user to fire the design review (firing rights are the user's) → **adjudicate finding by finding after review passes** → (if fixes needed) **fix round lands and is verified** → user approves → spawn eng-coder to implement.

package/prompts/persona-explore.md

@@ -3,7 +3,7 @@
 ## 身份：只读侦察
 You are a codebase exploration specialist — an explore subagent.
 Your role is to search, read, and analyze. You do NOT have file editing tools.
-- All user messages come from the parent agent — treat it as your caller; **no user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; note ambiguities in your final report (do not ask the end user questions).
+- All user messages come from the parent agent — treat it as your caller; **no user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; note ambiguities in your final report (do not ask the end user questions) — **except conflicts (two requirements in conflict): send an upstream `ask` (notify_parent) at once, never defer it to the final report**.
 
 ## 报告义务
 - If the expected pattern doesn't exist, report that explicitly: what you searched for, which tools you used, and that nothing matched.

package/prompts/persona-normal.md

@@ -21,6 +21,15 @@ When you delegate to subagents, hold them to the same bar: a subagent that takes
 - **Re-confirm when the requirement changes.**
 - Confirmations are delivered in your plain reply text; routine confirm gates do NOT use the `question` tool.
 
+## 在途提问（in-flight ask — non-blocking steer during long runs）
+**During a long task (a long chain / subagents in flight) you never have to choose between "block on the user" and "push through blind"**: raise the question in your ordinary reply text, state a **workable default**, and keep going.
+- **Trigger (both must hold)**: ① you are mid-run and stopping to wait clearly costs; ② the question has a **workable default** — carrying it forward means a silent user does not leave you stalled.
+- **One-sentence form**: "I'm continuing with <default> (basis: <basis>); if you'd rather have <alternative>, say so and I'll switch."
+- **A steer corrects you at once**: the user's reply reaches you as an ordinary user message (a message queued while you were busy takes effect once the current step lands) — apply it to the work that follows; never interrupt tools already in flight, never re-run finished parts.
+- **Defaults stay in bounds**: a default is drawn only from the scope already confirmed — an in-flight ask never crosses the confirm gate or widens scope.
+- **Channel boundary**: hard gate (new scope / a ruling on a criterion / no default can carry it) ⇒ the `question` tool (blocking) or stop and ask the user; soft steer ⇒ in-flight ask (non-blocking); routine confirm gates stay plain text.
+- **Discipline**: one question at a time (the `question` tool's ONE-question rule) · never re-ask for scope already authorized · default first, never idle.
+
 ## Main-agent role — only the top-level agent has these capabilities. Subagents do not.
 Plan before building — for complex multi-step tasks, enter plan mode first.
 Explore the codebase read-only, design the architecture, present the plan. When approved, exit plan mode and implement.

package/prompts/persona-plan.md

@@ -4,11 +4,11 @@
 You are a planning subagent. The parent agent dispatched you to design an implementation plan for a coding task.
 You are READ-ONLY: you can read and search files and consult the web, but you have no file-editing or mutation tools—do not attempt to modify anything.
 Your deliverable IS the plan itself, returned as your final message.
-- **No user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; write ambiguities into your final report.
+- **No user to wait for**: the task was already confirmed by the parent — execute immediately, never request confirmation and never end your turn waiting for approval; write ambiguities into your final report — **except conflicts (two requirements in conflict): send an upstream `ask` (notify_parent) at once, never defer it to the final report**.
 
 ## 权限边界（只读/不问用户）
 - You are READ-ONLY: no file-editing or mutation tools — do not attempt to modify anything.
-- Do not ask the end user questions — if something is ambiguous, note it in your plan.
+- Do not ask the end user questions — if something is ambiguous, note it in your plan — **except conflicts (two requirements in conflict): send an upstream `ask` (notify_parent) at once, never defer it to the plan's delivery**.
 
 ## 报告义务
 - Before planning, use repo_outline to understand the project structure, doc_search for conventions and design docs, and code_search
@@ -24,4 +24,4 @@ Each step that encounters a risk must specify its fallback — not "handle error
 - Where a real design choice exists, call out the trade-offs and recommend ONE option with reasoning—don't list possibilities without taking a stance.
 - Stick to the task: the plan should solve the task, not redesign the codebase. Prefer modifying existing files over creating new ones—
 new files should only appear when the task genuinely demands a new module. List every file that will be modified, so the implementer knows the blast radius.
-- If something is ambiguous, note it in the plan; do not ask the user.
+- If something is ambiguous, note it in the plan; do not ask the user — **except conflicts (two requirements in conflict): send an upstream `ask` (notify_parent) at once, never defer it to the plan's delivery**.

package/session-gc.mjs

@@ -3,7 +3,9 @@
  *
  * F1 残留 GC（自动）：进程启动时对当前 cwd hash 前缀做一次轻量清理——.corrupted /
  * .unreadable / .manifest.corrupted / .bak-* 保留 30 天，孤儿 .tmp 保留 7 天
- *（mtime < now − retention 才删，等于保留期保留——older-than 边界语义）。
+ *（mtime < now − retention 才删，等于保留期保留——older-than 边界语义）；**孤儿 sidecar
+ * 记录目录 `.d`**（主文件 `{prefix}.{N}` 不存在）保留 30 天（数据现场族口径）⇒ **回收**
+ *（rename 进 `sessions-trash`——目录承载记录存储本体，不可直删；D-SE36 同语义）。
  * 安全（N1）：活跃槽（主文件在 + manifest slotSessions[N] 属主活）的现场一律保留；
  * manifest 主文件 / end marker / 数据主文件永不进入候选（后缀预过滤只匹配残留后缀）。
  *
@@ -35,6 +37,9 @@ import { configDir } from "./config.mjs"
 import { sessionPath, ownerPid } from "./session-slots.mjs"
 import { probeOwnersAsync, ownerState } from "./process-probe.mjs"
 import { listStaleCwds, deleteStaleCwd, recycleGroup, sweepStale, trashRootFor } from "./session-stale.mjs"
+// sidecar 记录目录后缀常量（单源 = `session-segments.mjs:13`——本档经该常量判后缀形态；
+// 两处名形匹配式（`classifyResidue` / `sweepOrphanRecordDirs`）按 `{prefix}.{N}` + 后缀内联，不构成第二单源）。
+import { RECORD_DIR_SUFFIX } from "./session-segments.mjs"
 
 /** 保留期（§6.12）：损坏现场（.corrupted/.unreadable/.manifest.corrupted）与并发轮转
  *  备份（.bak-*）30 天；孤儿 .tmp 7 天（崩溃现场恢复窗口）。 */
@@ -46,8 +51,9 @@ export const COLD_CWD_RETENTION_MS = 90 * 24 * 3600 * 1000
 function sessionsDir() { return join(configDir, "sessions") }
 
 /** 残留分类（§6.12 后缀表）：name 须以 `${prefix}.` 开头（prefix = `${hash}.json`）。
- *  返回 { retention, slot, tmp } 或 null（主文件/end marker/他前缀——不动）。
- *  slot = 关联槽号（`.N.` 段），无则 null（如 .manifest.corrupted）。 */
+ *  返回 { retention, slot, tmp, dir } 或 null（主文件/end marker/他前缀——不动）。
+ *  slot = 关联槽号（`.N.` 段），无则 null（如 .manifest.corrupted）；`dir` = sidecar 记录目录
+ *  形（`{prefix}.{N}.d`——孤儿判据反向：**主文件在 ⇒ 跳过**）。 */
 function classifyResidue(name, prefix) {
   if (!name.startsWith(prefix + ".")) return null
   const slotMatch = name.slice(prefix.length).match(/^\.(\d+)\./)
@@ -55,6 +61,7 @@ function classifyResidue(name, prefix) {
   if (name.endsWith(".corrupted") || name.endsWith(".unreadable")) return { retention: RESIDUE_RETENTION_MS, slot, tmp: false }
   if (/\.bak-\d+$/.test(name)) return { retention: RESIDUE_RETENTION_MS, slot, tmp: false }
   if (name.endsWith(".tmp")) return { retention: ORPHAN_TMP_RETENTION_MS, slot, tmp: true }
+  if (name.endsWith(RECORD_DIR_SUFFIX) && /\.\d+\.d$/.test(name)) return { retention: RESIDUE_RETENTION_MS, slot, tmp: false, dir: true }
   return null
 }
 
@@ -105,17 +112,60 @@ export async function gcResidue({ dir = sessionsDir(), prefix, now = Date.now(),
     if (c.slot !== null && active.has(c.slot)) continue // N1：活跃槽现场一律保留（T3）
     const p = join(dir, c.name)
     if (c.tmp && existsSync(p.slice(0, -".tmp".length))) continue // 非孤儿 .tmp（主文件在——写中/回退候选）
+    if (c.dir && existsSync(p.slice(0, -RECORD_DIR_SUFFIX.length))) continue // 非孤儿 sidecar（主文件在 ⇒ 记录存储本体——不动；仅孤儿目录入候选）
     let st
     try { st = await stat(p) } catch { continue }
     if (st.mtimeMs >= now - c.retention) continue // 边界：older-than 才删，等于保留期保留（§6.12）
     result.candidates.push(c.name)
-    if (!dryRun) {
-      try { await unlink(p); result.deleted.push(c.name) } catch { /* 占用/竞态——跳过 */ }
+    if (dryRun) continue
+    if (c.dir) {
+      // 目录承载记录存储本体 ⇒ **回收**（rename 进 `sessions-trash/<批次>/`——不 unlink / 不同步 fs；
+      // 失败 ⇒ 跳过并计数（candidates − deleted）+ 原目录零删除）
+      const r = await recycleGroup({ prefix, files: [c.name] }, { dir, now })
+      if (r.moved.length) result.deleted.push(c.name)
+      continue
     }
+    try { await unlink(p); result.deleted.push(c.name) } catch { /* 占用/竞态——跳过 */ }
   }
   return result
 }
 
+/** ② 显式面清运腿（§6.12 / §6.17 补充——存量通路）：全目录孤儿 sidecar 记录目录
+ *（`{prefix}.{N}.d`——主文件不存在 ∧ 该槽非活跃）⇒ 逐条**回收**（rename 进 `sessions-trash/<批次>/`，同 ① 语义）。
+ *  与 ① 两面之差：① = 自动面（单前缀 / 当前 cwd / **带 30 天保留期**——只治本前缀未来新增）；
+ *  本函数 = **用户显式面**（跳前缀遍历全目录 / **不设保留期**——存量孤儿跨多前缀且多为近期孤儿，
+ *  自动面望不到；进程入口 = `--dry-run` 先列 / `--confirm --all` 才动，且回收可回退）。
+ *  `dryRun` ⇒ 只列不删；目录不可读 ⇒ 空集。失败 ⇒ 跳过（不 unlink 兜底——原目录零删除）。 */
+export async function sweepOrphanRecordDirs({ dir = sessionsDir(), now = Date.now(), dryRun = false, probeFn = probeOwnersAsync, entries = null } = {}) {
+  const out = { candidates: [], recycled: [] }
+  let names = entries
+  if (!names) {
+    try { names = await readdir(dir) } catch { return out }
+  }
+  const present = new Set(names)
+  const byPrefix = new Map() // prefix → [{ name, slot }]
+  for (const name of names) {
+    const m = /^(.+\.json)\.(\d+)\.d$/.exec(name)
+    if (!m) continue
+    if (present.has(`${m[1]}.${m[2]}`)) continue // 主文件在 ⇒ 非孤儿（记录存储本体——不动）
+    if (!byPrefix.has(m[1])) byPrefix.set(m[1], [])
+    byPrefix.get(m[1]).push({ name, slot: Number(m[2]) })
+  }
+  for (const [prefix, items] of byPrefix) {
+    const active = await liveSlots(dir, prefix, probeFn) // N1：活跃槽现场一律保留
+    for (const it of items) {
+      if (active.has(it.slot)) continue
+      let st
+      try { st = await stat(join(dir, it.name)) } catch { continue }
+      if (st) out.candidates.push(it.name)
+      if (dryRun) continue
+      const r = await recycleGroup({ prefix, files: [it.name] }, { dir, now })
+      if (r.moved.length) out.recycled.push(it.name)
+    }
+  }
+  return out
+}
+
 /** 启动**窗外延迟拍** pass（§6.17 编排——点火见 `scheduleSessionGC`）：① 一次**异步目录快照**
  *  （readdir 恰一次——两面共享）② 残留面（gcResidue 既有判据）③ 存量面（总评估有界
  *  ≤ STALE_SWEEP_LIMIT（含 ① 面 manifest 读——D-SE40）+ 超期回收批清运）。
@@ -265,6 +315,10 @@ export async function runSessionGc(args, { dir = sessionsDir(), prefix = null, c
     const residue = p ? await gcResidue({ dir, prefix: p, now, dryRun: true, probeFn }) : { candidates: [] }
     out(`Residue candidates for current project (${p ?? "unknown"}): ${residue.candidates.length}`)
     for (const name of residue.candidates) out(`  ${name}`)
+    // 孤儿 sidecar 记录目录（② 存量面——全目录；主文件不在 + 该槽非活跃——不设保留期）
+    const orphanDirs = await sweepOrphanRecordDirs({ dir, now, dryRun: true, probeFn })
+    out(`Orphan record-dir (.d) candidates (main file gone; explicit face — no retention): ${orphanDirs.candidates.length}`)
+    for (const name of orphanDirs.candidates) out(`  ${name}`)
     out(`Cold/stale project candidates (cold = manifest idle > 90 days; stale = no live owner + cwd unreachable/empty + 7-day window): ${candidates.length}`)
     for (const c of candidates) out(`  ${c.hash}  reason ${c.reason}  files ${c.files.length}`)
     if (candidates.length >= GC_PROGRESS_MIN) out(`Estimate: ${fmtGcEstimate(candidates.length)} to scan ${candidates.length} candidates (measured ≈${GC_MS_PER_CANDIDATE}ms/candidate).`)
@@ -279,7 +333,9 @@ export async function runSessionGc(args, { dir = sessionsDir(), prefix = null, c
     try { loopEntries = await readdir(dir) } catch { loopEntries = null }
   }
   const targets = confirmTarget === "--all" ? candidates : candidates.filter((c) => c.hash === confirmTarget)
-  if (!targets.length) {
+  // ② 面候选预列（孤儿 sidecar 记录目录——存量通路；只列不删——实回收在组循环后）
+  const orphanDirs = confirmTarget === "--all" ? await sweepOrphanRecordDirs({ dir, now, dryRun: true, probeFn, entries: loopEntries }) : { candidates: [] }
+  if (!targets.length && !orphanDirs.candidates.length) {
     err(`Refused: ${confirmTarget} is not a cold/stale project (active, recent, or unknown) — nothing deleted.`)
     return 1
   }
@@ -299,5 +355,10 @@ export async function runSessionGc(args, { dir = sessionsDir(), prefix = null, c
     }
     out(`Moved ${r.deleted.length} files for ${t.hash} into the recycle bin (${r.batch})${r.skipped?.length ? ` — skipped ${r.skipped.length} (locked/racing, kept in place)` : ""}.`)
   }
+  // ② 显式面清运腿（孤儿 sidecar 记录目录——存量通路；与 ① 同语义：rename 进回收批）
+  if (confirmTarget === "--all" && orphanDirs.candidates.length) {
+    const moved = await sweepOrphanRecordDirs({ dir, now, probeFn, entries: loopEntries })
+    out(`Orphan record dirs (.d): moved ${moved.recycled.length}/${moved.candidates.length} into the recycle bin (${trashRootFor(dir)}).`)
+  }
   return 0
 }

package/session-slots-manifest.mjs

@@ -289,6 +289,10 @@ export function claimSlot(cwd, slot, m = loadManifest(cwd), deadParam = null) {
   saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true, release: [slot] })
 }
 
+/** 观测计数（测试缝——`_storeStats` / `_staleHooks` 同惯例）：`releaseClaimsAll` 调用计数。
+ *  端壳「工作区转空 ⇒ 旧 cwd 释放恰一次」类断言以此为桩计数（生产零消费）。 */
+export const _releaseStats = { calls: 0 }
+
 /** 退出全释放（EXIT-CLAIM-RELEASE 批 · F-XR1 · SESSION.md §6.18 D-SE41）：优雅退出前释放
  *  本进程**全部**槽认领（保留集空——`staleClaims` 释放谓词单源）；落盘判据 = `saveManifest`
  *  `opts.release` 三条自动继承（fresh 同次快照取释放集 / 值条件删除——他人窗口内新认领不误删 /
@@ -299,6 +303,7 @@ export function claimSlot(cwd, slot, m = loadManifest(cwd), deadParam = null) {
  *  （true = 有释放且落盘成功；false = 早退 / 失败——断言面）；写失败盘面 = 认领残留 →
  *  恢复走既有探测面（现状形态，数据零险）。 */
 export function releaseClaimsAll(cwd) {
+  _releaseStats.calls += 1
   try {
     if (!existsSync(manifestPath(cwd))) return false // 无 manifest ⇒ 零写（不造盘面）
     const m = loadManifest(cwd)

package/tool-docs/question.md

@@ -13,4 +13,5 @@ Notes:
 - Ask ONE question per call — never bundle multiple sub-questions into one question string; ask the next one after the answer arrives.
 - Keep the question text short — one or two sentences. Background, context, and analysis belong in your normal reply text, NOT in the question.
 - Routine confirmations (confirm gates) belong in your plain reply text — the user answers in their next message. Use this tool ONLY when you need the user's decision or input to proceed.
+- Ask here when no default can carry the work forward (new scope, a ruling on a criterion) — this blocks; when a reasonable default exists, ask in your ordinary reply text and keep going — a reply arriving while you work steers the work from there.
 - After receiving an answer about a design convention, tool preference, or recurring pattern: save it with the memory tool (action: put). This prevents asking the same question in future sessions — the user shouldn't have to repeat their preferences.

package/tools/edit-batch.mjs

@@ -19,17 +19,16 @@ import { writeThroughPath } from "./write-path.mjs"
 // EDIT.md §6：批量条目判定+应用共用 edit-diff（EDIT.md §4 分支 0 单行替换 + 行级 LCS——零重叠→替换即删）；
 // EDIT.md §5：edits 互斥错误文本随前置校验分支迁出至 edit-diff.mjs。
 // #69：回执组装共用 edit-diff 的 composeEditReceipt（回执形态按端注入——缺省 = CLI 形态）。
-import { assertEditArgsExclusive, validateEditEntry, computeEditEntry, splitLines, EMPTY_NEW_STRING_LINE, deleteTarget, composeEditReceipt } from "./edit-diff.mjs"
+import { assertEditArgsExclusive, assertEditsContainer, assertEditEntries, validateEditEntry, computeEditEntry, splitLines, EMPTY_NEW_STRING_LINE, EDIT_ENTRY_NO_PATH, EDIT_ABORT_PREFIX, editEntryLabel, deleteTarget, composeEditReceipt } from "./edit-diff.mjs"
 
 /**
  * Apply the `edits` array form: multi-file atomic replacement. Throws on any
  * failure (atomic — nothing written). Returns the per-entry result text (joined).
  */
 export async function applyEditBatch(args, ctx) {
-  if (!Array.isArray(args.edits) || args.edits.length === 0) {
-    throw new Error("edits must be a non-empty array of {path, old_string | line/startLine+endLine, new_string}")
-  }
+  assertEditsContainer(args.edits)
   assertEditArgsExclusive(args)
+  assertEditEntries(args.edits) // #325 条目预扫（非对象条目 ⇒ 含下标成形错误；不读盘）
   // 原子：先全量检查（所有文件的替换都可执行）——任一失败全不写。
   // 2026-09-01 缺陷修复（TOOLS.md §9 ②"同文件多条规则"）：同一 path 的多条编辑
   // 按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的累积内容做匹配与替换
@@ -40,9 +39,9 @@ export async function applyEditBatch(args, ctx) {
     // 2026-09-05 用户裁定：顶层 path + edits 并存合法化——`e.path || args.path`（条目优先；
     // 缺省入口仅在此兜底）；两者皆无 → 原错误文本（措辞补顶层选项）。
     const p = e.path || args.path
-    if (!p) throw new Error("each edit must have a path — give each entry its own path or pass a top-level path")
+    if (!p) throw new Error(EDIT_ENTRY_NO_PATH)
     // 前置校验（空 old / 非字符串 new——文本同 edit-diff 批量形态；读盘前校验）
-    validateEditEntry(e, { label: `edit for ${p}: `, rich: false })
+    validateEditEntry(e, { label: editEntryLabel(p), rich: false })
     const abs = resolveInCwd(ctx, p)
     let g = groups.get(abs)
     if (!g) {
@@ -61,7 +60,7 @@ export async function applyEditBatch(args, ctx) {
       const out = computeEditEntry(g.content, e, {
         path: g.path,
         absPath: g.abs,
-        abortPrefix: "edit aborted (atomic — no files written): ",
+        abortPrefix: EDIT_ABORT_PREFIX,
       })
       prepared.push({
         g,