create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/fleet-session-lists.js

@@ -0,0 +1,672 @@
+'use strict';
+
+// WP-1 (docs/fleet-session-lists-hub-search-2026-11-01.html §5 D-1..D-10, §6.2, §7, §8 WP-1):
+// the fleet fan-out primitive. A session-LIST route (Recent, session search, PE conversations,
+// standup search) answered with `?scope=fleet` returns THIS machine's rows plus every dialable
+// pool member's rows, de-duplicated, stamped with provenance, and carrying a per-machine status
+// map. The route wiring lives in WP-2..WP-4 — this module owns the primitive, the merge rules and
+// the census seam.
+//
+// WP-3 adds the FUNCTION-LEVEL twin of `fleetRouted` for a route that calls a search function
+// rather than a ServerResponse handler — `searchFleet` (S-11, the standup deep search). It runs the
+// local search and the same fan-out CONCURRENTLY and merges through the same `mergeMemberLists` +
+// `dedupeFleetRows` the route flow uses, so the two can never drift.
+//
+// Hard rules implemented here (never re-derived elsewhere):
+//   D-2  only a hub fans out, and never twice: every forwarded leg carries NO `scope`, and a
+//        request arriving with `X-CTM-Forwarded-By`/`X-CTM-Machine` is never a fleet request.
+//   D-4  dedup: the local id wins; a box row whose non-empty `ownerInstanceId` names another
+//        machine is dropped; among box rows with the same id the owner's wins.
+//   D-5  one deadline per fan-out (`FLEET_LIST_MEMBER_DEADLINE_MS`); a late answer never rewrites
+//        the result (snapshot on settle — the same shape lib/session-context-locator.js used).
+//   D-6  the fleet body is the local route's own envelope with its row array replaced, plus
+//        `machines` (self first) and `partial`.
+//   D-8  stale-if-error for UNFILTERED lists only, keyed `${route}\0${machine_id}\0${limit}`.
+//   D-10 every surviving box row is a NEW object stamped `machine`/`machineName`.
+//
+// Module graph (no cycle): this module requires lib/session-context-locator.js (for `otherMembers`/
+// `isDialable`/`machineLabel`/`productionLocalIdentity`/`poolEnabled` — never re-typed) and the leaf
+// lib/fleet-fanout.js; the locator requires only the leaf. Neither requires the other back.
+
+const {
+  poolEnabled,
+  otherMembers,
+  isDialable,
+  machineLabel,
+  productionLocalIdentity,
+} = require('./session-context-locator');
+
+const FLEET_LIST_MEMBER_DEADLINE_MS = 2_000; // D-5/§1.3
+const FLEET_SCOPE_PARAM = 'scope';
+const FLEET_SCOPE_VALUE = 'fleet';
+const FLEET_STATUSES = Object.freeze(['ok', 'stale', 'timeout', 'unreachable', 'error', 'skipped']);
+/** Tags a handler with the route key it was built for (§7 census reads this). */
+const FLEET_ROUTED = Symbol.for('ctm.fleetRouted');
+
+// S-11: the one session-search path the standup deep search fans out over. Its route KEY is the
+// FLEET_LIST_ROUTES key lib/fleet-session-list-routes.js registers the search spec under.
+const SESSION_SEARCH_PATHNAME = '/api/sessions/search';
+const SESSION_SEARCH_ROUTE = `GET ${SESSION_SEARCH_PATHNAME}`;
+
+/**
+ * §6.2/§7: filled by WP-2 (Recent + session search) and WP-4 (PE conversations) with
+ * `{ 'GET /api/...': spec }`. A plain exported object on purpose — a later WP assigns into it.
+ */
+const FLEET_LIST_ROUTES = {};
+
+// D-2: a leg is only ever a READ of a peer's own list, so the two headers the relay sets on a
+// forwarded request are the no-recursion markers (§5 P-3, §6.3).
+const FORWARDED_BY_HEADER = 'x-ctm-forwarded-by';
+const MACHINE_HEADER = 'x-ctm-machine';
+
+/** Headers arrive either as a Node plain object (lower-cased keys) or a fetch-like `Headers`. */
+function headerValue(req, name) {
+  const headers = req && req.headers;
+  if (!headers) return '';
+  if (typeof headers.get === 'function') return String(headers.get(name) || '');
+  const direct = headers[name];
+  if (direct !== undefined) return String(direct || '');
+  const upper = name.toUpperCase();
+  for (const key of Object.keys(headers)) {
+    if (String(key).toLowerCase() === name) return String(headers[key] || '');
+    if (key === upper) return String(headers[key] || '');
+  }
+  return '';
+}
+
+/**
+ * D-1/D-2: is this request a fleet fan-out request for THIS machine? True iff `scope=fleet`, the
+ * pool flag is ON (`CTM_SESSION_CONTEXT_POOL`, default ON — the ONE kill switch for fleet reads),
+ * and the request is neither a forwarded leg nor a single-box proxy (`?machine=`).
+ */
+function isFleetRequest(req, url, env = process.env) {
+  if (!url || !url.searchParams) return false;
+  if (url.searchParams.get(FLEET_SCOPE_PARAM) !== FLEET_SCOPE_VALUE) return false;
+  if (!poolEnabled(env)) return false;
+  if (headerValue(req, FORWARDED_BY_HEADER)) return false;
+  if (headerValue(req, MACHINE_HEADER)) return false;
+  if (url.searchParams.get('machine')) return false;
+  return true;
+}
+
+/**
+ * D-2/D-3: the query string for one forwarded leg. Route-level params (`scope`, `token`,
+ * `machine`, `owner`) are dropped, `owner=self` is set, and everything else the caller asked for
+ * rides along unchanged (so each box answers ITS OWN top-N — the union of per-owner top-N lists is
+ * what contains the global top-N).
+ */
+function forwardSearchFor(url) {
+  const params = new URLSearchParams(url && url.searchParams ? url.searchParams : undefined);
+  for (const key of ['scope', 'token', 'machine', 'owner']) params.delete(key);
+  params.set('owner', 'self');
+  return `?${params.toString()}`;
+}
+
+/**
+ * One member's forwarded answer -> `{ error: false, rows, body }` | `{ error: true, status }`.
+ *
+ * A transport failure is named by TYPE: `machine_unreachable` with `error === 'timeout'` is a
+ * member that did not answer in time, any other unreachable reason is `unreachable`, and anything
+ * else (unknown code, non-2xx, non-JSON, a body without the expected rows array) is `error`.
+ * Never throws, never returns a silent empty list.
+ */
+function parseListLeg(result, spec) {
+  if (!result || result.ok !== true) {
+    if (result && result.code === 'machine_unreachable') {
+      return { error: true, status: result.error === 'timeout' ? 'timeout' : 'unreachable' };
+    }
+    return { error: true, status: '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 a named per-machine 'error', never thrown at the caller */
+    return { error: true, status: 'error' };
+  }
+  const rows = spec && spec.rowsKey ? (body ? body[spec.rowsKey] : undefined) : body;
+  if (!Array.isArray(rows)) return { error: true, status: 'error' };
+  return { error: false, rows, body };
+}
+
+/**
+ * S-6: the scatter-gather lives in the leaf lib/fleet-fanout.js; this wrapper only supplies the
+ * locator's `machineLabel`, so every caller labels members by the one rule.
+ */
+function fanOutMembers(machines, request, d = {}) {
+  return require('./fleet-fanout').fanOutMembers(machines, request, { label: machineLabel, ...d });
+}
+
+/**
+ * §6.2: a minimal ServerResponse stand-in for the LOCAL leg of a fleet request, so the wrapper can
+ * run the route's own handler to completion (it is the only always-authoritative leg) and then
+ * decide whether to merge into it or to re-emit it verbatim.
+ *
+ * Resolves `{ status, headers, raw, json }` when `end()` is called — `json` is `JSON.parse(raw)`,
+ * or `null` for a body that is not JSON (the wrapper then writes the captured bytes verbatim).
+ * Rejects if `local` throws (or its returned promise rejects) before `end()`.
+ */
+function captureLocal(local, req, url) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    // Header NAMES keep the local leg's own casing, so the verbatim re-emit is faithful; the
+    // lowercase index is only how getHeader/removeHeader/setHeader find them again.
+    const headers = {};
+    const byLower = new Map();
+    let sent = false;
+    let done = false;
+    const setHeaderValue = (key, value) => {
+      const name = String(key);
+      const lower = name.toLowerCase();
+      const previous = byLower.get(lower);
+      if (previous !== undefined && previous !== name) delete headers[previous];
+      headers[name] = value;
+      byLower.set(lower, name);
+    };
+    const push = (chunk) => {
+      if (chunk === undefined || chunk === null) return;
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    };
+    const shim = {
+      statusCode: 200,
+      get headersSent() { return sent; },
+      writeHead(status, hdrs) {
+        shim.statusCode = Number(status) || 200;
+        sent = true;
+        if (hdrs && typeof hdrs === 'object') {
+          for (const key of Object.keys(hdrs)) setHeaderValue(key, hdrs[key]);
+        }
+        return shim;
+      },
+      setHeader(key, value) { if (!sent) setHeaderValue(key, value); return shim; },
+      getHeader(key) { return headers[byLower.get(String(key).toLowerCase())]; },
+      removeHeader(key) {
+        const name = byLower.get(String(key).toLowerCase());
+        if (name !== undefined) { delete headers[name]; byLower.delete(String(key).toLowerCase()); }
+      },
+      write(chunk) { push(chunk); sent = true; return true; },
+      end(chunk) {
+        if (done) return shim;
+        done = true;
+        sent = true;
+        push(chunk);
+        const raw = Buffer.concat(chunks);
+        let json = null;
+        try {
+          json = JSON.parse(raw.toString('utf8'));
+        } catch {
+          /* expected: a non-JSON local body is reported as json === null — the wrapper then writes
+             the captured bytes verbatim, with no merge */
+          json = null;
+        }
+        resolve({ status: shim.statusCode, headers, raw, json });
+        return shim;
+      },
+    };
+    let outcome;
+    try {
+      outcome = local(req, shim, url);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    if (outcome && typeof outcome.then === 'function') outcome.catch(reject);
+  });
+}
+
+/** D-4's default key when a route does not supply `rowId`. */
+function defaultRowId(row) {
+  return String((row && (row.sessionId || row.id || row.session_id || row.ctm_session_id)) || '');
+}
+
+function textOf(value) {
+  return String(value == null ? '' : value);
+}
+
+/**
+ * D-4/D-10, exported for tests. Local rows come first and are kept AS IS (same objects — this
+ * machine's row is authoritative, §2.2); each surviving box row is a NEW object stamped
+ * `machine`/`machineName`. A box row is dropped when its id is a local id, and when its non-empty
+ * `ownerInstanceId` is one of `localOwnerIds` (this hub's own id + lineage): it is then a box's COPY
+ * of one of OUR sessions — the 3,775 Spark copies of §1.1 — even if this hub no longer lists it.
+ * A box row owned by any other id is kept: a box answering `owner=self` filters by its OWN lineage,
+ * so an owner id that differs from the box's registry id is that box's older lineage id, not a
+ * foreign row. Among box rows sharing an id the one whose `ownerInstanceId` is its own source
+ * machine wins, else the first seen. Rows with an empty id are never merged. Pure: no input mutated.
+ */
+function dedupeFleetRows(localRows, lists, rowId, localOwnerIds) {
+  const ours = localOwnerIds instanceof Set ? localOwnerIds : new Set(localOwnerIds || []);
+  const idOf = typeof rowId === 'function' ? rowId : defaultRowId;
+  const local = Array.isArray(localRows) ? localRows : [];
+  const localIds = new Set();
+  for (const row of local) {
+    const id = textOf(idOf(row));
+    if (id) localIds.add(id);
+  }
+  const out = local.slice();
+  const seen = new Map();
+  const order = [];
+  for (const list of Array.isArray(lists) ? lists : []) {
+    if (!list || typeof list !== 'object') continue;
+    const machineId = textOf(list.machine_id);
+    const rows = Array.isArray(list.rows) ? list.rows : [];
+    for (const row of rows) {
+      if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
+      const owner = textOf(row.ownerInstanceId).trim();
+      if (owner && ours.has(owner)) continue; // a box's copy of one of OUR sessions never enters the answer
+      const placed = { ...row, machine: list.machine_id, machineName: list.machine_name };
+      const id = textOf(idOf(row));
+      if (!id) {
+        out.push(placed);
+        continue;
+      }
+      if (localIds.has(id)) continue; // D-4: this machine's own row wins the id
+      const isOwnerRow = owner !== '' && owner === machineId;
+      const existing = seen.get(id);
+      if (!existing) {
+        seen.set(id, { row: placed, ownerRow: isOwnerRow });
+        order.push(id);
+        continue;
+      }
+      if (isOwnerRow && !existing.ownerRow) {
+        existing.row = placed;
+        existing.ownerRow = true;
+      }
+    }
+  }
+  for (const id of order) out.push(seen.get(id).row);
+  return out;
+}
+
+/** D-8: `${route}\0${machine_id}\0${limit}` (§6.2). */
+function lastGoodKey(route, machineId, limit) {
+  return `${route}\u0000${machineId}\u0000${limit}`;
+}
+
+/**
+ * D-8: per-(route, machine, limit) last-`ok` row list, in memory only.
+ * `get(key)` -> `{rows, at}|null`, `set(key, rows)` stamps `at` from the injected clock,
+ * `prune(liveMachineIds)` drops every entry whose machine is no longer in `machineRows()`.
+ */
+function createFleetLastGood({ now = () => Date.now() } = {}) {
+  const store = new Map();
+  return {
+    get(key) {
+      const entry = store.get(String(key));
+      return entry ? { rows: entry.rows, at: entry.at } : null;
+    },
+    set(key, rows) {
+      store.set(String(key), { rows: Array.isArray(rows) ? rows : [], at: Number(now()) });
+    },
+    prune(liveMachineIds) {
+      const live = liveMachineIds instanceof Set ? liveMachineIds : new Set(liveMachineIds || []);
+      for (const key of [...store.keys()]) {
+        const parts = String(key).split('\u0000');
+        if (!live.has(parts.length >= 2 ? parts[1] : '')) store.delete(key);
+      }
+    },
+  };
+}
+
+// Module-level default stale cache, so a hub keeps a member's last good list between requests.
+const defaultLastGood = createFleetLastGood();
+
+/** The literal response body is emitted with the local leg's status/headers and no merge (§6.2). */
+function writeVerbatim(res, captured) {
+  if (captured.headers && Object.keys(captured.headers).length) res.writeHead(captured.status, captured.headers);
+  else res.writeHead(captured.status);
+  res.end(captured.raw);
+}
+
+function writeJson(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+/** Every dependency of a fleet request, injectable so a unit test never touches the network or a DB. */
+function resolveFleetDeps(deps = {}) {
+  const deadline = Number(deps.deadlineMs) > 0 ? Number(deps.deadlineMs) : FLEET_LIST_MEMBER_DEADLINE_MS;
+  return {
+    machineRows: deps.machineRows || (() => require('./remote-machine-catalog').machineRows()),
+    localIdentity: deps.localIdentity || productionLocalIdentity,
+    // D-4: this hub's own id + lineage — a box row owned by one of these is a copy of OUR session.
+    localOwnerIds: deps.localOwnerIds || (() => {
+      const identity = require('./instance-identity-access').getInstanceIdentity({ required: false });
+      return new Set([...(identity && identity.lineage ? identity.lineage : [])]);
+    }),
+    forward: deps.forward || ((request) => require('./remote-machine-proxy').forwardMachineHttp({
+      ...request,
+      method: 'GET',
+      deps: { timeoutMs: deadline },
+    })),
+    setTimeoutFn: deps.setTimeoutFn || ((fn, ms) => setTimeout(fn, ms)),
+    clearTimeoutFn: deps.clearTimeoutFn || ((timer) => clearTimeout(timer)),
+    deadlineMs: deadline,
+    env: deps.env || process.env,
+    lastGood: deps.lastGood || defaultLastGood,
+    now: deps.now || (() => Date.now()),
+  };
+}
+
+/** D-8: only an unfiltered list (`/api/recent-sessions`, `/api/conversations`) is cache-eligible. */
+function isUnfiltered(spec, url) {
+  if (typeof spec.unfiltered !== 'function') return false;
+  try {
+    return spec.unfiltered(url) === true;
+  } catch {
+    /* expected: a spec that cannot evaluate its own filter predicate is simply not cache-eligible */
+    return false;
+  }
+}
+
+function limitOf(spec, url) {
+  if (typeof spec.limitOf === 'function') {
+    const n = Number(spec.limitOf(url));
+    if (Number.isFinite(n) && n >= 0) return Math.trunc(n);
+  }
+  return 0;
+}
+
+/**
+ * D-4/D-8/D-10: turn the fan-out's per-member answers into ONE deduped row list plus the
+ * per-member status entries of the `machines` envelope. Shared by the route flow (`runFleetUnguarded`)
+ * and the function-level `searchFleet` (S-11) so the two can never drift — a member is dialled only
+ * when `isDialable`, an undialled one is `skipped`, and only a `cacheable` route writes/reads D-8's
+ * last good copy.
+ *
+ * @param {{members:object[], fanout:{lists:object[],statuses:Map,counts:Map}, localRows:object[],
+ *          rowId:Function, ours:Set<string>, cacheable:boolean, route:string, limit:number, d:object}} input
+ * @returns {{rows:object[], entries:object[]}} `rows` = the deduped union (local rows first),
+ *   `entries` = one `{machine_id, machine_name, status, count, as_of?}` per member, in the order
+ *   `machineRows()` returned them (the caller prepends this machine's own `ok` entry).
+ */
+function mergeMemberLists({ members, fanout, localRows, rowId, ours, cacheable, route, limit, d }) {
+  const lists = [];
+  const entries = [];
+  for (const row of members) {
+    const id = textOf(row.instanceId);
+    const name = machineLabel(row);
+    if (!isDialable(row)) {
+      // Never dialled (disabled/unreachable) is `skipped`, exactly like the context probe's
+      // `searched` — D-8 covers it with the stale copy when one is held.
+      entries.push(fillFromLastGood(d, cacheable, route, id, name, limit, 'skipped', 0, lists));
+      continue;
+    }
+    const status = fanout.statuses.get(row.instanceId) || 'timeout';
+    const count = fanout.counts.get(row.instanceId) || 0;
+    if (status === 'ok') {
+      const answered = fanout.lists.find((entry) => entry.machine_id === id);
+      const rows = answered ? answered.rows : [];
+      if (cacheable) d.lastGood.set(lastGoodKey(route, id, limit), rows);
+      lists.push({
+        machine_id: id,
+        machine_name: name,
+        owner: false,
+        rows,
+        body: answered ? answered.body : undefined,
+      });
+      entries.push({ machine_id: id, machine_name: name, status, count });
+      continue;
+    }
+    entries.push(fillFromLastGood(d, cacheable, route, id, name, limit, status, count, lists));
+  }
+  return { rows: dedupeFleetRows(localRows, lists, rowId, ours), entries };
+}
+
+/**
+ * The fleet request itself: the local leg and the fan-out run CONCURRENTLY (D-5: the local leg is
+ * never cut by the member deadline), then either the local answer is re-emitted verbatim (not 2xx,
+ * not JSON, or no rows array to merge into) or the merged envelope is written with the local
+ * leg's status.
+ */
+async function runFleet(route, local, spec, deps, req, res, url) {
+  try {
+    return await runFleetUnguarded(route, local, spec, deps, req, res, url);
+  } catch (error) {
+    // REPORT: the local handler threw before answering. Answer 500 like any route error rather
+    // than leaving the request open or rejecting into the router.
+    console.warn(`[fleet-session-lists] ${route} local leg failed: ${(error && error.message) || error}`);
+    if (!res.headersSent) writeJson(res, 500, { error: 'fleet_local_failed' });
+    return undefined;
+  }
+}
+
+async function runFleetUnguarded(route, local, spec, deps, req, res, url) {
+  const d = resolveFleetDeps(deps);
+  const self = d.localIdentity();
+  const members = otherMembers({ localIdentity: d.localIdentity, machineRows: d.machineRows }, '');
+  const limit = limitOf(spec, url);
+  const [captured, fanout] = await Promise.all([
+    captureLocal(local, req, url),
+    fanOutMembers(members.filter(isDialable), {
+      pathname: url.pathname,
+      search: forwardSearchFor(url),
+      parse: (result) => parseListLeg(result, spec),
+    }, {
+      forward: d.forward,
+      setTimeoutFn: d.setTimeoutFn,
+      clearTimeoutFn: d.clearTimeoutFn,
+      deadlineMs: d.deadlineMs,
+    }),
+  ]);
+
+  const ok = Number(captured.status) >= 200 && Number(captured.status) < 300;
+  const localRows = captured.json == null ? null : (spec.rowsKey ? captured.json[spec.rowsKey] : captured.json);
+  if (!ok || captured.json == null || !Array.isArray(localRows)) {
+    writeVerbatim(res, captured);
+    return undefined;
+  }
+
+  const cacheable = spec.lastGood === true && isUnfiltered(spec, url);
+  // D-8: an entry whose machine left the registry is dropped on every fleet call.
+  d.lastGood.prune(new Set(members.map((row) => textOf(row.instanceId))));
+
+  const ours = new Set(d.localOwnerIds());
+  if (self && self.instanceId) ours.add(textOf(self.instanceId));
+  const { rows: merged, entries: memberEntries } = mergeMemberLists({
+    members,
+    fanout,
+    localRows,
+    rowId: spec.rowId,
+    ours,
+    cacheable,
+    route,
+    limit,
+    d,
+  });
+
+  const select = typeof spec.select === 'function' ? spec.select : ((rows) => rows);
+  const rows = select(merged, { limit, url });
+  const machines = [{
+    machine_id: textOf(self.instanceId),
+    machine_name: textOf(self.displayName),
+    status: 'ok',
+    count: localRows.length,
+  }, ...memberEntries];
+
+  const body = spec.rowsKey ? { ...captured.json, [spec.rowsKey]: rows } : { [spec.fleetRowsKey]: rows };
+  body.machines = machines;
+  body.partial = machines.some((entry) => entry.status !== 'ok');
+  if (spec.rowsKey && Object.prototype.hasOwnProperty.call(captured.json, 'total')) body.total = rows.length;
+  writeJson(res, captured.status, body);
+  return undefined;
+}
+
+/**
+ * D-8: a member that did not answer `ok` contributes its last good rows with `stale: true` on every
+ * row and reports status `stale` + `as_of`; with no entry (or a non-cacheable route) the member is
+ * named with its own failure status and contributes nothing.
+ */
+function fillFromLastGood(d, cacheable, route, id, name, limit, status, count, lists) {
+  if (cacheable) {
+    const entry = d.lastGood.get(lastGoodKey(route, id, limit));
+    if (entry) {
+      lists.push({
+        machine_id: id,
+        machine_name: name,
+        owner: false,
+        rows: entry.rows.map((row) => ({ ...row, stale: true })),
+      });
+      return {
+        machine_id: id, machine_name: name, status: 'stale', count: entry.rows.length, as_of: entry.at,
+      };
+    }
+  }
+  return { machine_id: id, machine_name: name, status, count };
+}
+
+/**
+ * S-11/§6.3: the FUNCTION-LEVEL fleet search, for the one fleet caller that is not a ServerResponse
+ * route — the standup deep search (`server.js` `apiStandupSearch`), which calls a search function
+ * and serialises the object itself. It runs `localSearch(query, options)` (today's
+ * `buildSessionSearchResponse` shape `{ results, total?, sources, … }`) CONCURRENTLY with the same
+ * fan-out the route flow uses (D-5: the local leg is never cut by the member deadline).
+ *
+ * The forwarded leg is `GET /api/sessions/search?q=<query>&limit=<options.limit>&owner=self` — NO
+ * `scope`, so a box answers its own top-N and never fans out again (D-2/D-3). The merged rows are
+ * deduped by the search spec's `rowId` (a box's copy of one of OUR sessions is dropped, D-4),
+ * ordered by the search spec's own `select` (D-9: `SessionSearchUtils.compareSearchHits`) and
+ * sliced to the search spec's own clamp — so a merged fleet order equals single-DB order by
+ * construction.
+ *
+ * @param {(query:string, options:object) => Promise<object>} localSearch  today's search function
+ * @param {string} query
+ * @param {{limit?:number}} [options]  passed through to `localSearch` untouched
+ * @param {object} [deps]  `resolveFleetDeps` keys (machineRows, localIdentity, forward, timers,
+ *                         deadlineMs, env, localOwnerIds, …) plus `spec` — the search route's spec
+ *                         (defaults to the one lib/fleet-session-list-routes.js registers in
+ *                         FLEET_LIST_ROUTES; read from the map because requiring that module here
+ *                         would form a lib cycle).
+ * @returns {Promise<object>} `{ ...localResult, results, machines, partial, total? }` — `total`
+ *   only when the local result carried one. NEVER stale-if-error (D-8: search is never cached) and
+ *   NO cache write. The pool kill switch (or a missing spec) returns `localSearch(query, options)`
+ *   untouched; a `localSearch` rejection PROPAGATES (the standup adapter owns the `degraded`
+ *   contract).
+ */
+async function searchFleet(localSearch, query, options = {}, deps = {}) {
+  const d = resolveFleetDeps(deps);
+  const spec = deps.spec || FLEET_LIST_ROUTES[SESSION_SEARCH_ROUTE];
+  if (!poolEnabled(d.env) || !spec) return localSearch(query, options);
+
+  const params = new URLSearchParams();
+  params.set('q', textOf(query));
+  if (options.limit != null) params.set('limit', String(options.limit));
+  params.set('owner', 'self');
+  const search = `?${params.toString()}`;
+  const legUrl = new URL(`${SESSION_SEARCH_PATHNAME}${search}`, 'http://fleet.local');
+  // The limit is the search spec's own clamp, applied to the caller's `limit` (default 50).
+  const limit = limitOf(spec, legUrl);
+
+  const self = d.localIdentity();
+  const members = otherMembers({ localIdentity: d.localIdentity, machineRows: d.machineRows }, '');
+  const ours = new Set(d.localOwnerIds());
+  if (self && self.instanceId) ours.add(textOf(self.instanceId));
+
+  const [localResult, fanout] = await Promise.all([
+    localSearch(query, options),
+    fanOutMembers(members.filter(isDialable), {
+      pathname: SESSION_SEARCH_PATHNAME,
+      search,
+      parse: (result) => parseListLeg(result, spec),
+    }, {
+      forward: d.forward,
+      setTimeoutFn: d.setTimeoutFn,
+      clearTimeoutFn: d.clearTimeoutFn,
+      deadlineMs: d.deadlineMs,
+    }),
+  ]);
+
+  const localRows = localResult && Array.isArray(localResult.results) ? localResult.results : [];
+  const { rows: merged, entries } = mergeMemberLists({
+    members,
+    fanout,
+    localRows,
+    rowId: spec.rowId,
+    ours,
+    // D-8: a search hit list is query-keyed with a low hit rate — never read from, never written to,
+    // the last-good store.
+    cacheable: false,
+    route: SESSION_SEARCH_ROUTE,
+    limit,
+    d,
+  });
+
+  const select = typeof spec.select === 'function' ? spec.select : ((rows) => rows);
+  const results = select(merged, { limit, url: legUrl });
+  const machines = [{
+    machine_id: textOf(self.instanceId),
+    machine_name: textOf(self.displayName),
+    status: 'ok',
+    count: localRows.length,
+  }, ...entries];
+
+  const body = { ...localResult, results, machines, partial: machines.some((entry) => entry.status !== 'ok') };
+  if (localResult && Object.prototype.hasOwnProperty.call(localResult, 'total')) body.total = results.length;
+  return body;
+}
+
+/**
+ * §6.2: the route wrapper. `!isFleetRequest` returns `local(req, res, url)` UNCHANGED (the same
+ * return value — every non-fleet caller keeps today's behaviour byte for byte).
+ *
+ * @param {string} route  `'GET /api/recent-sessions'` etc. — the key of FLEET_LIST_ROUTES
+ * @param {(req:any, res:any, url:URL) => any} local  today's handler, untouched
+ * @param {object} spec  see the module docblock / §6.2 typedef
+ * @param {object} deps  machineRows, localIdentity, forward, setTimeoutFn, clearTimeoutFn,
+ *                       deadlineMs, env, lastGood, now (all injectable for tests)
+ * @returns {(req:any, res:any, url:URL) => any} tagged with `handler[FLEET_ROUTED] = route`
+ */
+function fleetRouted(route, local, spec, deps = {}) {
+  // A missing or partial spec is a wiring bug (a misspelled export once made this route answer
+  // `{"undefined": [...]}` with no limit and no stale copy) — refuse it where the route is built,
+  // never degrade it to `{}` at request time.
+  assertFleetSpec(route, spec);
+  const handler = (req, res, url) => {
+    const requestUrl = url || safeUrl(req);
+    if (!isFleetRequest(req, requestUrl, deps.env || process.env)) return local(req, res, requestUrl);
+    return runFleet(route, local, spec, deps, req, res, requestUrl);
+  };
+  handler[FLEET_ROUTED] = route;
+  return handler;
+}
+
+/** §6.2 spec contract: the four functions every merge needs, and a key the merged rows go under. */
+function assertFleetSpec(route, spec) {
+  const missing = [];
+  if (!spec || typeof spec !== 'object') missing.push('spec');
+  else {
+    for (const fn of ['rowId', 'select', 'limitOf']) if (typeof spec[fn] !== 'function') missing.push(fn);
+    if (spec.lastGood === true && typeof spec.unfiltered !== 'function') missing.push('unfiltered');
+    if (!spec.rowsKey && !spec.fleetRowsKey) missing.push('rowsKey|fleetRowsKey');
+  }
+  if (missing.length) throw new TypeError(`fleetRouted(${route}): incomplete spec (${missing.join(', ')})`);
+}
+
+function safeUrl(req) {
+  try {
+    return new URL((req && req.url) || '/', 'http://localhost');
+  } catch {
+    /* expected: an unparseable req.url can only fall back to a root URL, never throw into the route */
+    return new URL('/', 'http://localhost');
+  }
+}
+
+module.exports = {
+  FLEET_LIST_MEMBER_DEADLINE_MS,
+  FLEET_SCOPE_PARAM,
+  FLEET_STATUSES,
+  FLEET_ROUTED,
+  FLEET_LIST_ROUTES,
+  isFleetRequest,
+  forwardSearchFor,
+  parseListLeg,
+  fanOutMembers,
+  captureLocal,
+  dedupeFleetRows,
+  mergeMemberLists,
+  searchFleet,
+  createFleetLastGood,
+  fleetRouted,
+  assertFleetSpec,
+};