Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
29.3 KB
Raw Blame
/**
 * CLI startup preflight — the FIRST statement of `cli.ts:main()`, before
 * global-flag parsing and any command dispatch. Ordered steps:
 *
 *   0. Sanitized re-run detection. When this process IS the re-run described
 *      in step 1b (verified, never trusted on the marker's say-so — see
 *      "Loop guard"), switch back to the caller's directory, arm the
 *      die-with-wrapper watchdog (see "Die with the wrapper") and skip step 1:
 *      the parent already quarantined and warned.
 *   1. `quarantineCwdDotenv()` — drop every protected key (env-trust.ts: the
 *      security-relevant GBRAIN_* keys plus the loader / git / node / XDG /
 *      TLS-trust / proxy / AI-endpoint hijack families) that a `.env` in the
 *      cwd assigns. GBRAIN_HOME is on that list, so it is quarantined BEFORE
 *      step 2 resolves the config dir. The 8 cwd .env files are parsed ONCE
 *      here and the parse is shared with the cwd == config dir check.
 *   1b. Re-run gbrain with the sanitized environment whenever anything was
 *      dropped (see "Why the re-run" below).
 *   2. `loadGbrainEnvFile(configDir)` — fill process.env from `~/.gbrain/.env`
 *      (never overriding an exported variable). `loadConfig()` does this too,
 *      but the guardrails loader in step 3 runs before any `loadConfig()`;
 *      without this step `~/.gbrain/.env` could not be the operator's home
 *      for GBRAIN_GUARDRAILS_MODULE.
 *   3. The #3688 guardrails loader (moved from cli.ts; now passes
 *      `skipCwdCheck`). Fail-closed: set-but-broken aborts rather than
 *      silently running without the operator's firewall; unset costs nothing.
 *
 * Fail-closed corollary of step 1 (see "GBRAIN_GUARDRAILS_MODULE" below): when
 * the quarantine dropped a NON-EMPTY `GBRAIN_GUARDRAILS_MODULE`, preflight
 * refuses to run at all instead of re-running without it.
 *
 * Every runtime entry — commands, `hook *`, `serve` (stdio and --http),
 * `mcp`, the supervisor-spawned `jobs work`, the per-job `jobs run-child` —
 * dispatches through `main()`, so this one call covers every gbrain process.
 * (`src/commands/auth.ts`'s `import.meta.main` seam is a dev-only
 * direct-script entry.)
 *
 * ## Why the re-run (step 1b)
 *
 * Deleting a key from process.env changes only THIS process's view. Bun hands
 * every child spawned without an explicit `env` option the environ snapshot
 * it took at startup — cwd-.env values included — so git, the claude CLI and
 * workers would still see the planted keys (verified on Bun 1.3.13: a `.env`
 * carrying `GIT_CONFIG_COUNT=1 / GIT_CONFIG_KEY_0=core.fsmonitor /
 * GIT_CONFIG_VALUE_0=./x.sh` runs x.sh from a plain `git status`). When the
 * quarantine dropped anything, preflight therefore spawns gbrain again with
 * an explicit, sanitized environment and exits with the re-run's status;
 * every descendant of the re-run inherits the clean view.
 *
 * The re-run starts in a NEUTRAL cwd: a fresh, empty `mkdtemp` directory that
 * is ours and by construction holds none of the `.env` family. Bun loads
 * `.env` from the process cwd only (no parent walk — verified on 1.3.13), so
 * the re-run's Bun never sees the hostile file and its environ simply LACKS
 * the dropped keys. They are deleted, never carried as empty strings: git and
 * the dynamic loader PRESENCE-check some of them (`GIT_SSL_NO_VERIFY=`
 * disables TLS verification, `LD_TRACE_LOADED_OBJECTS=` turns every
 * dynamically linked child into ldd, `GIT_DIR=` / `GIT_AUTHOR_NAME=` are hard
 * errors), so `''` would not have been neutral. Preflight in the re-run then
 * `chdir`s back to the caller's directory before anything else runs, so
 * relative arguments resolve exactly as typed. Nothing in cli.ts's import
 * graph captures `process.cwd()` at module-evaluation time (audited); every
 * read happens after this chdir.
 *
 * ## Loop guard
 *
 * The re-run carries `GBRAIN_CWD_ENV_QUARANTINED=<JSON {cwd, neutral,
 * wrapperPid}>`. The marker is NOT trusted by itself — a hostile .env could
 * plant one (the key is also on the protected list, so a planted copy is
 * dropped and named in the warning). It is honoured only when ALL of: it
 * parses to two strings (`wrapperPid` is informational — a positive integer
 * or ignored), this process's startup cwd IS `neutral` (realpath-compared),
 * and `neutral` contains none of the `.env` family. A process started from a hostile
 * directory fails the second check (its startup cwd has a `.env`) and the
 * third if it names its own directory — so it ignores the marker entirely
 * and never chdirs on one. Termination is structural: the re-run's startup
 * cwd has no `.env`, so it never drops anything and never re-runs. gbrain
 * self-spawns (supervisor → worker, hook → detached push, worker →
 * run-child) that start in the hostile cwd reload the file and perform the
 * hop once for their own subtree — accepted; one warning per subtree.
 *
 * ## Signals
 *
 * Handlers are installed BEFORE the spawn (a signal in the gap would take the
 * default action, kill the wrapper and orphan the re-run). The wrapper has no
 * duties of its own, so every listener some earlier module attached for the
 * forwarded signals is removed first: cli.ts installs its cleanup handlers
 * (process-cleanup.ts, SIGTERM → exit 143 / SIGHUP → exit 129) in its
 * `import.meta.main` block before `main()` reaches this preflight, and with
 * both attached a SIGTERM made the wrapper exit 143 before the re-run had
 * finished and before the neutral dir was removed. The wrapper's exit is
 * ALWAYS the child's. SIGTERM and SIGHUP — which a supervisor sends to the
 * wrapper pid alone — are always forwarded. SIGINT depends on whether the
 * process has a CONTROLLING TERMINAL (probed by opening `/dev/tty`; the
 * stdio `isTTY` flags on Windows), not on whether stdin is a tty:
 *   - a controlling terminal exists: the re-run shares the wrapper's
 *     foreground process group, so the terminal delivers Ctrl-C to it
 *     directly — ALSO when stdin/stdout/stderr are redirected
 *     (`serve --http </dev/null >log 2>&1` in a foreground shell). The wrapper
 *     does NOT forward (a second delivery would consume a `once('SIGINT')`
 *     graceful-shutdown handler such as serve-http's and turn Ctrl-C into an
 *     abrupt kill) and ignores the signal itself so it survives to relay the
 *     re-run's exit status.
 *   - no controlling terminal (a supervisor, cron, a detached agent harness):
 *     nothing does process-group delivery, so a SIGINT that reaches the
 *     wrapper pid alone would otherwise orphan the re-run. Each received
 *     SIGINT is forwarded once. (A harness that signals the whole group
 *     instead delivers twice here — accepted: no terminal, no graceful Ctrl-C
 *     expectation. A harness WITH a controlling terminal that signals the
 *     wrapper pid alone with SIGINT is not forwarded — the terminal is the
 *     delivery channel there; SIGTERM is what such harnesses send to stop a
 *     child, and it is always forwarded.)
 * Exit status: the re-run's code, or 128+signal when a signal killed it
 * (shell convention).
 *
 * ## Die with the wrapper
 *
 * SIGKILL cannot be forwarded. A supervisor that tracks the pid it spawned —
 * the WRAPPER's — and escalates to SIGKILL (minions/supervisor.ts
 * `restartCurrentChild`, job-isolation children, hook pushes) would leave the
 * real re-run running as an orphan while a replacement starts. So the marker
 * carries the wrapper's pid and a VERIFIED re-run arms a watchdog: every
 * second it compares `process.ppid` with that pid (Bun's `process.ppid` is
 * live — it flips to the reaper's pid once the parent is gone, whether it
 * exited or was killed; verified on 1.3.13) and, when they differ, prints one
 * line, removes the now-orphaned neutral dir (`rmdirSync` — it is empty by
 * construction, and a non-recursive remove can never take anything else
 * with it) and exits 137, mirroring the SIGKILL the wrapper took. The timer
 * is `unref()`ed so it never keeps a finished command alive. A marker without
 * a usable `wrapperPid` (planted, foreign, older) arms nothing.
 *
 * ## Runtime flags across the hop
 *
 * `bun <flags> src/cli.ts` re-inserts `process.execArgv` into the re-run (a
 * compiled binary has none). Bun reports path-bearing flags verbatim in both
 * spellings (`["--preload", "./x"]` and `["--preload=./x"]`) and resolves a
 * relative value against the process cwd — which for the re-run is the EMPTY
 * neutral dir, so `--preload ./probe.ts` died with `preload not found`. For
 * `--preload`/`-r`/`--require`/`--import`, `--config`/`-c`, `--env-file` and
 * `--tsconfig-override`, a value that is `./`- or `../`-relative, or a bare
 * relative name that exists in the original cwd, is resolved against the
 * ORIGINAL cwd; absolute values, bare package specifiers and every other
 * flag pass through untouched, in order.
 *
 * ## HOME after the drop
 *
 * HOME / USERPROFILE are on the protected list (a cron/systemd unit often has
 * HOME unset, and a planted value then reaches process.env and every child).
 * Dropping them must not leave the re-run with NO home at all: git fails
 * (`Author identity unknown`, `$HOME not set`) and every raw
 * `process.env.HOME || ''` read resolves cwd-relative INTO the checkout. So
 * when the quarantine dropped HOME (USERPROFILE on Windows), the sanitized env
 * gets it back from `os.userInfo().homedir` — Bun derives that from the REAL
 * startup environ (passwd when the variable was unset) BEFORE the .env merge,
 * so the planted value never reaches it (verified on Bun 1.3.13). Only a
 * DROPPED key is restored: a home that was simply never set stays unset, so a
 * hopped run and a plain run see the same environment.
 *
 * ## Script mode + cwd bunfig.toml
 *
 * The compiled binary is built with `--no-compile-autoload-bunfig`, so a cwd
 * `bunfig.toml` is inert for it. The documented install (`bun install -g
 * github:…`, `git clone` + `bun link`) maps the `gbrain` bin to src/cli.ts,
 * which runs as an ordinary Bun SCRIPT — and for a script Bun applies the cwd
 * bunfig.toml before any of the script's code: a top-level `preload` has
 * already run by the time preflight starts. Nothing here can undo that; only
 * `bun --config=/dev/null <entry>` suppresses it (verified on Bun 1.3.13: no
 * `-c`/`--no-bunfig` spelling and no `BUN_CONFIG_*` variable does). What
 * preflight CAN do is say so: when it detects the shape (script runtime + a
 * top-level `preload` in the startup cwd's bunfig.toml) it prints one stderr
 * line. The checkout that contains the running entry itself (a contributor's
 * own repo, whose bunfig is theirs) is exempt; the sanitized re-run started in
 * the neutral dir never saw a bunfig and does not repeat the warning.
 *
 * ## GBRAIN_GUARDRAILS_MODULE: fail closed, not open
 *
 * The quarantine is key-presence: when a cwd .env assigns the key, the value
 * in process.env is dropped whether it came from the file or from the
 * operator's shell (Bun merges the file before any code runs and never
 * overrides a live variable, so the two are indistinguishable). For every
 * other protected key a false drop is a loud downgrade with the fix in the
 * warning. For THIS key it would be the opposite of the #3688 contract: the
 * re-run would simply have no module and run without the operator's firewall,
 * with nothing but a stderr line. So when a non-empty value was dropped,
 * preflight refuses to run (exit 1). A benign repository never assigns this
 * gbrain-specific key, and the `~/.gbrain/.env` home is unaffected: it is
 * read AFTER the quarantine (step 2), never dropped by it.
 *
 * Zero cost on the normal path: no .env in the cwd, or nothing protected
 * assigned there, means no spawn.
 *
 * ## cwd == config dir
 *
 * Running gbrain from INSIDE `~/.gbrain` (or `$GBRAIN_HOME/.gbrain`) makes Bun
 * load the operator's own `.env` as a "cwd .env". That file is operator-owned,
 * so the quarantine and the guardrails loader's cwd check are skipped when
 * `realpath(cwd) === realpath(configDir())` — but ONLY when no cwd .env file
 * assigns any key the config dir is DERIVED from: GBRAIN_HOME, HOME or
 * USERPROFILE (a hostile checkout laid out as `<checkout>/.gbrain` could
 * otherwise try to point the home at itself to manufacture the collision; a
 * planted home is never the operator's config dir). Measured on Bun 1.3.13,
 * `os.homedir()` is captured from the real startup environ before the .env
 * merge, so a planted HOME does not actually reach `configDir()` — the check
 * is belt-and-braces against that implementation detail changing.
 */
import { closeSync, constants as fsConstants, existsSync, mkdtempSync, openSync, readFileSync, realpathSync, rmdirSync, rmSync } from 'fs';
import { constants as osConstants, homedir, tmpdir, userInfo } from 'os';
import { dirname, isAbsolute, join, resolve } from 'path';
import {
  CWD_DOTENV_FILES,
  cwdDotenvAssignsKey,
  parseCwdDotenv,
  quarantineCwdDotenv,
  type DotenvAssignment,
} from './env-trust.ts';
import { loadGbrainEnvFile } from './gbrain-env-file.ts';
import { configDir } from './config.ts';
import { bunSpawn } from './spawn.ts';

/**
 * Set on the sanitized re-run to `JSON {cwd, neutral}` (see "Loop guard").
 * Internal — not a setting; verified against the startup cwd, never trusted.
 */
export const CWD_ENV_QUARANTINED_MARKER = 'GBRAIN_CWD_ENV_QUARANTINED';

interface HopMarker {
  /** The caller's directory the re-run must switch back to. */
  cwd: string;
  /** The fresh empty directory the re-run was started in. */
  neutral: string;
  /** The wrapper's pid, for the die-with-wrapper watchdog; absent → no watchdog. Informational, not part of verification. */
  wrapperPid?: number;
}

function parseHopMarker(raw: string | undefined): HopMarker | null {
  if (!raw) return null;
  try {
    const v: unknown = JSON.parse(raw);
    if (
      v !== null && typeof v === 'object' &&
      typeof (v as HopMarker).cwd === 'string' && (v as HopMarker).cwd !== '' &&
      typeof (v as HopMarker).neutral === 'string' && (v as HopMarker).neutral !== ''
    ) {
      const marker: HopMarker = { cwd: (v as HopMarker).cwd, neutral: (v as HopMarker).neutral };
      const pid = (v as HopMarker).wrapperPid;
      if (typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0) marker.wrapperPid = pid;
      return marker;
    }
  } catch {
    // not JSON — a planted or foreign value; ignored
  }
  return null;
}

const WRAPPER_WATCHDOG_INTERVAL_MS = 1000;

/** See "Die with the wrapper". Only ever called for a VERIFIED hop. */
function installWrapperWatchdog(hop: HopMarker): void {
  const wrapperPid = hop.wrapperPid;
  if (wrapperPid === undefined) return;
  const t = setInterval(() => {
    if (process.ppid === wrapperPid) return;
    console.error('[env] sanitized re-run lost its wrapper (killed); exiting');
    try { rmdirSync(hop.neutral); } catch { /* already gone, or not empty — never ours to force */ }
    process.exit(137);
  }, WRAPPER_WATCHDOG_INTERVAL_MS);
  t.unref(); // must never keep a finished command alive
}

/**
 * The marker, but ONLY when this process provably is the re-run: it started
 * inside the neutral dir the marker names, and that dir holds no .env family
 * member. Anything else (absent, malformed, planted from a hostile cwd) → null.
 */
function verifiedHop(startupCwd: string): HopMarker | null {
  const marker = parseHopMarker(process.env[CWD_ENV_QUARANTINED_MARKER]);
  if (!marker) return null;
  try {
    if (realpathSync(startupCwd) !== realpathSync(marker.neutral)) return null;
  } catch {
    return null;
  }
  for (const name of CWD_DOTENV_FILES) {
    if (existsSync(join(marker.neutral, name))) return null;
  }
  return marker;
}

/** The keys `configDir()` is derived from; a cwd .env assigning any of them forfeits the cwd == config dir exemption. */
const CONFIG_DIR_SOURCE_KEYS: readonly string[] = ['GBRAIN_HOME', 'HOME', 'USERPROFILE'];

/**
 * True when `cwd` IS the operator's config dir (see "cwd == config dir") and
 * no cwd .env file assigns a key the config dir is derived from. Exported for
 * tests.
 */
export function cwdIsOperatorConfigDir(cwd: string, assignments: readonly DotenvAssignment[]): boolean {
  for (const key of CONFIG_DIR_SOURCE_KEYS) {
    if (cwdDotenvAssignsKey(key, assignments)) return false;
  }
  try {
    return realpathSync(cwd) === realpathSync(configDir());
  } catch {
    return false; // invalid GBRAIN_HOME or a config dir that does not exist yet — no collision
  }
}

/**
 * argv (after execPath) that runs THIS gbrain again. A compiled Bun binary
 * reports its virtual entrypoint as argv[1] (`/$bunfs/root/...`; `~BUN` on
 * Windows) and execPath IS gbrain, so the user args are the whole argv;
 * `bun src/cli.ts` needs the runtime flags (`--inspect`, `--preload`, … from
 * process.execArgv, relative paths resolved against `originalCwd` — see
 * "Runtime flags across the hop") and the entry file re-inserted — Bun
 * reports the entry as an absolute path, so it survives the neutral-cwd start
 * (cli.ts computes rawArgs as `process.argv.slice(2)` in both modes). null
 * when there is no re-runnable entry (`bun -e`).
 */
function selfArgv(originalCwd: string): string[] | null {
  const entry = process.argv[1];
  const userArgs = process.argv.slice(2);
  if (!isScriptRuntime()) return userArgs;
  if (!entry || entry.startsWith('-')) return null;
  return [...resolveRuntimePaths(process.execArgv, originalCwd), entry, ...userArgs];
}

/** Bun runtime flags whose value is a filesystem path (or, for the preload family, a path OR a package specifier). */
const PATH_RUNTIME_FLAGS: ReadonlySet<string> = new Set([
  '--preload', '-r', '--require', '--import',
  '--config', '-c',
  '--env-file',
  '--tsconfig-override',
]);

/** A path-flag value the re-run must see from `cwd`: relative → absolute; everything else verbatim. */
function resolveRuntimePath(value: string, cwd: string): string {
  if (value === '' || isAbsolute(value)) return value;
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- value is a --preload/--env-file/... path the operator passed on THIS process's own bun command line (process.execArgv) and cwd is the process's own startup cwd; absolutizing it so the sanitized re-run (which starts in a neutral dir) sees the same file IS the point, and no fs operation happens here
  if (/^\.\.?(?:[\\/]|$)/.test(value)) return resolve(cwd, value); // ./x  ../x  .  ..
  try {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- same operator-supplied runtime-flag value against the process's own cwd; existsSync only decides whether a bare name is a file here or a package specifier
    if (existsSync(resolve(cwd, value))) return resolve(cwd, value); // a bare relative name that IS a file here (`--env-file .env.ci`)
  } catch {
    // unreadable — treat as a specifier
  }
  return value; // a package specifier (`--preload some-pkg`) or a non-path
}

/** `execArgv` with every path-bearing flag's relative value resolved against `cwd`; order and every other flag preserved. */
function resolveRuntimePaths(execArgv: readonly string[], cwd: string): string[] {
  const out: string[] = [];
  for (let i = 0; i < execArgv.length; i++) {
    const arg = execArgv[i]!;
    const eq = arg.indexOf('=');
    const flag = eq === -1 ? arg : arg.slice(0, eq);
    if (!PATH_RUNTIME_FLAGS.has(flag)) {
      out.push(arg);
      continue;
    }
    if (eq !== -1) {
      out.push(`${flag}=${resolveRuntimePath(arg.slice(eq + 1), cwd)}`); // --flag=value
      continue;
    }
    out.push(arg); // --flag value
    if (i + 1 < execArgv.length) out.push(resolveRuntimePath(execArgv[++i]!, cwd));
  }
  return out;
}

/**
 * True when this process is `bun <entry>` (the dev runtime or a `bun install
 * -g` / `bun link` install running src/cli.ts through its shebang), false for
 * a compiled binary (execPath IS gbrain; the entry is a `/$bunfs/` virtual
 * path, `~BUN` on Windows).
 */
export function isScriptRuntime(): boolean {
  const entry = process.argv[1];
  const bunfsEntry = entry !== undefined && (/^\/\$bunfs\//.test(entry) || /[\\/]~BUN[\\/]/.test(entry));
  const devRuntime = /[/\\](bun|node)(\.exe)?$/.test(process.execPath);
  return !bunfsEntry && devRuntime;
}

/**
 * The one line preflight prints for the shape described in "Script mode + cwd
 * bunfig.toml". Exported for tests.
 */
export const SCRIPT_MODE_BUNFIG_WARNING =
  '[env] gbrain is running as a bun script (not the compiled binary) and the bunfig.toml in the current ' +
  'directory declares a top-level preload — Bun ran it before gbrain started. A cwd bunfig.toml is untrusted: ' +
  'run gbrain from a directory you control, or start it as `bun --config=/dev/null <path-to-gbrain/src/cli.ts> …`.';

/**
 * Does `bunfig.toml` in `dir` declare a TOP-LEVEL `preload` (the one Bun
 * applies to `bun <entry>`; a `[test]`-section preload applies to `bun test`
 * only)? Lines before the first `[section]` header are the top level.
 * Fail-quiet: unreadable → false (Bun would have failed on it first).
 */
function bunfigDeclaresTopLevelPreload(dir: string): boolean {
  let text: string;
  try {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- dir is the process's own startup cwd (process.cwd() in runCliPreflight) and the tail is the fixed literal 'bunfig.toml'; read-only probe for a top-level preload declaration
    text = readFileSync(join(dir, 'bunfig.toml'), 'utf-8');
  } catch {
    return false;
  }
  for (const line of text.split(/\r?\n/)) {
    if (/^\s*\[/.test(line)) return false; // first section header: top level ends
    if (/^\s*preload\s*=/.test(line)) return true;
  }
  return false;
}

/** The startup cwd is the checkout that contains the running entry (`<root>/src/cli.ts`). */
function cwdIsOwnCheckout(startupCwd: string): boolean {
  const entry = process.argv[1];
  if (!entry) return false;
  try {
    return realpathSync(startupCwd) === realpathSync(dirname(dirname(entry)));
  } catch {
    return false;
  }
}

function warnScriptModeBunfig(startupCwd: string): void {
  if (!isScriptRuntime()) return;
  if (!bunfigDeclaresTopLevelPreload(startupCwd)) return;
  if (cwdIsOwnCheckout(startupCwd)) return;
  console.error(SCRIPT_MODE_BUNFIG_WARNING);
}

/**
 * Does this process have a controlling terminal — i.e. will a terminal deliver
 * Ctrl-C to the whole foreground process group (wrapper AND re-run) itself?
 * POSIX: `open("/dev/tty")` succeeds exactly then (ENXIO otherwise), whatever
 * stdin/stdout/stderr are redirected to. Windows has no /dev/tty; the stdio
 * `isTTY` flags are the closest proxy there.
 */
function hasControllingTerminal(): boolean {
  if (process.platform === 'win32') {
    return Boolean(process.stdin.isTTY || process.stdout.isTTY || process.stderr.isTTY);
  }
  try {
    closeSync(openSync('/dev/tty', fsConstants.O_RDONLY | fsConstants.O_NOCTTY));
    return true;
  } catch {
    return false;
  }
}

/**
 * The operator's real home for "HOME after the drop": `os.userInfo().homedir`
 * (Bun: the startup environ's value, passwd when unset — never the merged
 * .env value), then `os.homedir()`. undefined when neither is available
 * (uid-less containers throw from userInfo).
 */
function realHomeDir(): string | undefined {
  try {
    const h = userInfo().homedir;
    if (h) return h;
  } catch {
    // no passwd entry for this uid — fall through
  }
  try {
    return homedir() || undefined;
  } catch {
    return undefined;
  }
}

/**
 * A fresh, empty directory that is ours, as an ABSOLUTE canonical path.
 * `tmpdir()` first — it reads TMPDIR/TMP/TEMP at call time, and those are on
 * the protected list, so a value planted by the cwd .env (a relative `t`, a
 * path inside the checkout) is already gone when this runs; the home dir when
 * the temp root is unusable. A mkdtemp dir is new by definition, so neither
 * can hold a .env. `realpathSync` so the marker's `neutral` and the re-run's
 * startup cwd compare canonically even if a caller-exported TMPDIR is
 * relative or a symlink.
 */
function makeNeutralDir(): string {
  let dir: string;
  try {
    dir = mkdtempSync(join(tmpdir(), 'gbrain-hop-'));
  } catch {
    dir = mkdtempSync(join(homedir(), '.gbrain-hop-'));
  }
  return realpathSync(dir);
}

/** The home variables restored after a drop (see "HOME after the drop"): HOME everywhere, USERPROFILE on Windows. */
const HOME_KEYS: readonly string[] = process.platform === 'win32' ? ['HOME', 'USERPROFILE'] : ['HOME'];

async function reexecSanitized(originalCwd: string, dropped: readonly string[]): Promise<void> {
  const argv = selfArgv(originalCwd);
  if (!argv) return; // in-process view is clean; nothing re-runnable for the descendants' sake
  const neutral = makeNeutralDir();
  // The quarantine already deleted the dropped keys from process.env; they are
  // NOT added back (not even empty — see "Why the re-run") …
  const env: Record<string, string> = {};
  for (const [k, v] of Object.entries(process.env)) {
    if (v !== undefined) env[k] = v;
  }
  // … except a dropped HOME, which comes back as the operator's REAL home
  // (see "HOME after the drop") — the planted value is still discarded.
  for (const key of HOME_KEYS) {
    if (!dropped.includes(key) || env[key] !== undefined) continue;
    const real = realHomeDir();
    if (real) env[key] = real;
  }
  env[CWD_ENV_QUARANTINED_MARKER] = JSON.stringify({ cwd: originalCwd, neutral, wrapperPid: process.pid } satisfies HopMarker);
  let code: number;
  let signalCode: string | null;
  // See "Signals". Installed BEFORE the spawn; the spawn is synchronous in the
  // same tick, so a handler can only ever run with `child` set.
  let child: ReturnType<typeof Bun.spawn> | null = null;
  const forward = (sig: NodeJS.Signals) => () => {
    try { child?.kill(sig); } catch { /* already exited */ }
  };
  // The wrapper's only job is to relay the child. Any listener an earlier
  // module attached for these signals (cli.ts's cleanup handlers: SIGTERM →
  // exit 143 / SIGHUP → exit 129, installed before main()) would exit the
  // wrapper on its own schedule — before the child has finished and before the
  // neutral dir is removed. Remove them; the forwarders below are the only ones.
  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) process.removeAllListeners(sig);
  process.on('SIGTERM', forward('SIGTERM'));
  process.on('SIGHUP', forward('SIGHUP'));
  // controlling terminal: it already delivered Ctrl-C to the child; only outlive it.
  // none: nothing else will deliver it — forward.
  process.on('SIGINT', hasControllingTerminal() ? () => {} : forward('SIGINT'));
  try {
    child = bunSpawn([process.execPath, ...argv], {
      cwd: neutral,
      env,
      stdio: ['inherit', 'inherit', 'inherit'],
    });
    code = await child.exited;
    signalCode = child.signalCode;
  } finally {
    rmSync(neutral, { recursive: true, force: true });
  }
  if (signalCode) {
    const signals = osConstants.signals as Record<string, number | undefined>;
    process.exit(128 + (signals[signalCode] ?? 1)); // shell convention for a signal death
  }
  process.exit(code);
}

/**
 * The refusal printed when a non-empty GBRAIN_GUARDRAILS_MODULE was dropped
 * (see "GBRAIN_GUARDRAILS_MODULE: fail closed, not open"). Exported for tests.
 */
export const GUARDRAILS_ASSIGNED_BY_CWD_DOTENV =
  'guardrails: GBRAIN_GUARDRAILS_MODULE is assigned by a .env file in the current directory; ' +
  "refusing to run without the operator's firewall. Bun merges that file before gbrain starts, " +
  "so a value you exported cannot be told apart from the file's — remove the assignment from the " +
  "project's .env, or run gbrain from a directory that does not assign it. Your own setting " +
  'belongs in your shell environment or in ~/.gbrain/.env (never in a project .env).';

export async function runCliPreflight(): Promise<void> {
  const startupCwd = process.cwd();
  const hop = verifiedHop(startupCwd);
  if (hop) {
    delete process.env[CWD_ENV_QUARANTINED_MARKER]; // never inherited further: a later self-spawn decides for itself
    try {
      process.chdir(hop.cwd);
    } catch (err) {
      console.error(`[env] cannot return to ${hop.cwd} after the sanitized re-run: ${(err as Error)?.message ?? String(err)}`);
      process.exit(1);
    }
    installWrapperWatchdog(hop); // after the chdir: the neutral dir may be removed only from outside it
  } else {
    // Bun applied the STARTUP cwd's bunfig.toml to this process (script mode
    // only); the re-run started in the neutral dir, so it has nothing to say.
    warnScriptModeBunfig(startupCwd);
  }
  const cwd = process.cwd();
  const assignments = parseCwdDotenv(cwd);
  const collision = cwdIsOperatorConfigDir(cwd, assignments);
  if (!hop && !collision) {
    const hadGuardrailsModule = (process.env.GBRAIN_GUARDRAILS_MODULE ?? '').trim() !== '';
    const dropped = quarantineCwdDotenv(process.env, cwd, { assignments });
    if (hadGuardrailsModule && dropped.includes('GBRAIN_GUARDRAILS_MODULE')) {
      console.error(GUARDRAILS_ASSIGNED_BY_CWD_DOTENV);
      process.exit(1);
    }
    if (dropped.length > 0) await reexecSanitized(cwd, dropped);
  }
  loadGbrainEnvFile(configDir);
  if (process.env.GBRAIN_GUARDRAILS_MODULE) {
    try {
      const { loadGuardrailProvidersFromEnv } = await import('./guardrails.ts');
      await loadGuardrailProvidersFromEnv(process.env, { skipCwdCheck: collision });
    } catch (err) {
      console.error(`guardrails: ${(err as Error)?.message ?? String(err)}`);
      process.exit(1);
    }
  }
}