create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/lib/remote-session-forward.js

@@ -0,0 +1,306 @@
+'use strict';
+
+// WP-2 (docs/remote-session-image-upload-forwarding-2026-10-24.html §5 D-1..D-10, §6, §8
+// AC-2a..AC-2f, §9 S-1/S-10) — the hub-side BYTE-FAITHFUL session request forwarder.
+//
+// The hub forwards only `POST /api/sessions/:id/(park|revive|pin|wake)` today
+// (lib/remote-machine-catalog.js's forwardLifecycleRequest). The image-draft family reaches the
+// hub's own handler, and for a MIRROR session that handler can never succeed: the hub does not hold
+// the session in its map, so lib/terminal-draft-owner.js throws a 503
+// CTM_OWNERSHIP_UNAVAILABLE that the browser uploader retries forever (public/js/ctm-uploader.js
+// treats 503 as retryable). This module is the seam that lets that family be answered by the BOX
+// that owns the session — the bytes must land on the PTY host, because the CLI opens the delivered
+// draft path on its own filesystem (§1 "Where the bytes must live").
+//
+// It is deliberately NOT a general reverse proxy, and it is NOT wired into any route here (WP-3
+// adds the one dispatch line in api-prompts.js):
+//
+//   D-1  ownership is decided ONCE, by `catalog.getMirrorSessionMachine` — local sessions Map
+//        first (the 2026-10-23 relay-hijack fix), then the forwarded creates, the live catalog and
+//        the sync mirror. A local id, or an id no registered machine claims, MISSES and the caller
+//        runs its local handler with the request stream untouched (byte-identical local path).
+//   D-2  a mirror id never reaches the hub's draft owner: this module either proxies it or refuses
+//        with the same 503 `machine_unreachable` body forwardLifecycleRequest uses.
+//   D-3  the forwarded set is a CLOSED list (FORWARDED_SESSION_ROUTES); every member has a
+//        matching `peerControl` row on the box (WP-1). A prefix-forward would 403 on every route
+//        nobody flagged (lib/auth-rules.js pins the peer allowlist EXACTLY).
+//   D-4  outbound headers are the peer credential plus an allowlist. The inbound `cookie` and
+//        `authorization` are NEVER forwarded, and the hub's `token` query parameter is stripped:
+//        the box's getAuthToken (server.js:11524) prefers `?token=` over the Bearer, so forwarding
+//        it verbatim would both leak a hub credential and 401 the request.
+//   D-5  bytes stream both ways with NO hub-side cap: `Readable.toWeb(req)` + `duplex:'half'` out,
+//        `pipeline(Readable.fromWeb(response.body), res)` back. The box's own 25 MiB limit
+//        (api-prompts.js) is the only limit — an intermediate cap reproduces JupyterHub #2831.
+//   D-6  honest status: registered but unreachable, no row, no credential, a connect error, or the
+//        headers deadline → 503 `machine_unreachable` naming the machine, with `Retry-After: 2`.
+//        Any status the box answered (409/413/503 included) goes through VERBATIM.
+//   D-7  the headers deadline is 30 s (= public/js/ctm-uploader.js's attemptTimeoutMs), so the hub
+//        never outlives the browser's attempt; a client that goes away aborts the upstream fetch.
+//   D-8  the hub never retries: a streamed body is single-use and the client uploader already owns
+//        retry with an idempotent `request_id`.
+//
+// Dependency note: this module must NOT require lib/hosted-sync-worker.js (dependency-cycle lint —
+// see lib/remote-machine-proxy.js:30-33). The two requires below are leaves on the way in:
+// lib/remote-machine-catalog.js is a dependency SINK and lib/remote-machine-create.js loads its own
+// heavy peers lazily inside `_productionDeps()`.
+
+const { Readable } = require('node:stream');
+const { pipeline } = require('node:stream/promises');
+
+const catalogDefault = require('./remote-machine-catalog');
+const { buildPeerControlHeaders: buildPeerControlHeadersDefault } = require('./remote-machine-create');
+
+// D-7: equal to public/js/ctm-uploader.js's attemptTimeoutMs — hub and browser agree on how long a
+// single upload attempt may live.
+const FORWARD_DEADLINE_MS = 30_000;
+
+// D-4: the hub's own device token and the picker's routing param belong to the FIRST hop. Everything
+// else in the query is the box's business (`provider`, `ordinal`, `request_id`, `filename`, `mode`,
+// `v`, the content route's cache buster).
+const STRIPPED_QUERY_PARAMS = Object.freeze(['token', 'machine']);
+
+// D-4: request headers copied from the browser — never `cookie`, never the inbound `authorization`.
+const FORWARDED_REQUEST_HEADERS = Object.freeze(['content-type', 'content-length', 'if-match', 'x-ctm-upload-request-id']);
+
+// D-5: response headers copied from the box. `retry-after` is here because the box's own 503 must
+// keep its own retry hint; everything else (set-cookie, server, date) stays at the hop that owns it.
+const FORWARDED_RESPONSE_HEADERS = Object.freeze(['content-type', 'content-length', 'etag', 'cache-control', 'retry-after', 'x-content-type-options']);
+
+// D-3: the closed forwarded set. Each entry is [METHOD, RegExp on pathname]; it mirrors the ten
+// image-draft peer-control routes on the box (lib/auth-rules.js:164-179) exactly, and the WP-1
+// pairing meta-test (tests/peer-control-auth.test.js §7) fails when a member here has no flagged
+// row on the box. A member added here without that flag turns the hub's honest 503 into the box's
+// 403 insufficient_scope (the incident-2/incident-3 class).
+const FORWARDED_SESSION_ROUTES = Object.freeze([
+  ['GET', /^\/api\/sessions\/[^/]+\/image-drafts$/],
+  ['GET', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/content$/],
+  ['POST', /^\/api\/sessions\/[^/]+\/image-drafts$/],
+  ['PUT', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+$/],
+  ['DELETE', /^\/api\/sessions\/[^/]+\/image-drafts$/],
+  ['DELETE', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+$/],
+  ['POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/delivery$/],
+  ['POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/freeze$/],
+  ['POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/submit$/],
+  ['POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/retry$/],
+]);
+
+function _string(value, max = 200) {
+  return String(value == null ? '' : value).trim().slice(0, max);
+}
+
+/** D-3 as a predicate: is (method, pathname) one of the forwarded routes? Purely lexical. */
+function isForwardedSessionRoute(method, pathname) {
+  const verb = _string(method, 12).toUpperCase();
+  const target = String(pathname == null ? '' : pathname);
+  if (!verb || !target) return false;
+  return FORWARDED_SESSION_ROUTES.some(([routeMethod, pattern]) => routeMethod === verb && pattern.test(target));
+}
+
+/**
+ * D-1 as a SYNCHRONOUS predicate for the dispatch line: is this a forwarded route for a MIRROR id?
+ * The caller uses it to keep the local path byte-identical — a local id calls its handler in the same
+ * tick, so the handler's body listeners attach before any `aborted`/`data` event can be missed.
+ */
+function isMirrorSessionRequest(req, url, sessionId, deps = {}) {
+  if (!isForwardedSessionRoute(req && req.method, url && url.pathname)) return false;
+  const catalog = (deps && deps.catalog) || catalogDefault;
+  if (typeof catalog.getMirrorSessionMachine !== 'function') return false;
+  const mirror = catalog.getMirrorSessionMachine(sessionId, deps || {});
+  return !!(mirror && mirror.machineInstanceId);
+}
+
+/** An allowlist copy of `headers` (values verbatim; a repeated header is comma-joined). */
+function _pickHeaders(headers, names) {
+  const out = {};
+  if (!headers) return out;
+  for (const name of names) {
+    const value = headers[name];
+    if (value === undefined || value === null) continue;
+    out[name] = Array.isArray(value) ? value.join(', ') : String(value);
+  }
+  return out;
+}
+
+/** The same allowlist over a fetch `Headers` object (or a plain object, for an injected fetch). */
+function _pickResponseHeaders(headers) {
+  const out = {};
+  if (!headers) return out;
+  for (const name of FORWARDED_RESPONSE_HEADERS) {
+    const value = typeof headers.get === 'function' ? headers.get(name) : headers[name];
+    if (value === undefined || value === null || value === '') continue;
+    out[name] = String(value);
+  }
+  return out;
+}
+
+/**
+ * D-6: the one refusal shape — the same body forwardLifecycleRequest writes, so the client renders
+ * one message for both forwarders, plus `Retry-After: 2` (the reader may retry; the box is down, not
+ * the request) and an optional machine-readable `detail`.
+ *
+ * @returns {true} always — the request was answered here (never falls through to a local handler).
+ */
+function _refuse(res, mirror, machineName, detail) {
+  const label = _string(machineName, 200) || _string(mirror && mirror.machineInstanceId, 160) || 'machine';
+  const payload = {
+    ok: false,
+    code: 'machine_unreachable',
+    error: `Machine ${label} is unreachable`,
+    machine: _string(mirror && mirror.machineInstanceId, 160),
+    machineName: _string(machineName, 200),
+    ...(detail ? { detail } : {}),
+  };
+  const body = JSON.stringify(payload);
+  // A client that already hung up (the abort path) has a destroyed res: writing to it would only
+  // raise a second, uninteresting error on the way out.
+  if (!res.headersSent && !res.writableEnded && !res.destroyed) {
+    res.writeHead(503, {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+      'Retry-After': '2',
+    });
+    res.end(body);
+  }
+  return true;
+}
+
+/**
+ * D-1/D-2 entry point. Returns `false` (the caller runs its local handler with the request stream
+ * untouched) unless `sessionId` is a MIRROR id AND `(req.method, url.pathname)` is in
+ * FORWARDED_SESSION_ROUTES. Otherwise it fully answers `res` and resolves `true`.
+ *
+ * Never throws, and never reads `req` before it has decided (a non-forwarded route leaves
+ * `req.readableFlowing === null`).
+ *
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {URL} url
+ * @param {string} sessionId   already decoded
+ * @param {{catalog?, buildPeerControlHeaders?, fetchImpl?, env?, deadlineMs?, setTimeoutFn?,
+ *          clearTimeoutFn?}} [deps]
+ * @returns {Promise<boolean>}
+ */
+async function maybeForwardSessionRequest(req, res, url, sessionId, deps = {}) {
+  const d = deps || {};
+  // 1. A route this module does not own is never even looked up — the request stream stays virgin.
+  if (!isForwardedSessionRoute(req && req.method, url && url.pathname)) return false;
+
+  // 2. D-1: the ONE ownership decision (local Map first). A local or unclaimed id falls through.
+  const catalog = d.catalog || catalogDefault;
+  const mirror = typeof catalog.getMirrorSessionMachine === 'function'
+    ? catalog.getMirrorSessionMachine(sessionId, d)
+    : null;
+  if (!mirror || !mirror.machineInstanceId) return false;
+
+  // 3. D-6: a registered machine with no usable row, or one known to be down, is refused here —
+  //    never acted on locally.
+  const machine = typeof catalog.machineRowForMirror === 'function' ? catalog.machineRowForMirror(mirror, d) : null;
+  const machineName = _string(machine ? machine.displayName : mirror.machineName, 200);
+  if (!machine) return _refuse(res, mirror, machineName, 'machine_row_unavailable');
+  if (_string(machine.health, 40) === 'unreachable') return _refuse(res, mirror, machineName, 'machine_unreachable');
+
+  // 4. D-4: the peer credential is the ONLY authorization on the wire. No credential configured
+  //    means this hub cannot be a peer of that box — refuse rather than send an unauthenticated
+  //    request that would come back as an opaque 401.
+  const buildHeaders = typeof d.buildPeerControlHeaders === 'function'
+    ? d.buildPeerControlHeaders
+    : buildPeerControlHeadersDefault;
+  const peerHeaders = buildHeaders(d.env || process.env);
+  if (!peerHeaders) return _refuse(res, mirror, machineName, 'peer_credential_missing');
+
+  const fetchImpl = typeof d.fetchImpl === 'function'
+    ? d.fetchImpl
+    : (typeof d.fetch === 'function' ? d.fetch : globalThis.fetch);
+  if (typeof fetchImpl !== 'function') return _refuse(res, mirror, machineName, 'fetch_unavailable');
+
+  // 5. D-4: the same path and query, minus what belongs to the first hop.
+  let target;
+  try {
+    target = new URL(`${(url && url.pathname) || ''}${(url && url.search) || ''}`, _string(machine.url, 1000));
+    for (const key of STRIPPED_QUERY_PARAMS) target.searchParams.delete(key);
+  } catch {
+    return _refuse(res, mirror, machineName, 'machine_url_invalid'); // expected: a malformed registry url is a refusal, not a throw
+  }
+
+  // 6/7. D-7: the abort path. Two independent signals, because Node emits the REQUEST's `close` on
+  // natural completion too (a fully received POST body closes long before the box answers) — so the
+  // request's own close only counts while the message is INCOMPLETE, and the response's close only
+  // counts while nothing has been written yet. Between them, exactly one shape aborts: the client
+  // went away with the answer still owed to it.
+  const controller = new AbortController();
+  let headersArrived = false;
+  const abortIfClientGone = () => {
+    if (!headersArrived && !res.writableEnded) controller.abort();
+  };
+  res.once('close', abortIfClientGone);
+  req.once('close', () => { if (!req.complete) abortIfClientGone(); });
+
+  const timeoutFn = typeof d.setTimeoutFn === 'function' ? d.setTimeoutFn : setTimeout;
+  const clearFn = typeof d.clearTimeoutFn === 'function' ? d.clearTimeoutFn : clearTimeout;
+  const deadlineMs = Number(d.deadlineMs) > 0 ? Number(d.deadlineMs) : FORWARD_DEADLINE_MS;
+  let timedOut = false;
+  const timer = timeoutFn(() => {
+    timedOut = true;
+    controller.abort();
+  }, deadlineMs);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+
+  const method = _string(req.method, 12).toUpperCase();
+  const hasBody = method !== 'GET' && method !== 'HEAD';
+  let response;
+  try {
+    response = await fetchImpl(target, {
+      method,
+      headers: { ...peerHeaders, ..._pickHeaders(req.headers, FORWARDED_REQUEST_HEADERS) },
+      redirect: 'manual',
+      signal: controller.signal,
+      // D-5: the body streams through — no buffering, no hub-side cap, single use (D-8: never retry).
+      ...(hasBody ? { body: Readable.toWeb(req), duplex: 'half' } : {}),
+    });
+  } catch (error) {
+    clearFn(timer);
+    // D-6: the response never started, so the honest answer is the machine_unreachable refusal. When
+    // the client itself is gone this write is skipped (the socket is dead) — `_refuse` owns that.
+    const detail = timedOut ? 'timeout' : (_string((error && (error.code || error.name)) || error, 80) || 'fetch_failed');
+    return _refuse(res, mirror, machineName, detail);
+  }
+  clearFn(timer);
+  headersArrived = true;
+
+  if (!response) return _refuse(res, mirror, machineName, 'empty_response');
+
+  // 8. Status and the response allowlist go through verbatim (D-5/D-6) — the box's own 4xx/5xx
+  //    included: the client parses the box's answer exactly as it parses a local one.
+  const status = Number(response.status) || 502;
+  try {
+    res.writeHead(status, _pickResponseHeaders(response.headers));
+  } catch {
+    // A header value the runtime refuses to write (a box bug, not a hub one) must still leave the
+    // hook's "never throws" contract intact for its caller: refuse honestly instead of rejecting.
+    return _refuse(res, mirror, machineName, 'invalid_response_headers'); // expected: an unwritable header from the box
+  }
+
+  // 9. Stream the body back.
+  if (!response.body) {
+    res.end();
+    return true;
+  }
+  try {
+    await pipeline(Readable.fromWeb(response.body), res, { signal: controller.signal });
+  } catch (error) {
+    // The headers are already on the wire, so there is no honest status left to send: destroy the
+    // response (the client sees a truncated body and a network error) and let its uploader retry
+    // with the same idempotent request_id (D-8).
+    try { res.destroy(error); } catch { /* expected: a response that is already destroyed */ }
+  }
+  return true;
+}
+
+module.exports = {
+  FORWARDED_SESSION_ROUTES,
+  FORWARD_DEADLINE_MS,
+  STRIPPED_QUERY_PARAMS,
+  maybeForwardSessionRequest,
+  isForwardedSessionRoute,
+  isMirrorSessionRequest,
+};

package/template/coding-task-manager/lib/remote-submission-status.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { normalizeRecoveryAction } = require('./prompt-submission-contract');
+
 function createRemoteSubmissionStatusWriter(deps = {}) {
   const required = ['getDb', 'getDbPath', 'getInstanceId', 'getSession', 'updateRemoteSubmission',
     'publicSubmission', 'remoteSubmissionIdentity', 'broadcastSubmissionStatus',
@@ -67,6 +69,10 @@ function createRemoteSubmissionStatusWriter(deps = {}) {
       reason: details.reason || '',
       message: details.message || '',
       retryable: details.retryable === true,
+      // WP-0: persisted next to `retryable` so a reloaded row (or any later
+      // frame built from `row.result`) carries the same recovery verdict the
+      // direct reply carried. Same normalization as publicSubmissionStatus.
+      recoveryAction: normalizeRecoveryAction(details.recoveryAction, details.retryable === true),
       source: details.source || '',
       evidence_source: details.evidenceSource || details.evidence_source || '',
       observed_at: Date.now(),

package/template/coding-task-manager/lib/restart-outcome-truth.js

@@ -63,16 +63,33 @@ function recordLingerEntered({ sessions, isHosted, hostIdForSession, recordSessi
   }
 }
 
+// §5 D-10 / §9 S-12: the model proxy's own restart outcome, as `adoption.proxy`. The default is the
+// real supervisor, required LAZILY (this module loads during boot, before any proxy exists), and a
+// failure is reported and answered as null — a diagnostics row must never break the boot it describes.
+function _proxyOutcomeFor(proxyOutcome, errorSink) {
+  try {
+    const outcome = (proxyOutcome || (() => require('./oauth-proxy-supervisor').lastRestartOutcome()))();
+    return outcome && typeof outcome === 'object' ? outcome : null;
+  } catch (e) {
+    if (errorSink && typeof errorSink.report === 'function') errorSink.report('restore:proxy-outcome', e);
+    return null;
+  }
+}
+
 // Ledgering must never break boot: any failure is reported, not thrown.
-function appendRestoreCompleteLedger({ build, summary, errorSink, ledger = require('./restart-ledger') }) {
+function appendRestoreCompleteLedger({ build, summary, errorSink, proxyOutcome, ledger = require('./restart-ledger') }) {
+  // `proxy` is nested FIRST on purpose: lib/restart-ledger.js:52-63 keeps an object's first 10 keys, and
+  // the adoption summary already carries more than that, so a trailing key would be silently dropped from
+  // the very row the design is judged on.
+  const adoption = () => ({ proxy: _proxyOutcomeFor(proxyOutcome, errorSink), ...summary() });
   try {
     const bootRestartId = ledger.getBootRestartId();
     if (bootRestartId) {
-      ledger.appendRestartReceiptStage(bootRestartId, 'restore_complete', { newPid: process.pid, build, adoption: summary() });
+      ledger.appendRestartReceiptStage(bootRestartId, 'restore_complete', { newPid: process.pid, build, adoption: adoption() });
     } else {
       ledger.appendRestartLedgerEntry({
         method: 'launchd-respawn', requester: { source: 'launchd' }, reason: 'restore complete (no restart id)',
-        force: false, guardVerdict: { blocked: false, blockers: [] }, build, stage: 'restore_complete', adoption: summary(),
+        force: false, guardVerdict: { blocked: false, blockers: [] }, build, stage: 'restore_complete', adoption: adoption(),
       });
     }
   } catch (e) { errorSink.report('restore:ledger', e); }

package/template/coding-task-manager/lib/restart-preflight.js

@@ -11,7 +11,14 @@ function aliveFn(isProcessAlive) {
 
 // `hostCodeDiffers(hostId, record)`: true when the live host's LOADED code differs from the files on
 // disk now -- the next boot will adopt it as upgrade-pending and hand it off, so predict a handoff.
-function computeRestartPreflight({ sessions, sessionHostManager, hostRecords, isProcessAlive, isRunning, isHosted, isExited, hostCodeDiffers } = {}) {
+//
+// `proxy` (§5 D-10, WP-3): what the next boot will do with the model proxy, already computed by
+// `lib/oauth-proxy-supervisor.js:proxyPreflight()`. It is passed THROUGH, never recomputed here: this
+// module reads session/host state, and the proxy is a different process with a different truth. A caller
+// with no proxy answer gets the honest default -- 'none', with the three measurements null rather than
+// guessed -- so the surface has one shape and the three session arrays below stay byte-for-byte what they
+// have always been.
+function computeRestartPreflight({ sessions, sessionHostManager, hostRecords, isProcessAlive, isRunning, isHosted, isExited, hostCodeDiffers, proxy = null } = {}) {
   const alive = aliveFn(isProcessAlive);
   const differsFn = typeof hostCodeDiffers === 'function' ? hostCodeDiffers : () => false;
   const differsByHost = new Map(); // one disk hash per host per preflight, not per session
@@ -52,7 +59,7 @@ function computeRestartPreflight({ sessions, sessionHostManager, hostRecords, is
     if (compat?.reason === 'upgrade-pending' || codeDiffers(String(hostId), record)) willHandoff.push(sessionId);
     else willAdopt.push(sessionId);
   }
-  return { willAdopt, willHandoff, willRevive };
+  return { willAdopt, willHandoff, willRevive, proxy: proxy ?? { action: 'none', pid: null, openStreams: null, closureDiffers: null } };
 }
 
 module.exports = { computeRestartPreflight };

package/template/coding-task-manager/lib/restore-backoff-gate.js

@@ -14,6 +14,10 @@
 //     activation): allowed past the auto ceiling, but a cooldown is waited out (bounded by
 //     maxCooldownMs) unless this is an unclaimed prewarm;
 //   - after a wait the session must still be the live, deferred, non-closing one.
+//
+// WP-3 (§9 S-10/S-11): the two silent bails below are pure skips of THIS attempt -- they change no
+// return value, they only report through the injected `onSkip(reason, id, session)` dep (default
+// no-op, so this module stays server-free and its unit tests need no lifecycle singleton).
 
 function createAwaitRestoreBackoffOutsideGate({
   enabled,
@@ -23,11 +27,12 @@ function createAwaitRestoreBackoffOutsideGate({
   maxCooldownMs,
   now = Date.now,
   setTimer = setTimeout,
+  onSkip = () => {},
 }) {
   return async function awaitRestoreBackoffOutsideGate(session, opts = {}) {
     if (!enabled) return true;
     const task = session?._restoreTask || {};
-    if (!task.session_id) return false;
+    if (!task.session_id) { onSkip('BackoffTaskMissingSessionId', task.session_id, session); return false; }
     const source = String(opts.source || '');
     const background = /auto-resume/.test(source);
     const decision = restoreBackoff.shouldAttempt(task.session_id, now(), { userInitiated: !background });
@@ -47,7 +52,10 @@ function createAwaitRestoreBackoffOutsideGate({
         timer?.unref?.();
       });
       const latest = getSession(task.session_id);
-      if (latest !== session || !session._restoreDeferred || session._closing || session._exited) return false;
+      if (latest !== session || !session._restoreDeferred || session._closing || session._exited) {
+        onSkip('BackoffSessionReplaced', task.session_id, session);
+        return false;
+      }
     }
     return true;
   };

package/template/coding-task-manager/lib/restore-prepare-retry.js

@@ -22,9 +22,13 @@ function prepareRetryJitterMs(sessionId) {
 // The coalescing "start a deferred restore on the next tick" scheduler, extracted verbatim from
 // server.js (`_scheduleDeferredRestoreStart`) so server.js stays under its file-size ratchet;
 // the retry timer below is one more caller of it (with source:'prepare-retry').
-function createScheduleDeferredRestoreStart({ getSession, startDeferredRestoreSession, log = console.error }) {
+//
+// WP-3 (§9 S-16): the bails report through the injected `onSkip(reason, id, session)` dep (default
+// no-op) and change no return value -- `RetryAlreadyStarting` in particular still returns TRUE: an
+// attempt is already in flight, which is a success-shaped bail, not a skip of the session.
+function createScheduleDeferredRestoreStart({ getSession, startDeferredRestoreSession, log = console.error, onSkip = () => {} }) {
   return function scheduleDeferredRestoreStart(session, opts = {}) {
-    if (!session?._restoreDeferred) return false;
+    if (!session?._restoreDeferred) { onSkip('RetryNotDeferred', session?.id, session); return false; }
     if (!session._deferredInputGeneration) {
       session._deferredInputGeneration = Math.max(1, Number(session._terminalLifecycleCounter || 0) + 1);
     }
@@ -32,7 +36,7 @@ function createScheduleDeferredRestoreStart({ getSession, startDeferredRestoreSe
       ...(session._restoreStartOpts || {}),
       ...(opts || {}),
     };
-    if (session._restoreStarting || session._restoreStartTimer) return true;
+    if (session._restoreStarting || session._restoreStartTimer) { onSkip('RetryAlreadyStarting', session.id, session); return true; }
     session._restoreStartTimer = setTimeout(() => {
       session._restoreStartTimer = null;
       const latest = getSession(session.id);
@@ -53,19 +57,22 @@ function scheduleDeferredRestoreRetry(session, params, deps) {
   const {
     getSession, recordSessionDiagnostic, scheduleStart,
     setTimer = setTimeout, clearTimer = clearTimeout, jitterMs = prepareRetryJitterMs,
+    onSkip = () => {},
   } = deps;
-  if (!session?._restoreDeferred || session._closing || session._exited) return false;
+  if (!session?._restoreDeferred || session._closing || session._exited) { onSkip('RetryNotDeferred', session?.id, session); return false; }
   const source = String(opts.source || '');
   const openClients = (session.clients || []).filter((client) => client?.readyState === 1).length;
   // No open client and a background origin: nothing is waiting to see the retry, and a
   // background drain will pick this session up again on its own cadence -- don't arm a timer
   // that will just fire into an empty room. An 'attach'-sourced failure (or any other
   // user-initiated source) still schedules: the client may reconnect before the timer fires.
-  if (openClients === 0 && /auto-resume|prewarm/.test(source)) return false;
+  if (openClients === 0 && /auto-resume|prewarm/.test(source)) { onSkip('RetryNoClients', session.id, session); return false; }
   const delayMs = Math.max(1500, Number(retryAfterMs) || 0) + jitterMs(session.id);
   if (session._prepareRetryTimer) clearTimer(session._prepareRetryTimer);
   session._prepareRetryTimer = setTimer(() => {
     session._prepareRetryTimer = null;
+    // WP-3 (§9 S-16): the fire-time guard records NOTHING -- it is an idempotent re-arm guard
+    // (something else already started / this session is gone), not a skip predicate.
     const latest = getSession(session.id);
     if (!latest?._restoreDeferred || latest._restoreStarting || latest._closing || latest._exited) return;
     scheduleStart(latest, { ...opts, source: 'prepare-retry' });

package/template/coding-task-manager/lib/restore-resume-batch.js

@@ -51,6 +51,12 @@
 //   now           () => number            injectable clock for tests
 //   isDrainPaused () => boolean           optional; true pauses the whole drain (WI-7(d))
 //   getTranscriptSize (id) => number      optional; sorts one batch's window ascending (WI-8)
+//   onSkip       (reason, id, session) => void  optional; WP-3 (§9 S-18) skip reporting
+//
+// WP-3 (§9 S-18) accounting, zero control-flow change: the requeues of a still-resumable `false`
+// start are counted as a plain NUMBER on the gap metadata (`requeues`) rather than a D-8 reason --
+// the vocabulary is about causes, this is mechanics. A paused tick reports `onSkip('DrainPaused')`
+// once per pause TRANSITION, not per tick, so a long pause cannot flood the lifecycle event ring.
 function drainDeferredInBatches(deps) {
   const {
     ids,
@@ -66,6 +72,7 @@ function drainDeferredInBatches(deps) {
     onComplete,
     isDrainPaused,
     getTranscriptSize,
+    onSkip = () => {},
   } = deps || {};
   const size = Math.max(1, Math.floor(Number(batchSize)) || 1);
   const budgetMs = Math.max(0, Math.floor(Number(batchBudgetMs)) || 0);
@@ -75,6 +82,11 @@ function drainDeferredInBatches(deps) {
   // front (its original relative position is preserved by the filter below).
   let remaining = Array.isArray(ids) ? ids.slice() : [];
   const totalCount = remaining.length;
+  // WP-3 (§9 S-18): `false` starts that stayed resumable (the id goes back to the front of the
+  // queue and is re-attempted after the normal gap) and the pause-transition latch. Neither
+  // changes what is started, requeued, broadcast or when the drain completes.
+  let requeues = 0;
+  let pauseReported = false;
 
   async function tick() {
     if (!remaining.length) {
@@ -82,15 +94,18 @@ function drainDeferredInBatches(deps) {
       return;
     }
     if (typeof isDrainPaused === 'function' && isDrainPaused()) {
+      if (!pauseReported) { pauseReported = true; onSkip('DrainPaused', '', null); }
       scheduleGap(tick, {
         phase: 'paused',
         resumedInBatch: 0,
         elapsedMs: 0,
         budgetMs,
         remaining: remaining.length,
+        requeues,
       });
       return;
     }
+    pauseReported = false;
     const batchWindow = remaining.slice(0, size);
     const ordered = typeof getTranscriptSize === 'function'
       ? batchWindow.slice().sort((a, b) => Number(getTranscriptSize(a) || 0) - Number(getTranscriptSize(b) || 0))
@@ -112,6 +127,11 @@ function drainDeferredInBatches(deps) {
           if (started !== false || !stillResumable) {
             processed.add(id);
             resumedInBatch++;
+          } else {
+            // WP-3 (§9 S-18): a refused start that is still resumable stays at the front of the
+            // queue and will be re-attempted after the gap. Counted, never capped -- the cap
+            // decision needs this counter's live data first (design D-9).
+            requeues++;
           }
         } catch (e) {
           if (typeof onError === 'function') onError(id, e);
@@ -145,12 +165,13 @@ function drainDeferredInBatches(deps) {
       elapsedMs,
       budgetMs,
       remaining: remaining.length,
+      requeues,
     });
   }
 
   // First tick is scheduled through the same gap (the original kicked off with
   // setTimeout(resumeNext, gap) after the identity-cache prebuild settled).
-  scheduleGap(tick, { phase: 'initial', resumedInBatch: 0, elapsedMs: 0, budgetMs, remaining: totalCount });
+  scheduleGap(tick, { phase: 'initial', resumedInBatch: 0, elapsedMs: 0, budgetMs, remaining: totalCount, requeues });
 }
 
 module.exports = { drainDeferredInBatches };

package/template/coding-task-manager/lib/resume-blocked-wire.js

@@ -50,6 +50,54 @@ function deriveTranscriptStateFromInfo(info) {
   });
 }
 
+// The ladder fields every resume-blocked message for a missing transcript carries (S-33).
+// WP-0 moved this out of server.js unchanged (same body, same precedence); server.js imports it.
+function resumeBlockedRungWire(info) {
+  return {
+    resumeRung: info?.resumeRung || '', coverage: info?.coverage || null, offerStoreFirst: info?.offerStoreFirst === true, restoreError: info?.restoreError || '',
+    deterministic: info?.deterministic === true, origin: info?.origin || 'unknown',
+    storeTurns: normalizeStoreTurns(info?.storeTurns), checkedAt: info?.checkedAt || '',
+  };
+}
+
+// WP-1 (session-exit-close-truth-2026-10-24.html §5 D-1/D-2, §6): the ONE chooser for the block a
+// deferred exit carries. Both exit handlers defer (keep the startup row); this decides whether the
+// defer may also claim a failure, and WHICH failure, from the exit evidence alone.
+//   - A resume that never became ready is a RESUME failure, whatever the exit code says -- checked
+//     FIRST, so it is never swallowed by the unknown-exit rule below (S-11 rule 1 beats rule 2).
+//   - An unknown exit (`exitSource === 'eof'` + a null code, a handed-off PTY macOS cannot reap) is
+//     NOT a crash verdict (D-1): the defer carries no block, so the session presents as exited and
+//     the next input resumes it. "Recovery was exhausted" would be a lie -- no restart ran.
+//   - `session_crash_loop` ("automatic recovery was exhausted") needs BOTH a known abnormal exit
+//     (a finite non-zero code, or a signal) AND a restart that actually ran (D-2).
+//   - Anything else known-abnormal is a plain crash with no recovery claim.
+// Returns the block to stamp on a defer, or null when the defer must carry no block.
+function deferBlockForExit({ exitPersistence, latestResumeExit, exitCode, signal, autoRestartCount, label }) {
+  const resumeExit = latestResumeExit || {};
+  if (resumeExit.failedBeforeReady) {
+    return { code: resumeExit.code || 'resume_failed', message: `${label} did not become ready while resuming.` };
+  }
+  if (exitPersistence?.reason === 'unknown-exit') return null;
+  const abnormalExit = (Number.isFinite(exitCode) && exitCode !== 0) || !!signal;
+  if (abnormalExit && Number(autoRestartCount) > 0) {
+    return { code: 'session_crash_loop', message: `${label} exited unexpectedly and automatic recovery was exhausted.` };
+  }
+  return { code: 'session_crashed', message: `${label} exited unexpectedly.` };
+}
+
+// WP-0 (D-8): the ONE diagnostic payload every resume-block site writes, so a card the user saw can
+// always be attributed to the code path that set it. `site` is always a literal at the call, never
+// derived from the record, because the whole point is to name the caller.
+function resumeBlockSetDetails(site, record) {
+  return {
+    site: String(site || 'unspecified'),
+    code: String(record?.code || ''),
+    deterministic: record?.deterministic === true,
+    storeHuman: Number(record?.storeTurns?.human) || 0,
+    rung: String(record?.resumeRung || ''),
+  };
+}
+
 function resumeBlockedWire(sessionId, info, { agentType = '', rungWire = null } = {}) {
   const i = info || {};
   return {
@@ -71,11 +119,24 @@ function resumeBlockedWire(sessionId, info, { agentType = '', rungWire = null }
     lastSeenAt: i.lastSeenAt || '',
     trashPath: i.trashPath || '',
     originalPath: i.originalPath || '',
+    // WP-3 (D-13): WHY the copy is in CTM's trash and WHEN it went there — recorded in the trash
+    // manifest, so the card can say what actually happened instead of guessing. Empty on servers
+    // (or rows) that predate the manifest keys.
+    trashReason: String(i.trashReason || ''),
+    trashedAt: String(i.trashedAt || ''),
     // WP-2 (multi-machine R-15): the three facts the resume-blocked card needs to say WHERE the transcript
     // is instead of only that it is missing. Additive keys; every field above keeps its value.
     transcriptState: deriveTranscriptStateFromInfo(i),
     originHostname: String(i.originHostname || ''),
     originIsPeer: i.originIsPeer === true,
+    // WP-6 (S-8, AC-6d): the tri-state above is PRESERVED exactly (`on_other_machine` is still the
+    // state — "the transcript is over there" is true); this ADDITIVE field is what makes the card
+    // actionable: when the origin instance is a registered, reachable machine, the client renders
+    // "Open on <displayName>" and posts the resume to the hub, which forwards it to that box. The
+    // key is absent (not null) when there is no such machine, so today's payload is byte-identical.
+    ...(i.openOnMachine && i.openOnMachine.instanceId
+      ? { openOnMachine: { instanceId: String(i.openOnMachine.instanceId), displayName: String(i.openOnMachine.displayName || '') } }
+      : {}),
     ...(rungWire || {}),
   };
 }
@@ -95,4 +156,4 @@ function sendResumeBlockedToClients(clients, payload, send) {
   return sent;
 }
 
-module.exports = { normalizeStoreTurns, normalizeLocalHistory, deriveTranscriptState, resumeBlockedWire, sendResumeBlockedToClients };
+module.exports = { normalizeStoreTurns, normalizeLocalHistory, deriveTranscriptState, resumeBlockedRungWire, resumeBlockSetDetails, resumeBlockedWire, sendResumeBlockedToClients, deferBlockForExit };