@sleep2agi/commhub-server 0.9.0-preview.6 → 0.9.0-preview.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.6",
+  "version": "0.9.0-preview.7",
   "description": "CommHub Server \u2014 AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",

package/src/db.ts

@@ -301,6 +301,29 @@ try {
   if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
 }
 
+// RFC-026 §9 / #338 PR2 — daemon self-declare fields promoted from
+// config_snapshot to first-class indexable columns. The hub
+// `list_host_supervisors` MCP tool reads these directly without parsing
+// the snapshot JSON on every list call.
+//
+// Both fields are JSON arrays of strings:
+//   runtimes_supported    e.g. ["claude-agent-sdk","codex-sdk","grok-build-acp"]
+//   allowed_secret_keys   e.g. ["ANTHROPIC_API_KEY","OPENAI_API_KEY"]
+//
+// Stored as TEXT (JSON-encoded) — SQLite has no native array type and
+// the wrapper code is small. Both nullable for pre-PR2 daemons; the
+// list endpoint falls back to [] when null.
+try {
+  db.exec(`ALTER TABLE nodes ADD COLUMN runtimes_supported TEXT`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+try {
+  db.exec(`ALTER TABLE nodes ADD COLUMN allowed_secret_keys TEXT`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/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/index.ts

@@ -1962,6 +1962,110 @@ Bun.serve({
     //      stable, dashboard-facing fields only.
     // Add a new column to this list explicitly when a real client needs
     // it; do NOT switch back to SELECT *.
+    // ── REST: list host_supervisor daemons (RFC-026 §9.2.2 / #338 PR2) ──
+    // Mirror of the `list_host_supervisors` MCP tool for non-MCP callers.
+    // Same SQL + role-extract + member-脱敏 logic; SEC-1 scoped via REST
+    // auth pipeline (restScope). Returns {ok, daemons:[...], count}.
+    if (url.pathname === "/api/host-supervisors") {
+      const netParam = url.searchParams.get("network_id");
+      const effectiveNetId = restScope.networkId ?? netParam ?? null;
+      if (!effectiveNetId) {
+        return withCors(req, Response.json({ ok: false, error: "missing_network_id" }, { status: 400 }));
+      }
+      // Role for member-脱敏 (admin/owner = full host_telemetry, others = masked)
+      let isPrivileged = false;
+      if (restAuth?.userId) {
+        const role = getUserNetworkRole(restAuth.userId, effectiveNetId);
+        isPrivileged = role === "admin" || role === "owner";
+      } else {
+        // Network-token caller (no user) — treat as privileged within its network
+        isPrivileged = true;
+      }
+
+      // EXISTS subquery handles BOTH revoked_at SET and DELETEd token
+      // rows (revokeToken DELETEs the row in production — PR2 v1
+      // SHOULD-FIX per 通信龙 audit). EXISTS naturally dedupes daemons
+      // with rotated tokens.
+      const sqlRows = db.all<Record<string, any>>(`
+        SELECT
+          n.node_id, n.alias, n.hostname, n.network_id,
+          n.runtimes_supported, n.allowed_secret_keys,
+          n.created_at, n.updated_at,
+          s.last_seen_at AS session_last_seen,
+          s.cpu_cores AS session_cpu_cores,
+          s.mem_total_gb AS session_mem_total_gb,
+          s.ip AS session_ip,
+          n.config_snapshot
+        FROM nodes n
+        LEFT JOIN sessions s ON s.alias = n.alias AND (s.network_id = n.network_id OR s.network_id IS NULL)
+        WHERE n.network_id = ?1
+          AND EXISTS (
+            SELECT 1 FROM api_tokens t
+            WHERE t.network_id = n.network_id
+              AND t.name = 'node:' || n.alias
+              AND t.revoked_at IS NULL
+          )
+        ORDER BY n.updated_at DESC
+      `, effectiveNetId);
+
+      const nowMs = Date.now();
+      const ONLINE_MS = 60_000;
+      const daemons = sqlRows
+        .map(r => {
+          let snapRole: string | null = null;
+          if (r.config_snapshot) {
+            try {
+              const parsed = typeof r.config_snapshot === "string" ? JSON.parse(r.config_snapshot) : r.config_snapshot;
+              snapRole = typeof parsed?.role === "string" ? parsed.role : null;
+            } catch { /* malformed */ }
+          }
+          return { row: r, role: snapRole };
+        })
+        .filter(({ role }) => role === "host_supervisor")
+        .map(({ row: r }) => {
+          let online = false;
+          let lastSeenAt: string | null = null;
+          if (r.session_last_seen) {
+            lastSeenAt = r.session_last_seen;
+            const t = Date.parse(r.session_last_seen);
+            if (!isNaN(t)) online = (nowMs - t) <= ONLINE_MS;
+          }
+          let runtimes: string[] = [];
+          let secrets: string[] = [];
+          try {
+            if (r.runtimes_supported) {
+              const parsed = JSON.parse(r.runtimes_supported);
+              runtimes = Array.isArray(parsed) ? parsed.filter((s: unknown) => typeof s === "string") : [];
+            }
+          } catch {}
+          try {
+            if (r.allowed_secret_keys) {
+              const parsed = JSON.parse(r.allowed_secret_keys);
+              secrets = Array.isArray(parsed) ? parsed.filter((s: unknown) => typeof s === "string") : [];
+            }
+          } catch {}
+          const telemetry: Record<string, unknown> = {
+            alert_level: online ? "green" : "gray",
+          };
+          if (isPrivileged) {
+            telemetry.cpu_cores = r.session_cpu_cores ?? null;
+            telemetry.mem_gb = r.session_mem_total_gb ?? null;
+            telemetry.ip_internal = r.session_ip ?? null;
+          }
+          return {
+            daemon_node_id: r.node_id,
+            alias: r.alias,
+            hostname: r.hostname,
+            online,
+            last_seen_at: lastSeenAt,
+            runtimes_supported: runtimes,
+            allowed_secret_keys: secrets,
+            host_telemetry: telemetry,
+          };
+        });
+      return withCors(req, Response.json({ ok: true, daemons, count: daemons.length }));
+    }
+
     if (url.pathname === "/api/nodes") {
       const nodeId = url.searchParams.get("node_id");
       const alias = url.searchParams.get("alias");

package/src/list-host-supervisors.test.ts

@@ -0,0 +1,314 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db, hashToken, generateId } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+// RFC-026 §9.2 / #338 PR2 v2 — list_host_supervisors HANDLER tests.
+//
+// PR2 v1 used a mirror-SQL pattern (re-implemented the query in the test
+// itself) → trivially passed but didn't exercise the handler. 通信龙 audit
+// caught: that style misses the SEC-1 scope-derivation bug
+// (`getNetworkId(clientNetId)` returns the unchecked client-supplied
+// network_id for utok_ callers when enforceNetworkId is null, leaking
+// cross-tenant daemons). This rewrite drives the registered MCP tool
+// through registerTools() so the auth context is real.
+//
+// Covers:
+//   SEC-1.1 — cross-tenant utok_ caller with foreign network_id: DENIED
+//   SEC-1.2 — admin caller with own network_id: returns own daemons
+//   SEC-1.3 — caller with no network_id: returns daemons in all member networks
+//   masking — non-admin viewer: host_telemetry IP/cpu/mem stripped, alert_level still surfaces
+//   revoked — DELETEd token row (revokeToken path): daemon excluded
+//   revoked — revoked_at SET token: daemon excluded
+//   self-declare — runtimes_supported/allowed_secret_keys surface from columns
+//   pre-PR2 daemon — empty arrays on NULL columns (back-compat)
+
+const NET_ALPHA = "net_lhs_alpha";
+const NET_BETA = "net_lhs_beta";
+
+interface ToolHandler { (args: any, extra?: any): Promise<{ content: Array<{ type: "text"; text: string }> }>; }
+interface Reply { ok?: boolean; error?: string; daemons?: any[]; count?: number; }
+
+function cleanup() {
+  for (const n of [NET_ALPHA, NET_BETA]) {
+    try { db.run("DELETE FROM nodes WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM sessions WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM network_members WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM networks WHERE network_id = ?1", [n]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id LIKE 'u_lhs_%'"); } catch {}
+}
+
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seedUser(user_id: string) {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [user_id, user_id],
+  );
+}
+function seedNetwork(net_id: string, owner_id = "u_lhs_owner") {
+  db.run(
+    `INSERT OR REPLACE INTO networks (network_id, network_name, owner_id, created_at)
+     VALUES (?1, ?2, ?3, datetime('now'))`,
+    [net_id, net_id, owner_id],
+  );
+}
+function seedMembership(user_id: string, net_id: string, role: "owner" | "admin" | "member" | "viewer" = "member") {
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at)
+     VALUES (?1, ?2, ?3, datetime('now'))`,
+    [user_id, net_id, role],
+  );
+}
+function seedDaemon(opts: {
+  network_id: string, alias: string, node_id?: string,
+  role?: string,
+  runtimes?: string[],
+  secrets?: string[],
+  sessionAgeMs?: number,
+  mintToken?: boolean,
+  tokenRevokedAt?: boolean,
+  tokenDeleted?: boolean,
+}) {
+  const node_id = opts.node_id || `node_${opts.network_id}_${opts.alias}`;
+  const snapshot = JSON.stringify({
+    model: "claude-opus", flags: {}, role: opts.role ?? "host_supervisor",
+    runtimes_supported: opts.runtimes ?? ["claude-agent-sdk"],
+    allowed_secret_keys: opts.secrets ?? [],
+  });
+  db.run(
+    `INSERT OR REPLACE INTO nodes (
+      node_id, node_name, alias, network_id,
+      runtimes_supported, allowed_secret_keys,
+      config_snapshot, hostname,
+      created_at, updated_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, datetime('now'), datetime('now'))`,
+    [node_id, opts.alias, opts.alias, opts.network_id,
+     JSON.stringify(opts.runtimes ?? ["claude-agent-sdk"]),
+     JSON.stringify(opts.secrets ?? []),
+     snapshot, `host-${opts.alias}`],
+  );
+  if (opts.sessionAgeMs !== undefined) {
+    const ts = new Date(Date.now() - opts.sessionAgeMs).toISOString().replace("T", " ").replace(/\..+/, "");
+    db.run(
+      `INSERT OR REPLACE INTO sessions (resume_id, alias, network_id, last_seen_at, status, cpu_cores, mem_total_gb, ip)
+       VALUES (?1, ?2, ?3, ?4, 'idle', 8, 16, '10.0.0.5')`,
+      [`s_${node_id}`, opts.alias, opts.network_id, ts],
+    );
+  }
+  if (opts.mintToken !== false && !opts.tokenDeleted) {
+    db.run(
+      `INSERT OR REPLACE INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+       VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, ?6)`,
+      [`tok_${node_id}`, `u_seed_${node_id}`, opts.network_id, `node:${opts.alias}`,
+       `hash_${node_id}`,
+       opts.tokenRevokedAt ? new Date().toISOString().replace("T", " ").replace(/\..+/, "") : null],
+    );
+  }
+  return node_id;
+}
+
+/** Build a server with registerTools wired to a specific enforceUserId. */
+function buildToolHandler(enforceUserId: string | null): ToolHandler {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  // Capture the registered tool function. The MCP SDK's server.tool stores
+  // the handler internally; we intercept by overriding before registerTools.
+  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);
+  };
+  // Some tools use registerTool; intercept that too
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, _cfg: any, handler: ToolHandler) => {
+      tools[name] = handler;
+      return origRegisterTool(name, _cfg, handler);
+    };
+  }
+  registerTools(
+    server,
+    /* clientIP */ undefined,
+    /* enforceNetworkId */ null,
+    /* enforceUserId */ enforceUserId,
+    /* callerAlias */ null,
+    /* callerTokenIsNetwork */ false,
+    /* callerTokenId */ null,
+  );
+  const h = tools["list_host_supervisors"];
+  if (!h) throw new Error("list_host_supervisors tool not registered");
+  return h;
+}
+
+async function callList(handler: ToolHandler, args: any = {}): Promise<Reply> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text) as Reply;
+}
+
+describe("list_host_supervisors HANDLER tests (RFC-026 §9.2, PR2 v2)", () => {
+  test("SEC-1.1: cross-tenant utok_ caller with foreign network_id → DENIED", async () => {
+    const userA = "u_lhs_alice"; // belongs to NET_ALPHA only
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedNetwork(NET_BETA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_BETA, alias: "secret-beta-daemon" });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_BETA });
+    // PR2 v1 BUG: this returned ok:true with secret-beta-daemon in the list.
+    expect(reply.ok).toBe(false);
+    expect(reply.error).toMatch(/access denied|not a member/i);
+    // Belt: hostname not in error payload
+    expect(JSON.stringify(reply)).not.toContain("secret-beta-daemon");
+    expect(JSON.stringify(reply)).not.toContain("host-secret-beta-daemon");
+  });
+
+  test("SEC-1.2: admin caller with own network_id returns own daemons", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "alpha-daemon-1" });
+    seedDaemon({ network_id: NET_ALPHA, alias: "alpha-daemon-2" });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    expect(reply.ok).toBe(true);
+    const aliases = (reply.daemons ?? []).map(d => d.alias).sort();
+    expect(aliases).toEqual(["alpha-daemon-1", "alpha-daemon-2"]);
+  });
+
+  test("SEC-1.3: caller without network_id arg → returns daemons across member networks only", async () => {
+    const userA = "u_lhs_alice"; // member of NET_ALPHA only
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedNetwork(NET_BETA);
+    seedMembership(userA, NET_ALPHA, "member");
+    seedDaemon({ network_id: NET_ALPHA, alias: "ok-daemon" });
+    seedDaemon({ network_id: NET_BETA, alias: "forbidden-daemon" });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler);
+    expect(reply.ok).toBe(true);
+    const aliases = (reply.daemons ?? []).map(d => d.alias);
+    expect(aliases).toContain("ok-daemon");
+    expect(aliases).not.toContain("forbidden-daemon");
+  });
+
+  test("masking: member caller gets host_telemetry without IP/cpu/mem; admin gets full", async () => {
+    const userMember = "u_lhs_bob_member";
+    const userAdmin = "u_lhs_carol_admin";
+    seedUser(userMember);
+    seedUser(userAdmin);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userMember, NET_ALPHA, "member");
+    seedMembership(userAdmin, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "telemetry-daemon", sessionAgeMs: 5_000 });
+
+    const memberHandler = buildToolHandler(userMember);
+    const memberReply = await callList(memberHandler, { network_id: NET_ALPHA });
+    expect(memberReply.daemons?.[0].host_telemetry.alert_level).toBeDefined();
+    expect(memberReply.daemons?.[0].host_telemetry).not.toHaveProperty("cpu_cores");
+    expect(memberReply.daemons?.[0].host_telemetry).not.toHaveProperty("mem_gb");
+    expect(memberReply.daemons?.[0].host_telemetry).not.toHaveProperty("ip_internal");
+
+    const adminHandler = buildToolHandler(userAdmin);
+    const adminReply = await callList(adminHandler, { network_id: NET_ALPHA });
+    expect(adminReply.daemons?.[0].host_telemetry.cpu_cores).toBe(8);
+    expect(adminReply.daemons?.[0].host_telemetry.mem_gb).toBe(16);
+    expect(adminReply.daemons?.[0].host_telemetry.ip_internal).toBe("10.0.0.5");
+  });
+
+  test("revoked: DELETEd token row (revokeToken path) excludes daemon", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "alive-daemon" });
+    seedDaemon({ network_id: NET_ALPHA, alias: "deleted-token-daemon", tokenDeleted: true });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const aliases = (reply.daemons ?? []).map(d => d.alias).sort();
+    expect(aliases).toContain("alive-daemon");
+    expect(aliases).not.toContain("deleted-token-daemon");
+  });
+
+  test("revoked: token with revoked_at SET also excludes daemon", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "alive-daemon" });
+    seedDaemon({ network_id: NET_ALPHA, alias: "revoked-at-daemon", tokenRevokedAt: true });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const aliases = (reply.daemons ?? []).map(d => d.alias).sort();
+    expect(aliases).toContain("alive-daemon");
+    expect(aliases).not.toContain("revoked-at-daemon");
+  });
+
+  test("role filter: regular member nodes (role=member) excluded after extraction", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "real-daemon", role: "host_supervisor" });
+    seedDaemon({ network_id: NET_ALPHA, alias: "regular-node", role: "member" });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const aliases = (reply.daemons ?? []).map(d => d.alias).sort();
+    expect(aliases).toEqual(["real-daemon"]);
+  });
+
+  test("self-declare: runtimes_supported + allowed_secret_keys surface from columns", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({
+      network_id: NET_ALPHA, alias: "rich-daemon",
+      runtimes: ["claude-agent-sdk", "codex-sdk", "grok-build-acp"],
+      secrets: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+    });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const d = reply.daemons?.[0];
+    expect(d.runtimes_supported).toEqual(["claude-agent-sdk", "codex-sdk", "grok-build-acp"]);
+    expect(d.allowed_secret_keys).toEqual(["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]);
+  });
+
+  test("pre-PR2 daemon (NULL columns) extracts to empty arrays back-compat", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    db.run(
+      `INSERT INTO nodes (node_id, node_name, alias, network_id, config_snapshot, runtimes_supported, allowed_secret_keys, created_at, updated_at)
+       VALUES (?1, 'legacy', 'legacy', ?2, ?3, NULL, NULL, datetime('now'), datetime('now'))`,
+      ["node_legacy_alpha", NET_ALPHA, JSON.stringify({ role: "host_supervisor" })],
+    );
+    // Seed active token so the EXISTS guard lets it through
+    db.run(
+      `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash)
+       VALUES ('tok_legacy', 'u_seed_legacy', ?1, 'network', 'node:legacy', 'hash_legacy')`,
+      [NET_ALPHA],
+    );
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const d = reply.daemons?.find(d => d.alias === "legacy");
+    expect(d).toBeTruthy();
+    expect(d.runtimes_supported).toEqual([]);
+    expect(d.allowed_secret_keys).toEqual([]);
+  });
+});

package/src/tools.ts

@@ -298,6 +298,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         // discovery (#337 extracts this field). "host_supervisor" =
         // anet daemon. Default-stripping zod would drop this otherwise.
         role: z.string().max(64).optional().nullable(),
+        // RFC-026 §9.3 — daemon self-declare. Promoted to first-class
+        // columns by PR2 so list_host_supervisors reads them directly
+        // (no per-call snapshot JSON parse). Soft caps avoid abuse.
+        runtimes_supported: z.array(z.string().max(64)).max(16).optional(),
+        allowed_secret_keys: z.array(z.string().max(64)).max(64).optional(),
       }).optional().describe("RFC-024 — masked node config snapshot"),
     },
     async ({ resume_id, alias, status, task, output, score, progress, server: srv, hostname: hn, agent: ag, project_dir: pd, version: ver, tmux_name: tmux, node_id, session_id, config_path, channels, model: mdl, node_name: nn, network_id: netId, host, process_telemetry: proc, config_snapshot: cfgSnap }) => {
@@ -1818,6 +1823,140 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     throw e;
   };
 
+  // RFC-026 §9.2.1 / #338 PR2 — list_host_supervisors.
+  // Surfaces host_supervisor daemons in the caller's network with
+  // online flag + declared capabilities. Replaces the prior `node_daemon_`
+  // prefix heuristic (dashboard /api/anet/node-create) + the role-extract
+  // path on /api/nodes (#337). Member脱敏 strips host_telemetry IP /
+  // cpu / mem (per RFC-026 §6 #3 — daemons can leak internal topology
+  // to non-admin readers). Revoked daemon ntoks filtered out via
+  // join on api_tokens.revoked_at.
+  server.tool(
+    "list_host_supervisors",
+    "List host_supervisor daemon nodes in the caller's network (online status + runtimes_supported + allowed_secret_keys + telemetry; member-脱敏). RFC-026 §9.2.1.",
+    {
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ network_id: clientNetId }) => {
+      // SEC-1 — use resolveReadScope, NOT getNetworkId. getNetworkId is
+      // for write-tool helpers and pairs with `canWrite`; READ tools that
+      // bypass canWrite and trust getNetworkId leak across tenants
+      // (PR2 v1 BLOCKER per 通信龙 audit — utok_ caller with
+      // enforceNetworkId=null could pass any network_id and read daemon
+      // names + allowed_secret_keys for tenants they're not a member of).
+      // resolveReadScope checks network_members for the user + denies
+      // on non-membership, mirroring REST resolveRestNetworkScope.
+      const readScope = resolveReadScope(clientNetId);
+      if (readScope.denied) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: readScope.denied }) }] };
+      }
+      // Caller role for 脱敏 decision (admin/owner = full, others = masked).
+      // Use the resolved scope's networkId (the verified one), not the
+      // unchecked clientNetId.
+      const scopedNetId = readScope.networkId ?? null;
+      const callerRole = enforceUserId && scopedNetId
+        ? getUserNetworkRole(enforceUserId, scopedNetId)
+        : null;
+      // Network-bound tokens get full telemetry within their bound network
+      // (already gate-locked by enforceNetworkId path of resolveReadScope).
+      const isPrivileged = callerRole === "admin" || callerRole === "owner" || (!enforceUserId);
+
+      // Pull candidate daemons. Active-token EXISTS subquery handles BOTH
+      // revoked daemon ntoks (revoked_at set) AND DELETEd token rows
+      // (the standard revokeToken path deletes the row, not flagging
+      // revoked_at — PR2 v1 SHOULD-FIX per 通信龙 audit). EXISTS naturally
+      // dedupes if a daemon ever had multiple tokens (e.g. rotation; nit ⚪).
+      let sql = `
+        SELECT
+          n.node_id, n.alias, n.hostname, n.network_id,
+          n.runtimes_supported, n.allowed_secret_keys,
+          n.created_at, n.updated_at,
+          s.last_seen_at AS session_last_seen,
+          s.status AS session_status,
+          s.cpu_cores AS session_cpu_cores,
+          s.mem_total_gb AS session_mem_total_gb,
+          s.ip AS session_ip,
+          n.config_snapshot
+        FROM nodes n
+        LEFT JOIN sessions s ON s.alias = n.alias AND (s.network_id = n.network_id OR s.network_id IS NULL)
+        WHERE EXISTS (
+          SELECT 1 FROM api_tokens t
+          WHERE t.network_id = n.network_id
+            AND t.name = 'node:' || n.alias
+            AND t.revoked_at IS NULL
+        )
+      `;
+      const sqlParams: any[] = [];
+      sql = addReadScope(sql, sqlParams, readScope, "n.network_id");
+      sql += ` ORDER BY n.updated_at DESC`;
+      const rows = db.all<Record<string, any>>(sql, ...sqlParams);
+
+      // Filter to role=host_supervisor (read from config_snapshot;
+      // schema-promoted columns runtimes_supported/allowed_secret_keys
+      // are pre-extracted but role isn't a first-class column).
+      const nowMs = Date.now();
+      const ONLINE_MS = 60_000;
+      const daemons = rows
+        .map(r => {
+          let snapRole: string | null = null;
+          if (r.config_snapshot) {
+            try {
+              const parsed = typeof r.config_snapshot === "string" ? JSON.parse(r.config_snapshot) : r.config_snapshot;
+              snapRole = typeof parsed?.role === "string" ? parsed.role : null;
+            } catch { /* malformed snapshot — role stays null */ }
+          }
+          return { row: r, role: snapRole };
+        })
+        .filter(({ role }) => role === "host_supervisor")
+        .map(({ row: r }) => {
+          // online = sessions.last_seen_at within ONLINE_MS
+          let online = false;
+          let lastSeenAt: string | null = null;
+          if (r.session_last_seen) {
+            lastSeenAt = r.session_last_seen;
+            const t = Date.parse(r.session_last_seen);
+            if (!isNaN(t)) online = (nowMs - t) <= ONLINE_MS;
+          }
+          // Parse self-declare arrays (default to [] for pre-PR2 daemons)
+          let runtimes: string[] = [];
+          let secrets: string[] = [];
+          try {
+            if (r.runtimes_supported) {
+              const parsed = JSON.parse(r.runtimes_supported);
+              runtimes = Array.isArray(parsed) ? parsed.filter((s: unknown) => typeof s === "string") : [];
+            }
+          } catch { /* malformed — empty */ }
+          try {
+            if (r.allowed_secret_keys) {
+              const parsed = JSON.parse(r.allowed_secret_keys);
+              secrets = Array.isArray(parsed) ? parsed.filter((s: unknown) => typeof s === "string") : [];
+            }
+          } catch { /* malformed — empty */ }
+          // host_telemetry — member脱敏 drops IP/cpu/mem
+          const telemetry: Record<string, unknown> = {
+            alert_level: online ? "green" : "gray",
+          };
+          if (isPrivileged) {
+            telemetry.cpu_cores = r.session_cpu_cores ?? null;
+            telemetry.mem_gb = r.session_mem_total_gb ?? null;
+            telemetry.ip_internal = r.session_ip ?? null;
+          }
+          return {
+            daemon_node_id: r.node_id,
+            alias: r.alias,
+            hostname: r.hostname,
+            online,
+            last_seen_at: lastSeenAt,
+            runtimes_supported: runtimes,
+            allowed_secret_keys: secrets,
+            host_telemetry: telemetry,
+          };
+        });
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, daemons, count: daemons.length }) }] };
+    },
+  );
+
   // §2.5 step 1+2 — dashboard-facing tool. Validates spec, mint
   // child-ntok, stash env_blob in pendingEnvBlobs Map, write request
   // row (metadata only — no env_blob in SQL), pushEvent doorbell.
@@ -2699,9 +2838,25 @@ export function upsertNodeWithSec1Guard(input: UpsertNodeWithSec1GuardInput): Up
     ],
   );
   if (input.config_snapshot) {
+    // RFC-026 §9.3 / #338 PR2 — promote daemon self-declare fields to
+    // first-class indexable columns alongside the snapshot blob. The
+    // snapshot stays the source of truth for non-list reads; the columns
+    // exist so `list_host_supervisors` doesn't JSON.parse on every call.
+    // typeof-narrow the array fields (don't trust shape per
+    // [[feedback_typeof_narrow_extracted_fields]]; zod has already
+    // narrowed, but the input.config_snapshot type is `unknown` here).
+    const snap = input.config_snapshot as Record<string, unknown> | null;
+    const runtimesRaw = snap?.runtimes_supported;
+    const allowedRaw = snap?.allowed_secret_keys;
+    const runtimesJson = Array.isArray(runtimesRaw) && runtimesRaw.every(s => typeof s === "string")
+      ? JSON.stringify(runtimesRaw)
+      : null;
+    const allowedJson = Array.isArray(allowedRaw) && allowedRaw.every(s => typeof s === "string")
+      ? JSON.stringify(allowedRaw)
+      : null;
     db.run(
-      `UPDATE nodes SET config_snapshot = ?1 WHERE node_id = ?2`,
-      [JSON.stringify(input.config_snapshot), input.node_id],
+      `UPDATE nodes SET config_snapshot = ?1, runtimes_supported = ?2, allowed_secret_keys = ?3 WHERE node_id = ?4`,
+      [JSON.stringify(input.config_snapshot), runtimesJson, allowedJson, input.node_id],
     );
     // RFC-024 — finalize any pending/restarting update whose target
     // patch is now reflected in the snapshot. Closes the