peaks-loop 4.0.47 → 4.0.49

package/dist/cli/commands/sub-agent/detached.d.ts

@@ -15,14 +15,27 @@ export declare function dispatch(f: DispatchFlags): Promise<{
     ok: boolean;
     command: string;
     data: {
+        expectedCompletionSeconds: number;
+        orchestratorVisibleHint: string;
         mode: string;
         vendor: "claude" | "codex" | "copilot" | undefined;
         pid: number;
         dispatchRecordPath: string;
         maxConcurrent: number;
         noThrottle: boolean;
-        orchestratorVisibleHint: string;
+    } | {
         expectedCompletionSeconds: number;
+        spawnError: {
+            code: string | undefined;
+            message: string;
+        };
+        orchestratorVisibleHint: string;
+        mode: string;
+        vendor: "claude" | "codex" | "copilot" | undefined;
+        pid: number;
+        dispatchRecordPath: string;
+        maxConcurrent: number;
+        noThrottle: boolean;
     };
     warnings: string[];
     nextActions: string[];

package/dist/cli/commands/sub-agent/detached.js

@@ -25,15 +25,26 @@ export async function dispatch(f) {
     if (f.noThrottle) {
         warnings.push('user-overrode: --no-throttle (peak runtime may exceed performance ceiling)');
     }
-    // rid-001 fix (F1 follow-up): the vendor CLI's ChildProcess is owned by
-    // peaks-loop-internal-runtime/dispatch.dispatchDetached, which now exposes
-    // it via DispatchResult.child. When the vendor binary is not on PATH the
-    // spawn fires an async 'error' event after dispatchDetached returns; we
-    // attach a per-child handler that swallows ENOENT (expected when the user
-    // hasn't installed claude/codex/copilot) and logs anything else. This is
-    // the canonical pattern (matches codegraph-process-runner.ts) — no more
-    // process-level uncaughtException swallow.
+    // The vendor CLI's ChildProcess is owned by
+    // peaks-loop-internal-runtime/dispatch.dispatchDetached, and this handler
+    // deliberately attaches NO 'error' listener to it.
+    //
+    // The handler that used to live here — an 'error' listener attached to
+    // `r.child` after the await — could never fire. `ProcessSupervisor.spawn`
+    // attaches its own 'error' + 'spawn' listeners in the SAME synchronous turn
+    // the child is created, and `dispatchDetached` awaits the resulting `settled` promise
+    // before returning. A missing binary is emitted on the nextTick queue,
+    // which drains BEFORE the awaiting caller resumes — so by the time this
+    // function holds `r`, the event has already been consumed and turned into
+    // the typed `spawnError` value below. Attaching a listener here is not
+    // merely late; it is unreachable by construction.
     const sid = process.env.PEAKS_SESSION_ID ?? 'local';
+    // `spawnError` is optional in this annotation, not because the value is
+    // uncertain but because the type this resolves against is: the workspace
+    // package's `types` entry points at `dist/index.d.ts`, and a `dist` built
+    // before the field was added does not declare it. Reading it defensively
+    // (`?? null`, below) is correct in both worlds; requiring it here would make
+    // the handler fail to compile against a stale build.
     let r;
     r = await dispatchDetached({
         sid,
@@ -46,15 +57,17 @@ export async function dispatch(f) {
         runtimeDir: `.peaks/_runtime/${sid}/detached`,
         subAgentsDir: `.peaks/_sub_agents/${sid}`,
     });
-    r.child?.on('error', (err) => {
-        if (err && err.code === 'ENOENT')
-            return;
-        // Non-ENOENT child errors are surfaced to stderr; the dispatch envelope
-        // has already been written and the detached child is fire-and-forget.
-        console.error('[peaks sub-agent dispatch] detached child error:', err);
-    });
+    // The launch outcome is the envelope's `ok`, not a footnote. A vendor CLI
+    // that is not installed is an expected environment, and the dispatch record
+    // already says `status: 'failed'`; the envelope used to say `ok: true` with
+    // `pid: -1` and a "⏳ Spawning …" hint, so the two surfaces disagreed and the
+    // orchestrator read a launch that never happened as a running one.
+    //
+    // `?? null` covers a DispatchResult-shaped value produced by a test double
+    // that omits the field; a real `dispatchDetached` always sets it.
+    const spawnError = r.spawnError ?? null;
     return {
-        ok: true,
+        ok: spawnError === null,
         command: 'sub-agent.dispatch.detached',
         data: {
             mode: 'detached',
@@ -63,14 +76,26 @@ export async function dispatch(f) {
             dispatchRecordPath: r.dispatchRecordPath,
             maxConcurrent,
             noThrottle: f.noThrottle ?? false,
-            orchestratorVisibleHint: `⏳ Spawning detached sub-agent via ${f.vendor ?? 'claude'}: rid=${f.requestId} (ETA ~60s)`,
+            ...(spawnError === null
+                ? {
+                    orchestratorVisibleHint: `⏳ Spawning detached sub-agent via ${f.vendor ?? 'claude'}: rid=${f.requestId} (ETA ~60s)`
+                }
+                : {
+                    spawnError: { code: spawnError.code, message: spawnError.message },
+                    orchestratorVisibleHint: `❌ Could not launch detached sub-agent via ${f.vendor ?? 'claude'}: rid=${f.requestId} (${spawnError.code})`
+                }),
             expectedCompletionSeconds: 60,
         },
         warnings,
-        nextActions: [
-            'Sub-agent runs as detached OS process. Status at .peaks/_runtime/<sid>/detached/<rid>/status.json',
-            'Use `peaks sub-agent list --mode detached` to monitor.',
-            'Run `peaks sub-agent cleanup --orphan` to reap orphan processes (RL-15: user-only decision).',
-        ],
+        nextActions: spawnError === null
+            ? [
+                'Sub-agent runs as detached OS process. Status at .peaks/_runtime/<sid>/detached/<rid>/status.json',
+                'Use `peaks sub-agent list --mode detached` to monitor.',
+                'Run `peaks sub-agent cleanup --orphan` to reap orphan processes (RL-15: user-only decision).'
+            ]
+            : [
+                `The ${f.vendor ?? 'claude'} CLI is not runnable from this shell (${spawnError.code}); nothing was launched and no sub-agent is running.`,
+                'Either install the vendor CLI on PATH, or re-dispatch without --mode detached to use the in-process path.'
+            ]
     };
 }

package/dist/cli/commands/sub-agent-shutdown-commands.js

@@ -2,9 +2,20 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { printResult } from '../cli-helpers.js';
 const REGISTRATIONS_FILE = 'service-registrations.json';
 function registrationsPath(input) {
+    // Both id axes reach this join. `dispatchId` is `--dispatch-id` (falling back
+    // to PEAKS_DISPATCH_ID), and `sessionId` is the session binding; neither was
+    // checked, and `register` writes through this path. Guarding the whole join
+    // rather than only the flag keeps the function's contract single-stated.
+    if (isUnsafePathInput(input.dispatchId)) {
+        throw new Error(`Invalid dispatch id: ${input.dispatchId} (must be a single path segment)`);
+    }
+    if (isUnsafePathInput(input.sessionId)) {
+        throw new Error(`Invalid session id: ${input.sessionId} (must be a single path segment)`);
+    }
     return join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'dispatch', input.dispatchId, REGISTRATIONS_FILE);
 }
 function readAll(file) {

package/dist/cli/commands/verdict-aggregate-command.js

@@ -4,11 +4,51 @@ import { aggregateVerdict } from '../../services/verdict/verdict-aggregator.js';
 import { parseKarpathyEnvelope, parseMutEnvelope, parseQaEnvelope, parseSecurityEnvelope, parsePerfEnvelope, envelopesToAggregatorInput } from '../../services/verdict/envelopes.js';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
-const SECURITY_REL = 'audit/security.md';
-const PERF_REL = 'audit/perf.md';
-const KARPATHY_REL = 'rd/karpathy-review.md';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+import { DEFAULT_REQUEST_TYPE } from '../../services/artifacts/artifact-prerequisites.js';
+import { REQUEST_ID_PATTERN } from '../../services/artifacts/request-artifact-service.js';
+import { contractEvidencePaths } from '../../services/workflow/pipeline-verify-gate-support.js';
+// Slice `2026-09-14-audit-artifact-rid-scoping`: the audit/review evidence
+// filenames carry the rid. The ridless names are the pre-rid locations and
+// stay readable during the back-compat window. `mut/` is NOT rid-scoped —
+// see `MUT_REPORT` in `artifact-prerequisites.ts`: no producer in the repo
+// can write a rid-scoped mut report, so probing a templated name here would
+// look for a file that no writer can create.
+//
+// The candidate lists are read FROM the contract — the same
+// `contractEvidencePaths()` the verify pipeline resolves with — rather than
+// hand-written here. Hand-written lists held two of the contract's THREE
+// tiers, so a session whose security/perf evidence sits at the oldest tier
+// (`rd/security-review.md`, `rd/perf-baseline.md` — the live shape of three
+// sessions on disk) reported `block` while `peaks request transition`
+// accepted the same tree, and the hint named a legacy location it had never
+// probed. One table, one answer.
 const MUT_REL = 'mut/mut-report.json';
 const QA_REL = 'qa/test-reports';
+/**
+ * The declared tiers for one artifact name, primary first. Probed by the name
+ * this command used before the rid-scoping (the table matches it as either
+ * the primary or a legacy tier), so the lookup survives the primary moving.
+ * `verdict aggregate` is request-type-agnostic and every fanout-trigger type
+ * declares these artifacts identically, so the default type's list is the
+ * full one; a name the table does not carry falls back to itself.
+ */
+function contractRels(probeName) {
+    return contractEvidencePaths('rd', 'qa-handoff', DEFAULT_REQUEST_TYPE, probeName) ?? [probeName];
+}
+const SECURITY_RELS = contractRels('audit/security.md');
+const PERF_RELS = contractRels('audit/perf.md');
+const KARPATHY_RELS = contractRels('rd/karpathy-review.md');
+/**
+ * Sources whose absence must not read as `pass`. `mut` is excluded on
+ * purpose: `MUT_REPORT` carries `backCompat: true`, so the contract itself
+ * treats a missing mut report as a warning rather than a gate failure.
+ */
+const REQUIRED_SOURCES = [
+    { key: 'security', source: 'security-audit', rels: SECURITY_RELS },
+    { key: 'perf', source: 'perf-audit', rels: PERF_RELS },
+    { key: 'karpathy', source: 'karpathy-reviewer', rels: KARPATHY_RELS }
+];
 export function registerVerdictAggregateCommands(program, io) {
     const verdict = program.command('verdict').description('Aggregate the 5 envelope sources feeding peaks-code verdict logic');
     addJsonOption(verdict
@@ -25,6 +65,27 @@ export function registerVerdictAggregateCommands(program, io) {
             process.exitCode = 1;
             return;
         }
+        // The rid SELECTS THE FILE, so it has to be one path segment. This is the
+        // repo's own request-id guard — the one `request-artifact-service.ts`
+        // applies to every request artifact and the reason `peaks workflow
+        // verify-pipeline` refuses a hostile rid — and it was not applied to the
+        // joins below. Measured before it was: `--from-rid
+        // '../../../../../../ONLY-HERE'` read `<project>/ONLY-HERE.md`, a file
+        // outside `.peaks/`, as this slice's security AND perf evidence.
+        if (!REQUEST_ID_PATTERN.test(rid)) {
+            printResult(io, fail('verdict.aggregate', 'RID_INVALID', `Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`, {}, ['Pass the rid of the slice whose evidence you want aggregated, e.g. 2026-09-14-some-slug']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // `--sid` names the session DIRECTORY and is the same axis. Reject
+        // anything that is not one safe path segment rather than pinning a
+        // format: the default here is the deliberately non-format value
+        // `default`.
+        if (isUnsafePathInput(sid)) {
+            printResult(io, fail('verdict.aggregate', 'SID_INVALID', `Invalid session id: ${sid} (must be a single path segment)`, {}, ['Pass the session id, e.g. 2026-09-14-session-abc123']), options.json);
+            process.exitCode = 1;
+            return;
+        }
         try {
             const sources = {
                 // v2.13.3 AC-1: use the canonical markdown-aware parser from
@@ -34,9 +95,9 @@ export function registerVerdictAggregateCommands(program, io) {
                 // returned `verdict: warn, violations: []` — the aggregator
                 // then produced `reasons: []` and `verdict: 'pass'` even when
                 // the audit had flagged HIGH violations.
-                security: readAudit(projectRoot, sid, SECURITY_REL, parseSecurityEnvelope),
-                perf: readAudit(projectRoot, sid, PERF_REL, parsePerfEnvelope),
-                karpathy: readAudit(projectRoot, sid, KARPATHY_REL, (m) => parseKarpathyEnvelope(m)),
+                security: readAudit(projectRoot, sid, rid, SECURITY_RELS, parseSecurityEnvelope),
+                perf: readAudit(projectRoot, sid, rid, PERF_RELS, parsePerfEnvelope),
+                karpathy: readAudit(projectRoot, sid, rid, KARPATHY_RELS, (m) => parseKarpathyEnvelope(m)),
                 mut: await readMut(projectRoot, sid),
                 qa: readQa(projectRoot, sid, rid)
             };
@@ -55,7 +116,26 @@ export function registerVerdictAggregateCommands(program, io) {
                 mut: sources.mut !== null ? 'present' : 'missing',
                 qa: sources.qa !== null ? 'present' : 'missing'
             };
-            printResult(io, ok('verdict.aggregate', { verdict: result.verdict, reasons: result.reasons, sources: sourceFlags }, [], []), options.json);
+            // Fail closed. `aggregateVerdict()` starts its top-level verdict at
+            // `'pass'`, so a source that could not be read simply never enters the
+            // input and the run reports green. Before this slice the bare paths
+            // were the ones the writers wrote; after it the writers moved and this
+            // reader did not — so a missing security or perf audit became a `pass`
+            // for the loop evaluator (`services/loop/evaluator-dispatcher.ts`). A
+            // guard that cannot read its input must not report success.
+            const missingRequired = REQUIRED_SOURCES.filter((entry) => sources[entry.key] === null);
+            const missingReasons = missingRequired.map((entry) => ({
+                source: entry.source,
+                sources: [entry.source],
+                signal: 'block',
+                kind: 'missing-evidence',
+                hint: `${entry.rels.map((rel) => rel.replace('<rid>', rid)).join(' | ')} could not be read under .peaks/_runtime/${sid}/`
+            }));
+            printResult(io, ok('verdict.aggregate', {
+                verdict: missingReasons.length > 0 ? 'block' : result.verdict,
+                reasons: [...missingReasons, ...result.reasons],
+                sources: sourceFlags
+            }, [], []), options.json);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -64,12 +144,14 @@ export function registerVerdictAggregateCommands(program, io) {
         }
     });
 }
-function readAudit(projectRoot, sid, rel, parse) {
-    const path = join(projectRoot, '.peaks', '_runtime', sid, rel);
-    if (!existsSync(path))
-        return null;
-    const md = readFileSync(path, 'utf8');
-    return parse(md);
+function readAudit(projectRoot, sid, rid, rels, parse) {
+    // Canonical rid-scoped location first, then the pre-rid locations.
+    for (const rel of rels) {
+        const path = join(projectRoot, '.peaks', '_runtime', sid, rel.replace('<rid>', rid));
+        if (existsSync(path))
+            return parse(readFileSync(path, 'utf8'));
+    }
+    return null;
 }
 async function readMut(projectRoot, sid) {
     const path = join(projectRoot, '.peaks', '_runtime', sid, MUT_REL);

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

@@ -420,7 +420,7 @@ export function registerWorkflowCommands(program, io) {
     // semantics, role-based auth).
     addJsonOption(workflow
         .command('skip')
-        .description('Skip specific gates for a request (RD/QA). Use --dry-run to preview without writing. Allowed gate names: QA / RD (phase shortcuts) or specific gate names (rd-request-exists, tech-doc, code-review, security-review, qa-request-exists, test-cases, test-report, security-findings, performance-findings). Three rules apply: (1) only docs/config/chore slices can skip; (2) skip is one-time per rid; (3) script callers must also pass --i-have-reviewed.')
+        .description('Skip specific gates for a request (RD/QA). Use --dry-run to preview without writing. Allowed gate names: QA / RD (phase shortcuts) or specific gate names (rd-request-exists, prd-handoff, bug-analysis, code-review, security-review, perf-baseline, qa-request-exists, test-cases, test-report). Three rules apply: (1) only docs/config/chore slices can skip; (2) skip is one-time per rid; (3) script callers must also pass --i-have-reviewed.')
         .requiredOption('--rid <rid>', 'request identifier')
         .requiredOption('--project <path>', 'project root path')
         .requiredOption('--gates <list>', 'comma-separated gate names (e.g. "QA" or "QA,slice-check" or "code-review,security-review")')

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 import { CommanderError } from 'commander';
 import { createProgram } from './program.js';
 import { getErrorMessage } from 'peaks-loop-shared/result';
-import { printErrorEnvelope } from './cli-helpers.js';
+import { printErrorEnvelope, printMissingRequiredOptionEnvelope, resolveInvokedCommandPath } from './cli-helpers.js';
 const defaultIo = {
     stdout: (text) => process.stdout.write(`${text}\n`),
     stderr: (text) => process.stderr.write(`${text}\n`)
@@ -30,32 +30,6 @@ const argv = process.argv.slice(2);
 const hasHelp = argv.some((arg) => arg === '--help' || arg === '-h');
 const firstPositional = argv.find((arg) => !arg.startsWith('-'));
 const program = createProgram();
-/**
- * The subcommand path the caller actually invoked, in the same tokens they
- * typed (`release canary`). Derived from the registered command tree by
- * consuming leading non-`-` argv tokens, so it never disagrees with what
- * Commander dispatched on.
- *
- * Commander's `CommanderError` carries a code and a message but no command
- * reference — `missingMandatoryOptionValue` is raised by the leaf command and
- * throws out of `parseAsync` with nothing naming it. Without this walk the
- * missing-option envelope could only say `command: "cli"`, which is the field
- * the caller needs to act on.
- */
-function resolveInvokedCommandPath() {
-    let cmd = program;
-    const parts = [];
-    for (const token of argv) {
-        if (token.startsWith('-'))
-            break;
-        const next = cmd.commands.find((c) => c.name() === token || c.aliases().includes(token));
-        if (next === undefined)
-            break;
-        parts.push(next.name());
-        cmd = next;
-    }
-    return parts.length > 0 ? parts.join(' ') : program.name();
-}
 if (hasHelp && firstPositional !== undefined) {
     const registered = new Set(program.commands.map((c) => c.name()));
     if (!registered.has(firstPositional)) {
@@ -86,24 +60,10 @@ program.parseAsync(process.argv).catch((error) => {
             return;
         }
         if (error.code === 'commander.missingMandatoryOptionValue') {
-            // A `.requiredOption()` the caller did not supply. Commander raises this
-            // as a plain `Error`-shaped `CommanderError`, so the `.catch()` below used
-            // to file it under `UNHANDLED_ERROR` — "you left out an argument" reported
-            // as a crash, with empty `nextActions` and no way to see WHICH option or
-            // what values it takes. The flags string Commander formats carries both
-            // (`--percent <10|50>`), so it is worth extracting rather than
-            // paraphrasing: it is the option's own declaration.
-            const message = getErrorMessage(error);
-            const option = /required option '([^']+)'/.exec(message)?.[1];
-            const invoked = resolveInvokedCommandPath();
-            printErrorEnvelope(defaultIo, invoked, 'MISSING_REQUIRED_OPTION', option === undefined
-                ? message
-                : `Missing required option '${option}' for \`peaks ${invoked}\`.`, { option: option ?? null }, [
-                option === undefined
-                    ? `Run \`peaks ${invoked} --help\` to see the options this command requires.`
-                    : `Supply ${option} — it is required, so the command has no default for it.`,
-                `Run \`peaks ${invoked} --help\` for the option's accepted values and its siblings.`
-            ]);
+            // See `printMissingRequiredOptionEnvelope` — the same builder backs the
+            // in-process test runner, so the envelope a test asserts is the envelope
+            // a user gets.
+            printMissingRequiredOptionEnvelope(defaultIo, resolveInvokedCommandPath(program, argv), getErrorMessage(error));
             return;
         }
         if (error.code === 'commander.missingArgument' || error.code === 'commander.unknownCommand' || error.code === 'commander.unknownOption') {

package/dist/services/artifacts/artifact-prerequisites.d.ts

@@ -29,18 +29,36 @@ export type ArtifactPrerequisite = {
      */
     headingMustContain?: ReadonlyArray<string>;
     /**
-     * Slice v2.12.0 Group B Tier 5: optional legacy path that satisfies
-     * the same gate. When `relativePath` does not resolve on disk, the
-     * resolver tries this fallback path before reporting the prereq as
-     * missing. Use this for 1-minor-release back-compat windows where
-     * an old artifact location is still accepted alongside the new one.
-     * v2.13.0 should remove all `legacyRelativePath` entries.
+     * The immediately previous location of this artifact. When
+     * `relativePath` does not resolve on disk, the resolver tries this
+     * path before reporting the prereq as missing.
+     *
+     * This field is a published surface, not just a private hint:
+     * `verify-pipeline`'s `contractEvidencePaths()`
+     * (`src/services/workflow/pipeline-verify-gate-support.ts`) reads it
+     * to build its probe list, so it must keep meaning "the one path a
+     * previous release wrote". Do not repurpose it as a general list —
+     * add older tiers to `legacyRelativePaths` instead.
      *
      * Body checks (`mustContain` / `mustContainAny` /
      * `headingMustContain`) apply to whichever path resolved — the
-     * gate does not distinguish which path served the file.
+     * gate does not distinguish which path served the file. That is
+     * deliberate: a legacy hit must keep the gate open, or existing
+     * sessions would fail the transition on upgrade.
      */
     legacyRelativePath?: string;
+    /**
+     * Further, older locations, tried **in declared order** after
+     * `legacyRelativePath`. Slice `2026-09-14-audit-artifact-rid-scoping`
+     * added this because the two audit artifacts have a two-release
+     * history behind their rid-scoped path: the pre-rid-scoping
+     * `audit/security.md` (v2.12.0) and, behind it, the v2.11.x
+     * `rd/security-review.md`. Three sessions on disk
+     * (`2026-09-06-session-a87ca4`, `2026-09-10-session-528a63`,
+     * `2026-09-12-session-e37ef0`) hold their security evidence only at
+     * the last of those, so the oldest tier still has to resolve.
+     */
+    legacyRelativePaths?: ReadonlyArray<string>;
 };
 export type PrerequisiteCheckResult = {
     ok: boolean;
@@ -75,4 +93,17 @@ export type CheckPrerequisitesOptions = {
     requestType?: RequestType;
 };
 export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType?: RequestType): ReadonlyArray<ArtifactPrerequisite>;
+/**
+ * The contract's BODY checks for one prerequisite, applied to `body`. Returns
+ * one human-readable message per failed check, empty when the body satisfies
+ * the contract.
+ *
+ * Exported because this contract has a SECOND enforcer: `peaks workflow
+ * verify-pipeline` probes the same table for the paths it checks
+ * (`pipeline-verify-gate-support.ts`), and a resolver that probed only
+ * `existsSync` passed files this function rejects — a guard laxer than the
+ * contract it claims to read. Both callers now share this one implementation,
+ * so the checker cannot drift from the table again.
+ */
+export declare function prerequisiteBodyViolations(prerequisite: ArtifactPrerequisite, body: string): string[];
 export declare function checkPrerequisites(options: CheckPrerequisitesOptions): Promise<PrerequisiteCheckResult>;