create-walle 0.10.1 → 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/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();