Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
31.8 KB
Raw Blame
/**
 * GBRA-175: the host side of the upgrade restart (src/core/upgrade-restart.ts
 * holds the pure planning and verification). `gbrain upgrade` calls
 * `preflightHostRestart` before it installs anything, so a process it could
 * not restart refuses the upgrade instead of leaving two builds running, and
 * the new build runs `gbrain upgrade --restart-only` after the swap, which
 * calls `runHostRestart`. `--restart-only` on its own restarts every process
 * onto the build already installed (doctor's `runtime_build_skew` fix);
 * `--dry-run` prints the plan and changes nothing.
 */
import { existsSync, mkdirSync, readFileSync, readlinkSync, realpathSync, statSync, writeFileSync } from 'node:fs';
import { homedir } from 'node:os';
import { delimiter, dirname, isAbsolute, join } from 'node:path';
import { spawn, spawnSync } from '../core/spawn.ts';
import { gbrainPath, isThinClient, loadConfig, toEngineConfig } from '../core/config.ts';
import { opError } from '../core/ops/contract.ts';
import type { Action } from '../core/agent-output.ts';
import { writeCliError } from '../cli/cli-error.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { SERVE_LAUNCHD_LABEL, SERVE_SYSTEMD_UNIT, serveServiceRestartArgv, serveServiceRunsWrapper } from '../core/serve-service.ts';
import { autopilotLockPath, resolveAutopilotJob } from '../core/autopilot-paths.ts';
import { cronLineBelongsToBrain, plistPath, scriptWrapperPath, systemdUnitPath } from './autopilot/jobs.ts';
import { readSupervisorBuild, readSupervisorPid } from '../core/minions/supervisor-pid.ts';
import { parseEtimeToMs, readWorkers } from '../core/minions/worker-registry.ts';
import { installedVersion, runtimeInstallRoot } from '../core/runtime-build.ts';
import { VERSION } from '../version.ts';
import { compareWriterVersions } from '../core/persistence/writer-versions.ts';
import { resolveQuietHoursWindow, resolveSelfUpgradeMode } from '../core/self-upgrade.ts';
import { evaluateQuietHours } from '../core/minions/quiet-hours.ts';
import { logSelfUpgrade } from '../core/audit/self-upgrade-audit.ts';
import {
  classifyGbrainCommand, collectHostProcesses, copyFix, gbrainEntry, launcherName, mismatchedBuilds, PENDING_BUILD, planRestart, runRestartSteps, verifyRestart,
  type AutopilotLauncher, type HostProcess, type ProcessSources, type ProcessTableRow, type RestartExecutor, type RestartPlan, type ServiceHandle, type WarmSocketState,
} from '../core/upgrade-restart.ts';

const DOCS = 'docs/guides/upgrades-auto-update.md#restart';
const DRY_RUN_VERIFY = ['gbrain', 'upgrade', '--restart-only', '--dry-run', '--json'];
const VERIFY_TIMEOUT_MS = 180_000;
const VERIFY_POLL_MS = 2_000;
/** #8776: how long verification waits for a launcher to start autopilot again: gbrain's cron line runs every 5 minutes. */
const HANDOFF_WAIT_MS = 360_000;

const brainHome = () => process.env.GBRAIN_HOME?.trim() || homedir();

/** The GBRAIN_HOME (else HOME) in a process's environment; undefined when it cannot be read (only Linux exposes it). */
function processHome(pid: number): string | null | undefined {
  try {
    const vars = readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0');
    const get = (name: string) => vars.find(v => v.startsWith(`${name}=`))?.slice(name.length + 1).trim() || null;
    return get('GBRAIN_HOME') ?? get('HOME');
  } catch {
    return undefined;
  }
}

/** A process's working directory, which a relative entry point resolves against; null when it cannot be read (only Linux exposes it). */
function processCwd(pid: number): string | null {
  try { return readlinkSync(`/proc/${pid}/cwd`); } catch { return null; }
}

/** The package name at a directory; undefined when it holds no readable package.json. */
function packageNameAt(root: string): string | null | undefined {
  try {
    const name = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { name?: unknown }).name;
    return typeof name === 'string' ? name : null;
  } catch {
    return undefined;
  }
}

/** This user's processes from `ps` (Linux and macOS), or the given pids; null when ps cannot run. */
function readProcessTable(uid: number | undefined, pids?: number[]): ProcessTableRow[] | null {
  const select = pids ? ['-p', pids.join(',')] : uid === undefined ? ['-x'] : ['-U', String(uid)];
  const run = spawnSync('ps', [...select, '-ww', '-o', 'pid=,ppid=,etime=,command='], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] });
  if (typeof run.stdout !== 'string' || (run.status !== 0 && !(pids && run.status === 1))) return null;
  const now = Date.now();
  return run.stdout.split('\n').flatMap(line => {
    const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
    if (!m) return [];
    const elapsed = parseEtimeToMs(m[3]!);
    const pid = Number(m[1]);
    return [{ pid, ppid: Number(m[2]), command: m[4]!, started_ms: elapsed === null ? null : now - elapsed, gbrain_home: processHome(pid), cwd: processCwd(pid) }];
  });
}

/** The gbrain install a command line starts from: the package directory above its entry point and the version it holds now (null for a compiled binary). */
function installOf(command: string, cwd?: string | null): { root: string | null; version: string | null } {
  const entry = gbrainEntry(command, { cwd, packageName: packageNameAt })?.entry;
  if (!entry) return { root: null, version: null };
  try {
    const found = entry.includes('/') ? (isAbsolute(entry) ? entry : undefined) : (process.env.PATH ?? '').split(delimiter).map(dir => join(dir, entry)).find(path => existsSync(path));
    if (!found) return { root: null, version: null };
    let dir = dirname(realpathSync(found));
    for (let i = 0; i < 4; i++, dir = dirname(dir)) {
      const version = installedVersion(dir);
      if (version) return { root: dir, version };
    }
  } catch { /* unknown */ }
  return { root: null, version: null };
}

/** The pid a service manager runs for a unit or label now; null when it is not running or cannot be read. */
function servicePid(platform: string, unit: string, launchdLabel: string): number | null {
  const r = platform === 'darwin' ? spawnSync('launchctl', ['list', launchdLabel], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] })
    : spawnSync('systemctl', ['--user', 'show', '-p', 'MainPID', unit], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] });
  if (r.status !== 0 || typeof r.stdout !== 'string') return null;
  const pid = Number((platform === 'darwin' ? /"PID"\s*=\s*(\d+)/ : /^MainPID=(\d+)/m).exec(r.stdout)?.[1]);
  return Number.isInteger(pid) && pid > 1 ? pid : null;
}

/** The services this brain installed on this host: each one's restart command and the pid its manager runs. */
export function hostServices(platform: string = process.platform, home: string = homedir(), uid: number = process.getuid?.() ?? 501): { serve: ServiceHandle | null; autopilot: ServiceHandle | null } {
  const job = resolveAutopilotJob();
  const autopilot = platform === 'darwin' && existsSync(plistPath(job.launchdLabel)) ? ['launchctl', 'kickstart', '-k', `gui/${uid}/${job.launchdLabel}`]
    : platform === 'linux' && existsSync(systemdUnitPath(job.systemdUnit)) ? ['systemctl', '--user', 'restart', job.systemdUnit] : null;
  const serve = serveServiceRestartArgv({ platform, home, uid });
  return {
    serve: serve ? { argv: serve, pid: servicePid(platform, SERVE_SYSTEMD_UNIT, SERVE_LAUNCHD_LABEL) } : null,
    autopilot: autopilot ? { argv: autopilot, pid: servicePid(platform, job.systemdUnit, job.launchdLabel) } : null,
  };
}

function readCrontab(): string | null {
  if (process.platform === 'win32') return null;
  const r = spawnSync('crontab', ['-l'], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] });
  return r.status === 0 && typeof r.stdout === 'string' ? r.stdout : null;
}

/**
 * #8776: what starts autopilot again when it exits, for an autopilot launchd or systemd does not run: this brain's own
 * gbrain cron line (`gbrain autopilot --install` on Linux without a user systemd bus: its wrapper every 5 minutes or more often), else a launcher the operator
 * declared with `self_upgrade.autopilot_launcher external`; null when neither, so the upgrade refuses as before.
 * `pid` is the daemon this brain's autopilot lock names, the only one the hand-off may stop.
 */
export function autopilotLauncher(crontab: () => string | null = readCrontab, declared: string | undefined = loadConfig()?.self_upgrade?.autopilot_launcher,
  lockPid: number | null = readAutopilotLockPid()): AutopilotLauncher | null {
  const job = resolveAutopilotJob();
  const relaunches = (line: string) => /^\*(?:\/[1-5])?\s+\*\s+\*\s+\*\s+\*\s/.test(line.trim()) && scriptWrapperPath(line) !== null && cronLineBelongsToBrain(line, job);
  if (crontab()?.split('\n').some(relaunches)) return { kind: 'cron', wait_ms: HANDOFF_WAIT_MS, pid: lockPid };
  return declared === 'external' ? { kind: 'declared', wait_ms: HANDOFF_WAIT_MS, pid: lockPid } : null;
}

/** The launcher matters only for a running autopilot, so a host without one never reads the crontab. */
export function launcherFor(processes: HostProcess[], launcher: () => AutopilotLauncher | null = autopilotLauncher): AutopilotLauncher | null {
  return processes.some(p => p.role === 'autopilot') ? launcher() : null;
}

function readAutopilotLockPid(): number | null {
  try {
    const pid = Number(readFileSync(autopilotLockPath(), 'utf8').trim());
    return Number.isInteger(pid) && pid > 1 ? pid : null;
  } catch {
    return null;
  }
}

/** The real process sources; `close` releases the database connection the heartbeat read holds (Postgres only, and only with `heartbeats`). */
async function hostSources(withHeartbeats = true): Promise<{ sources: ProcessSources; notes: string[]; close: () => Promise<void>; pidFile: string }> {
  const notes: string[] = [];
  let heartbeats: ProcessSources['heartbeats'] = async () => [];
  let close = async () => {};
  const config = loadConfig();
  if (withHeartbeats && config?.engine === 'postgres' && !isThinClient(config)) {
    try {
      const { createEngine } = await import('../core/engine-factory.ts');
      const { listHostConsumers } = await import('../core/persistence/consumer-heartbeat.ts');
      const { localHostIdentity } = await import('../core/persistence/identity.ts');
      const engine = await createEngine(toEngineConfig(config));
      await engine.connect(toEngineConfig(config));
      const hostId = localHostIdentity().id;
      heartbeats = async () => (await listHostConsumers(engine, hostId)).filter(row => row.liveness === 'live' && !row.self)
        .map(row => ({ pid: row.pid, kind: row.kind, version: row.version || null }));
      close = () => engine.disconnect();
    } catch (error) {
      notes.push(`The consumer heartbeat rows could not be read (${(error as Error).message}); builds come from the PID file, the worker registry and process start times.`);
    }
  }
  const { DEFAULT_PID_FILE } = await import('../core/minions/supervisor.ts');
  const uid = process.getuid?.();
  if (readProcessTable(uid, [process.pid]) === null) notes.push('ps could not run, so processes come from the heartbeat rows, the PID file and the worker registry, and no MCP server is signalled.');
  const sources: ProcessSources = {
    heartbeats,
    supervisor: () => {
      const status = readSupervisorPid(DEFAULT_PID_FILE);
      return status.running && status.pid !== null ? { pid: status.pid, version: readSupervisorBuild(DEFAULT_PID_FILE)?.version ?? null } : null;
    },
    workers: () => { try { return readWorkers(() => null).map(w => ({ pid: w.pid, version: w.version ?? null })); } catch { return []; } },
    processTable: () => readProcessTable(uid),
    install: installOf,
    packageName: packageNameAt,
    home: brainHome(),
    exclude: [process.pid, process.ppid],
  };
  return { sources, notes, close, pidFile: DEFAULT_PID_FILE };
}

/** The real executor for restart steps; `pidFile` is the default supervisor PID file. */
/** Runs restart commands without blocking the event loop (the autopilot daemon keeps its timers and signals); a command still running after `timeoutMs` is killed. */
export function hostExecutor(pidFile: string, timeoutMs = 600_000): RestartExecutor {
  return {
    run: (argv, env) => new Promise(resolve => {
      let output = '';
      let timedOut = false;
      const child = spawn(argv[0]!, argv.slice(1), { stdio: ['ignore', 'pipe', 'pipe'], env: env ? { ...process.env, ...env } : process.env });
      const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeoutMs);
      child.stdout?.on('data', chunk => { output += chunk; });
      child.stderr?.on('data', chunk => { output += chunk; });
      child.on('error', error => { clearTimeout(timer); resolve({ status: null, output: `${output}${error.message}` }); });
      child.on('close', code => {
        clearTimeout(timer);
        resolve({ status: timedOut ? null : code, output: timedOut ? `${output}${argv[0]} timed out after ${Math.round(timeoutMs / 1000)}s` : output });
      });
    }),
    terminate: terminateIfUnchanged,
    supervisorPid: file => { const status = readSupervisorPid(file ?? pidFile); return status.running ? status.pid : null; },
    sleep: ms => new Promise(r => setTimeout(r, ms)),
  };
}

/** SIGTERM pid only while it is still the MCP server or autopilot the plan saw: same role, same start time (ps reports it to the second). */
function terminateIfUnchanged(pid: number, startedMs: number | null, role: 'mcp' | 'autopilot'): 'stopped' | 'gone' | 'changed' {
  const row = readProcessTable(undefined, [pid])?.find(r => r.pid === pid);
  if (!row) return 'gone';
  if (classifyGbrainCommand(row.command, { cwd: row.cwd, packageName: packageNameAt }) !== role || startedMs === null || row.started_ms === null || Math.abs(row.started_ms - startedMs) > 2_000) return 'changed';
  try { process.kill(pid, 'SIGTERM'); return 'stopped'; } catch { return 'gone'; }
}

const describe = (p: Pick<HostProcess, 'role' | 'pid' | 'version'>) => `${p.role} pid ${p.pid} (${p.version ? `v${p.version}` : 'build not recorded'})`;

function describeSteps(plan: RestartPlan): string[] {
  const byPid = new Map(plan.stale.map(p => [p.pid, p]));
  const name = (pid: number) => byPid.has(pid) ? describe(byPid.get(pid)!) : `pid ${pid}`;
  return plan.steps.map(step => step.kind === 'service' ? `${step.pids.map(name).join(', ')}: \`${step.argv.join(' ')}\``
    : step.kind === 'supervisor' ? `${[step.pid, ...step.workers].map(name).join(', ')}: \`${step.stop.join(' ')}\`, then \`${step.start.join(' ')}\``
    : step.kind === 'replace_copy' ? `${step.pids.map(name).join(', ')} run from the Bun global copy at ${step.root} (${step.from ? `v${step.from}` : 'version unknown'}): replace it with v${step.to} (BUN_INSTALL=${step.bun_install}: bun remove -g gbrain, then bun add -g the tag) before the restarts`
    : step.kind === 'handoff' ? `${name(step.pid)}: stop it (SIGTERM drains it); ${launcherName(step.launcher)} starts the installed build again (verified for up to ${Math.round(step.launcher.wait_ms / 60_000)} minutes)`
    : `${name(step.pid)}: stop it (reconnect gbrain in its harness afterwards)`);
}

/** The refusal for a plan with manual steps, or null when every process restarts on its own. */
export function restartRefusal(plan: RestartPlan, rerunArgv: readonly string[], installed: boolean) {
  if (!plan.manual.length) return null;
  const onlyMcp = plan.manual.every(m => m.role === 'mcp');
  const first = plan.manual.find(m => m.role !== 'mcp') ?? plan.manual[0]!;
  const fix: Action = onlyMcp
    ? { ask_user: true, argv: [...rerunArgv.filter(a => a !== '--stop-mcp'), '--stop-mcp'], consent: [], actor: 'agent', requires_exclusive: false, docs: DOCS,
      why: 'Stops each listed MCP server during the restart; its harness starts the installed build when gbrain is reconnected.',
      user_message: `${plan.manual.length} gbrain MCP server(s) started by agent harnesses run on this host (${plan.manual.map(m => `pid ${m.pid}`).join(', ')}). Upgrading leaves them on the old build unless they stop. May the upgrade stop them? Reconnect gbrain in each harness afterwards.`,
      verify: { argv: DRY_RUN_VERIFY } }
    : { argv: first.argv, consent: [], actor: 'user', requires_exclusive: false, docs: DOCS, why: first.instruction, verify: { argv: DRY_RUN_VERIFY } };
  return opError('restart_refused',
    `${plan.manual.length} gbrain process(es) on this host cannot be restarted automatically, so nothing was restarted${installed ? '' : ' and nothing was installed'}: ${plan.manual.map(m => m.instruction).join(' ')}`,
    `Handle each process as listed, then run \`${rerunArgv.join(' ')}\` again; \`gbrain upgrade --no-restart\` installs without restarting (doctor then reports runtime_build_skew).`,
    { fix, docs: DOCS });
}

export interface HostRestartOptions { stopMcp: boolean; json: boolean; rerunArgv: string[] }

/**
 * `gbrain upgrade --restart-only [--dry-run]`. True when this handled the invocation. A `--dry-run` without
 * `--restart-only` is the channel preview (commands/upgrade-channel.ts runUpgradeDryRun), which installs nothing, so it
 * is still never ignored while the upgrade installs for real (#2185).
 */
export async function handleRestartOnly(args: readonly string[], opts: HostRestartOptions): Promise<boolean> {
  const dryRun = args.includes('--dry-run');
  if (args.includes('--restart-only')) {
    await runHostRestart({ ...opts, rerunArgv: ['gbrain', 'upgrade', '--restart-only', ...(opts.stopMcp ? ['--stop-mcp'] : [])], dryRun });
    return true;
  }
  return false;
}

/** The package directory this process loaded its code from (realpath), the install the upgrade replaces. */
function ownInstallRoot(): string | null {
  const root = runtimeInstallRoot();
  try { return root ? realpathSync(root) : null; } catch { return root; }
}

/**
 * GBRA-175: the fix for a process that came back on another build: move the install it runs from onto the target
 * (a Bun global copy is removed and re-added, since a pinned copy keeps its pin through `bun add`), then restart again.
 */
export function mismatchFix(p: HostProcess, expected: string): Action {
  const restart: Action = { argv: ['gbrain', 'upgrade', '--restart-only'], consent: [], actor: 'agent', requires_exclusive: false, docs: DOCS,
    why: 'Restarts every gbrain process onto the installed build and verifies it.', verify: { argv: DRY_RUN_VERIFY } };
  if (!p.install_root) {
    return { argv: DRY_RUN_VERIFY, consent: [], actor: 'agent', requires_exclusive: false, docs: DOCS, verify: { argv: DRY_RUN_VERIFY },
      why: `${p.role} pid ${p.pid} runs another build from an install that could not be located (a compiled binary): reinstall that binary at v${expected} or start the process from this install, then run gbrain upgrade --restart-only.` };
  }
  const fix = copyFix(p.install_root, p.install_version ?? null, expected);
  const envPrefix = Object.entries(fix.env).map(([k, v]) => `${k}=${v}`);
  const chain = fix.argv.reduceRight<Action>((then, argv) => ({ argv: envPrefix.length ? ['env', ...envPrefix, ...argv] : argv, consent: [], actor: 'user', requires_exclusive: false, docs: DOCS,
    why: `${p.role} pid ${p.pid} came back on another build because it runs from ${p.install_root}: ${fix.instruction}.`, then }), restart);
  return { ...chain, ask_user: true, user_message: `${p.role} pid ${p.pid} still runs another gbrain build after the restart: it starts from ${p.install_root}, which holds ${p.install_version ? `v${p.install_version}` : 'an unknown version'}. May I ${fix.instruction}, then restart again?` };
}

/**
 * Before the swap: refuse (exit 3, nothing installed) when a running process could not be restarted afterwards.
 * Returns true when the upgrade may proceed.
 */
export async function preflightHostRestart(opts: HostRestartOptions): Promise<boolean> {
  const { sources, close } = await hostSources();
  try {
    const services = hostServices();
    const processes = await collectHostProcesses(sources);
    const plan = planRestart(processes, { expected: PENDING_BUILD, serveService: services.serve, autopilotService: services.autopilot, stopMcp: opts.stopMcp, ownInstallRoot: ownInstallRoot(), autopilotLauncher: launcherFor(processes) });
    const refusal = restartRefusal(plan, opts.rerunArgv, false);
    if (!refusal) return true;
    setCliExitVerdict(writeCliError(refusal, 'upgrade', { json: opts.json }));
    return false;
  } finally {
    await close();
  }
}

/**
 * #8776, for doctor's `self_upgrade_health`: the plan the next `gbrain upgrade` makes before it installs (the preflight
 * plan), from the process table alone (no database connection). Read-only; null when ps cannot run.
 */
export async function upgradeRestartReadiness(): Promise<RestartPlan | null> {
  const { sources } = await hostSources(false);
  const processes = sources.processTable() === null ? null : await collectHostProcesses(sources);
  if (!processes) return null;
  const services = hostServices();
  return planRestart(processes, { expected: PENDING_BUILD, serveService: services.serve, autopilotService: services.autopilot, stopMcp: false, ownInstallRoot: ownInstallRoot(), autopilotLauncher: launcherFor(processes) });
}

/** `gbrain upgrade --restart-only [--stop-mcp] [--dry-run] [--json]`: restart every process onto the installed build and verify. */
export async function runHostRestart(opts: HostRestartOptions & { dryRun: boolean }): Promise<void> {
  const { sources, notes, close, pidFile } = await hostSources();
  try {
    const services = hostServices();
    const before = await collectHostProcesses(sources);
    const plan = planRestart(before, { expected: VERSION, serveService: services.serve, autopilotService: services.autopilot, stopMcp: opts.stopMcp, ownInstallRoot: ownInstallRoot(), autopilotLauncher: launcherFor(before) });
    const { probeCliSocket } = await import('../core/cli-socket/probe.ts');
    const warmBefore = await probeCliSocket();
    const planDoc = { expected: VERSION, processes: before, steps: plan.steps, manual: plan.manual, warm_socket: warmBefore, notes };
    if (opts.dryRun) {
      if (opts.json) console.log(JSON.stringify({ status: plan.manual.length ? 'refused' : 'ok', dry_run: true, ...planDoc }, null, 2));
      else printPlan(plan, warmBefore, notes);
      return;
    }
    const refusal = restartRefusal(plan, opts.rerunArgv, true);
    if (refusal) { setCliExitVerdict(writeCliError(refusal, 'upgrade', { json: opts.json })); return; }
    if (!opts.json) printPlan(plan, warmBefore, notes);
    const startedMs = Date.now();
    const results = await runRestartSteps(plan, hostExecutor(pidFile));
    if (!opts.json) for (const r of results) console.log(`  ${r.ok ? 'ok' : 'FAILED'}: ${r.detail}`);
    const verified = await verifyRestart(plan, startedMs, warmBefore, {
      collect: () => collectHostProcesses(sources), probeWarmSocket: () => probeCliSocket(),
      sleep: ms => new Promise(r => setTimeout(r, ms)), now: () => Date.now(), autopilotLockPid: readAutopilotLockPid,
    }, { timeoutMs: plan.steps.length ? Math.max(VERIFY_TIMEOUT_MS, ...plan.steps.map(step => step.kind === 'handoff' ? step.launcher.wait_ms : 0)) : 0, pollMs: VERIFY_POLL_MS });
    const doc = { status: verified.ok ? 'ok' : 'unverified', ...planDoc, results, verified: { processes: verified.processes, warm_socket: verified.warm_socket, problems: verified.problems, unverified: verified.unverified } };
    if (!verified.ok) {
      const failed = results.find(r => !r.ok);
      const mismatch = mismatchedBuilds(plan, verified.processes)[0];
      setCliExitVerdict(writeCliError(opError('restart_unverified',
        `After the restart this host still runs more than one gbrain build, or a process did not come back: ${verified.problems.join(' ')}`,
        `${failed ? `${failed.detail}. ` : ''}${mismatch ? 'Move each listed install onto this build as named' : 'Restart what is listed with the command the plan printed'}, then run \`gbrain upgrade --restart-only\` again.`,
        { docs: DOCS, fix: mismatch ? mismatchFix(mismatch, VERSION) : { argv: DRY_RUN_VERIFY, consent: [], actor: 'agent', requires_exclusive: false, docs: DOCS, why: 'Read-only: lists every gbrain process on this host with its build and the restart each one needs.', verify: { argv: ['gbrain', 'doctor', '--only', 'runtime_build_skew', '--json'] } } }),
        'upgrade', { json: opts.json, extra: opts.json ? { restart: doc } : undefined }));
      return;
    }
    if (opts.json) { console.log(JSON.stringify(doc, null, 2)); return; }
    const running = verified.processes.map(p => `${p.role} pid ${p.pid}`).join(', ');
    console.log(`Verified: every gbrain process on this host runs v${VERSION}${running ? ` (${running})` : ' (none is running)'}; warm CLI socket: ${verified.warm_socket.state === 'refused' ? `refused for this shell (${verified.warm_socket.reason}${verified.warm_socket.mismatch ? `: ${verified.warm_socket.mismatch}` : ''})` : verified.warm_socket.state}.`);
    for (const line of verified.unverified) console.log(`Note: ${line}`);
    const stopped = plan.steps.filter(step => step.kind === 'stop');
    if (stopped.length) console.log(`Reconnect gbrain in the harness of each stopped MCP server (${stopped.map(s => `pid ${s.pid}`).join(', ')}): Claude Code /mcp, then reconnect; other harnesses: start a new session.`);
  } finally {
    await close();
  }
}

export type ServeRestartOutcome = { outcome: 'no_service' | 'current' } | { outcome: 'manual' | 'restarted' | 'unverified'; detail: string };

/**
 * #7475: the serve-only restart plan when the serve service can move every older serve onto `expected` by itself;
 * otherwise the outcome. A serve counts as older only on evidence: a recorded build below `expected`, or no recorded
 * build and a start before the install on disk was written (`installedMs`). A newer or unknown serve is left alone.
 */
export function planServeRestart(processes: readonly HostProcess[], serveService: ServiceHandle, expected: string, ownRoot: string | null, installedMs: number | null = null): RestartPlan | ServeRestartOutcome {
  const older = processes.filter(p => p.role === 'serve' && (p.version !== null
    ? (compareWriterVersions(p.version, expected) ?? 0) < 0
    : installedMs !== null && p.started_ms !== null && p.started_ms < installedMs));
  const plan = planRestart(older, { expected, serveService, autopilotService: null, stopMcp: false, ownInstallRoot: ownRoot });
  if (!plan.stale.length) return { outcome: 'current' };
  if (plan.manual.length || plan.steps.some(step => step.kind !== 'service')) {
    return { outcome: 'manual', detail: `run \`gbrain upgrade --restart-only\`: ${[...describeSteps(plan), ...plan.manual.map(m => m.instruction)].join(' ')}` };
  }
  return plan;
}

/**
 * #7475: the autopilot self-upgrade swaps and relaunches only itself. Once it runs the new build, it calls this to
 * restart the serve the installed serve service runs when that serve is on an older build, and to verify it came
 * back on this one. Serve only: a stale serve the service does not run (started by hand, or from another install)
 * is reported as `manual` and left to doctor's `runtime_build_skew` and `gbrain upgrade --restart-only`.
 */
export async function restartStaleServeService(): Promise<ServeRestartOutcome> {
  const services = hostServices();
  if (!services.serve) return { outcome: 'no_service' };
  if (!serveServiceRunsWrapper(process.platform, homedir())) return { outcome: 'manual', detail: 'the serve service on this host starts another brain\'s serve wrapper (another GBRAIN_HOME), so this autopilot leaves it alone; run `gbrain upgrade --restart-only` with that brain\'s GBRAIN_HOME' };
  const { sources, close, pidFile } = await hostSources();
  try {
    const collectServe = async () => (await collectHostProcesses(sources)).filter(p => p.role === 'serve');
    const root = ownInstallRoot();
    const onDisk = installedVersion(root);
    if (onDisk !== VERSION) return { outcome: 'manual', detail: `the install on disk holds ${onDisk ? `v${onDisk}` : 'an unknown build'}, not this autopilot's v${VERSION}; run \`gbrain upgrade --restart-only\`` };
    let installedMs: number | null = null;
    try { installedMs = statSync(join(root!, 'package.json')).mtimeMs; } catch { /* no install time: a serve with no recorded build stays as it is */ }
    const plan = planServeRestart(await collectServe(), services.serve, VERSION, root, installedMs);
    if (!('steps' in plan)) return plan;
    const { probeCliSocket } = await import('../core/cli-socket/probe.ts');
    const warmBefore = await probeCliSocket();
    const startedMs = Date.now();
    const results = await runRestartSteps(plan, hostExecutor(pidFile, SERVE_RESTART_TIMEOUT_MS));
    const verified = await verifyRestart(plan, startedMs, warmBefore, {
      collect: collectServe, probeWarmSocket: () => probeCliSocket(),
      sleep: ms => new Promise(r => setTimeout(r, ms)), now: () => Date.now(),
    }, { timeoutMs: VERIFY_TIMEOUT_MS, pollMs: VERIFY_POLL_MS });
    const problems = [...results.filter(r => !r.ok).map(r => r.detail), ...verified.problems];
    return { outcome: verified.ok ? 'restarted' : 'unverified', detail: `${describeSteps(plan).join(' ')}${problems.length ? `; ${problems.join(' ')}` : ''}` };
  } finally {
    await close();
  }
}

export type ServeRestartDeps = { state: { tried: boolean }; restart: () => Promise<ServeRestartOutcome> };
const SERVE_RESTART_DEPS: ServeRestartDeps = { state: { tried: false }, restart: restartStaleServeService };
const SERVE_RESTART_TIMEOUT_MS = 120_000;
const serveRestartMarkerPath = () => gbrainPath('serve-restart-attempt.json');

function serveRestartAttemptedOnThisBuild(): boolean {
  try { return (JSON.parse(readFileSync(serveRestartMarkerPath(), 'utf8')) as { version?: unknown }).version === VERSION; } catch { return false; }
}

/**
 * #7475: the autopilot daemon calls this each tick. In auto mode, under the self-upgrade swap's own quiet-hours and
 * idle gates, the autopilot (relaunched on the new build after its swap) restarts the stale serve the serve service
 * runs, and audits the outcome as `restart_serve`. One attempt per build: `serve-restart-attempt.json` remembers it
 * across autopilot relaunches (#8013), and the relaunch after the next swap tries again. Never throws.
 */
export async function restartServeAfterSelfUpgrade(isIdle: () => Promise<boolean>, deps: ServeRestartDeps = SERVE_RESTART_DEPS): Promise<void> {
  if (deps.state.tried) return;
  try {
    const cfg = loadConfig();
    if (!cfg || resolveSelfUpgradeMode(cfg) !== 'auto') return;
    if (evaluateQuietHours(resolveQuietHoursWindow(cfg.self_upgrade?.quiet_hours), new Date()) === 'allow') return;
    if (!await isIdle()) return;
    deps.state.tried = true;
    if (serveRestartAttemptedOnThisBuild()) return;
    mkdirSync(dirname(serveRestartMarkerPath()), { recursive: true });
    writeFileSync(serveRestartMarkerPath(), `${JSON.stringify({ version: VERSION, ts: new Date().toISOString() })}\n`);
    const result = await deps.restart();
    if (!('detail' in result)) return;
    logSelfUpgrade({ channel: 'autopilot', action: 'restart_serve', current: VERSION, outcome: result.outcome === 'restarted' ? 'applied' : 'skipped', reason: result.outcome });
    console.log(`[autopilot] serve ${result.outcome === 'restarted' ? `restarted onto v${VERSION}` : `still on another build (${result.outcome})`}: ${result.detail}`);
  } catch {
    /* the serve restart must never break the autopilot tick */
  }
}

function printPlan(plan: RestartPlan, warm: WarmSocketState, notes: string[]): void {
  for (const note of notes) console.log(note);
  if (!plan.stale.length) console.log(`Every gbrain process on this host already runs v${plan.expected}${plan.current.length ? ` (${plan.current.map(describe).join(', ')})` : ' (none is running)'}.`);
  else {
    console.log(`Restarting onto v${plan.expected}:`);
    for (const line of describeSteps(plan)) console.log(`  ${line}`);
    for (const m of plan.manual) console.log(`  manual: ${m.instruction}`);
    if (plan.current.length) console.log(`Already on v${plan.expected}: ${plan.current.map(describe).join(', ')}.`);
  }
  console.log(`Warm CLI socket: ${warm.state}${warm.state === 'refused' ? ` (${warm.reason}${warm.mismatch ? `: ${warm.mismatch}` : ''})` : ''}.`);
}