peaks-loop 4.0.46 → 4.0.48

package/dist/cli/commands/compact-command.js

@@ -4,9 +4,53 @@ import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { writeCheckpoint } from '../../services/session/session-checkpoint-service.js';
 import { getSessionIdCanonical } from '../../services/session/session-manager.js';
-import { readCompactHistory, summarizeCompactHistory, } from '../../services/compact-history/compact-history-service.js';
+import { computeWindowCalibration, readCompactHistory, summarizeCompactHistory, } from '../../services/compact-history/compact-history-service.js';
+import { readHarnessWindowState, resolveHarnessWindowLocation } from '../../services/context/auto-compact-reader.js';
+import { disableHarnessWindowSync, reenableHarnessWindowSync, resetHarnessWindow } from '../../services/context/harness-window-config.js';
 import { buildRecommendEnvelopePure, dryRunCompact, suggestCompact } from '../../services/compact/suggest-service.js';
 import { PHASES, SURVIVAL_TABLE, isPhase, lookupPhaseTransition } from '../../services/compact/decision-tables.js';
+import { readSessionIdFromHookPayload, readTriggerFromHookPayload, settleCompactFromHarnessEvent } from '../../services/code/compact-event-settle.js';
+/**
+ * Read the `PostCompact` hook payload from stdin.
+ *
+ * `PEAKS_HOOK_STDIN` is the test seam, verbatim the one `peaks gate enforce`
+ * uses (`gate-commands.ts`) — the CLI side owns `process.stdin`'s lifecycle, so
+ * the reader lives with the command rather than in the service.
+ *
+ * Returns `null` for every shape that is not a JSON object: empty stdin, a TTY
+ * (the `--json` diagnostic path run by a human), malformed JSON. A payload that
+ * cannot be read is not a failure — it is a payload with no `trigger`, which is
+ * an input this path is explicitly designed to accept.
+ */
+async function readHookPayload() {
+    const override = process.env.PEAKS_HOOK_STDIN;
+    let raw;
+    if (override !== undefined) {
+        raw = override;
+    }
+    else if (process.stdin.isTTY) {
+        raw = '';
+    }
+    else {
+        raw = await new Promise((resolveStdin) => {
+            let data = '';
+            process.stdin.setEncoding('utf8');
+            process.stdin.on('data', (chunk) => {
+                data += chunk;
+            });
+            process.stdin.on('end', () => resolveStdin(data));
+            process.stdin.on('error', () => resolveStdin(data));
+        });
+    }
+    if (raw.trim().length === 0)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
 function splitList(value) {
     if (!value)
         return [];
@@ -288,9 +332,16 @@ export function registerCompactCommands(program, io) {
                 return;
             }
             const summary = summarizeCompactHistory(result.events);
+            // Slice 2026-09-13-auto-compact-trigger-ownership (T4): the
+            // intent-vs-observed record. `pairs[i].requestedTokens` is the token
+            // point peaks-loop asked for; `observedTokens` is what the next real
+            // session actually measured. Unmeasured pairs are reported as such —
+            // this instrument states what happened, it does not predict.
+            const windowCalibration = computeWindowCalibration(result.events);
             printResult(io, ok('compact.history', {
                 sessionId: session.sid,
                 ...summary,
+                windowCalibration,
                 events: result.events,
                 parseErrors: result.parseErrors,
                 historyPath: result.path,
@@ -301,4 +352,193 @@ export function registerCompactCommands(program, io) {
             process.exitCode = 1;
         }
     }));
+    // 7. peaks compact harness-window [--reset | --disable | --reenable]
+    //    (slice 2026-09-13-auto-compact-trigger-ownership, T1 + T2)
+    //
+    // The window peaks-loop divides by and the window the harness compacts
+    // against must be ONE number, or "95%" lands at two different token counts.
+    // This command is the visible half of that write: the default reports what
+    // is in force, `--reset` removes it, `--disable` stops managing it.
+    //
+    // There is deliberately NO `--sync` flag. Materializing the window requires
+    // the ratio's own denominator, which only a probe has (it is the only place
+    // the active model is known). A `--sync` that re-derived the window here
+    // would be the second, independent resolution this slice exists to delete —
+    // `peaks code context-now` and `peaks code auto-compact` already sync.
+    addJsonOption(compact
+        .command('harness-window')
+        .description('Report / roll back the auto-compact window peaks-loop writes into the ' +
+        'harness\'s own machine-local settings (the adapter-declared ' +
+        'autoCompactWindowEnvVar, e.g. CLAUDE_CODE_AUTO_COMPACT_WINDOW in ' +
+        '.claude/settings.local.json). peaks-loop computes its context ratio ' +
+        'against exactly this number, so the value it reports as "85%" and the ' +
+        'point the harness compacts at are the same. Context probes ' +
+        '(`peaks code context-now`, `peaks code auto-compact`) materialize it ' +
+        'automatically. Two different intentions, two verbs: --reset removes ' +
+        'the key AND opts the project out so later probes do not put it back ' +
+        '(when the file holds no peaks-loop row at all there is nothing to ' +
+        'roll back, so --reset writes nothing); --disable records the opt-out ' +
+        'only, leaving whatever value is already there untouched, so "stop ' +
+        'managing this key" works on a project peaks-loop has never written ' +
+        'to; --reenable undoes either opt-out.')
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--reset', 'rollback: remove the window key and stop managing it')
+        .option('--disable', 'record the opt-out only (do not manage this key), without removing a value that is already there; expressible before the first write')
+        .option('--reenable', 'undo a --reset or --disable opt-out (peaks-loop manages it again)')
+        .action((options) => {
+        try {
+            const project = options.project !== undefined
+                ? resolveCanonicalProjectRoot(options.project)
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const location = resolveHarnessWindowLocation({ projectRoot: project, env: process.env });
+            if (location === null) {
+                printResult(io, ok('compact.harness-window', {
+                    projectRoot: project,
+                    managed: false,
+                    message: 'The active IDE adapter declares no auto-compact window key, so peaks-loop cannot tie ' +
+                        'the harness window to its own ratio. Nothing was written and there is nothing to roll back.',
+                }), options.json);
+                return;
+            }
+            if (options.reset === true) {
+                const result = resetHarnessWindow({ location, env: process.env });
+                printResult(io, ok('compact.harness-window', {
+                    projectRoot: project,
+                    action: result.action,
+                    key: location.envVar,
+                    settingsPath: result.settingsPath,
+                    previousTokens: result.previousTokens,
+                }, [], [
+                    result.action === 'removed'
+                        ? `Removed ${location.envVar} from ${result.settingsPath} and opted this project out, so later probes stop writing it. Undo with \`peaks compact harness-window --reenable\`.`
+                        : `Nothing to remove — ${location.envVar} was already absent from ${result.settingsPath}, so nothing was written and no opt-out row was recorded: if a probe writes a window here later, run --reset again to remove it. To say "never manage this key here" WITHOUT waiting for that first write, run \`peaks compact harness-window --disable\`.`,
+                ]), options.json);
+                return;
+            }
+            if (options.disable === true) {
+                const result = disableHarnessWindowSync({ location });
+                printResult(io, ok('compact.harness-window', {
+                    projectRoot: project,
+                    action: result.action,
+                    key: location.envVar,
+                    settingsPath: result.settingsPath,
+                }, [], [
+                    result.action === 'disabled'
+                        ? `Recorded the opt-out in ${result.settingsPath}: peaks-loop will not write ${location.envVar} here, and left any value already in the file exactly as it was. Undo with \`peaks compact harness-window --reenable\`.`
+                        : result.action === 'already-opted-out'
+                            ? `Already opted out — ${result.settingsPath} carries ${location.envVar}'s opt-out, so nothing was written. Undo with \`peaks compact harness-window --reenable\`.`
+                            : result.action === 'refused-unsafe-project-root'
+                                ? `Nothing written: the resolved project root is the user's own home directory, so ${result.settingsPath} is their PERSONAL harness settings, not a project's. peaks-loop already refuses to write ${location.envVar} there, so an opt-out would change nothing except which refusal you see. Point --project at a project (a subdirectory of home is fine) and the opt-out lands there.`
+                                : `Nothing written — ${result.settingsPath} is not a JSON object peaks-loop can safely edit, so the opt-out could not be recorded there.`,
+                ]), options.json);
+                return;
+            }
+            if (options.reenable === true) {
+                const result = reenableHarnessWindowSync({ location });
+                printResult(io, ok('compact.harness-window', { projectRoot: project, action: result.action, key: location.envVar, settingsPath: result.settingsPath }, [], [
+                    result.action === 'reenabled'
+                        ? 'Opt-out cleared; the next context probe will materialize the window again.'
+                        : 'No opt-out was recorded for this project.',
+                ]), options.json);
+                return;
+            }
+            const state = readHarnessWindowState({ projectRoot: project, env: process.env });
+            printResult(io, ok('compact.harness-window', {
+                projectRoot: project,
+                managed: true,
+                key: location.envVar,
+                settingsPath: location.settingsPath,
+                tokens: state?.tokens ?? null,
+                raw: state?.raw ?? null,
+                source: state?.source ?? null,
+                optedOut: state?.optedOut ?? false,
+                // Provenance: whether this value is peaks-loop's own write or
+                // one the user set by hand. It decides whether the late 1M
+                // rescue may override it, so it is not just diagnostics.
+                peakWritten: state?.peakWritten ?? false,
+            }, [], [
+                state?.tokens === null || state?.tokens === undefined
+                    ? 'No window is set yet. The next `peaks code context-now` probe materializes the window it computes its ratio against.'
+                    : `peaks-loop computes its context ratio against ${state.tokens} tokens; the harness fires near the end of that window. ${state.peakWritten
+                        ? 'peaks-loop wrote this value; it may raise it if a session outgrows it.'
+                        : 'This value is not peaks-loop\'s own write, so peaks-loop will not raise it — it is treated as your setting.'}`,
+                'Rollback: `peaks compact harness-window --reset`.',
+                'Intent-vs-observed calibration: `peaks compact history --json` → windowCalibration.',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.harness-window', 'COMPACT_HARNESS_WINDOW_FAILED', getErrorMessage(error), {}, ['Verify the project path is writable and a session is bound']), options.json);
+            process.exitCode = 1;
+        }
+    }));
+    // 8. peaks compact settle [--json]
+    //    (slice 2026-09-13-compact-event-settle)
+    //
+    // The `PostCompact` hook's transport. Before this command, peaks-loop knew a
+    // compaction had landed only because a LATER probe measured a ratio that had
+    // fallen — an inference. This command lets the harness's own event settle the
+    // run, and records what the harness said the compaction WAS (`manual` /
+    // `auto`), which is the one question a ratio can never answer.
+    //
+    // STDOUT IS CONTEXT HERE. `PostCompact`'s output contract is truncated in the
+    // retrievable docs, so the safe assumption is the `SessionStart` one: stdout
+    // is added to the model's context. The hook path therefore prints NOTHING and
+    // exits 0 for every outcome — success, no open run, unresolvable session,
+    // unparseable stdin. An error sentence in the model's context is a false
+    // problem handed to it mid-slice. Same discipline as `session reinject`;
+    // `--json` is the diagnostic surface, and the hook never passes it.
+    addJsonOption(compact
+        .command('settle')
+        .description('PostCompact hook handler: settle the open compact run because the HARNESS reported a ' +
+        'compaction completed, and append an `observed` compact-history row carrying the ' +
+        'harness-reported trigger (manual | auto). Reads the hook JSON on stdin; prints nothing ' +
+        'and exits 0 when run by the hook. Pass --json for the diagnostic envelope.')
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding)')).action(async (options) => {
+        // One parse, two fields: reading stdin twice would let the two readers
+        // disagree about the payload they were handed.
+        const payload = await readHookPayload();
+        const trigger = readTriggerFromHookPayload(payload);
+        const hookSessionId = readSessionIdFromHookPayload(payload);
+        // The hook path returns before any `process.exitCode` assignment below, so
+        // the harness never sees a non-zero exit from this command.
+        try {
+            const project = options.project !== undefined
+                ? resolveCanonicalProjectRoot(options.project)
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const session = resolveSessionId(project, options.sessionId);
+            if (session.error !== null) {
+                if (options.json !== true)
+                    return;
+                printResult(io, fail('compact.settle', session.error.code, session.error.message, { projectRoot: project }, session.error.nextActions), true);
+                return;
+            }
+            const result = settleCompactFromHarnessEvent({
+                projectRoot: project,
+                sessionId: session.sid,
+                trigger,
+                hookSessionId
+            });
+            if (options.json !== true)
+                return;
+            printResult(io, ok('compact.settle', { projectRoot: project, sessionId: session.sid, trigger: trigger ?? null, ...result }, [], [
+                result.settled
+                    ? result.lifecycleWritten
+                        ? result.historyWritten
+                            ? `Settled run ${result.runId}; appended a kind:'observed' row with pathway 'post-compact-hook'.`
+                            : `Settled run ${result.runId}, but the kind:'observed' row could NOT be appended — check that .peaks/_runtime/<sid>/ is writable.`
+                        : `The harness reported a compaction for run ${result.runId}, but the lifecycle record could NOT be written — that run is still open, so a later probe will settle it from its own measurement.${result.historyWritten
+                            ? " A kind:'observed' row was still appended for this event."
+                            : " The kind:'observed' row could not be appended either."}`
+                    : result.reason === 'different-session'
+                        ? `The hook payload names a different harness session, so this project's open compact run was left alone.`
+                        : 'No compact run was open, so nothing was settled and no history row was appended.'
+            ]), true);
+        }
+        catch (error) {
+            if (options.json !== true)
+                return;
+            printResult(io, fail('compact.settle', 'COMPACT_SETTLE_FAILED', getErrorMessage(error), {}, ['Verify the project path and session binding']), true);
+        }
+    });
 }

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

@@ -91,10 +91,11 @@ function registerConfigMigrationCommands(config, io) {
             printResult(io, ok('config.rollback', { ...plan, applied: false }), options.json);
         }
         catch (error) {
+            // No `NO_BACKUP` branch: a missing `.bak` is no longer an error, it is
+            // an `available: false` SUCCESS envelope (see `config-rollback.ts`).
             const message = getErrorMessage(error);
-            const code = message.startsWith('NO_BACKUP') ? 'NO_BACKUP' : 'CONFIG_ROLLBACK_FAILED';
-            io.stderr(`${code}: ${message}`);
-            printResult(io, fail('config.rollback', code, message, {}, ['Re-run peaks config migrate --apply to recreate the .bak']), options.json);
+            io.stderr(`CONFIG_ROLLBACK_FAILED: ${message}`);
+            printResult(io, fail('config.rollback', 'CONFIG_ROLLBACK_FAILED', message, {}, ['Re-run peaks config migrate --apply to recreate the .bak']), options.json);
             process.exitCode = 1;
         }
     });
@@ -108,9 +109,14 @@ function registerConfigMigrationCommands(config, io) {
         .option('--json', 'JSON envelope output')
         .action((options) => {
         try {
+            // `available` is on every envelope this command prints (see
+            // `config-restore.ts`): `false` ⇒ this machine has no `.bak`, exit 0,
+            // nothing to restore; `true` on a FAILURE envelope ⇒ the backup is
+            // there and the field/guard was the problem, exit 1. One key replaces
+            // the exit code as the "was there ever a backup?" signal.
             if (options.list === true || !options.field) {
-                const fields = listAvailableFields();
-                printResult(io, ok('config.restore', { fields, applied: false }), options.json);
+                const { available, fields } = listAvailableFields();
+                printResult(io, ok('config.restore', { available, fields, applied: false }), options.json);
                 return;
             }
             const apply = options.apply === true;
@@ -119,15 +125,15 @@ function registerConfigMigrationCommands(config, io) {
         }
         catch (error) {
             const message = getErrorMessage(error);
+            // A missing `.bak` no longer reaches this block, so anything that does
+            // implies the backup exists — which is what `available: true` reports.
             let code = 'CONFIG_RESTORE_FAILED';
-            if (message.startsWith('NO_BACKUP'))
-                code = 'NO_BACKUP';
-            else if (message.startsWith('RESTORE_GUARDED'))
+            if (message.startsWith('RESTORE_GUARDED'))
                 code = 'RESTORE_GUARDED';
             else if (message.startsWith('FIELD_NOT_FOUND'))
                 code = 'FIELD_NOT_FOUND';
             io.stderr(`${code}: ${message}`);
-            printResult(io, fail('config.restore', code, message, {}, ['Use --list to see available fields']), options.json);
+            printResult(io, fail('config.restore', code, message, { available: true, ...(options.field !== undefined ? { field: options.field } : {}) }, ['Use --list to see available fields']), options.json);
             process.exitCode = 1;
         }
     });

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

@@ -37,7 +37,7 @@ function detectContainerRuntime(explicit) {
     const tryOrder = explicit ? [explicit] : ['docker', 'podman'];
     for (const r of tryOrder) {
         try {
-            const version = execSync(`${r} --version`, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' }).trim();
+            const version = execSync(`${r} --version`, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', windowsHide: true }).trim();
             return { ok: true, runtime: r, binary: `${r} (${version.split('\n')[0] ?? ''})` };
         }
         catch {
@@ -117,7 +117,7 @@ export function registerContainerCommand(program, io) {
             // when the lease file is missing.
             const cidFile = `${normalizePath(joinPathSession(projectRoot, sessionId))}/.${runtime.runtime}-cid-${leaseId}`;
             try {
-                execSync(`${runtime.runtime} run --rm -d --cidfile "${cidFile}" --label "peaks.leaseId=${leaseId}" --label "peaks.rid=${options.rid}" -v "${mount}:/work" -w /work ${image} sleep infinity`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+                execSync(`${runtime.runtime} run --rm -d --cidfile "${cidFile}" --label "peaks.leaseId=${leaseId}" --label "peaks.rid=${options.rid}" -v "${mount}:/work" -w /work ${image} sleep infinity`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8', windowsHide: true });
             }
             catch (err) {
                 printResult(io, fail('container.spawn', 'DOCKER_RUN_FAILED', getErrorMessage(err), { rid: options.rid, image, runtime: runtime.runtime, sessionId }, [
@@ -199,7 +199,7 @@ export function registerContainerCommand(program, io) {
             try {
                 const releaseRuntime = detectContainerRuntime(undefined);
                 const runtimeCmd = releaseRuntime.ok ? releaseRuntime.runtime : 'docker';
-                execSync(`${runtimeCmd} rm --force "${lease.containerId}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+                execSync(`${runtimeCmd} rm --force "${lease.containerId}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8', windowsHide: true });
             }
             catch {
                 dockerRmFailed = true;

package/dist/cli/commands/core/skill-command.js

@@ -307,17 +307,18 @@ export function registerSkillCommand(program, io) {
     });
     addJsonOption(skill
         .command('presence:clear')
-        .description('Clear the active Peaks skill presence indicator. Slice 4.0.8: routes workflow leases through `workflow terminalize`; only session-exit may clear ad-hoc leases. Raw unlink is FORBIDDEN.')
+        .description('Unlink the DEPRECATED pre-4.0.11 single-slot presence marker files (`.peaks/_runtime/active-skill.json`, `.peaks/.active-skill.json`). It does NOT terminalize a live presence lease — a workflow-bound lease terminalizes through `peaks workflow terminalize --workflow <id> --reason <reason>`, an ad-hoc lease only at session exit, and raw unlink is FORBIDDEN for both. The envelope reports what is still active.')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action(async (options) => {
         const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        // Slice 4.0.8 (DR): `presence:clear` is a workflow terminalizer,
-        // not a raw unlink. For workflow-bound leases the call is routed
-        // through `workflow terminalize` (canonical in
-        // workflow-presence-lifecycle.ts). Ad-hoc (non-workflow) leases
-        // remain terminalizable only via session exit. We delegate to the
-        // compat shim `clearSkillPresence`, which the compat wrapper
-        // re-routes to `terminalizePresenceLease` when a workflow
-        // binding is present.
+        // What this command actually is: a stale-marker cleanup for projects
+        // carrying a pre-4.0.11 single-slot file, and nothing more. The previous
+        // description claimed it "routes workflow leases through `workflow
+        // terminalize`" and that a "compat wrapper re-routes [it] to
+        // `terminalizePresenceLease` when a workflow binding is present" — there is
+        // no such wrapper, and no such routing happens here or in
+        // `clearSkillPresence`. A caller who read that line and ran this command
+        // expecting a live workflow lease to terminalize got a successful exit code
+        // and a still-running lease.
         const removed = clearSkillPresence(options.project);
         // Auto-update project context so future sessions have up-to-date history.
         // Slice 2026-07-15-project-scan-bootstrap: generateProjectContext now also
@@ -329,7 +330,41 @@ export function registerSkillCommand(program, io) {
         catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
             // non-fatal: context update failure should not block presence clear
         }
-        printResult(io, ok('skill.presence:clear', { active: false, removed, projectContextUpdated: true }), options.json);
+        // Report the state the project is actually in, not the state this command
+        // intended to reach. `clearSkillPresence` unlinks only the DEPRECATED
+        // single-slot marker files; the canonical sid-scoped lease is deliberately
+        // left alive for an AD-HOC lease (raw unlink is FORBIDDEN — only session
+        // exit may terminalize one; workflow leases route through `workflow
+        // terminalize`). So after a `presence:set` the very next `peaks skill
+        // presence` call still reads `active: true`. A hardcoded `active: false`
+        // therefore reported a state the command never reached, and the caller had
+        // no way to tell that from a real clear.
+        //
+        // Re-reading through `getSkillPresence` — the same projection the
+        // `skill presence` command serves — is the only derivation that cannot
+        // drift from what the next command prints: it is the same read path, on
+        // the same project root, evaluated after every write this command makes.
+        const active = getSkillPresence(projectRoot) !== null;
+        // `cleared` is the live question the caller is actually asking ("is it gone
+        // now?"), which `removed` could never answer: a legacy marker being unlinked
+        // says nothing about the lease the next command will read. When it is false
+        // the envelope says WHY, in the two routes that can terminalize a lease —
+        // without this the caller saw `active: true, removed: false` and had no way
+        // to tell "you ran the wrong command" from "this command has no opinion".
+        const cleared = !active;
+        printResult(io, ok('skill.presence:clear', {
+            active,
+            removed,
+            cleared,
+            ...(cleared ? {} : { reason: 'live-lease-survives-presence-clear' }),
+            projectContextUpdated: true
+        }, [], cleared
+            ? []
+            : [
+                'A workflow-bound lease terminalizes through `peaks workflow terminalize --workflow <id> --reason <reason>`.',
+                'An ad-hoc lease (`peaks skill presence:set`) is terminalizable only at session exit; `presence:clear` will not remove it, and raw unlink is FORBIDDEN.',
+                'Run `peaks skill presence --json` to read the lease that survived.'
+            ]), options.json);
     });
     // Slice 4.0.8 (RD §4): manual lease GC primitive. LLM-coordinated;
     // never a user-typed requirement. The user / LLM runner invokes

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

@@ -148,7 +148,8 @@ export function runTask(projectRoot, task) {
             cwd: projectRoot,
             stdio: ['ignore', 'pipe', 'pipe'],
             encoding: 'utf8',
-            timeout: EXEC_TIMEOUT_MS
+            timeout: EXEC_TIMEOUT_MS,
+            windowsHide: true
         });
     }
     catch (err) {

package/dist/cli/commands/dashboard-long-run.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { read24hState } from '../../services/24h-mode/index.js';
 import { getErrorMessage } from '../cli-helpers.js';
 const SINCE_PATTERN = /^(\d+)([smhd])$/i;
@@ -24,6 +25,11 @@ function parseSince(raw) {
     return { ok: true, ms: Math.min(WINDOW_CAP_MS, value * multiplier) };
 }
 function readSlices(projectRoot, sessionId) {
+    // Sid axis: `--session-id` reaches this join unmodified, and a traversal
+    // value resolved `metrics/slices.jsonl` outside every project root.
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
     const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'metrics', 'slices.jsonl');
     if (!existsSync(path))
         return 0;

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

@@ -127,7 +127,17 @@ export function registerDispatchCommand(parent, io) {
                         ? { maxConcurrent }
                         : {}),
                 });
-                printResult(io, ok(result.command, result.data, result.warnings ?? [], result.nextActions ?? []), asJson);
+                // The handler's `ok` is the launch outcome (a vendor CLI that is not
+                // installed is a failure, not a footnote) — the caller must not
+                // re-wrap it as `ok()` unconditionally, which is how `ok: true` with
+                // `pid: -1` reached the orchestrator.
+                if (result.ok) {
+                    printResult(io, ok(result.command, result.data, result.warnings ?? [], result.nextActions ?? []), asJson);
+                }
+                else {
+                    printResult(io, fail(result.command, 'DISPATCH_DETACHED_SPAWN_FAILED', `Could not launch the vendor CLI for a detached dispatch; nothing was started.`, result.data, result.nextActions ?? []), asJson);
+                    process.exitCode = 1;
+                }
             }
             catch (error) {
                 printResult(io, fail('sub-agent.dispatch', 'DISPATCH_DETACHED_ERROR', getErrorMessage(error), {

package/dist/cli/commands/doctor/invoke-from-code.js

@@ -7,7 +7,13 @@
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isUnsafePathInput } from '../../../shared/path-safety.js';
 export async function doctorInvokeFromCode(opts) {
+    // Sid axis: `opts.sid` is the sole path segment between the runtime root and
+    // the write below, and nothing upstream validated it.
+    if (isUnsafePathInput(opts.sid)) {
+        throw new Error(`Invalid session id: ${opts.sid} (must be a single path segment)`);
+    }
     const dir = join('.peaks', '_runtime', opts.sid, 'doctor');
     mkdirSync(dir, { recursive: true });
     const proposalPath = join(dir, 'proposal.md');

package/dist/cli/commands/e2e-verify.js

@@ -17,7 +17,7 @@ async function probeChromiumBinary() {
     const finder = process.platform === 'win32' ? 'where' : 'which';
     for (const candidate of candidates) {
         try {
-            const result = nodeSpawn(finder, [candidate], { stdio: ['ignore', 'pipe', 'pipe'] });
+            const result = nodeSpawn(finder, [candidate], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
             const stdout = await new Promise((resolve, reject) => {
                 let buf = '';
                 result.stdout.on('data', (chunk) => { buf += chunk.toString('utf8'); });
@@ -33,7 +33,7 @@ async function probeChromiumBinary() {
             const firstLine = stdout.split(/\r?\n/)[0]?.trim();
             if (!firstLine)
                 continue;
-            const probe = nodeSpawn(firstLine, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'] });
+            const probe = nodeSpawn(firstLine, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
             const exitCode = await new Promise((resolve) => {
                 probe.on('close', (code) => resolve(code ?? 1));
                 probe.on('error', () => resolve(1));
@@ -114,7 +114,7 @@ async function runOneFixtureWithPlaywright(fixture, env) {
                 `--profile-directory=${env.profileName}`,
                 `--dump-dom`,
                 fixture.url,
-            ], { stdio: ['ignore', 'pipe', 'ignore'] });
+            ], { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
             let html = '';
             proc.stdout.on('data', (chunk) => { html += chunk.toString('utf8'); });
             proc.on('error', () => settle({ pass: false, reason: 'chromium-spawn-failed' }));

package/dist/cli/commands/governance-classify-contract-commands.js

@@ -154,6 +154,7 @@ function getSignalsFromGitDiff(projectRoot) {
             cwd: projectRoot,
             stdio: ['ignore', 'pipe', 'ignore'],
             maxBuffer: 32 * 1024 * 1024,
+            windowsHide: true,
         }).toString('utf8');
     }
     catch {

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);
@@ -339,6 +339,15 @@ export function registerHooksCommands(program, io) {
             // through verbatim so the envelope reflects reality. The desired
             // list is also included for parity with install / uninstall.
             const onDiskDeny = readOnDiskDenyEntries(settings);
+            // `status` reports the state of the world; for an IDE that cannot host a
+            // hook the state of the world is "none, and none is possible". The exit
+            // code stays 0 (the query succeeded) and the payload carries the finding
+            // — `supportsHooks: false` on the data, plus a warning naming the IDE, so
+            // the negative fact is not confused with "supported IDE, nothing
+            // installed yet".
+            const warnings = status.supportsHooks
+                ? []
+                : [`IDE '${ide}' cannot host peaks hooks (no HOOK_COMMAND_BY_IDE entry); nothing can be installed for it, which is why none is.`];
             printResult(io, ok('hooks.status', {
                 ...status,
                 ide,
@@ -348,7 +357,7 @@ export function registerHooksCommands(program, io) {
                 ],
                 permissionsDenyEntries: listSuperpowersDenyEntries(),
                 permissionsDenyOnDisk: onDiskDeny
-            }), options.json);
+            }, warnings), options.json);
         }
         catch (error) {
             const message = getErrorMessage(error);

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

@@ -77,6 +77,7 @@ export function registerLoopCommands(program, io) {
             const stdout = execFileSync('node', ['bin/peaks.js', ...args], {
                 cwd: options.project,
                 stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
             }).toString('utf-8');
             printResult(io, ok('loop.distill', {
                 project: options.project,