@ferrule-io/ok-fine 0.3.7 → 0.3.9

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/http/ui.js

@@ -17,6 +17,9 @@ const CONTENT_TYPES = {
     ".txt": "text/plain; charset=utf-8",
 };
 const IMMUTABLE = "public, max-age=31536000, immutable";
+const PERMISSIONS_POLICY = "camera=(), display-capture=(), geolocation=(), microphone=()";
+const SVG_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";
+const DEFAULT_CSP = "frame-ancestors 'none'";
 /** Unique origins of the string http(s) URLs among `endpoints`; ignores anything else. */
 export function endpointOrigins(...endpoints) {
     const origins = new Set();
@@ -67,50 +70,61 @@ export async function registerUiRoutes(app, options) {
         app.log.warn({ dir: options.dir }, "web UI assets not found; /ui disabled");
         return false;
     }
-    const csp = [
+    const htmlCsp = [
         "default-src 'self'",
         "script-src 'self'",
-        // Shiki emits inline style attributes.
+        // Shiki emits inline style attributes for code block syntax highlighting.
         "style-src 'self' 'unsafe-inline'",
-        "img-src 'self' data: https:",
+        "img-src 'self' data:",
         "font-src 'self' data:",
         `connect-src 'self'${options.connectSrc.map((origin) => ` ${origin}`).join("")}`,
         "object-src 'none'",
         "base-uri 'none'",
         "form-action 'none'",
         "frame-ancestors 'none'",
+        ...(options.publicBaseUrl.startsWith("https://") ? ["upgrade-insecure-requests"] : []),
     ].join("; ");
-    const sendHtml = (reply) => reply
-        .header("content-type", "text/html; charset=utf-8")
-        .header("cache-control", "no-cache")
-        .header("referrer-policy", "no-referrer")
-        .header("x-frame-options", "DENY")
-        .header("x-content-type-options", "nosniff")
-        .header("content-security-policy", csp)
-        .send(index.body);
-    app.get("/", async (_req, reply) => reply.redirect("/ui/", 302));
-    app.get("/ui", async (_req, reply) => reply.redirect("/ui/", 301));
-    app.get("/ui/config.json", async (_req, reply) => reply.header("cache-control", "no-store").header("x-content-type-options", "nosniff").send(options.clientConfig));
-    app.get("/ui/*", async (req, reply) => {
-        const rel = req.params["*"];
-        if (rel === "" || rel === "index.html")
+    await app.register(async (ui) => {
+        ui.addHook("onSend", async (_req, reply, payload) => {
+            reply.header("x-content-type-options", "nosniff");
+            reply.header("x-frame-options", "DENY");
+            reply.header("referrer-policy", "no-referrer");
+            reply.header("cross-origin-opener-policy", "same-origin");
+            reply.header("permissions-policy", PERMISSIONS_POLICY);
+            const contentType = reply.getHeader("content-type");
+            if (typeof contentType === "string" && contentType.startsWith("image/svg+xml")) {
+                reply.header("content-security-policy", SVG_CSP);
+            }
+            else if (!reply.hasHeader("content-security-policy")) {
+                reply.header("content-security-policy", DEFAULT_CSP);
+            }
+            return payload;
+        });
+        const sendHtml = (reply) => reply
+            .header("content-type", "text/html; charset=utf-8")
+            .header("cache-control", "no-cache")
+            .header("content-security-policy", htmlCsp)
+            .send(index.body);
+        ui.get("/", async (_req, reply) => reply.redirect("/ui/", 302));
+        ui.get("/ui", async (_req, reply) => reply.redirect("/ui/", 301));
+        ui.get("/ui/config.json", async (_req, reply) => reply.header("cache-control", "no-store").send(options.clientConfig));
+        ui.get("/ui/*", async (req, reply) => {
+            const rel = req.params["*"];
+            if (rel === "" || rel === "index.html")
+                return sendHtml(reply);
+            const asset = assets.get(rel);
+            if (asset) {
+                return reply.header("content-type", asset.type).header("cache-control", asset.cache).send(asset.body);
+            }
+            const last = rel.slice(rel.lastIndexOf("/") + 1);
+            if (/\.[A-Za-z0-9]+$/.test(last)) {
+                return reply
+                    .code(404)
+                    .header("cache-control", "no-cache")
+                    .send({ error: { code: "not_found", message: "not found" } });
+            }
             return sendHtml(reply);
-        const asset = assets.get(rel);
-        if (asset) {
-            return reply
-                .header("content-type", asset.type)
-                .header("cache-control", asset.cache)
-                .header("x-content-type-options", "nosniff")
-                .send(asset.body);
-        }
-        const last = rel.slice(rel.lastIndexOf("/") + 1);
-        if (/\.[A-Za-z0-9]+$/.test(last)) {
-            return reply
-                .code(404)
-                .header("x-content-type-options", "nosniff")
-                .send({ error: { code: "not_found", message: "not found" } });
-        }
-        return sendHtml(reply);
+        });
     });
     app.log.info({ url: `${options.publicBaseUrl}/ui/` }, "web UI enabled");
     return true;

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
@@ -147,7 +150,10 @@ export async function startServer(config, options = {}) {
             }
             const host = parseHostHeader(req.headers.host);
             if (!host || !allowedHosts[host]) {
-                return reply.code(403).send({
+                return reply
+                    .code(403)
+                    .header("x-content-type-options", "nosniff")
+                    .send({
                     error: {
                         code: "forbidden",
                         message: `Host header '${req.headers.host ?? ""}' is not allowed in AUTH_MODE=none`,
@@ -170,7 +176,10 @@ export async function startServer(config, options = {}) {
                     }
                 }
                 if (!originAllowed) {
-                    return reply.code(403).send({
+                    return reply
+                        .code(403)
+                        .header("x-content-type-options", "nosniff")
+                        .send({
                         error: {
                             code: "forbidden",
                             message: `Origin '${rawOrigin ?? ""}' is not allowed in AUTH_MODE=none`,
@@ -262,13 +271,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 +323,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();
             })();