@gamaze/hicortex 0.23.0 → 0.23.1

package/dist/llm.d.ts

@@ -237,9 +237,20 @@ export declare class LlmClient {
     private acquireFlightGuard;
     private dispatchOnce;
     /**
-     * Claude CLI: shell out to `claude -p` for subscription users.
+     * Claude CLI: invoke `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.
      *
+     * Invocation contract (#512): the binary is called with a plain argument
+     * array and NO shell; the prompt travels on the child's stdin (execFileSync
+     * pipes stdin when `input` is set — the `< /dev/null` of the old shell
+     * command line is gone with the shell). The prompt is transcript-derived
+     * data, so it must reach the binary as bytes, never as command-line text
+     * an intermediary could interpret; argv stays exactly the fixed flag set.
+     * Side effects: stdin delivery lifts the per-argument exec limit on long
+     * transcripts, and a claudePath containing spaces works (one argv element,
+     * never re-parsed). cwd is left unset on purpose — the child inherits
+     * process.cwd() like every other phase of the daemon.
+     *
      * Token usage (#246): the claude CLI JSON output does not carry a token
      * usage field, so this path returns `usage: undefined`. The CLI is billed
      * by Claude subscription, not per-token — there is nothing to meter. The

package/dist/llm.js

@@ -570,9 +570,20 @@ class LlmClient {
         return this.completeOpenAiCompat(model, prompt, maxTokens, timeoutMs);
     }
     /**
-     * Claude CLI: shell out to `claude -p` for subscription users.
+     * Claude CLI: invoke `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.
      *
+     * Invocation contract (#512): the binary is called with a plain argument
+     * array and NO shell; the prompt travels on the child's stdin (execFileSync
+     * pipes stdin when `input` is set — the `< /dev/null` of the old shell
+     * command line is gone with the shell). The prompt is transcript-derived
+     * data, so it must reach the binary as bytes, never as command-line text
+     * an intermediary could interpret; argv stays exactly the fixed flag set.
+     * Side effects: stdin delivery lifts the per-argument exec limit on long
+     * transcripts, and a claudePath containing spaces works (one argv element,
+     * never re-parsed). cwd is left unset on purpose — the child inherits
+     * process.cwd() like every other phase of the daemon.
+     *
      * Token usage (#246): the claude CLI JSON output does not carry a token
      * usage field, so this path returns `usage: undefined`. The CLI is billed
      * by Claude subscription, not per-token — there is nothing to meter. The
@@ -580,10 +591,10 @@ class LlmClient {
      * correct outcome (no meterable cost to defend against).
      */
     async completeClaude(model, prompt, timeoutMs) {
-        const { execSync } = require("node:child_process");
+        const { execFileSync } = require("node:child_process");
         const claudePath = this.config.baseUrl; // baseUrl stores the claude binary path
         try {
-            const raw = execSync(`${claudePath} -p ${JSON.stringify(prompt)} --model ${model} --max-turns 1 --output-format json --no-session-persistence < /dev/null`, { encoding: "utf-8", timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 });
+            const raw = execFileSync(claudePath, ["-p", "--model", model, "--max-turns", "1", "--output-format", "json", "--no-session-persistence"], { encoding: "utf-8", timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024, input: prompt });
             const data = JSON.parse(raw);
             if (data.is_error) {
                 throw new Error(`Claude CLI error: ${data.result}`);

package/dist/mcp-stdio.d.ts

@@ -42,6 +42,27 @@
  * port: explicit error, never a spawn. A remote target that is down is
  * likewise an explicit error — we never spawn for remote URLs.
  *
+ * Startup retry (#501): a REMOTE target that is unreachable at launch is
+ * TRANSIENT, not fatal — the product case is a client (e.g. Claude Desktop
+ * auto-launched at login) starting before the VPN/DNS that carries the
+ * server URL is up (ENOTFOUND/EAI_AGAIN/ECONNREFUSED/timeouts). The bridge
+ * then keeps the stdio side ALIVE and answers `initialize` IMMEDIATELY
+ * (design B), retrying the upstream connect with backoff (1s→2s→4s… capped
+ * 10s) for a 60s window. Why answer immediately: MCP clients cancel a
+ * pending `initialize` at ~60s (TS SDK DEFAULT_REQUEST_TIMEOUT_MSEC;
+ * Claude Desktop observed cancelling at ~60s in the wild) — a delayed
+ * initialize would lose the session the retry window is meant to save, and
+ * the first tools/list request carries the same ~60s client budget, so the
+ * window deliberately stays at the BOTTOM of the 60–90s range the issue
+ * proposed (evidence + decision: issue #501 design-note comment). The
+ * daemon's initialize-result `instructions` are unknowable while it is down
+ * and are therefore omitted on this path (the pre-#383 shape); tools
+ * handlers await upstream readiness. NEVER retried: 401/403 (auth is not
+ * transient — existing HICORTEX_AUTH_TOKEN hint) and a reachable-but-not-
+ * healthy endpoint (foreign service). Local targets keep the autostart poll
+ * (which already waits 30s). Mid-session SSE reconnect after an established
+ * connection drops is OUT OF SCOPE (#501 follow-up).
+ *
  * STDIO DISCIPLINE: stdout carries ONLY the MCP protocol. Every diagnostic
  * goes to stderr; fatal errors are a one-liner on stderr + non-zero exit
  * (thrown to cli.ts's catch). Cancellation downstream→upstream rides the
@@ -51,6 +72,7 @@
  * upstream request id (a verbatim forward would carry the downstream id,
  * which means nothing to the daemon) — and reject the in-flight bridge call.
  */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 /** Where the bridge target came from — surfaces in the startup diagnostic. */
 export type BridgeTargetSource = "option" | "env" | "config" | "default";
@@ -122,6 +144,16 @@ export interface EnsureDaemonOptions {
  * every fail-path (explicit error, never silent degradation).
  */
 export declare function ensureDaemonReady(target: BridgeTarget, options?: EnsureDaemonOptions): Promise<void>;
+export type StartupFailureKind = "auth" | "foreign" | "transient" | "fatal";
+/**
+ * Classify a startup failure of the upstream connect sequence. Only a REMOTE
+ * target's network-level failure is transient (#501); auth rejections and a
+ * reachable-but-unhealthy endpoint are fatal immediately, and local targets
+ * keep their own autostart-poll semantics.
+ */
+export declare function classifyStartupFailure(err: unknown, target: BridgeTarget): StartupFailureKind;
+/** Backoff step N (0-based): base·2^N, capped — 1s, 2s, 4s, 8s, then the cap. */
+export declare function nextRetryDelayMs(attempt: number, baseMs: number, maxMs: number): number;
 export interface McpStdioOptions extends EnsureDaemonOptions {
     /** Explicit target URL (test seam; normally resolved from env/config). */
     serverUrl?: string;
@@ -129,10 +161,36 @@ export interface McpStdioOptions extends EnsureDaemonOptions {
     authToken?: string;
     /** Injectable downstream transport (test seam; default: real stdio). */
     downstream?: Transport;
+    /** Injectable upstream connect (test seam; default: real SSE transport). */
+    connectUpstream?: (target: BridgeTarget, token: string | undefined) => Promise<Client>;
+    /** Retry pacing for the #501 transient-unreachable window (test seams). */
+    retryWindowMs?: number;
+    retryBaseDelayMs?: number;
+    retryMaxDelayMs?: number;
 }
 /**
- * Run the stdio MCP bridge. Resolves only after the downstream transport
- * closes (the lifecycle handlers then exit the process); every setup failure
- * throws for cli.ts to report on stderr and exit 1.
+ * Connect the upstream Client to the daemon's SSE MCP endpoint. requestInit
+ * headers ride BOTH the GET /sse and the POST /messages (SDK 1.28
+ * _commonHeaders/send). Raw errors propagate — classification happens at the
+ * call site. Exported for the ghost-reconnect unit test.
+ *
+ * On failure the transport is closed EXPLICITLY: the SDK's Client.connect
+ * closes only when the initialize REQUEST fails after a successful start —
+ * a failed transport.start() (refused/DNS) propagates out of Protocol.connect
+ * with no cleanup, and the still-open EventSource keeps eventsource's ~3s
+ * reconnect loop alive. Every retry attempt would leak one ghost that, once
+ * the server appears, opens a REAL authed SSE session on the daemon and is
+ * never closed (proven empirically on SDK 1.28.0 / eventsource 3.0.7, PR
+ * review round 1 — pinned by the ghost-reconnect unit test).
+ */
+export declare function defaultConnectUpstream(target: BridgeTarget, token: string | undefined): Promise<Client>;
+/**
+ * Run the stdio MCP bridge. Fast path (daemon reachable now): connect
+ * upstream first, then serve stdio with the daemon's forwarded instructions
+ * — exactly the pre-#501 sequence. Slow path (REMOTE target, transient
+ * network failure — the boot race): serve stdio IMMEDIATELY (design B,
+ * initialize answered at once) and retry the upstream connect with backoff
+ * for the retry window. Resolves once bridging is established; every setup
+ * failure throws for cli.ts to report on stderr and exit 1.
  */
 export declare function runMcpStdio(options?: McpStdioOptions): Promise<void>;

package/dist/mcp-stdio.js

@@ -43,6 +43,27 @@
  * port: explicit error, never a spawn. A remote target that is down is
  * likewise an explicit error — we never spawn for remote URLs.
  *
+ * Startup retry (#501): a REMOTE target that is unreachable at launch is
+ * TRANSIENT, not fatal — the product case is a client (e.g. Claude Desktop
+ * auto-launched at login) starting before the VPN/DNS that carries the
+ * server URL is up (ENOTFOUND/EAI_AGAIN/ECONNREFUSED/timeouts). The bridge
+ * then keeps the stdio side ALIVE and answers `initialize` IMMEDIATELY
+ * (design B), retrying the upstream connect with backoff (1s→2s→4s… capped
+ * 10s) for a 60s window. Why answer immediately: MCP clients cancel a
+ * pending `initialize` at ~60s (TS SDK DEFAULT_REQUEST_TIMEOUT_MSEC;
+ * Claude Desktop observed cancelling at ~60s in the wild) — a delayed
+ * initialize would lose the session the retry window is meant to save, and
+ * the first tools/list request carries the same ~60s client budget, so the
+ * window deliberately stays at the BOTTOM of the 60–90s range the issue
+ * proposed (evidence + decision: issue #501 design-note comment). The
+ * daemon's initialize-result `instructions` are unknowable while it is down
+ * and are therefore omitted on this path (the pre-#383 shape); tools
+ * handlers await upstream readiness. NEVER retried: 401/403 (auth is not
+ * transient — existing HICORTEX_AUTH_TOKEN hint) and a reachable-but-not-
+ * healthy endpoint (foreign service). Local targets keep the autostart poll
+ * (which already waits 30s). Mid-session SSE reconnect after an established
+ * connection drops is OUT OF SCOPE (#501 follow-up).
+ *
  * STDIO DISCIPLINE: stdout carries ONLY the MCP protocol. Every diagnostic
  * goes to stderr; fatal errors are a one-liner on stderr + non-zero exit
  * (thrown to cli.ts's catch). Cancellation downstream→upstream rides the
@@ -59,6 +80,9 @@ exports.resolveBridgeToken = resolveBridgeToken;
 exports.probeHealthOnce = probeHealthOnce;
 exports.decideAutostart = decideAutostart;
 exports.ensureDaemonReady = ensureDaemonReady;
+exports.classifyStartupFailure = classifyStartupFailure;
+exports.nextRetryDelayMs = nextRetryDelayMs;
+exports.defaultConnectUpstream = defaultConnectUpstream;
 exports.runMcpStdio = runMcpStdio;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -83,6 +107,14 @@ const DEFAULT_BRIDGE_PORT = 8787;
 const HEALTH_PROBE_TIMEOUT_MS = 2000;
 const AUTOSTART_POLL_INTERVAL_MS = 250;
 const AUTOSTART_POLL_TOTAL_MS = 30_000;
+// #501 startup-retry window. 60s — the bottom of the issue's 60–90s proposal,
+// deliberately: the client's own request timeout (TS SDK default, and Claude
+// Desktop's observed initialize cancel) is 60s, and under design B the FIRST
+// tools/list inherits that same budget, so a longer window would only answer
+// requests the client has already abandoned.
+const REMOTE_RETRY_WINDOW_MS = 60_000;
+const REMOTE_RETRY_BASE_DELAY_MS = 1_000;
+const REMOTE_RETRY_MAX_DELAY_MS = 10_000;
 /** Loopback check for URL hostnames (Node's URL keeps the brackets on [::1]). */
 function isLoopbackHost(hostname) {
     return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
@@ -160,6 +192,13 @@ async function probeHealthOnce(url, timeoutMs = HEALTH_PROBE_TIMEOUT_MS) {
         return { reachable: false, ok: false };
     }
 }
+/** The clear unreachable message — shared by the fail-fast path and the #501
+ *  retry-window expiry, so both ends of the window say the same thing. */
+function remoteUnreachableMessage(target) {
+    return (`Cannot reach the Hicortex server at ${target.url}. Start it on the server machine ` +
+        `(check with \`hicortex status\`, start with \`npx @gamaze/hicortex server\`) or fix HICORTEX_SERVER_URL. ` +
+        `If it answers 401 once up, set HICORTEX_AUTH_TOKEN to the server's auth token.`);
+}
 /**
  * Pure decision from one health probe: healthy → bridge; refused + loopback
  * → spawn a local daemon; refused + remote → fail with an actionable message
@@ -177,14 +216,8 @@ function decideAutostart(probe, target) {
                 `then either free the port or point HICORTEX_SERVER_URL at the real Hicortex server.`,
         };
     }
-    if (!target.local) {
-        return {
-            action: "fail",
-            reason: `Cannot reach the Hicortex server at ${target.url}. Start it on the server machine ` +
-                `(check with \`hicortex status\`, start with \`npx @gamaze/hicortex server\`) or fix HICORTEX_SERVER_URL. ` +
-                `If it answers 401 once up, set HICORTEX_AUTH_TOKEN to the server's auth token.`,
-        };
-    }
+    if (!target.local)
+        return { action: "fail", reason: remoteUnreachableMessage(target) };
     return { action: "spawn" };
 }
 /**
@@ -234,49 +267,135 @@ async function ensureDaemonReady(target, options = {}) {
         `${Math.round(totalMs / 1000)}s of autostart. Try \`npx @gamaze/hicortex server\` in a terminal ` +
         `to see the daemon's startup error, then re-run this command.`);
 }
+/** Node/undici errno codes a "network not up yet" boot race produces. */
+const TRANSIENT_ERRNO_RE = /\b(?:ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|UND_ERR_CONNECT_TIMEOUT)\b/;
+/** SseError carries the HTTP status on .code (SDK client/sse.js). */
+function isAuthRejection(err) {
+    const code = err?.code;
+    return code === 401 || code === 403 || code === "401" || code === "403";
+}
 /**
- * Run the stdio MCP bridge. Resolves only after the downstream transport
- * closes (the lifecycle handlers then exit the process); every setup failure
- * throws for cli.ts to report on stderr and exit 1.
+ * A network-level failure that a retry window can plausibly outlive: walk the
+ * error + its cause chain for a transient errno, a fetch/undici timeout name,
+ * or errno text embedded in the message (SseError has no `cause` — the SDK
+ * puts the underlying text straight into `SSE error: getaddrinfo ENOTFOUND …`).
  */
-async function runMcpStdio(options = {}) {
-    const target = resolveBridgeTarget(options.serverUrl);
-    const token = resolveBridgeToken(options.authToken);
-    await ensureDaemonReady(target, options);
-    // Upstream: the daemon's SSE MCP endpoint. requestInit headers ride BOTH
-    // the GET /sse and the POST /messages (SDK 1.28 _commonHeaders/send).
+function isTransientNetworkError(err) {
+    let current = err;
+    for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
+        const code = current.code;
+        if (typeof code === "string" && TRANSIENT_ERRNO_RE.test(code))
+            return true;
+        if (current.name === "TimeoutError" || current.name === "AbortError")
+            return true;
+        if (TRANSIENT_ERRNO_RE.test(current.message))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * Classify a startup failure of the upstream connect sequence. Only a REMOTE
+ * target's network-level failure is transient (#501); auth rejections and a
+ * reachable-but-unhealthy endpoint are fatal immediately, and local targets
+ * keep their own autostart-poll semantics.
+ */
+function classifyStartupFailure(err, target) {
+    if (isAuthRejection(err))
+        return "auth";
+    const message = err instanceof Error ? err.message : String(err);
+    if (/not a healthy Hicortex/i.test(message))
+        return "foreign";
+    if (target.local)
+        return "fatal";
+    // decideAutostart's remote-unreachable reason is the probe-level shape of
+    // every refused/DNS-failed/timeout probe (probeHealthOnce collapses them).
+    if (message.startsWith("Cannot reach the Hicortex server"))
+        return "transient";
+    return isTransientNetworkError(err) ? "transient" : "fatal";
+}
+/** Backoff step N (0-based): base·2^N, capped — 1s, 2s, 4s, 8s, then the cap. */
+function nextRetryDelayMs(attempt, baseMs, maxMs) {
+    return Math.min(baseMs * 2 ** attempt, maxMs);
+}
+/** One-line reason for the stderr retry log — never the full fail message. */
+function summarizeStartupFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const errno = TRANSIENT_ERRNO_RE.exec(message)?.[0];
+    if (errno)
+        return errno;
+    if (message.startsWith("Cannot reach the Hicortex server"))
+        return "unreachable";
+    return message.length > 80 ? `${message.slice(0, 77)}…` : message;
+}
+/** The friendly fatal form: auth rejections get the token hint, the rest pass
+ *  through unchanged (their messages are already the actionable ones). */
+function toStartupError(err, target) {
+    if (isAuthRejection(err)) {
+        const status = err.code;
+        return new Error(`The Hicortex server at ${target.url} rejected the connection (${status}). ` +
+            `Set HICORTEX_AUTH_TOKEN to the server's auth token — it is printed by \`hicortex status\` on the server box.`);
+    }
+    return err instanceof Error ? err : new Error(String(err));
+}
+/**
+ * Connect the upstream Client to the daemon's SSE MCP endpoint. requestInit
+ * headers ride BOTH the GET /sse and the POST /messages (SDK 1.28
+ * _commonHeaders/send). Raw errors propagate — classification happens at the
+ * call site. Exported for the ghost-reconnect unit test.
+ *
+ * On failure the transport is closed EXPLICITLY: the SDK's Client.connect
+ * closes only when the initialize REQUEST fails after a successful start —
+ * a failed transport.start() (refused/DNS) propagates out of Protocol.connect
+ * with no cleanup, and the still-open EventSource keeps eventsource's ~3s
+ * reconnect loop alive. Every retry attempt would leak one ghost that, once
+ * the server appears, opens a REAL authed SSE session on the daemon and is
+ * never closed (proven empirically on SDK 1.28.0 / eventsource 3.0.7, PR
+ * review round 1 — pinned by the ghost-reconnect unit test).
+ */
+async function defaultConnectUpstream(target, token) {
     const upstream = new sse_js_1.SSEClientTransport(new URL(`${target.url}/sse`), token !== undefined ? { requestInit: { headers: { Authorization: `Bearer ${token}` } } } : {});
     const client = new index_js_2.Client({ name: "hicortex-mcp-bridge", version: VERSION });
     try {
         await client.connect(upstream);
     }
     catch (err) {
-        // 401 from the daemon's auth middleware (remote connections; loopback is
-        // exempt). SseError carries the HTTP status as .code.
-        if (err.code === 401) {
-            throw new Error(`The Hicortex server at ${target.url} rejected the connection (401). ` +
-                `Set HICORTEX_AUTH_TOKEN to the server's auth token — it is printed by \`hicortex status\` on the server box.`);
-        }
-        throw err instanceof Error ? err : new Error(String(err));
+        await client.close().catch(() => { });
+        throw err;
     }
-    // Downstream: a low-level Server over stdio advertising exactly what the
-    // daemon offers (tools). Ping is auto-answered by the Protocol base.
-    // #383: forward the DAEMON's initialize-result instructions verbatim — the
-    // daemon owns the text and the memoryInstructions gate, so the two surfaces
-    // cannot diverge and no config read is duplicated in the bridge (a
-    // pre-#383 remote daemon simply has none to forward; undefined omits the
-    // field from the bridge's own initialize result).
-    const server = new index_js_1.Server({ name: "hicortex", version: VERSION }, { capabilities: { tools: {} }, instructions: client.getInstructions() });
+    return client;
+}
+/**
+ * The downstream Server: a low-level Server over stdio advertising exactly
+ * what the daemon offers (tools). Ping is auto-answered by the Protocol
+ * base. #383: `instructions` is the DAEMON's initialize-result text,
+ * forwarded verbatim — undefined (pre-#383 daemon, memoryInstructions off,
+ * or the #501 slow path where the daemon has not answered yet) omits the
+ * field. `awaitClient` yields the upstream Client a tools request should
+ * use — already-resolved on the fast path, a readiness promise on the slow
+ * path, so tools requests queue until the server exists.
+ */
+function createBridgeServer(instructions, awaitClient) {
+    const server = new index_js_1.Server({ name: "hicortex", version: VERSION }, instructions !== undefined ? { capabilities: { tools: {} }, instructions } : { capabilities: { tools: {} } });
     // The proxy core — the SDK's documented proxy pattern. Forward the two
     // tools requests and pass extra.signal through so a downstream
     // notifications/cancelled aborts the upstream call (which emits the
     // correctly-id'd cancellation to the daemon). Nothing else is forwarded
     // request-wise: the daemon is tools-only and the base class answers ping.
-    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async (_request, extra) => (await client.listTools(undefined, { signal: extra.signal })));
-    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request, extra) => (await client.callTool(request.params, undefined, { signal: extra.signal })));
-    // Upstream → downstream notifications, best-effort: the daemon's tool-list
-    // changes or log messages reach the client; a closed far end must not kill
-    // the bridge from inside a notification handler.
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async (_request, extra) => {
+        const client = await awaitClient();
+        return (await client.listTools(undefined, { signal: extra.signal }));
+    });
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request, extra) => {
+        const client = await awaitClient();
+        return (await client.callTool(request.params, undefined, { signal: extra.signal }));
+    });
+    return server;
+}
+/** Upstream → downstream notifications, best-effort: the daemon's tool-list
+ *  changes or log messages reach the client; a closed far end must not kill
+ *  the bridge from inside a notification handler. */
+function forwardNotifications(client, server) {
     client.fallbackNotificationHandler = async (notification) => {
         try {
             await server.notification(notification);
@@ -285,29 +404,131 @@ async function runMcpStdio(options = {}) {
             // Best-effort by design.
         }
     };
-    // Lifecycle: whichever side ends first tears down the other. The `exiting`
-    // guard keeps our OWN client.close() (graceful path) from being read as an
-    // upstream loss.
+}
+/**
+ * Lifecycle: whichever side ends first tears down the other. The `exiting`
+ * guard keeps our OWN client.close() (graceful path) from being read as an
+ * upstream loss. The upstream attaches late on the #501 slow path, hence
+ * attachUpstream() instead of a constructor argument.
+ */
+function wireBridgeLifecycle(server) {
     let exiting = false;
+    let upstream;
     const shutdown = (code) => {
         if (exiting)
             return;
         exiting = true;
-        void Promise.allSettled([server.close(), client.close()]).then(() => process.exit(code));
+        const closing = [server.close()];
+        if (upstream)
+            closing.push(upstream.close());
+        void Promise.allSettled(closing).then(() => process.exit(code));
     };
     // Downstream closed (the MCP client went away) → close upstream → exit 0.
     server.onclose = () => shutdown(0);
-    // Upstream transport died → the bridge cannot serve anything → exit 1.
-    client.onclose = () => {
-        if (exiting)
-            return;
-        console.error("[hicortex] mcp: lost the connection to the Hicortex server");
-        shutdown(1);
-    };
     process.once("SIGINT", () => shutdown(0));
     process.once("SIGTERM", () => shutdown(0));
-    const downstream = options.downstream ?? new stdio_js_1.StdioServerTransport();
-    await server.connect(downstream);
-    // Diagnostics NEVER touch stdout (the MCP wire) — stderr only.
+    return {
+        shutdown,
+        attachUpstream(client) {
+            upstream = client;
+            // Upstream transport died → the bridge cannot serve anything → exit 1.
+            client.onclose = () => {
+                if (exiting)
+                    return;
+                console.error("[hicortex] mcp: lost the connection to the Hicortex server");
+                shutdown(1);
+            };
+        },
+    };
+}
+/**
+ * Run the stdio MCP bridge. Fast path (daemon reachable now): connect
+ * upstream first, then serve stdio with the daemon's forwarded instructions
+ * — exactly the pre-#501 sequence. Slow path (REMOTE target, transient
+ * network failure — the boot race): serve stdio IMMEDIATELY (design B,
+ * initialize answered at once) and retry the upstream connect with backoff
+ * for the retry window. Resolves once bridging is established; every setup
+ * failure throws for cli.ts to report on stderr and exit 1.
+ */
+async function runMcpStdio(options = {}) {
+    const target = resolveBridgeTarget(options.serverUrl);
+    const token = resolveBridgeToken(options.authToken);
+    const connect = options.connectUpstream ?? defaultConnectUpstream;
+    // ---- Fast path: the daemon answers now. ----
+    let firstFailure;
+    let upstream;
+    try {
+        await ensureDaemonReady(target, options);
+        upstream = await connect(target, token);
+    }
+    catch (err) {
+        if (classifyStartupFailure(err, target) !== "transient")
+            throw toStartupError(err, target);
+        firstFailure = err;
+    }
+    if (upstream) {
+        const server = createBridgeServer(upstream.getInstructions(), async () => upstream);
+        const lifecycle = wireBridgeLifecycle(server);
+        lifecycle.attachUpstream(upstream);
+        forwardNotifications(upstream, server);
+        await server.connect(options.downstream ?? new stdio_js_1.StdioServerTransport());
+        // Diagnostics NEVER touch stdout (the MCP wire) — stderr only.
+        console.error(`[hicortex] mcp: bridging stdio <-> ${target.url}/sse (target: ${target.source})`);
+        return;
+    }
+    // ---- Slow path (#501): remote + transient — answer initialize now,
+    // retry the upstream in the background, keep stdio alive throughout. ----
+    const windowMs = options.retryWindowMs ?? REMOTE_RETRY_WINDOW_MS;
+    const baseDelayMs = options.retryBaseDelayMs ?? REMOTE_RETRY_BASE_DELAY_MS;
+    const maxDelayMs = options.retryMaxDelayMs ?? REMOTE_RETRY_MAX_DELAY_MS;
+    let resolveReady;
+    let rejectReady;
+    const upstreamReady = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    // Mark handled: if the window expires before any tools request arrived,
+    // rejecting an un-awaited promise would crash the process as an unhandled
+    // rejection.
+    upstreamReady.catch(() => { });
+    const server = createBridgeServer(undefined, () => upstreamReady);
+    const lifecycle = wireBridgeLifecycle(server);
+    await server.connect(options.downstream ?? new stdio_js_1.StdioServerTransport());
     console.error(`[hicortex] mcp: bridging stdio <-> ${target.url}/sse (target: ${target.source})`);
+    console.error(`[hicortex] mcp: Hicortex server at ${target.url} unreachable at startup ` +
+        `(${summarizeStartupFailure(firstFailure)}) — retrying for up to ${Math.round(windowMs / 1000)}s ` +
+        `while the network comes up; the connection stays open and tools wait for the server`);
+    const deadline = Date.now() + windowMs;
+    let attempt = 0;
+    let lastFailure = firstFailure;
+    for (;;) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            rejectReady(new Error(remoteUnreachableMessage(target)));
+            throw new Error(remoteUnreachableMessage(target));
+        }
+        const delayMs = Math.min(nextRetryDelayMs(attempt, baseDelayMs, maxDelayMs), remainingMs);
+        console.error(`[hicortex] mcp: retrying ${target.url} in ${delayMs}ms ` +
+            `(attempt ${attempt + 1}, ${Math.ceil(remainingMs / 1000)}s of window left) after: ${summarizeStartupFailure(lastFailure)}`);
+        await sleep(delayMs);
+        attempt += 1;
+        try {
+            await ensureDaemonReady(target, { probeHealth: options.probeHealth });
+            const client = await connect(target, token);
+            // Established — from here the lifecycle is exactly the fast path's.
+            lifecycle.attachUpstream(client);
+            forwardNotifications(client, server);
+            resolveReady(client);
+            console.error(`[hicortex] mcp: server reachable after ${attempt} retry${attempt === 1 ? "" : "ies"} — serving tools`);
+            return;
+        }
+        catch (err) {
+            const kind = classifyStartupFailure(err, target);
+            if (kind === "auth")
+                throw toStartupError(err, target);
+            if (kind !== "transient")
+                throw err;
+            lastFailure = err;
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "description": "Persistent agent identity for AI agents \u2014 a hand-edited identity layer, nightly-distilled experience, and lessons injected every session, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, Pi, and opencode.",
   "main": "dist/index.js",
   "bin": {

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.gamaze-labs/hicortex",
   "title": "Hicortex \u2014 AI Fleet Memory",
   "description": "Shared fleet memory for AI agents: nightly self-correction, recall every prompt (supported agents).",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@gamaze/hicortex",
-      "version": "0.23.0",
+      "version": "0.23.1",
       "transport": {
         "type": "stdio",
         "command": "npx",