@securecoms/agent-bridge 0.30.0 → 0.30.2

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

@@ -56,6 +56,19 @@ export interface BridgeConfig {
     ownerGrantPin?: OwnerGrantPinResult;
 }
 export declare const REQUIRED: readonly ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
+export type ConfigErrorReason = "credential_not_found" | "credential_unreadable" | "credential_not_json" | "credential_missing_field" | "credential_voice_invalid";
+/**
+ * A key-file load failure with a fixed reason code, set by the step that
+ * failed (spec 2026-10-15 §5.2). Callers map the code to a log field and a
+ * fixed human line; nothing reads `message`, which carries no path, no
+ * identifier and no upstream error text.
+ */
+export declare class ConfigError extends Error {
+    readonly reason: ConfigErrorReason;
+    readonly field?: (typeof REQUIRED)[number] | undefined;
+    readonly source?: "file" | "env" | undefined;
+    constructor(reason: ConfigErrorReason, field?: (typeof REQUIRED)[number] | undefined, source?: "file" | "env" | undefined);
+}
 export declare function loadConfig(opts: {
     credentialPath: string;
     storePath?: string;

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;