commandmate 0.49.2 → 0.49.3

package/dist/server/src/lib/relay/relay-delivery.js

@@ -46,7 +46,9 @@ exports.notifyRelayTurnCompleted = notifyRelayTurnCompleted;
 exports.notifyRelayPromptWaiting = notifyRelayPromptWaiting;
 exports.sweepExpiredRelays = sweepExpiredRelays;
 exports.pumpRelayDeliveries = pumpRelayDeliveries;
+exports.requestRelayPump = requestRelayPump;
 exports.runRelayMaintenanceTick = runRelayMaintenanceTick;
+const crypto_1 = require("crypto");
 const db_instance_1 = require("../../lib/db/db-instance");
 const relay_db_1 = require("../../lib/db/relay-db");
 const chat_db_1 = require("../../lib/db/chat-db");
@@ -96,6 +98,7 @@ function resetRelayDeliveryState() {
     (0, relay_delivery_claims_1.resetRelayDeliveryClaims)();
     globalThis.__relayPumpRunning = false;
     globalThis.__relayRecoveredBootId = undefined;
+    globalThis.__relayAttemptsRecoveredBootId = undefined;
 }
 /**
  * The bound send was confirmed: judge what was held for it (Issue #3957).
@@ -150,9 +153,38 @@ function evaluateRelayAfterSend(relayId) {
         });
     }
 }
-/** {@link recoverBoundRelays}, once per boot. */
+/**
+ * {@link recoverBoundRelays}, once per boot; and the delivery attempts the
+ * previous boot left `attempting` are held as `uncertain` (Issue #4064).
+ *
+ * The second step is marked done only once it succeeded, and is safe to run
+ * again (it never touches this boot's own attempts). Until it has run, the
+ * rows it would hold are not listed for delivery anyway — `attempting` is
+ * already a hold — so a failure here costs a label, never a second send.
+ */
 function ensureRelayRecovery(db) {
     const boot = (0, relay_boot_1.relayServerBootId)();
+    if (globalThis.__relayAttemptsRecoveredBootId !== boot) {
+        try {
+            const held = (0, relay_db_1.recoverInterruptedRelayDeliveryRefs)(db, boot);
+            globalThis.__relayAttemptsRecoveredBootId = boot;
+            if (held.length > 0)
+                logger.info('relay-interrupted-deliveries-held', { held: held.length });
+            // Issue #4082: each attempt this recovery moved to `uncertain` — and
+            // only those — is told to its requester, once.
+            for (const ref of held) {
+                const relay = (0, relay_db_1.getRelayById)(db, ref.relayId);
+                if (!relay)
+                    continue;
+                noteRelayHeld(db, relay, (0, relay_session_ref_1.resolveRelaySession)(db, relay.from), ref, relay.deliveryHold?.kind ?? null, relay_db_1.RELAY_DELIVERY_SERVER_RESTARTED);
+            }
+        }
+        catch (error) {
+            logger.warn('relay-delivery-recovery-failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     if (globalThis.__relayRecoveredBootId === boot)
         return;
     globalThis.__relayRecoveredBootId = boot;
@@ -325,9 +357,15 @@ function sweepExpiredRelays(db, now = Date.now()) {
             const locale = (0, model_change_push_notifier_1.resolveReadersLocale)(db);
             // A payload that never went out is superseded by the expiry notice: A
             // asked for an answer, and what they are getting is the news that there
-            // will not be one. Both slots (Issue #3957).
+            // will not be one. Both slots (Issue #3957). Issue #4064: not a payload
+            // under a delivery hold — it may have reached A, so it stays readable
+            // (`clearRelayPending` refuses it), the expiry notice then finds the
+            // slot taken and is not queued, and the relay is closed all the same.
             (0, relay_db_1.clearRelayPending)(db, relay.id, now);
-            (0, relay_db_1.clearRelayPendingReply)(db, relay.id, now);
+            // Issue #4082: a reply waiting behind a HELD payload is kept: settling
+            // the hold decides it (on a closed relay, it is then discarded and the
+            // requester told). Without a hold it is superseded, as before.
+            (0, relay_db_1.clearRelayPendingReplyUnlessHeld)(db, relay.id, now);
             const body = (0, relay_messages_1.buildRelayExpiredMessage)(locale, (0, relay_bound_reply_1.senderLabel)(db, relay), relay.expiresAt - relay.createdAt);
             const stashed = (0, relay_db_1.stashRelayPayload)(db, relay.id, 'expired', body, now);
             if (!(0, relay_db_1.markRelayExpired)(db, relay.id, now)) {
@@ -347,26 +385,48 @@ function sweepExpiredRelays(db, now = Date.now()) {
     }
     return expired;
 }
+/** The hold reason of a send that threw: what it last reported, if anything. */
+function reasonForThrow(attempt) {
+    if (attempt === null)
+        return 'send-threw';
+    return attempt.state === 'sent' ? 'threw-after-sent' : attempt.reason;
+}
 /**
  * Try to put one stashed payload into A's composer.
  *
- * The order — readiness, then send, then ledger — is deliberate. Marking first
- * would lose the answer whenever the send failed, and the send path has real
- * refusals in it (`prompt_waiting`, a session that went away mid-attempt). A
- * repeat delivery is prevented by the in-flight set within a process and by
- * `markRelayDelivered`'s guarded update across one, which is the idempotency the
- * Issue asks for by name.
+ * The order — readiness, then claim, then send, then ledger — is deliberate.
+ * Marking delivered first would lose the answer whenever the send failed, and
+ * the send path has real refusals in it (`prompt_waiting`, a session that went
+ * away mid-attempt).
  *
- * `kind` and `body` are what the pump's listing saw, and that listing is stale
- * by the time the readiness check returns (#3732): an earlier relay's send, or
- * this one's own capture, may have let a cancel or an expiry sweep run. So the
- * row is read again AFTER the last await before the send, and the send goes
- * ahead only when it still carries the same payload — and, for anything but an
- * expiry notice, is still open. The claim is taken in that same synchronous
- * stretch, so no cancel can slip in between the check and the send; from then
- * on `withdrawRelay` answers `delivering`.
+ * Issue #4064: the payload is taken DURABLY before the send
+ * ({@link claimRelayPayloadDelivery}: `attempting`, under a fresh attempt id),
+ * and only the caller whose write took it sends. How the send ended decides
+ * what happens to it, read from the send's OWN attempt (`onAttempt`, not the
+ * instance's shared `lastSend`):
+ *
+ *  - delivered → the slot is emptied (under the attempt id);
+ *  - `prompt_waiting`, or `not-sent` → queued again, retried by the next pump;
+ *  - anything else — `indeterminate` (`composer-residue` included), a throw
+ *    after `sent`, a throw before any state — → held as `uncertain` with the
+ *    reason. It is not listed again, it is not replaced, and the relay's later
+ *    payloads (the second slot's reply too) wait behind it.
+ *
+ * A server that stops anywhere in between leaves `attempting`, which is a hold
+ * too, and the next boot labels it `uncertain`. The in-flight set and the
+ * in-process claim stay — they are what `withdrawRelay` and the expiry sweep
+ * read — but they are no longer what prevents a second send.
+ *
+ * `kind`, `body` and `payloadId` are what the pump's listing saw, and that
+ * listing is stale by the time the readiness check returns (#3732): an earlier
+ * relay's send, or this one's own capture, may have let a cancel or an expiry
+ * sweep run. So the row is read again AFTER the last await before the send,
+ * and the send goes ahead only when it still carries the same payload — and,
+ * for anything but an expiry notice, is still open. The claims are taken in
+ * that same synchronous stretch, so no cancel can slip in between the check
+ * and the send; from then on `withdrawRelay` answers `delivering`.
  */
-async function deliverOne(db, relayId, kind, body) {
+async function deliverOne(db, relayId, kind, body, listedPayloadId) {
     const listed = (0, relay_db_1.getRelayById)(db, relayId);
     if (!listed)
         return 'skipped';
@@ -377,87 +437,294 @@ async function deliverOne(db, relayId, kind, body) {
         return 'held';
     }
     // Synchronous from here to the send: re-read, then claim.
-    const current = (0, relay_db_1.getRelayPendingPayload)(db, relayId);
-    if (!current || current.kind !== kind || current.body !== body) {
-        logger.info('relay-delivery-superseded', { relayId, kind });
+    const current = rereadDeliverablePayload(db, relayId, kind, body, listedPayloadId);
+    if (!current)
         return 'skipped';
+    const relay = current.relay;
+    const requester = (0, relay_session_ref_1.resolveRelaySession)(db, relay.from);
+    // Issue #4064: take the payload in the ledger before the first key. A write
+    // that fails or finds the payload taken means no send.
+    const attemptId = (0, crypto_1.randomUUID)();
+    let payloadId;
+    try {
+        payloadId = (0, relay_db_1.claimRelayPayloadDelivery)(db, {
+            relayId,
+            payloadId: current.payloadId,
+            kind,
+            body,
+            attemptId,
+            owner: (0, relay_boot_1.relayServerBootId)(),
+            mintPayloadId: (0, crypto_1.randomUUID)(),
+        });
     }
-    // An expiry notice is delivered from a CLOSED relay by design; everything
-    // else is only owed while the relay is open.
-    if (kind !== 'expired' && !(0, types_1.isOpenRelayState)(current.relay.state)) {
-        logger.info('relay-delivery-closed', { relayId, kind, state: current.relay.state });
+    catch (error) {
+        logger.warn('relay-delivery-claim-failed', {
+            relayId,
+            kind,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return 'failed';
+    }
+    if (payloadId === null) {
+        logger.info('relay-delivery-taken', { relayId, kind });
         return 'skipped';
     }
-    const relay = current.relay;
-    const requester = (0, relay_session_ref_1.resolveRelaySession)(db, relay.from);
+    const ref = { relayId, payloadId, attemptId };
     (0, relay_delivery_claims_1.claimRelayDelivery)(relayId);
-    let delivered = false;
+    let requeued = false;
     try {
-        const result = await (0, send_user_message_1.sendUserMessage)(db, {
-            worktreeId: requester.worktreeId,
-            content: body,
-            cliToolId: requester.cliToolId,
-            instanceId: requester.instanceId,
-            messageType: 'relay',
-            // The pointer back at the ledger. Also `session_relays.sent_request_id` for
-            // a reply, which carries a UNIQUE index — so a second delivery of the same
-            // relay cannot be recorded even if one were somehow attempted.
-            requestId: kind === 'reply' ? (0, chat_db_1.relayRequestId)(relay.id) : undefined,
-        });
+        let attempt = null;
+        let result;
+        try {
+            result = await (0, send_user_message_1.sendUserMessage)(db, {
+                worktreeId: requester.worktreeId,
+                content: body,
+                cliToolId: requester.cliToolId,
+                instanceId: requester.instanceId,
+                messageType: 'relay',
+                // The pointer back at the ledger. Also `session_relays.sent_request_id` for
+                // a reply, which carries a UNIQUE index — so a second delivery of the same
+                // relay cannot be recorded even if one were somehow attempted.
+                requestId: kind === 'reply' ? (0, chat_db_1.relayRequestId)(relay.id) : undefined,
+                // Issue #4064: this send's own outcome, not the instance's last one.
+                onAttempt: (observed) => {
+                    attempt = observed;
+                },
+            });
+        }
+        catch (error) {
+            const reason = reasonForThrow(attempt);
+            logger.warn('relay-delivery-uncertain', {
+                relayId,
+                kind,
+                reason,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (holdUncertain(db, ref, reason))
+                noteRelayHeld(db, relay, requester, ref, kind, reason);
+            return 'uncertain';
+        }
         if (!result.ok) {
-            logger.info('relay-delivery-refused', { relayId, kind, stage: result.stage });
-            return result.stage === 'prompt_waiting' ? 'held' : 'failed';
+            const settled = settleUnsentResult(db, ref, relay, requester, kind, result.stage, attempt);
+            requeued = settled.requeued;
+            return settled.outcome;
         }
         const now = Date.now();
-        if (kind === 'reply') {
-            if (!(0, relay_db_1.markRelayDelivered)(db, relay.id, (0, chat_db_1.relayRequestId)(relay.id), now)) {
-                // Somebody closed it underneath us. The message is already in A's
-                // composer, which is the outcome that mattered.
-                logger.info('relay-already-closed-on-deliver', { relayId });
-            }
-            (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'replied', requester, (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now, { overlap: relay.overlap, holdReason: relay.holdReason });
-        }
-        else if (kind === 'prompt') {
-            (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'waiting', requester, (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now);
+        const { completed, promoted } = recordDeliveryCompletion(db, ref, relay, kind, now);
+        if (!completed) {
+            logger.warn('relay-delivery-result-stale', { relayId, kind, attemptId });
+            return 'skipped';
         }
-        // Issue #3957: only the payload that was sent. A reply that replaced it
-        // or waits in the second slot survives, and the second slot is promoted
-        // now that the notice is out.
-        (0, relay_db_1.clearRelayPending)(db, relay.id, now, current.payloadId);
-        if (kind === 'prompt' && (0, relay_db_1.promoteRelayPendingReply)(db, relay.id, now)) {
+        if (promoted)
             globalThis.__relayPumpAgain = true;
-        }
+        writeDeliveredSystemLine(db, relay, requester, kind, now);
         logger.info('relay-delivered', { relayId, kind, to: `${requester.worktreeId}/${requester.instanceId}` });
-        delivered = true;
         return 'delivered';
     }
     finally {
-        // Issue #3957: a prompt notice that did not go out (refused, failed,
-        // threw) is back to unclaimed — and a reply that finished while it was
-        // being typed waits in the second slot. The reply supersedes the notice
-        // exactly as it would have had it arrived a moment later.
+        // Issue #3957: a prompt notice that did not go out (refused, failed) is
+        // back to unclaimed — and a reply that finished while it was being typed
+        // waits in the second slot. The reply supersedes the notice exactly as it
+        // would have had it arrived a moment later. Issue #4064: only a notice
+        // known not to have gone out (queued again); one held as uncertain is
+        // kept, and the reply waits behind it (the replacement refuses a held
+        // notice in its own condition, too).
         // A failure here must not keep the claim below from being released: a
         // claim left behind refuses every cancel and every expiry of the relay.
-        if (!delivered && kind === 'prompt') {
-            try {
-                if ((0, relay_db_1.replaceRelayPromptWithPendingReply)(db, relay.id, current.payloadId)) {
-                    logger.info('relay-prompt-superseded-after-failed-delivery', { relayId });
-                    globalThis.__relayPumpAgain = true;
-                }
-            }
-            catch (error) {
-                logger.warn('relay-prompt-supersede-failed', {
-                    relayId,
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        }
+        if (requeued && kind === 'prompt')
+            supersedeRequeuedPrompt(db, relay, payloadId);
         // Delivered: a reply is closed now and a prompt notice leaves the relay
         // open on purpose, so either way a later cancel must be judged by the row.
-        // Held or failed: nothing reached A, so the relay can be withdrawn again.
+        // Held, failed or uncertain: the relay can be withdrawn again (a cancel
+        // stops later deliveries; it never takes back what may be in A's composer).
         (0, relay_delivery_claims_1.releaseRelayDelivery)(relayId);
     }
 }
+/**
+ * The pump's listing re-read after the last await before the send (#3732),
+ * or `null` (logged) when the send must not go ahead. Synchronous on purpose:
+ * the caller claims in the same stretch.
+ */
+function rereadDeliverablePayload(db, relayId, kind, body, listedPayloadId) {
+    const current = (0, relay_db_1.getRelayPendingPayload)(db, relayId);
+    if (!current ||
+        current.kind !== kind ||
+        current.body !== body ||
+        current.payloadId !== listedPayloadId) {
+        logger.info('relay-delivery-superseded', { relayId, kind });
+        return null;
+    }
+    // An expiry notice is delivered from a CLOSED relay by design; everything
+    // else is only owed while the relay is open.
+    if (kind !== 'expired' && !(0, types_1.isOpenRelayState)(current.relay.state)) {
+        logger.info('relay-delivery-closed', { relayId, kind, state: current.relay.state });
+        return null;
+    }
+    return current;
+}
+/**
+ * A send that returned `ok: false`: held as `uncertain`, or queued again when
+ * it is known not to have gone out (Issue #4064).
+ */
+function settleUnsentResult(db, ref, relay, requester, kind, stage, observed) {
+    const relayId = ref.relayId;
+    // Every failure `sendUserMessage` returns reports its attempt first; one
+    // without (a caller's stub) is read as before (#4064 keeps that).
+    const notSent = observed === null || observed.state === 'not-sent';
+    if (!notSent) {
+        logger.info('relay-delivery-uncertain', {
+            relayId,
+            kind,
+            stage,
+            reason: observed.reason,
+        });
+        if (holdUncertain(db, ref, observed.reason))
+            noteRelayHeld(db, relay, requester, ref, kind, observed.reason);
+        return { outcome: 'uncertain', requeued: false };
+    }
+    logger.info('relay-delivery-refused', { relayId, kind, stage });
+    const requeued = requeue(db, ref);
+    return { outcome: stage === 'prompt_waiting' ? 'held' : 'failed', requeued };
+}
+/** Record a delivered attempt's result, by kind (Issue #4082). */
+function recordDeliveryCompletion(db, ref, relay, kind, now) {
+    // Issue #4082: the attempt's result is recorded FIRST, and only while it
+    // is still the attempt in progress. A stale one (held by another boot's
+    // recovery, resolved, or replaced by a retry's new attempt) writes
+    // nothing — no close, no emptied payload, no promotion, no system line —
+    // so the newer attempt and the relay's later reply are left as they are.
+    let completed;
+    let promoted = false;
+    if (kind === 'reply') {
+        // Issue #4064: closing the relay (which empties the payload) and ending
+        // the attempt commit together. A throw rolls both back: the row stays
+        // `attempting` with its body and payload id — held, never re-sent — and
+        // the next boot labels it.
+        const result = (0, relay_db_1.completeRelayReplyDelivery)(db, {
+            ...ref,
+            sentRequestId: (0, chat_db_1.relayRequestId)(relay.id),
+            now,
+        });
+        completed = result.completed;
+        if (completed && !result.closed) {
+            // Somebody closed it underneath us. The message is already in A's
+            // composer, which is the outcome that mattered.
+            logger.info('relay-already-closed-on-deliver', { relayId: ref.relayId });
+        }
+    }
+    else if (kind === 'prompt') {
+        // Issue #3957: only the payload that was sent. A reply that waits in the
+        // second slot survives, and is promoted now that the notice is out —
+        // Issue #4082: in the same transaction as the attempt's end.
+        // A throw here leaves the row `attempting` — held, never re-sent — and
+        // the next boot labels it.
+        ({ completed, promoted } = (0, relay_db_1.completeRelayPromptDelivery)(db, { ...ref, now }));
+    }
+    else {
+        completed = (0, relay_db_1.completeRelayPayloadDelivery)(db, { ...ref, now });
+    }
+    return { completed, promoted };
+}
+/** The requester's system line for a delivered payload (best-effort). */
+function writeDeliveredSystemLine(db, relay, requester, kind, now) {
+    const relayId = relay.id;
+    try {
+        if (kind === 'reply') {
+            (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'replied', requester, (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now, { overlap: relay.overlap, holdReason: relay.holdReason });
+        }
+        else if (kind === 'prompt') {
+            (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'waiting', requester, (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now);
+        }
+    }
+    catch (error) {
+        // Issue #4064: the send went out; a ledger write after it failing must
+        // not turn into a second send. The attempt is closed already (above).
+        logger.warn('relay-delivery-record-failed', {
+            relayId,
+            kind,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Issue #3957: a requeued prompt notice gives way to a reply waiting in the
+ * second slot. A failure is logged, never thrown (the claim must be released).
+ */
+function supersedeRequeuedPrompt(db, relay, payloadId) {
+    const relayId = relay.id;
+    try {
+        if ((0, relay_db_1.replaceRelayPromptWithPendingReply)(db, relay.id, payloadId)) {
+            logger.info('relay-prompt-superseded-after-failed-delivery', { relayId });
+            globalThis.__relayPumpAgain = true;
+        }
+    }
+    catch (error) {
+        logger.warn('relay-prompt-supersede-failed', {
+            relayId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/** Queue a payload again after a send known not to have happened (Issue #4064). */
+function requeue(db, ref) {
+    try {
+        return (0, relay_db_1.releaseRelayPayloadDelivery)(db, ref);
+    }
+    catch (error) {
+        // Left `attempting`: held, not re-sent. Safe, if not what was wanted.
+        logger.warn('relay-delivery-release-failed', {
+            relayId: ref.relayId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Hold a payload whose delivery may have reached A (Issue #4064).
+ *
+ * @returns Whether THIS call moved the attempt to `uncertain` (Issue #4082):
+ *   false for a stale attempt (resolved, retried, held by a recovery) and for
+ *   a write that failed — neither may be announced
+ */
+function holdUncertain(db, ref, reason) {
+    try {
+        return (0, relay_db_1.holdRelayPayloadDelivery)(db, { ...ref, reason });
+    }
+    catch (error) {
+        // Left `attempting`, which is a hold already; the next boot labels it.
+        logger.warn('relay-delivery-hold-failed', {
+            relayId: ref.relayId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Tell the requester, in its history, that one delivery attempt was held as
+ * `uncertain` (Issue #4082). Called only for an attempt this process just
+ * moved there. Keyed on the relay, payload AND attempt, so the same attempt is
+ * told once and a retry's new attempt (or another payload) is told again.
+ *
+ * Best-effort and at most one line: a failed write (or a stop before it) is
+ * not retried and never touches the hold; the socket frame goes out only after
+ * the row is committed.
+ */
+function noteRelayHeld(db, relay, requester, ref, kind, reason) {
+    try {
+        (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'held', requester, (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), ref.now ?? Date.now(), {
+            relayId: relay.id,
+            payload: `${kind ?? '-'}:${ref.payloadId}`,
+            attemptId: ref.attemptId,
+            deliveryReason: reason,
+        }, `${ref.payloadId}:${ref.attemptId}`);
+    }
+    catch (error) {
+        logger.warn('relay-held-line-failed', {
+            relayId: ref.relayId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 /**
  * Deliver every stashed payload that can be delivered now.
  *
@@ -476,12 +743,14 @@ async function pumpRelayDeliveries() {
         // delivered by one more pass rather than waiting for the next tick.
         for (let pass = 0; pass < PUMP_PASSES_MAX; pass += 1) {
             globalThis.__relayPumpAgain = false;
-            for (const item of (0, relay_db_1.listRelaysWithPendingPayload)(db)) {
+            // Issue #4064: a payload under a delivery hold is not listed, so a pass
+            // (or the next pump) never types it again; other relays go on.
+            for (const item of (0, relay_db_1.listDeliverableRelayPayloads)(db)) {
                 if (inFlight.has(item.relay.id))
                     continue;
                 inFlight.add(item.relay.id);
                 try {
-                    await deliverOne(db, item.relay.id, item.kind, item.body);
+                    await deliverOne(db, item.relay.id, item.kind, item.body, item.payloadId);
                 }
                 catch (error) {
                     logger.warn('relay-delivery-failed', {
@@ -506,6 +775,17 @@ async function pumpRelayDeliveries() {
         globalThis.__relayPumpRunning = false;
     }
 }
+/**
+ * Ask for a delivery pass without waiting for it (Issue #4082): a resolved hold
+ * queued a payload again or promoted a reply. A pump already running makes one
+ * more pass for it; otherwise one starts. Never sends by itself — the payload
+ * goes through {@link deliverOne}'s readiness, claim and input lock like any
+ * other — and never throws.
+ */
+function requestRelayPump() {
+    globalThis.__relayPumpAgain = true;
+    void pumpRelayDeliveries();
+}
 /** One tick of the background loop: sweep the deadlines, then deliver. */
 async function runRelayMaintenanceTick() {
     try {

package/dist/server/src/lib/relay/relay-messages.js

@@ -152,12 +152,16 @@ const SYSTEM_TEMPLATES = {
         replied: 'Reply from {alias}.',
         waiting: '{alias} is waiting for a confirmation.',
         expired: 'The delegation to {alias} expired without a reply.',
+        held: 'Could not confirm that the relay from {alias} reached this session; it will not be resent automatically. Check this pane, then settle it with commandmate relays resolve.',
+        'reply-discarded': 'The reply from {alias} that waited behind the settled confirmation notice was discarded: the delegation had already closed, so it is not delivered.',
     },
     ja: {
         requested: '{alias} へ委任、返信待ち',
         replied: '{alias} から返信',
         waiting: '{alias} が確認待ち',
         expired: '{alias} への委任が返信のないまま期限切れ',
+        held: '{alias} からの relay がこのセッションへ届いたか確認できません（自動では再送しません）。この画面を確かめてから commandmate relays resolve で片付けてください',
+        'reply-discarded': '片付けた確認の通知の後ろで待っていた {alias} の返信は、委任が既に閉じていたため破棄しました（配送しません）',
     },
 };
 /**
@@ -175,5 +179,14 @@ function buildRelaySystemLine(locale, kind, alias, detail = {}) {
         parts.push(`overlap=${detail.overlap}`);
     if (detail.holdReason)
         parts.push(`hold=${detail.holdReason}`);
+    // Issue #4082: what `commandmate relays resolve` names, as the CLI prints it.
+    if (detail.relayId)
+        parts.push(`relay=${detail.relayId}`);
+    if (detail.payload)
+        parts.push(`payload=${detail.payload}`);
+    if (detail.attemptId)
+        parts.push(`attempt=${detail.attemptId}`);
+    if (detail.deliveryReason)
+        parts.push(`reason=${detail.deliveryReason}`);
     return parts.length === 0 ? line : `${line} (${parts.join(', ')})`;
 }

package/dist/server/src/lib/relay/relay-system-line.js

@@ -8,8 +8,9 @@
  * chat surface, the History tab and any transcript that happens to be open,
  * without a fourth history surface being invented for four sentences.
  *
- * Idempotent: the request id is `relay-sys:<relayId>:<kind>` and each row is
- * probed for before it is written, so a delivery that is retried — which the
+ * Idempotent: the request id is `relay-sys:<relayId>:<kind>` (Issue #4082:
+ * `…:<kind>:<scope>` for a line written once per payload attempt) and each row
+ * is probed for before it is written, in the same transaction, so a delivery that is retried — which the
  * pump does by design — does not stack four "waiting for the reply" lines.
  *
  * Never throws. A transcript line is the least important of a relay's three
@@ -35,23 +36,35 @@ const logger = (0, logger_1.createLogger)('relay-system-line');
  * @param subject - Whose name the sentence carries (always the worker, B)
  * @param at - Epoch ms
  * @param detail - Issue #3957: the overlap and hold reason a `replied` line names
+ * @param scope - Issue #4082: what makes this line one of several of its kind on
+ *   the relay (`<payloadId>:<attemptId>` for `held`); null for the once-per-relay lines
  * @returns Whether a row was written by this call
  */
-function writeRelaySystemLine(db, relayId, kind, target, subject, at = Date.now(), detail = {}) {
-    const requestId = `${chat_db_1.RELAY_SYSTEM_REQUEST_ID_PREFIX}${relayId}:${kind}`;
+function writeRelaySystemLine(db, relayId, kind, target, subject, at = Date.now(), detail = {}, scope = null) {
+    // Issue #4082: the probe and the write key the line through the same builder.
+    const requestId = (0, chat_db_1.relaySystemRequestId)(relayId, kind, scope);
     try {
-        if ((0, chat_db_1.findMessageByRequestId)(db, target.worktreeId, requestId))
+        // Probe and write in one IMMEDIATE transaction: a second connection (or a
+        // second server on the same file) cannot slip its own copy in between.
+        const message = db
+            .transaction(() => {
+            if ((0, chat_db_1.findMessageByRequestId)(db, target.worktreeId, requestId))
+                return null;
+            const locale = (0, model_change_push_notifier_1.resolveReadersLocale)(db);
+            return (0, chat_db_1.createRelaySystemMessage)(db, {
+                worktreeId: target.worktreeId,
+                cliToolId: target.cliToolId,
+                instanceId: target.instanceId,
+                content: (0, relay_messages_1.buildRelaySystemLine)(locale, kind, subject.alias, detail),
+                relayId,
+                kind,
+                scope,
+                at,
+            });
+        })
+            .immediate();
+        if (message === null)
             return false;
-        const locale = (0, model_change_push_notifier_1.resolveReadersLocale)(db);
-        const message = (0, chat_db_1.createRelaySystemMessage)(db, {
-            worktreeId: target.worktreeId,
-            cliToolId: target.cliToolId,
-            instanceId: target.instanceId,
-            content: (0, relay_messages_1.buildRelaySystemLine)(locale, kind, subject.alias, detail),
-            relayId,
-            kind,
-            at,
-        });
         try {
             (0, ws_server_1.broadcastMessage)('message', {
                 worktreeId: target.worktreeId,

package/dist/server/src/lib/relay/types.js

@@ -10,8 +10,9 @@
  * @module lib/relay/types
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LEGACY_RELAY_BINDING_FIELDS = exports.OPEN_RELAY_STATES = void 0;
+exports.LEGACY_RELAY_BINDING_FIELDS = exports.RELAY_HOLD_ACTIONS = exports.OPEN_RELAY_STATES = void 0;
 exports.isOpenRelayState = isOpenRelayState;
+exports.relayRequesterPaneCommand = relayRequesterPaneCommand;
 exports.emptyRelayCounts = emptyRelayCounts;
 /** The states from which a relay can still produce a delivery. */
 exports.OPEN_RELAY_STATES = ['pending', 'prompt'];
@@ -19,7 +20,17 @@ exports.OPEN_RELAY_STATES = ['pending', 'prompt'];
 function isOpenRelayState(state) {
     return exports.OPEN_RELAY_STATES.includes(state);
 }
-/** The v62 fields of a row with no binding, as a legacy relay reads (Issue #3957). */
+/**
+ * The `capture` that shows the requester's pane — where a held relay payload
+ * went (Issue #4064). The exact instance, so an alias or a worktree default
+ * cannot point at another pane.
+ */
+function relayRequesterPaneCommand(requester) {
+    return `commandmate capture ${requester.worktreeId} --instance ${requester.instanceId} --pane`;
+}
+/** Every {@link RelayHoldAction}, for validation. */
+exports.RELAY_HOLD_ACTIONS = ['confirm', 'retry', 'discard'];
+/** The v62 fields of a row with no binding, as a legacy relay reads (Issue #3957), and no delivery hold (#4064). */
 exports.LEGACY_RELAY_BINDING_FIELDS = {
     bindMode: 'legacy',
     sendState: null,
@@ -29,6 +40,7 @@ exports.LEGACY_RELAY_BINDING_FIELDS = {
     obsState: null,
     holdReason: null,
     overlap: null,
+    deliveryHold: null,
 };
 /** An empty {@link RelayCounts}. */
 function emptyRelayCounts() {