@sleep2agi/commhub-server 0.9.0-preview.82 → 0.9.0-preview.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.82",
+  "version": "0.9.0-preview.84",
   "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/agent-access.ts

@@ -475,4 +475,9 @@ export const RESTRICTED_MEMBER_TOOLS: ReadonlySet<string> = new Set([
   "requirements_checklist_toggle",
   "requirements_upsert_by_external_ref",
   "projects_list",
+  // 2026-10-02(app 任务页审计 M3):和 app「管理项目」/「动态」同一个 REST 处理,权限也同一套 —— 项目管理对仅相关任务的
+  // 成员和 viewer 一律 403;动态按任务可见性过滤,受限成员看不见的节点在里面隐去(listEvents 的 hiddenNodeFilter)。
+  "projects_create",
+  "projects_update",
+  "requirements_events",
 ]);

package/src/mcp-projects-events-http.test.ts

@@ -0,0 +1,162 @@
+// MCP projects_create / projects_update / requirements_events(app 任务页审计 2026-10-02 M3:Agent 能做人能做的)。
+// HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。三个工具都走 app 用的同一套 REST 处理(handleRequirementsRequest),
+// 所以这里不另抄一份权限规则:对每类调用者(网络 owner、全部任务成员、仅相关任务成员、viewer、节点令牌)都同时调
+// MCP 和 REST,断言状态码 / 结果逐项一致。再钉住正向行为(建 / 改名 / 归档 / 取消归档、读流水、"#N")和工具出现在 tools/list 里。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-mcp-projects-events-"));
+let BASE = "";
+let hub: any = null;
+const PW = "McpProjectsEventsPassw0rd!x";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json };
+}
+async function rpc(token: string, method: string, params?: unknown): Promise<any> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, ...(params === undefined ? {} : { params }) }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  return lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const out = await rpc(token, "tools/call", { name, arguments: args });
+  return JSON.parse(out.result.content[0].text);
+}
+// MCP error bodies from the REST handler carry its status (requirementsCall). Anything else that isn't ok (e.g. a tool-level
+// gate) is NOT a success — a body without `status` must never be read as the 2xx (that hid a gate in the first draft).
+const mcpStatus = (r: any, okStatus: number) => (r?.ok === true || (r && r.ok === undefined && (r.project || r.events)) ? okStatus : typeof r?.status === "number" ? r.status : -1);
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`mpe_owner_${Date.now()}`, PW, undefined, "Owner");
+  expect(a.ok).toBe(true);
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.id]);
+  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}`;
+  const mk = async (username: string, role: string) => {
+    expect((await rest(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role })).status).toBe(200);
+    const login = await rest("", "POST", "/api/auth/login", { username, password: PW });
+    expect(login.status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  U.member = await mk(`mpe_member_${stamp}`, "member");
+  U.scoped = await mk(`mpe_scoped_${stamp}`, "member");
+  U.viewer = await mk(`mpe_viewer_${stamp}`, "viewer");
+  db.run("UPDATE network_members SET task_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, U.member.id]);
+  expect((await rest(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.scoped.id}/task-grants`, { task_access: "scoped", project_grants: [] })).status).toBe(200);
+  const node = createNetworkTokenForNode(U.owner.id, NET, "mpe-node", "node_mpe");
+  U.node = { token: node.token!, id: "node_mpe" };
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("discoverable", () => {
+  test("tools/list carries the three tools with descriptions", async () => {
+    const list = await rpc(U.owner.token, "tools/list");
+    const byName = new Map((list.result.tools as any[]).map(t => [t.name, t]));
+    for (const n of ["projects_create", "projects_update", "requirements_events"]) {
+      expect(byName.has(n)).toBe(true);
+      expect(String(byName.get(n).description).length).toBeGreaterThan(40);
+    }
+    expect(String(byName.get("projects_list").description)).toContain("projects_create");
+  });
+});
+
+describe("projects_create / projects_update", () => {
+  test("owner: create, rename, recolour, archive, unarchive — same rows the app sees", async () => {
+    const created = await mcp(U.owner.token, "projects_create", { network_id: NET, name: "mpe-项目甲" });
+    expect(created.ok).toBe(true);
+    const id = created.project.id as string;
+    expect(created.project.name).toBe("mpe-项目甲");
+    const renamed = await mcp(U.owner.token, "projects_update", { network_id: NET, id, name: "mpe-项目乙", color: "#16a34a" });
+    expect(renamed.project.name).toBe("mpe-项目乙");
+    expect(renamed.project.color).toBe("#16a34a");
+    expect((await mcp(U.owner.token, "projects_update", { network_id: NET, id, archived: true })).project.archived).toBe(true);
+    const seen = await rest(U.owner.token, "GET", `/api/requirements/projects?network_id=${NET}`);
+    expect(seen.body.projects.find((p: any) => p.id === id).archived).toBe(true);
+    expect((await mcp(U.owner.token, "projects_update", { network_id: NET, id, archived: false })).project.archived).toBe(false);
+  });
+
+  test("validation comes from the REST handler: duplicate name 409, unknown id 404", async () => {
+    await mcp(U.owner.token, "projects_create", { network_id: NET, name: "mpe-重名" });
+    const dup = await mcp(U.owner.token, "projects_create", { network_id: NET, name: "mpe-重名" });
+    expect(dup.ok).toBe(false);
+    expect(dup.status).toBe(409);
+    const missing = await mcp(U.owner.token, "projects_update", { network_id: NET, id: "proj_nobody", name: "x" });
+    expect(missing.status).toBe(404);
+  });
+
+  test("permission parity with the app's REST path, for every kind of caller", async () => {
+    const results: Record<string, { mcp: number; rest: number }> = {};
+    for (const who of ["owner", "member", "scoped", "viewer", "node"]) {
+      const name = `mpe-parity-${who}`;
+      const viaMcp = await mcp(U[who].token, "projects_create", { network_id: NET, name: `${name}-mcp` });
+      const viaRest = await rest(U[who].token, "POST", `/api/requirements/projects?network_id=${NET}`, { name: `${name}-rest` });
+      results[who] = { mcp: mcpStatus(viaMcp, 201), rest: viaRest.status };
+    }
+    for (const r of Object.values(results)) expect(r.mcp).toBe(r.rest);
+    // the rule itself (RFC-038 §9): task-scoped members and viewers can't manage projects; the others can
+    expect(results.owner.rest).toBe(201);
+    expect(results.member.rest).toBe(201);
+    expect(results.scoped.rest).toBe(403);
+    expect(results.viewer.rest).toBe(403);
+  });
+});
+
+describe("requirements_events", () => {
+  test("one task's timeline by id and by #N, same rows as GET /api/requirements/events", async () => {
+    const card = await rest(U.owner.token, "POST", "/api/requirements", { network_id: NET, name: "mpe-流水示例" });
+    expect(card.status).toBe(201);
+    const id = card.body.requirement.id as string, seq = card.body.requirement.seq as number;
+    expect((await rest(U.owner.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { priority: "high" })).status).toBe(200);
+    const viaMcp = await mcp(U.owner.token, "requirements_events", { network_id: NET, requirement_id: id });
+    const viaRest = await rest(U.owner.token, "GET", `/api/requirements/events?network_id=${NET}&requirement_id=${id}`);
+    expect(viaMcp.ok).toBe(true);
+    expect(viaMcp.events.length).toBeGreaterThan(0);
+    expect(viaMcp.events.map((e: any) => e.id)).toEqual(viaRest.body.events.map((e: any) => e.id));
+    expect(viaMcp.events.every((e: any) => e.requirement_id === id)).toBe(true);
+    const bySeq = await mcp(U.owner.token, "requirements_events", { network_id: NET, requirement_id: `#${seq}` });
+    expect(bySeq.events.map((e: any) => e.id)).toEqual(viaMcp.events.map((e: any) => e.id));
+    // paging / bad input come from the REST handler too
+    expect((await mcp(U.owner.token, "requirements_events", { network_id: NET, since: "not-a-date" })).status).toBe(400);
+    expect((await mcp(U.owner.token, "requirements_events", { network_id: NET, requirement_id: "#999999" })).status).toBe(404);
+  });
+
+  test("visibility parity: a task-scoped member doesn't get events for a task they can't see", async () => {
+    const hidden = await rest(U.owner.token, "POST", "/api/requirements", { network_id: NET, name: "mpe-看不见的" });
+    const id = hidden.body.requirement.id as string;
+    await rest(U.owner.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { priority: "low" });
+    for (const who of ["scoped", "member", "node"]) {
+      const viaMcp = await mcp(U[who].token, "requirements_events", { network_id: NET, requirement_id: id });
+      const viaRest = await rest(U[who].token, "GET", `/api/requirements/events?network_id=${NET}&requirement_id=${id}`);
+      expect((viaMcp.events ?? []).map((e: any) => e.id)).toEqual((viaRest.body?.events ?? []).map((e: any) => e.id));
+    }
+    expect((await mcp(U.scoped.token, "requirements_events", { network_id: NET, requirement_id: id })).events ?? []).toHaveLength(0);
+    expect((await mcp(U.member.token, "requirements_events", { network_id: NET, requirement_id: id })).events.length).toBeGreaterThan(0);
+  });
+});

package/src/node-health-passthrough.test.ts

@@ -0,0 +1,115 @@
+// #448 — report_status.health passthrough (layered node health, report-only).
+//
+// Hub-side contract verified here:
+//   1. A well-formed `health` from the node's own token is kept (memory-only) and readable.
+//   2. Malformed `health` never rejects the report — the node stays online, health reads as null.
+//   3. Another node / a user login cannot speak for this node's health.
+//   4. Stale (> TTL) health reads as null, never as "healthy".
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/node-health.db bun test src/node-health-passthrough.test.ts
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { clearNodeHealthStore, NODE_HEALTH_TTL_MS, readNodeHealth, recordNodeHealth } from "./node-health-store.js";
+
+const NET = "net_health_t";
+const OWNER = "u_health_owner";
+const NODE_A = "health-node-a";
+const NODE_B = "health-node-b";
+const NODE_A_ID = "node_health_a";
+const NODE_B_ID = "node_health_b";
+const T_A = "tok_health_node_a";
+const T_B = "tok_health_node_b";
+
+function cleanup() {
+  for (const t of ["sessions", "nodes", "api_tokens", "network_members", "networks"]) {
+    try { db.run(`DELETE FROM ${t} WHERE network_id = ?1`, [NET]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [OWNER]); } catch {}
+  clearNodeHealthStore();
+}
+function seed() {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`, [OWNER, OWNER]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [NET, NET, OWNER]);
+  db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [OWNER, NET]);
+  for (const [id, alias, tok] of [[NODE_A_ID, NODE_A, T_A], [NODE_B_ID, NODE_B, T_B]]) {
+    db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, ?5, datetime('now'), datetime('now'))`, [id, alias, alias, NET, OWNER]);
+    db.run(`INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at, bound_node_id) VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL, ?6)`, [tok, OWNER, NET, `node:${alias}`, `hash_${tok}`, id]);
+  }
+}
+
+async function connectAs(alias: string, tokenId: string) {
+  const server = new McpServer({ name: "health-test", version: "1" });
+  registerTools(server, undefined, NET, OWNER, alias, true, tokenId);
+  const client = new Client({ name: "health-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = async (args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name: "report_status", arguments: args });
+    return { isError: r.isError === true, body: JSON.parse(r.content?.[0]?.text ?? "null") };
+  };
+  return { call, close: async () => { await client.close(); await server.close(); } };
+}
+
+const HEALTH = {
+  bridge: "ok",
+  app_server: { ok: false, rtt_ms: null, last_error: "connection refused" },
+  tui: { ok: false, reason: "sleep-placeholder" },
+  model_auth: "revoked",
+};
+
+beforeEach(() => { cleanup(); seed(); });
+afterAll(cleanup);
+
+describe("#448 report_status.health passthrough", () => {
+  test("node's own token: stored and readable as reported", async () => {
+    const a = await connectAs(NODE_A, T_A);
+    try {
+      const r = await a.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID, health: HEALTH });
+      expect(r.isError).toBe(false);
+      expect(r.body.ok).not.toBe(false);
+    } finally { await a.close(); }
+    expect(readNodeHealth(NET, NODE_A)?.health).toEqual(HEALTH as any);
+  });
+
+  test("malformed health never rejects the report (node stays online); it reads as not reported", async () => {
+    const a = await connectAs(NODE_A, T_A);
+    try {
+      for (const bad of [42, "ok", { app_server: { ok: "yes" }, model_auth: "weird", tui: [] }, { app_server: { ok: true, rtt_ms: NaN, last_error: 5 } }]) {
+        const r = await a.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID, health: bad });
+        expect(r.isError).toBe(false);
+      }
+    } finally { await a.close(); }
+    expect(db.get<{ s: string }>("SELECT status AS s FROM sessions WHERE alias = ?1 AND network_id = ?2", NODE_A, NET)?.s).toBe("idle");
+    // 最后一份里 app_server.ok 合法、其余两格降级成 null —— 留下的是能证实的部分,不是编出来的。
+    expect(readNodeHealth(NET, NODE_A)?.health.app_server).toEqual({ ok: true, rtt_ms: null, last_error: null });
+  });
+
+  test("another node's token cannot speak for this node", async () => {
+    const b = await connectAs(NODE_B, T_B);
+    try {
+      await b.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID, health: HEALTH });
+    } finally { await b.close(); }
+    expect(readNodeHealth(NET, NODE_A)).toBeNull();
+  });
+
+  test("stale health reads as null, never as healthy", () => {
+    const t0 = 1_000_000;
+    recordNodeHealth(NET, NODE_A, { bridge: "ok", model_auth: "ok" }, t0);
+    expect(readNodeHealth(NET, NODE_A, t0 + 1_000)?.observed_ms_ago).toBe(1_000);
+    expect(readNodeHealth(NET, NODE_A, t0 + NODE_HEALTH_TTL_MS + 1)).toBeNull();
+  });
+
+  test("a report without health leaves the last one (heartbeats from older code paths do not erase it)", async () => {
+    const a = await connectAs(NODE_A, T_A);
+    try {
+      await a.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID, health: HEALTH });
+      await a.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "working", node_id: NODE_A_ID });
+    } finally { await a.close(); }
+    expect(readNodeHealth(NET, NODE_A)?.health.model_auth).toBe("revoked");
+  });
+});

package/src/node-health-store.ts

@@ -0,0 +1,57 @@
+// #448 —— agent-node 上报的分层健康(`report_status.health`)的 Hub 侧透传。
+//
+// 「在线」只说明桥进程还活着:现场 ~40 台 codex 共存节点里,有的在 Hub 上 idle / in_flight=0,
+// 实际 app-server 端口没人监听、TUI pane 变成 `sleep infinity`、或登录态 "refresh token revoked"。
+// 节点把这几层分开报上来;这里只负责**收下、按节点存最新一份、在 /api/status 和 status_update 里带出去**。
+//
+// 刻意只放内存,不加列:它是**几秒钟一变的观测值**,不是需要跨重启保留的状态 —— Hub 重启后下一次
+// 心跳(≤3 分钟,翻转时立即)就会补上;持久化一份旧观测值反而会在节点死掉后继续说「app_server ok」。
+// 同理,超过 TTL 的那份按「没报」处理(null),不按「健康」处理。
+
+import { z } from "zod/v4";
+
+export const NODE_HEALTH_TTL_MS = 10 * 60_000;
+
+// 🔴 `.catch(undefined)`:这一格是纯诊断信息,**任何形状都不许拒掉整份 report_status**
+//    (zod 对象里一个已知字段验证失败 = 整份被拒 = 节点在 Hub 上失联,#1225 的形状)。
+//    合法的透传,其余一律当没报。子对象不 strict:新节点多报的键丢掉即可。
+export const nodeHealthSchema = z.object({
+  bridge: z.literal("ok").optional(),
+  app_server: z.object({
+    ok: z.boolean(),
+    rtt_ms: z.number().nullable().catch(null),
+    last_error: z.string().max(200).nullable().catch(null),
+  }).optional().catch(undefined),
+  tui: z.object({
+    ok: z.boolean(),
+    reason: z.string().max(40),
+  }).optional().catch(undefined),
+  model_auth: z.enum(["ok", "revoked", "expired", "unknown"]).optional().catch(undefined),
+}).optional().catch(undefined);
+
+export type NodeHealth = NonNullable<z.infer<typeof nodeHealthSchema>>;
+
+const store = new Map<string, { health: NodeHealth; at: number }>();
+const keyOf = (networkId: string | null | undefined, alias: string) => `${networkId ?? "default"}\0${alias}`;
+
+export function recordNodeHealth(networkId: string | null | undefined, alias: string, health: NodeHealth, now = Date.now()): void {
+  store.set(keyOf(networkId, alias), { health, at: now });
+  // 有界:按 TTL 顺手清掉过期的,别让改过名/删掉的节点在内存里攒着。
+  if (store.size > 256) {
+    for (const [k, v] of store) if (now - v.at > NODE_HEALTH_TTL_MS) store.delete(k);
+  }
+}
+
+/** 最新一份;没有或已过 TTL → null(读的人必须把它当「不知道」,而不是「健康」)。 */
+export function readNodeHealth(
+  networkId: string | null | undefined, alias: string, now = Date.now(),
+): { health: NodeHealth; observed_ms_ago: number } | null {
+  const hit = store.get(keyOf(networkId, alias));
+  if (!hit) return null;
+  const age = now - hit.at;
+  if (age > NODE_HEALTH_TTL_MS) { store.delete(keyOf(networkId, alias)); return null; }
+  return { health: hit.health, observed_ms_ago: Math.max(0, age) };
+}
+
+/** 测试用。 */
+export function clearNodeHealthStore(): void { store.clear(); }

package/src/rest-explicit-columns-http.test.ts

@@ -46,6 +46,8 @@ const GOLDEN_RESPONSE_KEYS = {
     "process_in_flight_count", "network_id", "registered_at", "updated_at",
     "node_id", "session_id", "config_path", "channels", "last_seen_at", "model",
     "external_schedules", "rules_file_capable", "skills_capable", "files_capable", "logs_capable", "runtime", "host", "process_telemetry",
+    // #448 — layered node health (memory-only; null when not reported or stale).
+    "health", "health_observed_ms_ago",
   ],
   task: [
     "task_id", "from_node_id", "from_name", "to_node_id", "to_name", "priority",

package/src/server.ts

@@ -1,6 +1,7 @@
 import { buildServeErrorResponse } from "./serve-error.js";
 import { maybeGzipResponse, trimLightTask } from "./http-gzip";
 import { statusAliasResolverRead } from "./status-alias-resolver.js";
+import { readNodeHealth } from "./node-health-store.js";
 import { redactMessageRow } from "./redact-tokens.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { parseDbTimestampMs } from "./db-timestamp.js";
@@ -2297,6 +2298,12 @@ return Bun.serve({
             uptime_seconds: s.process_uptime_seconds ?? null,
             in_flight_count: s.process_in_flight_count ?? null,
           },
+          // #448 — latest layered health the node reported (memory-only, 10 min TTL);
+          // null = not reported / stale / older agent-node — never "healthy".
+          ...(() => {
+            const h = readNodeHealth(s.network_id, s.alias);
+            return { health: h?.health ?? null, health_observed_ms_ago: h?.observed_ms_ago ?? null };
+          })(),
         };
       });
       const summary = sessions.reduce((acc: any, session: any) => {

package/src/tools.ts

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { parseDbTimestampMs } from "./db-timestamp.js";
 import { z } from "zod/v4";
+import { nodeHealthSchema, recordNodeHealth } from "./node-health-store.js";
 import { parseAliasFilter } from "./alias-filter.js";
 import { createHash } from "node:crypto";
 import { db, uuidv4, logTaskEvent, chainReplyToParent, hashToken, generateId, generateNetworkToken, syncScheduledRunForTask } from "./db.js";
@@ -827,8 +828,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       files_capable: z.literal(true).optional(),
       // Node run-log view — same doorbell, op logs_tail.
       logs_capable: z.literal(true).optional(),
+      // #448 — layered node health (bridge / app_server / tui / model_auth).
+      // Report-only, memory-only; any malformed shape degrades to "not reported"
+      // instead of rejecting the whole report (see node-health-store.ts).
+      health: nodeHealthSchema,
     },
-    async ({ resume_id, alias, status, task, output, score, progress, server: srv, hostname: hn, agent: ag, project_dir: pd, version: ver, tmux_name: tmux, node_id, session_id, config_path, channels, model: mdl, node_name: nn, network_id: netId, host, process_telemetry: proc, external_schedules: externalSchedules, config_snapshot: cfgSnap, rules_file_capable: rulesFileCapable, skills_capable: skillsCapable, files_capable: filesCapable, logs_capable: logsCapable }) => {
+    async ({ resume_id, alias, status, task, output, score, progress, server: srv, hostname: hn, agent: ag, project_dir: pd, version: ver, tmux_name: tmux, node_id, session_id, config_path, channels, model: mdl, node_name: nn, network_id: netId, host, process_telemetry: proc, external_schedules: externalSchedules, config_snapshot: cfgSnap, rules_file_capable: rulesFileCapable, skills_capable: skillsCapable, files_capable: filesCapable, logs_capable: logsCapable, health: nodeHealth }) => {
       const effectiveNetId = getNetworkId(netId);
       const sessionNetId = effectiveNetId ?? "default";
       if (!callerTokenIsNetwork || !enforceNetworkId) {
@@ -1051,6 +1056,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           );
         }
       });
+      // #448 — only the node token bound to this alias may speak for its health
+      // (same rule as the *_capable flags above).
+      const acceptedHealth = nodeHealth && callerTokenIsNetwork && callerAlias && callerAlias === effectiveAlias
+        ? nodeHealth
+        : undefined;
+      if (acceptedHealth) recordNodeHealth(sessionNetId, effectiveAlias, acceptedHealth);
       pushEvent(effectiveAlias, {
         type: "status_update",
         alias: effectiveAlias,
@@ -1059,6 +1070,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         progress: progress ?? null,
         host: statusHostTelemetry,
         process_telemetry: statusProcessTelemetry,
+        ...(acceptedHealth ? { health: acceptedHealth } : {}),
       }, sessionNetId);
 
       // V2: sync tasks table — report_status(working) → tasks.running
@@ -5888,10 +5900,67 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "projects_list",
-    "List requirement projects in your network (id, name, color, sort, archived).",
+    "List requirement projects in your network (id, name, color, sort, archived). Manage them with projects_create / projects_update.",
     { network_id: z.string().max(200).optional() },
     async ({ network_id }) => requirementsCall("GET", "/api/requirements/projects", network_id),
   );
+
+  // Agent parity (app task audit 2026-10-02 M3): what people do under 管理项目 and the task 动态 timeline. Both go
+  // through the same REST handlers as the app, so every permission check is the app's own: project management needs
+  // write access and is refused to 「仅相关任务」(task-scoped) members; events use the task list's visibility.
+  server.tool(
+    "projects_create",
+    "Create a requirement project in your network (same as 管理项目 → 新建 in the app). name 1–40 characters, unique in the network; color #RRGGBB (default: next palette colour); sort integer. Returns { project }. Refused (403) for task-scoped members and read-only roles.",
+    {
+      network_id: z.string().max(200).optional(),
+      name: z.string().min(1).max(40),
+      color: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
+      sort: z.number().int().optional(),
+    },
+    async (args) => requirementsCall("POST", "/api/requirements/projects", args.network_id, pick(args, ["name", "color", "sort"])),
+  );
+
+  server.tool(
+    "projects_update",
+    "Rename, recolour, reorder, archive or unarchive a requirement project (same as 管理项目 in the app). Only the fields you pass change. archived=true hides it from pickers (its tasks keep project_id); archived=false brings it back. Returns { project }. Refused (403) for task-scoped members and read-only roles.",
+    {
+      network_id: z.string().max(200).optional(),
+      id: z.string().min(1).max(200).describe("project id (proj_…), from projects_list"),
+      name: z.string().min(1).max(40).optional(),
+      color: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
+      sort: z.number().int().optional(),
+      archived: z.boolean().optional(),
+    },
+    async (args) => requirementsCall("PATCH", `/api/requirements/projects/${encodeURIComponent(args.id)}`, args.network_id, pick(args, ["name", "color", "sort", "archived"])),
+  );
+
+  server.tool(
+    "requirements_events",
+    "Read the task activity timeline (the app's 动态): field-level changes — who, when, old → new — newest first. Pass requirement_id (req_… or \"#N\") for one task, or omit it for the whole network. since (ISO) = only changes after it; limit 1–500 (default 200); next_cursor → pass as cursor for the next page; server_time → use as the next since. Same visibility as requirements_list: tasks you can't see (and hidden Agents) are left out.",
+    {
+      network_id: z.string().max(200).optional(),
+      requirement_id: z.string().min(1).max(200).optional(),
+      since: z.string().max(40).optional(),
+      limit: z.number().int().min(1).max(500).optional(),
+      cursor: z.string().max(20).optional(),
+    },
+    async (args) => {
+      let card = args.requirement_id;
+      // "#N" → the card's id, resolved exactly like requirements_get (same scope; a card you can't see is a 404 here too).
+      if (card && /^#\d+$/.test(card)) {
+        const got = await requirementsCall("GET", `/api/requirements/${encodeURIComponent(card)}`, args.network_id);
+        const parsed = JSON.parse(got.content[0].text) as { requirement?: { id?: string } };
+        if (!parsed.requirement?.id) return got;
+        card = parsed.requirement.id;
+      }
+      const q = new URLSearchParams();
+      if (card) q.set("requirement_id", card);
+      if (args.since) q.set("since", args.since);
+      if (args.limit !== undefined) q.set("limit", String(args.limit));
+      if (args.cursor) q.set("cursor", args.cursor);
+      return requirementsCall("GET", `/api/requirements/events${q.size ? `?${q}` : ""}`, args.network_id);
+    },
+  );
 }
 
 // ────────────────────────────────────────────────────────────────────