create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/fleet-resolver.js

@@ -0,0 +1,454 @@
+'use strict';
+// WP-7 (coding-task-manager/docs/fleet-origin-main-sync-skill-2026-10-31.html §13.4 R-R1/R-R5..R-R10,
+// §13.5, §13.6): the fleet-sync resolver — pure decisions, an injected-effect start sequence, the
+// resolver state file, and the session's first prompt.
+//
+// R-R1: the trigger is a `land sync` verdict. CTM's origin follower (WP-8) reads
+// `<common>/landing/sync-state.json`#lastSync after every tick; when that verdict is `conflict` or
+// `gate_failed` for a `kind:"sync"` job, this module decides whether a resolver session must start,
+// starts it through injected effects, and writes `<common>/landing/resolver.json`.
+//
+// Everything decision-shaped here is PURE: `decide()` reads no fs and no clock (the caller passes
+// `now`), so the whole rule table is a table test. The effects (`prepareWorkspace`, `resolvePick`,
+// `createSession`, `notify`) are injected by the caller — this module never touches server.js, never
+// creates a session on its own, and never pushes or moves `main` (R-R6 anti-goal: the resolver's
+// text names `git push` exactly once, on its Never line).
+//
+// R-R7 dedupe: one resolver per box, keyed per (local main tip, origin tip) — `key = base..tip`.
+// A key that is live is never started twice; a key that already ended (in `history`, or a `current`
+// record with an ended state) never restarts itself. A live record whose origin moved is kept as-is
+// (R-14.4: no queue nudge — the brief's own step 4 re-runs `land sync`), and a resolver with no
+// progress past its deadline follows the existing give-up path.
+//
+// §14 WP-13: the SAME `key` can also be owned from outside CTM. The `/fleet-sync` skill resolves the
+// sync in the USER's own session and marks the key first (`land resolve <job> --claim`, which writes
+// `owner: "session:<id>"` into this file); `decide()` then returns the no-op `keep`/`claimed` for it
+// so no second resolver is ever started for that conflict.
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const CONTRACT = 1;
+// §13.5: `resolveMaxMinutes` default (R-R8 deadline) — the caller's normalized publish block wins.
+const DEFAULT_RESOLVE_MAX_MINUTES = 120;
+// §13.5: default resolver agent when the config omits one.
+const DEFAULT_RESOLVE_AGENT = 'claude';
+// §13.4 R-R7: history keeps the last 20 ended records, newest first.
+const HISTORY_LIMIT = 20;
+// A `current` record in one of these states owns the box's resolver slot (R-R7).
+const LIVE_STATES = Object.freeze(['starting', 'resolving']);
+// §13.4 R-R1: the two verdicts that make a sync job a resolver candidate.
+const CANDIDATE_VERDICTS = Object.freeze(['conflict', 'gate_failed']);
+// A verdict in this set, recorded after the resolver started, means the sync finished under it.
+const SETTLED_VERDICTS = Object.freeze(['in_sync', 'pulled', 'pushed', 'published']);
+
+// §14.3 R-14.4: the rev-3 R-R7 queue nudge is gone — a live record whose origin moved is simply
+// KEPT (the `origin_moved` rule in `decide()`); there is no second prompt to queue and no per-key
+// bookkeeping on the record.
+
+// R-R4/R-R5 fast gate for a resolver's own merge commit, and the verify gate it runs afterwards.
+const RESOLVER_BRANCH_PREFIX = 'sync/origin-';
+const WORKTREE_NAME_PREFIX = 'sync-origin-';
+
+// §14 WP-13: the `owner` prefix that marks a record as claimed by a USER session (the `/fleet-sync`
+// skill's own session, via `land resolve <job> --claim`) rather than one CTM started. A CTM-started
+// record either has no `owner` at all or carries one without this prefix.
+const SESSION_OWNER_PREFIX = 'session:';
+
+/** §14 WP-13: does this record belong to a claiming user session (`owner: "session:<id>"`)? */
+function claimedBySession(record) {
+  return Boolean(record) && typeof record.owner === 'string' && record.owner.startsWith(SESSION_OWNER_PREFIX);
+}
+
+/** `<common>/landing/resolver.json` — the one resolver state file (R-R7). */
+function resolverPath(commonDir) {
+  return path.join(String(commonDir || ''), 'landing', 'resolver.json');
+}
+
+/** The empty state every reader gets for a missing or corrupt file (never a throw). */
+function emptyState(warning) {
+  const state = { contract: CONTRACT, current: null, history: [] };
+  if (warning) state.warning = warning;
+  return state;
+}
+
+/** The 12-char short form used in branch names and the session title (§13.5/R-R10). */
+function short12(sha) {
+  return String(sha == null ? '' : sha).slice(0, 12);
+}
+
+/** R-R7: the dedupe key of a (local main tip, origin tip) pair. */
+function jobKey(job) {
+  if (!job || !job.base || !job.tip) return '';
+  return `${job.base}..${job.tip}`;
+}
+
+/** The branch a resolver for this tip runs on; R-R10, and the pre-commit hook (WP-6) reads it. */
+function branchFor(tip) {
+  return `${RESOLVER_BRANCH_PREFIX}${short12(tip)}`;
+}
+
+/** The worktree NAME (not path) a resolver runs in; R-R10. */
+function worktreeNameFor(tip) {
+  return `${WORKTREE_NAME_PREFIX}${short12(tip)}`;
+}
+
+/** `now` is the only clock `decide()` may read; accept ms epoch, Date, or ISO string. */
+function nowToMs(now) {
+  if (typeof now === 'number') return now;
+  if (now instanceof Date) return now.getTime();
+  const t = Date.parse(String(now));
+  if (!Number.isFinite(t)) throw new TypeError('fleet-resolver: `now` must be a ms epoch, a Date, or an ISO string');
+  return t;
+}
+
+function isoOf(ms) {
+  return new Date(ms).toISOString();
+}
+
+// --- state file (atomic write, tolerant read) -----------------------------------------------------
+
+/**
+ * Read `<common>/landing/resolver.json`. A missing file is the empty state with no warning; a file
+ * that cannot be parsed (or is not an object) is the empty state plus a `warning` — REPORTED, never
+ * thrown, so one torn file can never stop the follower's tick.
+ */
+async function readState(commonDir) {
+  const file = resolverPath(commonDir);
+  let raw;
+  try {
+    raw = await fsp.readFile(file, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return emptyState();
+    return emptyState(`resolver state unreadable at ${file}: ${error && error.message ? error.message : String(error)}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return emptyState(`resolver state corrupt at ${file}: ${error && error.message ? error.message : String(error)}`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return emptyState(`resolver state corrupt at ${file}: not a JSON object`);
+  }
+  return {
+    contract: CONTRACT,
+    current: parsed.current && typeof parsed.current === 'object' ? parsed.current : null,
+    history: Array.isArray(parsed.history) ? parsed.history : [],
+  };
+}
+
+/**
+ * Write the state atomically: `resolver.json.tmp-<pid>` then `fs.rename` (same directory, so
+ * the rename is atomic — a reader never sees a half-written file). `history` is trimmed to the last
+ * 20 ended records, newest first. A `warning` read off disk is never persisted.
+ */
+async function writeState(commonDir, state) {
+  const file = resolverPath(commonDir);
+  const payload = {
+    contract: CONTRACT,
+    current: state && state.current ? state.current : null,
+    history: state && Array.isArray(state.history) ? state.history.slice(0, HISTORY_LIMIT) : [],
+  };
+  await fsp.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  await fsp.writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`);
+  await fsp.rename(tmp, file);
+  return payload;
+}
+
+/** The full on-disk state object for a write of one `current` record plus the history we read. */
+function stateWith(prev, current) {
+  return { contract: CONTRACT, current, history: prev && Array.isArray(prev.history) ? prev.history : [] };
+}
+
+// --- decide() -------------------------------------------------------------------------------------
+
+function none(reason, record) {
+  return { action: 'none', reason, record: record || null };
+}
+
+/** The normalized publish block: missing `resolve` means a session, missing keys take the defaults. */
+function publishPolicy(publish) {
+  const p = publish && typeof publish === 'object' ? publish : null;
+  if (!p) return null;
+  const resolve = p.resolve === undefined || p.resolve === null ? 'session' : p.resolve;
+  const maxMinutes = Number.isFinite(p.resolveMaxMinutes) && p.resolveMaxMinutes > 0
+    ? p.resolveMaxMinutes
+    : DEFAULT_RESOLVE_MAX_MINUTES;
+  const agent = typeof p.resolveAgent === 'string' && p.resolveAgent ? p.resolveAgent : DEFAULT_RESOLVE_AGENT;
+  return { resolve, maxMinutes, agent };
+}
+
+/** R-R1: is this sync job a resolver candidate at all? */
+function candidateJob(syncState, job) {
+  const verdict = syncState && syncState.lastSync ? syncState.lastSync.verdict : null;
+  if (!CANDIDATE_VERDICTS.includes(verdict)) return null;
+  if (!job || job.kind !== 'sync') return null;
+  if (job.state !== 'blocked' && job.state !== 'failed') return null;
+  if (!job.base || !job.tip) return null;
+  return { verdict, key: jobKey(job) };
+}
+
+/** R-R7: has this key already been handled — live, ended, or in the history? */
+function alreadyHandled(key, current, history) {
+  if (current && current.key === key) return true;
+  return (history || []).some((row) => row && row.key === key);
+}
+
+/** The fresh `current` record a `start` begins with. */
+function newRecord({ job, verdict, nowMs, maxMinutes, agent }) {
+  const startedAt = isoOf(nowMs);
+  return {
+    key: jobKey(job),
+    trigger: verdict,
+    jobId: job.id || job.jobId || null,
+    conflictPaths: Array.isArray(job.conflictPaths) ? job.conflictPaths : [],
+    gateLog: job.gateLog === undefined ? null : job.gateLog,
+    base: job.base,
+    tip: job.tip,
+    sessionId: null,
+    branch: branchFor(job.tip),
+    worktree: null,
+    agent,
+    model: '',
+    modelSource: '',
+    state: 'starting',
+    startedAt,
+    deadlineAt: isoOf(nowMs + maxMinutes * 60 * 1000),
+    updatedAt: startedAt,
+    reason: '',
+  };
+}
+
+/**
+ * §13.4 R-R1/R-R7: the whole decision table, first match wins.
+ *
+ * `syncState`  parsed `<common>/landing/sync-state.json` (`{ lastSync: { verdict, at, jobId } }`);
+ * `job`        the job record for `lastSync.jobId` (or null);
+ * `publish`    normalized `config.publish` (`resolve`, `resolveAgent`, `resolveMaxMinutes`);
+ * `now`        ms epoch | Date | ISO string — the ONLY clock read here;
+ * `sessionAlive(id)` → boolean, for a live record's session.
+ *
+ * Returns `{ action, reason, record }`. A live record whose `owner` is `session:<id>` (§14 WP-13, a
+ * claim written by `land resolve <job> --claim`) is `keep`/`claimed`: the follower starts nothing.
+ * PURE — no fs, no `Date.now()`.
+ */
+function decide({ syncState, resolverState, job, publish, now, sessionAlive } = {}) {
+  const policy = publishPolicy(publish);
+  if (!policy || policy.resolve === 'off') return none('resolve_off');
+
+  const nowMs = nowToMs(now);
+  const state = resolverState && typeof resolverState === 'object' ? resolverState : emptyState();
+  const current = state.current && typeof state.current === 'object' ? state.current : null;
+  const history = Array.isArray(state.history) ? state.history : [];
+  const lastSync = syncState && syncState.lastSync ? syncState.lastSync : null;
+
+  // A live record owns the slot: finish it, end it, keep it, or leave it alone (R-R7/R-14.4).
+  if (current && LIVE_STATES.includes(current.state)) {
+    if (lastSync && SETTLED_VERDICTS.includes(lastSync.verdict)
+      && lastSync.at && current.startedAt
+      && Date.parse(lastSync.at) > Date.parse(current.startedAt)) {
+      return {
+        action: 'finish',
+        reason: 'sync_settled',
+        record: { ...current, state: 'done', reason: '', updatedAt: isoOf(nowMs) },
+      };
+    }
+    // §14 WP-13: a claimed record is never ended by session liveness — the claiming session's id is
+    // not necessarily in CTM's map at all (a shell/other-provider session can claim), so
+    // `session_closed` would drop a live claim on the very next tick and start the second resolver
+    // this rule exists to prevent. Its deadline below still retires it (AC-13c).
+    if (!claimedBySession(current) && typeof sessionAlive === 'function' && !sessionAlive(current.sessionId)) {
+      return {
+        action: 'give_up',
+        reason: 'session_closed',
+        record: { ...current, state: 'gave_up', reason: 'session_closed', updatedAt: isoOf(nowMs) },
+      };
+    }
+    if (current.deadlineAt && nowMs >= Date.parse(current.deadlineAt)) {
+      return {
+        action: 'give_up',
+        reason: 'deadline',
+        record: { ...current, state: 'gave_up', reason: 'deadline', updatedAt: isoOf(nowMs) },
+      };
+    }
+    // §14 WP-13 AC-13b: the key is owned by the user's own session — the follower starts nothing. The
+    // no-op action is the existing `keep` (R-14.4), so `apply()` writes nothing and `start()` is never
+    // reached; only the reason distinguishes a claim from a live resolver whose origin moved.
+    if (claimedBySession(current)) return { action: 'keep', reason: 'claimed', record: current };
+    const moved = candidateJob(syncState, job);
+    if (moved && moved.key && moved.key !== current.key) {
+      // §14.3 R-14.4: the record is LEFT in its live state and nothing is written — no queue nudge
+      // (the rev-3 R-R7 path had the same Enter defect as the start prompt, E-5). The brief's own
+      // step 4 re-runs `land sync` after `land resolve`, which picks up an origin that moved.
+      return { action: 'keep', reason: 'origin_moved', record: current };
+    }
+    return none('resolving', current);
+  }
+
+  // No live record: is this a brand-new candidate?
+  const candidate = candidateJob(syncState, job);
+  if (!candidate) return none('no_candidate', current);
+  if (alreadyHandled(candidate.key, current, history)) return none('already_handled', current);
+
+  return {
+    action: 'start',
+    reason: 'candidate',
+    record: newRecord({ job, verdict: candidate.verdict, nowMs, maxMinutes: policy.maxMinutes, agent: policy.agent }),
+  };
+}
+
+// --- briefFor() -----------------------------------------------------------------------------------
+
+/**
+ * §13.6: the resolver session's first prompt — deterministic from the record alone. `git push`
+ * appears exactly once, on the Never line (bin/landing-rule-lint.js fixture, S-R13).
+ */
+function briefFor(record) {
+  const r = record || {};
+  const base12 = short12(r.base);
+  const tip12 = short12(r.tip);
+  const lines = [];
+  lines.push(`You are this box's fleet-sync resolver. Job ${r.jobId}: local main ${base12} and origin/main ${tip12}`);
+  if (r.trigger === 'gate_failed') {
+    lines.push(`merge is clean but the gate failed; log: ${r.gateLog == null ? 'unknown' : r.gateLog}`);
+  } else {
+    lines.push(`conflict in: ${(Array.isArray(r.conflictPaths) ? r.conflictPaths : []).join(', ')}`);
+  }
+  lines.push(`1. In this worktree run \`git merge --no-ff ${r.tip}\` (ledger merge drivers and the .ctm.json landing.refresh commands run; never hand-edit a ledger — regenerate it with the command .ctm.json names).`);
+  lines.push('2. Resolve keeping BOTH sides\' intent; never drop either side\'s change; for append-only registries keep every row.');
+  lines.push('3. `git commit` (for a conflict the hook runs the fast resolver lane automatically). Never `--no-verify`.');
+  lines.push(`4. \`node coding-task-manager/bin/land.js resolve ${r.jobId} --worktree "$PWD" --wait --json\`, then \`node coding-task-manager/bin/land.js sync --wait --json\`. If either reports conflict/publish_contended: run \`land sync\` again and repeat from 1 on the new tips.`);
+  if (r.trigger === 'conflict') {
+    lines.push(`5. After it is published, verify with the full gate on what landed: \`node bin/bounded.js --deadline-ms 5400000 -- bash bin/test-gate.sh --commit --plan-base ${r.base}\`. On FAIL: fix on this branch, commit (normal gate), \`land submit\`, then \`land sync\`.`);
+  }
+  lines.push('Never: git push, git merge into main, update-ref main, --force, --no-verify, restarting CTM.');
+  lines.push('Report each verdict in one line.');
+  return `${lines.join('\n')}\n`;
+}
+
+// --- start() / apply() — injected effects ---------------------------------------------------------
+
+function reasonOf(error) {
+  if (!error) return 'unknown';
+  return error.code || error.message || String(error);
+}
+
+/**
+ * §13.5/R-R10 + §14.3 R-14.3: start one resolver session, in this exact order —
+ *   prepareWorkspace(baseRef = record.base) → resolvePick → briefFor(record) →
+ *   createSession(title `fleet-sync: resolve <tip12>`, argv, prompt = the brief) →
+ *   writeState(state `resolving`).
+ * The brief is built BEFORE the session exists and rides the launch argv as the CLI's positional
+ * prompt (R-14.3); there is no queue, no PTY typing and no Enter, so nothing can sit unsubmitted.
+ * Any step throwing ends the record `failed` with the error's code/message, writes it, notifies
+ * once, and returns the record — `start` NEVER throws (a failed resolver cannot kill the tick).
+ */
+async function start({ record, repoRoot, commonDir, deps }) {
+  const effects = deps || {};
+  const tip12 = short12(record && record.tip);
+  const prev = await readState(commonDir);
+  let current = { ...record, state: 'starting', updatedAt: isoOf(Date.now()) };
+  try {
+    const workspace = await effects.prepareWorkspace({
+      repoRoot,
+      baseRef: current.base,
+      worktreeName: worktreeNameFor(current.tip),
+      branchName: current.branch,
+    });
+    current = { ...current, worktree: workspace && workspace.cwd ? workspace.cwd : null };
+    if (workspace && workspace.branch) current.branch = workspace.branch;
+
+    const pick = await effects.resolvePick({ agent: current.agent });
+    current = {
+      ...current,
+      model: pick && pick.model ? pick.model : '',
+      modelSource: pick && pick.source ? pick.source : '',
+    };
+
+    // Built from the record alone, so it is known before the session exists (R-14.3).
+    const brief = briefFor(current);
+    const session = await effects.createSession({
+      cwd: current.worktree,
+      agent: current.agent,
+      model: current.model,
+      title: `fleet-sync: resolve ${tip12}`,
+      argv: pick && Array.isArray(pick.argv) ? pick.argv : [],
+      prompt: brief,
+    });
+    current = { ...current, sessionId: session && session.sessionId ? session.sessionId : null };
+
+    current = { ...current, state: 'resolving', updatedAt: isoOf(Date.now()) };
+    await writeState(commonDir, stateWith(prev, current));
+    return current;
+  } catch (error) {
+    const failed = { ...current, state: 'failed', reason: reasonOf(error), updatedAt: isoOf(Date.now()) };
+    await writeState(commonDir, stateWith(prev, failed));
+    try {
+      if (typeof effects.notify === 'function') {
+        await effects.notify({
+          title: 'fleet sync resolver failed',
+          body: `could not start the resolver for job ${failed.jobId}: ${failed.reason}`,
+          sessionId: failed.sessionId || null,
+        });
+      }
+    } catch { /* expected: the failure notice is itself best-effort — start() never throws */ }
+    return failed;
+  }
+}
+
+/**
+ * §13.5/R-R7: execute one `decide()` result.
+ *   start        → start(); the new record.
+ *   finish/give_up → move `current` to `history` with that state, writeState;
+ *                    give_up also notifies once (R-R8).
+ *   keep/none    → nothing (R-14.4: the nudge path is gone, so a live `origin_moved` record is a
+ *                  pure no-op — no prompt, no state write).
+ */
+async function apply({ decision, repoRoot, commonDir, deps } = {}) {
+  const effects = deps || {};
+  const result = decision || { action: 'none' };
+  const prev = await readState(commonDir);
+
+  if (result.action === 'start') {
+    return start({ record: result.record, repoRoot, commonDir, deps: effects });
+  }
+
+  if (result.action === 'finish' || result.action === 'give_up') {
+    const ended = result.record || {};
+    const record = { ...ended, state: result.action === 'finish' ? 'done' : 'gave_up', updatedAt: isoOf(Date.now()) };
+    const history = [record, ...(prev.history || [])].slice(0, HISTORY_LIMIT);
+    await writeState(commonDir, { contract: CONTRACT, current: null, history });
+    if (result.action === 'give_up' && typeof effects.notify === 'function') {
+      const paths = (Array.isArray(record.conflictPaths) ? record.conflictPaths : []).join(', ');
+      await effects.notify({
+        title: 'fleet sync needs you',
+        body: `conflict in ${paths} on ${short12(record.tip)} — resolver ${result.reason}`,
+        sessionId: record.sessionId || null,
+      });
+    }
+    return record;
+  }
+
+  // `keep` (R-14.4 origin_moved) and `none` write nothing: the live record stays exactly as it is.
+  return null;
+}
+
+module.exports = {
+  CONTRACT,
+  DEFAULT_RESOLVE_MAX_MINUTES,
+  DEFAULT_RESOLVE_AGENT,
+  HISTORY_LIMIT,
+  resolverPath,
+  jobKey,
+  branchFor,
+  worktreeNameFor,
+  claimedBySession,
+  readState,
+  writeState,
+  decide,
+  start,
+  apply,
+  briefFor,
+};

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

@@ -0,0 +1,114 @@
+'use strict';
+
+// WP-2 (docs/fleet-session-lists-hub-search-2026-11-01.html §5 D-9/D-11, §6.2-§6.3, §8 WP-2,
+// §9 S-7/S-8): the two session-list route SPECS, and their registration into WP-1's
+// FLEET_LIST_ROUTES map.
+//
+// The specs are deliberately plain data. lib/fleet-session-lists.js `fleetRouted()` owns every
+// rule that is hard to get right (D-2 fan-out, D-4 dedup, D-6 envelope, D-8 stale-if-error,
+// D-10 provenance) — this module only says, per route:
+//   - which key of the local body holds the row array (`rowsKey`);
+//   - how a row is keyed for dedup (`rowId`);
+//   - how the caller's `limit` is read and clamped (`limitOf`);
+//   - which ORDER the merged rows keep — the route's own existing order, re-applied over the
+//     union of every machine's rows (D-9: one comparator, never a cross-machine RRF);
+//   - whether D-8 stale-if-error applies (`lastGood`), and what "unfiltered" means (`unfiltered`);
+//   - `select` = the local route's own selection rule, run over the deduped union.
+//
+// Registering is a module-load side effect (`registerFleetListRoutes()` at the bottom) so
+// lib/api/sessions.js only has to `require()` this file before it reads the map.
+
+const { FLEET_LIST_ROUTES } = require('./fleet-session-lists');
+const {
+  normalizeRecentCatalogShape,
+  selectRecentCatalogRows,
+} = require('./recent-session-catalog-response');
+// The ONE search-hit comparator, required exactly the way the server requires it
+// (server.js:2179) so a merged fleet order equals single-DB order (D-9) by construction.
+const SessionSearchUtils = require('../public/js/session-search-utils.js');
+
+const RECENT_SESSIONS_ROUTE = 'GET /api/recent-sessions';
+const SESSION_SEARCH_ROUTE = 'GET /api/sessions/search';
+
+/** The same clamp `buildSessionSearchResponse` applies (lib/api/session-messages.js:1013). */
+const MAX_SESSION_SEARCH_LIMIT = 100;
+const DEFAULT_SESSION_SEARCH_LIMIT = 50;
+
+/**
+ * D-4 (`sessionId || id`): both list shapes carry a session id under one of these two names, and
+ * a row with neither is left unkeyed (kept, never merged) — same rule as
+ * lib/fleet-session-lists.js `defaultRowId`, narrowed to the two keys these routes actually emit.
+ */
+function listRowId(row) {
+  return String((row && (row.sessionId || row.id)) || '');
+}
+
+/**
+ * §6.2/§6.3: GET /api/recent-sessions.
+ *
+ * `limitOf` is the route's own limit rule — `normalizeRecentCatalogShape` (1..500, default 50) —
+ * so the merged list is sliced exactly where the single-machine list is.
+ *
+ * `select` is `selectRecentCatalogRows` (WP-0, extracted from `buildRecentSessionCatalogResponse`):
+ * activityMs desc, then starred/pinned rows kept past the limit (D-9). The owner filter is NOT
+ * re-applied here — the hub's own leg already ran with no `owner`, and D-4 already dropped the
+ * copies of our sessions at the box boundary.
+ *
+ * `lastGood: true` + `unfiltered` (no `q`) = D-8's cache eligibility: an unfiltered Recent list is
+ * the same query for every caller, so a down box's last good rows may be re-served as `stale`.
+ */
+const recentSessionsSpec = {
+  rowsKey: 'sessions',
+  rowId: listRowId,
+  limitOf: (url) => normalizeRecentCatalogShape({ limit: url.searchParams.get('limit') || 50 }).limit,
+  select: (rows, { limit }) => selectRecentCatalogRows(rows, { limit }),
+  lastGood: true,
+  unfiltered: (url) => !url.searchParams.get('q'),
+};
+
+/**
+ * §6.2/§6.3: GET /api/sessions/search.
+ *
+ * `limitOf` is the same 1..100 clamp `buildSessionSearchResponse` uses, so a forwarded leg and the
+ * local leg slice identically.
+ *
+ * `select` is `SessionSearchUtils.compareSearchHits` over the deduped union (D-9), then the limit.
+ * `lastGood: false`: search hits are query-keyed with a low hit rate, so D-8 never caches them.
+ */
+const sessionSearchSpec = {
+  rowsKey: 'results',
+  rowId: listRowId,
+  limitOf: (url) => {
+    const requested = parseInt(url.searchParams.get('limit') || String(DEFAULT_SESSION_SEARCH_LIMIT), 10);
+    return Math.min(Math.max(requested || DEFAULT_SESSION_SEARCH_LIMIT, 1), MAX_SESSION_SEARCH_LIMIT);
+  },
+  select: (rows, { limit }) => rows.slice().sort(SessionSearchUtils.compareSearchHits).slice(0, limit),
+  lastGood: false,
+};
+
+/**
+ * Fill FLEET_LIST_ROUTES (§6.2/§7). Idempotent — assigning the same two spec objects again is a
+ * no-op — and called once at module load, so a plain `require()` of this file is enough for the
+ * router wiring and for the §7 census gate (tests-integration/fleet-session-lists-census.test.js).
+ */
+function registerFleetListRoutes() {
+  FLEET_LIST_ROUTES[RECENT_SESSIONS_ROUTE] = recentSessionsSpec;
+  FLEET_LIST_ROUTES[SESSION_SEARCH_ROUTE] = sessionSearchSpec;
+  return FLEET_LIST_ROUTES;
+}
+
+registerFleetListRoutes();
+
+module.exports = {
+  RECENT_SESSIONS_ROUTE,
+  SESSION_SEARCH_ROUTE,
+  // The same object lib/fleet-session-lists.js exports (identity matters: the router and the §7
+  // census read THIS map), re-exported so a caller needs one require to wire the routes.
+  FLEET_LIST_ROUTES,
+  // Re-exported so lib/api/sessions.js wires both rows with one require (its file-size ceiling).
+  fleetRouted: require('./fleet-session-lists').fleetRouted,
+  listRowId,
+  recentSessionsSpec,
+  sessionSearchSpec,
+  registerFleetListRoutes,
+};