@securecoms/agent-bridge 0.23.0 → 0.24.0

package/dist/bridge-agent.d.ts

@@ -239,6 +239,18 @@ export interface BridgeAgentDeps {
      * timer delays.
      */
     rng?: () => number;
+    /**
+     * How long start() waits for its boot drain before it stops blocking on it
+     * (default {@link BOOT_DRAIN_WAIT_MS_DEFAULT}). Past it, start() finishes and
+     * the boot key-package publish is DEFERRED until an ingest cycle settles:
+     * see start(). Injected so tests do not wait a minute.
+     */
+    bootDrainWaitMs?: number;
+    /**
+     * SEC-06 #18: the wait between in-process reply publish retries after a rate
+     * limit. Defaults to an unref'd setTimeout. Injected so tests do not sleep.
+     */
+    replySleep?: (ms: number) => Promise<void>;
     /**
      * Task 4 (self-hosted fast voice): test seam for the fast-path LLM client.
      * Defaults to `new FastLlmClient(cfg.voice.fastPath, fetchImpl)` when
@@ -293,6 +305,27 @@ export declare const DEAD_LETTER_NOTICE_INTERVAL_MS: number;
  * agent's own membership row before deciding.
  */
 export declare const PAUSE_RECHECK_MS = 30000;
+/**
+ * Stranded sender (PR #751 review H-1): how often a channel held after a send
+ * 409 `mls.group_superseded` re-reads its held group to see whether it
+ * converged (a local read, no network).
+ */
+export declare const SUPERSEDE_RECHECK_MS = 30000;
+/**
+ * Stranded sender (PR #751 review H-1): the longest a channel's inbound is
+ * held, without spending delivery attempts, after a send 409
+ * `mls.group_superseded`. Convergence needs the OWNER's client online (a
+ * forked or stranded member cannot self-heal), so the bound must cover an
+ * owner who is away for a working day or a night, not the ~150 s the
+ * dead-letter budget (5 attempts, 2^n x 5 s) allows. 24 h does, and it sits
+ * well inside the 7-day reply-intent retention, so a held message never
+ * outlives the intent that answers it. The hold is measured from the FIRST
+ * 409 (a repeat 409 does not extend it). When it expires the channel is
+ * released and the ordinary budget applies again (the refund stops), so a
+ * channel that never converges still dead-letters, about 24 h later instead
+ * of about 150 s later.
+ */
+export declare const SUPERSEDE_HOLD_MAX_MS: number;
 /**
  * TTL for the Phase 2 channelMeta cache. `is_dm` is immutable for a channel_id,
  * so this exists only so a cached channel `name` re-resolves after a channel
@@ -334,13 +367,53 @@ export declare class InvalidMessageIdError extends Error {
 }
 /**
  * Deterministic message id for the voice fast-path reply to inbound turn
- * `messageId`: SHA-256 of `fast:<messageId>`, first 16 bytes, RFC 4122
- * version/variant nibbles set. Live finding 2026-09-06: the previous
- * `fast-<messageId>` string failed `resolveMessageId` ("message_id must be a
- * UUID") on every turn, so the fast path never sent once. Same input → same
- * UUID, so the idempotency argument in `runFastPath`'s doc still holds.
+ * `messageId`, formatted as an RFC 4122 UUID. Live finding 2026-09-06: the
+ * previous `fast-<messageId>` string failed `resolveMessageId` ("message_id
+ * must be a UUID") on every turn, so the fast path never sent once. Same input
+ * → same UUID, so the idempotency argument in `runFastPath`'s doc still holds.
+ *
+ * SEC-06 #18: KEYED with the identity-seed-derived reply key and bound to the
+ * agent and channel. It used to be SHA-256 of `fast:<messageId>` alone, which
+ * any channel member could compute and publish under first (the agent's fast
+ * reply then collides on the backend's message_id key and never publishes),
+ * and which two agents fast-answering the same room message shared. Its scope
+ * (`fast:`) never meets a runtime reply's (`reply:`).
  */
-export declare function fastReplyId(messageId: string): string;
+export declare function fastReplyId(key: Uint8Array, identityId: string, channelId: string, messageId: string): string;
+/**
+ * SEC-06 #18: how many times one reply publish is retried in-process after a
+ * rate limit (the bridge's room floor, or a backend 429) before the failure is
+ * surfaced. A surfaced failure leaves the reply intent pending, so the
+ * redelivery republishes the SAME reply rather than re-running the model.
+ */
+export declare const REPLY_RATE_LIMIT_RETRIES = 3;
+/** SEC-06 #18: bounds on one rate-limit wait (ms). */
+export declare const REPLY_RATE_LIMIT_MIN_WAIT_MS = 250;
+export declare const REPLY_RATE_LIMIT_MAX_WAIT_MS = 30000;
+/**
+ * SEC-06 #18 (#706 @1fe47aa2): an EXACT retry that arrives while its original
+ * is still in its transaction gets 409 `message_in_flight`. That is
+ * retry-later, never "re-encrypt": the original may yet be accepted. The same
+ * bytes are resent after 1 s, 2 s, 4 s; after that the failure surfaces
+ * (intent still pending) and the redelivery backoff and delivery cap bound it.
+ */
+export declare const REPLY_IN_FLIGHT_RETRIES = 3;
+export declare const REPLY_IN_FLIGHT_BASE_WAIT_MS = 1000;
+/** PR #716 review HIGH-1: bound on part advances after slot collisions, per send. */
+export declare const REPLY_MAX_PART_ADVANCES = 8;
+/** Options shared by `send` and `sendA2A`. */
+export interface SendOptions {
+    /** Phase 3 F3: whether this send is a substantive agent turn (default true). */
+    agentTurn?: boolean;
+    /**
+     * SEC-06 #18: the inbound message this send answers. Makes the send an
+     * idempotent reply: a deterministic message_id plus a durable intent written
+     * before the publish.
+     */
+    inReplyTo?: string;
+    /** SEC-06 #18: caller idempotency key (WS path); names the reply part. */
+    idempotencyKey?: string;
+}
 /**
  * B7 (FileSafe vault): a file-backed {@link OwnerAuthorityStore} for the
  * daemon's owner-pin TOFU state (mirrors B4b's browser-side store, which
@@ -383,6 +456,25 @@ export declare class SendForbiddenError extends Error {
     readonly channelId: string;
     constructor(channelId: string);
 }
+/**
+ * Stranded sender (spec 2026-09-26 §7.4): the backend refused a publish with
+ * 409 `mls.group_superseded`: the envelope was sealed under a group that is no
+ * longer the channel's active one. Nothing was stored, nothing fanned out.
+ *
+ * TERMINAL for THIS send (no in-place retry; a re-seal under the same held
+ * group would be refused the same way), but NOT for the reply: the answered
+ * inbound message is not retired and a reply intent stays pending, so the
+ * reply is republished once the bridge holds the active group. The bridge
+ * never wipes on it (no `healWedgedChannel`, no `resetChannelForRejoin`).
+ *
+ * `activeGroupId` is the group the backend named, or null when the channel has
+ * no active group (fail closed: nothing to converge to).
+ */
+export declare class GroupSupersededSendError extends Error {
+    readonly channelId: string;
+    readonly activeGroupId: string | null;
+    constructor(channelId: string, activeGroupId: string | null);
+}
 /** Thrown by `agent.action.*` when a runId (or nodeId within a run) is unknown
  * or the run has already settled — settle() is terminal, mirroring the client
  * ingest side's "later partials for a settled run are dropped" rule. */
@@ -435,6 +527,8 @@ export interface AgentActionAPI {
     wrap<T>(runId: string, fn: () => T | Promise<T>, opts: AgentActionWrapOpts): Promise<T>;
 }
 export declare const BRIDGE_VERSION: string;
+/** start() waits this long for its boot drain before it stops blocking on it. */
+export declare const BOOT_DRAIN_WAIT_MS_DEFAULT = 60000;
 export declare class BridgeAgent {
     private readonly cfg;
     private readonly transport;
@@ -509,8 +603,39 @@ export declare class BridgeAgent {
      * Bounded; oldest forgotten first.
      */
     private readonly retiredRuntimeIds;
+    /** SEC-06 #18: HMAC key for deterministic reply ids and body MACs. */
+    private readonly replyIdKey;
+    /**
+     * PR #716 review MEDIUM-5: in-flight idempotent sends and intent replays.
+     * close() waits for them before it closes the store.
+     */
+    private readonly replyWork;
+    /** SEC-06 #18: channels whose redelivered message is being republished from its intent. */
+    private readonly replayingChannels;
+    /** SEC-06 #18: in-process locks: one resolve+claim per scope, one publish per part. */
+    private readonly replyIntentLocks;
+    private readonly replySleep;
+    /** SEC-06 #18: redelivered messages answered from a reply intent, not the model. */
+    private replyIntentReplays;
+    /** SEC-06 #18: in-process reply publish retries after a rate limit. */
+    private replyRateLimitRetries;
     /** Phase 3 F1: one pending membership recheck per paused channel holding work. */
     private readonly pauseRecheckTimers;
+    /**
+     * Stranded sender (PR #751 review H-1): channels whose send was refused 409
+     * `mls.group_superseded`, with the group held at that moment and when the
+     * hold began. Their inbound is held (never acked, no attempt spent) until
+     * the held group changes, a send succeeds, or SUPERSEDE_HOLD_MAX_MS passes.
+     */
+    private readonly supersededChannels;
+    /** H-1: channels whose hold EXPIRED; their 409s spend attempts again. */
+    private readonly supersedeHoldExpired;
+    /** H-1: one pending held-group recheck per held channel. */
+    private readonly supersedeRecheckTimers;
+    /** H-1: runtime messages whose CURRENT delivery attempt may be refunded once. */
+    private readonly supersedeRefundable;
+    /** M-1: channels this process has used as a FileSafe vault channel. */
+    private readonly vaultChannelIds;
     /** Phase 3 F3: consecutive agent turns per channel. */
     private readonly agentHops;
     private readonly maxAgentHops;
@@ -671,10 +796,55 @@ export declare class BridgeAgent {
     private readonly selfHealSweepEnabled;
     /** Task 12: proactive sweep cadence (in addition to the once-at-boot fire). */
     private static readonly SELF_HEAL_SWEEP_INTERVAL_MS;
+    /**
+     * A trigger that finds the in-flight ingest cycle older than this logs
+     * `receive.ingest_stalled` once for that cycle. Log only: the trigger still
+     * queues behind it (see ingestOnce). Two missed safety ticks.
+     */
+    private static readonly INGEST_STALL_LOG_MS;
+    /**
+     * An in-flight ingest cycle older than this is abandoned by the next trigger
+     * (see ingestOnce). A WALL-CLOCK age for the whole cycle, not a bound on any
+     * one request: a cycle makes many requests in sequence, each with its own
+     * budget, so a cycle that is only slow can pass it (see ingestOnce for what
+     * that costs).
+     */
+    private static readonly INGEST_ABANDON_MS;
     private static readonly SELF_HEAL_SWEEP_JITTER_MS;
     private selfHealTimer?;
     private bootSweepTimer?;
     private readonly rng;
+    private readonly bootDrainWaitMs;
+    /** Resolved (and cleared) each time an ingest cycle settles: see start(). */
+    private ingestSettledWaiters;
+    /** The boot key-package publish, when start() had to defer it. Test seam. */
+    private deferredBootPublish;
+    /**
+     * True from the moment start() begins its boot drain until an ingest cycle
+     * has SETTLED (the drain itself, or the valve's replacement). While it is
+     * true, no path outside that drain may rotate the device key package: see
+     * kpRotationRefusedByBootDrain.
+     */
+    private bootDrainPending;
+    /**
+     * #811 L-1: channels whose onWedged heal the boot drain REFUSED (a send the
+     * drain started quarantined them outside its exemption, #799 M-2). The SDK
+     * fires onWedged once per episode, so nothing else would ask again until a
+     * sweep proves the channel stuck. Signalled once after the drain settles:
+     * see signalWedgesRefusedByBootDrain. A set, so bounded by the channel count;
+     * a refusal can only happen while `bootDrainPending`, once per process.
+     */
+    private readonly wedgeSignalsRefusedByBootDrain;
+    /** #811 L-1: the post-drain pass has run; a refusal queued after it (its
+     *  catch ran on a later microtask than the settle) kicks the pass itself. */
+    private wedgeSignalsAfterBootDrainArmed;
+    /** #811 L-2: the rotation sites whose boot-drain refusal was already logged. */
+    private readonly bootDrainRefusalLogged;
+    /** The running ingest cycle's exemption, for everything the cycle runs.
+     *  ⛔ Read ONLY through drainExemptionAtCallIn(), and only where the drain
+     *  calls in: timers created inside a cycle inherit this context, so a check
+     *  that read it anywhere else would exempt them too (#789 LOW). */
+    private readonly ingestCycleContext;
     private readonly rateFloor;
     /**
      * agent.action.* run state, keyed by runId.
@@ -734,6 +904,10 @@ export declare class BridgeAgent {
     private readonly waiters;
     private pingHandle?;
     private safetyTimer?;
+    /** The ingest cycle now running, if any (see ingestOnce: single-flight). */
+    private ingestInFlight;
+    /** The ONE follow-up cycle every trigger during the in-flight cycle shares. */
+    private ingestFollowUp;
     private runtimeConfigTimer?;
     private readonly listeners;
     private startedAt;
@@ -813,6 +987,96 @@ export declare class BridgeAgent {
      */
     private capBuffer;
     start(): Promise<void>;
+    /**
+     * #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
+     * boot key-package publish, so `bootDrainPending` is false and nothing here
+     * can be refused again.
+     *
+     * ⛔ Never a wipe. The refused heal already ran its wipe step (under its own
+     * anti-thrash floor) before it reached the signal. This pass only re-sends
+     * the half that was refused, and only for a channel that STILL holds no
+     * state: one that holds state now rejoined meanwhile (or someone else put
+     * state there), and asking for it is the "ask without repudiating" churn
+     * healWedgedChannel itself refuses. The signal is the same one the
+     * no-local-state Task-11 branch and the sweep send, under the same shared
+     * per-channel cooldown. Never throws: each channel has its own catch.
+     */
+    private signalWedgesRefusedByBootDrain;
+    /** #811 L-1: queue a channel whose wedge heal the boot drain refused. */
+    private queueWedgeSignalAfterBootDrain;
+    /**
+     * Arm the self-heal sweeps: the periodic one and the once-at-boot one.
+     *
+     * ⛔ Only after the boot drain has settled AND the boot key-package publish
+     * has run. selfHealSweep opens with rotateDeviceKeyPackage(), which can
+     * delete a TTL-lapsed bundle, and a Welcome still waiting in the boot drain
+     * is sealed to that bundle: it would be discarded and acked (#789
+     * verification NO-GO: rng 0 fired the boot sweep inside the slow-drain
+     * window).
+     */
+    private armSelfHealSweeps;
+    /**
+     * Defence in depth for DRAIN BEFORE ROTATE (see start()). True, and logged,
+     * when a key-package rotation is attempted while the boot drain is still
+     * unsettled from OUTSIDE that drain: a send's supersede convergence, a
+     * sweep, any future caller. Such a rotation can delete the held bundle that
+     * a Welcome still inside the drain is sealed to.
+     *
+     * The drain's own calls are exempt: the SDK's onWedged / onSupersedeUnopenable
+     * heals fired from its receive pass (the onWedged heal is detached), and its
+     * phase-0 re-Welcome signal. That ordering is unchanged from before the boot
+     * wait was bounded, and refusing it would change the drain. #789 LOW: the
+     * exemption is an explicit DrainExemption handed down from those three
+     * call-in points, never the inherited AsyncLocalStorage context, so a timer
+     * or sweep scheduled inside the drain that calls a rotator is refused, as is
+     * the late work of a cycle the valve abandoned. The hook call-ins DO read
+     * the context, so sends the cycle starts and the send-side convergence run
+     * outside it (#799 M-2; see DrainExemption for the residual).
+     * Only the bridge-level rotators route through here. The SDK's own
+     * publishes (ensureSession bootstrap, vault owner, reset supersede) mint only
+     * when NO bundle is held, so they delete nothing.
+     */
+    /**
+     * The boot KeyPackage publish (architect ruling on the #793 M1 proposal, 1B).
+     * Runs only once the boot drain settled (`bootDrainPending` is already false).
+     * The plain publish can no longer rotate an expired KeyPackage without a drain
+     * receipt, and the bridge's boot drain is its own ingest cycle, which cannot
+     * mint an SDK receipt. So the helper runs its OWN drain here (one pull, joins
+     * only channels with no state, right after the boot ingest) and rotates only
+     * with that receipt. A failed read must never fail the boot: fall back to the
+     * plain publish, which mints when no bundle is held and never deletes.
+     */
+    private bootReconcileKeyPackage;
+    private kpRotationRefusedByBootDrain;
+    /**
+     * #799 L-1: give back a re-Welcome cooldown spent on a signal the boot drain
+     * refused (the same restore as a "deferred" outcome). `last` is the value
+     * read before the signal: an earlier request time, or -Infinity for never.
+     * True when `e` was that refusal: it is a wait, already logged once per
+     * site (kpRotationRefusedByBootDrain), so the caller logs no failure line
+     * for it (#811 L-2).
+     */
+    private restoreWelcomeCooldownIfRefused;
+    /**
+     * #799 M-2: run `fn` OUTSIDE the ingest cycle's AsyncLocalStorage context.
+     * For a SEND a cycle starts (the fast-path reply, the summarize answer) and
+     * for the send-side supersede convergence: a send is not the drain, but it
+     * can reach the SDK's onSupersedeUnopenable hook (its reconcileForSend
+     * receive pass, or the send-path adopt), and the hook reads the context at
+     * call-in. Outside it, the hook finds no exemption and a rotation while the
+     * boot drain is unsettled is refused.
+     */
+    private outsideIngestCycle;
+    /**
+     * The running ingest cycle's exemption, when the caller runs inside one.
+     * Call it ONLY synchronously at a place where the drain itself calls in (the
+     * two SDK hooks and the phase-0 signal), and pass the result down
+     * explicitly. Nothing else may read the context: see ingestCycleContext.
+     * Whether it still counts is decided at the rotator (`live`), because a
+     * detached heal can hold it past the moment the valve abandons its cycle.
+     */
+    private drainExemptionAtCallIn;
     /** C3: a random 0..SELF_HEAL_SWEEP_JITTER_MS decorrelation offset. */
     private sweepJitter;
     /**
@@ -841,15 +1105,32 @@ export declare class BridgeAgent {
      * "private KeyPackage key no longer held" and the Welcome is discarded. A bare
      * re-Welcome re-seals to the SAME diverged published KP — un-openable again —
      * looping until the channel quarantines. So:
-     *   - published == held  → publishKeyPackage() (no-op while held; mints only if
-     *     somehow none is held), then re-Welcome re-seals to the current KP we hold.
-     *   - published != held  → forceRepublishKeyPackage() re-syncs the server to a
-     *     bundle we hold, so the owner's re-Welcome is openable. Orphan-safe: a
-     *     diverged published KP means every other pending Welcome sealed via the
-     *     server is un-openable too, so replacing the shared per-device bundle
-     *     strands nothing that was openable (see heldBundleMatchesPublishedKp).
+     *   - published == held  → kept (no-op publish), then re-Welcome re-seals to
+     *     the current KP we hold.
+     *   - published != held  → provider.reconcileHeldKeyPackage DRAINS the queued
+     *     Welcomes first, then rotates, so the owner's re-Welcome is openable and
+     *     nothing already queued is stranded (architect ruling on the #793 M1
+     *     proposal). The text below describes the pre-ruling hazard.
+     *     ⛔ NOT ORPHAN-SAFE, and nothing here drains first. `false` covers two
+     *     different states. (a) The server vends DIFFERENT bytes: Welcomes sealed
+     *     since that publish are un-openable anyway, but ones sealed to the held
+     *     bundle before it may still be queued. (b) The server vends NOTHING because
+     *     the held KeyPackage EXPIRED: it is absent, not diverged, and every Welcome
+     *     sealed to it before expiry is still queued AND still openable with the
+     *     held bundle. The unconditional delete strands both. Disclosed residual
+     *     (#792 review M1); the proposed fix is one shared SDK rotate helper that
+     *     drains before it deletes.
      * getLastPublishedKpId then names the reconciled KP so the owner re-seals to it.
      * Callers own their cooldown/rate-limit gate and try/catch — this does neither.
+     *
+     * ⛔ An UNDETERMINED answer never rotates. The predicate is the THROWING
+     * variant: a failed batch KeyPackage read (a read deadline, 401/403, network)
+     * or a failed held-bundle store read REJECTS out of here, so nothing is
+     * published, nothing is deleted and no Welcome is requested. The catching
+     * variant answered `false` for those, which routed an outage to
+     * forceRepublishKeyPackage(): it deleted the device-wide bundle and every
+     * Welcome already queued to it, for any channel, was discarded un-openable
+     * (N-2). Every caller catches, and retries on its own cadence.
      */
     private signalHeldKpWelcome;
     /**
@@ -869,7 +1150,11 @@ export declare class BridgeAgent {
      * group (`continue`, no signal). ANY failure along the way (probe throws,
      * signal throws) is swallowed: a wedge heal must never throw back into the
      * SDK's onWedged caller. Single-shot per wedge episode — full rejoin
-     * reliability is P1, not this hook's job.
+     * reliability is P1, not this hook's job. #811 L-1: the one exception is a
+     * signal the boot drain REFUSED (a send the drain started fired onWedged
+     * outside its exemption): the channel is queued and signalled once after
+     * the drain settles (signalWedgesRefusedByBootDrain), since the SDK will
+     * not fire onWedged again for this episode.
      */
     private healWedgedChannel;
     /**
@@ -994,27 +1279,236 @@ export declare class BridgeAgent {
      * already resolves internally) propagates unchanged.
      */
     private sendWithSelfHealTerminal;
+    /**
+     * Stranded sender (spec 2026-09-26 §7.4, architect M-6 ruling + audit N-1):
+     * the ONE place a bridge publish meets 409 `mls.group_superseded`. Every
+     * `transport.publish` in this file goes through it, so the rule cannot be
+     * skipped by a send path:
+     *
+     *  1. Terminal for the send: the typed {@link GroupSupersededSendError} is
+     *     thrown, and the SDK send helpers never retry it in place.
+     *  2. NEVER a wipe. `healWedgedChannel` / `resetChannelForRejoin` are not
+     *     called: a wipe drops the held state, and the next Welcome then lands on
+     *     a device with no local state, where the join takes the first Welcome
+     *     for the channel with NO attestation check. A server-chosen response
+     *     code must not launder a refused supersede into an unverified join.
+     *  3. With a pinned owner: `adoptSupersededGroup` once (see
+     *     {@link convergeAfterSendSuperseded}).
+     *  4. The non-destructive signal (ditto).
+     *
+     * Any other error passes through unchanged.
+     */
+    private publishEnvelope;
+    /**
+     * PR #751 review M-1 (plan invariant F-1): adoption and the Welcome signal
+     * run only on a channel KNOWN not to be a FileSafe vault channel. FileSafe
+     * halts on a vault group mismatch by design and must never adopt, and the
+     * SDK's adoptSupersededGroup leaves the vault skip to its caller.
+     *
+     * Fail closed. A channel is allowed only when the enclave channel listing
+     * has shown it (the listing excludes hidden channels, and `vault` is the
+     * only kind that is ever hidden; the self-heal sweep works from the same
+     * listing, so this is the sweep's own scope) AND this process has never
+     * used it as a vault channel. An unlisted channel gets one listing refresh;
+     * still unlisted, it is skipped (a vault channel after a restart lands here,
+     * as does a channel whose listing is unavailable).
+     */
+    private supersedeConvergenceAllowed;
+    /**
+     * H-1: hold `channelId`'s buffered inbound after a send 409. The FIRST 409
+     * starts the hold; a repeat keeps its start (the bound is never extended)
+     * and a channel whose hold already expired is not held again until it
+     * converges or sends. Never throws.
+     */
+    private holdSuperseded;
+    /**
+     * H-1: whether `channelId`'s buffered work must be HELD (a send 409 is
+     * outstanding and the hold has not expired). Holding arms a recheck so the
+     * release does not depend on new traffic. Synchronous: it only reads the
+     * map; the held-group read happens in {@link recheckSupersedeHold}.
+     */
+    private heldForSupersede;
+    private scheduleSupersedeRecheck;
+    /**
+     * H-1: release the hold once the held group CHANGED (an adoption, a
+     * receive-path supersede, or a rejoin converged it), or once it expired.
+     * Otherwise keep holding, re-armed while work is buffered for the channel.
+     */
+    private recheckSupersedeHold;
+    private expireSupersedeHold;
+    private releaseSupersedeHold;
+    private clearSupersedeHold;
+    /**
+     * H-1: a reply to `inReplyTo` was refused 409 `mls.group_superseded`. That
+     * says nothing about the message, so the delivery that produced the reply
+     * does not count against its dead-letter budget: give its attempt back, in
+     * memory and durably. At most once per delivery (a multi-part reply cannot
+     * refund twice), and not once the channel's hold has expired (then the
+     * ordinary budget bounds a channel that never converges).
+     */
+    private refundSupersededDelivery;
+    /**
+     * Stranded sender, §7.4 rules 3 and 4, in that order.
+     *
+     * Rule 3 (audit N-1): with a PINNED owner, `adoptSupersededGroup(channelId,
+     * activeGroupId, pinnedOwner)` once. The owner comes ONLY from the bridge's
+     * own pin ({@link resolvePinnedOwnerHook}: the cached structural owner AND a
+     * persisted pin that matches it), never from the server's roster. It is the
+     * same verified core `trySupersede` runs on receive with the same pin, so it
+     * adds no trust; it converges without waiting for the next receive pass.
+     * Without a pin: no adoption.
+     *
+     * Rule 4 (architect M-6): the sweep's non-destructive diverged-channel
+     * action, `signalHeldKpWelcome(activeGroupId)`, at most once per the SHARED
+     * per-channel `lastWelcomeRequest` cooldown (the same map and floor as the
+     * self-heal sweep, so a 409 storm cannot out-pace the sweep's own cadence).
+     *
+     * Both are skipped when there is nothing to converge to (no active group:
+     * fail closed). The signal is also skipped when the bridge already holds
+     * the group the backend named (an adoption just converged it, or it
+     * converged between the seal and the answer): a request for a group we hold
+     * costs the committer a Remove+Add and cannot be consumed. Never throws: a
+     * failed adoption or signal must not mask the typed send error.
+     */
+    private convergeAfterSendSuperseded;
+    /**
+     * The terminal classification of {@link sendWithSelfHealTerminal}, shared
+     * with the SEC-06 #18 cached-envelope resend (which publishes prebuilt bytes
+     * and so does not go through sendWithSelfHeal).
+     */
+    private publishTerminal;
     /**
      * `opts.agentTurn` (default true): whether this send is a SUBSTANTIVE agent
      * turn for the Phase 3 F3 hop count. Notices (daily limit, dead letter) and
      * continuation parts of one multi-part reply pass false (final-wave I2).
+     *
+     * SEC-06 #18: `opts.inReplyTo` / `opts.idempotencyKey` make the send an
+     * idempotent reply (see {@link sendIdempotent}); `messageId` must then be
+     * absent, because the id is derived.
      */
-    send(channelId: string, text: string, messageId?: string, opts?: {
-        agentTurn?: boolean;
-    }): Promise<{
+    send(channelId: string, text: string, messageId?: string, opts?: SendOptions): Promise<{
         message_id: string;
         status: "sent";
     }>;
+    /** PR #716 review MEDIUM-5: register reply work so close() can wait for it. */
+    private trackReplyWork;
     sendA2A(channelId: string, a2a: {
         a2a_version: string;
         kind: "message" | "task" | "artifact";
         object: Record<string, unknown>;
-    }, messageId?: string, opts?: {
-        agentTurn?: boolean;
-    }): Promise<{
+    }, messageId?: string, opts?: SendOptions): Promise<{
         message_id: string;
         status: "sent";
     }>;
+    /**
+     * Seal and publish one application message under `id`: the room/a2a rate
+     * floor, join reconcile, and the shared self-heal seam. `onEnvelope` runs
+     * for every envelope built, BEFORE it is published (SEC-06 #18 persists it
+     * there so a retry can resend the exact bytes).
+     */
+    private publishBody;
+    private enforceBodyRateFloor;
+    /** Bookkeeping after a CONFIRMED publish of `body` under `id`. */
+    private afterPublish;
+    private isIdempotentSend;
+    /**
+     * SEC-06 #18: publish a reply part idempotently.
+     *
+     * 1. Resolve and claim the intent under one lock per scope. An explicit
+     *    idempotency_key names the part. Without one, a send whose body equals
+     *    the MOST RECENT part of this inbound is a retry of that part (PR #716
+     *    review MEDIUM-2: an older identical part is not matched, so A, B, A are
+     *    three messages); anything else is a new part, numbered from the STORE
+     *    (1 + the highest recorded ordinal, review HIGH-1), never from memory,
+     *    so a restart cannot reuse a published part's id.
+     * 2. The claim is durable BEFORE any publish. An existing intent for the
+     *    slot is authoritative when it holds this body; one holding a different
+     *    body is skipped past (the next ordinal).
+     * 3. Publish it (see {@link publishIntent}).
+     */
+    private sendIdempotent;
+    /**
+     * SEC-06 #18 / PR #716 review HIGH-1: resolve and claim an unkeyed part of
+     * the reply to `inReplyTo`. Caller holds the scope lock. `matchRetry` false
+     * after a slot collision: the body must go to a NEW part.
+     */
+    private claimUnkeyedPart;
+    /** SEC-06 #18: run `fn` after every earlier holder of `lockKey` settled. */
+    private withReplyLock;
+    /**
+     * SEC-06 #18: publish one pending intent, at most one publish in flight per
+     * intent in this process. A sent intent returns its id without publishing.
+     *
+     * - The row is verified first (review LOW-6); a row that fails is dropped.
+     * - A TERMINAL refusal abandons the reply's unpublished parts (the inbound
+     *   is retired by the caller), or the one keyed intent, so no sealed reply
+     *   text lingers (review LOW-8).
+     * - A slot collision (review HIGH-1): an unkeyed part is marked skipped and
+     *   its body re-claimed at the next ordinal; a keyed one is refused with
+     *   {@link IdempotencyConflictError}.
+     *
+     * Returns the id the reply was published under (a moved part's new id).
+     */
+    private publishIntent;
+    /**
+     * PR #716 review LOW-6: the row's id derives from its own identity, channel,
+     * scope and part, and its body matches its MAC (which binds id and channel).
+     */
+    private intentVerifies;
+    /**
+     * SEC-06 #18 item 3: a rate-limited reply retries the PUBLISH in-process
+     * with backoff, never the model turn; so does an exact resend whose
+     * original is still in flight. After REPLY_RATE_LIMIT_RETRIES a rate limit
+     * surfaces as the bridge's own `rate_limited`, and after
+     * REPLY_IN_FLIGHT_RETRIES an in-flight answer surfaces as an ambiguous
+     * failure. Either way the intent stays pending, so the redelivery
+     * republishes the same reply.
+     */
+    private publishIntentWithRetry;
+    /**
+     * One publish attempt of a pending intent.
+     *
+     * If a signed envelope was persisted by an earlier attempt, resend THOSE
+     * BYTES: the earlier attempt may have been accepted, and the backend
+     * replays the original ack only for identical canonical bytes (#706; a
+     * resealed retry of an accepted message is a 409). Never re-encrypt a reply
+     * that may already have been accepted. The #706 @1fe47aa2 table:
+     *   - 200 (`idempotent_replay`): done, the original ack.
+     *   - 409 `message_in_flight`, 429 `tenant_busy`, 503 `server_busy`: retry
+     *     the same bytes later ({@link ReplyInFlightError}).
+     *   - 409 `replay_nonce` on the cached bytes: the earlier attempt burned the
+     *     nonce and did NOT commit, so nothing is stored under this id: re-seal
+     *     (same id, fresh nonce, current epoch).
+     *   - 400 `mls.stale_epoch`: answered only for a NEW id: re-seal.
+     *   - 409 `message_id_conflict`: the id is held by OTHER bytes, so it is a
+     *     slot collision ({@link ReplyIdCollisionError}), never "delivered".
+     *   - 400 `mls.group_header_required` (stranded sender): the cached bytes
+     *     carry no group header and this population must name its group.
+     *     Answered before the nonce is burned and before anything is stored:
+     *     re-seal (a fresh seal captures the group, so it carries the header).
+     *   - 409 `mls.group_superseded` (stranded sender): step 4b answers a stored
+     *     id first, so reaching this answer proves NOTHING is stored under the
+     *     id; the nonce was burned at step 5. Clear the bytes, and stop: the send
+     *     is terminal ({@link GroupSupersededSendError}, spec §7.4), and a
+     *     re-seal now would seal under the same superseded group. The NEXT
+     *     attempt re-seals, after the bridge holds the active group.
+     *
+     * Stranded sender, carriage (spec §7.3): a cached envelope is resent with the
+     * group recorded for those exact bytes (the store checks the digest), or with
+     * NO header when none is recorded (an intent from before this change). It is
+     * never re-sealed pre-emptively for lack of a header.
+     *
+     * "Never publish twice" rests on the #706 contract plus one invariant of
+     * this function: the cached envelope ALWAYS holds the last bytes posted
+     * under this id. The envelope is saved (awaited) BEFORE every fresh POST,
+     * and it is cleared only after the backend answered `mls.stale_epoch` or
+     * `replay_nonce` for those very bytes, which #706 defines as "not accepted"
+     * (nothing is stored under the id). So a POST of our own possibly-accepted
+     * bytes is always a resend of those same bytes, which #706 answers with the
+     * original ack; a conflict can only mean the slot belongs to another
+     * message (for example an old reply whose intent was pruned).
+     */
+    private publishIntentOnce;
     private sendDeps;
     private receiveDeps;
     sendAttachment(channelId: string, filePath: string, caption?: string): Promise<{
@@ -1023,6 +1517,14 @@ export declare class BridgeAgent {
     }>;
     private vaultRoot;
     private vaultAuthHeaders;
+    /**
+     * SEC-06 #11 (FB-P1-024): every backend call this class makes directly goes
+     * through the SDK's one deadline helper, so a stalled backend or proxy can
+     * never hold a lane forever. `read` for idempotent GETs, `control` for
+     * writes; blob transfers use `fetchWithDeadline` with a size-scaled budget.
+     * A timeout rejects with the SDK's `FetchDeadlineError`.
+     */
+    private fetchBounded;
     /** M6 (Task 11): idempotent get-or-create resolve of the enclave's hidden
      *  vault channel id — used as the fallback when a caller omits
      *  vaultChannelId. Mirrors connect-web's filesafe-api.ts resolveVaultChannel
@@ -1116,7 +1618,7 @@ export declare class BridgeAgent {
      *
      * Dedupe: `fastPathSeen` is keyed by messageId so a redelivered/duplicate
      * InboxEntry (e.g. after an ack race) never fires the fast LLM — and never
-     * double-sends — twice for the same turn. The `fastReplyId(messageId)` send
+     * double-sends — twice for the same turn. The `fastReplyId(...)` send
      * id is itself also deterministic, so even a duplicate call that slipped past the
      * in-memory dedupe (e.g. a process restart) resolves to the same envelope
      * message id rather than a second spoken reply.
@@ -1374,7 +1876,63 @@ export declare class BridgeAgent {
      */
     private actionWrap;
     protected startReceivePump(): void;
+    /**
+     * Run one ingest cycle, SINGLE-FLIGHT. Every trigger goes through here: the
+     * delivery-ping pump, the 25 s safety tick, and start()'s boot drain.
+     *
+     * Two cycles must never run at once. Both pull the same unacked rows, custody
+     * serves the same application message to both, and each copy feeds
+     * per-message state before the copies merge in the runtime inbox: the
+     * agent-hop counter counted one message twice, and the inflated run
+     * suppressed and ACKED the next agent-authored message (a silent loss). Two
+     * concurrent reconcileJoin passes over one channel's Welcome are not a
+     * state this pump should be able to reach either.
+     *
+     * A trigger that lands while a cycle is in flight is NOT satisfied by that
+     * cycle: it pulled before the trigger, so a message the ping announced could
+     * sit until the next safety tick. It waits for ONE follow-up cycle, shared by
+     * every trigger that arrived during the in-flight one, and its promise
+     * settles when that follow-up settles. So "ingestOnce() resolved" still means
+     * "a cycle that started after my call has run", and a burst of pings costs
+     * at most one extra cycle.
+     *
+     * A slow cycle is NOT bypassed: a trigger behind it queues, and past
+     * INGEST_STALL_LOG_MS logs `receive.ingest_stalled` once.
+     *
+     * THE VALVE. A cycle older than INGEST_ABANDON_MS is abandoned by the next
+     * trigger: `receive.ingest_abandoned` is logged, the gate forgets it, and
+     * every waiter queued behind it is released to a fresh cycle. It exists
+     * because a cycle can still wait on something with no deadline: every
+     * RestMlsBackend READ, ack and nack is bounded (read 10 s, control 15 s),
+     * but its state-changing MLS writes (distribute, request-welcome, init,
+     * reinit, key-package publish, commit lease) are deliberately not, and a
+     * channel lock can be held by a send waiting on one. Without the valve, one
+     * such await that never settles stops inbound for the life of the process,
+     * where the pre-single-flight code's overlapping 25 s tick kept rows flowing.
+     *
+     * ⚠️ What the 10 minutes is and is not. It is the age of the whole cycle,
+     * not a per-request bound: each request carries its own budget, and a cycle
+     * makes many in sequence (a pull, a join per unjoined channel, a roster read
+     * per channel, one decrypt pass over up to 100 rows, an ack). So a cycle
+     * that is merely slow, and still progressing, can be abandoned too.
+     *
+     * ⚠️ What a late wake costs. The abandoned cycle keeps running if it ever
+     * wakes, now beside the replacement: the overlap this gate exists to stop.
+     * Two consequences, both at-least-once, neither a loss:
+     *  - Hop counting: the per-message idempotency in AgentHopTracker absorbs
+     *    the duplicate sighting.
+     *  - Redelivery to the runtime: the replacement may already have staged,
+     *    delivered AND had the runtime ack a message the abandoned cycle still
+     *    holds. The runtime ack removes it from `runtimePendingIds`, so the late
+     *    cycle's stageRuntimeMessage stages it again and the runtime is handed an
+     *    ALREADY-ACKED message a second time. The first-party runtime dedupes by
+     *    message_id; a third-party consumer of the bridge sees a duplicate. The
+     *    delivery row's own double ack is a no-op at the server
+     *    (`acked_at IS NULL`).
+     */
     private ingestOnce;
+    private startIngestCycle;
+    private ingestCycle;
     drain(channelId: string | undefined, waitSeconds: number): Promise<BridgeMessage[]>;
     /** Notify-only SSE signal: fired after a buffer push. Listener pulls via takeBuffered. */
     subscribe(listener: () => void): () => void;
@@ -1390,6 +1948,21 @@ export declare class BridgeAgent {
      * backlog replays one message per channel at a time after a restart.
      */
     takeDeliverable(busyChannels: ReadonlySet<string>): BridgeMessage[];
+    private hasReplyIntent;
+    /**
+     * SEC-06 #18: answer a redelivered message from its reply intent. Counts as
+     * a delivery attempt (so the cap and backoff still bound it) and holds the
+     * channel like an in-flight message. Success acknowledges the inbound; an
+     * ambiguous failure requeues it behind the usual backoff, still intercepted.
+     */
+    private startReplyReplay;
+    /**
+     * Publish every pending part of `m`'s reply, in order, from the intent
+     * (same id, same text), then record the reply receipt. A TERMINAL refusal
+     * (paused, forbidden) resolves too: the inbound is retired, exactly as the
+     * live send path retires it. Any other failure rejects.
+     */
+    private replayReplyIntents;
     /**
      * Phase 3 F1: gate ONE delivery of `message` to the runtime consumer. Returns
      * true when it may be sent (and counts the attempt durably), false when the
@@ -1532,6 +2105,15 @@ export declare class BridgeAgent {
         /** SDK-6: cumulative rows ack-drained because their group_id is RETIRED for
          *  the channel (superseded fork-loser traffic). */
         retired_drained: number;
+        /** INV-CUSTODY-DURABLE §5.C.6: rows silently drained past expires_at. */
+        expired_drained: number;
+        /** INV-CUSTODY-DURABLE §5.C.3: a decrypted, un-acked row is memory-only
+         *  (its durable write failed); a restart now would lose it. */
+        custody_persist_failing: boolean;
+        custody_persist_failures: number;
+        /** #772 audit M2/M1: custody reads failing; the store's breaker open. */
+        custody_read_failing: boolean;
+        custody_store_unavailable: boolean;
         /** Track 5: cumulative artifact_share messages where download/decrypt/digest failed (fail-soft — acked, no redeliver). */
         failed_attachments: number;
         /** Task 4 (self-hosted fast voice): cumulative fast-path replies actually sent. */
@@ -1580,6 +2162,26 @@ export declare class BridgeAgent {
          *  not be resolved. `null` folds into `degraded` exactly like `true`: healthy
          *  requires a positive, current proof of non-expiry. */
         keypackage_expired: boolean | null;
+        /** #792 review O4: FAILED held-vs-published KeyPackage reads (a read
+         *  deadline, 401/403, 429, network, a store read that throws). Since #792 a
+         *  failed read defers the re-Welcome request instead of rotating, so a
+         *  PERSISTENT failure is a device that silently never asks to be re-added.
+         *  `_consecutive` resets on the next read that returns an answer; alert on
+         *  it staying above zero across several sweeps. Not folded into `degraded`:
+         *  the read runs only when a channel needs a heal, so a stale streak can
+         *  outlive the need. A mismatch is an answer, never counted here. */
+        keypackage_match_read_failures: number;
+        keypackage_match_read_failures_consecutive: number;
+        /** ms since epoch of the newest failed read, or null. */
+        keypackage_match_read_last_failed_at: number | null;
+        /** Architect ruling on the #793 M1 proposal, 1D: reconciles that DEFERRED
+         *  (an in-lock drain arm) and that were REFUSED on a full delivery page.
+         *  A device that keeps refusing is one the server cannot vend: alert on the
+         *  `_consecutive` streak. */
+        keypackage_reconcile_deferred: number;
+        keypackage_reconcile_deferred_consecutive: number;
+        keypackage_reconcile_refused_page_full: number;
+        keypackage_reconcile_refused_page_full_consecutive: number;
         /** A2 (dr-evil F3, decision D-3): the truthful roll-up — true when any
          *  channel is definitively diverged OR the observations cannot be trusted
          *  (stale/absent). Additive: `status` stays "ok" until the flip ships as
@@ -1647,6 +2249,10 @@ export declare class BridgeAgent {
         /** Phase 3 F3: agent-authored messages not answered by the loop guard. */
         agentLoopSuppressed: number;
         rateLimitedSends: number;
+        /** SEC-06 #18: redelivered messages answered from a reply intent (no model run). */
+        replyIntentReplays: number;
+        /** SEC-06 #18: in-process reply publish retries after a rate limit. */
+        replyRateLimitRetries: number;
         permanentlySkipped: number;
         /** SDK-6: cumulative rows ack-drained via QUARANTINE, distinct from the
          *  same-group past-epoch permanentlySkipped drain. */
@@ -1654,6 +2260,9 @@ export declare class BridgeAgent {
         /** SDK-6: cumulative rows ack-drained because their group_id is RETIRED for
          *  the channel (superseded fork-loser traffic). */
         retiredDrained: number;
+        expiredDrained: number;
+        /** INV-CUSTODY-DURABLE §5.C.3 custody health snapshot. */
+        custody: ReturnType<MlsGroupKeyProvider["custodyHealth"]>;
         welcomeRequestsSent: number;
         /** Track 5: cumulative artifact_share failures (download/decrypt/digest). */
         failedAttachments: number;