ultra-builder-pro-cli 0.12.1 → 0.13.0

package/ultra-tools/commands/migrate.cjs

@@ -3,12 +3,17 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { initStateDb, openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const {
+  initStateDb, openStateDb, closeStateDb, MIGRATED_GAPS,
+} = require('../../mcp-server/lib/state-db.cjs');
 const ops = require('../../mcp-server/lib/state-ops.cjs');
 const projector = require('../../mcp-server/lib/projector.cjs');
 
-const SUPPORTED_FROM = '4.4';
-const SUPPORTED_TO = '4.5';
+const DEFAULT_FROM = '4.4';
+const SUPPORTED_TRANSITIONS = Object.freeze({
+  '4.4': '4.5',
+  '4.5': '12.0',
+});
 
 // Frozen SQL — values flow through parameter bindings.
 const RECORD_MIGRATION_SQL = "INSERT INTO migration_history (from_version, to_version, direction, status, notes) VALUES (@from, @to, @direction, @status, @notes)";
@@ -73,7 +78,7 @@ function copyDirSync(src, dst) {
     const s = path.join(src, entry.name);
     const d = path.join(dst, entry.name);
     if (entry.name === 'state.db' || entry.name === 'state.db-wal' || entry.name === 'state.db-shm') continue;
-    if (entry.name.startsWith('backup-v4.4-')) continue;
+    if (/^backup-v[^/]+-/.test(entry.name)) continue;
     if (entry.isDirectory()) copyDirSync(s, d);
     else fs.copyFileSync(s, d);
   }
@@ -148,15 +153,15 @@ function normalizeLegacyTask(task, tasksJson, contextHeaders, sourceDir) {
   };
 }
 
-function planForward(sourceDir) {
+function planForward(sourceDir, expectedFrom = DEFAULT_FROM) {
   const tasksPath = path.join(sourceDir, '.ultra', 'tasks', 'tasks.json');
   const tasksJson = readJsonOptional(tasksPath);
   if (!tasksJson || !Array.isArray(tasksJson.tasks)) {
     throw new Error(`migrate: tasks.json missing or malformed at ${tasksPath}`);
   }
   const version = String(tasksJson.version || tasksJson.schema_version || '');
-  if (version !== SUPPORTED_FROM) {
-    throw new Error(`migrate: expected v${SUPPORTED_FROM} tasks.json, found ${version || '(missing version)'}`);
+  if (version !== expectedFrom) {
+    throw new Error(`migrate: expected v${expectedFrom} tasks.json, found ${version || '(missing version)'}`);
   }
 
   const contextHeaders = {};
@@ -173,7 +178,7 @@ function planForward(sourceDir) {
         task_id: task.id,
         json_status: task.status,
         context_status: ctx.status,
-        resolution: 'tasks.json wins (v4.4 → v4.5 D21 rule)',
+        resolution: `tasks.json wins (v${expectedFrom} projection migration rule)`,
       });
     }
   }
@@ -190,6 +195,7 @@ function planForward(sourceDir) {
     events: eventList,
     contextHeaders,
     warnings,
+    projectName: tasksJson.project?.name || path.basename(sourceDir),
   };
 }
 
@@ -241,16 +247,17 @@ function recordMigration(db, { from, to, direction, status, notes }) {
   db.prepare(RECORD_MIGRATION_SQL).run({ from, to, direction, status, notes });
 }
 
-function ensureBackupName(sourceDir) {
+function ensureBackupName(sourceDir, fromVersion = DEFAULT_FROM) {
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  return path.join(sourceDir, '.ultra', `backup-v4.4-${ts}`);
+  return path.join(sourceDir, '.ultra', `backup-v${fromVersion}-${ts}`);
 }
 
-function findLatestBackup(sourceDir) {
+function findLatestBackup(sourceDir, fromVersion = DEFAULT_FROM) {
   const ultra = path.join(sourceDir, '.ultra');
   if (!fs.existsSync(ultra)) return null;
+  const prefix = `backup-v${fromVersion}-`;
   const candidates = fs.readdirSync(ultra)
-    .filter((n) => n.startsWith('backup-v4.4-'))
+    .filter((n) => n.startsWith(prefix))
     .sort();
   return candidates.length === 0 ? null : path.join(ultra, candidates[candidates.length - 1]);
 }
@@ -258,9 +265,11 @@ function findLatestBackup(sourceDir) {
 function cmdForward(flags) {
   const sourceDir = path.resolve(flags.sourceDir || '.');
   const dbPath = path.resolve(flags.dbPath || path.join(sourceDir, '.ultra', 'state.db'));
+  const fromVersion = flags.from || DEFAULT_FROM;
+  const toVersion = flags.to || SUPPORTED_TRANSITIONS[fromVersion];
   let plan;
   try {
-    plan = planForward(sourceDir);
+    plan = planForward(sourceDir, fromVersion);
   } catch (err) {
     emit({ ok: false, error: { code: 'MIGRATE_FAILED', message: err.message, retriable: false } });
     return 2;
@@ -271,8 +280,8 @@ function cmdForward(flags) {
       ok: true,
       data: {
         mode: 'dry',
-        from: SUPPORTED_FROM,
-        to: SUPPORTED_TO,
+        from: fromVersion,
+        to: toVersion,
         source_dir: sourceDir,
         db_path: dbPath,
         tasks_to_insert: plan.tasks.length,
@@ -284,7 +293,7 @@ function cmdForward(flags) {
   }
 
   // Real run: backup the entire .ultra subtree first.
-  const backupDir = ensureBackupName(sourceDir);
+  const backupDir = ensureBackupName(sourceDir, fromVersion);
   const ultraSource = path.join(sourceDir, '.ultra');
   copyDirSync(ultraSource, backupDir);
 
@@ -297,9 +306,18 @@ function cmdForward(flags) {
         throw new Error(`migrate: refusing to merge into non-empty state.db (tasks=${existing})`);
       }
       const inserted = applyForward(db, plan);
+      db.prepare(
+        `INSERT INTO baselines
+         (id, project_name, mode, status, gaps_json, approval_note)
+         VALUES ('migrated-baseline', ?, 'migrated', 'adopting', ?, ?)`,
+      ).run(
+        plan.projectName,
+        JSON.stringify(MIGRATED_GAPS),
+        `Legacy v${fromVersion} projection imported; evidence-backed owner re-adoption is required`,
+      );
       recordMigration(db, {
-        from: SUPPORTED_FROM,
-        to: SUPPORTED_TO,
+        from: fromVersion,
+        to: toVersion,
         direction: 'forward',
         status: 'success',
         notes: `tasks=${inserted.taskInserted} events=${inserted.eventsInserted} warnings=${plan.warnings.length}`,
@@ -312,8 +330,8 @@ function cmdForward(flags) {
       ok: true,
       data: {
         mode: 'apply',
-        from: SUPPORTED_FROM,
-        to: SUPPORTED_TO,
+        from: fromVersion,
+        to: toVersion,
         source_dir: sourceDir,
         db_path: dbPath,
         backup_dir: backupDir,
@@ -328,8 +346,8 @@ function cmdForward(flags) {
     if (db) {
       try {
         recordMigration(db, {
-          from: SUPPORTED_FROM,
-          to: SUPPORTED_TO,
+          from: fromVersion,
+          to: toVersion,
           direction: 'forward',
           status: 'failed',
           notes: err.message,
@@ -346,9 +364,11 @@ function cmdForward(flags) {
 function cmdRollback(flags) {
   const sourceDir = path.resolve(flags.sourceDir || '.');
   const dbPath = path.resolve(flags.dbPath || path.join(sourceDir, '.ultra', 'state.db'));
-  const backupDir = findLatestBackup(sourceDir);
+  const fromVersion = flags.from || DEFAULT_FROM;
+  const toVersion = flags.to || SUPPORTED_TRANSITIONS[fromVersion];
+  const backupDir = findLatestBackup(sourceDir, fromVersion);
   if (!backupDir) {
-    emit({ ok: false, error: { code: 'NO_BACKUP', message: 'no backup-v4.4-* directory found' } });
+    emit({ ok: false, error: { code: 'NO_BACKUP', message: `no backup-v${fromVersion}-* directory found` } });
     return 2;
   }
 
@@ -358,8 +378,8 @@ function cmdRollback(flags) {
     if (fs.existsSync(dbPath)) {
       db = openStateDb(dbPath);
       recordMigration(db, {
-        from: SUPPORTED_TO,
-        to: SUPPORTED_FROM,
+        from: toVersion,
+        to: fromVersion,
         direction: 'rollback',
         status: 'success',
         notes: `restored from ${backupDir}`,
@@ -376,7 +396,7 @@ function cmdRollback(flags) {
     // Restore .ultra contents from backup, leaving the backup itself in place.
     const ultraDir = path.join(sourceDir, '.ultra');
     for (const entry of fs.readdirSync(ultraDir, { withFileTypes: true })) {
-      if (entry.name.startsWith('backup-v4.4-')) continue;
+      if (/^backup-v[^/]+-/.test(entry.name)) continue;
       const target = path.join(ultraDir, entry.name);
       fs.rmSync(target, { recursive: true, force: true });
     }
@@ -386,8 +406,8 @@ function cmdRollback(flags) {
       ok: true,
       data: {
         mode: 'rollback',
-        from: SUPPORTED_TO,
-        to: SUPPORTED_FROM,
+        from: toVersion,
+        to: fromVersion,
         backup_dir: backupDir,
         source_dir: sourceDir,
       },
@@ -406,29 +426,35 @@ function dispatch(args) {
     process.stdout.write(USAGE);
     return 0;
   }
-  if (flags.from && flags.from !== SUPPORTED_FROM) {
-    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--from ${flags.from} unsupported (only ${SUPPORTED_FROM})` } });
+  const fromVersion = flags.from || DEFAULT_FROM;
+  const expectedTo = SUPPORTED_TRANSITIONS[fromVersion];
+  if (!expectedTo) {
+    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--from ${fromVersion} unsupported (supported: ${Object.keys(SUPPORTED_TRANSITIONS).join(', ')})` } });
     return 1;
   }
-  if (flags.to && flags.to !== SUPPORTED_TO) {
-    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--to ${flags.to} unsupported (only ${SUPPORTED_TO})` } });
+  if (flags.to && flags.to !== expectedTo) {
+    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--to ${flags.to} unsupported for --from ${fromVersion} (expected ${expectedTo})` } });
     return 1;
   }
   return flags.rollback ? cmdRollback(flags) : cmdForward(flags);
 }
 
-const USAGE = `ultra-tools migrate --from=4.4 --to=4.5 [flags]
+const USAGE = `ultra-tools migrate --from=<version> --to=<version> [flags]
+
+Supported transitions:
+  4.4 -> 4.5   import the legacy task projection into authoritative state
+  4.5 -> 12.0  import a projection-only project into current authoritative state
 
 Flags:
   --source-dir <dir>   project root containing .ultra/ (default: .)
   --db-path <path>     state.db destination (default: <source-dir>/.ultra/state.db)
   --dry                print the migration plan without writing
-  --rollback           restore the most recent backup-v4.4-* and drop state.db
+  --rollback           restore the most recent matching backup-v<from>-* and drop state.db
 
 The forward flow: backup .ultra/ → init state.db → insert tasks from
 tasks.json → merge context md status (tasks.json wins on conflict, warnings
 recorded) → insert activity-log events → record migration_history.
-Rollback restores from the latest backup-v4.4-* directory and writes a
+Rollback restores from the latest matching backup-v<from>-* directory and writes a
 matching migration_history rollback row before dropping state.db.
 `;
 

package/ultra-tools/commands/status.cjs

@@ -71,17 +71,26 @@ function buildCostPanel(db, { since = null, limit = 3, rootDir = process.cwd() }
   const total_cost_usd = by_runtime.reduce((acc, r) => acc + (r.cost_usd || 0), 0);
   const baselineHealth = baselines.inspectBaseline(db, { rootDir });
   const current = baselineHealth.baseline;
+  const baselineStatus = current?.status
+    || (baselineHealth.blockers.includes('BASELINE_SCHEMA_MIGRATION_REQUIRED')
+      ? 'migration_required' : 'missing');
+  const baseline = {
+    id: current?.id || null,
+    mode: current?.mode || null,
+    status: baselineStatus,
+    health: baselineHealth.status,
+    repository_revision: current?.repository_revision || null,
+    blockers: baselineHealth.blockers,
+    warnings: baselineHealth.warnings,
+  };
+  if (current) {
+    baseline.repository_branch = current.repository_branch || null;
+    baseline.worktree_state = current.worktree_state || 'unavailable';
+    baseline.gaps = baselines.summarizeGaps(current.gaps);
+  }
   return {
     period: { since: since || 'all-time' },
-    baseline: {
-      id: current?.id || null,
-      mode: current?.mode || null,
-      status: current?.status || 'missing',
-      health: baselineHealth.status,
-      repository_revision: current?.repository_revision || null,
-      blockers: baselineHealth.blockers,
-      warnings: baselineHealth.warnings,
-    },
+    baseline,
     by_runtime,
     top_tasks,
     total_cost_usd,

package/ultra-tools/commands/system.cjs

@@ -2,16 +2,323 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const Database = require('better-sqlite3');
 
-const { openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const { initStateDb, openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const { initProject } = require('../../mcp-server/lib/init-project.cjs');
 const doctor = require('../../mcp-server/lib/doctor.cjs');
 
-const USAGE = `ultra-tools system doctor [--repair]\n`;
+const RESTORE_CONFIRMATION = 'REPLACE_CORRUPT_ULTRA_STATE';
+const REBASELINE_CONFIRMATION = 'REBASELINE_CORRUPT_ULTRA_STATE';
+const USAGE = `ultra-tools system <verb> [options]
+
+VERBS:
+  doctor [--repair]
+  restore --backup <.ultra/backups/...db> --confirm ${RESTORE_CONFIRMATION}
+  rebaseline --project-name <name> [--scope <path>] --confirm ${REBASELINE_CONFIRMATION}
+`;
+
+class SystemCommandError extends Error {
+  constructor(code, message, exitCode = 1) {
+    super(message);
+    this.name = 'SystemCommandError';
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
 
 function emit(envelope) {
   process.stdout.write(`${JSON.stringify(envelope)}\n`);
 }
 
+function stamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function parseOptions(args, allowed) {
+  const options = { scope: [] };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+    const [flag, inline] = arg.startsWith('--') && arg.includes('=')
+      ? arg.split(/=(.*)/s, 2)
+      : [arg, null];
+    const name = flag.startsWith('--') ? flag.slice(2) : null;
+    if (!name || !allowed.has(name)) {
+      throw new SystemCommandError('VALIDATION_ERROR', `unknown system option: ${arg}`);
+    }
+    const value = inline === null ? args[index += 1] : inline;
+    if (value === undefined || String(value).length === 0 || String(value).startsWith('--')) {
+      throw new SystemCommandError('VALIDATION_ERROR', `${flag} requires a value`);
+    }
+    if (name === 'scope') options.scope.push(value);
+    else options[name.replaceAll('-', '_')] = value;
+  }
+  return options;
+}
+
+function inspectSqlite(file) {
+  if (!fs.existsSync(file)) return { exists: false, valid: false, corrupt: false };
+  let db;
+  try {
+    db = new Database(file, { readonly: true, fileMustExist: true });
+    const integrity = db.pragma('integrity_check', { simple: true });
+    const hasSchema = Boolean(db.prepare(
+      "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_version'",
+    ).get());
+    return { exists: true, valid: integrity === 'ok' && hasSchema, corrupt: false, integrity, hasSchema };
+  } catch (error) {
+    const corrupt = /not a database|database disk image is malformed|file is encrypted|malformed/i
+      .test(String(error.message || ''));
+    if (!corrupt) throw error;
+    return { exists: true, valid: false, corrupt: true, error: error.message };
+  } finally {
+    closeStateDb(db);
+  }
+}
+
+function inspectSqliteSnapshot(file) {
+  if (!fs.existsSync(file)) return { exists: false, valid: false, corrupt: false };
+  const snapshotDir = fs.mkdtempSync(path.join(path.dirname(file), '.state-inspect-'));
+  const snapshotPath = path.join(snapshotDir, 'state.db');
+  try {
+    for (const suffix of ['', '-wal', '-shm']) {
+      const source = `${file}${suffix}`;
+      if (fs.existsSync(source)) fs.copyFileSync(source, `${snapshotPath}${suffix}`);
+    }
+    return inspectSqlite(snapshotPath);
+  } finally {
+    fs.rmSync(snapshotDir, { recursive: true, force: true });
+  }
+}
+
+function ensureCorruptState(rootDir) {
+  const statePath = path.join(rootDir, '.ultra', 'state.db');
+  const state = inspectSqliteSnapshot(statePath);
+  if (!state.exists) throw new SystemCommandError('STATE_DB_MISSING', `.ultra/state.db not found under ${rootDir}`, 2);
+  if (!state.corrupt) {
+    throw new SystemCommandError(
+      'STATE_DB_NOT_CORRUPT',
+      'state.db is readable; use system doctor --repair for supported recovery instead of replacing authority',
+      2,
+    );
+  }
+  return statePath;
+}
+
+function managedBackup(rootDir, candidate) {
+  if (!candidate) throw new SystemCommandError('VALIDATION_ERROR', '--backup is required');
+  const backupRoot = path.join(rootDir, '.ultra', 'backups');
+  if (!fs.existsSync(backupRoot)) {
+    throw new SystemCommandError('BACKUP_NOT_FOUND', `managed backup directory does not exist: ${backupRoot}`);
+  }
+  const resolvedRoot = fs.realpathSync(backupRoot);
+  const requested = path.isAbsolute(candidate) ? candidate : path.resolve(rootDir, candidate);
+  let resolved;
+  try { resolved = fs.realpathSync(requested); }
+  catch {
+    throw new SystemCommandError('BACKUP_NOT_FOUND', `backup does not exist: ${requested}`);
+  }
+  if (!resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new SystemCommandError(
+      'BACKUP_OUTSIDE_MANAGED_ROOT',
+      `backup must be inside ${backupRoot}`,
+    );
+  }
+  if (!fs.statSync(resolved).isFile()) {
+    throw new SystemCommandError('BACKUP_NOT_FOUND', `backup is not a file: ${resolved}`);
+  }
+  const inspection = inspectSqlite(resolved);
+  if (!inspection.valid) {
+    throw new SystemCommandError('BACKUP_INVALID', `backup is not a verified Ultra SQLite database: ${resolved}`);
+  }
+  return resolved;
+}
+
+function createRecoveryDir(rootDir, prefix) {
+  const dir = path.join(rootDir, '.ultra', 'backups', `${prefix}-${stamp()}`);
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  fs.mkdirSync(dir, { recursive: false });
+  return dir;
+}
+
+function moveStateFiles(statePath, recoveryDir, moved = []) {
+  for (const suffix of ['', '-wal', '-shm']) {
+    const source = `${statePath}${suffix}`;
+    if (!fs.existsSync(source)) continue;
+    const target = path.join(recoveryDir, `state.db${suffix}`);
+    fs.renameSync(source, target);
+    moved.push({ source, target });
+  }
+  return moved;
+}
+
+function restoreMovedFiles(moved) {
+  const errors = [];
+  for (const item of moved) {
+    try {
+      if (fs.existsSync(item.source)) fs.rmSync(item.source, { force: true });
+    } catch (error) {
+      errors.push(`replacement cleanup failed for ${item.source}: ${error.message}`);
+    }
+  }
+  for (const item of moved) {
+    try {
+      if (fs.existsSync(item.target)) fs.renameSync(item.target, item.source);
+    } catch (error) {
+      errors.push(`evidence restore failed for ${item.source}: ${error.message}`);
+    }
+  }
+  return errors;
+}
+
+async function dispatchRestore(args) {
+  let options;
+  try { options = parseOptions(args, new Set(['backup', 'confirm'])); }
+  catch (error) { emit({ ok: false, error: { code: error.code, message: error.message } }); return error.exitCode || 1; }
+  if (options.help) { process.stdout.write(USAGE); return 0; }
+  if (options.confirm !== RESTORE_CONFIRMATION) {
+    emit({
+      ok: false,
+      error: {
+        code: 'CONFIRMATION_REQUIRED',
+        message: `restore requires --confirm ${RESTORE_CONFIRMATION}`,
+      },
+    });
+    return 1;
+  }
+  const rootDir = process.cwd();
+  let moved = [];
+  let activeState;
+  let staging;
+  try {
+    activeState = ensureCorruptState(rootDir);
+    const sourceBackup = managedBackup(rootDir, options.backup);
+    const recoveryDir = createRecoveryDir(rootDir, 'restore');
+    staging = path.join(rootDir, '.ultra', `.state.restore-${stamp()}.db`);
+    fs.copyFileSync(sourceBackup, staging, fs.constants.COPYFILE_EXCL);
+    moveStateFiles(activeState, recoveryDir, moved);
+    fs.renameSync(staging, activeState);
+    const initialized = initStateDb(activeState);
+    closeStateDb(initialized.db);
+    emit({
+      ok: true,
+      data: {
+        status: 'restored',
+        source_backup: sourceBackup,
+        recovery_backup_dir: recoveryDir,
+        quarantined_state_path: path.join(recoveryDir, 'state.db'),
+        schema_version: initialized.schema_version,
+        schema_migration_backup_path: initialized.backup_path || null,
+        next_action: 'Run ultra-tools system doctor, then ultra-init to inspect baseline readiness.',
+      },
+    });
+    return 0;
+  } catch (error) {
+    if (staging) {
+      try { fs.rmSync(staging, { force: true }); } catch { /* rollback continues */ }
+    }
+    const rollbackErrors = activeState ? restoreMovedFiles(moved) : [];
+    emit({
+      ok: false,
+      error: {
+        code: error instanceof SystemCommandError ? error.code : 'STATE_RESTORE_FAILED',
+        message: `${error.message}${rollbackErrors.length ? `; rollback errors: ${rollbackErrors.join('; ')}` : ''}`,
+      },
+    });
+    return error.exitCode || 2;
+  }
+}
+
+async function dispatchRebaseline(args) {
+  let options;
+  try { options = parseOptions(args, new Set(['project-name', 'scope', 'confirm'])); }
+  catch (error) { emit({ ok: false, error: { code: error.code, message: error.message } }); return error.exitCode || 1; }
+  if (options.help) { process.stdout.write(USAGE); return 0; }
+  if (options.confirm !== REBASELINE_CONFIRMATION) {
+    emit({
+      ok: false,
+      error: {
+        code: 'CONFIRMATION_REQUIRED',
+        message: `rebaseline requires --confirm ${REBASELINE_CONFIRMATION}`,
+      },
+    });
+    return 1;
+  }
+  if (!options.project_name) {
+    emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: '--project-name is required' } });
+    return 1;
+  }
+  const rootDir = process.cwd();
+  let moved = [];
+  let projectionMove = null;
+  let activeState;
+  try {
+    activeState = ensureCorruptState(rootDir);
+    const recoveryDir = createRecoveryDir(rootDir, 'rebaseline');
+    moveStateFiles(activeState, recoveryDir, moved);
+    const tasksDir = path.join(rootDir, '.ultra', 'tasks');
+    if (fs.existsSync(tasksDir)) {
+      const legacyTasksDir = path.join(recoveryDir, 'tasks');
+      projectionMove = { source: tasksDir, target: legacyTasksDir };
+      fs.renameSync(tasksDir, legacyTasksDir);
+    }
+    const initialized = initProject({
+      target_dir: rootDir,
+      project_name: options.project_name,
+      mode: 'brownfield',
+      scope: options.scope.length > 0 ? options.scope : undefined,
+      resume: true,
+    });
+    emit({
+      ok: true,
+      data: {
+        status: 'rebaseline_started',
+        recovery_backup_dir: recoveryDir,
+        quarantined_state_path: path.join(recoveryDir, 'state.db'),
+        legacy_projection_path: projectionMove
+          ? path.join(projectionMove.target, 'tasks.json')
+          : null,
+        baseline: initialized.baseline,
+        copied_files: initialized.copied_files,
+        next_action: 'Inspect the preserved evidence, record the brownfield baseline, and obtain owner approval before convergence.',
+      },
+    });
+    return 0;
+  } catch (error) {
+    const rollbackErrors = [];
+    if (moved.length > 0) {
+      const generatedState = activeState || path.join(rootDir, '.ultra', 'state.db');
+      for (const suffix of ['', '-wal', '-shm']) {
+        try { fs.rmSync(`${generatedState}${suffix}`, { force: true }); }
+        catch (rollbackError) { rollbackErrors.push(`generated state cleanup failed: ${rollbackError.message}`); }
+      }
+    }
+    if (projectionMove) {
+      try {
+        if (fs.existsSync(projectionMove.source)) {
+          fs.rmSync(projectionMove.source, { recursive: true, force: true });
+        }
+        if (fs.existsSync(projectionMove.target)) fs.renameSync(projectionMove.target, projectionMove.source);
+      } catch (rollbackError) {
+        rollbackErrors.push(`task projection restore failed: ${rollbackError.message}`);
+      }
+    }
+    rollbackErrors.push(...restoreMovedFiles(moved));
+    emit({
+      ok: false,
+      error: {
+        code: error.code || 'STATE_REBASELINE_FAILED',
+        message: `${error.message}${rollbackErrors.length ? `; rollback errors: ${rollbackErrors.join('; ')}` : ''}`,
+      },
+    });
+    return error.exitCode || 2;
+  }
+}
+
 async function dispatchDoctor(args) {
   const unknown = args.filter((arg) => !['--repair', '-h', '--help'].includes(arg));
   if (args.includes('-h') || args.includes('--help')) {
@@ -28,16 +335,33 @@ async function dispatchDoctor(args) {
     emit({ ok: false, error: { code: 'STATE_DB_MISSING', message: `.ultra/state.db not found under ${rootDir}` } });
     return 2;
   }
-  const db = openStateDb(dbPath);
+  let db;
   try {
+    const repair = args.includes('--repair');
+    const initialized = repair ? initStateDb(dbPath) : null;
+    db = initialized ? initialized.db : openStateDb(dbPath);
     const data = await doctor.runDoctor(db, { rootDir, repair: args.includes('--repair') });
+    if (initialized) {
+      data.schema_version = initialized.schema_version;
+      data.schema_migration_backup_path = initialized.backup_path || null;
+    }
     emit({ ok: true, data });
     return data.status === 'healthy' ? 0 : 2;
   } catch (error) {
-    emit({ ok: false, error: { code: error.code || 'STATE_DB_ERROR', message: error.message } });
+    const corrupt = /not a database|database disk image is malformed|file is encrypted or is not a database|malformed/i
+      .test(String(error.message || ''));
+    emit({
+      ok: false,
+      error: {
+        code: corrupt ? 'STATE_DB_CORRUPT' : (error.code || 'STATE_DB_ERROR'),
+        message: corrupt
+          ? `state.db is corrupt; after owner approval use system restore with a verified managed backup or system rebaseline to quarantine and rebuild authority: ${error.message}`
+          : error.message,
+      },
+    });
     return 2;
   } finally {
-    closeStateDb(db);
+    if (db) closeStateDb(db);
   }
 }
 
@@ -47,6 +371,8 @@ async function dispatch(args) {
     process.stdout.write(USAGE);
     return 0;
   }
+  if (verb === 'restore') return dispatchRestore(rest);
+  if (verb === 'rebaseline') return dispatchRebaseline(rest);
   if (verb !== 'doctor') {
     emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown system verb: ${verb}` } });
     return 1;
@@ -54,4 +380,12 @@ async function dispatch(args) {
   return dispatchDoctor(rest);
 }
 
-module.exports = { USAGE, dispatch, dispatchDoctor };
+module.exports = {
+  USAGE,
+  RESTORE_CONFIRMATION,
+  REBASELINE_CONFIRMATION,
+  dispatch,
+  dispatchDoctor,
+  dispatchRestore,
+  dispatchRebaseline,
+};