@pugi/cli 0.1.0-alpha.3

package/dist/runtime/cli.js

@@ -0,0 +1,2935 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { statSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AnvilEngineLoopClient } from '../core/engine/anvil-client.js';
+import { NoopEngineAdapter } from '../core/engine/noop.js';
+import { NativePugiEngineAdapter } from '../core/engine/native-pugi.js';
+import { decidePermission } from '../core/permission.js';
+import { 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 { emptyIndex, rebuildIndex, readIndex, upsertArtifact, writeIndex, } from '../core/index-store.js';
+import { buildRuntimeConfig, loadRuntimeConfig, pollDeviceFlow, pugiHandoffBundleSchema, pugiSyncDryRunPlanSchema, pugiSyncPrivacyModeSchema, pugiSyncRequestSchema, pugiSyncUploadPlanSchema, pugiTripleReviewRequestSchema, startDeviceFlow, submitSync, submitTripleReview, } from '@pugi/sdk';
+import { clearApiKey, DEFAULT_API_URL, listStoredCredentials, maskApiKey, normalizeApiUrl, purgeAllCredentials, readCredentialsFile, resolveActiveCredential, storeApiKey, switchActiveAccount, } from '../core/credentials.js';
+/**
+ * CLI version shown by `pugi version` and embedded in `pugi doctor --json`.
+ *
+ * Kept as a single hard-coded string (rather than reading package.json at
+ * runtime) because the CLI ships compiled JS via npm — the `.tgz` does not
+ * include package.json in a location relative to the compiled bundle, and
+ * the build does not run `--resolveJsonModule`. Bumping CLI version is a
+ * three-line ritual (this constant + apps/pugi-cli/package.json +
+ * packages/pugi-sdk/package.json); the publish workflow validates the
+ * three are in lockstep.
+ */
+const PUGI_CLI_VERSION = '0.1.0-alpha.1';
+const handlers = {
+    accounts,
+    build: runEngineTask('build_task'),
+    code: runEngineTask('code'),
+    config: notImplemented('config'),
+    doctor,
+    explain: runEngineTask('explain'),
+    fix: runEngineTask('fix'),
+    handoff,
+    help,
+    idea,
+    init,
+    login,
+    logout,
+    plan: runEngineTask('plan'),
+    privacy: notImplemented('privacy'),
+    review,
+    resume,
+    sessions,
+    sync,
+    undo: notImplemented('undo'),
+    version,
+    whoami,
+};
+export async function runCli(argv) {
+    const { command, args, flags } = parseArgs(argv);
+    const handler = handlers[command] ?? help;
+    const session = openSession(process.cwd());
+    recordCommandStarted(session, command);
+    try {
+        await handler(args, flags, session);
+        // Handlers can signal a failed gate by setting `process.exitCode`
+        // (e.g. BLOCK verdict, auth_missing, rate_limited) instead of
+        // throwing. Treat any non-zero exit as 'error' so the session log
+        // and `.pugi/index.json` agree with the actual process outcome.
+        const status = process.exitCode && process.exitCode !== 0 ? 'error' : 'success';
+        recordCommandCompleted(session, command, status);
+    }
+    catch (error) {
+        recordCommandCompleted(session, command, 'error');
+        throw error;
+    }
+}
+function parseArgs(argv) {
+    const flags = {
+        json: false,
+        remote: false,
+        web: false,
+        dryRun: false,
+        triple: false,
+        offline: false,
+    };
+    const args = [];
+    // 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
+    // discover the CLI works without knowing our subcommand grammar.
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        return { command: 'version', args: [], flags };
+    }
+    if (argv[0] === '--help' || argv[0] === '-h') {
+        return { command: 'help', args: [], flags };
+    }
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? '';
+        if (arg === '--json') {
+            flags.json = true;
+        }
+        else if (arg === '--remote') {
+            flags.remote = true;
+        }
+        else if (arg === '--web') {
+            flags.web = true;
+        }
+        else if (arg === '--dry-run') {
+            flags.dryRun = true;
+        }
+        else if (arg === '--triple' || arg === '--consensus') {
+            flags.triple = true;
+        }
+        else if (arg === '--offline') {
+            flags.offline = true;
+        }
+        else if (arg.startsWith('--privacy=')) {
+            flags.privacy = parsePrivacyMode(arg.slice('--privacy='.length));
+        }
+        else if (arg === '--privacy') {
+            const next = argv[index + 1];
+            if (!next)
+                throw new Error('--privacy requires a mode');
+            flags.privacy = parsePrivacyMode(next);
+            index += 1;
+        }
+        else {
+            args.push(arg);
+        }
+    }
+    return {
+        command: args.shift() ?? 'help',
+        args,
+        flags,
+    };
+}
+async function version(_args, flags, _session) {
+    const payload = {
+        name: 'pugi',
+        version: PUGI_CLI_VERSION,
+    };
+    writeOutput(flags, payload, `pugi ${payload.version}`);
+}
+async function help(_args, flags, _session) {
+    const commands = Object.keys(handlers).sort();
+    writeOutput(flags, { commands }, [
+        'Pugi CLI',
+        '',
+        'Usage: pugi <command> [--json] [--web] [--remote]',
+        '',
+        'Commands:',
+        ...commands.map((command) => `  ${command}`),
+        '',
+        'Authentication:',
+        '  pugi login              Interactive picker (browser OAuth / PAT / env).',
+        '  pugi login --provider device|token|env   Non-interactive variant.',
+        '  pugi whoami             Show active credential, JWT account, plan tier.',
+        '  pugi accounts list      All stored accounts across multiple endpoints.',
+        '  pugi accounts switch <label>             Re-point the active account.',
+        '  pugi accounts remove <label>             Delete a stored credential.',
+        '',
+        'Review gate:',
+        '  pugi review --triple    Prepare the Anvil-backed triple-review gate.',
+        '',
+        'Sync safety:',
+        '  pugi sync --dry-run --privacy metadata',
+        '',
+        'Execution defaults to local. Use --remote or --web to create a handoff bundle.',
+    ].join('\n'));
+}
+async function doctor(_args, flags, _session) {
+    const cwd = process.cwd();
+    const settings = loadSettings(cwd);
+    // `doctor` reports adapter capabilities only; we pass a no-op client
+    // so we do not require an Anvil endpoint to run `pugi doctor`. The
+    // adapter never invokes `client.send()` from inside `capabilities()`.
+    const inertClient = {
+        async send() {
+            return {
+                stop: 'error',
+                code: 'failed',
+                message: 'doctor: inert client',
+            };
+        },
+    };
+    const adapters = [
+        new NoopEngineAdapter(),
+        new NativePugiEngineAdapter({ client: inertClient }),
+    ];
+    const capabilities = await Promise.all(adapters.map(async (adapter) => ({
+        name: adapter.name,
+        capabilities: await adapter.capabilities(),
+    })));
+    const payload = {
+        cliVersion: PUGI_CLI_VERSION,
+        nodeVersion: process.version,
+        workspaceRoot: cwd,
+        pugiMode: existsSync(resolve(cwd, 'CLAUDE.md')),
+        pugiDir: existsSync(resolve(cwd, '.pugi')),
+        eventLog: existsSync(resolve(cwd, '.pugi/events.jsonl')),
+        permissionMode: settings.permissions.mode,
+        approvals: settings.workflow.approvals,
+        notAutomatic: [...settings.workflow.notAutomatic, ...settings.permissions.notAutomatic],
+        protectedFileCheck: decidePermission({ tool: 'doctor', kind: 'edit', target: '.env' }, settings, cwd),
+        protectedFileSafety: 'configured-in-m1',
+        mcpTrust: 'not-configured',
+        releaseGuard: 'scaffolded',
+        tools: toolRegistry,
+        engineAdapters: capabilities,
+        schemaBundleHash: createHash('sha256')
+            .update(toolSchemaBundleHashInput())
+            .digest('hex'),
+    };
+    writeOutput(flags, payload, [
+        'Pugi doctor',
+        `CLI: ${payload.cliVersion}`,
+        `Node: ${payload.nodeVersion}`,
+        `Workspace: ${payload.workspaceRoot}`,
+        `Pugi mode: ${payload.pugiMode ? 'detected' : 'not detected'}`,
+        `Pugi dir: ${payload.pugiDir ? 'present' : 'missing'}`,
+        `Event log: ${payload.eventLog ? 'present' : 'missing'}`,
+        `Permission mode: ${payload.permissionMode}`,
+        `Approvals: ${payload.approvals}`,
+        `Release guard: ${payload.releaseGuard}`,
+    ].join('\n'));
+}
+async function init(_args, flags, _session) {
+    const cwd = process.cwd();
+    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);
+    writeJsonIfMissing(resolve(pugiDir, 'settings.json'), {
+        schema: 1,
+        workflow: {
+            brand: 'pugi',
+            legacyName: 'codeforge',
+            approvals: 'auto',
+            notAutomatic: [],
+            defaultBaseBranch: 'dev',
+            branchPrefixes: ['feature', 'fix', 'refactor', 'chore'],
+            aiCoAuthorTrailers: false,
+        },
+        permissions: {
+            mode: 'auto',
+            allow: [],
+            deny: [],
+            notAutomatic: [],
+        },
+        privacy: {
+            mode: 'balanced',
+            telemetry: 'off',
+        },
+        artifacts: {
+            defaultPath: '.pugi/artifacts',
+            promoteExplicitly: true,
+        },
+    }, created, skipped);
+    writeJsonIfMissing(resolve(pugiDir, 'mcp.json'), {
+        schema: 1,
+        servers: [],
+    }, created, skipped);
+    writeJsonIfMissing(resolve(pugiDir, 'index.json'), emptyIndex(), created, skipped);
+    writeTextIfMissing(resolve(pugiDir, 'PUGI.md'), [
+        '# Pugi Project Context',
+        '',
+        '## Product Workflow',
+        '',
+        '- Public product name: Pugi',
+        '- Default flow: idea -> build -> review',
+        '- Approvals are automatic by default until a repo, environment, workflow, or action is marked notAutomatic.',
+        '- Do not add AI Co-Authored-By trailers.',
+        '- Generated code, comments, commits, PR text, and technical docs default to English.',
+        '',
+        '## Project Notes',
+        '',
+        '- Add repo-specific architecture, commands, and business rules here.',
+        '- Do not store secrets, real IPs, private key paths, tokens, or credentials here.',
+        '',
+    ].join('\n'), created, skipped);
+    writeTextIfMissing(resolve(cwd, '.pugiignore'), [
+        '# Pugi ignore rules',
+        '.env',
+        '.env.*',
+        '!.env.example',
+        'node_modules/',
+        'dist/',
+        '.next/',
+        'coverage/',
+        '*.log',
+        '*.pem',
+        '*.key',
+        '*.crt',
+        '*.p12',
+        '*.sql',
+        '*.dump',
+        '',
+    ].join('\n'), created, skipped);
+    // 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 = {
+        status: 'initialized',
+        root: cwd,
+        created,
+        skipped,
+    };
+    writeOutput(flags, payload, [
+        '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',
+    ].join('\n'));
+}
+async function idea(args, flags, session) {
+    const prompt = args.join(' ').trim();
+    if (!prompt) {
+        throw new Error('pugi idea requires a prompt');
+    }
+    const root = process.cwd();
+    const pugiDir = resolve(root, '.pugi');
+    if (!existsSync(pugiDir)) {
+        throw new Error('Run pugi init before pugi idea');
+    }
+    const id = `${new Date().toISOString().replace(/[:.]/g, '-')}-${slugify(prompt)}`;
+    const artifactDir = resolve(pugiDir, 'artifacts', id);
+    mkdirSync(artifactDir, { recursive: true });
+    const toolCallId = recordToolCall(session, 'artifact:idea', prompt);
+    const briefPath = resolve(artifactDir, 'brief.md');
+    const graphPath = resolve(artifactDir, 'execution-graph.json');
+    const criteriaPath = resolve(artifactDir, 'acceptance-criteria.md');
+    const brief = [
+        '# Pugi Idea Brief',
+        '',
+        `Prompt: ${prompt}`,
+        '',
+        '## Forcing Questions',
+        '',
+        '- Who exactly has this pain?',
+        '- What do they do now?',
+        '- What breaks if this stays unsolved?',
+        '- What is the narrowest useful wedge?',
+        '- What is the current status quo cost in time or money?',
+        '- Who is the first design partner?',
+        '',
+        '## Initial Positioning',
+        '',
+        'Pugi should turn this idea into a reviewed execution graph before code is written.',
+        '',
+    ].join('\n');
+    const executionGraph = {
+        id,
+        title: prompt,
+        nodes: [
+            {
+                id: 'brief',
+                title: 'Clarify founder intent',
+                kind: 'plan',
+                dependsOn: [],
+                status: 'pending',
+                acceptanceCriteria: ['Forcing questions are answered or explicitly deferred.'],
+            },
+            {
+                id: 'scope',
+                title: 'Define narrowest wedge',
+                kind: 'plan',
+                dependsOn: ['brief'],
+                status: 'pending',
+                acceptanceCriteria: ['One bounded MVP path is selected.'],
+            },
+            {
+                id: 'build',
+                title: 'Implement approved wedge',
+                kind: 'code',
+                dependsOn: ['scope'],
+                status: 'pending',
+                acceptanceCriteria: ['Working diff is produced with tests or explicit test gap.'],
+            },
+            {
+                id: 'review',
+                title: 'Run Pugi review gate',
+                kind: 'review',
+                dependsOn: ['build'],
+                status: 'pending',
+                acceptanceCriteria: ['Review returns PASS or BLOCK with findings.'],
+            },
+        ],
+        artifacts: [
+            { id: 'brief', kind: 'brief', path: relative(root, briefPath), title: 'Idea brief', createdAt: new Date().toISOString() },
+            {
+                id: 'execution_graph',
+                kind: 'execution_graph',
+                path: relative(root, graphPath),
+                title: 'Execution graph',
+                createdAt: new Date().toISOString(),
+            },
+        ],
+    };
+    const criteria = [
+        '# Acceptance Criteria',
+        '',
+        '- The target user and pain are explicit.',
+        '- The first wedge is narrow enough for a supervised build.',
+        '- The execution graph can be reviewed before implementation.',
+        '- The review gate can block incomplete or unsafe output.',
+        '',
+    ].join('\n');
+    writeFileSync(briefPath, brief, { encoding: 'utf8', mode: 0o600 });
+    writeFileSync(graphPath, `${JSON.stringify(executionGraph, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    writeFileSync(criteriaPath, criteria, { encoding: 'utf8', mode: 0o600 });
+    registerArtifact(root, {
+        id,
+        kind: 'idea',
+        path: relative(root, artifactDir),
+        sessionId: session.id,
+        createdAt: new Date().toISOString(),
+        files: ['brief.md', 'execution-graph.json', 'acceptance-criteria.md'],
+    });
+    recordToolResult(session, toolCallId, 'success', `Created idea artifacts ${id}`);
+    const payload = {
+        status: 'created',
+        id,
+        artifacts: {
+            brief: relative(root, briefPath),
+            executionGraph: relative(root, graphPath),
+            acceptanceCriteria: relative(root, criteriaPath),
+        },
+    };
+    writeOutput(flags, payload, [
+        'Pugi idea artifacts created',
+        `ID: ${id}`,
+        `Brief: ${payload.artifacts.brief}`,
+        `Execution graph: ${payload.artifacts.executionGraph}`,
+        `Acceptance criteria: ${payload.artifacts.acceptanceCriteria}`,
+    ].join('\n'));
+}
+/**
+ * Sprint 2 Track A offline fallbacks.
+ *
+ * `pugi plan` / `pugi build` / `pugi explain` are now engine-driven by
+ * default (`runEngineTask` above). When the operator has no credential
+ * configured (`pugi login` never run, no PUGI_API_KEY env) OR the
+ * `--offline` flag is set, the engine path is skipped and these
+ * helpers produce the same local-first artifacts the pre-Sprint-2 CLI
+ * shipped. This preserves the local-first invariant proven by
+ * `test/local-first-invariants.spec.ts` — a brand-new repo with no
+ * credential can still run `init → idea → plan → build → review`.
+ *
+ * The offline implementations are intentionally identical to the
+ * pre-Sprint-2 handlers (modulo the rename); behaviour drift between
+ * the two paths is a P1 — keep them aligned when extending either.
+ */
+async function offlinePlan(args, flags, session) {
+    const root = process.cwd();
+    ensureInitialized(root);
+    const prompt = args.join(' ').trim();
+    const latestIdea = latestArtifactDir(root);
+    // Code Reviewer P2 retro 2026-05-23: both engine and offline `plan`
+    // accept an empty prompt ONLY when a previous artifact set exists
+    // to plan against. Without one the operator has handed us nothing
+    // to plan, so we fail loudly instead of producing an empty
+    // skeleton-of-a-plan artifact.
+    if (!prompt && !latestIdea) {
+        throw new Error('pugi plan requires a prompt or a previous artifact in .pugi/artifacts/');
+    }
+    const artifactDir = createArtifactDir(root, prompt || 'plan');
+    const planPath = resolve(artifactDir, 'plan.md');
+    const graphPath = resolve(artifactDir, 'execution-graph.json');
+    const toolCallId = recordToolCall(session, 'artifact:plan', prompt || 'latest local context');
+    const planText = [
+        '# Pugi Execution Plan (offline)',
+        '',
+        prompt ? `Prompt: ${prompt}` : 'Prompt: continue from local artifacts/context',
+        latestIdea ? `Previous artifact set: ${relative(root, latestIdea)}` : 'Previous artifact set: none',
+        '',
+        '## Mode',
+        '',
+        '- Offline plan: no Pugi credential configured or --offline flag set.',
+        '- To run the engine-driven plan, set PUGI_API_KEY or run `pugi login`.',
+        '',
+        '## Local-First Contract',
+        '',
+        '- CLI works with the repository locally by default.',
+        '- Remote/web execution is opt-in and represented by a handoff bundle.',
+        '- Generated artifacts are reviewable before code execution.',
+        '',
+        '## Steps',
+        '',
+        '1. Confirm scope and acceptance criteria.',
+        '2. Inspect repository context.',
+        '3. Produce or update the implementation diff locally.',
+        '4. Run available checks.',
+        '5. Run review gate before PR/deploy.',
+        '',
+        '## Open Questions',
+        '',
+        '- Which files/modules are in scope?',
+        '- Which command proves the change works?',
+        '- Should this continue locally, in web, or on a remote runner?',
+        '',
+    ].join('\n');
+    const graph = {
+        id: artifactIdFromDir(artifactDir),
+        title: prompt || 'Local execution plan',
+        mode: flags.remote ? 'remote' : flags.web ? 'web' : 'local',
+        nodes: [
+            { id: 'scope', title: 'Confirm scope', kind: 'plan', dependsOn: [], status: 'pending' },
+            { id: 'inspect', title: 'Inspect repository', kind: 'research', dependsOn: ['scope'], status: 'pending' },
+            { id: 'implement', title: 'Implement locally or hand off', kind: 'code', dependsOn: ['inspect'], status: 'pending' },
+            { id: 'verify', title: 'Run checks', kind: 'test', dependsOn: ['implement'], status: 'pending' },
+            { id: 'review', title: 'Review result', kind: 'review', dependsOn: ['verify'], status: 'pending' },
+        ],
+    };
+    writeFileSync(planPath, planText, { encoding: 'utf8', mode: 0o600 });
+    writeFileSync(graphPath, `${JSON.stringify(graph, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    registerArtifact(root, {
+        id: artifactIdFromDir(artifactDir),
+        kind: 'plan',
+        path: relative(root, artifactDir),
+        sessionId: session.id,
+        createdAt: new Date().toISOString(),
+        files: ['plan.md', 'execution-graph.json'],
+    });
+    recordToolResult(session, toolCallId, 'success', `Created offline plan ${relative(root, planPath)}`);
+    writeOutput(flags, { status: 'planned', mode: 'offline', plan: relative(root, planPath), executionGraph: relative(root, graphPath) }, [`Pugi plan created (offline)`, `Plan: ${relative(root, planPath)}`, `Execution graph: ${relative(root, graphPath)}`].join('\n'));
+}
+async function offlineBuild(args, flags, session) {
+    const root = process.cwd();
+    ensureInitialized(root);
+    const prompt = args.join(' ').trim();
+    if (!prompt) {
+        throw new Error('pugi build requires a prompt');
+    }
+    if (flags.remote || flags.web) {
+        const bundle = createHandoffBundle(root, session, flags.remote ? 'remote_build' : 'web_continue', prompt);
+        writeOutput(flags, bundle, [
+            'Pugi build handoff created',
+            `Bundle: ${bundle.path}`,
+            flags.remote ? 'Next: remote runner can claim this job.' : 'Next: web can import this bundle and continue.',
+        ].join('\n'));
+        return;
+    }
+    const artifactDir = createArtifactDir(root, prompt);
+    const buildPath = resolve(artifactDir, 'build.md');
+    const toolCallId = recordToolCall(session, 'artifact:build', prompt);
+    const text = [
+        '# Pugi Local Build Request (offline)',
+        '',
+        `Prompt: ${prompt}`,
+        '',
+        'Status: pending local implementation',
+        '',
+        '## Mode',
+        '',
+        '- Offline build: no Pugi credential configured or --offline flag set.',
+        '- To run the engine-driven build, set PUGI_API_KEY or run `pugi login`.',
+        '',
+        '## Contract',
+        '',
+        '- This command is local-first.',
+        '- Code execution should happen in this repository unless --remote or --web is used.',
+        '- Before mutating files, the engine must inspect relevant files and respect permissions.',
+        '',
+        '## Suggested Next Checks',
+        '',
+        '- `git status --short`',
+        '- project-specific test/lint/build command',
+        '- `pugi review`',
+        '',
+    ].join('\n');
+    writeFileSync(buildPath, text, { encoding: 'utf8', mode: 0o600 });
+    registerArtifact(root, {
+        id: artifactIdFromDir(artifactDir),
+        kind: 'build',
+        path: relative(root, artifactDir),
+        sessionId: session.id,
+        createdAt: new Date().toISOString(),
+        files: ['build.md'],
+    });
+    recordToolResult(session, toolCallId, 'success', `Created offline build request ${relative(root, buildPath)}`);
+    writeOutput(flags, { status: 'created', mode: 'offline', build: relative(root, buildPath) }, [
+        'Pugi local build request created (offline)',
+        `Build artifact: ${relative(root, buildPath)}`,
+        'Configure PUGI_API_KEY or run `pugi login` to use the engine-driven build loop.',
+    ].join('\n'));
+}
+async function offlineExplain(args, flags, session) {
+    const target = args[0];
+    if (!target) {
+        throw new Error('pugi explain requires a file or directory path');
+    }
+    const root = process.cwd();
+    const settings = loadSettings(root);
+    const ctx = {
+        root,
+        settings,
+        session,
+        readCache: new FileReadCache(),
+    };
+    // Validate the target stays inside the workspace BEFORE statting it.
+    // `resolveWorkspacePath` follows symlinks at both the parent and the
+    // target itself, so `pugi explain etc-link` (a symlink to /etc) and
+    // `pugi explain /etc` are both refused here before any directory walk
+    // or file read fans out.
+    const resolvedTarget = resolveWorkspacePath(root, target);
+    const stat = statSync(resolvedTarget);
+    if (stat.isDirectory()) {
+        const paths = globTool(ctx, `${target.replace(/\/$/, '')}/**/*`).slice(0, 80);
+        const matches = grepTool(ctx, 'TODO').slice(0, 20);
+        writeOutput(flags, { target, kind: 'directory', mode: 'offline', paths, todoMatches: matches }, [`Directory: ${target}`, `Files: ${paths.length}`, ...paths.map((path) => `  ${path}`)].join('\n'));
+        return;
+    }
+    const content = readTool(ctx, target);
+    const lines = content.split('\n');
+    const excerpt = lines.slice(0, 120).join('\n');
+    writeOutput(flags, {
+        target,
+        kind: 'file',
+        mode: 'offline',
+        lineCount: lines.length,
+        excerpt,
+    }, [`File: ${target}`, `Lines: ${lines.length}`, '', excerpt].join('\n'));
+}
+async function review(args, flags, session) {
+    const root = process.cwd();
+    ensureInitialized(root);
+    const prompt = args.join(' ').trim();
+    if (flags.triple && flags.remote) {
+        await performRemoteTripleReview(root, session, flags, prompt);
+        return;
+    }
+    if (flags.remote || flags.web) {
+        const bundle = createHandoffBundle(root, session, flags.remote ? 'remote_review' : 'web_review', prompt || 'review local diff');
+        writeOutput(flags, bundle, ['Pugi review handoff created', `Bundle: ${bundle.path}`].join('\n'));
+        return;
+    }
+    const artifactDir = createArtifactDir(root, prompt || 'review');
+    const reviewPath = resolve(artifactDir, flags.triple ? 'triple-review.md' : 'review.md');
+    const toolCallId = recordToolCall(session, 'artifact:review', prompt || 'local diff');
+    const status = safeGit(root, ['status', '--short']);
+    const diffStat = safeGit(root, ['diff', '--stat']);
+    const currentBranch = safeGit(root, ['branch', '--show-current']).trim() || 'unknown';
+    const mergeBase = safeGit(root, ['merge-base', 'HEAD', 'origin/main']).trim();
+    const branchDiffStat = mergeBase ? safeGit(root, ['diff', '--stat', `${mergeBase}..HEAD`]) : '';
+    const branchNameStatus = mergeBase ? safeGit(root, ['diff', '--name-status', `${mergeBase}..HEAD`]) : '';
+    const text = [
+        flags.triple ? '# Pugi Anvil Triple Review Request' : '# Pugi Local Review',
+        '',
+        prompt ? `Prompt: ${prompt}` : 'Prompt: review current local state',
+        flags.triple ? 'Gate: Anvil-backed triple-review for main merge readiness' : 'Gate: local review',
+        `Branch: ${currentBranch}`,
+        '',
+        '## Git Status',
+        '',
+        '```text',
+        status || 'clean',
+        '```',
+        '',
+        '## Diff Stat',
+        '',
+        '```text',
+        diffStat || 'no unstaged diff',
+        '```',
+        '',
+        ...(flags.triple
+            ? [
+                '## Branch Diff Against origin/main',
+                '',
+                '```text',
+                branchDiffStat || 'origin/main merge-base unavailable or no branch diff',
+                '```',
+                '',
+                '## Files Changed',
+                '',
+                '```text',
+                branchNameStatus || 'origin/main merge-base unavailable or no branch diff',
+                '```',
+                '',
+                '## Anvil Contract',
+                '',
+                '- Pugi CLI prepares evidence locally; Anvil runs the reviewer fan-out.',
+                '- Do not invoke Claude dev-only `/triple-review` from product runtime.',
+                '- Runtime review uses the same deterministic rubric as the Claude skill and OES MCP triple_review tool.',
+                '- Any P0 = BLOCK.',
+                '- P1 from two or more reviewers = BLOCK.',
+                '- P1 from one reviewer = WARN.',
+                '- No P0/P1 = PASS.',
+                '',
+                '## Reviewer Shape',
+                '',
+                '- Architecture reviewer: scope, module boundaries, migrations, contracts, blast radius.',
+                '- Security/reliability reviewer: auth, secrets, permissions, destructive ops, data loss, deploy risk.',
+                '- QA/regression reviewer: commands run, smoke path, acceptance criteria, rollback path.',
+                '',
+                '## Future Transport',
+                '',
+                '- Send this evidence bundle to Anvil review endpoint once CLI auth/transport is wired.',
+                '- Persist result in local `.pugi/artifacts` and server ledger.',
+                '- Feed merge readiness into the existing agent merge gate instead of trusting a client-side PASS claim.',
+                '',
+            ]
+            : []),
+        '## Review Checklist',
+        '',
+        '- Are acceptance criteria explicit?',
+        '- Are generated artifacts present?',
+        '- Were tests/lint/build run or explicitly deferred?',
+        '- Are secrets, env files, and destructive ops untouched?',
+        '- Is remote/web handoff needed for longer execution?',
+        '',
+        flags.triple
+            ? 'Status: block until Anvil triple-review returns PASS or a WARN is explicitly accepted.'
+            : 'Status: block until a model-backed or human review fills findings.',
+        '',
+    ].join('\n');
+    writeFileSync(reviewPath, text, { encoding: 'utf8', mode: 0o600 });
+    registerArtifact(root, {
+        id: artifactIdFromDir(artifactDir),
+        kind: flags.triple ? 'triple-review' : 'review',
+        path: relative(root, artifactDir),
+        sessionId: session.id,
+        createdAt: new Date().toISOString(),
+        files: [flags.triple ? 'triple-review.md' : 'review.md'],
+    });
+    recordToolResult(session, toolCallId, 'success', `Created review ${relative(root, reviewPath)}`);
+    writeOutput(flags, { status: 'created', review: relative(root, reviewPath) }, [
+        flags.triple ? 'Pugi Anvil triple-review request created' : 'Pugi local review created',
+        `Review: ${relative(root, reviewPath)}`,
+    ].join('\n'));
+}
+async function sync(_args, flags, session) {
+    const root = process.cwd();
+    ensureInitialized(root);
+    const settings = loadSettings(root);
+    const mode = flags.privacy ?? privacyModeFromSettings(settings.privacy.mode);
+    const createdAt = new Date().toISOString();
+    const dryRunPlan = pugiSyncDryRunPlanSchema.parse({
+        schema: 1,
+        createdAt,
+        mode,
+        uploadEnabled: false,
+        workspace: workspaceSnapshot(root),
+        items: buildSyncDryRunItems(root, mode),
+        exclusions: [
+            '.env',
+            '.env.*',
+            '*.pem',
+            '*.key',
+            '*.p12',
+            '*.sql',
+            '*.dump',
+            'node_modules/',
+            'dist/',
+            '.next/',
+            'coverage/',
+        ],
+        notes: [
+            'Local repository and .pugi/ remain the source of truth (ADR-0037).',
+            'Server sync is explicit continuation, not default storage.',
+            mode === 'full-sync'
+                ? 'full-sync is a future explicit opt-in and is not upload-enabled in this scaffold.'
+                : 'Raw file contents are excluded by default.',
+        ],
+    });
+    if (flags.dryRun) {
+        writeOutput(flags, { status: 'dry_run', plan: dryRunPlan }, [
+            'Pugi sync dry-run',
+            `Mode: ${dryRunPlan.mode}`,
+            'Upload: disabled (dry-run)',
+            '',
+            ...dryRunPlan.items.map((item) => `  ${item.action.toUpperCase()} ${item.kind} ${item.path} (${item.bytes} bytes) - ${item.reason}`),
+            '',
+            'No upload performed.',
+        ].join('\n'));
+        return;
+    }
+    await performRemoteSync(root, session, flags, dryRunPlan, createdAt, mode);
+}
+async function performRemoteSync(root, session, flags, dryRunPlan, createdAt, mode) {
+    const toolCallId = recordToolCall(session, 'sync:upload', `mode=${mode}`);
+    const config = resolveRuntimeConfig();
+    if (!config) {
+        recordToolResult(session, toolCallId, 'error', 'pugi sync requires login (PUGI_API_KEY or `pugi login`)');
+        writeOutput(flags, { status: 'unauthenticated', reason: 'no_credentials', plan: dryRunPlan }, [
+            'Pugi sync requires credentials.',
+            'Run `pugi login --token=<api-key>` or set PUGI_API_URL + PUGI_API_KEY in your environment.',
+            'Run `pugi sync --dry-run` to inspect the plan offline.',
+        ].join('\n'));
+        process.exitCode = 5;
+        return;
+    }
+    // Build the handoff bundle in-memory (no `.pugi/handoffs/*.json`
+    // side-effect — the server record IS the durable handoff). The
+    // operator can call `pugi handoff` separately for a local-only
+    // snapshot.
+    //
+    // Mix a randomUUID() suffix into the id so two `pugi sync`
+    // invocations in the same millisecond (CI parallelism, scripted
+    // retries) produce distinct `bundle.id` values — the
+    // server-side `clientId` column relies on them being unique
+    // for the "which server records correspond to my local
+    // handoff #foo" affordance.
+    const id = `${createdAt.replace(/[:.]/g, '-')}-sync-${randomUUID().slice(0, 8)}`;
+    const latest = latestArtifactDir(root);
+    const bundle = pugiHandoffBundleSchema.parse({
+        schema: 1,
+        id,
+        reason: `pugi sync (mode=${mode})`,
+        prompt: `Continue from the most recent Pugi session on ${workspaceSnapshot(root).rootName}.`,
+        createdAt,
+        workspace: workspaceSnapshot(root),
+        session: {
+            id: session.id,
+            eventsPath: relative(root, session.eventsPath),
+        },
+        artifacts: {
+            latest: latest ? relative(root, latest) : null,
+        },
+        privacy: {
+            includesFileContents: false,
+            includesSecrets: false,
+        },
+    });
+    const uploadPlan = pugiSyncUploadPlanSchema.parse({
+        ...dryRunPlan,
+        uploadEnabled: true,
+    });
+    const request = pugiSyncRequestSchema.parse({
+        schema: 1,
+        bundle,
+        plan: uploadPlan,
+    });
+    const result = await submitSync(config, request);
+    if (result.status === 'ok') {
+        recordToolResult(session, toolCallId, 'success', `sync ${result.response.syncId} status=${result.response.status}`);
+        writeOutput(flags, {
+            status: 'completed',
+            syncId: result.response.syncId,
+            syncStatus: result.response.status,
+            receivedAt: result.response.receivedAt,
+        }, [
+            `Pugi sync uploaded — server id ${result.response.syncId}`,
+            `Status: ${result.response.status} at ${result.response.receivedAt}`,
+            'Local repository and .pugi/ remain the source of truth (ADR-0037).',
+        ].join('\n'));
+        return;
+    }
+    const outcome = describeSyncFailure(result);
+    // SECURITY: do NOT persist the raw upstream body into the local
+    // session events log. If the runtime ever echoes the submitted
+    // prompt / reason / bundle fragment back in its 4xx/5xx body
+    // (NestJS BadRequestException echoes failing field values by
+    // default), this would leak the customer's prompt text to disk
+    // under `.pugi/sessions/.../events.jsonl`. The class-only
+    // `recordedMessage` carries the status class + HTTP code so the
+    // session log still proves the failure happened without exposing
+    // the upstream body. The verbose `message` goes to stdout/JSON
+    // output only, where it is operator-visible and ephemeral.
+    recordToolResult(session, toolCallId, 'error', outcome.recordedMessage);
+    writeOutput(flags, {
+        status: result.status,
+        code: 'code' in result ? result.code : undefined,
+        message: outcome.message,
+        plan: dryRunPlan,
+    }, [outcome.headline, outcome.next ? `Next: ${outcome.next}` : '']
+        .filter(Boolean)
+        .join('\n'));
+    process.exitCode = outcome.exitCode;
+}
+function describeSyncFailure(result) {
+    switch (result.status) {
+        case 'endpoint_missing':
+            return {
+                headline: 'Pugi runtime sync endpoint not deployed on this Anvil instance.',
+                message: result.message,
+                recordedMessage: 'sync: endpoint_missing (HTTP 404)',
+                next: 'Operator must deploy POST /api/pugi/sync on api.pugi.io (Phase 1 of explicit continuation).',
+                exitCode: 6,
+            };
+        case 'unauthenticated':
+            return {
+                headline: `Pugi runtime rejected credentials (HTTP ${result.code}).`,
+                message: result.message,
+                recordedMessage: `sync: unauthenticated (HTTP ${result.code})`,
+                next: 'Rotate PUGI_API_KEY or check tenant entitlement.',
+                exitCode: 5,
+            };
+        case 'rate_limited':
+            return {
+                headline: `Pugi runtime rate-limited the sync request (HTTP ${result.code}).`,
+                message: result.message,
+                recordedMessage: `sync: rate_limited (HTTP ${result.code})`,
+                next: `Retry after ${Math.round(result.retryAfterMs / 1000)}s.`,
+                exitCode: 7,
+            };
+        case 'failed':
+        default:
+            return {
+                headline: 'Pugi runtime sync failed.',
+                message: result.message,
+                // `code === 0` denotes a transport-layer error (network /
+                // AbortError); keep it out of the recorded line so the
+                // session log normalises to "sync: failed".
+                recordedMessage: `sync: failed${'code' in result && result.code > 0 ? ` (HTTP ${result.code})` : ''}`,
+                next: 'Run `pugi sync --dry-run` to inspect the plan and retry.',
+                exitCode: 8,
+            };
+    }
+}
+function resolveRuntimeConfig() {
+    // Prefer env-only path first so CI use cases keep their fast path.
+    const envConfig = loadRuntimeConfig();
+    if (envConfig)
+        return envConfig;
+    // Fall back to the local credentials store written by `pugi login`.
+    const credential = resolveActiveCredential();
+    if (!credential)
+        return null;
+    return buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey });
+}
+async function performRemoteTripleReview(root, session, flags, prompt) {
+    const config = resolveRuntimeConfig();
+    const artifactDir = createArtifactDir(root, prompt || 'triple-review');
+    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-remote', prompt || 'review branch diff');
+    const settings = loadSettings(root);
+    const baseRef = resolveBaseRef(root, settings);
+    // Compute the diff against the merge-base SHA so the review covers BOTH
+    // committed-since-base AND uncommitted (staged + working tree) changes.
+    // The previous shape `base...HEAD` used triple-dot range but only sent
+    // committed-since-base, hiding pre-commit edits in the most common
+    // review case ("review what I'm about to commit").
+    const mergeBaseSha = baseRef ? safeGit(root, ['merge-base', baseRef, 'HEAD']).trim() : '';
+    const diffRange = mergeBaseSha || 'HEAD';
+    // Exclude protected paths from the patch at the git layer so we cannot
+    // accidentally POST a tracked `.env` / `*.key` / `*.sql` to the runtime.
+    const diffArgs = ['diff', diffRange, '--', '.', ...PROTECTED_DIFF_EXCLUDES];
+    const diffStatArgs = ['diff', '--shortstat', diffRange, '--', '.', ...PROTECTED_DIFF_EXCLUDES];
+    const diffPatch = safeGit(root, diffArgs);
+    const diffStats = parseDiffStats(safeGit(root, diffStatArgs));
+    // Untracked files are not in `git diff`. Include their paths (NOT contents)
+    // so reviewers know the diff is incomplete. Protected basenames/suffixes
+    // are stripped from the list before egress.
+    const untracked = collectUntrackedSummary(root);
+    // Append an untracked summary so reviewers see the path of any new file
+    // that is dirty-but-not-yet-staged. Contents are never included; only
+    // path counts and a capped list.
+    const augmentedDiff = untracked.paths.length === 0 && untracked.excludedProtected === 0
+        ? diffPatch
+        : [
+            diffPatch,
+            '',
+            '## Untracked files (paths only, contents withheld)',
+            `Total visible: ${untracked.paths.length}`,
+            `Protected paths excluded: ${untracked.excludedProtected}`,
+            ...untracked.paths.map((p) => `- ${p}`),
+            '',
+        ].join('\n');
+    const requestBody = pugiTripleReviewRequestSchema.parse({
+        schema: 1,
+        workspace: {
+            rootName: root.split('/').at(-1) ?? 'workspace',
+            gitBranch: safeGit(root, ['branch', '--show-current']).trim() || null,
+            gitHead: safeGit(root, ['rev-parse', '--short', 'HEAD']).trim() || null,
+            baseRef,
+            dirty: Boolean(safeGit(root, ['status', '--short']).trim()),
+        },
+        diffPatch: augmentedDiff,
+        diffStats,
+        prompt: prompt || undefined,
+        locale: 'en-US',
+        reviewerPersona: 'oes-dev',
+    });
+    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-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 --remote\`.`,
+        ].join('\n'));
+        process.exitCode = 5;
+        return;
+    }
+    const submitResult = await submitTripleReview(config, requestBody);
+    if (submitResult.status === 'ok') {
+        persistTripleReviewResult(resultPath, submitResult.response);
+        writeFileSync(summaryPath, buildTripleReviewMarkdown({
+            prompt,
+            requestPath: relative(root, requestPath),
+            verdict: submitResult.response.verdict,
+            reason: submitResult.response.reason,
+            response: submitResult.response,
+        }), { encoding: 'utf8', mode: 0o600 });
+        recordToolResult(session, toolCallId, submitResult.response.verdict === 'BLOCK' ? 'error' : 'success', `Verdict: ${submitResult.response.verdict} (${submitResult.response.reason})`);
+        writeOutput(flags, {
+            status: 'completed',
+            verdict: submitResult.response.verdict,
+            reason: submitResult.response.reason,
+            counts: submitResult.response.counts,
+            reviewerCount: submitResult.response.reviewerCount,
+            effectiveTier: submitResult.response.effectiveTier,
+            result: relative(root, resultPath),
+            summary: relative(root, summaryPath),
+        }, [
+            `Pugi triple-review ${submitResult.response.verdict}: ${submitResult.response.reason}`,
+            `Reviewers: ${submitResult.response.reviewerCount} (tier ${submitResult.response.effectiveTier})`,
+            `Findings: P0=${submitResult.response.counts.P0} P1=${submitResult.response.counts.P1} P2=${submitResult.response.counts.P2} P3=${submitResult.response.counts.P3}`,
+            `Result: ${relative(root, resultPath)}`,
+            `Summary: ${relative(root, summaryPath)}`,
+        ].join('\n'));
+        if (submitResult.response.verdict === 'BLOCK') {
+            process.exitCode = 9;
+        }
+        return;
+    }
+    // Non-OK paths: persist local artifact noting outcome, surface actionable error.
+    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;
+}
+function describeSubmitFailure(result) {
+    switch (result.status) {
+        case 'endpoint_missing':
+            return {
+                headline: 'Pugi runtime triple-review endpoint not deployed on this Anvil instance.',
+                message: result.message,
+                next: 'Operator must deploy POST /api/pugi/triple-review on api.pugi.io (proxies to AnvilBridgeService.askPersona with the configured reviewer persona).',
+                exitCode: 6,
+            };
+        case 'unauthenticated':
+            return {
+                headline: `Pugi runtime rejected credentials (HTTP ${result.code}).`,
+                message: result.message,
+                next: 'Rotate PUGI_API_KEY or check tenant entitlement.',
+                exitCode: 5,
+            };
+        case 'rate_limited':
+            return {
+                headline: `Pugi runtime rate-limited the triple-review request (HTTP ${result.code}).`,
+                message: result.message,
+                next: `Retry after ${Math.round(result.retryAfterMs / 1000)}s or upgrade the tenant tier.`,
+                exitCode: 7,
+            };
+        case 'failed':
+            return {
+                headline: `Pugi runtime triple-review failed (HTTP ${result.code}).`,
+                message: result.message,
+                next: 'Inspect server logs and retry once the runtime stabilises.',
+                exitCode: 6,
+            };
+        case 'ok':
+            throw new Error('describeSubmitFailure called with ok status');
+    }
+}
+function persistTripleReviewResult(path, response) {
+    writeFileSync(path, `${JSON.stringify(response, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+function buildTripleReviewMarkdown(input) {
+    const { prompt, requestPath, verdict, reason, response } = input;
+    const header = verdict
+        ? `# Pugi Triple Review — ${verdict}`
+        : '# Pugi Triple Review — request prepared';
+    const lines = [
+        header,
+        '',
+        prompt ? `Prompt: ${prompt}` : 'Prompt: review branch diff vs origin/main',
+        `Reason: ${reason}`,
+        `Request: ${requestPath}`,
+        '',
+    ];
+    if (response) {
+        lines.push(`Reviewers: ${response.reviewerCount} (effective tier ${response.effectiveTier}${response.draft ? ', draft' : ''})`, `Findings: P0=${response.counts.P0} P1=${response.counts.P1} P2=${response.counts.P2} P3=${response.counts.P3}`, '', '## Findings', '');
+        if (response.findings.length === 0) {
+            lines.push('- No findings reported.');
+        }
+        else {
+            for (const finding of response.findings) {
+                const location = [
+                    finding.path ? finding.path : null,
+                    finding.line ? `line ${finding.line}` : null,
+                ]
+                    .filter(Boolean)
+                    .join(' ');
+                const fix = finding.fix ? ` Fix: ${finding.fix}` : '';
+                lines.push(`- [${finding.severity}] ${finding.reviewer}${location ? ` — ${location}` : ''} — ${finding.issue}${fix}`);
+            }
+        }
+        lines.push('', '## Reviewer Verdicts', '');
+        for (const reviewer of response.reviewers) {
+            const declared = reviewer.declaredVerdict ?? 'unknown';
+            lines.push(`- ${reviewer.model}: ${declared}${reviewer.error ? ` (error: ${reviewer.error})` : ''}`);
+        }
+    }
+    else {
+        lines.push('## Outcome', '', '- Local request artifact preserved.', '- Runtime call did not return a verdict.');
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function resolveBaseRef(root, settings) {
+    // Honor `workflow.defaultBaseBranch` from `.pugi/settings.json` (defaults
+    // to `dev` per `pugi init`). Without this the resolver only checks
+    // `origin/main`/`master` and silently submits an empty patch for any
+    // repo on a non-main integration branch.
+    const configured = settings?.workflow.defaultBaseBranch;
+    const candidates = [
+        configured ? `origin/${configured}` : null,
+        configured ?? null,
+        'origin/main',
+        'origin/master',
+        'main',
+        'master',
+    ].filter((value) => Boolean(value));
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        const mergeBase = safeGit(root, ['merge-base', 'HEAD', candidate]).trim();
+        if (mergeBase)
+            return candidate;
+    }
+    return null;
+}
+function parseDiffStats(raw) {
+    const stats = { filesChanged: 0, insertions: 0, deletions: 0 };
+    const filesMatch = raw.match(/(\d+)\s+files?\s+changed/);
+    if (filesMatch?.[1])
+        stats.filesChanged = Number.parseInt(filesMatch[1], 10);
+    const insMatch = raw.match(/(\d+)\s+insertions?/);
+    if (insMatch?.[1])
+        stats.insertions = Number.parseInt(insMatch[1], 10);
+    const delMatch = raw.match(/(\d+)\s+deletions?/);
+    if (delMatch?.[1])
+        stats.deletions = Number.parseInt(delMatch[1], 10);
+    return stats;
+}
+async function handoff(args, flags, session) {
+    const root = process.cwd();
+    ensureInitialized(root);
+    const reason = args[0] || 'web_continue';
+    const prompt = args.slice(1).join(' ').trim() || 'continue local Pugi session';
+    const bundle = createHandoffBundle(root, session, reason, prompt);
+    writeOutput(flags, bundle, ['Pugi handoff bundle created', `Bundle: ${bundle.path}`].join('\n'));
+}
+async function sessions(args, flags, _session) {
+    const root = process.cwd();
+    ensureInitialized(root);
+    const rebuild = args.includes('--rebuild');
+    let index = rebuild ? null : readIndex(root);
+    if (!index) {
+        index = rebuildIndex(root);
+        writeIndex(root, index);
+    }
+    else if (hasStubSession(index)) {
+        // `registerArtifact` writes minimal session placeholders to keep the
+        // hot path O(1). If any are still stubs (no commands recorded yet),
+        // opportunistically materialize them from `events.jsonl` so the
+        // default `pugi sessions` output isn't misleadingly empty. Users no
+        // longer need to know to pass `--rebuild`.
+        index = rebuildIndex(root);
+        writeIndex(root, index);
+    }
+    const sessionsView = index.sessions.slice(0, 10).map((session) => {
+        const artifactsForSession = index.artifacts.filter((artifact) => artifact.sessionId === session.id);
+        const lastCommand = session.commands.at(-1) ?? null;
+        return {
+            id: session.id,
+            startedAt: session.startedAt,
+            endedAt: session.endedAt,
+            commandCount: session.commandCount,
+            lastCommand: lastCommand
+                ? { command: lastCommand.command, status: lastCommand.status, timestamp: lastCommand.timestamp }
+                : null,
+            artifactCount: artifactsForSession.length,
+            latestArtifact: artifactsForSession[0]?.path ?? null,
+        };
+    });
+    const orphans = index.artifacts.filter((artifact) => !artifact.sessionId);
+    const handoffs = index.artifacts.filter((artifact) => artifact.kind === 'handoff');
+    const payload = {
+        root,
+        indexPath: '.pugi/index.json',
+        updatedAt: index.updatedAt,
+        sessions: sessionsView,
+        artifacts: index.artifacts.slice(0, 20),
+        orphanArtifacts: orphans.slice(0, 10),
+        handoffs: handoffs.slice(0, 10),
+        latestSession: sessionsView[0] ?? null,
+        latestArtifact: index.artifacts[0] ?? null,
+        latestHandoff: handoffs[0] ?? null,
+    };
+    writeOutput(flags, payload, [
+        'Pugi local sessions',
+        `Index: ${payload.indexPath} (updated ${payload.updatedAt})`,
+        '',
+        'Sessions:',
+        ...(sessionsView.length
+            ? sessionsView.map((session) => {
+                const lastCmd = session.lastCommand
+                    ? `${session.lastCommand.command} (${session.lastCommand.status})`
+                    : 'none';
+                return `  ${session.id}  cmds=${session.commandCount}  last=${lastCmd}  artifacts=${session.artifactCount}`;
+            })
+            : ['  none']),
+        '',
+        'Artifacts (latest 10):',
+        ...(index.artifacts.length
+            ? index.artifacts.slice(0, 10).map((artifact) => `  ${artifact.id}  kind=${artifact.kind}  session=${artifact.sessionId ?? 'orphan'}  files=${artifact.files.length}`)
+            : ['  none']),
+        '',
+        'Handoffs:',
+        ...(handoffs.length
+            ? handoffs.slice(0, 10).map((handoff) => `  ${handoff.id}  path=${handoff.path}`)
+            : ['  none']),
+    ].join('\n'));
+}
+function hasStubSession(index) {
+    return index.sessions.some((session) => session.commandCount === 0 && session.commands.length === 0);
+}
+function registerArtifact(root, artifact) {
+    // Hot path on every artifact-producing command. Avoid `rebuildIndex` here —
+    // that walks the entire `.pugi/artifacts/` tree and re-parses `events.jsonl`
+    // which is O(N) per command. Instead we read the existing index and inject
+    // a minimal session placeholder if needed; the next `pugi sessions` call
+    // (or `pugi sessions --rebuild`) materialises the full session record from
+    // `events.jsonl`.
+    const current = readIndex(root) ?? emptyIndex();
+    const needsSessionStub = Boolean(artifact.sessionId) &&
+        !current.sessions.some((session) => session.id === artifact.sessionId);
+    const withSession = needsSessionStub
+        ? {
+            ...current,
+            sessions: [
+                ...current.sessions,
+                {
+                    id: artifact.sessionId,
+                    startedAt: new Date().toISOString(),
+                    endedAt: null,
+                    commandCount: 0,
+                    commands: [],
+                    artifactIds: [],
+                },
+            ],
+        }
+        : current;
+    const updated = upsertArtifact(withSession, artifact);
+    writeIndex(root, updated);
+    return updated;
+}
+async function resume(args, flags, session) {
+    const root = process.cwd();
+    ensureInitialized(root);
+    const target = args[0];
+    const artifacts = listArtifactSets(root);
+    const selected = target
+        ? artifacts.find((artifact) => artifact.id === target || artifact.path.endsWith(target))
+        : artifacts[0];
+    if (!selected) {
+        throw new Error('No local Pugi artifact session found');
+    }
+    const resumeDir = createArtifactDir(root, `resume-${selected.id}`);
+    const resumePath = resolve(resumeDir, 'resume.md');
+    const toolCallId = recordToolCall(session, 'artifact:resume', selected.id);
+    const handoffHint = listHandoffBundles(root)[0] ?? null;
+    const text = [
+        '# Pugi Resume',
+        '',
+        `Resuming: ${selected.path}`,
+        handoffHint ? `Latest handoff: ${handoffHint.path}` : 'Latest handoff: none',
+        '',
+        '## Available Files',
+        '',
+        ...selected.files.map((file) => `- ${file}`),
+        '',
+        '## Next Local Actions',
+        '',
+        '- Inspect the selected artifact set.',
+        '- Continue with `pugi build`, `pugi review`, or `pugi handoff --web`.',
+        '- Use `pugi build --remote` only when local execution is insufficient.',
+        '',
+    ].join('\n');
+    writeFileSync(resumePath, text, { encoding: 'utf8', mode: 0o600 });
+    registerArtifact(root, {
+        id: artifactIdFromDir(resumeDir),
+        kind: 'resume',
+        path: relative(root, resumeDir),
+        sessionId: session.id,
+        createdAt: new Date().toISOString(),
+        files: ['resume.md'],
+    });
+    recordToolResult(session, toolCallId, 'success', `Created resume ${relative(root, resumePath)}`);
+    writeOutput(flags, { status: 'resumed', source: selected.path, resume: relative(root, resumePath) }, ['Pugi resume created', `Source: ${selected.path}`, `Resume: ${relative(root, resumePath)}`].join('\n'));
+}
+/**
+ * Per-command exit code map. Surfaced to the operator so shell scripts
+ * can branch on the engine outcome:
+ *   - 0 = done (model returned a final answer)
+ *   - 8 = failed (transport / runtime / unhandled adapter error)
+ *   - 9 = blocked (budget exhausted, plan-mode refusal, abort)
+ *
+ * 1 is reserved for the credential gate (engine_unavailable) so
+ * existing shell wrappers that branch on "any non-zero" still work.
+ */
+const ENGINE_EXIT_CODES = {
+    done: 0,
+    failed: 8,
+    blocked: 9,
+    engine_unavailable: 1,
+};
+function commandLabel(kind) {
+    return kind === 'build_task' ? 'build' : kind;
+}
+/**
+ * Sprint 2 Track A: wire `pugi code/explain/fix/plan/build` to the real
+ * `NativePugiEngineAdapter`. Each command:
+ *
+ *   1. Resolves the active credential (falls back to PUGI_API_KEY env).
+ *   2. Builds an `AnvilEngineLoopClient` against the resolved API URL.
+ *   3. Runs the adapter to completion; collects status + result events.
+ *   4. For `plan`: writes a `.pugi/artifacts/<slug>/plan.md` artifact
+ *      (and registers it in the local index) so the operator gets a
+ *      reviewable file, not just stdout.
+ *   5. Prints a summary (files modified, tool calls, token usage) and
+ *      sets `process.exitCode` per the table above.
+ *
+ * `--json` flag swaps the text summary for a JSON envelope that wraps
+ * every event + the headline metrics, so downstream tooling (cabinet UI,
+ * cron pipelines) can consume the run directly.
+ *
+ * Per memory `feedback_decide_defaults_proactively` the explicit `code`/
+ * `fix`/`build` commands require a prompt; `explain` accepts either a
+ * path or a prompt and `plan` accepts an empty prompt only when there is
+ * a previous artifact in `.pugi/artifacts/` to plan against.
+ */
+/**
+ * Test seam: when this module-scoped factory is set, every engine task
+ * invocation uses it to build the client instead of constructing an
+ * `AnvilEngineLoopClient` directly. The CLI exports `setEngineClientFactory`
+ * so unit tests can inject a `FixtureClient`; production code never
+ * sets it.
+ */
+let engineClientFactory = null;
+export function setEngineClientFactory(factory) {
+    engineClientFactory = factory;
+}
+function runEngineTask(kind) {
+    return async (args, flags, session) => {
+        const label = commandLabel(kind);
+        const root = process.cwd();
+        // `.pugi/` is created by `pugi init`. The engine writes the per-
+        // session events mirror under it, so we fail fast here instead of
+        // silently no-op'ing the mirror inside the adapter.
+        ensureInitialized(root);
+        const credential = resolveActiveCredential();
+        const envConfig = loadRuntimeConfig();
+        const config = credential
+            ? buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey })
+            : envConfig;
+        // 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)
+        // still gets reviewable artifacts. `code` and `fix` reject the
+        // offline path because the value proposition IS the engine —
+        // attempting them offline would produce nothing useful.
+        const isExplicitlyOffline = flags.offline;
+        const isImplicitlyOffline = !config && !flags.offline;
+        if (isExplicitlyOffline || isImplicitlyOffline) {
+            if (kind === 'code' || kind === 'fix') {
+                const reason = isExplicitlyOffline
+                    ? `pugi ${label} requires the engine — drop --offline or run \`pugi ${label}\` with credentials configured`
+                    : 'no Pugi credential configured — run `pugi login` or set PUGI_API_KEY before invoking the engine';
+                writeOutput(flags, { command: label, status: 'engine_unavailable', reason }, [`Pugi engine unavailable`, `Reason: ${reason}`].join('\n'));
+                process.exitCode = ENGINE_EXIT_CODES.engine_unavailable;
+                return;
+            }
+            if (kind === 'plan')
+                return offlinePlan(args, flags, session);
+            if (kind === 'build_task')
+                return offlineBuild(args, flags, session);
+            if (kind === 'explain')
+                return offlineExplain(args, flags, session);
+        }
+        // Engine path prompt gate. (Offline `explain` accepts a path as
+        // its first positional arg — that branch returned above before
+        // we reach this gate.)
+        //
+        // Code Reviewer P2 retro 2026-05-23: previously `pugi plan` with
+        // an empty prompt threw here (engine path) but the offline path
+        // accepted the empty prompt and synthesised a plan from the
+        // latest `.pugi/artifacts/` entry. The handler docstring
+        // documents the offline behaviour as canonical — engine should
+        // mirror it. For `code/fix/build/explain` an empty prompt is
+        // still an error (nothing to act on), but for `plan` we resynth
+        // the prompt from the most recent artifact if one exists,
+        // keeping the two paths aligned.
+        let prompt = args.join(' ').trim();
+        if (!prompt) {
+            if (kind === 'plan') {
+                const latest = latestArtifactDir(root);
+                if (latest) {
+                    prompt = `Continue planning from the previous artifact set at ${relative(root, latest)}`;
+                }
+                else {
+                    throw new Error('pugi plan requires a prompt or a previous artifact in .pugi/artifacts/');
+                }
+            }
+            else {
+                throw new Error(`pugi ${label} requires a prompt`);
+            }
+        }
+        // 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 });
+        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`);
+                }
+            }
+            else {
+                result = {
+                    status: event.result.status,
+                    summary: event.result.summary,
+                    filesChanged: event.result.filesChanged,
+                    eventRefs: event.result.eventRefs,
+                    risks: event.result.risks,
+                };
+            }
+        }
+        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'],
+            };
+        }
+        // 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;
+            }
+            else {
+                // `done`, or `blocked` with outcome=tool_refused (= the plan-mode
+                // gate fired, which is the contract working as designed), or
+                // `blocked` with no outcome echo (legacy adapter — preserve the
+                // pre-retro 0 behaviour to avoid breaking external scripts).
+                process.exitCode = 0;
+            }
+        }
+        else {
+            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,
+            // 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 (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'));
+    };
+}
+/**
+ * Extract `key=value` metrics from `EngineResult.eventRefs`. The adapter
+ * already emits the canonical strings (`tool_calls=N`, `turns=N`,
+ * `tokens=N`, `mirror=<path>`); parsing back to a typed object keeps the
+ * CLI from sprinkling regex-on-eventRefs across the handler.
+ */
+function parseEventRefs(refs) {
+    const out = {
+        toolCalls: 0,
+        turns: 0,
+        tokens: 0,
+        mirror: null,
+        outcome: null,
+    };
+    for (const ref of refs) {
+        const idx = ref.indexOf('=');
+        if (idx <= 0)
+            continue;
+        const key = ref.slice(0, idx);
+        const value = ref.slice(idx + 1);
+        if (key === 'tool_calls')
+            out.toolCalls = Number(value) || 0;
+        else if (key === 'turns')
+            out.turns = Number(value) || 0;
+        else if (key === 'tokens')
+            out.tokens = Number(value) || 0;
+        else if (key === 'mirror')
+            out.mirror = value || null;
+        else if (key === 'outcome')
+            out.outcome = value || null;
+    }
+    return out;
+}
+/**
+ * Write the `plan.md` artifact for `pugi plan`. The plan body wraps the
+ * model's final answer (or the refusal reason when the model attempted
+ * to write/edit/bash from plan mode) so the operator gets a single file
+ * to review, share, or attach to a handoff bundle.
+ */
+function writePlanArtifact(input) {
+    const { root, session, prompt, result, statusEvents } = input;
+    const artifactDir = createArtifactDir(root, prompt);
+    const planPath = resolve(artifactDir, 'plan.md');
+    const metrics = parseEventRefs(result.eventRefs);
+    const lines = [
+        '# Pugi Plan',
+        '',
+        `Prompt: ${prompt}`,
+        `Status: ${result.status}`,
+        `Generated: ${new Date().toISOString()}`,
+        '',
+        '## Plan',
+        '',
+        result.summary || '_(empty)_',
+        '',
+        '## Metrics',
+        '',
+        `- Tool calls: ${metrics.toolCalls}`,
+        `- Turns: ${metrics.turns}`,
+        `- Tokens: ${metrics.tokens}`,
+        `- Session: ${session.id}`,
+        '',
+    ];
+    if (result.risks.length > 0) {
+        lines.push('## Risks', '');
+        for (const risk of result.risks)
+            lines.push(`- ${risk}`);
+        lines.push('');
+    }
+    if (statusEvents.length > 0) {
+        lines.push('## Engine trace', '', '```text');
+        for (const event of statusEvents)
+            lines.push(event);
+        lines.push('```', '');
+    }
+    writeFileSync(planPath, lines.join('\n'), { encoding: 'utf8', mode: 0o600 });
+    registerArtifact(root, {
+        id: artifactIdFromDir(artifactDir),
+        kind: 'plan',
+        path: relative(root, artifactDir),
+        sessionId: session.id,
+        createdAt: new Date().toISOString(),
+        files: ['plan.md'],
+    });
+    return { path: planPath, relPath: relative(root, planPath) };
+}
+// `explain` previously walked the workspace locally with read/grep/glob
+// only. Sprint 2 Track A retired it; the engine adapter now drives the
+// read-only loop (`runEngineTask('explain')`) with the same tool subset.
+/**
+ * The three login providers `pugi login` knows how to dispatch to.
+ *
+ *   - `device` — RFC 8628 device authorization grant against the cabinet.
+ *   - `token` — paste a PAT (or pipe it via `--token-stdin`).
+ *   - `env`   — promote `PUGI_API_KEY` from the current environment into
+ *               the persistent store so subsequent commands work without
+ *               re-exporting.
+ */
+const PUGI_LOGIN_PROVIDERS = ['device', 'token', 'env'];
+function parseProviderFlag(args) {
+    const raw = extractNamedFlagValue(args, 'provider');
+    if (raw === undefined)
+        return undefined;
+    const lower = raw.toLowerCase();
+    if (!PUGI_LOGIN_PROVIDERS.includes(lower)) {
+        throw new Error(`pugi login --provider must be one of ${PUGI_LOGIN_PROVIDERS.join('|')}; got "${raw}".`);
+    }
+    return lower;
+}
+/**
+ * Returns true when stdin is attached to a TTY AND `--json` was not
+ * supplied. We only prompt interactively when the human is plausibly
+ * looking at the screen. The two-condition gate matches Claude Code,
+ * gh CLI, and Codex CLI conventions.
+ */
+function isInteractive(flags) {
+    if (flags.json)
+        return false;
+    // `process.stdin.isTTY` is `undefined` when stdin is a pipe (CI) and
+    // `true` when attached to a real terminal.
+    return Boolean(process.stdin.isTTY);
+}
+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 [options]',
+            '',
+            'Authenticate Pugi CLI against an Anvil instance.',
+            '',
+            'When run on a TTY with no arguments, Pugi shows an interactive picker',
+            'with three variants (browser OAuth, paste a key, use PUGI_API_KEY).',
+            '',
+            '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.',
+            '  --token <PAT>       Inline API key (visible in `ps`).',
+            '  --token-stdin       Read API key from stdin (gh-CLI style).',
+            '  --label <name>      Friendly label for `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.',
+            '',
+            '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',
+        ].join('\n'));
+        return;
+    }
+    // Login dispatch (highest precedence first):
+    //   1. `--provider device|token|env` — explicit non-interactive choice
+    //      for scripts. Bypasses both the menu and the env-only shortcut.
+    //   2. `--token <PAT>` / `--token-stdin` / PUGI_LOGIN_TOKEN — paste-token
+    //      fast path, identical to gh CLI's `gh auth login --with-token`.
+    //   3. Auto-mode: PUGI_LOGIN_TOKEN or PUGI_API_KEY is set AND stdin is
+    //      not a TTY (CI). Promote the env credential into the store
+    //      without prompting.
+    //   4. Interactive: stdin is a TTY → render a 3-item menu and let the
+    //      user pick. Default selection is browser-based device flow.
+    //   5. Non-interactive without a token (rare; e.g. nohup, no env) →
+    //      fall back to device flow unless `--no-device-flow` is set, in
+    //      which case raise a deterministic error.
+    const tokenFromArgs = extractTokenFlag(args);
+    const tokenStdinFlag = args.includes('--token-stdin');
+    const noDeviceFlow = args.includes('--no-device-flow');
+    const apiUrlOverride = extractApiUrlFlag(args);
+    const labelFlag = extractLabelFlag(args);
+    const provider = parseProviderFlag(args);
+    const apiUrl = normalizeApiUrl(apiUrlOverride ?? process.env.PUGI_API_URL ?? DEFAULT_API_URL);
+    // Path 1: explicit --provider trumps everything else.
+    if (provider) {
+        await dispatchLoginProvider(provider, {
+            apiUrl,
+            flags,
+            label: labelFlag,
+            explicitToken: tokenFromArgs,
+            tokenStdinFlag,
+            noDeviceFlow,
+        });
+        return;
+    }
+    // Path 2: token paste-in (CLI flag / stdin / env).
+    let explicitToken = tokenFromArgs ?? process.env.PUGI_LOGIN_TOKEN;
+    if (!explicitToken && tokenStdinFlag) {
+        explicitToken = readFileSync(0, 'utf8').trim();
+    }
+    if (explicitToken) {
+        storeAndAnnounceToken({
+            apiUrl,
+            apiKey: explicitToken,
+            label: labelFlag,
+            source: 'token',
+            flags,
+        });
+        return;
+    }
+    // Path 3: auto-mode (env primed + no TTY) — promote the env key into
+    // the store. This keeps CI deterministic and avoids stalling on the
+    // menu when there is no human at the terminal.
+    if (!isInteractive(flags) && process.env.PUGI_API_KEY) {
+        storeAndAnnounceToken({
+            apiUrl,
+            apiKey: process.env.PUGI_API_KEY,
+            label: labelFlag,
+            source: 'env',
+            flags,
+        });
+        return;
+    }
+    // Path 4: interactive menu (TTY, not --json, no token args).
+    if (isInteractive(flags)) {
+        const choice = await promptLoginVariant(apiUrl);
+        await dispatchLoginProvider(choice, {
+            apiUrl,
+            flags,
+            label: labelFlag,
+            noDeviceFlow,
+        });
+        return;
+    }
+    // Path 5: no token, no TTY → preserve existing behaviour (device flow
+    // unless explicitly opted out).
+    if (noDeviceFlow) {
+        throw new Error('pugi login requires a token under `--no-device-flow`. Pass `--token <PAT>`, pipe via `--token-stdin`, set PUGI_LOGIN_TOKEN, or use `--provider env` with PUGI_API_KEY exported.');
+    }
+    await performDeviceFlowLogin(apiUrl, flags, labelFlag);
+}
+/**
+ * Render the interactive picker shown when `pugi login` runs on a TTY
+ * with no token args. Reads a single digit from stdin and returns the
+ * provider keyword. Mirrors Claude Code's auth picker UX.
+ */
+async function promptLoginVariant(apiUrl) {
+    process.stderr.write([
+        '',
+        `How would you like to log in to Pugi? (endpoint: ${apiUrl})`,
+        '',
+        '  1) Browser-based OAuth (recommended) — opens app.pugi.io, you approve',
+        '  2) Paste an API key (PAT)',
+        '  3) Use PUGI_API_KEY from environment',
+        '',
+    ].join('\n'));
+    const answer = await readSingleChoice('Enter choice [1-3] (default 1): ');
+    switch (answer) {
+        case '':
+        case '1':
+            return 'device';
+        case '2':
+            return 'token';
+        case '3':
+            return 'env';
+        default:
+            throw new Error(`Invalid login choice "${answer}". Expected 1, 2, or 3.`);
+    }
+}
+/**
+ * Carry-over buffer between successive `readSingleChoice` calls. When
+ * the user pastes two prompt answers into stdin at once
+ * ("2\nsk-token-xyz\n") the first invocation consumes only up to the
+ * first newline; the rest survives here so the next call returns
+ * "sk-token-xyz" instead of stalling on a closed pipe.
+ */
+let stdinReadBuffer = '';
+/**
+ * Single-line prompt → trimmed answer. Used for menu picks where we
+ * just need a digit (or empty for the default). Reads directly from
+ * stdin so the surrounding `--json` mode (which would short-circuit
+ * `isInteractive`) cannot accidentally consume the prompt.
+ *
+ * Keeps the implementation dependency-free by reading bytes from fd 0
+ * until the first newline. Avoids pulling in `readline` to keep the
+ * CLI startup cheap.
+ *
+ * If the carry-over buffer (`stdinReadBuffer`) already contains a
+ * newline we resolve synchronously — that handles piped multi-answer
+ * input correctly (`printf '2\\nsk-xyz\\n' | pugi login`).
+ */
+async function readSingleChoice(prompt) {
+    process.stderr.write(prompt);
+    // Drain any leftover bytes from a previous prompt before re-attaching
+    // a listener. This keeps the CLI usable from `here-doc` style scripts.
+    const existingNewline = stdinReadBuffer.indexOf('\n');
+    if (existingNewline >= 0) {
+        const answer = stdinReadBuffer.slice(0, existingNewline).trim();
+        stdinReadBuffer = stdinReadBuffer.slice(existingNewline + 1);
+        return answer;
+    }
+    return new Promise((resolveLine, rejectLine) => {
+        const onData = (chunk) => {
+            const text = chunk.toString('utf8');
+            stdinReadBuffer += text;
+            const newlineIndex = stdinReadBuffer.indexOf('\n');
+            if (newlineIndex >= 0) {
+                const answer = stdinReadBuffer.slice(0, newlineIndex).trim();
+                stdinReadBuffer = stdinReadBuffer.slice(newlineIndex + 1);
+                cleanup();
+                resolveLine(answer);
+            }
+        };
+        const onError = (err) => {
+            cleanup();
+            rejectLine(err);
+        };
+        const onEnd = () => {
+            cleanup();
+            // EOF reached mid-prompt — treat the carry-over as the final
+            // answer so a script that omits the trailing newline still works.
+            const tail = stdinReadBuffer;
+            stdinReadBuffer = '';
+            resolveLine(tail.trim());
+        };
+        const cleanup = () => {
+            process.stdin.removeListener('data', onData);
+            process.stdin.removeListener('error', onError);
+            process.stdin.removeListener('end', onEnd);
+            // Stop reading so the parent process does not hold stdin open.
+            if (typeof process.stdin.pause === 'function') {
+                process.stdin.pause();
+            }
+        };
+        process.stdin.on('data', onData);
+        process.stdin.on('error', onError);
+        process.stdin.on('end', onEnd);
+        if (typeof process.stdin.resume === 'function') {
+            process.stdin.resume();
+        }
+    });
+}
+/**
+ * No-echo TTY read for a single secret line. Used by `pugi login` to
+ * prompt for an API key without leaking it into shell scrollback /
+ * terminal recordings. Falls back to `readSingleChoice` (echoing) when
+ * stdin is not a TTY — pipe sources have no echo to suppress.
+ *
+ * Implementation pinned to Node's `tty.ReadStream.setRawMode` which is
+ * stable across Node 20+. We toggle raw mode + isRaw, read bytes
+ * char-by-char until \n, and emit `*` per byte for visual progress.
+ * Pasted multi-char chunks are masked uniformly.
+ */
+async function readSecretLine(prompt) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+        // Non-TTY (test harness, piped input). Fall back to the
+        // line-buffered reader; the absence of a real terminal means
+        // there is no echo to suppress in the first place.
+        return readSingleChoice(prompt);
+    }
+    process.stderr.write(prompt);
+    return new Promise((resolveLine, rejectLine) => {
+        let collected = '';
+        const onData = (chunk) => {
+            const text = chunk.toString('utf8');
+            for (const ch of text) {
+                const code = ch.charCodeAt(0);
+                if (ch === '\n' || ch === '\r') {
+                    process.stderr.write('\n');
+                    cleanup();
+                    resolveLine(collected.trim());
+                    return;
+                }
+                if (code === 0x03) {
+                    // Ctrl-C — abort.
+                    cleanup();
+                    process.stderr.write('\n');
+                    rejectLine(new Error('pugi login: aborted by user'));
+                    return;
+                }
+                if (code === 0x7f || code === 0x08) {
+                    // Backspace / DEL — drop last char.
+                    if (collected.length > 0) {
+                        collected = collected.slice(0, -1);
+                        process.stderr.write('\b \b');
+                    }
+                    continue;
+                }
+                if (code < 0x20) {
+                    // Other control codes — ignore.
+                    continue;
+                }
+                collected += ch;
+                process.stderr.write('*');
+            }
+        };
+        const onError = (err) => {
+            cleanup();
+            rejectLine(err);
+        };
+        const cleanup = () => {
+            stdin.removeListener('data', onData);
+            stdin.removeListener('error', onError);
+            stdin.setRawMode?.(false);
+            stdin.pause?.();
+        };
+        stdin.setRawMode?.(true);
+        stdin.resume?.();
+        stdin.on('data', onData);
+        stdin.on('error', onError);
+    });
+}
+async function dispatchLoginProvider(provider, ctx) {
+    switch (provider) {
+        case 'device': {
+            if (ctx.noDeviceFlow) {
+                throw new Error('pugi login --provider device conflicts with --no-device-flow. Drop one of the two.');
+            }
+            await performDeviceFlowLogin(ctx.apiUrl, ctx.flags, ctx.label);
+            return;
+        }
+        case 'token': {
+            // P2 fix Code Reviewer 2026-05-23: an explicit interactive
+            // `--provider token` should NOT silently inherit
+            // `PUGI_LOGIN_TOKEN` from env — the operator who typed the
+            // flag wants the prompt. Only honour the env var on the
+            // non-interactive path (CI shells) where there is no prompt
+            // surface to override.
+            const isInteractiveToken = isInteractive(ctx.flags);
+            let token = ctx.explicitToken ?? (isInteractiveToken ? undefined : process.env.PUGI_LOGIN_TOKEN);
+            if (!token && ctx.tokenStdinFlag) {
+                token = readFileSync(0, 'utf8').trim();
+            }
+            if (!token) {
+                // No-echo TTY read for the PAT prompt. Pasted secret never
+                // lands in shell scrollback / terminal recordings. Code
+                // Reviewer P1 2026-05-23: previous echoing prompt was a
+                // secret-handling regression vs gh CLI / npm login / aws
+                // configure.
+                if (isInteractiveToken) {
+                    token = await readSecretLine('Paste your Pugi API key (PAT): ');
+                }
+            }
+            if (!token) {
+                throw new Error('pugi login --provider token requires a key. Pass `--token <PAT>`, pipe via `--token-stdin`, or set PUGI_LOGIN_TOKEN.');
+            }
+            storeAndAnnounceToken({
+                apiUrl: ctx.apiUrl,
+                apiKey: token,
+                label: ctx.label,
+                source: 'token',
+                flags: ctx.flags,
+            });
+            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.');
+            }
+            storeAndAnnounceToken({
+                apiUrl: ctx.apiUrl,
+                apiKey: envKey,
+                label: ctx.label,
+                source: 'env',
+                flags: ctx.flags,
+            });
+            return;
+        }
+        default: {
+            // Type-level exhaustiveness check — adding a new provider without
+            // updating this switch becomes a compile error.
+            const exhaustive = provider;
+            throw new Error(`Unhandled login provider: ${String(exhaustive)}`);
+        }
+    }
+}
+function storeAndAnnounceToken(input) {
+    const record = storeApiKey({
+        apiUrl: input.apiUrl,
+        apiKey: input.apiKey,
+        label: input.label,
+        source: input.source,
+    });
+    writeOutput(input.flags, {
+        status: 'logged_in',
+        apiUrl: record.apiUrl,
+        apiKeyMasked: maskApiKey(record.apiKey),
+        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'));
+}
+/**
+ * OAuth 2.0 Device Authorization Grant client (RFC 8628). Renders
+ * progress to stderr so the user sees the verification URL and code
+ * even when `--json` redirects stdout to a file. Polls every
+ * `interval` seconds until the runtime returns authorized / denied /
+ * expired. Stores the issued JWT into the credentials store on
+ * success.
+ *
+ * Local-first contract: device flow only runs when the user invokes
+ * `pugi login` without a token AND without `--no-device-flow`. The
+ * CLI itself never reads files during this flow (the JWT and the
+ * verification URL are the only state). Polling is wall-clock,
+ * not retries-on-error; transient HTTP failures abort with a
+ * clear error.
+ */
+async function performDeviceFlowLogin(apiUrl, flags, label) {
+    process.stderr.write(`Pugi device-flow login at ${apiUrl}\n`);
+    const startResult = await startDeviceFlow(apiUrl);
+    if (startResult.status !== 'ok') {
+        const failure = describeDeviceFlowFailure(startResult, 'start');
+        writeOutput(flags, {
+            status: failure.status,
+            code: 'code' in startResult ? startResult.code : undefined,
+            message: failure.message,
+        }, [failure.headline, failure.next ? `Next: ${failure.next}` : '']
+            .filter(Boolean)
+            .join('\n'));
+        process.exitCode = failure.exitCode;
+        return;
+    }
+    const start = startResult.response;
+    // Surface the user-visible parts to stderr so JSON consumers on
+    // stdout are unaffected. The deviceCode itself is NEVER printed —
+    // it is the secret poll handle.
+    process.stderr.write([
+        '',
+        `1. Open this URL in your browser: ${start.verification_uri}`,
+        `2. Enter this code: ${start.user_code}`,
+        `   (or use the complete link: ${start.verification_uri_complete})`,
+        `3. Approve the request when prompted.`,
+        '',
+        `Polling every ${start.interval}s, expires in ${start.expires_in}s...`,
+        '',
+    ].join('\n'));
+    // Hard local cap on the polling deadline so a hostile or buggy
+    // runtime returning an absurdly large `expires_in` cannot trap
+    // the CLI in a long-running poll. The SDK schema already caps
+    // `expires_in` at 3600s, but enforce the floor here too — the
+    // SDK contract is what we own, and a future broadening must
+    // still respect this local maximum.
+    const PUGI_DEVICE_FLOW_DEADLINE_MAX_SEC = 60 * 60; // 1 hour
+    const expiresInSec = Math.min(start.expires_in, PUGI_DEVICE_FLOW_DEADLINE_MAX_SEC);
+    const deadline = Date.now() + expiresInSec * 1000;
+    const pollInterval = start.interval;
+    while (Date.now() < deadline) {
+        await sleep(pollInterval * 1000);
+        const pollResult = await pollDeviceFlow(apiUrl, start.device_code);
+        if (pollResult.status !== 'ok') {
+            const failure = describeDeviceFlowFailure(pollResult, 'poll');
+            writeOutput(flags, {
+                status: failure.status,
+                code: 'code' in pollResult ? pollResult.code : undefined,
+                message: failure.message,
+            }, [failure.headline, failure.next ? `Next: ${failure.next}` : '']
+                .filter(Boolean)
+                .join('\n'));
+            process.exitCode = failure.exitCode;
+            return;
+        }
+        const outcome = pollResult.response;
+        if (outcome.status === 'authorized') {
+            const record = storeApiKey({
+                apiUrl,
+                apiKey: outcome.access_token,
+                label: label ?? undefined,
+                source: 'device-flow',
+            });
+            // Defense-in-depth against the device-flow phishing class
+            // (P0, 2026-05-22 review): decode the JWT we just received
+            // and surface the principal identity to the user so they
+            // can confirm we landed in the expected tenant. Cabinet UI
+            // alone showing "you are about to grant access" is not
+            // enough — a phisher who tricked the victim into reading
+            // out a userCode would have approved on their own account
+            // and the JWT would silently authenticate the victim's CLI
+            // as the attacker. By showing the user/tenant on the CLI,
+            // the victim sees the mismatch before any sensitive
+            // operation runs.
+            const principal = decodeJwtPrincipal(outcome.access_token);
+            writeOutput(flags, {
+                status: 'logged_in',
+                apiUrl: record.apiUrl,
+                apiKeyMasked: maskApiKey(record.apiKey),
+                label: record.label ?? null,
+                createdAt: record.createdAt,
+                via: 'device-flow',
+                principal,
+            }, [
+                `Pugi logged in for ${record.apiUrl} via device flow`,
+                `Token: ${maskApiKey(record.apiKey)}${record.label ? ` (${record.label})` : ''}`,
+                principal
+                    ? `Authenticated as user=${principal.email ?? principal.sub} tenant=${principal.customerId ?? '(unknown)'}.`
+                    : 'Authenticated (JWT payload could not be decoded for principal display).',
+                'If this is NOT the user/tenant you expected, run `pugi logout` immediately and re-check the verification URL.',
+                'Stored at ~/.pugi/credentials.json (mode 0600). Run `pugi whoami` to verify.',
+            ].join('\n'));
+            return;
+        }
+        if (outcome.status === 'denied') {
+            writeOutput(flags, { status: 'denied' }, 'Pugi device flow denied. The cabinet user clicked Deny.');
+            process.exitCode = 5;
+            return;
+        }
+        if (outcome.status === 'expired' || outcome.status === 'redeemed') {
+            writeOutput(flags, { status: outcome.status }, outcome.status === 'expired'
+                ? 'Pugi device flow expired before approval. Run `pugi login` again.'
+                : 'Pugi device flow already redeemed by another CLI. Run `pugi login` to start a fresh flow.');
+            process.exitCode = 5;
+            return;
+        }
+        // status === 'pending' — keep polling
+    }
+    writeOutput(flags, { status: 'expired' }, 'Pugi device flow timed out locally. Run `pugi login` again.');
+    process.exitCode = 5;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Best-effort JWT payload decode for principal display ONLY. Does
+ * NOT verify the signature — that's not the CLI's role (the server
+ * is the trust anchor for the JWT it just issued). The decoded
+ * fields are surfaced to the user so they can confirm the resulting
+ * authentication matches the tenant they expected.
+ *
+ * Returns `null` on any parse error so the caller falls back to a
+ * generic "authenticated" message.
+ */
+function decodeJwtPrincipal(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length < 2)
+            return null;
+        const payload = parts[1];
+        if (!payload)
+            return null;
+        // base64url → base64
+        const padded = payload.replace(/-/g, '+').replace(/_/g, '/').padEnd(payload.length + ((4 - (payload.length % 4)) % 4), '=');
+        const json = Buffer.from(padded, 'base64').toString('utf8');
+        const obj = JSON.parse(json);
+        if (!obj || typeof obj !== 'object')
+            return null;
+        return {
+            sub: typeof obj.sub === 'string' ? obj.sub : undefined,
+            email: typeof obj.email === 'string' ? obj.email : undefined,
+            customerId: typeof obj.customerId === 'string' ? obj.customerId : undefined,
+            role: typeof obj.role === 'string' ? obj.role : undefined,
+            via: typeof obj.via === 'string' ? obj.via : undefined,
+            plan: typeof obj.plan === 'string' ? obj.plan : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function describeDeviceFlowFailure(result, stage) {
+    switch (result.status) {
+        case 'endpoint_missing':
+            return {
+                status: 'endpoint_missing',
+                headline: `Pugi device-flow ${stage} endpoint not deployed on this runtime.`,
+                message: result.message,
+                next: 'Use `pugi login --token <PAT>` until the operator deploys POST /api/auth/device/* on this Anvil instance.',
+                exitCode: 6,
+            };
+        case 'failed':
+        default:
+            return {
+                status: 'failed',
+                headline: `Pugi device-flow ${stage} failed.`,
+                message: result.message,
+                next: 'Use `pugi login --token <PAT>` or check network connectivity.',
+                exitCode: 8,
+            };
+    }
+}
+async function logout(args, flags, _session) {
+    const all = args.includes('--all');
+    if (all) {
+        const removed = purgeAllCredentials();
+        writeOutput(flags, { status: 'logged_out_all', removed }, removed ? 'All Pugi credentials cleared.' : 'No Pugi credentials were stored.');
+        return;
+    }
+    const apiUrlOverride = extractApiUrlFlag(args);
+    // Use the same resolution precedence as `whoami` so `pugi login --api-url X`
+    // followed by `pugi logout` clears the self-hosted credential the user
+    // just authenticated against. Falls back to DEFAULT_API_URL only when
+    // neither env nor active record names a host.
+    const file = readCredentialsFile();
+    const apiUrl = normalizeApiUrl(apiUrlOverride ?? process.env.PUGI_API_URL ?? file.activeApiUrl ?? DEFAULT_API_URL);
+    const removed = clearApiKey(apiUrl);
+    writeOutput(flags, { status: removed ? 'logged_out' : 'noop', apiUrl, removed }, removed
+        ? `Pugi logged out from ${apiUrl}.`
+        : `No credential stored for ${apiUrl} — nothing to clear.`);
+}
+async function whoami(_args, flags, _session) {
+    const credential = resolveActiveCredential();
+    if (!credential) {
+        // Surface the same activeApiUrl precedence the resolver uses so the
+        // user sees which host they would be talking to before logging in.
+        const file = readCredentialsFile();
+        const apiUrl = normalizeApiUrl(process.env.PUGI_API_URL ?? file.activeApiUrl ?? DEFAULT_API_URL);
+        writeOutput(flags, { status: 'anonymous', apiUrl }, [
+            'Pugi is not logged in.',
+            `Active API endpoint: ${apiUrl}`,
+            'Run `pugi login` to start (interactive) or `pugi login --provider token --token <PAT>`.',
+        ].join('\n'));
+        process.exitCode = 5;
+        return;
+    }
+    // Decode the JWT principal for display only — the server is the trust
+    // anchor for signature verification, the CLI surfaces what it sees so
+    // the user can spot a wrong-tenant credential before running a tool.
+    const principal = decodeJwtPrincipal(credential.apiKey);
+    const via = describeLoginMethod(credential);
+    const plan = principal && 'plan' in principal ? String(principal.plan ?? '') : '';
+    // Sprint 3A: fetch the current-month usage via /api/pugi/usage. Best
+    // effort, 4 s timeout — a slow / unreachable admin-api never blocks
+    // `pugi whoami` from rendering the local credential info. The usage
+    // payload, when present, lets us render "Plan: Founder ($20/mo) —
+    // 12/100 reviews used this month (resets in 18d)".
+    const usage = await fetchUsageSafely(credential);
+    const payload = {
+        status: 'authenticated',
+        apiUrl: credential.apiUrl,
+        source: credential.source,
+        via,
+        label: credential.label ?? null,
+        apiKeyMasked: maskApiKey(credential.apiKey),
+        createdAt: credential.createdAt ?? null,
+        lastUsedAt: credential.lastUsedAt ?? null,
+        cliVersion: PUGI_CLI_VERSION,
+        account: principal
+            ? {
+                email: principal.email ?? null,
+                sub: principal.sub ?? null,
+                role: principal.role ?? null,
+                customerId: principal.customerId ?? null,
+                plan: plan || null,
+            }
+            : null,
+        usage: usage ?? null,
+    };
+    const text = [
+        `Pugi authenticated against ${credential.apiUrl}`,
+        `via: ${via}${credential.label ? ` (${credential.label})` : ''}`,
+        `Token: ${maskApiKey(credential.apiKey)}`,
+        principal?.email || principal?.sub
+            ? `Account: ${principal.email ?? principal.sub}${principal.role ? ` (${principal.role})` : ''}`
+            : null,
+        principal?.customerId ? `Tenant: ${principal.customerId}` : null,
+        formatPlanLine(usage, plan),
+        formatUsageLine(usage),
+    ]
+        .filter((line) => Boolean(line))
+        .join('\n');
+    writeOutput(flags, payload, text);
+}
+/**
+ * Map a tier slug to its public price tag for the `pugi whoami` plan
+ * line. Mirrors the four-tier ladder in admin-api/billing/pricing.ts;
+ * kept in sync via the pricing.spec.ts gate.
+ */
+const TIER_PRICE_LABEL = {
+    free: 'Free',
+    founder: 'Founder ($20/mo)',
+    builder: 'Builder ($99/mo)',
+    team: 'Team ($199/mo)',
+};
+function fetchUsageSafely(credential) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 4000);
+    return (async () => {
+        try {
+            const res = await fetch(`${credential.apiUrl}/api/pugi/usage`, {
+                method: 'GET',
+                headers: {
+                    authorization: `Bearer ${credential.apiKey}`,
+                    accept: 'application/json',
+                },
+                signal: controller.signal,
+            });
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            // Defensive shape check — older admin-api versions may not yet
+            // expose this surface, in which case we silently degrade.
+            if (body &&
+                typeof body === 'object' &&
+                typeof body.tier === 'string' &&
+                body.used &&
+                body.quotas) {
+                return body;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    })();
+}
+function formatPlanLine(usage, jwtPlan) {
+    if (usage) {
+        return `Plan: ${TIER_PRICE_LABEL[usage.tier] ?? usage.tier}`;
+    }
+    if (jwtPlan)
+        return `Plan: ${jwtPlan}`;
+    return null;
+}
+function formatUsageLine(usage) {
+    if (!usage)
+        return null;
+    const r = formatDimension(usage.used.review, usage.quotas.review, 'reviews');
+    const s = formatDimension(usage.used.sync, usage.quotas.sync, 'syncs');
+    const e = formatDimension(usage.used.engine, usage.quotas.engine, 'engine turns');
+    const resetSuffix = formatResetSuffix(usage.resetAt);
+    return [`Usage: ${r} · ${s} · ${e}`, resetSuffix].filter(Boolean).join(' ');
+}
+function formatDimension(used, limit, label) {
+    if (limit === null)
+        return `${used} ${label} (unlimited)`;
+    return `${used}/${limit} ${label}`;
+}
+function formatResetSuffix(resetAtIso) {
+    const parsed = Date.parse(resetAtIso);
+    if (!Number.isFinite(parsed))
+        return '';
+    const diffMs = parsed - Date.now();
+    if (diffMs <= 0)
+        return '(resetting now)';
+    const days = Math.max(1, Math.round(diffMs / (24 * 60 * 60 * 1000)));
+    return `(resets in ${days}d)`;
+}
+/**
+ * Render the login-method label shown in `pugi whoami` and emitted in
+ * the JSON envelope. Aliases the resolver's `source` discriminator (env
+ * vs file) plus the stored `fileSource` (token vs device-flow vs env
+ * promotion) into a single human-friendly word.
+ */
+function describeLoginMethod(credential) {
+    if (credential.source === 'env')
+        return 'env';
+    switch (credential.fileSource) {
+        case 'device-flow':
+            return 'device-flow';
+        case 'token':
+            return 'token';
+        case 'env':
+            return 'env-promoted';
+        default:
+            return 'token';
+    }
+}
+/**
+ * `pugi accounts <list|switch|remove>` — manage stored credentials
+ * across multiple Pugi hosts (api.pugi.io, self-hosted Anvil, dev
+ * cabinet, etc.).
+ *
+ * `accounts list` — show every stored record with masked key, label,
+ * source, lastUsed, and whether it is the active one.
+ * `accounts switch <label-or-url>` — re-point `activeApiUrl` so
+ * subsequent commands authenticate against the chosen account.
+ * `accounts remove <label-or-url>` — delete a stored credential.
+ *
+ * The sub-verb is a positional, matching `gh auth <verb>` ergonomics.
+ */
+async function accounts(args, flags, _session) {
+    const subCommand = args[0];
+    if (!subCommand || subCommand === '--help' || subCommand === '-h') {
+        writeOutput(flags, {
+            command: 'accounts',
+            usage: [
+                'pugi accounts list',
+                'pugi accounts switch <label-or-url>',
+                'pugi accounts remove <label-or-url>',
+            ],
+        }, [
+            'Usage:',
+            '  pugi accounts list                  Show every stored credential.',
+            '  pugi accounts switch <label|url>    Set the active account.',
+            '  pugi accounts remove <label|url>    Delete a stored credential.',
+        ].join('\n'));
+        return;
+    }
+    const rest = args.slice(1);
+    switch (subCommand) {
+        case 'list':
+            return accountsList(flags);
+        case 'switch':
+            return accountsSwitch(rest, flags);
+        case 'remove':
+        case 'rm':
+            return accountsRemove(rest, flags);
+        default:
+            throw new Error(`Unknown sub-command "pugi accounts ${subCommand}". Expected list, switch, or remove.`);
+    }
+}
+function accountsList(flags) {
+    const records = listStoredCredentials();
+    if (records.length === 0) {
+        writeOutput(flags, { status: 'empty', accounts: [] }, 'No Pugi accounts stored. Run `pugi login` to add one.');
+        return;
+    }
+    const payload = {
+        status: 'ok',
+        accounts: records.map((record) => ({
+            apiUrl: record.apiUrl,
+            label: record.label ?? null,
+            apiKeyMasked: maskApiKey(record.apiKey),
+            source: record.source ?? null,
+            createdAt: record.createdAt,
+            lastUsedAt: record.lastUsedAt ?? null,
+            isActive: record.isActive,
+        })),
+    };
+    const text = [
+        'Stored Pugi accounts:',
+        '',
+        ...records.map((record) => {
+            const star = record.isActive ? '*' : ' ';
+            const label = record.label ?? '(unlabelled)';
+            const last = record.lastUsedAt ?? record.createdAt;
+            const source = record.source ?? 'unknown';
+            return `${star} ${label.padEnd(20)} ${record.apiUrl.padEnd(32)} ${maskApiKey(record.apiKey)} ${source.padEnd(12)} last:${last}`;
+        }),
+        '',
+        'Switch active account: pugi accounts switch <label>',
+    ].join('\n');
+    writeOutput(flags, payload, text);
+}
+function accountsSwitch(args, flags) {
+    const selector = args[0];
+    if (!selector) {
+        throw new Error('pugi accounts switch requires a label or apiUrl. Run `pugi accounts list` to see candidates.');
+    }
+    const next = switchActiveAccount(selector);
+    if (!next) {
+        writeOutput(flags, { status: 'not_found', selector }, `No stored account matches "${selector}". Run \`pugi accounts list\` to see candidates.`);
+        process.exitCode = 5;
+        return;
+    }
+    writeOutput(flags, {
+        status: 'switched',
+        apiUrl: next.apiUrl,
+        label: next.label ?? null,
+        apiKeyMasked: maskApiKey(next.apiKey),
+    }, [
+        `Active account is now ${next.label ?? next.apiUrl}`,
+        `Endpoint: ${next.apiUrl}`,
+        `Token: ${maskApiKey(next.apiKey)}`,
+    ].join('\n'));
+}
+function accountsRemove(args, flags) {
+    const selector = args[0];
+    if (!selector) {
+        throw new Error('pugi accounts remove requires a label or apiUrl.');
+    }
+    // Map label → apiUrl when a label is supplied; clearApiKey takes a
+    // canonicalised url.
+    const records = listStoredCredentials();
+    const lower = selector.toLowerCase();
+    const target = records.find((record) => record.label && record.label.toLowerCase() === lower)?.apiUrl ??
+        selector;
+    const removed = clearApiKey(target);
+    if (!removed) {
+        writeOutput(flags, { status: 'not_found', selector }, `No stored account matches "${selector}".`);
+        process.exitCode = 5;
+        return;
+    }
+    writeOutput(flags, { status: 'removed', selector, apiUrl: normalizeApiUrl(target) }, `Pugi credential for ${normalizeApiUrl(target)} removed.`);
+}
+function extractNamedFlagValue(args, flagName) {
+    const space = `--${flagName}`;
+    const equals = `--${flagName}=`;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === space) {
+            const next = args[i + 1];
+            // Refuse the next arg if it looks like another flag — otherwise
+            // `--token --api-url …` silently stores the literal string
+            // "--api-url" as the token. `pugi login --token` (last arg)
+            // returns undefined and falls through to PUGI_LOGIN_TOKEN.
+            if (!next || next.startsWith('--'))
+                return undefined;
+            return next;
+        }
+        if (arg.startsWith(equals))
+            return arg.slice(equals.length);
+    }
+    return undefined;
+}
+function extractTokenFlag(args) {
+    return extractNamedFlagValue(args, 'token');
+}
+function extractApiUrlFlag(args) {
+    return extractNamedFlagValue(args, 'api-url');
+}
+function extractLabelFlag(args) {
+    return extractNamedFlagValue(args, 'label');
+}
+function notImplemented(command) {
+    return async (_args, flags) => {
+        const payload = {
+            command,
+            status: 'not_implemented',
+            message: `pugi ${command} is scaffolded but not implemented yet`,
+        };
+        writeOutput(flags, payload, payload.message);
+    };
+}
+function ensurePugiGitIgnore(cwd, created, skipped) {
+    const gitignorePath = resolve(cwd, '.gitignore');
+    const marker = '.pugi/';
+    if (!existsSync(gitignorePath)) {
+        writeFileSync(gitignorePath, `${marker}\n`, { encoding: 'utf8', mode: 0o600 });
+        created.push(gitignorePath);
+        return;
+    }
+    const current = readFileSync(gitignorePath, 'utf8');
+    const lines = current.split('\n').map((line) => line.trim());
+    if (lines.includes(marker) || lines.includes('/.pugi/') || lines.includes('.pugi')) {
+        skipped.push(gitignorePath);
+        return;
+    }
+    const next = current.endsWith('\n') ? `${current}${marker}\n` : `${current}\n${marker}\n`;
+    writeFileSync(gitignorePath, next, { encoding: 'utf8' });
+    created.push(`${gitignorePath} (+${marker})`);
+}
+function ensureDir(path, created, skipped) {
+    if (existsSync(path)) {
+        skipped.push(path);
+        return;
+    }
+    mkdirSync(path, { recursive: true });
+    created.push(path);
+}
+function ensureInitialized(root) {
+    if (!existsSync(resolve(root, '.pugi'))) {
+        throw new Error('Run pugi init first');
+    }
+}
+function createArtifactDir(root, seed) {
+    const id = `${new Date().toISOString().replace(/[:.]/g, '-')}-${slugify(seed)}`;
+    const artifactDir = resolve(root, '.pugi', 'artifacts', id);
+    mkdirSync(artifactDir, { recursive: true });
+    return artifactDir;
+}
+function latestArtifactDir(root) {
+    const artifactsDir = resolve(root, '.pugi', 'artifacts');
+    if (!existsSync(artifactsDir))
+        return null;
+    const dirs = readdirSync(artifactsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => resolve(artifactsDir, entry.name))
+        .sort();
+    return dirs.at(-1) ?? null;
+}
+function listArtifactSets(root) {
+    const artifactsDir = resolve(root, '.pugi', 'artifacts');
+    if (!existsSync(artifactsDir))
+        return [];
+    return readdirSync(artifactsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => {
+        const dir = resolve(artifactsDir, entry.name);
+        const files = readdirSync(dir, { withFileTypes: true })
+            .filter((file) => file.isFile())
+            .map((file) => file.name)
+            .sort();
+        return {
+            id: entry.name,
+            path: relative(root, dir),
+            files,
+            updatedAt: statSync(dir).mtime.toISOString(),
+        };
+    })
+        .sort((a, b) => b.id.localeCompare(a.id));
+}
+function listHandoffBundles(root) {
+    const handoffDir = resolve(root, '.pugi', 'handoffs');
+    if (!existsSync(handoffDir))
+        return [];
+    return readdirSync(handoffDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+        .map((entry) => {
+        const path = resolve(handoffDir, entry.name);
+        const parsed = safeReadJson(path);
+        return {
+            id: String(parsed?.id ?? entry.name.replace(/\.json$/, '')),
+            path: relative(root, path),
+            reason: String(parsed?.reason ?? 'unknown'),
+            createdAt: String(parsed?.createdAt ?? statSync(path).mtime.toISOString()),
+        };
+    })
+        .sort((a, b) => b.id.localeCompare(a.id));
+}
+function artifactIdFromDir(path) {
+    return path.split('/').at(-1) ?? randomUUID();
+}
+function createHandoffBundle(root, session, reason, prompt) {
+    const id = `${new Date().toISOString().replace(/[:.]/g, '-')}-${slugify(reason)}`;
+    const handoffDir = resolve(root, '.pugi', 'handoffs');
+    mkdirSync(handoffDir, { recursive: true });
+    const bundlePath = resolve(handoffDir, `${id}.json`);
+    const latest = latestArtifactDir(root);
+    const payload = pugiHandoffBundleSchema.parse({
+        schema: 1,
+        id,
+        reason,
+        prompt,
+        createdAt: new Date().toISOString(),
+        workspace: {
+            rootName: root.split('/').at(-1) ?? 'workspace',
+            gitBranch: safeGit(root, ['branch', '--show-current']).trim() || null,
+            gitHead: safeGit(root, ['rev-parse', '--short', 'HEAD']).trim() || null,
+            dirty: Boolean(safeGit(root, ['status', '--short']).trim()),
+        },
+        session: {
+            id: session.id,
+            eventsPath: relative(root, session.eventsPath),
+        },
+        artifacts: {
+            latest: latest ? relative(root, latest) : null,
+        },
+        privacy: {
+            includesFileContents: false,
+            includesSecrets: false,
+        },
+    });
+    writeFileSync(bundlePath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    registerArtifact(root, {
+        id,
+        kind: 'handoff',
+        path: relative(root, bundlePath),
+        sessionId: session.id,
+        createdAt: payload.createdAt,
+        files: [`${id}.json`],
+    });
+    return { status: 'created', id, reason, path: relative(root, bundlePath) };
+}
+function parsePrivacyMode(input) {
+    return pugiSyncPrivacyModeSchema.parse(input);
+}
+function privacyModeFromSettings(mode) {
+    if (mode === 'airgapped')
+        return 'local-only';
+    if (mode === 'embeddings-only')
+        return 'summaries';
+    return 'metadata';
+}
+function workspaceSnapshot(root) {
+    return {
+        rootName: root.split('/').at(-1) ?? 'workspace',
+        gitBranch: safeGit(root, ['branch', '--show-current']).trim() || null,
+        gitHead: safeGit(root, ['rev-parse', '--short', 'HEAD']).trim() || null,
+        dirty: Boolean(safeGit(root, ['status', '--short']).trim()),
+    };
+}
+function buildSyncDryRunItems(root, mode) {
+    if (mode === 'local-only') {
+        return [];
+    }
+    const items = [];
+    for (const artifact of listArtifactSets(root).slice(0, 20)) {
+        const summaryMode = mode === 'summaries';
+        items.push({
+            kind: summaryMode ? 'artifact_summary' : 'artifact_metadata',
+            path: artifact.path,
+            bytes: directoryFileBytes(resolve(root, artifact.path)),
+            action: mode === 'selected-files' || mode === 'full-sync' ? 'exclude' : 'include',
+            reason: mode === 'metadata'
+                ? 'artifact metadata only; no raw file contents'
+                : summaryMode
+                    ? 'curated artifact summaries are eligible for explicit continuation'
+                    : 'raw file sync requires a future explicit file picker',
+        });
+    }
+    for (const handoffBundle of listHandoffBundles(root).slice(0, 20)) {
+        items.push({
+            kind: 'handoff_bundle',
+            path: handoffBundle.path,
+            bytes: fileBytes(resolve(root, handoffBundle.path)),
+            action: 'include',
+            reason: 'handoff bundles contain metadata and artifact references only',
+        });
+    }
+    const eventsPath = resolve(root, '.pugi', 'events.jsonl');
+    if (existsSync(eventsPath)) {
+        items.push({
+            kind: 'session_event_log',
+            path: relative(root, eventsPath),
+            bytes: fileBytes(eventsPath),
+            action: mode === 'metadata' ? 'exclude' : 'include',
+            reason: mode === 'metadata'
+                ? 'session event logs excluded in metadata mode'
+                : 'session timeline is eligible without raw repository contents',
+        });
+    }
+    return items;
+}
+function directoryFileBytes(path) {
+    if (!existsSync(path))
+        return 0;
+    return readdirSync(path, { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .reduce((total, entry) => total + fileBytes(resolve(path, entry.name)), 0);
+}
+function fileBytes(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function safeGit(root, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd: root,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            // Default `maxBuffer` is 1 MB. Branch diffs blow past that on real
+            // PRs and `execFileSync` throws ENOBUFS, which this helper used to
+            // swallow as empty string — causing the triple-review request to
+            // ship an empty `diffPatch` and get a false PASS. 64 MB matches
+            // GitHub's typical PR diff cap.
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Glob patterns excluded from triple-review `diffPatch` before egress.
+ *
+ * Mirrors `protectedBasenames` + `protectedSuffixes` from
+ * `apps/pugi-cli/src/core/permission.ts`. If a developer tracks a
+ * protected file (uncommon but possible) we still must not POST its
+ * contents to Anvil — the runtime endpoint does not need to see secrets
+ * to render a verdict.
+ *
+ * Format follows git's pathspec exclude syntax (`:!<pattern>`).
+ */
+const PROTECTED_DIFF_EXCLUDES = [
+    // Basename excludes apply at the repo root AND in any subdirectory
+    // (e.g. `apps/foo/.env`) via the `**/<name>` glob form. Without the
+    // `**/` prefix, git's literal pathspec syntax would only match the
+    // repo root and silently let a subdir `.env` ship in the diff —
+    // common pitfall in pnpm/turbo monorepos.
+    ':(exclude,glob)**/.env',
+    ':(exclude,glob)**/.env.*',
+    ':(exclude,glob)**/.npmrc',
+    ':(exclude,glob)**/.yarnrc',
+    ':(exclude,glob)**/.pypirc',
+    ':(exclude,glob)**/.gitconfig',
+    ':(exclude,glob)**/id_rsa',
+    ':(exclude,glob)**/id_ed25519',
+    ':(exclude,glob)**/*.pem',
+    ':(exclude,glob)**/*.key',
+    ':(exclude,glob)**/*.crt',
+    ':(exclude,glob)**/*.p12',
+    ':(exclude,glob)**/*.dump',
+    ':(exclude,glob)**/*.sql',
+];
+function collectUntrackedSummary(root) {
+    const raw = safeGit(root, ['ls-files', '--others', '--exclude-standard']);
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    const visible = [];
+    let excluded = 0;
+    for (const path of lines) {
+        if (isProtectedPath(path)) {
+            excluded += 1;
+            continue;
+        }
+        visible.push(path);
+    }
+    return { paths: visible.slice(0, 50), excludedProtected: excluded };
+}
+function isProtectedPath(path) {
+    const base = path.split('/').pop() ?? path;
+    if (base === '.env' || base.startsWith('.env.'))
+        return true;
+    if (['.npmrc', '.yarnrc', '.pypirc', '.gitconfig', 'id_rsa', 'id_ed25519'].includes(base))
+        return true;
+    return /\.(pem|key|crt|p12|dump|sql)$/i.test(base);
+}
+function safeReadJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonIfMissing(path, value, created, skipped) {
+    writeTextIfMissing(path, `${JSON.stringify(value, null, 2)}\n`, created, skipped);
+}
+function writeTextIfMissing(path, value, created, skipped) {
+    if (existsSync(path)) {
+        skipped.push(path);
+        return;
+    }
+    writeFileSync(path, value, { encoding: 'utf8', mode: 0o600 });
+    created.push(path);
+}
+function slugify(input) {
+    const slug = input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48);
+    return slug || randomUUID().slice(0, 8);
+}
+function writeOutput(flags, payload, text) {
+    if (flags.json) {
+        console.log(JSON.stringify(payload, null, 2));
+    }
+    else {
+        console.log(text);
+    }
+}
+export function packageRoot() {
+    return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+//# sourceMappingURL=cli.js.map