create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/public/js/core/active-session-groups.js

@@ -0,0 +1,179 @@
+//@provides: ACTIVE_SORT_MODES, ACTIVE_LOCAL_COMPUTER_LABEL, normalizeActiveSort, activeSortIsGrouped, activeComputerGroupKey, activeComputerGroupLabels, compareActiveComputerGroups, activeComputerFilterPasses, activeComputerMenuModel, applyActiveComputerOptgroup, parseActiveComputerOptionValue, activeComputerFilterChipHtml, activeProjectHeaderHtml, activeGroupHeaderHtml, sortActiveGroupedSessions
+// Active Sessions grouping (docs/active-sessions-group-by-computer-2026-10-30.html §5 D-1, §6).
+// ONE module owns the sort-mode allow-list, the grouped mode (by_project), its group ordering and
+// header markup, and (rev 2) the computer FILTER helpers, so index.html holds no copy of the mode list.
+// No module state; pure except applyActiveComputerOptgroup, which writes the passed-in select. Dual browser/node (worker-tree.js pattern): browser globals, plus
+// module.exports for tests. Loaded AFTER js/core/session-commands.js, whose sessionMachineFacts and
+// MACHINE_HEALTH_UNREACHABLE are the ONLY readers of the machine fields (no hostname parsing).
+
+const ACTIVE_SORT_MODES = ['by_activity', 'tab_order', 'by_project'];
+const ACTIVE_LOCAL_COMPUTER_LABEL = 'Local';
+
+// A member of ACTIVE_SORT_MODES, else 'by_activity' (D-11).
+function normalizeActiveSort(mode) {
+  return ACTIVE_SORT_MODES.includes(mode) ? mode : 'by_activity';
+}
+
+function activeSortIsGrouped(mode) {
+  return mode === 'by_project';
+}
+
+// entries are the renderer's [id, session] pairs; a bare session row is accepted too.
+function _activeGroupRow(entry) {
+  return Array.isArray(entry) ? entry[1] : entry;
+}
+
+// D-2: the hub-stamped instanceId; '' is the local machine.
+function activeComputerGroupKey(s) {
+  return sessionMachineFacts(s).machine;
+}
+
+// D-3: '' -> 'Local'; else the first non-empty machineName among the key's rows, else the key.
+// Labels that collide get ' · ' + key.slice(0, 6) so two machines are never indistinguishable.
+function activeComputerGroupLabels(entries) {
+  const names = new Map();
+  for (const entry of entries || []) {
+    const facts = sessionMachineFacts(_activeGroupRow(entry));
+    if (!names.has(facts.machine)) names.set(facts.machine, '');
+    if (!names.get(facts.machine) && facts.name) names.set(facts.machine, facts.name);
+  }
+  const labels = new Map();
+  for (const [key, name] of names) {
+    labels.set(key, key === '' ? ACTIVE_LOCAL_COMPUTER_LABEL : (name || key));
+  }
+  const seen = new Map();
+  for (const label of labels.values()) seen.set(label, (seen.get(label) || 0) + 1);
+  for (const [key, label] of labels) {
+    if (seen.get(label) > 1) labels.set(key, label + ' · ' + key.slice(0, 6));
+  }
+  return labels;
+}
+
+// D-4: Local first, then by label (case-insensitive, numeric-aware), ties broken by key.
+function compareActiveComputerGroups(a, b, labels) {
+  if (a === b) return 0;
+  if (a === '') return -1;
+  if (b === '') return 1;
+  const la = (labels && labels.get(a)) || a;
+  const lb = (labels && labels.get(b)) || b;
+  const byLabel = la.localeCompare(lb, undefined, { sensitivity: 'base', numeric: true });
+  if (byLabel !== 0) return byLabel;
+  return a < b ? -1 : 1;
+}
+
+// F-6: a session passes when the filter is null (all computers) or its machine key equals the filter.
+function activeComputerFilterPasses(s, filter) {
+  return filter === null || filter === undefined || activeComputerGroupKey(s) === filter;
+}
+
+// F-3/F-4/F-5: the Computers optgroup model. entries are [id, session] pairs (or bare rows).
+// options: All computers, Local, then machines; "✓ " prefixes exactly the active one.
+function activeComputerMenuModel(entries, filter, lastLabels) {
+  const active = typeof filter === 'string' ? filter : null;
+  const labels = activeComputerGroupLabels(entries);
+  const keys = new Set(labels.keys());
+  if (active !== null && !keys.has(active)) {
+    keys.add(active);
+    labels.set(active, (lastLabels && lastLabels.get(active)) || (active === '' ? ACTIVE_LOCAL_COMPUTER_LABEL : active));
+  }
+  const show = keys.size > 1 || active !== null || (keys.size === 1 && !keys.has(''));
+  const ordered = Array.from(keys).sort((a, b) => compareActiveComputerGroups(a, b, labels));
+  const mark = (on, text) => (on ? '✓ ' : '') + text;
+  const options = [{ value: 'computer:*', text: mark(active === null, 'All computers') }];
+  const sigRows = [];
+  for (const k of ordered) {
+    const label = labels.get(k);
+    sigRows.push([k, label]);
+    options.push({ value: 'computer:' + k, text: mark(active === k, label) });
+  }
+  return { show, signature: JSON.stringify([active, sigRows]), options, labels };
+}
+
+// F-5: rewrite the Computers optgroup of `sel` only when the model signature differs from prevSig; returns the
+// signature now in effect. Option text goes through new Option (no HTML parsing).
+function applyActiveComputerOptgroup(sel, model, prevSig) {
+  const sig = (model.show ? '1' : '0') + model.signature;
+  if (sig === prevSig) return prevSig;
+  const old = sel.querySelector('optgroup[label="Computers"]');
+  if (old) old.remove();
+  if (!model.show) return sig;
+  const grp = document.createElement('optgroup');
+  grp.label = 'Computers';
+  for (const o of model.options) grp.appendChild(new Option(o.text, o.value));
+  sel.appendChild(grp);
+  return sig;
+}
+
+// 'computer:*' -> null (all), 'computer:' -> '' (Local), 'computer:<id>' -> '<id>', anything else -> undefined.
+function parseActiveComputerOptionValue(v) {
+  if (typeof v !== 'string' || !v.startsWith('computer:')) return undefined;
+  const rest = v.slice('computer:'.length);
+  return rest === '*' ? null : rest;
+}
+
+// The Projects header, moved here verbatim from renderSessionList. opts adds iconHtml (the folder glyph,
+// which stays in index.html). Its markup, data-project-key and aria-label text are frozen.
+function activeProjectHeaderHtml(opts) {
+  const { key, count, collapsed, hasActive, iconHtml, escHtml, jsArg } = opts;
+  const label = opts.label || '(no project)';
+  const title = key || 'No project directory';
+  const verb = collapsed ? 'Expand' : 'Collapse';
+  return `<button type="button" class="session-group-sep project-sep${collapsed ? ' collapsed' : ''}${hasActive ? ' has-active' : ''}" data-project-key="${escHtml(key)}" title="${escHtml(title)}" aria-expanded="${collapsed ? 'false' : 'true'}" aria-label="${verb} ${escHtml(label)} project group, ${count} active session${count === 1 ? '' : 's'}" onclick="toggleActiveProjectGroup('${jsArg(key)}', event)"><span class="project-sep-chevron" aria-hidden="true">▾</span>${iconHtml}<span class="project-sep-label">${escHtml(label)}</span><span class="project-sep-count">${count}</span></button>`;
+}
+
+// One entry point for the grouped header (project only since rev 2). opts as activeProjectHeaderHtml.
+function activeGroupHeaderHtml(mode, opts) {
+  return activeProjectHeaderHtml(opts);
+}
+
+// Sorts `sessions` ([id, session] pairs) IN PLACE for a grouped mode and returns
+// { keyOf, labels, unitPrefix } for the caller's header emission. deps:
+//   bucketOf(id, s) -> status bucket, projectKey(s), projectLabels(keys) -> Map, lastActivityMs(s),
+//   compareRows(a, b) -> the within-group comparator (status, then display order).
+// by_project: the project with the most urgent session (best status rank, then most recent) floats
+// up.
+function sortActiveGroupedSessions(mode, sessions, deps) {
+  const ranks = (typeof SessionActivityUtils !== 'undefined' && SessionActivityUtils.ACTIVE_STATUS_RANK)
+    ? SessionActivityUtils.ACTIVE_STATUS_RANK
+    : { running: 0, resuming: 1, waiting: 2, idle: 3, exited: 4 };
+  const projectAgg = new Map(); // key -> { rank, recent }
+  for (const [id, s] of sessions) {
+    const k = deps.projectKey(s);
+    const rank = ranks[deps.bucketOf(id, s)] ?? 4;
+    const recent = deps.lastActivityMs(s);
+    const cur = projectAgg.get(k) || { rank: 99, recent: 0 };
+    if (rank < cur.rank) cur.rank = rank;
+    if (recent > cur.recent) cur.recent = recent;
+    projectAgg.set(k, cur);
+  }
+  const labels = deps.projectLabels(Array.from(projectAgg.keys()));
+  sessions.sort((a, b) => {
+    const ka = deps.projectKey(a[1]);
+    const kb = deps.projectKey(b[1]);
+    if (ka !== kb) {
+      const ga = projectAgg.get(ka);
+      const gb = projectAgg.get(kb);
+      if (ga.rank !== gb.rank) return ga.rank - gb.rank;
+      if (ga.recent !== gb.recent) return gb.recent - ga.recent;
+      return ka < kb ? -1 : 1;
+    }
+    return deps.compareRows(a, b);
+  });
+  return { keyOf: deps.projectKey, labels, unitPrefix: 'psep:' };
+}
+
+// G-3: removable filter chip markup; the label is escaped here, never trusted.
+function activeComputerFilterChipHtml({ label, escHtml }) {
+  const l = escHtml(String(label == null ? '' : label));
+  return '<button type="button" class="computer-filter-chip" aria-label="Remove computer filter: ' + l +
+    '" title="Showing only ' + l + ' \u2014 click to show all computers" onclick="setActiveComputerFilter(null)">\u25c8 ' + l +
+    ' <span aria-hidden="true">\u2715</span></button>';
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    ACTIVE_SORT_MODES, ACTIVE_LOCAL_COMPUTER_LABEL, normalizeActiveSort, activeSortIsGrouped, activeComputerGroupKey,
+    activeComputerGroupLabels, compareActiveComputerGroups, activeComputerFilterPasses, activeComputerMenuModel,
+    activeComputerFilterChipHtml, applyActiveComputerOptgroup, parseActiveComputerOptionValue, activeProjectHeaderHtml, activeGroupHeaderHtml, sortActiveGroupedSessions,
+  };
+}

package/template/coding-task-manager/public/js/core/pending-create.js

@@ -0,0 +1,238 @@
+//@provides: PendingCreate
+//@needs: toast, clearToastByKey, send, activateTab
+// WP-1 (coding-task-manager/docs/session-create-accept-then-complete-2026-11-01.html §5 D-1/D-7,
+// §6.4, §8 WP-1, §9 S-11/S-12).
+//
+// The 2026-11-01 15:33Z incident: the New Session flow sent `create` with no id, so when the hub's
+// 15 s phase-A wait expired and reported `machine_unreachable` "timeout" the client had no way to
+// match the box's later, successful session to the click — the tab is activated only inside
+// onCreated, and the orphaned success never opened one. This module owns the client half of the
+// fix: the id the client mints (D-1) and the pending entry that reconciles the click with whatever
+// arrives later (D-7 — a `created`, an `error`, the session appearing in a sessions list, or the TTL).
+// Adoption from a list is deliberately restricted to entries whose `created` cannot be coming
+// ('unconfirmed' / 'orphaned'): a list can race ahead of the `created` frame, and adopting a
+// still-'pending' entry would activate its lazy stub and then let onCreated activate the id again.
+//
+// It reads the global `state` object (public/index.html:3627) at CALL time only, and calls the
+// page's toast / clearToastByKey / send / activateTab globals, so loading it right after
+// 02-toast.js is enough. `_now` is the clock seam the unit tests pin.
+var PendingCreate = (function buildCtmPendingCreate() {
+  const TTL_MS = 600000; // D-7
+  // id -> { id, machine, machineName, label, activeTabAtClick, clickedAt, acceptedAt, state }
+  const entries = new Map();
+
+  const createKey = (id) => 'create-pending:' + id;
+  const readyKey = (id) => 'create-ready:' + id;
+  const nowMs = () => Number(PendingCreate._now()) || 0;
+  const machineClause = (entry) => (entry.machine ? ' on ' + entry.machineName : '');
+
+  function showToast(type, text, key, duration) {
+    if (typeof toast !== 'function') return;
+    const opts = { type: type, key: key };
+    if (duration) opts.duration = duration;
+    toast(text, opts);
+  }
+
+  function clearPendingToast(id) {
+    if (typeof clearToastByKey === 'function') clearToastByKey(createKey(id));
+  }
+
+  function settleTimings(entry, settledAt) {
+    return {
+      clickToAcceptedMs: entry.acceptedAt >= 0 ? Math.max(0, entry.acceptedAt - entry.clickedAt) : -1,
+      clickToSettledMs: Math.max(0, settledAt - entry.clickedAt),
+    };
+  }
+
+  const HEX = '0123456789abcdef';
+
+  // RFC 4122 §4.4: version 4 in the high nibble of byte 6, variant 10 in the top bits of byte 8.
+  function formatUuidV4(bytes) {
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    let out = '';
+    for (let i = 0; i < 16; i += 1) {
+      out += HEX[(bytes[i] >> 4) & 0x0f] + HEX[bytes[i] & 0x0f];
+      if (i === 3 || i === 5 || i === 7 || i === 9) out += '-';
+    }
+    return out;
+  }
+
+  // One `client-diag` / `create-ready` row per settled entry (§6.4). The server's
+  // lib/client-diag-handler.js turns it into one `[create-client]` line.
+  function emitDiag(entry, outcome) {
+    if (typeof send !== 'function') return;
+    const timings = settleTimings(entry, nowMs());
+    send({
+      type: 'client-diag',
+      event: 'create-ready',
+      id: entry.id,
+      details: {
+        machine: entry.machine,
+        outcome: outcome,
+        clickToAcceptedMs: timings.clickToAcceptedMs,
+        clickToSettledMs: timings.clickToSettledMs,
+      },
+    });
+  }
+
+  function drop(id) {
+    entries.delete(id);
+  }
+
+  return {
+    TTL_MS: TTL_MS,
+    // Test seam: the unit tests replace this with a fake clock. Nothing else may.
+    _now: function () { return Date.now(); },
+
+    /** The create id the client mints (D-1). `crypto.randomUUID` is SECURE-CONTEXT ONLY, so a hub
+     *  opened over plain http on a LAN address has no such function — it falls back to
+     *  `crypto.getRandomValues`, which is available in every context, and a sandbox with no crypto
+     *  at all falls back to Math.random. Always the 36-char 8-4-4-4-12 lowercase v4 form. */
+    newId: function () {
+      const cryptoApi = (typeof crypto === 'object' && crypto) ? crypto : null;
+      if (cryptoApi && typeof cryptoApi.randomUUID === 'function') return String(cryptoApi.randomUUID());
+      const bytes = new Array(16);
+      if (cryptoApi && typeof cryptoApi.getRandomValues === 'function' && typeof Uint8Array === 'function') {
+        const seed = new Uint8Array(16);
+        cryptoApi.getRandomValues(seed);
+        for (let i = 0; i < 16; i += 1) bytes[i] = seed[i];
+      } else {
+        for (let i = 0; i < 16; i += 1) bytes[i] = Math.floor(Math.random() * 256);
+      }
+      return formatUuidV4(bytes);
+    },
+
+    /** Called by _doCreate before send(). Shows toast(info) key 'create-pending:'+id,
+     *  text "Starting <label> on <machineName>…" (or "Starting <label>…" for a local create),
+     *  duration TTL_MS. */
+    begin: function (opts) {
+      const options = opts || {};
+      const id = String(options.id || '');
+      if (!id) return null;
+      const machine = String(options.machine || '');
+      const entry = {
+        id: id,
+        machine: machine,
+        machineName: String(options.machineName || machine || 'This Mac'),
+        label: String(options.label || '').trim() || 'New session',
+        activeTabAtClick: options.activeTabAtClick === undefined ? null : options.activeTabAtClick,
+        clickedAt: nowMs(),
+        acceptedAt: -1,
+        state: 'pending',
+      };
+      entries.set(id, entry);
+      showToast('info', 'Starting ' + entry.label + machineClause(entry) + '…', createKey(id), TTL_MS);
+      return entry;
+    },
+
+    /** 'create-accepted' with a pending id: replaces the toast text with
+     *  "Starting <label> on <machineName> (load <load1> on <cores> cores)…"; records acceptedAt.
+     *  Returns true if pending. */
+    accepted: function (msg) {
+      const entry = msg ? entries.get(String(msg.id || '')) : null;
+      if (!entry) return false;
+      entry.state = 'accepted';
+      if (entry.acceptedAt < 0) entry.acceptedAt = nowMs();
+      const hasLoad = msg.load1 !== undefined && msg.load1 !== null && msg.cores !== undefined
+        && msg.cores !== null && Number.isFinite(Number(msg.load1)) && Number.isFinite(Number(msg.cores));
+      const loadClause = hasLoad ? ' (load ' + Number(msg.load1) + ' on ' + Number(msg.cores) + ' cores)' : '';
+      showToast('info', 'Starting ' + entry.label + machineClause(entry) + loadClause + '…',
+        createKey(entry.id), TTL_MS);
+      return true;
+    },
+
+    /** 'created' with a pending id: clears toast + entry, emits diag outcome 'created'. Returns true
+     *  if it was pending. Activation stays in onCreated, unchanged. */
+    settleCreated: function (msg) {
+      const id = msg ? String(msg.id || '') : '';
+      const entry = id ? entries.get(id) : null;
+      if (!entry) return false;
+      drop(id);
+      clearPendingToast(id);
+      emitDiag(entry, 'created');
+      return true;
+    },
+
+    /** 'error' with a pending id. code === 'machine_create_unconfirmed': toast(warning) key
+     *  'create-pending:'+id, "<label> is still starting on <machineName>; it will open when ready",
+     *  keeps the entry, returns true (caller skips the Machine error toast). Any other code: clears
+     *  entry + pending toast, emits diag 'failed', returns false (caller's existing toast runs).
+     *
+     *  An id-less `machine_*` error naming a machine is the OLD hub's shape (its phase-A timeout
+     *  carries no id, §8 "new client, old hub"): every entry still waiting on that machine becomes
+     *  'orphaned', which is what lets the next sessions list adopt it. Always returns false, so the
+     *  caller's existing Machine error toast still runs. */
+    settleError: function (msg) {
+      const id = msg ? String(msg.id || '') : '';
+      const entry = id ? entries.get(id) : null;
+      if (entry) {
+        if (msg.code === 'machine_create_unconfirmed') {
+          entry.state = 'unconfirmed';
+          showToast('warning',
+            entry.label + ' is still starting' + machineClause(entry) + '; it will open when ready',
+            createKey(id));
+          return true;
+        }
+        drop(id);
+        clearPendingToast(id);
+        emitDiag(entry, 'failed');
+        return false;
+      }
+      if (!id && msg && typeof msg.machine === 'string' && msg.machine !== ''
+        && /^machine_/.test(String(msg.code || ''))) {
+        for (const candidate of entries.values()) {
+          if (candidate.machine === msg.machine
+            && (candidate.state === 'pending' || candidate.state === 'accepted')) {
+            candidate.state = 'orphaned';
+          }
+        }
+      }
+      return false;
+    },
+
+    /** Adopts only an entry whose `created` is known not to be coming — state 'unconfirmed'
+     *  (machine_create_unconfirmed) or 'orphaned' (an id-less machine error). An entry that is still
+     *  'pending'/'accepted' is left alone even when the list already carries its id: the server can
+     *  broadcast a sessions list BEFORE the `created` frame, and adopting it here would activate the
+     *  lazy stub and then let onCreated activate the same id again.
+     *
+     *  For each adoptable id present in sessions: if state.activeTab === entry.activeTabAtClick →
+     *  activateTab(id), else toast(info) "<label> is ready on <machineName>" key 'create-ready:'+id;
+     *  clears entry, emits diag 'adopted'. Also drops entries older than TTL_MS (diag 'expired'). */
+    adoptFromList: function (sessions) {
+      const list = Array.isArray(sessions) ? sessions : [];
+      const present = new Set();
+      for (const row of list) {
+        if (row && row.id !== undefined && row.id !== null && row.id !== '') present.add(String(row.id));
+      }
+      const settledAt = nowMs();
+      const ttl = Number(PendingCreate.TTL_MS) || 0;
+      for (const id of Array.from(entries.keys())) {
+        const entry = entries.get(id);
+        if (!entry) continue;
+        if (present.has(id) && (entry.state === 'unconfirmed' || entry.state === 'orphaned')) {
+          // Drop the entry BEFORE activating: activation happens once, ever, even if activateTab
+          // synchronously provokes another sessions list.
+          drop(id);
+          clearPendingToast(id);
+          const activeTab = (typeof state === 'object' && state) ? state.activeTab : undefined;
+          if (activeTab === entry.activeTabAtClick) {
+            if (typeof activateTab === 'function') activateTab(id);
+          } else {
+            showToast('info', entry.label + ' is ready on ' + entry.machineName, readyKey(id));
+          }
+          emitDiag(entry, 'adopted');
+          continue;
+        }
+        // A 'pending'/'accepted' entry is never adopted, so its TTL is the only other way out.
+        if (settledAt - entry.clickedAt > ttl) {
+          // D-7: dropped silently — the session, if any, is already a normal list row by now.
+          drop(id);
+          clearPendingToast(id);
+          emitDiag(entry, 'expired');
+        }
+      }
+    },
+  };
+})();

package/template/coding-task-manager/public/js/core/recent-machine-source.js

@@ -0,0 +1,228 @@
+//@provides: recentSourceKey, recentSourceForFilter, recentRequestUrl, stampRecentRowsFromMachine, recentMachineUnavailableText, recentMachineLoad, beginRecentLoad, recentSourceChanged, fetchMachineRecentRows, stampRecentBodyFromSource, recentNoteFleetBody, recentFleetStatusText, renderRecentFleetStatus
+// Recent Sessions machine routing (docs/recent-sessions-follow-computer-filter-2026-10-31.html §5 D-1..D-4, §6,
+// superseded for the All/Local mapping by docs/fleet-session-lists-hub-search-2026-11-01.html §5 D-11).
+// ONE module owns the decisions the Recent list makes once the Active Sessions "Computers" filter names a
+// paired box: which source answers (D-1 — that box's own list, never a hub merge), how the request is
+// spelled (D-2 — the existing ?machine= hub proxy), how the box's rows are stamped with their provenance
+// (D-3), what is said when the box cannot answer (D-4 — named, never "empty"), and which response is
+// still current (D-5 — a request token, never timing). Dual browser/node (active-session-groups.js
+// pattern): browser globals, plus module.exports for tests. Loaded AFTER js/core/active-session-groups.js.
+
+// D-11 (fleet-session-lists-hub-search-2026-11-01.html §5 D-11, supersedes the 10-31 D-1 mapping for
+// null): null = All computers -> the FLEET source (this hub fans out to every box, D-1..D-6); '' =
+// Local -> the hub's own list; a non-empty string = that box's own list. Any other non-string value
+// stays the hub, exactly as before.
+function recentSourceForFilter(filter) {
+  if (filter === null) return { kind: 'fleet' };
+  return typeof filter === 'string' && filter !== ''
+    ? { kind: 'machine', machine: filter }
+    : { kind: 'hub' };
+}
+
+// D-2/D-11: the query fragment that names the source. A fleet source adds &scope=fleet (this is the
+// one place the parameter is spelled); a hub source appends nothing, so Local/All-but-fleet keeps its
+// exact current URL. A box is ALSO asked for owner=self — without it the box answers with every row
+// it holds, including its copies of the hub's own sessions (151 of Spark's top 200, §1.1), which then
+// render as the box's. The box filters before its limit, so the list is that box's own top-N.
+function recentRequestUrl(base, source) {
+  if (source && source.kind === 'fleet') return base + '&scope=fleet';
+  return source && source.kind === 'machine'
+    ? base + '&machine=' + encodeURIComponent(source.machine) + '&owner=self'
+    : base;
+}
+
+// D-3: a box's own rows carry no machine key — they are local to the box. Stamping is by PROVENANCE
+// (which request returned the row), never inferred from the row's content. Returns a new array.
+function stampRecentRowsFromMachine(rows, machine, machineName) {
+  return (rows || []).map((row) => Object.assign({}, row, { machine, machineName }));
+}
+
+// D-4: the Recent empty state's copy when the box did not answer. 2xx -> '' (nothing to say). 404 /
+// machine_unknown -> the pairing is gone. Anything else (502 machine_unreachable, 503
+// peer_credential_missing, 0 / a fetch timeout) -> unreachable. A failed source is NEVER rendered as
+// an empty hub list (agentic-dev-framework#10, §3).
+function recentMachineUnavailableText(status, code, machineName) {
+  const name = machineName || 'This computer';
+  const s = Number(status) || 0;
+  if (s >= 200 && s < 300) return '';
+  if (s === 404 || code === 'machine_unknown') return name + ' is no longer paired.';
+  return name + " is unreachable — its recent sessions can't be listed right now.";
+}
+
+// D-5 + D-4: the load epoch. `machine` is the box the CURRENT load answers for (undefined when the
+// source is not a box), `key` is the full source identity (kind + box id) a re-render compares
+// against, `token` its epoch, `unavailable` the named failure the empty state shows ('' = none).
+// Kept here, not in index.html, so the inline script gains call sites only.
+const recentMachineLoad = { token: 0, machine: undefined, key: '', unavailable: '' };
+
+/** D-11: one comparable identity per source — All, Local and box A are now three distinct sources. */
+function recentSourceKey(source) {
+  return source.kind + ':' + (source.machine || '');
+}
+
+// Every Recent load (hub, box or fleet) opens a new epoch and clears the previous failure text.
+// Returns the source it answers for plus the token a response must still match to be applied.
+function beginRecentLoad(filter) {
+  const source = recentSourceForFilter(filter);
+  recentMachineLoad.token += 1;
+  recentMachineLoad.machine = source.machine;
+  recentMachineLoad.key = recentSourceKey(source);
+  recentMachineLoad.unavailable = '';
+  return { source, token: recentMachineLoad.token };
+}
+
+// D-5/D-11: did the filter move the SOURCE? All (fleet) <-> Local (hub) is a source change now that
+// null is the fleet, while box A <-> box B still is — so a comparison on the machine alone would
+// silently keep the previous list. Compare the source KEY instead.
+function recentSourceChanged(filter) {
+  return recentSourceKey(recentSourceForFilter(filter)) !== recentMachineLoad.key;
+}
+
+// D-7/D-11: one status line per member that did NOT answer `ok` (self is always `ok`, so it never
+// produces a line). A silent empty list for a box that failed is the bug this copy exists to kill
+// (§2.6). `status` values come from the fleet envelope (lib/fleet-session-lists.js FLEET_STATUSES).
+const FLEET_STATUS_UNIT_MIN = 60;
+const FLEET_STATUS_UNIT_HOUR = 60;
+const FLEET_STATUS_UNIT_DAY = 24;
+
+/** D-7: a short, floor-rounded age — `N s` / `N min` / `N h` / `N d`, never "just now", min 1 unit. */
+function relativeAge(ms) {
+  const value = Number(ms);
+  const seconds = Math.floor((Number.isFinite(value) ? value : 0) / 1000);
+  if (seconds < FLEET_STATUS_UNIT_MIN) return Math.max(1, seconds) + ' s';
+  const minutes = Math.floor(seconds / FLEET_STATUS_UNIT_MIN);
+  if (minutes < FLEET_STATUS_UNIT_HOUR) return minutes + ' min';
+  const hours = Math.floor(minutes / FLEET_STATUS_UNIT_HOUR);
+  if (hours < FLEET_STATUS_UNIT_DAY) return hours + ' h';
+  return Math.floor(hours / FLEET_STATUS_UNIT_DAY) + ' d';
+}
+
+/**
+ * D-7: the fleet status copy. `machines` is the envelope's `machines` (self first, so self is
+ * skipped by its `ok` status). Returns [] when every member answered, so the caller can hide the
+ * element instead of rendering an empty line.
+ * @param {object[]} machines
+ * @param {number} now  epoch ms; `as_of` is compared against it (injectable for tests)
+ * @returns {string[]}
+ */
+function recentFleetStatusText(machines, now = Date.now()) {
+  const lines = [];
+  for (const machine of Array.isArray(machines) ? machines : []) {
+    if (!machine || machine.status === 'ok') continue;
+    const name = machine.machine_name || machine.machine_id;
+    if (machine.status === 'stale') {
+      lines.push(name + ': showing its list from ' + relativeAge(Number(now) - Number(machine.as_of)) + ' ago');
+    } else if (machine.status === 'timeout') {
+      lines.push(name + " didn't answer in time — its sessions are missing");
+    } else if (machine.status === 'unreachable' || machine.status === 'skipped') {
+      lines.push(name + ' is unreachable — its sessions are missing');
+    } else {
+      lines.push(name + ' returned an error — its sessions are missing');
+    }
+  }
+  return lines;
+}
+
+/**
+ * D-7: the ONE owner of `<div id="recent-fleet-status">`, created lazily right after #recent-search.
+ * Each line is a child <div> set with textContent (never innerHTML — the strings carry machine
+ * names). Empty `lines` hides the element. A no-op without a DOM (node tests).
+ */
+function renderRecentFleetStatus(lines) {
+  if (typeof document === 'undefined' || !document) return;
+  const list = Array.isArray(lines) ? lines : [];
+  const search = document.getElementById('recent-search');
+  let el = document.getElementById('recent-fleet-status');
+  if (!el) {
+    // Below the whole search row: #recent-search sits in a flex row (.search-input-wrap inside
+    // .search-row), so inserting beside the input would shrink it instead of adding a line.
+    const anchor = (search && typeof search.closest === 'function' && search.closest('.search-row')) || search;
+    if (!anchor || !anchor.parentNode) return;
+    el = document.createElement('div');
+    el.id = 'recent-fleet-status';
+    el.className = 'recent-fleet-status';
+    el.setAttribute('role', 'status');
+    el.style.cssText = 'font-size:11px;color:var(--fg-dim);padding:2px 8px;';
+    anchor.parentNode.insertBefore(el, anchor.nextSibling);
+  }
+  el.textContent = '';
+  for (const line of list) {
+    const lineEl = document.createElement('div');
+    lineEl.textContent = String(line);
+    el.appendChild(lineEl);
+  }
+  el.hidden = list.length === 0;
+}
+
+// D-7: the status line a parsed list body implies, rendered inline so index.html gains no lines.
+// A fleet body was stamped (and its `machines` filled) by the server; a hub or machine body carries
+// no `machines`, so the element is cleared rather than left showing a previous fleet's failure.
+function recentNoteFleetBody(body) {
+  renderRecentFleetStatus(recentFleetStatusText((body && body.machines) || []));
+  return body;
+}
+
+// The box half of a Recent load: GET through the hub proxy, stamped on arrival. NEVER throws — a
+// failed box is an empty, NAMED list (D-4), never a hub fallback. Only a still-current load (token)
+// may publish the failure text.
+async function fetchMachineRecentRows(fetchImpl, base, load, labels) {
+  const machine = load.source.machine;
+  const name = (labels && labels.get ? labels.get(machine) : '') || machine;
+  let status = 0;
+  let code;
+  try {
+    const res = await fetchImpl(recentRequestUrl(base, load.source));
+    status = res && Number(res.status) || 0;
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+      /* expected: an unreadable proxy body is a failed source, not a thrown load */
+    }
+    if (status >= 200 && status < 300) {
+      const rows = Array.isArray(body) ? body : (Array.isArray(body?.sessions) ? body.sessions : []);
+      return stampRecentRowsFromMachine(rows, machine, name);
+    }
+    code = body?.code || body?.error;
+  } catch {
+    /* expected: a transport failure (proxy timeout, refused connection) is a named empty list */
+    status = 0;
+  }
+  if (load.token === recentMachineLoad.token) {
+    recentMachineLoad.unavailable = recentMachineUnavailableText(status, code, name);
+  }
+  return [];
+}
+
+// D-3, search flavour: `/api/sessions/search` answers `{results: [...]}`. A box's hits are its own
+// rows, so they are stamped the same way, and the body it returns carries the source machine as
+// `_machine` (provenance, not content) so the caller can tell whether the filter moved while the
+// search was in flight (D-5) without holding a variable of its own. A hub body is handed back
+// untouched — `_machine` is then undefined. `filterOrSource` accepts either a filter value or a
+// source object from recentSourceForFilter().
+function stampRecentBodyFromSource(body, filterOrSource, labels) {
+  const source = filterOrSource && filterOrSource.kind ? filterOrSource : recentSourceForFilter(filterOrSource);
+  // D-7/D-11: the fleet status line is rendered from the body itself, so index.html's search call
+  // site needs no extra line. A hub or machine body has no `machines`, so this clears the element.
+  recentNoteFleetBody(body);
+  if (!body) return body;
+  // D-5: every body names the SOURCE it answers (kind + machine), so the caller can drop a response
+  // whose source is no longer the current one — including All (fleet) <-> Local (hub), which share
+  // no machine id.
+  if (source.kind !== 'machine') return Object.assign({}, body, { _sourceKey: recentSourceKey(source) });
+  const machine = source.machine;
+  const name = (labels && labels.get ? labels.get(machine) : '') || machine;
+  return Object.assign({}, body, {
+    _sourceKey: recentSourceKey(source),
+    _machine: machine,
+    results: Array.isArray(body.results) ? stampRecentRowsFromMachine(body.results, machine, name) : body.results,
+  });
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    recentSourceKey, recentSourceForFilter, recentRequestUrl, stampRecentRowsFromMachine, recentMachineUnavailableText,
+    recentMachineLoad, beginRecentLoad, recentSourceChanged, fetchMachineRecentRows, stampRecentBodyFromSource,
+    recentNoteFleetBody, recentFleetStatusText, renderRecentFleetStatus,
+  };
+}