@sleep2agi/commhub-server 0.9.0-preview.29 → 0.9.0-preview.30

package/src/task-consumption.test.ts

@@ -18,6 +18,7 @@ function cleanup() {
   try { db.run("DELETE FROM network_members WHERE network_id = ?1", [NET]); } catch {}
   try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET]); } catch {}
   try { db.run("DELETE FROM users WHERE user_id = ?1", [USER]); } catch {}
+  try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [NET]); } catch {}
 }
 
 function seed() {
@@ -29,6 +30,10 @@ function seed() {
       "INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state) VALUES (?1, ?2, ?2, ?3, 'host', datetime('now'), datetime('now'), 'active')",
       [`id_${alias}`, alias, NET],
     );
+    db.run(
+      "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, bound_node_id) VALUES (?1, ?1, ?2, ?3, ?4, ?5)",
+      [`token_${alias}`, USER, NET, alias, `id_${alias}`],
+    );
     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_${alias}`, alias, `id_${alias}`, NET],
@@ -91,6 +96,70 @@ beforeEach(() => { cleanup(); seed(); });
 afterAll(cleanup);
 
 describe("task consumed_at identity and lifecycle", () => {
+  test("immutable node cursor paginates beyond 100 without alias or cross-node leakage", async () => {
+    for (let i = 0; i < 125; i++) {
+      db.run(
+        `INSERT INTO tasks (task_id, from_node_id, from_name, to_name, status, content, network_id, created_at)
+         VALUES (?1, ?2, ?3, ?4, 'replied', 'x', ?5, ?6)`,
+        [`page-${String(i).padStart(3, "0")}`, `id_${NODE_A}`, i < 60 ? "old-alias" : NODE_A, NODE_B, NET, `2026-01-01 00:${String(Math.floor(i / 60)).padStart(2, "0")}:${String(i % 60).padStart(2, "0")}`],
+      );
+    }
+    db.run(
+      `INSERT INTO tasks (task_id, from_node_id, from_name, to_name, status, content, network_id)
+       VALUES ('foreign-node-row', ?1, ?2, ?3, 'replied', 'x', ?4)`,
+      [`id_${NODE_B}`, NODE_A, NODE_A, NET],
+    );
+    const handler = toolsFor({ alias: NODE_A, nodeToken: true }).list_tasks;
+    const first = await call(handler, { from_node_id: `id_${NODE_A}`, durable_cursor: true, limit: 100 });
+    expect(first.capability).toBe("list_tasks.immutable-node-cursor.v1");
+    expect(first.tasks).toHaveLength(100);
+    const second = await call(handler, { from_node_id: `id_${NODE_A}`, durable_cursor: true, limit: 100, ...first.next_cursor });
+    expect(second.tasks).toHaveLength(25);
+    expect(new Set([...first.tasks, ...second.tasks].map((task: any) => task.task_id)).size).toBe(125);
+    expect([...first.tasks, ...second.tasks].some((task: any) => task.task_id === "foreign-node-row")).toBe(false);
+    expect((await call(handler, { from_node_id: `id_${NODE_B}`, durable_cursor: true, limit: 100 })).error).toBe("from_node_id_identity_mismatch");
+  });
+  test("terminal sequence paginates beyond 2000 and admits late completion of an old task", async () => {
+    db.run(
+      `INSERT INTO tasks (task_id, from_node_id, from_name, to_name, status, content, network_id, created_at)
+       VALUES ('old-open-task', ?1, 'renamed-sender', ?2, 'running', 'late', ?3, '2020-01-01 00:00:00')`,
+      [`id_${NODE_A}`, NODE_B, NET],
+    );
+    for (let i = 0; i < 2_001; i++) {
+      db.run(
+        `INSERT INTO tasks (task_id, from_node_id, from_name, to_name, status, content, network_id, created_at, completed_at)
+         VALUES (?1, ?2, ?3, ?4, 'replied', 'x', ?5, ?6, datetime('now'))`,
+        [`terminal-page-${String(i).padStart(4, "0")}`, `id_${NODE_A}`, i < 1_000 ? "old-alias" : NODE_A, NODE_B, NET, `2026-01-01 00:00:${String(i % 60).padStart(2, "0")}`],
+      );
+    }
+    db.run(
+      `INSERT INTO tasks (task_id, from_node_id, from_name, to_name, status, content, network_id)
+       VALUES ('terminal-cross-network', ?1, ?2, ?3, 'replied', 'x', 'other-network')`,
+      [`id_${NODE_A}`, NODE_A, NODE_B],
+    );
+    const handler = toolsFor({ alias: NODE_A, nodeToken: true }).list_tasks;
+    let after = 0;
+    const ids: string[] = [];
+    for (let page = 0; page < 30; page++) {
+      const response = await call(handler, {
+        from_node_id: `id_${NODE_A}`, durable_cursor: true, durable_terminal_cursor: true,
+        after_terminal_seq: after, limit: 100,
+      });
+      expect(response.capability).toBe("list_tasks.immutable-terminal-sequence.v2");
+      ids.push(...response.tasks.map((task: any) => task.task_id));
+      after = response.next_terminal_seq;
+      if (!response.has_more) break;
+    }
+    expect(ids).toHaveLength(2_001);
+    expect(new Set(ids).size).toBe(2_001);
+    expect(ids).not.toContain("terminal-cross-network");
+    db.run("UPDATE tasks SET status = 'failed', completed_at = datetime('now') WHERE task_id = 'old-open-task'");
+    const late = await call(handler, {
+      from_node_id: `id_${NODE_A}`, durable_cursor: true, durable_terminal_cursor: true,
+      after_terminal_seq: after, limit: 100,
+    });
+    expect(late.tasks.map((task: any) => task.task_id)).toEqual(["old-open-task"]);
+  }, 20_000);
   test("enqueue and process-level ack keep consumed_at null", async () => {
     const content = "connected process has not started a model turn";
     const before = db.get<{ last_seen_at: string; task: string | null }>(

package/src/task-diagnostic.test.ts

@@ -69,10 +69,43 @@ describe("#166 evidence-only task diagnostics", () => {
         live_sse_connections: 1,
         runtime_submitted: false,
         runtime_consumed: false,
+        // 🔴 #1083 新增。这里保持 toEqual（整形断言）而**不**退化成 toMatchObject ——
+        //    隔壁那条测试的名字就是 "without widening the evidence"，
+        //    这个严格性是故意的：它防的正是「有人往 evidence 里悄悄加字段」。
+        //    加宽了就把新字段写进来，不是把断言放松。
+        target_ever_reported_runtime_evidence: null,
       },
     });
   });
 
+  // 🔴 #1083：【时序】与【能力】必须落在不同的 code 上。
+  //    实测背景：一个**确实回了长信**的任务与一个**毫无回音**的任务，
+  //    在旧实现下 diagnostic 逐字相同（都是 lifecycle_progress_without_runtime_evidence
+  //    + inspect_runtime）⇒ 鉴别力 = 0。
+  test("a target that never reported runtime evidence gets its own code, not inspect_runtime", () => {
+    const d = diagnoseTask(base({ status: "acked", targetEverReportedRuntimeEvidence: false }));
+    expect(d.code).toBe("runtime_evidence_channel_absent");
+    expect(d.action_hint).toBe("wire_runtime_evidence");
+    expect(d.evidence.target_ever_reported_runtime_evidence).toBe(false);
+  });
+
+  test("a target that HAS reported evidence before keeps the timing-flavoured code", () => {
+    const d = diagnoseTask(base({ status: "acked", targetEverReportedRuntimeEvidence: true }));
+    expect(d.code).toBe("lifecycle_progress_without_runtime_evidence");
+    expect(d.action_hint).toBe("inspect_runtime");
+  });
+
+  // 「Hub 没算这一项」不等于「没报过」—— 不知道就不改判。
+  test("an unknown capability (null / omitted) does not change the old verdict", () => {
+    const omitted = diagnoseTask(base({ status: "acked" }));
+    const explicitNull = diagnoseTask(base({ status: "acked", targetEverReportedRuntimeEvidence: null }));
+    for (const d of [omitted, explicitNull]) {
+      expect(d.code).toBe("lifecycle_progress_without_runtime_evidence");
+      expect(d.action_hint).toBe("inspect_runtime");
+      expect(d.evidence.target_ever_reported_runtime_evidence).toBeNull();
+    }
+  });
+
   test("normalizes invalid SSE counts without widening the evidence", () => {
     expect(diagnoseTask(base({ liveSseConnections: Number.NaN }))).toMatchObject({
       code: "target_no_live_sse",

package/src/task-diagnostic.ts

@@ -8,6 +8,10 @@ export type TaskDiagnosticCode =
   | "target_session_offline"
   | "target_no_live_sse"
   | "lifecycle_progress_without_runtime_evidence"
+  // 🔴 #1083：与上一条的区别是【时序】vs【能力】。上一条说的是「还没走到那一步」，
+  //    这一条说的是「这个目标从来没有报过任何一次运行时证据」——它不会走到。
+  //    两者处置相反：前者【等】，后者【别等，去接线】。
+  | "runtime_evidence_channel_absent"
   | "delivered_waiting_for_agent";
 
 export type TaskDiagnosticAction =
@@ -16,7 +20,8 @@ export type TaskDiagnosticAction =
   | "check_target_registration"
   | "restore_target"
   | "restore_sse"
-  | "inspect_agent_queue";
+  | "inspect_agent_queue"
+  | "wire_runtime_evidence";
 
 export interface TaskDiagnosticInput {
   status: string;
@@ -25,6 +30,18 @@ export interface TaskDiagnosticInput {
   targetSessionStatus: string | null;
   targetSessionExists: boolean;
   liveSseConnections: number;
+  /**
+   * 🔴 #1083：这个目标节点【历史上是否报过任何一次】运行时证据。
+   * `false` = 从来没报过 ⇒ `runtime_submitted_at`/`consumed_at` 为空**推不出**「没消费」，
+   *           它只说明这条证据通道不存在。
+   * `null`/省略 = Hub 没算这一项 ⇒ 保持旧行为（不因为「不知道」就改判）。
+   *
+   * 背景：RFC-035 §75 要求 agent-node 接线上报，但 agent 侧至今没有实现
+   * （`grep -rn runtime_evidence agent-node/src/ agent-network/src/` = 0 命中），
+   * 于是这两列对所有任务恒为 NULL。实测后果：一个**确实回了长信**的任务
+   * 与一个**毫无回音**的任务，diagnostic 读数逐字相同 ⇒ 鉴别力 = 0。
+   */
+  targetEverReportedRuntimeEvidence?: boolean | null;
 }
 
 export interface TaskDiagnostic {
@@ -37,6 +54,8 @@ export interface TaskDiagnostic {
     live_sse_connections: number;
     runtime_submitted: boolean;
     runtime_consumed: boolean;
+    /** `null` = Hub 没算这一项；`false` = 该目标从来没报过运行时证据。 */
+    target_ever_reported_runtime_evidence: boolean | null;
   };
 }
 
@@ -55,6 +74,8 @@ export function diagnoseTask(input: TaskDiagnosticInput): TaskDiagnostic {
     live_sse_connections: liveSseConnections,
     runtime_submitted: Boolean(input.runtimeSubmittedAt),
     runtime_consumed: Boolean(input.consumedAt),
+    target_ever_reported_runtime_evidence:
+      input.targetEverReportedRuntimeEvidence ?? null,
   };
 
   let code: TaskDiagnosticCode;
@@ -78,8 +99,16 @@ export function diagnoseTask(input: TaskDiagnosticInput): TaskDiagnostic {
     code = "target_no_live_sse";
     action_hint = "restore_sse";
   } else if (input.status === "acked" || input.status === "running") {
-    code = "lifecycle_progress_without_runtime_evidence";
-    action_hint = "inspect_runtime";
+    // 🔴 #1083：这里原本只有一档，于是【还没走到】和【不会走到】共用同一个 code
+    //    和同一个 action_hint(`inspect_runtime`)。后者被支去查一个没坏的东西。
+    //    只有在 Hub **确知**该目标从未报过证据时才改判；`null`(没算) 保持旧行为。
+    if (input.targetEverReportedRuntimeEvidence === false) {
+      code = "runtime_evidence_channel_absent";
+      action_hint = "wire_runtime_evidence";
+    } else {
+      code = "lifecycle_progress_without_runtime_evidence";
+      action_hint = "inspect_runtime";
+    }
   } else {
     code = "delivered_waiting_for_agent";
     action_hint = "inspect_agent_queue";

package/src/task-idempotency-mcp.test.ts

@@ -114,6 +114,11 @@ describe("send_task durable idempotency", () => {
       task_id: first.message_id,
       task_status: "delivered",
       idempotent_replay: true,
+      actual_to: {
+        alias: TARGET,
+        to_node_id: "id_node_chat_idem",
+        network_id: NET,
+      },
     });
     expect(db.get<{ count: number }>("SELECT COUNT(*) AS count FROM tasks WHERE network_id = ?1", [NET])?.count).toBe(1);
     expect(db.get<{ count: number }>("SELECT COUNT(*) AS count FROM inbox WHERE network_id = ?1", [NET])?.count).toBe(1);

package/src/task-lifecycle-watcher.test.ts

@@ -45,6 +45,26 @@ afterAll(() => {
   try { server?.stop(true); } catch {}
 });
 
+/**
+ * 轮询到 `ready()` 为真,或到期抛错。
+ *
+ * 定长 sleep 的问题不是「慢」,是**报错报在错的层**:超时之后测试红在
+ * 「事件没写」这条断言上,读的人会去查 watcher,而真实原因可能是子进程
+ * 还没起来。这里到期时把那句话直接说出来。
+ */
+async function waitUntil(ready: () => boolean, timeoutMs: number, what: string | null): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (ready()) return;
+    if (Date.now() >= deadline) {
+      // what === null:到期本身就是期望结果(调用方随后自己断言),不抛。
+      if (what === null) return;
+      throw new Error(`timed out after ${timeoutMs}ms: ${what}`);
+    }
+    await Bun.sleep(25);
+  }
+}
+
 describe("#167 Hub delivered-stale lifecycle watcher", () => {
   test("30s/60s thresholds are exact and non-delivered tasks stay silent", () => {
     const first = recordDeliveredStaleEvents(NOW);
@@ -132,12 +152,23 @@ describe("#167 Hub delivered-stale lifecycle watcher", () => {
       stdout: "pipe",
       stderr: "pipe",
     });
-    await Bun.sleep(800);
+    // 这里**不**等「hub 就绪」——因为没有一个只有 hub 起来了才成立的廉价判据:
+    // db 文件在上面那步 init 里就已经存在了,拿它当条件的话这个等待恒真,等于没等。
+    // 真正需要「hub 起来了」的是下面那条断言,而它已经改成轮询到目标状态,
+    // hub 起得慢只是让它多等几轮。
+    //
+    // 这一步保留的是原来那条断言的原意:**子进程没有立刻崩**。所以只给它一个
+    // 短窗口,并且如果它在窗口内退出就立刻停下来报错,不用把 800ms 睡满。
+    await waitUntil(() => child.exitCode !== null, 800, null);
     expect(child.exitCode).toBeNull();
 
     const taskId = "stale-live-wiring";
     const childDb = new Database(childDbPath);
     try {
+      // startHub may still be finishing its startup migration transaction even
+      // though the process has stayed alive. Wait for that short-lived writer
+      // instead of turning scheduler timing into an immediate SQLITE_BUSY.
+      childDb.exec("PRAGMA busy_timeout = 5000");
       childDb.run(
         `INSERT INTO tasks
            (task_id, from_name, to_name, status, content, delivered_at, network_id)
@@ -147,14 +178,23 @@ describe("#167 Hub delivered-stale lifecycle watcher", () => {
       expect(childDb.query<{ count: number }, [string]>(
         "SELECT COUNT(*) AS count FROM task_events WHERE task_id = ?1",
       ).get(taskId)!.count).toBe(0);
-      await Bun.sleep(3_200);
-      expect(childDb.query<{ count: number }, [string]>(
+      // 巡检周期是 COMMHUB_DELIVERED_STALE_PATROL_MS=25ms —— 事件在插入后
+      // 几十毫秒内就该出现。原来这里是定长 sleep(3_200),纯粹是余量:
+      // 4.0s 的 sleep 装在 bun 默认的 5.0s 单测预算里,只剩 1s 给两次进程启动。
+      // 实测在 CI 上被这一条打红过(#798 让这个文件第一次进 CI 才暴露)。
+      // 改成「轮询到目标状态,或到期报错」:常态下快 ~60 倍,慢的时候等得起。
+      const countStale = () => childDb.query<{ count: number }, [string]>(
         "SELECT COUNT(*) AS count FROM task_events WHERE task_id = ?1 AND event_type = 'task.warning.delivered_stale_30s'",
-      ).get(taskId)!.count).toBe(1);
+      ).get(taskId)!.count;
+      await waitUntil(() => countStale() === 1, 20_000,
+        "watcher did not write the delivered_stale_30s event");
+      expect(countStale()).toBe(1);
     } finally {
       childDb.close();
       try { child.kill("SIGTERM"); } catch {}
       await child.exited;
     }
-  });
+    // 🔴 显式超时:这一条要起两个真 bun 进程,bun 默认的 5s 对它不成立。
+    // 上面两处已改成轮询,常态用不到这个上限;它只保证「慢」不会被报成「坏」。
+  }, 30_000);
 });

package/src/tools.ts

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod/v4";
+import { parseAliasFilter } from "./alias-filter.js";
 import { createHash } from "node:crypto";
 import { db, uuidv4, logTaskEvent, chainReplyToParent, hashToken, generateId, generateNetworkToken, syncScheduledRunForTask } from "./db.js";
 import { getSSEStats, pushEvent, pushNetworkObserverEvent } from "./push.js";
@@ -363,6 +364,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     | { state: "offline"; alias: string; session: any; message: string }
     | { state: "not_found"; alias: string; message: string };
 
+  // Only call after the authenticated, network-scoped lookup resolved a
+  // concrete target. Error paths intentionally omit this identity object.
+  const actualTo = (target: Exclude<DeliveryTarget, { state: "not_found" }>, networkId?: string | null) => ({
+    alias: target.alias,
+    to_node_id: target.session?.node_id ?? null,
+    network_id: networkId ?? null,
+  });
+
   const scopedSessionStatus = (alias: string, networkId?: string | null) => {
     const params: any[] = [alias];
     let sql = "SELECT status, updated_at, last_seen_at, node_id FROM sessions WHERE alias = ?1";
@@ -1104,16 +1113,25 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "get_all_status",
-    "Get status of all sessions. Hub uses this for the patrol loop.",
+    "Get status of all sessions. Hub uses this for the patrol loop. " +
+      "Pass filter_alias (comma-separated) when you only care about specific " +
+      "nodes — the unfiltered result is one row per session with 31 columns and " +
+      "is large enough on a real fleet that callers cannot read it.",
     {
       filter_status: z.string().max(50).optional(),
       filter_server: z.string().max(200).optional(),
+      // 2026-08-17: on a 222-session hub the unfiltered response is ~259 KB, past
+      // what an MCP client can take in one result — so the caller that wanted the
+      // status of THREE nodes could not get it from this tool at all. The patrol
+      // loop still wants everything, hence optional rather than required.
+      filter_alias: z.string().max(2000).optional()
+        .describe("One alias, or several separated by commas. Exact matches only."),
       network_id: z.string().max(200).optional().describe("Filter by network"),
     },
-    async ({ filter_status, filter_server, network_id: netId }) => {
+    async ({ filter_status, filter_server, filter_alias, network_id: netId }) => {
       const readScope = resolveReadScope(netId);
       if (readScope.denied) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: readScope.denied }) }] };
-      console.log(`[${ts()}] hub → get_all_status${filter_status ? ": filter=" + filter_status : ""}${readScope.networkId ? " net=" + readScope.networkId.slice(0, 12) : ""}`);
+      console.log(`[${ts()}] hub → get_all_status${filter_status ? ": filter=" + filter_status : ""}${filter_alias ? " alias=" + filter_alias.slice(0, 80) : ""}${readScope.networkId ? " net=" + readScope.networkId.slice(0, 12) : ""}`);
 
       // Round-2/4 review ③: stale-marking moved to startStaleSessionSweeper()
       // (background timer, ~60s cadence). Read path no longer fires UPDATE.
@@ -1122,20 +1140,42 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       sql = addReadScope(sql, params, readScope);
       if (filter_status) { sql += " AND status = ?"; params.push(filter_status); }
       if (filter_server) { sql += " AND server = ?"; params.push(filter_server); }
+      const aliasFilter = parseAliasFilter(filter_alias);
+      const aliases = aliasFilter.aliases;
+      if (aliasFilter.sql) {
+        sql += aliasFilter.sql;
+        params.push(...aliases);
+      }
       sql += " ORDER BY updated_at DESC";
       const sessions = db.all(sql, ...params);
 
+      // `summary` has always counted every session in the read scope, ignoring
+      // filter_status / filter_server — and now filter_alias. That is fine for
+      // the patrol loop, but a caller who asked about three aliases and gets
+      // back three rows plus "idle: 96" can easily read the 96 as being about
+      // their three. A count that does not say what it counted invites exactly
+      // that. So the response now says so, rather than the semantics changing
+      // under existing callers.
       const summaryParams: any[] = [];
       let summarySql = "SELECT status, COUNT(*) as count FROM sessions WHERE 1=1";
       summarySql = addReadScope(summarySql, summaryParams, readScope);
       summarySql += " GROUP BY status";
       const summary = db.all(summarySql, ...summaryParams);
 
+      const filtered = !!(filter_status || filter_server || aliases.length > 0);
       return {
         content: [
           {
             type: "text" as const,
-            text: JSON.stringify({ ok: true, sessions, summary }),
+            text: JSON.stringify({
+              ok: true,
+              sessions,
+              summary,
+              summary_scope: filtered
+                ? "every session in the read scope — NOT narrowed by the filters applied to `sessions`"
+                : "every session in the read scope",
+              sessions_returned: sessions.length,
+            }),
           },
         ],
       };
@@ -1283,8 +1323,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         ? idempotentTaskId(effectiveNetId ?? null, from_session, clientRequestId)
         : uuidv4();
       if (clientRequestId) {
-        const existing = db.get<StoredIdempotentTask>(
-          "SELECT task_id, from_name, to_name, priority, content, network_id, meta_json, status FROM tasks WHERE task_id = ?1",
+        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) {
@@ -1300,6 +1340,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           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,
+            // A replay acknowledges the already-persisted dispatch. Use that
+            // row rather than today's session record so alias reuse or a
+            // restarted process cannot rewrite historical recipient identity.
+            actual_to: {
+              alias: existing.to_name,
+              to_node_id: existing.to_node_id ?? null,
+              network_id: existing.network_id ?? null,
+            },
           }) }] };
         }
       }
@@ -1333,6 +1381,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: ${task.slice(0, 60)}${priority === "high" ? " [HIGH]" : ""}${canonical.renamed ? ` [renamed from ${alias}]` : ""}`);
       const fromNodeId = resolveNodeIdForAlias(from_session, effectiveNetId);
       const targetNodeId = target.session?.node_id ?? null;
+      const resolvedActualTo = actualTo(target, effectiveNetId);
       // 事务：inbox + tasks 双写 + 触碰目标 session 的 task/updated_at（让
       // dashboard 在派任务一刻就反映出"任务已下发"，不再等 agent 的
       // report_status 心跳；status 字段交给 agent，避免与 working/idle
@@ -1390,6 +1439,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
               task_id: id,
               message_id: id,
               session_status: target.session.status ?? "offline",
+              actual_to: resolvedActualTo,
               ...(canonical.renamed ? { renamed_from: alias, renamed_to: targetAlias } : {}),
             }),
           }],
@@ -1403,6 +1453,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             text: JSON.stringify({
               ok: true,
               message_id: id,
+              actual_to: resolvedActualTo,
               ...(canonical.renamed ? { renamed_from: alias, renamed_to: targetAlias } : {}),
               session_status: target.session?.status ?? "unknown",
             }),
@@ -1908,11 +1959,52 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       from_name: z.string().max(200).optional().describe("Filter by sender"),
       from_node_id: z.string().max(200).optional().describe("Filter by immutable sender node_id"),
       network_id: z.string().max(200).optional().describe("Filter by network"),
+      before_created_at: z.string().max(64).optional().describe("Pagination cursor timestamp"),
+      before_task_id: z.string().max(200).optional().describe("Pagination cursor task id"),
+      durable_cursor: z.boolean().optional().describe("Require immutable node-scoped cursor protocol"),
+      durable_terminal_cursor: z.boolean().optional().describe("Read terminal outbound journal in monotonic order"),
+      after_terminal_seq: z.number().int().min(0).optional().describe("Exclusive terminal journal watermark"),
       limit: z.number().min(1).max(100).optional().default(20),
     },
-    async ({ alias, status, from_name, from_node_id, network_id: netId, limit }) => {
+    async ({ alias, status, from_name, from_node_id, network_id: netId, before_created_at, before_task_id, durable_cursor, durable_terminal_cursor, after_terminal_seq, limit }) => {
       const readScope = resolveReadScope(netId);
       if (readScope.denied) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: readScope.denied }) }] };
+      if (durable_cursor) {
+        if (!callerTokenIsNetwork) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "node_token_required" }) }] };
+        const boundNodeId = callerTokenId && enforceNetworkId
+          ? db.get<{ bound_node_id: string | null }>(
+              "SELECT bound_node_id FROM api_tokens WHERE token_id = ?1 AND network_id = ?2",
+              callerTokenId,
+              enforceNetworkId,
+            )?.bound_node_id ?? null
+          : null;
+        if (!boundNodeId || from_node_id !== boundNodeId) {
+          return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "from_node_id_identity_mismatch" }) }] };
+        }
+      }
+      if (durable_terminal_cursor) {
+        if (!durable_cursor) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "durable_cursor_required" }) }] };
+        const params: any[] = [enforceNetworkId, from_node_id, after_terminal_seq ?? 0, limit];
+        const tasks = db.all(
+          `SELECT t.task_id, t.from_node_id, t.from_name, t.to_node_id, t.to_name, t.priority,
+                  t.status, t.content, t.result, t.created_at, t.runtime_submitted_at,
+                  t.consumed_at, t.completed_at, e.terminal_seq
+             FROM task_terminal_events e
+             JOIN tasks t ON t.task_id = e.task_id
+            WHERE COALESCE(e.network_id, 'default') = COALESCE(?1, 'default')
+              AND e.from_node_id = ?2 AND e.terminal_seq > ?3
+            ORDER BY e.terminal_seq ASC LIMIT ?4`,
+          ...params,
+        );
+        return { content: [{ type: "text" as const, text: JSON.stringify({
+          ok: true,
+          capability: "list_tasks.immutable-terminal-sequence.v2",
+          tasks,
+          count: tasks.length,
+          next_terminal_seq: tasks.length ? tasks[tasks.length - 1]?.terminal_seq : (after_terminal_seq ?? 0),
+          has_more: tasks.length === limit,
+        }) }] };
+      }
       let sql = "SELECT task_id, from_node_id, from_name, to_node_id, to_name, priority, status, content, result, created_at, runtime_submitted_at, consumed_at, completed_at FROM tasks WHERE 1=1";
       const params: any[] = [];
       sql = addReadScope(sql, params, readScope);
@@ -1920,7 +2012,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (status) { sql += ` AND status = ?${params.length + 1}`; params.push(status); }
       if (from_name) { sql += ` AND from_name = ?${params.length + 1}`; params.push(from_name); }
       if (from_node_id) { sql += ` AND from_node_id = ?${params.length + 1}`; params.push(from_node_id); }
-      sql += ` ORDER BY created_at DESC LIMIT ?${params.length + 1}`;
+      if (before_created_at && before_task_id) {
+        sql += ` AND (created_at < ?${params.length + 1} OR (created_at = ?${params.length + 1} AND task_id < ?${params.length + 2}))`;
+        params.push(before_created_at, before_task_id);
+      }
+      sql += ` ORDER BY created_at DESC, task_id DESC LIMIT ?${params.length + 1}`;
       params.push(limit);
       const tasks = db.all(sql, ...params);
 
@@ -1934,7 +2030,17 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       return {
         content: [{
           type: "text" as const,
-          text: JSON.stringify({ ok: true, tasks, count: tasks.length, stats }),
+          text: JSON.stringify({
+            ok: true,
+            ...(durable_cursor ? { capability: "list_tasks.immutable-node-cursor.v1" } : {}),
+            tasks,
+            count: tasks.length,
+            next_cursor: tasks.length === limit ? {
+              before_created_at: tasks[tasks.length - 1]?.created_at,
+              before_task_id: tasks[tasks.length - 1]?.task_id,
+            } : null,
+            stats,
+          }),
         }],
       };
     }