Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain migrate` engine graduation (PGLite -> Postgres): the CLI over the
* orchestrator in src/core/persistence/engine-graduation.ts.
*
* Dispatched before connectEngine() (src/cli.ts routeEngineFreeSubcommands):
* the orchestrator owns both connections, so `--plan` and `--status` migrate
* neither schema, and the run holds the source's kernel lock itself.
*
* gbrain migrate --to postgres|supabase [--url <url> | --url - | --url-env <VAR>]
* (no --yes) the plan as a confirmation_required payload, exit 3
* --plan | --dry-run the read-only plan, exit 0
* --yes --expect <hash> the run; ends with the target doctor result
* gbrain migrate --status | --resume | --rollback-to-source (the run in the manifest)
*
* Exit codes: 0 graduated / plan shown; 3 confirmation_required; 1 refusals;
* 2 usage; 11 resumable drain stop; 75 graduation_in_progress; 130 SIGINT.
* `--json` prints one document on stdout; progress goes to stderr.
*/
import { cliRenderContext, shellQuote, type Effect } from '../core/agent-output.ts';
import { buildConsentRefusal, isConsentRefusal, printConsentRefusal, requireConsent, type ConsentRequest } from '../core/consent.ts';
import { loadConfigFileOnly, type GBrainConfig } from '../core/config.ts';
import { cliOptsToProgressOptions, getCliOptions } from '../core/cli-options.ts';
import { setCliExitVerdict, writeJsonDocument } from '../core/cli-force-exit.ts';
import { readStdinBounded } from '../core/interaction.ts';
import { OperationError, opError } from '../core/ops/contract.ts';
import { createProgress, type ProgressReporter } from '../core/progress.ts';
import type {
GraduationCommandOptions, GraduationPhase, GraduationPlan, GraduationProgressSink, GraduationReceipt,
GraduationRollbackResult, GraduationStatusDoc, GraduationTargetSpelling, TriggerBypass,
} from '../core/persistence/engine-graduation.types.ts';
import { DEFAULT_TARGET_URL_ENV, planArgv, resumeArgv, statusArgv } from '../core/persistence/graduation-errors.ts';
import { writeCliError } from '../cli/cli-error.ts';
export type GraduationMode = 'plan' | 'run' | 'status' | 'resume' | 'rollback';
export interface GraduationArgs {
mode: GraduationMode;
/** The spelling typed after --to (absent on run-scoped verbs without it). */
to?: GraduationTargetSpelling;
url?: string;
urlFromStdin: boolean;
urlEnv?: string;
drainTimeoutSec: number;
drainTimeoutGiven: boolean;
triggerBypass?: TriggerBypass;
batchSize?: number;
force: boolean;
yes: boolean;
expect?: string;
json: boolean;
}
export const DEFAULT_DRAIN_TIMEOUT_SEC = 60;
/** The orchestrator surface the CLI calls (a test seam; production imports engine-graduation.ts). */
export interface GraduationApi {
planGraduation(opts: GraduationCommandOptions): Promise<GraduationPlan>;
runGraduation(opts: GraduationCommandOptions): Promise<GraduationReceipt>;
graduationStatus(): Promise<GraduationStatusDoc>;
resumeGraduation(opts: GraduationCommandOptions): Promise<GraduationReceipt>;
rollbackGraduation(opts: GraduationCommandOptions): Promise<GraduationRollbackResult>;
}
export interface GraduationCliDeps {
api?: GraduationApi;
env?: NodeJS.ProcessEnv;
/** One stdout document / human text. */
out?: (text: string) => void;
/** Human status lines (stderr). */
err?: (text: string) => void;
progress?: ProgressReporter;
readStdin?: () => Promise<string | null>;
/** SIGINT wiring; tests pass their own controller. */
signal?: AbortSignal;
/** Error writer (default writeCliError); `legacy` keys join the --json envelope. */
writeError?: (e: unknown, opts: { json: boolean; legacy?: Record<string, unknown> }) => number;
}
export const GRADUATION_USAGE = [
'Usage: gbrain migrate --to postgres|supabase [--url <url> | --url - | --url-env <VAR>] [--plan | --dry-run] [--yes --expect <plan_hash>]',
' [--drain-timeout <seconds>] [--trigger-bypass replica|disable-trigger] [--batch-size <n>] [--force] [--json]',
' gbrain migrate --status [--json]',
' gbrain migrate --resume [--drain-timeout <seconds>] [--url-env <VAR>] [--json]',
' gbrain migrate --rollback-to-source [--yes --expect <hash>] [--json]',
].join('\n');
const MODE_FLAGS: ReadonlyArray<[string, GraduationMode]> = [
['--plan', 'plan'], ['--dry-run', 'plan'], ['--status', 'status'], ['--resume', 'resume'], ['--rollback-to-source', 'rollback'],
];
function usage(message: string, suggestion: string): OperationError {
return opError('invalid_params', message, suggestion, {
fix: { argv: ['gbrain', 'migrate', '--help'], consent: [], actor: 'agent', requires_exclusive: false, why: 'The help lists every graduation flag.' },
});
}
function flagValue(args: readonly string[], name: string): string | undefined {
for (let i = 0; i < args.length; i++) {
if (args[i] === name) {
const v = args[i + 1];
if (v === undefined || (v.startsWith('--') && v !== '-')) throw usage(`${name} needs a value.`, `Give ${name} its value right after it, as ${name} VALUE or ${name}=VALUE.`);
return v;
}
if (args[i]!.startsWith(`${name}=`)) return args[i]!.slice(name.length + 1);
}
return undefined;
}
function positiveInt(raw: string | undefined, name: string): number | undefined {
if (raw === undefined) return undefined;
if (!/^\d+$/.test(raw) || Number(raw) <= 0 || !Number.isSafeInteger(Number(raw))) throw usage(`${name} must be a positive whole number (got "${raw}").`, `Pass ${name} as a positive whole number, e.g. ${name} ${name === '--batch-size' ? 500 : 60}.`);
return Number(raw);
}
export function parseGraduationArgs(args: readonly string[]): GraduationArgs {
const modes = MODE_FLAGS.filter(([f]) => args.includes(f));
const distinct = [...new Set(modes.map(([, m]) => m))];
if (distinct.length > 1) throw usage(`${modes.map(([f]) => f).join(' and ')} cannot be combined; pick one.`,
'Run one mode per command: preview with --plan, then the run itself with --yes --expect PLAN_HASH; --status, --resume and --rollback-to-source each run alone.');
const mode: GraduationMode = distinct[0] ?? 'run';
const toRaw = flagValue(args, '--to');
if (toRaw !== undefined && toRaw !== 'postgres' && toRaw !== 'supabase') {
throw usage(`Engine graduation moves a PGLite brain to Postgres; --to ${toRaw} is not a graduation target.`,
toRaw === 'pglite'
? 'A Postgres -> PGLite move uses the legacy copier and has no plan, status, resume or rollback: run `gbrain migrate --to pglite` without them.'
: 'Use --to postgres (alias supabase).');
}
if ((mode === 'plan' || mode === 'run') && toRaw === undefined) throw usage('Name the target engine: --to postgres (alias supabase).',
`Preview first with gbrain migrate --to postgres --url-env ${DEFAULT_TARGET_URL_ENV} --plan.`);
const urlRaw = flagValue(args, '--url');
const urlEnv = flagValue(args, '--url-env');
if (urlRaw !== undefined && urlEnv !== undefined) throw usage('--url and --url-env cannot be combined; prefer --url-env so the URL never appears in a command line.',
`Keep --url-env (e.g. --url-env ${DEFAULT_TARGET_URL_ENV}) and drop --url.`);
if (mode === 'status' && (args.includes('--yes') || args.includes('--force'))) throw usage('--status is read-only; it takes no --yes or --force.', 'Run gbrain migrate --status (add --json for the machine form) without --yes or --force.');
const bypass = flagValue(args, '--trigger-bypass');
if (bypass !== undefined && bypass !== 'replica' && bypass !== 'disable-trigger') throw usage(`--trigger-bypass takes replica or disable-trigger (got "${bypass}").`,
'Pass --trigger-bypass replica or --trigger-bypass disable-trigger, or omit the flag.');
const drain = positiveInt(flagValue(args, '--drain-timeout'), '--drain-timeout');
return {
mode,
...(toRaw ? { to: toRaw } : {}),
...(urlRaw !== undefined && urlRaw !== '-' ? { url: urlRaw } : {}),
urlFromStdin: urlRaw === '-',
...(urlEnv !== undefined ? { urlEnv } : {}),
drainTimeoutSec: drain ?? DEFAULT_DRAIN_TIMEOUT_SEC,
drainTimeoutGiven: drain !== undefined,
...(bypass ? { triggerBypass: bypass === 'replica' ? 'session_replication_role' : 'disable_trigger' } : {}),
...(flagValue(args, '--batch-size') !== undefined ? { batchSize: positiveInt(flagValue(args, '--batch-size'), '--batch-size') } : {}),
force: args.includes('--force'),
yes: args.includes('--yes'),
...(flagValue(args, '--expect') !== undefined ? { expect: flagValue(args, '--expect') } : {}),
json: args.includes('--json'),
};
}
/** `migrate.graduation` (file plane): only an explicit false opts out. */
export function graduationOptedOut(cfg: GBrainConfig | null): boolean {
const v = (cfg as { migrate?: { graduation?: unknown } } | null)?.migrate?.graduation;
return v === false || v === 'false' || v === '0' || v === 'off' || v === 'no';
}
/**
* Whether this `gbrain migrate` invocation is graduation's. Run-scoped verbs
* and the plan always are; a bare `--to postgres|supabase` is when the
* durable (file) config is PGLite, graduation is not opted out, and the host
* is not Windows (history-free Windows brains keep the legacy copier).
*/
export function routesToGraduation(args: readonly string[], fileCfg: GBrainConfig | null, platform: NodeJS.Platform = process.platform): boolean {
if (args[0] === 'embeddings' || args.includes('--help') || args.includes('-h')) return false;
if (MODE_FLAGS.some(([f]) => args.includes(f))) return true;
const toIdx = args.indexOf('--to');
const to = toIdx >= 0 ? args[toIdx + 1] : args.find(a => a.startsWith('--to='))?.slice(5);
if (to !== 'postgres' && to !== 'supabase') return false;
if (!fileCfg || (fileCfg.engine ?? 'pglite') !== 'pglite' || fileCfg.database_url) return false;
if (graduationOptedOut(fileCfg)) return false;
return platform !== 'win32';
}
/** What leaves this computer and what stays (the confirmation, success output and guide name both). */
export const WHAT_MOVES: readonly string[] = [
'pages, facts, takes, versions, links and timeline', 'embeddings', 'transcripts and paid model caches',
'request history, withdrawals and attribution', 'access-token and OAuth rows (hashes only)',
];
export const WHAT_STAYS: readonly string[] = [
'file storage object bytes', 'git worktrees and their host bindings', 'the MCP endpoint and OAuth issuer URL',
'the retained PGLite copy (<path>.graduated-<run_id>), which still holds private memory and token hashes',
];
const CREDENTIALS_NOTE = 'Existing access tokens, OAuth clients and local writer credentials stay valid on Postgres.';
const MCP_RESTART_NOTE = 'A gbrain serve handed the brain over during the move: restart your MCP client (or its gbrain server entry) so it reconnects to Postgres.';
function spellingOf(a: GraduationArgs): { to: GraduationTargetSpelling; urlEnv: string } {
return { to: a.to ?? 'postgres', urlEnv: a.urlEnv ?? DEFAULT_TARGET_URL_ENV };
}
/** The escape hatches that enter the plan hash, echoed into every emitted command. */
function hatchArgs(a: GraduationArgs): string[] {
return [
...(a.drainTimeoutGiven ? ['--drain-timeout', String(a.drainTimeoutSec)] : []),
...(a.triggerBypass ? ['--trigger-bypass', a.triggerBypass === 'session_replication_role' ? 'replica' : 'disable-trigger'] : []),
...(a.batchSize ? ['--batch-size', String(a.batchSize)] : []),
...(a.force ? ['--force'] : []),
];
}
function progressSink(p: ProgressReporter): { sink: GraduationProgressSink; done: () => void } {
let phase: ProgressReporter | null = null;
let table: ProgressReporter | null = null;
const closeTable = () => { table?.finish(); table = null; };
const closePhase = () => { closeTable(); phase?.finish(); phase = null; };
return {
sink: {
phase(name: GraduationPhase, total?: number) { closePhase(); phase = p.child(`migrate.graduation.${name}`, total); phase.start(`migrate.graduation.${name}`, total); },
table(relation: string, rows: number) { closeTable(); table = (phase ?? p).child(`table.${relation}`, rows); table.start(`table.${relation}`, rows); },
batch(_relation: string, rows: number) { table?.tick(rows); },
},
done: closePhase,
};
}
function displayHost(plan: GraduationPlan): string {
return plan.routes.main || `${plan.target.host}:${plan.target.port}/${plan.target.database}`;
}
function planLines(plan: GraduationPlan, next: string): string {
const carry = plan.tables.filter(t => t.class === 'carry' || t.class === 'rebind');
const rows = carry.reduce((n, t) => n + t.rows, 0);
const other = (c: string) => plan.tables.filter(t => t.class === c).map(t => t.relation);
const lines = [
`Move this PGLite brain to Postgres at ${displayHost(plan)}`,
` Source: ${plan.source.dataDir} (brain ${plan.source.brainId})${plan.sourceMeasured === 'at_run_start' ? ' — counts measured at run start (a live serve holds it)' : ''}`,
` Carry: ${carry.length} tables, ${rows} rows (keys preserved)`,
...(other('rebuild').length ? [` Rebuild: ${other('rebuild').join(', ')}`] : []),
...(other('discard').length ? [` Discard: ${other('discard').join(', ')}`] : []),
` Triggers: ${plan.triggerBypass ?? 'not probed'}`,
` Estimate: ${Math.ceil(plan.estimateSeconds.total)}s (copy ${Math.ceil(plan.estimateSeconds.copy)}s, verify ${Math.ceil(plan.estimateSeconds.verify)}s, doctor ${Math.ceil(plan.estimateSeconds.doctor)}s)`,
` Moves: ${WHAT_MOVES.join('; ')}`,
` Stays: ${WHAT_STAYS.join('; ')}`,
];
for (const b of plan.blockers) lines.push(` Blocker: ${b.kind} ${b.id}: ${b.detail}${b.argv?.length ? ` — ${shellQuote([...b.argv])}` : ''}`);
lines.push(` plan_hash ${plan.planHash}`, `Next: ${next}`);
return `${lines.join('\n')}\n`;
}
function consentRequest(a: GraduationArgs, plan: GraduationPlan, args: readonly string[]): ConsentRequest {
const s = spellingOf(a);
const host = displayHost(plan);
const people = plan.blockers.filter(b => b.needsUser);
const before = people.length ? ` Before it can run: ${people.map(b => b.detail).join(' ')}` : '';
const effects: Effect[] = ['egress', 'destructive'];
return {
command: 'migrate', effects, actor: 'agent',
what: 'Moving this brain to Postgres',
why: `The brain's database (${WHAT_MOVES.join('; ')}) is copied to ${host}, verified table by table, and only then made authoritative; the PGLite data dir is renamed aside and a tombstone takes its place.`,
risk: `Data leaves this computer for ${host}. Until a rollback, the PGLite copy is read-only history; rolling back after the move drops what changed on Postgres.`,
user_message: `Move this brain to Postgres at ${host}? That copies ${WHAT_MOVES.join(', ')}. Staying on this computer: ${WHAT_STAYS.join(', ')}.${before}`,
argv: ['gbrain', 'migrate', '--to', s.to, '--url-env', s.urlEnv, ...hatchArgs(a)],
preview_argv: planArgv(s, hatchArgs(a)),
plan_hash: plan.planHash,
args,
};
}
function orchestratorOptions(a: GraduationArgs, url: string | undefined, extra: Partial<GraduationCommandOptions>): GraduationCommandOptions {
return {
to: a.to ?? 'postgres',
...(url !== undefined ? { url } : {}),
...(a.urlEnv !== undefined ? { urlEnv: a.urlEnv } : {}),
drainTimeoutMs: a.drainTimeoutSec * 1000,
...(a.triggerBypass ? { triggerBypass: a.triggerBypass } : {}),
...(a.batchSize ? { batchSize: a.batchSize } : {}),
force: a.force,
yes: a.yes,
...(a.expect ? { expectPlanHash: a.expect } : {}),
...extra,
};
}
function successDoc(receipt: GraduationReceipt) {
return {
schema_version: 1 as const,
status: 'graduated' as const,
state: 'graduated' as const,
run_id: receipt.runId,
target: receipt.targetDisplayUrl ?? null,
retained_path: receipt.retainedPath ?? null,
doctor: receipt.doctor ?? null,
receipt,
credentials: CREDENTIALS_NOTE,
next_steps: [{ argv: ['gbrain', 'mcp', 'expose'], command: 'gbrain mcp expose', why: 'Share this brain with agents on other machines (multi-machine use).' }],
...(receipt.serveHandoff ? { mcp_client_restart: MCP_RESTART_NOTE } : {}),
};
}
function successLines(receipt: GraduationReceipt): string {
const rows = receipt.tables.reduce((n, t) => n + t.rows, 0);
const failing = receipt.doctor?.target ?? [];
const seconds = Object.values(receipt.timings).reduce((n, v) => n + v, 0) / 1000;
return [
`Graduated to Postgres${receipt.targetDisplayUrl ? ` at ${receipt.targetDisplayUrl}` : ''} (run ${receipt.runId}${seconds ? `, ${seconds.toFixed(0)}s` : ''}).`,
` Copied ${receipt.tables.length} tables, ${rows} rows; verify passed; replay probe: ${receipt.replay.status}.`,
` Target doctor: ${failing.length ? `failing checks: ${failing.join(', ')}` : 'no failing checks'}.`,
...(receipt.retainedPath ? [` Retained PGLite copy: ${receipt.retainedPath} (still holds private memory and token hashes; deleting it is your call; gbrain doctor reports it).`] : []),
` ${CREDENTIALS_NOTE}`,
' Next: share this brain with other machines: gbrain mcp expose',
...(receipt.serveHandoff ? [` ${MCP_RESTART_NOTE}`] : []),
].join('\n') + '\n';
}
function statusLines(doc: GraduationStatusDoc): string {
if (doc.state === 'none') return 'No engine graduation on record.\n';
const done = doc.tables.filter(t => t.state === 'copied' || t.state === 'verified').length;
return [
`Engine graduation ${doc.runId}: ${doc.state}${doc.liveRun ? ` (running, PID ${doc.liveRun.pid})` : ''}`,
...(doc.source ? [` Source: ${doc.source.dataDir} (brain ${doc.source.brainId})`] : []),
...(doc.target ? [` Target: ${doc.target.displayUrl} (row ${doc.target.row ?? 'absent'}${doc.target.reachable ? '' : ', unreachable'})`] : []),
...(doc.tables.length ? [` Tables: ${done}/${doc.tables.length} copied`] : []),
...(doc.splitBrain ?? []).map(p => ` Split brain: ${p.path} (brain ${p.brainId ?? 'unknown'}, ${p.rows} rows, newest write ${p.newestWriteAt ?? 'unknown'})`),
...(doc.nextArgv ? [`Next: ${shellQuote([...doc.nextArgv])}`] : []),
].join('\n') + '\n';
}
async function resolveUrl(a: GraduationArgs, deps: GraduationCliDeps): Promise<string | undefined> {
const env = deps.env ?? process.env;
if (a.urlEnv !== undefined && !env[a.urlEnv]) {
throw usage(`${a.urlEnv} is not set; --url-env names the environment variable that holds the target URL.`,
`Export the Postgres connection string as ${a.urlEnv} in this shell, then run the same command again.`);
}
if (!a.urlFromStdin) return a.url;
const text = deps.readStdin ? await deps.readStdin() : await (async () => {
const r = await readStdinBounded({ maxBytes: 64 * 1024 });
return r.kind === 'data' ? r.text : null;
})();
const url = text?.trim();
if (!url) throw usage('--url - reads the target URL from stdin, and stdin was empty.', `Pipe the URL in, or export it and use --url-env ${DEFAULT_TARGET_URL_ENV}.`);
return url;
}
/** Run one graduation invocation; returns the exit code (output already written). */
export async function runMigrateGraduation(args: readonly string[], deps: GraduationCliDeps = {}): Promise<number> {
const json = args.includes('--json');
const out = deps.out ?? ((t: string) => { void writeJsonDocument(t.replace(/\n$/, ''), s => { process.stdout.write(`${s}\n`); }); });
const err = deps.err ?? ((t: string) => { process.stderr.write(t); });
const emit = (doc: unknown, human: string) => { if (json) out(`${JSON.stringify(doc, null, 2)}\n`); else out(human); };
const controller = new AbortController();
const onSigint = () => {
if (controller.signal.aborted) return;
err('Interrupt received: stopping at the next batch boundary (the move stays resumable).\n');
controller.abort();
};
const signal = deps.signal ?? controller.signal;
if (!deps.signal) process.on('SIGINT', onSigint);
const progress = deps.progress ?? createProgress(cliOptsToProgressOptions(getCliOptions()));
const { sink, done } = progressSink(progress);
try {
const a = parseGraduationArgs(args);
if ((a.mode === 'plan' || a.mode === 'run') && graduationOptedOut(loadConfigFileOnly())) {
throw usage('Engine graduation is turned off on this machine (migrate.graduation = false), so there is no plan to show.',
'Turn it back on with `gbrain config unset migrate.graduation`, or run the legacy copier with `gbrain migrate --to postgres --url <url>` (it refuses brains with write history).');
}
const api = deps.api ?? await import('../core/persistence/engine-graduation.ts');
if (a.mode === 'status') {
const doc = await api.graduationStatus();
emit(doc, statusLines(doc));
return 0;
}
const url = await resolveUrl(a, deps);
const opts = orchestratorOptions(a, url, { progress: sink, signal });
if (a.mode === 'plan') {
const plan = await api.planGraduation(opts);
const next = shellQuote(['gbrain', 'migrate', '--to', spellingOf(a).to, '--url-env', spellingOf(a).urlEnv, ...hatchArgs(a), '--yes', '--expect', plan.planHash]);
emit({ schema_version: 1, status: 'plan', plan, what_moves: WHAT_MOVES, what_stays: WHAT_STAYS, next: { command: next } }, planLines(plan, next));
return 0;
}
if (a.mode === 'run' && !(a.yes && a.expect)) {
const plan = await api.planGraduation(opts);
const req = consentRequest(a, plan, args);
try {
await requireConsent(req, { interactive: false, preapprovals: {} });
} catch (e) {
if (!isConsentRefusal(e)) throw e;
Object.assign(e.consent, { plan, blockers: plan.blockers, what_moves: WHAT_MOVES, what_stays: WHAT_STAYS });
if (!json) err(planLines(plan, e.consent.fix.command ?? ''));
return printConsentRefusal(e, { json });
}
throw buildConsentRefusal(req, cliRenderContext());
}
if (a.mode === 'rollback') {
const result = await api.rollbackGraduation(opts);
emit({ schema_version: 1, status: result.state, restored_path: result.restoredPath, dropped: result.dropped },
`Rolled back: ${result.state === 'abandoned' ? 'the Postgres copy was abandoned; the PGLite brain never stopped being authoritative' : `the PGLite brain at ${result.restoredPath} is authoritative again`}.${result.dropped.length ? ` Dropped operational rows: ${result.dropped.map(d => `${d.relation} (${d.rows})`).join(', ')}.` : ''}\n`);
return 0;
}
const receipt = a.mode === 'resume' ? await api.resumeGraduation(opts) : await api.runGraduation(opts);
done();
if (receipt.state === 'rolled_back') {
emit({ schema_version: 1, status: 'rolled_back', state: 'rolled_back', run_id: receipt.runId, receipt },
`Rolled back (run ${receipt.runId}): the interrupted rollback finished and the PGLite brain is authoritative again.\n`);
return 0;
}
emit(successDoc(receipt), successLines(receipt));
return 0;
} catch (e) {
done();
return writeGraduationError(e, signal.aborted, json, deps.writeError ?? ((err, o) => writeCliError(err, 'migrate', o)));
} finally {
if (!deps.signal) process.removeListener('SIGINT', onSigint);
}
}
/** Render a graduation failure; applies the per-reason exit overrides (SIGINT 130, blocked drain 1). */
function writeGraduationError(e: unknown, aborted: boolean, json: boolean,
write: (e: unknown, opts: { json: boolean; legacy?: Record<string, unknown> }) => number): number {
if (aborted && !(e instanceof OperationError && e.code === 'interrupted')) {
const err = opError('interrupted', 'The move stopped at a batch boundary after an interrupt; it is resumable.',
'Ask the user whether to continue; `gbrain migrate --resume` picks up where it stopped.',
{ why: 'SIGINT stops the copy between batches and records the checkpoint, so nothing is half-written.',
fix: { argv: resumeArgv(), consent: [], actor: 'agent', requires_exclusive: true, verify: { argv: statusArgv() },
why: 'Continues from the recorded checkpoint.', user_message: 'The move to Postgres was paused. Should I continue it?' } });
return write(err, { json, ...(json ? { legacy: { resume_command: resumeArgv() } } : {}) });
}
if (e instanceof OperationError && e.code === 'graduation_rollback_writes_lost' && e.reason === 'user_data') {
// A confirmable loss asks the user (fix.next ask_user, like confirmation_required): exit 3. A final refusal stays 1.
write(e, { json });
return 3;
}
if (e instanceof OperationError && e.code === 'graduation_drain_timeout') {
const code = write(e, { json, ...(json ? { legacy: { resume_command: e.fix?.argv ?? resumeArgv() } } : {}) });
return e.reason === 'blocked' ? 1 : code;
}
return write(e, { json });
}
/** Pre-connect route from src/cli.ts: true when graduation handled this invocation. */
export async function tryRunMigrateGraduation(args: string[]): Promise<boolean> {
if (!routesToGraduation(args, loadConfigFileOnly())) return false;
setCliExitVerdict(await runMigrateGraduation(args));
return true;
}