sillyspec 3.27.12 → 3.28.0

package/src/agent-session-log.js

@@ -18,7 +18,11 @@
  *   - codex：无可靠 env 标记，按 mtime 活跃窗口扫 <home>/.codex/sessions/YYYY/MM/DD/
  *       rollout-*.jsonl，读首行 session_meta.cwd 精确匹配 CLI cwd（并带出 originator，
  *       如 sillyhub-daemon，供平台关联派发来源）
- *   - zcode：env ZCODE_* 门控；<home>/.zcode/cli/rollout/model-io-sess_<id>.jsonl
+ *   - zcode：env ZCODE_* 门控；<home>/.zcode/cli/rollout/model-io-sess_<id>.jsonl（含
+ *       subagent 会话，文件名带 sess_subagent_agent_ 前缀）。rollout 目录全局共享（所有
+ *       ZCode 窗口/项目混居），读首块系统提示词工作目录标记与 cwd 精确匹配——主会话
+ *       `Primary working directory:` / subagent `<env>` 块 `Working directory:` 两形态均
+ *       实证；标记读不出 fail-closed 不登（错登比漏登危害大，SILLYSPEC_AGENT_LOG 兜底）
  *   - pi：目录名即 cwd 编码（--<路径非字母数字替'-'>--），无需 env 门控；
  *       <home>/.pi/agent/sessions/<safePath>/session.jsonl
  *   - deepseek-dsh（@deepseek-ai/dsh）：同 pi 构但 ':' 删除；
@@ -121,6 +125,51 @@ function readFirstLineJson(filePath, maxBytes = 16384) {
   }
 }
 
+// zcode model-io 无结构化 cwd 字段，归属数据源 = 首行首个请求系统提示词的环境段工作目录标记。
+// 两形态均本机实证：主会话 `Primary working directory: <path>\n- Is a git repository: yes`；
+// subagent 会话 `<env>\nWorking directory: <path>\nIs directory a git repository`。
+const ZCODE_WORKDIR_RE = /[Ww]orking directory: /;
+
+/**
+ * 从 zcode model-io 文件首块字节提取会话工作目录（cwd 归属判定的数据源）。
+ *
+ * 文件是 JSONL：首行 = 首个模型请求（含完整系统提示词），路径以 JSON 字符串内嵌形态出现
+ * ——分隔符双写（`\\`）、行尾是字面 `\n` 两字符。因此取值不能裸 indexOf 截 `\n`：Windows
+ * 路径普遍含 `\n` 字面序列（`\node_modules`、`\notifications`…），须按转义逐字符扫描，
+ * 直到未转义的换行转义（提示词行边界）为止。只读首块不整行 JSON.parse（首行可达 MB 级）。
+ * @returns {string|null} 未命中标记/文件不可读/值为空返回 null（调用方 fail-closed 丢弃）
+ */
+function extractZcodeWorkdir(filePath, maxBytes = 64 * 1024) {
+  let fd = null;
+  try {
+    fd = openSync(filePath, 'r');
+    const buf = Buffer.alloc(maxBytes);
+    const n = readSync(fd, buf, 0, maxBytes, 0);
+    const text = buf.subarray(0, n).toString('utf8');
+    const m = ZCODE_WORKDIR_RE.exec(text);
+    if (!m) return null;
+    const s = text.slice(m.index + m[0].length);
+    let out = '';
+    for (let j = 0; j < s.length;) {
+      const c = s[j];
+      if (c !== '\\') { out += c; j += 1; continue; }
+      const e = s[j + 1];
+      if (e === undefined || e === 'n') break; // 行尾换行转义 → 值结束
+      if (e === 'u' && /^[0-9a-fA-F]{4}$/.test(s.slice(j + 2, j + 6))) {
+        out += String.fromCharCode(parseInt(s.slice(j + 2, j + 6), 16));
+        j += 6;
+      } else if (e === 'r') { out += '\r'; j += 2; }
+      else if (e === 't') { out += '\t'; j += 2; }
+      else { out += e === '/' ? '/' : e; j += 2; } // \\ \" \/ 等：取转义次字符
+    }
+    return out || null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) { try { closeSync(fd) } catch { /* best effort */ } }
+  }
+}
+
 // 活跃文件收集：dir 内 suffix 结尾文件，mtime 在窗口内，mtime 新→旧
 function listActiveFiles(dir, { now, windowMs, limit }) {
   let names;
@@ -233,21 +282,39 @@ function detectCodex(ctx) {
 /**
  * ZCode：env ZCODE_* 门控（本机实证子进程可见 ZCODE_APP_VERSION/ZCODE_ENV 等）；
  * <home>/.zcode/cli/rollout/model-io-sess_<id>.jsonl（含 subagent 会话，文件名带
- * sess_subagent_agent_ 前缀），完整模型 I/O。无 cwd 字段 → env 门控即归属依据。
+ * sess_subagent_agent_ 前缀），完整模型 I/O。
+ *
+ * cwd 归属：rollout 目录全局共享（所有 ZCode 窗口/项目混居），env 门控只证明「CLI 正被
+ * 某个 ZCode 实例驱动」，证明不了「该文件属于本项目」——多窗口并行时另一项目的活跃会话
+ * 会被整体误登（2026-08-31 实证：sillyspec run 把 multi-agent-platform 会话上报为本地
+ * agent 日志）。修法对齐 codex 的 session_meta.cwd 精确匹配：读首块工作目录标记
+ * （extractZcodeWorkdir）与 cwdCandidates 等值比较；标记读不出 fail-closed 丢弃
+ * （错登比漏登危害大——平台把该文件当本会话权威日志解析展示；env 覆盖是兜底通道）。
  */
 function detectZcode(ctx) {
   const { cwdCandidates, env, homeDir, now, windowMs } = ctx;
   const inZcode = Boolean(env.ZCODE_APP_VERSION || env.ZCODE_ENV || env.ZCODE_RUNTIME_ENV);
   if (!inZcode) return [];
   const rolloutDir = join(homeDir, '.zcode', 'cli', 'rollout');
-  const cwdPosix = toPosix(cwdCandidates[0] || '');
-  return listActiveFiles(rolloutDir, { now, windowMs, limit: MAX_PER_HARNESS }).map(f => ({
-    harness: 'zcode', format: 'zcode-model-io-jsonl', detected_via: 'zcode-env-marker',
-    log_path: toPosix(f.full), agent_cwd: cwdPosix,
-    session_id: f.name.replace(/^model-io-sess_/, '').replace(/\.jsonl$/, ''),
-    originator: null,
-    mtime_ms: f.mtimeMs,
-  }));
+  // 预筛多扫一倍再按 cwd 过滤：窗口内其他项目的活跃会话不应在过滤前挤占 MAX_PER_HARNESS 名额
+  const candidates = listActiveFiles(rolloutDir, { now, windowMs, limit: MAX_PER_HARNESS * 2 });
+  const entries = [];
+  for (const f of candidates) {
+    const workdir = extractZcodeWorkdir(f.full);
+    if (!workdir || !cwdCandidates.some(c => c && cwdsMatch(c, workdir))) {
+      debugLog(`zcode rollout cwd 不匹配/无标记，跳过: ${f.name} workdir=${workdir || '(none)'}`);
+      continue;
+    }
+    entries.push({
+      harness: 'zcode', format: 'zcode-model-io-jsonl', detected_via: 'zcode-workdir-marker',
+      log_path: toPosix(f.full), agent_cwd: toPosix(workdir),
+      session_id: f.name.replace(/^model-io-sess_/, '').replace(/\.jsonl$/, ''),
+      originator: null,
+      mtime_ms: f.mtimeMs,
+    });
+    if (entries.length >= MAX_PER_HARNESS) break;
+  }
+  return entries;
 }
 
 /**

package/src/config-schema.js

@@ -68,8 +68,8 @@ export const LOCAL_YAML_SCHEMA = {
       note: 'detect 核验 package.json(或对应构建文件) scripts 存在性后才写对应键；缺失则不写。agent 可改。',
       keys: [
         { path: 'commands.build', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '构建命令。', example: 'npm run build' },
-        { path: 'commands.test', type: 'string', optional: true, status: 'live', readers: ['extractTestCommand (src/verify-postcheck.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '测试命令——verify 阶段 CLI 亲自执行此命令与 verify-result.md 对账，实测失败即阻断。', example: 'npm test' },
-        { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令。', example: 'npm run lint' },
+        { path: 'commands.test', type: 'string', optional: true, status: 'live', readers: ['extractTestCommand (src/verify-postcheck.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '测试命令——verify 阶段 CLI 亲自执行此命令与 verify-result.md 对账，实测失败即阻断；quick --done 触及 src/test 时同款实测（P0-2 门禁）。', example: 'npm test' },
+        { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令——quick --done 触及 src/test 时 CLI 亲自执行（P0-2 门禁，失败阻断完成）。', example: 'npm run lint' },
         { path: 'commands.install', type: 'string', optional: true, status: 'live', readers: ['extractInstallCommand (src/worktree-deps.js)'], desc: '依赖安装命令（worktree 依赖 provisioning 用）。', example: 'npm install' },
       ],
     },

package/src/contract-matrix.js

@@ -15,6 +15,7 @@ import { splitOwnVsForeignDiffFiles } from './foreign-declared.js'
 import {
   scanBackendEndpoints,
   scanFrontendApiCalls,
+  scanMountPrefixes,
   normalizePath,
   diffApiParity,
 } from './endpoint-extractor.js'
@@ -558,7 +559,16 @@ export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = nu
     frontendCalls = scanFrontendApiCalls(frontendRoot)
   }
 
-  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, mergedProviderEndpoints)
+  // ── 挂载前缀收集（坑 endpoints-mount-prefix-gap，2026-08-31 用户实证）：endpoints 提取的是
+  // 「router 自身前缀 + 装饰器路径」，不含挂载点前缀（main.py 的 include_router(prefix=)/app.use
+  // 与 router 文件分离，静态扫描不做导入图关联）→ 前端全路径调用（/api/xxx）对不上欠前缀端点
+  // （/xxx）→ 17 个存量端点全量假 missing、人工逐条定性。对账时按前缀集合剥除前端调用前缀对齐。
+  const mountPrefixes = new Set()
+  for (const { root } of liveByRoot) {
+    try { for (const p of scanMountPrefixes(root)) mountPrefixes.add(p) } catch { /* 单根失败不拖垮整体 */ }
+  }
+
+  const { missingBackend, unusedBackend, prefixAlignedCount } = diffApiParity(frontendCalls, mergedProviderEndpoints, [...mountPrefixes])
   // unusedBackend 收窄到现算端点（存量 artifact 的过期端点不参与——它不在当前代码里，
   // 「前端未调用」可能是端点已被重构掉而非真泄漏）
   const narrowedUnused = unusedBackend.filter(u => {
@@ -575,6 +585,9 @@ export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = nu
   if (narrowedUnused.length > 0) {
     summary += ` | ${narrowedUnused.length} backend endpoints unused by frontend`
   }
+  if (prefixAlignedCount > 0) {
+    summary += ` | ${prefixAlignedCount} calls matched after mount-prefix alignment (artifact paths exclude include_router/app.use prefixes)`
+  }
 
-  return { ok, missingBackend, unusedBackend: narrowedUnused, summary, backendCount: mergedProviderEndpoints.length, frontendCount: frontendCalls.length, scanRoots: liveByRoot.map(r => r.root) }
+  return { ok, missingBackend, unusedBackend: narrowedUnused, summary, backendCount: mergedProviderEndpoints.length, frontendCount: frontendCalls.length, prefixAlignedCount, scanRoots: liveByRoot.map(r => r.root) }
 }

package/src/doctor-diagnostics.js

@@ -21,6 +21,7 @@
  * writer 落盘到 <authoritySpecDir>/.runtime/。
  */
 import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
+import { safeGit } from './git-helper.js';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync, rmSync } from 'fs';
 import { join } from 'path';
 import jsYaml from 'js-yaml';
@@ -750,8 +751,10 @@ export async function runDoctorDiagnostics({ cwd }) {
   const executeMismatch = detectExecuteProgressPlanMismatch(authoritySpecDir, authDb);
   const docBloat = detectDocBloat(authoritySpecDir);
   const repoNativeChain = detectRepoNativeChain(cwd, pointer);
+  // P2-2-②：file-lifecycle 文档欠账（git behind 事实计算，治「改了生命周期代码忘同步文档」）
+  const lifecycleDoc = detectLifecycleDocStaleness(cwd);
 
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain];
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc];
 
   return {
     dimensions,
@@ -763,6 +766,66 @@ export async function runDoctorDiagnostics({ cwd }) {
   };
 }
 
+// ── D8 file-lifecycle 文档欠账（P2-2-②，2026-09-02 跨 agent 工单）──────────────────
+
+/** 生命周期敏感路径（CLAUDE.md「文件生命周期文档同步」界定的触及面） */
+const LIFECYCLE_DOC_REL = 'docs/sillyspec/file-lifecycle.md';
+const LIFECYCLE_SENSITIVE_PATHS = ['src/stages/', 'src/run.js', 'src/run/', 'src/progress.js', 'src/progress/', 'src/db.js'];
+
+/**
+ * file-lifecycle.md 是否落后于生命周期代码改动（git 提交时间事实比较，只读）。
+ * 与 docs-debt（模块卡 behind 计算）同哲学：CLI 算事实、WARNING 提示不阻断——把 CLAUDE.md
+ * 的「更新检查清单」从人工 checklist 变 doctor 自动卡点（agent 忘同步 → 体检可见）。
+ * 降级语义：文档不存在 / 非 git 仓 / git 失败 → pass: true + findings 注记（不误报）。
+ */
+function detectLifecycleDocStaleness(cwd) {
+  const base = { name: 'lifecycle_doc_staleness', label: '生命周期文档同步', safe_actions: [] };
+  const docAbs = join(cwd, LIFECYCLE_DOC_REL);
+  if (!existsSync(docAbs)) {
+    return { ...base, pass: true, severity: null, findings: [`未找到 ${LIFECYCLE_DOC_REL}（本仓无生命周期总文档，跳过）`] };
+  }
+  // 文档最后提交时间（untracked = 从未提交 → 直接提示）
+  const docLog = safeGit(cwd, ['log', '-1', '--format=%ct', '--', LIFECYCLE_DOC_REL]);
+  if (!docLog.value) {
+    return {
+      ...base,
+      pass: false,
+      severity: CHECK_SEVERITY.WARNING,
+      findings: [`${LIFECYCLE_DOC_REL} 存在但从未提交（untracked）——首次提交后本检查生效`],
+    };
+  }
+  const docTs = Number(docLog.value);
+  if (!Number.isFinite(docTs)) {
+    return { ...base, pass: true, severity: null, findings: ['文档时间戳不可解析，跳过（不误报）'] };
+  }
+  // 生命周期代码侧最新提交（取各敏感路径 max %ct；任一路径 untracked 新文件不在 log 里，
+  // git 不可见性注记——工作树未提交改动本就不该由 doctor 报，提交后自然可见）
+  let srcTs = 0;
+  let srcPath = null;
+  for (const p of LIFECYCLE_SENSITIVE_PATHS) {
+    const r = safeGit(cwd, ['log', '-1', '--format=%ct', '--', p]);
+    const ts = Number(r.value);
+    if (Number.isFinite(ts) && ts > srcTs) { srcTs = ts; srcPath = p; }
+  }
+  if (srcTs === 0) {
+    return { ...base, pass: true, severity: null, findings: ['生命周期代码无提交历史，跳过'] };
+  }
+  if (docTs < srcTs) {
+    const days = Math.floor((srcTs - docTs) / 86400);
+    return {
+      ...base,
+      pass: false,
+      severity: CHECK_SEVERITY.WARNING,
+      findings: [
+        `${LIFECYCLE_DOC_REL} 落后生命周期代码改动（最新代码提交 ${srcPath}，文档已落后 ${days} 天）——` +
+        `请按 CLAUDE.md「文件生命周期文档同步」检查清单核对并更新文档 + updated_at 时间戳`,
+      ],
+      safe_actions: [{ dimension: 'lifecycle_doc_staleness', action: 'sync_file_lifecycle_doc', risk: 'manual_edit', rationale: '文档落后于生命周期代码', next_step: `按 CLAUDE.md 检查清单更新 ${LIFECYCLE_DOC_REL} 与头部 updated_at` }],
+    };
+  }
+  return { ...base, pass: true, severity: null, findings: ['file-lifecycle.md 与生命周期代码改动时间线一致'] };
+}
+
 /**
  * 转结构化 JSON（sillyspec doctor --json 输出 + 落盘格式）。
  * severity 口径对齐 scan-postcheck：CHECK_SEVERITY.FAILED → 'critical'。

package/src/endpoint-extractor.js

@@ -143,6 +143,69 @@ export function extractSpringEndpoints(filePath) {
   return endpoints
 }
 
+/**
+ * 从单个文件提取路由挂载前缀（挂载点侧，与 router 文件分离）。
+ * - FastAPI：`app.include_router(xxx_router, prefix="/api")`（含多行形态，`[^)]*?` 跨参数/换行）
+ * - Express：`app.use("/api", router)`
+ * 跨文件前缀无法在提取端点时合并（挂载点与 router 文件分离，静态扫描不做导入图关联），
+ * 收集为前缀集合供对账端剥除对齐（坑 endpoints-mount-prefix-gap）。
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {string[]} 挂载前缀列表
+ */
+export function extractMountPrefixes(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const prefixes = []
+  for (const m of content.matchAll(/\.include_router\s*\([^)]*?prefix\s*=\s*["'`]([^"'`]+)["'`]/g)) {
+    prefixes.push(m[1])
+  }
+  for (const m of content.matchAll(/\bapp\.use\s*\(\s*["'`]([^"'`]+)["'`]/g)) {
+    prefixes.push(m[1])
+  }
+  return prefixes
+}
+
+// backend 扫描目录排除清单（端点提取与挂载前缀收集共用）。
+// 对齐 scanFrontendApiCalls（坑 parity-scan-stale-dirs：.claude/worktrees 陈旧检出
+// 与各类 build 产物混入端点扫描全是噪音）——backend 侧另含 __pycache__/.gradle/maven target
+const BACKEND_DIR_EXCLUDE = [
+  /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^venv$/, /^\.git$/, /^\.gradle$/,
+  /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/, /^\.next$/, /^\.nuxt$/,
+  /^\.output$/, /^\.turbo$/, /^\.parcel-cache$/, /^coverage$/,
+  /^\.sillyspec$/, /^\.worktrees$/, /^\.d\.ts$/,
+  /^(dist|build|target|out)$/i,
+  /test/i,
+]
+
+/**
+ * 递归扫描目录收集路由挂载前缀集合（include_router prefix / app.use 路径）。
+ * @param {string} dir
+ * @param {{ excludePatterns?: RegExp[] }} opts
+ * @returns {string[]} 去重后的挂载前缀列表
+ */
+export function scanMountPrefixes(dir, opts = {}) {
+  const excludePatterns = opts.excludePatterns || BACKEND_DIR_EXCLUDE
+  const prefixes = new Set()
+  if (!existsSync(dir)) return [...prefixes]
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (excludePatterns.some(p => p.test(entry.name))) continue
+        walk(full)
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase()
+        if (ext !== '.py' && ext !== '.js' && ext !== '.ts') continue
+        try {
+          for (const p of extractMountPrefixes(full)) prefixes.add(p)
+        } catch {}
+      }
+    }
+  }
+  walk(dir)
+  return [...prefixes]
+}
+
 /**
  * 从目录递归扫描后端端点（多框架）。
  * 按扩展名分派：.py→FastAPI / .js,.ts→Express / .java→Spring。
@@ -152,16 +215,7 @@ export function extractSpringEndpoints(filePath) {
  * @returns {Array<{ method: string, path: string, source: string, line: number }>}
  */
 export function scanBackendEndpoints(dir, opts = {}) {
-  // 排除清单对齐 scanFrontendApiCalls（坑 parity-scan-stale-dirs：.claude/worktrees 陈旧检出
-  // 与各类 build 产物混入端点扫描全是噪音）——backend 侧另含 __pycache__/.gradle/maven target
-  const excludePatterns = opts.excludePatterns || [
-    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^venv$/, /^\.git$/, /^\.gradle$/,
-    /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/, /^\.next$/, /^\.nuxt$/,
-    /^\.output$/, /^\.turbo$/, /^\.parcel-cache$/, /^coverage$/,
-    /^\.sillyspec$/, /^\.worktrees$/, /^\.d\.ts$/,
-    /^(dist|build|target|out)$/i,
-    /test/i,
-  ]
+  const excludePatterns = opts.excludePatterns || BACKEND_DIR_EXCLUDE
 
   const results = []
   if (!existsSync(dir)) return results
@@ -326,16 +380,30 @@ export function normalizePath(rawPath) {
 // ─── 对账 ───────────────────────────────────────────────────────────────
 
 /**
- * 比较前端调用的路径和后端注册的端点，返回差异
+ * 比较前端调用的路径和后端注册的端点，返回差异。
+ *
+ * 挂载前缀对齐（坑 endpoints-mount-prefix-gap，2026-08-31 用户实证）：后端提取到的是
+ * 「router 自身前缀 + 装饰器路径」，不含挂载点前缀（main.py 的 include_router(prefix=)/
+ * app.use 与 router 文件分离，静态扫描不做导入图关联）→ 前端全路径调用（/api/xxx）对不上
+ * 欠前缀端点（/xxx）→ probe5 全量假 missing（17 个实证，人工定性成本高）。传入
+ * mountPrefixes 时前端调用路径按前缀集合逐个剥除生成候选，任一候选命中即匹配；原始路径
+ * 恒在候选集首位——装饰器自带全路径的仓（提取路径=真实路径）行为不变。
  *
  * @param {Array<{ path: string, method: string, source: string }>} frontendCalls
  * @param {Array<{ path: string, method: string, source: string }>} backendEndpoints
+ * @param {string[]} [mountPrefixes] 挂载前缀集合（scanMountPrefixes 收集）
  * @returns {{
  *   missingBackend: Array<{ path: string, method: string, consumerFile: string, consumerLine: number }>,
- *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>
+ *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>,
+ *   prefixAlignedCount: number,
+ *   ok: boolean
  * }}
  */
-export function diffApiParity(frontendCalls, backendEndpoints) {
+export function diffApiParity(frontendCalls, backendEndpoints, mountPrefixes = []) {
+  // 前缀降序（长的先剥）：/api/ppm 先于 /api，避免剥短前缀后路径失配
+  const prefixes = [...new Set((mountPrefixes || []).filter(p => p && p !== '/'))]
+    .sort((a, b) => b.length - a.length)
+
   // 构建 backend 注册表：归一化 path + method → endpoint
   const backendMap = new Map()
   for (const ep of backendEndpoints) {
@@ -344,27 +412,32 @@ export function diffApiParity(frontendCalls, backendEndpoints) {
   }
 
   const missingBackend = []
+  const frontendKeySet = new Set()
+  let prefixAlignedCount = 0
   for (const call of frontendCalls) {
-    const key = `${call.method}:${normalizePath(call.path)}`
-    if (!backendMap.has(key)) {
+    const base = normalizePath(call.path)
+    const candidates = [base]
+    for (const p of prefixes) {
+      if (base.startsWith(p + '/')) candidates.push(base.slice(p.length))
+    }
+    for (const c of candidates) frontendKeySet.add(`${call.method}:${c}`)
+    const matched = candidates.find(c => backendMap.has(`${call.method}:${c}`))
+    if (!matched) {
       missingBackend.push({
-        path: normalizePath(call.path),
+        path: base,
         method: call.method,
         consumerFile: call.source,
         consumerLine: call.line,
       })
+    } else if (matched !== base) {
+      prefixAlignedCount++
     }
   }
 
-  // 构建 frontend 调用表
-  const frontendSet = new Set(
-    frontendCalls.map(c => `${c.method}:${normalizePath(c.path)}`)
-  )
-
   const unusedBackend = []
   for (const ep of backendEndpoints) {
     const key = `${ep.method}:${normalizePath(ep.path)}`
-    if (!frontendSet.has(key)) {
+    if (!frontendKeySet.has(key)) {
       unusedBackend.push({
         path: normalizePath(ep.path),
         method: ep.method,
@@ -373,7 +446,7 @@ export function diffApiParity(frontendCalls, backendEndpoints) {
     }
   }
 
-  return { missingBackend, unusedBackend, ok: missingBackend.length === 0 }
+  return { missingBackend, unusedBackend, prefixAlignedCount, ok: missingBackend.length === 0 }
 }
 
 // ─── CLI 入口 ────────────────────────────────────────────────────────────
@@ -394,7 +467,9 @@ export async function contractScan(args, cwd) {
 
   const backendEndpoints = scanBackendEndpoints(backendDir)
   const frontendCalls = scanFrontendApiCalls(frontendDir)
-  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, backendEndpoints)
+  // 挂载前缀收集（坑 endpoints-mount-prefix-gap）：backend 根的挂载点（include_router/app.use）
+  const mountPrefixes = scanMountPrefixes(backendDir)
+  const { missingBackend, unusedBackend, prefixAlignedCount } = diffApiParity(frontendCalls, backendEndpoints, mountPrefixes)
 
   return {
     backend: backendEndpoints.map(e => ({ method: e.method, path: normalizePath(e.path), file: e.source })),
@@ -406,6 +481,7 @@ export async function contractScan(args, cwd) {
       frontendCallCount: frontendCalls.length,
       missingBackendCount: missingBackend.length,
       unusedBackendCount: unusedBackend.length,
+      prefixAlignedCount,
       ok: missingBackend.length === 0,
     },
   }

package/src/index.js

@@ -8,7 +8,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
 import { writeAtomicSync } from './fs-atomic.js';
-import { basename, extname, join, resolve, isAbsolute } from 'path';
+import { basename, dirname, extname, join, resolve, isAbsolute } from 'path';
 import { safeGit, git } from './git-helper.js';
 import { getVersion } from './version.js';
 
@@ -151,6 +151,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec run plan --reopen --from-step 2          # 修订 plan，从第 2 步重做
   sillyspec run quick --non-interactive --done --output "CI 内的快修"  # 脚本/CI
   sillyspec progress show
+  sillyspec progress show --json        # 全局总览 envelope（面板/脚本消费）
   sillyspec worktree apply 2026-07-03-add-login
 `);
 }
@@ -266,6 +267,25 @@ async function main() {
     // QUAL-01 收口：原 execSync 字符串拼接（经 shell）→ git-helper 数组形式
     const r = safeGit(baseDir, ['rev-parse', '--show-toplevel'])
     if (r.value && existsSync(join(r.value, '.sillyspec'))) return r.value
+    // P1-1 第四层锚定（2026-09-02 跨 agent 工单）：.sillyspec 被 gitignore 的仓，linked worktree
+    // 内无 .sillyspec 副本 → 上面两级全 miss，返回 baseDir 会在 worktree 里新建分裂进度库
+    // （run 链路的 D-03 守卫只覆盖「有副本」场景、quick drift 守卫只覆盖「已有 session guard」
+    // 场景，均拦不住新会话）。判据与 worktree.js detectIsolation/_resolveMainRepoRoot 同源：
+    // --git-dir ≠ --git-common-dir 且非 submodule = linked worktree → common-dir 父目录即主仓根。
+    const gd = safeGit(baseDir, ['rev-parse', '--git-dir'])
+    const gcd = safeGit(baseDir, ['rev-parse', '--git-common-dir'])
+    const superProj = safeGit(baseDir, ['rev-parse', '--show-superproject-working-tree'])
+    if (gd.value && gcd.value && gd.value !== gcd.value && !superProj.value) {
+      // common-dir 可能是相对路径，须相对 baseDir 绝对化（与 worktree.js _resolveMainRepoRoot 同坑同解）
+      const absCommonDir = resolve(baseDir, gcd.value)
+      if (existsSync(absCommonDir)) {
+        const mainRoot = dirname(absCommonDir)
+        if (mainRoot !== baseDir && existsSync(join(mainRoot, '.sillyspec'))) {
+          console.warn(`⚠️ cwd 位于 linked worktree，进度库已自动锚定主仓：${mainRoot}（治 worktree 分裂进度库，P1-1）。如确要在 worktree 内独立建进度库，请显式 --spec-dir。`)
+          return mainRoot
+        }
+      }
+    }
     return baseDir
   }
 
@@ -306,9 +326,20 @@ async function main() {
           pm.init(progDir);
           break;
         case 'status':
-        case 'show':
+        case 'show': {
+          // --json：全局总览 envelope（machine-interface，2026-09-02 单一状态源）——多变更
+          // 列表 + 进度/ghost/stall 标记，供 SillyHub 面板 / 跨 agent 程序化消费（与 dump 的
+          // 单变更视角互补）。overview 是纯数据方法不发 console，stdout 直接留 JSON，无需劫持。
+          if (json) {
+            const { runStatusOverview } = await import('./machine-interface.js');
+            const { envelope, exitCode } = runStatusOverview({ cwd: progDir, specBase: resolvePlatformSpecDir(dir, specDir) });
+            console.log(JSON.stringify(envelope));
+            process.exitCode = exitCode;
+            break;
+          }
           pm.show(progDir, progChangeName);
           break;
+        }
         case 'check': {
           const result = pm.checkConsistency(progDir, progChangeName);
           // checkConsistency 只返回 {ok, issues, warnings}，不打印——必须在此输出，
@@ -418,7 +449,7 @@ async function main() {
           break;
         }
         default:
-          console.log('用法: sillyspec progress <init|show|validate|reset|set-stage|add-step|update-step|complete-stage|dump>');
+          console.log('用法: sillyspec progress <init|show|validate|reset|set-stage|add-step|update-step|complete-stage|dump>\n  show 支持 --json：全局总览 envelope（活跃变更列表 + 进度 + ghost/stall，面板/脚本消费）');
           process.exit(2);
       }
       break;
@@ -539,14 +570,14 @@ async function main() {
       // 缺失草稿，独立可随时跑（不必再 execute --done）。缺数据（无 tasks/ 目录 / 改动未 commit / 无 worktree meta）
       // 时 generateTaskReviewDrafts 提前返回 reason，如实打印不报错。
       // --adopt（2026-08-21 agent-手工产出审计项①）：已存在 review.json 的 mechanics 字段
-      // （schemaVersion/task/base/head/changedFiles/repo）一键重算代填，agent/子代理只写
+      // （schemaVersion/task/base/head/changedFiles/diffPaths/repo）一键重算代填，agent/子代理只写
       // verdict——手算 hash、手抄 diff 清单是纯错误面，gate 校验的恰是这些字段。与草稿互补：
       // 草稿补「缺失」，adopt 修「已存在但 mechanics 错/缺」，verdict 原样保留。
       const brChangeIdx = args.indexOf('--change');
       const brChange = brChangeIdx >= 0 && args[brChangeIdx + 1] ? args[brChangeIdx + 1] : null;
       const brAdopt = args.includes('--adopt');
       if (!brChange) {
-        console.error('用法: sillyspec backfill-reviews --change <name> [--adopt] [--json] [--spec-dir <path>]\n  缺失 review.json → 生成 cannot_verify 草稿（解 archive 客观完成度阻断）\n  --adopt → 已存在 review.json 的 base/head/changedFiles 等 mechanics 字段一键重算代填（verdict 保留）');
+        console.error('用法: sillyspec backfill-reviews --change <name> [--adopt] [--json] [--spec-dir <path>]\n  缺失 review.json → 生成 cannot_verify 草稿（解 archive 客观完成度阻断）\n  --adopt → 已存在 review.json 的 base/head/changedFiles/diffPaths 等 mechanics 字段一键重算代填（verdict 保留；统一 commit 模式 diffPaths=task 卡 allowed_paths）');
         process.exit(2);
       }
       // 与 run 入口同源消毒（防路径穿越；backfill 下游拼 marker/changes/review 路径）

package/src/machine-interface.js

@@ -541,3 +541,66 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot,
     return { envelope, exitCode: EXIT_UNKNOWN };
   }
 }
+
+// ============ 全局状态总览（单一状态源，2026-09-02 跨 agent 协作改进 P0-1）============
+
+/**
+ * 全局状态总览：全部活跃变更列表 + 各自阶段/步骤进度 + ghost/stall 标记。
+ *
+ * 与 gate/derive（单变更粒度）和 progress dump（单变更视角、daemon 轮询）互补——
+ * 本命令回答「这个项目现在有谁在动哪些变更」，供 SillyHub 面板 / 跨 agent 消费
+ * （`sillyspec progress show --json`）。
+ *
+ * 只读契约（同 runGate D-002@v1）：仅 ProgressManager 读路径，不写 sillyspec.db；
+ * DB 不存在 → fail-closed 返回 exit 2（项目未初始化，无从总览），不建库。
+ * 数据组装单点在 StageMachine.overview（与 show 汇总视图同源 listChanges/_stallSignal），
+ * 本函数只做 envelope 封装——沿「只聚合不新增校验」的模块定位。
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd - 项目根目录
+ * @param {string} [opts.specBase] - .sillyspec（或平台 specRoot）目录；默认 resolveSpecDir(cwd)
+ * @returns {{ envelope: object, exitCode: number }} exitCode：0 总览成功（含空列表）/ 2 无法核验
+ */
+export function runStatusOverview({ cwd, specBase } = {}) {
+  const specRoot = specBase || resolveSpecDir(cwd);
+
+  try {
+    const dbPath = join(specRoot, '.runtime', 'sillyspec.db');
+    if (!existsSync(dbPath)) {
+      const envelope = buildEnvelope({
+        command: 'progress show',
+        ok: false,
+        errors: [`无法核验：进度库不存在（${dbPath}）——项目尚未初始化进度，只读总览不会为其建库`],
+      });
+      return { envelope, exitCode: EXIT_UNKNOWN };
+    }
+
+    const pm = new ProgressManager({ specDir: specRoot });
+    const data = pm.overview(cwd);
+
+    // ghost（目录缺失残留记录）升 warnings：不阻断 ok（总览本身是成功的，ghost 是待清理事实）
+    const warnings = data.changes
+      .filter(c => c.ghost)
+      .map(c => `${c.name}: 目录缺失（残留记录，sillyspec doctor --cleanup-ghosts --confirm 可归档清理）`);
+    // P2-2-①：未决同步冲突同样升 warnings（冲突可见性——daemon/面板看顶层即知有冲突待处理）
+    for (const cf of (data.pending_conflicts || [])) {
+      warnings.push(`${cf.change}: 未决同步冲突（${cf.type === 'progress' ? '进度' : 'spec 树'}，sillyspec platform resolve 处理）`);
+    }
+
+    const envelope = buildEnvelope({
+      command: 'progress show',
+      ok: true,
+      warnings,
+      data,
+    });
+    return { envelope, exitCode: EXIT_OK };
+  } catch (e) {
+    // 内部异常兜底（同 runDerive）：stdout 永远合法 JSON，exit 2
+    const envelope = buildEnvelope({
+      command: 'progress show',
+      ok: false,
+      errors: [`internal: ${e.message}`],
+    });
+    return { envelope, exitCode: EXIT_UNKNOWN };
+  }
+}