@pugi/cli 0.1.0-beta.3 → 0.1.0-beta.30

package/dist/runtime/cli.js

@@ -1,38 +1,73 @@
-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 { homedir } from 'node:os';
 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 { runDispatchCommand } from './commands/dispatch.js';
 import { clearApiKey, DEFAULT_API_URL, listStoredCredentials, maskApiKey, normalizeApiUrl, purgeAllCredentials, readCredentialsFile, resolveActiveCredential, storeApiKey, switchActiveAccount, } from '../core/credentials.js';
+import { resolveAndValidateEnvLogin, } from '../core/auth/env-provider.js';
 import { runDeployCommand } from '../commands/deploy.js';
 import { runJobsCommand } from '../commands/jobs.js';
 import { runConfigCommand } from './commands/config.js';
+import { runStyleCommand } from './commands/style.js';
+import { runThemeCommand } from './commands/theme.js';
+import { runOnboardingCommand } from './commands/onboarding.js';
+import { runVimCommand } from './commands/vim.js';
+import { isOnboarded } from '../core/onboarding/marker.js';
 import { runPrivacyCommand } from './commands/privacy.js';
+import { runReport } from './commands/report.js';
+import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.js';
+import { parsePrdCheckArgs, runPrdCheckCommand, } from './commands/prd-check.js';
+import { runChainCommand, } from './commands/chain.js';
+import { runStatusCommand, defaultStatusHome, } from './commands/status.js';
+import { runStickersCommand } from './commands/stickers.js';
+import { runRepoMapCommand } from './commands/repo-map.js';
+import { runReleaseNotesCommand, defaultReleaseNotesHome, } from './commands/release-notes.js';
 import { runUndoCommand } from './commands/undo.js';
+import { runCompactCommand } from './commands/compact.js';
+import { runRewindCommand } from './commands/rewind.js';
+import { runSessionsCommand } from './commands/sessions.js';
+// Day 4 ADR-0063: persona-memory operator surface (list / recall / write /
+// forget / sync). The runner is shared by `pugi memory` top-level and the
+// in-REPL `/memory` slash so the two surfaces stay single-sourced.
+import { runMemoryCommand } from './commands/memory.js';
 import { runBudgetCommand } from './commands/budget.js';
+import { BARE_MODE_BANNER, isBareMode, setBareMode, } from '../core/bare-mode/index.js';
+import { runCostCommand } from './commands/cost.js';
+import { runShareCommand } from './commands/share.js';
 import { runSkillsCommand } from './commands/skills.js';
+import { runHooksCommand } from './commands/hooks.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 { runPlanCommand } from './commands/plan.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,18 +82,39 @@ 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.3";
+// 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,
     ask: dispatchAsk,
     build: runEngineTask('build_task'),
     budget: dispatchBudget,
+    // Wave 6 (2026-05-27): `pugi chain` walks the deterministic 7-step
+    // artifact pipeline (PRD → ADR → mindmap → ER → sequence → tests →
+    // code). Subcommands: new / status / next / show / export / list.
+    // Same handler powers the in-REPL `/chain` slash via session.ts.
+    chain: dispatchChain,
     code: runEngineTask('code'),
     config: dispatchConfig,
+    cost: dispatchCost,
+    delegate: dispatchDelegate,
+    // Leak L10 (2026-05-27): `pugi dispatch list-cache-refs` /
+    // `clear-cache-refs` operate on `.pugi/cache-refs/` — the persisted
+    // prompt-cache inheritance handles for fork-subagent dispatches. The
+    // handler module lives in commands/dispatch.ts so the table stays narrow.
+    dispatch: dispatchSubagentCacheRefs,
     deploy: dispatchDeploy,
     doctor,
     explain: runEngineTask('explain'),
+    hooks: dispatchHooks,
     fix: runEngineTask('fix'),
     handoff,
     help,
@@ -68,16 +124,84 @@ const handlers = {
     login,
     logout,
     lsp: dispatchLsp,
+    mcp: dispatchMcp,
+    // ADR-0063 Day 4: `pugi memory list|recall|write|forget|sync`. Routes
+    // to `runMemoryCommand` (admin-api `/api/persona-memory` + offline
+    // queue at `~/.pugi/memory-queue.jsonl`).
+    memory: dispatchMemory,
     patch: dispatchPatch,
-    plan: runEngineTask('plan'),
+    permissions: dispatchPermissions,
+    perms: dispatchPermissions,
+    plan: dispatchPlan,
     'plan-review': dispatchPlanReview,
+    // Wave 6 (2026-05-27): `pugi prd-check` verifies PRD acceptance
+    // criteria against committed code/tests/docs/commands BEFORE an
+    // operator (or autonomous agent) claims a feature done. Same
+    // handler powers the in-REPL `/prd-check` slash via session.ts.
+    'prd-check': dispatchPrdCheck,
     privacy: dispatchPrivacy,
+    // L24 (2026-05-27): `pugi release-notes` shows the bundled CHANGELOG
+    // diff between the operator's last-seen version + installed version.
+    // The slash counterpart `/release-notes` shares this handler via the
+    // shared `runReleaseNotesCommand` runner.
+    'release-notes': releaseNotes,
+    releaseNotes,
+    // 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,
+    share: dispatchShare,
     skills: dispatchSkills,
+    status,
+    stickers,
+    // Leak L28 (2026-05-27): `pugi repo-map` walks the source tree,
+    // extracts top-level function / class / interface / type / enum
+    // declarations + JSDoc summaries, caches the result in
+    // `.pugi/repo-map.json`, and renders the compact markdown listing.
+    // Same builder powers the engine boot-time system-prompt injection
+    // — running the CLI command shows the operator EXACTLY what the
+    // engine would see.
+    'repo-map': dispatchRepoMap,
+    // Leak L21 (2026-05-27): in-CLI feedback collector. Shares the
+    // same handler as the in-REPL `/feedback` slash; the wrapper just
+    // routes TTY vs non-TTY before mounting Ink.
+    feedback: dispatchFeedback,
     sync,
+    style: dispatchStyle,
+    // Leak L30 (2026-05-27): `pugi theme` flips the local TUI color
+    // palette (orthogonal to `pugi style` — that one steers engine
+    // prose register). 4 presets: default / dark / light / colorblind.
+    theme: dispatchTheme,
+    // Leak L25 (2026-05-27): `pugi onboarding` walks the new operator
+    // through auth / mode / style / MCP / telemetry. Idempotent;
+    // `--reset` clears the marker file so the bare-invocation hint
+    // re-arms without nuking persisted defaults.
+    onboarding: dispatchOnboarding,
+    // Leak L26 (2026-05-27): `pugi vim` toggles vim-style modal editing
+    // in the REPL input buffer. Bare invocation toggles, `on`/`off`
+    // sets explicitly; preference persists in ~/.pugi/config.json.
+    vim: dispatchVim,
     undo: dispatchUndo,
+    compact: dispatchCompact,
+    // Leak L9 (2026-05-27): `pugi rewind [N | --to <id>]` rolls the
+    // conversation back to a checkpoint by appending a tombstone marker
+    // to the NDJSON event log. The slash counterpart `/rewind` forwards
+    // to the same runner via session.ts.
+    rewind: dispatchRewind,
+    // 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,
+    // Leak L27 (2026-05-27): `pugi update` — channel-aware npm registry
+    // probe + optional npm install shell-out. Same handler powers the
+    // in-REPL `/update` slash via the session module. R2 atomic swap
+    // deferred to Phase 2 per the sprint plan; npm is the single
+    // distribution channel today.
+    update: dispatchUpdate,
     version,
     web: dispatchWeb,
     whoami,
@@ -252,6 +376,259 @@ async function dispatchPrivacy(args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * ADR-0063 Day 4 — `pugi memory <sub>` top-level dispatcher.
+ *
+ * Forwards to the shared `runMemoryCommand` runner. Exit codes:
+ *
+ *   - 0 — happy paths (listed / recalled / written / forgot / synced /
+ *         queued_offline / sync_noop / sync_partial)
+ *   - 1 — unauthenticated / feature_disabled / unknown_sub
+ *   - 2 — invalid_args
+ *
+ * `forget_not_found` exits 0 because the operator-visible behaviour
+ * (the memory is gone) matches their intent; the JSON envelope still
+ * carries the `forget_not_found` status flag for scripted callers.
+ */
+async function dispatchMemory(args, flags, _session) {
+    const result = await runMemoryCommand(args, {
+        workspaceRoot: process.cwd(),
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    switch (result.status) {
+        case 'unauthenticated':
+        case 'feature_disabled':
+        case 'unknown_sub':
+            process.exitCode = 1;
+            return;
+        case 'invalid_args':
+            process.exitCode = 2;
+            return;
+        default:
+            // 'listed' | 'recalled' | 'written' | 'queued_offline' | 'forgot' |
+            // 'forget_not_found' | 'synced' | 'sync_partial' | 'sync_noop' — exit 0.
+            return;
+    }
+}
+/**
+ * Leak L18 (2026-05-27) — `pugi style` top-level dispatcher.
+ *
+ * Forwards to the shared `runStyleCommand` runner. The REPL `/style`
+ * slash uses the same runner via a dynamic import inside
+ * `core/repl/session.ts` so the two surfaces stay single-sourced.
+ *
+ * Exit-code policy:
+ *   - 0 — show / switch / reset / list happy paths
+ *   - 1 — unknown preset slug
+ *   - 2 — conflicting flags (`--reset` + positional / `--reset --persist`)
+ *
+ * The runner returns the code; we attach it to `process.exitCode` so
+ * subsequent dispatch wrappers do not clobber it on success.
+ */
+async function dispatchStyle(args, flags, _session) {
+    const rc = await runStyleCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
+/**
+ * Leak L30 (2026-05-27) — `pugi theme` top-level dispatcher.
+ *
+ * Forwards to the shared `runThemeCommand` runner. The REPL `/theme`
+ * slash uses the same runner via a dynamic import inside
+ * `core/repl/session.ts` so the two surfaces stay single-sourced.
+ *
+ * Exit-code policy mirrors `dispatchStyle`:
+ *   - 0 — show / switch / reset / list happy paths
+ *   - 1 — unknown preset slug
+ *   - 2 — conflicting flags (`--reset` + positional / `--reset --persist`)
+ *
+ * The runner returns the code; we attach it to `process.exitCode` so
+ * subsequent dispatch wrappers do not clobber it on success.
+ */
+/**
+ * Leak L12 (2026-05-27) — `pugi hooks` top-level dispatcher (MVP).
+ *
+ * Two subcommands:
+ *   - `pugi hooks list`   — show configured hooks per event.
+ *   - `pugi hooks doctor` — validate `~/.pugi/hooks-mvp.json`.
+ *
+ * MVP scope: 2 events of 8 (SessionStart + PreToolUse). Remaining 6
+ * events (PostToolUse, UserPromptSubmit, Stop, SubagentStop,
+ * PreCompact, Notification) deferred to fast-follow PR. The runner
+ * pattern established here is reusable for those events without
+ * touching this dispatcher.
+ *
+ * Exit codes:
+ *   0 -> happy path.
+ *   1 -> config present but invalid (doctor only).
+ *   2 -> argument error / unknown subcommand.
+ */
+async function dispatchHooks(args, flags, _session) {
+    const rc = await runHooksCommand(args, {
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
+async function dispatchTheme(args, flags, _session) {
+    const rc = await runThemeCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
+/**
+ * Leak L25 (2026-05-27) — `pugi onboarding` top-level dispatcher.
+ *
+ * Walks the new operator through auth / permission mode / output
+ * style / MCP / telemetry consent. The Ink wizard mounts only when
+ * stdin is a TTY and `--json` is not set; otherwise we dump the
+ * current snapshot + hints in the non-interactive envelope so
+ * scripted callers see the same structured payload.
+ *
+ * Auth status: we resolve credentials once up front and pass the
+ * boolean to the runner; the wizard surfaces a `pugi login` hint
+ * when auth is missing but DOES NOT block — local defaults are still
+ * configurable without an active credential.
+ *
+ * Exit-code policy:
+ *   0 — completed / cancelled / non-interactive / reset
+ *   2 — conflicting / unknown flags
+ */
+async function dispatchOnboarding(args, flags, _session) {
+    const credential = resolveActiveCredential();
+    const rc = await runOnboardingCommand(args, {
+        workspaceRoot: process.cwd(),
+        env: process.env,
+        authPresent: credential !== null,
+        interactive: isInteractive(flags) && !flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
+/**
+ * Leak L26 (2026-05-27) — `pugi vim` top-level dispatcher.
+ *
+ * Forwards to the shared `runVimCommand` runner. The REPL `/vim` slash
+ * uses the same runner via a dynamic import inside
+ * `core/repl/session.ts` so the two surfaces stay single-sourced.
+ *
+ * Exit-code policy:
+ *   - 0 — show / enable / disable / toggle happy paths
+ *   - 2 — unknown subcommand (e.g. `pugi vim chaos`) or too many args
+ */
+async function dispatchVim(args, flags, _session) {
+    const rc = await runVimCommand(args, {
+        env: process.env,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
+/**
+ * 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}` };
+        },
+    });
+}
+/**
+ * `pugi chain` — Wave 6 artifact chain dispatcher (2026-05-27).
+ * Forwards to `runChainCommand` with the live credential + session
+ * opener wired so the dispatcher can hit Anvil. The slash counterpart
+ * `/chain` shares the same handler via session.ts so the surface
+ * stays single-sourced.
+ */
+async function dispatchChain(args, flags, _session) {
+    await runChainCommand(args, {
+        cwd: process.cwd(),
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        resolveConfig: () => {
+            const credential = resolveActiveCredential();
+            if (!credential)
+                return null;
+            return buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey });
+        },
+        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 +636,225 @@ 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) {
+    // Wave 6 BT 8 (Claude Code parity): parse `--force` / `-f` so the
+    // operator can produce a marker against a short session. Auto-trigger
+    // paths never pass this flag — only the explicit CLI / slash invocation.
+    const force = args.some((t) => t === '--force' || t === '-f');
+    const result = await runCompactCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        force,
+    });
+    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 L9 (2026-05-27) — `pugi rewind [N | --to <id>]` rolls the
+ * conversation back to a checkpoint by appending a tombstone marker to
+ * the NDJSON event log. Append-only: events stay durable; `pugi
+ * sessions undo-rewind` reverses the operation. The slash `/rewind`
+ * forwards through this same runner via session.ts.
+ */
+async function dispatchRewind(args, flags, _session) {
+    const result = await runRewindCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (result.status === 'failed_no_session'
+        || result.status === 'failed_store') {
+        process.exitCode = 1;
+        return;
+    }
+    if (result.status === 'failed_parse') {
+        process.exitCode = 2;
+        return;
+    }
+    if (result.status === 'noop_zero' || result.status === 'noop_empty') {
+        process.exitCode = 2;
+    }
+}
+/**
+ * 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),
+    });
+}
+/**
+ * Leak L20 (2026-05-27): `pugi share` top-level surface. Exports the
+ * current session transcript as Markdown to gist (default when `gh` is
+ * available) or pugi.io (--pugi). The handler delegates to
+ * `runShareCommand` so the slash surface (`/share`) and the shell
+ * surface share one code path. JSON output mode is honoured via the
+ * shared `writeOutput` wrapper.
+ */
+async function dispatchShare(args, flags, _session) {
+    await runShareCommand(args, {
+        workspaceRoot: process.cwd(),
+        cliVersion: PUGI_CLI_VERSION,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
+/**
+ * Leak L7 — `pugi plan [--back | --persist | <prompt...>]`.
+ *
+ * Quick mode-switch shortcut + optional one-shot engine dispatch. Slash
+ * surface `/plan` shares the same `runPlanCommand` helper so the
+ * workspace-state writes go through one code path. Argument grammar:
+ *
+ *   pugi plan                    -> set workspace mode = plan + banner
+ *   pugi plan --back             -> restore the mode that was active
+ *                                   before the most recent /plan entry
+ *   pugi plan --persist          -> set + also write ~/.pugi/config.json
+ *   pugi plan <prompt...>        -> set + run `runEngineTask('plan')`
+ *                                   with the prompt (existing offline /
+ *                                   engine path; the permission gate now
+ *                                   sees plan as workspace state)
+ *   pugi plan <prompt> --auto-back  -> ALSO restore previous mode once
+ *                                       the engine returns (defaults to
+ *                                       leaving the operator in plan
+ *                                       mode so they can iterate)
+ *
+ * The handler intentionally intercepts the mode-switch flags BEFORE
+ * delegating to `runEngineTask('plan')` for the prompt path. Without
+ * this wrapper, `pugi plan` (no args) would error out of the engine
+ * task ("requires a prompt") which is the legacy behaviour; the L7
+ * spec wants bare `pugi plan` to be the mode switch.
+ */
+async function dispatchPlan(args, flags, session) {
+    // Strip `--back` / `--auto-back` from the positional args — the global
+    // parseArgs does not consume them (they are command-local). Anything
+    // else stays in `prompt` so the engine sees the operator's text
+    // verbatim. The flag parser keeps both `--back` and the spelling
+    // variants the operator might type from muscle memory after using
+    // `git checkout --` style flows.
+    let back = false;
+    let autoBack = false;
+    const remaining = [];
+    for (const arg of args) {
+        if (arg === '--back') {
+            back = true;
+        }
+        else if (arg === '--auto-back') {
+            autoBack = true;
+        }
+        else {
+            remaining.push(arg);
+        }
+    }
+    const hasPrompt = remaining.length > 0;
+    const persist = Boolean(flags.persist);
+    // --back and a prompt are mutually exclusive — back is a revert action,
+    // not a dispatch one. Refuse the combination with a clear hint instead
+    // of silently dropping one or the other.
+    if (back && hasPrompt) {
+        writeOutput(flags, { ok: false, error: 'pugi plan --back does not accept a prompt; revert first, then dispatch.' }, 'pugi plan --back does not accept a prompt; revert first, then dispatch.');
+        process.exitCode = 2;
+        return;
+    }
+    // --back + --auto-back is incoherent (auto-back applies to the
+    // dispatch path) — refuse rather than degrade silently.
+    if (back && autoBack) {
+        writeOutput(flags, { ok: false, error: 'pugi plan --back and --auto-back cannot be combined.' }, 'pugi plan --back and --auto-back cannot be combined.');
+        process.exitCode = 2;
+        return;
+    }
+    // When a prompt is going to be dispatched in --json mode, suppress
+    // the human-readable banner writes so the engine task remains the
+    // single JSON emitter on stdout. The mode write still happens. In
+    // human (non --json) mode the banner prints normally so the operator
+    // sees the gate-state change before the engine starts thinking.
+    const sinkSilent = hasPrompt && flags.json;
+    const writeLine = (line) => {
+        if (sinkSilent)
+            return;
+        writeOutput(flags, { text: line }, line);
+    };
+    const result = await runPlanCommand({ back, persist }, {
+        workspaceRoot: process.cwd(),
+        writeOutput: writeLine,
+    });
+    // No prompt → mode-switch only. Done.
+    if (!hasPrompt)
+        return;
+    // Prompt present → fall through to the existing engine task with the
+    // remaining args. The workspace mode is now `plan` (or stayed `plan`
+    // if already there); the engine sees the same plan-task semantics it
+    // always has — read-only schema + executor refusal sentinel — but the
+    // permission GATE now also enforces plan independently.
+    try {
+        await runEngineTask('plan')(remaining, flags, session);
+    }
+    finally {
+        // --auto-back restores the previous mode AFTER the engine returns
+        // (success OR failure) so the operator's gate state mirrors a normal
+        // `--back` invocation. Without --auto-back the operator stays in
+        // plan and can iterate / inspect before acting.
+        if (autoBack && (result.verdict === 'entered' || result.verdict === 'persisted')) {
+            await runPlanCommand({ back: true, persist: false }, {
+                workspaceRoot: process.cwd(),
+                writeOutput: writeLine,
+            });
+        }
+    }
+}
 async function dispatchSkills(args, flags, _session) {
     await runSkillsCommand(args, {
         workspaceRoot: process.cwd(),
@@ -279,6 +869,19 @@ async function dispatchAgents(args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * Leak L10 (2026-05-27): `pugi dispatch <sub>` — operator-facing
+ * inspection + GC for fork-subagent prompt-cache inherit refs
+ * (.pugi/cache-refs/). Delegates to the standalone runner in
+ * commands/dispatch.ts so the cli.ts table stays under control.
+ */
+async function dispatchSubagentCacheRefs(args, flags, _session) {
+    await runDispatchCommand(args, {
+        workspaceRoot: process.cwd(),
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
 /**
  * `pugi web <url>` — Sprint α6.15 Phase 1 quick-win subcommand.
  *
@@ -328,22 +931,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 +980,82 @@ 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);
+    // Leak L22 — print the one-line bare banner once per invocation when
+    // the flag is active and stdout is NOT bound for JSON consumption. The
+    // banner goes to stderr so it never lands in a `--json` envelope or a
+    // pipe-captured stdout stream; operators see it on the terminal,
+    // scripted callers stay clean. Suppressed for `pugi version` / `pugi
+    // help` (short, scripted-friendly surfaces) and when the operator
+    // sets PUGI_BARE without the flag (avoids double-printing across
+    // scripted nested invocations).
+    if (flags.bare &&
+        !flags.json &&
+        command !== 'version' &&
+        command !== 'help' &&
+        argv.includes('--bare')) {
+        process.stderr.write(`${BARE_MODE_BANNER}\n`);
+    }
+    // β-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;
+    }
+    // Leak L25 (2026-05-27): first-run hint. When the operator types a
+    // bare `pugi` on a real TTY AND the onboarding marker is absent, drop
+    // a one-line hint on stderr BEFORE the REPL splash mounts. Stderr so
+    // the line never lands in a `--json` envelope or a scripted stdout
+    // pipe; suppressed when --json is set or the operator already walked
+    // the wizard. The marker check is best-effort — a fs glitch returns
+    // false and we print the hint, which is harmless.
+    if (isBareInvocation
+        && isInteractive(flags)
+        && !flags.json
+        && !isOnboarded(process.env)) {
+        process.stderr.write('Tip: run `pugi onboarding` to configure defaults.\n');
+    }
     // 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 +1130,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,13 +1140,50 @@ 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,
+        // Leak L22 — `--bare` flag (skip project auto-discovery). Default
+        // honors the env var so a wrapper script that exports PUGI_BARE=1
+        // keeps the bit even when the operator forgets the flag, and the
+        // explicit flag overrides on the way through the loop below.
+        bare: isBareMode(),
+        // Leak L33 — `--ascii-only` for `pugi stickers`. Default off so the
+        // interactive surface keeps its boxed renderer; opt-in via flag
+        // for pipe / script use.
+        asciiOnly: false,
+        // Leak L24 — `--reset` for `pugi release-notes`. Default off so a
+        // bare invocation only surfaces new sections. Opt-in to force the
+        // full bundled changelog к re-render (clears the on-disk marker).
+        reset: false,
+        // Leak L28 — `--refresh` for `pugi repo-map`. Default off so a
+        // bare invocation hits the cache when mtime + size match; opt-in
+        // for a cold rebuild from the source tree.
+        refresh: false,
     };
     const args = [];
+    // Leak L22: scan for `--bare` BEFORE the early-return short-circuits
+    // below. Operators may pass `pugi --bare --version` or `pugi --bare
+    // --help` and the short-circuit return must still flip the bare bit
+    // so subprocesses + env-consulting modules see the activated state.
+    // The bit is idempotent — re-applied inside the main loop below for
+    // non-short-circuit paths.
+    if (argv.includes('--bare')) {
+        flags.bare = true;
+        setBareMode();
+    }
     // Sprint 2E: `pugi --version` / `-v` are universal install-test conventions
     // (npm uses --version on every published bin, Homebrew formula uses it in
     // the test block). Normalize them to the `version` command so users can
@@ -482,7 +1214,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 +1227,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 +1243,51 @@ 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 === '--ascii-only') {
+            // Leak L33 — `pugi stickers --ascii-only` skips the Ink boxed
+            // renderer. Parsed globally so the dispatcher can pass the flag
+            // through to runStickersCommand without per-command argv slicing.
+            flags.asciiOnly = true;
+        }
+        else if (arg === '--reset') {
+            // Leak L24 — `pugi release-notes --reset` clears the on-disk
+            // `~/.pugi/.last-seen-version` marker so the full bundled
+            // changelog re-renders. Parsed globally for symmetry with the
+            // rest of the flag grammar; `runReleaseNotesCommand` is the
+            // single consumer today.
+            flags.reset = true;
+        }
+        else if (arg === '--refresh') {
+            // Leak L28 — `pugi repo-map --refresh` busts the cache and
+            // rebuilds the AST-light summary from a cold scan. Parsed
+            // globally for symmetry with the rest of the flag grammar;
+            // `runRepoMapCommand` is the single consumer today.
+            flags.refresh = true;
+        }
+        else if (arg === '--format=json' || arg === '--format' && argv[index + 1] === 'json') {
+            // Leak L28 — `pugi repo-map --format=json` is a per-command
+            // synonym for the global `--json` flag. The L28 spec calls
+            // out the `--format=json` shape explicitly so we accept it
+            // verbatim and route through the existing JSON envelope.
+            flags.json = true;
+            if (arg === '--format')
+                index += 1;
+        }
+        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 +1298,190 @@ 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 if (arg === '--bare') {
+            // Leak L22: disable project auto-discovery for this invocation.
+            // Set BOTH the parsed flag and the process env so downstream
+            // modules consulting `isBareMode()` (markdown-traverse callsite,
+            // REPL auto-init gate, doctor probe, subprocess spawns) see a
+            // coherent activated state without re-threading the bit through
+            // every call signature.
+            flags.bare = true;
+            setBareMode();
+        }
         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 +1489,345 @@ 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>',
+    ],
+    share: [
+        'pugi share — export the current session transcript (leak L20).',
+        '',
+        'Reads .pugi/events.jsonl, formats it as Markdown, and uploads to',
+        'either a GitHub Gist (`gh`-backed, default when `gh` is available)',
+        'or pugi.io (--pugi). Always prompts before upload unless --yes is',
+        'set. Refuses upload entirely if the transcript carries an active',
+        '`Bearer ` credential — re-run with --redact to scrub it first.',
+        '',
+        'Flags:',
+        '  --gist            Force gist target; refuses if gh CLI is absent.',
+        '  --pugi            Force pugi.io target (requires `pugi login`).',
+        '  --redact          Run PII scrubber before upload.',
+        '  --preview         Print the transcript to stdout WITHOUT upload.',
+        '  --yes, -y         Skip the y/n confirmation prompt.',
+        '  --json            Emit a structured JSON envelope only.',
+        '',
+        'Examples:',
+        '  pugi share                          Auto-pick + confirm.',
+        '  pugi share --preview --redact       See what would be shared.',
+        '  pugi share --gist --redact --yes    Scripted secret-gist upload.',
+    ],
+    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                                   Read PUGI_API_KEY (or --key) + verify via /api/pugi/health.',
+        '  --provider env --key <value> --skip-validate    Explicit key, no probe (CI bootstrap).',
+    ],
+    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.',
+    ],
+    chain: [
+        'pugi chain — Wave 6 artifact chain (PRD → ADR → mindmap → ER → sequence → tests → code).',
+        '',
+        '  new "<intent>"           Start a new chain from a one-sentence intent.',
+        '  status [<chain-id>]      Show current cursor + per-step table.',
+        '  next [<chain-id>]        Approve the last step and dispatch the next.',
+        '  show <step> [<chain-id>] Render one artifact (prd/adr/mindmap/er/sequence/tests/code).',
+        '  export [<chain-id>] [--json]   Bundle every artifact as markdown / JSON.',
+        '  list                     Every chain in this workspace.',
+    ],
+    dispatch: [
+        'pugi dispatch <sub> — inspect + GC fork-subagent prompt-cache inherit refs.',
+        '',
+        '  list-cache-refs                        Table of every active ref under .pugi/cache-refs/.',
+        '  clear-cache-refs [--older-than 1h]     Evict refs older than the window (default 24h).',
+        '',
+        'Leak L10 (2026-05-27): when Mira spawns a child via the `agent` tool,',
+        'a prompt-cache handle is persisted so the child loop can request',
+        'parent-context reuse on the wire. These commands surface + clean up',
+        'the persisted refs.',
+    ],
+    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.',
+    ],
+    'prd-check': [
+        'pugi prd-check <prd-path> | --all   — Wave 6 verified-deliverable gate.',
+        '',
+        'Reads a markdown PRD, parses the acceptance-criteria section, and',
+        'runs verifiers against committed artifacts:',
+        '  file:<path>      fs.existsSync',
+        '  test:<spec>      spec file exists + has ≥1 test()/it() block',
+        '  doc:<path>       doc exists + has > 100 chars',
+        '  command:<name>   CLI registry contains the command',
+        '  route:METHOD /p  best-effort grep of controllers',
+        '',
+        '  --all                   Scan docs/prd/**.md instead of one file.',
+        '  --json                  Emit a structured envelope to stdout.',
+        '',
+        'Exit codes: 0 healthy · 1 failing · 2 unparsed / arg error.',
+    ],
+    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.',
+    ],
+    update: [
+        'pugi update — channel-aware @pugi/cli update check + install.',
+        '',
+        'Polls npm registry dist-tags for a newer @pugi/cli on the configured',
+        'channel (stable / beta / canary). Without flags, prints the install',
+        'command and exits. With --apply, shells out to `npm install -g …`.',
+        '',
+        '  --check                 Non-interactive probe + JSON envelope.',
+        '  --channel <name>        Switch channel (stable | beta | canary) and probe.',
+        '                          Persisted to ~/.pugi/config.json::updateChannel.',
+        '  --apply                 Shell out to `npm install -g @pugi/cli@<tag>`',
+        '                          after a y/n confirmation.',
+        '  --yes, -y               Skip the confirmation prompt on --apply.',
+        '  --json                  Force JSON envelope (auto-on with --check).',
+        '',
+        'Channel mapping: stable -> npm `latest`, beta -> npm `beta`,',
+        'canary -> npm `next`. Default channel is `beta` (Pugi currently',
+        'ships beta releases only).',
+        '',
+        'Also available as /update from inside the REPL — slash form NEVER',
+        'spawns npm (would corrupt the running binary); it only prints the',
+        'install command for the operator к run after exit.',
+        '',
+        'R2 atomic swap (sprint plan L27) deferred к Phase 2 — npm is the',
+        'only distribution channel today.',
+    ],
+    stickers: [
+        'pugi stickers — show a Pugi brand sticker (gimmick).',
+        '',
+        'Picks one of the curated pug-face ASCII variants at random and footers',
+        'it with a rotating brand quote. Brand-personality surface — never a gate.',
+        '',
+        '  --json                  Emit a structured envelope (id · caption · quote).',
+        '  --ascii-only            Plain stdout (no box, no dim accents) for scripting.',
+        '',
+        'Also available as /stickers from inside the REPL.',
+    ],
+    feedback: [
+        'pugi feedback — file a bug / feature / general comment from the CLI.',
+        '',
+        'Interactive five-step wizard:',
+        '  1. category (bug / feature / general / praise)',
+        '  2. rating (1-5 stars)',
+        '  3. comment (multi-line, Ctrl-D submits)',
+        '  4. include redacted last 5 turns? (y/n, default n)',
+        '  5. confirm submit (y/n, default y)',
+        '',
+        'On network failure the envelope is appended to',
+        '.pugi/feedback-queue.jsonl and drained on the next online session.',
+        '',
+        'Also available as /feedback from inside the REPL.',
+    ],
+    'release-notes': [
+        'pugi release-notes — show what changed since you last upgraded.',
+        '',
+        'Reads the bundled CHANGELOG.md, slices to sections strictly newer than',
+        '~/.pugi/.last-seen-version, renders Markdown to stdout, then bumps the',
+        'last-seen marker to the installed CLI version. Re-running is a no-op',
+        'until you upgrade again.',
+        '',
+        '  --json                  Emit a structured envelope (sections + meta).',
+        '  --reset                 Clear last-seen marker; re-render every section.',
+        '',
+        'Also available as /release-notes from inside the REPL.',
+    ],
+    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 +1847,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 +1865,17 @@ 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.',
+        '  pugi dispatch list-cache-refs            Inspect fork-subagent prompt-cache inherit refs.',
+        '  pugi dispatch clear-cache-refs           GC stale cache refs (--older-than 1h).',
+        '',
+        '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 +1898,302 @@ 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.',
+        '  --bare                  Disable project auto-discovery — no PUGI.md /',
+        '                          AGENTS.md / CLAUDE.md / GEMINI.md walk-up, no',
+        '                          auto-init of .pugi/, no persona auto-load.',
+        '                          Pairs with PUGI_BARE=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',
-            };
+    await runDoctorCommand({
+        cwd: process.cwd(),
+        home: defaultDoctorHome(),
+        env: process.env,
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
+/**
+ * `pugi prd-check` — Wave 6 verified-deliverable gate (2026-05-27).
+ *
+ * Reads `docs/prd/<feature>.md` (or any explicit path), parses the
+ * acceptance-criteria section, and runs file / test / doc / command
+ * / route verifiers per criterion. Same handler powers the in-REPL
+ * `/prd-check` slash via session.ts so the verdict is identical
+ * between surfaces.
+ *
+ * The `knownCommands` set is sourced from the same `handlers` map
+ * used by the CLI dispatcher (one source of truth), so a PRD that
+ * mentions `pugi <name>` resolves against the EXACT registry the
+ * shell exposes.
+ *
+ * Exit codes (from reporter.exitCodeFor):
+ *   0 — healthy (every criterion PASS or SKIPPED)
+ *   1 — failing (≥1 FAIL)
+ *   2 — unparsed (PRD has no acceptance section) OR arg error
+ */
+async function dispatchPrdCheck(args, flags, _session) {
+    const parsed = parsePrdCheckArgs(args, { jsonDefault: flags.json });
+    if (!parsed.ok) {
+        writeOutput(flags, { ok: false, error: parsed.error }, parsed.error);
+        process.exitCode = 2;
+        return;
+    }
+    await runPrdCheckCommand({
+        cwd: process.cwd(),
+        ...(parsed.prdPath !== undefined ? { prdPath: parsed.prdPath } : {}),
+        flags: parsed.flags,
+        knownCommands: knownCommandNames(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
+/**
+ * Snapshot the set of registered CLI command names — used by the
+ * prd-check `command:` verifier so PRD mentions of `pugi <name>`
+ * resolve against the exact same registry the shell exposes.
+ */
+function knownCommandNames() {
+    return new Set(Object.keys(handlers));
+}
+/**
+ * `pugi update` — Leak L27 (2026-05-27). Channel-aware npm registry
+ * probe + optional shell-out to `npm install -g @pugi/cli@<tag>`.
+ *
+ * Argument grammar:
+ *   pugi update                       -> probe + offer install command
+ *   pugi update --check               -> probe + JSON envelope (scripted)
+ *   pugi update --channel <name>      -> persist channel + probe
+ *   pugi update --apply [--yes]       -> probe + shell out to npm
+ *   pugi update --json                -> JSON envelope (any subcommand)
+ *
+ * The handler delegates to `runUpdateCommand` in
+ * `runtime/commands/update.ts` so the in-REPL `/update` slash + the
+ * top-level shell command share one channel-resolution + persistence
+ * + probe surface. Exit codes:
+ *
+ *   0 — happy path (no update OR update completed OR probe-only)
+ *   1 — install / probe failure with structured error
+ *   2 — argument error (unknown flag, unknown channel)
+ */
+async function dispatchUpdate(args, flags, _session) {
+    const { parseUpdateArgs, runUpdateCommand, defaultSpawnInstaller } = await import('./commands/update.js');
+    const parsed = parseUpdateArgs(args, { jsonDefault: flags.json });
+    if ('error' in parsed) {
+        writeOutput(flags, { ok: false, error: parsed.error }, parsed.error);
+        process.exitCode = 2;
+        return;
+    }
+    const envelope = await runUpdateCommand({
+        cwd: process.cwd(),
+        home: homedir(),
+        env: process.env,
+        flags: parsed,
+        promptConfirm: async (question) => {
+            const answer = await readSingleChoice(`${question} `);
+            return /^y(es)?$/i.test(answer.trim());
         },
-    };
-    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 = {
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        spawnInstaller: defaultSpawnInstaller,
+    });
+    if (!envelope.ok) {
+        // `apply_cancelled_by_operator` is a benign decline; we still
+        // surface a non-zero exit so scripted callers can detect that the
+        // operator did not green-light the install.
+        process.exitCode = 1;
+    }
+}
+/**
+ * `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),
+    });
+}
+/**
+ * `pugi stickers` — Leak L33 (2026-05-27). Brand-personality gimmick
+ * mirroring Claude Code's `/stickers` easter egg. Picks one curated
+ * pug-face ASCII variant at random + footers it with a rotating quote
+ * from the Pugi brand corpus. Always exits 0 — never a gate.
+ *
+ * The handler stays thin: corpus + picker + pure renderers live in
+ * `tui/stickers-art.tsx`; this wrapper just hands the resolved result
+ * к the shared `writeOutput` helper so `--json` keeps producing a
+ * structured envelope (id + caption + quote + meta) for scripted
+ * callers. The `--ascii-only` flag drops the box decoration in the
+ * non-JSON path so pipes (`pugi stickers --ascii-only | lolcat`) get
+ * clean plain-text frames.
+ *
+ * The same handler powers the in-REPL `/stickers` slash, which routes
+ * the text through the conversation system pane line-buffer.
+ */
+async function stickers(_args, flags, _session) {
+    runStickersCommand({
+        json: flags.json,
+        asciiOnly: flags.asciiOnly,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
+/**
+ * `pugi repo-map` — Leak L28 (2026-05-27). Builds + caches the AST-
+ * light symbol summary of the workspace. The handler is intentionally
+ * thin: argv tail tokens are honoured for `--refresh` symmetry (the
+ * global parser already sets `flags.refresh`, but accepting the flag
+ * positionally lets `pugi repo-map refresh` work too — both forms
+ * land в the same path). Exit code is always 0 (informational).
+ *
+ * The same builder is invoked lazily on engine boot when `--bare` is
+ * not set; running the CLI command shows the operator EXACTLY what
+ * the engine would inject into the system prompt.
+ */
+async function dispatchRepoMap(args, flags, _session) {
+    const refresh = flags.refresh || args.includes('--refresh') || args.includes('refresh');
+    await runRepoMapCommand({
+        cwd: process.cwd(),
+        refresh,
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
+/**
+ * `pugi feedback` — Leak L21 (2026-05-27). In-CLI feedback collector.
+ *
+ * Five-step wizard:
+ *   1. category (bug / feature / general / praise)
+ *   2. rating (1-5)
+ *   3. comment (multi-line, Ctrl-D submits)
+ *   4. include redacted session context? (y/n, default n)
+ *   5. confirm submit (y/n, default y)
+ *
+ * POSTs to `<apiUrl>/api/pugi/feedback`. On transient failure (404,
+ * 5xx, network error) the envelope is appended to
+ * `<cwd>/.pugi/feedback-queue.jsonl`. On next online session the
+ * background flusher drains the queue silently.
+ *
+ * Non-TTY callers (CI, pipes) get a one-line "non-interactive — re-run
+ * in a real terminal" stub. The feedback wizard is intentionally
+ * TTY-only — scripting a star-rating + multi-line comment from a
+ * shell pipe would just produce low-signal noise.
+ */
+async function dispatchFeedback(_args, flags, _session) {
+    if (!isInteractive(flags)) {
+        writeOutput(flags, {
+            ok: false,
+            error: 'pugi feedback requires an interactive terminal. Re-run from a real TTY.',
+        }, 'pugi feedback: non-interactive shell — re-run from a real terminal.');
+        process.exitCode = 2;
+        return;
+    }
+    const { renderFeedbackPrompt } = await import('../tui/feedback-prompt.js');
+    const { runFeedbackCommand, renderFeedbackToast } = await import('./commands/feedback.js');
+    const { submitFeedback } = await import('../core/feedback/submitter.js');
+    const verdict = await renderFeedbackPrompt();
+    if (verdict.cancelled || !verdict.draft) {
+        writeOutput(flags, { ok: true, kind: 'cancelled' }, 'Feedback cancelled. Nothing was sent.');
+        return;
+    }
+    // Best-effort credential resolution. Anonymous submission is allowed
+    // (the server may still accept it for ungated `/api/pugi/feedback`
+    // routes); on no-credential we route the POST through an empty
+    // bearer + the operator gets the 4xx → "rejected" toast if the
+    // server requires auth.
+    const credential = resolveActiveCredential(process.env);
+    const apiUrl = credential?.apiUrl ?? (process.env.PUGI_API_URL || 'https://api.pugi.io');
+    const apiKey = credential?.apiKey ?? '';
+    const result = await runFeedbackCommand({
+        cwd: process.cwd(),
         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'));
+        submit: async (env) => submitFeedback(env, { apiUrl, apiKey }),
+        draft: verdict.draft,
+        // `pugi feedback` from a fresh shell has no live transcript — the
+        // session-context provider is omitted. The REPL slash variant
+        // wires this in via `runFeedbackSlash` (session.ts).
+    });
+    writeOutput(flags, { ok: true, result }, renderFeedbackToast(result));
 }
-async function init(_args, flags, _session) {
-    const cwd = process.cwd();
+/**
+ * `pugi release-notes` — Leak L24 (2026-05-27). Diff between the
+ * last-seen + installed CLI versions, rendered from the bundled
+ * `apps/pugi-cli/CHANGELOG.md`. Bumps `~/.pugi/.last-seen-version`
+ * to the installed version on every successful render so the next
+ * invocation is a no-op until the operator upgrades again.
+ *
+ * The handler stays thin: parser, slicer, and state I/O all live in
+ * `core/release-notes/`. This wrapper just hands ambient state to
+ * `runReleaseNotesCommand` so `--json` keeps producing the same
+ * envelope from both the top-level shell + the in-REPL `/release-notes`
+ * slash dispatcher.
+ *
+ * Always exits 0 — the command is informational, never a gate. Read
+ * failures, missing CHANGELOG, and write failures all degrade to a
+ * structured envelope with a human-readable footer.
+ */
+async function releaseNotes(_args, flags, _session) {
+    runReleaseNotesCommand({
+        home: defaultReleaseNotesHome(),
+        json: flags.json,
+        reset: flags.reset,
+        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 +2215,9 @@ async function init(_args, flags, _session) {
             mode: 'balanced',
             telemetry: 'off',
         },
+        ui: {
+            cyberZoo: 'on',
+        },
         artifacts: {
             defaultPath: '.pugi/artifacts',
             promoteExplicitly: true,
@@ -692,7 +2225,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 +2278,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 +2659,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 +2684,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 +3130,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':
@@ -1642,6 +3557,25 @@ async function handoff(args, flags, session) {
     writeOutput(flags, bundle, ['Pugi handoff bundle created', `Bundle: ${bundle.path}`].join('\n'));
 }
 async function sessions(args, flags, _session) {
+    // L9 (2026-05-27): `pugi sessions undo-rewind [<session-id>]` rolls
+    // back the latest /rewind by appending an inverse marker. Append-only,
+    // reversible. Falls through to the legacy artifact-based handler when
+    // the sub-command is not recognised.
+    if (args[0] === 'undo-rewind') {
+        const result = await runSessionsCommand(args, {
+            workspaceRoot: process.cwd(),
+            writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        });
+        if (result) {
+            if (result.status === 'failed_no_session' || result.status === 'failed_store') {
+                process.exitCode = 1;
+            }
+            else if (result.status === 'noop_no_rewind') {
+                process.exitCode = 2;
+            }
+            return;
+        }
+    }
     // α6.4: `pugi sessions --local` / `--search "query"` route to the
     // local SessionStore. The default surface stays artifact-based for
     // backward compat — operators who relied on the index.json view get
@@ -2075,6 +4009,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 +4049,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 +4121,401 @@ 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`);
+                });
+            }
+            // Leak L15 (2026-05-27) — tear down any LSP servers warmed up
+            // by the post-edit diagnostics cache. The cache is per-process
+            // and survives across multiple tool calls; without this hook a
+            // `pugi code ...` invocation would leak a tsserver process when
+            // the Node host exits. The dynamic import keeps the cache module
+            // out of the cold path for runs that never touch LSP.
+            try {
+                const { stopAllLspClients } = await import('../core/lsp/cache.js');
+                await stopAllLspClients();
+            }
+            catch (error) {
+                process.stderr.write(`pugi ${label}: LSP cache 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
@@ -2579,7 +4747,7 @@ async function login(args, flags, _session) {
     if (args.includes('--help') || args.includes('-h')) {
         writeOutput(flags, {
             command: 'login',
-            usage: 'pugi login [--provider device|token|env] [--token <PAT>] [--token-stdin] [--label <name>] [--api-url <url>]',
+            usage: 'pugi login [--provider device|token|env] [--token <PAT>] [--token-stdin] [--key <value>] [--skip-validate] [--label <name>] [--api-url <url>]',
         }, [
             'Usage: pugi login [options]',
             '',
@@ -2591,19 +4759,27 @@ async function login(args, flags, _session) {
             'Non-interactive options:',
             '  --provider device   Run the device-flow login (recommended).',
             '  --provider token    Store an API key passed via --token / --token-stdin / PUGI_LOGIN_TOKEN.',
-            '  --provider env      Promote PUGI_API_KEY from the environment into the store.',
+            '  --provider env      Read PUGI_API_KEY (or --key) and verify it via /api/pugi/health.',
             '  --token <PAT>       Inline API key (visible in `ps`).',
             '  --token-stdin       Read API key from stdin (gh-CLI style).',
+            '  --key <value>       Explicit key for --provider env; beats PUGI_API_KEY.',
+            '  --skip-validate     Skip the /api/pugi/health probe for --provider env (CI bootstrap).',
             '  --label <name>      Short label surfaced in `pugi accounts list`.',
             '  --api-url <url>     Override the Anvil endpoint (self-hosted).',
             '  --no-device-flow    Refuse the device flow; fail fast in CI without a token.',
             '',
+            'Environment variables:',
+            '  PUGI_API_KEY        Read by --provider env. Pass --key to override.',
+            '  PUGI_LOGIN_TOKEN    Read by --provider token in non-interactive shells.',
+            '  PUGI_API_URL        Override the Anvil endpoint (same as --api-url).',
+            '',
             'Examples:',
             '  pugi login                                  # interactive picker on a TTY',
             '  pugi login --provider device                # explicit browser OAuth',
             '  pugi login --provider token --token sk-xx   # paste in a key',
             '  echo $TOKEN | pugi login --provider token --token-stdin',
-            '  PUGI_API_KEY=sk-xx pugi login --provider env',
+            '  PUGI_API_KEY=pugi_xxx pugi login --provider env',
+            '  pugi login --provider env --key pugi_xxx    # explicit key beats env',
         ].join('\n'));
         return;
     }
@@ -2626,6 +4802,11 @@ async function login(args, flags, _session) {
     const apiUrlOverride = extractApiUrlFlag(args);
     const labelFlag = extractLabelFlag(args);
     const provider = parseProviderFlag(args);
+    // Leak L35 (2026-05-27): `--key` is the explicit-arg path for
+    // `--provider env`; `--skip-validate` bypasses the /api/pugi/health
+    // probe (CI bootstrap before the network is up).
+    const envExplicitKey = extractKeyFlag(args);
+    const envSkipValidate = args.includes('--skip-validate');
     const apiUrl = normalizeApiUrl(apiUrlOverride ?? process.env.PUGI_API_URL ?? DEFAULT_API_URL);
     // Path 1: explicit --provider trumps everything else.
     if (provider) {
@@ -2636,6 +4817,8 @@ async function login(args, flags, _session) {
             explicitToken: tokenFromArgs,
             tokenStdinFlag,
             noDeviceFlow,
+            envExplicitKey,
+            envSkipValidate,
         });
         return;
     }
@@ -2683,6 +4866,8 @@ async function login(args, flags, _session) {
             flags,
             label: labelFlag,
             noDeviceFlow,
+            envExplicitKey,
+            envSkipValidate,
         });
         return;
     }
@@ -2901,16 +5086,28 @@ async function dispatchLoginProvider(provider, ctx) {
             return;
         }
         case 'env': {
-            const envKey = process.env.PUGI_API_KEY;
-            if (!envKey) {
-                throw new Error('pugi login --provider env requires PUGI_API_KEY to be exported in the current shell.');
+            // Leak L35 (2026-05-27): resolve the env / --key candidate,
+            // run the local format check, then probe `/api/pugi/health`
+            // BEFORE persisting. A bad token never lands on disk so the
+            // next `pugi <anything>` does not silently 401 against the
+            // cabinet. `--skip-validate` opts out for CI bootstrap.
+            const resolved = await resolveAndValidateEnvLogin({
+                apiUrl: ctx.apiUrl,
+                explicitKey: ctx.envExplicitKey,
+                env: process.env,
+                skipValidate: ctx.envSkipValidate ?? false,
+            });
+            if (resolved.kind !== 'ok') {
+                reportEnvLoginFailure(resolved, ctx.flags);
+                return;
             }
             storeAndAnnounceToken({
                 apiUrl: ctx.apiUrl,
-                apiKey: envKey,
+                apiKey: resolved.token,
                 label: ctx.label,
                 source: 'env',
                 flags: ctx.flags,
+                validatedLatencyMs: resolved.latencyMs > 0 ? resolved.latencyMs : undefined,
             });
             return;
         }
@@ -2929,6 +5126,15 @@ function storeAndAnnounceToken(input) {
         label: input.label,
         source: input.source,
     });
+    const textLines = [
+        `Pugi logged in for ${record.apiUrl}`,
+        `Method: ${input.source}${record.label ? ` (${record.label})` : ''}`,
+        `Token: ${maskApiKey(record.apiKey)}`,
+    ];
+    if (typeof input.validatedLatencyMs === 'number') {
+        textLines.push(`Verified via /api/pugi/health in ${input.validatedLatencyMs}ms`);
+    }
+    textLines.push('Stored at ~/.pugi/credentials.json (mode 0600). Run `pugi whoami` to verify.');
     writeOutput(input.flags, {
         status: 'logged_in',
         apiUrl: record.apiUrl,
@@ -2936,12 +5142,55 @@ function storeAndAnnounceToken(input) {
         label: record.label ?? null,
         createdAt: record.createdAt,
         source: input.source,
-    }, [
-        `Pugi logged in for ${record.apiUrl}`,
-        `Method: ${input.source}${record.label ? ` (${record.label})` : ''}`,
-        `Token: ${maskApiKey(record.apiKey)}`,
-        'Stored at ~/.pugi/credentials.json (mode 0600). Run `pugi whoami` to verify.',
-    ].join('\n'));
+        ...(typeof input.validatedLatencyMs === 'number'
+            ? { validatedLatencyMs: input.validatedLatencyMs }
+            : {}),
+    }, textLines.join('\n'));
+}
+/**
+ * Render a typed `EnvLoginFailure` from `resolveAndValidateEnvLogin`
+ * onto the surrounding CLI surface. Maps the failure kind to:
+ *   - an exit code (1 by default; 2 for invalid format so a CI step
+ *     can disambiguate "missing key" vs "key shape wrong" without
+ *     parsing stderr; 4 for network / server errors so retry logic
+ *     can distinguish transient failures from credential failures)
+ *   - a structured JSON payload for `--json` consumers
+ *   - a human-readable stderr line for the interactive path
+ *
+ * The token itself is never echoed — only the validator's own message
+ * (which the env-provider module composed without the secret in it).
+ */
+function reportEnvLoginFailure(failure, flags) {
+    const exitCode = (() => {
+        switch (failure.kind) {
+            case 'missing':
+                return 1;
+            case 'invalid-format':
+                return 2;
+            case 'unauthorized':
+                return 3;
+            case 'network-error':
+            case 'server-error':
+                return 4;
+            case 'unexpected-status':
+                return 5;
+            default: {
+                const exhaustive = failure;
+                return Number(exhaustive) || 1;
+            }
+        }
+    })();
+    const payload = {
+        status: 'login_failed',
+        kind: failure.kind,
+        message: failure.message,
+    };
+    if ('status' in failure)
+        payload.httpStatus = failure.status;
+    if ('cause' in failure && failure.cause)
+        payload.cause = failure.cause;
+    writeOutput(flags, payload, failure.message);
+    process.exitCode = exitCode;
 }
 /**
  * OAuth 2.0 Device Authorization Grant client (RFC 8628). Renders
@@ -3697,6 +5946,17 @@ function extractApiUrlFlag(args) {
 function extractLabelFlag(args) {
     return extractNamedFlagValue(args, 'label');
 }
+/**
+ * `pugi login --provider env --key <value>` — explicit key arg that
+ * beats `PUGI_API_KEY` env. Same precedence rule as `gh auth login
+ * --with-token`, `aws configure set`, and `pugi config`: the most
+ * specific operator intent (a typed flag) overrides the ambient
+ * environment so an operator can override a stale `PUGI_API_KEY`
+ * from their shell rc without unsetting it first.
+ */
+function extractKeyFlag(args) {
+    return extractNamedFlagValue(args, 'key');
+}
 /**
  * `pugi jobs` — surface the persistent JobRegistry on the CLI.
  * Sprint α5.9 (ADR-0056 PR-PUGI-CLI-M1-GAP-J). Subcommand parsing
@@ -3975,7 +6235,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 +6277,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 +6449,6 @@ export function packageRoot() {
 export const __test__ = {
     sleep,
     pollDeviceFlowUntilTerminal,
+    sanitizeSemver,
 };
 //# sourceMappingURL=cli.js.map