peaks-loop 4.0.46 → 4.0.47

package/dist/cli/commands/reinject-command.d.ts

@@ -0,0 +1,72 @@
+/**
+ * rid `2026-09-13-a2-post-compact-reinject` —
+ * `peaks session reinject --project <path>`.
+ *
+ * The transport for `buildPostCompactReinjectionCard`. A Claude Code
+ * `SessionStart` hook (installed by `peaks hooks install`, matcher `compact`)
+ * runs this and Claude Code adds its stdout to the context — which is the
+ * whole mechanism by which the engineering state comes back after a
+ * compaction. See `src/services/context/post-compact-reinjection.ts` for what
+ * the card says and why it has a byte budget.
+ *
+ * THE ONE THING THIS FILE HAS TO GET RIGHT
+ *
+ * stdout IS context here. Every other peaks command treats stdout as a
+ * channel for a human or a JSON consumer; this one's stdout is pasted in
+ * front of the model as though it were something peaks-loop meant to say.
+ * Two consequences, and both are the reason the code below looks the way it
+ * does:
+ *
+ *   1. The card is printed VERBATIM — no `printResult`, no envelope, no
+ *      `next:` lines, no JSON on the card path. Anything else would be
+ *      injected too, and a `{"ok":true,...}` blob in the context is noise the
+ *      model then has to interpret.
+ *   2. A FAILURE PRINTS NOTHING. Not an error, not a warning, not a hint. An
+ *      error message on stdout would be injected into the context as a fact,
+ *      and a model that reads `REINJECT_FAILED: project root must be
+ *      canonical` in its own context has been handed a false problem to solve
+ *      mid-slice. So every failure path exits 0 with empty stdout, and the
+ *      reason is reported only through `--json` (which the hook never passes).
+ *      This is `failure-soft` for a SessionStart hook: the session must start
+ *      whether or not there is any state to re-inject.
+ *
+ * `--json` exists for the human/diagnostic path — `peaks session reinject
+ * --json` is how you inspect what the hook would inject without reading a
+ * transcript. It is deliberately NOT what the hook runs.
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+import { buildPostCompactReinjectionCard } from '../../services/context/post-compact-reinjection.js';
+export type ReinjectOptions = {
+    project: string;
+    json?: boolean;
+    budgetBytes?: string;
+};
+/** Why no card was produced. Reported through `--json` only. */
+export type ReinjectSkipReason = 'empty-project' | 'invalid-project-root' | 'unreadable-project-root';
+export type ReinjectResult = {
+    readonly ok: true;
+    readonly card: ReturnType<typeof buildPostCompactReinjectionCard>;
+} | {
+    readonly ok: false;
+    readonly reason: ReinjectSkipReason;
+    readonly message: string;
+};
+/**
+ * Pure-ish action body, exported so tests can drive it with inputs Commander
+ * would mangle (trailing NUL bytes, whitespace-only paths). Never throws and
+ * never writes to stdout itself — `runReinjectAction` is the IO edge.
+ */
+export declare function buildReinjectResult(opts: ReinjectOptions): ReinjectResult;
+/**
+ * The IO edge. Returns the process exit code so callers (CLI path or test
+ * path) apply it uniformly. NEVER calls `process.exit`.
+ *
+ * Both branches return 0 on the failure path — see this file's header. The
+ * only way a caller sees `exitCode: 1` is a bug in the `--json` serializer
+ * itself, and even that is caught.
+ */
+export declare function runReinjectAction(opts: ReinjectOptions, io: ProgramIO): {
+    exitCode: 0 | 1;
+};
+export declare function registerReinjectCommand(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,174 @@
+/**
+ * rid `2026-09-13-a2-post-compact-reinject` —
+ * `peaks session reinject --project <path>`.
+ *
+ * The transport for `buildPostCompactReinjectionCard`. A Claude Code
+ * `SessionStart` hook (installed by `peaks hooks install`, matcher `compact`)
+ * runs this and Claude Code adds its stdout to the context — which is the
+ * whole mechanism by which the engineering state comes back after a
+ * compaction. See `src/services/context/post-compact-reinjection.ts` for what
+ * the card says and why it has a byte budget.
+ *
+ * THE ONE THING THIS FILE HAS TO GET RIGHT
+ *
+ * stdout IS context here. Every other peaks command treats stdout as a
+ * channel for a human or a JSON consumer; this one's stdout is pasted in
+ * front of the model as though it were something peaks-loop meant to say.
+ * Two consequences, and both are the reason the code below looks the way it
+ * does:
+ *
+ *   1. The card is printed VERBATIM — no `printResult`, no envelope, no
+ *      `next:` lines, no JSON on the card path. Anything else would be
+ *      injected too, and a `{"ok":true,...}` blob in the context is noise the
+ *      model then has to interpret.
+ *   2. A FAILURE PRINTS NOTHING. Not an error, not a warning, not a hint. An
+ *      error message on stdout would be injected into the context as a fact,
+ *      and a model that reads `REINJECT_FAILED: project root must be
+ *      canonical` in its own context has been handed a false problem to solve
+ *      mid-slice. So every failure path exits 0 with empty stdout, and the
+ *      reason is reported only through `--json` (which the hook never passes).
+ *      This is `failure-soft` for a SessionStart hook: the session must start
+ *      whether or not there is any state to re-inject.
+ *
+ * `--json` exists for the human/diagnostic path — `peaks session reinject
+ * --json` is how you inspect what the hook would inject without reading a
+ * transcript. It is deliberately NOT what the hook runs.
+ */
+import { printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { resolveCanonicalProjectRootStrict, InvalidProjectRootError } from '../../services/config/config-safety.js';
+import { POST_COMPACT_REINJECTION_BYTE_BUDGET, buildPostCompactReinjectionCard } from '../../services/context/post-compact-reinjection.js';
+/**
+ * Parse `--budget-bytes`. Diagnostic only — the production ceiling is the
+ * constant. A value that is not a non-negative integer is REFUSED rather than
+ * coerced, because a coerced budget would silently change what the card
+ * proves (`--budget-bytes 4KiB` becoming `NaN` and then the default would
+ * report a full card while the caller believed they had constrained it).
+ */
+function parseBudget(raw) {
+    if (raw === undefined)
+        return { ok: true, value: null };
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed < 0)
+        return { ok: false };
+    return { ok: true, value: parsed };
+}
+/**
+ * Pure-ish action body, exported so tests can drive it with inputs Commander
+ * would mangle (trailing NUL bytes, whitespace-only paths). Never throws and
+ * never writes to stdout itself — `runReinjectAction` is the IO edge.
+ */
+export function buildReinjectResult(opts) {
+    if (!opts.project || opts.project.trim() === '') {
+        return {
+            ok: false,
+            reason: 'empty-project',
+            message: '--project <path> is required and must be non-empty'
+        };
+    }
+    let projectRoot;
+    try {
+        projectRoot = resolveCanonicalProjectRootStrict(opts.project);
+    }
+    catch (error) {
+        if (error instanceof InvalidProjectRootError) {
+            return {
+                ok: false,
+                reason: 'invalid-project-root',
+                message: `--project is not a usable project root (${error.reason})`
+            };
+        }
+        return {
+            ok: false,
+            reason: 'unreadable-project-root',
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+    const budget = parseBudget(opts.budgetBytes);
+    if (!budget.ok) {
+        return {
+            ok: false,
+            reason: 'invalid-project-root',
+            message: `--budget-bytes must be a non-negative integer, got ${String(opts.budgetBytes)}`
+        };
+    }
+    const card = buildPostCompactReinjectionCard({
+        projectRoot,
+        ...(budget.value !== null ? { budgetBytes: budget.value } : {})
+    });
+    return { ok: true, card };
+}
+/**
+ * The IO edge. Returns the process exit code so callers (CLI path or test
+ * path) apply it uniformly. NEVER calls `process.exit`.
+ *
+ * Both branches return 0 on the failure path — see this file's header. The
+ * only way a caller sees `exitCode: 1` is a bug in the `--json` serializer
+ * itself, and even that is caught.
+ */
+export function runReinjectAction(opts, io) {
+    let result;
+    try {
+        result = buildReinjectResult(opts);
+    }
+    catch (error) {
+        result = {
+            ok: false,
+            reason: 'unreadable-project-root',
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+    if (opts.json === true) {
+        if (!result.ok) {
+            printResult(io, fail('session.reinject', `REINJECT_SKIPPED_${result.reason.replace(/-/g, '_').toUpperCase()}`, result.message, {
+                project: opts.project
+            }, []), true);
+            // A skipped card is a legitimate answer, not a failed command: the hook
+            // that runs this must never report a non-zero exit to the harness.
+            return { exitCode: 0 };
+        }
+        const card = result.card;
+        printResult(io, ok('session.reinject', {
+            sessionId: card.sessionId,
+            budgetBytes: card.budgetBytes,
+            bytes: card.bytes,
+            emittedRanks: card.emittedRanks,
+            droppedRanks: card.droppedRanks,
+            unresolved: card.unresolved,
+            // The payload itself, so a caller can read it without re-running.
+            card: card.text
+        }), true);
+        return { exitCode: 0 };
+    }
+    // The card path — the one the hook uses. Verbatim, and nothing on failure.
+    if (!result.ok)
+        return { exitCode: 0 };
+    if (result.card.text.length > 0)
+        io.stdout(result.card.text);
+    return { exitCode: 0 };
+}
+export function registerReinjectCommand(program, io) {
+    // Reuse the `session` commander group registered by the auto-registration
+    // pass, exactly as `registerPrimerCommand` does — `program.command('session
+    // reinject')` would register a single literal command name instead of a
+    // child of the group, and creating a second `session` group throws.
+    const session = program.commands.find((c) => c.name() === 'session');
+    if (!session) {
+        throw new Error('registerReinjectCommand: session group not registered; ' +
+            'autoRegisterAllCommands must run before registerReinjectCommand');
+    }
+    session
+        .command('reinject')
+        .description('Print the post-compact engineering-state card to stdout. ' +
+        'Run by the SessionStart hook (matcher: compact) so Claude Code re-injects it ' +
+        'as context after a compaction. Read-only; prints nothing (exit 0) when there is ' +
+        'no state to re-inject.')
+        .requiredOption('--project <path>', 'Project root (must be a non-empty canonical path)')
+        .option('--budget-bytes <n>', `Diagnostic override for the card's byte ceiling (default ${POST_COMPACT_REINJECTION_BYTE_BUDGET})`)
+        .option('--json', 'emit a JSON envelope { ok, data } to stdout instead of the card')
+        .action((opts) => {
+        const { exitCode } = runReinjectAction(opts, io);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+    });
+}

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

@@ -277,9 +277,12 @@ export function registerRequestCommands(program, io) {
             // 0.85–0.95 pre-compact zone, write a checkpoint BEFORE the
             // transition completes and attach `preCompactCheckpoint: true` to
             // the response envelope. The LLM remains the decision-maker; this
-            // hook only surfaces the signal. The 0.95 red-line behaviour is
-            // unchanged — the existing auto-compact orchestrator continues to
-            // refuse dispatch at ratio ≥ 0.95.
+            // hook only surfaces the signal. At ratio ≥ 0.95 the auto-compact
+            // orchestrator ASKS the harness to compact and reports that it is
+            // waiting; it does not refuse anything, because peaks-loop has no
+            // executor for a running session and a refusal it cannot enforce only
+            // deadlocked the runner (slice
+            // 2026-09-13-auto-compact-trigger-ownership).
             let preCompact = null;
             // 2026-09-03-codegraph-autorefresh: auto codegraph re-index on the
             // RD → QA slice-complete boundary. Set only for rd:qa-handoff; null

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

@@ -46,6 +46,7 @@ export function runShadcnInit(options) {
     const result = spawnSync(invocation.command, [...invocation.args], {
         cwd: options.cwd,
         encoding: 'utf8',
+        windowsHide: true,
         timeout: options.timeoutMs ?? 300_000,
         maxBuffer: 32 * 1024 * 1024,
         env: invocation.baseEnv

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

@@ -203,7 +203,8 @@ export function runRunner(framework, argv, projectRoot, deps = {}) {
         const proc = spawnFn(resolution.command, resolution.args, {
             cwd: projectRoot,
             env: process.env,
-            stdio: ['ignore', 'pipe', 'pipe']
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true
         });
         let stdout = '';
         let stderr = '';

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

@@ -59,7 +59,7 @@ function detectHypervisor(requested) {
             break;
     }
     try {
-        const v = execSync(`${binary} --version`, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+        const v = execSync(`${binary} --version`, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', windowsHide: true });
         if (requested === 'kvm' && !existsSync('/dev/kvm')) {
             return { ok: false, stderr: 'KVM kernel module not loaded (/dev/kvm absent)' };
         }
@@ -87,27 +87,27 @@ function spawnVmWithHypervisor(args) {
 </domain>`;
         const xmlPath = `${args.workdir}/.peaks-vm-${args.leaseId}.xml`;
         require('node:fs').writeFileSync(xmlPath, xml, 'utf8');
-        const out = execSync(`virsh create ${xmlPath}`, { cwd: args.workdir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+        const out = execSync(`virsh create ${xmlPath}`, { cwd: args.workdir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', windowsHide: true });
         return { vmId: out.trim() };
     }
     if (args.hypervisor === 'hyperkit') {
-        const out = execSync(`hvftool create --image ${args.image} --mount ${args.mount}:/work --label peaks.leaseId=${args.leaseId} --label peaks.rid=${args.rid} --entrypoint sleep -- infinity`, { cwd: args.workdir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+        const out = execSync(`hvftool create --image ${args.image} --mount ${args.mount}:/work --label peaks.leaseId=${args.leaseId} --label peaks.rid=${args.rid} --entrypoint sleep -- infinity`, { cwd: args.workdir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', windowsHide: true });
         return { vmId: out.trim() };
     }
     // hyperv: the hvc shim writes a vhdx + emits the new VM id.
-    const out = execSync(`hvc create --image ${args.image} --mount ${args.mount} --label peaks.leaseId=${args.leaseId} --label peaks.rid=${args.rid}`, { cwd: args.workdir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+    const out = execSync(`hvc create --image ${args.image} --mount ${args.mount} --label peaks.leaseId=${args.leaseId} --label peaks.rid=${args.rid}`, { cwd: args.workdir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', windowsHide: true });
     return { vmId: out.trim() };
 }
 function destroyVmWithHypervisor(args) {
     try {
         if (args.hypervisor === 'kvm') {
-            execSync(`virsh destroy ${args.vmId}`, { stdio: ['ignore', 'pipe', 'pipe'] });
+            execSync(`virsh destroy ${args.vmId}`, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
         }
         else if (args.hypervisor === 'hyperkit') {
-            execSync(`hvftool stop ${args.vmId}`, { stdio: ['ignore', 'pipe', 'pipe'] });
+            execSync(`hvftool stop ${args.vmId}`, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
         }
         else {
-            execSync(`hvc stop ${args.vmId}`, { stdio: ['ignore', 'pipe', 'pipe'] });
+            execSync(`hvc stop ${args.vmId}`, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
         }
         return true;
     }

package/dist/cli/commands/workspace/init-command.js

@@ -22,7 +22,7 @@ import { initWorkspace, InvalidSessionIdError, ConflictingSessionError, LegacyCh
 // session-id-shaped directories at the `.peaks/_runtime/` sibling
 // level.
 import { ensureSessionWithRotation } from '../../../services/session/session-manager.js';
-import { resolveCanonicalProjectRoot } from '../../../services/config/config-service.js';
+import { resolveWritableProjectRoot, UnsafeProjectRootError } from '../../../services/config/config-safety.js';
 import { applyHookInstall, readHookStatus } from '../../../services/skills/hooks-settings-service.js';
 import { clearStalePresenceOnRotation } from '../../../services/skills/skill-presence-service.js';
 import { gcStalePresenceLeases } from '../../../services/skills/presence-lease-service.js';
@@ -69,7 +69,12 @@ export function registerWorkspaceInitCommand(workspace, io) {
             // (the same regression that produced prompt-project/.peaks/ in
             // the 5/27-5/29 sessions). When startPath is not inside any
             // git repo, the helper falls through to the cwd verbatim.
-            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            // `resolveWritableProjectRoot` = `resolveCanonicalProjectRoot` plus the
+            // home-directory refusal. It has to be this one, and it has to run here:
+            // `ensureSessionWithRotation` below WRITES (it mints/binds a session), so
+            // a guard placed after it would leave a `.peaks/_runtime/` tree in the
+            // user's home even though the init was refused.
+            const projectRoot = resolveWritableProjectRoot(options.project);
             // Slice 018: outer-session-mismatch auto-rotation. When the
             // user did NOT pass --session-id explicitly, run
             // `ensureSessionWithRotation` so the binding is rotated on
@@ -408,6 +413,23 @@ export function registerWorkspaceInitCommand(workspace, io) {
             }, warningsForEnvelope, nextActions), options.json);
         }
         catch (error) {
+            if (error instanceof UnsafeProjectRootError) {
+                // A typed refusal, not a crash: "you are standing in your home
+                // directory, which is not a project" is a thing the caller can fix in
+                // one step, and the envelope has to say which directory was refused and
+                // what to pass instead. `WORKSPACE_INIT_FAILED` below would have buried
+                // it as an unexplained failure.
+                printResult(io, fail('workspace.init', 'UNSAFE_PROJECT_ROOT', error.message, {
+                    resolvedProjectRoot: error.projectRoot,
+                    projectOption: options.project ?? null
+                }, [
+                    'Pass --project <path-to-your-project> instead of a path that resolves to your home directory.',
+                    'This command creates .peaks/, .gitignore, .claude/settings.local.json and a codegraph index; none of those belong in $HOME.',
+                    'If you meant to initialize the current directory, cd into a project directory first — peaks will not write into the home directory itself.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
             if (error instanceof InvalidSessionIdError) {
                 printResult(io, fail('workspace.init', error.code, error.message, { sessionId: options.sessionId }, ['Use a date-prefixed kebab slug like 2026-05-25-add-user-auth']), options.json);
                 process.exitCode = 1;

package/dist/cli/commands/worktree-lease-commands.js

@@ -91,7 +91,7 @@ export function registerWorktreeLeaseCommands(auth, io) {
             // and authorize this very `git worktree add`; for Part 1 we still
             // require a current `peaks worktree auth grant` token to remain
             // consistent with the slice-027 hard gate contract.
-            execSync(`git worktree add "${wtPath}" -b "${branch}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+            execSync(`git worktree add "${wtPath}" -b "${branch}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8', windowsHide: true });
             atomicWriteJson(leaseFilePath(joinPathSession(projectRoot, sessionId), leaseId), lease);
             // Part 4.A: emit spawn metric (fire-and-forget; never blocks).
             emitLeaseEvent({
@@ -167,7 +167,7 @@ export function registerWorktreeLeaseCommands(auth, io) {
             // released.
             let gitWorktreeRemoveFailed = false;
             try {
-                execSync(`git worktree remove --force "${lease.path}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+                execSync(`git worktree remove --force "${lease.path}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8', windowsHide: true });
             }
             catch {
                 gitWorktreeRemoveFailed = true;
@@ -379,14 +379,14 @@ export function registerWorktreeLeaseCommands(auth, io) {
                     // already gone we still mark the lease gc.
                     let gitWorktreeRemoveFailed = false;
                     try {
-                        execSync(`git worktree remove --force "${updated.path}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+                        execSync(`git worktree remove --force "${updated.path}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8', windowsHide: true });
                     }
                     catch {
                         gitWorktreeRemoveFailed = true;
                     }
                     // `git worktree prune` clears any stale admin entries. Best-effort.
                     try {
-                        execSync('git worktree prune', { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+                        execSync('git worktree prune', { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8', windowsHide: true });
                     }
                     catch {
                         // ignore — prune is idempotent

package/dist/cli/index.js

@@ -29,8 +29,34 @@ const defaultIo = {
 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 program = createProgram();
     const registered = new Set(program.commands.map((c) => c.name()));
     if (!registered.has(firstPositional)) {
         // Defer the check by 0ms so Commander's own help handler runs first
@@ -41,7 +67,7 @@ if (hasHelp && firstPositional !== undefined) {
         });
     }
 }
-createProgram().parseAsync(process.argv).catch((error) => {
+program.parseAsync(process.argv).catch((error) => {
     if (error instanceof CommanderError && error.code === 'commander.version') {
         return;
     }
@@ -59,6 +85,27 @@ createProgram().parseAsync(process.argv).catch((error) => {
         if (error.code === 'commander.help' || error.code === 'commander.helpDisplayed') {
             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.`
+            ]);
+            return;
+        }
         if (error.code === 'commander.missingArgument' || error.code === 'commander.unknownCommand' || error.code === 'commander.unknownOption') {
             // Emit a `COMMAND_NOT_FOUND` JSON envelope for the unknown-command
             // path. The error text already went to stderr via Commander's

package/dist/cli/program.js

@@ -17,6 +17,7 @@ import { registerWorkspaceCommands } from './commands/workspace-commands.js';
 import { registerSopCommands } from './commands/sop-commands.js';
 import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
 import { registerPrimerCommand } from './commands/primer-command.js';
+import { registerReinjectCommand } from './commands/reinject-command.js';
 import { applyRetention, cleanupEccCache } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 import { printSuperCommandCatalog } from './cli-helpers.js';
@@ -217,5 +218,9 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // `program.command('session primer')` (that registers a single
     // literal command name, not a child of the session group).
     registerPrimerCommand(program, io);
+    // rid 2026-09-13-a2-post-compact-reinject: register `peaks session reinject`
+    // as a sibling child of the same `session` group. It is the transport for
+    // the SessionStart (matcher `compact`) hook's post-compaction card.
+    registerReinjectCommand(program, io);
     return program;
 }

package/dist/hooks/pre-tool-use-sub-agent.js

@@ -59,7 +59,7 @@ export function runHookGuardSubprocess(prompt) {
         'sub-agent-dispatch-guard',
         '--prompt', prompt,
         '--json'
-    ], { encoding: 'utf8' });
+    ], { encoding: 'utf8', windowsHide: true });
     if (result.status !== 0) {
         // Fallback: allow (don't block the dispatch on a guard subprocess failure).
         return {

package/dist/services/adapter/adapter-registry.js

@@ -53,7 +53,7 @@ class ProcessVendorAdapter {
         if (args.force === true)
             argv.push('--force');
         return new Promise((resolveRun) => {
-            const proc = spawn(this.binary, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+            const proc = spawn(this.binary, argv, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
             let stdout = '';
             let stderr = '';
             proc.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });

package/dist/services/artifacts/artifact-service.js

@@ -14,7 +14,7 @@ function getRemoteUrl(artifactRepo) {
 }
 function hasGit() {
     try {
-        execFileSync('git', ['--version']);
+        execFileSync('git', ['--version'], { windowsHide: true });
         return true;
     }
     catch {

package/dist/services/capability-guard-runner/contracts/J01.js

@@ -16,7 +16,8 @@ export async function runJ01Contract(ctx) {
         try {
             const stdout = execFileSync('node', [bin, command, input], {
                 cwd: ctx.projectRoot,
-                env: { ...process.env, PEAKS_CALLER_ID: `guard-J01-${ctx.sessionId}` }
+                env: { ...process.env, PEAKS_CALLER_ID: `guard-J01-${ctx.sessionId}` },
+                windowsHide: true
             }).toString('utf8');
             const env = JSON.parse(stdout);
             if (!env.ok) {

package/dist/services/capability-guard-runner/contracts/J02.js

@@ -6,10 +6,10 @@ const STATES = ['spec-locked', 'implemented', 'qa-handoff', 'handed-off'];
 export async function runJ02Contract(ctx, projectRoot = ctx.projectRoot) {
     const bin = join(ctx.projectRoot, 'bin', 'peaks.js');
     const tmp = mkdtempSync(join(tmpdir(), 'cbl-J02-'));
-    const ws = execFileSync('node', [bin, 'workspace', 'init', '--project', tmp, '--json'], { cwd: tmp }).toString('utf8');
+    const ws = execFileSync('node', [bin, 'workspace', 'init', '--project', tmp, '--json'], { cwd: tmp, windowsHide: true }).toString('utf8');
     const { data: { sessionId } } = JSON.parse(ws);
     const rid = '2026-08-03-j02-fixture';
-    const initOut = execFileSync('node', [bin, 'request', 'init', '--role', 'rd', '--id', rid, '--project', tmp, '--session-id', sessionId, '--apply', '--json'], { cwd: tmp }).toString('utf8');
+    const initOut = execFileSync('node', [bin, 'request', 'init', '--role', 'rd', '--id', rid, '--project', tmp, '--session-id', sessionId, '--apply', '--json'], { cwd: tmp, windowsHide: true }).toString('utf8');
     const initEnv = JSON.parse(initOut);
     // `request init` writes the file as `NNN-<id-slug>.md`. The transition CLI accepts
     // the file's basename (without .md) as the requestId. Derive it from data.path.
@@ -19,7 +19,7 @@ export async function runJ02Contract(ctx, projectRoot = ctx.projectRoot) {
     for (const s of STATES) {
         const out = execFileSync('node', [bin, 'request', 'transition', requestId, '--role', 'rd', '--state', s,
             '--project', tmp, '--session-id', sessionId, '--confirm', '--allow-incomplete',
-            '--reason', 'J02 contract fixture', '--json'], { cwd: tmp }).toString('utf8');
+            '--reason', 'J02 contract fixture', '--json'], { cwd: tmp, windowsHide: true }).toString('utf8');
         const env = JSON.parse(out);
         last = env.data.state;
     }

package/dist/services/capability-guard-runner/contracts/J04.js

@@ -10,7 +10,8 @@ export async function runJ04Contract(ctx) {
     try {
         const stdout = execFileSync('node', [bin, 'audit', 'goal', '--help'], {
             cwd: ctx.projectRoot,
-            env: { ...process.env, PEAKS_CALLER_ID: `guard-J04-${ctx.sessionId}` }
+            env: { ...process.env, PEAKS_CALLER_ID: `guard-J04-${ctx.sessionId}` },
+            windowsHide: true
         }).toString('utf8');
         helpOk = stdout.length > 0 && !stdout.includes('unknown command');
     }
@@ -23,7 +24,8 @@ export async function runJ04Contract(ctx) {
         execFileSync('node', [bin, 'audit', 'goal', '--project', tmp, '--json'], {
             cwd: ctx.projectRoot,
             env: { ...process.env, PEAKS_CALLER_ID: `guard-J04-${ctx.sessionId}` },
-            stdio: ['ignore', 'pipe', 'pipe']
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true
         });
     }
     catch (e) {

package/dist/services/capability-guard-runner/contracts/J07.js

@@ -19,7 +19,8 @@ export async function runJ07Contract(ctx) {
         const out = execFileSync('node', [bin, 'test', '--help'], {
             cwd: ctx.projectRoot,
             env: { ...process.env, PEAKS_CALLER_ID: `guard-J07-${ctx.sessionId}` },
-            stdio: ['ignore', 'pipe', 'pipe']
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true
         }).toString('utf8');
         helpOk = out.length > 0 && !out.includes('unknown command');
     }

package/dist/services/code/auto-compact-lifecycle.d.ts

@@ -126,6 +126,12 @@ export declare function summarizeLifecycleError(error: unknown): string;
  *     `afterRatio: 0` there would publish a fabricated number;
  *   - the ratio is still at or above the auto-fire threshold — the
  *     compact has not landed, so the run stays open.
+ *
+ * Returns the settled record, or `null` when nothing settled. Slice
+ * 2026-09-13-auto-compact-trigger-ownership: the caller needs the settled
+ * `afterRatio` to append the "observed compaction point" row that makes the
+ * intent-vs-observed gap readable after a real session. The return value is
+ * telemetry only — callers that ignore it are unaffected.
  */
 export declare function settleOpenLifecycleRun(input: {
     readonly projectRoot: string;
@@ -134,5 +140,9 @@ export declare function settleOpenLifecycleRun(input: {
     readonly source: string;
     readonly autoFireThreshold: number;
     readonly onLifecycleStage?: ((stage: CompactLifecycleStage, record: CompactLifecycleRecord) => void) | undefined;
-}): void;
+}): {
+    readonly runId: string;
+    readonly triggerRatio: number;
+    readonly afterRatio: number;
+} | null;
 export {};