Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `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,
};