peaks-loop 4.0.42 → 4.0.44

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/job-commands.js

@@ -56,7 +56,8 @@ function findSessionHoldingJob(project, jobId) {
  * `.peaks/_runtime/session.json` binding points at another session):
  * 1. `--session-id` flag (explicit override)
  * 2. `PEAKS_SESSION_ID` env var
- * 3. `getCurrentSessionId(project)` — reads `.peaks/_runtime/session.json`
+ * 3. `getCurrentSessionId(project)` — this caller's session binding, falling back
+ *    to `.peaks/_runtime/session.json` when no caller binding is resolvable
  * 4. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
  *
  * When `jobId` is passed and it is absent from the resolved session, the thrown
@@ -110,7 +111,8 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .option('--project <repo>')
         .action(async (opts) => {
         const project = projectRoot(opts);
-        // Resolve sessionId: explicit flag > PEAKS_SESSION_ID > canonical session binding > FAIL.
+        // Resolve sessionId: explicit flag > PEAKS_SESSION_ID > caller-first session binding
+        // (this caller's binding, else the project-global session.json) > FAIL.
         // Per spec §3.3, Job state lives at .peaks/_runtime/<sessionId>/job/<jobId>/state.json —
         // a random UUID would scatter state across dirs and break resume/auto-compact.
         let sessionId = opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);

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

@@ -30,7 +30,7 @@ export function registerScanCommands(program, io) {
     const scan = program.command('scan').description('Deterministic project scans (archetype, existing system) for Peaks workflows');
     addJsonOption(scan
         .command('archetype')
-        .description('Detect project archetype, frontend-only mode, and supporting signals from the filesystem (read-only)')
+        .description('Detect project archetype, integration mode (three scenarios), frontend-only mode, and supporting signals from the filesystem (read-only)')
         .requiredOption('--project <path>', 'target project root')).action(async (options) => {
         try {
             const report = await scanArchetype({ projectRoot: options.project });

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;

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

@@ -5,6 +5,36 @@ import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } f
 import { writeLogEntry } from '../../services/log/logger.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { summarizeBatchResults } from './sub-agent-shared.js';
+/** The one selection rule `--request-id` and `--batch` now share. */
+export const FINALIZE_SELECTION_RULE = 'prefer status=queued; among those, newest by record createdAt (then filename); ' +
+    'no queued match means nothing is finalized';
+/**
+ * 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 function selectFinalizeTarget(candidates) {
+    const queued = candidates.filter(candidate => candidate.status === 'queued');
+    if (queued.length === 0)
+        return null;
+    return [...queued].sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.recordPath.localeCompare(a.recordPath))[0];
+}
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export function describeFinalizeRejection(candidate, chosen) {
+    if (candidate.status !== 'queued' || chosen === null) {
+        return 'status is ' + candidate.status;
+    }
+    return 'superseded by the newer queued record ' + chosen.recordPath;
+}
 export function registerShareCommand(parent, io) {
     addJsonOption(parent
         .command('share')
@@ -329,6 +359,31 @@ export function registerFinalizeCommand(parent, io) {
                 const finalized = [];
                 const skipped = [];
                 const errors = [];
+                let selection = null;
+                /**
+                 * 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.
+                 */
+                const tryReadRecord = (recordPath) => {
+                    try {
+                        return readRecord(recordPath);
+                    }
+                    catch (e) {
+                        errors.push({ recordPath, error: getErrorMessage(e) });
+                        return null;
+                    }
+                };
                 const applyOutcome = (recordPath, rid) => {
                     markCompleted({ recordPath, now: () => new Date(), status: mapped.status, outcome: mapped.outcome, projectRoot });
                     finalized.push({ recordPath, requestId: rid, status: mapped.status });
@@ -352,29 +407,59 @@ export function registerFinalizeCommand(parent, io) {
                     const fs2 = await import('node:fs');
                     const path2 = await import('node:path');
                     const dir = path2.resolve(projectRoot, '.peaks', '_sub_agents', sessionId);
-                    let resolvedPath = null;
+                    const candidates = [];
                     if (fs2.existsSync(dir)) {
                         for (const f of fs2.readdirSync(dir)) {
-                            if (!f.endsWith('.json'))
+                            // Only dispatch records are readable records. The session
+                            // directory also holds `active-dispatches.json` (an index)
+                            // and `batch-<uuid>.counter.json` (batch counters); neither
+                            // carries a `version` field, so `readRecord` on them throws
+                            // `Dispatch record version mismatch ... got undefined`. The
+                            // `--batch` branch below has always used this same filter.
+                            if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
                                 continue;
                             const p = path2.join(dir, f);
-                            const r = readRecord(p);
-                            if (r.requestId === options.requestId) {
-                                resolvedPath = p;
-                                break;
-                            }
+                            const r = tryReadRecord(p);
+                            if (r === null || r.requestId !== options.requestId)
+                                continue;
+                            candidates.push({
+                                recordPath: p,
+                                requestId: r.requestId,
+                                status: r.status,
+                                createdAt: r.createdAt
+                            });
                         }
                     }
-                    if (!resolvedPath) {
+                    if (candidates.length === 0) {
                         printResult(io, fail('sub-agent.finalize', 'RECORD_NOT_FOUND', 'No dispatch record for requestId=' + options.requestId, { ok: false }, ['Check --request-id matches the dispatch envelope.']), asJson);
                         process.exitCode = 1;
                         return;
                     }
-                    try {
-                        applyOutcome(resolvedPath, options.requestId);
+                    // N3: same rule as `--batch` — see `selectFinalizeTarget`.
+                    const chosen = selectFinalizeTarget(candidates);
+                    selection = {
+                        requestId: options.requestId,
+                        rule: FINALIZE_SELECTION_RULE,
+                        matched: candidates.length,
+                        chosen: chosen?.recordPath ?? null,
+                        rejected: candidates
+                            .filter(candidate => candidate !== chosen)
+                            .map(candidate => ({
+                            recordPath: candidate.recordPath,
+                            status: candidate.status,
+                            reason: describeFinalizeRejection(candidate, chosen)
+                        }))
+                    };
+                    for (const rejected of selection.rejected) {
+                        skipped.push({ recordPath: rejected.recordPath, reason: rejected.reason });
                     }
-                    catch (e) {
-                        errors.push({ recordPath: resolvedPath, error: getErrorMessage(e) });
+                    if (chosen !== null) {
+                        try {
+                            applyOutcome(chosen.recordPath, chosen.requestId);
+                        }
+                        catch (e) {
+                            errors.push({ recordPath: chosen.recordPath, error: getErrorMessage(e) });
+                        }
                     }
                 }
                 else {
@@ -386,7 +471,9 @@ export function registerFinalizeCommand(parent, io) {
                             if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
                                 continue;
                             const p = path2.join(dir, f);
-                            const r = readRecord(p);
+                            const r = tryReadRecord(p);
+                            if (r === null)
+                                continue;
                             if (r.batchId !== options.batch)
                                 continue;
                             if (r.status !== 'queued') {
@@ -402,7 +489,20 @@ export function registerFinalizeCommand(parent, io) {
                         }
                     }
                 }
-                printResult(io, ok('sub-agent.finalize', { finalized, skipped, errors, sessionId, outcome }, errors.length > 0 ? [errors.length + ' failed'] : [], errors.length > 0 ? ['Re-run after fixing.'] : ['All targeted records transitioned out of queued.']), asJson);
+                const hints = [];
+                if (errors.length > 0) {
+                    hints.push('Re-run after fixing; unreadable records are listed in errors[] and were skipped, not fatal.');
+                }
+                else if (finalized.length === 0 && skipped.length > 0) {
+                    hints.push('Nothing was finalized: every matching record had already left `queued`. See skipped[] for each record\'s status.');
+                }
+                else {
+                    hints.push('All targeted records transitioned out of queued.');
+                }
+                if (selection !== null) {
+                    hints.push(`--request-id selection (${selection.rule}): chose ${selection.chosen ?? '(none)'} of ${selection.matched} matching record(s); ${selection.rejected.length} rejected.`);
+                }
+                printResult(io, ok('sub-agent.finalize', { finalized, skipped, errors, selection, sessionId, outcome }, errors.length > 0 ? [errors.length + ' failed'] : [], hints), asJson);
                 if (errors.length > 0)
                     process.exitCode = 1;
             }

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

@@ -6,14 +6,18 @@
  *
  *   1. Auto-detects the framework from package.json (devDependencies +
  *      dependencies) via detectTestFramework().
- *   2. Spawns the framework's CLI with --cache enabled (overriding any
+ *   2. Resolves the project-LOCAL runner binary (node_modules) and spawns
+ *      that, so the command works where the runner is not on PATH — notably
+ *      Windows, where node_modules/.bin/vitest.cmd is not spawnable without
+ *      a shell. PATH is a last resort and is reported, not silent.
+ *   3. Spawns the framework's CLI with --cache enabled (overriding any
  *      --no-cache in the consumer's `test` script). The user can
  *      opt back into no-cache via `peaks test --no-cache` or
  *      `peaks test --passthrough`.
- *   3. Skips tests where (fileMtime, fileSha256) is unchanged AND the
+ *   4. Skips tests where (fileMtime, fileSha256) is unchanged AND the
  *      previous run status was 'passed' (per-test fingerprint cache at
  *      `<projectRoot>/.peaks/_runtime/test-cache/<hash>.json`).
- *   4. Exits 0 on all-pass / all-skip; exits 1 on any failure.
+ *   5. Exits 0 on all-pass / all-skip; exits 1 on any failure.
  *
  * The CLI is invoked by USER (not just by skill) per slice 2.5.0
  * sub-fix B (G16) — a documented exception to the
@@ -29,6 +33,7 @@
  *   peaks test --passthrough          — do NOT override the consumer's argv
  *   peaks test --framework <name>     — force a specific framework
  */
+import { spawn } from 'node:child_process';
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 import { type TestFramework } from '../../services/test-cache/test-cache-service.js';
@@ -44,4 +49,56 @@ export declare function buildRunnerArgv(framework: TestFramework, patterns: stri
     cache?: boolean;
     passthrough?: boolean;
 }): string[];
+/** Successful resolution — everything `spawn` needs, plus provenance. */
+export type RunnerFound = {
+    ok: true;
+    /** Executable to spawn: node itself, a local shim, or a PATH hit. */
+    command: string;
+    /** argv for `command` (includes the JS entry when spawning node). */
+    args: string[];
+    /** How the runner was found — named in the PATH-fallback notice. */
+    via: string;
+    /** True only for the PATH fallback, which the caller surfaces visibly. */
+    fromPath: boolean;
+};
+export type RunnerResolution = RunnerFound | {
+    ok: false;
+    searched: string[];
+};
+/** Injection seams for tests — production passes nothing. */
+export type ResolveRunnerDeps = {
+    platform?: NodeJS.Platform;
+    existsSync?: (path: string) => boolean;
+    readFileSync?: (path: string) => string;
+    env?: NodeJS.ProcessEnv;
+    /** Node executable used to run the runner's JS entry. */
+    nodeExecPath?: string;
+};
+export type RunRunnerDeps = ResolveRunnerDeps & {
+    spawnFn?: typeof spawn;
+};
+/**
+ * Resolve the consumer project's LOCAL runner, and the form of it that
+ * `spawn` can actually launch on this platform.
+ *
+ * Probed, in order (every probe is reported when nothing is found):
+ *   1. `<root>/node_modules/.bin/<runner>` (+ `.cmd`/`.exe` on Windows) —
+ *      the project-local runner the command documents.
+ *   2. `<root>/node_modules/<runner>/package.json` → its `bin` JS entry.
+ *   3. PATH — last resort only; the caller prints a visible notice.
+ *
+ * Between 1 and 2 the **JS entry** wins: `spawn` runs it as
+ * `node <entry> …`, which is identical on Windows and POSIX and never
+ * routes argv through a shell. The `.cmd` shim is only a fallback because
+ * it needs cmd.exe to launch it (see `toSpawnable`).
+ */
+export declare function resolveRunner(framework: TestFramework, argv: string[], projectRoot: string, deps?: ResolveRunnerDeps): RunnerResolution;
+/** Actionable message for the no-runner case — never a raw ENOENT. */
+export declare function formatRunnerNotFound(framework: TestFramework, searched: string[]): string;
+export declare function runRunner(framework: TestFramework, argv: string[], projectRoot: string, deps?: RunRunnerDeps): Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+    notice: string | null;
+}>;
 export declare function registerTestCommands(program: Command, _io: ProgramIO): void;