create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/bin/repair-foreign-clone.js

@@ -0,0 +1,564 @@
+#!/usr/bin/env node
+'use strict';
+
+// WP-D — offline repair CLI for a pre-WP-2 cloned CTM data dir.
+// Design: docs/remote-hub-fences-followups-r2-clone-truth-and-repair-2026-10-23.html
+//   §1.1 (the measured Spark shape this tool repairs), §3 P-3..P-6, §5 D-D1..D-D7, §9 WP-D.
+//
+// The incident: a data dir was file-copied from one machine to another while running pre-WP-2
+// code. The clone's boot re-minted the instance id and WP-2's `restampOwnerLineage`-predecessor
+// claimed every row the source machine owned (Spark: 3,775 sessions + 64 startup tasks) as its
+// own. WP-2 fences that at write time (`cross_host = 1` stops the claim) but cannot undo a claim
+// that already happened, and a pre-WP-2 database has no `cross_host` column at all — so the
+// re-mint edge reads as "same host" forever.
+//
+// This tool replays WP-2's D-3 for ONE operator-named legacy edge, offline, on a STOPPED instance:
+//   * operator asserts the edge (`--edge-prior <instanceId>`); there is no auto-detection (P-2);
+//   * dry-run is the default; `--apply` is required to mutate;
+//   * it refuses while the server runs (lock artifact with a live pid, or a failing
+//     `BEGIN IMMEDIATE` probe — D-D3);
+//   * `--apply` takes a verified `VACUUM INTO` backup first (D-D4);
+//   * two independent discriminators (write-once `origin_instance_id ∈ foreign component`,
+//     `created_at` strictly before the clone) must agree on EVERY row or it refuses (D-D5);
+//   * the mutation is one transaction that re-stamps owners, parks foreign tasks and un-commits
+//     the edge — never rewrites `origin_instance_id`, never touches drafts, never deletes a row
+//     (D-D6), and a re-run is a no-op (P-6).
+//
+// It opens the database directly through lib/sqlite-driver.js — never db.initDb(), never a
+// connection outside `--data-dir`.
+//
+// Usage:
+//   node bin/repair-foreign-clone.js --edge-prior <instanceId> [--data-dir <dir>] [--apply] [--json]
+//
+// Exit codes:
+//   0 ok / nothing to repair    2 usage            3 server live
+//   4 discriminator disagreement                  5 pre-clone drafts present
+//   6 edge/db precondition                        7 backup failed
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { loadSqliteDriver } = require('../lib/sqlite-driver');
+const { getDataDir } = require('../lib/data-dir');
+const { ownerLineageComponent } = require('../lib/host-identity');
+
+const EXIT = Object.freeze({
+  OK: 0,
+  USAGE: 2,
+  SERVER_LIVE: 3,
+  DISAGREEMENT: 4,
+  DRAFTS: 5,
+  PRECONDITION: 6,
+  BACKUP_FAILED: 7,
+});
+
+// The two database files a CTM data dir can carry the core tables in: `core.db` under the
+// core/telemetry domain split (the default, and what Spark runs), `task-manager.db` pre-split.
+const CANDIDATE_DB_FILES = Object.freeze(['core.db', 'task-manager.db']);
+const REQUIRED_TABLES = Object.freeze(['instance_identity', 'instance_lineage', 'ctm_sessions', 'startup_tasks']);
+const SERVER_LIVE_ARTIFACTS = Object.freeze(['task-manager.db.walle-history-v2.lock', 'walle.pid']);
+const CLONE_REASON = 'clone_detected';
+const PARK_REASON = 'foreign-clone';
+const DISAGREEMENT_LIMIT = 20;
+const USAGE = 'usage: node bin/repair-foreign-clone.js --edge-prior <instanceId> [--data-dir <dir>] [--apply] [--json]';
+
+function refusal(exitCode, message) {
+  const error = new Error(message);
+  error.exitCode = exitCode;
+  error.repairRefusal = true;
+  return error;
+}
+
+// ── primitives ──────────────────────────────────────────────────────────────────────────────
+
+// One `new Database(...)` site: the read-write branch is the file's single registered SQLite
+// writer surface; the read-only branch never mutates (and never checkpoints a WAL on close).
+function openDatabase(dbPath, { readonly = false } = {}) {
+  const Database = loadSqliteDriver();
+  if (readonly) return new Database(dbPath, { readonly: true, fileMustExist: true });
+  return new Database(dbPath, { fileMustExist: true });
+}
+
+function tableNames(db) {
+  return new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => String(row.name)));
+}
+
+function tableColumns(db, table) {
+  try {
+    return new Set(db.pragma(`table_info(${table})`).map((row) => String(row.name)));
+  } catch {
+    return new Set(); // expected: an absent table has no columns; callers gate on tableExists
+  }
+}
+
+// SQLite text timestamps come in two shapes: `datetime('now')` writes `'YYYY-MM-DD HH:MM:SS'`
+// (UTC, no zone marker) and every newer writer uses `Date#toISOString()`. Both land on the same
+// absolute scale here; anything else is UNKNOWN (null), which callers must treat as "cannot
+// agree", never as "false" (D-D5).
+function normalizeTimestampMs(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return null;
+  const iso = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(raw) ? `${raw.replace(' ', 'T')}Z` : raw;
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function readPragmaScalar(db, pragma) {
+  const result = db.pragma(pragma);
+  if (Array.isArray(result)) {
+    const first = result[0];
+    if (first === undefined) return '';
+    if (first !== null && typeof first === 'object') return String(Object.values(first)[0] ?? '');
+    return String(first);
+  }
+  return String(result ?? '');
+}
+
+// ── step 1: which file is the database (D-D2) ───────────────────────────────────────────────
+
+function resolveDatabasePath(dataDir) {
+  const dir = path.resolve(String(dataDir || '').trim() || getDataDir());
+  const matches = [];
+  const inspected = [];
+  for (const name of CANDIDATE_DB_FILES) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) {
+      inspected.push(`${name} (missing)`);
+      continue;
+    }
+    let tables;
+    try {
+      const db = openDatabase(file, { readonly: true });
+      try { tables = tableNames(db); } finally { db.close(); }
+    } catch (error) {
+      // expected: an unreadable/foreign file cannot be the CTM database; report it as such
+      inspected.push(`${name} (unreadable: ${String(error?.message || error)})`);
+      continue;
+    }
+    const missing = REQUIRED_TABLES.filter((table) => !tables.has(table));
+    if (missing.length) {
+      inspected.push(`${name} (missing tables: ${missing.join(', ')})`);
+      continue;
+    }
+    matches.push(file);
+  }
+  if (matches.length !== 1) {
+    throw refusal(
+      EXIT.PRECONDITION,
+      `expected exactly one database carrying ${REQUIRED_TABLES.join(', ')} in ${dir}; found ${matches.length} — ${inspected.join('; ')}`,
+    );
+  }
+  return matches[0];
+}
+
+// ── step 2: prove the server is stopped (D-D3) ──────────────────────────────────────────────
+
+function _pidFromArtifact(artifact) {
+  const raw = (() => {
+    try {
+      return fs.readFileSync(artifact, 'utf8');
+    } catch {
+      return null; // expected: missing/unreadable artifact proves nothing is running
+    }
+  })();
+  if (raw === null) return null;
+  const text = String(raw).trim();
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === 'object') {
+      const pid = Number(parsed.pid);
+      return Number.isInteger(pid) && pid > 0 ? pid : null;
+    }
+  } catch {
+    // expected: walle.pid is a bare integer, the migration lock is JSON — fall through
+  }
+  const bare = Number.parseInt(text, 10);
+  return Number.isInteger(bare) && bare > 0 && String(bare) === text ? bare : null;
+}
+
+function _processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function assertOffline(dataDir, dbPath) {
+  const dir = path.resolve(String(dataDir || '').trim() || getDataDir());
+  for (const name of SERVER_LIVE_ARTIFACTS) {
+    const artifact = path.join(dir, name);
+    const pid = _pidFromArtifact(artifact);
+    if (pid !== null && _processAlive(pid)) {
+      throw refusal(EXIT.SERVER_LIVE, `refusing to run: ${artifact} names live pid ${pid} — stop CTM (and Wall-E) first`);
+    }
+  }
+  // The exclusivity proof has to be a READ-WRITE connection: a read-only connection's
+  // BEGIN IMMEDIATE is downgraded and reports success even while another process holds the write
+  // lock (measured, 2026-10-23). BEGIN IMMEDIATE takes the write lock without writing pages, so
+  // a successful probe leaves the file byte-identical.
+  const probe = openDatabase(dbPath);
+  try {
+    probe.pragma('busy_timeout = 0');
+    probe.exec('BEGIN IMMEDIATE');
+    probe.exec('ROLLBACK');
+  } catch (cause) {
+    try { probe.exec('ROLLBACK'); } catch { /* expected: the failed BEGIN opened no transaction */ }
+    if (cause?.code === 'SQLITE_BUSY' || cause?.code === 'SQLITE_LOCKED') {
+      throw refusal(EXIT.SERVER_LIVE, `refusing to run: ${dbPath} is still held by another writer (${cause.code})`);
+    }
+    throw cause;
+  } finally {
+    try { probe.close(); } catch { /* expected: already-closed probe */ }
+  }
+}
+
+// ── steps 3-7: the plan (D-D1/D-D2/D-D5/D-D7) ───────────────────────────────────────────────
+
+function _singleIdentity(db) {
+  const rows = db.prepare('SELECT instance_id FROM instance_identity').all();
+  if (rows.length !== 1) {
+    throw refusal(EXIT.PRECONDITION, `instance_identity holds ${rows.length} row(s); expected exactly 1 — refusing to guess this host's identity`);
+  }
+  const currentId = String(rows[0].instance_id || '').trim();
+  if (!currentId) throw refusal(EXIT.PRECONDITION, 'instance_identity.instance_id is empty');
+  return currentId;
+}
+
+function _matchEdge(db, { edgePrior, currentId }) {
+  const rows = db.prepare('SELECT * FROM instance_lineage').all();
+  const matches = rows.filter((row) => String(row.prior_instance_id || '').trim() === edgePrior
+    && String(row.new_instance_id || '').trim() === currentId
+    && String(row.reason || '').trim() === CLONE_REASON);
+  if (matches.length !== 1) {
+    throw refusal(
+      EXIT.PRECONDITION,
+      `expected exactly one instance_lineage row with prior_instance_id=${edgePrior}, new_instance_id=${currentId}, reason=${CLONE_REASON}; found ${matches.length}`,
+    );
+  }
+  const edge = matches[0];
+  const hasCrossHost = Object.prototype.hasOwnProperty.call(edge, 'cross_host');
+  // The verdict column belongs to db.js's hosted schema (the runner-owned DDL); this tool never
+  // issues DDL (ddl-outside-runner lint). A pre-WP-2 data dir gains it by booting once on WP-2+
+  // code — harmless before the repair, since the poisoned rows are already claimed.
+  if (!hasCrossHost) {
+    throw refusal(EXIT.PRECONDITION, 'instance_lineage has no cross_host column — boot this data dir once on WP-2+ code (db.js adds the column), stop it, then rerun');
+  }
+  // `Number(null) === 0`, so NULL must be excluded explicitly: a legacy edge carries no verdict
+  // and every pre-WP-2 edge is exactly that (D-D1: NULL or 1 proceed).
+  if (edge.cross_host !== null && Number(edge.cross_host) === 0) {
+    throw refusal(EXIT.PRECONDITION, `lineage edge ${edge.id} is marked cross_host = 0 — a proven same-host re-mint must not be repaired`);
+  }
+  return { edge, rows };
+}
+
+function _planRows(db, { table, keyColumn, detectedAtMs, foreignComponent, currentId }) {
+  const columns = tableColumns(db, table);
+  if (!columns.has('current_owner_instance_id')) return { foreign: [], native: 0, disagreements: [] };
+  const select = ['current_owner_instance_id', keyColumn];
+  if (columns.has('origin_instance_id')) select.push('origin_instance_id');
+  if (columns.has('created_at')) select.push('created_at');
+  if (columns.has('status')) select.push('status');
+  const rows = db.prepare(`SELECT ${select.join(', ')} FROM ${table} WHERE current_owner_instance_id = ?`).all(currentId);
+  const foreign = [];
+  const disagreements = [];
+  let native = 0;
+  for (const row of rows) {
+    const key = String(row[keyColumn] ?? '');
+    const origin = String(row.origin_instance_id ?? '').trim();
+    const createdAtMs = columns.has('created_at') ? normalizeTimestampMs(row.created_at) : null;
+    const isForeignOrigin = foreignComponent.has(origin);
+    const isPreClone = createdAtMs !== null && createdAtMs < detectedAtMs;
+    if (createdAtMs === null) {
+      disagreements.push({ table, key, reason: 'unparseable created_at' });
+    } else if (isForeignOrigin && isPreClone) {
+      foreign.push(row);
+    } else if (!isForeignOrigin && !isPreClone) {
+      native += 1;
+    } else {
+      disagreements.push({
+        table,
+        key,
+        reason: isForeignOrigin ? 'foreign origin but created after the clone' : 'no foreign origin but created before the clone',
+      });
+    }
+  }
+  return { foreign, native, disagreements };
+}
+
+function planRepair(db, { edgePrior, dataDir = '', dbPath = '' } = {}) {
+  const prior = String(edgePrior || '').trim();
+  if (!prior) throw refusal(EXIT.USAGE, `--edge-prior is required. ${USAGE}`);
+  const currentId = _singleIdentity(db);
+  const { edge, rows: lineageRows } = _matchEdge(db, { edgePrior: prior, currentId });
+  const detectedAtMs = normalizeTimestampMs(edge.detected_at);
+  if (detectedAtMs === null) {
+    throw refusal(EXIT.PRECONDITION, `lineage edge ${edge.id} has an unparseable detected_at (${JSON.stringify(edge.detected_at ?? null)})`);
+  }
+  // The foreign component is the transitive closure of the prior id in the lineage graph with
+  // THIS edge removed — "every id that reaches this host only through the cloned-DB edge", which
+  // is exactly the set of ids belonging to the other machine (P-2). `traverseCrossHost: true`
+  // keeps that closure complete once WP-C makes cross_host = 1 edges non-traversable by default.
+  const foreignComponent = ownerLineageComponent(prior, lineageRows.filter((row) => row !== edge), { traverseCrossHost: true });
+  if (foreignComponent.has(currentId)) {
+    throw refusal(EXIT.PRECONDITION, `${prior} is still linked to ${currentId} by another lineage path — this is not a foreign component`);
+  }
+  const sessions = _planRows(db, { table: 'ctm_sessions', keyColumn: 'id', detectedAtMs, foreignComponent, currentId });
+  const tasks = _planRows(db, { table: 'startup_tasks', keyColumn: 'ctm_session_id', detectedAtMs, foreignComponent, currentId });
+  const disagreements = [...sessions.disagreements, ...tasks.disagreements];
+  if (disagreements.length) {
+    const listed = disagreements.slice(0, DISAGREEMENT_LIMIT).map((row) => `${row.table}:${row.key} (${row.reason})`).join(', ');
+    const more = disagreements.length > DISAGREEMENT_LIMIT ? `, … ${disagreements.length - DISAGREEMENT_LIMIT} more` : '';
+    throw refusal(EXIT.DISAGREEMENT, `refusing: the two discriminators disagree on ${disagreements.length} row(s) owned by ${currentId}: ${listed}${more}`);
+  }
+  // D-D7: drafts move only through the media-store version allocator, never through raw SQL.
+  if (tableColumns(db, 'terminal_draft_images').has('owner_host_instance_id')) {
+    const drafts = db.prepare(`
+      SELECT attachment_id, created_at FROM terminal_draft_images WHERE owner_host_instance_id = ?
+    `).all(currentId);
+    const preClone = drafts.filter((row) => {
+      const ms = normalizeTimestampMs(row.created_at);
+      return ms !== null && ms < detectedAtMs;
+    });
+    if (preClone.length) {
+      throw refusal(EXIT.DRAFTS, `refusing: ${preClone.length} terminal_draft_images row(s) owned by ${currentId} predate the clone (e.g. ${String(preClone[0].attachment_id)}) — drafts move only through the media-store allocator`);
+    }
+  }
+  const sessionIds = sessions.foreign.map((row) => String(row.id));
+  const taskRows = tasks.foreign;
+  const leaseIds = [];
+  if (tableColumns(db, 'resource_leases').has('holder_instance_id') && sessionIds.length) {
+    const placeholders = sessionIds.map(() => '?').join(', ');
+    const leases = db.prepare(`
+      SELECT resource_id FROM resource_leases
+       WHERE resource_type = 'ctm_session' AND holder_instance_id = ? AND resource_id IN (${placeholders})
+    `).all(currentId, ...sessionIds);
+    for (const row of leases) leaseIds.push(String(row.resource_id));
+  }
+  const bindingIds = [];
+  if (tableColumns(db, 'workspace_bindings').has('host_instance_id')) {
+    const bindings = db.prepare('SELECT logical_id, created_at FROM workspace_bindings WHERE host_instance_id = ?').all(currentId);
+    for (const row of bindings) {
+      const ms = normalizeTimestampMs(row.created_at);
+      if (ms === null || ms >= detectedAtMs) continue;
+      // Moving host_instance_id is a PRIMARY KEY (logical_id, host_instance_id) rewrite: skip a
+      // binding the live instance already re-registered under the prior id (db.js's own
+      // conflict rule — never throw a UNIQUE/PK error, never lose the authoritative row).
+      const collision = db.prepare('SELECT 1 AS present FROM workspace_bindings WHERE logical_id = ? AND host_instance_id = ?').get(String(row.logical_id), prior);
+      if (collision) continue;
+      bindingIds.push(String(row.logical_id));
+    }
+  }
+  return {
+    dataDir,
+    dbPath,
+    currentId,
+    edge: {
+      id: Number(edge.id),
+      prior,
+      next: currentId,
+      detectedAt: String(edge.detected_at),
+      crossHost: edge.cross_host,
+    },
+    foreignComponent: [...foreignComponent],
+    rows: {
+      ctm_sessions: { foreign: sessionIds, native: sessions.native },
+      startup_tasks: {
+        foreign: taskRows.map((row) => String(row.ctm_session_id)),
+        park: taskRows.filter((row) => String(row.status ?? 'running') !== 'exited').map((row) => String(row.ctm_session_id)),
+        native: tasks.native,
+      },
+      resource_leases: { ids: leaseIds },
+      workspace_bindings: { logicalIds: bindingIds },
+    },
+    disagreements: [],
+  };
+}
+
+function isNothingToRepair(plan) {
+  if (!plan || !plan.rows) return true;
+  const { ctm_sessions: sessions, startup_tasks: tasks, resource_leases: leases, workspace_bindings: bindings } = plan.rows;
+  return sessions.foreign.length === 0
+    && tasks.foreign.length === 0
+    && leases.ids.length === 0
+    && bindings.logicalIds.length === 0
+    && Number(plan.edge?.crossHost) === 1;
+}
+
+// ── steps 8-10: backup + one transactional apply (D-D4/D-D6) ────────────────────────────────
+
+function _backupStamp(now) {
+  return new Date(now).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+function createVerifiedBackup(db, { dataDir, dbPath, now = new Date() }) {
+  const dir = path.resolve(String(dataDir || '').trim() || getDataDir());
+  const backupDir = path.join(dir, 'backups', `foreign-clone-repair-${_backupStamp(now)}`);
+  if (fs.existsSync(backupDir)) {
+    throw refusal(EXIT.BACKUP_FAILED, `refusing to overwrite an existing backup directory: ${backupDir}`);
+  }
+  fs.mkdirSync(backupDir, { recursive: true });
+  const backupPath = path.join(backupDir, path.basename(dbPath));
+  try {
+    // VACUUM INTO is WAL-safe and takes a consistent snapshot of the committed state; a plain
+    // file copy of a live WAL database can silently omit committed frames.
+    db.prepare('VACUUM INTO ?').run(backupPath);
+  } catch (error) {
+    throw refusal(EXIT.BACKUP_FAILED, `VACUUM INTO ${backupPath} failed: ${String(error?.message || error)}`);
+  }
+  let check = '';
+  try {
+    const copy = openDatabase(backupPath, { readonly: true });
+    try { check = readPragmaScalar(copy, 'quick_check'); } finally { copy.close(); }
+  } catch (error) {
+    throw refusal(EXIT.BACKUP_FAILED, `backup ${backupPath} could not be verified: ${String(error?.message || error)}`);
+  }
+  if (check !== 'ok') throw refusal(EXIT.BACKUP_FAILED, `PRAGMA quick_check on ${backupPath} returned ${JSON.stringify(check)} — refusing to continue`);
+  return { backupDir, backupPath };
+}
+
+function applyRepair(db, plan, { dataDir = '', dbPath = '', now = new Date() } = {}) {
+  const { backupDir, backupPath } = createVerifiedBackup(db, { dataDir, dbPath, now });
+  const prior = String(plan.edge.prior);
+  const currentId = String(plan.currentId);
+  const parkedAt = new Date(now).toISOString();
+  const sessionColumns = tableColumns(db, 'ctm_sessions');
+  const changed = { ctm_sessions: [], startup_tasks: [], parked: [], resource_leases: 0, workspace_bindings: 0 };
+  const run = db.transaction(() => {
+    db.prepare('UPDATE instance_lineage SET cross_host = 1 WHERE id = ?').run(Number(plan.edge.id));
+    for (const id of plan.rows.ctm_sessions.foreign) {
+      db.prepare('UPDATE ctm_sessions SET current_owner_instance_id = ? WHERE id = ?').run(prior, id);
+      if (sessionColumns.has('execution_host_instance_id')) {
+        // execution_host_instance_id is a separate pointer and can name the current host while the
+        // owner already names the prior one; only the current host's value is the wrong one.
+        db.prepare('UPDATE ctm_sessions SET execution_host_instance_id = ? WHERE id = ? AND execution_host_instance_id = ?').run(prior, id, currentId);
+      }
+      changed.ctm_sessions.push(String(id));
+    }
+    for (const id of plan.rows.startup_tasks.foreign) {
+      db.prepare('UPDATE startup_tasks SET current_owner_instance_id = ? WHERE ctm_session_id = ?').run(prior, id);
+      if (plan.rows.startup_tasks.park.includes(id)) {
+        db.prepare(`
+          UPDATE startup_tasks SET status = 'parked', park_reason = ?, parked_at = ? WHERE ctm_session_id = ?
+        `).run(PARK_REASON, parkedAt, id);
+        changed.parked.push(String(id));
+      }
+      changed.startup_tasks.push(String(id));
+    }
+    for (const resourceId of plan.rows.resource_leases.ids) {
+      changed.resource_leases += db.prepare(`
+        UPDATE resource_leases SET holder_instance_id = ?
+         WHERE resource_type = 'ctm_session' AND holder_instance_id = ? AND resource_id = ?
+      `).run(prior, currentId, resourceId).changes || 0;
+    }
+    for (const logicalId of plan.rows.workspace_bindings.logicalIds) {
+      changed.workspace_bindings += db.prepare(`
+        UPDATE workspace_bindings SET host_instance_id = ?
+         WHERE logical_id = ? AND host_instance_id = ?
+      `).run(prior, logicalId, currentId).changes || 0;
+    }
+  });
+  run();
+  const report = {
+    at: parkedAt,
+    dbPath,
+    backupPath,
+    currentId,
+    edge: plan.edge,
+    foreignComponent: plan.foreignComponent,
+    changed,
+  };
+  fs.writeFileSync(path.join(backupDir, 'report.json'), `${JSON.stringify(report, null, 2)}\n`);
+  return { applied: true, backupDir, backupPath, report, changed };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { edgePrior: '', dataDir: '', apply: false, json: false };
+  const list = Array.isArray(argv) ? argv : [];
+  for (let i = 0; i < list.length; i += 1) {
+    const token = String(list[i] ?? '');
+    if (token === '--apply') { args.apply = true; continue; }
+    if (token === '--json') { args.json = true; continue; }
+    if (token === '--edge-prior' || token === '--data-dir') {
+      const value = list[i + 1];
+      if (value === undefined || String(value).startsWith('--')) throw refusal(EXIT.USAGE, `${token} requires a value. ${USAGE}`);
+      i += 1;
+      if (token === '--edge-prior') args.edgePrior = String(value).trim();
+      else args.dataDir = String(value).trim();
+      continue;
+    }
+    if (token.startsWith('--edge-prior=')) { args.edgePrior = token.slice('--edge-prior='.length).trim(); continue; }
+    if (token.startsWith('--data-dir=')) { args.dataDir = token.slice('--data-dir='.length).trim(); continue; }
+    throw refusal(EXIT.USAGE, `unknown argument: ${token}. ${USAGE}`);
+  }
+  // An explicitly EMPTY --data-dir must not silently fall back to the operator's real data dir.
+  if (args.dataDir === '' && (Array.isArray(argv) && argv.some((token) => String(token).startsWith('--data-dir')))) {
+    throw refusal(EXIT.USAGE, `--data-dir requires a value. ${USAGE}`);
+  }
+  return args;
+}
+
+function printPlan(write, plan, { apply }) {
+  write(`[repair-foreign-clone] data dir:   ${plan.dataDir}\n`);
+  write(`[repair-foreign-clone] database:   ${plan.dbPath}\n`);
+  write(`[repair-foreign-clone] current id: ${plan.currentId}\n`);
+  write(`[repair-foreign-clone] edge:       id=${plan.edge.id} prior=${plan.edge.prior} detected_at=${plan.edge.detectedAt} cross_host=${JSON.stringify(plan.edge.crossHost)}\n`);
+  write(`[repair-foreign-clone] foreign component: ${plan.foreignComponent.length} id(s)\n`);
+  write(`[repair-foreign-clone] ctm_sessions:   foreign=${plan.rows.ctm_sessions.foreign.length} native=${plan.rows.ctm_sessions.native}\n`);
+  write(`[repair-foreign-clone] startup_tasks:  foreign=${plan.rows.startup_tasks.foreign.length} (to park ${plan.rows.startup_tasks.park.length}) native=${plan.rows.startup_tasks.native}\n`);
+  write(`[repair-foreign-clone] resource_leases to restore:    ${plan.rows.resource_leases.ids.length}\n`);
+  write(`[repair-foreign-clone] workspace_bindings to restore: ${plan.rows.workspace_bindings.logicalIds.length}\n`);
+  if (!apply) write('[repair-foreign-clone] dry run — nothing written. Re-run with --apply to repair.\n');
+}
+
+function main(argv, io = {}) {
+  const out = io.stdout || process.stdout;
+  const err = io.stderr || process.stderr;
+  try {
+    const args = parseArgs(argv);
+    if (!args.edgePrior) throw refusal(EXIT.USAGE, `--edge-prior is required. ${USAGE}`);
+    const dataDir = path.resolve(String(args.dataDir || '').trim() || getDataDir());
+    const dbPath = resolveDatabasePath(dataDir);
+    assertOffline(dataDir, dbPath);
+    const db = openDatabase(dbPath, { readonly: !args.apply });
+    try {
+      const plan = planRepair(db, { edgePrior: args.edgePrior, dataDir, dbPath });
+      if (args.json) out.write(`${JSON.stringify(plan, null, 2)}\n`);
+      else printPlan((text) => out.write(text), plan, { apply: args.apply });
+      if (!args.apply) return EXIT.OK;
+      if (isNothingToRepair(plan)) {
+        out.write('[repair-foreign-clone] nothing to repair — no backup taken\n');
+        return EXIT.OK;
+      }
+      out.write('[repair-foreign-clone] --apply: taking a verified backup, then repairing in one transaction\n');
+      const result = applyRepair(db, plan, { dataDir, dbPath });
+      out.write(`[repair-foreign-clone] repaired ${result.changed.ctm_sessions.length} session(s), ${result.changed.startup_tasks.length} task(s) (${result.changed.parked.length} parked)\n`);
+      out.write(`[repair-foreign-clone] backup: ${result.backupPath}\n`);
+      out.write(`[repair-foreign-clone] report: ${path.join(result.backupDir, 'report.json')}\n`);
+      return EXIT.OK;
+    } finally {
+      try { db.close(); } catch { /* expected: already-closed handle */ }
+    }
+  } catch (error) {
+    err.write(`[repair-foreign-clone] ${String(error?.message || error)}\n`);
+    return Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+  }
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = {
+  EXIT,
+  resolveDatabasePath,
+  assertOffline,
+  planRepair,
+  applyRepair,
+  isNothingToRepair,
+  main,
+};