@ferrule-io/ok-fine 0.3.7 → 0.3.8

package/README.md

@@ -21,7 +21,7 @@ claude mcp add --scope user ok-fine -- npx -y @ferrule-io/ok-fine
 ```
 
 Other harnesses: [Coding agents](https://github.com/ferrule-io/ok-fine/wiki/Coding-Agents#local-setup-stdio). Git
-remotes, flags, and several concurrent sessions: [Running locally](https://github.com/ferrule-io/ok-fine/wiki/Running-Locally).
+remotes, flags, and concurrent sessions: [Running locally](https://github.com/ferrule-io/ok-fine/wiki/Running-Locally).
 
 ### HTTP server (REST + MCP)
 

package/dist/cli-options.js

@@ -3,7 +3,7 @@ import { parseArgs } from "node:util";
 export const USAGE = `Usage: ok-fine [stdio|serve] [options]
 
 Commands:
-  stdio (default)          Serve MCP over stdin/stdout for one local client
+  stdio (default)          Serve MCP over stdin/stdout
   serve                    Serve MCP and the REST API over HTTP
 
 Options:

package/dist/cli.js

@@ -5,7 +5,8 @@ import { pino } from "pino";
 import { parseCli, USAGE } from "./cli-options.js";
 import { loadConfig, loadStorageConfig } from "./config.js";
 import { lockDataDir } from "./data-dir-lock.js";
-import { startServer, startStdioServer } from "./server.js";
+import { startLocalHost, startServer } from "./server.js";
+import { startStdioProxy } from "./stdio-proxy.js";
 import { VERSION } from "./version.js";
 const message = (err) => (err instanceof Error ? err.message : String(err));
 /** `git config user.email` in the launch directory; null when unset or git is unavailable. Not `Git`: it forces ok-fine's own email. */
@@ -57,26 +58,23 @@ if (inv.command === "stdio") {
     }
     // stdout carries JSON-RPC only; every log line goes to stderr.
     const log = pino({ level: config.logLevel }, pino.destination({ dest: 2, sync: true }));
-    try {
-        const release = await lockDataDir(config.dataDir);
-        process.once("exit", release);
-    }
-    catch (err) {
-        log.error(message(err));
-        process.exit(1);
-    }
     const identity = await localGitEmail(inv.env);
     log.info({ dataDir: config.dataDir, identity }, "serving MCP over stdio");
-    let server;
+    let proxy;
     try {
-        server = await startStdioServer(config, { log, identity });
+        proxy = await startStdioProxy({
+            config,
+            identity,
+            log,
+            startHost: () => startLocalHost(config, { log }),
+        });
     }
     catch (err) {
         log.error({ err }, "ok-fine failed to start");
         process.exit(1);
     }
-    const shutdown = shutdownOnce(() => server.close(), (err) => log.error({ err }, "shutdown failed"));
-    void server.done.then(shutdown);
+    const shutdown = shutdownOnce(() => proxy.close(), (err) => log.error({ err }, "shutdown failed"));
+    void proxy.done.then(shutdown);
     process.once("SIGINT", shutdown);
     process.once("SIGTERM", shutdown);
 }
@@ -99,7 +97,7 @@ else {
     }
     let server;
     try {
-        server = await startServer(config);
+        server = await startServer(config, { hostEndpoint: config.auth.mode === "none" });
     }
     catch (err) {
         console.error("ok-fine failed to start:", err);

package/dist/data-dir-lock.js

@@ -1,43 +1,52 @@
 import { readFileSync, unlinkSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-function errorCode(err) {
-    return err?.code;
-}
-function isRunning(pid) {
+import { join, resolve } from "node:path";
+/** Checks if a process with the given PID is alive. */
+export function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
         return true;
     }
     catch (err) {
-        return errorCode(err) === "EPERM";
+        return err?.code === "EPERM";
     }
 }
+/** In-process tracking so concurrent sessions in the same process do not clobber each other's locks. */
+const inProcessLocks = new Set();
 /**
- * Takes the exclusive per-data-dir lock for a local CLI process; a lock left by a dead process is taken over.
- * Returns a synchronous release, safe to call from `process.on("exit")`.
+ * Attempts to acquire the exclusive per-data-dir lock without throwing.
+ * Returns a release function (callable directly or via .release()) on success,
+ * or { acquired: false, holderPid } when held by another process or concurrent session.
  */
-export async function lockDataDir(dataDir) {
+export async function tryLockDataDir(dataDir) {
+    const canonicalDir = resolve(dataDir);
+    if (inProcessLocks.has(canonicalDir)) {
+        return { acquired: false, holderPid: process.pid };
+    }
     await mkdir(dataDir, { recursive: true });
     const lockPath = join(dataDir, "ok-fine.lock");
     const pid = String(process.pid);
-    let holder = "unknown";
     for (let attempt = 0; attempt < 2; attempt++) {
         try {
             await writeFile(lockPath, `${pid}\n`, { flag: "wx" });
-            return () => {
+            inProcessLocks.add(canonicalDir);
+            const releaseFn = (() => {
+                inProcessLocks.delete(canonicalDir);
                 try {
                     if (readFileSync(lockPath, "utf8").trim() === pid)
                         unlinkSync(lockPath);
                 }
                 catch (err) {
-                    if (errorCode(err) !== "ENOENT")
+                    if (err?.code !== "ENOENT")
                         throw err;
                 }
-            };
+            });
+            releaseFn.acquired = true;
+            releaseFn.release = releaseFn;
+            return releaseFn;
         }
         catch (err) {
-            if (errorCode(err) !== "EEXIST")
+            if (err?.code !== "EEXIST")
                 throw err;
         }
         let content;
@@ -45,16 +54,46 @@ export async function lockDataDir(dataDir) {
             content = (await readFile(lockPath, "utf8")).trim();
         }
         catch (err) {
-            if (errorCode(err) === "ENOENT")
+            if (err?.code === "ENOENT")
                 continue;
             throw err;
         }
-        holder = content || "unknown";
         const holderPid = Number.parseInt(content, 10);
-        if (Number.isInteger(holderPid) && holderPid > 0 && holderPid !== process.pid && isRunning(holderPid))
-            break;
+        if (Number.isInteger(holderPid) && holderPid > 0) {
+            if (holderPid !== process.pid && isProcessAlive(holderPid)) {
+                return { acquired: false, holderPid };
+            }
+            if (holderPid === process.pid && inProcessLocks.has(canonicalDir)) {
+                return { acquired: false, holderPid: process.pid };
+            }
+        }
         await rm(lockPath, { force: true });
     }
-    throw new Error(`ok-fine is already running on ${dataDir} (pid ${holder}). One process serves a data directory: connect more clients to \`ok-fine serve\` over HTTP, or pass a different --data-dir. If no ok-fine process is running, delete ${lockPath}.`);
+    let content = null;
+    try {
+        content = (await readFile(lockPath, "utf8")).trim();
+    }
+    catch {
+        // ignore
+    }
+    const finalHolder = content ? Number.parseInt(content, 10) : null;
+    return {
+        acquired: false,
+        holderPid: finalHolder !== null && Number.isInteger(finalHolder) && finalHolder > 0 ? finalHolder : null,
+    };
+}
+/**
+ * Takes the exclusive per-data-dir lock for a local CLI process; a lock left by a dead process is taken over.
+ * Returns a synchronous release, safe to call from `process.on("exit")`.
+ * Throws if already held by a live process or concurrent session.
+ */
+export async function lockDataDir(dataDir) {
+    const result = await tryLockDataDir(dataDir);
+    if (result.acquired) {
+        return result;
+    }
+    const lockPath = join(dataDir, "ok-fine.lock");
+    const holder = result.holderPid ?? "unknown";
+    throw new Error(`ok-fine is already running on ${dataDir} (pid ${holder}). Close existing ok-fine sessions or pass a different --data-dir. If no ok-fine process is running, delete ${lockPath}.`);
 }
 //# sourceMappingURL=data-dir-lock.js.map

package/dist/local-host.js

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+import { chmod, rm } from "node:fs/promises";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { PassThrough } from "node:stream";
+import { StdioServerTransport, serveStdio } from "@modelcontextprotocol/server/stdio";
+import { z } from "zod";
+import { createMcpServer } from "./mcp/server.js";
+const HelloMessageSchema = z.object({
+    okFine: z.literal(1),
+    identity: z.string().nullable(),
+});
+/**
+ * Resolves the local IPC endpoint path for a given data directory:
+ * - Windows: named pipe `\\.\pipe\ok-fine-<first 16 hex of sha256(resolved dataDir)>`
+ * - Unix: `DATA_DIR/ok-fine.sock` (or `os.tmpdir()/ok-fine-<hash>.sock` if default exceeds 100 bytes)
+ */
+export function localEndpointPath(dataDir) {
+    const resolvedDir = resolve(dataDir);
+    const hash = createHash("sha256").update(resolvedDir).digest("hex").slice(0, 16);
+    if (process.platform === "win32") {
+        return `\\\\.\\pipe\\ok-fine-${hash}`;
+    }
+    const defaultPath = join(resolvedDir, "ok-fine.sock");
+    if (Buffer.byteLength(defaultPath) > 100) {
+        return join(tmpdir(), `ok-fine-${hash}.sock`);
+    }
+    return defaultPath;
+}
+/**
+ * Starts the local endpoint listener on Unix domain socket or Windows named pipe.
+ * Each incoming connection sends a newline-delimited JSON hello with its identity,
+ * and receives its own MCP server instance with full local permissions.
+ */
+export async function createLocalHost(options) {
+    const { service, config, log } = options;
+    const endpointPath = localEndpointPath(config.dataDir);
+    if (process.platform !== "win32") {
+        try {
+            await rm(endpointPath, { force: true });
+        }
+        catch {
+            // safe: we hold the data dir lock
+        }
+    }
+    const connections = new Set();
+    const server = net.createServer((socket) => {
+        socket.on("error", (err) => log.debug({ err }, "local host client socket error"));
+        const connRecord = { socket };
+        connections.add(connRecord);
+        const cleanup = () => {
+            connections.delete(connRecord);
+        };
+        socket.once("close", cleanup);
+        socket.once("end", cleanup);
+        let buffer = "";
+        const onData = (chunk) => {
+            buffer += chunk.toString("utf8");
+            const idx = buffer.indexOf("\n");
+            if (idx === -1) {
+                if (buffer.length > 65536) {
+                    socket.destroy();
+                }
+                return;
+            }
+            socket.off("data", onData);
+            const firstLine = buffer.slice(0, idx).trim();
+            const remainder = buffer.slice(idx + 1);
+            let helloRaw;
+            try {
+                helloRaw = JSON.parse(firstLine);
+            }
+            catch {
+                socket.destroy();
+                return;
+            }
+            const parsed = HelloMessageSchema.safeParse(helloRaw);
+            if (!parsed.success) {
+                socket.destroy();
+                return;
+            }
+            const identity = parsed.data.identity;
+            const principal = {
+                subject: "local",
+                clientId: "stdio",
+                identity,
+                scopes: [],
+                canRead: true,
+                canWrite: true,
+                canAdmin: true,
+            };
+            const inStream = new PassThrough();
+            inStream.on("error", (err) => log.debug({ err }, "client inStream error"));
+            if (remainder.length > 0) {
+                inStream.write(Buffer.from(remainder, "utf8"));
+            }
+            socket.pipe(inStream);
+            const handle = serveStdio(() => createMcpServer(service, principal, log), {
+                transport: new StdioServerTransport(inStream, socket),
+                onerror: (err) => log.error({ err }, "local host stdio transport error"),
+            });
+            connRecord.handle = handle;
+        };
+        socket.on("data", onData);
+    });
+    const { promise: listenPromise, resolve: resolveListen, reject: rejectListen } = Promise.withResolvers();
+    server.once("error", rejectListen);
+    server.listen(endpointPath, () => {
+        server.off("error", rejectListen);
+        resolveListen();
+    });
+    await listenPromise;
+    if (process.platform !== "win32") {
+        try {
+            await chmod(endpointPath, 0o600);
+        }
+        catch {
+            // safe ignore
+        }
+    }
+    let closing;
+    return {
+        endpointPath,
+        close: () => {
+            closing ??= (async () => {
+                const { promise: closePromise, resolve: resolveClose } = Promise.withResolvers();
+                try {
+                    server.close(() => resolveClose());
+                }
+                catch {
+                    resolveClose();
+                }
+                const closePromises = [];
+                for (const conn of connections) {
+                    if (conn.handle) {
+                        closePromises.push(conn.handle.close().catch(() => { }));
+                    }
+                    conn.socket.destroy();
+                }
+                connections.clear();
+                await Promise.all(closePromises);
+                await closePromise;
+                if (process.platform !== "win32") {
+                    try {
+                        await rm(endpointPath, { force: true });
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            })();
+            return closing;
+        },
+    };
+}
+//# sourceMappingURL=local-host.js.map

package/dist/mcp/server.js

@@ -3,9 +3,9 @@ import { z } from "zod";
 import { OkfError } from "../errors.js";
 import { FEEDBACK_TYPES, feedbackLink } from "../service/feedback.js";
 import { VERSION } from "../version.js";
-export const INSTRUCTIONS = `ok-fine holds shared project knowledge outside the codebase, as OKF v0.2 markdown concepts grouped into projects. In a git repository, first run \`git remote get-url origin\` and call list_projects with that URL as \`repository\`; use the returned project(s) for every read and write. If none match, say the repository is not onboarded and offer to onboard it (ok-fine-onboard skill). Search before non-trivial work; record durable decisions, conventions, and runbooks afterwards.
+export const INSTRUCTIONS = `ok-fine holds shared project knowledge outside the codebase, as OKF v0.2 markdown concepts grouped into projects. In a git repository, first run \`git remote get-url origin\` and call list_projects with that URL as \`repository\`; use the returned project(s) for every read and write. If none match, say the repository is not onboarded and offer to onboard it (ok-fine-onboard skill). Search before planning or editing; record durable decisions, conventions, and runbooks afterwards.
 1. Discover: get_index (progressive disclosure) or search_concepts with \`project\`.
-2. Read: read_concept returns frontmatter, body, trust tier (unverified | machine-confirmed | human-reviewed), staleness, and links. Freshness comes first: a concept that is stale, or whose code sources changed since \`sources[].commit\`, is a lead to re-check whatever its tier; among fresh concepts prefer higher trust tiers. Deprecated concepts are history; when code contradicts a concept, trust the code and update the concept.
+2. Read: read_concept returns frontmatter, body, trust tier (unverified | machine-confirmed | human-reviewed), staleness, and links. Freshness comes first: a concept that is stale, when its code sources changed since \`sources[].commit\`, or when that commit is not an ancestor of HEAD (unmerged or rebased away), is a lead to re-check whatever its tier; among fresh concepts prefer higher trust tiers. Knowledge about unmerged work goes into \`proposals/<slug>\` concepts with a \`proposal: { ref: <URI> }\` frontmatter key, never into current-state concepts; concepts carrying \`proposal\` are not current truth. Deprecated concepts are history; when code contradicts a concept, trust the code and update the concept.
 3. Write: write_concept with frontmatter containing \`type\` (e.g. Decision, Convention, Architecture, Component, Playbook, Interface, Reference) plus \`title\`, \`description\`, \`tags\`, and \`stale_after\` (ISO 8601, e.g. 180 days ahead). Record provenance in \`sources\` (each with \`resource\` and a stable \`id\`; code sources carry \`commit\`) and cite claims with footnotes [^id]. Link concepts with bundle-absolute links such as [orders](/tables/orders.md). After re-checking a concept against the code, refresh \`sources[].commit\` and \`stale_after\` with write_concept, then call verify_concept.
 4. Pass \`actor\` as <harness>/<model> (e.g. claude-code/claude-opus-4-5, codex/gpt-5-codex, gemini-cli/gemini-2.5-pro). Use human:<email>, with the email from \`git config user.email\`, only when the user personally reviewed the concept; on forbidden_actor, report both identities instead of retrying as another. The server stamps \`generated\`; \`verified\` changes only through verify_concept.
 5. When updating, pass expectedRevision from read_concept (null to create only).

package/dist/server.js

@@ -1,6 +1,5 @@
 import { setTimeout as sleep } from "node:timers/promises";
 import { buildOAuthProtectedResourceMetadata, createMcpHandler, getOAuthProtectedResourceMetadataUrl, } from "@modelcontextprotocol/server";
-import { StdioServerTransport, serveStdio } from "@modelcontextprotocol/server/stdio";
 import Fastify, {} from "fastify";
 import { ZodError } from "zod";
 import { discoverAuthorizationServer } from "./auth/discovery.js";
@@ -10,6 +9,7 @@ import { OkfError } from "./errors.js";
 import { registerMcpRoute } from "./http/mcp-route.js";
 import { registerRestRoutes } from "./http/rest.js";
 import { DEFAULT_UI_DIR, endpointOrigins, registerUiRoutes } from "./http/ui.js";
+import { createLocalHost } from "./local-host.js";
 import { createMcpServer } from "./mcp/server.js";
 import { KnowledgeService } from "./service/knowledge-service.js";
 import { Catalog } from "./store/catalog.js";
@@ -42,6 +42,9 @@ function parseHostHeader(hostHeader) {
     return trimmed.toLowerCase();
 }
 export async function startServer(config, options = {}) {
+    if (options.hostEndpoint && config.auth.mode !== "none") {
+        throw new Error("Cannot enable hostEndpoint with auth mode oidc");
+    }
     const tp = config.trustProxy;
     const trustProxy = typeof tp === "number"
         ? (_addr, hop) => hop < tp
@@ -262,13 +265,28 @@ export async function startServer(config, options = {}) {
         registerMcpRoute(secured, (request, options) => mcpHandler.fetch(request, options), config.publicBaseUrl);
         registerRestRoutes(secured, service);
     });
-    const address = await app.listen({ port: config.port, host: config.host });
     const stopSync = startPeriodicSync(config, service, app.log);
+    let localHost;
+    if (options.hostEndpoint) {
+        localHost = await createLocalHost({ service, config, log: app.log });
+    }
+    let address;
+    try {
+        address = await app.listen({ port: config.port, host: config.host });
+    }
+    catch (err) {
+        stopSync();
+        await localHost?.close();
+        await storage.close();
+        await mcpHandler.close();
+        throw err;
+    }
     return {
         app,
         url: address,
         close: async () => {
             stopSync();
+            await localHost?.close();
             await app.close();
             await storage.close();
             await mcpHandler.close();
@@ -299,40 +317,22 @@ function startPeriodicSync(config, service, log) {
         clearTimeout(syncTimer);
     };
 }
-/** Serves MCP over stdio to one local client with full permissions. Only the transport writes to stdout. */
-export async function startStdioServer(config, options) {
+/** Starts the local endpoint host that listens on a domain socket / named pipe. */
+export async function startLocalHost(config, options) {
     const { log } = options;
-    const stdin = options.stdin ?? process.stdin;
-    const stdout = options.stdout ?? process.stdout;
     const storage = await GitBackend.open(config, log);
     const catalog = new Catalog();
     const service = new KnowledgeService({ config, storage, catalog, log });
     await service.initialize();
-    const principal = {
-        subject: "local",
-        clientId: "stdio",
-        identity: options.identity,
-        scopes: [],
-        canRead: true,
-        canWrite: true,
-        canAdmin: true,
-    };
     const stopSync = startPeriodicSync(config, service, log);
-    // serveStdio owns transport.onclose, so watch stdin directly.
-    const { promise: done, resolve } = Promise.withResolvers();
-    stdin.once("end", resolve);
-    stdin.once("close", resolve);
-    const handle = serveStdio(() => createMcpServer(service, principal, log), {
-        transport: new StdioServerTransport(stdin, stdout),
-        onerror: (err) => log.error({ err }, "stdio transport error"),
-    });
+    const host = await createLocalHost({ service, config, log });
     let closing;
     return {
-        done,
+        endpointPath: host.endpointPath,
         close: () => {
             closing ??= (async () => {
                 stopSync();
-                await handle.close();
+                await host.close();
                 // Waits for the storage mutex, so an in-flight write still commits.
                 await storage.close();
             })();

package/dist/stdio-proxy.js

@@ -0,0 +1,349 @@
+import net from "node:net";
+import { setTimeout as sleep } from "node:timers/promises";
+import { z } from "zod";
+import { isProcessAlive, tryLockDataDir } from "./data-dir-lock.js";
+import { localEndpointPath } from "./local-host.js";
+const JsonRpcMessageSchema = z
+    .object({
+    jsonrpc: z.string().optional(),
+    id: z.union([z.string(), z.number()]).optional(),
+    method: z.string().optional(),
+    params: z.unknown().optional(),
+    result: z.unknown().optional(),
+    error: z.unknown().optional(),
+})
+    .passthrough();
+function tryConnectSocket(endpoint) {
+    const { promise, resolve } = Promise.withResolvers();
+    const socket = net.createConnection(endpoint);
+    const onError = () => {
+        socket.destroy();
+        resolve(null);
+    };
+    socket.once("error", onError);
+    socket.once("connect", () => {
+        socket.off("error", onError);
+        resolve(socket);
+    });
+    return promise;
+}
+async function connectSocket(endpoint, timeoutMs) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const socket = await tryConnectSocket(endpoint);
+        if (socket)
+            return socket;
+        await sleep(25);
+    }
+    throw new Error(`Failed to connect to local endpoint at ${endpoint}`);
+}
+/**
+ * Starts a stdio proxy session. Every stdio CLI process is a proxy:
+ * runs election to start the local endpoint host if it acquires the lock,
+ * or attaches to an existing host.
+ */
+export async function startStdioProxy(options) {
+    const { config, identity, log, startHost } = options;
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const timeoutMs = options.electionTimeoutMs ?? 30_000;
+    const endpoint = localEndpointPath(config.dataDir);
+    const { promise: done, resolve: resolveDone } = Promise.withResolvers();
+    let shuttingDown = false;
+    let isFailingOver = false;
+    let isReconnecting = false;
+    let activeSocket = null;
+    let activeHost = null;
+    let activeLockRelease = null;
+    /** Drops the current socket and, if this process hosts, closes the host and releases the lock. */
+    async function teardownActive() {
+        const socket = activeSocket;
+        activeSocket = null;
+        if (socket) {
+            socket.removeAllListeners();
+            socket.destroy();
+        }
+        const host = activeHost;
+        activeHost = null;
+        if (host)
+            await host.close().catch((err) => log.error({ err }, "closing local host failed"));
+        const release = activeLockRelease;
+        activeLockRelease = null;
+        release?.();
+    }
+    let storedInitialize = null;
+    let storedInitialized = null;
+    const inFlightRequests = new Map();
+    const pendingStdinLines = [];
+    let replaySeq = 0;
+    let awaitingReplayId = null;
+    let onReplayResponse = null;
+    async function runElection(deadline) {
+        while (Date.now() < deadline && !shuttingDown) {
+            const lockRes = await tryLockDataDir(config.dataDir);
+            if (lockRes.acquired) {
+                activeLockRelease = lockRes.release;
+                try {
+                    activeHost = await startHost();
+                    const remainingMs = Math.min(5000, Math.max(100, deadline - Date.now()));
+                    return await connectSocket(endpoint, remainingMs);
+                }
+                catch (err) {
+                    if (activeHost) {
+                        await activeHost.close().catch(() => { });
+                        activeHost = null;
+                    }
+                    activeLockRelease();
+                    activeLockRelease = null;
+                    throw err;
+                }
+            }
+            const holderPid = lockRes.holderPid;
+            if (holderPid !== null && isProcessAlive(holderPid)) {
+                const socket = await tryConnectSocket(endpoint);
+                if (socket)
+                    return socket;
+            }
+            await sleep(50);
+        }
+        const timeoutStr = timeoutMs % 1000 === 0 ? `${timeoutMs / 1000}s` : `${timeoutMs}ms`;
+        throw new Error(`Timed out waiting for ok-fine host on ${config.dataDir} after ${timeoutStr}`);
+    }
+    function handleStdinLine(line) {
+        let msg = null;
+        try {
+            const parsed = JsonRpcMessageSchema.safeParse(JSON.parse(line));
+            if (parsed.success)
+                msg = parsed.data;
+        }
+        catch {
+            // Non-JSON line, forward as-is
+        }
+        if (msg) {
+            if (msg.method === "initialize" && msg.id !== undefined) {
+                storedInitialize = { raw: line, parsed: msg };
+            }
+            else if (msg.method === "notifications/initialized") {
+                storedInitialized = line;
+            }
+            if (msg.id !== undefined && msg.method !== undefined) {
+                inFlightRequests.set(msg.id, msg.id);
+            }
+        }
+        if (isReconnecting || !activeSocket || activeSocket.destroyed || !activeSocket.writable) {
+            pendingStdinLines.push(line);
+        }
+        else {
+            activeSocket.write(`${line}\n`);
+        }
+    }
+    let stdinBuffer = "";
+    function onStdinData(chunk) {
+        stdinBuffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        while (true) {
+            const idx = stdinBuffer.indexOf("\n");
+            if (idx === -1)
+                break;
+            const line = stdinBuffer.slice(0, idx).replace(/\r$/, "");
+            stdinBuffer = stdinBuffer.slice(idx + 1);
+            if (line.length > 0) {
+                handleStdinLine(line);
+            }
+        }
+    }
+    function handleSocketLine(line) {
+        let msg = null;
+        try {
+            const parsed = JsonRpcMessageSchema.safeParse(JSON.parse(line));
+            if (parsed.success)
+                msg = parsed.data;
+        }
+        catch {
+            // Non-JSON line
+        }
+        if (msg && awaitingReplayId !== null && msg.id === awaitingReplayId) {
+            const resolve = onReplayResponse;
+            awaitingReplayId = null;
+            onReplayResponse = null;
+            resolve?.();
+            return;
+        }
+        if (msg && msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+            inFlightRequests.delete(msg.id);
+        }
+        stdout.write(`${line}\n`);
+    }
+    let socketBuffer = "";
+    function onSocketData(chunk) {
+        socketBuffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        while (true) {
+            const idx = socketBuffer.indexOf("\n");
+            if (idx === -1)
+                break;
+            const line = socketBuffer.slice(0, idx).replace(/\r$/, "");
+            socketBuffer = socketBuffer.slice(idx + 1);
+            if (line.length > 0) {
+                handleSocketLine(line);
+            }
+        }
+    }
+    async function handleSocketClose() {
+        if (shuttingDown || isFailingOver)
+            return;
+        isFailingOver = true;
+        isReconnecting = true;
+        try {
+            await teardownActive();
+            // Answer every in-flight request with host restart error
+            for (const id of inFlightRequests.values()) {
+                const errorResponse = {
+                    jsonrpc: "2.0",
+                    id,
+                    error: {
+                        code: -32603,
+                        message: "ok-fine host restarted; retry the request",
+                    },
+                };
+                stdout.write(`${JSON.stringify(errorResponse)}\n`);
+            }
+            inFlightRequests.clear();
+            const deadline = Date.now() + timeoutMs;
+            let connectedSocket = null;
+            while (Date.now() < deadline && !shuttingDown) {
+                try {
+                    const socket = await runElection(deadline);
+                    attachSocket(socket);
+                    socket.write(`${JSON.stringify({ okFine: 1, identity })}\n`);
+                    if (storedInitialize) {
+                        const replayId = `okf-replay-${++replaySeq}`;
+                        awaitingReplayId = replayId;
+                        const remainingMs = Math.max(1, deadline - Date.now());
+                        const replayTimeoutMs = Math.min(timeoutMs, remainingMs);
+                        const { promise: replayPromise, resolve: resolveReplay, reject: rejectReplay, } = Promise.withResolvers();
+                        onReplayResponse = resolveReplay;
+                        const onEarlyClose = () => {
+                            rejectReplay(new Error("Socket closed while awaiting initialize replay response"));
+                        };
+                        const onEarlyError = (err) => {
+                            rejectReplay(err);
+                        };
+                        const timer = setTimeout(() => {
+                            const timeoutStr = replayTimeoutMs % 1000 === 0 ? `${replayTimeoutMs / 1000}s` : `${replayTimeoutMs}ms`;
+                            rejectReplay(new Error(`Timed out awaiting initialize replay response after ${timeoutStr}`));
+                        }, replayTimeoutMs);
+                        socket.once("close", onEarlyClose);
+                        socket.once("error", onEarlyError);
+                        try {
+                            const replayReq = { ...storedInitialize.parsed, id: replayId };
+                            socket.write(`${JSON.stringify(replayReq)}\n`);
+                            await replayPromise;
+                            if (storedInitialized) {
+                                socket.write(`${storedInitialized}\n`);
+                            }
+                            else {
+                                socket.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`);
+                            }
+                        }
+                        finally {
+                            clearTimeout(timer);
+                            socket.off("close", onEarlyClose);
+                            socket.off("error", onEarlyError);
+                            if (awaitingReplayId === replayId) {
+                                awaitingReplayId = null;
+                                onReplayResponse = null;
+                            }
+                        }
+                    }
+                    connectedSocket = socket;
+                    break;
+                }
+                catch (attemptErr) {
+                    log.debug({ err: attemptErr }, "failover attempt failed, retrying");
+                    await teardownActive();
+                    if (Date.now() >= deadline || shuttingDown) {
+                        throw attemptErr;
+                    }
+                    await sleep(50);
+                }
+            }
+            if (!connectedSocket && !shuttingDown) {
+                const timeoutStr = timeoutMs % 1000 === 0 ? `${timeoutMs / 1000}s` : `${timeoutMs}ms`;
+                throw new Error(`Timed out waiting for ok-fine host on ${config.dataDir} after ${timeoutStr}`);
+            }
+            isReconnecting = false;
+            const queued = pendingStdinLines.splice(0, pendingStdinLines.length);
+            for (const q of queued) {
+                connectedSocket?.write(`${q}\n`);
+            }
+        }
+        catch (err) {
+            log.error({ err }, "proxy failover failed");
+            await shutdown();
+        }
+        finally {
+            isFailingOver = false;
+        }
+    }
+    function attachSocket(socket) {
+        activeSocket = socket;
+        socketBuffer = "";
+        socket.on("data", onSocketData);
+        socket.on("error", (err) => log.debug({ err }, "proxy socket error"));
+        socket.once("close", () => {
+            void handleSocketClose();
+        });
+    }
+    async function shutdown() {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        stdin.off("data", onStdinData);
+        if (activeSocket) {
+            activeSocket.removeAllListeners();
+            activeSocket.destroy();
+            activeSocket = null;
+        }
+        if (activeHost) {
+            try {
+                await activeHost.close();
+            }
+            catch (err) {
+                log.error({ err }, "error closing host on shutdown");
+            }
+            activeHost = null;
+        }
+        if (activeLockRelease) {
+            try {
+                activeLockRelease();
+            }
+            catch (err) {
+                log.error({ err }, "error releasing lock on shutdown");
+            }
+            activeLockRelease = null;
+        }
+        resolveDone();
+    }
+    // Initial election and connection
+    const initialSocket = await runElection(Date.now() + timeoutMs);
+    attachSocket(initialSocket);
+    initialSocket.write(`${JSON.stringify({ okFine: 1, identity })}\n`);
+    stdin.on("data", onStdinData);
+    stdin.once("end", () => {
+        void shutdown();
+    });
+    stdin.once("close", () => {
+        void shutdown();
+    });
+    if (stdin.readableEnded || stdin.destroyed) {
+        void shutdown();
+    }
+    let closing;
+    return {
+        done,
+        close: () => {
+            closing ??= shutdown();
+            return closing;
+        },
+    };
+}
+//# sourceMappingURL=stdio-proxy.js.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.3.7";
+export const VERSION = "0.3.8";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferrule-io/ok-fine",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "OKF v0.2 knowledge repository for AI agents (MCP + REST)",
   "license": "Apache-2.0",
   "repository": {