@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/editor/lsp/lspNodeAdapter.js

@@ -0,0 +1,230 @@
+// Node spawn adapter for the governed LSP process manager (Issue #1381, Epic #1491, ADR-0069 D2).
+// This is the only module in the lsp/ subdir that touches `node:child_process` and the filesystem;
+// the manager consumes the injected `LspSpawnFn` port so every lifecycle branch is testable against
+// the in-memory fake without a real subprocess.
+//
+// SECURITY BOUNDARY (FIX 8): the deny-by-default preflight (`isCommandAllowed`, I5), the workspace-root
+// containment check (I2), and the copy-only env allowlist (`buildSandboxEnv`) are the MANAGER's
+// responsibility — it calls `preflightSpawnEnv` and `resolveExecutableOutsideWorkspace` BEFORE ever
+// invoking the injected `LspSpawnFn`. `defaultLspSpawnFn` therefore assumes it is handed an
+// already-resolved, ABSOLUTE, allowlisted executable path plus the already-built sandbox env; it adds
+// only an ephemeral empty HOME (so the server cannot read or write the operator's real home) and the
+// process-group spawn/kill wiring. As defense-in-depth it asserts the executable is an absolute path,
+// so a future DIRECT caller that bypassed the manager's resolution cannot spawn a relative/bare name.
+// POSIX spawns detached and kills the whole process group; Windows kills the single child.
+import { spawn } from "node:child_process";
+import { accessSync, constants, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, isAbsolute, join, resolve as resolvePath } from "node:path";
+import { isCommandAllowed, buildSandboxEnv } from "@oscharko-dev/keiko-tools";
+import { isWithinWorkspace } from "@oscharko-dev/keiko-workspace";
+// Typed failure carrying only a content-free `LspProcessErrorCode` — never a path, server output, or
+// stack-derived message beyond the code itself (ADR-0069 D6).
+export class LspProcessError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "LspProcessError";
+        this.code = code;
+    }
+}
+function pathEntries(processEnv) {
+    const pathValue = processEnv.PATH ?? "";
+    return pathValue.length === 0 ? [] : pathValue.split(delimiter).filter(Boolean);
+}
+function executableExtensions(processEnv) {
+    if (process.platform !== "win32") {
+        return [""];
+    }
+    return (processEnv.PATHEXT ?? ".EXE;.CMD;.BAT;.COM")
+        .split(";")
+        .filter((value) => value.length > 0);
+}
+function probeCandidate(directory, name, ext) {
+    const candidate = resolvePath(resolvePath(directory), name + ext);
+    try {
+        accessSync(candidate, constants.X_OK);
+        return { path: candidate, real: realpathSync(candidate) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function realWorkspaceRoot(root) {
+    try {
+        return realpathSync(root);
+    }
+    catch {
+        return root;
+    }
+}
+// Mirrors `exec.ts assertExecutableOutsideWorkspace`: a candidate is rejected if EITHER its lexical
+// path OR its symlink-resolved real path lies inside the workspace, so a symlink planted in the
+// workspace cannot point at a workspace-external binary and bypass the check (ADR-0069 I2).
+function resolvesInsideWorkspace(candidate, lexicalRoot, realRoot) {
+    return (isWithinWorkspace(lexicalRoot, candidate.path) || isWithinWorkspace(realRoot, candidate.real));
+}
+// Resolves a bare executable name on the operator's PATH to an absolute real path that lies OUTSIDE
+// the workspace root (ADR-0069 I2/I5). Throws `EXECUTABLE_NOT_FOUND` when the name has a separator,
+// is absent from PATH, or resolves inside the workspace.
+export function resolveExecutableOutsideWorkspace(name, workspace, processEnv) {
+    if (name.length === 0 || name.includes("/") || name.includes("\\") || name.includes(" ")) {
+        throw new LspProcessError("EXECUTABLE_NOT_FOUND");
+    }
+    const lexicalRoot = workspace.root;
+    const realRoot = realWorkspaceRoot(lexicalRoot);
+    for (const directory of pathEntries(processEnv)) {
+        for (const ext of executableExtensions(processEnv)) {
+            const candidate = probeCandidate(directory, name, ext);
+            if (candidate === undefined) {
+                continue;
+            }
+            if (resolvesInsideWorkspace(candidate, lexicalRoot, realRoot)) {
+                throw new LspProcessError("EXECUTABLE_NOT_FOUND");
+            }
+            return candidate.real;
+        }
+    }
+    throw new LspProcessError("EXECUTABLE_NOT_FOUND");
+}
+// Creates an empty per-process HOME directory. The server child receives this as HOME/USERPROFILE so
+// it cannot read or write the operator's real home; `cleanup` removes it best-effort on dispose.
+export function createEphemeralHome() {
+    const path = mkdtempSync(join(tmpdir(), "keiko-lsp-home-"));
+    return {
+        path,
+        cleanup: () => {
+            try {
+                rmSync(path, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort: a failed cleanup of a temp directory must never block dispose.
+            }
+        },
+    };
+}
+// POSIX group kill: signals the whole process group (`-pid`) so the LSP server's grandchildren are
+// included (ADR-0069 D2). Windows has no process groups here, so the single child is killed. A failed
+// kill (process already gone) is swallowed; the escalation timer still owns the SIGKILL fallback.
+function nodeGroupKill(pid, child, signal) {
+    if (process.platform !== "win32") {
+        try {
+            process.kill(-pid, signal);
+            return;
+        }
+        catch {
+            // Group may already be gone; fall through to a direct child kill.
+        }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // The child may have already exited.
+    }
+}
+function safeKill(child, signal) {
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // The child may have already exited; the escalation timer owns the SIGKILL fallback.
+    }
+}
+// Escalates termination: SIGTERM, then SIGKILL after `gracePeriodMs` measured on the injected clock.
+// Resolves immediately if the child has already exited, or as soon as it exits during the grace
+// window (via the optional `whenExited` registration), or when the window elapses and SIGKILL is sent.
+// Resolving early on a mid-window exit is what lets a prompt shutdown avoid waiting the full grace
+// (ADR-0069 D4 / FIX 2). The child's own `kill` carries the POSIX-group-vs-Windows distinction (see
+// `defaultLspSpawnFn`), so this stays platform-agnostic and test-safe.
+export function escalateKill(child, gracePeriodMs, exited, scheduler = defaultKillScheduler, whenExited) {
+    safeKill(child, "SIGTERM");
+    if (exited()) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (sendKill) => {
+            if (settled)
+                return;
+            settled = true;
+            if (sendKill && !exited()) {
+                safeKill(child, "SIGKILL");
+            }
+            resolve();
+        };
+        whenExited?.(() => {
+            finish(false);
+        });
+        scheduler.setTimer(() => {
+            finish(true);
+        }, gracePeriodMs);
+    });
+}
+const defaultKillScheduler = {
+    setTimer: (callback, delayMs) => setTimeout(callback, delayMs).unref(),
+};
+function wrapChild(child) {
+    const stdin = child.stdin;
+    const stdout = child.stdout;
+    const stderr = child.stderr;
+    if (stdin === null || stdout === null || stderr === null) {
+        throw new LspProcessError("SPAWN_FAILED");
+    }
+    return {
+        stdin: { write: (chunk) => void stdin.write(chunk) },
+        stdout,
+        stderr,
+        pid: child.pid,
+        kill: (signal) => {
+            const pid = child.pid;
+            if (pid === undefined) {
+                safeKill(child, signal);
+                return;
+            }
+            nodeGroupKill(pid, child, signal);
+        },
+        onExit: (callback) => {
+            child.on("exit", (code) => {
+                callback(code);
+            });
+        },
+        onError: (callback) => {
+            child.on("error", callback);
+        },
+    };
+}
+// Default spawn adapter (ADR-0069 D2). The manager has already run the deny-by-default preflight (I5),
+// resolved the executable to an absolute workspace-external path (I2), and built the copy-only env;
+// this adapter substitutes an ephemeral HOME/USERPROFILE and spawns detached on POSIX so the manager
+// can group-kill grandchildren. As defense-in-depth (FIX 8) it rejects a non-absolute executable, so a
+// future caller that bypassed `resolveExecutableOutsideWorkspace` cannot spawn a bare/relative name.
+export const defaultLspSpawnFn = (executable, args, env, cwd) => {
+    if (!isAbsolute(executable)) {
+        throw new LspProcessError("EXECUTABLE_NOT_FOUND");
+    }
+    const home = createEphemeralHome();
+    const childEnv = { ...env, HOME: home.path, USERPROFILE: home.path };
+    const child = spawn(executable, [...args], {
+        cwd,
+        env: childEnv,
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: process.platform !== "win32",
+        windowsHide: true,
+    });
+    const wrapped = wrapChild(child);
+    wrapped.onExit(() => {
+        home.cleanup();
+    });
+    return wrapped;
+};
+// Convenience preflight used by the manager before it calls the injected spawn fn: proves the command
+// is allowlisted (I5) and builds the copy-only child env (no parent secrets leak). Returns the env on
+// success; throws `EXECUTABLE_NOT_FOUND` on a denied command.
+export function preflightSpawnEnv(rules, executable, args, processEnv, envAllowlist) {
+    const decision = isCommandAllowed(rules, executable, args);
+    if (!decision.allowed) {
+        throw new LspProcessError("EXECUTABLE_NOT_FOUND");
+    }
+    return buildSandboxEnv(processEnv, envAllowlist);
+}

package/dist/editor/lsp/lspProcessManager.d.ts

@@ -0,0 +1,24 @@
+import type { LanguageServiceOperation, LspLifecycleEvent, LspProcessConfig, LspProcessStatus } from "@oscharko-dev/keiko-contracts";
+import type { CommandRule } from "@oscharko-dev/keiko-tools";
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import type { LspSpawnFn } from "./lspNodeAdapter.js";
+import type { LspManagerLanguageProvider } from "./lspLanguageProvider.js";
+export interface LspProcessManagerDeps {
+    readonly config: LspProcessConfig;
+    readonly workspace: WorkspaceInfo;
+    readonly processEnv: NodeJS.ProcessEnv;
+    readonly commandRules: readonly CommandRule[];
+    readonly spawn?: LspSpawnFn | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly onLifecycleEvent?: ((event: LspLifecycleEvent) => void) | undefined;
+}
+export interface LspProcessManager {
+    getLspProcessStatus(): LspProcessStatus;
+    asLanguageProvider(languages: readonly string[], operations: readonly LanguageServiceOperation[]): LspManagerLanguageProvider;
+    sendRequest<T>(method: string, params: unknown, signal: AbortSignal): Promise<T>;
+    sendNotification(method: string, params: unknown): void;
+    onNotification(handler: (method: string, params: unknown) => void): void;
+    dispose(): Promise<void>;
+}
+export declare function createLspProcessManager(deps: LspProcessManagerDeps): LspProcessManager;
+//# sourceMappingURL=lspProcessManager.d.ts.map

package/dist/editor/lsp/lspProcessManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lspProcessManager.d.ts","sourceRoot":"","sources":["../../../src/editor/lsp/lspProcessManager.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,wBAAwB,EACxB,iBAAiB,EAEjB,gBAAgB,EAEhB,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAWnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAQtD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAE3E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC9E;AAED,MAAM,WAAW,iBAAiB;IAChC,mBAAmB,IAAI,gBAAgB,CAAC;IACxC,kBAAkB,CAChB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,UAAU,EAAE,SAAS,wBAAwB,EAAE,GAC9C,0BAA0B,CAAC;IAC9B,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjF,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACxD,cAAc,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAoHD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,qBAAqB,GAAG,iBAAiB,CAiBtF"}

package/dist/editor/lsp/lspProcessManager.js

@@ -0,0 +1,255 @@
+// Governed LSP process manager (Issue #1381, Epic #1491, ADR-0069 D2/D4/D5). A long-lived supervisor
+// for one external language-server child over stdio JSON-RPC: it runs the deny-by-default preflight,
+// spawns through the injected `LspSpawnFn`, drives the `initialize` handshake under a timeout, serves
+// requests under a per-request deadline plus AbortSignal cancellation, restarts on crash within a
+// rolling throttle window, and shuts the process down gracefully on dispose. Every state transition
+// emits a content-free `LspLifecycleEvent` (ADR-0069 I4/D6); no source text, paths, or method names
+// ever cross the audit boundary.
+import { createLspTransport } from "./lspTransport.js";
+import { LspFrameRejectError } from "./lspFrameCodec.js";
+import { LspProcessError, defaultLspSpawnFn, escalateKill, preflightSpawnEnv, resolveExecutableOutsideWorkspace, } from "./lspNodeAdapter.js";
+import { createLspRestartThrottle } from "./lspRestartThrottle.js";
+import { LspRpcCancelledError, LspRpcDisposedError, LspRpcTimeoutError, } from "./lspJsonRpcClient.js";
+import { buildLanguageProvider } from "./lspLanguageProvider.js";
+function supervisorOnCrash(ctx, crashGeneration) {
+    // A late `exit`/`error` from a child already superseded by a restart carries a stale generation;
+    // discard it so it cannot debit the throttle or re-enter CRASHED (FIX 4). The same-generation
+    // error+exit pair coalesces because the first call advances `exited`/`childGeneration` so the second
+    // is caught here (stale generation after a restart) or by the `exited` guard below (no restart).
+    if (crashGeneration !== ctx.state.childGeneration || ctx.state.exited) {
+        return;
+    }
+    // Marking the child exited BEFORE the disposed early-return lets `escalateKill`'s stop-predicate
+    // (`() => state.exited`) observe a prompt exit during dispose and resolve without waiting the full
+    // grace window (FIX 2).
+    ctx.state.exited = true;
+    if (ctx.state.disposed) {
+        return;
+    }
+    ctx.transition("CRASHED", "CRASHED");
+    if (ctx.throttle.recordCrashAndMayRestart(ctx.now())) {
+        ctx.state.restartCount = ctx.throttle.restartCount();
+        supervisorStart(ctx);
+    }
+    else {
+        ctx.transition("RESTART_THROTTLED", "RESTART_THROTTLED");
+    }
+}
+function supervisorStart(ctx) {
+    if (ctx.state.disposed) {
+        return;
+    }
+    const env = preflightOrFail(ctx.deps, ctx.transition);
+    if (env === undefined) {
+        return;
+    }
+    const executable = resolveOrFail(ctx.deps, ctx.transition);
+    if (executable === undefined) {
+        return;
+    }
+    spawnAndInitialize(ctx.state, ctx.deps, ctx.spawn, ctx.now, ctx.transition, executable, env, (generation) => {
+        supervisorOnCrash(ctx, generation);
+    });
+}
+function createManagerRuntime(deps) {
+    const now = deps.now ?? Date.now;
+    const state = {
+        status: "STARTING",
+        transport: undefined,
+        child: undefined,
+        exited: false,
+        restartCount: 0,
+        disposed: false,
+        childGeneration: 0,
+    };
+    const transition = (status, code) => {
+        state.status = status;
+        deps.onLifecycleEvent?.(buildLifecycleEvent(deps.config.managerId, state, now(), code));
+    };
+    const ctx = {
+        deps,
+        state,
+        now,
+        spawn: deps.spawn ?? defaultLspSpawnFn,
+        throttle: createLspRestartThrottle(deps.config.restartWindowMs, deps.config.maxRestartsInWindow),
+        transition,
+    };
+    transition("STARTING");
+    supervisorStart(ctx);
+    return { state, now, transition };
+}
+export function createLspProcessManager(deps) {
+    const { state, now, transition } = createManagerRuntime(deps);
+    return {
+        getLspProcessStatus: () => state.status,
+        asLanguageProvider: (languages, operations) => buildLanguageProvider(deps.config.managerId, languages, operations, () => state.status),
+        sendRequest: (method, params, signal) => sendRequest(state, deps, now, method, params, signal),
+        sendNotification: (method, params) => {
+            if (state.status === "READY")
+                state.transport?.client.notify(method, params);
+        },
+        onNotification: (handler) => {
+            state.transport?.client.onNotification(handler);
+        },
+        dispose: () => disposeManager(state, deps, now, transition),
+    };
+}
+function buildLifecycleEvent(managerId, state, timestampMs, errorCode) {
+    return {
+        schemaVersion: "1",
+        managerId,
+        status: state.status,
+        ...(errorCode !== undefined ? { errorCode } : {}),
+        timestampMs,
+        pendingRequestCount: state.transport?.client.pendingCount() ?? 0,
+        restartCount: state.restartCount,
+        stderrBytesSeen: state.transport?.stderrBytesSeen() ?? 0,
+    };
+}
+function spawnAndInitialize(state, deps, spawn, now, transition, executable, env, onCrash) {
+    // On a restart, reject any request still pending against the dead transport IMMEDIATELY instead of
+    // letting it linger until requestTimeoutMs: dispose rejects pending with LspRpcDisposedError, which
+    // maps to DISPOSED (FIX 3). The new generation guards stale callbacks from the superseded child.
+    state.transport?.dispose();
+    state.childGeneration += 1;
+    const generation = state.childGeneration;
+    state.exited = false;
+    const child = trySpawn(spawn, executable, env, deps, transition);
+    if (child === undefined) {
+        return;
+    }
+    state.child = child;
+    state.transport = createLspTransport(child, deps.config.maxFrameBytes, {
+        onReaderError: () => {
+            onCrash(generation);
+        },
+    });
+    child.onExit(() => {
+        onCrash(generation);
+    });
+    child.onError(() => {
+        onCrash(generation);
+    });
+    transition("INITIALIZING");
+    void runInitialize(state, deps, now, transition);
+}
+function preflightOrFail(deps, transition) {
+    try {
+        return preflightSpawnEnv(deps.commandRules, deps.config.executableName, deps.config.executableArgs ?? [], deps.processEnv, deps.config.envAllowlist);
+    }
+    catch {
+        transition("EXECUTABLE_NOT_FOUND", "EXECUTABLE_NOT_FOUND");
+        return undefined;
+    }
+}
+function resolveOrFail(deps, transition) {
+    try {
+        return resolveExecutableOutsideWorkspace(deps.config.executableName, deps.workspace, deps.processEnv);
+    }
+    catch {
+        transition("EXECUTABLE_NOT_FOUND", "EXECUTABLE_NOT_FOUND");
+        return undefined;
+    }
+}
+function trySpawn(spawn, executable, env, deps, transition) {
+    try {
+        return spawn(executable, deps.config.executableArgs ?? [], env, deps.workspace.root);
+    }
+    catch {
+        transition("SPAWN_FAILED", "SPAWN_FAILED");
+        return undefined;
+    }
+}
+async function runInitialize(state, deps, now, transition) {
+    const client = state.transport?.client;
+    if (client === undefined) {
+        return;
+    }
+    const networkPolicy = deps.config.networkPolicy ?? "inherit";
+    try {
+        await client.request("initialize", { capabilities: {}, networkPolicy }, { deadlineMs: deps.config.initializeTimeoutMs, now });
+        if (state.status === "INITIALIZING") {
+            transition("READY");
+        }
+    }
+    catch (error) {
+        if (state.status === "INITIALIZING") {
+            transition("INITIALIZE_TIMEOUT", classifyInitFailure(error));
+        }
+    }
+}
+function classifyInitFailure(error) {
+    return error instanceof LspRpcTimeoutError ? "INITIALIZE_TIMEOUT" : "INITIALIZE_FAILED";
+}
+async function sendRequest(state, deps, now, method, params, signal) {
+    if (state.disposed || state.status === "DISPOSED") {
+        throw new LspProcessError("DISPOSED");
+    }
+    const client = state.transport?.client;
+    if (client === undefined || state.status !== "READY") {
+        throw new LspProcessError("CRASHED");
+    }
+    try {
+        return await client.request(method, params, {
+            signal,
+            deadlineMs: deps.config.requestTimeoutMs,
+            now,
+        });
+    }
+    catch (error) {
+        throw mapRequestError(error);
+    }
+}
+function mapRequestError(error) {
+    if (error instanceof LspProcessError) {
+        return error;
+    }
+    if (error instanceof LspRpcTimeoutError) {
+        return new LspProcessError("REQUEST_TIMED_OUT");
+    }
+    if (error instanceof LspRpcCancelledError) {
+        return new LspProcessError("CANCELLED");
+    }
+    if (error instanceof LspRpcDisposedError) {
+        return new LspProcessError("DISPOSED");
+    }
+    // RESPONSE_TOO_LARGE is reserved for an ACTUAL frame-size rejection, never a generic RPC failure
+    // (FIX 9). A frame reject for an oversized body keeps that code; any other frame reject (malformed
+    // header) poisons the channel and surfaces as CRASHED. A plain server-side RPC error (the
+    // `new Error("LSP error")` raised in `settleResponse`) is a transport/protocol fault for that
+    // request, mapped to CRASHED — honest and content-free, never echoing the server's message text.
+    if (error instanceof LspFrameRejectError) {
+        return new LspProcessError(error.reason === "RESPONSE_TOO_LARGE" ? "RESPONSE_TOO_LARGE" : "CRASHED");
+    }
+    return new LspProcessError("CRASHED");
+}
+async function disposeManager(state, deps, now, transition) {
+    if (state.disposed) {
+        return;
+    }
+    state.disposed = true;
+    transition("SHUTDOWN");
+    const child = state.child;
+    const transport = state.transport;
+    await requestGracefulShutdown(transport, deps, now);
+    transport?.dispose();
+    if (child !== undefined) {
+        await escalateKill(child, deps.config.shutdownTimeoutMs, () => state.exited, undefined, (onExit) => {
+            child.onExit(onExit);
+        });
+    }
+    transition("DISPOSED", "DISPOSED");
+}
+async function requestGracefulShutdown(transport, deps, now) {
+    const client = transport?.client;
+    if (client === undefined) {
+        return;
+    }
+    try {
+        await client.request("shutdown", null, { deadlineMs: deps.config.shutdownTimeoutMs, now });
+    }
+    catch {
+        // A server that never answers shutdown is forced down by escalateKill (ADR-0069 D4).
+    }
+    client.notify("exit", null);
+}

package/dist/editor/lsp/lspRestartThrottle.d.ts

@@ -0,0 +1,6 @@
+export interface LspRestartThrottle {
+    recordCrashAndMayRestart(nowMs: number): boolean;
+    restartCount(): number;
+}
+export declare function createLspRestartThrottle(windowMs: number, maxInWindow: number): LspRestartThrottle;
+//# sourceMappingURL=lspRestartThrottle.d.ts.map

package/dist/editor/lsp/lspRestartThrottle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lspRestartThrottle.d.ts","sourceRoot":"","sources":["../../../src/editor/lsp/lspRestartThrottle.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,kBAAkB;IAEjC,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACjD,YAAY,IAAI,MAAM,CAAC;CACxB;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,kBAAkB,CAmBpB"}

package/dist/editor/lsp/lspRestartThrottle.js

@@ -0,0 +1,24 @@
+// Pure rolling-window restart throttle for the LSP process manager (Issue #1381, ADR-0069 D4). A
+// crash records a timestamp; the manager may restart while the number of crashes within the trailing
+// `windowMs` stays below `maxInWindow`. Once the window is saturated the manager transitions to
+// RESTART_THROTTLED and stays down. The state is a plain timestamp ring kept entirely in memory and
+// driven by an injected clock so every branch is deterministically testable.
+export function createLspRestartThrottle(windowMs, maxInWindow) {
+    const crashes = [];
+    let totalRestarts = 0;
+    return {
+        recordCrashAndMayRestart: (nowMs) => {
+            crashes.push(nowMs);
+            const cutoff = nowMs - windowMs;
+            const withinWindow = crashes.filter((timestamp) => timestamp > cutoff);
+            crashes.length = 0;
+            crashes.push(...withinWindow);
+            if (withinWindow.length > maxInWindow) {
+                return false;
+            }
+            totalRestarts += 1;
+            return true;
+        },
+        restartCount: () => totalRestarts,
+    };
+}

package/dist/editor/lsp/lspStatusRoute.d.ts

@@ -0,0 +1,8 @@
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+import { type RouteResult } from "../../routes.js";
+export interface LspStatusRouteDeps {
+    readonly env: EnvSource;
+}
+export declare function isLspStatusTrusted(env: EnvSource): boolean;
+export declare function handleEditorLspStatus(_ctx: unknown, deps: LspStatusRouteDeps): RouteResult;
+//# sourceMappingURL=lspStatusRoute.d.ts.map

package/dist/editor/lsp/lspStatusRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lspStatusRoute.d.ts","sourceRoot":"","sources":["../../../src/editor/lsp/lspStatusRoute.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;CACzB;AAID,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAG1D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,kBAAkB,GAAG,WAAW,CAK1F"}

package/dist/editor/lsp/lspStatusRoute.js

@@ -0,0 +1,22 @@
+// Issue #1381, ADR-0069 D5/D6 — read-only status route for the governed LSP process manager. It serves
+// the bounded, content-free lifecycle ledger so an operator can inspect recent LSP process activity
+// (spawn, initialize, crash, restart, dispose) without any source text, paths, or method names ever
+// crossing the boundary. The route is env-gated default-OFF (`KEIKO_EDITOR_LSP_STATUS`): until an
+// operator explicitly enables it, the endpoint reports 404 NOT_FOUND so it is not even discoverable.
+//
+// GET only, no CSRF (a read route mutates nothing). No CSP/connect-src change is needed: the response
+// is same-origin BFF JSON consumed over the existing fetch path, identical to /api/editor/agent/audit.
+import { errorBody } from "../../routes.js";
+import { listLspLifecycleEvents } from "./lspLifecycleLedger.js";
+// Default-OFF: the status surface is only exposed when the operator opts in. Any value other than the
+// explicit truthy tokens leaves it disabled (fail-closed), so a typo cannot accidentally expose it.
+export function isLspStatusTrusted(env) {
+    const raw = env.KEIKO_EDITOR_LSP_STATUS;
+    return raw === "1" || raw === "true";
+}
+export function handleEditorLspStatus(_ctx, deps) {
+    if (!isLspStatusTrusted(deps.env)) {
+        return { status: 404, body: errorBody("NOT_FOUND", "The requested resource was not found.") };
+    }
+    return { status: 200, body: { events: listLspLifecycleEvents() } };
+}

package/dist/editor/lsp/lspTransport.d.ts

@@ -0,0 +1,19 @@
+import type { LspByteSink, LspByteSource } from "./lspFrameCodec.js";
+import type { LspJsonRpcClient, LspRpcScheduler } from "./lspJsonRpcClient.js";
+export interface LspSpawnHandle {
+    readonly stdin: LspByteSink;
+    readonly stdout: LspByteSource;
+    readonly stderr: LspByteSource;
+    readonly pid: number | undefined;
+}
+export interface LspTransport {
+    readonly client: LspJsonRpcClient;
+    stderrBytesSeen(): number;
+    dispose(): void;
+}
+export interface LspTransportDeps {
+    readonly scheduler?: LspRpcScheduler | undefined;
+    readonly onReaderError?: ((error: unknown) => void) | undefined;
+}
+export declare function createLspTransport(handle: LspSpawnHandle, maxFrameBytes: number, deps?: LspTransportDeps): LspTransport;
+//# sourceMappingURL=lspTransport.d.ts.map

package/dist/editor/lsp/lspTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lspTransport.d.ts","sourceRoot":"","sources":["../../../src/editor/lsp/lspTransport.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAY,MAAM,oBAAoB,CAAC;AAE/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAK/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,eAAe,IAAI,MAAM,CAAC;IAC1B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAGjD,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACjE;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,EACtB,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,gBAAqB,GAC1B,YAAY,CA0Bd"}

package/dist/editor/lsp/lspTransport.js

@@ -0,0 +1,55 @@
+// Transport wiring (Issue #1381, Epic #1491, ADR-0069 D3). Binds a spawned LSP child's stdio to the
+// pure frame codec and the JSON-RPC client: stdout frames feed the client's request/response
+// correlation, the client's outbound frames are written to stdin, and stderr is drained for a byte
+// COUNT only — never stored, logged, or surfaced (ADR-0069 I3/I4/D6 content-free invariant). Only the
+// drained-byte count is exposed via `stderrBytesSeen()` for the lifecycle event's `stderrBytesSeen`.
+import { createLspFrameReader, writeLspFrame } from "./lspFrameCodec.js";
+import { createLspJsonRpcClient } from "./lspJsonRpcClient.js";
+export function createLspTransport(handle, maxFrameBytes, deps = {}) {
+    let stderrBytes = 0;
+    let disposed = false;
+    const reader = createLspFrameReader(handle.stdout, maxFrameBytes);
+    const guardedSource = guardReader(reader, deps.onReaderError);
+    const client = createLspJsonRpcClient({
+        source: guardedSource,
+        sendFrame: (body) => { writeLspFrame(handle.stdin, body); },
+        ...(deps.scheduler !== undefined ? { scheduler: deps.scheduler } : {}),
+    });
+    void drainStderr(handle.stderr, (count) => {
+        stderrBytes += count;
+    });
+    return {
+        client,
+        stderrBytesSeen: () => stderrBytes,
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            client.dispose();
+        },
+    };
+}
+// Wraps the frame reader so a frame-level reject (oversized/malformed) is surfaced to the manager via
+// `onReaderError` and then ends the stream cleanly, rather than propagating as an unhandled rejection
+// in the client's detached consume loop. The reader stops after the first reject (the connection is
+// considered poisoned, ADR-0069 I3).
+async function* guardReader(reader, onReaderError) {
+    try {
+        yield* reader;
+    }
+    catch (error) {
+        onReaderError?.(error);
+    }
+}
+// Counts stderr bytes without storing them. The bytes are read and immediately discarded; only the
+// running total survives (ADR-0069 D6: raw stderr never crosses an audit or status boundary).
+async function drainStderr(stderr, onCount) {
+    try {
+        for await (const chunk of stderr) {
+            onCount(chunk.length);
+        }
+    }
+    catch {
+        // A stderr read error is non-fatal to the protocol channel; the count simply stops advancing.
+    }
+}