@sleep2agi/commhub-server 0.9.0-preview.143 → 0.9.0-preview.145

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.143",
+  "version": "0.9.0-preview.145",
   "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-department-http.test.ts

@@ -145,4 +145,20 @@ describe("Agent 显式归属部门", () => {
     const agents2 = [...(dir2.body.people ?? []).flatMap((p: any) => p.agents ?? []), ...(dir2.body.agents_without_owner ?? [])];
     expect(agents2.find((a: any) => a.node_id === NODE_A)?.department_id ?? null).toBeNull();
   });
+
+  // #1976 —— Agent 归属与人类部门是两个独立的结构。通讯录顶层要说明「这个 Hub 支持显式
+  // Agent 部门」,客户端据此把「行里没有 department_id」读成「没有显式归属」,
+  // 而不是从「负责人在哪个部门」推断出来。
+  test("通讯录声明支持显式 Agent 部门（与人类部门相互独立）", async () => {
+    const dir = await send(U.owner.token, "GET", `/api/requirements/people/directory?network_id=${NET}`);
+    expect(dir.status).toBe(200);
+    expect(dir.body.agent_department_supported).toBe(true);
+    // 行形状不变:没有显式归属的行**不带** department_id 这一格(旧客户端形状不变)。
+    const agents = [...(dir.body.people ?? []).flatMap((p: any) => p.agents ?? []), ...(dir.body.agents_without_owner ?? [])];
+    for (const a of agents) {
+      // 显式归属 ⇒ 带这一格且非空;没有显式归属 ⇒ **不带这一格**(旧客户端形状不变)。
+      if (a.department_id) expect(typeof a.department_id).toBe("string");
+      else expect(Object.prototype.hasOwnProperty.call(a, "department_id")).toBe(false);
+    }
+  });
 });

package/src/db.ts

@@ -322,6 +322,21 @@ db.exec(`
   CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
 `);
 
+// 账号头像上传（二进制 PNG，Hub 自己发 URL）。与 users.avatar_url 并存：
+// avatar_url 仍可指向内建池/外链；这张表只存「上传到 Hub 本人的那张」。
+// 单行/人：新版本覆盖旧版本，旧 URL 立刻 404（version 变了），不做历史留存。
+db.exec(`
+  CREATE TABLE IF NOT EXISTS user_avatar_uploads (
+    user_id    TEXT PRIMARY KEY,
+    version    TEXT NOT NULL,
+    png        BLOB NOT NULL,
+    bytes      INTEGER NOT NULL,
+    width      INTEGER NOT NULL,
+    height     INTEGER NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+`);
+
 // Human profile avatar. Additive for existing databases; old binaries ignore it.
 try {
   db.exec("ALTER TABLE users ADD COLUMN avatar_url TEXT");

package/src/node-lifecycle-read-http.test.ts

@@ -66,8 +66,13 @@ test("public errors redact free text for granted viewers on every projection", a
       "adopt_codex_session_conflict", "adopt_codex_port_unavailable", "adopt_codex_stage_still_running",
       "adopt_codex_identity_unproven",
       "TUI session mismatch", "opencode_launch_health:TUI session mismatch", "opencode_tui_session_mismatch",
+      // #2012：daemon 明确拒绝的固定安全码，必须原样投影给用户，而不是退化成 lifecycle_error。
+      "copresence_adopt_v2",
+      // 负控：带后缀/路径/空白的形状仍必须清成 lifecycle_error（只精确放行这一串）。
+      "copresence_adopt_v2: /private/fixture", "copresence_adopt_v2x", " copresence_adopt_v2",
     ]) {
       const publicCodes = ["adopt_start_timeout", "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed", "opencode_tui_session_mismatch",
+        "copresence_adopt_v2",
         "adopt_codex_external_start_unproven", "adopt_codex_launch_failed", "adopt_codex_launch_timeout",
         "adopt_codex_port_unproven", "adopt_codex_start_superseded", "adopt_codex_binding_generation_unproven",
         "adopt_codex_start_evidence_missing", "adopt_codex_start_evidence_changed",

package/src/node-lifecycle-read.ts

@@ -33,6 +33,9 @@ const publicLifecycleErrors = new Set([
   "adopt_pane_process_mismatch", "adopt_socket_directory_unsafe", "adopt_socket_unsafe",
   "adopt_pid_changed", "adopt_pid_invalid", "adopt_pidfile_unsafe",
   "opencode_tui_session_mismatch",
+  // #2012 —— daemon 的 copresence_adopt_v2 拒绝是固定安全码（无路径/无异常文本），
+  // 不放行会让用户投影退化成 lifecycle_error，看不到「为什么被拒绝」。
+  "copresence_adopt_v2",
   "adopt_proc_invalid", "adopt_proc_unreadable", "adopt_platform_unsupported",
   "adopt_registry_conflict", "adopt_registry_entry_invalid", "adopt_registry_invalid",
   "adopt_registry_unsafe", "adopt_config_env_invalid", "adopt_env_file_invalid",

package/src/node-session-control-http.test.ts

@@ -0,0 +1,308 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, setSystemTime, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-session-control-"));
+process.env.COMMHUB_DB ||= join(dir, "hub.db");
+const root = "/api/node-session-control";
+let server: any, base: string, db: any, net: string, otherNet: string;
+let owner: any, admin: any, member: any, outsider: any, ntok: any, peer: any;
+let legacyOwner: any, legacyAdmin: any, legacyMember: any, legacyOutsider: any, legacyFull: any, legacyNetwork: any;
+let binding = { session_id: "session_1", binding_id: "binding_1" }, serial = 0;
+const nodeId = "n_session_control", peerId = "n_session_control_peer";
+async function api(token: string, path: string, value?: unknown, method?: string) {
+  const res = await fetch(`${base}${path}`, { method: method ?? (value === undefined ? "GET" : "POST"),
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    ...(value === undefined ? {} : { body: JSON.stringify(value) }) });
+  return { status: res.status, body: await res.json() as any };
+}
+const registerBridge = (v = binding, token = ntok.token!) => api(token, `${root}/bridge`,
+  { ...v, expected: { node_id: nodeId, network_id: net } });
+const enqueue = (operation = "background", extra = {}) => api(owner.token!, root,
+  { network_id: net, node_id: nodeId, operation, expected: binding, ...extra });
+const pull = (token = ntok.token!, v = binding) => api(token, `${root}/pull`, v);
+const read = (request: string, token = owner.token!, network = net) => api(token, `${root}/${request}?network_id=${network}`);
+const state = () => ({ ...binding, supported: true, active: true, can_request_background: true, observed_at: Date.now() });
+const ack = (request: string, result: unknown, extra = {}) => api(ntok.token!, `${root}/${request}/ack`,
+  { ...binding, status: "done", result, ...extra });
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register, addNetworkMember, createNetworkTokenForNode, createToken } = await import("./auth.js");
+  const stamp = Date.now();
+  admin = register(`sc_admin_${stamp}`, "SessionControl-Test-1!");
+  owner = register(`sc_owner_${stamp}`, "SessionControl-Test-2!");
+  member = register(`sc_member_${stamp}`, "SessionControl-Test-3!");
+  outsider = register(`sc_other_${stamp}`, "SessionControl-Test-4!");
+  expect(admin.ok && owner.ok && member.ok && outsider.ok).toBe(true);
+  net = admin.network_id!; otherNet = outsider.network_id!;
+  for (const u of [owner, member]) expect(addNetworkMember(net, u.user.user_id, "member", admin.user.user_id, { agentAccess: "all" }).ok).toBe(true);
+  // Real atok hashes via the legacy issuer; only fixture rows are converted
+  // to the historical global scope=user shape. No prefix-based authority.
+  const legacyUser = (u: any) => {
+    const t = createToken(u.user.user_id, "sc-legacy-user");
+    expect(t.ok).toBe(true);
+    expect(t.token).toMatch(/^atok_/);
+    db.run("UPDATE api_tokens SET scope='user' WHERE token_id=?1", t.token_id);
+    return t;
+  };
+  legacyOwner = legacyUser(owner); legacyAdmin = legacyUser(admin);
+  legacyMember = legacyUser(member); legacyOutsider = legacyUser(outsider);
+  legacyFull = createToken(owner.user.user_id, "sc-legacy-global-full");
+  legacyNetwork = createToken(owner.user.user_id, "sc-legacy-network", net);
+  expect(legacyFull.ok && legacyNetwork.ok).toBe(true);
+  ntok = createNetworkTokenForNode(owner.user.user_id, net, "sc-target", nodeId);
+  peer = createNetworkTokenForNode(owner.user.user_id, net, "sc-peer", peerId);
+  expect(ntok.ok && peer.ok).toBe(true);
+  db.run("INSERT INTO sessions(resume_id,alias,node_id,network_id,status) VALUES (?1,?2,?3,?4,'idle')", ["r_sc_target", "sc-target", nodeId, net]);
+  const { bootServer } = await import("./server.js");
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+beforeEach(async () => {
+  binding = { session_id: `session_${++serial}`, binding_id: `binding_${serial}` };
+  expect((await registerBridge()).status).toBe(200);
+});
+afterEach(() => setSystemTime());
+afterAll(() => { server?.stop(true); rmSync(dir, { recursive: true, force: true }); });
+
+describe("#2017 human-to-exact-Bridge HTTP relay", () => {
+  test("[2017 identity] missing or malformed expected is refused without fallback", async () => {
+    for (const expected of [undefined, {}, { node_id: nodeId }, { node_id: nodeId, network_id: net, token_id: ntok.token_id }]) {
+      const rejected = await api(ntok.token!, `${root}/bridge`, { ...binding, expected });
+      expect(rejected.status).toBe(400);
+      expect(rejected.body.error).toBe("session_control_request_invalid");
+    }
+    expect((await registerBridge()).status).toBe(200);
+  });
+  test("[2017 identity] A credential expected B cannot sweep, replace or retire the valid binding", async () => {
+    const made = await enqueue("state"), clock = Date.now();
+    const tokenBefore = db.get("SELECT token_id,bound_node_id,network_id FROM api_tokens WHERE token_id=?1", ntok.token_id);
+    const nodeBefore = db.get("SELECT node_id,network_id,owner_user_id FROM nodes WHERE node_id=?1", nodeId);
+    // Advancing beyond the request deadline exposes an accidental sweep before
+    // rejecting expected. Restore only the clock, never the authoritative queue.
+    setSystemTime(new Date(clock + 16_000));
+    for (const expected of [{ node_id: peerId, network_id: net }, { node_id: nodeId, network_id: otherNet }]) {
+      const rejected = await api(ntok.token!, `${root}/bridge`, {
+        session_id: "would_replace_session", binding_id: "would_retire_binding", expected,
+      });
+      expect(rejected.status).toBe(409);
+      expect(rejected.body.error).toBe("session_control_changed");
+    }
+    setSystemTime(new Date(clock));
+    expect((await read(made.body.request_id)).body.status).toBe("pending");
+    expect((await registerBridge()).status).toBe(200); // Original generation was not retired.
+    expect((await pull()).body.request).toMatchObject({ request_id: made.body.request_id, ...binding });
+    expect(db.get("SELECT token_id,bound_node_id,network_id FROM api_tokens WHERE token_id=?1", ntok.token_id)).toEqual(tokenBefore);
+    expect(db.get("SELECT node_id,network_id,owner_user_id FROM nodes WHERE node_id=?1", nodeId)).toEqual(nodeBefore);
+  });
+  test("[2017 identity] success carries the authenticated token row identity, never credential material", async () => {
+    const response = await registerBridge();
+    const row = db.get("SELECT token_id,bound_node_id,network_id FROM api_tokens WHERE token_id=?1", ntok.token_id);
+    expect(response.status).toBe(200);
+    expect(response.body.identity).toEqual({ node_id: row.bound_node_id, network_id: row.network_id, token_id: row.token_id });
+    expect(Object.keys(response.body).sort()).toEqual(["expires_at", "identity", "ok"]);
+    expect(JSON.stringify(response.body)).not.toContain(ntok.token);
+  });
+  test("normal state and background receipts are separate from actual tool completion", async () => {
+    const s = await enqueue("state");
+    expect(s.body).toMatchObject({ ok: true, status: "pending" });
+    expect(s.body.request_id).toMatch(/^sc_\d{13}_[A-Za-z0-9_-]{8,64}$/);
+    expect((await pull()).body.request).toMatchObject({ request_id: s.body.request_id, operation: "state", ...binding });
+    const observed = state();
+    expect((await ack(s.body.request_id, observed)).body.status).toBe("done");
+    expect((await read(s.body.request_id)).body.result).toEqual(observed);
+    const b = await enqueue();
+    expect(b.body.request_id).toMatch(/^bg_\d{13}_[A-Za-z0-9_-]{8,64}$/);
+    expect(b.body.expires_at).toBeGreaterThan(Date.now());
+    await pull();
+    const result = { outcome: "request_processed", state: state() };
+    expect((await ack(b.body.request_id, result)).body.status).toBe("done");
+    expect((await read(b.body.request_id)).body).toMatchObject({ ok: true, status: "done", result });
+  });
+  test("[2017 review] already_idle cannot confirm an active or background-capable state", async () => {
+    for (const flags of [
+      { active: true, can_request_background: true },
+      { active: true, can_request_background: false },
+      { active: false, can_request_background: true },
+    ]) {
+      const made = await enqueue(); await pull();
+      const reply = await ack(made.body.request_id, { outcome: "already_idle", state: { ...state(), ...flags } });
+      expect(reply.status).toBe(400);
+      expect(reply.body.error).toBe("session_control_invalid_response");
+      expect((await read(made.body.request_id)).body).toMatchObject({ status: "unknown", error: "session_control_invalid_response" });
+    }
+  });
+  test("[2017 review] legacy user atok owner/admin and global full can create and read control", async () => {
+    for (const t of [legacyOwner, legacyAdmin, legacyFull]) {
+      for (const operation of ["state", "background"]) {
+        const made = await api(t.token, root, { network_id: net, node_id: nodeId, operation, expected: binding });
+        expect(made.status).toBe(200);
+        expect((await read(made.body.request_id, t.token)).body.status).toBe("pending");
+        expect((await pull()).body.request.request_id).toBe(made.body.request_id);
+        const result = operation === "state" ? state() : { outcome: "request_processed", state: state() };
+        expect((await ack(made.body.request_id, result)).body.status).toBe("done");
+        expect((await read(made.body.request_id, t.token)).body.result).toEqual(result);
+      }
+    }
+  });
+  test("[2017 review] legacy atok still requires current target ownership and exact network", async () => {
+    for (const t of [legacyMember, legacyOutsider]) {
+      expect((await api(t.token, root, { network_id: net, node_id: nodeId, operation: "state" })).status).toBe(403);
+    }
+    expect((await api(legacyOwner.token, root, { network_id: otherNet, node_id: nodeId, operation: "state" })).status).toBe(403);
+    const made = await enqueue("state");
+    for (const t of [legacyMember, legacyOutsider]) expect((await read(made.body.request_id, t.token)).status).toBe(403);
+    expect((await read(made.body.request_id, legacyOwner.token, otherNet)).status).toBe(403);
+  });
+  test("[2017 review] legacy atok user and unbound network credentials cannot impersonate Bridge", async () => {
+    const made = await enqueue("state");
+    for (const t of [legacyOwner, legacyAdmin, legacyFull, legacyNetwork]) {
+      expect((await registerBridge(binding, t.token)).status).toBe(403);
+      expect((await pull(t.token)).status).toBe(403);
+      expect((await api(t.token, `${root}/${made.body.request_id}/ack`, { ...binding, status: "done", result: state() })).status).toBe(403);
+    }
+    expect((await read(made.body.request_id)).body.status).toBe("pending");
+    expect((await pull()).body.request.request_id).toBe(made.body.request_id);
+  });
+  test("[2017 review] unknown, revoked, expired or unsupported-scope credentials stay refused", async () => {
+    const request = () => api(legacyOwner.token, root, { network_id: net, node_id: nodeId, operation: "state" });
+    expect((await api("atok_00000000000000000000000000000000", root, {})).status).toBe(401);
+    for (const patch of ["revoked_at=datetime('now')", "expires_at=datetime('now','-1 day')", "scope='unsupported'"]) {
+      db.run(`UPDATE api_tokens SET ${patch} WHERE token_id=?1`, legacyOwner.token_id);
+      try { expect((await request()).status).toBeGreaterThanOrEqual(400); }
+      finally { db.run("UPDATE api_tokens SET revoked_at=NULL,expires_at=NULL,scope='user' WHERE token_id=?1", legacyOwner.token_id); }
+    }
+    expect((await request()).status).toBe(200);
+  });
+  test("SSE is a scoped doorbell only; the request lives in pull", async () => {
+    const abort = new AbortController();
+    const response = await fetch(`${base}/events/sc-target`, { headers: { authorization: `Bearer ${ntok.token}` }, signal: abort.signal });
+    expect(response.status).toBe(200);
+    const reader = response.body!.getReader();
+    try {
+      const made = await enqueue();
+      let data = "";
+      for (let i = 0; i < 4 && !data.includes('"type":"session_control"'); i++) {
+        const next = await reader.read(); data += new TextDecoder().decode(next.value);
+      }
+      const event = data.split("\n").filter(s => s.startsWith("data: ")).map(s => JSON.parse(s.slice(6))).find(s => s.type === "session_control");
+      expect(event).toEqual({ type: "session_control", request_id: made.body.request_id });
+      expect((await pull()).body.request.request_id).toBe(made.body.request_id);
+    } finally { abort.abort(); await reader.cancel().catch(() => {}); }
+  });
+  test("node, peer, anonymous, master and member cannot impersonate human owner/admin", async () => {
+    for (const token of [ntok.token, peer.token, "", "legacy-test-only", member.token, outsider.token]) {
+      expect((await api(token, root, { network_id: net, node_id: nodeId, operation: "state" })).status).toBeGreaterThanOrEqual(400);
+    }
+    const adminMade = await api(admin.token!, root, { network_id: net, node_id: nodeId, operation: "state" });
+    expect(adminMade.status).toBe(200);
+    expect((await read(adminMade.body.request_id, member.token!)).status).toBe(403);
+    expect((await read(adminMade.body.request_id, ntok.token!)).status).toBe(403);
+    expect((await read(adminMade.body.request_id, owner.token!, otherNet)).status).toBe(403);
+  });
+  test("cross-network, wrong expected, absent expected and command/path keys are refused", async () => {
+    expect((await enqueue("background", { network_id: otherNet })).status).toBe(403);
+    expect((await enqueue("background", { expected: { ...binding, session_id: "other_session" } })).body.error).toBe("session_control_changed");
+    expect((await api(owner.token!, root, { network_id: net, node_id: nodeId, operation: "background" })).status).toBe(400);
+    for (const key of ["url", "path", "keys", "shell"]) expect((await enqueue("state", { [key]: "unsafe" })).status).toBe(400);
+    expect((await registerBridge({ ...binding, node_id: peerId } as any)).status).toBe(400);
+  });
+  test("peer token and legacy unbound token never receive target requests", async () => {
+    const { createNetworkTokenForNode } = await import("./auth.js");
+    const legacy = createNetworkTokenForNode(owner.user.user_id, net, "sc-unbound");
+    expect(legacy.ok).toBe(true);
+    // Same-holder refreshes now bind existing rows. Construct an actual old
+    // unbound credential whose name only hints at this target instead.
+    db.run("UPDATE api_tokens SET name='node:sc-target' WHERE token_id=?1", legacy.token_id);
+    expect(db.get("SELECT bound_node_id FROM api_tokens WHERE token_id=?1", legacy.token_id).bound_node_id).toBeNull();
+    expect((await registerBridge(binding, legacy.token!)).status).toBe(403);
+    expect((await registerBridge(binding, owner.token!)).status).toBe(403);
+    const made = await enqueue();
+    expect((await pull(peer.token!)).body.request).toBeUndefined();
+    expect((await pull()).body.request.request_id).toBe(made.body.request_id);
+    expect((await api(peer.token!, `${root}/${made.body.request_id}/ack`, { ...binding, status: "done", result: state() })).status).toBe(409);
+  });
+  test("concurrent claims yield exactly one delivery and do not replay", async () => {
+    const made = await enqueue();
+    expect((await enqueue()).status).toBe(429);
+    const claims = await Promise.all([pull(), pull(), pull()]);
+    expect(claims.filter(r => r.body.request?.request_id === made.body.request_id)).toHaveLength(1);
+    expect((await read(made.body.request_id)).body.status).toBe("in_progress");
+    expect((await pull()).body.request).toBeNull();
+  });
+  test("expired pending request is never delivered", async () => {
+    const made = await enqueue();
+    setSystemTime(new Date(Date.now() + 16_000));
+    expect((await pull()).body.request).toBeNull();
+    expect((await read(made.body.request_id)).body.status).toBe("expired");
+  });
+  test("lost ACK becomes unknown, never success; late ACK and repeated pull cannot replay", async () => {
+    const made = await enqueue(); await pull();
+    setSystemTime(new Date(Date.now() + 16_000));
+    expect((await read(made.body.request_id)).body).toMatchObject({ status: "unknown", error: "session_background_outcome_unknown" });
+    expect((await ack(made.body.request_id, { outcome: "request_processed", state: state() })).status).toBe(409);
+    expect((await pull()).body.request).toBeNull();
+  });
+  test("new generation invalidates pending and cannot be overwritten by delayed old Bridge", async () => {
+    const old = { ...binding }, made = await enqueue();
+    binding = { session_id: "new_session", binding_id: `new_binding_${serial}` };
+    expect((await registerBridge()).status).toBe(200);
+    expect((await registerBridge(old)).body.error).toBe("session_control_changed");
+    expect((await pull(ntok.token!, old)).body.error).toBe("session_control_changed");
+    expect((await read(made.body.request_id)).body).toMatchObject({ status: "failed", error: "session_control_changed" });
+    expect((await pull()).body.request).toBeNull();
+  });
+  test("handle change after claim is unknown and old-session ACK cannot complete", async () => {
+    const old = { ...binding }, made = await enqueue(); await pull();
+    binding = { ...binding, binding_id: `changed_${serial}` }; await registerBridge();
+    expect((await api(ntok.token!, `${root}/${made.body.request_id}/ack`, { ...old, status: "done", result: { outcome: "already_idle", state: { ...state(), ...old } } })).status).toBe(409);
+    expect((await read(made.body.request_id)).body.status).toBe("unknown");
+  });
+  test("requester revocation before pull prevents delivery and current read permission is rechecked", async () => {
+    const made = await enqueue();
+    db.run("UPDATE network_members SET role='member' WHERE network_id=?1 AND user_id=?2", [net, owner.user.user_id]);
+    db.run("UPDATE nodes SET owner_user_id=?1 WHERE node_id=?2", [member.user.user_id, nodeId]);
+    try {
+      expect((await pull()).body.request).toBeNull();
+      expect((await read(made.body.request_id)).status).toBe(403);
+      expect((await read(made.body.request_id, admin.token!)).body.status).toBe("failed");
+    } finally { db.run("UPDATE nodes SET owner_user_id=?1 WHERE node_id=?2", [owner.user.user_id, nodeId]); }
+  });
+  test("target token revocation is checked at pull, not only registration", async () => {
+    const made = await enqueue();
+    db.run("UPDATE api_tokens SET revoked_at=datetime('now') WHERE token_id=?1", ntok.token_id);
+    try {
+      expect((await pull()).status).toBeGreaterThanOrEqual(400);
+      expect((await read(made.body.request_id)).body.status).toBe("failed");
+    } finally { db.run("UPDATE api_tokens SET revoked_at=NULL WHERE token_id=?1", ntok.token_id); }
+  });
+  test("malformed runtime results and raw exception strings never become success or leak", async () => {
+    const made = await enqueue(); await pull();
+    const reply = await ack(made.body.request_id, { outcome: "request_processed", state: { ...state(), binding_id: "wrong" } });
+    expect(reply.status).toBe(400);
+    expect((await read(made.body.request_id)).body).toMatchObject({ status: "unknown", error: "session_control_invalid_response" });
+    const next = await enqueue(); await pull();
+    const secret = "http://secret-host/?token=ntok_secret";
+    expect((await api(ntok.token!, `${root}/${next.body.request_id}/ack`, { ...binding, status: "failed", error: secret })).body.error).toBe("session_control_invalid_response");
+    expect(JSON.stringify((await read(next.body.request_id)).body)).not.toContain(secret);
+  });
+  test("known runtime refusal is failed; already_idle receipt is accepted", async () => {
+    const made = await enqueue(); await pull();
+    expect((await api(ntok.token!, `${root}/${made.body.request_id}/ack`, { ...binding, status: "failed", error: "session_control_unsupported" })).body.status).toBe("failed");
+    const next = await enqueue(); await pull();
+    expect((await ack(next.body.request_id, { outcome: "already_idle", state: { ...state(), active: false, can_request_background: false } })).body.status).toBe("done");
+  });
+  test("lease expiry refuses new work and Hub restart loses IDs without replay", async () => {
+    const made = await enqueue();
+    setSystemTime(new Date(Date.now() + 76_000));
+    expect((await enqueue()).body.error).toBe("session_control_unavailable");
+    setSystemTime();
+    server.stop(true);
+    const { bootServer } = await import("./server.js");
+    server = bootServer({ port: 0, hostname: "127.0.0.1" }); base = `http://127.0.0.1:${server.port}`;
+    expect((await read(made.body.request_id)).status).toBe(404);
+    expect((await pull()).body.error).toBe("session_control_changed");
+  });
+});

package/src/node-session-control.ts

@@ -0,0 +1,254 @@
+import { randomBytes } from "node:crypto";
+import { db } from "./db.js";
+import { getUserNetworkRole, resolveToken, sessionIdleDays } from "./auth.js";
+import { isAgentRestricted } from "./agent-access.js";
+import { resolveNodeCaller } from "./create-node.js";
+import { pushEvent } from "./push.js";
+
+type Identity = { session_id: string; binding_id: string };
+type Credential = { token_id: string; user_id: string; network_id: string | null;
+  bound_node_id: string | null; scope: string; role: string };
+type Node = { node_id: string; network_id: string; owner_user_id: string | null; alias: string };
+type Bridge = Identity & { tokenId: string; expires: number; retired: Set<string> };
+type Entry = Identity & { request_id: string; operation: "state" | "background";
+  networkId: string; nodeId: string; tokenId: string; requester: string; expires_at: number;
+  status: "pending" | "in_progress" | "done" | "failed" | "unknown" | "expired";
+  result?: unknown; error?: string };
+const TTL = 15_000, LEASE = 75_000, CAP = 1024, HISTORY = 64;
+const ROOT = "/api/node-session-control";
+const ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
+const ERRORS = new Set(["unavailable", "changed", "unsupported", "invalid_response", "request_invalid",
+  "request_expired", "request_limit"].map(s => `session_control_${s}`).concat("session_background_outcome_unknown"));
+const keys = (o: Record<string, unknown>, allowed: string[]) => Object.keys(o).every(k => allowed.includes(k));
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const id = (v: unknown): v is string => typeof v === "string" && ID.test(v);
+const identity = (v: unknown): v is Identity => object(v) && keys(v, ["session_id", "binding_id"])
+  && id(v.session_id) && id(v.binding_id);
+const same = (a: Identity, b: Identity) => a.session_id === b.session_id && a.binding_id === b.binding_id;
+const generation = (token: string, v: Identity) => JSON.stringify([token, v.session_id, v.binding_id]);
+const fail = (error: string, status = 409) => Response.json({ ok: false, error }, { status });
+const ok = (value: object) => Response.json({ ok: true, ...value });
+
+// Recheck stored identities without storing plaintext bearer tokens. The SQL
+// mirrors resolveToken's expiry/revoke/idle rules; membership is checked below.
+function credential(tokenId: string): Credential | null {
+  const days = sessionIdleDays();
+  return db.get<Credential>(`SELECT t.token_id,t.user_id,t.network_id,t.bound_node_id,t.scope,u.role
+    FROM api_tokens t JOIN users u ON u.user_id=t.user_id WHERE t.token_id=?1
+    AND t.revoked_at IS NULL AND (t.expires_at IS NULL OR t.expires_at>datetime('now'))
+    AND NOT (t.scope='user' AND t.network_id IS NULL AND ?2>0
+      AND COALESCE(t.last_used_at,t.created_at)<datetime('now',?3))`,
+    tokenId, days, `-${Math.round(days * 86400)} seconds`) ?? null;
+}
+function node(nodeId: string): Node | null {
+  return db.get<Node>("SELECT node_id,network_id,owner_user_id,alias FROM nodes WHERE node_id=?1", nodeId) ?? null;
+}
+function isHumanCredential(c: Credential | null): c is Credential {
+  return !!c && c.network_id === null && c.bound_node_id === null
+    && (c.scope === "user" || c.scope === "full");
+}
+function human(tokenId: string, n: Node): boolean {
+  const c = credential(tokenId);
+  if (!isHumanCredential(c) || !n.network_id) return false;
+  const role = getUserNetworkRole(c.user_id, n.network_id);
+  return !!role && role !== "viewer" && !isAgentRestricted(c.user_id, n.network_id)
+    && (c.user_id === n.owner_user_id || role === "owner" || role === "admin" || c.role === "admin");
+}
+function bound(tokenId: string, n?: Node | null): Node | null {
+  const c = credential(tokenId);
+  if (!c?.bound_node_id || !c.network_id || c.scope !== "network") return null;
+  const target = n ?? node(c.bound_node_id);
+  if (!target || c.bound_node_id !== target.node_id || c.network_id !== target.network_id
+    || !getUserNetworkRole(c.user_id, c.network_id) || isAgentRestricted(c.user_id, c.network_id)) return null;
+  const caller = resolveNodeCaller(tokenId);
+  return caller.ok && caller.kind === "node" && caller.nodeId === target.node_id
+    && caller.networkId === target.network_id ? target : null;
+}
+async function body(req: Request): Promise<Record<string, unknown> | null> {
+  const reader = req.body?.getReader();
+  if (!reader) return null;
+  const chunks: Uint8Array[] = []; let size = 0;
+  try {
+    for (;;) {
+      const part = await reader.read(); if (part.done) break;
+      size += part.value.byteLength;
+      if (size > 8192) { await reader.cancel(); return null; }
+      chunks.push(part.value);
+    }
+    const v: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    return object(v) ? v : null;
+  } catch { return null; }
+}
+function state(value: unknown, e: Entry): boolean {
+  return object(value) && keys(value, ["session_id", "binding_id", "supported", "active", "can_request_background", "observed_at"])
+    && same(value as Identity, e) && typeof value.supported === "boolean" && typeof value.active === "boolean"
+    && typeof value.can_request_background === "boolean" && typeof value.observed_at === "number"
+    && Number.isFinite(value.observed_at) && value.observed_at > 0
+    && (!value.can_request_background || (value.supported && value.active));
+}
+function validResult(v: unknown, e: Entry): boolean {
+  if (e.operation === "state") return state(v, e);
+  return object(v) && keys(v, ["outcome", "state"])
+    && (v.outcome === "request_processed" || v.outcome === "already_idle") && state(v.state, e)
+    && (v.outcome !== "already_idle" || (object(v.state)
+      && v.state.active === false && v.state.can_request_background === false));
+}
+
+/** One finite, process-local relay per Hub boot. Restart loses requests (404),
+ * never replays them. Multi-worker deployments require process affinity.
+ * A claim authorizes one delivery, not proof that any tool moved to background.
+ */
+export function createNodeSessionControlRelay() {
+  const bridges = new Map<string, Bridge>();
+  const entries = new Map<string, Entry>();
+  const key = (n: Node) => JSON.stringify([n.network_id, n.node_id]);
+  function close(e: Entry, error: string) {
+    e.status = e.status === "in_progress" ? "unknown" : "failed";
+    e.error = e.status === "unknown" ? "session_background_outcome_unknown" : error;
+  }
+  function refresh(e: Entry, now: number) {
+    if (e.status !== "pending" && e.status !== "in_progress") return;
+    if (now >= e.expires_at) {
+      e.status = e.status === "in_progress" ? "unknown" : "expired";
+      e.error = e.status === "unknown" ? "session_background_outcome_unknown" : "session_control_request_expired";
+      return;
+    }
+    const n = node(e.nodeId), b = n && bridges.get(key(n));
+    if (!n || n.network_id !== e.networkId || !human(e.requester, n) || !bound(e.tokenId, n)) {
+      close(e, "session_control_unavailable");
+    } else if (!b || b.expires <= now || b.tokenId !== e.tokenId || !same(b, e)) {
+      close(e, "session_control_changed");
+    }
+  }
+  function sweep(now: number) {
+    for (const [k, e] of entries) {
+      refresh(e, now);
+      if (now > e.expires_at + 60_000) entries.delete(k);
+    }
+  }
+  return async function handle(req: Request, url: URL): Promise<Response | null> {
+    if (url.pathname !== ROOT && !url.pathname.startsWith(`${ROOT}/`)) return null;
+    try {
+    // Header-only, persisted credential authority; no master/dev-open fallback.
+    const raw = req.headers.get("authorization")?.match(/^Bearer (\S+)$/)?.[1] ?? "";
+    const auth = resolveToken(raw);
+    if (!auth?.tokenId) return fail("session_control_unavailable", 401);
+    const tokenId = auth.tokenId;
+    const c = credential(tokenId);
+    if (!c) return fail("session_control_unavailable", 401);
+    const isHuman = isHumanCredential(c);
+    const isNode = c.scope === "network" && !!c.network_id;
+    const suffix = url.pathname.slice(ROOT.length);
+      if (req.method === "GET" && /^\/(bg|sc)_\d{13}_[A-Za-z0-9_-]{8,64}$/.test(suffix)) {
+        const e = entries.get(suffix.slice(1));
+        // Unknown/restarted Hub and unauthorized reads reveal no request data.
+        if (!isHuman) return fail("session_control_unavailable", 403);
+        if (!e) return fail("session_control_unavailable", 404);
+        const n = node(e.nodeId);
+        if (!n || url.searchParams.get("network_id") !== e.networkId || n.network_id !== e.networkId || !human(tokenId, n)) {
+          return fail("session_control_unavailable", 403);
+        }
+        refresh(e, Date.now());
+        return ok({ request_id: e.request_id, status: e.status,
+          ...(e.result === undefined ? {} : { result: e.result }), ...(e.error ? { error: e.error } : {}) });
+      }
+      if (req.method !== "POST") return fail("session_control_request_invalid", 405);
+      const v = await body(req);
+      if (!v) return fail("session_control_request_invalid", 400);
+      const now = Date.now();
+      if (suffix === "/bridge") {
+        if (!isNode) return fail("session_control_unavailable", 403);
+        if (!keys(v, ["session_id", "binding_id", "expected"]) || !id(v.session_id) || !id(v.binding_id)
+          || !object(v.expected) || !keys(v.expected, ["node_id", "network_id"])
+          || !id(v.expected.node_id) || !id(v.expected.network_id)) return fail("session_control_request_invalid", 400);
+        // Body reading is complete. This synchronous section rechecks authority
+        // and expected identity BEFORE sweep, retirement, or registration writes.
+        // expected is an assertion, never a source for binding or proof fields.
+        const c = credential(tokenId), n = bound(tokenId);
+        if (!c || !n) return fail("session_control_unavailable", 403);
+        if (c.bound_node_id !== n.node_id || c.network_id !== n.network_id
+          || v.expected.node_id !== c.bound_node_id || v.expected.network_id !== c.network_id) {
+          return fail("session_control_changed");
+        }
+        const registration = { session_id: v.session_id, binding_id: v.binding_id };
+        const k = key(n), b = bridges.get(k), g = generation(tokenId, registration);
+        if (b?.retired.has(g)) return fail("session_control_changed");
+        const replacing = b && (b.tokenId !== tokenId || !same(b, registration));
+        if ((replacing && b.retired.size >= HISTORY) || (!b && bridges.size >= CAP)) {
+          return fail("session_control_request_limit", 429);
+        }
+        sweep(now);
+        if (replacing) {
+          b.retired.add(generation(b.tokenId, b));
+          for (const e of entries.values()) if (e.nodeId === n.node_id && e.networkId === n.network_id
+            && (e.status === "pending" || e.status === "in_progress")) close(e, "session_control_changed");
+        }
+        bridges.set(k, { ...registration, tokenId, expires: now + LEASE, retired: b?.retired ?? new Set() });
+        return ok({ expires_at: now + LEASE,
+          identity: { node_id: c.bound_node_id, network_id: c.network_id, token_id: c.token_id } });
+      }
+      sweep(now);
+      if (!suffix) {
+        if (!isHuman) return fail("session_control_unavailable", 403);
+        if (!keys(v, ["network_id", "node_id", "operation", "expected"]) || !id(v.network_id) || !id(v.node_id)
+          || (v.operation !== "state" && v.operation !== "background")
+          || (v.expected !== undefined && !identity(v.expected)) || (v.operation === "background" && !identity(v.expected))) {
+          return fail("session_control_request_invalid", 400);
+        }
+        const n = node(v.node_id);
+        if (!n || n.network_id !== v.network_id || !human(tokenId, n)) return fail("session_control_unavailable", 403);
+        const b = bridges.get(key(n));
+        if (!b || b.expires <= now || !bound(b.tokenId, n)) return fail("session_control_unavailable");
+        if (v.expected && !same(v.expected as Identity, b)) return fail("session_control_changed");
+        if (entries.size >= CAP || [...entries.values()].some(e => e.nodeId === n.node_id
+          && e.networkId === n.network_id && (e.status === "pending" || e.status === "in_progress"))) {
+          return fail("session_control_request_limit", 429);
+        }
+        const request_id = `${v.operation === "background" ? "bg" : "sc"}_${now}_${randomBytes(18).toString("base64url")}`;
+        entries.set(request_id, { session_id: b.session_id, binding_id: b.binding_id, request_id,
+          operation: v.operation, networkId: n.network_id, nodeId: n.node_id, tokenId: b.tokenId,
+          requester: tokenId, expires_at: now + TTL, status: "pending" });
+        pushEvent(n.alias, { type: "session_control", request_id }, n.network_id);
+        return ok({ request_id, status: "pending", expires_at: now + TTL });
+      }
+      if (!isNode) return fail("session_control_unavailable", 403);
+      const n = bound(tokenId);
+      if (!n) return fail("session_control_unavailable", 403);
+      const k = key(n), b = bridges.get(k);
+      if (!b || b.expires <= now || b.tokenId !== tokenId) return fail("session_control_changed");
+      if (suffix === "/pull") {
+        if (!identity(v)) return fail("session_control_request_invalid", 400);
+        if (!same(b, v)) return fail("session_control_changed");
+        const e = [...entries.values()].find(e => e.nodeId === n.node_id && e.networkId === n.network_id && e.status === "pending");
+        if (!e) return ok({ request: null });
+        refresh(e, now);
+        if (e.status !== "pending") return ok({ request: null });
+        // No await between authority recheck, claim, and response. Never requeue.
+        e.status = "in_progress";
+        return ok({ request: { request_id: e.request_id, operation: e.operation,
+          session_id: e.session_id, binding_id: e.binding_id, expires_at: e.expires_at } });
+      }
+      if (/^\/(bg|sc)_\d{13}_[A-Za-z0-9_-]{8,64}\/ack$/.test(suffix)) {
+        if (!keys(v, ["session_id", "binding_id", "status", "result", "error"]) || !id(v.session_id) || !id(v.binding_id)
+          || (v.status !== "done" && v.status !== "failed")) return fail("session_control_request_invalid", 400);
+        const e = entries.get(suffix.split("/")[1]);
+        if (!e) return fail("session_control_unavailable", 404);
+        if (e.nodeId !== n.node_id || e.networkId !== n.network_id || e.tokenId !== tokenId || !same(e, v as Identity)
+          || !same(b, e)) return fail("session_control_changed");
+        refresh(e, now);
+        if (e.status !== "in_progress") return fail("session_control_request_expired");
+        if (v.status === "done" && validResult(v.result, e) && v.error === undefined) {
+          e.status = "done"; e.result = v.result;
+        } else if (v.status === "failed" && typeof v.error === "string" && ERRORS.has(v.error) && v.result === undefined) {
+          e.status = "failed"; e.error = v.error;
+        } else {
+          // Invalid/untrusted runtime replies never become success or leak raw errors.
+          e.status = "unknown"; e.error = "session_control_invalid_response";
+          return fail(e.error, 400);
+        }
+        return ok({ request_id: e.request_id, status: e.status });
+      }
+      return fail("session_control_request_invalid", 404);
+    } catch { return fail("session_control_unavailable", 503); }
+  };
+}