Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
32.5 KB
Raw Blame
import { existsSync } from 'fs';
import { dirname, join, relative, resolve, sep } from 'path';
import type { BrainEngine } from '../core/engine.ts';
import { hasUnresolvedDbOnlyDeclaration, loadStorageConfig, validateStorageConfig, getStorageTier, isDbOnly } from '../core/storage-config.ts';
import type { StorageConfig, StorageTier } from '../core/storage-config.ts';
import { walkBrainRepo, type DiskFileEntry } from '../core/disk-walk.ts';
import { getDefaultSourcePath, isResolverUserError, resolveSourceForRepoPath } from '../core/source-resolver.ts';
import { resolveRestoreTarget, restoreFilePath, RestoreTargetError } from '../core/restore-target.ts';
import { shellQuote } from '../core/shell-quote.ts';
import { scannerSlugRootMode } from '../core/write-through.ts';
import type { SlugRootMode } from '../core/sync-anchor.ts';
import { nativeFileTarget } from '../core/persistence/native-file-target.ts';
import { opError, OperationError, type OperationContext } from '../core/ops/contract.ts';
import { readFix } from '../core/ops/op-fix.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { PENDING_WRITE_EXIT_CODE } from '../core/exit-codes.ts';

/**
 * Distinct nominal types for the two tier-keyed numeric maps. Both shapes
 * are `Record<StorageTier, number>` structurally — but they carry
 * semantically different units (page COUNT vs disk BYTES). Distinct types
 * make accidental swaps a compile-time error rather than a silent display
 * bug. Issue #11 of the eng review.
 */
export type PageCountsByTier = Record<StorageTier, number> & { __brand?: 'page-counts' };
export type DiskUsageByTier = Record<StorageTier, number> & { __brand?: 'disk-bytes' };

/**
 * Pure-data result of a storage-status query. No side effects, no I/O
 * beyond the engine call and one filesystem walk. Consumed by both the
 * JSON formatter and the human formatter; kept narrow so it's a stable
 * MCP/scripting contract (D14: storage_status is read-only MCP-exposed).
 */
export interface StorageStatusResult {
  config: StorageConfig | null;
  repoPath: string | null;
  /**
   * The source `gbrain export --restore-only` restores for this repo; the
   * counts cover only its pages. Null when no restore target was resolved.
   */
  restoreSource: string | null;
  /** Why the restore target was refused; null when it was not. */
  restoreRefusal: string | null;
  totalPages: number;
  pagesByTier: PageCountsByTier;
  missingFiles: Array<{ slug: string; expectedPath: string }>;
  diskUsageByTier: DiskUsageByTier;
  warnings: string[];
}

// ── Dispatcher ────────────────────────────────────────────

// #3686: real usage, reachable via `gbrain storage --help` (the generic
// one-line CLI_ONLY stub used to shadow this surface entirely).
const STORAGE_HELP = `gbrain storage — storage tiers of the brain repo, and the storage shelf

USAGE
  gbrain storage [status] [--repo <path>] [--json]
  gbrain storage init [--dir <path>] [--push-remote <url>] [--dry-run | --expect <plan_hash>] [--json]
  gbrain storage adopt [--source <id>] [--from-prefix <prefix>] [--drop-field <dotted.name>]...
                       [--apply --expect <plan_hash> | --finalize [--expect <plan_hash>]] [--json]
  gbrain storage export --jsonl [--out <file>]
  gbrain storage import --jsonl <file> [--apply --expect <plan_hash>] [--json]

SUBCOMMANDS
  status            (default) Report page counts and disk usage per storage
                    tier, list DB pages whose repo file is missing, and
                    validate the storage config.
  init              Create the storage shelf: the source that holds one card
                    per item archived to object storage (B2, Supabase Storage,
                    S3). A repo-less brain gets a database-only source (the
                    first storage-register also creates it). A brain with a
                    Git checkout gets a hosted git-canonical repository under
                    --dir, which needs managed persistence; preview first and
                    apply the printed command after the user agrees.
  adopt             Move interim records (type stored-object pages under
                    --from-prefix, default storage-manifest/, in --source,
                    default default; each with a json block under ## Record)
                    onto the shelf. Preview by default; --apply --expect
                    registers each card (origin adopt) and tags the original
                    storage-manifest-adopted, deleting nothing. Fields a card
                    refuses are left out only when named with --drop-field;
                    a credential-shaped value always refuses. --finalize
                    previews soft-deleting the adopted originals (72 h
                    restore window); with --expect it deletes them, only when
                    every card matches its original.
  export            Write every card as one JSON line, sorted by id, to --out
                    (a new file) or stdout.
  import            Preview a JSONL export line by line (create, identical,
                    conflict, invalid); --apply --expect registers the missing
                    cards (origin import) and never overwrites a differing one.

THE STORAGE SHELF (separate commands)
  gbrain storage-find "<phrase>"     Find a card; closest cards when none match
  gbrain storage-get <id>            One card: copies, restore form, revision
  gbrain storage-list                Cards, filtered by --store / --status
  gbrain storage-register --card <json>        Register a verified archive (local only)
  gbrain storage-update <id> --expected-revision <rev> [--patch <json>] [--restored-to <path>]

OPTIONS
  --repo <path>     Brain repo to walk (default: resolved from the storage
                    config / default source path)
  --json            Machine-readable output
  --help, -h        Show this help
`;

export async function runStorage(engine: BrainEngine, args: string[]): Promise<void> {
  // Help first — before the engine argument is touched, so `--help` works
  // with no brain configured (dispatched engine-free from cli.ts).
  if (args.includes('--help') || args.includes('-h')) {
    console.log(STORAGE_HELP);
    return;
  }
  const subcommand = args[0];
  if (!subcommand || subcommand === 'status') {
    await runStorageStatus(engine, args.slice(1));
    return;
  }
  if (subcommand === 'init') {
    await runStorageInit(engine, args.slice(1));
    return;
  }
  if (subcommand === 'adopt') {
    await runStorageAdopt(engine, args.slice(1));
    return;
  }
  if (subcommand === 'export' || subcommand === 'import') {
    await runStorageJsonl(engine, subcommand, args.slice(1));
    return;
  }
  if (['find', 'get', 'list', 'register', 'update'].includes(subcommand)) {
    console.error(`The storage manifest verbs are their own commands: run gbrain storage-${subcommand} (see gbrain storage-${subcommand} --help).`);
    process.exit(1);
  }
  console.error(`Unknown storage subcommand: ${subcommand}`);
  console.error('Available subcommands: status, init, adopt, export, import');
  process.exit(1);
}

async function runStorageStatus(engine: BrainEngine, args: string[]): Promise<void> {
  warnIfPGLite(engine);

  // Resolution chain (D5, Issue #3): explicit --repo → typed accessor → null.
  // No cwd fallback. The original silent footgun is dead. The repo and source
  // come from export's restore-only rule, so the printed restore command
  // restores the files listed as missing; a refused rule keeps the chain.
  const repoIdx = args.indexOf('--repo');
  const explicitRepo = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : undefined;
  let repoPath: string | null;
  let restore: StorageRestoreTarget;
  try {
    const target = await resolveRestoreTarget(engine, undefined, explicitRepo);
    // Export matches an archived owner on the exact path only; a repo inside
    // an archived source's tree (dotfile or longest registered local_path)
    // stays a refusal here, as status always refused it. An active source
    // registered at the repo's exact path owns it outright: skip the check,
    // whose prefix match does not prefer active sources over archived ones.
    const [activeOwner] = await engine.executeRaw<{ id: string }>(
      'SELECT id FROM sources WHERE archived IS NOT TRUE AND local_path = $1 LIMIT 1', [resolve(target.repo)]);
    if (!activeOwner) {
      try {
        await resolveSourceForRepoPath(engine, target.repo);
      } catch (e) {
        if (!isResolverUserError(e)) throw e;
        throw new RestoreTargetError((e as Error).message);
      }
    }
    repoPath = target.repo;
    restore = { source: target.source };
  } catch (e) {
    if (!(e instanceof RestoreTargetError)) throw e;
    repoPath = explicitRepo ?? (await getDefaultSourcePath(engine));
    restore = { refusal: e.message };
  }

  const result = await getStorageStatus(engine, repoPath, restore);

  if (args.includes('--json')) {
    console.log(formatStorageStatusJson(result));
    return;
  }
  console.log(formatStorageStatusHuman(result));
}

/**
 * D4: storage tiering on PGLite is a partial feature. The "DB" the pages
 * live in IS the local file gbrain uses for everything else, so "db_only"
 * has no real offload effect. The .gitignore management still helps
 * (keeps bulk content out of git history), so we warn but proceed.
 *
 * Once-per-process via a module-local flag — sub-commands invoked from a
 * single CLI run share the same warning.
 */
let _pgliteWarned = false;
function warnIfPGLite(engine: BrainEngine): void {
  if (_pgliteWarned) return;
  if (engine.kind !== 'pglite') return;
  _pgliteWarned = true;
  console.warn(
    `Note: storage tiering has limited effect on PGLite — pages live in your ` +
      `local database file regardless of tier. The .gitignore management still ` +
      `keeps bulk content out of git history. To get full tiering, migrate to ` +
      `Postgres with \`gbrain migrate --to postgres --plan\`.`,
  );
}

/** Reset for tests. */
export function __resetPGLiteWarn(): void {
  _pgliteWarned = false;
}

// ── Pure data ─────────────────────────────────────────────

/**
 * The repo's path inside its enclosing git checkout, as a `dir/` prefix
 * (empty when the repo is the checkout root or in none). A recorded
 * source_path starting with it is re-anchored by resolveSourceLocalFilePath,
 * so the repo walk cannot answer for it.
 */
function gitScopePrefix(repoPath: string): string {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- repoPath is the local operator's --repo arg, a registered source path or the default source path on the trusted `gbrain storage status` CLI (never MCP/remote); this only absolutizes it
  const repo = resolve(repoPath);
  for (let cursor = repo; ; cursor = dirname(cursor)) {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- read-only existence probe walking up from that operator-supplied repo path
    if (existsSync(join(cursor, '.git'))) {
      const scope = relative(cursor, repo).split(sep).filter(Boolean).join('/');
      return scope ? scope + '/' : '';
    }
    if (dirname(cursor) === cursor) return '';
  }
}

/** The restore-only source for the repo, or why it was refused. */
export type StorageRestoreTarget = { source: string } | { refusal: string };

/**
 * The source whose pages count when no restore source was resolved: the one
 * owning repoPath (dotfile, then longest registered local_path), else none
 * (every source counts). After a refused restore target, an owner the
 * resolver rejects (an archived source) counts every source too: the refusal
 * already tells the user why no restore command fits.
 */
async function repoOwner(
  engine: BrainEngine,
  repoPath: string,
  restore: StorageRestoreTarget | undefined,
): Promise<string | null> {
  try {
    return (await resolveSourceForRepoPath(engine, repoPath))?.source_id ?? null;
  } catch (e) {
    if (restore && 'refusal' in restore && isResolverUserError(e)) return null;
    throw e;
  }
}

/**
 * Compute the storage status against the given engine + brain repo path.
 *
 * Side-effect-free apart from the engine.listPages call and one recursive
 * filesystem walk. Pure for testability — formatters are tested separately.
 *
 * Returns null `config` when no gbrain.yml is present at repoPath. In that
 * case pagesByTier is all zeros for db_tracked/db_only and totals roll up
 * into unspecified.
 *
 * `restore` with a source counts only that source's pages; without one, the
 * pages of the source that owns repoPath are counted.
 */
export async function getStorageStatus(
  engine: BrainEngine,
  repoPath: string | null,
  restore?: StorageRestoreTarget,
): Promise<StorageStatusResult> {
  const config = repoPath ? loadStorageConfig(repoPath) : null;
  const warnings = config ? validateStorageConfig(config) : [];
  if (config?.ignored_db_only) warnings.push(`gbrain.yml lists the deprecated supabase_only next to canonical keys, which ignores it: ${config.ignored_db_only.join(', ')}. Move those directories under db_only and remove supabase_only. Until then sync keeps every page under them whose file is gone (#8007).`);
  if (repoPath && hasUnresolvedDbOnlyDeclaration(repoPath, config)) warnings.push('gbrain.yml declares storage.db_only but no directory resolved from it (a flow list split over lines, or the key outside storage:); list the directories in block style or as one line, db_only: [a/, b/]. Until then sync keeps every page whose file is gone (#8007).');

  const pagesByTier: PageCountsByTier = { db_tracked: 0, db_only: 0, unspecified: 0 };
  const diskUsageByTier: DiskUsageByTier = { db_tracked: 0, db_only: 0, unspecified: 0 };
  const missingFiles: Array<{ slug: string; expectedPath: string }> = [];

  // Single recursive walk of the brain repo (Issue #14). Replaces per-page
  // existsSync+statSync — was ~400K syscalls on 200K-page brains, now ~one
  // per directory + one stat per .md file, plus O(1) lookups below.
  const fileMap: Map<string, DiskFileEntry> = repoPath ? walkBrainRepo(repoPath) : new Map();

  const restoreSource = restore && 'source' in restore ? restore.source : null;
  const sourceId = restoreSource ?? (repoPath ? await repoOwner(engine, repoPath, restore) : null);
  const pages = await engine.listPages({
    limit: 1_000_000,
    ...(sourceId ? { sourceId } : {}),
  });

  // Pages export would refuse the whole restore on, grouped per reason (with
  // the lowest slug named) so a symlinked db_only dir yields one warning,
  // not one line per page.
  const refusedPages = new Map<string, { first: string; count: number }>();
  const scopePrefix = repoPath ? gitScopePrefix(repoPath) : '';
  const slugRootModes = new Map<string, SlugRootMode>();
  for (const page of pages) {
    const tier = config ? getStorageTier(page.slug, config) : 'unspecified';
    pagesByTier[tier]++;
    if (!repoPath) continue;
    const entry = fileMap.get(page.slug);
    if (entry) diskUsageByTier[tier] += entry.size;
    // Missing means what `export --restore-only` restores: any page under a
    // db_only dir (a db_tracked parent dir does not exempt it) whose recorded
    // source_path, else <slug>.md, is absent, checked the way export checks.
    if (!config || !isDbOnly(page.slug, config)) continue;
    const sourcePath = page.source_path ?? null;
    // Fast path, no per-page syscall: the walk saw the exact file export
    // checks as a regular file under real (non-symlink) directories, so
    // export's check finds it too. A recorded path that export would
    // re-anchor (it starts with the repo's path inside its git checkout)
    // takes the full check.
    const walkedKey = sourcePath === null ? page.slug
      : sourcePath.endsWith('.md') && !(scopePrefix && sourcePath.startsWith(scopePrefix)) ? sourcePath.slice(0, -3) : null;
    if (walkedKey !== null && fileMap.has(walkedKey)) continue;
    let expectedPath: string;
    let present: boolean;
    try {
      if (!slugRootModes.has(page.source_id)) slugRootModes.set(page.source_id, await scannerSlugRootMode(engine, page.source_id, repoPath));
      expectedPath = restoreFilePath(repoPath, page.slug, sourcePath, sourcePath ? Buffer.byteLength(sourcePath) : 0, slugRootModes.get(page.source_id)!);
      present = existsSync(nativeFileTarget(repoPath, expectedPath));
    } catch (e) {
      // Export refuses the whole restore on this page (unsafe recorded path,
      // symlinked or ambiguous file target); report that refusal.
      if (!(e instanceof RestoreTargetError) && !(e instanceof OperationError)) throw e;
      const group = refusedPages.get(e.message);
      if (!group) refusedPages.set(e.message, { first: page.slug, count: 1 });
      else {
        group.count++;
        if (page.slug < group.first) group.first = page.slug;
      }
      continue;
    }
    if (!present) missingFiles.push({ slug: page.slug, expectedPath });
  }

  // Ordered by each group's lowest slug, so warnings and the printed refusal
  // are the same run to run whatever order the pages were listed in.
  const refusals = [...refusedPages].sort(([, a], [, b]) => (a.first < b.first ? -1 : a.first > b.first ? 1 : 0));
  for (const [reason, { first, count }] of refusals) {
    warnings.push(count === 1 ? `${first}: ${reason}` : `${first} and ${count - 1} more page(s): ${reason}`);
  }

  return {
    config,
    repoPath,
    restoreSource,
    restoreRefusal: restore && 'refusal' in restore ? restore.refusal : (refusals[0]?.[0] ?? null),
    totalPages: pages.length,
    pagesByTier,
    missingFiles,
    diskUsageByTier,
    warnings,
  };
}

// ── JSON formatter ────────────────────────────────────────

/**
 * Serialize StorageStatusResult to a stable JSON contract. Indented for
 * human readability; agents/orchestrators can parse with a standard
 * JSON.parse. Schema is the StorageStatusResult interface above.
 */
export function formatStorageStatusJson(result: StorageStatusResult): string {
  return JSON.stringify(result, null, 2);
}

// ── Human formatter ───────────────────────────────────────

/**
 * Render StorageStatusResult to ASCII text suitable for terminal output.
 * D10 lock: ASCII separators only — universally portable. No unicode
 * box-drawing.
 */
export function formatStorageStatusHuman(result: StorageStatusResult): string {
  const lines: string[] = [];
  lines.push('Storage Status');
  lines.push('==============');
  lines.push('');

  if (!result.config) {
    lines.push('No gbrain.yml configuration found.');
    if (result.repoPath) lines.push(`Checked: ${result.repoPath}/gbrain.yml`);
    lines.push('');
    lines.push('All pages are stored in git by default.');
    lines.push(`Total pages: ${result.totalPages}`);
    return lines.join('\n');
  }

  lines.push(`Repository: ${result.repoPath}`);
  lines.push(`Total pages: ${result.totalPages}`);
  lines.push('');
  lines.push('Storage Tiers:');
  lines.push('-------------');
  lines.push(`DB tracked:     ${result.pagesByTier.db_tracked.toLocaleString()} pages`);
  lines.push(`DB only:        ${result.pagesByTier.db_only.toLocaleString()} pages`);
  lines.push(`Unspecified:    ${result.pagesByTier.unspecified.toLocaleString()} pages`);

  if (result.diskUsageByTier.db_tracked > 0 || result.diskUsageByTier.db_only > 0) {
    lines.push('');
    lines.push('Disk Usage:');
    lines.push('-----------');
    if (result.diskUsageByTier.db_tracked > 0) {
      lines.push(`DB tracked:     ${formatBytes(result.diskUsageByTier.db_tracked)}`);
    }
    if (result.diskUsageByTier.db_only > 0) {
      lines.push(`DB only:        ${formatBytes(result.diskUsageByTier.db_only)}`);
    }
    if (result.diskUsageByTier.unspecified > 0) {
      lines.push(`Unspecified:    ${formatBytes(result.diskUsageByTier.unspecified)}`);
    }
  }

  if (result.missingFiles.length === 0 && result.restoreRefusal) {
    lines.push('');
    lines.push(`Cannot suggest a restore command: ${result.restoreRefusal}`);
  }

  if (result.missingFiles.length > 0) {
    lines.push('');
    lines.push('Missing Files (need restore):');
    lines.push('-----------------------------');
    for (const missing of result.missingFiles.slice(0, 10)) {
      lines.push(`  ${missing.slug}`);
    }
    if (result.missingFiles.length > 10) {
      lines.push(`  ... and ${result.missingFiles.length - 10} more`);
    }
    lines.push('');
    if (result.restoreRefusal) {
      lines.push(`Cannot suggest a restore command: ${result.restoreRefusal}`);
    } else {
      const source = result.restoreSource ? ` --source ${result.restoreSource}` : '';
      // Shell-quoted: the line is meant to be pasted, and a repo path may hold
      // quotes, `$(...)` or backticks.
      lines.push(`Use: gbrain export --restore-only${source} --repo ${shellQuote(result.repoPath ?? '')}`);
    }
  }

  if (result.warnings.length > 0) {
    lines.push('');
    lines.push('Warnings:');
    lines.push('---------');
    for (const warning of result.warnings) lines.push(`  ! ${warning}`);
  }

  lines.push('');
  lines.push('Configuration:');
  lines.push('--------------');
  lines.push('DB tracked directories:');
  for (const dir of result.config.db_tracked) lines.push(`  - ${dir}`);
  lines.push('');
  lines.push('DB-only directories:');
  for (const dir of result.config.db_only) lines.push(`  - ${dir}`);

  return lines.join('\n');
}

function formatBytes(bytes: number): string {
  if (bytes === 0) return '0 B';
  const k = 1024;
  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
}

// ── storage init (GST-1943) ───────────────────────────────

async function runStorageInit(engine: BrainEngine, args: string[]): Promise<void> {
  const json = args.includes('--json');
  const value = (flag: string): string | undefined => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
  const { initStorageSource } = await import('../core/storage-manifest/source.ts');
  try {
    const expect = value('--expect');
    const result = await initStorageSource(engine, { dir: value('--dir'), pushRemote: value('--push-remote'), dryRun: args.includes('--dry-run') || expect === undefined && args.includes('--dir'), expect });
    if (json) { console.log(JSON.stringify(result)); return; }
    for (const line of result.summary) console.log(line);
    if (result.dry_run && result.apply) console.log(`Apply (after the user agrees): ${result.apply.join(' ')}`);
    else if (!result.dry_run && result.action !== 'none') console.log('Done: the storage shelf exists.');
  } catch (error) {
    if (!(error instanceof OperationError)) throw error;
    console.log(json ? JSON.stringify({ error: error.code, message: error.message, suggestion: error.suggestion }) : `Refused (${error.code}): ${error.message}
Fix: ${error.suggestion ?? ''}`);
    setCliExitVerdict(error.code === 'invalid_params' ? 2 : 1);
  }
}

// ── storage adopt / export / import (GST-1943) ─────────────

function flagValue(args: string[], flag: string): string | undefined {
  const i = args.indexOf(flag);
  return i >= 0 ? args[i + 1] : undefined;
}

async function shelfCliContext(engine: BrainEngine, sourceId: string): Promise<OperationContext> {
  const { loadConfig } = await import('../core/config.ts');
  const { resolveCliWriteWaitMs } = await import('../core/persistence/write-wait.ts');
  const config = loadConfig() ?? { engine: engine.kind };
  return { engine, config, remote: false, dryRun: false, sourceId, writeWaitMs: resolveCliWriteWaitMs({ config }),
    logger: { info: () => {}, warn: (m: string) => console.error(m), error: (m: string) => console.error(m) } } as unknown as OperationContext;
}

async function shelfRefusal(error: unknown, json: boolean): Promise<void> {
  if (!(error instanceof OperationError)) throw error;
  const { writeCliError } = await import('../cli/cli-error.ts');
  setCliExitVerdict(writeCliError(error, 'storage', { json }));
}

const argvText = (argv: string[]) => argv.map(shellQuote).join(' ');

type ShelfOutcome = { side_effects: string; failure?: { item: string; code: string; message: string }; pending?: Array<{ item: string; request_id: string; poll: string[] }>; rerun?: string[] };

/** Exit 1 on a failure or a conflict, else exit 10 while an accepted write is still pending (poll it; never resubmit). */
function outcomeExit(result: ShelfOutcome, refused: boolean): void {
  if (result.failure || refused) setCliExitVerdict(1);
  else if (result.pending?.length) setCliExitVerdict(PENDING_WRITE_EXIT_CODE);
}

function printOutcome(result: ShelfOutcome): void {
  console.log(`Side effects: ${result.side_effects}.`);
  for (const held of result.pending ?? []) console.log(`Accepted, still being written: ${held.item} (poll it with ${argvText(held.poll)}; do not submit it again).`);
  if (result.failure) console.log(`Stopped at ${result.failure.item} (${result.failure.code}): ${result.failure.message}`);
  if (result.rerun) console.log(`${result.failure ? 'Rerun after fixing it' : 'Rerun once it has committed, to finish'}: ${argvText(result.rerun)}`);
}

async function runStorageAdopt(engine: BrainEngine, args: string[]): Promise<void> {
  const json = args.includes('--json');
  const adopt = await import('../core/storage-manifest/adopt.ts');
  const rawPrefix = (flagValue(args, '--from-prefix') ?? adopt.ADOPT_DEFAULT_PREFIX).trim().toLowerCase();
  const opts = { sourceId: flagValue(args, '--source') ?? adopt.ADOPT_DEFAULT_SOURCE, prefix: rawPrefix.endsWith('/') ? rawPrefix : `${rawPrefix}/` };
  const expect = flagValue(args, '--expect');
  const finalize = args.includes('--finalize');
  const apply = args.includes('--apply');
  const dropFields = args.flatMap((arg, i) => arg === '--drop-field' && args[i + 1] ? [args[i + 1]!] : []);
  try {
    const preview = [...adopt.adoptArgv(opts), ...(finalize ? ['--finalize'] : [])];
    if (opts.prefix === '/') throw opError('invalid_params', '--from-prefix needs a slug prefix such as storage-manifest/.', 'Pass the folder the interim pages live under, or omit --from-prefix for storage-manifest/.');
    if (apply && finalize) throw opError('invalid_params', '--apply and --finalize are separate steps.', 'Apply the adopt first; finalize afterwards with gbrain storage adopt --finalize, then its --expect value.');
    if ((apply && !expect) || (expect && !apply && !finalize)) {
      throw opError('invalid_params', 'An apply needs both --apply and the --expect value its preview printed.', 'Preview without --apply, then run the apply command the preview prints after the user agrees.',
        { fix: readFix('Prints the plan and its plan_hash; changes nothing.', { argv: [...preview, '--json'] }) });
    }
    const ctx = await shelfCliContext(engine, opts.sourceId);
    const result = finalize
      ? expect ? await adopt.applyFinalize(ctx, { ...opts, expect }) : await adopt.previewFinalize(ctx, opts)
      : expect ? await adopt.applyAdopt(ctx, { ...opts, expect, dropFields }) : await adopt.previewAdopt(ctx, opts);
    if (!result.dry_run) outcomeExit(result, result.action === 'adopt' && result.conflicts.length > 0);
    if (json) { console.log(JSON.stringify(result)); return; }
    if (result.dry_run) {
      for (const line of result.summary) console.log(line);
      for (const entry of result.entries) {
        const extra = 'refused' in entry ? [...entry.refused.map((f) => `${f.field} refused (${f.reason})`), ...(entry.problem ? [entry.problem.message] : [])] : [];
        console.log(`  ${entry.state.padEnd(11)} ${entry.slug}${entry.card_id ? ` -> ${entry.card_id}` : ''}${extra.length ? `: ${extra.join('; ')}` : ''}`);
      }
      console.log(`plan_hash: ${result.plan_hash}`);
      if (result.apply) console.log(`Apply (after the user agrees): ${argvText(result.apply)}`);
      return;
    }
    if (result.action === 'adopt') {
      for (const row of result.results) console.log(`  ${row.outcome.padEnd(10)} ${row.slug}${row.card_id ? ` -> ${row.card_id}` : ''}`);
      if (result.conflicts.length) console.log(`Conflicts (a different card with that id is on the shelf; nothing was overwritten): ${result.conflicts.join(', ')}`);
      printOutcome(result);
      if (result.index?.resume) console.log(`The shelf's sync checkpoint is behind the cards committed; index them with ${argvText(result.index.resume)}`);
      if (result.finalize) console.log(`Originals are kept. Preview deleting them: ${argvText(result.finalize)}`);
      return;
    }
    console.log(`Soft-deleted ${result.deleted.length} original(s) (restorable for 72 hours with gbrain restore).`);
    printOutcome(result);
  } catch (error) {
    await shelfRefusal(error, json);
  }
}

async function runStorageJsonl(engine: BrainEngine, subcommand: 'export' | 'import', args: string[]): Promise<void> {
  const json = args.includes('--json');
  const jsonl = await import('../core/storage-manifest/jsonl.ts');
  const { readFileSync, writeFileSync } = await import('fs');
  try {
    if (!args.includes('--jsonl')) throw opError('invalid_params', `gbrain storage ${subcommand} reads and writes JSONL only, so it needs --jsonl.`,
      subcommand === 'export' ? 'Run gbrain storage export --jsonl, adding --out with a new file path to write a file.' : 'Run gbrain storage import --jsonl with the path of an export file.');
    if (subcommand === 'export') {
      const out = flagValue(args, '--out');
      if (out && existsSync(out)) throw opError('invalid_params', `${out} already exists; export never overwrites a file.`, 'Pass --out with a path that does not exist yet, or omit --out to write to stdout.');
      const { lines, skipped, invalid } = await jsonl.exportShelfJsonl(engine);
      const text = lines.length ? `${lines.join('\n')}\n` : '';
      if (!out) { process.stdout.write(text); }
      else { writeFileSync(out, text, { flag: 'wx' }); console.error(`Wrote ${lines.length} card(s) to ${out}.`); }
      if (skipped.length) console.error(`Skipped ${skipped.length} page(s) on the shelf that hold no card: ${skipped.join(', ')}`);
      if (invalid.length) console.error(`Skipped ${invalid.length} card(s) that fail the card rules (gbrain doctor --only storage_manifest names why): ${invalid.join(', ')}`);
      return;
    }
    const file = flagValue(args, '--jsonl');
    if (!file || file.startsWith('--')) throw opError('invalid_params', 'gbrain storage import needs the JSONL file after --jsonl.', 'Run gbrain storage import --jsonl with the path of a file gbrain storage export wrote.');
    if (!existsSync(file)) throw opError('invalid_params', `No file at ${file}.`, 'Pass --jsonl with the path of a file gbrain storage export wrote.');
    const text = readFileSync(file, 'utf8');
    const expect = flagValue(args, '--expect');
    if (args.includes('--apply') !== (expect !== undefined)) throw opError('invalid_params', 'An import apply needs both --apply and the --expect value its preview printed.',
      'Preview without --apply, then run the apply command the preview prints after the user agrees.',
      { fix: readFix('Prints the import plan and its plan_hash; writes nothing.', { argv: ['gbrain', 'storage', 'import', '--jsonl', file, '--json'] }) });
    if (expect !== undefined) {
      const result = await jsonl.applyImport(await shelfCliContext(engine, 'default'), file, text, expect);
      outcomeExit(result, result.conflicts.length > 0 || result.invalid.length > 0);
      if (json) { console.log(JSON.stringify(result)); return; }
      console.log(`Created ${result.created.length} card(s); ${result.identical.length} already on the shelf.`);
      if (result.conflicts.length) console.log(`Conflicts (a different card with that id is on the shelf; nothing was overwritten): ${result.conflicts.join(', ')}`);
      if (result.invalid.length) console.log(`Invalid lines skipped: ${result.invalid.join(', ')}`);
      printOutcome(result);
      return;
    }
    const { cards: _cards, ...plan } = await jsonl.previewImport(engine, file, text);
    if (json) { console.log(JSON.stringify(plan)); return; }
    for (const line of plan.summary) console.log(line);
    for (const line of plan.lines) console.log(`  line ${String(line.line).padEnd(5)} ${line.action.padEnd(9)} ${line.id ?? ''}${line.message ? `: ${line.message}` : ''}`);
    console.log(`plan_hash: ${plan.plan_hash}`);
    if (plan.apply) console.log(`Apply (after the user agrees): ${argvText(plan.apply)}`);
  } catch (error) {
    await shelfRefusal(error, json);
  }
}