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

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,92 @@ 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 {
             args.push(arg);
         }
@@ -853,6 +982,9 @@ export async function scaffoldPugiWorkspace(input) {
             mode: 'balanced',
             telemetry: 'off',
         },
+        ui: {
+            cyberZoo: 'on',
+        },
         artifacts: {
             defaultPath: '.pugi/artifacts',
             promoteExplicitly: true,
@@ -2293,6 +2425,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 +2554,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