@mulmobridge/client 1.0.2 → 1.2.0

package/README.md

@@ -17,7 +17,8 @@ yarn add @mulmobridge/client
 | `createBridgeClient(opts)` | Create a connected socket.io client with auth |
 | `requireBearerToken()` | Read the bearer token or exit with a helpful message |
 | `readBridgeToken()` | Read the bearer token (returns `null` if absent) |
-| `TOKEN_FILE_PATH` | Path to `~/mulmoclaude/.session-token` |
+| `TOKEN_FILE_PATH` | Path to the workspace's `.session-token` |
+| `resolveApiUrl(explicit?)` | Resolve the server URL a bridge should connect to |
 | `mimeFromExtension(ext)` | Map file extension to MIME type |
 | `isImageMime(mime)` | Check if MIME is an image type |
 | `isPdfMime(mime)` | Check if MIME is PDF |
@@ -47,6 +48,66 @@ client.onPush((ev) => {
 });
 ```
 
+## Which server it connects to
+
+The MulmoClaude server is **not pinned to port 3001**. It honours `PORT`, and an
+implicit default that is already busy walks forward (`Port 3001 busy → using 3002
+instead`). Whatever it ends up binding, it publishes to `<workspace>/.server-port`
+— the file every out-of-process reader uses to find it.
+
+`createBridgeClient()` resolves the address in this order:
+
+1. `opts.apiUrl` — an explicit value always wins
+2. `$MULMOCLAUDE_API_URL`
+3. `http://127.0.0.1:<port>` from `<workspace>/.server-port`
+
+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
+token is read from.
+
+Only `process.env` is consulted. A `.env` file reaches this library through the
+bridge's own `import "dotenv/config"`, which resolves `.env` against the
+process's **current working directory** — so a bridge launched from somewhere
+else does not see a `MULMOCLAUDE_WORKSPACE_PATH` that lives only in the repo's
+`.env`, exactly as it would not see `MULMOCLAUDE_AUTH_TOKEN` there. Export the
+variable, or run the bridge from the directory holding the `.env`.
+
+| Export | Resolves |
+|---|---|
+| `readBridgeToken()` / `tokenFilePath()` | at call time |
+| `TOKEN_FILE_PATH` | at import time — a snapshot, kept for compatibility |
+
+### 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
 
 Part of the [`@mulmobridge/*`](https://www.npmjs.com/~mulmobridge) package family.

package/dist/apiUrl.d.ts

@@ -0,0 +1,49 @@
+/** Used only when nothing has been published and nothing was configured. */
+export declare const DEFAULT_API_URL = "http://localhost:3001";
+/**
+ * The published port, or `null` for anything that is not one.
+ *
+ * Decimal digits only. The writer is `formatServerPort()`, which emits
+ * `${port}\n` and nothing else, so there is no lenient shape worth
+ * accepting — while `Number.parseInt` would read `3002abc` as 3002 and send
+ * the bridge to a port a corrupted file never meant.
+ */
+export declare function parsePublishedPort(raw: string | null): number | null;
+/**
+ * The origin the running server published, or `null` if it published none.
+ *
+ * `127.0.0.1` rather than `localhost`: the server binds the IPv4 loopback
+ * explicitly (`app.listen(port, "127.0.0.1")`), while `localhost` resolves
+ * to `::1` first on a dual-stack host. Usually that still works — nothing
+ * holds `::1`, the connection is refused and Node falls back to IPv4 — but
+ * when something IS there the client reaches it and never falls back, which
+ * 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`.
+ *
+ * An explicit value still wins, so nothing that already sets one changes.
+ * 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

@@ -0,0 +1,90 @@
+// Which server a bridge talks to (#3078).
+//
+// The server is not pinned to 3001. `server/index.ts` walks forward off a
+// busy default (`Port 3001 busy → using 3002 instead`) and honours `PORT`,
+// then publishes whatever it actually bound to `<workspace>/.server-port`.
+// A client that does not read that file either connects to nothing (case A:
+// `PORT=3099` and nobody on 3001) or — worse — connects cleanly to a
+// DIFFERENT instance that happens to hold 3001 (case B), which with a shared
+// `MULMOCLAUDE_AUTH_TOKEN` authenticates without a single error.
+//
+// This is the same class as #2650 (Vite's proxy target) and #2981
+// (`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 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";
+const MIN_PORT = 1;
+const MAX_PORT = 65_535;
+/**
+ * The published port, or `null` for anything that is not one.
+ *
+ * Decimal digits only. The writer is `formatServerPort()`, which emits
+ * `${port}\n` and nothing else, so there is no lenient shape worth
+ * accepting — while `Number.parseInt` would read `3002abc` as 3002 and send
+ * the bridge to a port a corrupted file never meant.
+ */
+export function parsePublishedPort(raw) {
+    if (raw === null)
+        return null;
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed))
+        return null;
+    const port = Number.parseInt(trimmed, 10);
+    return port >= MIN_PORT && port <= MAX_PORT ? port : null;
+}
+/**
+ * The origin the running server published, or `null` if it published none.
+ *
+ * `127.0.0.1` rather than `localhost`: the server binds the IPv4 loopback
+ * explicitly (`app.listen(port, "127.0.0.1")`), while `localhost` resolves
+ * to `::1` first on a dual-stack host. Usually that still works — nothing
+ * holds `::1`, the connection is refused and Node falls back to IPv4 — but
+ * when something IS there the client reaches it and never falls back, which
+ * is the silent misdirection this module exists to remove (#2981).
+ */
+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`.
+ *
+ * An explicit value still wins, so nothing that already sets one changes.
+ * 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) {
+    return resolvePublishedApiUrl(explicit) ?? DEFAULT_API_URL;
+}

package/dist/client.d.ts

@@ -14,7 +14,9 @@ export interface BridgeClientOptions {
     /** Required. Identifier for this bridge in the handshake.
      *  Matches `handshake.auth.transportId` server-side. */
     transportId: string;
-    /** Defaults to `$MULMOCLAUDE_API_URL` or `http://localhost:3001`. */
+    /** Defaults to `$MULMOCLAUDE_API_URL`, then the port the server
+     *  published to `<workspace>/.server-port`, then
+     *  `http://localhost:3001` (#3078). */
     apiUrl?: string;
     /** Flat primitive bag forwarded to the host app's startChat
      *  callback via the handshake (`BridgeOptions` from the
@@ -41,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

@@ -13,12 +13,13 @@
 // minimal non-Node equivalent.
 import { io } from "socket.io-client";
 import { CHAT_SOCKET_EVENTS, CHAT_SOCKET_PATH } from "@mulmobridge/protocol";
-import { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+import { readBridgeToken, tokenFilePath } from "./token.js";
 import { readBridgeEnvOptions } from "./options.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;
-const DEFAULT_API_URL = "http://localhost:3001";
 /**
  * Resolve the bearer token from the workspace / env var, exit with
  * a clear error if absent. Kept separate so bridges that want to
@@ -29,67 +30,237 @@ export function requireBearerToken() {
     const token = readBridgeToken();
     if (token !== null)
         return token;
+    // `tokenFilePath()` rather than `TOKEN_FILE_PATH`, which is fixed at module
+    // load: a bridge that imports this before `dotenv/config` would otherwise be
+    // told to look somewhere the token was never going to be.
     process.stderr.write(`No bearer token found. The MulmoClaude server writes one to\n` +
-        `  ${TOKEN_FILE_PATH}\n` +
+        `  ${tokenFilePath()}\n` +
         `at startup (mode 0600). Start the server with \`yarn dev\` (or\n` +
         `\`npm run dev\`) first, or set MULMOCLAUDE_AUTH_TOKEN to the\n` +
         `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) {
-    const apiUrl = opts.apiUrl ?? process.env.MULMOCLAUDE_API_URL ?? DEFAULT_API_URL;
+    // 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. 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();
     // `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}).`);
@@ -104,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/index.d.ts

@@ -1,8 +1,10 @@
 export { createBridgeClient, requireBearerToken, type MessageAck, type PushEvent, type BridgeClientOptions, type BridgeClient } from "./client.js";
-export { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+export { readBridgeToken, tokenFilePath, TOKEN_FILE_PATH } from "./token.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";

package/dist/index.js

@@ -1,9 +1,11 @@
 // @mulmobridge/client — shared socket.io client for all MulmoBridge bridges.
 export { createBridgeClient, requireBearerToken } from "./client.js";
-export { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+export { readBridgeToken, tokenFilePath, TOKEN_FILE_PATH } from "./token.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";

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/dist/token.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Where the token file is, resolved NOW.
+ *
+ * Prefer this over `TOKEN_FILE_PATH` for anything that reads, writes, or
+ * reports the path: the constant freezes the workspace root at import time, so
+ * it disagrees with `readBridgeToken()` for any process that sets
+ * `MULMOCLAUDE_WORKSPACE_PATH` after importing this package (Codex, #3078).
+ */
+export declare function tokenFilePath(): string;
+/** Public since #272, so it stays. It now honours `MULMOCLAUDE_WORKSPACE_PATH`
+ *  (#3078) instead of hardcoding `<homedir>/mulmoclaude`, but it is a snapshot
+ *  taken at import time — use `tokenFilePath()` unless you specifically want
+ *  the value as it stood when the module loaded. */
 export declare const TOKEN_FILE_PATH: string;
 export declare function readBridgeToken(): string | null;

package/dist/token.js

@@ -4,26 +4,34 @@
 // Resolution order:
 //   1. `MULMOCLAUDE_AUTH_TOKEN` env var (useful for parallel shells,
 //      CI, or when the user runs the bridge against a different
-//      workspace than ~/mulmoclaude/)
-//   2. `<homedir>/mulmoclaude/.session-token` — the file the server
-//      writes at startup. Same path the Vite dev plugin reads from.
+//      workspace than the server's)
+//   2. `<workspace>/.session-token` — the file the server writes at
+//      startup. Same path the Vite dev plugin reads from, and the
+//      pair of `.server-port` (see `workspace.ts`).
 //
 // Returns null if neither source yields a non-empty string — the
 // caller decides how to react (exit with a helpful message, in the
 // bridge's case).
-import fs from "fs";
-import os from "os";
-import path from "path";
-export const TOKEN_FILE_PATH = path.join(os.homedir(), "mulmoclaude", ".session-token");
+import { readSidecarFile, SIDECAR_FILES, sidecarPath } from "./workspace.js";
+/**
+ * Where the token file is, resolved NOW.
+ *
+ * Prefer this over `TOKEN_FILE_PATH` for anything that reads, writes, or
+ * reports the path: the constant freezes the workspace root at import time, so
+ * it disagrees with `readBridgeToken()` for any process that sets
+ * `MULMOCLAUDE_WORKSPACE_PATH` after importing this package (Codex, #3078).
+ */
+export function tokenFilePath() {
+    return sidecarPath(SIDECAR_FILES.token);
+}
+/** Public since #272, so it stays. It now honours `MULMOCLAUDE_WORKSPACE_PATH`
+ *  (#3078) instead of hardcoding `<homedir>/mulmoclaude`, but it is a snapshot
+ *  taken at import time — use `tokenFilePath()` unless you specifically want
+ *  the value as it stood when the module loaded. */
+export const TOKEN_FILE_PATH = sidecarPath(SIDECAR_FILES.token);
 export function readBridgeToken() {
     const fromEnv = process.env.MULMOCLAUDE_AUTH_TOKEN;
     if (typeof fromEnv === "string" && fromEnv.length > 0)
         return fromEnv;
-    try {
-        const raw = fs.readFileSync(TOKEN_FILE_PATH, "utf-8").trim();
-        return raw.length > 0 ? raw : null;
-    }
-    catch {
-        return null;
-    }
+    return readSidecarFile(SIDECAR_FILES.token);
 }

package/dist/workspace.d.ts

@@ -0,0 +1,23 @@
+/** Sidecar files the server rewrites on every startup. */
+export declare const SIDECAR_FILES: {
+    readonly token: ".session-token";
+    readonly port: ".server-port";
+};
+/**
+ * The workspace root the server is using.
+ *
+ * Same rule as the server's own `workspacePath`
+ * (`server/workspace/paths.ts`): `MULMOCLAUDE_WORKSPACE_PATH` wins,
+ * otherwise `<homedir>/mulmoclaude`. The server's extra test-env
+ * branch is deliberately not mirrored — it isolates the server's own
+ * integration runs and means nothing to a bridge process.
+ */
+export declare function workspaceRoot(): string;
+/** Absolute path of one sidecar file inside the workspace. */
+export declare function sidecarPath(fileName: string): string;
+/**
+ * Sidecar contents, trimmed. `null` when the file is absent,
+ * unreadable, or holds nothing but whitespace — all of which mean the
+ * same thing to a caller: the server has not told us this yet.
+ */
+export declare function readSidecarFile(fileName: string): string | null;

package/dist/workspace.js

@@ -0,0 +1,54 @@
+// Where a bridge looks for the sidecar files the server writes on every
+// startup (#3078).
+//
+// The server publishes two files into its workspace root at boot:
+// `.session-token` (the bearer token the bridge presents) and
+// `.server-port` (the port it actually bound, which is NOT always the
+// one it was asked for — see `server/workspace/serverPort.ts`). They
+// are a PAIR, rewritten together on every restart, so both are
+// resolved from one root here rather than each growing its own idea of
+// where the workspace is. Reading only one of them is how the bridges
+// ended up following the token across restarts while still addressing
+// a hardcoded `localhost:3001`.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_WORKSPACE_DIR = "mulmoclaude";
+/** Sidecar files the server rewrites on every startup. */
+export const SIDECAR_FILES = {
+    token: ".session-token",
+    port: ".server-port",
+};
+/**
+ * The workspace root the server is using.
+ *
+ * Same rule as the server's own `workspacePath`
+ * (`server/workspace/paths.ts`): `MULMOCLAUDE_WORKSPACE_PATH` wins,
+ * otherwise `<homedir>/mulmoclaude`. The server's extra test-env
+ * branch is deliberately not mirrored — it isolates the server's own
+ * integration runs and means nothing to a bridge process.
+ */
+export function workspaceRoot() {
+    const configured = process.env.MULMOCLAUDE_WORKSPACE_PATH;
+    if (typeof configured === "string" && configured.length > 0)
+        return configured;
+    return path.join(os.homedir(), DEFAULT_WORKSPACE_DIR);
+}
+/** Absolute path of one sidecar file inside the workspace. */
+export function sidecarPath(fileName) {
+    return path.join(workspaceRoot(), fileName);
+}
+/**
+ * Sidecar contents, trimmed. `null` when the file is absent,
+ * unreadable, or holds nothing but whitespace — all of which mean the
+ * same thing to a caller: the server has not told us this yet.
+ */
+export function readSidecarFile(fileName) {
+    try {
+        const raw = fs.readFileSync(sidecarPath(fileName), "utf-8").trim();
+        return raw.length > 0 ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/client",
-  "version": "1.0.2",
+  "version": "1.2.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.1.2",
+    "@mulmoclaude/common": "^1.3.0",
     "socket.io-client": "^4.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.4.1",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/client#readme",