peaks-loop 4.1.2 → 4.1.4

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

@@ -0,0 +1,52 @@
+import type { FinalReviewOutput } from '../../services/final-review/final-review-types.js';
+/** Whitelist of supported `--llm-provider` values for `peaks prepare-final-review`. */
+export declare const SUPPORTED_LLM_PROVIDERS: readonly ["anthropic", "stub"];
+export type SupportedLlmProvider = (typeof SUPPORTED_LLM_PROVIDERS)[number];
+/**
+ * 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.
+ */
+export declare const DEFAULT_LLM_PROVIDER: SupportedLlmProvider;
+export declare function isSupportedLlmProvider(value: string): value is SupportedLlmProvider;
+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: 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[];
+}
+/**
+ * Empty placeholder used by `fail()` envelopes. `status` is
+ * `'not-applicable'` on the error path so consumers can tell
+ * "this is a placeholder on a failure" apart from "this is a real
+ * scaffold-only success".
+ */
+export declare function emptyFinalReviewData(rid: string, sessionId: string, auditGoalPath: string, missingEnv?: readonly string[]): FinalReviewData;
+export type PrepareFinalReviewOptions = {
+    project: string;
+    sessionId: string;
+    llmProvider?: string;
+    base?: string;
+    json?: boolean;
+};

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

@@ -0,0 +1,35 @@
+// src/cli/commands/final-review-command-shared.ts
+//
+// What `peaks prepare-final-review` reports: the envelope's data shape, its
+// provider vocabulary, and the placeholder a failure carries. Split out of
+// `final-review-commands.ts`; every value and every field name is unchanged.
+/** Whitelist of supported `--llm-provider` values for `peaks prepare-final-review`. */
+export 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.
+ */
+export const DEFAULT_LLM_PROVIDER = 'stub';
+export function isSupportedLlmProvider(value) {
+    return SUPPORTED_LLM_PROVIDERS.includes(value);
+}
+/**
+ * Empty placeholder used by `fail()` envelopes. `status` is
+ * `'not-applicable'` on the error path so consumers can tell
+ * "this is a placeholder on a failure" apart from "this is a real
+ * scaffold-only success".
+ */
+export function emptyFinalReviewData(rid, sessionId, auditGoalPath, missingEnv) {
+    return {
+        status: 'not-applicable',
+        rid,
+        sessionId,
+        auditGoalPath,
+        serviceWired: false,
+        providerBinding: 'unknown',
+        ...(missingEnv === undefined ? {} : { missingEnv })
+    };
+}

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

@@ -4,7 +4,8 @@
  *
  * Exposes the `prepareFinalReview()` service (W2 T9 on
  * `feature/slice-topology-multipass`) via the CLI surface. The service
- * depends on an injected `LlmRunner`; this file owns the binding:
+ * depends on an injected `LlmRunner`; the binding lives in
+ * `final-review-prepare-command.ts`:
  *   - `--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.
@@ -23,33 +24,12 @@
  *   - `peaks audit goal`   — propose a 6-dim goal from a human need
  *   - `peaks prepare-final-review` — produce a 4-dim review evidence
  *                                  pack for human acceptance
+ *
+ * This file is the registration module only; the run body it dispatches to
+ * lives in `final-review-prepare-command.ts` and the envelope vocabulary in
+ * `final-review-command-shared.ts`.
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-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: 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;
+export { emptyFinalReviewData, isSupportedLlmProvider, type FinalReviewData, type FinalReviewProviderBinding, type FinalReviewStatus, type PrepareFinalReviewOptions } from './final-review-command-shared.js';

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

@@ -4,7 +4,8 @@
  *
  * Exposes the `prepareFinalReview()` service (W2 T9 on
  * `feature/slice-topology-multipass`) via the CLI surface. The service
- * depends on an injected `LlmRunner`; this file owns the binding:
+ * depends on an injected `LlmRunner`; the binding lives in
+ * `final-review-prepare-command.ts`:
  *   - `--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.
@@ -23,91 +24,14 @@
  *   - `peaks audit goal`   — propose a 6-dim goal from a human need
  *   - `peaks prepare-final-review` — produce a 4-dim review evidence
  *                                  pack for human acceptance
+ *
+ * This file is the registration module only; the run body it dispatches to
+ * lives in `final-review-prepare-command.ts` and the envelope vocabulary in
+ * `final-review-command-shared.ts`.
  */
-import { existsSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { REQUEST_ID_PATTERN } from '../../services/artifacts/request-artifact-service.js';
-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 = ['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);
-}
-/**
- * Empty placeholder used by `fail()` envelopes. `status` is
- * `'not-applicable'` on the error path so consumers can tell
- * "this is a placeholder on a failure" apart from "this is a real
- * scaffold-only success".
- */
-function emptyFinalReviewData(rid, sessionId, auditGoalPath, missingEnv) {
-    return {
-        status: 'not-applicable',
-        rid,
-        sessionId,
-        auditGoalPath,
-        serviceWired: false,
-        providerBinding: 'unknown',
-        ...(missingEnv === undefined ? {} : { missingEnv })
-    };
-}
-function validateProjectRoot(projectArg) {
-    const projectRoot = resolve(projectArg);
-    if (!existsSync(projectRoot)) {
-        return {
-            ok: false,
-            code: 'PROJECT_NOT_FOUND',
-            message: `project path does not exist: ${projectArg}`
-        };
-    }
-    let stat;
-    try {
-        stat = statSync(projectRoot);
-    }
-    catch (error) {
-        return { ok: false, code: 'INVALID_PROJECT', message: getErrorMessage(error) };
-    }
-    if (!stat.isDirectory()) {
-        return {
-            ok: false,
-            code: 'INVALID_PROJECT',
-            message: `project path is not a directory: ${projectArg}`
-        };
-    }
-    return { ok: true, projectRoot };
-}
-/**
- * Validate the session id. Rejects empty, path-traversal (`..`), and
- * any segment separator (`/`, `\`) so the caller cannot escape
- * `.peaks/_runtime/<sessionId>/audit-goal/` via CLI flags.
- */
-function validateSessionId(sessionId) {
-    if (sessionId.length === 0) {
-        return {
-            ok: false,
-            code: 'MISSING_REQUIRED_FLAG',
-            message: '`--session-id` is required and must be a non-empty string'
-        };
-    }
-    if (sessionId.includes('..') || sessionId.includes('/') || sessionId.includes('\\')) {
-        return {
-            ok: false,
-            code: 'INVALID_SESSION_ID',
-            message: '`--session-id` must not contain path-traversal or path-separator characters (rejected: "..", "/", "\\")'
-        };
-    }
-    return { ok: true, sessionId };
-}
+import { addJsonOption } from '../cli-helpers.js';
+import { DEFAULT_LLM_PROVIDER, SUPPORTED_LLM_PROVIDERS } from './final-review-command-shared.js';
+import { runPrepareFinalReview } from './final-review-prepare-command.js';
 export function registerFinalReviewCommands(program, io) {
     addJsonOption(program
         .command('prepare-final-review <rid>')
@@ -115,159 +39,8 @@ export function registerFinalReviewCommands(program, io) {
         .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: ${SUPPORTED_LLM_PROVIDERS.join(' | ')} (default: ${DEFAULT_LLM_PROVIDER} — performs no review)`, DEFAULT_LLM_PROVIDER)
-        .option('--base <ref>', 'base ref for the pre/post baseline diff (`existing-functionality-intact`); default: merge-base with origin/HEAD, then origin/main, then origin/master, then HEAD~1 — pass this explicitly when none of those resolve')).action(async (rid, options) => {
-        // 1. Project root must exist and be a directory.
-        const projectValidation = validateProjectRoot(options.project);
-        if (!projectValidation.ok) {
-            printResult(io, fail('final-review.prepare', projectValidation.code, projectValidation.message, emptyFinalReviewData(rid, options.sessionId, ''), ['Verify the project path exists and is a directory']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        // 2. Session id must be a safe single-segment string.
-        const sessionValidation = validateSessionId(options.sessionId);
-        if (!sessionValidation.ok) {
-            printResult(io, fail('final-review.prepare', sessionValidation.code, sessionValidation.message, emptyFinalReviewData(rid, options.sessionId, ''), [
-                'Pass a non-empty `--session-id` whose value is a single segment (no "..", "/", or "\\")'
-            ]), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        // 3. Compute the audit-goal path the service WOULD read. We do this
-        //    in two places: the pre-flight existence check (here) and the
-        //    stub-path envelope (below). The service computes it identically
-        //    at `src/services/final-review/final-review-service.ts:45-52`.
-        //
-        //    Rid axis. The rid is the CLI positional and it is the FILENAME
-        //    segment below, so it is checked here, at the join. Added 2026-09-14
-        //    (repair R1): this join was a second-slot hole — the `--session-id`
-        //    validation above passed and the rid slot escaped. Found by the
-        //    widened rule D, not by a human reading the file.
-        if (!REQUEST_ID_PATTERN.test(rid)) {
-            printResult(io, fail('final-review.prepare', 'RID_INVALID', `Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`, emptyFinalReviewData(rid, options.sessionId, ''), ['Pass the rid of the slice, e.g. 2026-09-14-some-slug']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        const auditGoalPath = join(projectValidation.projectRoot, '.peaks', '_runtime', sessionValidation.sessionId, 'audit-goal', `${rid}.json`);
-        // 4. Pre-flight: if the audit-goal file is missing, surface a 404
-        //    BEFORE the stub/provider check so the caller learns the real
-        //    reason their request can't proceed.
-        if (!existsSync(auditGoalPath)) {
-            printResult(io, fail('final-review.prepare', 'AUDIT_GOAL_NOT_FOUND', `audit-goal file not found at expected path: ${auditGoalPath}`, emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath), [
-                'Run `peaks audit goal --project <path> --need <text>` first to produce the approved goal JSON.',
-                'Confirm `--session-id` matches the session that wrote the goal.'
-            ]), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        // 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', `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 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,
-                ...(options.base === undefined ? {} : { baseRef: options.base })
-            });
-            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.'];
-    }
+        .option('--base <ref>', 'base ref for the pre/post baseline diff (`existing-functionality-intact`); default: merge-base with origin/HEAD, then origin/main, then origin/master, then HEAD~1 — pass this explicitly when none of those resolve')).action((rid, options) => runPrepareFinalReview(rid, options, io));
 }
+// Re-export for tests / external consumers: the envelope vocabulary and the
+// types this command's surface is documented with.
+export { emptyFinalReviewData, isSupportedLlmProvider } from './final-review-command-shared.js';

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

@@ -0,0 +1,3 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type PrepareFinalReviewOptions } from './final-review-command-shared.js';
+export declare function runPrepareFinalReview(rid: string, options: PrepareFinalReviewOptions, io: ProgramIO): Promise<void>;

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

@@ -0,0 +1,200 @@
+// src/cli/commands/final-review-prepare-command.ts
+//
+// The body of `peaks prepare-final-review`: the two input validations, the
+// audit-goal path resolution, the provider check, the stub scaffold route and
+// the real-provider route. Split out of `final-review-commands.ts`; every
+// envelope code, message, `data` field and next-action string is unchanged.
+//
+// The input validations and the `_runtime` join below live in ONE module on
+// purpose: rule D is file-scoped, so a join whose id slot is checked two
+// modules away is a join the guard cannot see.
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { REQUEST_ID_PATTERN } from '../../services/artifacts/request-artifact-service.js';
+import { createAnthropicRunner, LlmBindingError, resolveAnthropicConfig } from '../../services/llm/anthropic-runner.js';
+import { prepareFinalReview } from '../../services/final-review/final-review-service.js';
+import { getErrorMessage } from '../cli-helpers.js';
+import { DEFAULT_LLM_PROVIDER, isSupportedLlmProvider, SUPPORTED_LLM_PROVIDERS } from './final-review-command-shared.js';
+import { emitPrepareFailure, emitReviewEnvelope, emitStubEnvelope, finalReviewErrorCode, finalReviewNextActions } from './final-review-command-envelopes.js';
+function validateProjectRoot(projectArg) {
+    const projectRoot = resolve(projectArg);
+    if (!existsSync(projectRoot)) {
+        return {
+            ok: false,
+            code: 'PROJECT_NOT_FOUND',
+            message: `project path does not exist: ${projectArg}`
+        };
+    }
+    let stat;
+    try {
+        stat = statSync(projectRoot);
+    }
+    catch (error) {
+        return { ok: false, code: 'INVALID_PROJECT', message: getErrorMessage(error) };
+    }
+    if (!stat.isDirectory()) {
+        return {
+            ok: false,
+            code: 'INVALID_PROJECT',
+            message: `project path is not a directory: ${projectArg}`
+        };
+    }
+    return { ok: true, projectRoot };
+}
+/**
+ * Validate the session id. Rejects empty, path-traversal (`..`), and
+ * any segment separator (`/`, `\`) so the caller cannot escape
+ * `.peaks/_runtime/<sessionId>/audit-goal/` via CLI flags.
+ */
+function validateSessionId(sessionId) {
+    if (sessionId.length === 0) {
+        return {
+            ok: false,
+            code: 'MISSING_REQUIRED_FLAG',
+            message: '`--session-id` is required and must be a non-empty string'
+        };
+    }
+    if (sessionId.includes('..') || sessionId.includes('/') || sessionId.includes('\\')) {
+        return {
+            ok: false,
+            code: 'INVALID_SESSION_ID',
+            message: '`--session-id` must not contain path-traversal or path-separator characters (rejected: "..", "/", "\\")'
+        };
+    }
+    return { ok: true, sessionId };
+}
+/** The refusal for an audit goal the pre-flight did not find on disk. */
+function auditGoalMissingRefusal(rid, sessionId, auditGoalPath) {
+    return {
+        rid,
+        code: 'AUDIT_GOAL_NOT_FOUND',
+        message: `audit-goal file not found at expected path: ${auditGoalPath}`,
+        sessionId,
+        auditGoalPath,
+        nextActions: [
+            'Run `peaks audit goal --project <path> --need <text>` first to produce the approved goal JSON.',
+            'Confirm `--session-id` matches the session that wrote the goal.'
+        ]
+    };
+}
+/**
+ * Resolve the audit-goal path, or the refusal that replaces it.
+ *
+ * The `rid` axis is checked HERE, at the join: the rid is the CLI positional
+ * and it is the FILENAME segment, so the `--session-id` validation does not
+ * cover it (added 2026-09-14, repair R1 — a second-slot hole, found by the
+ * widened rule D rather than by a human reading the file).
+ *
+ * The audit-goal existence pre-flight sits here too, so the caller learns the
+ * real reason its request cannot proceed BEFORE the provider check.
+ */
+function resolveAuditGoalPath(rid, options, projectRoot) {
+    const sessionValidation = validateSessionId(options.sessionId);
+    if (!sessionValidation.ok) {
+        return {
+            rid,
+            code: sessionValidation.code,
+            message: sessionValidation.message,
+            sessionId: options.sessionId,
+            auditGoalPath: '',
+            nextActions: [
+                'Pass a non-empty `--session-id` whose value is a single segment (no "..", "/", or "\\")'
+            ]
+        };
+    }
+    if (!REQUEST_ID_PATTERN.test(rid)) {
+        return {
+            rid,
+            code: 'RID_INVALID',
+            message: `Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`,
+            sessionId: sessionValidation.sessionId,
+            auditGoalPath: '',
+            nextActions: ['Pass the rid of the slice, e.g. 2026-09-14-some-slug']
+        };
+    }
+    const auditGoalPath = join(projectRoot, '.peaks', '_runtime', sessionValidation.sessionId, 'audit-goal', `${rid}.json`);
+    if (!existsSync(auditGoalPath)) {
+        return auditGoalMissingRefusal(rid, sessionValidation.sessionId, auditGoalPath);
+    }
+    return { projectRoot, sessionId: sessionValidation.sessionId, auditGoalPath };
+}
+/** Resolve the three inputs the run needs, or the refusal that replaces them. */
+function resolvePrepareInputs(rid, options) {
+    const projectValidation = validateProjectRoot(options.project);
+    if (!projectValidation.ok) {
+        return {
+            rid,
+            code: projectValidation.code,
+            message: projectValidation.message,
+            sessionId: options.sessionId,
+            auditGoalPath: '',
+            nextActions: ['Verify the project path exists and is a directory']
+        };
+    }
+    return resolveAuditGoalPath(rid, options, projectValidation.projectRoot);
+}
+function isRefusal(value) {
+    return !('projectRoot' in value);
+}
+/**
+ * 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.
+ */
+async function runRealReview(io, rid, inputs, options) {
+    const { json } = options;
+    try {
+        const config = resolveAnthropicConfig();
+        const llmRunner = createAnthropicRunner(config);
+        const review = await prepareFinalReview(rid, {
+            projectRoot: inputs.projectRoot,
+            sessionId: inputs.sessionId,
+            llmRunner,
+            ...(options.base === undefined ? {} : { baseRef: options.base })
+        });
+        emitReviewEnvelope(io, { rid, goal: inputs, model: config.model, review, json });
+    }
+    catch (error) {
+        const code = finalReviewErrorCode(error);
+        emitPrepareFailure(io, json, {
+            rid,
+            code,
+            message: getErrorMessage(error),
+            sessionId: inputs.sessionId,
+            auditGoalPath: inputs.auditGoalPath,
+            nextActions: finalReviewNextActions(code)
+        }, error instanceof LlmBindingError ? error.missingEnv : undefined);
+    }
+}
+export async function runPrepareFinalReview(rid, options, io) {
+    const inputs = resolvePrepareInputs(rid, options);
+    if (isRefusal(inputs)) {
+        emitPrepareFailure(io, options.json, inputs);
+        return;
+    }
+    // Unknown provider 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)) {
+        emitPrepareFailure(io, options.json, {
+            rid,
+            code: 'LLM_PROVIDER_NOT_IMPLEMENTED',
+            message: `LLM provider "${provider}" is not implemented. Supported providers: ${SUPPORTED_LLM_PROVIDERS.join(', ')}.`,
+            sessionId: inputs.sessionId,
+            auditGoalPath: inputs.auditGoalPath,
+            nextActions: [
+                `Re-run with \`--llm-provider anthropic\` for a real 4-dim review, or \`--llm-provider ${DEFAULT_LLM_PROVIDER}\` for an offline scaffold.`
+            ]
+        });
+        return;
+    }
+    if (provider === 'stub') {
+        emitStubEnvelope(io, rid, inputs, options.json);
+        return;
+    }
+    await runRealReview(io, rid, inputs, options);
+}

package/dist/cli/commands/finalize-accumulator.d.ts

@@ -0,0 +1,44 @@
+import type { DispatchRecord } from '../../services/dispatch/dispatch-record-writer.js';
+import type { FinalizeSelection } from './finalize-selection.js';
+interface FinalizedEntry {
+    recordPath: string;
+    requestId: string;
+    status: string;
+}
+interface SkippedEntry {
+    recordPath: string;
+    reason: string;
+}
+interface FailedEntry {
+    recordPath: string;
+    error: string;
+}
+/** The sweep's three counters, threaded explicitly instead of closed over. */
+export interface FinalizeAccumulator {
+    readonly finalized: FinalizedEntry[];
+    readonly skipped: SkippedEntry[];
+    readonly errors: FailedEntry[];
+}
+export interface MappedOutcome {
+    readonly status: 'done' | 'failed' | 'cancelled';
+    readonly outcome: 'success' | 'failed' | 'cancelled';
+}
+export declare const OUTCOME_MAP: Record<string, MappedOutcome>;
+export declare function makeAccumulator(): FinalizeAccumulator;
+/**
+ * N2 — one unreadable record must not abort the sweep.
+ *
+ * Skipping `active-dispatches.json` and `batch-*.counter.json` by FILENAME
+ * removed the two non-record files that happened to be in the directory, but a
+ * single stale or foreign `dispatch-*.json` (an old `version`, hand-edited
+ * JSON, a truncated write) still made `readRecord` throw from OUTSIDE any
+ * try/catch — and the throw escaped to the action's outer handler, so
+ * `--request-id` AND `--batch` both died with `FINALIZE_ERROR` and exit 1
+ * without touching a single healthy record.
+ *
+ * A record that cannot be read is now reported in `errors[]` and skipped;
+ * every other record is processed as before.
+ */
+export declare function tryReadRecord(recordPath: string, readRecord: (recordPath: string) => DispatchRecord, acc: FinalizeAccumulator): DispatchRecord | null;
+export declare function buildFinalizeHints(acc: FinalizeAccumulator, selection: FinalizeSelection | null): string[];
+export {};