peaks-loop 4.0.54 → 4.1.1

package/dist/cli/commands/gate-commands-enforce.js

@@ -0,0 +1,210 @@
+import { evaluateWorktreeAuth } from '../../services/hooks/worktree-authorization-gate.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { detectIdeFromContext, pluckObject, pluckString } from '../../services/ide/hook-translator.js';
+import { DISPATCH_PROVENANCE_ENV } from '../../services/worktree/dispatch-provenance.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { emitBlock, emitDecision, emitHint } from '../../services/hooks/output.js';
+/**
+ * Parse the raw stdin payload, failing open to `null` on malformed JSON.
+ */
+export function parseHookStdin(raw) {
+    let parsedStdin = null;
+    if (raw.trim().length > 0) {
+        try {
+            parsedStdin = JSON.parse(raw);
+        }
+        catch {
+            // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0).
+            // Malformed JSON — fail-open. Detect + parse on null fall back to the
+            // default adapter and yield empty tool/command, which short-circuits to
+            // the "not a guarded surface" early exit.
+        }
+    }
+    return parsedStdin;
+}
+/**
+ * Map Claude Code tool name to the gate's internal `ToolCallKind`. Anything we don't recognize
+ * returns `'Other'` — the worktree gate is opt-in by tool, so unknown tools short-circuit to allow.
+ */
+export function classifyTool(toolName) {
+    if (toolName === 'Bash')
+        return 'Bash';
+    if (toolName === 'Agent' || toolName === 'Task')
+        return 'Agent';
+    if (toolName === 'EnterWorktree')
+        return 'EnterWorktree';
+    if (toolName === 'Workflow')
+        return 'Workflow';
+    return 'Other';
+}
+/**
+ * Best-effort extraction of the `isolation` field for `Agent` / `Task` tool calls. The Claude
+ * hook payload puts args under `tool_input`, the Cursor/Trae sibling puts them under `toolInput`.
+ * Both shapes are accepted; everything else returns null.
+ */
+function extractIsolation(parsed) {
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const input = pluckObject(parsed, ['tool_input']) ?? pluckObject(parsed, ['toolInput']);
+    if (input === undefined)
+        return null;
+    const value = pluckString(input, ['isolation']);
+    return value === undefined ? null : value;
+}
+/**
+ * Detect the IDE + adapter and return the adapter's tool matcher. For slice #1 only the Claude
+ * adapter is registered, so the payload parser is Claude-shaped. Future slices dispatch on `ide`
+ * to pick a per-adapter parser; the parser entry-point (`parseXxxShapeStdin`) is the only change
+ * required.
+ *
+ * The Bash-surface predicate itself stays in `runGateEnforceAction`: TypeScript's aliased-condition
+ * narrowing needs `isBashSurface` (which embeds `typeof command === 'string'`) computed in the same
+ * scope where `command` is later read, so the extraction stops at the adapter lookup.
+ */
+export function resolveToolMatcher(parsedStdin) {
+    const ide = detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin });
+    return getAdapter(ide).toolMatcher;
+}
+/** `Bash` tool calls pass their command through; every other kind contributes `null`. */
+function resolveBashCommand(toolKind, command) {
+    return toolKind === 'Bash' && typeof command === 'string' ? command : null;
+}
+/** Only `Agent` / `EnterWorktree` calls carry a gated `isolation`; others contribute `null`. */
+function resolveIsolation(toolKind, parsedStdin) {
+    return toolKind === 'Agent' || toolKind === 'EnterWorktree'
+        ? extractIsolation(parsedStdin)
+        : null;
+}
+/** Lease ids are only honored when they are a 16-char hex token; anything else fails closed. */
+function normalizeLeaseId(value) {
+    return value !== null && /^[a-f0-9]{16}$/.test(value) ? value : null;
+}
+/**
+ * Assemble the worktree-gate input from the hook payload (Bash/Agent/EnterWorktree/Workflow).
+ * We extract the tool kind from the hook payload. For Agent/Task we also pull `isolation` from the
+ * tool input — only "worktree" isolation is gated. For all other tool kinds the worktree gate is a
+ * no-op.
+ *
+ * slice 2026-07-29-worktree-l2-extended Part 2.B: the gate consults the lease file referenced by
+ * `PEAKS_WORKTREE_LEASE_ID` as a second authorization path when no `peaks worktree auth grant` is on
+ * file. Dispatch (Part 2.C) injects the env var on every sub-agent spawn so worktree-mutating tool
+ * calls from inside the sub-agent process auto-authorize via the lease instead of requiring a
+ * separate grant. Part 19: container lease (L4) is the parallel path for `--isolation container`
+ * sub-agents. The env is set by the dispatch command (Part 8 + Part 12) at spawn time.
+ */
+function buildWorktreeAuthInput(options, toolKind, command, parsedStdin) {
+    const sessionId = getCurrentSessionId(options.project) ?? 'unknown-sid';
+    return {
+        projectRoot: options.project,
+        sessionId,
+        toolName: toolKind,
+        command: resolveBashCommand(toolKind, command),
+        isolation: resolveIsolation(toolKind, parsedStdin),
+        requestId: null,
+        leaseId: normalizeLeaseId(process.env.PEAKS_WORKTREE_LEASE_ID ?? null),
+        containerLeaseId: normalizeLeaseId(process.env.PEAKS_CONTAINER_LEASE_ID ?? null),
+        dispatchProvenanceToken: process.env[DISPATCH_PROVENANCE_ENV] ?? null
+    };
+}
+/**
+ * Run the fail-closed worktree authorization gate for a gated tool kind. Returns `true` when the
+ * call was denied (a hard block has already been emitted and the handler must stop) and `false`
+ * when the flow should continue to the SOP gate. `Other` tool kinds are not gated at all.
+ *
+ * slice 2026-07-27-worktree-user-auth: BEFORE the SOP gate runs, check the worktree authorization
+ * gate. The worktree gate is narrower than the SOP gate (it only inspects a small set of
+ * worktree-mutating operations) and is fail-CLOSED. The two layers are complementary: SOP gates
+ * decide "may this command run under this SOP's state", the worktree gate decides "did the user
+ * explicitly authorize this worktree-mutating operation in the current task". The worktree gate is
+ * cheap and self-contained, so it runs first to give the LLM a clear error reason before the SOP
+ * gate would otherwise allow.
+ *
+ * wtDecision may have arrived via lease (viaLease != null); the SOP gate does not care which path
+ * granted, only that the worktree gate said allow.
+ */
+export function handleWorktreeGate(io, options, toolKind, payload) {
+    if (toolKind === 'Other') {
+        return false;
+    }
+    const wtDecision = evaluateWorktreeAuth(buildWorktreeAuthInput(options, toolKind, payload.command, payload.parsedStdin));
+    if (!wtDecision.allow) {
+        emitWorktreeDeny(io, options, wtDecision);
+        return true;
+    }
+    // allow: continue to the SOP gate (the regular enforcement path).
+    return false;
+}
+/**
+ * Not a guarded surface — allow. Emit minimal JSON on stdout so Claude Code's PreToolUse hook
+ * validator accepts the response. Empty stdout is rejected with "Hook JSON output validation
+ * failed — Invalid input" in Claude Code 2.x; `{}` is the canonical no-op marker.
+ */
+export function emitAllowSkipped(io, options) {
+    if (options.json === true) {
+        printResult(io, ok('gate.enforce', { decision: 'allow', skipped: true }), true);
+    }
+    else {
+        emitDecision(io, {});
+    }
+}
+/**
+ * Hard block: a worktree-mutating tool call without a current-task user grant. emitBlock writes
+ * the Claude Code permissionDecision:"deny" envelope and exits 2. The reason includes the
+ * remediation hint so the LLM can run `peaks worktree auth grant` and retry, and the user can
+ * read the deny text in the next-turn stderr.
+ */
+function emitWorktreeDeny(io, options, wtDecision) {
+    emitBlock(io, `[worktree-gate:${wtDecision.code}] ${wtDecision.reason} — ${wtDecision.remediation}`);
+    if (options.json === true) {
+        emitHint(io, JSON.stringify(ok('gate.enforce', { decision: 'deny', layer: 'worktree-auth', ...wtDecision })));
+    }
+}
+/** Worktree gate allowed and this is not a Bash surface — allow without running the SOP gate. */
+export function emitAllowWorktree(io, options) {
+    if (options.json === true) {
+        printResult(io, ok('gate.enforce', { decision: 'allow', layer: 'worktree-auth' }), true);
+    }
+    else {
+        emitDecision(io, {});
+    }
+}
+/**
+ * PRD#2 (2026-06-16-fact-forcing-gate-format): a true SOP gate failure is a HARD block. emitBlock
+ * writes the Claude Code permissionDecision:"deny" JSON to stdout (the hook's decision signal),
+ * sets process.exitCode = 2 (Claude Code's block exit code), AND surfaces the reason to stderr so
+ * the LLM sees it on the next turn. This prevents the previous behaviour where Claude Code wrapped
+ * the output as "PreToolUse:Bash hook error".
+ */
+export function emitSopDeny(io, options, decision) {
+    emitBlock(io, decision.reason);
+    if (options.json === true) {
+        emitHint(io, JSON.stringify(ok('gate.enforce', decision)));
+    }
+}
+/** Surface any SOP-gate warnings as hints before the allow decision is emitted. */
+export function emitSopWarnings(io, decision) {
+    if (decision.warnings && decision.warnings.length > 0) {
+        for (const warning of decision.warnings) {
+            emitHint(io, warning);
+        }
+    }
+}
+/**
+ * SOP gate allowed the command. --json mode emits the canonical envelope on stdout (the documented
+ * contract for downstream tooling). The hook decision (allow/deny) is still signalled via
+ * process.exitCode + the minimal `{}` on stdout in non-`--json` mode. Slice 2026-07-30-nightshift:
+ * emitHint here was wrong — emitHint writes to stderr, but the AC5 contract expects the JSON
+ * envelope on stdout. Switch to printResult(asJson=true).
+ */
+export function emitSopAllow(io, options, decision) {
+    if (options.json === true) {
+        printResult(io, ok('gate.enforce', decision), true);
+    }
+    else {
+        // allow: emit minimal JSON on stdout so Claude Code's PreToolUse hook
+        // validator accepts the response (see comment above).
+        emitDecision(io, {});
+    }
+}

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

@@ -1,3 +1,3 @@
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerGateCommands(program: Command, io: ProgramIO): void;

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

@@ -1,12 +1,16 @@
 import { enforceBashCommand, recordGateBypass, GateBypassError } from '../../services/sop/gate-enforce-service.js';
-import { evaluateWorktreeAuth } from '../../services/hooks/worktree-authorization-gate.js';
-import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { detectIdeFromContext, parseClaudeShapeStdin, pluckObject, pluckString } from '../../services/ide/hook-translator.js';
-import { DISPATCH_PROVENANCE_ENV } from '../../services/worktree/dispatch-provenance.js';
-import { getAdapter } from '../../services/ide/ide-registry.js';
-import { emitBlock, emitDecision, emitHint } from '../../services/hooks/output.js';
+import { emitHint } from '../../services/hooks/output.js';
+import { parseClaudeShapeStdin } from '../../services/ide/hook-translator.js';
+import { classifyTool, emitAllowSkipped, emitAllowWorktree, emitSopAllow, emitSopDeny, emitSopWarnings, handleWorktreeGate, parseHookStdin, resolveToolMatcher } from './gate-commands-enforce.js';
+export function registerGateCommands(program, io) {
+    const gate = program
+        .command('gate')
+        .description('SOP gate enforcement (PreToolUse hook handler and bypass)');
+    registerGateEnforceCommand(gate, io);
+    registerGateBypassCommand(gate, io);
+}
 /**
  * Read the PreToolUse hook payload. `PEAKS_HOOK_STDIN` is a test seam; production
  * reads stdin. The CLI-side stdin reader is intentionally kept here (not in
@@ -25,208 +29,81 @@ async function readHookPayload() {
         let data = '';
         process.stdin.setEncoding('utf8');
         process.stdin.on('data', (chunk) => {
-            data += chunk;
+            data += String(chunk);
         });
         process.stdin.on('end', () => resolveStdin(data));
         process.stdin.on('error', () => resolveStdin(data));
     });
 }
 /**
- * Map Claude Code tool name to the gate's internal `ToolCallKind`. Anything we don't recognize
- * returns `'Other'` — the worktree gate is opt-in by tool, so unknown tools short-circuit to allow.
+ * Slice 2026-07-29-windows-console-flash Part 46: actively exit the process when the gate-enforce
+ * handler returns. The default behavior is to wait for stdin EOF before exiting, but the hook's
+ * stdin pipe may not close promptly (the parent can keep the handle open even after it has finished
+ * reading the JSON decision), which causes 4 Node.js processes to accumulate in the user's task
+ * manager. An explicit process.exit here forces the gate process to release all handles and exit
+ * immediately.
+ *
+ * Slice 2026-07-30-nightshift: gate the `process.exit` on being invoked as a real CLI hook (no
+ * PEAKS_HOOK_STDIN test seam, no PEAKS_TEST_SEAM env var). The test harness calls `runCommand`
+ * which invokes the same action handler in process — calling `process.exit` inside the test would
+ * kill the vitest runner before assertions complete. The `process.exitCode` set above is sufficient
+ * for the test path: Commander's `parseAsync` resolves the action, then the harness reads the
+ * captured stdout/stderr before the runner exits normally with the recorded exit code.
  */
-function classifyTool(toolName) {
-    if (toolName === 'Bash')
-        return 'Bash';
-    if (toolName === 'Agent' || toolName === 'Task')
-        return 'Agent';
-    if (toolName === 'EnterWorktree')
-        return 'EnterWorktree';
-    if (toolName === 'Workflow')
-        return 'Workflow';
-    return 'Other';
+function exitWhenRealCliHook() {
+    if (process.env.PEAKS_HOOK_STDIN === undefined && process.env.PEAKS_TEST_SEAM === undefined) {
+        process.exit(process.exitCode || 0);
+    }
 }
 /**
- * Best-effort extraction of the `isolation` field for `Agent` / `Task` tool calls. The Claude
- * hook payload puts args under `tool_input`, the Cursor/Trae sibling puts them under `toolInput`.
- * Both shapes are accepted; everything else returns null.
+ * Body of the `gate enforce` PreToolUse handler. The worktree-then-SOP ordering and every early
+ * return / exit-code path are documented on the helpers this delegates to in `gate-commands-enforce`.
  */
-function extractIsolation(parsed) {
-    if (parsed === null || typeof parsed !== 'object')
-        return null;
-    const input = pluckObject(parsed, ['tool_input']) ?? pluckObject(parsed, ['toolInput']);
-    if (input === undefined)
-        return null;
-    const value = pluckString(input, ['isolation']);
-    return value === undefined ? null : value;
+async function runGateEnforceAction(io, options) {
+    // Trust red line: this runs on (potentially) every Bash call. Any failure to
+    // decide must FAIL-OPEN (allow), never block the user's Claude Code.
+    try {
+        const raw = await readHookPayload();
+        const parsedStdin = parseHookStdin(raw);
+        const toolMatcher = resolveToolMatcher(parsedStdin);
+        const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
+        const toolKind = classifyTool(toolName);
+        const isBashSurface = toolName === toolMatcher && typeof command === 'string' && command.trim().length > 0;
+        const isWorktreeToolSurface = toolKind === 'Agent' || toolKind === 'EnterWorktree';
+        if (!isBashSurface && !isWorktreeToolSurface) {
+            emitAllowSkipped(io, options);
+            return;
+        }
+        if (handleWorktreeGate(io, options, toolKind, { command, parsedStdin })) {
+            return;
+        }
+        if (!isBashSurface) {
+            emitAllowWorktree(io, options);
+            return;
+        }
+        const decision = await enforceBashCommand(options.project, command);
+        if (decision.decision === 'deny') {
+            emitSopDeny(io, options, decision);
+            return;
+        }
+        emitSopWarnings(io, decision);
+        emitSopAllow(io, options, decision);
+    }
+    catch (error) {
+        // Fail-open: a bug in enforcement must not brick Claude Code.
+        emitHint(io, `gate enforce: internal error, allowing command (${getErrorMessage(error)})`);
+    }
+    exitWhenRealCliHook();
 }
-export function registerGateCommands(program, io) {
-    const gate = program.command('gate').description('SOP gate enforcement (PreToolUse hook handler and bypass)');
+function registerGateEnforceCommand(gate, io) {
     addJsonOption(gate
         .command('enforce')
         .description('PreToolUse hook handler: deny a Bash command guarded by an unsatisfied SOP gate')
         .option('--project <path>', 'project the gates evaluate against (default: current directory)', '.')).action(async (options) => {
-        // Trust red line: this runs on (potentially) every Bash call. Any failure to
-        // decide must FAIL-OPEN (allow), never block the user's Claude Code.
-        try {
-            const raw = await readHookPayload();
-            let parsedStdin = null;
-            if (raw.trim().length > 0) {
-                try {
-                    parsedStdin = JSON.parse(raw);
-                }
-                catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                    // Malformed JSON — fail-open. Detect + parse on null fall back to the
-                    // default adapter and yield empty tool/command, which short-circuits
-                    // to the "not a guarded surface" early exit below.
-                }
-            }
-            const ide = detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin });
-            const adapter = getAdapter(ide);
-            // For slice #1 only the Claude adapter is registered, so the parser is
-            // Claude-shaped. Future slices dispatch on `ide` to pick a per-adapter
-            // parser; the parser entry-point (`parseXxxShapeStdin`) is the only
-            // change required.
-            const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
-            const toolKind = classifyTool(toolName);
-            const isBashSurface = toolName === adapter.toolMatcher && typeof command === 'string' && command.trim().length > 0;
-            const isWorktreeToolSurface = toolKind === 'Agent' || toolKind === 'EnterWorktree';
-            if (!isBashSurface && !isWorktreeToolSurface) {
-                // Not a guarded surface — allow. Emit minimal JSON on stdout so Claude
-                // Code's PreToolUse hook validator accepts the response. Empty stdout
-                // is rejected with "Hook JSON output validation failed — Invalid input"
-                // in Claude Code 2.x; `{}` is the canonical no-op marker.
-                if (options.json === true) {
-                    printResult(io, ok('gate.enforce', { decision: 'allow', skipped: true }), true);
-                }
-                else {
-                    emitDecision(io, {});
-                }
-                return;
-            }
-            // slice 2026-07-27-worktree-user-auth: BEFORE the SOP gate runs, check the worktree
-            // authorization gate. The worktree gate is narrower than the SOP gate (it only inspects
-            // a small set of worktree-mutating operations) and is fail-CLOSED. The two layers are
-            // complementary: SOP gates decide "may this command run under this SOP's state", the
-            // worktree gate decides "did the user explicitly authorize this worktree-mutating operation
-            // in the current task". The worktree gate is cheap and self-contained, so it runs first
-            // to give the LLM a clear error reason before the SOP gate would otherwise allow.
-            //
-            // We extract the tool kind from the hook payload (Bash/Agent/EnterWorktree/Workflow).
-            // For Agent/Task we also pull `isolation` from the tool input — only "worktree" isolation
-            // is gated. For all other tool kinds the worktree gate is a no-op.
-            if (toolKind !== 'Other') {
-                const sessionId = getCurrentSessionId(options.project) ?? 'unknown-sid';
-                // slice 2026-07-29-worktree-l2-extended Part 2.B: the gate consults
-                // the lease file referenced by `PEAKS_WORKTREE_LEASE_ID` as a
-                // second authorization path when no `peaks worktree auth grant`
-                // is on file. Dispatch (Part 2.C) injects the env var on every
-                // sub-agent spawn so worktree-mutating tool calls from inside
-                // the sub-agent process auto-authorize via the lease instead
-                // of requiring a separate grant.
-                const leaseId = process.env.PEAKS_WORKTREE_LEASE_ID ?? null;
-                // Part 19: container lease (L4) is the parallel path for
-                // `--isolation container` sub-agents. The env is set by the
-                // dispatch command (Part 8 + Part 12) at spawn time.
-                const containerLeaseId = process.env.PEAKS_CONTAINER_LEASE_ID ?? null;
-                const wtDecision = evaluateWorktreeAuth({
-                    projectRoot: options.project,
-                    sessionId,
-                    toolName: toolKind,
-                    command: toolKind === 'Bash' && typeof command === 'string' ? command : null,
-                    isolation: toolKind === 'Agent' || toolKind === 'EnterWorktree' ? extractIsolation(parsedStdin) : null,
-                    requestId: null,
-                    leaseId: leaseId !== null && /^[a-f0-9]{16}$/.test(leaseId) ? leaseId : null,
-                    containerLeaseId: containerLeaseId !== null && /^[a-f0-9]{16}$/.test(containerLeaseId) ? containerLeaseId : null,
-                    dispatchProvenanceToken: process.env[DISPATCH_PROVENANCE_ENV] ?? null
-                });
-                if (!wtDecision.allow) {
-                    // Hard block: a worktree-mutating tool call without a current-task user grant.
-                    // emitBlock writes the Claude Code permissionDecision:"deny" envelope and exits 2.
-                    // The reason includes the remediation hint so the LLM can run `peaks worktree auth grant`
-                    // and retry, and the user can read the deny text in the next-turn stderr.
-                    emitBlock(io, `[worktree-gate:${wtDecision.code}] ${wtDecision.reason} — ${wtDecision.remediation}`);
-                    if (options.json === true) {
-                        emitHint(io, JSON.stringify(ok('gate.enforce', { decision: 'deny', layer: 'worktree-auth', ...wtDecision })));
-                    }
-                    return;
-                }
-                // allow: continue to the SOP gate (the regular enforcement path).
-                // wtDecision may have arrived via lease (viaLease != null); the SOP gate does not
-                // care which path granted, only that the worktree gate said allow.
-            }
-            if (!isBashSurface) {
-                if (options.json === true) {
-                    printResult(io, ok('gate.enforce', { decision: 'allow', layer: 'worktree-auth' }), true);
-                }
-                else {
-                    emitDecision(io, {});
-                }
-                return;
-            }
-            const decision = await enforceBashCommand(options.project, command);
-            if (decision.decision === 'deny') {
-                // PRD#2 (2026-06-16-fact-forcing-gate-format): a true SOP gate failure is
-                // a HARD block. emitBlock writes the Claude Code permissionDecision:"deny"
-                // JSON to stdout (the hook's decision signal), sets process.exitCode = 2
-                // (Claude Code's block exit code), AND surfaces the reason to stderr so
-                // the LLM sees it on the next turn. This prevents the previous behaviour
-                // where Claude Code wrapped the output as "PreToolUse:Bash hook error".
-                emitBlock(io, decision.reason);
-                if (options.json === true) {
-                    emitHint(io, JSON.stringify(ok('gate.enforce', decision)));
-                }
-                return;
-            }
-            if (decision.warnings && decision.warnings.length > 0) {
-                for (const warning of decision.warnings) {
-                    emitHint(io, warning);
-                }
-            }
-            if (options.json === true) {
-                // --json mode: emit the canonical envelope on stdout (the
-                // documented contract for downstream tooling). The hook
-                // decision (allow/deny) is still signalled via process.exitCode
-                // + the minimal `{}` on stdout in non-`--json` mode.
-                // Slice 2026-07-30-nightshift: emitHint here was wrong —
-                // emitHint writes to stderr, but the AC5 contract expects
-                // the JSON envelope on stdout. Switch to printResult(asJson=true).
-                printResult(io, ok('gate.enforce', decision), true);
-            }
-            else {
-                // allow: emit minimal JSON on stdout so Claude Code's PreToolUse hook
-                // validator accepts the response (see comment above).
-                emitDecision(io, {});
-            }
-        }
-        catch (error) {
-            // Fail-open: a bug in enforcement must not brick Claude Code.
-            emitHint(io, `gate enforce: internal error, allowing command (${getErrorMessage(error)})`);
-        }
-        // Slice 2026-07-29-windows-console-flash Part 46: actively
-        // exit the process when the gate-enforce handler returns.
-        // The default behavior is to wait for stdin EOF before
-        // exiting, but the hook's stdin pipe may not close promptly
-        // (the parent can keep the handle open even after it has
-        // finished reading the JSON decision), which causes 4
-        // Node.js processes to accumulate in the user's task
-        // manager. An explicit process.exit here forces the gate
-        // process to release all handles and exit immediately.
-        //
-        // Slice 2026-07-30-nightshift: gate the `process.exit` on
-        // being invoked as a real CLI hook (no PEAKS_HOOK_STDIN test
-        // seam, no PEAKS_TEST_SEAM env var). The test harness calls
-        // `runCommand` which invokes the same action handler in
-        // process — calling `process.exit` inside the test would
-        // kill the vitest runner before assertions complete. The
-        // `process.exitCode` set above is sufficient for the test
-        // path: Commander's `parseAsync` resolves the action, then
-        // the harness reads the captured stdout/stderr before the
-        // runner exits normally with the recorded exit code.
-        if (process.env.PEAKS_HOOK_STDIN === undefined && process.env.PEAKS_TEST_SEAM === undefined) {
-            process.exit(process.exitCode || 0);
-        }
+        await runGateEnforceAction(io, options);
     });
+}
+function registerGateBypassCommand(gate, io) {
     addJsonOption(gate
         .command('bypass')
         .description('Record a one-shot bypass so the next guarded Bash command is allowed once')
@@ -234,19 +111,22 @@ export function registerGateCommands(program, io) {
         .requiredOption('--phase <phase>', 'phase whose gate to bypass')
         .requiredOption('--reason <text>', 'justification recorded for the bypass')
         .option('--project <path>', 'project whose run-state holds the token (default: current directory)', '.')).action((options) => {
-        try {
-            if (options.reason.trim().length === 0) {
-                printResult(io, fail('gate.bypass', 'BYPASS_REASON_REQUIRED', '--reason must not be empty', { sop: options.sop, phase: options.phase }, ['Provide --reason "<why>"']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const result = recordGateBypass(options.project, options.sop, options.phase, options.reason);
-            printResult(io, ok('gate.bypass', { sop: options.sop, phase: options.phase, count: result.count }, [], ['The next guarded Bash command for this transition will be allowed once']), options.json);
-        }
-        catch (error) {
-            const code = error instanceof GateBypassError ? error.code : 'GATE_BYPASS_FAILED';
-            printResult(io, fail('gate.bypass', code, getErrorMessage(error), { sop: options.sop, phase: options.phase }, ['Satisfy the gate instead of bypassing']), options.json);
+        runGateBypassAction(io, options);
+    });
+}
+function runGateBypassAction(io, options) {
+    try {
+        if (options.reason.trim().length === 0) {
+            printResult(io, fail('gate.bypass', 'BYPASS_REASON_REQUIRED', '--reason must not be empty', { sop: options.sop, phase: options.phase }, ['Provide --reason "<why>"']), options.json);
             process.exitCode = 1;
+            return;
         }
-    });
+        const result = recordGateBypass(options.project, options.sop, options.phase, options.reason);
+        printResult(io, ok('gate.bypass', { sop: options.sop, phase: options.phase, count: result.count }, [], ['The next guarded Bash command for this transition will be allowed once']), options.json);
+    }
+    catch (error) {
+        const code = error instanceof GateBypassError ? error.code : 'GATE_BYPASS_FAILED';
+        printResult(io, fail('gate.bypass', code, getErrorMessage(error), { sop: options.sop, phase: options.phase }, ['Satisfy the gate instead of bypassing']), options.json);
+        process.exitCode = 1;
+    }
 }

package/dist/cli/commands/governance-classify-contract-commands.d.ts

@@ -15,7 +15,7 @@
  * sit under 200 lines and the merged file lands at ~360 lines — well
  * below the 400-line AC-9 sanity guard and the 800-line scan gate.
  */
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerContractCommands(program: Command, io: ProgramIO): void;
 export declare function registerClassifyCommands(program: Command, io: ProgramIO): void;