create-walle 0.10.0 → 0.10.1

package/README.md

@@ -1,44 +1,99 @@
 # create-walle
 
-**Run your agents. Keep your context.** Set up CTM's coding workspace and Wall-E's personal agent and memory in one command. Run coding sessions side by side, delegate focused tasks, review results, and recover the decisions behind them.
+**One workspace for your coding agents. Context that carries forward.**
 
-## What You Get
+Install **CTM** (Coding Task Manager) and **Wall-E** in one command. CTM runs coding agents in real terminals on your machine and gives them a browser workspace for sessions, worktrees, approvals and review. Wall-E is the personal agent alongside it, keeping project knowledge and preferences for later work.
 
-### CTM (Coding Task Manager)
+Different tasks suit different agents, so choose per session instead of committing to one up front.
 
-A web dashboard for running and managing AI coding sessions across multiple providers.
+Start at [walle.sh](https://walle.sh), or follow the [illustrated walkthrough](https://walle.sh/blog/paste-the-link/) for the same workflow with more detail and examples.
 
-- **Sessions & history** — Run Claude Code, Codex, Gemini CLI, OpenCode, Cursor Agent, Wall-E, and shell sessions with persistent scrollback. Session features vary by agent.
-- **Delegated workers** — Delegate focused implementation tasks to Claude or Codex workers, and choose the model and effort for the work.
-- **Prompts & queues** — Save prompts, organize them, and queue work for a deliberate sequence.
-- **Review & approvals** — Review code and documents, with approval workflows where the connected agent supports them. Rich review is supported for Claude, Codex, OpenCode, and Wall-E.
-- **Remote phone & tablet access** — Configure access to the running host from a phone or tablet when you need to check in away from your desk.
-- **Models** — Set a default or choose a model by task and role. Claude and Codex support lead-model switching; Wall-E has its own native model configuration.
+## Quick start
 
-### Wall-E (personal agent and memory)
+```bash
+npx create-walle install ./walle
+```
 
-Wall-E brings searchable memory, connected tools, and reusable workflows to your work. Use its chat or connect compatible coding agents through MCP to look up shared memory and prior session history.
+Install **Node.js 24.22.0 or later** and npm first. The installer manages the supported runtime for CTM and Wall-E; that runtime requires macOS 13.5 or later, or Linux with glibc 2.28 or later and kernel 4.18 or later.
 
-- **Chat** — Threaded conversations with a pinned Home thread. Chat can search memories, recall sessions, run skills, call configured MCP tools, and schedule jobs.
-- **Inbox and approvals** — One inbox for what needs your attention. Actions that leave your machine follow per-capability policies: allowed, asked for approval, or denied.
-- **Jobs** — Scheduled and one-off work (briefings, reflections, Slack inbound) with run history. Nothing runs on a schedule unless you configure it.
-- **Searchable memory** — Knowledge, entities, and timeline, available to the chat and to coding agents through MCP.
-- **Connected sources** — Optional integrations (for example Slack, with auto-replies only to an allowlist you set). They require the relevant accounts and permissions.
-- **Phone** — The same Wall-E views on the CTM phone app.
+The command copies the project, installs dependencies and starts the server. Open **http://localhost:3456** to finish setup in the browser, then authenticate the agents and providers you choose and configure any optional connections or remote device access. The npm installation is the current path on macOS and Linux; the Mac app is still being updated.
 
-## Install
+![CTM's session list with Claude Code and Codex sessions grouped under Running, Needs You and Idle, and two worker sessions nested beneath their lead.](https://walle.sh/blog/paste-the-link/img/fig-1-workspace.png)
 
-Install **Node.js 24.22.0 or later** and npm first. The installer manages the supported runtime for CTM and Wall-E.
+Screenshots show the real application with fictional `acme-ledger` data and scripted agent dialogue.
 
-The managed Node runtime requires macOS 13.5 or later, or supported Linux with glibc 2.28 or later and kernel 4.18 or later.
+## Why CTM and Wall-E
 
-```bash
-npx create-walle install ./walle
+### Choose the agent for the task
+
+Every session has its own agent choice. Run Claude Code, Codex, Gemini CLI, OpenCode, Cursor Agent, Wall-E or a shell side by side and move between them from the same workspace.
+
+The CLI, the model and the connection serving that model are separate decisions: the AI Providers area brings native agent options, direct provider connections and configured routers into one place, using your own accounts and credentials. Agents differ in what they support, so the available model-switching controls depend on the CLI you pick.
+
+### See what each agent needs
+
+Running, Needs You and Idle group the session list by what requires attention, and delegated workers appear beneath the lead session that started them.
+
+The session summary answers the next question — what is this agent trying to finish? — by bringing together the current task, recent progress and how fresh that information is. "Add jitter to webhook retries. Implementation is ready; the duplicate-delivery test still needs review." After a break, that is enough to decide which session to open.
+
+![CTM's session summary for the lead session, showing the current task, recent progress and freshness beside the session list.](https://walle.sh/blog/paste-the-link/img/fig-3-summary.png)
+
+### Coordinate worktrees, changes and workers
+
+Start a session with its own **worktree** and CTM creates the branch and working directory and links them to the session, so an investigation and a test run can proceed in separate checkouts of the same repository.
+
+The worktree panel shows **Ready to merge**, **Behind main** and **Dirty** states, uncommitted changes and branch drift, along with the sessions linked to each checkout. Changed-file and commit indicators connect a conversation to the code it touched, and describe the working tree rather than who wrote each line: sessions that share a checkout share that Git state.
+
+For focused work, delegate to Claude or Codex workers, choose the model and effort, and inspect the result beneath the lead. Tasks that start servers still need separate ports and data directories. See the [delegation walkthrough](https://walle.sh/blog/delegation-guide/) for setup and an example task.
+
+### Let routine permissions move forward
+
+Repeated prompts interrupt work, so CTM applies rules for decisions you have already made, such as allowing a particular test command in the project you are working on.
+
+For requests that need more judgment, an approval flow can check the request against the task with a scoped AI review. Requests held for you stay visible as Needs You, with the reason available to inspect, and the Permissions panel shows the policy behind each decision so you can change or disable a rule. These settings govern CTM's automatic approval; the selected CLI also keeps its own permission controls.
+
+### Reuse the knowledge behind your code
+
+Conversations hold more than the final patch: approaches that failed, constraints that mattered and the reasoning behind a decision. CTM records prompts, answers and tool calls as structured turns you can read and search by phrase, file reference or session link.
+
+With Wall-E connected through MCP, paste the earlier session's URL into a new session and ask the agent to read that session, or let it search Wall-E:
+
+```text
+Search Wall-E for the earlier retry investigation in acme-ledger.
+Find the decision about the 30-second cap and use it when reviewing this diff.
 ```
 
-This copies the project, installs dependencies, and starts the server. Open **http://localhost:3456** to finish setup in the browser, then authenticate the agents and providers you choose and configure any optional integrations or remote device access.
+![A recorded session shown as prompts, answers and tool calls, including the reasoning behind the 30-second retry cap.](https://walle.sh/blog/paste-the-link/img/fig-6-conversation.png)
+
+The layers do different jobs. Recorded conversations preserve the discussion as it happened; search and selected context retrieval fit the parts that matter into a limited model context; durable memory keeps the facts, entities and preferences worth keeping. Retrieval is not automatic — the agent has to look, and it depends on which history and tools are connected — so check retrieved context against the current branch before relying on it.
+
+### Keep work available without keeping everything running
+
+CTM can park an eligible inactive session to stop its process and free resources while the recorded conversation stays in the workspace, then bring it back when you need it.
+
+A shared MCP gateway lets eligible tool servers reuse one process across sessions; tools needing session-specific state keep separate instances.
+
+### Review changes in one place
+
+The Review page moves between rendered HTML or Markdown, source files and diffs, and new files appear before Git tracks them. Comments collect into one message for the session responsible for the change, keeping feedback beside the files that produced it.
+
+For a small correction, open the current file in File or Source view, choose **Edit**, change the text and save: the working file changes and the diff reflects it, while historical revisions and binary files stay read-only.
+
+### A personal agent with context about you
+
+Wall-E keeps its own chat threads, an inbox for what needs your attention, and scheduled or one-off jobs with run history. Schedules run only when you configure them.
 
-Use the npm installation on macOS and Linux. The Mac app is being updated for this release.
+Saved preferences and project knowledge carry into later work. Store `Show the failure and test evidence before proposing a rollout`, for example, and a later review brief can start from it instead of restating the point.
+
+Optional connected sources such as Slack need their own accounts and permissions, and Slack auto-replies stay inside the allowlist you configure.
+
+## Try it on one project
+
+This example is fictional and the dialogue is scripted; it illustrates the workflow rather than measuring an agent. A failed webhook delivery in `acme-ledger` needs better retry handling, so Claude Code investigates the retry behaviour in one session while Codex works on tests in a separate worktree.
+
+A scoped test command proceeds under an approval rule, while a request to write outside the test transaction is held as Needs You until you release it.
+
+Days later, a review session needs the reasoning behind the 30-second retry cap recorded during the earlier investigation. With Wall-E connected through MCP, paste that session's URL into the new session, or ask Wall-E to find it, and the agent works from the original reasoning while you read the design document and patch together.
 
 ## Commands
 
@@ -61,26 +116,15 @@ If an older installation asks for its existing Node executable during an update,
 npx create-walle update --installed-node /absolute/path/to/node
 ```
 
-## Setup
-
-On first launch, the browser setup page guides you through:
-
-1. **Browser setup** — finish the local installation in the dashboard
-2. **Providers** — authenticate the coding agents and model providers you use
-3. **Integrations** — optionally connect available sources with their required permissions
-4. **Remote phone and tablet access** — optionally configure access to the running host
-
-## Custom Port
+Run on another port with `CTM_PORT`. Wall-E runs on `CTM_PORT + 1` — 5001 in this example:
 
 ```bash
 CTM_PORT=5000 npx create-walle install ./walle
 ```
 
-Wall-E runs on `CTM_PORT + 1` (e.g., 5001).
-
 ## Hosting and storage
 
-The dashboard and Wall-E memory run on the host where you install them. SQLite is the default storage. Coding providers and optional integrations may contact their own services and require their own accounts or permissions. Use backups and exports to preserve or move local data; do not treat file-sync services as database replication.
+The dashboard and Wall-E memory run on the host where you install them, and SQLite is the default storage. Coding providers and optional integrations may contact their own services and require their own accounts or permissions. Use backups and exports to preserve or move local data; do not treat file-sync services as database replication.
 
 | Component | Default Port | What it does |
 |-----------|-------------|--------------|
@@ -89,13 +133,12 @@ The dashboard and Wall-E memory run on the host where you install them. SQLite i
 
 ## Updates and recovery
 
-Run `npx create-walle update` from your installation directory. Updates verify compatibility, back up existing databases, and check the services before reporting success. The command reports backup and recovery information if attention is needed.
-
-Keep your backups available, and resolve an update error before retrying.
+Run `npx create-walle update` from your installation directory. Updates verify compatibility, back up existing databases and check the services before reporting success, and report backup and recovery information if attention is needed. Keep your backups available, and resolve an update error before retrying.
 
 ## Links
 
 - [Homepage](https://walle.sh)
+- [Walkthrough](https://walle.sh/blog/paste-the-link/)
 
 ## License
 

package/lib/runtime-closure-policy.json

@@ -1789,7 +1789,7 @@
     "coding-task-manager/public/js/client-health-worker.js": "07e300113ee749ac7a6adaaa1461502d1562087af395b6c89cf1b885f1f5e00e",
     "coding-task-manager/public/js/image-normalize-worker.js": "37cb0758bddcf10c66060fae52088c1a842409f30e919988e789cfea7d05e2be",
     "coding-task-manager/public/m/app.js": "483f777f57efd28d7796713c33df48ffba47e5bfb50597b446a37b961f53d585",
-    "coding-task-manager/server.js": "24a9871d0d974aed567a1f15e563fae1dc055484822b24b0f58146bcedb90d34",
+    "coding-task-manager/server.js": "927a036ed5143c02b2c021e5b5c0a80def7f87d01524514108f90f438e48b776",
     "scripts/conversation-storage-v2-migration.js": "80c66e41c9fb9b1d756fe21be17f3b07c6a65389712887043a86341fbf6a6879",
     "shared/storage/schema-port.js": "e41cec8c075a6167fba2efd0177d9e20a11c0cd49ae176aaf36d5b9257409e67",
     "shared/storage/schema-sync.js": "7ca080e44e35e8178a0f74317023881f920ae75bde4f7431702ce1f9fa4a1d03",
@@ -1815,7 +1815,7 @@
     "wall-e/channels/telegram-channel.plugin.json": "696d601804c91387824e80263b784f76ce5cad4b8ae81277d4b4030c1710e437",
     "wall-e/coding/action-memory-store.js": "5c7a467e9cb3e08dbfc7b27dec6724f8ea6eedac29d2c40f6c6bda3a4263a0c0",
     "wall-e/coding/hooks/plugin-loader.js": "f1ca5e032e64f68447af9317ad75821a5152ca25fad09ce4ac23e8cd39ac891c",
-    "wall-e/coding/host-capabilities.js": "1f320231fdf9ff078ec873255129168475ab5570b8864676836f678ea2ed70d4",
+    "wall-e/coding/host-capabilities.js": "9dafbc2a76ba5e00911219316be7b5f57ca26db278275606ea7fad61631370bd",
     "wall-e/coding/prompt-capabilities.js": "e230871618f9f43e6c7a3a7f98ebda2e77bb522018c6d4c0b1e29d0b08926708",
     "wall-e/coding/user-hooks.js": "4a0d9b82894f6a23c126b09d8f1feca3aa894b171a9c815e11389b2d96b1e018",
     "wall-e/lib/boot-preflight.js": "4415c7c3dae9add70bebdd29d75ee68d09097c53732438d35c3cd1ae0de5f01e",

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "create-walle",
-  "version": "0.10.0",
-  "description": "CTM + Wall-E — AI coding dashboard and personal digital twin agent. Multi-agent terminal for Claude Code, Codex, Gemini, Aider, OpenCode, and more, plus prompt editor, task queue, remote phone and tablet access, code/doc review, and an agent that learns from Slack, email & calendar.",
+  "version": "0.10.1",
+  "description": "CTM + Wall-E: one workspace for coding agents, worktrees and review, with shared session context and a personal agent.",
+  "homepage": "https://walle.sh",
   "bin": {
     "create-walle": "bin/create-walle.js"
   },
@@ -32,8 +33,13 @@
     "task-manager",
     "wall-e",
     "ai",
-    "digital-twin",
     "claude",
-    "personal-assistant"
+    "personal-assistant",
+    "coding-task-manager",
+    "coding-agents",
+    "codex",
+    "worktrees",
+    "mcp",
+    "memory"
   ]
 }

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 };