create-walle 0.10.1 → 0.10.3

package/template/coding-task-manager/lib/host-fseventsd-sampler.js

@@ -0,0 +1,399 @@
+'use strict';
+
+// WP-2 (design doc coding-task-manager/docs/fsevents-churn-followups-r2-2026-10-26.html
+// §5 D-4..D-6, §6, §8 WP-2, §9 S-11): the host fseventsd sampler.
+//
+// Why it exists: fseventsd reached 2262 MB RSS on 2026-10-26 (§1.1) and nothing in this repo
+// recorded it. The parent AC-8d ("< 100 MB on 10-28") was unmeasurable and is superseded by
+// D-5: prove the sampler is alive (>= 1 row/hour of primary uptime), parse every JetsamEvent,
+// and attach a producer attribution to every growth event so "our trees are not the producer"
+// is a number instead of a feeling.
+//
+// Rules it obeys (§5 D-6, §11 anti-goals):
+//   * read-only instrumentation: it never starts, signals or heals fseventsd, never calls
+//     sudo/vmmap/sample/footprint, and never deletes anything;
+//   * every child process is ASYNC (execFile with a timeout, never execFileSync);
+//   * a metric is `top -l 1 -pid <pid> -stats pid,mem,cmprs` (no sudo; ~2.5 s wall) — chosen
+//     over vmmap (it suspends the target) and ps RSS (it excludes compressed pages);
+//   * every failure becomes an `error` row in the log; tick() never throws into the server.
+//
+// It runs inside the primary CTM process (launchd com.walle.server, survives reboot) — see
+// server.js's registration block, gated by shouldRunSampler().
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFile: defaultExecFile } = require('node:child_process');
+
+const SAMPLE_INTERVAL_MS = 30 * 60_000;
+const GROWTH_ATTRIBUTION_BYTES = 256 * 1024 * 1024;
+const ATTRIBUTION_MIN_GAP_MS = 6 * 60 * 60_000;
+// D-6: one `top` per sample, async, bounded.
+const TOP_TIMEOUT_MS = 10000;
+// §6: the attribution child runs `fs-event-census.js --seconds 30`, bounded at 60 s.
+const ATTRIBUTION_TIMEOUT_MS = 60000;
+const ATTRIBUTION_SECONDS = 30;
+const ATTRIBUTION_MAX_BUFFER = 8 * 1024 * 1024;
+const JETSAM_DIR = '/Library/Logs/DiagnosticReports';
+// §6: `memoryStatus.pageSize` (16384 on Apple silicon); 16384 is the documented fallback.
+const FALLBACK_PAGE_SIZE = 16384;
+const DEFAULT_LOG_PATH = path.join(os.homedir(), '.walle', 'logs', 'host-fseventsd.jsonl');
+const STATE_FILE_NAME = 'host-fseventsd.state.json';
+
+// ---------------------------------------------------------------------------
+// Gating (D-4). server.js inlines this condition (the doc's §6 snippet); the predicate is
+// exported so the gating itself is unit-testable without booting a server.
+// ---------------------------------------------------------------------------
+function shouldRunSampler({ platform = process.platform, devPort = '', flag = '1' } = {}) {
+  return platform === 'darwin' && !devPort && String(flag) !== '0';
+}
+
+// ---------------------------------------------------------------------------
+// parseTopLine (pure): the last line of
+//   top -l 1 -pid <pid> -stats pid,mem,cmprs
+// looks like `29548  2262M 637M`. Units may be B/K/M/G and may carry a +/- delta marker
+// (either side; the magnitude is what the row is about). Returns
+// { pid, memBytes, cmprsBytes } or null (e.g. for the `PID MEM CMPrS` header).
+// ---------------------------------------------------------------------------
+const TOP_ROW_RE = /^(\d+)\s+([+-]?[\d.]+)\s*([BKMG])?([+-])?\s+([+-]?[\d.]+)\s*([BKMG])?([+-])?$/;
+const UNIT_MULTIPLIERS = { B: 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3 };
+
+function unitToBytes(value, unit) {
+  const n = Math.abs(Number(value));
+  if (!Number.isFinite(n)) return null;
+  const multiplier = UNIT_MULTIPLIERS[String(unit || '').toUpperCase()] || 1;
+  return Math.round(n * multiplier);
+}
+
+function parseTopLine(line) {
+  const s = String(line === null || line === undefined ? '' : line).trim();
+  if (s === '') return null;
+  const m = s.match(TOP_ROW_RE);
+  if (!m) return null;
+  const memBytes = unitToBytes(m[2], m[3]);
+  const cmprsBytes = unitToBytes(m[5], m[6]);
+  if (memBytes === null || cmprsBytes === null) return null;
+  return { pid: Number(m[1]), memBytes, cmprsBytes };
+}
+
+function lastNonEmptyLine(text) {
+  const lines = String(text === null || text === undefined ? '' : text).split('\n');
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (lines[i].trim() !== '') return lines[i];
+  }
+  return '';
+}
+
+// ---------------------------------------------------------------------------
+// sampleOnce: pgrep the pid, then one bounded async `top`.
+// Returns { at, pid, memBytes, cmprsBytes, raw } or { at, error } — never throws.
+// ---------------------------------------------------------------------------
+function runChild(execFile, file, args, options) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      fn(value);
+    };
+    const callback = (err, stdout, stderr) => {
+      if (err) settle(reject, err);
+      else settle(resolve, { stdout: String(stdout === null || stdout === undefined ? '' : stdout), stderr: String(stderr === null || stderr === undefined ? '' : stderr) });
+    };
+    let returned;
+    try {
+      returned = execFile(file, args, options, callback);
+    } catch (err) {
+      settle(reject, err);
+      return;
+    }
+    // HANDLE: an injected promise-style stand-in (a test fake) resolves instead of calling
+    // back; accept either shape so the fake needs no callback plumbing.
+    if (returned && typeof returned.then === 'function') {
+      returned.then(
+        (value) => settle(resolve, {
+          stdout: String(value && value.stdout !== undefined ? value.stdout : (value === undefined ? '' : value)),
+          stderr: String(value && value.stderr !== undefined ? value.stderr : ''),
+        }),
+        (err) => settle(reject, err),
+      );
+    }
+  });
+}
+
+async function sampleOnce({ execFile = defaultExecFile, now = Date.now } = {}) {
+  const at = now();
+  try {
+    const pidOut = await runChild(execFile, 'pgrep', ['-x', 'fseventsd'], { timeout: TOP_TIMEOUT_MS });
+    const pid = Number(String(pidOut.stdout).trim().split('\n')[0]);
+    if (!Number.isFinite(pid) || pid <= 0) return { at, error: 'pgrep -x fseventsd returned no pid' };
+    const topOut = await runChild(
+      execFile,
+      'top',
+      ['-l', '1', '-pid', String(pid), '-stats', 'pid,mem,cmprs'],
+      { timeout: TOP_TIMEOUT_MS },
+    );
+    const raw = lastNonEmptyLine(topOut.stdout);
+    const parsed = parseTopLine(raw);
+    if (!parsed) return { at, error: `unparsable top row ${JSON.stringify(raw)}` };
+    return { at, pid, memBytes: parsed.memBytes, cmprsBytes: parsed.cmprsBytes, raw };
+  } catch (err) {
+    return { at, error: String((err && err.message) || err) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// readNewJetsam: every JetsamEvent-*.ips newer than `lastSeen`, oldest first.
+// Format (§6): line 1 is a JSON header, the rest is one JSON body carrying
+// memoryStatus.pageSize, largestProcess, date and processes[] entries with name/rpages.
+// Returns [{ file, date, largestProcess, fseventsdBytes, pageSize }] — plus `error` when a
+// single file could not be read or parsed (the caller turns that into an `error` row).
+// ---------------------------------------------------------------------------
+async function readNewJetsam({ dir = JETSAM_DIR, lastSeen = '', fsImpl = fs } = {}) {
+  const io = fsImpl && fsImpl.promises ? fsImpl.promises : fsImpl;
+  let names;
+  try {
+    names = await io.readdir(dir);
+  } catch (err) {
+    // HANDLE: a host with no JetsamEvent directory (or no read permission) simply has no
+    // reports to ingest; that is not a sampler failure.
+    if (err && (err.code === 'ENOENT' || err.code === 'EACCES' || err.code === 'EPERM' || err.code === 'ENOTDIR')) return [];
+    throw err; // RETHROW: EMFILE/EIO are real problems worth an error row.
+  }
+  const since = String(lastSeen || '');
+  const files = names
+    .filter((name) => /^JetsamEvent-.*\.ips$/.test(name) && name > since)
+    .sort();
+  const rows = [];
+  for (const file of files) {
+    rows.push(await readJetsamFile(dir, file, io));
+  }
+  return rows;
+}
+
+async function readJetsamFile(dir, file, io) {
+  const pageSizeFallback = { file, date: null, largestProcess: null, fseventsdBytes: null, pageSize: FALLBACK_PAGE_SIZE };
+  let text;
+  try {
+    text = String(await io.readFile(path.join(dir, file), 'utf8'));
+  } catch (err) {
+    return { ...pageSizeFallback, error: `read failed: ${(err && err.message) || err}` };
+  }
+  const newline = text.indexOf('\n');
+  const headerText = newline === -1 ? text : text.slice(0, newline);
+  const bodyText = newline === -1 ? '' : text.slice(newline + 1);
+  let header = null;
+  let body = null;
+  try {
+    header = JSON.parse(headerText);
+  } catch {
+    /* expected: a truncated/foreign .ips header must not abort the remaining reports */
+  }
+  try {
+    body = JSON.parse(bodyText);
+  } catch {
+    /* expected: a truncated/foreign .ips body is reported as a per-file error below */
+  }
+  if (!body || typeof body !== 'object') {
+    return { ...pageSizeFallback, date: (header && header.timestamp) || null, error: 'body is not JSON' };
+  }
+  const pageSize = Number(body.memoryStatus && body.memoryStatus.pageSize) || FALLBACK_PAGE_SIZE;
+  const processes = Array.isArray(body.processes) ? body.processes : [];
+  const entry = processes.find((row) => row && row.name === 'fseventsd');
+  const rpages = entry && Number(entry.rpages);
+  return {
+    file,
+    date: body.date || (header && header.timestamp) || null,
+    largestProcess: body.largestProcess === undefined ? null : body.largestProcess,
+    fseventsdBytes: Number.isFinite(rpages) ? rpages * pageSize : null,
+    pageSize,
+    lifetimeMax: entry && entry.lifetimeMax !== undefined ? entry.lifetimeMax : null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// createSampler: append-only JSONL rows + a sibling state file so a restart keeps the growth
+// baseline (and does not re-ingest every JetsamEvent again).
+//   { kind: 'sample',      at, pid, memBytes, cmprsBytes }
+//   { kind: 'jetsam',      at, file, date, largestProcess, fseventsdBytes }
+//   { kind: 'attribution', at, memBytes, deltaBytes, census: { total, perSecond, categories, families } }
+//   { kind: 'error',       at, stage, message }
+// ---------------------------------------------------------------------------
+function defaultState() {
+  return { version: 1, lastJetsam: '', lastSample: null, lastAttributionAt: null, updatedAt: null };
+}
+
+function createSampler({
+  logPath = DEFAULT_LOG_PATH,
+  repoRoot,
+  now = Date.now,
+  execFile = defaultExecFile,
+  homeDir = os.homedir(),
+  tmpDir = os.tmpdir(),
+  jetsamDir = JETSAM_DIR,
+} = {}) {
+  const resolvedLogPath = logPath;
+  const statePath = path.join(path.dirname(resolvedLogPath), STATE_FILE_NAME);
+  const root = repoRoot || path.resolve(__dirname, '..', '..');
+  let state = null;
+
+  async function appendRow(row) {
+    await fs.promises.mkdir(path.dirname(resolvedLogPath), { recursive: true });
+    await fs.promises.appendFile(resolvedLogPath, `${JSON.stringify(row)}\n`, { mode: 0o600 });
+  }
+
+  // REPORT: an unwritable log must not stop the sampler from trying again next tick, so the
+  // caller sees the failure through console.warn in the server's timer callback.
+  async function appendRowSafe(row) {
+    try {
+      await appendRow(row);
+    } catch (err) {
+      process.stderr.write(`[fseventsd-sampler] log write failed: ${(err && err.message) || err}\n`);
+    }
+  }
+
+  async function loadState() {
+    if (state) return state;
+    try {
+      const parsed = JSON.parse(String(await fs.promises.readFile(statePath, 'utf8')));
+      state = { ...defaultState(), ...parsed };
+      return state;
+    } catch (err) {
+      if (err && err.code !== 'ENOENT') {
+        await appendRowSafe({ kind: 'error', at: now(), stage: 'state-read', message: String((err && err.message) || err) });
+      }
+      state = defaultState();
+      return state;
+    }
+  }
+
+  async function saveState() {
+    const tmp = `${statePath}.${process.pid}.tmp`;
+    state.updatedAt = new Date(now()).toISOString();
+    await fs.promises.writeFile(tmp, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+    await fs.promises.rename(tmp, statePath);
+  }
+
+  // The attribution snapshot: one census run over the three producers we own (§6, §1.2).
+  async function runAttributionCensus() {
+    const args = [
+      path.join(root, 'bin', 'fs-event-census.js'),
+      '--seconds', String(ATTRIBUTION_SECONDS),
+      '--json',
+      '--families',
+      '--root', tmpDir,
+      '--root', path.join(homeDir, '.walle'),
+      '--root', path.join(homeDir, 'ws'),
+    ];
+    const { stdout } = await runChild(execFile, process.execPath, args, {
+      timeout: ATTRIBUTION_TIMEOUT_MS,
+      maxBuffer: ATTRIBUTION_MAX_BUFFER,
+    });
+    const parsed = JSON.parse(stdout);
+    return {
+      total: parsed.total,
+      perSecond: parsed.perSecond,
+      categories: (Array.isArray(parsed.categories) ? parsed.categories : []).map((row) => ({
+        name: row.name, count: row.count, share: row.share, newUnique: row.newUnique,
+      })),
+      families: Array.isArray(parsed.families)
+        ? parsed.families.map((row) => ({ name: row.name, count: row.count, newUnique: row.newUnique }))
+        : [],
+    };
+  }
+
+  async function ingestJetsam(current) {
+    let rows;
+    try {
+      rows = await readNewJetsam({ dir: jetsamDir, lastSeen: current.lastJetsam });
+    } catch (err) {
+      await appendRowSafe({ kind: 'error', at: now(), stage: 'jetsam', message: String((err && err.message) || err) });
+      return;
+    }
+    for (const row of rows) {
+      if (row.error) {
+        await appendRowSafe({ kind: 'error', at: now(), stage: 'jetsam-parse', message: `${row.file}: ${row.error}` });
+      } else {
+        await appendRowSafe({
+          kind: 'jetsam',
+          at: now(),
+          file: row.file,
+          date: row.date,
+          largestProcess: row.largestProcess,
+          fseventsdBytes: row.fseventsdBytes,
+        });
+      }
+      // HANDLE: the name advances even for an unparsable report — .ips files are immutable,
+      // so re-reading one every 30 min would only repeat the same error row forever.
+      current.lastJetsam = row.file;
+    }
+  }
+
+  async function maybeAttribute(current, sample) {
+    const prev = current.lastSample;
+    if (!prev || !Number.isFinite(prev.memBytes) || !Number.isFinite(sample.memBytes)) return;
+    const deltaBytes = sample.memBytes - prev.memBytes;
+    if (deltaBytes <= GROWTH_ATTRIBUTION_BYTES) return;
+    if (current.lastAttributionAt !== null && sample.at - current.lastAttributionAt < ATTRIBUTION_MIN_GAP_MS) return;
+    try {
+      const census = await runAttributionCensus();
+      await appendRowSafe({ kind: 'attribution', at: sample.at, memBytes: sample.memBytes, deltaBytes, census });
+      current.lastAttributionAt = sample.at;
+    } catch (err) {
+      // REPORT: no attribution time is recorded, so the next sample retries (the 6 h gap only
+      // bounds successes, §6). The absence is visible as an `error` row beside the growth.
+      await appendRowSafe({ kind: 'error', at: sample.at, stage: 'attribution', message: String((err && err.message) || err) });
+    }
+  }
+
+  async function tick() {
+    let current;
+    let sample;
+    try {
+      current = await loadState();
+      sample = await sampleOnce({ execFile, now });
+      if (sample.error) {
+        await appendRowSafe({ kind: 'error', at: sample.at, stage: 'sample', message: sample.error });
+        return;
+      }
+      await appendRowSafe({ kind: 'sample', at: sample.at, pid: sample.pid, memBytes: sample.memBytes, cmprsBytes: sample.cmprsBytes });
+      await ingestJetsam(current);
+      await maybeAttribute(current, sample);
+      current.lastSample = { at: sample.at, memBytes: sample.memBytes };
+      await saveState();
+    } catch (err) {
+      // REPORT: tick() is called from a named interval and from a boot timer; a rejection
+      // there would only be logged by the caller, so it is recorded here as an error row.
+      await appendRowSafe({
+        kind: 'error',
+        at: now(),
+        stage: 'tick',
+        message: String((err && err.message) || err),
+      });
+    }
+  }
+
+  return {
+    tick,
+    // Test/ops surface (read-only): where rows and state live.
+    logPath: resolvedLogPath,
+    statePath,
+    loadState,
+  };
+}
+
+module.exports = {
+  SAMPLE_INTERVAL_MS,
+  GROWTH_ATTRIBUTION_BYTES,
+  ATTRIBUTION_MIN_GAP_MS,
+  ATTRIBUTION_SECONDS,
+  DEFAULT_LOG_PATH,
+  JETSAM_DIR,
+  STATE_FILE_NAME,
+  FALLBACK_PAGE_SIZE,
+  createSampler,
+  parseTopLine,
+  readNewJetsam,
+  sampleOnce,
+  shouldRunSampler,
+};

package/template/coding-task-manager/lib/host-handoff-orchestrator.js

@@ -173,10 +173,17 @@ async function probeSuccessor(ch, spawned, hostId, deadlineAt) {
 }
 
 // One handoff attempt. Resolves { ok:true, ... } or { ok:false, reason, attempted }; never rejects.
+//
+// WP-3 (D-3/S-3): opts.reason is 'upgrade' (default) or 'evacuate-threadpool'.
+// An evacuation is not an upgrade -- the host is being replaced because its
+// libuv pool is dead, so it does not need an 'upgrade-pending' compat entry to
+// be eligible (any entry, or none, passes). The recovery-protected check stays
+// first for both reasons, and 'upgrade' keeps today's check byte-for-byte.
 async function handoffHost(manager, hostId, opts = {}) {
+  const reason = opts.reason === 'evacuate-threadpool' ? 'evacuate-threadpool' : 'upgrade';
   if (manager.isRecoveryProtectedHost?.(hostId)) return { ok: false, attempted: false, reason: 'owner-recovery-pending' };
   const compat = manager.hostCompatibility.get(hostId);
-  if (!compat || compat.reason !== 'upgrade-pending') return { ok: false, attempted: false, reason: 'not-upgrade-pending' };
+  if (reason === 'upgrade' && (!compat || compat.reason !== 'upgrade-pending')) return { ok: false, attempted: false, reason: 'not-upgrade-pending' };
   const adapters = liveAdapters(manager, hostId);
   const first = adapters.values().next().value;
   const conn = first && first._socketConn && !first._socketConn.destroyed ? first._socketConn : null;
@@ -331,11 +338,18 @@ async function handoffHostWithRetry(manager, hostId, opts = {}) {
 }
 
 // Restore-loop tail (server.js): upgrade every upgrade-pending host, serially. Never throws.
-async function runUpgradePendingHandoffs({ manager, log = console.log, ...opts } = {}) {
+// WP-3 (S-4): skipHostIds names hosts the boot-time stall escalation (D-4) has
+// ALREADY decided to evacuate -- they are logged and left alone here, so no
+// rollup/stale flag/10-minute retry can be armed against a stalled host.
+async function runUpgradePendingHandoffs({ manager, skipHostIds = new Set(), log = console.log, ...opts } = {}) {
   const results = [];
   try {
     const hostIds = [...manager.hostCompatibility].filter(([, c]) => c && c.reason === 'upgrade-pending').map(([id]) => id);
     for (const hostId of hostIds) {
+      if (skipHostIds.has(hostId)) {
+        log(`[host-handoff] ${hostId} skipped: evacuating`);
+        continue;
+      }
       const result = await handoffHostWithRetry(manager, hostId, { ...opts, log });
       results.push(result);
       if (!result.attempted) {

package/template/coding-task-manager/lib/host-handoff.js

@@ -33,6 +33,14 @@ function modelProcessGenerationMetadata(value) {
   return validModelProcessGeneration(value) ? { modelProcessGeneration: value } : {};
 }
 const MODEL_STORAGE_ROOT_KEYS = Object.freeze(['HOME', 'CODEX_HOME', 'CTM_CODEX_SESSIONS_DIR', 'CLAUDE_CONFIG_DIR', 'GEMINI_CLI_HOME', 'OPENCODE_DATA_DIR', 'XDG_DATA_HOME']);
+// WP-0: the projected keys and the strip moved to lib/launch-environment.js (§5 D-1); re-exported from here so
+// the existing importers are unchanged. The keys a lead-model switch re-projects into the launch context
+// (lib/lead-model-restore-reconciliation.js projectDeferredRestoreLaunch: HOME / CODEX_HOME from the launch
+// context, TMPDIR alongside them) are PROJECTED launch context, not per-session private overrides: a spawn
+// still receives them, but their presence must never turn an otherwise empty override set into a private
+// environment that only a surviving owner can reproduce. Anything else in the env is private and is captured
+// by value.
+const { PROJECTED_LAUNCH_CONTEXT_KEYS, privateOverridesFromEnv, launchEnvironmentMetadata } = require('./launch-environment');
 function modelStorageRootsFromEnv(env) {
   const roots = {};
   for (const key of MODEL_STORAGE_ROOT_KEYS) {
@@ -51,8 +59,8 @@ function writeHandoffManifest(dir, oldHostId, entries, { manifestPath } = {}) {
   const target = manifestPath || path.join(dir, `handoff-${oldHostId}-${++manifestCounter}.json`);
   const tmp = `${target}.tmp-${process.pid}`;
   entries = entries.map((entry) => {
-    const { modelProcessGeneration, modelStorageRoots, modelExecutionRecipe, ...base } = entry;
-    return { ...base, ...modelProcessGenerationMetadata(modelProcessGeneration), ...modelStorageRootsMetadata(modelStorageRoots), ...modelExecutionRecipeMetadata(modelExecutionRecipe, { sessionId: entry.sessionId, processGeneration: modelProcessGeneration }) };
+    const { modelProcessGeneration, modelStorageRoots, modelExecutionRecipe, launchEnvironment, ...base } = entry;
+    return { ...base, ...modelProcessGenerationMetadata(modelProcessGeneration), ...modelStorageRootsMetadata(modelStorageRoots), ...modelExecutionRecipeMetadata(modelExecutionRecipe, { sessionId: entry.sessionId, processGeneration: modelProcessGeneration }), ...launchEnvironmentMetadata(launchEnvironment, { manifest: true }) };
   });
   fs.writeFileSync(tmp, JSON.stringify({ version: 1, oldHostId, entries }), { mode: 0o600 });
   fs.renameSync(tmp, target);
@@ -84,6 +92,10 @@ function readHandoffManifest(manifestPath) {
     const recipe = modelExecutionRecipeMetadata(entry.modelExecutionRecipe, { sessionId: entry.sessionId, processGeneration: entry.modelProcessGeneration });
     if (recipe.modelExecutionRecipe) entry.modelExecutionRecipe = recipe.modelExecutionRecipe;
     else delete entry.modelExecutionRecipe;
+    // WP-1 (S-11): a manifest written by an older host has no field at all -- absent stays absent.
+    const launchEnv = launchEnvironmentMetadata(entry.launchEnvironment, { manifest: true });
+    if (launchEnv.launchEnvironment) entry.launchEnvironment = launchEnv.launchEnvironment;
+    else delete entry.launchEnvironment;
   });
   fs.unlinkSync(manifestPath);
   return { entries: parsed.entries };
@@ -111,6 +123,10 @@ function isAlive(pid) {
 // listSessions() -> [{ sessionId, ptyProcess, ptyClosed, cols, rows, seq, cmd, cwd, name, outputEpoch,
 //   workerDisplayContext, suppressPtyHeadlessUntilInput, mirrorFeed }]; serialize(sessionId) -> {data,cols,rows}|null.
 const REPAINT_NUDGE_MS = 80;
+// D-1: the old host's painted-seal await is bounded. A seal runs on its session's own op chain; a wedged chain
+// (a dead libuv pool) never comes back, and no deadline is long enough to wait it out. Losing the race costs a
+// restart break in that session's painted rows (an unsealed stretch cannot be joined), never the whole handoff.
+const HANDOFF_SEAL_TIMEOUT_MS = 1000;
 
 function createHandoff({ hostId, workerPath, controlSocketPath, listSessions, serialize, mirrorStatus, headless, send, log = () => {}, setTimer = setTimeout, spawnSuccessor = spawnSuccessorHost }) {
   let active = null;
@@ -140,6 +156,26 @@ function createHandoff({ hostId, workerPath, controlSocketPath, listSessions, se
     (reply || send)({ type: 'handoff-aborted', handoffId: cur.handoffId, reason });
   }
 
+  // One session's painted-seal, raced against HANDOFF_SEAL_TIMEOUT_MS: resolves when the seal completes (its
+  // timer then cleared) or when the bound expires, in which case the handoff proceeds and the loss is reported.
+  // A rejecting seal still rejects (the begin() catch aborts the handoff, unchanged).
+  function raceSeal(sessionId) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const timer = setTimer(() => {
+        if (settled) return;
+        settled = true;
+        diagnostic(sessionId, 'host-handoff-seal-timeout', { timeoutMs: HANDOFF_SEAL_TIMEOUT_MS, oldHostId: hostId });
+        resolve();
+      }, HANDOFF_SEAL_TIMEOUT_MS);
+      timer?.unref?.();
+      Promise.resolve(headless.handleMessage({ type: 'painted-seal', sessionId })).then(
+        () => { if (settled) return; settled = true; clearTimeout(timer); resolve(); },
+        (err) => { if (settled) return; settled = true; clearTimeout(timer); reject(err); },
+      );
+    });
+  }
+
   async function begin(msg, reply) {
     const handoffId = String(msg.handoffId || '');
     if (active) { reply({ type: 'handoff-aborted', handoffId, reason: 'already-in-progress' }); return; }
@@ -153,11 +189,11 @@ function createHandoff({ hostId, workerPath, controlSocketPath, listSessions, se
         s.ptyProcess.pause();
         cur.paused.push(s);
       }
-      const seeds = new Map();
-      for (const s of cur.paused) {
+      // D-1: every seed is issued concurrently -- each `serialize` keeps its own 2 000 ms cap, so N sessions cost
+      // one cap, not N. The mirrorFeed flush still lands immediately before its own session's serialize.
+      const seeds = new Map(await Promise.all(cur.paused.map(async (s) => {
         s.mirrorFeed?.flush?.({ force: true });
         const snap = await serialize(s.sessionId);
-        seeds.set(s.sessionId, snap);
         // Probe (observe only): what the seed carries vs what the mirror believed at the same instant.
         const seedData = String((snap && snap.data) || '');
         diagnostic(s.sessionId, 'host-handoff-mirror-seed', {
@@ -168,18 +204,16 @@ function createHandoff({ hostId, workerPath, controlSocketPath, listSessions, se
           seedBytes: Buffer.byteLength(seedData),
           oldHostId: hostId,
         });
-      }
+        return [s.sessionId, snap];
+      })));
       if (active !== cur) return; // aborted (deadline) while serializing
       // This host exits without its headless close(): seal each painted-row stretch (with its last screen) and flush the
       // log now, before the successor exists to load it -- an unsealed stretch cannot be joined (a restart break).
-      // Each id is listed BEFORE its seal is queued, so an abort that lands mid-seal still reopens it (the per-session op
-      // queue runs that reopen after the seal).
-      cur.sealed = [];
-      for (const s of cur.paused) {
-        if (active !== cur) return; // aborted (deadline) while sealing
-        cur.sealed.push(s.sessionId);
-        await headless.handleMessage({ type: 'painted-seal', sessionId: s.sessionId });
-      }
+      // D-1: every id is listed BEFORE any seal is queued (so an abort that lands mid-seal still reopens all of them,
+      // the per-session op queue running each reopen after its seal), and every seal is raced against
+      // HANDOFF_SEAL_TIMEOUT_MS, so one wedged op chain cannot hold the handoff past its bound.
+      cur.sealed = cur.paused.map((s) => s.sessionId);
+      await Promise.all(cur.paused.map((s) => raceSeal(s.sessionId)));
       if (active !== cur) return; // aborted (deadline) while sealing
       const running = cur.paused.filter((s) => !s.ptyClosed);
       const entries = running.map((s, i) => {
@@ -190,6 +224,7 @@ function createHandoff({ hostId, workerPath, controlSocketPath, listSessions, se
           ...modelProcessGenerationMetadata(s.modelProcessGeneration),
           ...modelStorageRootsMetadata(s.modelStorageRoots),
           ...modelExecutionRecipeMetadata(s.modelExecutionRecipe),
+          ...launchEnvironmentMetadata(s.launchEnvironment, { manifest: true }),
           // Identity only: the context also carries the runtime render cache (Sets/Maps JSON turns into {}).
           workerDisplayContext: s.workerDisplayContext ? { agentRole: s.workerDisplayContext.agentRole, _workerAgent: s.workerDisplayContext._workerAgent, cwd: s.workerDisplayContext.cwd } : null,
           suppressPtyHeadlessUntilInput: !!s.suppressPtyHeadlessUntilInput,
@@ -306,4 +341,4 @@ function createHandoff({ hostId, workerPath, controlSocketPath, listSessions, se
   return { intercept, restore, resumeRestored, isActive: () => !!active };
 }
 
-module.exports = { handoffManifestFromArgv, writeHandoffManifest, readHandoffManifest, spawnSuccessorHost, createHandoff, validModelProcessGeneration, modelProcessGenerationFromEnv, modelProcessGenerationMetadata, modelStorageRootsFromEnv, modelStorageRootsMetadata };
+module.exports = { HANDOFF_SEAL_TIMEOUT_MS, handoffManifestFromArgv, writeHandoffManifest, readHandoffManifest, spawnSuccessorHost, createHandoff, validModelProcessGeneration, modelProcessGenerationFromEnv, modelProcessGenerationMetadata, modelStorageRootsFromEnv, modelStorageRootsMetadata, PROJECTED_LAUNCH_CONTEXT_KEYS, privateOverridesFromEnv, launchEnvironmentMetadata };