@sleep2agi/commhub-server 0.8.4 → 0.8.5-preview.1

package/README.md

@@ -1,8 +1,13 @@
 # @sleep2agi/commhub-server
 
+[![npm version](https://img.shields.io/npm/v/@sleep2agi/commhub-server.svg)](https://www.npmjs.com/package/@sleep2agi/commhub-server)
+[![npm downloads](https://img.shields.io/npm/dm/@sleep2agi/commhub-server.svg)](https://www.npmjs.com/package/@sleep2agi/commhub-server)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/sleep2agi/agent-network/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-anet.sh-009e7e.svg)](https://anet.sh)
+
 CommHub: MCP Streamable HTTP + SSE push + REST API for an AI agent network. Single-process Bun server, SQLite-backed, zero config when launched through `anet`.
 
-The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`, currently v2.2.9 at v0.10.10) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
+The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`, currently v2.2.10 at v0.10.11) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
 
 ## Quick start (verified)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.8.4",
+  "version": "0.8.5-preview.1",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -6,6 +6,7 @@ import { db, logTaskEvent, logAudit } from "./db.js";
 import { createSSEStream, pushEvent, getSSEStats } from "./push.js";
 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";
 
 const PORT = Number(process.env.PORT) || 9200;
 const HOST = process.env.HOST || "127.0.0.1";
@@ -340,6 +341,36 @@ function canRestWriteNetwork(authCtx: { userId: string; networkId: string | null
   return !!role && role !== "viewer";
 }
 
+type RestDeliveryTarget =
+  | { state: "online"; alias: string; session: any }
+  | { state: "offline"; alias: string; session: any; message: string }
+  | { state: "not_found"; alias: string; message: string };
+
+function resolveRestDeliveryTarget(alias: string, networkId: string | null): RestDeliveryTarget {
+  const params: any[] = [alias];
+  let sql = "SELECT status, updated_at, last_seen_at FROM sessions WHERE alias = ?1";
+  if (networkId) {
+    sql += " AND network_id = ?2";
+    params.push(networkId);
+  }
+  const session = db.get<any>(sql, ...params);
+  if (!session) {
+    return { state: "not_found", alias, message: `alias not found: ${alias}` };
+  }
+  const lastSeen = session.last_seen_at || session.updated_at;
+  const lastSeenAt = lastSeen ? new Date(String(lastSeen).replace(" ", "T") + "Z").getTime() : 0;
+  const stale = !lastSeenAt || Date.now() - lastSeenAt > 5 * 60 * 1000;
+  if (String(session.status || "").toLowerCase() === "offline" || stale) {
+    return {
+      state: "offline",
+      alias,
+      session,
+      message: `alias is offline; task queued in inbox: ${alias}`,
+    };
+  }
+  return { state: "online", alias, session };
+}
+
 // ── REST input schema ───────────────────────────────
 const TaskSchema = z.object({
   alias: z.string().min(1).max(200),
@@ -1198,10 +1229,39 @@ Bun.serve({
       }
       const canonical = resolveCanonicalAlias(taskNetId, body.alias);
       const targetAlias = canonical.alias;
+      const target = resolveRestDeliveryTarget(targetAlias, taskNetId);
+      if (target.state === "not_found") {
+        return withCors(req, Response.json({
+          ok: false,
+          error: "alias_not_found",
+          message: target.message,
+          alias: targetAlias,
+          queued: false,
+          ...(canonical.renamed ? { renamed_from: body.alias, renamed_to: targetAlias } : {}),
+        }, { status: 404 }));
+      }
       const id = crypto.randomUUID();
       const fromSession = body.from || "api";
       const ttlSeconds = (body as any).ttl_seconds || 3600;
       const metaJson = normalizeMetaJson((body as any).meta);
+
+      // #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);
+      if (dedup.duplicate) {
+        const payload = buildDuplicateSendPayload({
+          from: fromSession,
+          to: targetAlias,
+          ageMs: dedup.ageMs,
+          windowMs: sharedSendDedup.windowMs,
+        });
+        console.log(`[/api/task] ${fromSession} → ${targetAlias}: DROPPED duplicate (age=${dedup.ageMs}ms, window=${sharedSendDedup.windowMs}ms)`);
+        return withCors(req, Response.json(payload, { status: 429 }));
+      }
+
       // Mirror send_task MCP: write inbox + tasks rows in a single
       // transaction so the dispatch is visible to dashboard's Tasks page
       // and the parent_task_id lineage chain. Previously this endpoint
@@ -1232,11 +1292,26 @@ Bun.serve({
       let pendingSql = "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
       if (taskNetId) { pendingSql += " AND network_id = ?2"; pendingParams.push(taskNetId); }
       const pending = db.get<{ cnt: number }>(pendingSql, ...pendingParams);
-      const sessionParams: any[] = [targetAlias];
-      let sessionSql = "SELECT 1 FROM sessions WHERE alias = ?1";
-      if (taskNetId) { sessionSql += " AND network_id = ?2"; sessionParams.push(taskNetId); }
-      const targetSession = db.get<any>(sessionSql, ...sessionParams);
-      if (targetSession) pushEvent(targetAlias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority: body.priority, from: fromSession, ...(canonical.renamed ? { renamed_from: body.alias } : {}) }, taskNetId);
+      if (target.state === "online") {
+        pushEvent(targetAlias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority: body.priority, from: fromSession, ...(canonical.renamed ? { renamed_from: body.alias } : {}) }, taskNetId);
+      }
+      // #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);
+      if (target.state === "offline") {
+        return withCors(req, Response.json({
+          ok: false,
+          error: "alias_offline",
+          message: target.message,
+          alias: targetAlias,
+          queued: true,
+          task_id: id,
+          message_id: id,
+          session_status: target.session.status ?? "offline",
+          ...(canonical.renamed ? { renamed_from: body.alias, renamed_to: targetAlias } : {}),
+        }, { status: 202 }));
+      }
       return withCors(req, Response.json({ ok: true, task_id: id, message_id: id, ...(canonical.renamed ? { renamed_from: body.alias, renamed_to: targetAlias } : {}) }));
     }
 

package/src/send_dedup.test.ts

@@ -0,0 +1,160 @@
+// Unit test for the #212 send_task dedup guardrail.
+//
+// Pure-function module — no DB, no MCP server, just verifies the dedup
+// algebra: same key in window is rejected; different key (cross-from,
+// cross-to, cross-content) is allowed; expired entry restored; disabled
+// window short-circuits everything; structured payload contains both the
+// Chinese hint the LLM is supposed to act on and machine-parseable
+// details.
+import { describe, expect, it } from "bun:test";
+import {
+  SendDedup,
+  buildDuplicateSendPayload,
+  readDedupConfig,
+} from "./send_dedup.js";
+
+describe("readDedupConfig", () => {
+  it("defaults to 300000 ms window and 4096 max keys", () => {
+    const cfg = readDedupConfig({});
+    expect(cfg.windowMs).toBe(300_000);
+    expect(cfg.maxKeys).toBe(4096);
+  });
+
+  it("respects COMMHUB_SEND_DEDUP_WINDOW_MS=0 to disable", () => {
+    const cfg = readDedupConfig({ COMMHUB_SEND_DEDUP_WINDOW_MS: "0" });
+    expect(cfg.windowMs).toBe(0);
+  });
+
+  it("parses custom window and max keys from env", () => {
+    const cfg = readDedupConfig({
+      COMMHUB_SEND_DEDUP_WINDOW_MS: "60000",
+      COMMHUB_SEND_DEDUP_MAX_KEYS: "256",
+    });
+    expect(cfg.windowMs).toBe(60_000);
+    expect(cfg.maxKeys).toBe(256);
+  });
+
+  it("clamps negative window to 0 and small max keys to 64", () => {
+    const cfg = readDedupConfig({
+      COMMHUB_SEND_DEDUP_WINDOW_MS: "-1",
+      COMMHUB_SEND_DEDUP_MAX_KEYS: "1",
+    });
+    expect(cfg.windowMs).toBe(0);
+    expect(cfg.maxKeys).toBe(64);
+  });
+});
+
+describe("SendDedup", () => {
+  it("flags a repeat send within the window", () => {
+    const d = new SendDedup({ windowMs: 60_000, maxKeys: 32 });
+    const t0 = 1_700_000_000_000;
+
+    expect(d.check("alice", "bob", "hello", t0)).toEqual({ duplicate: false });
+    d.record("alice", "bob", "hello", t0);
+
+    const second = d.check("alice", "bob", "hello", t0 + 1000);
+    expect(second.duplicate).toBe(true);
+    if (second.duplicate) {
+      expect(second.lastSentMs).toBe(t0);
+      expect(second.ageMs).toBe(1000);
+    }
+  });
+
+  it("allows the same content after the window elapses", () => {
+    const d = new SendDedup({ windowMs: 60_000, maxKeys: 32 });
+    const t0 = 1_700_000_000_000;
+    d.record("alice", "bob", "hello", t0);
+
+    const stillIn = d.check("alice", "bob", "hello", t0 + 59_000);
+    expect(stillIn.duplicate).toBe(true);
+
+    const past = d.check("alice", "bob", "hello", t0 + 60_001);
+    expect(past).toEqual({ duplicate: false });
+  });
+
+  it("does not conflate different senders, targets, or contents", () => {
+    const d = new SendDedup({ windowMs: 60_000, maxKeys: 32 });
+    const t0 = 1_700_000_000_000;
+    d.record("alice", "bob", "hello", t0);
+
+    // Different sender → allowed.
+    expect(d.check("carol", "bob", "hello", t0 + 1000)).toEqual({ duplicate: false });
+    // Different target → allowed.
+    expect(d.check("alice", "dave", "hello", t0 + 1000)).toEqual({ duplicate: false });
+    // Different content → allowed (even with trailing whitespace tweak).
+    expect(d.check("alice", "bob", "hello ", t0 + 1000)).toEqual({ duplicate: false });
+    // Repeated original → still flagged.
+    expect(d.check("alice", "bob", "hello", t0 + 1000).duplicate).toBe(true);
+  });
+
+  it("treats windowMs=0 as fully disabled", () => {
+    const d = new SendDedup({ windowMs: 0, maxKeys: 32 });
+    expect(d.enabled).toBe(false);
+    d.record("alice", "bob", "hello", 1);
+    expect(d.check("alice", "bob", "hello", 2)).toEqual({ duplicate: false });
+    expect(d.size).toBe(0);
+  });
+
+  it("opportunistically evicts expired entries during check", () => {
+    const d = new SendDedup({ windowMs: 10_000, maxKeys: 32 });
+    d.record("alice", "bob", "hello", 1000);
+    d.record("alice", "bob", "world", 1500);
+    expect(d.size).toBe(2);
+
+    // Far past both entries' window — check should evict both.
+    expect(d.check("alice", "bob", "third", 100_000)).toEqual({ duplicate: false });
+    expect(d.size).toBe(0);
+  });
+
+  it("caps map size by oldest-first eviction when exceeding maxKeys", () => {
+    const d = new SendDedup({ windowMs: 600_000, maxKeys: 64 });
+    for (let i = 0; i < 100; i++) {
+      d.record(`from-${i}`, "bob", `content-${i}`, 1_000 + i);
+    }
+    // Eviction triggers when size > maxKeys; after eviction we keep ~90 %
+    // of maxKeys, so size should land below maxKeys.
+    expect(d.size).toBeLessThanOrEqual(64);
+    expect(d.size).toBeGreaterThan(0);
+  });
+
+  it("hashes content rather than holding the raw bytes", () => {
+    // The key function is the public surface that proves we don't keep
+    // raw content in memory between sends — the map keys themselves are
+    // safe to log/inspect.
+    const key = SendDedup.key("alice", "bob", "secret payload");
+    expect(key.startsWith("alice|bob|")).toBe(true);
+    expect(key).toMatch(/\|[0-9a-f]{64}$/);
+    expect(key).not.toContain("secret");
+  });
+});
+
+describe("buildDuplicateSendPayload", () => {
+  it("contains the Chinese LLM-facing hint with target alias and window minutes", () => {
+    const payload = buildDuplicateSendPayload({
+      from: "A站Grok",
+      to: "A站负责人",
+      ageMs: 12_345,
+      windowMs: 300_000,
+    });
+    expect(payload.ok).toBe(false);
+    expect(payload.error).toBe("duplicate_send");
+    expect(payload.message).toContain("5 分钟内已发给 A站负责人");
+    expect(payload.message).toContain("改写内容或等待");
+    expect(payload.details.age_ms).toBe(12_345);
+    expect(payload.details.window_ms).toBe(300_000);
+    expect(payload.details.from).toBe("A站Grok");
+    expect(payload.details.target).toBe("A站负责人");
+    expect(payload.details.hint_en).toContain("change the content or wait");
+  });
+
+  it("rounds the window display to whole minutes", () => {
+    const payload = buildDuplicateSendPayload({
+      from: "from-x",
+      to: "to-y",
+      ageMs: 0,
+      windowMs: 90_000,
+    });
+    // 90 s rounds to 2 min for the human-readable hint.
+    expect(payload.message).toContain("2 分钟内");
+  });
+});

package/src/send_dedup.ts

@@ -0,0 +1,192 @@
+// #212 — commhub-server send_task dedup guardrail.
+//
+// Vincent's A站Grok ran away on 2026-06-10 and sent the same task to the
+// same target 50+ times within five LLM turns (4692 chunks in a single
+// turn). It ignored three STOP replies — by the time a reply landed back
+// in its inbox the LLM had already decided to dispatch again. The dispatch
+// path was the agent's own commhub_send_task MCP tool call against
+// commhub-server's HTTP MCP transport (#204 preview.6 wiring), so the
+// agent-node runtime never saw the bytes and could not intervene
+// client-side.
+//
+// This module is the server-side guardrail: any `send_task` (whether
+// through MCP `tools/call` or the REST `/api/task` endpoint) is checked
+// against an in-memory dedup index keyed by `(from_session, target_alias,
+// sha256(content))`. A second call to the same key within the configured
+// window is rejected with a structured `duplicate_send` error containing
+// a human-readable hint the LLM can act on ("change the task content or
+// wait").
+//
+// Design notes:
+//   - Keyed by content hash, not the raw content, so we never hold the
+//     task body in memory longer than the request itself.
+//   - In-memory only. Process restart wipes the index, which is the
+//     desired failure mode (servers restart far more rarely than the
+//     5-minute default window, and a fresh window after restart is safer
+//     than rehydrating from disk).
+//   - Opportunistic eviction during every `shouldDedup` call keeps the
+//     map bounded without a separate sweep timer.
+//   - Window = 0 disables the guardrail entirely (escape hatch for the
+//     rare cases where a workflow genuinely needs to fan out the same
+//     task repeatedly — e.g. a batch sweep that produces identical
+//     payloads by design).
+//   - The structured response shape is identical between MCP and REST
+//     callers so the LLM gets the same parseable hint regardless of
+//     transport.
+
+import { createHash } from "crypto";
+
+export type DedupConfig = {
+  /** Window in ms; 0 disables guardrail. Default 300000 (5 min). */
+  windowMs: number;
+  /** Max keys to retain; opportunistically evicted past this. Default 4096. */
+  maxKeys: number;
+};
+
+export function readDedupConfig(env: NodeJS.ProcessEnv = process.env): DedupConfig {
+  const rawWindow = env.COMMHUB_SEND_DEDUP_WINDOW_MS;
+  const windowMs = rawWindow !== undefined ? Math.max(0, Number(rawWindow)) : 300_000;
+  const rawMax = env.COMMHUB_SEND_DEDUP_MAX_KEYS;
+  const maxKeys = rawMax !== undefined ? Math.max(64, Number(rawMax)) : 4096;
+  return {
+    windowMs: Number.isFinite(windowMs) ? windowMs : 300_000,
+    maxKeys: Number.isFinite(maxKeys) ? maxKeys : 4096,
+  };
+}
+
+export type DedupCheck =
+  | { duplicate: false }
+  | { duplicate: true; lastSentMs: number; ageMs: number };
+
+export class SendDedup {
+  private last = new Map<string, number>();
+  private cfg: DedupConfig;
+
+  constructor(cfg: Partial<DedupConfig> = {}) {
+    const fallback = readDedupConfig();
+    this.cfg = { windowMs: cfg.windowMs ?? fallback.windowMs, maxKeys: cfg.maxKeys ?? fallback.maxKeys };
+  }
+
+  /** Whether the dedup guardrail is enabled at all. */
+  get enabled(): boolean {
+    return this.cfg.windowMs > 0;
+  }
+
+  get windowMs(): number {
+    return this.cfg.windowMs;
+  }
+
+  /** Visible for tests only. */
+  get size(): number {
+    return this.last.size;
+  }
+
+  static key(from: string, to: string, content: string): string {
+    const hash = createHash("sha256").update(content).digest("hex");
+    return `${from}|${to}|${hash}`;
+  }
+
+  /**
+   * Check whether (from, to, content) was sent recently. Returns
+   * `{ duplicate: false }` when the call should proceed, or
+   * `{ duplicate: true, lastSentMs, ageMs }` when the caller should be
+   * rejected with a `duplicate_send` error.
+   *
+   * Does NOT record the new send — callers should call `record(...)`
+   * 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 {
+    if (!this.enabled) return { duplicate: false };
+    this.evictExpired(nowMs);
+    const k = SendDedup.key(from, to, content);
+    const lastSentMs = this.last.get(k);
+    if (lastSentMs === undefined) return { duplicate: false };
+    const ageMs = nowMs - lastSentMs;
+    if (ageMs >= this.cfg.windowMs) {
+      this.last.delete(k);
+      return { duplicate: false };
+    }
+    return { duplicate: true, lastSentMs, ageMs };
+  }
+
+  /** Record a successful send for future dedup checks. */
+  record(from: string, to: string, content: string, nowMs: number = Date.now()): void {
+    if (!this.enabled) return;
+    const k = SendDedup.key(from, to, content);
+    this.last.set(k, nowMs);
+    if (this.last.size > this.cfg.maxKeys) this.evictOldest();
+  }
+
+  /** Visible for tests. Drops everything. */
+  clear(): void {
+    this.last.clear();
+  }
+
+  private evictExpired(nowMs: number): void {
+    const cutoff = nowMs - this.cfg.windowMs;
+    for (const [k, ts] of this.last) {
+      if (ts < cutoff) this.last.delete(k);
+    }
+  }
+
+  private evictOldest(): void {
+    const target = Math.max(64, Math.floor(this.cfg.maxKeys * 0.9));
+    if (this.last.size <= target) return;
+    const entries = Array.from(this.last.entries()).sort((a, b) => a[1] - b[1]);
+    for (let i = 0; i < this.last.size - target; i++) this.last.delete(entries[i][0]);
+  }
+}
+
+// Process-wide singleton consumed by both the MCP `send_task` tool and
+// the REST `/api/task` endpoint so they share a single dedup index
+// regardless of which transport the agent hits. Tests reach for it via
+// `sharedSendDedup.clear()` to reset between cases.
+export const sharedSendDedup = new SendDedup();
+
+/**
+ * Build the structured `duplicate_send` error payload returned to the
+ * caller (MCP wraps it inside `content[0].text` JSON; REST returns it
+ * directly with HTTP 429). The Chinese hint matches what 通信龙 specified
+ * in the #212 dispatch so the LLM has a consistent piece of text to
+ * reason about and rewrite around.
+ */
+export function buildDuplicateSendPayload(args: {
+  from: string;
+  to: string;
+  ageMs: number;
+  windowMs: number;
+}): {
+  ok: false;
+  error: "duplicate_send";
+  message: string;
+  details: {
+    from: string;
+    target: string;
+    age_ms: number;
+    window_ms: number;
+    hint_zh: string;
+    hint_en: string;
+  };
+} {
+  const windowMin = Math.round(args.windowMs / 60_000);
+  const hintZh =
+    `同内容任务 ${windowMin} 分钟内已发给 ${args.to}, ` +
+    `如确需重发请改写内容或等待。 (Last sent ${args.ageMs}ms ago)`;
+  const hintEn =
+    `Same task content already sent to ${args.to} within the last ` +
+    `${windowMin} min — change the content or wait. (Last sent ${args.ageMs}ms ago)`;
+  return {
+    ok: false,
+    error: "duplicate_send",
+    message: hintZh,
+    details: {
+      from: args.from,
+      target: args.to,
+      age_ms: args.ageMs,
+      window_ms: args.windowMs,
+      hint_zh: hintZh,
+      hint_en: hintEn,
+    },
+  };
+}

package/src/tools.ts

@@ -4,6 +4,7 @@ import { db, uuidv4, logTaskEvent, chainReplyToParent } from "./db.js";
 import { pushEvent } from "./push.js";
 import { getUserNetworkRole } from "./auth.js";
 import { canonicalAliasExists, cleanupRenamedAliasSession, resolveCanonicalAlias } from "./rename.js";
+import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
 
 function ts(): string {
   return new Date().toTimeString().slice(0, 8);
@@ -111,12 +112,75 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     return sql;
   };
 
+  type DeliveryTarget =
+    | { state: "online"; alias: string; session: any }
+    | { state: "offline"; alias: string; session: any; message: string }
+    | { state: "not_found"; alias: string; message: string };
+
   const scopedSessionStatus = (alias: string, networkId?: string | null) => {
     const params: any[] = [alias];
-    let sql = "SELECT status FROM sessions WHERE alias = ?1";
+    let sql = "SELECT status, updated_at, last_seen_at FROM sessions WHERE alias = ?1";
     sql = addScope(sql, params, networkId);
     return db.get<any>(sql, ...params);
   };
+
+  const resolveDeliveryTarget = (alias: string, networkId?: string | null): DeliveryTarget => {
+    const session = scopedSessionStatus(alias, networkId);
+    if (!session) {
+      return {
+        state: "not_found",
+        alias,
+        message: `alias not found: ${alias}`,
+      };
+    }
+    const lastSeen = session.last_seen_at || session.updated_at;
+    const lastSeenAt = lastSeen ? new Date(String(lastSeen).replace(" ", "T") + "Z").getTime() : 0;
+    const stale = !lastSeenAt || Date.now() - lastSeenAt > 5 * 60 * 1000;
+    if (String(session.status || "").toLowerCase() === "offline" || stale) {
+      return {
+        state: "offline",
+        alias,
+        session,
+        message: `alias is offline; message queued in inbox: ${alias}`,
+      };
+    }
+    return { state: "online", alias, session };
+  };
+
+  const deliveryTargetReply = (target: DeliveryTarget, ids: Record<string, string> = {}) => {
+    if (target.state === "not_found") {
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            ok: false,
+            error: "alias_not_found",
+            message: target.message,
+            alias: target.alias,
+            queued: false,
+            ...ids,
+          }),
+        }],
+      };
+    }
+    if (target.state === "offline") {
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            ok: false,
+            error: "alias_offline",
+            message: target.message,
+            alias: target.alias,
+            queued: true,
+            session_status: target.session.status ?? "offline",
+            ...ids,
+          }),
+        }],
+      };
+    }
+    return null;
+  };
   // ═══════════════════════════════════════════
   //  Child Agent Tools (4)
   // ═══════════════════════════════════════════
@@ -657,6 +721,29 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
       const canonical = resolveCanonicalAlias(effectiveNetId, alias);
       const targetAlias = canonical.alias;
+      const target = resolveDeliveryTarget(targetAlias, effectiveNetId);
+      if (target.state === "not_found") return deliveryTargetReply(target)!;
+
+      // #212 dedup guardrail. If this exact (from, to, content) has already
+      // been delivered within COMMHUB_SEND_DEDUP_WINDOW_MS (default 5 min)
+      // we refuse the call and surface a structured `duplicate_send`
+      // error. The LLM receives the Chinese hint inside details.message
+      // and can act on it (rewrite the task or wait). See A站Grok #212
+      // 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);
+      if (dedup.duplicate) {
+        const payload = buildDuplicateSendPayload({
+          from: from_session,
+          to: targetAlias,
+          ageMs: dedup.ageMs,
+          windowMs: sharedSendDedup.windowMs,
+        });
+        console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: DROPPED duplicate (age=${dedup.ageMs}ms, window=${sharedSendDedup.windowMs}ms)`);
+        return { content: [{ type: "text" as const, text: JSON.stringify(payload) }] };
+      }
+
       console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: ${task.slice(0, 60)}${priority === "high" ? " [HIGH]" : ""}${canonical.renamed ? ` [renamed from ${alias}]` : ""}`);
       const id = uuidv4();
       // 事务：inbox + tasks 双写 + 触碰目标 session 的 task/updated_at（让
@@ -680,8 +767,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         db.run(touchSql, touchParams);
       });
       logTaskEvent(id, null, "delivered", from_session, parentTaskId ? `→ ${targetAlias} (parent=${parentTaskId.slice(0,8)})` : `→ ${targetAlias}`);
-
-      const session = scopedSessionStatus(targetAlias, effectiveNetId);
+      // 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);
 
       // SSE push by alias.
       // The SSE channel is keyed by alias (subscribers connected to /events/<alias>),
@@ -694,7 +783,28 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       let pendingSql = "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
       pendingSql = addScope(pendingSql, pendingParams, effectiveNetId);
       const pending = db.get<{ cnt: number }>(pendingSql, ...pendingParams);
-      pushEvent(targetAlias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority, from: from_session, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
+      if (target.state === "online") {
+        pushEvent(targetAlias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority, from: from_session, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
+      }
+
+      if (target.state === "offline") {
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              ok: false,
+              error: "alias_offline",
+              message: target.message,
+              alias: targetAlias,
+              queued: true,
+              task_id: id,
+              message_id: id,
+              session_status: target.session.status ?? "offline",
+              ...(canonical.renamed ? { renamed_from: alias, renamed_to: targetAlias } : {}),
+            }),
+          }],
+        };
+      }
 
       return {
         content: [
@@ -704,7 +814,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
               ok: true,
               message_id: id,
               ...(canonical.renamed ? { renamed_from: alias, renamed_to: targetAlias } : {}),
-              session_status: session?.status ?? "unknown",
+              session_status: target.session?.status ?? "unknown",
             }),
           },
         ],
@@ -723,6 +833,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     async ({ alias, message, from_session: _fromIn }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
       const effectiveNetId = getNetworkId(null);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
+      const target = resolveDeliveryTarget(alias, effectiveNetId);
+      if (target.state === "not_found") return deliveryTargetReply(target)!;
       console.log(`[${ts()}] ${from_session} → send_message → ${alias}: ${message.slice(0, 60)}`);
       const id = uuidv4();
       db.run(
@@ -731,9 +843,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         [id, alias, message, from_session, effectiveNetId ?? null]
       );
 
-      const session = scopedSessionStatus(alias, effectiveNetId);
+      if (target.state === "online") {
+        pushEvent(alias, { type: "new_message", from: from_session, message_id: id }, effectiveNetId);
+      }
 
-      pushEvent(alias, { type: "new_message", from: from_session, message_id: id }, effectiveNetId);
+      const offlineReply = deliveryTargetReply(target, { message_id: id });
+      if (offlineReply) return offlineReply;
 
       return {
         content: [
@@ -742,7 +857,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             text: JSON.stringify({
               ok: true,
               message_id: id,
-              session_status: session?.status ?? "unknown",
+              session_status: target.session?.status ?? "unknown",
             }),
           },
         ],
@@ -766,6 +881,42 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
       console.log(`[${ts()}] ${from_session} → send_reply (${replyStatus}) → ${alias}: ${text.slice(0, 60)}`);
       const id = uuidv4();
+      let taskBefore: { status: string } | null = null;
+      if (in_reply_to) {
+        const taskParams: any[] = [in_reply_to];
+        let taskSql = "SELECT status FROM tasks WHERE task_id = ?1";
+        taskSql = addScope(taskSql, taskParams, effectiveNetId);
+        taskBefore = db.get<{ status: string }>(taskSql, ...taskParams) ?? null;
+        if (!taskBefore) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify({
+                ok: false,
+                error: "reply_task_not_found",
+                message: `cannot apply reply: task not found (${in_reply_to})`,
+                in_reply_to,
+                reply_queued: false,
+              }),
+            }],
+          };
+        }
+        if (!["created", "delivered", "acked", "running"].includes(taskBefore.status)) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify({
+                ok: false,
+                error: "reply_task_terminal",
+                message: `cannot apply reply: task is already terminal (${taskBefore.status})`,
+                in_reply_to,
+                task_status: taskBefore.status,
+                reply_queued: false,
+              }),
+            }],
+          };
+        }
+      }
       const replyLogged = db.transaction(() => {
         db.run(
           `INSERT INTO inbox (id, session_name, type, priority, content, from_session, in_reply_to, requires_response, network_id)
@@ -789,6 +940,21 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         return false;
       });
 
+      if (in_reply_to && !replyLogged) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              ok: false,
+              error: "reply_not_applied",
+              message: "reply was not applied to task",
+              in_reply_to,
+              reply_queued: false,
+            }),
+          }],
+        };
+      }
+
       // Log event after commit (outside transaction)
       if (replyLogged && in_reply_to) logTaskEvent(in_reply_to, null, replyStatus, from_session, text.slice(0, 200));