teamshare-bridge 0.26.14 → 0.26.17

package/dist/bridge/local-server.js

@@ -6,14 +6,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MCP_REQUIRED_ACCEPT = void 0;
 exports.getProbeToken = getProbeToken;
 exports.startProbeServer = startProbeServer;
+exports.enableTokenStatePersistence = enableTokenStatePersistence;
+exports.tokenStateSnapshot = tokenStateSnapshot;
 exports.registerSessionToken = registerSessionToken;
 exports.revokeSessionToken = revokeSessionToken;
 exports.revokeSessionTokensForApiKey = revokeSessionTokensForApiKey;
 exports.revokeSessionTokensForLabel = revokeSessionTokensForLabel;
+exports.revokeSessionTokensForSession = revokeSessionTokensForSession;
 exports.noteSessionLive = noteSessionLive;
 exports.resolveRelayFallbackAgentId = resolveRelayFallbackAgentId;
 exports.relayRequestHeaders = relayRequestHeaders;
 exports.relayResponseHeaders = relayResponseHeaders;
+exports.isUnknownMcpSession = isUnknownMcpSession;
+exports.isReplayableMcpRequest = isReplayableMcpRequest;
 exports.probeErrorMessage = probeErrorMessage;
 /**
  * Localhost probe server - the piece the TeamShare website detects.
@@ -376,6 +381,11 @@ async function startProbeServer(preferredPort, getStatus, onReload, onPushState,
     throw new Error(`no free probe port found (tried ${tried.join(', ')})`);
 }
 function listen(port, getStatus, onReload, onPushState, sessionCallbacks, onRelease, onStopAllSessions) {
+    // Restore the relay tokens a previous daemon instance minted for sessions
+    // that may still be running (a restart must not 401 a live run). Reads the
+    // agent ids from the state file and re-resolves each key from the secret
+    // store - no API key is ever written there.
+    enableTokenStatePersistence();
     return new Promise((resolve, reject) => {
         const server = (0, node_http_1.createServer)((req, res) => handle(req, res, getStatus, onReload, onPushState, sessionCallbacks, onRelease, onStopAllSessions));
         // WebSocket upgrade handler for the CDP relay.
@@ -591,12 +601,15 @@ function handle(req, res, getStatus, onReload, onPushState, sessionCallbacks, on
         });
         return;
     }
-    // Mint a per-session MCP relay token (2026-10-15). The CLI knows its own
-    // agent key and the probe token (from runtime.json), so it can arm the relay
-    // for its harness WITHOUT the key ever being written to a config file:
-    //   POST /internal/mcp-token { apiKey, label? } -> { token }
-    // The token is single-purpose (this daemon, 1 h) and revoked when the harness
-    // exits; it identifies the run to `/mcp-relay`.
+    // Mint (or REUSE) a per-session MCP relay token (2026-10-15). The CLI knows
+    // its own agent key and the probe token (from runtime.json), so it can arm the
+    // relay for its harness WITHOUT the key ever being written to a config file:
+    //   POST /internal/mcp-token { apiKey, label?, sessionId? } -> { token }
+    // The token is single-purpose (this daemon, loopback only). With a sessionId
+    // the SAME token is returned for the life of that bridge session, because the
+    // OpenCode service keeps the MCP connection it opened with the first one
+    // (2026-10-25 - see `RelaySession.sessionId`). It never expires while in use;
+    // it dies after TOKEN_TTL_MS of idleness, on an explicit run end, or on stop.
     if (req.method === 'POST' && url.pathname === '/internal/mcp-token') {
         void (async () => {
             try {
@@ -610,7 +623,9 @@ function handle(req, res, getStatus, onReload, onPushState, sessionCallbacks, on
                     res.end(JSON.stringify({ ok: false, error: 'apiKey (ts_...) is required' }));
                     return;
                 }
-                const token = registerSessionToken(apiKey, typeof parsed.label === 'string' ? parsed.label : undefined);
+                const token = registerSessionToken(apiKey, typeof parsed.label === 'string' ? parsed.label : undefined, typeof parsed.sessionId === 'string' && parsed.sessionId
+                    ? parsed.sessionId
+                    : undefined);
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ ok: true, token }));
             }
@@ -621,10 +636,12 @@ function handle(req, res, getStatus, onReload, onPushState, sessionCallbacks, on
         })();
         return;
     }
-    // Retire a per-run MCP relay token the moment its run is over (2026-10-15):
-    //   POST /internal/mcp-token/revoke { token } -> { ok }
-    // Without this, a reused run directory could keep acting as the previous
-    // run's agent until the 1 h TTL expired.
+    // Retire a relay token when its run is TRULY over (2026-10-15):
+    //   POST /internal/mcp-token/revoke { token } | { sessionId } -> { ok }
+    // Deliberately NOT called from the harness's own exit path: a resumed run
+    // keeps the OpenCode service's MCP connection, and revoking its token would
+    // leave that live connection authenticating with a dead credential
+    // (2026-10-25). Stop and a completed run call it instead.
     if (req.method === 'POST' && url.pathname === '/internal/mcp-token/revoke') {
         void (async () => {
             try {
@@ -632,11 +649,16 @@ function handle(req, res, getStatus, onReload, onPushState, sessionCallbacks, on
                 for await (const chunk of req)
                     chunks.push(chunk);
                 const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+                let revoked = 0;
                 if (typeof parsed.token === 'string' && parsed.token) {
                     revokeSessionToken(parsed.token);
+                    revoked += 1;
+                }
+                if (typeof parsed.sessionId === 'string' && parsed.sessionId) {
+                    revoked += revokeSessionTokensForSession(parsed.sessionId);
                 }
                 res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ ok: true }));
+                res.end(JSON.stringify({ ok: true, revoked }));
             }
             catch (err) {
                 res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -730,43 +752,213 @@ function handle(req, res, getStatus, onReload, onPushState, sessionCallbacks, on
     res.writeHead(404, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ ok: false, error: 'not found' }));
 }
-const TOKEN_TTL_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * IDLE lifetime of a relay token, refreshed on EVERY authenticated relay call
+ * (sliding expiry). A run that keeps using its tools never expires.
+ *
+ * WHY 24 HOURS AND NOT 1 HOUR (2026-10-25): a paused run waits for a PERSON.
+ * `ask_human` can be answered after a night's sleep, and the resumed run still
+ * authenticates with the token its MCP connection was opened with - a 1 h idle
+ * clock killed exactly that case, which is the failure the session-scoped token
+ * exists to prevent. Exposure stays bounded: the token is revoked on stop, on a
+ * scope violation, and 24 h after its last relayed request; it carries no more
+ * authority than the agent key the daemon injects, and it never leaves the
+ * machine.
+ */
+const TOKEN_TTL_MS = 24 * 60 * 60 * 1000; // 24 h idle
 const sessionTokens = new Map();
+/** sessionId -> token, so a resume of the same session reuses its identity. */
+const tokenBySession = new Map();
+/**
+ * DURABILITY (2026-10-25): the map is in memory, so a daemon restart (manual,
+ * upgrade, watchdog replace) used to invalidate every live run's token - and
+ * the OpenCode service cannot recover from that 401. Session-backed tokens are
+ * persisted WITHOUT their API key (the agent id is enough to re-resolve the key
+ * from the secret store at boot), so a restart keeps live runs working without
+ * writing a credential to disk.
+ *
+ * `TEAMSHARE_STATE_DIR` exists so a test can round-trip the file without
+ * touching the operator's real home directory.
+ */
+const TOKEN_STATE_FILE = (0, node_path_1.join)(process.env.TEAMSHARE_STATE_DIR?.trim() ||
+    (0, node_path_1.join)((0, node_os_1.homedir)(), '.teamshare', 'state'), 'mcp-tokens.json');
+let tokenStateEnabled = false;
+let lastTokenStateSave = 0;
+function saveTokenState(force = false) {
+    if (!tokenStateEnabled)
+        return;
+    const now = Date.now();
+    if (!force && now - lastTokenStateSave < 5 * 60_000)
+        return;
+    lastTokenStateSave = now;
+    try {
+        const rows = [];
+        for (const [token, entry] of sessionTokens) {
+            // Only session-backed tokens are worth surviving: a token with no session
+            // id cannot be reused by anything (and the relay log calls that a bug).
+            if (!entry.label || !entry.sessionId)
+                continue;
+            rows.push({
+                token,
+                label: entry.label,
+                sessionId: entry.sessionId,
+                createdAt: entry.createdAt,
+            });
+        }
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(TOKEN_STATE_FILE), { recursive: true });
+        (0, node_fs_1.writeFileSync)(TOKEN_STATE_FILE, JSON.stringify(rows), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort: a read-only state dir must never break a run */
+    }
+}
+/**
+ * Load the tokens a previous daemon instance minted, re-resolving each agent's
+ * key from the secret store (never from this file). Called when the probe
+ * server starts, so tests that import this module never touch disk.
+ */
+function enableTokenStatePersistence(resolveKey = agentKeyById) {
+    tokenStateEnabled = true;
+    try {
+        const raw = (0, node_fs_1.readFileSync)(TOKEN_STATE_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        const rows = Array.isArray(parsed) ? parsed : [];
+        const now = Date.now();
+        for (const row of rows) {
+            if (!row ||
+                typeof row.token !== 'string' ||
+                !row.token ||
+                typeof row.label !== 'string' ||
+                !row.label ||
+                typeof row.sessionId !== 'string' ||
+                !row.sessionId) {
+                continue;
+            }
+            const createdAt = Number(row.createdAt);
+            if (!Number.isFinite(createdAt) || now - createdAt > TOKEN_TTL_MS)
+                continue;
+            // Resolve the key now when the secret store is readable, but NEVER drop
+            // the row when it is not: a transient failure at boot must not 401 a
+            // live run. An empty key is adopted on the first relayed request or on
+            // the session's own re-registration.
+            const apiKey = resolveKey(row.label) ?? '';
+            sessionTokens.set(row.token, {
+                apiKey,
+                label: row.label,
+                sessionId: row.sessionId,
+                createdAt,
+            });
+            tokenBySession.set(row.sessionId, row.token);
+        }
+        lastTokenStateSave = now;
+    }
+    catch {
+        /* first boot, or a corrupt file - nothing to restore */
+    }
+}
+/**
+ * The persisted rows a restart would restore, for tests and diagnostics.
+ * Deliberately contains NO apiKey field - that is the invariant this file
+ * exists to keep.
+ */
+function tokenStateSnapshot() {
+    const rows = [];
+    for (const [token, entry] of sessionTokens) {
+        if (!entry.label || !entry.sessionId)
+            continue;
+        rows.push({
+            token,
+            label: entry.label,
+            sessionId: entry.sessionId,
+            createdAt: entry.createdAt,
+        });
+    }
+    return rows;
+}
 /** Agents with a session the daemon currently considers live (agentId -> last ping). */
 const liveSessionAgents = new Map();
 const LIVE_SESSION_MAX_MS = 12 * 60 * 60 * 1000;
 /** agentId -> { key, at } so the fallback does not read the secret store per call. */
 const keyCache = new Map();
 const KEY_CACHE_MS = 60_000;
-/** Register a new session token for the given agent key. Returns the token. */
-function registerSessionToken(apiKey, label) {
+/**
+ * Register a relay token for an agent key.
+ *
+ * With a `sessionId`, an existing token for that session is REUSED (and its
+ * idle clock refreshed). That is the load-bearing part: the OpenCode service
+ * keeps the first MCP connection for the run's project directory, so handing a
+ * resumed/continued run a NEW token would leave the live connection
+ * authenticating with the OLD one - and 401ing forever.
+ */
+function registerSessionToken(apiKey, label, sessionId) {
+    if (sessionId) {
+        const existing = tokenBySession.get(sessionId);
+        const entry = existing ? sessionTokens.get(existing) : undefined;
+        if (existing && entry) {
+            // Restored from disk without a key (the secret store was unavailable at
+            // boot): adopt the identity that is re-registering, keeping the token the
+            // live MCP connection already holds.
+            if (!entry.apiKey) {
+                entry.apiKey = apiKey;
+                if (label)
+                    entry.label = label;
+                entry.createdAt = Date.now();
+                saveTokenState(true);
+                return existing;
+            }
+            if (entry.apiKey === apiKey) {
+                if (label)
+                    entry.label = label;
+                entry.createdAt = Date.now();
+                return existing;
+            }
+            // A different key for the same session must never inherit the token.
+            dropToken(existing);
+        }
+        tokenBySession.delete(sessionId);
+    }
     const token = (0, node_crypto_1.randomBytes)(24).toString('hex');
-    sessionTokens.set(token, { apiKey, label, createdAt: Date.now() });
+    sessionTokens.set(token, { apiKey, label, sessionId, createdAt: Date.now() });
+    if (sessionId)
+        tokenBySession.set(sessionId, token);
+    saveTokenState(true);
     return token;
 }
-/** Revoke a session token (harness exit). */
-function revokeSessionToken(token) {
+/** Delete a token AND its session/agent indexes (one way in, one way out). */
+function dropToken(token) {
+    const entry = sessionTokens.get(token);
+    if (!entry)
+        return false;
     sessionTokens.delete(token);
+    if (entry.sessionId && tokenBySession.get(entry.sessionId) === token) {
+        tokenBySession.delete(entry.sessionId);
+    }
+    return true;
+}
+/** Revoke a session token (explicit run end / stop). */
+function revokeSessionToken(token) {
+    if (dropToken(token))
+        saveTokenState(true);
 }
 /**
  * Revoke every relay token minted for an agent's API key (2026-10).
  *
- * THE FORCED-STOP HOLE: the CLI revokes its own token in `cleanMcp`, but a
- * forced stop kills the CLI, so that code never runs. The token then stayed
- * valid for an hour and a surviving OpenCode V2 service session kept calling
- * MCP tools as the agent. The daemon knows the agent's key, so it can revoke
- * every token for that key at stop time. Returns how many were revoked.
+ * THE FORCED-STOP HOLE: a forced stop kills the CLI, so its own cleanup never
+ * runs. The token would otherwise stay valid and a surviving OpenCode V2
+ * service session would keep calling MCP tools as the agent. The daemon knows
+ * the agent's key, so it revokes every token for that key at stop time.
+ * Returns how many were revoked.
  */
 function revokeSessionTokensForApiKey(apiKey) {
     if (!apiKey)
         return 0;
     let revoked = 0;
     for (const [token, session] of sessionTokens) {
-        if (session.apiKey === apiKey) {
-            sessionTokens.delete(token);
+        if (session.apiKey === apiKey && dropToken(token))
             revoked++;
-        }
     }
+    if (revoked > 0)
+        saveTokenState(true);
     return revoked;
 }
 /** Revoke every relay token whose debug label is `label` (the agent id). */
@@ -775,11 +967,30 @@ function revokeSessionTokensForLabel(label) {
         return 0;
     let revoked = 0;
     for (const [token, session] of sessionTokens) {
-        if (session.label === label) {
-            sessionTokens.delete(token);
+        if (session.label === label && dropToken(token))
             revoked++;
-        }
     }
+    if (revoked > 0)
+        saveTokenState(true);
+    return revoked;
+}
+/**
+ * Revoke the token(s) of ONE bridge session. Used when the session is truly
+ * finished (never on a harness exit - a resume keeps using the same token,
+ * because the OpenCode service still holds the connection it opened with it).
+ */
+function revokeSessionTokensForSession(sessionId) {
+    if (!sessionId)
+        return 0;
+    let revoked = 0;
+    for (const [token, session] of sessionTokens) {
+        if (session.sessionId === sessionId && dropToken(token))
+            revoked++;
+    }
+    if (tokenBySession.get(sessionId))
+        tokenBySession.delete(sessionId);
+    if (revoked > 0)
+        saveTokenState(true);
     return revoked;
 }
 /**
@@ -848,13 +1059,20 @@ function agentKeyById(agentId) {
     keyCache.set(agentId, { key, at: Date.now() });
     return key;
 }
-/** Expire tokens older than TTL (called periodically). */
+/**
+ * Expire tokens that have been IDLE longer than the TTL (sliding clock).
+ * `handleMcpRelay` refreshes `createdAt` on every authenticated call, so this
+ * only reaps sessions that stopped using their tools.
+ */
 function expireTokens() {
     const now = Date.now();
+    let dropped = 0;
     for (const [token, entry] of sessionTokens) {
-        if (now - entry.createdAt > TOKEN_TTL_MS)
-            sessionTokens.delete(token);
+        if (now - entry.createdAt > TOKEN_TTL_MS && dropToken(token))
+            dropped++;
     }
+    if (dropped > 0)
+        saveTokenState(true);
 }
 // Expire every 5 minutes.
 setInterval(expireTokens, 5 * 60_000).unref?.();
@@ -942,13 +1160,136 @@ function relayResponseHeaders(upstream) {
         headers['mcp-session-id'] = sessionId;
     return headers;
 }
+/**
+ * Buddy mapping for a re-initialized upstream MCP session (2026-10-25).
+ *
+ * When the hub forgets a session (`404 Session not found or expired`) the relay
+ * opens a fresh one and replays the request. Clients (the OpenCode SDK) only
+ * adopt a new `mcp-session-id` reliably on `initialize`, so the OLD id is
+ * aliased to the new one here and rewritten on the way in. Bounded: an alias is
+ * worthless after the client re-initializes on its own.
+ */
+const SESSION_ALIAS_MAX = 500;
+const sessionAlias = new Map();
+function aliasUpstreamSession(oldId, newId) {
+    if (!oldId || !newId || oldId === newId)
+        return;
+    sessionAlias.set(oldId, newId);
+    while (sessionAlias.size > SESSION_ALIAS_MAX) {
+        const oldest = sessionAlias.keys().next().value;
+        if (typeof oldest !== 'string')
+            break;
+        sessionAlias.delete(oldest);
+    }
+}
+/** Does this upstream body mean "that MCP session no longer exists"? */
+function isUnknownMcpSession(body) {
+    return /session (?:not found|expired|unknown)|no such session|invalid session/i.test(body);
+}
+/**
+ * Is this request safe to REPLAY after a hub session expired?
+ *
+ * Only metadata requests. A `tools/call` may have reached the tool even when
+ * the response looks like a session error (a proxy, or a hub restart mid-call),
+ * and replaying `create_document` / `submit_qa_report` would duplicate it. The
+ * cost of not replaying a tool call is one clear error the agent can retry; the
+ * cost of replaying a mutation is a duplicate write.
+ */
+function isReplayableMcpRequest(body) {
+    const raw = typeof body === 'string' ? body : body.toString('utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    const messages = Array.isArray(parsed) ? parsed : [parsed];
+    if (messages.length === 0)
+        return false;
+    for (const message of messages) {
+        if (!message || typeof message !== 'object')
+            return false;
+        const method = message.method;
+        if (typeof method !== 'string' || !method)
+            return false;
+        // Anything not a tools/call is a read/metadata request. Be explicit about
+        // the mutating one rather than allow-listing every future read method.
+        if (method === 'tools/call')
+            return false;
+    }
+    return true;
+}
+/** Open a fresh MCP session upstream and complete the initialize handshake. */
+async function initializeUpstreamSession(apiBase, incoming, apiKey) {
+    const headers = relayRequestHeaders(incoming, apiKey);
+    delete headers['mcp-session-id'];
+    const initBody = JSON.stringify({
+        jsonrpc: '2.0',
+        id: `relay-init-${(0, node_crypto_1.randomBytes)(6).toString('hex')}`,
+        method: 'initialize',
+        params: {
+            protocolVersion: headerValue(incoming['mcp-protocol-version']) ?? '2025-06-18',
+            capabilities: {},
+            clientInfo: { name: 'teamshare-bridge-relay', version: VERSION },
+        },
+    });
+    const init = await fetch(`${apiBase}/mcp`, {
+        method: 'POST',
+        headers,
+        body: initBody,
+    });
+    const sessionId = init.headers.get('mcp-session-id');
+    // Drain either shape - an SSE initialize answers with a stream.
+    await init.text().catch(() => '');
+    if (!sessionId)
+        return null;
+    await fetch(`${apiBase}/mcp`, {
+        method: 'POST',
+        headers: { ...headers, 'mcp-session-id': sessionId },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            method: 'notifications/initialized',
+        }),
+    })
+        .then((r) => r.text())
+        .catch(() => '');
+    return sessionId;
+}
+/** Pipe an upstream response to the local client (SSE included). */
+async function pumpUpstream(res, upstream, extraHeaders = {}) {
+    res.writeHead(upstream.status, {
+        ...relayResponseHeaders(upstream.headers),
+        ...extraHeaders,
+    });
+    if (!upstream.body) {
+        res.end();
+        return;
+    }
+    const reader = upstream.body.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        res.write(value);
+    }
+    res.end();
+}
 async function handleMcpRelay(req, res) {
     const rawToken = req.headers['x-teamshare-session-token'];
     const token = typeof rawToken === 'string' ? rawToken : undefined;
     let apiKey = null;
+    let relaySession = null;
     if (token) {
         const session = sessionTokens.get(token);
         if (!session) {
+            // A 401 here kills EVERY tool call of the run, and the OpenCode SDK does
+            // not re-initialize on it - it reports "requires a login before it can
+            // register a client" forever. Never let that pass in silence.
+            console.warn(`[mcp-relay] rejected session token ${token.slice(0, 8)}… ` +
+                `(unknown or revoked; active tokens: ${sessionTokens.size}) - ` +
+                'the run lost its tools. A token is revoked on stop or after ' +
+                '1 h of idleness; a live run should never see this.');
             res.writeHead(401, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
                 ok: false,
@@ -956,6 +1297,28 @@ async function handleMcpRelay(req, res) {
             }));
             return;
         }
+        // SLIDING EXPIRY: a session that keeps calling tools never expires. The
+        // persisted copy is refreshed at most every 5 minutes (saveTokenState), so
+        // a daemon restart restores the token a live run is still using.
+        session.createdAt = Date.now();
+        saveTokenState();
+        // A token restored from disk without its key (the secret store was
+        // unavailable at boot) resolves lazily here, on the first real request.
+        if (!session.apiKey && session.label) {
+            session.apiKey = agentKeyById(session.label) ?? '';
+        }
+        if (!session.apiKey) {
+            console.warn(`[mcp-relay] session token ${token.slice(0, 8)}… has no resolvable agent key ` +
+                `(label: ${session.label ?? 'none'}) - the run cannot authenticate.`);
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                ok: false,
+                error: 'mcp-relay could not resolve this session’s agent key. ' +
+                    'Reconnect the agent, then restart the run.',
+            }));
+            return;
+        }
+        relaySession = session;
         apiKey = session.apiKey;
     }
     else {
@@ -1005,30 +1368,66 @@ async function handleMcpRelay(req, res) {
     // request is rejected as session-less. See `relayRequestHeaders` /
     // `relayResponseHeaders`.
     const apiBase = (process.env.TEAMSHARE_API_URL ?? 'https://api.teamshare.name.ng').replace(/\/$/, '');
+    const incomingSessionId = headerValue(req.headers['mcp-session-id']);
+    const upstreamSessionId = incomingSessionId
+        ? (sessionAlias.get(incomingSessionId) ?? incomingSessionId)
+        : undefined;
+    const upstreamHeaders = relayRequestHeaders(req.headers, apiKey);
+    if (upstreamSessionId)
+        upstreamHeaders['mcp-session-id'] = upstreamSessionId;
+    else
+        delete upstreamHeaders['mcp-session-id'];
     try {
-        const apiRes = await fetch(`${apiBase}/mcp`, {
+        let apiRes = await fetch(`${apiBase}/mcp`, {
             method: 'POST',
-            headers: relayRequestHeaders(req.headers, apiKey),
+            headers: upstreamHeaders,
             body,
         });
-        // Stream the response back (SSE included - the body is piped verbatim).
-        res.writeHead(apiRes.status, relayResponseHeaders(apiRes.headers));
-        if (apiRes.body) {
-            const reader = apiRes.body.getReader();
-            const pump = async () => {
-                while (true) {
-                    const { done, value } = await reader.read();
-                    if (done)
-                        break;
-                    res.write(value);
+        // HUB SESSION EXPIRED (2026-10-25): a deploy/restart drops every MCP
+        // session, and the hub answers 404 "Session not found or expired" - a
+        // request the hub never dispatched (it failed before tool execution), so
+        // replaying it is safe. Open a fresh session and replay once instead of
+        // handing the failure to a client that gives up after two SSE retries.
+        if (apiRes.status === 404 && upstreamSessionId) {
+            const errorText = await apiRes.text().catch(() => '');
+            // A mutation is never replayed (a duplicate create is worse than an
+            // error the agent can retry); the fresh session is still established so
+            // the NEXT request works.
+            const replayable = isReplayableMcpRequest(body);
+            if (isUnknownMcpSession(errorText)) {
+                const fresh = await initializeUpstreamSession(apiBase, req.headers, apiKey);
+                if (fresh) {
+                    aliasUpstreamSession(upstreamSessionId, fresh);
+                    if (incomingSessionId && incomingSessionId !== upstreamSessionId) {
+                        aliasUpstreamSession(incomingSessionId, fresh);
+                    }
+                    if (replayable) {
+                        console.warn(`[mcp-relay] hub session expired${relaySession?.label ? ` for agent ${relaySession.label}` : ''} - re-initialized and replayed the request`);
+                        apiRes = await fetch(`${apiBase}/mcp`, {
+                            method: 'POST',
+                            headers: { ...upstreamHeaders, 'mcp-session-id': fresh },
+                            body,
+                        });
+                        await pumpUpstream(res, apiRes, {
+                            'mcp-session-id': apiRes.headers.get('mcp-session-id') ?? fresh,
+                        });
+                        return;
+                    }
+                    console.warn(`[mcp-relay] hub session expired${relaySession?.label ? ` for agent ${relaySession.label}` : ''} - re-initialized; the tools/call was NOT replayed (mutations are never replayed)`);
                 }
-                res.end();
-            };
-            await pump();
-        }
-        else {
-            res.end();
+                else {
+                    console.warn('[mcp-relay] hub session expired and re-initialize failed - forwarding the 404');
+                }
+            }
+            // Not a session problem (or re-init failed): forward what the hub said.
+            res.writeHead(404, {
+                'Content-Type': apiRes.headers.get('content-type') ?? 'application/json',
+            });
+            res.end(errorText);
+            return;
         }
+        // Stream the response back (SSE included - the body is piped verbatim).
+        await pumpUpstream(res, apiRes);
     }
     catch (err) {
         res.writeHead(502, { 'Content-Type': 'application/json' });