Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
93.7 KB
Raw Blame
/**
 * `gbrain mcp expose` — publish `gbrain serve --http` on the user's Tailscale
 * tailnet (or, with `--funnel`, on the public internet through Tailscale
 * Funnel) and keep it running as a user service.
 *
 * Engine-free: never opens the database. Local CLI only (a `mcp`
 * subcommand). Every step is a named check in `--json`; prose goes to stderr
 * when `--json` is set so stdout carries exactly one document.
 *
 * Exit codes: 0 done · 1 failed · 2 needs confirmation (`--yes`) or a step is
 * pending (Tailscale login not completed, tailnet health still pending).
 *
 * Every side effect (exec, fetch, resolver, prompt, clock, paths) is
 * injectable through `McpExposeDeps` so the command is testable against a
 * fake runner in a tmpdir. Never mutate process.env here — read it through
 * `deps.env`. The health / occupancy probes live in `mcp-expose-probe.ts`.
 */
import { existsSync, unlinkSync } from 'node:fs';
import { dirname, resolve as resolvePath } from 'node:path';
import { homedir, userInfo } from 'node:os';
import { promptLineStderr } from '../core/cli-util.ts';
import { isInteractive } from '../core/interaction.ts';
import { isConsentRefusal, renderConsentRefusal, requireConsent } from '../core/consent.ts';
import type { Effect } from '../core/agent-output.ts';
import { gbrainPath, isThinClient, loadConfig, type GBrainConfig } from '../core/config.ts';
import { detectExecutionEnvironment, type ExecutionEnvironment } from '../core/execution-env.ts';
import { validateHarnessArguments } from '../core/harness/arguments.ts';
import { probeLivePgliteHolder } from '../core/bootstrap/uninstall.ts';
import {
  classifyTailscaleError, defaultCommandRunner, findProxiedHandler, findRootHandlers, findTailscaleBinary, isSystemTailscaleBinary,
  parseServeStatusStrict, parseTailscaleStatus, publicUrlFromDnsName, tailscaleDaemonStartHint, tailscaleInstallPlan,
  tailscaleLoginArgv, tailscaleManualLoginCommand, tailscaleServeArgv, tailscaleServeOffArgv, tailscaleSetOperatorCommand,
  TAILSCALE_ADMIN_ACL_URL, TAILSCALE_ADMIN_DNS_URL, TAILSCALE_BINARY_CANDIDATES, TAILSCALE_DOWNLOAD_URL, TAILSCALE_FUNNEL_KB_URL,
  TAILSCALE_SERVE_STATUS_ARGV, TAILSCALE_STATUS_ARGV,
  type CommandResult, type CommandRunner, type ServeHandler, type ServeStatusView, type TailscaleStatus,
} from '../core/tailscale.ts';
import {
  defaultLookup, defaultTcpProbe, pollHealth, probeHealth, probeOccupied, statusOnlyHealthDetail, tryFetch, unresolvedDetail,
  type FetchOutcome, type HostLookup, type ProbeFetch, type TcpProbe,
} from './mcp-expose-probe.ts';
// The probes were peeled into `mcp-expose-probe.ts`; the default TCP probe keeps its import site here.
export { defaultTcpProbe };
import {
  adminTokenPath as adminTokenPathFor, detectServiceTarget, ensureAdminToken, installServeService, launchdBootoutFailed, launchdPlistPath,
  readExposeReceipt, receiptPath as receiptPathFor, renderServeWrapper, resolveServeGbrainCommand, serveCommandArgv,
  serveDir as defaultServeDir, serveErrPath, serveLogPath, serveServiceState, systemdUnitPath, SYSTEMCTL_USER_BUS_PROBE_ARGV,
  SERVE_LAUNCHD_LABEL, SERVE_SYSTEMD_UNIT, uninstallServeService, wrapperPath as wrapperPathFor, writeExposeReceipt,
  type ExposeReceipt, type ServiceState, type ServiceTarget, type UninstallServiceResult,
} from '../core/serve-service.ts';
import { registrationAdvertise, shellQuote } from '../core/mcp-registration.ts';
import { connectorInstallLinks, installLinkLines, printInstallLinks, type ConnectorInstallLinks } from '../core/connector-install-links.ts';
import { cliRenderContext, renderNotice } from '../core/agent-output.ts';
import { EXPOSE_FRICTION_REASONS, hostedOptionLine, hostedOptionMuted, hostedOptionNotice } from '../core/onboard/hosted-option.ts';

export const MCP_EXPOSE_HELP = `gbrain mcp expose — publish the MCP server on your Tailscale tailnet and keep it running

gbrain mcp expose [--port N] [--funnel] [--surface verbs|starter|full] [--enable-dcr]
                  [--no-tailscale] [--no-service] [--no-install] [--force]
                  [--dry-run] [--yes] [--json]
gbrain mcp expose --status [--json]
gbrain mcp expose --remove [--yes] [--json]

Steps (each a named check in --json): plan, consent, tailscale.binary, tailscale.login,
tailscale.identity, tailscale.publish, admin_token, service, verify.local, verify.tailnet, receipt.
Nothing is published until Tailscale reports HTTPS certificates (and, with --funnel, the Funnel
node attribute) enabled — otherwise exit 2 with the admin URL to fix it.

--port N          Local port for the gbrain HTTP server (default: 3131)
--funnel          Publish on the public internet via Tailscale Funnel (cloud agents:
                  Grok Bot, Muse, ChatGPT). Default is tailnet-only — your own devices.
--surface X       MCP tool surface: verbs | starter | full, listed in full (default: full,
                  listing the memory verbs and request_tools; an earlier exposure
                  keeps its listing)
--enable-dcr      Allow OAuth Dynamic Client Registration on the server
--no-tailscale    Skip every Tailscale step (you publish the port yourself)
--no-service      Publish only; do not install or start the user service
--no-install      Never install Tailscale; exit 1 with the install plan when it is missing
--force           Take over a foreign tailscale serve handler on :443; with --remove also
                  delete the admin token file, and (without a receipt) turn off a :443 handler
                  for --port that no wrapper, unit or service of gbrain's corroborates
--dry-run         Print the plan and stop (exit 0, no changes)
--yes             Skip the confirmation prompt (required when not on a TTY)
--status          Re-probe the published server, the service and both health URLs. Without a
                  receipt it looks for leftovers of an interrupted run (exit 1 when any are found)
--remove          Stop the service, clear our serve/funnel handler, delete wrapper + receipt.
                  Without a receipt (an interrupted run) it recovers from what is on disk:
                  the wrapper, the launchd/systemd unit and the :443 handler for --port (the
                  handler only when the wrapper, unit or service corroborates it, or --force).
--json            One JSON document on stdout; prose moves to stderr

A host with no brain config is refused (no_brain_config) unless --no-service: a service there
would only crash-loop. Anything listening on 127.0.0.1:<port> — a TCP connect that is accepted,
or any HTTP answer — counts as occupied. --no-tailscale is refused while a receipt says the brain
is published on the tailnet (tailscale_receipt_present): --remove first.

Exit codes: 0 done · 1 failed · 2 confirmation needed or a step is pending (re-run).
Env: GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS bounds the wait for \`tailscale up\` (default 300000).

Next: gbrain mcp grant NAME --harness ID --profile memory-writer --source default --url URL/mcp \\
        --admin-token-file ~/.gbrain/serve/admin-token --credentials-out /private/NAME.json
`;

export const MCP_EXPOSE_ARGUMENTS = {
  values: ['--port', '--surface'],
  flags: ['--funnel', '--enable-dcr', '--no-tailscale', '--no-service', '--no-install', '--force', '--dry-run', '--yes', '--json', '--status', '--remove', '--help', '-h'],
  exclusive: [['--status', '--remove'], ['--funnel', '--no-tailscale'], ['--dry-run', '--status'], ['--dry-run', '--remove']],
} as const;

export const DEFAULT_EXPOSE_PORT = 3131;
/** `tailscale serve|funnel --bg` is killed after this long — it blocks (waiting for an enablement step) rather than failing. */
const PUBLISH_TIMEOUT_MS = 60_000;
/** `tailscale serve|funnel --https=443 --set-path=/ off`. */
const SERVE_OFF_TIMEOUT_MS = 30_000;
/** `tailscale status --json` and `tailscale serve status --json` (read-only). */
const STATUS_READ_TIMEOUT_MS = 15_000;
/** After `open -a Tailscale` on a fresh brew install: poll `status --json` this many times, this far apart, until the app's daemon answers. */
const APP_DAEMON_POLL_ATTEMPTS = 20;
const APP_DAEMON_POLL_INTERVAL_MS = 1_000;
const SURFACES = ['verbs', 'starter', 'full'] as const;
type Surface = (typeof SURFACES)[number];

// ---------------------------------------------------------------------------
// Deps
// ---------------------------------------------------------------------------

export interface McpExposeDeps {
  platform?: string;
  /** Read-only view of the environment (USER, HOME, GBRAIN_HOME, GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS). */
  env?: Record<string, string | undefined>;
  home?: string;
  user?: string;
  uid?: number;
  serveDir?: string;
  gbrainEnvFile?: string;
  plistPath?: string;
  unitPath?: string;
  loadConfig?: () => GBrainConfig | null;
  /** The owner's muted notice codes (default: the global and stdio mute lists under GBRAIN_HOME). */
  mutedNotices?: () => ReadonlySet<string>;
  executionEnv?: ExecutionEnvironment;
  run?: CommandRunner;
  which?: (name: string) => string | null;
  fileExists?: (path: string) => boolean;
  fetch?: ProbeFetch;
  /** Bounded TCP connect to `host:port` (true on connect, false on refusal / timeout); default `node:net`. Tests inject a fake. */
  tcpProbe?: TcpProbe;
  /**
   * Resolver consulted after a tailnet `/health` fetch REJECTS (Bun's fetch
   * reports an unresolvable name and a refused connection identically);
   * default `dns.promises.lookup`. Tests inject a fake — never the real one.
   */
  lookup?: HostLookup;
  isTTY?: boolean;
  prompt?: (question: string) => Promise<string | null>;
  stdout?: (line: string) => void;
  stderr?: (line: string) => void;
  now?: () => Date;
  sleep?: (ms: number) => Promise<void>;
  gbrainCommand?: string[];
  runtimeDir?: string;
  randomHex?: () => string;
  /** Health polling budget (ms). Tests shrink these. */
  localHealthMs?: number;
  tailnetHealthMs?: number;
  healthIntervalMs?: number;
  /** Milliseconds the login step waits for `tailscale up` (default GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS or 300000). */
  loginTimeoutMs?: number;
  /** Read-only PGLite lock probe (default `probeLivePgliteHolder`; never opens the engine). */
  pgliteHolder?: PgliteHolderProbe;
}

/** Matches `probeLivePgliteHolder`'s `LiveHolder | null` (`serve` is what the lock file recorded; `command` is optional detail). */
export type PgliteHolderProbe = (dbPath: string) => { pid: number; serve?: boolean; command?: string } | null;

interface Check { name: string; status: 'ok' | 'warn' | 'fail' | 'skipped' | 'pending' | 'planned'; detail: string }

type ExposeStatus = 'exposed' | 'pending' | 'planned' | 'error' | 'removed' | 'not_exposed';

interface Resolved {
  platform: string;
  env: Record<string, string | undefined>;
  home: string;
  user: string;
  uid: number | undefined;
  serveDir: string;
  gbrainEnvFile: string;
  plistPath: string;
  unitPath: string;
  run: CommandRunner;
  which: (name: string) => string | null;
  fileExists: (path: string) => boolean;
  fetch: ProbeFetch;
  tcpProbe: TcpProbe;
  lookup: HostLookup;
  isTTY: boolean;
  prompt: (question: string) => Promise<string | null>;
  out: (line: string) => void;
  err: (line: string) => void;
  now: () => Date;
  sleep: (ms: number) => Promise<void>;
  executionEnv: ExecutionEnvironment;
  loadConfig: () => GBrainConfig | null;
  mutedNotices: () => ReadonlySet<string>;
  gbrainCommand: () => string[];
  runtimeDir: string;
  randomHex?: () => string;
  localHealthMs: number;
  tailnetHealthMs: number;
  healthIntervalMs: number;
  loginTimeoutMs: number;
  pgliteHolder: PgliteHolderProbe;
}

function resolveDeps(deps: McpExposeDeps): Resolved {
  const env = deps.env ?? process.env;
  const home = deps.home ?? env.HOME ?? homedir();
  const which = deps.which ?? ((name: string) => { try { return Bun.which(name, { PATH: env.PATH ?? process.env.PATH ?? '' }); } catch { return null; } });
  const loginEnv = Number(env.GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS);
  return {
    platform: deps.platform ?? process.platform,
    env,
    home,
    user: deps.user ?? env.USER ?? (() => { try { return userInfo().username; } catch { return 'user'; } })(),
    uid: deps.uid ?? (typeof process.getuid === 'function' ? process.getuid() : undefined),
    serveDir: deps.serveDir ?? defaultServeDir(),
    gbrainEnvFile: deps.gbrainEnvFile ?? gbrainPath('env'),
    plistPath: deps.plistPath ?? launchdPlistPath(home),
    unitPath: deps.unitPath ?? systemdUnitPath(home),
    run: deps.run ?? defaultCommandRunner,
    which,
    fileExists: deps.fileExists ?? existsSync,
    fetch: deps.fetch ?? ((url, init) => fetch(url, init as RequestInit)),
    tcpProbe: deps.tcpProbe ?? defaultTcpProbe,
    lookup: deps.lookup ?? defaultLookup,
    isTTY: deps.isTTY ?? isInteractive({ stdoutIsTTY: process.stderr.isTTY === true }),
    prompt: deps.prompt ?? ((q: string) => promptLineStderr(q)),
    out: deps.stdout ?? ((line: string) => { process.stdout.write(`${line}\n`); }),
    err: deps.stderr ?? ((line: string) => { process.stderr.write(`${line}\n`); }),
    now: deps.now ?? (() => new Date()),
    sleep: deps.sleep ?? ((ms: number) => new Promise(resolve => setTimeout(resolve, ms))),
    executionEnv: deps.executionEnv ?? detectExecutionEnvironment({ env }),
    loadConfig: deps.loadConfig ?? loadConfig,
    mutedNotices: deps.mutedNotices ?? hostedOptionMuted,
    gbrainCommand: () => deps.gbrainCommand ?? resolveServeGbrainCommand({ which, fileExists: deps.fileExists }),
    runtimeDir: deps.runtimeDir ?? dirname(process.execPath || ''),
    randomHex: deps.randomHex,
    localHealthMs: deps.localHealthMs ?? 20_000,
    tailnetHealthMs: deps.tailnetHealthMs ?? 30_000,
    healthIntervalMs: deps.healthIntervalMs ?? 1_000,
    loginTimeoutMs: deps.loginTimeoutMs ?? (Number.isFinite(loginEnv) && loginEnv > 0 ? loginEnv : 300_000),
    pgliteHolder: deps.pgliteHolder ?? ((dbPath: string) => { try { return probeLivePgliteHolder(dbPath); } catch { return null; } }),
  };
}

// ---------------------------------------------------------------------------
// Options
// ---------------------------------------------------------------------------

export interface ExposeOptions {
  port: number;
  funnel: boolean;
  surface: Surface;
  /** --surface was passed: that surface is listed in full (no --advertise). */
  surfaceChosen: boolean;
  enableDcr: boolean;
  noTailscale: boolean;
  noService: boolean;
  noInstall: boolean;
  force: boolean;
  dryRun: boolean;
  yes: boolean;
  json: boolean;
  status: boolean;
  remove: boolean;
  help: boolean;
}

/** Throws with a one-line message on any shape error (unknown flag, bad value, conflict). */
export function parseExposeArgs(args: string[]): ExposeOptions {
  validateHarnessArguments(args, MCP_EXPOSE_ARGUMENTS);
  const value = (flag: string) => { const i = args.indexOf(flag); return i < 0 ? undefined : args[i + 1]; };
  const rawPort = value('--port');
  let port = DEFAULT_EXPOSE_PORT;
  if (rawPort !== undefined) {
    const n = Number(rawPort);
    if (!Number.isInteger(n) || n <= 0 || n > 65535) throw new Error(`invalid --port '${rawPort}' (1-65535)`);
    port = n;
  }
  const rawSurface = value('--surface');
  if (rawSurface !== undefined && !(SURFACES as readonly string[]).includes(rawSurface)) throw new Error(`invalid --surface '${rawSurface}' — pass verbs, starter or full`);
  return {
    port,
    funnel: args.includes('--funnel'),
    surface: (rawSurface as Surface | undefined) ?? 'full',
    surfaceChosen: rawSurface !== undefined,
    enableDcr: args.includes('--enable-dcr'),
    noTailscale: args.includes('--no-tailscale'),
    noService: args.includes('--no-service'),
    noInstall: args.includes('--no-install'),
    force: args.includes('--force'),
    dryRun: args.includes('--dry-run'),
    yes: args.includes('--yes'),
    json: args.includes('--json'),
    status: args.includes('--status'),
    remove: args.includes('--remove'),
    help: args.includes('--help') || args.includes('-h'),
  };
}

// ---------------------------------------------------------------------------
// Session: check ledger + output routing
// ---------------------------------------------------------------------------

class Session {
  readonly checks: Check[] = [];
  readonly nextActions: string[] = [];
  /** Set on the run whose early receipt write created the first receipt: that run shows hosted_option. */
  firstPublish = false;
  constructor(private readonly d: Resolved, readonly json: boolean) {}
  /** Prose: stderr under --json, stdout otherwise. */
  say(line = ''): void { (this.json ? this.d.err : this.d.out)(line); }
  check(name: string, status: Check['status'], detail: string): Check {
    const c = { name, status, detail };
    this.checks.push(c);
    return c;
  }
  finish(status: ExposeStatus, code: number, extra: { receipt?: ExposeReceipt | null; reason?: string; message?: string; plan?: string[]; consent?: Record<string, unknown>; installLinks?: ConnectorInstallLinks } = {}): number {
    const where = EXPOSE_FRICTION_REASONS.has(extra.reason ?? '') ? 'mcp_expose_friction'
      : this.firstPublish && (status === 'exposed' || status === 'pending') ? 'mcp_expose' : null;
    const hosted = where ? hostedOptionNotice(where, this.d.mutedNotices()) : null;
    if (extra.message) this.say(`${status}: ${extra.message}`);
    if (hosted && where && !this.json) this.say(hostedOptionLine(where));
    if (this.json) {
      this.d.out(JSON.stringify({
        status, receipt: extra.receipt ?? null, checks: this.checks, next_actions: this.nextActions,
        ...(extra.reason ? { reason: extra.reason } : {}), ...(extra.message ? { message: extra.message } : {}), ...(extra.plan ? { plan: extra.plan } : {}),
        ...(extra.consent ?? {}), ...(hosted ? { notices: [renderNotice(hosted, cliRenderContext())] } : {}), ...(extra.installLinks?.cursor ? { install_links: extra.installLinks } : {}),
      }));
    }
    return code;
  }
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

function engineKind(cfg: GBrainConfig | null): ExposeReceipt['engine'] {
  if (!cfg) return 'unknown';
  if (cfg.database_path && !cfg.database_url) return 'pglite';
  if (cfg.database_url || cfg.engine === 'postgres') return 'postgres';
  if (cfg.engine === 'pglite') return 'pglite';
  return 'unknown';
}

interface ServeRead {
  /** null when the read FAILED (non-zero / killed exit, or stdout that is not a JSON object) — never mistaken for an empty config. */
  view: ServeStatusView | null;
  stderr: string;
  status: number | null;
}

/**
 * `tailscale serve status --json`, fail-closed: a non-zero (or killed) exit,
 * or output that is not a JSON object, yields `view: null` so callers refuse
 * to publish over, remove from, or report on a config they could not read.
 * An empty document / `{}` / `null` from exit 0 is the legitimately empty view.
 */
async function readServeView(d: Resolved, binary: string): Promise<ServeRead> {
  const r = await d.run([binary, ...TAILSCALE_SERVE_STATUS_ARGV], { timeoutMs: STATUS_READ_TIMEOUT_MS });
  const view = r.status === 0 ? parseServeStatusStrict(r.stdout) : null;
  return { view, stderr: r.stderr || (r.status !== 0 ? r.stdout : ''), status: r.status };
}

/** A failed serve-status read, classified: the error kind, one detail line (kind + raw stderr + exit status) and the operator fix. */
function describeServeReadFailure(d: Resolved, r: ServeRead): { kind: string; detail: string; fix: string } {
  const cls = classifyTailscaleError(r.stderr, { platform: d.platform, user: d.user });
  const why = r.status === null ? 'killed or not spawned' : r.status === 0 ? 'exit 0 but stdout was not a JSON object' : `exit ${r.status}`;
  return { kind: cls.kind, detail: `could not read tailscale serve status (${why}): ${cls.kind}${cls.raw ? `: ${cls.raw}` : ''}`, fix: cls.fix };
}

async function readStatus(d: Resolved, binary: string): Promise<{ status: TailscaleStatus | null; stderr: string; exit: number | null }> {
  const r = await d.run([binary, ...TAILSCALE_STATUS_ARGV], { timeoutMs: STATUS_READ_TIMEOUT_MS });
  return { status: parseTailscaleStatus(r.stdout), stderr: r.stderr, exit: r.status };
}

async function probeServiceTarget(d: Resolved): Promise<ServiceTarget> {
  let userBus: { status: number | null; stdout: string } | null = null;
  if (d.platform === 'linux' && d.executionEnv === 'local' && d.which('systemctl')) {
    const r = await d.run([...SYSTEMCTL_USER_BUS_PROBE_ARGV], { timeoutMs: 3_000 });
    userBus = { status: r.status, stdout: `${r.stdout}\n${r.stderr}` };
  }
  return detectServiceTarget({ platform: d.platform, executionEnv: d.executionEnv, userBus });
}

function tildify(path: string, home: string): string {
  return home && path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
}

/** A supervisor reports our service as present when it is running or loaded (installed but not up yet). */
const isLiveService = (s: ServiceState | 'skipped' | null | undefined) => s === 'running' || s === 'loaded';

function serviceKindLabel(target: ServiceTarget): string {
  return target === 'macos' ? `launchd ${SERVE_LAUNCHD_LABEL}` : target === 'linux-systemd' ? `systemd (user) ${SERVE_SYSTEMD_UNIT}` : 'manual wrapper';
}

function serviceLabel(target: ServiceTarget, state: ServiceState | 'skipped', d: Resolved): string {
  if (target === 'none') return `manual (no supervisor here) — wrapper: ${tildify(wrapperPathFor(d.serveDir), d.home)}`;
  return `${serviceKindLabel(target)}, ${state}   (log: ${tildify(serveLogPath(d.serveDir), d.home)})`;
}

function manualCommands(d: Resolved, wrapper: string): { foreground: string; background: string } {
  const w = shellQuote(wrapper);
  return { foreground: w, background: `nohup ${w} >> ${shellQuote(serveLogPath(d.serveDir))} 2>> ${shellQuote(serveErrPath(d.serveDir))} &` };
}

function describeHandler(h: ServeHandler): string {
  const target = h.proxy ?? (h.tcpForward ? `raw TCP forward ${h.tcpForward}` : '(non-proxy handler)');
  return `${h.host || '*'}:443/ -> ${target}${h.foreground ? ' (foreground session in another terminal)' : ''}`;
}

/**
 * How LOCAL agents (Claude Code / Codex / opencode on this machine) get wired.
 * Postgres mints fine while the serve runs. PGLite is single-writer: a live
 * serve holds the lock, so `bootstrap harness` refuses to mint (`live_serve`)
 * unless the operator pre-minted a token or provisions a scoped client
 * through the running server's admin API.
 */
function localAgentGuidance(engine: ExposeReceipt['engine'], port: number, tokenHint: string): { lines: string[]; nextActions: string[] } {
  const plain = `gbrain bootstrap harness --yes --port ${port}`;
  if (engine !== 'pglite') return { lines: [plain], nextActions: [plain] };
  const localUrl = `http://127.0.0.1:${port}/mcp`;
  const grant = `gbrain mcp grant local-agents --harness <id> --profile memory-writer --source default --url ${localUrl} --admin-token-file ${tokenHint} --credentials-out /private/local-agents.json`;
  const connect = `gbrain connect ${localUrl} --harness <id> --credentials-file /private/local-agents.json --install`;
  return {
    lines: [
      'PGLite is single-writer, so `gbrain bootstrap harness` cannot mint while this server runs. Either:',
      `(a) mint while the service is stopped — \`gbrain auth create local-agents --scopes read,write\` — then`,
      `    ${plain} --token <value>`,
      `(b) or grant a scoped client through the running server: ${grant}`,
      `    then ${connect}`,
    ],
    nextActions: [
      'gbrain auth create local-agents --scopes read,write   # PGLite: run while the service is stopped, then pass --token',
      `${plain} --token <value>`,
      grant,
      connect,
    ],
  };
}

/** Re-run hint: the user's publish flags + `--yes` (+ `extra`, e.g. ` --no-service`). */
function rerunCommand(opts: ExposeOptions, extra = ''): string {
  return `gbrain mcp expose${args2(opts)} --yes${extra}`;
}

interface ConsentExtra {
  yes: boolean;
  /** Carried into the `pending` document (the `--remove` receipt). */
  receipt?: ExposeReceipt | null;
  /** Message for a non-TTY run without `--yes`. */
  confirmationMessage: string;
  /** Pushed to `next_actions` on a non-TTY run without `--yes`. */
  nextAction?: string;
  /** The command that runs once approved, without `--yes` (consentFix adds it). */
  argv: string[];
  effects: Effect[];
  what: string;
  why: string;
  risk: string;
  user_message: string;
}

/** The publish run's consent request: effects, the approved command and the words to relay. */
function publishConsent(opts: ExposeOptions): ConsentExtra {
  const where = opts.noTailscale ? 'on this machine' : opts.funnel ? 'on the public internet through Tailscale Funnel' : 'on your Tailscale network';
  return {
    yes: opts.yes, nextAction: rerunCommand(opts),
    confirmationMessage: 'These are system-state changes (Tailscale, serve config, a user service). Pass --yes to confirm.',
    argv: ['gbrain', 'mcp', 'expose', ...publishFlags(opts)],
    effects: opts.noTailscale ? ['persistent_install'] : ['persistent_install', 'egress'],
    what: 'mcp expose',
    why: `Publishes this brain's MCP server ${where}${opts.noService ? '' : ' and installs a user service that keeps it running'}, so authorized agents on other machines can reach it.`,
    risk: 'Changes system state (Tailscale serve config, a user service, files under the serve directory); `gbrain mcp expose --remove` undoes it.',
    user_message: `I'd like to publish your gbrain MCP server ${where}${opts.noService ? '' : ' and install a background service for it'}. OK?`,
  };
}

/**
 * The `consent` check, through the consent primitive (requireConsent). Returns
 * the exit code to hand back when the run must stop, or null to proceed.
 * Under contract v1 `mcp expose` keeps its documented exit 2 for a refusal
 * (non-TTY without `--yes` → `pending` / `confirmation_required`; declined at
 * the prompt → `pending` / `declined`); the document gains the consent
 * payload's agent fields (`code`, `effects`, `user_message`, `fix`, …) and
 * human output prints its `[AGENT]` block.
 */
async function confirmOrFinish(d: Resolved, s: Session, question: string, extra: ConsentExtra): Promise<number | null> {
  try {
    await requireConsent({
      command: 'mcp expose', effects: extra.effects, actor: 'agent', what: extra.what, why: extra.why, risk: extra.risk,
      user_message: extra.user_message, argv: extra.argv, args: extra.yes ? ['--yes'] : [],
    }, {
      interactive: d.isTTY,
      readLine: async () => {
        const answer = await d.prompt(question);
        return answer === null ? { kind: 'eof' } : { kind: 'line', text: answer.trim() };
      },
    });
  } catch (e) {
    if (!isConsentRefusal(e)) throw e;
    const declined = d.isTTY && !extra.yes;
    s.check('consent', 'pending', declined ? 'declined' : 'not a TTY and --yes not passed');
    if (!declined && extra.nextAction) s.nextActions.push(extra.nextAction);
    const { status: _status, error: _error, message: _message, suggestion: _suggestion, ...payload } = e.consent;
    if (!declined && !s.json) s.say(renderConsentRefusal(e.consent, { json: false }).stdout?.trimEnd() ?? '');
    return s.finish('pending', 2, {
      receipt: extra.receipt, reason: declined ? 'declined' : 'confirmation_required',
      message: declined ? 'Nothing changed: the confirmation was declined.' : extra.confirmationMessage, consent: payload,
    });
  }
  s.check('consent', 'ok', extra.yes ? '--yes' : 'confirmed interactively');
  return null;
}

/**
 * The tailscale binary `--status` / `--remove` execute. The receipt's recorded
 * path is honored only when it still exists AND is either what discovery finds
 * now or one of the known install locations — a receipt is 0600 but it is
 * still a file on disk, and an arbitrary path in it must never be run.
 */
function resolveReceiptBinary(d: Resolved, receipt: ExposeReceipt): string | null {
  const found = findTailscaleBinary({ which: d.which, fileExists: d.fileExists });
  const recorded = receipt.tailscale.binary;
  if (recorded && d.fileExists(recorded) && (recorded === found || TAILSCALE_BINARY_CANDIDATES.includes(recorded))) return recorded;
  return found;
}

interface PublishedThisRun { binary: string; hadHandlerBefore: boolean }

/**
 * A throw in the admin-token / service steps after THIS run's
 * `tailscale serve|funnel --bg` succeeded would leave a live handler with no
 * receipt to find it by. Turn it off again — but only when no handler for our
 * port existed before this run (a pre-existing one is the operator's and
 * stays). No receipt is written in that case. Once the early receipt is on
 * disk (`receiptWritten`), nothing is torn down: `--remove` can find it all.
 * Returns the error to re-throw, its message naming the handler state.
 */
async function rollbackAfterThrow(d: Resolved, s: Session, opts: ExposeOptions, published: PublishedThisRun | null, error: unknown, receiptWritten: boolean): Promise<Error> {
  const message = error instanceof Error ? error.message : String(error);
  if (receiptWritten) {
    // The early receipt is on disk: the handler and service are findable, so
    // nothing is torn down here — `--remove` is the operator's clean path.
    s.check('rollback', 'skipped', 'receipt already written; the handler and service stay — run `gbrain mcp expose --remove --yes` to undo, or `--status` to inspect');
    s.nextActions.push('gbrain mcp expose --status', 'gbrain mcp expose --remove --yes');
    return new Error(`${message} — the receipt was already written, so the published handler and the service were left in place (gbrain mcp expose --status / --remove --yes)`);
  }
  if (!published) return error instanceof Error ? error : new Error(message);
  if (published.hadHandlerBefore) {
    s.check('rollback', 'skipped', `a :443 handler for port ${opts.port} existed before this run; left in place, no receipt written`);
    return new Error(`${message} — the tailscale handler for port ${opts.port} was left in place (it existed before this run); no receipt written`);
  }
  const offArgv = tailscaleServeOffArgv({ funnel: opts.funnel });
  let outcome: string;
  try {
    const off = await d.run([published.binary, ...offArgv], { timeoutMs: SERVE_OFF_TIMEOUT_MS });
    // "turned off again" is claimed only when a re-read no longer shows our
    // port: an `off` that exits 0 can still leave the mount in place.
    const re = off.status === 0 ? await readServeView(d, published.binary) : null;
    outcome = off.status !== 0 ? `NOT turned off (exit ${off.status ?? 'null'}; run \`tailscale serve status\`)`
      : !re?.view ? 'state unknown (off exited 0 but tailscale serve status could not be re-read; run `tailscale serve status`)'
        : findProxiedHandler(re.view, opts.port) ? 'NOT turned off (off exited 0 but the handler is still present; run `tailscale serve status`)'
          : 'turned off again';
    s.check('rollback', outcome === 'turned off again' ? 'ok' : 'warn', `tailscale ${offArgv.join(' ')}: ${outcome}; no receipt written`);
  } catch (offError) {
    outcome = `NOT turned off (${offError instanceof Error ? offError.message : String(offError)}; run \`tailscale serve status\`)`;
    s.check('rollback', 'warn', `tailscale ${offArgv.join(' ')}: ${outcome}; no receipt written`);
  }
  return new Error(`${message} — the tailscale handler published by this run was ${outcome}; no receipt written`);
}

// ---------------------------------------------------------------------------
// Entry
// ---------------------------------------------------------------------------

export async function runMcpExpose(args: string[], deps: McpExposeDeps = {}): Promise<number> {
  const d = resolveDeps(deps);
  let opts: ExposeOptions;
  try {
    opts = parseExposeArgs(args);
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    if (args.includes('--json')) d.out(JSON.stringify({ status: 'error', reason: 'invalid_arguments', message, checks: [], next_actions: [], receipt: null }));
    d.err(`gbrain mcp expose: ${message}`);
    d.err('Run: gbrain mcp expose --help');
    return 1;
  }
  if (opts.help) { d.out(MCP_EXPOSE_HELP); return 0; }
  const s = new Session(d, opts.json);
  try {
    if (opts.status) return await runStatus(d, s, opts);
    if (opts.remove) return await runRemove(d, s, opts);
    return await runPublish(d, s, opts);
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    s.check('internal', 'fail', message);
    return s.finish('error', 1, { reason: 'mcp_expose_failed', message });
  }
}

// ---------------------------------------------------------------------------
// Publish (the default path)
// ---------------------------------------------------------------------------

async function runPublish(d: Resolved, s: Session, opts: ExposeOptions): Promise<number> {
  // 1. plan ------------------------------------------------------------------
  let cfg: GBrainConfig | null = null;
  try { cfg = d.loadConfig(); } catch { cfg = null; }
  if (isThinClient(cfg)) {
    s.check('plan', 'fail', 'this machine is a thin client (remote_mcp configured); run gbrain mcp expose on the brain host');
    return s.finish('error', 1, { reason: 'thin_client', message: 'This is a thin client. Run `gbrain mcp expose` on the machine that hosts the brain.' });
  }
  const engine = engineKind(cfg);
  const receiptPath = receiptPathFor(d.serveDir);
  const existing = readExposeReceipt(receiptPath);
  const advertise = registrationAdvertise({ userChoseSurface: opts.surfaceChosen, prior: existing });
  const tailscaleBinary = opts.noTailscale ? null : findTailscaleBinary({ which: d.which, fileExists: d.fileExists });
  const hasBrew = !!d.which('brew');
  const installPlan = tailscaleInstallPlan(d.platform, hasBrew);
  const target = opts.noService ? 'none' : await probeServiceTarget(d);
  const mode: ExposeReceipt['mode'] = opts.funnel ? 'funnel' : 'tailnet';
  // A service block from an earlier full run survives a `--no-service` re-run
  // untouched (the wrapper is not rewritten either).
  const keptService = opts.noService && existing && existing.service.state !== 'skipped' ? existing.service : null;
  const localHealthUrl = `http://127.0.0.1:${opts.port}/health`;
  // `--no-tailscale` over a receipt that says the brain is published on the
  // tailnet would rewrite the receipt to loopback while the Serve/Funnel
  // mapping stays live and unfindable. Refused before consent; `--remove` first.
  const tailscaleReceipt = opts.noTailscale && existing?.tailscale.dns_name ? existing : null;
  const plan: string[] = [];
  plan.push(`Server    gbrain serve (HTTP) on 127.0.0.1:${opts.port} (surface ${opts.surface}${advertise ? `, listing ${advertise === 'verbs' ? 'the memory verbs and request_tools' : advertise}` : ''}${opts.enableDcr ? ', DCR on' : ''}); engine ${engine}`);
  if (tailscaleReceipt) plan.push(`Tailscale ${opts.dryRun ? 'WOULD BE REFUSED' : 'REFUSED'} (--no-tailscale): this brain is already published on your tailnet at ${tailscaleReceipt.public_url} — run \`gbrain mcp expose --remove --yes\` first, or re-run without --no-tailscale`);
  else if (opts.noTailscale) plan.push('Tailscale skipped (--no-tailscale): you publish the port yourself');
  else if (tailscaleBinary) plan.push(`Tailscale ${tailscaleBinary} — sign in if needed, then \`tailscale ${tailscaleServeArgv(opts.port, { funnel: opts.funnel }).join(' ')}\``);
  else if (opts.noInstall) plan.push(`Tailscale NOT installed and --no-install set — would stop with: ${installPlan.command}`);
  else plan.push(`Tailscale not installed — would run: ${installPlan.command}`);
  plan.push(`Reach     ${mode === 'funnel' ? 'PUBLIC internet via Tailscale Funnel (cloud agents); gbrain OAuth/bearer + grants protect it' : 'tailnet only — your devices; cloud agents need --funnel'}`);
  plan.push(`Token     ${tildify(adminTokenPathFor(d.serveDir), d.home)} (0600; created or reused; never printed)`);
  if (keptService) plan.push(`Service   kept as is (--no-service): ${serviceLabel(keptService.target, keptService.state, d)}`);
  else if (opts.noService) plan.push('Service   skipped (--no-service): publish only');
  else if (target === 'macos') plan.push(`Service   launchd user agent ${tildify(d.plistPath, d.home)} (RunAtLoad, KeepAlive)`);
  else if (target === 'linux-systemd') plan.push(`Service   systemd user unit ${tildify(d.unitPath, d.home)} (enabled + started, linger)`);
  else plan.push(`Service   manual — no user supervisor in this ${d.executionEnv === 'local' ? 'environment (no user bus)' : d.executionEnv}; you get a foreground command + nohup line`);
  plan.push(`Receipt   ${tildify(receiptPath, d.home)}${existing ? ' (updates the existing receipt)' : ''}`);
  // No brain config → the service would only crash-loop (`gbrain serve` has
  // nothing to open). Refused here, before consent; `--no-service` publishes a
  // server the operator runs themselves and is still allowed.
  const noBrain = engine === 'unknown' && !opts.noService;
  if (noBrain) plan.push(`Brain     ${opts.dryRun ? 'WOULD BE REFUSED' : 'REFUSED'}: no brain is configured on this host (gbrain init first) — a service would only crash-loop; pass --no-service to publish a server you run yourself`);
  // PGLite is single-writer: a live holder that is not our own managed service
  // keeps the service from starting. A warning, not a stop — the operator may
  // be about to stop that process.
  const lockHolder = engine === 'pglite' && cfg?.database_path ? d.pgliteHolder(cfg.database_path) : null;
  const ownService = existing !== null && isLiveService(existing.service.state);
  const lockWarning = lockHolder && !ownService
    ? `a live process holds this PGLite brain (pid ${lockHolder.pid}, ${lockHolder.command ?? (lockHolder.serve ? 'gbrain serve' : 'gbrain')}): the service cannot start until it exits — stop it, or move to Postgres`
    : null;
  if (lockWarning) plan.push(`Lock      ${lockWarning}`);
  s.check('plan', opts.dryRun ? 'planned' : noBrain || tailscaleReceipt ? 'fail' : 'ok', plan.join(' | '));
  if (lockWarning) s.check('pglite_lock', 'warn', lockWarning);
  s.say('Plan');
  for (const line of plan) s.say(`  ${line}`);
  if (opts.dryRun) {
    s.say('');
    s.say('Dry run: nothing changed. To apply, run the same command without --dry-run; it asks for confirmation first.');
    return s.finish('planned', 0, { receipt: existing, plan });
  }
  if (noBrain) {
    s.nextActions.push('gbrain init', rerunCommand(opts, ' --no-service'));
    return s.finish('error', 1, { receipt: existing, reason: 'no_brain_config', message: 'No brain is configured on this host (gbrain init first), so a service would only crash-loop; pass --no-service to publish a server you run yourself.' });
  }
  if (tailscaleReceipt) {
    s.nextActions.push('gbrain mcp expose --remove --yes', rerunCommand({ ...opts, noTailscale: false }));
    return s.finish('error', 1, { receipt: existing, reason: 'tailscale_receipt_present', message: `This brain is already published on your tailnet at ${tailscaleReceipt.public_url}; run \`gbrain mcp expose --remove --yes\` first, or re-run without --no-tailscale.` });
  }
  // Probe the local port NOW so a foreign listener is refused before anything
  // is published or installed (never after `tailscale serve --bg`). ANY
  // listener counts as occupied — an accepted TCP connect (a non-HTTP
  // service too) or an HTTP answer of any status (a 404 or 500 still owns the
  // port). A receipt for the same port claims the listener (it is our own server).
  const listeningBefore = await probeOccupied(d, opts.port, localHealthUrl);
  if (listeningBefore && !opts.noService && (!existing || existing.port !== opts.port)) {
    s.check('service', 'fail', `something already answers on 127.0.0.1:${opts.port} (a TCP connect was accepted or ${localHealthUrl} answered) and no expose receipt claims it`);
    s.nextActions.push('gbrain mcp expose --remove --yes', rerunCommand(opts, ' --no-service'));
    return s.finish('error', 1, {
      reason: 'foreign_listener',
      message: `Something already answers on 127.0.0.1:${opts.port} and no expose receipt claims it. Stop it, pick another --port, or pass --no-service to only publish it. If this is a gbrain server left behind by an interrupted \`gbrain mcp expose\`, run \`gbrain mcp expose --remove --yes\` first.`,
    });
  }

  // 2. consent -------------------------------------------------------------
  const consent = await confirmOrFinish(d, s, 'Proceed with the plan above? [y/N] ', publishConsent(opts));
  if (consent !== null) return consent;

  // 3-6. tailscale ---------------------------------------------------------
  let publicUrl: string | null = null;
  let binary = tailscaleBinary;
  let tsStatus: TailscaleStatus | null = null;
  /** Set once THIS run's `--bg` succeeded, so a later throw can roll it back. */
  let published: PublishedThisRun | null = null;
  if (opts.noTailscale) {
    for (const name of ['tailscale.binary', 'tailscale.login', 'tailscale.identity', 'tailscale.publish']) s.check(name, 'skipped', '--no-tailscale');
    publicUrl = `http://127.0.0.1:${opts.port}`;
    s.say('Tailscale skipped: the server stays on loopback until you publish it yourself.');
  } else {
    if (!binary) {
      if (opts.noInstall || !installPlan.argv) {
        s.check('tailscale.binary', 'fail', `not installed; ${installPlan.command}`);
        s.say('Tailscale is not installed.');
        s.say(`  Install: ${installPlan.command}`);
        s.say(`  ${installPlan.note}`);
        s.nextActions.push(installPlan.command);
        return s.finish('error', 1, { reason: opts.noInstall ? 'tailscale_missing' : 'tailscale_unsupported_platform', message: opts.noInstall ? 'Tailscale is missing and --no-install was set.' : installPlan.note });
      }
      s.say(`Installing Tailscale: ${installPlan.command}`);
      const inst = await d.run(installPlan.argv, { inherit: true, stdoutToStderr: opts.json, timeoutMs: 15 * 60_000 });
      binary = findTailscaleBinary({ which: d.which, fileExists: d.fileExists });
      if (inst.status !== 0 || !binary) {
        s.check('tailscale.binary', 'fail', `install ${inst.status === 0 ? 'finished but no binary was found' : `exited ${inst.status ?? 'null'}`}`);
        return s.finish('error', 1, { reason: 'tailscale_install_failed', message: `Tailscale install did not complete. Install it from ${TAILSCALE_DOWNLOAD_URL} and re-run.` });
      }
      if (installPlan.kind === 'brew-cask') {
        // The app bundle's CLI talks to the app's daemon, which only runs once
        // the app has been opened. Best effort: poll until `status --json`
        // answers; if the budget runs out the login step below reports the
        // daemon as not running.
        await d.run(['open', '-a', 'Tailscale'], { inherit: true, stdoutToStderr: opts.json, timeoutMs: 30_000 });
        for (let attempt = 0; attempt < APP_DAEMON_POLL_ATTEMPTS; attempt++) {
          await d.sleep(APP_DAEMON_POLL_INTERVAL_MS);
          if ((await readStatus(d, binary)).status) break;
        }
      }
      s.check('tailscale.binary', 'ok', `installed: ${binary}`);
    } else {
      s.check('tailscale.binary', 'ok', binary);
    }

    // 4. login
    let st = await readStatus(d, binary);
    if (!st.status) {
      const cls = classifyTailscaleError(st.stderr, { platform: d.platform, user: d.user });
      if (cls.kind === 'daemon_not_running' || st.exit === null) {
        s.check('tailscale.login', 'pending', `daemon not running: ${cls.raw || 'no output'}`);
        s.nextActions.push(tailscaleDaemonStartHint(d.platform), rerunCommand(opts));
        return s.finish('pending', 2, { reason: 'tailscale_daemon_not_running', message: `The Tailscale daemon is not running. ${cls.fix}` });
      }
      s.check('tailscale.login', 'fail', cls.raw || 'tailscale status printed no JSON');
      return s.finish('error', 1, { reason: `tailscale_${cls.kind}`, message: cls.fix });
    }
    if (st.status.backendState !== 'Running') {
      const login = tailscaleLoginArgv(d.platform, d.user, binary);
      if (login.setOperator && !isSystemTailscaleBinary(binary)) {
        // Linux login runs `sudo <binary> …`: never hand root to a binary
        // outside the system install locations (a user-writable PATH entry).
        const rerun = rerunCommand(opts);
        const manual = tailscaleManualLoginCommand(binary);
        s.check('tailscale.login', 'pending', `${st.status.backendState}; ${binary} is not a system install, so gbrain will not run it with sudo — sign in yourself if you trust that binary`);
        s.nextActions.push(manual, rerun);
        return s.finish('pending', 2, { reason: 'tailscale_login_manual', message: `tailscale at ${binary} is not a system install, so gbrain will not run it with sudo. If you trust that binary, sign in yourself (this runs it as root): \`${manual}\`, then re-run: ${rerun}` });
      }
      if (login.setOperator) {
        // Set the operator FIRST (so `serve` works without sudo later); a
        // failure is a note, not a stop — `up --operator=` is avoided because
        // it trips the CLI's settings-revert check on a node with custom prefs.
        s.say(`Tailscale is ${st.status.backendState}. Letting ${d.user} manage serve: ${login.setOperator.join(' ')}`);
        const so = await d.run(login.setOperator, { inherit: true, stdoutToStderr: opts.json, timeoutMs: 120_000 });
        if (so.status !== 0) s.say(`Note: ${login.setOperator.join(' ')} exited ${so.status ?? 'null'}; run \`${tailscaleSetOperatorCommand(d.user)}\` later so \`tailscale serve\` works without sudo.`);
      }
      s.say(`Signing in: ${login.up.join(' ')}`);
      s.say('  Open the URL it prints, approve the device, and come back.');
      const upResult = await d.run(login.up, { inherit: true, stdoutToStderr: opts.json, timeoutMs: d.loginTimeoutMs });
      st = await readStatus(d, binary);
      if (!st.status || st.status.backendState !== 'Running') {
        s.check('tailscale.login', 'pending', `BackendState ${st.status?.backendState ?? 'unknown'} after tailscale up (exit ${upResult.status ?? 'null'})`);
        const rerun = rerunCommand(opts);
        s.nextActions.push(d.platform === 'darwin' ? 'Open the Tailscale app and sign in' : login.up.join(' '), rerun);
        return s.finish('pending', 2, { reason: 'tailscale_login_pending', message: d.platform === 'darwin' ? `Open the Tailscale app and sign in, then re-run: ${rerun}` : `Complete the login, then re-run: ${rerun}` });
      }
      s.check('tailscale.login', 'ok', 'Running (signed in just now)');
    } else {
      s.check('tailscale.login', 'ok', 'Running');
    }
    tsStatus = st.status;

    // 5. identity
    if (!tsStatus.dnsName) {
      s.check('tailscale.identity', 'fail', 'Self.DNSName is empty — MagicDNS is off for this tailnet');
      s.nextActions.push(`Enable MagicDNS + HTTPS Certificates at ${TAILSCALE_ADMIN_DNS_URL}`);
      return s.finish('error', 1, { reason: 'tailscale_no_dns_name', message: `Your node has no MagicDNS name. Enable MagicDNS and HTTPS Certificates at ${TAILSCALE_ADMIN_DNS_URL}, then re-run.` });
    }
    publicUrl = publicUrlFromDnsName(tsStatus.dnsName);
    // Pre-checks. `tailscale serve/funnel --bg` do NOT fail when the feature
    // is off — they print an enablement URL and wait for the operator — so
    // never start them blind.
    const rerun = rerunCommand(opts);
    if (tsStatus.certDomains.length === 0) {
      s.check('tailscale.identity', 'pending', `${tsStatus.dnsName}; CertDomains empty — HTTPS certificates are not enabled for this tailnet (${TAILSCALE_ADMIN_DNS_URL})`);
      s.nextActions.push(`Enable MagicDNS + HTTPS Certificates at ${TAILSCALE_ADMIN_DNS_URL}`, rerun);
      return s.finish('pending', 2, { reason: 'tailscale_https_not_enabled', message: `HTTPS certificates are not enabled for your tailnet, so nothing was published. Enable MagicDNS + HTTPS Certificates at ${TAILSCALE_ADMIN_DNS_URL}, then re-run: ${rerun}` });
    }
    if (opts.funnel && tsStatus.funnelCapable === false) {
      s.check('tailscale.identity', 'pending', `${tsStatus.dnsName}; this node lacks the Funnel capability (${TAILSCALE_ADMIN_ACL_URL})`);
      s.nextActions.push(`Enable the funnel node attribute at ${TAILSCALE_ADMIN_ACL_URL} (see ${TAILSCALE_FUNNEL_KB_URL})`, rerun);
      return s.finish('pending', 2, { reason: 'tailscale_funnel_not_enabled', message: `Tailscale Funnel is not enabled for this node, so nothing was published. Enable the \`funnel\` node attribute in your tailnet policy at ${TAILSCALE_ADMIN_ACL_URL} (see ${TAILSCALE_FUNNEL_KB_URL}), then re-run: ${rerun}` });
    }
    s.check('tailscale.identity', 'ok', `${tsStatus.dnsName}${opts.funnel && tsStatus.funnelCapable === null ? ' (Funnel capability not reported by this CLI; the publish step decides)' : ''}`);

    // 6. publish
    const beforeRead = await readServeView(d, binary);
    if (!beforeRead.view) {
      // Fail closed: never publish over a serve config that could not be read.
      const failure = describeServeReadFailure(d, beforeRead);
      s.check('tailscale.publish', 'fail', failure.detail);
      s.nextActions.push('tailscale serve status --json', failure.fix);
      return s.finish('error', 1, { reason: `tailscale_${failure.kind}`, message: `Could not read the current \`tailscale serve status\`, so nothing was published. ${failure.fix}` });
    }
    const before = beforeRead.view;
    const ours = findProxiedHandler(before, opts.port);
    const foreign = findRootHandlers(before).filter(h => h.proxyPort !== opts.port);
    const claimed = existing !== null && foreign.some(h => h.proxyPort === existing.port);
    const foregroundForeign = foreign.filter(h => h.foreground);
    if (foreign.length > 0 && !claimed && (!opts.force || foregroundForeign.length > 0)) {
      const desc = foreign.map(describeHandler).join(', ');
      s.check('tailscale.publish', 'fail', `someone else's serve config on :443: ${desc}`);
      s.nextActions.push('tailscale serve status');
      const message = foregroundForeign.length > 0
        ? `tailscale serve already proxies :443 to ${desc}. A foreground \`tailscale serve\` session in another terminal owns it — --force cannot overwrite it; stop it there (Ctrl-C), then re-run.`
        : `tailscale serve already proxies :443 to ${desc}. Re-run with --force to take it over, or pick another local port for that service.`;
      return s.finish('error', 1, { reason: 'foreign_serve_config', message });
    }
    // Switching our own handler funnel -> tailnet needs Funnel turned off
    // first (`serve --bg` over a Funnel mount keeps AllowFunnel); the other
    // direction is one atomic `funnel --bg`, so nothing is pre-cleared there.
    const preOff = ours !== null && ours.funnel && !opts.funnel;
    if (preOff) await d.run([binary, ...tailscaleServeOffArgv({ funnel: true })], { timeoutMs: SERVE_OFF_TIMEOUT_MS });
    /** After a failed publish that followed the pre-off: best-effort re-publish of the previous (funnel) shape so the switch never strands the handler. Returns the detail suffix. */
    const restorePrevious = async (): Promise<string> => {
      if (!preOff) return '';
      const argv = tailscaleServeArgv(opts.port, { funnel: true });
      let r: CommandResult | null = null;
      try { r = await d.run([binary!, ...argv], { timeoutMs: PUBLISH_TIMEOUT_MS }); } catch { r = null; }
      const re = r?.status === 0 ? await readServeView(d, binary!) : null;
      const restored = re?.view ? findProxiedHandler(re.view, opts.port)?.funnel === true : false;
      return restored
        ? `; the previous funnel handler was restored (tailscale ${argv.join(' ')}) and the existing receipt kept`
        : `; the previous funnel handler could NOT be restored (tailscale ${argv.join(' ')}: ${r ? `exit ${r.status ?? 'null'}` : 'runner threw'}) — run \`tailscale serve status\`; the existing receipt was kept`;
    };
    const publishArgv = tailscaleServeArgv(opts.port, { funnel: opts.funnel });
    const pub = await d.run([binary, ...publishArgv], { timeoutMs: PUBLISH_TIMEOUT_MS });
    if (pub.status !== 0) {
      const restored = await restorePrevious();
      if (pub.status === null) {
        // Killed at the deadline: most likely the CLI was waiting for an
        // enablement step the pre-checks could not see. Say so, never guess.
        const hint = `\`tailscale ${publishArgv.join(' ')}\` did not finish within ${PUBLISH_TIMEOUT_MS / 1000}s (it may be waiting for you to enable a feature). Run it by hand to see what it prints, then re-run: ${rerun}`;
        s.check('tailscale.publish', 'fail', `unknown: timed out after ${PUBLISH_TIMEOUT_MS / 1000}s${restored}`);
        s.nextActions.push(`tailscale ${publishArgv.join(' ')}`);
        return s.finish('error', 1, { reason: 'tailscale_unknown', message: hint });
      }
      const cls = classifyTailscaleError(pub.stderr || pub.stdout, { platform: d.platform, user: d.user });
      s.check('tailscale.publish', 'fail', `${cls.kind}: ${cls.raw || `exit ${pub.status}`}${restored}`);
      s.nextActions.push(cls.fix);
      return s.finish('error', 1, { reason: `tailscale_${cls.kind}`, message: cls.fix });
    }
    published = { binary, hadHandlerBefore: ours !== null };
    const afterRead = await readServeView(d, binary);
    const confirmed = afterRead.view ? findProxiedHandler(afterRead.view, opts.port) : null;
    if (!confirmed) {
      const why = afterRead.view ? `serve status shows no / handler for port ${opts.port}` : describeServeReadFailure(d, afterRead).detail;
      s.check('tailscale.publish', 'fail', `tailscale ${publishArgv.join(' ')} exited 0 but ${why}${await restorePrevious()}`);
      s.nextActions.push('tailscale serve status', 'gbrain mcp expose --remove --yes');
      return s.finish('error', 1, { reason: 'tailscale_publish_unconfirmed', message: `Tailscale accepted the command but ${afterRead.view ? 'does not show the handler' : 'its serve status could not be read afterwards'}. Run \`tailscale serve status\` to inspect; \`gbrain mcp expose --remove --yes\` clears a handler for port ${opts.port} without a receipt (add --force when no wrapper or service of gbrain's is on this host yet).` });
    }
    if (confirmed.funnel !== opts.funnel) {
      s.check('tailscale.publish', 'warn', `handler present but funnel=${confirmed.funnel} (wanted ${opts.funnel})`);
      s.say(`Warning: Funnel is ${confirmed.funnel ? 'ON' : 'OFF'} for this handler but you asked for ${opts.funnel ? 'Funnel' : 'tailnet-only'}. Fix: tailscale ${tailscaleServeOffArgv({ funnel: confirmed.funnel }).join(' ')}, then re-run.`);
    } else {
      s.check('tailscale.publish', 'ok', `${confirmed.host}:443/ -> ${confirmed.proxy}${opts.funnel ? ' (funnel)' : ''}`);
    }
  }

  // 7-9. admin token, service, verify ----------------------------------------
  // Wrapped so a throw after THIS run's `--bg` succeeded rolls the handler
  // back (rollbackAfterThrow) instead of leaving it live with no receipt.
  const tokenPath = adminTokenPathFor(d.serveDir);
  const wrapper = wrapperPathFor(d.serveDir);
  let serviceReceipt: ExposeReceipt['service'] = { target, unit_path: null, plist_path: null, wrapper_path: wrapper, state: 'skipped' };
  const buildReceipt = (): ExposeReceipt => {
    const nowIso = d.now().toISOString();
    return {
      version: 1,
      created_at: existing?.created_at ?? nowIso,
      updated_at: nowIso,
      port: opts.port,
      public_url: publicUrl!,
      mcp_url: `${publicUrl}/mcp`,
      admin_url: `${publicUrl}/admin`,
      mode,
      surface: opts.surface,
      ...(advertise ? { advertise } : {}),
      enable_dcr: opts.enableDcr,
      tailscale: { binary, dns_name: tsStatus?.dnsName ?? null, tailscale_version: tsStatus?.version ?? null },
      service: serviceReceipt,
      admin_token_file: tokenPath,
      engine,
    };
  };
  let localHealth: 'ok' | 'timeout' | 'skipped' = 'skipped';
  let tailnetHealth: 'ok' | 'pending' | 'unresolved' | 'skipped' = 'skipped';
  /** Set once the early receipt (right after the service step) is on disk: from then on `--remove` can find everything. */
  let receiptWritten = false;
  try {
    // 7. admin token
    const token = ensureAdminToken(tokenPath, { randomHex: d.randomHex });
    s.check('admin_token', 'ok', `${token.action}: ${tokenPath}`);
    if (token.action === 'regenerated') s.say(`Note: ${tildify(tokenPath, d.home)} did not look like a valid admin token and was regenerated.`);

    // 8. service
    if (keptService) {
      serviceReceipt = keptService;
      s.check('service', 'skipped', `--no-service: existing ${serviceLabel(keptService.target, keptService.state, d)} kept as is`);
    } else if (opts.noService) {
      s.check('service', 'skipped', '--no-service');
    } else {
      // (a foreign listener was already refused in the plan step, before publishing)
      const content = renderServeWrapper({
        gbrainCommand: d.gbrainCommand(), adminTokenPath: tokenPath, gbrainEnvFile: d.gbrainEnvFile, gbrainHome: d.env.GBRAIN_HOME,
        runtimeDir: d.runtimeDir, port: opts.port, publicUrl: publicUrl!, surface: opts.surface, advertise, enableDcr: opts.enableDcr,
      });
      const installed = await installServeService({
        target, wrapperPath: wrapper, wrapperContent: content, home: d.home, logPath: serveLogPath(d.serveDir), errPath: serveErrPath(d.serveDir),
        run: d.run, uid: d.uid, plistPath: d.plistPath, unitPath: d.unitPath, sleep: d.sleep,
      });
      serviceReceipt.plist_path = installed.plist_path;
      serviceReceipt.unit_path = installed.unit_path;
      for (const note of installed.notes) s.say(`Note: ${note}`);
      if (installed.error) {
        s.check('service', 'fail', installed.error);
        // Keep a receipt so `--status` / `--remove` can still see and clean up
        // the handler that WAS published.
        serviceReceipt.state = 'stopped';
        const partial = buildReceipt();
        writeExposeReceipt(receiptPath, partial);
        s.check('receipt', 'ok', `${receiptPath} (service stopped)`);
        s.nextActions.push('gbrain mcp expose --status', 'gbrain mcp expose --remove --yes');
        return s.finish('error', 1, { receipt: partial, reason: 'service_install_failed', message: installed.error });
      }
      if (target === 'none') {
        serviceReceipt.state = 'manual';
        const cmds = manualCommands(d, wrapper);
        s.check('service', 'ok', `manual: wrapper written to ${wrapper}`);
        s.say('No user supervisor is available here, so the server is not auto-started. Run it yourself:');
        s.say(`  Foreground   ${cmds.foreground}`);
        s.say(`  Background   ${cmds.background}`);
        s.nextActions.push(cmds.foreground);
      } else {
        serviceReceipt.state = await serveServiceState({ target, run: d.run, uid: d.uid });
        s.check('service', isLiveService(serviceReceipt.state) ? 'ok' : 'warn', serviceLabel(target, serviceReceipt.state, d));
      }
    }

    // Early receipt: the handler is live and the service is installed, so a
    // kill / crash during verify must leave `--status` / `--remove` something
    // to find. Rewritten below with the settled state (created_at kept).
    writeExposeReceipt(receiptPath, buildReceipt());
    receiptWritten = true;
    s.firstPublish = existing === null;

    // 9. verify
    if (opts.noService && !listeningBefore && !keptService) {
      s.check('verify.local', 'skipped', `--no-service and nothing listens on ${localHealthUrl} yet`);
      s.say(`Nothing listens on 127.0.0.1:${opts.port} yet — start the server: ${['gbrain', ...serveCommandArgv({ port: opts.port, publicUrl: publicUrl!, surface: opts.surface, advertise, enableDcr: opts.enableDcr })].join(' ')}`);
    } else if (target === 'none' && !opts.noService && !listeningBefore) {
      s.check('verify.local', 'skipped', 'manual service: start the wrapper, then run --status');
    } else {
      localHealth = (await pollHealth(d, localHealthUrl, d.localHealthMs)).ok ? 'ok' : 'timeout';
      s.check('verify.local', localHealth === 'ok' ? 'ok' : 'warn', `${localHealthUrl}: ${localHealth === 'ok' ? localHealth : statusOnlyHealthDetail(opts.port) ?? localHealth}`);
    }
    if (!opts.noTailscale && localHealth === 'ok') {
      const tn = await pollHealth(d, `${publicUrl}/health`, d.tailnetHealthMs);
      tailnetHealth = tn.ok ? 'ok' : tn.unresolved ? 'unresolved' : 'pending';
      // A name this host cannot resolve is a warn (MagicDNS off HERE), never
      // `pending`: the server may already be reachable from devices that do.
      if (tailnetHealth === 'unresolved') s.check('verify.tailnet', 'warn', `${publicUrl}/health: ${unresolvedDetail(tsStatus!.dnsName!)}`);
      else s.check('verify.tailnet', tailnetHealth === 'ok' ? 'ok' : 'pending', `${publicUrl}/health: ${tailnetHealth}${tailnetHealth === 'pending' ? ' (first certificate issuance can take a minute)' : ''}`);
    } else {
      s.check('verify.tailnet', 'skipped', opts.noTailscale ? '--no-tailscale' : 'local server not confirmed yet');
    }
  } catch (error) {
    throw await rollbackAfterThrow(d, s, opts, published, error, receiptWritten);
  }

  // 10. receipt — the settled state (created_at kept; a supervisor that was
  // still `loaded` when first probed is re-read now that /health had its say).
  if (!keptService && !opts.noService && target !== 'none' && localHealth !== 'skipped') {
    serviceReceipt.state = await serveServiceState({ target, run: d.run, uid: d.uid });
  }
  const receipt = buildReceipt();
  writeExposeReceipt(receiptPath, receipt);
  s.check('receipt', 'ok', receiptPath);

  // Human summary -----------------------------------------------------------
  const tokenHint = tildify(tokenPath, d.home);
  const ownerCredential = opts.noService && !keptService ? '<existing-server-admin-token-file>' : shellQuote(tokenPath);
  const ownerLogin = `gbrain mcp admin login-link --url ${receipt.mcp_url} --admin-token-file ${ownerCredential}`;
  s.say('');
  s.say(opts.noTailscale ? 'GBrain MCP server configured (not published — --no-tailscale)' : `GBrain MCP server published on ${mode === 'funnel' ? 'the public internet via Tailscale Funnel' : 'your tailnet'}`);
  s.say(`  MCP URL   ${receipt.mcp_url}`);
  s.say(`  Admin     ${receipt.admin_url}   (owner session required)`);
  s.say(opts.noService && !keptService
    ? '  Owner     use the credential configured for your existing server; --no-service does not change it.'
    : `  Owner     ${tokenHint} (protected service credential)`);
  s.say(`  Reach     ${mode === 'funnel' ? 'public (Funnel) — cloud agents can connect; gbrain OAuth/bearer + scoped grants protect it.' : 'tailnet only — your devices. Cloud agents (Grok Bot, Muse, ChatGPT) need `--funnel`.'}`);
  s.say(`  Service   ${keptService ? `${serviceLabel(keptService.target, keptService.state, d)} (kept, --no-service)` : opts.noService ? 'skipped (--no-service)' : serviceLabel(target, serviceReceipt.state, d)}`);
  if (engine === 'pglite') {
    s.say('  Engine    PGLite (single-writer): host-side commands that open the database fail with `live_serve` —');
    s.say('            administer through the running server (--admin-token-file; `gbrain sync` delegates to it),');
    s.say('            or move to Postgres for concurrent local use.');
  } else {
    s.say(`  Engine    ${engine === 'postgres' ? 'Postgres' : 'unknown (no brain config found — run gbrain init on this host)'}`);
  }
  if (localHealth === 'timeout') s.say(`  Health    local ${localHealthUrl} did not answer within ${Math.round(d.localHealthMs / 1000)}s — check ${tildify(serveErrPath(d.serveDir), d.home)}`);
  if (tailnetHealth === 'pending') s.say(`  Health    ${publicUrl}/health still pending — re-run \`gbrain mcp expose --status\` in a minute.`);
  if (tailnetHealth === 'unresolved') s.say(`  Health    ${publicUrl}/health: ${unresolvedDetail(tsStatus!.dnsName!)}`);
  s.say('');
  s.say('Next — choose the connection method supported by the intended client');
  s.say(`  Owner login      ${ownerLogin}`);
  s.say('  Native OAuth     gbrain mcp admin register --help (public/confidential PKCE; exact client redirect URIs)');
  s.say('                   The native client starts authorization; the owner separately reviews consent.');
  s.say(`  Machine client   gbrain mcp grant <name> --harness <id> --profile memory-writer --source default \\`);
  s.say(`                     --url ${receipt.mcp_url} \\`);
  s.say(`                     --admin-token-file ${ownerCredential} --credentials-out /private/<name>.json`);
  s.say(`  Machine install  gbrain connect ${receipt.mcp_url} --harness <id> --credentials-file /private/<name>.json --install`);
  const local = localAgentGuidance(engine, opts.port, ownerCredential);
  s.say(`  Local agents     ${local.lines[0]}`);
  for (const line of local.lines.slice(1)) s.say(`                   ${line}`);
  const installLinks = printInstallLinks(receipt.mcp_url, mode === 'funnel', (line) => s.say(line));
  s.say('  Check            gbrain mcp expose --status');
  s.nextActions.push(
    `gbrain mcp grant <name> --harness <id> --profile memory-writer --source default --url ${receipt.mcp_url} --admin-token-file ${ownerCredential} --credentials-out /private/<name>.json`,
    ownerLogin,
    'gbrain mcp admin register --help',
    ...local.nextActions,
    'gbrain mcp expose --status',
  );
  const pending = tailnetHealth === 'pending' || localHealth === 'timeout';
  return s.finish(pending ? 'pending' : 'exposed', pending ? 2 : 0, { receipt, installLinks, ...(pending ? { reason: tailnetHealth === 'pending' ? 'tailnet_health_pending' : 'local_health_timeout' } : {}) });
}

/** The user's publish flags, for a re-run hint or the approved command (never --yes/--json/--dry-run). */
function publishFlags(opts: ExposeOptions): string[] {
  const parts: string[] = [];
  if (opts.port !== DEFAULT_EXPOSE_PORT) parts.push('--port', String(opts.port));
  if (opts.funnel) parts.push('--funnel');
  if (opts.surfaceChosen) parts.push('--surface', opts.surface);
  if (opts.enableDcr) parts.push('--enable-dcr');
  if (opts.noTailscale) parts.push('--no-tailscale');
  if (opts.noService) parts.push('--no-service');
  if (opts.noInstall) parts.push('--no-install');
  return parts;
}

function args2(opts: ExposeOptions): string {
  const parts = publishFlags(opts);
  return parts.length ? ` ${parts.join(' ')}` : '';
}

// ---------------------------------------------------------------------------
// --status
// ---------------------------------------------------------------------------

async function runStatus(d: Resolved, s: Session, opts: ExposeOptions): Promise<number> {
  const receipt = readExposeReceipt(receiptPathFor(d.serveDir));
  if (!receipt) return runStatusWithoutReceipt(d, s, opts);
  s.check('receipt', 'ok', `${receipt.mode} on port ${receipt.port} since ${receipt.created_at}`);
  let allOk = true;
  let pending = false;
  // The four probes (serve config, supervisor, local + tailnet /health) are
  // independent: run them together, then report in the fixed check order.
  const viaTailscale = !!(receipt.tailscale.binary || receipt.tailscale.dns_name);
  const binary = viaTailscale ? resolveReceiptBinary(d, receipt) : null;
  const localUrl = `http://127.0.0.1:${receipt.port}/health`;
  const tailnetUrl = receipt.public_url.startsWith('https://') ? `${receipt.public_url}/health` : null;
  const [serveRead, state, localOk, tailnet] = await Promise.all([
    binary ? readServeView(d, binary) : Promise.resolve<ServeRead | null>(null),
    receipt.service.state !== 'skipped' ? serveServiceState({ target: receipt.service.target, run: d.run, uid: d.uid }) : Promise.resolve<ServiceState | 'skipped'>('skipped'),
    probeHealth(d, localUrl, 3_000),
    tailnetUrl ? tryFetch(d, tailnetUrl, 8_000) : Promise.resolve<FetchOutcome | null>(null),
  ]);
  // tailscale
  if (!viaTailscale) {
    s.check('tailscale.publish', 'skipped', 'published without Tailscale');
  } else if (!serveRead) {
    allOk = false;
    s.check('tailscale.publish', 'fail', 'tailscale binary not found');
  } else if (!serveRead.view) {
    // Fail closed: an unreadable serve config is not "handler present".
    allOk = false;
    s.check('tailscale.publish', 'fail', describeServeReadFailure(d, serveRead).detail);
    s.nextActions.push('tailscale serve status --json');
  } else {
    const view = serveRead.view;
    const ours = findProxiedHandler(view, receipt.port);
    if (!ours) { allOk = false; s.check('tailscale.publish', 'fail', `no :443 handler proxies to port ${receipt.port}`); }
    else if (ours.funnel !== (receipt.mode === 'funnel')) { allOk = false; s.check('tailscale.publish', 'warn', `handler present but funnel=${ours.funnel}; receipt says ${receipt.mode}`); }
    else s.check('tailscale.publish', 'ok', `${ours.host}:443/ -> ${ours.proxy}${ours.funnel ? ' (funnel)' : ''}`);
  }
  // service
  if (receipt.service.state !== 'skipped') {
    const good = isLiveService(state) || state === 'manual';
    if (!good) allOk = false;
    s.check('service', good ? 'ok' : 'fail', serviceLabel(receipt.service.target, state, d));
  } else {
    s.check('service', 'skipped', 'installed with --no-service');
  }
  // health
  if (!localOk) allOk = false;
  const statusOnly = localOk ? null : statusOnlyHealthDetail(receipt.port);
  s.check('verify.local', localOk ? 'ok' : statusOnly ? 'warn' : 'fail', `${localUrl}: ${localOk ? 'ok' : statusOnly ?? 'no answer'}`);
  if (tailnetUrl && tailnet) {
    if (tailnet.res?.ok) s.check('verify.tailnet', 'ok', `${tailnetUrl}: ok`);
    else if (tailnet.unresolved) s.check('verify.tailnet', 'warn', `${tailnetUrl}: ${unresolvedDetail(receipt.tailscale.dns_name ?? receipt.public_url.slice('https://'.length))}`);
    else { pending = true; s.check('verify.tailnet', 'pending', `${tailnetUrl}: pending`); }
  } else {
    s.check('verify.tailnet', 'skipped', 'no https public URL');
  }
  s.say(`GBrain MCP server (${receipt.mode}) — ${receipt.mcp_url}`);
  for (const c of s.checks) s.say(`  ${c.status.padEnd(8)} ${c.name.padEnd(18)} ${c.detail}`);
  if (!allOk) s.nextActions.push('gbrain mcp expose --yes');
  if (!allOk) return s.finish('error', 1, { receipt, reason: 'status_unhealthy' });
  // Spec: --status exits 0 only when EVERYTHING verifies. A pending tailnet
  // certificate is reported as `pending` (not `error`) so callers can tell
  // "wait a minute" from "broken", but it is still a non-zero exit.
  if (pending) { s.nextActions.push('gbrain mcp expose --status'); return s.finish('pending', 1, { receipt, reason: 'tailnet_health_pending', message: 'tailnet health still pending (first certificate issuance can take a minute) — re-run --status shortly.' }); }
  const installLinks = connectorInstallLinks(receipt.mcp_url, receipt.mode === 'funnel');
  const linkLines = installLinkLines(installLinks, receipt.mode === 'funnel');
  for (const line of linkLines.length ? ['', ...linkLines] : []) s.say(line);
  return s.finish('exposed', 0, { receipt, installLinks });
}

interface Leftovers {
  wrapper: string;
  wrapperExists: boolean;
  binary: string | null;
  target: ServiceTarget;
  serviceState: ServiceState | null;
  /** The launchd plist / systemd unit is present, or the supervisor reports our service live. */
  serviceFound: boolean;
  /** The `/` handler on `:443` proxying `port`, when the serve config could be read. */
  handler: ServeHandler | null;
  /** The serve-status read that FAILED (null view), for the caveat line. */
  serveUnreadable: ServeRead | null;
  /** Something of gbrain's besides a handler: the wrapper or the service. */
  evidence: boolean;
}

/**
 * What an interrupted `gbrain mcp expose` (no receipt) can leave behind:
 * `wrapperPath(serveDir)`, the launchd plist / systemd unit or a live
 * service, and a `/` handler on `:443` proxying `port`. Read-only; shared by
 * `--status` and `--remove` without a receipt. The supervisor chain and the
 * serve-status read are independent probes.
 */
async function probeLeftovers(d: Resolved, port: number): Promise<Leftovers> {
  const wrapper = wrapperPathFor(d.serveDir);
  const binary = findTailscaleBinary({ which: d.which, fileExists: d.fileExists });
  const [[target, serviceState], read] = await Promise.all([
    probeServiceTarget(d).then(async (t): Promise<[ServiceTarget, ServiceState | null]> => [t, t !== 'none' ? await serveServiceState({ target: t, run: d.run, uid: d.uid }) : null]),
    binary ? readServeView(d, binary) : Promise.resolve<ServeRead | null>(null),
  ]);
  const unitFile = target === 'macos' ? d.plistPath : target === 'linux-systemd' ? d.unitPath : null;
  const wrapperExists = existsSync(wrapper);
  const serviceFound = target !== 'none' && ((unitFile !== null && existsSync(unitFile)) || isLiveService(serviceState));
  return {
    wrapper, wrapperExists, binary, target, serviceState, serviceFound,
    handler: read?.view ? findProxiedHandler(read.view, port) : null,
    serveUnreadable: read && !read.view ? read : null,
    evidence: wrapperExists || serviceFound,
  };
}

/** `--remove --yes [--force] [--port N]` for the receipt-less recovery. */
function recoveryCommand(port: number, force: boolean): string {
  return `gbrain mcp expose --remove --yes${force ? ' --force' : ''}${port !== DEFAULT_EXPOSE_PORT ? ` --port ${port}` : ''}`;
}

/**
 * `--status` with NO receipt: not simply "not exposed" — an interrupted run
 * may have left the wrapper, the unit / service or a `:443` handler behind.
 * Any of them found → one warn check per artifact, the recovery command in
 * `next_actions` (`--force` when only a handler stands, since nothing else of
 * gbrain's corroborates it), reason `leftovers_without_receipt`, exit 1.
 */
async function runStatusWithoutReceipt(d: Resolved, s: Session, opts: ExposeOptions): Promise<number> {
  const lo = await probeLeftovers(d, opts.port);
  const found: string[] = [];
  if (lo.wrapperExists || lo.serviceFound || lo.handler) s.check('receipt', 'warn', `no expose receipt, but leftovers of an interrupted publish are on this host (port ${opts.port})`);
  else s.check('receipt', 'skipped', 'no expose receipt');
  if (lo.serviceFound) { s.check('service', 'warn', `${serviceKindLabel(lo.target)} is installed${lo.serviceState ? ` (${lo.serviceState})` : ''} without a receipt`); found.push(`the ${serviceKindLabel(lo.target)} service`); }
  if (lo.handler) { s.check('tailscale.publish', 'warn', `a :443 handler proxies ${lo.handler.proxy}${lo.handler.funnel ? ' (funnel)' : ''} without a receipt`); found.push(`the :443 handler proxying ${lo.handler.proxy}`); }
  else if (lo.serveUnreadable) s.check('tailscale.publish', 'warn', `${describeServeReadFailure(d, lo.serveUnreadable).detail}; a handler for port ${opts.port} could not be checked`);
  if (lo.wrapperExists) { s.check('files', 'warn', `wrapper ${tildify(lo.wrapper, d.home)} exists without a receipt`); found.push(`the wrapper ${tildify(lo.wrapper, d.home)}`); }
  if (found.length === 0) {
    s.say('not exposed — run: gbrain mcp expose');
    s.nextActions.push('gbrain mcp expose');
    return s.finish('not_exposed', s.json ? 2 : 0, { reason: 'not_exposed' });
  }
  const rerun = recoveryCommand(opts.port, !lo.evidence);
  s.say(`not exposed, but an interrupted \`gbrain mcp expose\` left these behind (port ${opts.port}): ${found.join('; ')}`);
  s.say(`  Clean up: ${rerun}`);
  s.nextActions.push(rerun);
  return s.finish('error', 1, { reason: 'leftovers_without_receipt', message: `leftovers without a receipt: ${found.join('; ')} — run ${rerun}` });
}

// ---------------------------------------------------------------------------
// --remove
// ---------------------------------------------------------------------------

interface HandlerOffOutcome {
  /** `funnel off: exit 0, serve off: exit 0` style ledger. */
  results: string[];
  /** The handler that survived, `'unknown'` when the re-read failed, null when it is gone. */
  remaining: ServeHandler | 'unknown' | null;
}

/**
 * Turn OUR `/` handler on `:443` (the one proxying `port`) off: Funnel first
 * when it is on, then the plain serve handler if it is still there. The serve
 * config is re-read only after a command could have changed it; a failed
 * re-read is reported as `unknown` (fail closed), never as "gone".
 */
async function turnOffOurHandler(d: Resolved, binary: string, port: number, ours: ServeHandler, funnelFirst: boolean): Promise<HandlerOffOutcome> {
  const results: string[] = [];
  if (funnelFirst || ours.funnel) {
    const off = await d.run([binary, ...tailscaleServeOffArgv({ funnel: true })], { timeoutMs: SERVE_OFF_TIMEOUT_MS });
    results.push(`funnel off: exit ${off.status ?? 'null'}`);
  }
  let stillThere: ServeHandler | 'unknown' | null = ours;
  if (results.length) {
    const re = await readServeView(d, binary);
    stillThere = re.view ? findProxiedHandler(re.view, port) : 'unknown';
  }
  if (stillThere) {
    const off = await d.run([binary, ...tailscaleServeOffArgv({ funnel: false })], { timeoutMs: SERVE_OFF_TIMEOUT_MS });
    results.push(`serve off: exit ${off.status ?? 'null'}`);
    const re = await readServeView(d, binary);
    return { results, remaining: re.view ? findProxiedHandler(re.view, port) : 'unknown' };
  }
  return { results, remaining: null };
}

function recordHandlerOff(s: Session, outcome: HandlerOffOutcome, left: string[]): void {
  const { results, remaining } = outcome;
  if (remaining === 'unknown') {
    s.check('tailscale.publish', 'warn', `${results.join(', ')} — could not re-read tailscale serve status afterwards; run \`tailscale serve status\``);
    left.push('the tailscale serve handler (state unknown: serve status could not be re-read)');
    return;
  }
  s.check('tailscale.publish', remaining ? 'fail' : 'ok', `${results.join(', ')}${remaining ? ' — handler still present; run `tailscale serve status`' : ''}`);
  if (remaining) left.push('the tailscale serve handler');
}

/**
 * `--remove` never reports success while our handler survives: when the off
 * attempt leaves it present (or its state unreadable) the receipt and the
 * wrapper are kept — exactly as on an unreadable serve status — so a re-run
 * finds everything again, and the exit is 1 / `handler_not_removed`. The
 * service was already uninstalled by then; `serviceNote` says so.
 */
function finishHandlerNotRemoved(s: Session, p: { receipt: ExposeReceipt | null; port: number; remaining: ServeHandler | 'unknown'; serviceNote: string; kept: string; rerun: string }): number {
  const why = p.remaining === 'unknown' ? 'could not be confirmed gone (tailscale serve status could not be re-read)' : 'is still present';
  s.check(p.receipt ? 'receipt' : 'files', 'skipped', `kept: ${p.kept} — the :443 handler for port ${p.port} ${why}; re-run --remove once it can be turned off`);
  s.nextActions.push('tailscale serve status', p.rerun);
  s.say('');
  s.say(`Stopped here: ${p.serviceNote}, but the tailscale handler for port ${p.port} ${why}. Left in place: ${p.kept}. Run \`tailscale serve status\`, then re-run \`${p.rerun}\`.`);
  return s.finish('error', 1, { receipt: p.receipt, reason: 'handler_not_removed', message: `the tailscale handler for port ${p.port} ${why}; left in place: ${p.kept}` });
}

/**
 * The `service` check after `uninstallServeService`: notes as prose; a launchd
 * bootout that failed for a non-benign reason is a warn and the job is named
 * as left. Returns the one-line summary `finishHandlerNotRemoved` quotes.
 */
function recordServiceUninstall(s: Session, r: UninstallServiceResult, left: string[]): string {
  for (const note of r.notes) s.say(`Note: ${note}`);
  const files = r.removed.length ? `removed ${r.removed.join(', ')}` : 'no unit file to delete';
  if (launchdBootoutFailed(r)) {
    left.push('the launchd job (bootout failed)');
    s.check('service', 'warn', `${files}; launchctl bootout failed, so the job may still be loaded — check \`launchctl print gui/$(id -u)/${SERVE_LAUNCHD_LABEL}\``);
    return 'the service files were removed but the launchd bootout failed';
  }
  s.check('service', 'ok', r.removed.length ? files : 'stopped (no unit file to delete)');
  return 'the service was stopped and removed';
}

/**
 * A path in a receipt is data, never a licence to delete elsewhere: the
 * wrapper, receipt and admin token are unlinked only inside the serve
 * directory; the plist and unit are only ever the computed paths
 * (`d.plistPath` / `d.unitPath`), whatever the receipt recorded.
 */
function serveDirGuard(d: Resolved): (p: string) => boolean {
  const serveDir = resolvePath(d.serveDir);
  return (p: string) => dirname(resolvePath(p)) === serveDir;
}

const OUTSIDE_NOTE = 'outside the serve directory; not touched';
const RECORDED_ELSEWHERE_NOTE = 'recorded in the receipt but not the expected location; not touched';

function unlinkQuietly(s: Session, p: string, removed: string[]): void {
  try { if (existsSync(p)) { unlinkSync(p); removed.push(p); } } catch (error) { s.say(`Note: could not delete ${p}: ${error instanceof Error ? error.message : String(error)}`); }
}

async function runRemove(d: Resolved, s: Session, opts: ExposeOptions): Promise<number> {
  const receiptPath = receiptPathFor(d.serveDir);
  const receipt = readExposeReceipt(receiptPath);
  if (!receipt) return runRemoveWithoutReceipt(d, s, opts);
  const inServeDir = serveDirGuard(d);
  const wrapperFile = receipt.service.wrapper_path;
  const tokenFile = receipt.admin_token_file;
  const plan = [
    receipt.service.state === 'skipped' ? 'Service   none installed' : receipt.service.target === 'none' ? 'Service   manual — nothing to stop here (stop the wrapper process yourself); the wrapper file is deleted below' : `Service   stop + remove ${serviceKindLabel(receipt.service.target)}`,
    receipt.tailscale.binary ? `Tailscale turn off OUR :443 handler${receipt.mode === 'funnel' ? ' (funnel first)' : ''} — Tailscale stays installed and signed in` : 'Tailscale nothing to undo',
    inServeDir(wrapperFile)
      ? `Files     delete ${tildify(wrapperFile, d.home)} and ${tildify(receiptPath, d.home)}`
      : `Files     delete ${tildify(receiptPath, d.home)}; leave ${tildify(wrapperFile, d.home)} (${OUTSIDE_NOTE})`,
    !inServeDir(tokenFile)
      ? `Token     leave ${tildify(tokenFile, d.home)} (${OUTSIDE_NOTE})`
      : opts.force ? `Token     delete ${tildify(tokenFile, d.home)} (--force)` : `Token     keep ${tildify(tokenFile, d.home)} (dashboard session may still use it; --force deletes)`,
  ];
  s.check('plan', 'ok', plan.join(' | '));
  s.say('Remove plan');
  for (const line of plan) s.say(`  ${line}`);
  const consent = await confirmOrFinish(d, s, 'Remove the published server? [y/N] ', {
    yes: opts.yes, receipt, confirmationMessage: 'Pass --yes to confirm the removal.',
    argv: ['gbrain', 'mcp', 'expose', '--remove', ...(opts.force ? ['--force'] : [])],
    effects: ['persistent_install'], what: 'mcp expose --remove',
    why: 'Stops and removes the published server: the user service, the Tailscale handler and the files listed in the remove plan.',
    risk: 'Agents connected through the published URL lose access until it is published again.',
    user_message: 'I\'d like to unpublish your gbrain MCP server (stop its service and remove its Tailscale handler). OK?',
  });
  if (consent !== null) return consent;
  const left: string[] = [];
  // service — the receipt may say `skipped` (a `--no-service` run) while a
  // service from an earlier run still exists; probe the supervisor too.
  let serviceTarget: ServiceTarget = receipt.service.target;
  let serviceKnown = receipt.service.state !== 'skipped';
  if (!serviceKnown) {
    serviceTarget = await probeServiceTarget(d);
    if (serviceTarget !== 'none') {
      const unitFile = serviceTarget === 'macos' ? d.plistPath : d.unitPath;
      const state = await serveServiceState({ target: serviceTarget, run: d.run, uid: d.uid });
      serviceKnown = isLiveService(state) || existsSync(unitFile);
      if (serviceKnown) s.say(`Note: the receipt says no service was installed, but a ${serviceLabel(serviceTarget, state, d)} exists — removing it too.`);
    }
  }
  // The plist / unit paths the receipt recorded are never handed to the
  // supervisor step: only the computed paths are touched, and a recorded path
  // that differs is named as left in place.
  for (const [recorded, computed] of [[receipt.service.plist_path, d.plistPath], [receipt.service.unit_path, d.unitPath]] as const) {
    if (recorded !== null && recorded !== computed) left.push(`${tildify(recorded, d.home)} (${RECORDED_ELSEWHERE_NOTE})`);
  }
  let serviceNote = 'there was no service to stop';
  if (serviceKnown && serviceTarget !== 'none') {
    serviceNote = recordServiceUninstall(s, await uninstallServeService({ target: serviceTarget, home: d.home, run: d.run, uid: d.uid, plistPath: d.plistPath, unitPath: d.unitPath }), left);
  } else {
    const manualLeft = receipt.service.target === 'none' && receipt.service.state !== 'skipped';
    s.check('service', 'skipped', manualLeft ? 'manual service: stop the wrapper process yourself if it is running' : 'none installed');
    if (manualLeft) left.push('a manually started server process (if any)');
  }
  // tailscale handler
  if (receipt.tailscale.binary || receipt.tailscale.dns_name) {
    const binary = resolveReceiptBinary(d, receipt);
    if (!binary) {
      s.check('tailscale.publish', 'warn', 'tailscale binary not found; serve handler left as is');
      left.push('the tailscale serve handler (binary not found)');
    } else {
      const read = await readServeView(d, binary);
      if (!read.view) {
        // Fail closed: do not guess which handler is ours, and keep the
        // receipt + wrapper so a re-run can finish the job.
        s.check('tailscale.publish', 'fail', `${describeServeReadFailure(d, read).detail}; handler left as is`);
        s.check('receipt', 'skipped', 'kept (the tailscale serve status could not be read; re-run --remove once it can)');
        s.nextActions.push('tailscale serve status --json', 'gbrain mcp expose --remove --yes');
        s.say('');
        s.say('Stopped here: could not read `tailscale serve status`, so the handler, the wrapper and the receipt were left in place. Fix Tailscale, then run the removal again (the user already approved it: `gbrain mcp expose --remove --yes`).');
        return s.finish('error', 1, { receipt, reason: 'tailscale_serve_status_unreadable', message: 'could not read tailscale serve status; handler left as is' });
      }
      const ours = findProxiedHandler(read.view, receipt.port);
      if (!ours) {
        s.check('tailscale.publish', 'ok', `no :443 handler proxies to port ${receipt.port}; nothing to turn off`);
      } else {
        const outcome = await turnOffOurHandler(d, binary, receipt.port, ours, receipt.mode === 'funnel');
        recordHandlerOff(s, outcome, left);
        if (outcome.remaining !== null) {
          return finishHandlerNotRemoved(s, { receipt, port: receipt.port, remaining: outcome.remaining, kept: 'the wrapper and the receipt', rerun: 'gbrain mcp expose --remove --yes', serviceNote });
        }
      }
    }
    left.push('Tailscale itself (installed and signed in)');
  } else {
    s.check('tailscale.publish', 'skipped', 'published without Tailscale');
  }
  // files
  const removed: string[] = [];
  for (const p of [wrapperFile, receiptPath]) {
    if (!inServeDir(p)) { left.push(`${tildify(p, d.home)} (${OUTSIDE_NOTE})`); continue; }
    unlinkQuietly(s, p, removed);
  }
  if (!inServeDir(tokenFile)) {
    left.push(`${tildify(tokenFile, d.home)} (admin token ${OUTSIDE_NOTE})`);
  } else if (opts.force) {
    unlinkQuietly(s, tokenFile, removed);
  } else if (existsSync(tokenFile)) {
    left.push(`${tildify(tokenFile, d.home)} (admin token; pass --force to delete)`);
  }
  s.check('receipt', 'ok', `removed ${removed.map(p => tildify(p, d.home)).join(', ') || 'nothing'}`);
  s.say('');
  s.say('Removed the published MCP server.');
  s.say(`  Left in place: ${left.length ? left.join('; ') : 'nothing'}`);
  s.say(`  Log files: ${tildify(serveLogPath(d.serveDir), d.home)}, ${tildify(serveErrPath(d.serveDir), d.home)} (kept)`);
  return s.finish('removed', 0, { receipt: null });
}

/**
 * `--remove` with NO receipt: an interrupted `gbrain mcp expose` (killed
 * between `tailscale serve --bg` and the receipt write) can leave the
 * wrapper, a launchd/systemd unit and a `:443` handler behind. Recover from
 * what is on disk: remove exactly those artifacts (for `--port`, default
 * 3131), leave the admin token, and say so. A `:443` handler proxying the
 * port is turned off only when something else of gbrain's corroborates it
 * (the wrapper, our unit/plist, or the supervisor reporting our service) —
 * another tool may proxy the same port — or with `--force`. Nothing of ours
 * found → today's "not exposed — nothing to remove", exit 0.
 */
async function runRemoveWithoutReceipt(d: Resolved, s: Session, opts: ExposeOptions): Promise<number> {
  const { wrapper, wrapperExists, binary, target, serviceState, serviceFound, handler, serveUnreadable, evidence } = await probeLeftovers(d, opts.port);
  /** The handler we will turn off: only with corroborating evidence or `--force`. */
  const handlerOff = handler && (evidence || opts.force) ? handler : null;
  const forceRerun = recoveryCommand(opts.port, true);
  if (!evidence && !handlerOff) {
    s.check('receipt', 'skipped', 'no expose receipt; nothing to remove');
    if (serveUnreadable) s.check('tailscale.publish', 'warn', `${describeServeReadFailure(d, serveUnreadable).detail}; a handler for port ${opts.port} could not be checked`);
    if (handler) {
      const note = `a :443 handler proxies ${handler.proxy} but nothing else of gbrain's is here (no wrapper, unit or service), so it is not proven to be ours; left as is — pass --force to turn it off`;
      s.check('tailscale.publish', 'warn', note);
      s.nextActions.push(forceRerun);
      s.say(`Note: ${note}`);
    }
    s.say('not exposed — nothing to remove');
    return s.finish('not_exposed', 0, { reason: 'not_exposed' });
  }
  const plan = [
    serviceFound ? `Service   stop + remove ${serviceKindLabel(target)}${serviceState ? ` (${serviceState})` : ''}` : 'Service   none found',
    handlerOff ? `Tailscale turn off the :443 handler proxying ${handlerOff.proxy}${handlerOff.funnel ? ' (funnel first)' : ''}${evidence ? '' : ' (--force: no wrapper, unit or service corroborates it)'} — Tailscale stays installed and signed in` : serveUnreadable ? `Tailscale could not read serve status; a handler for port ${opts.port} cannot be checked — stops after the service step (exit 1)` : `Tailscale no :443 handler proxies to port ${opts.port}`,
    wrapperExists ? (serveUnreadable ? `Files     keep ${tildify(wrapper, d.home)} (the corroboration a re-run needs while serve status cannot be read)` : `Files     delete ${tildify(wrapper, d.home)}`) : 'Files     no wrapper found',
    `Token     leave ${tildify(adminTokenPathFor(d.serveDir), d.home)} (no receipt names it)`,
  ];
  s.check('receipt', 'warn', `no expose receipt — recovering from what is on disk (port ${opts.port})`);
  s.check('plan', 'ok', plan.join(' | '));
  s.say(`Recovering without a receipt (an interrupted \`gbrain mcp expose\` left these behind; port ${opts.port}):`);
  for (const line of plan) s.say(`  ${line}`);
  const rerun = recoveryCommand(opts.port, opts.force);
  const consent = await confirmOrFinish(d, s, 'Remove these leftovers? [y/N] ', {
    yes: opts.yes, receipt: null, confirmationMessage: 'Pass --yes to confirm the removal.', nextAction: rerun,
    argv: ['gbrain', 'mcp', 'expose', '--remove', ...(opts.force ? ['--force'] : []), ...(opts.port !== DEFAULT_EXPOSE_PORT ? ['--port', String(opts.port)] : [])],
    effects: ['persistent_install'], what: 'mcp expose --remove',
    why: `Removes what an interrupted \`gbrain mcp expose\` left behind on port ${opts.port} (the service, a Tailscale handler, the wrapper), as listed in the plan.`,
    risk: 'Anything still using that server loses it.',
    user_message: 'An interrupted gbrain publish left a server behind. I\'d like to remove those leftovers. OK?',
  });
  if (consent !== null) return consent;
  const left: string[] = [];
  let serviceNote = 'no service was found';
  if (serviceFound) {
    serviceNote = recordServiceUninstall(s, await uninstallServeService({ target, home: d.home, run: d.run, uid: d.uid, plistPath: d.plistPath, unitPath: d.unitPath }), left);
  } else {
    s.check('service', 'skipped', 'none found');
  }
  if (handlerOff && binary) {
    const outcome = await turnOffOurHandler(d, binary, opts.port, handlerOff, handlerOff.funnel);
    recordHandlerOff(s, outcome, left);
    // The wrapper stays as corroborating evidence for the re-run (without it
    // a handler standing alone would need `--force`).
    if (outcome.remaining !== null) {
      return finishHandlerNotRemoved(s, { receipt: null, port: opts.port, remaining: outcome.remaining, kept: wrapperExists ? 'the wrapper' : 'nothing (no wrapper was found)', rerun: recoveryCommand(opts.port, opts.force || !wrapperExists), serviceNote });
    }
    left.push('Tailscale itself (installed and signed in)');
  } else if (serveUnreadable) {
    // Fail closed, as with a receipt: the handler cannot be checked, so the
    // wrapper stays as the corroboration the re-run needs (the service, when
    // found, is already gone) and the exit says the job is not finished.
    const kept = wrapperExists ? 'the wrapper' : 'nothing (no wrapper was found)';
    const unreadableRerun = recoveryCommand(opts.port, opts.force || !wrapperExists);
    s.check('tailscale.publish', 'fail', `${describeServeReadFailure(d, serveUnreadable).detail}; handler state unknown`);
    s.check('files', 'skipped', `kept: ${kept} — the :443 handler for port ${opts.port} could not be checked; re-run --remove once tailscale serve status can be read`);
    s.nextActions.push('tailscale serve status --json', unreadableRerun);
    s.say('');
    s.say(`Stopped here: ${serviceNote}, but \`tailscale serve status\` could not be read, so the handler state for port ${opts.port} is unknown. Left in place: ${kept}. Fix Tailscale, then re-run \`${unreadableRerun}\`.`);
    return s.finish('error', 1, { receipt: null, reason: 'tailscale_serve_status_unreadable', message: 'could not read tailscale serve status; handler state unknown' });
  } else {
    s.check('tailscale.publish', 'ok', binary ? `no :443 handler proxies to port ${opts.port}; nothing to turn off` : 'tailscale binary not found; nothing to turn off');
  }
  const removed: string[] = [];
  if (wrapperExists) unlinkQuietly(s, wrapper, removed);
  const tokenFile = adminTokenPathFor(d.serveDir);
  if (existsSync(tokenFile)) left.push(`${tildify(tokenFile, d.home)} (admin token; left without a receipt)`);
  s.check('files', 'ok', `removed ${removed.map(p => tildify(p, d.home)).join(', ') || 'nothing'}`);
  s.say('');
  s.say('Removed the leftovers of an interrupted publish.');
  s.say(`  Left in place: ${left.length ? left.join('; ') : 'nothing'}`);
  return s.finish('removed', 0, { receipt: null, reason: 'recovered_without_receipt' });
}