@sleep2agi/commhub-server 0.9.0-preview.60 → 0.9.0-preview.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.60",
+  "version": "0.9.0-preview.61",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/inbox-count-sse.test.ts

@@ -302,7 +302,7 @@ describe("#1440 broadcast delivery set", () => {
     expect(res.message_ids).toHaveLength(3);
     // #1440 ③ — `recipients` counted candidates, not deliveries, so it
     // disagreed with the documented invariant
-    // ("message_ids.length === recipients", docs-site/docs/api/rest.md)
+    // ("message_ids.length === recipients", docs-site/docs/api/rest-data.md)
     // exactly when a node was skipped. 4 sessions, 3 delivered.
     expect(res.recipients).toBe(res.message_ids.length);
     expect(res.recipients).toBe(3);

package/src/send-dedup-request-id.test.ts

@@ -0,0 +1,229 @@
+// Handler-level regression for the #212 dedup window swallowing human chat
+// messages (see send_dedup.ts header, "Key selection").
+//
+// Before the fix, POST /api/task keyed the dedup window on
+// (from, to, sha256(content)) only and ignored meta.client_request_id, so a
+// user sending the same short text twice within 5 minutes got 200/429/429 and
+// ONE stored row — and the app maps that 429 to "delivered". The table below
+// is the repro, run against both transports:
+//
+//   case                              | before (REST) | after
+//   ----------------------------------+---------------+-------------------------
+//   same text, 3 different ids        | 1 row         | 3 rows, 3 x ok
+//   same text, same id (retry)        | 1 row         | 1 row, 2 x replay (same id)
+//   different text, same id           | 3 rows        | 1 row, 2 x idempotency_conflict
+//   same text, no id (#212 agents)    | 1 row         | 1 row, 2 x duplicate_send
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { register } from "./auth.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { sharedSendDedup } from "./send_dedup.js";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-send-dedup-rid-"));
+const TARGET = `dedup-rid-target-${process.pid}`;
+const TARGET_NODE_ID = `node_dedup_rid_${process.pid}`;
+
+let server: any;
+let base = "";
+let userToken = "";
+let restNet = "";
+let restUser = "";
+
+const MCP_NET = `net_dedup_rid_${process.pid}`;
+const MCP_USER = `user_dedup_rid_${process.pid}`;
+
+function rid(n: number): string {
+  // App shape: dreq_ + 32 lowercase hex.
+  return `dreq_${n.toString(16).padStart(32, "0")}`;
+}
+
+function seedTarget(networkId: string, suffix: string) {
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+     VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))`,
+    [`resume_${TARGET_NODE_ID}_${suffix}`, TARGET, `${TARGET_NODE_ID}_${suffix}`, networkId],
+  );
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?2, ?3, datetime('now'), datetime('now'), 'active')`,
+    [`${TARGET_NODE_ID}_${suffix}`, TARGET, networkId],
+  );
+}
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB = process.env.COMMHUB_DB || join(PRIVATE_DB_DIR, "hub.db");
+  restUser = `dedup_rid_${Date.now()}`;
+  const registered = register(restUser, "DedupRid123!", undefined, "seed");
+  expect(registered.ok).toBe(true);
+  userToken = registered.token!;
+  restNet = registered.network_id!;
+  seedTarget(restNet, "rest");
+
+  db.run("INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?1, 'x', 'user', datetime('now'))", [MCP_USER]);
+  db.run("INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))", [MCP_NET, MCP_USER]);
+  db.run("INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))", [MCP_USER, MCP_NET]);
+  seedTarget(MCP_NET, "mcp");
+
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+beforeEach(() => {
+  for (const net of [restNet, MCP_NET]) {
+    if (!net) continue;
+    for (const table of ["tasks", "inbox", "task_events"]) {
+      try { db.run(`DELETE FROM ${table} WHERE network_id = ?1`, [net]); } catch {}
+    }
+  }
+  sharedSendDedup.clear();
+});
+
+function rowCount(networkId: string): number {
+  return db.get<{ n: number }>("SELECT COUNT(*) AS n FROM tasks WHERE network_id = ?1", [networkId])!.n;
+}
+function inboxCount(networkId: string): number {
+  return db.get<{ n: number }>("SELECT COUNT(*) AS n FROM inbox WHERE network_id = ?1", [networkId])!.n;
+}
+
+// ── REST ────────────────────────────────────────────────────────────────
+
+async function rest(task: string, requestId?: string): Promise<{ status: number; body: any }> {
+  const res = await fetch(`${base}/api/task`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${userToken}`, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      alias: TARGET,
+      task,
+      priority: "normal",
+      network_id: restNet,
+      from: restUser,
+      meta: requestId
+        ? { source: "dashboard-chat", client_request_id: requestId }
+        : { source: "dashboard-chat" },
+    }),
+  });
+  return { status: res.status, body: await res.json() };
+}
+
+describe("POST /api/task dedup key selection", () => {
+  test("same text with 3 different request ids -> 3 rows (the reported data loss)", async () => {
+    const results = [await rest("好", rid(1)), await rest("好", rid(2)), await rest("好", rid(3))];
+    expect(results.map((r) => r.status)).toEqual([200, 200, 200]);
+    const ids = results.map((r) => r.body.task_id);
+    expect(new Set(ids).size).toBe(3);
+    expect(rowCount(restNet)).toBe(3);
+    expect(inboxCount(restNet)).toBe(3);
+  });
+
+  test("same text with the same request id -> 1 row, retries replay the same task id", async () => {
+    const first = await rest("好", rid(7));
+    const second = await rest("好", rid(7));
+    const third = await rest("好", rid(7));
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(third.status).toBe(200);
+    expect(second.body).toMatchObject({ ok: true, task_id: first.body.task_id, message_id: first.body.task_id, idempotent_replay: true });
+    expect(third.body.task_id).toBe(first.body.task_id);
+    expect(rowCount(restNet)).toBe(1);
+    expect(inboxCount(restNet)).toBe(1);
+  });
+
+  test("different text with the same request id -> 1 row, reuse fails closed (409)", async () => {
+    const first = await rest("第一条", rid(9));
+    const second = await rest("第二条", rid(9));
+    const third = await rest("第三条", rid(9));
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(409);
+    expect(second.body.error).toBe("idempotency_conflict");
+    expect(third.status).toBe(409);
+    expect(rowCount(restNet)).toBe(1);
+  });
+
+  test("#212 guard: same text WITHOUT a request id is still deduped (429 duplicate_send)", async () => {
+    const results = [await rest("继续"), await rest("继续"), await rest("继续")];
+    expect(results.map((r) => r.status)).toEqual([200, 429, 429]);
+    expect(results[1].body.error).toBe("duplicate_send");
+    expect(rowCount(restNet)).toBe(1);
+  });
+
+  test("no request id, different text -> each goes through", async () => {
+    const results = [await rest("a"), await rest("b"), await rest("c")];
+    expect(results.map((r) => r.status)).toEqual([200, 200, 200]);
+    expect(rowCount(restNet)).toBe(3);
+  });
+});
+
+// ── MCP send_task ──────────────────────────────────────────────────────
+
+type ToolHandler = (args: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function mcpSendTask(): ToolHandler {
+  const mcp = new McpServer({ name: "dedup-rid-test", version: "0" }) as any;
+  let handler: ToolHandler | undefined;
+  const original = mcp.tool.bind(mcp);
+  mcp.tool = (name: string, description: string, schema: any, candidate: ToolHandler) => {
+    if (name === "send_task") handler = candidate;
+    return original(name, description, schema, candidate);
+  };
+  registerTools(mcp, undefined, MCP_NET, MCP_USER, MCP_USER, false, null);
+  if (!handler) throw new Error("send_task handler missing");
+  return handler;
+}
+
+async function mcp(handler: ToolHandler, task: string, requestId?: string): Promise<any> {
+  const result = await handler({
+    alias: TARGET,
+    task,
+    priority: "normal",
+    ...(requestId ? { meta: { source: "dashboard-chat", client_request_id: requestId } } : {}),
+  });
+  return JSON.parse(result.content[0].text);
+}
+
+describe("MCP send_task dedup key selection", () => {
+  test("same text with 3 different request ids -> 3 rows", async () => {
+    const h = mcpSendTask();
+    const results = [await mcp(h, "好", rid(11)), await mcp(h, "好", rid(12)), await mcp(h, "好", rid(13))];
+    expect(results.map((r) => r.ok)).toEqual([true, true, true]);
+    expect(new Set(results.map((r) => r.message_id)).size).toBe(3);
+    expect(rowCount(MCP_NET)).toBe(3);
+  });
+
+  test("same text with the same request id -> 1 row, replay returns the same task id", async () => {
+    const h = mcpSendTask();
+    const first = await mcp(h, "好", rid(17));
+    const second = await mcp(h, "好", rid(17));
+    const third = await mcp(h, "好", rid(17));
+    expect(first.ok).toBe(true);
+    expect(second).toMatchObject({ ok: true, task_id: first.message_id, idempotent_replay: true });
+    expect(third.task_id).toBe(first.message_id);
+    expect(rowCount(MCP_NET)).toBe(1);
+  });
+
+  test("different text with the same request id -> 1 row, idempotency_conflict", async () => {
+    const h = mcpSendTask();
+    expect((await mcp(h, "第一条", rid(19))).ok).toBe(true);
+    expect((await mcp(h, "第二条", rid(19))).error).toBe("idempotency_conflict");
+    expect((await mcp(h, "第三条", rid(19))).error).toBe("idempotency_conflict");
+    expect(rowCount(MCP_NET)).toBe(1);
+  });
+
+  test("#212 guard: same text WITHOUT a request id is still deduped", async () => {
+    const h = mcpSendTask();
+    const results = [await mcp(h, "继续"), await mcp(h, "继续"), await mcp(h, "继续")];
+    expect(results[0].ok).toBe(true);
+    expect(results[1].error).toBe("duplicate_send");
+    expect(results[2].error).toBe("duplicate_send");
+    expect(rowCount(MCP_NET)).toBe(1);
+  });
+});

package/src/send_dedup.test.ts

@@ -146,6 +146,60 @@ describe("SendDedup", () => {
   });
 });
 
+describe("SendDedup key selection (client_request_id vs content)", () => {
+  const t0 = 1_700_000_000_000;
+  const A = "dreq_00000000000000000000000000000001";
+  const B = "dreq_00000000000000000000000000000002";
+
+  it("keyFor picks the request id when present, content hash otherwise", () => {
+    const withId = SendDedup.keyFor("alice", "bob", "好", { requestId: A, networkId: "net1" });
+    expect(withId.kind).toBe("request_id");
+    expect(withId.key).toBe(`rid|net1|alice|bob|${A}`);
+    const noId = SendDedup.keyFor("alice", "bob", "好", {});
+    expect(noId.kind).toBe("content");
+    expect(noId.key).toBe(SendDedup.key("alice", "bob", "好"));
+    // Empty / null ids fall back to the content key.
+    expect(SendDedup.keyFor("alice", "bob", "好", { requestId: "" }).kind).toBe("content");
+    expect(SendDedup.keyFor("alice", "bob", "好", { requestId: null }).kind).toBe("content");
+  });
+
+  it("same text with different request ids is never a duplicate", () => {
+    const d = new SendDedup({ windowMs: 300_000, maxKeys: 64 });
+    d.record("alice", "bob", "好", t0, { requestId: A });
+    expect(d.check("alice", "bob", "好", t0 + 1000, { requestId: B })).toEqual({ duplicate: false });
+  });
+
+  it("same request id is a duplicate even with different content (one id = one message)", () => {
+    const d = new SendDedup({ windowMs: 300_000, maxKeys: 64 });
+    d.record("alice", "bob", "first", t0, { requestId: A });
+    const again = d.check("alice", "bob", "second", t0 + 1000, { requestId: A });
+    expect(again.duplicate).toBe(true);
+    if (again.duplicate) expect(again.kind).toBe("request_id");
+  });
+
+  it("request-id keys are scoped by network, sender and target", () => {
+    const d = new SendDedup({ windowMs: 300_000, maxKeys: 64 });
+    d.record("alice", "bob", "x", t0, { requestId: A, networkId: "net1" });
+    expect(d.check("alice", "bob", "x", t0 + 1, { requestId: A, networkId: "net2" })).toEqual({ duplicate: false });
+    expect(d.check("carol", "bob", "x", t0 + 1, { requestId: A, networkId: "net1" })).toEqual({ duplicate: false });
+    expect(d.check("alice", "dave", "x", t0 + 1, { requestId: A, networkId: "net1" })).toEqual({ duplicate: false });
+  });
+
+  it("#212 regression guard: without an id, same content is still a duplicate and reports kind=content", () => {
+    const d = new SendDedup({ windowMs: 300_000, maxKeys: 64 });
+    d.record("agent", "peer", "same task", t0);
+    const again = d.check("agent", "peer", "same task", t0 + 1000);
+    expect(again.duplicate).toBe(true);
+    if (again.duplicate) expect(again.kind).toBe("content");
+  });
+
+  it("an id-bearing send does not shadow a later id-less send of the same text", () => {
+    const d = new SendDedup({ windowMs: 300_000, maxKeys: 64 });
+    d.record("alice", "bob", "好", t0, { requestId: A });
+    expect(d.check("alice", "bob", "好", t0 + 1000)).toEqual({ duplicate: false });
+  });
+});
+
 describe("buildDuplicateSendPayload", () => {
   it("contains the Chinese LLM-facing hint with target alias and window minutes", () => {
     const payload = buildDuplicateSendPayload({

package/src/send_dedup.ts

@@ -33,6 +33,26 @@
 //   - The structured response shape is identical between MCP and REST
 //     callers so the LLM gets the same parseable hint regardless of
 //     transport.
+//
+// Key selection (#2043, follow-up to #212): the content-hash key above is
+// only right for callers that have no other notion of "one message".
+// Human chat clients (the desktop/mobile app, the web Dashboard) mint a
+// fresh `meta.client_request_id` per message bubble and reuse it only
+// when retrying that same bubble. For those sends the content hash is the
+// WRONG identity: a user who types 「好」 twice within five minutes sent
+// two messages, and dropping the second one (while the app maps the 429
+// to "delivered") silently loses it. So:
+//   - a send WITH a valid client_request_id is keyed on
+//     (network, from, to, client_request_id) — a new id always proceeds,
+//     identical text or not; a same-id retry is answered from the durable
+//     tasks row by the handler (task-idempotency.ts) before this index is
+//     even consulted, so this key is defence in depth, not the primary
+//     replay mechanism;
+//   - a send WITHOUT one (agent / MCP / scripted traffic) keeps the #212
+//     content-hash window unchanged.
+// One id is one message: re-using an id with different content is a
+// client bug and the handlers fail it closed (`idempotency_conflict`)
+// rather than storing a second row or silently replaying the first.
 
 import { createHash } from "crypto";
 
@@ -61,9 +81,23 @@ export function readDedupConfig(env: NodeJS.ProcessEnv = process.env): DedupConf
   };
 }
 
+/** Which identity a dedup key was built from. Logged on every drop. */
+export type DedupKeyKind = "request_id" | "content";
+
+/**
+ * Optional per-send scope. When `requestId` is a non-empty string the key
+ * is the request id (scoped by network/from/to) instead of the content hash.
+ * Callers must pass the already-validated id (clientRequestIdFromMeta), not
+ * raw client input.
+ */
+export type DedupScope = {
+  requestId?: string | null;
+  networkId?: string | null;
+};
+
 export type DedupCheck =
   | { duplicate: false }
-  | { duplicate: true; lastSentMs: number; ageMs: number };
+  | { duplicate: true; lastSentMs: number; ageMs: number; kind: DedupKeyKind };
 
 export class SendDedup {
   private last = new Map<string, number>();
@@ -93,6 +127,18 @@ export class SendDedup {
     return `${from}|${to}|${hash}`;
   }
 
+  /**
+   * Pick the dedup identity for one send. A validated client request id
+   * wins over the content hash; see the header comment for why.
+   */
+  static keyFor(from: string, to: string, content: string, scope: DedupScope = {}): { key: string; kind: DedupKeyKind } {
+    const requestId = typeof scope.requestId === "string" && scope.requestId.length > 0 ? scope.requestId : null;
+    if (requestId) {
+      return { key: `rid|${scope.networkId ?? ""}|${from}|${to}|${requestId}`, kind: "request_id" };
+    }
+    return { key: SendDedup.key(from, to, content), kind: "content" };
+  }
+
   /**
    * Check whether (from, to, content) was sent recently. Returns
    * `{ duplicate: false }` when the call should proceed, or
@@ -103,10 +149,10 @@ export class SendDedup {
    * AFTER the underlying side effect (inbox insert + pushEvent) succeeds,
    * so failed sends don't accidentally block legitimate retries.
    */
-  check(from: string, to: string, content: string, nowMs: number = Date.now()): DedupCheck {
+  check(from: string, to: string, content: string, nowMs: number = Date.now(), scope: DedupScope = {}): DedupCheck {
     if (!this.enabled) return { duplicate: false };
     this.evictExpired(nowMs);
-    const k = SendDedup.key(from, to, content);
+    const { key: k, kind } = SendDedup.keyFor(from, to, content, scope);
     const lastSentMs = this.last.get(k);
     if (lastSentMs === undefined) return { duplicate: false };
     const ageMs = nowMs - lastSentMs;
@@ -114,13 +160,13 @@ export class SendDedup {
       this.last.delete(k);
       return { duplicate: false };
     }
-    return { duplicate: true, lastSentMs, ageMs };
+    return { duplicate: true, lastSentMs, ageMs, kind };
   }
 
   /** Record a successful send for future dedup checks. */
-  record(from: string, to: string, content: string, nowMs: number = Date.now()): void {
+  record(from: string, to: string, content: string, nowMs: number = Date.now(), scope: DedupScope = {}): void {
     if (!this.enabled) return;
-    const k = SendDedup.key(from, to, content);
+    const k = SendDedup.keyFor(from, to, content, scope).key;
     this.last.set(k, nowMs);
     if (this.last.size > this.cfg.maxKeys) this.evictOldest();
   }

package/src/server.ts

@@ -19,6 +19,7 @@ import { narrowTags, parseStoredTags, validateScalarAttr } from "./node-attrs-va
 import { register, login, resolveToken, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getUserNetworkRole, addNetworkMember, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
 import { abortRename, cleanupCommittedRenameSessions, commitRename, prepareRename, resolveCanonicalAlias } from "./rename.js";
 import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
+import { clientRequestIdFromMeta, idempotentTaskId, idempotentTaskMatches, type StoredIdempotentTask } from "./task-idempotency.js";
 import { getLoginClientIp, sharedLoginFailureLockout, sharedLoginIpRateLimiter } from "./auth_login_guard.js";
 import {
   FILE_ID_REGEX,
@@ -738,6 +739,16 @@ export function patrolExpiredTasks(): void {
         // in this count. The WHERE clause still targets one exact guarded
         // task, so any positive count proves the task transition happened.
         if (result.changes < 1) continue;
+        // #2022 — retire the inbox rows in the same transaction. Nothing
+        // else acks them: an expired task can never be acked by its target,
+        // and retention only sweeps acked=1 rows, so leaving them unacked
+        // kept them in every "unacked inbox" consumer (the stop/delete gate,
+        // the unread badge) forever. COALESCE(task_id, id) mirrors
+        // cancel_task — legacy rows carry the logical task id in `id`.
+        db.run(
+          `UPDATE inbox SET acked = 1 WHERE COALESCE(task_id, id) = ?1 AND acked = 0`,
+          [task.task_id],
+        );
         syncScheduledRunForTask(task.task_id, task.network_id);
         changed.push(task);
       }
@@ -2391,7 +2402,6 @@ return Bun.serve({
           ...(canonical.renamed ? { renamed_from: body.alias, renamed_to: targetAlias } : {}),
         }, { status: 404 }));
       }
-      const id = crypto.randomUUID();
       // Identity binding, mirroring the MCP transport (tools.ts defaultFrom /
       // fromIdentityMismatchReply). Both transports resolve the same
       // api_tokens row through resolveToken, and auth.ts already documents the
@@ -2450,12 +2460,61 @@ return Bun.serve({
           : "legacy";
       const metaJson = normalizeMetaJson(stampTaskAuthOrigin(mergedMeta, authOrigin));
 
+      // Client-request-id idempotency, mirroring the MCP `send_task` tool
+      // (tools.ts). The app/Dashboard mint one `meta.client_request_id` per
+      // message bubble and reuse it only to retry that bubble, so:
+      //   - the task id is derived from (network, from, request id): a retry
+      //     after a lost response finds the row it already wrote and gets the
+      //     same task id back (200, idempotent_replay) — across restarts too;
+      //   - the same id with a different payload fails closed (409);
+      //   - a NEW id is a new message even when the text is identical, so it
+      //     must not hit the #212 content-hash window below (that silently
+      //     dropped a user's second 「好」 while the app showed it delivered).
+      const clientRequestId = clientRequestIdFromMeta(mergedMeta);
+      const id = clientRequestId
+        ? idempotentTaskId(taskNetId ?? null, fromSession, clientRequestId)
+        : crypto.randomUUID();
+      if (clientRequestId) {
+        const existing = db.get<StoredIdempotentTask & { to_node_id: string | null }>(
+          "SELECT task_id, from_name, to_node_id, to_name, priority, content, network_id, meta_json, status FROM tasks WHERE task_id = ?1",
+          [id],
+        );
+        if (existing) {
+          if (!idempotentTaskMatches(existing, {
+            fromName: fromSession, toName: targetAlias, priority: body.priority, content: body.task,
+            networkId: taskNetId ?? null, metaJson,
+          })) {
+            console.log(`[/api/task] ${fromSession} → ${targetAlias}: REJECTED idempotency_conflict (key=request_id, task=${existing.task_id.slice(0, 13)})`);
+            return withCors(req, Response.json({
+              ok: false,
+              error: "idempotency_conflict",
+              message: "client_request_id was already used with a different task payload",
+            }, { status: 409 }));
+          }
+          console.log(`[/api/task] ${fromSession} → ${targetAlias}: REPLAY (key=request_id, task=${existing.task_id.slice(0, 13)})`);
+          return withCors(req, Response.json({
+            ok: true,
+            task_id: existing.task_id,
+            message_id: existing.task_id,
+            task_status: existing.status,
+            idempotent_replay: true,
+            actual_to: {
+              alias: existing.to_name,
+              to_node_id: existing.to_node_id ?? null,
+              network_id: existing.network_id ?? null,
+            },
+          }));
+        }
+      }
+
       // #212 dedup guardrail. Mirrors the MCP `send_task` tool: same
       // (from_session, target_alias, task) within COMMHUB_SEND_DEDUP_WINDOW_MS
       // is rejected with a structured `duplicate_send` error so dashboard
       // dispatch buttons and scripted REST callers get the same guarantee
-      // as agent-driven MCP traffic.
-      const dedup = sharedSendDedup.check(fromSession, targetAlias, body.task);
+      // as agent-driven MCP traffic. Sends carrying a client_request_id are
+      // keyed on that id instead of the content (send_dedup.ts header).
+      const dedupScope = { requestId: clientRequestId, networkId: taskNetId ?? null };
+      const dedup = sharedSendDedup.check(fromSession, targetAlias, body.task, undefined, dedupScope);
       if (dedup.duplicate) {
         const payload = buildDuplicateSendPayload({
           from: fromSession,
@@ -2463,7 +2522,7 @@ return Bun.serve({
           ageMs: dedup.ageMs,
           windowMs: sharedSendDedup.windowMs,
         });
-        console.log(`[/api/task] ${fromSession} → ${targetAlias}: DROPPED duplicate (age=${dedup.ageMs}ms, window=${sharedSendDedup.windowMs}ms)`);
+        console.log(`[/api/task] ${fromSession} → ${targetAlias}: DROPPED duplicate (key=${dedup.kind}, age=${dedup.ageMs}ms, window=${sharedSendDedup.windowMs}ms)`);
         return withCors(req, Response.json(payload, { status: 429 }));
       }
 
@@ -2518,7 +2577,7 @@ return Bun.serve({
       // #212 — stamp the dedup index only after the inbox/tasks insert
       // succeeds. Mirrors the MCP `send_task` path so a failed write
       // never shadows a legitimate retry.
-      sharedSendDedup.record(fromSession, targetAlias, body.task);
+      sharedSendDedup.record(fromSession, targetAlias, body.task, undefined, dedupScope);
       if (target.state === "offline") {
         return withCors(req, Response.json({
           ok: false,

package/src/stop-delete-node.test.ts

@@ -2,6 +2,7 @@ import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 import { db } from "./db.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerTools } from "./tools.js";
+import { patrolExpiredTasks } from "./server.js";
 
 // RFC-027 PR1 — handler-driven tests for stop_node, delete_node,
 // get_stop_request, ack_stop_request. Drives the MCP handlers via
@@ -42,6 +43,9 @@ function cleanup() {
     // PR1.2a restart_node tests leave node_config_updates rows; clear
     // so the next test's restart_node doesn't see them as in_flight.
     try { db.run("DELETE FROM node_config_updates WHERE network_id = ?1", [n]); } catch {}
+    // #2022 seeds tasks rows whose status drives the in-flight join; clear
+    // them by network or a later test inherits a stale terminal row.
+    try { db.run("DELETE FROM tasks WHERE network_id = ?1", [n]); } catch {}
     try { db.run("DELETE FROM nodes WHERE network_id = ?1", [n]); } catch {}
     try { db.run("DELETE FROM sessions WHERE network_id = ?1", [n]); } catch {}
     try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [n]); } catch {}
@@ -950,3 +954,211 @@ describe("delete_node — stale-deleting redispatch exit (#1286)", () => {
     expect(r.ok).toBe(true);
   });
 });
+
+// ── #2022 — in-flight gate: terminal / aged rows must not pin busy ──
+//
+// The old gate was COUNT(*) FROM inbox WHERE session_name=? AND acked=0:
+// no join to tasks, no age limit, and nothing acks an inbox row whose
+// task already died (retention sweeps only acked=1 rows), so a single
+// dead row pinned the node to node_busy_in_flight forever.
+//
+// Rule under test (#2029 review):
+//   1. type='task' rows that join to a tasks row are judged by status
+//      ALONE — terminal (replied / failed / cancelled / expired) is not
+//      counted, anything else is counted with NO age ceiling. agent-node
+//      acks the inbox row only when the task is done, so a 90-minute
+//      (or ttl_seconds>3600) run stays acked=0 the whole time and must
+//      keep the gate closed; expiry is patrolExpiredTasks' job.
+//      Join key is COALESCE(task_id, id), the logical id cancel_task
+//      uses.
+//   2. rows with no status of their own — task rows whose tasks row is
+//      gone, and non-task rows (reply / broadcast / message) — get the
+//      60-minute age ceiling; nothing else will ever retire them.
+//   3. patrolExpiredTasks acks the matching inbox rows in the same
+//      transaction that expires the task.
+
+function seedTaskWithInbox(
+  net: string,
+  alias: string,
+  opts: {
+    task_id: string;
+    status: string;
+    /** signed datetime offset for the tasks row, e.g. '-3 days' */
+    task_age?: string;
+    /** signed datetime offset for the inbox row, e.g. '-3 days' */
+    inbox_age?: string;
+    /** signed datetime offset for tasks.expires_at, e.g. '+1 hour' */
+    expires_in?: string;
+  },
+) {
+  db.run(
+    `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response,
+                        created_at, delivered_at, expires_at, network_id)
+     VALUES (?1, 'caller', ?2, 'normal', ?3, 'do the thing', 'reply',
+             datetime('now', ?4), datetime('now', ?4), datetime('now', ?5), ?6)`,
+    [opts.task_id, alias, opts.status, opts.task_age ?? "0 seconds", opts.expires_in ?? "+1 hour", net],
+  );
+  db.run(
+    `INSERT INTO inbox (id, task_id, session_name, type, priority, content, from_session, network_id, acked, created_at)
+     VALUES (?1, ?1, ?2, 'task', 'normal', 'do the thing', 'caller', ?3, 0, datetime('now', ?4))`,
+    [opts.task_id, alias, net, opts.inbox_age ?? "0 seconds"],
+  );
+}
+
+function stopArgs() {
+  return { child_node_id: CHILD_A_ID, daemon_node_id: DAEMON_A_ID, network_id: NET_A };
+}
+
+describe("#2022 stop gate — terminal task rows are not in flight", () => {
+  test("28-day-old expired + 3-day-old replied rows → stop dispatches, in_flight=0", async () => {
+    setupAlphaNetwork();
+    seedTaskWithInbox(NET_A, CHILD_A_ALIAS, {
+      task_id: "task_2022_expired", status: "expired",
+      task_age: "-28 days", inbox_age: "-28 days", expires_in: "-27 days",
+    });
+    seedTaskWithInbox(NET_A, CHILD_A_ALIAS, {
+      task_id: "task_2022_replied", status: "replied",
+      task_age: "-3 days", inbox_age: "-3 days", expires_in: "-2 days",
+    });
+    const r = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(r.ok).toBe(true);
+    expect(r.in_flight_at_dispatch).toBe(0);
+    expect(readNode(CHILD_A_ID)?.lifecycle_state).toBe("stopping");
+  });
+
+  test("FRESH terminal row (replied, 0s old) also not counted — terminal filter alone is enough", async () => {
+    setupAlphaNetwork();
+    seedTaskWithInbox(NET_A, CHILD_A_ALIAS, { task_id: "task_2022_fresh_replied", status: "replied" });
+    const r = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(r.ok).toBe(true);
+    expect(r.in_flight_at_dispatch).toBe(0);
+  });
+});
+
+describe("#2022 stop gate — genuinely in-flight rows still block", () => {
+  test("fresh non-terminal task row → node_busy_in_flight, count surfaced, state untouched", async () => {
+    setupAlphaNetwork();
+    seedTaskWithInbox(NET_A, CHILD_A_ALIAS, { task_id: "task_2022_live", status: "delivered" });
+    const r = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("node_busy_in_flight");
+    expect(r.in_flight_count).toBe(1);
+    expect(readNode(CHILD_A_ID)?.lifecycle_state).toBe("active");
+    expect(readAudit("stop_node_dispatched", NET_A).length).toBe(0);
+  });
+
+  test("fresh non-task inbox row (type='reply') still counts — judged by age only", async () => {
+    setupAlphaNetwork();
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, content, from_session, network_id, acked, created_at)
+       VALUES (?1, ?2, 'reply', 'fresh reply', 'caller', ?3, 0, datetime('now'))`,
+      [`inbox_2022_fresh_reply`, CHILD_A_ALIAS, NET_A],
+    );
+    const r = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("node_busy_in_flight");
+    expect(r.in_flight_count).toBe(1);
+  });
+});
+
+describe("#2022 stop gate — a live task is never aged out (status wins over age)", () => {
+  test("🔴 created 2 hours ago + task.status='running' → still node_busy_in_flight", async () => {
+    setupAlphaNetwork();
+    seedTaskWithInbox(NET_A, CHILD_A_ALIAS, {
+      task_id: "task_2022_running_90m", status: "running",
+      task_age: "-120 minutes", inbox_age: "-120 minutes", expires_in: "-60 minutes",
+    });
+    const r = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("node_busy_in_flight");
+    expect(r.in_flight_count).toBe(1);
+    expect(readNode(CHILD_A_ID)?.lifecycle_state).toBe("active");
+  });
+
+  test("task.status='acked' 2 hours old (patrol never expires it) → still blocked", async () => {
+    setupAlphaNetwork();
+    seedTaskWithInbox(NET_A, CHILD_A_ALIAS, {
+      task_id: "task_2022_acked_120m", status: "acked",
+      inbox_age: "-120 minutes", expires_in: "+12 hours",
+    });
+    const r = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(r.error).toBe("node_busy_in_flight");
+    expect(r.in_flight_count).toBe(1);
+  });
+});
+
+describe("#2022 stop gate — age ceiling (60 min) for rows with no status", () => {
+  test("orphan task row (tasks row reaped) 8 days old → not counted", async () => {
+    setupAlphaNetwork();
+    db.run(
+      `INSERT INTO inbox (id, task_id, session_name, type, content, from_session, network_id, acked, created_at)
+       VALUES (?1, ?1, ?2, 'task', 'orphan task', 'caller', ?3, 0, datetime('now', '-8 days'))`,
+      [`task_2022_reaped`, CHILD_A_ALIAS, NET_A],
+    );
+    const r = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(r.ok).toBe(true);
+    expect(r.in_flight_at_dispatch).toBe(0);
+  });
+
+  test("non-task row older than the ceiling → not counted (the production backlog shape)", async () => {
+    setupAlphaNetwork();
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, content, from_session, network_id, acked, created_at)
+       VALUES (?1, ?2, 'broadcast', 'week-old broadcast', 'caller', ?3, 0, datetime('now', '-7 days'))`,
+      [`inbox_2022_old_broadcast`, CHILD_A_ALIAS, NET_A],
+    );
+    const r = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(r.ok).toBe(true);
+    expect(r.in_flight_at_dispatch).toBe(0);
+  });
+});
+
+describe("#2022 patrolExpiredTasks — expires the task AND acks its inbox rows", () => {
+  test("same transaction: tasks.status='expired' + inbox.acked=1 → gate unblocks", async () => {
+    setupAlphaNetwork();
+    seedTaskWithInbox(NET_A, CHILD_A_ALIAS, {
+      task_id: "task_2022_due", status: "delivered",
+      inbox_age: "-10 minutes", expires_in: "-1 minute",
+    });
+
+    // Before the patrol: fresh, non-terminal → the node is correctly busy.
+    const before = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(before.error).toBe("node_busy_in_flight");
+    expect(before.in_flight_count).toBe(1);
+
+    patrolExpiredTasks();
+
+    expect(db.get<{ status: string }>("SELECT status FROM tasks WHERE task_id = ?1", "task_2022_due")?.status).toBe("expired");
+    const inboxRow = db.get<{ acked: number }>(
+      "SELECT acked FROM inbox WHERE task_id = ?1 AND session_name = ?2", "task_2022_due", CHILD_A_ALIAS,
+    );
+    expect(inboxRow?.acked).toBe(1);
+
+    // And the gate that was blocked a moment ago now dispatches.
+    const after = await call(buildHandlers(USER_A_ID).stop_node, stopArgs());
+    expect(after.ok).toBe(true);
+    expect(after.in_flight_at_dispatch).toBe(0);
+  });
+
+  test("legacy inbox row keyed by id (task_id IS NULL) is acked too", async () => {
+    setupAlphaNetwork();
+    db.run(
+      `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response,
+                          created_at, expires_at, network_id)
+       VALUES ('task_2022_legacy', 'caller', ?1, 'normal', 'delivered', 'do the thing', 'reply',
+               datetime('now', '-10 minutes'), datetime('now', '-1 minute'), ?2)`,
+      [CHILD_A_ALIAS, NET_A],
+    );
+    // Pre-task_id shape: the transport row IS the logical id.
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, content, from_session, network_id, acked, created_at)
+       VALUES ('task_2022_legacy', ?1, 'task', 'do the thing', 'caller', ?2, 0, datetime('now', '-10 minutes'))`,
+      [CHILD_A_ALIAS, NET_A],
+    );
+
+    patrolExpiredTasks();
+
+    expect(db.get<{ status: string }>("SELECT status FROM tasks WHERE task_id = 'task_2022_legacy'")?.status).toBe("expired");
+    expect(db.get<{ acked: number }>("SELECT acked FROM inbox WHERE id = 'task_2022_legacy'")?.acked).toBe(1);
+  });
+});

package/src/tools.ts

@@ -1621,6 +1621,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
               message: "client_request_id was already used with a different task payload",
             }) }] };
           }
+          console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: REPLAY (key=request_id, task=${existing.task_id.slice(0, 13)})`);
           return { content: [{ type: "text" as const, text: JSON.stringify({
             ok: true, message_id: existing.task_id, task_id: existing.task_id,
             task_status: existing.status, idempotent_replay: true,
@@ -1644,7 +1645,13 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // incident: 50+ identical dispatches across 5 LLM turns ignored
       // three STOP replies — the LLM cannot be trusted to debounce
       // itself, so the runtime layer must.
-      const dedup = sharedSendDedup.check(from_session, targetAlias, task);
+      //
+      // A send carrying a validated client_request_id is keyed on that id
+      // instead of the content hash (send_dedup.ts header): a human typing
+      // the same short text twice sent two messages. Same-id retries were
+      // already answered from the durable row above.
+      const dedupScope = { requestId: clientRequestId, networkId: effectiveNetId ?? null };
+      const dedup = sharedSendDedup.check(from_session, targetAlias, task, undefined, dedupScope);
       if (dedup.duplicate) {
         const payload = buildDuplicateSendPayload({
           from: from_session,
@@ -1652,7 +1659,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           ageMs: dedup.ageMs,
           windowMs: sharedSendDedup.windowMs,
         });
-        console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: DROPPED duplicate (age=${dedup.ageMs}ms, window=${sharedSendDedup.windowMs}ms)`);
+        console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: DROPPED duplicate (key=${dedup.kind}, age=${dedup.ageMs}ms, window=${sharedSendDedup.windowMs}ms)`);
         return { content: [{ type: "text" as const, text: JSON.stringify(payload) }] };
       }
 
@@ -1692,7 +1699,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // Only stamp the dedup index after the inbox/tasks transaction
       // succeeds, so a failed insert never silently shadows a legitimate
       // retry.
-      sharedSendDedup.record(from_session, targetAlias, task);
+      sharedSendDedup.record(from_session, targetAlias, task, undefined, dedupScope);
 
       // SSE push by alias.
       // The SSE channel is keyed by alias (subscribers connected to /events/<alias>),
@@ -4528,10 +4535,50 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     // Use COALESCE so a NULL inbox row is counted against the same
     // network as the target node (which is the only safe default
     // — pre-multi-network rows existed in single-network mode).
+    //
+    // #2022 — "unacked" alone is not "in flight". Nothing acks a row
+    // whose task already reached a terminal state (report_completion,
+    // send_reply, send_ack, the TTL patrol all leave inbox alone) and
+    // retention sweeps only acked=1 rows, so those rows were counted
+    // forever: one dead row pinned this gate to node_busy_in_flight
+    // and force=true was the only way past it.
+    //
+    // Counting rule (#2029 review): a row counts while it can still be
+    // work this node is doing — and the age ceiling must NOT be applied
+    // to a task row whose tasks row we can see. agent-node acks the
+    // inbox row only once the task is done, so a 90-minute (or 3-hour,
+    // or ttl_seconds>3600) task keeps acked=0 for its whole run;
+    // capping it by age would open this gate mid-run, which is exactly
+    // what the gate exists to prevent. So:
+    //   1. type='task' row with a matching tasks row — LEFT JOIN on
+    //      COALESCE(task_id, id), the key cancel_task / ack_inbox use
+    //      (first deliveries set id == task_id; retry/reassign write a
+    //      fresh transport id). Status alone decides: terminal
+    //      (replied / failed / cancelled / expired) → not counted;
+    //      anything else → counted, no age ceiling. Expiry belongs to
+    //      patrolExpiredTasks, which now acks the inbox row in the same
+    //      transaction, so an expired task leaves this count together
+    //      with its rows.
+    //   2. every other row — a task row whose tasks row is gone
+    //      (reaped by retention, or a legacy row whose id resolves to
+    //      nothing) and non-task rows (reply / broadcast / message):
+    //      these carry no status of their own and nothing else will
+    //      ever retire them, so they get the age ceiling
+    //      IN_FLIGHT_MAX_AGE_MINUTES on inbox.created_at.
+    // The count stays a per-alias inbox count: one PK join per row.
+    const IN_FLIGHT_MAX_AGE_MINUTES = 60;
     const inFlightRow = db.get<{ n: number }>(
-      `SELECT COUNT(*) AS n FROM inbox WHERE session_name = ?1 AND acked = 0
-         AND COALESCE(network_id, ?2) = ?2`,
-      node.alias, node.network_id,
+      `SELECT COUNT(*) AS n FROM inbox i
+         LEFT JOIN tasks t
+           ON i.type = 'task'
+          AND t.task_id = COALESCE(i.task_id, i.id)
+        WHERE i.session_name = ?1 AND i.acked = 0
+          AND COALESCE(i.network_id, ?2) = ?2
+          AND ((t.task_id IS NOT NULL
+                AND t.status NOT IN ('replied', 'failed', 'cancelled', 'expired'))
+            OR (t.task_id IS NULL
+                AND i.created_at >= datetime('now', ?3)))`,
+      node.alias, node.network_id, `-${IN_FLIGHT_MAX_AGE_MINUTES} minutes`,
     );
     const inFlight = inFlightRow?.n ?? 0;
     if (inFlight > 0 && !args.force) {