create-walle 0.10.2 → 0.10.3

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

@@ -537,6 +537,32 @@ function catalogSessionIds(machineInstanceId) {
   return entry ? new Set(entry.byId.keys()) : new Set();
 }
 
+/** WP-5: is this a multi-machine install at all? The sessions frame carries `machinesPending` ONLY
+ *  then — zero registered machines keeps the payload byte-identical to the single-machine one. */
+function hasEnabledMachines(deps = {}) {
+  return _enabledMachines(_d(deps)).length > 0;
+}
+
+/**
+ * WP-5 (§5.4/§8 AC-5a, docs/remote-session-child-transcript-model-truth-and-restart-2026-10-27.html):
+ * how many ENABLED machines have delivered NO session list since this hub booted.
+ *
+ * Their ids CAN still arrive (the machine sweep + catalog fetch land seconds to a minute after a hub
+ * restart), so a client restoring a `tab_order` that names one must not treat the id as dropped. A
+ * machine that delivered ONCE is settled — its ids were classified — even if it later drops, and
+ * health is deliberately irrelevant: an unreachable or still-'unknown' box that has never answered
+ * is exactly the pending case (its ids are the ones the client is waiting for).
+ */
+function catalogPendingCount(deps = {}) {
+  const d = _d(deps);
+  let pending = 0;
+  for (const machine of _enabledMachines(d)) {
+    const id = _string(machine.instanceId, 160);
+    if (id && !_catalogs.has(id)) pending += 1;
+  }
+  return pending;
+}
+
 /**
  * S-3/AC-6a: fetch one machine's LIVE session list over the WP-3 machine link.
  *
@@ -859,7 +885,13 @@ function mergeSessionRows(localRows, deps = {}) {
     seen.add(id);
     out.push(remote);
   }
-  _lastMergeSignature = JSON.stringify([machines.map((m) => `${m.instanceId}:${m.health}`), out.slice(rows.length)]);
+  // WP-5: the pending count joins the signature so a pending->settled flip (a machine that finally
+  // delivered its first list) is never elided as a no-op broadcast with identical remote rows.
+  _lastMergeSignature = JSON.stringify([
+    machines.map((m) => `${m.instanceId}:${m.health}`),
+    catalogPendingCount(d),
+    out.slice(rows.length),
+  ]);
   return out;
 }
 
@@ -883,19 +915,13 @@ function _machineRowForMirror(mirror, d) {
 }
 
 /**
- * §7 ownership routing (AC-6b), HTTP half: `POST /api/sessions/:id/(park|revive|pin|wake)` for a
- * MIRROR session must be acted on the BOX, never locally — the hub's `parkSession`/`getSession`
- * would otherwise be asked about a session it does not have (OQ-4: mirror sessions are deliberately
- * NOT in the hub's sessions Map).
+ * The shared middle of every mirror forwarder (lifecycle + WP-2's lead-model): resolve the mirror to
+ * the registry row that owns it and write the ONE refusal shape when the box cannot be reached. The
+ * three bodies below are byte-identical to what each forwarder used to write inline.
  *
- * @returns {Promise<boolean>} true = the request was answered here (do NOT run the local handler)
+ * @returns {{machine: object, machineName: string, proxy: object}|null} null = already refused here
  */
-async function forwardLifecycleRequest(req, res, sessionId, action, deps = {}) {
-  const d = _d(deps);
-  const verb = _string(action, 20);
-  if (!['park', 'revive', 'pin', 'wake'].includes(verb)) return false;
-  const mirror = getMirrorSessionMachine(sessionId, d);
-  if (!mirror) return false; // a LOCAL session takes the byte-identical existing path
+function _forwardTarget(res, mirror, d) {
   const machine = _machineRowForMirror(mirror, d);
   const machineName = _string(machine ? machine.displayName : mirror.machineName, 200);
   if (!machine) {
@@ -903,16 +929,16 @@ async function forwardLifecycleRequest(req, res, sessionId, action, deps = {}) {
       ok: false, code: 'machine_unreachable', error: `Machine ${machineName || mirror.machineInstanceId} is not available`,
       machine: mirror.machineInstanceId, machineName,
     });
-    return true;
+    return null;
   }
   if (_string(machine.health, 40) === 'unreachable') {
-    // Never a local act: a lifecycle action on a session the hub does not own is refused, not
-    // silently applied to a same-id session on this host (which does not exist anyway).
+    // Never a local act: an action on a session the hub does not own is refused, not silently
+    // applied to a same-id session on this host (which does not exist anyway).
     _sendJson(res, 503, {
       ok: false, code: 'machine_unreachable', error: `Machine ${machineName} is unreachable`,
       machine: mirror.machineInstanceId, machineName,
     });
-    return true;
+    return null;
   }
   const proxy = _peer('proxy', d);
   if (!proxy || typeof proxy.forwardMachineHttp !== 'function') {
@@ -920,15 +946,18 @@ async function forwardLifecycleRequest(req, res, sessionId, action, deps = {}) {
       ok: false, code: 'machine_unreachable', error: `Machine ${machineName} could not be reached`,
       machine: mirror.machineInstanceId, machineName,
     });
-    return true;
+    return null;
   }
-  const result = await proxy.forwardMachineHttp({
-    machine: machine,
-    pathname: `/api/sessions/${encodeURIComponent(mirror && sessionId)}/${verb}`,
-    method: 'POST',
-    body: '',
-    deps: d,
-  });
+  return { machine, machineName, proxy };
+}
+
+/**
+ * The shared tail: a failed dial is the one refusal shape, and the box's own status + body are
+ * returned VERBATIM (§6.5) — the client parses the box's answer exactly as it parses the local one.
+ *
+ * @returns {true} always — the request was answered here.
+ */
+function _relayBoxAnswer(res, result, mirror, machineName) {
   if (!result || !result.ok) {
     _sendJson(res, 503, {
       ok: false, code: (result && result.code) || 'machine_unreachable',
@@ -937,8 +966,6 @@ async function forwardLifecycleRequest(req, res, sessionId, action, deps = {}) {
     });
     return true;
   }
-  // The box's own status and body are returned VERBATIM (§6.5): the client parses the box's answer
-  // exactly as it parses the local one.
   if (!res.headersSent) {
     res.writeHead(Number(result.status) || 502, { 'Content-Type': result.contentType || 'application/json' });
     res.end(result.text || '');
@@ -946,6 +973,260 @@ async function forwardLifecycleRequest(req, res, sessionId, action, deps = {}) {
   return true;
 }
 
+/**
+ * §7 ownership routing (AC-6b), HTTP half: `POST /api/sessions/:id/(park|revive|pin|wake)` for a
+ * MIRROR session must be acted on the BOX, never locally — the hub's `parkSession`/`getSession`
+ * would otherwise be asked about a session it does not have (OQ-4: mirror sessions are deliberately
+ * NOT in the hub's sessions Map).
+ *
+ * @returns {Promise<boolean>} true = the request was answered here (do NOT run the local handler)
+ */
+async function forwardLifecycleRequest(req, res, sessionId, action, deps = {}) {
+  const d = _d(deps);
+  const verb = _string(action, 20);
+  if (!['park', 'revive', 'pin', 'wake'].includes(verb)) return false;
+  const mirror = getMirrorSessionMachine(sessionId, d);
+  if (!mirror) return false; // a LOCAL session takes the byte-identical existing path
+  const target = _forwardTarget(res, mirror, d);
+  if (!target) return true;
+  const result = await target.proxy.forwardMachineHttp({
+    machine: target.machine,
+    pathname: `/api/sessions/${encodeURIComponent(mirror && sessionId)}/${verb}`,
+    method: 'POST',
+    body: '',
+    deps: d,
+  });
+  return _relayBoxAnswer(res, result, mirror, target.machineName);
+}
+
+// ---------------------------------------------------------------------------------------------
+// WP-2 (docs/remote-box-model-access-2026-10-26.html §1.3 C-6, §5.1 R-4/R-8, §5.3 D-4, §6.3) —
+// the model picker's four calls for a MIRROR session
+// ---------------------------------------------------------------------------------------------
+//
+// `GET .../lead-model/options`, `POST .../lead-model`, `GET .../lead-model/request` and
+// `DELETE .../lead-model/request` are answered hub-locally today, and for a mirror id that is a
+// `404 session_not_found` (the id is deliberately NOT in the hub's sessions Map, so
+// lib/lead-model-options.js can never serve it). The BOX owns the session, its CLI and its
+// servability rules (D-4), so the four calls are forwarded there exactly like the lifecycle verbs
+// above: a local id takes the byte-identical existing path, an unknown/down box is the shared 503
+// `machine_unreachable`, and otherwise the box's status + body come back VERBATIM.
+
+/** kind → the BOX route it belongs to. `switch` is the only kind that carries a body. */
+const LEAD_MODEL_FORWARDS = Object.freeze({
+  options: { method: 'GET', suffix: '/lead-model/options' },
+  switch: { method: 'POST', suffix: '/lead-model' },
+  request: { method: 'GET', suffix: '/lead-model/request' },
+  'request-cancel': { method: 'DELETE', suffix: '/lead-model/request' },
+});
+
+// The local POST handler's own bound (lib/api/sessions.js handleLeadModelSwitch: 4 KiB), so a body
+// the hub itself would refuse is never dialled out. The bytes forwarded are the caller's, as-is.
+const LEAD_MODEL_BODY_LIMIT_BYTES = 4 * 1024;
+
+/** The request's query string, unchanged ('' when there is none). */
+function _searchOf(req) {
+  const raw = String((req && req.url) || '');
+  const at = raw.indexOf('?');
+  return at < 0 ? '' : raw.slice(at);
+}
+
+/** The request's own path — the part of `req.url` before `?`, never decoded/re-encoded. */
+function _pathOf(req) {
+  const raw = String((req && req.url) || '');
+  const at = raw.indexOf('?');
+  return at < 0 ? raw : raw.slice(0, at);
+}
+
+// D-4 (lib/remote-session-forward.js:58-61): the hub's OWN device token and the picker's routing
+// param belong to the first hop and must never be dialled to the box — the box's own `getAuthToken`
+// prefers `?token=` over the peer Bearer, so a forwarded `token` would shadow the peer credential.
+const DELEGATE_PREFS_STRIPPED_PARAMS = Object.freeze(['token', 'machine']);
+
+// WP-1 (docs/remote-session-delegate-pick-write-forward-2026-10-30.html D-1/D-2): the delegate-prefs
+// READ plus the two WRITES that set a rung of the box's own ladder cross the same peer leg. Any other
+// verb is not a delegate-prefs forward at all (the caller keeps its unchanged local path).
+const DELEGATE_PREFS_FORWARD_METHODS = Object.freeze(['GET', 'PUT', 'DELETE']);
+
+/**
+ * The delegate-prefs read's query string with the hub's protocol params removed ('' when nothing is
+ * left). `ctm_session_id` and `agent` — everything that is the box's business — cross unchanged.
+ */
+function _delegatePrefsSearch(req) {
+  const raw = _searchOf(req);
+  if (!raw) return '';
+  const params = new URLSearchParams(raw);
+  for (const key of DELEGATE_PREFS_STRIPPED_PARAMS) params.delete(key);
+  const rest = params.toString();
+  return rest ? `?${rest}` : '';
+}
+
+/** The request body as the caller wrote it, bounded like the local handler. */
+function _readLeadModelBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    let size = 0;
+    let done = false;
+    const finish = (fn, value) => { if (done) return; done = true; fn(value); };
+    req.on('data', (chunk) => {
+      if (done) return;
+      size += chunk.length;
+      if (size > LEAD_MODEL_BODY_LIMIT_BYTES) { finish(reject, new Error('request_body_too_large')); return; }
+      raw += chunk;
+    });
+    req.on('end', () => finish(resolve, raw));
+    req.on('error', (error) => finish(reject, error));
+  });
+}
+
+/**
+ * Like forwardLifecycleRequest: true = the request was answered here (do NOT run the local handler).
+ *
+ * @param {'options'|'switch'|'request'|'request-cancel'} kind
+ * @returns {Promise<boolean>}
+ */
+async function forwardLeadModelRequest(req, res, sessionId, kind, deps = {}) {
+  const d = _d(deps);
+  const spec = LEAD_MODEL_FORWARDS[_string(kind, 20)];
+  if (!spec) return false;
+  const mirror = getMirrorSessionMachine(sessionId, d);
+  if (!mirror) return false; // a LOCAL session takes the byte-identical existing path
+  const target = _forwardTarget(res, mirror, d);
+  if (!target) return true;
+  let body = '';
+  if (spec.method === 'POST') {
+    // Mirrors lib/api/sessions.js handleLeadModelSwitch's own admission (413 too large / 400
+    // otherwise, same body) so the two agreement points cannot drift.
+    try { body = await _readLeadModelBody(req); }
+    catch (error) { return _sendJson(res, error && error.message === 'request_body_too_large' ? 413 : 400, { ok: false, code: 'invalid_request', message: error && error.message || 'Invalid request.' }); }
+  }
+  const result = await target.proxy.forwardMachineHttp({
+    machine: target.machine,
+    pathname: `/api/sessions/${encodeURIComponent(sessionId)}${spec.suffix}`,
+    search: _searchOf(req),
+    method: spec.method,
+    body,
+    deps: d,
+  });
+  return _relayBoxAnswer(res, result, mirror, target.machineName);
+}
+
+/**
+ * WP-3 (docs/remote-session-child-transcript-model-truth-and-restart-2026-10-27.html §5 D-4) GET,
+ * and WP-1 (docs/remote-session-delegate-pick-write-forward-2026-10-30.html D-1/D-2/D-7) PUT/DELETE:
+ * /api/models/delegate-prefs[?ctm_session_id=<id>&agent=<a>] for a BOX-owned session is answered by
+ * the box's own Wall-E ladder (session pick > per-agent default > vendor), not the hub's — the READ,
+ * and the per-session / per-agent WRITES that set those rungs, take the same peer leg. Returns true
+ * when the response was written (forwarded or refused); false for a local/unclaimed id or an
+ * unsupported verb (the caller takes the unchanged proxyHttp path).
+ *
+ * @returns {Promise<boolean>}
+ */
+async function forwardDelegatePrefsRequest(req, res, sessionId, deps = {}) {
+  const d = _d(deps);
+  const method = String((req && req.method) || '').toUpperCase();
+  if (!DELEGATE_PREFS_FORWARD_METHODS.includes(method)) return false;
+  const mirror = getMirrorSessionMachine(sessionId, d);
+  if (!mirror) return false; // a LOCAL session takes the byte-identical existing path
+  const target = _forwardTarget(res, mirror, d);
+  if (!target) return true;
+  let body = '';
+  if (method === 'PUT') {
+    // Mirrors lib/api/sessions.js handleLeadModelSwitch's own admission (413 too large / 400
+    // otherwise, same body) so the two agreement points cannot drift.
+    try { body = await _readLeadModelBody(req); }
+    catch (error) { return _sendJson(res, error && error.message === 'request_body_too_large' ? 413 : 400, { ok: false, code: 'invalid_request', message: error && error.message || 'Invalid request.' }); }
+  }
+  const result = await target.proxy.forwardMachineHttp({
+    machine: target.machine,
+    pathname: _pathOf(req),
+    search: _delegatePrefsSearch(req),
+    method,
+    body,
+    deps: d,
+  });
+  return _relayBoxAnswer(res, result, mirror, target.machineName);
+}
+
+/**
+ * WP-1/AC-1h (docs/remote-session-child-transcript-model-truth-and-restart-2026-10-27.html): the
+ * sidebar's "Clear N finished" retires a lead's finished workers by POSTing { lead } (or { ids }) to
+ * /api/sessions/workers/retire. For a BOX-owned lead those rows live in the box's worker_sessions,
+ * so the call is forwarded to the owning machine by looking the ids up in the mirror union.
+ * Returns true when the response was written (forwarded, or refused); false when every id is local
+ * or unclaimed (the caller runs the byte-identical local path).
+ *
+ * Unlike the per-session forwards above, this route carries the ids in its BODY, not in the path — so
+ * the ownership decision is made here, after the caller has parsed and validated the JSON, and the
+ * body is re-serialized byte-for-byte to the one machine that owns every id.
+ *
+ * @param {object} body the already-parsed, already-validated request body ({ ids?: string[], lead?: string })
+ * @returns {Promise<boolean>}
+ */
+async function forwardWorkersRetireRequest(req, res, body, deps = {}) {
+  const d = _d(deps);
+  const raw = body && typeof body === 'object' ? body : {};
+  const candidates = [];
+  if (typeof raw.lead === 'string' && raw.lead.trim()) candidates.push(raw.lead.trim());
+  if (Array.isArray(raw.ids)) {
+    for (const entry of raw.ids) {
+      const id = _string(entry, 200);
+      if (id) candidates.push(id);
+    }
+  }
+  if (!candidates.length) return false;
+  const mirrors = candidates.map((id) => getMirrorSessionMachine(id, d));
+  const claimed = mirrors.filter(Boolean);
+  if (!claimed.length) return false; // every id is local or unclaimed: the byte-identical local path
+  const machineInstanceId = claimed[0].machineInstanceId;
+  // A mix of local and mirror ids, or mirrors of two different machines, has no single owner to send
+  // the one POST to — never split the call, never apply half of it here.
+  if (claimed.length !== candidates.length || claimed.some((m) => m.machineInstanceId !== machineInstanceId)) {
+    _sendJson(res, 400, { ok: false, code: 'mixed_owners', message: 'Retire ids must all belong to one machine.' });
+    return true;
+  }
+  const mirror = claimed[0];
+  const target = _forwardTarget(res, mirror, d);
+  if (!target) return true; // a refusal was already written
+  const result = await target.proxy.forwardMachineHttp({
+    machine: target.machine,
+    pathname: '/api/sessions/workers/retire',
+    search: '',
+    method: 'POST',
+    // forwardMachineHttp sets `Content-Type: application/json` itself for a non-GET/HEAD verb; the
+    // caller's own JSON body crosses unmodified.
+    body: JSON.stringify(raw),
+    deps: d,
+  });
+  return _relayBoxAnswer(res, result, mirror, target.machineName);
+}
+
+/**
+ * WP-1 (docs/remote-session-rename-forward-and-empty-rows-2026-10-30.html §5 D-1/D-2): a rename or
+ * star of a BOX-owned session is the box's write. Body-keyed like forwardWorkersRetireRequest: the
+ * caller has parsed and validated the JSON; the body is re-serialized to the owning box's same route.
+ * Returns true when the response was written (forwarded or refused); false for a local/unclaimed id
+ * (the caller runs the byte-identical local path).
+ *
+ * @param {object} body the already-parsed request body ({ sessionId?: string, id?: string, ... })
+ * @returns {Promise<boolean>}
+ */
+async function forwardSessionTitleWrite(req, res, body, deps = {}) {
+  const d = _d(deps);
+  const raw = body && typeof body === 'object' ? body : {};
+  const id = _string(raw.sessionId || raw.id, 200);
+  if (!id) return false;
+  const mirror = getMirrorSessionMachine(id, d);
+  if (!mirror) return false;
+  const target = _forwardTarget(res, mirror, d);
+  if (!target) return true;
+  const result = await target.proxy.forwardMachineHttp({
+    machine: target.machine, pathname: _pathOf(req), search: '', method: 'POST',
+    body: JSON.stringify(raw), deps: d,
+  });
+  return _relayBoxAnswer(res, result, mirror, target.machineName);
+}
+
 function _sendJson(res, status, payload) {
   const body = JSON.stringify(payload);
   if (res.headersSent) return true;
@@ -1045,6 +1326,9 @@ module.exports = {
   ingestFenceCounters,
   catalogFor,
   catalogSessionIds,
+  // WP-5 (§5.4): the hub's own truth for "a box tab may still be on its way" + the multi-machine gate.
+  catalogPendingCount,
+  hasEnabledMachines,
   fetchCatalog,
   refreshAll,
   onLinkReady,
@@ -1056,6 +1340,17 @@ module.exports = {
   mergeSessionRows,
   lastMergeSignature,
   forwardLifecycleRequest,
+  // WP-2 (§6.3): the picker's four lead-model calls for a MIRROR session go to the box that owns it.
+  forwardLeadModelRequest,
+  // WP-3 (§5 D-4): the Delegate pane's ladder read for a BOX-owned session is answered by the box.
+  forwardDelegatePrefsRequest,
+  // WP-1 (docs/remote-session-child-transcript-model-truth-and-restart-2026-10-27.html AC-1h): the
+  // body-keyed sibling — "Clear N finished" for a BOX-owned lead retires on the box that owns it.
+  forwardWorkersRetireRequest,
+  // WP-1 (docs/remote-session-rename-forward-and-empty-rows-2026-10-30.html §5 D-1/D-2, §8 WP-1): a
+  // rename or star of a BOX-owned session is the box's write — the body-keyed sibling that forwards it
+  // to the owning machine's same route instead of writing the hub's ledger for an id it does not own.
+  forwardSessionTitleWrite,
   resumeMachineFor,
   forwardResumeOnMachine,
   _resetForTests,