Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
75.2 KB
Raw Blame
import type { BrainEngine } from '../core/engine.ts';
import { execSync, execFileSync, spawnSync } from '../core/spawn.ts';
import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, realpathSync } from 'fs';
import { basename, join, dirname, resolve } from 'path';
import { isNewerVersion, parseSemver, semverGt } from '../core/semver.ts';
import { cliChildStdio, jsonRequested, setCliExitVerdict, writeJsonDocument } from '../core/cli-force-exit.ts';
import { opError, type OperationError } from '../core/ops/contract.ts';
import { writeCliError } from '../cli/cli-error.ts';
import { VERSION } from '../version.ts';
import type { InteractiveProbe } from '../core/interaction.ts';
import { forwardProgressPast, hostWorkOwedForVersion, hostWorkOwedMessage, indexCompletedEntries, migrationLedgerSummary, wedgedLedgerHint } from '../core/migration-ledger.ts';
import { loadCompletedMigrations } from '../core/preferences.ts';
import { MIGRATIONS_RUNNING_EXIT_CODE, readMigrationLockHolder } from '../core/migration-orchestration-lock.ts';
import { loadConfig, gbrainPath } from '../core/config.ts';
import { clearSnooze, clearUpdateCache, currentReleaseChannel, writeJustUpgraded, writeSwapReceipt, type ReleaseChannel } from '../core/self-upgrade.ts';
import { handleRestartOnly, preflightHostRestart } from './upgrade-restart.ts';
import { resolveStableRelease } from '../core/stable-channel.ts';
import { channelTarget, runUpgradeDryRun } from './upgrade-channel.ts';
export { parseChannelArg, resolveStableRelease } from '../core/stable-channel.ts';
import { MOVEMENT_SUPERVISOR_STEP } from './movement-step.ts';
import {
  BUN_FLOOR_EXIT_CODE,
  evaluateBunFloor,
  globalGbrainSpec,
  readBunLinkTarget,
  readHostBun,
  readPackageTarget,
  type TargetFloor,
} from '../core/bun-floor.ts';

const GBRAIN_GITHUB_REPO = 'garrytan/gbrain';

/**
 * Compare the post-swap resolved version against the caller's target (#4366).
 * `bun update` exits 0 without upgrading exact-tag Git installs (the pin
 * wins), so exit status alone cannot prove a swap happened. 'unverified'
 * (missing/unparseable observed version) keeps legacy fail-open behavior —
 * only a confirmed still-older version is a 'mismatch'.
 */
export function assessUpgradeOutcome(
  target: string | undefined,
  observed: string,
): 'ok' | 'mismatch' | 'unverified' {
  if (!target) return 'ok';
  const t = parseSemver(target);
  const o = parseSemver(observed.trim());
  if (!t || !o) return 'unverified';
  return semverGt(t, o) ? 'mismatch' : 'ok';
}

export async function runUpgrade(args: string[], opts: { targetVersion?: string } = {}) {
  if (args.includes('--help') || args.includes('-h')) {
    console.log('Usage: gbrain upgrade [--channel stable|alpha] [--dry-run] [--stop-mcp] [--no-restart] [--swap-only] [--no-autopilot-install] [--no-bun-floor-check]\n       gbrain upgrade --restart-only [--stop-mcp] [--dry-run] [--json]\n\nSelf-update the CLI, then restart every gbrain process on this host onto the new build.\n\nDetects install method (bun, bun-link, binary) and runs the appropriate update.\nAfter upgrading, shows what\'s new and offers to set up new features.\n\n--channel <name>        stable (the default: weekly, sooner only for security, data-loss and stable-regression fixes,\n                       and only to a release whose gates passed on its exact code) or alpha (every published\n                       release; latest is an alias). Precedence: --channel, GBRAIN_RELEASE_CHANNEL,\n                       self_upgrade.channel, stable. Persist it as self_upgrade.channel in config.\n--stop-mcp              Stop MCP stdio servers agent harnesses started, instead of refusing; reconnect gbrain\n                       in each harness afterwards.\n--no-restart            Install without restarting anything (doctor reports runtime_build_skew until\n                       \'gbrain upgrade --restart-only\' runs).\n--restart-only          Restart serve, autopilot, the jobs supervisor and its worker (and, with --stop-mcp, MCP\n                       servers) onto the installed build, then verify every process reports it and the warm\n                       CLI socket accepts it. A process it cannot restart refuses with the exact step (exit 3).\n--dry-run               Print the effective channel, where it came from and what would install; change nothing.\n                       With --restart-only: print the restart plan instead.\n--no-autopilot-install  Skip autopilot installation and service rewrites.\n                       Also supported as GBRAIN_NO_AUTOPILOT_INSTALL=1.\n--no-bun-floor-check    Upgrade even when the target release\'s Bun floor cannot be read or is above\n                       this host\'s Bun (manual upgrades only). Docs: docs/guides/upgrades-auto-update.md#bun-floor.\n--swap-only  Perform ONLY the binary/source swap and skip post-upgrade\n             (migrations run on the next launch). Used by the autopilot\n             silent self-upgrade channel so the daemon can swap + relaunch\n             without a 30-min blocking post-upgrade inside its tick.');
    return;
  }

  // --swap-only: do the swap, skip the (potentially 30-min) post-upgrade. The
  // relaunched binary runs migrations on boot (split-brain guard). v0.42.
  const swapOnly = args.includes('--swap-only');
  const noAutopilotInstall = args.includes('--no-autopilot-install') || process.env.GBRAIN_NO_AUTOPILOT_INSTALL === '1';
  const checkBunFloor = !args.includes('--no-bun-floor-check');
  // #5693: post-upgrade owns migrations. gbrain ships no postinstall now; the flag still tells an older release's postinstall to skip them.
  const upgradeEnv = { ...process.env, GBRAIN_UPGRADE_OWNS_MIGRATIONS: '1', ...(noAutopilotInstall ? { GBRAIN_NO_AUTOPILOT_INSTALL: '1' } : {}) };

  const json = jsonRequested(args);
  const stopMcp = args.includes('--stop-mcp');
  const restartOpts = { stopMcp, json, rerunArgv: ['gbrain', 'upgrade', ...args.filter(a => a !== '--json')] };
  if (await handleRestartOnly(args, restartOpts)) return;
  if (await runUpgradeDryRun(args, json)) return;
  const noRestart = args.includes('--no-restart');
  // Capture old version BEFORE upgrading (Codex finding: old binary runs this code)
  const oldVersion = VERSION;
  const method = detectInstallMethod();

  console.log(`Detected install method: ${method}`);

  const stableTarget = await channelTarget(args, oldVersion, json);
  if (stableTarget === 'stop') return;
  if (stableTarget) opts = { ...opts, targetVersion: stableTarget.version };
  if (!swapOnly && !noRestart && !await preflightHostRestart(restartOpts)) return;

  let upgraded = false;
  const recovery: SmokeRecovery = { method, oldVersion };
  if (stableTarget) {
    const outcome = await installStableRelease(method, stableTarget, { oldVersion, upgradeEnv, checkBunFloor, recovery });
    if (outcome === 'refused') return;
    upgraded = outcome === 'installed';
  } else switch (method) {
    case 'bun-link': {
      const linkInfo = detectBunLink();
      if (!linkInfo) {
        console.error('bun-link detected but could not resolve repo root.');
        break;
      }
      console.log(`Upgrading bun-link source clone at ${linkInfo.repoRoot}...`);
      // #5855: fast-forward to the exact commit whose Bun floor was checked.
      const checked = checkBunFloor ? readBunLinkTarget(linkInfo.repoRoot) : null;
      if (checked && refuseForBunFloor(checked.target, opts.targetVersion)) return;
      const sha = checked?.sha;
      try { recovery.previousSha = execFileSync('git', ['-C', linkInfo.repoRoot, 'rev-parse', 'HEAD'], { encoding: 'utf-8', timeout: 10_000 }).trim(); } catch { /* recovery text falls back */ }
      recovery.repoRoot = linkInfo.repoRoot;
      try {
        execFileSync('git', ['-C', linkInfo.repoRoot, ...(sha ? ['merge', '--ff-only', sha] : ['pull', '--ff-only'])], { stdio: 'inherit', timeout: 120_000 });
        execFileSync('bun', ['install'], { cwd: linkInfo.repoRoot, env: upgradeEnv, stdio: 'inherit', timeout: 120_000 });
        upgraded = true;
      } catch {
        if (installedDespiteFailure(oldVersion)) upgraded = true;
        else {
          console.error('Auto-upgrade failed. Try manually:');
          console.error(`  cd ${linkInfo.repoRoot} && git pull && bun install`);
        }
      }
      break;
    }

    case 'bun': {
      console.log('Upgrading via bun...');
      const bunGlobalRoot = resolveBunGlobalRoot();
      const pinned = await replacePinnedInstall(bunGlobalRoot, opts.targetVersion ?? null, { oldVersion, upgradeEnv, checkBunFloor, recovery, phase: 'pinned-reinstall' });
      if (pinned) { if (pinned === 'refused') return; upgraded = pinned === 'installed'; break; }
      if (checkBunFloor && refuseForBunFloor(await readPackageTarget(globalGbrainSpec(bunGlobalRoot)), opts.targetVersion)) return;
      try {
        execFileSync('bun', ['update', BUN_BACKEND, 'gbrain'], { cwd: bunGlobalRoot, env: upgradeEnv, stdio: 'inherit', timeout: 120_000 });
        upgraded = true;
      } catch {
        if (installedDespiteFailure(oldVersion)) upgraded = true;
        else {
          console.error('Upgrade failed. Try running manually:');
          console.error(`  cd ${bunGlobalRoot} && bun update ${BUN_BACKEND} gbrain`);
        }
      }
      break;
    }

    case 'binary': {
      // v0.42: real atomic self-update on the published targets
      // (darwin-arm64, linux-x64). Other platforms have no asset → notify.
      const { runBinarySelfUpdate } = await import('../core/binary-self-update.ts');
      console.log('Updating gbrain binary (atomic download + replace)...');
      const result = await runBinarySelfUpdate();
      if (result.ok) {
        upgraded = true;
      } else if (result.reason === 'unsupported_platform' || result.reason === 'no_asset') {
        console.log('No published binary for this platform/arch.');
        console.log('Download the latest binary from GitHub Releases:');
        console.log('  https://github.com/garrytan/gbrain/releases');
      } else if (
        result.reason === 'integrity_failed' ||
        result.reason === 'integrity_unavailable' ||
        result.reason === 'version_mismatch'
      ) {
        // Fail-closed: the downloaded binary was never installed (renamed over
        // the live path). "signed" is intentionally omitted — we match against
        // the build-provenance attestation's digest + builder identity fetched
        // over TLS from the GitHub API; we do NOT independently verify the
        // Sigstore signature chain (see src/core/binary-self-update.ts header).
        const detail =
          result.reason === 'integrity_failed'
            ? 'the downloaded binary did not match its build-provenance attestation (digest/builder mismatch)'
            : result.reason === 'version_mismatch'
              ? 'the downloaded binary reported a different version than the release it was fetched for (possible downgrade)'
              : 'the build-provenance attestation could not be fetched (offline, rate-limited, or missing)';
        console.error(`Binary self-update rejected — integrity not confirmed: ${detail}.`);
        console.error('Your existing binary is unchanged and the download was discarded.');
        console.error('Retry later, or download + verify manually:');
        console.error('  https://github.com/garrytan/gbrain/releases');
        recordUpgradeError({
          phase: 'binary-self-update',
          fromVersion: oldVersion,
          toVersion: opts.targetVersion ?? result.targetVersion ?? 'unknown',
          error: result.reason,
          recover: 'Integrity check failed; existing binary retained. Retry or download manually.',
        });
      } else {
        console.error(`Binary self-update failed (${result.reason}${result.error ? `: ${result.error}` : ''}).`);
        console.error('Your existing binary is unchanged. Download manually if needed:');
        console.error('  https://github.com/garrytan/gbrain/releases');
        recordUpgradeError({
          phase: 'binary-self-update',
          fromVersion: oldVersion,
          toVersion: opts.targetVersion ?? result.targetVersion ?? 'unknown',
          error: `${result.reason}${result.error ? `: ${result.error}` : ''}`,
          recover: 'Download from https://github.com/garrytan/gbrain/releases',
        });
      }
      break;
    }

    default:
      console.error('Could not detect installation method.');
      console.log('Try one of:');
      console.log(`  bun update ${BUN_BACKEND} gbrain`);
      console.log('  Download from https://github.com/garrytan/gbrain/releases');
  }

  if (!upgraded) {
    console.log('Binary: upgrade failed');
    // #6828: an install step can fail after replacing files, so only a probe
    // that still reads the old version proves nothing was installed.
    const observed = verifyUpgrade();
    if (observed && observed === oldVersion) writeSwapReceipt({ outcome: 'not_installed', from: oldVersion, installed: observed });
    return;
  }
  const newVersion = verifyUpgrade();
  // #6828: an install step that exits 0 can install nothing (`bun update` on a
  // moving tag whose head is already installed). A verified version that is
  // not newer than the one running is no swap: no last_upgrade overwrite, no
  // JUST_UPGRADED breadcrumb, no cache reset, and the receipt tells the
  // autopilot channel not to relaunch or record known-bad. A verified version
  // EQUAL to the running one is the no-op; an unreadable one keeps the legacy path.
  const newParsed = parseSemver(newVersion);
  const oldParsed = parseSemver(oldVersion);
  const unchanged = !!newParsed && !!oldParsed && newParsed.join('.') === oldParsed.join('.');
  if (unchanged) {
    console.log(`No newer version was installed: still running gbrain ${newVersion}.`);
    writeSwapReceipt({ outcome: 'not_installed', from: oldVersion, installed: newVersion });
  } else {
    console.log(newVersion ? `Upgrade complete. Now running: gbrain ${newVersion}` : 'Upgrade complete. Could not verify new version.');
  }
  // #4366: a still-older resolved version means the swap never happened
  // (exact-tag Git pins make `bun update` a successful no-op). Fail loudly
  // and return BEFORE the breadcrumb/cache bookkeeping below, so the
  // pending-upgrade marker survives and keeps nagging.
  const target = opts.targetVersion;
  if (target && assessUpgradeOutcome(target, newVersion) === 'mismatch') {
    console.error(`Upgrade did not take effect: still running ${newVersion}, expected ${target}.`);
    const plan = planPinnedReinstall(target, oldVersion);
    printPinnedReinstall(plan, oldVersion, 'Exact-tag Git installs stay pinned through `bun update`. Reinstall with:');
    recordUpgradeError({
      phase: 'verify-target',
      fromVersion: oldVersion,
      toVersion: target,
      error: `still running ${newVersion} after upgrade`,
      recover: pinnedReinstallHint(plan),
    });
    setCliExitVerdict(1);
    return;
  }
  // #5311: a bare `gbrain upgrade` has no target, so the check above cannot
  // fire, and on an exact-tag Git pin `bun update` is a successful no-op.
  // When the version did not change and the global install pins a tag, say
  // so and exit non-zero instead of reporting an upgrade. #6718: the target is
  // the newest PUBLISHED release tag only; with none newer the hint moves the
  // install off the pin, and the ledger row names no unpublished version.
  if (!target && method === 'bun' && unchanged) {
    const pin = bunGlobalExactTagPin(resolveBunGlobalRoot(), true);
    if (pin) {
      const plan = planPinnedReinstall(null, oldVersion);
      console.error(`Upgrade did not take effect: still running ${newVersion}, because the global install is pinned to ${pin} and \`bun update\` keeps a pinned tag.`);
      printPinnedReinstall(plan, oldVersion, 'Reinstall to move off the pin:');
      recordUpgradeError({
        phase: 'verify-pin',
        fromVersion: oldVersion,
        toVersion: plan.version ?? 'latest',
        error: `pinned to ${pin}; still running ${newVersion} after upgrade`,
        recover: pinnedReinstallHint(plan),
      });
      setCliExitVerdict(1);
      return;
    }
  }
  if (!unchanged) {
    // Save old version for post-upgrade migration detection
    saveUpgradeState(oldVersion, newVersion);
    // #5855: `--version` answers on any Bun, so prove the new release starts.
    if (!postSwapSmoke(newVersion, recovery)) {
      writeSwapReceipt({ outcome: 'installed_broken', from: oldVersion, installed: newVersion || null });
      return;
    }

    // Self-upgrade breadcrumb + cache reset (covers both the full and
    // --swap-only paths, so the autopilot silent channel benefits too):
    //   - write just-upgraded-from so the next invocation's startup hook prints
    //     the one-time JUST_UPGRADED confirmation;
    //   - clear the update-check cache + snooze so a now-stale "upgrade
    //     available" marker doesn't keep nudging after we've already applied it.
    try {
      writeJustUpgraded(oldVersion);
      clearUpdateCache();
      clearSnooze();
    } catch {
      /* best-effort: never block the upgrade on confirmation bookkeeping */
    }
    writeSwapReceipt({ outcome: 'installed', from: oldVersion, installed: newVersion || null });
  }

  // --swap-only stops here: the swap is done + smoke-verified (or installed
  // nothing), but the (potentially 30-min) post-upgrade is deferred to the
  // next launch so the autopilot silent channel can swap + relaunch without
  // freezing its tick. connectEngine's pending-migration probe + runPostUpgrade run on boot.
  if (swapOnly) {
    return;
  }
  // Run post-upgrade feature discovery (reads migration files from the NEW binary).
  // Timeout bumped 300s → 1800s (30 min) in v0.15.2 because v0.12.0 graph
  // backfill on 50K+ brains regularly exceeded the old ceiling. The heartbeat
  // wiring added in v0.15.2 makes the long wait observable; a hard 300s
  // cap would still kill legit migrations mid-run. Override via
  // GBRAIN_POST_UPGRADE_TIMEOUT_MS env var.
  const postUpgradeTimeoutMs = Number(
    process.env.GBRAIN_POST_UPGRADE_TIMEOUT_MS || 1_800_000,
  );
  let migrationsLine = 'Migrations: complete';
  try {
    execFileSync('gbrain', ['post-upgrade', ...(noAutopilotInstall ? ['--no-autopilot-install'] : [])], { env: upgradeEnv, stdio: 'inherit', timeout: postUpgradeTimeoutMs });
  } catch (e) {
    migrationsLine = await describeMigrationFailure(e, newVersion);
    // post-upgrade is best-effort, don't fail the upgrade. BUT leave a
    // trail so `gbrain doctor` can surface it and give the user a clear
    // paste-ready recovery command. Silent failure here is how users end
    // up with half-upgraded brains and no signal. A competing runner is
    // not a failure: its own run finishes the migrations.
    if ((e as { status?: number }).status !== MIGRATIONS_RUNNING_EXIT_CODE) recordUpgradeError({
      phase: 'post-upgrade',
      fromVersion: oldVersion,
      toVersion: newVersion,
      error: e instanceof Error ? e.message : String(e),
      recover: 'Run: gbrain apply-migrations --yes',
    });
  }
  // Run features scan to show what's new and what to fix
  try {
    execSync('gbrain features', { stdio: 'inherit', timeout: 30_000 });
  } catch {
    // features scan is best-effort
  }
  // GBRA-175: the new build restarts every process onto itself and verifies one build runs (this process is the old build).
  const restartLine = unchanged ? 'Restart: nothing to restart (no newer version was installed)'
    : noRestart ? 'Restart: skipped (--no-restart). Run `gbrain upgrade --restart-only`; doctor reports runtime_build_skew until then'
    : restartOntoNewBuild(stopMcp, newVersion);
  console.log(unchanged ? `Binary: no newer version installed (still ${newVersion})` : `Binary: installed ${newVersion || 'a new version (could not verify)'}`);
  console.log(migrationsLine);
  console.log(restartLine);
  // #6317 (I2): the supervisor proves data movement once serve and the workers run the new build.
  console.log(`Next: ${MOVEMENT_SUPERVISOR_STEP}`);
}

/** GBRA-175: the new build restarts every process onto itself and verifies one build runs; returns the summary line. */
function restartOntoNewBuild(stopMcp: boolean, newVersion: string): string {
  const restart = spawnSync('gbrain', ['upgrade', '--restart-only', ...(stopMcp ? ['--stop-mcp'] : [])], { stdio: cliChildStdio(), env: { ...process.env, GBRAIN_SKIP_STARTUP_HOOKS: '1' }, timeout: 900_000 });
  if (restart.status === 0) return `Restart: every gbrain process on this host runs ${newVersion || 'the new build'}`;
  setCliExitVerdict(restart.status ?? 1);
  return `Restart: incomplete (exit ${restart.status ?? restart.signal ?? 'unknown'}). Follow the steps above, then run \`gbrain upgrade --restart-only\``;
}

/**
 * GBRA-175: `bun update` keeps a pinned tag or commit, so a pinned global install is replaced with the newest published
 * release (remove, then add the tag). null when the install is not pinned, or a requested version is not published (#6662
 * then reports it after the no-op update).
 */
async function replacePinnedInstall(globalRoot: string, requested: string | null, ctx: StableInstallContext): Promise<'installed' | 'failed' | 'refused' | null> {
  const pin = bunGlobalExactTagPin(globalRoot, true);
  const plan = pin ? planPinnedReinstall(requested, ctx.oldVersion) : null;
  if (!plan?.version || plan.unpublished) return null;
  console.log(`The global install is pinned to ${pin}; replacing it with v${plan.version}.`);
  return installStableRelease('bun', { version: plan.version, commit: '' }, ctx);
}

interface StableInstallContext { oldVersion: string; upgradeEnv: NodeJS.ProcessEnv; checkBunFloor: boolean; recovery: SmokeRecovery; phase?: string }

/**
 * GBRA-175: install exactly the stable release. bun: reinstall pinned to its tag (an in-place tag swap corrupts a
 * global install, #5034), restoring the previous release when the add fails. bun-link: fast-forward the clone to the
 * release commit, never backward or across a fork. binary: the release's own asset.
 */
async function installStableRelease(method: string, target: { version: string; commit: string }, ctx: StableInstallContext): Promise<'installed' | 'failed' | 'refused'> {
  const spec = `github:${GBRAIN_GITHUB_REPO}#v${target.version}`;
  if (method === 'unknown') {
    console.error('The stable channel installs through bun, a bun-link clone or the release binary, and this install method could not be detected. Nothing was changed.');
    console.error(`Reinstall on the stable release with: ${bunReinstallCommand(`#v${target.version}`)}`);
    setCliExitVerdict(1);
    return 'refused';
  }
  if (ctx.checkBunFloor && method !== 'binary' && refuseForBunFloor(await readPackageTarget(spec), target.version)) return 'refused';
  if (method === 'binary') {
    const { runBinarySelfUpdate, fetchReleaseByTag } = await import('../core/binary-self-update.ts');
    const result = await runBinarySelfUpdate(process.execPath, { fetchRelease: () => fetchReleaseByTag(`v${target.version}`) });
    if (result.ok) return 'installed';
    console.error(`Binary self-update to the stable release ${target.version} failed (${result.reason}${result.error ? `: ${result.error}` : ''}). Your existing binary is unchanged.`);
    recordUpgradeError({ phase: 'binary-self-update', fromVersion: ctx.oldVersion, toVersion: target.version, error: `${result.reason}`, recover: 'Retry gbrain upgrade --channel stable, or download the release asset manually.' });
    setCliExitVerdict(1);
    return 'failed';
  }
  if (method === 'bun-link') {
    const link = detectBunLink();
    if (!link) { console.error('bun-link detected but could not resolve repo root.'); return 'failed'; }
    const git = (gitArgs: string[]) => spawnSync('git', ['-C', link.repoRoot, ...gitArgs], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 120_000 });
    try { ctx.recovery.previousSha = execFileSync('git', ['-C', link.repoRoot, 'rev-parse', 'HEAD'], { encoding: 'utf-8', timeout: 10_000 }).trim(); } catch { /* recovery text falls back */ }
    ctx.recovery.repoRoot = link.repoRoot;
    if (git(['fetch', '--quiet', 'origin', `+refs/tags/v${target.version}:refs/tags/v${target.version}`]).status !== 0) {
      console.error(`Could not fetch v${target.version} into ${link.repoRoot}. Nothing was changed.`);
      setCliExitVerdict(1);
      return 'failed';
    }
    if (git(['merge-base', '--is-ancestor', 'HEAD', target.commit]).status !== 0) {
      console.error(`The clone at ${link.repoRoot} has commits that v${target.version} does not, and the stable channel never moves a clone backward or across a fork. Nothing was changed.`);
      console.error(`To run the stable release from this clone, check it out yourself: git -C ${link.repoRoot} checkout v${target.version} && bun install`);
      setCliExitVerdict(1);
      return 'refused';
    }
    try {
      execFileSync('git', ['-C', link.repoRoot, 'merge', '--ff-only', target.commit], { stdio: cliChildStdio(), timeout: 120_000 });
      execFileSync('bun', ['install'], { cwd: link.repoRoot, env: ctx.upgradeEnv, stdio: cliChildStdio(), timeout: 120_000 });
      return 'installed';
    } catch {
      if (installedDespiteFailure(ctx.oldVersion)) return 'installed';
      console.error(`Upgrade to v${target.version} failed. Try manually: cd ${link.repoRoot} && git merge --ff-only ${target.commit} && bun install`);
      return 'failed';
    }
  }
  if (probeReleaseTag(target.version) === 'not_published') {
    console.error(`v${target.version} has no release tag on GitHub. Nothing was removed.`);
    setCliExitVerdict(1);
    return 'refused';
  }
  const bun = (bunArgs: string[]) => execFileSync('bun', bunArgs, { env: ctx.upgradeEnv, stdio: cliChildStdio(), timeout: 300_000 });
  try {
    bun(['remove', '-g', 'gbrain']);
    bun(['add', '-g', BUN_BACKEND, spec]);
    return 'installed';
  } catch {
    if (installedDespiteFailure(ctx.oldVersion)) return 'installed';
    console.error(`Installing ${spec} failed. Restoring gbrain ${ctx.oldVersion}...`);
    try { bun(['add', '-g', BUN_BACKEND, `github:${GBRAIN_GITHUB_REPO}#v${ctx.oldVersion}`]); console.error(`Restored gbrain ${ctx.oldVersion}.`); }
    catch { console.error(`Restore failed. Reinstall by hand: ${bunReinstallCommand(`#v${target.version}`)}`); }
    recordUpgradeError({ phase: ctx.phase ?? 'stable-reinstall', fromVersion: ctx.oldVersion, toVersion: target.version, error: `bun add -g ${BUN_BACKEND} ${spec} failed`, recover: bunReinstallCommand(`#v${target.version}`) });
    setCliExitVerdict(1);
    return 'failed';
  }
}

/**
 * #5855: the Bun floor of the release `gbrain upgrade` would install for this
 * install method (the autopilot channel's pre-swap check). The swap re-reads
 * it, so a floor raised in between still refuses there. GBRA-175: on the stable
 * channel (self_upgrade.channel) it is the stable release's floor.
 */
export async function readInstallTargetFloor(method: string, channel: ReleaseChannel | null = currentReleaseChannel()): Promise<TargetFloor> {
  if (channel !== 'alpha') {
    const stable = channel ? await resolveStableRelease() : null;
    return !stable?.ok ? { ok: false, failedRead: `the stable channel's release (${stable ? stable.code : 'invalid channel'})` } : readPackageTarget(`github:${GBRAIN_GITHUB_REPO}#v${stable.version}`);
  }
  if (method === 'bun-link') {
    const link = detectBunLink();
    return link ? readBunLinkTarget(link.repoRoot).target : { ok: false, failedRead: 'the bun-link source clone could not be found' };
  }
  return readPackageTarget(method === 'bun' ? globalGbrainSpec(resolveBunGlobalRoot()) : null);
}

/**
 * #5855: refuse a swap whose target the host's Bun cannot start, or whose
 * floor cannot be read. Prints the refusal and sets the floor exit code,
 * which the autopilot channel treats as a hold rather than a failed version.
 */
function refuseForBunFloor(target: TargetFloor, targetVersion: string | undefined): boolean {
  const verdict = evaluateBunFloor(target, readHostBun(), targetVersion);
  if (verdict.ok) return false;
  console.error(verdict.message);
  console.error(verdict.kind === 'unreadable'
    ? 'Nothing was changed. Re-run with --no-bun-floor-check to upgrade without this check.'
    : 'Nothing was changed.');
  setCliExitVerdict(BUN_FLOOR_EXIT_CODE);
  return true;
}

interface SmokeRecovery { method: string; oldVersion: string; repoRoot?: string; previousSha?: string }

/**
 * #5855: after the swap, run a command that passes the CLI's runtime gate
 * (`--version` is exempt from it). A failure prints per-method recovery and
 * exits non-zero; nothing is rolled back automatically.
 */
function postSwapSmoke(newVersion: string, r: SmokeRecovery): boolean {
  const run = spawnSync('gbrain', ['--help'], {
    encoding: 'utf-8',
    stdio: ['ignore', 'ignore', 'pipe'],
    timeout: 60_000,
    env: { ...process.env, GBRAIN_SKIP_STARTUP_HOOKS: '1' },
  });
  if (run.status === 0) return true;
  const why = run.error ? run.error.message : `exit ${run.status ?? run.signal}`;
  const detail = (run.stderr ?? '').trim().split('\n')[0];
  const back = r.method === 'bun-link' && r.repoRoot && r.previousSha
    ? `git -C ${r.repoRoot} checkout ${r.previousSha} && bun install`
    : r.method === 'bun' ? bunReinstallCommand(`#v${r.oldVersion}`) : null;
  console.error(`gbrain ${newVersion || '(new version)'} was installed but does not start: \`gbrain --help\` failed (${why}).${detail ? `\n  ${detail}` : ''}`);
  console.error('Recovery:');
  console.error('  If it names an old Bun: bun upgrade, then gbrain post-upgrade');
  if (back) console.error(`  To return to ${r.oldVersion}: ${back}`);
  recordUpgradeError({
    phase: 'post-swap-smoke',
    fromVersion: r.oldVersion,
    toVersion: newVersion || 'unknown',
    error: `gbrain --help failed after the swap (${why})${detail ? `: ${detail}` : ''}`,
    recover: back ? `bun upgrade && gbrain post-upgrade, or return to ${r.oldVersion}: ${back}` : 'bun upgrade && gbrain post-upgrade',
  });
  setCliExitVerdict(1);
  return false;
}

/**
 * #5693: an install step can fail or time out after the new version is
 * already in place (postinstall work outlived the install timeout). Treat a
 * newer `gbrain --version` as a completed swap instead of reporting failure.
 */
function installedDespiteFailure(oldVersion: string): boolean {
  try {
    const observed = execSync('gbrain --version', { encoding: 'utf-8', timeout: 10_000 }).trim().replace(/^gbrain\s*/i, '');
    const o = parseSemver(observed), prior = parseSemver(oldVersion);
    if (!o || !prior || !semverGt(o, prior)) return false;
    console.log(`The install step did not finish cleanly, but gbrain ${observed} is installed. Migrations run in post-upgrade.`);
    return true;
  } catch {
    return false;
  }
}

export async function describeMigrationFailure(error: unknown, newVersion: string): Promise<string> {
  if ((error as { status?: number }).status === MIGRATIONS_RUNNING_EXIT_CODE) {
    const config = loadConfig();
    const holder = config ? await readMigrationLockHolder(config) : null;
    return `Migrations: running (host ${holder?.host ?? 'unknown'}, pid ${holder?.pid ?? 'unknown'}) in another apply-migrations. `
      + 'Wait for it to finish; `gbrain doctor` shows migration progress.';
  }
  const ledger = newVersion ? loadCompletedMigrations() : [];
  const history = indexCompletedEntries(ledger);
  const summary = newVersion ? migrationLedgerSummary(newVersion).wedged : [];
  const owed = summary.filter(v => hostWorkOwedForVersion(v, history));
  const wedged = summary.filter(v => !owed.includes(v) && forwardProgressPast(v, ledger) === null);
  if (owed.length > 0 && wedged.length === 0) return `Migrations: wedged. ${hostWorkOwedMessage(owed)}`;
  if (wedged.length > 0) {
    return `Migrations: wedged (${wedged.map(v => `v${v}`).join(', ')} ended partial 3+ times in a row). Fix the cause recorded in ${wedgedLedgerHint()}, then run: `
      + `${wedged.map(v => `gbrain apply-migrations --force-retry ${v}`).join(' && ')} && gbrain apply-migrations --yes`;
  }
  return 'Migrations: failed. Run: gbrain apply-migrations --yes';
}

export function resolveBunGlobalRoot(): string {
  const bunInstall = process.env.BUN_INSTALL;
  if (bunInstall) {
    return join(bunInstall, 'install', 'global');
  }

  const defaultRoot = join(process.env.HOME || '', '.bun', 'install', 'global');
  if (isBunGlobalRoot(defaultRoot)) {
    return defaultRoot;
  }

  const installRoot = findBunInstallRootFromArgv();
  return installRoot ?? defaultRoot;
}

/**
 * #8659: Bun's default backend hardlinks package files from its cache on Linux, and OpenClaw refuses a hardlinked
 * plugin manifest, so a global install OpenClaw loads as a plugin stopped loading after every upgrade. Every global
 * reinstall, and each hint that repeats one, copies the files instead.
 */
const BUN_BACKEND = '--backend=copyfile';

/**
 * #5034 / B-NEW-5: reinstall the global Bun package at `ref` by removing it
 * first. An in-place `bun add -g` / `bun install --global` tag swap over an
 * existing global install fails with DependencyLoop on Bun 1.3 and, on Bun
 * 1.4, exits 0 without swapping while it corrupts the global package.json
 * and bun.lock.
 */
export function bunReinstallCommand(ref: string): string {
  const tag = /^#(v\d[\w.]*)$/.exec(ref)?.[1];
  const remove = `bun remove -g gbrain && bun add -g ${BUN_BACKEND} github:${GBRAIN_GITHUB_REPO}${ref}`;
  return tag ? `${releaseTagProbeCommand(tag)} && ${remove}` : remove;
}

const GBRAIN_GIT_URL = `https://github.com/${GBRAIN_GITHUB_REPO}`;

/** #6662: the shell guard a printed reinstall runs first, so a missing tag stops it before `bun remove`. */
function releaseTagProbeCommand(tag: string): string {
  return `git ls-remote --exit-code --tags ${GBRAIN_GIT_URL} refs/tags/${tag}`;
}

type GitRunner = (args: string[]) => { status: number | null; stdout: string };
const runGit: GitRunner = (args) => {
  const r = spawnSync('git', args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 15_000 });
  return { status: r.error ? null : r.status, stdout: r.stdout ?? '' };
};

/**
 * #6662: whether release tag v<version> exists on GitHub. Master's VERSION is
 * stamped before release.yml mints the tag (and superseded versions never get
 * one), so a version can be offered whose tag 404s. `--exit-code` exits 2 when
 * no ref matches; anything else (no git, offline, timeout) is unknown.
 */
export function probeReleaseTag(version: string, git: GitRunner = runGit): 'published' | 'not_published' | 'unknown' {
  const { status } = git(['ls-remote', '--exit-code', '--tags', GBRAIN_GIT_URL, `refs/tags/v${version}`]);
  return status === 0 ? 'published' : status === 2 ? 'not_published' : 'unknown';
}

/** #6662 (D24): the newest published `v<x>` release tag, or null when it cannot be read. */
export function latestPublishedVersion(git: GitRunner = runGit): string | null {
  const { status, stdout } = git(['ls-remote', '--tags', '--refs', GBRAIN_GIT_URL, 'v*']);
  if (status !== 0) return null;
  let best: string | null = null;
  for (const line of stdout.split('\n')) {
    const v = /\trefs\/tags\/v(\d+\.\d+\.\d+(?:\.\d+)?)$/.exec(line.trim())?.[1];
    if (v && (!best || isNewerVersion(best, v))) best = v;
  }
  return best;
}

export interface PinnedReinstallPlan {
  /** The tag-pinned version to reinstall, or null when no published newer release is known. */
  version: string | null;
  /** The requested version whose tag is confirmed missing on GitHub. */
  unpublished: string | null;
}

/**
 * #6662 (D24): tag-pinned installs reinstall a published tag. A requested
 * version is kept unless its tag is confirmed missing; then (or with no
 * request) the newest published tag newer than the running version is used.
 */
export function planPinnedReinstall(requested: string | null, oldVersion: string, git: GitRunner = runGit): PinnedReinstallPlan {
  const state = requested ? probeReleaseTag(requested, git) : null;
  if (requested && state !== 'not_published') return { version: requested, unpublished: null };
  const published = latestPublishedVersion(git);
  return { version: published && isNewerVersion(oldVersion, published) ? published : null, unpublished: requested };
}

/**
 * #6662: the reinstall steps to print. The guarded one-liner works in POSIX
 * shells and PowerShell 7; Windows PowerShell 5.1 has no `&&`, so on Windows
 * each step is its own line. Always ends with the restore line for oldVersion.
 */
export function reinstallHintLines(version: string, oldVersion: string, platform: NodeJS.Platform = process.platform): string[] {
  const tag = `v${version}`;
  const restore = `If the add fails, restore ${oldVersion} with: bun add -g ${BUN_BACKEND} github:${GBRAIN_GITHUB_REPO}#v${oldVersion}`;
  if (platform !== 'win32') return [bunReinstallCommand(`#${tag}`), restore];
  return [
    'Run these one at a time, and stop if the first one fails (the tag is not published yet):',
    releaseTagProbeCommand(tag),
    'bun remove -g gbrain',
    `bun add -g ${BUN_BACKEND} github:${GBRAIN_GITHUB_REPO}#${tag}`,
    restore,
  ];
}

function printPinnedReinstall(plan: PinnedReinstallPlan, oldVersion: string, lead: string): void {
  if (plan.unpublished) {
    console.error(`v${plan.unpublished} is not published yet: its release tag is not on GitHub (tags are created after the release checks pass). Nothing was removed.`);
  }
  if (!plan.version) {
    if (plan.unpublished) return console.error('Retry `gbrain upgrade` later.');
    console.error(lead);
    console.error(`  ${bunReinstallCommand('')}`);
    return;
  }
  console.error(plan.unpublished ? `The newest published release is ${plan.version}. ${lead}` : lead);
  for (const line of reinstallHintLines(plan.version, oldVersion)) console.error(`  ${line}`);
}

function pinnedReinstallHint(plan: PinnedReinstallPlan): string {
  if (plan.version) return bunReinstallCommand(`#v${plan.version}`);
  return plan.unpublished ? `v${plan.unpublished} is not published yet; retry gbrain upgrade later` : bunReinstallCommand('');
}

/**
 * #5311: the exact Git tag the bun global install pins gbrain to
 * (`github:garrytan/gbrain#v0.51.0`), or null for an unpinned or branch spec.
 * With `commits`, a commit pin (`#<sha>`) counts too (GBRA-175).
 */
export function bunGlobalExactTagPin(globalRoot: string, commits = false): string | null {
  try {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- globalRoot is resolveBunGlobalRoot(): Bun's own global install dir from BUN_INSTALL or HOME
    const pkg = JSON.parse(readFileSync(join(globalRoot, 'package.json'), 'utf-8')) as { dependencies?: Record<string, string> };
    const spec = pkg.dependencies?.gbrain;
    if (typeof spec !== 'string') return null;
    return /#v?\d+\.\d+(\.\d+)*$/.test(spec.trim()) || (commits && /#[0-9a-f]{7,40}$/.test(spec.trim())) ? spec.trim() : null;
  } catch {
    return null;
  }
}

function isBunGlobalRoot(dir: string): boolean {
  return existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'node_modules'));
}

function findBunInstallRootFromArgv(): string | null {
  try {
    const argv1 = process.argv[1];
    if (!argv1) return null;

    let dir = dirname(realpathSync(argv1));
    for (let i = 0; i < 10; i++) {
      if (basename(dir) === 'gbrain' && basename(dirname(dir)) === 'node_modules') {
        const root = dirname(dirname(dir));
        if (isBunGlobalRoot(root)) return root;
      }
      const parent = dirname(dir);
      if (parent === dir) break;
      dir = parent;
    }
    return null;
  } catch {
    return null;
  }
}

function verifyUpgrade(): string {
  try {
    const output = execSync('gbrain --version', { encoding: 'utf-8', timeout: 10_000 }).trim();
    return output.replace(/^gbrain\s*/i, '').trim();
  } catch {
    return '';
  }
}

/**
 * Append a structured record to ~/.gbrain/upgrade-errors.jsonl when a
 * best-effort phase of the upgrade fails (e.g., `gbrain post-upgrade`
 * silently bombing). Without this trail, users end up with half-upgraded
 * brains and no signal. `gbrain doctor` reads this file and surfaces the
 * paste-ready recovery hint. Failures here are themselves best-effort.
 */
export function recordUpgradeError(record: {
  phase: string;
  fromVersion: string;
  toVersion: string;
  error: string;
  /** The paste-ready recovery step doctor shows (the record's `hint` field). */
  recover: string;
}): void {
  try {
    const dir = gbrainPath();
    mkdirSync(dir, { recursive: true });
    const path = join(dir, 'upgrade-errors.jsonl');
    const line = JSON.stringify({
      ts: new Date().toISOString(),
      phase: record.phase,
      from_version: record.fromVersion,
      to_version: record.toVersion,
      error: record.error,
      hint: record.recover,
    }) + '\n';
    appendFileSync(path, line);
  } catch {
    // Recording errors is itself best-effort. The user will still see the
    // underlying failure in stdout/stderr from the original command.
  }
}

function saveUpgradeState(oldVersion: string, newVersion: string) {
  try {
    const dir = gbrainPath();
    mkdirSync(dir, { recursive: true });
    const statePath = join(dir, 'upgrade-state.json');
    const state: Record<string, unknown> = existsSync(statePath)
      ? JSON.parse(readFileSync(statePath, 'utf-8'))
      : {};
    state.last_upgrade = {
      from: oldVersion,
      to: newVersion,
      ts: new Date().toISOString(),
    };
    writeFileSync(statePath, JSON.stringify(state, null, 2));
  } catch {
    // best-effort
  }
}

/**
 * Post-upgrade feature discovery + migration application.
 *
 * Two responsibilities:
 *   1. Print feature_pitch headlines for migrations newer than the prior
 *      binary (cosmetic; runs only when upgrade-state.json is readable and
 *      has a from/to pair).
 *   2. Invoke `gbrain apply-migrations --yes` so the mechanical side of
 *      every outstanding migration actually executes (schema, smoke, prefs,
 *      host rewrites, autopilot install). This is the Codex H8 fix:
 *      previously runPostUpgrade early-returned when upgrade-state.json
 *      was missing, which meant every broken-v0.11.0 install stayed broken.
 *      apply-migrations now runs unconditionally (idempotent; cheap when
 *      nothing is pending).
 *
 * Migration enumeration uses the TS registry at
 * src/commands/migrations/index.ts (Codex K) — no filesystem walk of
 * skills/migrations/*.md, so compiled binaries see the same set source
 * installs do.
 */
/**
 * The search-mode banner for a brain that never chose a mode (copy: core/search/mode-advice.ts).
 */
export async function printSearchModeUpgradeBanner(engine: BrainEngine): Promise<void> {
  // One-shot: fires at most once per install (state persisted via `search.mode_upgrade_notice_shown`).
  // A brain with no search.mode resolves to the default (balanced); the banner says so and relays the matrix.
  try {
    const shown = await engine.getConfig('search.mode_upgrade_notice_shown');
    const existingMode = await engine.getConfig('search.mode');
    if (shown !== 'true' && !existingMode) {
      await printSearchModeBanner();
      await engine.setConfig('search.mode_upgrade_notice_shown', 'true');
    }
  } catch {
    // Banner is cosmetic; never block the upgrade.
  }
}

/**
 * v0.42 self-upgrade setup (file plane; idempotent). Default existing installs
 * to `notify` (a nudge, not autonomy — `auto` stays an explicit opt-in), show a
 * one-time informational banner, and rewrite an existing autopilot systemd unit
 * to Restart=always so the silent channel's exit-for-relaunch respawns.
 */
async function applySelfUpgradeSetup(noAutopilotInstall: boolean): Promise<void> {
  try {
    const { loadConfig, saveConfig } = await import('../core/config.ts');
    const cfg = loadConfig();
    if (cfg) {
      const su = cfg.self_upgrade ?? {};
      let changed = false;
      if (su.mode === undefined) {
        su.mode = 'notify';
        changed = true;
      }
      if (!su.mode_prompted) {
        console.log('');
        console.log('═══════════════════════════════════════════════════════════════');
        console.log('[gbrain] Self-upgrade is ON in NOTIFY mode.');
        console.log('[gbrain] Every gbrain invocation now checks for new versions and');
        console.log('[gbrain] nudges when one is available. Apply with: gbrain self-upgrade');
        console.log('[gbrain]');
        console.log('[gbrain] Hands-off (silent quiet-hours auto-upgrade for always-on installs):');
        console.log('[gbrain]   gbrain config set self_upgrade.mode auto');
        console.log('[gbrain] Turn it off entirely: gbrain config set self_upgrade.mode off');
        console.log('═══════════════════════════════════════════════════════════════');
        console.log('');
        su.mode_prompted = true;
        changed = true;
      }
      if (changed) {
        cfg.self_upgrade = su;
        saveConfig(cfg);
      }
    }
  } catch {
    /* best-effort */
  }
  if (noAutopilotInstall) return;
  try {
    const { migrateSystemdUnitToRestartAlways } = await import('./autopilot.ts');
    const r = migrateSystemdUnitToRestartAlways();
    if (r.rewritten) {
      console.log('[gbrain] Updated autopilot systemd unit to Restart=always (self-upgrade relaunch).');
    }
  } catch {
    /* best-effort */
  }
}

export async function runPostUpgrade(args: string[] = []): Promise<void> {
  if (args.includes('--help') || args.includes('-h')) {
    console.log('Usage: gbrain post-upgrade [--no-autopilot-install] [--json]');
    console.log('Prints feature pitches for new migrations and runs apply-migrations.');
    console.log('--no-autopilot-install (or GBRAIN_NO_AUTOPILOT_INSTALL=1) skips autopilot installation and service rewrites.');
    console.log('--json prints one result document on stdout (progress and banners go to stderr).');
    console.log('Idempotent — safe to re-run any time.');
    return;
  }
  // D2: under --json the human lines go to stderr (the guard) and this report is the one document.
  const json = jsonRequested(args);
  const report: PostUpgradeReport = { status: 'ok', warnings: [] };

  // v0.35.8.0: lay down ~/.gbrain/.gitignore retroactively. Existing users
  // never re-run `gbrain init`, so init-only coverage misses them entirely
  // (codex F-CDX-8). Idempotent + non-clobbering — safe to run every upgrade.
  try {
    const { ensureGitignore } = await import('../core/config.ts');
    ensureGitignore();
  } catch { /* Best-effort hygiene; never block upgrade. */ }

  // v0.42 self-upgrade setup: default existing installs to NOTIFY (a nudge, no
  // autonomy), inform once, and rewrite an existing systemd unit to
  // Restart=always so the silent channel's exit-for-relaunch respawns. All
  // file-plane + mechanical + idempotent; never blocks the upgrade.
  const noAutopilotInstall = args.includes('--no-autopilot-install') || process.env.GBRAIN_NO_AUTOPILOT_INSTALL === '1';
  await applySelfUpgradeSetup(noAutopilotInstall);
  // Cosmetic: print feature pitches for migrations newer than the prior binary.
  try {
    const statePath = gbrainPath('upgrade-state.json');
    if (existsSync(statePath)) {
      const state = JSON.parse(readFileSync(statePath, 'utf-8'));
      const from = state?.last_upgrade?.from;
      if (from) {
        const summary = (await import('../core/upgrade-summary.ts')).upgradeSummary(from);
        if (summary) console.log(['', ...summary, ''].join('\n'));
        const { migrations } = await import('./migrations/index.ts');
        for (const m of migrations) {
          if (isNewerThan(m.version, from)) {
            console.log('');
            console.log(`NEW: ${m.featurePitch.headline}`);
            if (m.featurePitch.description) console.log(m.featurePitch.description);
            if (m.featurePitch.recipe) {
              console.log(`Run \`gbrain integrations show ${m.featurePitch.recipe}\` to set it up.`);
            }
            console.log('');
          }
        }
      }
    }
  } catch {
    // Pitch printing is cosmetic — don't gate migrations on it.
  }

  (await import('../core/setup/brain-first-upgrade-notice.ts')).printBrainFirstUpgradeNotice(); // GBRA-188: the command that writes a missing brain-first block
  await (await import('../core/setup/hook-launcher-refresh.ts')).refreshHookLaunchers(); // #8424: hooks that start gbrain in the session's directory move onto the launcher
  (await import('../core/post-upgrade-notice.ts')).writePostUpgradeCliNotice(); // F7: safety notice ([AGENT] block for agents)
  // Mechanical: run every outstanding migration. Idempotent; exits 0 quickly
  // when nothing is pending. Stays inside the same process so a long Phase F
  // (autopilot install) doesn't hit a subprocess boundary.
  try {
    const { applyMigrations } = await import('./apply-migrations.ts');
    const { exitCode, failure } = await applyMigrations(['--yes', '--non-interactive', ...(noAutopilotInstall ? ['--no-autopilot-install'] : [])]);
    report.apply_migrations = { exit_code: exitCode ?? 0 };
    // A failure, a consent refusal (3) or a held migration lock (75) ends
    // post-upgrade here. 0 ("all migrations up to date", the common case on
    // an upgrade with no new orchestrator migration) continues: the schema
    // pass, banners, prompts and recovery checks below still run.
    if (exitCode !== undefined && exitCode !== 0) process.exit(finishPostUpgrade(json, report, exitCode, failure));
  } catch (e) {
    // Surface the error but don't throw — post-upgrade is best-effort.
    // Users can re-run `gbrain apply-migrations` manually if they want
    // to retry.
    const msg = e instanceof Error ? e.message : String(e);
    console.error(`\napply-migrations failed: ${msg}`);
    console.error('Run `gbrain apply-migrations --yes` manually to retry.');
    report.warnings.push(`apply-migrations failed: ${msg}`);
  }

  // v0.28.5 (X1): explicitly apply pending schema migrations.
  // Since #3085, apply-migrations --yes applies schema-version drift itself
  // (it previously only WARNed), so the in-process call above may have
  // already run these — runMigrations is idempotent, making this hook a
  // harmless second pass. It stays because it also covers paths where the
  // preflight was skipped. We've shipped 11 wedge incidents asking users to
  // read warnings; keep the loop closed here.
  // A1's hasPendingMigrations probe in connectEngine is belt-and-suspenders
  // for any path that bypasses upgrade (autopilot, direct CLI on stale brain).
  try {
    const { loadConfig: lcSchema, toEngineConfig: toCfgSchema } = await import('../core/config.ts');
    const { createEngine } = await import('../core/engine-factory.ts');
    const cfgSchema = lcSchema();
    if (cfgSchema) {
      const engine = await createEngine(toCfgSchema(cfgSchema));
      try {
        await engine.connect(toCfgSchema(cfgSchema));
        await engine.initSchema();
        console.log('  Schema up to date.');
        report.schema = 'up_to_date';

        // v0.32.3 search-lite mode banner (one-shot, `search.mode_upgrade_notice_shown`).
        await printSearchModeUpgradeBanner(engine);

        // #5876: auto_chronicle now defaults on; one-shot [AGENT] cost + opt-out notice, best-effort.
        await (await import('../core/chronicle/upgrade-notice.ts')).printAutoChronicleUpgradeNotice(engine);
        await (await import('../core/feedback/upgrade-notice.ts')).printRetrievalFeedbackUpgradeNotice(engine);
        // Entity mention index: [AGENT] catch-up line while pages are due (best-effort).
        await (await import('../core/mentions/upgrade-notice.ts')).printMentionIndexUpgradeNotice(engine);
        await (await import('../core/page-state/projection-upgrade-notice.ts')).printProjectionUpgradeNotice(engine); // #6803 image projections: read-only [AGENT] drain preview
        // Large pages: re-index pages an older gbrain stored chunkless for size (keyless-safe, time-boxed, resumable).
        await (await import('../core/oversized-backfill.ts')).printOversizedBackfillUpgradeNotice(engine);

        // Temporal typed edges: one-shot [AGENT] notice (live-by-default graph reads + relationship check), best-effort.
        await (await import('../core/temporal-edges-upgrade-notice.ts')).printTemporalEdgesUpgradeNotice(engine);
        // #5575 memory trust: [AGENT] ask_user while unclaimed sources hold legacy rows; never claims or scans (best-effort).
        await (await import('../core/trust/claim-notice.ts')).printTrustClaimUpgradeNotice(engine);
        await (await import('../core/access/requester-scope.ts')).printUnscopedReadsUpgradeNotice(engine); // GST-363: credentials bound to nobody on a several-people brain
        await (await import('../core/access/open-pages.ts')).printOpenPagesUpgradeNotice(engine); // GST-2670: open DM, chat and mail pages on a several-people brain

        // Ambient-writeback consent ask (WP8): one-shot for EXISTING installs
        // upgrading into the feature. Personal brains only; double-gated on
        // its own sentinel + the setting being unset; [AGENT]-relayed;
        // never auto-enables; its own try/catch lives inside.
        {
          const { runWritebackNudge } = await import('../core/onboard/writeback-nudge.ts');
          await runWritebackNudge(engine, { context: 'post-upgrade' });
        }

        // Waiting-TTL pre-notice (one-shot, warn-before-act). The worker
        // gates its first sweep behind the SAME flag via runWaitingTtlTick
        // (notice → grace window → sweep) because daemon restarts never run
        // this CLI path — this banner is the interactive channel. Stamping
        // the ISO timestamp here starts the same grace clock, so an operator
        // who sees this banner gets the full window to tune before anything
        // is cancelled.
        try {
          const { admissionKilled, resolveTtlNames, countTtlExpiredWaiting, ttlNoticeGraceMs, TTL_NOTICE_SHOWN_KEY } =
            await import('../core/minions/admission.ts');
          const shown = await engine.getConfig(TTL_NOTICE_SHOWN_KEY);
          if ((shown == null || shown.trim() === '') && !admissionKilled()) {
            const ttlNames = await resolveTtlNames(engine);
            const { total: affected, by_name } = await countTtlExpiredWaiting(engine, ttlNames);
            const parts = [...ttlNames].map(([name, hours]) => `${name} > ${hours}h: ${by_name[name] ?? 0}`);
            console.log('');
            console.log(`⚠ [gbrain] Waiting-TTL is now active: queued jobs that never get claimed are`);
            console.log(`  cancelled after their per-type TTL (${parts.join('; ') || 'defaults'}).`);
            if (affected > 0) {
              console.log(`  ${affected} currently-queued job(s) already exceed their TTL and will be`);
              console.log(`  cancelled after a ${Math.round(ttlNoticeGraceMs() / 60_000)}min grace window`);
              console.log(`  (auditable error_text; visible in 'gbrain jobs stats').`);
            }
            console.log(`  Tune or disable: gbrain config set minions.ttl_waiting_hours.<name> <hours|0>`);
            console.log('');
            await engine.setConfig(TTL_NOTICE_SHOWN_KEY, new Date().toISOString());
          }
        } catch {
          // Banner is cosmetic; never block the upgrade.
        }

        // PR1: skill-catalog publish consent. New installs default ON at
        // `gbrain init`; EXISTING installs stay OFF (default-OFF runtime = no
        // silent capability grant on upgrade) until the owner opts in HERE.
        // One-time, gated by `mcp.publish_skills_prompted`. Strongly recommended.
        try {
          const prompted = await engine.getConfig('mcp.publish_skills_prompted');
          const { loadConfigFileOnly } = await import('../core/config.ts');
          const filePublication = loadConfigFileOnly()?.mcp?.publish_skills;
          const current = await engine.getConfig('mcp.publish_skills') ?? (filePublication == null ? null : String(filePublication));
          if (prompted !== 'true' && current == null) {
            const sources = await engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE NOT archived AND local_path IS NOT NULL');
            const dirLine = sources.length
              ? `${sources.length} registered content source(s); shared skills require reviewed source-local publication.`
              : 'No registered content root: choose a canonical source and complete host content migration first.';
            console.log('');
            console.log('═══════════════════════════════════════════════════════════════');
            console.log('[gbrain] Publish your skills to MCP clients?');
            console.log('[gbrain] Codex desktop, Claude Code/Cowork, and Perplexity can then');
            console.log('[gbrain] DISCOVER approved source-scoped skill prose over `gbrain serve`.');
            console.log('[gbrain] This makes your MCP server dramatically more useful.');
            console.log('[gbrain]');
            console.log(`[gbrain] ${dirLine}`);
            console.log('[gbrain] Effect: the CONTENTS of your SKILL.md files become readable by');
            console.log('[gbrain] remote MCP callers you have authorized. Source code is NOT exposed.');
            console.log('[gbrain] Following updates, bundle bytes and skill editing require separate approval.');
            console.log('═══════════════════════════════════════════════════════════════');
            const { isInteractive } = await import('../core/interaction.ts');
            const isTty = isInteractive();
            let enabled = false;
            if (isTty) {
              enabled = await promptEnableSkillPublishing();
            } else {
              console.log('[AGENT] Relay this to your operator. Recommended: enable it.');
              console.log('[AGENT] Enable with: gbrain config set mcp.publish_skills true');
            }
            if (enabled) {
              await engine.setConfig('mcp.publish_skills', 'true');
              console.log('[gbrain] Skill publishing ENABLED. Disable anytime: gbrain config set mcp.publish_skills false');
            } else if (isTty) {
              console.log('[gbrain] Left disabled. Enable later: gbrain config set mcp.publish_skills true');
            }
            await engine.setConfig('mcp.publish_skills_prompted', 'true');
          }
        } catch {
          // Consent prompt is best-effort; never block the upgrade.
        }

        // v0.32.7 CJK wave: chunker-version bump → re-embed sweep.
        // Idempotent — `runReindex` short-circuits when no pages are pending.
        // A managed brain refuses the markdown reindex; name its drain instead.
        try {
          const { managedPersistenceEnabled } = await import('../core/persistence/ownership.ts');
          const managed = await managedPersistenceEnabled(engine);
          if (!managed) {
            const { runPostUpgradeReembedPrompt } = await import('../core/post-upgrade-reembed.ts');
            const { getEmbeddingModel } = await import('../core/ai/gateway.ts');
            let modelString = 'openai:text-embedding-3-large';
            try { modelString = getEmbeddingModel(); } catch { /* gateway not configured — keep default */ }
            const promptResult = await runPostUpgradeReembedPrompt(engine, modelString);
            if (promptResult.proceeded) {
              const { runReindex } = await import('./reindex.ts');
              await runReindex(engine, ['--markdown'], { authorized: true }); // the TTY yes above is the consent
            }
          }
        } catch (re) {
          const msg = re instanceof Error ? re.message : String(re);
          console.warn(`\nChunker-bump reindex skipped: ${msg}`);
          report.warnings.push(`chunker-bump reindex skipped: ${msg}`);
          console.warn('Run `gbrain reindex --markdown` manually when ready.');
        }

        // Fix wave 3: run the wave checks once (full, not --fast) and relay a
        // preview-only recovery banner; applying stays the user's decision.
        try {
          const { postUpgradeRecoveryBanner } = await import('./doctor/upgrade-banner.ts');
          const [brain] = await engine.executeRaw<{ brain_id: string }>('SELECT brain_id FROM persistence_brain WHERE singleton=1').catch(() => []);
          for (const line of await postUpgradeRecoveryBanner(engine, `host (${engine.kind}${brain ? `, id ${brain.brain_id}` : ''})`)) console.log(line);
        } catch (be) {
          console.warn(`\nRecovery checks skipped: ${be instanceof Error ? be.message : String(be)}. Run \`gbrain doctor --remediation-plan\` to preview.`);
        }
      } finally {
        try { await engine.disconnect(); } catch { /* best-effort */ }
      }
    }
  } catch (e) {
    // Non-fatal: connection or DDL failure here falls back to the existing
    // user-facing WARN. apply-migrations.ts:296-302 already surfaces the
    // hint to run `gbrain init --migrate-only`.
    const msg = e instanceof Error ? e.message : String(e);
    console.warn(`\nSchema auto-apply skipped: ${msg}`);
    report.schema = 'skipped';
    report.warnings.push(`schema auto-apply skipped: ${msg}`);
    if ((e as { code?: unknown }).code !== 'client_behind') console.warn('Run `gbrain init --migrate-only` manually if your brain is wedged.');
  }

  // v0.25.1: agent-readable advisory listing recommended skills the
  // workspace hasn't installed yet. No-op when everything is installed.
  try {
    const { printAdvisoryIfRecommended } = await import('../core/skillpack/post-install-advisory.ts');
    const { VERSION } = await import('../version.ts');
    printAdvisoryIfRecommended({ version: VERSION, context: 'upgrade' });
  } catch {
    // Best-effort cosmetic surface; never block post-upgrade.
  }

  // v0.36 DX: skillpack reference sweep. After an upgrade, the gbrain bundle
  // may have shipped changes to scaffolded skills the host already has on
  // disk. Run `reference --all` automatically and print a one-line-per-skill
  // summary so the agent + operator see what drifted without manually
  // running the sweep. Skipped silently when:
  //   - GBRAIN_SKIP_REFERENCE_SWEEP=1 in env
  //   - no target workspace can be auto-detected (gbrain installed but
  //     never scaffolded anywhere)
  //   - the detected workspace IS the gbrain repo (dev-mode, would just
  //     compare gbrain against itself)
  //   - every scaffolded skill is identical (nothing to say)
  await postUpgradeReferenceSweep();

  // v0.41.18.0 (A4 + A18, T14): post-upgrade onboard banner. Fail-open;
  // doesn't engine-connect (lightweight TTY check only). The actual
  // recommendations need engine access via `gbrain onboard --check`;
  // the banner just nudges the user to run it.
  try {
    const { runUpgradeBanner } = await import('../core/onboard/init-nudge.ts');
    // The banner doesn't actually use the engine today; passing null-equivalent
    // would require a type widening. Skip the engine arg and let the banner
    // print the static nudge text.
    await runUpgradeBanner(null as never);
  } catch {
    // Fail-open per A18: never crash post-upgrade from the banner.
  }
  // #6317 (I2): the supervisor's step; bare, so the check inherits its default window.
  (json ? console.error : console.log)(`Next: ${MOVEMENT_SUPERVISOR_STEP}`);
  if (json) await writeJsonDocument(JSON.stringify(report));
}

/** The one-shot search-mode banner post-upgrade prints for a brain with no search.mode (stdout; stderr under --json). */
async function printSearchModeBanner(): Promise<void> {
  const { upgradeBannerLines } = await import('../core/search/mode-advice.ts');
  for (const line of upgradeBannerLines()) console.log(line);
}

interface PostUpgradeReport {
  status: 'ok' | 'failed';
  apply_migrations?: { exit_code: number };
  schema?: 'up_to_date' | 'skipped';
  warnings: string[];
}

/**
 * D2: the exit status once apply-migrations ended the run. Success under
 * --json writes the report; a failure (apply-migrations already printed its
 * human lines) is one envelope leading with the report's keys.
 */
function finishPostUpgrade(json: boolean, report: PostUpgradeReport, exitCode: number, failure?: OperationError): number {
  if (exitCode === 0) {
    if (json) void writeJsonDocument(JSON.stringify(report));
    return 0;
  }
  report.status = 'failed';
  if (!json) return exitCode;
  const e = failure ?? opError('migration_failed', `apply-migrations exited with status ${exitCode}.`,
    'Read stderr for the failing migration, fix it, then run `gbrain post-upgrade` again.');
  return writeCliError(e, 'post-upgrade', { json: true, stderr: false, legacy: { ...report } });
}

/**
 * Run `reference --all` against the auto-detected host workspace and print
 * a one-line-per-skill summary of any drift. Best-effort; failures are
 * swallowed so a broken sweep never blocks post-upgrade.
 *
 * Exported (with optional `opts` test seam) for unit testing the gate
 * logic + output shape. Production callers pass no args — both paths are
 * auto-detected.
 */
export async function postUpgradeReferenceSweep(
  opts: { gbrainRoot?: string; targetWorkspace?: string } = {},
): Promise<void> {
  if (process.env.GBRAIN_SKIP_REFERENCE_SWEEP) return;
  try {
    const { autoDetectSkillsDirReadOnly } = await import('../core/repo-root.ts');
    const { findGbrainRoot } = await import('../core/skillpack/bundle.ts');
    const { runReferenceAll } = await import('../core/skillpack/reference.ts');
    const path = await import('path');

    // Allow tests to inject; default to auto-detection.
    let targetWorkspace = opts.targetWorkspace;
    if (!targetWorkspace) {
      const detected = autoDetectSkillsDirReadOnly();
      if (!detected.dir) return;
      targetWorkspace = path.resolve(detected.dir, '..');
    }

    const gbrainRoot = opts.gbrainRoot ?? findGbrainRoot();
    if (!gbrainRoot) return;

    // Dev-mode guard: the detected workspace IS the gbrain repo. Sweeping
    // gbrain against itself is always identical — print nothing.
    if (path.resolve(targetWorkspace) === path.resolve(gbrainRoot)) return;

    const result = runReferenceAll({ gbrainRoot, targetWorkspace });
    // Drifted = skills the host has actually scaffolded that now differ from
    // the bundle (local edits are legitimate — this is advisory).
    const drifted = result.skills.filter(
      s =>
        s.summary.identical + s.summary.differs > 0 &&
        (s.summary.differs > 0 || s.summary.missing > 0),
    );

    // New = skills the host never scaffolded (own body absent). These used to
    // be filtered out as "noise", which meant an upgrade that shipped brand-new
    // skills said nothing about them. Surface them via the currency classifier
    // (own-files aware) so new capability is discoverable — but ONLY for a host
    // that has already scaffolded at least one skill (a skills user missing the
    // new ones). A host with zero scaffolded skills has opted out; surfacing
    // every bundled skill on every upgrade would be exactly the noise the old
    // filter avoided, so it stays silent for them.
    let newSkills: string[] = [];
    try {
      const { computeSkillCurrency } = await import('../core/skillpack/skill-currency.ts');
      const currency = computeSkillCurrency({ gbrainRoot, targetWorkspace });
      const hasScaffolded = currency.counts.current > 0 || currency.counts.drifted > 0;
      if (hasScaffolded) {
        newSkills = currency.skills.filter(s => s.status === 'new').map(s => s.slug);
      }
    } catch {
      // Best-effort; drift report still prints below.
    }

    if (drifted.length === 0 && newSkills.length === 0) return;

    console.log('');
    console.log('Skillpack sweep (post-upgrade):');
    if (newSkills.length > 0) {
      const shown = newSkills.slice(0, 10);
      console.log(
        `  ${newSkills.length} new built-in skill(s) not installed here: ${shown.join(', ')}` +
          (newSkills.length > shown.length ? `, … +${newSkills.length - shown.length} more` : ''),
      );
      console.log('  Add them all: `gbrain skillpack sync`');
    }
    for (const s of drifted) {
      console.log(
        `  ${s.slug.padEnd(40)} differs:${s.summary.differs} missing:${s.summary.missing}`,
      );
    }
    console.log('');
    console.log(
      'New skills → `gbrain skillpack sync`. Drifted skills → `gbrain skillpack reference <slug>` (local edits are yours; nothing is overwritten).\nSee `skills/_AGENT_README.md` for what your agent should do on update.\nSkip this sweep: `GBRAIN_SKIP_REFERENCE_SWEEP=1`.',
    );
  } catch {
    // Best-effort. Never block post-upgrade.
  }
}

// findMigrationsDir + extractFeaturePitch removed in v0.11.1: migration data
// now lives in the TS registry at src/commands/migrations/index.ts so
// compiled binaries don't depend on filesystem skills/migrations/*.md
// (Codex K).

function isNewerThan(version: string, baseline: string): boolean {
  const v = version.split('.').map(Number);
  const b = baseline.split('.').map(Number);
  for (let i = 0; i < 3; i++) {
    if ((v[i] || 0) > (b[i] || 0)) return true;
    if ((v[i] || 0) < (b[i] || 0)) return false;
  }
  return false;
}

export function detectInstallMethod(): 'bun' | 'bun-link' | 'binary' | 'unknown' {
  const execPath = process.execPath || '';

  // v0.28.5 cluster D: bun-link signal first.
  // bun link puts a symlink at ~/.bun/bin/gbrain → either the source's bin
  // entry (compiled CLI) OR src/cli.ts directly. Either way, realpath
  // resolves into a directory we can walk up from to find a .git/config
  // pointing at our repo.
  const bunLinkResult = detectBunLink();
  if (bunLinkResult) return 'bun-link';

  // Check if running from node_modules (bun/npm install). Could be canonical
  // (we publish under garrytan/gbrain) OR the squatter (npm `[email protected]`).
  // Sub-classify and warn loudly on suspect installs (#658).
  if (execPath.includes('node_modules') || process.argv[1]?.includes('node_modules')) {
    const verdict = classifyBunInstall();
    if (verdict === 'suspect') {
      printSquatterRecovery();
    }
    return 'bun';
  }

  // A compiled binary runs from Bun's virtual entrypoint whatever its file is
  // named, so a release asset run as gbrain-linux-x64 is still the binary.
  if (execPath.endsWith('/gbrain') || execPath.endsWith('\\gbrain.exe') || /^(\/\$bunfs\/|[A-Za-z]:[\\/]~BUN[\\/])/.test(process.argv[1] ?? '')) {
    return 'binary';
  }

  // #8464: never `clawhub update gbrain`. We publish no gbrain skill on ClawHub, and that
  // command installs whatever skill anyone else publishes under the name.
  return 'unknown';
}

/**
 * Detect bun-link source-clone installs (closes #656, fixes #368).
 *
 * Walk up from argv[1] looking for a `.git/config` whose remote url
 * contains `garrytan/gbrain` (case-insensitive substring).
 *
 * v0.28.5 gated on lstatSync(argv1).isSymbolicLink(), but bun resolves
 * the entire symlink chain before setting process.argv[1], so the check
 * always returned false and short-circuited detection. Now we skip the
 * symlink check and use argv[1] directly — it is already the real path
 * inside the checkout, which is exactly what the git-config walk needs.
 *
 * Returns { repoRoot } when confident; null otherwise (caller falls
 * through to the existing detection chain).
 */
export function detectBunLink(): { repoRoot: string } | null {
  try {
    const argv1 = process.argv[1];
    if (!argv1) return null;

    let dir = dirname(resolve(argv1));
    for (let i = 0; i < 6; i++) {
      const gitConfigPath = join(dir, '.git', 'config');
      if (existsSync(gitConfigPath)) {
        try {
          const cfg = readFileSync(gitConfigPath, 'utf-8');
          if (cfg.toLowerCase().includes(GBRAIN_GITHUB_REPO.toLowerCase())) {
            return { repoRoot: dir };
          }
        } catch { /* unreadable config — not our case */ }
        return null;
      }
      const parent = dirname(dir);
      if (parent === dir) break;
      dir = parent;
    }
    return null;
  } catch {
    return null;
  }
}

/**
 * v0.28.5 cluster D, signal 2 — bun install authenticity check (closes #658).
 *
 * When `bun add -g gbrain` (or `npm install -g gbrain`) installs from
 * npm, the package is the squatter — an unrelated `[email protected]` that
 * silently overwrites our binary. This function reads the install
 * directory's package.json and checks two non-spoofable signals:
 *   - `repository.url` contains `garrytan/gbrain` (case-insensitive)
 *   - the install dir contains a `src/cli.ts` file (squatter ships
 *     compiled binary, not source)
 *
 * If neither matches, returns 'suspect' and the caller surfaces a loud
 * recovery message. Codex's plan-review noted these signals are spoofable
 * by a determined squatter — accepted; this is best-effort warning, not
 * an assertion. The right structural fix is publishing under a scoped
 * name like `@garrytan/gbrain` (tracked v0.29 follow-up).
 */
function classifyBunInstall(): 'canonical' | 'suspect' {
  try {
    const argv1 = process.argv[1];
    if (!argv1) return 'suspect';

    // Walk up from argv1 looking for the package.json that owns this install.
    let dir = dirname(realpathSync(argv1));
    for (let i = 0; i < 6; i++) {
      const pkgPath = join(dir, 'package.json');
      if (existsSync(pkgPath)) {
        try {
          const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
          const repoUrl = (typeof pkg.repository === 'string'
            ? pkg.repository
            : pkg.repository?.url) ?? '';
          if (repoUrl.toLowerCase().includes(GBRAIN_GITHUB_REPO.toLowerCase())) {
            return 'canonical';
          }
          // Source-marker fallback: our published-as-source install always
          // ships src/cli.ts next to package.json. The squatter ships dist/.
          if (existsSync(join(dir, 'src', 'cli.ts'))) {
            return 'canonical';
          }
          return 'suspect';
        } catch {
          return 'suspect';
        }
      }
      const parent = dirname(dir);
      if (parent === dir) break;
      dir = parent;
    }
    return 'suspect';
  } catch {
    return 'suspect';
  }
}

function printSquatterRecovery(): void {
  console.warn('');
  console.warn('  WARNING: gbrain install does not appear to be from garrytan/gbrain.');
  console.warn('  This is likely the npm-name collision tracked in issue #658:');
  console.warn('    https://www.npmjs.com/package/gbrain (an unrelated package).');
  console.warn('');
  console.warn('  Recovery options:');
  console.warn('    1. Install from source:');
  console.warn('         bun remove -g gbrain');
  console.warn('         git clone https://github.com/garrytan/gbrain.git');
  console.warn('         cd gbrain && bun install && bun link');
  console.warn('');
  console.warn('    2. Download a release binary:');
  console.warn('         https://github.com/garrytan/gbrain/releases');
  console.warn('');
  console.warn('  See docs/INSTALL_FOR_AGENTS.md for the canonical install paths.');
  console.warn('');
}

/**
 * The one-time "Enable skill publishing now? (recommended) [Y/n]" prompt
 * (#4318 residual). Default yes: an empty line (Enter), `y` or `yes`
 * accepts; anything else, EOF, the prompt timeout or a non-interactive
 * caller declines (A5: never hang on a silent stdin). Seams for tests.
 */
export async function promptEnableSkillPublishing(
  opts: { input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream; probe?: InteractiveProbe; timeoutMs?: number } = {},
): Promise<boolean> {
  const { readLine } = await import('../core/interaction.ts');
  const answer = await readLine({ prompt: '[gbrain] Enable skill publishing now? (recommended) [Y/n] ', ...opts });
  if (answer.kind !== 'line') return false;
  const a = answer.text.toLowerCase();
  return a === '' || a === 'y' || a === 'yes';
}