create-walle 0.10.2 → 0.10.3

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

@@ -20,6 +20,7 @@
  * §8 WP-2, §9 S-5.
  */
 
+const { moveToOwnScope } = require('./systemd-scope');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawn } = require('node:child_process');
@@ -99,7 +100,7 @@ const PROXY_LIVENESS_MS = 10_000;
 // 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'.
+// dropped on stop()/_resetForTest() and whenever the mode leaves 'child'/'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.
@@ -107,6 +108,9 @@ 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;
+// §5 D-1b: whether the last heartbeat renewal failed. Module memory only, so one stderr line marks each
+// transition (ok->failed, failed->ok) rather than one per tick. Reset by _onProxyGone/stop/_resetForTest.
+let _heartbeatFailing = false;
 
 // WP-3 (§5 D-6): CTM-side mirror of the proxy's pick table. CTM pushes the full table
 // on every delegate-pick mutation; start() replays it into a fresh child so the same
@@ -170,11 +174,14 @@ function isRunning() {
   return _mode === 'adopted' || _mode === 'adopting';
 }
 
-// ── §5 D-6: liveness in adopted mode ─────────────────────────────────────
+// ── §5 D-6/D-1: one liveness timer in BOTH modes ────────────────────────
 // 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.
+// CTM's own probe can notice the pid going away. D-6 was adopted-only; D-1 arms the SAME single timer in
+// both modes. Every tick is one authenticated admin read, and that read is what renews the proxy's own D-8
+// linger lease (docs/model-proxy-linger-without-ctm-heartbeat-2026-10-27.html D-1): the adopted tick ALSO
+// checks the pid first, and the child tick does not need to (its 'exit' event already owns that). Recovery
+// on the other side is the same _onProxyGone() handler and the same one rate-limited restart.
 
 function _clearLivenessProbe() {
   if (_livenessTimer) clearTimeout(_livenessTimer);
@@ -187,27 +194,58 @@ function _setLivenessProbeMsForTest(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.
+ * §5 D-1: does `owner` -- the identity captured when the timer was armed -- still own this module? A
+ * stop(), a fresh spawn or a newer adoption reassigns the state, and the stale tick must then do nothing.
+ */
+function _ownsProbe(owner) {
+  return (_mode === 'child' && _child === owner) || (_mode === 'adopted' && _adopted === owner);
+}
+
+/**
+ * §5 D-1: arm the ONE probe for the proxy currently owned -- the spawned child in 'child' mode, the
+ * adopted proxy in 'adopted' mode. Re-arming replaces the timer, so a call after a WP-2 handoff watches
+ * the SUCCESSOR's pid and not the predecessor's. No owner means no timer at all.
  */
 function _armLivenessProbe({ port, dataDir }) {
   _clearLivenessProbe();
-  if (_mode !== 'adopted' || !_adopted) return;
-  _livenessTimer = setTimeout(() => {
+  const owner = _mode === 'child' ? _child : (_mode === 'adopted' ? _adopted : null);
+  if (!owner) return;
+  _livenessTimer = setTimeout(async () => {
     _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 });
+    // Re-checked at fire time: a stop(), a fresh spawn or a newer adoption owns the state now.
+    if (!_ownsProbe(owner)) return;
+    // §5 D-6: only the ADOPTED identity needs a pid check -- it is the one process nothing else reports on.
+    if (_mode === 'adopted' && !instanceRecord.isProcessAlive(_adopted.pid)) {
+      _onProxyGone({ code: null, signal: ADOPTED_PID_GONE, port, dataDir });
       return;
     }
-    _onProxyGone({ code: null, signal: ADOPTED_PID_GONE, port, dataDir });
+    const pid = _ownedPid();
+    // §5 D-1: the authenticated admin read IS the lease renewal; a failed read is reported, never fatal.
+    const ok = _adminSecret ? await _probeAdminSecretImpl({ port, secret: _adminSecret }) : false;
+    _noteHeartbeat({ ok, pid });
+    if (_ownsProbe(owner)) _armLivenessProbe({ port, dataDir });
   }, _livenessProbeMs);
   // §5 D-6: a probe is never a reason for CTM to stay alive.
   _livenessTimer.unref();
 }
 
+/**
+ * §5 D-1b: report a heartbeat that stopped being answered, and one that started again -- each on its own
+ * transition only, so a long outage is one line and not one per tick. A failed renewal is NOT a death
+ * verdict: death is the child 'exit' event, or the adopted pid check above.
+ */
+function _noteHeartbeat({ ok, pid }) {
+  if (ok) {
+    if (!_heartbeatFailing) return;
+    _heartbeatFailing = false;
+    process.stderr.write(`[oauth-proxy-supervisor] proxy heartbeat recovered pid=${pid}\n`);
+    return;
+  }
+  if (_heartbeatFailing) return;
+  _heartbeatFailing = true;
+  process.stderr.write(`[oauth-proxy-supervisor] proxy heartbeat failed pid=${pid}\n`);
+}
+
 /**
  * §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
@@ -377,20 +415,42 @@ async function _performUpgradeHandoff({ port }) {
     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`);
+    const refusal = String((err && err.reason) || (err && err.message) || err).slice(0, 200);
+    process.stderr.write(`[oauth-proxy-supervisor] proxy handoff refused: ${refusal}\n`);
+    return;
+  }
+  // §5 D-2 (WP-0 AC-0d): the 202 names the successor the PREDECESSOR proved it was waiting for, and only the
+  // process answering on the wire may be published as this adoption's identity or replayed into. A probe that
+  // names anybody else -- the draining predecessor still answering a connection it accepted before the handoff,
+  // or a foreign listener that took the port -- is a bounded refusal. Nothing is thrown or killed: a throw here
+  // would fall through _finishAdoption's catch into a fresh spawn over a successor already serving this port.
+  const successorHealth = await _probeHealth(port);
+  if (!successorHealth || successorHealth.pid !== handed.successorPid) {
+    const answeringPid = successorHealth && Number.isSafeInteger(successorHealth.pid) ? successorHealth.pid : null;
+    // The TYPED refusal is `_adopted.decision` plus the line below: `_finishAdoption` is the only caller and
+    // ignores a return value, so nothing is returned that could be mistaken for success. The acknowledged
+    // successor is still named TRUTHFULLY (it is the process the predecessor handed its sockets to, and the one
+    // the liveness probe must watch), but no closure identity is published, no replay is attempted, no retry is
+    // scheduled, and no handoff timing is reported (a null handoffMs reads as an adoption, never a handoff).
+    // Fail-closed: the adopted proxy keeps serving, and nothing is killed or spawned over it.
+    _adopted = {
+      ..._adopted, pid: handed.successorPid, generation: handed.generation, handoffMs: null,
+      decision: 'upgrade-pending-unverified', closureHash: null,
+    };
+    process.stderr.write('[oauth-proxy-supervisor] proxy handoff unverified: successor_identity_mismatch'
+      + ` expected_pid=${handed.successorPid} answering_pid=${answeringPid === null ? 'none' : answeringPid}\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,
+    closureHash: successorHealth.closure_hash || 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.
@@ -464,6 +524,13 @@ function _spawnFresh({ port, resolvedDataDir }) {
   // §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();
+  // WP-1 (S-4, session-host-cgroup-survival): on a systemd service host the proxy must leave ctm.service's cgroup
+  // or a restart reaps it. Not awaited (the proxy spawns no children); failure is REPORTED, never fatal.
+  moveToOwnScope(_child.pid, { label: 'oauth-proxy' }).then((moved) => {
+    if (!moved.moved && moved.reason !== 'not-systemd' && moved.reason !== 'disabled') {
+      process.stderr.write(`[host-scope] move failed host=oauth-proxy pid=${_child && _child.pid} reason=${moved.reason}\n`);
+    }
+  });
   // 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;
@@ -477,6 +544,9 @@ function _spawnFresh({ port, resolvedDataDir }) {
     // below is the authoritative signal, not this write.
     _lastError = `admin secret handoff failed: ${err.message}`;
   }
+  // §5 D-1a: arm the lease-renewal probe for THIS child, exactly as the adopted path arms its own. Armed
+  // after the secret write so the first tick already has a secret to authenticate with.
+  _armLivenessProbe({ port, dataDir: resolvedDataDir });
   _startedAt = Date.now();
   child.on('error', (err) => {
     _lastError = err.message;
@@ -509,7 +579,11 @@ function _onProxyGone({ code, signal, port, dataDir }) {
   // 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;
+  // §5 D-2: the pid the exit line names, captured before the state reset below.
+  const gonePid = _child ? _child.pid : adoptedPid;
   _clearLivenessProbe();
+  // §5 D-1b: the next identity starts with a clean heartbeat verdict.
+  _heartbeatFailing = false;
   if (adoptedPid !== null) {
     process.stderr.write(`[oauth-proxy-supervisor] adopted proxy pid=${adoptedPid} gone\n`);
     instanceRecord.unlinkInstanceRecord({ dataDir });
@@ -526,16 +600,21 @@ function _onProxyGone({ code, signal, port, dataDir }) {
   // 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) {
+  // §5 D-2: with D-1 keeping the lease renewed, a linger under a live CTM is already a bug -- so a clean
+  // code-0 exit nobody asked for is reported as what it is (and recovered below like any other exit).
+  if (!wasStopping && code === 0 && !signal) {
+    _lastError = 'exited code=0 unrequested';
+    process.stderr.write(`[oauth-proxy-supervisor] proxy pid=${gonePid} exited code=0 without stop()\n`);
+  }
+  // WP-0 (§6.2) + §5 D-2: ANY exit stop() did not ask for -- clean or not -- 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.
+  if (!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,
@@ -552,6 +631,8 @@ function stop() {
   const mode = _mode;
   // §5 D-6: whatever happens below, this CTM is no longer watching that pid.
   _clearLivenessProbe();
+  // §5 D-1b: a stopped CTM has no heartbeat verdict to carry into the next start().
+  _heartbeatFailing = false;
   if (!isRunning()) {
     _adminSecret = null;
     _activeChildDataDir = null;
@@ -615,11 +696,10 @@ async function status({ port = DEFAULT_PORT } = {}) {
   }
   let health = null;
   try {
-    const resp = await fetch(`http://127.0.0.1:${port}/_health`, {
-      signal: AbortSignal.timeout(2000),
-    });
-    if (resp.ok) health = await resp.json();
+    health = await _controlHealth(port, { signal: AbortSignal.timeout(2000) });
   } catch (err) {
+    // §5 D-1: unchanged meaning -- only a network/protocol failure lands here; an unsuccessful status is a
+    // null health that leaves `_lastError` alone, and the helper releases its body either way.
     _lastError = `health probe failed: ${err.message}`;
   }
   // Never include the admin secret here — status() is a diagnostics surface
@@ -695,11 +775,41 @@ function hasLiveSurvivor({ port = DEFAULT_PORT, dataDir } = {}) {
   return !!record && record.port === port && instanceRecord.isProxyProcess(record.pid);
 }
 
+// §5 D-1 (WP-0 AC-0b, docs/native-owner-restart-handoff-2026-10-26.html): every supervisor CONTROL request is
+// one-use. Fetch's `keepalive:false` is unrelated; the HTTP `Connection: close` header is what undici honours
+// by giving the request its own closed-when-done connection. Without it the pool can hand a later control
+// request the socket opened against the PREDECESSOR, which stops ACCEPTING on a handoff but keeps answering
+// connections it already accepted (`closeIdleConnections()` cannot close one still serving the handoff
+// response). INFERENCE, not packet-level observation: that reuse is how the native-owner replay lands in the
+// draining process while the successor holding the port never learns the owner -- what the live 00:47:11Z
+// `native_lead_listener_closed` + 401 `native_owner_unknown` sequence looks like outside, reproduced in
+// `.scratch/native-owner/socket-handoff.cjs`. Lifecycle traffic only: no dispatcher, flag or retry.
+const CONTROL_HEADERS = Object.freeze({ connection: 'close' });
+
+// §5 D-1: release the body of a control response this call is not going to read, so neither a reader nor
+// its socket outlives the call. Already-consumed bodies and 204/304 (`body` null) are simply nothing to do.
+async function _releaseControlResponse(resp) {
+  if (!resp || !resp.body || resp.bodyUsed) return;
+  try { await resp.body.cancel(); } catch { /* expected: consumed, already cancelled, or the peer is gone */ }
+}
+
+// §5 D-1: the `/_health` control request shared by the two callers wanting its parsed body (`_probeHealth`,
+// `status()`). A non-ok status answers `null`; a dead proxy or malformed body THROWS, so each caller keeps its
+// own meaning for that failure (a refused adoption, or `status()`'s `_lastError`).
+async function _controlHealth(port, init) {
+  let resp = null;
+  try {
+    resp = await fetch(`http://127.0.0.1:${port}/_health`, { headers: CONTROL_HEADERS, ...init });
+    return resp.ok ? await resp.json() : null;
+  } finally {
+    await _releaseControlResponse(resp);
+  }
+}
+
 /** §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;
+    return await _controlHealth(port, { signal: AbortSignal.timeout(timeoutMs) });
   } catch (err) {
     // expected: an unreachable proxy is a refused adoption, never a thrown boot
     void err;
@@ -711,9 +821,10 @@ async function _probeHealth(port, timeoutMs = 2000) {
 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 },
+      headers: { ...CONTROL_HEADERS, [ADMIN_HEADER]: secret },
       signal: AbortSignal.timeout(timeoutMs),
     });
+    await _releaseControlResponse(resp);
     return resp.ok;
   } catch (err) {
     // expected: an unreachable proxy cannot confirm the secret; the caller falls back to a spawn
@@ -722,6 +833,14 @@ async function _probeAdminSecret({ port, secret, timeoutMs = 2000 }) {
   }
 }
 
+// §6 test seam: the D-1 renewal request itself. Injectable so a case can count heartbeats without touching
+// the proxy. Production never calls the setter; _resetForTest restores it.
+let _probeAdminSecretImpl = _probeAdminSecret;
+
+function _setProbeAdminSecretForTest(fn) {
+  _probeAdminSecretImpl = typeof fn === 'function' ? fn : _probeAdminSecret;
+}
+
 // ── 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
@@ -757,8 +876,10 @@ async function _pollHealth({ port = DEFAULT_PORT, timeoutMs = 2000, signal } = {
     const probeTimeout = Math.max(1, Math.min(500, remaining));
     try {
       const resp = await fetch(`http://127.0.0.1:${port}/_health`, {
+        headers: CONTROL_HEADERS,
         signal: signal ? AbortSignal.any([AbortSignal.timeout(probeTimeout), signal]) : AbortSignal.timeout(probeTimeout),
       });
+      await _releaseControlResponse(resp);
       if (resp.ok) return true;
     } catch {
       // expected: connection refused during cold start, or the probe's own
@@ -787,6 +908,7 @@ async function _adminRequest({ port = DEFAULT_PORT, method, path: adminPath, bod
     resp = await fetch(`http://127.0.0.1:${port}${adminPath}`, {
       method,
       headers: {
+        ...CONTROL_HEADERS,
         'Content-Type': 'application/json',
         [ADMIN_HEADER]: _adminSecret,
       },
@@ -802,6 +924,7 @@ async function _adminRequest({ port = DEFAULT_PORT, method, path: adminPath, bod
     if (returnHttpErrors) {
       let errorBody = null;
       try { errorBody = await resp.json(); } catch { /* expected: an empty or non-JSON rejection */ }
+      await _releaseControlResponse(resp);
       return errorBody && typeof errorBody === 'object'
         ? { ...errorBody, http_status: resp.status }
         : { error: 'admin_request_failed', http_status: resp.status };
@@ -814,13 +937,18 @@ async function _adminRequest({ port = DEFAULT_PORT, method, path: adminPath, bod
       // expected: a non-JSON error body (e.g. plain 401 text) — the status-based
       // reason above is enough.
     }
+    await _releaseControlResponse(resp);
     throw new ProxyAdminError('admin_request_failed', reason);
   }
   const len = resp.headers.get('content-length');
-  if (resp.status === 204 || len === '0') return null;
+  if (resp.status === 204 || len === '0') {
+    await _releaseControlResponse(resp);
+    return null;
+  }
   try {
     return await resp.json();
   } catch {
+    await _releaseControlResponse(resp);
     return null;
   }
 }
@@ -1035,7 +1163,7 @@ function _leadEntryKey(entry) {
     nativeCertFingerprint: native ? (entry.nativeCertFingerprint || null) : null,
     // The public settings locator is identity for the same reason: the same token may not silently start
     // pointing at a different reserved directory.
-    nativeSettingsRef: native ? (entry.nativeSettingsRef || null) : null,
+    nativeSettingsRef: native ? (entry.nativeSettingsRef || null) : null, usageLog: entry.usageLog || null, // WP-9 L-2: the usage mark is identity
   });
 }
 
@@ -1057,14 +1185,14 @@ async function _flushPendingLeadRevokes({ port = DEFAULT_PORT } = {}) {
 
 function _normalizeLeadRegistration({ ctmSessionId, aliases, bindings, processGeneration, transitionId,
   purpose = 'routed-primary', delegateScope = false, harness, providerThreadId, nativeTransport,
-  nativeCertFingerprint, nativeSettingsRef } = {}) {
+  nativeCertFingerprint, nativeSettingsRef, usageLog } = {}) {
   if (typeof ctmSessionId !== 'string' || !SAFE_LEAD_OWNER_ID.test(ctmSessionId)
       || !Array.isArray(aliases) || aliases.length === 0 || aliases.length > 64
       || aliases.some((alias) => !_safeLeadDeploymentId(alias))
       || new Set(aliases).size !== aliases.length
       || !Number.isSafeInteger(processGeneration) || processGeneration < 1
       || typeof delegateScope !== 'boolean') return null;
-  if (purpose !== 'routed-primary' && purpose !== 'native-claude-passthrough') return null;
+  if (purpose !== 'routed-primary' && purpose !== 'native-claude-passthrough') return null; if (usageLog != null && (usageLog !== 'dsh' || purpose !== 'routed-primary')) return null; // WP-9 L-2 (D-19): dsh usage mark, routed leads only
   if (nativeTransport != null && !LEAD_NATIVE_TRANSPORTS.includes(nativeTransport)) return null;
   if (nativeCertFingerprint != null
       && (typeof nativeCertFingerprint !== 'string' || !LEAD_NATIVE_CERT_FINGERPRINT_RE.test(nativeCertFingerprint))) return null;
@@ -1116,7 +1244,7 @@ function _normalizeLeadRegistration({ ctmSessionId, aliases, bindings, processGe
   if (providerThreadId != null && (typeof providerThreadId !== 'string' || !SAFE_LEAD_OWNER_ID.test(providerThreadId))) return null;
   return { ctmSessionId, aliases: [...aliases], bindings: normalizedBindings, processGeneration,
     purpose, delegateScope, ...(normalizedHarness ? { harness: normalizedHarness } : {}), ...(providerThreadId ? { providerThreadId } : {}),
-    ...(transitionId != null ? { transitionId } : {}) };
+    ...(transitionId != null ? { transitionId } : {}), ...(usageLog ? { usageLog } : {}) };
 }
 
 async function registerLeadToken(registration = {}) {
@@ -1332,14 +1460,14 @@ async function probeRoute(alias, { timeoutMs = 2000, port = DEFAULT_PORT, signal
 // Generation readiness is stronger than probeRoute() reachability: it sends one fixed,
 // minimal inference through the provider's configured wire and returns the proxy's
 // normalized receipt. Admission release remains a caller responsibility.
-async function probeRouteGeneration(alias, { model, timeoutMs = 30_000, port = DEFAULT_PORT } = {}) {
+async function probeRouteGeneration(alias, { model, timeoutMs = 30_000, port = DEFAULT_PORT, face } = {}) {
   const requestedTimeout = Number(timeoutMs);
   const cappedTimeout = Math.max(1, Math.min(Number.isFinite(requestedTimeout) && requestedTimeout > 0 ? requestedTimeout : 30_000, 30_000));
   return _adminRequest({
     port,
     method: 'POST',
     path: `/_admin/routes/${encodeURIComponent(alias)}/generation-probe`,
-    body: { model, timeoutMs: cappedTimeout },
+    body: { model, timeoutMs: cappedTimeout, ...(typeof face === 'string' ? { face } : {}) },
     timeoutMs: cappedTimeout + 1000,
     returnHttpErrors: true,
   });
@@ -1364,8 +1492,10 @@ function _resetForTest() {
   _pendingLeadRevokes.clear();
   _leadWorkerPicks = [];
   _hashClosureFiles = hashClosureFiles;
+  _probeAdminSecretImpl = _probeAdminSecret;
   _clearLivenessProbe();
   _livenessProbeMs = PROXY_LIVENESS_MS;
+  _heartbeatFailing = false;
 }
 
 module.exports = {
@@ -1411,6 +1541,13 @@ module.exports = {
     // §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-1/D-1b (§6): the armed timer (read-only) and the renewal request the probe sends, so a case can
+    // assert one timer is ever armed and count heartbeats without touching the proxy. Production never
+    // calls the setter; the real implementation is exported beside it so a wrapper can call through.
+    get _livenessTimer() { return _livenessTimer; },
+    get _heartbeatFailing() { return _heartbeatFailing; },
+    _probeAdminSecret,
+    _setProbeAdminSecretForTest,
     // §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,

package/template/coding-task-manager/lib/online-backup-worker-client.js

@@ -13,6 +13,7 @@ function workerError(payload) {
 function createOnlineBackupRunner(options = {}) {
   const getDbPath = options.getDbPath;
   const getBackupDir = options.getBackupDir;
+  const getRetentionDays = options.getRetentionDays;
   const WorkerClass = options.WorkerClass || Worker;
   const workerPath = options.workerPath || path.join(__dirname, '..', 'workers', 'online-backup-worker.js');
   const timeoutMs = Math.max(1000, Number(options.timeoutMs || 15 * 60 * 1000));
@@ -46,6 +47,7 @@ function createOnlineBackupRunner(options = {}) {
           dbPath,
           backupDir,
           label: String(meta.label || 'manual'),
+          retentionDays: typeof getRetentionDays === 'function' ? Number(getRetentionDays()) : undefined,
         },
         env: { ...process.env },
       });