@sleep2agi/commhub-server 0.9.0-preview.274 → 0.9.0-preview.276

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/build-info.json +2 -2
  2. package/package.json +1 -1
  3. package/src/agent-access-batch.test.ts +7 -2
  4. package/src/agent-acl-slice3-http.test.ts +4 -1
  5. package/src/agent-groups-perf.test.ts +6 -1
  6. package/src/anet-variant-real-daemon-http.test.ts +184 -0
  7. package/src/build-commit-report-http.test.ts +90 -0
  8. package/src/config-apply-sec1.test.ts +37 -0
  9. package/src/config-apply-validate.ts +7 -3
  10. package/src/contracts/session-project-create.ts +14 -0
  11. package/src/contracts/session-source-delivery.ts +16 -0
  12. package/src/contracts/session-source-directory.ts +54 -0
  13. package/src/contracts/session-source-evidence.ts +72 -0
  14. package/src/contracts/session-source-execution.ts +24 -0
  15. package/src/contracts/session-source-transport.ts +18 -0
  16. package/src/create-node-tool-schema.test.ts +10 -0
  17. package/src/db.ts +35 -0
  18. package/src/node-permissions.ts +1 -1
  19. package/src/node-session-control-http.test.ts +90 -2
  20. package/src/node-session-control.ts +89 -31
  21. package/src/opencode-v2-catalog.test.ts +14 -0
  22. package/src/opencode-v2-catalog.ts +1 -0
  23. package/src/package-self-contained.test.ts +32 -0
  24. package/src/report-status-host-schema.test.ts +37 -0
  25. package/src/rules-file-transport.test.ts +9 -0
  26. package/src/server.ts +47 -4
  27. package/src/session-fork-store.test.ts +43 -0
  28. package/src/session-fork-store.ts +51 -0
  29. package/src/session-project-attach-migration.test.ts +22 -0
  30. package/src/session-project-attach-native.test.ts +121 -0
  31. package/src/session-project-create-http.test.ts +407 -0
  32. package/src/session-project-create-native.test.ts +290 -0
  33. package/src/session-project-create.ts +159 -0
  34. package/src/session-source-admission-store.ts +58 -0
  35. package/src/session-source-create.test.ts +155 -0
  36. package/src/session-source-create.ts +97 -0
  37. package/src/session-source-delivery.ts +109 -0
  38. package/src/session-source-directory-http.test.ts +192 -0
  39. package/src/session-source-evidence.test.ts +890 -0
  40. package/src/session-source-evidence.ts +191 -0
  41. package/src/session-source-execution.ts +87 -0
  42. package/src/session-source-grant.test.ts +117 -0
  43. package/src/session-source-grant.ts +78 -0
  44. package/src/session-source-issuer.test.ts +247 -0
  45. package/src/session-source-issuer.ts +158 -0
  46. package/src/session-source-transport.ts +368 -0
  47. package/src/task-not-found-error-domain.test.ts +4 -1
  48. package/src/token-usage-http.test.ts +10 -0
  49. package/src/tool-audience-http.test.ts +18 -0
  50. package/src/tool-audience.ts +1 -1
  51. package/src/tools.ts +154 -51
package/src/tools.ts CHANGED
@@ -978,6 +978,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
978
978
  // can grey out remote-restart for them.
979
979
  config_snapshot: z.object({
980
980
  model: z.string().max(200).optional().nullable(),
981
+ model_effective: z.string().max(401).optional(),
982
+ modelVariant: z.string().max(200).nullable().optional(),
981
983
  flags: z.record(z.string(), z.unknown()).optional(),
982
984
  config_revision: z.number().int().min(0).optional(),
983
985
  // #2293(admin 2026-10-25)—— 节点自己上报的 OpenCode V2 模型 id 清单
@@ -993,6 +995,17 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
993
995
  // (#3294 的 build_commit 就是同一个坑)。`.catch(undefined)` 与邻居一致:
994
996
  // 形状不对只丢这一格,绝不拒掉整份心跳。
995
997
  opencode_catalog_seen_at: z.string().max(40).optional().catch(undefined),
998
+ // #4150-Build —— 这台节点的 OpenCode V2 暴露的 agent 列表(`build`/`plan`…)。
999
+ // 🔴 与上面 catalog 同一个陷阱:不写进这个 schema,daemon 报上来也**会被静默剥掉**,
1000
+ // `/api/nodes` 的投影读到的永远是 null。空数组合法 =「确实没有 agent」。
1001
+ opencode_agents: z.array(z.string().max(200)).max(200).optional().catch(undefined),
1002
+ opencode_agents_seen_at: z.string().max(40).optional().catch(undefined),
1003
+ // 绑定会话当前使用的 agent(读不到就不报;绝不用默认值冒充)。
1004
+ opencode_agent_current: z.string().max(200).optional().catch(undefined),
1005
+ // 只有真的能热切 agent 的节点才置 true(客户端据此决定是否显示可点选项)。
1006
+ opencode_agent_config_capable: z.literal(true).optional().catch(undefined),
1007
+ // Heartbeat capability only; it never finalizes a pending variant write.
1008
+ opencode_variant_config_capable: z.literal(true).optional().catch(undefined),
996
1009
  // #2293 —— 这台机器上 OpenCode serve 的 loopback 端点(`http://127.0.0.1:PORT`)。
997
1010
  // 客户端「OpenCode Server」行此前只能写「端口未上报」。只收 loopback URL,不收密码。
998
1011
  opencode_server: z.string().max(200).optional().catch(undefined),
@@ -1105,6 +1118,23 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
1105
1118
  // `.catch(undefined)`:同上一格的立场 —— 一个诊断/展示字段不许拒掉整份 report。
1106
1119
  // 读取侧再按形状消毒(create-node-validate.ts daemonDefaultWorkdirRoot)。
1107
1120
  default_workdir_root: z.string().max(1024).optional().catch(undefined),
1121
+ // Internal source-aware delivery handshake; declaration alone enables
1122
+ // no public queue/dispatch and old daemons must not receive it.
1123
+ source_node_delivery: z.literal("source-node-delivery-v1-opencode-2.0.22").optional().catch(undefined),
1124
+ // #4150-Build — public agent identifiers the node's OpenCode V2 server exposes.
1125
+ // Bounded and optional: an older node omits it, an empty list means "none".
1126
+ opencode_agents: z.array(z.string().max(200)).max(200).optional().catch(undefined),
1127
+ opencode_agents_seen_at: z.string().max(40).optional().catch(undefined),
1128
+ opencode_agent_current: z.string().max(200).optional().catch(undefined),
1129
+ // #4150 — the three independent read/attach previews plus the fork
1130
+ // transport. The transport reads these off this snapshot, so a hub
1131
+ // whose report schema omits them drops them silently (zod object is
1132
+ // non-strict) and every call answers 403 forever. Literals, and
1133
+ // .catch(undefined) so one unknown value never rejects a whole report.
1134
+ source_directory_read: z.literal("source-directory-read-v1-opencode-2.0.22").optional().catch(undefined),
1135
+ project_new_session: z.literal("project-new-session-v1-opencode-2.0.22").optional().catch(undefined),
1136
+ session_attach: z.literal("existing-session-attach-v1-opencode-2.0.22").optional().catch(undefined),
1137
+ source_fork_transport: z.literal("source-fork-transport-v1-opencode-2.0.22").optional().catch(undefined),
1108
1138
  // #622 —— 逐 runtime 实测就绪度。收得宽、坏了只丢这一格(见 runtime-readiness.ts)。
1109
1139
  runtime_readiness: runtimeReadinessSchema,
1110
1140
  }).optional(),
@@ -1712,7 +1742,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
1712
1742
  alias: z.string().min(1).max(200).describe("Alias"),
1713
1743
  message_id: z.string().min(1).max(200),
1714
1744
  response: z.string().max(10000).optional(),
1715
- network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
1745
+ network_id: z.string().max(200).optional().describe("Network; auto-resolved for single-network user tokens"),
1716
1746
  },
1717
1747
  async ({ alias, message_id, response, network_id: netId }) => {
1718
1748
  const effectiveNetId = getNetworkId(netId);
@@ -1950,10 +1980,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
1950
1980
 
1951
1981
  server.tool(
1952
1982
  "get_all_status",
1953
- "Get status of all sessions (each row has queue_depth = open tasks). Hub uses this for the patrol loop. " +
1954
- "Pass filter_alias (comma-separated) when you only care about specific " +
1955
- "nodes — the unfiltered result is one row per session with 31 columns and " +
1956
- "is large enough on a real fleet that callers cannot read it.",
1983
+ "Session status for Hub patrol; queue_depth = open tasks. Use comma-separated filter_alias for specific nodes. Unfiltered: one row/session, 31 columns; large fleets can exceed client limits.",
1957
1984
  {
1958
1985
  filter_status: z.string().max(50).optional(),
1959
1986
  filter_server: z.string().max(200).optional(),
@@ -2420,7 +2447,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
2420
2447
  alias: z.string().min(1).max(200).describe("Target session alias"),
2421
2448
  message: z.string().min(1).max(10000).describe("Message content"),
2422
2449
  from_session: z.string().max(200).optional(),
2423
- network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
2450
+ network_id: z.string().max(200).optional().describe("Network; auto-resolved for single-network user tokens"),
2424
2451
  },
2425
2452
  async ({ alias, message, from_session: _fromIn, network_id: netId }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
2426
2453
  const effectiveNetId = getNetworkId(netId);
@@ -2486,7 +2513,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
2486
2513
  in_reply_to: z.string().max(200).optional().describe("Original task/message ID"),
2487
2514
  status: z.enum(["replied", "failed", "cancelled"]).optional().default("replied").describe("Task outcome"),
2488
2515
  from_session: z.string().max(200).optional(),
2489
- network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
2516
+ network_id: z.string().max(200).optional().describe("Network; auto-resolved for single-network user tokens"),
2490
2517
  // #507 — top-level attachments (parity with REST /api/task L506). MCP Zod
2491
2518
  // otherwise silently strips unknown fields, so a caller passing
2492
2519
  // `attachments` before this schema entry existed would see `ok:true`
@@ -2993,7 +3020,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
2993
3020
  {
2994
3021
  task_id: z.string().min(1).max(200).describe("Task ID to acknowledge"),
2995
3022
  from_session: z.string().max(200).optional(),
2996
- network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
3023
+ network_id: z.string().max(200).optional().describe("Network; auto-resolved for single-network user tokens"),
2997
3024
  },
2998
3025
  async ({ task_id, from_session: _fromIn, network_id: netId }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
2999
3026
  const effectiveNetId = getNetworkId(netId);
@@ -3020,7 +3047,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
3020
3047
  {
3021
3048
  task_id: z.string().min(1).max(200).describe("Task ID to retry"),
3022
3049
  from_session: z.string().max(200).optional(),
3023
- network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
3050
+ network_id: z.string().max(200).optional().describe("Network; auto-resolved for single-network user tokens"),
3024
3051
  force: z.boolean().optional().describe("dispatch even if the target is degraded (user tokens only)"),
3025
3052
  },
3026
3053
  async ({ task_id, from_session: _fromIn, network_id: netId, force }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
@@ -3337,7 +3364,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
3337
3364
  task_id: z.string().min(1).max(200).describe("Task ID to cancel"),
3338
3365
  reason: z.string().max(1000).optional().describe("Cancellation reason"),
3339
3366
  from_session: z.string().max(200).optional(),
3340
- network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
3367
+ network_id: z.string().max(200).optional().describe("Network; auto-resolved for single-network user tokens"),
3341
3368
  },
3342
3369
  async ({ task_id, reason, from_session: _fromIn, network_id: netId }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
3343
3370
  const effectiveNetId = getNetworkId(netId);
@@ -3374,7 +3401,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
3374
3401
  task_id: z.string().min(1).max(200).describe("Task ID to reassign"),
3375
3402
  new_alias: z.string().min(1).max(200).describe("Target agent alias"),
3376
3403
  from_session: z.string().max(200).optional(),
3377
- network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
3404
+ network_id: z.string().max(200).optional().describe("Network; auto-resolved for single-network user tokens"),
3378
3405
  force: z.boolean().optional().describe("dispatch even if the target is degraded (user tokens only)"),
3379
3406
  },
3380
3407
  async ({ task_id, new_alias, from_session: _fromIn, network_id: netId, force }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
@@ -3719,6 +3746,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
3719
3746
  base_revision: z.number().int().min(0).describe("Revision from the dashboard's last GET — 409 if the hub's differs."),
3720
3747
  patch: z.object({
3721
3748
  model: z.string().max(200).optional(),
3749
+ modelVariant: z.string().min(1).max(200).nullable().optional(),
3750
+ // OpenCode V2 agent (Build) selection. Hot-only, live-session only:
3751
+ // the node POSTs /api/session/<ses_>/agent and reads the value back.
3752
+ // Absent = preserve. `null` is rejected by the node (no "clear agent"
3753
+ // operation exists), so the hub refuses it here as well.
3754
+ agent: z.string().min(1).max(200).optional(),
3722
3755
  flags: z.record(z.string(), z.unknown()).optional(),
3723
3756
  // #260 P5 — channel enable/disable. Restart-tier field (agent-node
3724
3757
  // reads config.channels once at boot to fork per-channel workers,
@@ -3754,6 +3787,31 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
3754
3787
  return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_node", message: "node belongs to another network" }) }] };
3755
3788
  }
3756
3789
 
3790
+ // Old nodes ignore unknown patch fields and may restart or falsely ack.
3791
+ // Require an explicitly advertised runtime capability before any queueing.
3792
+ if (patch.modelVariant !== undefined) {
3793
+ let snapshot: any;
3794
+ try { snapshot = JSON.parse(node.config_snapshot || "{}"); } catch { snapshot = {}; }
3795
+ if (snapshot.opencode_variant_config_capable !== true)
3796
+ return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "variant_unsupported" }) }] };
3797
+ if ((patch.flags && Object.keys(patch.flags).length) || patch.channels !== undefined ||
3798
+ (patch.modelVariant !== null && /[\s\x00-\x1f\x7f]/.test(patch.modelVariant)))
3799
+ return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "invalid_patch", field: "modelVariant" }) }] };
3800
+ }
3801
+
3802
+ if (patch.agent !== undefined) {
3803
+ let snapshot: any;
3804
+ try { snapshot = JSON.parse(node.config_snapshot || "{}"); } catch { snapshot = {}; }
3805
+ // Fail closed on nodes that cannot switch: without the capability the
3806
+ // node would ignore the field and ack whatever it likes, which is
3807
+ // exactly the "looks applied, nothing changed" failure we are avoiding.
3808
+ if (snapshot.opencode_agent_config_capable !== true)
3809
+ return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "agent_unsupported" }) }] };
3810
+ if ((patch.flags && Object.keys(patch.flags).length) || patch.channels !== undefined ||
3811
+ /[\s\x00-\x1f\x7f]/.test(patch.agent))
3812
+ return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "invalid_patch", field: "agent" }) }] };
3813
+ }
3814
+
3757
3815
  const model = typeof patch.model === "string" ? patch.model : undefined;
3758
3816
  const flags = (patch.flags && typeof patch.flags === "object") ? patch.flags as Record<string, unknown> : {};
3759
3817
  // Narrow untrusted `channels` at the boundary (typeof + allowlist +
@@ -3910,13 +3968,18 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
3910
3968
  // computeApplyMode 退回旧行为(model ⇒ restart),那正是客户端
3911
3969
  // 显示「重启中」却永远等不到重启的原因。
3912
3970
  const opencodeSnap = readOpencodeSnapshotFlags(node.config_snapshot);
3913
- const applyMode = computeApplyMode(model, flags, channels, {
3971
+ const applyMode = patch.modelVariant !== undefined || patch.agent !== undefined ? "hot" : computeApplyMode(model, flags, channels, {
3914
3972
  runtime: node.runtime,
3915
3973
  opencodeGeneration: opencodeSnap.opencodeGeneration,
3916
3974
  opencodeMode: opencodeSnap.opencodeMode,
3917
3975
  });
3976
+ let variantCapableAtQueue = false;
3977
+ try { variantCapableAtQueue = JSON.parse(node.config_snapshot || "{}").opencode_variant_config_capable === true; } catch { /* fail closed */ }
3918
3978
  const patchJson = JSON.stringify({
3919
3979
  ...(model !== undefined ? { model } : {}),
3980
+ ...(patch.modelVariant !== undefined ? { modelVariant: patch.modelVariant } : {}),
3981
+ ...(patch.agent !== undefined ? { agent: patch.agent } : {}),
3982
+ ...(model !== undefined && applyMode === "hot" && variantCapableAtQueue ? { _anet_variant_ack_required: true } : {}),
3920
3983
  flags,
3921
3984
  ...(channels !== undefined ? { channels } : {}),
3922
3985
  });
@@ -4078,6 +4141,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4078
4141
  }
4079
4142
  let patch: any = {};
4080
4143
  try { patch = JSON.parse(update.patch_json); } catch { patch = {}; }
4144
+ // Hub-only persistence metadata is never part of the node patch contract.
4145
+ if (patch && typeof patch === "object") delete patch._anet_variant_ack_required;
4081
4146
  return {
4082
4147
  content: [{
4083
4148
  type: "text" as const,
@@ -4352,10 +4417,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4352
4417
 
4353
4418
  server.tool(
4354
4419
  "read_node_rules_file",
4355
- "Ask a node to send back its rules file (CLAUDE.md for claude, else AGENTS.md) from its work dir. No path argument. Poll get_rules_file_result with the returned request_id. app#225.",
4420
+ "Read the node's workdir rules file (CLAUDE.md for claude, else AGENTS.md). No path argument. Poll get_rules_file_result with request_id. app#225.",
4356
4421
  {
4357
4422
  ...NODE_ID_ALIAS_FIELDS,
4358
- alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting rules_file_capable)."),
4423
+ alias: z.string().min(1).max(200).optional().describe("Instead of node_id: node or rules_file_capable session alias."),
4359
4424
  network_id: z.string().max(200).optional(),
4360
4425
  },
4361
4426
  async ({ node_id, child_node_id, alias, network_id }) => enqueueRulesFileRequest("read", { node_id, child_node_id, alias, network_id }),
@@ -4366,7 +4431,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4366
4431
  "Ask a node to write a managed block into its rules file (CLAUDE.md / AGENTS.md). Poll get_rules_file_result. User logins only (node owner or network owner/admin).",
4367
4432
  {
4368
4433
  ...NODE_ID_ALIAS_FIELDS,
4369
- alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting rules_file_capable)."),
4434
+ alias: z.string().min(1).max(200).optional().describe("Instead of node_id: node or rules_file_capable session alias."),
4370
4435
  content: z.string().max(RULES_FILE_MAX_BYTES).describe("Full new file content (UTF-8). The node writes it atomically."),
4371
4436
  network_id: z.string().max(200).optional(),
4372
4437
  },
@@ -4375,10 +4440,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4375
4440
 
4376
4441
  server.tool(
4377
4442
  "list_node_skills",
4378
- "Ask a node for the skills its runtime loads (name, scope project|user|system, display path, description; team skills add origin \"team\"). No path. Poll get_rules_file_result: {skills:[...], roots, warnings}.",
4443
+ "List runtime skills (name, scope project|user|system, display path, description; team adds origin=\"team\"). No path. Poll get_rules_file_result: {skills, roots, warnings}.",
4379
4444
  {
4380
4445
  ...NODE_ID_ALIAS_FIELDS,
4381
- alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting skills_capable)."),
4446
+ alias: z.string().min(1).max(200).optional().describe("Instead of node_id: node or skills_capable session alias."),
4382
4447
  network_id: z.string().max(200).optional(),
4383
4448
  },
4384
4449
  async ({ node_id, child_node_id, alias, network_id }) => enqueueRulesFileRequest("skills_list", { node_id, child_node_id, alias, network_id }),
@@ -4386,10 +4451,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4386
4451
 
4387
4452
  server.tool(
4388
4453
  "read_node_skill",
4389
- "One skill's SKILL.md by name; the node resolves it under its own skills roots (no path). Poll get_rules_file_result: {name, scope, path_rel, description, content, origin?}; origin=\"team\" only for a team skill.",
4454
+ "Read SKILL.md by name within node skills roots (no path). Poll get_rules_file_result: {name, scope, path_rel, description, content, origin?}; origin=\"team\" only for team skills.",
4390
4455
  {
4391
4456
  ...NODE_ID_ALIAS_FIELDS,
4392
- alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting skills_capable)."),
4457
+ alias: z.string().min(1).max(200).optional().describe("Instead of node_id: node or skills_capable session alias."),
4393
4458
  name: z.string().min(1).max(64).describe("Skill directory name, [A-Za-z0-9._-]."),
4394
4459
  network_id: z.string().max(200).optional(),
4395
4460
  },
@@ -4398,10 +4463,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4398
4463
 
4399
4464
  server.tool(
4400
4465
  "list_node_files",
4401
- "List one level of the node's work dir (read-only). `path` relative (default root); absolute and .. refused. Poll get_rules_file_result: {path, entries:[{name,type,size?,mtime?,hidden_reason?,no_descend?}], truncated, total}. User logins only.",
4466
+ "List one level of node workdir (read-only). Relative path (default root); absolute and .. refused. Poll get_rules_file_result: {path, entries:[{name,type,size?,mtime?,hidden_reason?,no_descend?}], truncated, total}. User logins only.",
4402
4467
  {
4403
4468
  ...NODE_ID_ALIAS_FIELDS,
4404
- alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting files_capable)."),
4469
+ alias: z.string().min(1).max(200).optional().describe("Instead of node_id: node or files_capable session alias."),
4405
4470
  path: z.string().max(NODE_FILE_PATH_MAX).optional().describe("Directory relative to the node's work dir; omit or \"\" for the root."),
4406
4471
  network_id: z.string().max(200).optional(),
4407
4472
  },
@@ -4410,10 +4475,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4410
4475
 
4411
4476
  server.tool(
4412
4477
  "read_node_file",
4413
- "One text file under the node's work dir (read-only, 256 KiB cap; binary / too large -> size only; secret-looking -> name only). `path` relative. Poll get_rules_file_result: {path, name, kind, size?, mtime?, content?, hidden_reason?}. User logins only.",
4478
+ "Read node workdir text file (read-only, 256 KiB cap; binary/too large → size only; secret-looking → name only). Relative path. Poll get_rules_file_result: {path, name, kind, size?, mtime?, content?, hidden_reason?}. User logins only.",
4414
4479
  {
4415
4480
  ...NODE_ID_ALIAS_FIELDS,
4416
- alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting files_capable)."),
4481
+ alias: z.string().min(1).max(200).optional().describe("Instead of node_id: node or files_capable session alias."),
4417
4482
  path: z.string().min(1).max(NODE_FILE_PATH_MAX).describe("File path relative to the node's work dir."),
4418
4483
  network_id: z.string().max(200).optional(),
4419
4484
  },
@@ -4422,10 +4487,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4422
4487
 
4423
4488
  server.tool(
4424
4489
  "tail_node_logs",
4425
- "Tail of the node's own run log (read-only, redacted on the node). No path argument. User logins only (node owner or network owner/admin). Poll get_rules_file_result: {files, lines, truncated, matched}; handed out once, then purged.",
4490
+ "Tail node's own run log (read-only, node-redacted). No path. User login only (node owner or network owner/admin). Poll get_rules_file_result: {files, lines, truncated, matched}; handed out once, then purged.",
4426
4491
  {
4427
4492
  ...NODE_ID_ALIAS_FIELDS,
4428
- alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting logs_capable)."),
4493
+ alias: z.string().min(1).max(200).optional().describe("Instead of node_id: node or logs_capable session alias."),
4429
4494
  lines: z.number().int().min(1).max(LOGS_MAX_LINES).optional().describe("How many of the newest matching lines (default 500, max 2000)."),
4430
4495
  level: z.enum(["info", "warn", "error"]).optional().describe("Only lines of exactly this level."),
4431
4496
  grep: z.string().min(1).max(LOGS_GREP_MAX).optional().describe("Case-insensitive substring, matched after redaction."),
@@ -4916,9 +4981,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4916
4981
  // row (metadata only — no env_blob in SQL), pushEvent doorbell.
4917
4982
  server.tool(
4918
4983
  "create_node",
4919
- "Create/start a node on the target daemon; the child reports back to Hub.",
4984
+ "Create/start node via daemon; child reports to Hub.",
4920
4985
  {
4921
4986
  daemon_node_id: z.string().min(1).max(200),
4987
+ // #4150: unsupported source intent must not be stripped into ordinary create.
4988
+ source_ref: z.never().optional(),
4922
4989
  node_spec: z.object({
4923
4990
  // #652 — 64 *code points* after trim is enforced by validateChildName (shared/node-name.ts);
4924
4991
  // zod's max counts UTF-16 units and surrounding whitespace, so it is only a coarse bound here.
@@ -4932,6 +4999,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
4932
4999
  opencodeGeneration: z.never().optional(),
4933
5000
  opencodeUnsafeTools: z.never().optional(),
4934
5001
  opencodeNewServer: z.never().optional(),
5002
+ source_ref: z.never().optional(),
4935
5003
  channels: z.array(z.unknown()).optional(),
4936
5004
  // app「新建节点」确认页的工作目录(绝对路径或 ~/…,daemon 侧展开并校验)。
4937
5005
  // 缺席 = 老行为:落 daemon 的 cwd。
@@ -7015,13 +7083,40 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7015
7083
  },
7016
7084
  );
7017
7085
 
7086
+ // #4099: a deliberately closed entry point, NOT a queued operation. Until
7087
+ // daemon/session ownership and an atomic idle gate are wired end-to-end,
7088
+ // never emit a doorbell or fall back to node configuration/restart.
7089
+ server.registerTool(
7090
+ "select_opencode_session_model",
7091
+ {
7092
+ description: "OpenCode V2 session model change: unavailable; no write or restart.",
7093
+ inputSchema: z.object({
7094
+ network_id: z.string().min(1).max(200).optional(),
7095
+ daemon_node_id: z.string().min(1).max(200),
7096
+ node_id: z.string().min(1).max(200),
7097
+ session_id: z.string().regex(/^ses_[A-Za-z0-9]+$/),
7098
+ model: z.object({ providerID: z.string().min(1).max(200), id: z.string().min(1).max(200), variant: z.string().min(1).max(200).optional() }).strict(),
7099
+ }).strict() as any,
7100
+ },
7101
+ async (args: { network_id?: string }) => {
7102
+ const networkId = getNetworkId(args.network_id);
7103
+ const role = enforceUserId && networkId ? getUserNetworkRole(enforceUserId, networkId) : null;
7104
+ const result = callerTokenIsNetwork
7105
+ ? { ok: false, error: "user_token_required" }
7106
+ : !enforceUserId || !networkId || !["owner", "admin"].includes(role ?? "")
7107
+ ? { ok: false, error: "access_denied" }
7108
+ : { ok: false, status: "rejected", reason: "unsupported" };
7109
+ return { content: [{ type: "text" as const, text: JSON.stringify(result) }] };
7110
+ },
7111
+ );
7112
+
7018
7113
  // OpenCode V2 catalog. Human tokens queue; the owning daemon pulls scope
7019
7114
  // only and acks a whitelist snapshot. pending is stored authorization, not
7020
7115
  // a snapshot and not proof the doorbell was received.
7021
7116
  server.registerTool(
7022
7117
  "read_opencode_catalog",
7023
7118
  {
7024
- description: "Queue a native OpenCode V2 catalog read for one owned child. ok with status pending means authorized and stored in memory, not a snapshot and not proof a daemon received the doorbell. Does not start a server. url, authorization, directory, settings, headers, and body are rejected.",
7119
+ description: "Queue an owned child’s native V2 catalog read. pending means authorized and stored in memory, not a snapshot or proof of daemon receipt. Does not start a server. URL, authorization, directory, settings, headers and body are rejected.",
7025
7120
  inputSchema: z.object({
7026
7121
  daemon_node_id: z.string().min(1).max(200),
7027
7122
  node_id: z.string().min(1).max(200),
@@ -7046,7 +7141,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7046
7141
  server.registerTool(
7047
7142
  "get_opencode_catalog",
7048
7143
  {
7049
- description: "Poll one queued OpenCode V2 catalog read. status pending is not a snapshot. Only status ready returns a whitelist snapshot, still completeness unknown and invocationVerified false.",
7144
+ description: "Poll a V2 catalog read. pending is not a snapshot; only ready returns one, with completeness unknown and invocationVerified false.",
7050
7145
  inputSchema: z.object({
7051
7146
  request_id: z.string().min(1).max(200),
7052
7147
  network_id: z.string().max(200).optional(),
@@ -7066,7 +7161,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7066
7161
  server.registerTool(
7067
7162
  "get_opencode_catalog_request",
7068
7163
  {
7069
- description: "Daemon pulls one authorized OpenCode V2 catalog read. Scope only: no URL, authorization, settings, headers, or body.",
7164
+ description: "Daemon pulls an authorized V2 catalog read. Scope only; no URL, authorization, settings, headers or body.",
7070
7165
  inputSchema: z.object({ request_id: z.string().min(1).max(200) }).strict() as any,
7071
7166
  },
7072
7167
  async (args: { request_id: string }) => {
@@ -7079,7 +7174,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7079
7174
  server.registerTool(
7080
7175
  "ack_opencode_catalog",
7081
7176
  {
7082
- description: "Daemon stores a whitelist OpenCode V2 catalog snapshot or a closed error code. Extra fields are rejected. A stored failure is status failed, not a transport error.",
7177
+ description: "Daemon stores a whitelisted V2 catalog snapshot or error code. Extra fields are rejected; stored failure means status failed, not a transport error.",
7083
7178
  inputSchema: opencodeCatalogAckSchema as any,
7084
7179
  },
7085
7180
  async (args: unknown) => {
@@ -7121,33 +7216,33 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7121
7216
  });
7122
7217
  const reqChecklistItem = z.object({ id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/).optional(), text: z.string().min(1).max(500), done: z.boolean().optional() });
7123
7218
  const reqFields = {
7124
- tags: z.array(z.string()).max(10).optional().describe("Task labels; each 1–20 Unicode characters. Omit to preserve, [] to clear."),
7219
+ tags: z.array(z.string()).max(10).optional().describe("1–20 Unicode chars each; omit preserves, [] clears."),
7125
7220
  name: z.string().min(1).max(80).optional(),
7126
- priority: z.enum(["high", "normal", "low", "lowest"]).optional().describe("high = P0 最高, normal = P1 普通, low = P2 低, lowest = P3 极低"),
7221
+ priority: z.enum(["high", "normal", "low", "lowest"]).optional().describe("high=P0, normal=P1, low=P2, lowest=P3"),
7127
7222
  column: z.enum(["pool", "doing", "done", "abandoned"]).optional(),
7128
- due: z.string().max(40).optional().describe("YYYY-MM-DD (all day) or ISO 8601 (stored as UTC seconds); \"\" clears"),
7129
- start: z.string().max(40).optional().describe("start date (Gantt): same shapes as due; \"\" clears"),
7223
+ due: z.string().max(40).optional().describe("YYYY-MM-DD (all day) or ISO 8601 (UTC sec); \"\" clears"),
7224
+ start: z.string().max(40).optional().describe("Gantt start: as due; \"\" clears"),
7130
7225
  description: z.string().max(20_000).optional().describe("markdown"),
7131
7226
  checklist: z.array(reqChecklistItem).max(100).optional().describe("replaces the whole list"),
7132
7227
  project_id: z.string().max(200).nullable().optional(),
7133
- owner: reqPerson.nullable().optional().describe("Owner (person): {kind:'user', id|username} from requirements_people; a node gets owner_must_be_human — use agent_owner"),
7228
+ owner: reqPerson.nullable().optional().describe("Human {kind:'user',id|username}; see requirements_people. Nodes: agent_owner (owner_must_be_human)."),
7134
7229
  agent_owner: reqPerson.nullable().optional().describe("负责 Agent: {kind:'node', id | alias}"),
7135
- participants: z.array(reqPerson).max(100).optional().describe("REPLACES the list (omitted removed; [] clears). For a few use participants_add/_remove."),
7230
+ participants: z.array(reqPerson).max(100).optional().describe("REPLACES list (omitted removed, [] clears); partial: participants_add/_remove."),
7136
7231
  external_url: z.string().max(500).nullable().optional(),
7137
- parent_id: z.string().regex(/^[A-Za-z0-9_-]{1,200}$/).nullable().optional().describe("parent requirement (same network, no cycles, ≤ 5 levels); null detaches"),
7232
+ parent_id: z.string().regex(/^[A-Za-z0-9_-]{1,200}$/).nullable().optional().describe("Same-network parent, no cycles, ≤5 levels; null detaches"),
7138
7233
  };
7139
7234
  const pick = (args: Record<string, unknown>, keys: string[]) => Object.fromEntries(keys.filter(k => args[k] !== undefined).map(k => [k, args[k]]));
7140
7235
  const REQ_WRITE_KEYS = [...Object.keys(reqFields), "external_ref", "archived"];
7141
7236
  // #475 —— status 是 column 的别名(列表的筛选参数就叫 status,Agent 写任务时也常这么写)。只在 MCP 这层换名,REST 不变;
7142
7237
  // 两个都给且不同 → 400 status_conflicts_with_column,不替调用方挑一个。
7143
- const reqStatus = z.enum(["pool", "doing", "done", "abandoned"]).optional().describe("alias of column; must match it if both are sent");
7238
+ const reqStatus = z.enum(["pool", "doing", "done", "abandoned"]).optional().describe("column alias; if both are sent they must match");
7144
7239
  const withColumn = (args: Record<string, unknown>, call: (args: Record<string, unknown>) => Promise<{ content: { type: "text"; text: string }[] }>) => {
7145
7240
  if (args.status === undefined) return call(args);
7146
7241
  if (args.column !== undefined && args.column !== args.status) return Promise.resolve({ content: [{ type: "text" as const, text: JSON.stringify({ ...errorBody("status_conflicts_with_column"), status: 400 }) }] });
7147
7242
  return call({ ...args, column: args.status });
7148
7243
  };
7149
- const reqPeopleDelta = (verb: string) => z.array(reqPerson).max(100).optional().describe(`${verb === "add" ? "Add to" : "Remove from"} the participant list, keeping the rest (atomic; not with participants).`);
7150
- const REQ_ID_DESC = "requirement id (req_…) or short number \"#N\" (per network; with several networks also pass network_id)";
7244
+ const reqPeopleDelta = (verb: string) => z.array(reqPerson).max(100).optional().describe(`${verb === "add" ? "Add to" : "Remove from"} participants, keeping the rest (atomic; not with participants).`);
7245
+ const REQ_ID_DESC = "req_… or per-network #N; pass network_id if multiple networks";
7151
7246
 
7152
7247
  // #471 —— MCP 的列表默认省流:summary 视图 + 50 张一页(REST 的默认 full + 500 不变,App 靠它)。
7153
7248
  // 生产实测 122 张卡:旧默认(full、500)148 KB,summary 81 KB —— 一次调用就塞满 Agent 的上下文。
@@ -7179,7 +7274,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7179
7274
  server.registerTool(
7180
7275
  "requirements_list",
7181
7276
  {
7182
- description: `List requirement tasks in your network, newest first. Defaults (MCP): view='summary' (no description / checklist bodies; has_description, checklist_count instead; ~0.5 KB per task) and ${REQ_LIST_MCP_DEFAULT_LIMIT} per page; has_more + next_cursor → pass cursor. Full text: requirements_get, or view='full' with a small limit (≤ 1000). Filters: seq (#N), status, project_id ('none'), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), tag (exact), updated_since (ISO), overdue / due_within_days (open tasks only), external_ref, parent_id / top_level, department_id (owner in it or below), include_archived; q searches title / description / people / project / tags (terms ANDed). Rows carry children {total, done}; include_last_event=true adds last_event (newest event incl. comments). changes=true (with updated_since) returns only tasks changed since then, archived included, plus deleted ids and server_time for the next updated_since. Unknown parameters are rejected (-32602).`,
7277
+ description: `List network tasks, newest first. MCP default: ${REQ_LIST_MCP_DEFAULT_LIMIT}/page, view=summary (no description/checklist bodies; has_description, checklist_count; ~0.5 KB/task). If has_more, pass next_cursor as cursor. Full text: requirements_get or view=full (limit ≤1000). Filters: seq (#N), status, project_id ('none'), owner/agent_owner ('user:<id>'/'node:<id>'/'none'), exact tag, ISO updated_since, overdue/due_within_days (open only), external_ref, parent_id/top_level, department_id (owner in it or below), include_archived. q AND-searches title/description/people/project/tags. Rows: children {total,done}; include_last_event adds newest event incl. comments. changes=true with updated_since returns changed tasks incl. archived, deleted ids, and server_time for next updated_since. Unknown parameters rejected (-32602).`,
7183
7278
  // Strict: registerTool honours a constructed object's unknownKeys (server.tool() would strip them silently).
7184
7279
  inputSchema: z.strictObject(reqListShape, {
7185
7280
  error: (iss: any) => iss.code === "unrecognized_keys"
@@ -7214,7 +7309,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7214
7309
  server.registerTool(
7215
7310
  "requirements_people",
7216
7311
  {
7217
- description: "Look up the people in your network and the Agents they own, to fill task person fields. Each row: user_id, username, display_name (\"\" if not set), role, department {id, name} or null, agents [{node_id, alias}]; Agents with no owner in this network are listed in agents_without_owner (first page only). q filters by username / display name / department / Agent alias (case-insensitive substring). 50 people per page (limit ≤ 200); has_more + next_offset → pass offset. Agents you are not granted are left out. Task person fields take these ids, or {kind:'user', username} / {kind:'node', alias}.",
7312
+ description: "Find network people and their Agents for task fields. Rows: user_id, username, display_name (\"\" if unset), role, department {id,name} or null, agents [{node_id,alias}]. agents_without_owner: first page only. q: case-insensitive substring of username/display name/department/Agent alias. Default 50/page, limit ≤200; pass next_offset when has_more. Ungranted Agents omitted. Task person fields accept these IDs or {kind:'user',username}/{kind:'node',alias}.",
7218
7313
  inputSchema: z.strictObject(reqPeopleShape, {
7219
7314
  error: (iss: any) => iss.code === "unrecognized_keys"
7220
7315
  ? `unknown parameter(s): ${(iss.keys ?? []).join(", ")}; valid parameters: ${reqPeopleKeys.join(", ")}`
@@ -7237,35 +7332,35 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7237
7332
 
7238
7333
  server.tool(
7239
7334
  "requirements_create",
7240
- "Create a task; name required. column (alias status) = pool/doing/done/abandoned. Duplicate external_ref -> 409 external_ref_exists with existing_id; use requirements_upsert_by_external_ref to sync.",
7335
+ "Create task; name required. column (alias status): pool/doing/done/abandoned. Duplicate external_ref: 409 external_ref_exists with existing_id; sync via requirements_upsert_by_external_ref.",
7241
7336
  { network_id: z.string().max(200).optional(), ...reqFields, status: reqStatus, name: z.string().min(1).max(80), external_ref: z.string().max(200).optional() },
7242
7337
  async (args) => withColumn(args, a => requirementsCall("POST", "/api/requirements", args.network_id, pick(a, REQ_WRITE_KEYS))),
7243
7338
  );
7244
7339
 
7245
7340
  server.tool(
7246
7341
  "requirements_update",
7247
- "Patch a task (id or \"#N\"); omitted fields keep their value. column (alias status) = pool/doing/done/abandoned. participants REPLACES the whole list (use participants_add / _remove to keep others). archived=true hides it; agents cannot delete.",
7342
+ "Patch a task (id or #N); omitted fields unchanged. column (alias status): pool/doing/done/abandoned. participants REPLACES the list; participants_add/_remove keeps others. archived=true hides; agents cannot delete.",
7248
7343
  { id: z.string().min(1).max(200).describe(REQ_ID_DESC), network_id: z.string().max(200).optional(), ...reqFields, status: reqStatus, participants_add: reqPeopleDelta("add"), participants_remove: reqPeopleDelta("remove"), external_ref: z.string().max(200).nullable().optional(), archived: z.boolean().optional() },
7249
7344
  async (args) => withColumn(args, a => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(args.id)}`, args.network_id, pick(a, [...REQ_WRITE_KEYS, "participants_add", "participants_remove"]))),
7250
7345
  );
7251
7346
 
7252
7347
  server.tool(
7253
7348
  "requirements_checklist_toggle",
7254
- "Set one checklist item done / not done (only that item is written, so concurrent edits of other items are kept).",
7349
+ "Set one checklist item done/not done; other items' concurrent edits are kept.",
7255
7350
  { id: z.string().min(1).max(200).describe(REQ_ID_DESC), item_id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/), done: z.boolean(), network_id: z.string().max(200).optional() },
7256
7351
  async ({ id, item_id, done, network_id }) => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(id)}/checklist/${encodeURIComponent(item_id)}`, network_id, { done }),
7257
7352
  );
7258
7353
 
7259
7354
  server.tool(
7260
7355
  "requirements_upsert_by_external_ref",
7261
- "Idempotent sync: create the task for external_ref (e.g. github:owner/repo#123) or update the one already bound to it. Returns { requirement, created }.",
7356
+ "Idempotent sync: create for external_ref (e.g. github:owner/repo#123) or update its bound task. Returns {requirement, created}.",
7262
7357
  { network_id: z.string().max(200).optional(), external_ref: z.string().min(1).max(200), ...reqFields, status: reqStatus, archived: z.boolean().optional() },
7263
7358
  async (args) => withColumn(args, a => requirementsCall("POST", "/api/requirements/upsert", args.network_id, pick(a, REQ_WRITE_KEYS))),
7264
7359
  );
7265
7360
 
7266
7361
  server.tool(
7267
7362
  "projects_list",
7268
- "List requirement projects (id, name, color, sort, archived, parentId). node tokens can only read projects; creating / changing needs a person's token (projects_create / projects_update).",
7363
+ "Projects: id, name, color, sort, archived, parentId. Node tokens read only; create/update needs a user token (projects_create/projects_update).",
7269
7364
  { network_id: z.string().max(200).optional() },
7270
7365
  async ({ network_id }) => requirementsCall("GET", "/api/requirements/projects", network_id),
7271
7366
  );
@@ -7275,7 +7370,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7275
7370
  // write access and is refused to 「仅相关任务」(task-scoped) members; events use the task list's visibility.
7276
7371
  server.tool(
7277
7372
  "projects_create",
7278
- "Create a project (管理项目 → 新建). name 1-40, unique; color #RRGGBB; sort int; parent_id optional (<=3 levels). Returns { project }; node tokens can only read projects.",
7373
+ "Create project (管理项目 → 新建). name 1-40, unique; color #RRGGBB; integer sort; optional parent_id (≤3 levels). Returns {project}; node tokens read only.",
7279
7374
  {
7280
7375
  network_id: z.string().max(200).optional(),
7281
7376
  name: z.string().min(1).max(40),
@@ -7288,7 +7383,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7288
7383
 
7289
7384
  server.tool(
7290
7385
  "projects_update",
7291
- "Rename, recolour, reorder, archive, or move a project under another (parent_id; null = top level; cycles / depth>3 refused). Only fields you pass change; node tokens can only read projects.",
7386
+ "Rename, recolour, reorder, archive or move project (parent_id; null=top level; cycles/depth>3 refused). Only passed fields change; node tokens read only.",
7292
7387
  {
7293
7388
  network_id: z.string().max(200).optional(),
7294
7389
  id: z.string().min(1).max(200).describe("project id (proj_…), from projects_list"),
@@ -7341,7 +7436,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7341
7436
  server.registerTool(
7342
7437
  "requirements_events",
7343
7438
  {
7344
- description: `Read the task activity timeline (the app's 动态), newest first: field-level changes (who, when, old → new) and comments (kind=comment, text in new.text; add one with requirements_comment). With requirement_id (req_… or "#N"): that task's events (limit default 200). Without it: the whole network, ${REQ_EVENTS_NETWORK_DEFAULT_LIMIT} per page by default. limit ≤ 500; next_cursor → pass as cursor for older events; server_time → use as the next since. Same visibility as requirements_list. Unknown parameters are rejected (-32602).`,
7439
+ description: `Task activity (动态), newest first: field changes (who, when, old → new) and comments (kind=comment, new.text; add via requirements_comment). With requirement_id (req_… or #N), default limit 200; otherwise network-wide, default ${REQ_EVENTS_NETWORK_DEFAULT_LIMIT}. limit ≤500; pass next_cursor as cursor for older events, server_time as next since. Visibility as requirements_list. Unknown parameters rejected (-32602).`,
7345
7440
  inputSchema: z.strictObject(reqEventsShape, {
7346
7441
  error: (iss: any) => iss.code === "unrecognized_keys"
7347
7442
  ? `unknown parameter(s): ${(iss.keys ?? []).join(", ")}; valid parameters: ${reqEventsKeys.join(", ")}`
@@ -7371,7 +7466,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
7371
7466
  // 两次调用,并发时覆盖别人刚写的描述。这条只追加,进「动态」(requirements_events kind=comment),不改任务本身。
7372
7467
  server.tool(
7373
7468
  "requirements_comment",
7374
- "Append a comment / progress note to a task (**append-only**; never rewrites the description). Shows in requirements_events (kind=comment, text in new.text). text: markdown 1-4000. Anyone who can see the task and write in the network may comment. Returns { event }.",
7469
+ "Append-only task comment/progress; never rewrites description. requirements_events: kind=comment, new.text. Markdown 1-4000; caller must see task and write in network. Returns {event}.",
7375
7470
  {
7376
7471
  id: z.string().min(1).max(200).describe(REQ_ID_DESC),
7377
7472
  text: z.string().min(1).max(4000).describe("the comment (markdown), 1–4000 characters"),
@@ -7721,6 +7816,14 @@ export function finalizePendingMatchingUpdates(
7721
7816
  let patch: any = {};
7722
7817
  try { patch = JSON.parse(row.patch_json); } catch { continue; }
7723
7818
 
7819
+ // Live-session variant changes are not represented by config_snapshot.
7820
+ // Only the explicit node ack after scoped readback may finalize them.
7821
+ if (Object.prototype.hasOwnProperty.call(patch, "modelVariant")) continue;
7822
+ // A capable live-session model write also preserves the selected variant.
7823
+ // A matching old model snapshot cannot prove that operation has finished.
7824
+ if (row.apply_mode === "hot" && patch.model !== undefined &&
7825
+ (patch._anet_variant_ack_required === true || snapshot?.opencode_variant_config_capable === true)) continue;
7826
+
7724
7827
  let matches = true;
7725
7828
  // restart_only / empty patch → any snapshot proves the restart
7726
7829
  // happened, finalize unconditionally.