@logicseek/hello-cc 0.1.8 → 1.0.0

package/lib/core/peers/tmux-safety.mjs

@@ -0,0 +1,290 @@
+import { compareProcessIdentity } from '../../process/identity.mjs';
+import { tx } from '../../db/schema.mjs';
+import { CliError } from '../../shared/errors.mjs';
+
+function completeIdentity(identity) {
+  return Boolean(
+    identity &&
+    Number.isInteger(Number(identity.pid)) &&
+    Number(identity.pid) > 0 &&
+    identity.startToken &&
+    /^[a-f0-9]{64}$/i.test(String(identity.commandHash || ''))
+  );
+}
+
+export function validateTmuxDestructiveEvidence(stored = {}, observed = {}, options = {}) {
+  const authority = validateTmuxAuthorityEvidence(stored, observed);
+  if (!authority.ok) return authority;
+  if (!completeIdentity(observed.process_identity) ||
+      compareProcessIdentity(stored.process_identity, observed.process_identity) !== 'live') {
+    return { ok: false, reason: 'tmux_process_changed' };
+  }
+  return validateTmuxClients(observed, options);
+}
+
+function validateTmuxAuthorityEvidence(stored, observed) {
+  if (!stored.session || !stored.session_created || !stored.session_id || !stored.root || !stored.pane || !completeIdentity(stored.process_identity)) {
+    return { ok: false, reason: 'tmux_stored_evidence_incomplete' };
+  }
+  if (!observed.session || observed.session !== stored.session) {
+    return { ok: false, reason: 'tmux_session_changed' };
+  }
+  if (!observed.session_created || observed.session_created !== stored.session_created) {
+    return { ok: false, reason: 'tmux_session_reused' };
+  }
+  if (!observed.session_id || observed.session_id !== stored.session_id) {
+    return { ok: false, reason: 'tmux_session_id_changed' };
+  }
+  if (!observed.root) return { ok: false, reason: 'tmux_root_unknown' };
+  if (observed.root !== stored.root) return { ok: false, reason: 'tmux_root_changed' };
+  if (!observed.pane || observed.pane !== stored.pane) {
+    return { ok: false, reason: 'tmux_pane_changed' };
+  }
+  return { ok: true };
+}
+
+function validateTmuxClients(observed, options) {
+  if (observed.clients?.state !== 'known') {
+    return { ok: false, reason: 'tmux_clients_unknown' };
+  }
+  if (!options.allowClients && Number(observed.clients.count || 0) > 0) {
+    return { ok: false, reason: 'tmux_has_clients' };
+  }
+  return { ok: true };
+}
+
+export function validateTmuxGcDeadProcessEvidence(stored = {}, observed = {}, options = {}) {
+  const authority = validateTmuxAuthorityEvidence(stored, observed);
+  if (!authority.ok) return authority;
+  if (!observed.pane_dead) return { ok: false, reason: 'tmux_pane_not_dead' };
+  if (Number(observed.pane_pid) !== Number(stored.process_identity.pid)) {
+    return { ok: false, reason: 'tmux_dead_process_pid_changed' };
+  }
+  if (observed.process_inspection?.state !== 'dead' || observed.process_inspection.identity !== null) {
+    return { ok: false, reason: 'tmux_process_not_confirmed_dead' };
+  }
+  return validateTmuxClients(observed, options);
+}
+
+export function validateTmuxGcBindingEvidence(subject = {}, observed = {}, options = {}) {
+  const authority = subject.authority;
+  if (!subject.peer || subject.transport !== 'tmux' || !subject.runtime_target ||
+      !subject.expected_session || !subject.expected_root || !authority) {
+    return { ok: false, reason: 'tmux_binding_subject_incomplete' };
+  }
+  if (authority.session !== subject.expected_session) {
+    return { ok: false, reason: 'tmux_binding_session_authority_changed' };
+  }
+  if (authority.root !== subject.expected_root) {
+    return { ok: false, reason: 'tmux_binding_root_authority_changed' };
+  }
+  if (authority.pane !== subject.runtime_target) {
+    return { ok: false, reason: 'tmux_binding_pane_authority_changed' };
+  }
+  if (subject.owner_evidence?.state === 'live') {
+    return { ok: false, reason: 'tmux_owner_process_live' };
+  }
+
+  const dead = validateTmuxGcDeadProcessEvidence(authority, observed, options);
+  if (dead.ok) return { ok: true, mode: 'dead_process' };
+  if (subject.status !== 'exited') return dead;
+
+  const live = validateTmuxDestructiveEvidence(authority, observed, options);
+  return live.ok ? { ok: true, mode: 'explicit_exit_live' } : live;
+}
+
+export function finalizeTmuxGcBindingMutation(options = {}) {
+  const {
+    db,
+    plannedSubject,
+    readSubject,
+    sameSubject,
+    conditionalKill,
+    casBinding,
+    updatePeer,
+    beforeBegin
+  } = options;
+  for (const [name, fn] of Object.entries({ readSubject, sameSubject, conditionalKill, casBinding, updatePeer })) {
+    if (typeof fn !== 'function') throw new TypeError(`${name} must be a function`);
+  }
+  if (!db) throw new TypeError('db is required');
+  if (typeof beforeBegin === 'function') beforeBegin();
+
+  return tx(db, () => {
+    const currentSubject = readSubject();
+    if (!sameSubject(plannedSubject, currentSubject)) {
+      throw new CliError('TMUX_GC_BINDING_SUBJECT_CHANGED',
+        'tmux GC binding subject changed before final mutation');
+    }
+    conditionalKill();
+    const bindingResult = casBinding(currentSubject);
+    if (Number(bindingResult?.changes) !== 1) {
+      throw new CliError('TMUX_GC_BINDING_CAS_FAILED',
+        'tmux GC binding compare-and-swap did not update exactly one row');
+    }
+    updatePeer(currentSubject);
+    return currentSubject;
+  });
+}
+
+export function prepareTmuxRestartBinding(db, {
+  peer,
+  runtimeTarget,
+  nowSec
+} = {}) {
+  if (!db || typeof db.prepare !== 'function') throw new TypeError('db is required');
+  if (typeof peer !== 'string' || !peer) throw new TypeError('peer is required');
+  if (typeof runtimeTarget !== 'string' || !runtimeTarget) {
+    throw new TypeError('runtimeTarget is required');
+  }
+  if (!Number.isSafeInteger(nowSec) || nowSec < 0) {
+    throw new TypeError('nowSec must be a non-negative safe integer');
+  }
+  const row = db.prepare(`
+    SELECT transport, runtime_target, updated_at
+    FROM peer_bindings
+    WHERE peer = ?
+  `).get(peer);
+  if (!row) return { ok: false, reason: 'tmux_binding_missing' };
+  if (row.transport !== 'tmux') return { ok: false, reason: 'tmux_binding_transport_changed' };
+  if (row.runtime_target === runtimeTarget) return { ok: true, restored: false };
+  if (row.runtime_target !== null) return { ok: false, reason: 'tmux_binding_target_changed' };
+
+  const previousUpdatedAt = Number(row.updated_at);
+  if (!Number.isSafeInteger(previousUpdatedAt) || previousUpdatedAt < 0) {
+    return { ok: false, reason: 'tmux_binding_timestamp_invalid' };
+  }
+  const preparedUpdatedAt = Math.max(nowSec, previousUpdatedAt + 1);
+  if (!Number.isSafeInteger(preparedUpdatedAt)) {
+    return { ok: false, reason: 'tmux_binding_timestamp_invalid' };
+  }
+  const updated = db.prepare(`
+    UPDATE peer_bindings
+    SET runtime_target = ?, updated_at = ?
+    WHERE peer = ? AND transport = 'tmux' AND runtime_target IS NULL
+      AND updated_at IS ?
+  `).run(runtimeTarget, preparedUpdatedAt, peer, previousUpdatedAt);
+  if (Number(updated.changes) !== 1) {
+    return { ok: false, reason: 'tmux_binding_subject_changed' };
+  }
+  return {
+    ok: true,
+    restored: true,
+    peer,
+    runtimeTarget,
+    previousUpdatedAt,
+    preparedUpdatedAt
+  };
+}
+
+export function rollbackTmuxRestartBinding(db, preparation) {
+  if (!preparation?.restored) return true;
+  const updated = db.prepare(`
+    UPDATE peer_bindings
+    SET runtime_target = NULL, updated_at = ?
+    WHERE peer = ? AND transport = 'tmux' AND runtime_target = ?
+      AND updated_at = ?
+  `).run(
+    preparation.previousUpdatedAt,
+    preparation.peer,
+    preparation.runtimeTarget,
+    preparation.preparedUpdatedAt
+  );
+  return Number(updated.changes) === 1;
+}
+
+const KILL_OK = 'HCC_CONDITIONAL_KILL_OK';
+const KILL_MISMATCH = 'HCC_CONDITIONAL_KILL_MISMATCH';
+const RENAME_OK = 'HCC_CONDITIONAL_RENAME_OK';
+const RENAME_MISMATCH = 'HCC_CONDITIONAL_RENAME_MISMATCH';
+
+function conditionalFields(stored, {
+  code = 'TMUX_CONDITIONAL_KILL_MISMATCH',
+  operation = 'conditional-kill'
+} = {}) {
+  const fields = {
+    session: String(stored?.session || ''),
+    sessionCreated: String(stored?.session_created || ''),
+    sessionId: String(stored?.session_id || ''),
+    pane: String(stored?.pane || ''),
+    panePid: String(stored?.process_identity?.pid || '')
+  };
+  if (!/^[a-zA-Z0-9_.-]+$/.test(fields.session) ||
+      !/^\d+$/.test(fields.sessionCreated) ||
+      !/^\$\d+$/.test(fields.sessionId) ||
+      !/^%\d+$/.test(fields.pane) ||
+      !/^\d+$/.test(fields.panePid)) {
+    throw new CliError(code, `Stored tmux ${operation} identity is incomplete or invalid`);
+  }
+  return fields;
+}
+
+function tmuxIdentityCondition(fields) {
+  return `#{&&:#{==:#{session_name},${fields.session}},#{&&:#{==:#{session_created},${fields.sessionCreated}},#{&&:#{==:#{session_id},${fields.sessionId}},#{&&:#{==:#{pane_id},${fields.pane}},#{==:#{pane_pid},${fields.panePid}}}}}}`;
+}
+
+export function conditionalTmuxKill(runTmux, stored, options = {}) {
+  if (typeof runTmux !== 'function') throw new TypeError('runTmux must be a function');
+  const fields = conditionalFields(stored);
+  if (typeof options.beforeConditional === 'function') options.beforeConditional();
+  const identityCondition = tmuxIdentityCondition(fields);
+  const processCondition = options.requireDeadPane
+    ? `#{&&:${identityCondition},#{==:#{pane_dead},1}}`
+    : identityCondition;
+  const condition = options.allowClients
+    ? processCondition
+    : `#{&&:${processCondition},#{==:#{session_attached},0}}`;
+  const successCommand = `display-message -p ${KILL_OK} ; kill-session -t '${fields.sessionId}'`;
+  let output = '';
+  try {
+    output = runTmux([
+      'if-shell', '-F', '-t', fields.session,
+      condition,
+      successCommand,
+      `display-message -p ${KILL_MISMATCH}`
+    ]);
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError('TMUX_ERROR',
+      `Conditional tmux kill command failed: ${error?.message || error}`);
+  }
+  if (!String(output).split('\n').includes(KILL_OK)) {
+    throw new CliError('TMUX_CONDITIONAL_KILL_MISMATCH', 'Conditional tmux kill target changed before execution');
+  }
+  return { killed: true };
+}
+
+export function conditionalTmuxRename(runTmux, stored, newName, options = {}) {
+  if (typeof runTmux !== 'function') throw new TypeError('runTmux must be a function');
+  const fields = conditionalFields(stored, {
+    code: 'TMUX_CONDITIONAL_RENAME_MISMATCH',
+    operation: 'conditional-rename'
+  });
+  const targetName = String(newName || '');
+  if (!/^[a-zA-Z0-9_.-]+$/.test(targetName) || targetName === fields.session) {
+    throw new CliError('TMUX_CONDITIONAL_RENAME_MISMATCH', 'Replacement tmux session name is incomplete or invalid');
+  }
+  if (typeof options.beforeConditional === 'function') options.beforeConditional();
+  const identityCondition = tmuxIdentityCondition(fields);
+  const condition = options.allowClients
+    ? identityCondition
+    : `#{&&:${identityCondition},#{==:#{session_attached},0}}`;
+  const successCommand = `display-message -p ${RENAME_OK} ; rename-session -t '${fields.sessionId}' ${targetName}`;
+  let output = '';
+  try {
+    output = runTmux([
+      'if-shell', '-F', '-t', fields.session,
+      condition,
+      successCommand,
+      `display-message -p ${RENAME_MISMATCH}`
+    ]);
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError('TMUX_ERROR',
+      `Conditional tmux rename command failed: ${error?.message || error}`);
+  }
+  if (!String(output).split('\n').includes(RENAME_OK)) {
+    throw new CliError('TMUX_CONDITIONAL_RENAME_MISMATCH', 'Conditional tmux rename target changed before execution');
+  }
+  return { renamed: true, session: targetName };
+}

package/lib/core/sessions/launch.mjs

@@ -14,6 +14,7 @@ const LAUNCH_ENV_IGNORED_KEYS = new Set([
   'HCC_NO_AUTO_INSTALL_TMUX',
   'HCC_PEER',
   'HCC_ROOT',
+  'HCC_RUNTIME_LOCAL_ONLY',
   'HCC_SKIP_SHIM_INSTALL',
   PROVIDER_STATE_ENV,
   'HCC_SHIM_ENSURED',
@@ -30,14 +31,20 @@ const LAUNCH_ENV_IGNORED_KEYS = new Set([
   'SHLVL',
   'TERM',
   'TERMCAP',
+  'TERM_SESSION_ID',
+  'TMPDIR',
   'TMUX',
   'TMUX_PANE',
-  'WINDOWID'
+  'WINDOWID',
+  'XPC_FLAGS',
+  'XPC_SERVICE_NAME',
+  'SSH_AUTH_SOCK'
 ]);
 
 export function childSessionEnv(extra = {}, baseEnv = process.env) {
   const env = { ...(baseEnv || {}), ...extra };
   delete env[WEB_CHILD_ENV];
+  delete env.HCC_RUNTIME_LOCAL_ONLY;
   return env;
 }
 
@@ -77,6 +84,13 @@ export function isRelaunchableProviderSession(kind, command, binding = {}) {
   return ['claude', 'codex'].includes(provider) && isProviderFallbackWrapper(command);
 }
 
+export function providerRestartReason({ providerState, ownerEvidence, paneCommand } = {}) {
+  if (ownerEvidence?.state !== 'dead') return null;
+  if (providerState === 'exited') return 'provider_exited';
+  if (!providerState && isLikelyShellCommand(paneCommand)) return 'provider_fallback_shell';
+  return null;
+}
+
 export function isolatedEnvCommandArgs(env) {
   const envBin = fs.existsSync('/usr/bin/env') ? '/usr/bin/env' : 'env';
   const args = [envBin, '-i'];

package/lib/db/connection.mjs

@@ -0,0 +1,104 @@
+// Database connection helpers extracted from bin/hcc.mjs.
+// Factory pattern: callers inject the functions that remain in bin/hcc.mjs
+// (now, dedupePeerBindings, redactedLogText) while everything else is imported
+// directly from lib/ modules.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { CliError } from '../shared/errors.mjs';
+import {
+  DB_SCHEMA_VERSION,
+  execWithBusyRetry
+} from './schema.mjs';
+import { initSchemaWithBackup } from './migration-backup.mjs';
+import { readProjectRegistry } from '../runtime/projects.mjs';
+import { resolveProjectDatabase } from '../runtime/project-path.mjs';
+
+const MIGRATION_FAILURE_COOLDOWN_MS = 5 * 60 * 1000;
+
+export function createConnectionHelpers({ now, dedupePeerBindings, redactedLogText }) {
+  let projectMigrationFanoutDepth = 0;
+  const migratedRegisteredProjectDbs = new Set();
+
+  function connect(ctx, options = {}) {
+    if (options.create === false && !fs.existsSync(ctx.dbPath)) {
+      throw new CliError('NOT_FOUND', `Project database does not exist: ${ctx.dbPath}`);
+    }
+    if (options.create !== false) fs.mkdirSync(path.dirname(ctx.dbPath), { recursive: true });
+    const db = new DatabaseSync(ctx.dbPath, { timeout: 5000 });
+    db.exec('PRAGMA busy_timeout = 5000;');
+    execWithBusyRetry(db, 'PRAGMA journal_mode = WAL;', { ignoreBusy: true });
+    db.exec('PRAGMA synchronous = NORMAL;');
+    db.exec('PRAGMA wal_autocheckpoint = 1000;');
+    db.exec('PRAGMA foreign_keys = ON;');
+    initSchemaWithBackup(db, ctx.dbPath, {
+      beforePostMigrationIndexes: dedupePeerBindings
+    });
+    if (options.migrateRegistered !== false) migrateRegisteredProjectDbs(ctx);
+    return db;
+  }
+
+  function connectReadOnly(ctx) {
+    if (!fs.existsSync(ctx.dbPath) || !fs.statSync(ctx.dbPath).isFile()) {
+      throw new CliError('NOT_FOUND', `Project database does not exist: ${ctx.dbPath}`);
+    }
+    return new DatabaseSync(ctx.dbPath, { timeout: 5000, readOnly: true });
+  }
+
+  function migrateRegisteredProjectDbs(ctx) {
+    if (projectMigrationFanoutDepth > 0) return;
+    projectMigrationFanoutDepth += 1;
+    try {
+      const currentDb = path.resolve(ctx.dbPath);
+      const seen = new Set([currentDb]);
+      for (const project of readProjectRegistry()) {
+        let resolved;
+        try {
+          resolved = resolveProjectDatabase({
+            root: project.root,
+            db: project.db || path.join(project.root, '.hello-cc', 'mesh.db'),
+            createStateDir: false
+          });
+        } catch (err) {
+          console.error(redactedLogText(`[${new Date().toISOString()}] skipping registered project DB migration for ${project.db || project.root}: ${err?.message || err}`));
+          continue;
+        }
+        const root = resolved.root;
+        const dbPath = resolved.db;
+        if (seen.has(dbPath)) continue;
+        seen.add(dbPath);
+        const cacheKey = `${dbPath}:${DB_SCHEMA_VERSION}`;
+        if (migratedRegisteredProjectDbs.has(cacheKey)) continue;
+        if (!fs.existsSync(root) || !fs.existsSync(dbPath)) continue;
+        const failedMarker = `${dbPath}.migration-failed`;
+        try {
+          if (Date.now() - fs.statSync(failedMarker).mtimeMs < MIGRATION_FAILURE_COOLDOWN_MS) continue;
+        } catch {}
+        let db = null;
+        try {
+          db = new DatabaseSync(dbPath, { timeout: 5000 });
+          db.exec('PRAGMA busy_timeout = 5000;');
+          execWithBusyRetry(db, 'PRAGMA journal_mode = WAL;', { ignoreBusy: true });
+          db.exec('PRAGMA synchronous = NORMAL;');
+          db.exec('PRAGMA foreign_keys = ON;');
+          initSchemaWithBackup(db, dbPath, {
+            beforePostMigrationIndexes: dedupePeerBindings
+          });
+          migratedRegisteredProjectDbs.add(cacheKey);
+          try { fs.rmSync(failedMarker, { force: true }); } catch {}
+        } catch (err) {
+          console.error(redactedLogText(`[${new Date().toISOString()}] skipping registered project DB migration for ${dbPath}: ${err?.message || err}`));
+          try { fs.writeFileSync(failedMarker, String(now())); } catch {}
+          continue;
+        } finally {
+          try { db?.close(); } catch {}
+        }
+      }
+    } finally {
+      projectMigrationFanoutDepth -= 1;
+    }
+  }
+
+  return { connect, connectReadOnly, migrateRegisteredProjectDbs };
+}

package/lib/db/events.mjs

@@ -0,0 +1,34 @@
+// Shared DB event/audit helpers extracted from bin/hcc.mjs.
+// These are pure functions with a single dependency (now()) that callers
+// inject, so they can be reused by CLI commands, web routes, and tests.
+
+function defaultNow() {
+  return Math.floor(Date.now() / 1000);
+}
+
+export function createEventHelpers({ now = defaultNow } = {}) {
+  function addEvent(db, type, actor, taskId, payload) {
+    db.prepare(`
+      INSERT INTO events(type, actor, task_id, payload, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(type, actor || null, taskId || null, JSON.stringify(payload || {}), now());
+  }
+
+  function auditPayload({ actor = null, target = null, source = 'cli', admin = false, ...extra } = {}) {
+    const payload = { ...extra, source };
+    if (actor) payload.actor_peer = actor;
+    if (target) payload.target_peer = target;
+    if (admin) payload.admin = true;
+    return payload;
+  }
+
+  function requestActorPeer(input = {}, fallback = 'web') {
+    return String(input.auditActorPeer || fallback || 'web').trim() || 'web';
+  }
+
+  function requestSource(input = {}, fallback = 'web') {
+    return String(input.auditSource || fallback || 'web').trim() || fallback;
+  }
+
+  return { addEvent, auditPayload, requestActorPeer, requestSource };
+}

package/lib/db/migration-backup.mjs

@@ -0,0 +1,225 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import {
+  DB_SCHEMA_VERSION,
+  initSchema,
+  readSchemaVersion
+} from './schema.mjs';
+import { withFileLock } from '../shared/file-lock.mjs';
+
+const MAX_BACKUP_COMPONENT_BYTES = 240;
+// v1-02: keep at most this many migration backups per database basename.
+const MAX_BACKUPS_PER_DB = 5;
+
+function quoteSqlString(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function defaultTimestamp() {
+  return new Date().toISOString().replace(/[-:.]/g, '');
+}
+
+function defaultSuffix() {
+  return randomBytes(4).toString('hex');
+}
+
+function backupFilename(dbBasename, fromVersion, toVersion, timestamp, suffix) {
+  return `${dbBasename}.pre-v${fromVersion}-to-v${toVersion}.${timestamp}.${suffix}.bak`;
+}
+
+function boundedDbBasename(dbPath, fromVersion, toVersion, timestamp) {
+  const dbBasename = path.basename(dbPath);
+  const finalName = backupFilename(dbBasename, fromVersion, toVersion, timestamp, 'ffffffff');
+  const stagingName = `.${dbBasename}.migration-backup-XXXXXX`;
+  if (Buffer.byteLength(finalName) <= MAX_BACKUP_COMPONENT_BYTES &&
+      Buffer.byteLength(stagingName) <= MAX_BACKUP_COMPONENT_BYTES) {
+    return dbBasename;
+  }
+  const hash = createHash('sha256').update(dbBasename).digest('hex').slice(0, 16);
+  return `db-${hash}`;
+}
+
+function syncPath(target) {
+  const fd = fs.openSync(target, 'r');
+  let syncError = null;
+  try {
+    fs.fsyncSync(fd);
+  } catch (err) {
+    syncError = err;
+  }
+  try {
+    fs.closeSync(fd);
+  } catch (closeError) {
+    if (syncError) {
+      throw new AggregateError([syncError, closeError], `Failed to sync and close ${target}`);
+    }
+    throw closeError;
+  }
+  if (syncError) throw syncError;
+}
+
+function removeStagingDirectory(tempDirectory) {
+  let lastError;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fs.rmSync(tempDirectory, { recursive: true, force: true });
+      return;
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  throw new Error(`Failed to remove migration backup staging directory: ${tempDirectory}`, {
+    cause: lastError
+  });
+}
+
+function verifyBackup(backupPath) {
+  const backup = new DatabaseSync(backupPath, { readOnly: true });
+  try {
+    const rows = backup.prepare('PRAGMA quick_check').all();
+    if (rows.length !== 1 || rows[0]?.quick_check !== 'ok') {
+      throw new Error(`Migration backup failed SQLite quick_check: ${backupPath}`);
+    }
+  } finally {
+    backup.close();
+  }
+}
+
+export function initSchemaWithBackup(db, dbPath, {
+  beforePostMigrationIndexes = null,
+  ensureBackup = ensureMigrationBackup,
+  withLock = withFileLock
+} = {}) {
+  const initialize = (lockedDbPath = dbPath) => initSchema(db, {
+    beforeMigration: ({ fromVersion, toVersion }) =>
+      ensureBackup(db, lockedDbPath, fromVersion, toVersion),
+    beforePostMigrationIndexes
+  });
+  if (readSchemaVersion(db) >= DB_SCHEMA_VERSION) return initialize();
+  return withLock(dbPath, (lockedDbPath) => initialize(lockedDbPath));
+}
+
+export function ensureMigrationBackup(db, dbPath, fromVersion, toVersion, {
+  timestamp = defaultTimestamp,
+  suffix = defaultSuffix,
+  verifySnapshot = verifyBackup
+} = {}) {
+  if (!Number.isInteger(fromVersion) || fromVersion < 0 ||
+      !Number.isInteger(toVersion) || toVersion <= fromVersion) {
+    throw new TypeError(`Invalid migration version range: ${fromVersion} to ${toVersion}`);
+  }
+  // v1-03: under a racing migration, this connection may already observe the
+  // migrated version (another process migrated between our stale version read
+  // and this call). Backing it up would mislabel an already-migrated DB as
+  // pre-v<from>-to-v<to>; skip the backup entirely in that case.
+  try {
+    const pragma = db.prepare('PRAGMA user_version').get();
+    const actualVersion = Number(pragma?.user_version || 0);
+    if (Number.isInteger(actualVersion) && actualVersion >= toVersion) return null;
+  } catch {
+    // Cannot read the version — proceed conservatively with the backup.
+  }
+  const timestampValue = timestamp();
+  if (!/^\d{8}T\d{9}Z$/.test(timestampValue)) {
+    throw new TypeError(`Invalid migration backup timestamp: ${timestampValue}`);
+  }
+
+  const directory = path.dirname(path.resolve(dbPath));
+  const dbBasename = boundedDbBasename(dbPath, fromVersion, toVersion, timestampValue);
+  let tempDirectory;
+  let backupPath;
+  let operationError = null;
+  try {
+    tempDirectory = fs.mkdtempSync(path.join(directory, `.${dbBasename}.migration-backup-`));
+    fs.chmodSync(tempDirectory, 0o700);
+    const tempPath = path.join(tempDirectory, 'snapshot.db');
+    db.exec(`VACUUM INTO ${quoteSqlString(tempPath)};`);
+    fs.chmodSync(tempPath, 0o600);
+    syncPath(tempPath);
+    verifySnapshot(tempPath);
+
+    for (let attempt = 0; attempt < 128; attempt += 1) {
+      const suffixValue = suffix();
+      if (!/^[a-f0-9]{8}$/.test(suffixValue)) {
+        throw new TypeError(`Invalid migration backup suffix: ${suffixValue}`);
+      }
+      const candidate = path.join(
+        directory,
+        backupFilename(dbBasename, fromVersion, toVersion, timestampValue, suffixValue)
+      );
+      try {
+        // Linking publishes the already-verified inode exclusively. EEXIST is
+        // safe for regular files and symlinks: neither is followed or replaced.
+        fs.linkSync(tempPath, candidate);
+        backupPath = candidate;
+        break;
+      } catch (err) {
+        if (err?.code === 'EEXIST') continue;
+        throw err;
+      }
+    }
+    if (!backupPath) throw new Error('Unable to allocate a unique migration backup path');
+  } catch (err) {
+    operationError = err;
+  }
+
+  let cleanupError = null;
+  if (tempDirectory) {
+    try {
+      removeStagingDirectory(tempDirectory);
+    } catch (err) {
+      cleanupError = err;
+    }
+  }
+  if (operationError && cleanupError) {
+    throw new AggregateError(
+      [operationError, cleanupError],
+      'Migration backup failed and staging cleanup also failed'
+    );
+  }
+  if (operationError) throw operationError;
+  if (cleanupError) throw cleanupError;
+
+  syncPath(directory);
+  rotateBackups(directory, dbBasename, backupPath);
+  return backupPath;
+}
+
+// v1-02: prune old migration backups for this database, keeping the most
+// recent MAX_BACKUPS_PER_DB. Backups are full DB copies; without rotation a
+// long-lived project accumulates them on every failed/racing migration attempt.
+function rotateBackups(directory, dbBasename, publishedPath) {
+  const escapedBasename = dbBasename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const backupPattern = new RegExp(
+    `^${escapedBasename}\\.pre-v(\\d+)-to-v(\\d+)\\.(\\d{8}T\\d{9}Z)\\.([a-f0-9]{8})\\.bak$`
+  );
+  const publishedName = path.basename(publishedPath);
+  let entries = [];
+  try {
+    entries = fs.readdirSync(directory);
+  } catch {
+    return;
+  }
+  const backups = entries
+    .map((name) => {
+      const match = name.match(backupPattern);
+      if (!match) return null;
+      try {
+        if (!fs.lstatSync(path.join(directory, name)).isFile()) return null;
+        return { name, timestamp: match[3] };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => {
+      if (a.name === publishedName) return b.name === publishedName ? 0 : -1;
+      if (b.name === publishedName) return 1;
+      return b.timestamp.localeCompare(a.timestamp) || b.name.localeCompare(a.name);
+    });
+  for (const old of backups.slice(MAX_BACKUPS_PER_DB)) {
+    try { fs.rmSync(path.join(directory, old.name), { force: true }); } catch {}
+  }
+}