@optima-chat/agentic-sdk 0.34.1 → 0.36.0

package/dist/client/gateway-client.d.ts

@@ -29,6 +29,37 @@ export interface GatewayClientOptions {
      * SDK). Optional — omit it in headless/test contexts that don't trace.
      */
     sessionIdProvider?: () => string | null | undefined;
+    /**
+     * gw#2313 S1 — multi-session attach addressing. When this returns a session
+     * id, every socket open appends `?sessionId=<id>` so the gateway ATTACHES to
+     * that exact session (gateway three-intent leg, gw#905: attach / `?new=1`
+     * create / default reuse). Return null/undefined for the default-reuse leg
+     * (unchanged behaviour for existing hosts — this is why it is a separate
+     * option from `sessionIdProvider`, which only feeds OTel and must not change
+     * reconnect semantics). Non-string returns are treated as absent.
+     *
+     * Ownership mismatch or a dead session makes the gateway fall through to
+     * default resolution — the client cannot attach to someone else's session.
+     *
+     * Multi-tab recipe (gw#2313 decision, 06-25): store the id in **sessionStorage**
+     * (per-tab in the common case; localStorage would make tabs collide on one
+     * session), write it on `session_ready`, and return it here so F5/reconnect
+     * lands on the same session. Two caveats (#147 r1): "duplicate tab" and
+     * same-origin `target=_blank` COPY sessionStorage — a copied tab attaches to
+     * its parent's session unless the host detects the copy and calls
+     * `startNewSession()`; and the storage key should be namespaced per
+     * principal/environment (impersonation or personal↔enterprise switches leave
+     * a stale id that the gateway will reject with a warn on every open).
+     * `startNewSession()` takes precedence for its one open: an explicit "give
+     * me a fresh session" must not be silently overridden by a stored attach id
+     * (the caller should clear/overwrite its stored id when the new
+     * `session_ready` arrives). Blank/whitespace ids are treated as absent;
+     * 3 consecutive attach opens that upgraded but never reached `session_ready`
+     * drop the id (also a `?sessionId=` baked into `gatewayUrl`) until the next
+     * `session_ready` (escape hatch from owner-proxy pre-route dead loops); the
+     * count is keyed by id, so a new id starts from zero.
+     */
+    sessionAttachProvider?: () => string | null | undefined;
     reconnectOptions?: {
         maxRetries?: number;
         baseDelay?: number;
@@ -47,11 +78,6 @@ export interface GatewayClientOptions {
      */
     onMessageDispatched?: (clientMsgId: string, conversationId: string) => void;
 }
-/**
- * WebSocket client for the Optima gateway. Handles connect/reconnect,
- * heartbeat, token-refresh signalling, and event dispatch. Does not own any
- * state — everything flows out via the callbacks.
- */
 export declare class GatewayClient {
     private readonly options;
     private ws;
@@ -74,14 +100,53 @@ export declare class GatewayClient {
      */
     private connecting;
     /**
-     * One-shot flag: when set, the *next* socket open appends `new=1` so the
-     * gateway takes the `createSession` path (COO toggle ENTER/EXIT, #467/#1076).
-     * Consumed (reset to false) as soon as the URL is built, so it never leaks
-     * into subsequent auto-reconnects — a leaked `new=1` would spawn a fresh
-     * session (and, pre gateway drain-on-createSession invariant, an orphan) on
-     * every unexpected disconnect. Set via startNewSession().
+     * When set, socket opens append `new=1` so the gateway takes the
+     * `createSession` path (COO toggle ENTER/EXIT #467/#1076; gw#2313 "give me a
+     * fresh session"). Set via startNewSession().
+     * Consumed on the next **`session_ready`**, NOT when the URL is built and NOT
+     * on `onopen` (#147 r2 finding 1: `onopen` is only the HTTP 101 upgrade; the
+     * gateway rejects — `CONCURRENCY_LIMIT_EXCEEDED`, `AUTH_TOKEN_INVALID` — over
+     * the already-open socket). So it **deliberately survives failed opens and
+     * flows into auto-reconnect**: that leak IS the fix — do not "tidy" it back
+     * to consume-on-build, that re-introduces the silent fall-back to the session
+     * the caller just asked to leave. Bounded by FORCE_NEW_FAIL_ESCAPE_N (#147 r3
+     * finding 2): after N opens that upgraded but never reached `session_ready`
+     * the intent is dropped and the next open resolves by attach/default.
      */
     private forceNewNextConnect;
+    /** r1（#147 🟠4）：上一次 session_ready 报的 sessionId——跨 session 闸的判据。 */
+    private lastReadySessionId;
+    /**
+     * r1（#147 🟡）：带 attach 的 open 连续失败计数——owner-proxy 预路由拒连时（1013 循环），
+     * 每次重连都带同一个 sessionId 会撞同一判定直到重试耗尽。连续 ≥3 次失败后，下一次
+     * open 丢掉 attach id 按默认解析（gateway 本地可服务），成功后清零恢复 attach。
+     * r3 🟡：按 id 归键——宿主换了**新的有效 id** 时计数归零，不会因为旧 id 的失败被丢一轮。
+     * attach id 来源两种：provider 供的，或 README 临时通路烤在 `gatewayUrl` 里的 `?sessionId=`
+     * （r3 finding 3：后者也必须计 streak + 可删，否则 owner-proxy 1013 循环对它无界）。
+     */
+    private attachFailStreak;
+    /** 本次 open 是否带了 attach id（失败时归因给 streak 用）。 */
+    private lastOpenHadAttach;
+    /** #147 r3 finding 2：带 new=1 的 open 连续「已 open 但没 ready」计数（见 FORCE_NEW_FAIL_ESCAPE_N）。 */
+    private forceNewFailStreak;
+    /**
+     * #147 r3 finding 4：startNewSession() 那一刻的 outbox switch 纪元——new 意图活过失败 open
+     * 期间入队的帧都属于新 session，跨 session 闸只丢这个纪元之前的。随意图一起在 session_ready 清空。
+     */
+    private forceNewEpoch;
+    /** 同上，attach 腿：宿主要求 attach 到与当前不同的 id 时的纪元（同 id 重试沿用）。 */
+    private attachSwitch;
+    /**
+     * 🔴 #147 r2 finding 1/2/3 共用的一块状态：**本次 open 的寻址意图**。
+     * 消费点必须是 `session_ready` 而不是 `onopen` —— `onopen` 只是 HTTP 101 升级，
+     * gateway 的 `/ws` 是 `@fastify/websocket`，`handleWebSocket` 在 101 **之后**才跑，
+     * `CONCURRENCY_LIMIT_EXCEEDED` / `AUTH_TOKEN_INVALID` 都是通过**已打开的 socket**
+     * 发来的。在 onopen 消费 = 点「新建」→ 101 → 意图蒸发 → 上限错误关闭 → 重连带
+     * `sessionId=ses_old` → 静默回到刚要离开的那个 session。
+     */
+    private pendingOpenIntent;
+    /** 当前 socket 的「见过 session_ready」回写钩子（随连接作用域创建/清空）。 */
+    private readyFlagForCurrentSocket;
     /**
      * `sub` of the token the CURRENT socket was opened with — the principal this
      * connection is bound to, since the gateway resolves the session from the
@@ -169,11 +234,37 @@ export declare class GatewayClient {
     reconnect(opts?: TokenProviderOpts): Promise<void>;
     /**
      * Force a brand-new gateway session: appends `new=1` to the next connect URL
-     * (→ gateway `createSession` instead of resolve/reuse) and reconnects. Used by
-     * the COO toggle (ENTER/EXIT, #467/#1076) — mode is baked at session creation,
-     * so switching it requires a fresh session. One-shot: the flag is consumed on
-     * the next open, so it never leaks into auto-reconnect. B1-freeness (no orphan
-     * always-on container) is a gateway invariant, not this call's responsibility.
+     * (→ gateway `createSession` instead of resolve/reuse) and reconnects.
+     * ⚠️ This MOVES the client to a fresh session — it does not open an
+     * additional one (one GatewayClient holds exactly one socket/session; a
+     * multi-session host runs one client per tab/instance). The abandoned
+     * session is NOT released server-side: it stays alive (own container,
+     * counted by `GET /api/sessions/concurrency`) until idle-suspend/TTL —
+     * repeated calls can hit the concurrency limit (gw#2315 default 10).
+     * **General-purpose primitive** (gw#2313): any caller that wants a fresh
+     * session uses this, and the COO
+     * toggle (ENTER/EXIT, #467/#1076) uses it because mode is baked at session
+     * creation. Takes precedence over `sessionAttachProvider` for its one open.
+     * One-shot, but **deliberately survives failed opens**: the flag is consumed on
+     * the next `session_ready`, not on `onopen` (#147 r2 finding 1). So if the first
+     * attempt is rejected *after* the 101 upgrade — gw#2315 concurrency limit,
+     * `AUTH_TOKEN_INVALID`, any drop between 101 and `session_ready` — auto-reconnect
+     * keeps retrying with `new=1` instead of silently attaching back to the session
+     * the caller just asked to leave. That "leak into auto-reconnect" **is** the fix;
+     * do not undo it. Bounded (#147 r3 finding 2): after FORCE_NEW_FAIL_ESCAPE_N
+     * opens that upgraded but never reached `session_ready`, the intent is dropped
+     * and the next open resolves by attach/default — otherwise a sustained
+     * `CONCURRENCY_LIMIT_EXCEEDED` would retry forever on the client side (every
+     * 101 resets `reconnectAttempt`, so `maxRetries` never fires).
+     * What the cap bounds is **client retries, not server cost**: a rejected open
+     * mints **zero** server-side sessions — gateway's `SessionManager.createSession`
+     * calls `concurrencyGate.acquire()` first and throws `ConcurrencyLimitError`
+     * before `createSessionInner()` ever runs, so orphans stay at 0.
+     * B1-freeness (no orphan always-on container) is a gateway invariant, not this
+     * call's responsibility.
+     * Resolves on `onopen` (before `session_ready`). Frames the host enqueues after
+     * this call are for the NEW session: the cross-session outbox gate only drops
+     * entries enqueued before it (#147 r3 finding 4).
      */
     startNewSession(opts?: TokenProviderOpts): Promise<void>;
     /**

package/dist/client/gateway-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-client.d.ts","sourceRoot":"","sources":["../../src/client/gateway-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gateway-client.d.ts","sourceRoot":"","sources":["../../src/client/gateway-client.ts"],"names":[],"mappings":"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"}

package/dist/client/gateway-client.js

@@ -7,6 +7,62 @@ import { readTokenSubject } from './token-subject.js';
  * heartbeat, token-refresh signalling, and event dispatch. Does not own any
  * state — everything flows out via the callbacks.
  */
+/**
+ * attach 逃生口阈值：连续 N 次「带 attach 打开了 socket、却始终没等到 `session_ready`」
+ * 之后，下一次开连接丢掉 attach 按 gateway 默认解析。
+ * 🔴 #147 r2 finding 3：判据是「**开了但没 ready**」，不是「从未 open」——
+ *  · owner-proxy 关的是**已打开**的 socket（1013），客户端已见过 onopen ⇒ 按「从未 open」
+ *    数永远到不了阈值，逃生口对它要救的场景是死代码；
+ *  · 反过来 TCP/DNS 失败全是「从未 open」，一次 wifi 抖动 ~7-14 秒就能凑够三次 ⇒
+ *    第一次成功重连不带 sessionId → gateway 默认解析 → **tab 2 落进 tab 1 的 session**，
+ *    正是这个 feature 要防的。
+ */
+const ATTACH_FAIL_ESCAPE_N = 3;
+/**
+ * forceNew 逃生口阈值（#147 r3 finding 2，与 attach 对称）：new 意图钉到 `session_ready`
+ * 才兑现是对的（r2 finding 1），但没有上限就是无界——持续 `CONCURRENCY_LIMIT_EXCEEDED` 下
+ * open→101→拒→close→重连带 new=1→gateway 再 createSession→…，而 onopen 每次 101 都把
+ * `reconnectAttempt` 清零，maxRetries 永不触发。连续 N 次「带 new=1 打开了 socket、却没等到
+ * session_ready」之后，丢掉 new 意图按默认（attach/复用）解析。
+ * ⚠️ 这个上限封的是**客户端重试次数**，不是服务端成本 —— `CONCURRENCY_LIMIT_EXCEEDED`
+ * 这一路**服务端零 session**：gateway 的 `SessionManager.createSession` 先
+ * `concurrencyGate.acquire()`，`!decision.allowed` 当场 throw `ConcurrencyLimitError`，
+ * `createSessionInner()` **从未被调用**（optima-gateway
+ * `packages/session-manager/src/session-manager.ts` 的 `createSession`）。
+ * ⇒ 孤儿 session 恒为 0，不占并发预算，也没有「等 idle-suspend 才释放」这回事。
+ * 之所以仍要封口，是因为**无界重连本身**是 bug：onopen 每次 101 都把 `reconnectAttempt`
+ * 清零 ⇒ `maxRetries` 永不触发，客户端会永远转下去。
+ */
+const FORCE_NEW_FAIL_ESCAPE_N = 3;
+/**
+ * #147 r3 finding 1：`new URL(gatewayUrl)` 对**相对地址**（`'/ws'`）无 base 直接抛，而改前的
+ * 字符串拼接交给浏览器 WebSocket 是能解析相对地址的（BC）。解析顺序：
+ *  1. 绝对地址 → 原样；
+ *  2. 相对地址 + 浏览器有 `location` → 按 `location.href` 解析，http(s) 换成 ws(s)
+ *     （浏览器 WebSocket 内部就是这么做的，只是提前做掉，兼容不接受 http(s) 的老实现）；
+ *  3. 相对地址 + 无 `location`（Node/SSR）→ 用占位 base 解析后剥掉占位 origin，保留相对形态
+ *     交给 WebSocket 构造器（与改前一致：能不能连由宿主运行时决定）。
+ * 抛错只剩「真畸形」（如 `wss://[bad`），由调用方的 catch 按连接失败收口。
+ */
+function resolveGatewayUrl(gatewayUrl) {
+    try {
+        return { url: new URL(gatewayUrl), relativePrefix: null };
+    }
+    catch {
+        /* 相对地址或畸形：往下走 */
+    }
+    const loc = globalThis.location?.href;
+    if (typeof loc === 'string' && loc.length > 0) {
+        const url = new URL(gatewayUrl, loc);
+        if (url.protocol === 'http:')
+            url.protocol = 'ws:';
+        else if (url.protocol === 'https:')
+            url.protocol = 'wss:';
+        return { url, relativePrefix: null };
+    }
+    const placeholder = 'ws://relative.invalid';
+    return { url: new URL(gatewayUrl, placeholder), relativePrefix: placeholder };
+}
 export class GatewayClient {
     options;
     ws = null;
@@ -29,14 +85,53 @@ export class GatewayClient {
      */
     connecting = false;
     /**
-     * One-shot flag: when set, the *next* socket open appends `new=1` so the
-     * gateway takes the `createSession` path (COO toggle ENTER/EXIT, #467/#1076).
-     * Consumed (reset to false) as soon as the URL is built, so it never leaks
-     * into subsequent auto-reconnects — a leaked `new=1` would spawn a fresh
-     * session (and, pre gateway drain-on-createSession invariant, an orphan) on
-     * every unexpected disconnect. Set via startNewSession().
+     * When set, socket opens append `new=1` so the gateway takes the
+     * `createSession` path (COO toggle ENTER/EXIT #467/#1076; gw#2313 "give me a
+     * fresh session"). Set via startNewSession().
+     * Consumed on the next **`session_ready`**, NOT when the URL is built and NOT
+     * on `onopen` (#147 r2 finding 1: `onopen` is only the HTTP 101 upgrade; the
+     * gateway rejects — `CONCURRENCY_LIMIT_EXCEEDED`, `AUTH_TOKEN_INVALID` — over
+     * the already-open socket). So it **deliberately survives failed opens and
+     * flows into auto-reconnect**: that leak IS the fix — do not "tidy" it back
+     * to consume-on-build, that re-introduces the silent fall-back to the session
+     * the caller just asked to leave. Bounded by FORCE_NEW_FAIL_ESCAPE_N (#147 r3
+     * finding 2): after N opens that upgraded but never reached `session_ready`
+     * the intent is dropped and the next open resolves by attach/default.
      */
     forceNewNextConnect = false;
+    /** r1（#147 🟠4）：上一次 session_ready 报的 sessionId——跨 session 闸的判据。 */
+    lastReadySessionId = null;
+    /**
+     * r1（#147 🟡）：带 attach 的 open 连续失败计数——owner-proxy 预路由拒连时（1013 循环），
+     * 每次重连都带同一个 sessionId 会撞同一判定直到重试耗尽。连续 ≥3 次失败后，下一次
+     * open 丢掉 attach id 按默认解析（gateway 本地可服务），成功后清零恢复 attach。
+     * r3 🟡：按 id 归键——宿主换了**新的有效 id** 时计数归零，不会因为旧 id 的失败被丢一轮。
+     * attach id 来源两种：provider 供的，或 README 临时通路烤在 `gatewayUrl` 里的 `?sessionId=`
+     * （r3 finding 3：后者也必须计 streak + 可删，否则 owner-proxy 1013 循环对它无界）。
+     */
+    attachFailStreak = { id: null, count: 0 };
+    /** 本次 open 是否带了 attach id（失败时归因给 streak 用）。 */
+    lastOpenHadAttach = false;
+    /** #147 r3 finding 2：带 new=1 的 open 连续「已 open 但没 ready」计数（见 FORCE_NEW_FAIL_ESCAPE_N）。 */
+    forceNewFailStreak = 0;
+    /**
+     * #147 r3 finding 4：startNewSession() 那一刻的 outbox switch 纪元——new 意图活过失败 open
+     * 期间入队的帧都属于新 session，跨 session 闸只丢这个纪元之前的。随意图一起在 session_ready 清空。
+     */
+    forceNewEpoch = null;
+    /** 同上，attach 腿：宿主要求 attach 到与当前不同的 id 时的纪元（同 id 重试沿用）。 */
+    attachSwitch = null;
+    /**
+     * 🔴 #147 r2 finding 1/2/3 共用的一块状态：**本次 open 的寻址意图**。
+     * 消费点必须是 `session_ready` 而不是 `onopen` —— `onopen` 只是 HTTP 101 升级，
+     * gateway 的 `/ws` 是 `@fastify/websocket`，`handleWebSocket` 在 101 **之后**才跑，
+     * `CONCURRENCY_LIMIT_EXCEEDED` / `AUTH_TOKEN_INVALID` 都是通过**已打开的 socket**
+     * 发来的。在 onopen 消费 = 点「新建」→ 101 → 意图蒸发 → 上限错误关闭 → 重连带
+     * `sessionId=ses_old` → 静默回到刚要离开的那个 session。
+     */
+    pendingOpenIntent = null;
+    /** 当前 socket 的「见过 session_ready」回写钩子（随连接作用域创建/清空）。 */
+    readyFlagForCurrentSocket = null;
     /**
      * `sub` of the token the CURRENT socket was opened with — the principal this
      * connection is bound to, since the gateway resolves the session from the
@@ -188,6 +283,14 @@ export class GatewayClient {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        // #147 r3 🟡：寻址意图/逃生计数不活过显式 disconnect——登出再登入不该带着旧的
+        // 「新建」意图去铸 session，也不该带着上个身份的 attach 失败计数把新 id 丢一轮。
+        this.forceNewNextConnect = false;
+        this.forceNewEpoch = null;
+        this.forceNewFailStreak = 0;
+        this.attachFailStreak = { id: null, count: 0 };
+        this.attachSwitch = null;
+        this.pendingOpenIntent = null;
         if (this.ws) {
             // Reject pending switch_config waiters HERE, not from onclose: a real
             // browser fires onclose asynchronously, by which time this.ws is
@@ -338,14 +441,42 @@ export class GatewayClient {
     }
     /**
      * Force a brand-new gateway session: appends `new=1` to the next connect URL
-     * (→ gateway `createSession` instead of resolve/reuse) and reconnects. Used by
-     * the COO toggle (ENTER/EXIT, #467/#1076) — mode is baked at session creation,
-     * so switching it requires a fresh session. One-shot: the flag is consumed on
-     * the next open, so it never leaks into auto-reconnect. B1-freeness (no orphan
-     * always-on container) is a gateway invariant, not this call's responsibility.
+     * (→ gateway `createSession` instead of resolve/reuse) and reconnects.
+     * ⚠️ This MOVES the client to a fresh session — it does not open an
+     * additional one (one GatewayClient holds exactly one socket/session; a
+     * multi-session host runs one client per tab/instance). The abandoned
+     * session is NOT released server-side: it stays alive (own container,
+     * counted by `GET /api/sessions/concurrency`) until idle-suspend/TTL —
+     * repeated calls can hit the concurrency limit (gw#2315 default 10).
+     * **General-purpose primitive** (gw#2313): any caller that wants a fresh
+     * session uses this, and the COO
+     * toggle (ENTER/EXIT, #467/#1076) uses it because mode is baked at session
+     * creation. Takes precedence over `sessionAttachProvider` for its one open.
+     * One-shot, but **deliberately survives failed opens**: the flag is consumed on
+     * the next `session_ready`, not on `onopen` (#147 r2 finding 1). So if the first
+     * attempt is rejected *after* the 101 upgrade — gw#2315 concurrency limit,
+     * `AUTH_TOKEN_INVALID`, any drop between 101 and `session_ready` — auto-reconnect
+     * keeps retrying with `new=1` instead of silently attaching back to the session
+     * the caller just asked to leave. That "leak into auto-reconnect" **is** the fix;
+     * do not undo it. Bounded (#147 r3 finding 2): after FORCE_NEW_FAIL_ESCAPE_N
+     * opens that upgraded but never reached `session_ready`, the intent is dropped
+     * and the next open resolves by attach/default — otherwise a sustained
+     * `CONCURRENCY_LIMIT_EXCEEDED` would retry forever on the client side (every
+     * 101 resets `reconnectAttempt`, so `maxRetries` never fires).
+     * What the cap bounds is **client retries, not server cost**: a rejected open
+     * mints **zero** server-side sessions — gateway's `SessionManager.createSession`
+     * calls `concurrencyGate.acquire()` first and throws `ConcurrencyLimitError`
+     * before `createSessionInner()` ever runs, so orphans stay at 0.
+     * B1-freeness (no orphan always-on container) is a gateway invariant, not this
+     * call's responsibility.
+     * Resolves on `onopen` (before `session_ready`). Frames the host enqueues after
+     * this call are for the NEW session: the cross-session outbox gate only drops
+     * entries enqueued before it (#147 r3 finding 4).
      */
     async startNewSession(opts) {
         this.forceNewNextConnect = true;
+        this.forceNewFailStreak = 0;
+        this.forceNewEpoch = this.delivery.bumpEpoch();
         await this.reconnect(opts);
     }
     /**
@@ -626,14 +757,112 @@ export class GatewayClient {
         // is what that state wants anyway) and a "same" verdict sends onto a closed
         // socket, where send() returns false as a noop.
         this.connectedSub = readTokenSubject(token);
-        const separator = this.options.gatewayUrl.includes('?') ? '&' : '?';
-        let url = `${this.options.gatewayUrl}${separator}token=${encodeURIComponent(token)}`;
-        // One-shot forceNew (COO toggle): consume the flag as we build the URL so it
-        // applies to exactly this open and never leaks into an auto-reconnect.
-        if (this.forceNewNextConnect) {
-            this.forceNewNextConnect = false;
-            url += '&new=1';
+        // r1（#147 🔴3）：URL 一律经 `new URL()` + searchParams 构造——手搓字符串拼接在
+        // gatewayUrl 自带 query（临时通路 `?sessionId=`）时会发出重复参数，而 gateway 的
+        // `searchParams.get()` 取第一个 ⇒ `startNewSession()` 发出 `?sessionId=X&new=1`
+        // 时 attach 反而压过 new，本 PR 的核心不变量在 README 自己推荐的路径上失效。
+        // set/delete 语义天然去重，顺带修掉 gatewayUrl 带 fragment 时 query 落进 fragment。
+        // r1（#147 🟠5）+ r2：try/catch 必须罩住**整段** —— r1 只罩了 provider 调用本身，
+        // 而 `attachId?.trim()`（provider 返回非字符串时 TypeError）和
+        // `new URL(this.options.gatewayUrl)`（宿主传了畸形 url）都在守卫之外。抛在这里会落在
+        // `connecting=false` 之后、disown 置空 `this.ws` 之前 ⇒ **永久卡在 reconnecting**，
+        // 与 r1 finding 5 的形态一字不差。
+        let url;
+        let intent;
+        try {
+            // r3 finding 1：相对 gatewayUrl（'/ws'）必须给 base，否则 new URL() 直接抛（改前的
+            // 字符串拼接是能连的 —— BC）。见 resolveGatewayUrl。
+            const { url: wsUrl, relativePrefix } = resolveGatewayUrl(this.options.gatewayUrl);
+            wsUrl.hash = '';
+            wsUrl.searchParams.set('token', token);
+            // 🔴 r2：`lastOpenHadAttach` 无条件先置 false —— r1 只在 else 分支重置，
+            // forceNew 那次会**继承上次的值**，把自己的失败记进 attach streak。
+            this.lastOpenHadAttach = false;
+            let attachForThisOpen = null;
+            let switchEpoch = null;
+            // r3 finding 2：forceNew 逃生口 —— 连续 N 次带 new=1 已 open 却没 ready，丢掉意图，
+            // 本次按 attach/默认解析（否则持续上限拒绝下客户端无限重连——服务端零 session）。
+            if (this.forceNewNextConnect && this.forceNewFailStreak >= FORCE_NEW_FAIL_ESCAPE_N) {
+                this.forceNewNextConnect = false;
+                this.forceNewEpoch = null;
+                this.forceNewFailStreak = 0;
+            }
+            if (this.forceNewNextConnect) {
+                wsUrl.searchParams.delete('sessionId');
+                wsUrl.searchParams.set('new', '1');
+                switchEpoch = this.forceNewEpoch;
+            }
+            else {
+                wsUrl.searchParams.delete('new'); // 防 gatewayUrl 自带残留的 new=1 漏进重连
+                // gw#2313 S1 — attach addressing: pin this open to an exact session.
+                let attachId;
+                try {
+                    attachId = this.options.sessionAttachProvider?.();
+                }
+                catch {
+                    attachId = null;
+                }
+                // 空串/空白当「没配」（getItem 残留空值常见）；r3 finding 1：非字符串（JSON.parse 出的
+                // 数字/对象）同样归一为「没配」，README「按无 attach 处理」的承诺才对所有形态成立。
+                const trimmed = typeof attachId === 'string' ? attachId.trim() : '';
+                // r3 finding 3：attach id 的候选 = provider 供的，否则 gatewayUrl 自带的（临时通路）。
+                // 两种来源同一套 streak/逃生口 —— 否则纯 baked-URL 宿主在 owner-proxy 1013 循环里
+                // streak 永远不涨、id 永远不删，而每次 101 又把 maxRetries 清零 ⇒ 无界。
+                const candidate = trimmed || wsUrl.searchParams.get('sessionId')?.trim() || null;
+                // r3 🟡：streak 按 id 归键——换了新的有效 id 从零计。
+                if (candidate !== this.attachFailStreak.id) {
+                    this.attachFailStreak = { id: candidate, count: 0 };
+                }
+                if (candidate && this.attachFailStreak.count < ATTACH_FAIL_ESCAPE_N) {
+                    wsUrl.searchParams.set('sessionId', candidate);
+                    this.lastOpenHadAttach = true;
+                    attachForThisOpen = candidate;
+                    // 宿主要求 attach 到与当前不同的 session = 一次 switch 请求（跨 session 闸的纪元锚点）。
+                    // 同一个 id 的重试沿用同一纪元：重试期间入队的帧仍算「请求之后」。
+                    if (candidate !== this.lastReadySessionId) {
+                        if (this.attachSwitch?.id !== candidate) {
+                            this.attachSwitch = { id: candidate, epoch: this.delivery.bumpEpoch() };
+                        }
+                        switchEpoch = this.attachSwitch.epoch;
+                    }
+                }
+                else {
+                    // 逃生口生效（或根本没 id）：本次按 gateway 默认解析。
+                    // 🔴 r2：**必须一并删掉 gatewayUrl 自带的 sessionId** —— README 的临时通路把
+                    // attach id 烤在 url 里，不删的话逃生口形同虚设（照样进 owner-proxy 预路由）。
+                    wsUrl.searchParams.delete('sessionId');
+                }
+            }
+            intent = { forceNew: this.forceNewNextConnect, attachId: attachForThisOpen, switchEpoch };
+            url = relativePrefix !== null
+                ? wsUrl.toString().slice(relativePrefix.length)
+                : wsUrl.toString();
         }
+        catch (err) {
+            // 构不出 URL = 这次连接根本发不出去。按「连接失败」收口，绝不让异常穿过
+            // connecting=false 之后的窗口。
+            // 🔴 r3 finding 1：这条路径从没构造出 socket、永远到不了 onclose，maxRetries 检查
+            // 必须在这里自己做 —— r2 的版本无条件 scheduleReconnect + rethrow：reconnectAttempt
+            // 无界增长、永不 reconnect_exhausted、outbox 永无终态，定时器里的 `void openSocket()`
+            // 每 tick 一个 unhandled rejection（Node/SSR 宿主直接挂）。不再 rethrow：与 onclose
+            // 路径一致，调用方通过 onConnectionStateChange / onError 观察。
+            this.connecting = false;
+            const message = err instanceof Error ? err.message : String(err);
+            if (this.reconnectAttempt >= this.reconnectConfig.maxRetries) {
+                this.options.onConnectionStateChange('disconnected');
+                this.delivery.onConnTerminal();
+                this.options.onError({
+                    code: 'reconnect_exhausted',
+                    message: `WebSocket reconnect retries exhausted (connect URL invalid: ${message})`,
+                    retryable: false,
+                });
+                return;
+            }
+            this.options.onConnectionStateChange('reconnecting');
+            this.scheduleReconnect();
+            return;
+        }
+        this.pendingOpenIntent = intent;
         // #99: disown any previous socket BEFORE creating its replacement. Multiple
         // reconnect entrances (onclose backoff timer, token refresh, heartbeat
         // recovery) can race into openSocket; without this the superseded socket
@@ -676,11 +905,21 @@ export class GatewayClient {
             // under the disown above — any path that replaces this.ws without
             // detaching (future refactors included) still can't double-feed the
             // store or trigger ghost reconnects from a superseded socket.
+            // 声明在赋值它的闭包**之前**（r2 小项：r1 写在 onopen 之后，靠 hoisting 才不炸）。
+            let everOpened = false;
+            let sawReady = false;
+            this.readyFlagForCurrentSocket = () => { sawReady = true; };
             ws.onopen = () => {
                 if (this.ws !== ws) {
                     resolve();
                     return;
                 }
+                everOpened = true;
+                // 🔴 #147 r2 finding 1：**这里不消费任何寻址意图**。onopen 只是 HTTP 101 升级，
+                // gateway 的 handleWebSocket 在 101 之后才跑，CONCURRENCY_LIMIT_EXCEEDED /
+                // AUTH_TOKEN_INVALID 都是通过已打开的 socket 发来的。在这里消费 =
+                // 点「新建」→ 101 → 意图蒸发 → 上限错误关闭 → 重连带 sessionId=ses_old →
+                // 静默回到刚要离开的 session。消费点是 `session_ready`（见 handleEvent）。
                 if (this.reconnectAttempt !== 0) {
                     this.reconnectAttempt = 0;
                     this.options.onReconnectAttempt?.(0);
@@ -709,6 +948,19 @@ export class GatewayClient {
                     return;
                 }
                 this.stopHeartbeat();
+                // 🔴 #147 r2 finding 3：计数判据 = 「**开了但从没等到 session_ready**」+ 带 attach。
+                // 这正好覆盖 owner-proxy 1013 与 101↔session_ready 之间的各类拒绝，
+                // 又把 TCP/DNS 失败（从未 open）排除在外——后者是网络问题，不是寻址问题，
+                // 拿它去触发逃生口会把 tab 2 甩进 tab 1 的 session。
+                if (everOpened && !sawReady) {
+                    if (this.lastOpenHadAttach)
+                        this.attachFailStreak.count++;
+                    // r3 finding 2：forceNew 同判据计数（101 后被拒——服务端零 session，见 FORCE_NEW_FAIL_ESCAPE_N 注释）。
+                    if (intent.forceNew)
+                        this.forceNewFailStreak++;
+                }
+                this.pendingOpenIntent = null; // 本次 open 的意图随连接作用域作废（未兑现）
+                this.readyFlagForCurrentSocket = null;
                 // gw#1587：断连边沿——in-flight ack 等待作废回 pending（重连 armed 后全量 drain 重投）；
                 // stale 10s 计时器随连接作用域取消（防跨连接误兜底）。
                 this.cancelArmTimer();
@@ -765,6 +1017,44 @@ export class GatewayClient {
         // 未 retry 的兜底 failed 条目）；不带信号 → 维持 disarmed（幂等）。
         if (event.type === 'session_ready') {
             this.cancelArmTimer();
+            // r1（#147 🟠4）：跨 session 闸——本连接解析到了**不同的 session**（startNewSession /
+            // attach id 改写 / 旧 session 被回收后 attach 落空）时，旧 session 的待发帧不得
+            // 灌进新容器（帧里带着旧 conversation_id）。对齐 foreign-principal 闸的处置顺序：
+            // 先 conn_terminal（宿主拿到每条的终态 failed）再 dropAll——且必须在下方
+            // onArmedDecision 之前，armed 恢复腿才不会把旧帧复活重投。同 session 重连不受影响。
+            const readySessionId = event.session?.sessionId;
+            const intent = this.pendingOpenIntent;
+            // 🔴 #147 r2 finding 1：**寻址意图在这里才算兑现**。走到 session_ready 说明
+            // gateway 真的按本次 URL 建/接上了会话；在 onopen（101）消费会让上限拒绝、
+            // 鉴权失败这类「已 open 再拒」把用户的「新建」意图静默吃掉。
+            this.readyFlagForCurrentSocket?.();
+            this.forceNewNextConnect = false;
+            this.forceNewEpoch = null;
+            this.forceNewFailStreak = 0;
+            this.attachFailStreak.count = 0;
+            this.attachSwitch = null;
+            this.pendingOpenIntent = null;
+            // 🔴 #147 r2 finding 2：跨 session 闸必须**同时**满足「换了 session」和
+            // 「客户端确实要求换」。r1 只看前者 ⇒ 没配 attach 的宿主（今天的 agentic-chat
+            // 生产）断网期间 session 被回收、重连拿到新 id，两条 retry 通道被 dropAll 一起杀掉，
+            // 而改前它们会在下次 armed drain 重投。抄的 principal-switch 先例不能平移：
+            // conversation 是 **user 域**的（connection-handler 的 getConversationsForUser），
+            // `conv-A` 在新 session 里仍可恢复 —— 这些帧是可投递的，不是毒。
+            const hostAskedToSwitch = intent?.forceNew === true
+                || (intent?.attachId != null && intent.attachId !== this.lastReadySessionId);
+            if (hostAskedToSwitch
+                && this.lastReadySessionId && readySessionId
+                && readySessionId !== this.lastReadySessionId) {
+                // r3 finding 4：只丢 switch 请求**之前**入队的（epoch < switchEpoch）。startNewSession()
+                // 在 onopen 就 resolve，宿主随即重新启用输入框——此后到 session_ready 之间用户发的帧
+                // 是为新 session 写的，可投递，不是毒。switchEpoch 为 null（理论上不会：hostAskedToSwitch
+                // 为真时两条腿都设了）则退回全丢。
+                const epochBelow = intent?.switchEpoch ?? undefined;
+                this.delivery.onConnTerminal(epochBelow);
+                this.delivery.dropAll(epochBelow);
+            }
+            if (readySessionId)
+                this.lastReadySessionId = readySessionId;
             const supports = event.session?.supportsMessageReceipt === true;
             this.deliveryArmState = supports ? 'armed' : 'disarmed';
             this.delivery.onArmedDecision(supports, 'session_ready');