create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/lib/oauth-proxy-supervisor.js

@@ -25,11 +25,26 @@ const crypto = require('node:crypto');
 const { spawn } = require('node:child_process');
 const { resolveRealNode } = require('./real-node');
 const { getDataDir } = require('./data-dir');
+const { readExitRecord, clearExitRecord } = require('./model-proxy/stream-accounting');
+const instanceRecord = require('./model-proxy/proxy-instance-record');
+const { hostRuntimeCompatibilityDecision } = require('./host-runtime-compatibility');
+const { hashClosureFiles } = require('./host-closure-hash');
+const { HANDOFF_READY_DEADLINE_MS } = require('./model-proxy/handoff');
 const walleClient = require('./walle-client');
 
 const PROXY_SCRIPT = path.resolve(__dirname, '..', 'oauth-proxy.js');
 const DEFAULT_PORT = parseInt(process.env.OAUTH_PROXY_PORT || '3459', 10);
 const ADMIN_HEADER = 'X-CTM-Proxy-Admin';
+// §5 D-3/§6: the proxy's own identity protocol and floor. A proxy that reports a different floor is not
+// adoptable at all (hostRuntimeCompatibilityDecision), which is what makes a WP-2 successor safe to run
+// beside its predecessor.
+const PROXY_PROTOCOL = instanceRecord.PROXY_PROTOCOL;
+const PROXY_FLOOR_VERSION = instanceRecord.PROXY_FLOOR_VERSION;
+// hostRuntimeCompatibilityDecision() compares protocol VERSIONS numerically (its canonical caller passes
+// host-registry's integer protocol), while /_health reports the wire NAME. The name is mapped to the
+// version it names here, so an identical proxy answers 'compatible' rather than the 'upgrade-pending' a
+// NaN-to-NaN comparison would produce for every restart -- which would schedule a handoff each time.
+const PROXY_PROTOCOL_VERSION = 1;
 const SAFE_LEAD_OWNER_ID = /^[A-Za-z0-9][A-Za-z0-9._:@/+\-]{0,255}$/;
 const SAFE_LEAD_DEPLOYMENT_ID = /^[@A-Za-z0-9][A-Za-z0-9._:/@+-]{0,159}$/;
 // WP-0A (claude-native-auth-mtls-and-routed-subagents-2026-10-15 §6.2, D-2/D-7): the immutable
@@ -74,6 +89,21 @@ const _pendingLeadRevokes = new Set();
 // tokens. A tight crash loop must not become a spawn storm.
 const LEAD_RESTART_MIN_INTERVAL_MS = 10_000;
 let _lastLeadAutoRestartAt = 0;
+// §5 D-6: how often CTM asks whether the ADOPTED proxy is still there. It is
+// LEAD_RESTART_MIN_INTERVAL_MS by value ON PURPOSE: a probe that found a death
+// faster than the restart rate limit could only be answered by the suppression
+// line below, so probing faster would buy nothing but wakeups.
+const PROXY_LIVENESS_MS = 10_000;
+// The signal name a probe-found death carries into _onProxyGone(). It is not a
+// real signal: it is what makes an adopted death "unexpected" to the ONE
+// recovery branch below, exactly as a SIGKILL of a spawned child is.
+const ADOPTED_PID_GONE = 'ADOPTED_PID_GONE';
+// The armed probe, or null. Module memory only: it is a live timer, and it is
+// dropped on stop()/_resetForTest() and whenever the mode leaves 'adopted'.
+let _livenessTimer = null;
+// §6 test seam: the cadence a test can shrink, so AC-3a's 10 s bound is not a
+// 10 s test. Production never writes it.
+let _livenessProbeMs = PROXY_LIVENESS_MS;
 // Set by stop() right before it kills the child, cleared by the child's 'exit'
 // handler. A graceful stop must never trigger the lead-token auto-restart.
 let _stopping = false;
@@ -97,22 +127,141 @@ let _adminSecret = null;
 // child's environment, and a request for a DIFFERENT directory while a child is running is refused
 // rather than silently retargeted by an implicit restart.
 let _activeChildDataDir = null;
+// §5 D-10/§9 S-12: the last-exit record read by the most recent start(), or null when the previous exit
+// left none. Module memory only, and consumed by lastRestartOutcome() for the restore_complete row.
+let _lastExitRecord = null;
+// The in-flight read+clear of that record; a test awaits it before asserting lastRestartOutcome().
+let _exitRecordLoad = Promise.resolve();
+
+// §5 D-4: which identity this module is holding. 'child' = a proxy THIS CTM spawned (the only mode that
+// owns a process handle); 'adopting'/'adopted' = a surviving proxy found through its instance record,
+// which CTM did not spawn and therefore only ever signals by ps-verified pid; 'stopped' = nothing.
+let _mode = 'stopped';
+let _adopted = null;
+// The in-flight adoption decision (record → ps → /_health → secret → compatibility). waitForHealth()
+// awaits it, because every caller already follows start() with waitForHealth().
+let _adoptionPromise = null;
+// Adoption attempt sequence: stop() and a newer start() bump it, so a probe that lands afterwards cannot
+// adopt a proxy CTM has already given up on (or spawn a second child beside a fresh one).
+let _adoptionSeq = 0;
+
+function _ownedPid() {
+  if (_mode === 'child') return _child ? _child.pid : null;
+  return _adopted ? _adopted.pid : null;
+}
 
 function _ensureShutdownHook() {
   if (_shutdownRegistered) return;
   _shutdownRegistered = true;
+  // §5 D-5 (+ hosts' D-A6): a CTM exit or SIGTERM is a RECONNECT for the proxy, never a stop -- the
+  // surviving proxy is adopted by the next CTM (§5 D-4), so its in-flight streams are never cut. SIGINT
+  // is the one verb an operator expects to stop everything: it reaches a foreground `node server.js`,
+  // and the primary under launchd never receives one. stop() knows both identities (a child this CTM
+  // spawned, or a survivor it adopted) and also reaps the record and secret, so Ctrl-C leaves nothing
+  // for the next boot to adopt.
   const stopOnExit = () => {
-    if (_child && !_child.killed) {
-      try { _child.kill('SIGTERM'); } catch {}
-    }
+    try { stop(); } catch { /* expected: the process is exiting; a failed signal changes nothing */ }
   };
-  process.on('exit', stopOnExit);
   process.on('SIGINT', stopOnExit);
-  process.on('SIGTERM', stopOnExit);
 }
 
 function isRunning() {
-  return !!(_child && !_child.killed && _child.exitCode === null);
+  if (_mode === 'child') return !!(_child && !_child.killed && _child.exitCode === null);
+  return _mode === 'adopted' || _mode === 'adopting';
+}
+
+// ── §5 D-6: liveness in adopted mode ─────────────────────────────────────
+// A proxy THIS CTM spawned reports its own death: the child handle has an 'exit' event. An ADOPTED proxy
+// has no handle -- it is somebody else's process that outlived the CTM that started it -- so nothing but
+// CTM's own probe can notice the pid going away. That is the whole of D-6: one timer, the same
+// _onProxyGone() handler, and the same one rate-limited restart on the other side of it.
+
+function _clearLivenessProbe() {
+  if (_livenessTimer) clearTimeout(_livenessTimer);
+  _livenessTimer = null;
+}
+
+/** §6 test seam: shrink the probe cadence. Pass null (or anything not a positive integer) to restore. */
+function _setLivenessProbeMsForTest(ms) {
+  _livenessProbeMs = Number.isSafeInteger(ms) && ms > 0 ? ms : PROXY_LIVENESS_MS;
+}
+
+/**
+ * §5 D-6: arm the ONE probe for the proxy currently adopted. Re-arming replaces the timer, so a call
+ * after a WP-2 handoff watches the SUCCESSOR's pid and not the predecessor's.
+ */
+function _armLivenessProbe({ port, dataDir }) {
+  _clearLivenessProbe();
+  if (_mode !== 'adopted' || !_adopted) return;
+  _livenessTimer = setTimeout(() => {
+    _livenessTimer = null;
+    // Re-checked at fire time: a stop() or a newer adoption in between owns the state now.
+    if (_mode !== 'adopted' || !_adopted) return;
+    const pid = _adopted.pid;
+    if (instanceRecord.isProcessAlive(pid)) {
+      _armLivenessProbe({ port, dataDir });
+      return;
+    }
+    _onProxyGone({ code: null, signal: ADOPTED_PID_GONE, port, dataDir });
+  }, _livenessProbeMs);
+  // §5 D-6: a probe is never a reason for CTM to stay alive.
+  _livenessTimer.unref();
+}
+
+/**
+ * §5 D-6: an admin call that cannot reach an ADOPTED proxy is the cheapest probe there is -- run the same
+ * test the timer runs, so a dead proxy is noticed now instead of on the next tick. Only the two codes that
+ * mean "the process is not serving" count; a timeout is not evidence of death.
+ */
+function _probeAdoptedAfterAdminFailure({ port, err }) {
+  const code = (err && err.cause && err.cause.code) || (err && err.code);
+  if (code !== 'ECONNREFUSED' && code !== 'ECONNRESET') return;
+  if (_mode !== 'adopted' || !_adopted) return;
+  // Without the directory the record on disk belongs to, the recovery below cannot reap it and a restart
+  // would target the wrong root -- so the probe stays silent rather than acting on a guess.
+  if (!_activeChildDataDir) return;
+  if (instanceRecord.isProcessAlive(_adopted.pid)) return;
+  _onProxyGone({ code: null, signal: ADOPTED_PID_GONE, port, dataDir: _activeChildDataDir });
+}
+
+/**
+ * §5 D-10 / §9 S-12: the proxy's own restart outcome, as the restore_complete ledger row reports it
+ * (`adoption.proxy`). Exactly eight keys, so lib/restart-ledger.js's boundedRecordDetail keeps it whole.
+ * `action` is 'spawn' for the fresh child start() created and 'adopt' for the surviving proxy it took
+ * over; the previous-exit fields come from the record that spawn consumed and are null when the previous
+ * exit left none -- an ADOPTED proxy never exited, so a stale exit record must not be reported as this
+ * restart's cut (WP-1 §5 D-5).
+ */
+function lastRestartOutcome() {
+  // Only a DECIDED adoption is reported as one; while the decision is in flight the fallback may still
+  // be a spawn, and the restore_complete row must not name an outcome that has not happened yet.
+  if (_adopted && _mode === 'adopted') {
+    return {
+      // §5 D-7 (WP-2): an adoption that also performed a handoff is reported as one, with the measured
+      // handoff time and the SUCCESSOR's pid/generation (a handoff always bumps the generation).
+      // `drainForcedCuts` stays null at restore time on purpose: the predecessor's drain finishes later,
+      // in its own process, and its count is only in the old proxy's log line.
+      action: _adopted.handoffMs == null ? 'adopt' : 'handoff',
+      pid: _adopted.pid,
+      generation: _adopted.generation,
+      openStreamsAtExit: null,
+      handoffMs: _adopted.handoffMs == null ? null : _adopted.handoffMs,
+      drainForcedCuts: null,
+      previousPid: null,
+      previousExitAt: null,
+    };
+  }
+  const record = _lastExitRecord;
+  return {
+    action: 'spawn',
+    pid: isRunning() ? _ownedPid() : null,
+    generation: 1,
+    openStreamsAtExit: record ? record.openStreams : null,
+    handoffMs: null,
+    drainForcedCuts: null,
+    previousPid: record ? record.pid : null,
+    previousExitAt: record ? record.at : null,
+  };
 }
 
 function start({ port = DEFAULT_PORT, dataDir } = {}) {
@@ -122,12 +271,155 @@ function start({ port = DEFAULT_PORT, dataDir } = {}) {
     if (_activeChildDataDir && _activeChildDataDir !== resolvedDataDir) {
       // No implicit restart: the running child owns its directory (and any mounted authority, tokens and
       // worker budgets that came with it). The caller must stop it explicitly.
-      return { ok: false, running: true, port, pid: _child.pid, reason: 'data_dir_mismatch' };
+      return { ok: false, running: true, port, pid: _ownedPid(), reason: 'data_dir_mismatch' };
     }
-    return { ok: true, running: true, port, pid: _child.pid, alreadyRunning: true };
+    return { ok: true, running: true, port, pid: _ownedPid(), alreadyRunning: true };
   }
   _ensureShutdownHook();
   _lastError = null;
+  // §5 D-4 (+ D-11, D-12): ADOPT BEFORE SPAWN, on the boot path and on the crash-recovery path alike. A
+  // record that names a live, ps-verified proxy on THIS port and in THIS data directory is the previous
+  // process answering; it is taken over instead of being replaced (and its in-flight streams are never
+  // cut). Anything else -- a dead pid, another port, a foreign process that reused the pid -- is stale
+  // truth and is removed before the fresh spawn below. The decision itself is synchronous because six
+  // callers and the boot log read start()'s return value; only the HTTP half is asynchronous.
+  const record = instanceRecord.readInstanceRecord({ dataDir: resolvedDataDir });
+  if (record && record.port === port && instanceRecord.isProxyProcess(record.pid)) {
+    _mode = 'adopting';
+    _adopted = { pid: record.pid, generation: record.generation, closureHash: null, decision: null };
+    _adminSecret = null;
+    _activeChildDataDir = resolvedDataDir;
+    _stopping = false;
+    const seq = (_adoptionSeq += 1);
+    _adoptionPromise = _finishAdoption({ port, dataDir: resolvedDataDir, record, seq });
+    return { ok: true, running: true, port, pid: record.pid, mode: 'adopting' };
+  }
+  if (record) instanceRecord.unlinkInstanceRecord({ dataDir: resolvedDataDir });
+  return _spawnFresh({ port, resolvedDataDir });
+}
+
+/**
+ * §5 D-4: the asynchronous half of an adoption -- the secret read, the two loopback probes and the
+ * compatibility verdict. On success the proxy keeps running under this CTM; on any failure the record is
+ * reaped and the caller's start() falls through to a fresh spawn, so the next isRunning()/waitForHealth()
+ * sees a child. WP-1 adopts an `upgrade-pending` proxy and leaves it running: the handoff that would
+ * replace it is WP-2.
+ */
+async function _finishAdoption({ port, dataDir, record, seq }) {
+  try {
+    const secret = instanceRecord.readAdminSecret({ dataDir });
+    const health = secret ? await _probeHealth(port) : null;
+    const authed = secret ? await _probeAdminSecret({ port, secret }) : false;
+    const decision = health && authed && health.pid === record.pid
+      ? hostRuntimeCompatibilityDecision({
+        expectedProtocol: PROXY_PROTOCOL_VERSION,
+        actualProtocol: health.protocol === PROXY_PROTOCOL ? PROXY_PROTOCOL_VERSION : 0,
+        expectedFloor: PROXY_FLOOR_VERSION,
+        actualFloor: health.floor_version,
+        diskClosureHash: _hashClosureFiles(health.closure_files),
+        hostClosureHash: health.closure_hash,
+      })
+      : { compatible: false, reason: secret ? 'proxy_not_answering' : 'admin_secret_missing' };
+    if (seq !== _adoptionSeq) return; // a stop() or a newer start() superseded this attempt
+    if (decision.compatible) {
+      _mode = 'adopted';
+      _adopted = { pid: record.pid, generation: record.generation, closureHash: health.closure_hash, decision: decision.reason };
+      _adminSecret = secret;
+      _activeChildDataDir = dataDir;
+      // §5 D-5: the previous proxy did not exit, so there is no previous exit to report -- and a
+      // last-exit.json left behind by some earlier stop must not be attributed to this restart.
+      _lastExitRecord = null;
+      _exitRecordLoad = Promise.resolve();
+      // D-4 step 7: replay into the adopted proxy exactly as the fresh-spawn path does; the token
+      // registry and the pick table live in CTM, the adopted proxy's own table survived with it.
+      await _replayLeadTokens({ port });
+      process.stderr.write(`[oauth-proxy-supervisor] adopted proxy pid=${record.pid} generation=${record.generation} decision=${decision.reason}\n`);
+      // §5 D-7 (WP-2): `upgrade-pending` means the proxy answering on the wire is not the code on disk,
+      // so it is asked ONCE to hand its listening sockets and its memory-only state to a successor it
+      // spawns from that disk. Adopting first (above) is what makes a refusal harmless: the adopted
+      // proxy keeps serving, and the next restart asks again.
+      if (decision.reason === 'upgrade-pending') await _performUpgradeHandoff({ port });
+      // §5 D-6, LAST: after the handoff above, `_adopted.pid` is the SUCCESSOR's, which is the process
+      // that will be answering from here on. Nothing before this point may probe -- the adoption is not
+      // decided yet (and _pollHealth, never waitForHealth, is what the steps above may await).
+      _armLivenessProbe({ port, dataDir });
+      return;
+    }
+    // Rejected: reap the record. The pid is signalled ONLY when ps proved it is this proxy -- a language
+    // runtime is free to hand a dead proxy's pid to an unrelated process, and that process is not ours.
+    process.stderr.write(`[oauth-proxy-supervisor] proxy record rejected: ${decision.reason}\n`);
+    instanceRecord.unlinkInstanceRecord({ dataDir });
+    try { process.kill(record.pid, 'SIGTERM'); } catch { /* expected: the pid may be gone; the record is already reaped */ }
+  } catch (err) {
+    // REPORT: an adoption that throws is refused like any other; the spawn below is the fallback.
+    process.stderr.write(`[oauth-proxy-supervisor] adoption failed: ${String(err && err.message || err).slice(0, 200)}\n`);
+    instanceRecord.unlinkInstanceRecord({ dataDir });
+  }
+  if (seq !== _adoptionSeq) return;
+  _mode = 'stopped';
+  _adopted = null;
+  _adminSecret = null;
+  _activeChildDataDir = null;
+  _adoptionPromise = null;
+  _spawnFresh({ port, resolvedDataDir: dataDir });
+}
+
+/**
+ * §5 D-7 (WP-2, AC-2f): the ONE handoff a `upgrade-pending` adoption schedules. On 202 the module
+ * switches to the successor's identity and replays CTM's lead registry and pick table into it exactly as
+ * the fresh-spawn path does (idempotent: the rows that survived with the predecessor are re-registered
+ * verbatim). A refusal or a throw is REPORTED and the adopted proxy is kept -- it still serves, and there
+ * is nothing here worth failing a boot over.
+ */
+async function _performUpgradeHandoff({ port }) {
+  let handed = null;
+  try {
+    handed = await requestHandoff({ port, reason: 'upgrade-pending' });
+  } catch (err) {
+    // REPORT: the old proxy is still serving; the next restart asks again.
+    process.stderr.write(`[oauth-proxy-supervisor] proxy handoff refused: ${String((err && err.reason) || (err && err.message) || err).slice(0, 200)}\n`);
+    return;
+  }
+  // The successor loaded the code on disk, so the predecessor's closure hash is no longer this adoption's
+  // identity: status() and the restore_complete row must describe the process now answering. (WP-4 live
+  // proof, 2026-10-23: status reported the predecessor's hash after a handoff while /_health had the new one.)
+  const successorHealth = await _probeHealth(port);
+  _adopted = {
+    ..._adopted,
+    pid: handed.successorPid,
+    generation: handed.generation,
+    handoffMs: handed.handoffMs,
+    decision: 'upgrade-pending',
+    closureHash: successorHealth && successorHealth.pid === handed.successorPid ? (successorHealth.closure_hash || null) : null,
+  };
+  // The successor starts with the token table the predecessor handed over PLUS whatever CTM replays; the
+  // replay is the same idempotent call the fresh-spawn path makes, so a token cannot be double-registered.
+  // Its ROUTE and PICK tables, though, start EMPTY (§1.5 rows 4-5: both are CTM's, and the handoff
+  // carries only the state that has no other authority), so `successor:true` pushes them even when CTM
+  // holds no lead token at all -- the carried-over tokens would otherwise 404 on `unknown route alias`
+  // until the next provider save happened to re-push.
+  await _replayLeadTokens({ port, successor: true });
+  process.stderr.write(`[oauth-proxy-supervisor] proxy handoff generation=${handed.generation} successorPid=${handed.successorPid} handoffMs=${handed.handoffMs}\n`);
+}
+
+function _spawnFresh({ port, resolvedDataDir }) {
+  _mode = 'child';
+  _adopted = null;
+  _adoptionPromise = null;
+  // §5 D-6: the mode is leaving 'adopted', and a spawned child reports its own death.
+  _clearLivenessProbe();
+  // §5 D-10 / §9 S-12: what the PREVIOUS proxy was still carrying when it stopped. Read once, here,
+  // immediately before a fresh spawn, and cleared so one exit is reported once. The outcome this module
+  // reports afterwards always describes THIS spawn. The read is async (start() stays synchronous);
+  // lastRestartOutcome() answers null for the previous-exit fields until it lands, which is well before
+  // the restore_complete row that reads them.
+  _lastExitRecord = null;
+  _exitRecordLoad = readExitRecord({ dataDir: resolvedDataDir })
+    .then((record) => { _lastExitRecord = record; return clearExitRecord({ dataDir: resolvedDataDir }); })
+    .catch((err) => {
+      // REPORT: an unreadable record costs the ledger one field, never the boot.
+      process.stderr.write(`[oauth-proxy-supervisor] exit record unreadable: ${String(err && err.code || err).slice(0, 80)}\n`);
+    });
   // A superseded child may exit late with _stopping still set; this spawn is not a stop, so the
   // stale flag can never opt a future crash out of the lead auto-restart.
   _stopping = false;
@@ -147,73 +439,54 @@ function start({ port = DEFAULT_PORT, dataDir } = {}) {
   // stdin (never env/argv — oauth-proxy.js:_readAdminSecretFromStdin() is the
   // only reader). Kept in module memory for the admin-channel calls below.
   _adminSecret = crypto.randomBytes(32).toString('hex');
+  // §5 D-2: the secret is on disk BEFORE the child exists. A CTM that dies between this spawn and its
+  // own exit leaves no adopter behind, but the NEXT boot finds a readable secret and can take the
+  // survivor over; the child is handed the very same value on stdin.
+  instanceRecord.writeAdminSecret({ dataDir: resolvedDataDir, secret: _adminSecret });
+  // §5 D-1: the child's stdout/stderr ARE the log file (rotated once per generation inside
+  // openProxyLogFd). No pipe to relay and nothing for an orphaned child to write into -- a write to a
+  // dead parent's pipe is what killed the previous shape with EPIPE.
+  const logFd = instanceRecord.openProxyLogFd(resolvedDataDir);
   try {
     _child = spawn(resolveRealNode(), [PROXY_SCRIPT], {
-      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: true,
+      stdio: ['pipe', logFd, logFd],
       env: childEnv,
-      detached: false,
     });
   } catch (err) {
+    instanceRecord.closeProxyLogFd(logFd);
     _lastError = err.message;
     _adminSecret = null;
+    _mode = 'stopped';
     return { ok: false, running: false, error: err.message };
   }
+  instanceRecord.closeProxyLogFd(logFd); // the child holds its own copy of the descriptor
+  // §5 D-1: CTM is never held open by the proxy it spawned -- the proxy outlives this process and the
+  // next CTM adopts it (D-4), so nothing here may wait on its exit.
+  _child.unref();
   // D-13: capture THIS spawn so a superseded child's late 'exit' (stop() -> start(), or a rapid
   // restart) cannot null the current child's handle / admin secret out from under a fresh boot.
   const child = _child;
+  // S-5: the secret travels on stdin, never env/argv -- oauth-proxy.js:_readAdminSecretFromStdin() is
+  // the only reader, and the child starts as soon as that line ends.
   try {
     _child.stdin.write(_adminSecret + '\n');
     _child.stdin.end();
   } catch (err) {
-    // expected: the child may exit before stdin flushes on a fast startup
-    // failure — the health probe below is the authoritative signal, not this
-    // write.
+    // expected: the child may exit before stdin flushes on a fast startup failure -- the health probe
+    // below is the authoritative signal, not this write.
     _lastError = `admin secret handoff failed: ${err.message}`;
   }
   _startedAt = Date.now();
-  _child.stdout.on('data', (d) => {
-    // Forward to CTM stderr so it lands in the same log files. Prefix to
-    // disambiguate.
-    process.stderr.write('[oauth-proxy] ' + d.toString());
-  });
-  _child.stderr.on('data', (d) => {
-    process.stderr.write('[oauth-proxy] ' + d.toString());
-  });
-  _child.on('error', (err) => {
+  child.on('error', (err) => {
     _lastError = err.message;
   });
-  _child.on('exit', (code, signal) => {
+  child.on('exit', (code, signal) => {
     // D-13: a superseded child (stop() -> start(), or a rapid restart) can exit LATE, after a newer
     // child is live. Its exit owns none of the module state below -- nulling the current child's
     // handle or admin secret would tear the live proxy's admin channel down.
     if (child !== _child) return;
-    if (code !== 0 && !signal) {
-      _lastError = `exited code=${code}`;
-    }
-    _child = null;
-    _startedAt = null;
-    _adminSecret = null;
-    _activeChildDataDir = null;
-    // The dead child's in-memory token table is gone; any revoke that was still
-    // pending against it no longer has anything to reap.
-    _pendingLeadRevokes.clear();
-    // WP-0 (§6.2): an unexpected exit (signal, or a non-zero code) with live
-    // lead tokens must bring the proxy back so those tokens keep working. A
-    // graceful stop() opts out via _stopping; a crash-loop is rate-limited.
-    const unexpected = !!signal || code !== 0;
-    const wasStopping = _stopping;
-    _stopping = false;
-    if (unexpected && !wasStopping && _leadTokens.size > 0) {
-      if (Date.now() - _lastLeadAutoRestartAt >= LEAD_RESTART_MIN_INTERVAL_MS) {
-        _lastLeadAutoRestartAt = Date.now();
-        // WP-1 §5 D-3: the restart is bound to the directory the DEAD child was actually running with,
-        // captured here rather than re-resolved from a possibly-changed environment. A restart therefore
-        // cannot silently move the authority root out from under a surviving native owner.
-        start({ port, dataDir: resolvedDataDir });
-      } else {
-        process.stderr.write('[oauth-proxy-supervisor] model-proxy-restart-suppressed\n');
-      }
-    }
+    _onProxyGone({ code, signal, port, dataDir: resolvedDataDir });
   });
   // WP-0 (§6.2): a fresh child has an empty token registry. Replay ours without
   // blocking the caller (start() is synchronous).
@@ -222,26 +495,108 @@ function start({ port = DEFAULT_PORT, dataDir } = {}) {
       process.stderr.write(`[oauth-proxy-supervisor] lead replay failed: ${String(err && err.message || err).slice(0, 200)}\n`);
     });
   }
-  return { ok: true, running: true, port, pid: _child.pid };
+  return { ok: true, running: true, port, pid: _child.pid, mode: 'child' };
+}
+
+/**
+ * Everything the child's 'exit' event owns (WP-3 calls this from the liveness probe too). `dataDir` and
+ * `port` are the ones THIS spawn was started with, so a recovery restart can never be retargeted by a
+ * changed environment.
+ */
+function _onProxyGone({ code, signal, port, dataDir }) {
+  // §5 D-6: an ADOPTED proxy has no child handle, so this handler is reached from the probe (or from an
+  // admin call that could not connect) rather than from an 'exit' event. Everything below is the same
+  // recovery either way; only the reaping differs, because the record a dead adopted pid left behind is
+  // stale truth that start() would otherwise have to discover by ps.
+  const adoptedPid = _mode === 'adopted' || _mode === 'adopting' ? (_adopted ? _adopted.pid : null) : null;
+  _clearLivenessProbe();
+  if (adoptedPid !== null) {
+    process.stderr.write(`[oauth-proxy-supervisor] adopted proxy pid=${adoptedPid} gone\n`);
+    instanceRecord.unlinkInstanceRecord({ dataDir });
+  }
+  if (code !== 0 && !signal) {
+    _lastError = `exited code=${code}`;
+  }
+  _child = null;
+  _startedAt = null;
+  _adminSecret = null;
+  _activeChildDataDir = null;
+  _adopted = null;
+  _mode = 'stopped';
+  // The dead child's in-memory token table is gone; any revoke that was still
+  // pending against it no longer has anything to reap.
+  _pendingLeadRevokes.clear();
+  // WP-0 (§6.2): an unexpected exit (signal, or a non-zero code) with live
+  // lead tokens must bring the proxy back so those tokens keep working. A
+  // graceful stop() opts out via _stopping; a crash-loop is rate-limited.
+  const unexpected = !!signal || code !== 0;
+  const wasStopping = _stopping;
+  _stopping = false;
+  // §9 S-5: the child records every SIGTERM exit, including the one a deliberate stop() sent. A stop
+  // is not a restart, so its record must not become the next start()'s "previous exit".
+  if (wasStopping) clearExitRecord({ dataDir });
+  if (unexpected && !wasStopping && _leadTokens.size > 0) {
+    if (Date.now() - _lastLeadAutoRestartAt >= LEAD_RESTART_MIN_INTERVAL_MS) {
+      _lastLeadAutoRestartAt = Date.now();
+      // WP-1 §5 D-3: the restart is bound to the directory the DEAD child was actually running with,
+      // captured here rather than re-resolved from a possibly-changed environment. A restart therefore
+      // cannot silently move the authority root out from under a surviving native owner.
+      start({ port, dataDir });
+    } else {
+      process.stderr.write('[oauth-proxy-supervisor] model-proxy-restart-suppressed\n');
+    }
+  }
 }
 
 function stop() {
+  const mode = _mode;
+  // §5 D-6: whatever happens below, this CTM is no longer watching that pid.
+  _clearLivenessProbe();
   if (!isRunning()) {
     _adminSecret = null;
     _activeChildDataDir = null;
-    return { ok: true, running: false, alreadyStopped: true };
+    _adopted = null;
+    return { ok: true, running: false, alreadyStopped: true, mode };
   }
-  // WP-0 (§6.2): mark this exit as deliberate so the lead-token auto-restart in
-  // the 'exit' handler stands down.
-  _stopping = true;
-  try {
-    _child.kill('SIGTERM');
-  } catch (err) {
-    return { ok: false, error: err.message };
+  const dataDir = _activeChildDataDir;
+  if (mode === 'child') {
+    // WP-0 (§6.2): mark this exit as deliberate so the lead-token auto-restart in
+    // the 'exit' handler stands down.
+    _stopping = true;
+    try {
+      _child.kill('SIGTERM');
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  } else if (_adopted && instanceRecord.isProxyProcess(_adopted.pid)) {
+    // §5 D-5: an explicit stop -- the /api/setup/oauth-proxy/stop path -- is the one caller allowed to
+    // end a proxy this CTM did not spawn, and only after ps proved the pid is still that proxy.
+    try {
+      process.kill(_adopted.pid, 'SIGTERM');
+    } catch (err) {
+      // REPORT: a pid that vanished between the probe and the signal is already stopped.
+      process.stderr.write(`[oauth-proxy-supervisor] stop signal failed: ${String(err && err.code || err).slice(0, 40)}\n`);
+    }
+  }
+  // An adoption in flight is superseded here: its continuation must not adopt (or spawn) after a stop.
+  _adoptionSeq += 1;
+  _adoptionPromise = null;
+  // The record and the secret are THIS CTM's files: an explicit stop leaves neither behind, so the next
+  // boot cannot resurrect a proxy that was deliberately stopped.
+  if (dataDir) {
+    instanceRecord.unlinkInstanceRecord({ dataDir });
+    instanceRecord.unlinkAdminSecret({ dataDir });
   }
   _adminSecret = null;
   _activeChildDataDir = null;
-  return { ok: true, running: false };
+  // §5 D-5: an adopted proxy is CTM's memory of a process it never owned, so the stop above ends that
+  // memory here. A child's own 'exit' handler owns the same reset, and only after the process is really
+  // gone -- the handle stays live until then so a start() in between is still refused.
+  if (mode !== 'child') {
+    _adopted = null;
+    _mode = 'stopped';
+  }
+  return { ok: true, running: false, mode };
 }
 
 async function status({ port = DEFAULT_PORT } = {}) {
@@ -250,6 +605,9 @@ async function status({ port = DEFAULT_PORT } = {}) {
       running: false,
       port,
       pid: null,
+      mode: _mode,
+      generation: null,
+      closureHash: null,
       uptime_ms: null,
       health: null,
       last_error: _lastError,
@@ -269,13 +627,101 @@ async function status({ port = DEFAULT_PORT } = {}) {
   return {
     running: true,
     port,
-    pid: _child.pid,
+    // §5 D-4: which identity is answering -- a child this CTM spawned, or a surviving proxy it adopted.
+    mode: _mode,
+    pid: _ownedPid(),
+    generation: _adopted ? _adopted.generation : 1,
+    closureHash: _adopted ? _adopted.closureHash : null,
     uptime_ms: _startedAt ? Date.now() - _startedAt : null,
+    // §5 D-6: the two things the PROXY knows and CTM does not -- lifted from /_health when it answered.
+    openStreams: health && Number.isSafeInteger(health.open_streams) ? health.open_streams : null,
+    draining: health ? !!health.draining : null,
     health,
     last_error: _lastError,
   };
 }
 
+/**
+ * §5 D-10 / §6 (WP-3): what the NEXT boot will do with the model proxy. The preflight's `proxy` field is
+ * this answer, passed through by lib/restart-preflight.js -- never recomputed there.
+ *
+ * This reads LIVE state only -- the published record and the proxy's own `/_health` -- never this
+ * module's `_mode`: a preflight answers for the next boot, which adopts whatever the record names
+ * whether or not this process is the one that spawned it. The verdict is the boot's own rule (D-4): no
+ * record on this port means nothing to do (`none`); a record the port does not answer for is the stale
+ * truth the boot reaps and replaces (`spawn`); a record whose pid IS the process answering is adopted,
+ * or handed off when the code on disk is not the code that process loaded. `closureDiffers:null` means
+ * the answering proxy published no closure at all (an older build), which is adoptable as it stands.
+ *
+ * @returns {Promise<{action:'adopt'|'handoff'|'spawn'|'none', pid:number|null,
+ *   openStreams:number|null, closureDiffers:boolean|null}>}
+ */
+async function proxyPreflight({ port = DEFAULT_PORT, dataDir } = {}) {
+  const resolvedDataDir = typeof dataDir === 'string' && dataDir.trim() ? path.resolve(dataDir) : getDataDir();
+  const record = instanceRecord.readInstanceRecord({ dataDir: resolvedDataDir });
+  if (!record || record.port !== port) {
+    return { action: 'none', pid: null, openStreams: null, closureDiffers: null };
+  }
+  const health = await _probeHealth(port);
+  // Same test _finishAdoption makes: the record names the process that must be answering on the port.
+  if (!health || health.pid !== record.pid) {
+    return { action: 'spawn', pid: null, openStreams: null, closureDiffers: null };
+  }
+  // The same seam the adoption decision reads: the disk side of the closure comparison.
+  const closureDiffers = Array.isArray(health.closure_files) && typeof health.closure_hash === 'string'
+    ? _hashClosureFiles(health.closure_files) !== health.closure_hash
+    : null;
+  return {
+    action: closureDiffers ? 'handoff' : 'adopt',
+    pid: health.pid,
+    openStreams: Number.isSafeInteger(health.open_streams) ? health.open_streams : null,
+    closureDiffers,
+  };
+}
+
+/**
+ * §5 D-4 at boot (WP-4 AC-4e): is there a proxy on this port that this data dir already owns -- a published
+ * record whose pid is a live proxy process? server.js's boot-start gate asks this beside WALLE_AUTH_METHOD,
+ * because the live proof found the primary does NOT set that method (its proxy is started later by the
+ * setup surface): without this question a proxy that survived the restart was never adopted, its lead
+ * tokens never re-tracked, and the restore_complete row said `spawn`. Sync on purpose -- the gate is in
+ * the sync boot path -- and it reuses the exact test start() makes before adopting (`isProxyProcess`).
+ * A stale record (pid gone) is NOT a survivor: start() is not called for it, so an operator who never
+ * configured the proxy never gets one spawned by a leftover file.
+ */
+function hasLiveSurvivor({ port = DEFAULT_PORT, dataDir } = {}) {
+  const resolvedDataDir = typeof dataDir === 'string' && dataDir.trim() ? path.resolve(dataDir) : getDataDir();
+  const record = instanceRecord.readInstanceRecord({ dataDir: resolvedDataDir });
+  return !!record && record.port === port && instanceRecord.isProxyProcess(record.pid);
+}
+
+/** §5 D-4 step 4: the health probe the adoption decision reads, with its own 2 s budget. */
+async function _probeHealth(port, timeoutMs = 2000) {
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/_health`, { signal: AbortSignal.timeout(timeoutMs) });
+    return resp.ok ? await resp.json() : null;
+  } catch (err) {
+    // expected: an unreachable proxy is a refused adoption, never a thrown boot
+    void err;
+    return null;
+  }
+}
+
+/** §5 D-4 step 5: the secret check -- an authenticated admin read, 200 means this secret is its own. */
+async function _probeAdminSecret({ port, secret, timeoutMs = 2000 }) {
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/_admin/lead-worker-picks`, {
+      headers: { [ADMIN_HEADER]: secret },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return resp.ok;
+  } catch (err) {
+    // expected: an unreachable proxy cannot confirm the secret; the caller falls back to a spawn
+    void err;
+    return false;
+  }
+}
+
 // ── D-8 readiness ────────────────────────────────────────────────────────
 // Polls /_health every ~100ms until it answers ok or the deadline passes.
 // A single fetch is not enough here: during the child's cold start (just
@@ -287,6 +733,22 @@ async function status({ port = DEFAULT_PORT } = {}) {
 const HEALTH_POLL_INTERVAL_MS = 100;
 
 async function waitForHealth({ port = DEFAULT_PORT, timeoutMs = 2000, signal } = {}) {
+  // §5 D-4: an adoption in flight decides whether /_health will be answered by the proxy already
+  // listening or by the child start() falls back to. Every caller already follows start() with this
+  // wait, so this is the one place that must outlast the decision.
+  if (_adoptionPromise) {
+    await _adoptionPromise.catch(() => {
+      // expected: a failed adoption already reaped the record and spawned a child; the loop below is
+      // the verdict on whichever proxy is now listening.
+    });
+  }
+  return _pollHealth({ port, timeoutMs, signal });
+}
+
+// The bare /_health poll, with no adoption wait in front of it. `_replayLeadTokens` runs INSIDE
+// `_finishAdoption` (the adoption promise itself), so it must use this one: awaiting the adoption from
+// there is a wait on oneself, and the replay -- hence the adoption -- would never finish.
+async function _pollHealth({ port = DEFAULT_PORT, timeoutMs = 2000, signal } = {}) {
   const deadline = Date.now() + timeoutMs;
   for (;;) {
     if (signal?.aborted) throw signal.reason || new Error('proxy health wait aborted');
@@ -332,6 +794,8 @@ async function _adminRequest({ port = DEFAULT_PORT, method, path: adminPath, bod
       signal: signal ? AbortSignal.any([AbortSignal.timeout(timeoutMs), signal]) : AbortSignal.timeout(timeoutMs),
     });
   } catch (err) {
+    // §5 D-6: a refused/reset connection to an ADOPTED proxy is a liveness answer for free.
+    _probeAdoptedAfterAdminFailure({ port, err });
     throw new ProxyAdminError('proxy_unreachable', `admin request failed: ${err.message}`);
   }
   if (!resp.ok) {
@@ -361,6 +825,50 @@ async function _adminRequest({ port = DEFAULT_PORT, method, path: adminPath, bod
   }
 }
 
+/**
+ * §5 D-7 (WP-2): ask the running proxy to hand its listening sockets and its memory-only state to a
+ * successor it spawns from disk. Resolves once the proxy answered 202 -- which it does only after the
+ * successor is genuinely serving AND the predecessor stopped accepting -- or throws a ProxyAdminError
+ * carrying the 409 reason (`already_draining`, `successor_not_ready`, `spawn_failed`).
+ *
+ * The two deadlines are TEST OVERRIDES and travel in the admin body only, never in the environment; the
+ * client's own wait outlives the proxy's readiness deadline, so a handoff the PROXY decides to abandon is
+ * reported by its own 409 rather than by a socket timeout here.
+ *
+ * @returns {Promise<{ok:true, generation:number, successorPid:number, handoffMs:number}>}
+ */
+async function requestHandoff({ port = DEFAULT_PORT, reason = 'closure-changed', readyDeadlineMs, drainDeadlineMs, signal } = {}) {
+  const body = { reason };
+  if (Number.isSafeInteger(readyDeadlineMs) && readyDeadlineMs > 0) body.readyDeadlineMs = readyDeadlineMs;
+  if (Number.isSafeInteger(drainDeadlineMs) && drainDeadlineMs > 0) body.drainDeadlineMs = drainDeadlineMs;
+  const readyMs = Number.isSafeInteger(readyDeadlineMs) && readyDeadlineMs > 0 ? readyDeadlineMs : HANDOFF_READY_DEADLINE_MS;
+  const result = await _adminRequest({
+    port,
+    method: 'POST',
+    path: '/_admin/handoff',
+    body,
+    timeoutMs: readyMs + 5000,
+    returnHttpErrors: true,
+    signal,
+  });
+  if (result && result.ok === true && Number.isSafeInteger(result.successorPid)) {
+    return { ok: true, generation: result.generation, successorPid: result.successorPid, handoffMs: result.handoffMs };
+  }
+  const refused = String((result && (result.reason || result.error)) || 'handoff_refused');
+  const err = new ProxyAdminError('handoff_refused', refused);
+  err.reason = refused;
+  throw err;
+}
+
+// Test seam (§6, AC-2f): the disk-side closure hash the compatibility decision compares, injectable so a
+// test can make an otherwise-compatible adoption read `upgrade-pending` without editing source.
+// Production never calls the setter.
+let _hashClosureFiles = hashClosureFiles;
+
+function _setHashClosureFilesForTest(fn) {
+  _hashClosureFiles = typeof fn === 'function' ? fn : hashClosureFiles;
+}
+
 // Forwards one worker-route contract row from Wall-E's internal feed verbatim.
 // Field names match lib/model-proxy/routes.js's buildRoute() input contract
 // ("model-proxy route protocol and gateway auth", 2026-09-26 §5 D-3..D-7,
@@ -745,9 +1253,13 @@ async function adoptLeadToken(registration = {}) {
 
 // Replays the CTM-side lead-token registry into a freshly spawned child: the new
 // child starts empty, so the SAME tokens must be re-registered to keep working.
-async function _replayLeadTokens({ port = DEFAULT_PORT } = {}) {
-  if (_leadTokens.size === 0) return;
-  await waitForHealth({ port, timeoutMs: 5000 });
+// `successor:true` (§5 D-7, WP-2) names a handoff successor: it already holds the tokens its
+// predecessor passed over, but its route and pick tables are empty, so CTM's copies are pushed
+// even when this process has no lead token of its own to replay.
+async function _replayLeadTokens({ port = DEFAULT_PORT, successor = false } = {}) {
+  if (_leadTokens.size === 0 && !successor) return;
+  // Never waitForHealth() here: two of the three callers are inside the adoption promise it awaits.
+  await _pollHealth({ port, timeoutMs: 5000 });
   try {
     await pushRoutesNow({ port });
   } catch (err) {
@@ -833,13 +1345,40 @@ async function probeRouteGeneration(alias, { model, timeoutMs = 30_000, port = D
   });
 }
 
+/** Test seam (§6): drop every module global this module owns, so the next case starts from a cold boot. */
+function _resetForTest() {
+  _child = null;
+  _startedAt = null;
+  _lastError = null;
+  _mode = 'stopped';
+  _adopted = null;
+  _adoptionPromise = null;
+  _adoptionSeq += 1;
+  _adminSecret = null;
+  _activeChildDataDir = null;
+  _lastExitRecord = null;
+  _exitRecordLoad = Promise.resolve();
+  _stopping = false;
+  _lastLeadAutoRestartAt = 0;
+  _leadTokens.clear();
+  _pendingLeadRevokes.clear();
+  _leadWorkerPicks = [];
+  _hashClosureFiles = hashClosureFiles;
+  _clearLivenessProbe();
+  _livenessProbeMs = PROXY_LIVENESS_MS;
+}
+
 module.exports = {
   DEFAULT_PORT,
   start,
   stop,
   status,
   isRunning,
+  // §5 D-10 / §9 S-12: the proxy's own restart outcome for the restore_complete ledger row.
+  lastRestartOutcome,
   waitForHealth,
+  // §5 D-7 (WP-2): the upgrade handoff CTM schedules on an `upgrade-pending` adoption.
+  requestHandoff,
   pushRoutesNow,
   pushLeadWorkerPicks,
   listWorkerRoutes,
@@ -856,20 +1395,45 @@ module.exports = {
   adoptLeadToken,
   leadTokenCount,
   LEAD_RESTART_MIN_INTERVAL_MS,
+  // §5 D-6: the adopted-mode probe cadence, exported beside the rate limit it mirrors.
+  PROXY_LIVENESS_MS,
+  // §5 D-10 (WP-3): what the next boot will do with the proxy, for computeRestartPreflight({ proxy }).
+  proxyPreflight,
+  // §5 D-4 at boot (WP-4 AC-4e): the boot-start gate's second question -- a live recorded survivor is adopted
+  // whether or not WALLE_AUTH_METHOD names the proxy.
+  hasLiveSurvivor,
   ProxyAdminError,
   _internals: {
     _rowToAdminRoute,
     workerTokenAdminBody,
     ADMIN_HEADER,
     _setRouteFetcherForTest,
+    // §5 D-6/§6: shrink the adopted-mode probe cadence so a liveness case does not take 10 s (and so
+    // AC-3a's own bound can be checked against production's constant, which is exported beside it).
+    _setLivenessProbeMsForTest,
+    // §5 D-7/§6 (AC-2f): make the disk-side closure hash disagree, so the adoption decision reads
+    // `upgrade-pending` and the handoff path runs, without editing source. Pass null to restore.
+    _setHashClosureFilesForTest,
     _leadTokens,
     _pendingLeadRevokes,
     // WP-1 §5 D-3/§6.5: the directory the LIVE child was actually started with, resolved once at spawn.
     // Exposed read-only for tests that assert pinning; nothing here is a secret.
     get _activeChildDataDir() { return _activeChildDataDir; },
+    // §9 S-12: the async read+clear of the previous exit record that start() kicked off; a test awaits it
+    // before asserting lastRestartOutcome()'s previous-exit fields.
+    get _exitRecordLoad() { return _exitRecordLoad; },
     // Test read/reset seam: a getter so tests see the CURRENT table after a
     // replay reassigns it, and a setter so a test can clear it in after().
     get _leadWorkerPicks() { return _leadWorkerPicks; },
     set _leadWorkerPicks(value) { _leadWorkerPicks = Array.isArray(value) ? value : []; },
+    // §5 D-4: which identity this module holds ('stopped' | 'child' | 'adopting' | 'adopted') and the
+    // adopted proxy's facts, plus the in-flight adoption decision a test can await.
+    get _mode() { return _mode; },
+    get _adopted() { return _adopted; },
+    get _adoptionPromise() { return _adoptionPromise; },
+    // Test seam: forgets every module-global this module owns, so the next case in the same process
+    // starts from a genuinely cold boot. It does NOT signal anything -- a case that started a proxy
+    // stops it in its own t.after().
+    _resetForTest,
   },
 };