@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/editor/lsp/lspFrameCodec.js

@@ -0,0 +1,164 @@
+// Byte-level LSP base-protocol codec (Issue #1381, Epic #1491, ADR-0069 D3/I3). The reader consumes
+// raw stdout chunks, splits `Content-Length: N\r\n\r\n` + exactly N bytes, and yields frame body
+// buffers. It works purely at the Buffer level: headers are ASCII, but bodies are decoded as JSON
+// only by the caller after exactly N bytes are accumulated, so a multi-byte UTF-8 sequence that
+// straddles a chunk boundary is never split mid-character.
+//
+// ADR-0069 I3 (stream boundaries never buffer an oversized body): when the declared Content-Length
+// exceeds `maxFrameBytes` the reader rejects the frame BEFORE reading the body and never accumulates
+// the oversized payload. A missing or garbled header is rejected as MALFORMED_HEADER. The pre-header
+// region is itself capped at `MAX_HEADER_BYTES` so a server that floods bytes WITHOUT ever sending a
+// `\r\n\r\n` terminator cannot grow the accumulation buffer unbounded (OOM); such a stream is rejected
+// as MALFORMED_HEADER. Incoming chunks accumulate in a list and are concatenated at most once per
+// yielded frame, so a large body arriving in many small chunks costs O(n) total copy, not O(n^2).
+import { parseLspFrameHeader } from "@oscharko-dev/keiko-contracts";
+const HEADER_DELIMITER = Buffer.from("\r\n\r\n", "ascii");
+const HEADER_LINE_DELIMITER = "\r\n";
+// Per LSP-norm header bound: a well-formed `Content-Length` (+ optional `Content-Type`) header block
+// is far under 8 KiB. Capping the pre-terminator region at this constant (independent of the body cap
+// `maxFrameBytes`, which governs the declared body) means a delimiter-less flood is rejected promptly
+// instead of accumulating without limit. 8192 is the conventional LSP base-protocol header ceiling.
+const MAX_HEADER_BYTES = 8192;
+// Thrown by the frame reader when a frame cannot be read safely. The `reason` is a content-free enum
+// member; no header text or body bytes are carried on the error (ADR-0069 D6).
+export class LspFrameRejectError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.name = "LspFrameRejectError";
+        this.reason = reason;
+    }
+}
+// Locates the `\r\n\r\n` header terminator in the accumulated buffer and parses the Content-Length.
+// Returns null when the terminator is not yet present (more chunks needed). Throws LspFrameRejectError
+// when a header is present but malformed, so the caller surfaces MALFORMED_HEADER deterministically.
+function parseHeader(buffer) {
+    const delimiterIndex = buffer.indexOf(HEADER_DELIMITER);
+    if (delimiterIndex === -1) {
+        return null;
+    }
+    const headerBlock = buffer.subarray(0, delimiterIndex).toString("ascii");
+    const contentLength = readContentLength(headerBlock);
+    if (contentLength === null) {
+        throw new LspFrameRejectError("MALFORMED_HEADER");
+    }
+    return { contentLength, headerEndIndex: delimiterIndex + HEADER_DELIMITER.length };
+}
+// Scans the header block lines for a parseable Content-Length. Other header lines (LSP allows an
+// optional Content-Type) are ignored; absence of a valid Content-Length is malformed.
+function readContentLength(headerBlock) {
+    const lines = headerBlock.split(HEADER_LINE_DELIMITER);
+    for (const line of lines) {
+        const parsed = parseLspFrameHeader(line);
+        if (parsed !== null) {
+            return parsed.contentLength;
+        }
+    }
+    return null;
+}
+// Reads framed bodies from a byte source, yielding one Buffer per frame. Async-generator semantics
+// give natural backpressure: a frame is yielded only once its full body is buffered, and the next
+// source pull happens when the consumer requests the next frame.
+//
+// Accumulation is a list of chunks plus a running byte total; the list is concatenated into a single
+// contiguous buffer only when a header terminator is present (so a complete header+body frame can be
+// sliced). A large body delivered in many small chunks therefore incurs one O(n) concat at yield time
+// rather than an O(n^2) concat-on-every-chunk. Before any terminator arrives, the accumulated size is
+// bounded by `MAX_HEADER_BYTES`; exceeding it without a terminator is a MALFORMED_HEADER reject.
+export async function* createLspFrameReader(source, maxFrameBytes) {
+    const pending = createPendingBuffer();
+    for await (const chunk of source) {
+        pending.push(chunk);
+        yield* drainFrames(pending, maxFrameBytes);
+    }
+}
+const EMPTY = Buffer.alloc(0);
+const DELIMITER_OVERLAP = HEADER_DELIMITER.length - 1;
+function createPendingBuffer() {
+    let chunks = [];
+    let totalBytes = 0;
+    let delimiterFound = false;
+    // The last `DELIMITER_OVERLAP` bytes of already-scanned data, retained so a terminator straddling a
+    // chunk boundary is detected by scanning only `tail + newChunk` — never a full re-concat (O(n)).
+    let tail = EMPTY;
+    const scanIncoming = (chunk) => {
+        const window = tail.length === 0 ? chunk : Buffer.concat([tail, chunk]);
+        if (window.indexOf(HEADER_DELIMITER) !== -1) {
+            delimiterFound = true;
+            return;
+        }
+        tail = window.subarray(Math.max(0, window.length - DELIMITER_OVERLAP));
+    };
+    return {
+        push: (chunk) => {
+            if (chunk.length === 0)
+                return;
+            chunks.push(chunk);
+            totalBytes += chunk.length;
+            if (!delimiterFound) {
+                scanIncoming(chunk);
+            }
+        },
+        byteLength: () => totalBytes,
+        hasHeaderDelimiter: () => delimiterFound,
+        coalesce: () => (chunks.length === 1 ? (chunks[0] ?? EMPTY) : Buffer.concat(chunks)),
+        reset: (rest) => {
+            chunks = rest.length === 0 ? [] : [rest];
+            totalBytes = rest.length;
+            tail = EMPTY;
+            delimiterFound = rest.indexOf(HEADER_DELIMITER) !== -1;
+        },
+    };
+}
+// Rejects a delimiter-less accumulation that has grown past the header cap (ADR-0069 I3): a server
+// that floods bytes without ever sending `\r\n\r\n` would otherwise grow the buffer unbounded.
+function guardHeaderBound(pending) {
+    if (!pending.hasHeaderDelimiter() && pending.byteLength() > MAX_HEADER_BYTES) {
+        throw new LspFrameRejectError("MALFORMED_HEADER");
+    }
+}
+// Attempts to slice one complete frame from the head of the buffer. Returns null when the full
+// declared body is not yet present. Enforces the oversized cap at the header boundary, before any
+// body byte is required (ADR-0069 I3). The caller only invokes this once a terminator is present, so
+// `parseHeader` never returns null here.
+function takeFrame(buffer, maxFrameBytes) {
+    const header = parseHeader(buffer);
+    if (header === null) {
+        return null;
+    }
+    if (header.contentLength > maxFrameBytes) {
+        throw new LspFrameRejectError("RESPONSE_TOO_LARGE");
+    }
+    const bodyEnd = header.headerEndIndex + header.contentLength;
+    if (buffer.length < bodyEnd) {
+        return null;
+    }
+    return {
+        body: buffer.subarray(header.headerEndIndex, bodyEnd),
+        rest: buffer.subarray(bodyEnd),
+    };
+}
+// Slices every complete frame currently buffered, yielding each body. Enforces the header cap on the
+// no-terminator path before coalescing, so a delimiter-less flood is rejected without an unbounded
+// concat. Stops when neither a full header nor a full body is yet available (awaiting more chunks).
+function* drainFrames(pending, maxFrameBytes) {
+    for (;;) {
+        if (!pending.hasHeaderDelimiter()) {
+            guardHeaderBound(pending);
+            return;
+        }
+        const frame = takeFrame(pending.coalesce(), maxFrameBytes);
+        if (frame === null) {
+            return;
+        }
+        pending.reset(frame.rest);
+        yield frame.body;
+    }
+}
+// Serializes a JSON-RPC body string as one LSP base-protocol frame: an ASCII Content-Length header
+// (byte length of the UTF-8 body, not the string length) followed by `\r\n\r\n` and the body bytes.
+export function writeLspFrame(sink, body) {
+    const bodyBytes = Buffer.from(body, "utf8");
+    const header = Buffer.from(`Content-Length: ${String(bodyBytes.length)}\r\n\r\n`, "ascii");
+    sink.write(Buffer.concat([header, bodyBytes]));
+}

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

@@ -0,0 +1,34 @@
+import type { LspByteSource } from "./lspFrameCodec.js";
+export declare class LspRpcTimeoutError extends Error {
+    constructor();
+}
+export declare class LspRpcCancelledError extends Error {
+    constructor();
+}
+export declare class LspRpcDisposedError extends Error {
+    constructor();
+}
+export type LspNotificationHandler = (method: string, params: unknown) => void;
+export interface LspRequestOptions {
+    readonly signal?: AbortSignal | undefined;
+    readonly deadlineMs: number;
+    readonly now?: (() => number) | undefined;
+}
+export interface LspJsonRpcClient {
+    request<T>(method: string, params: unknown, options: LspRequestOptions): Promise<T>;
+    notify(method: string, params: unknown): void;
+    onNotification(handler: LspNotificationHandler): void;
+    pendingCount(): number;
+    dispose(): void;
+}
+export interface LspRpcScheduler {
+    setTimer(callback: () => void, delayMs: number): unknown;
+    clearTimer(handle: unknown): void;
+}
+export interface LspJsonRpcClientDeps {
+    readonly source: LspByteSource;
+    readonly sendFrame: (body: string) => void;
+    readonly scheduler?: LspRpcScheduler | undefined;
+}
+export declare function createLspJsonRpcClient(deps: LspJsonRpcClientDeps): LspJsonRpcClient;
+//# sourceMappingURL=lspJsonRpcClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lspJsonRpcClient.d.ts","sourceRoot":"","sources":["../../../src/editor/lsp/lspJsonRpcClient.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,oBAAoB,CAAC;AAElE,qBAAa,kBAAmB,SAAQ,KAAK;;CAK5C;AAED,qBAAa,oBAAqB,SAAQ,KAAK;;CAK9C;AAED,qBAAa,mBAAoB,SAAQ,KAAK;;CAK7C;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9C,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAID,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACzD,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CAClD;AAaD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CA4CnF"}

package/dist/editor/lsp/lspJsonRpcClient.js

@@ -0,0 +1,173 @@
+// Minimal JSON-RPC 2.0 client over the LSP base protocol (Issue #1381, Epic #1491, ADR-0069 D3/D4).
+// It correlates outbound requests to inbound responses by numeric id, dispatches server-initiated
+// notifications to a registered handler, and enforces a per-request deadline plus AbortSignal
+// cancellation by mirroring the `createDeadlineCancellation` clock+signal model natively. We do NOT
+// import `languageCancellation` here: it pulls in the TypeScript compiler for its HostCancellationToken,
+// which this transport layer must not depend on.
+//
+// On deadline expiry the client sends `$/cancelRequest` and rejects with LspRpcTimeoutError (the
+// process is not killed — a slow request is not a crash, ADR-0069 D4). On abort it sends
+// `$/cancelRequest` and rejects with LspRpcCancelledError. On dispose every pending request rejects
+// with LspRpcDisposedError. All three carry only a class name, never request/response content.
+export class LspRpcTimeoutError extends Error {
+    constructor() {
+        super("LSP request timed out");
+        this.name = "LspRpcTimeoutError";
+    }
+}
+export class LspRpcCancelledError extends Error {
+    constructor() {
+        super("LSP request cancelled");
+        this.name = "LspRpcCancelledError";
+    }
+}
+export class LspRpcDisposedError extends Error {
+    constructor() {
+        super("LSP client disposed");
+        this.name = "LspRpcDisposedError";
+    }
+}
+const defaultScheduler = {
+    setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimer: (handle) => { clearTimeout(handle); },
+};
+export function createLspJsonRpcClient(deps) {
+    const scheduler = deps.scheduler ?? defaultScheduler;
+    const pending = new Map();
+    let notificationHandler;
+    let nextId = 1;
+    let disposed = false;
+    const send = (payload) => {
+        deps.sendFrame(JSON.stringify(payload));
+    };
+    void consume(deps.source, (body) => { dispatch(body, pending, (m, p) => notificationHandler?.(m, p)); });
+    const request = (method, params, options) => {
+        if (disposed) {
+            return Promise.reject(new LspRpcDisposedError());
+        }
+        const id = nextId++;
+        return new Promise((resolve, reject) => {
+            registerPending(id, pending, scheduler, send, options, {
+                resolve: resolve,
+                reject,
+            });
+            send({ jsonrpc: "2.0", id, method, params });
+        });
+    };
+    return {
+        request,
+        notify: (method, params) => {
+            if (!disposed)
+                send({ jsonrpc: "2.0", method, params });
+        },
+        onNotification: (handler) => {
+            notificationHandler = handler;
+        },
+        pendingCount: () => pending.size,
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            rejectAll(pending, new LspRpcDisposedError());
+        },
+    };
+}
+// Wires the deadline timer and abort listener for one in-flight request and records it in the pending
+// map. The shared `settle()` tears down both the timer and the abort listener exactly once, on any
+// terminal outcome (response, timeout, abort, dispose), so no handle leaks.
+function registerPending(id, pending, scheduler, send, options, handlers) {
+    const cancel = () => { send({ jsonrpc: "2.0", method: "$/cancelRequest", params: { id } }); };
+    const timer = scheduler.setTimer(() => {
+        if (!pending.has(id))
+            return;
+        pending.delete(id);
+        settle();
+        cancel();
+        handlers.reject(new LspRpcTimeoutError());
+    }, options.deadlineMs);
+    const onAbort = () => {
+        if (!pending.has(id))
+            return;
+        pending.delete(id);
+        settle();
+        cancel();
+        handlers.reject(new LspRpcCancelledError());
+    };
+    const settle = () => {
+        scheduler.clearTimer(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+    };
+    if (options.signal?.aborted === true) {
+        pending.delete(id);
+        settle();
+        cancel();
+        handlers.reject(new LspRpcCancelledError());
+        return;
+    }
+    options.signal?.addEventListener("abort", onAbort);
+    pending.set(id, { resolve: handlers.resolve, reject: handlers.reject, settle });
+}
+// Parses one frame body and routes it: a response (has numeric `id`) resolves or rejects its pending
+// entry; anything else is treated as a server-initiated notification. Malformed JSON or an unknown id
+// is ignored — a misbehaving server cannot crash the client (fail-safe, ADR-0069 D4).
+function dispatch(body, pending, notify) {
+    const message = parseMessage(body);
+    if (message === null)
+        return;
+    const id = message.id;
+    if (typeof id === "number") {
+        settleResponse(id, message, pending);
+        return;
+    }
+    if (typeof message.method === "string") {
+        notify(message.method, message.params);
+    }
+}
+function settleResponse(id, message, pending) {
+    const entry = pending.get(id);
+    if (entry === undefined)
+        return;
+    pending.delete(id);
+    entry.settle();
+    const error = message.error;
+    if (isRpcError(error)) {
+        entry.reject(new Error(typeof error.message === "string" ? error.message : "LSP error"));
+        return;
+    }
+    entry.resolve(message.result);
+}
+function isRpcError(value) {
+    return typeof value === "object" && value !== null;
+}
+function parseMessage(body) {
+    try {
+        const parsed = JSON.parse(body.toString("utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function rejectAll(pending, error) {
+    for (const entry of pending.values()) {
+        entry.settle();
+        entry.reject(error);
+    }
+    pending.clear();
+}
+// Drains the frame source until it ends. Reader-loop errors (e.g. a frame-reject thrown by the codec)
+// terminate the loop; the transport owns surfacing that as a process-level failure, so it is swallowed
+// here to avoid an unhandled rejection on the detached consume promise.
+async function consume(source, onBody) {
+    try {
+        for await (const body of source) {
+            onBody(body);
+        }
+    }
+    catch {
+        // Intentionally ignored: frame-level failures are surfaced by the transport via the reader, not
+        // by this detached drain loop. See lspTransport.ts.
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { LanguageProviderDescriptor, LanguageServiceOperation, LspProcessStatus } from "@oscharko-dev/keiko-contracts";
+import type { LanguageProvider } from "../languageProvider.js";
+export interface LspManagerLanguageProvider extends LanguageProvider {
+    readonly descriptor: LanguageProviderDescriptor;
+}
+export declare function buildLanguageProvider(managerId: string, languages: readonly string[], operations: readonly LanguageServiceOperation[], getStatus: () => LspProcessStatus): LspManagerLanguageProvider;
+//# sourceMappingURL=lspLanguageProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lspLanguageProvider.d.ts","sourceRoot":"","sources":["../../../src/editor/lsp/lspLanguageProvider.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,0BAA0B,EAC1B,wBAAwB,EACxB,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAGV,gBAAgB,EAEjB,MAAM,wBAAwB,CAAC;AAGhC,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAClE,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;CACjD;AAYD,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,UAAU,EAAE,SAAS,wBAAwB,EAAE,EAC/C,SAAS,EAAE,MAAM,gBAAgB,GAChC,0BAA0B,CAa5B"}

package/dist/editor/lsp/lspLanguageProvider.js

@@ -0,0 +1,29 @@
+// Adapts a managed LSP process into a `LanguageProvider` whose descriptor reflects the manager's live
+// status (Issue #1381, ADR-0069 D5). This foundation ships no real provider: the language-intelligence
+// operations return empty, non-truncated results and the descriptor is the sole governed surface —
+// `describeLanguageCapabilities()` consumes `descriptor.availability` unchanged. A future per-language
+// issue replaces these stubs with real LSP request mappings.
+import { lspStatusToProviderDescriptor } from "@oscharko-dev/keiko-contracts";
+const EMPTY_DIAGNOSTICS = { diagnostics: [], truncated: false };
+const EMPTY_SYMBOLS = { symbols: [], truncated: false };
+const EMPTY_FORMATTING = { edits: [], truncated: false };
+const EMPTY_COMPLETION = {
+    items: [],
+    isIncomplete: false,
+    truncated: false,
+};
+const EMPTY_HOVER = { contents: null };
+export function buildLanguageProvider(managerId, languages, operations, getStatus) {
+    const supported = new Set(languages);
+    return {
+        get descriptor() {
+            return lspStatusToProviderDescriptor(managerId, languages, operations, getStatus());
+        },
+        supports: (languageId) => supported.has(languageId),
+        getDiagnostics: () => EMPTY_DIAGNOSTICS,
+        getCompletions: () => EMPTY_COMPLETION,
+        getHover: () => EMPTY_HOVER,
+        getSymbols: () => EMPTY_SYMBOLS,
+        getFormatting: () => EMPTY_FORMATTING,
+    };
+}

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

@@ -0,0 +1,5 @@
+import type { LspLifecycleEvent } from "@oscharko-dev/keiko-contracts";
+export declare function recordLspLifecycleEvent(event: LspLifecycleEvent): LspLifecycleEvent | null;
+export declare function listLspLifecycleEvents(): readonly LspLifecycleEvent[];
+export declare function _resetLspLifecycleLedgerForTests(): void;
+//# sourceMappingURL=lspLifecycleLedger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lspLifecycleLedger.d.ts","sourceRoot":"","sources":["../../../src/editor/lsp/lspLifecycleLedger.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAmBvE,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,IAAI,CAW1F;AAGD,wBAAgB,sBAAsB,IAAI,SAAS,iBAAiB,EAAE,CAErE;AAED,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD"}

package/dist/editor/lsp/lspLifecycleLedger.js

@@ -0,0 +1,37 @@
+// Issue #1381, ADR-0069 D6/I4 — bounded, content-free in-memory ledger of LSP process lifecycle
+// events. Mirrors agentActionAudit.ts: a module-level append-only FIFO surfaces "recent LSP process
+// activity" to the read-only status route. The record is content-free by construction (the contract
+// `LspLifecycleEvent` carries only an opaque managerId, an enum status/error code, counts, and a
+// timestamp — no source text, paths, method names, or raw stderr) and is run through the
+// keiko-security redactor as defense in depth before it is stored or served, so a secret-shaped
+// substring that ever slipped into an id cannot reach the ledger.
+import { deepRedactStrings, redact } from "@oscharko-dev/keiko-security";
+// Bounded like the agent-audit ledger: a long-lived server must not grow this without limit.
+const MAX_EVENTS = 200;
+const state = { events: [] };
+function redactEvent(event) {
+    return deepRedactStrings(event, redact);
+}
+// Record one content-free lifecycle event. Best-effort and throw-free: a ledger failure must never
+// break the manager's lifecycle path. Returns the stored (redacted) event, or null when recording
+// failed. The manager's `onLifecycleEvent` callback feeds this on every state transition.
+export function recordLspLifecycleEvent(event) {
+    try {
+        const redacted = redactEvent(event);
+        state.events.push(redacted);
+        if (state.events.length > MAX_EVENTS) {
+            state.events.splice(0, state.events.length - MAX_EVENTS);
+        }
+        return redacted;
+    }
+    catch {
+        return null;
+    }
+}
+// Recent lifecycle events, newest last, bounded to the FIFO cap. Already redacted at record time.
+export function listLspLifecycleEvents() {
+    return state.events;
+}
+export function _resetLspLifecycleLedgerForTests() {
+    state.events.length = 0;
+}

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

@@ -0,0 +1,31 @@
+import type { CommandRule } from "@oscharko-dev/keiko-tools";
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import type { LspProcessErrorCode } from "@oscharko-dev/keiko-contracts";
+import type { LspSpawnHandle } from "./lspTransport.js";
+export declare class LspProcessError extends Error {
+    readonly code: LspProcessErrorCode;
+    constructor(code: LspProcessErrorCode);
+}
+export type LspSpawnFn = (executable: string, args: readonly string[], env: Record<string, string>, cwd: string) => LspSpawnHandle & {
+    kill(signal: NodeJS.Signals): void;
+    onExit(callback: (code: number | null) => void): void;
+    onError(callback: (error: Error) => void): void;
+};
+export interface EphemeralHome {
+    readonly path: string;
+    cleanup(): void;
+}
+export interface KillableChild {
+    readonly pid?: number | undefined;
+    kill(signal: NodeJS.Signals): void;
+}
+export declare function resolveExecutableOutsideWorkspace(name: string, workspace: WorkspaceInfo, processEnv: NodeJS.ProcessEnv): string;
+export declare function createEphemeralHome(): EphemeralHome;
+export type ChildExitRegistration = (onExit: () => void) => void;
+export declare function escalateKill(child: KillableChild, gracePeriodMs: number, exited: () => boolean, scheduler?: KillScheduler, whenExited?: ChildExitRegistration): Promise<void>;
+export interface KillScheduler {
+    setTimer(callback: () => void, delayMs: number): unknown;
+}
+export declare const defaultLspSpawnFn: LspSpawnFn;
+export declare function preflightSpawnEnv(rules: readonly CommandRule[], executable: string, args: readonly string[], processEnv: NodeJS.ProcessEnv, envAllowlist: readonly string[]): Record<string, string>;
+//# sourceMappingURL=lspNodeAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lspNodeAdapter.d.ts","sourceRoot":"","sources":["../../../src/editor/lsp/lspNodeAdapter.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,IAAI,EAAE,mBAAmB,CAAC;gBAEvB,IAAI,EAAE,mBAAmB;CAK7C;AAID,MAAM,MAAM,UAAU,GAAG,CACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,GAAG,EAAE,MAAM,KACR,cAAc,GAAG;IACpB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACnC,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IACtD,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;CACjD,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,IAAI,IAAI,CAAC;CACjB;AAID,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CACpC;AA2DD,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,aAAa,EACxB,UAAU,EAAE,MAAM,CAAC,UAAU,GAC5B,MAAM,CAmBR;AAID,wBAAgB,mBAAmB,IAAI,aAAa,CAYnD;AAgCD,MAAM,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAQjE,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,EACpB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,OAAO,EACrB,SAAS,GAAE,aAAoC,EAC/C,UAAU,CAAC,EAAE,qBAAqB,GACjC,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1D;AA0CD,eAAO,MAAM,iBAAiB,EAAE,UAkB/B,CAAC;AAKF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,UAAU,EAAE,MAAM,CAAC,UAAU,EAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB"}