peaks-loop 4.0.50 → 4.0.52

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 4.0.52 — 2026-09-17 (codegraph 索引完整性检测闸门 + repair-index 强制重建 + 套用到本仓：include gap 31→0、dead rows 4→0、strict-mode exit 75→0)
+
+**Highlights**:
+
+1. **codegraph 索引完整性的"不能评估"路径是一个静默假绿（exit 0）。** `codegraph-index-integrity.ts` 的 `try/catch` 只裹住 `new Database(...)`；`db.prepare('SELECT path FROM files').all()` 在 `try { … } finally { db.close() }` 里 —— `no such table: files`（上游 schema 漂移）会**裸抛**到 `codegraph-commands.ts:304-309`，那里把 `indexIntegrity` 写成 `null`，下游 `integrity?.gap === true || indexGap ? … : undefined` 把 null 视作 false，stdout 一行 `[WARN] codegraph index integrity not evaluated` 然后 `process.exitCode = 0`。这是**本仓签名缺陷**：`codegraph-exclude-reconciler.ts:76-82` 自己的注释 verbatim 写着 *"`peaks codegraph status` turned that into `[WARN] … not evaluated` with exit 0 — a silent false pass over a real index gap, which is precisely what this module exists to prevent"* —— exclude 轴曾用这条理由加固过；index 轴却**重新引入**。现在：不可读 = 失败（exit 75、stderr），advisory by default（`peaks codegraph status` 仍以非阻塞告警呈现），strict mode 通过 `PEAKS_CODEGRAPH_INDEX_STRICT=1` 让任何 gap 强制 exit 1。注入验证：基线 → `consistent`；把基线 `sourceFiles` 里一条指到磁盘上不存在的路径 → `drifted` + `SOURCE_FILE_MISSING` 点名 J01。
+
+2. **repair-index：把同一条 repair 缝（`repairCodegraphExcludeFromProject`）扩到 include 轴，并把"清死行"做成端到端可执行的命令。** `peaks codegraph repair-index` 是新公开命令，先调上游 `cg.clear()` 再 `index --force`；不修缝就修不了"旧的无效的也要删除"那条 directive —— 增量 `index` 永不删行（`.peaks/memory/codegraph-status-ok.md` 已记），只有 `--force` 会。**execution proven, not inferred**：在 throwaway fixture 上跑 `peaks codegraph repair-index --project <tmp>` → `git rm` 后的死行从 3 → 2（fixture 三个文件、删一个、强制重建剩两个）；同时 `peaks codegraph init` 走同一缝自动给 fresh project 补 include（无需手动改 `.codegraph/config.json`，directive 3 对新项目成立）。缝的 3 个调用点（`init` / preflight / post-slice auto-refresh）都自动受益，没有新增平行缝。**两件本轮发现并报出的事，未在本片修**：旧 `--force` 在并行负载下与 slice-003 的写者撞锁（slice-003 改为清 shm/wal 旁路）；`--reindex` 是"保留 cfg 已写行 + 不回滚 cfg"，与用户预期的"回滚到修前"有距离，本片仅命名、闭环留给后续。
+
+3. **套用到本仓（slice-003）：include gap 31 → 0、dead rows 4 → 0、strict-mode exit 75 → 0。** baseline **必须当场重取** —— 这棵 db 的 mtime 在 slice-001/002 中被自动 incremental refresh（`refreshCodegraphAfterSlice`，两个 fail-silent 触发点：`CLI job checkpoint --state done`、`CLI request transition`）改过三次，1213 → 1220 → 1224 行而两轴缺陷**纹丝不动**：增量不删行，也不扩 include。修前 sha256 + 行/死行计数在同一步取，然后修，然后比对。修前 `.codegraph/codegraph.db-shm` 与 `codegraph.db-wal` 旁路清掉（WAL 留在原地会让 byte-exact diff 出假阳性；slice-003 完整记录这套对齐步骤）。**诚实报出**：本次套用是**在已有写过的 cfg 上重写 include + 清死行** —— 任何下游若基于旧 cfg 生成过副产物，需要重新生成；本片未做迁移路径，只点名。
+
+4. **用户报后修。** (a) **7 个 SKILL.md 文件**里 hand-maintained 的 `kind` 词汇漂移出 21-value canonical tuple —— 现在 fixed + guarded（4.0.51 那片把引用完整性守卫的语料扩到 `skills/**`；本片把 `kind` 字段接进守卫），未来漂移一发生即红。(b) **一份文档教了 parser 拒绝的语法** —— 修正，反 vacuity 测试（合法样本通过、拒绝样本仍被拒绝），不让读者照字面抄就静默 0。
+
+5. **缺陷扫荡（12+）：codegraph 错误消息、refresh 可见性、`.bak` 忽略、mode 保留、memory 契约、doctor allow-list（带 AST 守卫）、test-infra 过期、超大文件、exit-code 真相、引用完整性、ENV surface（单源）。** 统一动作：每条都接住一个"读到的是这样，证据说的是那样"对位，修后配注入验证（基线 → 绿；注入 → 红；移除 → 复绿）。**单源原则是这一轮的暗线**：凡有"两个地方算同一个数 / 同一个字符串"的地方，本片都合并到唯一来源（`vitest.workers.ts` 是 maxWorkers 单源；ENV 表面单源；doctor allow-list 单源）。
+
+6. **`vitest.workers.ts`：单源 `maxWorkers`，默认 2（负载形 flake safety），`PEAKS_VITEST_MAX_WORKERS` 覆盖。** 之前的最大值是分散在两套配置里算的（`Math.max(2, …)`），但其中一个入口从来没被走过；负载一上来就在 worker 数不稳定的两条路径之间漂。
+
+**验证**：290/290 unit tests、`tsc` 142、`lint` 6/6、`peaks codegraph status` 在 strict 模式下本仓 `consistent`、`codegraph.db` 行 1224 + 0 dead rows、`config.json` 与 `codegraph.db` 的 sha256 在 repair 前后取两次确认未引入新漂移。
+
+**明确未验证的（不当作已完成）**：`peaks codegraph repair-index` 的回滚契约 —— 现实现是 `--reindex`（不动 cfg 已写行 + 不回滚 cfg），与用户预期的"回滚到修前"有距离，本片仅命名 + 留口，未做；`refreshCodegraphAfterSlice` 仍是 fail-silent —— 本片不修，因为改它需要同时改两处调用点的契约（`job-commands.ts:306` / `request-commands.ts:468`），超出本版范围；slice-001 的 `indexIntegrity === null` 路径现在**不再静默**，但若上游 `codegraph.db` 合法但表完全缺（比 `no such table: files` 更罕见），错误消息的精细度还有一格没补。
+
+## 4.0.51 — 2026-09-16 (子代理 await 永远报不出结果 + 49 处"声称有测试守护、测试早已删除" + 9 个恒真断言 + 三个不可达导出)
+
+**Highlights**:
+
+1. **`peaks sub-agent await` 永远不可能报告任何结果。** `share-commands.ts` 把 `recordPaths` **硬编码成空数组**，而 `await-batch.ts` 在它为空时**直接短路** —— 于是这个命令每次都走空分支，静默返回。文件自己的注释就承认了这个状态（*"`recordPaths: []` case"*）。现在：新增 `resolveBatchRecords` 扫 `.peaks/_sub_agents/<sid>/dispatch-*.json` 并按 record **自己的 `batchId`** 匹配 —— 用的是 `finalize --batch` 与 `findBatchRecords` **已经在用的同一套约定**，没有另发明路径约定；`dispatchCount` 是真实计数；**零匹配 → `NO_DISPATCH_RECORDS` + exit 1**；ok 信封新增 `unreadableRecords` 与告警，**不可读的候选不再沉默**。反例对照：把 `recordPaths: []` 重新注入 → 新增的 7 个测试**全部失败**；还原 → 7/7 通过。
+
+2. **49 处在文档里声称"由某个测试守护"，而那些测试早就被删了 —— 包括守卫自己文件头里写的那次提交删掉的那个。** 引用完整性守卫原先的语料是 `CLAUDE.md` / `.peaks/PROJECT.md` / `README.md` / `.peaks/standards` —— **不含 `skills/**`**，而它的锚点正则里明明列着 `skills/`。把 `skills/**` 加进语料后，**守卫自己吐出 178 处悬空引用 / 64 文件**（此前临时扫描器估的 95 **低了近一倍**，且它归因的 `de0872b7` 只占 11 处）。修了 93 处后剩 85 处，**全部逐条处置、零白名单化**：其中 **43 处引用 21 个测试** —— 1 个删于 `457b9a87`（**正是守卫文件头自称"它存在的理由"的那次提交**）、20 个删于 `f17aa377`（*"delete 559 legacy unit tests"*）、**2 个从未在任何 commit 里存在过**；另有 6 处悬空文档互引。**每一条都逐站改写，不做批量正则替换**（"由 X 守护"与"见 X"语义不同）。**残留如实披露而非关闭**：这 49 站现在如实说明"无物钉住它"，并逐个点名了真实的覆盖缺口 —— `isDeprecatedReviewer` / `RD_DEPRECATED_REVIEWERS`、prereq 向后兼容形态、G11.5 标题锁、20-次调用节奏、handoff frontmatter（`gateEvidence` 在 `src/` 里**无人读取**）、superpowers 四条款规则、`peaks-ide` 审计日志助手。**未补测试（超出本片范围），也未放宽或删除任何一个。**
+
+3. **9 个 `supportsScope` 断言全部恒真，且唯一消费者是一个循环论证的测试。** 接口声明 `supportsScope(scope: 'project' | 'global')`，9 个 adapter 的实现是 1 个 `() => true` 加 8 个逐字相同、**在类型上必然为真**的表达式 —— 没有一个能返回 `false`。**生产零调用者**：全仓唯一消费者是一个把它"characterise"成两个 scope 都返回 true 的新测试。**删除**（接口 + 9 实现 + 那个测试）。理由：参数类型即值域、无 adapter 只支持单一 scope（9/9 `resolveSettingsFile` 双 scope 对称），且真实属性已被 `adapter-runtime-surfaces.test.ts` 钉住。
+
+4. **两个不可达导出与一处死参数。** `traeCnSubAgentDispatcher` 有导出、有测试、**没注册到任何 adapter**（8 个 adapter 分别注册了 claudeCode / codex / cursor / trae / null —— 且**没有 `trae-cn` adapter**，`IdeId` 里也没有）。它唯一可引的"支持"证据是 postinstall 的目录映射，**不是适配器注册** —— 给它建 adapter 等于**发明一条不存在的接线**，故删除。`awaitByLlmFallback` 生产零调用者（它的"向后兼容测试"只证明它自己存在 —— 与第 3 条同型的循环），且其注释里承诺的目标在 1.3 已兑现，故删除。另报出：`PollDispatchRecordsOptions.ide` **从未被 `pollDispatchRecords` 读取**（既有死表面，属三项目标之外，仅报出未修）。共 15 文件 **+61/−170**。
+
+5. **守卫的射程缺口与被裁掉的候选一起被记录。** 本片为 31 处误报新增了 5 条**带理由**的候选排除规则（省略号族、`./` 消费者根、`<…>` 模板、illustration 提示、`isDocumentRelative`），为 5 处运行时路径新增 `RUNTIME_STATE_PREFIXES`（`_runtime/` / `cron/` / `cache/`，各带理由）—— `OPTIONAL_RUNTIME_PATHS` **未增长（仍 2 条）**。**同时如实报出两个未修的射程缺口**：裸文件名引用（如 `skills-skill-md-naming.test.ts`）与围栏 ` ```bash ` 代码块对候选规则**不可见**。守卫的注入验证含**一条负对照**：同一路径写成 `mappers/…` 保持绿 —— 那正是本片唯一收窄候选集的地方，公开标注以免被读成"全都能抓"。
+
 ## 4.0.50 — 2026-09-16 (自审把 29% 从分母里排除 + 反漂移闸门报 15/15 而只跑了 1 条 + 一条"no exceptions"的红线没有任何执行者 + 五个测试套件从未运行过 + macOS 从未进 CI)
 
 **Highlights**:

package/README-en.md

@@ -140,7 +140,7 @@ Every lane opens with **one slash command**.
 
 | | |
 | --- | --- |
-| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.50 (2026-09-16) |
+| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.52 (2026-09-17) |
 | **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
 | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
 | **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · **0 timeouts** · 14 BDD caller-binding edge cases |

package/README.md

@@ -140,7 +140,7 @@ npm i -g peaks-loop
 
 | | |
 | --- | --- |
-| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.50(2026-09-16) |
+| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.52(2026-09-17) |
 | **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
 | **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
 | **测试套件** | 1096 cases · 4 packages (peaks-loop 1015 / runtime 39 / mut 22 / shared-channel 20) · **CI 首次全绿**(ubuntu + windows) · 14 BDD caller-binding coverage |

package/dist/cli/commands/baseline-commands.js

@@ -6,6 +6,7 @@ import { validateBaselineFile } from '../../services/capability-baseline/validat
 import { P0_JOURNEY_IDS } from '../../services/capability-baseline/types.js';
 import { GUARD_CONTRACTS, getGuardContract, isJourneyId } from '../../services/capability-guard-runner/registry.js';
 import { exitCodeForGuardSummary, runAllGuards } from '../../services/capability-guard-runner/runner.js';
+import { RUNTIME_SESSIONLESS_SCOPE } from '../../services/workspace/runtime-layout.js';
 function fail(io, code, message, data = {}) {
     io.stdout(JSON.stringify({ ok: false, command: `baseline`, code, message, data, warnings: [], nextActions: [] }));
     process.exitCode = 1;
@@ -163,9 +164,18 @@ export function registerBaselineCommands(program, io) {
         // It is handed the frozen rows and the registry, not just the guard
         // summary — a scorer that only sees the guard result is a restatement.
         const { runAudit } = await import('../../services/capability-audit-service/runner.js');
+        // `sessionId` is the on-disk scope for the audit artifacts. This command
+        // has NO session — it is the credential-free scorer that runs inside the
+        // secretless OIDC publish gate — and it used to pass the literal `'cli'`,
+        // so every run wrote `.peaks/_runtime/cli/capability-audit/*.json` into
+        // the operator's real workspace. That directory is indistinguishable from
+        // a session dir whose id failed validation, so `peaks doctor`'s
+        // orphan-session check failed on it permanently (`4 orphan session(s)
+        // …: callers, cli, unknown-sid, x`, exit 1). The reserved
+        // underscore-prefixed scope says "machinery, not a session" in the name.
         const audit = await runAudit({
             projectRoot,
-            sessionId: 'cli',
+            sessionId: RUNTIME_SESSIONLESS_SCOPE,
             journeyId: 'J01',
             scorerMode: opts.scorer,
             baselineRows: r.file.rows,

package/dist/cli/commands/codegraph-command-runtime.d.ts

@@ -0,0 +1,28 @@
+import { type CodegraphInvocationOptions } from '../../services/codegraph/codegraph-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface CommonCodegraphOptions {
+    project: string;
+    peaksJson?: boolean;
+}
+export declare function printCodegraphFailure(io: ProgramIO, command: string, error: unknown, asJson?: boolean, exitCode?: number): void;
+/**
+ * Rewrites bare upstream `codegraph <subcommand>` hints to the peaks-loop
+ * equivalent (`peaks codegraph <subcommand>`). The upstream binary is a
+ * nested transitive dependency and is NOT on PATH, so an LLM that follows
+ * a bare hint like `Run "codegraph init" to initialize` would hit
+ * "command not found". Already-prefixed `peaks codegraph ...` hints and
+ * other `codegraph` references (e.g. `@colbymchenry/codegraph`) are left
+ * untouched.
+ */
+export declare function rewriteBareCodegraphHints(text: string): string;
+/**
+ * Proxy one upstream invocation. Returns whether UPSTREAM FAILED — the
+ * caller needs that to rank the exit-code precedence (an upstream failure
+ * outranks every localized integrity verdict: see the tail of
+ * `runCodegraphStatusCommand`), and it cannot re-derive it from
+ * `process.exitCode` once a later branch has overwritten it.
+ *
+ * Callers that do not rank precedence (every command but `status`) simply
+ * ignore the return value.
+ */
+export declare function runCodegraphCommand(io: ProgramIO, command: string, options: CodegraphInvocationOptions, asJson?: boolean, attributeStdout?: (text: string) => string): Promise<boolean>;

package/dist/cli/commands/codegraph-command-runtime.js

@@ -0,0 +1,72 @@
+// src/cli/commands/codegraph-command-runtime.ts
+//
+// Shared invocation runtime for every `peaks codegraph <verb>`: the option
+// shape they all extend, the failure envelope they all print, the hint
+// rewriter that keeps upstream's bare `codegraph …` hints runnable, and the
+// upstream proxy itself.
+//
+// Extracted verbatim from `codegraph-commands.ts` (rid
+// 2026-09-17-oversize-and-scale, D1 — the 800-line file-size cap). Every moved
+// line is byte-identical and no behaviour changed; `codegraph-commands.ts`
+// re-exports `rewriteBareCodegraphHints` so the public surface is stable.
+//
+// This module is the BOTTOM of the codegraph CLI's import graph. It must not
+// import `codegraph-commands.ts` or `codegraph-status-command.ts`, or the
+// extraction would introduce a cycle.
+import { createCodegraphInvocation, executeCodegraphInvocation } from '../../services/codegraph/codegraph-service.js';
+import { fail } from 'peaks-loop-shared/result';
+import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+export function printCodegraphFailure(io, command, error, asJson, exitCode = 1) {
+    printResult(io, fail(command, 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check the codegraph command options and project path before retrying']), asJson);
+    process.exitCode = exitCode;
+}
+/**
+ * Rewrites bare upstream `codegraph <subcommand>` hints to the peaks-loop
+ * equivalent (`peaks codegraph <subcommand>`). The upstream binary is a
+ * nested transitive dependency and is NOT on PATH, so an LLM that follows
+ * a bare hint like `Run "codegraph init" to initialize` would hit
+ * "command not found". Already-prefixed `peaks codegraph ...` hints and
+ * other `codegraph` references (e.g. `@colbymchenry/codegraph`) are left
+ * untouched.
+ */
+export function rewriteBareCodegraphHints(text) {
+    return text.replace(/(?<![\w-])(?<!peaks\s)codegraph(?=\s+(?:status|init|index|query|files|context|affected)\b)/g, 'peaks codegraph');
+}
+/**
+ * Proxy one upstream invocation. Returns whether UPSTREAM FAILED — the
+ * caller needs that to rank the exit-code precedence (an upstream failure
+ * outranks every localized integrity verdict: see the tail of
+ * `runCodegraphStatusCommand`), and it cannot re-derive it from
+ * `process.exitCode` once a later branch has overwritten it.
+ *
+ * Callers that do not rank precedence (every command but `status`) simply
+ * ignore the return value.
+ */
+export async function runCodegraphCommand(io, command, options, asJson, attributeStdout) {
+    try {
+        const invocation = createCodegraphInvocation(options);
+        const result = await executeCodegraphInvocation(invocation);
+        if (result.exitCode !== null && result.exitCode !== 0 && asJson === true) {
+            printCodegraphFailure(io, command, new Error(result.stderr || result.stdout || `codegraph exited with code ${result.exitCode}`), true, result.exitCode);
+            return true;
+        }
+        const didFail = result.exitCode !== null && result.exitCode !== 0;
+        const rewritten = rewriteBareCodegraphHints(result.stdout);
+        const stdout = attributeStdout === undefined ? rewritten : attributeStdout(rewritten);
+        const stderr = rewriteBareCodegraphHints(result.stderr);
+        if (stdout.length > 0) {
+            io.stdout((didFail ? redactSensitiveErrorMessage(stdout) : stdout).trimEnd());
+        }
+        if (stderr.length > 0) {
+            io.stderr((didFail ? redactSensitiveErrorMessage(stderr) : stderr).trimEnd());
+        }
+        if (didFail) {
+            process.exitCode = result.exitCode;
+        }
+        return didFail;
+    }
+    catch (error) {
+        printCodegraphFailure(io, command, error, asJson);
+        return true;
+    }
+}

package/dist/cli/commands/codegraph-commands.d.ts

@@ -1,14 +1,5 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-/**
- * Rewrites bare upstream `codegraph <subcommand>` hints to the peaks-loop
- * equivalent (`peaks codegraph <subcommand>`). The upstream binary is a
- * nested transitive dependency and is NOT on PATH, so an LLM that follows
- * a bare hint like `Run "codegraph init" to initialize` would hit
- * "command not found". Already-prefixed `peaks codegraph ...` hints and
- * other `codegraph` references (e.g. `@colbymchenry/codegraph`) are left
- * untouched.
- */
-export declare function rewriteBareCodegraphHints(text: string): string;
-export declare function attributeUpstreamUpToDateLine(stdout: string): string;
+export { rewriteBareCodegraphHints } from './codegraph-command-runtime.js';
+export { attributeUpstreamUpToDateLine } from './codegraph-status-command.js';
 export declare function registerCodegraphCommands(program: Command, io: ProgramIO): void;