create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/lib/remote-machine-catalog.js

@@ -0,0 +1,1062 @@
+'use strict';
+
+// WP-6 (docs/remote-machine-hub-sessions-2026-10-22.html §5 D-2/D-6, §6.6, §7, §8 AC-6a..AC-6d,
+// §9 S-3/S-4/S-5/S-8/S-27): the hub-side REMOTE CATALOG — the one place that knows which ctm
+// session ids belong to a box, and the one place that builds the remote rows the hub's session list
+// carries.
+//
+// Three sources, one catalog (D-2: the box owns the session; the hub only mirrors):
+//   LIVE     the box's own session list, fetched over the WP-3 machine link (WS `list`, answered by
+//            the box's `sessions` frame — server.js handleList). Refreshed on every registry probe
+//            sweep (lib/hosted-sync-worker.js), on every link (re)connect, right after a forwarded
+//            create and right after a relayed kill. A catalog-initiated link open counts as ONE link
+//            user and is released as soon as the reply lands, so the link's existing 60 s idle close
+//            still applies — the catalog never keeps a machine link open.
+//   SYNC     the at-rest mirror rows the sync layer already materializes on the hub
+//            (`startup_tasks.park_reason='remote-mirror'`, db.js's ctm_session applier). These lag
+//            (a ~15 s tick) and never carry an IN-MEMORY lifecycle park (S-27): a box session parked
+//            by a lifecycle action still looks `running` to a DB reader until the next sync push. The
+//            live list is the truth while the box is reachable; this source is the DEGRADED look.
+//   CREATE   lib/remote-machine-create.js's in-memory `_mirrorSessions` — ids this hub forwarded a
+//            create for in THIS process (never persisted, OQ-4).
+//
+// D-3/S-5: machine labeling is the MINTED instance id plus the user-set display name. A hostname is
+// never used to label a machine (lib/recent-session-catalog-response.js overwrites every row's
+// hostname with the LOCAL hostname, so a hostname label would silently claim a box session is local).
+//
+// Everything is injectable for tests; nothing here opens a DB handle of its own.
+//
+// DEPENDENCY DIRECTION (lint ceiling: 0 cycles in lib/**): this module is a SINK. Every peer it
+// drives — the machine link, the create/mirror registry, the HTTP proxy, the origin facts, the db
+// owner client — transitively REQUIRES this module (the link's relay hook, the create post-hook and
+// the sync worker's sweep hook all call in here), so a lexical `require` of any of them would close
+// a dependency cycle and make load order load-bearing. They arrive instead through
+// `configureProduction()`, called ONCE by server.js — the composition root, which is outside lib —
+// with lazy getters, so nothing is loaded earlier than it is used. Tests inject the same names
+// through each function's `deps` argument. lib/machine-registry.js is the only direct require: it is
+// a leaf (nothing it requires reaches back here).
+
+const { boolFlag, registerFlag } = require('./env-flags');
+const { makeDedupeLogger } = require('../../shared/log-dedupe');
+
+// db.js's own spelling of an at-rest box mirror (db.js `_applySyncCtmSessionOnHandle`).
+const SYNC_MIRROR_PARK_REASON = 'remote-mirror';
+
+// The three routing fields §6.6/§8 add to EVERY session row the hub sends. Local rows carry them
+// EMPTY (the client never has to guess); remote rows carry the registry's values.
+const MACHINE_FIELDS = Object.freeze(['machine', 'machineName', 'machineHealth']);
+
+const DEFAULT_CATALOG_TIMEOUT_MS = 5000;
+// The registry read is a small indexed SELECT through the db owner; a couple of seconds of staleness
+// is harmless (the probe sweep is the only writer and it runs ~15 s apart) and it keeps the relay's
+// hot path — one lookup per relayable frame — off the database.
+const REGISTRY_TTL_MS = 2000;
+// The at-rest mirror scan is only paid for when the live catalog cannot answer (a hub restart, or an
+// unreachable box), and then at most once per TTL.
+const SYNC_MIRROR_TTL_MS = 15000;
+
+let _injected = null;
+// The production peers, as lazy getters (see the dependency-direction note above). null until
+// server.js wires them; a missing peer degrades ONE feature (see `_peer` call sites), never boot.
+let _wired = null;
+
+// machineInstanceId -> { rows, byId: Map<ctmSessionId, row>, fetchedAt, ok, error }
+const _catalogs = new Map();
+const _registryCache = { machines: [], at: 0, revision: null };
+// The remote half of the last merged list (machine health + the appended rows). `_finishBroadcast`
+// folds it into its no-op elision key, so a box-side change is never elided as "nothing changed"
+// just because the LOCAL rows did not move.
+let _lastMergeSignature = '';
+const _syncMirrorCache = { byId: new Map(), at: 0 };
+
+/** Test/host seam: override any production dependency (db, registry, link, clock, log). */
+function configure(deps) {
+  _injected = deps && typeof deps === 'object' ? deps : null;
+  // Each cache below holds a SNAPSHOT of ONE read. A caller supplying its own registry/db (the host
+  // seam, every unit test) must not be served a snapshot that a DIFFERENT caller's read cached —
+  // `machineRows` deliberately ignores its `deps` argument once a snapshot is warm, because in
+  // production every caller reads the same process-global registry through the same deps.
+  _registryCache.machines = [];
+  _registryCache.at = 0;
+  _registryCache.revision = null;
+  _syncMirrorCache.byId = new Map();
+  _syncMirrorCache.at = 0;
+}
+
+/**
+ * Production wiring (server.js, once at boot): `{ link, create, proxy, originFacts, db }`, each a
+ * function returning the module, so the requires happen in the composition root and stay lazy.
+ */
+function configureProduction(peers) {
+  _wired = peers && typeof peers === 'object' ? peers : null;
+}
+
+/**
+ * Resolve one peer: an explicit `deps` value wins (tests), then the production getter. Returns null
+ * when neither exists — every caller below treats null as "this one degraded feature is unavailable",
+ * because a hub that boots without a wired catalog must still serve its LOCAL session list.
+ */
+function _peer(name, d) {
+  if (d && d[name]) return d[name];
+  const getter = _wired ? _wired[name] : null;
+  if (typeof getter !== 'function') return null;
+  try {
+    return getter() || null;
+  } catch (error) {
+    _report(d, `${name} peer unavailable: ${error?.message || error}`);
+    return null;
+  }
+}
+
+function _string(value, max = 200) {
+  return String(value == null ? '' : value).trim().slice(0, max);
+}
+
+// Lazy: a pure unit test (merge/dedupe) must never load db.js / the owner client. `db` and
+// `registry` are therefore NOT part of this object — every reader below falls back to a lazy
+// `require`/peer only when a caller did not inject its own handle.
+function _productionDeps() {
+  return {
+    env: process.env,
+    now: () => Date.now(),
+    setTimeoutFn: global.setTimeout,
+    clearTimeoutFn: global.clearTimeout,
+    catalogTimeoutMs: DEFAULT_CATALOG_TIMEOUT_MS,
+    registryTtlMs: REGISTRY_TTL_MS,
+    syncMirrorTtlMs: SYNC_MIRROR_TTL_MS,
+    log: console,
+  };
+}
+
+/**
+ * "Is this id a session THIS instance owns locally right now?" — server.js wires it to
+ * server-state's getSession (the sessions Map covers live sessions AND deferred boot placeholders).
+ * 2026-10-23 live incident: a sync peer (DGX Spark) materialized this hub's synced startup tasks as
+ * its own sessions and listed them in its `sessions` broadcast; recordSessionList ingested the echo,
+ * the mirror lookup claimed the hub's OWN sessions as box mirrors, and the WP-3 relay intercept
+ * diverted their acks/bootstraps/attaches/input/wakes to the box — live sessions wedged read-only
+ * (ackedSeq=0 forever) and deferred restores never started. The §6.6 display merge already enforces
+ * "a local id always wins"; this lookup lets the RELAY enforce the same rule, before any source.
+ */
+function _localSessionLookup(d) {
+  if (typeof d.localSession === 'function') return d.localSession;
+  const lookup = _peer('localSession', d);
+  return typeof lookup === 'function' ? lookup : null;
+}
+
+/**
+ * "What instance id is THIS hub?" — server.js wires it to db.js's hosted identity. The ingest fence
+ * needs it to recognise a box row that echoes the hub's own sessions (D-1 clause b). Null when
+ * unwired: clause (b) then faults and passes the row (D-2 fail-open).
+ */
+function _localInstanceIdFn(d) {
+  if (typeof d.localInstanceId === 'function') return d.localInstanceId;
+  const fn = _peer('localInstanceId', d);
+  return typeof fn === 'function' ? fn : null;
+}
+
+/**
+ * "Is this instance id lineage-linked to ours?" (lib/host-identity.js's graph closure through
+ * db.js's isSameOwnerLineage, which defaults its second argument to this process's own id). A
+ * previous id of the SAME host — a re-mint — is the same owner, so its rows are echoes too (D-1).
+ */
+function _ownerLineageFn(d) {
+  if (typeof d.ownerLineage === 'function') return d.ownerLineage;
+  const fn = _peer('ownerLineage', d);
+  return typeof fn === 'function' ? fn : null;
+}
+
+/**
+ * "Does this hub's DURABLE ledger hold the id, and who owns it?" (db.js getCtmSessionOwnerRow —
+ * ctm_sessions, the one table that still knows an ENDED session). Clause (d) needs it because an
+ * ended session is in neither the sessions Map (clause c) nor startup_tasks, yet a box clone row
+ * for it can carry a restamped owner that defeats clause (b). Null when unwired: fail-open (D-2).
+ */
+function _ledgerOwnerFn(d) {
+  if (typeof d.ledgerOwner === 'function') return d.ledgerOwner;
+  const handle = d.db || _peer('db', d);
+  const fn = handle && typeof handle.getCtmSessionOwnerRow === 'function' ? handle.getCtmSessionOwnerRow : null;
+  return fn ? (id) => fn(id) : null;
+}
+
+/** The in-memory create registrations (lib/remote-machine-create.js), through the wired peer. */
+function _localMirrorLookup(d) {
+  if (typeof d.localMirror === 'function') return d.localMirror;
+  const create = _peer('create', d);
+  if (create && typeof create.getLocalMirrorSession === 'function') {
+    return (sessionId) => create.getLocalMirrorSession(sessionId);
+  }
+  return null;
+}
+
+function _d(overrides) {
+  return Object.assign({}, _productionDeps(), _injected || {}, overrides || {});
+}
+
+function _report(d, message) {
+  // REPORT (never throw): a catalog fault is a degraded remote list, not a hub fault.
+  try {
+    if (d && d.log && typeof d.log.warn === 'function') d.log.warn(`[remote-machine-catalog] ${message}`);
+  } catch { /* expected: an injected log that throws must not break the caller */ }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Machine registry snapshot
+// ---------------------------------------------------------------------------------------------
+
+/** The registered machines (registry view rows). Cached for `registryTtlMs` — see the note above. */
+function machineRows(deps = {}) {
+  const d = _d(deps);
+  const now = d.now();
+  const ttl = Number(d.registryTtlMs || REGISTRY_TTL_MS) || REGISTRY_TTL_MS;
+  let registry = null;
+  try {
+    registry = d.registry || require('./machine-registry');
+  } catch {
+    registry = null; // expected: a pure unit harness without the registry module -> zero machines
+  }
+  // A registry write (register/remove/seed/probe) invalidates the snapshot at once: within the TTL
+  // alone, a snapshot taken just before a registration hid the new machine from the relay lookup
+  // (live: a hub viewer's attach for a just-created box session fell through to "Session not found").
+  const revision = registry && typeof registry.registryRevision === 'function' ? registry.registryRevision() : null;
+  if (_registryCache.at && now - _registryCache.at < ttl && _registryCache.revision === revision) return _registryCache.machines;
+  let machines = [];
+  try {
+    const listed = registry ? (registry.listMachines({ db: d.db || _peer('db', d) }) || {}) : {};
+    machines = Array.isArray(listed.machines) ? listed.machines : [];
+  } catch {
+    machines = []; // expected: pre-boot / no machines table yet -> zero machines, zero remote rows
+  }
+  _registryCache.machines = machines;
+  _registryCache.at = now;
+  _registryCache.revision = revision;
+  return machines;
+}
+
+function _enabledMachines(d) {
+  return machineRows(d).filter((machine) => machine && machine.enabled !== false);
+}
+
+function _findMachine(machineId, d) {
+  const id = _string(machineId, 160);
+  if (!id) return null;
+  return machineRows(d).find((machine) => _string(machine.instanceId, 160) === id) || null;
+}
+
+/**
+ * "Is this instance id THIS host, or an id lineage-linked to it?" — the SAME test the WP-1
+ * ownership fences use (D-1 clause b), so a recent row and a sidebar row can never disagree about
+ * which sessions are local (D-10). A previous id of the SAME host (a re-mint) counts as local.
+ *
+ * FAIL-OPEN, in the D-2 direction: a peer that THROWS returns true ("treat as local"), which hides
+ * a chip rather than claiming a local session lives on a box. An unwired peer is not evidence of
+ * locality, so it returns false.
+ */
+function isLocalOwnerId(instanceId, deps = {}) {
+  const id = _string(instanceId, 160);
+  if (!id) return false;
+  const d = _d(deps);
+  try {
+    const localIdFn = _localInstanceIdFn(d);
+    if (localIdFn && _string(localIdFn(), 160) === id) return true;
+  } catch { return true; /* expected: a faulty identity peer hides the chip (D-2 fail-open) */ }
+  try {
+    const lineageFn = _ownerLineageFn(d);
+    if (lineageFn && lineageFn(id) === true) return true;
+  } catch { return true; /* expected: a faulty lineage peer hides the chip (D-2 fail-open) */ }
+  return false;
+}
+
+/**
+ * WP-3 D-9/D-10: the ONE cheap input both HTTP surfaces that MISS the §6.6 merge stamp from — the
+ * ENABLED registered machines (`{instanceId, displayName}`, never a hostname: D-3/S-5) and the set
+ * of ids that are LOCAL to this host (its own minted instance id, plus any registered id that is
+ * the same host or a lineage-linked re-mint of it — `isLocalOwnerId`).
+ *
+ * Pure in-memory registry snapshot (the `machineRows` TTL cache); nothing here opens a handle. A
+ * throwing identity/lineage peer degrades to "no extra local id" and is reported, never thrown.
+ *
+ * @returns {{machines: Array<{instanceId: string, displayName: string}>, localIds: string[]}}
+ */
+function machineTagInputs(deps = {}) {
+  const d = _d(deps);
+  const localIds = [];
+  try {
+    const localIdFn = _localInstanceIdFn(d);
+    const localId = localIdFn ? _string(localIdFn(), 160) : '';
+    if (localId) localIds.push(localId);
+  } catch (error) {
+    _report(d, `machineTagInputs: local identity unavailable: ${error?.message || error}`);
+  }
+  const machines = _enabledMachines(d)
+    .map((machine) => ({
+      instanceId: _string(machine.instanceId, 160),
+      displayName: _string(machine.displayName, 200),
+    }))
+    .filter((machine) => machine.instanceId);
+  // D-10: "names a registered machine AND is not this host or its lineage". The host's own id is
+  // local by definition (above); a REGISTERED machine that is lineage-linked to this host is the
+  // same owner, so its id joins `localIds` and can never label a row as a box.
+  for (const machine of machines) {
+    if (localIds.includes(machine.instanceId)) continue;
+    if (isLocalOwnerId(machine.instanceId, d)) localIds.push(machine.instanceId);
+  }
+  return { machines, localIds };
+}
+
+// ---------------------------------------------------------------------------------------------
+// WP-1 ingest fence (docs/remote-hub-ownership-fences-and-restore-skip-diagnostics-2026-10-23.html
+// §5 D-1/D-2/D-10, §8 AC-1a..AC-1e, §9 S-1)
+// ---------------------------------------------------------------------------------------------
+
+// The five rejection reasons, IN CLAUSE ORDER. `fenceFault` is not a clause: it counts a clause
+// that could not be evaluated (a throwing or unwired peer) — the D-2 fail-open path.
+const FENCE_REASONS = Object.freeze(['thirdPartyTag', 'ownEcho', 'localLive', 'localLedger', 'fenceFault']);
+// D-1 clause (b): first NON-EMPTY wins, in this order. Origin fields (`originInstanceId`,
+// `origin_instance_id`) are deliberately absent: origin is write-once provenance, not a live
+// ownership pointer (db.js:1438), so a session genuinely transferred TO the box keeps hub origin
+// and must keep working.
+const OWNER_FIELDS = Object.freeze([
+  'currentOwnerInstanceId', 'current_owner_instance_id', 'ownerInstanceId', 'owner_instance_id',
+]);
+
+// Cumulative, process-lifetime: machineInstanceId -> { thirdPartyTag, ownEcho, localLive, localLedger, fenceFault }.
+const _fenceCounters = new Map();
+const _fenceTotals = { thirdPartyTag: 0, ownEcho: 0, localLive: 0, localLedger: 0, fenceFault: 0 };
+
+// One warn per (machine, clause) window; the window's repeats collapse into a single summary line
+// (shared/log-dedupe.js, 600 s default — the state-sync-ack-stall precedent). The sink is the
+// CURRENT caller's `d.log` through the module's own `_report`, so this stays the same
+// "[remote-machine-catalog] …" channel as every other report here and never throws.
+// NOTE: the composite key separator must be the ESCAPED \u0000 form, never a raw control byte.
+let _fenceLogDeps = null;
+const _fenceLog = makeDedupeLogger({
+  logFn: (line) => _report(_fenceLogDeps, line),
+  formatSummary: (key, count, windowMs) => {
+    const [machine, reason] = String(key).split('\u0000');
+    return `ingest-fence: ${count} rows rejected by ${reason} from ${machine || '(unknown machine)'} in ${windowMs} ms (further repeats collapsed)`;
+  },
+});
+
+// D-10: the ONE kill switch, registered at its owner so the flag inventory sees it (read-pool-client
+// precedent). '0' restores the pre-WP-1 verbatim ingest; READ through lib/env-flags.js, never a raw
+// process.env read (the flag-read lint's rule).
+registerFlag('CTM_HUB_INGEST_FENCE', {
+  kind: 'bool',
+  default: true,
+  desc: 'Hub ingest fence (WP-1 D-1): drop box rows this hub does not own (third-party-tagged, echoing this hub\'s instance id or a lineage-linked id, naming a live local session, or held in this hub\'s own session ledger — ended sessions included). 0 restores verbatim ingest.',
+  expires: null,
+});
+
+function _fenceEnabled() {
+  try {
+    return boolFlag('CTM_HUB_INGEST_FENCE', true);
+  } catch { /* expected: an env-flags fault must not change ingest at all */ return true; }
+}
+
+/** D-1 clause (b): the row's owner field, first non-empty wins. '' when the row names no owner. */
+function _rowOwner(row) {
+  for (const field of OWNER_FIELDS) {
+    const owner = _string(row[field], 160);
+    if (owner) return owner;
+  }
+  return '';
+}
+
+function _bumpFenceCounters(machineId, rejection) {
+  let row = _fenceCounters.get(machineId);
+  if (!row) {
+    row = { thirdPartyTag: 0, ownEcho: 0, localLive: 0, localLedger: 0, fenceFault: 0 };
+    _fenceCounters.set(machineId, row);
+  }
+  for (const reason of FENCE_REASONS) {
+    const count = rejection[reason] || 0;
+    if (!count) continue;
+    row[reason] += count;
+    _fenceTotals[reason] += count;
+  }
+}
+
+function _reportFenceRejection(d, machineId, reason, id) {
+  _fenceLogDeps = d;
+  _fenceLog.log(`${machineId}\u0000${reason}`,
+    () => `ingest-fence rejected a row: clause=${reason} machine=${machineId || '(unnamed)'} id=${id} — the sender does not own it (D-1)`);
+}
+
+/**
+ * D-1, the four-clause drop predicate, FIRST MATCH WINS. Each clause is individually guarded
+ * (D-2): a clause that cannot be evaluated — a throwing peer, or one this process never wired —
+ * PASSES the row and counts `fenceFault`, exactly like the relay guard's fail-open. A catalog
+ * fault must degrade to "the remote list is slightly wrong", never to "a genuine box session lost
+ * its relay/display".
+ *
+ * @returns {{reason: string|null, faults: string[]}} the clause that dropped the row (null = keep)
+ */
+function _fenceVerdict(machineId, row, id, d) {
+  const faults = [];
+  // Clause 1 (D-1a): the SENDER itself tags the row as a third machine's (the box's own merge marks
+  // provenance — lib/remote-machine-catalog.js MACHINE_FIELDS). No peer, so no fault path in
+  // practice; the guard is structural.
+  try {
+    const tag = _string(row.machine, 160);
+    if (tag && tag !== machineId) return { reason: 'thirdPartyTag', faults };
+  } catch { faults.push('thirdPartyTag'); /* expected: an unreadable row never drops and never throws */ }
+
+  // Clause 2 (D-1b): the row's OWNER names this hub, or an id lineage-linked to it. Identity-based,
+  // so it holds for a phantom id that is not (yet) in the sessions Map — the §9 S-2/S-3 case.
+  try {
+    const owner = _rowOwner(row);
+    const localIdFn = owner ? _localInstanceIdFn(d) : null;
+    const lineageFn = owner ? _ownerLineageFn(d) : null;
+    if (owner && (!localIdFn || !lineageFn)) faults.push('ownEcho');
+    if (owner) {
+      const localId = localIdFn ? _string(localIdFn(), 160) : '';
+      if (localId && owner === localId) return { reason: 'ownEcho', faults };
+      if (lineageFn && lineageFn(owner) === true) return { reason: 'ownEcho', faults };
+    }
+  } catch { faults.push('ownEcho'); /* expected: a faulty identity/lineage peer fails OPEN (D-2) */ }
+
+  // Clause 3 (D-1c): the id is a session THIS instance already holds locally (live or a deferred
+  // boot placeholder). The belt to clause 2's braces, and the only clause that can fire for an
+  // older box that sends no owner field at all.
+  try {
+    const localSession = _localSessionLookup(d);
+    if (!localSession) faults.push('localLive');
+    else if (localSession(id)) return { reason: 'localLive', faults };
+  } catch { faults.push('localLive'); /* expected: a faulty local-lookup fails OPEN (D-2) */ }
+
+  // Clause 4 (D-1d, the ENDED-session hole distributed-10 reported): this hub's durable ledger
+  // (ctm_sessions) holds the id as its OWN — owner blank (pre-multi-machine rows are local by
+  // definition, db.js:15665 precedent), this instance, or lineage-linked. An ended session is in
+  // neither the sessions Map nor startup_tasks, and a file-cloned box lists it with owner fields
+  // restamped to ITSELF, so clauses 2 and 3 both miss it. A ledger row owned by the SENDER (a
+  // session genuinely transferred to the box) passes — ownership, never origin, decides (D-1b).
+  try {
+    const ledgerFn = _ledgerOwnerFn(d);
+    if (!ledgerFn) faults.push('localLedger');
+    else {
+      const ledger = ledgerFn(id);
+      if (ledger && ledger.exists) {
+        const owner = _string(ledger.currentOwner, 160);
+        if (!owner) return { reason: 'localLedger', faults };
+        const localIdFn = _localInstanceIdFn(d);
+        const lineageFn = _ownerLineageFn(d);
+        if (!localIdFn || !lineageFn) faults.push('localLedger');
+        const localId = localIdFn ? _string(localIdFn(), 160) : '';
+        if (localId && owner === localId) return { reason: 'localLedger', faults };
+        if (lineageFn && lineageFn(owner) === true) return { reason: 'localLedger', faults };
+      }
+    }
+  } catch { faults.push('localLedger'); /* expected: a faulty ledger/identity peer fails OPEN (D-2) */ }
+
+  return { reason: null, faults };
+}
+
+/** The cumulative ingest-fence counters (the pending-client-registry snapshot() shape). */
+function ingestFenceCounters() {
+  const byMachine = {};
+  for (const [machineId, row] of _fenceCounters) byMachine[machineId] = { ...row };
+  return { byMachine, total: { ..._fenceTotals } };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Live catalog
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Store a box's session list. Exported because the link also calls it for the box's UNSOLICITED
+ * `sessions` broadcasts (the box re-broadcasts its list on every session-list change), which is the
+ * cheapest possible freshness signal for the hub's sidebar.
+ *
+ * WP-1: rows the SENDER does not own are dropped here (the four D-1 clauses, first match wins) and
+ * tallied — see `_fenceVerdict` and `ingestFenceCounters()`.
+ *
+ * @returns {{rows: Array, byId: Map, fetchedAt: number, ok: true,
+ *            rejected?: {thirdPartyTag: number, ownEcho: number, localLive: number, localLedger: number, fenceFault: number}}}
+ *          `rejected` is present only when at least one counter is non-zero.
+ */
+function recordSessionList(machineInstanceId, rows, deps = {}) {
+  const d = _d(deps);
+  const machineId = _string(machineInstanceId, 160);
+  const byId = new Map();
+  const clean = [];
+  // WP-1 (D-1): the fence runs HERE, on the one choke point above every consumer of catalog rows
+  // (§9 S-1), before the id-dedupe ever sees the row. Flag off (D-10) = the pre-WP-1 verbatim loop.
+  const fencing = _fenceEnabled();
+  const rejected = { thirdPartyTag: 0, ownEcho: 0, localLive: 0, localLedger: 0, fenceFault: 0 };
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (!row || typeof row !== 'object') continue;
+    const id = _string(row.id || row.sessionId, 200);
+    // Deduped by ctm session id: the box listing one id twice must not produce two hub rows.
+    if (!id || byId.has(id)) continue;
+    if (fencing) {
+      const { reason, faults } = _fenceVerdict(machineId, row, id, d);
+      if (faults.length) rejected.fenceFault += faults.length;
+      if (reason) {
+        rejected[reason] += 1;
+        _reportFenceRejection(d, machineId, reason, id);
+        continue;
+      }
+    }
+    byId.set(id, row);
+    clean.push(row);
+  }
+  const entry = { rows: clean, byId, fetchedAt: d.now(), ok: true };
+  if (rejected.thirdPartyTag || rejected.ownEcho || rejected.localLive || rejected.localLedger || rejected.fenceFault) {
+    entry.rejected = rejected;
+    _bumpFenceCounters(machineId, rejected);
+  }
+  if (machineId) _catalogs.set(machineId, entry);
+  _notifyChanged(d);
+  return entry;
+}
+
+/**
+ * Ask the hub to re-broadcast its session list (the wired `onChange` peer: the DEBOUNCED
+ * broadcastSessionList). Cheap to over-call: an unchanged merge has an unchanged signature, so the
+ * broadcast is elided.
+ */
+function _notifyChanged(d) {
+  const onChange = _peer('onChange', d);
+  if (typeof onChange !== 'function') return;
+  try { onChange(); } catch (error) { _report(d, `onChange failed: ${error?.message || error}`); }
+}
+
+/** The remote half of the last merge ('' with zero machines) — see _lastMergeSignature. */
+function lastMergeSignature() {
+  return _lastMergeSignature;
+}
+
+function catalogFor(machineInstanceId) {
+  return _catalogs.get(_string(machineInstanceId, 160)) || null;
+}
+
+/** The ids the latest catalog holds for a registered machine (a Set; empty when never fetched). */
+function catalogSessionIds(machineInstanceId) {
+  const entry = catalogFor(machineInstanceId);
+  return entry ? new Set(entry.byId.keys()) : new Set();
+}
+
+/**
+ * S-3/AC-6a: fetch one machine's LIVE session list over the WP-3 machine link.
+ *
+ * Never throws and never rejects: an unreachable box, a missing credential or a link that never
+ * answers all resolve to `{ok:false}` and leave the previous catalog (if any) in place, which is
+ * what degrades a dropped box to its sync-mirror look instead of emptying the sidebar.
+ */
+async function fetchCatalog(machineOrId, deps = {}) {
+  const d = _d(deps);
+  try {
+    const row = machineOrId && typeof machineOrId === 'object' ? machineOrId : _findMachine(machineOrId, d);
+    if (!row) return { ok: false, code: 'machine_unknown' };
+    const machineId = _string(row.instanceId, 160);
+    if (!machineId) return { ok: false, code: 'machine_unknown' };
+    if (row.enabled === false) return { ok: false, code: 'machine_disabled' };
+    if (_string(row.health, 40) !== 'reachable') return { ok: false, code: 'machine_unreachable' };
+    const link = _peer('link', d);
+    if (!link || typeof link.openLink !== 'function' || typeof link.requestSessionList !== 'function') {
+      // Degraded, never a throw: an unwired catalog must not break a create/sweep caller.
+      return { ok: false, code: 'machine_unreachable', error: 'catalog_link_not_wired' };
+    }
+    const opened = link.openLink(row, d);
+    if (!opened) return { ok: false, code: 'machine_unreachable' };
+    const reply = await link.requestSessionList(opened, d);
+    if (!reply || !reply.ok) {
+      return { ok: false, code: (reply && reply.code) || 'machine_unreachable', error: (reply && reply.error) || '' };
+    }
+    const entry = recordSessionList(machineId, reply.rows, d);
+    return { ok: true, machineInstanceId: machineId, rowCount: entry.rows.length, fetchedAt: entry.fetchedAt };
+  } catch (error) {
+    // REPORT via the return value; the caller (a sweep or a fire-and-forget hook) decides.
+    _report(d, `catalog fetch failed: ${error?.message || error}`);
+    return { ok: false, code: 'machine_unreachable', error: _string(error?.message || error, 300) };
+  }
+}
+
+/**
+ * The probe-sweep hook (lib/hosted-sync-worker.js, where the sweep result is available — never a
+ * second timer). Every ENABLED machine the sweep judged `reachable` gets a live list; a machine the
+ * sweep judged otherwise keeps whatever catalog it had, so its rows degrade to the sync-mirror look.
+ */
+function refreshAll(deps = {}) {
+  const d = _d(deps);
+  const enabled = _enabledMachines(d);
+  const reachable = enabled.filter((machine) => _string(machine.health, 40) === 'reachable');
+  if (!reachable.length) {
+    // Zero machines (the single-machine install) stays silent; registered-but-all-down re-broadcasts.
+    if (enabled.length) _notifyChanged(d);
+    return Promise.resolve({ ok: true, refreshed: 0 });
+  }
+  return Promise.all(reachable.map((machine) => fetchCatalog(machine, d)))
+    .then((results) => {
+      // A sweep can flip a machine's health with no new list (a dropped box): re-broadcast so the
+      // sidebar degrades to the mirror look now, not at the next unrelated local change.
+      _notifyChanged(d);
+      return { ok: true, refreshed: results.filter((result) => result && result.ok).length, results };
+    })
+    .catch((error) => {
+      _report(d, `catalog sweep failed: ${error?.message || error}`);
+      return { ok: false, refreshed: 0, error: _string(error?.message || error, 300) };
+    });
+}
+
+/** Link (re)connect hook: the box just said hello, so ask it for its list on this very link. */
+function onLinkReady(link, deps = {}) {
+  const d = _d(deps);
+  const machineId = _string(link && link.machineInstanceId, 160);
+  if (!machineId) return Promise.resolve({ ok: false, code: 'machine_unknown' });
+  const row = _findMachine(machineId, d);
+  if (!row || row.enabled === false || _string(row.health, 40) !== 'reachable') {
+    return Promise.resolve({ ok: false, code: 'machine_unreachable' });
+  }
+  return fetchCatalog(row, d);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Sync mirrors (at-rest)
+// ---------------------------------------------------------------------------------------------
+
+function _readSyncMirrorRows(d) {
+  const byId = new Map();
+  try {
+    const handle = d.db || _peer('db', d);
+    if (!handle || typeof handle.listStartupTasks !== 'function') return byId;
+    // includeParked/includeRemoteOwned: an at-rest box mirror IS a parked row owned by the box —
+    // the restore-path defaults filter exactly these out, which is why they are named here.
+    const tasks = handle.listStartupTasks({ includeParked: true, includeRemoteOwned: true }) || [];
+    for (const task of tasks) {
+      if (_string(task.park_reason, 60) !== SYNC_MIRROR_PARK_REASON) continue;
+      const id = _string(task.ctm_session_id || task.session_id, 200);
+      const machineInstanceId = _string(task.current_owner_instance_id || task.origin_instance_id, 160);
+      if (!id || !machineInstanceId) continue;
+      byId.set(id, { machineInstanceId, task });
+    }
+  } catch {
+    // expected: pre-boot / a database without startup_tasks -> no sync mirrors, which under-claims
+  }
+  return byId;
+}
+
+function _syncMirrorIndex(d) {
+  const now = d.now();
+  const ttl = Number(d.syncMirrorTtlMs || SYNC_MIRROR_TTL_MS) || SYNC_MIRROR_TTL_MS;
+  if (!_syncMirrorCache.at || now - _syncMirrorCache.at >= ttl) {
+    _syncMirrorCache.byId = _readSyncMirrorRows(d);
+    _syncMirrorCache.at = now;
+  }
+  return _syncMirrorCache.byId;
+}
+
+/** The degraded (parked-look) row a box session gets while its machine is not serving live state. */
+function _mirrorSessionRow(sessionId, task, machine, health) {
+  const row = task || {};
+  const id = _string(sessionId || row.ctm_session_id || row.session_id, 200);
+  const type = _string(row.type, 40) || 'pty';
+  return {
+    id,
+    type,
+    session_type: type,
+    runtime_type: type,
+    label: _string(row.label, 400),
+    // S-27/D-4: `row.title` was a dead read — the mirrored row IS a startup_tasks row, and that table
+    // has no `title` column (db.js ~6749-6756), so every parked hub row carried title:'' and a client
+    // that prefers `title` over `label` showed nothing. The sync payload's task object is built from
+    // `_startupTaskRow` (startup_tasks columns only, db.js ~3150) and the applier persists only
+    // startup_tasks columns (db.js ~2728), so there is no box-side title field on the wire: the row's
+    // own label is the box's name for it, and that is what `title` must carry.
+    title: _string(row.label, 400),
+    cwd: _string(row.cwd, 4000),
+    cmd: _string(row.cmd, 4000),
+    // The at-rest mirror's status IS 'parked' (db.js's applier writes exactly that for a row whose
+    // owner is another instance), and the lifecycle fields below are the client's parked card.
+    status: 'parked',
+    lifecycleState: 'parked',
+    parkedAt: _string(row.parked_at, 60),
+    parkReason: SYNC_MIRROR_PARK_REASON,
+    executionHostInstanceId: _string(row.current_owner_instance_id || row.origin_instance_id, 160),
+    createdAt: _string(row.created_at, 60),
+    // §6.6/D-3: the machine tag. `machineName` is the registry DISPLAY NAME — never a hostname (S-5).
+    machine: _string(machine.instanceId, 160),
+    machineName: _string(machine.displayName, 200),
+    machineHealth: _string(health || machine.health, 40) || 'unknown',
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// The read seam (WP-3's intercept calls this for every relayable frame)
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * S-3/S-27/§7: which machine owns this ctm session id — the UNION of the three sources above, and
+ * the single read seam lib/remote-machine-link.js's pre-dispatch hook consults (through
+ * lib/remote-machine-create.js's `getMirrorSessionMachine`).
+ *
+ * Precedence: this process's forwarded creates (newest knowledge) > the live catalog > the at-rest
+ * sync mirror. A machine that is not registered can never claim an id, so an unregistered owner
+ * keeps today's observe-only behaviour.
+ *
+ * @returns {{machineInstanceId: string, machineName: string, health: string, source: string, at: number}|null}
+ */
+function getMirrorSessionMachine(ctmSessionId, deps = {}) {
+  const id = _string(ctmSessionId, 200);
+  if (!id) return null;
+  const d = _d(deps);
+  // A LOCAL session id always wins (see _localSessionLookup — the 2026-10-23 relay-hijack incident):
+  // whatever a box lists or a mirror row says, a session this instance holds in its own sessions Map
+  // is never a mirror, so its WS plane (acks, bootstraps, input, wakes) stays on the local handlers.
+  const localSession = _localSessionLookup(d);
+  if (localSession) {
+    try {
+      if (localSession(id)) return null;
+    } catch { /* expected: a local-lookup fault must fail OPEN — a genuine box session keeps its relay */ }
+  }
+  const localMirrorFn = _localMirrorLookup(d);
+  const local = localMirrorFn ? localMirrorFn(id) : null;
+  if (local && local.machineInstanceId) {
+    const machine = _findMachine(local.machineInstanceId, d);
+    // A registration removed while the process still holds the map entry no longer claims relaying:
+    // an unregistered owner keeps today's behaviour (S-7).
+    if (!machine || machine.enabled === false) return null;
+    return {
+      machineInstanceId: _string(machine.instanceId, 160),
+      machineName: _string(machine.displayName, 200),
+      health: _string(machine.health, 40) || 'unknown',
+      source: 'create',
+      at: Number(local.at) || 0,
+    };
+  }
+  // Zero registered machines ⇒ no catalog and no mirror scan at all: the relay path is exactly
+  // today's (one map miss) for every frame of every local session.
+  const machines = _enabledMachines(d);
+  if (!machines.length) return null;
+  for (const machine of machines) {
+    const entry = catalogFor(machine.instanceId);
+    if (entry && entry.byId.has(id)) {
+      return {
+        machineInstanceId: _string(machine.instanceId, 160),
+        machineName: _string(machine.displayName, 200),
+        health: _string(machine.health, 40) || 'unknown',
+        source: 'catalog',
+        at: entry.fetchedAt,
+      };
+    }
+  }
+  const mirror = _syncMirrorIndex(d).get(id);
+  if (mirror) {
+    const machine = machines.find((row) => row.instanceId === mirror.machineInstanceId);
+    if (machine) {
+      return {
+        machineInstanceId: _string(machine.instanceId, 160),
+        machineName: _string(machine.displayName, 200),
+        health: _string(machine.health, 40) || 'unknown',
+        source: 'sync-mirror',
+        at: 0,
+      };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------------------------
+// §6.6 merge (S-3/S-4, AC-6c)
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * The remote rows this hub adds to its session list, one per box session, deduped by ctm session id.
+ * A REACHABLE machine contributes its LIVE rows (its own state); anything else contributes the
+ * at-rest sync mirror rows for that machine — the parked look plus `machineHealth` (§6.6, AC-6a's
+ * degradation half) — and, for a session with no mirror row, its last good live row in that look.
+ */
+function remoteRows(deps = {}) {
+  const d = _d(deps);
+  const out = [];
+  const seen = new Set();
+  for (const machine of _enabledMachines(d)) {
+    const entry = catalogFor(machine.instanceId);
+    const live = (_string(machine.health, 40) === 'reachable' && entry && entry.ok) ? entry.rows : null;
+    if (live) {
+      for (const row of live) {
+        const id = _string(row.id || row.sessionId, 200);
+        if (!id || seen.has(id)) continue; // AC-6c: never two rows for one session
+        seen.add(id);
+        out.push({
+          ...row,
+          machine: _string(machine.instanceId, 160),
+          machineName: _string(machine.displayName, 200),
+          machineHealth: 'reachable',
+        });
+      }
+      continue;
+    }
+    for (const row of mirrorRowsForMachine(machine, d)) {
+      const id = _string(row.id, 200);
+      if (!id || seen.has(id)) continue;
+      seen.add(id);
+      out.push(row);
+    }
+    // No at-rest mirror for a session (a hub with no sync peer has none at all): its last good
+    // live row stands in, in the same parked look, so a box going down never makes its sessions
+    // vanish from the hub — the unreachable chip promises "its last known state".
+    for (const row of (entry && entry.ok && Array.isArray(entry.rows)) ? entry.rows : []) {
+      const id = _string(row && (row.id || row.sessionId), 200);
+      if (!id || seen.has(id)) continue;
+      seen.add(id);
+      out.push({
+        ...row,
+        status: 'parked',
+        lifecycleState: 'parked',
+        parkReason: SYNC_MIRROR_PARK_REASON,
+        machine: _string(machine.instanceId, 160),
+        machineName: _string(machine.displayName, 200),
+        machineHealth: _string(machine.health, 40) || 'unknown',
+      });
+    }
+  }
+  return out;
+}
+
+function mirrorRowsForMachine(machine, deps = {}) {
+  const d = _d(deps);
+  const machineId = _string(machine && machine.instanceId, 160);
+  if (!machineId) return [];
+  const out = [];
+  for (const [id, entry] of _syncMirrorIndex(d)) {
+    if (entry.machineInstanceId !== machineId) continue;
+    out.push(_mirrorSessionRow(id, entry.task, machine, machine.health));
+  }
+  return out;
+}
+
+/**
+ * The §6.6 merge seam for the hub's session-list projection (server.js `handleList` /
+ * `_finishBroadcast`).
+ *
+ * BYTE-IDENTITY (the lead's rule): with ZERO registered machines this returns the caller's own array
+ * — same reference, no fields added, the payload is indistinguishable from today's. With machines
+ * registered, local rows gain the three routing fields EMPTY (the client never has to guess) and the
+ * remote rows are appended. A LOCAL session id always wins: it is pre-seeded into the dedupe set, so
+ * a box row can never shadow a local session.
+ */
+function mergeSessionRows(localRows, deps = {}) {
+  const rows = Array.isArray(localRows) ? localRows : [];
+  const d = _d(deps);
+  const machines = _enabledMachines(d);
+  if (!machines.length) { _lastMergeSignature = ''; return rows; }
+  const seen = new Set();
+  for (const row of rows) {
+    const id = _string(row && (row.id || row.sessionId), 200);
+    if (id) seen.add(id);
+  }
+  const out = rows.map((row) => ({
+    ...(row && typeof row === 'object' ? row : {}),
+    machine: '',
+    machineName: '',
+    machineHealth: '',
+  }));
+  for (const remote of remoteRows(d)) {
+    const id = _string(remote.id || remote.sessionId, 200);
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    out.push(remote);
+  }
+  _lastMergeSignature = JSON.stringify([machines.map((m) => `${m.instanceId}:${m.health}`), out.slice(rows.length)]);
+  return out;
+}
+
+// ---------------------------------------------------------------------------------------------
+// S-8 / §7 — lifecycle routing for a mirror session
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * The registry row a mirror lookup resolved to (null when the machine is gone/disabled).
+ *
+ * Exported as `machineRowForMirror` for WP-2's forwarder (docs/remote-session-image-upload-
+ * forwarding-2026-10-24.html §6): the mirror lookup answers WHO owns an id, this answers WHERE to
+ * send it (and whether the box is known to be down). Same function, same behaviour — the internal
+ * name stays for the lifecycle forwarder below.
+ */
+function _machineRowForMirror(mirror, d) {
+  if (!mirror) return null;
+  const machine = _findMachine(mirror.machineInstanceId, d);
+  if (!machine || machine.enabled === false || !_string(machine.url, 1000)) return null;
+  return machine;
+}
+
+/**
+ * §7 ownership routing (AC-6b), HTTP half: `POST /api/sessions/:id/(park|revive|pin|wake)` for a
+ * MIRROR session must be acted on the BOX, never locally — the hub's `parkSession`/`getSession`
+ * would otherwise be asked about a session it does not have (OQ-4: mirror sessions are deliberately
+ * NOT in the hub's sessions Map).
+ *
+ * @returns {Promise<boolean>} true = the request was answered here (do NOT run the local handler)
+ */
+async function forwardLifecycleRequest(req, res, sessionId, action, deps = {}) {
+  const d = _d(deps);
+  const verb = _string(action, 20);
+  if (!['park', 'revive', 'pin', 'wake'].includes(verb)) return false;
+  const mirror = getMirrorSessionMachine(sessionId, d);
+  if (!mirror) return false; // a LOCAL session takes the byte-identical existing path
+  const machine = _machineRowForMirror(mirror, d);
+  const machineName = _string(machine ? machine.displayName : mirror.machineName, 200);
+  if (!machine) {
+    _sendJson(res, 503, {
+      ok: false, code: 'machine_unreachable', error: `Machine ${machineName || mirror.machineInstanceId} is not available`,
+      machine: mirror.machineInstanceId, machineName,
+    });
+    return true;
+  }
+  if (_string(machine.health, 40) === 'unreachable') {
+    // Never a local act: a lifecycle action on a session the hub does not own is refused, not
+    // silently applied to a same-id session on this host (which does not exist anyway).
+    _sendJson(res, 503, {
+      ok: false, code: 'machine_unreachable', error: `Machine ${machineName} is unreachable`,
+      machine: mirror.machineInstanceId, machineName,
+    });
+    return true;
+  }
+  const proxy = _peer('proxy', d);
+  if (!proxy || typeof proxy.forwardMachineHttp !== 'function') {
+    _sendJson(res, 503, {
+      ok: false, code: 'machine_unreachable', error: `Machine ${machineName} could not be reached`,
+      machine: mirror.machineInstanceId, machineName,
+    });
+    return true;
+  }
+  const result = await proxy.forwardMachineHttp({
+    machine: machine,
+    pathname: `/api/sessions/${encodeURIComponent(mirror && sessionId)}/${verb}`,
+    method: 'POST',
+    body: '',
+    deps: d,
+  });
+  if (!result || !result.ok) {
+    _sendJson(res, 503, {
+      ok: false, code: (result && result.code) || 'machine_unreachable',
+      error: (result && result.error) || `Machine ${machineName} is unreachable`,
+      machine: mirror.machineInstanceId, machineName,
+    });
+    return true;
+  }
+  // The box's own status and body are returned VERBATIM (§6.5): the client parses the box's answer
+  // exactly as it parses the local one.
+  if (!res.headersSent) {
+    res.writeHead(Number(result.status) || 502, { 'Content-Type': result.contentType || 'application/json' });
+    res.end(result.text || '');
+  }
+  return true;
+}
+
+function _sendJson(res, status, payload) {
+  const body = JSON.stringify(payload);
+  if (res.headersSent) return true;
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+  return true;
+}
+
+/**
+ * S-8/S-25 (AC-6d) action half: the machine a stopped session should be RESUMED on, when its origin
+ * instance is a registered, reachable box. '' / not-registered / not-reachable ⇒ null (today's flow).
+ */
+function resumeMachineFor(ctmSessionId, deps = {}) {
+  const d = _d(deps);
+  const id = _string(ctmSessionId, 200);
+  if (!id) return null;
+  const machines = _enabledMachines(d);
+  if (!machines.length) return null;
+  let originId = '';
+  try {
+    const facts = _peer('originFacts', d);
+    if (!facts || typeof facts.resumeOriginFacts !== 'function') return null;
+    // `resumeOriginFacts` is the ONE relative-origin rule (lib/resume-origin-facts.js): it already
+    // knows how to compare the row's origin against THIS instance's lineage, and it now also carries
+    // the raw origin id, which is the key the machine registry is pinned by (D-3).
+    const looked = facts.resumeOriginFacts(d.db || null, id, {}) || {};
+    if (looked.origin !== 'other_instance') return null;
+    originId = _string(looked.originInstanceId, 160);
+  } catch {
+    return null; // expected: no DB / pre-boot -> today's flow, byte-identical
+  }
+  if (!originId) return null;
+  const machine = machines.find((row) => _string(row.instanceId, 160) === originId) || null;
+  if (!machine || _string(machine.health, 40) !== 'reachable') return null;
+  return { instanceId: _string(machine.instanceId, 160), displayName: _string(machine.displayName, 200) };
+}
+
+/** S-8/S-25 action half: resume this session ON the box, through the WP-2 allowlist (no widening —
+ *  a resume needs `id`, `cmd`, `args`, `cwd`, `label`/`title`, all of which are already on it). */
+async function forwardResumeOnMachine({ launch, machine } = {}, deps = {}) {
+  const d = _d(deps);
+  const row = (machine && machine.url ? machine : null) || _findMachine(machine && machine.instanceId, d);
+  if (!row || !_string(row.url, 1000)) return { ok: false, code: 'machine_unreachable', error: 'machine_url_missing' };
+  const create = _peer('create', d);
+  if (!create || typeof create.filterRemoteCreateForward !== 'function' || typeof create.sendRemoteCreate !== 'function') {
+    return { ok: false, code: 'machine_unreachable', error: 'catalog_create_peer_not_wired' };
+  }
+  const payload = create.filterRemoteCreateForward({
+    id: launch && launch.id,
+    cmd: launch && launch.cmd,
+    args: launch && launch.args,
+    cwd: launch && launch.cwd,
+    label: launch && launch.title,
+    title: launch && launch.title,
+  });
+  const result = await create.sendRemoteCreate({ machineUrl: row.url, payload, deps: d });
+  if (!result.ok) return { ok: false, code: result.code, error: result.error };
+  const frame = result.frame || {};
+  const sessionId = _string(frame.id || payload.id, 200);
+  if (sessionId && typeof create.recordMirrorSession === 'function') create.recordMirrorSession(sessionId, row);
+  return {
+    ok: true,
+    sessionId: sessionId || _string(payload.id, 200),
+    machineInstanceId: _string(row.instanceId, 160),
+    machineName: _string(row.displayName, 200),
+  };
+}
+
+/** Test seam: every cache and the injection slot are module state. */
+function _resetForTests() {
+  _catalogs.clear();
+  _registryCache.machines = [];
+  _registryCache.at = 0;
+  _registryCache.revision = null;
+  _syncMirrorCache.byId = new Map();
+  _syncMirrorCache.at = 0;
+  _injected = null;
+  _lastMergeSignature = '';
+  // WP-1: the fence counters are process-cumulative, so a test that resets the module must reset
+  // them too or a later assertion reads an earlier test's tallies. (The log-dedupe WINDOW state is
+  // deliberately left alone: it only ever suppresses duplicate lines, never changes a verdict, and
+  // flushing it here would emit summaries into a resetting test's output.)
+  _fenceCounters.clear();
+  for (const reason of FENCE_REASONS) _fenceTotals[reason] = 0;
+}
+
+module.exports = {
+  SYNC_MIRROR_PARK_REASON,
+  MACHINE_FIELDS,
+  DEFAULT_CATALOG_TIMEOUT_MS,
+  configure,
+  configureProduction,
+  machineRows,
+  machineTagInputs,
+  isLocalOwnerId,
+  recordSessionList,
+  ingestFenceCounters,
+  catalogFor,
+  catalogSessionIds,
+  fetchCatalog,
+  refreshAll,
+  onLinkReady,
+  getMirrorSessionMachine,
+  // WP-2 (§6 step 3): the registry row behind a mirror lookup, for lib/remote-session-forward.js.
+  machineRowForMirror: _machineRowForMirror,
+  remoteRows,
+  mirrorRowsForMachine,
+  mergeSessionRows,
+  lastMergeSignature,
+  forwardLifecycleRequest,
+  resumeMachineFor,
+  forwardResumeOnMachine,
+  _resetForTests,
+};