create-walle 0.10.2 → 0.10.3

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

@@ -42,6 +42,9 @@ const MACHINE_HEADER = 'x-ctm-machine';
 const MACHINE_QUERY_PARAM = 'machine';
 const DEFAULT_TIMEOUT_MS = 10_000;
 const BODY_LIMIT_BYTES = 1024 * 1024;
+// D-5 (§6.4): a box mid fleet-update is silent for a minute or two. A bundle the hub sent inside
+// this window is what lets a 502 name the update instead of leaving the user with "unreachable".
+const FLEET_UPDATE_MAX_AGE_MS = 10 * 60 * 1000;
 
 // The four routes this WP proxies (§9 S-9/S-10). Keyed `METHOD /pathname`, the same spelling the
 // lead passes as `{ route }`.
@@ -72,6 +75,39 @@ const PROXIED_ROUTES = Object.freeze([
   'GET /api/providers/login-state',
   'POST /api/providers/:id/login',
   'POST /api/providers/:id/login/code',
+  // WP-2 (docs/remote-box-model-access-2026-10-26.html §6.3, §5.1 R-4, §5.3 D-4): the picker's four
+  // lead-model calls for a MIRROR session are answered by the BOX that owns the session, through
+  // lib/remote-machine-catalog.js `forwardLeadModelRequest`, which names the REAL box path. Declared
+  // here so the box-routed route list stays the ONE inventory of what crosses the peer leg (the same
+  // `:id` spelling as the templated rows above).
+  'GET /api/sessions/:id/lead-model/options',
+  'POST /api/sessions/:id/lead-model',
+  'GET /api/sessions/:id/lead-model/request',
+  'DELETE /api/sessions/:id/lead-model/request',
+  // WP-3 (docs/remote-session-child-transcript-model-truth-and-restart-2026-10-27.html §5 D-4, §8
+  // WP-3): the Delegate pane's ladder read for a BOX-owned session is answered by the box that owns
+  // it, through lib/api/walle-bridge.js `handleProxy` → lib/remote-machine-catalog.js
+  // `forwardDelegatePrefsRequest` (a MIRROR lookup on the `ctm_session_id` query param, not a path
+  // id). Declared here so this list stays the ONE inventory of what crosses the peer leg.
+  'GET /api/models/delegate-prefs',
+  // WP-1 (docs/remote-session-delegate-pick-write-forward-2026-10-30.html D-1/D-2/D-7): the same
+  // forward carries the two WRITES that set a rung of that box's own ladder — a pick saved on the
+  // hub's Wall-E is one the box never reads. Same peer leg, same `ctm_session_id` ownership lookup.
+  'PUT /api/models/delegate-prefs',
+  'DELETE /api/models/delegate-prefs/:scope',
+  // WP-0 (docs/recent-sessions-follow-computer-filter-2026-10-31.html §5 D-2, §6): with a box
+  // selected the Recent list, its server-side search and the single-click review transcript all
+  // come from that box — the same ?machine= + peer-bearer leg as every row above, so the hub never
+  // has to mirror a box's sessions. The box already answers /api/recent-sessions and admits the
+  // peer bearer for it (lib/auth-rules.js); the other two rows gain the flag in the same change.
+  'GET /api/recent-sessions',
+  'GET /api/sessions/search',
+  'GET /api/session/messages',
+  // WP-4 (docs/fleet-session-lists-hub-search-2026-11-01.html §6.3, §9 S-15): the PE conversations
+  // list is fleet-wide (api-prompts.js wraps it with fleetRouted), so a stamped row's single-click
+  // view is answered by the BOX that owns the conversation — same `?machine=` + peer-bearer leg as
+  // the rows above, with lib/auth-rules.js admitting the peer bearer for both shapes.
+  'GET /api/conversations/:id',
 ]);
 
 // S-10 mixed-request refusal: a create that names a REMOTE machine must carry the BOX-owned source
@@ -178,6 +214,63 @@ function _recencyScore(row, index) {
   return index ? -index : 0;
 }
 
+// ---------------------------------------------------------------------------------------------
+// WP-4 (D-5, §6.4): the failure trace and the "box is restarting for an update" name.
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * D-5: ONE line per failed forward, so the next 02:20 has a record on the hub. `route`, `machine`
+ * and `status` are the only identifiers; `detail` is the refusal's own short reason. Headers,
+ * bodies and tokens are NEVER logged.
+ */
+function _logProxyFailure(route, machine, status, detail, startedAt) {
+  const elapsedMs = Math.max(0, Date.now() - (Number(startedAt) || Date.now()));
+  console.warn(`[remote-proxy] ${route} machine=${machine} status=${status} detail=${_string(detail, 300)} elapsedMs=${elapsedMs}`);
+}
+
+/**
+ * D-5: the hub's persisted per-box fleet record -> `{ to, sentAt }` for a box the hub sent a
+ * bundle to inside the last 10 minutes, else null. Reads the normalized shape
+ * lib/fleet-hub.js `_normalizeHubState` produces: `{ inFlight: {instanceId, target, sentAt}|null,
+ * boxes: { [id]: { lastSentAt, attempts: { [target]: {sentAt, verdict, reason} } } } }`.
+ */
+function _fleetUpdateFromHubState(state, instanceId, now = Date.now()) {
+  const id = _string(instanceId, 160);
+  if (!state || !id) return null;
+  const fresh = (sentAt) => Number.isFinite(sentAt) && sentAt > 0 && now - sentAt < FLEET_UPDATE_MAX_AGE_MS;
+  const inFlight = state.inFlight;
+  if (inFlight && _string(inFlight.instanceId, 160) === id && fresh(Number(inFlight.sentAt))) {
+    return { to: _string(inFlight.target, 200), sentAt: Number(inFlight.sentAt) };
+  }
+  const box = state.boxes && typeof state.boxes === 'object' ? state.boxes[id] : null;
+  const attempts = box && box.attempts && typeof box.attempts === 'object' ? box.attempts : null;
+  if (!attempts) return null;
+  let best = null;
+  for (const [target, attempt] of Object.entries(attempts)) {
+    if (!attempt || typeof attempt !== 'object') continue;
+    if (String(attempt.verdict || '') !== 'sent') continue;
+    const sentAt = Number(attempt.sentAt);
+    if (!fresh(sentAt)) continue;
+    if (!best || sentAt > best.sentAt) best = { to: _string(target, 200), sentAt };
+  }
+  return best;
+}
+
+/**
+ * D-5: the injected seam (`deps.fleetUpdateFor(instanceId)`), defaulting to the hub's own
+ * `<dataDir>/fleet-hub.json`. A lookup failure — no file, unreadable data dir, a throwing stub —
+ * is null and NOTHING else: naming an update may never change the proxy's own outcome.
+ */
+async function _fleetUpdateFor(deps, instanceId) {
+  try {
+    if (typeof deps.fleetUpdateFor === 'function') return await deps.fleetUpdateFor(instanceId);
+    const state = await require('./fleet-hub').readHubState(require('./data-dir').getDataDir());
+    return _fleetUpdateFromHubState(state, instanceId, Date.now());
+  } catch {
+    return null; /* expected: no fleet record yet (or an unreadable data dir) — the proxy still answers 502 */
+  }
+}
+
 /**
  * The routing machine id, or '' when this request is not machine-routed at all.
  * Query/header are consulted first so the common GET path never touches the request body.
@@ -197,6 +290,26 @@ function isMachineRouted(req, url) {
   return !!_machineFromRequest(req, _resolveUrl(req, url));
 }
 
+/**
+ * WP-0 (docs/recent-sessions-follow-computer-filter-2026-10-31.html §5 D-2, §6): wrap a route
+ * handler so a picker request naming another machine (?machine= / X-CTM-Machine) is answered by
+ * that box and every other request is the unchanged local handler — the same shape
+ * lib/api/misc-ops.js's `_machineRouted` keeps for its own rows. Exported so lib/api/sessions.js
+ * can wrap its three rows without a fourth private copy (and without growing past its file-size
+ * ceiling). `local` runs exactly when the request is not machine-routed, or when the hook declines
+ * (a route it does not own) — the `handled === true` case never touches it.
+ *
+ * @param {string} route  `'METHOD /pathname'`, the key PROXIED_ROUTES spells
+ * @param {(req: any, res: any, url: URL) => any} local
+ * @returns {(req: any, res: any, url: URL) => any}
+ */
+function machineRouted(route, local) {
+  return (req, res, url) => (isMachineRouted(req, url)
+    ? maybeProxyMachineRequest(req, res, url, { route })
+      .then((handled) => (handled ? undefined : local(req, res, url)))
+    : local(req, res, url));
+}
+
 function _localInstanceId(deps) {
   if (typeof deps.localInstanceId === 'string') return _string(deps.localInstanceId, 160);
   try {
@@ -273,6 +386,9 @@ async function maybeProxyMachineRequest(req, res, url, options = {}) {
   const isPost = route.startsWith('POST ');
   const machine = _machineFromRequest(req, parsed);
   if (!machine) return false;
+  // D-5: the clock every `[remote-proxy]` line reports against — the whole machine-routed
+  // handling, from the registry read to the box's answer.
+  const startedAt = Date.now();
   let rawBody = null;
   let parsedBody = null;
 
@@ -306,14 +422,22 @@ async function maybeProxyMachineRequest(req, res, url, options = {}) {
   }
 
   const machineName = _string(target.displayName, 200) || machine;
-  const unreachable = (extra = {}) => _sendJson(res, 502, {
-    ok: false,
-    code: 'machine_unreachable',
-    error: `Machine ${machineName} is unreachable`,
-    machine,
-    machineName,
-    ...extra,
-  });
+  // D-5: every 502 is logged once, and names the update the box is applying when the hub's fleet
+  // record says a bundle went to it inside the last 10 minutes.
+  const unreachable = async (extra = {}) => {
+    const status = 502;
+    _logProxyFailure(route, machine, status, extra.detail || extra.error || '', startedAt);
+    const update = await _fleetUpdateFor(deps, machine);
+    return _sendJson(res, status, {
+      ok: false,
+      code: 'machine_unreachable',
+      error: `Machine ${machineName} is unreachable`,
+      machine,
+      machineName,
+      ...extra,
+      ...(update && typeof update === 'object' ? { box_updating: { to: _string(update.to, 200) } } : {}),
+    });
+  };
 
   // S-10: a create that mixes a hub-local worktree source with a remote machine is refused rather
   // than silently creating a worktree on the hub (whose path the caller would then hand to the box).
@@ -358,6 +482,7 @@ async function maybeProxyMachineRequest(req, res, url, options = {}) {
   // what it says: the box was dialled and did not answer.
   if (!peerHeaders) {
     const missing = _peerCredentialMissing(machineName);
+    _logProxyFailure(route, machine, 503, missing.code, startedAt);
     return _sendJson(res, 503, {
       ok: false,
       code: missing.code,
@@ -430,7 +555,13 @@ async function maybeProxyMachineRequest(req, res, url, options = {}) {
   if (res.headersSent) return true;
   // The box's status and body are returned VERBATIM (§6.5): the picker parses the box's own
   // payload shape, and a hub that re-shaped it would drift from the local case.
-  res.writeHead(Number(response.status) || 502, {
+  const upstreamStatus = Number(response.status) || 502;
+  // D-5: a non-2xx answer from the box is a failed forward like any other. The body is never
+  // logged — only "upstream", because the box's own payload may carry anything.
+  if (upstreamStatus < 200 || upstreamStatus >= 300) {
+    _logProxyFailure(route, machine, upstreamStatus, 'upstream', startedAt);
+  }
+  res.writeHead(upstreamStatus, {
     'Content-Type': _string(response.headers && response.headers.get && response.headers.get('content-type'), 200)
       || 'application/json',
   });
@@ -509,12 +640,15 @@ module.exports = {
   MACHINE_HEADER,
   MACHINE_QUERY_PARAM,
   DEFAULT_TIMEOUT_MS,
+  FLEET_UPDATE_MAX_AGE_MS,
   PROXIED_ROUTES,
   configure,
   isMachineRouted,
+  machineRouted,
   maybeProxyMachineRequest,
   forwardMachineHttp,
   matchBoxProject,
   normalizeGitRemote,
   _recencyScore,
+  _fleetUpdateFromHubState,
 };

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

@@ -12,8 +12,9 @@
 // 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):
+// 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
@@ -66,11 +67,24 @@ const FORWARDED_REQUEST_HEADERS = Object.freeze(['content-type', 'content-length
 // 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).
+// 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$/],
@@ -82,6 +96,31 @@ const FORWARDED_SESSION_ROUTES = Object.freeze([
   ['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) {
@@ -296,6 +335,24 @@ async function maybeForwardSessionRequest(req, res, url, sessionId, deps = {}) {
   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,
@@ -303,4 +360,5 @@ module.exports = {
   maybeForwardSessionRequest,
   isForwardedSessionRoute,
   isMirrorSessionRequest,
+  serveMirrorOrLocal,
 };

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/restore-seed-modes.js

@@ -0,0 +1,87 @@
+'use strict';
+
+// WP-1 (docs/claude-restore-seed-alt-screen-trap-2026-10-27.html §5 R-1/R-2/R-5, §6, §8, §9):
+// a restore seed fed to a NEW process's headless mirror must be CONTENT-ONLY. The persisted
+// snapshot of a fullscreen Claude begins with `ESC[?1049h` (xterm SerializeAddon serializes an
+// active alternate buffer that way). Fed to a newly-started Claude that renders INLINE -- which
+// never emits `ESC[?1049l` because it never entered -- the mirror stays on the alternate buffer
+// forever: DECSET 1049 disables scrollback while active, CTM strips mouse enables from snapshots,
+// so the tab has no mouse and no history and the UI shows "Scrolling is off until this app
+// reports its mouse mode". This module rewrites the seed so the NEW process alone decides the
+// terminal modes:
+//   * every alternate-screen ENTER (`?1049h`/`?1047h`/`?47h`, including inside a multi-param
+//     DECSET such as `ESC[?2004;1049h`) is replaced by a push-out into normal-buffer history --
+//     the same shape lib/seed-push-out.js:17 (`seedPushOutSequence`) emits, with n = rows -- so
+//     the picture that followed the enter survives as scrollback instead of being covered;
+//   * every alternate-screen LEAVE (`?1049l`/`?1047l`/`?47l`, incl. inside a multi-param DECRST)
+//     is dropped (the new process never entered, so a leave is meaningless);
+//   * every mouse-tracking ENABLE (MOUSE_PARAMS with `h`) is dropped -- mouse truth must come only
+//     from the live process (R-2 / the read-only R-10 contract); mouse DISABLES (`l`) are kept.
+// Pure: no I/O, no shared state. Applied to the WHOLE seed before slicing (R-5) so a DECSET is
+// never torn across feedSliceChars chunks.
+//
+// NOT used by lib/host-handoff.js (R-3): a same-process handoff keeps the real alternate screen.
+// The push-out is emitted once per DECSET that named at least one alt-screen param; the three
+// counters each report the number of individual params removed.
+
+const ALT_SCREEN_PARAMS = [1049, 1047, 47];
+const MOUSE_PARAMS = [1000, 1002, 1003, 1005, 1006, 1015, 1016];
+
+const ALT_SET = new Set(ALT_SCREEN_PARAMS);
+const MOUSE_SET = new Set(MOUSE_PARAMS);
+
+// A private DECSET/DECRST: `ESC [ ? <;params> h|l`. Params are decimal.
+const DEC_MODE_RE = /\x1b\[\?([0-9;]*)([hl])/g;
+
+// The push-out shape -- byte-identical to lib/seed-push-out.js:17 seedPushOutSequence with
+// cursorY >= rows (n = rows): move to the bottom row, emit one LF per row (scrolling each seed
+// row into history), then home the cursor.
+function pushOutSequence(rows) {
+  return '\x1b[' + rows + ';1H' + '\n'.repeat(rows) + '\x1b[H';
+}
+
+function contentOnlyRestoreSeed(data, rows) {
+  if (typeof data !== 'string') {
+    return { data, altEntersConverted: 0, altLeavesDropped: 0, mouseEnablesDropped: 0 };
+  }
+  // Never guess a row count: anything that is not an integer >= 1 drops alt enters outright.
+  const validRows = Number.isInteger(rows) && rows >= 1;
+  let altEntersConverted = 0;
+  let altLeavesDropped = 0;
+  let mouseEnablesDropped = 0;
+
+  const out = data.replace(DEC_MODE_RE, (match, paramsStr, final) => {
+    if (!paramsStr) return match; // `ESC[?h` / `ESC[?l` name no mode -> leave untouched
+    const params = paramsStr.split(';');
+    const kept = [];
+    let altCount = 0;
+    let mouseCount = 0;
+    for (const param of params) {
+      const n = Number(param);
+      if (final === 'h' && ALT_SET.has(n)) { altCount += 1; continue; }
+      if (final === 'l' && ALT_SET.has(n)) { altLeavesDropped += 1; continue; }
+      if (final === 'h' && MOUSE_SET.has(n)) { mouseCount += 1; continue; }
+      kept.push(param);
+    }
+    if (final === 'l') {
+      // Alt leaves already dropped; keep the other params verbatim (or remove the DECRST).
+      return kept.length ? '\x1b[?' + kept.join(';') + 'l' : '';
+    }
+    // final === 'h'
+    mouseEnablesDropped += mouseCount;
+    if (altCount > 0) {
+      altEntersConverted += altCount;
+      const head = kept.length ? '\x1b[?' + kept.join(';') + 'h' : '';
+      return head + (validRows ? pushOutSequence(rows) : '');
+    }
+    if (mouseCount === 0) return match; // nothing matched -> preserve the exact bytes
+    return kept.length ? '\x1b[?' + kept.join(';') + 'h' : '';
+  });
+
+  if (altEntersConverted === 0 && altLeavesDropped === 0 && mouseEnablesDropped === 0) {
+    return { data, altEntersConverted, altLeavesDropped, mouseEnablesDropped };
+  }
+  return { data: out, altEntersConverted, altLeavesDropped, mouseEnablesDropped };
+}
+
+module.exports = { contentOnlyRestoreSeed, ALT_SCREEN_PARAMS, MOUSE_PARAMS };

package/template/coding-task-manager/lib/restored-scrollback-hydration-runtime.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { contentOnlyRestoreSeed } = require('./restore-seed-modes');
+
 // Owns the restored-scrollback probe/feed transaction. The host supplies archive,
 // worker, session, and diagnostic boundaries; this module owns ordering and policy.
 function createRestoredScrollbackHydrationRuntime(deps = {}) {
@@ -80,6 +82,24 @@ function createRestoredScrollbackHydrationRuntime(deps = {}) {
     return tail;
   }
 
+  // WP-1 (docs/claude-restore-seed-alt-screen-trap-2026-10-27.html §5 R-1/R-2/R-5): strip the
+  // dead process's terminal modes from the seed so the NEW process alone decides the buffer and
+  // the mouse. Applied to the whole (already bounded) string so a DECSET is never split across
+  // feed slices. Idempotent, so hydrateInBackground (prepareSeed -> feed) records exactly one
+  // 'restore-seed-modes' diagnostic -- at whichever stage actually removed a mode.
+  function contentOnlySeed(sessionId, scrollData, seedRows) {
+    const cleaned = contentOnlyRestoreSeed(scrollData, seedRows);
+    if (cleaned.altEntersConverted || cleaned.altLeavesDropped || cleaned.mouseEnablesDropped) {
+      recordDiagnostic(sessionId, 'restore-seed-modes', {
+        altEntersConverted: cleaned.altEntersConverted,
+        altLeavesDropped: cleaned.altLeavesDropped,
+        mouseEnablesDropped: cleaned.mouseEnablesDropped,
+        seedRows: seedRows === undefined ? null : seedRows,
+      });
+    }
+    return cleaned.data;
+  }
+
   async function prepareSeed(sessionId, scrollDataIn, opts = {}) {
     let probe = { aligned: false, reason: 'flag-off', archiveLastRow: null };
     if (alignedEnabled) {
@@ -103,7 +123,7 @@ function createRestoredScrollbackHydrationRuntime(deps = {}) {
       drift: seam.drift,
     });
     return {
-      data: boundInput(sessionId, scrollDataIn, probe.aligned === true),
+      data: contentOnlySeed(sessionId, boundInput(sessionId, scrollDataIn, probe.aligned === true), opts.seedRows),
       seedAligned: probe.aligned === true,
       forwardDriftSeamRow: probe.mode === 'forward-drift' ? seam.recordedSeamRow : null,
     };
@@ -114,7 +134,7 @@ function createRestoredScrollbackHydrationRuntime(deps = {}) {
     const forwardDriftSeamRow = Number.isFinite(opts.forwardDriftSeamRow)
       ? opts.forwardDriftSeamRow
       : null;
-    const scrollData = boundInput(sessionId, scrollDataIn, seedAligned);
+    const scrollData = contentOnlySeed(sessionId, boundInput(sessionId, scrollDataIn, seedAligned), opts.seedRows);
     if (!sessionId || !scrollData) {
       opts.onDone?.('empty');
       return;

package/template/coding-task-manager/lib/resume-admission.js

@@ -703,7 +703,7 @@ function classifyStartupTaskRestore(task, restoredOrdinal, fastSessionCount, ali
   ) {
     return 'adopt';
   }
-  if (task?.type === 'walle') return 'eager';
+  if (task?.type === 'walle') return 'eager'; if (task?.type === 'dsh') return 'defer'; // D-A (WP-5): dsh NEVER spawns at boot -- it is a childless deferred placeholder, started on attach/input by lib/session-create/dsh-session.js's restoreDshSession.
   if (primary && task?._restoreInterruption?.interrupted) return 'eager'; // WP-2: resume an interrupted turn now
   const ordinal = Number(restoredOrdinal) || 0;
   const fastCount = Number(fastSessionCount) || 0;
@@ -790,12 +790,24 @@ function orderAutoResumeDeferredIds(deferredIds, priorityIds) {
 
 function selectAutoResumeDeferredIds(deferredIds, priorityIds, policy) {
   const ids = Array.isArray(deferredIds) ? deferredIds.filter(Boolean).map(String) : [];
-  if (!ids.length || !policy || !policy.enabled || policy.limit <= 0) return [];
+  // WP-2 (docs/external-causality-kill-session-loss-2026-10-27.html §6): the ONE escape from the
+  // boot cap, used by the explicit "Resume N sessions" control (POST /api/sessions/resume-deferred).
+  // `all` is read ONLY when present; with it absent every arm below is byte-identical to before.
+  const all = !!(policy && policy.all === true);
+  if (!ids.length) return [];
+  if (!all && (!policy || !policy.enabled || policy.limit <= 0)) return [];
   const ordered = orderAutoResumeDeferredIds(ids, priorityIds);
-  if (!Number.isFinite(policy.limit)) return ordered;
+  if (all || !Number.isFinite(policy.limit)) return ordered;
   return ordered.slice(0, Math.max(0, Math.floor(policy.limit)));
 }
 
+// WP-2 (§5 D-5, §6): the boot restore selector's cap as ONE object, so the adopted-host-death
+// drain reuses the exact boot policy instead of inventing a second one. Same CTM_AUTO_RESUME_DEFERRED
+// semantics resolveAutoResumeDeferredPolicy already applies at boot (mode 'off' ⇒ nothing drains).
+function bootAutoResumePolicy(env = process.env) {
+  return resolveAutoResumeDeferredPolicy(env);
+}
+
 // WP-3 (design doc §5 D-4, §8 WP-3, §9 S-17/S-18): explicit all/wide numeric
 // drains can still admit many eligible sessions, most-recent-first. The 2026-08-22
 // incident measured 8 sessions (~2.5 GB) auto-resumed on a host already at 88%
@@ -914,6 +926,7 @@ const resumeAdmission = {
     selectAutoResumeDeferredIds,
     orderAutoResumeDeferredIds,
     resolveAutoResumePolicy,
+    bootAutoResumePolicy,
     DEFAULT_SESSION_FOOTPRINT_MB,
   },
 };
@@ -949,5 +962,6 @@ module.exports = {
   selectAutoResumeDeferredIds,
   orderAutoResumeDeferredIds,
   resolveAutoResumePolicy,
+  bootAutoResumePolicy,
   DEFAULT_SESSION_FOOTPRINT_MB,
 };