create-walle 0.10.1 → 0.10.3

package/template/coding-task-manager/lib/machine-registry.js

@@ -0,0 +1,1494 @@
+'use strict';
+
+// WP-0 (remote-machine-hub-sessions-2026-10-22.html §5 D-3/D-4, §6.1): the hub-side machine
+// registry — the durable list of boxes this CTM can drive sessions on, plus the probe loop
+// that keeps their liveness honest.
+//
+// Three rules from the design doc drive every decision in this file:
+//   D-3  identity is the box's MINTED instance id, pinned on first contact. The transport URL
+//        is replaceable config (it will be a 127.0.0.1 forward at home and a relay URL away),
+//        so a URL whose manifest instance id disagrees with the pinned row for that URL is
+//        refused (`machine_identity_mismatch`) rather than silently re-pointed.
+//   D-4  liveness is HUB-probed and persisted with the HUB clock. The box never dials us
+//        (NAT/corp networks); the hub already both pulls and pushes on its own tick, so the
+//        probe rides that tick.
+//   P3   Unknown != Dead. A machine keeps its previous health until 2 consecutive missed
+//        probes (`unknown`), and only reads `unreachable` after 60 s without a success. If
+//        EVERY enabled machine misses in one sweep, the sweep ALSO reports hubNetworkSuspect
+//        (far more likely this host's network) — advisory context for the UI, never a
+//        write-suppressor: the grace walk still runs, because suppressing it would freeze a
+//        stale `reachable` forever in the common away-from-home case (every box behind the
+//        home LAN), and with one registered machine `unreachable` could never be recorded at
+//        all. Blip protection comes from the grace thresholds themselves, not suppression.
+//
+// All durable writes go through the db owner (db.js's DB_OWNER_MUTATION_ACTIONS map) exactly
+// like every other lib-side mutation; this module never opens a handle and never runs raw SQL.
+// The consecutive-miss counters are deliberately MODULE state, not columns: they are probe
+// bookkeeping, they die with the process, and they must never look like fact to a reader.
+const { dispatchOwnerMutation } = require('./owner-mutation-disposition');
+const { createErrorSink } = require('./error-sink');
+// WP-3 rev 3 (§13.6 D-17): the hub-side `proxy.sh` the installer writes. Node builtins only.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+// WP-7 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-11, §6.5): the pure classification of
+// a box's own skills against the hub's copy and the base the box reported. Required at the top
+// level on purpose — it is a leaf (build/store/codex-install only), so it introduces no cycle, and a
+// probe-time require would hide the edge from the dependency lint.
+const bundleInventory = require('./agent-bundle/inventory');
+// WP-1 (docs/remote-box-model-access-2026-10-26.html §6.2, §5.3 D-2/D-9): the box's OWN model
+// availability, read on the same probe tick as everything else. Only the TTL constant is needed from
+// the module (the block is derived here, on the hub, from the box's §6.1 body) — the module is a
+// leaf (http/https only), so the edge introduces no cycle.
+const { ORIGIN_TTL_MS } = require('./model-availability');
+
+/** REPORT sink for a probe-sweep fault that must not fail the sweep (WP-7's hub-side build). */
+const errorSink = createErrorSink({ name: 'machine-registry' });
+
+const DEFAULT_TIMEOUT_MS = 3000;
+// D-4/P3 grace: a machine with no successful probe for this long reads `unreachable`.
+const UNREACHABLE_AFTER_MS = 60_000;
+// P3: `unknown` starts at the SECOND consecutive miss, so one dropped probe is not news.
+const UNKNOWN_AFTER_MISSES = 2;
+
+const HEALTH_STATES = Object.freeze(['reachable', 'unknown', 'unreachable', 'unhealthy']);
+
+// WP-3 (DGX Spark coding readiness §2): how long a box's CLI sign-in verdict is trusted before the
+// next probe re-reads it. Sign-in changes only when a human acts, so a minute is plenty; the sweep
+// rides the same tick as the health probe and adds no timer of its own.
+const AGENT_AUTH_REFRESH_MS = 60_000;
+// The three states a box's coding agent can be in, as the hub reads them: 'signed_in' |
+// 'signed_out' | 'unknown'. 'unknown' is the honest answer for "never fetched", "the box did not
+// answer", and "the box answered something we do not recognize" alike (P3 Unknown != Dead): only
+// an explicit `signedIn:false` refuses a forward.
+
+// WP-2 (machine-pool-picker-pairing-dashboard-2026-10-24.html D-12/D-16, §6.3): how long a box's
+// own host sample (load, memory, disk, GPU, tasks, lastUsedAt) is trusted before the next probe
+// re-reads it. The SAME 60 s cadence as the sign-in read, on the SAME tick, in the SAME loop — this
+// module still owns exactly ONE timer site (`_getJsonBox`), so no new stabilization-lint surface.
+const HOST_STATS_REFRESH_MS = 60_000;
+
+// instance_id -> consecutive missed probes. Module state by design (see the header).
+const _missStreak = new Map();
+// instance_id -> { claude, codex, checkedAt } — the box's coding-CLI sign-in verdict as the hub
+// last read it (WP-3). Module state for the same reason as _missStreak: it is probe bookkeeping
+// with a freshness stamp, it dies with the process, and a stale copy must never look like fact to a
+// reader (a restart reads `unknown`, which never refuses a forward).
+const _agentAuth = new Map();
+// instance_id -> { presence: { dsh: boolean }, checkedAt } (WP-13b, D-15). The box's OWN
+// available-agents answer as this hub last read it from ITS /api/models/available-agents, reduced to
+// the compact presence the new-session card and the machine row need: whether the box has the
+// DeepSeek Harness. Nothing else from the body is kept — not paths, not versions, not the other
+// agents. Same module-state contract as _agentAuth: a stale copy must never look like fact to a
+// reader (a restart reads "never read", which refuses nothing), and a failed/404/unparseable read
+// KEEPS the previous value (P3, "Unknown != Dead").
+const _agentPresence = new Map();
+// instance_id -> { sample, checkedAt } (D-12, D-16). The box's own host sample as the hub last read
+// it from ITS /api/host/stats?latest=1, plus the hub-clock stamp that gates the next re-read. Same
+// module-state contract as _agentAuth: a stale number must never look fresh, and a box that stops
+// answering keeps its last entry with a FROZEN checkedAt (never advanced without an answer).
+const _hostStats = new Map();
+// instance_id -> the `executionHost` block of the last manifest this hub read from the box (D-4
+// rev 2). The manifest is the ONLY place a member's user settings (displayName/favorite/hidden) and
+// its os/arch/hostname live — the roster deliberately carries none of them (P-1) — so the sweep
+// caches what the probe already fetched instead of asking again.
+const _manifestHost = new Map();
+// instance_id -> the `build` block of the last manifest this hub read from the box (WP-0,
+// docs/fleet-auto-update-pooled-machines-2026-10-26.html S-1/S-2). Same lifetime and the same write
+// sites as `_manifestHost`: the manifest the probe already fetched is the version truth the fleet
+// reconciler and the Machines card read ("which build is that box running?"), so nothing re-asks.
+const _manifestBuild = new Map();
+// instance_id -> the agent-skill push result (WP-3, docs/remote-agent-skills-bundles-2026-10-25.html
+// §6.5). Module state for the same reason as _agentAuth: it describes the LAST push this process
+// made, it is not durable truth about the box, and a restart must read "never pushed" rather than a
+// stale tree. `pushError` is cleared by the next success and kept otherwise; `sentTreeHash`/
+// `sentAt`/`sentCount`/`heldBack` always describe the last SUCCESSFUL push (D-6: a failure never
+// erases what the box is actually running).
+const _agentBundlePush = new Map();
+// instance_id -> { onBox, checkedAt } (WP-7 §6.5/D-11). The box's OWN skill inventory as this hub
+// last read it from ITS /api/agent-skills/inventory, classified against the hub's copy and the base
+// the BOX reported. Module state for the same reason as _agentAuth: it is the last read this process
+// made, and a box that stops answering keeps its entry with a FROZEN onBox — never blanked to "no
+// skills", which would read as "the box lost everything". `checkedAt` is the hub clock stamp that
+// gates the next read (SAME 60 s constant, SAME tick — this module still owns ONE timer site).
+const _agentSkills = new Map();
+// WP-1 §6.2: instance_id -> { block, checkedAt }. The box's OWN model availability (§6.1) as this
+// hub last read it from ITS /api/models/availability, plus the hub-clock stamp that gates the next
+// read. D-9: the read rides the EXISTING 60 s probe tick and is refreshed at most once per
+// ORIGIN_TTL_MS (10 min) per machine — no second timer, no poll. Module state for the same reason as
+// _agentAuth. `block === null` is a REAL answer ("this box predates WP-1"), not "never read" —
+// `checkedAt` is what tells the two apart, and a failed read keeps the previous block untouched.
+const _machineModels = new Map();
+// WP-1 §6.2: how long a box's availability answer is trusted. Same value as the box's own per-origin
+// cache, on purpose: the hub must not re-ask more often than the box would re-probe.
+const MODELS_REFRESH_MS = ORIGIN_TTL_MS;
+// platform -> { items, at }: the hub's own item list (`{agent, kind, name, itemHash}`) as WP-1's
+// builder produced it for that platform. Memoized for AGENT_AUTH_REFRESH_MS so N boxes of one
+// platform cost ONE build per minute. Only `items` is kept — `blobsByHash` is hub-local absolute
+// paths and would pin the whole hub tree in memory for a classification that never reads it.
+const _hubItemCache = new Map();
+// The last sweep's self-suspicion verdict, surfaced by GET /api/machines. Not persisted per
+// machine (design §7 "not persisted per machine") — it is a hub-wide observation about one sweep.
+let _lastSweep = { hubNetworkSuspect: false, at: 0 };
+// WP-3 rev 3 (§13.6 D-17): does THIS hub have an away path? The installer writes its hub half to
+// `~/.config/ctm-away-path/proxy.sh` (bin/away-path.sh cmd_install_hub). Read once per sweep, off
+// the request path (see machineAwayReason); `null` = this process has not swept yet.
+let _awayPathProxyExists = null;
+// Bumped by every registry write this process makes (register, remove, seed, a probe that changed
+// a row). Readers that keep a snapshot (lib/remote-machine-catalog.js) compare it instead of
+// trusting a TTL alone: a snapshot taken a moment before a registration must not hide the new
+// machine from the relay and the merged list.
+let _revision = 0;
+
+/** The registry's write revision (see above). */
+function registryRevision() {
+  return _revision;
+}
+
+/** Record a registry write made outside this module (lib/api/machines.js's remove route). */
+function noteRegistryChanged() {
+  _revision += 1;
+}
+
+function _string(value, max = 1000) {
+  return String(value == null ? '' : value).trim().slice(0, max);
+}
+
+function _now(deps = {}) {
+  return typeof deps.now === 'function' ? Number(deps.now()) || 0 : Date.now();
+}
+
+function _trimUrl(url) {
+  return _string(url, 1000).replace(/\/+$/, '');
+}
+
+// The manifest's instance id, from the same three shapes server.js's golive probe accepts
+// (server.js:13009): {manifest:{instanceId}}, {instance:{…}} and a bare manifest body.
+function _manifestInstanceId(body) {
+  const manifest = (body && (body.manifest || body.instance)) || body || {};
+  return _string(
+    manifest.instanceId || manifest.instance_id || manifest.id
+    || (body && (body.instanceId || body.instance_id)) || '',
+    160,
+  );
+}
+
+/**
+ * D-4 rev 2 / P-1: the machine-owned settings and host identity, read off the manifest's
+ * `executionHost` block. Display fields NEVER come from the roster (P-1) — the manifest is the
+ * authority, and this is the one place the sweep reads them.
+ */
+function _manifestHostBlock(body) {
+  const manifest = (body && (body.manifest || body.instance)) || body || {};
+  const host = manifest.executionHost || manifest.execution_host || {};
+  return {
+    displayName: _string(host.displayName || host.display_name || host.hostLabel || host.hostname || '', 160),
+    favorite: host.favorite === true || host.favorite === 1,
+    hidden: host.hidden === true || host.hidden === 1,
+    os: _string(host.os || host.platform || '', 40),
+    arch: _string(host.arch || '', 40),
+    hostname: _string(host.hostname || '', 160),
+  };
+}
+
+/**
+ * WP-0 (S-1): the manifest's `build` block — the box's own version truth (`lib/instance-manifest.js`
+ * publishes `{ version, sha, builtAt, release }`). Each field is bounded; a manifest without the
+ * block (an older box) reads as three empty strings, never undefined, so a reader can tell "no
+ * build published" from "never probed" (`null`).
+ */
+function _manifestBuildBlock(body) {
+  const manifest = (body && (body.manifest || body.instance)) || body || {};
+  const build = manifest.build || {};
+  return {
+    sha: _string(build.sha, 64),
+    version: _string(build.version, 64),
+    release: _string(build.release, 64),
+  };
+}
+
+function _manifestDisplayName(body) {
+  return _manifestHostBlock(body).displayName;
+}
+
+/**
+ * D-9/WP-3: the cached manifest host block for an instance (the box's `os` is what the bundle
+ * build targets), or null when this hub has never read that box's manifest. A COPY: the cache is
+ * module state and a reader must not be able to mutate it.
+ */
+function manifestHostFor(instanceId) {
+  const host = _manifestHost.get(_string(instanceId, 160)) || null;
+  return host ? { ...host } : null;
+}
+
+function _hostLabel(url) {
+  try { return _string(new URL(url).host, 160); } catch { return _string(url, 160); }
+}
+
+// The hub's own peer credential on the probe, the same headers lib/hosted-sync-worker.js sends to
+// /api/sync/manifest: a box behind a relay or tunnel sees forwarding markers, stops trusting the
+// caller as loopback and answers a credential-less probe 401. INJECTED by the caller (requiring the
+// header builder from here would be a dependency cycle, as with parseSyncPeers below); none
+// configured probes without one (a same-host box still answers over loopback).
+//
+// WP-2 / P-8: the credential is a PER-TARGET decision on a pool member — the shared pool secret goes
+// to a member, the legacy env bearer to a box that never joined — so the caller may inject
+// `peerHeadersFor(instanceId)` instead of one fixed object. The fixed `peerHeaders` object is kept
+// for callers (and tests) that dial with a single credential; when neither is given the probe goes
+// out credential-less, exactly as before.
+function _peerHeadersFor(deps = {}) {
+  const builder = deps.peerHeadersFor;
+  const fixed = deps.peerHeaders && typeof deps.peerHeaders === 'object' ? deps.peerHeaders : {};
+  if (typeof builder !== 'function') return () => fixed;
+  return (instanceId) => {
+    try {
+      const built = builder(instanceId);
+      return built && typeof built === 'object' ? built : {};
+    } catch {
+      return {}; // expected: a credential-builder fault degrades to an anonymous probe, never a failed sweep
+    }
+  };
+}
+
+/**
+ * P-4: the URLs to dial for a machine, in order — the roster's `urls` (LAN first, then the relay
+ * origin), falling back to the single pinned `url` when the row predates the roster (P-8 legacy rows
+ * and seeded placeholders).
+ */
+function _dialUrls(machine = {}) {
+  const list = (Array.isArray(machine.urls) ? machine.urls : []).map((u) => _trimUrl(u)).filter(Boolean);
+  if (list.length) return list;
+  const pinned = _trimUrl(machine.url);
+  return pinned ? [pinned] : [];
+}
+
+// WP-3 rev 3 (§13.6 D-17): is this host one only the home LAN (or this machine) can name? A URL
+// that does not parse is NOT local-only — "would this work from another network?" would be unknown.
+function _isLocalOnlyHost(hostname) {
+  const host = String(hostname || '').toLowerCase();
+  if (!host) return false;
+  if (host === 'localhost' || host.endsWith('.localhost')) return true;
+  if (host.endsWith('.local')) return true;
+  // `new URL('http://[::1]:3456').hostname` keeps the brackets; strip them before parsing.
+  const ip = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+  if (ip.includes(':')) {
+    if (ip === '::1') return true;
+    const first = parseInt(ip.split(':')[0] || '', 16);
+    if (!Number.isInteger(first)) return false;
+    // fc00::/7 (unique-local) and fe80::/10 (link-local).
+    return (first >= 0xfc00 && first <= 0xfdff) || (first >= 0xfe80 && first <= 0xfebf);
+  }
+  const octets = ip.split('.');
+  if (octets.length !== 4) return false;
+  const nums = octets.map((part) => (/^\d{1,3}$/.test(part) ? Number(part) : NaN));
+  if (nums.some((n) => !Number.isInteger(n) || n > 255)) return false;
+  if (nums[0] === 127 || nums[0] === 10) return true; // 127/8 loopback, 10/8 private
+  if (nums[0] === 172 && nums[1] >= 16 && nums[1] <= 31) return true; // 172.16/12
+  return nums[0] === 192 && nums[1] === 168; // 192.168/16
+}
+
+/**
+ * WP-3 rev 3 (docs/off-lan-hub-to-box-access-2026-10-31.html §13.6 D-17): WHY an `unreachable` box
+ * whose every dial URL is local-only cannot be dialled from here, or null when the hub cannot know.
+ * The one readable fact is whether this hub has an away path at all — the hub-side
+ * `~/.config/ctm-away-path/proxy.sh` (bin/away-path.sh cmd_install_hub): no proxy ⇒ nothing could
+ * ever route to the box from off-LAN; proxy present ⇒ this box's tunnel or forward is the down half.
+ *
+ * That fact is read ONCE PER SWEEP (`probeMachinesOnce`), never on the request path: /api/machines
+ * renders on the main thread. `null` (module state) = this process has not swept yet — an honest
+ * "not known", and `unreachable` is only ever written BY a sweep.
+ */
+function machineAwayReason(machine = {}, deps = {}) {
+  const row = machine || {};
+  if (row.health !== 'unreachable') return null;
+  const urls = _dialUrls(row);
+  if (!urls.length) return null;
+  const localOnly = urls.every((raw) => {
+    try {
+      return _isLocalOnlyHost(new URL(raw).hostname);
+    } catch {
+      return false; // expected: an unparsable URL is not local-only (see _isLocalOnlyHost)
+    }
+  });
+  if (!localOnly) return null;
+  const proxyExists = typeof deps.awayPathProxyExists === 'boolean' ? deps.awayPathProxyExists : _awayPathProxyExists;
+  if (proxyExists === null) return null; // this hub has not swept yet, so it does not know
+  return proxyExists ? 'away_path_down' : 'no_away_path';
+}
+
+// One JSON GET against a box, with the AbortController + unref'd timer shape server.js's golive
+// probe uses, so a hung box can never hold the tick open past timeoutMs. Shared by the manifest and
+// the agent-sign-in probes: this is the ONE timer site in the file (a second copy would be a new
+// stabilization-lint ownership surface for no gain).
+async function _getJsonBox(url, pathname, { fetchImpl, timeoutMs = DEFAULT_TIMEOUT_MS, peerHeaders = {} } = {}) {
+  const fetchFn = fetchImpl || global.fetch;
+  if (typeof fetchFn !== 'function') return { ok: false, error: 'fetch_unavailable', status: null, body: null };
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  try {
+    const res = await fetchFn(`${url}${pathname}`, {
+      method: 'GET',
+      headers: { ...peerHeaders, Accept: 'application/json' },
+      signal: controller ? controller.signal : undefined,
+    });
+    if (!res || res.ok === false) {
+      return { ok: false, error: `http_${res ? res.status : 'unknown'}`, status: res ? res.status : null, body: null };
+    }
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+      // expected: a non-JSON 200 body is reachable-but-degraded, not unreachable — each caller
+      // reports it with its own verdict (manifest_invalid / an 'unknown' agent state).
+      body = null;
+    }
+    return { ok: true, error: '', status: res.status, body };
+  } catch (err) {
+    return { ok: false, error: err?.message || String(err), status: null, body: null };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// One manifest read, in the shape server.js's golive probe expects.
+async function _probeManifest(url, options = {}) {
+  const fetched = await _getJsonBox(url, '/api/sync/manifest', options);
+  if (!fetched.ok) return { ok: false, code: 'machine_unreachable', error: fetched.error };
+  const instanceId = _manifestInstanceId(fetched.body);
+  // Reachable but degraded: the box answered and told us nothing we can pin or trust.
+  if (!instanceId) return { ok: false, code: 'machine_manifest_invalid', error: 'manifest_instance_id_missing', body: fetched.body };
+  const host = _manifestHostBlock(fetched.body);
+  return { ok: true, instanceId, displayName: host.displayName, host, build: _manifestBuildBlock(fetched.body) };
+}
+
+/**
+ * P-4 dial order: try the machine's URLs in order and use the first whose manifest instance id is
+ * the row's. A URL that answers with ANOTHER box's id is refused for that URL (D-3) and the next one
+ * is dialled — an SSH forward that was re-pointed must not silently re-key the row.
+ *
+ * `machine_unreachable` is reported only when no URL answered at all: the sweep's "every box silent ⇒
+ * hubNetworkSuspect" verdict (P3) must not fire for a box that answered on one of its URLs.
+ */
+async function _probeMachineManifest(machine = {}, options = {}) {
+  const urls = _dialUrls(machine);
+  let answered = null; // the last attempt that got an HTTP answer (mismatch / no instance id)
+  let last = null;
+  for (const url of urls) {
+    const probe = await _probeManifest(url, options);
+    if (probe.ok && probe.instanceId === machine.instanceId) return { ...probe, url };
+    if (probe.ok) {
+      answered = { ok: false, code: 'machine_identity_mismatch', error: `manifest ${probe.instanceId} != pinned ${machine.instanceId}` };
+      last = answered;
+      continue;
+    }
+    if (probe.code === 'machine_manifest_invalid') {
+      answered = probe;
+      last = probe;
+      continue;
+    }
+    last = probe;
+  }
+  return answered || last || { ok: false, code: 'machine_unreachable', error: 'machine_has_no_url' };
+}
+
+/**
+ * D-12/D-16: read a box's own latest host sample from ITS `/api/host/stats?latest=1` (WP-1). Never
+ * throws and never reports anything but the sample or null: a non-2xx, an unparseable body, a
+ * missing `latest` and a transport throw alike read "no sample this time" and leave the previous
+ * entry (and its `checkedAt`) exactly where they were.
+ */
+async function _probeHostStats(url, options = {}) {
+  const fetched = await _getJsonBox(url, '/api/host/stats?latest=1', options);
+  if (!fetched.ok) return null;
+  const latest = fetched.body && fetched.body.latest;
+  return latest && typeof latest === 'object' ? latest : null;
+}
+
+/**
+ * P-5: read a member's roster version + membership from ITS `/api/pool/roster`. Returns
+ * `{ version, members }` or null (a version-less / unreachable / unparseable answer is "nothing to
+ * adopt", never an error).
+ */
+async function _pullRoster(url, options = {}) {
+  const fetched = await _getJsonBox(url, '/api/pool/roster', options);
+  if (!fetched.ok) return null;
+  const body = fetched.body;
+  if (!body || typeof body !== 'object') return null;
+  const version = body.version && typeof body.version === 'object' ? body.version : null;
+  if (!version) return null;
+  return { version, members: Array.isArray(body.members) ? body.members : [] };
+}
+
+/** The pool store: injected in tests, the machine-pool leaf singleton in production. Never throws. */
+function _machinePool(deps = {}) {
+  if (deps.machinePool && typeof deps.machinePool.hasPool === 'function') return deps.machinePool;
+  try {
+    return require('./machine-pool').getMachinePool();
+  } catch {
+    return null; // expected: machine-pool is a pure leaf; an unreadable store means "no pool"
+  }
+}
+
+/**
+ * This machine's own minted id, or '' when the caller has not injected one (the P-5 delete leg is
+ * then skipped by db.js — an upsert-only convergence, never a wrong deletion).
+ *
+ * INJECTED, never required: `lib/instance-identity-access.js` reaches db.js, and db.js reaches
+ * lib/hosted-sync-worker.js, which reaches this module — so requiring it here closes a lib/**
+ * dependency cycle (dependency-lint ceiling 0; verified, not assumed: the first cut of this file did
+ * exactly that and the lint reported
+ * `lib/instance-identity-access.js -> lib/machine-registry.js -> lib/hosted-sync-worker.js -> db.js`).
+ * `selfInstanceId` may be a string or a `() => string` getter, because identity is only ready after
+ * boot while a sweep repeats for the life of the process.
+ */
+function _selfInstanceId(deps = {}) {
+  const source = deps.selfInstanceId;
+  try {
+    return _string(typeof source === 'function' ? source() : source, 160);
+  } catch {
+    return ''; // expected: identity is not ready yet (pre-boot / pre-DB) — never a sweep failure
+  }
+}
+
+/**
+ * P-5 sweep pull: a member that was offline during a roster push converges on its next sweep. Adopt
+ * only a strictly NEWER version (revision, then updatedAt, then `by` — machine-pool.isNewer); an
+ * equal or older one is ignored (the receiver answers with its own version, and the pusher decides).
+ * Self is never written into its own roster (db.js's replaceRosterMachines also refuses it).
+ */
+async function _maybePullRoster(machine, url, { deps = {}, fetchImpl, timeoutMs, peerHeaders = {} } = {}) {
+  const pool = _machinePool(deps);
+  if (!pool || typeof pool.hasPool !== 'function' || !pool.hasPool()) return null;
+  const pulled = await _pullRoster(url, { fetchImpl, timeoutMs, peerHeaders });
+  if (!pulled) return null;
+  if (typeof pool.isNewer !== 'function' || !pool.isNewer(pulled.version, pool.rosterVersion())) return null;
+
+  const self = _selfInstanceId(deps);
+  const members = pulled.members
+    .map((member) => ({
+      instanceId: _string(member && (member.instanceId || member.instance_id), 160),
+      urls: (Array.isArray(member && member.urls) ? member.urls : []).map((u) => _trimUrl(u)).filter(Boolean),
+    }))
+    .filter((member) => member.instanceId && member.instanceId !== self);
+
+  // Only PREVIOUS pool members may be deleted (a legacy env-token row is never one, P-8).
+  const removable = typeof pool.members === 'function' ? pool.members() : [];
+  await dispatchOwnerMutation(deps.db, 'replaceRosterMachines', [{ members, selfInstanceId: self, removable }], 'machine registry roster pull');
+  if (typeof pool.setRosterVersion === 'function') await pool.setRosterVersion(pulled.version);
+  if (typeof pool.setMembers === 'function') await pool.setMembers(members.map((member) => member.instanceId));
+  noteRegistryChanged();
+  return { version: pulled.version, members };
+}
+
+/** D-4: cache the manifest's executionHost block; a display/settings CHANGE is registry news. */
+function _cacheManifestHost(instanceId, host) {
+  const id = _string(instanceId, 160);
+  if (!id || !host) return;
+  const previous = _manifestHost.get(id) || null;
+  _manifestHost.set(id, host);
+  if (!previous) return; // a first read is not news (the registration already bumped the revision)
+  if (previous.displayName !== host.displayName || previous.favorite !== host.favorite
+    || previous.hidden !== host.hidden || previous.os !== host.os
+    || previous.arch !== host.arch || previous.hostname !== host.hostname) {
+    noteRegistryChanged();
+  }
+}
+
+/**
+ * WP-0 (S-2): cache the manifest's `build` block beside `_manifestHost` — written by the same single
+ * caller (the sweep), cleared by the same test seam. A build change is deliberately NOT registry
+ * news: it is a version stamp the fleet reconciler reads, not machine identity, and bumping the
+ * revision on every restart of every box would wake every snapshot reader for nothing.
+ */
+function _cacheManifestBuild(instanceId, build) {
+  const id = _string(instanceId, 160);
+  if (!id || !build) return;
+  _manifestBuild.set(id, build);
+}
+
+/** A box's logged-in flag -> the hub's three-state verdict (unknown for anything unexpected). */
+function _agentLoginState(signedIn) {
+  if (signedIn === true) return 'signed_in';
+  if (signedIn === false) return 'signed_out';
+  return 'unknown';
+}
+
+/**
+ * WP-3: read a box's own coding-CLI sign-in truth from ITS `/api/providers/login-state` (the route
+ * a signed-out box answers with `providers.<agent>.account.signedIn: false`). It NEVER throws and
+ * never reports anything but a three-state verdict: a non-2xx, an unparseable body, an unexpected
+ * shape and a transport throw all read `unknown` — only an explicit false is a refusal.
+ */
+async function _probeAgentAuth(url, options = {}) {
+  const fetched = await _getJsonBox(url, '/api/providers/login-state', options);
+  const unknown = { claude: 'unknown', codex: 'unknown' };
+  if (!fetched.ok) return unknown;
+  const providers = (fetched.body && typeof fetched.body === 'object' && fetched.body.providers) || {};
+  const signedInFor = (agent) => {
+    const entry = providers[agent];
+    if (!entry || typeof entry !== 'object') return undefined;
+    const account = entry.account;
+    return account && typeof account === 'object' ? account.signedIn : undefined;
+  };
+  return { claude: _agentLoginState(signedInFor('claude')), codex: _agentLoginState(signedInFor('codex')) };
+}
+
+/**
+ * WP-13b (D-15): the box's OWN available-agents answer, reduced to the one compact presence the hub
+ * surfaces — `{ dsh: boolean }`.
+ *
+ * The route (`GET /api/models/available-agents`) answers `agentCliCache.getAvailableAgents()`'s
+ * body: `{ ok, agents: { <agent>: { available, … } }, <agent>: boolean }`. This read keeps ONLY
+ * whether `dsh` is present; paths and every other agent are dropped at the door, so nothing the box
+ * printed about its filesystem is ever cached hub-side.
+ *
+ * Three outcomes, matching the sign-in/skills reads:
+ *   'block' — a 200 that carries an explicit dsh verdict: store the compact presence.
+ *   'keep'  — a failed read, a 404 (a box older than this route), a non-object/unparseable body, or
+ *             a body that names no dsh at all: KEEP the previous value (P3, "Unknown != Dead"). Only
+ *             an explicit answer is news; a silent box is never read as "the box lost dsh".
+ */
+async function _probeAgentAvailability(url, options = {}) {
+  const fetched = await _getJsonBox(url, '/api/models/available-agents', options);
+  if (!fetched.ok) return { state: 'keep' };
+  const presence = _dshPresenceFromBody(fetched.body);
+  if (!presence) return { state: 'keep' };
+  return { state: 'block', presence };
+}
+
+/**
+ * The `dsh` verdict in a `/api/models/available-agents` body, or null when the body carries none.
+ * Accepted shapes (the hub must not care which one its box serves): the route's own
+ * `{ dsh: <boolean>, agents: { dsh: { available } } }`, and the bare `{ agents: {…} }` / `{ dsh }`.
+ */
+function _dshPresenceFromBody(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return null;
+  const agents = body.agents && typeof body.agents === 'object' && !Array.isArray(body.agents) ? body.agents : null;
+  const detail = agents ? agents.dsh : undefined;
+  if (detail !== undefined) {
+    if (typeof detail === 'boolean') return { dsh: detail };
+    if (detail && typeof detail === 'object' && typeof detail.available === 'boolean') return { dsh: detail.available };
+    return null; // present but not a verdict — "no answer", never "not installed"
+  }
+  if (typeof body.dsh === 'boolean') return { dsh: body.dsh };
+  return null;
+}
+
+/**
+ * Store one box's agent presence. `noteRegistryChanged()` fires only when the SURFACED presence
+ * actually moved, exactly like the sign-in read above: a first read is not news (registration already
+ * bumped the revision), and an identical re-read under a newer `checkedAt` is not either.
+ */
+function _setAgentPresence(instanceId, presence, now) {
+  const id = _string(instanceId, 160);
+  if (!id || !presence) return null;
+  const previous = _agentPresence.get(id) || null;
+  const next = { presence: { dsh: presence.dsh === true }, checkedAt: now };
+  _agentPresence.set(id, next);
+  if (previous && previous.presence.dsh !== next.presence.dsh) noteRegistryChanged();
+  return next;
+}
+
+/**
+ * WP-7 (§6.5/AC-7a): read a box's OWN skill inventory from ITS `GET /api/agent-skills/inventory`.
+ *
+ * Never throws and never reports anything but the parsed body or null. A box running an older CTM
+ * answers 404, a silent box never answers, and an unparseable body is not an inventory — all three
+ * read "no inventory this time", which the caller answers with KEEP THE LAST VALUE. It is
+ * deliberately not "an empty inventory": that would claim the box lost every skill it had.
+ */
+async function _probeAgentSkills(url, options = {}) {
+  const fetched = await _getJsonBox(url, '/api/agent-skills/inventory', options);
+  if (!fetched.ok) return null;
+  const body = fetched.body;
+  return body && typeof body === 'object' && !Array.isArray(body) ? body : null;
+}
+
+/**
+ * WP-1 (§6.2/§6.1): read a box's OWN model availability from ITS `GET /api/models/availability`.
+ *
+ * Three outcomes, and the difference between them is the whole contract:
+ *   'block' — the box answered with a §6.1 body: store the derived §6.2 block.
+ *   'null'  — the box answered 404: it predates WP-1, so `models` is null and the row renders
+ *             exactly as it did before (AC-1e). Stamped, so a pre-WP-1 box is asked once per TTL.
+ *   'keep'  — anything else (silent box, non-JSON answer, transport throw): KEEP the previous block
+ *             and move only the stamp (the remote-skills WP-7 rule). Never blank a block we hold.
+ */
+async function _probeModelsAvailability(url, options = {}) {
+  const fetched = await _getJsonBox(url, '/api/models/availability', options);
+  if (fetched.ok) {
+    const body = fetched.body;
+    // A 200 that is not a §6.1 body (no `routes` array) is not an answer to this question: KEEP.
+    if (!body || typeof body !== 'object' || Array.isArray(body) || !Array.isArray(body.routes)) {
+      return { state: 'keep' };
+    }
+    return { state: 'block', block: _modelsBlockFrom(body) };
+  }
+  if (fetched.status === 404) return { state: 'null', block: null };
+  return { state: 'keep' };
+}
+
+/**
+ * §6.2: the block the machine row surfaces, derived from the box's §6.1 body. `usable` is the
+ * launch-able count the card states (enabled, and either keyed or a local runtime, and reachable);
+ * `unreachable` lists the enabled rows the box cannot get to; `delegate` mirrors the box's own
+ * /delegate picks with the verdict of the route each one names.
+ */
+function _modelsBlockFrom(body) {
+  const routes = (Array.isArray(body.routes) ? body.routes : []).filter((row) => row && typeof row === 'object');
+  const enabled = routes.filter((row) => row.enabled !== false);
+  const isOllama = (row) => _string(row.type, 60).toLowerCase() === 'ollama';
+  const usable = enabled.filter((row) => row.reach === 'reachable' && (row.keyed === true || isOllama(row))).length;
+  const unreachable = enabled
+    .filter((row) => row.reach === 'unreachable' || row.reach === 'no_server')
+    .map((row) => ({
+      id: _string(row.id, 200),
+      type: _string(row.type, 60),
+      origin: row.origin ? _string(row.origin, 300) : null,
+    }));
+  // WP-5 (§6.4/R-6): the box's own route list, so the hub can offer "Use on <box>" for the routes
+  // the box does NOT have and refuse one whose origin that same list calls unreachable. THREE fields
+  // only — id, origin and the reach verdict — never a name, a type, a credential flag or a key: the
+  // hub needs "does this box already have this id" and "can this box reach this origin", nothing
+  // else. A row with no id is not a route the hub can match, so it is skipped rather than surfaced
+  // as an empty id.
+  const routeRows = routes
+    .map((row) => ({
+      id: _string(row.id, 200),
+      origin: row.origin ? _string(row.origin, 300) : null,
+      reach: _string(row.reach, 20) || 'unknown',
+    }))
+    .filter((row) => row.id);
+  const delegate = (Array.isArray(body.delegateDefaults) ? body.delegateDefaults : [])
+    .filter((pref) => pref && typeof pref === 'object')
+    .map((pref) => ({
+      agent: _string(pref.agent, 20),
+      routeId: _string(pref.routeId, 200),
+      model: _string(pref.model, 200),
+      reach: _string(pref.reach, 20) || 'unknown',
+    }));
+  const nativeOf = (agent) => ({
+    signedIn: !!(body.native && body.native[agent] && body.native[agent].signedIn === true),
+  });
+  return {
+    checkedAt: _string(body.checkedAt, 60),
+    usable,
+    unreachable,
+    routes: routeRows,
+    delegate,
+    native: { claude: nativeOf('claude'), codex: nativeOf('codex') },
+  };
+}
+
+/**
+ * Store one box's availability block. `noteRegistryChanged()` fires only when the SURFACED block
+ * moved — a first read or a real change is news, an identical re-read under a newer `checkedAt` is
+ * not, or every 60 s tick would invalidate every reader's snapshot for nothing.
+ */
+function _setMachineModels(instanceId, block, now) {
+  const id = _string(instanceId, 160);
+  if (!id) return null;
+  const previous = _machineModels.get(id) || null;
+  const next = { block, checkedAt: now };
+  _machineModels.set(id, next);
+  if (!previous || JSON.stringify(previous.block) !== JSON.stringify(next.block)) noteRegistryChanged();
+  return next;
+}
+
+/** WP-1 §6.2: the box's availability block as this hub last read it, or null (never read / pre-WP-1). */
+function modelsFor(instanceId) {
+  const entry = _machineModels.get(_string(instanceId, 160));
+  return entry ? entry.block : null;
+}
+
+/**
+ * WP-7 (§6.5): the hub's own item list for one box platform, memoized for AGENT_AUTH_REFRESH_MS.
+ *
+ * `deps.buildAgentBundle` is injectable so a unit test never reads the real home; production falls
+ * back to WP-1's builder. A build failure is REPORTed and answered with null — "the hub cannot read
+ * its own skills" and "the hub has no skills" are DIFFERENT claims, and only the second one may
+ * rewrite a box's classification to `new_on_box`.
+ *
+ * @returns {Promise<{items: object[]}|null>}
+ */
+async function _hubItemsForPlatform(platform, { deps = {}, now = Date.now() } = {}) {
+  const key = _string(platform, 40) || 'unknown';
+  const cached = _hubItemCache.get(key) || null;
+  if (cached && now - cached.at < AGENT_AUTH_REFRESH_MS) return { items: cached.items };
+  const build = typeof deps.buildAgentBundle === 'function'
+    ? deps.buildAgentBundle
+    : require('./agent-bundle/build').buildAgentBundle;
+  try {
+    const bundle = await build({ targetPlatform: key });
+    const items = (bundle && Array.isArray(bundle.items) ? bundle.items : []).map((item) => ({
+      agent: item.agent, kind: item.kind, name: item.name, itemHash: item.itemHash,
+    }));
+    _hubItemCache.set(key, { items, at: now });
+    return { items };
+  } catch (error) {
+    // REPORT: a hub-side build fault leaves every box's `onBox` exactly as it was (see the caller).
+    errorSink.report('agent-skill-inventory-build', error);
+    return null;
+  }
+}
+
+/**
+ * WP-7 (§6.5/AC-7a): classify one box's inventory read. `boxSkills` come from the box, `baseItems`
+ * from the base the BOX reported (that is the design adjustment: the hub's push record is
+ * in-process, so classification survives a hub restart only if the box carries the base back).
+ *
+ * @returns {Promise<object[]|null>} the classification rows, or null when the hub could not read its
+ *          own skills — the caller then keeps the previous `onBox` rather than publishing a wrong one.
+ */
+async function _classifyInventory(inventory, { deps = {}, now = Date.now() } = {}) {
+  const boxSkills = Array.isArray(inventory.skills) ? inventory.skills : [];
+  // §6.5: only a box holding at least one UNMANAGED skill is worth the hub's own build — a box whose
+  // skills are all CTM's (AC-7d) has nothing to classify, so the hub never walks its own tree for it.
+  const unmanaged = boxSkills.some((skill) => skill && (skill.managed === null || skill.managed === undefined));
+  if (!unmanaged) return [];
+  const hub = await _hubItemsForPlatform(inventory.platform, { deps, now });
+  if (!hub) return null;
+  const baseItems = inventory.base && Array.isArray(inventory.base.items) ? inventory.base.items : [];
+  return bundleInventory.classifyBoxSkills({ hubItems: hub.items, baseItems, boxSkills });
+}
+
+/**
+ * Store one box's classification. `noteRegistryChanged()` fires when the SURFACED block actually
+ * moved — a first read (the row goes from "no inventory" to a review list) is news, an identical
+ * re-read with only a newer `checkedAt` is not, or every 15 s tick would invalidate every snapshot.
+ */
+function _setAgentSkills(instanceId, onBox, now) {
+  const id = _string(instanceId, 160);
+  if (!id) return null;
+  const previous = _agentSkills.get(id) || null;
+  const next = { onBox, checkedAt: now };
+  _agentSkills.set(id, next);
+  if (!previous || JSON.stringify(previous.onBox) !== JSON.stringify(next.onBox)) noteRegistryChanged();
+  return next;
+}
+
+function _rows(deps = {}) {
+  const db = deps.db;
+  if (!db || typeof db.listMachineRows !== 'function') return [];
+  return db.listMachineRows() || [];
+}
+
+function _isPinned(row = {}) {
+  // A row is pinned once something observed the box: registerMachine stamps both fields, and
+  // the probe loop keeps last_seen_at moving. A seeded row (enabled=0, never probed) is NOT
+  // pinned — it carries no evidence about which box its URL points at.
+  // S-9 (machine-pool-picker-pairing-dashboard-2026-10-24.html §9): a dead `row.pinned` field was
+  // dropped here — nothing ever wrote it. The picker's star is `favorite`, a machine-owned setting
+  // (D-4, lib/machine-self.js + the manifest), which is NOT this identity pin and never was.
+  return Number(row.lastSeenAt || row.last_seen_at || 0) > 0;
+}
+
+function _machineView(row = {}, deps = {}) {
+  const lastSeenAt = Number(row.lastSeenAt ?? row.last_seen_at ?? 0) || 0;
+  const enabled = Number(row.enabled ?? 1) !== 0;
+  const health = _string(row.health, 40) || 'unknown';
+  const instanceId = _string(row.instanceId || row.instance_id, 160);
+  // D-4 rev 2: the machine owns its display name / favorite / hidden and serves them in its own
+  // manifest, which the sweep caches per instance. The registry row's own label is the fallback for
+  // a box this hub has not read a manifest from yet.
+  const manifest = _manifestHost.get(instanceId) || null;
+  // WP-0 (S-1/S-2): the build stamp the box published in the manifest this hub last read, or null
+  // when it has never answered (never a fabricated {sha:''} row pretending to be a version).
+  const build = _manifestBuild.get(instanceId) || null;
+  // D-12/D-16: the box's own host sample (load, memory, disk, GPU, tasks) and its newest session
+  // create. `checkedAt` is the HUB clock stamp of the read, so a reader can label a stale number
+  // instead of showing it as current.
+  const stats = _hostStats.get(instanceId) || null;
+  const view = {
+    instanceId,
+    displayName: _string((manifest && manifest.displayName) || row.displayName || row.display_name, 200),
+    url: _string(row.url, 1000),
+    urls: (Array.isArray(row.urls) ? row.urls : []).map((u) => _string(u, 1000)).filter(Boolean),
+    walleUrl: _string(row.walleUrl || row.walle_url, 1000),
+    enabled,
+    health,
+    healthDetail: _string(row.healthDetail || row.health_detail, 500),
+    lastSeenAt,
+    createdAt: _string(row.createdAt || row.created_at, 60),
+    updatedAt: _string(row.updatedAt || row.updated_at, 60),
+    // D-4 rev 2: machine-owned settings, read from the last manifest this hub probed.
+    favorite: !!(manifest && manifest.favorite),
+    hidden: !!(manifest && manifest.hidden),
+    os: _string(manifest && manifest.os, 40),
+    arch: _string(manifest && manifest.arch, 40),
+    hostname: _string(manifest && manifest.hostname, 160),
+    // WP-0 (S-1): the box's own version truth (the manifest's build block), null until it answers.
+    build,
+    // null = this hub has never read a sample for this box (never a zeroed-out sample).
+    stats: stats ? { sample: stats.sample, checkedAt: stats.checkedAt } : null,
+    // WP-3 (§6.5) + WP-7 (§6.5/D-11) + WP-8 (§6.5): the skills push state for this box — the last
+    // successful tree and the last failure if there is one — together with the classification of the
+    // box's OWN skills (`onBox`, `checkedAt`) and this machine's per-machine plugin exclusions.
+    // null = this process neither pushed to, read this box, nor excluded anything for it.
+    skills: _skillsView(instanceId, deps),
+    // WP-1 (§6.2): the box's own model availability, read on the existing tick. null = this hub has
+    // never read it, or the box predates WP-1 — the row then renders exactly as it did before.
+    models: modelsFor(instanceId),
+    lastUsedAt: Number((stats && stats.sample && stats.sample.lastUsedAt) || 0) || 0,
+    // D-5: "unknown" until the box has ever answered; a disabled row is never a picker
+    // candidate, and only reachable/unhealthy ever render as cards.
+    pickerState: !enabled ? 'unknown' : health,
+    visible: enabled && (health === 'reachable' || health === 'unhealthy'),
+  };
+  // WP-3 rev 3 (§13.6 D-17): computed LAST, on the view itself, so the reason is derived from the
+  // exact `health` / `url` / `urls` the card renders (never a second, possibly-different reading).
+  // null for every row the hub cannot speak for; the Machines card then renders no note at all.
+  view.awayReason = machineAwayReason(view, deps);
+  return view;
+}
+
+function listMachines(deps = {}) {
+  const machines = _rows(deps).map((row) => _machineView(row, deps));
+  return { machines, hubNetworkSuspect: !!_lastSweep.hubNetworkSuspect };
+}
+
+/**
+ * Register (or re-point) a machine by URL. One successful manifest probe IS the pin (D-3):
+ * an unreachable box cannot be registered, because there would be nothing to key it on.
+ *
+ * @returns {{ok: true, machine: object}|{ok: false, code: string, error: string}}
+ */
+async function registerMachine({ url, displayName, walleUrl } = {}, deps = {}) {
+  const baseUrl = _trimUrl(url);
+  if (!baseUrl) return { ok: false, code: 'machine_url_required', error: 'url is required' };
+  const probe = await _probeManifest(baseUrl, {
+    fetchImpl: deps.fetchImpl || deps.fetch,
+    timeoutMs: Number(deps.timeoutMs || DEFAULT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS,
+    // P-8: registration probes the URL BEFORE the box's identity is known, so the caller's
+    // no-target builder is used (the pool-vs-env split needs an instanceId the hub does not have yet).
+    peerHeaders: _peerHeadersFor(deps)(''),
+  });
+  if (!probe.ok) return { ok: false, code: probe.code, error: probe.error };
+
+  const rows = _rows(deps).map((row) => _machineView(row));
+  const byUrl = rows.find((row) => row.url === baseUrl);
+  if (byUrl && byUrl.instanceId !== probe.instanceId && _isPinned(byUrl)) {
+    // The URL already points at a DIFFERENT box (or the forward was re-pointed). Refuse
+    // instead of silently re-keying: sessions already routed to the pinned id would move.
+    return {
+      ok: false,
+      code: 'machine_identity_mismatch',
+      error: `manifest ${probe.instanceId} != pinned ${byUrl.instanceId}`,
+    };
+  }
+  const byId = rows.find((row) => row.instanceId === probe.instanceId);
+  if (byId && byId.url !== baseUrl) {
+    return {
+      ok: false,
+      code: 'machine_identity_mismatch',
+      error: `instance ${probe.instanceId} already registered at ${byId.url}`,
+    };
+  }
+
+  // A seeded placeholder for this URL (enabled=0, never probed — S-19's env-seeded row) holds
+  // the URL but not the identity: replace it with the pinned row rather than keying on a guess.
+  if (byUrl && byUrl.instanceId !== probe.instanceId) {
+    await dispatchOwnerMutation(deps.db, 'deleteMachineRow', [byUrl.instanceId], 'machine registry reseed');
+  }
+  const now = _now(deps);
+  await dispatchOwnerMutation(deps.db, 'upsertMachineRow', [{
+    instanceId: probe.instanceId,
+    displayName: _string(displayName, 200) || probe.displayName || _hostLabel(baseUrl),
+    url: baseUrl,
+    walleUrl: _trimUrl(walleUrl),
+    enabled: 1,
+  }], 'machine registry register');
+  _missStreak.delete(probe.instanceId);
+  await dispatchOwnerMutation(deps.db, 'recordMachineProbe', [probe.instanceId, {
+    health: 'reachable', healthDetail: '', lastSeenAt: now,
+  }], 'machine registry register probe');
+  noteRegistryChanged();
+  const machine = _rows(deps).map((row) => _machineView(row)).find((row) => row.instanceId === probe.instanceId);
+  return { ok: true, machine: machine || null };
+}
+
+/**
+ * One probe sweep over every ENABLED machine. Zero machines ⇒ zero fetches (AC-0d).
+ *
+ * Grace walk (D-4/P3), per machine:
+ *   probe ok                     -> health 'reachable', last_seen_at = hub now
+ *   manifest ok, no instance id  -> health 'unhealthy' + detail (the box answered; it is
+ *                                   degraded, not gone — so last_seen_at still moves)
+ *   probe failed, 1st miss       -> previous health kept
+ *   probe failed, >= 2 misses    -> health 'unknown'
+ *   probe failed, no success for >= 60 s (hub clock) -> health 'unreachable'
+ * If EVERY enabled machine failed in this sweep, the sweep ADDITIONALLY reports
+ * hubNetworkSuspect: true — the UI's cue to say "network?" rather than "all machines down".
+ * The walk above still runs: a hub-side blip is absorbed by the grace thresholds (one miss
+ * keeps the previous health and writes nothing; `unreachable` needs 60 s of silence), while a
+ * genuine all-boxes-down (laptop away from home) converges to the truth instead of freezing a
+ * stale `reachable` forever.
+ *
+ * The returned {reachable, unknown, unreachable, unhealthy} are the RESULTING-HEALTH histogram
+ * (the same states lib/instance-sync-status.js reports through summarizeMachines), so a machine
+ * still inside its grace window counts under the health it kept, not under "missed".
+ */
+async function probeMachinesOnce(options = {}, deps = {}) {
+  const fetchImpl = options.fetchImpl || deps.fetchImpl || deps.fetch;
+  const timeoutMs = Number(options.timeoutMs || DEFAULT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+  const now = _now(deps);
+  const enabled = _rows(deps).map((row) => _machineView(row)).filter((row) => row.enabled);
+  if (!enabled.length) {
+    _lastSweep = { hubNetworkSuspect: false, at: now };
+    return { ok: true, probed: 0, reachable: 0, unknown: 0, unreachable: 0, unhealthy: 0, hubNetworkSuspect: false, results: [] };
+  }
+
+  // WP-3 rev 3 (§13.6 D-17): ONE away-path read per sweep, OFF the request path (see
+  // machineAwayReason). A missing proxy.sh IS the false answer; `deps` may inject the verdict.
+  _awayPathProxyExists = typeof deps.awayPathProxyExists === 'boolean'
+    ? deps.awayPathProxyExists
+    : await fs.promises.access(path.join(os.homedir(), '.config', 'ctm-away-path', 'proxy.sh'))
+      .then(() => true, () => false /* expected: an absent proxy.sh is the "no away path" answer */);
+
+  // P-8: one credential PER TARGET (pool secret for a member, the legacy env bearer for a box that
+  // never joined), so the header builder is resolved per machine, not once per sweep.
+  const headersFor = _peerHeadersFor(deps);
+  const results = await Promise.all(enabled.map(async (machine) => {
+    const probe = await _probeMachineManifest(machine, { fetchImpl, timeoutMs, peerHeaders: headersFor(machine.instanceId) });
+    // P-4: the URL that actually answered is the row's dial address from here on. A row whose
+    // pinned url went dead (an SSH forward torn down, a relay origin that took over) is re-pointed
+    // through the existing owner write path rather than re-dialled to nowhere every sweep.
+    if (probe.ok && _trimUrl(machine.url) !== probe.url) {
+      await dispatchOwnerMutation(deps.db, 'upsertMachineRow', [{
+        instanceId: machine.instanceId,
+        displayName: machine.displayName,
+        url: probe.url,
+        walleUrl: machine.walleUrl,
+        enabled: machine.enabled ? 1 : 0,
+      }], 'machine registry dial order');
+      noteRegistryChanged();
+    }
+    return { machine, probe };
+  }));
+
+  // P3 self-suspicion is ADVISORY: all boxes silent at once is most likely THIS host's network,
+  // so the sweep says so — but the grace walk below still runs (see the function comment).
+  const hubNetworkSuspect = results.every((row) => !row.probe.ok && row.probe.code === 'machine_unreachable');
+  _lastSweep = { hubNetworkSuspect, at: now };
+
+  const counts = { reachable: 0, unknown: 0, unreachable: 0, unhealthy: 0 };
+  for (const { machine, probe } of results) {
+    let health;
+    let detail = '';
+    if (probe.ok) {
+      health = 'reachable';
+      _missStreak.delete(machine.instanceId);
+    } else if (probe.code === 'machine_manifest_invalid') {
+      // Reachable-but-degraded: the box is up, so this is not a liveness miss either.
+      health = 'unhealthy';
+      detail = probe.error || 'manifest_invalid';
+      _missStreak.delete(machine.instanceId);
+    } else {
+      const misses = (_missStreak.get(machine.instanceId) || 0) + 1;
+      _missStreak.set(machine.instanceId, misses);
+      // The 60 s rule is measured FROM A RECORDED SUCCESS. A machine the hub has never seen
+      // answer (enabled before its first probe, so last_seen_at is still 0) is `unknown` after
+      // 2 misses — never `unreachable`, which would be a claim about silence we never measured
+      // (P3 Unknown != Dead).
+      const silentMs = machine.lastSeenAt > 0 ? now - machine.lastSeenAt : 0;
+      if (machine.lastSeenAt > 0 && silentMs >= UNREACHABLE_AFTER_MS) health = 'unreachable';
+      else if (misses >= UNKNOWN_AFTER_MISSES) health = 'unknown';
+      else health = machine.health;
+      // The detail describes the STANDING verdict: a first miss inside the grace window keeps
+      // the previous health AND its detail (so a blip sweep writes nothing at all).
+      detail = health === machine.health ? machine.healthDetail : (probe.error || '');
+    }
+    counts[_string(health, 40)] = (counts[_string(health, 40)] || 0) + 1;
+    const next = { health, healthDetail: detail, lastSeenAt: probe.ok || probe.code === 'machine_manifest_invalid' ? now : machine.lastSeenAt };
+    if (next.health !== machine.health || next.healthDetail !== machine.healthDetail || next.lastSeenAt !== machine.lastSeenAt) {
+      await dispatchOwnerMutation(deps.db, 'recordMachineProbe', [machine.instanceId, next], 'machine registry probe');
+      noteRegistryChanged();
+    }
+  }
+
+  // WP-3: the box's CLI sign-in truth, refreshed on the SAME tick as its health — never on its own
+  // timer. Only a box whose manifest probe just answered is asked: a box that did not answer tells
+  // us nothing about its CLIs, so its stored entry is left exactly as it was (never blanked to
+  // 'unknown', which would weaken a verdict we already hold). A refresh older than
+  // AGENT_AUTH_REFRESH_MS (or a box never fetched) is re-read; anything fresher is reused.
+  for (const { machine, probe } of results) {
+    if (!probe.ok) continue;
+    const machineHeaders = headersFor(machine.instanceId);
+    const url = probe.url || machine.url;
+    // D-4: the manifest we just read IS the machine's settings + host identity. Cached here so
+    // /api/machines serves the machine-owned displayName/favorite/hidden and os/arch/hostname.
+    _cacheManifestHost(machine.instanceId, probe.host);
+    // WP-0 (S-2): the same manifest read carries the box's build stamp; cache it here, the one place
+    // the hub learns it, so /api/machines can serve build.sha without a second fetch.
+    _cacheManifestBuild(machine.instanceId, probe.build);
+
+    const previous = _agentAuth.get(machine.instanceId);
+    if (!previous || now - previous.checkedAt >= AGENT_AUTH_REFRESH_MS) {
+      const probed = await _probeAgentAuth(url, { fetchImpl, timeoutMs, peerHeaders: machineHeaders });
+      _agentAuth.set(machine.instanceId, { ...probed, checkedAt: now });
+      // A sign-in CHANGE is registry news (a reader keeping a snapshot must re-read); a first read
+      // or an identical re-read is not.
+      if (previous && (previous.claude !== probed.claude || previous.codex !== probed.codex)) noteRegistryChanged();
+    }
+
+    // WP-13b (D-15): the box's OWN available-agents answer, on the SAME tick and under the SAME
+    // per-instance 60 s stamp as the sign-in read — the New Session card and the machine row need to
+    // know whether the box has the DeepSeek Harness BEFORE a create is dialled. A failed / 404 /
+    // unparseable read keeps the last value (P3): only an explicit answer moves it.
+    const presenceEntry = _agentPresence.get(machine.instanceId) || null;
+    if (!presenceEntry || now - presenceEntry.checkedAt >= AGENT_AUTH_REFRESH_MS) {
+      const read = await _probeAgentAvailability(url, { fetchImpl, timeoutMs, peerHeaders: machineHeaders });
+      if (read.state === 'block') _setAgentPresence(machine.instanceId, read.presence, now);
+      // A failed / 404 / unparseable read KEEPS the last value and moves only the stamp, so a box
+      // without this route is asked once a minute rather than on every tick. A FIRST failure stores
+      // nothing at all — there is no previous value to keep, and "never read" is the honest answer.
+      else if (presenceEntry) _setAgentPresence(machine.instanceId, presenceEntry.presence, now);
+    }
+
+    // WP-7 (§6.5/AC-7a/AC-7c): the box's own skill inventory, on the SAME tick and under the SAME
+    // per-instance 60 s stamp as the sign-in read — one pass over `results`, no timer of this
+    // module's own (AC-7b), so a box-created skill shows up on the row within 60 s + one 15 s tick.
+    const skillsEntry = _agentSkills.get(machine.instanceId) || null;
+    if (!skillsEntry || now - skillsEntry.checkedAt >= AGENT_AUTH_REFRESH_MS) {
+      const inventory = await _probeAgentSkills(url, { fetchImpl, timeoutMs, peerHeaders: machineHeaders });
+      if (inventory) {
+        const onBox = await _classifyInventory(inventory, { deps, now });
+        // null = the hub could not read its OWN skills: keep what we hold (a build fault is not news
+        // about the box), and move only the stamp so the next read waits its full 60 s.
+        _setAgentSkills(machine.instanceId, onBox === null ? (skillsEntry ? skillsEntry.onBox : null) : onBox, now);
+      } else if (skillsEntry) {
+        // An older box (404) or a failed read: KEEP the last value, no error noise — and move the
+        // stamp, so a box without this route is asked once a minute rather than on every tick.
+        _setAgentSkills(machine.instanceId, skillsEntry.onBox, now);
+      }
+    }
+
+    // WP-1 (§6.2/D-9): the box's OWN model availability, on the SAME tick and under its own per-
+    // instance ORIGIN_TTL_MS (10 min) stamp — the hub must not ask more often than the box would
+    // re-probe. A failure keeps the last block (never blanked), and a 404 records that the box
+    // predates WP-1 (models: null, the row renders exactly as today).
+    const modelsEntry = _machineModels.get(machine.instanceId) || null;
+    if (!modelsEntry || now - modelsEntry.checkedAt >= MODELS_REFRESH_MS) {
+      const read = await _probeModelsAvailability(url, { fetchImpl, timeoutMs, peerHeaders: machineHeaders });
+      if (read.state === 'block') _setMachineModels(machine.instanceId, read.block, now);
+      else if (read.state === 'null') _setMachineModels(machine.instanceId, null, now);
+      else if (modelsEntry) _setMachineModels(machine.instanceId, modelsEntry.block, now);
+    }
+
+    // D-12/P-5: the box's own host sample and its roster version, refreshed on the SAME tick and
+    // under the SAME per-instance 60 s stamp as the sign-in read — one pass over `results`, no
+    // timer of this module's own. Both are asked ONLY of a box whose manifest probe just answered
+    // (a silent box teaches us nothing, and its stored entry keeps its FROZEN checkedAt — AC-2b).
+    const statsEntry = _hostStats.get(machine.instanceId);
+    if (statsEntry && now - (statsEntry.attemptedAt || statsEntry.checkedAt) < HOST_STATS_REFRESH_MS) continue;
+    const sample = await _probeHostStats(url, { fetchImpl, timeoutMs, peerHeaders: machineHeaders });
+    // Two stamps: `attemptedAt` gates the 60 s refresh on every attempt; `checkedAt` moves ONLY when
+    // a sample arrived. A failed stats read keeps the sample we hold AND its old checkedAt, so the
+    // picker's "stats stale" (checkedAt older than 180 s) is driven by the stats read itself.
+    _hostStats.set(machine.instanceId, sample
+      ? { sample, checkedAt: now, attemptedAt: now }
+      : { sample: (statsEntry && statsEntry.sample) || null, checkedAt: (statsEntry && statsEntry.checkedAt) || 0, attemptedAt: now });
+    await _maybePullRoster(machine, url, { deps, fetchImpl, timeoutMs, peerHeaders: machineHeaders });
+  }
+
+  return {
+    ok: true,
+    probed: results.length,
+    reachable: counts.reachable || 0,
+    unknown: counts.unknown || 0,
+    unreachable: counts.unreachable || 0,
+    unhealthy: counts.unhealthy || 0,
+    hubNetworkSuspect,
+    results: results.map((row) => ({
+      instanceId: row.machine.instanceId,
+      url: row.machine.url,
+      ok: !!row.probe.ok,
+      ...(row.probe.ok ? {} : { error: row.probe.error }),
+    })),
+  };
+}
+
+/**
+ * Boot seeding (§8 WP-0 "seed-from-CTM_SYNC_PEERS"): every configured sync peer that is not
+ * already registered becomes a DISABLED machines row — visible, never probed, so the user can
+ * enable it in Settings → Machines (WP-5). Env is a seed, never an authority: it never
+ * auto-enables a machine.
+ */
+function seedMachinesFromSyncPeers(deps = {}) {
+  // The peer list (or the parser) is INJECTED by the caller — lib/hosted-sync-worker.js passes
+  // its own parsed peers. Requiring hosted-sync-worker from here would be a dependency cycle
+  // (it requires this module for the probe ride), so this module never imports it.
+  let peers = Array.isArray(deps.peers) ? deps.peers : [];
+  if (!peers.length && typeof deps.parseSyncPeers === 'function') {
+    try { peers = deps.parseSyncPeers(deps.env || process.env) || []; } catch { peers = []; } // expected: malformed CTM_SYNC_PEERS seeds nothing
+  }
+  if (!peers.length) return { seeded: 0, skipped: 0 };
+  // No owner handle (unit tests, receiver-only boots) ⇒ nothing to seed; report the peers as
+  // skipped rather than counting writes that never happened.
+  if (!deps.db || typeof deps.db.upsertMachineRow !== 'function') return { seeded: 0, skipped: peers.length };
+  const known = new Set();
+  for (const row of _rows(deps).map((r) => _machineView(r))) {
+    if (row.instanceId) known.add(row.instanceId);
+    if (row.url) known.add(row.url);
+  }
+  let seeded = 0;
+  let skipped = 0;
+  for (const peer of peers) {
+    const url = _trimUrl(peer.url);
+    if (!url) { skipped += 1; continue; }
+    const instanceId = _string(peer.instanceId, 160);
+    if ((instanceId && known.has(instanceId)) || known.has(url)) { skipped += 1; continue; }
+    const key = instanceId || `unpinned:${url}`;
+    if (known.has(key)) { skipped += 1; continue; }
+    // void: boot seeding is fire-and-forget by contract (a failed seed is a missing card the
+    // next boot retries, surfaced via status().machineSeed) — never a boot failure.
+    void dispatchOwnerMutation(deps.db, 'upsertMachineRow', [{
+      instanceId: key,
+      displayName: instanceId || _hostLabel(url),
+      url,
+      walleUrl: _trimUrl(peer.walleUrl),
+      enabled: 0,
+    }], 'machine registry seed');
+    known.add(key);
+    known.add(url);
+    seeded += 1;
+  }
+  if (seeded) noteRegistryChanged();
+  return { seeded, skipped };
+}
+
+/** S-30: the machines section of /api/instance/sync-status (lib/instance-sync-status.js). */
+function summarizeMachines(deps = {}) {
+  const machines = _rows(deps).map((row) => _machineView(row));
+  const summary = { count: machines.length, reachable: 0, unknown: 0, unreachable: 0, unhealthy: 0, hubNetworkSuspect: !!_lastSweep.hubNetworkSuspect };
+  for (const machine of machines) {
+    if (Object.prototype.hasOwnProperty.call(summary, machine.health)) summary[machine.health] += 1;
+  }
+  return summary;
+}
+
+/** WP-3: the box's last-read coding-CLI sign-in verdict, or null when it was never fetched. */
+function agentAuthFor(instanceId) {
+  return _agentAuth.get(_string(instanceId, 160)) || null;
+}
+
+/**
+ * WP-13b (D-15): the box's last-read agent presence as `{ dsh: { available: boolean } }`, or null
+ * when this process has never read it. The shape is the one `lib/remote-machine-create.js`'s
+ * `_boxAgentMissing` already accepts verbatim — the gate asks THIS module, never the box, so a
+ * never-read (or restarted) hub holds no verdict and refuses nothing (P3).
+ */
+function agentAvailabilityFor(instanceId) {
+  const entry = _agentPresence.get(_string(instanceId, 160));
+  if (!entry) return null;
+  return { dsh: { available: entry.presence.dsh === true } };
+}
+
+/**
+ * The §6.5 `skills` block for a machine row, or null when this process neither pushed nor read an
+ * inventory for this box.
+ *
+ * WP-7: the block is the UNION of the two module truths — the last push (§6.5, WP-3) and the last
+ * inventory read (D-11/§6.5). A box this hub has read an inventory from but never pushed to still
+ * gets a block (`sentTreeHash: null`, `onBox` populated); that is the WP-9 review card's whole input.
+ * `onBox`/`checkedAt` are null — never absent — when only one half is known, so a reader can always
+ * ask "have we read this box's own skills, and when".
+ */
+/**
+ * WP-8 (§6.5): this machine's per-machine plugin exclusions, read through the caller's provider.
+ *
+ * The provider is INJECTED (`deps.excludePluginsFor`), never imported: the real reader is a hub-side
+ * JSON file that lib/api/machines.js supplies, so this module — which must run in unit tests with a
+ * temp db and no data dir — never reads a real one, and a default `[]` keeps every existing caller
+ * (and the probe sweep) exactly as it was.
+ */
+function _excludePluginsFor(deps = {}, instanceId) {
+  const provider = deps.excludePluginsFor;
+  if (typeof provider !== 'function') return [];
+  try {
+    const list = provider(instanceId);
+    return Array.isArray(list) ? list.map((id) => _string(id, 200)).filter(Boolean) : [];
+  } catch {
+    return []; // expected: an unreadable exclusion file is "nothing excluded", never a failed row read
+  }
+}
+
+/**
+ * WP-9 (§9 S-9): the PLUGIN names the hub's last bundle carried — the Review dialog's exclusion
+ * checklist is "the plugins the hub sends to this box", so it is derived from the push entry's own
+ * item list (never re-read from disk here: this module holds no home dir, and the push already
+ * decided what went out).
+ *
+ * push.js's result reports `sentCount`/`heldBack` and NO items in this release, so the reader accepts
+ * every shape a caller could hand it (`items`, a nested `bundle.items`, or a plain `plugins` list) and
+ * otherwise falls back to what the PREVIOUS push recorded — the same rule the rest of
+ * `recordAgentBundlePush` follows: a failed push must not empty a checklist the user is looking at.
+ */
+function _pluginNamesFromItems(items) {
+  const names = new Set();
+  for (const item of Array.isArray(items) ? items : []) {
+    if (!item || typeof item !== 'object') continue;
+    if (_string(item.kind, 40) !== 'plugin') continue;
+    const name = _string(item.name, 200);
+    if (name) names.add(name);
+  }
+  return [...names].sort();
+}
+
+function _pluginsFromResult(result, previous) {
+  const nested = result && result.bundle && result.bundle.items;
+  if (Array.isArray(result && result.items)) return _pluginNamesFromItems(result.items);
+  if (Array.isArray(nested)) return _pluginNamesFromItems(nested);
+  if (Array.isArray(result && result.plugins)) {
+    const names = new Set();
+    for (const value of result.plugins) {
+      const name = _string(value && typeof value === 'object' ? value.name : value, 200);
+      if (name) names.add(name);
+    }
+    return [...names].sort();
+  }
+  return previous && Array.isArray(previous.plugins) ? previous.plugins.slice() : [];
+}
+
+/**
+ * WP-6 D-13 (§6.3): the per-phase timings a push result carries, kept as a COPY of only the keys
+ * whose values are finite numbers — anything else (a missing object, a string, NaN) is dropped, and
+ * a result that kept nothing reads as null. Recorded for an ok AND a failed push alike.
+ */
+function _pushTimingsOf(result) {
+  const source = result && result.timings;
+  if (!source || typeof source !== 'object') return null;
+  const kept = {};
+  let any = false;
+  for (const key of Object.keys(source)) {
+    const value = source[key];
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      kept[key] = value;
+      any = true;
+    }
+  }
+  return any ? kept : null;
+}
+
+function _skillsView(instanceId, deps = {}) {
+  const id = _string(instanceId, 160);
+  return _skillsViewFrom(_agentBundlePush.get(id) || null, _agentSkills.get(id) || null, _excludePluginsFor(deps, id));
+}
+
+/** The surfaced `skills` block, one shape for the row and the change check below. */
+function _skillsViewFrom(pushEntry, inventoryEntry = null, excludePlugins = []) {
+  const exclusions = Array.isArray(excludePlugins) ? excludePlugins : [];
+  // WP-8: a machine with nothing pushed, nothing read AND nothing excluded has no block at all — the
+  // pre-WP-8 `null` (and every test that pins it) is preserved. A machine with ONLY exclusions does get
+  // a block, because the exclusions are the hub's own setting for it and a reader must be able to see
+  // them before the first probe ever answers.
+  if (!pushEntry && !inventoryEntry && !exclusions.length) return null;
+  return {
+    sentTreeHash: pushEntry ? pushEntry.sentTreeHash : null,
+    sentAt: pushEntry ? pushEntry.sentAt : 0,
+    sentCount: pushEntry ? pushEntry.sentCount : 0,
+    heldBack: pushEntry ? pushEntry.heldBack : [],
+    pushError: pushEntry ? pushEntry.pushError : null,
+    // WP-6 D-13 (§6.3): the per-phase timings of the LAST push — which phase cost the caller its wait.
+    // Null when no push result has carried any yet (a pre-WP-6 push, or none at all).
+    pushTimings: pushEntry && pushEntry.pushTimings ? pushEntry.pushTimings : null,
+    onBox: inventoryEntry ? inventoryEntry.onBox : null,
+    checkedAt: inventoryEntry ? inventoryEntry.checkedAt : null,
+    excludePlugins: exclusions.slice(),
+    // WP-9 (§9 S-9): the plugin names the last push carried, for the Review dialog's checklist.
+    // Always an array on a non-null block, like `heldBack` — a reader never has to treat "no push"
+    // and "no plugins" differently.
+    plugins: pushEntry && Array.isArray(pushEntry.plugins) ? pushEntry.plugins.slice() : [],
+  };
+}
+
+/** A `skills` change is registry news — a reader keeping a snapshot must re-read (`noteRegistryChanged`). */
+function _skillsChanged(previousPush, nextPush, inventoryEntry) {
+  return JSON.stringify(_skillsViewFrom(previousPush, inventoryEntry))
+    !== JSON.stringify(_skillsViewFrom(nextPush, inventoryEntry));
+}
+
+/** WP-3: the last agent-skill push this process made to `instanceId`, or null when it made none. */
+function agentBundlePushFor(instanceId) {
+  return _skillsView(instanceId);
+}
+
+/**
+ * WP-3 (§6.5): record the outcome of a push to `instanceId`.
+ *
+ *   ok      -> sentTreeHash/sentAt/sentCount/heldBack describe THIS push and `pushError` is cleared.
+ *   ok:false-> the failure is stamped (`pushError: {code, message?, continuing?, at}` — `message` is
+ *              the box's own reason, `result.boxCode` from lib/agent-bundle/push.js D-4, present only
+ *              when the box named one; `continuing` is present only when the push outlived the
+ *              caller's wait and is still running, WP-6 D-11) while the last SUCCESSFUL push's fields
+ *              are kept: D-6's whole point is that a failed push changes nothing about the session,
+ *              and a reader must not conclude the box stopped running its last tree.
+ *
+ * WP-6 D-13: BOTH outcomes also store `pushTimings`, the per-phase timings the result carried (only
+ * keys whose values are finite numbers; null when it carried none). A LATE ok result (D-11) clears
+ * `pushError` exactly as an on-time one does — it is `recordAgentBundlePush` either way.
+ *
+ * Bumps the registry revision only when the surfaced `skills` block actually changed.
+ */
+function recordAgentBundlePush(instanceId, result, deps = {}) {
+  const id = _string(instanceId, 160);
+  if (!id) return null;
+  const now = _now(deps);
+  const previous = _agentBundlePush.get(id) || null;
+  const ok = !!(result && result.ok);
+  const pushTimings = _pushTimingsOf(result);
+  const next = ok
+    ? {
+      sentTreeHash: _string(result.treeHash, 80) || null,
+      sentAt: now,
+      sentCount: Number(result.sentCount) || 0,
+      heldBack: Array.isArray(result.heldBack) ? result.heldBack : [],
+      plugins: _pluginsFromResult(result, previous),
+      pushError: null,
+      pushTimings,
+    }
+    : {
+      sentTreeHash: previous ? previous.sentTreeHash : null,
+      sentAt: previous ? previous.sentAt : 0,
+      sentCount: previous ? previous.sentCount : 0,
+      heldBack: previous ? previous.heldBack : [],
+      plugins: _pluginsFromResult(result, previous),
+      pushError: {
+        code: _string(result && result.code, 80) || 'agent_bundle_push_network',
+        // D-4: the box's own reason, so the Machines line can say WHY (public/m/machines.js renders
+        // `error.message || error.code`). Absent when the box named nothing — never an empty string.
+        ...(_string(result && result.boxCode, 80) ? { message: _string(result.boxCode, 80) } : {}),
+        // WP-6 D-11: the push outlived the caller's wait and is running on — its result will arrive
+        // later. Present ONLY when true, like every other optional key here.
+        ...(result && result.continuing === true ? { continuing: true } : {}),
+        at: now,
+      },
+      pushTimings,
+    };
+  _agentBundlePush.set(id, next);
+  if (_skillsChanged(previous, next, _agentSkills.get(id) || null)) noteRegistryChanged();
+  return _skillsViewFrom(next, _agentSkills.get(id) || null);
+}
+
+/**
+ * D-12/D-16: the box's own host sample as this hub last read it, with the hub-clock stamp of that
+ * read, or null when the box has never been asked successfully. Readers use `checkedAt` to label a
+ * stale number (the UI says "stats stale" past 180 s) instead of printing it as current.
+ */
+function hostStatsFor(instanceId) {
+  const entry = _hostStats.get(_string(instanceId, 160));
+  return entry ? { sample: entry.sample, checkedAt: entry.checkedAt } : null;
+}
+
+/**
+ * WP-8 §6.5 step 7: drop the memoized hub item lists.
+ *
+ * A skill IMPORT changes the hub's own skill tree, and the cache is keyed only by platform — so without
+ * this the hub would keep classifying every OTHER box against the pre-import list for up to 60 s. The
+ * next read rebuilds from the (now-changed) tree.
+ */
+function invalidateHubItemCache() {
+  _hubItemCache.clear();
+}
+
+/**
+ * WP-8 §6.5 step 7: make ONE box's inventory stale, so the next probe tick re-reads it.
+ *
+ * The stamp (not the entry) is zeroed: the last classification stays visible — a reader sees the
+ * pre-import review list rather than a row blanked to "no skills" — and `probeMachinesOnce`'s
+ * `now - checkedAt >= AGENT_AUTH_REFRESH_MS` gate re-reads on the very next tick. Only a box this
+ * process has actually read is touched; a never-read box has nothing to invalidate.
+ */
+function markAgentSkillsStale(instanceId) {
+  const id = _string(instanceId, 160);
+  if (!id) return;
+  const entry = _agentSkills.get(id);
+  if (entry) _agentSkills.set(id, { ...entry, checkedAt: 0 });
+}
+
+/**
+ * WP-4: routes just deleted ON the box are gone from the hub's cached models block at once (the
+ * Review dialog re-reads the list right after the remove), and the stamp is zeroed so the very next
+ * tick re-reads the box's own truth. The block's other fields are left as read — only the box can
+ * say what the removal did to `usable` or to a /delegate pick that named a removed route.
+ */
+function forgetMachineModelRoutes(instanceId, routeIds) {
+  const id = _string(instanceId, 160);
+  const entry = id ? _machineModels.get(id) : null;
+  if (!entry) return;
+  const gone = new Set((Array.isArray(routeIds) ? routeIds : []).map((route) => _string(route, 200)));
+  const block = entry.block && Array.isArray(entry.block.unreachable)
+    ? { ...entry.block, unreachable: entry.block.unreachable.filter((row) => !gone.has(row.id)) }
+    : entry.block;
+  _machineModels.set(id, { block, checkedAt: 0 });
+  noteRegistryChanged();
+}
+
+function markMachineModelsStale(instanceId) {
+  const id = _string(instanceId, 160);
+  if (!id) return;
+  const entry = _machineModels.get(id);
+  if (!entry) return;
+  _machineModels.set(id, { block: entry.block, checkedAt: 0 });
+}
+
+/** Test seam: the miss counters, the agent-auth/host-stats/manifest caches, the skills push state
+ * (WP-3) and the skill inventory + hub-item cache (WP-7), the sweep verdict, and the hub's cached
+ * away-path read (WP-3 rev 3). */
+function _resetMachineRegistryStateForTests() {
+  _missStreak.clear();
+  _agentAuth.clear();
+  _agentPresence.clear();
+  _hostStats.clear();
+  _manifestHost.clear();
+  _manifestBuild.clear();
+  _agentBundlePush.clear();
+  _agentSkills.clear();
+  _machineModels.clear();
+  _hubItemCache.clear();
+  _lastSweep = { hubNetworkSuspect: false, at: 0 };
+  _awayPathProxyExists = null;
+}
+
+module.exports = {
+  UNREACHABLE_AFTER_MS,
+  UNKNOWN_AFTER_MISSES,
+  HEALTH_STATES,
+  AGENT_AUTH_REFRESH_MS,
+  HOST_STATS_REFRESH_MS,
+  agentAuthFor,
+  // WP-13b (D-15): the box's own available-agents presence as this hub last read it
+  // (`{ dsh: { available } }`), or null when it was never read — the gate in
+  // lib/remote-machine-create.js and the machine row both read it through here.
+  agentAvailabilityFor,
+  hostStatsFor,
+  listMachines,
+  // WP-3 rev 3 (§13.6 D-17): why an unreachable box cannot be dialled from here (`no_away_path` /
+  // `away_path_down`), or null when that is not this hub's to say. Read straight off the machine view.
+  machineAwayReason,
+  registryRevision,
+  noteRegistryChanged,
+  registerMachine,
+  probeMachinesOnce,
+  seedMachinesFromSyncPeers,
+  summarizeMachines,
+  // WP-3 (docs/remote-agent-skills-bundles-2026-10-25.html D-9/§6.5): the box's os (from the cached
+  // manifest host block) and the agent-skill push state the machine row surfaces.
+  manifestHostFor,
+  recordAgentBundlePush,
+  agentBundlePushFor,
+  // WP-8 (§6.5 step 7): after an import/retire/exclude-plugins write the hub's own item list and this
+  // box's inventory read are both stale — these two make the next read see the change.
+  invalidateHubItemCache,
+  markAgentSkillsStale,
+  // WP-5 (§6.4): after a copy the box has one more row — zero the stamp so the next tick re-reads
+  // it, without dropping the block (the removal path's `forgetMachineModelRoutes` drops ids, which
+  // is the wrong move for an ADDITION: the hub cannot say what the new row's verdict is).
+  markMachineModelsStale,
+  forgetMachineModelRoutes,
+  // WP-5 (§6.4): the §6.2 block as this hub last read it — the hub's "Use on <box>" list reads it
+  // to drop the routes the box already has and the origins the box already said it cannot reach.
+  modelsFor,
+  _resetMachineRegistryStateForTests,
+};