create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/bin/repair-resume-echo-titles.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+'use strict';
+
+// Repair "resume echo" titles (design doc session-name-agent-title-precedence §1e/§8 WP-6).
+//
+// A CTM session named after the harness's own resume boilerplate ("Resume: …", "Continue the
+// conversation…") instead of the name the agent wrote into its own transcript is the bug WP-0..5
+// fixes for NEW ingests. For rows that were already mis-titled, this script, per id:
+//
+//   1. demotes the row back to a CTM-generated name — user_renamed=0, title_source='ai_title',
+//      title_status='generated', title_status_reason='demoted_resume_echo' — so tier 2 may write
+//      again, then
+//   2. re-runs WP-6's per-row backfill for that id: the SAME read-pool op the boot job uses
+//      ('backfillAgentTitles', one ≤64 KiB transcript tail read) and the SAME applier
+//      (lib/agent-title-apply.js applyAgentTitleSignals — the ONLY tier-2 apply).
+//
+// The initial id list this was written for (2026-10-23; NOT applied automatically — pass the ids
+// explicitly). Kept here as documentation, never as code:
+//
+//   21b4bb0b-b889-4c7f-b8b8-fa333291fdd4
+//
+// Usage:
+//   node bin/repair-resume-echo-titles.js <id> [<id> …] [--db <path>] [--apply] [--force]
+//   node bin/repair-resume-echo-titles.js --ids <id,id,…> [--db <path>] [--apply]
+//
+// Dry run by default: each id's demote + apply runs in one IMMEDIATE transaction that is ROLLED
+// BACK, so the printed before → after is exactly what --apply would write and nothing persists.
+// --apply commits. --db picks the database file; with no --db the script uses CTM's own resolver
+// (lib/data-dir.js + lib/domain-db-paths.js), i.e. <data dir>/task-manager.db and its core
+// sibling if this install is flipped.
+//
+// ABSOLUTE RULE (same as bin/conversation-adopt-self-links.js): run this against a STOPPED CTM or
+// a copy — NEVER against ports 3456/3457's live database, whose owning CTM keeps its own copy of
+// these rows in memory and would overwrite the repair on its next write. --apply refuses a
+// database whose -wal was written in the last 60 s unless --force is passed. The documented path
+// is: stop CTM first, or work on a copy.
+//
+// Exit codes: 0 success, 2 refusal (bad args, missing file, looks live), 1 error.
+
+// No CTM_PROCESS_ROLE here on purpose: this script never calls db.js initDb() — it opens the
+// sqlite files itself — so the process identity CTM_PROCESS_ROLE exists for has no reader here,
+// and setting it would mean a new raw flag read for nothing (bin/flag-lint.js).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { loadSqliteDriver } = require('../lib/sqlite-driver');
+const { getDataDir } = require('../lib/data-dir');
+const { resolveDomainDbPath } = require('../lib/domain-db-paths');
+const { applyAgentTitleSignals } = require('../lib/agent-title-apply');
+const { createReadPoolClient } = require('../lib/read-pool-client');
+
+const DEMOTE_REASON = 'demoted_resume_echo';
+const REQUEST_TIMEOUT_MS = 30000;
+const ROW_COLUMNS = 'title, title_source, title_status, title_status_reason, user_renamed, '
+  + 'title_mirror_state, title_mirror_value';
+
+function arg(name, fallback = '') {
+  const index = process.argv.indexOf(name);
+  if (index < 0) return fallback;
+  const value = process.argv[index + 1];
+  return value != null && !value.startsWith('--') ? value : fallback;
+}
+const has = (name) => process.argv.includes(name);
+
+// A WAL sidecar that is being actively written is the cheap, honest signal that another
+// process (the primary) owns this database. Copied from bin/conversation-adopt-self-links.js.
+function looksLive(dbPath) {
+  try {
+    const wal = fs.statSync(`${dbPath}-wal`);
+    return wal.size > 0 && (Date.now() - wal.mtimeMs) < 60_000;
+  } catch {
+    /* expected: no -wal sidecar (or an unstattable one) means nobody is writing this
+       database right now, which is exactly the "not live" answer. */
+    return false;
+  }
+}
+
+function refuse(message) {
+  console.error(`ERROR: ${message}`);
+  process.exit(2);
+}
+
+// Positional ids, plus `--ids a,b,c`. Every other flag (and its value) is skipped, so
+// `--db <path>` can never be mistaken for a session id.
+function parseIds() {
+  const argv = process.argv.slice(2);
+  const out = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = String(argv[i]);
+    if (item === '--ids') { out.push(...String(argv[i + 1] || '').split(',')); i += 1; continue; }
+    if (item === '--db') { i += 1; continue; }
+    if (item.startsWith('--')) continue;
+    out.push(item);
+  }
+  return [...new Set(out.map((id) => id.trim()).filter(Boolean))];
+}
+
+function tableExists(handle, table) {
+  try {
+    return !!handle.prepare('SELECT 1 FROM sqlite_master WHERE type = ? AND name = ?').get('table', table);
+  } catch {
+    return false; // expected: an unreadable/foreign sqlite file is "no such table" here, never a crash
+  }
+}
+
+// The file that actually holds ctm_sessions + agent_sessions: the given file when it already does
+// (an explicit core.db, or a pre-split task-manager.db), otherwise its flipped core sibling.
+function resolveCorePath(basePath) {
+  const Database = loadSqliteDriver({ source: 'repair-resume-echo-titles' });
+  const probe = new Database(basePath, { readonly: true, fileMustExist: true });
+  try {
+    if (tableExists(probe, 'ctm_sessions')) return basePath;
+  } finally {
+    probe.close();
+  }
+  return resolveDomainDbPath('core', basePath, { flipped: true });
+}
+
+/**
+ * Demote + re-title ONE id. The write half runs in its own IMMEDIATE transaction, committed by
+ * --apply and rolled back otherwise — that is what makes a dry run print the real after-state
+ * while writing nothing. The transaction is opened AFTER the await, never across it: the tail read
+ * belongs to the read pool, and a write lock must not be held while waiting on another process.
+ */
+async function repairOne({ core, pool, basePath, id, apply }) {
+  const readRow = () => core.prepare(`SELECT ${ROW_COLUMNS} FROM ctm_sessions WHERE id = ?`).get(id);
+  const before = readRow();
+  if (!before) return { id, action: 'skip', reason: 'no_row' };
+  // Presence check only — the read op resolves the file itself, by the same "latest agent_sessions
+  // row" rule db.js's display path uses (a stitched continuation adds a row).
+  const transcript = String(core.prepare(`
+    SELECT jsonl_path FROM agent_sessions WHERE ctm_session_id = ?
+     ORDER BY COALESCE(NULLIF(modified_at, ''), updated_at, created_at) DESC,
+       updated_at DESC, created_at DESC
+     LIMIT 1
+  `).get(id)?.jsonl_path || '');
+  // 1. re-run the per-row backfill: the boot job's own read op, scoped to this id.
+  let signal = null;
+  if (transcript) {
+    const page = await pool.request('backfillAgentTitles', {
+      dbPath: basePath, ids: [id], limit: 1,
+    }, { timeoutMs: REQUEST_TIMEOUT_MS });
+    const row = (Array.isArray(page?.rows) ? page.rows : []).find((r) => r.id === id);
+    if (row) {
+      signal = {
+        customTitle: row.customTitle || '',
+        aiTitle: row.aiTitle || '',
+        tailBytes: row.tailBytes,
+        jsonlPath: String(row.jsonlPath || transcript),
+      };
+    }
+  }
+  // 2. demote (D-1: tier 1 off, tier 3 restated, so the applier below is allowed to write) and
+  //    apply — one synchronous burst, no awaits.
+  core.exec('BEGIN IMMEDIATE');
+  let outcome = null;
+  let labelSynced = false;
+  let after = null;
+  try {
+    core.prepare(`
+      UPDATE ctm_sessions
+         SET user_renamed = 0, title_source = 'ai_title', title_status = 'generated',
+             title_status_reason = ?
+       WHERE id = ?
+    `).run(DEMOTE_REASON, id);
+    outcome = signal
+      ? applyAgentTitleSignals(core, { ctmSessionId: id, customTitle: signal.customTitle, aiTitle: signal.aiTitle })
+      : { applied: 'none', reason: transcript ? 'no_title_signal' : 'no_transcript', reassert: false };
+    if (outcome.applied === 'agent' && outcome.title) {
+      // D-13: the restore label and the durable title must never disagree. This is a local repair —
+      // it does not enqueue the multi-machine sync outbox row, which db.js's own
+      // updateStartupTaskLabel owns (see lib/agent-title-apply.js's header).
+      labelSynced = core.prepare('UPDATE startup_tasks SET label = ? WHERE ctm_session_id = ?')
+        .run(outcome.title, id).changes > 0;
+    }
+    // The dry run's whole point: this read happens INSIDE the transaction, so a rolled-back run
+    // still reports the state --apply would have left behind.
+    after = readRow();
+    core.exec(apply ? 'COMMIT' : 'ROLLBACK');
+  } catch (error) {
+    try { core.exec('ROLLBACK'); } catch { /* expected: a failed statement may already have aborted the transaction */ }
+    throw error;
+  }
+  return {
+    id,
+    action: 'demoted+retitled',
+    // The file the read op actually read, which is the row's latest transcript.
+    transcript: signal?.jsonlPath || transcript,
+    tailBytes: signal?.tailBytes ?? null,
+    signal: signal ? { customTitle: signal.customTitle || '', aiTitle: signal.aiTitle || '' } : null,
+    apply: outcome.applied,
+    reason: outcome.reason,
+    title: outcome.title || null,
+    labelSynced,
+    before,
+    after,
+  };
+}
+
+async function main() {
+  const ids = parseIds();
+  if (ids.length === 0) refuse('at least one session id is required (see the header comment)');
+  const apply = has('--apply');
+  const dbArg = String(arg('--db') || '').trim();
+  const basePath = path.resolve(dbArg || path.join(getDataDir(), 'task-manager.db'));
+  if (!fs.existsSync(basePath)) refuse(`db not found: ${basePath}`);
+  const corePath = resolveCorePath(basePath);
+  if (!fs.existsSync(corePath)) refuse(`core db not found: ${corePath} (resolved from ${basePath})`);
+  if (apply && !has('--force')) {
+    for (const candidate of [basePath, corePath]) {
+      if (!looksLive(candidate)) continue;
+      console.error(`ERROR: ${candidate} looks like a LIVE database (recent -wal writes).`);
+      console.error('       Stop CTM and re-run, work on a copy, or pass --force.');
+      process.exit(2);
+    }
+  }
+
+  const Database = loadSqliteDriver({ source: 'repair-resume-echo-titles' });
+  const core = new Database(corePath, {});
+  core.pragma('busy_timeout = 30000');
+  const pool = createReadPoolClient({ size: 1, requestTimeoutMs: REQUEST_TIMEOUT_MS, closeTimeoutMs: 2000 });
+  const counts = { repaired: 0, skipped: 0 };
+  try {
+    await pool.start();
+    for (const id of ids) {
+      const line = await repairOne({ core, pool, basePath, id, apply });
+      if (line.action === 'skip') counts.skipped += 1;
+      else counts.repaired += 1;
+      console.log(JSON.stringify({ ...line, dryRun: !apply }));
+    }
+    console.log(JSON.stringify({ summary: true, dryRun: !apply, ids: ids.length, ...counts }));
+  } finally {
+    try { await pool.close(); } catch { /* expected: the pool may never have started */ }
+    try { core.close(); } catch { /* expected: closing an already-closed handle is not an error here */ }
+  }
+}
+
+if (require.main === module) {
+  main()
+    .catch((error) => {
+      // REPORT: print the failure and exit 1; nothing is retried.
+      console.error(`[repair-resume-echo-titles] ${error && error.stack ? error.stack : String(error)}`);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { looksLive, parseIds, resolveCorePath, DEMOTE_REASON };

package/template/coding-task-manager/bin/seam-replay-codex.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+'use strict';
+
+// bin/seam-replay-codex.js -- the Codex lane of the reader seam replay harness (design
+// seam-proof-r3-codex-render-parity-2026-10-20, WP-0 / §6).
+//
+// Offline and read-only. For every Codex CTM session that still has a painted-row store, replay the
+// RECORDED live screen (a store `seal` record's `ref.rows`) against CTM's own render of the session's
+// rollouts AS THEY STOOD AT THE SEAL TIME, through the shipped join, and print COUNTS as JSON:
+//
+//   sessions   Codex sessions (core.db: ctm_sessions.provider = 'codex') with at least one rollout on
+//              disk AND a store directory, that contributed at least one taken seal.
+//   screens    seals that reached the join: the rollout rendered rows at the seal's cut, and the screen
+//              held MIN_LIVE_ROWS non-blank rows.
+//   unreplayable  seals whose render threw, produced no rows, or whose screen was too small to be one.
+//   byKind     what findJoin decided: proven / overlap / none.
+//   why        for a `none`, landingDiag's own refusal (`noknown` / `cover` / `loss` / `cut` / ...).
+//   dup3       `none` screens whose live rows repeat >= DUP3_MIN transcript-window rows (the visibly
+//              duplicated population the design measures).
+//   headerRows screens whose first live row is Codex's own `› ` prompt header (WP-3 changes what
+//              the join does with it; this counts how often it is there).
+//   hiddenTextRowsNotOnScreen  proofs whose rows [cut, end) hold an evidence row with a cut word the
+//              live screen does not show. Must be 0: it is the join's own safety claim.
+//
+// The render is the SHIPPED lib/raw-codex-history-window.js `getRawCodexHistoryWindow`, fed every
+// rollout of the session with a `fileOps` whose `fstatSync` caps `size` at the seal's cut, so the
+// window is what the rollout held at that moment. Nothing is ever written: no file is opened for
+// writing, no copy of a rollout is made, and the core.db handle is opened read-only and closed before
+// the replay starts.
+//
+// PRIVACY (hard, the same rule as bin/seam-replay.js): never prints row text, transcript lines, file
+// paths, file contents or a full session id. The report is JSON numbers, enums and the fixed key names
+// below -- nothing else.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const Database = require('better-sqlite3');
+const Raw = require('../lib/raw-codex-history-window.js');
+const RowJoin = require('../public/js/row-join.js');
+// The store's PURE reader only (`parseBuffer` verifies every line's CRC and stops at the first bad
+// one). `createPaintedRowStore` is never called from here, so nothing is written, pruned or swept.
+const { parseBuffer } = require('../lib/painted-row-store.js');
+
+const DEFAULT_PER = 40; // newest N seals per session (the same default as the Claude lane)
+const MAX_ROWS = 400; // rows the renderer may return (design §6: 400 / 1 MiB)
+const MAX_BYTES = 1 << 20;
+const SCAN_CHUNK_BYTES = 1 << 24; // 16 MiB: rollouts can be large, so the timestamp scan is chunked
+const STAMP_SCAN_BYTES = 120; // the `"timestamp"` field must be inside a line's first 120 bytes
+const MIN_LIVE_ROWS = 3; // a screen with fewer non-blank live rows is not a screen
+const DUP3_MIN = 3; // `landingDiag().dup >= 3` is the visibly-duplicated population
+const SID_PREFIX = 8; // never used for printing a full id; kept for callers that need one
+// 46 bytes, well over the 32 the cursor signer demands. Local to this script: a cursor is never
+// round-tripped here (each seal starts a fresh `older` read), so the value only has to be constant.
+const CURSOR_SECRET = 'seam-replay-codex-offline-replay-cursor-secret';
+const STRETCH_FILE_RE = /^stretch-\d+\.jsonl$/; // one stretch of a painted-row store session
+const CODEX_PROMPT_HEADER = /^› /u; // Codex's own presentation-only prompt header row
+// The Codex sessions and their rollouts. Read-only; `jsonl_path <> ''` skips a session with no file.
+const CODEX_SESSIONS_SQL = "select a.ctm_session_id sid, a.jsonl_path p from agent_sessions a "
+  + "join ctm_sessions c on c.id = a.ctm_session_id "
+  + "where c.provider = 'codex' and a.provider = 'codex' and a.jsonl_path <> '' order by a.jsonl_path";
+
+const defaultStore = () => path.join(os.homedir(), '.walle', 'data', 'painted-rows');
+const defaultCoreDb = () => path.join(os.homedir(), '.walle', 'data', 'core.db');
+
+// --- text handling ---------------------------------------------------------
+
+// The Claude lane's `strip` (bin/seam-replay.js), which is byte for byte RowJoin.stripForCompare:
+// SGR/CSI removed, U+00A0 folded to a space, trailing blanks trimmed. Delegating to the join's own
+// copy keeps one truth (and findJoin strips every row it is handed with it anyway).
+function strip(text) {
+  return RowJoin.stripForCompare(text);
+}
+
+function inc(counts, key) {
+  counts[key] = (counts[key] || 0) + 1;
+}
+
+// --- core.db (read-only) ---------------------------------------------------
+
+// Codex CTM sessions with at least one rollout still on disk: sid -> [rollout path], in path order.
+// The DB handle is opened read-only (`fileMustExist`) and closed before anything else runs; a session
+// whose rollout file has gone is dropped here rather than counted.
+function codexSessions(coreDb) {
+  const db = new Database(coreDb, { readonly: true, fileMustExist: true });
+  let pairs = [];
+  try {
+    pairs = db.prepare(CODEX_SESSIONS_SQL).all();
+  } finally {
+    db.close();
+  }
+  const bySid = new Map();
+  for (const row of pairs) {
+    const file = String(row.p == null ? '' : row.p);
+    if (!file || !fs.existsSync(file)) continue;
+    const sid = String(row.sid == null ? '' : row.sid);
+    const list = bySid.get(sid);
+    if (list) list.push(file);
+    else bySid.set(sid, [file]);
+  }
+  return bySid;
+}
+
+// --- the recorded screens --------------------------------------------------
+
+// Every `seal` record of one session directory, in file order (`stretch-*.jsonl` sorted by name, so
+// the oldest stretch first). Each line's CRC is verified by the store's own reader; a file that is
+// missing, unreadable or torn past its first bad line contributes only what it verified.
+function readSeals(dir) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return []; /* expected: the session directory went away between the store scan and the read */
+  }
+  const seals = [];
+  for (const name of names.filter((n) => STRETCH_FILE_RE.test(n)).sort()) {
+    let buffer;
+    try {
+      buffer = fs.readFileSync(path.join(dir, name));
+    } catch {
+      continue; /* expected: a stretch file unreadable between the listing and the read */
+    }
+    for (const object of parseBuffer(buffer).objects) {
+      if (object.op !== 'seal' || !object.ref || !Array.isArray(object.ref.rows)) continue;
+      if (typeof object.at !== 'number') continue;
+      seals.push(object);
+    }
+  }
+  return seals;
+}
+
+// The timestamp marks of one rollout: `[parsedMs, byteOffset]` for every line whose first
+// STAMP_SCAN_BYTES bytes hold a `"timestamp":"..."` field, in file order, plus the file size. Read in
+// SCAN_CHUNK_BYTES chunks with a carry, because a rollout can hold more than one chunk and the scan is
+// per line, not per chunk. Read-only: the file is opened 'r' and closed before returning.
+function timestampMarks(file) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const marks = [];
+    let carry = Buffer.alloc(0);
+    let base = 0;
+    for (let offset = 0; offset < size; offset += SCAN_CHUNK_BYTES) {
+      const chunk = Buffer.alloc(Math.min(SCAN_CHUNK_BYTES, size - offset));
+      fs.readSync(fd, chunk, 0, chunk.length, offset);
+      const buffer = carry.length ? Buffer.concat([carry, chunk]) : chunk;
+      let position = 0;
+      for (;;) {
+        const newline = buffer.indexOf(10, position);
+        if (newline < 0) break;
+        const line = buffer.subarray(position, Math.min(newline, position + STAMP_SCAN_BYTES)).toString('utf8');
+        const match = line.match(/"timestamp":"([^"]+)"/);
+        if (match) marks.push([Date.parse(match[1]), base + position]);
+        position = newline + 1;
+      }
+      carry = buffer.subarray(position);
+      base += position;
+    }
+    return { size, marks };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// The byte offset a seal's view of a rollout ends at: the offset of the FIRST line whose timestamp is
+// after the seal, else the whole file (the rollout never went further than the seal).
+function cutFor(marks, size, at) {
+  for (const [ms, offset] of marks) if (ms > at) return offset;
+  return size;
+}
+
+// Is `sid` a session the store still has a directory for? A store without one is simply not replayed.
+function hasStoreDir(store, sid) {
+  try {
+    return fs.statSync(path.join(store, sid)).isDirectory();
+  } catch {
+    return false; /* expected: no store directory for this session (or it is not a directory) */
+  }
+}
+
+// --- the join --------------------------------------------------------------
+
+// The safety count (design §7): does a proof's hidden tail hold an EVIDENCE row with a cut word the
+// live screen does not show? Rows, not words; nothing is printed.
+function hidesEvidenceRow(rows, kinds, live, cut) {
+  const liveWords = new Set();
+  for (const row of live) for (const word of RowJoin.cutWordsOf(row)) liveWords.add(word);
+  for (let i = Math.max(0, cut); i < rows.length; i += 1) {
+    if (kinds && kinds[i] !== 'text' && kinds[i] !== 'prompt') continue;
+    if (RowJoin.cutWordsOf(strip(rows[i])).some((word) => !liveWords.has(word))) return true;
+  }
+  return false;
+}
+
+// Replay ONE seal: render the session's rollouts as they stood at `seal.at`, join the recorded screen
+// against them, and tally. Mutates `report`; returns nothing. Counts and enums only, ever.
+function replaySeal(report, sid, seal, scans) {
+  const cutOf = new Map();
+  for (const scan of scans) cutOf.set(scan.file, cutFor(scan.marks, scan.size, seal.at));
+  const sources = [];
+  for (const scan of scans) {
+    const cut = cutOf.get(scan.file);
+    if (cut > 0) sources.push({ jsonl_path: scan.file, provider: 'codex', size: cut, offset: cut });
+  }
+  // No rollout held a byte at the seal time: there is no screen to replay and no join to make.
+  if (!sources.length) return;
+  // The cut is a `fstat` size cap, nothing more: the window reads the real files (read-only) and stops
+  // at the sealed size. `fd` -> path is remembered so a copied stat can be capped per source.
+  const fdPath = new Map();
+  const fileOps = {
+    ...fs,
+    openSync(file, ...args) {
+      const fd = fs.openSync(file, ...args);
+      fdPath.set(fd, String(file));
+      return fd;
+    },
+    fstatSync(fd) {
+      const stat = fs.fstatSync(fd);
+      const cut = cutOf.get(fdPath.get(fd));
+      return Object.assign(Object.create(Object.getPrototypeOf(stat)), stat, {
+        size: cut === undefined ? stat.size : Math.min(stat.size, cut),
+      });
+    },
+  };
+  let win;
+  try {
+    win = Raw.getRawCodexHistoryWindow(sources, {
+      sessionId: sid, provider: 'codex', cols: seal.ref.cols, maxRows: MAX_ROWS, maxBytes: MAX_BYTES, cursorSecret: CURSOR_SECRET,
+    }, fileOps);
+  } catch {
+    report.unreplayable += 1; /* expected: a rollout shape the renderer refuses (counted, never printed) */
+    return;
+  }
+  const items = win.items || [];
+  const rows = win.rows || items.map((item) => item.content);
+  if (!rows.length) {
+    report.unreplayable += 1; /* expected: a render that produced no rows (counted, never printed) */
+    return;
+  }
+  const kinds = items.length === rows.length ? items.map((item) => item.kind) : undefined;
+  const live = seal.ref.rows.slice(seal.ref.pinned || 0).map(strip);
+  if (live.filter((row) => row.trim()).length < MIN_LIVE_ROWS) {
+    report.unreplayable += 1; /* expected: a screen too small to be one (counted, never printed) */
+    return;
+  }
+  report.screens += 1;
+  const found = RowJoin.findJoin({ transcriptRows: rows, transcriptKinds: kinds, painted: { from: 0, rows: [] }, liveRows: live, appBelow: 0 });
+  inc(report.byKind, found.kind);
+  if (found.kind === 'none') {
+    const diag = RowJoin.landingDiag(rows, live, kinds);
+    inc(report.why, diag.why);
+    if (diag.dup >= DUP3_MIN) report.dup3 += 1;
+  }
+  if (CODEX_PROMPT_HEADER.test(live[0] || '')) report.headerRows += 1;
+  if (found.kind !== 'none' && hidesEvidenceRow(rows, kinds, live, found.cut)) report.hiddenTextRowsNotOnScreen += 1;
+}
+
+// --- the run ---------------------------------------------------------------
+
+// The whole `--codex` mode (design §6). Returns the report object; the counts are the only thing an
+// operator reads, and the caller prints it as JSON. `opts`:
+//   per      newest N seals per session (default DEFAULT_PER)
+//   until    an ISO time (or epoch ms) -- seals at or after it are not taken; null = no limit
+//   store    painted-rows root (default ~/.walle/data/painted-rows)
+//   coreDb   CTM core database (default ~/.walle/data/core.db), opened READ-ONLY
+function runCodex(opts) {
+  const options = opts || {};
+  const per = Number(options.per) > 0 ? Math.floor(Number(options.per)) : DEFAULT_PER;
+  const until = options.until === null || options.until === undefined || options.until === ''
+    ? null
+    : (typeof options.until === 'number' ? options.until : Date.parse(String(options.until)));
+  if (until !== null && !Number.isFinite(until)) throw new TypeError('--until must be an ISO time');
+  const report = {
+    mode: 'codex',
+    until: until === null ? null : new Date(until).toISOString(),
+    per,
+    sessions: 0,
+    screens: 0,
+    unreplayable: 0,
+    byKind: { proven: 0, overlap: 0, none: 0 },
+    why: {},
+    dup3: 0,
+    headerRows: 0,
+    hiddenTextRowsNotOnScreen: 0,
+  };
+  const store = options.store ? String(options.store) : defaultStore();
+  for (const [sid, paths] of codexSessions(options.coreDb ? String(options.coreDb) : defaultCoreDb())) {
+    if (!hasStoreDir(store, sid)) continue;
+    const seals = readSeals(path.join(store, sid))
+      .filter((seal) => until === null || seal.at <= until)
+      .slice(-per);
+    if (!seals.length) continue;
+    report.sessions += 1;
+    const scans = paths.map((file) => Object.assign({ file }, timestampMarks(file)));
+    for (const seal of seals) replaySeal(report, sid, seal, scans);
+  }
+  return report;
+}
+
+module.exports = { runCodex, defaultStore, defaultCoreDb, DEFAULT_PER, MAX_ROWS, MAX_BYTES, SID_PREFIX };

package/template/coding-task-manager/bin/write-lock-bench.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+'use strict';
+
+// AC-1h (coding-task-manager/docs/fsevents-churn-kernel-write-lock-2026-10-23.html §8): measure
+// the cost of one UNCONTENDED locked write through the installed module, on a throwaway temp
+// database, and print the distribution. The pre-WP-1 link-claim mechanism measured 913–2,797 µs
+// per cycle; the kernel-backed protocol's budget is p50 ≤ 100 µs.
+//
+//   node bin/write-lock-bench.js --cycles 5000
+//
+// This is a measurement, not a gate: it always exits 0 and prints whether the budget was met.
+// The cycle measured is a full `createSqliteWriteLock(...)(fn)` round trip — kernel BEGIN
+// EXCLUSIVE, the fence, the 1,024-byte in-place identity write, and the COMMIT — i.e. everything
+// a wrapped write pays before and after the caller's own statement.
+//
+// Adapted from the WP-0 exploration harness (scratchpad/lockexp/mech.js), which compared the
+// candidate mechanisms; this file keeps only the shipped one, so the numbers stay comparable to
+// the ones quoted in the design doc.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const Database = require('better-sqlite3');
+
+const { createSqliteWriteLock, closeSqliteWriteLocksForTests } = require('../../shared/sqlite-write-lock');
+
+const AC_1H_P50_BUDGET_US = 100;
+const DEFAULT_CYCLES = 2000;
+
+function parseCycles(argv) {
+  const index = argv.indexOf('--cycles');
+  if (index === -1) return DEFAULT_CYCLES;
+  const raw = argv[index + 1];
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    console.error(`write-lock-bench: --cycles needs a positive integer, got ${JSON.stringify(raw)}`);
+    process.exit(2);
+  }
+  return value;
+}
+
+// Nearest-rank percentile over an ascending array.
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const rank = Math.ceil((p / 100) * sorted.length);
+  return sorted[Math.min(sorted.length - 1, Math.max(0, rank - 1))];
+}
+
+function main() {
+  const cycles = parseCycles(process.argv.slice(2));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'write-lock-bench-'));
+  const lockPath = path.join(dir, 'bench.db.write-lock');
+  const lock = createSqliteWriteLock(lockPath, { Database, label: 'bench' });
+  const warmup = Math.min(200, Math.max(1, Math.floor(cycles / 10)));
+  const samples = new Float64Array(cycles);
+  const hold = [];
+
+  try {
+    // Warmup absorbs the one-time costs (lock DB creation, the record's first write, the
+    // journal's first open) so the distribution describes steady state, which is what AC-1h
+    // compares against the baseline.
+    for (let i = 0; i < warmup; i += 1) lock(() => {}, 'bench');
+    for (let i = 0; i < cycles; i += 1) {
+      const started = process.hrtime.bigint();
+      lock(() => {}, 'bench');
+      samples[i] = Number(process.hrtime.bigint() - started) / 1000;
+    }
+  } finally {
+    closeSqliteWriteLocksForTests();
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* expected: best-effort removal of the throwaway bench directory; a leaked temp dir must
+         not turn a successful measurement into a failed run. */
+    }
+  }
+
+  const sorted = Float64Array.prototype.slice.call(samples).sort((a, b) => a - b);
+  const total = sorted.reduce((sum, value) => sum + value, 0);
+  const p50 = percentile(sorted, 50);
+  const report = {
+    // The mechanism is named without its lock-path literal on purpose: that literal is confined to
+    // shared/sqlite-write-lock.js by bin/lint-shared-copy-parity.js (E-2), because an unrelated
+    // open()+close() on it drops a live holder's POSIX lock (D-6).
+    mechanism: 'kernel write lock (BEGIN EXCLUSIVE on the module\'s lock DB, protocol 2)',
+    cycles,
+    warmupCycles: warmup,
+    platform: `${process.platform}/${process.arch} node ${process.version}`,
+    p50us: Number(p50.toFixed(1)),
+    p95us: Number(percentile(sorted, 95).toFixed(1)),
+    p99us: Number(percentile(sorted, 99).toFixed(1)),
+    minUs: Number(sorted[0].toFixed(1)),
+    maxUs: Number(sorted[sorted.length - 1].toFixed(1)),
+    meanUs: Number((total / sorted.length).toFixed(1)),
+    budgetP50us: AC_1H_P50_BUDGET_US,
+    withinBudget: p50 <= AC_1H_P50_BUDGET_US,
+  };
+  console.log(`[write-lock-bench] ${report.platform}`);
+  console.log(
+    `[write-lock-bench] cycles=${report.cycles} (warmup ${report.warmupCycles}) `
+    + `p50=${report.p50us}µs p95=${report.p95us}µs p99=${report.p99us}µs `
+    + `min=${report.minUs}µs max=${report.maxUs}µs mean=${report.meanUs}µs`,
+  );
+  console.log(
+    `[write-lock-bench] AC-1h budget p50 <= ${report.budgetP50us}µs: `
+    + `${report.withinBudget ? 'MET' : 'MISSED'} (baseline link-claim: 913–2,797µs)`,
+  );
+  console.log(JSON.stringify(report));
+}
+
+main();