ast-mcp-server 0.11.1 → 0.11.2

package/CHANGELOG.md

@@ -6,7 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.11.1] — local recovery candidate, pending release (2026-08-23)
+## [0.11.2] — local release candidate, pending release (2026-08-25)
+
+### Added
+
+- Added an explicit per-connection supervised compiler-worker mode that can recycle an idle compiler child while the local stdio parent remains connected; `in_process` remains the default and rollback, and TTL `0` disables recycling.
+- Added scoped Linux evidence on exact Node.js 22.13.0 and Node.js 24 for PSS reclamation, stable compiler fingerprints, SQLite reuse, bounded redaction, and parent-death cleanup without orphans.
+
+### Fixed
+
+- Compiler-worker startup now waits for `ready` before replaying initialization, preventing cross-channel settlement ordering from rejecting the first forwarded request as stale.
+- CLI project-discovery fixtures now create the external project directory before concurrent configuration writes, eliminating a nondeterministic `ENOENT` setup race.
+- Public-registry verification now copies the isolated runner's complete local runtime dependency closure, including the shared managed-skill validator, before launching it outside the source tree.
+- A deterministic copied-runner regression executes the isolated entry point and rejects any local import omitted by its production bootstrap.
+
+### Release status
+
+- This local release candidate succeeds immutable npm versions `0.11.0` and `0.11.1`, neither of which was promotable: `0.11.0` verification exposed stale managed-skill predicates, and `0.11.1` verification exposed the copied runner's missing validator module. Version `0.11.2` remains pending its exact-tree matrix, CI, and separately authorized delivery sequence; it has not been published or assigned to any dist-tag.
+
+## [0.11.1] — published to `next`, verification failed, not promoted (2026-08-23)
 
 ### Fixed
 
@@ -15,7 +33,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Release status
 
-- This local recovery candidate succeeds the immutable npm `0.11.0` publication, whose public-registry verification failed because two consumer validators still required skill bundle `4.4.0` while the published package correctly contained `4.5.0`. Version `0.11.0` remains under `next` only and must not be promoted, tagged, or released. Version `0.11.1` remains pending its exact-tree matrix, CI, and separately authorized delivery sequence; it has not been published or assigned to any dist-tag.
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. Public-registry verification then failed because the isolated registry runner omitted its newly imported managed-skill validator module; `0.11.1` was never promoted to `latest`, tagged in Git, or released on GitHub.
 
 ## [0.11.0] — published to `next`, verification failed, not promoted (2026-08-23)
 

package/README.md

@@ -84,11 +84,23 @@ The included batch benchmark records a 50% reduction in model round-trips and a
 
 ## Supported environment and trust boundary
 
-The local `0.11.1` recovery candidate requires Node.js `>=22.13.0`; its evidence matrix targets exact Node.js 22.13.0 and the current Node.js 24 line. Published v0.10.0 retains its immutable historical Node.js 22.13.0/24 evidence. Managed setup-file publication additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified.
+The local `0.11.2` release candidate requires Node.js `>=22.13.0`; its evidence matrix targets exact Node.js 22.13.0 and the current Node.js 24 line. Published v0.10.0 retains its immutable historical Node.js 22.13.0/24 evidence. Managed setup-file publication additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified.
 
 This is a local stdio server. It runs with the invoking user's filesystem permissions, and clients may request any `project_root` that user can access. It does not provide HTTP authentication, sandboxing, tenant isolation, or a remote-service security boundary. Remote, untrusted, and multi-tenant operation is unsupported.
 
-In published v0.10.0 and the local `0.11.1` recovery candidate, an absent `AST_SYMBOL_INDEX_PERSISTENCE` or explicit `enabled` selects the private SQLite symbol-index cache. `disabled` is the immediate memory-only rollback. `canary` requires an explicit absolute normalized `AST_SYMBOL_INDEX_CACHE_ROOT`. Invalid policy or storage fails closed to compiler-authoritative memory reads with bounded path-free status.
+### Optional supervised compiler worker
+
+The compiler runs in process by default. Linux operators may explicitly keep the stdio parent connected while allowing an idle compiler child to exit and lazily respawn:
+
+```bash
+AST_COMPILER_WORKER_MODE=supervised ast-mcp-server
+```
+
+The parent waits for child readiness before replaying bounded initialization state. Requests and cancellation remain generation-affine; mutation history, live operation leases, and completion-critical apply work prevent unsafe recycling. Set `AST_COMPILER_WORKER_MODE=in_process` for the full rollback, or set `AST_COMPILER_WORKER_IDLE_TTL_MS=0` to retain the relay while disabling idle recycling.
+
+The scoped Linux canary passed on exact Node.js 22.13.0 and Node.js 24 with repeatable PSS reclamation, stable compiler fingerprints, unchanged SQLite reuse, bounded redacted diagnostics, and no orphan after parent death. This is one child per connection, not a shared daemon, pool, or new default. See [ADR 0014](docs/adr/0014-supervised-compiler-worker.md).
+
+In published v0.10.0 and the local `0.11.2` release candidate, an absent `AST_SYMBOL_INDEX_PERSISTENCE` or explicit `enabled` selects the private SQLite symbol-index cache. `disabled` is the immediate memory-only rollback. `canary` requires an explicit absolute normalized `AST_SYMBOL_INDEX_CACHE_ROOT`. Invalid policy or storage fails closed to compiler-authoritative memory reads with bounded path-free status.
 
 The default cache root is selected from `AST_SYMBOL_INDEX_CACHE_ROOT`, then `XDG_CACHE_HOME`, then `HOME`. Inspect or clear only derived cache artifacts through the bounded CLI:
 

package/SECURITY.md

@@ -11,7 +11,7 @@ Security fixes are provided for the exact version currently identified by the np
 | Earlier npm versions                        | No        |
 | Unpublished release candidates              | No        |
 
-This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The local `0.11.1` recovery candidate requires Node.js `>=22.13.0`, with evidence targeted at exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.10.0 retains its immutable Node.js 22.13.0/24 release matrix. Managed setup mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. The candidate's default SQLite cache also relies on Linux ownership, mode, no-follow, link-count and inode-identity checks; it does not defend against a malicious same-UID process. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
+This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The local `0.11.2` release candidate requires Node.js `>=22.13.0`, with evidence targeted at exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.10.0 retains its immutable Node.js 22.13.0/24 release matrix. Managed setup mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. The candidate's default SQLite cache also relies on Linux ownership, mode, no-follow, link-count and inode-identity checks; it does not defend against a malicious same-UID process. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
 
 ## Reporting a vulnerability
 

package/dist/compiler-worker-entry.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import { createInterface } from "node:readline";
+import { PassThrough } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { decodeCompilerWorkerEnvelope } from "./services/compiler-worker-protocol.js";
+async function runDefaultCompilerRuntime(input = process.stdin) {
+    return (await import("./worker-runtime.js")).runStdioServer({
+        transport: new StdioServerTransport(input, process.stdout),
+    });
+}
+export function runCompilerWorkerChild(runRuntime = runDefaultCompilerRuntime) {
+    return runRuntime();
+}
+// prettier-ignore
+export function installPrivateControl(runtime, input) {
+    let sequence = 0, generation = 0, writeSequence = 0;
+    const send = (generation, type, payload) => process.send?.({ v: 1, generation, sequence: ++sequence, type, payload });
+    const arm = (handle) => { const force = () => { if (handle.snapshot?.().completion_critical_operations > 0)
+        setTimeout(force, 50).unref();
+    else
+        process.exit(1); }; setTimeout(force, (handle.shutdownGraceMs ?? 10_000) + 2_000).unref(); };
+    const shutdown = (handle, trigger) => { if (trigger === "parent_exit")
+        arm(handle); void handle.shutdown(trigger).finally(() => process.disconnect()); };
+    process.on("message", (message) => { const decoded = decodeCompilerWorkerEnvelope(JSON.stringify(message)); if (!decoded.ok)
+        return; if (decoded.value.type === "handshake") {
+        generation = decoded.value.generation;
+        void runtime.then(() => send(generation, "ready", {}));
+    } if (decoded.value.type === "snapshot")
+        void runtime.then((handle) => send(generation, "snapshot", (handle.snapshot?.() ?? {}))); if (decoded.value.type === "shutdown") {
+        const trigger = decoded.value.payload.trigger === "parent_exit" ? "parent_exit" : "requested";
+        void runtime.then((handle) => shutdown(handle, trigger));
+    } });
+    if (input) {
+        const lines = createInterface({ input: process.stdin });
+        lines.on("line", (line) => input.write(`${line}\n`, () => send(generation, "settled", { write_sequence: ++writeSequence })));
+        lines.once("close", () => input.end());
+    }
+    process.once("disconnect", () => void runtime.then((handle) => { arm(handle); void handle.shutdown("parent_exit").then(() => process.exit(0), () => process.exit(1)); }));
+}
+const entry = process.argv[1];
+if (entry && fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+    const input = process.send ? new PassThrough() : undefined;
+    const runtime = input ? runDefaultCompilerRuntime(input) : runCompilerWorkerChild();
+    if (process.send)
+        installPrivateControl(runtime, input);
+    runtime.catch(() => {
+        process.stderr.write("Fatal compiler worker startup error.\n");
+        process.exit(1);
+    });
+}

package/dist/index.js

@@ -1,131 +1,31 @@
 #!/usr/bin/env node
 import fs from "node:fs";
-import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createServer } from "./server.js";
-import { beginProjectShutdown, closeDrainedProjectSessions, getProjectRuntimeShutdownSnapshot, prepareProjectRuntimeForStartup, waitForProjectCompletionCriticalOperationsToDrain, waitForProjectOperationsToDrain, } from "./services/project.js";
-import { RuntimeActivityTracker } from "./services/runtime-activity.js";
 import { readRuntimePolicy } from "./services/runtime-policy.js";
-import { emitIncompleteShutdownEvent, ShutdownCoordinator, } from "./services/shutdown.js";
-function emitShutdownFailureEvent() {
-    process.stderr.write(`${JSON.stringify({ event: "shutdown_failed", version: 1 })}\n`);
+export async function loadRuntimeModule(policy, loaders) {
+    return {
+        mode: policy.compilerWorkerMode,
+        module: await (policy.compilerWorkerMode === "supervised"
+            ? loaders.supervised()
+            : loaders.inProcess()),
+    };
 }
 export async function runStdioServer(options = {}) {
-    if (options.server && !options.runtimeActivity) {
-        throw new Error("An injected MCP server requires its runtime activity tracker.");
-    }
-    prepareProjectRuntimeForStartup();
-    const runtimeActivity = options.runtimeActivity ?? new RuntimeActivityTracker();
-    runtimeActivity.prepareForStartup();
-    const server = options.server ?? createServer({ runtimeActivity });
-    const transport = options.transport ?? new StdioServerTransport();
-    const send = transport.send.bind(transport);
-    transport.send = (message, sendOptions) => runtimeActivity.trackSend(() => send(message, sendOptions));
-    const runtimePolicy = options.runtimePolicy ?? readRuntimePolicy();
-    const installProcessHandlers = options.installProcessHandlers ?? true;
-    const exit = options.exit ?? ((code) => process.exit(code));
-    const protocol = server.server;
-    const previousTransportClose = protocol.onclose;
-    let listenersInstalled = false;
-    let terminalHandlerInstalled = false;
-    const onSigint = () => requestFromRuntime("sigint");
-    const onSigterm = () => requestFromRuntime("sigterm");
-    const onStdinEnd = () => requestFromRuntime("stdin_eof");
-    const onStdinClose = () => requestFromRuntime("stdin_eof");
-    const onTransportClose = () => {
-        previousTransportClose?.();
-        requestFromRuntime("transport_closed");
-    };
-    const removeLifecycleListeners = () => {
-        if (listenersInstalled) {
-            process.off("SIGINT", onSigint);
-            process.off("SIGTERM", onSigterm);
-            process.stdin.off("end", onStdinEnd);
-            process.stdin.off("close", onStdinClose);
-            listenersInstalled = false;
-        }
-        if (protocol.onclose === onTransportClose)
-            protocol.onclose = previousTransportClose;
-    };
-    const coordinator = new ShutdownCoordinator({
-        drainTimeoutMs: runtimePolicy.shutdownDrainTimeoutMs,
-        stopAdmissionAndCancel: () => {
-            runtimeActivity.beginShutdown();
-            return beginProjectShutdown();
-        },
-        getDrainSnapshot: getProjectRuntimeShutdownSnapshot,
-        waitForDrain: async () => {
-            await Promise.all([waitForProjectOperationsToDrain(), runtimeActivity.waitForIdle()]);
-        },
-        waitForCompletionCriticalOperationsToDrain: waitForProjectCompletionCriticalOperationsToDrain,
-        closeMcp: async () => {
-            await server.close();
-        },
-        closeProjects: closeDrainedProjectSessions,
-        emitIncompleteShutdown: emitIncompleteShutdownEvent,
-        onCompletionCriticalWait: options.onCompletionCriticalWait,
-    });
-    let lifecycleCompletion;
-    function requestShutdown(trigger) {
-        lifecycleCompletion ??= coordinator.shutdown(trigger).finally(removeLifecycleListeners);
-        return lifecycleCompletion;
-    }
-    function requestFromRuntime(trigger) {
-        try {
-            options.onRuntimeTrigger?.(trigger);
-        }
-        catch {
-            // Runtime observation is non-authoritative and must never interrupt shutdown.
-        }
-        const completion = requestShutdown(trigger);
-        if (terminalHandlerInstalled)
-            return;
-        terminalHandlerInstalled = true;
-        void completion
-            .then((result) => {
-            if (result.state === "forced_noncritical")
-                exit(1);
-        })
-            .catch(() => {
-            emitShutdownFailureEvent();
-            exit(1);
-        });
-    }
-    protocol.onclose = onTransportClose;
-    if (installProcessHandlers) {
-        process.on("SIGINT", onSigint);
-        process.on("SIGTERM", onSigterm);
-        process.stdin.once("end", onStdinEnd);
-        process.stdin.once("close", onStdinClose);
-        listenersInstalled = true;
-    }
-    try {
-        await server.connect(transport);
-    }
-    catch (error) {
-        await requestShutdown("requested").catch(() => undefined);
-        throw error;
-    }
-    if (options.logStartup ?? true)
-        process.stderr.write("ast-mcp-server running over stdio.\n");
-    return Object.freeze({
-        shutdown: (trigger = "requested") => requestShutdown(trigger),
-    });
+    return (await import("./worker-runtime.js")).runStdioServer(options);
 }
-function isMainModule() {
-    const entry = process.argv[1];
-    if (!entry)
-        return false;
-    try {
-        return fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url));
-    }
-    catch {
-        return path.resolve(entry) === path.resolve(fileURLToPath(import.meta.url));
-    }
+async function runConfiguredStdioServer() {
+    const policy = readRuntimePolicy();
+    const selected = await loadRuntimeModule(policy, {
+        inProcess: async () => ({ run: () => runStdioServer({ runtimePolicy: policy }) }),
+        supervised: async () => ({
+            run: () => import("./services/compiler-worker-host.js").then((host) => host.runSupervisedStdioServer()),
+        }),
+    });
+    await selected.module.run();
 }
-if (isMainModule()) {
-    runStdioServer().catch(() => {
+const entry = process.argv[1];
+if (entry && fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+    runConfiguredStdioServer().catch(() => {
         process.stderr.write("Fatal ast-mcp-server startup error.\n");
         process.exit(1);
     });

package/dist/services/compiler-worker-host.js

@@ -0,0 +1,422 @@
+import { Buffer } from "node:buffer";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { decodeCompilerWorkerEnvelope, startCompilerWorker } from "./compiler-worker-protocol.js";
+import { createCompilerWorkerSpawnSpec, readRuntimePolicy, } from "./runtime-policy.js";
+import { emitCompilerWorkerEvent } from "./runtime-logger.js";
+import { PublicOperationalError, renderPublicError } from "./public-errors.js";
+export class CompilerWorkerHostError extends Error {
+    kind;
+    recovery;
+    constructor(kind, recovery) {
+        super("Compiler worker request failed.");
+        this.kind = kind;
+        this.recovery = recovery;
+    }
+}
+const bounded = (value) => Buffer.byteLength(JSON.stringify(value)) <= 256 * 1024;
+const within = (promise, ms) => Promise.race([
+    promise,
+    delay(ms, undefined, { ref: false }).then(() => {
+        throw new CompilerWorkerHostError("startup");
+    }),
+]);
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => {
+        resolve = yes;
+        reject = no;
+    });
+    return { promise, resolve, reject };
+}
+export function spawnCompilerWorkerProcess(options) {
+    const spec = createCompilerWorkerSpawnSpec(options.workerEntryPath, options.environment);
+    if (!spec.ok || !spec.command)
+        throw new CompilerWorkerHostError("startup");
+    const child = spawn(spec.command, spec.args, {
+        ...spec.options,
+        stdio: ["pipe", "pipe", "inherit", "ipc"],
+    });
+    const ready = deferred();
+    const closed = new Promise((resolve) => child.once("close", () => resolve()));
+    const pending = new Map();
+    const snapshots = [];
+    const acknowledgements = new Map();
+    let outbound = 0;
+    let inbound = 0;
+    let controlInbound = 0;
+    let writes = 0;
+    const fail = (error) => {
+        ready.reject(error);
+        for (const request of pending.values())
+            request.reject(error);
+        pending.clear();
+        for (const snapshot of snapshots.splice(0))
+            snapshot.reject(error);
+        for (const acknowledged of acknowledgements.values())
+            acknowledged.reject(error);
+        acknowledgements.clear();
+    };
+    child.once("close", () => fail(new CompilerWorkerHostError("worker_exit")));
+    child.on("message", (message) => {
+        const frame = JSON.stringify(message);
+        const decoded = decodeCompilerWorkerEnvelope(frame);
+        if (!decoded.ok ||
+            decoded.value.generation !== options.generation ||
+            decoded.value.sequence <= controlInbound ||
+            !["ready", "snapshot", "settled"].includes(decoded.value.type))
+            return fail(new CompilerWorkerHostError("protocol"));
+        controlInbound = decoded.value.sequence;
+        if (decoded.value.type === "settled") {
+            const writeSequence = decoded.value.payload.write_sequence;
+            if (!Number.isSafeInteger(writeSequence))
+                return fail(new CompilerWorkerHostError("protocol"));
+            acknowledgements.get(writeSequence)?.resolve();
+            acknowledgements.delete(writeSequence);
+        }
+        else if (decoded.value.type === "ready") {
+            inbound = 1;
+            ready.resolve(frame);
+        }
+        else
+            snapshots.shift()?.resolve(decoded.value);
+    });
+    createInterface({ input: child.stdout }).on("line", (line) => {
+        if (Buffer.byteLength(line) > 256 * 1024)
+            return fail(new CompilerWorkerHostError("protocol"));
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return fail(new CompilerWorkerHostError("protocol"));
+        }
+        if (!("id" in message) || message.id === undefined)
+            return;
+        const request = pending.get(message.id);
+        if (!request)
+            return;
+        pending.delete(message.id);
+        request.resolve({
+            generation: options.generation,
+            sequence: ++inbound,
+            payload: { request_id: message.id, message },
+        });
+    });
+    const write = (message, acknowledge = false) => {
+        if (!bounded(message) || !child.stdin?.writable)
+            return Promise.reject(new CompilerWorkerHostError("protocol"));
+        options.beforeWrite?.(message);
+        const writeSequence = ++writes, processed = acknowledge ? deferred() : undefined;
+        if (processed) {
+            acknowledgements.set(writeSequence, processed);
+            void processed.promise.catch(() => undefined);
+        }
+        const written = new Promise((resolve, reject) => child.stdin.write(`${JSON.stringify(message)}\n`, (error) => error ? (acknowledgements.delete(writeSequence), reject(error)) : resolve()));
+        return processed ? written.then(() => processed.promise) : written;
+    };
+    const control = (type, payload) => {
+        const frame = { v: 1, generation: options.generation, sequence: ++outbound, type, payload };
+        if (!bounded(frame) || !child.connected)
+            return Promise.reject(new CompilerWorkerHostError("protocol"));
+        return new Promise((resolve, reject) => child.send(frame, (error) => (error ? reject(error) : resolve())));
+    };
+    return {
+        generation: options.generation,
+        ready: ready.promise,
+        async replay(frames) {
+            await control("handshake", {});
+            await ready.promise;
+            for (const frame of frames)
+                await write(frame);
+        },
+        forward(message) {
+            if (!("id" in message))
+                return write(message, true).then(() => undefined);
+            if (message.id === undefined)
+                return Promise.reject(new CompilerWorkerHostError("protocol"));
+            const result = deferred();
+            const id = message.id;
+            pending.set(id, result);
+            void write(message).catch((error) => {
+                pending.delete(id);
+                result.reject(error);
+            });
+            return result.promise;
+        },
+        cancel(id) {
+            if (!pending.has(id))
+                return false;
+            void write({ jsonrpc: "2.0", method: "notifications/cancelled", params: { requestId: id } }, true).catch(() => undefined);
+            return true;
+        },
+        async snapshot() {
+            await Promise.all([...acknowledgements.values()].map(({ promise }) => promise));
+            const result = deferred();
+            snapshots.push(result);
+            await control("snapshot", {});
+            return (await result.promise).payload;
+        },
+        terminate: () => {
+            child.kill("SIGKILL");
+        },
+        reap: () => closed,
+        async shutdown(trigger) {
+            await control("shutdown", { trigger }).catch(() => undefined);
+            child.stdin?.end();
+            await closed;
+            return "complete";
+        },
+    };
+}
+export class CompilerWorkerHost {
+    spawn;
+    timeoutMs;
+    lifecycle;
+    generation = 0;
+    sequence = 0;
+    child;
+    starting;
+    active = new Map();
+    leases = new Map();
+    initialization = [];
+    activity = 0;
+    parentWork = 0;
+    parentAdmission = "open";
+    idleTimer;
+    retiring;
+    constructor(spawn, timeoutMs = 10_000, lifecycle = {}) {
+        this.spawn = spawn;
+        this.timeoutMs = timeoutMs;
+        this.lifecycle = lifecycle;
+    }
+    now() {
+        return (this.lifecycle.now ?? Date.now)();
+    }
+    // prettier-ignore
+    pruneLeases() { const now = this.now(); for (const [id, expiry] of this.leases)
+        if (expiry <= now)
+            this.leases.delete(id); }
+    // prettier-ignore
+    addLease(id) { if (typeof id !== "string" || !id || !bounded(id))
+        return; this.pruneLeases(); this.leases.set(id, this.now() + (this.lifecycle.leaseTtlMs ?? 15 * 60_000)); while (this.leases.size > (this.lifecycle.leaseLimit ?? 128))
+        this.leases.delete(this.leases.keys().next().value); }
+    // prettier-ignore
+    scheduleIdle() { clearTimeout(this.idleTimer); const ttl = this.lifecycle.idleTtlMs ?? 0; if (ttl > 0 && this.child)
+        this.idleTimer = setTimeout(() => { this.retiring = this.recycle(this.activity).catch(async () => { const child = this.child; await child?.reap().catch(() => undefined); if (this.child === child)
+            this.child = undefined; }).finally(() => { this.retiring = undefined; }); }, ttl); }
+    // prettier-ignore
+    static quiescent(value) { return value.runtime_admission === "open" && value.project_admission === "open" && ["active_requests", "active_sends", "active_operations", "queued_operations", "completion_critical_operations"].every((key) => value[key] === 0) && value.mutation_history === false; }
+    // prettier-ignore
+    async recycle(activity) { this.pruneLeases(); const child = this.child, generation = this.generation, sequence = this.sequence; if (!child || this.parentWork || this.leases.size || child.generation !== generation)
+        return this.scheduleIdle(); const first = await child.snapshot(); if (!CompilerWorkerHost.quiescent(first) || activity !== this.activity || sequence !== this.sequence)
+        return this.scheduleIdle(); this.parentAdmission = "closed"; const second = await child.snapshot(); if (child !== this.child || generation !== this.generation || sequence !== this.sequence || activity !== this.activity || !CompilerWorkerHost.quiescent(second)) {
+        this.parentAdmission = "open";
+        return this.scheduleIdle();
+    } await this.stopChild(child, "requested"); emitCompilerWorkerEvent({ kind: "idle", generation }); this.parentAdmission = "open"; }
+    // prettier-ignore
+    async stopChild(child, trigger) { const completion = child.shutdown(trigger); try {
+        await within(completion, this.timeoutMs);
+        if (this.child === child)
+            this.child = undefined;
+        return "complete";
+    }
+    catch {
+        const snapshot = await child.snapshot().catch(() => undefined);
+        if (snapshot?.completion_critical_operations) {
+            await completion;
+            if (this.child === child)
+                this.child = undefined;
+            return "complete";
+        }
+        child.terminate();
+        await child.reap().catch(() => undefined);
+        if (this.child === child)
+            this.child = undefined;
+        return "forced";
+    } }
+    async start(initialization) {
+        if (this.child)
+            return { generation: this.child.generation, sequence: this.sequence };
+        if (this.starting)
+            return this.starting;
+        this.starting = (async () => {
+            let child;
+            try {
+                const envelope = initialization.length === 2
+                    ? await startCompilerWorker({
+                        frames: initialization,
+                        timeoutMs: this.timeoutMs,
+                        spawn: () => (child = this.spawn(++this.generation)),
+                    })
+                    : await (async () => {
+                        child = this.spawn(++this.generation);
+                        await child.replay([]);
+                        const decoded = decodeCompilerWorkerEnvelope(await within(child.ready, this.timeoutMs));
+                        if (!decoded.ok || decoded.value.type !== "ready")
+                            throw new Error();
+                        return decoded.value;
+                    })();
+                if (!child || envelope.generation !== child.generation)
+                    throw new Error();
+                this.child = child;
+                this.sequence = envelope.sequence;
+                this.parentAdmission = "open";
+                this.scheduleIdle();
+                return { generation: child.generation, sequence: this.sequence };
+            }
+            catch {
+                child?.terminate();
+                await child?.reap().catch(() => undefined);
+                throw new CompilerWorkerHostError("startup");
+            }
+        })().finally(() => {
+            this.starting = undefined;
+        });
+        return this.starting;
+    }
+    async forward(message) {
+        if (!bounded(message))
+            throw new CompilerWorkerHostError("protocol");
+        await this.retiring;
+        this.activity += 1;
+        await this.start(this.initialization.length === 2 ? this.initialization : []);
+        this.parentWork += 1;
+        const id = "id" in message ? message.id : undefined;
+        if (id !== undefined)
+            this.active.set(id, this.generation);
+        try {
+            const settled = await this.child.forward(message);
+            if ("method" in message && message.method === "initialize")
+                this.initialization = [message];
+            if ("method" in message &&
+                message.method === "notifications/initialized" &&
+                this.initialization.length === 1)
+                this.initialization.push(message);
+            if (!settled)
+                return undefined;
+            const payload = settled.payload;
+            if (settled.generation !== this.generation ||
+                settled.sequence <= this.sequence ||
+                payload.request_id !== id ||
+                !payload.message)
+                throw new CompilerWorkerHostError("protocol");
+            this.sequence = settled.sequence;
+            const response = payload.message;
+            const result = "result" in response ? response.result : undefined;
+            this.addLease(result?.operation_id ??
+                result?.structuredContent?.operation_id);
+            return response;
+        }
+        catch (error) {
+            if (error instanceof CompilerWorkerHostError && error.kind === "worker_exit") {
+                const child = this.child;
+                await child?.reap().catch(() => undefined);
+                if (this.child === child)
+                    this.child = undefined;
+                emitCompilerWorkerEvent({
+                    kind: "crash",
+                    generation: child?.generation ?? this.generation,
+                });
+                const params = "params" in message
+                    ? message.params
+                    : undefined;
+                const operationId = params?.name === "ast_apply_operation" ? params.arguments?.operation_id : undefined;
+                if (typeof operationId === "string") {
+                    this.addLease(operationId);
+                    const correlationId = randomUUID();
+                    emitCompilerWorkerEvent({
+                        kind: "ambiguity",
+                        generation: child?.generation ?? this.generation,
+                        correlationId,
+                        count: this.leases.size,
+                    });
+                    throw new CompilerWorkerHostError("ambiguous_apply", {
+                        correlation_id: correlationId,
+                        expires_at: this.leases.get(operationId),
+                    });
+                }
+            }
+            throw error instanceof CompilerWorkerHostError
+                ? error
+                : new CompilerWorkerHostError("worker_exit");
+        }
+        finally {
+            if (id !== undefined)
+                this.active.delete(id);
+            this.parentWork -= 1;
+            this.scheduleIdle();
+        }
+    }
+    cancel(id) {
+        if (this.active.get(id) !== this.generation || !this.child)
+            return "not_found";
+        return this.child.cancel(id) ? "forwarded" : "not_found";
+    }
+    async shutdown(trigger) {
+        clearTimeout(this.idleTimer);
+        await this.starting?.catch(() => undefined);
+        if (!this.child)
+            return "complete";
+        const child = this.child;
+        this.parentAdmission = "closed";
+        return this.stopChild(child, trigger);
+    }
+    snapshot() {
+        this.pruneLeases();
+        return {
+            generation: this.generation,
+            sequence: this.sequence,
+            state: this.child ? "ready" : this.starting ? "starting" : "idle",
+            active_requests: this.active.size,
+            parent_work: this.parentWork,
+            parent_admission: this.parentAdmission,
+            lease_tombstones: this.leases.size,
+        };
+    }
+}
+export async function runSupervisedStdioServer() {
+    const entry = fileURLToPath(new URL("../compiler-worker-entry.js", import.meta.url));
+    const policy = readRuntimePolicy(process.env);
+    const host = new CompilerWorkerHost((generation) => spawnCompilerWorkerProcess({ generation, workerEntryPath: entry, environment: process.env }), 10_000, { idleTtlMs: policy.compilerWorkerIdleTtlMs });
+    const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    const relay = async (line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        // prettier-ignore
+        if ("method" in message && message.method === "notifications/cancelled") {
+            const id = message.params?.requestId;
+            if ((typeof id === "string" || typeof id === "number") && bounded(id))
+                host.cancel(id);
+            return;
+        }
+        try {
+            const response = await host.forward(message);
+            if (response)
+                process.stdout.write(`${JSON.stringify(response)}\n`);
+        }
+        catch (error) {
+            if ("id" in message) {
+                const ambiguous = error instanceof CompilerWorkerHostError &&
+                    error.kind === "ambiguous_apply" &&
+                    error.recovery;
+                const rendered = ambiguous
+                    ? renderPublicError(new PublicOperationalError("AMBIGUOUS_APPLY", "The apply outcome is ambiguous."), ambiguous.correlation_id).envelope.error
+                    : undefined;
+                process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: rendered?.message ?? "Compiler worker request failed.", ...(ambiguous ? { data: { code: "AMBIGUOUS_APPLY", ...ambiguous } } : {}) } })}\n`);
+            }
+        }
+    };
+    lines.on("line", (line) => void relay(line));
+    lines.once("close", () => void host.shutdown("parent_exit"));
+    return { shutdown: () => host.shutdown("requested"), snapshot: () => host.snapshot() };
+}

package/dist/services/compiler-worker-protocol.js

@@ -0,0 +1,95 @@
+import { Buffer } from "node:buffer";
+const FIELDS = new Set(["v", "generation", "sequence", "type", "payload"]);
+const TYPES = new Set(["handshake", "snapshot", "shutdown", "ready", "settled", "lease", "exit"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function decodeCompilerWorkerEnvelope(frame) {
+    if (Buffer.byteLength(frame) > 256 * 1024) {
+        return { ok: false, reason: "oversized" };
+    }
+    let value;
+    try {
+        value = JSON.parse(frame);
+    }
+    catch {
+        return { ok: false, reason: "malformed" };
+    }
+    if (!isRecord(value))
+        return { ok: false, reason: "invalid_envelope" };
+    if (Object.keys(value).some((key) => !FIELDS.has(key)))
+        return { ok: false, reason: "unknown_field" };
+    if (value.v !== 1)
+        return { ok: false, reason: "version_drift" };
+    if (typeof value.type !== "string" || !TYPES.has(value.type)) {
+        return { ok: false, reason: "unknown_type" };
+    }
+    if (!Number.isSafeInteger(value.generation) ||
+        value.generation < 1 ||
+        !Number.isSafeInteger(value.sequence) ||
+        value.sequence < 1 ||
+        !isRecord(value.payload)) {
+        return { ok: false, reason: "invalid_envelope" };
+    }
+    return { ok: true, value };
+}
+export function validateInitializationReplay(frames) {
+    if (frames.length < 2)
+        return { ok: false, reason: "missing_replay" };
+    if (frames.length > 2)
+        return { ok: false, reason: "unexpected_replay" };
+    const [request, notification] = frames;
+    if (!isRecord(request) ||
+        request.method !== "initialize" ||
+        !("id" in request) ||
+        !isRecord(notification) ||
+        notification.method !== "notifications/initialized" ||
+        "id" in notification) {
+        return { ok: false, reason: "missing_replay" };
+    }
+    if (Buffer.byteLength(JSON.stringify(frames)) > 256 * 1024) {
+        return { ok: false, reason: "oversized_replay" };
+    }
+    return { ok: true, frames: [request, notification] };
+}
+export class CompilerWorkerStartupError extends Error {
+    reason;
+    constructor(reason) {
+        super("Compiler worker startup failed.");
+        this.reason = reason;
+    }
+}
+async function attempt(options, frames) {
+    const child = await options.spawn();
+    let timeout;
+    try {
+        await child.replay(frames);
+        const timedOut = new Promise((_, reject) => {
+            timeout = setTimeout(() => reject(new CompilerWorkerStartupError("timeout")), options.timeoutMs ?? 10_000);
+        });
+        const decoded = decodeCompilerWorkerEnvelope(await Promise.race([child.ready, timedOut]));
+        if (!decoded.ok || decoded.value.type !== "ready")
+            throw new CompilerWorkerStartupError("protocol");
+        return decoded.value;
+    }
+    catch (error) {
+        child.terminate();
+        await child.reap();
+        throw error;
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    }
+}
+export async function startCompilerWorker(options) {
+    const replay = validateInitializationReplay(options.frames);
+    if (!replay.ok)
+        throw new CompilerWorkerStartupError(replay.reason);
+    try {
+        return await attempt(options, replay.frames);
+    }
+    catch {
+        return attempt(options, replay.frames);
+    }
+}

package/dist/services/operations.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { LanguageVariant, Node, ScriptTarget, SyntaxKind, ts } from "ts-morph";
 import { compareDiagnostics, normalizeDiagnostic, } from "./diagnostics.js";
-import { createFreshProject, findDeclarationByName, getSourceFileOrThrow, invalidateProjectIfIdle, withProjectOperation, } from "./project.js";
+import { createFreshProject, findDeclarationByName, getSourceFileOrThrow, invalidateProjectIfIdle, recordProjectMutationHistory, withProjectOperation, } from "./project.js";
 import { NO_REQUEST_CONTEXT } from "./request-context.js";
 import { executableDeclaration } from "./symbols.js";
 import { buildClassScaffold } from "./scaffold.js";
@@ -290,6 +290,7 @@ async function createPlan(projectRootInput, kind, allowNewErrors, mutate, reques
         };
         operationContext.checkpoint();
         operations.set(operationId, record);
+        recordProjectMutationHistory();
         retainedOperationId = operationId;
         await operationTestHooks.afterRetain?.(operationId);
         return publicOperation(record);
@@ -846,6 +847,7 @@ export function importOperationRecord(persisted, expectedPlanHash) {
     }
     pruneOperations();
     operations.set(record.operation_id, record);
+    recordProjectMutationHistory();
     return publicOperation(record);
 }
 export function setOperationTestHooksForTests(hooks) {

package/dist/services/project.js

@@ -23,6 +23,7 @@ const projectRoots = new WeakMap();
 let projectSessionAccessSequence = 0n;
 let projectRuntimePolicy;
 let projectRuntimeAdmission = "open";
+let projectMutationHistory = false;
 function nextProjectSessionAccessSequence() {
     projectSessionAccessSequence += 1n;
     return projectSessionAccessSequence;
@@ -791,12 +792,17 @@ export function clearProjectSessions() {
     projectSessionAccessSequence = 0n;
     projectRuntimePolicy = undefined;
     projectRuntimeAdmission = "open";
+    projectMutationHistory = false;
+}
+export function recordProjectMutationHistory() {
+    projectMutationHistory = true;
 }
 export function prepareProjectRuntimeForStartup() {
     if (projectSessions.size !== 0) {
         throw new Error("Cannot start a project runtime while sessions remain open.");
     }
     projectRuntimeAdmission = "open";
+    projectMutationHistory = false;
 }
 export function getProjectRuntimeShutdownSnapshot() {
     let activeOperations = 0;
@@ -814,6 +820,7 @@ export function getProjectRuntimeShutdownSnapshot() {
         active_operations: activeOperations,
         queued_operations: queuedOperations,
         completion_critical_operations: completionCriticalOperations,
+        mutation_history: projectMutationHistory,
     });
 }
 export function beginProjectShutdown() {

package/dist/services/public-errors.js

@@ -15,6 +15,7 @@ export const PUBLIC_ERROR_CODES = Object.freeze([
     "STALE_WORKSPACE",
     "INCOMPLETE_EVIDENCE",
     "MUTATION_BLOCKED",
+    "AMBIGUOUS_APPLY",
     "CONFLICT",
     "INTERNAL_ERROR",
 ]);
@@ -38,6 +39,7 @@ const FIXED_PUBLIC_MESSAGES = Object.freeze({
     STALE_WORKSPACE: "The workspace changed. Retry the operation.",
     INCOMPLETE_EVIDENCE: "The required compiler evidence is incomplete.",
     MUTATION_BLOCKED: "The mutation is blocked.",
+    AMBIGUOUS_APPLY: "The apply outcome is ambiguous. Inspect the operation receipt before retrying.",
     CONFLICT: "The operation conflicts with current state.",
     INTERNAL_ERROR: INTERNAL_ERROR_MESSAGE,
 });
@@ -178,7 +180,9 @@ function codedError(error) {
                 return null;
             return {
                 code: code,
-                message: sanitizePublicText(message),
+                message: code === "AMBIGUOUS_APPLY"
+                    ? FIXED_PUBLIC_MESSAGES.AMBIGUOUS_APPLY
+                    : sanitizePublicText(message),
             };
         }
         if (!(error instanceof Error))
@@ -236,9 +240,8 @@ function serializePublicError(code, message, correlationId) {
     };
     return { envelope, text: JSON.stringify(envelope) };
 }
-export function renderPublicError(error) {
+export function renderPublicError(error, correlationId = randomUUID()) {
     const classified = classifyPublicError(error);
-    const correlationId = randomUUID();
     const initial = serializePublicError(classified.code, classified.message, correlationId);
     if (Buffer.byteLength(initial.text, "utf8") <= MAX_PUBLIC_ERROR_RESPONSE_BYTES) {
         return initial;

package/dist/services/runtime-logger.js

@@ -48,3 +48,8 @@ export function renderToolFailureEvent(input) {
 export function emitToolFailureEvent(input) {
     process.stderr.write(`${renderToolFailureEvent(input)}\n`);
 }
+// prettier-ignore
+export function emitCompilerWorkerEvent(input) {
+    const event = { event: "compiler_worker", version: 1, kind: input.kind, generation: Number.isSafeInteger(input.generation) ? input.generation : 0, correlation_id: input.correlationId && UUID_PATTERN.test(input.correlationId) ? input.correlationId : undefined, count: input.count === undefined ? undefined : Math.max(0, Math.min(128, Math.trunc(input.count))) };
+    process.stderr.write(`${JSON.stringify(event)}\n`);
+}

package/dist/services/runtime-policy.js

@@ -1,9 +1,12 @@
+import path from "node:path";
 export const RUNTIME_POLICY_ENV_KEYS = Object.freeze([
     "AST_MAX_PROJECT_SESSIONS",
     "AST_MAX_QUEUED_OPERATIONS_PER_PROJECT",
     "AST_QUEUE_WAIT_TIMEOUT_MS",
     "AST_OPERATION_DEADLINE_MS",
     "AST_SHUTDOWN_DRAIN_TIMEOUT_MS",
+    "AST_COMPILER_WORKER_MODE",
+    "AST_COMPILER_WORKER_IDLE_TTL_MS",
 ]);
 function parseBoundedInteger(rawValue, defaultValue, minimum, maximum) {
     if (rawValue === undefined)
@@ -26,12 +29,22 @@ export function parseRuntimePolicy(environment) {
     const queueWaitTimeoutMs = parseBoundedInteger(environment.AST_QUEUE_WAIT_TIMEOUT_MS, 30_000, 100, 300_000);
     const operationDeadlineMs = parseBoundedInteger(environment.AST_OPERATION_DEADLINE_MS, 120_000, 1_000, 900_000);
     const shutdownDrainTimeoutMs = parseBoundedInteger(environment.AST_SHUTDOWN_DRAIN_TIMEOUT_MS, 10_000, 100, 60_000);
+    const rawWorkerMode = environment.AST_COMPILER_WORKER_MODE;
+    const compilerWorkerMode = rawWorkerMode === "supervised" ? "supervised" : "in_process";
+    const compilerWorkerModeReason = rawWorkerMode === undefined
+        ? "default"
+        : rawWorkerMode === "in_process" || rawWorkerMode === "supervised"
+            ? "configured"
+            : "invalid_mode";
+    const compilerWorkerIdleTtlMs = parseBoundedInteger(environment.AST_COMPILER_WORKER_IDLE_TTL_MS, 60_000, 0, 86_400_000);
     const reasons = Object.freeze({
         AST_MAX_PROJECT_SESSIONS: maxProjectSessions.reason,
         AST_MAX_QUEUED_OPERATIONS_PER_PROJECT: maxQueuedOperationsPerProject.reason,
         AST_QUEUE_WAIT_TIMEOUT_MS: queueWaitTimeoutMs.reason,
         AST_OPERATION_DEADLINE_MS: operationDeadlineMs.reason,
         AST_SHUTDOWN_DRAIN_TIMEOUT_MS: shutdownDrainTimeoutMs.reason,
+        AST_COMPILER_WORKER_MODE: compilerWorkerModeReason,
+        AST_COMPILER_WORKER_IDLE_TTL_MS: compilerWorkerIdleTtlMs.reason,
     });
     return Object.freeze({
         maxProjectSessions: maxProjectSessions.value,
@@ -39,9 +52,57 @@ export function parseRuntimePolicy(environment) {
         queueWaitTimeoutMs: queueWaitTimeoutMs.value,
         operationDeadlineMs: operationDeadlineMs.value,
         shutdownDrainTimeoutMs: shutdownDrainTimeoutMs.value,
+        compilerWorkerMode,
+        compilerWorkerIdleTtlMs: compilerWorkerIdleTtlMs.value,
         reasons,
     });
 }
+const WORKER_PATH_KEYS = ["HOME", "XDG_CACHE_HOME", "AST_SYMBOL_INDEX_CACHE_ROOT"];
+const WORKER_ENV_KEYS = [
+    ...WORKER_PATH_KEYS,
+    "AST_SYMBOL_INDEX_PERSISTENCE",
+    "AST_SYMBOL_INDEX_BUSY_TIMEOUT_MS",
+];
+const MAX_WORKER_ENV_VALUE_LENGTH = 4096;
+function validEnvironmentString(value) {
+    return (typeof value === "string" &&
+        value.length <= MAX_WORKER_ENV_VALUE_LENGTH &&
+        !value.includes("\0"));
+}
+export function createCompilerWorkerSpawnSpec(workerEntryPath, environment) {
+    const projected = {};
+    for (const key of WORKER_ENV_KEYS) {
+        const value = environment[key];
+        if (value === undefined)
+            continue;
+        if (!validEnvironmentString(value))
+            return { ok: false, reason: "invalid_environment" };
+        const isPath = WORKER_PATH_KEYS.includes(key);
+        const invalidMode = key === "AST_SYMBOL_INDEX_PERSISTENCE" && !["disabled", "canary", "enabled"].includes(value);
+        const invalidTimeout = key === "AST_SYMBOL_INDEX_BUSY_TIMEOUT_MS" &&
+            parseBoundedInteger(value, 1_000, 1, 60_000).reason !== "configured";
+        if ((isPath && (!path.isAbsolute(value) || path.normalize(value) !== value)) ||
+            invalidMode ||
+            invalidTimeout) {
+            return { ok: false, reason: "invalid_environment" };
+        }
+        projected[key] = value;
+    }
+    const policy = parseRuntimePolicy(environment);
+    Object.assign(projected, {
+        AST_MAX_PROJECT_SESSIONS: String(policy.maxProjectSessions),
+        AST_MAX_QUEUED_OPERATIONS_PER_PROJECT: String(policy.maxQueuedOperationsPerProject),
+        AST_QUEUE_WAIT_TIMEOUT_MS: String(policy.queueWaitTimeoutMs),
+        AST_OPERATION_DEADLINE_MS: String(policy.operationDeadlineMs),
+        AST_SHUTDOWN_DRAIN_TIMEOUT_MS: String(policy.shutdownDrainTimeoutMs),
+    });
+    return {
+        ok: true,
+        command: process.execPath,
+        args: [workerEntryPath],
+        options: { shell: false, env: projected },
+    };
+}
 export function readRuntimePolicy(environment = process.env) {
     return parseRuntimePolicy(environment);
 }

package/dist/worker-runtime.js

@@ -0,0 +1,126 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { beginProjectShutdown, closeDrainedProjectSessions, getProjectRuntimeShutdownSnapshot, prepareProjectRuntimeForStartup, waitForProjectCompletionCriticalOperationsToDrain, waitForProjectOperationsToDrain, } from "./services/project.js";
+import { RuntimeActivityTracker } from "./services/runtime-activity.js";
+import { readRuntimePolicy } from "./services/runtime-policy.js";
+import { emitIncompleteShutdownEvent, ShutdownCoordinator, } from "./services/shutdown.js";
+function emitShutdownFailureEvent() {
+    process.stderr.write(`${JSON.stringify({ event: "shutdown_failed", version: 1 })}\n`);
+}
+export async function runStdioServer(options = {}) {
+    if (options.server && !options.runtimeActivity) {
+        throw new Error("An injected MCP server requires its runtime activity tracker.");
+    }
+    prepareProjectRuntimeForStartup();
+    const runtimeActivity = options.runtimeActivity ?? new RuntimeActivityTracker();
+    runtimeActivity.prepareForStartup();
+    const server = options.server ?? createServer({ runtimeActivity });
+    const transport = options.transport ?? new StdioServerTransport();
+    const send = transport.send.bind(transport);
+    transport.send = (message, sendOptions) => runtimeActivity.trackSend(() => send(message, sendOptions));
+    const runtimePolicy = options.runtimePolicy ?? readRuntimePolicy();
+    const installProcessHandlers = options.installProcessHandlers ?? true;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const protocol = server.server;
+    const previousTransportClose = protocol.onclose;
+    let listenersInstalled = false;
+    let terminalHandlerInstalled = false;
+    const onSigint = () => requestFromRuntime("sigint");
+    const onSigterm = () => requestFromRuntime("sigterm");
+    const onStdinEnd = () => requestFromRuntime("stdin_eof");
+    const onStdinClose = () => requestFromRuntime("stdin_eof");
+    const onTransportClose = () => {
+        previousTransportClose?.();
+        requestFromRuntime("transport_closed");
+    };
+    const removeLifecycleListeners = () => {
+        if (listenersInstalled) {
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+            process.stdin.off("end", onStdinEnd);
+            process.stdin.off("close", onStdinClose);
+            listenersInstalled = false;
+        }
+        if (protocol.onclose === onTransportClose)
+            protocol.onclose = previousTransportClose;
+    };
+    const coordinator = new ShutdownCoordinator({
+        drainTimeoutMs: runtimePolicy.shutdownDrainTimeoutMs,
+        stopAdmissionAndCancel: () => {
+            runtimeActivity.beginShutdown();
+            return beginProjectShutdown();
+        },
+        getDrainSnapshot: getProjectRuntimeShutdownSnapshot,
+        waitForDrain: async () => {
+            await Promise.all([waitForProjectOperationsToDrain(), runtimeActivity.waitForIdle()]);
+        },
+        waitForCompletionCriticalOperationsToDrain: waitForProjectCompletionCriticalOperationsToDrain,
+        closeMcp: async () => {
+            await server.close();
+        },
+        closeProjects: closeDrainedProjectSessions,
+        emitIncompleteShutdown: emitIncompleteShutdownEvent,
+        onCompletionCriticalWait: options.onCompletionCriticalWait,
+    });
+    let lifecycleCompletion;
+    function requestShutdown(trigger) {
+        lifecycleCompletion ??= coordinator.shutdown(trigger).finally(removeLifecycleListeners);
+        return lifecycleCompletion;
+    }
+    function requestFromRuntime(trigger) {
+        try {
+            options.onRuntimeTrigger?.(trigger);
+        }
+        catch {
+            // Runtime observation is non-authoritative and must never interrupt shutdown.
+        }
+        const completion = requestShutdown(trigger);
+        if (terminalHandlerInstalled)
+            return;
+        terminalHandlerInstalled = true;
+        void completion
+            .then((result) => {
+            if (result.state === "forced_noncritical")
+                exit(1);
+        })
+            .catch(() => {
+            emitShutdownFailureEvent();
+            exit(1);
+        });
+    }
+    protocol.onclose = onTransportClose;
+    if (installProcessHandlers) {
+        process.on("SIGINT", onSigint);
+        process.on("SIGTERM", onSigterm);
+        process.stdin.once("end", onStdinEnd);
+        process.stdin.once("close", onStdinClose);
+        listenersInstalled = true;
+    }
+    try {
+        await server.connect(transport);
+    }
+    catch (error) {
+        await requestShutdown("requested").catch(() => undefined);
+        throw error;
+    }
+    if (options.logStartup ?? true)
+        process.stderr.write("ast-mcp-server running over stdio.\n");
+    return Object.freeze({
+        shutdown: (trigger = "requested") => requestShutdown(trigger),
+        shutdownGraceMs: runtimePolicy.shutdownDrainTimeoutMs,
+        snapshot: () => {
+            const runtime = runtimeActivity.snapshot(), project = getProjectRuntimeShutdownSnapshot();
+            return Object.freeze({
+                runtime_admission: runtime.admission,
+                active_requests: runtime.active_requests,
+                active_sends: runtime.active_sends,
+                project_admission: project.admission,
+                session_count: project.session_count,
+                active_operations: project.active_operations,
+                queued_operations: project.queued_operations,
+                completion_critical_operations: project.completion_critical_operations,
+                mutation_history: project.mutation_history,
+            });
+        },
+    });
+}

package/docs/support.md

@@ -1,20 +1,20 @@
 # Support policy
 
-This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.10.0 and the local `0.11.1` recovery candidate.
+This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.10.0 and the local `0.11.2` release candidate.
 
 ## Supported release target
 
 | Environment                                                                   | Status      | Contract                                                                                      |
 | ----------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------- |
 | Linux x64 with required GNU coreutils and procfs, Node.js 22.5.0              | Historical  | Immutable v0.8.1 release evidence; not the runtime floor of the published or candidate lines. |
-| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Published v0.10.0 and local 0.11.1 matrices, each bound to its own package and tree bytes.    |
-| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.10.0 and local 0.11.1 matrices, each bound to its own package and tree bytes.    |
+| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Published v0.10.0 and local 0.11.2 matrices, each bound to its own package and tree bytes.    |
+| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.10.0 and local 0.11.2 matrices, each bound to its own package and tree bytes.    |
 | Other Linux architectures or systems without the required filesystem features | Unverified  | Not supported until equivalent architecture, mutation, and filesystem-publication gates pass. |
 | macOS                                                                         | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass. |
 | Windows                                                                       | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass. |
 | Remote, untrusted, or multi-tenant service use                                | Unsupported | No network authentication, sandbox, or tenant-isolation boundary is provided.                 |
 
-The local `0.11.1` recovery candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.10.0 retains its immutable `>=22.13.0` metadata and exact Node.js 22.13.0/24 release evidence. The earlier v0.8.1 Node.js 22.5.0/24 matrix remains historical evidence for those bytes only. A future runtime satisfying an engine range is not automatically a verified release target.
+The local `0.11.2` release candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.10.0 retains its immutable `>=22.13.0` metadata and exact Node.js 22.13.0/24 release evidence. The earlier v0.8.1 Node.js 22.5.0/24 matrix remains historical evidence for those bytes only. A future runtime satisfying an engine range is not automatically a verified release target.
 
 The checked-evidence freezer requires GNU coreutils 9.7 `mv` with `--update=none-fail`, `--no-copy`, and `--no-target-directory`. Managed setup-file mutation additionally requires that same `mv` with `--exchange`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, `O_DIRECTORY`, and `O_NOFOLLOW`. It fails closed when any verified Linux primitive is unavailable. Equivalent publication, exchange, descriptor-link, and descriptor-relative mutation semantics have not been verified on other operating systems or architectures.
 
@@ -32,9 +32,25 @@ The server does not provide:
 
 Operation locks coordinate cooperating same-user processes. They do not stop editors, network filesystems, or hostile same-user writers. Report-set freezer coordination likewise assumes cooperating same-UID processes and cannot defend checked evidence against a malicious process with the same filesystem authority. The freezer guarantees no-replace atomic visibility of the checked directory; it does not claim persistence across sudden power loss because parent-directory `fsync` durability is not established.
 
+## Optional supervised compiler worker
+
+The default and rollback remain `AST_COMPILER_WORKER_MODE=in_process`. Explicit `supervised` mode keeps one lightweight stdio parent connected to one disposable compiler child per connection:
+
+```bash
+AST_COMPILER_WORKER_MODE=supervised \
+AST_COMPILER_WORKER_IDLE_TTL_MS=60000 \
+ast-mcp-server
+```
+
+The parent waits for `ready` before replaying bounded initialization state. Generation-affine forwarding and cancellation reject stale settlements and do not retry forwarded calls. Recycling requires stable parent and child quiescence; mutation history, live leases, and completion-critical work keep the child pinned. Parent death closes admission and permits only completion-critical drain before exit.
+
+Set the TTL to `0` to disable recycling without removing the relay, or select `in_process` to remove the worker boundary. No shared daemon, pool, cross-client deduplication, default promotion, or automatic mutation-plan repair is provided.
+
+The scoped Linux evidence passed on exact Node.js 22.13.0 and the governed Node.js 24 line: three parents each completed three load/idle/respawn cycles with at least 80% PSS-delta reclamation and no upward trend. Respawns retained the compiler fingerprint, recorded six SQLite hits, reused exactly 400 files, rebuilt zero, and returned equivalent reads. Diagnostics remained bounded and redacted, and parent-death inspection found zero orphan processes. These results do not establish support for macOS, Windows, or other Linux environments.
+
 ## Symbol-index persistence
 
-Published v0.10.0 and the local `0.11.1` recovery candidate select native SQLite when the persistence setting is absent or explicitly `enabled`; operators requiring no persistent index state must set `disabled` explicitly:
+Published v0.10.0 and the local `0.11.2` release candidate select native SQLite when the persistence setting is absent or explicitly `enabled`; operators requiring no persistent index state must set `disabled` explicitly:
 
 ```bash
 AST_SYMBOL_INDEX_PERSISTENCE=disabled \
@@ -64,7 +80,7 @@ Both commands are bounded and path-free. Clear preflights the tree, refuses unsa
 
 ## Production-readiness acceptance
 
-The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0 or v0.9.1, the local 0.9.2 candidate, published v0.10.0, published-next v0.11.0, or the local v0.11.1 recovery candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes, the exact 0.9.2 matrix remains historical local-candidate evidence, the exact 0.10.0 matrix remains historical published-release evidence, and the exact 0.11.0 matrix remains historical evidence for its immutable published-next bytes before registry verification exposed verifier drift. A separate exact 0.11.1 release matrix is the recovery-candidate gate for current repository bytes under both supported runtime lines, including local-registry managed-asset verification; none of these matrices rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
+The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0 or v0.9.1, the local 0.9.2 candidate, published v0.10.0, published-next v0.11.0 or v0.11.1, or the local v0.11.2 release candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes, the exact 0.9.2 matrix remains historical local-candidate evidence, the exact 0.10.0 matrix remains historical published-release evidence, and the exact 0.11.0 and 0.11.1 matrices remain historical evidence for their immutable published-next bytes before public-registry verification exposed their distinct verifier defects. A separate exact 0.11.2 release matrix is the release-candidate gate for current repository bytes under both supported runtime lines, including supervised-worker lifecycle and reclamation evidence, deterministic CLI project-discovery fixture setup, local-registry managed-asset verification, and the public copied-runner dependency-closure regression; none of these matrices rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
 
 - zero semantic mismatches across disabled, cold, warm, restart, and rollback reads;
 - byte-identical real-repository status and worktree trees;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -49,7 +49,7 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "vitest run",
+    "test": "vitest run --exclude test/supervised-worker.integration.test.ts && yarn build && vitest run test/supervised-worker.integration.test.ts --no-file-parallelism",
     "test:watch": "vitest",
     "test:mcp": "yarn build && node scripts/mcp-smoke.mjs",
     "test:lifecycle": "yarn build && node scripts/mcp-lifecycle-smoke.mjs",
@@ -97,5 +97,5 @@
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   },
-  "gitHead": "7aee46639d887a406c20c10fd66de7fa179d9e92"
+  "gitHead": "f7b429670093bd9f43195979e395ccf418eb4ba2"
 }

package/skills/structural-code-editing/SKILL.md

@@ -18,7 +18,7 @@ Cargar este skill antes de navegar semánticamente, analizar impacto o referenci
 
 No forzar un roundtrip AST para Markdown, configuración, comentarios ni una edición textual trivial en un archivo ya conocido. Si las tools `ast_*` no están disponibles, declarar el fallback y no presentar búsquedas textuales como evidencia compiler-backed.
 
-The local 0.11.1 recovery candidate requires Node.js `>=22.13.0` and is verified with exact Node.js 22.13.0 plus the governed Node.js 24 line. Published v0.10.0 retains its immutable Node.js 22.13.0/24 release evidence.
+The local 0.11.2 release candidate requires Node.js `>=22.13.0` and is verified with exact Node.js 22.13.0 plus the governed Node.js 24 line. Published v0.10.0 retains its immutable Node.js 22.13.0/24 release evidence.
 
 ## Hard Rules
 

package/skills/structural-code-editing/releases.json

@@ -6,7 +6,7 @@
     "files": [
       {
         "path": "SKILL.md",
-        "sha256": "2729b30ff6b7344e6680c7ee02ab540bc6db9774ad7111f091cd356f8cc9d4ce"
+        "sha256": "18132b4b747d135e4ccfbca9e2190a9afb41e144cc06c31c5e6bc0f1571e11da"
       },
       {
         "path": "references/operations.md",