@pugi/cli 0.1.0-beta.17 → 0.1.0-beta.19

package/dist/runtime/commands/mcp.js

@@ -1,11 +1,12 @@
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, resolve } from 'node:path';
 import { FileReadCache } from '../../core/file-cache.js';
 import { openSession } from '../../core/session.js';
 import { loadSettings } from '../../core/settings.js';
-import { loadMcpRegistry } from '../../core/mcp/registry.js';
+import { isAlive } from '../../core/mcp/client.js';
+import { loadMcpRegistry, mcpLogPath } from '../../core/mcp/registry.js';
 import { listMcpTrust, setMcpTrust } from '../../core/mcp/trust.js';
 import { createPugiMcpServer, serveStdio } from '../../core/mcp/server.js';
 import { buildPugiMcpTools } from '../../core/mcp/server-tools.js';
@@ -22,6 +23,15 @@ export async function runMcpCommand(args, ctx) {
             return runMcpFlip(args.slice(1), ctx, 'denied');
         case 'install':
             return runMcpInstall(args.slice(1), ctx);
+        case 'remove':
+        case 'uninstall':
+            return runMcpRemove(args.slice(1), ctx);
+        case 'doctor':
+            return runMcpDoctor(args.slice(1), ctx);
+        case 'logs':
+            return runMcpLogs(args.slice(1), ctx);
+        case 'restart':
+            return runMcpRestart(args.slice(1), ctx);
         case 'serve':
             return runMcpServe(args.slice(1), ctx);
         case 'perms':
@@ -32,7 +42,7 @@ export async function runMcpCommand(args, ctx) {
             ctx.writeOutput({ command: 'mcp', usage: USAGE_LINES }, USAGE_LINES.join('\n'));
             return;
         default:
-            throw new Error(`Unknown sub-command "pugi mcp ${sub}". Try one of: list, trust, deny, install, serve, perms.`);
+            throw new Error(`Unknown sub-command "pugi mcp ${sub}". Try one of: list, trust, deny, install, remove, doctor, logs, restart, serve, perms.`);
     }
 }
 const USAGE_LINES = [
@@ -44,6 +54,15 @@ const USAGE_LINES = [
     '  install <name> <command...>   Add a server to .pugi/mcp.json (workspace scope).',
     '                                <command> must be an absolute path OR a binary',
     '                                resolvable via `which` on the operator PATH.',
+    '  remove <name>                 Remove a server from .pugi/mcp.json (workspace scope).',
+    '                                Trust ledger entry is preserved — re-install reuses it.',
+    '  doctor [--connect]            Print per-server health (handshake, tool count, last error).',
+    '                                --connect actually spawns the children (slow, ~5s/server).',
+    '                                Without --connect, reports the declared state only.',
+    '  logs <name> [--tail N]        Tail the per-server log file at .pugi/logs/mcp-<name>.log.',
+    '                                Default tail is 40 lines.',
+    '  restart <name>                Bounce a server: tear down the connection, reload the',
+    '                                config, re-handshake. Surfaces the new tool count.',
     '  serve [options]               Run Pugi as an MCP server',
     '    --http :<port>              HTTP+SSE transport (default: stdio)',
     '    --host <ip>                 HTTP bind host (default: 127.0.0.1)',
@@ -219,6 +238,274 @@ function containsShellMetachar(value) {
     // a shell pipeline.
     return /[;|&`$<>(){}\n\r]/.test(value);
 }
+/* ---------- remove ---------------------------------------------------- */
+async function runMcpRemove(args, ctx) {
+    const name = args[0];
+    if (!name) {
+        throw new Error('Usage: pugi mcp remove <name>');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp remove: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    const mcpJsonPath = resolve(ctx.workspaceRoot, '.pugi/mcp.json');
+    if (!existsSync(mcpJsonPath)) {
+        throw new Error(`pugi mcp remove: no .pugi/mcp.json at ${mcpJsonPath}. Nothing to remove.`);
+    }
+    let existing;
+    try {
+        const raw = readFileSync(mcpJsonPath, 'utf8');
+        if (raw.trim().length === 0) {
+            existing = { servers: {} };
+        }
+        else {
+            const parsed = JSON.parse(raw);
+            existing = { servers: parsed.servers ?? {} };
+        }
+    }
+    catch (error) {
+        throw new Error(`pugi mcp remove: cannot parse .pugi/mcp.json: ${error.message}. ` +
+            `Fix the file by hand or delete it and re-run.`);
+    }
+    if (!existing.servers[name]) {
+        throw new Error(`pugi mcp remove: server "${name}" not declared in ${mcpJsonPath}. ` +
+            `Run \`pugi mcp list\` to see declared servers.`);
+    }
+    // Preserve the trust ledger entry on purpose — a re-install of the same
+    // server name should land back at its old trust state so the operator
+    // does not have to re-approve it. To wipe trust as well, run
+    // `pugi mcp deny <name>` (or edit ~/.pugi/trust-mcp.json by hand).
+    delete existing.servers[name];
+    writeFileSync(mcpJsonPath, `${JSON.stringify(existing, null, 2)}\n`, { mode: 0o600 });
+    ctx.writeOutput({
+        command: 'mcp.remove',
+        name,
+        configPath: mcpJsonPath,
+        remaining: Object.keys(existing.servers),
+    }, [
+        `Removed MCP server "${name}" from ${mcpJsonPath}.`,
+        `Trust ledger entry preserved — re-install reuses it.`,
+        `Remaining servers: ${Object.keys(existing.servers).length === 0 ? '(none)' : Object.keys(existing.servers).join(', ')}.`,
+    ].join('\n'));
+}
+/* ---------- doctor ---------------------------------------------------- */
+async function runMcpDoctor(args, ctx) {
+    // `--connect` forces the doctor to actually spawn children + handshake.
+    // Default behaviour is dry-run (config + trust ledger only) so a routine
+    // `pugi doctor` does not block on a misbehaving server's 5s timeout per
+    // entry. Operators investigating an outage pass `--connect` explicitly.
+    const wantsConnect = args.includes('--connect');
+    const registry = await loadMcpRegistry(ctx.workspaceRoot, { connect: wantsConnect });
+    const ledger = await listMcpTrust();
+    const rows = [];
+    for (const state of registry.servers.values()) {
+        const conn = state.connection;
+        let handshake;
+        if (!wantsConnect) {
+            handshake = 'not-attempted';
+        }
+        else if (state.lastError) {
+            handshake = 'failed';
+        }
+        else if (conn && isAlive(conn)) {
+            handshake = 'ok';
+        }
+        else {
+            handshake = 'failed';
+        }
+        rows.push({
+            name: state.name,
+            trust: state.trust,
+            handshake,
+            pid: conn?.child.pid ?? null,
+            tools: state.surfacedTools.length,
+            uptimeMs: conn ? Date.now() - conn.startedAt : null,
+            lastError: state.lastError ?? null,
+            logFile: mcpLogPath(ctx.workspaceRoot, state.name),
+        });
+    }
+    rows.sort((a, b) => a.name.localeCompare(b.name));
+    await registry.shutdown();
+    if (rows.length === 0) {
+        ctx.writeOutput({ command: 'mcp.doctor', rows, ledger, connectAttempted: wantsConnect }, 'No MCP servers declared. Add one with `pugi mcp install <name> <command...>`.');
+        return;
+    }
+    const headerLines = [
+        `MCP doctor (${wantsConnect ? 'live handshake' : 'declared state only — pass --connect for live probe'}):`,
+        '',
+        `  ${'NAME'.padEnd(20)} ${'TRUST'.padEnd(8)} ${'HANDSHAKE'.padEnd(14)} ${'TOOLS'.padEnd(6)} ${'PID'.padEnd(7)} NOTE`,
+    ];
+    for (const row of rows) {
+        const note = row.lastError
+            ? `error: ${truncate(row.lastError, 60)}`
+            : row.handshake === 'ok'
+                ? `uptime ${formatUptime(row.uptimeMs ?? 0)}`
+                : row.handshake === 'failed'
+                    ? 'see log file'
+                    : '';
+        headerLines.push(`  ${row.name.padEnd(20)} ${row.trust.padEnd(8)} ${row.handshake.padEnd(14)} ${String(row.tools).padEnd(6)} ${String(row.pid ?? '-').padEnd(7)} ${note}`);
+    }
+    headerLines.push('', `Log dir: ${resolve(ctx.workspaceRoot, '.pugi/logs')}`);
+    if (!wantsConnect) {
+        headerLines.push('Hint: pass --connect to actually spawn the children (slow, ~5s budget/server).');
+    }
+    ctx.writeOutput({ command: 'mcp.doctor', rows, ledger, connectAttempted: wantsConnect }, headerLines.join('\n'));
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 1)}…`;
+}
+function formatUptime(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const sec = Math.floor(ms / 1000);
+    if (sec < 60)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m${sec % 60}s`;
+    const hr = Math.floor(min / 60);
+    return `${hr}h${min % 60}m`;
+}
+/* ---------- logs ------------------------------------------------------ */
+async function runMcpLogs(args, ctx) {
+    const name = args[0];
+    if (!name || name.startsWith('--')) {
+        throw new Error('Usage: pugi mcp logs <name> [--tail N]');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp logs: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    // `--tail N` and `--tail=N` both supported. Default 40 lines — matches
+    // typical `tail -n 40` muscle memory.
+    let tail = 40;
+    for (let i = 1; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--tail') {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error('pugi mcp logs: --tail requires a value');
+            const n = Number.parseInt(next, 10);
+            if (!Number.isInteger(n) || n <= 0) {
+                throw new Error(`pugi mcp logs: --tail must be a positive integer (got "${next}")`);
+            }
+            tail = n;
+            i += 1;
+        }
+        else if (arg.startsWith('--tail=')) {
+            const n = Number.parseInt(arg.slice('--tail='.length), 10);
+            if (!Number.isInteger(n) || n <= 0) {
+                throw new Error(`pugi mcp logs: --tail must be a positive integer (got "${arg}")`);
+            }
+            tail = n;
+        }
+        else {
+            throw new Error(`pugi mcp logs: unknown flag "${arg}"`);
+        }
+    }
+    const path = mcpLogPath(ctx.workspaceRoot, name);
+    if (!existsSync(path)) {
+        ctx.writeOutput({ command: 'mcp.logs', name, path, tail, lines: [] }, `No log file at ${path}. The server has not produced stderr output yet (or has never been started).`);
+        return;
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`pugi mcp logs: cannot read ${path}: ${error.message}.`);
+    }
+    const allLines = raw.split('\n');
+    // `split('\n')` of a trailing-newline file yields an empty last element.
+    // Drop it so the displayed tail matches `wc -l` expectations.
+    if (allLines.length > 0 && allLines[allLines.length - 1] === '') {
+        allLines.pop();
+    }
+    const tailed = allLines.slice(Math.max(0, allLines.length - tail));
+    const sizeBytes = (() => {
+        try {
+            return statSync(path).size;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    ctx.writeOutput({
+        command: 'mcp.logs',
+        name,
+        path,
+        tail,
+        totalLines: allLines.length,
+        sizeBytes,
+        lines: tailed,
+    }, [
+        `pugi mcp logs ${name} (${path}, ${sizeBytes} bytes, ${allLines.length} total lines, showing last ${Math.min(tail, allLines.length)}):`,
+        ...tailed,
+    ].join('\n'));
+}
+/* ---------- restart --------------------------------------------------- */
+async function runMcpRestart(args, ctx) {
+    const name = args[0];
+    if (!name) {
+        throw new Error('Usage: pugi mcp restart <name>');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp restart: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    // `pugi mcp restart` is stateless from the CLI's perspective — the CLI
+    // process has no long-lived MCP registry of its own (the REPL owns it
+    // and tears it down on exit). What we DO here is: load the config,
+    // refuse if the server is not declared or not trusted, then probe-spawn
+    // the server with the live handshake. This proves it is reachable +
+    // surfaces the tool count for the operator. The REPL picks up the
+    // change on its next `loadMcpRegistry` cycle.
+    const registry = await loadMcpRegistry(ctx.workspaceRoot, { connect: false });
+    const state = registry.servers.get(name);
+    if (!state) {
+        await registry.shutdown();
+        throw new Error(`pugi mcp restart: server "${name}" not declared. Run \`pugi mcp list\` to see declared servers.`);
+    }
+    if (state.trust !== 'trusted') {
+        await registry.shutdown();
+        throw new Error(`pugi mcp restart: server "${name}" trust state is "${state.trust}". ` +
+            `Run \`pugi mcp trust ${name}\` first.`);
+    }
+    await registry.shutdown();
+    // Re-load WITH connect=true but scoped to a single-server probe via
+    // handshakeTimeoutMs (5s default keeps the CLI snappy). We use the same
+    // loadMcpRegistry path so log routing + error capture stay consistent.
+    const probe = await loadMcpRegistry(ctx.workspaceRoot, { connect: true });
+    const probed = probe.servers.get(name);
+    const lastError = probed?.lastError ?? null;
+    const toolCount = probed?.surfacedTools.length ?? 0;
+    const pid = probed?.connection?.child.pid ?? null;
+    await probe.shutdown();
+    if (lastError) {
+        ctx.writeOutput({
+            command: 'mcp.restart',
+            name,
+            ok: false,
+            error: lastError,
+            logFile: mcpLogPath(ctx.workspaceRoot, name),
+        }, [
+            `pugi mcp restart ${name}: FAILED`,
+            `  error: ${lastError}`,
+            `  log file: ${mcpLogPath(ctx.workspaceRoot, name)}`,
+        ].join('\n'));
+        return;
+    }
+    ctx.writeOutput({
+        command: 'mcp.restart',
+        name,
+        ok: true,
+        pid,
+        surfacedTools: toolCount,
+    }, [
+        `pugi mcp restart ${name}: OK`,
+        `  pid: ${pid ?? '-'}`,
+        `  surfaced tools: ${toolCount}`,
+    ].join('\n'));
+}
 async function runMcpServe(args, ctx) {
     const flags = parseServeFlags(args);
     const session = openSession(ctx.workspaceRoot);

package/dist/runtime/commands/permissions.js

@@ -0,0 +1,87 @@
+/**
+ * `pugi permissions` / `/permissions` — Leak L6 4-mode gate control.
+ *
+ * Two entry points share one runtime helper:
+ *   1. `/permissions` in the REPL — forwarded by `core/repl/session.ts`.
+ *   2. `pugi permissions ...` top-level CLI command (handler in
+ *      `runtime/cli.ts`).
+ *
+ * Both pass a `PermissionsCommand` payload describing the operator
+ * intent (show / flip / persist) and a `writeOutput` callback that
+ * lets the caller route the rendered lines into the right surface
+ * (REPL transcript vs. stdout). The helper is intentionally I/O-free
+ * itself — it produces lines and lets the caller stream them.
+ */
+import { DEFAULT_PERMISSION_MODE, PERMISSION_MODES, PERMISSION_MODE_GLOSS, getCurrentMode, getGlobalDefaultMode, setCurrentMode, setGlobalDefaultMode, } from '../../core/permissions/index.js';
+/**
+ * Run the `/permissions` or `pugi permissions` flow. Side effects:
+ *   - When `command.mode` is undefined: prints the current mode + the
+ *     4-mode table (no writes).
+ *   - When `command.mode === 'bypass'` without `confirmBypass`: prints
+ *     a refusal + the safety copy, no writes.
+ *   - When `command.mode` is set + valid: writes workspace session
+ *     state; optionally writes global default when `persist` is true.
+ *   - Always prints the new effective mode + a one-line confirmation.
+ */
+export async function runPermissionsCommand(command, ctx) {
+    if (!command.mode) {
+        renderCurrentMode(ctx);
+        renderModeTable(ctx);
+        return;
+    }
+    if (command.mode === 'bypass' && !command.confirmBypass) {
+        ctx.writeOutput('Bypass mode disables policy hooks (skill steering, denial tracking).');
+        ctx.writeOutput('Run `/permissions bypass --confirm` to acknowledge before flipping.');
+        return;
+    }
+    setCurrentMode(ctx.workspaceRoot, command.mode);
+    if (command.persist) {
+        setGlobalDefaultMode(command.mode, ctx.homeDir);
+    }
+    const persistedHint = command.persist
+        ? ' Persisted to ~/.pugi/config.json for future sessions.'
+        : '';
+    ctx.writeOutput(`Permission mode set to '${command.mode}'.${persistedHint} ${PERMISSION_MODE_GLOSS[command.mode]}`);
+    if (command.mode === 'bypass') {
+        ctx.writeOutput('BYPASS MODE — all tools execute without prompts AND policy hooks disabled. Switch back with /permissions allow.');
+    }
+}
+/**
+ * Print the resolved current mode + the layered source. The merge
+ * order mirrors `resolveMode()`: workspace > global > default.
+ */
+function renderCurrentMode(ctx) {
+    const workspace = getCurrentMode(ctx.workspaceRoot);
+    const global = getGlobalDefaultMode(ctx.homeDir);
+    const effective = workspace ?? global ?? DEFAULT_PERMISSION_MODE;
+    const source = workspace
+        ? 'workspace session.json'
+        : global
+            ? 'global ~/.pugi/config.json'
+            : 'default (no override)';
+    ctx.writeOutput(`Current permission mode: ${effective} (source: ${source})`);
+}
+/**
+ * Print the 4-mode reference table. Keeps the gloss + the side-effect
+ * matrix in one place so the operator can see the contract while they
+ * decide which mode to switch to.
+ */
+function renderModeTable(ctx) {
+    ctx.writeOutput('');
+    ctx.writeOutput('Permission modes:');
+    for (const mode of PERMISSION_MODES) {
+        ctx.writeOutput(`  ${mode.padEnd(7)}  ${PERMISSION_MODE_GLOSS[mode]}`);
+    }
+    ctx.writeOutput('');
+    ctx.writeOutput('Switch with `/permissions <mode> [--persist]`. Bypass requires `--confirm`.');
+}
+/**
+ * Render the one-shot banner shown on session boot when the effective
+ * mode is `bypass`. The caller (engine adapter / REPL bootstrap) calls
+ * this once per session — repeated invocations are idempotent in copy
+ * but the caller is responsible for the once-only semantics.
+ */
+export function renderBypassBanner(writeOutput) {
+    writeOutput('BYPASS MODE — all tools execute without prompts AND policy hooks disabled. Switch back with /permissions allow.');
+}
+//# sourceMappingURL=permissions.js.map

package/dist/runtime/commands/status.js

@@ -0,0 +1,178 @@
+/**
+ * `pugi status` — concise session-state probe (Leak L34, 2026-05-27).
+ *
+ * Different from `pugi doctor` (environment health). The status
+ * command answers "what is this Pugi session doing right now?" —
+ * session id + age, cwd, permission mode, CLI version, token
+ * usage, dispatch counts, last command, compact boundaries, auth
+ * identity.
+ *
+ * # Module contract
+ *
+ *   - This file owns the WIRING from CLI flags + ambient process
+ *     state к the snapshot collector. The data collector itself
+ *     lives in `core/diagnostics/probes/status-snapshot.ts` and
+ *     has zero coupling к the CLI dispatch surface.
+ *
+ *   - `runStatusCommand` is the single entry point. Both the
+ *     top-level `pugi status` handler in `runtime/cli.ts` AND the
+ *     in-REPL `/status` slash command call it. The function
+ *     returns the `StatusSnapshot` so the REPL slash handler can
+ *     mount the Ink renderer without re-collecting fields.
+ *
+ *   - The credential resolver is captured behind a function so the
+ *     spec can stub it without monkey-patching `core/credentials.ts`.
+ *
+ *   - The permission state module is dynamic-imported with a
+ *     try/catch so this command lands cleanly before the L6
+ *     permission-mode work — when the module is absent the field
+ *     degrades к "unknown" instead of crashing the snapshot.
+ *
+ *   - Exit code is 0 unless the snapshot itself throws. The
+ *     command is intentionally informational — even a fully
+ *     "unavailable" snapshot (everything degraded к sentinels)
+ *     exits 0 so monitoring scripts can rely on a stable contract.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolveActiveCredential } from '../../core/credentials.js';
+import { PUGI_CLI_VERSION } from '../version.js';
+import { collectStatusSnapshot, } from '../../core/diagnostics/probes/status-snapshot.js';
+/**
+ * Default production filesystem stubs. Wraps node:fs so the
+ * snapshot collector can stay sync + structurally testable.
+ */
+const DEFAULT_FS = {
+    existsSync,
+    statSync,
+    readdirSync: (p) => readdirSync(p),
+    readFileSync: (p, encoding) => readFileSync(p, encoding),
+};
+/**
+ * Default credential resolver. Wraps `resolveActiveCredential` so
+ * the snapshot only sees the trimmed `ResolvedCredentialSummary`
+ * shape and не the full store record.
+ */
+function defaultResolveCredential(env, home) {
+    const cred = resolveActiveCredential(env, home);
+    if (!cred)
+        return null;
+    // Tier is не yet recorded в the credentials file — set к null
+    // until a future sprint surfaces `tier` on the stored record.
+    // The renderer hides the parenthetical when tier is null.
+    return {
+        apiUrl: cred.apiUrl,
+        label: cred.label ?? null,
+        tier: null,
+        identity: cred.label ?? null,
+    };
+}
+/**
+ * Default permission-mode loader. Dynamic-imports
+ * `core/permissions/state.ts` (L6 in the leak-parity roadmap);
+ * returns null when the module is absent OR malformed, which the
+ * snapshot field degrades к the "unknown" sentinel.
+ */
+async function defaultResolvePermissionMode() {
+    try {
+        const mod = (await import('../../core/permissions/state.js').catch(() => null));
+        if (!mod || typeof mod.getCurrentPermissionMode !== 'function') {
+            return null;
+        }
+        const mode = mod.getCurrentPermissionMode();
+        return typeof mode === 'string' && mode.length > 0 ? mode : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Collect the snapshot + emit the output via the supplied
+ * writeOutput sink. Returns the snapshot so REPL callers can
+ * route it к the Ink renderer instead of the plain-text fallback.
+ */
+export async function runStatusCommand(ctx) {
+    // Resolve the permission mode upfront — the snapshot is sync but
+    // the L6 loader is async (dynamic import). We materialise the
+    // value here and hand the snapshot a sync getter.
+    const permissionMode = ctx.resolvePermissionMode === undefined
+        ? await defaultResolvePermissionMode()
+        : null;
+    const deps = {
+        cwd: ctx.cwd,
+        home: ctx.home,
+        cliVersion: PUGI_CLI_VERSION,
+        now: ctx.now ?? Date.now,
+        liveSessionId: ctx.liveSessionId ?? null,
+        sessionStartedAtEpochMs: ctx.sessionStartedAtEpochMs ?? null,
+        liveTokensUsed: ctx.liveTokensUsed ?? null,
+        lastCommand: ctx.lastCommand ?? null,
+        lastCommandAtEpochMs: ctx.lastCommandAtEpochMs ?? null,
+        fs: ctx.fs ?? DEFAULT_FS,
+        resolveCredential: ctx.resolveCredential ?? (() => defaultResolveCredential(ctx.env, ctx.home)),
+        resolvePermissionMode: ctx.resolvePermissionMode ?? (() => permissionMode),
+    };
+    let snapshot;
+    try {
+        snapshot = collectStatusSnapshot(deps);
+    }
+    catch (error) {
+        // Defensive: the snapshot collector is fail-soft per field, but
+        // a structural crash (e.g. a hostile env that throws on
+        // `process.version` access) must не bring down `pugi status`.
+        // We synthesise a minimal envelope and surface the error в the
+        // text output so the operator can file a bug.
+        const message = error instanceof Error ? error.message : String(error);
+        snapshot = {
+            command: 'status',
+            fields: [
+                {
+                    key: 'session',
+                    label: 'Session',
+                    value: 'unknown',
+                    available: false,
+                    note: `snapshot collector crashed: ${message}`,
+                },
+            ],
+            meta: {
+                cliVersion: PUGI_CLI_VERSION,
+                nodeVersion: process.version,
+                cwd: ctx.cwd,
+                capturedAt: new Date((ctx.now ?? Date.now)()).toISOString(),
+            },
+        };
+    }
+    const text = renderStatusTable(snapshot);
+    ctx.writeOutput(snapshot, text);
+    // Always exit 0 — `pugi status` is informational, never a gate.
+    process.exitCode = 0;
+    return snapshot;
+}
+/**
+ * Plain-text table renderer. Lays out the snapshot as a two-column
+ * (LABEL / VALUE) table with the brand-voice header `Pugi status`.
+ * Matches the column-light pattern used by `renderDoctorTable` so
+ * narrow terminals stay legible without a layout library.
+ */
+export function renderStatusTable(snapshot) {
+    const labelWidth = Math.max('Label'.length, ...snapshot.fields.map((f) => f.label.length));
+    const lines = [];
+    lines.push('Pugi status');
+    lines.push('═'.repeat(50));
+    for (const field of snapshot.fields) {
+        const labelPart = field.label.padEnd(labelWidth, ' ');
+        lines.push(`${labelPart}  ${field.value}`);
+    }
+    lines.push('');
+    lines.push(`CLI ${snapshot.meta.cliVersion}  Node ${snapshot.meta.nodeVersion}  cwd ${snapshot.meta.cwd}`);
+    return lines.join('\n');
+}
+/**
+ * Default home dir resolver. Centralised so the CLI handler can
+ * call `runStatusCommand` without re-importing `os.homedir`
+ * everywhere.
+ */
+export function defaultStatusHome() {
+    return homedir();
+}
+//# sourceMappingURL=status.js.map

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.17');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.19');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/dist/tools/agent-tool.js

@@ -58,8 +58,16 @@ import { spawnSubagentWithOutcome } from '../core/subagents/spawn.js';
  * inverse (forces shared-fs even for roles whose default is `worktree`).
  *
  * The role enum mirrors the SDK's SubagentRole — keep both in lockstep.
+ *
+ * Leak P0 L2 (2026-05-27): `z.strictObject` rejects ANY additional or
+ * aliased fields at parse time. Matches the openclaude FileEditTool /
+ * FileWriteTool posture (research memo §1.1). The model-facing JSON
+ * schema already declares `additionalProperties: false`; the strict
+ * Zod variant is defense-in-depth — if the bridge ever bypasses the
+ * model-side gate (raw test fixture, internal dispatch), the runtime
+ * still refuses unknown keys instead of silently dropping them.
  */
-export const agentToolArgsSchema = z.object({
+export const agentToolArgsSchema = z.strictObject({
     role: z.enum([
         'orchestrator',
         'architect',
@@ -70,12 +78,18 @@ export const agentToolArgsSchema = z.object({
         'release',
         'devops',
         'design_qa',
-    ]),
+    ]).describe('SubagentRole — selects persona + isolation tier.'),
     brief: z
         .string()
         .min(1, 'brief must not be empty')
-        .max(8000, 'brief must be ≤ 8000 chars'),
-    isolation: z.enum(['worktree', 'shared_fs', 'auto']).optional(),
+        .max(8000, 'brief must be ≤ 8000 chars')
+        .describe('One-paragraph task description forwarded to the child as the user prompt. '
+        + 'Be concrete: include filenames, expected behavior, and acceptance criteria.'),
+    isolation: z
+        .enum(['worktree', 'shared_fs', 'auto'])
+        .optional()
+        .describe('Optional override. `worktree` forces a scratch git worktree for write isolation; '
+        + '`shared_fs` forces same-tree execution; `auto` (default) defers to the role tier.'),
 });
 /**
  * Dispatch a subagent via the `agent` tool. Returns the JSON envelope