@nanhara/hara 0.122.2 → 0.122.4

package/dist/gateway/flows.js

@@ -7,12 +7,91 @@
 // Platform-agnostic: matching only reads the generic InboundMsg fields each adapter populates (chatType,
 // mentions), so a flow works on whatever platform surfaces the data it asks for.
 import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { chunkText } from "./telegram.js";
 import { deliverResult, parseDeliver } from "../cron/deliver.js";
 import { addPending } from "./flows-pending.js";
 import { redactSensitiveValue } from "../security/secrets.js";
 const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+function deliveryLabel(spec) {
+    const parsed = parseDeliver(spec);
+    return "error" in parsed ? "invalid-target" : parsed.platform;
+}
+function hashFlowKey(...parts) {
+    const hash = createHash("sha256");
+    for (const part of parts) {
+        const value = String(part ?? "");
+        hash.update(String(Buffer.byteLength(value, "utf8"))).update(":").update(value).update(";");
+    }
+    return hash.digest("hex");
+}
+function canonicalFlowValue(value, depth = 0) {
+    if (depth > 64)
+        return '"<depth-limit>"';
+    if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalFlowValue(item, depth + 1)).join(",")}]`;
+    if (typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalFlowValue(record[key], depth + 1)}`).join(",")}}`;
+    }
+    return '"<unsupported>"';
+}
+/** Stable only when the adapter provides a true platform event id. Falling back to message text/time could
+ * suppress two legitimate identical messages, so adapters without ids retain at-least-once behavior. */
+export function flowSourceKey(context, platform, messageId) {
+    const id = messageId?.trim();
+    return context && id ? hashFlowKey("hara-flow-source-v1", context.scope, platform, id) : undefined;
+}
+async function runFlowEffect(receipts, key, effect) {
+    if (!receipts || !key)
+        return effect();
+    const claim = await receipts.claim(key);
+    if (!claim)
+        return; // already completed in this process or before a restart
+    try {
+        await effect();
+        await claim.complete();
+    }
+    catch (error) {
+        // Releasing a receipt is cleanup. A store I/O failure must not hide the transport/model error that made
+        // this source event retry in the first place.
+        try {
+            await claim.release();
+        }
+        catch {
+            /* best-effort; the bounded in-flight lease can be reclaimed after restart */
+        }
+        throw error;
+    }
+}
+/** Persist each chat-sized piece separately. A later piece can fail without making a retry resend pieces whose
+ * external send and local receipt both completed. Including a hash of content avoids joining a changed model
+ * answer to receipts from an older answer, while the persisted key remains opaque. */
+async function runFlowTextEffect(receipts, key, text, effect) {
+    for (const [index, part] of chunkText(text || "(empty)", 3_500).entries()) {
+        const partKey = key ? hashFlowKey("hara-flow-effect-part-v1", key, index, part) : undefined;
+        await runFlowEffect(receipts, partKey, () => effect(part, partKey));
+    }
+}
+async function runFlowDeliveryEffect(receipts, key, spec, text, signal) {
+    const target = parseDeliver(spec);
+    const deliver = async (part, idempotencyKey) => {
+        const error = await deliverResult(spec, part, signal, idempotencyKey);
+        if (error)
+            throw new Error(`deliver(${deliveryLabel(spec)}) failed — ${error}`);
+    };
+    if (!("error" in target) && target.platform !== "webhook") {
+        await runFlowTextEffect(receipts, key, text, deliver);
+    }
+    else {
+        await runFlowEffect(receipts, key, () => deliver(text, key));
+    }
+}
 function isStrings(value) {
     return typeof value === "string" || (Array.isArray(value) && value.every((item) => typeof item === "string"));
 }
@@ -145,6 +224,11 @@ const MAX_SENDER_RATE_BUCKETS = 1_024;
 const MAX_CHAT_RATE_BUCKETS = 1_024;
 const MAX_RATE_KEY_PART_CHARS = 160;
 const RATE_SWEEP_INTERVAL = 64;
+const FLOW_SOURCE_RETRY_TTL_MS = 60 * 60_000;
+const MAX_FLOW_SOURCE_RETRIES = 4_096;
+const MAX_FLOW_SOURCE_ATTEMPTS = 3;
+const FLOW_RETRY_BASE_DELAY_MS = 2_000;
+const admittedFlowSources = new Map();
 let claimsUntilRateSweep = RATE_SWEEP_INTERVAL;
 function boundedRateKey(...parts) {
     return parts
@@ -205,10 +289,60 @@ export function resetFlowRateStateForTests() {
     chatFlowRate.clear();
     globalFlowRate = [];
     activeFlowRuns = 0;
+    admittedFlowSources.clear();
     claimsUntilRateSweep = RATE_SWEEP_INTERVAL;
 }
-function claimFlowRun(rule, m, platform) {
+function flowRetryState(sourceRunKey, now) {
+    if (!sourceRunKey)
+        return undefined;
+    const state = admittedFlowSources.get(sourceRunKey);
+    if (!state)
+        return undefined;
+    if (now >= state.expiresAt) {
+        admittedFlowSources.delete(sourceRunKey);
+        return undefined;
+    }
+    admittedFlowSources.delete(sourceRunKey);
+    admittedFlowSources.set(sourceRunKey, state); // bounded LRU refresh; expiry deliberately stays fixed
+    return state;
+}
+function rememberFlowSource(sourceRunKey, now) {
+    if (!sourceRunKey)
+        return;
+    for (const [key, state] of admittedFlowSources) {
+        if (now >= state.expiresAt)
+            admittedFlowSources.delete(key);
+    }
+    while (admittedFlowSources.size >= MAX_FLOW_SOURCE_RETRIES) {
+        const oldest = admittedFlowSources.keys().next().value;
+        if (!oldest)
+            break;
+        admittedFlowSources.delete(oldest);
+    }
+    admittedFlowSources.set(sourceRunKey, {
+        attempts: 1,
+        expiresAt: now + FLOW_SOURCE_RETRY_TTL_MS,
+        nextAttemptAt: now,
+        alarmed: false,
+    });
+}
+function markFlowRunFailed(sourceRunKey, now) {
+    if (!sourceRunKey)
+        return;
+    const state = admittedFlowSources.get(sourceRunKey);
+    if (!state)
+        return;
+    const exponent = Math.max(0, state.attempts - 1);
+    state.nextAttemptAt = now + Math.min(30_000, FLOW_RETRY_BASE_DELAY_MS * (2 ** exponent));
+}
+function forgetFlowSource(sourceRunKey) {
+    if (sourceRunKey)
+        admittedFlowSources.delete(sourceRunKey);
+}
+function claimFlowRun(rule, m, platform, sourceRunKey, durableRetry) {
     const now = Date.now();
+    const retryState = durableRetry === undefined ? flowRetryState(sourceRunKey, now) : undefined;
+    const retry = durableRetry ?? (retryState !== undefined);
     if (--claimsUntilRateSweep <= 0) {
         sweepRateMap(senderFlowRate, now, RATE_MINUTE_MS, MAX_SENDER_RUNS_PER_MINUTE);
         sweepRateMap(chatFlowRate, now, RATE_HOUR_MS, MAX_CHAT_RUNS_PER_HOUR);
@@ -216,7 +350,24 @@ function claimFlowRun(rule, m, platform) {
     }
     globalFlowRate = pruneRateTimes(globalFlowRate, now, RATE_HOUR_MS, MAX_GLOBAL_RUNS_PER_HOUR);
     if (activeFlowRuns >= MAX_ACTIVE_FLOW_RUNS)
-        return false;
+        return { claimed: false, retry };
+    if (retryState) {
+        if (retryState.attempts >= MAX_FLOW_SOURCE_ATTEMPTS) {
+            const alarm = !retryState.alarmed;
+            retryState.alarmed = true;
+            return { claimed: false, retry: true, exhausted: true, alarm };
+        }
+        if (now < retryState.nextAttemptAt) {
+            return { claimed: false, retry: true, retryAfterMs: retryState.nextAttemptAt - now };
+        }
+        retryState.attempts++;
+        activeFlowRuns++;
+        return { claimed: true, retry: true };
+    }
+    if (durableRetry) {
+        activeFlowRuns++;
+        return { claimed: true, retry: true };
+    }
     const senderKey = boundedRateKey(rule.name, platform, m.chatId, m.userId);
     const chatKey = boundedRateKey(rule.name, platform, m.chatId);
     const senderMinute = prepareRateBucket(senderFlowRate, senderKey, now, RATE_MINUTE_MS, MAX_SENDER_RATE_BUCKETS, MAX_SENDER_RUNS_PER_MINUTE);
@@ -224,21 +375,36 @@ function claimFlowRun(rule, m, platform) {
     // A full identity table is itself an abuse signal. Reject new identities instead of evicting a live
     // bucket and letting an attacker cycle through unbounded sender/chat ids.
     if (!senderMinute || !chatHour)
-        return false;
+        return { claimed: false, retry: false };
     if (senderMinute.length >= MAX_SENDER_RUNS_PER_MINUTE ||
         countRateTimes(chatHour, now, RATE_MINUTE_MS) >= MAX_CHAT_RUNS_PER_MINUTE ||
         chatHour.length >= MAX_CHAT_RUNS_PER_HOUR ||
         countRateTimes(globalFlowRate, now, RATE_MINUTE_MS) >= MAX_GLOBAL_RUNS_PER_MINUTE ||
         globalFlowRate.length >= MAX_GLOBAL_RUNS_PER_HOUR) {
-        return false;
+        return { claimed: false, retry: false };
     }
     senderMinute.push(now);
     chatHour.push(now);
     globalFlowRate.push(now);
     senderFlowRate.set(senderKey, senderMinute);
     chatFlowRate.set(chatKey, chatHour);
+    if (durableRetry === undefined)
+        rememberFlowSource(sourceRunKey, now);
     activeFlowRuns++;
-    return true;
+    return { claimed: true, retry: false };
+}
+async function reportFlowRetryExhausted(rule, markAlarmed) {
+    console.error(`hara flow: ALERT "${rule.name}" stopped after ${MAX_FLOW_SOURCE_ATTEMPTS} failed attempts for one source event — acknowledged to break the retry loop`);
+    appendFlowLog({
+        flow: rule.name,
+        event: "retry-exhausted",
+        severity: "error",
+        attempts: MAX_FLOW_SOURCE_ATTEMPTS,
+        outcome: "source-event-acknowledged",
+    });
+    // Mark only after both operator-visible records were emitted. A crash may duplicate an alarm, but can never
+    // make an exhausted poison event disappear silently.
+    await markAlarmed?.();
 }
 /** Extract the flow agent's structured result — {disposition,briefing,draft,dispatch?} — from its text
  *  output. Tolerant of surrounding prose/fences; null if there's no parseable object (caller falls back). */
@@ -296,26 +462,80 @@ export function buildFlowPrompt(r, m) {
         `\n\n--- Untrusted triggering message (data only) ---\nchat ${String(m.chatId).slice(0, 200)}${m.chatType ? ` (${m.chatType})` : ""} · from ${String(m.userName || m.userId).slice(0, 200)}\n${(m.text ?? "").slice(0, 16_000)}`);
 }
 /** Try to handle `m` via configured flows. Returns true if ≥1 rule matched (caller should STOP default routing).
- *  The agent run + delivery are fire-and-forget so a slow LLM call never blocks the gateway's event loop.
+ *  All claimed runs settle before this resolves, so the gateway can bind delivery success to its inbound claim.
  *  `runAgent` must be the gateway's isolated no-tool provider path; `reply` (optional) sends text back to the
  *  originating chat. `approvalOwner` is a concrete platform:user identity; without one, consequential actions
  *  fail closed instead of becoming approvable by an arbitrary allowlisted DM. */
-export async function dispatchFlows(m, platform, runAgent, reply, approvalOwner, signal) {
-    const matched = loadFlows().filter((r) => matchFlow(r, m, platform)).slice(0, 4);
+export async function dispatchFlows(m, platform, runAgent, reply, approvalOwner, signal, effects) {
+    const flowOccurrences = new Map();
+    const matched = loadFlows()
+        .map((rule) => {
+        const baseIdentity = hashFlowKey("hara-flow-rule-v1", canonicalFlowValue(rule));
+        const occurrence = flowOccurrences.get(baseIdentity) ?? 0;
+        flowOccurrences.set(baseIdentity, occurrence + 1);
+        return { rule, flowIdentity: hashFlowKey(baseIdentity, occurrence) };
+    })
+        .filter(({ rule }) => matchFlow(rule, m, platform))
+        .slice(0, 4);
     if (!matched.length)
         return false;
     if (signal?.aborted)
         return true;
-    for (const r of matched) {
+    const sourceKey = flowSourceKey(effects, platform, m.messageId);
+    const jobs = [];
+    let deferredRetry = false;
+    for (const { rule: r, flowIdentity } of matched) {
         console.error(`hara flow: "${r.name}" matched · ${platform} ${m.chatType ?? "?"} ${m.chatId}`);
-        if (!claimFlowRun(r, m, platform)) {
-            console.error(`hara flow: "${r.name}" rate/concurrency limit reached — trigger dropped`);
+        const sourceRunKey = sourceKey ? hashFlowKey("hara-flow-run-v1", sourceKey, flowIdentity) : undefined;
+        let durableClaim;
+        if (sourceRunKey && sourceKey && effects?.runs) {
+            const durableAdmission = await effects.runs.claim(sourceRunKey, sourceKey);
+            if (durableAdmission.kind === "complete")
+                continue;
+            if (durableAdmission.kind === "exhausted") {
+                if (durableAdmission.alarm) {
+                    await reportFlowRetryExhausted(r, () => effects.runs.markAlarmed(sourceRunKey));
+                }
+                continue;
+            }
+            if (durableAdmission.kind === "backoff") {
+                console.error(`hara flow: "${r.name}" retry deferred — backoff has ${Math.ceil(durableAdmission.retryAfterMs / 1_000)}s left`);
+                deferredRetry = true;
+                continue;
+            }
+            durableClaim = durableAdmission.claim;
+        }
+        const admission = claimFlowRun(r, m, platform, sourceRunKey, durableClaim?.retry);
+        if (!admission.claimed) {
+            await durableClaim?.release();
+            if (admission.exhausted) {
+                if (admission.alarm)
+                    await reportFlowRetryExhausted(r);
+            }
+            else if (admission.retry) {
+                const wait = admission.retryAfterMs === undefined ? "capacity is full" : `backoff has ${Math.ceil(admission.retryAfterMs / 1_000)}s left`;
+                console.error(`hara flow: "${r.name}" retry deferred — ${wait}`);
+                deferredRetry = true;
+            }
+            else {
+                console.error(`hara flow: "${r.name}" rate/concurrency limit reached — trigger dropped`);
+            }
             continue;
         }
         const home = r.cwd ? (r.cwd === "~" ? homedir() : r.cwd.replace(/^~\//, homedir() + "/")) : undefined;
-        void (async () => {
+        jobs.push((async () => {
+            let failed = false;
+            let durableSettled = false;
             try {
-                const output = (await runAgent(buildFlowPrompt(r, m), home, r.schema, signal)).trim();
+                const effectKey = (stage, target = "", targetIndex = 0) => sourceKey
+                    ? hashFlowKey("hara-flow-effect-v1", sourceKey, flowIdentity, stage, targetIndex, target)
+                    : undefined;
+                let output = durableClaim?.output;
+                if (output === undefined) {
+                    output = (await runAgent(buildFlowPrompt(r, m), home, r.schema, signal)).trim();
+                    if (!signal?.aborted)
+                        await durableClaim?.saveOutput(output);
+                }
                 if (signal?.aborted)
                     return;
                 if (!output)
@@ -378,28 +598,36 @@ export async function dispatchFlows(m, platform, runAgent, reply, approvalOwner,
                             context: `派单 ${parsed.dispatch.agent}: ${parsed.dispatch.task.slice(0, 30)}`,
                             notify: r.deliver,
                             origin: `${platform}:${m.chatId}`,
+                            sourceKey: effectKey("pending-org", `${platform}:${m.chatId}\0${parsed.dispatch.agent}`),
                         });
                         if (pendingDispatch)
                             briefing += `\n\n[${pendingDispatch.id}] 拟派单：${parsed.dispatch.agent} ← ${parsed.dispatch.task}\n—— /approve ${pendingDispatch.id} 派出 · /reject ${pendingDispatch.id} 取消`;
                     }
                     if (draft && (route.needsApproval || route.replyInChat) && (!canAutoReply || route.needsApproval || wantsDispatch)) {
-                        const pendingSend = park({ kind: "send", target: `${platform}:${m.chatId}`, draft, context: (parsed.briefing || parsed.draft).slice(0, 40), notify: r.deliver });
+                        const pendingTarget = `${platform}:${m.chatId}`;
+                        const pendingSend = park({
+                            kind: "send",
+                            target: pendingTarget,
+                            draft,
+                            context: (parsed.briefing || parsed.draft).slice(0, 40),
+                            notify: r.deliver,
+                            sourceKey: effectKey("pending-send", pendingTarget),
+                        });
                         if (pendingSend) {
                             briefing += `\n\n[${pendingSend.id}] 拟发到群：${draft}\n—— /approve ${pendingSend.id} 发出 · /edit ${pendingSend.id} <内容> · /reject ${pendingSend.id}`;
                         }
                     }
                     else if (route.replyInChat && canAutoReply && reply) {
-                        if (!signal?.aborted)
-                            await reply(draft).catch(() => { });
+                        if (!signal?.aborted) {
+                            await runFlowTextEffect(effects?.receipts, effectKey("reply-in-chat", `${platform}:${m.chatId}`), draft, reply);
+                        }
                         console.error(`hara flow "${r.name}": answered in-chat (route)`);
                     }
                     if (route.notifyOwner || route.needsApproval || wantsDispatch || (route.replyInChat && !canAutoReply)) {
-                        for (const d of asArray(r.deliver)) {
+                        for (const [targetIndex, d] of asArray(r.deliver).entries()) {
                             if (signal?.aborted)
                                 return;
-                            const err = await deliverResult(d, briefing);
-                            if (err)
-                                console.error(`hara flow "${r.name}": deliver(${d}) failed — ${err}`);
+                            await runFlowDeliveryEffect(effects?.receipts, effectKey("notify-owner", d, targetIndex), d, briefing, signal);
                         }
                     }
                     else
@@ -409,8 +637,9 @@ export async function dispatchFlows(m, platform, runAgent, reply, approvalOwner,
                 // Auto-answer lane (replyOn): safe Q&A goes straight back to the origin chat — no owner round-trip.
                 // Runs BEFORE the noise gate so an answered question needs no WeChat push at all.
                 if (r.replyOn?.length && dispo && r.replyOn.includes(dispo) && parsed?.draft?.trim() && reply) {
-                    if (!signal?.aborted)
-                        await reply(parsed.draft.trim()).catch(() => { });
+                    if (!signal?.aborted) {
+                        await runFlowTextEffect(effects?.receipts, effectKey("reply-in-chat", `${platform}:${m.chatId}`), parsed.draft.trim(), reply);
+                    }
                     console.error(`hara flow "${r.name}": ${dispo} — answered in-chat (replyOn)`);
                     if (!r.notifyOn?.length || !r.notifyOn.includes(dispo))
                         return; // answered; only ALSO brief the owner if asked to
@@ -423,7 +652,15 @@ export async function dispatchFlows(m, platform, runAgent, reply, approvalOwner,
                 }
                 // Drafted reply → park for approval; approved = posted back to the ORIGIN chat.
                 if (parsed?.draft?.trim() && (dispo === "reply" || dispo === "handle")) {
-                    const pendingSend = park({ kind: "send", target: `${platform}:${m.chatId}`, draft: parsed.draft.trim(), context: (parsed.briefing || parsed.draft).slice(0, 40), notify: r.deliver });
+                    const pendingTarget = `${platform}:${m.chatId}`;
+                    const pendingSend = park({
+                        kind: "send",
+                        target: pendingTarget,
+                        draft: parsed.draft.trim(),
+                        context: (parsed.briefing || parsed.draft).slice(0, 40),
+                        notify: r.deliver,
+                        sourceKey: effectKey("pending-send", pendingTarget),
+                    });
                     if (pendingSend) {
                         briefing += `\n\n[${pendingSend.id}] 拟发到群：${parsed.draft.trim()}\n—— /approve ${pendingSend.id} 发出 · /edit ${pendingSend.id} <内容> · /reject ${pendingSend.id}`;
                     }
@@ -438,27 +675,65 @@ export async function dispatchFlows(m, platform, runAgent, reply, approvalOwner,
                         context: `派单 ${parsed.dispatch.agent}: ${parsed.dispatch.task.slice(0, 30)}`,
                         notify: r.deliver,
                         origin: `${platform}:${m.chatId}`, // the asker's chat — an approved task's result goes back here
+                        sourceKey: effectKey("pending-org", `${platform}:${m.chatId}\0${parsed.dispatch.agent}`),
                     });
                     if (pendingDispatch)
                         briefing += `\n\n[${pendingDispatch.id}] 拟派单：${parsed.dispatch.agent} ← ${parsed.dispatch.task}\n—— /approve ${pendingDispatch.id} 派出 · /reject ${pendingDispatch.id} 取消`;
                 }
-                for (const d of asArray(r.deliver)) {
+                for (const [targetIndex, d] of asArray(r.deliver).entries()) {
                     if (signal?.aborted)
                         return;
-                    const err = await deliverResult(d, briefing);
-                    if (err)
-                        console.error(`hara flow "${r.name}": deliver(${d}) failed — ${err}`);
+                    await runFlowDeliveryEffect(effects?.receipts, effectKey("notify-owner", d, targetIndex), d, briefing, signal);
+                }
+                if (r.reply && reply && !signal?.aborted) {
+                    await runFlowTextEffect(effects?.receipts, effectKey("reply-briefing", `${platform}:${m.chatId}`), briefing, reply);
                 }
-                if (r.reply && reply && !signal?.aborted)
-                    await reply(briefing).catch(() => { });
             }
             catch (e) {
+                failed = true;
                 console.error(`hara flow "${r.name}": ${e instanceof Error ? e.message : String(e)}`);
+                if (durableClaim) {
+                    if (signal?.aborted) {
+                        await durableClaim.release();
+                        durableSettled = true;
+                    }
+                    else {
+                        const failure = await durableClaim.fail();
+                        durableSettled = true;
+                        if (failure.exhausted) {
+                            if (failure.alarm)
+                                await reportFlowRetryExhausted(r, () => durableClaim.markAlarmed());
+                            return;
+                        }
+                    }
+                }
+                else {
+                    markFlowRunFailed(sourceRunKey, Date.now());
+                }
+                throw e;
             }
             finally {
-                activeFlowRuns = Math.max(0, activeFlowRuns - 1);
+                try {
+                    if (durableClaim && !durableSettled) {
+                        if (signal?.aborted)
+                            await durableClaim.release();
+                        else if (!failed)
+                            await durableClaim.complete();
+                    }
+                    if (!durableClaim && !failed && !signal?.aborted)
+                        forgetFlowSource(sourceRunKey);
+                }
+                finally {
+                    activeFlowRuns = Math.max(0, activeFlowRuns - 1);
+                }
             }
-        })();
+        })());
     }
+    const outcomes = await Promise.allSettled(jobs);
+    const failed = outcomes.find((outcome) => outcome.status === "rejected");
+    if (failed)
+        throw failed.reason;
+    if (deferredRetry)
+        throw new Error("a previously admitted flow retry is deferred by backoff or capacity; retry the source event");
     return true;
 }

package/dist/gateway/outbound-files.js

@@ -17,6 +17,10 @@ const SNAPSHOT_SUFFIX = new RegExp(`-${UUID}(?=\\.|$)`, "i");
 // a later path replacement is never mistaken for the consumed snapshot.
 const consumedSnapshotIdentities = new Map();
 const outboundQueueLocks = new Map();
+function throwIfOutboundCancelled(signal) {
+    if (signal?.aborted)
+        throw new Error("gateway file queue cancelled before commit");
+}
 export function outboundSnapshotDir(outbox) {
     return `${resolve(outbox)}.files`;
 }
@@ -72,7 +76,8 @@ function existingBatchUsage(dir) {
     }
     return { bytes, files };
 }
-async function appendOutbox(outbox, snapshot) {
+async function appendOutbox(outbox, snapshot, signal) {
+    throwIfOutboundCancelled(signal);
     const path = resolve(outbox);
     let before;
     try {
@@ -99,6 +104,9 @@ async function appendOutbox(outbox, snapshot) {
             || !ownedByProcess(path))
             throw new Error(`unsafe gateway outbox: ${outbox}`);
         await handle.chmod(0o600);
+        // This append makes the snapshot visible to the adapter. Re-check after all descriptor validation and
+        // immediately before that irreversible queue mutation.
+        throwIfOutboundCancelled(signal);
         await handle.writeFile(snapshot + "\n", "utf8");
         await handle.sync();
     }
@@ -107,7 +115,8 @@ async function appendOutbox(outbox, snapshot) {
     }
 }
 /** Copy a verified source fd to a private immutable snapshot, then append only that snapshot to the queue. */
-async function queueOutboundSnapshotLocked(sourcePath, outbox) {
+async function queueOutboundSnapshotLocked(sourcePath, outbox, signal) {
+    throwIfOutboundCancelled(signal);
     const source = resolve(sourcePath);
     const verified = await openVerifiedRegularFileNoFollow(source, {
         action: "send",
@@ -138,6 +147,7 @@ async function queueOutboundSnapshotLocked(sourcePath, outbox) {
         const buffer = Buffer.allocUnsafe(64 * 1024);
         let position = 0;
         while (position < verified.info.size) {
+            throwIfOutboundCancelled(signal);
             const want = Math.min(buffer.length, verified.info.size - position);
             const { bytesRead } = await verified.handle.read(buffer, 0, want, position);
             if (bytesRead <= 0)
@@ -167,9 +177,12 @@ async function queueOutboundSnapshotLocked(sourcePath, outbox) {
         await destination.chmod(0o600);
         await destination.close();
         destination = undefined;
+        // Publishing the private snapshot is reversible until appendOutbox succeeds; cancellation after this
+        // check is caught below and removes the published inode before returning.
+        throwIfOutboundCancelled(signal);
         renameSync(temporary, snapshot);
         published = true;
-        await appendOutbox(outbox, snapshot);
+        await appendOutbox(outbox, snapshot, signal);
         return snapshot;
     }
     catch (error) {
@@ -193,16 +206,17 @@ async function queueOutboundSnapshotLocked(sourcePath, outbox) {
     }
 }
 /** Serialize admissions for one outbox so parallel send_file calls cannot race past the aggregate budget. */
-export async function queueOutboundSnapshot(sourcePath, outbox) {
+export async function queueOutboundSnapshot(sourcePath, outbox, signal) {
     const key = resolve(outbox);
     const previous = outboundQueueLocks.get(key) ?? Promise.resolve();
     let release;
     const gate = new Promise((resolveGate) => { release = resolveGate; });
     const current = previous.then(() => gate, () => gate);
     outboundQueueLocks.set(key, current);
-    await previous.catch(() => { });
     try {
-        return await queueOutboundSnapshotLocked(sourcePath, outbox);
+        await previous.catch(() => { });
+        throwIfOutboundCancelled(signal);
+        return await queueOutboundSnapshotLocked(sourcePath, outbox, signal);
     }
     finally {
         release();