create-walle 0.10.1 → 0.10.2

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

@@ -0,0 +1,749 @@
+'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 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 -> { 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();
+// 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 };
+// 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),
+  };
+}
+
+function _manifestDisplayName(body) {
+  return _manifestHostBlock(body).displayName;
+}
+
+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] : [];
+}
+
+// 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 };
+}
+
+/**
+ * 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();
+  }
+}
+
+/** 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')) };
+}
+
+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 = {}) {
+  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;
+  // 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;
+  return {
+    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),
+    // 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,
+    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'),
+  };
+}
+
+function listMachines(deps = {}) {
+  const machines = _rows(deps).map((row) => _machineView(row));
+  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: [] };
+  }
+
+  // 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);
+
+    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();
+    }
+
+    // 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;
+}
+
+/**
+ * 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;
+}
+
+/** Test seam: the miss counters, the agent-auth/host-stats/manifest caches and the sweep verdict. */
+function _resetMachineRegistryStateForTests() {
+  _missStreak.clear();
+  _agentAuth.clear();
+  _hostStats.clear();
+  _manifestHost.clear();
+  _lastSweep = { hubNetworkSuspect: false, at: 0 };
+}
+
+module.exports = {
+  UNREACHABLE_AFTER_MS,
+  UNKNOWN_AFTER_MISSES,
+  HEALTH_STATES,
+  AGENT_AUTH_REFRESH_MS,
+  HOST_STATS_REFRESH_MS,
+  agentAuthFor,
+  hostStatsFor,
+  listMachines,
+  registryRevision,
+  noteRegistryChanged,
+  registerMachine,
+  probeMachinesOnce,
+  seedMachinesFromSyncPeers,
+  summarizeMachines,
+  _resetMachineRegistryStateForTests,
+};