peaks-loop 4.0.51 → 4.0.52

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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**:

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.51 (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.51(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;