@sleep2agi/commhub-server 0.9.0-preview.38 → 0.9.0-preview.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.38",
+  "version": "0.9.0-preview.39",
   "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/create-node.ts

@@ -318,6 +318,8 @@ export function auditCreateNode(input: {
     // wider migration (see P1.1 issue).
     | "stop_node_dispatched"
     | "stop_node_completed"
+    | "start_node_dispatched"
+    | "start_node_completed"
     | "delete_node_dispatched"
     | "delete_node_completed"
     | "forced_stop_with_in_flight"

package/src/db.ts

@@ -432,6 +432,36 @@ db.exec(`
 db.exec(`CREATE INDEX IF NOT EXISTS idx_stop_req_daemon ON node_stop_requests(daemon_node_id, status)`);
 db.exec(`CREATE INDEX IF NOT EXISTS idx_stop_req_child ON node_stop_requests(child_node_id)`);
 
+// Daemon-mediated start request. Kept separate from node_stop_requests:
+// the deployed stop table has a CHECK(action IN ('stop','delete')) and
+// rebuilding that table in-place would be a risky migration for an additive
+// lifecycle operation.
+db.exec(`
+  CREATE TABLE IF NOT EXISTS node_start_requests (
+    request_id TEXT PRIMARY KEY,
+    network_id TEXT NOT NULL,
+    daemon_node_id TEXT NOT NULL,
+    child_node_id TEXT NOT NULL,
+    child_alias TEXT NOT NULL,
+    created_by_token TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    error TEXT,
+    child_pid INTEGER,
+    created_at INTEGER NOT NULL,
+    delivered_at INTEGER,
+    acked_at INTEGER
+  )
+`);
+db.exec(`CREATE INDEX IF NOT EXISTS idx_start_req_daemon ON node_start_requests(daemon_node_id, status)`);
+db.exec(`CREATE INDEX IF NOT EXISTS idx_start_req_child ON node_start_requests(child_node_id)`);
+try {
+  db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS uniq_start_req_child_inflight
+             ON node_start_requests(child_node_id)
+          WHERE status IN ('pending', 'delivered')`);
+} catch (e: any) {
+  if (!/unique constraint/i.test(e?.message || "")) throw e;
+}
+
 // `node_config_updates` — pending + history. One row per dashboard write.
 // At most one row per node may be in a non-terminal state at a time
 // (single-flight enforced at the tool layer; this table just stores).

package/src/inbox-count-sse.test.ts

@@ -0,0 +1,310 @@
+// SSE `inbox_count` contract for the message-shaped events.
+//
+// Background: `new_task` has shipped a real unacked count since #1304,
+// but `new_message` / `new_reply` carried NO count at all and
+// `broadcast` carried a hardcoded `inbox_count: 1`. A client that
+// renders "N new" from the SSE payload therefore never moved for plain
+// messages and replies, and showed a constant 1 for broadcasts.
+//
+// Gate discipline: every assertion below expects a count that is NOT 1
+// (pre-seeded unacked rows push the expected value to 2 or 3). A
+// hardcoded `1` — the exact defect being fixed — fails these tests
+// rather than passing them. Asserting `=== 1` would have been a fake
+// gate that the old code satisfied.
+//
+// Run: COMMHUB_DB=/tmp/inbox-count-sse.db bun test src/inbox-count-sse.test.ts
+
+import { afterAll, beforeEach, afterEach, describe, expect, test } from "bun:test";
+import { db, uuidv4 } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+import { __resetSSEClientsForTest, createSSEStream } from "./push.js";
+import { pendingInboxCount } from "./inbox-count.js";
+
+const NET = "net_inboxcount";
+const OWNER = "u_inboxcount_owner";
+const RECV = "peer-inboxcount-recv";   // receives messages/replies
+const OTHER = "peer-inboxcount-other"; // second broadcast recipient
+const SENDER = "peer-inboxcount-send";
+// #1440 ① — a broadcast target the lifecycle guard skips.
+const STOPPED = "peer-inboxcount-stopped";
+const ALIASES = [RECV, OTHER, SENDER];
+
+type ToolHandler = (args: any, extra?: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function cleanup() {
+  for (const t of ["tasks", "inbox", "task_events"]) {
+    try { db.run(`DELETE FROM ${t} WHERE network_id = ?1`, [NET]); } catch {}
+  }
+  try { db.run("DELETE FROM sessions WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM nodes WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [OWNER]); } catch {}
+}
+
+function seed() {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?1, 'x', 'user', datetime('now'))`,
+    [OWNER],
+  );
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [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 alias of ALIASES) {
+    db.run(
+      `INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state)
+       VALUES (?1, ?2, ?2, ?3, ?4, datetime('now'), datetime('now'), 'active')`,
+      [`node_${alias}`, alias, NET, `host-${alias}`],
+    );
+    db.run(
+      `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+       VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))`,
+      [`res_${alias}`, alias, `node_${alias}`, NET],
+    );
+  }
+  // A session that broadcast will select as a target, but whose node is
+  // NOT active — assertNodeActive skips it, so it gets no inbox row.
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?2, ?3, ?4, datetime('now'), datetime('now'), 'stopped')`,
+    [`node_${STOPPED}`, STOPPED, NET, `host-${STOPPED}`],
+  );
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+     VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))`,
+    [`res_${STOPPED}`, STOPPED, `node_${STOPPED}`, NET],
+  );
+}
+
+beforeEach(() => { cleanup(); seed(); });
+afterEach(() => { __resetSSEClientsForTest(); });
+afterAll(cleanup);
+
+function buildHandlers(alias: string): Record<string, ToolHandler> {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, _desc: string, schema: any, handler: ToolHandler) => {
+    tools[name] = handler;
+    return origTool(name, _desc, schema, handler);
+  };
+  registerTools(server, undefined, NET, OWNER, alias, true, null);
+  return tools;
+}
+
+async function call(handler: ToolHandler, args: any): Promise<Record<string, any>> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text);
+}
+
+/** Read the next SSE data frame, with a hard timeout so a silent stream
+ *  fails instead of hanging. Skips keepalive comment frames. */
+async function readFrame(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  timeoutMs = 2_000,
+): Promise<Record<string, any>> {
+  const decoder = new TextDecoder();
+  let buf = "";
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const result = await Promise.race([
+      reader.read(),
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error(`no SSE frame within ${timeoutMs}ms`)), deadline - Date.now()),
+      ),
+    ]);
+    if (result.done) throw new Error("SSE stream ended unexpectedly");
+    buf += decoder.decode(result.value, { stream: true });
+    const sep = buf.indexOf("\n\n");
+    if (sep === -1) continue;
+    const rawFrame = buf.slice(0, sep);
+    buf = buf.slice(sep + 2);
+    const dataLine = rawFrame.split("\n").find((l) => l.startsWith("data: "));
+    if (!dataLine) continue;
+    return JSON.parse(dataLine.slice(6));
+  }
+  throw new Error(`no SSE frame within ${timeoutMs}ms`);
+}
+
+/** Subscribe and swallow the initial `connected` frame. */
+async function subscribe(alias: string) {
+  const reader = createSSEStream(alias, NET).body!.getReader();
+  await readFrame(reader);
+  return reader;
+}
+
+/** Pre-existing unacked inbox rows, so the expected count is never 1. */
+function seedUnacked(alias: string, n: number, type = "message") {
+  for (let i = 0; i < n; i++) {
+    db.run(
+      `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id)
+       VALUES (?1, ?2, ?3, ?4, 'normal', ?5, ?6, ?7)`,
+      [uuidv4(), alias, `node_${alias}`, type, `backlog ${i}`, SENDER, NET],
+    );
+  }
+}
+
+function makeTask(from: string, to: string, content: string, status = "delivered"): string {
+  const id = uuidv4();
+  db.run(
+    `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response, created_at, network_id)
+     VALUES (?1, ?2, ?3, 'normal', ?4, ?5, 'reply', datetime('now'), ?6)`,
+    [id, from, to, status, content, NET],
+  );
+  return id;
+}
+
+describe("SSE inbox_count", () => {
+  test("new_message carries the recipient's real unacked count, not a hardcoded 1", async () => {
+    seedUnacked(RECV, 2);
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.send_message, { alias: RECV, message: "hello", network_id: NET });
+    expect(res.ok ?? true).not.toBe(false);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_message");
+    // 2 seeded + this one. A hardcoded 1 — or a missing field — fails here.
+    expect(evt.inbox_count).toBe(3);
+    expect(evt.inbox_count).toBe(pendingInboxCount(RECV, NET));
+  });
+
+  test("new_reply carries the reply target's real unacked count", async () => {
+    seedUnacked(RECV, 1);
+    const taskId = makeTask(RECV, SENDER, "please do the thing");
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.send_reply, {
+      alias: RECV,
+      text: "done",
+      in_reply_to: taskId,
+      status: "completed",
+      network_id: NET,
+    });
+    expect(res.ok).toBe(true);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_reply");
+    // 1 seeded + the reply row. Not 1, and not absent.
+    expect(evt.inbox_count).toBe(2);
+    expect(evt.inbox_count).toBe(pendingInboxCount(RECV, NET));
+  });
+
+  test("broadcast counts per recipient instead of shipping a constant 1", async () => {
+    // Asymmetric backlogs: if the payload were hardcoded, both
+    // recipients would report the same number. They must not.
+    seedUnacked(RECV, 2);
+    const recvReader = await subscribe(RECV);
+    const otherReader = await subscribe(OTHER);
+
+    const tools = buildHandlers(SENDER);
+    await call(tools.broadcast, { message: "all hands", network_id: NET });
+
+    const recvEvt = await readFrame(recvReader);
+    const otherEvt = await readFrame(otherReader);
+    expect(recvEvt.type).toBe("broadcast");
+    expect(otherEvt.type).toBe("broadcast");
+
+    // RECV: 2 seeded + the broadcast row. OTHER: only the broadcast row.
+    expect(recvEvt.inbox_count).toBe(3);
+    expect(otherEvt.inbox_count).toBe(1);
+    expect(recvEvt.inbox_count).not.toBe(otherEvt.inbox_count);
+  });
+
+  test("acked rows are excluded — the count tracks what is still unread", async () => {
+    seedUnacked(RECV, 3);
+    db.run("UPDATE inbox SET acked = 1 WHERE session_name = ?1 AND network_id = ?2", [RECV, NET]);
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    await call(tools.send_message, { alias: RECV, message: "after the catch-up", network_id: NET });
+
+    const evt = await readFrame(reader);
+    // 3 acked rows contribute nothing; only the new one is outstanding.
+    expect(evt.inbox_count).toBe(1);
+  });
+});
+
+// #1440 ② — `retry_task` and `reassign_task` re-queue a task and push
+// `new_task`, but both shipped a hardcoded `inbox_count: 1` while the
+// hub already knew the real number. Same defect family as the
+// `broadcast` case above; same gate discipline — the expected counts
+// here are 3, so a hardcoded 1 cannot satisfy them.
+describe("#1440 new_task inbox_count on requeue paths", () => {
+  test("retry_task carries the real unacked count, not a hardcoded 1", async () => {
+    seedUnacked(RECV, 2);
+    const taskId = makeTask(SENDER, RECV, "flaky job", "failed");
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.retry_task, { task_id: taskId, network_id: NET });
+    expect(res.ok).toBe(true);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_task");
+    // 2 seeded + the re-queued task row.
+    expect(evt.inbox_count).toBe(3);
+    expect(evt.inbox_count).toBe(pendingInboxCount(RECV, NET));
+  });
+
+  test("reassign_task carries the NEW assignee's real unacked count", async () => {
+    seedUnacked(RECV, 2);
+    const taskId = makeTask(SENDER, OTHER, "moved job");
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.reassign_task, { task_id: taskId, new_alias: RECV, network_id: NET });
+    expect(res.ok).toBe(true);
+    expect(res.reassigned_to).toBe(RECV);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_task");
+    // 2 seeded on the new assignee + the row reassign just wrote.
+    expect(evt.inbox_count).toBe(3);
+    expect(evt.inbox_count).toBe(pendingInboxCount(RECV, NET));
+  });
+});
+
+// #1440 ① — the broadcast push loop walked every candidate target,
+// including the ones assertNodeActive had just skipped. Those nodes
+// were told "you have a broadcast" while their inbox got no row for it.
+// Before #1439 the hardcoded `inbox_count: 1` hid this: everyone got
+// the same digit, so a spurious event was indistinguishable from a real
+// one.
+describe("#1440 broadcast delivery set", () => {
+  test("a lifecycle-skipped node gets no inbox row AND no broadcast event", async () => {
+    const activeReader = await subscribe(OTHER);
+    const stoppedReader = await subscribe(STOPPED);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.broadcast, { message: "all hands", network_id: NET });
+
+    // The active recipient is served — this proves the broadcast ran, so
+    // the absence checked below is "not sent", not "not yet sent"
+    // (pushEvent is synchronous inside the handler).
+    const activeEvt = await readFrame(activeReader);
+    expect(activeEvt.type).toBe("broadcast");
+
+    // The skipped node has no row...
+    const rows = db.get<{ cnt: number }>(
+      "SELECT COUNT(*) AS cnt FROM inbox WHERE session_name = ?1 AND type = 'broadcast'",
+      STOPPED,
+    );
+    expect(rows?.cnt).toBe(0);
+    // ...and must therefore receive no event announcing one.
+    await expect(readFrame(stoppedReader, 300)).rejects.toThrow(/no SSE frame/);
+
+    // message_ids covers only the recipients that actually got a row:
+    // RECV + OTHER + SENDER, never STOPPED.
+    expect(res.message_ids).toHaveLength(3);
+    // #1440 ③ — `recipients` counted candidates, not deliveries, so it
+    // disagreed with the documented invariant
+    // ("message_ids.length === recipients", docs-site/docs/api/rest.md)
+    // exactly when a node was skipped. 4 sessions, 3 delivered.
+    expect(res.recipients).toBe(res.message_ids.length);
+    expect(res.recipients).toBe(3);
+  });
+});

package/src/inbox-count.ts

@@ -0,0 +1,29 @@
+import { db } from "./db.js";
+
+/**
+ * Unacked inbox rows for `alias` — the number a client should show as
+ * "new". This is the count `new_task` has shipped since #1304; it is
+ * lifted here verbatim so every SSE event that carries `inbox_count`
+ * derives it the same way instead of hardcoding a digit.
+ *
+ * The SQL and its network scoping are unchanged from the `new_task`
+ * sites (tools.ts / server.ts): falsy `networkId` means "no network
+ * filter", matching both `addScope()` and the inline `if (taskNetId)`
+ * guard those sites already use.
+ *
+ * The `?? 1` fallback only fires if the COUNT itself returns no row,
+ * which SQLite does not do. It is not a default count: it is the
+ * fail-closed direction for this gate. Every caller pushes right after
+ * inserting an inbox row, so the floor is genuinely 1, and under-
+ * reporting an unread (badge says 0, a message is sitting there) is the
+ * failure this event exists to prevent.
+ */
+export function pendingInboxCount(alias: string, networkId?: string | null): number {
+  const params: any[] = [alias];
+  let sql = "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
+  if (networkId) {
+    sql += " AND network_id = ?2";
+    params.push(networkId);
+  }
+  return db.get<{ cnt: number }>(sql, ...params)?.cnt ?? 1;
+}

package/src/node-id-alias.test.ts

@@ -0,0 +1,147 @@
+// #1281 — 子节点生命周期工具的参数名统一（node_id ⇄ child_node_id）。
+//
+// 分叉现状（origin/main 2976adb2）：stop_node / start_node / delete_node 用
+// `child_node_id`，restart_node / update_node_config 用 `node_id`，指向同一个
+// 子节点。调用方按一个工具的习惯给另一个传就吃 -32602。修复：5 个工具都同时
+// 接受两个名字（canonical = node_id，child_node_id 兼容 alias），解析收敛到一个
+// 模块级 helper resolveNodeIdArg。
+//
+// 两向 witnessed-red（本文件即判据）：
+//   · schema 层：每个工具的**历史用名**始终 parse 成功（证明没破已发布契约），
+//     **新增别名**在修复前 parse 失败（缺必填字段）、修复后成功。
+//   · handler 层：resolveNodeIdArg 纯函数 —— 二选一至少一必填、都传须相等。
+//   · 真实 handler 路径：stop_node 用 node_id / child_node_id 都能穿到
+//     resolveDaemonForChild（不再被 node_id_required 挡），都传冲突 → node_id_conflict。
+//
+// 对 pre-fix 见红的证明方式（评审可复现）：把 tools.ts 里任一工具的
+// `...NODE_ID_ALIAS_FIELDS` 还原成原来的单名字段（如 stop_node 的
+// `child_node_id: z.string()...regex(...)`），本文件对应工具的「新增别名 parse 成功」
+// 断言立即变红 —— 证明该断言有判别力，不是恒真。
+
+import { describe, expect, test, beforeAll } from "bun:test";
+import { mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+process.env.COMMHUB_DB = process.env.COMMHUB_DB || (mkdtempSync(join(tmpdir(), "anet-1281-")) + "/commhub.db");
+
+import { z } from "zod/v4";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools, resolveNodeIdArg } from "./tools.js";
+
+type ToolHandler = (args: any) => Promise<{ content: { type: "text"; text: string }[] }>;
+
+// Capture BOTH the raw zod shape and the handler for every tool, so the
+// schema-layer assertions run against the exact object server.tool received.
+function buildCaptured() {
+  const schemas: Record<string, any> = {};
+  const handlers: Record<string, ToolHandler> = {};
+  const server = new McpServer({ name: "t1281", version: "0" }) as any;
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, _desc: string, schema: any, handler: ToolHandler) => {
+    schemas[name] = schema; handlers[name] = handler;
+    return origTool(name, _desc, schema, handler);
+  };
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, cfg: any, handler: ToolHandler) => {
+      schemas[name] = cfg?.inputSchema ?? cfg; handlers[name] = handler;
+      return origRegisterTool(name, cfg, handler);
+    };
+  }
+  registerTools(server, undefined, null, "user_1281", null, false, null);
+  return { schemas, handlers };
+}
+
+let SCHEMAS: Record<string, any> = {};
+let HANDLERS: Record<string, ToolHandler> = {};
+beforeAll(() => { const c = buildCaptured(); SCHEMAS = c.schemas; HANDLERS = c.handlers; });
+
+async function call(name: string, args: any) {
+  const r = await HANDLERS[name](args);
+  return JSON.parse(r.content[0].text);
+}
+
+// Per tool: the historically-required id name, the newly-added alias, and
+// the OTHER required fields the shape needs so a safeParse isolates the id
+// field rather than tripping on an unrelated missing field.
+const TOOLS = [
+  { name: "stop_node",          historic: "child_node_id", added: "node_id",        extra: {} },
+  { name: "start_node",         historic: "child_node_id", added: "node_id",        extra: {} },
+  { name: "delete_node",        historic: "child_node_id", added: "node_id",        extra: { confirm_alias: "some-alias" } },
+  { name: "restart_node",       historic: "node_id",       added: "child_node_id",  extra: {} },
+  { name: "update_node_config", historic: "node_id",       added: "child_node_id",  extra: { base_revision: 0, patch: {} } },
+];
+
+const VALID_ID = "node_test_1281";
+
+describe("#1281 schema layer — every lifecycle tool accepts BOTH node_id and child_node_id", () => {
+  for (const t of TOOLS) {
+    test(`${t.name}: historic name '${t.historic}' still parses (published contract intact)`, () => {
+      const shape = z.object(SCHEMAS[t.name]);
+      const r = shape.safeParse({ [t.historic]: VALID_ID, ...t.extra });
+      expect(r.success).toBe(true);
+    });
+
+    test(`${t.name}: added alias '${t.added}' parses (was -32602 pre-#1281 → RED without the fix)`, () => {
+      const shape = z.object(SCHEMAS[t.name]);
+      const r = shape.safeParse({ [t.added]: VALID_ID, ...t.extra });
+      expect(r.success).toBe(true);
+    });
+
+    test(`${t.name}: both names present + equal parses (schema layer permissive; conflict caught in handler)`, () => {
+      const shape = z.object(SCHEMAS[t.name]);
+      const r = shape.safeParse({ node_id: VALID_ID, child_node_id: VALID_ID, ...t.extra });
+      expect(r.success).toBe(true);
+    });
+  }
+});
+
+describe("#1281 resolveNodeIdArg — the single resolution helper", () => {
+  test("node_id only → resolves to node_id", () => {
+    expect(resolveNodeIdArg({ node_id: "node_a" })).toEqual({ ok: true, node_id: "node_a" });
+  });
+  test("child_node_id only → resolves to it (back-compat)", () => {
+    expect(resolveNodeIdArg({ child_node_id: "node_b" })).toEqual({ ok: true, node_id: "node_b" });
+  });
+  test("both present + EQUAL → resolves (no conflict)", () => {
+    expect(resolveNodeIdArg({ node_id: "node_c", child_node_id: "node_c" })).toEqual({ ok: true, node_id: "node_c" });
+  });
+  test("both present + DIFFERENT → node_id_conflict (catches A/B fat-finger)", () => {
+    const r = resolveNodeIdArg({ node_id: "node_a", child_node_id: "node_b" });
+    expect(r.ok).toBe(false);
+    expect((r as any).error).toBe("node_id_conflict");
+  });
+  test("neither present → node_id_required", () => {
+    const r = resolveNodeIdArg({});
+    expect(r.ok).toBe(false);
+    expect((r as any).error).toBe("node_id_required");
+  });
+});
+
+describe("#1281 real handler path — stop_node routes both names to the same place", () => {
+  // stop_node calls resolveNodeIdArg FIRST, then resolveDaemonForChild. A
+  // fabricated id has no create-request row → daemon_not_resolvable. The
+  // point is that BOTH names get PAST the id gate to that same downstream
+  // error (proving the alias flows through), and the two error branches fire.
+  test("node_id (new name) flows through → daemon_not_resolvable, NOT node_id_required", async () => {
+    const r = await call("stop_node", { node_id: VALID_ID });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("daemon_not_resolvable");
+  });
+  test("child_node_id (old name) flows through → daemon_not_resolvable (back-compat intact)", async () => {
+    const r = await call("stop_node", { child_node_id: VALID_ID });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("daemon_not_resolvable");
+  });
+  test("neither → node_id_required (before any daemon resolution)", async () => {
+    const r = await call("stop_node", { force: true });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("node_id_required");
+  });
+  test("both differ → node_id_conflict (before any daemon resolution)", async () => {
+    const r = await call("stop_node", { node_id: "node_a", child_node_id: "node_b" });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("node_id_conflict");
+  });
+});

package/src/server.ts

@@ -9,6 +9,7 @@ import { registerTools } from "./tools.js";
 import { db, logTaskEvent, logAudit, syncScheduledRunForTask } from "./db.js";
 import { createSSEStream, createNetworkObserverStream, createUserEventStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
+import { pendingInboxCount } from "./inbox-count.js";
 import { addNetworkScope, canRestWriteNetwork, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { validateAvatarUrl } from "./avatar-validate.js";
 import { narrowTags, parseStoredTags, validateScalarAttr } from "./node-attrs-validate.js";
@@ -2549,6 +2550,9 @@ return Bun.serve({
       if (body.filter_status) { sql += " AND status = ?"; params.push(body.filter_status); }
       const targets = db.all<{ alias: string; node_id: string | null; network_id: string | null }>(sql, ...params);
       const ids: string[] = [];
+      // #1440 ① — mirrors the MCP handler: push to the recipients that
+      // actually got an inbox row, not to every candidate target.
+      const delivered: Array<{ alias: string; netId: string | null }> = [];
       for (const t of targets) {
         // RFC-027 §2.3 inbox-enqueue lifecycle guard (PR1.2a REST site
         // 2/2). Broadcast skips non-active recipients silently per its
@@ -2563,11 +2567,12 @@ return Bun.serve({
           [id, t.alias, t.node_id ?? null, body.message, t.network_id]
         );
         ids.push(id);
+        delivered.push({ alias: t.alias, netId: t.network_id });
       }
-      for (const t of targets) {
-        pushEvent(t.alias, { type: "broadcast", inbox_count: 1 }, t.network_id);
+      for (const d of delivered) {
+        pushEvent(d.alias, { type: "broadcast", inbox_count: pendingInboxCount(d.alias, d.netId) }, d.netId);
       }
-      return withCors(req, Response.json({ ok: true, recipients: targets.length, message_ids: ids }));
+      return withCors(req, Response.json({ ok: true, recipients: ids.length, message_ids: ids }));
     }
 
     // ── REST: tmux capture-pane ──

package/src/start-node.test.ts

@@ -0,0 +1,52 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+
+const NET = "net_start_node"; const USER = "u_start_node";
+const DAEMON = "node_start_daemon"; const DAEMON_ALIAS = "start-daemon";
+const CHILD = "node_start_child"; const CHILD_ALIAS = "start-child";
+
+function cleanup() {
+  for (const table of ["node_start_requests", "node_create_requests", "audit_log", "nodes", "api_tokens", "network_members", "networks"]) {
+    try { db.run(`DELETE FROM ${table} WHERE network_id = ?1`, [NET]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id=?1", USER); } catch {}
+}
+beforeEach(() => { cleanup();
+  db.run(`INSERT INTO users(user_id,username,password_hash,role,created_at) VALUES(?1,?1,'x','user',datetime('now'))`, USER);
+  db.run(`INSERT INTO networks(network_id,network_name,owner_id,created_at) VALUES(?1,?1,?2,datetime('now'))`, [NET, USER]);
+  db.run(`INSERT INTO network_members(user_id,network_id,role,joined_at) VALUES(?1,?2,'owner',datetime('now'))`, [USER, NET]);
+  db.run(`INSERT INTO nodes(node_id,node_name,alias,network_id,config_snapshot,hostname,created_at,updated_at,lifecycle_state) VALUES(?1,?2,?2,?3,'{}','h',datetime('now'),datetime('now'),'active')`, [DAEMON, DAEMON_ALIAS, NET]);
+  db.run(`INSERT INTO nodes(node_id,node_name,alias,network_id,config_snapshot,hostname,created_at,updated_at,lifecycle_state) VALUES(?1,?2,?2,?3,'{}','h',datetime('now'),datetime('now'),'stopped')`, [CHILD, CHILD_ALIAS, NET]);
+  db.run(`INSERT INTO api_tokens(token_id,user_id,network_id,scope,name,token_hash) VALUES('tok_start_daemon',?1,?2,'network',?3,'h')`, [USER, NET, `node:${DAEMON_ALIAS}`]);
+  db.run(`INSERT INTO node_create_requests(request_id,daemon_node_id,child_name,network_id,runtime,model,flags_json,env_keys,status,created_at,created_by_token,child_node_id) VALUES('cr_start_child',?1,?2,?3,'codex-sdk','x','{}','[]','succeeded',1,'t',?4)`, [DAEMON, CHILD_ALIAS, NET, CHILD]);
+});
+afterAll(cleanup);
+
+function handlers(user: string | null, daemon = false) {
+  const s = new McpServer({ name: "t", version: "0" }) as any; const out: any = {};
+  const orig = s.tool.bind(s); s.tool = (n: string, d: string, schema: any, h: any) => { out[n] = h; return orig(n,d,schema,h); };
+  registerTools(s, undefined, daemon ? NET : null, user, null, daemon, daemon ? "tok_start_daemon" : null); return out;
+}
+async function call(h: any, args: any) { return JSON.parse((await h(args)).content[0].text); }
+
+describe("start_node Hub -> daemon lifecycle", () => {
+  test("dispatch, authenticated pull, ack transitions stopped -> starting -> active", async () => {
+    const u = handlers(USER); const dispatch = await call(u.start_node, { child_node_id: CHILD, network_id: NET });
+    expect(dispatch.ok).toBe(true); expect(dispatch.lifecycle_state).toBe("starting");
+    const d = handlers(null, true); const pulled = await call(d.get_start_request, { request_id: dispatch.request_id });
+    expect(pulled).toMatchObject({ ok: true, child_node_id: CHILD, child_alias: CHILD_ALIAS });
+    const ack = await call(d.ack_start_request, { request_id: dispatch.request_id, status: "started", child_pid: 4321 });
+    expect(ack.ok).toBe(true);
+    expect(db.get<any>(`SELECT lifecycle_state FROM nodes WHERE node_id=?1`, CHILD)?.lifecycle_state).toBe("active");
+    expect(db.all<any>(`SELECT action FROM audit_log WHERE target_id=?1 ORDER BY id`, dispatch.request_id).map((x:any)=>x.action)).toEqual(["start_node_dispatched", "start_node_completed"]);
+  });
+  test("active child and caller-supplied wrong daemon fail closed", async () => {
+    const u = handlers(USER);
+    db.run(`UPDATE nodes SET lifecycle_state='active' WHERE node_id=?1`, CHILD);
+    expect((await call(u.start_node, { child_node_id: CHILD, network_id: NET })).error).toBe("node_not_stopped");
+    db.run(`UPDATE nodes SET lifecycle_state='stopped' WHERE node_id=?1`, CHILD);
+    expect((await call(u.start_node, { child_node_id: CHILD, daemon_node_id: "node_wrong", network_id: NET })).error).toBe("daemon_child_mismatch");
+  });
+});

package/src/tools.ts

@@ -6,6 +6,7 @@ import { createHash } from "node:crypto";
 import { db, uuidv4, logTaskEvent, chainReplyToParent, hashToken, generateId, generateNetworkToken, syncScheduledRunForTask } from "./db.js";
 import { getSSEStats, hasSubscribers, pushEvent, pushNetworkObserverEvent, pushUserEvent } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
+import { pendingInboxCount } from "./inbox-count.js";
 import { getUserNetworkRole, createNetworkTokenForNode } from "./auth.js";
 import { canRestWriteNetwork, getUserNetworkIds, singleNetworkId } from "./network-scope.js";
 import {
@@ -80,6 +81,49 @@ function normalizeMetaJson(meta: unknown): string | null {
   try { return JSON.stringify(stripHostLocalPathsForCrossHostSafe(meta)); } catch { return null; }
 }
 
+// ── #1281 — 子节点生命周期工具的参数名统一 ────────────────────────────
+//
+// stop_node / start_node / delete_node 历史上用 `child_node_id`（RFC-027），
+// restart_node / update_node_config 用 `node_id`。同一个对象（子节点）两个名字，
+// 调用方按一个工具的习惯给另一个传就吃 -32602。两侧都已是**已发布契约**
+// （start_node 随 #1273 合入），且 hub API 在 RFC-030 混版滚动期老客户端还在
+// 发老名——所以不能硬改名，改为**两个名字都接受**：
+//   · canonical = `node_id`（= DB 列 nodes.node_id、= create_node 的输出、
+//     restart/update 历史用名；「建完节点→再操作它」用同一个名才是傻瓜式）。
+//   · `child_node_id` 作为**兼容 alias 保留** + deprecation 注释；不加运行时
+//     warning（老客户端是设计内兼容，不是错误，别刷屏）。
+// create_node 的 `daemon_node_id` 指宿主 daemon，是另一层语义，不在本次统一内。
+//
+// server.tool 收的是 ZodRawShape（裸对象），挂不了 .refine()，所以「至少一个
+// 必填」+「两个都传须相等」在 handler 侧用 resolveNodeIdArg 兜——返回结构化
+// ok:false 反而比 schema 层的 -32602 更友好。两个名字在 schema 层都做成
+// optional + 宽松 .min(1).max(200)（不带 regex），使命名与校验强度同时统一：
+// 对 restart/update 不变（本就宽松），对 stop/start/delete 是放宽（原 regex 会
+// 在 schema 层挡掉 alias/杂串，放宽后落到查表返回 node_not_found，对合法调用
+// 方无影响，只是错误形态更一致）。
+const NODE_ID_ALIAS_FIELDS = {
+  node_id: z.string().min(1).max(200).optional()
+    .describe("Target child node ID (canonical, #1281). The value create_node returns. Must be in caller's network."),
+  child_node_id: z.string().min(1).max(200).optional()
+    .describe("DEPRECATED alias for node_id (#1281): kept for back-compat with pre-unification clients; prefer node_id."),
+} as const;
+
+/** #1281 — 把 node_id / child_node_id 收敛成单一内部 id。两个都传且不等 ⇒
+ *  node_id_conflict（挡「node_id 填 A、child_node_id 填 B」的手滑，比单纯二选一强）；
+ *  都不传 ⇒ node_id_required。纯函数，模块级导出以便单测直接验解析逻辑。 */
+export function resolveNodeIdArg(a: { node_id?: string; child_node_id?: string }):
+  { ok: true; node_id: string } | { ok: false; error: string; message: string } {
+  const n = a.node_id, c = a.child_node_id;
+  if (n && c && n !== c) {
+    return { ok: false, error: "node_id_conflict", message: "node_id and child_node_id both provided but differ; send only one (they are aliases for the same child node)" };
+  }
+  const id = n ?? c;
+  if (!id) {
+    return { ok: false, error: "node_id_required", message: "one of node_id / child_node_id is required (child_node_id is a deprecated alias; prefer node_id)" };
+  }
+  return { ok: true, node_id: id };
+}
+
 export function registerTools(server: McpServer, clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false, callerTokenId?: string | null) {
   // Default from_session for outbound tools — extracted from the calling
   // token's binding (ntok_ → node alias, utok_ → username). Without this,
@@ -1581,7 +1625,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       );
 
       // 同 send_task：可达性用订阅者注册表判，不用心跳时间戳猜。
-      pushEvent(targetAlias, { type: "new_message", from: from_session, message_id: id, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
+      pushEvent(targetAlias, { type: "new_message", inbox_count: pendingInboxCount(targetAlias, effectiveNetId), from: from_session, message_id: id, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
 
       const offlineReply = deliveryTargetReply(target, { message_id: id });
       if (offlineReply) {
@@ -1893,7 +1937,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       }
 
       const session = scopedSessionStatus(replyTargetAlias, effectiveNetId);
-      pushEvent(replyTargetAlias, { type: "new_reply", from: from_session, message_id: id, in_reply_to, status: replyStatus }, effectiveNetId);
+      pushEvent(replyTargetAlias, { type: "new_reply", inbox_count: pendingInboxCount(replyTargetAlias, effectiveNetId), from: from_session, message_id: id, in_reply_to, status: replyStatus }, effectiveNetId);
       // #461 network observer summary — ids + routing only, no reply text.
       pushNetworkObserverEvent(effectiveNetId, { type: "new_reply", task_id: in_reply_to ?? null, message_id: id, from: from_session, to: replyTargetAlias, status: replyStatus });
 
@@ -2033,7 +2077,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       });
       logTaskEvent(task_id, task.status, "delivered", from_session, "retry");
       // SSE push (unconditional — channel is keyed by alias, not network)
-      pushEvent(task.to_name, { type: "new_task", inbox_count: 1, priority: task.priority, from: from_session }, effectiveNetId ?? task.network_id ?? null);
+      pushEvent(task.to_name, { type: "new_task", inbox_count: pendingInboxCount(task.to_name, effectiveNetId ?? task.network_id ?? null), priority: task.priority, from: from_session }, effectiveNetId ?? task.network_id ?? null);
       pushNetworkObserverEvent(effectiveNetId ?? task.network_id ?? null, { type: "new_task", task_id, from: from_session, to: task.to_name, status: "delivered", priority: task.priority });
       return {
         content: [{ type: "text" as const, text: JSON.stringify({ ok: true, task_id, retried_to: task.to_name }) }],
@@ -2247,7 +2291,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           [newInboxId, task_id, reassignedAlias, newNodeId, task.priority, task.content, from_session, effectiveNetId ?? task.network_id ?? null]);
       });
       logTaskEvent(task_id, task.status, "delivered", from_session, `reassign: ${oldAlias} → ${reassignedAlias}`);
-      pushEvent(reassignedAlias, { type: "new_task", inbox_count: 1, priority: task.priority, from: from_session, ...(canonical.renamed ? { renamed_from: new_alias } : {}) }, effectiveNetId ?? task.network_id ?? null);
+      pushEvent(reassignedAlias, { type: "new_task", inbox_count: pendingInboxCount(reassignedAlias, effectiveNetId ?? task.network_id ?? null), priority: task.priority, from: from_session, ...(canonical.renamed ? { renamed_from: new_alias } : {}) }, effectiveNetId ?? task.network_id ?? null);
       pushNetworkObserverEvent(effectiveNetId ?? task.network_id ?? null, { type: "new_task", task_id, from: from_session, to: reassignedAlias, status: "delivered", priority: task.priority });
       return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, task_id, reassigned_from: oldAlias, reassigned_to: reassignedAlias, ...(canonical.renamed ? { renamed_from: new_alias, renamed_to: reassignedAlias } : {}) }) }] };
     }
@@ -2365,32 +2409,39 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
       const targets = db.all<{ alias: string; node_id: string | null; network_id: string | null }>(sql, ...params);
       const ids: string[] = [];
+      // #1440 ① — the push loop must walk the recipients that actually
+      // got an inbox row, not every candidate target. Walking `targets`
+      // announced a broadcast to nodes the lifecycle guard had just
+      // skipped, i.e. nodes with nothing to fetch.
+      const delivered: Array<{ alias: string; netId: string | null }> = [];
 
       for (const t of targets) {
         // RFC-027 §2.3 inbox-enqueue lifecycle guard (PR1.1 site 6/6).
         // Broadcast skips non-active recipients silently rather than
         // failing the entire send — broadcast semantics are best-effort
         // per-recipient and a stopped node simply gets nothing.
-        const lc = assertNodeActive(t.alias, effectiveNetId ?? t.network_id ?? null);
+        const netId = effectiveNetId ?? t.network_id ?? null;
+        const lc = assertNodeActive(t.alias, netId);
         if (!lc.ok) continue;
         const id = uuidv4();
         db.run(
           `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id)
            VALUES (?1, ?2, ?3, 'broadcast', 'normal', ?4, 'hub', ?5)`,
-          [id, t.alias, t.node_id ?? null, message, effectiveNetId ?? t.network_id ?? null]
+          [id, t.alias, t.node_id ?? null, message, netId]
         );
         ids.push(id);
+        delivered.push({ alias: t.alias, netId });
       }
 
-      for (const t of targets) {
-        pushEvent(t.alias, { type: "broadcast", inbox_count: 1 }, effectiveNetId ?? t.network_id ?? null);
+      for (const d of delivered) {
+        pushEvent(d.alias, { type: "broadcast", inbox_count: pendingInboxCount(d.alias, d.netId) }, d.netId);
       }
 
       return {
         content: [
           {
             type: "text" as const,
-            text: JSON.stringify({ ok: true, recipients: targets.length, message_ids: ids }),
+            text: JSON.stringify({ ok: true, recipients: ids.length, message_ids: ids }),
           },
         ],
       };
@@ -2483,7 +2534,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "update_node_config",
     "Set the desired per-node config (model + flags) and push a doorbell to the node. The node pulls + validates + applies (hot or restart per field tier). RFC-024.",
     {
-      node_id: z.string().min(1).max(200).describe("Target node ID (not alias). Must be in caller's network."),
+      ...NODE_ID_ALIAS_FIELDS,
       base_revision: z.number().int().min(0).describe("Current revision per the dashboard's last GET — 409 if hub's current revision differs."),
       patch: z.object({
         model: z.string().max(200).optional(),
@@ -2507,7 +2558,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       }).describe("Fields to update. Empty patch → no-op (use restart_node for that)."),
       network_id: z.string().max(200).optional(),
     },
-    async ({ node_id: nodeId, base_revision: baseRev, patch, network_id: clientNetId }) => {
+    async ({ node_id, child_node_id, base_revision: baseRev, patch, network_id: clientNetId }) => {
+      const idArg = resolveNodeIdArg({ node_id, child_node_id });
+      if (!idArg.ok) return { content: [{ type: "text" as const, text: JSON.stringify(idArg) }] };
+      const nodeId = idArg.node_id;
       const effectiveNetId = getNetworkId(clientNetId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, "write");
 
@@ -2816,10 +2870,13 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "restart_node",
     "Trigger a node restart without changing config. RFC-024 Vincent 2026-06-28 increment. Network-scoped (SEC-1); member+ role suffices (lifecycle ops are not privilege elevation).",
     {
-      node_id: z.string().min(1).max(200),
+      ...NODE_ID_ALIAS_FIELDS,
       network_id: z.string().max(200).optional(),
     },
-    async ({ node_id: nodeId, network_id: clientNetId }) => {
+    async ({ node_id, child_node_id, network_id: clientNetId }) => {
+      const idArg = resolveNodeIdArg({ node_id, child_node_id });
+      if (!idArg.ok) return { content: [{ type: "text" as const, text: JSON.stringify(idArg) }] };
+      const nodeId = idArg.node_id;
       const effectiveNetId = getNetworkId(clientNetId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, "write");
 
@@ -3718,7 +3775,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "stop_node",
     "Stop the agent-node child process; keep config dir intact. Reversible via restart_node. RFC-027 §2.2. daemon_node_id is auto-resolved from child_node_id when omitted (looked up in node_create_requests).",
     {
-      child_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/),
+      ...NODE_ID_ALIAS_FIELDS,
       // PR2 prereq: dashboard rarely knows daemon_node_id directly.
       // When omitted, hub resolves from the original creation record
       // (node_create_requests.daemon_node_id keyed by this child).
@@ -3727,7 +3784,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       grace_seconds: z.number().int().min(5).max(60).optional().default(10),
       network_id: z.string().max(200).optional(),
     },
-    async ({ child_node_id, daemon_node_id, force, grace_seconds, network_id: clientNetId }) => {
+    async ({ node_id, child_node_id: child_node_id_arg, daemon_node_id, force, grace_seconds, network_id: clientNetId }) => {
+      const idArg = resolveNodeIdArg({ node_id, child_node_id: child_node_id_arg });
+      if (!idArg.ok) return { content: [{ type: "text" as const, text: JSON.stringify(idArg) }] };
+      const child_node_id = idArg.node_id;
       const resolved = daemon_node_id ?? resolveDaemonForChild(child_node_id);
       if (!resolved) {
         return { content: [{ type: "text" as const, text: JSON.stringify({
@@ -3748,7 +3808,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "delete_node",
     "Stop child + revoke ntok + delete hub row + (default) backup config to ~/.anet/deleted/<ts>-<alias>/ for 30d. confirm_alias must equal the node's alias. daemon_node_id is auto-resolved when omitted. RFC-027 §2.2.",
     {
-      child_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/),
+      ...NODE_ID_ALIAS_FIELDS,
       daemon_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/).optional(),
       confirm_alias: z.string().min(1).max(200),
       force: z.boolean().optional().default(false),
@@ -3756,7 +3816,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       delete_config: z.boolean().optional().default(true),
       network_id: z.string().max(200).optional(),
     },
-    async ({ child_node_id, daemon_node_id, confirm_alias, force, grace_seconds, delete_config, network_id: clientNetId }) => {
+    async ({ node_id, child_node_id: child_node_id_arg, daemon_node_id, confirm_alias, force, grace_seconds, delete_config, network_id: clientNetId }) => {
+      const idArg = resolveNodeIdArg({ node_id, child_node_id: child_node_id_arg });
+      if (!idArg.ok) return { content: [{ type: "text" as const, text: JSON.stringify(idArg) }] };
+      const child_node_id = idArg.node_id;
       const resolved = daemon_node_id ?? resolveDaemonForChild(child_node_id);
       if (!resolved) {
         return { content: [{ type: "text" as const, text: JSON.stringify({
@@ -3927,6 +3990,141 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     },
   );
 
+  // start_node is deliberately daemon-mediated. A stopped child has no SSE
+  // consumer of its own, so restart_node's self-doorbell cannot revive it.
+  server.tool(
+    "start_node",
+    "Start a stopped child through its host supervisor daemon. daemon_node_id is auto-resolved from the original create request.",
+    {
+      ...NODE_ID_ALIAS_FIELDS,
+      daemon_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/).optional(),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ node_id, child_node_id: child_node_id_arg, daemon_node_id, network_id: clientNetId }) => {
+      const idArg = resolveNodeIdArg({ node_id, child_node_id: child_node_id_arg });
+      if (!idArg.ok) return { content: [{ type: "text" as const, text: JSON.stringify(idArg) }] };
+      const child_node_id = idArg.node_id;
+      const resolvedDaemonId = daemon_node_id ?? resolveDaemonForChild(child_node_id);
+      if (!resolvedDaemonId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({
+          ok: false, error: "daemon_not_resolvable",
+          message: "no create request maps this child to a daemon",
+        }) }] };
+      }
+      const scope = resolveReadScope(clientNetId);
+      if (scope.denied) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "forbidden_cross_tenant" }) }] };
+      const q: any[] = [child_node_id];
+      const child = db.get<{ node_id: string; alias: string; network_id: string; lifecycle_state: string | null }>(
+        addReadScope(`SELECT node_id, alias, network_id, lifecycle_state FROM nodes WHERE node_id = ?1`, q, scope), ...q,
+      );
+      if (!child) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "forbidden_cross_tenant" }) }] };
+      if (!canWrite(child.network_id)) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "permission_denied" }) }] };
+      if ((child.lifecycle_state ?? "active") !== "stopped") {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "node_not_stopped", current_state: child.lifecycle_state ?? "active" }) }] };
+      }
+      // The caller may provide daemon_node_id, but it cannot override the
+      // authoritative child->daemon relationship recorded at creation.
+      const authoritativeDaemonId = resolveDaemonForChild(child_node_id);
+      if (!authoritativeDaemonId || authoritativeDaemonId !== resolvedDaemonId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "daemon_child_mismatch" }) }] };
+      }
+      const daemon = db.get<{ node_id: string; alias: string; network_id: string }>(
+        `SELECT node_id, alias, network_id FROM nodes WHERE node_id = ?1`, resolvedDaemonId,
+      );
+      if (!daemon) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "daemon_not_found" }) }] };
+      if (daemon.network_id !== child.network_id) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "daemon_cross_tenant" }) }] };
+      }
+      const requestId = generateId("str");
+      const now = Date.now();
+      try {
+        db.transaction(() => {
+          db.run(
+            `INSERT INTO node_start_requests
+               (request_id, network_id, daemon_node_id, child_node_id, child_alias,
+                created_by_token, status, created_at)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'pending', ?7)`,
+            [requestId, child.network_id, daemon.node_id, child.node_id, child.alias, callerTokenId || "unknown", now],
+          );
+          db.run(`UPDATE nodes SET lifecycle_state = 'starting' WHERE node_id = ?1 AND lifecycle_state = 'stopped'`, [child.node_id]);
+          auditCreateNodeStrict({
+            action: "start_node_dispatched", user_id: enforceUserId,
+            network_id: child.network_id, target_id: requestId,
+            detail: { child_node_id: child.node_id, child_alias: child.alias, daemon_node_id: daemon.node_id,
+              lifecycle_state_before: "stopped", lifecycle_state_after: "starting", ts_request: now },
+          });
+        });
+      } catch (e: any) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "dispatch_tx_failed", message: e?.message || String(e) }) }] };
+      }
+      pushEvent(daemon.alias, { type: "start_node", request_id: requestId }, child.network_id);
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request_id: requestId, lifecycle_state: "starting" }) }] };
+    },
+  );
+
+  server.tool(
+    "get_start_request",
+    "Host supervisor pulls an authenticated pending start request.",
+    { request_id: z.string().min(1).max(200) },
+    async ({ request_id }) => {
+      const callerDaemon = resolveCallerDaemonTokenBound();
+      if (!callerDaemon.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
+      const row = db.get<{ daemon_node_id: string; network_id: string; child_node_id: string; child_alias: string; status: string }>(
+        `SELECT daemon_node_id, network_id, child_node_id, child_alias, status FROM node_start_requests WHERE request_id = ?1`, request_id,
+      );
+      if (!row) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_found" }) }] };
+      if (row.daemon_node_id !== callerDaemon.daemonNodeId) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "not_your_request" }) }] };
+      if (row.network_id !== callerDaemon.networkId) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_request" }) }] };
+      if (!['pending', 'delivered'].includes(row.status)) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_startable", status: row.status }) }] };
+      db.run(`UPDATE node_start_requests SET status='delivered', delivered_at=?1 WHERE request_id=?2 AND status='pending'`, [Date.now(), request_id]);
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request_id, child_node_id: row.child_node_id, child_alias: row.child_alias }) }] };
+    },
+  );
+
+  server.tool(
+    "ack_start_request",
+    "Host supervisor reports start completion or failure.",
+    {
+      request_id: z.string().min(1).max(200),
+      status: z.enum(["started", "start_failed"]),
+      child_pid: z.number().int().positive().optional(),
+      error: z.string().max(1000).optional(),
+    },
+    async ({ request_id, status, child_pid, error: ackError }) => {
+      const callerDaemon = resolveCallerDaemonTokenBound();
+      if (!callerDaemon.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
+      const row = db.get<{ daemon_node_id: string; network_id: string; child_node_id: string; child_alias: string; status: string }>(
+        `SELECT daemon_node_id, network_id, child_node_id, child_alias, status FROM node_start_requests WHERE request_id=?1`, request_id,
+      );
+      if (!row) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_found" }) }] };
+      if (row.daemon_node_id !== callerDaemon.daemonNodeId) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "not_your_request" }) }] };
+      if (row.network_id !== callerDaemon.networkId) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_request" }) }] };
+      if (row.status === "started" || row.status === "start_failed") {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, status: row.status, idempotent: true }) }] };
+      }
+      if (!['pending', 'delivered'].includes(row.status)) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_ackable", status: row.status }) }] };
+      }
+      if (status === "started" && !child_pid) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "child_pid_required" }) }] };
+      }
+      const now = Date.now();
+      try {
+        db.transaction(() => {
+          db.run(`UPDATE node_start_requests SET status=?1,error=?2,child_pid=?3,acked_at=?4 WHERE request_id=?5`, [status, ackError || null, child_pid || null, now, request_id]);
+          db.run(`UPDATE nodes SET lifecycle_state=?1 WHERE node_id=?2`, [status === "started" ? "active" : "stopped", row.child_node_id]);
+          if (status === "started") auditCreateNodeStrict({
+            action: "start_node_completed", network_id: row.network_id, target_id: request_id,
+            detail: { child_node_id: row.child_node_id, child_alias: row.child_alias, child_pid, lifecycle_state_after: "active", ts_daemon_ack: now },
+          });
+        });
+      } catch (e: any) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "finalize_tx_failed", message: e?.message || String(e) }) }] };
+      }
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, status }) }] };
+    },
+  );
+
   // RFC-027 PR1.1 — list_my_children: daemon-only query. Returns the
   // {child_node_id, alias, lifecycle_state} tuples for nodes whose
   // active create-request has this daemon as daemon_node_id. Used at