Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
64.3 KB
Raw Blame
/**
 * `gbrain apply-migrations` — migration runner CLI.
 *
 * Reads ~/.gbrain/migrations/completed.jsonl, diffs against the TS migration
 * registry, runs any pending orchestrators. Resumes `status: "partial"`
 * entries (stopgap bash script writes these). Idempotent: rerunning is
 * cheap when nothing is pending.
 *
 * Invoked from:
 *   - `gbrain upgrade` → runPostUpgrade() tail (Lane A-5)
 *   - `gbrain setup <harness>` on the brain it just created
 *   - explicit user / host-agent after registering new handlers (Lane C-1)
 */

import { VERSION } from '../version.ts';
import type { BrainEngine } from '../core/engine.ts';
import { gbrainPath, loadConfig } from '../core/config.ts';
import { LiveServeLockError, PgliteBusyError, peekLock } from '../core/pglite-lock.ts';
import {
  acquireMigrationOrchestrationLock,
  MigrationLeaseLostError,
  MIGRATIONS_RUNNING_EXIT_CODE,
  MigrationsRunningError,
  type MigrationOrchestrationLock,
} from '../core/migration-orchestration-lock.ts';
import { loadCompletedMigrations, appendCompletedMigration, type CompletedMigrationEntry } from '../core/preferences.ts';
import { migrations, compareVersions, type Migration, type OrchestratorOpts } from './migrations/index.ts';
import { setRunEngineSharing, withRunEngineSession } from './migrations/run-engine.ts';
import { migrationDeclinedError, readDeclinedMigrations, readHostWorkMigrations } from './migrations/opt-out.ts';
import {
  indexCompletedEntries,
  statusForVersion as ledgerStatusForVersion,
  freshInstallVersion,
  isFreshInstallStamp,
  forwardProgressPast,
  isPendingFreshInstall,
  hostWorkInspectArgv,
  hostWorkPendingForVersion,
  hostWorkOwedFix,
  hostWorkOwedForVersion,
  hostWorkOwedMessage,
  MAX_CONSECUTIVE_PARTIALS,
  wedgedLedgerHint,
  type OwedConflict,
} from '../core/migration-ledger.ts';
import { owedConflicts } from '../core/shared-skills/migration-host-work.ts';
import type { SharedMigrationReport } from '../core/shared-skills/migration.ts';
import { clearRepoPathWedge } from './migrations/v0_11_0-install.ts';
import { shellQuote, type Action, type Effect } from '../core/agent-output.ts';
import { writeJsonDocument } from '../core/cli-force-exit.ts';
import { consentGate } from '../core/consent-cli.ts';
import { opError, OperationError } from '../core/ops/contract.ts';
import { exitCliError, usageError, writeCliError } from '../cli/cli-error.ts';
import {
  checkSchemaAfterOrchestrators,
  connectAtSchemaVersion,
  connectForForcedSchema,
  redactDbError,
  reportDatabaseUnreachable,
  schemaAheadRefusal,
  schemaBehindAtPreflight,
  schemaPendingError,
  type SchemaPending,
} from './apply-migrations-schema.ts';
import { migrationStatementTimeoutMs, readMigrationTimeout, setMigrationStatementTimeoutMs, type MigrationTimeoutRecord } from '../core/migration-timeout.ts';

interface ApplyMigrationsArgs {
  list: boolean;
  dryRun: boolean;
  json: boolean;
  dbOnlyExport?: OrchestratorOpts['dbOnlyExport'];
  acceptReviewedInventory?: OrchestratorOpts['acceptReviewedInventory'];
  yes: boolean;
  nonInteractive: boolean;
  mode?: 'always' | 'pain_triggered' | 'off';
  specificMigration?: string;
  hostDir?: string;
  noAutopilotInstall: boolean;
  /** Bug 3 — explicit reset for a wedged migration. Writes a 'retry' marker. */
  forceRetry?: string;
  /**
   * v0.30.1 namespaced --force flags (codex T5):
   *   --force-orchestrator: write 'retry' markers for ALL wedged orchestrator migrations
   *   --force-schema:       reset schema-version drift (re-run runMigrations)
   *   --force-all:          both
   */
  forceOrchestrator?: boolean;
  forceSchema?: boolean;
  forceAll?: boolean;
  /** v0.30.1 (D6 / X3): bypass verify-hook drift detection on a single run. */
  skipVerify?: boolean;
  /** #4364: exit 1 when the DB pre-flight probe fails instead of proceeding filesystem-only. */
  requireDb: boolean;
  /** #7108: operator-only statement budget (minutes, 0 = none) for this run's schema migrations. */
  statementTimeoutMinutes?: number;
  help: boolean;
}

function parseArgs(args: string[]): ApplyMigrationsArgs {
  const has = (flag: string) => args.includes(flag);
  const val = (flag: string): string | undefined => {
    const i = args.indexOf(flag);
    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
  };
  const mode = val('--mode') as ApplyMigrationsArgs['mode'];
  const exporting = has('--export-db-only');
  if (exporting && !val('--content-root') || has('--backup-confirmed') && has('--acknowledge-no-backup')) {
    exitCliError(usageError('DB-only export requires --content-root and exactly one explicit backup choice for a non-dry run.',
      'Example: gbrain apply-migrations --migration <version> --export-db-only --content-root <path> --backup-confirmed --dry-run --json'), COMMAND);
  }
  const accepted: Record<string, string> = {};
  args.forEach((arg, i) => {
    if (arg !== '--accept-reviewed-inventory') return;
    const match = /^([^=\s]+)=([a-f0-9]{64})$/.exec(args[i + 1] ?? '');
    if (!match) exitCliError(usageError('--accept-reviewed-inventory takes <source-id>=<64-hex inventory digest>, copied from the migration\'s conflict message.',
      'Example: gbrain apply-migrations --migration 0.53.0 --accept-reviewed-inventory default=<digest> --yes'), COMMAND);
    accepted[match![1]] = match![2];
  });
  const budget = val('--statement-timeout');
  if (has('--statement-timeout') && !/^\d+$/.test(budget ?? '')) {
    exitCliError(usageError('--statement-timeout takes whole minutes (0 removes the limit) for this run\'s schema migrations.',
      'Example: gbrain apply-migrations --yes --statement-timeout 120'), COMMAND);
  }
  if (mode && !['always', 'pain_triggered', 'off'].includes(mode)) {
    exitCliError(usageError(`Invalid --mode "${mode}". Allowed: always, pain_triggered, off.`,
      'Example: gbrain apply-migrations --yes --mode pain_triggered'), COMMAND);
  }
  return {
    list: has('--list'),
    dryRun: has('--dry-run'),
    json: has('--json'),
    dbOnlyExport: exporting ? { root: val('--content-root')!, sourceId: val('--export-source') ?? 'default',
      confirmQuiesced: has('--confirm-quiesced'),
      backup: has('--backup-confirmed') ? 'operator_verified' : has('--acknowledge-no-backup') ? 'acknowledged_unprotected' : undefined } : undefined,
    ...(Object.keys(accepted).length ? { acceptReviewedInventory: accepted } : {}),
    yes: has('--yes'),
    nonInteractive: has('--non-interactive'),
    mode,
    specificMigration: val('--migration'),
    hostDir: val('--host-dir'),
    noAutopilotInstall: has('--no-autopilot-install') || process.env.GBRAIN_NO_AUTOPILOT_INSTALL === '1',
    forceRetry: val('--force-retry'),
    forceOrchestrator: has('--force-orchestrator'),
    forceSchema: has('--force-schema'),
    forceAll: has('--force-all') || has('--force'),
    skipVerify: has('--skip-verify'),
    requireDb: has('--require-db'),
    ...(budget !== undefined && has('--statement-timeout') ? { statementTimeoutMinutes: Number(budget) } : {}),
    help: has('--help') || has('-h'),
  };
}

function printHelp(): void {
  console.log(`gbrain apply-migrations — run pending migration orchestrators.

Usage:
  gbrain apply-migrations                Run all pending migrations interactively.
  gbrain apply-migrations --yes          Non-interactive; uses default mode (pain_triggered).
  gbrain apply-migrations --dry-run      Print the plan; take no action.
  gbrain apply-migrations --dry-run --json
                                        Include read-only content inventories and conflicts.
  gbrain apply-migrations --migration 0.53.0 --export-db-only --content-root <path>
    [--export-source <id>] --dry-run --json
                                        Preview a lossless host-side DB-only content export.
    --confirm-quiesced                   Attest old writers and skill servers are stopped.
    --backup-confirmed                   Attest an operational backup was verified by you.
    --acknowledge-no-backup               Explicitly proceed without a verified backup.
  gbrain apply-migrations --migration 0.53.0 --accept-reviewed-inventory <source>=<digest> --yes
                                        Accept a skill-pack change the user reviewed; the
                                        digest comes from the conflict message and stops
                                        matching if the files change again. Repeatable.
  gbrain apply-migrations --list [--json]
                                         Show applied + pending migrations.
                                         pending_fresh_install = setup work a
                                         brain created by gbrain init has not
                                         run yet (expected; apply with --yes).
                                         applied_pending_host_work = the
                                         checkpoint is recorded but host work
                                         (publication, client activation) is
                                         not done; inspect it with --migration
                                         <v> --dry-run --json, then --yes
                                         records it (doctor minions_migration).
                                         Unenrolled members and opted-out
                                         sources are not host work.
  gbrain apply-migrations --migration vX.Y.Z
                                         Force-run a specific migration by version.
  gbrain apply-migrations --force-retry vX.Y.Z
                                         Clear a wedged migration (3+ consecutive
                                         partials). Writes a 'retry' marker so the
                                         next run treats it as fresh.
  gbrain apply-migrations --force-orchestrator
                                         Reset every wedged orchestrator migration
                                         in one shot (writes 'retry' for each).
  gbrain apply-migrations --force-schema
                                         Reset schema-version drift; re-runs
                                         runMigrations from current config.version.
  gbrain apply-migrations --force        (alias --force-all) Apply both
                                         --force-orchestrator and --force-schema.
  gbrain apply-migrations --skip-verify  Bypass post-condition verify hooks on
                                         non-idempotent migrations (D6 escape hatch).

Flags:
  --require-db                           Exit 1 when the database is unreachable
                                         instead of continuing with the
                                         filesystem-only migration plan.
  --statement-timeout <minutes>          Operator escape hatch (#7108): the statement
                                         budget for this run's schema migrations
                                         (default 10; 0 removes it). Each one holds
                                         its table locks that long, so writes wait.
                                         Use it only when a migration times out with
                                         nothing blocking it (doctor schema_version).
  --mode <always|pain_triggered|off>     Set minion_mode without prompting.
  --host-dir <path>                      Include this directory in host-file walk
                                         (default scope: \$HOME/.claude + \$HOME/.openclaw).
  --no-autopilot-install                 Skip the Phase F autopilot install step.
                                         Also: GBRAIN_NO_AUTOPILOT_INSTALL=1.
  --non-interactive                      Never prompt; authorizes only the autopilot
                                         install (persistent_install), like --yes.
  --json                                 One JSON document on stdout (failures: the
                                         error envelope with code + suggestion).

Exit codes:
  0  Success (including "nothing to do").
  1  An orchestrator failed, the migration lease stopped matching this run
     (migration_lease_lost), or the run left the schema behind
     (migrations_pending: not_applied → apply them with --yes; still_behind or
     schema_unreadable → run gbrain doctor --json and report, not --yes again;
     wedged → a migration ended partial 3+ times in a row: ask the user, fix
     the cause, then --force-retry <version>).
     An unreachable Postgres stays 0 (GBRAIN_DB_ACCESS on stderr) unless --require-db.
  2  Invalid arguments.
  3  confirmation_required: a migration installs the autopilot service and the
     user has not approved it (--yes, --non-interactive or a preapproval).
  75 Another apply-migrations run holds the orchestration lock.
`);
}

interface CompletedIndex {
  byVersion: Map<string, CompletedMigrationEntry[]>;
  /** The version whose `gbrain init` created this brain (fresh-install stamps), or null. */
  freshVersion: string | null;
}

// Ledger status logic moved to src/core/migration-ledger.ts (shared with the
// get_health op's migrations block, TODOS:4063) — same semantics, same Bug 3
// "complete wins / trailing retry overrides / consecutive-partial cap" rules.
function indexCompleted(entries: CompletedMigrationEntry[]): CompletedIndex {
  return { byVersion: indexCompletedEntries(entries), freshVersion: freshInstallVersion(entries) };
}

function statusForVersion(
  version: string,
  idx: CompletedIndex,
): 'complete' | 'partial' | 'pending' | 'wedged' {
  return ledgerStatusForVersion(version, idx.byVersion);
}

interface Plan {
  applied: Migration[];
  /** #6796: applied migrations whose ledger row records host work and whose stored report still names some (a subset of applied). */
  applied_pending_host_work: Migration[];
  partial: Migration[];
  pending: Migration[];
  /** Never run on a brain gbrain init created at or after its version: expected setup work, not an interrupted upgrade. */
  pending_fresh_install: Migration[];
  skippedFuture: Migration[];
  wedged: Migration[];
  /** #6696 C5: wedged in the ledger, but a newer migration ran past it (doctor's forward-progress rule): history, not outstanding work. */
  wedged_superseded: Migration[];
  /** Wedged with host work still owed (its latest row records apply_migrations_pending): never superseded and never run by itself; a person resolves the conflict first. */
  wedged_host_work: Migration[];
  /** #6466: declined by the brain's config (`Migration.optOut`); never run, listed as `declined`. */
  declined: Migration[];
}

/**
 * Build the run plan.
 *
 * - applied:  has a `status: "complete"` entry for its version.
 * - partial:  has only `status: "partial"` entries (stopgap wrote one) →
 *             orchestrator runs to finish missing phases.
 * - pending:  has no entries at all and migration.version ≤ installed VERSION.
 * - pending_fresh_install: pending, on a brain `gbrain init` created at or
 *             after this version (fresh-install stamps). Runs like pending.
 * - skippedFuture: migration.version > installed VERSION (binary is older
 *                  than the migration; wait for a newer install).
 * - declined: the brain's config turns the migration off (#6466); not
 *             applied, partial or pending whatever the ledger says.
 *
 * Codex H9: we never compare against `current VERSION >` — that rule would
 * skip v0.11.0 when running v0.11.1. Compare against completed.jsonl.
 */
function buildPlan(idx: CompletedIndex, installed: string, filterVersion?: string, declined: ReadonlySet<string> = new Set(), hostWork: ReadonlySet<string> = new Set()): Plan {
  const plan: Plan = { applied: [], applied_pending_host_work: [], partial: [], pending: [], pending_fresh_install: [], skippedFuture: [], wedged: [], wedged_superseded: [], wedged_host_work: [], declined: [] };
  const ledger = [...idx.byVersion.values()].flat();
  for (const m of migrations) {
    if (filterVersion && m.version !== filterVersion) continue;
    if (compareVersions(m.version, installed) > 0) {
      plan.skippedFuture.push(m);
      continue;
    }
    if (declined.has(m.version)) { plan.declined.push(m); continue; }
    const status = statusForVersion(m.version, idx);
    if (status === 'complete') {
      plan.applied.push(m);
      if (hostWork.has(m.version) && hostWorkPendingForVersion(m.version, idx.byVersion)) plan.applied_pending_host_work.push(m);
    } else if (status === 'partial') plan.partial.push(m);
    else if (status === 'wedged' && hostWorkOwedForVersion(m.version, idx.byVersion)) plan.wedged_host_work.push(m);
    else if (status === 'wedged') (forwardProgressPast(m.version, ledger) === null ? plan.wedged : plan.wedged_superseded).push(m);
    else if (isPendingFreshInstall(m.version, idx.freshVersion)) plan.pending_fresh_install.push(m);
    else plan.pending.push(m);
  }
  return plan;
}

/**
 * #4364: pre-flight DB probe outcome. Surfaced on --list/--dry-run so an
 * unreachable database is distinguishable from a clean one — both used to
 * print the identical all-pending plan at exit 0.
 */
type DbProbeOutcome =
  | { status: 'connected'; schemaVer: number; latest: number }
  | { status: 'unreachable'; reason: string; access?: string }
  | { status: 'skipped'; reason: string };

function formatDbProbeLine(probe: DbProbeOutcome): string {
  if (probe.status === 'connected') {
    return `Database: connected, schema v${probe.schemaVer} (latest ${probe.latest})`;
  }
  if (probe.status === 'unreachable') {
    return `Database: UNREACHABLE (${probe.reason})`;
  }
  return `Database: not probed (${probe.reason})`;
}

const FINISH_SETUP_ARGV = ['gbrain', 'apply-migrations', '--yes', '--no-autopilot-install'];

function listRows(plan: Plan): Array<{ status: string; m: Migration }> {
  return [
    ...plan.applied.map(m => ({ status: plan.applied_pending_host_work.includes(m) ? 'applied_pending_host_work' : 'applied', m })),
    ...plan.partial.map(m => ({ status: 'partial', m })),
    ...[...plan.wedged, ...plan.wedged_host_work, ...plan.wedged_superseded].map(m => ({ status: 'wedged', m })),
    ...plan.pending.map(m => ({ status: 'pending', m })),
    ...plan.pending_fresh_install.map(m => ({ status: 'pending_fresh_install', m })),
    ...plan.declined.map(m => ({ status: 'declined', m })),
    ...plan.skippedFuture.map(m => ({ status: 'future', m })),
  ];
}

function printList(plan: Plan, installed: string, dbProbe: DbProbeOutcome): void {
  console.log(`Installed gbrain version: ${installed}`);
  console.log(`${formatDbProbeLine(dbProbe)}\n`);
  console.log('  Status                 Version   Headline');
  console.log('  ---------------------  --------  -----------------------------------------');
  const rows = listRows(plan);
  for (const r of rows) {
    const ver = r.m.version.padEnd(8);
    const status = r.status.padEnd(21);
    console.log(`  ${status}  ${ver}  ${r.m.featurePitch.headline}`);
  }
  if (rows.length === 0) console.log('  (no migrations registered)');
  console.log('');
  const needsWork = plan.pending.length + plan.partial.length;
  const setup = plan.pending_fresh_install.length;
  for (const m of plan.declined) console.log(`v${m.version} is declined by config (${m.optOut?.key} is false); turn it back on: gbrain config set ${m.optOut?.key} true`);
  for (const m of plan.wedged) console.log(`v${m.version} is wedged (${MAX_CONSECUTIVE_PARTIALS}+ consecutive partial runs). Read ${wedgedLedgerHint()}, fix the cause, then: ${shellQuote(forceRetryArgv(m.version))}`);
  if (plan.wedged_host_work.length) console.log(hostWorkOwedMessage(plan.wedged_host_work.map(m => m.version)));
  for (const m of plan.applied_pending_host_work) {
    console.log(`v${m.version} is applied_pending_host_work: its mechanical checkpoint is recorded, but host publication or client activation is not done. `
      + `Inspect each source's next step: ${shellQuote(hostWorkInspectArgv(m.version))}; once that work is done, \`gbrain apply-migrations --yes\` records it in the migration's report.`);
  }
  if (needsWork === 0 && setup === 0 && plan.wedged.length === 0 && plan.wedged_host_work.length === 0) {
    if (plan.applied_pending_host_work.length === 0) console.log('All migrations up to date.');
    return;
  }
  if (needsWork > 0) console.log(`${needsWork} migration(s) need action. Run \`gbrain apply-migrations --yes\` to apply.`);
  if (setup > 0) {
    console.log(`${setup} setup migration(s) are pending_fresh_install: this brain was created by gbrain init and has not run them yet. `
      + `This is expected setup work, not a failed upgrade. Finish setup: ${shellQuote(FINISH_SETUP_ARGV)}`);
  }
}

/** `--list --json` fields: one row per registered migration plus the command that completes outstanding work. */
function listJson(plan: Plan, idx: CompletedIndex, installed: string, dbProbe: DbProbeOutcome): Record<string, unknown> {
  const outstanding = plan.pending.length + plan.partial.length + plan.pending_fresh_install.length;
  return {
    installed,
    database: dbProbe,
    fresh_install_version: idx.freshVersion,
    migrations: listRows(plan).map(r => ({
      version: r.m.version,
      status: r.status,
      headline: r.m.featurePitch.headline,
      ...(r.status === 'applied' && (idx.byVersion.get(r.m.version) ?? []).some(isFreshInstallStamp) ? { fresh_install: true } : {}),
      ...(r.status === 'declined' && r.m.optOut ? { opt_out: { key: r.m.optOut.key } } : {}),
    })),
    needs_action: plan.pending.length + plan.partial.length,
    ...(plan.wedged.length ? { wedged: plan.wedged.map(m => ({ version: m.version, fix: { argv: forceRetryArgv(m.version), command: shellQuote(forceRetryArgv(m.version)) } })) } : {}),
    ...(plan.wedged_host_work.length ? { wedged_host_work: plan.wedged_host_work.map(m => ({ version: m.version,
      fix: { argv: hostWorkInspectArgv(m.version), command: shellQuote(hostWorkInspectArgv(m.version)) } })) } : {}),
    pending_fresh_install: plan.pending_fresh_install.length,
    ...(plan.applied_pending_host_work.length ? { applied_pending_host_work: plan.applied_pending_host_work.map(m => ({ version: m.version,
      fix: { argv: hostWorkInspectArgv(m.version), command: shellQuote(hostWorkInspectArgv(m.version)) } })) } : {}),
    ...(outstanding > 0 ? { next: { argv: FINISH_SETUP_ARGV, command: shellQuote(FINISH_SETUP_ARGV) } } : {}),
  };
}

function printDryRun(plan: Plan, installed: string, dbProbe: DbProbeOutcome): void {
  console.log(`Dry run — installed gbrain version: ${installed}`);
  console.log(formatDbProbeLine(dbProbe));
  console.log('');
  if (plan.applied.length) {
    console.log('Already applied:');
    for (const m of plan.applied) console.log(`  ✓ v${m.version} — ${m.featurePitch.headline}`);
    console.log('');
  }
  if (plan.partial.length) {
    console.log('Would RESUME (previously partial):');
    for (const m of plan.partial) console.log(`  ⟳ v${m.version} — ${m.featurePitch.headline}`);
    console.log('');
  }
  if (plan.pending.length) {
    console.log('Would APPLY:');
    for (const m of plan.pending) console.log(`  → v${m.version} — ${m.featurePitch.headline}`);
    console.log('');
  }
  if (plan.pending_fresh_install.length) {
    console.log('Would APPLY (pending_fresh_install — setup a brain created by gbrain init has not run yet; expected, not a failed upgrade):');
    for (const m of plan.pending_fresh_install) console.log(`  → v${m.version} — ${m.featurePitch.headline}`);
    console.log('');
  }
  if (plan.declined.length) {
    console.log('Declined by config (not run; turn one back on with gbrain config set <key> true):');
    for (const m of plan.declined) console.log(`  ⊘ v${m.version} — ${m.optOut?.key} is false`);
    console.log('');
  }
  if (plan.wedged_host_work.length) {
    console.log('Wedged with host work owed (not run; a person resolves each source\'s conflict first):');
    for (const m of plan.wedged_host_work) console.log(`  ✗ v${m.version} — inspect each source: ${shellQuote(hostWorkInspectArgv(m.version))}`);
    console.log('');
  }
  if (plan.skippedFuture.length) {
    console.log('Skipped (newer than installed binary):');
    for (const m of plan.skippedFuture) console.log(`  ⧗ v${m.version}`);
    console.log('');
  }
  if (plan.pending.length + plan.partial.length + plan.pending_fresh_install.length === 0) {
    console.log('Nothing to do.');
  } else {
    console.log('Re-run without --dry-run to apply. Use --yes to skip prompts.');
  }
}

/**
 * #1530: schema-drift pre-flight resolution. When the schema version is
 * behind, `--yes`/`--non-interactive` runs the schema migrations right there
 * (the engine is already connected); interactive runs warn and return true so
 * the caller exits non-zero instead of claiming "All migrations up to date".
 * All output goes to stderr (migrations never print to stdout).
 *
 * Returns true when the schema is STILL behind after this call.
 */
async function resolveSchemaBehind(opts: {
  schemaVer: number;
  latest: number;
  autoApply: boolean;
  run: () => Promise<{ applied: number; current: number }>;
}): Promise<boolean> {
  const { schemaVer, latest, autoApply, run } = opts;
  if (schemaVer >= latest) return false;
  if (autoApply) {
    console.error(`Schema version ${schemaVer} is behind latest ${latest}; running schema migrations...`);
    try {
      const result = await run();
      console.error(`Applied ${result.applied} schema migration(s); now at v${result.current}.`);
      return false;
    } catch (err) {
      console.error(`Schema migration failed: ${err instanceof Error ? err.message : String(err)}`);
      return true;
    }
  }
  console.warn(
    `\n⚠️  Schema version ${schemaVer} is behind latest ${latest}.\n` +
    `   Run \`gbrain apply-migrations --yes\` to apply now, or \`gbrain init --migrate-only\`.\n`,
  );
  return true;
}

function orchestratorOptsFrom(cli: ApplyMigrationsArgs, ownLeaseToken?: string): OrchestratorOpts {
  return {
    yes: cli.yes || cli.nonInteractive,
    mode: cli.mode,
    dryRun: cli.dryRun,
    hostDir: cli.hostDir,
    noAutopilotInstall: cli.noAutopilotInstall,
    dbOnlyExport: cli.dbOnlyExport && { ...cli.dbOnlyExport, ownLeaseToken },
    ...(cli.acceptReviewedInventory ? { acceptReviewedInventory: cli.acceptReviewedInventory } : {}),
  };
}

const COMMAND = 'apply-migrations';

/**
 * D2: what a run reports. `doc` is the `--json` success document (and the
 * legacy keys a failure envelope leads with); `failure` is the typed error a
 * non-zero exit renders (`Error [code]` / `Fix:` on stderr, the envelope
 * under `--json`).
 */
interface RunReport {
  doc: Record<string, unknown>;
  failure?: OperationError;
  /** #6696 C5: wedged migrations the run cannot clear itself; a run that otherwise succeeds fails `migrations_pending` reason `wedged`. */
  wedged?: readonly Migration[];
  /** Wedged with host work owed and no newer migration past it: fails like `wedged`, with the read-only inspect as its fix. */
  wedgedHostWork?: readonly Migration[];
  /** Every wedged migration with host work owed, past a newer migration or not: the run never says all migrations are up to date while one is listed. */
  hostWorkOwed?: readonly Migration[];
  /** The sources in conflict now, from the owed migration's read-only preview; null when it was not read. */
  owedConflicts?: OwedConflict[] | null;
}

function unknownMigrationError(version: string): OperationError {
  return usageError(`No migration registered with version "${version}".`,
    'Run `gbrain apply-migrations --list` to see registered versions.',
    { fix: { argv: ['gbrain', COMMAND, '--list'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Lists every registered migration and its status.' } });
}

/** The sources a wedged migration's read-only preview finds in conflict now; null when it has no preview or the preview fails. */
async function previewOwedConflicts(migration: Migration, cli: ApplyMigrationsArgs): Promise<OwedConflict[] | null> {
  if (!migration.preview) return null;
  try { return owedConflicts(await migration.preview({ ...orchestratorOptsFrom(cli), dryRun: true }) as SharedMigrationReport | null); }
  catch { return null; }
}

/** A named run of a wedged migration: it runs by name again only after its wedge is cleared; --list and --dry-run still inspect it. */
function wedgedByNameError(version: string, hostWorkOwed: boolean): OperationError {
  if (hostWorkOwed) {
    return usageError(`Migration v${version} is wedged on a source conflict (${MAX_CONSECUTIVE_PARTIALS}+ consecutive partial runs), so it does not run by name.`,
      `See each source's conflict and the step that settles it (read-only): ${shellQuote(hostWorkInspectArgv(version))}.`,
      { fix: hostWorkOwedFix([version]) });
  }
  return usageError(`Migration v${version} is wedged (${MAX_CONSECUTIVE_PARTIALS}+ consecutive partial runs), so it does not run by name until the wedge is cleared.`,
    `Read ${wedgedLedgerHint()} for the last failure and fix its cause. Then clear the wedge with ${shellQuote(forceRetryArgv(version))} and run this command again.`,
    { fix: wedgedMigrationFix([version]) });
}

/** The same invocation again once the underlying failure is fixed; any approval it needs is asked by the run itself. */
function rerunFix(args: readonly string[], why: string, yes = false) {
  // Approval flags are dropped: the rerun asks for any consent effect itself.
  const argv = ['gbrain', COMMAND, ...args.filter(a => a !== '--yes' && a !== '--non-interactive'), ...(yes ? ['--yes'] : [])];
  return { argv, consent: [] as Effect[], actor: 'agent' as const, requires_exclusive: true, why };
}

/**
 * Write the run's result and return the exit status. A non-zero status with
 * a typed failure renders it; the consent refusal (3) already wrote its
 * payload. Success under `--json` is the one document.
 */
function finishReport(cli: ApplyMigrationsArgs, report: RunReport, exitCode: number | undefined): number | undefined {
  if (exitCode === 3) return exitCode;
  if (exitCode !== undefined && exitCode !== 0) {
    const failure = report.failure ?? opError('migration_failed', `apply-migrations exited with status ${exitCode}.`,
      'Read the stderr lines above for the failing migration, fix it, then run `gbrain apply-migrations` again.');
    return writeCliError(failure, COMMAND, { json: cli.json, ...(cli.json ? { legacy: report.doc } : {}) });
  }
  if (cli.json) void writeJsonDocument(JSON.stringify(report.doc));
  return exitCode;
}

/**
 * Entry point. Does not call connectEngine — each phase inside an
 * orchestrator manages its own engine / subprocess lifecycle.
 */
export async function runApplyMigrations(args: string[]): Promise<void> {
  const { exitCode } = await applyMigrations(args);
  if (exitCode !== undefined) process.exit(exitCode);
}

/**
 * The run without the process exit, for in-process callers that report the
 * outcome themselves (`post-upgrade --json`). The result (or the failure
 * under --json) is already written; `failure` is the typed error behind a
 * non-zero status.
 */
export async function applyMigrations(args: string[]): Promise<{ exitCode: number | undefined; failure?: OperationError }> {
  const cli = parseArgs(args);
  if (cli.help) { printHelp(); return { exitCode: undefined }; }
  if (cli.statementTimeoutMinutes === undefined) return applyParsed(cli, args);
  // #7108: the operator's budget covers this run only, whichever way it returns.
  const prior = migrationStatementTimeoutMs();
  setMigrationStatementTimeoutMs(cli.statementTimeoutMinutes * 60_000);
  try {
    return await applyParsed(cli, args);
  } finally {
    setMigrationStatementTimeoutMs(prior);
  }
}

async function applyParsed(cli: ApplyMigrationsArgs, args: string[]): Promise<{ exitCode: number | undefined; failure?: OperationError }> {
  const installed = VERSION.replace(/^v/, '').trim() || '0.0.0';
  const report: RunReport = { doc: { status: 'ok', installed } };

  // First-install guard (an older release's postinstall calls us even on `bun add gbrain`
  // before the user has run `gbrain init`). No config = no brain = nothing
  // to migrate. Exit silently for --yes / --non-interactive so postinstall
  // stays quiet; mention the init step when invoked interactively.
  const config = loadConfig();
  if (!config) {
    if (cli.json) await writeJsonDocument(JSON.stringify({ status: 'unconfigured', previews: [], message: 'No brain configured; nothing to migrate.' }));
    else if (cli.list) console.log('No brain configured. Run `gbrain init` to set one up.');
    else if (cli.dryRun) console.log('No brain configured (run `gbrain init` first). Nothing to migrate.');
    return { exitCode: undefined };
  }

  if (cli.dryRun && (cli.forceRetry || cli.forceOrchestrator || cli.forceSchema || cli.forceAll)) {
    const would: string[] = [];
    if (cli.forceRetry) {
      if (!migrations.some(m => m.version === cli.forceRetry)) exitCliError(unknownMigrationError(cli.forceRetry), COMMAND, { json: cli.json });
      would.push(`write a 'retry' marker for v${cli.forceRetry}`);
      console.log(`[dry-run] Would write a 'retry' marker for v${cli.forceRetry}. No ledger or database changes made.`);
    } else {
      if (cli.forceOrchestrator || cli.forceAll) {
        would.push("write 'retry' markers for wedged orchestrator migrations");
        console.log("[dry-run] Would write 'retry' markers for wedged orchestrator migrations. No ledger changes made.");
      }
      if (cli.forceSchema || cli.forceAll) {
        would.push('run schema migrations from current config.version');
        console.log('[dry-run] Would run schema migrations from current config.version. Database not opened; no schema changes made.');
      }
    }
    if (cli.json) await writeJsonDocument(JSON.stringify({ status: 'dry_run', installed, would, changed: false }));
    return { exitCode: undefined };
  }

  // #5693: one runner orchestrates at a time. --list and --dry-run are
  // read-only and never take the lock.
  const held: { lock: MigrationOrchestrationLock | null } = { lock: null };
  const holdLock = async (): Promise<void> => {
    if (cli.list || cli.dryRun) return;
    if (held.lock) { await held.lock.assertHeld(); return; }
    held.lock = await acquireMigrationOrchestrationLock(config);
  };
  let exitCode: number | undefined;
  try {
    await holdLock();
    exitCode = await withRunEngineSession(() => runLockedMigrations(cli, installed, holdLock, () => held.lock, report, args));
  } catch (error) {
    if (error instanceof MigrationLeaseLostError) {
      console.error(`apply-migrations stopped: ${error.message}`);
      report.doc.status = 'lease_lost';
      report.doc.lease = error.details;
      report.failure = opError('migration_lease_lost', error.message,
        'Run `gbrain doctor --json` and report this to the user with the lease details; do not delete the lease row or rerun in a loop.',
        { why: 'The migration lease row still names this run, but its fenced refresh matched nothing, so mutual exclusion can no longer be proven (#6028).',
          fix: { consent: [], actor: 'agent', requires_exclusive: false, why: 'Tell the user the migration lease no longer matched its own fence and what doctor reports.',
            verify: { argv: ['gbrain', 'doctor', '--json'] } } });
      exitCode = 1;
    } else if (error instanceof MigrationsRunningError) {
      console.error(`apply-migrations refused: ${error.message}`);
      report.doc.status = 'refused';
      report.failure = opError('migrations_running', error.message,
        'Wait for the other apply-migrations run to finish, then run `gbrain apply-migrations` again (it resumes where that run stopped).');
      exitCode = MIGRATIONS_RUNNING_EXIT_CODE;
    } else {
      throw error;
    }
  } finally {
    await held.lock?.release();
  }
  return { exitCode: finishReport(cli, report, exitCode), ...(report.failure ? { failure: report.failure } : {}) };
}

/**
 * Everything that mutates the ledger or the database runs here, under the
 * orchestration lock. Returns the process exit status instead of exiting so
 * the caller releases the lock first.
 */
async function runLockedMigrations(
  cli: ReturnType<typeof parseArgs>,
  installed: string,
  holdLock: () => Promise<void>,
  heldLock: () => MigrationOrchestrationLock | null,
  report: RunReport,
  args: readonly string[],
): Promise<number | undefined> {
  const { doc } = report;
  const fail = (status: string, failure: OperationError): void => { doc.status = status; report.failure = failure; };
  const refusal: SchemaRefusal = {};
  const migrateSchema = (eng: BrainEngine, from: number) => migrateSchemaThroughInit(eng, from, refusal);
  // Bug 3 — --force-retry: write an explicit reset marker for a wedged
  // migration, then return. User re-runs `gbrain apply-migrations --yes`
  // to actually re-attempt.
  if (cli.forceRetry) {
    const target = migrations.find(m => m.version === cli.forceRetry);
    if (!target) {
      fail('invalid', unknownMigrationError(cli.forceRetry));
      return 2;
    }
    appendCompletedMigration({ version: cli.forceRetry, status: 'retry' });
    doc.retry_markers = [cli.forceRetry];
    console.log(`Wrote 'retry' marker for v${cli.forceRetry}. Run \`gbrain apply-migrations --yes\` to re-attempt.`);
    return;
  }

  // v0.30.1 (codex T5): --force-orchestrator OR --force-all writes a 'retry'
  // marker for EVERY wedged orchestrator migration in one shot. User re-runs
  // `gbrain apply-migrations --yes` to actually re-attempt.
  if (cli.forceOrchestrator || cli.forceAll) {
    const completed = loadCompletedMigrations();
    const idx = indexCompleted(completed);
    let resetCount = 0;
    const markers: string[] = [];
    doc.retry_markers = markers;
    for (const m of migrations) {
      const status = statusForVersion(m.version, idx);
      if (status === 'wedged') {
        appendCompletedMigration({ version: m.version, status: 'retry' });
        markers.push(m.version);
        console.log(`Wrote 'retry' marker for v${m.version} (${m.featurePitch.headline.slice(0, 60)})`);
        resetCount++;
      }
    }
    if (resetCount === 0) {
      console.log('No wedged orchestrator migrations found.');
    } else {
      console.log(`\nReset ${resetCount} wedged orchestrator migration(s). Run \`gbrain apply-migrations --yes\` to re-attempt.`);
    }
    if (!cli.forceAll) return; // --force-schema continues below if --force-all is set
  }

  // v0.30.1 (codex T5): --force-schema OR --force-all resets schema-version
  // drift by re-running runMigrations(). When the actual DDL state diverges
  // from config.version (the brain_config incident), this is the manual
  // recovery path.
  if (cli.forceSchema || cli.forceAll) {
    try {
      const cfg = loadConfig();
      if (!cfg) {
        console.error('No brain configured for --force-schema.');
        fail('failed', opError('no_brain', 'No brain configured for --force-schema.', 'Create a brain first: `gbrain init` (`gbrain init --help` lists the options).'));
        return 2;
      }
      const { engine: eng, version, behind } = await connectForForcedSchema(cfg);
      if (behind) { fail('refused', behind); return 1; }
      console.log('Running schema migrations from current config.version...');
      const result = await migrateSchema(eng, version);
      console.log(`Applied ${result.applied} schema migration(s); now at v${result.current}.`);
      doc.schema = result;
      await eng.disconnect();
    } catch (err) {
      console.error(`--force-schema failed: ${(err as Error).message}`);
      fail('failed', err instanceof OperationError && err.code === 'foreign_table' ? err : opError('migration_failed', `--force-schema failed: ${(err as Error).message}`,
        'Fix the database error above, then run `gbrain apply-migrations --force-schema` again.', { reason: 'schema_failed' }));
      return 1;
    }
    return; // --force-schema alone, or --force-all with both surfaces flushed
  }

  // Pre-flight: schema drift (#1530) and the DB probe (#4364); see preflightSchema.
  const { schemaBehind, dbProbe, schemaTimeout } = await preflightSchema(cli, migrateSchema);

  if (!cli.list && !cli.dryRun) await clearRepoPathWedge(loadCompletedMigrations());
  const completed = loadCompletedMigrations();
  const idx = indexCompleted(completed);
  await setRunEngineSharing(true);
  const declined = await readDeclinedMigrations(loadConfig()!);
  const hostWork = cli.list && [...idx.byVersion.keys()].some(v => hostWorkPendingForVersion(v, idx.byVersion))
    ? await readHostWorkMigrations(loadConfig()!) : new Set<string>();
  const plan = buildPlan(idx, installed, cli.specificMigration, declined, hostWork);

  doc.database = dbProbe;
  doc.plan = Object.fromEntries(Object.entries(plan).map(([state, entries]) => [state, entries.map((migration: Migration) => migration.version)]));
  report.wedged = plan.wedged;
  report.hostWorkOwed = plan.wedged_host_work;
  report.wedgedHostWork = plan.wedged_host_work.filter(m => forwardProgressPast(m.version, completed) === null);
  report.owedConflicts = plan.wedged_host_work.length && !cli.list ? await previewOwedConflicts(plan.wedged_host_work[0]!, cli) : null;
  reportWedgedMigrations(plan.wedged, plan.wedged_superseded, plan.wedged_host_work, completed, report.owedConflicts);

  const namedWedged = plan.wedged.length + plan.wedged_superseded.length + plan.wedged_host_work.length;
  const readOnlyWedged = cli.list || cli.dryRun ? namedWedged : 0;
  if (cli.specificMigration && plan.applied.length + plan.partial.length + plan.pending.length + plan.pending_fresh_install.length + plan.skippedFuture.length + plan.declined.length + readOnlyWedged === 0) {
    const error = namedWedged ? wedgedByNameError(cli.specificMigration, plan.wedged_host_work.length > 0) : unknownMigrationError(cli.specificMigration);
    console.error(`${error.message} ${error.suggestion}`);
    fail('invalid', error);
    return 2;
  }
  // #6466: an explicit run of a declined migration refuses (T1) instead of overriding brain-level config every machine shares.
  if (cli.specificMigration && plan.declined.length > 0 && !cli.list && !cli.dryRun) {
    fail('declined', migrationDeclinedError(plan.declined[0]!));
    return writeCliError(report.failure, COMMAND, { json: cli.json });
  }

  // #4364: --require-db turns an unreachable DB into a hard failure instead
  // of a filesystem-only plan that renders identically to a clean database.
  const listExit = cli.requireDb && dbProbe.status === 'unreachable' ? 1 : 0;
  if (listExit) fail('database_unreachable', requireDbError(dbProbe));
  if (cli.list || cli.dryRun) await setRunEngineSharing(false);
  if (cli.list && cli.json) { Object.assign(doc, listJson(plan, idx, installed, dbProbe)); doc.status = listExit ? doc.status : 'listed'; return listExit; }
  if (cli.list) { printList(plan, installed, dbProbe); return listExit; }
  if (cli.dryRun) {
    const previews: Array<{ version: string; preview?: unknown; error?: string }> = [];
    for (const migration of [...plan.applied, ...plan.partial, ...plan.pending, ...plan.pending_fresh_install, ...plan.wedged, ...plan.wedged_host_work, ...plan.wedged_superseded]) {
      if (!migration.preview) continue;
      try { previews.push({ version: migration.version, preview: await migration.preview(orchestratorOptsFrom(cli)) }); }
      catch (error) { previews.push({ version: migration.version, error: error instanceof Error ? error.message : 'Inventory unavailable.' }); }
    }
    doc.previews = previews;
    if (!listExit) doc.status = 'dry_run';
    if (!cli.json) {
      printDryRun(plan, installed, dbProbe);
      for (const preview of previews) console.log(JSON.stringify(preview));
    }
    const failedPreview = previews.find(preview => preview.error);
    if (!listExit && failedPreview) fail('preview_failed', opError('migration_failed', `The v${failedPreview.version} preview could not be computed: ${failedPreview.error}`,
      'Read the previews array for the failing inventory, fix it, then preview again with `gbrain apply-migrations --dry-run --json`.', { reason: 'preview_failed' }));
    return listExit || (previews.some(preview => preview.error) ? 1 : 0);
  }
  if (cli.requireDb && dbProbe.status === 'unreachable') {
    console.error(formatDbProbeLine(dbProbe));
    console.error('--require-db: database is unreachable; aborting before orchestrators run.');
    return 1;
  }
  if (dbProbe.status === 'unreachable') reportDatabaseUnreachable(dbProbe);

  // A Postgres schema without gbrain_cycle_locks had no lease yet; the
  // preflight above created the table, so take the lease before orchestrating.
  await holdLock();

  // #6089: an applied reconcile re-check is not pending work. With nothing
  // else pending, a schema the pre-flight left behind fails the run here; the
  // re-check runs on the next run, once the schema is current.
  const pendingWork = [...plan.partial, ...plan.pending, ...plan.pending_fresh_install];
  const authorized = cli.yes || cli.nonInteractive;
  if (schemaBehind && pendingWork.length === 0 && dbProbe.status === 'connected') {
    return failSchemaBehind(report, args, await schemaBehindAtPreflight(dbProbe.schemaVer, authorized, schemaTimeout), refusal.foreignTable);
  }
  const toRun: Migration[] = [...pendingWork, ...plan.applied.filter(migration => migration.reconcile)]
    .sort((left, right) => compareVersions(left.version, right.version));
  if (toRun.length === 0) return upToDateOrWedged(report);
  if (!schemaBehind && pendingWork.length === 0) {
    console.log(`${report.hostWorkOwed?.length ? othersUpToDate(report.hostWorkOwed) : 'All migrations up to date.'} This covers orchestrator checkpoints only; host publication and client activation are being rechecked.`);
  }

  // A4: a migration whose orchestrator performs a consent effect (v0.11.0's
  // autopilot service install) runs only once it is authorized: --yes, the
  // --non-interactive mapping (persistent_install only), a preapproval, or a
  // TTY prompt. Refused: nothing runs, exit 3 with the consent payload.
  const consent = migrationConsentRequest(cli, toRun, args);
  if (consent) await setRunEngineSharing(false);
  if (consent && !(await consentGate(consent, { json: cli.json }))) {
    doc.status = 'confirmation_required';
    return 3;
  }

  // A7: the orchestrators need a PGLite brain to themselves. With a live serve owning it
  // every phase fails and a partial attempt is recorded against the retry cap, so refuse
  // up front: the fatal seam prints the two-step plan (stop the owner, re-run this command).
  const owned = loadConfig();
  if (owned?.engine === 'pglite' && !owned.database_url) {
    const peek = peekLock(owned.database_path ?? gbrainPath('brain.pglite'));
    if (peek.held && peek.isServe && peek.pid !== undefined && peek.pid !== process.pid) {
      throw new LiveServeLockError(`GBrain's local database is already open through \`gbrain serve\` (MCP, PID ${peek.pid}); apply-migrations needs it to itself. Nothing was applied.`,
        { pid: peek.pid, transport: peek.http ? 'http' : 'stdio' });
    }
  }

  // Run each orchestrator in registry order. An orchestrator failure aborts
  // the rest of the chain; fixing the failure and re-running picks up where
  // we left off (per-phase idempotency markers + resume from "partial").
  //
  // Bug 3 — the RUNNER owns the ledger write now. Orchestrators return their
  // result; we persist it here with a canonical shape. If the write fails,
  // surface the error and DO NOT proceed to the next migration (a silent
  // ledger drop was the root cause of the original infinite-retry symptom).
  let failed = false;
  const results: Array<{ version: string; status: string }> = [];
  doc.results = results;
  for (const m of toRun) {
    // A lease lost while an earlier orchestrator ran stops the chain here.
    await holdLock();
    await setRunEngineSharing(m.sharesRunEngine === true);
    const recordCheckpoint = !m.reconcile || !plan.applied.includes(m);
    console.log(`\n=== Applying migration v${m.version}: ${m.featurePitch.headline} ===`);
    try {
      const result = await m.orchestrator(orchestratorOptsFrom(cli, heldLock()?.leaseToken));
      for (const p of result.phases) if (p.argv) console.log(`  ${p.name} — next step: ${shellQuote(p.argv)}`);
      if (result.status === 'failed' || result.phases.some(p => p.status === 'failed')) {
        console.error(result.status === 'failed'
          ? `Migration v${m.version} reported status=failed.`
          : `Migration v${m.version} has failed phases (reported status=${result.status}); recording as partial.`);
        // Surface each failed phase's detail — the ledger records it, but
        // the operator needs it on stderr to act (#921).
        for (const p of result.phases) {
          if (p.status === 'failed') {
            console.error(`  phase ${p.name}: ${p.detail ?? '(no detail)'}`);
          }
        }
        results.push({ version: m.version, status: 'failed' });
        const failedPhases = result.phases.filter(p => p.status === 'failed').map(p => `${p.name}: ${p.detail ?? '(no detail)'}`);
        fail('failed', opError('migration_failed',
          `Migration v${m.version} failed${failedPhases.length ? ` (${failedPhases.join('; ')})` : ''}; the chain stopped there.`,
          'Fix the failing phase named above, then run `gbrain apply-migrations` again; it resumes from this migration.',
          { reason: 'orchestrator_failed', fix: rerunFix(args, `Resumes the chain from v${m.version} once the failing phase is fixed.`) }));
        // Record the attempt as 'partial' (not 'complete') so the cap counts
        // it. Don't let a failed orchestrator look like it never ran.
        try {
          if (recordCheckpoint) appendCompletedMigration({
            version: m.version,
            status: 'partial',
            phases: result.phases,
            files_rewritten: result.files_rewritten,
            autopilot_installed: result.autopilot_installed,
            install_target: result.install_target,
            apply_migrations_pending: result.pending_host_work ? result.pending_host_work > 0 : undefined,
          });
        } catch (e) {
          console.error(`Also: could not persist failure record: ${e instanceof Error ? e.message : String(e)}`);
        }
        failed = true;
        break;
      }

      // Persist the terminal outcome. appendCompletedMigration no-ops when
      // the last entry for this version is already 'complete' (idempotency
      // guard), so repeated clean runs don't spam the ledger.
      try {
        if (recordCheckpoint) appendCompletedMigration({
          version: m.version,
          status: result.status, // 'complete' | 'partial'
          phases: result.phases,
          files_rewritten: result.files_rewritten,
          autopilot_installed: result.autopilot_installed,
          install_target: result.install_target,
          apply_migrations_pending: result.pending_host_work ? result.pending_host_work > 0 : undefined,
        });
      } catch (e) {
        const msg = e instanceof Error ? e.message : String(e);
        console.error(`Failed to persist ledger entry for v${m.version}: ${msg}. Stopping to prevent silent drift.`);
        fail('failed', opError('migration_failed', `Failed to persist the ledger entry for v${m.version}: ${msg}.`,
          'Check that ~/.gbrain/migrations is writable, then run `gbrain apply-migrations` again.', { reason: 'ledger_write_failed' }));
        failed = true;
        break;
      }

      results.push({ version: m.version, status: result.status });
      if (result.status === 'partial') {
        doc.status = 'partial';
        console.log(`Migration v${m.version} finished as PARTIAL. Run \`gbrain apply-migrations\` again after resolving any pending host-work items.`);
      } else if (m.reconcile && result.pending_host_work) {
        console.log(`Migration v${m.version} mechanical checks complete; host publication or client actions remain pending.`);
      } else {
        console.log(`Migration v${m.version} complete.`);
      }
    } catch (e) {
      const msg = e instanceof Error ? e.message : String(e);
      console.error(`Migration v${m.version} threw: ${msg}`);
      if (e instanceof PgliteBusyError) throw e;
      results.push({ version: m.version, status: 'failed' });
      fail('failed', opError('migration_failed', `Migration v${m.version} threw: ${msg}`,
        'Fix the error above, then run `gbrain apply-migrations` again; it resumes from this migration.',
        { reason: 'orchestrator_threw', fix: rerunFix(args, `Resumes the chain from v${m.version} once the error is fixed.`) }));
      // Same partial-on-throw treatment so the cap counts runaway failures.
      try {
        if (recordCheckpoint) appendCompletedMigration({ version: m.version, status: 'partial' });
      } catch { /* swallow ledger-write failure on throw path */ }
      failed = true;
      break;
    }
  }

  if (failed) return 1;
  await setRunEngineSharing(true);
  // #6089: an orchestrator may migrate the schema itself, so read it again.
  return failSchemaBehind(report, args, await checkSchemaAfterOrchestrators({
    cfg: loadConfig()!, authorized, preflightVersion: dbProbe.status === 'connected' ? dbProbe.schemaVer : null, apply: migrateSchema,
  }), refusal.foreignTable);
}

/** #6089: the run leaves the schema behind → `migrations_pending`, exit 1; undefined (success) when it does not. */
/** #9190: a foreign_table refusal replaces the generic still_behind error, so its fix reaches the caller. */
function failSchemaBehind(report: RunReport, args: readonly string[], pending: SchemaPending | null, foreignTable?: OperationError): number | undefined {
  if (!pending) return failWedged(report);
  report.doc.status = 'schema_behind';
  report.doc.schema_pending = pending;
  report.failure = pending.reason === 'still_behind' && foreignTable ? foreignTable
    : schemaPendingError(pending, rerunFix(args, 'Applies the pending schema migrations (no consent effect; it migrates the brain\'s own schema).', true));
  return 1;
}

interface SchemaRefusal { foreignTable?: OperationError }

/**
 * Schema work goes through initSchema(), lease or not: it takes the schema migration lock and replays the idempotent
 * schema blob before the pending migrations, so a blob-owned table that is missing is back first (#9191). A
 * `foreign_table` refusal (#9190) is kept for the run's failure.
 */
async function migrateSchemaThroughInit(eng: BrainEngine, from: number, refusal: SchemaRefusal): Promise<{ applied: number; current: number }> {
  try {
    await eng.initSchema();
  } catch (err) {
    if (err instanceof OperationError && err.code === 'foreign_table') refusal.foreignTable = err;
    throw err;
  }
  const current = parseInt(await eng.getConfig('version') || String(from), 10);
  const { MIGRATIONS } = await import('../core/migrate.ts');
  return { applied: MIGRATIONS.filter(m => m.version > from && m.version <= current).length, current };
}

/**
 * Pre-flight for runLockedMigrations: detect schema migrations (migrate.ts)
 * being behind and probe the database (moved out of runLockedMigrations to
 * keep it under the function-size limit; behaviour unchanged).
 */
async function preflightSchema(
  cli: ApplyMigrationsArgs,
  migrateSchema: (eng: BrainEngine, from: number) => Promise<{ applied: number; current: number }>,
): Promise<{ schemaBehind: boolean; dbProbe: DbProbeOutcome; schemaTimeout?: MigrationTimeoutRecord }> {
  let schemaBehind = false;
  let schemaTimeout: MigrationTimeoutRecord | undefined;
  let dbProbe: DbProbeOutcome = { status: 'skipped', reason: 'no probe attempted' };
  // Detect schema migrations (migrate.ts) being behind.
  // apply-migrations historically ran orchestrator migrations only; schema
  // migrations run via connectEngine() / initSchema(). Users expect this CLI
  // to handle everything (Issue 1 from v0.18.0 field report; #1530). With
  // --yes/--non-interactive we apply them here; otherwise we warn and make
  // sure the run does NOT report "All migrations up to date" with exit 0.
  const cfg = loadConfig();
  try {
    const { LATEST_VERSION } = await import('../core/migrate.ts');
    if (cfg) {
      // v0.36.x #1100: skip the pre-flight warning on PGLite. The probe
      // briefly holds the single-writer lock; if a downstream orchestrator
      // phase spawns `gbrain init --migrate-only` as a subprocess (the
      // legacy v0.11.0 phase A path), the child can race the parent's
      // lock release and hit a 30s timeout. The orchestrators handle
      // schema lifecycle internally on PGLite (phase A routes in-process).
      // #6089: PGLite's schema version is checked in-process after the
      // orchestrators released the datastore (checkSchemaAfterOrchestrators).
      const skipPreflight = cfg.engine === 'pglite';
      if (skipPreflight) {
        dbProbe = { status: 'skipped', reason: 'pglite manages schema in-process' };
      } else {
        const { engine: eng, version: schemaVer } = await connectAtSchemaVersion(cfg);
        dbProbe = { status: 'connected', schemaVer, latest: LATEST_VERSION };
        schemaBehind = await resolveSchemaBehind({
          schemaVer,
          latest: LATEST_VERSION,
          // --list and --dry-run are read-only surfaces: never mutate schema
          // even when combined with --yes/--non-interactive.
          autoApply: (cli.yes || cli.nonInteractive) && !cli.dryRun && !cli.list,
          run: () => migrateSchema(eng, schemaVer),
        });
        if (schemaBehind) schemaTimeout = (await readMigrationTimeout(eng, parseInt(await eng.getConfig('version') || String(schemaVer), 10))) ?? undefined;
        await eng.disconnect();
      }
    }
  } catch (err) {
    // Non-fatal by default: if DB is unreachable, orchestrator migrations can
    // still run their filesystem-only phases. #4364: keep the (redacted)
    // reason so --list/--dry-run say UNREACHABLE and --require-db fails hard —
    // connect errors are exactly what users paste into issues and CI logs.
    const { classifyPgAccessError } = await import('../core/pg-access-classify.ts');
    dbProbe = {
      status: 'unreachable',
      reason: await redactDbError(err),
      access: classifyPgAccessError(err, { url: cfg?.database_url ?? null }).reason,
    };
  }
  // #7776: an older binary runs no orchestrator (or its schema replay) on a database a newer gbrain migrated.
  const behind = cfg && !cli.list && !cli.dryRun ? await schemaAheadRefusal(cfg, dbProbe.status === 'connected' ? dbProbe.schemaVer : null) : null;
  if (behind) throw behind;
  return { schemaBehind, dbProbe, schemaTimeout };
}

/** #6696 C5: the clearing step for a wedged migration; it needs the user, since the cause behind the partial runs must be fixed first. */
function forceRetryArgv(version: string): string[] { return ['gbrain', COMMAND, '--force-retry', version]; }

/** #6696 C5: nothing left to run is up to date only when no migration is wedged. */
function upToDateOrWedged(report: RunReport): number {
  const wedged = failWedged(report);
  if (wedged !== undefined) return wedged;
  report.doc.status = 'up_to_date';
  const owed = report.hostWorkOwed ?? [];
  if (owed.length) report.doc.wedged_host_work = owed.map(m => m.version);
  console.log(owed.length ? othersUpToDate(owed) : 'All migrations up to date.');
  return 0;
}

/** Said instead of "All migrations up to date" while a wedged migration still owes host work (reported above; the exit status is unchanged). */
function othersUpToDate(owed: readonly Migration[]): string {
  return `Every other migration is up to date; ${owed.map(m => `v${m.version}`).join(', ')} still owes host work a person has to resolve (see above).`;
}

/** #6696 C5: a run that leaves a wedged migration fails `migrations_pending` (reason `wedged`, exit 1); undefined when none is wedged. */
function failWedged(report: RunReport): number | undefined {
  const wedged = report.wedged ?? [];
  const owed = report.wedgedHostWork ?? [];
  if (!wedged.length && owed.length) {
    report.doc.status = 'wedged';
    report.doc.wedged = owed.map(m => m.version);
    report.failure = opError('migrations_pending', hostWorkOwedMessage(owed.map(m => m.version), report.owedConflicts ?? null),
      'Run the read-only inspect in the fix and show the user each source\'s conflict and the step that settles it.',
      { reason: 'wedged', fix: hostWorkOwedFix(owed.map(m => m.version), report.owedConflicts ?? null) });
    return 1;
  }
  if (!wedged.length) return undefined;
  const versions = wedged.map(m => `v${m.version}`).join(', ');
  report.doc.status = 'wedged';
  report.doc.wedged = wedged.map(m => m.version);
  report.failure = opError('migrations_pending',
    `Migration ${versions} is wedged (${MAX_CONSECUTIVE_PARTIALS}+ consecutive partial runs with no completion), so the run did not complete every migration.`,
    `Read ${wedgedLedgerHint()} for the last failure, fix its cause, then clear it with \`${shellQuote(forceRetryArgv(wedged[0]!.version))}\` and run \`gbrain apply-migrations --yes\` again. Ask the user first.`,
    { reason: 'wedged', fix: wedgedMigrationFix(wedged.map(m => m.version)) });
  return 1;
}

/** The ask-the-user step that clears the first wedged migration; also the fix of connect's pending-migrations notice (src/cli/migrations-notice.ts). */
export function wedgedMigrationFix(wedged: readonly string[]): Action {
  const versions = wedged.map(v => `v${v}`).join(', ');
  return { ask_user: true, argv: forceRetryArgv(wedged[0]!), consent: [], actor: 'agent', requires_exclusive: true,
    why: `Writes a 'retry' marker so the next run re-attempts v${wedged[0]!}; without fixing the cause the run partials again.`,
    user_message: `gbrain migration ${versions} failed ${MAX_CONSECUTIVE_PARTIALS} or more times in a row. Fix the cause recorded in ${wedgedLedgerHint()}, then clear it with ${shellQuote(forceRetryArgv(wedged[0]!))} and run gbrain apply-migrations --yes. Clear it now?`,
    verify: { argv: ['gbrain', COMMAND, '--list', '--json'] } };
}

/** Bug 3 — surface wedged migrations as a loud, actionable error; the run continues (applied/partial/pending are still reported and run). */
function reportWedgedMigrations(wedged: readonly Migration[], superseded: readonly Migration[], owed: readonly Migration[], completed: readonly CompletedMigrationEntry[],
  conflicts: OwedConflict[] | null): void {
  if (owed.length) console.error(`\n${hostWorkOwedMessage(owed.map(m => m.version), conflicts)}`);
  for (const m of superseded) {
    console.error(`\nMigration v${m.version} has ${MAX_CONSECUTIVE_PARTIALS}+ consecutive partial runs, but v${forwardProgressPast(m.version, completed)} completed after it, `
      + 'so it is history, not outstanding work. Nothing to do.');
  }
  for (const m of wedged) {
    console.error(
      `\nMigration v${m.version} is WEDGED (${MAX_CONSECUTIVE_PARTIALS}+ consecutive partials with no completion). ` +
      `Check ${wedgedLedgerHint()} for the last failure reasons, fix the underlying issue, then run:\n` +
      `  gbrain apply-migrations --force-retry ${m.version}\n` +
      `Then run \`gbrain apply-migrations\` again (it asks for any approval the migration needs).`,
    );
  }
}

function requireDbError(dbProbe: DbProbeOutcome): OperationError {
  return opError('database_error', `${formatDbProbeLine(dbProbe)}; --require-db stops the run before any orchestrator runs.`,
    'Fix the database connection (run `gbrain db-repair` to diagnose it), then run apply-migrations again.',
    { fix: { argv: ['gbrain', 'db-repair', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Diagnoses the database access failure and names the repair.' } });
}

/**
 * The consent request for the effects `toRun`'s orchestrators perform, or
 * null when none apply (dry runs never reach here). `persistent_install` is
 * dropped when the install is skipped anyway (--no-autopilot-install, PGLite).
 */
function migrationConsentRequest(cli: ApplyMigrationsArgs, toRun: readonly Migration[], args: readonly string[]) {
  const installSkipped = cli.noAutopilotInstall || loadConfig()?.engine === 'pglite';
  const asking = toRun.filter(m => (m.effects ?? []).some(e => e !== 'persistent_install' || !installSkipped));
  const effects = [...new Set(asking.flatMap(m => (m.effects ?? []).filter(e => e !== 'persistent_install' || !installSkipped)))];
  if (effects.length === 0) return null;
  const versions = asking.map(m => `v${m.version}`).join(', ');
  return {
    command: COMMAND, effects, actor: 'agent' as const, args,
    what: `Apply migration ${versions}`,
    why: `Migration ${versions} installs the gbrain autopilot background service (launchd, systemd or cron) so brain maintenance keeps running on a schedule.`,
    risk: 'Adds a persistent background service on this machine. Remove it with `gbrain autopilot --uninstall`, or skip it now with --no-autopilot-install.',
    user_message: 'The gbrain upgrade wants to install the autopilot background service so brain maintenance runs on a schedule. Install it? (If not, migrations can still run without it.)',
    argv: ['gbrain', COMMAND, ...args.filter(a => a !== '--json')],
    preview_argv: ['gbrain', COMMAND, '--dry-run'],
  };
}

/** Exported for unit tests only. Do not use from production code. */
export const __testing = {
  parseArgs,
  buildPlan,
  indexCompleted,
  statusForVersion,
  resolveSchemaBehind,
  formatDbProbeLine,
};