create-walle 0.10.1 → 0.10.2

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

@@ -0,0 +1,200 @@
+'use strict';
+
+// §5 D-7 / §6 (docs/model-proxy-survives-ctm-restart-2026-10-22.html): the CLI half of oauth-proxy.js.
+// It lives here so oauth-proxy.js stays inside its hard 1500-line ceiling, and nothing in this file is
+// reachable from an embedded start() -- only from `node oauth-proxy.js`.
+//
+// Two ways in, distinguished by ONE thing: whether there is an IPC channel.
+//   * the supervisor spawns the proxy with the admin secret on STDIN (WP-0 §5 D-4): read one line, start
+//     serving, and the secret is only ever used for the loopback admin calls above;
+//   * a PREDECESSOR performing an upgrade handoff (§5 D-7) spawns it with an `ipc` channel and no stdin
+//     at all (`stdio: ['ignore', logFd, logFd, 'ipc']`): the three `handoff/v1*` messages carry the two
+//     listening sockets, the admin secret and the memory-only token state, and this process is the
+//     SUCCESSOR. It publishes its own identity and answers `ready` -- the predecessor stops accepting
+//     only after that answer, which is why the answer is sent from start(), not from here.
+
+const readline = require('node:readline');
+
+const LOOPBACK_HOST = '127.0.0.1';
+const LOOPBACK_REFUSAL_EXIT_CODE = 78;
+const STARTUP_FAILURE_EXIT_CODE = 1;
+const SIGTERM_EXIT_CODE = 143;
+
+// Test seam (§6, AC-2b): truthy => the successor does everything a successor does EXCEPT send `ready`, so
+// a test can observe the predecessor's bounded wait from outside both processes. It is read through a
+// local `env` binding -- the shape lib/hermetic-agent-launch-guard.js uses for its own test-only
+// switches -- and it reaches a successor because the supervisor's `childEnv = { ...process.env }` and the
+// predecessor's `env: process.env` both pass it through. There is no operator flag here.
+function _holdReadyFlag(env = process.env) {
+  return String(env.CTM_TEST_HANDOFF_SUCCESSOR_HOLD_READY || '') === '1';
+}
+
+/**
+ * §5 D-8 test seam: the CLI is the ONLY caller that arms the proxy's own linger timer, and this is its
+ * idle window. It is read through a local `env` binding, exactly like `_holdReadyFlag` above, so a child
+ * spawned by a test can be observed leaving its window in about a second instead of fifteen minutes; the
+ * production value comes from handoff.js (`PROXY_LINGER_MS`, === HOST_LINGER_MS). No operator flag, and
+ * no production path ever sets this.
+ */
+function _lingerMsFlag(env = process.env, handoff) {
+  const raw = Number(env.CTM_TEST_PROXY_LINGER_MS);
+  return Number.isSafeInteger(raw) && raw > 0 ? raw : handoff.PROXY_LINGER_MS;
+}
+
+/** D-1: the CLI's bind host, resolved once from the environment exactly as it always was. */
+function _resolveHost(env = process.env) {
+  const raw = env.OAUTH_PROXY_HOST;
+  return typeof raw === 'string' && raw.length > 0 ? raw : LOOPBACK_HOST;
+}
+
+// ── D-4 stdin secret (CLI mode only) ────────────────────────────────────
+// Reads exactly one line from stdin at process start. Never env, never argv.
+// Resolves null (no admin secret; admin endpoints stay locked) if stdin is a
+// TTY or closes without producing a line.
+function _readAdminSecretFromStdin() {
+  return new Promise((resolve) => {
+    if (!process.stdin || process.stdin.isTTY) {
+      resolve(null);
+      return;
+    }
+    const rl = readline.createInterface({ input: process.stdin, terminal: false });
+    let resolved = false;
+    const finish = (value) => {
+      if (resolved) return;
+      resolved = true;
+      rl.close();
+      resolve(value);
+    };
+    rl.once('line', (line) => finish((line || '').trim() || null));
+    rl.once('close', () => finish(null));
+  });
+}
+
+/**
+ * §9 S-5: record the exit, say it once, then leave. Semantics are unchanged -- nothing drains, and
+ * 128+15 keeps the supervisor's `code !== 0` classification of a SIGTERM exactly as it is today.
+ */
+function _installSigtermHandler({ startedContext, streamAccountingMod, instanceRecord, handoff }) {
+  process.on('SIGTERM', () => {
+    const ctx = startedContext();
+    if (!ctx) {
+      process.exit(SIGTERM_EXIT_CODE);
+      return;
+    }
+    const openStreams = ctx.streamAccounting.count();
+    // §5 D-5: an explicit stop leaves no record, so the next boot spawns rather than adopts. A
+    // PREDECESSOR that is draining a handoff is the one exception: the record on disk already names its
+    // successor, and removing it would take the live proxy out of the next boot's reach.
+    if (!handoff.isDraining()) instanceRecord.unlinkInstanceRecord({ dataDir: ctx.dataDir });
+    streamAccountingMod.writeExitRecord({ dataDir: ctx.dataDir, reason: 'SIGTERM', openStreams })
+      .catch((err) => {
+        // REPORT: the exit code below still classifies this stop, so a failed write is not fatal.
+        console.error(`[model-proxy] exit record not written: ${(err && err.code) || 'unknown'}`);
+      })
+      .then(() => {
+        console.log(`[model-proxy] exit reason=SIGTERM open_streams=${openStreams}`);
+        process.exit(SIGTERM_EXIT_CODE);
+      });
+  });
+}
+
+/**
+ * The CLI entry point, called by oauth-proxy.js's `require.main === module` block with its own
+ * dependencies injected (so this module never requires oauth-proxy.js back).
+ *
+ * @param {object} input
+ * @param {Function} input.start oauth-proxy.js's start()
+ * @param {object} input.streamAccountingMod lib/model-proxy/stream-accounting.js
+ * @param {object} input.instanceRecord lib/model-proxy/proxy-instance-record.js
+ * @param {object} input.handoff lib/model-proxy/handoff.js
+ * @param {Function} [input.startedContext] getter for the context of the server this process started
+ * @param {string} [input.loopbackErrorCode] the named refusal code start() rejects with
+ */
+function run({
+  start,
+  streamAccountingMod,
+  instanceRecord,
+  handoff,
+  startedContext = () => null,
+  loopbackErrorCode = 'EBIND_NOT_LOOPBACK',
+} = {}) {
+  const host = _resolveHost();
+  if (host !== LOOPBACK_HOST) {
+    // D-1: refuse before ever touching stdin, so a bad --host/env doesn't hang waiting for an admin
+    // secret that will never matter.
+    console.error(`[oauth-proxy] ${loopbackErrorCode}: refusing to bind to "${host}" — must be 127.0.0.1 (D-1)`);
+    process.exit(LOOPBACK_REFUSAL_EXIT_CODE);
+    return;
+  }
+  const successor = typeof process.send === 'function';
+  const startup = successor
+    // §5 D-7: the successor never reads stdin -- its secret and its data directory arrive in the
+    // handoff message, and its listener is a socket it did not open.
+    ? handoff.receiveInheritance().then((received) => ({
+      host,
+      adminSecret: received.inherited.adminSecret,
+      dataDir: received.inherited.dataDir,
+      inherited: { ...received.inherited, state: received.state, holdReady: _holdReadyFlag() },
+    }))
+    // A TTY, or stdin closing before a line arrived, is not a failure: the process simply serves with no
+    // admin secret, and its admin surface stays locked. The read itself already resolves null in both of
+    // those cases, so this tail exists only for an unexpected readline error.
+    : _readAdminSecretFromStdin()
+      .catch((/* expected: no line on stdin -- start with no admin secret rather than not at all */) => null)
+      .then((adminSecret) => ({ host, adminSecret }));
+
+  startup
+    // §5 D-8: `lingerMs` is what makes THIS process (and only this one: an embedded start() passes none)
+    // leave on its own once CTM has been gone for a full window.
+    .then((args) => start({ ...args, lingerMs: _lingerMsFlag(process.env, handoff) }))
+    .then(() => {
+      if (successor) {
+        // §5 D-7: the successor outlives the predecessor that spawned it, so the channel it was born
+        // with must never be what keeps it alive -- nor may its closure end it. `ready` is already sent.
+        try {
+          process.channel.unref();
+        } catch (err) {
+          // expected: nothing to detach when this process has no channel state left to manage.
+          void err;
+        }
+      }
+      _installSigtermHandler({ startedContext, streamAccountingMod, instanceRecord, handoff });
+    })
+    .catch((err) => {
+      if (err && err.code === loopbackErrorCode) {
+        console.error(`[oauth-proxy] ${err.code}: ${err.message}`);
+        process.exit(LOOPBACK_REFUSAL_EXIT_CODE);
+        return;
+      }
+      console.error('[oauth-proxy] failed to start:', err.message);
+      process.exit(STARTUP_FAILURE_EXIT_CODE);
+    });
+}
+
+/**
+ * The `require.main === module` entry: oauth-proxy.js calls exactly this, so its own CLI seams
+ * (start, the accounting/record modules, the SIGTERM context) do not have to be spelled out at the bottom
+ * of a file that is at its hard line ceiling. The require is deferred to call time, so loading THIS module
+ * never loads oauth-proxy.js back -- and when the proxy is its own main, this module is loaded from
+ * inside that same evaluation, by which point oauth-proxy.js's exports are complete.
+ */
+function runCli() {
+  const proxy = require('../../oauth-proxy.js');
+  return run({
+    start: proxy.start,
+    streamAccountingMod: require('./stream-accounting'),
+    instanceRecord: require('./proxy-instance-record'),
+    handoff: require('./handoff'),
+    startedContext: proxy._startedContext,
+    loopbackErrorCode: proxy.EBIND_NOT_LOOPBACK,
+  });
+}
+
+module.exports = {
+  run,
+  runCli,
+  _readAdminSecretFromStdin,
+  _holdReadyFlag,
+  _lingerMsFlag,
+  _resolveHost,
+};

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

@@ -0,0 +1,257 @@
+'use strict';
+
+// §5 D-1/D-2/D-3 + §6 (docs/model-proxy-survives-ctm-restart-2026-10-22.html): the durable identity of a
+// LIVE model proxy, and the four paths it lives on. The supervisor binds the child's stdout/stderr to
+// proxyLogPath() (the proxy never writes into a CTM-owned pipe -- incident 7: an orphaned child dies on
+// its second write with EPIPE); the child publishes instance.json after listen and removes it on an
+// explicit stop; CTM writes the per-spawn admin secret BEFORE the spawn, so a CTM that dies between the
+// spawn and its own exit still leaves a readable secret for the next boot -- which is also the CTM that
+// adopts the survivor (§5 D-4). Both processes must agree on these paths byte-for-byte, so they are
+// defined once, here.
+//
+// Publications are atomic in the shape lib/host-registry.js uses (a nonce-scoped tmp file created with
+// flag 'wx' and mode 0600, renamed over the final path), and the directory is 0700 -- the same tree the
+// native mTLS authority already lives in. The same 0600 secret authenticates loopback admin calls only;
+// nothing here is a transport credential.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { computeClosure } = require('../host-closure-hash');
+
+// lib/host-closure-hash.js resolves its own default repo root from ITS __dirname (coding-task-manager/lib
+// -> the repo root). This module sits one level deeper, so the same root is re-stated explicitly: the
+// file list the PROXY hashes and the file list CTM hashes from disk must name the same files.
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+const RECORD_VERSION = 1;
+const PROXY_PROTOCOL = 'proxy-v1';
+const PROXY_FLOOR_VERSION = 0;
+const PROXY_SCRIPT_NAME = 'oauth-proxy.js';
+// §5 D-1: one generation of log is kept. 203,900 request lines in 26 days is ~1.5 MB/day, so ~40 days
+// per generation; the rotation is a rename, not a truncation, so the previous generation stays readable.
+const LOG_ROTATE_BYTES = 64 * 1024 * 1024;
+const LOG_ROTATE_SUFFIX = '.1';
+const PS_TIMEOUT_MS = 2000;
+
+function proxyDir(dataDir) {
+  return path.join(dataDir, 'oauth-proxy');
+}
+
+function instanceRecordPath(dataDir) {
+  return path.join(proxyDir(dataDir), 'instance.json');
+}
+
+function adminSecretPath(dataDir) {
+  return path.join(proxyDir(dataDir), 'admin-secret');
+}
+
+function proxyLogPath(dataDir) {
+  return path.join(proxyDir(dataDir), 'oauth-proxy.log');
+}
+
+// 0700, created on demand. Synchronous because the spawn-time log descriptor below needs the directory to
+// exist before the child does; one call per spawn and one per publication, never a request path.
+function ensureProxyDir(dataDir) {
+  const dir = proxyDir(dataDir);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+function _writeAtomic0600Sync(target, text) {
+  const tmp = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(tmp, text, { mode: 0o600, flag: 'wx' });
+  fs.renameSync(tmp, target);
+  return target;
+}
+
+function _unlinkQuiet(target) {
+  try {
+    fs.unlinkSync(target);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return false;
+    // REPORT: a file that cannot be removed is stale truth on disk; the caller's decision still stands.
+    process.stderr.write(`[model-proxy] record not removed: ${path.basename(target)} ${(err && err.code) || 'unknown'}\n`);
+    return false;
+  }
+}
+
+/**
+ * §5 D-2: the record the proxy publishes after listen. Written before the first request is answered, so
+ * a CTM that restarts immediately afterwards still finds the exact identity of what is listening.
+ * @returns {object} the record written
+ */
+function writeInstanceRecord({ dataDir, record }) {
+  ensureProxyDir(dataDir);
+  _writeAtomic0600Sync(instanceRecordPath(dataDir), `${JSON.stringify(record)}\n`);
+  return record;
+}
+
+/**
+ * §5 D-3/D-2: compute this process's loaded-code hash ONCE, publish the record, and hand the same two
+ * fields to the accounting the /_health answer reports from -- so identity and the published record can
+ * never describe different code. §5 D-7 (WP-2): a handoff successor publishes `generation: n+1` and the
+ * predecessor it took over from, so the record names the LIVE socket owner and who handed it over.
+ */
+function publishInstanceRecord({ dataDir, port, nativePort = null, accounting = null, generation = 1, predecessorPid = null }) {
+  const { closureHash, closureFiles } = computeClosure({ repoRoot: REPO_ROOT });
+  const record = writeInstanceRecord({
+    dataDir,
+    record: {
+      v: RECORD_VERSION,
+      pid: process.pid,
+      port,
+      nativePort,
+      protocol: PROXY_PROTOCOL,
+      floorVersion: PROXY_FLOOR_VERSION,
+      closureHash,
+      closureFiles,
+      generation,
+      predecessorPid,
+      startedAt: new Date().toISOString(),
+      draining: false,
+    },
+  });
+  if (accounting && typeof accounting.setIdentity === 'function') {
+    accounting.setIdentity({ closureHash, closureFiles, generation, draining: false });
+  }
+  return record;
+}
+
+/**
+ * §5 D-7 step 2: rewrite the published record in place with one patch (today: `draining`). Written
+ * BEFORE the successor is spawned, so a predecessor that dies mid-handoff leaves a truthful record --
+ * and rewritten with `draining:false` on any abort, because the predecessor kept serving.
+ * @returns {object|null} the rewritten record, or null when this process published none
+ */
+function updateInstanceRecord({ dataDir, patch }) {
+  const current = readInstanceRecord({ dataDir });
+  if (!current) return null;
+  return writeInstanceRecord({ dataDir, record: { ...current, ...patch } });
+}
+
+/**
+ * @returns {object|null} the published record, or null when there is none. A truncated, hand-edited or
+ * unusable record is reported as absent AND removed: writes are atomic via rename, so it can only be
+ * leftover garbage, and leaving it behind would make the next boot re-read the same lie.
+ */
+function readInstanceRecord({ dataDir }) {
+  let raw;
+  try {
+    raw = fs.readFileSync(instanceRecordPath(dataDir), 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null; // expected: no proxy has published one
+    throw err;
+  }
+  try {
+    const record = JSON.parse(raw);
+    if (record && typeof record === 'object' && Number.isSafeInteger(record.pid) && record.pid > 0) return record;
+  } catch {
+    // expected: an unparseable record is not evidence -- fall through and remove it
+  }
+  unlinkInstanceRecord({ dataDir });
+  return null;
+}
+
+function unlinkInstanceRecord({ dataDir }) {
+  return _unlinkQuiet(instanceRecordPath(dataDir));
+}
+
+/** §5 D-2: written before each fresh spawn, read back when CTM adopts a proxy it did not spawn. */
+function writeAdminSecret({ dataDir, secret }) {
+  ensureProxyDir(dataDir);
+  _writeAtomic0600Sync(adminSecretPath(dataDir), `${String(secret)}\n`);
+  return secret;
+}
+
+/** @returns {string|null} the current secret, or null when there is none to authenticate with. */
+function readAdminSecret({ dataDir }) {
+  let raw;
+  try {
+    raw = fs.readFileSync(adminSecretPath(dataDir), 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null; // expected: this CTM never spawned a proxy here
+    throw err;
+  }
+  const secret = raw.trim();
+  return secret || null;
+}
+
+function unlinkAdminSecret({ dataDir }) {
+  return _unlinkQuiet(adminSecretPath(dataDir));
+}
+
+/**
+ * §5 D-1: the descriptor the child's stdout and stderr are bound to. One synchronous open per spawn
+ * (never a request path), rotating one generation at 64 MiB first: every proxy generation passes through
+ * this spawn, including WP-2's handoff successor, so this is the one place rotation has to happen.
+ */
+function openProxyLogFd(dataDir) {
+  ensureProxyDir(dataDir);
+  const target = proxyLogPath(dataDir);
+  const fd = fs.openSync(target, 'a');
+  if (fs.fstatSync(fd).size <= LOG_ROTATE_BYTES) return fd;
+  fs.closeSync(fd);
+  fs.renameSync(target, `${target}${LOG_ROTATE_SUFFIX}`);
+  return fs.openSync(target, 'a');
+}
+
+/** The supervisor's own copy of the descriptor; the child holds its own. */
+function closeProxyLogFd(fd) {
+  try {
+    fs.closeSync(fd);
+  } catch (err) {
+    // expected: a descriptor that is already closed costs nothing -- the child has its own copy
+    void err;
+  }
+}
+
+/** §5 D-4: is this pid a live proxy? `ps` is the authority -- a recycled pid must never be signalled. */
+function isProxyProcess(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false;
+  try {
+    return execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8', timeout: PS_TIMEOUT_MS })
+      .includes(PROXY_SCRIPT_NAME);
+  } catch (err) {
+    // expected: ps exits non-zero for a pid that is gone, and a failed probe is never a proxy
+    void err;
+    return false;
+  }
+}
+
+/** D-4 step 1: `process.kill(pid, 0)` -- EPERM means alive but not ours, which is still alive. */
+function isProcessAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+}
+
+module.exports = {
+  RECORD_VERSION,
+  PROXY_PROTOCOL,
+  PROXY_FLOOR_VERSION,
+  LOG_ROTATE_BYTES,
+  proxyDir,
+  instanceRecordPath,
+  adminSecretPath,
+  proxyLogPath,
+  ensureProxyDir,
+  publishInstanceRecord,
+  updateInstanceRecord,
+  writeInstanceRecord,
+  readInstanceRecord,
+  unlinkInstanceRecord,
+  writeAdminSecret,
+  readAdminSecret,
+  unlinkAdminSecret,
+  openProxyLogFd,
+  closeProxyLogFd,
+  isProxyProcess,
+  isProcessAlive,
+};

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

@@ -0,0 +1,205 @@
+'use strict';
+
+// §5 D-9 / §9 S-5, S-8: how many requests this proxy is still carrying, and what it was carrying when
+// it last stopped. Both truths live here on purpose -- the exit record is nothing but the counter read
+// at exit, and a second copy of that number is exactly how the two would drift apart.
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+// The health probe is itself a request, so counting it would make the counter unobservable from the one
+// surface that reports it (the probe would always see its own 1). Only these two status paths are
+// exempt; every other path is counted, keep-alive or not.
+const UNCOUNTED_PATHS = new Set(['/_health', '/_status']);
+
+const EXIT_RECORD_VERSION = 1;
+
+function _pathOf(url) {
+  const raw = String(url || '');
+  const cut = raw.indexOf('?');
+  return cut === -1 ? raw : raw.slice(0, cut);
+}
+
+/**
+ * The process's own in-flight stream counter.
+ *
+ * @param {{startedAt?: string}} [options] `startedAt` is overridable only so a test can pin it.
+ */
+function createStreamAccounting({ startedAt = new Date().toISOString() } = {}) {
+  let openStreams = 0;
+  // §5 D-3: the loaded-code hash this process published, set ONCE after listen by
+  // proxy-instance-record.publishInstanceRecord(). Read here so the /_health answer and the on-disk
+  // record can never describe different code; null until then (a start that never binds publishes none).
+  // §5 D-7 (WP-2): `generation` and `draining` travel the same way -- the successor of a handoff is
+  // generation N+1 and says so on /_health while its predecessor is still draining.
+  let identity = null;
+  // §5 D-7 step 7: the drain ends when this counter reaches zero, so the DECREMENT is what notifies --
+  // there is no polling loop and no second copy of the count.
+  const idleWaiters = new Set();
+
+  function _notifyIdle() {
+    const waiters = [...idleWaiters];
+    idleWaiters.clear();
+    for (const waiter of waiters) {
+      try {
+        waiter();
+      } catch (err) {
+        // REPORT: a drain waiter that throws is not the counter's problem; the drain deadline owns the
+        // fallback, so the failure is worth one line and nothing else.
+        process.stderr.write(`[model-proxy] drain waiter failed: ${(err && err.message) || 'unknown'}\n`);
+      }
+    }
+  }
+
+  return {
+    /**
+     * Count every request this server is still answering. An idle keep-alive SOCKET carries no request
+     * and is never counted; a request is in flight until its response emits 'close' (whether it
+     * completed, errored or was cut by the client).
+     */
+    track(server) {
+      server.on('request', (req, res) => {
+        if (UNCOUNTED_PATHS.has(_pathOf(req.url))) return;
+        openStreams += 1;
+        res.once('close', () => {
+          openStreams -= 1;
+          if (openStreams === 0) _notifyIdle();
+        });
+      });
+    },
+    count() {
+      return openStreams;
+    },
+    snapshot() {
+      return { openStreams, startedAt, identity };
+    },
+    /** §5 D-3: the code this process loaded, published once; what /_health reports from. */
+    setIdentity(next) {
+      identity = next
+        ? {
+          closureHash: next.closureHash || null,
+          closureFiles: Array.isArray(next.closureFiles) ? next.closureFiles : [],
+          generation: Number.isSafeInteger(next.generation) && next.generation > 0 ? next.generation : 1,
+          draining: next.draining === true,
+        }
+        : null;
+    },
+    /** §5 D-7 step 8: the predecessor answers /_health with draining:true from here until it exits. */
+    setDraining(value) {
+      const current = identity || { closureHash: null, closureFiles: [], generation: 1, draining: false };
+      identity = { ...current, draining: value === true };
+    },
+    /**
+     * §5 D-7 step 7: called ONCE by the handoff drain, on the decrement that brings the count to zero.
+     * @returns {Function} unsubscribe, so a drain that was already forced does not hold a callback
+     */
+    onIdle(callback) {
+      idleWaiters.add(callback);
+      return () => idleWaiters.delete(callback);
+    },
+  };
+}
+
+/**
+ * §9 S-8: the process-identity fields the `/_health` answer reports alongside its existing ones. The
+ * count is read live, never cached, so the answer can never describe an earlier moment. `generation`
+ * and `draining` come from the published identity (a handoff successor is generation N+1 and reports
+ * `draining:true` while its predecessor drains); a process that published none reports today's
+ * 1/false.
+ */
+function healthFields(accounting) {
+  const snapshot = accounting.snapshot();
+  const identity = snapshot.identity || {};
+  return {
+    pid: process.pid,
+    generation: identity.generation || 1,
+    protocol: 'proxy-v1',
+    floor_version: 0,
+    open_streams: snapshot.openStreams,
+    draining: identity.draining === true,
+    started_at: snapshot.startedAt,
+    // §5 D-3: what CTM compares against its own disk hash to decide adopt vs hand off.
+    closure_hash: identity.closureHash || null,
+    closure_files: identity.closureFiles || [],
+  };
+}
+
+/**
+ * §9 S-8: the health fields merged into whatever JSON body the responder writes. The relay keeps
+ * ownership of its own five fields (unchanged, names and types); this only adds what D-9/S-8 own, and a
+ * non-JSON end (there is none today) is passed through untouched rather than guessed at.
+ */
+function withHealthFields(res, accounting) {
+  const end = res.end.bind(res);
+  res.end = (chunk, ...rest) => {
+    let body;
+    try {
+      body = JSON.parse(Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk));
+    } catch {
+      return end(chunk, ...rest); // expected: only the health JSON body is augmented
+    }
+    return end(JSON.stringify({ ...body, ...healthFields(accounting) }), ...rest);
+  };
+  return res;
+}
+
+function exitRecordPath(dataDir) {
+  return path.join(dataDir, 'oauth-proxy', 'last-exit.json');
+}
+
+/**
+ * §9 S-5: the previous exit, written once. Atomic (tmp + rename) and owner-only, so a concurrent reader
+ * sees either the whole record or no record — never a half-written one. Async like the budget journals
+ * beside it (request-budget-store.js): the proxy awaits the write before it exits, and the supervisor
+ * reads it off the main thread.
+ * @returns {Promise<object>} the record written
+ */
+async function writeExitRecord({ dataDir, reason, openStreams }) {
+  const record = { v: EXIT_RECORD_VERSION, at: new Date().toISOString(), pid: process.pid, reason, openStreams };
+  const target = exitRecordPath(dataDir);
+  const tmp = `${target}.${process.pid}.tmp`;
+  await fsp.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  await fsp.writeFile(tmp, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  await fsp.rename(tmp, target);
+  return record;
+}
+
+/**
+ * @returns {Promise<object|null>} the recorded previous exit, or null when there is none to report. A
+ * truncated or hand-edited record is reported as absent rather than thrown: it is evidence of nothing.
+ */
+async function readExitRecord({ dataDir }) {
+  let raw;
+  try {
+    raw = await fsp.readFile(exitRecordPath(dataDir), 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null; // expected: no previous exit was recorded
+    throw err;
+  }
+  try {
+    const record = JSON.parse(raw);
+    return record && typeof record === 'object' ? record : null;
+  } catch {
+    return null; // expected: an unparseable record is not evidence; report it as absent
+  }
+}
+
+/** One exit is reported once: the supervisor reads the record, then clears it. */
+async function clearExitRecord({ dataDir }) {
+  try {
+    await fsp.rm(exitRecordPath(dataDir), { force: true });
+  } catch (err) {
+    // REPORT: a record that cannot be removed is stale truth on disk, which is worth a line.
+    console.error(`[model-proxy] exit record not removed: ${(err && err.code) || 'unknown'}`);
+  }
+}
+
+module.exports = {
+  createStreamAccounting,
+  healthFields,
+  withHealthFields,
+  writeExitRecord,
+  readExitRecord,
+  clearExitRecord,
+  exitRecordPath,
+};