create-walle 0.10.1 → 0.10.3

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

@@ -0,0 +1,364 @@
+'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. Two dispatch lines use it today: WP-3's image-draft
+// line in api-prompts.js, and WP-2's three terminal-history reads in lib/api/sessions.js (through
+// `serveMirrorOrLocal` below):
+//
+//   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 — EIGHTEEN members. Each entry is [METHOD, RegExp on pathname]. The
+// first ten mirror the image-draft peer-control routes on the box (lib/auth-rules.js:164-179)
+// exactly; WP-1 of docs/composer-image-chip-stuck-submission-recovery-2026-10-30.html §5 R-1 adds the
+// eleventh, `POST /api/sessions/<id>/image-refs` (image-ref recording, session-scoped so it can be
+// forwarded); the next three are WP-2's box-owned terminal-history reads — the SINGULAR
+// `/api/session/<id>/(history-window|scrollback|painted-rows)` GETs
+// (docs/remote-session-history-reads-and-box-status-hooks-2026-10-26.html WP-2 / D-3), whose matching
+// `peerControl` row is lib/auth-rules.js's single anchor regex; the fourteenth is WP-13's canonical
+// conversation read for a BOX-OWNED session — the SINGULAR `/api/session/messages` GET, whose session
+// id rides the `?id=` query (see the member's own comment below); the last three are WP-1's box-owned
+// child-transcript routes — the native/worker review GETs and the native clear cutoff
+// (docs/remote-session-child-transcript-model-truth-and-restart-2026-10-27.html §5 D-2/D-3), whose
+// `peerControl` rows are lib/auth-rules.js:181/187/485. The
+// pairing meta-test is tests/peer-control-auth.test.js → `forwarded-route pairing: every
+// FORWARDED_SESSION_ROUTES member resolves to a peerControl HTTP rule with the same method`: it
+// iterates this set and 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$/],
+  // WP-1 (§5 R-1, §6, §8 WP-1): image-ref RECORDING is session-scoped so it can be forwarded too —
+  // the draft it resolves lives on the box that owns a MIRROR session, and the hub's local resolver
+  // cannot see it (it answered CTM_SESSION_IMAGE_REF_UNRESOLVED until this row existed). The singular
+  // `/api/session/image-refs` path is REMOVED, not aliased, and lib/auth-rules.js carries the paired
+  // peerControl row.
+  ['POST', /^\/api\/sessions\/[^/]+\/image-refs$/],
+  // WP-2/D-3: the box's terminal-history reads — SINGULAR `/api/session/`, not `/api/sessions/`.
+  ['GET', /^\/api\/session\/[^/]+\/history-window$/],
+  ['GET', /^\/api\/session\/[^/]+\/scrollback$/],
+  ['GET', /^\/api\/session\/[^/]+\/painted-rows$/],
+  // WP-13 (docs/deepseek-harness-acp-agent-2026-10-28.html §5 D-25, §8 WP-13, §9 R-1, §10 T-23): the
+  // CANONICAL conversation read — the one the Conv view polls. It was local-only, so a box-owned
+  // session's Conv showed nothing on the hub for EVERY agent (Claude and Codex included, not just
+  // dsh): the hub holds no session row for a mirror id, so its own reader answered empty. There is
+  // ONE generic forward — no dsh-only route and no hub mirror file. The session id is the `?id=`
+  // QUERY parameter here (server.js's apiSessionMessages reads `url.searchParams.get('id')`), so the
+  // dispatch line in lib/api/sessions.js passes that value as serveMirrorOrLocal's encodedSessionId.
+  // The pathname is fixed, which is all this predicate needs (D-3 is purely lexical).
+  ['GET', /^\/api\/session\/messages$/],
+  // WP-1 (docs/remote-session-child-transcript-model-truth-and-restart-2026-10-27.html §5 D-2):
+  // child-transcript reads and the clear cutoff are box-owned — the transcript and the native
+  // runtime live on the box; the hub has no row for a mirror id.
+  ['GET', /^\/api\/sessions\/[^/]+\/native-subagents\/[^/]+\/messages$/],
+  ['GET', /^\/api\/sessions\/[^/]+\/worker-transcript\/messages$/],
+  ['POST', /^\/api\/sessions\/[^/]+\/native-subagents\/clear$/],
+]);
+
+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;
+}
+
+/**
+ * D-1/D-4: serve `localHandler` for a local or unclaimed id (same tick, request untouched), or forward a mirror id.
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {URL} url
+ * @param {string} encodedSessionId  the raw path segment (route param '1')
+ * @param {(req, res, url, encodedSessionId) => any} localHandler
+ * @param {object} [deps]  passed through to isMirrorSessionRequest / maybeForwardSessionRequest
+ */
+function serveMirrorOrLocal(req, res, url, encodedSessionId, localHandler, deps = {}) {
+  let sessionId = '';
+  try { sessionId = decodeURIComponent(String(encodedSessionId || '')); }
+  catch { return localHandler(req, res, url, encodedSessionId); } // expected: a malformed id is the local handler's 4xx to give
+  if (!isMirrorSessionRequest(req, url, sessionId, deps)) return localHandler(req, res, url, encodedSessionId);
+  return maybeForwardSessionRequest(req, res, url, sessionId, deps)
+    .then((forwarded) => (forwarded ? undefined : localHandler(req, res, url, encodedSessionId)));
+}
+
+module.exports = {
+  FORWARDED_SESSION_ROUTES,
+  FORWARD_DEADLINE_MS,
+  STRIPPED_QUERY_PARAMS,
+  maybeForwardSessionRequest,
+  isForwardedSessionRoute,
+  isMirrorSessionRequest,
+  serveMirrorOrLocal,
+};

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/remote-terminal-target.js

@@ -2,10 +2,17 @@
 
 const attemptOwners = new WeakMap();
 
+// The delivery target's process identity: a PTY session's ptyProcess, or an ACP (DeepSeek Harness)
+// session's `_acpProcess` token — set once per child by lib/session-create/dsh-session.js and cleared when
+// the child exits — so a replaced or dead ACP child retires the target exactly like a replaced PTY.
+function targetProcessOf(session) {
+  return session?.ptyProcess || session?._acpProcess || null;
+}
+
 function captureRemoteTerminalTarget(sessionId, session, sessionSource, getProcessGeneration) {
   const getSession = typeof sessionSource === 'function' ? sessionSource : id => sessionSource?.get(id);
   const originalSession = session && typeof session === 'object' ? session : null;
-  const originalPtyProcess = originalSession?.ptyProcess || null;
+  const originalPtyProcess = targetProcessOf(originalSession);
   const originalGeneration = originalSession && typeof getProcessGeneration === 'function'
     ? getProcessGeneration(originalSession)
     : null;
@@ -19,7 +26,7 @@ function captureRemoteTerminalTarget(sessionId, session, sessionSource, getProce
     }
     const current = getSession(sessionId);
     const matches = current === originalSession
-      && current.ptyProcess === originalPtyProcess
+      && targetProcessOf(current) === originalPtyProcess
       && typeof getProcessGeneration === 'function'
       && getProcessGeneration(current) === originalGeneration;
     if (!matches) targetRetired = true;

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

@@ -81,13 +81,17 @@ function summarizeRestartGuard(sessions = [], options = {}) {
       ? normalizeWaitingReason(options.waitingReasonForSession(session))
       : defaultWaitingReasonForSession(session);
     const summary = restartSessionSummary(session, rawStatus, waitingForInput, waitingReason);
-    // WP-4 (pty-survival design doc, S-16): a restart no longer kills a HOSTED
-    // session's live process (WP-1/2 linger + WP-3 boot adoption) -- a
-    // running/busy hosted session survives the restart itself, so it must stop
-    // counting as "would be interrupted". Approval/choice waits still block:
-    // those are a human decision left hanging mid-turn, not process survival.
+    // WP-4 (pty-survival design doc, S-16) + WP-2 (session-host-cgroup-survival design doc, D-5): a HOSTED
+    // session's live process survives a restart ONLY IF its host actually survives CTM's exit -- true under
+    // launchd (proven), and under systemd only when the host was moved out of ctm.service's cgroup
+    // (KillMode=control-group reaps everything else). `options.hostSurvivesRestart(session)` answers that at
+    // snapshot time; when absent it defaults to true (callers/tests that never knew about cgroups). A running or
+    // busy session whose host would NOT survive blocks like a non-hosted one. Approval/choice waits still
+    // block: those are a human decision left hanging mid-turn, not process survival.
     const isHosted = typeof options.isHostedSession === 'function' ? !!options.isHostedSession(session) : false;
-    const runningBlocked = BLOCKING_STATUSES.has(summary.status) && !isHosted;
+    const survives = isHosted && (typeof options.hostSurvivesRestart === 'function' ? !!options.hostSurvivesRestart(session) : true);
+    summary.hostSurvives = isHosted ? survives : null;
+    const runningBlocked = BLOCKING_STATUSES.has(summary.status) && !survives;
     const waitingBlocked = summary.status === 'waiting_input' &&
       isBlockingWaitingSession(session, summary, waitingForInput, waitingReason, options);
     if (runningBlocked || waitingBlocked) blockers.push(summary);
@@ -107,6 +111,14 @@ function summarizeRestartGuard(sessions = [], options = {}) {
     blockers.push(summary);
   }
 
+  // WP-3 (docs/session-create-box-restart-and-git-lane-starvation-2026-10-30.html §6.3/§8):
+  // an in-flight CREATE has no session row yet, so the loop above cannot see it — but a restart
+  // would still abort it. Each entry is appended VERBATIM (the caller owns the shape:
+  // `{ id, kind: 'create_in_progress', ... }`), and counts as a blocker. Absent/empty => unchanged.
+  for (const entry of options.pendingCreates || []) {
+    if (entry) blockers.push(entry);
+  }
+
   return {
     preflight,
     totalCount: items.length,

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' });