create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/session-context-locator.js

@@ -0,0 +1,742 @@
+'use strict';
+
+// WP-2 (docs/cross-machine-session-context-2026-10-31.html §5 R-3/R-4/R-5/R-8/R-11, §6.1, §9 S-14):
+// owner resolution + forwarding for session-memory reads.
+//
+// The defect this module fixes: `GET /api/ctm/session-memory/context` answered from THIS machine
+// only, so a session that lives on another pool member came back as a well-formed EMPTY envelope
+// with no hint that it exists elsewhere (observed M-5/I-5). The hub resolution order (R-3) is:
+//   (a) the directory (`getMirrorSessionMachine`) names an owner -> forward ONE GET to that owner;
+//   (b) else read locally                                       -> hit: label it and return;
+//   (c) else probe every dialable member IN PARALLEL under one deadline; first non-empty answer wins;
+//   (d) else found:false + `searched`, naming self and every member with a status.
+//
+// Every forwarded request carries `scope=local` (R-4/R-11): a receiver never forwards again. That is
+// the no-recursion invariant, and this module is its single owner (§7).
+//
+// No new ports and no new trust: the forward leg is the existing peer-bearer HTTP leg
+// (lib/remote-machine-proxy.js `forwardMachineHttp`), and the receiving route admits it with
+// `{ peerControl: true }` (lib/auth-rules.js, §6.2). All external calls go through the injectable
+// `deps` object below; production defaults are loaded lazily via require, so requiring this module
+// from a unit test never wires the machine registry, the proxy or the identity store.
+
+const os = require('node:os');
+
+const { boolFlag, createEnvFlags } = require('./env-flags');
+// RRF (D-6/P-5): the ONE reciprocal-rank damping constant the repo already shares with the
+// in-process fusion (lib/session-search-fusion.js:6-21) — imported, never re-typed.
+const { DEFAULT_RRF_K } = require('./session-search-fusion');
+// S-6: the one scatter-gather (a leaf module, shared with lib/fleet-session-lists.js).
+const { fanOutMembers } = require('./fleet-fanout');
+
+const SESSION_OWNER_FORWARD_TIMEOUT_MS = 10_000; // = remote-machine-proxy DEFAULT_TIMEOUT_MS (D-11)
+const SESSION_PROBE_DEADLINE_MS = 5_000;          // D-11
+const POOL_SEARCH_MEMBER_DEADLINE_MS = 5_000;     // D-11
+
+const SESSION_CONTEXT_PATHNAME = '/api/ctm/session-memory/context';
+const POOL_SEARCH_PATHNAME = '/api/ctm/session-memory/search';
+const POOL_SEARCH_DEFAULT_LIMIT = 10;
+const POOL_FLAG = 'CTM_SESSION_CONTEXT_POOL';
+
+// A machine display name is never fabricated: the registry's display name first, then the name the
+// directory reported, then the instance id (which is at least honest).
+function machineLabel(machine) {
+  const label = machine && (machine.displayName || machine.machineName);
+  return String(label || (machine && machine.instanceId) || '');
+}
+
+/**
+ * R-11: the pool flag, default ON in source (`!== '0'`), read through the one truthiness parser
+ * (lib/env-flags.js — flag-lint forbids raw `process.env.CTM_*` reads outside it). An injected env
+ * object (tests) is parsed by the same core, never by a second hand-rolled parser.
+ */
+function poolEnabled(env = process.env) {
+  if (!env || env === process.env) return boolFlag(POOL_FLAG, true);
+  return createEnvFlags({ env, warn: () => {} }).boolFlag(POOL_FLAG, true);
+}
+
+/**
+ * Who owns `sessionId`, as seen from THIS CTM (P-1: identity -> location, then route).
+ *
+ * @returns {{owner: 'self'} | {owner: 'machine', machine: object} | {owner: 'unknown'}}
+ * deps: { isLocalOwner?(id): boolean, getMirrorSessionMachine?(id), findMachine?(instanceId) }
+ */
+function locateSessionOwner(sessionId, deps = {}) {
+  const id = String(sessionId == null ? '' : sessionId).trim();
+  if (!id) return { owner: 'unknown' };
+  if (typeof deps.isLocalOwner === 'function' && deps.isLocalOwner(id)) return { owner: 'self' };
+  const getMirror = deps.getMirrorSessionMachine;
+  const mirror = typeof getMirror === 'function' ? getMirror(id) : null;
+  if (!mirror || !mirror.machineInstanceId) return { owner: 'unknown' };
+  const find = typeof deps.findMachine === 'function' ? deps.findMachine(mirror.machineInstanceId) : null;
+  // No registry row: still name the owner the directory reported (its forward will fail as
+  // `machine_unreachable` — a named failure, never a silent empty answer).
+  return {
+    owner: 'machine',
+    machine: find || {
+      instanceId: String(mirror.machineInstanceId),
+      displayName: String(mirror.machineName || ''),
+      health: String(mirror.health || 'unknown'),
+    },
+  };
+}
+
+/**
+ * R-3 hub order. `args` is the same object the context route builds today
+ * (lib/ctm-session-context-api.js), plus `scope`.
+ *
+ * Returns the local/owner context object with `location` (R-5), or
+ * `{ ok: true, found: false, sessions: [], messages: [], searched: [{ machine_id, machine_name, status }] }`,
+ * or `null` when the local read was deferred (the caller renders today's deferred envelope).
+ *
+ * deps: { readLocal(args) -> Promise<context|null>, forward(request) -> forwardMachineHttp result,
+ *         getMirrorSessionMachine(id), machineRows(), findMachine(id), localIdentity(), isLocalOwner(id),
+ *         now(), setTimeoutFn, clearTimeoutFn, probeDeadlineMs }
+ */
+async function readSessionContextAnywhere({ args = {}, excludeMachineId = '', env = process.env } = {}, deps = {}) {
+  const d = resolveDeps(deps);
+  const exclude = String(excludeMachineId || '').trim();
+  const ids = sessionIdsOf(args);
+
+  // Multi-id (or id-less) requests keep today's LOCAL-ONLY behaviour: WP-2 resolves ONE session id
+  // (the single-session read is the case the design measures). The answer is still labelled, so a
+  // caller can always see which machine answered.
+  if (ids.length !== 1) {
+    const local = await d.readLocal(args);
+    if (local == null) return null; // deferred off-thread read — today's deferred envelope
+    return { ...local, location: selfLocation(d, 'local') };
+  }
+
+  const sessionId = ids[0];
+  const pool = poolEnabled(env);
+  const scopeLocal = String(args.scope || '').trim() === 'local';
+  // R-3(a): the directory names an owner that is not the caller -> forward ONE GET to it.
+  if (pool && !scopeLocal) {
+    const located = locateSessionOwner(sessionId, {
+      isLocalOwner: d.isLocalOwner,
+      getMirrorSessionMachine: d.getMirrorSessionMachine,
+      findMachine: d.findMachine,
+    });
+    if (located.owner === 'machine' && located.machine.instanceId !== exclude) {
+      return forwardToMachine(located.machine, args, d, 'owner');
+    }
+  }
+
+  // R-3(b): read locally.
+  const local = await d.readLocal(args);
+  if (local == null) return null;
+  if (hasSessions(local)) {
+    // R-6 (WP-5, S-14): a local hit whose items arrived through transcript replication — the reader
+    // stamps `replica_origin` when the session's ONLY ingest cursors are `peer-sync:<origin>:<session>`
+    // rows — is not an owner hit. This machine holds a COPY, so the owner is asked instead and the
+    // copy is served only when the owner cannot be reached, labelled as the copy it is.
+    const origin = replicaOriginOf(local);
+    if (!origin) return { ...local, location: selfLocation(d, 'local') };
+    // `scope=local` is a caller saying "this machine's copy": served as-is, still labelled a replica.
+    if (!pool || scopeLocal) return replicaAnswer(local, d, origin, []);
+    const originRow = d.findMachine(origin);
+    const owner = replicaOwnerMachine(sessionId, origin, exclude, d, originRow);
+    if (!owner) return replicaAnswer(local, d, origin, [ownerEntry(origin, originRow, 'skipped')]);
+    const attempt = await attemptForward(owner, args, d);
+    if (attempt.error) return replicaAnswer(local, d, origin, [ownerEntry(origin, owner, attempt.status)]);
+    return withLocation(attempt.body, owner, 'owner');
+  }
+
+  // R-3(c)/(d). `scope=local` and a disabled pool both stop here: no forward, no probe.
+  if (!pool || scopeLocal) return missEnvelope([selfEntry(d, 'miss')]);
+  const members = otherMembers(d, exclude);
+  const probe = await probeMembers(members.filter(isDialable), args, d);
+  if (probe.hit) return probe.hit;
+  return missEnvelope(searchedEntries(d, members, probe.statuses));
+}
+
+/**
+ * R-7 pool search + merge. The LOCAL search always runs (it is the only leg that is always
+ * authoritative); every DIALABLE member is asked ONCE, in parallel, with `scope=local` (R-4: the
+ * receiver never fans out again), all under ONE deadline — a straggler is reported `timeout`, never
+ * waited for (P-2/P-3). Partial results are the contract: a member that fails is a per-machine
+ * status, and the merged answer still comes back.
+ *
+ * Returns `{ ok: true, results, machines }` (machines with self FIRST and every member named with its
+ * status), or `null` when the local read was deferred (the caller renders today's deferred envelope).
+ * Deliberately carries no wall clock (`ms`) in the result: nothing downstream may branch on latency.
+ *
+ * deps: { searchLocal(args) -> Promise<{ results }|null>, forward(request), machineRows(), findMachine,
+ *         localIdentity(), setTimeoutFn, clearTimeoutFn, searchDeadlineMs }
+ */
+async function searchSessionsAnywhere({
+  query = '', limit, excludeMachineId = '', scope = '', env = process.env,
+} = {}, deps = {}) {
+  const d = resolveDeps(deps);
+  const cap = clampSearchLimit(limit);
+  const local = await d.searchLocal({ query, limit: cap });
+  if (local == null) return null; // deferred off-thread search — today's deferred envelope
+  const localRows = Array.isArray(local.results) ? local.results : [];
+  const self = d.localIdentity();
+  const selfEntry = {
+    machine_id: String(self.instanceId || ''),
+    machine_name: String(self.displayName || ''),
+    status: 'ok',
+    count: localRows.length,
+  };
+  const selfList = {
+    machine_id: selfEntry.machine_id,
+    machine_name: selfEntry.machine_name,
+    owner: true,
+    rows: localRows,
+  };
+  const pool = poolEnabled(env);
+  const scopeLocal = String(scope || '').trim() === 'local';
+  const members = otherMembers(d, excludeMachineId);
+  // R-11/`scope=local`: no fan-out. The answer is still labelled, so self is always the first machine.
+  if (!pool || scopeLocal) {
+    return withLocalEnvelope(local, fusePoolResults([selfList], { limit: cap }), [selfEntry]);
+  }
+  const fanout = await searchMembers(members.filter(isDialable), { query, limit: cap }, d);
+  const machines = [selfEntry];
+  for (const row of members) {
+    machines.push({
+      machine_id: String(row.instanceId || ''),
+      machine_name: machineLabel(row),
+      // Never dialled (disabled/unreachable) is `skipped`, exactly like the context probe's `searched`.
+      status: isDialable(row) ? (fanout.statuses.get(row.instanceId) || 'timeout') : 'skipped',
+      count: fanout.counts.get(row.instanceId) || 0,
+    });
+  }
+  return withLocalEnvelope(local, fusePoolResults([selfList, ...fanout.lists], { limit: cap }), machines);
+}
+
+// §5 "what does not change": the local search envelope (op, query, db_path, active_source, …) is
+// kept as is; only `results` (now fused) and `count` change, and `machines` is added.
+function withLocalEnvelope(local, results, machines) {
+  const envelope = { ...local, ok: local.ok !== false, results, machines };
+  if (Object.prototype.hasOwnProperty.call(local, 'count')) envelope.count = results.length;
+  return envelope;
+}
+
+/**
+ * R-7/D-6 rank fusion over per-source rank order. Each list is `{ machine_id, machine_name, owner,
+ * rows }` with `rows` ALREADY in that machine's rank order; `score(row) = Σ 1/(k + rank)` (rank
+ * 1-based), so a row several machines found scores higher than the same row found once.
+ *
+ * Dedup key is `${session_id}\u0000${content_hash}` (§6.1): the OWNER's row wins the copy (its text
+ * is the one the session's own machine wrote), otherwise the higher-scoring one; scores always add.
+ * R-7 (WP-5): a row the reader marked `replica_origin` is a COPY, so it never displaces a machine
+ * that holds the item itself, and a surviving replica row carries `stale:true`.
+ * Output is sorted by score desc — ties broken deterministically (machine_id, session_id,
+ * message_index, content_hash) so a list reorder can never reorder the answer — sliced to `limit`,
+ * and every row carries a `machine_id`/`machine_name` (its own attribution when it already has one —
+ * a hub's answer already names the machine each row came from — else the list's) plus its 0-based
+ * output position as `rank` (order-preserving downstream consumers keep the fusion order).
+ * Pure and deterministic: no clock, no I/O, no mutation of the input rows.
+ */
+function fusePoolResults(lists, { limit, k = DEFAULT_RRF_K } = {}) {
+  const damping = Number.isFinite(Number(k)) && Number(k) >= 0 ? Number(k) : DEFAULT_RRF_K;
+  const merged = new Map();
+  for (const list of Array.isArray(lists) ? lists : []) {
+    if (!list || typeof list !== 'object') continue;
+    const machineId = String(list.machine_id == null ? '' : list.machine_id);
+    const machineName = String(list.machine_name == null ? '' : list.machine_name);
+    const owner = list.owner === true;
+    const rows = Array.isArray(list.rows) ? list.rows : [];
+    for (let index = 0; index < rows.length; index += 1) {
+      const row = rows[index];
+      if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
+      const contribution = 1 / (damping + (index + 1));
+      const replica = isReplicaRow(row);
+      const placed = {
+        ...row,
+        // The row's OWN attribution wins when it has one (a hub's answer already names the machine
+        // each row came from); the list's machine is the label for a row that carries none.
+        machine_id: rowMachineId(row, machineId),
+        machine_name: rowMachineName(row, machineName),
+        ...(replica ? { stale: true } : {}),
+      };
+      const key = fuseKey(row);
+      const existing = merged.get(key);
+      if (!existing) {
+        merged.set(key, {
+          row: placed, score: contribution, contribution, owner: owner && !replica, machineId, replica,
+        });
+        continue;
+      }
+      existing.score += contribution; // a row several lists carried adds every contribution
+      // R-7 (WP-5): a replica copy of an item never beats a machine that holds the item itself —
+      // the owner's row wins the duplicate whichever order the two arrived in.
+      if (existing.replica !== replica) {
+        if (existing.replica) {
+          existing.row = placed;
+          existing.owner = owner;
+          existing.contribution = contribution;
+          existing.machineId = machineId;
+          existing.replica = false;
+        }
+        continue;
+      }
+      if (owner && !replica && !existing.owner) {
+        existing.row = placed;
+        existing.owner = true;
+        existing.contribution = contribution;
+        existing.machineId = machineId;
+      } else if (!owner && !existing.owner
+        && (contribution > existing.contribution
+          || (contribution === existing.contribution && machineId < existing.machineId))) {
+        existing.row = placed;
+        existing.contribution = contribution;
+        existing.machineId = machineId;
+      }
+    }
+  }
+  const entries = [...merged.values()];
+  entries.sort((a, b) => (b.score - a.score)
+    || cmpText(a.row.machine_id, b.row.machine_id)
+    || cmpText(a.row.session_id, b.row.session_id)
+    || (toSortNumber(a.row.message_index) - toSortNumber(b.row.message_index))
+    || cmpText(a.row.content_hash, b.row.content_hash));
+  const n = Number(limit);
+  const capped = Number.isFinite(n) && n >= 0 ? Math.trunc(n) : entries.length;
+  return entries.slice(0, capped).map((entry, index) => ({ ...entry.row, rank: index }));
+}
+
+/** A row that already names its machine keeps that name; otherwise it inherits the list's. Pure. */
+function rowMachineId(row, listMachineId) {
+  const own = row && row.machine_id != null ? String(row.machine_id) : '';
+  return own || listMachineId;
+}
+
+function rowMachineName(row, listMachineName) {
+  const own = row && row.machine_id != null && String(row.machine_id) !== '' ? String(row.machine_name == null ? '' : row.machine_name) : '';
+  return own || listMachineName;
+}
+
+/** §6.1 dedup key: one row per (session, content). Pure. */
+function fuseKey(row) {
+  const sessionId = row && row.session_id != null ? row.session_id : '';
+  const contentHash = row && row.content_hash != null ? row.content_hash : '';
+  return `${String(sessionId)}\u0000${String(contentHash)}`;
+}
+
+/** Locale-independent string order (never `localeCompare`: its result depends on the host locale). */
+function cmpText(a, b) {
+  const x = String(a == null ? '' : a);
+  const y = String(b == null ? '' : b);
+  if (x < y) return -1;
+  return x > y ? 1 : 0;
+}
+
+function toSortNumber(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : Number.MAX_SAFE_INTEGER;
+}
+
+/**
+ * S-6 (docs/fleet-session-lists-hub-search-2026-11-01.html §5 D-5, §8 WP-1): one request per
+ * dialable member, all in flight at once, under ONE deadline. The scatter-gather itself now lives
+ * in the leaf lib/fleet-fanout.js `fanOutMembers` — this is the caller that gives it the pool-search
+ * leg (pathname, `scope=local` query, envelope parser), the search deadline and the member label.
+ */
+function searchMembers(machines, args, d) {
+  return fanOutMembers(machines, {
+    pathname: POOL_SEARCH_PATHNAME,
+    search: buildSearchParams(args),
+    parse: (result) => parseSearchEnvelope(result, args.limit),
+  }, {
+    forward: d.forward,
+    setTimeoutFn: d.setTimeoutFn,
+    clearTimeoutFn: d.clearTimeoutFn,
+    deadlineMs: d.searchDeadlineMs,
+    label: machineLabel,
+  });
+}
+
+/**
+ * A member's answer -> `{ error: false, rows }` | `{ error: true, status }`. Success is a 2xx JSON
+ * object carrying a `results` array; an over-long list is CAPPED (the member answered truthfully, its
+ * tail is simply beyond what this caller asked for). Anything else — non-2xx, malformed JSON, a body
+ * without `results` — is a named per-machine `error`, never a throw and never a silent empty answer.
+ */
+function parseSearchEnvelope(result, limit) {
+  if (!result || result.ok !== true) {
+    return { error: true, status: result && result.code === 'machine_unreachable' ? 'unreachable' : 'error' };
+  }
+  if (!(Number(result.status) >= 200 && Number(result.status) < 300)) return { error: true, status: 'error' };
+  let body;
+  try {
+    body = JSON.parse(String(result.text == null ? '' : result.text));
+  } catch {
+    /* expected: a non-JSON member body is reported as status 'error', never thrown at the caller */
+    return { error: true, status: 'error' };
+  }
+  if (!body || typeof body !== 'object' || Array.isArray(body) || !Array.isArray(body.results)) {
+    return { error: true, status: 'error' };
+  }
+  const cap = clampSearchLimit(limit);
+  return { error: false, status: 'ok', rows: body.results.slice(0, cap) };
+}
+
+/** R-4: an outbound search re-encodes the read with `scope=local` — the receiver never fans out. */
+function buildSearchParams({ query, limit } = {}) {
+  const params = new URLSearchParams();
+  params.set('q', String(query == null ? '' : query));
+  params.set('limit', String(clampSearchLimit(limit)));
+  params.set('scope', 'local');
+  return `?${params.toString()}`;
+}
+
+/** A search limit is a positive whole row count; junk/absent falls back to the pool default. */
+function clampSearchLimit(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return POOL_SEARCH_DEFAULT_LIMIT;
+  return Math.min(Math.trunc(n), 1000);
+}
+
+// ---------------------------------------------------------------------------------------------
+// R-3(a) — forward to the owner
+// ---------------------------------------------------------------------------------------------
+
+async function forwardToMachine(machine, args, d, source) {
+  const parsed = await attemptForward(machine, args, d);
+  if (parsed.error) {
+    // R-3(a) forward failure. WP-5's stale-replica fallback lives in readSessionContextAnywhere;
+    // here the failure is named (the machine, and why), never a silent empty envelope.
+    return missEnvelope([ownerEntry(machine.instanceId, machine, parsed.status)]);
+  }
+  return withLocation(parsed.body, machine, source);
+}
+
+/** One GET to `machine` and the envelope verdict — the R-6 owner attempt reads the failure itself. */
+function attemptForward(machine, args, d) {
+  return d.forward({
+    machine,
+    pathname: SESSION_CONTEXT_PATHNAME,
+    search: buildForwardSearch(args),
+    method: 'GET',
+  }).then((result) => parseForwardedEnvelope(result));
+}
+
+// ---------------------------------------------------------------------------------------------
+// R-6 (WP-5) — replica as stale-if-error
+// ---------------------------------------------------------------------------------------------
+
+/** R-6: the origin the shared reader stamped on a replicated session ('' = this machine ingested it). */
+function replicaOriginOf(local) {
+  const session = Array.isArray(local && local.sessions) ? local.sessions[0] : null;
+  return String((session && session.replica_origin) || '').trim();
+}
+
+/** R-7: a search row the reader marked as a copy of another machine's record. Pure. */
+function isReplicaRow(row) {
+  return String((row && row.replica_origin) || '') !== '';
+}
+
+/**
+ * R-6: who to ask for the replica's own machine. The directory (`getMirrorSessionMachine`) is the
+ * fleet's naming authority and R-3(a) already forwards to what it names without a registry row; the
+ * registry row whose `instanceId` IS the replica's origin is the fallback, and only when dialable.
+ * `null` means no owner can be reached — the copy is then served, labelled, with that named.
+ */
+function replicaOwnerMachine(sessionId, origin, exclude, d, originRow) {
+  const located = locateSessionOwner(sessionId, {
+    isLocalOwner: d.isLocalOwner,
+    getMirrorSessionMachine: d.getMirrorSessionMachine,
+    findMachine: d.findMachine,
+  });
+  if (located.owner === 'machine' && String(located.machine.instanceId) !== exclude) return located.machine;
+  const instanceId = String((originRow && originRow.instanceId) || '');
+  if (instanceId && instanceId === String(origin) && instanceId !== exclude && isDialable(originRow)) return originRow;
+  return null;
+}
+
+/** R-5/R-6: the `searched` row for the machine an R-6 read could not reach (named when known). */
+function ownerEntry(origin, row, status) {
+  const named = row && String(row.instanceId || '') === String(origin) ? row : null;
+  return {
+    machine_id: String(origin),
+    machine_name: named ? machineLabel(named) : String(origin),
+    status,
+  };
+}
+
+/**
+ * R-6: the caller gets THIS machine's copy, labelled as the copy it is. `searched` names the owner
+ * that could not be reached, and is absent when there was no owner to name (`scope=local`, where the
+ * caller asked for this machine's copy on purpose).
+ */
+function replicaAnswer(local, d, origin, searched) {
+  const self = d.localIdentity();
+  const answer = {
+    ...local,
+    location: {
+      machine_id: String(self.instanceId || ''),
+      machine_name: String(self.displayName || ''),
+      source: 'replica',
+      stale: true,
+      origin: String(origin),
+    },
+  };
+  if (Array.isArray(searched) && searched.length) answer.searched = searched;
+  return answer;
+}
+
+// ---------------------------------------------------------------------------------------------
+// R-3(c) — the deadline-bounded parallel probe
+// ---------------------------------------------------------------------------------------------
+
+/** One request per dialable member, all in flight at once; the first non-empty answer wins. */
+function probeMembers(machines, args, d) {
+  const statuses = new Map();
+  if (!machines.length) return Promise.resolve({ hit: null, statuses });
+  const search = buildForwardSearch(args);
+  return new Promise((resolve) => {
+    let settled = false;
+    let pending = machines.length;
+    let timer = null;
+    const settle = (hit) => {
+      if (settled) return;
+      settled = true;
+      if (timer) d.clearTimeoutFn(timer);
+      // Snapshot: a late answer after the deadline must not rewrite what we already reported.
+      resolve({ hit, statuses: new Map(statuses) });
+    };
+    // P-3: bound the whole fan-out, never wait for a straggler.
+    timer = d.setTimeoutFn(() => settle(null), d.probeDeadlineMs);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+    // Every member answering before the deadline ends the probe at once (no gratuitous 5 s wait).
+    const note = (machineId, status) => {
+      statuses.set(machineId, status);
+      pending -= 1;
+      if (pending === 0) settle(null);
+    };
+    for (const machine of machines) {
+      statuses.set(machine.instanceId, 'timeout');
+      Promise.resolve()
+        .then(() => d.forward({
+          machine,
+          pathname: SESSION_CONTEXT_PATHNAME,
+          search,
+          method: 'GET',
+        }))
+        .then((result) => {
+          const parsed = parseForwardedEnvelope(result);
+          if (parsed.error) {
+            note(machine.instanceId, parsed.status);
+            return;
+          }
+          if (hasSessions(parsed.body)) {
+            statuses.set(machine.instanceId, 'ok');
+            settle(withLocation(parsed.body, machine, 'owner'));
+            return;
+          }
+          note(machine.instanceId, 'miss');
+        })
+        .catch(() => {
+          /* HANDLE: one member's failure is a per-machine status in `searched`, never thrown */
+          note(machine.instanceId, 'error');
+        });
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------------------------
+// Envelope helpers
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * A forwarded result -> `{ error: false, body }` | `{ error: true, status }`. Success is a 2xx with
+ * a JSON object body (the owner's answer is authoritative, even when it is itself a miss).
+ */
+function parseForwardedEnvelope(result) {
+  if (!result || result.ok !== true) {
+    return { error: true, status: result && result.code === 'machine_unreachable' ? 'unreachable' : 'error' };
+  }
+  if (!(Number(result.status) >= 200 && Number(result.status) < 300)) return { error: true, status: 'error' };
+  let body;
+  try {
+    body = JSON.parse(String(result.text == null ? '' : result.text));
+  } catch {
+    /* expected: a non-JSON member body is reported as status 'error', never thrown at the caller */
+    return { error: true, status: 'error' };
+  }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return { error: true, status: 'error' };
+  return { error: false, body };
+}
+
+function hasSessions(result) {
+  return Array.isArray(result && result.sessions) && result.sessions.length > 0;
+}
+
+function withLocation(body, machine, source) {
+  return {
+    ...body,
+    location: {
+      machine_id: String(machine.instanceId || ''),
+      machine_name: machineLabel(machine),
+      source,
+      stale: false,
+    },
+  };
+}
+
+function missEnvelope(searched) {
+  return { ok: true, found: false, sessions: [], messages: [], searched };
+}
+
+/**
+ * R-4: the receiver never forwards again — every outbound request re-encodes the read params with
+ * `scope=local`. Route-level params (`scope`, and the `ref` alias) are never forwarded.
+ */
+function buildForwardSearch(args = {}) {
+  const params = new URLSearchParams();
+  const set = (key, value) => {
+    if (value === undefined || value === null || value === '') return;
+    params.set(key, String(value));
+  };
+  set('session_id', args.session_id);
+  if (Array.isArray(args.session_ids)) {
+    for (const id of args.session_ids) {
+      const value = String(id == null ? '' : id).trim();
+      if (value) params.append('session_id', value);
+    }
+  }
+  set('limit', args.limit);
+  set('turn_limit', args.turn_limit);
+  set('byte_limit', args.byte_limit);
+  set('deadline_ms', args.deadline_ms);
+  set('direction', args.direction);
+  set('cursor', args.cursor);
+  set('payload_byte_limit', args.payload_byte_limit);
+  if (args.include_raw) params.set('include_raw', '1');
+  if (args.dedupe === false) params.set('no_dedupe', '1');
+  set('format', args.format);
+  set('projection', args.projection);
+  params.set('scope', 'local');
+  return `?${params.toString()}`;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Targets / labels
+// ---------------------------------------------------------------------------------------------
+
+/** The mirror rows that are NOT this machine and NOT the caller's (`excludeMachineId`). */
+function otherMembers(d, exclude) {
+  const self = String(d.localIdentity().instanceId || '');
+  return (d.machineRows() || []).filter((row) => row
+    && row.instanceId
+    && String(row.instanceId) !== self
+    && String(row.instanceId) !== exclude);
+}
+
+/** The mesh's dialable rule (lib/hub-bridge-mesh.js `_dialable`): enabled and proved reachable. */
+function isDialable(row) {
+  if (!row) return false;
+  if (row.enabled === false || row.enabled === 0) return false;
+  return String(row.health || '') === 'reachable';
+}
+
+function searchedEntries(d, members, statuses) {
+  const entries = [selfEntry(d, 'miss')];
+  for (const row of members) {
+    entries.push({
+      machine_id: String(row.instanceId || ''),
+      machine_name: machineLabel(row),
+      status: statuses.get(row.instanceId) || 'skipped', // never dialled (disabled/unreachable)
+    });
+  }
+  return entries;
+}
+
+function selfEntry(d, status) {
+  const self = d.localIdentity();
+  return { machine_id: String(self.instanceId || ''), machine_name: String(self.displayName || ''), status };
+}
+
+function selfLocation(d, source) {
+  const self = d.localIdentity();
+  return {
+    machine_id: String(self.instanceId || ''),
+    machine_name: String(self.displayName || ''),
+    source,
+    stale: false,
+  };
+}
+
+function sessionIdsOf(args = {}) {
+  const out = [];
+  const push = (value) => {
+    const id = String(value == null ? '' : value).trim();
+    if (id && !out.includes(id)) out.push(id);
+  };
+  if (Array.isArray(args.session_ids)) args.session_ids.forEach(push);
+  push(args.session_id);
+  return out;
+}
+
+// ---------------------------------------------------------------------------------------------
+// deps
+// ---------------------------------------------------------------------------------------------
+
+let _localIdentityMemo = null;
+
+/** The SAME lazy identity module lib/remote-machine-proxy.js `_localInstanceId` uses (reused). */
+function productionLocalIdentity() {
+  if (_localIdentityMemo) return _localIdentityMemo;
+  let instanceId = '';
+  try {
+    const identity = require('./instance-identity-access').getInstanceIdentity({ required: false });
+    instanceId = String((identity && identity.instanceId) || '');
+  } catch {
+    /* expected: identity is not minted before the DB is open — an unknown local id is honest */
+    instanceId = '';
+  }
+  let displayName = '';
+  try {
+    displayName = String(os.hostname() || '');
+  } catch {
+    /* expected: os.hostname() is best-effort — an empty display name never blocks a read */
+    displayName = '';
+  }
+  _localIdentityMemo = { instanceId, displayName };
+  return _localIdentityMemo;
+}
+
+function resolveDeps(deps = {}) {
+  return {
+    getMirrorSessionMachine: deps.getMirrorSessionMachine
+      || ((id) => require('./remote-machine-catalog').getMirrorSessionMachine(id)),
+    machineRows: deps.machineRows || (() => require('./remote-machine-catalog').machineRows()),
+    findMachine: deps.findMachine || ((instanceId) => (require('./remote-machine-catalog').machineRows() || [])
+      .find((row) => row && String(row.instanceId) === String(instanceId)) || null),
+    forward: deps.forward || ((request) => require('./remote-machine-proxy').forwardMachineHttp({
+      ...request,
+      deps: { timeoutMs: SESSION_OWNER_FORWARD_TIMEOUT_MS },
+    })),
+    readLocal: deps.readLocal || (() => Promise.reject(new Error('session_context_locator: readLocal is not wired'))),
+    searchLocal: deps.searchLocal || (() => Promise.reject(new Error('session_context_locator: searchLocal is not wired'))),
+    localIdentity: deps.localIdentity || productionLocalIdentity,
+    isLocalOwner: deps.isLocalOwner,
+    now: deps.now || (() => Date.now()),
+    setTimeoutFn: deps.setTimeoutFn || ((fn, ms) => setTimeout(fn, ms)),
+    clearTimeoutFn: deps.clearTimeoutFn || ((timer) => clearTimeout(timer)),
+    probeDeadlineMs: Number(deps.probeDeadlineMs) > 0 ? Number(deps.probeDeadlineMs) : SESSION_PROBE_DEADLINE_MS,
+    searchDeadlineMs: Number(deps.searchDeadlineMs) > 0
+      ? Number(deps.searchDeadlineMs)
+      : POOL_SEARCH_MEMBER_DEADLINE_MS,
+  };
+}
+
+module.exports = {
+  poolEnabled,
+  locateSessionOwner,
+  readSessionContextAnywhere,
+  searchSessionsAnywhere,
+  fusePoolResults,
+  // §8 WP-1: shared, never re-typed by lib/fleet-session-lists.js (its fan-out members and its
+  // labels must stay exactly this module's rules).
+  otherMembers,
+  isDialable,
+  machineLabel,
+  productionLocalIdentity,
+  SESSION_OWNER_FORWARD_TIMEOUT_MS,
+  SESSION_PROBE_DEADLINE_MS,
+  POOL_SEARCH_MEMBER_DEADLINE_MS,
+};