create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/bin/census-codex-lead-history.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+'use strict';
+
+// WP-1 (docs/codex-lead-routed-switch-history-handoff-2026-10-21.html §1, §7 first row, §8 WP-1):
+// the §1 census, promoted from a scratch script to the tool the report quotes.
+//
+// WHY IT EXISTS. The naive census calls the scanner's inner function and counts record TYPES, which
+// reported "no new record types" for 0.163.0 while CTM refused 265 of 505 real sessions because of
+// the KEYS inside a known type (`thread_settings_applied`). This tool calls the PRODUCTION entry
+// point instead: readCodexHistoryTransitionSnapshot = owned-rollout resolution + the native prefix
+// reader + the scanner; when the scan completes it also runs the planner (inspectTransition), so the
+// first refusal of the REAL chain is what gets reported. See §1 "The naive count is wrong".
+//
+// OQ-1 (the census harness, not production, showed 65 `canonical_history_path_unavailable`): this
+// tool derives each session's storage root from the session's OWN jsonl_path -- the directory whose
+// last `sessions` segment holds the rollout -- instead of assuming one ~/.codex home for every row.
+// The corresponding root receipt is built the same way CTM's launch path builds it
+// (lib/codex-paths.js codexSessionsRootReceipt), so what is measured here is what production reads.
+//
+// READ-ONLY. The database is opened `readonly` + `fileMustExist` and is never written; no file is
+// created anywhere; no port is contacted.
+//
+// usage:
+//   node bin/census-codex-lead-history.js [--since YYYY-MM-DD] [--limit N] [--only <ctm-session-prefix>]
+//                                         [--db <path to core.db>] [--explain <ctm-session-prefix>]
+//
+//   --since   oldest modified_at to include (default 2026-10-01, the §1 population)
+//   --limit   newest sessions to scan (default 1000: above the 505 of §1, so a full table by default)
+//   --only    only sessions whose ctm_session_id starts with this prefix
+//   --explain also print the snapshot's summary fields for the matching session(s), and for a
+//             `thread_settings_applied` refusal the lineage set vs the failing record's thread_id (OQ-3)
+//
+// exit 0 the table printed · 1 usage error · 2 the database could not be opened read-only.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const Database = require('better-sqlite3');
+
+const op = require('../lib/history-transition-read-op');
+const { readNativeHistoryPrefix } = require('../lib/codex-native-history-prefix');
+const { inspectTransition } = require('../lib/harness-history-transition');
+const codexPaths = require('../lib/codex-paths');
+const { CODEX_CONTROL_ADAPTER, CODEX_COMPACTION_SCHEMA_RECEIPT } = require('../lib/codex-harness-qualification');
+
+const DEFAULT_DB = path.join(os.homedir(), '.walle', 'data', 'core.db');
+const DEFAULT_SINCE = '2026-10-01';
+const DEFAULT_LIMIT = 1000;
+const EXAMPLES_PER_REASON = 4;
+const EXPLAIN_GENERATION = 'census-codex-lead-history';
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+// The §1 target recipe: a routed DeepSeek V4.1 Flash target (any provider id other than the
+// source's; the planner only compares them) with the
+// qualified harness version and the qualified compaction receipt. Per-session fields (approval
+// policy, sandbox policy, cyber access program) are copied from the scanned snapshot.
+const TARGET_RECIPE_BASE = Object.freeze({
+  providerId: 'census-routed-target',
+  routeId: 'census-routed-target',
+  origin: 'routed-proxy',
+  harness: 'codex-cli',
+  controlAdapterVersion: CODEX_CONTROL_ADAPTER,
+  harnessVersion: '0.163.0',
+  wireModelId: 'deepseek-v4p1-flash',
+  contextTokens: 1049000,
+  usableContextTokens: 996550,
+  nativeCompactThresholdTokens: 944100,
+  plannedRequestOutputTokens: 65536,
+  compactHash: null,
+  compactHashStatus: 'known-absent-with-native-schema-receipt',
+  compactHashSchemaReceipt: CODEX_COMPACTION_SCHEMA_RECEIPT,
+  catalogSha256: '0'.repeat(64),
+});
+
+// One row per CTM session, newest agent_sessions row first (§1: "the newest row per session").
+const SESSION_QUERY = `SELECT ctm_session_id, agent_session_id, jsonl_path, max(modified_at) AS modified_at
+  FROM agent_sessions
+  WHERE lower(provider) = 'codex' AND ctm_session_id IS NOT NULL AND ctm_session_id <> ''
+    AND jsonl_path IS NOT NULL AND modified_at > ?
+  GROUP BY ctm_session_id
+  ORDER BY modified_at DESC
+  LIMIT ?`;
+
+class UsageError extends Error {}
+
+function usage() {
+  return [
+    'usage: node bin/census-codex-lead-history.js [--since YYYY-MM-DD] [--limit N] [--only <ctm-session-prefix>] [--db <path>] [--explain <ctm-session-prefix>]',
+    '  --since <date>   oldest modified_at to include (default 2026-10-01)',
+    '  --limit <n>      newest sessions to scan (default 1000)',
+    '  --only <prefix>  only sessions whose ctm_session_id starts with this prefix',
+    '  --db <path>      core.db to read (default ~/.walle/data/core.db, opened read-only)',
+    '  --explain <prefix> print the snapshot summary (and, for a thread_settings_applied refusal,',
+    '                   the lineage set vs the failing record thread_id) for matching session(s)',
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  const parsed = { help: false, since: DEFAULT_SINCE, limit: DEFAULT_LIMIT, only: null, db: DEFAULT_DB, explain: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') { parsed.help = true; continue; }
+    if (['--since', '--limit', '--only', '--db', '--explain'].includes(arg)) {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('--')) throw new UsageError(`${arg} needs a value`);
+      index += 1;
+      if (arg === '--since') parsed.since = value;
+      else if (arg === '--limit') parsed.limit = value;
+      else if (arg === '--only') parsed.only = value;
+      else if (arg === '--explain') parsed.explain = value;
+      else parsed.db = value;
+      continue;
+    }
+    throw new UsageError(`unknown option ${arg}`);
+  }
+  if (!DATE_RE.test(parsed.since)) throw new UsageError(`--since must be YYYY-MM-DD, got ${parsed.since}`);
+  const limit = Number(parsed.limit);
+  if (!Number.isSafeInteger(limit) || limit <= 0) throw new UsageError(`--limit must be a positive integer, got ${parsed.limit}`);
+  parsed.limit = limit;
+  return parsed;
+}
+
+function openReadOnly(dbPath) {
+  if (!fs.existsSync(dbPath)) throw new Error(`${dbPath} does not exist`);
+  const stat = fs.statSync(dbPath);
+  if (!stat.isFile()) throw new Error(`${dbPath} is not a file`);
+  return new Database(dbPath, { readonly: true, fileMustExist: true });
+}
+
+// OQ-1: the storage root of THIS session, taken from its own rollout path. Codex writes
+// <codexHome>/sessions/<date>/rollout-<ts>-<uuid>.jsonl, so the codex home is the parent of the
+// `sessions` segment; the receipt is the same object the launch path captures. A jsonl_path with no
+// `sessions` segment is not a Codex rollout path this tool can speak about -- reported, not guessed.
+function storageRootForSession(jsonlPath) {
+  const segments = path.resolve(jsonlPath).split(path.sep);
+  const index = segments.lastIndexOf('sessions');
+  if (index <= 0) return { codexHome: null, sessionsDir: null, receipt: null };
+  const codexHome = segments.slice(0, index).join(path.sep) || path.sep;
+  const sessionsDir = segments.slice(0, index + 1).join(path.sep);
+  return { codexHome, sessionsDir, receipt: codexPaths.codexSessionsRootReceipt({ codexHomePath: codexHome, sessionsDir }) };
+}
+
+// The §1 methodology, one session at a time: the production read path, then the planner. Keeping
+// only the key (never the snapshot) is what lets this run over every session in the window.
+function scanSession(row) {
+  const storage = storageRootForSession(row.jsonl_path);
+  if (!storage.receipt) {
+    return { key: `scan:${storage.codexHome ? 'history_storage_root_unavailable' : 'census_jsonl_path_unexpected'}`, storage };
+  }
+  let snapshot;
+  try {
+    snapshot = op.readCodexHistoryTransitionSnapshot({
+      db: row.db,
+      ctmSessionId: row.ctm_session_id,
+      sourceThreadId: row.agent_session_id,
+      processGeneration: 0,
+      storageRootReceipt: storage.receipt,
+      maxBytes: op.MAX_SCAN_BYTES,
+    });
+  } catch (error) {
+    // expected: a rollout deleted or replaced mid-scan is reported as a throw, never as a pass
+    return { key: `scan:THROW:${String(error?.message || error).slice(0, 60)}`, storage, snapshot: null };
+  }
+  if (!snapshot.complete) return { key: `scan:${snapshot.reason}`, storage, snapshot };
+  const previousSettings = snapshot.previousSettings || {};
+  const decision = inspectTransition({
+    sourceRecipe: {
+      providerId: previousSettings.modelProvider || 'openai',
+      origin: 'native-codex',
+      harness: 'codex-cli',
+      controlAdapterVersion: CODEX_CONTROL_ADAPTER,
+      programVersion: previousSettings.programVersion,
+      cyberAccessProgram: previousSettings.cyberAccessProgram,
+      approvalPolicy: previousSettings.approvalPolicy,
+      sandboxPolicy: previousSettings.sandboxPolicy,
+      wireModelId: previousSettings.model,
+      providerThreadId: row.agent_session_id,
+    },
+    targetRecipe: {
+      ...TARGET_RECIPE_BASE,
+      approvalPolicy: previousSettings.approvalPolicy,
+      sandboxPolicy: previousSettings.sandboxPolicy,
+      cyberAccessProgram: previousSettings.cyberAccessProgram,
+    },
+    snapshot,
+  });
+  return { key: decision.action === 'unsupported' ? `plan:${decision.reason}` : `OK:${decision.action}`, storage, snapshot };
+}
+
+function prefixed(value) {
+  return String(value || '').slice(0, 8);
+}
+
+function printTable(rows, tallies, examples, { since, limit }) {
+  const lines = [];
+  lines.push(`sessions ${rows.length} (since ${since}, limit ${limit})`);  const ordered = [...tallies.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const width = ordered.reduce((max, [reason]) => Math.max(max, reason.length), 6);
+  for (const [reason, count] of ordered) {
+    lines.push(`${String(count).padStart(4)}  ${reason.padEnd(width)}  ${examples.get(reason).join(', ')}`);
+  }
+  if (!ordered.length) lines.push('    (no sessions matched)');
+  lines.push(`total  ${[...tallies.values()].reduce((sum, count) => sum + count, 0)}`);
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+// OQ-3: the refusal the scanner returns for a `thread_settings_applied` record is the generic
+// `unsupported_native_history_event`, so the failing RECORD has to be located. The scanner stops at
+// its first refusal, and summarizing a slice that ends after the last `compacted` record uses the
+// same start index as the full list -- so "does this slice refuse" is monotone there, and a binary
+// search finds the refusing index in O(log n) scans instead of one scan per record.
+function firstRefusalIndex(records, { threadId, lineageIds }) {
+  const lastCompaction = records.findLastIndex((record) => record?.type === 'compacted');
+  const startIndex = lastCompaction >= 0 ? lastCompaction : 0;
+  let low = startIndex + 1;
+  let high = records.length;
+  let found = -1;
+  while (low <= high) {
+    const mid = (low + high) >> 1;
+    const summary = op.summarizeCodexHistoryRecords(records.slice(0, mid), {
+      threadId, generation: EXPLAIN_GENERATION, lineageThreadIds: lineageIds,
+    });
+    if (summary.complete) low = mid + 1;
+    else { found = mid - 1; high = mid - 1; }
+  }
+  return found;
+}
+
+function describeRefusal(root, threadId) {
+  const lines = [];
+  const prefix = readNativeHistoryPrefix(root.jsonl_path, { expectedThreadId: threadId, storageRoots: [root.storage.receipt.canonicalPath] });
+  if (!prefix.ok) {
+    lines.push(`  raw prefix read refused: ${prefix.reason}`);
+    return lines;
+  }
+  lines.push(`  lineage ids (${prefix.lineageIds.length}): ${prefix.lineageIds.join(', ')}`);
+  const index = firstRefusalIndex(prefix.records, { threadId, lineageIds: prefix.lineageIds });
+  if (index < 0) {
+    lines.push('  no refusing record found by re-summarizing prefixes (the refusal may be outside the scanned window)');
+  } else {
+    const record = prefix.records[index];
+    const payload = record?.payload && typeof record.payload === 'object' ? record.payload : {};
+    lines.push(`  first refusing record: index ${index}, type=${record?.type}, payload.type=${payload.type}`);
+    if ('thread_id' in payload) {
+      const owned = new Set(prefix.lineageIds.map((id) => String(id).toLowerCase()));
+      lines.push(`    payload.thread_id=${payload.thread_id} in lineage=${owned.has(String(payload.thread_id).toLowerCase())}`);
+    }
+  }
+  // OQ-3 verbatim: every thread_settings_applied record's thread_id against the computed lineage,
+  // with its key set, so "the keys are in the D-1 set, so the thread_id must be outside it" is
+  // answerable from this output alone.
+  const settingsRecords = prefix.records
+    .map((record, at) => ({ record, at }))
+    .filter(({ record }) => record?.type === 'event_msg' && record.payload?.type === 'thread_settings_applied');
+  const owned = new Set(prefix.lineageIds.map((id) => String(id).toLowerCase()));
+  lines.push(`  thread_settings_applied records: ${settingsRecords.length}`);
+  for (const { record, at } of settingsRecords.slice(0, 8)) {
+    const payload = record.payload;
+    const keys = payload.thread_settings && typeof payload.thread_settings === 'object' ? Object.keys(payload.thread_settings) : [];
+    lines.push(`    index ${at}: thread_id=${payload.thread_id ?? '(absent)'} in lineage=${payload.thread_id === undefined || payload.thread_id === null ? 'n/a' : owned.has(String(payload.thread_id).toLowerCase())} settings_keys=${keys.length}`);
+  }
+  return lines;
+}
+
+function explainSessions(rows, db) {
+  for (const row of rows) {
+    process.stdout.write(`\nexplain ${row.ctm_session_id}\n`);
+    process.stdout.write(`  agent_session_id: ${row.agent_session_id}\n`);
+    process.stdout.write(`  jsonl_path: ${row.jsonl_path}\n`);
+    const storage = storageRootForSession(row.jsonl_path);
+    process.stdout.write(`  codex_home: ${storage.codexHome || '(no sessions segment)'}\n`);
+    process.stdout.write(`  storage_root: ${storage.receipt ? storage.receipt.canonicalPath : '(no receipt)'}`
+      + `${storage.receipt ? ` fingerprint=${storage.receipt.fingerprint.slice(0, 12)}` : ''}\n`);
+    const result = scanSession({ ...row, db });
+    process.stdout.write(`  verdict: ${result.key}\n`);
+    process.stdout.write(`  snapshot: ${result.snapshot ? JSON.stringify(result.snapshot, null, 2).split('\n').join('\n  ') : '(not captured: the scan never ran or threw)'}\n`);
+    if (result.key === 'scan:unsupported_native_history_event' && storage.receipt) {
+      for (const line of describeRefusal({ jsonl_path: row.jsonl_path, storage }, row.agent_session_id)) {
+        process.stdout.write(`${line}\n`);
+      }
+    }
+  }
+}
+
+function run(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(`${usage()}\n`);
+    return 0;
+  }
+  const db = openReadOnly(args.db);
+  try {
+    const rows = db.prepare(SESSION_QUERY).all(args.since, args.limit)
+      .filter((row) => !args.only || String(row.ctm_session_id).startsWith(args.only));
+    const tallies = new Map();
+    const examples = new Map();
+    for (const row of rows) {
+      const result = scanSession({ ...row, db });
+      tallies.set(result.key, (tallies.get(result.key) || 0) + 1);
+      const list = examples.get(result.key) || [];
+      if (list.length < EXAMPLES_PER_REASON) list.push(prefixed(row.ctm_session_id));
+      examples.set(result.key, list);
+    }
+    printTable(rows, tallies, examples, args);
+    if (args.explain) {
+      const matching = rows.filter((row) => String(row.ctm_session_id).startsWith(args.explain));
+      if (!matching.length) process.stdout.write(`\nexplain ${args.explain}: no matching session\n`);
+      else explainSessions(matching, db);
+    }
+  } finally {
+    db.close();
+  }
+  return 0;
+}
+
+if (require.main === module) {
+  try {
+    process.exitCode = run(process.argv.slice(2));
+  } catch (error) {
+    if (error instanceof UsageError) process.stderr.write(`census-codex-lead-history: ${error.message}\n${usage()}\n`);
+    else process.stderr.write(`census-codex-lead-history: ${error?.stack || error}\n`);
+    process.exitCode = error instanceof UsageError ? 1 : 2;
+  }
+}
+
+module.exports = { run, parseArgs, storageRootForSession, scanSession, firstRefusalIndex };

package/template/coding-task-manager/bin/claude-hook.js

@@ -15,16 +15,20 @@ const http = require('http');
 const crypto = require('crypto');
 const modelGeneration = require('../lib/env-flags').strFlag('CTM_MODEL_PROCESS_GENERATION', '');
 
-// Only these routes can carry a notice back to the model (Claude hook stdout JSON).
-const NOTICE_ROUTES = new Set(['PostToolUse', 'start']);
+// Only these routes can carry a notice back to the model (Claude hook stdout JSON). `stop` is
+// here for RC-1 (docs/session-stops-mid-job-2026-10-24.html D-1): the Stop hook is answered
+// synchronously so a lead that still owns a live worker is told to keep waiting.
+const NOTICE_ROUTES = new Set(['PostToolUse', 'start', 'stop']);
 
 // The hook stdout for a CTM response body: one JSON object when it carries notices, else ''.
+// Against an OLD server that answers {"matched":true} there is no `notices` array, so nothing is
+// printed (D-8, safe in either rollout order).
 function formatHookOutput(responseText, hookEventName) {
   let parsed;
   try { parsed = JSON.parse(responseText); } catch { return ''; }
   const notices = parsed && Array.isArray(parsed.notices) ? parsed.notices : [];
   const texts = notices.map((n) => (n && typeof n.text === 'string' ? n.text : '')).filter(Boolean);
-  if (!texts.length || (hookEventName !== 'PostToolUse' && hookEventName !== 'UserPromptSubmit')) return '';
+  if (!texts.length || !['PostToolUse', 'UserPromptSubmit', 'Stop'].includes(hookEventName)) return '';
   return JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext: texts.join('\n') } });
 }
 

package/template/coding-task-manager/bin/claude-table-parity.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+'use strict';
+
+// WP-2 (docs/reader-claude-table-layout-parity-2026-10-25.html §1.2 the census, §6 the CLI sketch,
+// §8 WP-2, D-7): the census that produced the design's parity floor, kept as a repo tool so a
+// Claude Code upgrade that changes the Markdown-table layout is MEASURED, not guessed (R-8: the
+// port pins one version and there is no runtime switch -- drift is caught here and by the golden
+// fixtures).
+//
+// READ-ONLY. It opens the painted-row stores (`~/.walle/data/painted-rows`) and the provider
+// transcripts (`~/.claude/projects`) read-only: never a database, never a file write. It prints
+// numbers and 8-character session-id prefixes only -- never a painted row, never a cell.
+//
+//   node bin/claude-table-parity.js [--painted DIR] [--projects DIR] [--json]
+//
+// For every session directory that has a painted-row store and a transcript: lex every assistant
+// text block with the repo's own `marked`; every GFM `table` token is one table. Locate the drawing
+// (the first body cell of at least 8 characters, its first 24 characters, searched in the painted
+// rows -- one record per stretch file that holds a hit) and re-draw the table with the SHIPPED
+// renderer (`lib/claude-markdown-ansi.emitMarkdownRows` -> `lib/claude-table-layout`) at every
+// `cols` the session's stretch headers recorded. `predicted` is the form that re-draw took (a row
+// carrying `│` means the box), `identical` the most rows that matched the painted window.
+//
+// Exits 0 always -- a missing store, a torn line or an unknown flag is not a census failure.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const marked = require('marked');
+const { emitMarkdownRows } = require('../lib/claude-markdown-ansi');
+
+// The renderer's own style object (lib/claude-transcript-terminal-renderer.js MARKDOWN_STYLE, as
+// its test copies it). It is not exported; the comparison strips SGR anyway, but `cardLines`
+// styles the `Header:` key through it, so the re-draw must carry it.
+const MD_STYLE = Object.freeze({
+  bold: [1], boldOff: [22],
+  italic: [3], italicOff: [23],
+  del: [9], delOff: [29],
+  code: [38, 5, 180], codeOff: [39],
+  dim: [2],
+});
+
+const SGR_RE = /\x1b\[[0-9;?]*[ -\/]*[@-~]/g;
+const CARD_RULE = '─'.repeat(40); // the vertical form's card separator (RULE_MAX)
+const PROBE_MIN = 8; // a probe cell must be at least this long
+const PROBE_LEN = 24; // ... and only its first 24 characters are searched for
+const WINDOW_BEFORE = 40; // painted rows kept before the hit
+const WINDOW_AFTER = 400; // painted rows kept after the hit
+
+const stripSgr = (text) => String(text == null ? '' : text).replace(SGR_RE, '');
+const trimEnd = (text) => String(text == null ? '' : text).replace(/\s+$/, '');
+
+function parseArgs(argv) {
+  const opts = {
+    painted: path.join(os.homedir(), '.walle', 'data', 'painted-rows'),
+    projects: path.join(os.homedir(), '.claude', 'projects'),
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = String(argv[i]);
+    const eq = arg.indexOf('=');
+    const name = eq < 0 ? arg : arg.slice(0, eq);
+    const inline = eq < 0 ? null : arg.slice(eq + 1);
+    if (name === '--painted') opts.painted = (inline != null ? inline : argv[i + 1]) || opts.painted;
+    else if (name === '--projects') opts.projects = (inline != null ? inline : argv[i + 1]) || opts.projects;
+    else if (name === '--json') opts.json = true;
+  }
+  return opts;
+}
+
+// Immediate sub-directory names of `dir`, sorted (deterministic output). A missing root is a
+// legitimate empty census on a machine that never ran the reader.
+function listDirs(dir) {
+  let entries = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; } /* expected: the store/projects root may not exist here */
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+
+function readText(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch { return ''; } /* expected: a store file may vanish under a live writer */
+}
+
+// One `JSON<TAB>crc` line; the CRC is not verified (the stores are append-only and the census
+// reads numbers, not truth).
+function parseLine(prefix) {
+  try { return JSON.parse(prefix); } catch { return null; } // a torn / non-JSON line is not a record
+}
+
+function findTranscript(projectsRoot, projectDirs, sessionId) {
+  for (const project of projectDirs) {
+    const file = path.join(projectsRoot, project, `${sessionId}.jsonl`);
+    if (fs.existsSync(file)) return file;
+  }
+  return null;
+}
+
+// Every painted row of one session's store: `{ r, f, cols, t }` with `t` = SGR-stripped,
+// right-trimmed text. `cols` is the width the surrounding stretch header recorded (a row written
+// before the first header of the file keeps `null`).
+function readPainted(dir) {
+  const rows = [];
+  for (const file of listFiles(dir).filter((f) => /^stretch-\d+\.jsonl$/.test(f)).sort()) {
+    let cols = null;
+    const text = readText(path.join(dir, file));
+    if (!text) continue;
+    for (const line of text.split('\n')) {
+      const tab = line.lastIndexOf('\t');
+      if (tab < 0) continue;
+      const record = parseLine(line.slice(0, tab));
+      if (!record) continue;
+      if (record.stretch != null && record.cols) cols = record.cols;
+      if (record.r != null) rows.push({ r: record.r, f: file, cols, t: trimEnd(stripSgr(record.a)) });
+    }
+  }
+  return rows;
+}
+
+function listFiles(dir) {
+  try { return fs.readdirSync(dir); } catch { return []; } /* expected: the session store may be pruned between readdir and read */
+}
+
+// Every `table` token of one assistant text block. The `|` pre-check only skips blocks that cannot
+// hold a GFM table -- the decision is `marked`'s, never a local grammar.
+function lexTables(text) {
+  if (!text.includes('|')) return [];
+  let tokens = [];
+  try { tokens = marked.lexer(text, { gfm: true }); } catch { return []; } // an unlexable block holds no table we can census
+  return tokens.filter((token) => token.type === 'table');
+}
+
+// A cell's plain text: `label (href)` for a link (R-3 -- the rendering, not the raw markdown, is
+// what the layout measures) and the literal text everywhere else.
+function cellText(tokens) {
+  let out = '';
+  for (const token of tokens || []) {
+    switch (token.type) {
+      case 'text': case 'escape': out += token.text; break;
+      case 'codespan': out += token.text; break;
+      case 'strong': case 'em': case 'del': out += cellText(token.tokens); break;
+      case 'link': {
+        const label = cellText(token.tokens);
+        out += label === token.href ? label : `${label} (${token.href})`;
+        break;
+      }
+      case 'image': out += `${token.text} (${token.href})`; break;
+      case 'br': out += ' '; break;
+      case 'checkbox': break;
+      default: out += token.text != null ? token.text : (token.raw || '');
+    }
+  }
+  return out;
+}
+
+// The form the LIVE screen drew, read off the hit row and its neighbours: a row starting with the
+// box border is `bordered`; otherwise a 40-dash card rule or a `Header:` label within
+// `2 * columns + 2` rows of the hit says `cards`; anything else is `other` (a drawing we could not
+// classify -- counted, never predicted against).
+function observedForm(hit, painted, labels) {
+  if (/^\s*│/.test(hit.t)) return 'bordered';
+  const near = painted
+    .filter((p) => p.f === hit.f && p.r >= hit.r - 2 && p.r <= hit.r + 2 * labels.length + 2)
+    .map((p) => p.t)
+    .join('\n');
+  if (near.includes(CARD_RULE) || labels.some((label) => label && near.includes(`${label}:`))) return 'cards';
+  return 'other';
+}
+
+// The re-draw: the shipped renderer at `cols`, SGR-stripped and right-trimmed, exactly as the
+// painted rows are.
+function renderRows(markdown, cols) {
+  return emitMarkdownRows(markdown, cols, { markdown: marked, style: MD_STYLE })
+    .map((line) => trimEnd(stripSgr(line)));
+}
+
+// The prediction for one drawing: try every width the session's stretch headers recorded, align the
+// emitted rows to the painted window by the offset with the most identical rows, keep the best
+// width. `predicted` is the form the re-draw took (no `│` row => the stacked cards).
+function predict(raw, widths, window) {
+  let best = null;
+  for (const cols of widths) {
+    const lines = renderRows(raw, cols);
+    let identical = 0;
+    for (let off = 0; off < window.length; off += 1) {
+      let same = 0;
+      for (let i = 0; i < lines.length; i += 1) if (lines[i] === window[off + i]) same += 1;
+      if (same > identical) identical = same;
+    }
+    const candidate = {
+      cols,
+      predicted: lines.some((line) => line.includes('│')) ? 'bordered' : 'cards',
+      identical,
+      emitted: lines.length,
+    };
+    if (!best || candidate.identical > best.identical) best = candidate;
+  }
+  return best;
+}
+
+// One table token -> its record(s): one per stretch file that holds the probe, or a single
+// `notfound` record when no cell is long enough / no painted row matches.
+function locateTable({ sid, index, token, painted, widths }) {
+  const header = (token.header || []).map((cell) => cellText(cell.tokens));
+  const rows = (token.rows || []).map((row) => row.map((cell) => cellText(cell.tokens)));
+  const base = { sid: sid.slice(0, 8), table: index, columns: header.length, rows: rows.length };
+  const probe = (rows[0] || []).find((cell) => cell && cell.length >= PROBE_MIN)
+    || header.find((cell) => cell && cell.length >= PROBE_MIN)
+    || '';
+  if (!probe) return [{ ...base, form: 'notfound', predicted: null, identical: 0, emitted: 0, cols: null }];
+  const key = probe.slice(0, PROBE_LEN);
+  const hits = new Map(); // file -> the first painted row of that file holding the probe
+  for (const row of painted) if (!hits.has(row.f) && row.t.includes(key)) hits.set(row.f, row);
+  if (hits.size === 0) return [{ ...base, form: 'notfound', predicted: null, identical: 0, emitted: 0, cols: null }];
+  const out = [];
+  for (const hit of hits.values()) {
+    const window = painted
+      .filter((p) => p.f === hit.f && p.r >= hit.r - WINDOW_BEFORE && p.r <= hit.r + WINDOW_AFTER)
+      .map((p) => p.t);
+    const candidates = widths.length ? widths : (hit.cols ? [hit.cols] : []);
+    const best = predict(token.raw, candidates, window) || { cols: hit.cols, predicted: null, identical: 0, emitted: 0 };
+    out.push({ ...base, at: hit.r, form: observedForm(hit, painted, header), ...best });
+  }
+  return out;
+}
+
+function census(opts) {
+  const storeDirs = listDirs(opts.painted);
+  const projectDirs = listDirs(opts.projects);
+  const records = [];
+  let sessionsWithStore = 0;
+  let sessionsPaired = 0;
+  let tables = 0;
+  for (const sid of storeDirs) {
+    sessionsWithStore += 1;
+    const transcript = findTranscript(opts.projects, projectDirs, sid);
+    if (!transcript) continue;
+    sessionsPaired += 1;
+    const painted = readPainted(path.join(opts.painted, sid));
+    const widths = [...new Set(painted.map((row) => row.cols).filter(Boolean))];
+    let index = 0;
+    for (const line of readText(transcript).split('\n')) {
+      const message = parseLine(line);
+      if (!message || !message.message || message.message.role !== 'assistant') continue;
+      const parts = Array.isArray(message.message.content)
+        ? message.message.content
+        : [{ type: 'text', text: message.message.content }];
+      for (const part of parts) {
+        if (!part || part.type !== 'text' || typeof part.text !== 'string') continue;
+        for (const token of lexTables(part.text)) {
+          index += 1;
+          tables += 1;
+          records.push(...locateTable({ sid, index, token, painted, widths }));
+        }
+      }
+    }
+  }
+
+  const observed = { bordered: 0, cards: 0, other: 0, notfound: 0 };
+  for (const record of records) observed[record.form] = (observed[record.form] || 0) + 1;
+  // `drawings` = the drawings whose form we could read (bordered + cards) -- the denominator of
+  // predictedAgree, the number the design's floor (313 of 328, §1.2) is stated against. `other`
+  // hits and `notfound` tables are carried in `observed` and never predicted against.
+  const drawings = observed.bordered + observed.cards;
+  const found = records.filter((record) => record.form === 'bordered' || record.form === 'cards');
+  const predictedAgree = found.filter((record) => record.predicted === record.form).length;
+  const byteIdentical = found.filter((record) => record.emitted > 0 && record.identical === record.emitted).length;
+  const within2 = found.filter((record) => record.emitted > 0 && record.identical >= record.emitted - 2).length;
+  return {
+    summary: {
+      sessionsWithStore,
+      sessionsPaired,
+      tables,
+      drawings,
+      observed,
+      predictedAgree,
+      predictedDisagree: found.length - predictedAgree,
+      byteIdentical,
+      within2,
+    },
+    records,
+  };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const { summary, records } = census(opts);
+  process.stdout.write(`${JSON.stringify(summary)}\n`);
+  if (opts.json) return;
+  // Disagreement list: the observed form the prediction missed, or a re-draw that lost more than
+  // two rows of the painted drawing. Numbers and an 8-character session prefix only -- no cell.
+  const disagreements = records
+    .filter((record) => record.form !== 'notfound'
+      && (record.predicted !== record.form || record.identical < record.emitted - 2))
+    .sort((a, b) => (a.sid === b.sid ? a.table - b.table : a.sid.localeCompare(b.sid)));
+  for (const record of disagreements) {
+    process.stdout.write(`${record.sid} table#${record.table} cols=${record.cols} `
+      + `observed=${record.form} predicted=${record.predicted} identical=${record.identical}/${record.emitted}\n`);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  // The census is a report, not a test: an unexpected failure is printed on stderr and still
+  // exits 0 (numbers only -- never a painted row or a cell).
+  process.stderr.write(`claude-table-parity: ${error && error.message ? error.message : String(error)}\n`);
+}
+process.exitCode = 0;