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

package/dist/runtime/commands/doctor.js

@@ -0,0 +1,357 @@
+/**
+ * `pugi doctor` — environment health report (Leak L17, 2026-05-27).
+ *
+ * Parity command with Claude Code's `/doctor` (gap doc:
+ * docs/research/2026-05-27-pugi-gap-analysis-3-repos.md §6). Probes
+ * auth, API reachability, CLI version, workspace state, disk space,
+ * Node version, pnpm, git, MCP servers, config file, and session
+ * activity. Emits either a human-readable table OR a structured JSON
+ * envelope depending on `--json`.
+ *
+ * Module contract:
+ *
+ *   - This file owns the WIRING from CLI flags + workspace context to
+ *     the probe runner. The probes themselves live in
+ *     `core/diagnostics/probes/*.ts` and have NO module-level coupling
+ *     to the CLI dispatch surface.
+ *
+ *   - `runDoctorCommand` is the single entry point. Both the top-level
+ *     `pugi doctor` handler in `runtime/cli.ts` AND the in-REPL
+ *     `/doctor` slash command call it. The function returns the
+ *     `DoctorReport` so the REPL can render via the Ink table without
+ *     re-running the probes.
+ *
+ *   - Exit codes are derived from `exitCodeFor(overall)` in
+ *     `core/diagnostics/types.ts` and bubble up via `process.exitCode`
+ *     (matches the convention of every other CLI handler in cli.ts).
+ *
+ *   - The MCP probe is opportunistic: if `core/mcp/registry.js` is
+ *     unavailable for any reason (e.g. sibling L13 not yet landed,
+ *     unexpected schema change), the probe degrades to a graceful
+ *     `skipped` result so the rest of the table still renders.
+ */
+import { execFileSync } from 'node:child_process';
+import { constants as fsConstants, existsSync, accessSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolveActiveCredential } from '../../core/credentials.js';
+import { PUGI_CLI_VERSION } from '../version.js';
+import { runProbes, } from '../../core/diagnostics/probe-runner.js';
+import { computeOverall, countProbes, exitCodeFor, } from '../../core/diagnostics/types.js';
+import { probeAuth } from '../../core/diagnostics/probes/auth.js';
+import { probeApi } from '../../core/diagnostics/probes/api.js';
+import { probeCliVersion } from '../../core/diagnostics/probes/cli-version.js';
+import { probeWorkspace } from '../../core/diagnostics/probes/workspace.js';
+import { probeDisk } from '../../core/diagnostics/probes/disk.js';
+import { probeNode } from '../../core/diagnostics/probes/node.js';
+import { probePnpm } from '../../core/diagnostics/probes/pnpm.js';
+import { probeGit } from '../../core/diagnostics/probes/git.js';
+import { probeMcp } from '../../core/diagnostics/probes/mcp.js';
+import { probeConfig } from '../../core/diagnostics/probes/config.js';
+import { probeSession } from '../../core/diagnostics/probes/session.js';
+/**
+ * Default API URL when no PUGI_API_URL env override is set. Mirrors
+ * the constant in `core/credentials.ts` (kept local to avoid an
+ * extra named export from that module).
+ */
+const DEFAULT_API_URL = 'https://api.pugi.io';
+/**
+ * Build the standard probe set with production dependencies. Exported
+ * for the spec so the test can construct the same suite with stub
+ * deps + assert per-probe ordering + fail-isolation in isolation.
+ */
+export function buildDefaultProbes(ctx, options = {}) {
+    const fetchImpl = ctx.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    const now = Date.now;
+    const probes = [
+        {
+            name: 'AUTH',
+            run: () => probeAuth(ctx, {
+                resolveCredential: (env, home) => {
+                    const credential = resolveActiveCredential(env, home);
+                    if (!credential)
+                        return null;
+                    return { apiUrl: credential.apiUrl, apiKey: credential.apiKey };
+                },
+                fetchImpl,
+                now,
+            }),
+            timeoutMs: 4_000,
+        },
+        {
+            name: 'API',
+            run: () => probeApi(ctx, {
+                resolveApiUrl: (env) => {
+                    return env.PUGI_API_URL ?? DEFAULT_API_URL;
+                },
+                fetchImpl,
+                now,
+            }),
+            timeoutMs: 4_000,
+        },
+        {
+            name: 'CLI VERSION',
+            run: () => probeCliVersion({
+                localVersion: options.localCliVersion ?? PUGI_CLI_VERSION,
+                fetchImpl,
+                now,
+            }),
+            timeoutMs: 4_000,
+        },
+        {
+            name: 'WORKSPACE',
+            run: async () => probeWorkspace(ctx, {
+                existsSync,
+                statSync,
+                accessSync,
+                W_OK: fsConstants.W_OK,
+            }),
+        },
+        {
+            name: 'DISK',
+            run: async () => probeDisk(ctx, {
+                getFreeBytes: (home) => getFreeBytesViaDf(home),
+            }),
+        },
+        {
+            name: 'NODE',
+            run: async () => probeNode({ version: process.version }),
+        },
+        {
+            name: 'PNPM',
+            run: async () => probePnpm({
+                resolveVersion: () => execFileSync('pnpm', ['--version'], {
+                    encoding: 'utf8',
+                    timeout: 2_000,
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                }).trim(),
+            }),
+        },
+        {
+            name: 'GIT',
+            run: async () => probeGit(ctx, {
+                resolveVersion: () => execFileSync('git', ['--version'], {
+                    encoding: 'utf8',
+                    timeout: 2_000,
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                }).trim(),
+                isInWorkTree: (cwd) => {
+                    try {
+                        const result = execFileSync('git', ['-C', cwd, 'rev-parse', '--is-inside-work-tree'], {
+                            encoding: 'utf8',
+                            timeout: 2_000,
+                            stdio: ['ignore', 'pipe', 'ignore'],
+                        }).trim();
+                        return result === 'true';
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+                resolveHeadSha: (cwd) => {
+                    try {
+                        return execFileSync('git', ['-C', cwd, 'rev-parse', 'HEAD'], {
+                            encoding: 'utf8',
+                            timeout: 2_000,
+                            stdio: ['ignore', 'pipe', 'ignore'],
+                        }).trim();
+                    }
+                    catch {
+                        return null;
+                    }
+                },
+                resolveRoot: (cwd) => {
+                    try {
+                        return execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], {
+                            encoding: 'utf8',
+                            timeout: 2_000,
+                            stdio: ['ignore', 'pipe', 'ignore'],
+                        }).trim();
+                    }
+                    catch {
+                        return null;
+                    }
+                },
+            }),
+        },
+        {
+            name: 'MCP SERVERS',
+            run: async () => probeMcpSafely(ctx),
+        },
+        {
+            name: 'CONFIG',
+            run: async () => probeConfig(ctx, {
+                existsSync,
+                readFileSync: (p, encoding) => readFileSync(p, encoding),
+            }),
+        },
+        {
+            name: 'SESSION',
+            run: async () => probeSession(ctx, {
+                existsSync,
+                statSync,
+                readFileSync: (p, encoding) => readFileSync(p, encoding),
+            }, {
+                now,
+                ...(options.liveSessionId ? { liveSessionId: options.liveSessionId } : {}),
+            }),
+        },
+    ];
+    return probes;
+}
+/**
+ * Run the full doctor sweep + emit the output via the supplied
+ * writeOutput sink. Returns the report so REPL callers can route it
+ * к the Ink renderer instead of the plain-text fallback.
+ */
+export async function runDoctorCommand(ctx) {
+    const probeCtx = {
+        cwd: ctx.cwd,
+        home: ctx.home,
+        env: ctx.env,
+    };
+    const probes = buildDefaultProbes(probeCtx, {
+        ...(ctx.liveSessionId ? { liveSessionId: ctx.liveSessionId } : {}),
+    });
+    const report = await runProbes(probes);
+    // Defensive recompute: even though runProbes already computed the
+    // overall + counts, recomputing here documents the invariant for the
+    // reader and gives the JSON envelope a single source of truth.
+    const overall = computeOverall(report.probes);
+    const counts = countProbes(report.probes);
+    const envelope = {
+        command: 'doctor',
+        overall,
+        counts,
+        durationMs: report.durationMs,
+        probes: report.probes,
+        meta: {
+            cliVersion: PUGI_CLI_VERSION,
+            nodeVersion: process.version,
+            cwd: ctx.cwd,
+        },
+    };
+    const text = renderDoctorTable(envelope);
+    ctx.writeOutput(envelope, text);
+    process.exitCode = exitCodeFor(overall);
+    return { ...report, overall, counts };
+}
+/**
+ * Plain-text table renderer. Mirrors the layout from the leak-parity
+ * spec but is intentionally column-light (3 columns: NAME / STATUS /
+ * DETAIL) so it composes well in narrow terminals without dragging
+ * a layout library into the CLI hot path. The Ink TUI renderer in
+ * `tui/doctor-table.tsx` is the colour-aware variant used inside the
+ * REPL.
+ */
+export function renderDoctorTable(envelope) {
+    const NAME_WIDTH = Math.max('NAME'.length, ...envelope.probes.map((row) => row.name.length));
+    const STATUS_WIDTH = Math.max('STATUS'.length, ...envelope.probes.map((row) => row.status.length));
+    const lines = [];
+    lines.push('Pugi Doctor — environment health report');
+    lines.push('='.repeat(50));
+    lines.push('');
+    for (const row of envelope.probes) {
+        const namePart = row.name.padEnd(NAME_WIDTH, ' ');
+        const statusPart = row.status.toUpperCase().padEnd(STATUS_WIDTH, ' ');
+        const latencyPart = typeof row.latencyMs === 'number' ? ` (${row.latencyMs}ms)` : '';
+        lines.push(`${namePart}  ${statusPart}  ${row.detail}${latencyPart}`);
+        if (row.remediation && (row.status === 'warn' || row.status === 'error')) {
+            lines.push(`${' '.repeat(NAME_WIDTH + STATUS_WIDTH + 4)}→ ${row.remediation}`);
+        }
+    }
+    lines.push('');
+    const { ok, warn, error: errorCount, skipped } = envelope.counts;
+    const summary = envelope.overall === 'healthy'
+        ? 'HEALTHY'
+        : envelope.overall === 'warning'
+            ? 'WARNINGS'
+            : 'ERRORS';
+    lines.push(`${errorCount} error(s), ${warn} warning(s), ${ok} ok, ${skipped} skipped. Overall: ${summary}`);
+    lines.push(`CLI ${envelope.meta.cliVersion}  Node ${envelope.meta.nodeVersion}  cwd ${envelope.meta.cwd}`);
+    return lines.join('\n');
+}
+/**
+ * Wrap the MCP probe in a dynamic import + try/catch so a missing
+ * sibling L13 surface (or a schema mismatch in `core/mcp/registry`)
+ * degrades the row к `skipped` instead of breaking the entire sweep.
+ * The probe-runner already isolates throws into `error` rows; this
+ * wrapper additionally distinguishes "feature not available" from
+ * "feature crashed".
+ */
+async function probeMcpSafely(ctx) {
+    try {
+        const mod = await import('../../core/mcp/registry.js');
+        if (typeof mod.loadMcpRegistry !== 'function') {
+            return {
+                name: 'MCP SERVERS',
+                status: 'skipped',
+                detail: 'MCP integration not exported by this build',
+            };
+        }
+        return await probeMcp(ctx, {
+            loadRegistry: (cwd, options) => mod.loadMcpRegistry(cwd, { connect: options.connect ?? false }),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'MCP SERVERS',
+            status: 'skipped',
+            detail: 'MCP integration not available',
+            remediation: `Inspection failed: ${message}`,
+        };
+    }
+}
+/**
+ * Best-effort free-bytes lookup via `df -k <home>`. Parses the second
+ * line (header + one data row) and returns the `Available` column ×
+ * 1024. Throws on parse failure so the probe surfaces a `warn`
+ * instead of a misleading 0-bytes-free verdict.
+ *
+ * Exported for the spec so we can drive it through a stubbed
+ * execFileSync without spawning a real subprocess.
+ */
+export function getFreeBytesViaDf(home) {
+    const out = execFileSync('df', ['-k', home], {
+        encoding: 'utf8',
+        timeout: 2_000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return parseDfOutput(out);
+}
+/**
+ * Parse the textual output of `df -k`. Handles both BSD and GNU
+ * variants — both emit a `Available` column at index 3 of the data
+ * row, with one quirk: long device names wrap к the next line on
+ * GNU, so we collapse whitespace + tab newlines first.
+ */
+export function parseDfOutput(out) {
+    // Collapse multi-line device-name wraps into a single logical row.
+    const collapsed = out.replace(/\n\s+/g, ' ');
+    const lines = collapsed
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length < 2) {
+        throw new Error(`df output too short: ${JSON.stringify(out.slice(0, 64))}`);
+    }
+    const data = lines[1].split(/\s+/);
+    // Schema: Filesystem 1K-blocks Used Available Capacity Mounted-on
+    const availableField = data[3];
+    if (!availableField) {
+        throw new Error(`df output missing Available column: ${JSON.stringify(lines[1])}`);
+    }
+    const value = Number(availableField);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`df Available column not numeric: ${availableField}`);
+    }
+    return value * 1024;
+}
+/**
+ * Default home dir resolver. Centralised so the CLI handler can call
+ * `runDoctorCommand` without re-importing `os.homedir` everywhere.
+ */
+export function defaultHome() {
+    return homedir();
+}
+//# sourceMappingURL=doctor.js.map

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);