@nanhara/hara 0.122.2 → 0.122.4

package/dist/gateway/serve.js

@@ -3,8 +3,9 @@
 // subprocess (the cron pattern) on that chat's session → the reply is sent back. This is hara's first
 // persistent process; it is never required by the core CLI.
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { telegramAdapter } from "./telegram.js";
-import { dispatchFlows } from "./flows.js";
+import { dispatchFlows, flowSourceKey } from "./flows.js";
 import { handleOwnerReply, runNoToolModel } from "./flows-pending.js";
 import { chatContext, chatCd, newChatSession, ownsChatSession, resolveOwnedSessionId, setChatSession, setChatAgent, toggleVoice } from "./sessions.js";
 import { plainChat } from "../cron/deliver.js";
@@ -18,6 +19,7 @@ import { join, resolve } from "node:path";
 import { chmodSync, mkdirSync, writeFileSync, readFileSync, existsSync, statSync, rmSync } from "node:fs";
 import { redactToolSubprocessOutput, terminateSubprocessTree } from "../security/subprocess-env.js";
 import { cleanupOutboundSnapshot, cleanupOutboundSnapshots, consumeOutboundSnapshots, queueOutboundSnapshot, } from "./outbound-files.js";
+import { acquireGatewayInstance, gatewayRuntimeScope, GatewayFlowRunStore, GatewayInboundTracker, GatewayMessageDeduper, GatewayRunOutcomeStore, } from "./runtime-state.js";
 /** Parse a leading slash-command from a chat message (pure). null if it isn't one. */
 export function parseCommand(text) {
     const m = /^\/([a-z]+)\b\s*([\s\S]*)$/i.exec(text.trim());
@@ -44,6 +46,18 @@ export function canonicalGatewayPlatform(platform) {
         return "wecom";
     return value;
 }
+/** Stable FIFO lane for all state and side effects belonging to one chat actor. DMs deliberately use one
+ * lane per chat; group users remain isolated even when they share a room. Only the hash is retained in RAM. */
+export function gatewayAdmissionKey(runtimeScope, message) {
+    return createHash("sha256")
+        .update("hara-gateway-admission-v1\0")
+        .update(runtimeScope)
+        .update("\0")
+        .update(String(message.chatId))
+        .update("\0")
+        .update(message.chatType === "group" ? String(message.userId) : "dm")
+        .digest("hex");
+}
 /** Strip hara's CLI chrome from captured `-p` output so a chat reply is just the answer: MCP status lines
  *  (`mcp: …`) and the token-usage footer (`… · ↑N ↓N tok`). Colors are off when piped, so no ANSI to strip. */
 export function cleanReply(raw) {
@@ -54,26 +68,79 @@ export function cleanReply(raw) {
         .trim();
 }
 let outboxSeq = 0;
-/** Snapshot and materialize a direct gateway file before an adapter sees it. This also covers TTS output, so
- * every outbound attachment crosses the same verified-byte boundary rather than handing adapters a pathname. */
-async function deliverVerifiedLocalFile(adapter, chatId, sourcePath) {
-    const sendFile = adapter.sendFile;
-    if (!sendFile)
-        throw new Error("this platform can't send files yet");
+const INTERRUPTED_EFFECT_REPLY = "⚠️ 上一次操作在已经开始后中断，可能已经修改文件、调用工具或改变本地状态。为避免重复副作用，Hara 没有自动重跑。请先检查工作区，再发送一条明确的新指令继续。";
+const TERMINAL_EFFECT_REPLY = "⚠️ 这条消息对应的操作已经执行过，但保存的回复或附件已被安全缓存回收，无法再次投递。为避免重复修改文件或再次调用工具，Hara 没有自动重跑。请先检查工作区，再发送一条明确的新指令继续。";
+function resultFromRunOutcome(outcome) {
+    if (outcome.status === "running")
+        return { reply: INTERRUPTED_EFFECT_REPLY, files: [] };
+    if (outcome.status === "terminal")
+        return { reply: TERMINAL_EFFECT_REPLY, files: [] };
+    return {
+        reply: outcome.reply,
+        files: outcome.files.map((file) => ({ ...file, snapshotPath: "" })),
+        ...(outcome.voice ? { voice: { ...outcome.voice, snapshotPath: "" } } : {}),
+    };
+}
+async function finishRunOutcome(store, messageId, candidate) {
+    try {
+        await store.finish(messageId, {
+            reply: candidate.reply,
+            files: candidate.files.map(({ safeName, bytes }) => ({ safeName, bytes })),
+            ...(candidate.voice
+                ? { voice: { safeName: candidate.voice.safeName, bytes: candidate.voice.bytes } }
+                : {}),
+        });
+    }
+    catch (error) {
+        // Never deliver a side effect's success unless its immutable outcome is durable. The started tombstone
+        // remains fail-closed; temporary snapshots are no longer needed and must not leak.
+        for (const file of candidate.files)
+            if (file.snapshotPath)
+                cleanupOutboundSnapshot(file.snapshotPath);
+        if (candidate.voice?.snapshotPath)
+            cleanupOutboundSnapshot(candidate.voice.snapshotPath);
+        throw error;
+    }
+}
+/** Execute any irreversible gateway action at most once for a stable platform message id. A started marker is
+ * durable before `effect`; completion is durable before transport. A retry therefore returns only the cached
+ * result (or an interrupted warning) and never invokes `effect` again. */
+export async function executeDurableGatewayEffect(store, messageId, effect, signal) {
+    if (signal?.aborted)
+        throw signal.reason instanceof Error ? signal.reason : new Error("gateway effect cancelled");
+    const prior = await store.start(messageId);
+    if (signal?.aborted)
+        throw signal.reason instanceof Error ? signal.reason : new Error("gateway effect cancelled");
+    if (prior) {
+        const recovered = resultFromRunOutcome(prior);
+        if (prior.status !== "complete")
+            await finishRunOutcome(store, messageId, recovered);
+        return recovered;
+    }
+    const executed = await effect();
+    if (signal?.aborted) {
+        for (const file of executed.files)
+            if (file.snapshotPath)
+                cleanupOutboundSnapshot(file.snapshotPath);
+        if (executed.voice?.snapshotPath)
+            cleanupOutboundSnapshot(executed.voice.snapshotPath);
+        throw signal.reason instanceof Error ? signal.reason : new Error("gateway effect cancelled");
+    }
+    await finishRunOutcome(store, messageId, executed);
+    return executed;
+}
+async function snapshotVerifiedLocalFile(sourcePath) {
     const outbox = join(tmpdir(), `hara-direct-send-${process.pid}-${Date.now()}-${outboxSeq++}.txt`);
     let payload;
     try {
         await queueOutboundSnapshot(sourcePath, outbox);
         [payload] = await consumeOutboundSnapshots(outbox);
-        cleanupOutboundSnapshots(outbox, payload ? [payload.snapshotPath] : []);
         if (!payload)
             throw new Error("the private file snapshot could not be verified");
-        await sendFile(chatId, payload);
+        return payload;
     }
     finally {
-        if (payload)
-            cleanupOutboundSnapshot(payload.snapshotPath);
-        cleanupOutboundSnapshots(outbox);
+        cleanupOutboundSnapshots(outbox, payload ? [payload.snapshotPath] : []);
     }
 }
 export class GatewayQueueFullError extends Error {
@@ -427,7 +494,11 @@ async function buildAdapter(platform) {
             return null;
         }
         // The iLink user_id is whoever scanned the QR — the bot owner. Auto-allow them so there's no wxid dance.
-        return { adapter: weixinAdapter(creds), ownerId: creds.user_id || undefined };
+        return {
+            adapter: weixinAdapter(creds),
+            ownerId: creds.user_id || undefined,
+            runtimeScope: gatewayRuntimeScope("weixin", creds.user_id),
+        };
     }
     if (platform === "discord") {
         const token = process.env.HARA_DISCORD_TOKEN;
@@ -436,7 +507,7 @@ async function buildAdapter(platform) {
             return null;
         }
         const { discordAdapter } = await import("./discord.js");
-        return { adapter: discordAdapter(token) };
+        return { adapter: discordAdapter(token), runtimeScope: gatewayRuntimeScope("discord", token) };
     }
     if (platform === "feishu" || platform === "lark") {
         const appId = process.env.HARA_FEISHU_APP_ID;
@@ -446,7 +517,7 @@ async function buildAdapter(platform) {
             return null;
         }
         const { feishuAdapter } = await import("./feishu.js");
-        return { adapter: feishuAdapter(appId, appSecret) };
+        return { adapter: feishuAdapter(appId, appSecret), runtimeScope: gatewayRuntimeScope("feishu", appId) };
     }
     if (platform === "slack") {
         const appToken = process.env.HARA_SLACK_APP_TOKEN;
@@ -456,7 +527,7 @@ async function buildAdapter(platform) {
             return null;
         }
         const { slackAdapter } = await import("./slack.js");
-        return { adapter: slackAdapter(appToken, botToken) };
+        return { adapter: slackAdapter(appToken, botToken), runtimeScope: gatewayRuntimeScope("slack", appToken) };
     }
     if (platform === "mattermost") {
         const url = process.env.HARA_MATTERMOST_URL;
@@ -466,7 +537,7 @@ async function buildAdapter(platform) {
             return null;
         }
         const { mattermostAdapter } = await import("./mattermost.js");
-        return { adapter: mattermostAdapter(url, token) };
+        return { adapter: mattermostAdapter(url, token), runtimeScope: gatewayRuntimeScope("mattermost", `${url}\0${token}`) };
     }
     if (platform === "matrix") {
         const homeserver = process.env.HARA_MATRIX_HOMESERVER;
@@ -477,7 +548,7 @@ async function buildAdapter(platform) {
             return null;
         }
         const { matrixAdapter } = await import("./matrix.js");
-        return { adapter: matrixAdapter(homeserver, token, userId) };
+        return { adapter: matrixAdapter(homeserver, token, userId), runtimeScope: gatewayRuntimeScope("matrix", `${homeserver}\0${userId}`) };
     }
     if (platform === "dingtalk" || platform === "ding") {
         const clientId = process.env.HARA_DINGTALK_CLIENT_ID;
@@ -487,7 +558,7 @@ async function buildAdapter(platform) {
             return null;
         }
         const { dingtalkAdapter } = await import("./dingtalk.js");
-        return { adapter: dingtalkAdapter(clientId, clientSecret) };
+        return { adapter: dingtalkAdapter(clientId, clientSecret), runtimeScope: gatewayRuntimeScope("dingtalk", clientId) };
     }
     if (platform === "wecom" || platform === "wework") {
         const botId = process.env.HARA_WECOM_BOT_ID;
@@ -497,7 +568,10 @@ async function buildAdapter(platform) {
             return null;
         }
         const { wecomAdapter } = await import("./wecom.js");
-        return { adapter: wecomAdapter(botId, secret, process.env.HARA_WECOM_WS_URL) };
+        return {
+            adapter: wecomAdapter(botId, secret, process.env.HARA_WECOM_WS_URL),
+            runtimeScope: gatewayRuntimeScope("wecom", botId),
+        };
     }
     if (platform === "signal") {
         const rpcUrl = process.env.HARA_SIGNAL_RPC_URL;
@@ -507,14 +581,37 @@ async function buildAdapter(platform) {
             return null;
         }
         const { signalAdapter } = await import("./signal.js");
-        return { adapter: signalAdapter(rpcUrl, number) };
+        return { adapter: signalAdapter(rpcUrl, number), runtimeScope: gatewayRuntimeScope("signal", `${rpcUrl}\0${number}`) };
     }
     const token = process.env.HARA_TELEGRAM_TOKEN;
     if (!token) {
         console.error("hara gateway: set HARA_TELEGRAM_TOKEN (from @BotFather) and HARA_GATEWAY_ALLOWED=<your telegram user id>.");
         return null;
     }
-    return { adapter: telegramAdapter(token) };
+    return { adapter: telegramAdapter(token), runtimeScope: gatewayRuntimeScope("telegram", token) };
+}
+/** Recover exactly one private run marker while the corresponding credential-scoped gateway is stopped.
+ * The store requires a message-id-bound action confirmation; this wrapper also takes the normal instance
+ * lease so an operator cannot race a live callback or its platform acknowledgement. */
+export async function recoverGatewayRunOutcome(options) {
+    const requestedPlatform = canonicalGatewayPlatform(options.platform);
+    if (![
+        "telegram", "weixin", "discord", "feishu", "slack", "mattermost", "matrix", "dingtalk", "wecom", "signal",
+    ].includes(requestedPlatform)) {
+        throw new Error(`unsupported gateway recovery platform '${options.platform}'`);
+    }
+    const built = await buildAdapter(requestedPlatform);
+    if (!built)
+        throw new Error("gateway credentials are required to locate the credential-scoped outcome marker");
+    const platform = built.adapter.name || requestedPlatform;
+    const release = acquireGatewayInstance(built.runtimeScope, { displayPlatform: platform });
+    try {
+        const store = await GatewayRunOutcomeStore.open(gatewayRuntimeScope("run-cache", built.runtimeScope));
+        return await store.recover(options.messageId, options.confirmation);
+    }
+    finally {
+        release();
+    }
 }
 /** Allowlist = the env ids ∪ a platform-confirmed owner (WeChat QR) ∪ an explicitly configured approval
  * owner. Matrix/Signal bot account IDs are deliberately not treated as human owners. */
@@ -592,10 +689,29 @@ export async function runGateway(opts) {
     const built = await buildAdapter(requestedPlatform);
     if (!built)
         process.exit(1);
-    const { adapter, ownerId } = built;
+    const { adapter, ownerId, runtimeScope } = built;
     // Adapter names are the source of truth (e.g. requested `lark` builds the `feishu` adapter). Keep the
     // requested spelling only for startup/config hints; all persisted/routable identities are canonical.
     const platform = adapter.name || canonicalGatewayPlatform(requestedPlatform);
+    const releaseInstance = acquireGatewayInstance(runtimeScope, { displayPlatform: platform });
+    let messageDeduper;
+    let flowEffectReceipts;
+    let flowRuns;
+    let runOutcomes;
+    try {
+        messageDeduper = await GatewayMessageDeduper.open(runtimeScope);
+        // A distinct credential-scoped receipt log lets a redelivered inbound event resume after a partial flow
+        // failure without repeating replies/notifications that already succeeded.
+        flowEffectReceipts = await GatewayMessageDeduper.open(gatewayRuntimeScope("flow-effects", runtimeScope), {
+            ttlMs: 24 * 60 * 60_000,
+        });
+        flowRuns = await GatewayFlowRunStore.open(gatewayRuntimeScope("flow-runs", runtimeScope));
+        runOutcomes = await GatewayRunOutcomeStore.open(gatewayRuntimeScope("run-cache", runtimeScope));
+    }
+    catch (error) {
+        releaseInstance();
+        throw error;
+    }
     const explicitOwner = process.env.HARA_GATEWAY_OWNER?.trim();
     const allowlist = resolveAllowlist(process.env.HARA_GATEWAY_ALLOWED, ownerId, explicitOwner);
     const approvalUserId = resolveApprovalOwner(explicitOwner, ownerId, allowlist);
@@ -618,7 +734,11 @@ export async function runGateway(opts) {
         console.error(`hara gateway: flow approvals restricted to ${approvalOwner}.`);
     }
     const ac = new AbortController();
+    // Every daemon-originated outbound operation inherits shutdown cancellation. Telegram/Feishu also enforce
+    // their own hard transfer deadlines, so an SDK that ignores this signal still cannot pin shutdown forever.
+    const sendMessage = (chatId, text, idempotencyKey) => adapter.send(chatId, text, ac.signal, idempotencyKey);
     const sessionRuns = new KeyedSerialQueue(8, 4, 64, 32);
+    const inboundHandlers = new GatewayInboundTracker();
     const stop = () => ac.abort(new GatewayQueueClosedError());
     const closeQueue = () => sessionRuns.close(new GatewayQueueClosedError());
     process.once("SIGINT", stop);
@@ -629,243 +749,424 @@ export async function runGateway(opts) {
         await pruneStaleMedia(platform).catch((error) => {
             console.error(`hara gateway: media cleanup failed — ${error instanceof Error ? error.message : String(error)}`);
         });
-        await adapter.start(async (m) => {
+        await adapter.start((m) => inboundHandlers.track((async () => {
             try {
                 if (ac.signal.aborted)
                     return;
-                // Flows (opt-in, ~/.hara/flows.json): rules that intercept a matching inbound message → agent task + deliver,
-                // BEFORE the allowlist/DM-driver logic. A matched flow is authorized by its own presence in the user's config
-                // (group senders won't be in the allowlist), so this must run first; the agent run/deliver is fire-and-forget.
-                const flowRan = await dispatchFlows(m, platform, (prompt, home, schema, signal) => runFlowAgent(prompt, home ?? cwd, schema, signal), // stateless per trigger; rule cwd = agent's home
-                (text) => adapter.send(m.chatId, plainChat(text)), // flow replies are chat bubbles too — flatten markdown
-                approvalOwner, ac.signal);
-                if (flowRan)
-                    return;
-                // The gateway's default is a DM driver. Unknown channel shapes fail closed too: older/third-party adapters
-                // may omit chatType, and treating every unknown room as a DM would expose the full coding agent in groups.
-                // The chatId===userId invariant preserves legacy Telegram/Weixin-style DMs until their adapter is upgraded.
-                if (!isPrivateApprovalMessage(m))
-                    return;
-                if (!isAllowed(m.userId, allowlist)) {
-                    console.error(`hara gateway: ✗ message from ${m.userId} — not in allowlist. Add it to HARA_GATEWAY_ALLOWED to authorize.`);
-                    await adapter.send(m.chatId, "⛔ not authorized.");
-                    return;
+                let existingRunOutcome = null;
+                let outcomeLoadError;
+                try {
+                    existingRunOutcome = await runOutcomes.load(m.messageId);
                 }
-                // Owner approving a pending flow action ("采用" / "改:…" / "取消")? Execute it (e.g. post the drafted reply
-                // back to the origin group) instead of routing this as a fresh command. This is the flow approve→execute loop.
-                if (approvalUserId && String(m.userId) === approvalUserId && isPrivateApprovalMessage(m)) {
-                    const pendingReply = await handleOwnerReply(approvalOwner, m.text, { signal: ac.signal });
-                    if (pendingReply) {
-                        await adapter.send(m.chatId, pendingReply);
-                        return;
-                    }
+                catch (error) {
+                    // Claim first so a corrupt/unreadable terminal marker consumes the same bounded failure budget instead
+                    // of causing an unbounded platform redelivery loop. Presence is conservatively treated as durable.
+                    outcomeLoadError = error;
                 }
-                // If a tmux session opted in (via `hara remote ask/bind`), this reply is its input → inject it into that
-                // pane, let it react, and reply with the session's NEW output (on-inbound relay — quiet + iLink-friendly:
-                // one reply per message, no continuous push). Owner-gated by the allowlist check above.
-                if (!parseCommand(m.text)) {
-                    const pane = pickPaneForReply();
-                    if (pane) {
-                        console.error(`hara gateway: routed reply → tmux pane ${pane}`);
-                        const before = capturePane(pane) ?? "";
-                        injectTmux(pane, m.text);
-                        // wait for the session's output to SETTLE (poll every 800ms; stable for ~1.6s → done; cap ~10s) so a
-                        // slow response isn't missed and we don't capture mid-stream.
-                        let after = "";
-                        let stable = 0;
-                        for (let i = 0; i < 12; i++) {
-                            await new Promise((r) => setTimeout(r, 800));
-                            const cur = capturePane(pane) ?? "";
-                            if (cur === after) {
-                                if (++stable >= 2)
-                                    break;
-                            }
-                            else {
-                                stable = 0;
-                                after = cur;
-                            }
-                        }
-                        const delta = outputDelta(before, after).trim();
-                        const body = delta ? (delta.length > 1500 ? "…\n" + delta.slice(-1500) : delta) : "(已注入,暂无新输出 — 发 ? 再看)";
-                        await adapter.send(m.chatId, `🖥 ${pane}\n${body}`);
-                        return;
-                    }
+                const flowRunSource = flowSourceKey({ scope: runtimeScope }, platform, m.messageId);
+                const postAckCleanup = m.messageId === undefined
+                    ? undefined
+                    : async () => {
+                        const cleanup = await Promise.allSettled([
+                            runOutcomes.remove(m.messageId),
+                            flowRuns.removeSource(flowRunSource),
+                        ]);
+                        const failed = cleanup.find((result) => result.status === "rejected");
+                        if (failed)
+                            throw failed.reason;
+                    };
+                const messageClaim = await messageDeduper.claim(m.messageId, m.createdAtMs, {
+                    durable: m.durablyQueued === true || existingRunOutcome !== null || outcomeLoadError !== undefined,
+                });
+                if (!messageClaim) {
+                    console.error(`hara gateway: ignored a duplicate or stale ${platform} event.`);
+                    // A prior callback may have persisted the processed id and then crashed before its adapter ACK. Let the
+                    // redelivery ACK first; only its adapter-confirmed cleanup may remove any terminal execution marker.
+                    return postAckCleanup;
                 }
-                // Thread identity is (platform, chat) for DMs and (platform, chat, USER) for groups — auto-derived, so
-                // group members each get their own session thread instead of interleaving into one polluted context.
-                const who = { userId: m.userId, chatType: m.chatType };
-                const ctx = chatContext(adapter.name, m.chatId, cwd, who); // this chat's current { cwd, sessionId, agent }
-                if (ctx.rotatedFrom) {
-                    // Idle auto-rotation just happened (session hygiene): tell the user ONCE, with the escape hatch.
-                    await adapter.send(m.chatId, `🧵 fresh thread (chat was idle) — /resume ${ctx.rotatedFrom.slice(-18)} continues the previous one`);
+                if (ac.signal.aborted) {
+                    await messageClaim.release();
+                    return;
                 }
-                const cmd = parseCommand(m.text);
-                if (cmd) {
-                    if (cmd.cmd === "help")
-                        return adapter.send(m.chatId, "commands:\n/pwd · /cd <dir> — project\n/sessions · /new · /resume <id> — threads\n/agent <name|project:name|main> — who answers this thread (default: main)\n/voice · /say <text> — speech · /send <path> — send a file\n/detach — stop injecting replies into bound tmux panes\n/help\nanything else = run hara here");
-                    if (cmd.cmd === "agent") {
-                        // Per-thread agent switch, resolved via the GLOBAL index: an agent with a home also /cd's the thread
-                        // there (its data + AGENTS.md context — correctness over chat continuity; /agent main switches back,
-                        // and the previous thread is preserved per (chat, cwd), so nothing is lost).
-                        if (!cmd.arg)
-                            return adapter.send(m.chatId, `🤖 current agent: ${ctx.agent ?? "main"}\nusage: /agent <name|project:name> · /agent main`);
-                        if (cmd.arg === "main" || cmd.arg === "off") {
-                            setChatAgent(adapter.name, m.chatId, undefined, who);
-                            const restored = chatContext(adapter.name, m.chatId, cwd, who);
-                            return adapter.send(m.chatId, `🤖 back to the main agent.\n📂 ${restored.cwd}`);
-                        }
-                        const { resolveAgent } = await import("../org/projects.js");
-                        // A bare name means the override in the thread's current project when one exists; explicit
-                        // `global:name` and `project:name` remain deterministic. This avoids making a local reviewer
-                        // ambiguous merely because several other registered projects also define one.
-                        const hit = resolveAgent(cmd.arg, ctx.cwd);
-                        if (!hit)
-                            return adapter.send(m.chatId, `✗ no agent '${cmd.arg}' — see \`hara agents\` on the host.`);
-                        if ("ambiguous" in hit)
-                            return adapter.send(m.chatId, `'${cmd.arg}' exists in several projects — pick one:\n${hit.ambiguous.map((e) => `${e.project}:${e.name}`).join("\n")}`);
-                        const agentRef = hit.project ? `${hit.project}:${hit.name}` : `global:${hit.name}`;
-                        setChatAgent(adapter.name, m.chatId, agentRef, who, hit.home || undefined);
-                        return adapter.send(m.chatId, `🤖 this thread now talks to ${agentRef}${hit.home ? `\n📂 ${hit.home}` : ""}\n/agent main switches back`);
-                    }
-                    if (cmd.cmd === "detach") {
-                        const { unbindBinds } = await import("./tmux-routes.js");
-                        const n = unbindBinds();
-                        return adapter.send(m.chatId, n ? `🔓 detached ${n} bound tmux pane(s) — replies go to hara again.` : "(no tmux panes were bound)");
-                    }
-                    if (cmd.cmd === "pwd")
-                        return adapter.send(m.chatId, `📂 ${ctx.cwd}\n🧵 ${ctx.sessionId.slice(-18)}`);
-                    if (cmd.cmd === "cd" || cmd.cmd === "project") {
-                        if (ctx.agent && !ctx.agent.startsWith("global:")) {
-                            return adapter.send(m.chatId, `🤖 ${ctx.agent} is pinned to its home. Use /agent main before changing project.`);
-                        }
-                        if (!cmd.arg)
-                            return adapter.send(m.chatId, `📂 ${ctx.cwd}\nusage: /cd <dir> (absolute, ~, or relative to here)`);
-                        const target = resolve(ctx.cwd, cmd.arg.replace(/^~(?=\/|$)/, homedir()));
-                        if (!existsSync(target) || !statSync(target).isDirectory())
-                            return adapter.send(m.chatId, `✗ not a directory: ${target}`);
-                        const sid = chatCd(adapter.name, m.chatId, target, who);
-                        return adapter.send(m.chatId, `📂 now in ${target}\n🧵 ${sid.slice(-18)} · /sessions lists this dir's threads`);
-                    }
-                    if (cmd.cmd === "new")
-                        return adapter.send(m.chatId, `✨ new thread: ${newChatSession(adapter.name, m.chatId, cwd, who).slice(-18)}`);
-                    if (cmd.cmd === "sessions") {
-                        const list = listSessions(ctx.cwd).filter((session) => ownsChatSession(adapter.name, m.chatId, session.id, who)).slice(0, 10).map((x) => `${x.id.slice(-18)}  ${x.title || "(untitled)"}`).join("\n");
-                        return adapter.send(m.chatId, `📂 ${ctx.cwd}\n${list || "(no threads in this dir yet)"}`);
-                    }
-                    if (cmd.cmd === "resume") {
-                        const match = resolveOwnedSessionId(adapter.name, m.chatId, cmd.arg, listSessions().map((session) => session.id), who);
-                        if (!match)
-                            return adapter.send(m.chatId, `no session '${cmd.arg}' in this chat thread`);
-                        if ("ambiguous" in match)
-                            return adapter.send(m.chatId, `ambiguous session '${cmd.arg}' — use more characters`);
-                        const id = match.id;
-                        const target = loadSession(id)?.meta.cwd || ctx.cwd; // follow the session's own dir so it runs in the right place
-                        setChatSession(adapter.name, m.chatId, id, target, who);
-                        return adapter.send(m.chatId, `↩ resumed ${id.slice(-18)}\n📂 ${target}`);
-                    }
-                    if (cmd.cmd === "voice") {
-                        if (!adapter.sendFile)
-                            return adapter.send(m.chatId, "this platform can't send voice yet.");
-                        const on = toggleVoice(adapter.name, m.chatId, who);
-                        return adapter.send(m.chatId, on ? "🔊 voice replies ON — I'll speak each reply too." : "🔇 voice replies OFF.");
-                    }
-                    if (cmd.cmd === "say") {
-                        if (!adapter.sendFile)
-                            return adapter.send(m.chatId, "this platform can't send voice yet.");
-                        if (!cmd.arg)
-                            return adapter.send(m.chatId, "usage: /say <text to speak>");
-                        const audio = await synthesize(cmd.arg);
-                        if (!audio)
-                            return adapter.send(m.chatId, "✗ TTS failed (check HARA_TTS_* config).");
-                        try {
-                            await deliverVerifiedLocalFile(adapter, m.chatId, audio);
-                        }
-                        finally {
-                            rmSync(audio, { force: true });
-                        }
+                const messageEffectKey = (stage, index = 0) => m.messageId
+                    ? createHash("sha256")
+                        .update("hara-gateway-effect-v1\0")
+                        .update(runtimeScope)
+                        .update("\0")
+                        .update(m.messageId)
+                        .update("\0")
+                        .update(stage)
+                        .update("\0")
+                        .update(String(index))
+                        .digest("hex")
+                    : undefined;
+                const runMessageEffect = async (stage, index, effect) => {
+                    const key = messageEffectKey(stage, index);
+                    if (!key)
+                        return effect();
+                    const claim = await flowEffectReceipts.claim(key);
+                    if (!claim)
                         return;
+                    try {
+                        await effect(key);
+                        await claim.complete();
                     }
-                    if (cmd.cmd === "send") {
-                        if (!adapter.sendFile)
-                            return adapter.send(m.chatId, "this platform can't send files yet.");
-                        const p = cmd.arg ? resolve(ctx.cwd, cmd.arg.replace(/^~(?=\/|$)/, homedir())) : "";
-                        if (!p)
-                            return adapter.send(m.chatId, "usage: /send <path> (abs, ~, or relative to current dir)");
+                    catch (error) {
                         try {
-                            await deliverVerifiedLocalFile(adapter, m.chatId, p);
-                        }
-                        catch (error) {
-                            return adapter.send(m.chatId, `✗ couldn't send ${p}: ${error instanceof Error ? error.message : String(error)}`);
+                            await claim.release();
                         }
-                        return;
+                        catch { /* retain the original delivery error */ }
+                        throw error;
                     }
-                    // any other slash word → treat as a normal task
-                }
-                // Transient progress marker — capability-driven: sent ONLY where it can be recalled afterwards (Feishu),
-                // so it never leaves residue. Platforms without recall (WeChat iLink: send response is `{}`, no message
-                // id exists to revoke) get no marker at all — a clean thread beats a permanent "working…" bubble.
-                let workingId;
-                if (adapter.sendTracked && adapter.recall)
-                    workingId = await adapter.sendTracked(m.chatId, "⟳ working…").catch(() => undefined);
-                let result;
-                try {
-                    result = await sessionRuns.run(ctx.sessionId, () => runHara(m.text, ctx.sessionId, ctx.cwd, adapter.name, m.images, ctx.agent, { signal: ac.signal }));
-                }
-                catch (e) {
-                    if (e instanceof GatewayQueueFullError) {
-                        const message = e.scope === "session"
-                            ? "⏳ this thread is busy — wait for an earlier message to finish, then retry."
-                            : "⏳ the gateway is at capacity — try again shortly.";
-                        await adapter.send(m.chatId, message);
-                        return;
-                    }
-                    if (e instanceof GatewayQueueClosedError || ac.signal.aborted) {
-                        return;
-                    }
-                    throw e;
-                }
-                finally {
-                    if (workingId && adapter.recall)
-                        await adapter.recall(m.chatId, workingId).catch(() => { });
-                }
-                const { reply, files } = result;
+                };
+                let preparedResult;
                 try {
-                    if (ac.signal.aborted)
-                        return;
-                    const hasReply = Boolean(reply);
-                    if (hasReply)
-                        await adapter.send(m.chatId, plainChat(reply)); // chat bubbles are plain text — flatten markdown
-                    else if (files.length)
-                        await adapter.send(m.chatId, "📎");
-                    // Deliver only immutable private snapshots produced by send_file.
-                    for (const f of files) {
-                        if (!adapter.sendFile) {
-                            await adapter.send(m.chatId, "(this platform can't send files yet)");
-                            break;
+                    await (async () => {
+                        if (outcomeLoadError)
+                            throw outcomeLoadError;
+                        // Flows (opt-in, ~/.hara/flows.json): rules that intercept a matching inbound message → agent task + deliver,
+                        // BEFORE the allowlist/DM-driver logic. A matched flow is authorized by its own presence in the user's config
+                        // (group senders won't be in the allowlist), so this must run first. dispatchFlows settles every claimed
+                        // run/delivery before returning, keeping the inbound tracker and persistent message claim truthful.
+                        const flowRan = existingRunOutcome ? false : await dispatchFlows(m, platform, (prompt, home, schema, signal) => runFlowAgent(prompt, home ?? cwd, schema, signal), // stateless per trigger; rule cwd = agent's home
+                        (text, idempotencyKey) => adapter.send(m.chatId, plainChat(text), ac.signal, idempotencyKey), 
+                        // Flow replies are chat bubbles too — flatten markdown; an opaque effect key lets Feishu deduplicate
+                        // an externally-successful request whose local response/receipt was interrupted.
+                        approvalOwner, ac.signal, { scope: runtimeScope, receipts: flowEffectReceipts, runs: flowRuns });
+                        if (flowRan)
+                            return;
+                        // The gateway's default is a DM driver. Unknown channel shapes fail closed too: older/third-party adapters
+                        // may omit chatType, and treating every unknown room as a DM would expose the full coding agent in groups.
+                        // The chatId===userId invariant preserves legacy Telegram/Weixin-style DMs until their adapter is upgraded.
+                        if (!isPrivateApprovalMessage(m))
+                            return;
+                        if (!isAllowed(m.userId, allowlist)) {
+                            console.error(`hara gateway: ✗ message from ${m.userId} — not in allowlist. Add it to HARA_GATEWAY_ALLOWED to authorize.`);
+                            await sendMessage(m.chatId, "⛔ not authorized.");
+                            return;
                         }
+                        // One credential/chat/user admission covers context lookup, routing, stateful commands, coding, and
+                        // delivery. Context is therefore read only after earlier messages settle; /new or /voice cannot slip
+                        // between a tmux preflight and a second coding enqueue because there is no second enqueue.
+                        const admissionKey = gatewayAdmissionKey(runtimeScope, m);
                         try {
-                            await adapter.sendFile(m.chatId, f);
+                            await sessionRuns.run(admissionKey, async () => {
+                                // Owner approving a pending flow action ("采用" / "改:…" / "取消")? Execute it (e.g. post the drafted reply
+                                // back to the origin group) instead of routing this as a fresh command. This is the flow approve→execute loop.
+                                if (!existingRunOutcome && approvalUserId && String(m.userId) === approvalUserId && isPrivateApprovalMessage(m)) {
+                                    const pendingReply = await handleOwnerReply(approvalOwner, m.text, { signal: ac.signal });
+                                    if (pendingReply) {
+                                        await sendMessage(m.chatId, pendingReply);
+                                        return;
+                                    }
+                                }
+                                // Context is resolved inside this message's one FIFO admission, after all earlier chat work has settled.
+                                const who = { userId: m.userId, chatType: m.chatType };
+                                const ctx = chatContext(adapter.name, m.chatId, cwd, who);
+                                const runSerializedSideEffect = (effect) => executeDurableGatewayEffect(runOutcomes, m.messageId, effect, ac.signal);
+                                // If a tmux session opted in (via `hara remote ask/bind`), this reply is its input → inject it into that
+                                // pane, let it react, and reply with the session's NEW output (on-inbound relay — quiet + iLink-friendly:
+                                // one reply per message, no continuous push). Owner-gated by the allowlist check above.
+                                if (!existingRunOutcome && !parseCommand(m.text)) {
+                                    preparedResult = await (async () => {
+                                        // pickPaneForReply consumes a one-shot route, so even that lookup must happen after the durable
+                                        // marker. If a process dies after route consumption, redelivery warns instead of injecting elsewhere.
+                                        const prior = await runOutcomes.start(m.messageId);
+                                        if (prior) {
+                                            const recovered = resultFromRunOutcome(prior);
+                                            if (prior.status !== "complete")
+                                                await finishRunOutcome(runOutcomes, m.messageId, recovered);
+                                            return recovered;
+                                        }
+                                        if (ac.signal.aborted)
+                                            throw ac.signal.reason instanceof Error ? ac.signal.reason : new Error("gateway effect cancelled");
+                                        const pane = pickPaneForReply();
+                                        if (!pane) {
+                                            // No irreversible route existed. Remove this preflight marker before falling through to coding.
+                                            await runOutcomes.remove(m.messageId);
+                                            return undefined;
+                                        }
+                                        console.error(`hara gateway: routed reply → tmux pane ${pane}`);
+                                        const before = capturePane(pane) ?? "";
+                                        injectTmux(pane, m.text);
+                                        // wait for the session's output to SETTLE (poll every 800ms; stable for ~1.6s → done; cap ~10s) so a
+                                        // slow response isn't missed and we don't capture mid-stream.
+                                        let after = "";
+                                        let stable = 0;
+                                        for (let i = 0; i < 12; i++) {
+                                            await new Promise((r) => setTimeout(r, 800));
+                                            const cur = capturePane(pane) ?? "";
+                                            if (cur === after) {
+                                                if (++stable >= 2)
+                                                    break;
+                                            }
+                                            else {
+                                                stable = 0;
+                                                after = cur;
+                                            }
+                                        }
+                                        const delta = outputDelta(before, after).trim();
+                                        const body = delta ? (delta.length > 1500 ? "…\n" + delta.slice(-1500) : delta) : "(已注入,暂无新输出 — 发 ? 再看)";
+                                        const completed = { reply: `🖥 ${pane}\n${body}`, files: [] };
+                                        if (ac.signal.aborted)
+                                            throw ac.signal.reason instanceof Error ? ac.signal.reason : new Error("gateway effect cancelled");
+                                        await finishRunOutcome(runOutcomes, m.messageId, completed);
+                                        return completed;
+                                    })();
+                                }
+                                // Thread identity is (platform, chat) for DMs and (platform, chat, USER) for groups — auto-derived, so
+                                // group members each get their own session thread instead of interleaving into one polluted context.
+                                if (!existingRunOutcome && !preparedResult && ctx.rotatedFrom) {
+                                    // Idle auto-rotation just happened (session hygiene): tell the user ONCE, with the escape hatch.
+                                    await sendMessage(m.chatId, `🧵 fresh thread (chat was idle) — /resume ${ctx.rotatedFrom.slice(-18)} continues the previous one`);
+                                }
+                                const cmd = existingRunOutcome || preparedResult ? null : parseCommand(m.text);
+                                if (cmd) {
+                                    if (cmd.cmd === "help")
+                                        return sendMessage(m.chatId, "commands:\n/pwd · /cd <dir> — project\n/sessions · /new · /resume <id> — threads\n/agent <name|project:name|main> — who answers this thread (default: main)\n/voice · /say <text> — speech · /send <path> — send a file\n/detach — stop injecting replies into bound tmux panes\n/help\nanything else = run hara here");
+                                    if (cmd.cmd === "agent") {
+                                        // Per-thread agent switch, resolved via the GLOBAL index: an agent with a home also /cd's the thread
+                                        // there (its data + AGENTS.md context — correctness over chat continuity; /agent main switches back,
+                                        // and the previous thread is preserved per (chat, cwd), so nothing is lost).
+                                        if (!cmd.arg)
+                                            return sendMessage(m.chatId, `🤖 current agent: ${ctx.agent ?? "main"}\nusage: /agent <name|project:name> · /agent main`);
+                                        if (cmd.arg === "main" || cmd.arg === "off") {
+                                            setChatAgent(adapter.name, m.chatId, undefined, who);
+                                            const restored = chatContext(adapter.name, m.chatId, cwd, who);
+                                            return sendMessage(m.chatId, `🤖 back to the main agent.\n📂 ${restored.cwd}`);
+                                        }
+                                        const { resolveAgent } = await import("../org/projects.js");
+                                        // A bare name means the override in the thread's current project when one exists; explicit
+                                        // `global:name` and `project:name` remain deterministic. This avoids making a local reviewer
+                                        // ambiguous merely because several other registered projects also define one.
+                                        const hit = resolveAgent(cmd.arg, ctx.cwd);
+                                        if (!hit)
+                                            return sendMessage(m.chatId, `✗ no agent '${cmd.arg}' — see \`hara agents\` on the host.`);
+                                        if ("ambiguous" in hit)
+                                            return sendMessage(m.chatId, `'${cmd.arg}' exists in several projects — pick one:\n${hit.ambiguous.map((e) => `${e.project}:${e.name}`).join("\n")}`);
+                                        const agentRef = hit.project ? `${hit.project}:${hit.name}` : `global:${hit.name}`;
+                                        setChatAgent(adapter.name, m.chatId, agentRef, who, hit.home || undefined);
+                                        return sendMessage(m.chatId, `🤖 this thread now talks to ${agentRef}${hit.home ? `\n📂 ${hit.home}` : ""}\n/agent main switches back`);
+                                    }
+                                    if (cmd.cmd === "detach") {
+                                        const { unbindBinds } = await import("./tmux-routes.js");
+                                        const n = unbindBinds();
+                                        return sendMessage(m.chatId, n ? `🔓 detached ${n} bound tmux pane(s) — replies go to hara again.` : "(no tmux panes were bound)");
+                                    }
+                                    if (cmd.cmd === "pwd")
+                                        return sendMessage(m.chatId, `📂 ${ctx.cwd}\n🧵 ${ctx.sessionId.slice(-18)}`);
+                                    if (cmd.cmd === "cd" || cmd.cmd === "project") {
+                                        if (ctx.agent && !ctx.agent.startsWith("global:")) {
+                                            return sendMessage(m.chatId, `🤖 ${ctx.agent} is pinned to its home. Use /agent main before changing project.`);
+                                        }
+                                        if (!cmd.arg)
+                                            return sendMessage(m.chatId, `📂 ${ctx.cwd}\nusage: /cd <dir> (absolute, ~, or relative to here)`);
+                                        const target = resolve(ctx.cwd, cmd.arg.replace(/^~(?=\/|$)/, homedir()));
+                                        if (!existsSync(target) || !statSync(target).isDirectory())
+                                            return sendMessage(m.chatId, `✗ not a directory: ${target}`);
+                                        const sid = chatCd(adapter.name, m.chatId, target, who);
+                                        return sendMessage(m.chatId, `📂 now in ${target}\n🧵 ${sid.slice(-18)} · /sessions lists this dir's threads`);
+                                    }
+                                    if (cmd.cmd === "new") {
+                                        preparedResult = await runSerializedSideEffect(async () => ({
+                                            reply: `✨ new thread: ${newChatSession(adapter.name, m.chatId, cwd, who).slice(-18)}`,
+                                            files: [],
+                                        }));
+                                    }
+                                    if (cmd.cmd === "sessions") {
+                                        const list = listSessions(ctx.cwd).filter((session) => ownsChatSession(adapter.name, m.chatId, session.id, who)).slice(0, 10).map((x) => `${x.id.slice(-18)}  ${x.title || "(untitled)"}`).join("\n");
+                                        return sendMessage(m.chatId, `📂 ${ctx.cwd}\n${list || "(no threads in this dir yet)"}`);
+                                    }
+                                    if (cmd.cmd === "resume") {
+                                        const match = resolveOwnedSessionId(adapter.name, m.chatId, cmd.arg, listSessions().map((session) => session.id), who);
+                                        if (!match)
+                                            return sendMessage(m.chatId, `no session '${cmd.arg}' in this chat thread`);
+                                        if ("ambiguous" in match)
+                                            return sendMessage(m.chatId, `ambiguous session '${cmd.arg}' — use more characters`);
+                                        const id = match.id;
+                                        const target = loadSession(id)?.meta.cwd || ctx.cwd; // follow the session's own dir so it runs in the right place
+                                        setChatSession(adapter.name, m.chatId, id, target, who);
+                                        return sendMessage(m.chatId, `↩ resumed ${id.slice(-18)}\n📂 ${target}`);
+                                    }
+                                    if (cmd.cmd === "voice") {
+                                        if (!adapter.sendFile)
+                                            return sendMessage(m.chatId, "this platform can't send voice yet.");
+                                        preparedResult = await runSerializedSideEffect(async () => {
+                                            // Read the state inside the serialized action, derive one target, and persist that exact target.
+                                            // A redelivery loads the completed outcome and never invokes toggleVoice a second time.
+                                            const targetOn = !chatContext(adapter.name, m.chatId, cwd, who).voice;
+                                            const actual = toggleVoice(adapter.name, m.chatId, who);
+                                            if (actual !== targetOn)
+                                                throw new Error("voice preference changed concurrently; refusing to toggle twice");
+                                            return {
+                                                reply: targetOn ? "🔊 voice replies ON — I'll speak each reply too." : "🔇 voice replies OFF.",
+                                                files: [],
+                                            };
+                                        });
+                                    }
+                                    if (cmd.cmd === "say") {
+                                        if (!adapter.sendFile)
+                                            return sendMessage(m.chatId, "this platform can't send voice yet.");
+                                        if (!cmd.arg)
+                                            return sendMessage(m.chatId, "usage: /say <text to speak>");
+                                        preparedResult = await runSerializedSideEffect(async () => {
+                                            const audio = await synthesize(cmd.arg, ac.signal);
+                                            if (!audio)
+                                                return { reply: "✗ TTS failed (check HARA_TTS_* config).", files: [] };
+                                            try {
+                                                return { reply: "", files: [await snapshotVerifiedLocalFile(audio)] };
+                                            }
+                                            finally {
+                                                rmSync(audio, { force: true });
+                                            }
+                                        });
+                                    }
+                                    if (cmd.cmd === "send") {
+                                        if (!adapter.sendFile)
+                                            return sendMessage(m.chatId, "this platform can't send files yet.");
+                                        const p = cmd.arg ? resolve(ctx.cwd, cmd.arg.replace(/^~(?=\/|$)/, homedir())) : "";
+                                        if (!p)
+                                            return sendMessage(m.chatId, "usage: /send <path> (abs, ~, or relative to current dir)");
+                                        preparedResult = await runSerializedSideEffect(async () => {
+                                            try {
+                                                return { reply: "", files: [await snapshotVerifiedLocalFile(p)] };
+                                            }
+                                            catch (error) {
+                                                return { reply: `✗ couldn't send ${p}: ${error instanceof Error ? error.message : String(error)}`, files: [] };
+                                            }
+                                        });
+                                    }
+                                    // any other slash word → treat as a normal task
+                                }
+                                // Transient progress marker — capability-driven: sent ONLY where it can be recalled afterwards (Feishu),
+                                // so it never leaves residue. Platforms without recall (WeChat iLink: send response is `{}`, no message
+                                // id exists to revoke) get no marker at all — a clean thread beats a permanent "working…" bubble.
+                                let workingId;
+                                if (!preparedResult && !existingRunOutcome && adapter.sendTracked && adapter.recall) {
+                                    workingId = await adapter.sendTracked(m.chatId, "⟳ working…", ac.signal).catch(() => undefined);
+                                }
+                                let result;
+                                try {
+                                    if (preparedResult) {
+                                        result = preparedResult;
+                                    }
+                                    else {
+                                        const cached = existingRunOutcome ?? await runOutcomes.load(m.messageId);
+                                        if (cached) {
+                                            console.error(cached.status === "complete"
+                                                ? "hara gateway: resuming delivery from a completed outcome; local side effects are not repeated."
+                                                : cached.status === "terminal"
+                                                    ? "hara gateway: terminal outcome payload was reclaimed; notifying the user without repeating local side effects."
+                                                    : "hara gateway: ALERT an interrupted operation was recovered; local side effects were not repeated automatically.");
+                                            result = await executeDurableGatewayEffect(runOutcomes, m.messageId, async () => { throw new Error("cached gateway outcome disappeared during recovery"); }, ac.signal);
+                                        }
+                                        else {
+                                            // The outer chat admission is the only queue. Starting the tombstone and running the agent here
+                                            // prevents a later /new, /voice, or coding message from slipping between routing and execution.
+                                            result = await executeDurableGatewayEffect(runOutcomes, m.messageId, async () => {
+                                                const completed = await runHara(m.text, ctx.sessionId, ctx.cwd, adapter.name, m.images, ctx.agent, { signal: ac.signal });
+                                                if (!completed.reply || !ctx.voice || !adapter.sendFile)
+                                                    return completed;
+                                                const audio = await synthesize(completed.reply, ac.signal);
+                                                if (!audio)
+                                                    return completed;
+                                                try {
+                                                    return { ...completed, voice: await snapshotVerifiedLocalFile(audio) };
+                                                }
+                                                finally {
+                                                    rmSync(audio, { force: true });
+                                                }
+                                            }, ac.signal);
+                                        }
+                                    }
+                                }
+                                catch (e) {
+                                    if (e instanceof GatewayQueueClosedError || ac.signal.aborted) {
+                                        return;
+                                    }
+                                    throw e;
+                                }
+                                finally {
+                                    if (workingId && adapter.recall)
+                                        await adapter.recall(m.chatId, workingId, ac.signal).catch(() => { });
+                                }
+                                const { reply, files, voice } = result;
+                                try {
+                                    if (ac.signal.aborted)
+                                        return;
+                                    const hasReply = Boolean(reply);
+                                    const deliveryCommand = parseCommand(m.text)?.cmd;
+                                    const directFileCommand = deliveryCommand === "say" || deliveryCommand === "send";
+                                    if (hasReply) {
+                                        await runMessageEffect("reply", 0, (key) => sendMessage(m.chatId, plainChat(reply), key));
+                                    }
+                                    else if (files.length && !directFileCommand) {
+                                        await runMessageEffect("attachment-marker", 0, (key) => sendMessage(m.chatId, "📎", key));
+                                    }
+                                    // Deliver only immutable private snapshots produced by send_file.
+                                    for (const [fileIndex, f] of files.entries()) {
+                                        if (!adapter.sendFile) {
+                                            await sendMessage(m.chatId, "(this platform can't send files yet)");
+                                            break;
+                                        }
+                                        try {
+                                            await runMessageEffect("attachment", fileIndex, (key) => adapter.sendFile(m.chatId, f, ac.signal, key));
+                                        }
+                                        catch (e) {
+                                            const deliveryError = e instanceof Error ? e : new Error(String(e));
+                                            await runMessageEffect("attachment-error", fileIndex, (key) => sendMessage(m.chatId, `✗ couldn't send attachment: ${deliveryError.message}`, key));
+                                            // The durable outcome and per-attachment receipt let platform redelivery retry only this unfinished
+                                            // transport. Never ACK a failed upload and force the user to rerun the side-effect command.
+                                            throw deliveryError;
+                                        }
+                                    }
+                                    if (voice && adapter.sendFile) {
+                                        // `voice` is part of the durable run outcome. If this upload fails, platform redelivery observes the
+                                        // completed outcome and retries only this receipt/transport with the identical audio bytes.
+                                        await runMessageEffect("voice", 0, (key) => adapter.sendFile(m.chatId, voice, ac.signal, key));
+                                    }
+                                }
+                                finally {
+                                    // Text-send failures, shutdown races, unsupported adapters, and upload failures all remove snapshots.
+                                    for (const f of files)
+                                        if (f.snapshotPath)
+                                            cleanupOutboundSnapshot(f.snapshotPath);
+                                    if (voice?.snapshotPath)
+                                        cleanupOutboundSnapshot(voice.snapshotPath);
+                                }
+                            });
                         }
-                        catch (e) {
-                            await adapter.send(m.chatId, `✗ couldn't send attachment: ${e.message}`);
-                        }
-                    }
-                    if (hasReply && ctx.voice && adapter.sendFile) {
-                        const audio = await synthesize(reply);
-                        if (audio) {
-                            try {
-                                await deliverVerifiedLocalFile(adapter, m.chatId, audio);
-                            }
-                            finally {
-                                rmSync(audio, { force: true });
-                            }
+                        catch (error) {
+                            if (!(error instanceof GatewayQueueFullError))
+                                throw error;
+                            const message = error.scope === "session"
+                                ? "⏳ this chat is busy — wait for earlier messages to finish, then retry."
+                                : "⏳ the gateway is at capacity — try again shortly.";
+                            await sendMessage(m.chatId, message);
+                            return;
                         }
+                    })();
+                    if (ac.signal.aborted)
+                        await messageClaim.release();
+                    else {
+                        await messageClaim.complete();
+                        // Telegram invokes this only after a subsequent offset-bearing poll succeeds; Feishu invokes it only
+                        // after durable spool deletion. A crash between handler completion and platform ACK therefore leaves
+                        // the terminal marker intact and can never turn a redelivery into another coding/tool execution.
+                        return postAckCleanup;
                     }
                 }
-                finally {
-                    // Text-send failures, shutdown races, unsupported adapters, and upload failures all remove snapshots.
-                    for (const f of files)
-                        cleanupOutboundSnapshot(f.snapshotPath);
+                catch (error) {
+                    if (ac.signal.aborted) {
+                        await messageClaim.release(); // shutdown is not a poison-message failure
+                        throw error;
+                    }
+                    const exhausted = await messageClaim.fail();
+                    if (!exhausted)
+                        throw error;
+                    // Third real failure is dead-lettered by the deduper. Resolve normally so Telegram advances its offset
+                    // and a durable Feishu spool can remove the item instead of rerunning full-auto coding forever.
+                    return postAckCleanup;
                 }
             }
             finally {
@@ -873,14 +1174,21 @@ export async function runGateway(opts) {
                     console.error(`hara gateway: inbound media cleanup failed — ${error instanceof Error ? error.message : String(error)}`);
                 });
             }
-        }, ac.signal, (m) => shouldDownloadInboundMedia(m, allowlist));
+        })()), ac.signal, (m) => shouldDownloadInboundMedia(m, allowlist));
     }
     finally {
         stop();
         closeQueue();
         await sessionRuns.waitForIdle();
+        const handlersDrained = await inboundHandlers.drain();
         ac.signal.removeEventListener("abort", closeQueue);
         process.off("SIGINT", stop);
         process.off("SIGTERM", stop);
+        if (handlersDrained)
+            releaseInstance();
+        else {
+            console.error("hara gateway: shutdown timed out with inbound work still active; instance lease retained until callbacks finish.");
+            void inboundHandlers.waitForIdle().then(() => releaseInstance(), (error) => console.error(`hara gateway: could not release the deferred instance lease — ${error instanceof Error ? error.message : String(error)}`));
+        }
     }
 }