Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
79.4 KB
Raw Blame
/**
 * gbrain autopilot — Self-maintaining brain daemon.
 *
 * v0.11.1 shape:
 *   - Default path (minion_mode != off AND engine == postgres): spawn a
 *     `gbrain jobs work` child process, submit ONE `autopilot-cycle` job
 *     per interval with an idempotency_key so slow cycles don't stack up.
 *     The forked worker drains the queue durably; restart with 10s backoff
 *     on crash (5-crash cap → autopilot stops with a clear error).
 *   - Fallback (minion_mode=off, PGLite, or `--inline`): run sync →
 *     extract → embed inline, same as pre-v0.11.1 behavior.
 *
 * Usage:
 *   gbrain autopilot [--repo <path>] [--interval N] [--json] [--inline]
 *   gbrain autopilot --install [--repo <path>]
 *   gbrain autopilot --uninstall
 *   gbrain autopilot --status [--json]
 */

import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, unlinkSync, chmodSync, statSync } from 'fs';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { exitCliError } from '../cli/cli-error.ts';
import { autopilotNoRepoRefusal, autopilotPgliteRefusal } from './autopilot-refusals.ts';
import { readGlobalMaintenanceVerdict } from '../core/minions/global-maintenance-stall.ts';
import { readDaemonStaleAfter } from '../core/autopilot-heartbeat.ts';
import { detectExecutionEnvironment } from '../core/execution-env.ts';
import { join, dirname, isAbsolute, resolve as resolvePath } from 'path';
import { execSync } from '../core/spawn.ts';
import type { BrainEngine } from '../core/engine.ts';
import { loadConfig, saveConfig, gbrainPath as gbrainHomePath } from '../core/config.ts';
import {
  classifyAutopilotLockHolder,
  type AutopilotLockProbeDeps,
  isPidAlive,
} from '../core/autopilot-lock.ts';
import { OwnerProcessingState, readAutopilotProcessingStatus } from '../core/minions/processing-state.ts';
import { VERSION } from '../version.ts';
import {
  AUTO_CHECK_INTERVAL_MS,
  CRASH_ON_LAUNCH_REASON_PREFIX,
  canSelfUpdate,
  decideSelfUpgrade,
  gateOnTargetRuntime,
  isCacheFresh,
  readUpdateCache,
  reconcileBreadcrumb,
  resolveQuietHoursWindow,
  resolveSelfUpgradeMode,
  SWAP_RECEIPT_ENV,
  SWAPPED_REASON,
} from '../core/self-upgrade.ts';
import { prepareSwapReceipt, settleAutopilotSwap } from '../core/self-upgrade-swap.ts';
import { logSelfUpgrade } from '../core/audit/self-upgrade-audit.ts';
import { readHostBun } from '../core/bun-floor.ts';
import { detectInstallMethod, readInstallTargetFloor } from './upgrade.ts';
import { evaluateQuietHours } from '../core/minions/quiet-hours.ts';
import { inspectLock } from '../core/db-lock.ts';
import { relativeSourceLocalPathSkipWarning } from '../core/sources-load.ts';
import { installRepoFallback } from './autopilot/install-repo.ts';
// Path helpers live in a LEAF core module so other commands (gbrain migrate)
// can read the daemon's state files without importing this one — a dynamic
// import of a command module drags its whole flag surface into the importer's
// CLI allowlist. Re-exported here so existing importers keep working.
import {
  autopilotLockPath,
  autopilotDisabledMarkerPath,
  autopilotPausedMarkerPath,
  autopilotPauseReason,
  autopilotDisableStrikesPath,
  autopilotLaunchdLabel,
  autopilotWrapperOwner,
  resolveAutopilotJob,
  DEFAULT_AUTOPILOT_SYSTEMD_UNIT,
  type AutopilotJob,
} from '../core/autopilot-paths.ts';
import {
  BOOTSTRAP_MARKER,
  brainCommand,
  cronLineBelongsToBrain,
  crontabIndicatesAutopilotInstall,
  autopilotJobStatus,
  detectOpenClaw,
  legacyStartScriptPath,
  plistPath,
  plistWrapperPath,
  readIfExists,
  refuseForeignJob,
  replaceLegacySharedJob,
  scriptWrapperPath,
  shellQuote,
  stripBootstrapLines,
  systemdUnitPath,
  unitWrapperPath,
} from './autopilot/jobs.ts';
import { autopilotInstallConsent, renderInstallDryRun } from './autopilot/install-consent.ts';
export { cronLineBelongsToBrain, crontabIndicatesAutopilotInstall, plistWrapperPath, scriptWrapperPath, unitWrapperPath };
export { autopilotLockPath, autopilotDisabledMarkerPath, autopilotPausedMarkerPath, autopilotLaunchdLabel };
export { relativeSourceLocalPathSkipWarning as relativeLocalPathSkipWarning };

/**
 * v0.37.7.0 #1162 — classify autopilot reconnect-loop errors.
 *
 * `recoverable` (network blip, Supabase 503, pool saturated, connection
 * refused on a port that may be coming up): retry with backoff up to
 * `GBRAIN_AUTOPILOT_MAX_RECONNECT_FAILS` (default 30).
 *
 * `unrecoverable` (`database_url` unset/empty/malformed, auth failure,
 * config file unreadable): exit immediately so launchd's 60s
 * `ThrottleInterval` backs off the relaunch instead of thrashing.
 *
 * `crash` (a JS TypeError from dereferencing an undefined object): a BUG, not a
 * verdict about the operator's configuration. Treated as recoverable so a code
 * defect cannot permanently kill the daemon, but logged distinctly so it is not
 * silently misfiled as "you forgot to set a URL."
 *
 * Exported (string-based signature preserved) so tests drive it without needing
 * a real reconnect error.
 */
export function classifyReconnectError(err: unknown): 'recoverable' | 'unrecoverable' | 'crash' {
  // Type check FIRST. Bun/V8 renders a null-deref as
  //   "undefined is not an object (evaluating 'config.database_url')"
  // which, lowercased, contains BOTH "database_url" and "undefined" — so the
  // substring rule below classified a crash as a config verdict and exited the
  // daemon permanently. That is exactly how a 71-day outage started: an engine
  // migration rewrote config.json, the running daemon crashed on a stale object,
  // and the crash was reported as "database_url not set".
  const earlyMsg = (err instanceof Error ? err.message : String(err ?? '')).toLowerCase();
  // Invalid-URL errors ARE TypeErrors in JS (`new URL('garbage')`), but they
  // are an operator-config verdict, not a code defect — test the message
  // pattern BEFORE the blanket TypeError-means-crash rule, or a malformed
  // database_url spends the whole reconnect budget before exiting.
  if (earlyMsg.includes('invalid url') || earlyMsg.includes('malformed') || earlyMsg.includes('parse url')) {
    return 'unrecoverable';
  }
  if (err instanceof Error && err.name === 'TypeError') return 'crash';
  const msg = (err instanceof Error ? err.message : String(err ?? '')).toLowerCase();
  // Same shape, for hosts where the error arrives as a plain string/serialized
  // object and the `name` is gone.
  if (
    msg.includes('is not an object')
    || msg.includes('is not a function')
    || msg.includes('cannot read propert')
    || msg.includes('undefined is not')
  ) {
    return 'crash';
  }
  if (msg.includes('database_url') && (msg.includes('undefined') || msg.includes('missing') || msg.includes('empty') || msg.includes('not set'))) {
    return 'unrecoverable';
  }
  if (msg.includes('invalid url') || msg.includes('malformed') || msg.includes('parse url')) {
    return 'unrecoverable';
  }
  // Auth failures: postgres prints `role "name" does not exist` (with the
  // role name in quotes between role and does), so use a skeleton match.
  if (msg.includes('password authentication failed') || msg.includes('authentication failed')) {
    return 'unrecoverable';
  }
  if (msg.includes('role') && msg.includes('does not exist')) {
    return 'unrecoverable';
  }
  if (msg.includes('no brain configured') || msg.includes('config not found')) {
    return 'unrecoverable';
  }
  return 'recoverable';
}

export function parseArg(args: string[], flag: string): string | undefined {
  const idx = args.indexOf(flag);
  return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined;
}

export function logError(phase: string, e: unknown) {
  const msg = e instanceof Error ? e.message : String(e);
  const ts = new Date().toISOString().slice(0, 19);
  const line = `[${ts}] [${phase}] ERROR: ${msg}`;
  console.error(line);
  try {
    const logDir = gbrainHomePath();
    mkdirSync(logDir, { recursive: true });
    appendFileSync(join(logDir, 'autopilot.log'), line + '\n');
  } catch { /* best-effort */ }
}

/**
 * Enumerate %PATH% (Windows) for the gbrain CLI shim, honoring PATHEXT.
 *
 * On win32 this is the FIRST resolution path (`which` does not exist in
 * cmd/PowerShell); resolveGbrainCliPath calls it before the execPath and
 * argv[1] fallbacks. Unlike `where`, this NEVER looks at the current
 * directory, so a stray gbrain.exe in cwd cannot hijack resolution. Only
 * directly spawnable extensions (.exe/.com/.cmd/.bat) are accepted, and
 * only regular files - a directory named gbrain.exe cannot shadow a real
 * binary. Returns the first existing candidate, or '' when none exists.
 */
export function resolveWindowsCliPath(): string {
  const pathext = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';');
  const pathDirs = (process.env.PATH ?? '').split(';');
  for (const dir of pathDirs) {
    // Skip empty and relative entries: '.' or 'bin' resolve against the
    // current directory, which would reintroduce the cwd-hijack `where`
    // has. Only absolute %PATH% entries are trusted.
    if (!dir || !isAbsolute(dir)) continue;
    for (const ext of pathext) {
      // Only directly spawnable types: PATHEXT can also carry .JS/.VBS
      // (Windows Script Host), which Bun cannot exec - spawning them fails
      // EFTYPE. .CMD/.BAT spawn through the shell; .COM/.EXE direct.
      const type = ext.toLowerCase();
      if (type !== '.exe' && type !== '.com' && type !== '.cmd' && type !== '.bat') continue;
      const candidate = join(dir, 'gbrain' + type);
      try {
        if (statSync(candidate).isFile()) return candidate;
      } catch { /* missing or unreadable - keep looking */ }
    }
  }
  return '';
}

/**
 * Resolve the gbrain CLI entrypoint for spawning the worker child.
 *
 * A .ts source path is never a valid spawn target - spawning it fails with
 * EACCES because TypeScript source isn't executable. The canonical install
 * puts a shim at `/usr/local/bin/gbrain` (or wherever `which gbrain`
 * resolves to) that already wraps the right runtime+entrypoint; prefer it.
 *
 * Order of resolution:
 *   1. Platform PATH lookup - `which gbrain` on POSIX; explicit %PATH%
 *      enumeration (resolveWindowsCliPath) on win32, where `which` does
 *      not exist (#3793).
 *   2. process.execPath if it ends with /gbrain (compiled binary, no shim).
 *   3. argv[1] if it ends with /gbrain (e.g., direct invocation of compiled
 *      binary without PATH). Never .ts source paths.
 *   4. Throw with a clear install hint.
 */
export function resolveGbrainCliPath(): string {
  // #3793: `which` does not exist in cmd or PowerShell on Windows, so the
  // bun-installed gbrain.exe shim on %PATH% was never found and autopilot
  // died with "Could not resolve the gbrain CLI path". `where` would find
  // it but has a cwd-hijack; use explicit %PATH% enumeration on win32.
  if (process.platform === 'win32') {
    const win = resolveWindowsCliPath();
    if (win) return win;
  } else {
    try {
      // #2747: `env: process.env` is required under Bun. Bun's execSync
      // snapshots process.env at Bun's OWN startup, not at call time - a
      // runtime PATH mutation (dotenv/config loading, shell-profile sourcing
      // in a wrapper, etc.) happening between Bun boot and this call is
      // invisible to `which` without explicitly forwarding the current env.
      // This is why "which gbrain" succeeds when run standalone (fresh Bun
      // process, no prior mutation) but can fail from inside autopilot's own
      // process at this exact call site. Same fix already applied to
      // detectTini() in spawn-helpers.ts (see its comment) - this call site
      // was missed.
      const which = execSync('which gbrain', {
        encoding: 'utf-8',
        stdio: ['ignore', 'pipe', 'ignore'],
        env: process.env,
      })
        .trim()
        .split(/\r?\n/, 1)[0];
      if (which) return which;
    } catch { /* not on $PATH - fall through */ }
  }
  const exec = process.execPath ?? '';
  if (exec.endsWith('/gbrain') || exec.endsWith('\\gbrain.exe')) {
    return exec;
  }

  const arg1 = process.argv[1] ?? '';
  if (arg1.endsWith('/gbrain') || arg1.endsWith('\\gbrain.exe')) {
    return arg1;
  }

  // #2747: include what we actually saw so an operator (or a future bug
  // report) doesn't have to guess whether PATH/execPath/argv[1] looked
  // sane at the moment of failure.
  throw new Error(
    'Could not resolve the gbrain CLI path. Install gbrain so it is on $PATH ' +
      '(e.g. /usr/local/bin/gbrain), or run autopilot from the compiled binary directly. ' +
      `Debug: PATH=${JSON.stringify(process.env.PATH ?? '')} execPath=${JSON.stringify(exec)} argv1=${JSON.stringify(arg1)}`,
  );
}
export function shouldSpawnAutopilotWorker(args: string[]): boolean {
  return !args.includes('--no-worker');
}

export { isPidAlive };

export const AUTOPILOT_FOREIGN_PID_TAKEOVER_GRACE_MS = 10 * 60 * 1000;

function autopilotLockAgeMs(lockPath: string): number | null {
  try {
    return Date.now() - statSync(lockPath).mtimeMs;
  } catch {
    return null;
  }
}

export function decideLockAcquisition(
  lockPath: string,
  currentPid: number,
  deps: AutopilotLockProbeDeps = {},
):
  | { action: 'acquire' }
  | { action: 'exit'; holderPid: number; holderState: 'alive-autopilot' | 'alive-foreign' | 'alive-unknown' }
  | { action: 'takeover'; reason: string } {
  if (!existsSync(lockPath)) return { action: 'acquire' };

  let raw = '';
  try {
    raw = readFileSync(lockPath, 'utf-8').trim();
  } catch {
    // An unreadable lock cannot prove another process is alive.
  }

  const holderPid = Number.parseInt(raw, 10);
  const holder = classifyAutopilotLockHolder(holderPid, currentPid, deps);

  if (holder.state === 'alive-autopilot') {
    return { action: 'exit', holderPid, holderState: holder.state };
  }
  if (holder.state === 'alive-foreign' || holder.state === 'alive-unknown') {
    // #4300: an alive PID whose command we can't identify as gbrain autopilot
    // (recycled PID after reboot, or a /proc-less + ps-restricted host) gets
    // the same age-gated takeover as a known-foreign holder. A fresh lock is
    // still respected; only a stale one (past the grace window) is stolen —
    // otherwise a single recycled PID bricks the daemon forever.
    const lockAgeMs = autopilotLockAgeMs(lockPath);
    if (lockAgeMs !== null && lockAgeMs >= AUTOPILOT_FOREIGN_PID_TAKEOVER_GRACE_MS) {
      const kind = holder.state === 'alive-foreign' ? 'foreign' : 'unidentifiable';
      return { action: 'takeover', reason: `${kind} pid ${raw || '<empty>'} with stale lock` };
    }
    return { action: 'exit', holderPid, holderState: holder.state };
  }
  if (holder.state === 'self') {
    return { action: 'takeover', reason: `own pid ${raw || '<empty>'}` };
  }
  return { action: 'takeover', reason: `dead pid ${raw || '<empty>'}` };
}

// ── Self-upgrade silent channel (v0.42; opt-in, supervisor-relaunch) ─────────

/**
 * Reconcile the pre-swap breadcrumb at daemon boot (the post-swap attribution
 * gate). If we're running the version we attempted or a newer one, the
 * swap+relaunch worked; if not, the new binary failed to launch and we record
 * it as a known-bad version so the auto channel never retries it. Best-effort.
 */
export function reconcileSelfUpgradeAtBoot(): void {
  try {
    const cfg = loadConfig();
    if (!cfg) return;
    const attempted = cfg.self_upgrade?.attempting_version;
    const { state, transition } = reconcileBreadcrumb(cfg.self_upgrade, VERSION);
    if (!transition) return;
    cfg.self_upgrade = state;
    saveConfig(cfg);
    logSelfUpgrade({
      channel: 'autopilot',
      action: 'apply',
      current: VERSION,
      latest: attempted,
      outcome: transition === 'applied' ? 'applied' : 'failed',
      reason:
        transition === 'applied'
          ? 'running version is at or past the attempted version'
          : `${CRASH_ON_LAUNCH_REASON_PREFIX} running version is not at or past the attempted version (recorded known-bad)`,
    });
    if (transition === 'applied') {
      console.log(`[autopilot] self-upgrade confirmed: attempted ${attempted}, now running ${VERSION}.`);
    } else {
      console.error(`[autopilot] self-upgrade did not take: attempted ${attempted}, still running ${VERSION}; recorded ${attempted} known-bad.`);
    }
  } catch {
    /* best-effort */
  }
}

/** Conservative idle: no cycle running AND (Postgres) no active/waiting jobs.
 * Any ambiguity / error → NOT idle (we'd rather skip an upgrade window). */
export async function computeAutopilotIdle(engine: BrainEngine, engineType: string): Promise<boolean> {
  try {
    const cycle = await inspectLock(engine, 'gbrain-cycle');
    if (cycle) return false; // a cycle (sync/extract/embed/...) is running
    if (engineType === 'postgres') {
      const rows = await (engine as any).executeRaw?.(
        `SELECT count(*)::int AS n FROM minion_jobs WHERE status IN ('active','waiting')`,
      );
      const busy = Number((rows as Array<{ n: number }>)?.[0]?.n ?? 0);
      return busy === 0;
    }
    return true; // pglite: no separate worker queue; cycle-lock-free is the signal
  } catch {
    return false;
  }
}

export function guardAutopilotEngine(engine: BrainEngine, state: OwnerProcessingState): BrainEngine {
  const refuse = (): never => {
    throw new Error('Autopilot processing is configuration-blocked; repair and restart the owner.');
  };
  return new Proxy(engine, {
    get(target, property) {
      const value = Reflect.get(target, property);
      if (typeof value !== 'function') return value;
      return (...args: unknown[]) => {
        if (property !== 'disconnect' && state.blocked) refuse();
        if (property === 'transaction' || property === 'transactionDirect') {
          const fn = args[0] as (tx: BrainEngine) => Promise<unknown>;
          return Reflect.apply(value, target, [async (tx: BrainEngine) => {
            const result = await fn(guardAutopilotEngine(tx, state));
            if (state.blocked) refuse();
            return result;
          }]);
        }
        return Reflect.apply(value, target, args);
      };
    },
  });
}

/**
 * The autopilot silent self-upgrade channel. Opt-in (`self_upgrade.mode=auto`).
 * Fires only when behind + idle + in quiet hours + the install can self-update
 * and the target isn't known-bad. On apply: write the breadcrumb, run
 * `gbrain upgrade --swap-only` (fast; defers post-upgrade to the relaunch),
 * then unlink the autopilot lock and exit(0) so the supervisor relaunches the
 * new binary (no in-process re-exec — Bun has no execve). Never throws.
 */
export async function attemptAutopilotSelfUpgrade(
  engine: BrainEngine,
  engineType: string,
  lockPath: string,
  mayContinue: () => boolean = () => true,
): Promise<void> {
  try {
    const cfg = loadConfig();
    if (!cfg) return;
    if (resolveSelfUpgradeMode(cfg) !== 'auto') return;

    // latestVersion from the shared cache; refresh when stale (TTL throttles fetch).
    let entry = readUpdateCache();
    if (!entry || !isCacheFresh(entry, Date.now())) {
      try {
        const { refreshUpdateCache } = await import('./check-update.ts');
        await refreshUpdateCache();
        entry = readUpdateCache();
      } catch {
        /* fail-open */
      }
    }
    if (!entry || entry.error || entry.marker?.kind !== 'upgrade_available' || !entry.marker.latest) return;
    const latestVersion = entry.marker.latest;

    const idle = await computeAutopilotIdle(engine, engineType);
    const verdict = evaluateQuietHours(resolveQuietHoursWindow(cfg.self_upgrade?.quiet_hours), new Date());
    const installMethod = detectInstallMethod();

    let decision = decideSelfUpgrade({
      mode: 'auto',
      channel: 'autopilot',
      currentVersion: VERSION,
      latestVersion,
      failedVersions: cfg.self_upgrade?.failed_versions ?? [],
      idle,
      inQuietHours: verdict !== 'allow',
      canSelfUpdate: canSelfUpdate(installMethod),
      // The cache TTL throttles the fetch; last_check_ts (written when a swap
      // installed nothing, #6828) keeps a no-op swap to one attempt a day.
      throttledByInterval: typeof cfg.self_upgrade?.last_check_ts === 'number'
        && Date.now() - cfg.self_upgrade.last_check_ts < AUTO_CHECK_INTERVAL_MS,
    });
    // #5855: never swap in a release the host's Bun cannot start (a binary carries its own Bun).
    if (decision.action === 'apply' && installMethod !== 'binary') {
      decision = gateOnTargetRuntime(decision, await readInstallTargetFloor(installMethod), readHostBun(), cfg.self_upgrade?.failed_versions);
    }

    if (decision.action !== 'apply') {
      if (['unsupported_install', 'known_bad', 'unsupported_runtime'].includes(decision.action)) {
        logSelfUpgrade({
          channel: 'autopilot',
          action: decision.action,
          current: VERSION,
          latest: latestVersion,
          outcome: 'skipped',
          reason: decision.reason,
        });
      }
      return;
    }

    if (!mayContinue()) return;
    // Apply. Breadcrumb first so a crash-on-launch is attributable.
    cfg.self_upgrade = { ...(cfg.self_upgrade ?? {}), attempting_version: latestVersion };
    saveConfig(cfg);
    logSelfUpgrade({ channel: 'autopilot', action: 'apply', current: VERSION, latest: latestVersion, reason: decision.reason });
    console.log(`[autopilot] self-upgrade: applying ${VERSION} -> ${latestVersion} (idle, quiet hours).`);

    // #6828: the swap writes what it installed to the receipt; exit 0 alone cannot tell a swap from a no-op.
    const receiptPath = prepareSwapReceipt();
    let swapError: unknown = null;
    try {
      execSync('gbrain upgrade --swap-only', {
        stdio: 'inherit',
        timeout: 300_000,
        env: { ...process.env, GBRAIN_SKIP_STARTUP_HOOKS: '1', [SWAP_RECEIPT_ENV]: receiptPath },
      });
    } catch (e) {
      swapError = e;
    }
    const swap = settleAutopilotSwap(VERSION, latestVersion, swapError, receiptPath);
    if (!swap.relaunch) return;

    if (!mayContinue()) return;
    // Swap done + smoke-verified by `upgrade --swap-only`. Exit cleanly so the
    // supervisor relaunches the NEW binary, which reconciles the breadcrumb.
    logSelfUpgrade({
      channel: 'autopilot',
      action: 'apply',
      current: VERSION,
      latest: swap.installed,
      outcome: 'applied',
      reason: SWAPPED_REASON,
    });
    console.log('[autopilot] self-upgrade swapped; exiting for relaunch.');
    try {
      unlinkSync(lockPath);
    } catch {
      /* already gone */
    }
    process.exit(0);
  } catch {
    /* the self-upgrade channel must never break the tick */
  }
}

/** Flags that consume the following argv token as their value (#1525). */
const AUTOPILOT_VALUE_FLAGS = new Set(['--repo', '--interval', '--target', '--reason', '--phase']);

/** Positional spellings → their canonical flags. A Map (not a plain object)
 * so prototype-chain words like `constructor` stay unknown positionals. */
const AUTOPILOT_POSITIONAL_ALIASES = new Map<string, string>([
  ['status', '--status'],
  ['install', '--install'],
  ['uninstall', '--uninstall'],
  ['pause', '--pause'],
  ['resume', '--resume'],
  ['help', '--help'],
]);

/**
 * #1525 — positional args were never validated, so `gbrain autopilot status`
 * fell through every flag branch and STARTED the daemon in the foreground: a
 * status CHECK silently became a daemon LAUNCH. Map the natural subcommand
 * spellings onto their canonical flags, drop the redundant `start` (daemon
 * start is already the default action), and refuse anything unrecognized
 * with exit 2 before any engine or daemon work happens. Value-taking flags
 * keep their argument verbatim (`--repo status` names a directory, not a
 * subcommand). cli.ts resolves BEFORE connectEngine so `autopilot status`
 * rides the same engine-free short-circuit as `--status`; the call in
 * runAutopilot keeps direct callers safe and is a no-op on resolved argv.
 */
export function resolveAutopilotPositionals(args: string[]): string[] {
  const out: string[] = [];
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (a.startsWith('-')) {
      out.push(a);
      if (AUTOPILOT_VALUE_FLAGS.has(a) && i + 1 < args.length) out.push(args[++i]);
      continue;
    }
    const alias = AUTOPILOT_POSITIONAL_ALIASES.get(a);
    if (alias) {
      out.push(alias);
      continue;
    }
    if (a === 'start') continue; // daemon start is the default action
    console.error(
      `Unknown autopilot argument '${a}'. Expected one of: status, install, uninstall, pause, resume, start, help.\n` +
      `Run 'gbrain autopilot --help' for usage.`,
    );
    process.exit(2);
  }
  return out;
}

/**
 * #2608 — pure function (test seam, same pattern as generateLaunchdPlist):
 * the boot-time warning emitted when no chat provider is available, so the
 * silent no-op of every LLM phase (chronicle, dream, enrich) is visible in
 * the daemon log instead of manifesting as "autopilot runs green but
 * nothing gets extracted".
 *
 * gbrainDir is a param (not resolved here) to keep the function pure AND so
 * both remediation paths honor GBRAIN_HOME — a literal `~/.gbrain` lies on
 * custom-home installs. `gbrain config set` is deliberately NOT named: the
 * canonical key guidance (INSTALL_FOR_AGENTS.md Step 2) tells users not to
 * use it for API keys. The reload instruction is load-bearing: the wrapper
 * sources the env file only at exec and the gateway folds env once
 * pre-dispatch, so a key written after boot changes nothing until
 * `--install` regenerates the wrapper and reloads the daemon.
 */
export function chatBootWarning(chatAvailable: boolean, gbrainDir: string): string | null {
  if (chatAvailable) return null;
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- warning-message hint construction, no fs operation; gbrainDir is configDir()-validated (absolute, no ..), same pattern as import.ts:43
  const envFile = join(gbrainDir, 'env');
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- same: log-string construction only
  const configJson = join(gbrainDir, 'config.json');
  return (
    '[autopilot] WARNING: no chat provider available — LLM phases (chronicle, dream, enrich) will no-op. ' +
    `Put an API key (ANTHROPIC_API_KEY or OPENAI_API_KEY) in ${envFile} (sourced by the daemon wrapper) ` +
    `or in ${configJson} (file plane), then re-run \`gbrain autopilot --install\` to reload the daemon.`
  );
}

/**
 * `gbrain autopilot` mode flags, checked in order (first match wins, the
 * precedence of the old if-chain). No mode flag runs the daemon.
 */
const AUTOPILOT_MODES: Array<{ flags: string[]; run: (engine: BrainEngine, args: string[]) => unknown }> = [
  { flags: ['--install'], run: async (engine, args) => { await installDaemon(engine, args); } },
  { flags: ['--uninstall'], run: () => { uninstallDaemon(); } },
  { flags: ['--status'], run: (_engine, args) => { runAutopilotStatus(args); } },
  { flags: ['--pause', '--resume'], run: async (_engine, args) => (await import('./autopilot-pause.ts')).runAutopilotPauseCommand(args) },
  { flags: ['--retry-global'], run: async (engine, args) => (await import('./autopilot-retry-global.ts')).runAutopilotRetryGlobal(engine, args) },
];

export async function runAutopilot(engine: BrainEngine, args: string[]) {
  args = resolveAutopilotPositionals(args);
  if (args.includes('--help') || args.includes('-h')) {
    console.log(
      'Usage: gbrain autopilot [--repo <path>] [--interval N] [--json] [--no-worker]\n' +
      '       gbrain autopilot --install [--repo <path>]\n' +
      '       gbrain autopilot --uninstall\n' +
      '       gbrain autopilot --status [--json]\n' +
      '       gbrain autopilot pause [--reason <text>] | resume   (operator hold; upgrade and --install keep it)\n' +
      '       gbrain autopilot --retry-global [--phase <name>] [--json]   (end a failing maintenance phase\'s back-off)\n\n' +
      'Self-maintaining brain daemon. Runs the full maintenance cycle\n' +
      '(lint + backlinks + sync + extract + embed + orphans) on an interval.\n\n' +
      'For a one-shot cron-triggered cycle, see `gbrain dream`.',
    );
    return;
  }

  const mode = AUTOPILOT_MODES.find((m) => m.flags.some((f) => args.includes(f)));
  if (mode) return mode.run(engine, args);
  return (await import('./autopilot-daemon.ts')).runAutopilotDaemon(engine, args);
}

// --- Install/Uninstall ---

export type InstallTarget = 'macos' | 'linux-systemd' | 'ephemeral-container' | 'linux-cron';

/**
 * Detect the right supervisor for this host.
 *
 *   - macos   → launchd (always, when platform === 'darwin').
 *   - ephemeral-container → Render / Railway / Fly / Docker. Crontab is
 *                           unreliable here (wiped on deploy); we hand
 *                           the user a start script instead.
 *   - linux-systemd → systemd user scope actually works (is-system-running
 *                     probe succeeds). Codex hardened from the naive
 *                     /run/systemd/system check.
 *   - linux-cron  → fallback.
 */
export function detectInstallTarget(): InstallTarget {
  if (process.platform === 'darwin') return 'macos';

  // Shared detector (execution-env.ts): covers the original Render/Railway/
  // Fly//.dockerenv signals AND the cloud-sandbox signature — both get the
  // start-script treatment here (no reliable scheduler in either).
  if (detectExecutionEnvironment() !== 'local') return 'ephemeral-container';

  if (existsSync('/run/systemd/system')) {
    try {
      execSync('systemctl --user is-system-running', { stdio: 'pipe', timeout: 3000 });
      return 'linux-systemd';
    } catch {
      // user bus not available → fall through to cron.
    }
  }

  return 'linux-cron';
}

/** systemd unit name. The launchd label lives in `autopilotLaunchdLabel()`
 *  (core/autopilot-paths.ts) so installer, uninstaller, status, and the
 *  wrapper's self-disable can never name different jobs. */
export const AUTOPILOT_SYSTEMD_UNIT = DEFAULT_AUTOPILOT_SYSTEMD_UNIT;


/**
 * Bash block that stops the daemon for good when its captured `--repo` is gone.
 *
 * Two things this must get right, both learned the hard way:
 *
 * 1. PREDICATE. Test the repo DIRECTORY, not `$repo/.git`. `--repo` may be a
 *    subdirectory of the checkout (sync resolves the root itself by walking up
 *    with `git rev-parse` show-toplevel), and in worktrees and submodules
 *    `.git` is a FILE, not a directory. Testing `.git/` would self-disable a
 *    perfectly healthy install in both shapes.
 *
 * 2. MECHANISM. `exit 0` is the right answer for the sibling cron wrapper in
 *    `brain-repo-durability.ts` because launchd fires that one on StartInterval —
 *    one shot, so exiting ends it. Autopilot runs under `KeepAlive=true` +
 *    `ThrottleInterval=60` (and systemd `Restart=always` / `RestartSec=30`),
 *    where exiting 0 disables NOTHING: it converts a dead install into a silent
 *    respawn-every-60s log-append loop that runs forever. On those two targets
 *    the wrapper has to actually take the job out of rotation.
 *
 *    `linux-cron` and `ephemeral-container` are periodic/one-shot, so a plain
 *    exit is correct and sufficient there.
 *
 * Exported pure so tests can assert the emitted shape per target without
 * installing a daemon.
 */
export function generateSelfDisableGuard(repoPath: string, target: InstallTarget, job: AutopilotJob = resolveAutopilotJob()): string {
  const q = (s: string) => s.replace(/'/g, "'\\''");
  const marker = autopilotDisabledMarkerPath();
  const disableCmd =
    target === 'macos'
      ? `  launchctl bootout "gui/$(id -u)/${job.launchdLabel}" 2>/dev/null || true\n`
      : target === 'linux-systemd'
        ? `  systemctl --user disable --now ${job.systemdUnit} 2>/dev/null || true\n`
        : '';
  const strikes = autopilotDisableStrikesPath();
  return `# Self-disable if the captured checkout is gone (rename / relocation / deletion).
# Tests the repo DIRECTORY: --repo may be a subdirectory of the checkout, and
# .git is a FILE in worktrees and submodules, so [ ! -d "$repo/.git" ] would
# false-positive on healthy installs.
# THREE consecutive misses before disabling: repos on external volumes, NFS,
# or cloud-synced folders are routinely absent for the first launch after
# login, and one transient miss must not permanently kill the install. Any
# successful probe resets the strike counter.
if [ ! -d '${q(repoPath)}' ]; then
  _strikes=$(($(cat '${q(strikes)}' 2>/dev/null || echo 0) + 1))
  echo "$_strikes" > '${q(strikes)}' 2>/dev/null || true
  if [ "$_strikes" -lt 3 ]; then
    echo "$(date -u +%FT%TZ) [autopilot] repo path missing (strike $_strikes of 3, disabling at 3):" '${q(repoPath)}'
    exit 0
  fi
  echo "$(date -u +%FT%TZ) [autopilot] repo path gone, disabling:" '${q(repoPath)}'
  printf '%s\\n' 'repo path gone: ${q(repoPath)}' > '${q(marker)}' 2>/dev/null || true
  rm -f '${q(strikes)}' 2>/dev/null || true
${disableCmd}  exit 0
fi
rm -f '${q(strikes)}' 2>/dev/null || true
`;
}

// Exported for tests (#2608): the emitted wrapper text is the contract —
// key-channel regressions (rc-file || chains, missing env-file sourcing)
// must be pinnable without installing a daemon.
/**
 * #2608: contents of the install-time `<gbrainDir>/env` template. All lines
 * commented — the install must never ship a live secret. GBRAIN_HOME is
 * deliberately absent: the wrapper bakes it at install time AFTER sourcing
 * this file, so setting it here would be clobbered (or diverge the daemon's
 * home from the file's own location).
 */
const GBRAIN_ENV_TEMPLATE = `# gbrain daemon environment — sourced by autopilot-run.sh before the daemon
# starts (set -a: plain KEY=value lines are exported too). Created once by
# \`gbrain autopilot --install\`; gbrain never overwrites or deletes it.
# Interactive shell rc files do NOT reach daemon shells — put anything the
# daemon needs here, then re-run \`gbrain autopilot --install\` to reload.
#
# API keys (~/.gbrain/config.json file plane works too):
# export ANTHROPIC_API_KEY=sk-ant-...
# export OPENAI_API_KEY=sk-...
# export VOYAGE_API_KEY=pa-...  (off disk, as this file is bash: ="$(op read 'op://Private/Voyage/credential')")
#
# Process-level env that must exist before the daemon boots:
# export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem
# export HTTPS_PROXY=http://proxy:3128
# export GBRAIN_DATABASE_URL=postgres://...
#
# Do NOT set GBRAIN_HOME here — --install bakes it into the wrapper after
# this file is sourced, so a value here is clobbered or diverges the
# daemon's home from this file's own location.
`;

export function writeWrapperScript(repoPath: string, target: InstallTarget, job: AutopilotJob = resolveAutopilotJob()): string {
  // gbrainHomePath, not raw $HOME: the daemon writes its lock/markers through
  // it and the status command reads through it, so a GBRAIN_HOME install must
  // keep its wrapper (and the start-script detection that looks for it) in
  // the same directory. Identical to the old behavior when GBRAIN_HOME is
  // unset. The env var is also baked into the wrapper below — launchd does
  // not pass the installer's environment to the spawned job.
  const gbrainDir = gbrainHomePath();
  mkdirSync(gbrainDir, { recursive: true });

  // Wrapper sources the user's shell profile for API keys so nothing is
  // baked into plist/crontab/systemd unit files (#2).
  const wrapperPath = join(gbrainDir, 'autopilot-run.sh');
  const gbrainPath = resolveGbrainCliPath();
  const safeRepoPath = repoPath.replace(/'/g, "'\\''");
  const safeGbrainPath = gbrainPath.replace(/'/g, "'\\''");
  // #2608: same gbrain home the daemon itself uses (honors GBRAIN_HOME),
  // baked as an absolute path so the sourcing below never depends on a
  // literal ~/.gbrain guess drifting from a custom install.
  const gbrainEnvFile = join(gbrainDir, 'env');
  const safeGbrainEnvFile = gbrainEnvFile.replace(/'/g, "'\\''");
  // #2608: install-time template so the boot warning points at a file that
  // exists, secret-safe (0600) from birth. Never overwrite — it may hold
  // user secrets — and never chmod a pre-existing file (warn instead). A
  // failed template write must not abort an otherwise-working install
  // (untested by design: dir-permission tricks don't bite under root CI).
  try {
    if (!existsSync(gbrainEnvFile)) {
      writeFileSync(gbrainEnvFile, GBRAIN_ENV_TEMPLATE, { mode: 0o600 });
    } else if ((statSync(gbrainEnvFile).mode & 0o077) !== 0) {
      console.error(`[autopilot] warning: ${gbrainEnvFile} is group/world-readable and may hold API keys — consider: chmod 600 '${safeGbrainEnvFile}'`);
    }
  } catch (e) {
    console.error(`[autopilot] warning: could not create env template at ${gbrainEnvFile}: ${e instanceof Error ? e.message : String(e)}`);
  }
  // Bake the dir of the bun runtime actually executing this install onto PATH,
  // so the wrapper finds bun wherever it lives — Homebrew (/opt/homebrew/bin),
  // npm -g, Docker (/usr/local/bin), a custom BUN_INSTALL, or nix — not just
  // ~/.bun/bin (which #3305 hardcoded, covering only the default bun.sh installer).
  // dirname('') === '.', so guard the degenerate/empty case — otherwise a missing
  // execPath would prepend '.' (cwd) onto a cron PATH. Empty prefix falls back to
  // the #3305 behavior exactly.
  const runtimeDir = dirname(process.execPath || '');
  const runtimePathPrefix = runtimeDir && runtimeDir !== '.'
    ? `'${runtimeDir.replace(/'/g, "'\\''")}':`
    : '';
  const wrapper = `#!/bin/bash
# Auto-generated by gbrain autopilot --install
# Sources shell profile for API keys, then runs autopilot.
# zshenv is the canonical place for env vars in zsh on macOS (zshrc is for
# interactive shells only — vars defined there don't reach this non-interactive
# subprocess). Source it first so secrets like GBRAIN_DATABASE_URL or any
# OPENAI/ANTHROPIC keys exported in zshenv reach autopilot.
[ -f ~/.zshenv ] && source ~/.zshenv 2>/dev/null
# #2608: source zshrc AND bashrc independently. The old \`zshrc || bashrc\`
# chain only reached bashrc when sourcing zshrc FAILED — on a machine with
# both files (default macOS + a bash-managed key setup) the bashrc keys
# never loaded and every LLM phase silently no-op'd.
[ -f ~/.zshrc ] && source ~/.zshrc 2>/dev/null
[ -f ~/.bashrc ] && source ~/.bashrc 2>/dev/null
# gbrain-owned env file (#2608), additive to the profiles above: daemon
# shells are non-interactive, so exports that live only in an interactive
# rc file never reach them — and the ~/.bashrc guard below means even
# ~/.bashrc-only exports can be lost on a common Linux config. This is the
# deterministic place for API keys AND process-level env the daemon needs
# before boot (NODE_EXTRA_CA_CERTS, proxy vars, GBRAIN_DATABASE_URL) —
# things an in-process config read could never deliver. Created 0600 by
# --install. Sourced AFTER the profiles so it wins on conflicts; a missing
# file is a normal no-op, not an error. set -a exports dotenv-style
# KEY=value lines too — without it a plain assignment never reaches the
# exec'd daemon.
[ -f '${safeGbrainEnvFile}' ] && { set -a; source '${safeGbrainEnvFile}' 2>/dev/null; set +a; }
# Belt-and-suspenders PATH fix. ~/.bashrc ships with a non-interactive guard
# (\`case $- in *i*) ;; *) return;; esac\`) that exits early when launched from
# cron/systemd/launchd — so its PATH exports never reach this subprocess.
# Without bun on PATH, the exec'd gbrain (a \`#!/usr/bin/env bun\` script) fails
# silently with "env: bun: No such file or directory" and leaves a stale
# lockfile that blocks every subsequent tick. Prepending the running bun's own
# dir (derived from process.execPath at install time), with ~/.bun/bin kept as a
# fallback, keeps the wrapper self-contained regardless of where bun is installed
# or which init file the OS loaded.
export PATH=${runtimePathPrefix}"$HOME/.bun/bin:$PATH"
${process.env.GBRAIN_HOME ? `# Baked at install: the supervisor does not pass the installer's env, and\n# without this the daemon would read/write a different home than the\n# install that configured it.\nexport GBRAIN_HOME='${(process.env.GBRAIN_HOME).replace(/'/g, "'\\''")}'\n` : ''}
${generateSelfDisableGuard(repoPath, target, job)}# #3696: daemon cwd = the repo. Sync refuses a legacy RELATIVE local_path /
# sync.repo_path row and guarded readers skip it (#7630); the few readers #7646
# tracks still resolve one against this cwd, so the cd stays. Done HERE — after the guard has proven the repo exists —
# and NOT via launchd's plist WorkingDirectory: launchd chdir()s before exec,
# so a deleted repo would fail every respawn and the self-disable guard above
# could never run. Fail-open (|| true): a repo deleted between the guard and
# this line still starts the daemon, and the dispatch loops skip relative
# paths loudly.
cd '${safeRepoPath}' 2>/dev/null || true
# #4728: the CLI path below was resolved ONCE at --install. On the
# ephemeral-container target the container layer is wiped on every deploy, so
# a CLI that lived there vanishes while this wrapper (on the volume) survives,
# and bash's bare "No such file or directory" named no remedy. The baked path
# stays primary; only once it is gone do we fall back to PATH — the same
# resolution the daemon already applies at run time when it spawns its worker
# child (resolveGbrainCliPath -> which gbrain), so this adds no lookup
# semantics the install did not already rely on. \`type -P\` only returns an
# executable file on PATH, ignoring any \`gbrain\` shell function or alias the
# rc files sourced above may have defined. Logs go to stdout: that is the
# autopilot.log sink on all four targets (same choice as the boot warning).
if [ ! -x '${safeGbrainPath}' ]; then
  _resolved=$(type -P gbrain 2>/dev/null)
  if [ -n "$_resolved" ]; then
    echo "$(date -u +%FT%TZ) [autopilot] baked CLI path is gone:" '${safeGbrainPath}' "- using $_resolved"
    exec "$_resolved" autopilot --repo '${safeRepoPath}'
  fi
  echo "$(date -u +%FT%TZ) [autopilot] gbrain CLI not found at" '${safeGbrainPath}' "nor on PATH; re-run: gbrain autopilot --install"
  exit 1
fi
exec '${safeGbrainPath}' autopilot --repo '${safeRepoPath}'
`;
  writeFileSync(wrapperPath, wrapper, { mode: 0o755 });
  return wrapperPath;
}

async function installDaemon(engine: BrainEngine, args: string[]) {
  // #677: on a PGLite brain the autopilot daemon would hold the single-writer
  // DB lock for its lifetime — every other gbrain process (serve, search,
  // sweep, embed) then fails to connect. Refuse with guidance; --force for
  // operators who genuinely want a daemon-owned brain.
  const guardMsg = pgliteDaemonGuardMessage(engine.kind, args.includes('--force'));
  if (guardMsg) exitCliError(autopilotPgliteRefusal(guardMsg), 'autopilot');
  const rawRepoPath = parseArg(args, '--repo') || await installRepoFallback(engine);
  if (!rawRepoPath) exitCliError(autopilotNoRepoRefusal(engine.kind), 'autopilot');
  // #3696: the daemon runs with an arbitrary cwd (launchd: `/`), so a
  // relative `--repo .` baked into the wrapper script resolves to a phantom
  // path at daemon runtime. Resolve NOW, against the installer's cwd.
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- rawRepoPath is the local operator's own --repo CLI arg, the operator-written sync.repo_path config row or the default source's local_path; installDaemon is reachable only via `gbrain autopilot --install` on the trusted local CLI (never MCP/remote), and absolutizing it here IS the #3696 fix
  const repoPath = resolvePath(rawRepoPath);

  const forcedTarget = parseArg(args, '--target') as InstallTarget | undefined;
  const target: InstallTarget = forcedTarget ?? detectInstallTarget();

  const injectBootstrap = args.includes('--inject-bootstrap');
  const noInject = args.includes('--no-inject');

  // #5195: every name this brain's job uses (minting the install id on a
  // non-default brain's first install), and a refusal before anything is
  // written when the job under that name runs another live brain.
  const job = resolveAutopilotJob({ mint: true });
  try {
    if (target === 'macos') refuseForeignJob(job.launchdLabel, plistWrapperPath(readIfExists(plistPath(job.launchdLabel)) ?? ''), job);
    if (target === 'linux-systemd') refuseForeignJob(job.systemdUnit, unitWrapperPath(readIfExists(systemdUnitPath(job.systemdUnit)) ?? ''), job);
    if (target === 'ephemeral-container') refuseForeignJob(job.startScriptPath, scriptWrapperPath(readIfExists(job.startScriptPath) ?? ''), job);
  } catch (e) {
    console.error(e instanceof Error ? e.message : String(e));
    process.exit(1);
  }

  if (args.includes('--dry-run')) { console.log(renderInstallDryRun({ target, repoPath, job })); return; }
  if (!await autopilotInstallConsent(engine, args, { target, repoPath, job })) return;
  const wrapperPath = writeWrapperScript(repoPath, target, job);
  // #2608: tell the operator about the deterministic key channel — launchd/
  // systemd don't inherit the login shell env, and rc-file interactive guards
  // routinely swallow exports, so "it works in my terminal" keys often never
  // reach the daemon.
  console.log(
    `API keys: the daemon sources ${join(gbrainHomePath(), 'env')} (plain KEY=value lines, ` +
    `auto-exported) in addition to your shell profile. If LLM phases report no provider, put ` +
    'ANTHROPIC_API_KEY=... (or KEY="$(your-secret-manager get KEY)" to keep it off disk) there and re-run `gbrain autopilot --install`.',
  );
  // A fresh install clears any prior self-disable AND any leaked pause, so a
  // reinstall does not report "disabled" forever or park itself from day one
  // on a marker some dead migration left behind.
  try { unlinkSync(autopilotDisabledMarkerPath()); } catch { /* not disabled */ }
  try { unlinkSync(autopilotPausedMarkerPath()); } catch { /* not paused */ }
  const home = process.env.HOME || '';

  switch (target) {
    case 'macos':
      installLaunchd(wrapperPath, home, repoPath, job);
      break;
    case 'linux-systemd':
      installSystemd(wrapperPath, repoPath, job);
      break;
    case 'ephemeral-container':
      installEphemeralContainer(wrapperPath, home, repoPath, { injectBootstrap, noInject }, job);
      break;
    case 'linux-cron':
      installCrontab(wrapperPath, home, job);
      break;
    default: {
      console.error(`Unknown --target "${forcedTarget}". Allowed: macos, linux-systemd, ephemeral-container, linux-cron.`);
      process.exit(2);
    }
  }
}

/**
 * #677 — PGLite install guard, pure (the unit-test surface). A PGLite brain
 * is single-writer: a daemonized autopilot holds the exclusive DB lock 24/7,
 * so every OTHER gbrain process (`serve`, `search`, `sweep --once`,
 * `embed --stale`) fails to connect for as long as the daemon lives. The
 * supported PGLite background story is `gbrain serve` (resident sweep +
 * serve-delegated sync/sweep over IPC). Returns the refusal message, or null
 * when the install may proceed (postgres engine, or explicit --force).
 */
export function pgliteDaemonGuardMessage(engineKind: string, force: boolean): string | null {
  if (engineKind !== 'pglite' || force) return null;
  return (
    `gbrain autopilot --install: this brain runs on PGLite (single-writer). A daemonized ` +
    `autopilot would hold the exclusive DB lock 24/7 and block every other gbrain ` +
    `process (serve, search, sweep, embed) for as long as it runs.\n` +
    `  Recommended: run \`gbrain serve\` instead — it owns the lock, runs the resident ` +
    `maintenance sweep, and delegates \`gbrain sync\`/\`gbrain sweep --once\` through its ` +
    `IPC socket.\n` +
    `  To install the daemon anyway (dedicated-brain setups), re-run with --force.`
  );
}

// v0.37.7.0 #1162 — pure function for plist generation so tests can
// assert ThrottleInterval/KeepAlive shape without an installed daemon.
// #3696: WorkingDirectory pins the daemon's cwd away from launchd's `/`
// default — but it MUST be a spawn-safe path, NEVER the repo. launchd
// chdir()s before exec, so a WorkingDirectory that stops existing makes
// every (re)spawn fail: after a repo deletion the wrapper — and its
// self-disable guard — would never run again, leaving a zombie KeepAlive
// job that can never take itself out of rotation. $HOME exists for the
// job's whole lifetime; the WRAPPER cd's into the repo AFTER the guard has
// proven it exists (writeWrapperScript). Sync refuses a legacy RELATIVE
// sources.local_path / sync.repo_path row and the guarded readers skip it
// (#7630); the few readers #7646 tracks still resolve one against that cwd.
export function generateLaunchdPlist(wrapperPath: string, home: string, job?: AutopilotJob): string {
  const logPath = job?.logPath ?? `${home}/.gbrain/autopilot.log`;
  const errPath = job?.errPath ?? `${home}/.gbrain/autopilot.err`;
  return `<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>${escapeXml(job?.launchdLabel ?? autopilotLaunchdLabel())}</string>
  <key>ProgramArguments</key><array>
${(job?.launchdViaBash ? ['/bin/bash', wrapperPath] : [wrapperPath]).map(arg => `    <string>${escapeXml(arg)}</string>`).join('\n')}
  </array>
  <key>WorkingDirectory</key><string>${escapeXml(home)}</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <!--
    v0.37.7.0 #1162: ThrottleInterval=60 forces launchd to wait at
    least 60s between relaunches. Combined with the in-process
    classifier (recoverable vs unrecoverable in the supervisor loop),
    this prevents the spinning respawn pattern where an unrecoverable
    error (missing database_url, malformed config) immediately
    relaunched and re-hit the same error. ThrottleInterval is a hard
    floor; launchd would have applied a default of 10s if unset.
  -->
  <key>ThrottleInterval</key><integer>60</integer>
  <key>StandardOutPath</key><string>${escapeXml(logPath)}</string>
  <key>StandardErrorPath</key><string>${escapeXml(errPath)}</string>
</dict>
</plist>`;
}

function installLaunchd(wrapperPath: string, home: string, repoPath: string, job: AutopilotJob) {
  const plist = generateLaunchdPlist(wrapperPath, home, job);

  try {
    const agentsDir = join(home, 'Library', 'LaunchAgents');
    for (const dir of [agentsDir, dirname(job.logPath)]) mkdirSync(dir, { recursive: true });
    replaceLegacySharedJob(job, 'macos');
    writeFileSync(plistPath(job.launchdLabel), plist, { mode: 0o644 });
    // launchd rejects group/world-writable agent plists: bootstrap/load fails
    // with the opaque "Bootstrap failed: 5: Input/output error" and the login
    // scan skips the file silently. writeFileSync's mode only applies on
    // create — a reinstall over an existing plist keeps the old bits (a 0666
    // plist written under an umask-0 parent stays 0666 forever) — so
    // normalize unconditionally.
    chmodSync(plistPath(job.launchdLabel), 0o644);
    // Unload-before-load (same pattern as uninstall): bare `launchctl load`
    // on an already-loaded agent errors and aborted every reinstall — and a
    // running daemon must be relaunched anyway to pick up a regenerated
    // wrapper / env file (#2608: the boot warning tells users to re-run
    // --install to reload; this line is what makes that true on macOS).
    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- launchdLabel comes from autopilotLaunchdLabel(), which rejects anything outside [A-Za-z0-9._-] and '..'; trusted local CLI only
    execSync(`launchctl unload "${plistPath(job.launchdLabel)}" 2>/dev/null || true`, { stdio: 'pipe' });
    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- same grammar-checked label
    execSync(`launchctl load "${plistPath(job.launchdLabel)}"`, { stdio: 'pipe' });
    console.log(`Installed launchd service: ${job.launchdLabel}`);
    console.log(`  Repo: ${repoPath}`);
    console.log(`  Log: ${job.logPath}`);
    console.log('  Uninstall: gbrain autopilot --uninstall');
  } catch (e: unknown) {
    const msg = e instanceof Error ? e.message : String(e);
    if (msg.includes('EACCES') || msg.includes('Permission')) {
      console.error('Permission denied writing plist. Try: mkdir -p ~/Library/LaunchAgents');
    } else {
      console.error(`Failed to install: ${msg}`);
    }
    process.exit(1);
  }
}

/**
 * Generate the gbrain-autopilot systemd user unit.
 *
 * v0.42: `Restart=always` (was `on-failure`). The self-upgrade silent channel
 * does swap-only + `exit(0)` and relies on the supervisor to relaunch the new
 * binary — there is no in-process re-exec (Bun has no `execve`). `on-failure`
 * would NOT relaunch on a clean exit, silently killing the daemon after it
 * upgraded itself. `StartLimitIntervalSec`/`StartLimitBurst` cap a clean-exit
 * respawn storm (systemd's analog to the launchd `ThrottleInterval=60`).
 *
 * Exported so the v0.42 migration can recognize the prior generated shape and
 * rewrite existing `on-failure` units in place.
 */
export function generateSystemdUnit(wrapperPath: string, job?: AutopilotJob): string {
  const logPath = job && job.kind !== 'default' ? job.logPath : '%h/.gbrain/autopilot.log';
  const errPath = job && job.kind !== 'default' ? job.errPath : '%h/.gbrain/autopilot.err';
  return `[Unit]
Description=GBrain Autopilot
After=network-online.target
StartLimitIntervalSec=300
StartLimitBurst=10

[Service]
Type=simple
ExecStart=${wrapperPath}
Restart=always
RestartSec=30
StandardOutput=append:${logPath}
StandardError=append:${errPath}

[Install]
WantedBy=default.target
`;
}

/**
 * v0.42 migration: rewrite an existing `Restart=on-failure` autopilot systemd
 * unit to `Restart=always` so the self-upgrade silent channel's clean
 * exit-for-relaunch actually respawns. HARD-GUARDED: only rewrites a unit that
 * matches the known gbrain-generated shape (never a hand-edited one), only
 * user-level units (never system, never needs root), Linux only. Idempotent:
 * a no-op once already `Restart=always`. Best-effort; called from runPostUpgrade.
 */
export function migrateSystemdUnitToRestartAlways(): { rewritten: boolean; reason: string } {
  if (process.platform !== 'linux') return { rewritten: false, reason: 'not-linux' };
  let unitPath: string;
  try {
    unitPath = systemdUnitPath();
  } catch {
    return { rewritten: false, reason: 'no-unit-path' };
  }
  if (!existsSync(unitPath)) return { rewritten: false, reason: 'no-unit' };
  let content: string;
  try {
    content = readFileSync(unitPath, 'utf8');
  } catch {
    return { rewritten: false, reason: 'unreadable' };
  }
  if (!content.includes('Restart=on-failure')) {
    return { rewritten: false, reason: 'already-migrated' };
  }
  // Hard guard: must look like OUR generated unit, not a hand-edited one.
  const execMatch = content.match(/ExecStart=(\S+)/);
  const looksGenerated =
    content.includes('Description=GBrain Autopilot') &&
    content.includes('StandardOutput=append:%h/.gbrain/autopilot.log') &&
    !!execMatch;
  if (!looksGenerated) {
    process.stderr.write(
      '[gbrain] autopilot systemd unit looks hand-edited; NOT rewriting Restart=on-failure. ' +
        'Set Restart=always manually so self-upgrade relaunch works.\n',
    );
    return { rewritten: false, reason: 'hand-edited' };
  }
  try {
    writeFileSync(unitPath, generateSystemdUnit(execMatch![1]), { mode: 0o644 });
    // This path always rewrites an EXISTING unit, so writeFileSync's mode
    // never applies — chmod is the only thing that normalizes a unit born
    // 0666 under a umask-0 parent (systemd warns on world-writable units).
    chmodSync(unitPath, 0o644);
    try {
      execSync('systemctl --user daemon-reload', { stdio: 'pipe', timeout: 10_000 });
    } catch {
      /* daemon-reload best-effort */
    }
    return { rewritten: true, reason: 'rewritten' };
  } catch (e) {
    return { rewritten: false, reason: e instanceof Error ? e.message : 'write-failed' };
  }
}

function installSystemd(wrapperPath: string, repoPath: string, job: AutopilotJob) {
  const unit = generateSystemdUnit(wrapperPath, job);
  try {
    const unitPath = systemdUnitPath(job.systemdUnit);
    mkdirSync(join(process.env.HOME || '', '.config', 'systemd', 'user'), { recursive: true });
    replaceLegacySharedJob(job, 'linux-systemd');
    writeFileSync(unitPath, unit, { mode: 0o644 });
    // Same umask-0 hardening as the launchd path (systemd warns on
    // world-writable units); mode only applies on create, so normalize.
    chmodSync(unitPath, 0o644);
    execSync('systemctl --user daemon-reload', { stdio: 'pipe', timeout: 10_000 });
    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- systemdUnit is a constant or gbrain-autopilot-<8 hex chars>.service from the install id; trusted local CLI only
    execSync(`systemctl --user enable --now ${job.systemdUnit}`, { stdio: 'pipe', timeout: 15_000 });
    // enable --now does NOT restart an already-active unit, so a reinstall
    // over a running daemon would keep the old process (and its stale env)
    // alive indefinitely (#2608: the boot warning tells users to re-run
    // --install to reload; this line is what makes that true on systemd).
    // try-restart only bounces a running unit — a fresh install just started
    // above is restarted at worst, never left stopped.
    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- same derived unit name
    execSync(`systemctl --user try-restart ${job.systemdUnit}`, { stdio: 'pipe', timeout: 15_000 });
    console.log(`Installed systemd user service: ${job.systemdUnit}`);
    console.log(`  Repo: ${repoPath}`);
    console.log(`  Log: ${job.logPath}`);
    console.log('  Uninstall: gbrain autopilot --uninstall');
  } catch (e: unknown) {
    console.error(`Failed to install systemd unit: ${e instanceof Error ? e.message : e}`);
    console.error('You may need: `loginctl enable-linger $USER` so the unit runs without a login session.');
    process.exit(1);
  }
}

function installEphemeralContainer(
  wrapperPath: string,
  home: string,
  repoPath: string,
  opts: { injectBootstrap: boolean; noInject: boolean },
  job: AutopilotJob,
) {
  // Write a start script the agent's bootstrap can source on every container start.
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- homeDir is configDir() of the local operator's own brain
  const pidPath = join(job.homeDir, 'autopilot.pid');
  const script = `#!/bin/bash
# Auto-generated by gbrain autopilot --install (ephemeral-container target)
# Ephemeral filesystems lose crontab on every deploy; source this from
# your agent's bootstrap instead.
nohup ${shellQuote(wrapperPath)} > ${shellQuote(job.logPath)} 2>&1 &
echo \$! > ${shellQuote(pidPath)}
`;
  const scriptPath = job.startScriptPath;
  mkdirSync(job.homeDir, { recursive: true });
  replaceLegacySharedJob(job, 'ephemeral-container');
  writeFileSync(scriptPath, script, { mode: 0o755 });

  console.log('Ephemeral container detected (Render / Railway / Fly / Docker).');
  console.log(`Repo: ${repoPath}`);
  console.log(`Start script: ${scriptPath}`);
  // Rewriting the start script cannot reload an autopilot already launched
  // from it — that process keeps its old environment until the container
  // restarts. Never auto-kill; say how (#2608, same honesty as the cron path).
  console.log('  An already-running autopilot keeps its old environment until the container');
  console.log(`  restarts (or: kill $(cat ${shellQuote(pidPath)}), then re-run the start script).`);
  console.log('');
  console.log('Crontab is unreliable here (wiped on deploy). Add ONE LINE to your');
  console.log('agent bootstrap to launch autopilot on every start:');
  console.log('');
  console.log(`  bash ${scriptPath}`);
  console.log('');

  // OpenClaw detection + optional auto-injection into ensure-services.sh.
  const { detected, bootstrapCandidates } = detectOpenClaw();
  if (detected) {
    console.log(`OpenClaw detected. Bootstrap candidates found:`);
    for (const p of bootstrapCandidates) console.log(`  - ${p}`);
    console.log('');
  }

  const shouldInject = (injectOpts: { detected: boolean; injectBootstrap: boolean; noInject: boolean }) => {
    if (injectOpts.noInject) return false;
    // Auto-inject by default when OpenClaw is detected + at least one
    // candidate exists. Users can explicitly opt in with --inject-bootstrap
    // on other hosts (uncommon).
    if (injectOpts.detected && bootstrapCandidates.length > 0) return true;
    return injectOpts.injectBootstrap;
  };

  if (shouldInject({ detected, injectBootstrap: opts.injectBootstrap, noInject: opts.noInject })) {
    for (const candidate of bootstrapCandidates) {
      try {
        const existing = readFileSync(candidate, 'utf-8');
        const marker = BOOTSTRAP_MARKER;
        if (existing.includes(`${marker}\nbash ${scriptPath}`)) {
          console.log(`  [skip] ${candidate} already has the gbrain marker`);
          continue;
        }
        // Backup before edit
        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
        const bakPath = `${candidate}.bak.${stamp}`;
        writeFileSync(bakPath, existing);
        const snippet = `\n${marker}\nbash ${scriptPath}\n`;
        writeFileSync(candidate, existing.trimEnd() + snippet);
        console.log(`  [injected] ${candidate} (.bak at ${bakPath})`);
      } catch (e) {
        console.error(`  [warn] failed to inject ${candidate}: ${e instanceof Error ? e.message : e}`);
      }
    }
  }
  console.log('  Uninstall: gbrain autopilot --uninstall');
}

function installCrontab(wrapperPath: string, home: string, job: AutopilotJob) {
  // Linux/WSL without systemd — crontab runs the wrapper every 5 minutes.
  // #5195: a non-default brain's line carries its marker; the default brain's
  // line is unchanged.
  const cronLine = `*/5 * * * * ${shellQuote(wrapperPath)} >> ${shellQuote(job.logPath)} 2>&1${job.cronMarker ? ` ${job.cronMarker}` : ''}`;
  try {
    let existing = execSync('crontab -l 2>/dev/null || true', { encoding: 'utf-8' });
    // A line of this brain is stale when it predates the brain's marker (a
    // pre-#5195 shared line) or runs a wrapper that is not this brain's
    // current one (the brain moved): either is replaced, never duplicated.
    const ownLines = existing.split('\n').filter(l => cronLineBelongsToBrain(l, job));
    const staleLines = ownLines.filter(l =>
      (job.cronMarker !== null && !l.includes(job.cronMarker)) || (scriptWrapperPath(l) !== null && scriptWrapperPath(l) !== wrapperPath));
    if (staleLines.length > 0) {
      existing = existing.split('\n').filter(l => !staleLines.includes(l)).join('\n');
      console.log(`Replacing ${staleLines.length} crontab line(s) that ran this brain from an older install with its current line.`);
    } else if (ownLines.length > 0) {
      console.log('Crontab entry already exists. Remove with: gbrain autopilot --uninstall');
      // The wrapper (and env template) were regenerated above, but cron
      // cannot reload a loop that is already running — it keeps its old
      // environment until it exits. Never auto-kill a user process; tell
      // them exactly how (#2608: makes the boot warning's re-run---install
      // remediation honest on the cron target).
      console.log(`  A running autopilot loop keeps its old environment until it exits — end it with: kill $(cat '${autopilotLockPath().replace(/'/g, "'\\''")}')`);
      console.log('  The next cron tick relaunches it with the refreshed wrapper and env file.');
      return;
    }
    // Use a temp file instead of echo pipe to avoid shell escaping issues (#1)
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- homeDir is configDir() of the local operator's own brain
    const tmpFile = join(job.homeDir, 'crontab.tmp');
    mkdirSync(job.homeDir, { recursive: true });
    writeFileSync(tmpFile, existing.trimEnd() + '\n' + cronLine + '\n');
    execSync(`crontab '${tmpFile.replace(/'/g, "'\\''")}'`, { stdio: 'pipe' });
    try { unlinkSync(tmpFile); } catch { /* best-effort */ }
    console.log('Installed crontab entry for gbrain autopilot (every 5 minutes)');
    console.log('  Uninstall: gbrain autopilot --uninstall');
  } catch (e: unknown) {
    console.error(`Failed to install crontab: ${e instanceof Error ? e.message : e}`);
    process.exit(1);
  }
}

/**
 * The status verdict, engine-free. Dispatched BEFORE connectEngine in cli.ts:
 * a running PGLite daemon holds the exclusive DB lock, so an engine-bound
 * status could not run against a healthy live install — and a DB outage would
 * take down the very alarm meant to diagnose it. Everything it reads is
 * filesystem (lock mtime, markers, plist/unit/crontab, log tail).
 */
export function runAutopilotStatus(args: string[]): void {
  // An INSTALLED daemon always runs the default interval — the generated
  // wrapper execs `autopilot --repo <path>` with no --interval. The flag is
  // honored here for the manual foreground case. Garbage input must not
  // become NaN: staleAfter = NaN makes every age comparison false, which
  // reads a 71-day-dead daemon as 'fresh' with exit 0 — a typo'd flag would
  // silently disable the very alarm this exit code exists to be.
  const rawInterval = parseInt(parseArg(args, '--interval') || '300', 10);
  showStatus(args.includes('--json'), Number.isFinite(rawInterval) && rawInterval > 0 ? rawInterval : 300);
}

export function uninstallDaemon() {
  // #5195: only this brain's job is removed — its own named job (checked to
  // run this brain's wrapper before removal), plus, for a non-default brain,
  // a pre-#5195 shared-name job whose wrapper names this brain. A shared job
  // that runs another live brain is left alone and named.
  const job = resolveAutopilotJob();
  const wrapperPath = job.wrapperPath;
  const ownsDefinition = (name: string, wrapper: string | null): boolean => {
    const owner = autopilotWrapperOwner(wrapper, job.homeDir);
    if (owner.owner !== 'other') return true;
    console.log(`Left ${name} in place: it runs the brain at ${owner.home}. To remove it: ${brainCommand(owner.home, '--uninstall')}`);
    return false;
  };
  const legacyOnly = (wrapper: string | null) => autopilotWrapperOwner(wrapper, job.homeDir).owner === 'own';
  const assigned = job.kind !== 'unassigned';

  // Always try all four targets — the user might have run `--install` under
  // one target earlier and moved hosts (e.g. macOS laptop → Linux server).
  // Each path is idempotent (missing files = skip silently).

  let removed = 0;

  // macOS launchd
  const labels: Array<{ label: string; legacy: boolean }> = [];
  if (assigned) labels.push({ label: job.launchdLabel, legacy: false });
  if (job.kind !== 'default' && (!assigned || autopilotLaunchdLabel(null) !== job.launchdLabel)) labels.push({ label: autopilotLaunchdLabel(null), legacy: true });
  for (const { label, legacy } of labels) {
    const path = plistPath(label);
    if (!existsSync(path)) continue;
    const wrapper = plistWrapperPath(readIfExists(path) ?? '');
    if (legacy ? !legacyOnly(wrapper) : !ownsDefinition(label, wrapper)) continue;
    try {
      execSync(`launchctl unload "${path}" 2>/dev/null || true`, { stdio: 'pipe' });
      unlinkSync(path);
      console.log(`Removed launchd service: ${label}`);
      removed++;
    } catch (e) {
      console.error(`  [warn] launchd: ${e instanceof Error ? e.message : e}`);
    }
  }

  // Linux systemd user unit
  const units: Array<{ unit: string; legacy: boolean }> = [];
  if (assigned) units.push({ unit: job.systemdUnit, legacy: false });
  if (job.kind !== 'default') units.push({ unit: DEFAULT_AUTOPILOT_SYSTEMD_UNIT, legacy: true });
  for (const { unit, legacy } of units) {
    const path = systemdUnitPath(unit);
    if (!existsSync(path)) continue;
    const wrapper = unitWrapperPath(readIfExists(path) ?? '');
    if (legacy ? !legacyOnly(wrapper) : !ownsDefinition(unit, wrapper)) continue;
    try {
      execSync(`systemctl --user disable --now ${unit} 2>/dev/null || true`, { stdio: 'pipe', timeout: 10_000 });
      unlinkSync(path);
      try { execSync('systemctl --user daemon-reload', { stdio: 'pipe', timeout: 5_000 }); } catch { /* best-effort */ }
      console.log(`Removed systemd user service: ${unit}`);
      removed++;
    } catch (e) {
      console.error(`  [warn] systemd: ${e instanceof Error ? e.message : e}`);
    }
  }

  // Ephemeral container start script + bootstrap marker injection
  const scripts: Array<{ path: string; legacy: boolean }> = [];
  if (assigned) scripts.push({ path: job.startScriptPath, legacy: false });
  if (job.kind !== 'default') scripts.push({ path: legacyStartScriptPath(), legacy: true });
  for (const { path, legacy } of scripts) {
    if (!existsSync(path)) continue;
    const wrapper = scriptWrapperPath(readIfExists(path) ?? '');
    if (legacy ? !legacyOnly(wrapper) : !ownsDefinition(path, wrapper)) continue;
    try {
      unlinkSync(path);
      console.log(`Removed ephemeral start script: ${path}`);
      removed++;
    } catch (e) {
      console.error(`  [warn] start script: ${e instanceof Error ? e.message : e}`);
    }
    // Remove marker-lines from any OpenClaw bootstrap we previously injected.
    removed += stripBootstrapLines(path);
  }

  // Linux crontab (don't gate on platform — the user may have run `--install
  // --target linux-cron` on a different machine that now has the crontab).
  try {
    const existing = execSync('crontab -l 2>/dev/null || true', { encoding: 'utf-8' });
    const lines = existing.split('\n');
    const filtered = lines.filter(l => !cronLineBelongsToBrain(l, job));
    if (filtered.length !== lines.length) {
      const tmpFile = join(job.homeDir, 'crontab.tmp');
      mkdirSync(job.homeDir, { recursive: true });
      writeFileSync(tmpFile, filtered.join('\n'));
      execSync(`crontab '${tmpFile.replace(/'/g, "'\\''")}' 2>/dev/null || true`, { stdio: 'pipe' });
      try { unlinkSync(tmpFile); } catch { /* best-effort */ }
      console.log('Removed crontab entry for gbrain autopilot');
      removed++;
    }
  } catch (e) {
    console.error(`  [warn] crontab: ${e instanceof Error ? e.message : e}`);
  }

  // Wrapper script — shared by all targets
  if (existsSync(wrapperPath)) {
    try {
      unlinkSync(wrapperPath);
    } catch { /* best-effort */ }
  }

  if (removed === 0) {
    console.log('No autopilot install found for this brain. Nothing to uninstall.');
  }

  // A deliberate uninstall ends the disabled/paused story: without this, a
  // self-disabled install that is then uninstalled keeps reporting
  // "DISABLED — repo path gone" with exit 2 forever on a machine with nothing
  // installed ('disabled' outranks 'not_installed' in the classifier).
  try { unlinkSync(autopilotDisabledMarkerPath()); } catch { /* not present */ }
  try { unlinkSync(autopilotPausedMarkerPath()); } catch { /* not present */ }
}

/**
 * The daemon's view of WHICH engine the file-plane config points at. Pure and
 * deliberately narrow: only the fields an engine migration flips participate,
 * so unrelated config edits (models, search knobs, spend gates) never trigger
 * a restart. Compared at boot vs every tick by the daemon loop.
 */
export function autopilotEngineIdentity(
  cfg: { engine?: string; database_url?: string; database_path?: string } | null,
): string {
  return JSON.stringify({
    engine: cfg?.engine ?? 'pglite',
    url: cfg?.database_url ?? null,
    path: cfg?.database_path ?? null,
  });
}

export type AutopilotState = 'not_installed' | 'disabled' | 'paused' | 'never_run' | 'stale' | 'fresh';

export interface AutopilotStatusReport {
  installed: boolean;
  install_target: InstallTarget | null;
  state: AutopilotState;
  disabled_reason: string | null;
  paused_reason: string | null;
  heartbeat_age_seconds: number | null;
  stale_after_seconds: number;
  /** #7003: threshold from the running daemon's heartbeat sidecar or the --interval flag; its next tick while it sleeps. */
  stale_after_source: 'daemon' | 'flag';
  next_tick_at: string | null;
  last_log: string;
}

/**
 * Exit codes for `gbrain autopilot --status`, so cron and CI can gate on it.
 *   0 — fresh, or nothing installed (nothing claimed, nothing broken)
 *   1 — installed but not syncing (stale heartbeat, never ran, or parked on a
 *       cooperative pause marker — a live migrate, or one that died without
 *       cleaning up; either way the brain is not being kept current)
 *   2 — the daemon took itself out of rotation (repo gone)
 * A daemon that ticks but reports brain-wide maintenance stalled (its latest
 * verdict file, GBRA-130 C-6) turns a 0 into 1.
 */
export function autopilotStatusExitCode(state: AutopilotState, globalMaintenanceStalled = false): number {
  if (state === 'disabled') return 2;
  if (state === 'stale' || state === 'never_run' || state === 'paused') return 1;
  return globalMaintenanceStalled ? 1 : 0;
}

/**
 * Pure classifier so the tri-state is testable without an installed daemon.
 *
 * The heartbeat is the lock mtime, which the tick loop already refreshes every
 * pass (`utimesSync(lockPath, ...)`). #7003: the threshold comes from the
 * daemon's own heartbeat sidecar when one matches the lock (its next tick, so an
 * adaptive 2x sleep is not stale); a missing, foreign or older sidecar (a daemon
 * still on a pre-#7003 binary) falls back to the flag rule below, so liveness
 * never depends on the sidecar existing.
 */
export function classifyAutopilotStatus(input: {
  installed: boolean;
  installTarget: InstallTarget | null;
  disabledReason: string | null;
  pausedReason?: string | null;
  heartbeatAgeSeconds: number | null;
  intervalSeconds: number;
  /** #7003: the running daemon's own threshold (autopilot-heartbeat.ts daemonStaleAfterSeconds); wins over intervalSeconds. */
  daemon?: { staleAfter: number; nextTickAt: string | null } | null;
  lastLog: string;
}): AutopilotStatusReport {
  // Tolerance = 6 intervals. The adaptive scheduler sleeps TWO intervals
  // between ticks on the healthiest brains (score >= 90), and the heartbeat
  // only refreshes at tick top — so a healthy gap is cycle_duration + 2x
  // interval, and a 3x tolerance would flap 'stale' exit-1 alarms on exactly
  // the installs doing best. 6x still catches the dead-daemon incident in
  // 30 minutes at the default interval instead of 71 days. A non-finite or
  // non-positive interval (a typo'd flag upstream) would make staleAfter NaN
  // and every age comparison false — reading a long-dead daemon as 'fresh' —
  // so the pure layer defends itself too.
  const daemon = input.daemon && Number.isFinite(input.daemon.staleAfter) && input.daemon.staleAfter > 0 ? input.daemon : null;
  const staleAfter = daemon ? daemon.staleAfter
    : Number.isFinite(input.intervalSeconds) && input.intervalSeconds > 0
    ? input.intervalSeconds * 6
    : 1800;
  const pausedReason = input.pausedReason ?? null;
  let state: AutopilotState;
  if (input.disabledReason !== null) state = 'disabled';
  else if (!input.installed) state = 'not_installed';
  // Paused outranks the heartbeat states: the tick loop refreshes its
  // heartbeat BEFORE honoring the pause marker, so a parked daemon looks
  // 'fresh' by mtime while doing no work. Without this state a pause marker
  // orphaned by a dead migrate is invisible — the daemon idles forever and
  // status swears everything is fine (the 71-day incident's shape again).
  else if (pausedReason !== null) state = 'paused';
  else if (input.heartbeatAgeSeconds === null) state = 'never_run';
  else state = input.heartbeatAgeSeconds > staleAfter ? 'stale' : 'fresh';

  return {
    installed: input.installed,
    install_target: input.installTarget,
    state,
    disabled_reason: input.disabledReason,
    paused_reason: pausedReason,
    heartbeat_age_seconds: input.heartbeatAgeSeconds,
    stale_after_seconds: staleAfter,
    stale_after_source: daemon ? 'daemon' : 'flag',
    next_tick_at: daemon?.nextTickAt ?? null,
    last_log: input.lastLog,
  };
}

function showStatus(json: boolean, intervalSeconds: number) {
  // gbrainHomePath, not raw HOME: the daemon writes its lock through
  // gbrainHomePath() (#1226), so a GBRAIN_HOME install had status reading one
  // directory while the daemon wrote another — a permanent false "stale".
  // #5195: every log sink writes under the brain's own home, so the log is
  // read only there (a raw-$HOME fallback would show another brain's log).
  const job = resolveAutopilotJob();
  let lastLine = '';
  try {
    const content = readFileSync(job.logPath, 'utf-8');
    const lines = content.trim().split('\n');
    lastLine = lines[lines.length - 1] || '';
  } catch { /* no log yet */ }

  let disabledReason: string | null = null;
  try {
    disabledReason = readFileSync(autopilotDisabledMarkerPath(), 'utf-8').trim() || null;
  } catch { /* not self-disabled */ }

  const pausedReason = autopilotPauseReason();

  let heartbeatAgeSeconds: number | null = null;
  try {
    const { mtimeMs } = statSync(autopilotLockPath());
    heartbeatAgeSeconds = Math.max(0, Math.floor((Date.now() - mtimeMs) / 1000));
  } catch { /* never ran, or already cleaned up */ }

  const jobStatus = autopilotJobStatus(job);
  const installTarget = jobStatus.installTarget;
  const report = classifyAutopilotStatus({
    installed: installTarget !== null,
    installTarget,
    disabledReason,
    pausedReason,
    heartbeatAgeSeconds,
    intervalSeconds,
    daemon: readDaemonStaleAfter(),
    lastLog: lastLine,
  });
  const processing = readAutopilotProcessingStatus();
  const globalMaintenance = readGlobalMaintenanceVerdict();
  const stalled = globalMaintenance !== null && globalMaintenance.status !== 'ok';

  if (json) {
    console.log(JSON.stringify({ ...report, ...processing, job: jobStatus.report, global_maintenance: globalMaintenance }));
  } else {
    switch (report.state) {
      case 'not_installed':
        console.log('Autopilot: not installed. Install with `gbrain autopilot --install`.');
        break;
      case 'disabled':
        console.log(`Autopilot: DISABLED — ${report.disabled_reason}`);
        console.log('  It stopped itself. Fix the path, then `gbrain autopilot --install --repo <path>`.');
        break;
      case 'paused':
        console.log(`Autopilot: PAUSED — ${report.paused_reason}`);
        if (report.paused_reason?.startsWith('operator pause')) { console.log('  Operator pause on this host. Resume with: gbrain autopilot resume'); break; }
        console.log('  A pause marker is parked at ' + autopilotPausedMarkerPath() + '. Normal while `gbrain migrate` runs. A marker orphaned by a dead migration');
        console.log('  clears itself on the daemon\'s next poll; only remove it by hand if the');
        console.log('  pid it names is dead and no daemon is running to clean it up.');
        break;
      case 'never_run':
        console.log(`Autopilot: installed (${report.install_target}) but has NEVER run.`);
        break;
      case 'stale':
        console.log(
          `Autopilot: installed (${report.install_target}) but NOT ticking — last heartbeat ` +
          `${report.heartbeat_age_seconds}s ago (stale after ${report.stale_after_seconds}s).`,
        );
        break;
      case 'fresh':
        console.log(
          `Autopilot: running (${report.install_target}) — last heartbeat ` +
          `${report.heartbeat_age_seconds}s ago.`,
        );
        break;
    }
    if (processing) {
      console.log(`Processing: ${processing.processing_state}${processing.reason_code ? ` (${processing.reason_code})` : ''}`);
      console.log(`Stage: ${processing.processing_stage}${processing.retry_at ? `; next retry ${processing.retry_at}` : ''}`);
      if (processing.processing_state === 'configuration_blocked') console.log('Repair the worker and selected child installation, then explicitly restart autopilot.');
    }
    for (const line of jobStatus.lines) console.log(line);
    if (stalled) console.log(`Global maintenance: ${globalMaintenance.status.toUpperCase()}. ${globalMaintenance.message}`);
    if (lastLine) console.log(`Last log: ${lastLine}`);
  }

  setCliExitVerdict(autopilotStatusExitCode(report.state, stalled));
}

function escapeXml(s: string): string {
  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
}