@securecoms/agent-bridge 0.30.0 → 0.30.1

package/dist/bridge-agent.d.ts

@@ -353,6 +353,9 @@ export interface BridgeAgentDeps {
     transport?: any;
     backend?: any;
     fetchImpl?: typeof fetch;
+    /** TEST SEAM: WebSocket constructor for the real RestTransport's delivery-ping
+     *  socket. Production leaves it undefined (globalThis.WebSocket). */
+    wsImpl?: typeof WebSocket;
     /**
      * Round 5 (runtime config delivery): the home directory under which the
      * managed runtime-config directory lives. Injected only by tests, so they can
@@ -714,6 +717,15 @@ export declare class RoomClassChangedSendError extends SendForbiddenError {
  * `activeGroupId` is the group the backend named, or null when the channel has
  * no active group (fail closed: nothing to converge to).
  */
+/**
+ * C10 (spec P-15, §4.1.6): start() was superseded (4409) before it finished.
+ * start() has already run the memoized close() quiesce when this is thrown, and
+ * armed none of its timers or the receive pump. runMode catches it: the process
+ * stays alive holding the lock and the port, and serves no route.
+ */
+export declare class SessionSupersededError extends Error {
+    constructor();
+}
 export declare class GroupSupersededSendError extends Error {
     readonly channelId: string;
     readonly activeGroupId: string | null;
@@ -780,6 +792,13 @@ export declare class BridgeAgent {
     private readonly backend;
     private readonly custody;
     private readonly 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. */
+    private sessionSuperseded;
+    /** C9: who hears `session_superseded` (runMode's quiesce). */
+    private readonly sessionSupersededListeners;
+    /** C9 (spec §4.1.6, low 3): the one close() run every caller shares. */
+    private closing;
     /** Round 5: home for the managed runtime-config directory (test seam). */
     private readonly home;
     private readonly grantWriters;
@@ -1243,6 +1262,12 @@ export declare class BridgeAgent {
     readonly action: AgentActionAPI;
     private readonly waiters;
     private pingHandle?;
+    /** C10 (P-15): the delivery-ping subscription start() opens at its top,
+     *  held unconsumed until startReceivePump() takes it. */
+    private earlyPings;
+    /** 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. */
+    private startInFlight;
     private safetyTimer?;
     /** The ingest cycle now running, if any (see ingestOnce: single-flight). */
     private ingestInFlight;
@@ -1490,7 +1515,24 @@ export declare class BridgeAgent {
      * shed so a silently-dropping daemon stays observable (item 3 / ADR-0002).
      */
     private capBuffer;
+    /**
+     * 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.
+     */
     start(): Promise<void>;
+    /** C10: true once a 4409 landed; checked before each arming step of start(). */
+    private supersededDuringStart;
+    private startBody;
     /**
      * #811 L-1: send the re-Welcome signal ONCE for each channel whose onWedged
      * heal the boot drain refused. Runs after the drain settled and after the
@@ -3485,5 +3527,23 @@ export declare class BridgeAgent {
          * and zero on restart (spec §5.5). */
         build: string;
     };
+    /** 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(): "live" | "session_superseded";
+    /** C9: subscribe to `session_superseded`. runMode subscribes right after
+     *  construction, before start(), so a 4409 during start() is heard too. */
+    on(event: "session_superseded", listener: () => void): () => void;
+    /** 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. */
+    private onSessionSuperseded;
+    /**
+     * 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(): Promise<void>;
+    private closeOnce;
 }

package/dist/errors.d.ts

@@ -6,7 +6,7 @@
  * WebSocket returns `{type:"error", error, message, detail?}`. A client gets the
  * same `error` code regardless of which transport it used. (A2A §9.5/§10.6 pattern.)
  */
-export type BridgeErrorCode = "unauthorized" | "forbidden_origin" | "not_found" | "invalid_request" | "invalid_json" | "body_too_large" | "channel_pending" | "rate_limited" | "agent_paused" | "send_forbidden" | "group_superseded" | "unknown_action_run" | "vault_integrity_failed" | "vault_ref_changed" | "internal";
+export type BridgeErrorCode = "unauthorized" | "forbidden_origin" | "not_found" | "invalid_request" | "invalid_json" | "body_too_large" | "channel_pending" | "rate_limited" | "agent_paused" | "send_forbidden" | "group_superseded" | "unknown_action_run" | "vault_integrity_failed" | "vault_ref_changed" | "session_superseded" | "internal";
 export interface BridgeErrorSpec {
     /** HTTP status this code maps to (the WS binding ignores it). */
     http: number;

package/dist/index.js

@@ -24091,6 +24091,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 +24307,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 +24316,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 +24473,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 +24582,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 +24655,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 +35068,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 +35343,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 +35388,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 +35413,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 +35484,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 +35615,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 +36097,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 +36680,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 +36783,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 +36796,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 +36804,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 +36815,7 @@ var BridgeAgent = class _BridgeAgent {
       });
     }, 1e3);
     this.recallMaintenanceTimer?.unref?.();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     this.startReceivePump();
     if (drainedInTime) {
       this.armSelfHealSweeps();
@@ -40887,7 +41079,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 +42665,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 +42713,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([
@@ -42761,6 +43011,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 +43244,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 +43459,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 +43480,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 +43625,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 +43647,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 +43665,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/service/install-prep.d.ts

@@ -1,5 +1,19 @@
 import { type ServiceInput } from "./config.js";
 import { type AutoWireDeps } from "./harness-wire.js";
+/** The parsed `/healthz` body fields the install and status liveness checks read. */
+export interface DaemonHealth {
+    agent_sessions?: number;
+    evictions?: number;
+    state?: string;
+}
+/**
+ * Liveness is a routed `/healthz` 200 whose state is not `session_superseded`
+ * (P-2). A TCP accept proves nothing: the daemon pre-binds its port before
+ * `agent.start()`, so a connect succeeds before the bridge routes anything.
+ */
+export declare function isDaemonRouted(h: DaemonHealth | null): h is DaemonHealth;
+/** Default install wait: the boot drain may take up to BOOT_DRAIN_WAIT_MS_DEFAULT, plus 15 s. */
+export declare const VERIFY_BUDGET_MS: number;
 export interface PrepDeps {
     readFile: (p: string) => string;
     writeFileMode: (p: string, data: string, mode: number) => void;
@@ -8,8 +22,11 @@ export interface PrepDeps {
     realpath: (p: string) => string;
     listDir: (p: string) => string[];
     probeBindFree: (port: number) => boolean;
-    probeConnect: (port: number) => boolean;
+    /** Routed `/healthz` probe (P-2): null unless the daemon answered a 200 with parseable JSON. */
+    getHealth: (port: number) => DaemonHealth | null;
     sleep: (ms: number) => Promise<void>;
+    /** Wall clock in ms (Date.now). verifyDaemonUp's deadline reads it, so probe time counts, not only sleep. */
+    now: () => number;
 }
 export interface ParsedCredential {
     deviceId: string;
@@ -19,6 +36,9 @@ export interface ParsedCredential {
 export declare function assertReadableCredential(absPath: string, deps: PrepDeps): ParsedCredential;
 export declare function durableDir(home: string, slug: string): string;
 export declare function durableCredentialPath(home: string, slug: string): string;
+/** M5 (OQ-3): the approved refusal text for an identity that is already installed. */
+export declare class InstallRefusedError extends Error {
+}
 export declare function takeCustody(args: {
     home: string;
     slug: string;