peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/dispatch-from-dag.js

@@ -1,283 +1,113 @@
 /**
+ * The `--from-dag` path of `peaks sub-agent dispatch`.
  *
- * Pulled out of `dispatch-commands.ts` to honor the 800-line file cap
- * (Karpathy #2 Simplicity First). The single-dispatch action stays in
- * `dispatch-commands.ts`; the DAG-dispatch path lives here because the
- * two paths share no logic — the warm-path single dispatch does NOT
- * load slice-dag / dag-orchestrator / contract-store (slice 9 perf),
- * while the --from-dag codepath loads all three on first call.
+ * Pulled out of `dispatch-commands.ts` to honor the file-size cap (Karpathy #2
+ * Simplicity First). The single-dispatch action stays in `dispatch-commands.ts`;
+ * the DAG-dispatch path lives here because the two share no logic — the
+ * warm-path single dispatch does NOT load slice-dag / dag-orchestrator /
+ * contract-store (slice 9 perf), while the `--from-dag` codepath loads all
+ * three on first call.
  *
- * 2.7.0 slice-dag-dispatcher MVP: read a SliceDag from a file and run
- * it through `runDag`. The orchestrator's `runSlice` is a thin wrapper
- * that emits the per-IDE `buildToolCall` envelope for each topological
- * level.
+ * 2.7.0 slice-dag-dispatcher MVP: read a SliceDag from a file and run it
+ * through `runLayeredDag`. The orchestrator's `runSlice` is a thin wrapper
+ * that emits the per-IDE `buildToolCall` envelope for each topological level.
  *
  * 1.2 MVP scope: this dispatches the FIRST topological level synchronously
- * (returns the dispatch specs); subsequent levels are not surfaced in
- * the CLI envelope because the LLM-side runner must actually execute
- * each `buildToolCall` and write the resulting contract before level 2+
- * can be safely auto-advanced. The LLM re-invokes
- * `peaks sub-agent dispatch --from-dag <file> --batch-id <id>` after
- * writing level-1 contracts, which causes runDag to plan level 2+ with
- * the level-1 ancestor contracts spliced into their dispatch prompts.
+ * (returns the dispatch specs); subsequent levels are not surfaced in the CLI
+ * envelope because the LLM-side runner must actually execute each
+ * `buildToolCall` and write the resulting contract before level 2+ can be
+ * safely auto-advanced. The LLM re-invokes `peaks sub-agent dispatch --from-dag
+ * <file> --batch-id <id>` after writing level-1 contracts, which causes
+ * `runLayeredDag` to plan level 2+ with the level-1 ancestor contracts spliced
+ * into their dispatch prompts.
  *
- * Internally, runDag DOES iterate all levels so its join-barrier +
- * cancel-on-fail path is exercised end-to-end during the MVP emit; only
- * the CLI envelope is filtered to level-1 toolCalls (see `firstLevelIds`).
+ * Internally, `runLayeredDag` DOES iterate all levels so its join-barrier +
+ * cancel-on-fail path is exercised end-to-end during the MVP emit; only the
+ * CLI envelope is filtered to level-1 toolCalls (see `firstLevelIds`).
  */
-import { randomUUID } from 'node:crypto';
 import { printResult } from '../cli-helpers.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { detectInstalledIde } from '../../services/ide/ide-detector.js';
-import { getAdapter } from '../../services/ide/ide-registry.js';
-import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
-import { planFileOverlapWaves } from '../../services/dispatch/file-overlap-wave-planner.js';
+import { buildDagSuccessEnvelope } from './dispatch-dag-envelope.js';
+import { emitDagFailure } from './dispatch-dag-failure.js';
+import { assertGraphNodesMapped, loadDagRuntime, readDagOrFail, resolveDagIds, topologicalLevelsOrFail } from './dispatch-dag-preflight.js';
+import { makeCliRunner, makeNoopWriter, planFirstLevelWaves, resolveDagDispatcher } from './dispatch-dag-runners.js';
 export async function runDispatchFromDag(role, options, asJson, io) {
     if (!options.fromDag)
         return;
-    const projectRoot = options.project ?? process.cwd();
-    // Auto-resolve sid from .peaks/_runtime/session.json before falling back.
-    const sid = options.sessionId ??
-        process.env.PEAKS_SESSION_ID ??
-        getCurrentSessionId(projectRoot) ??
-        'unknown-sid';
-    const rid = options.requestId ?? 'unknown-rid';
-    const batchId = options.batchId ?? randomUUID();
-    // Slice 9 (dispatch CLI latency): the --from-dag codepath loads three
-    // heavy modules (slice-dag, dag-orchestrator, contract-store) that
-    // transitively import 10+ more services. They are NOT touched by the
-    // warm-path single-dispatch action, so we lazy-load them here only
-    // when --from-dag is actually requested. The dynamic-import promise
-    // resolves on first call, then ESM caches the module for subsequent
-    // calls in the same process.
-    const [{ readFileSync }, sliceDagMod, dagOrchestratorMod, contractStoreMod] = await Promise.all([
-        import('node:fs'),
-        import('../../services/dispatch/slice-dag.js'),
-        import('../../services/code/dag-orchestrator.js'),
-        import('../../services/dispatch/contract-store.js')
-    ]);
-    const { validateDag, topologicalLevels, isSliceComplexity } = sliceDagMod;
-    const { runLayeredDag } = dagOrchestratorMod;
-    const { listContracts, hashContract } = contractStoreMod;
-    let dag;
-    try {
-        const raw = readFileSync(options.fromDag, 'utf8');
-        const parsed = JSON.parse(raw);
-        validateDag(parsed);
-        dag = parsed;
-    }
-    catch (err) {
-        printResult(io, fail('sub-agent.dispatch', 'INVALID_DAG', `failed to read or validate DAG from ${options.fromDag}: ${err.message}`, { role, toolCall: null, dispatchRecordPath: null }, [
-            'Check the JSON file at the given path; the DAG must have {nodes, edges} and pass validateDag().'
-        ]), asJson);
-        process.exitCode = 1;
+    const scope = { role, asJson, io };
+    const ids = resolveDagIds(options);
+    const runtime = await loadDagRuntime();
+    const dag = readDagOrFail(runtime, options.fromDag, scope);
+    if (dag === null)
         return;
-    }
-    // Slice 4.0.8 RD §4 D4c: each DAG node must map to an explicitly
-    // prepared workflow graph node before sub-agent dispatch. Reject
-    // unmapped nodes with PEAKS_GRAPH_NODE_REQUIRED. The mapping is
-    // carried via the `graphNode` annotation on each DAG node, OR — as
-    // a back-compat fallback for DAGs without the annotation — the
-    // DAG node id itself is treated as the graph node id. Either way,
-    // the graph node must be prepared (RD §3 D4c) before the dispatch
-    // CLI runs.
-    for (const node of dag.nodes) {
-        const graphNodeId = node.graphNode;
-        const candidate = typeof graphNodeId === 'string' && graphNodeId.length > 0 ? graphNodeId : node.id;
-        if (typeof candidate !== 'string' || candidate.length === 0) {
-            printResult(io, fail('sub-agent.dispatch', 'PEAKS_GRAPH_NODE_REQUIRED', `DAG node ${node.id} has no graph-node mapping (RD §4 D4c)`, { role, toolCall: null, dispatchRecordPath: null, dagNodeId: node.id }, [
-                'Annotate the DAG node with `graphNode: "<id>"` so each dispatch can bind a prepared graph node.'
-            ]), asJson);
-            process.exitCode = 1;
-            return;
-        }
-    }
-    // MVP (1.2): the orchestrator iterates topological levels + join
-    // barrier + cancel-on-fail end-to-end. The CLI's runner returns `done`
-    // for every leaf (so runDag's cancel-on-fail path is exercised when a
-    // leaf actually fails); the CLI envelope filters `emittedToolCalls` to
-    // the first level only (see `firstLevelIds`). The LLM-side runner
-    // re-invokes `--from-dag` for level 2+ after writing level-1
-    // contracts via `peaks contract write`.
-    let levelArr;
-    try {
-        levelArr = topologicalLevels(dag);
-    }
-    catch (err) {
-        printResult(io, fail('sub-agent.dispatch', 'INVALID_DAG', `topologicalLevels failed for ${options.fromDag}: ${err.message}`, { role, toolCall: null, dispatchRecordPath: null }, [
-            'The DAG passed validateDag() but topologicalLevels threw (likely a cycle that slipped past validateDag, or a runtime invariant).',
-            'Inspect the DAG file with the editor and re-invoke dispatch. (No peaks scan dag CLI ships in 2.7.0; if you need a programmatic DAG validator, import validateDag / topologicalLevels from src/services/dispatch/slice-dag.ts directly.)'
-        ]), asJson);
-        process.exitCode = 1;
+    if (assertGraphNodesMapped(dag, scope) === null)
         return;
-    }
-    // Read upstream contracts so downstream-level prompts (when re-invoked
-    // for level 2+) get auto-injected ancestors via `formatContractInjection`.
-    // At level-1 emit time, contracts is empty (no ancestors yet); the
-    // injection matters when the LLM re-invokes for level 2+ after writing
-    // level-1 contracts via `writeContract`.
-    const existingContracts = listContracts(projectRoot, sid);
-    const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
-    const adapter = getAdapter(ide);
-    const dispatcher = adapter.subAgentDispatcher;
-    if (!dispatcher.supportsRole(role)) {
-        printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', `IDE ${ide} does not support role "${role}"`, { role, toolCall: null, dispatchRecordPath: null }, ['Switch to a registered IDE (e.g. claude-code) or pick a role the current IDE supports.']), asJson);
-        process.exitCode = 1;
+    const levelArr = topologicalLevelsOrFail(runtime, dag, options.fromDag, scope);
+    if (levelArr === null)
+        return;
+    const dispatched = resolveDagDispatcher(ids.projectRoot);
+    if (!dispatched.dispatcher.supportsRole(role)) {
+        emitDagFailure(io, asJson, {
+            role,
+            code: 'IDE_NOT_SUPPORTED',
+            message: `IDE ${dispatched.ide} does not support role "${role}"`,
+            nextActions: [
+                'Switch to a registered IDE (e.g. claude-code) or pick a role the current IDE supports.'
+            ]
+        });
         return;
     }
-    // Track per-level emissions so the CLI envelope can expose ONLY the
-    // first topological level to the LLM (matching MVP 1.2 semantics: LLM
-    // executes level-1 toolCalls, writes contracts via `peaks contract
-    // write`, then re-invokes `--from-dag` for level 2+). Level-2+ leaves
-    // still flow through runDag's join-barrier — their toolCalls are
-    // generated internally so the orchestrator's happy path is exercised
-    // end-to-end, but they are NOT surfaced in the CLI envelope (the LLM
-    // sees them only after re-invoking with fresh level-1 contracts).
+    await runLevels({ runtime, dag, levelArr, dispatched, ids, scope, fromDag: options.fromDag });
+}
+/**
+ * Run every topological level through `runLayeredDag` and print the level-1
+ * envelope. Upstream contracts are read first so downstream-level prompts get
+ * auto-injected ancestors via `formatContractInjection` (empty at level-1 emit
+ * time, which is when the LLM re-invokes with fresh level-1 contracts).
+ */
+async function runLevels(run) {
+    const { runtime, dag, levelArr, dispatched, ids, scope, fromDag } = run;
+    const existingContracts = runtime.listContracts(ids.projectRoot, ids.sid);
     const firstLevelIds = new Set(levelArr[0] ?? []);
-    // node declares `files`, refine the level into file-overlap waves so the
-    // LLM fans out without serializing on a shared file. Emitted additively
-    // in the envelope; the topological dispatch flow itself is unchanged.
-    // Nodes without `files` → `firstLevelWaves: null` (legacy envelope).
-    const firstLevelDescriptors = [...firstLevelIds].map((id) => ({
-        id,
-        files: dag.nodes.find((n) => n.id === id)?.files ?? []
-    }));
-    const firstLevelWaves = firstLevelDescriptors.length > 0 && firstLevelDescriptors.every((d) => d.files.length > 0)
-        ? planFileOverlapWaves(firstLevelDescriptors).waves
-        : null;
-    const emittedToolCalls = [];
-    const emittedSliceIds = [];
-    // CLI runner: emit the per-slice `buildToolCall` envelope, then return
-    // `done` with an empty `publicSurface` placeholder. The orchestrator
-    // treats the slice as "CLI-emitted, awaiting LLM-side execution" and
-    // advances to the next topological level (or breaks on failure). The
-    // placeholder surface is intentionally empty: the real public surface
-    // arrives later via `peaks contract write` from the LLM-side runner,
-    // and overwrites the CLI placeholder contract written by `noopWriter`.
-    // Why not `cancelled`? Returning `cancelled` here short-circuits
-    // runDag's join-barrier + cancel-on-fail path — the orchestrator
-    // breaks out after the first level with a cancellation, which hides
-    // the real cancel-on-fail semantics from the test suite (and from any
-    // future caller that wants to use `runDag` end-to-end from the CLI).
-    // Returning `done` exercises the full happy path; cancel-on-fail
-    // semantics will be covered when 1.3 lands real per-IDE await.
-    const cliRunner = async (spec) => {
-        const toolCall = dispatcher.buildToolCall({
-            role: spec.role,
-            prompt: spec.prompt,
-            requestId: rid,
-            sessionId: sid
-        });
-        if (firstLevelIds.has(spec.sliceId)) {
-            emittedToolCalls.push(toolCall);
-            emittedSliceIds.push(spec.sliceId);
-        }
-        return {
-            status: 'done',
-            publicSurface: {
-                exports: [],
-                types: [],
-                publicSignatures: []
-            }
-        };
-    };
-    // CLI noop writer — the orchestrator collects a `SliceContract` per
-    // emitted toolCall so downstream re-invocations (level 2+) can splice
-    // ancestor contracts via `formatContractInjection`. We don't write to
-    // disk here (the LLM-side runner does that via `peaks contract write`
-    // after each toolCall resolves), but the returned placeholder MUST be
-    // shape-valid: the `contractHash` field has to be a real SHA-256 hex
-    // string so formatContractInjection + downstream validators don't
-    // reject the placeholder. The placeholder hash is computed from the
-    // slice identity only (`sliceId|sessionId`) — it's deterministic,
-    // stable, and collision-free for the MVP run, but obviously does NOT
-    // represent the slice's actual public surface. The LLM-side runner's
-    // `peaks contract write` call will overwrite this with a content-based
-    // hash once the slice finishes.
-    const noopWriter = (sliceId, _publicSurface) => {
-        const partial = {
-            sliceId,
-            sessionId: sid,
-            exports: [],
-            types: [],
-            publicSignatures: []
-        };
-        return {
-            sliceId,
-            sessionId: sid,
-            completedAt: new Date(0).toISOString(), // epoch sentinel = "placeholder, not yet finished"
-            exports: [],
-            types: [],
-            publicSignatures: [],
-            contractHash: hashContract(partial)
-        };
-    };
-    // runLayeredDag IS in the path: validates the DAG, iterates all
-    // topological levels (foundation/upstreamSync slices prioritized within
-    // each level by `topologicalLevels`), runs the join barrier after
-    // each level, and triggers cancel-on-fail rollback if any leaf
-    // returns `failed` (or `cancelled`, once 1.3 lands). The CLI
-    // envelope below filters `emittedToolCalls` / `emittedSliceIds` to
-    // the first level — see the `firstLevelIds` filter inside `cliRunner`.
+    const emissions = { toolCalls: [], sliceIds: [] };
+    const runSlice = makeCliRunner({
+        firstLevelIds,
+        dispatcher: dispatched.dispatcher,
+        ids,
+        emissions
+    });
+    const writeContractFn = makeNoopWriter(runtime.hashContract, ids.sid);
     try {
-        await runLayeredDag(dag, {
-            projectRoot,
-            sessionId: sid,
+        await runtime.runLayeredDag(dag, {
+            projectRoot: ids.projectRoot,
+            sessionId: ids.sid,
             existingContracts,
-            runSlice: cliRunner,
-            writeContractFn: noopWriter
+            runSlice,
+            writeContractFn
         });
     }
     catch (err) {
-        // runLayeredDag throws DagPlanError for plan-level failures (e.g.
-        // cycle slipping past validateDag). Surface it as INVALID_DAG so
-        // the CLI envelope has a clear failure code, not a generic
-        // DISPATCH_ERROR.
-        printResult(io, fail('sub-agent.dispatch', 'INVALID_DAG', `runLayeredDag failed for ${options.fromDag}: ${err.message}`, { role, toolCall: null, dispatchRecordPath: null }, [
-            'runLayeredDag threw DagPlanError; the DAG passed validateDag() but failed at topologicalLevels or contractStore dispatch.',
-            'Inspect the DAG file and re-run.'
-        ]), asJson);
-        process.exitCode = 1;
+        emitDagFailure(scope.io, scope.asJson, {
+            role: scope.role,
+            code: 'INVALID_DAG',
+            message: `runLayeredDag failed for ${fromDag}: ${err.message}`,
+            nextActions: [
+                'runLayeredDag threw DagPlanError; the DAG passed validateDag() but failed at topologicalLevels or contractStore dispatch.',
+                'Inspect the DAG file and re-run.'
+            ]
+        });
         return;
     }
-    printResult(io, ok('sub-agent.dispatch', {
-        envelopeVersion: '2.1.0',
-        role,
-        ide: dispatcher.label,
-        fromDag: options.fromDag,
-        batchId,
-        dispatchCount: emittedSliceIds.length,
+    printResult(scope.io, buildDagSuccessEnvelope({
+        role: scope.role,
+        ide: dispatched.dispatcher.label,
+        fromDag,
+        batchId: ids.batchId,
         levelsTotal: levelArr.length,
-        firstLevel: emittedSliceIds,
-        // §3: file-overlap wave plan for the first level (null when any
-        // first-level node omits `files`). Additive field.
-        firstLevelWaves,
-        toolCalls: emittedToolCalls,
+        emittedSliceIds: emissions.sliceIds,
+        emittedToolCalls: emissions.toolCalls,
+        firstLevelWaves: planFirstLevelWaves(dag, levelArr),
         existingContractCount: existingContracts.length,
-        expectedCompletionSeconds: 60,
-        artifactsPublicPaths: [],
-        orchestratorVisibleHint: `⏳ Spawning ${emittedSliceIds.length} sub-agents via Task tool from DAG ${options.fromDag}, batch-id=${batchId} (ETA ~60s)`,
-        // v2.15.0 follow-up — G12/G11/G2: per-slice metadata (foundation /
-        // upstreamSync / complexity) for downstream scheduling decisions.
-        sliceMeta: emittedSliceIds.map((id) => {
-            const node = dag.nodes.find((n) => n.id === id);
-            return {
-                id,
-                foundation: node?.foundation === true,
-                upstreamSync: node?.upstreamSync === true,
-                complexity: node?.complexity !== undefined && isSliceComplexity(node.complexity)
-                    ? node.complexity
-                    : null
-            };
-        }),
-        nextActions: [
-            'Execute each toolCall in your IDE; on completion, write the slice contract to .peaks/_runtime/<sid>/dispatch/contracts/<slice-id>.json.',
-            'Re-invoke `peaks sub-agent dispatch --from-dag <file>` with the same batch-id to advance to the next level once all current-level slices have written contracts.'
-        ]
-    }, [], [
-        'MVP (1.2) plans the first level via runLayeredDag orchestrator (cancel-on-fail path active); the LLM drives subsequent levels by re-invoking this command after contract writes.',
-        existingContracts.length > 0
-            ? `Injected ${existingContracts.length} upstream contract(s) into downstream-level prompts via formatContractInjection.`
-            : 'No upstream contracts found; first-level prompts have empty ancestor blocks.'
-    ]), asJson);
+        dag,
+        isSliceComplexity: runtime.isSliceComplexity
+    }), scope.asJson);
 }

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

@@ -0,0 +1,44 @@
+import type { FinalReviewOutput } from '../../services/final-review/final-review-types.js';
+import { type ProgramIO } from '../cli-helpers.js';
+/** The two inputs a refusal envelope names, plus why it was refused. */
+export type PrepareRefusal = {
+    readonly rid: string;
+    readonly code: string;
+    readonly message: string;
+    readonly sessionId: string;
+    readonly auditGoalPath: string;
+    readonly nextActions: string[];
+};
+/** Print one refusal envelope and mark the process failed. */
+export declare function emitPrepareFailure(io: ProgramIO, json: boolean | undefined, refusal: PrepareRefusal, missingEnv?: readonly string[]): void;
+/** Where a resolved run reads its audit goal from. */
+export type PrepareGoalPath = {
+    readonly sessionId: string;
+    readonly auditGoalPath: string;
+};
+/**
+ * Stub path: surface a structured "scaffold ready" envelope.
+ *
+ * The service is NOT called 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.
+ */
+export declare function emitStubEnvelope(io: ProgramIO, rid: string, goal: PrepareGoalPath, json: boolean | undefined): void;
+/** The success envelope of a real-provider run. */
+export declare function emitReviewEnvelope(io: ProgramIO, result: {
+    readonly rid: string;
+    readonly goal: PrepareGoalPath;
+    readonly model: string;
+    readonly review: FinalReviewOutput;
+    readonly json: boolean | undefined;
+}): void;
+/**
+ * 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.
+ */
+export declare function finalReviewErrorCode(error: unknown): string;
+export declare function finalReviewNextActions(code: string): string[];

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

@@ -0,0 +1,100 @@
+// src/cli/commands/final-review-command-envelopes.ts
+//
+// Every envelope `peaks prepare-final-review` can print, and the error-code
+// mapping behind the failure one. Split out of `final-review-commands.ts`; the
+// codes, messages, data fields and next-action strings are unchanged.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { IncompleteFinalReviewError } from '../../services/final-review/final-review-service.js';
+import { LlmBindingError, LlmRequestError } from '../../services/llm/anthropic-runner.js';
+import { printResult } from '../cli-helpers.js';
+import { emptyFinalReviewData } from './final-review-command-shared.js';
+/** Print one refusal envelope and mark the process failed. */
+export function emitPrepareFailure(io, json, refusal, missingEnv) {
+    printResult(io, fail('final-review.prepare', refusal.code, refusal.message, emptyFinalReviewData(refusal.rid, refusal.sessionId, refusal.auditGoalPath, missingEnv), refusal.nextActions), json ?? false);
+    process.exitCode = 1;
+}
+/**
+ * Stub path: surface a structured "scaffold ready" envelope.
+ *
+ * The service is NOT called 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.
+ */
+export function emitStubEnvelope(io, rid, goal, json) {
+    const data = {
+        status: 'scaffold-only',
+        rid,
+        sessionId: goal.sessionId,
+        auditGoalPath: goal.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: ${goal.auditGoalPath}`,
+        'Re-run with `--llm-provider anthropic` to produce a real review.'
+    ]);
+    printResult(io, envelope, json ?? false);
+}
+/** The success envelope of a real-provider run. */
+export function emitReviewEnvelope(io, result) {
+    const { rid, goal, model, review, json } = result;
+    const data = {
+        status: 'review-complete',
+        rid,
+        sessionId: goal.sessionId,
+        auditGoalPath: goal.auditGoalPath,
+        serviceWired: true,
+        providerBinding: 'anthropic-messages-api',
+        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: ${model}).`,
+        `allPass: ${String(review.allPass)}.`
+    ]);
+    printResult(io, envelope, json ?? false);
+}
+/**
+ * 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.
+ */
+export function finalReviewErrorCode(error) {
+    if (error instanceof LlmBindingError ||
+        error instanceof LlmRequestError ||
+        error instanceof IncompleteFinalReviewError) {
+        return error.code;
+    }
+    return 'FINAL_REVIEW_FAILED';
+}
+export 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/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 })
+    };
+}