@mulmobridge/client 1.1.0 → 1.3.0

package/README.md

@@ -60,7 +60,25 @@ instead`). Whatever it ends up binding, it publishes to `<workspace>/.server-por
 1. `opts.apiUrl` — an explicit value always wins
 2. `$MULMOCLAUDE_API_URL`
 3. `http://127.0.0.1:<port>` from `<workspace>/.server-port`
-4. `http://localhost:3001`
+
+The fourth step — `http://localhost:3001` — depends on **who supplied the
+token**, and that is a security boundary rather than a quirk:
+
+- **Token from the workspace** (`.session-token`): no fallback. The workspace
+  owns both halves, so a token without a port is HALF a generation — the server
+  is mid-startup and has not bound yet. The client waits and joins when the port
+  appears. The window is not narrow: the server writes `.session-token` before
+  it binds, with sandbox setup (a Docker image build on a cold start) in
+  between, so it can last minutes (#3078).
+- **Token pinned by you** (`MULMOCLAUDE_AUTH_TOKEN`): the default still applies.
+  You supplied the credential and are pointing the bridge somewhere deliberately
+  — a container without the workspace mounted, say — so there is no freshly
+  minted secret to strand.
+
+`resolveApiUrl()` still returns `http://localhost:3001` as its last step, and
+`DEFAULT_API_URL` is still exported — they are for naming a default, not for
+connecting to one. `resolvePublishedApiUrl()` is the same order WITHOUT that
+step, and is what the client uses.
 
 The workspace itself is `$MULMOCLAUDE_WORKSPACE_PATH`, or `~/mulmoclaude` when
 that is unset — the same rule the server applies, and the same root the bearer
@@ -78,8 +96,17 @@ variable, or run the bridge from the directory holding the `.env`.
 | `readBridgeToken()` / `tokenFilePath()` | at call time |
 | `TOKEN_FILE_PATH` | at import time — a snapshot, kept for compatibility |
 
-The port is read once, when the client is created. A server that restarts onto a
-*different* port after that still needs the bridge restarted.
+### Following a restart
+
+The pair is re-read whenever the connection fails. If the server comes back as a
+different generation — a new token, a new port, or both — the client rebuilds its
+socket against it and your handlers are re-attached; nothing needs restarting
+(#3078). If the pair is unchanged, the socket is left alone so socket.io's own
+reconnection handles an ordinary outage.
+
+One case is outside this: a server-initiated disconnect (`io server disconnect`)
+is the one reason socket.io does not retry, so no connection failure follows it.
+The chat-service never issues one, so there is nothing to recover from today.
 
 ## Ecosystem
 

package/dist/apiUrl.d.ts

@@ -20,6 +20,19 @@ export declare function parsePublishedPort(raw: string | null): number | null;
  * is the silent misdirection this module exists to remove (#2981).
  */
 export declare function readPublishedApiUrl(): string | null;
+/**
+ * Everything except the default: an explicit argument, `MULMOCLAUDE_API_URL`,
+ * or the port the server published — and `null` when none of those says
+ * anything.
+ *
+ * The distinction matters exactly once, and it is a security boundary rather
+ * than a nicety. A caller RECONNECTING must be able to tell "the server has not
+ * published a port yet" from "here is a port", because the server clears
+ * `.server-port` at startup and writes the new token before publishing the new
+ * one (#3082). Collapsing the first into `DEFAULT_API_URL` there would take a
+ * freshly minted bearer token to whatever holds 3001 (Codex, #3078).
+ */
+export declare function resolvePublishedApiUrl(explicit?: string): string | null;
 /**
  * Resolution order: explicit argument → `MULMOCLAUDE_API_URL` → the port the
  * server published → `DEFAULT_API_URL`.
@@ -28,5 +41,9 @@ export declare function readPublishedApiUrl(): string | null;
  * An EMPTY value falls through instead of being used verbatim, matching how
  * `readBridgeToken` treats an empty `MULMOCLAUDE_AUTH_TOKEN` — an empty
  * string reached `io("")` before this.
+ *
+ * The default at the end is a STARTUP affordance: a bridge run against a
+ * machine where no server has published anything still tries the conventional
+ * port. Do not reuse it for reconnection — see `resolvePublishedApiUrl`.
  */
 export declare function resolveApiUrl(explicit?: string): string;

package/dist/apiUrl.js

@@ -12,9 +12,10 @@
 // (`wait-for-backend`); both were fixed by reading the published port.
 //
 // A leftover `.server-port` cannot mislead here the way it can mislead
-// `yarn dev`: the file is not removed on shutdown, but the server REWRITES it
-// on every startup, so a running server's entry is always current — and with
-// no server running, the old hardcoded 3001 was just as dead.
+// `yarn dev`: the server REWRITES it on every startup, so a running server's
+// entry is always current — and with no server running, the old hardcoded 3001
+// was just as dead. Since #3082 a graceful shutdown removes it too, so the
+// leftover case is now a crash rather than the ordinary stop.
 import { readSidecarFile, SIDECAR_FILES } from "./workspace.js";
 /** Used only when nothing has been published and nothing was configured. */
 export const DEFAULT_API_URL = "http://localhost:3001";
@@ -51,6 +52,26 @@ export function readPublishedApiUrl() {
     const port = parsePublishedPort(readSidecarFile(SIDECAR_FILES.port));
     return port === null ? null : `http://127.0.0.1:${port}`;
 }
+/**
+ * Everything except the default: an explicit argument, `MULMOCLAUDE_API_URL`,
+ * or the port the server published — and `null` when none of those says
+ * anything.
+ *
+ * The distinction matters exactly once, and it is a security boundary rather
+ * than a nicety. A caller RECONNECTING must be able to tell "the server has not
+ * published a port yet" from "here is a port", because the server clears
+ * `.server-port` at startup and writes the new token before publishing the new
+ * one (#3082). Collapsing the first into `DEFAULT_API_URL` there would take a
+ * freshly minted bearer token to whatever holds 3001 (Codex, #3078).
+ */
+export function resolvePublishedApiUrl(explicit) {
+    if (typeof explicit === "string" && explicit.length > 0)
+        return explicit;
+    const fromEnv = process.env.MULMOCLAUDE_API_URL;
+    if (typeof fromEnv === "string" && fromEnv.length > 0)
+        return fromEnv;
+    return readPublishedApiUrl();
+}
 /**
  * Resolution order: explicit argument → `MULMOCLAUDE_API_URL` → the port the
  * server published → `DEFAULT_API_URL`.
@@ -59,12 +80,11 @@ export function readPublishedApiUrl() {
  * An EMPTY value falls through instead of being used verbatim, matching how
  * `readBridgeToken` treats an empty `MULMOCLAUDE_AUTH_TOKEN` — an empty
  * string reached `io("")` before this.
+ *
+ * The default at the end is a STARTUP affordance: a bridge run against a
+ * machine where no server has published anything still tries the conventional
+ * port. Do not reuse it for reconnection — see `resolvePublishedApiUrl`.
  */
 export function resolveApiUrl(explicit) {
-    if (typeof explicit === "string" && explicit.length > 0)
-        return explicit;
-    const fromEnv = process.env.MULMOCLAUDE_API_URL;
-    if (typeof fromEnv === "string" && fromEnv.length > 0)
-        return fromEnv;
-    return readPublishedApiUrl() ?? DEFAULT_API_URL;
+    return resolvePublishedApiUrl(explicit) ?? DEFAULT_API_URL;
 }

package/dist/client.d.ts

@@ -43,8 +43,10 @@ export interface BridgeClient {
     onDisconnect(handler: (reason: string) => void): void;
     /** Explicit shutdown. */
     close(): void;
-    /** Escape hatch — raw socket for anything the helpers don't cover. */
-    socket: Socket;
+    /** Escape hatch — the socket in use NOW. Read it per use rather than
+     *  caching it: the client replaces the socket when the server comes back
+     *  as a different generation (#3078). */
+    readonly socket: Socket;
 }
 /**
  * Resolve the bearer token from the workspace / env var, exit with

package/dist/client.js

@@ -15,7 +15,8 @@ import { io } from "socket.io-client";
 import { CHAT_SOCKET_EVENTS, CHAT_SOCKET_PATH } from "@mulmobridge/protocol";
 import { readBridgeToken, tokenFilePath } from "./token.js";
 import { readBridgeEnvOptions } from "./options.js";
-import { resolveApiUrl } from "./apiUrl.js";
+import { DEFAULT_API_URL, resolvePublishedApiUrl } from "./apiUrl.js";
+import { backoffMs, credentialsChanged } from "./supervisor.js";
 // 6 min > the server's REPLY_TIMEOUT_MS (5 min) so the server's
 // timeout surfaces as a reply, not a client-side cancellation.
 const REPLY_TIMEOUT_MS = 6 * 60 * 1000;
@@ -39,70 +40,227 @@ export function requireBearerToken() {
         `same value the server is using.\n`);
     return process.exit(1);
 }
+const emptySubscriptions = () => ({ push: [], textChunk: [], connect: [], disconnect: [] });
+/** The handshake bag. `options` is omitted when empty so a server too old to
+ *  know the field never sees an empty object on the wire. */
+function buildAuth(transportId, token, options) {
+    const auth = { transportId, token };
+    if (Object.keys(options).length > 0)
+        auth.options = options;
+    return auth;
+}
+function attach(socket, subscriptions) {
+    subscriptions.push.forEach((handler) => socket.on(CHAT_SOCKET_EVENTS.push, handler));
+    subscriptions.textChunk.forEach((handler) => socket.on(CHAT_SOCKET_EVENTS.textChunk, (event) => {
+        handler(event.text);
+    }));
+    subscriptions.connect.forEach((handler) => socket.on("connect", handler));
+    subscriptions.disconnect.forEach((handler) => socket.on("disconnect", handler));
+}
 export function createBridgeClient(opts) {
     // Token BEFORE port. A restart rewrites both files and nothing marks them as
     // one generation, so a bridge starting mid-restart can read a torn pair in
     // either order. What the order decides is WHICH tear it gets. Port first
     // yields a NEW token with an OLD port — a fresh credential sent to the port
-    // the server has just left, retried in silence because the socket's URL is
-    // fixed at construction. Token first mostly yields the opposite, an OLD token
-    // with a NEW port, which the right server answers `invalid token` and the
-    // connect handler explains; the dangerous pairing survives only in the narrow
-    // window where BOTH reads fall between the token write and the port publish.
-    // Closing it needs a shared generation marker on the sidecars (Codex, #3082).
+    // the server has just left. Token first mostly yields the opposite, an OLD
+    // token with a NEW port, which the right server answers `invalid token`; the
+    // dangerous pairing survives only in the narrow window where BOTH reads fall
+    // between the token write and the port publish (Codex, #3082).
     const token = requireBearerToken();
-    const apiUrl = resolveApiUrl(opts.apiUrl);
     // `opts.options === undefined` → scrape env automatically.
     // `opts.options === {}` → opt out of the scrape explicitly.
     const options = opts.options ?? readBridgeEnvOptions(opts.transportId, process.env);
-    // Only include the `options` key in the handshake when there's
-    // something to send — keeps old servers unaware of the field from
-    // ever seeing an empty object on the wire.
-    const auth = { transportId: opts.transportId, token };
-    if (Object.keys(options).length > 0)
-        auth.options = options;
-    const socket = io(apiUrl, {
-        path: CHAT_SOCKET_PATH,
-        auth,
-        transports: ["websocket"],
-    });
-    installDefaultLogging(socket);
+    const subscriptions = emptySubscriptions();
+    const pending = new Set();
+    const published = resolvePublishedApiUrl(opts.apiUrl);
+    // Who supplied the token decides whether the startup default is usable.
+    //
+    // From the WORKSPACE: the workspace is the source of truth for both halves, so
+    // a token without a port is half a generation — the server is mid-startup and
+    // has not bound yet. Connecting to the default there hands a freshly minted
+    // credential to whoever holds 3001, and that window is minutes wide on a cold
+    // start (#3078). Wait instead.
+    //
+    // From `MULMOCLAUDE_AUTH_TOKEN`: the caller pinned a credential themselves and
+    // is pointing this bridge somewhere deliberately — a container without the
+    // workspace mounted, a server too old to publish. There is no fresh secret to
+    // strand, and refusing the default would break a setup that worked (Codex,
+    // round-5 checkpoint). They keep the documented fallback.
+    const tokenIsPinned = typeof process.env.MULMOCLAUDE_AUTH_TOKEN === "string" && process.env.MULMOCLAUDE_AUTH_TOKEN.length > 0;
+    const startAddress = published ?? (tokenIsPinned ? DEFAULT_API_URL : null);
+    // `DEFAULT_API_URL` is a placeholder when we are waiting, never a destination:
+    // the idle socket is built with `autoConnect: false` and is replaced before it
+    // ever handshakes, so the token cannot reach it.
+    const startedAt = { apiUrl: startAddress ?? DEFAULT_API_URL, token };
+    /** The pair as the workspace has it NOW, or null while the server is mid-restart.
+     *
+     *  BOTH halves have to be present. The startup default is deliberately not
+     *  consulted here: the server clears `.server-port` before writing the new
+     *  token (#3082), so "token, no port" is a real and frequent state, and
+     *  resolving it to `http://localhost:3001` would carry a freshly minted
+     *  bearer token to whatever holds that port (Codex, #3078). Half a generation
+     *  is not a generation. */
+    const reread = () => {
+        const freshToken = readBridgeToken();
+        const freshApiUrl = resolvePublishedApiUrl(opts.apiUrl);
+        if (freshToken === null || freshApiUrl === null)
+            return null;
+        return { apiUrl: freshApiUrl, token: freshToken };
+    };
+    const open = (credentials) => {
+        // Say where we are going, every time, from the SHARED client — so the
+        // answer exists for all 25 bridges and not just the one that happened to
+        // print a banner. `error-recovery.md` leans on this line to separate "an
+        // old build hardcoding 3001" from "the address is right": a diagnostic the
+        // help describes has to be one the code actually emits (#3085).
+        console.error(`Connecting to ${credentials.apiUrl}`);
+        const socket = io(credentials.apiUrl, {
+            path: CHAT_SOCKET_PATH,
+            auth: buildAuth(opts.transportId, credentials.token, options),
+            transports: ["websocket"],
+        });
+        installDefaultLogging(socket);
+        socket.on("connect", () => {
+            live.attempt = 0;
+        });
+        socket.on("connect_error", scheduleReresolve);
+        attach(socket, subscriptions);
+        return socket;
+    };
+    /**
+     * A socket that will never connect, for the case where the token is readable
+     * and the port is not.
+     *
+     * That window is not a race to lose sleep over — it is minutes wide on a cold
+     * start, because `setupSandbox()` (which can build a Docker image) runs
+     * between the server writing the token and binding its port. Connecting to
+     * `DEFAULT_API_URL` there would hand a freshly minted bearer token to whatever
+     * holds 3001 (Codex, #3078). Waiting is the only safe answer, and the
+     * supervisor is already the thing that waits.
+     */
+    const openIdle = () => io(DEFAULT_API_URL, { path: CHAT_SOCKET_PATH, transports: ["websocket"], autoConnect: false });
+    /** Everything the supervisor mutates, boxed so every binding stays `const`.
+     *  Built after `open` / `openIdle` because it holds the socket they make;
+     *  they only READ it from callbacks, which cannot fire before it exists. */
+    const live = {
+        socket: startAddress === null ? openIdle() : open(startedAt),
+        current: startedAt,
+        attempt: 0,
+        retry: null,
+        closed: false,
+    };
+    if (startAddress === null) {
+        console.error("\nThe server has not published a port yet — waiting for it rather than guessing.\n");
+        scheduleReresolve();
+    }
+    /** Replace the socket only when the pair actually moved — a server that is
+     *  merely down must keep socket.io's own reconnection, not a worse copy. */
+    function reresolve() {
+        live.retry = null;
+        if (live.closed)
+            return;
+        const fresh = reread();
+        live.attempt += 1;
+        if (!credentialsChanged(live.current, fresh) || fresh === null) {
+            // Keep waiting. A LIVE socket would re-arm this itself through its next
+            // `connect_error`, but the idle socket built when nothing was published
+            // never connects and so never emits one — without this the wait is
+            // single-shot and a bridge started before its server would hang forever.
+            // The `retry !== null` guard in `scheduleReresolve` stops the two paths
+            // from doubling up, and the backoff caps the cost of an idle wait.
+            if (!live.socket.connected)
+                scheduleReresolve();
+            return;
+        }
+        console.error(`\nServer moved: reconnecting to ${fresh.apiUrl}.\n`);
+        abandon(pending, "the server restarted before this was acknowledged — resend");
+        live.socket.removeAllListeners();
+        live.socket.close();
+        live.current = fresh;
+        live.attempt = 0;
+        live.socket = open(live.current);
+    }
+    function scheduleReresolve() {
+        if (live.closed || live.retry !== null)
+            return;
+        // NOT `unref()`ed. A bridge waiting for its server to publish a port is
+        // doing work, and while it waits the idle socket (`autoConnect: false`)
+        // holds nothing — so an unref'd timer let the process exit immediately
+        // after printing that it would wait. `close()` clears this, so holding the
+        // loop open costs nothing on the way out (Codex, #3078).
+        live.retry = setTimeout(reresolve, backoffMs(live.attempt));
+    }
     return {
-        send: (externalChatId, text, attachments) => sendMessage(socket, externalChatId, text, attachments),
+        send: (externalChatId, text, attachments) => sendMessage(live.socket, pending, externalChatId, text, attachments),
         onPush: (handler) => {
-            socket.on(CHAT_SOCKET_EVENTS.push, handler);
+            subscriptions.push.push(handler);
+            live.socket.on(CHAT_SOCKET_EVENTS.push, handler);
         },
         onTextChunk: (handler) => {
-            socket.on(CHAT_SOCKET_EVENTS.textChunk, (event) => {
+            subscriptions.textChunk.push(handler);
+            live.socket.on(CHAT_SOCKET_EVENTS.textChunk, (event) => {
                 handler(event.text);
             });
         },
         onConnect: (handler) => {
-            socket.on("connect", handler);
+            subscriptions.connect.push(handler);
+            live.socket.on("connect", handler);
         },
         onDisconnect: (handler) => {
-            socket.on("disconnect", handler);
+            subscriptions.disconnect.push(handler);
+            live.socket.on("disconnect", handler);
         },
         close: () => {
-            socket.disconnect();
+            live.closed = true;
+            if (live.retry !== null)
+                clearTimeout(live.retry);
+            abandon(pending, "the bridge closed before this was acknowledged");
+            live.socket.disconnect();
+        },
+        get socket() {
+            return live.socket;
         },
-        socket,
     };
 }
-function sendMessage(socket, externalChatId, text, attachments) {
+function sendMessage(socket, pending, externalChatId, text, attachments) {
     const payload = { externalChatId, text };
     if (attachments && attachments.length > 0)
         payload.attachments = attachments;
     return new Promise((resolve) => {
-        socket.timeout(REPLY_TIMEOUT_MS).emit(CHAT_SOCKET_EVENTS.message, payload, (err, ack) => {
-            if (err) {
-                resolve({ ok: false, error: `timeout: ${err.message}` });
+        // The timeout is OURS, not `socket.timeout(...)`'s, because it has to be
+        // CANCELLABLE. socket.io arms its ack timer at emit time and keeps it armed
+        // on a socket that is closed underneath it, so a send abandoned by a rebuild
+        // left a six-minute timer behind per send — measured: the test process exited
+        // at 6:00.45, exactly REPLY_TIMEOUT_MS, long after every assertion had passed
+        // (Codex, #3078). `settle` clears it, so `abandon` clears it too.
+        const state = {};
+        const settle = (ack) => {
+            if (!pending.delete(settle))
                 return;
-            }
-            resolve(ack ?? { ok: false, error: "no ack from server" });
+            clearTimeout(state.timer);
+            resolve(ack);
+        };
+        state.timer = setTimeout(() => settle({ ok: false, error: `timeout: no ack within ${REPLY_TIMEOUT_MS}ms` }), REPLY_TIMEOUT_MS);
+        pending.add(settle);
+        socket.emit(CHAT_SOCKET_EVENTS.message, payload, (ack) => {
+            settle(ack ?? { ok: false, error: "no ack from server" });
         });
     });
 }
+/**
+ * Fail every unacknowledged send, because the socket carrying them is going.
+ *
+ * socket.io settles an IN-FLIGHT ack immediately when its socket closes, but a
+ * send issued while the socket was already disconnected is queued for a
+ * reconnection that will never happen here — the socket is being replaced, not
+ * reconnected — so its callback would sit for the full 6-minute ack timeout
+ * (measured, Codex). The bridge's user would wait six minutes for a message the
+ * client already knows it cannot deliver.
+ */
+function abandon(pending, reason) {
+    Array.from(pending).forEach((settle) => settle({ ok: false, error: reason }));
+    pending.clear();
+}
 function installDefaultLogging(socket) {
     socket.on("connect", () => {
         console.log(`Connected (${socket.id}).`);
@@ -117,9 +275,11 @@ function installDefaultLogging(socket) {
         // right after the server bounces. Tell the user instead of
         // spinning silently.
         if (msg === "invalid token" || msg === "server auth not ready") {
-            console.error("\nConnect error: bearer token rejected. The server likely\n" +
-                "restarted since this bridge started — re-run the bridge to\n" +
-                "pick up the new token.\n");
+            // No longer "re-run the bridge": the client re-reads the sidecar pair
+            // after every connect failure and rebuilds the socket when the server
+            // comes back as a different generation (#3078 A-3). This says what is
+            // happening so a run that never recovers is still diagnosable.
+            console.error("\nConnect error: bearer token rejected — waiting for the server to publish a new one.\n");
             return;
         }
         console.error(`\nConnect error: ${msg}`);

package/dist/inProcess.d.ts

@@ -0,0 +1,34 @@
+import type { Attachment, BridgeOptions } from "@mulmobridge/protocol";
+import type { BridgeClient, PushEvent } from "./client.js";
+/** Shape of `chat-service`'s `RelayResult`, restated so this package does not
+ *  import the server package. Kept structural on purpose: the host passes its
+ *  own function and TypeScript checks the two agree. */
+export type InProcessRelayResult = {
+    kind: "ok";
+    reply: string;
+} | {
+    kind: "error";
+    status: number;
+    message: string;
+};
+export type InProcessRelayFn = (params: {
+    transportId: string;
+    externalChatId: string;
+    text: string;
+    attachments?: Attachment[] | undefined;
+    bridgeOptions?: Readonly<Record<string, string | number | boolean>> | undefined;
+    onChunk?: ((text: string) => void) | undefined;
+}) => Promise<InProcessRelayResult>;
+/** Registers this bridge to receive server → bridge pushes. Returns the
+ *  unregister function, which `close()` calls. */
+export type RegisterInProcessPush = (transportId: string, handler: (event: PushEvent) => void) => () => void;
+export interface InProcessBridgeClientOptions {
+    transportId: string;
+    relay: InProcessRelayFn;
+    registerPush: RegisterInProcessPush;
+    /** Forwarded to the host's `startChat` exactly as the handshake bag is on the
+     *  socket path. Defaults to `{}` — an in-process bridge is configured by the
+     *  host, so there is no env to scrape on its behalf. */
+    options?: BridgeOptions;
+}
+export declare function createInProcessBridgeClient(opts: InProcessBridgeClientOptions): BridgeClient;

package/dist/inProcess.js

@@ -0,0 +1,77 @@
+// A `BridgeClient` that talks to a chat service living in the SAME process,
+// with no socket, no port and no bearer token (#3080).
+//
+// `packages/chat-service/src/relay.ts` calls itself "the shared core of the
+// bridge chat flow ... HTTP (router) and socket.io transports both call the
+// `RelayFn` this factory returns". This is the third caller of that same core,
+// so nothing new is introduced server-side — only a different way in.
+//
+// The relay and the push registration arrive as callbacks rather than imports:
+// `@mulmobridge/client` sits BELOW the server in the dependency direction and
+// must not import `@mulmoclaude/chat-service`.
+export function createInProcessBridgeClient(opts) {
+    const bridgeOptions = opts.options ?? {};
+    const pushHandlers = [];
+    const chunkHandlers = [];
+    let unregisterPush = null;
+    let closed = false;
+    const deliverPush = (event) => {
+        for (const handler of pushHandlers) {
+            try {
+                handler(event);
+            }
+            catch (err) {
+                // Per subscriber, so one bad handler does not stop the ones after it
+                // from seeing the push — and does not reach the server's stack.
+                console.error(`[${opts.transportId}] push handler threw: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    };
+    const send = async (externalChatId, text, attachments) => {
+        if (closed)
+            return { ok: false, error: "bridge client is closed" };
+        const result = await opts.relay({
+            transportId: opts.transportId,
+            externalChatId,
+            text,
+            attachments,
+            bridgeOptions,
+            // Only subscribe the relay to chunks when someone is listening, so the
+            // serialiser is not paying for a stream nobody reads.
+            onChunk: chunkHandlers.length > 0 ? (chunk) => chunkHandlers.forEach((handler) => handler(chunk)) : undefined,
+        });
+        return result.kind === "ok" ? { ok: true, reply: result.reply } : { ok: false, error: result.message, status: result.status };
+    };
+    return {
+        send,
+        onPush(handler) {
+            pushHandlers.push(handler);
+            // Registered on the FIRST subscriber so a bridge that never listens costs
+            // the host nothing, and only once however many handlers are added.
+            unregisterPush ??= opts.registerPush(opts.transportId, deliverPush);
+        },
+        onTextChunk(handler) {
+            chunkHandlers.push(handler);
+        },
+        // There is no socket, so there is no connection to gain or lose. An
+        // in-process bridge is connected from the moment it is constructed.
+        onConnect(handler) {
+            handler();
+        },
+        onDisconnect() { },
+        close() {
+            closed = true;
+            unregisterPush?.();
+            unregisterPush = null;
+            pushHandlers.length = 0;
+            chunkHandlers.length = 0;
+        },
+        get socket() {
+            // Deliberately loud rather than null. Measured across all 25 bridges: none
+            // reads `.socket`, so the first caller to do so is writing new code against
+            // an assumption that does not hold here, and a null would surface as an
+            // unrelated TypeError somewhere downstream.
+            throw new Error("in-process bridge client has no socket — see packages/client/src/inProcess.ts");
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { createBridgeClient, requireBearerToken, type MessageAck, type PushEvent, type BridgeClientOptions, type BridgeClient } from "./client.js";
 export { readBridgeToken, tokenFilePath, TOKEN_FILE_PATH } from "./token.js";
-export { resolveApiUrl } from "./apiUrl.js";
+export { resolveApiUrl, resolvePublishedApiUrl } from "./apiUrl.js";
 export { readBridgeEnvOptions } from "./options.js";
 export { chunkText } from "./text.js";
 export { frameText } from "./frame.js";
 export { asJsonRecord, fetchJsonRecord, type JsonRecord } from "./http.js";
 export { formatAckReply } from "./reply.js";
 export { mimeFromExtension, isImageMime, isPdfMime, isSupportedAttachmentMime, isNativeAttachmentMime, parseDataUrl, buildDataUrl, type ParsedDataUrl, } from "./mime.js";
+export { installProcessGuards, SHUTDOWN_GRACE_MS, type ProcessGuardOptions, type ShutdownTask } from "./processGuards.js";
+export { createInProcessBridgeClient, type InProcessBridgeClientOptions, type InProcessRelayFn, type InProcessRelayResult, type RegisterInProcessPush, } from "./inProcess.js";

package/dist/index.js

@@ -1,10 +1,12 @@
 // @mulmobridge/client — shared socket.io client for all MulmoBridge bridges.
 export { createBridgeClient, requireBearerToken } from "./client.js";
 export { readBridgeToken, tokenFilePath, TOKEN_FILE_PATH } from "./token.js";
-export { resolveApiUrl } from "./apiUrl.js";
+export { resolveApiUrl, resolvePublishedApiUrl } from "./apiUrl.js";
 export { readBridgeEnvOptions } from "./options.js";
 export { chunkText } from "./text.js";
 export { frameText } from "./frame.js";
 export { asJsonRecord, fetchJsonRecord } from "./http.js";
 export { formatAckReply } from "./reply.js";
 export { mimeFromExtension, isImageMime, isPdfMime, isSupportedAttachmentMime, isNativeAttachmentMime, parseDataUrl, buildDataUrl, } from "./mime.js";
+export { installProcessGuards, SHUTDOWN_GRACE_MS } from "./processGuards.js";
+export { createInProcessBridgeClient, } from "./inProcess.js";

package/dist/processGuards.d.ts

@@ -0,0 +1,16 @@
+/** Release resources and stop accepting work. May be async. */
+export type ShutdownTask = () => void | Promise<void>;
+export interface ProcessGuardOptions {
+    /** Transport id, used as the log prefix so the line says WHICH bridge died. */
+    name: string;
+    /** Runs once, on the first signal, before the process exits. */
+    onShutdown?: ShutdownTask;
+    /** Test seam; production ends the process. */
+    exit?: (code: number) => void;
+    /** How long a shutdown task may take before the process leaves anyway.
+     *  Defaults to `SHUTDOWN_GRACE_MS`; tests shorten it. */
+    graceMs?: number;
+}
+/** A shutdown task that hangs must not hold the terminal hostage. */
+export declare const SHUTDOWN_GRACE_MS = 5000;
+export declare function installProcessGuards(opts: ProcessGuardOptions): void;

package/dist/processGuards.js

@@ -0,0 +1,84 @@
+// Process-level guards for a bridge (#3084).
+//
+// A bridge is a long-lived process a user starts in a terminal and leaves
+// running, and none of the 25 had any of these:
+//
+//   - `unhandledRejection` — Node 15+ terminates the process, so ONE missed
+//     `await` anywhere took the bot down leaving a bare stack trace that names
+//     no bridge. From the outside that is "the bot just stopped answering".
+//   - `uncaughtException` — the same, for a throw off the call stack.
+//   - `SIGINT` / `SIGTERM` — Ctrl-C killed the process mid-flight, dropping a
+//     webhook that was being handled or updates already fetched and unprocessed.
+//
+// Installing a handler for the first two SUPPRESSES Node's own exit, so both
+// re-exit explicitly: the aim is a legible message, not a survivable error. No
+// restart logic lives here — a supervisor belongs to whatever started the
+// bridge (#3080), and two of them would fight.
+import { errorMessage } from "@mulmoclaude/common";
+/** A shutdown task that hangs must not hold the terminal hostage. */
+export const SHUTDOWN_GRACE_MS = 5_000;
+export function installProcessGuards(opts) {
+    const exit = opts.exit ?? ((code) => process.exit(code));
+    installCrashGuards(opts.name, exit);
+    installSignalGuards(opts, exit);
+}
+function installCrashGuards(name, exit) {
+    process.on("unhandledRejection", (reason) => {
+        console.error(`[${name}] unhandled rejection — exiting: ${errorMessage(reason)}`);
+        if (reason instanceof Error && reason.stack !== undefined)
+            console.error(reason.stack);
+        exit(1);
+    });
+    process.on("uncaughtException", (err) => {
+        console.error(`[${name}] uncaught exception — exiting: ${errorMessage(err)}`);
+        if (err instanceof Error && err.stack !== undefined)
+            console.error(err.stack);
+        exit(1);
+    });
+}
+function installSignalGuards(opts, exit) {
+    let shuttingDown = false;
+    const handle = (signal) => {
+        if (shuttingDown) {
+            // Someone pressed Ctrl-C twice because the first one looked stuck. Honour
+            // the impatience rather than waiting out the grace period.
+            console.error(`[${opts.name}] ${signal} again — exiting now`);
+            exit(1);
+            return;
+        }
+        shuttingDown = true;
+        console.log(`[${opts.name}] ${signal} — shutting down`);
+        void runShutdown(opts.name, opts.onShutdown, opts.graceMs ?? SHUTDOWN_GRACE_MS).then(() => exit(0));
+    };
+    ["SIGINT", "SIGTERM"].forEach((signal) => process.on(signal, () => handle(signal)));
+}
+async function runShutdown(name, task, graceMs) {
+    if (task === undefined)
+        return;
+    // The deadline timer stays REFERENCED, and is cleared once the race settles.
+    // An `unref`ed one looks tidier and silently breaks the guarantee: a shutdown
+    // task that hangs after the last other handle closed lets Node empty its loop
+    // and exit before the timer fires, so neither the message below nor the
+    // `exit(0)` that follows this call ever runs. Keeping it referenced is what
+    // holds the process open for exactly as long as the grace period.
+    let deadline;
+    try {
+        await Promise.race([
+            Promise.resolve(task()),
+            new Promise((resolve) => {
+                deadline = setTimeout(() => {
+                    console.error(`[${name}] shutdown did not finish within ${graceMs}ms — exiting anyway`);
+                    resolve();
+                }, graceMs);
+            }),
+        ]);
+    }
+    catch (err) {
+        console.error(`[${name}] shutdown task failed: ${errorMessage(err)}`);
+    }
+    finally {
+        // A fast shutdown must not wait out the rest of the grace period.
+        if (deadline !== undefined)
+            clearTimeout(deadline);
+    }
+}

package/dist/supervisor.d.ts

@@ -0,0 +1,16 @@
+/** The pair a socket was built from. */
+export interface Credentials {
+    apiUrl: string;
+    token: string;
+}
+/** Did the server come back as a different generation? */
+export declare function credentialsChanged(current: Credentials, fresh: Credentials | null): boolean;
+/**
+ * Exponential backoff, capped.
+ *
+ * A restart takes seconds, so the first few re-reads should be quick; a server
+ * that is down for the afternoon should not have its workspace stat-ed twice a
+ * second until someone notices. Pure, so the schedule is testable without a
+ * clock — `attempt` is 0-based and anything below 0 is treated as the first try.
+ */
+export declare function backoffMs(attempt: number): number;

package/dist/supervisor.js

@@ -0,0 +1,45 @@
+// Following the server across a restart (#3078 A-3).
+//
+// Both sidecars are rewritten when the server restarts, and the socket's URL is
+// fixed when the socket is constructed — so a bridge that reads them once is
+// pinned to the generation it started against. Before this, the client detected
+// the resulting `invalid token` and told the user to re-run the bridge, which is
+// where "I restart the server and then restart every bridge by hand" came from.
+//
+// `invalid token` is not a sufficient trigger. It only arrives when the bridge
+// still REACHES the server, i.e. when the port happened not to change. When the
+// port did change, nothing answers and the error is a refused connection, so a
+// supervisor watching only for auth failures would sit on a dead port forever.
+// Every connect failure therefore re-resolves.
+//
+// What it deliberately does NOT do is rebuild on every failure. A server that is
+// simply down produces an unbroken stream of refusals, and tearing the socket
+// down for each one would replace socket.io's own reconnection with a worse copy
+// of it. The pair changing is the signal; everything else is left alone.
+//
+// That leaning on socket.io has one edge: a server-initiated disconnect
+// (`io server disconnect`) is the one reason socket.io does NOT retry, so no
+// connect failure follows it and nothing here would fire. It is not handled
+// because the chat-service never issues one — it only logs disconnects — and a
+// recovery path for an event nothing produces is a path nothing tests. If that
+// changes, this is where it would go.
+/** Did the server come back as a different generation? */
+export function credentialsChanged(current, fresh) {
+    if (fresh === null)
+        return false;
+    return fresh.apiUrl !== current.apiUrl || fresh.token !== current.token;
+}
+const FIRST_RETRY_MS = 500;
+const MAX_RETRY_MS = 30_000;
+/**
+ * Exponential backoff, capped.
+ *
+ * A restart takes seconds, so the first few re-reads should be quick; a server
+ * that is down for the afternoon should not have its workspace stat-ed twice a
+ * second until someone notices. Pure, so the schedule is testable without a
+ * clock — `attempt` is 0-based and anything below 0 is treated as the first try.
+ */
+export function backoffMs(attempt) {
+    const step = attempt > 0 ? attempt : 0;
+    return Math.min(FIRST_RETRY_MS * 2 ** step, MAX_RETRY_MS);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/client",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Socket.io client library for MulmoBridge — shared by all bridge implementations",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,11 +46,11 @@
   "author": "Receptron Team",
   "dependencies": {
     "@mulmobridge/protocol": "^1.0.1",
-    "@mulmoclaude/common": "^1.2.0",
+    "@mulmoclaude/common": "^1.3.0",
     "socket.io-client": "^4.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.5.1",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/client#readme",