create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/bin/capture-codex-rollout-records.js

@@ -0,0 +1,417 @@
+#!/usr/bin/env node
+'use strict';
+
+// D-9 (WP-0 of docs/codex-lead-routed-switch-history-handoff-2026-10-21.html): cut real records
+// out of real Codex rollouts into sanitized fixtures, one file per Codex CLI version, so the
+// scanner is exercised against what Codex actually serializes instead of a hand-written copy.
+//
+//   node bin/capture-codex-rollout-records.js --out tests/fixtures/codex-rollout-records [--roots <dir,dir>]
+//
+// Default roots are ~/.codex/sessions and ~/.codex-local/sessions. For every distinct
+// session_meta.cli_version found the tool writes <version>.jsonl holding one real example of the
+// session_meta, thread_settings_applied (the one with the most optional keys), turn_context,
+// task_started, task_complete, token_count, world_state (full:true) and, when the version produced
+// one, a compacted record. Adding a new Codex version's fixture file is part of qualifying it.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const DEFAULT_ROOTS = [path.join(os.homedir(), '.codex', 'sessions'), path.join(os.homedir(), '.codex-local', 'sessions')];
+// Kinds captured per version, written in this order. The optional kind is only present when the
+// version wrote one; a missing optional record never fails the capture.
+const REQUIRED_KINDS = Object.freeze(['thread_settings_applied', 'turn_context', 'task_started', 'task_complete', 'token_count', 'world_state']);
+const OPTIONAL_KINDS = Object.freeze(['compacted']);
+const MAX_FILES_PER_VERSION = 40;
+const MAX_BYTES_PER_FILE = 24 * 1024 * 1024;
+
+const THREAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const FIXTURE_ID_PREFIX = 'a0000000-0000-4000-8000-';
+// The one thread a fixture file describes. Every record is cut from a rollout of that thread, so
+// the payload `thread_id`/`session_id` fields all name it (the scanner checks them against the
+// session_meta lineage).
+const FIXTURE_THREAD_ID = `${FIXTURE_ID_PREFIX}000000000001`;
+const FIXTURE_PATH_ROOT = '/tmp/fixture';
+const FIXTURE_TEXT = 'fixture text';
+const FIXTURE_IMAGE_URL = 'data:image/png;base64,AAAA';
+const FIXTURE_CIPHERTEXT = `gAAAA${'x'.repeat(40)}`;
+// Every string under these keys is a filesystem location, whatever its depth in the record.
+const PATH_KEYS = new Set(['cwd', 'path', 'paths', 'runtime_workspace_roots', 'workspace_roots',
+  'writable_roots', 'roots', 'dir', 'directory', 'home', 'jsonl_path', 'rollout_path']);
+// Every string under these keys names the thread the fixture describes.
+const THREAD_KEYS = new Set(['thread_id', 'session_id', 'threadid']);
+// The replacement-item types `classifyReplacement` accepts in lib/history-transition-read-op.js.
+// A compacted record outside this set is refused by the scanner, so it is not a usable fixture.
+const REPLACEMENT_CALL_TYPES = new Set(['function_call', 'custom_tool_call', 'computer_call', 'local_shell_call']);
+const REPLACEMENT_OUTPUT_TYPES = new Set(['function_call_output', 'custom_tool_call_output',
+  'computer_call_output', 'local_shell_call_output']);
+const REPLACEMENT_ITEM_TYPES = new Set(['text', 'summary', 'compaction', 'message']);
+// Every string under these keys is prose the person wrote or Codex prompted with.
+const TEXT_KEYS = new Set(['text', 'message', 'last_agent_message', 'developer_instructions',
+  'base_instructions', 'instructions', 'summary', 'prompt', 'description']);
+// Prose and tool arguments arrive as one long string under keys this tool cannot enumerate
+// (`arguments`, `plugins_instructions`, ...). Anything that long is text, not a protocol value.
+const MAX_TEXT_LENGTH = 200;
+// Default-deny: a short string survives only under a key whose values are protocol enums or
+// identifiers of the protocol itself. Everything else -- approved command prefixes, network
+// domains, MCP server and tool names, search queries, document and channel ids -- is local data
+// and becomes FIXTURE_WORD (a token that also satisfies the scanner's identifier patterns).
+const ENUM_KEYS = new Set(['type', 'role', 'model', 'model_provider_id', 'approval_policy',
+  'approvals_reviewer', 'mode', 'network', 'service_tier', 'reasoning_effort', 'reasoning_summary',
+  'effort', 'personality', 'status', 'phase', 'turn_trigger', 'sandbox', 'sandbox_mode',
+  'sandbox_policy', 'cli_version', 'originator', 'source', 'detail', 'timestamp', 'model_family',
+  'collaboration_mode', 'collaboration_mode_kind', 'kind', 'trigger', 'reason', 'stop_reason', 'end_turn', 'level']);
+const ENUM_VALUE = /^[A-Za-z0-9@][A-Za-z0-9@._:+-]{0,63}$/;
+const FIXTURE_WORD = 'fixture';
+// The local account name, matched anywhere (including inside an ssh remote "<account>@host:path").
+const ACCOUNT_NAME = new RegExp(os.userInfo().username.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i');
+const ENVELOPE_KEYS = Object.freeze(['timestamp', 'ordinal', 'type', 'payload']);
+
+function parseArgs(argv) {
+  const args = { out: '', roots: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === '--out') { args.out = String(argv[index + 1] || ''); index += 1; }
+    else if (flag === '--roots') {
+      args.roots = String(argv[index + 1] || '').split(',').map((value) => value.trim()).filter(Boolean);
+      index += 1;
+    } else if (flag === '--help' || flag === '-h') { args.help = true; }
+    else throw new Error(`unknown argument: ${flag}`);
+  }
+  return args;
+}
+
+function walkRollouts(root) {
+  const files = [];
+  const pending = [root];
+  while (pending.length) {
+    const dir = pending.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    // expected: an absent or unreadable configured Codex home simply contributes no rollouts.
+    catch { continue; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) pending.push(full);
+      else if (entry.isFile() && entry.name.startsWith('rollout-') && entry.name.endsWith('.jsonl')) files.push(full);
+    }
+  }
+  return files;
+}
+
+function readFirstLine(file, maxBytes = 256 * 1024) {
+  let fd;
+  try { fd = fs.openSync(file, 'r'); }
+  // expected: a rollout that vanished between listing and reading is skipped.
+  catch { return null; }
+  try {
+    const buffer = Buffer.allocUnsafe(maxBytes);
+    const read = fs.readSync(fd, buffer, 0, maxBytes, 0);
+    const text = buffer.toString('utf8', 0, read);
+    const newline = text.indexOf('\n');
+    return newline < 0 ? text : text.slice(0, newline);
+  } catch { return null; }
+  finally { fs.closeSync(fd); }
+}
+
+function parseRecord(line) {
+  if (!line.trim()) return null;
+  try { return JSON.parse(line); }
+  // expected: a rollout captured while a turn was running can end in a partial line.
+  catch { return null; }
+}
+
+function recordKind(record) {
+  if (!record || typeof record.type !== 'string') return '';
+  if (record.type === 'event_msg') return String(record.payload?.type || '');
+  return record.type;
+}
+
+function threadSettingsScore(record) {
+  const settings = record?.payload?.thread_settings;
+  return settings && typeof settings === 'object' ? Object.keys(settings).length : 0;
+}
+
+// Streams one rollout from the start, up to `maxBytes`, reporting the first (or best) example of
+// every wanted kind and stopping as soon as all of them have been seen.
+function collectKinds(file, { kinds, maxBytes = MAX_BYTES_PER_FILE, accept = null } = {}) {
+  const hits = new Map();
+  const scores = new Map();
+  const rejected = new Map();
+  let sessionMeta = null;
+  let fd;
+  try { fd = fs.openSync(file, 'r'); }
+  // expected: an unreadable rollout contributes nothing.
+  catch { return { hits, sessionMeta, rejected }; }
+  const buffer = Buffer.allocUnsafe(1 << 20);
+  let carry = '';
+  let bytes = 0;
+  try {
+    while (bytes < maxBytes) {
+      const read = fs.readSync(fd, buffer, 0, buffer.length, null);
+      if (!read) break;
+      bytes += read;
+      carry += buffer.toString('utf8', 0, read);
+      const lines = carry.split('\n');
+      carry = lines.pop();
+      for (const line of lines) {
+        const record = parseRecord(line);
+        if (!record) continue;
+        if (record.type === 'session_meta' && !sessionMeta) sessionMeta = record;
+        const kind = recordKind(record);
+        if (!kinds.has(kind)) continue;
+        const refusal = accept ? accept(kind, record) : '';
+        if (refusal) { if (!rejected.has(kind)) rejected.set(kind, refusal); continue; }
+        const score = kind === 'thread_settings_applied' ? threadSettingsScore(record) : 0;
+        if (!hits.has(kind) || score > (scores.get(kind) || 0)) { hits.set(kind, record); scores.set(kind, score); }
+      }
+      if ([...kinds].every((kind) => hits.has(kind))) break;
+    }
+  } catch { /* expected: a truncated read of an active rollout keeps what was parsed so far */ }
+  finally { fs.closeSync(fd); }
+  return { hits, sessionMeta, rejected };
+}
+
+function pickVersionRecords(files) {
+  const candidates = files
+    .map((file) => ({ file, size: statSize(file) }))
+    .sort((a, b) => b.size - a.size || a.file.localeCompare(b.file))
+    .slice(0, MAX_FILES_PER_VERSION);
+  const wanted = new Set([...REQUIRED_KINDS, ...OPTIONAL_KINDS]);
+  const accept = (kind, record) => (kind === 'compacted' ? compactedRefusal(record) : '');
+  const picked = { sessionMeta: null, records: new Map(), skipped: new Map() };
+  for (const { file } of candidates) {
+    const remaining = new Set([...wanted].filter((kind) => !picked.records.has(kind)));
+    if (!remaining.size) break;
+    // The largest rollout for a version carries the most record types; after it, only the kinds
+    // still missing are searched for, so a version costs at most one full pass.
+    const found = collectKinds(file, { kinds: remaining, accept });
+    if (!picked.sessionMeta) picked.sessionMeta = found.sessionMeta;
+    for (const [kind, reason] of found.rejected) if (!picked.skipped.has(kind)) picked.skipped.set(kind, reason);
+    for (const [kind, record] of found.hits) {
+      const previous = picked.records.get(kind);
+      if (!previous) { picked.records.set(kind, record); continue; }
+      if (kind === 'thread_settings_applied' && threadSettingsScore(record) > threadSettingsScore(previous)) {
+        picked.records.set(kind, record);
+      }
+    }
+  }
+  return picked;
+}
+
+// A compacted record is only a fixture when the scanner can classify its replacement window; the
+// item types below mirror `classifyReplacement` (lib/history-transition-read-op.js). Codex writes
+// `agent_message` items into some windows, which the scanner still refuses -- such a record is
+// reported as skipped instead of being written into a fixture that cannot pass.
+function compactedRefusal(record) {
+  const payload = record?.payload;
+  if (!payload || typeof payload !== 'object') return 'no payload';
+  const replacement = payload.replacement_history ?? payload.replacementHistory ?? payload.summary;
+  if (replacement === undefined) return '';
+  if (typeof replacement === 'string') return '';
+  if (!Array.isArray(replacement)) return 'replacement is not an array';
+  const calls = new Set();
+  const outputs = new Set();
+  for (const item of replacement) {
+    if (typeof item === 'string') continue;
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return 'replacement item is not an object';
+    const type = String(item.type || item.kind || '');
+    const id = String(item.call_id || item.id || '');
+    if (REPLACEMENT_ITEM_TYPES.has(type)) continue;
+    if (REPLACEMENT_CALL_TYPES.has(type)) {
+      if (!id || calls.has(id)) return 'replacement call id is missing or repeated';
+      calls.add(id);
+      continue;
+    }
+    if (REPLACEMENT_OUTPUT_TYPES.has(type)) {
+      if (!id || !calls.has(id) || outputs.has(id)) return 'replacement output does not pair with a call';
+      outputs.add(id);
+      continue;
+    }
+    return `replacement item type ${type || '(none)'}`;
+  }
+  return calls.size === outputs.size ? '' : 'replacement tool pair is unclosed';
+}
+
+function statSize(file) {
+  try { return fs.statSync(file).size; }
+  // expected: a rollout deleted mid-run is ranked last instead of aborting the capture.
+  catch { return 0; }
+}
+
+// `threadRealId` is the session_meta id of the fixture: it is the fixture's thread id, so every
+// other record naming that thread keeps naming it.
+function createSanitizer(threadRealId = '') {
+  const ids = new Map();
+  if (THREAD_ID.test(threadRealId)) ids.set(threadRealId, FIXTURE_THREAD_ID);
+  const paths = new Map();
+  let nextIdIndex = 2;
+  const idFor = (value) => {
+    if (!ids.has(value)) {
+      ids.set(value, `${FIXTURE_ID_PREFIX}${nextIdIndex.toString(16).padStart(12, '0')}`);
+      nextIdIndex += 1;
+    }
+    return ids.get(value);
+  };
+  const pathFor = (value) => {
+    if (!paths.has(value)) paths.set(value, `${FIXTURE_PATH_ROOT}/${paths.size + 1}`);
+    return paths.get(value);
+  };
+  return { idFor, pathFor, threadId: () => FIXTURE_THREAD_ID };
+}
+
+function sanitizeValue(key, value, sanitizer, depth) {
+  if (typeof value === 'string') return sanitizeString(key, value, sanitizer);
+  if (depth > 64) return value;
+  if (Array.isArray(value)) return value.map((item) => sanitizeValue(key, item, sanitizer, depth + 1));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [childKey, sanitizeValue(childKey, child, sanitizer, depth + 1)]));
+  }
+  return value;
+}
+
+function sanitizeString(key, value, sanitizer) {
+  const name = key.toLowerCase();
+  if (name === 'encrypted_content') return FIXTURE_CIPHERTEXT;
+  if (name === 'image_url') return FIXTURE_IMAGE_URL;
+  if (PATH_KEYS.has(name)) return sanitizer.pathFor(value);
+  // Every record in the file belongs to the one fixture thread, exactly as in the rollout it was
+  // cut from, so the scanner's lineage check holds across records captured from different rollouts.
+  if (THREAD_KEYS.has(name)) return sanitizer.threadId();
+  if (THREAD_ID.test(value)) return sanitizer.idFor(value);
+  // A path or an account name can appear anywhere, including inside prose, tool arguments and an
+  // ssh remote ("<account>@host:path"). The substring test is deliberate: the account name is a
+  // substring of other local accounts too.
+  if (value.includes('/Users/') || value.includes('/home/') || ACCOUNT_NAME.test(value)) return FIXTURE_TEXT;
+  if (TEXT_KEYS.has(name) || value.length > MAX_TEXT_LENGTH) return FIXTURE_TEXT;
+  if (value.startsWith('/')) return sanitizer.pathFor(value);
+  if (ENUM_KEYS.has(name) && (ENUM_VALUE.test(value) || /^\d{4}-\d\d-\d\dT[\d:.]+Z$/.test(value))) return value;
+  // An id the scanner pairs or compares (call_id, item id, ...) stays consistent within the file.
+  if (name === 'id' || name.endsWith('_id')) return sanitizer.idFor(value);
+  return FIXTURE_WORD;
+}
+
+function sanitizeRecord(record, sanitizer) {
+  const envelope = {};
+  for (const key of ENVELOPE_KEYS) {
+    if (!Object.hasOwn(record, key)) continue;
+    envelope[key] = key === 'payload' ? sanitizeValue(key, record.payload, sanitizer, 0) : record[key];
+  }
+  // Any envelope key Codex adds later is carried through, never dropped.
+  for (const [key, value] of Object.entries(record)) {
+    if (Object.hasOwn(envelope, key)) continue;
+    envelope[key] = sanitizeValue(key, value, sanitizer, 0);
+  }
+  return envelope;
+}
+
+function fixtureRecords(picked) {
+  const sanitizer = createSanitizer(String(picked.sessionMeta?.payload?.id || ''));
+  const ordered = [];
+  if (picked.sessionMeta) ordered.push(picked.sessionMeta);
+  for (const kind of [...OPTIONAL_KINDS, ...REQUIRED_KINDS]) {
+    const record = picked.records.get(kind);
+    if (record) ordered.push(record);
+  }
+  return ordered.map((record, index) => sanitizeRecord(record, sanitizer));
+}
+
+function compareVersions(a, b) {
+  const parse = (value) => String(value).split('.').map((part) => Number.parseInt(part, 10) || 0);
+  const left = parse(a), right = parse(b);
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    if ((left[index] || 0) !== (right[index] || 0)) return (left[index] || 0) - (right[index] || 0);
+  }
+  return String(a).localeCompare(String(b));
+}
+
+function groupByVersion(files) {
+  const byVersion = new Map();
+  for (const file of files) {
+    const first = parseRecord(readFirstLine(file) || '');
+    if (!first || first.type !== 'session_meta') continue;
+    const version = String(first.payload?.cli_version || first.payload?.version || '').trim();
+    if (!version) continue;
+    if (!byVersion.has(version)) byVersion.set(version, []);
+    byVersion.get(version).push(file);
+  }
+  return byVersion;
+}
+
+function capture({ outDir, roots }) {
+  const files = roots.flatMap((root) => walkRollouts(root));
+  const byVersion = groupByVersion(files);
+  fs.mkdirSync(outDir, { recursive: true });
+  const captured = [];
+  for (const version of [...byVersion.keys()].sort(compareVersions)) {
+    const picked = pickVersionRecords(byVersion.get(version));
+    const records = fixtureRecords(picked);
+    const missing = REQUIRED_KINDS.filter((kind) => !picked.records.has(kind));
+    fs.writeFileSync(path.join(outDir, `${version}.jsonl`), `${records.map((record) => JSON.stringify(record)).join('\n')}\n`);
+    captured.push({ version, records: records.length, files: byVersion.get(version).length,
+      compacted: picked.records.has('compacted'), missing, skipped: picked.skipped });
+  }
+  return captured;
+}
+
+const README = `# Codex rollout record fixtures
+
+One file per Codex CLI version (\`<cli_version>.jsonl\`), holding real rollout records cut from real
+sessions and sanitized. These are what the scanner in \`lib/history-transition-read-op.js\` is
+validated against, so schema drift shows up as a test failure instead of a refused provider switch.
+
+Each file holds, in order: the session_meta that names the fixture thread, and then one record of
+each kind Codex writes — \`compacted\` when the version produced one, \`thread_settings_applied\`
+(the record with the most optional keys), \`turn_context\`, \`task_started\`, \`task_complete\`,
+\`token_count\`, \`world_state\` (\`full: true\`).
+
+Sanitization (bin/capture-codex-rollout-records.js): every string under a path key
+(\`cwd\`, \`path\`, \`runtime_workspace_roots\`, \`workspace_roots\`, \`writable_roots\`, ...) and every
+other absolute path becomes \`/tmp/fixture/<n>\`; every id-like uuid (thread, turn, response,
+window) becomes a fixture uuid that is consistent within a file; prose keys (\`text\`, \`message\`,
+\`last_agent_message\`, \`developer_instructions\`, \`base_instructions\`, ...) and any string that
+carries a home path or the account name become \`fixture text\`; \`encrypted_content\` becomes
+\`gAAAA\` + 40 x's; \`image_url\` becomes a tiny data uri. Every other short string is
+default-deny: it survives only under a protocol-enum key (\`ENUM_KEYS\`: type, role, model, status,
+approval_policy, ...); an \`id\`/\`*_id\` value becomes a consistent fixture uuid and anything
+else -- approved command prefixes, network domains, MCP names, queries -- becomes \`fixture\`.
+Key sets and value types are unchanged.
+
+## Regenerate
+
+\`\`\`
+cd coding-task-manager
+node bin/capture-codex-rollout-records.js --out tests/fixtures/codex-rollout-records
+\`\`\`
+
+Add \`--roots <dir,dir>\` to read other Codex homes (default \`~/.codex/sessions\`,
+\`~/.codex-local/sessions\`). After a Codex upgrade, capture the new version's file and review the
+diff: **adding a new Codex version's fixture file is part of qualifying that version** (see
+\`docs/codex-harness-version-qualification-2026-10-19.html\`).
+
+Verify no real path or account name survives: \`tests/codex-rollout-record-fixtures.test.js\` greps
+every fixture for the home-directory prefix and for the account name, and fails if either appears.
+`;
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help || !args.out) {
+    process.stdout.write('usage: node bin/capture-codex-rollout-records.js --out <dir> [--roots <dir,dir>]\n');
+    return args.help ? 0 : 2;
+  }
+  const roots = (args.roots.length ? args.roots : DEFAULT_ROOTS).map((root) => path.resolve(root));
+  const outDir = path.resolve(process.cwd(), args.out);
+  const captured = capture({ outDir, roots });
+  fs.writeFileSync(path.join(outDir, 'README.md'), README);
+  for (const entry of captured) {
+    const compactedNote = entry.compacted ? 'compacted'
+      : `no-compacted${entry.skipped.has('compacted') ? ` (${entry.skipped.get('compacted')})` : ''}`;
+    const notes = [entry.missing.length ? `missing ${entry.missing.join(',')}` : 'complete', compactedNote];
+    process.stdout.write(`${entry.version}: ${entry.records} records from ${entry.files} rollout(s) (${notes.join(', ')})\n`);
+  }
+  return 0;
+}
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));
+
+module.exports = { capture, sanitizeValue, createSanitizer, walkRollouts, groupByVersion, fixtureRecords };