@securecoms/agent-bridge 0.30.0 → 0.30.2

package/dist/index.js

@@ -17457,7 +17457,13 @@ var CODES = [
   // lookup missed and before any write, so a retry can never land: the
   // pending commit is dropped instead of being resent forever. The same pair
   // answers an application send into a deleted channel (#325 F5).
-  { status: 409, code: "channel_unavailable" }
+  { status: 409, code: "channel_unavailable" },
+  // ADR-0023 B.1: an Add or Welcome into a humans-only enclave's group naming
+  // a device that is not provably a person's. Refused after the replay lookup
+  // missed and before any write, so nothing landed. Definite: the committer's
+  // work cannot name an agent in a humans-only enclave (admission refuses
+  // one), so dropping the commit starts no resend loop.
+  { status: 403, code: "humans_only_enclave" }
 ];
 var DISTRIBUTE_DEFINITE_CODES = Object.freeze(CODES.map((c) => Object.freeze({ ...c })));
 var DEFINITE_KEYS = new Set(DISTRIBUTE_DEFINITE_CODES.map((c) => `${c.status} ${c.code}`));
@@ -24091,6 +24097,7 @@ function base64UrlNoPad(s) {
 }
 var BEARER_SUBPROTOCOL = "securecoms.bearer.v1";
 var WS_CLOSE_IDENTITY_REVOKED = 4006;
+var WS_CLOSE_SESSION_SUPERSEDED = 4409;
 function isIdentityRevokedClose(code, reason) {
   return code === WS_CLOSE_IDENTITY_REVOKED || reason === "identity_revoked";
 }
@@ -24306,7 +24313,7 @@ function openDeliveryPings(o) {
         end();
       };
       if (!hardened) {
-        if (code === 4001 || isIdentityRevokedClose(code, reason)) {
+        if (code === 4001 || code === WS_CLOSE_SESSION_SUPERSEDED || isIdentityRevokedClose(code, reason)) {
           terminalClose();
           return;
         }
@@ -24315,7 +24322,7 @@ function openDeliveryPings(o) {
       }
       const tr = terminalReason;
       terminalReason = void 0;
-      if (code === 4006 || tr && code === 4001) {
+      if (code === 4006 || code === WS_CLOSE_SESSION_SUPERSEDED || tr && code === 4001) {
         lifecycle("terminal", tr ?? `code ${code}`);
         terminalClose();
         return;
@@ -24472,10 +24479,14 @@ var RestTransport = class {
   f;
   ws;
   tokenProvider;
-  /** The most recent device-wide WS send handle, captured on subscribe and
-   * cleared on its close. Control frames (status keepalive) route through it;
-   * a no-op when no subscription is active. */
+  /** The shared delivery-ping socket's send, set while that socket is open and
+   * cleared when it closes (last subscriber gone, or terminal). Control frames
+   * (status keepalive) route through it; a no-op when no subscription is active. */
   _controlSend = null;
+  /** P-5: the one delivery-ping stream this transport holds, shared by every subscriber. */
+  pingHub = null;
+  /** Set once the shared stream ends on a terminal close; no socket is ever reopened. */
+  pingsTerminal = false;
   constructor(opts) {
     this.opts = opts;
     this.f = opts.fetchImpl ?? fetch;
@@ -24577,25 +24588,52 @@ var RestTransport = class {
       idempotentReplay: j.idempotent_replay === true
     };
   }
+  /** One device-wide delivery-ping socket per transport (P-5): the backend
+   * supersedes a second socket for the same device, so every subscriber shares
+   * one `openDeliveryPings` handle. Each gets its own bounded queue; its close()
+   * detaches only itself; the socket closes with the last subscriber and a later
+   * subscribe opens a fresh one. After a terminal close the transport is
+   * terminal: later calls open no socket and get an already-ended iterator. */
   subscribeDeliveryPings(_channelId) {
+    if (this.pingsTerminal) {
+      const ended = new PingSubscriber();
+      ended.end();
+      return { pings: ended.pings, close: () => {
+      }, send: () => {
+      } };
+    }
+    const hub = this.pingHub ??= this.openPingHub();
+    const sub = hub.attach();
+    return { pings: sub.pings, close: () => hub.detach(sub), send: hub.send };
+  }
+  openPingHub() {
     let wsUrl = this.opts.baseUrl.replace(/^http/, "ws").replace(/\/$/, "") + "/api/v1/ws";
     if (this.opts.connectIdentityId) {
       wsUrl += `?connect_identity_id=${encodeURIComponent(this.opts.connectIdentityId)}`;
     }
-    const handle = openDeliveryPings({
+    const hub = new PingHub(openDeliveryPings({
       url: wsUrl,
       tokenProvider: this.tokenProvider,
       wsImpl: this.ws,
       hardened: this.opts.hardenedReconnect ?? false,
-      onLifecycle: this.opts.onWsLifecycle
-    });
-    this._controlSend = handle.send;
-    const close = () => {
-      if (this._controlSend === handle.send)
-        this._controlSend = null;
-      handle.close();
-    };
-    return { pings: handle.pings, close, send: handle.send };
+      onLifecycle: this.opts.onWsLifecycle,
+      // Any terminal close (4001, 4006, 4409, hardened war-cap) of the shared
+      // socket makes this transport terminal. The shared iterator ends right
+      // after this call, so the pump exit tears down every subscriber.
+      onTerminalClose: (close) => {
+        this.pingsTerminal = true;
+        this.opts.onTerminalClose?.(close);
+      }
+    }), () => this.dropPingHub(hub));
+    this._controlSend = hub.send;
+    return hub;
+  }
+  dropPingHub(hub) {
+    if (this.pingHub === hub) {
+      this.pingHub = null;
+      this._controlSend = null;
+    }
+    hub.shutdown();
   }
   sendControlFrame(_channelId, frame) {
     try {
@@ -24623,6 +24661,90 @@ var RestTransport = class {
     }));
   }
 };
+var SUBSCRIBER_QUEUE_MAX = 8;
+var PingSubscriber = class {
+  queue = [];
+  waiter;
+  ended = false;
+  started = false;
+  pings = {
+    [Symbol.asyncIterator]: () => {
+      if (this.started)
+        throw new Error("subscribeDeliveryPings: single-use async iterable");
+      this.started = true;
+      return {
+        next: () => {
+          if (this.ended)
+            return Promise.resolve({ value: void 0, done: true });
+          if (this.queue.length)
+            return Promise.resolve({ value: this.queue.shift(), done: false });
+          return new Promise((resolve) => {
+            this.waiter = resolve;
+          });
+        }
+      };
+    }
+  };
+  push(p) {
+    if (this.ended)
+      return;
+    if (this.waiter) {
+      const w = this.waiter;
+      this.waiter = void 0;
+      w({ value: p, done: false });
+    } else if (this.queue.length < SUBSCRIBER_QUEUE_MAX) {
+      this.queue.push(p);
+    }
+  }
+  end() {
+    this.ended = true;
+    this.queue.length = 0;
+    if (this.waiter) {
+      const w = this.waiter;
+      this.waiter = void 0;
+      w({ value: void 0, done: true });
+    }
+  }
+};
+var PingHub = class {
+  handle;
+  onGone;
+  subs = /* @__PURE__ */ new Set();
+  send;
+  constructor(handle, onGone) {
+    this.handle = handle;
+    this.onGone = onGone;
+    this.send = handle.send;
+    void this.pump();
+  }
+  /** `openDeliveryPings` iterables never reject and push() never throws, so
+   * this loop only ends when the shared stream ends (our close, or terminal). */
+  async pump() {
+    for await (const p of this.handle.pings)
+      for (const s of this.subs)
+        s.push(p);
+    this.onGone();
+  }
+  attach() {
+    const s = new PingSubscriber();
+    this.subs.add(s);
+    return s;
+  }
+  /** Idempotent: detaches and ends only `s`; the last one out closes the socket. */
+  detach(s) {
+    this.subs.delete(s);
+    s.end();
+    if (this.subs.size === 0)
+      this.onGone();
+  }
+  /** Idempotent: `openDeliveryPings().close()` is, and the set is empty after. */
+  shutdown() {
+    for (const s of this.subs)
+      s.end();
+    this.subs.clear();
+    this.handle.close();
+  }
+};
 
 // ../connect-sdk-ts/dist/mls/rest-backend.js
 function describeType(v) {
@@ -34952,6 +35074,7 @@ var ROOM_DEFAULT_READ_GRANTS = Object.freeze([
   Object.freeze({ tool: "current_time", mode: "read" })
 ]);
 var NO_TOOL_GRANTS = Object.freeze([]);
+var WS_CLOSE_SESSION_SUPERSEDED2 = 4409;
 var OWNER_REPLAY_PRUNE_INTERVAL_MS = 5 * 60 * 1e3;
 var OWNER_TURN_UNCHECKED = Object.freeze({ kind: "unchecked" });
 function ownerDmDefaultGrantsEnabled(env = process.env) {
@@ -35226,6 +35349,12 @@ function rosterFreshAt(entry, heldEpoch, heldGroupId) {
 var RoomGrantEpochMovedError = class extends Error {
 };
 var ROOM_GRANT_TRACK_MAX = 4096;
+var SessionSupersededError = class extends Error {
+  constructor() {
+    super("session_superseded: another copy of this agent took its session during start()");
+    this.name = "SessionSupersededError";
+  }
+};
 var GroupSupersededSendError = class extends Error {
   constructor(channelId, activeGroupId) {
     super(`send refused for channel ${channelId}: the channel moved to a new secure group; not sent`);
@@ -35265,9 +35394,18 @@ var BridgeAgent = class _BridgeAgent {
     const seed = hexToBytes4(cfg.signingPrivateKey);
     this.custody = SoftwareKeyCustody.fromPrivateKey("ed25519", seed);
     this.replyIdKey = deriveReplyIdKey(seed);
+    const base = deps.fetchImpl ?? fetch;
+    this.fetchImpl = (input, init) => this.sessionSuperseded ? Promise.reject(new Error("session_superseded")) : base(input, init);
     this.transport = deps.transport ?? new RestTransport({
       baseUrl: cfg.apiBase,
       bearerToken: cfg.apiKey,
+      fetchImpl: this.fetchImpl,
+      wsImpl: deps.wsImpl,
+      // A 4409 close means another copy of this agent took the session.
+      // Every other terminal close keeps today's behaviour.
+      onTerminalClose: (close) => {
+        if (close.code === WS_CLOSE_SESSION_SUPERSEDED2) this.onSessionSuperseded();
+      },
       connectIdentityId: cfg.identityId,
       // P1b: hardened delivery-ping reconnect (verify-before-terminal +
       // half-open + wake + auth war-cap). On by default for the daemon;
@@ -35281,7 +35419,7 @@ var BridgeAgent = class _BridgeAgent {
         else writeServiceLog2("warn", "transport.delivery_ping_lifecycle_unknown");
       }
     });
-    this.backend = deps.backend ?? new RestMlsBackend({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey });
+    this.backend = deps.backend ?? new RestMlsBackend({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey, fetchImpl: this.fetchImpl });
     this.store = new SqliteMlsStateStore({
       dbPath: cfg.storePath,
       identityId: cfg.identityId,
@@ -35352,7 +35490,6 @@ var BridgeAgent = class _BridgeAgent {
       // throws (mirrors the divergence-heal signal path).
       onSupersedeUnopenable: (channelId, groupId) => this.healSupersedeUnopenable(channelId, groupId, this.drainExemptionAtCallIn())
     });
-    this.fetchImpl = deps.fetchImpl ?? fetch;
     this.home = deps.home ?? homedir4();
     this.grantWriters = {
       writeManifestPolicy: deps.grantWriters?.writeManifestPolicy ?? writeManifestPolicy,
@@ -35484,6 +35621,13 @@ var BridgeAgent = class _BridgeAgent {
   // stored for peek-then-join in ingestOnce
   custody;
   fetchImpl;
+  /** P-1: set once a 4409 close says another copy took this agent's session.
+   *  The gated fetch built in the constructor refuses every request after it. */
+  sessionSuperseded = false;
+  /** C9: who hears `session_superseded` (runMode's quiesce). */
+  sessionSupersededListeners = /* @__PURE__ */ new Set();
+  /** C9 (spec §4.1.6, low 3): the one close() run every caller shares. */
+  closing = null;
   /** Round 5: home for the managed runtime-config directory (test seam). */
   home;
   grantWriters;
@@ -35959,6 +36103,12 @@ var BridgeAgent = class _BridgeAgent {
   action;
   waiters = [];
   pingHandle;
+  /** C10 (P-15): the delivery-ping subscription start() opens at its top,
+   *  held unconsumed until startReceivePump() takes it. */
+  earlyPings = null;
+  /** C10 fix round 1: settles (never rejects) when start()'s body does; close()
+   *  awaits it, bounded, so the store never closes under a start() step. */
+  startInFlight = null;
   safetyTimer;
   /** The ingest cycle now running, if any (see ingestOnce: single-flight). */
   ingestInFlight = null;
@@ -36536,7 +36686,50 @@ var BridgeAgent = class _BridgeAgent {
       this.droppedMessages += overflow;
     }
   }
+  /**
+   * C10 (spec P-15, OQ-8 (b)): subscribe early, consume late. The
+   * delivery-ping socket opens here, before anything else, so this copy claims
+   * the device's session (and another copy gets its 4409) BEFORE this copy's
+   * boot drain runs. The pings it carries are NOT consumed until
+   * startReceivePump(), the same place as before: starting the pump first is
+   * still forbidden (DRAIN BEFORE ROTATE, startBody).
+   *
+   * A 4409 during start() (audit H-3): the gated fetch is already set (C9 step
+   * 0). start() then arms nothing more (supersededDuringStart before each
+   * timer and before the pump), runs the memoized close() quiesce, and rejects
+   * with SessionSupersededError. A step that FAILED because of the supersede
+   * (a refused fetch, a store the quiesce closed) is the same outcome.
+   */
   async start() {
+    const early = this.transport.subscribeDeliveryPings("");
+    this.earlyPings = early;
+    this.pingHandle = { close: early.close };
+    const body = this.startBody();
+    this.startInFlight = body.then(() => {
+    }, () => {
+    });
+    try {
+      await body;
+    } catch (e) {
+      if (!this.sessionSuperseded) {
+        if (this.earlyPings) {
+          this.earlyPings.close();
+          this.earlyPings = null;
+          this.pingHandle = void 0;
+        }
+        throw e;
+      }
+      if (!(e instanceof SessionSupersededError)) writeServiceLog2("warn", "startup.superseded_start_error", {}, e);
+      await this.close().catch(() => {
+      });
+      throw new SessionSupersededError();
+    }
+  }
+  /** C10: true once a 4409 landed; checked before each arming step of start(). */
+  supersededDuringStart() {
+    return this.sessionSuperseded;
+  }
+  async startBody() {
     this.startedAt = Date.now();
     await this.restoreRuntimeInbox();
     await this.loadToolGrantState();
@@ -36596,10 +36789,12 @@ var BridgeAgent = class _BridgeAgent {
     await this.warmRestoredNotes();
     await this.reindexRestoredTurns();
     if (this.unifiedOn) await this.reindexUnifiedRestored();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     this.runtimeConfigTimer = setInterval(() => {
       void this.refetchRuntimeConfig();
     }, 6 * 60 * 60 * 1e3);
     this.runtimeConfigTimer.unref?.();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     this.membershipSweepTimer = setInterval(() => {
       if (this.closingDown || this.membershipSweepWork) return;
       this.membershipSweepWork = this.runMembershipSweeps().finally(() => {
@@ -36607,6 +36802,7 @@ var BridgeAgent = class _BridgeAgent {
       });
     }, PURGE_SWEEP_INTERVAL_MS);
     this.membershipSweepTimer.unref?.();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     this.recallPruneTimer = setInterval(() => {
       if (this.closingDown || this.recallPruneWork) return;
       this.recallPruneWork = this.runRecallPruneTick().finally(() => {
@@ -36614,6 +36810,7 @@ var BridgeAgent = class _BridgeAgent {
       });
     }, 60 * 60 * 1e3);
     this.recallPruneTimer.unref?.();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     if (this.machinePaths) this.recallMaintenanceTimer = setInterval(() => {
       if (this.closingDown) return;
       const n = ++this.maintenanceTickN;
@@ -36624,6 +36821,7 @@ var BridgeAgent = class _BridgeAgent {
       });
     }, 1e3);
     this.recallMaintenanceTimer?.unref?.();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     this.startReceivePump();
     if (drainedInTime) {
       this.armSelfHealSweeps();
@@ -40887,7 +41085,8 @@ var BridgeAgent = class _BridgeAgent {
     }
   }
   startReceivePump() {
-    const sub = this.transport.subscribeDeliveryPings("");
+    const sub = this.earlyPings ?? this.transport.subscribeDeliveryPings("");
+    this.earlyPings = null;
     this.pingHandle = { close: sub.close };
     void (async () => {
       try {
@@ -42472,7 +42671,42 @@ ${channelId}`;
       build: BRIDGE_VERSION
     };
   }
-  async close() {
+  /** C9: `session_superseded` once a 4409 said another copy took this
+   *  agent's session (the gated fetch already refuses every request). The
+   *  local HTTP routes read it: every route but `/healthz` answers 503. */
+  get sessionState() {
+    return this.sessionSuperseded ? "session_superseded" : "live";
+  }
+  /** C9: subscribe to `session_superseded`. runMode subscribes right after
+   *  construction, before start(), so a 4409 during start() is heard too. */
+  on(event, listener) {
+    this.sessionSupersededListeners.add(listener);
+    return () => this.sessionSupersededListeners.delete(listener);
+  }
+  /** P-1 step 0, then the event (spec §4.1.6): another copy of this agent took
+   *  the session (4409). The gated-fetch switch is set FIRST, so no HTTP
+   *  request leaves the process after this, whatever a listener does. */
+  onSessionSuperseded() {
+    this.sessionSuperseded = true;
+    for (const listener of [...this.sessionSupersededListeners]) {
+      try {
+        listener();
+      } catch (e) {
+        writeServiceLog2("error", "transport.session_superseded_listener_failed", {}, e);
+      }
+    }
+  }
+  /**
+   * Idempotent (C9, spec §4.1.6 low 3): every call returns the FIRST call's
+   * promise, so a SIGTERM during or after the supersede quiesce never runs
+   * store.close() twice. A rejected close stays rejected: a retry would close
+   * the store a second time.
+   */
+  close() {
+    this.closing ??= this.closeOnce();
+    return this.closing;
+  }
+  async closeOnce() {
     this.closingDown = true;
     this.statusGate.close();
     for (const t of this.pauseRecheckTimers.values()) clearTimeout(t);
@@ -42485,6 +42719,28 @@ ${channelId}`;
     if (this.safetyTimer) clearInterval(this.safetyTimer);
     if (this.runtimeConfigTimer) clearInterval(this.runtimeConfigTimer);
     if (this.membershipSweepTimer) clearInterval(this.membershipSweepTimer);
+    const ingest = this.ingestInFlight;
+    if (ingest) {
+      let timer;
+      await Promise.race([
+        ingest.released,
+        new Promise((resolve) => {
+          timer = setTimeout(resolve, _BridgeAgent.GRACEFUL_DRAIN_MS);
+        })
+      ]);
+      if (timer) clearTimeout(timer);
+    }
+    const starting = this.startInFlight;
+    if (starting) {
+      let timer;
+      await Promise.race([
+        starting,
+        new Promise((resolve) => {
+          timer = setTimeout(resolve, _BridgeAgent.GRACEFUL_DRAIN_MS);
+        })
+      ]);
+      if (timer) clearTimeout(timer);
+    }
     if (this.membershipSweepWork) {
       let timer;
       await Promise.race([
@@ -42571,8 +42827,30 @@ ${channelId}`;
 import { readFileSync as readFileSync10, statSync as statSync5 } from "node:fs";
 import { dirname as dirname6, join as join18 } from "node:path";
 var REQUIRED = ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
+var CONFIG_ERROR_MESSAGE = {
+  credential_not_found: "credential file not found",
+  credential_unreadable: "credential file could not be read",
+  credential_not_json: "credential file is not valid JSON",
+  credential_missing_field: "credential file missing required field",
+  credential_voice_invalid: "credential file voice config invalid"
+};
+var ConfigError = class extends Error {
+  constructor(reason, field, source) {
+    super(CONFIG_ERROR_MESSAGE[reason] + (field ? `: ${field}` : ""));
+    this.reason = reason;
+    this.field = field;
+    this.source = source;
+    this.name = "ConfigError";
+  }
+};
 function loadConfig(opts) {
-  const raw = readFileSync10(opts.credentialPath, "utf8");
+  let raw;
+  try {
+    raw = readFileSync10(opts.credentialPath, "utf8");
+  } catch (e) {
+    const code = e?.code;
+    throw new ConfigError(code === "ENOENT" ? "credential_not_found" : "credential_unreadable");
+  }
   try {
     const mode = statSync5(opts.credentialPath).mode & 511;
     if (mode & 63) writeServiceLog2("warn", "config.credential_permissions_unsafe");
@@ -42582,9 +42860,9 @@ function loadConfig(opts) {
   try {
     json2 = JSON.parse(raw);
   } catch {
-    throw new Error("credential file is not valid JSON");
+    throw new ConfigError("credential_not_json");
   }
-  for (const k of REQUIRED) if (typeof json2[k] !== "string" || !json2[k]) throw new Error(`credential file missing required field: ${k}`);
+  for (const k of REQUIRED) if (typeof json2[k] !== "string" || !json2[k]) throw new ConfigError("credential_missing_field", k);
   const storePath = opts.storePath ?? join18(dirname6(opts.credentialPath), "bridge-state.db");
   const ownerGrantPin = loadOwnerGrantPin({ credentialPath: opts.credentialPath, credentialJson: json2 });
   writeServiceLog2(ownerGrantPin.state === "ok" || ownerGrantPin.state === "no_pin" ? "info" : "warn", "authz.pin", {
@@ -42622,8 +42900,14 @@ function loadConfig(opts) {
   let voice;
   try {
     voice = parseVoiceConfig(json2.voice, process.env);
-  } catch (e) {
-    throw new Error(`credential file voice config invalid: ${e.message}`);
+  } catch {
+    let source = "env";
+    try {
+      parseVoiceConfig(json2.voice, {});
+    } catch {
+      source = "file";
+    }
+    throw new ConfigError("credential_voice_invalid", void 0, source);
   }
   const modelSource = json2.memory?.model_source === "import_only" ? "import_only" : "download";
   const enabledRaw = json2.memory?.enabled;
@@ -42761,6 +43045,9 @@ var BRIDGE_ERRORS = {
   // longer holds the shared bytes or key. Terminal for that link: never fall
   // back to the current version. `detail.pin` names the refused pin.
   vault_ref_changed: { http: 422, message: "this file changed in Files after it was shared; not opened" },
+  // C9 (spec §4.1.6 step 1): another copy of this agent took its SecureComs
+  // session (WS 4409), so this copy stopped. Every local route but /healthz.
+  session_superseded: { http: 503, message: "another copy of this agent took its session; this copy stopped" },
   internal: { http: 500, message: "internal error" }
 };
 function errorBody(code, detail) {
@@ -42991,6 +43278,10 @@ function createHttpServer(agent, opts) {
       const url = new URL(req.url ?? "/", "http://localhost");
       const path = url.pathname;
       const method = req.method ?? "GET";
+      if (agent.sessionState === "session_superseded") {
+        if (method === "GET" && path === "/healthz") return json(res, 200, { state: "session_superseded" });
+        return jsonError(res, "session_superseded");
+      }
       if (method === "GET" && path === "/healthz") {
         return json(res, 200, { ...agent.health(), capabilities: capabilities(opts) });
       }
@@ -43202,6 +43493,7 @@ var PING_INTERVAL_MS = 3e4;
 var INFLIGHT_STALE_SWEEP_MS = 6e4;
 var INFLIGHT_STALE_AFTER_MS = 15 * 6e4;
 var HELLO_WAIT_MS = 2e3;
+var WS_CLOSE_SESSION_SUPERSEDED3 = 4409;
 var MEMORY_NOTES_FEATURE = "memory_notes";
 var MEMORY_RECALL_FEATURE = "memory_recall";
 var MEMORY_UNIFIED_FEATURE = "memory_unified";
@@ -43222,7 +43514,12 @@ function authedUpgrade(req, opts) {
   return true;
 }
 function attachAgentWebSocket(server, agent, opts) {
-  const wss = new WebSocketServer({ server, path: "/v1/ws" });
+  let sessionSuperseded = false;
+  const wss = new WebSocketServer({
+    server,
+    path: "/v1/ws",
+    verifyClient: (_info, done) => sessionSuperseded ? done(false, 503, "session_superseded") : done(true)
+  });
   const keepalive = setInterval(() => {
     for (const client of wss.clients) {
       const sock = client;
@@ -43362,6 +43659,7 @@ function attachAgentWebSocket(server, agent, opts) {
       if (helloTimer) clearTimeout(helloTimer);
       agent.noteSessionClose();
       unsubscribe();
+      if (sessionSuperseded) inflight.clear();
       if (inflight.size) {
         agent.requeueFailedRuntimeDeliveries(
           [...inflight.values()].filter((m) => !agent.isRuntimeMessageRetired(m.message_id))
@@ -43383,7 +43681,10 @@ function attachAgentWebSocket(server, agent, opts) {
     sock.on("close", cleanup);
     sock.on("error", cleanup);
     sock.on("message", (data) => {
-      void handleInbound(sock, agent, data, inflight, flush, session);
+      if (sessionSuperseded) return;
+      handleInbound(sock, agent, data, inflight, flush, session).catch((e) => {
+        writeServiceLog2("error", "ws.inbound_failed", {}, e);
+      });
     });
     flush();
   });
@@ -43398,6 +43699,13 @@ function attachAgentWebSocket(server, agent, opts) {
         }
       }
       wss.close();
+    },
+    /** C9 (spec §4.1.6 step 1, OQ-9): close every open socket with 4409 /
+     *  `session_superseded`, and answer every later upgrade with 503. The
+     *  runtime's reconnect backoff does the rest; idempotent. */
+    enterSessionSuperseded() {
+      sessionSuperseded = true;
+      for (const client of wss.clients) client.close(WS_CLOSE_SESSION_SUPERSEDED3, "session_superseded");
     }
   };
 }

package/dist/preflight-upgrade.d.cts

@@ -14,8 +14,6 @@ export interface UpgradeDeps {
     isTTY: boolean;
     stderr: (s: string) => void;
     ask: (q: string) => Promise<string>;
-    hasBrew: () => boolean;
-    runBrew: () => number;
     fetchText: (url: string) => Promise<string>;
     fetchBinary: (url: string, destPath: string) => Promise<void>;
     fileSha256: (p: string) => string;