create-walle 0.10.0 → 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/responses-face.js

@@ -18,6 +18,7 @@
 const crypto = require('node:crypto');
 const chatUpstream = require('./chat-upstream');
 const routes = require('./routes');
+const { dropHandedOffCompactions } = require('./collaboration-codec');
 const { effectiveOutputCap } = require('./output-cap');
 const { upstreamRequest, readBodyBuffer } = require('./upstream-http');
 const { parseRetryAfterMs } = require('./retry-after');
@@ -39,6 +40,10 @@ function errorEnvelope(type, message) {
   return { error: { type: String(type), code: String(type), message: String(message) } };
 }
 
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
 function writeJson(res, status, obj) {
   res.writeHead(status, { 'content-type': 'application/json' });
   res.end(JSON.stringify(obj));
@@ -355,10 +360,27 @@ async function handle(req, res, ctx) {
     writeJson(res, 502, errorEnvelope('route_not_servable', `route "${route.alias}" (${route.upstreamApis.join(',')}) is not servable from the Responses face`));
     return;
   }
+  // WP-3 (docs/codex-lead-routed-switch-history-handoff-2026-10-21.html §5 D-7): a `compaction`
+  // item whose plaintext handoff replacement travels in the SAME request is omitted
+  // -- the replacement IS the readable form of that turn, so both faces get the
+  // rewritten body (chat-translate translates the summary; passthrough relays it).
+  // An UNMATCHED compaction item is untouched, so chat-translate still refuses it
+  // through the existing preflight and passthrough still forwards it verbatim.
+  const handedOff = isPlainObject(ctx.body) ? dropHandedOffCompactions(ctx.body) : null;
+  let requestCtx = ctx;
+  if (handedOff && handedOff.droppedHandedOffCompactions > 0) {
+    const body = handedOff.body;
+    // Same tag/wording policy as chat-upstream.js's reasoning-ciphertext line: one
+    // line, once per request, counts only -- never provider text.
+    process.stderr.write(`[model-proxy] dropped ${handedOff.droppedHandedOffCompactions} handed-off compaction item(s)\n`);
+    // ctx.body was JSON-parsed from the request, so it always serializes; passthrough sends
+    // this buffer (the caller's content-length is in CALLER_HEADER_DENYLIST).
+    requestCtx = { ...ctx, body, rawBody: Buffer.from(JSON.stringify(body)) };
+  }
   if (sel.mode === 'passthrough') {
-    return _passthrough(req, res, ctx);
+    return _passthrough(req, res, requestCtx);
   }
-  return _handleChatTranslate(req, res, ctx);
+  return _handleChatTranslate(req, res, requestCtx);
 }
 
 module.exports = { handle, errorEnvelope, notFound, writeJson, recordTranslatedNonstreamTelemetry };