@medplum/agent 5.1.21 → 5.1.22

package/dist/cjs/index.cjs

@@ -5871,8 +5871,8 @@ var require_buffer_util = __commonJS({
       }
       return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.length);
     }
-    function toBuffer(data2) {
-      toBuffer.readOnly = true;
+    function toBuffer2(data2) {
+      toBuffer2.readOnly = true;
       if (Buffer.isBuffer(data2)) return data2;
       let buf;
       if (data2 instanceof ArrayBuffer) {
@@ -5881,7 +5881,7 @@ var require_buffer_util = __commonJS({
         buf = new FastBuffer(data2.buffer, data2.byteOffset, data2.byteLength);
       } else {
         buf = Buffer.from(data2);
-        toBuffer.readOnly = false;
+        toBuffer2.readOnly = false;
       }
       return buf;
     }
@@ -5889,7 +5889,7 @@ var require_buffer_util = __commonJS({
       concat,
       mask: _mask,
       toArrayBuffer,
-      toBuffer,
+      toBuffer: toBuffer2,
       unmask: _unmask
     };
     if (!process.env.WS_NO_BUFFER_UTIL) {
@@ -7187,7 +7187,7 @@ var require_sender = __commonJS({
     var PerMessageDeflate2 = require_permessage_deflate();
     var { EMPTY_BUFFER, kWebSocket, NOOP } = require_constants2();
     var { isBlob, isValidStatusCode } = require_validation();
-    var { mask: applyMask, toBuffer } = require_buffer_util();
+    var { mask: applyMask, toBuffer: toBuffer2 } = require_buffer_util();
     var kByteLength = /* @__PURE__ */ Symbol("kByteLength");
     var maskBuffer = Buffer.alloc(4);
     var RANDOM_POOL_SIZE = 8 * 1024;
@@ -7377,9 +7377,9 @@ var require_sender = __commonJS({
           byteLength = data2.size;
           readOnly = false;
         } else {
-          data2 = toBuffer(data2);
+          data2 = toBuffer2(data2);
           byteLength = data2.length;
-          readOnly = toBuffer.readOnly;
+          readOnly = toBuffer2.readOnly;
         }
         if (byteLength > 125) {
           throw new RangeError("The data size must not be greater than 125 bytes");
@@ -7424,9 +7424,9 @@ var require_sender = __commonJS({
           byteLength = data2.size;
           readOnly = false;
         } else {
-          data2 = toBuffer(data2);
+          data2 = toBuffer2(data2);
           byteLength = data2.length;
-          readOnly = toBuffer.readOnly;
+          readOnly = toBuffer2.readOnly;
         }
         if (byteLength > 125) {
           throw new RangeError("The data size must not be greater than 125 bytes");
@@ -7482,9 +7482,9 @@ var require_sender = __commonJS({
           byteLength = data2.size;
           readOnly = false;
         } else {
-          data2 = toBuffer(data2);
+          data2 = toBuffer2(data2);
           byteLength = data2.length;
-          readOnly = toBuffer.readOnly;
+          readOnly = toBuffer2.readOnly;
         }
         if (this._firstFragment) {
           this._firstFragment = false;
@@ -7554,7 +7554,7 @@ var require_sender = __commonJS({
             return;
           }
           this._bufferedBytes -= options[kByteLength];
-          const data2 = toBuffer(arrayBuffer);
+          const data2 = toBuffer2(arrayBuffer);
           if (!compress) {
             this._state = DEFAULT;
             this.sendFrame(_Sender.frame(data2, options), cb);
@@ -8081,7 +8081,7 @@ var require_websocket = __commonJS({
       EventTarget: { addEventListener, removeEventListener }
     } = require_event_target();
     var { format, parse } = require_extension();
-    var { toBuffer } = require_buffer_util();
+    var { toBuffer: toBuffer2 } = require_buffer_util();
     var kAborted = /* @__PURE__ */ Symbol("kAborted");
     var protocolVersions = [8, 13];
     var readyStates = ["CONNECTING", "OPEN", "CLOSING", "CLOSED"];
@@ -8829,7 +8829,7 @@ var require_websocket = __commonJS({
     }
     function sendAfterClose(websocket, data2, cb) {
       if (data2) {
-        const length2 = isBlob(data2) ? data2.size : toBuffer(data2).length;
+        const length2 = isBlob(data2) ? data2.size : toBuffer2(data2).length;
         if (websocket._socket) websocket._sender._bufferedBytes += length2;
         else websocket._bufferedAmount += length2;
       }
@@ -54825,7 +54825,7 @@ function lt(r6) {
   return r6.bareCriteria ? [r6.bareCriteria, ...r6.criteriaWithProps] : r6.criteriaWithProps;
 }
 var hc = new X(1e3);
-var yn = "5.1.21-747496a";
+var yn = "5.1.22-7350a53";
 var xc = k.FHIR_JSON + ", */*; q=0.1";
 var vc = "https://api.medplum.com/";
 var Tc = 1e3;
@@ -56056,11 +56056,11 @@ async function Dy(r6) {
 
 // src/main.ts
 var import_node_child_process3 = require("node:child_process");
-var import_node_fs7 = require("node:fs");
+var import_node_fs8 = require("node:fs");
 var import_node_path5 = __toESM(require("node:path"));
 
 // src/agent-main.ts
-var import_node_fs5 = require("node:fs");
+var import_node_fs6 = require("node:fs");
 
 // ../hl7/dist/esm/index.mjs
 var import_node_assert = __toESM(require("node:assert"), 1);
@@ -56435,7 +56435,7 @@ var x = class {
 // src/app.ts
 var import_node_assert3 = __toESM(require("node:assert"));
 var import_node_child_process = require("node:child_process");
-var import_node_fs4 = require("node:fs");
+var import_node_fs5 = require("node:fs");
 var import_node_net4 = require("node:net");
 var import_node_os4 = require("node:os");
 var import_node_process2 = __toESM(require("node:process"));
@@ -56597,9 +56597,11 @@ var AgentByteStreamChannel = class extends BaseChannel {
   }
   sendToRemote(msg) {
     const connection = this.connections.get(msg.remote);
-    if (connection) {
-      connection.write(Buffer.from(msg.body, "hex"));
+    if (!connection) {
+      return false;
     }
+    connection.write(Buffer.from(msg.body, "hex"));
+    return true;
   }
   handleNewConnection(socket) {
     const c2 = new ByteStreamChannelConnection(this, socket);
@@ -73620,6 +73622,410 @@ function calculateRttStats(rttSamples, pendingCount) {
   };
 }
 
+// src/queue/types.ts
+var MessageState = {
+  QUEUED: "queued",
+  CLAIMED: "claimed",
+  INFLIGHT: "inflight",
+  PROCESSED: "processed",
+  REJECTED: "rejected",
+  FAILED: "failed",
+  NACKED: "nacked"
+};
+var AckOutcome = {
+  PENDING: "pending",
+  DELIVERED: "delivered",
+  UNDELIVERED: "undelivered",
+  NOT_OWED: "not_owed"
+};
+var QueueErrorCode = {
+  /** Transient (`failed`): server returned 5xx. */
+  ServerError: "server-error",
+  /** Transient (`failed`): server returned 429. */
+  ServerRateLimited: "server-rate-limited",
+  /** Ambiguous (`failed`): timed out waiting for the server response; delivery unknown. */
+  ResponseTimeout: "response-timeout",
+  /** Ambiguous (`failed`): row was in `processing` when the agent restarted. */
+  Interrupted: "interrupted",
+  /** Ambiguous (`failed`): in-flight dispatch was cancelled by worker shutdown. */
+  WorkerStopped: "worker-stopped",
+  /** Ambiguous (`failed`): dispatch failed for an unclassified reason; delivery unknown. */
+  DispatchFailed: "dispatch-failed",
+  /** Permanent (`rejected`): server returned 4xx (other than 429) — the message was rejected. */
+  ServerRejected: "server-rejected",
+  /** Intake rejection (`nacked`): a storage error prevented the message from being committed. */
+  StorageError: "storage-error",
+  /** Intake rejection (`nacked`): the message reused a committed control ID (duplicate collision). */
+  DuplicateRejected: "duplicate-rejected"
+};
+var QueueError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    __publicField(this, "code");
+    this.code = code;
+  }
+};
+var QueueLeaseError = class extends Error {
+  constructor(localHolder, currentHolder) {
+    super(
+      `Queue lease held by a peer; this process is no longer leader (local holder=${localHolder ?? "unset"}, current holder=${currentHolder ?? "none"})`
+    );
+    /** The holder this process believes it is (the one bound via `setLeaseHolder`). */
+    __publicField(this, "localHolder");
+    /** The holder that actually owns the lease now (the peer that took over). */
+    __publicField(this, "currentHolder");
+    this.name = "QueueLeaseError";
+    this.localHolder = localHolder;
+    this.currentHolder = currentHolder;
+  }
+};
+var DuplicateBehavior = {
+  REJECT: "reject",
+  IDEMPOTENT: "idempotent"
+};
+
+// src/queue/worker.ts
+var DEFAULT_WORKER_RESPONSE_TIMEOUT_MS = 6e4;
+var DEFAULT_WORKER_IDLE_POLL_MS = 250;
+var RowRequeuedError = class extends Error {
+  constructor() {
+    super("row requeued after WebSocket disconnect");
+  }
+};
+var ChannelQueueWorker = class {
+  constructor(options) {
+    __publicField(this, "channelName");
+    __publicField(this, "app");
+    __publicField(this, "queue");
+    __publicField(this, "log");
+    __publicField(this, "responseTimeoutMs");
+    __publicField(this, "idlePollMs");
+    __publicField(this, "sendAck");
+    __publicField(this, "running", false);
+    __publicField(this, "stopping", false);
+    __publicField(this, "loopPromise");
+    // Resolves whenever `notify()` is called, then is replaced with a fresh promise.
+    // Lets the loop sleep without polling when the queue is known-empty.
+    __publicField(this, "wakeSignal");
+    __publicField(this, "pending");
+    /**
+     * In-flight lease check, fired on each App heartbeat tick (~10s). While a
+     * dispatch is awaiting the server, a worker can't notice via `claimNext` that a
+     * peer took the lease — it's wedged on the response. This cancels that wedged
+     * dispatch with a {@link QueueLeaseError} so the loop tears the worker down,
+     * instead of waiting out the full {@link DEFAULT_WORKER_RESPONSE_TIMEOUT_MS}. A
+     * no-op while no dispatch is pending — an idle worker detects loss far sooner on
+     * its next `claimNext` poll. An arrow field so add/removeEventListener share one
+     * stable reference.
+     */
+    __publicField(this, "onHeartbeat", () => {
+      const pending = this.pending;
+      if (!pending || !this.queue.isLeaseHeldByPeer()) {
+        return;
+      }
+      clearTimeout(pending.timeout);
+      this.pending = void 0;
+      pending.reject(new QueueLeaseError(void 0, this.queue.getCurrentLease()?.holder));
+    });
+    this.channelName = options.channelName;
+    this.app = options.app;
+    this.queue = options.queue;
+    this.log = options.log;
+    this.responseTimeoutMs = options.responseTimeoutMs ?? DEFAULT_WORKER_RESPONSE_TIMEOUT_MS;
+    this.idlePollMs = options.idlePollMs ?? DEFAULT_WORKER_IDLE_POLL_MS;
+    this.sendAck = options.sendAck;
+    this.wakeSignal = makeWakeSignal();
+  }
+  /** Starts the dispatch loop. No-op if already started. */
+  start() {
+    if (this.running) {
+      return;
+    }
+    this.running = true;
+    this.stopping = false;
+    this.app.heartbeatEmitter.addEventListener("heartbeat", this.onHeartbeat);
+    this.loopPromise = this.loop().catch((err2) => {
+      this.log.error(`Worker loop crashed: ${Re(err2)}`);
+    });
+  }
+  /**
+   * @returns True while the dispatch loop is live. Goes false after {@link stop}
+   * or after the worker self-terminates on lease loss — the channel checks this
+   * to reap a demoted worker before starting a fresh one on re-acquisition.
+   */
+  isRunning() {
+    return this.running;
+  }
+  /**
+   * Signals to the loop that work may be available. Idempotent; multiple calls
+   * before the loop wakes coalesce into a single wake.
+   */
+  notify() {
+    this.wakeSignal.resolve();
+  }
+  /**
+   * Routes a server `agent:transmit:response` to its row.
+   *
+   * The common case is the response to the current in-flight dispatch, which
+   * resolves the pending promise and lets {@link process} settle the row.
+   *
+   * A response can also arrive *late* — after the response timeout (or a requeue
+   * / worker stop) already cleared the pending dispatch and left the row
+   * `failed`. We don't discard those: the Medplum server is the authority on the
+   * Bot-leg outcome, so a late ACK/NACK for a row that errored and isn't being
+   * retried right now is applied to settle the row ({@link applyServerResponse}),
+   * exactly as if it had arrived in time. This disambiguates the ambiguous
+   * `ResponseTimeout` case — a row we couldn't classify becomes a definite
+   * `processed`/`rejected`/`failed` — and avoids a redundant re-dispatch.
+   * @param response - The response message received over the WS.
+   * @returns True if the response was applied or resolved a pending dispatch;
+   *          false if it could not be matched to a settleable row.
+   */
+  onServerResponse(response2) {
+    if (!response2.callback) {
+      return false;
+    }
+    const pending = this.pending;
+    if (pending?.row.callbackId === response2.callback) {
+      clearTimeout(pending.timeout);
+      this.pending = void 0;
+      pending.resolve(response2);
+      return true;
+    }
+    const row = this.queue.findByCallback(response2.callback);
+    if (!row) {
+      this.log.warn(`Discarding server response with no matching row (callback=${response2.callback})`);
+      return false;
+    }
+    if (row.state === MessageState.FAILED) {
+      this.log.info(
+        `Applying late server response to errored row id=${row.id} (control id=${row.msgControlId ?? "n/a"}, status=${response2.statusCode ?? "n/a"})`
+      );
+      try {
+        this.applyServerResponse(row, response2);
+      } catch (err2) {
+        if (err2 instanceof QueueLeaseError) {
+          this.log.info(`Discarding late server response for row id=${row.id}: queue lease held by a peer`);
+          return false;
+        }
+        throw err2;
+      }
+      return true;
+    }
+    this.log.warn(
+      `Discarding server response for row id=${row.id} in state '${row.state}' (callback=${response2.callback})`
+    );
+    return false;
+  }
+  /**
+   * Stops the dispatch loop. Cancels any in-flight dispatch by rejecting its
+   * pending response Promise with `worker-stopped` — an ambiguous outcome (we
+   * don't know whether the server processed the message). The row is marked
+   * `failed` for operator review; an operator decides whether to replay.
+   */
+  async stop() {
+    if (!this.running) {
+      return;
+    }
+    this.stopping = true;
+    this.app.heartbeatEmitter.removeEventListener("heartbeat", this.onHeartbeat);
+    if (this.pending) {
+      const pending = this.pending;
+      clearTimeout(pending.timeout);
+      this.pending = void 0;
+      pending.reject(new QueueError(QueueErrorCode.WorkerStopped, "worker stopping"));
+    }
+    this.notify();
+    if (this.loopPromise) {
+      await this.loopPromise;
+    }
+    this.running = false;
+  }
+  /** @returns True if a row is currently in-flight (worker awaiting a server response). */
+  hasInFlight() {
+    return this.pending !== void 0;
+  }
+  /**
+   * Called from `app.ts` when the agent WebSocket closes. If the in-flight
+   * row's `agent:transmit:request` is still sitting unsent in the app's WS
+   * queue, the server provably never saw it — remove it and return the row to
+   * `queued` so it retries on reconnect instead of timing out into `failed`.
+   *
+   * If the request already went out on the wire, the outcome is ambiguous (the
+   * server may have processed it and the response was lost), so we leave the
+   * pending dispatch alone and let the response timeout mark it `errored`.
+   */
+  onWebSocketDisconnect() {
+    const pending = this.pending;
+    if (!pending) {
+      return;
+    }
+    if (!this.app.removeUnsentTransmit(pending.row.callbackId)) {
+      return;
+    }
+    clearTimeout(pending.timeout);
+    this.pending = void 0;
+    try {
+      this.queue.requeue(pending.row.id);
+    } catch (err2) {
+      if (err2 instanceof QueueLeaseError) {
+        pending.reject(err2);
+        return;
+      }
+      throw err2;
+    }
+    this.log.info(
+      `Row id=${pending.row.id} (control id=${pending.row.msgControlId ?? "n/a"}) requeued: WebSocket disconnected before transmit was sent`
+    );
+    pending.reject(new RowRequeuedError());
+  }
+  async loop() {
+    try {
+      while (!this.stopping) {
+        if (!this.app.isLive()) {
+          await this.waitForWork();
+          continue;
+        }
+        const row = this.queue.claimNext(this.channelName);
+        if (row) {
+          await this.process(row);
+        } else {
+          await this.waitForWork();
+        }
+      }
+    } catch (err2) {
+      if (!(err2 instanceof QueueLeaseError)) {
+        throw err2;
+      }
+      this.log.info(`Worker for channel '${this.channelName}' stepping down: queue lease taken by a peer.`);
+      this.stopping = true;
+      this.app.heartbeatEmitter.removeEventListener("heartbeat", this.onHeartbeat);
+      this.running = false;
+    }
+  }
+  async process(row) {
+    let response2;
+    try {
+      response2 = await this.dispatch(row);
+    } catch (err2) {
+      if (err2 instanceof RowRequeuedError) {
+        return;
+      }
+      if (err2 instanceof QueueLeaseError) {
+        throw err2;
+      }
+      const code = err2 instanceof QueueError ? err2.code : QueueErrorCode.DispatchFailed;
+      const msg = Re(err2);
+      this.queue.markFailed(row.id, msg, code);
+      this.log.error(
+        `Row id=${row.id} (control id=${row.msgControlId ?? "n/a"}) failed during dispatch (${code}): ${msg}`
+      );
+      return;
+    }
+    this.applyServerResponse(row, response2);
+  }
+  /**
+   * Settles a row from its server `agent:transmit:response`: records the raw
+   * response, then transitions the row by status — 2xx → `processed` (plus the
+   * source-leg ACK), permanent 4xx → `rejected`, 5xx/429 → `failed`.
+   *
+   * Shared by the normal in-flight path ({@link process}) and the late-response
+   * path ({@link onServerResponse}), so a response that arrives after the
+   * response timeout settles the row identically to one that arrived in time.
+   * @param row - The row the response belongs to.
+   * @param response - The server response to apply.
+   */
+  applyServerResponse(row, response2) {
+    this.queue.recordServerResponse(row.id, response2.statusCode ?? null, response2.body ?? null);
+    const statusCode = response2.statusCode ?? 0;
+    if (statusCode >= 400) {
+      const msg = `Server returned ${statusCode}: ${response2.body ?? ""}`;
+      const code = classifyStatusCode(statusCode);
+      if (code === QueueErrorCode.ServerRejected) {
+        this.queue.markRejected(row.id, msg, code);
+      } else {
+        this.queue.markFailed(row.id, msg, code);
+      }
+      this.log.warn(`Row id=${row.id} (control id=${row.msgControlId ?? "n/a"}) ${code}: ${msg}`);
+      return;
+    }
+    if (row.enhancedMode === "aaMode") {
+      this.queue.markProcessed(row.id, AckOutcome.DELIVERED);
+      this.log.debug(
+        `Row id=${row.id} (control id=${row.msgControlId ?? "n/a"}) processed; app-level AA suppressed (aaMode commit ACK already acknowledged the source)`
+      );
+      return;
+    }
+    let ackOk = false;
+    let ackError;
+    try {
+      ackOk = this.sendAck(response2, row);
+    } catch (err2) {
+      ackError = err2;
+    }
+    this.queue.markProcessed(row.id, ackOk ? AckOutcome.DELIVERED : AckOutcome.UNDELIVERED);
+    if (!ackOk) {
+      const detail = ackError ? `: ${Re(ackError)}` : "";
+      this.log.warn(
+        `Row id=${row.id} (control id=${row.msgControlId ?? "n/a"}) processed upstream but ACK delivery to source failed${detail}; awaiting source retransmit to replay`
+      );
+    }
+  }
+  async dispatch(row) {
+    return new Promise((resolve2, reject) => {
+      const timeout = setTimeout(() => {
+        if (this.pending?.row.id === row.id) {
+          this.pending = void 0;
+        }
+        reject(
+          new QueueError(
+            QueueErrorCode.ResponseTimeout,
+            `Timed out after ${this.responseTimeoutMs}ms waiting for server response`
+          )
+        );
+      }, this.responseTimeoutMs);
+      if (typeof timeout.unref === "function") {
+        timeout.unref();
+      }
+      this.pending = { row, resolve: resolve2, reject, timeout };
+      this.app.addToWebSocketQueue({
+        type: "agent:transmit:request",
+        accessToken: "placeholder",
+        channel: row.channelName,
+        remote: row.remote,
+        contentType: k.HL7_V2,
+        // finalizedMessage holds the decoded HL7 text stored as UTF-8 at intake
+        // (see AgentHl7ChannelConnection.handleMessage) — the same body the legacy
+        // path forwards. The channel `encoding` is wire-level only and recorded
+        // on the row for reference; it does not affect the forwarded text.
+        body: row.finalizedMessage.toString("utf8"),
+        callback: row.callbackId
+      });
+    });
+  }
+  async waitForWork() {
+    const wake = this.wakeSignal;
+    this.wakeSignal = makeWakeSignal();
+    await Promise.race([wake.promise, rn(this.idlePollMs)]);
+  }
+};
+function classifyStatusCode(statusCode) {
+  if (statusCode === 429) {
+    return QueueErrorCode.ServerRateLimited;
+  }
+  if (statusCode >= 500) {
+    return QueueErrorCode.ServerError;
+  }
+  return QueueErrorCode.ServerRejected;
+}
+function makeWakeSignal() {
+  let resolve2;
+  const promise = new Promise((r6) => {
+    resolve2 = r6;
+  });
+  return { promise, resolve: resolve2 };
+}
+
 // src/stats.ts
 var currentStats = {
   hl7ConnectionsOpen: 0,
@@ -73649,6 +74055,14 @@ var AgentHl7Channel = class extends BaseChannel {
     // Default app level ack mode is AL (Always)
     __publicField(this, "assignSeqNo", false);
     __publicField(this, "lastSeqNo", -1);
+    __publicField(this, "duplicateBehavior", DuplicateBehavior.IDEMPOTENT);
+    // The channel's own copy of the enhanced mode, parsed from the endpoint URL.
+    // In durable mode this is intentionally NOT pushed onto the Hl7Connection (so
+    // the connection's synchronous auto-ACK stays off and the agent can defer the
+    // commit ACK until after the DB write); the connection therefore can't be the
+    // source of truth, so we track it here and the durable path reads it directly.
+    __publicField(this, "enhancedMode");
+    __publicField(this, "worker");
     this.server = new x((connection) => this.handleNewConnection(connection));
     this.prefix = `[HL7:${definition.name}] `;
     this.log = app.log.clone({ options: { prefix: this.prefix } });
@@ -73664,6 +74078,7 @@ var AgentHl7Channel = class extends BaseChannel {
     this.log.info(`Channel starting on ${address}...`);
     this.stats = new ChannelStatsTracker({ heartbeatEmitter: this.app.heartbeatEmitter, log: this.log });
     this.configureHl7ServerAndConnections();
+    this.maybeStartWorker();
     await this.server.start(Number.parseInt(address.port, 10));
     this.log.info("Channel started successfully");
   }
@@ -73672,45 +74087,102 @@ var AgentHl7Channel = class extends BaseChannel {
       return;
     }
     this.log.info("Channel stopping...");
+    if (this.worker) {
+      await this.worker.stop();
+      this.worker = void 0;
+    }
     await Promise.allSettled(Array.from(this.connections.values()).map((connection) => connection.close()));
     await this.server.stop();
     this.stats.cleanup();
     this.started = false;
     this.log.info("Channel stopped successfully");
   }
+  /**
+   * Starts a {@link ChannelQueueWorker} bound to this channel and the app's
+   * durable queue, but only if we currently hold the queue lease.
+   *
+   * Called both from `start()` (when leadership may already be established by
+   * the time the channel comes up) and from `onBecameQueueLeader()` (when
+   * leadership arrives later, e.g. after waiting out a peer's lease during a
+   * zero-downtime upgrade overlap).
+   *
+   * No-op when the queue is off, we're not leader, or the worker is already
+   * running — so it's safe to call from either entry point.
+   */
+  maybeStartWorker() {
+    if (this.worker && !this.worker.isRunning()) {
+      this.worker = void 0;
+    }
+    if (this.worker) {
+      return;
+    }
+    const queue = this.app.getDurableQueue();
+    if (!queue?.isLeader()) {
+      return;
+    }
+    this.worker = new ChannelQueueWorker({
+      channelName: this.getDefinition().name,
+      app: this.app,
+      queue,
+      log: this.log,
+      sendAck: (response2) => this.sendToRemote(response2)
+    });
+    this.worker.start();
+    this.worker.notify();
+  }
+  /**
+   * Notification from the App that we've taken the durable-queue lease.
+   * Triggers worker bring-up for this channel if it isn't already running.
+   */
+  onBecameQueueLeader() {
+    this.maybeStartWorker();
+  }
   shouldAssignSeqNo() {
     return this.assignSeqNo;
   }
+  /**
+   * Returns the next MSH.13 sequence number from the in-memory counter (resets
+   * on restart). Used only by the legacy (non-durable) path; the durable path
+   * peeks/commits a persisted per-channel counter via the queue so a failed
+   * intake doesn't consume a number. See {@link DurableQueue.peekNextSeqNo}.
+   * @returns The next sequence number to assign.
+   */
   takeNextSeqNo() {
     return ++this.lastSeqNo;
   }
   sendToRemote(msg) {
     const connection = this.connections.get(msg.remote);
-    if (connection) {
-      const hl7Message = Wo.parse(msg.body);
-      const msgControlId = hl7Message.getSegment("MSA")?.getField(2)?.toString();
-      const ackCode = hl7Message.getSegment("MSA")?.getField(1)?.toString()?.toUpperCase();
-      if (ackCode && isAppLevelAckCode(ackCode) && !shouldSendAppLevelAck({
-        mode: this.appLevelAckMode,
-        ackCode,
-        enhancedMode: this.server.getEnhancedMode()
-      })) {
-        this.channelLog.debug(
-          `[Skipping ACK -- Mode: ${this.appLevelAckMode} -- ID: ${msgControlId ?? "not provided"} -- ACK: ${ackCode ?? "unknown"}]`
-        );
-        if (msgControlId) {
-          this.stats.recordAckReceived(msgControlId);
-        }
-        return;
-      }
-      this.channelLog.info(`[Sending ACK -- ID: ${msgControlId}]: ${hl7Message.toString().replaceAll("\r", "\n")}`);
-      connection.hl7Connection.send(Wo.parse(msg.body));
+    if (!connection) {
+      this.log.warn(`Attempted to send message to disconnected remote: ${msg.remote}`);
+      return false;
+    }
+    const hl7Message = Wo.parse(msg.body);
+    const msgControlId = hl7Message.getSegment("MSA")?.getField(2)?.toString();
+    const ackCode = hl7Message.getSegment("MSA")?.getField(1)?.toString()?.toUpperCase();
+    if (ackCode && isAppLevelAckCode(ackCode) && !shouldSendAppLevelAck({
+      mode: this.appLevelAckMode,
+      ackCode,
+      enhancedMode: this.enhancedMode
+    })) {
+      this.channelLog.debug(
+        `[Skipping ACK -- Mode: ${this.appLevelAckMode} -- ID: ${msgControlId ?? "not provided"} -- ACK: ${ackCode ?? "unknown"}]`
+      );
       if (msgControlId) {
         this.stats.recordAckReceived(msgControlId);
       }
-    } else {
-      this.log.warn(`Attempted to send message to disconnected remote: ${msg.remote}`);
+      return true;
     }
+    this.channelLog.info(`[Sending ACK -- ID: ${msgControlId}]: ${hl7Message.toString().replaceAll("\r", "\n")}`);
+    try {
+      connection.hl7Connection.send(Wo.parse(msg.body));
+    } catch (err2) {
+      this.channelLog.error(`Failed to send ACK to ${msg.remote}: ${Re(err2)}`);
+      return false;
+    }
+    if (msgControlId) {
+      this.stats.recordAckReceived(msgControlId);
+    }
+    return true;
   }
   async reloadConfig(definition, endpoint) {
     const previousEndpoint = this.endpoint;
@@ -73744,6 +74216,7 @@ var AgentHl7Channel = class extends BaseChannel {
     const assignSeqNo = address.searchParams.get("assignSeqNo")?.toLowerCase() === "true";
     const messagesPerMinRaw = address.searchParams.get("messagesPerMin") ?? void 0;
     const appLevelAckRaw = address.searchParams.get("appLevelAck") ?? void 0;
+    const duplicateBehaviorRaw = address.searchParams.get("duplicateBehavior") ?? void 0;
     let messagesPerMin = messagesPerMinRaw ? Number.parseInt(messagesPerMinRaw, 10) : void 0;
     if (messagesPerMin !== void 0 && !Number.isInteger(messagesPerMin)) {
       this.log.warn(
@@ -73753,18 +74226,33 @@ var AgentHl7Channel = class extends BaseChannel {
     }
     this.appLevelAckMode = parseAppLevelAckMode(appLevelAckRaw, this.log);
     this.assignSeqNo = assignSeqNo;
+    this.duplicateBehavior = parseDuplicateBehavior(duplicateBehaviorRaw, this.log);
     if (!assignSeqNo) {
       this.lastSeqNo = -1;
     }
+    this.enhancedMode = enhancedMode;
+    const queueOn = this.app.getDurableQueue() !== void 0;
+    const connectionEnhancedMode = queueOn ? void 0 : enhancedMode;
     this.server.setEncoding(encoding);
-    this.server.setEnhancedMode(enhancedMode);
+    this.server.setEnhancedMode(connectionEnhancedMode);
     this.server.setMessagesPerMin(messagesPerMin);
     for (const connection of this.connections.values()) {
       connection.hl7Connection.setEncoding(encoding);
-      connection.hl7Connection.setEnhancedMode(enhancedMode);
+      connection.hl7Connection.setEnhancedMode(connectionEnhancedMode);
       connection.hl7Connection.setMessagesPerMin(messagesPerMin);
     }
   }
+  getDuplicateBehavior() {
+    return this.duplicateBehavior;
+  }
+  /**
+   * @returns The channel's enhanced mode, as parsed from the endpoint URL. This is
+   * the agent's source of truth in durable mode, where enhancedMode is deliberately
+   * kept off the underlying {@link Hl7Connection} (see {@link enhancedMode}).
+   */
+  getEnhancedMode() {
+    return this.enhancedMode;
+  }
   handleNewConnection(connection) {
     const c2 = new AgentHl7ChannelConnection(this, connection);
     updateStat("hl7ConnectionsOpen", getCurrentStats().hl7ConnectionsOpen + 1);
@@ -73798,44 +74286,353 @@ var AgentHl7ChannelConnection = class {
       this.channel.channelLog.info(
         `[Received -- ID: ${msgControlId ?? "not provided"}]: ${event.message.toString().replaceAll("\r", "\n")}`
       );
-      if (this.channel.shouldAssignSeqNo()) {
-        const seqNo = this.channel.takeNextSeqNo();
-        event.message.getSegment("MSH")?.setField(13, seqNo.toString());
-        this.channel.channelLog.info(`Setting sequence number for message control ID '${msgControlId}': ${seqNo}`);
-      }
-      this.channel.app.addToWebSocketQueue({
-        type: "agent:transmit:request",
-        accessToken: "placeholder",
-        channel: this.channel.getDefinition().name,
-        remote: this.remote,
-        contentType: k.HL7_V2,
-        body: event.message.toString(),
-        callback: `Agent/${this.channel.app.agentId}-${(0, import_node_crypto3.randomUUID)()}`
-      });
+      const originalMessage = Buffer.from(event.message.toString(), "utf8");
       if (msgControlId) {
         this.channel.stats.recordMessageSent(msgControlId);
       }
+      const queue = this.channel.app.getDurableQueue();
+      if (queue) {
+        await this.handleMessageDurable(queue, event, msgControlId, originalMessage);
+      } else {
+        this.handleMessageLegacy(event, msgControlId);
+      }
     } catch (err2) {
       this.channel.log.error(`HL7 error occurred - check channel logs`);
       this.channel.channelLog.error(`HL7 error: ${Re(err2)}`);
     }
   }
+  /**
+   * Legacy non-durable inbound path: push directly to the in-memory WS queue.
+   * Behavior unchanged from the pre-durable-queue agent — used when the
+   * `durableQueue` setting is off.
+   * @param event - The incoming HL7 message event from the underlying connection.
+   * @param msgControlId - MSH.10 of the inbound message.
+   */
+  handleMessageLegacy(event, msgControlId) {
+    this.maybeAssignSeqNo(event, msgControlId);
+    this.channel.app.addToWebSocketQueue({
+      type: "agent:transmit:request",
+      accessToken: "placeholder",
+      channel: this.channel.getDefinition().name,
+      remote: this.remote,
+      contentType: k.HL7_V2,
+      body: event.message.toString(),
+      callback: `Agent/${this.channel.app.agentId}-${(0, import_node_crypto3.randomUUID)()}`
+    });
+  }
+  /**
+   * Assigns the next channel sequence number into MSH.13 when assignSeqNo is on.
+   * The durable path calls this only after the duplicate check, so retransmits
+   * don't consume a sequence number; the legacy path calls it on every message.
+   * @param event - The inbound message event whose MSH.13 to set.
+   * @param msgControlId - MSH.10, for logging only.
+   */
+  maybeAssignSeqNo(event, msgControlId) {
+    if (!this.channel.shouldAssignSeqNo()) {
+      return;
+    }
+    const seqNo = this.channel.takeNextSeqNo();
+    event.message.getSegment("MSH")?.setField(13, seqNo.toString());
+    this.channel.channelLog.info(`Setting sequence number for message control ID '${msgControlId ?? "n/a"}': ${seqNo}`);
+  }
+  /**
+   * Parses MSH.13 as a non-negative integer sequence number.
+   * @param event - The inbound message event.
+   * @returns The parsed sequence number, or null when MSH.13 is absent/non-numeric.
+   */
+  parseSeqNo(event) {
+    const seqNoField = event.message.getSegment("MSH")?.getField(13)?.toString();
+    return seqNoField && /^\d+$/.test(seqNoField) ? Number.parseInt(seqNoField, 10) : null;
+  }
+  /**
+   * Durable inbound path (§8 of DURABLE_QUEUE_ARCHITECTURE.md):
+   *
+   *  1. INSERT a `queued` row.
+   *  2. On success, send CA/AA via the deferred-ack API — only now is the
+   *     sender allowed to drop their retransmit buffer.
+   *  3. Notify the channel worker so it picks the row up immediately.
+   *
+   * Duplicate handling — a prior non-`nacked` row already owns this MSH.10
+   * (in any state: queued/processing/processed/errored — see {@link handleDuplicate}):
+   *  - `idempotent`: if the re-sent body matches the prior copy byte-for-byte,
+   *    replay the prior server response ACK (or, if none yet, the commit ACK);
+   *    if it differs, send AR — a different message reused a committed control ID.
+   *  - `reject`: send CR (or AR in aaMode); insert a `nacked` audit row.
+   *
+   * Storage failure: send CR with the underlying error in MSA.3; best-effort
+   * insert a `nacked` audit row (which may itself fail if the DB is unwritable —
+   * intentional, not retried).
+   * @param queue - The app-owned durable queue handle.
+   * @param event - The incoming HL7 message event from the underlying connection.
+   * @param msgControlId - MSH.10 of the inbound message (may be undefined for malformed messages).
+   * @param originalMessage - The message exactly as received, before any transformation (for dedup comparison).
+   */
+  async handleMessageDurable(queue, event, msgControlId, originalMessage) {
+    const conn = this.hl7Connection;
+    const enhancedMode = this.channel.getEnhancedMode();
+    const enhancedModeColumn = enhancedMode ?? null;
+    const channelName = this.channel.getDefinition().name;
+    const msgType = event.message.getSegment("MSH")?.getField(9)?.toString() ?? null;
+    const callbackId = `Agent/${this.channel.app.agentId}-${(0, import_node_crypto3.randomUUID)()}`;
+    const receivedAt = Date.now();
+    const assigning = this.channel.shouldAssignSeqNo();
+    let finalizedMessage = originalMessage;
+    let seqNo = this.parseSeqNo(event);
+    let result;
+    try {
+      result = queue.enqueue(
+        {
+          channelName,
+          remote: this.remote,
+          msgControlId: msgControlId ?? null,
+          msgType,
+          originalMessage,
+          finalizedMessage,
+          encoding: conn.getEncoding() ?? null,
+          enhancedMode: enhancedModeColumn,
+          callbackId,
+          seqNo,
+          receivedAt
+        },
+        assigning ? {
+          assignSeqNo: (candidate) => {
+            event.message.getSegment("MSH")?.setField(13, candidate.toString());
+            this.channel.channelLog.info(
+              `Setting sequence number for message control ID '${msgControlId ?? "n/a"}': ${candidate}`
+            );
+            finalizedMessage = Buffer.from(event.message.toString(), "utf8");
+            seqNo = candidate;
+            return finalizedMessage;
+          }
+        } : void 0
+      );
+    } catch (err2) {
+      const reason = `storage error: ${Re(err2)}`;
+      this.channel.channelLog.error(`Durable enqueue failed for ${msgControlId ?? "no-id"}: ${reason}`);
+      this.sendCommitNack(event.message, enhancedMode === "aaMode" ? "AE" : "CE", "storage error");
+      this.recordImmediateAck(msgControlId);
+      queue.enqueueRejected({
+        channelName,
+        remote: this.remote,
+        msgControlId: msgControlId ?? null,
+        msgType,
+        originalMessage,
+        finalizedMessage,
+        encoding: conn.getEncoding() ?? null,
+        enhancedMode: enhancedModeColumn,
+        callbackId,
+        seqNo,
+        receivedAt,
+        lastError: reason,
+        errorCode: QueueErrorCode.StorageError
+      });
+      return;
+    }
+    if (result.kind === "duplicate") {
+      this.handleDuplicate(queue, event, result.existing, msgControlId, {
+        callbackId,
+        msgType,
+        originalMessage,
+        finalizedMessage,
+        enhancedModeColumn,
+        seqNo,
+        receivedAt
+      });
+      return;
+    }
+    this.sendCommitAck(event.message);
+    this.recordImmediateAck(msgControlId);
+    this.channel.worker?.notify();
+  }
+  /**
+   * Handles an inbound message whose `(channel, MSH.10)` already belongs to a
+   * prior non-`nacked` row (`existing`), per the channel's `duplicateBehavior`:
+   *
+   * - `reject`: reject every collision (CR, or AR in aaMode) and write a
+   *   `nacked` audit row — unchanged, now spanning all prior states.
+   * - `idempotent` (default): treat a byte-for-byte re-send as a benign
+   *   retransmit and replay the acknowledgment the sender missed —
+   *   {@link AgentHl7Channel.sendToRemote the prior server response ACK} if the
+   *   message was already dispatched, otherwise the commit ACK (CA/AA). A body
+   *   that differs is a *different* message reusing a committed control ID, so
+   *   we reject it with AR (and a `nacked` audit row) the same way `reject`
+   *   handles any duplicate.
+   *
+   * The replayed ACKs go through {@link sendCommitAck}/{@link sendCommitNack} just
+   * like a fresh message — a retransmit means the sender never saw the original
+   * ACK and must be re-told, and the durable row is the dedup authority.
+   * @param queue - The app-owned durable queue handle.
+   * @param event - The duplicate inbound message event.
+   * @param existing - The prior row that owns this MSH.10.
+   * @param msgControlId - MSH.10 of the inbound message.
+   * @param audit - Decoded fields of the inbound message, for any `nacked` audit row.
+   * @param audit.callbackId - Callback ID minted for this inbound message.
+   * @param audit.msgType - MSH.9 message type.
+   * @param audit.originalMessage - Bytes as received (compared against the prior row's original_message).
+   * @param audit.finalizedMessage - Bytes as transformed for dispatch (persisted on any audit row).
+   * @param audit.enhancedModeColumn - Enhanced-mode column value to persist.
+   * @param audit.seqNo - Sequence number (MSH.13), if any.
+   * @param audit.receivedAt - Intake timestamp (ms).
+   */
+  handleDuplicate(queue, event, existing, msgControlId, audit) {
+    const conn = this.hl7Connection;
+    const enhancedMode = this.channel.getEnhancedMode();
+    const idLabel = msgControlId ?? "n/a";
+    const behavior = this.channel.getDuplicateBehavior();
+    if (behavior === DuplicateBehavior.IDEMPOTENT && existing.originalMessage.equals(audit.originalMessage)) {
+      if (existing.serverResponseBody && existing.serverResponseBody.length > 0 && this.replayServerAck(existing)) {
+        if (existing.ackOutcome === AckOutcome.UNDELIVERED) {
+          queue.setAckOutcome(existing.id, AckOutcome.DELIVERED);
+        }
+        this.channel.channelLog.info(
+          `[Duplicate idempotent -- ID: ${idLabel}] replayed prior server response ACK from row id=${existing.id}`
+        );
+        return;
+      }
+      this.channel.channelLog.info(
+        `[Duplicate idempotent -- ID: ${idLabel}] replayed commit ACK for prior row id=${existing.id}`
+      );
+      this.sendCommitAck(event.message);
+      this.recordImmediateAck(msgControlId);
+      return;
+    }
+    const contentMismatch = behavior === DuplicateBehavior.IDEMPOTENT;
+    const reason = contentMismatch ? `duplicate control id ${idLabel}: a message with this control ID was already committed with different content` : "duplicate control id";
+    this.channel.channelLog.warn(`[Duplicate rejected -- ID: ${idLabel}] prior row id=${existing.id}: ${reason}`);
+    this.sendCommitNack(event.message, enhancedMode === "aaMode" ? "AR" : "CR", reason);
+    this.recordImmediateAck(msgControlId);
+    queue.enqueueRejected({
+      channelName: this.channel.getDefinition().name,
+      remote: this.remote,
+      msgControlId: msgControlId ?? null,
+      msgType: audit.msgType,
+      originalMessage: audit.originalMessage,
+      finalizedMessage: audit.finalizedMessage,
+      encoding: conn.getEncoding() ?? null,
+      enhancedMode: audit.enhancedModeColumn,
+      callbackId: audit.callbackId,
+      seqNo: audit.seqNo,
+      receivedAt: audit.receivedAt,
+      lastError: reason,
+      errorCode: QueueErrorCode.DuplicateRejected
+    });
+  }
+  /**
+   * Balances {@link ChannelStatsTracker} for a message we answered synchronously
+   * at intake (duplicate replay / reject / storage-error NACK). `handleMessage`
+   * already called `recordMessageSent`; without this the control ID would linger
+   * in the pending map until the 5-minute GC, skewing pendingCount and RTT.
+   * @param msgControlId - MSH.10 of the message just answered, if present.
+   */
+  recordImmediateAck(msgControlId) {
+    if (msgControlId) {
+      this.channel.stats.recordAckReceived(msgControlId);
+    }
+  }
+  /**
+   * Replays the stored server response ACK for an already-dispatched duplicate,
+   * routing it through {@link AgentHl7Channel.sendToRemote} so the same
+   * app-level ACK policy and encoding apply as on the original delivery.
+   * @param existing - The prior row whose `serverResponseBody` to replay.
+   * @returns True if the response ACK was delivered; false if it couldn't be parsed/sent.
+   */
+  replayServerAck(existing) {
+    if (!existing.serverResponseBody) {
+      return false;
+    }
+    try {
+      return this.channel.sendToRemote({
+        type: "agent:transmit:response",
+        channel: this.channel.getDefinition().name,
+        remote: this.remote,
+        contentType: k.HL7_V2,
+        body: existing.serverResponseBody.toString("utf8"),
+        callback: existing.callbackId
+      });
+    } catch (err2) {
+      this.channel.channelLog.warn(
+        `[Duplicate idempotent] failed to replay server response ACK for row id=${existing.id}: ${Re(err2)}`
+      );
+      return false;
+    }
+  }
   async handleError(event) {
     this.channel.log.error(`HL7 connection error: ${Re(event.error)}`);
     this.channel.channelLog.error(`HL7 connection error: ${Re(event.error)}`);
   }
+  /**
+   * Sends the commit ACK (CA in `standard` enhanced mode, AA in `aaMode`) for an
+   * inbound message that has been durably committed. No-op outside enhanced mode.
+   *
+   * This is the durable path's replacement for the connection's synchronous
+   * auto-ACK: in durable mode the connection carries no enhancedMode (so it never
+   * auto-ACKs), and the agent calls this only after the DB write succeeds — so the
+   * CA/AA is a real promise that the message is on disk. Idempotency is not enforced
+   * here; the on-disk row (channel + MSH.10) is the dedup authority, and a genuine
+   * retransmit must be re-ACKed because the sender never saw the original.
+   * @param message - The original inbound message to ACK.
+   */
+  sendCommitAck(message) {
+    const enhancedMode = this.channel.getEnhancedMode();
+    if (!enhancedMode) {
+      return;
+    }
+    const ackCode = enhancedMode === "standard" ? "CA" : "AA";
+    const response2 = message.buildAck({ ackCode });
+    this.hl7Connection.send(response2);
+    this.hl7Connection.dispatchEvent(new E(this.hl7Connection, response2));
+  }
+  /**
+   * Sends a negative commit ACK for an inbound message. The wire code is CE/CR in
+   * `standard` enhanced mode and AE/AR in `aaMode` (error = retryable, reject =
+   * terminal); the caller picks which best describes the failure. An optional
+   * `reason` is written to MSA.3 for the sender's logs. No-op outside enhanced mode.
+   * @param message - The original inbound message to NACK.
+   * @param code - The negative ACK code to send.
+   * @param reason - Optional human-readable explanation placed in MSA.3.
+   */
+  sendCommitNack(message, code, reason) {
+    const enhancedMode = this.channel.getEnhancedMode();
+    if (!enhancedMode) {
+      return;
+    }
+    const response2 = message.buildAck({ ackCode: code });
+    if (reason) {
+      response2.getSegment("MSA")?.setField(3, reason);
+    }
+    this.hl7Connection.send(response2);
+    this.hl7Connection.dispatchEvent(new E(this.hl7Connection, response2));
+  }
   handleEnhancedAckSent(event) {
     const hl7Message = event.message;
     const msgControlId = hl7Message.getSegment("MSA")?.getField(2)?.toString();
     const ackCode = hl7Message.getSegment("MSA")?.getField(1)?.toString()?.toUpperCase();
     this.channel.channelLog.info(
-      `[Sent ${ackCode === "CA" ? "Commit ACK (CA)" : "Immediate ACK (AA)"} -- ID: ${msgControlId ?? "not provided"}]: ${hl7Message.toString().replaceAll("\r", "\n")}`
+      `[Sent ${describeAckCode(ackCode)} -- ID: ${msgControlId ?? "not provided"}]: ${hl7Message.toString().replaceAll("\r", "\n")}`
     );
   }
   close() {
     return this.hl7Connection.close();
   }
 };
+function describeAckCode(code) {
+  switch (code) {
+    case "CA":
+      return "Commit ACK (CA)";
+    case "AA":
+      return "App ACK (AA)";
+    case "CE":
+      return "Commit Error (CE)";
+    case "CR":
+      return "Commit Reject (CR)";
+    case "AE":
+      return "App Error (AE)";
+    case "AR":
+      return "App Reject (AR)";
+    default:
+      return `ACK (${code ?? "unknown"})`;
+  }
+}
 function parseEnhancedMode(rawValue, logger) {
   if (!rawValue) {
     return void 0;
@@ -73869,6 +74666,17 @@ function isAppLevelAckCode(code) {
 function isAppLevelAckMode(candidate) {
   return APP_LEVEL_ACK_MODES.includes(candidate);
 }
+function parseDuplicateBehavior(rawValue, logger) {
+  if (!rawValue) {
+    return DuplicateBehavior.IDEMPOTENT;
+  }
+  const normalized = rawValue.toLowerCase();
+  if (normalized === DuplicateBehavior.REJECT || normalized === DuplicateBehavior.IDEMPOTENT) {
+    return normalized;
+  }
+  logger.warn(`Invalid duplicateBehavior value '${rawValue}'; expected 'reject' or 'idempotent'. Using idempotent.`);
+  return DuplicateBehavior.IDEMPOTENT;
+}
 function shouldSendAppLevelAck(options) {
   const { mode, ackCode, enhancedMode } = options;
   if (!enhancedMode) {
@@ -74641,8 +75449,1355 @@ function registerAgentCleanup() {
   }
 }
 
-// src/upgrader-utils.ts
+// src/queue/durable-queue.ts
+var import_node_crypto4 = require("node:crypto");
 var import_node_fs3 = require("node:fs");
+
+// src/queue/queries.ts
+var ENQUEUE = `
+  INSERT INTO inbound_hl7_messages (
+    channel_name, remote, msg_control_id, msg_type, original_message, finalized_message, encoding,
+    enhanced_mode, state, attempt_count, callback_id,
+    seq_no, received_at
+  ) VALUES (
+    ?, ?, ?, ?, ?, ?, ?, ?, 'queued', 0, ?, ?, ?
+  )
+`;
+var ENQUEUE_REJECTED = `
+  INSERT INTO inbound_hl7_messages (
+    channel_name, remote, msg_control_id, msg_type, original_message, finalized_message, encoding,
+    enhanced_mode, state, attempt_count, callback_id,
+    ack_outcome, last_error, error_code, seq_no, received_at
+  ) VALUES (
+    ?, ?, ?, ?, ?, ?, ?, ?, 'nacked', 0, ?, 'not_owed', ?, ?, ?, ?
+  )
+`;
+var PEEK_LAST_SEQ_NO = `
+  SELECT last_seq_no FROM _channel_seq WHERE channel_name = ?
+`;
+var COMMIT_SEQ_NO = `
+  INSERT INTO _channel_seq (channel_name, last_seq_no) VALUES (?, ?)
+    ON CONFLICT(channel_name) DO UPDATE SET last_seq_no = excluded.last_seq_no
+`;
+var FIND_SEEN_BY_CONTROL_ID = `
+  SELECT * FROM inbound_hl7_messages
+   WHERE channel_name = ?
+     AND msg_control_id = ?
+     AND state != 'nacked'
+   ORDER BY id DESC
+   LIMIT 1
+`;
+var CLAIM_NEXT = `
+  UPDATE inbound_hl7_messages
+     SET state = 'claimed',
+         processing_started_at = ?,
+         attempt_count = attempt_count + 1
+   WHERE id = (
+     SELECT id FROM inbound_hl7_messages
+      WHERE channel_name = ? AND state = 'queued'
+      ORDER BY id ASC
+      LIMIT 1
+   )
+   RETURNING *
+`;
+var MARK_SENT = `
+  UPDATE inbound_hl7_messages
+     SET state = 'inflight',
+         sent_at = ?
+   WHERE callback_id = ? AND state = 'claimed'
+`;
+var FIND_BY_CALLBACK = `
+  SELECT * FROM inbound_hl7_messages WHERE callback_id = ?
+`;
+var FIND_BY_ID = `
+  SELECT * FROM inbound_hl7_messages WHERE id = ?
+`;
+var RECORD_SERVER_RESPONSE = `
+  UPDATE inbound_hl7_messages
+     SET server_status_code = ?,
+         server_response_body = ?
+   WHERE id = ?
+`;
+var MARK_PROCESSED = `
+  UPDATE inbound_hl7_messages
+     SET state = 'processed',
+         ack_outcome = ?,
+         processed_at = ?
+   WHERE id = ?
+`;
+var MARK_BOT_FAILED = `
+  UPDATE inbound_hl7_messages
+     SET state = ?,
+         errored_at = ?,
+         last_error = ?,
+         error_code = ?,
+         ack_outcome = 'not_owed'
+   WHERE id = ?
+`;
+var SET_ACK_OUTCOME = `
+  UPDATE inbound_hl7_messages
+     SET ack_outcome = ?
+   WHERE id = ?
+`;
+var REQUEUE = `
+  UPDATE inbound_hl7_messages
+     SET state = 'queued',
+         processing_started_at = NULL,
+         attempt_count = MAX(0, attempt_count - 1)
+   WHERE id = ? AND state = 'claimed'
+`;
+var LIST_QUEUED_IDS_FOR_CHANNEL = `
+  SELECT id FROM inbound_hl7_messages
+   WHERE channel_name = ? AND state = 'queued'
+   ORDER BY id ASC
+`;
+var RECOVER_INFLIGHT = `
+  UPDATE inbound_hl7_messages
+     SET state = 'failed',
+         errored_at = ?,
+         last_error = COALESCE(last_error, 'interrupted: process restart while inflight'),
+         error_code = COALESCE(error_code, '${QueueErrorCode.Interrupted}')
+   WHERE state = 'inflight'
+`;
+var RECOVER_CLAIMED = `
+  UPDATE inbound_hl7_messages
+     SET state = 'queued',
+         processing_started_at = NULL,
+         attempt_count = MAX(0, attempt_count - 1)
+   WHERE state = 'claimed'
+`;
+var COUNT_BY_STATE = `
+  SELECT state, COUNT(*) AS n FROM inbound_hl7_messages GROUP BY state
+`;
+var CHANNEL_DEPTH = `
+  SELECT
+    SUM(state = 'queued')                                            AS queued,
+    SUM(state = 'claimed')                                           AS claimed,
+    SUM(state = 'inflight')                                          AS inflight,
+    MIN(CASE WHEN state = 'queued' THEN received_at ELSE NULL END)   AS oldest_queued_at
+  FROM inbound_hl7_messages
+  WHERE channel_name = ?
+`;
+var DB_SIZE_BYTES = `
+  SELECT page_count * page_size AS bytes FROM pragma_page_count, pragma_page_size
+`;
+var TRY_ACQUIRE_LEASE = `
+  INSERT INTO _lease (id, holder, acquired_at, expires_at)
+  VALUES (1, ?, ?, ?)
+  ON CONFLICT(id) DO UPDATE
+     SET holder = excluded.holder,
+         acquired_at = excluded.acquired_at,
+         expires_at = excluded.expires_at
+   WHERE _lease.holder = ? OR _lease.expires_at <= ?
+`;
+var HEARTBEAT_LEASE = `
+  UPDATE _lease SET expires_at = ? WHERE id = 1 AND holder = ?
+`;
+var RELEASE_LEASE = `
+  DELETE FROM _lease WHERE id = 1 AND holder = ?
+`;
+var GET_LEASE = `
+  SELECT holder, expires_at FROM _lease WHERE id = 1
+`;
+var CHECKPOINT_WAL = `PRAGMA wal_checkpoint(TRUNCATE)`;
+var RETENTION_PHASE1_DELETE = `
+  DELETE FROM inbound_hl7_messages
+   WHERE state = 'processed' AND ack_outcome != 'undelivered' AND processed_at < ?
+`;
+var RETENTION_PHASE2_DELETE = `
+  DELETE FROM inbound_hl7_messages
+   WHERE id IN (
+     SELECT id FROM inbound_hl7_messages
+      WHERE state = 'processed' AND ack_outcome != 'undelivered'
+      ORDER BY processed_at ASC
+      LIMIT ?
+   )
+`;
+var RETENTION_PHASE3_DELETE = `
+  DELETE FROM inbound_hl7_messages
+   WHERE id IN (
+     SELECT id FROM inbound_hl7_messages
+      WHERE (
+              state IN ('rejected', 'failed', 'nacked')
+              OR (state = 'processed' AND ack_outcome = 'undelivered')
+            )
+        AND COALESCE(errored_at, processed_at) < ?
+      ORDER BY COALESCE(errored_at, processed_at) ASC
+      LIMIT ?
+   )
+`;
+
+// src/queue/schema.ts
+var MIGRATIONS = [
+  {
+    version: 1,
+    sql: `
+      CREATE TABLE IF NOT EXISTS _schema (
+        version    INTEGER PRIMARY KEY,
+        applied_at INTEGER NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS inbound_hl7_messages (
+        id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+        channel_name          TEXT    NOT NULL,
+        remote                TEXT    NOT NULL,
+        msg_control_id        TEXT,
+        msg_type              TEXT,
+        -- original_message is the message exactly as received, used for the
+        -- intake duplicate-content comparison. finalized_message is what the
+        -- worker dispatches upstream; it differs from original only when the
+        -- channel rewrites the message (e.g. assignSeqNo sets MSH.13). When no
+        -- transformation applies the two are byte-identical.
+        original_message      BLOB    NOT NULL,
+        finalized_message     BLOB    NOT NULL,
+        encoding              TEXT,
+        enhanced_mode         TEXT,
+        -- state tracks the Bot leg: queued \u2192 claimed (worker owns it, request not
+        -- yet on the wire) \u2192 inflight (request written to the socket, sent_at
+        -- stamped, awaiting response) \u2192 processed/rejected/failed, plus the
+        -- intake-reject 'nacked'. The claimed/inflight split is what lets crash
+        -- recovery tell a provably-unsent row (safe to requeue) from an ambiguous
+        -- in-flight one (must fail for review). The source-leg ACK-delivery outcome
+        -- is tracked independently in ack_outcome
+        -- (pending/delivered/undelivered/not_owed) so the two legs never conflate.
+        state                 TEXT    NOT NULL,
+        attempt_count         INTEGER NOT NULL DEFAULT 0,
+        callback_id           TEXT    NOT NULL,
+        server_response_body  BLOB,
+        server_status_code    INTEGER,
+        ack_outcome           TEXT    NOT NULL DEFAULT 'pending',
+        last_error            TEXT,
+        error_code            TEXT,
+        seq_no                INTEGER,
+        received_at           INTEGER NOT NULL,
+        -- processing_started_at is stamped when the worker claims the row (enters
+        -- the claimed state); sent_at is stamped when the request is written to the
+        -- socket (enters inflight). A NULL sent_at on a claimed row is the durable
+        -- discriminator crash recovery uses to know the request never left.
+        processing_started_at INTEGER,
+        sent_at               INTEGER,
+        processed_at          INTEGER,
+        errored_at            INTEGER
+      ) STRICT;
+
+      CREATE INDEX IF NOT EXISTS idx_inbound_channel_state_id
+        ON inbound_hl7_messages (channel_name, state, id);
+
+      -- Also serves the retention phase-3 sweep: its (state IN ... OR ...)
+      -- predicate resolves to a MULTI-INDEX OR over this index's leading state
+      -- column, so the sweep filters by index rather than full-scanning. A
+      -- dedicated COALESCE(errored_at, processed_at) expression index was
+      -- evaluated to also satisfy phase 3's ORDER BY, but SQLite's partial-index
+      -- prover can't match that disjunctive predicate (so a partial index goes
+      -- unused), and a non-partial one would key every queued row as NULL and tax
+      -- the hot intake path -- not worth it for an hourly, size-gated sweep.
+      CREATE INDEX IF NOT EXISTS idx_inbound_state_processed_at
+        ON inbound_hl7_messages (state, processed_at);
+
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_inbound_dup_active
+        ON inbound_hl7_messages (channel_name, msg_control_id)
+        WHERE msg_control_id IS NOT NULL
+          AND state IN ('queued', 'claimed', 'inflight');
+
+      -- Intake dedup reads the most recent prior row for a (channel, control_id)
+      -- across ALL non-nacked states (uq_inbound_dup_active only covers the
+      -- active window). This runs once per inbound message that carries an
+      -- MSH.10, so without it the lookup scans every row for the channel. The
+      -- trailing id makes ORDER BY id DESC LIMIT 1 a reverse index seek; the
+      -- partial predicate matches the query so there's no residual recheck.
+      CREATE INDEX IF NOT EXISTS idx_inbound_dup_lookup
+        ON inbound_hl7_messages (channel_name, msg_control_id, id)
+        WHERE msg_control_id IS NOT NULL
+          AND state != 'nacked';
+
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_inbound_callback
+        ON inbound_hl7_messages (callback_id);
+
+      -- Single-row table holding the current queue lease, used for coordinating
+      -- the active queue worker across zero-downtime agent upgrades (two
+      -- processes share the DB for the upgrade overlap window; only the
+      -- leaseholder drains rows and runs recovery). The CHECK constraint keeps
+      -- it strictly single-row.
+      CREATE TABLE IF NOT EXISTS _lease (
+        id          INTEGER PRIMARY KEY CHECK (id = 1),
+        holder      TEXT    NOT NULL,
+        acquired_at INTEGER NOT NULL,
+        expires_at  INTEGER NOT NULL
+      ) STRICT;
+
+      -- Per-channel monotonic sequence counter for the assignSeqNo feature.
+      -- Persisting it here (rather than only in memory) keeps MSH.13 sequence
+      -- numbers monotonic across agent restarts. last_seq_no holds the most
+      -- recently assigned value; the next assignment is last_seq_no + 1.
+      CREATE TABLE IF NOT EXISTS _channel_seq (
+        channel_name TEXT    PRIMARY KEY,
+        last_seq_no  INTEGER NOT NULL
+      ) STRICT;
+    `
+  }
+];
+function runMigrations(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS _schema (
+      version    INTEGER PRIMARY KEY,
+      applied_at INTEGER NOT NULL
+    );
+  `);
+  const currentRow = db.prepare("SELECT MAX(version) AS v FROM _schema").get();
+  let current = currentRow?.v ?? 0;
+  const insertVersion = db.prepare("INSERT INTO _schema (version, applied_at) VALUES (?, ?)");
+  for (const migration of MIGRATIONS) {
+    if (migration.version <= current) {
+      continue;
+    }
+    db.exec("BEGIN");
+    try {
+      db.exec(migration.sql);
+      insertVersion.run(migration.version, Date.now());
+      db.exec("COMMIT");
+      current = migration.version;
+    } catch (err2) {
+      db.exec("ROLLBACK");
+      throw err2;
+    }
+  }
+  return current;
+}
+
+// src/queue/durable-queue.ts
+var DEFAULT_LEASE_TTL_MS = 3e4;
+var DEFAULT_LEASE_HEARTBEAT_MS = 1e4;
+var DEFAULT_LEASE_ACQUIRE_RETRY_MS = 2e3;
+var DEFAULT_CHECKPOINT_INTERVAL_MS = 1e4;
+var DurableQueue = class _DurableQueue {
+  constructor(db, options) {
+    __publicField(this, "db");
+    __publicField(this, "log");
+    __publicField(this, "path");
+    __publicField(this, "closed", false);
+    // The dispatch-lease holder ID of THIS process, set when startDispatchLease()
+    // begins the acquire/heartbeat loop (or bound directly via setLeaseHolder in
+    // tests). Dispatch-class mutations are gated on the live lease still belonging
+    // to this holder; when a peer takes over, the gate throws QueueLeaseError so the
+    // demoted worker stops driving the queue. Undefined when the dispatch lease was
+    // never started (single-process use and most unit tests), in which case the gate
+    // is inert because no lease row exists.
+    __publicField(this, "leaseHolderId");
+    // ── Dispatch-lease orchestration (formerly DispatchLeaseManager) ──
+    // Lightweight leader election for the DISPATCH path. The lease gates *dispatch
+    // only* — claiming rows and driving them to the server (the worker +
+    // recoverOnStartup). It deliberately does NOT gate intake (followers still
+    // persist inbound messages via enqueue), maintenance (WAL checkpoint, retention
+    // sweep), or diagnostics (stats): those are valid on any process with the queue
+    // file open. Exactly one process may dispatch at a time, which is the
+    // load-bearing primitive that makes zero-downtime upgrades safe: during the
+    // overlap window where the old and new agent processes both have the SQLite file
+    // open, only the leaseholder claims/sends rows; the non-leader keeps accepting
+    // and persisting inbound traffic but does not dispatch.
+    //
+    // There is deliberately NO lost-leadership callback: loss is enforced at the
+    // data layer instead — the dispatch ops throw QueueLeaseError once a peer holds
+    // the lease (see assertNotDemoted), so the worker self-detects and drains
+    // without pushing an event down a chain of callbacks.
+    __publicField(this, "leaseTtlMs");
+    __publicField(this, "leaseHeartbeatMs");
+    __publicField(this, "leaseAcquireRetryMs");
+    __publicField(this, "leaseLeader", false);
+    __publicField(this, "leaseLoopActive", false);
+    __publicField(this, "leaseAcquireTimer");
+    __publicField(this, "leaseHeartbeatTimer");
+    __publicField(this, "onBecameLeader");
+    // True when the WAL may contain frames not yet checkpointed into the main DB
+    // file. SQLite only attempts checkpoints piggybacked on commits, so once
+    // traffic stops nothing would ever drain the WAL — the queue's own checkpoint
+    // loop (startCheckpointLoop) polls this via checkpointWalIfDirty(). Starts true
+    // because open() itself writes (pragmas, migrations, lease).
+    __publicField(this, "walDirty", true);
+    // WAL-checkpoint loop. Runs while the queue is open, INDEPENDENT of the
+    // dispatch lease: a follower still accepts intake writes (enqueue runs on any
+    // process with the file open), so WAL draining can't be gated on leadership the
+    // way the lease timers are. Started in open(), cleared in close().
+    __publicField(this, "checkpointIntervalMs");
+    __publicField(this, "checkpointTimer");
+    // Prepared statements — created once at open(), reused for every call.
+    // Names mirror the public methods that use them.
+    __publicField(this, "enqueueStmt");
+    __publicField(this, "enqueueRejectedStmt");
+    __publicField(this, "peekLastSeqNoStmt");
+    __publicField(this, "commitSeqNoStmt");
+    __publicField(this, "findSeenByControlIdStmt");
+    __publicField(this, "claimNextStmt");
+    __publicField(this, "markSentStmt");
+    __publicField(this, "findByCallbackStmt");
+    __publicField(this, "findByIdStmt");
+    __publicField(this, "recordServerResponseStmt");
+    __publicField(this, "markProcessedStmt");
+    __publicField(this, "markBotFailedStmt");
+    __publicField(this, "setAckOutcomeStmt");
+    __publicField(this, "requeueStmt");
+    __publicField(this, "recoverInflightStmt");
+    __publicField(this, "recoverClaimedStmt");
+    __publicField(this, "listQueuedIdsForChannelStmt");
+    __publicField(this, "countByStateStmt");
+    __publicField(this, "channelDepthStmt");
+    __publicField(this, "tryAcquireLeaseStmt");
+    __publicField(this, "heartbeatLeaseStmt");
+    __publicField(this, "releaseLeaseStmt");
+    __publicField(this, "getLeaseStmt");
+    __publicField(this, "checkpointStmt");
+    __publicField(this, "dbSizeBytesStmt");
+    this.db = db;
+    this.log = options.log;
+    this.path = options.path;
+    this.leaseHolderId = options.leaseHolder;
+    this.leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+    this.leaseHeartbeatMs = options.leaseHeartbeatMs ?? DEFAULT_LEASE_HEARTBEAT_MS;
+    this.leaseAcquireRetryMs = options.leaseAcquireRetryMs ?? DEFAULT_LEASE_ACQUIRE_RETRY_MS;
+    this.checkpointIntervalMs = options.checkpointIntervalMs ?? DEFAULT_CHECKPOINT_INTERVAL_MS;
+    this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA synchronous  = NORMAL;
+      PRAGMA temp_store   = MEMORY;
+      PRAGMA cache_size   = -65536;
+      PRAGMA mmap_size    = 268435456;
+      PRAGMA wal_autocheckpoint = 1000;
+      PRAGMA busy_timeout = 5000;
+      PRAGMA foreign_keys = ON;
+    `);
+    runMigrations(this.db);
+    this.enqueueStmt = this.db.prepare(ENQUEUE);
+    this.enqueueRejectedStmt = this.db.prepare(ENQUEUE_REJECTED);
+    this.peekLastSeqNoStmt = this.db.prepare(PEEK_LAST_SEQ_NO);
+    this.commitSeqNoStmt = this.db.prepare(COMMIT_SEQ_NO);
+    this.findSeenByControlIdStmt = this.db.prepare(FIND_SEEN_BY_CONTROL_ID);
+    this.claimNextStmt = this.db.prepare(CLAIM_NEXT);
+    this.markSentStmt = this.db.prepare(MARK_SENT);
+    this.findByCallbackStmt = this.db.prepare(FIND_BY_CALLBACK);
+    this.findByIdStmt = this.db.prepare(FIND_BY_ID);
+    this.recordServerResponseStmt = this.db.prepare(RECORD_SERVER_RESPONSE);
+    this.markProcessedStmt = this.db.prepare(MARK_PROCESSED);
+    this.markBotFailedStmt = this.db.prepare(MARK_BOT_FAILED);
+    this.setAckOutcomeStmt = this.db.prepare(SET_ACK_OUTCOME);
+    this.requeueStmt = this.db.prepare(REQUEUE);
+    this.recoverInflightStmt = this.db.prepare(RECOVER_INFLIGHT);
+    this.recoverClaimedStmt = this.db.prepare(RECOVER_CLAIMED);
+    this.listQueuedIdsForChannelStmt = this.db.prepare(LIST_QUEUED_IDS_FOR_CHANNEL);
+    this.countByStateStmt = this.db.prepare(COUNT_BY_STATE);
+    this.channelDepthStmt = this.db.prepare(CHANNEL_DEPTH);
+    this.tryAcquireLeaseStmt = this.db.prepare(TRY_ACQUIRE_LEASE);
+    this.heartbeatLeaseStmt = this.db.prepare(HEARTBEAT_LEASE);
+    this.releaseLeaseStmt = this.db.prepare(RELEASE_LEASE);
+    this.getLeaseStmt = this.db.prepare(GET_LEASE);
+    this.checkpointStmt = this.db.prepare(CHECKPOINT_WAL);
+    this.dbSizeBytesStmt = this.db.prepare(DB_SIZE_BYTES);
+  }
+  /**
+   * Opens (or creates) the DB file at `options.path`, runs migrations, and
+   * returns a ready DurableQueue.
+   *
+   * Constructs synchronously — `node:sqlite` is itself synchronous so there's
+   * no benefit to making this `async`.
+   *
+   * @param options - Path + logger.
+   * @returns The opened DurableQueue.
+   */
+  static open(options) {
+    const { DatabaseSync } = require("node:sqlite");
+    const db = new DatabaseSync(options.path);
+    const queue = new _DurableQueue(db, options);
+    if ((0, import_node_fs3.existsSync)(options.path)) {
+      try {
+        (0, import_node_fs3.chmodSync)(options.path, 384);
+      } catch {
+      }
+    }
+    queue.startCheckpointLoop();
+    return queue;
+  }
+  /** Closes the underlying SQLite handle. Idempotent. */
+  close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.stopCheckpointLoop();
+    this.stopDispatchLease();
+    this.checkpointWal();
+    try {
+      this.db.close();
+    } catch (err2) {
+      this.log.warn(`Error while closing durable queue DB: ${Re(err2)}`);
+    }
+  }
+  /**
+   * Unconditionally runs a TRUNCATE checkpoint, folding the WAL into the main
+   * DB file and truncating the WAL to zero bytes. Best-effort: failures are
+   * logged, and an incomplete checkpoint (a peer connection pinning part of the
+   * WAL) leaves the dirty flag set so the next attempt retries.
+   * @returns True when the checkpoint fully completed.
+   */
+  checkpointWal() {
+    try {
+      const row = this.checkpointStmt.get();
+      if (row?.busy) {
+        return false;
+      }
+      this.walDirty = false;
+      return true;
+    } catch (err2) {
+      this.log.warn(`wal_checkpoint failed: ${Re(err2)}`);
+      return false;
+    }
+  }
+  /**
+   * Runs {@link DurableQueue.checkpointWal} only when writes have landed since
+   * the last completed checkpoint. Driven by the queue's own checkpoint loop
+   * (see {@link DurableQueue.startCheckpointLoop}) every `checkpointIntervalMs`,
+   * so the WAL drains shortly after traffic stops instead of waiting for the next
+   * retention sweep or for close(). A no-op on an idle queue.
+   * @returns True when a checkpoint ran and fully completed.
+   */
+  checkpointWalIfDirty() {
+    if (this.closed || !this.walDirty) {
+      return false;
+    }
+    return this.checkpointWal();
+  }
+  /**
+   * Starts the periodic WAL-checkpoint loop. Idempotent. Called once by
+   * {@link DurableQueue.open}; runs regardless of dispatch leadership (see the
+   * `checkpointTimer` field) and is torn down by {@link DurableQueue.close}.
+   */
+  startCheckpointLoop() {
+    if (this.checkpointTimer) {
+      return;
+    }
+    this.checkpointTimer = setInterval(() => this.checkpointWalIfDirty(), this.checkpointIntervalMs);
+    if (typeof this.checkpointTimer.unref === "function") {
+      this.checkpointTimer.unref();
+    }
+  }
+  /** Stops the WAL-checkpoint loop. Idempotent and a no-op when never started. */
+  stopCheckpointLoop() {
+    if (this.checkpointTimer) {
+      clearInterval(this.checkpointTimer);
+      this.checkpointTimer = void 0;
+    }
+  }
+  /** @returns Filesystem path of the underlying SQLite file. */
+  getPath() {
+    return this.path;
+  }
+  /** @returns Direct access to the underlying handle. Used by retention sweeper for PRAGMA queries. */
+  getDb() {
+    return this.db;
+  }
+  /**
+   * Runs `fn` inside a single SQLite transaction, committing if it returns and
+   * rolling back if it throws. Used to make a row state transition atomic with an
+   * external side effect — e.g. flipping a row `claimed` → `inflight` only if the
+   * socket write that puts it on the wire also succeeds (see `App.sendToWebSocket`):
+   * if the write throws, the marker rolls back and the row stays `claimed`
+   * (provably unsent, safe to requeue) rather than a phantom `inflight`.
+   *
+   * `node:sqlite` is synchronous, so `fn` must be synchronous too — do any `await`
+   * (e.g. token refresh) before calling, not inside.
+   * @param fn - The work to run transactionally.
+   * @returns Whatever `fn` returns.
+   */
+  runInTransaction(fn2) {
+    this.db.exec("BEGIN");
+    try {
+      const result = fn2();
+      this.db.exec("COMMIT");
+      return result;
+    } catch (err2) {
+      this.db.exec("ROLLBACK");
+      throw err2;
+    }
+  }
+  /**
+   * Inserts a new `queued` row.
+   *
+   * If any prior non-`nacked` row already owns this `(channel_name,
+   * msg_control_id)` — in `queued`, `claimed`, `inflight`, `processed`,
+   * `rejected`, or `failed` — we don't insert; we surface a `duplicate` result
+   * carrying that row so the caller can compare bodies and decide between
+   * replaying the prior ACK and rejecting the collision (§8). This SELECT is the
+   * single dedup authority on the intake path: the partial unique index only
+   * covers the live `queued`/`claimed`/`inflight` window, so it can't recognize a
+   * retransmit of an already-`processed`/`rejected`/`failed` row —
+   * it remains only as a last-resort guard against an active-window race (not
+   * expected in the single-process agent).
+   * @param input - Fields to persist on the new row.
+   * @param options - Optional behavior.
+   * @param options.assignSeqNo - When provided, enqueue assigns the channel's next
+   *   sequence number — but only after the duplicate check passes, so a retransmit
+   *   never consumes one. It peeks the persisted counter (a non-consuming read),
+   *   calls this callback with the candidate so the caller can stamp it into MSH.13
+   *   and return the finalized bytes to persist, then advances the counter in the
+   *   SAME transaction as the insert (so a crash can't store the row while leaving
+   *   the counter behind, which would reuse the number on restart). On a duplicate
+   *   the callback is never invoked.
+   * @returns Either the inserted row, or the prior row that owns the MSH.10.
+   */
+  enqueue(input, options) {
+    if (input.msgControlId) {
+      const existing = this.findSeenByControlId(input.channelName, input.msgControlId);
+      if (existing) {
+        return { kind: "duplicate", existing };
+      }
+    }
+    let finalizedMessage = input.finalizedMessage;
+    let seqNo = input.seqNo;
+    let seqNoToCommit;
+    if (options?.assignSeqNo) {
+      const candidate = this.peekNextSeqNo(input.channelName);
+      finalizedMessage = options.assignSeqNo(candidate);
+      seqNo = candidate;
+      seqNoToCommit = candidate;
+    }
+    try {
+      const runInsert = () => {
+        const info = this.enqueueStmt.run(
+          input.channelName,
+          input.remote,
+          input.msgControlId,
+          input.msgType,
+          toBlob(input.originalMessage),
+          toBlob(finalizedMessage),
+          input.encoding,
+          input.enhancedMode,
+          input.callbackId,
+          seqNo,
+          input.receivedAt
+        );
+        return Number(info.lastInsertRowid);
+      };
+      let id;
+      if (seqNoToCommit !== void 0) {
+        this.db.exec("BEGIN");
+        try {
+          id = runInsert();
+          this.commitSeqNo(input.channelName, seqNoToCommit);
+          this.db.exec("COMMIT");
+        } catch (txErr) {
+          this.db.exec("ROLLBACK");
+          throw txErr;
+        }
+      } else {
+        id = runInsert();
+      }
+      this.walDirty = true;
+      const row = this.getById(id);
+      if (!row) {
+        throw new Error(`enqueue: inserted row id=${id} could not be re-read`);
+      }
+      return { kind: "inserted", row };
+    } catch (err2) {
+      if (isUniqueConstraintError(err2) && input.msgControlId) {
+        const existing = this.findSeenByControlId(input.channelName, input.msgControlId);
+        if (existing) {
+          return { kind: "duplicate", existing };
+        }
+      }
+      throw err2;
+    }
+  }
+  /**
+   * Inserts an audit row in the `nacked` terminal state — used when intake
+   * rejected the message (duplicate, malformed) but we still want a forensics
+   * record. Failure to write this is non-fatal; the caller is expected to log.
+   * @param input - Fields to persist plus the `lastError`/`errorCode` describing why we rejected.
+   * @returns The newly inserted audit row, or null if even the audit insert failed.
+   */
+  enqueueRejected(input) {
+    try {
+      const info = this.enqueueRejectedStmt.run(
+        input.channelName,
+        input.remote,
+        input.msgControlId,
+        input.msgType,
+        toBlob(input.originalMessage),
+        toBlob(input.finalizedMessage),
+        input.encoding,
+        input.enhancedMode,
+        input.callbackId,
+        input.lastError,
+        input.errorCode,
+        input.seqNo,
+        input.receivedAt
+      );
+      this.walDirty = true;
+      return this.getById(Number(info.lastInsertRowid));
+    } catch (err2) {
+      this.log.warn(`enqueueRejected failed: ${Re(err2)}`);
+      return null;
+    }
+  }
+  /**
+   * Atomically claims the next `queued` row for `channelName`, flipping it to
+   * `claimed` and bumping `attempt_count`. The row stays `claimed` until
+   * {@link markSent} flips it to `inflight` once the request hits the socket.
+   * @param channelName - The channel to claim from.
+   * @param now - Override the timestamp written to `processing_started_at` (for tests).
+   * @returns The claimed row, or `null` if the channel queue is empty.
+   */
+  claimNext(channelName, now = Date.now()) {
+    this.assertNotDemoted();
+    const raw = this.claimNextStmt.get(now, channelName);
+    if (raw) {
+      this.walDirty = true;
+    }
+    return raw ? rowFromSql(raw) : null;
+  }
+  /**
+   * Phase A → B transition: records that the transmit request for `callbackId`
+   * was written to the WebSocket, flipping the row from `claimed` to `inflight`
+   * and stamping `sent_at`. Called from the App's send path the instant the
+   * request leaves the process — the durable marker that distinguishes a
+   * provably-unsent row (safe to requeue on crash) from an ambiguous in-flight
+   * one (failed for review). Guarded on `state = 'claimed'`, so it's a no-op for
+   * legacy (non-durable) sends and for any row already past `claimed`.
+   * @param callbackId - The callback ID of the transmit request just sent.
+   * @param now - Override for `sent_at` (for tests).
+   * @returns True if a `claimed` row was flipped to `inflight`.
+   */
+  markSent(callbackId, now = Date.now()) {
+    const info = this.markSentStmt.run(now, callbackId);
+    if (Number(info.changes) > 0) {
+      this.walDirty = true;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Looks up a row by its server-callback ID. Returns `null` if not found.
+   * @param callbackId - The callback ID echoed back by the Medplum server.
+   * @returns The matching row, or null.
+   */
+  findByCallback(callbackId) {
+    const raw = this.findByCallbackStmt.get(callbackId);
+    return raw ? rowFromSql(raw) : null;
+  }
+  /**
+   * Looks up a row by its primary key.
+   * @param id - The row's primary key.
+   * @returns The matching row, or null.
+   */
+  getById(id) {
+    const raw = this.findByIdStmt.get(id);
+    return raw ? rowFromSql(raw) : null;
+  }
+  /**
+   * Records the server's `agent:transmit:response` body + status against the row.
+   * @param id - Row primary key.
+   * @param statusCode - HTTP-style status code returned by the server.
+   * @param body - Response payload, or null when the server omitted one.
+   */
+  recordServerResponse(id, statusCode, body) {
+    this.assertNotDemoted();
+    this.recordServerResponseStmt.run(statusCode, body === null ? null : toBlob(body), id);
+    this.walDirty = true;
+  }
+  /**
+   * Terminal Bot-leg transition: the server accepted the message (2xx). The
+   * source leg is recorded independently via `ackOutcome` — `delivered` when the
+   * app-level ACK reached the source, `undelivered` when it couldn't (e.g. the
+   * source connection had closed). An `undelivered` row is fully processed
+   * upstream and must never be re-dispatched; it recovers when the source
+   * retransmits and the stored ACK is replayed (see {@link setAckOutcome}).
+   * @param id - Row primary key.
+   * @param ackOutcome - Source-leg result: `delivered` or `undelivered`.
+   * @param now - Override for `processed_at` (for tests).
+   */
+  markProcessed(id, ackOutcome, now = Date.now()) {
+    this.assertNotDemoted();
+    this.markProcessedStmt.run(ackOutcome, now, id);
+    this.walDirty = true;
+  }
+  /**
+   * Terminal Bot-leg transition: the server **rejected** the message itself
+   * (permanent 4xx). Retrying can never help — the content must be triaged.
+   * @param id - Row primary key.
+   * @param error - Human-readable error string, written to `last_error`.
+   * @param errorCode - Machine-readable classification, written to `error_code`.
+   * @param now - Override for `errored_at` (for tests).
+   */
+  markRejected(id, error, errorCode, now = Date.now()) {
+    this.assertNotDemoted();
+    this.markBotFailedStmt.run(MessageState.REJECTED, now, error, errorCode, id);
+    this.walDirty = true;
+  }
+  /**
+   * Terminal-for-now Bot-leg transition: a **transient/ambiguous** failure
+   * (5xx, 429, response timeout, dispatch error, interrupted). The retry/
+   * operator-review candidate — distinct from a `rejected` message so a future
+   * retry policy can re-dispatch `failed` rows without ever touching `rejected`
+   * ones (or `processed` + `undelivered` ones, whose Bot leg already succeeded).
+   * @param id - Row primary key.
+   * @param error - Human-readable error string, written to `last_error`.
+   * @param errorCode - Machine-readable classification, written to `error_code`.
+   * @param now - Override for `errored_at` (for tests).
+   */
+  markFailed(id, error, errorCode, now = Date.now()) {
+    this.assertNotDemoted();
+    this.markBotFailedStmt.run(MessageState.FAILED, now, error, errorCode, id);
+    this.walDirty = true;
+  }
+  /**
+   * Updates only the source-leg {@link AckOutcome}, leaving the Bot-leg `state`
+   * untouched. Used when a duplicate retransmit replays a previously
+   * `undelivered` ACK and it lands — flipping the row to `delivered` so it no
+   * longer reads as awaiting source delivery.
+   * @param id - Row primary key.
+   * @param ackOutcome - The new source-leg outcome.
+   */
+  setAckOutcome(id, ackOutcome) {
+    this.setAckOutcomeStmt.run(ackOutcome, id);
+    this.walDirty = true;
+  }
+  /**
+   * Returns a `claimed` row to `queued` — used when the WS connection drops
+   * before the transmit request was ever written to the socket, so retrying on
+   * reconnect carries no duplicate-delivery risk. (A row that already reached the
+   * socket is `inflight`, not `claimed`, and this is a no-op for it — its outcome
+   * is ambiguous and owned by the response timeout.) Because the row keeps its
+   * original id and claims are ordered by id, it goes back to the front of its
+   * channel's FIFO.
+   * @param id - Row primary key.
+   * @returns True if the row was requeued; false if it was not in `claimed`.
+   */
+  requeue(id) {
+    this.assertNotDemoted();
+    const info = this.requeueStmt.run(id);
+    if (Number(info.changes) > 0) {
+      this.walDirty = true;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Recovers rows left mid-flight by a previous process, splitting on whether the
+   * request reached the wire. Runs once at startup (§10):
+   * - `inflight` rows are ambiguous (the server may have processed them) → `failed`
+   *   with error code `interrupted`, surfaced for operator review, never silently retried.
+   * - `claimed` rows provably never left the process (`sent_at` is NULL) → returned
+   *   to `queued` for a clean re-dispatch with no duplicate-delivery risk.
+   * @param now - Override for `errored_at` (for tests).
+   * @returns Counts of `claimed` rows requeued and `inflight` rows failed.
+   */
+  recoverOnStartup(now = Date.now()) {
+    const failedInfo = this.recoverInflightStmt.run(now);
+    const requeuedInfo = this.recoverClaimedStmt.run();
+    const failed = Number(failedInfo.changes);
+    const requeued = Number(requeuedInfo.changes);
+    if (failed > 0 || requeued > 0) {
+      this.walDirty = true;
+    }
+    return { requeued, failed };
+  }
+  /**
+   * Lists all `queued` row IDs for a channel, in FIFO order. Used by the
+   * worker on startup to repopulate its in-memory wake signal.
+   * @param channelName - The channel to query.
+   * @returns Row IDs in FIFO order.
+   */
+  listQueuedIdsForChannel(channelName) {
+    const rows = this.listQueuedIdsForChannelStmt.all(channelName);
+    return rows.map((r6) => r6.id);
+  }
+  /** @returns Counts of rows by state. Missing states are reported as 0. */
+  countByState() {
+    const counts = {
+      queued: 0,
+      claimed: 0,
+      inflight: 0,
+      processed: 0,
+      rejected: 0,
+      failed: 0,
+      nacked: 0
+    };
+    const rows = this.countByStateStmt.all();
+    for (const r6 of rows) {
+      counts[r6.state] = r6.n;
+    }
+    return counts;
+  }
+  /**
+   * @param channelName - The channel to query.
+   * @param now - Override for the "now" timestamp used in `oldestQueuedAgeMs`.
+   * @returns Depth snapshot for `channelName` (queued/claimed/inflight counts + oldest queued age).
+   */
+  getChannelDepth(channelName, now = Date.now()) {
+    const row = this.channelDepthStmt.get(channelName);
+    return {
+      queued: row?.queued ?? 0,
+      claimed: row?.claimed ?? 0,
+      inflight: row?.inflight ?? 0,
+      oldestQueuedAgeMs: row?.oldest_queued_at ? now - row.oldest_queued_at : null
+    };
+  }
+  /**
+   * Attempts to acquire (or re-acquire) the queue lease as `holder`.
+   *
+   * Succeeds when there is no current lease, the current lease is already held
+   * by us (refresh case), or the prior holder's lease has expired. Fails when a
+   * different holder still has a valid lease — caller should wait and retry.
+   *
+   * The lease is the cross-process coordination primitive that makes zero-downtime
+   * upgrades safe: only the holder runs workers and `recoverOnStartup`, so two
+   * processes sharing the DB during the upgrade overlap don't fight over rows.
+   * @param holder - Stable identifier for this process (a per-process UUID).
+   * @param ttlMs - How long the new lease should remain valid before another
+   *                process can take over (also drives the heartbeat cadence).
+   * @param now - Override the "now" timestamp (for tests).
+   * @returns True if the lease is now held by `holder`; false if a foreign holder still owns it.
+   */
+  tryAcquireLease(holder, ttlMs, now = Date.now()) {
+    const expiresAt = now + ttlMs;
+    const info = this.tryAcquireLeaseStmt.run(holder, now, expiresAt, holder, now);
+    if (Number(info.changes) > 0) {
+      this.walDirty = true;
+    }
+    return Number(info.changes) > 0;
+  }
+  /**
+   * Extends the existing lease held by `holder`. Fails (returns false) when the
+   * lease is no longer ours — most commonly because a peer took over after our
+   * TTL elapsed. A leader that sees `false` here must stop driving the queue.
+   * @param holder - The same identifier passed to {@link DurableQueue.tryAcquireLease}.
+   * @param ttlMs - New TTL for the lease (added to `now`).
+   * @param now - Override the "now" timestamp (for tests).
+   * @returns True if the heartbeat extended our lease; false if we lost it.
+   */
+  heartbeatLease(holder, ttlMs, now = Date.now()) {
+    const info = this.heartbeatLeaseStmt.run(now + ttlMs, holder);
+    if (Number(info.changes) > 0) {
+      this.walDirty = true;
+    }
+    return Number(info.changes) > 0;
+  }
+  /**
+   * Releases the lease if (and only if) `holder` still owns it. Idempotent. The
+   * holder check means a process that already lost its lease won't accidentally
+   * delete a newer leader's row.
+   * @param holder - The identifier of the lease to release.
+   */
+  releaseLease(holder) {
+    const info = this.releaseLeaseStmt.run(holder);
+    if (Number(info.changes) > 0) {
+      this.walDirty = true;
+    }
+  }
+  /**
+   * @returns The current lease, or null if no row exists. Used for diagnostics
+   *          and stats; the acquire/heartbeat methods do the actual coordination.
+   */
+  getCurrentLease() {
+    const row = this.getLeaseStmt.get();
+    return row ? { holder: row.holder, expiresAt: row.expires_at } : null;
+  }
+  /**
+   * Binds this queue to the lease holder ID of the local process, so the
+   * dispatch gate ({@link assertNotDemoted}) can tell "us" from a peer.
+   * {@link startDispatchLease} sets this automatically; call it directly only in
+   * tests that drive {@link tryAcquireLease}/{@link heartbeatLease} by hand.
+   * @param holderId - This process's lease holder ID.
+   */
+  setLeaseHolder(holderId) {
+    this.leaseHolderId = holderId;
+  }
+  /**
+   * Begins the dispatch-lease acquire-and-heartbeat loop for this process.
+   *
+   * Tries to acquire the lease immediately. On success it fires `onBecameLeader`
+   * and begins heartbeating every `leaseHeartbeatMs`; on failure it retries every
+   * `leaseAcquireRetryMs` until the lease frees up. `onBecameLeader` fires every
+   * time this process transitions from follower to leader (typically once, but
+   * again if it loses the lease mid-run and reclaims it). There is no
+   * lost-leadership callback by design — loss surfaces as a {@link QueueLeaseError}
+   * from the dispatch ops, which the worker catches to drain itself.
+   *
+   * Idempotent: calling it again while the loop is already active is a no-op,
+   * regardless of whether this process is currently a retrying follower or the
+   * leader. A repeat call does not re-acquire, re-heartbeat, re-fire
+   * `onBecameLeader`, or replace the callback — so the App can call it on every
+   * heartbeat tick (and when already the leader) without restarting the loop.
+   * @param onBecameLeader - Callback invoked when this process takes the lease.
+   */
+  startDispatchLease(onBecameLeader) {
+    if (this.leaseLoopActive) {
+      return;
+    }
+    this.onBecameLeader = onBecameLeader;
+    this.leaseLoopActive = true;
+    if (!this.leaseHolderId) {
+      this.leaseHolderId = (0, import_node_crypto4.randomUUID)();
+    }
+    this.tryAcquireDispatchLease();
+  }
+  /**
+   * Stops the dispatch-lease loop and releases the lease if we hold it.
+   * Idempotent and a no-op when the loop was never started.
+   * @returns True if we were the leader when stopping (and released the lease).
+   */
+  stopDispatchLease() {
+    this.leaseLoopActive = false;
+    this.onBecameLeader = void 0;
+    this.clearLeaseAcquireTimer();
+    this.clearLeaseHeartbeatTimer();
+    const wasLeader = this.leaseLeader;
+    if (this.leaseLeader && this.leaseHolderId) {
+      try {
+        this.releaseLease(this.leaseHolderId);
+      } catch (err2) {
+        this.log.warn(`Failed to release queue lease: ${Re(err2)}`);
+      }
+      this.leaseLeader = false;
+    }
+    return wasLeader;
+  }
+  /** @returns True if this process currently holds the dispatch lease. */
+  isLeader() {
+    return this.leaseLeader;
+  }
+  /** @returns The dispatch-lease holder ID for this process (for diagnostics), or undefined if never started. */
+  getLeaseHolderId() {
+    return this.leaseHolderId;
+  }
+  tryAcquireDispatchLease() {
+    if (!this.leaseLoopActive || this.closed || !this.leaseHolderId) {
+      return;
+    }
+    let acquired = false;
+    try {
+      acquired = this.tryAcquireLease(this.leaseHolderId, this.leaseTtlMs);
+    } catch (err2) {
+      this.log.warn(`Queue lease acquire threw: ${Re(err2)}`);
+    }
+    if (acquired) {
+      this.leaseLeader = true;
+      this.clearLeaseAcquireTimer();
+      this.log.info(`Acquired queue lease (holder=${this.leaseHolderId}).`);
+      this.scheduleLeaseHeartbeat();
+      try {
+        this.onBecameLeader?.();
+      } catch (err2) {
+        this.log.error(`onBecameLeader callback threw: ${Re(err2)}`);
+      }
+      return;
+    }
+    this.scheduleLeaseAcquireRetry();
+  }
+  scheduleLeaseAcquireRetry() {
+    if (!this.leaseLoopActive || this.leaseAcquireTimer) {
+      return;
+    }
+    this.leaseAcquireTimer = setTimeout(() => {
+      this.leaseAcquireTimer = void 0;
+      this.tryAcquireDispatchLease();
+    }, this.leaseAcquireRetryMs);
+    if (typeof this.leaseAcquireTimer.unref === "function") {
+      this.leaseAcquireTimer.unref();
+    }
+  }
+  scheduleLeaseHeartbeat() {
+    if (!this.leaseLoopActive || this.leaseHeartbeatTimer) {
+      return;
+    }
+    this.leaseHeartbeatTimer = setInterval(() => this.leaseHeartbeat(), this.leaseHeartbeatMs);
+    if (typeof this.leaseHeartbeatTimer.unref === "function") {
+      this.leaseHeartbeatTimer.unref();
+    }
+  }
+  leaseHeartbeat() {
+    if (!this.leaseLoopActive || !this.leaseLeader || !this.leaseHolderId) {
+      return;
+    }
+    let extended = false;
+    try {
+      extended = this.heartbeatLease(this.leaseHolderId, this.leaseTtlMs);
+    } catch (err2) {
+      this.log.warn(`Queue lease heartbeat threw: ${Re(err2)}`);
+      return;
+    }
+    if (!extended) {
+      this.log.error(`Lost queue lease (holder=${this.leaseHolderId}); peer took over.`);
+      this.leaseLeader = false;
+      this.clearLeaseHeartbeatTimer();
+      this.scheduleLeaseAcquireRetry();
+    }
+  }
+  clearLeaseAcquireTimer() {
+    if (this.leaseAcquireTimer) {
+      clearTimeout(this.leaseAcquireTimer);
+      this.leaseAcquireTimer = void 0;
+    }
+  }
+  clearLeaseHeartbeatTimer() {
+    if (this.leaseHeartbeatTimer) {
+      clearInterval(this.leaseHeartbeatTimer);
+      this.leaseHeartbeatTimer = void 0;
+    }
+  }
+  /**
+   * @returns True when a lease row exists and a DIFFERENT holder owns it — i.e. a
+   * peer has taken over and this process has been demoted. False when no lease
+   * exists (no coordination in play) or the lease is ours. Note this intentionally
+   * does NOT consider expiry: a merely-expired-but-still-ours lease will be
+   * re-extended by our next heartbeat, so only a foreign holder means "demoted",
+   * which keeps this exactly aligned with {@link DurableQueue.isLeader}.
+   */
+  isLeaseHeldByPeer() {
+    const lease = this.getCurrentLease();
+    return lease !== null && lease.holder !== this.leaseHolderId;
+  }
+  /**
+   * Throws {@link QueueLeaseError} when a peer holds the lease. Called at the top
+   * of every dispatch-class mutation so a demoted process can't claim, dispatch,
+   * or settle rows the new leader now owns — the authoritative, data-layer half of
+   * leadership enforcement (the {@link DurableQueue.isLeader} flag is the
+   * cheap optimistic half). Intake, maintenance, diagnostics, and the physical
+   * `markSent` marker are deliberately NOT gated.
+   */
+  assertNotDemoted() {
+    if (this.isLeaseHeldByPeer()) {
+      throw new QueueLeaseError(this.leaseHolderId, this.getCurrentLease()?.holder);
+    }
+  }
+  /**
+   * @returns Size of the underlying database file in bytes, computed from
+   * `page_count * page_size`. Used by the retention sweeper.
+   */
+  getDbSizeBytes() {
+    const row = this.dbSizeBytesStmt.get();
+    return row?.bytes ?? 0;
+  }
+  /**
+   * @param channelName - The channel to search.
+   * @param msgControlId - MSH.10 to look up.
+   * @returns The most recent non-`nacked` row owning this `(channel, control_id)`, or null.
+   */
+  findSeenByControlId(channelName, msgControlId) {
+    const raw = this.findSeenByControlIdStmt.get(channelName, msgControlId);
+    return raw ? rowFromSql(raw) : null;
+  }
+  /**
+   * Returns the sequence number that {@link commitSeqNo} would next persist for
+   * a channel, WITHOUT advancing the counter. The first value for a channel is
+   * 0; thereafter it is the last committed value + 1. Read-only: callers stamp
+   * this candidate into MSH.13 and only {@link commitSeqNo} it once the row is
+   * durably enqueued, so a failed insert never burns a sequence number.
+   * @param channelName - The channel whose counter to peek.
+   * @returns The next sequence number to assign.
+   */
+  peekNextSeqNo(channelName) {
+    const row = this.peekLastSeqNoStmt.get(channelName);
+    return row === void 0 ? 0 : row.last_seq_no + 1;
+  }
+  /**
+   * Persists `seqNo` as the channel's last assigned sequence number. Production
+   * intake commits this inside the insert transaction via
+   * {@link enqueue}'s `commitSeqNo` option, so the row and the counter advance
+   * atomically; call it directly only when not pairing it with an insert. The
+   * counter survives restarts, keeping MSH.13 sequence numbers monotonic.
+   * @param channelName - The channel whose counter to advance.
+   * @param seqNo - The sequence number that was assigned and successfully enqueued.
+   */
+  commitSeqNo(channelName, seqNo) {
+    this.commitSeqNoStmt.run(channelName, seqNo);
+    this.walDirty = true;
+  }
+};
+function rowFromSql(raw) {
+  return {
+    id: raw.id,
+    channelName: raw.channel_name,
+    remote: raw.remote,
+    msgControlId: raw.msg_control_id ?? null,
+    msgType: raw.msg_type ?? null,
+    originalMessage: toBuffer(raw.original_message),
+    finalizedMessage: toBuffer(raw.finalized_message),
+    encoding: raw.encoding ?? null,
+    enhancedMode: raw.enhanced_mode ?? null,
+    state: raw.state,
+    attemptCount: raw.attempt_count,
+    callbackId: raw.callback_id,
+    serverResponseBody: raw.server_response_body === null || raw.server_response_body === void 0 ? null : toBuffer(raw.server_response_body),
+    serverStatusCode: raw.server_status_code ?? null,
+    ackOutcome: raw.ack_outcome ?? AckOutcome.PENDING,
+    lastError: raw.last_error ?? null,
+    errorCode: raw.error_code ?? null,
+    seqNo: raw.seq_no ?? null,
+    receivedAt: raw.received_at,
+    processingStartedAt: raw.processing_started_at ?? null,
+    sentAt: raw.sent_at ?? null,
+    processedAt: raw.processed_at ?? null,
+    erroredAt: raw.errored_at ?? null
+  };
+}
+function toBlob(value) {
+  return typeof value === "string" ? Buffer.from(value) : value;
+}
+function toBuffer(value) {
+  if (Buffer.isBuffer(value)) {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value);
+  }
+  if (typeof value === "string") {
+    return Buffer.from(value);
+  }
+  return Buffer.alloc(0);
+}
+function isUniqueConstraintError(err2) {
+  if (err2 === null || typeof err2 !== "object") {
+    return false;
+  }
+  const asAny = err2;
+  if (typeof asAny.code === "string" && asAny.code.includes("CONSTRAINT_UNIQUE")) {
+    return true;
+  }
+  if (asAny.errcode === 2067) {
+    return true;
+  }
+  if (typeof asAny.message === "string" && /UNIQUE constraint failed/i.test(asAny.message)) {
+    return true;
+  }
+  return false;
+}
+
+// src/queue/retention.ts
+var DEFAULT_RETENTION_DAYS = 7;
+var DEFAULT_MAX_SIZE_MB = 512;
+var DEFAULT_ERRORED_RETENTION_DAYS = 90;
+var DEFAULT_SWEEP_INTERVAL_SECS = 3600;
+var RetentionSweeper = class {
+  constructor(options) {
+    __publicField(this, "queue");
+    __publicField(this, "log");
+    __publicField(this, "retentionMs");
+    __publicField(this, "maxSizeBytes");
+    __publicField(this, "erroredRetentionMs");
+    __publicField(this, "intervalMs");
+    __publicField(this, "timer");
+    __publicField(this, "running", false);
+    __publicField(this, "lastSweepAt", null);
+    __publicField(this, "lastResult", null);
+    // Prepared once at construction and reused on every sweep — re-preparing per
+    // sweep would leak GC-finalised statement objects proportional to sweep count.
+    __publicField(this, "phase1Stmt");
+    __publicField(this, "phase2Stmt");
+    __publicField(this, "phase3Stmt");
+    this.queue = options.queue;
+    this.log = options.log;
+    this.retentionMs = (options.retentionDays ?? DEFAULT_RETENTION_DAYS) * 24 * 60 * 60 * 1e3;
+    this.maxSizeBytes = (options.maxSizeMb ?? DEFAULT_MAX_SIZE_MB) * 1024 * 1024;
+    this.erroredRetentionMs = (options.erroredRetentionDays ?? DEFAULT_ERRORED_RETENTION_DAYS) * 24 * 60 * 60 * 1e3;
+    this.intervalMs = (options.sweepIntervalSecs ?? DEFAULT_SWEEP_INTERVAL_SECS) * 1e3;
+    const db = this.queue.getDb();
+    this.phase1Stmt = db.prepare(RETENTION_PHASE1_DELETE);
+    this.phase2Stmt = db.prepare(RETENTION_PHASE2_DELETE);
+    this.phase3Stmt = db.prepare(RETENTION_PHASE3_DELETE);
+  }
+  /** Starts the periodic sweep timer and runs one sweep right away. No-op if already started. */
+  start() {
+    if (this.timer) {
+      return;
+    }
+    this.timer = setInterval(() => this.runSweep(), this.intervalMs);
+    if (typeof this.timer.unref === "function") {
+      this.timer.unref();
+    }
+    this.runSweep();
+  }
+  /** Wrapper around {@link RetentionSweeper.sweep} that logs failures instead of throwing. */
+  runSweep() {
+    try {
+      this.sweep();
+    } catch (err2) {
+      this.log.error(`Retention sweep crashed: ${Re(err2)}`);
+    }
+  }
+  /** Stops the periodic sweep timer. */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = void 0;
+    }
+  }
+  /**
+   * Run a single sweep cycle immediately. Safe to call from `start`'s timer or tests.
+   *
+   * Synchronous: every SQLite call here is synchronous, so there is no `await` to
+   * make. Keeping the signature non-`async` means the `running` guard can't be
+   * defeated by a future edit that adds an `await` mid-sweep and opens a
+   * re-entrancy window.
+   * @param now - Override the "now" timestamp used for retention comparisons.
+   * @returns The deletion counts and DB size after this sweep cycle.
+   */
+  sweep(now = Date.now()) {
+    if (this.running) {
+      return this.lastResult ?? { deletedProcessed: 0, deletedErrored: 0, dbSizeBytesAfter: this.queue.getDbSizeBytes() };
+    }
+    this.running = true;
+    const startedAt = Date.now();
+    try {
+      const cutoffProcessed = now - this.retentionMs;
+      const cutoffErrored = now - this.erroredRetentionMs;
+      const phase1 = this.phase1Stmt.run(cutoffProcessed);
+      let deletedProcessed = Number(phase1.changes);
+      let deletedErrored = 0;
+      const sizeBudget = this.maxSizeBytes;
+      const batchSize = 1e3;
+      while (this.queue.getDbSizeBytes() > sizeBudget) {
+        const info = this.phase2Stmt.run(batchSize);
+        if (info.changes === 0) {
+          break;
+        }
+        deletedProcessed += Number(info.changes);
+      }
+      if (this.queue.getDbSizeBytes() > sizeBudget) {
+        while (this.queue.getDbSizeBytes() > sizeBudget) {
+          const info = this.phase3Stmt.run(cutoffErrored, batchSize);
+          if (info.changes === 0) {
+            break;
+          }
+          deletedErrored += Number(info.changes);
+        }
+      }
+      this.queue.checkpointWal();
+      const result = {
+        deletedProcessed,
+        deletedErrored,
+        dbSizeBytesAfter: this.queue.getDbSizeBytes()
+      };
+      this.lastResult = result;
+      this.lastSweepAt = now;
+      if (deletedProcessed > 0 || deletedErrored > 0) {
+        this.log.info(
+          `Retention sweep: deleted ${deletedProcessed} processed, ${deletedErrored} errored. DB ${result.dbSizeBytesAfter} bytes. Took ${Date.now() - startedAt} ms.`
+        );
+      }
+      return result;
+    } finally {
+      this.running = false;
+    }
+  }
+  /** @returns Time of the most recent sweep, or null if none has run yet. */
+  getLastSweepAt() {
+    return this.lastSweepAt;
+  }
+  /** @returns Result of the most recent sweep, or null if none has run yet. */
+  getLastResult() {
+    return this.lastResult;
+  }
+};
+
+// src/upgrader-utils.ts
+var import_node_fs4 = require("node:fs");
 var import_node_os3 = require("node:os");
 var import_node_path4 = require("node:path");
 var import_node_stream = require("node:stream");
@@ -74665,10 +76820,10 @@ async function downloadRelease(version, path4) {
   }
   const readable = import_node_stream.Readable.fromWeb(result.body);
   try {
-    await (0, import_promises.pipeline)(readable, (0, import_node_fs3.createWriteStream)(path4));
+    await (0, import_promises.pipeline)(readable, (0, import_node_fs4.createWriteStream)(path4));
   } catch (err2) {
-    if ((0, import_node_fs3.existsSync)(path4)) {
-      (0, import_node_fs3.unlinkSync)(path4);
+    if ((0, import_node_fs4.existsSync)(path4)) {
+      (0, import_node_fs4.unlinkSync)(path4);
     }
     throw new Error(`Error while downloading release version ${version} to ${path4}`, { cause: err2 });
   }
@@ -74720,6 +76875,22 @@ async function execAsync(command, options) {
     });
   });
 }
+var STOP_DRAIN_TIMEOUT_MS = 1e4;
+function raceWithTimeout(promise, ms) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => resolve2("timeout"), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve2(value);
+      },
+      (err2) => {
+        clearTimeout(timer);
+        reject(err2);
+      }
+    );
+  });
+}
 var _App = class _App {
   constructor(medplum, agentId, logLevel, options) {
     __publicField(this, "medplum");
@@ -74746,6 +76917,8 @@ var _App = class _App {
     __publicField(this, "logStatsTimer");
     __publicField(this, "config");
     __publicField(this, "lastHeartbeatSentTime", -1);
+    __publicField(this, "durableQueue");
+    __publicField(this, "retentionSweeper");
     // Whether this process owns the `medplum-agent` PID, i.e. it is the sole agent that should
     // touch the data plane. A normally-started agent is primary from the outset (main.ts creates
     // the PID before start()). An upgrading agent stays non-primary until it wins the PID from the
@@ -74759,7 +76932,7 @@ var _App = class _App {
   }
   async start() {
     this.log.info("Medplum service starting...");
-    this.isPrimary = !(0, import_node_fs4.existsSync)(UPGRADE_MANIFEST_PATH);
+    this.isPrimary = !(0, import_node_fs5.existsSync)(UPGRADE_MANIFEST_PATH);
     await this.startWebSocket();
     const { listenersStarted } = await this.beginReloadConfig();
     const upgradeManifest = this.consumeUpgradeManifest();
@@ -74787,12 +76960,12 @@ var _App = class _App {
    * @returns The parsed manifest, or undefined if no upgrade is in progress.
    */
   consumeUpgradeManifest() {
-    if (!(0, import_node_fs4.existsSync)(UPGRADE_MANIFEST_PATH)) {
+    if (!(0, import_node_fs5.existsSync)(UPGRADE_MANIFEST_PATH)) {
       return void 0;
     }
-    const upgradeFile = (0, import_node_fs4.readFileSync)(UPGRADE_MANIFEST_PATH, { encoding: "utf-8" });
+    const upgradeFile = (0, import_node_fs5.readFileSync)(UPGRADE_MANIFEST_PATH, { encoding: "utf-8" });
     const upgradeDetails = JSON.parse(upgradeFile);
-    (0, import_node_fs4.unlinkSync)(UPGRADE_MANIFEST_PATH);
+    (0, import_node_fs5.unlinkSync)(UPGRADE_MANIFEST_PATH);
     return upgradeDetails;
   }
   async maybeFinalizeUpgrade(upgradeDetails) {
@@ -74887,9 +77060,10 @@ var _App = class _App {
       WebSocket: wrapper_default,
       binaryType: "nodebuffer"
     });
-    this.webSocket.addEventListener("error", () => {
+    this.webSocket.addEventListener("error", (event) => {
       if (!this.shutdown) {
-        this.log.error("WebSocket closed due to an error");
+        const error = event.error;
+        this.log.error("WebSocket closed due to an error", error);
       }
     });
     this.webSocket.addEventListener("open", async () => {
@@ -74907,6 +77081,7 @@ var _App = class _App {
       if (!this.shutdown && this.live) {
         this.live = false;
         this.log.info("WebSocket closed");
+        this.forEachChannelWorker((worker) => worker.onWebSocketDisconnect());
       }
     });
     this.webSocket.addEventListener("message", async (e) => {
@@ -74924,6 +77099,7 @@ var _App = class _App {
             this.notLiveHeartbeats = 0;
             this.outstandingHeartbeats = 0;
             this.startWebSocketWorker();
+            this.forEachChannelWorker((worker) => worker.notify());
             this.log.info("Successfully connected to Medplum server");
             break;
           case "agent:heartbeat:request":
@@ -74944,9 +77120,12 @@ var _App = class _App {
             if (!command.callback) {
               this.log.warn("Transmit response missing callback");
             }
+            if (this.routeServerResponseToWorker(command)) {
+              break;
+            }
             if (this.config?.status !== "active") {
               this.sendAgentDisabledError(command);
-            } else if (!(command.statusCode && command.statusCode >= 400)) {
+            } else if (command.statusCode === void 0 || command.statusCode < 400) {
               this.addToHl7Queue(command);
             } else {
               this.log.error(`Error during handling transmit request: ${command.body}`);
@@ -75049,6 +77228,16 @@ var _App = class _App {
     const keepAlive = agent?.setting?.find((setting) => setting.name === "keepAlive")?.valueBoolean;
     const maxClientsPerRemote = agent?.setting?.find((setting) => setting.name === "maxClientsPerRemote")?.valueInteger;
     const logStatsFreqSecs = agent?.setting?.find((setting) => setting.name === "logStatsFreqSecs")?.valueInteger;
+    const durableQueueOn = agent?.setting?.find((setting) => setting.name === "durableQueue")?.valueBoolean ?? false;
+    const queueDbPath = agent?.setting?.find((setting) => setting.name === "queueDbPath")?.valueString;
+    const queueRetentionDays = agent?.setting?.find((setting) => setting.name === "queueRetentionDays")?.valueInteger;
+    const queueRetentionMaxMb = agent?.setting?.find((setting) => setting.name === "queueRetentionMaxMb")?.valueInteger;
+    const queueErroredRetentionDays = agent?.setting?.find(
+      (setting) => setting.name === "queueErroredRetentionDays"
+    )?.valueInteger;
+    const queueSweepIntervalSecs = agent?.setting?.find(
+      (setting) => setting.name === "queueSweepIntervalSecs"
+    )?.valueInteger;
     if (this.keepAlive !== keepAlive) {
       const results = await Promise.allSettled(Array.from(this.hl7Clients.values()).map((pool) => pool.closeAll()));
       for (const result of results) {
@@ -75079,9 +77268,136 @@ var _App = class _App {
       this.log.info(`Stats logging enabled. Logging stats every ${this.logStatsFreqSecs} seconds...`);
       this.logStatsTimer ??= setInterval(() => this.logStats(), this.logStatsFreqSecs * 1e3);
     }
+    this.reconcileDurableQueue({
+      durableQueueOn,
+      queueDbPath,
+      queueRetentionDays,
+      queueRetentionMaxMb,
+      queueErroredRetentionDays,
+      queueSweepIntervalSecs
+    });
     const startPromises = await this.hydrateListeners();
     return { listenersStarted: this.waitForChannelsToStart(startPromises) };
   }
+  /**
+   * Opens, closes, or reconfigures the durable queue based on the latest config.
+   *
+   * Toggling `durableQueue` between true and false at runtime triggers a queue
+   * open/close. Toggling other queue settings (retention, sweep interval) starts
+   * a fresh {@link RetentionSweeper} against the existing DB without reopening it.
+   *
+   * Changing `queueDbPath` while the queue is already open is intentionally NOT
+   * supported — that would require moving / closing the existing DB. Operators
+   * who need to change the path should disable the queue, then re-enable with the
+   * new path.
+   * @param args - The current queue-related settings drawn from the Agent resource.
+   * @param args.durableQueueOn - Master switch — true to open the queue, false to close it.
+   * @param args.queueDbPath - Optional override for the DB file path (defaults to `<logDir>/medplum-agent-queue.sqlite`).
+   * @param args.queueRetentionDays - Time-based retention window for `processed` rows, in days.
+   * @param args.queueRetentionMaxMb - Soft cap on DB size, in MiB.
+   * @param args.queueErroredRetentionDays - Floor on `errored` / `nacked` retention, in days.
+   * @param args.queueSweepIntervalSecs - How often the retention sweeper runs, in seconds.
+   */
+  reconcileDurableQueue(args) {
+    if (!args.durableQueueOn) {
+      if (this.durableQueue) {
+        this.log.info("durableQueue disabled \u2014 closing queue.");
+        this.retentionSweeper?.stop();
+        this.retentionSweeper = void 0;
+        this.durableQueue.close();
+        this.durableQueue = void 0;
+      }
+      return;
+    }
+    if (!this.durableQueue) {
+      const path4 = args.queueDbPath ?? this.defaultQueueDbPath();
+      try {
+        this.durableQueue = DurableQueue.open({ path: path4, log: this.log });
+        this.log.info(`Durable queue opened at ${path4}.`);
+      } catch (err2) {
+        this.log.error(`Failed to open durable queue at ${path4}: ${Re(err2)}`);
+        this.durableQueue = void 0;
+        return;
+      }
+    }
+    this.durableQueue.startDispatchLease(() => this.onBecameQueueLeader());
+    this.retentionSweeper?.stop();
+    this.retentionSweeper = new RetentionSweeper({
+      queue: this.durableQueue,
+      log: this.log,
+      retentionDays: args.queueRetentionDays,
+      maxSizeMb: args.queueRetentionMaxMb,
+      erroredRetentionDays: args.queueErroredRetentionDays,
+      sweepIntervalSecs: args.queueSweepIntervalSecs
+    });
+    this.retentionSweeper.start();
+  }
+  /**
+   * Called by the {@link DurableQueue} dispatch-lease loop the first time we take the lease.
+   *
+   * This is the single point that runs `recoverOnStartup` and spins up the
+   * channel workers. Both depend on us being the only writer — running them at
+   * raw queue-open time would race with any peer that still holds the lease.
+   *
+   * Re-entrancy: if we lose and regain the lease later, this fires again. The
+   * recovery sweep is idempotent (no `claimed`/`inflight` rows means no work), and
+   * `maybeStartWorker` is a no-op if the worker is already running.
+   */
+  onBecameQueueLeader() {
+    const queue = this.durableQueue;
+    if (!queue) {
+      return;
+    }
+    const recovered = queue.recoverOnStartup();
+    if (recovered.requeued > 0 || recovered.failed > 0) {
+      this.log.info(
+        `Acquired queue lease \u2014 recovered interrupted rows: ${recovered.requeued} requeued (unsent), ${recovered.failed} failed (ambiguous, in-flight).`
+      );
+    }
+    const errors = [];
+    for (const channel of this.channels.values()) {
+      if (channel instanceof AgentHl7Channel) {
+        try {
+          channel.onBecameQueueLeader();
+        } catch (err2) {
+          errors.push(err2);
+        }
+      }
+    }
+    if (errors.length > 0) {
+      throw new Error(`Failed to start ${errors.length} HL7 channel worker(s) after acquiring queue lease`, {
+        cause: errors
+      });
+    }
+  }
+  /** @returns True when this agent currently holds the durable-queue lease. */
+  isQueueLeader() {
+    return this.durableQueue?.isLeader() ?? false;
+  }
+  /**
+   * Default location for the queue DB file when no override is provided.
+   *
+   * Co-locating with the main logger's log directory keeps everything an
+   * operator needs to mount a persistent volume in one place. The fallback is
+   * the current working directory — same default an unconfigured agent uses.
+   * @returns Absolute path to the default queue DB file.
+   */
+  defaultQueueDbPath() {
+    const baseDir = isWinstonWrapperLogger(this.log) && this.log.logDir || import_node_process2.default.cwd();
+    const sep = baseDir.endsWith("/") || baseDir.endsWith("\\") ? "" : "/";
+    return `${baseDir}${sep}medplum-agent-queue.sqlite`;
+  }
+  /**
+   * @returns The opened {@link DurableQueue}, or undefined when the queue setting
+   * is off. This is the OPEN handle, valid regardless of leadership — for intake,
+   * maintenance (WAL checkpoint, retention sweep), and diagnostics. For the
+   * dispatch path, gate worker startup on {@link DurableQueue.isLeader} (the cheap
+   * optimistic check); the authoritative gate is implicit in the dispatch ops
+   * themselves, which throw `QueueLeaseError` once a peer holds the lease.
+   */
+  getDurableQueue() {
+    return this.durableQueue;
+  }
   getStats() {
     const stats = getCurrentStats();
     let totalHl7Clients = 0;
@@ -75107,7 +77423,49 @@ var _App = class _App {
       live: this.live,
       outstandingHeartbeats: this.outstandingHeartbeats,
       channelStats,
-      clientStats
+      clientStats,
+      ...this.durableQueue ? { durableQueue: this.getDurableQueueStats(this.durableQueue) } : {}
+    };
+  }
+  /**
+   * Snapshot of durable-queue health, surfaced in `agent:stats:response`.
+   *
+   * Structured to fit the `AgentStatValue` shape — 3 nested levels of primitive
+   * records — so `AgentStats`'s index signature stays satisfied. Null sentinels
+   * become `-1` for the same reason ("never swept" reads as -1 on the wire).
+   *
+   * The field is only included when the queue is on; consumers that detect its
+   * absence know the queue is disabled, which is more honest than reporting a
+   * zeroed structure that a dashboard could misread as "queue on but idle."
+   * @param queue - The opened durable queue to read counters from.
+   * @returns A primitive-friendly snapshot fit for `AgentStats`.
+   */
+  getDurableQueueStats(queue) {
+    const counts = queue.countByState();
+    const channelDepth = {};
+    for (const channel of this.channels.values()) {
+      if (channel instanceof AgentHl7Channel) {
+        const d2 = queue.getChannelDepth(channel.getDefinition().name);
+        channelDepth[channel.getDefinition().name] = {
+          queued: d2.queued,
+          claimed: d2.claimed,
+          inflight: d2.inflight,
+          // -1 means "no queued rows" (a zero-aged-row would be 0).
+          oldestQueuedAgeMs: d2.oldestQueuedAgeMs ?? -1
+        };
+      }
+    }
+    const lastResult = this.retentionSweeper?.getLastResult();
+    return {
+      enabled: true,
+      isLeader: this.isQueueLeader(),
+      dbSizeBytes: queue.getDbSizeBytes(),
+      countsByState: counts,
+      channelDepth,
+      // -1 means "never swept yet."
+      lastSweepAt: this.retentionSweeper?.getLastSweepAt() ?? -1,
+      lastSweepDeletedProcessed: lastResult?.deletedProcessed ?? -1,
+      lastSweepDeletedErrored: lastResult?.deletedErrored ?? -1
     };
   }
   logStats() {
@@ -75334,25 +77692,131 @@ var _App = class _App {
       this.webSocket.close();
       this.webSocket = void 0;
     }
+    try {
+      const drained = await raceWithTimeout(this.drainForStop(), STOP_DRAIN_TIMEOUT_MS);
+      if (drained === "timeout") {
+        this.log.warn(
+          `Timed out after ${STOP_DRAIN_TIMEOUT_MS}ms waiting for clients/channels to stop \u2014 proceeding with shutdown.`
+        );
+      }
+    } catch (err2) {
+      this.log.error(`Error while stopping clients/channels: ${Re(err2)}`);
+    }
+    if (this.retentionSweeper) {
+      this.retentionSweeper.stop();
+      this.retentionSweeper = void 0;
+    }
+    if (this.durableQueue) {
+      this.durableQueue.close();
+      this.durableQueue = void 0;
+    }
+    this.log.info("Medplum service stopped successfully");
+  }
+  /**
+   * Closes all outbound HL7 client pools, then stops every channel. Factored out
+   * of {@link App.stop} so the whole drain can be raced against a single timeout.
+   *
+   * Uses allSettled rather than all: one channel failing to stop must not
+   * abandon the wait on its siblings — the durable-queue DB is closed right
+   * after this returns, so every channel that *can* drain must finish first.
+   */
+  async drainForStop() {
     if (this.hl7Clients.size !== 0) {
       const poolClosePromises = [];
       for (const pool of this.hl7Clients.values()) {
         poolClosePromises.push(pool.closeAll());
       }
-      await Promise.all(poolClosePromises);
+      const poolResults = await Promise.allSettled(poolClosePromises);
+      for (const result of poolResults) {
+        if (result.status === "rejected") {
+          this.log.error(`Error while closing HL7 client pool: ${Re(result.reason)}`);
+        }
+      }
       this.hl7Clients.clear();
     }
     const channelStopPromises = [];
     for (const channel of this.channels.values()) {
       channelStopPromises.push(channel.stop());
     }
-    await Promise.all(channelStopPromises);
-    this.log.info("Medplum service stopped successfully");
+    const results = await Promise.allSettled(channelStopPromises);
+    for (const result of results) {
+      if (result.status === "rejected") {
+        this.log.error(`Error while stopping channel: ${Re(result.reason)}`);
+      }
+    }
+  }
+  /**
+   * Dispatches an `agent:transmit:response` to the owning channel's worker, if any.
+   * @param response - The response message received over the agent WebSocket.
+   * @returns True if a worker claimed the response (caller should stop here);
+   *          false if no worker matched and legacy handling should run.
+   */
+  routeServerResponseToWorker(response2) {
+    if (!this.durableQueue) {
+      return false;
+    }
+    if (!response2.channel) {
+      return false;
+    }
+    const channel = this.channels.get(response2.channel);
+    if (!(channel instanceof AgentHl7Channel) || !channel.worker) {
+      return false;
+    }
+    channel.worker.onServerResponse(response2);
+    return true;
   }
   addToWebSocketQueue(message) {
     this.webSocketQueue.push(message);
     this.startWebSocketWorker();
   }
+  /** @returns True when the agent WebSocket is connected and the server has acknowledged the connect request. */
+  isLive() {
+    return this.live;
+  }
+  /**
+   * Removes a not-yet-sent `agent:transmit:request` from the WebSocket queue.
+   *
+   * Used by {@link ChannelQueueWorker.onWebSocketDisconnect} to decide whether
+   * an in-flight row can be safely requeued: a request still in this queue
+   * provably never reached the server. A request not found here was either
+   * already written to the socket or is mid-send — both ambiguous, so the
+   * caller must treat `false` as "may have been delivered".
+   * @param callbackId - The `callback` ID of the transmit request to remove.
+   * @returns True if the request was found and removed before being sent.
+   */
+  removeUnsentTransmit(callbackId) {
+    const index = this.webSocketQueue.findIndex(
+      (msg) => msg.type === "agent:transmit:request" && msg.callback === callbackId
+    );
+    if (index === -1) {
+      return false;
+    }
+    this.webSocketQueue.splice(index, 1);
+    return true;
+  }
+  /**
+   * Invokes `fn` for every channel that currently has a durable-queue worker running.
+   *
+   * Collects any failures so one worker throwing can't stop `fn` from reaching the
+   * rest, then surfaces them together as an aggregate error with the collected
+   * errors as its `cause`.
+   * @param fn - Callback applied to each running {@link ChannelQueueWorker}.
+   */
+  forEachChannelWorker(fn2) {
+    const errors = [];
+    for (const channel of this.channels.values()) {
+      if (channel instanceof AgentHl7Channel && channel.worker) {
+        try {
+          fn2(channel.worker);
+        } catch (err2) {
+          errors.push(err2);
+        }
+      }
+    }
+    if (errors.length > 0) {
+      throw new Error(`Failed to run channel worker callback for ${errors.length} channel(s)`, { cause: errors });
+    }
+  }
   addToHl7Queue(message) {
     this.hl7Queue.push(message);
     this.trySendToHl7Connection();
@@ -75531,8 +77995,8 @@ ${result}`);
         forceKillApp("medplum-agent-upgrader");
         removePidFile("medplum-agent-upgrader");
       }
-      if ((0, import_node_fs4.existsSync)(UPGRADE_MANIFEST_PATH)) {
-        (0, import_node_fs4.unlinkSync)(UPGRADE_MANIFEST_PATH);
+      if ((0, import_node_fs5.existsSync)(UPGRADE_MANIFEST_PATH)) {
+        (0, import_node_fs5.unlinkSync)(UPGRADE_MANIFEST_PATH);
       }
     }
     try {
@@ -75551,7 +78015,7 @@ ${result}`);
     }
     try {
       const command = __filename;
-      const logFile = (0, import_node_fs4.openSync)(UPGRADER_LOG_PATH, "w+");
+      const logFile = (0, import_node_fs5.openSync)(UPGRADER_LOG_PATH, "w+");
       child = (0, import_node_child_process.spawn)(command, message.version ? ["--upgrade", message.version] : ["--upgrade"], {
         detached: true,
         stdio: ["ignore", logFile, logFile, "ipc"]
@@ -75591,7 +78055,7 @@ ${result}`);
     }
     try {
       this.log.info("Writing upgrade manifest...", { previousVersion: yn, targetVersion });
-      (0, import_node_fs4.writeFileSync)(
+      (0, import_node_fs5.writeFileSync)(
         UPGRADE_MANIFEST_PATH,
         JSON.stringify({
           previousVersion: yn,
@@ -75655,14 +78119,25 @@ ${result}`);
     }
   }
   async sendToWebSocket(message) {
-    if (!this.webSocket) {
+    const ws2 = this.webSocket;
+    if (!ws2) {
       throw new Error("WebSocket not connected");
     }
     if ("accessToken" in message) {
       await this.medplum.refreshIfExpired();
       message.accessToken = this.medplum.getAccessToken();
     }
-    this.webSocket.send(JSON.stringify(message));
+    const payload = JSON.stringify(message);
+    const callback = message.type === "agent:transmit:request" ? message.callback : void 0;
+    if (callback && this.durableQueue) {
+      const durableQueue = this.durableQueue;
+      durableQueue.runInTransaction(() => {
+        durableQueue.markSent(callback);
+        ws2.send(payload);
+      });
+    } else {
+      ws2.send(payload);
+    }
   }
   sendAgentDisabledError(command) {
     const errMsg = "Agent.status is currently set to off";
@@ -75791,7 +78266,7 @@ ${result}`);
     });
   }
   isAgentUpgrading() {
-    if ((0, import_node_fs4.existsSync)(UPGRADE_MANIFEST_PATH)) {
+    if ((0, import_node_fs5.existsSync)(UPGRADE_MANIFEST_PATH)) {
       return true;
     }
     if (isAppRunning("medplum-upgrading-agent") || isAppRunning("medplum-agent-upgrader")) {
@@ -75834,7 +78309,7 @@ async function agentMain(argv) {
     console.log("    clientSecret: The OAuth client secret.");
     console.log("    agentId: The Medplum agent ID.");
     process.exit(0);
-  } else if ((0, import_node_fs5.existsSync)("agent.properties")) {
+  } else if ((0, import_node_fs6.existsSync)("agent.properties")) {
     args = readPropertiesFile("agent.properties");
   } else {
     console.log("Missing arguments");
@@ -75895,13 +78370,13 @@ function readCommandLineArgs(argv) {
 }
 function readPropertiesFile(fileName) {
   return Object.fromEntries(
-    (0, import_node_fs5.readFileSync)(fileName).toString().split("\n").map((line) => line.split("=").map((s) => s.trim()))
+    (0, import_node_fs6.readFileSync)(fileName).toString().split("\n").map((line) => line.split("=").map((s) => s.trim()))
   );
 }
 
 // src/upgrader.ts
 var import_node_child_process2 = require("node:child_process");
-var import_node_fs6 = require("node:fs");
+var import_node_fs7 = require("node:fs");
 var import_node_os5 = require("node:os");
 var import_node_process3 = __toESM(require("node:process"));
 var semver2 = __toESM(require_semver2());
@@ -75928,7 +78403,7 @@ async function upgraderMain(argv) {
     }
     version = argv[3] ?? await Dy("agent-upgrader");
     binPath = getReleaseBinPath(version);
-    if (!(0, import_node_fs6.existsSync)(binPath)) {
+    if (!(0, import_node_fs7.existsSync)(binPath)) {
       globalLogger.info(`Could not find binary at "${binPath}". Downloading release from GitHub...`);
       await downloadRelease(version, binPath);
       globalLogger.info("Release successfully downloaded");
@@ -75979,53 +78454,53 @@ async function main(argv) {
     createPidFile("medplum-agent-upgrader");
     await upgraderMain(argv);
   } else if (argv[2] === "--remove-old-services") {
-    const logFileFd = (0, import_node_fs7.openSync)(TEMP_LOG_FILE, "a");
+    const logFileFd = (0, import_node_fs8.openSync)(TEMP_LOG_FILE, "a");
     let allAgentServices = [];
     const currentServiceName = `MedplumAgent_${yn}`;
     while (!allAgentServices.includes(currentServiceName)) {
       const output = (0, import_node_child_process3.execSync)('cmd.exe /c sc query type= service state= all | findstr /i "SERVICE_NAME.*MedplumAgent"');
-      (0, import_node_fs7.appendFileSync)(logFileFd, `${output}\r
+      (0, import_node_fs8.appendFileSync)(logFileFd, `${output}\r
 `, { encoding: "utf-8" });
       allAgentServices = output.toString().trim().split("\n").map((line) => line.replace("SERVICE_NAME: ", "").trim());
-      (0, import_node_fs7.appendFileSync)(logFileFd, `All services: \r
+      (0, import_node_fs8.appendFileSync)(logFileFd, `All services: \r
 ${allAgentServices.join("\r\n")}\r
 `, { encoding: "utf-8" });
     }
     const servicesToRemove = argv[3] === "--all" ? allAgentServices : allAgentServices.filter((serviceName) => serviceName !== `MedplumAgent_${yn}`);
-    (0, import_node_fs7.appendFileSync)(logFileFd, `Medplum agent service to filter out: MedplumAgent_${yn}\r
+    (0, import_node_fs8.appendFileSync)(logFileFd, `Medplum agent service to filter out: MedplumAgent_${yn}\r
 `, {
       encoding: "utf-8"
     });
     for (const serviceName of servicesToRemove) {
       try {
         (0, import_node_child_process3.execSync)(`net stop ${serviceName}`);
-        (0, import_node_fs7.appendFileSync)(logFileFd, `${serviceName} stopped\r
+        (0, import_node_fs8.appendFileSync)(logFileFd, `${serviceName} stopped\r
 `, { encoding: "utf-8" });
         console.log(`${serviceName} stopped`);
       } catch (err2) {
-        (0, import_node_fs7.appendFileSync)(logFileFd, `Failed to stop service: ${serviceName}\r
+        (0, import_node_fs8.appendFileSync)(logFileFd, `Failed to stop service: ${serviceName}\r
 `, { encoding: "utf-8" });
-        (0, import_node_fs7.appendFileSync)(logFileFd, `${Re(err2)}\r
+        (0, import_node_fs8.appendFileSync)(logFileFd, `${Re(err2)}\r
 `, { encoding: "utf-8" });
         console.error(`Failed to stop service: ${serviceName}`);
         console.error(Re(err2));
       }
       try {
         (0, import_node_child_process3.execSync)(`sc.exe delete ${serviceName}`);
-        (0, import_node_fs7.appendFileSync)(logFileFd, `${serviceName} deleted\r
+        (0, import_node_fs8.appendFileSync)(logFileFd, `${serviceName} deleted\r
 `, { encoding: "utf-8" });
         console.log(`${serviceName} deleted`);
       } catch (err2) {
-        (0, import_node_fs7.appendFileSync)(logFileFd, `Failed to delete service: ${serviceName}\r
+        (0, import_node_fs8.appendFileSync)(logFileFd, `Failed to delete service: ${serviceName}\r
 `, { encoding: "utf-8" });
-        (0, import_node_fs7.appendFileSync)(logFileFd, `${Re(err2)}\r
+        (0, import_node_fs8.appendFileSync)(logFileFd, `${Re(err2)}\r
 `, { encoding: "utf-8" });
         console.error(`Failed to delete service: ${serviceName}`);
         console.error(Re(err2));
       }
     }
-    (0, import_node_fs7.closeSync)(logFileFd);
-  } else if ((0, import_node_fs7.existsSync)(UPGRADE_MANIFEST_PATH)) {
+    (0, import_node_fs8.closeSync)(logFileFd);
+  } else if ((0, import_node_fs8.existsSync)(UPGRADE_MANIFEST_PATH)) {
     createPidFile("medplum-upgrading-agent");
     await agentMain(argv);
   } else {