@pleri/olam-cli 0.1.195 → 0.1.198

package/host-cp/src/server.mjs

@@ -84,6 +84,11 @@ import {
   defaultListContainerNames,
 } from './boot-reconciler.mjs';
 import { startWorldActivityTracker } from './world-activity-tracker.mjs';
+import { startWorldWatchdog } from './world-watchdog.mjs';
+import { createRecovery } from './world-watchdog-recovery.mjs';
+import { createLeakyBucket } from './lib/leaky-bucket.mjs';
+import { read as readLastDispatch, safePersistLastDispatch } from './dispatch-persister.mjs';
+import { findClaudePid } from './world-watchdog-pid-lookup.mjs';
 import { authSecretHint } from './auth-secret-hint.mjs';
 import * as tunnelManager from './world-tunnel-manager.mjs';
 import * as bridgeManager from './port-bridge-manager.mjs';
@@ -96,6 +101,7 @@ import {
 import { instrumentHandler, renderMetrics } from './metrics.mjs';
 import { handleDispatchFromEmail } from './lib/email-dispatch.mjs';
 import { handleDispatchFromLinear } from './lib/linear-dispatch.mjs';
+// (safePersistLastDispatch imported above alongside readLastDispatch)
 import { emitTierSuggestion } from '../dispatch/auto-tier-scheduler.mjs';
 import { isServeOnly, isOrchestrationRoute, ORCHESTRATION_UNAVAILABLE } from './serve-only-config.mjs';
 
@@ -1874,6 +1880,41 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
   // the isOrchestrationRoute guard — it covers /api/world/, /api/worlds/<id>,
   // and /v1/worlds/ for all methods, so no per-route guard is needed here.)
 
+  // GET /api/world/<id>/socket-health — world watchdog verdict (A5).
+  // Returns the latest in-memory probe result from the world watchdog.
+  // Read-only; never mutates world state.
+  //   200: { worldId, verdict, signals, pid, lastTickAt } — known world + tick fired
+  //   200 verdict='unknown': known world but no tick has fired yet
+  //   404: unknown_world
+  // serve-only: returns 503 orchestration_unavailable (isOrchestrationRoute covers
+  //   /api/world/* prefix, so this route is already blocked upstream before reaching here).
+  const socketHealthMatch = /^\/api\/world\/([^/?#]+)\/socket-health\/?$/.exec(url.pathname);
+  if (socketHealthMatch && req.method === 'GET') {
+    const worldId = decodeURIComponent(socketHealthMatch[1]);
+    if (!(worldId in WORLDS)) {
+      return jsonReply(res, 404, { error: 'unknown_world' });
+    }
+    // worldWatchdog is null in serve-only mode (but the serve-only gate above
+    // would have returned 503 before we get here; belt-and-suspenders).
+    const entry = worldWatchdog ? worldWatchdog.getVerdict(worldId) : null;
+    if (!entry) {
+      return jsonReply(res, 200, {
+        worldId,
+        verdict: 'unknown',
+        signals: null,
+        pid: null,
+        lastTickAt: null,
+      });
+    }
+    return jsonReply(res, 200, {
+      worldId,
+      verdict: entry.lastVerdict,
+      signals: entry.lastSignals,
+      pid: entry.lastPid,
+      lastTickAt: entry.lastTickAt,
+    });
+  }
+
   // GET /api/world/<id>/progress — phase ladder progress for inbox row.
   const progressMatch = /^\/api\/world\/([^/?#]+)\/progress\/?$/.exec(url.pathname);
   if (progressMatch && req.method === 'GET') {
@@ -1892,8 +1933,16 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
       prStateStore,
       getGhToken: resolveGhToken,
     });
-    progressCache.set(worldId, { fetchedAt: Date.now(), data });
-    return jsonReply(res, 200, data);
+    // C1 — attach socketHealth if watchdog has fired for this world.
+    const verdictEntry = worldWatchdog ? worldWatchdog.getVerdict(worldId) : null;
+    const enriched = verdictEntry
+      ? {
+          ...data,
+          socketHealth: buildSocketHealthPayload(worldId, verdictEntry),
+        }
+      : data;
+    progressCache.set(worldId, { fetchedAt: Date.now(), data: enriched });
+    return jsonReply(res, 200, enriched);
   }
 
   // /api/world/<id>/* → proxy to per-world CP with X-Olam-Secret injected.
@@ -2686,6 +2735,15 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
       // env-var enrichments are applied.
       const enriched = enrichedObj ? JSON.stringify(enrichedObj) : JSON.stringify(parsed);
 
+      if (parsed.world_id && parsed.prompt) {
+        safePersistLastDispatch({
+          worldId: parsed.world_id,
+          messageId: parsed.session_id ?? `cloud-dispatch-${Date.now()}`,
+          prompt: parsed.prompt,
+          source: 'cloud-dispatch',
+        });
+      }
+
       // Phase H h2: attach CF Access service-token headers when configured
       // (machine-to-machine auth). Additive alongside Basic auth. CF Access
       // headers are validated at the EDGE of origins behind a CF Access app
@@ -3674,6 +3732,119 @@ const worldActivityTracker = SERVE_ONLY
       broadcaster: hostStream,
     });
 
+// World watchdog — periodic probe of each active world's claude PID for the
+// three wedge signals (wchan + CLOSE_WAIT + CPU). Emits `world.watchdog.tick`
+// events on the host-stream broadcaster.
+//
+// Phase B: recovery is wired when compute.autoRecover !== false.
+// Default is false (detection-only, byte-identical to Phase A behaviour).
+//
+// SERVE-ONLY: no docker / worlds.db on a managed cluster; null sentinel keeps
+// the shutdown handler's `worldWatchdog?.stop()` a no-op.
+//
+// getClaudePidForWorld is a v1 stub returning null for all worlds. All worlds
+// therefore emit verdict='unknown' until real PID lookup is wired in a follow-up.
+
+// ── Recovery setup (Phase B) ─────────────────────────────────────────────────
+// Load autoRecover from env OLAM_AUTO_RECOVER (or false by default — D4).
+// Falls back to false if config unavailable or field absent.
+
+// The compute.autoRecover field lives in .olam/config.yaml (per workspace),
+// not in ~/.olam/config.json (global). Host-cp does not load workspace YAML at
+// startup. Read from env OLAM_AUTO_RECOVER; default false (D4 — OFF by default).
+const _watchdogAutoRecoverMode = (() => {
+  const envVal = process.env.OLAM_AUTO_RECOVER;
+  if (envVal === 'true') return true;
+  if (envVal === 'dry-run') return 'dry-run';
+  return false;
+})();
+
+const _watchdogLeakyBucket = createLeakyBucket({ capacity: 3, windowMs: 3_600_000 });
+
+const _watchdogRecovery = SERVE_ONLY
+  ? null
+  : createRecovery({
+      autoRecoverMode: _watchdogAutoRecoverMode,
+      leakyBucket: _watchdogLeakyBucket,
+      broadcaster: hostStream,
+      persister: { read: readLastDispatch },
+      // TODO: wire real replay once operator has run the B3 idempotence probe
+      // and confirmed dispatch is idempotent for all substrates in use.
+      // See docs/architecture/world-watchdog.md Recovery > Idempotence probe.
+      // For now: log + emit replay_stub breadcrumb so the stub path is visible.
+      replay: async ({ worldId, prompt }) => {
+        console.warn(
+          `[world-watchdog-recovery] replay stub: worldId=${worldId} prompt="${prompt.slice(0, 80)}..." — real replay deferred pending B3 sign-off`,
+        );
+        // breadcrumb already emitted by createRecovery before calling replay
+      },
+    });
+
+const worldWatchdog = SERVE_ONLY
+  ? null
+  : startWorldWatchdog({
+      broadcaster: hostStream,
+      recovery: _watchdogRecovery,
+      listActiveWorlds: async () => {
+        // Reuse the same worlds.db query as worldActivityTracker: return all
+        // non-destroyed/failed world IDs for probing.
+        let Database;
+        try {
+          const { createRequire } = await import('node:module');
+          const req = createRequire(import.meta.url);
+          Database = req('better-sqlite3');
+        } catch {
+          return [];
+        }
+        let db;
+        try {
+          db = new Database(WORLDS_DB_PATH, { fileMustExist: true });
+        } catch {
+          return [];
+        }
+        try {
+          const rows = db
+            .prepare("SELECT id FROM worlds WHERE status NOT IN ('destroyed', 'failed')")
+            .all();
+          return rows.map((r) => r.id).filter((id) => typeof id === 'string');
+        } catch {
+          return [];
+        } finally {
+          try { db.close(); } catch { /* ignore */ }
+        }
+      },
+      getClaudePidForWorld: async (worldId) =>
+        findClaudePid({ containerId: `olam-${worldId}-devbox` }),
+    });
+
+/**
+ * C1 — Serialize a WorldWatchdogState entry into the `socketHealth` sub-object
+ * shape shared by the /progress payload and the SPA TypeScript types.
+ *
+ * @param {string} worldId  Used to peek the per-world leaky-bucket count.
+ * @param {import('./world-watchdog.mjs').WorldWatchdogState} entry
+ * @returns {object}
+ */
+function buildSocketHealthPayload(worldId, entry) {
+  const payload = {
+    verdict: entry.lastVerdict,
+    signals: entry.lastSignals,
+    pid: entry.lastPid,
+    lastTickAt: entry.lastTickAt,
+  };
+  // Attach recovery sub-object only when OLAM_AUTO_RECOVER is non-false.
+  if (_watchdogRecovery) {
+    payload.recovery = {
+      mode: _watchdogAutoRecoverMode,
+      restartsInWindow: _watchdogLeakyBucket
+        ? _watchdogLeakyBucket.peek(worldId).totalInWindow
+        : 0,
+      lastRestartAt: null, // tracking per-world last-restart-at is a future enhancement
+    };
+  }
+  return payload;
+}
+
 // ── Phase 1a / B1 (PR3): engine-select + await-before-listen ─────
 //
 // Decision 15: the async KubernetesEngine factory MUST be fully awaited
@@ -3774,12 +3945,13 @@ for (const sig of ['SIGTERM', 'SIGINT']) {
     console.log(`received ${sig}, shutting down`);
     stopEvents();
     prPoller.stop();
-    // worldsDbReconciler + worldActivityTracker are null in SERVE-ONLY mode.
+    // worldsDbReconciler + worldActivityTracker + worldWatchdog are null in SERVE-ONLY mode.
     worldsDbReconciler?.stop();
     stopWorldsSnapshotLoop();
     stopTunnelsSnapshotLoop();
     stopListeningSnapshotLoop();
     worldActivityTracker?.stop();
+    worldWatchdog?.stop();
     if (serversSnapshotTimer) { clearTimeout(serversSnapshotTimer); serversSnapshotTimer = null; }
     hostStream.close();
     if (ndjsonSpanSink) ndjsonSpanSink.close().catch(() => {});

package/host-cp/src/world-watchdog-pid-lookup.mjs

@@ -0,0 +1,119 @@
+/**
+ * world-watchdog-pid-lookup.mjs — host-visible PID lookup for the world watchdog.
+ *
+ * Uses `docker top <containerId>` to enumerate processes inside a world's
+ * container and returns the host-visible PID of the claude process.
+ *
+ * `docker top` output format (Linux Docker / Colima):
+ *   UID   PID   PPID  C  STIME  TTY  TIME     CMD
+ *   root  1234  1     0  10:00  ?    00:00:00  node /usr/local/bin/claude ...
+ *
+ * The PID column (index 1 in default ps output) is already the host-visible
+ * PID. On Mac/Colima the container runs inside a Linux VM so `docker top`
+ * returns PIDs within the VM's PID namespace — these are NOT the macOS host
+ * PIDs, but they ARE the PIDs visible from within the Linux layer (where
+ * /proc reads happen). This is the same namespace the watchdog probes use
+ * when reading /proc/<pid>/wchan etc., so the PIDs are correct for probe use.
+ *
+ * Inject `docker` for tests (avoids spawning real docker processes).
+ *
+ * @see docs/architecture/world-watchdog.md
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Default docker executor — shells out to the real `docker` CLI.
+ *
+ * @param {string} containerId
+ * @returns {Promise<string>}  stdout from `docker top <containerId>`
+ */
+async function defaultDockerTop(containerId) {
+  const { stdout } = await execFileAsync('docker', ['top', containerId], {
+    timeout: 5_000,
+  });
+  return stdout;
+}
+
+/**
+ * Parse the stdout from `docker top` and extract host-visible PIDs whose
+ * CMD column matches a claude process.
+ *
+ * docker top default output columns (ps -ef format):
+ *   UID PID PPID C STIME TTY TIME CMD
+ * Indices: 0=UID, 1=PID, 2=PPID, ..., 7+=CMD (rest of line after 7 columns).
+ *
+ * @param {string} stdout  Raw output from `docker top <id>`
+ * @returns {number[]}     Host-visible PIDs of matching claude processes, sorted ascending.
+ */
+export function parseDockerTopOutput(stdout) {
+  const lines = stdout.split('\n').filter((l) => l.trim().length > 0);
+  if (lines.length < 2) return []; // header only or empty
+
+  // Skip the header line (first line contains column names).
+  const dataLines = lines.slice(1);
+
+  const pids = [];
+  for (const line of dataLines) {
+    // Split on any whitespace — `docker top` columns are space-separated.
+    // CMD may contain spaces; split into at most 8 parts (last = full CMD string).
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 8) continue;
+
+    const pid = parseInt(parts[1], 10);
+    if (!Number.isFinite(pid) || pid <= 0) continue;
+
+    // parts[7] onward is the CMD. Rejoin the remainder.
+    const cmd = parts.slice(7).join(' ');
+
+    // Match: `claude` as standalone binary, or `node` process running claude.
+    if (/(?:^|\/)claude(\s|$)/.test(cmd) || /node[^\s]*\s+.*[/\\]claude(?:\s|$)/.test(cmd)) {
+      pids.push(pid);
+    }
+  }
+
+  return pids.sort((a, b) => a - b);
+}
+
+/**
+ * Find the host-visible PID of the claude process running inside a container.
+ *
+ * Returns the lowest matching PID (parent process heuristic — the supervisor
+ * claude process has a lower PID than any child workers it spawns).
+ *
+ * Fail-soft:
+ *   - docker unreachable / container not found → null + log
+ *   - no claude process in the container → null (silent)
+ *   - multiple claude processes → return the lowest PID
+ *
+ * @param {{
+ *   containerId: string,
+ *   dockerTop?: (containerId: string) => Promise<string>,
+ *   log?: (msg: string) => void,
+ * }} opts
+ * @returns {Promise<number | null>}
+ */
+export async function findClaudePid({
+  containerId,
+  dockerTop = defaultDockerTop,
+  log = (m) => console.log(`[world-watchdog-pid-lookup] ${m}`),
+}) {
+  if (!containerId) return null;
+
+  let stdout;
+  try {
+    stdout = await dockerTop(containerId);
+  } catch (err) {
+    log(`docker top ${containerId} failed: ${err?.message ?? err}`);
+    return null;
+  }
+
+  const pids = parseDockerTopOutput(stdout);
+  if (pids.length === 0) return null;
+
+  // Lowest PID = the parent/supervisor process.
+  return pids[0];
+}

package/host-cp/src/world-watchdog-probes.mjs

@@ -0,0 +1,271 @@
+/**
+ * world-watchdog-probes.mjs — pure probe functions for the world watchdog.
+ *
+ * Three readers extract raw signals from the Linux /proc filesystem:
+ *   - readWchan(pid, opts)            → string | null
+ *   - readCloseWaitSockets(pid, opts) → Array<{remoteIp, remotePort}>
+ *   - readCpuPercent(pid, windowMs, opts) → number | null
+ *
+ * One pure classifier turns those signals into a verdict:
+ *   - classify({ wchan, closeWaitCount, cpuPercent }) → 'healthy'|'suspect'|'wedged'
+ *
+ * All readers are fail-soft: any I/O error or parse error returns
+ * null / [] / 0 rather than throwing. The classifier treats null inputs as
+ * the signal not firing (conservative — only promotes to 'wedged' when all
+ * three signals are conclusive).
+ *
+ * Test injection: pass `opts.procRoot` to redirect /proc reads to a fixture
+ * directory (e.g. src/__tests__/fixtures/proc-gold-elk-5574/).
+ *
+ * CLOSE_WAIT threshold note (deviation from D2): Decision D2 specifies
+ * filtering CLOSE_WAIT by peer hostname (*.anthropic.com | auth-worker.*).
+ * DNS resolution at every tick is unreliable under network stress (exactly
+ * when the watchdog must be most accurate). The gold-elk-5574 forensic data
+ * shows ≥3 CLOSE_WAIT to ANY peer is already diagnostic — a healthy claude
+ * process has 0-1 CLOSE_WAIT sockets under normal operation. The classifier
+ * therefore uses count ≥ 3 without hostname filtering. This deviation is
+ * documented in docs/architecture/world-watchdog.md Signal 2.
+ *
+ * @see docs/architecture/world-watchdog.md
+ * @see packages/host-cp/src/__tests__/world-watchdog-probes.test.mjs
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// HZ — Linux scheduler tick rate. Kernel default is 100; can be 250 or 1000
+// on tickless kernels but the /proc/stat jiffies-to-seconds conversion is
+// independent of the actual HZ when the denominator is wall-clock ms.
+// We divide jiffies by HZ to get seconds of CPU time, then compare to the
+// wall-clock window. HZ=100 is correct for virtually all container environments.
+const LINUX_HZ = 100;
+
+// /proc/net/tcp state byte for CLOSE_WAIT.
+const CLOSE_WAIT_STATE = '08';
+
+/**
+ * Read the wchan (wait channel) of a process's main thread.
+ *
+ * @param {number|string} pid   Process ID.
+ * @param {{ procRoot?: string }} [opts]
+ *   `procRoot` defaults to '/proc'; override for tests.
+ * @returns {Promise<string|null>}
+ *   The wchan string (e.g. 'futex_wait_queue', 'epoll_wait') or null on error.
+ */
+export async function readWchan(pid, opts = {}) {
+  const procRoot = opts.procRoot ?? '/proc';
+  const wchanPath = path.join(procRoot, String(pid), 'wchan');
+  try {
+    const content = await fs.readFile(wchanPath, 'utf8');
+    return content.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read CLOSE_WAIT sockets for a process from /proc/<pid>/net/tcp (and tcp6).
+ *
+ * Parses the /proc/net/tcp format (space-separated hex fields). State field
+ * (column index 3, 0-based) == '08' means CLOSE_WAIT. Returns all matching
+ * entries regardless of remote peer — see module JSDoc for rationale.
+ *
+ * @param {number|string} pid   Process ID.
+ * @param {{ procRoot?: string }} [opts]
+ * @returns {Promise<Array<{remoteIp: string, remotePort: number}>>}
+ *   Array of CLOSE_WAIT socket descriptors, empty on error or no matches.
+ */
+export async function readCloseWaitSockets(pid, opts = {}) {
+  const procRoot = opts.procRoot ?? '/proc';
+  const results = [];
+
+  for (const proto of ['tcp', 'tcp6']) {
+    const tcpPath = path.join(procRoot, String(pid), 'net', proto);
+    let content;
+    try {
+      content = await fs.readFile(tcpPath, 'utf8');
+    } catch {
+      // ENOENT: pid gone or proto not available — skip, not an error.
+      continue;
+    }
+
+    const lines = content.split('\n');
+    // Skip header line.
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      const fields = line.split(/\s+/);
+      // /proc/net/tcp columns (0-based):
+      //   0: sl
+      //   1: local_address (hex IP:port)
+      //   2: rem_address   (hex IP:port)
+      //   3: st            (hex state)
+      if (fields.length < 4) continue;
+      const state = fields[3];
+      if (state !== CLOSE_WAIT_STATE) continue;
+
+      const remAddr = fields[2];
+      const colonIdx = remAddr.lastIndexOf(':');
+      if (colonIdx === -1) continue;
+      const remIpHex = remAddr.slice(0, colonIdx);
+      const remPortHex = remAddr.slice(colonIdx + 1);
+
+      const remIp = parseHexIp(remIpHex);
+      const remPort = parseInt(remPortHex, 16);
+
+      if (remIp !== null && Number.isFinite(remPort)) {
+        results.push({ remoteIp: remIp, remotePort: remPort });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Measure CPU utilisation for a process over a time window.
+ *
+ * Reads /proc/<pid>/stat twice (before + after `windowMs` ms) and computes:
+ *   cpuPercent = (utime+stime delta) / (HZ * windowMs / 1000) * 100
+ *
+ * @param {number|string} pid     Process ID.
+ * @param {number} windowMs       Measurement window in milliseconds.
+ * @param {{ procRoot?: string, sleep?: (ms: number) => Promise<void>, now?: () => number }} [opts]
+ *   `sleep`  — injectable delay function (default: real setTimeout).
+ *   `now`    — injectable clock (default: Date.now).
+ *   `procRoot` — injectable proc root for tests.
+ * @returns {Promise<number|null>}
+ *   CPU percent (0–100+) or null on read/parse error.
+ */
+export async function readCpuPercent(pid, windowMs, opts = {}) {
+  const procRoot = opts.procRoot ?? '/proc';
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const statPath = path.join(procRoot, String(pid), 'stat');
+
+  const before = await readStatTimes(statPath);
+  if (before === null) return null;
+
+  await sleep(windowMs);
+
+  const after = await readStatTimes(statPath);
+  if (after === null) return null;
+
+  const deltaTicks = (after.utime + after.stime) - (before.utime + before.stime);
+  if (deltaTicks < 0) return null;
+
+  // deltaTicks jiffies / HZ = delta CPU-seconds.
+  // windowMs / 1000 = window in seconds.
+  const windowSec = windowMs / 1000;
+  if (windowSec <= 0) return null;
+
+  const cpuPercent = (deltaTicks / LINUX_HZ / windowSec) * 100;
+  return cpuPercent;
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Parse utime + stime from /proc/<pid>/stat content.
+ *
+ * @param {string} statPath
+ * @returns {Promise<{utime: number, stime: number}|null>}
+ */
+async function readStatTimes(statPath) {
+  let content;
+  try {
+    content = await fs.readFile(statPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  // The stat format is: pid (comm) state ppid pgroup session ... utime stime ...
+  // The command name (field 2) can contain spaces and parentheses, so we
+  // find the last ')' to reliably locate the fields that follow.
+  const parenClose = content.lastIndexOf(')');
+  if (parenClose === -1) return null;
+
+  // After the closing ')', fields are space-separated starting with ' state'.
+  // Fields after ')' (0-indexed):
+  //   0: state, 1: ppid, 2: pgrp, 3: session, 4: tty_nr, 5: tpgid,
+  //   6: flags, 7: minflt, 8: cminflt, 9: majflt, 10: cmajflt,
+  //   11: utime, 12: stime (i.e. indices 11+12 from the post-paren split)
+  const afterParen = content.slice(parenClose + 1).trim();
+  const fields = afterParen.split(/\s+/);
+  // utime = fields[11], stime = fields[12]
+  if (fields.length < 13) return null;
+
+  const utime = parseInt(fields[11], 10);
+  const stime = parseInt(fields[12], 10);
+
+  if (!Number.isFinite(utime) || !Number.isFinite(stime)) return null;
+  return { utime, stime };
+}
+
+/**
+ * Parse a hex-encoded IP address from /proc/net/tcp format.
+ *
+ * IPv4: 8 hex chars in little-endian byte order (e.g. "0101007F" → "127.0.0.1").
+ * IPv6: 32 hex chars (4 groups of 8, each in little-endian).
+ *
+ * @param {string} hexIp
+ * @returns {string|null}
+ */
+function parseHexIp(hexIp) {
+  if (hexIp.length === 8) {
+    // IPv4: stored as little-endian 32-bit integer.
+    const b = [
+      parseInt(hexIp.slice(6, 8), 16),
+      parseInt(hexIp.slice(4, 6), 16),
+      parseInt(hexIp.slice(2, 4), 16),
+      parseInt(hexIp.slice(0, 2), 16),
+    ];
+    if (b.some((x) => !Number.isFinite(x))) return null;
+    return b.join('.');
+  }
+  if (hexIp.length === 32) {
+    // IPv6: 4 groups of 8 hex chars, each group little-endian.
+    const groups = [];
+    for (let g = 0; g < 4; g++) {
+      const chunk = hexIp.slice(g * 8, g * 8 + 8);
+      // Reverse byte order within each 32-bit group.
+      const bytes = [
+        chunk.slice(6, 8),
+        chunk.slice(4, 6),
+        chunk.slice(2, 4),
+        chunk.slice(0, 2),
+      ];
+      // Pair bytes into 16-bit groups for IPv6 notation.
+      groups.push(bytes[0] + bytes[1], bytes[2] + bytes[3]);
+    }
+    return groups.join(':');
+  }
+  return null;
+}
+
+// ── Classifier ───────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {'healthy'|'suspect'|'wedged'} WatchdogVerdict
+ */
+
+/**
+ * Classify a set of probe signals into a watchdog verdict.
+ *
+ * AND-gate: all three of (wchan=futex_wait_queue, closeWaitCount≥3, cpuPercent<1)
+ * must fire for 'wedged'. Any subset → 'suspect'. None → 'healthy'.
+ * Null inputs are treated as not-firing (fail-soft).
+ *
+ * @param {{ wchan: string|null, closeWaitCount: number|null, cpuPercent: number|null }} signals
+ * @returns {WatchdogVerdict}
+ */
+export function classify({ wchan, closeWaitCount, cpuPercent }) {
+  const wchanFires = wchan === 'futex_wait_queue';
+  const closeWaitFires = typeof closeWaitCount === 'number' && closeWaitCount >= 3;
+  const cpuFires = typeof cpuPercent === 'number' && cpuPercent < 1;
+
+  const firingCount = (wchanFires ? 1 : 0) + (closeWaitFires ? 1 : 0) + (cpuFires ? 1 : 0);
+
+  if (firingCount === 3) return 'wedged';
+  if (firingCount > 0) return 'suspect';
+  return 'healthy';
+}