create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/lib/model-proxy/handoff.js

@@ -0,0 +1,494 @@
+'use strict';
+
+// §5 D-7 / §5 D-9 / §9 S-6, S-10, S-13 (docs/model-proxy-survives-ctm-restart-2026-10-22.html): the
+// UPGRADE HANDOFF -- both halves of it, in one place.
+//
+// The proxy's code changed on disk (CTM adopted it with `upgrade-pending`), so the running proxy cannot
+// keep serving new code it never loaded, and CTM must not simply kill it: every in-flight model stream of
+// every live CLI dies with it. Instead the OLD proxy spawns its own path from disk -- its successor --
+// passes over the two LISTENING sockets it owns (plaintext HTTP, and the native mTLS listener when it is
+// up), the memory-only state that has no other authority (the token registry, the per-token last lead
+// model), and then stops ACCEPTING, drains its in-flight streams, and exits 0.
+//
+// The pillars this is built from (§3 P-1..P-4): the fd is passed, never re-bound (no EADDRINUSE window,
+// no dropped syscall between two binds); the successor's `ready` is a handshake BEFORE the predecessor
+// stops accepting; stop-accepting is split from stop-serving (`native-lead-listener.stopAccepting()`,
+// `wrapHttpServerClose(..., { drain:true })`); and the drain is BOUNDED -- at `DRAIN_DEADLINE_MS` the
+// remaining streams are cut and the process still exits 0 so nothing is left half-upgraded.
+//
+// What this module deliberately does NOT do: it never picks a different port, never retries a failed
+// handoff (the predecessor keeps serving and CTM's next adoption tries again), and never writes the
+// instance record of its successor -- the successor publishes its own identity, and a predecessor that
+// is still draining must not unlink it (`isDraining()` is what keeps its SIGTERM handler off that file).
+
+const { spawn } = require('node:child_process');
+
+const tokens = require('./tokens');
+const leadWorkerPicks = require('./lead-worker-picks');
+const instanceRecord = require('./proxy-instance-record');
+const streamAccounting = require('./stream-accounting');
+const { wrapHttpServerClose } = require('./native-lead-listener');
+
+// §5 D-7: the successor must answer `ready` within this; the old proxy keeps serving unchanged if it does
+// not. Host handoffs measured 179-256 ms for five sessions, and the successor also loads the TLS
+// authority, so 15 s is two orders of magnitude of headroom and still bounded.
+const HANDOFF_READY_DEADLINE_MS = 15_000;
+// §5 D-7: the failsafe only -- a drain normally ends the moment the counter reaches zero. 45 real
+// streamed requests exceeded 10 minutes (§1.3), so the ceiling is above the longest observed turn.
+const DRAIN_DEADLINE_MS = 1_800_000;
+
+const HANDOFF_MESSAGE = 'handoff/v1';
+const HANDOFF_NATIVE_MESSAGE = 'handoff/v1/native';
+const HANDOFF_STATE_MESSAGE = 'handoff/v1/state';
+const READY_MESSAGE = 'ready';
+const HANDOFF_INHERITANCE_TIMEOUT_CODE = 'handoff_inheritance_timeout';
+
+// The successor is always THIS file's sibling from disk, never a caller-supplied path.
+const PROXY_SCRIPT = require.resolve('../../oauth-proxy.js');
+
+// Whether THIS process has taken itself out of the accepting role: the record on disk now belongs to the
+// successor, so a SIGTERM arriving after step 6 must not unlink it (WP-0's handler asks exactly this).
+let _predecessorState = null;
+
+function isDraining() {
+  return _predecessorState !== null;
+}
+
+// ── §5 D-8: the proxy's own linger ────────────────────────────────────────────────────────────────────
+// A proxy outlives the CTM that spawned it (§5 D-4) on purpose: a restart is a reconnect, and the
+// in-flight streams of every live CLI survive it. The other half of that bargain is that a proxy which
+// outlives CTM FOR GOOD must not serve forever -- it is a credential-holding listener on a loopback port.
+// So it keeps serving a while after the last sign of life from above and then leaves by itself, exactly
+// as a session host does (workers/session-host-pool-process.js:49 `HOST_LINGER_MS`, same value on
+// purpose: one linger policy to reason about, and an operator reads "15 minutes" once, in both logs).
+const PROXY_LINGER_MS = 15 * 60_000; // === HOST_LINGER_MS
+
+// "Contact" is exactly one thing: a request that passed the admin-secret check in oauth-proxy.js's
+// `_handleAdmin` -- CTM's boot probe, its lead-worker-picks read, a token mint, a handoff request. The
+// unauthenticated surfaces (`/_health`, `/_status`, `/r/*`) are NOT contact: anyone on the loopback
+// interface can poll them, so counting them would let a spectator keep a stale proxy alive for ever.
+let _lastAdminContactAt = null;
+// The ONE timer, armed by the CLI's start() only (see armLinger): null means "this process never lingers".
+let _lingerTimer = null;
+
+/** §5 D-8: record contact from above. Called once per authenticated admin request, and nowhere else. */
+function noteAdminContact({ now = Date.now() } = {}) {
+  _lastAdminContactAt = now;
+}
+
+/** The moment of the last authenticated admin request, or null when this process has never had one. */
+function lastAdminContactAt() {
+  return _lastAdminContactAt;
+}
+
+/** Test seam (§6): whether a linger timer is armed. Nothing in production reads it. */
+function _lingerArmedForTest() {
+  return _lingerTimer !== null;
+}
+
+function _armLingerTimer({ lingerMs, ctx }) {
+  _lingerTimer = setTimeout(() => {
+    _lingerTimer = null;
+    _lingerTick({ lingerMs, ctx });
+  }, lingerMs);
+  // §5 D-8: never a reason for this process to stay alive -- the listeners and the sockets are.
+  _lingerTimer.unref();
+}
+
+/**
+ * §5 D-8: one tick. The window is the cadence as well as the test, so there is one constant here, not two.
+ * Anything that could still be serving -- an in-flight stream, an open connection on either lane, a
+ * handoff being brought up -- re-arms and the process stays.
+ */
+function _lingerTick({ lingerMs, ctx }) {
+  const idleMs = _lastAdminContactAt === null ? 0 : Date.now() - _lastAdminContactAt;
+  const rearm = () => _armLingerTimer({ lingerMs, ctx });
+  // A predecessor mid-handoff is not idle: its successor is starting, and its own drain owns its exit.
+  if (idleMs < lingerMs || isDraining()) { rearm(); return; }
+  // The counter outlives the transfer for an upgraded stream, so it is checked as well as the sockets.
+  if (ctx.streamAccounting.count() > 0) { rearm(); return; }
+  const nativeCount = ctx.nativeListener && typeof ctx.nativeListener.socketCount === 'function'
+    ? ctx.nativeListener.socketCount()
+    : 0;
+  if (nativeCount > 0) { rearm(); return; }
+  ctx.httpServer.getConnections((err, count) => {
+    // REPORT: a count that cannot be read is treated as busy -- an unanswerable question must never be
+    // the reason a proxy holding live credentials disappears.
+    if (err || count > 0) { rearm(); return; }
+    _exitOnLinger({ idleMs, ctx });
+  });
+}
+
+/** §5 D-8: the exit itself -- record it, remove this process's own record, and leave 0. */
+function _exitOnLinger({ idleMs, ctx }) {
+  console.log(`[model-proxy] exit reason=linger idle_ms=${idleMs}`);
+  // The record names a process that is about to be gone, so the next CTM spawns rather than adopts. It is
+  // removed BEFORE the exit record is written: that one is the ledger's, and it is written once.
+  instanceRecord.unlinkInstanceRecord({ dataDir: ctx.dataDir });
+  streamAccounting.writeExitRecord({ dataDir: ctx.dataDir, reason: 'linger', openStreams: 0 })
+    .catch((err) => {
+      // REPORT: the exit code below still classifies this exit, so a failed write is not fatal.
+      console.error(`[model-proxy] exit record not written: ${(err && err.code) || 'unknown'}`);
+    })
+    .then(() => process.exit(0));
+}
+
+/**
+ * §5 D-8: arm the linger timer for THIS process. Only the CLI calls this (proxy-cli.js, with an optional
+ * `CTM_TEST_PROXY_LINGER_MS` override) -- an embedded start() from a test or another module passes no
+ * `lingerMs`, so no test process can ever be exited by a proxy's own linger.
+ *
+ * "Contact" starts at arming time: a process that has just started (a handoff SUCCESSOR above all) has
+ * been in contact by construction -- its predecessor only hands over after an authenticated request.
+ *
+ * @param {object} input
+ * @param {number} [input.lingerMs] the idle window, defaulting to PROXY_LINGER_MS
+ * @param {object} input.ctx this server's context (`httpServer`, `nativeListener`, `streamAccounting`,
+ *   `dataDir` -- everything the tick needs to prove nothing is being served)
+ */
+function armLinger({ lingerMs = PROXY_LINGER_MS, ctx } = {}) {
+  if (!ctx || !ctx.httpServer || !ctx.streamAccounting) return false;
+  if (_lingerTimer) clearTimeout(_lingerTimer);
+  _lastAdminContactAt = _lastAdminContactAt === null ? Date.now() : _lastAdminContactAt;
+  _armLingerTimer({ lingerMs: _positiveIntOr(lingerMs, PROXY_LINGER_MS), ctx });
+  return true;
+}
+
+/** A bounded deadline comes from the admin body or not at all: anything that is not a positive integer
+ *  (a float, a string, 0, a negative, a missing field) is IGNORED and the constant stands. */
+function _positiveIntOr(value, fallback) {
+  return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+/**
+ * §5 D-7 steps 1-6: hand this proxy over to a successor spawned from disk.
+ *
+ * @param {object} input
+ * @param {object} input.ctx the running server's context (its `streamAccounting` is the drain signal)
+ * @param {import('http').Server} input.httpServer the plaintext server whose listening socket is passed
+ * @param {object|null} [input.nativeListener] the mTLS controller; its server is passed only when ready
+ * @param {string} input.dataDir the canonical data directory (record, secret and log live under it)
+ * @param {number} input.port the bound plaintext port
+ * @param {number|null} [input.nativePort] the bound native port, when the listener was up
+ * @param {string|null} [input.adminSecret] this process's admin secret, re-used by the successor
+ * @param {number} [input.generation] this process's generation; the successor is +1
+ * @param {number} [input.readyDeadlineMs] test override (admin body only, never env)
+ * @param {number} [input.drainDeadlineMs] test override (admin body only, never env)
+ * @param {object} [input.log] `log`/`error` sink, default console
+ * @returns {Promise<{ok:true, generation:number, successorPid:number, handoffMs:number, armDrain:Function}
+ *   | {ok:false, status:409, reason:string}>} the caller's `armDrain()` runs the drain (step 7) once its
+ *   own 202 has been written, so the exit this schedules can never preempt the response.
+ */
+async function initiateHandoff({
+  ctx = null,
+  httpServer = null,
+  nativeListener = null,
+  dataDir = null,
+  port = null,
+  nativePort = null,
+  adminSecret = null,
+  generation = 1,
+  readyDeadlineMs,
+  drainDeadlineMs,
+  log = console,
+} = {}) {
+  // step 1 -- one handoff per process, and the first one is final: a drained predecessor has nothing
+  // left to hand over, and a second caller must not spawn a second successor.
+  if (_predecessorState) return { ok: false, status: 409, reason: 'already_draining' };
+  _predecessorState = 'draining';
+  const startedAt = Date.now();
+  const readyMs = _positiveIntOr(readyDeadlineMs, HANDOFF_READY_DEADLINE_MS);
+  const drainMs = _positiveIntOr(drainDeadlineMs, DRAIN_DEADLINE_MS);
+  const accounting = ctx && ctx.streamAccounting ? ctx.streamAccounting : null;
+
+  const abort = (reason) => {
+    // §5 D-7 step 5 ("abort restores"): the predecessor kept serving, so both truths it wrote must say
+    // so again -- the record stops claiming a drain, and /_health stops reporting one. The IDENTITY is
+    // restored with them: a successor that got as far as publishing its own record and then never
+    // answered is killed here, so the record must name the process that is really serving rather than
+    // the one that just died (otherwise the next boot reads a dead pid and spawns a second proxy onto a
+    // port this process still holds).
+    _predecessorState = null;
+    instanceRecord.updateInstanceRecord({
+      dataDir, patch: { pid: process.pid, generation, predecessorPid: null, draining: false },
+    });
+    if (accounting && typeof accounting.setDraining === 'function') accounting.setDraining(false);
+    return { ok: false, status: 409, reason };
+  };
+
+  // step 2 -- the record is truthful BEFORE the successor exists: a predecessor that dies mid-handoff
+  // leaves a record that says a handoff was in progress rather than one that silently claims to serve.
+  instanceRecord.updateInstanceRecord({ dataDir, patch: { draining: true } });
+  if (accounting && typeof accounting.setDraining === 'function') accounting.setDraining(true);
+
+  // step 3 -- detached, its own log file, an IPC channel for the two handles, and this process's own
+  // environment (the successor is the same proxy with the same configurability).
+  let logFd = null;
+  let child = null;
+  try {
+    logFd = instanceRecord.openProxyLogFd(dataDir);
+    child = spawn(process.execPath, [PROXY_SCRIPT], {
+      detached: true,
+      stdio: ['ignore', logFd, logFd, 'ipc'],
+      env: process.env,
+      serialization: 'json',
+    });
+  } catch (err) {
+    // REPORT: a successor that could not be created is the same outcome as one that never answered.
+    log.error(`[model-proxy] handoff spawn failed: ${(err && err.code) || 'unknown'}`);
+    instanceRecord.closeProxyLogFd(logFd);
+    return abort('spawn_failed');
+  }
+  instanceRecord.closeProxyLogFd(logFd); // the successor holds its own copy of the descriptor
+  child.unref(); // CTM owns neither proxy; a successor must not be reaped with this process
+
+  // steps 4 + 5 -- the handshake. The wait is armed BEFORE the first send, so a successor that answers
+  // instantly cannot be missed.
+  const ready = _waitForReady(child, readyMs);
+  const handed = _sendHandoff(child, httpServer, nativeListener, {
+    adminSecret, dataDir, port, nativePort, generation: generation + 1,
+  });
+  const outcome = handed ? await ready : { ok: false, reason: 'successor_not_ready' };
+  if (!outcome.ok) {
+    try {
+      child.kill('SIGKILL');
+    } catch (err) {
+      // expected: the successor may already be gone; the predecessor's own state is what matters.
+      void err;
+    }
+    log.error(`[model-proxy] handoff aborted: ${outcome.reason}`);
+    return abort(outcome.reason);
+  }
+
+  // step 6 -- stop ACCEPTING (never destroy): the plaintext listening socket is closed here and the
+  // native listener releases its own, while every connection either one already accepted keeps serving.
+  const handoffMs = Date.now() - startedAt;
+  if (nativeListener) wrapHttpServerClose(httpServer, nativeListener, { drain: true });
+  httpServer.close();
+  if (typeof httpServer.closeIdleConnections === 'function') httpServer.closeIdleConnections();
+  _predecessorState = 'drained';
+  log.log(`[model-proxy] handoff successor_pid=${outcome.pid} generation=${generation + 1} handoff_ms=${handoffMs}`);
+  return {
+    ok: true,
+    generation: generation + 1,
+    successorPid: outcome.pid,
+    handoffMs,
+    // step 7 is armed by the CALLER, once its own 202 is on the wire.
+    armDrain: () => startDrain({ accounting, httpServer, nativeListener, drainMs, log }),
+  };
+}
+
+/**
+ * §5 D-7 step 5 (successor side): everything that must be true before `ready` may be sent. The inherited
+ * TLS socket is re-bound first -- when the predecessor had one, its listener was serving, so the
+ * successor must be serving on the same socket before the predecessor stops accepting on it.
+ * @returns {Promise<void>} resolves when this process is genuinely serving
+ */
+function announceInheritedStart({ ctx, inherited, record }) {
+  if (!inherited.nativeHandle || !ctx || !ctx.nativeListener) return Promise.resolve(sendReady(inherited, record));
+  return ctx.nativeListener.ensureReady().then(
+    () => sendReady(inherited, record),
+    (err) => {
+      // REPORT: the inherited TLS socket could not be re-bound; the plaintext lane is unaffected and the
+      // native lane falls back to its own bind on the next registration.
+      process.stderr.write(`[model-proxy] inherited native listener unavailable: ${(err && err.code) || 'unknown'}\n`);
+      return sendReady(inherited, record);
+    },
+  );
+}
+
+/** §6 test seam (AC-2b): a successor that is held back does everything else and never answers. */
+function sendReady(inherited, record) {
+  if (inherited.holdReady) return;
+  process.send({ t: READY_MESSAGE, pid: process.pid, closureHash: record ? record.closureHash : null });
+}
+
+/**
+ * §5 D-7 step 4: the three messages, in the order the successor expects them. The plaintext server goes
+ * with the first one, the TLS server with the second -- and only when it is really up, because a
+ * listener that never bound has no socket to give (the successor binds the port itself in that case).
+ * @returns {boolean} false when the channel refused a send, which aborts the handoff
+ */
+function _sendHandoff(child, httpServer, nativeListener, payload) {
+  try {
+    child.send({ t: HANDOFF_MESSAGE, ...payload, predecessorPid: process.pid }, httpServer);
+    if (nativeListener && nativeListener.isReady() && typeof nativeListener.server === 'function') {
+      child.send({ t: HANDOFF_NATIVE_MESSAGE }, nativeListener.server());
+    }
+    child.send({
+      t: HANDOFF_STATE_MESSAGE,
+      tokens: tokens.exportAll(),
+      lastLeadModel: leadWorkerPicks.exportLastLeadModel(),
+    });
+    return true;
+  } catch (err) {
+    // REPORT: the successor never became reachable, so the caller kills it and keeps serving.
+    process.stderr.write(`[model-proxy] handoff send failed: ${(err && err.code) || 'unknown'}\n`);
+    return false;
+  }
+}
+
+/**
+ * §5 D-7 step 5: `{ t:'ready', pid, closureHash }` within the deadline; a successor that exits first is
+ * the same failure as one that never answers.
+ * @returns {Promise<{ok:true, pid:number, closureHash:string}|{ok:false, reason:'successor_not_ready'}>}
+ */
+function _waitForReady(child, readyMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer = null;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.removeListener('message', onMessage);
+      child.removeListener('exit', onExit);
+      resolve(value);
+    };
+    const onMessage = (message) => {
+      if (message && message.t === READY_MESSAGE) settle({ ok: true, pid: message.pid, closureHash: message.closureHash });
+    };
+    const onExit = () => settle({ ok: false, reason: 'successor_not_ready' });
+    timer = setTimeout(() => settle({ ok: false, reason: 'successor_not_ready' }), readyMs);
+    child.on('message', onMessage);
+    child.on('exit', onExit);
+  });
+}
+
+/**
+ * §5 D-7 step 7: exit 0 the moment the counter reaches zero (the decrement notifies -- there is no
+ * polling loop), or at the deadline cut whatever is left and exit 0 anyway. `drain_forced_cuts` is the
+ * count AT the moment of the cut, so a clean drain logs 0 and the number is never a guess.
+ */
+function startDrain({ accounting = null, httpServer = null, nativeListener = null, drainMs = DRAIN_DEADLINE_MS, log = console } = {}) {
+  let done = false;
+  let timer = null;
+  const finish = (forcedCuts) => {
+    if (done) return;
+    done = true;
+    clearTimeout(timer);
+    log.log(`[model-proxy] drain_forced_cuts=${forcedCuts}`);
+    process.exit(0);
+  };
+  timer = setTimeout(() => {
+    const remaining = accounting ? accounting.count() : 0;
+    try {
+      if (httpServer && typeof httpServer.closeAllConnections === 'function') httpServer.closeAllConnections();
+    } catch (err) {
+      // expected: a server that is already closed owns no connection to cut; the exit below still runs.
+      void err;
+    }
+    if (nativeListener && typeof nativeListener.close === 'function') {
+      try {
+        nativeListener.close();
+      } catch (err) {
+        // expected: the native listener may already be closed; the exit below still runs.
+        void err;
+      }
+    }
+    finish(remaining);
+  }, drainMs);
+  if (!accounting || accounting.count() === 0) {
+    // Nothing is in flight: leave on the next turn, so the caller's own response has been queued first.
+    setImmediate(() => finish(0));
+    return;
+  }
+  accounting.onIdle(() => finish(0));
+}
+
+/**
+ * §5 D-7 (successor side): collect the predecessor's three messages and resolve what they carry. Only a
+ * process spawned with an IPC channel calls this -- and it is the SUCCESSOR, so it never reads stdin.
+ *
+ * Termination is the STATE message, not a count: the native message is optional (it is sent only when
+ * the predecessor's TLS listener was up), and IPC preserves order, so the state message proves whether a
+ * native handle was coming.
+ *
+ * @param {{timeoutMs?:number}} [options] bounded wait; a predecessor that dies mid-handshake must not
+ *   leave a successor waiting forever
+ * @returns {Promise<{inherited:object, state:{tokens:Array, lastLeadModel:Array}}>}
+ */
+function receiveInheritance({ timeoutMs = HANDOFF_READY_DEADLINE_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    if (typeof process.send !== 'function' || typeof process.on !== 'function') {
+      const err = new Error('handoff inheritance requested without an IPC channel');
+      err.code = HANDOFF_INHERITANCE_TIMEOUT_CODE;
+      reject(err);
+      return;
+    }
+    let first = null;
+    let nativeHandle = null;
+    let state = null;
+    let settled = false;
+    let timer = null;
+    const cleanup = () => {
+      clearTimeout(timer);
+      process.removeListener('message', onMessage);
+    };
+    const maybe = () => {
+      if (settled || !first || !state) return;
+      settled = true;
+      cleanup();
+      resolve({
+        inherited: {
+          httpHandle: first.httpHandle,
+          nativeHandle,
+          adminSecret: first.adminSecret,
+          dataDir: first.dataDir,
+          port: first.port,
+          nativePort: first.nativePort === undefined ? null : first.nativePort,
+          generation: first.generation,
+          predecessorPid: first.predecessorPid,
+        },
+        state: {
+          tokens: Array.isArray(state.tokens) ? state.tokens : [],
+          lastLeadModel: Array.isArray(state.lastLeadModel) ? state.lastLeadModel : [],
+        },
+      });
+    };
+    const onMessage = (message, handle) => {
+      if (!message || typeof message !== 'object') return;
+      if (message.t === HANDOFF_MESSAGE) {
+        first = { ...message, httpHandle: handle };
+        maybe();
+        return;
+      }
+      if (message.t === HANDOFF_NATIVE_MESSAGE) {
+        nativeHandle = handle;
+        return;
+      }
+      if (message.t === HANDOFF_STATE_MESSAGE) {
+        state = message;
+        maybe();
+      }
+    };
+    timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      const err = new Error('handoff inheritance timed out');
+      err.code = HANDOFF_INHERITANCE_TIMEOUT_CODE;
+      reject(err);
+    }, _positiveIntOr(timeoutMs, HANDOFF_READY_DEADLINE_MS));
+    process.on('message', onMessage);
+  });
+}
+
+module.exports = {
+  HANDOFF_READY_DEADLINE_MS,
+  DRAIN_DEADLINE_MS,
+  // §5 D-8: the proxy's own idle window, and the two functions that implement it. `noteAdminContact` is
+  // the ONLY writer of the contact clock; oauth-proxy.js calls it from one place, after the secret check.
+  PROXY_LINGER_MS,
+  armLinger,
+  noteAdminContact,
+  lastAdminContactAt,
+  _lingerArmedForTest,
+  HANDOFF_INHERITANCE_TIMEOUT_CODE,
+  initiateHandoff,
+  receiveInheritance,
+  announceInheritedStart,
+  startDrain,
+  isDraining,
+  _positiveIntOr,
+};

package/template/coding-task-manager/lib/model-proxy/lead-worker-picks.js

@@ -112,6 +112,29 @@ function forgetToken(token) {
   _lastLeadModel.delete(token);
 }
 
+/** §9 S-10 (WP-2 handoff): the memory-only per-token model memory, as IPC-safe rows. */
+function exportLastLeadModel() {
+  return [..._lastLeadModel.entries()];
+}
+
+/**
+ * Register each exported pair verbatim (§9 S-10). A malformed row is skipped rather than thrown on:
+ * one unreadable pair must not keep a successor from serving the pairs that are readable.
+ * @returns {number} how many pairs were registered
+ */
+function importLastLeadModel(rows) {
+  if (!Array.isArray(rows)) return 0;
+  let imported = 0;
+  for (const row of rows) {
+    if (!Array.isArray(row) || row.length !== 2) continue;
+    const [token, model] = row;
+    if (!_isNonEmptyString(token) || !_isNonEmptyString(model)) continue;
+    _lastLeadModel.set(token, model);
+    imported += 1;
+  }
+  return imported;
+}
+
 /**
  * Resolve a `walle-worker` model request against this lead session's pick table (§5 D-6/D-7).
  * @returns {{swapped:false} | {swapped:true, alias:string, model:string, source:'pick'|'last_lead_model'} | {error:'subagent_pick_unset'}}
@@ -146,5 +169,7 @@ module.exports = {
   noteLeadModel,
   lastLeadModel,
   forgetToken,
+  exportLastLeadModel,
+  importLastLeadModel,
   resolveWorkerAlias,
 };

package/template/coding-task-manager/lib/model-proxy/native-lead-listener.js

@@ -95,6 +95,9 @@ function _peerCertificateFingerprint(socket) {
 
 function _deny(res, status, code) {
   if (res.writableEnded || res.headersSent) return;
+  // §9 S-9: one line, the finite reason code only — never the certificate, header value or path that
+  // caused the refusal, and never the body this connection never got to send.
+  console.log(`[model-proxy] refused status=${status} reason=${code}`);
   res.writeHead(status, { 'content-type': 'application/json' });
   res.end(JSON.stringify({ type: 'error', error: { type: 'authentication_error', code, message: code } }));
 }
@@ -111,7 +114,7 @@ function _deny(res, status, code) {
  * @param {Function} input.onAuthorizedRequest the host callback into the shared routing pipeline,
  *   invoked as `(req, res, {token, binding, suffix, query, fingerprint})` after authorization
  */
-function createNativeLeadListener({ httpPort, dataDir, loadAuthority, onAuthorizedRequest } = {}) {
+function createNativeLeadListener({ httpPort, dataDir, loadAuthority, onAuthorizedRequest, streamAccounting, inheritedHandle = null } = {}) {
   // Static refusals, before anything can bind. A port whose successor is not a TCP port is refused
   // rather than renumbered (D-8: a collision fails this transport explicitly; it never strands an
   // adopted host on a port nobody recorded).
@@ -253,6 +256,9 @@ function createNativeLeadListener({ httpPort, dataDir, loadAuthority, onAuthoriz
     server.on('tlsClientError', (_err, socket) => {
       try { socket.destroy(); } catch { /* expected: the failed handshake socket is already unusable. */ }
     });
+    // §5 D-9: this lane's requests are counted by the SAME counter as the plaintext lane when the host
+    // supplies one; a caller that wires none counts none.
+    if (streamAccounting) streamAccounting.track(server);
     server.on('request', (req, res) => {
       _handleRequest(req, res).catch(() => {
         if (!res.headersSent && !res.writableEnded) _deny(res, 500, 'native_lead_request_failed');
@@ -274,7 +280,11 @@ function createNativeLeadListener({ httpPort, dataDir, loadAuthority, onAuthoriz
       server.once('error', onError);
       server.once('listening', onListening);
       try {
-        server.listen(nativePort, LOOPBACK_ADDRESS);
+        // §5 D-7 step 4 / S-6: a handoff successor binds the TLS LISTENING SOCKET its predecessor passed
+        // over IPC, so the port never has a gap and no second bind can race an EADDRINUSE. Without a
+        // handle this is today's lazy port bind, byte for byte.
+        if (inheritedHandle) server.listen(inheritedHandle);
+        else server.listen(nativePort, LOOPBACK_ADDRESS);
       } catch {
         onError();
       }
@@ -318,6 +328,29 @@ function createNativeLeadListener({ httpPort, dataDir, loadAuthority, onAuthoriz
     _admissionClosed = true;
   }
 
+  /**
+   * §5 D-7 step 6 / S-6: stop ACCEPTING on this listener without touching a single accepted connection.
+   * This is the handoff's half of the stop-accepting/stop-serving split (P-3): the predecessor is on its
+   * way out, so it must not take another connection, and every mTLS request already in flight finishes
+   * on the socket it arrived on. Idempotent, and a listener that never became ready resolves at once.
+   *
+   * The listening handle is released SYNCHRONOUSLY by `close()`; close()'s own callback fires only once
+   * every open connection has ended, which is exactly what this function must not wait for.
+   * @returns {Promise<void>}
+   */
+  function stopAccepting() {
+    _admissionClosed = true;
+    const server = _server;
+    if (!server) return Promise.resolve();
+    try {
+      server.close();
+    } catch (err) {
+      // expected: a server that is already closed owns nothing to release; the refusal flag above stands.
+      void err;
+    }
+    return Promise.resolve();
+  }
+
   async function _joinInit() {
     if (!_readyPromise) return;
     try {
@@ -364,6 +397,9 @@ function createNativeLeadListener({ httpPort, dataDir, loadAuthority, onAuthoriz
     ensureReady,
     close,
     closeHttpAdmission,
+    stopAccepting,
+    /** §5 D-7 step 4 / S-6: the LIVE server, for `child.send(msg, listener.server())`. Null until ready. */
+    server: () => _server,
     nativePort,
     baseUrl: `https://${LOOPBACK_ADDRESS}:${nativePort}/native-lead/v1`,
     isReady: () => _server !== null,
@@ -372,6 +408,12 @@ function createNativeLeadListener({ httpPort, dataDir, loadAuthority, onAuthoriz
   };
 }
 
+// The un-wrapped close is remembered ON the server (never in a module global: two servers can be alive
+// in one process) so a LATER wrap can replace the behaviour instead of stacking on top of it. The
+// handoff drain (§5 D-7 step 6) installs its wrap after start() already installed the normal-mode one,
+// and a stacked wrap would run the destroying close underneath the non-destroying stop.
+const kOriginalServerClose = Symbol('ctmHttpServerOriginalClose');
+
 /**
  * Wrap an HTTP server's `close` so the native listener starts closing IMMEDIATELY and the caller's
  * callback fires only once BOTH joins completed.
@@ -383,15 +425,27 @@ function createNativeLeadListener({ httpPort, dataDir, loadAuthority, onAuthoriz
  * controller first removes that ordering hazard; the callback still waits for both, and `close()`
  * returns the server, exactly as Node's does.
  *
+ * `drain:false` (every caller before WP-2, and every caller that passes no options) is today's
+ * behaviour byte for byte: admission closed, sockets destroyed. `drain:true` is the handoff's
+ * stop-ACCEPTING half — the listener releases its listening socket and every accepted connection keeps
+ * serving; the predecessor exits once the counter reaches zero, or at the drain deadline (§5 D-7 step 7).
+ *
  * @param {import('http').Server} server
- * @param {{close:Function, closeHttpAdmission:Function}} listener
+ * @param {{close:Function, closeHttpAdmission:Function, stopAccepting?:Function}} listener
+ * @param {{drain?:boolean}} [options]
  * @returns {import('http').Server} the same server
  */
-function wrapHttpServerClose(server, listener) {
-  const originalClose = server.close;
+function wrapHttpServerClose(server, listener, { drain = false } = {}) {
+  const originalClose = server[kOriginalServerClose] || server.close;
+  server[kOriginalServerClose] = originalClose;
   server.close = function close(callback) {
-    listener.closeHttpAdmission();
-    const nativeDone = listener.close();
+    let nativeDone;
+    if (drain && typeof listener.stopAccepting === 'function') {
+      nativeDone = listener.stopAccepting();
+    } else {
+      listener.closeHttpAdmission();
+      nativeDone = listener.close();
+    }
     const httpDone = new Promise((resolve) => {
       try {
         originalClose.call(this, () => resolve());