@pugi/cli 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/runtime/cli.js

@@ -1,38 +1,50 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { statSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 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';
 import { resolveWorkspacePath } from '../core/path-security.js';
 import { globTool, grepTool, readTool } from '../tools/file-tools.js';
-import { toolRegistry, toolSchemaBundleHashInput } from '../tools/registry.js';
 import { webFetchTool } from '../tools/web-fetch.js';
 import { emptyIndex, rebuildIndex, readIndex, upsertArtifact, writeIndex, } from '../core/index-store.js';
 import { signatureForPlanReview } from '../core/repl/ask.js';
-import { buildRuntimeConfig, loadRuntimeConfig, pollDeviceFlow, pugiHandoffBundleSchema, pugiSyncDryRunPlanSchema, pugiSyncPrivacyModeSchema, pugiSyncRequestSchema, pugiSyncUploadPlanSchema, pugiTripleReviewRequestSchema, startDeviceFlow, submitSync, submitTripleReview, } from '@pugi/sdk';
+import { buildRuntimeConfig, fetchPersonaRoster, loadRuntimeConfig, openPugiSession, pollDeviceFlow, pugiHandoffBundleSchema, pugiSyncDryRunPlanSchema, pugiSyncPrivacyModeSchema, pugiSyncRequestSchema, pugiSyncUploadPlanSchema, pugiTripleReviewRequestSchema, startDeviceFlow, submitDelegate, submitSync, submitTripleReview, } from '@pugi/sdk';
 import { PUGI_TAGLINE } from '@pugi/personas';
+import { resolveRoster, renderRosterTable } from './commands/roster.js';
+import { runDelegateCommand } from './commands/delegate.js';
 import { clearApiKey, DEFAULT_API_URL, listStoredCredentials, maskApiKey, normalizeApiUrl, purgeAllCredentials, readCredentialsFile, resolveActiveCredential, storeApiKey, switchActiveAccount, } from '../core/credentials.js';
 import { runDeployCommand } from '../commands/deploy.js';
 import { runJobsCommand } from '../commands/jobs.js';
 import { runConfigCommand } from './commands/config.js';
 import { runPrivacyCommand } from './commands/privacy.js';
+import { runReport } from './commands/report.js';
+import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.js';
+import { runStatusCommand, defaultStatusHome, } from './commands/status.js';
 import { runUndoCommand } from './commands/undo.js';
+import { runCompactCommand } from './commands/compact.js';
 import { runBudgetCommand } from './commands/budget.js';
+import { runCostCommand } from './commands/cost.js';
 import { runSkillsCommand } from './commands/skills.js';
+import { installDefaultSkills } from '../core/skills/defaults.js';
 import { runAgentsCommand } from './commands/agents.js';
 import { runLspCommand } from './commands/lsp.js';
 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 { runPermissionsCommand } from './commands/permissions.js';
+import { parsePermissionMode } from '../core/permissions/index.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';
 import { dispatchEdit, } from '../core/edits/index.js';
@@ -47,7 +59,15 @@ import { dispatchEdit, } from '../core/edits/index.js';
  * packages/pugi-sdk/package.json); the publish workflow validates the
  * three are in lockstep.
  */
-const PUGI_CLI_VERSION = "0.1.0-beta.2";
+// 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,
@@ -56,6 +76,8 @@ const handlers = {
     budget: dispatchBudget,
     code: runEngineTask('code'),
     config: dispatchConfig,
+    cost: dispatchCost,
+    delegate: dispatchDelegate,
     deploy: dispatchDeploy,
     doctor,
     explain: runEngineTask('explain'),
@@ -68,16 +90,30 @@ const handlers = {
     login,
     logout,
     lsp: dispatchLsp,
+    mcp: dispatchMcp,
     patch: dispatchPatch,
+    permissions: dispatchPermissions,
+    perms: dispatchPermissions,
     plan: runEngineTask('plan'),
     'plan-review': dispatchPlanReview,
     privacy: dispatchPrivacy,
+    // PAVF-7 (2026-05-27): `pugi report --from-error` captures the
+    // most-recent failed session as a redacted bundle so operators can
+    // file clean bug reports without manual log-grepping.
+    report: dispatchReport,
     review,
     resume,
+    roster: dispatchRoster,
     sessions,
     skills: dispatchSkills,
+    status,
     sync,
     undo: dispatchUndo,
+    compact: dispatchCompact,
+    // L19 (2026-05-27): `pugi usage` is an alias of `pugi cost` — same
+    // handler, same flags. Operators trained on Claude Code expect either
+    // verb to surface the per-model token + USD table.
+    usage: dispatchCost,
     version,
     web: dispatchWeb,
     whoami,
@@ -252,6 +288,78 @@ async function dispatchPrivacy(args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * PAVF-7 (2026-05-27): `pugi report --from-error` — bundle the most-
+ * recent failed session into a redacted local report so operators can
+ * file clean bug tickets without manual log-grepping. v1 is local-only
+ * (no auto-upload — see commands/report.ts header for the rationale).
+ */
+async function dispatchReport(args, flags, _session) {
+    const rc = runReport(args, {
+        cwd: process.cwd(),
+        json: flags.json,
+        emit: (line) => {
+            if (!flags.json)
+                process.stdout.write(line);
+        },
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
+/**
+ * `pugi roster` - α7.5 Phase 1.
+ *
+ * List the live Tier 1 personas with display name, role, and routing
+ * tag. Walks the remote /api/pugi/sessions/roster endpoint when a
+ * credential is available; falls back to the local @pugi/personas
+ * roster when offline so the operator can still see who is on the team.
+ */
+async function dispatchRoster(_args, flags, _session) {
+    const credential = resolveActiveCredential();
+    const config = credential
+        ? buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey })
+        : null;
+    const { rows, warning } = await resolveRoster(config);
+    const payload = {
+        ok: true,
+        personas: rows,
+        warning,
+    };
+    const text = (warning ? `# warning: ${warning}\n\n` : '') +
+        renderRosterTable(rows);
+    writeOutput(flags, payload, text);
+}
+/**
+ * `pugi delegate <slug> "<brief>"` - α7.5 Phase 1.
+ *
+ * Open a fresh REPL session and POST the brief to one Tier 1 persona,
+ * bypassing Mira's coordinator pass. Non-interactive: the CLI prints
+ * the dispatch id on success and exits; the operator (or a script) can
+ * subscribe to the session stream separately if they want the live
+ * lifecycle. Interactive operators use `/delegate` from inside the REPL
+ * instead so the dispatch lifecycle surfaces inline.
+ */
+async function dispatchDelegate(args, flags, _session) {
+    await runDelegateCommand(args, {
+        workspaceCwd: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        resolveConfig: () => {
+            const credential = resolveActiveCredential();
+            if (!credential)
+                return null;
+            return buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey });
+        },
+        fetchRoster: fetchPersonaRoster,
+        submitDelegate,
+        openSession: async (config, workspaceCwd) => {
+            const result = await openPugiSession(config, { workspaceCwd });
+            if (result.status === 'ok')
+                return { sessionId: result.response.sessionId };
+            return { error: `${result.status}: ${result.message}` };
+        },
+    });
+}
 async function dispatchUndo(args, flags, session) {
     await runUndoCommand(args, {
         workspaceRoot: process.cwd(),
@@ -259,12 +367,77 @@ async function dispatchUndo(args, flags, session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * Leak L8 (2026-05-27) — `pugi compact` summarises older REPL turns
+ * into a single boundary marker, freeing context for the next `pugi
+ * resume <id>`. The slash `/compact` inside a live REPL forwards
+ * through the same runner via session.ts so the surface stays single-
+ * sourced.
+ */
+async function dispatchCompact(args, flags, _session) {
+    const result = await runCompactCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (result.status === 'failed_no_session'
+        || result.status === 'failed_transport'
+        || result.status === 'failed_store') {
+        process.exitCode = 1;
+        return;
+    }
+    if (result.status === 'noop_empty' || result.status === 'noop_recent_marker') {
+        process.exitCode = 2;
+    }
+}
 async function dispatchBudget(args, flags, _session) {
     await runBudgetCommand(args, {
         workspaceRoot: process.cwd(),
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * Leak L6 — `pugi permissions [mode] [--persist] [--confirm]`.
+ *
+ * Surface the same intent as the in-REPL `/permissions` slash. Mode
+ * arg is positional; `--persist` and `--confirm` are zero-arg flags
+ * already consumed by `parseArgs` into `flags.persist` / `flags.confirm`.
+ *
+ * Examples:
+ *   pugi permissions                  -> show current mode + table
+ *   pugi permissions plan             -> flip workspace state to plan
+ *   pugi permissions allow --persist  -> flip + write ~/.pugi/config.json
+ *   pugi permissions bypass --confirm -> flip to bypass (acknowledge banner)
+ */
+async function dispatchPermissions(args, flags, _session) {
+    const head = args[0];
+    if (head && parsePermissionMode(head) === null) {
+        writeOutput(flags, { error: 'unknown_mode', mode: head }, `Unknown mode '${head}'. Allowed: plan, ask, allow, bypass.`);
+        process.exitCode = 1;
+        return;
+    }
+    const mode = head ? parsePermissionMode(head) : undefined;
+    await runPermissionsCommand({
+        ...(mode ? { mode } : {}),
+        persist: Boolean(flags.persist),
+        confirmBypass: Boolean(flags.confirm),
+    }, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (text) => writeOutput(flags, { text }, text),
+    });
+}
+/**
+ * L19 sprint (2026-05-27): `pugi cost` / `pugi usage` top-level surface.
+ *
+ * Aliased through the handlers table so `pugi usage` reuses the same
+ * implementation. The persisted store lives at `<cwd>/.pugi/cost.json`
+ * and is shared with the REPL `/cost` / `/usage` slash handlers.
+ */
+async function dispatchCost(args, flags, _session) {
+    await runCostCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
 async function dispatchSkills(args, flags, _session) {
     await runSkillsCommand(args, {
         workspaceRoot: process.cwd(),
@@ -328,22 +501,46 @@ async function dispatchWeb(args, flags, _session) {
  */
 async function dispatchLsp(args, flags, _session) {
     const result = await runLspCommand(args, { cwd: process.cwd(), json: flags.json });
-    if (flags.json)
-        console.log(result.text);
-    else
-        console.log(result.text);
+    console.log(result.text);
     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
  * (see `src/core/edits/security-gate.ts`). Exit codes mirror the
  * security taxonomy so CI loops can alert on hostile patches without
  * confusing them with operator typos.
+ *
+ * R1 fix (2026-05-26, PR #413 r1): pass `flags.dryRun` through so the
+ * top-level parser's consumption of `--dry-run` does not silently
+ * disable dry-run mode on `pugi patch --dry-run < diff.patch`.
  */
 async function dispatchPatch(args, flags, _session) {
-    const result = await runPatchCommand(args, { cwd: process.cwd(), json: flags.json });
+    const result = await runPatchCommand(args, {
+        cwd: process.cwd(),
+        json: flags.json,
+        dryRun: flags.dryRun,
+    });
     console.log(result.text);
     if (result.exitCode !== 0)
         process.exitCode = result.exitCode;
@@ -353,15 +550,54 @@ async function dispatchPatch(args, flags, _session) {
  * The `pugi build` and `pugi review --consensus` paths use the same
  * primitives internally (`createWorktree` / `promoteWorktree`); this
  * surface is the operator escape hatch for debug + experiment flows.
+ *
+ * R1 fix (2026-05-26, PR #413 r1): forward `flags.dryRun` so the
+ * top-level parser's consumption of `--dry-run` does not silently
+ * disable dry-run mode on `pugi worktree promote --dry-run <path>`.
  */
 async function dispatchWorktree(args, flags, _session) {
-    const result = await runWorktreeCommand(args, { cwd: process.cwd(), json: flags.json });
+    const result = await runWorktreeCommand(args, {
+        cwd: process.cwd(),
+        json: flags.json,
+        dryRun: flags.dryRun,
+    });
     console.log(result.text);
     if (result.exitCode !== 0)
         process.exitCode = result.exitCode;
 }
 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
@@ -436,6 +672,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
@@ -445,11 +682,21 @@ function parseArgs(argv) {
         // "Mira: ..." prose, never "Read(path)" prefix) OR fires falsely on
         // accidental `Verb(noun)` shapes producing stuck `running` rows.
         // Hide by default; opt-in via `--tool-stream` OR PUGI_TOOL_STREAM=1
-        // for development/testing. Will flip к default ON when backend
+        // for development/testing. Will flip to default ON when backend
         // emits real tool events (filed as α6.13.X follow-up).
         noToolStream: process.env.PUGI_TOOL_STREAM === '1' || process.env.PUGI_HIDE_TOOL_STREAM === '1'
             ? process.env.PUGI_HIDE_TOOL_STREAM === '1'
             : 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,
+        // Leak L6 — `pugi permissions <mode> --persist/--confirm`. Default
+        // false so existing invocations stay no-op on the new permission
+        // surface.
+        persist: false,
+        confirm: false,
     };
     const args = [];
     // Sprint 2E: `pugi --version` / `-v` are universal install-test conventions
@@ -482,7 +729,7 @@ function parseArgs(argv) {
         else if (arg === '--consensus') {
             // α6.7: customer-facing 3-model consensus review. Routes through
             // the SSE-based runtime gate rather than the legacy artifact
-            // writer. The triple flag stays unset так the existing
+            // writer. The triple flag stays unset so the existing
             // performRemoteTripleReview path is never accidentally entered.
             flags.consensus = true;
         }
@@ -495,6 +742,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;
         }
@@ -505,10 +758,21 @@ function parseArgs(argv) {
             flags.noToolStream = true;
         }
         else if (arg === '--tool-stream') {
-            // Opt-in для α6.12 dev/testing — backend tool events not live yet,
-            // pane shows синтесайз heuristic OR empty placeholder
+            // Opt-in for α6.12 dev/testing — backend tool events not live yet,
+            // pane shows synthesized heuristic OR empty placeholder
             flags.noToolStream = false;
         }
+        else if (arg === '--no-defaults') {
+            // Init-only flag: skip the bundled default-skills install. Parsed
+            // at the global level for consistency with --no-splash / --no-tool-stream.
+            flags.noDefaults = true;
+        }
+        else if (arg === '--decompose') {
+            // α6.8 EXTEND PR1: plan-only flag. Other engine commands ignore
+            // it. Parsed globally for symmetry with the rest of the flag
+            // grammar; `runEngineTask('plan')` is the single consumer.
+            flags.decompose = true;
+        }
         else if (arg.startsWith('--privacy=')) {
             flags.privacy = parsePrivacyMode(arg.slice('--privacy='.length));
         }
@@ -519,18 +783,180 @@ 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 if (arg.startsWith('--mode=')) {
+            // Leak L6: top-level `--mode plan|ask|allow|bypass`. Validation
+            // happens at the consumer side (parsePermissionMode) so the
+            // parser stays string-typed; an invalid value surfaces a clean
+            // error in the dispatcher rather than blowing up here.
+            flags.mode = arg.slice('--mode='.length);
+        }
+        else if (arg === '--mode') {
+            const next = argv[index + 1];
+            if (!next || next.startsWith('--')) {
+                throw new Error('--mode requires plan|ask|allow|bypass');
+            }
+            flags.mode = next;
+            index += 1;
+        }
+        else if (arg === '--persist') {
+            // Leak L6: paired with `pugi permissions <mode>` to also write
+            // the mode to ~/.pugi/config.json::defaultPermissionMode.
+            flags.persist = true;
+        }
+        else if (arg === '--confirm') {
+            // Leak L6: required for `pugi permissions bypass` (bypass
+            // disables policy hooks; the gate refuses the flip without
+            // acknowledgement).
+            flags.confirm = true;
+        }
         else {
             args.push(arg);
         }
     }
     const isBareInvocation = args.length === 0;
+    const command = args.shift() ?? 'help';
+    // Sprint α6.X CEO dogfood 2026-05-26 (P0 hot-fix): trailing `--help`
+    // / `-h` on ANY sub-command must route to the help printer rather
+    // than dispatching the real engine. Before this guard `pugi build
+    // --help` burned 86k tokens running the actual build loop because
+    // the dispatcher saw `--help` as an opaque arg and forwarded it
+    // through to the engine. Re-routing here means `pugi <cmd> --help`
+    // becomes `pugi help <cmd>` deterministically across the entire
+    // command tree.
+    //
+    // β1 Tt3 carve-out: commands that ship their OWN `--help` block
+    // (login, init, ...) must keep `--help` in their args so the
+    // command-local printer fires. Without this carve-out
+    // `pugi login --help` produces the global help and the per-variant
+    // reference (`--provider device|token|env`) gets lost. The carve-out
+    // list mirrors handlers whose source carries an
+    // `args.includes('--help')` short-circuit.
+    if ((args.includes('--help') || args.includes('-h')) && !COMMAND_LOCAL_HELP.has(command)) {
+        return { command: 'help', args: [command], flags, isBareInvocation: false };
+    }
     return {
-        command: args.shift() ?? 'help',
+        command,
         args,
         flags,
         isBareInvocation,
     };
 }
+/**
+ * β1 Tt3: commands that own their `--help` rendering. The bare-help
+ * redirect leaves their `--help` arg in place so the command-local
+ * printer fires instead of the global summary.
+ */
+const COMMAND_LOCAL_HELP = new Set([
+    'login',
+]);
 async function version(_args, flags, _session) {
     const payload = {
         name: 'pugi',
@@ -538,7 +964,220 @@ async function version(_args, flags, _session) {
     };
     writeOutput(flags, payload, `pugi ${payload.version}`);
 }
-async function help(_args, flags, _session) {
+/**
+ * Per-command help bodies (task #100). When the operator types
+ * `pugi <cmd> --help` the dispatcher routes here with `args = [cmd]`.
+ * If we have a focused body for that command, print it instead of the
+ * global summary. Falls back to the global summary so unknown / new
+ * commands still get a useful response.
+ *
+ * Source of truth for each entry: the comment block at the top of the
+ * command's implementation module + any flags the command declares.
+ * Keep entries short — operators want the one-liner of intent + the
+ * 2-5 most useful flags, not a tutorial. The global help still has the
+ * full per-section reference; the per-command body is the "tell me
+ * how to use this NOW" surface.
+ */
+const COMMAND_HELP_BODIES = {
+    init: [
+        'pugi init — bootstrap a new Pugi workspace in the current directory.',
+        '',
+        'Creates .pugi/{PUGI.md, mcp.json, index.json, artifacts/, sessions/} and',
+        'seeds the 6 default skills. Idempotent — running again only fills gaps.',
+        '',
+        'Flags:',
+        '  --no-defaults     Skip the bundled default-skills install.',
+        '',
+        'Env:',
+        '  PUGI_INIT_NO_DEFAULTS=1   Same as --no-defaults.',
+    ],
+    explain: [
+        'pugi explain "<question>" — read-only Q&A about the workspace.',
+        '',
+        'Calls the engine loop in explain mode (budget: 5 calls / 20k tokens).',
+        'No file writes; safe to run against unfamiliar code.',
+        '',
+        'Examples:',
+        '  pugi explain "what does this package.json define?"',
+        '  pugi explain "trace the auth flow in src/auth/"',
+    ],
+    code: [
+        'pugi code "<brief>" — engineering-mode write loop (30k token budget).',
+        '',
+        'Writes files in the current workspace. Use --no-tty in CI / pipes.',
+    ],
+    fix: [
+        'pugi fix "<brief>" — minimal-diff bugfix loop (30k token budget).',
+        '',
+        'Same as `pugi code` but the prompt biases toward the smallest patch',
+        'that closes the brief — refuses scope creep / refactor invitations.',
+    ],
+    build: [
+        'pugi build "<brief>" — feature-build loop (200k token budget).',
+        '',
+        'Multi-turn engineering with plan-review checkpoints. Pairs with',
+        'pugi plan --decompose <idea> when the brief is bigger than one PR.',
+    ],
+    plan: [
+        'pugi plan --decompose <idea> — split an idea into 3-7 components.',
+        '',
+        'Writes .pugi/plan/<session-id>/splits/NN-<name>/spec.md plus',
+        'manifest.md with the dependency DAG. Pass each split to `pugi build`.',
+    ],
+    review: [
+        'pugi review — code review surfaces.',
+        '',
+        '  --triple                3-model consensus via Anvil paid fleet.',
+        '  --triple --commit <SHA> Review a specific commit (vs origin/main).',
+        '  --consensus             Customer-facing consensus review (codex + claude + deepseek).',
+        '                          Optional: --commit <sha> | --pr <num> | --branch <name>.',
+        '',
+        'Exit codes: 0 PASS · 1 WARN · 2 BLOCK · 5 auth_missing · 7 rate_limited.',
+    ],
+    privacy: [
+        'pugi privacy — privacy-mode operations.',
+        '',
+        '  show                    Display effective mode + source.',
+        '  set <mode>              Local-only legacy values (local-only|metadata|full).',
+        '',
+        'For tenant-scoped server-side modes (strict|balanced|permissive), use:',
+        '  pugi config get privacy',
+        '  pugi config set privacy=<mode>',
+    ],
+    cost: [
+        'pugi cost — token + USD breakdown for the current Pugi session.',
+        '',
+        'Reads .pugi/cost.json (persisted via the in-REPL CostTracker) and',
+        'prints a per-model table plus dollar estimate. Alias: pugi usage.',
+        '',
+        'Flags:',
+        '  --all-sessions          30-day rolling aggregate across all sessions.',
+        '  --window=<days>         Override the aggregate window (max 365).',
+        '  --reset --yes           Clear the current-session counter. History',
+        '                          is preserved. Requires --yes to confirm.',
+        '  --json                  Emit a structured JSON envelope only.',
+        '',
+        'Examples:',
+        '  pugi cost                       Current session totals.',
+        '  pugi cost --all-sessions        Past 30 days aggregated.',
+        '  pugi cost --all-sessions --window=7',
+        '  pugi cost --reset --yes         Wipe the session counter.',
+        '  pugi usage                      Alias for pugi cost.',
+    ],
+    config: [
+        'pugi config — read / write CLI + tenant configuration.',
+        '',
+        '  get <key>                                       Local config value.',
+        '  get privacy                                     Tenant privacy snapshot (admin-api).',
+        '  get routing                                     Effective routing table.',
+        '  set <key>=<value>                               Local config write.',
+        '  set privacy=<mode>                              Flip tenant privacy (strict|balanced|permissive).',
+        '  set routing.<tag>.<budget>=<model>              Override one routing lane.',
+        '  unset routing.<tag>.<budget>                    Revert a routing override.',
+        '  mcp trust|deny|list <name>                      MCP server trust + visibility.',
+    ],
+    sync: [
+        'pugi sync — explicit-continuation handoff bundle upload.',
+        '',
+        '  --dry-run               Print the bundle plan without uploading.',
+        '  --privacy <mode>        Override per-bundle privacy posture.',
+    ],
+    whoami: [
+        'pugi whoami — show the active credential + JWT principal + plan tier.',
+        '',
+        'Reads from ~/.pugi/credentials.json. No network call unless --remote.',
+    ],
+    login: [
+        'pugi login — authenticate against an api.pugi.io endpoint.',
+        '',
+        'Interactive picker by default (browser OAuth / PAT / env). Non-interactive:',
+        '  --provider device                                Device-flow OAuth.',
+        '  --provider token --token <jwt>                   Pass a JWT directly.',
+        '  --provider env --env PUGI_API_KEY                Read from an env var.',
+    ],
+    accounts: [
+        'pugi accounts — manage stored credentials across endpoints.',
+        '',
+        '  list                    Every account + its endpoint + active flag.',
+        '  switch <label>          Re-point the active account.',
+        '  remove <label>          Delete a stored credential.',
+    ],
+    jobs: [
+        'pugi jobs — list, tail, or kill background dispatch jobs.',
+        '',
+        '  list                    All jobs in the registry.',
+        '  tail <id>               Stream output from one job.',
+        '  kill <id>               Cancel a running job.',
+    ],
+    delegate: [
+        'pugi delegate <slug> "<brief>" — dispatch a brief to one specialist persona.',
+        '',
+        'Slugs (Tier 1 alpha 7.5): dev qa pm devops researcher analyst designer',
+        'frontend architect. `pugi roster` lists the live set.',
+    ],
+    roster: [
+        'pugi roster — list the live Tier 1 personas + roles.',
+    ],
+    doctor: [
+        'pugi doctor — diagnose CLI + workspace + adapter capabilities.',
+        '',
+        'Prints CLI version, Node version, workspace state (.pugi presence,',
+        'event log, settings), permission mode, and the capability matrix per',
+        'engine adapter. Safe to run anywhere; no network calls.',
+    ],
+    status: [
+        'pugi status — concise session snapshot.',
+        '',
+        'Different from `pugi doctor` (environment health). Status answers',
+        '"what is this Pugi session doing right now?" — session id + age,',
+        'cwd, permission mode, CLI version, token usage, active + completed',
+        'dispatches, last command, compact boundary count, auth identity.',
+        '',
+        '  --json                  Emit a structured envelope to stdout.',
+        '',
+        'Live REPL state (tokens, last command) is only available via the',
+        'in-REPL `/status` slash; the shell path degrades those fields к',
+        '"n/a" and exits 0.',
+    ],
+    report: [
+        'pugi report — capture a bug report from the most-recent session.',
+        '',
+        '  --from-error            Bundle the most-recent failed session as a',
+        '                          redacted local report (default + only mode in v1).',
+        '',
+        'Output: writes .pugi/reports/<timestamp>-<session-id>/{report.json, report.md}.',
+        'Secrets (bearer tokens, JWTs, named env values) are stripped before disk write.',
+        'Auto-upload to api.pugi.io planned for a follow-up; v1 keeps everything local.',
+    ],
+    ask: [
+        'pugi ask "<question>" — surface a yes/no question modal locally.',
+        '',
+        'Useful in shell scripts that need a human-confirm before a destructive',
+        'step. Exits 0 on yes, 1 on no, 2 on cancel.',
+    ],
+    deploy: [
+        'pugi deploy — trigger a vendor deployment from the bound Git source.',
+        '',
+        '  --target vercel <vercelProject> --project <id>   Vercel deploy.',
+        '  --target render <renderService> --project <id>   Render deploy (Sprint 2 stub).',
+        '  --status <id>                                    Vendor-agnostic status snapshot.',
+        '  --logs <id> [--tail]                             Build-log tail.',
+        '',
+        'Optional: --target-env production|preview, --ref <ref>, --integration <id>.',
+    ],
+};
+async function help(args, flags, _session) {
+    // 2026-05-27 task #100: per-command help bodies. When dispatcher
+    // routed `pugi <cmd> --help` here it passes `args = [cmd]`; if we
+    // have a focused body, print that. Falls through to the global
+    // summary on unknown / new commands so the dispatcher's redirect
+    // never produces a worse-than-baseline response.
+    const requested = args[0];
+    if (requested && COMMAND_HELP_BODIES[requested]) {
+        const body = COMMAND_HELP_BODIES[requested];
+        writeOutput(flags, { command: requested, lines: body }, body.join('\n'));
+        return;
+    }
     const commands = Object.keys(handlers).sort();
     writeOutput(flags, { commands }, [
         'Pugi CLI',
@@ -558,6 +1197,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.',
@@ -573,6 +1215,15 @@ async function help(_args, flags, _session) {
         '  pugi ask "<question>"          Surface a yes/no question modal locally.',
         '  pugi plan-review <task>        Generate + present a plan-review modal.',
         '',
+        'Persona dispatch (α7.5):',
+        '  pugi roster                              List the live Tier 1 personas + roles.',
+        '  pugi delegate <slug> "<brief>"           Dispatch a brief to one specialist.',
+        '',
+        'Plan decomposition (α6.8):',
+        '  pugi plan --decompose <idea>   Split a high-level idea into 3-7 components.',
+        '                                 Writes .pugi/plan/<session-id>/splits/NN-<name>/spec.md',
+        '                                 plus manifest.md with the dependency DAG.',
+        '',
         'Deploy:',
         '  pugi deploy --target vercel <vercelProject> --project <id>',
         '                          Trigger a Vercel deployment from the bound Git source.',
@@ -595,75 +1246,83 @@ async function help(_args, flags, _session) {
         '                          PUGI_SKIP_SPLASH=1.',
         '  --no-tool-stream        Hide the live tool stream pane (α6.12).',
         '                          Pairs with PUGI_HIDE_TOOL_STREAM=1.',
+        '  --no-defaults           Skip bundled default-skills install on',
+        '                          `pugi init`. Pairs with PUGI_INIT_NO_DEFAULTS=1.',
         '',
         PUGI_TAGLINE,
         'Execution defaults to local. Use --remote or --web to create a handoff bundle.',
     ].join('\n'));
 }
+/**
+ * `pugi doctor` — Leak L17 (2026-05-27). Delegates to the diagnostics
+ * probe runner in `runtime/commands/doctor.ts`. The handler stays
+ * thin so the probe surface stays single-sourced between the CLI
+ * shell command, the `pnpm run doctor --json` package script, and
+ * the in-REPL `/doctor` slash command.
+ *
+ * Exit codes are set by `runDoctorCommand` (0 = healthy/warnings,
+ * 2 = at least one error probe). The pre-L17 minimal doctor surface
+ * (adapter capabilities + schema bundle hash) is preserved under
+ * `payload.meta.legacy` so any operator scripts that grep the JSON
+ * keep working through the transition; the field is marked for
+ * removal in a follow-up sprint once the new shape is the
+ * documented contract.
+ */
 async function doctor(_args, flags, _session) {
-    const cwd = process.cwd();
-    const settings = loadSettings(cwd);
-    // `doctor` reports adapter capabilities only; we pass a no-op client
-    // so we do not require an Anvil endpoint to run `pugi doctor`. The
-    // adapter never invokes `client.send()` from inside `capabilities()`.
-    const inertClient = {
-        async send() {
-            return {
-                stop: 'error',
-                code: 'failed',
-                message: 'doctor: inert client',
-            };
-        },
-    };
-    const adapters = [
-        new NoopEngineAdapter(),
-        new NativePugiEngineAdapter({ client: inertClient }),
-    ];
-    const capabilities = await Promise.all(adapters.map(async (adapter) => ({
-        name: adapter.name,
-        capabilities: await adapter.capabilities(),
-    })));
-    const payload = {
-        cliVersion: PUGI_CLI_VERSION,
-        nodeVersion: process.version,
-        workspaceRoot: cwd,
-        pugiMode: existsSync(resolve(cwd, 'CLAUDE.md')),
-        pugiDir: existsSync(resolve(cwd, '.pugi')),
-        eventLog: existsSync(resolve(cwd, '.pugi/events.jsonl')),
-        permissionMode: settings.permissions.mode,
-        approvals: settings.workflow.approvals,
-        notAutomatic: [...settings.workflow.notAutomatic, ...settings.permissions.notAutomatic],
-        protectedFileCheck: decidePermission({ tool: 'doctor', kind: 'edit', target: '.env' }, settings, cwd),
-        protectedFileSafety: 'configured-in-m1',
-        mcpTrust: 'not-configured',
-        releaseGuard: 'scaffolded',
-        tools: toolRegistry,
-        engineAdapters: capabilities,
-        schemaBundleHash: createHash('sha256')
-            .update(toolSchemaBundleHashInput())
-            .digest('hex'),
-    };
-    writeOutput(flags, payload, [
-        'Pugi doctor',
-        `CLI: ${payload.cliVersion}`,
-        `Node: ${payload.nodeVersion}`,
-        `Workspace: ${payload.workspaceRoot}`,
-        `Pugi mode: ${payload.pugiMode ? 'detected' : 'not detected'}`,
-        `Pugi dir: ${payload.pugiDir ? 'present' : 'missing'}`,
-        `Event log: ${payload.eventLog ? 'present' : 'missing'}`,
-        `Permission mode: ${payload.permissionMode}`,
-        `Approvals: ${payload.approvals}`,
-        `Release guard: ${payload.releaseGuard}`,
-    ].join('\n'));
+    await runDoctorCommand({
+        cwd: process.cwd(),
+        home: defaultDoctorHome(),
+        env: process.env,
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
 }
-async function init(_args, flags, _session) {
-    const cwd = process.cwd();
+/**
+ * `pugi status` — Leak L34 (2026-05-27). Concise session-state probe
+ * mirroring Claude Code's `/status`. Distinct from `pugi doctor`
+ * (environment health) — `status` answers "what is THIS Pugi
+ * session doing right now?" with session id + age, cwd, permission
+ * mode, CLI version, token usage, dispatch count, last command,
+ * compact boundaries, and auth identity.
+ *
+ * The top-level shell invocation has no live REPL state — fields
+ * that need a live session (`tokens`, `lastCommand`) degrade к the
+ * `n/a` sentinel. The same handler powers the in-REPL `/status`
+ * slash, which passes live state through `StatusCommandContext`.
+ *
+ * Always exits 0 — the command is informational, never a gate.
+ */
+async function status(_args, flags, _session) {
+    await runStatusCommand({
+        cwd: process.cwd(),
+        home: defaultStatusHome(),
+        env: process.env,
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
+/**
+ * Programmatic init scaffolder. Idempotent — every helper call is a
+ * `*_IfMissing` write, so re-running over an existing .pugi/ workspace
+ * adds nothing to `created` and the operator sees the "Already
+ * initialized" copy. Default skills install is best-effort: failure
+ * does not throw, the error is appended to the result via stderr so
+ * the slash dispatcher can surface it in the REPL system pane.
+ *
+ * Callers MUST provide `cwd` explicitly; the function does not read
+ * `process.cwd()` so REPL invocations from an arbitrary workspace
+ * cannot accidentally scaffold the binary's install directory.
+ */
+export async function scaffoldPugiWorkspace(input) {
+    const cwd = input.cwd;
+    const log = input.log ?? ((line) => process.stderr.write(line));
     const pugiDir = resolve(cwd, '.pugi');
     const created = [];
     const skipped = [];
     ensureDir(pugiDir, created, skipped);
     ensureDir(resolve(pugiDir, 'artifacts'), created, skipped);
     ensureDir(resolve(pugiDir, 'sessions'), created, skipped);
+    ensureDir(resolve(pugiDir, 'skills'), created, skipped);
     writeJsonIfMissing(resolve(pugiDir, 'settings.json'), {
         schema: 1,
         workflow: {
@@ -685,6 +1344,9 @@ async function init(_args, flags, _session) {
             mode: 'balanced',
             telemetry: 'off',
         },
+        ui: {
+            cyberZoo: 'on',
+        },
         artifacts: {
             defaultPath: '.pugi/artifacts',
             promoteExplicitly: true,
@@ -692,7 +1354,19 @@ async function init(_args, flags, _session) {
     }, 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'), [
@@ -733,17 +1407,67 @@ async function init(_args, flags, _session) {
     // Ensure `.pugi/` is git-ignored so users do not accidentally commit
     // local audit logs, artifacts, or triple-review request payloads.
     ensurePugiGitIgnore(cwd, created, skipped);
-    const payload = {
+    // Bundled default skills (brand-voice, endpoint-probe, readme-sync).
+    // Skipped when --no-defaults is passed OR when PUGI_INIT_NO_DEFAULTS=1.
+    // Idempotent: a skill whose target directory already exists is left
+    // alone so re-running `pugi init` after the operator customised one of
+    // the defaults does not clobber their edits.
+    let defaultSkills = [];
+    if (!input.noDefaults) {
+        try {
+            defaultSkills = await installDefaultSkills({
+                workspaceRoot: cwd,
+                log,
+            });
+        }
+        catch (error) {
+            // Default-skills install is a convenience layer. A failure here
+            // (bad sha256 hashing, permission error on .pugi/skills/) must not
+            // leave `pugi init` in a half-state where settings.json exists but
+            // the operator sees an unexplained crash. Log the error to stderr
+            // and continue — the operator can still install skills manually.
+            const message = error instanceof Error ? error.message : String(error);
+            log(`[pugi init] default-skills install failed: ${message}\n`);
+        }
+    }
+    return {
         status: 'initialized',
         root: cwd,
         created,
         skipped,
+        defaultSkills,
+        alreadyInitialized: created.length === 0,
     };
-    writeOutput(flags, payload, [
+}
+/**
+ * Standalone `pugi init` CLI entry. Thin wrapper around
+ * `scaffoldPugiWorkspace` that handles flag plumbing + writeOutput
+ * formatting. β1a r1: extracted from the previous inline init so the
+ * REPL's `/init` slash can call `scaffoldPugiWorkspace` directly.
+ */
+async function init(_args, flags, _session) {
+    const result = await scaffoldPugiWorkspace({
+        cwd: process.cwd(),
+        noDefaults: flags.noDefaults,
+    });
+    const defaultSkillLines = flags.noDefaults
+        ? ['Default skills: skipped (--no-defaults)']
+        : result.defaultSkills.length === 0
+            ? ['Default skills: none installed']
+            : [
+                'Default skills:',
+                ...result.defaultSkills.map((entry) => `  ${entry.name.padEnd(18)} ${entry.status}`),
+            ];
+    writeOutput(flags, result, [
         'Pugi initialized',
-        `Root: ${cwd}`,
-        created.length ? `Created:\n${created.map((path) => `  ${path}`).join('\n')}` : 'Created: none',
-        skipped.length ? `Already present:\n${skipped.map((path) => `  ${path}`).join('\n')}` : 'Already present: none',
+        `Root: ${result.root}`,
+        result.created.length
+            ? `Created:\n${result.created.map((path) => `  ${path}`).join('\n')}`
+            : 'Created: none',
+        result.skipped.length
+            ? `Already present:\n${result.skipped.map((path) => `  ${path}`).join('\n')}`
+            : 'Already present: none',
+        ...defaultSkillLines,
     ].join('\n'));
 }
 async function idea(args, flags, session) {
@@ -1064,10 +1788,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);
@@ -1079,6 +1813,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;
@@ -1516,6 +2259,307 @@ 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;
+    // merge-base is intentionally a PROBE: an empty result is a valid
+    // signal (orphan branch, shallow clone, moved tag) that the dispatch
+    // path handles by falling back к range-notation. Use the legacy
+    // `safeGit` (probe semantics) explicitly rather than the strict
+    // variant.
+    const mergeBase = safeGitProbe(root, ['merge-base', baseRef, commitRef]).trim() || '';
+    // 2026-05-27 (Claude review followup #489): when merge-base returns empty
+    // (orphan branch, shallow clone, moved tag), we MUST NOT pass the
+    // `<range> <commitRef>` two-arg form to `git diff` — that combo is
+    // invalid syntax, git exits 129, `safeGit` swallows the error, and the
+    // diff payload ships empty. An empty diff is then classified as
+    // `'code'` server-side, dispatched to reviewers who emit a trivial
+    // `VERDICT: PASS` over zero lines — a SILENT GREEN REVIEW on a commit
+    // nobody actually examined. Branch on `mergeBase` так что:
+    //   - mergeBase present  → `git diff <mergeBase> <commitRef> --`
+    //     (both endpoints explicit, only-uncommitted-against-base ignored
+    //     because commitRef is a SHA, not HEAD).
+    //   - mergeBase empty    → `git diff <baseRef>..<commitRef> --`
+    //     (range form encodes both endpoints; do NOT append commitRef
+    //     again or git rejects the args).
+    const diffRange = mergeBase || `${baseRef}..${commitRef}`;
+    const diffArgs = mergeBase
+        ? ['diff', mergeBase, commitRef, '--', '.', ...PROTECTED_DIFF_EXCLUDES]
+        : ['diff', diffRange, '--', '.', ...PROTECTED_DIFF_EXCLUDES];
+    const diffStatArgs = mergeBase
+        ? ['diff', '--shortstat', mergeBase, commitRef, '--', '.', ...PROTECTED_DIFF_EXCLUDES]
+        : ['diff', '--shortstat', diffRange, '--', '.', ...PROTECTED_DIFF_EXCLUDES];
+    // Use the strict variant — a non-empty diffPatch is load-bearing for
+    // the review gate. If git fails for ANY reason (bad ref, ENOBUFS, FS
+    // permission), we'd rather surface a hard error than ship a green
+    // review on nothing. The `--shortstat` companion uses the same
+    // helper so the throw is symmetric.
+    const diffPatch = safeGitRequired(root, diffArgs, 'triple-providers diff');
+    const diffStats = parseDiffStats(safeGitRequired(root, diffStatArgs, 'triple-providers diff --shortstat'));
+    if (diffPatch.trim() === '') {
+        throw new Error(`pugi review --triple: empty diff between '${baseRef}' and '${commitRef}'. ` +
+            `Refusing to dispatch a review for zero changes — check the refs ` +
+            `or commit your changes before running.`);
+    }
+    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':
@@ -2075,6 +3119,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);
@@ -2088,6 +3159,26 @@ function runEngineTask(kind) {
         const config = credential
             ? buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey })
             : envConfig;
+        // α6.8 EXTEND PR1 v2: `--decompose` gating runs BEFORE the offline
+        // fallback. Two reasons:
+        //   1. The flag is plan-only — surfacing the rejection for
+        //      `pugi build --decompose` before we drop into `offlineBuild`
+        //      means the operator gets a deterministic error instead of a
+        //      silent no-op stub.
+        //   2. The decompose post-processor depends on the engine's final
+        //      text. The offline plan stub does not invoke the engine, so
+        //      `pugi plan --decompose --offline` would silently skip the
+        //      decomposition step. Refusing the combination up front is the
+        //      cheapest way to keep the contract honest.
+        if (flags.decompose && kind !== 'plan') {
+            throw new Error(`--decompose is only valid for \`pugi plan\` (got \`pugi ${label}\`)`);
+        }
+        if (flags.decompose && flags.offline) {
+            throw new Error('--decompose requires the engine — drop --offline (decomposition needs the model to emit a fenced JSON block)');
+        }
+        if (flags.decompose && !config) {
+            throw new Error('--decompose requires the engine — run `pugi login` or set PUGI_API_KEY (decomposition needs the model to emit a fenced JSON block)');
+        }
         // Offline fallback: preserves the local-first invariant. `plan` /
         // `build` / `explain` drop back to their pre-Sprint-2 stub
         // behaviour so an operator without an API key (or with --offline)
@@ -2140,214 +3231,388 @@ function runEngineTask(kind) {
                 throw new Error(`pugi ${label} requires a prompt`);
             }
         }
+        // α6.8 EXTEND PR1: when `--decompose` is set, augment the user
+        // prompt with the decomposition-request suffix BEFORE the adapter
+        // run. The system prompt for `plan` already constrains the model
+        // to read-only tools + a plan deliverable; the suffix layers the
+        // JSON-emission contract on top so the post-run parser can lift
+        // the structured payload out of the final answer. The plan-only /
+        // engine-required gates fired before the offline fallback above,
+        // so by here we know we are on the engine path with a plan task.
+        if (flags.decompose && kind === 'plan') {
+            prompt = `${prompt}\n${DECOMPOSE_PROMPT_SUFFIX}`;
+        }
         // Narrow `config` for the type checker — the offline branches above
         // return whenever `config` is null, so by this point it must be set.
         if (!config) {
             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,
-            });
-        }
-        // 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;
+            // 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,
+                });
             }
-            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;
+            // α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 };
+                }
             }
-        }
-        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,
-            })),
-            // 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}`);
-        }
-        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)`);
+            // 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 {
-                    textLines.push(`  ! ${dr.layer} ${dr.file}: ${dr.reason ?? 'failure'} — ${dr.detail ?? ''}`);
+                    // `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 {
+                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 ?? ''}`);
+                    }
                 }
             }
+            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
@@ -3975,7 +5240,31 @@ function fileBytes(path) {
         return 0;
     }
 }
-function safeGit(root, args) {
+/**
+ * Git invocation helpers — probe vs required semantics.
+ *
+ * 2026-05-27 (Claude review followup #489): the historical `safeGit`
+ * collapsed BOTH "tell me the branch name if you can" probes AND
+ * "give me the diff or fail" hard requirements into a single helper
+ * that swallowed every error as an empty string. That's the correct
+ * shape for the probe case (branch / status / dirty flag — empty
+ * result is a valid signal) but catastrophically wrong for the diff
+ * case (empty result === false PASS on a commit nobody reviewed).
+ *
+ * The split:
+ *   - `safeGitProbe`  — best-effort. Returns '' on any error. Use for
+ *     branch name lookups, status probes, opt-in dirty detection.
+ *   - `safeGitRequired` — throws on non-zero exit / ENOBUFS / bad ref.
+ *     Use for diff, merge-base resolution, anything whose empty
+ *     output would silently corrupt downstream behaviour.
+ *
+ * Legacy `safeGit` is kept as a deprecated alias of `safeGitProbe`
+ * so existing call-sites (branch detection, status, etc.) keep their
+ * tolerant semantics until they are individually migrated. Diff /
+ * merge-base / rev-parse-verify call-sites are migrated к
+ * `safeGitRequired` in this same patch.
+ */
+export function safeGitProbe(root, args) {
     try {
         return execFileSync('git', args, {
             cwd: root,
@@ -3993,6 +5282,38 @@ function safeGit(root, args) {
         return '';
     }
 }
+/**
+ * Strict variant — throws on non-zero exit, ENOBUFS, or any git-side
+ * failure. The thrown error carries the operation context so the
+ * caller (triple-review dispatch, etc.) can fail loud rather than
+ * ship an empty diff to a remote reviewer.
+ */
+export function safeGitRequired(root, args, context) {
+    try {
+        return execFileSync('git', args, {
+            cwd: root,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        throw new Error(`git ${args.slice(0, 2).join(' ')} failed (${context}): ${cause}. ` +
+            `Refusing to proceed — empty git output here would corrupt downstream behaviour.`);
+    }
+}
+/**
+ * Deprecated alias preserved for diff / status / branch probes that
+ * legitimately want a tolerant empty-string-on-error shape. New call
+ * sites should pick `safeGitProbe` or `safeGitRequired` explicitly.
+ *
+ * @deprecated 2026-05-27 — prefer `safeGitProbe` (tolerant) or
+ * `safeGitRequired` (strict, throws).
+ */
+function safeGit(root, args) {
+    return safeGitProbe(root, args);
+}
 /**
  * Glob patterns excluded from triple-review `diffPatch` before egress.
  *
@@ -4133,5 +5454,6 @@ export function packageRoot() {
 export const __test__ = {
     sleep,
     pollDeviceFlowUntilTerminal,
+    sanitizeSemver,
 };
 //# sourceMappingURL=cli.js.map