chainlesschain 0.66.0 → 0.132.0

package/src/lib/hook-manager.js

@@ -387,3 +387,383 @@ export function updateHookStats(
     "UPDATE hooks SET execution_count = ?, error_count = ?, total_execution_time = ?, updated_at = datetime('now') WHERE id = ?",
   ).run(newCount, newErrorCount, newTotalTime, hookId);
 }
+
+// ===== V2 Surface: Hook Manager governance overlay (CLI v0.132.0) =====
+// In-memory governance for hook profiles + execution lifecycle, independent of
+// the legacy registerHook/executeHooks SQLite-backed path above.
+
+export const HOOK_PROFILE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  DISABLED: "disabled",
+  RETIRED: "retired",
+});
+
+export const HOOK_EXEC_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _hookProfileTransitionsV2 = new Map([
+  [
+    HOOK_PROFILE_MATURITY_V2.PENDING,
+    new Set([
+      HOOK_PROFILE_MATURITY_V2.ACTIVE,
+      HOOK_PROFILE_MATURITY_V2.RETIRED,
+    ]),
+  ],
+  [
+    HOOK_PROFILE_MATURITY_V2.ACTIVE,
+    new Set([
+      HOOK_PROFILE_MATURITY_V2.DISABLED,
+      HOOK_PROFILE_MATURITY_V2.RETIRED,
+    ]),
+  ],
+  [
+    HOOK_PROFILE_MATURITY_V2.DISABLED,
+    new Set([
+      HOOK_PROFILE_MATURITY_V2.ACTIVE,
+      HOOK_PROFILE_MATURITY_V2.RETIRED,
+    ]),
+  ],
+  [HOOK_PROFILE_MATURITY_V2.RETIRED, new Set()],
+]);
+const _hookProfileTerminalV2 = new Set([HOOK_PROFILE_MATURITY_V2.RETIRED]);
+
+const _hookExecTransitionsV2 = new Map([
+  [
+    HOOK_EXEC_LIFECYCLE_V2.QUEUED,
+    new Set([HOOK_EXEC_LIFECYCLE_V2.RUNNING, HOOK_EXEC_LIFECYCLE_V2.CANCELLED]),
+  ],
+  [
+    HOOK_EXEC_LIFECYCLE_V2.RUNNING,
+    new Set([
+      HOOK_EXEC_LIFECYCLE_V2.COMPLETED,
+      HOOK_EXEC_LIFECYCLE_V2.FAILED,
+      HOOK_EXEC_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [HOOK_EXEC_LIFECYCLE_V2.COMPLETED, new Set()],
+  [HOOK_EXEC_LIFECYCLE_V2.FAILED, new Set()],
+  [HOOK_EXEC_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _hookExecTerminalV2 = new Set([
+  HOOK_EXEC_LIFECYCLE_V2.COMPLETED,
+  HOOK_EXEC_LIFECYCLE_V2.FAILED,
+  HOOK_EXEC_LIFECYCLE_V2.CANCELLED,
+]);
+
+const _hookProfilesV2 = new Map();
+const _hookExecsV2 = new Map();
+let _maxActiveHooksPerOwnerV2 = 20;
+let _maxPendingExecsPerHookV2 = 32;
+let _hookIdleMsV2 = 24 * 60 * 60 * 1000;
+let _hookExecStuckMsV2 = 60 * 1000;
+
+function _hookPosIntV2(n, label) {
+  const v = Math.floor(Number(n));
+  if (!Number.isFinite(v) || v <= 0)
+    throw new Error(`${label} must be positive integer`);
+  return v;
+}
+
+export function setMaxActiveHooksPerOwnerV2(n) {
+  _maxActiveHooksPerOwnerV2 = _hookPosIntV2(n, "maxActiveHooksPerOwner");
+}
+export function getMaxActiveHooksPerOwnerV2() {
+  return _maxActiveHooksPerOwnerV2;
+}
+export function setMaxPendingExecsPerHookV2(n) {
+  _maxPendingExecsPerHookV2 = _hookPosIntV2(n, "maxPendingExecsPerHook");
+}
+export function getMaxPendingExecsPerHookV2() {
+  return _maxPendingExecsPerHookV2;
+}
+export function setHookIdleMsV2(n) {
+  _hookIdleMsV2 = _hookPosIntV2(n, "hookIdleMs");
+}
+export function getHookIdleMsV2() {
+  return _hookIdleMsV2;
+}
+export function setHookExecStuckMsV2(n) {
+  _hookExecStuckMsV2 = _hookPosIntV2(n, "hookExecStuckMs");
+}
+export function getHookExecStuckMsV2() {
+  return _hookExecStuckMsV2;
+}
+
+export function _resetStateHookManagerV2() {
+  _hookProfilesV2.clear();
+  _hookExecsV2.clear();
+  _maxActiveHooksPerOwnerV2 = 20;
+  _maxPendingExecsPerHookV2 = 32;
+  _hookIdleMsV2 = 24 * 60 * 60 * 1000;
+  _hookExecStuckMsV2 = 60 * 1000;
+}
+
+export function registerHookProfileV2({ id, owner, event, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_hookProfilesV2.has(id))
+    throw new Error(`hook profile ${id} already registered`);
+  const now = Date.now();
+  const p = {
+    id,
+    owner,
+    event: event || "*",
+    status: HOOK_PROFILE_MATURITY_V2.PENDING,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    retiredAt: null,
+    lastTouchedAt: now,
+    metadata: { ...(metadata || {}) },
+  };
+  _hookProfilesV2.set(id, p);
+  return { ...p, metadata: { ...p.metadata } };
+}
+
+function _hookProfileCheck(from, to) {
+  const allowed = _hookProfileTransitionsV2.get(from);
+  if (!allowed || !allowed.has(to))
+    throw new Error(`invalid hook profile transition ${from} → ${to}`);
+}
+
+function _countActiveHooksByOwner(owner) {
+  let n = 0;
+  for (const p of _hookProfilesV2.values()) {
+    if (p.owner === owner && p.status === HOOK_PROFILE_MATURITY_V2.ACTIVE) n++;
+  }
+  return n;
+}
+
+export function activateHookProfileV2(id) {
+  const p = _hookProfilesV2.get(id);
+  if (!p) throw new Error(`hook profile ${id} not found`);
+  _hookProfileCheck(p.status, HOOK_PROFILE_MATURITY_V2.ACTIVE);
+  const isRecovery = p.status === HOOK_PROFILE_MATURITY_V2.DISABLED;
+  if (!isRecovery) {
+    const active = _countActiveHooksByOwner(p.owner);
+    if (active >= _maxActiveHooksPerOwnerV2) {
+      throw new Error(
+        `max active hooks per owner (${_maxActiveHooksPerOwnerV2}) reached for ${p.owner}`,
+      );
+    }
+  }
+  const now = Date.now();
+  p.status = HOOK_PROFILE_MATURITY_V2.ACTIVE;
+  p.updatedAt = now;
+  p.lastTouchedAt = now;
+  if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+
+export function disableHookProfileV2(id) {
+  const p = _hookProfilesV2.get(id);
+  if (!p) throw new Error(`hook profile ${id} not found`);
+  _hookProfileCheck(p.status, HOOK_PROFILE_MATURITY_V2.DISABLED);
+  const now = Date.now();
+  p.status = HOOK_PROFILE_MATURITY_V2.DISABLED;
+  p.updatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+
+export function retireHookProfileV2(id) {
+  const p = _hookProfilesV2.get(id);
+  if (!p) throw new Error(`hook profile ${id} not found`);
+  _hookProfileCheck(p.status, HOOK_PROFILE_MATURITY_V2.RETIRED);
+  const now = Date.now();
+  p.status = HOOK_PROFILE_MATURITY_V2.RETIRED;
+  p.updatedAt = now;
+  if (!p.retiredAt) p.retiredAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+
+export function touchHookProfileV2(id) {
+  const p = _hookProfilesV2.get(id);
+  if (!p) throw new Error(`hook profile ${id} not found`);
+  if (_hookProfileTerminalV2.has(p.status))
+    throw new Error(`cannot touch terminal hook profile ${id}`);
+  const now = Date.now();
+  p.lastTouchedAt = now;
+  p.updatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+
+export function getHookProfileV2(id) {
+  const p = _hookProfilesV2.get(id);
+  if (!p) return null;
+  return { ...p, metadata: { ...p.metadata } };
+}
+
+export function listHookProfilesV2() {
+  return [..._hookProfilesV2.values()].map((p) => ({
+    ...p,
+    metadata: { ...p.metadata },
+  }));
+}
+
+function _countPendingExecsByHook(hookId) {
+  let n = 0;
+  for (const e of _hookExecsV2.values()) {
+    if (
+      e.hookId === hookId &&
+      (e.status === HOOK_EXEC_LIFECYCLE_V2.QUEUED ||
+        e.status === HOOK_EXEC_LIFECYCLE_V2.RUNNING)
+    )
+      n++;
+  }
+  return n;
+}
+
+export function createHookExecV2({ id, hookId, payload, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!hookId || typeof hookId !== "string")
+    throw new Error("hookId is required");
+  if (_hookExecsV2.has(id)) throw new Error(`hook exec ${id} already exists`);
+  const hook = _hookProfilesV2.get(hookId);
+  if (!hook) throw new Error(`hook profile ${hookId} not found`);
+  const pending = _countPendingExecsByHook(hookId);
+  if (pending >= _maxPendingExecsPerHookV2) {
+    throw new Error(
+      `max pending execs per hook (${_maxPendingExecsPerHookV2}) reached for ${hookId}`,
+    );
+  }
+  const now = Date.now();
+  const e = {
+    id,
+    hookId,
+    payload: payload || null,
+    status: HOOK_EXEC_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...(metadata || {}) },
+  };
+  _hookExecsV2.set(id, e);
+  return { ...e, metadata: { ...e.metadata } };
+}
+
+function _hookExecCheck(from, to) {
+  const allowed = _hookExecTransitionsV2.get(from);
+  if (!allowed || !allowed.has(to))
+    throw new Error(`invalid hook exec transition ${from} → ${to}`);
+}
+
+export function startHookExecV2(id) {
+  const e = _hookExecsV2.get(id);
+  if (!e) throw new Error(`hook exec ${id} not found`);
+  _hookExecCheck(e.status, HOOK_EXEC_LIFECYCLE_V2.RUNNING);
+  const now = Date.now();
+  e.status = HOOK_EXEC_LIFECYCLE_V2.RUNNING;
+  e.updatedAt = now;
+  if (!e.startedAt) e.startedAt = now;
+  return { ...e, metadata: { ...e.metadata } };
+}
+
+export function completeHookExecV2(id) {
+  const e = _hookExecsV2.get(id);
+  if (!e) throw new Error(`hook exec ${id} not found`);
+  _hookExecCheck(e.status, HOOK_EXEC_LIFECYCLE_V2.COMPLETED);
+  const now = Date.now();
+  e.status = HOOK_EXEC_LIFECYCLE_V2.COMPLETED;
+  e.updatedAt = now;
+  if (!e.settledAt) e.settledAt = now;
+  return { ...e, metadata: { ...e.metadata } };
+}
+
+export function failHookExecV2(id, reason) {
+  const e = _hookExecsV2.get(id);
+  if (!e) throw new Error(`hook exec ${id} not found`);
+  _hookExecCheck(e.status, HOOK_EXEC_LIFECYCLE_V2.FAILED);
+  const now = Date.now();
+  e.status = HOOK_EXEC_LIFECYCLE_V2.FAILED;
+  e.updatedAt = now;
+  if (!e.settledAt) e.settledAt = now;
+  if (reason) e.metadata.failReason = String(reason);
+  return { ...e, metadata: { ...e.metadata } };
+}
+
+export function cancelHookExecV2(id, reason) {
+  const e = _hookExecsV2.get(id);
+  if (!e) throw new Error(`hook exec ${id} not found`);
+  _hookExecCheck(e.status, HOOK_EXEC_LIFECYCLE_V2.CANCELLED);
+  const now = Date.now();
+  e.status = HOOK_EXEC_LIFECYCLE_V2.CANCELLED;
+  e.updatedAt = now;
+  if (!e.settledAt) e.settledAt = now;
+  if (reason) e.metadata.cancelReason = String(reason);
+  return { ...e, metadata: { ...e.metadata } };
+}
+
+export function getHookExecV2(id) {
+  const e = _hookExecsV2.get(id);
+  if (!e) return null;
+  return { ...e, metadata: { ...e.metadata } };
+}
+
+export function listHookExecsV2() {
+  return [..._hookExecsV2.values()].map((e) => ({
+    ...e,
+    metadata: { ...e.metadata },
+  }));
+}
+
+export function autoDisableIdleHooksV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const p of _hookProfilesV2.values()) {
+    if (
+      p.status === HOOK_PROFILE_MATURITY_V2.ACTIVE &&
+      t - p.lastTouchedAt >= _hookIdleMsV2
+    ) {
+      p.status = HOOK_PROFILE_MATURITY_V2.DISABLED;
+      p.updatedAt = t;
+      flipped.push(p.id);
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function autoFailStuckHookExecsV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const e of _hookExecsV2.values()) {
+    if (
+      e.status === HOOK_EXEC_LIFECYCLE_V2.RUNNING &&
+      e.startedAt != null &&
+      t - e.startedAt >= _hookExecStuckMsV2
+    ) {
+      e.status = HOOK_EXEC_LIFECYCLE_V2.FAILED;
+      e.updatedAt = t;
+      if (!e.settledAt) e.settledAt = t;
+      e.metadata.failReason = "auto-fail-stuck";
+      flipped.push(e.id);
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function getHookManagerStatsV2() {
+  const profilesByStatus = {};
+  for (const s of Object.values(HOOK_PROFILE_MATURITY_V2))
+    profilesByStatus[s] = 0;
+  for (const p of _hookProfilesV2.values()) profilesByStatus[p.status]++;
+  const execsByStatus = {};
+  for (const s of Object.values(HOOK_EXEC_LIFECYCLE_V2)) execsByStatus[s] = 0;
+  for (const e of _hookExecsV2.values()) execsByStatus[e.status]++;
+  return {
+    totalProfilesV2: _hookProfilesV2.size,
+    totalExecsV2: _hookExecsV2.size,
+    maxActiveHooksPerOwner: _maxActiveHooksPerOwnerV2,
+    maxPendingExecsPerHook: _maxPendingExecsPerHookV2,
+    hookIdleMs: _hookIdleMsV2,
+    hookExecStuckMs: _hookExecStuckMsV2,
+    profilesByStatus,
+    execsByStatus,
+  };
+}

package/src/lib/inference-network.js

@@ -404,4 +404,334 @@ export function getSchedulerStats(db) {
 export function _resetState() {
   _nodes.clear();
   _tasks.clear();
+  _maxConcurrentTasksPerNode = INFERENCE_DEFAULT_MAX_CONCURRENT_TASKS_PER_NODE;
+  _heartbeatTimeoutMs = INFERENCE_DEFAULT_HEARTBEAT_TIMEOUT_MS;
+}
+
+/* ──────────────────────────────────────────────────────────
+ *  V2 — Phase 67 surface (strictly additive)
+ * ────────────────────────────────────────────────────────── */
+
+export const NODE_STATUS_V2 = NODE_STATUS;
+export const TASK_STATUS_V2 = TASK_STATUS;
+export const PRIVACY_MODE_V2 = PRIVACY_MODE;
+
+export const INFERENCE_DEFAULT_MAX_CONCURRENT_TASKS_PER_NODE = 4;
+export const INFERENCE_DEFAULT_HEARTBEAT_TIMEOUT_MS = 90000;
+
+let _maxConcurrentTasksPerNode =
+  INFERENCE_DEFAULT_MAX_CONCURRENT_TASKS_PER_NODE;
+let _heartbeatTimeoutMs = INFERENCE_DEFAULT_HEARTBEAT_TIMEOUT_MS;
+
+const TASK_TRANSITIONS_V2 = new Map([
+  ["queued", new Set(["dispatched", "failed"])],
+  ["dispatched", new Set(["running", "failed"])],
+  ["running", new Set(["complete", "failed"])],
+]);
+const TASK_TERMINALS_V2 = new Set(["complete", "failed"]);
+
+export function setMaxConcurrentTasksPerNode(n) {
+  if (typeof n !== "number" || Number.isNaN(n) || n < 1) {
+    throw new Error("maxConcurrentTasksPerNode must be a positive integer");
+  }
+  _maxConcurrentTasksPerNode = Math.floor(n);
+}
+
+export function getMaxConcurrentTasksPerNode() {
+  return _maxConcurrentTasksPerNode;
+}
+
+export function setHeartbeatTimeoutMs(ms) {
+  if (typeof ms !== "number" || Number.isNaN(ms) || ms < 1) {
+    throw new Error("heartbeatTimeoutMs must be a positive integer");
+  }
+  _heartbeatTimeoutMs = Math.floor(ms);
+}
+
+export function getHeartbeatTimeoutMs() {
+  return _heartbeatTimeoutMs;
+}
+
+export function getActiveTasksPerNode(nodeId) {
+  if (!nodeId) return 0;
+  let count = 0;
+  for (const t of _tasks.values()) {
+    if (
+      t.assigned_node === nodeId &&
+      (t.status === "dispatched" || t.status === "running")
+    ) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+export function submitTaskV2(db, { model, input, privacyMode, priority } = {}) {
+  if (!model) throw new Error("model is required");
+  const mode = privacyMode || DEFAULT_CONFIG.defaultPrivacyMode;
+  if (!VALID_PRIVACY_MODES.has(mode)) {
+    throw new Error(`Invalid privacy mode: ${mode}`);
+  }
+  const prio = Math.min(Math.max(priority || 5, 1), DEFAULT_CONFIG.maxPriority);
+
+  const id = _id();
+  const now = _now();
+  const task = {
+    id,
+    model,
+    input: input || null,
+    output: null,
+    privacy_mode: mode,
+    priority: prio,
+    assigned_node: null,
+    status: "queued",
+    duration_ms: null,
+    created_at: now,
+    completed_at: null,
+    started_at: null,
+    error_message: null,
+  };
+
+  db.prepare(
+    `INSERT INTO inference_tasks (id, model, input, output, privacy_mode, priority,
+     assigned_node, status, duration_ms, created_at, completed_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    id,
+    model,
+    task.input,
+    null,
+    mode,
+    prio,
+    null,
+    "queued",
+    null,
+    now,
+    null,
+  );
+
+  _tasks.set(id, task);
+  return { ...task };
+}
+
+function _pickLeastLoadedOnline(privacyMode) {
+  let best = null;
+  let bestLoad = Infinity;
+  for (const n of _nodes.values()) {
+    if (n.status !== "online") continue;
+    const load = getActiveTasksPerNode(n.id);
+    if (load >= _maxConcurrentTasksPerNode) continue;
+    if (load < bestLoad) {
+      best = n;
+      bestLoad = load;
+    }
+  }
+  return best;
+}
+
+export function dispatchTaskV2(db, taskId, { nodeId } = {}) {
+  const t = _tasks.get(taskId);
+  if (!t) throw new Error(`Unknown task: ${taskId}`);
+  if (t.status !== "queued") {
+    throw new Error(
+      `Invalid transition: ${t.status} → dispatched (must be queued)`,
+    );
+  }
+
+  let target = null;
+  if (nodeId) {
+    target = _nodes.get(nodeId);
+    if (!target) throw new Error(`Unknown node: ${nodeId}`);
+    if (target.status !== "online") {
+      throw new Error(`Node ${nodeId} is not online (status=${target.status})`);
+    }
+    if (getActiveTasksPerNode(nodeId) >= _maxConcurrentTasksPerNode) {
+      throw new Error(`Max concurrent tasks reached for node ${nodeId}`);
+    }
+  } else {
+    target = _pickLeastLoadedOnline(t.privacy_mode);
+    if (!target) throw new Error("No eligible online nodes available");
+  }
+
+  t.status = "dispatched";
+  t.assigned_node = target.id;
+  target.task_count += 1;
+
+  db.prepare(
+    `UPDATE inference_tasks SET status = ?, assigned_node = ? WHERE id = ?`,
+  ).run("dispatched", target.id, taskId);
+  db.prepare("UPDATE inference_nodes SET task_count = ? WHERE id = ?").run(
+    target.task_count,
+    target.id,
+  );
+
+  return { ...t };
+}
+
+export function startTask(db, taskId) {
+  const t = _tasks.get(taskId);
+  if (!t) throw new Error(`Unknown task: ${taskId}`);
+  if (t.status !== "dispatched") {
+    throw new Error(
+      `Invalid transition: ${t.status} → running (must be dispatched)`,
+    );
+  }
+  t.status = "running";
+  t.started_at = _now();
+  db.prepare("UPDATE inference_tasks SET status = ? WHERE id = ?").run(
+    "running",
+    taskId,
+  );
+  return { ...t };
+}
+
+export function completeTaskV2(db, taskId, { output, durationMs } = {}) {
+  const t = _tasks.get(taskId);
+  if (!t) throw new Error(`Unknown task: ${taskId}`);
+  if (t.status !== "running") {
+    throw new Error(
+      `Invalid transition: ${t.status} → complete (must be running)`,
+    );
+  }
+  t.status = "complete";
+  t.output = output != null ? output : null;
+  t.completed_at = _now();
+  if (durationMs != null) {
+    t.duration_ms = durationMs;
+  } else if (t.started_at) {
+    t.duration_ms = t.completed_at - t.started_at;
+  } else {
+    t.duration_ms = t.completed_at - t.created_at;
+  }
+
+  db.prepare(
+    `UPDATE inference_tasks SET status = ?, output = ?, completed_at = ?,
+     duration_ms = ? WHERE id = ?`,
+  ).run("complete", t.output, t.completed_at, t.duration_ms, taskId);
+
+  return { ...t };
+}
+
+export function failTaskV2(db, taskId, { error } = {}) {
+  const t = _tasks.get(taskId);
+  if (!t) throw new Error(`Unknown task: ${taskId}`);
+  if (!TASK_TRANSITIONS_V2.get(t.status)?.has("failed")) {
+    throw new Error(`Invalid transition: ${t.status} → failed`);
+  }
+  t.status = "failed";
+  t.error_message = error || null;
+  t.output = error || null;
+  t.completed_at = _now();
+
+  db.prepare(
+    "UPDATE inference_tasks SET status = ?, output = ?, completed_at = ? WHERE id = ?",
+  ).run("failed", t.output, t.completed_at, taskId);
+
+  return { ...t };
+}
+
+export function setTaskStatus(db, taskId, newStatus, patch = {}) {
+  const t = _tasks.get(taskId);
+  if (!t) throw new Error(`Unknown task: ${taskId}`);
+  if (!Object.values(TASK_STATUS).includes(newStatus)) {
+    throw new Error(`Unknown status: ${newStatus}`);
+  }
+  const allowed = TASK_TRANSITIONS_V2.get(t.status);
+  if (!allowed || !allowed.has(newStatus)) {
+    throw new Error(`Invalid transition: ${t.status} → ${newStatus}`);
+  }
+
+  t.status = newStatus;
+  if (patch.output !== undefined) t.output = patch.output;
+  if (patch.errorMessage !== undefined) t.error_message = patch.errorMessage;
+  if (patch.durationMs !== undefined) t.duration_ms = patch.durationMs;
+  if (patch.startedAt !== undefined) t.started_at = patch.startedAt;
+  if (newStatus === "running" && !t.started_at) t.started_at = _now();
+  if (TASK_TERMINALS_V2.has(newStatus)) {
+    t.completed_at = t.completed_at || _now();
+  }
+
+  db.prepare(
+    `UPDATE inference_tasks SET status = ?, output = ?, completed_at = ?,
+     duration_ms = ? WHERE id = ?`,
+  ).run(newStatus, t.output, t.completed_at, t.duration_ms, taskId);
+
+  return { ...t };
+}
+
+export function autoMarkOfflineNodes(db) {
+  const cutoff = _now() - _heartbeatTimeoutMs;
+  const offlined = [];
+  for (const n of _nodes.values()) {
+    if (n.status === "offline") continue;
+    if (n.last_heartbeat < cutoff) {
+      n.status = "offline";
+      db.prepare("UPDATE inference_nodes SET status = ? WHERE id = ?").run(
+        "offline",
+        n.id,
+      );
+      offlined.push({ ...n });
+    }
+  }
+  return offlined;
+}
+
+export function findEligibleNodes({ capability, privacyMode } = {}) {
+  const _ = privacyMode; // reserved for future mode-aware routing
+  const out = [];
+  for (const n of _nodes.values()) {
+    if (n.status !== "online") continue;
+    if (getActiveTasksPerNode(n.id) >= _maxConcurrentTasksPerNode) continue;
+    if (capability) {
+      if (
+        !Array.isArray(n.capabilities) ||
+        !n.capabilities.includes(capability)
+      ) {
+        continue;
+      }
+    }
+    out.push({ ...n });
+  }
+  return out.sort(
+    (a, b) => getActiveTasksPerNode(a.id) - getActiveTasksPerNode(b.id),
+  );
+}
+
+export function getInferenceStatsV2() {
+  const nodesByStatus = {};
+  for (const s of Object.values(NODE_STATUS)) nodesByStatus[s] = 0;
+  const tasksByStatus = {};
+  for (const s of Object.values(TASK_STATUS)) tasksByStatus[s] = 0;
+  const tasksByPrivacyMode = {};
+  for (const m of Object.values(PRIVACY_MODE)) tasksByPrivacyMode[m] = 0;
+
+  const loadPerNode = {};
+  for (const n of _nodes.values()) {
+    nodesByStatus[n.status] = (nodesByStatus[n.status] || 0) + 1;
+    loadPerNode[n.id] = getActiveTasksPerNode(n.id);
+  }
+
+  let durSum = 0;
+  let durCount = 0;
+  for (const t of _tasks.values()) {
+    tasksByStatus[t.status] = (tasksByStatus[t.status] || 0) + 1;
+    tasksByPrivacyMode[t.privacy_mode] =
+      (tasksByPrivacyMode[t.privacy_mode] || 0) + 1;
+    if (t.status === "complete" && typeof t.duration_ms === "number") {
+      durSum += t.duration_ms;
+      durCount += 1;
+    }
+  }
+
+  return {
+    totalNodes: _nodes.size,
+    totalTasks: _tasks.size,
+    maxConcurrentTasksPerNode: _maxConcurrentTasksPerNode,
+    heartbeatTimeoutMs: _heartbeatTimeoutMs,
+    nodesByStatus,
+    tasksByStatus,
+    tasksByPrivacyMode,
+    loadPerNode,
+    avgDurationMs: durCount > 0 ? Math.round(durSum / durCount) : 0,
+  };
 }