klypix-mcp 1.90.0 → 1.90.1

package/bin/klypix-install.mjs

@@ -212,6 +212,33 @@ function renameSyncWithBackoff(from, to) {
     }
 }
 
+// The live install as its own `.mcp-runtime.json` describes it, every listed
+// file read and hashed now: { raw, entries: [[name, bytes]] }; { absent: true }
+// with no manifest (an install from before the supervisor); { error } when a
+// listed file is missing or differs — a half-applied install, two versions'
+// files side by side. Only the flat layout (bare file names) is accepted.
+function readVerifiedLiveRuntime(dir) {
+    const manifestPath = path.join(dir, '.mcp-runtime.json');
+    let raw;
+    try { raw = fs.readFileSync(manifestPath, 'utf8'); }
+    catch (e) { return e?.code === 'ENOENT' ? { absent: true } : { error: `manifest unreadable (${e?.code || e?.message})` }; }
+    let manifest;
+    try { manifest = JSON.parse(raw); } catch { return { error: 'manifest is not valid JSON' }; }
+    const files = manifest && typeof manifest.files === 'object' && !Array.isArray(manifest.files) ? manifest.files : null;
+    if (manifest?.protocol !== 1 || !files || !Object.prototype.hasOwnProperty.call(files, String(manifest.worker || ''))) {
+        return { error: 'manifest does not hash its worker' };
+    }
+    const entries = [];
+    for (const [name, expected] of Object.entries(files)) {
+        if (path.basename(name) !== name) return { error: `unexpected path ${name}` };
+        let bytes;
+        try { bytes = fs.readFileSync(path.join(dir, name)); } catch { return { error: `${name} is missing` }; }
+        if (crypto.createHash('sha256').update(bytes).digest('hex') !== expected) return { error: `${name} differs from its hash` };
+        entries.push([name, bytes]);
+    }
+    return { raw, entries };
+}
+
 function migrateProjectMcpConfig() {
     try {
         const file = path.join(process.cwd(), '.mcp.json');
@@ -416,10 +443,37 @@ try {
         const s = path.join(BIN, src); if (exists(s)) staged.push({ dst, content: flatten(fs.readFileSync(s, 'utf8')) });
     }
     for (const st of staged) fs.writeFileSync(path.join(BRAIN_DIR, st.dst + '.klypix-new'), st.content);
+    // .prev is what a supervisor boots while an install is half-applied (a
+    // fresh connection, a wake, a crash recovery), so it must be ONE version,
+    // whole (K1-PREV-UNVERIFIED, 2026-10-03 review). It used to be refreshed from
+    // whatever the live directory held: a retry after an install that stopped
+    // mid-rename (the updater's own, 15 min later) copied the MIXED set over the
+    // last complete snapshot. Now the live files are snapshotted only when they
+    // verify against their own manifest — the very bytes that were hashed are
+    // written — and that manifest is copied in LAST: it is what the supervisor
+    // verifies before it boots .prev (prevSnapshotAt). A live directory that
+    // fails its manifest leaves the last complete snapshot where it is.
     try {
-        const prevDir = path.join(BRAIN_DIR, '.prev'); fs.mkdirSync(prevDir, { recursive: true });
-        for (const st of staged) { const live = path.join(BRAIN_DIR, st.dst); if (exists(live)) fs.copyFileSync(live, path.join(prevDir, st.dst)); }
-    } catch { /* .prev rollback snapshot is best-effort */ }
+        const prevDir = path.join(BRAIN_DIR, '.prev');
+        const prevManifest = path.join(prevDir, '.mcp-runtime.json');
+        const live = readVerifiedLiveRuntime(BRAIN_DIR);
+        if (live.entries) {
+            fs.mkdirSync(prevDir, { recursive: true });
+            fs.rmSync(prevManifest, { force: true });   // nothing vouches for .prev while it changes
+            for (const [name, bytes] of live.entries) fs.writeFileSync(path.join(prevDir, name), bytes);
+            fs.writeFileSync(prevManifest + '.klypix-new', live.raw);
+            renameSyncWithBackoff(prevManifest + '.klypix-new', prevManifest);
+        } else if (live.absent) {
+            // No manifest to verify against (an install from before the
+            // supervisor): a plain copy for a manual rollback, which no
+            // supervisor boots — nothing vouches for it.
+            fs.mkdirSync(prevDir, { recursive: true });
+            fs.rmSync(prevManifest, { force: true });
+            for (const st of staged) { const file = path.join(BRAIN_DIR, st.dst); if (exists(file)) fs.copyFileSync(file, path.join(prevDir, st.dst)); }
+        } else {
+            console.log(`• .prev kept: the live core files do not match their manifest (${live.error}) — the last complete snapshot stays the rollback copy`);
+        }
+    } catch { /* .prev rollback snapshot is best-effort; an unfinished one has no manifest */ }
     const renameOrder = staged.slice().sort((a, b) => (a.dst === 'global-brain-hook.mjs' ? 1 : 0) - (b.dst === 'global-brain-hook.mjs' ? 1 : 0));
     let n = 0;
     for (const st of renameOrder) { renameSyncWithBackoff(path.join(BRAIN_DIR, st.dst + '.klypix-new'), path.join(BRAIN_DIR, st.dst)); n++; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.90.0",
+  "version": "1.90.1",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",

package/src/brain-doctor.mjs

@@ -297,9 +297,6 @@ function inspectRunning(brainDir, baked, now, self) {
 const SUPERVISOR_DEAD_RECEIPT_MS = 120 * 1000;
 const SUPERVISOR_TRANSITION_MS = 45 * 1000;
 const WAKING_STATUSES = new Set(['validating-update', 'update-ready', 'recovering', 'recovery-ready']);
-// readRuntimeTarget's failures (mcp-supervisor.mjs): the core files on disk do
-// not verify, so a sleeping pair has nothing consistent to wake into.
-const RUNTIME_INTEGRITY_ERROR = /^(runtime (manifest|worker|file|integrity)\b|unsupported runtime protocol)/;
 const majorOf = (version) => {
   const match = String(version || '').match(/^v?(\d+)\.\d+\.\d+/);
   return match ? Number(match[1]) : null;
@@ -357,18 +354,26 @@ function inspectSupervisors(brainDir, baked, now = Date.now()) {
     // queue. A broken or backpressured host pipe stays what it is.
     const deliveryStatus = transition === 'waking' && !['impaired', 'backpressured'].includes(state.transport?.host)
       ? 'queued' : recordedDelivery;
-    // F6 (2026-10-03 review): a sleeping pair whose last wake found the core
-    // files failing verification (wakeDeferred), or whose poller has reported
-    // them failing for longer than an install takes, answers every request with
-    // an error until they verify. It used to read "wakes on the next request".
+    // F6 (2026-10-03 review): a sleeping pair whose last wake found no
+    // consistent core to boot (wakeDeferred, which the supervisor writes on the
+    // first refused wake) answers every request with an error until the core
+    // files verify. It used to read "wakes on the next request".
+    // Only that refusal counts (K1-DOCTOR-WAKEBLOCKED-FALSE, 2026-10-03 review),
+    // the rule `klypix-mcp runtime` follows (runtime-inspector wakeBlock). An
+    // integrity error the receipt merely carries is not one: the wake resumes
+    // .prev when it holds this pair's version — every pair K1 booted from .prev
+    // records the error in its first receipt and wakes from .prev — or the
+    // package's own worker outside the managed directory. Read as "cannot
+    // wake", every connection that started during a failing install was
+    // printed IMPAIRED while it woke without trouble. The error itself is still
+    // shown on the pair's line.
     const wakeDeferred = intentionallyHibernated && state.hibernation?.wakeDeferred
       && typeof state.hibernation.wakeDeferred === 'object' ? state.hibernation.wakeDeferred : null;
-    // A pair that already served from .prev can resume that same snapshot;
-    // the live directory's integrity error alone does not prove its wake fails.
-    // An actual refused wake still wins over this last-known fallback.
-    const hasPreviousWorker = sleepingTarget?.source === 'rollback';
-    const wakeBlocked = intentionallyHibernated
-      && (Boolean(wakeDeferred) || (!hasPreviousWorker && RUNTIME_INTEGRITY_ERROR.test(String(state.lastError || '')) && !fresh));
+    // Only a wake the supervisor actually refused proves a sleeping pair cannot
+    // wake — the same rule as `klypix-mcp runtime` (wakeBlock). An integrity error
+    // alone does not: the wake waits for the install to settle, and a pair that
+    // served from .prev resumes that snapshot while it still verifies.
+    const wakeBlocked = intentionallyHibernated && Boolean(wakeDeferred);
     const workerImpaired = (!state.active && !intentionallyHibernated && transition !== 'waking'
       && status !== 'starting' && status !== 'awaiting-initialize') || wakeBlocked;
     const deliveryImpaired = deliveryStatus === 'impaired' || state.transport?.host === 'impaired';
@@ -634,6 +639,20 @@ function autoUpdateView({ au, brainDir, supervisors, version, hooks, npmLatest,
   const overdueSuppressed = rule.suppressed === 'no-live-session' ? 'no-live-session'
     : (skew && (rule.overdue || rule.suppressed) ? 'version-skew' : (rule.suppressed || null));
   const overdue = rule.overdue === true && !skew;
+  // TR-1 (2026-10-03 review): a long-due check the rule did NOT judge for want
+  // of a poll (K3) used to print the generic "check due now — runs within
+  // 10 min", hiding how long it had been due and repeating a promise an open
+  // session had visibly not kept. That is the normal state right after this
+  // release: every live connection runs pre-fix supervisor code, which records
+  // no poll, until it reconnects. Keep not judging, but carry what is known:
+  // how long it has been due, the latest poll on record, and how many sessions
+  // record none.
+  const pollers = live.filter((state) => state.autoUpdateEnabled !== false);
+  const pollTimes = pollers.map((state) => timeOf(state.lastPollAt)).filter((ms) => Number.isFinite(ms) && ms <= now + 1000);
+  const latestPollAt = pollTimes.length ? new Date(Math.max(...pollTimes)).toISOString() : null;
+  // Pre-fix supervisor code (no supervisorVersion, B9) never records a poll; a
+  // fixed one records its first 2 s after it starts, so it is not counted here.
+  const unpolledSessions = pollers.filter((state) => state.preFix && !Number.isFinite(timeOf(state.lastPollAt))).length;
 
   const knownLatest = knownNpmLatest(brainDir, au, npmLatest, now);
   // MV-2: a pre-hold updater re-installs whatever the owner rolled back from;
@@ -679,6 +698,11 @@ function autoUpdateView({ au, brainDir, supervisors, version, hooks, npmLatest,
     overdue,
     overdueByMs: overdue ? rule.overdueByMs : null,
     overdueSuppressed,
+    // How long the check has been due by the rule's own reckoning (null when
+    // it was due since before any record), and the polls behind a suppression.
+    dueForMs: Number.isFinite(rule.dueForMs) ? rule.dueForMs : null,
+    latestPollAt,
+    unpolledSessions,
     // What the overdue rule saw: the live sessions that polled after the check
     // fell due, and the latest such poll (K3).
     overdueEvidence: overdue ? rule.evidence || null : null,
@@ -1633,6 +1657,18 @@ export function render(r, opts = {}) {
         parts.push(`next check unknown${au.scheduleError ? ` (${au.scheduleError})` : ''}`);
       } else if (au.overdue) {
         parts.push(`${c.yel}check overdue by ${durationText(au.overdueByMs)} — no running session performed the check${c.rst}`);
+      } else if (au.overdueSuppressed === 'no-poll-evidence' && Number.isFinite(au.dueForMs)) {
+        // TR-1: not judged (K3), but not "due now" either — the rule reports
+        // this only once the check is past its 30 min grace. Say how long, and
+        // why it is not called overdue.
+        const sinceMs = nowMs - au.dueForMs;
+        const polledMs = timeOf(au.latestPollAt);
+        const why = Number.isFinite(polledMs) && polledMs >= sinceMs
+          ? `the latest poll on record (${isoMinute(polledMs)}, ${durationText(nowMs - polledMs)} ago) is too recent, or too close to the due time, to judge it overdue yet`
+          : (au.unpolledSessions
+            ? `overdue is not judged: no open session has recorded a poll since then — ${au.unpolledSessions} connection${au.unpolledSessions === 1 ? '' : 's'} on pre-fix supervisor code record${au.unpolledSessions === 1 ? 's' : ''} none (/mcp reconnect)`
+            : `no open session has polled since then; it runs within ${pollText} while one is open`);
+        parts.push(`check due since ${isoMinute(sinceMs)} (${durationText(au.dueForMs)}) — ${why}`);
       } else if (dueMs <= nowMs) {
         parts.push(`check due now — runs within ${pollText} while any KLYPIX session is open, or 2 s after the next one starts`);
       } else {

package/src/global-brain-hook.mjs

@@ -5474,6 +5474,13 @@ function updateRemedy({ plan, decision, overdue = null, latest, baked, now, spaw
         }
         return { mark: '⚠️', text: `Automatic check overdue (${late}) — run ${installedDoctorHint(baked)}.` };
     }
+    // TR-1 (2026-10-03 review): a check past its grace that the rule did not
+    // judge for want of a poll (K3: every session on pre-fix supervisor code,
+    // or none polled since it fell due) has been due for a while — "(due now)"
+    // hid that. Not judged overdue, so still no alarm.
+    const when = dueAt <= now && overdue && overdue.suppressed === 'no-poll-evidence' && Number.isFinite(overdue.dueForMs)
+        ? `due for ${spanLabel(overdue.dueForMs)}`
+        : etaLabel(dueAt, now);
     // A failed result written by a pre-2026-10-03 updater has no count in its
     // stamp; it is still one failed attempt, never a clean slate.
     const failures = Math.max(
@@ -5486,9 +5493,9 @@ function updateRemedy({ plan, decision, overdue = null, latest, baked, now, spaw
         const why = plan.result === 'failed' && plan.error
             ? String(plan.error).replace(/[`\r\n]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 120)
             : 'it stopped before recording a result';
-        return { mark: '⚠️', text: `KLYPIX will retry automatically — last automatic attempt failed (${why}, attempt ${failures}); next retry ${etaLabel(dueAt, now)}.` };
+        return { mark: '⚠️', text: `KLYPIX will retry automatically — last automatic attempt failed (${why}, attempt ${failures}); next retry ${when}.` };
     }
-    return promise(etaLabel(dueAt, now));
+    return promise(when);
 }
 
 // SessionStart footer — ambient version drift. Reads ONLY local files (zero

package/src/mcp-supervisor.mjs

@@ -61,6 +61,11 @@ const DEFAULT_AUTO_UPDATE_START_DELAY_MS = 2000;
 const RECOVERY_MAX_ATTEMPTS = 5;
 const RECOVERY_BACKOFF_BASE_MS = 1000;
 const RECOVERY_BACKOFF_MAX_MS = 60_000;
+// Hot-swap retry policy (2026-10-03): a candidate that fails TRANSIENTLY while
+// the old worker keeps serving is retried after base × 1, 4, 20 (30 s, 2 min,
+// 10 min by default); only then is it kept rejected until a reconnect.
+const DEFAULT_SWAP_RETRY_BASE_MS = 30_000;
+const SWAP_RETRY_FACTORS = [1, 4, 20];
 // Unbounded queue growth is its own failure mode while a recovery is running.
 const HOST_QUEUE_MAX = 200;
 // A wake that finds the manifest failing integrity is usually racing an install:
@@ -166,17 +171,32 @@ const workerFileVersion = (file) => {
     return pkg?.name === 'klypix-mcp' && typeof pkg.version === 'string' ? pkg.version : null;
   } catch { return null; }
 };
-// The installer's snapshot of a worker file: `.prev/<name>` beside it. Every
-// live file is copied there before the first new one is renamed in, so it is a
-// complete copy of the previous install. Null when there is none, or when its
-// version is not baked in (only the flat bundle bakes it).
-const prevSnapshotTarget = (workerPath) => {
-  const previousPath = path.join(path.dirname(workerPath), '.prev', path.basename(workerPath));
-  if (!fs.existsSync(previousPath)) return null;
-  const version = readBakedVersion(previousPath);
-  if (!version) return null;
-  return { path: previousPath, version, signature: `previous:${previousPath}:${version}`, source: 'rollback', dev: false };
+// The installer's snapshot of the previous install, `.prev/` beside the worker,
+// as a boot target — or null. It is one only while `.prev/.mcp-runtime.json`
+// verifies here and now, byte for byte: the installer snapshots the live
+// directory only when it verifies against its own manifest, and copies that
+// manifest in LAST (bin/klypix-install.mjs). A baked version string used to be
+// the whole check (K1-PREV-UNVERIFIED, 2026-10-03 review), and both installers
+// refreshed .prev from whatever the live directory held — so a retry after a
+// half-applied install filled .prev with two versions' files, and a boot or a
+// wake from it loaded a mixed module graph. A .prev that no manifest vouches for
+// (the desktop installer's, or any installer's before this) is never booted.
+const prevSnapshotAt = (prevDir) => {
+  const manifestPath = path.join(prevDir, '.mcp-runtime.json');
+  const runtime = readRuntimeTarget(manifestPath);
+  if (!runtime.ok) return null;
+  const { path: file, version } = runtime.target;
+  // The worker itself must be among the files the manifest hashes, and carry
+  // the version the manifest names.
+  let hashed = false;
+  try {
+    const files = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))?.files;
+    hashed = isRecord(files) && Object.keys(files).some((relative) => path.resolve(prevDir, relative) === file);
+  } catch { /* unreadable since the verified read: not vouched for */ }
+  if (!hashed || readBakedVersion(file) !== version) return null;
+  return { path: file, version, signature: `previous:${file}:${version}`, source: 'rollback', dev: false };
 };
+const prevSnapshotTarget = (workerPath) => prevSnapshotAt(path.join(path.dirname(workerPath), '.prev'));
 
 function createLineReader(onMessage, onError) {
   let buffered = Buffer.alloc(0);
@@ -334,6 +354,7 @@ function createRuntimeWatch(manifestPath, {
   now = () => Date.now(),
 } = {}) {
   let verified = null;
+  let lastKey = null;
   const statKey = () => {
     try {
       // bigint: NTFS file ids exceed 2^53 and must compare exactly.
@@ -344,6 +365,7 @@ function createRuntimeWatch(manifestPath, {
   return {
     read({ force = false } = {}) {
       const key = statKey();
+      lastKey = key;
       const at = now();
       if (!force && key !== null && verified?.key === key && at >= verified.at && at - verified.at < reverifyMs) {
         return { ok: true, target: verified.target, cached: true };
@@ -352,9 +374,42 @@ function createRuntimeWatch(manifestPath, {
       verified = runtime.ok && key !== null ? { key, at, target: runtime.target } : null;
       return runtime;
     },
+    // The manifest's stat now, and as it was just before the last read: a
+    // commit since that read moves it (settleRuntime).
+    statKey,
+    lastReadKey: () => lastKey,
   };
 }
 
+// Wait for an install to settle (B3 wakes, K1 boots): repeat the read while it
+// fails integrity (or cannot be read) for up to waitMs. Installs commit the
+// manifest LAST, by rename-over, so until its stat moves nothing can have made
+// a failing read verify: the wait polls the stat and re-hashes the runtime
+// only when it moves, plus once at the deadline, before .prev or the fallback
+// is chosen (K1-WAIT-FULL-REHASH, 2026-10-03 review). It used to re-hash every
+// file every 250 ms — ~20 full reads (~8 MiB/s) per waiting connection, the
+// load B8 removed from the poller because it contends with the installer's
+// renames, whose EPERM is what leaves an install half-applied in the first place.
+async function settleRuntime(watch, {
+  initial = watch.read({ force: true }),
+  waitMs = WAKE_INTEGRITY_WAIT_MS,
+  pollMs = WAKE_INTEGRITY_POLL_MS,
+  stopped = () => false,
+} = {}) {
+  let runtime = initial;
+  const deadline = Date.now() + waitMs;
+  // The key taken just before that read: a commit landing during it still moves.
+  let seen = watch.lastReadKey();
+  while (!runtime.ok && !runtime.absent && !stopped() && Date.now() < deadline) {
+    await sleep(pollMs);
+    const key = watch.statKey();
+    if (key === seen && Date.now() < deadline) continue;
+    seen = key;
+    runtime = watch.read({ force: true });
+  }
+  return runtime;
+}
+
 // Is this supervisor receipt provably dead? The boot cleanup deletes on a yes,
 // so every doubt keeps the receipt.
 function deadSupervisorReceipt(state, { now = Date.now(), probe = pidState } = {}) {
@@ -440,6 +495,10 @@ class Supervisor {
     this.pollMs = Number(options.pollMs || process.env.KLYPIX_MCP_SUPERVISOR_POLL_MS || DEFAULT_POLL_MS);
     this.timeoutMs = Number(options.timeoutMs || process.env.KLYPIX_MCP_SUPERVISOR_TIMEOUT_MS || DEFAULT_TIMEOUT_MS);
     this.rollbackGraceMs = Number(options.rollbackGraceMs || process.env.KLYPIX_MCP_ROLLBACK_GRACE_MS || DEFAULT_ROLLBACK_GRACE_MS);
+    this.swapRetryBaseMs = Math.max(1000, Number(options.swapRetryBaseMs || process.env.KLYPIX_MCP_SWAP_RETRY_BASE_MS || DEFAULT_SWAP_RETRY_BASE_MS) || DEFAULT_SWAP_RETRY_BASE_MS);
+    this.swapRetryAttempts = 0;
+    this.swapRetrySignature = null;
+    this.swapRetryTimer = null;
     this.autoUpdate = options.autoUpdate !== false && autoUpdateEnabled();
     this.autoUpdatePollMs = Number(
       options.autoUpdatePollMs
@@ -756,12 +815,11 @@ class Supervisor {
     return target.dev || cmp === null || cmp >= 0;
   }
 
-  // The installer copies every live file to .prev before it renames new ones
-  // in, so .prev is a complete, consistent copy of the PREVIOUS install. It is a
-  // safe place to resume only when that copy is the version this connection
-  // last ran — the version the host's tool list still describes. Any other
-  // version would be a swap no gate has seen; crash recovery used to boot
-  // whatever .prev held.
+  // A .prev whose manifest verifies (prevSnapshotAt) is a complete, consistent
+  // copy of ONE previous install. It is a safe place to resume only when that
+  // copy is the version this connection last ran — the version the host's tool
+  // list still describes. Any other version would be a swap no gate has seen;
+  // crash recovery used to boot whatever .prev held.
   previousBaselineTarget(anchor) {
     if (!anchor?.path || anchor.source === 'rollback') return null;
     const previous = prevSnapshotTarget(anchor.path);
@@ -770,6 +828,16 @@ class Supervisor {
     return previous;
   }
 
+  // A pair that already runs from .prev resumes that same snapshot — while it
+  // still verifies and still holds this connection's version. An install
+  // rewrites .prev, and a pre-fix installer could rewrite it with a mixed set.
+  resumableRollback(anchor) {
+    const snapshot = anchor?.path ? prevSnapshotAt(path.dirname(anchor.path)) : null;
+    const baseVersion = this.baselineVersion();
+    if (!snapshot || !baseVersion || snapshot.version !== String(baseVersion)) return null;
+    return path.resolve(snapshot.path) === path.resolve(anchor.path) ? snapshot : null;
+  }
+
   // The package's own worker as it is on disk NOW. fallbackTarget carries the
   // version this supervisor started with, but an install (flat bundle) or an
   // npx cache refresh (direct-package launch) can replace the file since, and a
@@ -888,14 +956,10 @@ class Supervisor {
 
   // A full read of the manifest, repeated while it fails integrity (or cannot be
   // read) for up to WAKE_INTEGRITY_WAIT_MS: an install renames its files one at
-  // a time and commits the manifest last. Wakes (B3) and boots (K1) wait alike.
+  // a time and commits the manifest last. Wakes (B3) and boots (K1) wait alike;
+  // settleRuntime re-hashes only when the manifest moves.
   async settledRuntime(runtime = this.runtimeWatch.read({ force: true })) {
-    const deadline = Date.now() + WAKE_INTEGRITY_WAIT_MS;
-    while (!runtime.ok && !runtime.absent && !this.closed && Date.now() < deadline) {
-      await sleep(WAKE_INTEGRITY_POLL_MS);
-      runtime = this.runtimeWatch.read({ force: true });
-    }
-    return runtime;
+    return settleRuntime(this.runtimeWatch, { initial: runtime, stopped: () => this.closed });
   }
 
   // B3 (2026-10-03): the wake re-reads the manifest instead of trusting the
@@ -951,9 +1015,9 @@ class Supervisor {
     // sleeping target's path inside the managed directory — resume .prev when it
     // holds this connection's version...
     // A pair that already resumed from .prev resumes that same copy — while it
-    // still holds this connection's version (a new install overwrites .prev).
+    // still verifies and holds this connection's version (resumableRollback).
     const previous = anchor?.source === 'rollback'
-      ? (fs.existsSync(anchor.path) && readBakedVersion(anchor.path) === String(this.baselineVersion()) ? anchor : null)
+      ? this.resumableRollback(anchor)
       : this.previousBaselineTarget(anchor);
     if (previous) {
       log(`runtime still fails integrity after ${WAKE_INTEGRITY_WAIT_MS} ms (${runtime.error}) — waking v${previous.version} from .prev`);
@@ -1043,9 +1107,10 @@ class Supervisor {
   // is <brainDir>/klypix-mcp-worker.mjs — inside the directory being renamed —
   // and booting it at once could load a mixed module graph (a new worker beside
   // an old engine, or the reverse). So the boot waits for the install to settle,
-  // as a wake does (B3), and then tries the previous worker snapshot. Without
-  // one it refuses the connection instead of loading the known-unverified live
-  // files. A direct-package launch
+  // as a wake does (B3), and then boots .prev's complete pre-install copy — one
+  // whose own manifest verifies (prevSnapshotAt). Without one it refuses the
+  // connection instead of loading the known-unverified live files; the
+  // integrity error is recorded either way. A direct-package launch
   // keeps its worker outside the managed directory, which no install touches: it
   // boots at once. The host's first requests queue meanwhile (run()).
   async selectInitialTarget() {
@@ -1064,7 +1129,7 @@ class Supervisor {
           log(`runtime still fails integrity after ${WAKE_INTEGRITY_WAIT_MS} ms (${runtime.error}) — starting v${previous.version} from .prev, the complete copy of the previous install`);
           return previous;
         }
-        throw new Error(`KLYPIX core files do not verify (${runtime.error}) and no previous worker is available — no worker was started; retry after the install finishes, then /mcp reconnect`);
+        throw new Error(`KLYPIX core files do not verify (${runtime.error}) and no previous worker whose own manifest verifies is available — no worker was started; retry after the install finishes, then /mcp reconnect`);
       }
     }
     if (!runtime.ok) return this.fallbackTarget;
@@ -1532,6 +1597,37 @@ class Supervisor {
     }
   }
 
+  // A hot-swap that failed while the old worker still serves. A deterministic
+  // rejection (new major, breaking tools) stays rejected until a new install or a
+  // reconnect. A TRANSIENT one — an initialize timeout under load, a spawn error,
+  // an exit before activation — used to pin the connection to its old version
+  // just the same (field, 2026-10-03: one 15 s initialize timeout during a
+  // test-heavy hour left a Codex pair on v1.88.0 beside a v1.89.0 install until it
+  // reconnected). It now retries the same target on the swap backoff while the
+  // old worker keeps serving; the signature stays rejected meanwhile so the 1 s
+  // poller cannot restart it early, and the timer lifts it.
+  scheduleSwapRetry(candidate, reason) {
+    const signature = candidate.target.signature;
+    if (this.swapRetrySignature !== signature) {
+      this.swapRetrySignature = signature;
+      this.swapRetryAttempts = 0;
+    }
+    if (this.swapRetryAttempts >= SWAP_RETRY_FACTORS.length) return false;
+    const delay = this.swapRetryBaseMs * SWAP_RETRY_FACTORS[this.swapRetryAttempts++];
+    const rejectedVersion = candidate.version || candidate.target.version;
+    this.rejectedSignature = signature;
+    this.status = 'ready';
+    if (this.swapRetryTimer) clearTimeout(this.swapRetryTimer);
+    this.swapRetryTimer = setTimeout(() => {
+      this.swapRetryTimer = null;
+      if (!this.closed && this.rejectedSignature === signature) this.rejectedSignature = null;
+    }, delay);
+    this.swapRetryTimer.unref?.();
+    this.writeState({ rejectedVersion, swapRetry: { attempt: this.swapRetryAttempts, of: SWAP_RETRY_FACTORS.length, inMs: delay } });
+    log(`kept v${this.active?.version || 'none'}; v${rejectedVersion} failed transiently (${reason}) — retrying in ${Math.round(delay / 1000)} s (${this.swapRetryAttempts}/${SWAP_RETRY_FACTORS.length})`);
+    return true;
+  }
+
   rejectCandidate(reason, terminate = true, { deterministic = false } = {}) {
     const candidate = this.candidate;
     if (!candidate) return;
@@ -1542,6 +1638,7 @@ class Supervisor {
       this.rejectWhileIdle(candidate, reason);
       return;
     }
+    if (this.active && !deterministic && this.scheduleSwapRetry(candidate, reason)) return;
     this.status = this.active ? 'restart-required' : 'recovery-failed';
     if (!this.active) {
       // RECOVERY rejection: transient spawn failures (0xC0000142-class) must
@@ -1646,6 +1743,9 @@ class Supervisor {
     this.rejectedSignature = rejection ? rejection.signature : null;
     this.recoveryAttempts = 0;   // a committed worker resets the retry budget
     if (this.recoveryTimer) { clearTimeout(this.recoveryTimer); this.recoveryTimer = null; }
+    this.swapRetryAttempts = 0;   // and the hot-swap retry budget
+    this.swapRetrySignature = null;
+    if (this.swapRetryTimer) { clearTimeout(this.swapRetryTimer); this.swapRetryTimer = null; }
     this.status = rejection ? 'restart-required' : 'ready';
     this.lastError = rejection ? rejection.reason : null;
     this.runtimeError = null;
@@ -1941,6 +2041,7 @@ class Supervisor {
     clearTimeout(this.autoUpdateStarter);
     clearInterval(this.autoUpdatePoller);
     if (this.recoveryTimer) { clearTimeout(this.recoveryTimer); this.recoveryTimer = null; }
+    if (this.swapRetryTimer) { clearTimeout(this.swapRetryTimer); this.swapRetryTimer = null; }
     // Real shutdown grace: stdin EOF lets the worker run its own presence
     // cleanup (stopRuntimePresence/removeSession). An instant SIGTERM is
     // TerminateProcess on Windows — the cleanup never runs and every normally
@@ -1967,6 +2068,8 @@ export const __test = {
   compareSemver,
   atomicJson,
   createRuntimeWatch,
+  settleRuntime,
+  prevSnapshotTarget,
   cleanSupervisorStateDir,
   deadSupervisorReceipt,
   pidState,