@sleep2agi/commhub-server 0.9.0-preview.157 → 0.9.0-preview.158

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.157",
+  "version": "0.9.0-preview.158",
   "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/api-nodes-shape.test.ts

@@ -36,10 +36,25 @@ afterAll(() => {
 // the dashboard / external clients see.
 function mapRow(r: Record<string, unknown>): Record<string, unknown> {
   let role: string | null = null;
+  // #2293 —— 与 handler 同一套读法：快照可能是文本或对象；解析失败/形状不对 = 这一格没有。
+  let opencodeCatalog: string[] | null = null;
+  let opencodeGeneration: "v1" | "v2" | null = null;
+  let opencodeMode: string | null = null;
+  let opencodeServer: string | null = null;
   const snap = r.config_snapshot;
   if (snap) {
-    try { role = (typeof snap === "string" ? JSON.parse(snap) : snap)?.role ?? null; }
-    catch { /* malformed */ }
+    let parsed: any = null;
+    try { parsed = typeof snap === "string" ? JSON.parse(snap) : snap; }
+    catch { parsed = null; }
+    role = parsed?.role ?? null;
+    const raw = parsed?.opencode_catalog;
+    if (Array.isArray(raw) && raw.every((m: unknown) => typeof m === "string" && m.length <= 400)) {
+      opencodeCatalog = raw.slice(0, 400);
+    }
+    const flags = parsed?.flags;
+    if (flags?.opencodeGeneration === "v1" || flags?.opencodeGeneration === "v2") opencodeGeneration = flags.opencodeGeneration;
+    if (typeof flags?.opencodeMode === "string" && flags.opencodeMode.length <= 32) opencodeMode = flags.opencodeMode;
+    if (typeof parsed?.opencode_server === "string" && parsed.opencode_server.length <= 200) opencodeServer = parsed.opencode_server;
   }
   const { config_snapshot, ...rest } = r;
   return {
@@ -47,6 +62,10 @@ function mapRow(r: Record<string, unknown>): Record<string, unknown> {
     tags: parseStoredTags(r.tags),
     attrs_revision: Number(r.attrs_revision ?? 0),
     role,
+    opencode_catalog: opencodeCatalog,
+    opencode_generation: opencodeGeneration,
+    opencode_mode: opencodeMode,
+    opencode_server: opencodeServer,
   };
 }
 
@@ -83,7 +102,7 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     // Expected fields present (13 = 12 contract + new role)
     for (const k of ["node_id", "node_name", "alias", "runtime", "model",
                      "config_path", "channels", "server", "hostname",
-                     "network_id", "created_at", "updated_at", "role"]) {
+                     "network_id", "created_at", "updated_at", "role", "opencode_catalog"]) {
       expect(row).toHaveProperty(k);
     }
     // Internal fields NOT present
@@ -100,7 +119,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     expect(Object.keys(row).sort()).toEqual([
       "alias", "attrs_revision", "channels", "config_path", "created_at",
       "display_name", "hostname", "model", "network_id", "node_id",
-      "node_name", "role", "runtime", "server", "tags", "team",
+      "node_name", "opencode_catalog", "opencode_generation", "opencode_mode",
+      "opencode_server", "role", "runtime", "server", "tags", "team",
       "updated_at",
     ]);
   });
@@ -186,3 +206,74 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     expect(cfgRow?.config_snapshot).toContain("claude-opus");
   });
 });
+
+// #2293（admin 2026-10-25）—— 节点自报的模型清单必须能到 /api/nodes：
+// 「没有 daemon 绑定」的节点，客户端就是靠这一格给建议列表（否则只能手填）。
+describe("#2293 opencode_catalog projection", () => {
+  const insert = (snapshot: unknown) => db.run(
+    `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, config_snapshot)
+     VALUES (?1, ?2, ?3, ?4, ?5)`,
+    [TEST_NODE, "test-shape", "test-shape", TEST_NETWORK, typeof snapshot === "string" ? snapshot : JSON.stringify(snapshot)],
+  );
+  const read = () => mapRow(db.get<Record<string, unknown>>(
+    `SELECT node_id, node_name, alias, network_id, config_snapshot FROM nodes WHERE node_id = ?1`,
+    TEST_NODE,
+  )!);
+
+  test("valid list reaches the row, order kept", () => {
+    insert({ opencode_catalog: ["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"] });
+    expect(read().opencode_catalog).toEqual(["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"]);
+  });
+
+  test("absent / malformed / wrong shape → null, row still served", () => {
+    insert({ model: "x" });
+    expect(read().opencode_catalog).toBeNull();
+    insert("not-json{");
+    expect(read().opencode_catalog).toBeNull();
+    // 混了非字符串 → 整格作废（不猜、不部分展示）
+    insert({ opencode_catalog: ["a/b", 7] });
+    expect(read().opencode_catalog).toBeNull();
+    // 空列表是合法但无意义 → 照原样给出（客户端自己判断要不要建列表）
+    insert({ opencode_catalog: [] });
+    expect(read().opencode_catalog).toEqual([]);
+  });
+});
+
+// #2293（PR #1092 在真机上拿不到值的原因）—— /api/nodes 不带整个 config_snapshot，
+// 但「Runtime · V2」「OpenCode Server」两行只要三个标量：代际、模式、loopback 端点。
+describe("#2293 opencode_* scalars", () => {
+  test("generation / mode / server come from the snapshot, nothing else leaks", () => {
+    db.run(
+      `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, config_snapshot)
+       VALUES (?1, ?2, ?3, ?4, ?5)`,
+      [TEST_NODE, "test-shape", "test-shape", TEST_NETWORK, JSON.stringify({
+        flags: { opencodeGeneration: "v2", opencodeMode: "copresence", secretOther: "must-not-leak" },
+        opencode_server: "http://127.0.0.1:4096",
+      })],
+    );
+    const row = mapRow(db.get<Record<string, unknown>>(
+      `SELECT node_id, node_name, alias, network_id, config_snapshot FROM nodes WHERE node_id = ?1`,
+      TEST_NODE,
+    )!);
+    expect(row.opencode_generation).toBe("v2");
+    expect(row.opencode_mode).toBe("copresence");
+    expect(row.opencode_server).toBe("http://127.0.0.1:4096");
+    expect(row).not.toHaveProperty("config_snapshot");
+    expect(JSON.stringify(row)).not.toContain("must-not-leak");
+  });
+
+  test("unknown generation / absent fields → null (old nodes keep rendering)", () => {
+    db.run(
+      `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, config_snapshot)
+       VALUES (?1, ?2, ?3, ?4, ?5)`,
+      [TEST_NODE, "test-shape", "test-shape", TEST_NETWORK, JSON.stringify({ flags: { opencodeGeneration: "v9" } })],
+    );
+    const row = mapRow(db.get<Record<string, unknown>>(
+      `SELECT node_id, node_name, alias, network_id, config_snapshot FROM nodes WHERE node_id = ?1`,
+      TEST_NODE,
+    )!);
+    expect(row.opencode_generation).toBeNull();
+    expect(row.opencode_mode).toBeNull();
+    expect(row.opencode_server).toBeNull();
+  });
+});

package/src/node-attrs.test.ts

@@ -215,3 +215,44 @@ describe("node display attrs — auth + scope", () => {
     expect(r.status).toBe(404);
   });
 });
+
+// #2293（admin 2026-10-25）—— 走**真正**的 HTTP，不镜像 handler：
+// 客户端「Runtime · V2」「OpenCode Server」和「模型可选列表」要的三样东西
+// （代际 / 模式 / loopback 端点）与「这台机器上报的模型 id 清单」都在 /api/nodes 上，
+// 而整个 config_snapshot 仍然不外泄（终端 #312 的约定）。
+describe("#2293 opencode bits on GET /api/nodes (real HTTP)", () => {
+  const OC_NODE = "node_attrs_opencode";
+  const OC_ALIAS = "attrs-opencode-node";
+
+  test("generation / mode / server / catalog are projected; config_snapshot is not", async () => {
+    db.run(`DELETE FROM nodes WHERE node_id = ?1`, [OC_NODE]);
+    db.run(
+      `INSERT INTO nodes (node_id, node_name, alias, runtime, model, network_id, config_snapshot)
+       VALUES (?1, 'attrs-oc', ?2, 'opencode-sdk', 'deepseek/deepseek-flash', ?3, ?4)`,
+      [OC_NODE, OC_ALIAS, NET, JSON.stringify({
+        model: "deepseek/deepseek-flash",
+        flags: { opencodeGeneration: "v2", opencodeMode: "copresence", daemonSideSecret: "must-not-leak" },
+        opencode_server: "http://127.0.0.1:4096",
+        opencode_catalog: ["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"],
+      })],
+    );
+    const row = (await listNodes()).find((r) => r.node_id === OC_NODE)!;
+    expect(row).toBeDefined();
+    expect(row.opencode_generation).toBe("v2");
+    expect(row.opencode_mode).toBe("copresence");
+    expect(row.opencode_server).toBe("http://127.0.0.1:4096");
+    expect(row.opencode_catalog).toEqual(["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"]);
+    // 整个快照仍然不出现，且 flags 里的其它键不外泄。
+    expect(row).not.toHaveProperty("config_snapshot");
+    expect(JSON.stringify(row)).not.toContain("must-not-leak");
+    db.run(`DELETE FROM nodes WHERE node_id = ?1`, [OC_NODE]);
+  });
+
+  test("a node that never reported them reads as null / [] (old node, no invented values)", async () => {
+    const row = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    expect(row.opencode_generation ?? null).toBeNull();
+    expect(row.opencode_mode ?? null).toBeNull();
+    expect(row.opencode_server ?? null).toBeNull();
+    expect(row.opencode_catalog ?? null).toBeNull();
+  });
+});

package/src/opencode-catalog-report-http.test.ts

@@ -0,0 +1,139 @@
+// #2293（admin 2026-10-25）—— 从**节点的真实上报**一路走到 `/api/nodes` 的投影。
+//
+// 为什么这条要单独写：`api-nodes-shape.test.ts` 是**镜像 handler** 的（文件里自己声明会漂），
+// `node-attrs.test.ts` 是直接往库里塞一行快照。两者都没有走 `report_status` 的 zod schema ——
+// 而 schema 恰恰是「节点发了、Hub 上却什么都没有」最容易出事的地方（#1545：往非 strict 对象里
+// 加键会被静默丢弃）。这里用真 node 令牌 + 真 MCP `tools/call` + 真 `GET /api/nodes`。
+//
+// 断言三件事：
+//   1. `opencode_catalog` / `opencode_server` / flags 里的代际·模式，经 schema 后**落到库里**；
+//   2. `/api/nodes` 把它们投影出来，且**整个 config_snapshot 不外泄**；
+//   3. 形状不对（嵌对象、混非字符串）时**心跳照收**，只是这一格没有 —— 不许拒整份上报。
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-catalog-report-"));
+process.env.COMMHUB_DB ||= join(DIR, "commhub.db");
+
+const stamp = `${process.pid}_${Date.now()}`;
+const NET_ALIAS = `catalog-${stamp}`;
+let hub: any;
+let base = "";
+let adminToken = "";
+let nodeToken = "";
+let networkId = "";
+let nodeId = "";
+
+async function send(token: string, method: string, path: string, body?: unknown) {
+  const r = await fetch(`${base}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await r.text();
+  let json: any = null;
+  try { json = text ? JSON.parse(text) : null; } catch { /* MCP may answer as SSE */ }
+  return { status: r.status, body: json, text };
+}
+
+/** 真 MCP `tools/call report_status`，和 agent-node 心跳走同一条入参路径。 */
+async function reportStatus(snapshot: Record<string, unknown>) {
+  const r = await fetch(`${base}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${nodeToken}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+    body: JSON.stringify({
+      jsonrpc: "2.0", id: 1, method: "tools/call",
+      params: {
+        name: "report_status",
+        arguments: {
+          resume_id: `r_catalog_${stamp}`, alias: NET_ALIAS, status: "idle", node_id: nodeId,
+          runtime: "opencode-sdk",
+          config_snapshot: { model: "deepseek/deepseek-flash", ...snapshot },
+        },
+      },
+    }),
+  });
+  await r.text();
+  return r.status;
+}
+
+async function listNodes() {
+  const r = await send(adminToken, "GET", `/api/nodes?network_id=${networkId}`);
+  expect(r.status).toBe(200);
+  return (r.body?.nodes ?? []) as Array<Record<string, unknown>>;
+}
+
+beforeAll(async () => {
+  const admin = register(`catalog_admin_${stamp}`, "CatalogAdmin123!", undefined, "Catalog Admin");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  networkId = admin.network_id!;
+  const ownerId = admin.user!.user_id;
+  nodeId = `n_catalog_${stamp}`;
+  const minted = createNetworkTokenForNode(ownerId, networkId, NET_ALIAS, nodeId);
+  expect(minted.ok).toBe(true);
+  nodeToken = minted.token!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch { /* already down */ }
+  try { rmSync(DIR, { recursive: true, force: true }); } catch { /* best effort */ }
+});
+
+describe("#2293 node-reported OpenCode catalog reaches GET /api/nodes", () => {
+  test("a real report_status lands the catalog and the scalars on the node row", async () => {
+    expect(await reportStatus({
+      flags: { opencodeGeneration: "v2", opencodeMode: "copresence", daemonSideSecret: "must-not-leak" },
+      opencode_catalog: ["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"],
+      opencode_server: "http://127.0.0.1:4096",
+    })).toBe(200);
+
+    const stored = db.get<{ config_snapshot: string }>("SELECT config_snapshot FROM nodes WHERE node_id = ?1", nodeId)!;
+    expect(JSON.parse(stored.config_snapshot).opencode_catalog).toEqual([
+      "deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free",
+    ]);
+
+    const row = (await listNodes()).find(r => r.node_id === nodeId)!;
+    expect(row).toBeDefined();
+    expect(row.opencode_catalog).toEqual(["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"]);
+    expect(row.opencode_generation).toBe("v2");
+    expect(row.opencode_mode).toBe("copresence");
+    expect(row.opencode_server).toBe("http://127.0.0.1:4096");
+    // 整个快照仍然不出现在这一行里；flags 中的其它键也不外泄。
+    expect(row).not.toHaveProperty("config_snapshot");
+    expect(JSON.stringify(row)).not.toContain("must-not-leak");
+  });
+
+  test("a malformed catalog drops that field only — the heartbeat is still accepted", async () => {
+    expect(await reportStatus({
+      flags: { opencodeGeneration: "v2" },
+      // 嵌对象 + 混入数字：形状不对，schema 的 `.catch(undefined)` 应当只丢这一格。
+      opencode_catalog: { models: ["deepseek/deepseek-flash"] },
+      opencode_server: 12345,
+    })).toBe(200);
+
+    const row = (await listNodes()).find(r => r.node_id === nodeId)!;
+    expect(row).toBeDefined();
+    expect(row.opencode_catalog).toBeNull();
+    expect(row.opencode_server).toBeNull();
+    // 代际这一格仍然照常投影（没被同一条错误连带丢掉）。
+    expect(row.opencode_generation).toBe("v2");
+  });
+
+  test("a node that never reported the fields reads as null on every one of them", async () => {
+    const other = (await listNodes()).find(r => r.node_id !== nodeId);
+    if (!other) return; // 该网络里只有一个节点时无需断言（不是失败）
+    expect(other.opencode_catalog ?? null).toBeNull();
+    expect(other.opencode_generation ?? null).toBeNull();
+    expect(other.opencode_mode ?? null).toBeNull();
+    expect(other.opencode_server ?? null).toBeNull();
+  });
+});

package/src/scheduled-requirement-wake-http.test.ts

@@ -268,6 +268,12 @@ describe("#1279 authoritative scoped requirement-event wake over HTTP/MCP", () =
       expect({exit:code,stderr:w.stderr().trim().slice(0,800)}).toEqual({exit:0,stderr:""});
       results.push(JSON.parse(output.trim().split("\n").at(-1)!).wake);}
     expect(results.sort()).toEqual([false,true]);expect(state(scheduleId).revision).toBe(before.revision+1);expect(poll(scheduleId)).toBe(false);
-  });
+  // #2198:显式预算。这条用例要起 2 个 Node 子进程、各自打开同一个磁盘 SQLite,
+  // 再用 /tmp 上的 gate 文件对齐起跑。默认 5s 在机器繁忙时会被打满,而**超时与断言
+  // 失败在报告里长得一样**(都只是一行 (fail)):实测 8 路并发 + 3× CPU 超订时,
+  // 11 轮里有 2 轮红,但每次红的都是 `timed out after 5000ms`,而 trues 恒为 1、
+  // revision 恒只 +1 —— 语义一直是对的,是预算不够。
+  // 这里只放宽**时间**,不放宽任何断言(仍然 [false,true]、仍然 revision+1、仍然 poll false)。
+  }, 30_000);
 
 });

package/src/server.ts

@@ -5250,10 +5250,31 @@ return Bun.serve({
       const management = lifecycleUser ? lifecycleProjections(restScope) : null;
       const rows = rawRows.map(r => {
         let role: string | null = null;
+        // #2293（admin 2026-10-25）—— 节点自报的 OpenCode V2 模型 id 清单（`provider/model` 字符串数组）。
+        // 客户端在**没有 daemon 绑定**时用它当建议列表。读法同 role：快照可能是文本或对象；
+        // 解析失败/形状不对 = 这一格没有（null），不影响整行。
+        let opencodeCatalog: string[] | null = null;
+        let opencodeGeneration: "v1" | "v2" | null = null;
+        let opencodeMode: string | null = null;
+        let opencodeServer: string | null = null;
         const snap = r.config_snapshot;
         if (snap) {
-          try { role = (typeof snap === "string" ? JSON.parse(snap) : snap)?.role ?? null; }
-          catch { /* malformed snapshot — leave role null */ }
+          let parsed: any = null;
+          try { parsed = typeof snap === "string" ? JSON.parse(snap) : snap; }
+          catch { parsed = null; }
+          role = parsed?.role ?? null;
+          const raw = parsed?.opencode_catalog;
+          if (Array.isArray(raw) && raw.every((m: unknown) => typeof m === "string" && m.length <= 400)) {
+            opencodeCatalog = raw.slice(0, 400);
+          }
+          // #2293 —— 客户端「Runtime · V2」和「OpenCode Server」两行要的正是快照里这三格标量。
+          // PR #1092 之前从 `node.config_snapshot` 读，但这个端点**刻意不带整个快照**
+          // （见上方 #312 注释）⇒ 真机上两行是空的/整行不出现。这里只放三个标量出来，
+          // 仍不暴露 flags 里的其它内容，更不暴露任何凭据。
+          const flags = parsed?.flags;
+          if (flags?.opencodeGeneration === "v1" || flags?.opencodeGeneration === "v2") opencodeGeneration = flags.opencodeGeneration;
+          if (typeof flags?.opencodeMode === "string" && flags.opencodeMode.length <= 32) opencodeMode = flags.opencodeMode;
+          if (typeof parsed?.opencode_server === "string" && parsed.opencode_server.length <= 200) opencodeServer = parsed.opencode_server;
         }
         const { config_snapshot, owner_user_id, ...rest } = r;
         // `tags` is stored as JSON text; hand the dashboard a real array so
@@ -5269,6 +5290,10 @@ return Bun.serve({
           tags: parseStoredTags(r.tags),
           attrs_revision: Number(r.attrs_revision ?? 0),
           role,
+          opencode_catalog: opencodeCatalog,
+          opencode_generation: opencodeGeneration,
+          opencode_mode: opencodeMode,
+          opencode_server: opencodeServer,
           lifecycle_controllable,
           lifecycle_daemon_node_id: controllable.get(r.node_id) ?? null,
           ...(management ? (management.get(r.node_id) ?? { managed: "none", adoption: null }) : {}),

package/src/tools.ts

@@ -921,7 +921,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           revision: z.number().int().min(0).optional(),
         }).strict()).max(64),
         error: z.enum(["invalid_manifest", "unsafe_manifest", "read_failed"]).optional(),
-      }).strict().optional().describe("Bounded node-reported external schedule snapshot; never includes host paths or commands"),
+      }).strict().optional().describe("Node-reported schedules; never includes host paths or commands"),
       // RFC-024 B6 — masked snapshot of the node's effective config
       // (model + 6 dashboard-editable flags). Secrets ARE NOT in this
       // shape (env._envRef stays on host); the dashboard reads this
@@ -934,6 +934,16 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         model: z.string().max(200).optional().nullable(),
         flags: z.record(z.string(), z.unknown()).optional(),
         config_revision: z.number().int().min(0).optional(),
+        // #2293（admin 2026-10-25）—— 节点自己上报的 OpenCode V2 模型 id 清单
+        // （`provider/model`）。没有 daemon 绑定的节点靠这一格给客户端可选列表，
+        // 否则 admin 只能手填。只收 id：名字/设置/headers 可能带凭据，一律不收。
+        // 排成**一个字符串数组**而不是对象，是为了不抬 tools/list 的字节上限
+        // （约定见 tool-audience-http.test.ts：加字段先砍描述或合并，别改那三个数）。
+        // `.catch(undefined)`：形状不对只丢这一格，绝不拒掉整份心跳。
+        opencode_catalog: z.array(z.string()).max(400).optional().catch(undefined),
+        // #2293 —— 这台机器上 OpenCode serve 的 loopback 端点（`http://127.0.0.1:PORT`）。
+        // 客户端「OpenCode Server」行此前只能写「端口未上报」。只收 loopback URL，不收密码。
+        opencode_server: z.string().max(200).optional().catch(undefined),
         config_update_capable: z.boolean().optional(),
         peer_reply_inbox_capable: z.literal(true).optional(),
         side_thread_capability: z.object({
@@ -2002,8 +2012,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       from_session: z.string().max(200).optional(),
       ttl_seconds: z.number().min(1).max(86400).optional().describe("Task TTL in seconds (default: 3600)"),
       network_id: z.string().max(200).optional().describe("Network scope"),
-      parent_task_id: z.string().max(200).optional().describe("Parent task this dispatch is on behalf of. When the child task replies the hub will auto-chain the answer to the parent task's originator, so the user sees the final result even if the intermediate session ends."),
-      meta: z.any().optional().describe("Optional structured task metadata, e.g. { attachments: [{ type, path, url, mime, name, size }] }."),
+      parent_task_id: z.string().max(200).optional().describe("Parent task this dispatch is on behalf of. The child's reply is auto-chained to the parent's originator, so the user sees the result even if the intermediate session ends."),
+      meta: z.any().optional().describe("Optional task metadata, e.g. { attachments: [{ type, path, url, mime, name, size }] }."),
       force: z.boolean().optional().describe("dispatch even if the target is degraded (user tokens only)"),
     },
     async ({ alias, task, priority, context, from_session: _fromIn, ttl_seconds, network_id: netId, parent_task_id: parentIn, meta, force }) => {
@@ -2367,7 +2377,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // it always sent alias=undefined → -32602 "expected string, received
       // undefined at alias". The target was already knowable from the task,
       // so requiring the caller to pass it was a redundant-param trap.
-      alias: z.string().min(1).max(200).optional().describe("Target session alias — optional; derived from in_reply_to's task sender when omitted"),
+      alias: z.string().min(1).max(200).optional().describe("Target alias — optional; defaults to in_reply_to's sender"),
       text: z.string().min(1).max(10000).describe("Reply content"),
       in_reply_to: z.string().max(200).optional().describe("Original task/message ID"),
       status: z.enum(["replied", "failed", "cancelled"]).optional().default("replied").describe("Task outcome"),
@@ -2378,7 +2388,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // `attachments` before this schema entry existed would see `ok:true`
       // and never learn the attachments were dropped. Validated by
       // validateAttachments (uploads.ts) — the same helper the REST path uses.
-      attachments: z.any().optional().describe("Attachments, like send_task's meta.attachments: [{type:'file', file_id, name?, mime?, size?}]."),
+      attachments: z.any().optional().describe("Attachments, like send_task's: [{type:'file', file_id, name?, mime?, size?}]."),
       // #507 — optional structured metadata (parity with send_task L837). If
       // both `attachments` (top-level) and `meta.attachments` are supplied,
       // top-level wins (same rule as REST /api/task L2101).
@@ -4111,7 +4121,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       lines: z.number().int().min(1).max(LOGS_MAX_LINES).optional().describe("How many of the newest matching lines (default 500, max 2000)."),
       level: z.enum(["info", "warn", "error"]).optional().describe("Only lines of exactly this level."),
       grep: z.string().min(1).max(LOGS_GREP_MAX).optional().describe("Case-insensitive substring, matched after redaction."),
-      since_ts: z.number().int().min(0).optional().describe("Only lines at or after this epoch-ms timestamp (follow mode; the client de-duplicates by line key)."),
+      since_ts: z.number().int().min(0).optional().describe("Only lines at/after this epoch-ms timestamp (follow mode; client de-dupes by line key)."),
       network_id: z.string().max(200).optional(),
     },
     async ({ node_id, child_node_id, alias, lines, level, grep, since_ts, network_id }) =>
@@ -6776,7 +6786,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     name: z.string().min(1).max(80).optional(),
     priority: z.enum(["high", "normal", "low", "lowest"]).optional().describe("high = P0 最高, normal = P1 普通, low = P2 低, lowest = P3 极低"),
     column: z.enum(["pool", "doing", "done", "abandoned"]).optional(),
-    due: z.string().max(40).optional().describe("YYYY-MM-DD (all day) or ISO 8601 with Z / ±HH:MM (stored as UTC seconds); \"\" clears"),
+    due: z.string().max(40).optional().describe("YYYY-MM-DD (all day) or ISO 8601 (stored as UTC seconds); \"\" clears"),
     start: z.string().max(40).optional().describe("start date (Gantt): same shapes as due; \"\" clears"),
     description: z.string().max(20_000).optional().describe("markdown"),
     checklist: z.array(reqChecklistItem).max(100).optional().describe("replaces the whole list"),