peaks-loop 4.0.43 → 4.0.44

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 4.0.44 — 2026-09-12 (被静默排除的源文件 + 一个验错东西的验收闸)
+
+**Highlights**:
+
+1. **`peaks codegraph status` 报"索引是最新的",而 26 个 git 跟踪的源文件根本不在索引里。** 上游默认 exclude 表**按目录名**匹配,而本仓库恰好把 `artifacts/` `release/` `vendor/` `bin/` `publish/` 用作了源码目录名,于是 5 条默认规则把 26 个真实源文件挡在门外。`status` 说的是"图与上次扫描一致",不是"图覆盖了仓库" —— 所以这个洞是隐形的。
+
+   本版按**一条原则**建了 reconcile / repair / verify:被 git 跟踪的源文件不得被 exclude 规则挡住。
+
+   - 对账用 `picomatch`(从传递依赖提升为直接依赖),与上游**同一个匹配引擎**;此前自实现的 glob 对 `{}` 模式**漏报**,且会灾难性回溯
+   - `status` 现在**失败(exit 74)**并指名违规规则与文件,而不是报 OK;doctor 也报这个缺口
+   - `init` 自愈,且 preflight / autorefresh 走**同一个 helper** —— 它们此前会跑上游 init 并盖 marker 却**不做修复**,使"全新 clone 自愈"在真实流程里**不可达**
+   - 匹配不到任何 tracked 文件的规则**永不删除**;未跟踪文件仍被排除(原语义不变)
+
+2. **4 维人工验收闸干不了活 —— 四层独立失效,每一层都只有真机跑才看得见。**
+
+   - **(a)** 服务只把目标的 `successCriteria` 喂给模型,**一条证据都不给**,却要求它产出**带证据的裁决**。现在从磁盘收集真实证据(有界),并用**结构而非提示词措辞**保证:支撑源全部缺失的 `pass` 一律降级为 `inconclusive`
+   - **(b)** CLI 只能跑 `stub`;`--llm-provider anthropic` 现在真的构造 runner,`providerBinding` 如实上报
+   - **(c)** `maxTokens` 硬编码 3000,低于一份完整证据包所需,回复被**截在 JSON 中间**;预算随内联证据量伸缩,截断被诊断为"输出预算失败"而非"JSON 非法",并给出 `PEAKS_FINAL_REVIEW_MAX_OUTPUT_TOKENS` 逃生阀
+   - **(d)** 证据预算是**先到先得**,于是最后排序的源 —— 也就是四个维度里的一个 —— 被**永久饿死**;现在每个维度有保留配额
+
+   ⚠️ **`existing-functionality-intact` 仍然无法通过**:它要求的 `pre-post-diff` 产物**全仓没有任何生产者**。这是缺功能,不是 bug;已在 SKILL.md 记为**工具状态**,而**不是**把一个不相关的源重映射进去把闸弄绿。
+
+3. **同一个"闸门验代理而非性质"的形状,又抓到三处。**
+
+   - `handoff-auto-regen` 把 `sessionId` **写了两遍**,产出的 frontmatter 仓库自己的 YAML 解析器**拒绝** —— 而 `AUDIT_REQUIRES_HANDOFF` 只做**子串**检查,所以放行
+   - `sub-agent finalize --request-id` 扫会话目录下**所有** `.json`,读到 `active-dispatches.json` 就抛;两个分支现在都容忍坏记录,且 `--request-id` 与 `--batch` 共用**优先 queued** 的选择逻辑,并报出选了哪条、为何跳过其它
+   - `skills/peaks-final-review/SKILL.md` 断言它自己的 CLI "**尚不存在**",让调用方去手写 service 调用 —— 而它存在且已注册。这句话在本版开发中**真实地浪费了工作**:orchestrator 为一个早已存在的命令手写了一个调用脚本
+
+**验证**:三个版本常量一致(**4.0.44**);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **213 files / 2116 passed / 3 skipped / 0 failed**;`pnpm build` 的 `build-integrity` OK。
+
+**已知未修**:`existing-functionality-intact` 缺证据生产者(见第 2 条);`RUNTIME_NPM_VERSION`(0.0.21)与 internal-runtime 包版本已不同步(4.0.43 起即如此)。
+
 ## 4.0.43 — 2026-09-12 (一个从来拦不住东西的闸门 + 前端接口防腐层)
 
 **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.43 (2026-09-12) |
+| **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.44 (2026-09-12) |
 | **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.43(2026-09-12) |
+| **最新版本** | [![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.44(2026-09-12) |
 | **覆盖域** | 代码(`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/codegraph-commands.js

@@ -2,6 +2,8 @@ import { InvalidArgumentError } from 'commander';
 import { statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { createCodegraphInvocation, executeCodegraphInvocation, defaultCodegraphInitGuard, writeCodegraphMarker, writeCodegraphAffectedContext, CodegraphInitConflictError } from '../../services/codegraph/codegraph-service.js';
+import { CODEGRAPH_INTEGRITY_EXIT_CODE, inspectCodegraphExcludeIntegrity, isCodegraphExcludeConfigPresent, renderCodegraphExcludeIntegrityLines } from '../../services/codegraph/codegraph-exclude-integrity.js';
+import { repairCodegraphExcludeFromProject } from '../../services/codegraph/codegraph-exclude-repair.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
 function addPeaksJsonOption(command) {
@@ -61,6 +63,140 @@ async function runCodegraphCommand(io, command, options, asJson) {
         printCodegraphFailure(io, command, error, asJson);
     }
 }
+/**
+ * `--peaks-json` machine report for `status`. Carries the upstream
+ * result AND the peaks-loop integrity verdict as one JSON document so a
+ * CI job can gate on `data.integrity.gap` / `data.integrity.rulesToRemove`
+ * without scraping human text.
+ */
+async function runCodegraphStatusJson(io, options, integrity, integrityWarning) {
+    let result;
+    try {
+        result = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'status', project: options.project }));
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.status', error, true);
+        return;
+    }
+    const upstream = {
+        exitCode: result.exitCode,
+        stdout: rewriteBareCodegraphHints(result.stdout).trimEnd(),
+        stderr: redactSensitiveErrorMessage(rewriteBareCodegraphHints(result.stderr)).trimEnd()
+    };
+    const upstreamFailed = result.exitCode !== null && result.exitCode !== 0;
+    if (integrity?.gap === true) {
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_INCOMPLETE', `codegraph index is incomplete: ${integrity.excludedTrackedCount} of ${integrity.trackedSourceCount} tracked source files are excluded by ${integrity.rulesToRemove.length} rule(s).`, { upstream, integrity, integrityWarning }, ['Run `peaks codegraph repair-exclude --project <root>` to drop the offending rules and rebuild the index.']), true);
+    }
+    else if (upstreamFailed) {
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(upstream.stderr || upstream.stdout || `codegraph exited with code ${String(result.exitCode)}`), { upstream, integrity, integrityWarning }, ['Check the codegraph project path before retrying']), true);
+    }
+    else {
+        printResult(io, ok('codegraph.status', { upstream, integrity, integrityWarning }), true);
+    }
+    if (upstreamFailed) {
+        process.exitCode = result.exitCode ?? 1;
+    }
+}
+/**
+ * `peaks codegraph status` with an integrity gate.
+ *
+ * The upstream status is still proxied verbatim (that is what the
+ * command has always done), but a clean upstream "index is up to date"
+ * is no longer sufficient: when git-tracked source files are being
+ * excluded by the config, the command says so, names the rules and
+ * files, and exits non-zero.
+ *
+ * Read-only by construction — it imports the integrity inspector, never
+ * the repair writer. Fixing the config is `peaks codegraph init`
+ * (fresh) or `peaks codegraph repair-exclude` (explicit).
+ */
+async function runCodegraphStatusCommand(io, options, asJson) {
+    let integrity = null;
+    let integrityWarning = null;
+    const projectRoot = resolve(options.project);
+    try {
+        // Never initialized here → no exclude list is in play, so there is
+        // nothing to report. Staying silent keeps `status` honest and
+        // unchanged for projects that do not use codegraph at all.
+        integrity = isCodegraphExcludeConfigPresent(projectRoot)
+            ? inspectCodegraphExcludeIntegrity(projectRoot)
+            : null;
+    }
+    catch (error) {
+        // Not a git work tree, no config yet, malformed config — the
+        // upstream status is still worth printing, so degrade to a warning
+        // instead of failing the whole command.
+        integrityWarning = getErrorMessage(error);
+    }
+    if (asJson === true) {
+        await runCodegraphStatusJson(io, options, integrity, integrityWarning);
+    }
+    else {
+        await runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project });
+        if (integrityWarning !== null) {
+            io.stdout(`[WARN] codegraph exclude integrity not evaluated: ${integrityWarning}`);
+        }
+        else if (integrity !== null) {
+            for (const line of renderCodegraphExcludeIntegrityLines(integrity)) {
+                io.stdout(line);
+            }
+        }
+    }
+    if (integrity?.gap === true) {
+        process.exitCode = CODEGRAPH_INTEGRITY_EXIT_CODE;
+    }
+}
+/**
+ * Explicit repair path: reconcile → drop offending rules → back up the
+ * config → rebuild the index. Mirrors the automatic step `init` runs
+ * after a fresh upstream init, for workspaces that were already
+ * initialized before the integrity gate existed.
+ */
+async function runCodegraphRepairExcludeCommand(io, options, asJson) {
+    let projectRoot;
+    try {
+        const candidate = resolve(options.project);
+        if (!statSync(candidate).isDirectory()) {
+            throw new Error('Project path must exist and be a directory');
+        }
+        projectRoot = candidate;
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.repair-exclude', error, asJson);
+        return;
+    }
+    const report = await repairCodegraphExcludeFromProject(projectRoot);
+    // Where the notes go matters: `printResult` renders every `warnings`
+    // entry to stderr with a `warning: ` prefix, so a confirmation parked
+    // in the third slot reads as a problem — and a real warning parked
+    // there double-prefixes. Confirmations go to `nextActions`; only a
+    // genuine `report.warning` reaches `warnings`, verbatim.
+    const confirmations = [];
+    if (report.applied) {
+        confirmations.push(`Removed ${report.rulesRemoved.length} exclude rule(s), recovering ${report.filesRecovered} tracked source file(s). Config backed up to ${report.backupPath}.`);
+    }
+    else {
+        confirmations.push('No tracked source file is excluded by the codegraph config; nothing to repair.');
+    }
+    if (report.applied) {
+        confirmations.push('Re-run `peaks codegraph status --project <root>` to confirm the gap is closed.');
+    }
+    printResult(io, ok('codegraph.repair-exclude', {
+        applied: report.applied,
+        rulesRemoved: report.rulesRemoved,
+        filesRecovered: report.filesRecovered,
+        trackedSourceCount: report.trackedSourceCount,
+        configPath: report.configPath,
+        backupPath: report.backupPath,
+        reindexed: report.reindexed,
+        warning: report.warning
+    }, report.warning === null ? [] : [report.warning], confirmations), asJson);
+    // A repair that could not run to completion (or could not reindex)
+    // must not report success to a shell.
+    if (report.warning !== null) {
+        process.exitCode = 1;
+    }
+}
 /**
  * rid-CG-006 — init conflict guard. Resolves the project root and
  * probes `.codegraph/` for the peaks-loop marker before invoking the
@@ -92,7 +228,14 @@ async function runCodegraphInitCommand(io, options, asJson) {
             guard: guardOutcome.status,
             codegraphDir: guardOutcome.codegraphDir,
             markerPresent: true
-        }, [`.codegraph/ is already managed by peaks-loop; init is a no-op. Marker: ${guardOutcome.codegraphDir}/.peaks-loop-marker`], ['Run `peaks codegraph index` to (re)build the index without touching the schema.']), asJson);
+        }, 
+        // A no-op init is a SUCCESS. This message used to sit in the
+        // `warnings` slot and was therefore printed as
+        // `warning: .codegraph/ is already managed by peaks-loop...`.
+        [], [
+            `.codegraph/ is already managed by peaks-loop; init is a no-op. Marker: ${guardOutcome.codegraphDir}/.peaks-loop-marker`,
+            'Run `peaks codegraph index` to (re)build the index without touching the schema.'
+        ]), asJson);
         return;
     }
     if (guardOutcome.status === 'conflict-foreign-schema') {
@@ -110,8 +253,7 @@ async function runCodegraphInitCommand(io, options, asJson) {
     try {
         const invocation = createCodegraphInvocation({
             subcommand: 'init',
-            project: options.project,
-            ...(options.yes === true ? { yes: true } : {})
+            project: options.project
         });
         const result = await executeCodegraphInvocation(invocation);
         const didFail = result.exitCode !== null && result.exitCode !== 0;
@@ -137,7 +279,47 @@ async function runCodegraphInitCommand(io, options, asJson) {
         catch {
             // intentionally swallowed — surface as warning below
         }
-        printResult(io, ok('codegraph.init', { guard: guardOutcome.status, codegraphDir: guardOutcome.codegraphDir, markerWritten: true }, [], [`Stamped peaks-loop marker at ${guardOutcome.codegraphDir}/.peaks-loop-marker`]), asJson);
+        // Upstream `init` writes its 99-rule default `exclude` template,
+        // some of which collide with real source directories in this
+        // project. Left alone, a fresh clone / new machine gets an index
+        // that silently omits tracked source files while `status` says it
+        // is up to date. Reconcile now, drop the offending rules, and
+        // rebuild the index — a fresh init is the one moment this is both
+        // safe (nothing has been indexed yet) and necessary (`.codegraph/`
+        // is gitignored, so every clone starts from the default template).
+        //
+        // Never throws: a failure here is reported as a warning, not a
+        // failed init (the init itself already succeeded).
+        const excludeRepair = await repairCodegraphExcludeFromProject(projectRoot);
+        // These are confirmations, not warnings: `printResult` renders every
+        // `warnings` entry to stderr behind a `warning: ` prefix, so a fully
+        // successful init used to print a wall of `warning:` lines for what
+        // were plain success messages.
+        const initNotes = [
+            `Stamped peaks-loop marker at ${guardOutcome.codegraphDir}/.peaks-loop-marker`
+        ];
+        if (excludeRepair.applied) {
+            initNotes.push(`Removed ${excludeRepair.rulesRemoved.length} exclude rule(s) that blocked tracked source files, recovering ${excludeRepair.filesRecovered} file(s); config backed up to ${excludeRepair.backupPath}.`);
+            if (excludeRepair.reindexed) {
+                initNotes.push('Rebuilt the codegraph index over the recovered files.');
+            }
+        }
+        printResult(io, ok('codegraph.init', {
+            guard: guardOutcome.status,
+            codegraphDir: guardOutcome.codegraphDir,
+            markerWritten: true,
+            excludeRepair: {
+                applied: excludeRepair.applied,
+                rulesRemoved: excludeRepair.rulesRemoved,
+                filesRecovered: excludeRepair.filesRecovered,
+                reindexed: excludeRepair.reindexed,
+                backupPath: excludeRepair.backupPath,
+                warning: excludeRepair.warning
+            }
+        }, 
+        // Verbatim: `printResult` supplies the `warning: ` prefix, so a
+        // prefix added here would render as `warning: warning: ...`.
+        excludeRepair.warning === null ? [] : [excludeRepair.warning], initNotes), asJson);
     }
     catch (error) {
         printCodegraphFailure(io, 'codegraph.init', error, asJson);
@@ -211,8 +393,11 @@ async function runCodegraphAffectedCommand(io, files, options, asJson) {
 }
 export function registerCodegraphCommands(program, io) {
     const codegraph = program.command('codegraph').description('Run upstream codegraph commands through the Peaks launcher');
-    addProjectOption(codegraph.command('status').description('Show codegraph status')).action((options) => runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, options.peaksJson));
-    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project').option('--yes', 'answer yes to upstream prompts')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
+    addProjectOption(codegraph.command('status').description('Show codegraph status, including the exclude integrity gate')).action((options) => runCodegraphStatusCommand(io, options, options.peaksJson));
+    addProjectOption(codegraph
+        .command('repair-exclude')
+        .description('Drop codegraph exclude rules that block tracked source files, then rebuild the index')).action((options) => runCodegraphRepairExcludeCommand(io, options, options.peaksJson));
+    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
     addProjectOption(codegraph
         .command('index')
         .description('Index a project with codegraph')

package/dist/cli/commands/final-review-commands.d.ts

@@ -1,14 +1,21 @@
 /**
- * W5 Fix M2 — `peaks prepare-final-review <rid>` CLI wrapper.
+ * `peaks prepare-final-review <rid>` CLI wrapper (W5 Fix M2; real provider
+ * binding added by the S3 defect-remediation slice).
  *
- * Exposes the `prepareFinalReview()` service (added in W2 T9 on
+ * Exposes the `prepareFinalReview()` service (W2 T9 on
  * `feature/slice-topology-multipass`) via the CLI surface. The service
- * depends on an injected `LlmRunner`; this slice wires the CLI route
- * with a `stub` provider that returns a structured "scaffold ready"
- * envelope so CI can verify the route without a real LLM. A follow-up
- * slice will bind a real provider. Until then, non-stub providers fail
- * loudly with `LLM_PROVIDER_NOT_IMPLEMENTED` so callers cannot silently
- * no-op.
+ * depends on an injected `LlmRunner`; this file owns the binding:
+ *   - `--llm-provider stub` (default) returns a structured "scaffold ready"
+ *     envelope WITHOUT calling the service, so CI can verify the route
+ *     offline. It performs no review, and says so in every hint it emits.
+ *   - `--llm-provider anthropic` binds the real Messages-API runner
+ *     (`resolveAnthropicConfig()` + `createAnthropicRunner()`) and runs the
+ *     service for real, carrying the 4-dim result back in the envelope.
+ *     An absent credential or model raises `LlmBindingError`, reported under
+ *     its own error code — never degraded into a scaffold a caller could
+ *     mistake for a review.
+ * Unknown provider names still fail loudly with
+ * `LLM_PROVIDER_NOT_IMPLEMENTED` rather than silently falling back to stub.
  *
  * Per the dev-preference "Default-no on new CLI commands" rule and the
  * W4 T14 spec, this is a NEW top-level command (`prepare-final-review`),
@@ -19,13 +26,30 @@
  */
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-export type FinalReviewStatus = 'scaffold-only' | 'not-applicable';
+import type { FinalReviewOutput } from '../../services/final-review/final-review-types.js';
+export type FinalReviewStatus = 'scaffold-only' | 'review-complete' | 'not-applicable';
+/**
+ * Which LLM produced this envelope. `unknown` is reserved for failure
+ * envelopes, where no binding was ever established.
+ */
+export type FinalReviewProviderBinding = 'stub' | 'anthropic-messages-api' | 'unknown';
 export interface FinalReviewData {
     readonly status: FinalReviewStatus;
     readonly rid: string;
     readonly sessionId: string;
     readonly auditGoalPath: string;
     readonly serviceWired: boolean;
-    readonly providerBinding: 'pending-follow-up-slice' | 'unknown';
+    readonly providerBinding: FinalReviewProviderBinding;
+    /** Model id the bound provider answered with (real-provider runs only). */
+    readonly model?: string;
+    /** The 4-dim review the service produced (real-provider runs only). */
+    readonly review?: FinalReviewOutput;
+    /**
+     * Environment variables that were absent when binding failed. Surfaced on
+     * `data` because `fail()` redacts `message` through
+     * `redactSensitiveErrorMessage`, whose catch-all pattern matches the words
+     * `token` / `api_key` and would blank out the very names an operator needs.
+     */
+    readonly missingEnv?: readonly string[];
 }
 export declare function registerFinalReviewCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/final-review-commands.js

@@ -1,14 +1,21 @@
 /**
- * W5 Fix M2 — `peaks prepare-final-review <rid>` CLI wrapper.
+ * `peaks prepare-final-review <rid>` CLI wrapper (W5 Fix M2; real provider
+ * binding added by the S3 defect-remediation slice).
  *
- * Exposes the `prepareFinalReview()` service (added in W2 T9 on
+ * Exposes the `prepareFinalReview()` service (W2 T9 on
  * `feature/slice-topology-multipass`) via the CLI surface. The service
- * depends on an injected `LlmRunner`; this slice wires the CLI route
- * with a `stub` provider that returns a structured "scaffold ready"
- * envelope so CI can verify the route without a real LLM. A follow-up
- * slice will bind a real provider. Until then, non-stub providers fail
- * loudly with `LLM_PROVIDER_NOT_IMPLEMENTED` so callers cannot silently
- * no-op.
+ * depends on an injected `LlmRunner`; this file owns the binding:
+ *   - `--llm-provider stub` (default) returns a structured "scaffold ready"
+ *     envelope WITHOUT calling the service, so CI can verify the route
+ *     offline. It performs no review, and says so in every hint it emits.
+ *   - `--llm-provider anthropic` binds the real Messages-API runner
+ *     (`resolveAnthropicConfig()` + `createAnthropicRunner()`) and runs the
+ *     service for real, carrying the 4-dim result back in the envelope.
+ *     An absent credential or model raises `LlmBindingError`, reported under
+ *     its own error code — never degraded into a scaffold a caller could
+ *     mistake for a review.
+ * Unknown provider names still fail loudly with
+ * `LLM_PROVIDER_NOT_IMPLEMENTED` rather than silently falling back to stub.
  *
  * Per the dev-preference "Default-no on new CLI commands" rule and the
  * W4 T14 spec, this is a NEW top-level command (`prepare-final-review`),
@@ -21,8 +28,18 @@ import { existsSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
+import { createAnthropicRunner, LlmBindingError, LlmRequestError, resolveAnthropicConfig, } from '../../services/llm/anthropic-runner.js';
+import { IncompleteFinalReviewError, prepareFinalReview, } from '../../services/final-review/final-review-service.js';
 /** Whitelist of supported `--llm-provider` values for `peaks prepare-final-review`. */
-const SUPPORTED_LLM_PROVIDERS = ['stub'];
+const SUPPORTED_LLM_PROVIDERS = ['anthropic', 'stub'];
+/**
+ * Default stays `stub` (unlike `peaks audit goal`, whose default is the real
+ * provider): the scaffold route is what CI and the registered e2e contract
+ * exercise without credentials, and the stub envelope is labelled
+ * `status: 'scaffold-only'` / `providerBinding: 'stub'` so it can never be
+ * read as a review.
+ */
+const DEFAULT_LLM_PROVIDER = 'stub';
 function isSupportedLlmProvider(value) {
     return SUPPORTED_LLM_PROVIDERS.includes(value);
 }
@@ -32,7 +49,7 @@ function isSupportedLlmProvider(value) {
  * "this is a placeholder on a failure" apart from "this is a real
  * scaffold-only success".
  */
-function emptyFinalReviewData(rid, sessionId, auditGoalPath) {
+function emptyFinalReviewData(rid, sessionId, auditGoalPath, missingEnv) {
     return {
         status: 'not-applicable',
         rid,
@@ -40,6 +57,7 @@ function emptyFinalReviewData(rid, sessionId, auditGoalPath) {
         auditGoalPath,
         serviceWired: false,
         providerBinding: 'unknown',
+        ...(missingEnv === undefined ? {} : { missingEnv }),
     };
 }
 function validateProjectRoot(projectArg) {
@@ -95,7 +113,7 @@ export function registerFinalReviewCommands(program, io) {
         .description('Prepare the 4-dimension business review (final-review primitive) for human acceptance (W2 T9 service; CLI surface in W5 M2)')
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--session-id <sid>', 'session id whose .peaks/_runtime/<sid>/audit-goal/<rid>.json is the approved goal source')
-        .option('--llm-provider <name>', 'LLM provider name (default: stub)', 'stub')).action(async (rid, options) => {
+        .option('--llm-provider <name>', `LLM provider name: ${SUPPORTED_LLM_PROVIDERS.join(' | ')} (default: ${DEFAULT_LLM_PROVIDER} — performs no review)`, DEFAULT_LLM_PROVIDER)).action(async (rid, options) => {
         // 1. Project root must exist and be a directory.
         const projectValidation = validateProjectRoot(options.project);
         if (!projectValidation.ok) {
@@ -128,34 +146,112 @@ export function registerFinalReviewCommands(program, io) {
             process.exitCode = 1;
             return;
         }
-        // 5. Provider check: only `stub` is wired in this slice.
-        const provider = options.llmProvider ?? 'stub';
+        // 5. Provider check: unknown names fail loudly — a silent fallback to
+        //    `stub` would hand the caller a scaffold envelope that reads as a
+        //    review route, which is the defect class this gate exists to stop.
+        const provider = options.llmProvider ?? DEFAULT_LLM_PROVIDER;
         if (!isSupportedLlmProvider(provider)) {
-            printResult(io, fail('final-review.prepare', 'LLM_PROVIDER_NOT_IMPLEMENTED', `Provider '${provider}' is not yet wired. The CLI surface is in place; real provider binding is a follow-up slice. Use --llm-provider stub to validate the route without invoking the LLM.`, emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath), [
-                'Re-run with `--llm-provider stub` (default) to validate the route.',
-                'Real provider binding is tracked as a follow-up slice.',
+            printResult(io, fail('final-review.prepare', 'LLM_PROVIDER_NOT_IMPLEMENTED', `LLM provider "${provider}" is not implemented. Supported providers: ${SUPPORTED_LLM_PROVIDERS.join(', ')}.`, emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath), [
+                `Re-run with \`--llm-provider anthropic\` for a real 4-dim review, or \`--llm-provider ${DEFAULT_LLM_PROVIDER}\` for an offline scaffold.`,
             ]), options.json);
             process.exitCode = 1;
             return;
         }
         // 6. Stub path: surface a structured "scaffold ready" envelope.
-        //    We DO NOT call the service in this slice — the service depends
-        //    on an injected `LlmRunner` interface, and no real provider is
-        //    bound yet. The envelope confirms the route is wired end-to-end
-        //    and reports the audit-goal path the service WOULD read.
-        const data = {
-            status: 'scaffold-only',
-            rid,
-            sessionId: sessionValidation.sessionId,
-            auditGoalPath,
-            serviceWired: true,
-            providerBinding: 'pending-follow-up-slice',
-        };
-        const envelope = ok('final-review.prepare', data, [], [
-            'prepareFinalReview() service is wired and reachable. The stub provider returns a scaffold envelope so CI can verify the route without a real LLM.',
-            `Audit-goal file is present at: ${auditGoalPath}`,
-            'A follow-up slice will bind a real LLM provider; until then, non-stub providers fail loudly with `LLM_PROVIDER_NOT_IMPLEMENTED`.',
-        ]);
-        printResult(io, envelope, options.json);
+        //    We DO NOT call the service here — the stub runner answers the
+        //    audit-goal shape, not the 4-dim review shape, so running it through
+        //    `prepareFinalReview()` would only manufacture a malformed review.
+        //    The envelope confirms the route is wired end-to-end and reports the
+        //    audit-goal path the service WOULD read.
+        if (provider === 'stub') {
+            const data = {
+                status: 'scaffold-only',
+                rid,
+                sessionId: sessionValidation.sessionId,
+                auditGoalPath,
+                serviceWired: true,
+                providerBinding: 'stub',
+            };
+            const envelope = ok('final-review.prepare', data, [], [
+                'Stub provider: no 4-dim review was performed. This envelope only proves the route is wired and reachable.',
+                `Audit-goal file is present at: ${auditGoalPath}`,
+                'Re-run with `--llm-provider anthropic` to produce a real review.',
+            ]);
+            printResult(io, envelope, options.json);
+            return;
+        }
+        // 7. Real provider path: bind a real `LlmRunner` and run the service.
+        //    Binding happens INSIDE the try so an absent credential surfaces as
+        //    `LlmBindingError`'s own code instead of escaping as a crash. No
+        //    envelope is emitted on that path — a "successful" empty review would
+        //    be worse than an error.
+        try {
+            const config = resolveAnthropicConfig();
+            const llmRunner = createAnthropicRunner(config);
+            const review = await prepareFinalReview(rid, {
+                projectRoot: projectValidation.projectRoot,
+                sessionId: sessionValidation.sessionId,
+                llmRunner,
+            });
+            const data = {
+                status: 'review-complete',
+                rid,
+                sessionId: sessionValidation.sessionId,
+                auditGoalPath,
+                serviceWired: true,
+                providerBinding: 'anthropic-messages-api',
+                model: config.model,
+                review,
+            };
+            const envelope = ok('final-review.prepare', data, review.allPass ? [] : [
+                `Dimensions needing human attention: ${review.needsAttention.join(', ') || 'none flagged'}.`,
+            ], [
+                `4-dim review produced by anthropic-messages-api (model: ${config.model}).`,
+                `allPass: ${String(review.allPass)}.`,
+            ]);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            const code = finalReviewErrorCode(error);
+            printResult(io, fail('final-review.prepare', code, getErrorMessage(error), emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath, error instanceof LlmBindingError ? error.missingEnv : undefined), finalReviewNextActions(code)), options.json);
+            process.exitCode = 1;
+        }
     });
 }
+/**
+ * Map a thrown error to the CLI's error code. The LLM-layer errors already
+ * carry codes precise enough to act on (`LLM_CREDENTIAL_MISSING`,
+ * `LLM_REQUEST_FAILED`, …), so they are passed through rather than flattened
+ * into one opaque failure.
+ */
+function finalReviewErrorCode(error) {
+    if (error instanceof LlmBindingError ||
+        error instanceof LlmRequestError ||
+        error instanceof IncompleteFinalReviewError) {
+        return error.code;
+    }
+    return 'FINAL_REVIEW_FAILED';
+}
+function finalReviewNextActions(code) {
+    switch (code) {
+        case 'LLM_CREDENTIAL_MISSING':
+            return [
+                'Export ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY) in the environment that launches peaks, then re-run.',
+                'For an offline scaffold instead of a review, re-run with `--llm-provider stub` — it performs NO review.',
+            ];
+        case 'LLM_MODEL_MISSING':
+            return [
+                'Export ANTHROPIC_MODEL (or CLAUDE_CODE_SUBAGENT_MODEL) in the environment that launches peaks, then re-run.',
+            ];
+        case 'LLM_REQUEST_FAILED':
+            return [
+                'Check ANTHROPIC_BASE_URL and network reachability, then re-run — a transport failure produces no review.',
+            ];
+        case 'INCOMPLETE_FINAL_REVIEW':
+            return [
+                'The LLM reply was not valid JSON or omitted a required dimension; re-run so the gate is never read as complete.',
+            ];
+        default:
+            return ['Re-run with `--llm-provider stub` to validate the CLI route without a real LLM.'];
+    }
+}

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

@@ -12,6 +12,55 @@
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * A `dispatch-*.json` candidate for `finalize --request-id`, as read off disk.
+ * The record's own `createdAt` is carried as the recency key — NOT the file's
+ * mtime, which any heartbeat or finalize rewrites, so a `done` record can look
+ * newer than the `queued` one that superseded it. Keeping the key on the
+ * candidate makes the selection rule a pure function of the records and
+ * testable without a filesystem.
+ */
+export interface FinalizeCandidate {
+    readonly recordPath: string;
+    readonly requestId: string;
+    readonly status: string;
+    readonly createdAt: string;
+}
+/**
+ * What `--request-id` actually did, reported in the envelope. N3: the branch
+ * used to resolve silently and could not say WHY a record was or was not the
+ * one finalized.
+ */
+export interface FinalizeSelection {
+    readonly requestId: string;
+    readonly rule: string;
+    readonly matched: number;
+    readonly chosen: string | null;
+    readonly rejected: readonly {
+        readonly recordPath: string;
+        readonly status: string;
+        readonly reason: string;
+    }[];
+}
+/** The one selection rule `--request-id` and `--batch` now share. */
+export declare const FINALIZE_SELECTION_RULE: string;
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * (this session holds six records for `2026-09-12-defect-remediation`) it
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export declare function selectFinalizeTarget(candidates: readonly FinalizeCandidate[]): FinalizeCandidate | null;
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export declare function describeFinalizeRejection(candidate: FinalizeCandidate, chosen: FinalizeCandidate | null): string;
 export declare function registerShareCommand(parent: Command, io: ProgramIO): void;
 export declare function registerSharedReadCommand(parent: Command, io: ProgramIO): void;
 export declare function registerAwaitCommand(parent: Command, io: ProgramIO): void;