@thincoder/core 0.9.4 → 0.10.1

package/process-probe-exec.mjs

@@ -0,0 +1,187 @@
+/**
+ * process-probe-exec.mjs — 探测执行面（#590① 自 `process-probe.mjs` 外提——CORE-UNIFICATION
+ * 行 10 预案兑现；语义逐字零变）。
+ *
+ * 归本档：双超时常量（`ALIVE_EXEC_TIMEOUT_MS` / `CMDLINE_EXEC_TIMEOUT_MS`）· 模块级测试注入缝
+ * （`_testImpl` + 两 setter——唯一读取点 = 本档四批量函数，同档免回引 / 免环）· `uniqPids` ·
+ * 输出解析族 · `execFileP` · 四批量探测函数（`batchAlive` / `batchAliveAsync` / `probeCmdlines` /
+ * `probeCmdlinesAsync`）。
+ * 留 `process-probe.mjs`：身份判据 · 三态判据 · 束 API · 单 pid 兼容面 · 清理面适配——该档对
+ * 四批量名与缝名 **import + re-export**（导入面逐字零改；`isProcessAlive` 经 import 取用本档
+ * `parseTasklistPids`，并自持 `execFileSync` import——win32 分支直调，不设转口）。
+ *
+ * 成本纪律与两形态语义（同步 / 异步共用同一解析族与同一注入缝）= `process-probe.mjs` 头注
+ * （单源——本档不重述）。
+ */
+import { execFile, execFileSync } from "node:child_process"
+
+const ALIVE_EXEC_TIMEOUT_MS = 10_000
+const CMDLINE_EXEC_TIMEOUT_MS = 15_000
+
+// 模块级测试注入缝（default null = 生产实现；测试注入 + finally 恢复——见测试文件）
+let _testImpl = null
+
+/** 注入测试实现。aliveFn(pids) → Set<pid>|null；cmdlineFn(pids) → Map<pid,cmdline>|null
+ *  （两缝均**批量**语义——一次调用拿全量）。返回前值便于测试保存恢复；**未传的槽置 null**（传 `{}` = 两槽同清，等价 reset）。 */
+export function _setProcessProbeTestImpl({ aliveFn = undefined, cmdlineFn = undefined } = {}) {
+  const prev = _testImpl
+  _testImpl = { aliveFn: aliveFn ?? null, cmdlineFn: cmdlineFn ?? null }
+  return prev
+}
+
+export function _resetProcessProbeTestImpl() {
+  _testImpl = null
+}
+
+/** pid 清单归一：去重 + 正整数（两探测共用——空清单调用面零 exec）。 */
+export function uniqPids(pids) {
+  return [...new Set(pids.map(Number).filter((n) => Number.isInteger(n) && n > 0))]
+}
+
+// ── 输出解析族（同步 / 异步两形态**共用**——单源，防两形态漂移） ─────────────────
+/** Windows tasklist CSV（`"name","pid"…`）→ 全量 PID 集合。 */
+export function parseTasklistPids(out) {
+  const alive = new Set()
+  for (const line of out.split(/\r?\n/)) {
+    const m = line.match(/^"([^"]*)","(\d+)"/)
+    if (m) alive.add(Number(m[2]))
+  }
+  return alive
+}
+
+/** Unix `ps -eo pid=` → 全量 PID 集合。 */
+function parsePsPids(out) {
+  return new Set(out.split(/\r?\n/).map((l) => Number(l.trim())).filter((n) => Number.isInteger(n)))
+}
+
+/** Windows `Get-CimInstance … ConvertTo-Json` → `Map<pid, cmdline>`。 */
+function parseCimCmdlines(out) {
+  const rows = JSON.parse(out.trim())
+  const map = new Map()
+  for (const r of Array.isArray(rows) ? rows : [rows]) {
+    if (r && Number.isInteger(r.ProcessId) && typeof r.CommandLine === "string") {
+      map.set(Number(r.ProcessId), r.CommandLine)
+    }
+  }
+  return map
+}
+
+/** Unix `ps -eo pid=,args=` → `Map<pid, cmdline>`。 */
+function parsePsArgs(out) {
+  const map = new Map()
+  for (const line of out.split(/\r?\n/)) {
+    const m = line.match(/^\s*(\d+)\s+(.*)$/)
+    if (m) map.set(Number(m[1]), m[2])
+  }
+  return map
+}
+
+/** execFile → Promise<string>（stdout；exec / 超时失败 ⇒ reject——调用面按「探测失败」降级）。 */
+function execFileP(cmd, args, timeout) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { encoding: "utf8", timeout, windowsHide: true }, (err, stdout) => {
+      if (err) reject(err); else resolve(stdout)
+    })
+  })
+}
+
+/**
+ * 批量判活：单次 tasklist（Windows 全量 CSV）/ ps（Unix）拿全量 PID 集合 → 一次 exec
+ * 比对（修复 isProcessAlive 每 pid 一次 execSync 的成本——每回合 N 次 = 贵，探索 §4）。
+ * 返回存活 pid 的 Set；exec/解析失败 → null（调用方区分"探测失败"与"全死"——只读面按
+ * 无活伴降级；域面（peer-domains 死清理）在 null 时不得执行删除——探测失败 ≠ 死）。
+ * **纯存在性**：身份判据不在此层（D-MI11——过滤落点在读面 `peerInstances()` 与清理面
+ * `filterDeadOwners`；`peer-domains.mjs` 的域残留清理语义保持零变）。
+ */
+export function batchAlive(pids, { timeoutMs = ALIVE_EXEC_TIMEOUT_MS } = {}) {
+  const uniq = uniqPids(pids)
+  if (uniq.length === 0) return new Set()
+  if (_testImpl?.aliveFn) return _testImpl.aliveFn(uniq)
+  try {
+    if (process.platform === "win32") {
+      const output = execFileSync("tasklist", ["/FO", "CSV", "/NH"], {
+        encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"],
+      })
+      const alive = parseTasklistPids(output)
+      return new Set(uniq.filter((pid) => alive.has(pid)))
+    }
+    const output = execFileSync("ps", ["-eo", "pid="], {
+      encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"],
+    })
+    const alive = parsePsPids(output)
+    return new Set(uniq.filter((pid) => alive.has(pid)))
+  } catch {
+    return null // 探测失败（区别于全死）——调用方不得据此执行删除/判死副作用
+  }
+}
+
+/**
+ * 异步对偶（TUI 假死批 · MULTI-INSTANCE-COLLAB §3.1）：与 `batchAlive` 同语义（返回集 / null
+ * 降级一致），但 `execFile` + Promise 化——**读面**（每回合的 `peerInstances`）不得用同步 exec
+ * 占住事件循环。**同一注入缝** `_setProcessProbeTestImpl`（注入值可能是同步函数——经 await
+ * 消费）；**清理面继续用同步版**（会话起点 / 认领路径，非每回合面——D-MI14 登记）。
+ */
+export async function batchAliveAsync(pids) {
+  const uniq = uniqPids(pids)
+  if (uniq.length === 0) return new Set()
+  if (_testImpl?.aliveFn) return _testImpl.aliveFn(uniq)
+  try {
+    if (process.platform === "win32") {
+      const alive = parseTasklistPids(await execFileP("tasklist", ["/FO", "CSV", "/NH"], ALIVE_EXEC_TIMEOUT_MS))
+      return new Set(uniq.filter((pid) => alive.has(pid)))
+    }
+    const alive = parsePsPids(await execFileP("ps", ["-eo", "pid="], ALIVE_EXEC_TIMEOUT_MS))
+    return new Set(uniq.filter((pid) => alive.has(pid)))
+  } catch {
+    return null // 探测失败（区别于全死）——只读面按「无活伴」降级
+  }
+}
+
+/**
+ * 批量 cmdline 探测（决策③ A——一次 exec 拿全部 pid+cmdline）：返回 Map<pid, cmdline>
+ * 或 null（exec 失败/解析失败）。Windows = 一次 Get-CimInstance（PowerShell）；Unix =
+ * 一次 ps。仅在 manifest mtime 变化后跑一次（~百 ms 级——设计已接受）；清理面同一批量
+ * 结果逐条消费（D-MI3 / N-MI3——不做每 pid 一次 exec）。
+ */
+export function probeCmdlines(pids, { timeoutMs = CMDLINE_EXEC_TIMEOUT_MS } = {}) {
+  const uniq = uniqPids(pids)
+  if (uniq.length === 0) return new Map()
+  if (_testImpl?.cmdlineFn) return _testImpl.cmdlineFn(uniq)
+  try {
+    let out
+    if (process.platform === "win32") {
+      // 一次 Get-CimInstance 拿全表 → node 侧过滤目标 pid（避免 shell 引号注入面）
+      out = execFileSync("powershell.exe",
+        ["-NoProfile", "-NonInteractive", "-Command",
+          "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress"],
+        { encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"] })
+      return parseCimCmdlines(out)
+    }
+    out = execFileSync("ps", ["-eo", "pid=,args="], {
+      encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"],
+    })
+    return parsePsArgs(out)
+  } catch {
+    return null // 探测失败 → 端字段/身份缺省（调用方降级：保守保留）
+  }
+}
+
+/** 异步对偶（同 `probeCmdlines` 语义——`execFile` + Promise；同一注入缝；读面在用）。 */
+export async function probeCmdlinesAsync(pids) {
+  const uniq = uniqPids(pids)
+  if (uniq.length === 0) return new Map()
+  if (_testImpl?.cmdlineFn) return _testImpl.cmdlineFn(uniq)
+  try {
+    if (process.platform === "win32") {
+      const out = await execFileP("powershell.exe",
+        ["-NoProfile", "-NonInteractive", "-Command",
+          "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress"],
+        CMDLINE_EXEC_TIMEOUT_MS)
+      return parseCimCmdlines(out)
+    }
+    const out = await execFileP("ps", ["-eo", "pid=,args="], CMDLINE_EXEC_TIMEOUT_MS)
+    return parsePsArgs(out)
+  } catch {
+    return null // 探测失败 → 端字段/身份缺省（调用方降级：保守保留）
+  }
+}

package/process-probe.mjs

@@ -20,11 +20,17 @@
  * 2 s + 三态）。`filterDeadOwners` = `ownerState` 薄适配（`alive` 三态，缺省 = 未知）。
  * 方向不对称（D-MI10）：探测失败（null）/ 该 pid 缺行 ⇒ **保守保留/不删**——误保留 = 噪音，
  * 误删活实例 = 破坏存储隔离（双进程同槽），两者代价不同级。
+ *
+ * 执行面拆分（#590① · CORE-UNIFICATION 行 10 兑现）：注入缝 + 解析族 + 四批量探测函数
+ * （`batchAlive` / `batchAliveAsync` / `probeCmdlines` / `probeCmdlinesAsync`）+ `uniqPids`
+ * 住拆分件 `process-probe-exec.mjs`（迁移账 = 该档头注）；本档 import 自用 + re-export
+ * 保导入面逐字零改（VSC `session-io.mjs` 与核七消费档不动）。
  */
-import { execFile, execFileSync } from "node:child_process"
-
-const ALIVE_EXEC_TIMEOUT_MS = 10_000
-const CMDLINE_EXEC_TIMEOUT_MS = 15_000
+import { execFileSync } from "node:child_process"
+import {
+  batchAlive, batchAliveAsync, probeCmdlines, probeCmdlinesAsync,
+  uniqPids, parseTasklistPids,
+} from "./process-probe-exec.mjs"
 
 /** 同步束的**紧界**（F-MI7 · SESSION.md §6.2）：同步探测阻塞事件循环 ⇒ 单次 exec ≤ 2 s；
  *  超时 / 失败 ⇒ 未知（三态判据）⇒ 保守保留（D-MI10）。单源常量——调用面不得自行取值。 */
@@ -40,187 +46,30 @@ const VSC_END_RE = /--extensionDevelopmentPath|--type=extensionHost|extensionHos
  *  「误删方向」——消解路径 = 实测出现时补进本族，单源改点仅此一处）。 */
 const CLI_ENTRY_RE = /thincoder\.cjs|thincoder\.mjs|thincoder-cli/i
 
-// 模块级测试注入缝（default null = 生产实现；测试注入 + finally 恢复——见测试文件）
-let _testImpl = null
-
-/** 注入测试实现。aliveFn(pids) → Set<pid>|null；cmdlineFn(pids) → Map<pid,cmdline>|null
- *  （两缝均**批量**语义——一次调用拿全量）。返回前值便于测试保存恢复；**未传的槽置 null**（传 `{}` = 两槽同清，等价 reset）。 */
-export function _setProcessProbeTestImpl({ aliveFn = undefined, cmdlineFn = undefined } = {}) {
-  const prev = _testImpl
-  _testImpl = { aliveFn: aliveFn ?? null, cmdlineFn: cmdlineFn ?? null }
-  return prev
-}
-
-export function _resetProcessProbeTestImpl() {
-  _testImpl = null
-}
-
-/** pid 清单归一：去重 + 正整数（两探测共用——空清单调用面零 exec）。 */
-function uniqPids(pids) {
-  return [...new Set(pids.map(Number).filter((n) => Number.isInteger(n) && n > 0))]
-}
-
-// ── 输出解析族（同步 / 异步两形态**共用**——单源，防两形态漂移） ─────────────────
-/** Windows tasklist CSV（`"name","pid"…`）→ 全量 PID 集合。 */
-function parseTasklistPids(out) {
-  const alive = new Set()
-  for (const line of out.split(/\r?\n/)) {
-    const m = line.match(/^"([^"]*)","(\d+)"/)
-    if (m) alive.add(Number(m[2]))
-  }
-  return alive
-}
-
-/** Unix `ps -eo pid=` → 全量 PID 集合。 */
-function parsePsPids(out) {
-  return new Set(out.split(/\r?\n/).map((l) => Number(l.trim())).filter((n) => Number.isInteger(n)))
-}
-
-/** Windows `Get-CimInstance … ConvertTo-Json` → `Map<pid, cmdline>`。 */
-function parseCimCmdlines(out) {
-  const rows = JSON.parse(out.trim())
-  const map = new Map()
-  for (const r of Array.isArray(rows) ? rows : [rows]) {
-    if (r && Number.isInteger(r.ProcessId) && typeof r.CommandLine === "string") {
-      map.set(Number(r.ProcessId), r.CommandLine)
-    }
-  }
-  return map
-}
-
-/** Unix `ps -eo pid=,args=` → `Map<pid, cmdline>`。 */
-function parsePsArgs(out) {
-  const map = new Map()
-  for (const line of out.split(/\r?\n/)) {
-    const m = line.match(/^\s*(\d+)\s+(.*)$/)
-    if (m) map.set(Number(m[1]), m[2])
-  }
-  return map
-}
-
-/** execFile → Promise<string>（stdout；exec / 超时失败 ⇒ reject——调用面按「探测失败」降级）。 */
-function execFileP(cmd, args, timeout) {
-  return new Promise((resolve, reject) => {
-    execFile(cmd, args, { encoding: "utf8", timeout, windowsHide: true }, (err, stdout) => {
-      if (err) reject(err); else resolve(stdout)
-    })
-  })
-}
-
-/**
- * 批量判活：单次 tasklist（Windows 全量 CSV）/ ps（Unix）拿全量 PID 集合 → 一次 exec
- * 比对（修复 isProcessAlive 每 pid 一次 execSync 的成本——每回合 N 次 = 贵，探索 §4）。
- * 返回存活 pid 的 Set；exec/解析失败 → null（调用方区分"探测失败"与"全死"——只读面按
- * 无活伴降级；域面（peer-domains 死清理）在 null 时不得执行删除——探测失败 ≠ 死）。
- * **纯存在性**：身份判据不在此层（D-MI11——过滤落点在读面 `peerInstances()` 与清理面
- * `filterDeadOwners`；`peer-domains.mjs` 的域残留清理语义保持零变）。
- */
-export function batchAlive(pids, { timeoutMs = ALIVE_EXEC_TIMEOUT_MS } = {}) {
-  const uniq = uniqPids(pids)
-  if (uniq.length === 0) return new Set()
-  if (_testImpl?.aliveFn) return _testImpl.aliveFn(uniq)
-  try {
-    if (process.platform === "win32") {
-      const output = execFileSync("tasklist", ["/FO", "CSV", "/NH"], {
-        encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"],
-      })
-      const alive = parseTasklistPids(output)
-      return new Set(uniq.filter((pid) => alive.has(pid)))
-    }
-    const output = execFileSync("ps", ["-eo", "pid="], {
-      encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"],
-    })
-    const alive = parsePsPids(output)
-    return new Set(uniq.filter((pid) => alive.has(pid)))
-  } catch {
-    return null // 探测失败（区别于全死）——调用方不得据此执行删除/判死副作用
-  }
-}
-
-/**
- * 异步对偶（TUI 假死批 · MULTI-INSTANCE-COLLAB §3.1）：与 `batchAlive` 同语义（返回集 / null
- * 降级一致），但 `execFile` + Promise 化——**读面**（每回合的 `peerInstances`）不得用同步 exec
- * 占住事件循环。**同一注入缝** `_setProcessProbeTestImpl`（注入值可能是同步函数——经 await
- * 消费）；**清理面继续用同步版**（会话起点 / 认领路径，非每回合面——D-MI14 登记）。
- */
-export async function batchAliveAsync(pids) {
-  const uniq = uniqPids(pids)
-  if (uniq.length === 0) return new Set()
-  if (_testImpl?.aliveFn) return _testImpl.aliveFn(uniq)
-  try {
-    if (process.platform === "win32") {
-      const alive = parseTasklistPids(await execFileP("tasklist", ["/FO", "CSV", "/NH"], ALIVE_EXEC_TIMEOUT_MS))
-      return new Set(uniq.filter((pid) => alive.has(pid)))
-    }
-    const alive = parsePsPids(await execFileP("ps", ["-eo", "pid="], ALIVE_EXEC_TIMEOUT_MS))
-    return new Set(uniq.filter((pid) => alive.has(pid)))
-  } catch {
-    return null // 探测失败（区别于全死）——只读面按「无活伴」降级
-  }
-}
+/** 桌面端（Electron 主进程）判别标记族（台账 #584 实读定形——`electron .` 启动形态）：真机捕获
+ *  命令行 = `"…\thincoder-desktop\node_modules\electron\dist\electron.exe" .`——产品树路径段可判
+ *  （打包件 exe 名同族）。补入本族 = §3.1「标记族假阴性」已知局限的实测消解路径（原族外形态）。
+ *  #707 扩（2026-09-30 实测 · 台账 #707）：桌面 dev 启动形 = `node_modules\electron\dist\electron.exe
+ *  --remote-debugging-port=9222 --remote-allow-origins=* .`（**相对路径**，无 `thincoder-desktop` 段）
+ *  ⇒ 原族假阴性（活属主判 dead——误删方向）⇒ 补 `node_modules[\\/]electron[\\/]dist[\\/]` 段；
+ *  超集面（他 electron dev 应用）与 VSC 宿主族同向——宁可多留（误保留=噪音／误删=双进程同槽破坏级）。 */
+const DESKTOP_END_RE = /thincoder-desktop|node_modules[\\/]electron[\\/]dist[\\/]/i
 
-/**
- * 批量 cmdline 探测（决策③ A——一次 exec 拿全部 pid+cmdline）：返回 Map<pid, cmdline>
- * 或 null（exec 失败/解析失败）。Windows = 一次 Get-CimInstance（PowerShell）；Unix =
- * 一次 ps。仅在 manifest mtime 变化后跑一次（~百 ms 级——设计已接受）；清理面同一批量
- * 结果逐条消费（D-MI3 / N-MI3——不做每 pid 一次 exec）。
- */
-export function probeCmdlines(pids, { timeoutMs = CMDLINE_EXEC_TIMEOUT_MS } = {}) {
-  const uniq = uniqPids(pids)
-  if (uniq.length === 0) return new Map()
-  if (_testImpl?.cmdlineFn) return _testImpl.cmdlineFn(uniq)
-  try {
-    let out
-    if (process.platform === "win32") {
-      // 一次 Get-CimInstance 拿全表 → node 侧过滤目标 pid（避免 shell 引号注入面）
-      out = execFileSync("powershell.exe",
-        ["-NoProfile", "-NonInteractive", "-Command",
-          "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress"],
-        { encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"] })
-      return parseCimCmdlines(out)
-    }
-    out = execFileSync("ps", ["-eo", "pid=,args="], {
-      encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"],
-    })
-    return parsePsArgs(out)
-  } catch {
-    return null // 探测失败 → 端字段/身份缺省（调用方降级：保守保留）
-  }
-}
-
-/** 异步对偶（同 `probeCmdlines` 语义——`execFile` + Promise；同一注入缝；读面在用）。 */
-export async function probeCmdlinesAsync(pids) {
-  const uniq = uniqPids(pids)
-  if (uniq.length === 0) return new Map()
-  if (_testImpl?.cmdlineFn) return _testImpl.cmdlineFn(uniq)
-  try {
-    if (process.platform === "win32") {
-      const out = await execFileP("powershell.exe",
-        ["-NoProfile", "-NonInteractive", "-Command",
-          "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress"],
-        CMDLINE_EXEC_TIMEOUT_MS)
-      return parseCimCmdlines(out)
-    }
-    const out = await execFileP("ps", ["-eo", "pid=,args="], CMDLINE_EXEC_TIMEOUT_MS)
-    return parsePsArgs(out)
-  } catch {
-    return null // 探测失败 → 端字段/身份缺省（调用方降级：保守保留）
-  }
-}
-
-/** 本产品身份判据（单源）：命令行命中 CLI 入口族或 VSC 扩展宿主族 ⇒ 本产品进程。
+/** 本产品身份判据（单源）：命令行命中 CLI 入口族 ∕ VSC 扩展宿主族 ∕ 桌面端族 ⇒ 本产品进程。
  *  命令未知（undefined / 空串）⇒ `false`——**调用方须自行区分「未知」与「明确不符」**
  *  （未知 = 保守保留，明确不符 = 剔除/可删；两态判据见 `filterDeadOwners` 与读面落点）。 */
 export function isProductProc(cmdline) {
   if (typeof cmdline !== "string" || cmdline.length === 0) return false
-  return CLI_ENTRY_RE.test(cmdline) || VSC_END_RE.test(cmdline)
+  return CLI_ENTRY_RE.test(cmdline) || VSC_END_RE.test(cmdline) || DESKTOP_END_RE.test(cmdline)
 }
 
-/** cmdline → 端标签：扩展宿主标记 → vscode；其余（node/thincoder CLI）→ cli。
+/** cmdline → 端标签：扩展宿主标记 → vscode；桌面端族 → desktop；其余（node/thincoder CLI）→ cli。
  *  命令不可得（探测失败 / 缺行）⇒ `undefined`（端字段缺省——既有降级语义）。 */
 export function classifyEnd(cmdline) {
   if (typeof cmdline !== "string" || cmdline.length === 0) return undefined
-  return VSC_END_RE.test(cmdline) ? "vscode" : "cli"
+  if (VSC_END_RE.test(cmdline)) return "vscode"
+  if (DESKTOP_END_RE.test(cmdline)) return "desktop"
+  return "cli"
 }
 
 /**
@@ -313,3 +162,6 @@ export function filterDeadOwners(pid, { alive = undefined, cmdline = undefined }
   const cmds = typeof cmdline === "string" && cmdline.length > 0 ? new Map([[n, cmdline]]) : null
   return ownerState(n, { aliveSet, cmds }) === "dead"
 }
+
+// ── 执行面 re-export（拆分件接口——导入面逐字零改：#590①） ──
+export { batchAlive, batchAliveAsync, probeCmdlines, probeCmdlinesAsync, _setProcessProbeTestImpl, _resetProcessProbeTestImpl } from "./process-probe-exec.mjs"

package/prompt-overlays.mjs

@@ -3,9 +3,9 @@
  * 施工② G1+G2, 2026-09-10). Slot constants are loaded ONCE (byte-stable, module scope);
  * assemblePrompt composes them per PROMPT-SYSTEM.md §3.2 装配矩阵 (D1 内联表——设计锚).
  *
- * Slot model (PROMPT-SYSTEM.md §1/§2): persona → common → discipline → [4] other
- * (AGENTS/skills ride the existing tail logic). explore/coder/plan reuse PERSONA_NORMAL
- * as their persona slot (蓝图 §3.1 同槽位复用——变体差异归人格层覆写; design D1 G1 note).
+ * Slot model (PROMPT-SYSTEM.md §1/§2): persona → common → discipline → [4] subagent-base
+ * (AGENTS/skills ride the existing tail logic — tail block, no numbered slot). explore/coder/plan
+ * reuse PERSONA_NORMAL as their persona slot (蓝图 §3.1 同槽位复用——变体差异归人格层覆写; design D1 G1 note).
  */
 
 import { loadSlot, applyPromptInjections } from "./prompt-files.mjs"
@@ -22,6 +22,7 @@ const SLOT_CONTENTS = {
   "common.md": loadSlot("common.md"),
   "discipline-engineering.md": loadSlot("discipline-engineering.md"),
   "discipline-normal.md": loadSlot("discipline-normal.md"),
+  "subagent-base.md": loadSlot("subagent-base.md"),
 }
 
 // ── G1 六件导出（评审 #1 计数口径：人格 2 + 公共 1 + 纪律 2 + consult 自含基底；
@@ -40,11 +41,11 @@ export const CONSULT_BASE = loadSlot("consult-base.md")
 export const SCENARIO_SLOT_FILES = {
   engineering: ["persona-engineering.md", "common.md", "discipline-engineering.md"],
   normal: ["persona-normal.md", "common.md", "discipline-normal.md"],
-  "eng-coder": ["persona-eng-coder.md", "common.md", "discipline-engineering.md"],
-  "eng-designer": ["persona-eng-designer.md", "common.md", "discipline-engineering.md"],
-  explore: ["persona-explore.md", "common.md", "discipline-normal.md"],
-  coder: ["persona-coder.md", "common.md", "discipline-normal.md"],
-  plan: ["persona-plan.md", "common.md", "discipline-normal.md"],
+  "eng-coder": ["persona-eng-coder.md", "common.md", "discipline-engineering.md", "subagent-base.md"],
+  "eng-designer": ["persona-eng-designer.md", "common.md", "discipline-engineering.md", "subagent-base.md"],
+  explore: ["persona-explore.md", "common.md", "discipline-normal.md", "subagent-base.md"],
+  coder: ["persona-coder.md", "common.md", "discipline-normal.md", "subagent-base.md"],
+  plan: ["persona-plan.md", "common.md", "discipline-normal.md", "subagent-base.md"],
   consult: null, // §3.3 特殊模块——consult-base.md 自含基底，不入主装配链（CONSULT_BASE 直出）
 }
 
@@ -55,8 +56,8 @@ export function slotWarning(fileName) {
 
 /**
  * G2: the single prompt-assembly function — table-driven (D1), fixed order
- * persona → common → discipline (§3.1 四槽位固定序；[4] AGENTS/skills 由既有尾部
- * 逻辑承担). A missing slot file is SKIPPED with a prominent warning (蓝图 §3.4 降级链);
+ * persona → common → discipline → [4] subagent-base (§3.1 四槽位固定序；AGENTS/skills
+ * 由既有尾部逻辑承担——槽位外尾块，无编号). A missing slot file is SKIPPED with a prominent warning (蓝图 §3.4 降级链);
  * AGENTS.md missing = silent skip in the caller's existing tail logic. Byte-stable
  * per scenario (D3): fixed slot contents + fixed order — no timestamps here.
  *

package/prompts/advisor-design.md

@@ -1,5 +1,5 @@
 <!-- slot:special-advisor-design consumers:[advisor(type='design') injection — self-contained, NOT part of the main assembly chain] -->
-You are an independent design reviewer for an engineering-mode project. ## Your role (identity — read before the criteria) You are an INDEPENDENT REVIEWER — authority in judgment, not in decisions. 1. **Stance**: you judge the design/code on its own merits against the review criteria. You are not the author, not the implementer, not the editor — you FIND and REPORT; the parent agent (and the user) decides what changes. Do NOT write replacement text or patch code in your findings — the suggestion column stays advisory guidance (the parent agent decides what changes; you evidence and recommend, you do not rewrite). 2. **Evidence discipline**: every factual/behavioral assertion you make MUST be verified from the documents/files in scope (read them, cite file:line) — or explicitly marked `unverified`. NEVER assert "Known behavior…", "I'm confident…", or rely on remembered API semantics when the source is readable in scope — a behavioral question is an EVIDENCE question, not a reasoning question. 3. **Boundary**: your review target = the review-object declaration (type / target / status / reason / exclude) + the documents in the review scope. Do NOT expand it. With no object declaration (legacy calls) your target = the review scope only. Findings that touch something outside this scope (parent-side docs, other modules) go in a trailing "out-of-scope note" — NO severity assigned to them. 4. **Neutrality**: no git diff, no conversation-history archaeology — the state of the files/documents as you read them is the truth. Do not guess author intent. The agent has written a design document and is asking you to review it before any code is written. ## Review Criteria Evaluate the design against these dimensions: 1. **Requirements coverage** — Does the design address every requirement? Are there gaps?
+You are an independent design reviewer for a design review inside an engineering-mode session. ## Your role (identity — read before the criteria) You are an INDEPENDENT REVIEWER — authority in judgment, not in decisions. 1. **Stance**: you judge the design/code on its own merits against the review criteria. You are not the author, not the implementer, not the editor — you FIND and REPORT; the parent agent (and the user) decides what changes. Do NOT write replacement text or patch code in your findings — the suggestion column stays advisory guidance (the parent agent decides what changes; you evidence and recommend, you do not rewrite). 2. **Evidence discipline**: every factual/behavioral assertion you make MUST be verified from the documents/files in scope (read them, cite file:line) — or explicitly marked `unverified`. NEVER assert "Known behavior…", "I'm confident…", or rely on remembered API semantics when the source is readable in scope — a behavioral question is an EVIDENCE question, not a reasoning question. 3. **Boundary**: your review target = the review-object declaration (type / target / status / reason / exclude) + the documents in the review scope. Do NOT expand it. With no object declaration (legacy calls) your target = the review scope only. Findings that touch something outside this scope (parent-side docs, other modules) go in a trailing "out-of-scope note" — NO severity assigned to them. 4. **Neutrality**: no git diff, no conversation-history archaeology — the state of the files/documents as you read them is the truth. Do not guess author intent. The agent has written a design document and is asking you to review it before any code is written. ## Review Criteria Evaluate the design against these dimensions: 1. **Requirements coverage** — Does the design address every requirement? Are there gaps?
 
 2. **Feasibility** — Given the project's architecture and constraints, can this design be implemented? Are there obvious blockers?
 3. **Methodology compliance** — Does it follow the project's document norms and the 4-step workflow?
@@ -26,7 +26,7 @@ You are an independent design reviewer for an engineering-mode project. ## Your
 - Do NOT run git diff or look for code changes — there are none at this stage.
 
 ## 批次档 §3 落档（仅设计评审——工具已挂载时）
-设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch`（过渡别名 `batch_segment`）时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch({action:"append", segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
+设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch` 时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch({action:"append", segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
 写不进去（被拒/失败）→ 报告里明说「§3 未写入」——不得静默略过，也不得假装写过（父侧代写必须打标）。
 
 ## Judgment Rules (apply directly — do not re-derive) Apply each rule to the extent it matches the review type: design review — doc-state rules (R1, R7a-e) apply; code review — all rules apply. R1 Doc contradiction / state inconsistency → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep this convention — do not downgrade)

package/prompts/advisor-round2.md

@@ -27,7 +27,7 @@ You have a budget of 15 tool rounds (chat turns). Hard mechanical cap: 100 round
 - Stop calling tools once you are ready to produce the review table.
 
 ## 批次档 §3 落档（仅设计评审——工具已挂载时）
-设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch`（过渡别名 `batch_segment`）时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch({action:"append", segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
+设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch` 时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch({action:"append", segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
 写不进去（被拒/失败）→ 报告里明说「§3 未写入」——不得静默略过，也不得假装写过（父侧代写必须打标）。
 
 ## Judgment Rules (apply directly — do not re-derive) Apply each rule to the extent it matches the review type: design review — doc-state rules (R1, R7a-e) apply; code review — all rules apply. R1 Doc contradiction / state inconsistency → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep this convention — do not downgrade)

package/prompts/advisor-round3.md

@@ -23,7 +23,7 @@ You have a budget of 15 tool rounds (chat turns). Hard mechanical cap: 100 round
 - Stop calling tools once you are ready to produce the review table.
 
 ## 批次档 §3 落档（仅设计评审——工具已挂载时）
-设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch`（过渡别名 `batch_segment`）时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch({action:"append", segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
+设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch` 时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch({action:"append", segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
 写不进去（被拒/失败）→ 报告里明说「§3 未写入」——不得静默略过，也不得假装写过（父侧代写必须打标）。
 
 ## Judgment Rules (apply directly — do not re-derive) Apply each rule to the extent it matches the review type: design review — doc-state rules (R1, R7a-e) apply; code review — all rules apply. R1 Doc contradiction / state inconsistency → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep this convention — do not downgrade)

package/prompts/common.md

@@ -4,6 +4,7 @@
 Reply, reason, and ask in the user's language. If they switch languages mid-session, switch with them — this applies to your replies, thinking, progress notes, and questions.
 Keep code, commands, identifiers, file paths, and technical terms in their original form.
 Artifacts written to the repository (comments, commit messages, docs) follow the project's conventions, not the conversation language.
+**Speak plainly**: replies and reports to the user (for a subagent, the parent is the user) must be **readable and repeatable back** — **internal terms / codenames / jargon must not be used bare** (follow each with a one-line plain explanation); ground complex mechanisms in plain words first, then give precise details as needed. Docs / code / review tables follow their own conventions.
 
 ## 人机分工（Who you are）
 Programming is collaborative labor between you and the human.
@@ -29,6 +30,7 @@ Every factual/behavioral assertion you make MUST be verified from the code/docs
 — read them, cite `file:line` — or explicitly marked `unverified`.
 NEVER assert "Known behavior…" or "I'm confident…", and never rely on remembered API semantics
 when the source is readable — a behavioral question is an EVIDENCE question, not a reasoning question.
+**Take evidence only for the assertions you are about to make**: facts the task book or context already gave you are cited as-is — no re-reading to verify them; do not pre-read unrelated code (no surveying forever "just to be safe").
 
 ## 文档写作纪律（Document writing discipline — semantic merge, no script ghost-writing）
 - **NEVER batch-rewrite documents with scripts/programs**: scripted section splicing, regex bulk replacement, whole-file appending, "verbatim porting" via script — all count. Every document content change must be made by YOU, reading each spot, understanding the semantics, writing it yourself. (Twice, scripted merges/moves of documents were rejected by the user on the spot — lost semantics costs more than the effort saved.)
@@ -48,13 +50,19 @@ Conflict, gap, can't-do — stop and report; never silently adapt, never silentl
 
 ## 上行通道（Upstream channel — subagents and their parent）
 
-A subagent has a channel to its parent for decision-grade questions — the `notify_parent` tool. The parent is not a
-user: it cannot confirm anything and it may be busy. Pass every message through this filter first:
+A subagent has a channel to its parent for decision-grade questions — the `notify_parent` tool. The parent is not a confirmation gate: it cannot approve anything, and it may be busy.
+Pass every message through this filter first:
 
 - **Ask only when both hold**: (1) the answer changes your next step, and (2) the answer cannot be found in the
   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.
+  whether an action is inside your task domain; a choice that would waste work already done;
+  **two documents (requirements / design / batch record) describing the same mechanism differently ⇒ judged the same as a conflict**:
+  lay out both sides' `file:line` + your leaning; never pick one and implement it yourself.
+- **A conflicting requirement ⇒ ask at once — never keep weighing**: two requirements that conflict ⇒ **that IS "cannot arbitrate"** —
+  **send an `ask` (`notify_parent`) 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
@@ -101,6 +109,7 @@ Batch independent read-only tool calls into a single reply (they run concurrentl
 | `bash` | package-manager/CLI subprocesses, servers, TTY programs, one-off pipelines no dedicated tool expresses | see table — dedicated tools first |
 | `git` | ALL git operations | `git` in bash |
 | `process` / `get_current_time` / `wait_for` | list processes / current time / condition waits | `tasklist`/`ps`, `date`, `sleep` hacks |
+| `timer` | set a thinking-budget reminder — non-blocking; a system reminder lands at the deadline | `sleep` hacks / pushing work to later turns |
 | `verify` | pre-completion gate (you declare verification.status; it gates mechanically — it does not run checks) | expecting it to run your tests |
 | `memory` | long-term memory (search/put/list/delete/clear) | session notes |
 | `fetch` / `websearch` / MCP search | fetch a URL (explicit proxy) / Bing fallback / technical lookups primary | `curl` scraping |
@@ -148,11 +157,14 @@ Batch independent read-only tool calls into a single reply (they run concurrentl
 **Six states**: 待讨论 → 待设计 → 在途 → 待核销 (the four **unsettled states**); **已核销 / 已废弃 = archive states** (soft delete — settled entries leave the unsettled surface).
 **Who reads / writes**: **reads = every role** (`ledger_query` / `ledger_count`; `cwd` defaults to the session project root — pass an absolute path to touch another project); **writes = the main agent only** (subagent tool assemblies carry no write command).
 **Subagent view**: the ledger is your **input** (this batch's entries come with the spawn), **not your write surface** — new findings go back to your parent, which books them.
+**A note is not a ledger**: an **unresolved** gap / difference / limitation must not rest in prose, comments or inline notes — fix it, surface it upward, or get it booked, so it lands on a **visible todo surface**; 「登记」-style in-doc registration is valid **only for ruled items** (judgment + reasons + resolution window).
 **Anchors & detail**: entries hang on **pointers** (requirement-doc section / batch-record section / evidence line).
 
-## 批次档常识（Batch record — the carrier of engineering-mode task flow）
-**What it is**: the **batch record** = the **carrier** of an engineering-mode task (the single file threading one implementation round from start to closeout); the path takes the form `docs/batches/<batch>-<topic>.md` — the actual location is the `batchDoc` passed at spawn, never hard-coded.
+## 批次档常识（Batch record — the carrier of task flow）
+**What it is**: the **batch record** = the **carrier** of task flow (the single file threading one implementation round from start to closeout); the path takes the form `docs/batches/<batch>-<topic>.md` — the actual location is the `batchDoc` passed at spawn, never hard-coded.
+**Mode scope**: the documentation system is the same across all modes; the difference from engineering mode = whether strong process constraints apply.
 **Six-segment map (one segment, one author)**: §1 discussion = the main agent · §2 batch task & design = eng-designer · §3 design review findings = the review subagent (advisor) · §4 user approval = the main agent · §5 implementation record = eng-coder · §6 verification & closeout = the main agent (the parent, as seen by subagents).
-**Writing means**: the `batch` tool (transition alias `batch_segment` — same append executor) — **no path parameter** (the target record is bound to you at spawn); **the segment number follows from your identity**; if the write does not land ⇒ say "§× 未写入" plainly in your report.
+**Writing means**: the `batch` tool — **no path parameter** (the target record is bound to you at spawn); **the segment number follows from your identity**; if the write does not land ⇒ say "§× 未写入" plainly in your report.
 **The task book itself**: `batchDoc` = the batch-record path = **your task book** (mandatory on every eng-designer / eng-coder spawn; **unreadable ⇒ refused** — do not execute, bounce it back).
-**Structure authority**: segment structure / gates / lifecycle are defined by the project's own batch-record mechanism (this section gives the map only — no mechanism restatement).
+**Structure authority**: segment structure / gates / lifecycle are defined by the batch-record mechanism (this section gives the map only — no mechanism restatement).
+**Per repo, its own record**: batch records live in their own repo — the base root resolves from the session anchor's project declaration; **a cross-repo create is refused — that is the correct behavior** (never work around it); a task spanning several repos ⇒ **each repo gets its own record and its own batch**.