@sleep2agi/commhub-server 0.9.0-preview.120 → 0.9.0-preview.122

package/src/daemon-provider-snapshots.ts

@@ -0,0 +1,269 @@
+// #906: human-requested readback of ONE daemon's private Provider metadata.
+// Hub registry is not a fallback. No credential values enter this protocol.
+import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from 'node:util';
+import { db } from "./db";
+import { getUserNetworkRole } from "./auth";
+import { validateDaemonProviderSnapshot } from "./shared/daemon-provider-snapshot";
+import { encryptSecret, decryptSecret, VaultError } from './vault';
+import { buildControllableMap } from './node-lifecycle-controllable';
+import { validProviderApplicationSelection, validProviderApplicationReceipt, type ProviderApplicationSelection } from './shared/provider-application';
+import { validLoginIntent, validLoginReceipt } from './shared/daemon-provider-login';
+
+export function providerScanTargets(networkId: string, daemonId: string) {
+  const ownership = buildControllableMap(
+    db.all<{ request_id: string; daemon_node_id: string }>('SELECT request_id,daemon_node_id FROM node_create_requests WHERE network_id=?1', networkId),
+    db.all<{ node_id: string; daemon_node_id: string }>('SELECT node_id,daemon_node_id FROM node_daemon_bindings WHERE network_id=?1 AND status=\'active\'', networkId));
+  const targets = db.all<{ node_id: string; alias: string }>('SELECT node_id,alias FROM nodes WHERE network_id=?1 ORDER BY node_id', networkId)
+    .filter(n => ownership.get(n.node_id) === daemonId && typeof n.alias === 'string');
+  if (targets.length > 200) throw Error('inventory_limit'); // no silent incomplete denominator
+  return targets;
+}
+
+type Human = { userId?: string | null; isNode: boolean; networkId: string | null };
+type Daemon = { ok: false; error: string } | { ok: true; networkId: string; daemonNodeId: string; daemonAlias: string };
+type Row = { request_id: string; network_id: string; daemon_node_id: string; status: string;
+  created_at: number; expires_at: number; observed_at: number | null; snapshot_json: string | null; error: string | null };
+const denied = (error: string) => ({ ok: false as const, error });
+function authorize(h: Human) {
+  if (h.isNode || !h.userId) return denied("user_token_required");
+  if (!h.networkId || !["owner", "admin"].includes(getUserNetworkRole(h.userId, h.networkId) || "")) return denied("provider_admin_required");
+  return null;
+}
+function daemonExists(networkId: string, nodeId: string): boolean {
+  const node = db.get<{ config_snapshot: string }>(
+    `SELECT n.config_snapshot FROM nodes n WHERE n.node_id=?1 AND n.network_id=?2
+      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
+        AND (t.expires_at IS NULL OR t.expires_at > datetime('now')))`, nodeId, networkId);
+  try { return JSON.parse(node?.config_snapshot || "{}").role === "host_supervisor"; } catch { return false; }
+}
+function expire(networkId: string, daemonId?: string) {
+  // Device-code instructions are short-lived; do not leave them in audit history.
+  db.run(`UPDATE daemon_provider_snapshots SET status='expired', snapshot_json=NULL, error='request_expired'
+    WHERE network_id=?1 AND request_id LIKE 'dpl_%' AND expires_at <= ?2`, [networkId, Date.now()]);
+  db.run(`UPDATE daemon_provider_snapshots SET status='expired', error='request_expired'
+    WHERE network_id=?1 AND status='pending' AND expires_at <= ?2
+    AND (?3 IS NULL OR daemon_node_id=?3)`, [networkId, Date.now(), daemonId ?? null]);
+  db.run(`DELETE FROM daemon_provider_writes WHERE request_id IN
+    (SELECT request_id FROM daemon_provider_snapshots WHERE network_id=?1 AND status!='pending')`, [networkId]);
+  db.run(`DELETE FROM daemon_provider_applications WHERE request_id IN
+    (SELECT request_id FROM daemon_provider_snapshots WHERE network_id=?1 AND status!='pending')`, [networkId]);
+  db.run(`DELETE FROM daemon_provider_logins WHERE request_id IN
+    (SELECT request_id FROM daemon_provider_snapshots WHERE network_id=?1 AND status!='pending')`, [networkId]);
+  db.run(`DELETE FROM daemon_provider_snapshots WHERE network_id=?1 AND expires_at < ?2`, [networkId, Date.now() - 7 * 86400_000]);
+}
+/** Validate the complete public projection before encrypting the private input. */
+function validateWrite(provider: any, networkId: string, daemonId: string) {
+  if (Buffer.byteLength(JSON.stringify(provider) || '') > 64 * 1024) throw new Error('invalid_provider');
+  const publicProvider = { ...provider, runtimes: provider?.runtimes?.map((r: any) => ({ ...r,
+    auth: r.auth?.map((a: any) => {
+      const { key, ...rest } = a;
+      if (a.kind === 'chatgpt' && key !== undefined) throw new Error('invalid_provider');
+      if (key !== undefined && (typeof key !== 'string' || !key || key.length > 8192 || /[\s\x00-\x1f\x7f]/.test(key))) throw new Error('invalid_provider');
+      // Only CLI write fields may be supplied; public-state flags are not writable.
+      if (Object.keys(a).some(k => !['id','kind','models','baseUrl','key','account_id'].includes(k))) throw new Error('invalid_provider');
+      // A bound login write must be confirmed present by its owning daemon;
+      // this projection is the expected receipt, not an independent Hub claim.
+      return { ...rest, credential_present: a.kind === 'api_key' || (a.kind === 'chatgpt' && a.account_id !== undefined), verification: 'not_checked', application: 'not_applied' };
+    }),
+  })) };
+  validateDaemonProviderSnapshot({ network_id: networkId, daemon_node_id: daemonId, source: 'daemon', revision: 0, providers: [publicProvider] }, networkId, daemonId);
+  return publicProvider;
+}
+export function requestProviderWrite(h: Human, daemonId: string, expectedRevision: number, provider: unknown) {
+  const refusal = authorize(h); if (refusal) return refusal;
+  if (!daemonExists(h.networkId!, daemonId)) return denied('daemon_not_found');
+  if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0 || expectedRevision >= Number.MAX_SAFE_INTEGER) return denied('invalid_revision');
+  try { validateWrite(provider, h.networkId!, daemonId); } catch { return denied('invalid_provider'); }
+  expire(h.networkId!, daemonId);
+  if (db.get('SELECT request_id FROM daemon_provider_snapshots WHERE network_id=?1 AND daemon_node_id=?2 AND status=\'pending\'', h.networkId!, daemonId)) return denied('provider_snapshot_busy');
+  try {
+    const enc = encryptSecret(JSON.stringify({ network_id: h.networkId, daemon_node_id: daemonId, provider }));
+    const requestId = `dps_${randomUUID()}`, now = Date.now();
+    db.transaction(() => {
+      db.run(`INSERT INTO daemon_provider_snapshots (request_id,network_id,daemon_node_id,requested_by,status,created_at,expires_at)
+        VALUES (?1,?2,?3,?4,'pending',?5,?6)`, [requestId, h.networkId!, daemonId, h.userId!, now, now + 120_000]);
+      db.run(`INSERT INTO daemon_provider_writes (request_id,expected_revision,ciphertext,iv,tag) VALUES (?1,?2,?3,?4,?5)`,
+        [requestId, expectedRevision, enc.ciphertext, enc.iv, enc.tag]);
+    });
+    return { ok: true as const, request_id: requestId, status: 'pending', expires_at: now + 120_000 };
+  } catch (error) { return denied(error instanceof VaultError ? error.code : 'provider_write_unavailable'); }
+}
+function privateWrite(requestId: string, networkId: string, daemonId: string) {
+  const row = db.get<{ expected_revision: number; ciphertext: any; iv: any; tag: any }>('SELECT * FROM daemon_provider_writes WHERE request_id=?1', requestId);
+  if (!row) return null;
+  const payload = JSON.parse(decryptSecret({ ciphertext: Buffer.from(row.ciphertext), iv: Buffer.from(row.iv), tag: Buffer.from(row.tag) }));
+  if (payload.network_id !== networkId || payload.daemon_node_id !== daemonId) throw new Error('scope_mismatch');
+  validateWrite(payload.provider, networkId, daemonId);
+  return { expected_revision: row.expected_revision, provider: payload.provider };
+}
+function applicationIntent(requestId: string) {
+  const row = db.get<{ expected_revision: number; selection_json: string }>('SELECT * FROM daemon_provider_applications WHERE request_id=?1', requestId);
+  if (!row) return null;
+  const selection = JSON.parse(row.selection_json);
+  if (!validProviderApplicationSelection(selection)) throw Error('invalid_application');
+  return { expected_revision: row.expected_revision, selection };
+}
+function boundApplicationTarget(networkId: string, daemonId: string, selection: ProviderApplicationSelection) {
+  return selection.node_id !== daemonId && providerScanTargets(networkId, daemonId).find(n => n.node_id === selection.node_id);
+}
+export function requestProviderApplication(h: Human, daemonId: string, revision: number, selection: unknown) {
+  const refusal = authorize(h); if (refusal) return refusal;
+  if (!daemonExists(h.networkId!, daemonId)) return denied('daemon_not_found');
+  if (!Number.isSafeInteger(revision) || revision < 0) return denied('invalid_revision');
+  if (!validProviderApplicationSelection(selection)) return denied('invalid_application');
+  try {
+    if (!boundApplicationTarget(h.networkId!, daemonId, selection)) return denied('application_target_not_bound');
+    expire(h.networkId!, daemonId);
+    const requestId = `dpa_${randomUUID()}`, now = Date.now();
+    db.transaction(() => {
+      db.run(`INSERT INTO daemon_provider_snapshots (request_id,network_id,daemon_node_id,requested_by,status,created_at,expires_at)
+        VALUES (?1,?2,?3,?4,'pending',?5,?6)`, [requestId, h.networkId!, daemonId, h.userId!, now, now + 600_000]);
+      db.run('INSERT INTO daemon_provider_applications (request_id,expected_revision,selection_json) VALUES (?1,?2,?3)',
+        [requestId, revision, JSON.stringify(selection)]);
+    });
+    return { ok: true as const, request_id: requestId, status: 'pending', expires_at: now + 600_000 };
+  } catch { return denied('provider_application_unavailable'); }
+}
+export function requestProviderSnapshot(h: Human, daemonId: string) {
+  const refusal = authorize(h); if (refusal) return refusal;
+  if (!daemonExists(h.networkId!, daemonId)) return denied("daemon_not_found");
+  expire(h.networkId!, daemonId);
+  // Repeated refresh clicks share the pending request; pending never means ready.
+  const pending = db.get<Row>(`SELECT * FROM daemon_provider_snapshots WHERE network_id=?1 AND daemon_node_id=?2 AND status='pending' ORDER BY created_at DESC LIMIT 1`, h.networkId!, daemonId);
+  if (pending) return { ok: true as const, request_id: pending.request_id, status: "pending", expires_at: pending.expires_at };
+  const requestId = `dps_${randomUUID()}`, now = Date.now();
+  db.run(`INSERT INTO daemon_provider_snapshots
+    (request_id,network_id,daemon_node_id,requested_by,status,created_at,expires_at)
+    VALUES (?1,?2,?3,?4,'pending',?5,?6) ON CONFLICT DO NOTHING`, [requestId, h.networkId!, daemonId, h.userId!, now, now + 120_000]);
+  const accepted = db.get<Row>(`SELECT * FROM daemon_provider_snapshots WHERE network_id=?1 AND daemon_node_id=?2 AND status='pending'`, h.networkId!, daemonId);
+  if (!accepted) return denied("provider_snapshot_busy");
+  return { ok: true as const, request_id: accepted.request_id, status: "pending", expires_at: accepted.expires_at };
+}
+export function requestProviderLogin(h: Human, daemonId: string, intent: unknown) {
+  const refusal = authorize(h); if (refusal) return refusal;
+  if (!daemonExists(h.networkId!, daemonId)) return denied('daemon_not_found');
+  if (!validLoginIntent(intent)) return denied('invalid_login_intent');
+  expire(h.networkId!, daemonId);
+  const requestId = `dpl_${randomUUID()}`, now = Date.now();
+  try {
+    db.transaction(() => {
+      db.run(`INSERT INTO daemon_provider_snapshots (request_id,network_id,daemon_node_id,requested_by,status,created_at,expires_at)
+        VALUES (?1,?2,?3,?4,'pending',?5,?6)`, [requestId, h.networkId!, daemonId, h.userId!, now, now + 120_000]);
+      db.run('INSERT INTO daemon_provider_logins (request_id,intent_json) VALUES (?1,?2)', [requestId, JSON.stringify(intent)]);
+    });
+    return { ok: true as const, request_id: requestId, status: 'pending', expires_at: now + 120_000 };
+  } catch { return denied('provider_snapshot_busy'); }
+}
+export function getProviderSnapshot(h: Human, requestId: string) {
+  const refusal = authorize(h); if (refusal) return refusal;
+  expire(h.networkId!);
+  const row = db.get<Row>(`SELECT * FROM daemon_provider_snapshots WHERE request_id=?1 AND network_id=?2`, requestId, h.networkId!);
+  if (!row) return denied("request_not_found");
+  return { ok: true, request_id: row.request_id, daemon_node_id: row.daemon_node_id, status: row.status,
+    expires_at: row.expires_at, observed_at: row.observed_at, error: row.error,
+    snapshot: !/^dp[al]_/.test(row.request_id) && row.snapshot_json ? JSON.parse(row.snapshot_json) : null,
+    ...(row.request_id.startsWith('dpl_') ? { login: row.snapshot_json ? JSON.parse(row.snapshot_json) : null } : {}),
+    ...(row.request_id.startsWith('dpa_') ? { application: row.snapshot_json ? JSON.parse(row.snapshot_json) : null } : {}) };
+}
+export function pullProviderSnapshots(d: Daemon, acceptWrites = false, acceptApplications = false, acceptLogins = false) {
+  if (!d.ok) return denied("caller_not_a_daemon");
+  if (!daemonExists(d.networkId, d.daemonNodeId)) return denied("caller_not_a_daemon");
+  expire(d.networkId, d.daemonNodeId);
+  const requests = db.all<{ request_id: string; expires_at: number }>(`SELECT request_id,expires_at FROM daemon_provider_snapshots
+    WHERE network_id=?1 AND daemon_node_id=?2 AND status='pending' ORDER BY created_at LIMIT 20`, d.networkId, d.daemonNodeId);
+  try { return { ok: true, requests: requests.flatMap<Record<string, unknown>>(r => {
+    if (r.request_id.startsWith('dpl_')) {
+      if (!acceptLogins) return [];
+      const row = db.get<{ intent_json: string }>('SELECT intent_json FROM daemon_provider_logins WHERE request_id=?1', r.request_id);
+      const intent = row && JSON.parse(row.intent_json);
+      if (!validLoginIntent(intent)) throw Error('invalid_login_intent');
+      return [{ ...r, operation: 'login', intent }];
+    }
+    if (r.request_id.startsWith('dpa_')) {
+      if (!acceptApplications) return []; // old daemons must not consume applications as scans
+      const application = applicationIntent(r.request_id);
+      const target = application && boundApplicationTarget(d.networkId, d.daemonNodeId, application.selection);
+      if (!target) {
+        db.run("UPDATE daemon_provider_snapshots SET status='failed',error='application_target_not_bound',observed_at=?1 WHERE request_id=?2 AND status='pending'", [Date.now(), r.request_id]);
+        db.run('DELETE FROM daemon_provider_applications WHERE request_id=?1', [r.request_id]);
+        return [];
+      }
+      return [{ ...r, operation: 'apply', ...application!, alias: target.alias }];
+    }
+    if (!acceptWrites && db.get('SELECT request_id FROM daemon_provider_writes WHERE request_id=?1', r.request_id)) return [];
+    const write = privateWrite(r.request_id, d.networkId, d.daemonNodeId);
+    return [write ? { ...r, operation: 'put', ...write } : { ...r, scan_targets: providerScanTargets(d.networkId, d.daemonNodeId) }];
+  }) }; } catch { return denied('provider_write_unavailable'); }
+}
+export function ackProviderSnapshot(d: Daemon, requestId: string, snapshot?: unknown, failed = false, appliedRevision?: number, application?: unknown, login?: unknown) {
+  if (!d.ok || !daemonExists(d.networkId, d.daemonNodeId)) return denied("caller_not_a_daemon");
+  expire(d.networkId, d.daemonNodeId);
+  const row = db.get<Row>(`SELECT * FROM daemon_provider_snapshots WHERE request_id=?1 AND network_id=?2 AND daemon_node_id=?3`, requestId, d.networkId, d.daemonNodeId);
+  if (!row) return denied("request_not_found");
+  // First accepted receipt wins; reconnect replay cannot rewrite prior evidence.
+  if (row.status !== "pending") return { ok: row.status === "succeeded" || row.status === "failed", status: row.status };
+  if (requestId.startsWith('dpl_')) {
+    if (snapshot !== undefined || application !== undefined || appliedRevision !== undefined || (failed && login !== undefined)) return denied('invalid_login_receipt');
+    const intentRow = db.get<{ intent_json: string }>('SELECT intent_json FROM daemon_provider_logins WHERE request_id=?1', requestId);
+    const intent = intentRow && JSON.parse(intentRow.intent_json);
+    if (!failed && (!validLoginIntent(intent) || !validLoginReceipt(login, intent, d.networkId, d.daemonNodeId))) return denied('invalid_login_receipt');
+    db.run(`UPDATE daemon_provider_snapshots SET status=?1,snapshot_json=?2,error=?3,observed_at=?4
+      WHERE request_id=?5 AND status='pending'`, [failed ? 'failed' : 'succeeded', failed ? null : JSON.stringify(login),
+      failed ? 'provider_login_unavailable' : null, Date.now(), requestId]);
+    db.run('DELETE FROM daemon_provider_logins WHERE request_id=?1', [requestId]);
+    return { ok: true, status: failed ? 'failed' : 'succeeded' };
+  }
+  if (login !== undefined) return denied('invalid_login_receipt');
+  if (requestId.startsWith('dpa_')) {
+    if (snapshot !== undefined || appliedRevision !== undefined || (failed && application !== undefined)) return denied('invalid_application_receipt');
+    if (!failed) {
+      try {
+        const intent = applicationIntent(requestId);
+        if (!intent || !boundApplicationTarget(d.networkId, d.daemonNodeId, intent.selection)
+          || !validProviderApplicationReceipt(application, requestId, intent.expected_revision, intent.selection)
+          || (application as any).runtime_provider !== (intent.selection.account_id ? 'openai' : `anet_${createHash('sha256').update(JSON.stringify([intent.selection.provider_id, intent.selection.auth_id])).digest('hex').slice(0, 20)}`)
+          || (application as any).applied_at < row.created_at - 30_000) return denied('invalid_application_receipt');
+      } catch { return denied('invalid_application_receipt'); }
+    }
+    db.run(`UPDATE daemon_provider_snapshots SET status=?1,snapshot_json=?2,error=?3,observed_at=?4
+      WHERE request_id=?5 AND status='pending'`, [failed ? 'failed' : 'succeeded', failed ? null : JSON.stringify(application),
+      failed ? 'provider_application_unavailable' : null, Date.now(), requestId]);
+    db.run('DELETE FROM daemon_provider_applications WHERE request_id=?1', [requestId]);
+    return { ok: true, status: failed ? 'failed' : 'succeeded' };
+  }
+  if (application !== undefined) return denied('invalid_application_receipt');
+  let safe: unknown = null;
+  if (failed && snapshot !== undefined) return denied("invalid_provider_snapshot");
+  if (!failed) {
+    try { safe = validateDaemonProviderSnapshot(snapshot, d.networkId, d.daemonNodeId); }
+    catch { return denied("invalid_provider_snapshot"); }
+    if ((safe as any).codex_inventory) {
+      try {
+        const targets = new Map(providerScanTargets(d.networkId, d.daemonNodeId).map(n => [n.node_id, n.alias]));
+        const rows = (safe as any).codex_inventory.rows;
+        if (rows.length !== targets.size || rows.some((r: any) => targets.get(r.node_id) !== r.alias)) return denied('invalid_provider_snapshot');
+      } catch { return denied('invalid_provider_snapshot'); }
+    }
+    try {
+      const write = privateWrite(requestId, d.networkId, d.daemonNodeId);
+      if (write) {
+        const actual = safe as any;
+        if (appliedRevision !== write.expected_revision + 1 || actual.revision !== appliedRevision) return denied('provider_write_unconfirmed');
+        const expected = validateWrite(write.provider, d.networkId, d.daemonNodeId);
+        const saved = actual.providers.find((p: any) => p.id === expected.id);
+        // CLI canonicalizes label and endpoint. No credential is compared or returned here.
+        expected.label = expected.label.trim();
+        for (const r of expected.runtimes) for (const a of r.auth) if (a.baseUrl) a.baseUrl = new URL(a.baseUrl).toString().replace(/\/$/, '');
+        if (!isDeepStrictEqual(saved, expected)) return denied('provider_write_unconfirmed');
+      }
+    } catch { return denied('provider_write_unconfirmed'); }
+  }
+  db.run(`UPDATE daemon_provider_snapshots SET status=?1, snapshot_json=?2, error=?3, observed_at=?4
+    WHERE request_id=?5 AND status='pending'`, [failed ? "failed" : "succeeded", safe ? JSON.stringify(safe) : null,
+    failed ? "provider_snapshot_unavailable" : null, Date.now(), requestId]);
+  const accepted = db.get<Row>("SELECT * FROM daemon_provider_snapshots WHERE request_id=?1", requestId);
+  db.run('DELETE FROM daemon_provider_writes WHERE request_id=?1', [requestId]);
+  return { ok: true, status: accepted!.status };
+}

package/src/daemon-token-owner-http.test.ts

@@ -215,7 +215,9 @@ test("all production token issuers explicitly mark the rollout epoch", () => {
       expect(match[1]).toContain("node_identity_epoch"); count++;
     }
   }
-  expect(count).toBe(9);
+  // Hub #938: clone_node mints a child ntok_ with node_identity_epoch=2,
+  // the same column create_node already writes. 9 issuers → 10.
+  expect(count).toBe(10);
   expect(readFileSync(`${root}/agent-network/bin/cli.ts`, "utf8")).toContain("'admin-reset', 'user', 1)");
 });
 

package/src/db.ts

@@ -320,6 +320,15 @@ db.exec(`
   CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
 `);
 
+// Human profile avatar. Additive for existing databases; old binaries ignore it.
+try {
+  db.exec("ALTER TABLE users ADD COLUMN avatar_url TEXT");
+} catch (e: any) {
+  // Both supported adapters report a duplicate column on the next startup.
+  // Do not send SQLite PRAGMA to PostgreSQL or swallow other migration errors.
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+
 // #261 P0-2 (2026-06-28): must_change_password flag. Added via ALTER
 // (not in the CREATE block above) so it's a no-op on fresh DBs that
 // already get the column via the CREATE path's full definition AND a
@@ -519,6 +528,33 @@ try {
 }
 
 // `node_config_updates` — pending + history. One row per dashboard write.
+// #906: redacted daemon-owned inventory requests, never credential material.
+db.exec(`CREATE TABLE IF NOT EXISTS daemon_provider_snapshots (
+  request_id TEXT PRIMARY KEY, network_id TEXT NOT NULL, daemon_node_id TEXT NOT NULL,
+  requested_by TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'pending',
+  created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, observed_at INTEGER,
+  snapshot_json TEXT, error TEXT
+)`);
+db.exec(`CREATE INDEX IF NOT EXISTS idx_daemon_provider_pending
+  ON daemon_provider_snapshots(network_id, daemon_node_id, status)`);
+db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS uniq_daemon_provider_inflight
+  ON daemon_provider_snapshots(network_id, daemon_node_id) WHERE status='pending'`);
+// One encrypted mutation payload per request; public receipt remains secret-free.
+db.exec(`CREATE TABLE IF NOT EXISTS daemon_provider_writes (
+  request_id TEXT PRIMARY KEY, expected_revision INTEGER NOT NULL,
+  ciphertext BLOB NOT NULL, iv BLOB NOT NULL, tag BLOB NOT NULL
+)`);
+// Application intent is credential-free; secrets stay in the daemon's store.
+db.exec(`CREATE TABLE IF NOT EXISTS daemon_provider_applications (
+  request_id TEXT PRIMARY KEY, expected_revision INTEGER NOT NULL,
+  selection_json TEXT NOT NULL
+)`);
+
+// Login commands contain only intent. OAuth tokens never enter Hub storage.
+db.exec(`CREATE TABLE IF NOT EXISTS daemon_provider_logins (
+  request_id TEXT PRIMARY KEY, intent_json TEXT NOT NULL
+)`);
+
 // 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).
 //
@@ -779,6 +815,15 @@ try {
   if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
 }
 
+// Hub #938 — clone_node reuses this table (same token mint, sweeper, and
+// register finalize) but must not be replayed as a blank create_node.
+// NULL/empty = ordinary create. Non-empty JSON = clone directives.
+try {
+  db.exec(`ALTER TABLE node_create_requests ADD COLUMN clone_json TEXT`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+
 // #1493 — 把 user_inbox.network_id 升到 **schema 级 NOT NULL**(belt-and-suspenders,
 // 叠在 send_desktop_message 的代码级三闸之上:canWrite / `!effectiveNetId` return /
 // getUserNetworkRole,tools.ts)。「不产生 network_id=NULL 孤儿」现是代码级保证 + #1492

package/src/mcp-context-cost-http.test.ts

@@ -26,7 +26,9 @@ if (!activeDbPath) throw new Error("mcp-context-cost requires COMMHUB_DB (or COM
  * 加工具或加说明超过它,就在这里改数字并在 PR 里说为什么。
  */
 // Board #625: two human adoption tools; measured 58 tools / 56,615 B.
-const TOOLS_LIST_MAX_BYTES = 57_500;
+// Hub #938 clone_node is audience both, so this user-token list grows.
+// Measured with #906's tools plus clone_node: 60 tools / 58,169 B. Ceiling keeps ~431 B.
+const TOOLS_LIST_MAX_BYTES = 58_600;
 /** 单个工具(名字 + 描述 + 输入 schema)的上限;最大的是 report_status(节点心跳,~8.4 KB 的遥测结构)。 */
 const TOOL_MAX_BYTES = 9_000;
 /** 单条工具描述的上限(说明写进参数的 describe,或者拆短)。 */

package/src/member-presence-http.test.ts

@@ -3,7 +3,7 @@
 // GET /api/networks/:id/humans 给每个人加 online / last_seen_at(判据 = 此刻有没有活着的用户流
 // /events/users/me);用户流上推 member_presence。两个方向都测:
 //   看得到:普通成员、受限成员、viewer;连上 → online=true,断开 → online=false + last_seen_at。
-//   看不到:非成员 403;节点令牌拿到的仍是原来三个身份字段;别的网络的人收不到推送;自己收不到自己的。
+//   看不到:非成员 403;节点令牌只拿身份字段(含头像),无在线状态;别的网络的人收不到推送;自己收不到自己的。
 
 import { describe, expect, test, beforeAll, afterAll } from "bun:test";
 import { mkdtempSync, rmSync } from "fs";
@@ -125,7 +125,8 @@ describe("GET /api/networks/:id/humans — online / last_seen_at", () => {
   test("never connected since hub start → online=false, last_seen_at=null (unknown, not 'long ago')", async () => {
     const r = await get(users.pres_alpha.token, `/api/networks/${NET}/humans`);
     expect(r.status).toBe(200);
-    expect(Object.keys(r.body.humans[0]).sort()).toEqual(["display_name", "last_seen_at", "online", "user_id", "username"]);
+    expect(Object.keys(r.body.humans[0]).sort()).toEqual(["avatar_url", "display_name", "last_seen_at", "online", "user_id", "username"]);
+    expect(r.body.humans.every((h: any) => h.avatar_url === null)).toBe(true);
     const beta = r.body.humans.find((h: any) => h.user_id === users.pres_beta.userId);
     expect(beta.online).toBe(false);
     expect(beta.last_seen_at).toBeNull();
@@ -181,11 +182,14 @@ describe("who must NOT see presence", () => {
     expect(r.body.humans).toBeUndefined();
   });
 
-  test("node token → same three identity fields as before, no online / last_seen_at", async () => {
+  test("node token → identity fields including avatar, no online / last_seen_at", async () => {
     const beta = await openUserStream(users.pres_beta.token, NET);
     const r = await get(nodeToken, `/api/networks/${NET}/humans`);
     expect(r.status).toBe(200);
-    for (const h of r.body.humans) expect(Object.keys(h).sort()).toEqual(["display_name", "user_id", "username"]);
+    for (const h of r.body.humans) {
+      expect(Object.keys(h).sort()).toEqual(["avatar_url", "display_name", "user_id", "username"]);
+      expect(h.avatar_url).toBeNull();
+    }
     // 节点令牌也不能订阅用户流(既有行为,这里钉住:不能借它收 member_presence)。
     expect((await fetch(`${BASE}/events/users/me?network_id=${NET}`, { headers: auth(nodeToken) })).status).toBe(403);
     beta.close();

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

@@ -60,8 +60,20 @@ test("public errors redact free text for granted viewers on every projection", a
       "bin: ENOENT: /private/fixture/bin/anet on fixture-host",
       "adopt_unknown_secret", "adopt_start_timeout: /private/fixture", "", "adopt_start_timeout", null,
       "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed",
+      "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",
+      "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",
     ]) {
-      const expected = error === null || ["adopt_start_timeout", "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed"].includes(error) ? error : "lifecycle_error";
+      const publicCodes = ["adopt_start_timeout", "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed", "opencode_tui_session_mismatch",
+        "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",
+        "adopt_codex_session_conflict", "adopt_codex_port_unavailable", "adopt_codex_stage_still_running",
+        "adopt_codex_identity_unproven"];
+      const expected = error === null || publicCodes.includes(error) ? error : "lifecycle_error";
       for (const [kind, table, request] of [
         ["adopt", "node_daemon_bindings", "adopt_read_active"],
         ["start", "node_start_requests", "start_read_failed"],

package/src/node-lifecycle-read.ts

@@ -7,6 +7,11 @@ const publicLifecycleErrors = new Set([
   "codex_fork_confirmation_invalid", "codex_fork_recovery_unsupported", "codex_fork_cli_unsupported",
   "codex_fork_result_invalid", "codex_fork_outcome_unknown",
   "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed",
+  "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",
+  "adopt_codex_session_conflict", "adopt_codex_port_unavailable", "adopt_codex_stage_still_running",
+  "adopt_codex_identity_unproven",
   "adopt_active_binding_required", "adopt_binding_unavailable",
   "adopt_binding_revoked_during_start", "adopt_explicit_private_socket_required",
   "adopt_start_evidence_missing", "adopt_stop_evidence_missing",
@@ -27,6 +32,7 @@ const publicLifecycleErrors = new Set([
   "adopt_tmux_socket_mismatch", "adopt_pane_invalid", "adopt_pane_unverified",
   "adopt_pane_process_mismatch", "adopt_socket_directory_unsafe", "adopt_socket_unsafe",
   "adopt_pid_changed", "adopt_pid_invalid", "adopt_pidfile_unsafe",
+  "opencode_tui_session_mismatch",
   "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-permissions.ts

@@ -246,6 +246,8 @@ export function streamVerdict(id: NodeIdentity, target: AgentRef | "network"): V
 // ── MCP:每个工具归一类(test 钉住「每个注册的工具都归了类」,新工具忘了归类会红) ──
 export type ToolClass = "always" | "read" | "dispatch" | "broadcast" | "requirements" | "schedule" | "node_write" | "human_only";
 export const NODE_TOOL_CLASS: Readonly<Record<string, ToolClass>> = {
+  daemon_provider_snapshot: "human_only",
+  pull_daemon_provider_snapshots: "always", ack_daemon_provider_snapshot: "always",
   // 回复 / 上报 / 自己的收件箱 / 生命周期协议(节点自己的请求)—— 任何模式都能做
   report_status: "always", report_completion: "always", get_inbox: "always", ack_inbox: "always",
   mark_tasks_runtime_submitted: "always", mark_tasks_consumed: "always", send_reply: "always", send_peer_reply: "always", send_ack: "always",
@@ -273,7 +275,7 @@ export const NODE_TOOL_CLASS: Readonly<Record<string, ToolClass>> = {
   schedule_create: "schedule", schedule_update: "schedule", schedule_cancel: "schedule", schedule_run_now: "schedule",
   schedule_batch_interval: "schedule",
   // 写节点 / 技能 / 探测:只读、受限不行;正常由 RFC-036 等既有规则管
-  update_node_config: "node_write", write_node_rules_file: "node_write", restart_node: "node_write", create_node: "node_write",
+  update_node_config: "node_write", write_node_rules_file: "node_write", restart_node: "node_write", create_node: "node_write", clone_node: "node_write",
   stop_node: "node_write", delete_node: "node_write", start_node: "node_write", submit_skill: "node_write", probe_provider_model: "node_write",
   // 只有人能做
   upsert_network_secret: "human_only", upsert_provider: "human_only", update_provider: "human_only",

package/src/report-status-host-schema.test.ts

@@ -149,6 +149,30 @@ describe("#1545 create_capability_observed_ms_ago —— schema 必须收得宽"
  * 注释会烂。这组测试的作用**不是禁止改 strict**(两种都各有其位),而是:谁改了,
  * 谁就会在这里撞红,从而**被迫连注释一起改**。所以断言写成「和注释里那张表一致」,
  * 而不是「必须是某个值」。 */
+describe("adoption_candidates ingest does not reject the heartbeat or keep secrets", () => {
+  const caps = () => schemas.report_status.config_snapshot;
+  const base = { flags: {}, config_update_capable: false, peer_reply_inbox_capable: true };
+
+  test("a clean row is kept, a bad sibling is dropped, and token keys are stripped", () => {
+    const parsed = caps().parse({ ...base, daemon_capabilities: { adopt_capable: true, adoption_candidates: [
+      { node_id: "n_ok", alias: "演示", workdir: "/tmp/proj", runtime: "claude-agent-sdk", launch_hint: "stopped", token: "ntok_supersecret" },
+      { node_id: "n_bad", alias: "x", workdir: "relative", launch_hint: "stopped" },
+      { node_id: "n_hint", alias: "y", workdir: "/tmp/y", launch_hint: "nope" },
+    ] } });
+    expect(parsed.daemon_capabilities.adoption_candidates.filter(Boolean)).toEqual([
+      { node_id: "n_ok", alias: "演示", workdir: "/tmp/proj", runtime: "claude-agent-sdk", launch_hint: "stopped" },
+    ]);
+    expect(JSON.stringify(parsed)).not.toContain("ntok_supersecret");
+  });
+
+  test("a non-array does not reject report_status and does not keep the payload", () => {
+    const parsed = caps().parse({ ...base, daemon_capabilities: { adopt_capable: true, adoption_candidates: { token: "ntok_supersecret" } } });
+    expect(parsed.daemon_capabilities.adoption_candidates).toBeUndefined();
+    expect(JSON.stringify(parsed)).not.toContain("ntok_supersecret");
+    expect(parsed.daemon_capabilities.adopt_capable).toBe(true);
+  });
+});
+
 describe("#1545 report_status 子对象的 strict 分布(注释里那张表的可执行副本)", () => {
   const rs = () => schemas.report_status;
   const UNKNOWN = { __hub_does_not_know_this_key__: 1 };

package/src/runtime-readiness.ts

@@ -40,6 +40,9 @@ export interface RuntimeReadinessOut {
   auth?: string;
   network?: string;
   shared_login_count?: number;
+  /** Copied only for runtime key `opencode-cli`. */
+  generation?: "v1" | "v2";
+  accepted?: boolean;
 }
 
 const ENUMS: Record<string, readonly string[]> = {
@@ -76,6 +79,10 @@ export function sanitizeRuntimeReadiness(raw: unknown): Record<string, RuntimeRe
         && e.shared_login_count >= 0 && e.shared_login_count <= 100_000) {
       entry.shared_login_count = e.shared_login_count;
     }
+    if (rt === "opencode-cli" && (e.generation === "v1" || e.generation === "v2")) {
+      entry.generation = e.generation;
+      if (typeof e.accepted === "boolean") entry.accepted = e.accepted;
+    }
     out[rt] = entry;
     n++;
   }

package/src/server.ts

@@ -32,6 +32,7 @@ import { expireStaleOpenTasks } from "./task-stale-open.js";
 import { flagOrphanTasks } from "./task-orphan.js";
 import { addAgentNetworkScope, addHumanNetworkScope, addNetworkScope, addOwnTrafficScope, addAgentTimelineScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { lifecycleProjections, lifecycleRequestResponse } from "./node-lifecycle-read.js";
+import { listAdoptionCandidates, snapshotReportsAdoptionDiscovery } from "./adoption-candidates.js";
 import { restrictedMemberSeesFile, restrictedMemberAttachmentsDenied } from "./restricted-files.js";
 import { dmParticipantSeesFile, listDmThread, listDmThreads, sendHumanDm } from "./human-dm.js";
 import { groupMemberSeesFile, groupUnreadFor, listGroupMessages, listGroupThreads, markGroupRead, memberGroup, sendGroupMessage } from "./group-messages.js";
@@ -1455,6 +1456,30 @@ return Bun.serve({
       return withCors(req, Response.json({ ok: true, user: resolved.user, networks, current_network: resolved.networkId, credential }));
     }
 
+    // Separate route: older Hubs must return unsupported, not silently ignore
+    // avatar_url in their existing profile PUT and pretend that it was saved.
+    if (url.pathname === "/api/auth/me/avatar" && req.method === "PUT") {
+      const token = req.headers.get("Authorization")?.replace("Bearer ", "");
+      if (!token) return withCors(req, Response.json({ ok: false, error: "token required" }, { status: 401 }));
+      const resolved = resolveToken(token);
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
+      if (isNodeCredential(resolved)) return userTokenRequired(req);
+      let body: unknown;
+      try { body = await req.json(); } catch {
+        return withCors(req, Response.json({ ok: false, error: "invalid_json" }, { status: 400 }));
+      }
+      if (!body || typeof body !== "object" || Array.isArray(body)
+          || !Object.hasOwn(body, "avatar_url")
+          || Object.keys(body).some((key) => key !== "avatar_url")) {
+        return withCors(req, Response.json({ ok: false, error: "invalid_avatar_body", reason: "expected only avatar_url (string or null)" }, { status: 400 }));
+      }
+      const avatar = validateAvatarUrl((body as { avatar_url: unknown }).avatar_url);
+      if (!avatar.ok) return withCors(req, Response.json({ ok: false, error: "invalid_avatar_url", reason: avatar.reason }, { status: 400 }));
+      // No supplied target ID/alias; user identity comes exclusively from auth.
+      db.run("UPDATE users SET avatar_url = ?1, updated_at = datetime('now') WHERE user_id = ?2", [avatar.value, resolved.user.user_id]);
+      return withCors(req, Response.json({ ok: true, user_id: resolved.user.user_id, avatar_url: avatar.value }));
+    }
+
     if (url.pathname === "/api/auth/me" && req.method === "PUT") {
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "token required" }, { status: 401 }));
@@ -1473,7 +1498,7 @@ return Bun.serve({
           db.run(`UPDATE users SET ${updates.join(", ")} WHERE user_id = ?${params.length}`, params);
         }
         // Re-fetch
-        const user = db.get<any>("SELECT user_id, username, display_name, email, role FROM users WHERE user_id = ?1", resolved.user.user_id);
+        const user = db.get<any>("SELECT user_id, username, display_name, avatar_url, email, role FROM users WHERE user_id = ?1", resolved.user.user_id);
         return withCors(req, Response.json({ ok: true, user }));
       } catch (e: any) {
         return withCors(req, Response.json({ ok: false, error: e.message }, { status: 400 }));
@@ -2567,6 +2592,11 @@ return Bun.serve({
       if (!lifecycleUser) return withCors(req, Response.json({ ok: false, error: "user_token_required" }, { status: 403 }));
       return withCors(req, lifecycleRequestResponse(url, restScope));
     }
+    // Board #654: read-only hand-started adoption candidates. Not a binding.
+    if (url.pathname === "/api/adoption-candidates" && req.method === "GET") {
+      if (!lifecycleUser || !restAuth?.userId) return withCors(req, Response.json({ ok: false, error: "user_token_required" }, { status: 403 }));
+      return withCors(req, Response.json(listAdoptionCandidates(restScope, { userId: restAuth.userId, isAdmin })));
+    }
 
     const sideActor = resolveSideThreadActor(req, resolveRequestAuth(req, { allowQueryToken: false }), isAdmin);
     const nodeCommandActor = sideActor?.kind === "node" && sideActor.boundNodeId && sideActor.boundNetworkId
@@ -4589,6 +4619,7 @@ return Bun.serve({
           // upgraded past preview.55.
           let snapCanCreate: boolean | undefined;
           let snapAdoptCapable: boolean | undefined;
+          let snapAdoptionDiscovery = false;
           let snapBlockedReason: string | undefined;
           // #1545 —— 见 report_status schema 里 create_capability_observed_ms_ago 的注释:
           // 上报侧**故意收得宽**(无 int/min/max,免得一个诊断字段能让整份 report 被拒),
@@ -4603,6 +4634,7 @@ return Bun.serve({
               snapRole = typeof parsed?.role === "string" ? parsed.role : null;
               const caps = parsed?.daemon_capabilities;
               if (typeof caps?.adopt_capable === "boolean") snapAdoptCapable = caps.adopt_capable;
+              if (snapshotReportsAdoptionDiscovery(parsed)) snapAdoptionDiscovery = true;
               if (caps && typeof caps.can_create_nodes === "boolean") {
                 snapCanCreate = caps.can_create_nodes;
               }
@@ -4620,10 +4652,11 @@ return Bun.serve({
             } catch { /* malformed */ }
           }
           return { row: r, role: snapRole, canCreate: snapCanCreate, blockedReason: snapBlockedReason,
-            observedMsAgo: snapObservedMsAgo, readiness: snapReadiness, adoptCapable: snapAdoptCapable };
+            observedMsAgo: snapObservedMsAgo, readiness: snapReadiness, adoptCapable: snapAdoptCapable,
+            adoptionDiscovery: snapAdoptionDiscovery };
         })
         .filter(({ role }) => role === "host_supervisor")
-        .map(({ row: r, canCreate, blockedReason, observedMsAgo, readiness, adoptCapable }) => {
+        .map(({ row: r, canCreate, blockedReason, observedMsAgo, readiness, adoptCapable, adoptionDiscovery }) => {
           let online = false;
           let lastSeenAt: string | null = null;
           if (r.session_last_seen) {
@@ -4667,7 +4700,10 @@ return Bun.serve({
             // Do not reveal even the new capability for a node the user cannot read.
             const visibleParams: any[] = [r.node_id];
             const visibleSql = addAgentNetworkScope("SELECT node_id FROM nodes WHERE node_id=?1", visibleParams, restScope, { alias: "alias", nodeId: "node_id" });
-            if (db.get(visibleSql, ...visibleParams)) out.adopt_capable = adoptCapable;
+            if (db.get(visibleSql, ...visibleParams)) {
+              out.adopt_capable = adoptCapable;
+              if (adoptionDiscovery) out.adoption_discovery = true;
+            }
           }
           // #1353 Fix ② — only emit the two capability keys when the
           // daemon actually reported them. Undefined vs. false is a