peaks-loop 4.0.47 → 4.0.48

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

@@ -7,7 +7,7 @@ import { findProjectRoot } from '../../services/config/config-safety.js';
 import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntriesFromSettings, removeHookInstall, listSuperpowersDenyEntries } from '../../services/skills/hooks-settings-service.js';
 import { readJsonObjectFile } from '../../services/ide/shared/atomic-json.js';
 import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
-import { getAdapter } from '../../services/ide/ide-registry.js';
+import { getAdapter, resolveIdeOptionHelp } from '../../services/ide/ide-registry.js';
 /**
  * This module's own directory — `<root>/src/cli/commands` in the source tree,
  * `<root>/dist/cli/commands` in a build. Same reason as
@@ -153,7 +153,7 @@ export function registerHooksCommands(program, io) {
         .description(`Install the peaks-managed gate-enforce hook entry into the adapter's settings.json. Slice #014: only the gate-enforce entry is installed; the legacy progress-start entry is no longer installed. Idempotent: re-runs are no-ops. Project scope by default.`)
         .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
-        .option('--ide <id>', "target adapter id (claude-code | trae); default: auto-detect from env/cwd")
+        .option('--ide <id>', resolveIdeOptionHelp())
         .option('--dry-run', 'show what would change without writing')
         .option('--no-progress', 'skip the progress-start PreToolUse hook entry; install ONLY the gate-enforce entry')).action((options) => {
         const scope = resolveScope(options);
@@ -282,7 +282,7 @@ export function registerHooksCommands(program, io) {
         .description("Remove the peaks-managed gate-enforce hook entry from the target settings.json. Any legacy progress-start entry that a pre-#014 install left behind is also removed (sentinel-based scan). Third-party hooks are preserved.")
         .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
-        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        .option('--ide <id>', resolveIdeOptionHelp())).action((options) => {
         const scope = resolveScope(options);
         const projectRoot = resolveProjectRoot(scope, options.project);
         const ide = resolveIdeForCommand(options, projectRoot);
@@ -310,7 +310,7 @@ export function registerHooksCommands(program, io) {
         .description('Report which peaks-managed hook entries are installed.')
         .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
-        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        .option('--ide <id>', resolveIdeOptionHelp())).action((options) => {
         const scope = resolveScope(options);
         const projectRoot = resolveProjectRoot(scope, options.project);
         const ide = resolveIdeForCommand(options, projectRoot);

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

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { Command } from 'commander';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { JobStateStore } from '../../services/job/job-state-store.js';
 import { JobOrchestrator } from '../../services/job/job-orchestrator.js';
 import { writeJobProgress, readJobProgress, tryReadJobProgress } from '../../services/job/job-progress-store.js';
@@ -70,6 +71,13 @@ function resolveJobStateRoot(opts, jobId) {
     if (!sessionId) {
         throw new Error('NO_ACTIVE_SESSION: peaks job requires --session-id or an active peaks-code session via peaks workspace init');
     }
+    // Sid axis — the sibling of the jobId guard in `JobStateStore.jobDir`. A
+    // caller-supplied `--session-id` reaches this join unmodified, so a
+    // traversal value lands `job/<id>/state.json` outside every project root
+    // while the envelope still reads `ok: true`.
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
     const rootDir = join(project, '.peaks', '_runtime', sessionId, 'job');
     if (jobId && !existsSync(join(rootDir, jobId, 'state.json'))) {
         const other = findSessionHoldingJob(project, jobId);

package/dist/cli/commands/loop-eval-commands.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { resolveWorkflow, planWorkflow, planWorkflowRun } from '../../services/workflow/workflow-loader.js';
 import { dispatchEvaluator } from '../../services/loop/evaluator-dispatcher.js';
 import { DEFAULT_MONOTONIC_THRESHOLD } from '../../services/loop/monotonic-guard.js';
@@ -165,6 +166,14 @@ export function registerWorkflowEvalCommands(program, io) {
                     process.exitCode = 1;
                     return;
                 }
+                // Sid axis. `--session` reaches two joins below (`dir` and, through
+                // `nextEvalCaptureIndex`, the same literal), so one guard here covers
+                // the whole `--capture-score` write path.
+                if (isUnsafePathInput(options.session)) {
+                    printResult(io, fail('loop.eval', 'INVALID_SESSION_ID', `Invalid session id: ${options.session} (must be a single path segment)`, { provided: options.session }, ['Pass a session id that is a single path segment']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
                 const score = envelope.degraded ? 0.25 : (envelope.gateAction === 'pass' ? 1.0 : envelope.gateAction === 'warn' ? 0.5 : 0.0);
                 const dir = join(projectRoot, '.peaks', '_runtime', options.session, 'loop', rid, 'cycles');
                 const n = nextEvalCaptureIndex(projectRoot, options.session, rid);
@@ -475,6 +484,12 @@ export function registerWorkflowEvalCommands(program, io) {
  *  writes. The run-driver also writes to the same dir; the next
  *  index = max(prior)+1, or 1. */
 function nextEvalCaptureIndex(projectRoot, sid, rid) {
+    // Sid axis: this function is the join for the capture-score cycle dir. The
+    // action guards `options.session` before calling in, but the seam is callable
+    // on its own, so the join states its own contract.
+    if (isUnsafePathInput(sid)) {
+        throw new Error(`Invalid session id: ${sid} (must be a single path segment)`);
+    }
     const dir = join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid, 'cycles');
     if (!existsSync(dir))
         return 1;

package/dist/cli/commands/perf-audit-commands.js

@@ -46,6 +46,7 @@ export function registerPerfAuditCommands(program, io) {
         .option('--project <path>', 'project root (default: cwd)')).action((options) => {
         const projectRoot = options.project ?? process.cwd();
         const sid = options.sid;
+        const rid = options.rid;
         if (sid === undefined || sid.length === 0) {
             printResult(io, fail('perf-audit.detect', 'SID_REQUIRED', 'session id (--sid) is required for perf-audit.detect', { state: 'sid-missing' }, ['Pass --sid <session-id> (e.g. 2026-06-27-session-...)', 'Run `peaks session info --active --json` to find the active sid.']), options.json);
             process.exitCode = 1;
@@ -55,6 +56,7 @@ export function registerPerfAuditCommands(program, io) {
             const detect = detectPerfAudit({
                 projectRoot,
                 sessionId: sid,
+                ...(rid !== undefined ? { requestId: rid } : {}),
             });
             const envelope = detect.state === 'ready'
                 ? ok('perf-audit.detect', detect, [...detect.warnings], [...detect.nextActions])

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

@@ -33,6 +33,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { getErrorMessage } from '../cli-helpers.js';
 import { runBrowserAction } from '../../services/qa/browser-wrapper-service.js';
 export const DEFAULT_PORT = 8931;
@@ -43,6 +44,17 @@ export function playwrightSessionsDir(projectRoot) {
     return join(projectRoot, '.peaks', '_runtime', PLAYWRIGHT_SESSIONS_DIR);
 }
 export function sessionFilePath(projectRoot, terminalId) {
+    // Terminal-id axis. The derived id is already sanitised (`deriveTerminalId`),
+    // but `--terminal` is caller-supplied and reaches this join unsanitised.
+    // Measured (repair cycle 1, item 1): `playwright stop --terminal ../../../../X`
+    // read a session record planted OUTSIDE the project root, sent SIGTERM to the
+    // pid it named, unlinked that file, and returned `ok: true` — arbitrary
+    // process termination plus an arbitrary file delete, one flag away. This is
+    // the join every reader/writer of a session record goes through, so this is
+    // where the invariant lives.
+    if (isUnsafePathInput(terminalId)) {
+        throw new Error(`Invalid terminal id: ${terminalId} (must be a single path segment)`);
+    }
     return join(playwrightSessionsDir(projectRoot), `${terminalId}.json`);
 }
 /**

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

@@ -44,7 +44,7 @@ export function registerPrdCommands(program, io) {
     // peaks prd handoff init
     addJsonOption(handoff
         .command('init')
-        .description('Initialize an immutable handoff: sha256(body) → frontmatter → write to .peaks/_runtime/<sid>/prd/handoff.md')
+        .description('Initialize an immutable handoff: sha256(body) → frontmatter → write to .peaks/_runtime/<sid>/prd/handoff-<rid>.md')
         .requiredOption('--rid <request-id>', 'request id (e.g. 001-v2-11-cc-group-b)')
         .requiredOption('--sid <session-id>', 'session id (e.g. 2026-06-26-session-a28d69)')
         .requiredOption('--body <body>', 'handoff body markdown, or @<file> to read from disk')

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

@@ -29,6 +29,7 @@ import { join, resolve } from 'node:path';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { archiveScreenshots } from '../../services/qa/screenshot-archive-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { getSessionId } from '../../services/session/session-manager.js';
 import { BrowserRestartDetector } from '../../services/qa/browser-restart-detector.js';
 import { BrowserEventLogger } from '../../services/qa/browser-event-logger.js';
@@ -68,6 +69,12 @@ async function ensureContextForQa(goal, project, sid) {
 }
 export const DEFAULT_MAX_BROWSER_RESTARTS = 3;
 export function runQaSlice(input) {
+    // Sid axis: this is the join for `qa/browser-events.jsonl`. The `qa gate run`
+    // action guards before calling in, but the function is exported for tests and
+    // states its own contract at the join.
+    if (isUnsafePathInput(input.sessionId)) {
+        throw new Error(`Invalid session id: ${input.sessionId} (must be a single path segment)`);
+    }
     const detector = new BrowserRestartDetector({
         maxRestarts: input.maxRestarts,
         enabled: input.detectorEnabled
@@ -221,6 +228,15 @@ export function registerQaCommands(program, io) {
             // when the user did not supply one.
             const qaProject = options.project;
             const qaSid = options.sessionId ?? 'ad-hoc';
+            // Sid axis. `--session-id` reaches three consumers below — the context
+            // pre-build, `loadMutReport`, and `runQaSlice`'s
+            // `qa/browser-events.jsonl` join — so one guard at resolution covers all
+            // three. (`peaks qa archive-screenshots` has its own, separate join.)
+            if (isUnsafePathInput(qaSid)) {
+                printResult(io, fail('qa.gate', 'INVALID_SESSION_ID', `Invalid session id: ${qaSid} (must be a single path segment)`, { provided: qaSid }, ['Pass a session id that is a single path segment']), options.json);
+                process.exitCode = 1;
+                return;
+            }
             await ensureContextForQa('qa gate run', qaProject, qaSid);
             // Plan 2 / Task 8 — load peaks-mut's report (MUT.sig) if present.
             // Returns null when peaks-mut was not run; the gate treats that
@@ -289,6 +305,12 @@ export function registerQaCommands(program, io) {
         try {
             const projectRoot = resolve(options.project);
             const sid = options.sessionId?.trim() || getSessionId(projectRoot) || 'ad-hoc';
+            // Sid axis. Guarded after resolution so the flag value and the session
+            // binding are both covered. `archiveScreenshots` cannot do this itself:
+            // it only ever sees a fully-resolved `targetDir`.
+            if (isUnsafePathInput(sid)) {
+                throw new Error(`Invalid session id: ${sid} (must be a single path segment)`);
+            }
             const targetDir = join(projectRoot, '.peaks', '_runtime', sid, 'qa', 'screenshots');
             const envelope = archiveScreenshots({ sourceDir: options.source, targetDir });
             printResult(io, ok('qa.archive-screenshots', envelope, [], envelope.moved.length === 0

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

@@ -10,6 +10,7 @@ import { fail, ok } from 'peaks-loop-shared/result';
 import { triggerBestPracticeScan } from '../../services/prd/best-practice-auto-trigger.js';
 import { refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 /**
  * Slice 2026-09-10-context-audit-and-discipline (Slice B): bounded view of
  * `request list`. `count` is the true total; `names` carries
@@ -189,6 +190,13 @@ export function registerRequestCommands(program, io) {
             // non-existent .peaks/default/ dir and crashes with ENOENT, so when
             // --session-id is omitted we look the artifact up to find its session.
             let resolvedSessionId = options.sessionId;
+            // Sid axis: either arm of `resolvedSessionId` can be a caller-supplied
+            // `--session-id`, and it is joined into the bypass-counter root below.
+            if (resolvedSessionId !== undefined && isUnsafePathInput(resolvedSessionId)) {
+                printResult(io, fail('request.transition', 'INVALID_SESSION_ID', `Invalid session id: ${resolvedSessionId} (must be a single path segment)`, { provided: resolvedSessionId }, ['Pass a session id that is a single path segment']), options.json);
+                process.exitCode = 1;
+                return;
+            }
             if (resolvedSessionId === undefined) {
                 const { showRequestArtifact: showForSession } = await import('../../services/artifacts/request-artifact-service.js');
                 const located = await showForSession({ projectRoot: options.project, role, requestId });

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

@@ -408,7 +408,7 @@ export function registerScanCommands(program, io) {
             });
             const nextActions = [];
             if (report.gateAction === 'block') {
-                nextActions.push('Karpathy review file missing under scope=all. Per karpathy §1 Think Before Coding, create rd/karpathy-review.md before requesting qa-handoff.');
+                nextActions.push('Karpathy review file missing under scope=all. Per karpathy §1 Think Before Coding, the rd:qa-handoff gate wants rd/karpathy-review-<rid>.md; this scanner has no rid and reads only the back-compat name rd/karpathy-review.md, so it cannot go green on the rid-scoped name alone. `peaks request transition --state qa-handoff` is the authoritative gate.');
             }
             else if (report.gateAction === 'warn') {
                 nextActions.push(`Karpathy review emitted ${report.totalViolations} violation(s). Review the warnings and re-run after cleanup (karpathy §3 Surgical Changes).`);

package/dist/cli/commands/security-audit-commands.js

@@ -46,6 +46,7 @@ export function registerSecurityAuditCommands(program, io) {
         .option('--project <path>', 'project root (default: cwd)')).action((options) => {
         const projectRoot = options.project ?? process.cwd();
         const sid = options.sid;
+        const rid = options.rid;
         if (sid === undefined || sid.length === 0) {
             printResult(io, fail('security-audit.detect', 'SID_REQUIRED', 'session id (--sid) is required for security-audit.detect', { state: 'sid-missing' }, ['Pass --sid <session-id> (e.g. 2026-06-27-session-...)', 'Run `peaks session info --active --json` to find the active sid.']), options.json);
             process.exitCode = 1;
@@ -55,6 +56,7 @@ export function registerSecurityAuditCommands(program, io) {
             const detect = detectSecurityAudit({
                 projectRoot,
                 sessionId: sid,
+                ...(rid !== undefined ? { requestId: rid } : {}),
             });
             const envelope = detect.state === 'ready'
                 ? ok('security-audit.detect', detect, [...detect.warnings], [...detect.nextActions])

package/dist/cli/commands/slice-integrate-commands.js

@@ -9,10 +9,15 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { integrateSlices } from '../../services/slice/slice-integration.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 function loadContractsForSlices(projectRoot, sessionId, sliceIds) {
+    // Sid axis: `--session-id` reaches this join unmodified.
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
     const dir = resolve(projectRoot, '.peaks', '_runtime', sessionId, 'dispatch', 'contracts');
     if (!existsSync(dir))
         return [];

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

@@ -6,11 +6,39 @@ import { renderStatusLine, resolveStatusLineCapability, } from '../../services/s
 import { applyStatusLineInstall, planStatusLineInstall, removeStatusLineInstall } from '../../services/skills/statusline-settings-service.js';
 import { readHookStatus as readSettingsStatus } from '../../services/skills/hooks-settings-service.js';
 import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
+import { resolveIdeOptionHelp } from '../../services/ide/ide-registry.js';
 import { decideCompactStatusline, renderCompactStatusline, } from '../../services/compact-statusline/compact-statusline-service.js';
 import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+import { writeHarnessWitness } from '../../services/context/harness-context-witness.js';
 const STDIN_READ_TIMEOUT_MS = 250;
-/** Read piped stdin if present; resolve quickly with '' when attached to a TTY. */
+/**
+ * Read piped stdin if present; resolve quickly with '' when attached to a TTY.
+ *
+ * `PEAKS_STATUSLINE_STDIN` is a test seam (same shape as the `PEAKS_HOOK_STDIN`
+ * seam in `gate-commands.ts`): the harness payload is the only channel that
+ * carries the harness's own context numbers, and a test that cannot supply one
+ * cannot verify the capture at all.
+ *
+ * WHY THIS SEAM IS ACCEPTABLE ON A DIFFERENT ARGUMENT (repair cycle 3). The
+ * precedent does not transfer by itself: `PEAKS_HOOK_STDIN` is defended in
+ * `.peaks/memory/peaks-hook-stdin-test-seam-pattern.md` because its payload
+ * still routes through the `enforceBashCommand` SOP gate. This payload is
+ * routed through no gate — it is PERSISTED verbatim as the record the witness
+ * guard then reads. So the compensating control is different, not absent: the
+ * record is observation-only and one-way. It reaches only `data` and the
+ * `warnings` / `nextActions` arrays of `peaks code context-now`; the compact
+ * `action` there is computed from `probe.ratio` alone, before and independently
+ * of the witness. A forged payload can therefore make the instrument lie —
+ * measured: a hand-written record yields a confident false `agree`, or a
+ * self-contradictory false `disagree` — and can do nothing else. What it cannot
+ * do is fire, block or delay a compact. Unconditional rather than NODE_ENV-
+ * gated, for the reason already recorded for the sibling seam.
+ */
 function readStdin() {
+    const override = process.env['PEAKS_STATUSLINE_STDIN'];
+    if (override !== undefined) {
+        return Promise.resolve(override);
+    }
     return new Promise((resolve) => {
         if (process.stdin.isTTY) {
             resolve('');
@@ -82,6 +110,18 @@ export async function runDefaultStatuslineRender(options, io) {
     // subprocess sat descheduled. Production callers omit the flag.
     const now = options.now !== undefined ? Number(options.now) : Date.now();
     const model = buildStatusLineModel(seeded, now);
+    // Slice 2026-09-13-statusline-window-witness (AC1): capture the harness's OWN
+    // context numbers from the payload it just piped in. The project root and the
+    // canonical session id are taken from the model that was JUST built, so the
+    // witness lands under the same session this render already resolved — a second
+    // resolution here could disagree with it. Never throws; never changes the
+    // rendered line.
+    writeHarnessWitness({
+        projectRoot: model.projectRoot,
+        sessionId: model.sessionId,
+        stdin,
+        nowMs: now,
+    });
     const capability = resolveStatusLineCapability({
         env: process.env,
         isTTY: Boolean(process.stdout.isTTY),
@@ -136,7 +176,7 @@ export function registerStatusLineCommands(program, io) {
         .description("Install the Peaks status line into the adapter's settings.json (project scope by default).")
         .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
-        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')
+        .option('--ide <id>', resolveIdeOptionHelp())
         .option('--force', 'overwrite an existing non-Peaks statusLine entry')
         .option('--dry-run', 'show what would change without writing')).action((options) => {
         const scope = resolveScope(options);
@@ -173,7 +213,7 @@ export function registerStatusLineCommands(program, io) {
         .description("Remove the Peaks status line from the adapter's settings.json.")
         .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
-        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        .option('--ide <id>', resolveIdeOptionHelp())).action((options) => {
         const scope = resolveScope(options);
         const projectRoot = scope === 'project'
             ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())
@@ -194,7 +234,7 @@ export function registerStatusLineCommands(program, io) {
         .description('Report whether the Peaks status line is installed in the adapter settings.json.')
         .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
-        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        .option('--ide <id>', resolveIdeOptionHelp())).action((options) => {
         const scope = resolveScope(options);
         const projectRoot = scope === 'project'
             ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())

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) {