@sleep2agi/commhub-server 0.8.8 → 0.9.0-preview.1

package/src/db.ts

@@ -117,12 +117,43 @@ db.exec(`
     created_at              TEXT NOT NULL DEFAULT (datetime('now'))
   );
 
-  CREATE INDEX IF NOT EXISTS idx_agent_telemetry_host_time
-    ON agent_telemetry(network_id, hostname, ip, created_at);
   CREATE INDEX IF NOT EXISTS idx_agent_telemetry_alias_time
     ON agent_telemetry(network_id, alias, created_at);
 `);
 
+// Round-2/4 review ② — server-health index split.
+//
+// The /api/server-health/:host query (index.ts) filters
+//   WHERE (hostname = ?1 OR ip = ?2) AND created_at >= ?3
+// The old combined index (network_id, hostname, ip, created_at) only
+// covers an equality on hostname AND ip (not OR), so SQLite couldn't
+// use it for the disjunction and fell back to a full scan of
+// agent_telemetry on every server-health page load. At a 30s heartbeat
+// × N agents, the table grows fast and the scan dominates.
+//
+// Split into two narrow indexes so SQLite's OR optimizer can run an
+// index UNION on (hostname-path ∪ ip-path), each path covered by an
+// index that also lets the created_at range be range-scanned.
+//
+// **Honest trade-off** (corrected after reviewer flag): secondary
+// index count goes from 2 (host_time + alias_time) to 3 (hostname_time
+// + ip_time + alias_time). Every agent_telemetry insert now maintains
+// ONE MORE B-tree, so per-insert write-amp is +50%. The trade-off is
+// deliberate: write-amp is bounded by the heartbeat cadence (30s ×
+// N agents) and is small in absolute terms, while the read-path win
+// is going from O(n) full-scan-per-dashboard-poll to O(log n) two-
+// branch index union. For the public-facing hub's expected load
+// shape (many readers, few writers), that's a clear net gain.
+try { db.exec("DROP INDEX IF EXISTS idx_agent_telemetry_host_time"); } catch {}
+try {
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_agent_telemetry_hostname_time
+           ON agent_telemetry(network_id, hostname, created_at)`);
+} catch {}
+try {
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_agent_telemetry_ip_time
+           ON agent_telemetry(network_id, ip, created_at)`);
+} catch {}
+
 // inbox: add in_reply_to, requires_response, expires_at, scope, node identity
 for (const col of [
   { name: "in_reply_to", def: "TEXT" },
@@ -231,6 +262,86 @@ db.exec(`
   CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
 `);
 
+// #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
+// pure additive migration on existing prod DBs — column defaults 0
+// for every existing row, so old `admin/anethub` deployments are NOT
+// locked or nudged on upgrade (back-compat per 通信龙 spec). Wrapped
+// in try/catch because SQLite throws "duplicate column" if the column
+// already exists on subsequent restarts (no IF NOT EXISTS syntax for
+// ALTER ADD COLUMN until SQLite 3.35+, can't assume that everywhere).
+try {
+  db.exec(`ALTER TABLE users ADD COLUMN must_change_password INTEGER DEFAULT 0`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+
+// RFC-024 (2026-06-28): node config-apply foundation.
+//
+// `nodes` table gains two columns:
+//   - `config_revision`: monotonically-incrementing per-node revision
+//     that gates write conflicts (dashboard sends base_revision, hub
+//     rejects 409 if it doesn't match current). Promoted by hub when
+//     the node ACKs `applied` from a successful apply.
+//   - `config_snapshot`: masked JSON of the node's current effective
+//     config, posted by the node via report_status. Dashboard reads
+//     this for the GET snapshot path (never touches per-node files).
+//
+// Both ALTERs wrapped in try/catch for the same reason as
+// must_change_password above (no IF NOT EXISTS on SQLite < 3.35).
+try {
+  db.exec(`ALTER TABLE nodes ADD COLUMN config_revision INTEGER DEFAULT 0`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+try {
+  db.exec(`ALTER TABLE nodes ADD COLUMN config_snapshot 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).
+//
+// network_id is denormalized from nodes(network_id) at insert time so
+// queries don't need to JOIN through nodes every time + so a node
+// deletion doesn't orphan the history (audit retention).
+db.exec(`
+  CREATE TABLE IF NOT EXISTS node_config_updates (
+    update_id        TEXT PRIMARY KEY,
+    node_id          TEXT NOT NULL,
+    network_id       TEXT NOT NULL,
+    patch_json       TEXT NOT NULL,
+    apply_mode       TEXT NOT NULL,
+    base_revision    INTEGER NOT NULL,
+    status           TEXT NOT NULL,
+    error            TEXT,
+    created_at       INTEGER NOT NULL,
+    created_by_token TEXT NOT NULL,
+    acked_at         INTEGER,
+    new_revision     INTEGER
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_ncu_node_status ON node_config_updates(node_id, status);
+  CREATE INDEX IF NOT EXISTS idx_ncu_network ON node_config_updates(network_id);
+`);
+
+// F-C (CHANGE_REQ): partial unique index on non-terminal rows. The
+// single-flight check in tools.ts is an app-level check-then-INSERT —
+// safe under single-process Bun, but two hub workers could race and
+// double-insert. This index makes that race impossible at the DB
+// layer regardless of process count. Wrapped in try/catch because
+// SQLite < 3.8.0 doesn't support partial indexes (rare on modern
+// systems; if missing, app-level check is the fallback).
+try {
+  db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS uniq_ncu_node_inflight ON node_config_updates(node_id) WHERE status IN ('pending', 'restarting')`);
+} catch (e: any) {
+  // Older SQLite — fall back to app-level single-flight only.
+  console.warn(`[commhub] partial unique index uniq_ncu_node_inflight skipped: ${e?.message || e}`);
+}
+
 // ── V3: networks table ──
 db.exec(`
   CREATE TABLE IF NOT EXISTS networks (
@@ -692,8 +803,179 @@ export function generateId(prefix: string): string {
   return `${prefix}_${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`;
 }
 
-export function hashPassword(password: string): string {
-  return new Bun.CryptoHasher("sha256").update(`anet:${password}`).digest("hex");
+// ──────────────────────────────────────────────────────────────────
+// Round-6 A1 — Password hashing: salted scrypt with lazy migration
+//
+// Format: `scrypt$<N>$<salt-b64>$<hash-b64>`
+//   N        = log2(cost). E.g. 14 → 2^14 = 16384 (~50ms on modern hw).
+//   salt-b64 = base64 of 16 random bytes.
+//   hash-b64 = base64 of 64-byte scrypt output.
+//
+// Why scrypt: Node built-in crypto.scryptSync — zero new deps.
+//   Memory-hard, ASIC-resistant. Better than bcrypt under modern GPU
+//   attack. argon2id would be marginally better but pulls a native
+//   dep (argon2 npm package) we don't want on the hub.
+//
+// Why "$" delimiter: legacy hashes are bare hex (0-9a-f only). Any
+//   "$" in stored hash means new format. Trivial detect with zero
+//   false-positives.
+//
+// Lazy migration:
+//   - register/bootstrap/changePassword/resetUserPassword always
+//     write the new format.
+//   - login + changePassword (old-verify) accept BOTH formats.
+//   - on successful login against a legacy hash, the caller rehashes
+//     in place. Zero downtime, no forced password change.
+//
+// See feedback_assume_unit_before_threshold.md: explicit-set
+// crypto parameters; don't rely on library defaults.
+// ──────────────────────────────────────────────────────────────────
+
+import { scryptSync, randomBytes, timingSafeEqual } from "node:crypto";
+
+// Default cost parameter (N = 2^14 = 16384). Tunable via env for
+// test suites that don't want to spend ~50ms per scrypt call.
+//   N=10 → 2^10 = 1024 iter, ~5ms (test-only)
+//   N=14 → 2^14 = 16384 iter, ~50ms (production)
+//   N=15 → 2^15 = 32768 iter, ~100ms (if hw improves and ops want headroom)
+const DEFAULT_SCRYPT_N = 14;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SCRYPT_KEYLEN = 64;
+const SCRYPT_SALT_BYTES = 16;
+// Bun's scrypt defaults maxmem to ~32 MiB which is too tight for
+// N ≥ 14 (128 * r * 2^N = ~16 MiB at r=8, N=14; default has no
+// headroom for the internal buffers). Set explicitly so a higher-N
+// upgrade later doesn't suddenly throw at runtime.
+const SCRYPT_MAXMEM = 128 * 1024 * 1024; // 128 MiB
+
+function getScryptN(): number {
+  const raw = process.env.COMMHUB_SCRYPT_N;
+  if (!raw) return DEFAULT_SCRYPT_N;
+  const n = parseInt(raw, 10);
+  // Bound: 8 (way-too-weak, only for unit tests) — 20 (DoS risk).
+  if (!Number.isFinite(n) || n < 8 || n > 20) return DEFAULT_SCRYPT_N;
+  return n;
+}
+
+export function hashPassword(plain: string): string {
+  const N = getScryptN();
+  const salt = randomBytes(SCRYPT_SALT_BYTES);
+  const hash = scryptSync(plain, salt, SCRYPT_KEYLEN, {
+    N: 1 << N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    maxmem: SCRYPT_MAXMEM,
+  });
+  return `scrypt$${N}$${salt.toString("base64")}$${hash.toString("base64")}`;
+}
+
+/**
+ * Verify a plaintext password against the stored hash. Accepts BOTH
+ * the new scrypt format and the legacy bare-hex SHA-256 format
+ * (back-compat for pre-A1 deployments).
+ *
+ * Returns:
+ *   ok           — true iff the password matches.
+ *   needsRehash  — true iff the stored hash was legacy format AND the
+ *                  password matched. The caller MUST rehash and write
+ *                  the new format back to disk so the legacy hash
+ *                  stops existing. Returned false for already-new
+ *                  hashes (no rehash needed even on N upgrade —
+ *                  follow-up if/when we bump default N).
+ */
+export function verifyPassword(plain: string, stored: string): { ok: boolean; needsRehash: boolean } {
+  // Format detection: new format always contains "$". Legacy bare
+  // sha256 hex never does (0-9a-f only).
+  if (stored.includes("$")) {
+    const parts = stored.split("$");
+    if (parts.length !== 4 || parts[0] !== "scrypt") {
+      // Unknown new-style scheme — be conservative, reject.
+      return { ok: false, needsRehash: false };
+    }
+    const N = parseInt(parts[1], 10);
+    if (!Number.isFinite(N) || N < 8 || N > 20) return { ok: false, needsRehash: false };
+    let saltBuf: Buffer;
+    let expectedBuf: Buffer;
+    try {
+      saltBuf = Buffer.from(parts[2], "base64");
+      expectedBuf = Buffer.from(parts[3], "base64");
+    } catch {
+      return { ok: false, needsRehash: false };
+    }
+    if (expectedBuf.length === 0) return { ok: false, needsRehash: false };
+    let actualBuf: Buffer;
+    try {
+      actualBuf = scryptSync(plain, saltBuf, expectedBuf.length, {
+        N: 1 << N,
+        r: SCRYPT_R,
+        p: SCRYPT_P,
+        maxmem: SCRYPT_MAXMEM,
+      });
+    } catch {
+      return { ok: false, needsRehash: false };
+    }
+    // timingSafeEqual requires equal-length buffers; we sized actual
+    // to expected.length above so this is safe.
+    const ok = timingSafeEqual(actualBuf, expectedBuf);
+    return { ok, needsRehash: false };
+  }
+
+  // Legacy bare-hex SHA-256 format (pre-A1).
+  const legacy = new Bun.CryptoHasher("sha256").update(`anet:${plain}`).digest("hex");
+  // Use timingSafeEqual on byte buffers (hex strings would be
+  // compared via JS === which is variable-time on first-differing
+  // char — the timing leak is tiny for fixed-format hex but pin the
+  // habit). Both are exactly 64 hex chars when sha256 produced.
+  if (stored.length !== legacy.length) {
+    // Length mismatch is itself indistinguishable from a parse miss
+    // — but we still pay the scrypt to keep this branch's timing
+    // peer to the verify branches below.
+    burnEqualTimeScrypt(plain);
+    return { ok: false, needsRehash: false };
+  }
+  let ok = false;
+  try {
+    ok = timingSafeEqual(Buffer.from(stored, "hex"), Buffer.from(legacy, "hex"));
+  } catch {
+    burnEqualTimeScrypt(plain);
+    return { ok: false, needsRehash: false };
+  }
+  // Timing-oracle close (round-6 round-2 — independent reviewer flag):
+  // legacy-OK   path callers (auth.ts:login) do `hashPassword(password)`
+  //             immediately after to rehash → one scrypt cost on top of
+  //             this function's return. ~50ms.
+  // legacy-WRONG path callers reject and return → ZERO additional cost.
+  //
+  // That asymmetry leaks "is this user on the legacy hash" via wall-
+  // clock difference (sub-ms wrong vs ~50ms ok). To close it, burn an
+  // equal-time scrypt on the wrong-password branch too. Now both
+  // legacy paths cost SHA-256 + one scrypt, matching new-format paths
+  // and the missing-user dummy-scrypt path.
+  if (!ok) {
+    burnEqualTimeScrypt(plain);
+  }
+  return { ok, needsRehash: ok };
+}
+
+// Round-6 round-2 hardening — throwaway scrypt to equalize timing on
+// failure paths. Burns the same wall-clock cost as a real
+// hashPassword() call. Result discarded; salt is a fresh random so
+// the work is real (not optimised away). Cost ~N=14 → 50ms,
+// COMMHUB_SCRYPT_N controlled like the real path.
+function burnEqualTimeScrypt(plain: string): void {
+  try {
+    const N = getScryptN();
+    scryptSync(plain, randomBytes(SCRYPT_SALT_BYTES), SCRYPT_KEYLEN, {
+      N: 1 << N,
+      r: SCRYPT_R,
+      p: SCRYPT_P,
+      maxmem: SCRYPT_MAXMEM,
+    });
+  } catch {
+    // Even on failure to scrypt (shouldn't happen), don't surface —
+    // this is a timing pacer, not a correctness path.
+  }
 }
 
 export function hashToken(token: string): string {
@@ -734,10 +1016,59 @@ export function logAudit(userId: string | null, username: string | null, action:
 // 'replied' if it's still open, and post an inbox notification to the parent's
 // originator (so an upstream agent or the dashboard sees the chained answer).
 // Recurse up the chain (in case of N hops).
-export function chainReplyToParent(childTaskId: string, replyText: string, replyStatus: "replied" | "failed" | "cancelled" = "replied", maxDepth = 5): void {
+/**
+ * Auto-chain a sub-task reply up to the parent task lineage.
+ *
+ * `callerNetId` (round5 F2 fix): the network the *caller* (send_reply
+ * / report_completion) is operating in. When supplied, the chain
+ * refuses to traverse into a parent whose `network_id` doesn't match —
+ * blocks cross-tenant write where network B replies to a task they've
+ * named as parent but which actually lives in network A.
+ *
+ * Callers that legitimately need the legacy network-blind behavior
+ * (e.g. server-internal bookkeeping that doesn't have a tenant
+ * context) can omit `callerNetId`, but every MCP tool path MUST
+ * supply it.
+ *
+ * Returns `{ chained, stoppedReason? }` so the caller can gate its
+ * follow-up SSE push on whether the chain actually wrote (round-2
+ * fix per #275 follow-up, 通信牛 catch): even when the WRITE was
+ * refused, callers were still running `SELECT parent.from_name;
+ * pushEvent(parent.from_name, { parent_task_id }, callerNetId)` —
+ * leaking the foreign parent's task_id into the caller's network
+ * via the SSE payload. Now the caller checks `result.chained` before
+ * pushing the chained_reply event.
+ */
+export type ChainReplyResult = {
+  /** True iff this call actually wrote into at least one parent row.
+   *  When false, callers MUST NOT push SSE events for parent
+   *  listeners — the chain would otherwise leak the foreign parent's
+   *  identifiers into the caller's network. */
+  chained: boolean;
+  /** Optional reason the chain stopped short. Today the only enforced
+   *  reason is `cross_network`; future reasons (max-depth, parent-
+   *  archived, etc.) can land here without breaking callers. */
+  stoppedReason?: "cross_network";
+};
+
+export function chainReplyToParent(
+  childTaskId: string,
+  replyText: string,
+  replyStatus: "replied" | "failed" | "cancelled" = "replied",
+  maxDepth = 5,
+  callerNetId?: string | null,
+): ChainReplyResult {
   let currentChildId: string | null = childTaskId;
   let currentReply = replyText;
   let depth = 0;
+  let chained = false;
+  // Normalize so undefined ("don't enforce") stays distinct from
+  // null ("explicit default network"). Caller passes undefined to
+  // opt out of the cross-tenant check; null to require the parent
+  // also live in the default (null) network.
+  const enforce = callerNetId !== undefined;
+  const callerNorm = callerNetId ?? null;
+
   while (currentChildId && depth < maxDepth) {
     depth++;
     type ChildRow = { parent_task_id: string | null; to_name: string; from_name: string; content: string };
@@ -746,12 +1077,24 @@ export function chainReplyToParent(childTaskId: string, replyText: string, reply
       "SELECT parent_task_id, to_name, from_name, content FROM tasks WHERE task_id = ?1",
       currentChildId
     );
-    if (!child?.parent_task_id) return;
+    if (!child?.parent_task_id) return { chained };
     const parent: ParentRow | null = db.get<ParentRow>(
       "SELECT task_id, from_name, to_name, status, result, network_id, parent_task_id FROM tasks WHERE task_id = ?1",
       child.parent_task_id
     );
-    if (!parent) return;
+    if (!parent) return { chained };
+
+    // round5 F2 fix: refuse to write into a parent that lives in a
+    // different network than the caller. Stops chain-reply being a
+    // cross-tenant write primitive. Logs once per attempt so ops can
+    // see the rejection in the access log.
+    if (enforce) {
+      const parentNet = parent.network_id ?? null;
+      if (parentNet !== callerNorm) {
+        console.log(`[commhub] 🚫 chainReplyToParent cross-network blocked: parent=${parent.task_id.slice(0, 8)} parent-net=${parentNet ?? "null"} caller-net=${callerNorm ?? "null"}`);
+        return { chained, stoppedReason: "cross_network" };
+      }
+    }
 
     const childAlias = child.to_name;
     const marker = `\n\n[via ${childAlias} 子任务结果]\n${currentReply}`;
@@ -790,10 +1133,16 @@ export function chainReplyToParent(childTaskId: string, replyText: string, reply
       } catch {}
     }
 
+    // This iteration actually wrote a parent row (and possibly an
+    // inbox notification). Record that so the caller can gate its
+    // SSE push on a real chain.
+    chained = true;
+
     // Recurse up the chain.
     currentChildId = parent.task_id;
     currentReply = newResult;
   }
+  return { chained };
 }
 
 export function logTaskEvent(taskId: string, fromStatus: string | null, toStatus: string, actor: string, detail?: string) {

package/src/index.ts

@@ -24,6 +24,8 @@ import {
 } from "./uploads.js";
 import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync } from "fs";
 import { dirname as pathDirname } from "path";
+import { startRetentionSweeper } from "./retention.js";
+import { startStaleSessionSweeper } from "./stale-sweeper.js";
 
 const PORT = Number(process.env.PORT) || 9200;
 const HOST = process.env.HOST || "127.0.0.1";
@@ -1066,11 +1068,9 @@ Bun.serve({
 
     // ── REST: all sessions status ──
     if (url.pathname === "/api/status") {
-      const cutoff = new Date(Date.now() - 10 * 60 * 1000).toISOString().replace("T", " ").slice(0, 19);
-      const staleParams: any[] = [cutoff];
-      let staleSql = "UPDATE sessions SET status = 'offline' WHERE updated_at < ?1 AND status != 'offline'";
-      staleSql = addNetworkScope(staleSql, staleParams, restScope);
-      db.run(staleSql, staleParams);
+      // Round-2/4 review ③: stale-marking moved to startStaleSessionSweeper()
+      // (background timer, ~60s cadence). Read paths no longer fire UPDATE.
+      // Per-request UPDATE was a write-amp vector — see stale-sweeper.ts.
       cleanupCommittedRenameSessions(restScope.networkId ? [restScope.networkId] : restScope.networkIds ?? null);
       // `?light=1` returns a narrow projection (alias / status / agent / task /
       // server / updated_at + runtime + network_id) — used by the mobile APP
@@ -1138,12 +1138,7 @@ Bun.serve({
 
     // ── REST: aggregate agents by physical server ──
     if (url.pathname === "/api/servers") {
-      const cutoff = new Date(Date.now() - 10 * 60 * 1000).toISOString().replace("T", " ").slice(0, 19);
-      const staleParams: any[] = [cutoff];
-      let staleSql = "UPDATE sessions SET status = 'offline' WHERE updated_at < ?1 AND status != 'offline'";
-      staleSql = addNetworkScope(staleSql, staleParams, restScope);
-      db.run(staleSql, staleParams);
-
+      // Round-2/4 review ③: stale-marking moved to background sweeper.
       const params: any[] = [];
       let sql = `
         SELECT hostname, ip, cpu_load_1min, cpu_cores, mem_avail_gb, mem_used_gb,
@@ -1220,12 +1215,7 @@ Bun.serve({
       const detailKind = serverDetailMatch[2];
       if (!host) return withCors(req, Response.json({ ok: false, error: "host required" }, { status: 400 }));
 
-      const cutoff = sqliteTime(new Date(Date.now() - 10 * 60 * 1000));
-      const staleParams: any[] = [cutoff];
-      let staleSql = "UPDATE sessions SET status = 'offline' WHERE updated_at < ?1 AND status != 'offline'";
-      staleSql = addNetworkScope(staleSql, staleParams, restScope);
-      db.run(staleSql, staleParams);
-
+      // Round-2/4 review ③: stale-marking moved to background sweeper.
       if (detailKind === "agents") {
         const params: any[] = [host, host];
         let sql = `
@@ -1927,6 +1917,38 @@ Bun.serve({
       }));
     }
 
+    // ── REST: single node config snapshot (RFC-024 B5) ──
+    // Dashboard calls this for the snapshot path. Returns the masked
+    // {model, flags, config_revision} the node last posted via
+    // report_status (B6). NEVER reads per-node files. Network-scoped
+    // via addNetworkScope so a netA viewer can't read a netB node.
+    const nodeConfigMatch = url.pathname.match(/^\/api\/nodes\/([^/]+)\/config$/);
+    if (nodeConfigMatch && req.method === "GET") {
+      const nodeId = decodeURIComponent(nodeConfigMatch[1] ?? "");
+      const params: any[] = [nodeId];
+      let sql = "SELECT node_id, alias, network_id, config_revision, config_snapshot FROM nodes WHERE node_id = ?1";
+      sql = addNetworkScope(sql, params, restScope);
+      sql += " LIMIT 1";
+      const node = db.get<any>(sql, ...params);
+      if (!node) {
+        return withCors(req, Response.json({ ok: false, error: "node_not_found", node_id: nodeId }, { status: 404 }));
+      }
+      let snapshot: any = {};
+      if (node.config_snapshot) {
+        try { snapshot = JSON.parse(node.config_snapshot); } catch { snapshot = {}; }
+      }
+      return withCors(req, Response.json({
+        ok: true,
+        node_id: node.node_id,
+        alias: node.alias,
+        network_id: node.network_id,
+        config_revision: node.config_revision || 0,
+        model: snapshot.model ?? null,
+        flags: snapshot.flags ?? {},
+        config_update_capable: snapshot.config_update_capable ?? false,
+      }));
+    }
+
     // ── REST: nodes table (V2 Sprint 2) ──
     if (url.pathname === "/api/nodes") {
       const nodeId = url.searchParams.get("node_id");
@@ -2105,9 +2127,31 @@ Security: ${SECURITY_LABEL}
   },
 });
 
+// Round-2/4 review ② — periodic retention sweep + incremental VACUUM.
+// Sweeps every hour by default. Operators can disable any single table
+// by setting COMMHUB_RETENTION_*_DAYS to a negative value, or shorten
+// the sweep window via COMMHUB_RETENTION_SWEEP_MINUTES.
+const sweepIntervalMinutes = Number(process.env.COMMHUB_RETENTION_SWEEP_MINUTES);
+const sweepIntervalMs = Number.isFinite(sweepIntervalMinutes) && sweepIntervalMinutes > 0
+  ? sweepIntervalMinutes * 60 * 1000
+  : 60 * 60 * 1000;
+const retentionSweeperTimer = startRetentionSweeper(sweepIntervalMs);
+
+// Round-2/4 review ③ — stale session sweeper (coexists with the
+// retention sweeper above; different concerns + different cadences).
+// Replaces the per-request UPDATE in GET /api/status (+ /api/servers,
+// /api/server-detail/*, MCP get_all_status). Each of those endpoints
+// used to run UPDATE on the sessions table just to maintain the
+// derived `offline` status; with the dashboard polling fast that was
+// 99% no-op write-amp under hot read paths. Now done globally once
+// every COMMHUB_STALE_SWEEP_SECONDS (default 60s).
+const staleSweeperTimer = startStaleSessionSweeper();
+
 // ── Graceful shutdown ───────────────────────────────
 function shutdown() {
   console.log("[commhub] shutting down...");
+  clearInterval(retentionSweeperTimer);
+  clearInterval(staleSweeperTimer);
   db.close();
   process.exit(0);
 }