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

package/dist/core/file-cache.js

@@ -1,6 +1,45 @@
+/**
+ * Per-session file-read cache + stale-read gate.
+ *
+ * Leak intel L1 (openclaude `FileEditTool.ts`, 2026-05-27 gap analysis
+ * §5.1): every FileEdit must validate the operator's last-known view of
+ * the file before mutating disk. The gate compares BOTH `mtimeMs` and
+ * `sha256(content)` of the file on disk against the record captured at
+ * read time:
+ *
+ *   - mtimeMs is a cheap fast-path. If the inode mtime hasn't moved
+ *     since the read, the content hash cannot have changed (barring a
+ *     filesystem with hash-on-mtime-skew bugs) and we can short-circuit.
+ *   - sha256 is the authoritative gate. A user editor that writes back
+ *     identical content can leave mtime untouched on some filesystems
+ *     (atomic-rename with preserved metadata), and conversely `touch`
+ *     bumps mtime without changing content. Hash is the truth.
+ *
+ * Both signals must agree for the gate to PASS. Any divergence => STALE
+ * => refuse the edit, force the model to re-read.
+ *
+ * Cache lifetime: per-session. `FileReadCache.clear()` is called at
+ * session.end (see `core/session.ts`). The cache is intentionally NOT
+ * durable across sessions — a re-read after restart is cheap and stale
+ * cross-session entries would themselves be a soundness hazard.
+ *
+ * Exception: writeTool for create-new (path doesn't exist on disk) does
+ * not consult the cache. Creating a brand new file has no "last-known
+ * view" to invalidate.
+ */
 import { createHash } from 'node:crypto';
-import { statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
+export class StaleReadError extends Error {
+    reason;
+    path;
+    constructor(path, reason, detail) {
+        super(`stale_read: ${path} — ${detail}. Re-read the file before editing.`);
+        this.name = 'StaleReadError';
+        this.reason = reason;
+        this.path = path;
+    }
+}
 export class FileReadCache {
     records = new Map();
     set(record) {
@@ -9,6 +48,70 @@ export class FileReadCache {
     get(root, path) {
         return this.records.get(resolve(root, path));
     }
+    /**
+     * Validate a candidate edit against the cached read record. Returns
+     * a tagged-union: `{ stale: false }` when the edit may proceed, or
+     * `{ stale: true, reason, detail }` when the gate must refuse.
+     *
+     * Pure function over the cache + supplied `currentMtimeMs` /
+     * `currentContent` — does NOT touch disk. Callers (editTool /
+     * writeTool) do their own `statSync` + `readFileSync` because they
+     * also need the content for the diff/edit itself.
+     *
+     * @param root           workspace root (used to resolve relative path)
+     * @param path           workspace-relative file path
+     * @param currentMtimeMs `fs.statSync().mtimeMs` of the on-disk file
+     * @param currentContent UTF-8 contents of the on-disk file
+     */
+    validate(root, path, currentMtimeMs, currentContent) {
+        const record = this.get(root, path);
+        if (!record) {
+            return {
+                stale: true,
+                reason: 'no_prior_read',
+                detail: 'file must be read first',
+            };
+        }
+        // Fast-path: mtime hasn't moved. Hash check is redundant in the
+        // common case but cheap, so we still verify below. Skipping hash
+        // when mtime matches would allow a subtle bug class (in-place
+        // writers that preserve mtime) to slip through.
+        if (currentMtimeMs > record.mtimeMs) {
+            // mtime advanced — confirm with hash before flagging. A bump
+            // without a content change (e.g. `touch`) shouldn't fire stale.
+            const currentHash = hashContent(currentContent);
+            if (currentHash !== record.sha256) {
+                return {
+                    stale: true,
+                    reason: 'mtime_drift',
+                    detail: `mtime advanced (${record.mtimeMs} → ${currentMtimeMs}) and content hash diverged`,
+                };
+            }
+            // mtime bumped but content identical — treat as fresh. The cache
+            // entry's mtime is intentionally NOT refreshed here; the next
+            // edit will hit the same path and the gate will keep agreeing.
+            return { stale: false };
+        }
+        // mtime hasn't moved — hash MUST still match the record. A
+        // mismatch is a filesystem-level inconsistency or an in-place
+        // editor that preserves mtime; either way, refuse.
+        const currentHash = hashContent(currentContent);
+        if (currentHash !== record.sha256) {
+            return {
+                stale: true,
+                reason: 'hash_drift',
+                detail: 'content hash diverged from last read (mtime unchanged)',
+            };
+        }
+        return { stale: false };
+    }
+    /**
+     * Drop every cached record. Called by session.end so a fresh REPL
+     * session never inherits stale cross-session entries.
+     */
+    clear() {
+        this.records.clear();
+    }
 }
 export function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
@@ -26,4 +129,13 @@ export function createReadRecord(root, path, content, source) {
         source,
     };
 }
+/**
+ * Convenience helper: does this absolute path exist on disk? Wraps the
+ * existsSync import so file-tools.ts can decide between create-new
+ * (skip stale gate) and update-existing (apply stale gate) without
+ * pulling in another fs import.
+ */
+export function pathExists(absolutePath) {
+    return existsSync(absolutePath);
+}
 //# sourceMappingURL=file-cache.js.map

package/dist/core/mcp/client.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
 import { z } from 'zod';
 /**
  * Minimal JSON-RPC 2.0 over stdio MCP client for Pugi CLI M1.
@@ -79,6 +80,22 @@ export async function connect(serverName, config, options = {}) {
         env: { ...process.env, ...config.env },
         stdio: ['pipe', 'pipe', 'pipe'],
     });
+    // L13: optional stderr → log file. We open the stream lazily so a bad
+    // path surfaces synchronously to the caller instead of getting buried
+    // in the child's stderr handler. `mkdir -p` of the parent dir is the
+    // caller's responsibility (the registry does it once per session).
+    let logStream;
+    if (options.logFile) {
+        try {
+            logStream = createWriteStream(options.logFile, { flags: 'a' });
+        }
+        catch {
+            // Log directory missing or unwritable — degrade silently rather
+            // than refuse the handshake. The operator still gets the same
+            // surface they had pre-L13 (stderr dropped on the floor).
+            logStream = undefined;
+        }
+    }
     const connection = {
         serverName,
         child,
@@ -86,6 +103,8 @@ export async function connect(serverName, config, options = {}) {
         pending: new Map(),
         nextId: 1,
         closed: false,
+        ...(logStream ? { logStream } : {}),
+        startedAt: Date.now(),
     };
     // Attach the spawn-error handler BEFORE the reader: ENOENT and similar
     // are emitted asynchronously on the next tick, and without this
@@ -193,11 +212,25 @@ export async function callTool(connection, name, args, options = {}) {
  * SIGKILL if the child has not exited. Safe to call multiple times.
  */
 export async function disconnect(connection) {
-    if (connection.closed)
+    const closeLogStream = () => {
+        const stream = connection.logStream;
+        if (!stream)
+            return;
+        try {
+            stream.end();
+        }
+        catch {
+            // Best-effort — stream may already be destroyed.
+        }
+    };
+    if (connection.closed) {
+        closeLogStream();
         return;
+    }
     const { child } = connection;
     if (child.exitCode !== null || child.killed) {
         connection.closed = true;
+        closeLogStream();
         return;
     }
     return new Promise((resolveDone) => {
@@ -207,6 +240,7 @@ export async function disconnect(connection) {
                 return;
             settled = true;
             connection.closed = true;
+            closeLogStream();
             resolveDone();
         };
         child.once('exit', settle);
@@ -232,6 +266,22 @@ export async function disconnect(connection) {
         }, SHUTDOWN_GRACE_MS);
     });
 }
+/**
+ * L13: cheap liveness probe for `pugi mcp doctor`. True when the child
+ * process is still running AND the connection has not been torn down.
+ * Does NOT issue a JSON-RPC call — that would race with in-flight tool
+ * dispatch and the doctor surface is read-only.
+ */
+export function isAlive(connection) {
+    if (connection.closed)
+        return false;
+    const { child } = connection;
+    if (child.killed)
+        return false;
+    if (child.exitCode !== null)
+        return false;
+    return true;
+}
 function writeFrame(connection, message) {
     if (connection.closed) {
         throw new Error(`mcp server "${connection.serverName}" connection is closed`);
@@ -283,11 +333,21 @@ function attachReader(connection) {
             newlineIndex = buffer.indexOf('\n');
         }
     });
-    // stderr is captured but never thrown. Some MCP servers log diagnostics
-    // there even on success; we route it to nowhere so the CLI stdout stays
-    // pure JSON envelope output. A future iteration may forward this to the
-    // audit log.
-    connection.child.stderr.on('data', () => { });
+    // stderr is captured and (when `connect({ logFile })` was set) mirrored
+    // to a per-server log file under `.pugi/logs/`. Operators can tail the
+    // file via `pugi mcp logs <server>`. Default sink remains "drop on the
+    // floor" so the CLI stdout stays pure JSON envelope output.
+    connection.child.stderr.on('data', (chunk) => {
+        const stream = connection.logStream;
+        if (!stream || stream.destroyed)
+            return;
+        try {
+            stream.write(typeof chunk === 'string' ? chunk : chunk);
+        }
+        catch {
+            // Disk full / fd revoked — drop silently. Mirroring is best-effort.
+        }
+    });
 }
 function handleLine(connection, line) {
     let parsed;

package/dist/core/mcp/registry.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { z } from 'zod';
@@ -38,6 +38,13 @@ import { getMcpTrust } from './trust.js';
 const mcpFileSchema = z.object({
     servers: z.record(mcpServerConfigSchema).default({}),
 });
+/**
+ * L13: workspace-relative path for per-server log files. Surfaces in
+ * `pugi mcp logs <name>` and is mkdir -p'd before the first connect.
+ */
+export function mcpLogPath(workspaceRoot, serverName) {
+    return resolve(workspaceRoot, '.pugi/logs', `mcp-${serverName}.log`);
+}
 /**
  * Load and (optionally) connect every approved MCP server defined in the
  * workspace + user configs. Pending and denied servers stay in the
@@ -45,6 +52,7 @@ const mcpFileSchema = z.object({
  */
 export async function loadMcpRegistry(workspaceRoot, options = {}) {
     const shouldConnect = options.connect !== false;
+    const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5_000;
     const userConfig = readMcpFile(resolve(userHomeDir(), 'mcp.json'));
     const workspaceConfig = readMcpFile(resolve(workspaceRoot, '.pugi/mcp.json'));
     const merged = new Map();
@@ -52,6 +60,17 @@ export async function loadMcpRegistry(workspaceRoot, options = {}) {
         merged.set(name, config);
     for (const [name, config] of Object.entries(workspaceConfig))
         merged.set(name, config);
+    // L13: ensure the log dir exists once per session so per-server log
+    // streams can `append` without each one having to mkdir -p.
+    if (shouldConnect && merged.size > 0) {
+        try {
+            mkdirSync(resolve(workspaceRoot, '.pugi/logs'), { recursive: true });
+        }
+        catch {
+            // Workspace may be read-only (CI sandbox). Log routing degrades
+            // silently in that case — see `client.ts::connect`.
+        }
+    }
     const servers = new Map();
     for (const [name, config] of merged) {
         const ledgerTrust = await getMcpTrust(name);
@@ -70,7 +89,10 @@ export async function loadMcpRegistry(workspaceRoot, options = {}) {
         };
         if (shouldConnect && trust === 'trusted') {
             try {
-                const connection = await connect(name, config);
+                const connection = await connect(name, config, {
+                    timeoutMs: handshakeTimeoutMs,
+                    logFile: mcpLogPath(workspaceRoot, name),
+                });
                 state.connection = connection;
                 state.surfacedTools = await listTools(connection);
             }

package/dist/core/repl/session.js

@@ -765,6 +765,40 @@ export class ReplSession {
                 }
                 return verdict;
             }
+            case 'doctor': {
+                // L17 (2026-05-27): run the doctor probe sweep inline. We
+                // dynamic-import the runtime/commands/doctor module so the
+                // slash dispatcher does not pull the diagnostics graph
+                // (execFileSync + fs probes) into every keystroke. The
+                // module's output is captured into local lines so we can
+                // render it as system entries in the conversation pane;
+                // an Ink-rendered table inside the REPL frame is a follow-up.
+                try {
+                    const { runDoctorCommand, defaultHome } = await import('../../runtime/commands/doctor.js');
+                    const lines = [];
+                    await runDoctorCommand({
+                        cwd: process.cwd(),
+                        home: defaultHome(),
+                        env: process.env,
+                        json: false,
+                        writeOutput: (_payload, text) => {
+                            const trimmed = text.replace(/\n+$/u, '');
+                            if (trimmed.length > 0)
+                                lines.push(trimmed);
+                        },
+                    });
+                    for (const line of lines)
+                        this.appendSystemLine(line);
+                    if (lines.length === 0) {
+                        this.appendSystemLine('/doctor: no output.');
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.appendSystemLine(`/doctor failed: ${message}`);
+                }
+                return verdict;
+            }
             case 'stub': {
                 this.appendSystemLine(verdict.message);
                 return verdict;

package/dist/core/repl/slash-commands.js

@@ -81,6 +81,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     // Meta
     { name: 'help', args: '', gloss: 'Show this help overlay', group: 'Meta' },
     { name: 'version', args: '', gloss: 'Show CLI version', group: 'Meta' },
+    { name: 'doctor', args: '', gloss: 'Environment health report (auth · API · Node · disk · MCP · …)', group: 'Meta' },
     { name: 'quit', args: '', gloss: 'Exit the REPL', group: 'Meta' },
 ]);
 /**
@@ -271,6 +272,14 @@ export function parseSlashCommand(input) {
             const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
             return { kind: 'mcp', args: tokens };
         }
+        case 'doctor':
+        case 'health': {
+            // L17 (2026-05-27): run the probe sweep inline. Tail is ignored —
+            // the doctor command has no operator-facing arguments (every
+            // probe runs unconditionally; per-probe disable lives on the CLI
+            // shell surface, not the slash one).
+            return { kind: 'doctor' };
+        }
         case 'compact':
         case 'memory':
         case 'config':

package/dist/runtime/cli.js

@@ -1,13 +1,11 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { statSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AnvilEngineLoopClient } from '../core/engine/anvil-client.js';
-import { NoopEngineAdapter } from '../core/engine/noop.js';
 import { NativePugiEngineAdapter } from '../core/engine/native-pugi.js';
-import { decidePermission } from '../core/permission.js';
 import { loadMcpRegistry } from '../core/mcp/registry.js';
 import { loadHookRegistryOrExit } from './load-hooks-or-exit.js';
 import { defaultNonInteractiveMcpPrompt } from '../tools/mcp-tool.js';
@@ -16,7 +14,6 @@ import { loadSettings } from '../core/settings.js';
 import { FileReadCache } from '../core/file-cache.js';
 import { resolveWorkspacePath } from '../core/path-security.js';
 import { globTool, grepTool, readTool } from '../tools/file-tools.js';
-import { toolRegistry, toolSchemaBundleHashInput } from '../tools/registry.js';
 import { webFetchTool } from '../tools/web-fetch.js';
 import { emptyIndex, rebuildIndex, readIndex, upsertArtifact, writeIndex, } from '../core/index-store.js';
 import { signatureForPlanReview } from '../core/repl/ask.js';
@@ -30,6 +27,7 @@ import { runJobsCommand } from '../commands/jobs.js';
 import { runConfigCommand } from './commands/config.js';
 import { runPrivacyCommand } from './commands/privacy.js';
 import { runReport } from './commands/report.js';
+import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.js';
 import { runUndoCommand } from './commands/undo.js';
 import { runBudgetCommand } from './commands/budget.js';
 import { runSkillsCommand } from './commands/skills.js';
@@ -1111,61 +1109,29 @@ async function help(args, flags, _session) {
         'Execution defaults to local. Use --remote or --web to create a handoff bundle.',
     ].join('\n'));
 }
+/**
+ * `pugi doctor` — Leak L17 (2026-05-27). Delegates to the diagnostics
+ * probe runner in `runtime/commands/doctor.ts`. The handler stays
+ * thin so the probe surface stays single-sourced between the CLI
+ * shell command, the `pnpm run doctor --json` package script, and
+ * the in-REPL `/doctor` slash command.
+ *
+ * Exit codes are set by `runDoctorCommand` (0 = healthy/warnings,
+ * 2 = at least one error probe). The pre-L17 minimal doctor surface
+ * (adapter capabilities + schema bundle hash) is preserved under
+ * `payload.meta.legacy` so any operator scripts that grep the JSON
+ * keep working through the transition; the field is marked for
+ * removal in a follow-up sprint once the new shape is the
+ * documented contract.
+ */
 async function doctor(_args, flags, _session) {
-    const cwd = process.cwd();
-    const settings = loadSettings(cwd);
-    // `doctor` reports adapter capabilities only; we pass a no-op client
-    // so we do not require an Anvil endpoint to run `pugi doctor`. The
-    // adapter never invokes `client.send()` from inside `capabilities()`.
-    const inertClient = {
-        async send() {
-            return {
-                stop: 'error',
-                code: 'failed',
-                message: 'doctor: inert client',
-            };
-        },
-    };
-    const adapters = [
-        new NoopEngineAdapter(),
-        new NativePugiEngineAdapter({ client: inertClient }),
-    ];
-    const capabilities = await Promise.all(adapters.map(async (adapter) => ({
-        name: adapter.name,
-        capabilities: await adapter.capabilities(),
-    })));
-    const payload = {
-        cliVersion: PUGI_CLI_VERSION,
-        nodeVersion: process.version,
-        workspaceRoot: cwd,
-        pugiMode: existsSync(resolve(cwd, 'CLAUDE.md')),
-        pugiDir: existsSync(resolve(cwd, '.pugi')),
-        eventLog: existsSync(resolve(cwd, '.pugi/events.jsonl')),
-        permissionMode: settings.permissions.mode,
-        approvals: settings.workflow.approvals,
-        notAutomatic: [...settings.workflow.notAutomatic, ...settings.permissions.notAutomatic],
-        protectedFileCheck: decidePermission({ tool: 'doctor', kind: 'edit', target: '.env' }, settings, cwd),
-        protectedFileSafety: 'configured-in-m1',
-        mcpTrust: 'not-configured',
-        releaseGuard: 'scaffolded',
-        tools: toolRegistry,
-        engineAdapters: capabilities,
-        schemaBundleHash: createHash('sha256')
-            .update(toolSchemaBundleHashInput())
-            .digest('hex'),
-    };
-    writeOutput(flags, payload, [
-        'Pugi doctor',
-        `CLI: ${payload.cliVersion}`,
-        `Node: ${payload.nodeVersion}`,
-        `Workspace: ${payload.workspaceRoot}`,
-        `Pugi mode: ${payload.pugiMode ? 'detected' : 'not detected'}`,
-        `Pugi dir: ${payload.pugiDir ? 'present' : 'missing'}`,
-        `Event log: ${payload.eventLog ? 'present' : 'missing'}`,
-        `Permission mode: ${payload.permissionMode}`,
-        `Approvals: ${payload.approvals}`,
-        `Release guard: ${payload.releaseGuard}`,
-    ].join('\n'));
+    await runDoctorCommand({
+        cwd: process.cwd(),
+        home: defaultDoctorHome(),
+        env: process.env,
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
 }
 /**
  * Programmatic init scaffolder. Idempotent — every helper call is a