create-walle 0.10.1 → 0.10.2

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;

package/template/coding-task-manager/bin/conversation-storage-auto-migration-lib.js

@@ -15,6 +15,9 @@ const {
   bindObservedDatabaseGenerations,
 } = require('./conversation-storage-generation-evidence');
 const { inspectCompletedMarker } = require('./conversation-storage-completed-marker');
+// WP-3 (clock-free r5 R-4..R-8): walle liveness from the write-lock identity record, the
+// proven-owned daemon stop before the first walle write, and a fail-closed foreign holder.
+const { ensureWalleOwnerStopped } = require('./conversation-storage-walle-owner');
 // No-op when options.profile is absent so behaviour is byte-identical to today: this
 // module only ever calls profile.measure/measureAsync around existing calls, never adds
 // new work, so an absent profile just means the timing calls disappear.
@@ -475,7 +478,13 @@ function runAutomaticConversationMigration(options = {}) {
       }
     }
     if (!state.irreversibleAt) {
-      profile.measure('assert_databases_offline', () => _assertDatabasesOffline(specs));
+      // R-5/R-8: stop this instance's PROVEN-OWNED Wall-E before the first walle write, and
+      // probe only the databases this run will mutate -- `specs` included a live walle in a
+      // CTM-only rerun, which blocked the boot on a database it was never going to touch.
+      const walleSpecForPreflight = specs.find((spec) => spec.id === 'walle');
+      const walleOwner = walleSpecForPreflight && plannedDatabaseIds.has('walle')
+        ? ensureWalleOwnerStopped(walleSpecForPreflight.path, options.walleOwner || {}) : null;
+      profile.measure('assert_databases_offline', () => _assertDatabasesOffline(plannedSpecs()));
       const headroomDatabaseIds = new Set(plannedDatabaseIds);
       if (headroomDatabaseIds.has('ctm') && specs.some((spec) => spec.id === 'walle')) {
         headroomDatabaseIds.add('walle');
@@ -486,6 +495,7 @@ function runAutomaticConversationMigration(options = {}) {
           options,
         )),
         databaseOwnership: 'offline',
+        ...(walleOwner ? { walleOwner } : {}),
       };
       checkpoint('preflight');
       checkpoint('inventory');
@@ -654,6 +664,11 @@ function runAutomaticConversationMigration(options = {}) {
           expandWalleDependency = true;
         } finally { ctmDb.close(); walleDb.close(); }
         if (expandWalleDependency) {
+          // R-5/R-8 (still inside the !state.irreversibleAt guard above): the expansion adds
+          // walle AFTER the preflight probe, so the owner must be proven stopped here too,
+          // before rebuild_walle -- and walle alone is re-probed.
+          state.preflight.walleOwner = ensureWalleOwnerStopped(walleSpec.path, options.walleOwner || {});
+          _assertDatabasesOffline([walleSpec]);
           plannedDatabaseIds.add('walle');
           delete state.cleanBackups.walle;
           state.restartPreflight.plannedDatabaseIds = specs

package/template/coding-task-manager/bin/conversation-storage-generation-evidence.js

@@ -5,6 +5,7 @@ const Database = require('better-sqlite3');
 const migration = require('../../scripts/conversation-storage-v2-migration');
 const {
   sanitizeInspectionViolations,
+  inspectionErrorClass,
 } = require('../../shared/conversation-storage-v2-contract');
 
 // Moved from conversation-storage-auto-migration-lib.js (WP-5 un-golf/split: keeping the
@@ -170,8 +171,14 @@ function inspectCompletedMarkerSpec(spec, expectedGeneration, generationEvidence
       violations,
       ...(generationChanged ? { generationChanged: true } : {}),
     };
-  } catch {
-    return { clean: false, reasonCodes: ['inspection_failed'], violations: [] };
+  } catch (error) {
+    // REPORT: an inspection that throws still plans a rerun (RERUN_CLASS, unchanged), but the
+    // boot log now names the error class instead of an empty violation list (clock-free r6 OQ-5).
+    return {
+      clean: false,
+      reasonCodes: ['inspection_failed'],
+      violations: [{ code: 'inspection_failed', objectId: inspectionErrorClass(error), count: 1 }],
+    };
   }
 }
 

package/template/coding-task-manager/bin/conversation-storage-service-entry-lib.js

@@ -12,6 +12,7 @@ const {
   buildConversationMigrationStatus,
 } = require('../lib/conversation-storage-migration-status');
 const { rebindCompletedGenerations } = require('./conversation-storage-generation-evidence');
+const { resolveInstanceTag } = require('../lib/instance-tag');
 const { createPhaseProfile } = require('../lib/phase-profile');
 const {
   sanitizeInspectionViolations,
@@ -102,7 +103,13 @@ function buildConversationStorageServiceLog(result = {}) {
     recoveryArtifactCount: status.recoveryArtifactCount,
     cleanupPendingCount: status.cleanupPendingCount,
   };
-  const restartPreflight = _restartPreflightForServiceLog(result.restartPreflight);
+  // R-6 (clock-free r4): restartPreflight describes a migration that was PLANNED by the
+  // boot that ran it. An already_complete / generation_rebound boot (result.skipped set)
+  // only re-reads the journal, so re-emitting the recorded object would print a stale
+  // re-run plan for a boot that ran no migration -- exactly what misled r3's census.
+  const restartPreflight = result.skipped == null
+    ? _restartPreflightForServiceLog(result.restartPreflight)
+    : null;
   if (restartPreflight) summary.restartPreflight = restartPreflight;
   return summary;
 }
@@ -129,6 +136,14 @@ function resolveAutomaticConversationMigrationOptions(env = process.env, homedir
     },
     batchLimit: Number(env.CTM_CONVERSATION_MIGRATION_BATCH_ROWS) || undefined,
     batchByteLimit: Number(env.CTM_CONVERSATION_MIGRATION_BATCH_BYTES) || undefined,
+    // WP-3 (clock-free r5 R-5/R-6): the kill authority the boot migration uses to prove and
+    // stop THIS instance's Wall-E before it touches wall-e-brain.db. Same tag derivation the
+    // supervisor uses (server.js:5897), so a dev/test instance can never signal the primary's
+    // daemon. Kept out of buildConversationStorageServiceLog, which never serializes options.
+    walleOwner: {
+      configDir: ctmDataDir,
+      instanceTag: resolveInstanceTag({ env, configDir: ctmDataDir, port: parseInt(env.CTM_PORT || '3456', 10) }),
+    },
   };
 }
 

package/template/coding-task-manager/bin/conversation-storage-walle-owner.js

@@ -0,0 +1,247 @@
+'use strict';
+
+// WP-3 / R-4..R-8 of docs/clock-free-tests-followups-r5-2026-10-25.html §5.
+//
+// Liveness for the boot migration's destructive walle re-run comes from Wall-E's own
+// write-lock identity record — `<db>.write-lock`, a 1,024-byte space-padded JSON
+// `{pid,...}` that PERSISTS after release (shared/sqlite-write-lock.js:1-40,250, D-3) —
+// not from a `BEGIN IMMEDIATE` probe. Probe P1 showed that an owner which is alive with an
+// idle connection (or no connection at all) passes the transaction probe, and the purge
+// then rewrites the database under it (the 2026-07-20 column-loss incident, r4 §1.1).
+//
+// The module is synchronous on purpose: bin/ctm-service-entry.js runs this migration
+// BEFORE it requires ../server, and the stop has to finish before the first walle write.
+//
+// R-6: nothing here is ever signalled on a name match. The one pid that may receive a
+// signal is the daemon pid read from `<configDir>/walle.pid`, and only after a single
+// `ps -p <pid>` row proves it is this instance's own Wall-E (lib/walle-kill-authority.js).
+// R-7: any other live write-lock holder stays fail-closed (`conversation_migration_database_busy`),
+// which the caller maps to exit 78 exactly as before.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { processTitleCandidates } = require('../lib/process-title');
+const { isOwnedRow } = require('../lib/walle-kill-authority');
+const { intFlag } = require('../lib/env-flags');
+
+const WALLE_PID_FILE = 'walle.pid';
+const WRITE_LOCK_SUFFIX = '.write-lock';
+const PS_TIMEOUT_MS = 5000;
+const PS_MAX_BUFFER = 1024 * 1024;
+// One SIGKILL grace window after the graceful budget is spent; a killed-but-unreaped
+// process is still a live pid until the kernel reaps it.
+const SIGKILL_GRACE_MS = 1000;
+// Same budget, default and clamp as lib/walle-supervisor.js:333,389 — a Wall-E that is
+// legitimately draining inside its own WALLE_SHUTDOWN_DEADLINE_MS gets to finish.
+const CHILD_EXIT_WAIT_ENV = 'WALLE_CHILD_EXIT_WAIT_MS';
+const DEFAULT_CHILD_EXIT_WAIT_MS = 16000;
+const MIN_CHILD_EXIT_WAIT_MS = 5000;
+const MAX_CHILD_EXIT_WAIT_MS = 120000;
+const DEFAULT_LOCK_RELEASE_WAIT_MS = 2000;
+const DEFAULT_POLL_MS = 100;
+
+function _childExitWaitMs() {
+  return Math.max(MIN_CHILD_EXIT_WAIT_MS, Math.min(MAX_CHILD_EXIT_WAIT_MS,
+    intFlag(CHILD_EXIT_WAIT_ENV, DEFAULT_CHILD_EXIT_WAIT_MS)));
+}
+
+// R-4: the owner identity, read off disk. null covers ENOENT (nothing ever wrote here),
+// EISDIR and a torn read of a v2 in-place write — every one of those means "no usable
+// identity", never "throw". Shape copied from shared/sqlite-write-lock.js:250 (_readIdentity)
+// and wall-e/bin/brain-purge-legacy-ctm.js:236-245 (liveReason's first check).
+function readWriteLockOwnerPid(dbPath) {
+  let record;
+  try {
+    record = JSON.parse(fs.readFileSync(`${dbPath}${WRITE_LOCK_SUFFIX}`, 'utf8'));
+  } catch {
+    /* expected: ENOENT (no writer yet), EISDIR (a directory sits at the path) and a torn
+       read of an in-place v2 write all mean "no identity readable right now". */
+    return null;
+  }
+  const pid = Number(record?.pid);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+// R-4: only ESRCH proves the pid is gone. EPERM means the pid EXISTS but is owned by
+// another user — kill(pid,0) probes existence, not killability — so every non-ESRCH
+// error fails toward "alive" (shared/sqlite-write-lock.js:231-245).
+function pidAlive(pid, kill = process.kill) {
+  const value = Number(pid);
+  if (!Number.isFinite(value) || value <= 0) return false;
+  try {
+    kill(value, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}
+
+// A pid that has exited but has not been REAPED is still a live pid for kill(pid,0): the
+// kernel keeps a zombie's pid until its parent waits. libuv only waits when the event loop
+// runs, and this migration blocks the loop for its whole duration (see the module comment:
+// it runs before ../server is required), so a daemon this process spawned -- ppid === myPid,
+// which lib/walle-kill-authority.js:17 explicitly accepts as owned -- stays kill(pid,0)-alive
+// forever after it has exited. Measured on this host: `kill(pid,0)` says alive while
+// `ps -o stat=` says "Z" for the whole blocked window, then the pid disappears once the loop
+// turns. A zombie has exited, so it must read as gone -- otherwise the SIGTERM we just sent
+// would be reported back to the caller as "a live holder that is not this instance's Wall-E".
+// Only consulted when kill(pid,0) already says alive, so the common reparented-to-launchd
+// daemon (ppid 1, reaped by init) never pays for it.
+function _isZombiePid(pid) {
+  try {
+    const stdout = execFileSync('ps', ['-p', String(pid), '-o', 'stat='], {
+      encoding: 'utf8',
+      timeout: PS_TIMEOUT_MS,
+      maxBuffer: 4096,
+    });
+    return String(stdout).trim().startsWith('Z');
+  } catch {
+    /* expected: ps exits non-zero when the pid has no row -- it is gone, or it was reaped
+       between the two probes. Either way there is no zombie to report. */
+    return false;
+  }
+}
+
+function _readWalleDaemonPid(configDir) {
+  if (!configDir) return null;
+  try {
+    const pid = Number.parseInt(fs.readFileSync(path.join(String(configDir), WALLE_PID_FILE), 'utf8').trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    /* expected: no pid file (Wall-E never started for this config dir) or an unreadable
+       one both mean "no daemon to stop" — R-7 still fails closed on the write-lock owner. */
+    return null;
+  }
+}
+
+// The same synchronous sleep idiom the write-lock module uses (shared/sqlite-write-lock.js:226-229).
+function sleepSync(ms) {
+  const buffer = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+}
+
+let _parsePsWithPpid = null;
+
+// Rows for ONE pid, parsed by the supervisor's own parser so ownership sees an identical
+// row shape (lib/walle-supervisor.js:166-184,205-212). Loaded lazily: the migration runs
+// before ../server boots, and the ps path is only reached when a live owner record exists.
+function _psRow(pid) {
+  if (!_parsePsWithPpid) ({ parsePsWithPpid: _parsePsWithPpid } = require('../lib/walle-supervisor'));
+  try {
+    const stdout = execFileSync('ps', ['-p', String(pid), '-o', 'pid=,ppid=,command='], {
+      encoding: 'utf8',
+      timeout: PS_TIMEOUT_MS,
+      maxBuffer: PS_MAX_BUFFER,
+    });
+    return _parsePsWithPpid(stdout);
+  } catch (error) {
+    // A non-zero exit is ps answering "no such process" -> an empty row list.
+    // Anything else (ps un-runnable, timed out) is the probe itself failing -> null, which
+    // ownership must read as "not proven owned", never as "there is no process".
+    return Number.isInteger(error?.status) ? [] : null;
+  }
+}
+
+// R-4/R-5/R-7 liveness, one predicate: gone (ESRCH) or exited-and-not-yet-reaped (zombie).
+function _hasExited(pid, ops) {
+  return !pidAlive(pid, ops.kill) || ops.zombie(pid);
+}
+
+// Poll until the pid is gone, bounded by BOTH the deadline and an iteration cap: a caller
+// that injects a `now` which does not advance must not spin this loop forever.
+function _waitForExit(pid, timeoutMs, pollMs, ops) {
+  if (_hasExited(pid, ops)) return true;
+  const budget = Math.max(0, Number(timeoutMs) || 0);
+  const poll = Math.max(1, Number(pollMs) || DEFAULT_POLL_MS);
+  const deadline = ops.now() + budget;
+  const maxIterations = Math.ceil(budget / poll) + 1;
+  for (let index = 0; index < maxIterations; index += 1) {
+    if (ops.now() >= deadline) break;
+    ops.sleep(Math.max(1, Math.min(poll, deadline - ops.now())));
+    if (_hasExited(pid, ops)) return true;
+  }
+  return _hasExited(pid, ops);
+}
+
+// R-5/R-6/R-7. Returns { stopped, pid, waitedMs, signal }; throws
+// `conversation_migration_database_busy` when a live holder survives (R-7).
+function ensureWalleOwnerStopped(walleDbPath, options = {}) {
+  const injected = options.ops || {};
+  const ops = {
+    kill: typeof injected.kill === 'function' ? injected.kill : process.kill,
+    psRow: typeof injected.psRow === 'function' ? injected.psRow : _psRow,
+    sleep: typeof injected.sleep === 'function' ? injected.sleep : sleepSync,
+    now: typeof injected.now === 'function' ? injected.now : Date.now,
+    myPid: Number.isInteger(injected.myPid) ? injected.myPid : process.pid,
+    // A caller that injects its own process table owns liveness entirely -- probing the
+    // real ps for a fake pid would be meaningless (and would fork a process per poll). The
+    // real zombie probe is only armed on the real process.kill path.
+    zombie: typeof injected.zombie === 'function' ? injected.zombie
+      : (typeof injected.kill === 'function' ? () => false : _isZombiePid),
+  };
+  const instanceTag = options.instanceTag ? String(options.instanceTag) : null;
+  const childExitWaitMs = Number.isFinite(options.childExitWaitMs)
+    ? Math.max(0, Number(options.childExitWaitMs)) : _childExitWaitMs();
+  const lockReleaseWaitMs = Number.isFinite(options.lockReleaseWaitMs)
+    ? Math.max(0, Number(options.lockReleaseWaitMs)) : DEFAULT_LOCK_RELEASE_WAIT_MS;
+  const pollMs = Number.isFinite(options.pollMs) ? Math.max(1, Number(options.pollMs)) : DEFAULT_POLL_MS;
+  const startedAt = ops.now();
+
+  const ownerPid = readWriteLockOwnerPid(walleDbPath);
+  if (ownerPid === null || ownerPid === ops.myPid || _hasExited(ownerPid, ops)) {
+    // No usable record, our own pid, or a provably dead writer: nothing to stop, and no
+    // ownership probe is even attempted.
+    return { stopped: false, pid: null, waitedMs: 0, signal: null };
+  }
+
+  let daemonPid = null;
+  let signal = null;
+  if (options.configDir && instanceTag) {
+    const candidate = _readWalleDaemonPid(options.configDir);
+    if (candidate !== null && !_hasExited(candidate, ops)) daemonPid = candidate;
+  }
+  if (daemonPid !== null) {
+    const rows = ops.psRow(daemonPid);
+    const row = (Array.isArray(rows) ? rows : []).find((entry) => Number(entry?.pid) === daemonPid) || null;
+    const owned = isOwnedRow(row, {
+      titles: new Set(processTitleCandidates('walle', instanceTag)),
+      myPid: ops.myPid,
+    });
+    if (owned) {
+      ops.kill(daemonPid, 'SIGTERM');
+      signal = 'SIGTERM';
+      if (!_waitForExit(daemonPid, childExitWaitMs, pollMs, ops)) {
+        ops.kill(daemonPid, 'SIGKILL');
+        signal = 'SIGKILL';
+        _waitForExit(daemonPid, SIGKILL_GRACE_MS, pollMs, ops);
+      }
+    }
+  }
+  // The write-lock owner may be a different pid than the daemon (a worker, or a foreign
+  // process). It gets the same short grace — the lock is released by process exit — and
+  // then fails closed below. It is never signalled unless it IS the proven daemon pid.
+  if (!_hasExited(ownerPid, ops)) _waitForExit(ownerPid, lockReleaseWaitMs, pollMs, ops);
+
+  if (!_hasExited(ownerPid, ops)) {
+    const error = new Error(
+      `database is owned by a live process that is not this instance's Wall-E: walle pid=${ownerPid}`,
+    );
+    error.code = 'conversation_migration_database_busy';
+    error.database = 'walle';
+    error.ownerPid = ownerPid;
+    throw error;
+  }
+  return {
+    stopped: signal !== null,
+    pid: daemonPid,
+    waitedMs: Math.max(0, ops.now() - startedAt),
+    signal,
+  };
+}
+
+module.exports = {
+  ensureWalleOwnerStopped,
+  pidAlive,
+  readWriteLockOwnerPid,
+};