@pugi/cli 0.1.0-beta.12 → 0.1.0-beta.14

package/dist/runtime/cli.js

@@ -8,6 +8,9 @@ import { AnvilEngineLoopClient } from '../core/engine/anvil-client.js';
 import { NoopEngineAdapter } from '../core/engine/noop.js';
 import { NativePugiEngineAdapter } from '../core/engine/native-pugi.js';
 import { decidePermission } from '../core/permission.js';
+import { loadMcpRegistry } from '../core/mcp/registry.js';
+import { loadHookRegistryOrExit } from './load-hooks-or-exit.js';
+import { defaultNonInteractiveMcpPrompt } from '../tools/mcp-tool.js';
 import { openSession, recordCommandCompleted, recordCommandStarted, recordToolCall, recordToolResult, } from '../core/session.js';
 import { loadSettings } from '../core/settings.js';
 import { FileReadCache } from '../core/file-cache.js';
@@ -36,6 +39,7 @@ import { runPatchCommand } from './commands/patch.js';
 import { runWorktreeCommand } from './commands/worktree.js';
 import { resolveWorkspaceLabel } from '../core/repl/workspace-context.js';
 import { runReviewConsensus } from './commands/review-consensus.js';
+import { runMcpCommand } from './commands/mcp.js';
 import { DECOMPOSE_PROMPT_SUFFIX, parseDecompositionFromText, writeDecomposition, } from './plan-decompose.js';
 import { FtsSyntaxError, SqliteSessionStore, resolveProjectStoreDir } from '../core/repl/store/index.js';
 import { slugForCwd } from '../core/repl/history.js';
@@ -51,37 +55,15 @@ import { dispatchEdit, } from '../core/edits/index.js';
  * packages/pugi-sdk/package.json); the publish workflow validates the
  * three are in lockstep.
  */
-/**
- * β1 housekeeping (#51): defensive semver sanitizer. If a future
- * refactor moves PUGI_CLI_VERSION reading to a JSON import (resolveJson)
- * the npm publish pipeline can leak `workspace:*` from a partially-bumped
- * package.json — `npm publish` rewrites these but a local `pnpm pack`
- * does not, and the failure mode is silently shipping an unsemver
- * version that breaks `pugi --version` JSON consumers. Sanitize at the
- * read site so even a leaked literal lands as a deterministic
- * "0.0.0-unknown" rather than `workspace:*`.
- */
-function sanitizeSemver(raw) {
-    if (typeof raw !== 'string')
-        return '0.0.0-unknown';
-    const trimmed = raw.trim();
-    if (!trimmed)
-        return '0.0.0-unknown';
-    // Strip a `workspace:` / `npm:` / `file:` protocol prefix that pnpm
-    // can emit when a partial publish runs.
-    const stripped = trimmed.replace(/^(workspace:|npm:|file:)/, '');
-    // Accept anything that begins with major.minor.patch + optional
-    // prerelease/build per semver 2.0. Reject `*`, `^x`, `~x`, ranges, etc.
-    if (/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(stripped)) {
-        return stripped;
-    }
-    return '0.0.0-unknown';
-}
-// Main bumped to 0.1.0-beta.9 (PR #430 REPL-hang fix). β1a r1 rebase
-// preserves the main bump and runs it through the β1 sanitizer added
-// here so a future workspace:* leak from a partial publish lands as
-// "0.0.0-unknown" instead of corrupting `pugi --version` JSON output.
-const PUGI_CLI_VERSION = sanitizeSemver("0.1.0-beta.12");
+// PR-CLI-SERVER-VERSION-HANDSHAKE (#225). PUGI_CLI_VERSION lives in
+// `runtime/version.ts` now so the engine transport interceptor can
+// import it without dragging in the cli.ts module graph. Re-exported
+// here under the original name so every existing reader (`pugi version`,
+// `pugi doctor --json`, splash render, telemetry) keeps working with
+// zero churn. Bumping the CLI version is still a single-file edit —
+// just on `runtime/version.ts` instead of here. The β1 sanitizer that
+// guarded against `workspace:*` leaks moved with the constant.
+import { PUGI_CLI_VERSION, sanitizeSemver } from './version.js';
 const handlers = {
     accounts,
     agents: dispatchAgents,
@@ -103,6 +85,7 @@ const handlers = {
     login,
     logout,
     lsp: dispatchLsp,
+    mcp: dispatchMcp,
     patch: dispatchPatch,
     plan: runEngineTask('plan'),
     'plan-review': dispatchPlanReview,
@@ -421,6 +404,25 @@ async function dispatchLsp(args, flags, _session) {
     if (result.exitCode !== 0)
         process.exitCode = result.exitCode;
 }
+/**
+ * β4 M6 + M7 + Sl7 (2026-05-26): `pugi mcp <sub>` — MCP execution +
+ * server. `list / trust / deny / install` manage the client-side
+ * registry (the same surface `pugi config mcp ...` exposes); `serve`
+ * boots Pugi-as-MCP-server over stdio (default) or HTTP+SSE; `perms`
+ * inspects + resets the per-(server, tool) permission cache that
+ * gates engine-loop dispatch.
+ *
+ * The serve sub-command never returns under normal conditions — the
+ * stdio path runs until stdin closes (parent agent disconnect) and the
+ * HTTP path runs until SIGINT/SIGTERM. Both honour the optional
+ * AbortSignal we pass through from the REPL slash bridge in β4b.
+ */
+async function dispatchMcp(args, flags, _session) {
+    await runMcpCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
 /**
  * α7.7: `pugi patch` — apply a unified-diff patch from stdin or a file.
  * Routes through the same security gate as the Layer A/B/C applicators
@@ -464,6 +466,37 @@ async function dispatchWorktree(args, flags, _session) {
 }
 export async function runCli(argv) {
     const { command, args, flags, isBareInvocation } = parseArgs(argv);
+    // β-headless dispatch (CEO directive 2026-05-27 "нужно тестирование по
+    // кругу"): when `--print <brief>` is set we route to the headless
+    // runner BEFORE the REPL / splash / command branches. The runner
+    // never mounts Ink, never opens raw stdin, never prints the splash
+    // — only the structured event stream lands on stdout. Same engine
+    // adapter path the REPL uses (no fork), only the output sink
+    // differs.
+    if (typeof flags.print === 'string') {
+        const { runHeadlessPrint } = await import('./headless.js');
+        // Default to NDJSON when stdout is not a TTY OR when --json is set
+        // explicitly. A human running `pugi --print "..."` in their
+        // terminal without flags gets the readable text sink; a pipe gets
+        // the machine-readable stream.
+        const wantJson = flags.json || !process.stdout.isTTY;
+        const headlessFactory = getEngineClientFactory();
+        const exitCode = await runHeadlessPrint({
+            prompt: flags.print,
+            json: wantJson,
+            cwd: flags.cwd ?? process.cwd(),
+            ...(flags.workspace ? { workspace: flags.workspace } : {}),
+            ...(flags.sessionId ? { sessionIdOverride: flags.sessionId } : {}),
+            ...(flags.timeoutSeconds ? { timeoutSeconds: flags.timeoutSeconds } : {}),
+            noTools: flags.noTools,
+            ...(flags.maxTurns ? { maxTurns: flags.maxTurns } : {}),
+            ...(headlessFactory ? { engineClientFactory: headlessFactory } : {}),
+            ...(headlessStdoutWriter ? { stdoutWrite: headlessStdoutWriter } : {}),
+            ...(headlessStderrWriter ? { stderrWrite: headlessStderrWriter } : {}),
+        });
+        process.exitCode = exitCode;
+        return;
+    }
     // Bare `pugi` on a TTY enters the REPL-by-default agentic session
     // (Sprint α5.7, ADR-0056). The REPL is the customer-facing surface
     // that brings Pugi to parity with Claude Code / Codex CLI. When the
@@ -538,6 +571,7 @@ function parseArgs(argv) {
         offline: false,
         noTty: false,
         allowFetch: false,
+        allowSearch: false,
         noUpdateCheck: false,
         noSplash: process.env.PUGI_SKIP_SPLASH === '1',
         // Claude triple-review P1 PR #369: default tool-stream pane HIDDEN
@@ -554,6 +588,9 @@ function parseArgs(argv) {
             : true,
         noDefaults: process.env.PUGI_INIT_NO_DEFAULTS === '1',
         decompose: false,
+        // β-headless: --no-tools default OFF so existing flag-free invocations
+        // keep tool advertisement. Flipped only by explicit operator opt-in.
+        noTools: false,
     };
     const args = [];
     // Sprint 2E: `pugi --version` / `-v` are universal install-test conventions
@@ -599,6 +636,12 @@ function parseArgs(argv) {
         else if (arg === '--allow-fetch') {
             flags.allowFetch = true;
         }
+        else if (arg === '--allow-search') {
+            // β1b T4 (2026-05-26): unlock the `web_search` tool for one
+            // invocation, mirroring the `--allow-fetch` gate. Distinct flag
+            // because an operator may want to query without fetching pages.
+            flags.allowSearch = true;
+        }
         else if (arg === '--no-update-check') {
             flags.noUpdateCheck = true;
         }
@@ -634,6 +677,114 @@ function parseArgs(argv) {
             flags.privacy = parsePrivacyMode(next);
             index += 1;
         }
+        else if (arg === '--print') {
+            // β-headless: top-level `--print <brief>` runs a single
+            // non-interactive engine turn. Consumes the next argv token as
+            // the brief — refusing if it looks like another flag so a
+            // dangling `--print --json` does not silently swallow `--json`.
+            const next = argv[index + 1];
+            if (!next || next.startsWith('--')) {
+                throw new Error('--print requires a brief (e.g. --print "create word_counter.py")');
+            }
+            flags.print = next;
+            index += 1;
+        }
+        else if (arg.startsWith('--print=')) {
+            flags.print = arg.slice('--print='.length);
+        }
+        else if (arg === '--cwd') {
+            const next = argv[index + 1];
+            if (!next || next.startsWith('--'))
+                throw new Error('--cwd requires a path');
+            flags.cwd = next;
+            index += 1;
+        }
+        else if (arg.startsWith('--cwd=')) {
+            flags.cwd = arg.slice('--cwd='.length);
+        }
+        else if (arg === '--workspace') {
+            const next = argv[index + 1];
+            if (!next || next.startsWith('--'))
+                throw new Error('--workspace requires a slug');
+            flags.workspace = next;
+            index += 1;
+        }
+        else if (arg.startsWith('--workspace=')) {
+            flags.workspace = arg.slice('--workspace='.length);
+        }
+        else if (arg === '--session') {
+            const next = argv[index + 1];
+            if (!next || next.startsWith('--'))
+                throw new Error('--session requires an id');
+            flags.sessionId = next;
+            index += 1;
+        }
+        else if (arg.startsWith('--session=')) {
+            flags.sessionId = arg.slice('--session='.length);
+        }
+        else if (arg === '--timeout') {
+            const next = argv[index + 1];
+            if (!next || next.startsWith('--'))
+                throw new Error('--timeout requires seconds');
+            const parsed = Number(next);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                throw new Error(`--timeout requires positive seconds, got "${next}"`);
+            }
+            flags.timeoutSeconds = parsed;
+            index += 1;
+        }
+        else if (arg.startsWith('--timeout=')) {
+            const raw = arg.slice('--timeout='.length);
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                throw new Error(`--timeout requires positive seconds, got "${raw}"`);
+            }
+            flags.timeoutSeconds = parsed;
+        }
+        else if (arg === '--no-tools') {
+            flags.noTools = true;
+        }
+        else if (arg === '--max-turns') {
+            const next = argv[index + 1];
+            if (!next || next.startsWith('--'))
+                throw new Error('--max-turns requires an integer');
+            const parsed = Number(next);
+            if (!Number.isInteger(parsed) || parsed <= 0) {
+                throw new Error(`--max-turns requires positive integer, got "${next}"`);
+            }
+            flags.maxTurns = parsed;
+            index += 1;
+        }
+        else if (arg.startsWith('--max-turns=')) {
+            const raw = arg.slice('--max-turns='.length);
+            const parsed = Number(raw);
+            if (!Number.isInteger(parsed) || parsed <= 0) {
+                throw new Error(`--max-turns requires positive integer, got "${raw}"`);
+            }
+            flags.maxTurns = parsed;
+        }
+        else if (arg.startsWith('--commit=')) {
+            // `pugi review --triple --commit <SHA>` activates the multi-
+            // provider routing path against a specific revision.
+            flags.commit = arg.slice('--commit='.length);
+        }
+        else if (arg === '--commit') {
+            const next = argv[index + 1];
+            if (!next)
+                throw new Error('--commit requires a SHA or ref');
+            flags.commit = next;
+            index += 1;
+        }
+        else if (arg.startsWith('--base=')) {
+            flags.base = arg.slice('--base='.length);
+        }
+        else if (arg === '--base') {
+            const next = argv[index + 1];
+            if (!next)
+                throw new Error('--base requires a ref');
+            flags.base = next;
+            index += 1;
+        }
         else {
             args.push(arg);
         }
@@ -701,6 +852,9 @@ async function help(_args, flags, _session) {
         '',
         'Review gate:',
         '  pugi review --triple    Prepare the Anvil-backed triple-review gate.',
+        '  pugi review --triple --commit <SHA>',
+        '                          3-model consensus via Anvil (Anthropic · OpenAI · Google).',
+        '                          Optional: --base <ref> | "<prompt>". Quota: 1 slot per call.',
         '  pugi review --consensus 3-model consensus review (codex · claude · deepseek).',
         '                          Optional: --commit <sha> | --pr <num> | --branch <name>.',
         '                          Exits 0 PASS · 1 WARN · 2 BLOCK.',
@@ -853,6 +1007,9 @@ export async function scaffoldPugiWorkspace(input) {
             mode: 'balanced',
             telemetry: 'off',
         },
+        ui: {
+            cyberZoo: 'on',
+        },
         artifacts: {
             defaultPath: '.pugi/artifacts',
             promoteExplicitly: true,
@@ -860,7 +1017,19 @@ export async function scaffoldPugiWorkspace(input) {
     }, created, skipped);
     writeJsonIfMissing(resolve(pugiDir, 'mcp.json'), {
         schema: 1,
-        servers: [],
+        // 2026-05-27 dogfood: `servers` MUST be an object keyed by server
+        // name (z.record(mcpServerConfigSchema) in
+        // apps/pugi-cli/src/core/mcp/registry.ts:51). A bare `[]` array
+        // here passed schema validation на pugi init exit но crashed
+        // the next dispatch with
+        //   "MCP config at .pugi/mcp.json failed validation:
+        //    servers: Expected object, received array"
+        // and the operator's first command after `pugi init` printed an
+        // error banner before the actual reply. Empty object matches the
+        // schema default and keeps the file forwards-compatible with
+        // `pugi mcp install <name> ...` which merges into the same
+        // record shape.
+        servers: {},
     }, created, skipped);
     writeJsonIfMissing(resolve(pugiDir, 'index.json'), emptyIndex(), created, skipped);
     writeTextIfMissing(resolve(pugiDir, 'PUGI.md'), [
@@ -1282,10 +1451,20 @@ async function review(args, flags, session) {
     // streaming UX and rubric-driven exit codes don't disturb the existing
     // pugi-cli surfaces that depend on the old shape.
     if (flags.consensus) {
+        // 2026-05-27 (Codex r0 P1 on PR #489): pass the globally-parsed
+        // --commit / --base flags to consensus so `pugi review --consensus
+        // --commit X` reviews the requested SHA instead of silently falling
+        // back to the working-tree diff. parseConsensusArgs gives the inline
+        // args (`--commit Y` after the command name) precedence; the
+        // fallback only fires when `args` does not carry the token.
         const exitCode = await runReviewConsensus(args, {
             cwd: root,
             config: resolveRuntimeConfig(),
             json: flags.json,
+            flagsFallback: {
+                ...(flags.commit ? { commit: flags.commit } : {}),
+                ...(flags.base ? { base: flags.base } : {}),
+            },
             emit: (line) => {
                 if (!flags.json)
                     process.stdout.write(line);
@@ -1297,6 +1476,15 @@ async function review(args, flags, session) {
         process.exitCode = exitCode;
         return;
     }
+    if (flags.triple && flags.commit) {
+        // CEO directive 2026-05-27: `pugi review --triple --commit <SHA>`
+        // dispatches to the customer-facing 3-model consensus path through
+        // Anvil's already-paid Anthropic / OpenAI / Google routes. Replaces
+        // the dev-only Codex/Claude/Gemini OAuth CLIs the `/triple-review`
+        // skill uses.
+        await performTripleProviderReview(root, session, flags, prompt);
+        return;
+    }
     if (flags.triple && flags.remote) {
         await performRemoteTripleReview(root, session, flags, prompt);
         return;
@@ -1734,6 +1922,274 @@ async function performRemoteTripleReview(root, session, flags, prompt) {
         .join('\n'));
     process.exitCode = outcome.exitCode;
 }
+/**
+ * `pugi review --triple --commit <SHA>` — customer-facing 3-model
+ * consensus review via Anvil multi-provider routing.
+ *
+ * Dispatches the same diff to Anthropic / OpenAI / Google models
+ * (routed through Anvil's already-paid fleet, NOT OAuth-bound dev
+ * CLIs) and renders the per-reviewer verdict + cross-model
+ * disagreement summary at the end. Quota: one `reviewPerMonth` slot
+ * per call regardless of provider count — the controller-level
+ * `@QuotaGated('reviewPerMonth')` decorator enforces single-slot
+ * debit (see apps/admin-api/src/pugi/pugi.controller.ts).
+ *
+ * CEO directive 2026-05-27: replaces the dev-only `/triple-review`
+ * skill's Codex/Claude/Gemini OAuth dependency with a customer-
+ * runnable Pugi product surface. Dogfood loop: Pugi reviews Pugi PRs.
+ */
+async function performTripleProviderReview(root, session, flags, prompt) {
+    const config = resolveRuntimeConfig();
+    const artifactDir = createArtifactDir(root, prompt || 'triple-providers');
+    const requestPath = resolve(artifactDir, 'triple-review-request.json');
+    const resultPath = resolve(artifactDir, 'triple-review-result.json');
+    const summaryPath = resolve(artifactDir, 'triple-review.md');
+    const toolCallId = recordToolCall(session, 'review:triple-providers', prompt || `review ${flags.commit ?? 'HEAD'} via providers`);
+    // Resolve base ref. CLI flag wins over settings → so an operator
+    // can target a specific integration branch without editing settings.
+    const settings = loadSettings(root);
+    const baseRef = flags.base ?? resolveBaseRef(root, settings) ?? 'origin/main';
+    // Normalise both the commit and the base to short SHAs so the audit
+    // log stores a stable reference even if branches move.
+    const commitRef = flags.commit ?? 'HEAD';
+    // 2026-05-27 (Codex r0 P2 on PR #489): safeGit returns '' on a bad ref
+    // (it swallows the git exit code so callers don't have to wrap every
+    // probe). Without an explicit refusal, a misspelled --commit or --base
+    // produced an EMPTY diff that the gate then PASSED — operators saw a
+    // green review for changes that were never reviewed. Resolve both refs
+    // through `rev-parse --verify` first; an empty result is a hard error.
+    const verifiedCommit = safeGit(root, ['rev-parse', '--verify', commitRef]).trim();
+    if (!verifiedCommit) {
+        throw new Error(`pugi review --triple: cannot resolve --commit '${commitRef}' — ` +
+            `check the SHA or branch name. ` +
+            `Refusing to submit an empty diff for review.`);
+    }
+    const verifiedBase = safeGit(root, ['rev-parse', '--verify', baseRef]).trim();
+    if (!verifiedBase) {
+        throw new Error(`pugi review --triple: cannot resolve --base '${baseRef}' — ` +
+            `check the ref or set base via 'pugi config set review.base=<ref>'. ` +
+            `Refusing to submit an empty diff for review.`);
+    }
+    const resolvedCommit = safeGit(root, ['rev-parse', '--short', commitRef]).trim() || commitRef;
+    const mergeBase = safeGit(root, ['merge-base', baseRef, commitRef]).trim() || '';
+    const diffRange = mergeBase || `${baseRef}..${commitRef}`;
+    const diffArgs = ['diff', diffRange, commitRef, '--', '.', ...PROTECTED_DIFF_EXCLUDES];
+    const diffStatArgs = ['diff', '--shortstat', diffRange, commitRef, '--', '.', ...PROTECTED_DIFF_EXCLUDES];
+    const diffPatch = safeGit(root, diffArgs);
+    const diffStats = parseDiffStats(safeGit(root, diffStatArgs));
+    const requestBody = pugiTripleReviewRequestSchema.parse({
+        schema: 1,
+        workspace: {
+            rootName: root.split('/').at(-1) ?? 'workspace',
+            gitBranch: safeGit(root, ['branch', '--show-current']).trim() || null,
+            gitHead: resolvedCommit || null,
+            baseRef,
+            dirty: Boolean(safeGit(root, ['status', '--short']).trim()),
+        },
+        diffPatch,
+        diffStats,
+        prompt: prompt || undefined,
+        locale: 'en-US',
+        reviewerPersona: 'oes-dev',
+        commit: resolvedCommit,
+        modelProviders: ['claude', 'gpt', 'gemini'],
+    });
+    writeFileSync(requestPath, `${JSON.stringify(requestBody, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    registerArtifact(root, {
+        id: artifactIdFromDir(artifactDir),
+        kind: 'triple-review',
+        path: relative(root, artifactDir),
+        sessionId: session.id,
+        createdAt: new Date().toISOString(),
+        files: ['triple-review-request.json'],
+    });
+    if (!config) {
+        const reason = 'No active Pugi credentials. Run `pugi login --token <PAT>` or set PUGI_API_KEY for CI use.';
+        recordToolResult(session, toolCallId, 'error', reason);
+        writeFileSync(summaryPath, buildTripleReviewMarkdown({
+            prompt,
+            requestPath: relative(root, requestPath),
+            verdict: null,
+            reason,
+            response: null,
+        }), { encoding: 'utf8', mode: 0o600 });
+        writeOutput(flags, {
+            status: 'auth_missing',
+            request: relative(root, requestPath),
+            summary: relative(root, summaryPath),
+        }, [
+            'Pugi triple-provider review request prepared but not sent — no active credentials.',
+            `Request: ${relative(root, requestPath)}`,
+            `Run \`pugi login --token <PAT>\` (or export PUGI_API_KEY for CI) then retry \`pugi review --triple --commit ${resolvedCommit}\`.`,
+        ].join('\n'));
+        process.exitCode = 5;
+        return;
+    }
+    const submitResult = await submitTripleReview(config, requestBody);
+    if (submitResult.status !== 'ok') {
+        const outcome = describeSubmitFailure(submitResult);
+        writeFileSync(summaryPath, buildTripleReviewMarkdown({
+            prompt,
+            requestPath: relative(root, requestPath),
+            verdict: null,
+            reason: outcome.message,
+            response: null,
+        }), { encoding: 'utf8', mode: 0o600 });
+        recordToolResult(session, toolCallId, 'error', outcome.message);
+        writeOutput(flags, {
+            status: submitResult.status,
+            code: submitResult.code,
+            message: outcome.message,
+            request: relative(root, requestPath),
+            summary: relative(root, summaryPath),
+        }, [
+            outcome.headline,
+            `Request: ${relative(root, requestPath)}`,
+            `Summary: ${relative(root, summaryPath)}`,
+            outcome.next ? `Next: ${outcome.next}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n'));
+        process.exitCode = outcome.exitCode;
+        return;
+    }
+    const response = submitResult.response;
+    persistTripleReviewResult(resultPath, response);
+    writeFileSync(summaryPath, buildTripleReviewMarkdown({
+        prompt,
+        requestPath: relative(root, requestPath),
+        verdict: response.verdict,
+        reason: response.reason,
+        response,
+    }), { encoding: 'utf8', mode: 0o600 });
+    recordToolResult(session, toolCallId, response.verdict === 'BLOCK' ? 'error' : 'success', `Verdict: ${response.verdict} (${response.reason})`);
+    const verdictReport = renderTripleProviderVerdict({
+        response,
+        commit: resolvedCommit,
+        baseRef,
+    });
+    writeOutput(flags, {
+        status: 'completed',
+        verdict: response.verdict,
+        reason: response.reason,
+        counts: response.counts,
+        reviewerCount: response.reviewerCount,
+        effectiveTier: response.effectiveTier,
+        commit: resolvedCommit,
+        baseRef,
+        reviewers: response.reviewers.map((r) => ({
+            provider: r.provider ?? null,
+            model: r.model,
+            declaredVerdict: r.declaredVerdict,
+            findings: r.findings,
+            latencyMs: r.latencyMs,
+            tokensUsed: r.tokensUsed,
+            error: r.error,
+        })),
+        result: relative(root, resultPath),
+        summary: relative(root, summaryPath),
+    }, verdictReport);
+    if (response.verdict === 'BLOCK') {
+        process.exitCode = 9;
+    }
+    else if (response.verdict === 'WARN') {
+        process.exitCode = 1;
+    }
+}
+/**
+ * Pretty-printer for the `pugi review --triple --commit <SHA>` verdict.
+ * Mirrors the `/triple-review` skill's verdict block (per-reviewer
+ * counts table → final GATE line → per-reviewer verbatim → cross-
+ * model disagreement summary → tokens/cost note) so the output is
+ * familiar to operators who already use the dev-only skill.
+ */
+export function renderTripleProviderVerdict(input) {
+    const { response, commit, baseRef } = input;
+    const divider = '═'.repeat(68);
+    const subDivider = '─'.repeat(68);
+    // Per-reviewer counts table.
+    const reviewerRows = response.reviewers.map((reviewer) => {
+        const c = { P0: 0, P1: 0, P2: 0, P3: 0 };
+        for (const f of reviewer.findings)
+            c[f.severity] += 1;
+        const status = reviewer.error
+            ? 'ERROR'
+            : reviewer.declaredVerdict ?? 'UNKNOWN';
+        const label = reviewer.provider
+            ? reviewer.provider.toUpperCase().padEnd(8)
+            : reviewer.model.slice(0, 8).padEnd(8);
+        return `   ${label} ${pad(c.P0)} ${pad(c.P1)} ${pad(c.P2)} ${pad(c.P3)}   ${status}`;
+    });
+    // Cross-model disagreement: list severities flagged by 1 of N but not
+    // the others. Surfaces the "highest-signal moment" per the skill.
+    const disagreements = [];
+    const allFindings = response.reviewers.flatMap((r) => r.findings.map((f) => ({
+        provider: r.provider ?? r.model,
+        severity: f.severity,
+        line: f.line,
+        issue: f.issue,
+    })));
+    const p1Flaggers = new Set(response.reviewers
+        .filter((r) => r.findings.some((f) => f.severity === 'P1'))
+        .map((r) => r.provider ?? r.model));
+    if (p1Flaggers.size === 1) {
+        const sole = [...p1Flaggers][0];
+        disagreements.push(`Only ${sole} flagged a P1 — examine the disagreement, often the highest-signal moment.`);
+    }
+    const p0Flaggers = new Set(response.reviewers
+        .filter((r) => r.findings.some((f) => f.severity === 'P0'))
+        .map((r) => r.provider ?? r.model));
+    if (p0Flaggers.size > 0 && p0Flaggers.size < response.reviewers.length) {
+        disagreements.push(`P0 flagged by ${[...p0Flaggers].join(', ')} but not ${response.reviewers
+            .filter((r) => !p0Flaggers.has(r.provider ?? r.model))
+            .map((r) => r.provider ?? r.model)
+            .join(', ')} — verify the finding before merging.`);
+    }
+    // Tokens / cost summary. Tokens are best-effort (some providers
+    // return null). Cost is a placeholder pending billing wire-up; we
+    // surface the quota note inline so the operator knows it counts as
+    // one slot, not three.
+    const totalTokens = response.reviewers.reduce((sum, r) => sum + (r.tokensUsed ?? 0), 0);
+    // Verbatim reviewer outputs. Each section gets a header so operators
+    // can scroll quickly and copy any individual reviewer's text into
+    // their own notes / triage doc.
+    const reviewerSections = response.reviewers.map((reviewer) => {
+        const label = reviewer.provider
+            ? reviewer.provider.toUpperCase()
+            : reviewer.model;
+        const body = reviewer.error
+            ? `(reviewer errored: ${reviewer.error})`
+            : reviewer.rawContent.trim() || '(empty response)';
+        return [subDivider, `${label} SAYS (${reviewer.model}):`, '', body].join('\n');
+    });
+    return [
+        `PUGI TRIPLE-PROVIDER REVIEW — commit ${commit} vs ${baseRef}`,
+        divider,
+        '',
+        `         P0  P1  P2  P3   Status`,
+        ...reviewerRows,
+        '',
+        `GATE: ${response.verdict}`,
+        `Reason: ${response.reason}`,
+        '',
+        ...reviewerSections,
+        '',
+        subDivider,
+        'CROSS-MODEL DISAGREEMENT:',
+        disagreements.length === 0
+            ? '   (none — all reviewers agreed within rubric tolerance)'
+            : disagreements.map((d) => `   - ${d}`).join('\n'),
+        '',
+        `Tokens: ~${totalTokens} total across ${response.reviewers.length} reviewers`,
+        'Quota: charged as 1 review slot (multi-provider counts as a single call).',
+    ].join('\n');
+}
+function pad(n) {
+    return String(n).padStart(2, ' ');
+}
 function describeSubmitFailure(result) {
     switch (result.status) {
         case 'endpoint_missing':
@@ -2293,6 +2749,33 @@ let engineClientFactory = null;
 export function setEngineClientFactory(factory) {
     engineClientFactory = factory;
 }
+/**
+ * β-headless test seam: surface the module-scoped engine client factory
+ * to sibling runtime modules (`headless.ts`) so the same fixture
+ * injection that `setEngineClientFactory` provides for the
+ * `runEngineTask` path applies to `pugi --print` runs. Production
+ * callers never read this — the factory is `null` and falls through
+ * to the real `AnvilEngineLoopClient`.
+ */
+export function getEngineClientFactory() {
+    return engineClientFactory;
+}
+/**
+ * β-headless test seam: optional stdout/stderr writers injected for
+ * `pugi --print` runs. When set, the headless runner forwards every
+ * NDJSON line / human-readable chunk to these closures instead of the
+ * real `process.stdout.write` / `process.stderr.write`. Needed because
+ * `node:test`'s worker pool hijacks `process.stdout` for a binary IPC
+ * channel — a captureStdio override would race the runner's frames
+ * and surface as `Unexpected token '\x0F'` JSON parse failures in spec
+ * assertions. Production never sets these.
+ */
+let headlessStdoutWriter = null;
+let headlessStderrWriter = null;
+export function setHeadlessWriters(writers) {
+    headlessStdoutWriter = writers.stdout ?? null;
+    headlessStderrWriter = writers.stderr ?? null;
+}
 function runEngineTask(kind) {
     return async (args, flags, session) => {
         const label = commandLabel(kind);
@@ -2395,264 +2878,371 @@ function runEngineTask(kind) {
             throw new Error('internal: engine config missing after offline gate');
         }
         const client = engineClientFactory ? engineClientFactory(config) : new AnvilEngineLoopClient(config);
-        const adapter = new NativePugiEngineAdapter({ client, session });
+        // β1b r1 (--allow-fetch / --allow-search wiring, 2026-05-26):
+        // forward operator flags to the adapter so the schema-advertise +
+        // executor-dispatch gates see the OR of (settings.json flag, CLI
+        // flag). PR #425 r1 Backend Architect: the comment at
+        // `tool-bridge.ts:740` documented `--allow-fetch` but the flag was
+        // never wired into the adapter constructor — fix lands here.
+        //
+        // β4 r2 P1 #3 — load the MCP registry pre-run so the engine's
+        // tool-bridge advertises every trusted server's tools under
+        // `mcp__<server>__<tool>`. Before this fix the registry was never
+        // loaded in the CLI engine path: `pugi mcp install` + `pugi mcp
+        // trust` ran successfully but `pugi code/explain/fix/build` still
+        // saw zero `mcp__*` tools in the schema (so the feature was
+        // non-functional at the customer-facing surface). The adapter does
+        // NOT own the registry lifecycle — we tear it down in the `finally`
+        // below regardless of outcome so live MCP child processes are
+        // reaped before the CLI exits.
+        //
+        // Failure mode: a bad `.pugi/mcp.json` (corrupted JSON, schema
+        // violation) bubbles as an exception from `loadMcpRegistry`. We
+        // surface it as a warning on stderr and continue WITHOUT MCP — the
+        // operator's `pugi code "..."` invocation should not fail just
+        // because a stale MCP entry refuses to parse. They get the engine
+        // run without `mcp__*` tools and a clear hint to fix the file.
+        let mcpRegistry;
+        try {
+            mcpRegistry = await loadMcpRegistry(root);
+        }
+        catch (error) {
+            process.stderr.write(`pugi ${label}: MCP registry load failed — ${error.message}. ` +
+                `Continuing without MCP tools. Fix .pugi/mcp.json to enable.\n`);
+            mcpRegistry = undefined;
+        }
+        // P1 fix (deep audit 2026-05-26): load the workspace HookRegistry so
+        // `.pugi/hooks/` lifecycle hooks fire for model-initiated tool calls
+        // from the engine loop, not just for direct CLI tool invocations.
+        // SECURITY: a `PreToolUse onFailure: 'block'` hook that refuses bash
+        // containing `rm` now applies to model dispatch. Before this fix the
+        // hooks were INVISIBLE to the engine adapter — a workspace operator
+        // who set up a block hook for destructive bash would still see the
+        // model freely dispatch those calls.
+        //
+        // r2 fix (triple-review 2026-05-26 P2): the fail-open path is a
+        // security hole. If `.pugi/hooks.json` exists but is malformed
+        // (truncated write, typo, partial edit) and the operator has block
+        // hooks configured, the previous `continue without hooks` silently
+        // disabled the BLOCK rules — a hostile or careless mutation of the
+        // file would turn off all SECURITY-CRITICAL refusals without any
+        // visible signal. We now distinguish three cases:
+        //
+        //   (a) Neither user nor project hooks file exists → no hooks. Safe.
+        //   (b) File(s) exist and load() succeeds → hooks live. Normal.
+        //   (c) File(s) exist and load() fails → REFUSE THE RUN with a
+        //       fatal stderr message and `process.exit(1)`. Operator must
+        //       fix the file OR set `PUGI_HOOKS_BYPASS=1` to override (the
+        //       escape hatch is logged loudly so it cannot be silent).
+        //
+        // The bypass env var exists for the mid-edit recovery case (the
+        // operator is in the middle of fixing the file and needs to run
+        // pugi to see the world state). It is NEVER a default — the
+        // operator types it explicitly.
+        const hookOutcome = await loadHookRegistryOrExit({
+            workspaceRoot: root,
+            session,
+            label,
+        });
+        if (hookOutcome.kind === 'parse-failure-refused') {
+            // The helper already emitted the fatal message on stderr. Exit
+            // directly so dispatchEngineCommand's caller observes a non-zero
+            // exit code without a stack trace.
+            process.exit(1);
+        }
+        const hooks = hookOutcome.hooks;
+        const adapter = new NativePugiEngineAdapter({
+            client,
+            session,
+            allowFetch: flags.allowFetch,
+            allowSearch: flags.allowSearch,
+            ...(mcpRegistry ? { mcpRegistry } : {}),
+            ...(hooks ? { hooks } : {}),
+            // Non-interactive CLI path: the FSM prompt callback always denies
+            // until the operator explicitly grants permission via
+            // `pugi mcp perms` (out-of-band). A future Ink-backed REPL path
+            // overrides this with a modal prompt; pipes / CI never auto-allow.
+            mcpPrompt: defaultNonInteractiveMcpPrompt,
+            // P1 fix (deep audit 2026-05-26): CLI dispatcher is non-interactive
+            // by default — pipes, CI, and scripted `pugi code "..."` runs do
+            // not have an ink modal to surface ask_user_question into. The
+            // REPL layer (β2b ink modal wiring, future) overrides this with
+            // `interactive: true` + a live askUserBridge.
+            interactive: false,
+        });
         const toolCallId = recordToolCall(session, `engine:${adapter.name}`, `${label}: ${prompt}`);
         const taskId = `${kind}-${Date.now()}`;
-        const events = adapter.run({
-            id: taskId,
-            kind,
-            prompt,
-            workspaceRoot: root,
-            allowedPaths: [root],
-            deniedPaths: [],
-            artifacts: [],
-            // plan mode is enforced inside the tool-bridge (read-only schema +
-            // executor refusal sentinel). The permission mode here is the
-            // workspace-level toggle and is unchanged from interactive default.
-            permissionMode: 'auto',
-        }, { sessionId: session.id });
-        const statusEvents = [];
-        let result = null;
-        for await (const event of events) {
-            if (event.type === 'status') {
-                statusEvents.push(event.message);
-                // For `explain` the spec wants status events on stderr so the
-                // final summary on stdout is grep-able. Other commands keep the
-                // events on stdout-via-final-text so the operator sees the
-                // chronological trace.
-                if (kind === 'explain' && !flags.json) {
-                    process.stderr.write(`${event.message}\n`);
+        // β4 r2 P1 #3 — try/finally so loaded MCP child processes are
+        // reaped regardless of run outcome (success, blocked, failed,
+        // thrown). The shutdown is best-effort; we never want a stuck
+        // MCP server to mask a successful Pugi run.
+        try {
+            const events = adapter.run({
+                id: taskId,
+                kind,
+                prompt,
+                workspaceRoot: root,
+                allowedPaths: [root],
+                deniedPaths: [],
+                artifacts: [],
+                // plan mode is enforced inside the tool-bridge (read-only schema +
+                // executor refusal sentinel). The permission mode here is the
+                // workspace-level toggle and is unchanged from interactive default.
+                permissionMode: 'auto',
+            }, { sessionId: session.id });
+            const statusEvents = [];
+            let result = null;
+            for await (const event of events) {
+                if (event.type === 'status') {
+                    statusEvents.push(event.message);
+                    // For `explain` the spec wants status events on stderr so the
+                    // final summary on stdout is grep-able. Other commands keep the
+                    // events on stdout-via-final-text so the operator sees the
+                    // chronological trace.
+                    if (kind === 'explain' && !flags.json) {
+                        process.stderr.write(`${event.message}\n`);
+                    }
+                }
+                else {
+                    result = {
+                        status: event.result.status,
+                        summary: event.result.summary,
+                        filesChanged: event.result.filesChanged,
+                        eventRefs: event.result.eventRefs,
+                        risks: event.result.risks,
+                    };
                 }
             }
-            else {
+            if (!result) {
+                // Adapter MUST emit a terminal result event. Treat the empty
+                // outcome as a failure so the CLI surfaces a clear error rather
+                // than exiting 0 with no output.
                 result = {
-                    status: event.result.status,
-                    summary: event.result.summary,
-                    filesChanged: event.result.filesChanged,
-                    eventRefs: event.result.eventRefs,
-                    risks: event.result.risks,
+                    status: 'failed',
+                    summary: 'engine adapter returned no result',
+                    filesChanged: [],
+                    eventRefs: [],
+                    risks: ['adapter terminated without emitting a result event'],
                 };
             }
-        }
-        if (!result) {
-            // Adapter MUST emit a terminal result event. Treat the empty
-            // outcome as a failure so the CLI surfaces a clear error rather
-            // than exiting 0 with no output.
-            result = {
-                status: 'failed',
-                summary: 'engine adapter returned no result',
-                filesChanged: [],
-                eventRefs: [],
-                risks: ['adapter terminated without emitting a result event'],
-            };
-        }
-        // α6.6 diff escalation — Layer A/B/C dispatcher.
-        //
-        // Some models emit file edits as inline SEARCH/REPLACE markers in
-        // the final response rather than through tool calls (especially
-        // Gemini and o1 family, which under-use tool schemas in long
-        // reasoning chains). We run the dispatcher against the model's
-        // final text so those markers still land on disk. Tool-call edits
-        // (Layer-A equivalent already handled by `edit`/`write` tools) are
-        // unaffected — the dispatcher only fires on prose blocks that
-        // happen to contain markers.
-        //
-        // Scope: code / fix / build / explain only. `plan` is read-only
-        // (the engine refuses write tools), so even a stray marker in plan
-        // output gets ignored to honour the plan-mode contract.
-        //
-        // Dry-run + read-only short-circuits: when the flags forbid writes
-        // we dispatch with `dryRun: true` so the operator still sees what
-        // WOULD have been written, but nothing touches disk.
-        let dispatchResults = [];
-        if (kind === 'code' || kind === 'fix' || kind === 'build_task') {
-            dispatchResults = await runMarkerDispatch({
-                root,
-                result: {
-                    status: result.status,
-                    summary: result.summary,
-                    eventRefs: result.eventRefs,
-                },
-                dryRun: flags.dryRun,
-            });
-            // Merge dispatcher-touched files into `result.filesChanged` so the
-            // operator-facing summary lists them alongside tool-driven edits.
-            for (const dr of dispatchResults) {
-                if (dr.ok && dr.absPath) {
-                    const rel = relative(root, dr.absPath);
-                    if (!result.filesChanged.includes(rel))
-                        result.filesChanged.push(rel);
+            // α6.6 diff escalation — Layer A/B/C dispatcher.
+            //
+            // Some models emit file edits as inline SEARCH/REPLACE markers in
+            // the final response rather than through tool calls (especially
+            // Gemini and o1 family, which under-use tool schemas in long
+            // reasoning chains). We run the dispatcher against the model's
+            // final text so those markers still land on disk. Tool-call edits
+            // (Layer-A equivalent already handled by `edit`/`write` tools) are
+            // unaffected — the dispatcher only fires on prose blocks that
+            // happen to contain markers.
+            //
+            // Scope: code / fix / build / explain only. `plan` is read-only
+            // (the engine refuses write tools), so even a stray marker in plan
+            // output gets ignored to honour the plan-mode contract.
+            //
+            // Dry-run + read-only short-circuits: when the flags forbid writes
+            // we dispatch with `dryRun: true` so the operator still sees what
+            // WOULD have been written, but nothing touches disk.
+            let dispatchResults = [];
+            if (kind === 'code' || kind === 'fix' || kind === 'build_task') {
+                dispatchResults = await runMarkerDispatch({
+                    root,
+                    result: {
+                        status: result.status,
+                        summary: result.summary,
+                        eventRefs: result.eventRefs,
+                    },
+                    dryRun: flags.dryRun,
+                });
+                // Merge dispatcher-touched files into `result.filesChanged` so the
+                // operator-facing summary lists them alongside tool-driven edits.
+                for (const dr of dispatchResults) {
+                    if (dr.ok && dr.absPath) {
+                        const rel = relative(root, dr.absPath);
+                        if (!result.filesChanged.includes(rel))
+                            result.filesChanged.push(rel);
+                    }
                 }
             }
-        }
-        // For `plan` we always write a plan.md artifact, regardless of
-        // outcome. A blocked plan (budget exhausted, tool refusal) still
-        // produces a reviewable artifact — the reason is recorded inline.
-        let planArtifact = null;
-        if (kind === 'plan') {
-            planArtifact = writePlanArtifact({
-                root,
-                session,
-                prompt,
-                result,
-                statusEvents,
-            });
-        }
-        // α6.8 EXTEND PR1: `--decompose` post-processing. We only attempt
-        // the parse on a `done` plan (a blocked/failed plan is already
-        // captured in plan.md with its reason; no JSON to extract). The
-        // model's final answer arrives via `result.summary` — on success
-        // the adapter prefix is empty so it is the raw final text. We
-        // strip any leading/trailing whitespace then run the parser
-        // against the contents. On parse failure we surface a non-fatal
-        // structured error in the payload — the operator still gets the
-        // plan.md artifact and can re-run.
-        //
-        // TODO(α7.x): `result.summary` is currently a string contract that
-        // doubles as both "human-readable headline" and "raw final model
-        // text". Split into `{ summary, finalText }` on the adapter so the
-        // parser does not have to assume the prefix is empty. Tracked in
-        // PR #423 v2 retro (P2.6, Claude review).
-        let decomposeArtifact = null;
-        let decomposeError = null;
-        if (flags.decompose && kind === 'plan' && result.status === 'done') {
-            const parsed = parseDecompositionFromText(result.summary);
-            if (parsed.ok) {
-                decomposeArtifact = writeDecomposition({
+            // For `plan` we always write a plan.md artifact, regardless of
+            // outcome. A blocked plan (budget exhausted, tool refusal) still
+            // produces a reviewable artifact — the reason is recorded inline.
+            let planArtifact = null;
+            if (kind === 'plan') {
+                planArtifact = writePlanArtifact({
                     root,
-                    sessionId: session.id,
-                    // Persist the OPERATOR's original prompt, not the prompt+suffix
-                    // we sent to the engine. The suffix is plumbing; the manifest
-                    // header reads naturally only with the operator text.
-                    prompt: args.join(' ').trim() || prompt,
-                    decomposition: parsed.decomposition,
-                    rationale: parsed.rationale,
+                    session,
+                    prompt,
+                    result,
+                    statusEvents,
                 });
             }
+            // α6.8 EXTEND PR1: `--decompose` post-processing. We only attempt
+            // the parse on a `done` plan (a blocked/failed plan is already
+            // captured in plan.md with its reason; no JSON to extract). The
+            // model's final answer arrives via `result.summary` — on success
+            // the adapter prefix is empty so it is the raw final text. We
+            // strip any leading/trailing whitespace then run the parser
+            // against the contents. On parse failure we surface a non-fatal
+            // structured error in the payload — the operator still gets the
+            // plan.md artifact and can re-run.
+            //
+            // TODO(α7.x): `result.summary` is currently a string contract that
+            // doubles as both "human-readable headline" and "raw final model
+            // text". Split into `{ summary, finalText }` on the adapter so the
+            // parser does not have to assume the prefix is empty. Tracked in
+            // PR #423 v2 retro (P2.6, Claude review).
+            let decomposeArtifact = null;
+            let decomposeError = null;
+            if (flags.decompose && kind === 'plan' && result.status === 'done') {
+                const parsed = parseDecompositionFromText(result.summary);
+                if (parsed.ok) {
+                    decomposeArtifact = writeDecomposition({
+                        root,
+                        sessionId: session.id,
+                        // Persist the OPERATOR's original prompt, not the prompt+suffix
+                        // we sent to the engine. The suffix is plumbing; the manifest
+                        // header reads naturally only with the operator text.
+                        prompt: args.join(' ').trim() || prompt,
+                        decomposition: parsed.decomposition,
+                        rationale: parsed.rationale,
+                    });
+                }
+                else {
+                    decomposeError = { reason: parsed.reason, detail: parsed.detail };
+                }
+            }
+            // Pull the headline metrics out of `eventRefs` so the summary and
+            // JSON envelope match without re-parsing strings in two places.
+            const metrics = parseEventRefs(result.eventRefs);
+            const finalStatus = result.status === 'failed' ? 'error' : 'success';
+            recordToolResult(session, toolCallId, finalStatus, result.summary);
+            // Exit code policy (spec §1-§5):
+            //   code/fix/build  → 0 done, 8 failed, 9 blocked
+            //   explain         → same triple; read-only blocked = budget exhaustion
+            //   plan            → 0 on done OR plan-mode refusal (refusal is a
+            //                     SUCCESS for plan: the gate worked); 8 on failed
+            //                     transport; 9 on budget exhaustion.
+            //
+            // Code Reviewer P2 retro 2026-05-23: previously `plan` masked
+            // `budget_exhausted` as exit 0, so a CI loop with a token budget
+            // hit looked identical to a successful plan. We now distinguish
+            // via the adapter's `outcome=<status>` echo on `eventRefs` so
+            // shell wrappers can branch on the real cause.
+            if (kind === 'plan') {
+                if (result.status === 'failed') {
+                    process.exitCode = ENGINE_EXIT_CODES.failed;
+                }
+                else if (result.status === 'blocked' &&
+                    metrics.outcome === 'budget_exhausted') {
+                    process.exitCode = ENGINE_EXIT_CODES.blocked;
+                }
+                else {
+                    // `done`, or `blocked` with outcome=tool_refused (= the plan-mode
+                    // gate fired, which is the contract working as designed), or
+                    // `blocked` with no outcome echo (legacy adapter — preserve the
+                    // pre-retro 0 behaviour to avoid breaking external scripts).
+                    process.exitCode = 0;
+                }
+            }
             else {
-                decomposeError = { reason: parsed.reason, detail: parsed.detail };
+                process.exitCode = ENGINE_EXIT_CODES[result.status];
             }
-        }
-        // Pull the headline metrics out of `eventRefs` so the summary and
-        // JSON envelope match without re-parsing strings in two places.
-        const metrics = parseEventRefs(result.eventRefs);
-        const finalStatus = result.status === 'failed' ? 'error' : 'success';
-        recordToolResult(session, toolCallId, finalStatus, result.summary);
-        // Exit code policy (spec §1-§5):
-        //   code/fix/build  → 0 done, 8 failed, 9 blocked
-        //   explain         → same triple; read-only blocked = budget exhaustion
-        //   plan            → 0 on done OR plan-mode refusal (refusal is a
-        //                     SUCCESS for plan: the gate worked); 8 on failed
-        //                     transport; 9 on budget exhaustion.
-        //
-        // Code Reviewer P2 retro 2026-05-23: previously `plan` masked
-        // `budget_exhausted` as exit 0, so a CI loop with a token budget
-        // hit looked identical to a successful plan. We now distinguish
-        // via the adapter's `outcome=<status>` echo on `eventRefs` so
-        // shell wrappers can branch on the real cause.
-        if (kind === 'plan') {
-            if (result.status === 'failed') {
-                process.exitCode = ENGINE_EXIT_CODES.failed;
+            const payload = {
+                command: label,
+                taskId,
+                status: result.status,
+                summary: result.summary,
+                filesChanged: result.filesChanged,
+                toolCalls: metrics.toolCalls,
+                turns: metrics.turns,
+                tokens: metrics.tokens,
+                sessionId: session.id,
+                sessionEventsMirror: metrics.mirror,
+                risks: result.risks,
+                plan: planArtifact ? { path: planArtifact.relPath } : undefined,
+                // α6.6 — per-edit dispatcher trace. Empty array when no inline
+                // markers were detected in the model's final response.
+                diffEdits: dispatchResults.map((dr) => ({
+                    layer: dr.layer,
+                    file: dr.file,
+                    ok: dr.ok,
+                    bytesWritten: dr.bytesWritten,
+                    reason: dr.reason,
+                    detail: dr.detail,
+                })),
+                // α6.8 EXTEND PR1: decompose artifacts (only present when
+                // `--decompose` was passed AND the model emitted a parseable
+                // JSON block). The `error` shape lands when the model returned
+                // unparseable output; the operator can re-run with a tighter
+                // prompt without losing the plain plan.md artifact.
+                decompose: decomposeArtifact !== null
+                    ? {
+                        manifest: relative(root, decomposeArtifact.manifestPath),
+                        planDir: relative(root, decomposeArtifact.planDir),
+                        splits: decomposeArtifact.splitPaths,
+                    }
+                    : decomposeError !== null
+                        ? { error: decomposeError }
+                        : undefined,
+                // The full event stream is useful for cabinet UI replay. We surface
+                // it in JSON mode only — text mode operators want the summary, not
+                // 30 turn-level lines.
+                events: flags.json ? statusEvents : undefined,
+            };
+            const textLines = [];
+            if (kind === 'plan' && planArtifact) {
+                textLines.push(`Pugi plan written to ${planArtifact.relPath}`);
             }
-            else if (result.status === 'blocked' &&
-                metrics.outcome === 'budget_exhausted') {
-                process.exitCode = ENGINE_EXIT_CODES.blocked;
+            if (decomposeArtifact !== null) {
+                textLines.push(`Decomposition: ${decomposeArtifact.splitPaths.length} component spec${decomposeArtifact.splitPaths.length === 1 ? '' : 's'} under ${relative(root, decomposeArtifact.planDir)}`);
+                textLines.push(`Manifest: ${relative(root, decomposeArtifact.manifestPath)}`);
             }
-            else {
-                // `done`, or `blocked` with outcome=tool_refused (= the plan-mode
-                // gate fired, which is the contract working as designed), or
-                // `blocked` with no outcome echo (legacy adapter — preserve the
-                // pre-retro 0 behaviour to avoid breaking external scripts).
-                process.exitCode = 0;
+            else if (decomposeError !== null) {
+                textLines.push(`Decomposition: skipped (${decomposeError.reason}) — plan.md still written`);
             }
-        }
-        else {
-            process.exitCode = ENGINE_EXIT_CODES[result.status];
-        }
-        const payload = {
-            command: label,
-            taskId,
-            status: result.status,
-            summary: result.summary,
-            filesChanged: result.filesChanged,
-            toolCalls: metrics.toolCalls,
-            turns: metrics.turns,
-            tokens: metrics.tokens,
-            sessionId: session.id,
-            sessionEventsMirror: metrics.mirror,
-            risks: result.risks,
-            plan: planArtifact ? { path: planArtifact.relPath } : undefined,
-            // α6.6 — per-edit dispatcher trace. Empty array when no inline
-            // markers were detected in the model's final response.
-            diffEdits: dispatchResults.map((dr) => ({
-                layer: dr.layer,
-                file: dr.file,
-                ok: dr.ok,
-                bytesWritten: dr.bytesWritten,
-                reason: dr.reason,
-                detail: dr.detail,
-            })),
-            // α6.8 EXTEND PR1: decompose artifacts (only present when
-            // `--decompose` was passed AND the model emitted a parseable
-            // JSON block). The `error` shape lands when the model returned
-            // unparseable output; the operator can re-run with a tighter
-            // prompt without losing the plain plan.md artifact.
-            decompose: decomposeArtifact !== null
-                ? {
-                    manifest: relative(root, decomposeArtifact.manifestPath),
-                    planDir: relative(root, decomposeArtifact.planDir),
-                    splits: decomposeArtifact.splitPaths,
-                }
-                : decomposeError !== null
-                    ? { error: decomposeError }
-                    : undefined,
-            // The full event stream is useful for cabinet UI replay. We surface
-            // it in JSON mode only — text mode operators want the summary, not
-            // 30 turn-level lines.
-            events: flags.json ? statusEvents : undefined,
-        };
-        const textLines = [];
-        if (kind === 'plan' && planArtifact) {
-            textLines.push(`Pugi plan written to ${planArtifact.relPath}`);
-        }
-        if (decomposeArtifact !== null) {
-            textLines.push(`Decomposition: ${decomposeArtifact.splitPaths.length} component spec${decomposeArtifact.splitPaths.length === 1 ? '' : 's'} under ${relative(root, decomposeArtifact.planDir)}`);
-            textLines.push(`Manifest: ${relative(root, decomposeArtifact.manifestPath)}`);
-        }
-        else if (decomposeError !== null) {
-            textLines.push(`Decomposition: skipped (${decomposeError.reason}) — plan.md still written`);
-        }
-        textLines.push(`Pugi ${label}: ${result.status}`);
-        textLines.push(`Summary: ${result.summary}`);
-        if (result.filesChanged.length > 0) {
-            textLines.push(`Files modified (${result.filesChanged.length}):`);
-            for (const file of result.filesChanged)
-                textLines.push(`  - ${file}`);
-        }
-        else if (kind !== 'explain' && kind !== 'plan') {
-            textLines.push('Files modified: none');
-        }
-        textLines.push(`Tool calls: ${metrics.toolCalls} · Turns: ${metrics.turns} · Tokens: ${metrics.tokens}`);
-        if (dispatchResults.length > 0) {
-            const okCount = dispatchResults.filter((d) => d.ok).length;
-            const failCount = dispatchResults.length - okCount;
-            textLines.push(`Diff dispatch: ${okCount} applied, ${failCount} rejected (${dispatchResults.length} marker block${dispatchResults.length === 1 ? '' : 's'})`);
-            for (const dr of dispatchResults) {
-                if (dr.ok) {
-                    textLines.push(`  + ${dr.layer} ${dr.file} (${dr.bytesWritten} bytes)`);
-                }
-                else {
-                    textLines.push(`  ! ${dr.layer} ${dr.file}: ${dr.reason ?? 'failure'} — ${dr.detail ?? ''}`);
+            textLines.push(`Pugi ${label}: ${result.status}`);
+            textLines.push(`Summary: ${result.summary}`);
+            if (result.filesChanged.length > 0) {
+                textLines.push(`Files modified (${result.filesChanged.length}):`);
+                for (const file of result.filesChanged)
+                    textLines.push(`  - ${file}`);
+            }
+            else if (kind !== 'explain' && kind !== 'plan') {
+                textLines.push('Files modified: none');
+            }
+            textLines.push(`Tool calls: ${metrics.toolCalls} · Turns: ${metrics.turns} · Tokens: ${metrics.tokens}`);
+            if (dispatchResults.length > 0) {
+                const okCount = dispatchResults.filter((d) => d.ok).length;
+                const failCount = dispatchResults.length - okCount;
+                textLines.push(`Diff dispatch: ${okCount} applied, ${failCount} rejected (${dispatchResults.length} marker block${dispatchResults.length === 1 ? '' : 's'})`);
+                for (const dr of dispatchResults) {
+                    if (dr.ok) {
+                        textLines.push(`  + ${dr.layer} ${dr.file} (${dr.bytesWritten} bytes)`);
+                    }
+                    else {
+                        textLines.push(`  ! ${dr.layer} ${dr.file}: ${dr.reason ?? 'failure'} — ${dr.detail ?? ''}`);
+                    }
                 }
             }
+            if (result.risks.length > 0) {
+                textLines.push(`Risks: ${result.risks.join('; ')}`);
+            }
+            textLines.push(`Session: ${session.id}`);
+            if (metrics.mirror)
+                textLines.push(`Events mirror: ${metrics.mirror}`);
+            writeOutput(flags, payload, textLines.join('\n'));
         }
-        if (result.risks.length > 0) {
-            textLines.push(`Risks: ${result.risks.join('; ')}`);
+        finally {
+            // β4 r2 P1 #3 — tear down live MCP child processes BEFORE the
+            // CLI exits. shutdown() is idempotent and swallows per-server
+            // disconnect errors, so it is safe even if no servers connected.
+            if (mcpRegistry) {
+                await mcpRegistry.shutdown().catch((error) => {
+                    process.stderr.write(`pugi ${label}: MCP registry shutdown reported error — ${error.message}\n`);
+                });
+            }
         }
-        textLines.push(`Session: ${session.id}`);
-        if (metrics.mirror)
-            textLines.push(`Events mirror: ${metrics.mirror}`);
-        writeOutput(flags, payload, textLines.join('\n'));
     };
 }
 // Exported for the α6.6.1 triple-review remediation spec