Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
178 KB
Raw Blame
/**
 * `gbrain mcp expose` end-to-end against a stateful fake tailnet: a recording
 * runner stands in for tailscale/systemctl/launchctl, fetch is injected, every
 * path lives in a tmpdir. No network, no real supervisor, no process.env writes.
 */
import { afterEach, describe, expect, spyOn, test } from 'bun:test';
import * as dnsPromises from 'node:dns/promises';
import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, mkdirSync } from 'node:fs';
import { createServer } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { mcpNeedsEngine, runMcp } from '../src/commands/mcp.ts';
import { defaultTcpProbe, runMcpExpose, parseExposeArgs, MCP_EXPOSE_HELP, type McpExposeDeps } from '../src/commands/mcp-expose.ts';
import { defaultLookup, isUnresolvedLookupError, tryFetch } from '../src/commands/mcp-expose-probe.ts';
import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';
import { TAILSCALE_ADMIN_ACL_URL, TAILSCALE_ADMIN_DNS_URL, TAILSCALE_BINARY_CANDIDATES, TAILSCALE_FUNNEL_KB_URL, type CommandRunner, type CommandRunOptions } from '../src/core/tailscale.ts';
import { adminTokenPath, readExposeReceipt, receiptPath, wrapperPath, writeExposeReceipt, type ExposeReceipt } from '../src/core/serve-service.ts';

const roots: string[] = [];
const temp = () => { const p = mkdtempSync(join(tmpdir(), 'gbrain-mcp-expose-')); roots.push(p); return p; };
afterEach(() => { for (const p of roots.splice(0)) rmSync(p, { recursive: true, force: true }); });

const DNS = 'your-machine.your-tailnet.ts.net';
const TS = '/usr/bin/tailscale';
const APP_TS = '/Applications/Tailscale.app/Contents/MacOS/Tailscale';
const TOKEN = 'f'.repeat(64);
/**
 * Hermetic `fileExists`: every Tailscale binary candidate answers from the
 * fake (`present`), never from the developer's real filesystem — a real
 * Tailscale at /usr/local/bin, /opt/homebrew/bin or in /Applications must not
 * leak into `findTailscaleBinary`. Other paths fall through to `existsSync`
 * only under the test's tmp home.
 */
const hermeticExists = (home: string, present: (candidate: string) => boolean) => (p: string): boolean =>
  TAILSCALE_BINARY_CANDIDATES.includes(p) ? present(p) : (p === home || p.startsWith(`${home}/`)) && existsSync(p);

interface TailnetOpts {
  /** Path the fake tailscale answers under (default /usr/bin/tailscale; darwin runs use the app bundle). */
  binary?: string;
  backendState?: string;
  /** BackendState after `tailscale up` ran (default: Running). */
  afterUp?: string;
  certDomains?: string[];
  dnsName?: string | null;
  /** Self.CapMap: true → carries the Funnel capability, false → CapMap without it, undefined → no CapMap field. */
  funnelCapable?: boolean;
  /** Self.CapMap verbatim (overrides funnelCapable). */
  capMap?: Record<string, unknown>;
  /** Pre-existing root handlers: port → funnel flag. */
  existingHandlers?: Record<number, boolean>;
  publishStatus?: number | null;
  publishStderr?: string;
  /** `--bg` exits 0 but registers nothing (the CLI lied). */
  publishNoop?: boolean;
  /** Register the handler with THIS funnel flag regardless of the subcommand (mismatch drill). */
  publishedFunnel?: boolean;
  statusStderr?: string;
  statusStdoutOverride?: string;
  userBusStatus?: number;
  serviceActive?: string;
  /** Exit status of `sudo tailscale set --operator=…` (default 0). */
  setOperatorStatus?: number;
  /** Local health answers before anything is installed (a foreign listener). */
  localListeningBefore?: boolean;
  tailnetHealthy?: boolean;
  localHealthyAfterStart?: boolean;
}

interface Fake {
  run: CommandRunner;
  calls: string[][];
  /** Every runner invocation with the opts the command passed (inherit / stdoutToStderr / timeoutMs). */
  recorded: { argv: string[]; opts: CommandRunOptions | undefined }[];
  fetches: string[];
  stdout: string[];
  stderr: string[];
  deps: McpExposeDeps;
  home: string;
  serveDir: string;
  /** Flip the fake service off (as if the supervisor stopped it). */
  stopService: () => void;
}

function fakeTailnet(o: TailnetOpts = {}): Fake {
  const home = temp();
  const ts = o.binary ?? TS;
  const serveDir = join(home, '.gbrain', 'serve');
  const handlers: Record<number, boolean> = { ...(o.existingHandlers ?? {}) };
  let state = o.backendState ?? 'Running';
  let serviceStarted = false;
  const calls: string[][] = [];
  const recorded: Fake['recorded'] = [];
  const fetches: string[] = [];
  const stdout: string[] = [];
  const stderr: string[] = [];
  const statusDoc = () => JSON.stringify({
    Version: '1.80.0', BackendState: state,
    Self: {
      DNSName: o.dnsName === undefined ? `${DNS}.` : (o.dnsName ?? ''), TailscaleIPs: ['100.64.0.1'],
      ...(o.capMap ? { CapMap: o.capMap } : o.funnelCapable === undefined ? {} : { CapMap: o.funnelCapable ? { 'https://tailscale.com/cap/funnel': [] } : { 'https://tailscale.com/cap/is-admin': [] } }),
    },
    CurrentTailnet: { MagicDNSEnabled: true }, CertDomains: o.certDomains ?? [DNS],
  });
  const serveDoc = () => {
    const web: Record<string, unknown> = {};
    const allow: Record<string, boolean> = {};
    for (const [port, funnel] of Object.entries(handlers)) {
      web[`${DNS}:443`] = { Handlers: { '/': { Proxy: `http://127.0.0.1:${port}` } } };
      if (funnel) allow[`${DNS}:443`] = true;
    }
    return JSON.stringify({ TCP: { '443': { HTTPS: true } }, Web: web, AllowFunnel: allow });
  };
  const run: CommandRunner = async (argv, runOpts) => {
    calls.push(argv);
    recorded.push({ argv, opts: runOpts });
    const joined = argv.join(' ');
    if (joined === `${ts} status --json`) {
      // `status --json` exits 0 in every BackendState (only the human form exits 1 when logged out).
      if (o.statusStdoutOverride !== undefined) return { status: 1, stdout: o.statusStdoutOverride, stderr: o.statusStderr ?? '' };
      return { status: 0, stdout: statusDoc(), stderr: o.statusStderr ?? '' };
    }
    if (joined === `${ts} serve status --json`) return { status: 0, stdout: serveDoc(), stderr: '' };
    if (argv[0] === 'sudo' && argv[1] === ts && argv[2] === 'set') return { status: o.setOperatorStatus ?? 0, stdout: '', stderr: o.setOperatorStatus ? 'set: permission denied' : '' };
    if ((argv[0] === 'sudo' && argv[1] === ts && argv[2] === 'up') || (argv[0] === ts && argv[1] === 'up')) { state = o.afterUp ?? 'Running'; return { status: 0, stdout: '', stderr: '' }; }
    if (argv[0] === ts && (argv[1] === 'serve' || argv[1] === 'funnel') && argv[2] === '--bg') {
      if (o.publishStatus !== undefined && o.publishStatus !== 0) return { status: o.publishStatus, stdout: '', stderr: o.publishStderr ?? 'boom' };
      if (o.publishNoop) return { status: 0, stdout: '', stderr: '' };
      for (const k of Object.keys(handlers)) delete handlers[Number(k)];
      handlers[Number(argv[3])] = o.publishedFunnel ?? (argv[1] === 'funnel');
      return { status: 0, stdout: '', stderr: '' };
    }
    if (argv[0] === ts && argv[2] === '--https=443' && argv[3] === '--set-path=/' && argv[4] === 'off') {
      for (const k of Object.keys(handlers)) delete handlers[Number(k)];
      return { status: 0, stdout: '', stderr: '' };
    }
    if (argv[0] === 'open') return { status: 0, stdout: '', stderr: '' };
    // systemd (user)
    if (joined === 'systemctl --user is-system-running') return { status: o.userBusStatus ?? 0, stdout: o.userBusStatus === undefined ? 'running\n' : '', stderr: '' };
    if (joined.startsWith('systemctl --user restart')) { serviceStarted = true; return { status: 0, stdout: '', stderr: '' }; }
    if (joined.startsWith('systemctl --user disable --now')) { serviceStarted = false; return { status: 0, stdout: '', stderr: '' }; }
    if (joined.startsWith('systemctl --user is-active')) return { status: serviceStarted ? 0 : 3, stdout: `${o.serviceActive ?? (serviceStarted ? 'active' : 'inactive')}\n`, stderr: '' };
    // launchd (modern, domain-explicit verbs; the legacy load/unload pair is never expected here)
    if (joined.startsWith('launchctl bootstrap gui/')) { serviceStarted = true; return { status: 0, stdout: '', stderr: '' }; }
    if (joined.startsWith('launchctl bootout gui/')) { const was = serviceStarted; serviceStarted = false; return { status: was ? 0 : 3, stdout: '', stderr: was ? '' : 'Boot-out failed: 3: No such process' }; }
    if (joined.startsWith('launchctl load') || joined.startsWith('launchctl unload')) return { status: 64, stdout: '', stderr: 'legacy verb: not expected' };
    if (joined.startsWith('launchctl print')) return serviceStarted ? { status: 0, stdout: 'state = running\n', stderr: '' } : { status: 113, stdout: '', stderr: 'Could not find service' };
    return { status: 0, stdout: '', stderr: '' };
  };
  const deps: McpExposeDeps = {
    platform: 'linux', env: { HOME: home, USER: 'alice-example', PATH: '/usr/bin' }, home, user: 'alice-example', uid: 1000,
    serveDir, gbrainEnvFile: join(home, '.gbrain', 'env'), plistPath: join(home, 'LaunchAgents', 'com.gbrain.serve.plist'), unitPath: join(home, '.config', 'systemd', 'user', 'gbrain-serve.service'),
    loadConfig: () => ({ engine: 'pglite', database_path: join(home, 'brain.pglite') } as never), executionEnv: 'local', run,
    mutedNotices: () => new Set(),
    which: (n) => (n === 'tailscale' ? TS : n === 'systemctl' ? '/usr/bin/systemctl' : n === 'gbrain' ? '/usr/local/bin/gbrain' : null),
    fileExists: hermeticExists(home, (p) => p === ts),
    fetch: async (url) => {
      fetches.push(url);
      if (url.startsWith('http://127.0.0.1:')) {
        if (o.localListeningBefore) return { ok: true, status: 200 };
        if (serviceStarted && (o.localHealthyAfterStart ?? true)) return { ok: true, status: 200 };
        throw new Error('ECONNREFUSED');
      }
      if (url.startsWith(`https://${DNS}/`)) { if (o.tailnetHealthy ?? true) return { ok: true, status: 200 }; throw new Error('cert pending'); }
      throw new Error(`unexpected fetch ${url}`);
    },
    // The default tcpProbe opens a real loopback socket; the fake never does.
    tcpProbe: async () => false,
    // The default lookup asks the real resolver; the fake resolves every name (tests that need an unresolvable name inject their own).
    lookup: async () => {},
    isTTY: false, prompt: async () => { throw new Error('prompt must not be called'); },
    stdout: (l) => stdout.push(l), stderr: (l) => stderr.push(l),
    now: () => new Date('2026-06-01T12:00:00.000Z'), sleep: async () => {},
    gbrainCommand: ['/usr/local/bin/gbrain'], runtimeDir: '/home/alice-example/.bun/bin', randomHex: () => TOKEN,
    localHealthMs: 3, tailnetHealthMs: 3, healthIntervalMs: 1,
  };
  return { run, calls, recorded, fetches, stdout, stderr, deps, home, serveDir, stopService: () => { serviceStarted = false; } };
}

/** A darwin fake: app-bundle binary (no PATH hit), launchd target, brew present. */
function fakeMac(o: TailnetOpts = {}): Fake {
  const f = fakeTailnet({ ...o, binary: APP_TS });
  f.deps.platform = 'darwin';
  f.deps.uid = 501;
  f.deps.which = (n) => (n === 'brew' ? '/opt/homebrew/bin/brew' : n === 'gbrain' ? '/usr/local/bin/gbrain' : null);
  f.deps.fileExists = hermeticExists(f.home, (p) => p === APP_TS);
  return f;
}

const jsonDoc = (f: Fake) => { expect(f.stdout).toHaveLength(1); return JSON.parse(f.stdout[0]); };
const checkOf = (doc: { checks: { name: string; status: string; detail: string }[] }, name: string) => doc.checks.find(c => c.name === name);
const joinedCalls = (f: Fake) => f.calls.map(c => c.join(' '));
const readAll = (dir: string): Record<string, string> => {
  const out: Record<string, string> = {};
  const walk = (d: string) => { for (const e of readdirSync(d, { withFileTypes: true })) { const p = join(d, e.name); if (e.isDirectory()) walk(p); else out[p] = readFileSync(p, 'utf-8'); } };
  if (existsSync(dir)) walk(dir);
  return out;
};
/** A complete receipt for `f` (the shape a real run writes — the reader refuses partial ones); `over` patches top-level fields. */
const fullReceipt = (f: Fake, over: Partial<ExposeReceipt> = {}): ExposeReceipt => ({
  version: 1, created_at: '2026-05-01T00:00:00.000Z', updated_at: '2026-05-01T00:00:00.000Z', port: 3131,
  public_url: `https://${DNS}`, mcp_url: `https://${DNS}/mcp`, admin_url: `https://${DNS}/admin`, mode: 'tailnet', surface: 'full', enable_dcr: false,
  tailscale: { binary: TS, dns_name: DNS, tailscale_version: '1.80.0' },
  service: { target: 'linux-systemd', unit_path: null, plist_path: null, wrapper_path: wrapperPath(f.serveDir), state: 'skipped' },
  admin_token_file: adminTokenPath(f.serveDir), engine: 'pglite',
  ...over,
});

describe('dispatch + argument shape', () => {
  test('expose is engine-free in mcpNeedsEngine', () => {
    expect(mcpNeedsEngine(['expose'])).toBe(false);
    expect(mcpNeedsEngine(['expose', '--status'])).toBe(false);
    expect(mcpNeedsEngine(['expose', '--funnel', '--yes'])).toBe(false);
    expect(mcpNeedsEngine(['grant', 'x'])).toBe(true);
  });
  test('help text carries every flag literal and names verify.local / verify.tailnet; --help exits 0 on stdout', async () => {
    for (const flag of ['--port', '--funnel', '--surface', '--enable-dcr', '--no-tailscale', '--no-service', '--no-install', '--force', '--dry-run', '--yes', '--json', '--status', '--remove']) expect(MCP_EXPOSE_HELP).toContain(flag);
    expect(MCP_EXPOSE_HELP).toContain('verify.local');
    expect(MCP_EXPOSE_HELP).toContain('verify.tailnet');
    expect(MCP_EXPOSE_HELP).not.toMatch(/service, verify, receipt/);
    const f = fakeTailnet();
    expect(await runMcpExpose(['--help'], f.deps)).toBe(0);
    expect(f.stdout.join('\n')).toContain('gbrain mcp expose --status');
  });
  test('unknown, duplicate, exclusive and malformed flags fail loud (exit 1, JSON envelope under --json)', async () => {
    expect(() => parseExposeArgs(['--bogus'])).toThrow('Unknown setup argument');
    expect(() => parseExposeArgs(['--status', '--remove'])).toThrow('Conflicting');
    expect(() => parseExposeArgs(['--funnel', '--no-tailscale'])).toThrow('Conflicting');
    expect(() => parseExposeArgs(['--dry-run', '--status'])).toThrow('Conflicting');
    expect(() => parseExposeArgs(['--port', '70000'])).toThrow('invalid --port');
    expect(() => parseExposeArgs(['--port'])).toThrow('requires a value');
    expect(() => parseExposeArgs(['--surface', 'huge'])).toThrow('invalid --surface');
    expect(() => parseExposeArgs(['--yes', '--yes'])).toThrow('Duplicate');
    expect(parseExposeArgs(['--port', '4000', '--funnel', '--surface', 'verbs'])).toMatchObject({ port: 4000, funnel: true, surface: 'verbs', enableDcr: false });
    const f = fakeTailnet();
    expect(await runMcpExpose(['--bogus', '--json'], f.deps)).toBe(1);
    expect(jsonDoc(f)).toMatchObject({ status: 'error', reason: 'invalid_arguments' });
    expect(f.stderr.join('\n')).toContain('gbrain mcp expose --help');
  });
  test('runMcp dispatches expose: --help prints MCP_EXPOSE_HELP (exit verdict untouched); --bogus --json yields invalid_arguments + verdict 1', async () => {
    const savedExitCode = process.exitCode;
    const out: string[] = [];
    const err: string[] = [];
    const outSpy = spyOn(process.stdout, 'write').mockImplementation(((chunk: unknown) => { out.push(String(chunk)); return true; }) as never);
    const errSpy = spyOn(process.stderr, 'write').mockImplementation(((chunk: unknown) => { err.push(String(chunk)); return true; }) as never);
    try {
      _resetCliExitVerdictForTests();
      await runMcp(['expose', '--help']);
      expect(out.join('')).toContain(MCP_EXPOSE_HELP);
      expect(currentExitCode()).toBe(0);
      out.length = 0;
      await runMcp(['expose', '--bogus', '--json']);
      const doc = JSON.parse(out.join('').trim());
      expect(doc).toMatchObject({ status: 'error', reason: 'invalid_arguments' });
      expect(err.join('')).toContain('gbrain mcp expose --help');
      expect(currentExitCode()).toBe(1);
    } finally {
      outSpy.mockRestore();
      errSpy.mockRestore();
      _resetCliExitVerdictForTests();
      // Bun keeps a non-zero exitCode when it is set back to undefined; the mirror
      // write from setCliExitVerdict(1) would otherwise fail this whole test run.
      process.exitCode = savedExitCode ?? 0;
    }
  });
});

describe('plan + consent', () => {
  test('--dry-run --json prints a plan, exits 0, mutates nothing and never publishes', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--dry-run', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('planned');
    expect(doc.receipt).toBeNull();
    expect(checkOf(doc, 'plan')?.status).toBe('planned');
    expect(doc.plan.join('\n')).toContain('engine pglite');
    expect(doc.plan.join('\n')).toContain('systemd user unit');
    expect(existsSync(f.serveDir)).toBe(false);
    expect(existsSync(f.deps.unitPath!)).toBe(false);
    expect(joinedCalls(f).some(c => c.includes('--bg') || c.includes('restart') || c.includes(' up'))).toBe(false);
    expect(f.fetches).toEqual([]);
    expect(f.stderr.join('\n')).toContain('Plan');
  });
  test('non-interactive without --yes → exit 2 confirmation_required and no changes', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'confirmation_required' });
    expect(doc.next_actions).toContain('gbrain mcp expose --yes');
    // The consent payload's agent fields ride the legacy document (exit 2 stays under contract v1).
    expect(doc).toMatchObject({
      code: 'confirmation_required', effects: ['persistent_install', 'egress'], actor: 'agent', contract_version: 1,
      fix: { argv: ['gbrain', 'mcp', 'expose', '--yes'], next: 'ask_user' },
    });
    expect(doc.user_message).toContain('publish your gbrain MCP server');
    expect(doc.error).toBeUndefined();
    const human = fakeTailnet();
    expect(await runMcpExpose([], human.deps)).toBe(2);
    const out = human.stdout.join('\n');
    expect(out).toContain('[AGENT]');
    expect(out).toContain('next: ask_user');
    expect(out).toContain('if_yes: gbrain mcp expose --yes');
    expect(out).not.toMatch(/re-?run[^.\n]{0,40}--yes/i);
    expect(existsSync(f.serveDir)).toBe(false);
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
  });
  test('interactive decline → status pending, exit 2, reason declined, nothing changed; interactive yes proceeds', async () => {
    const f = fakeTailnet();
    f.deps.isTTY = true;
    f.deps.prompt = async () => 'n';
    expect(await runMcpExpose(['--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'declined', message: 'Nothing changed: the confirmation was declined.', code: 'confirmation_required' });
    expect(checkOf(doc, 'consent')?.status).toBe('pending');
    expect(existsSync(f.serveDir)).toBe(false);
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
    const g = fakeTailnet();
    g.deps.isTTY = true;
    g.deps.prompt = async () => 'y';
    expect(await runMcpExpose([], g.deps)).toBe(0);
    expect(existsSync(receiptPath(g.serveDir))).toBe(true);
  });
  test('thin client → exit 1 with run-on-the-brain-host guidance', async () => {
    const f = fakeTailnet();
    f.deps.loadConfig = () => ({ engine: 'postgres', remote_mcp: { url: 'https://brain.example.com/mcp' } } as never);
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    expect(jsonDoc(f)).toMatchObject({ status: 'error', reason: 'thin_client' });
  });
});

describe('tailscale steps', () => {
  test('missing binary + --no-install → exit 1 with the install plan printed', async () => {
    const f = fakeTailnet();
    f.deps.which = (n) => (n === 'systemctl' ? '/usr/bin/systemctl' : null);
    f.deps.fileExists = () => false;
    expect(await runMcpExpose(['--yes', '--no-install', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'tailscale_missing' });
    expect(checkOf(doc, 'tailscale.binary')?.detail).toContain('curl -fsSL https://tailscale.com/install.sh | sh');
    expect(f.stderr.join('\n')).toContain('Install:');
    expect(joinedCalls(f).some(c => c.startsWith('sh -c'))).toBe(false);
  });
  test('unsupported platform without brew → exit 1 with the download URL', async () => {
    const f = fakeTailnet();
    f.deps.platform = 'darwin';
    f.deps.which = () => null;
    f.deps.fileExists = () => false;
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    expect(jsonDoc(f)).toMatchObject({ reason: 'tailscale_unsupported_platform' });
    expect(f.stderr.join('\n')).toContain('https://tailscale.com/download');
  });
  test('install path: the binary appears only after the installer argv ran → tailscale.binary says installed:, run continues', async () => {
    const f = fakeTailnet();
    let installed = false;
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => {
      if (argv[0] === 'sh' && argv[1] === '-c' && argv[2].includes('tailscale.com/install.sh')) { installed = true; f.calls.push(argv); f.recorded.push({ argv, opts: o }); return { status: 0, stdout: '', stderr: '' }; }
      return inner(argv, o);
    };
    f.deps.which = (n) => (n === 'tailscale' ? (installed ? TS : null) : n === 'systemctl' ? '/usr/bin/systemctl' : n === 'gbrain' ? '/usr/local/bin/gbrain' : null);
    f.deps.fileExists = hermeticExists(f.home, (p) => p === TS && installed);
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(checkOf(doc, 'tailscale.binary')?.detail).toContain(`installed: ${TS}`);
    const inst = f.recorded.find(r => r.argv[0] === 'sh')!;
    expect(inst.opts).toMatchObject({ inherit: true, stdoutToStderr: true });
    expect(joinedCalls(f).indexOf(`sh -c curl -fsSL https://tailscale.com/install.sh | sh`)).toBeLessThan(joinedCalls(f).indexOf(`${TS} serve --bg 3131`));
  });
  test('install path: installer exits non-zero → tailscale_install_failed, nothing published', async () => {
    const f = fakeTailnet();
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => (argv[0] === 'sh' ? { status: 1, stdout: '', stderr: 'curl: (6) Could not resolve host' } : inner(argv, o));
    f.deps.which = (n) => (n === 'systemctl' ? '/usr/bin/systemctl' : null);
    f.deps.fileExists = () => false;
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'tailscale_install_failed' });
    expect(checkOf(doc, 'tailscale.binary')?.detail).toContain('exited 1');
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
  });
  test('NeedsLogin → set --operator (non-fatal) then a FLAGLESS sudo up; still not Running → exit 2 with the re-run command', async () => {
    const f = fakeTailnet({ backendState: 'NeedsLogin', afterUp: 'NeedsLogin', setOperatorStatus: 1 });
    expect(await runMcpExpose(['--yes', '--funnel', '--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'tailscale_login_pending' });
    const calls = joinedCalls(f);
    expect(calls).toContain(`sudo ${TS} set --operator=alice-example`);
    expect(calls).toContain(`sudo ${TS} up`);
    expect(calls.indexOf(`sudo ${TS} set --operator=alice-example`)).toBeLessThan(calls.indexOf(`sudo ${TS} up`));
    expect(calls.some(c => c.includes('up --operator'))).toBe(false);
    expect(f.stderr.join('\n')).toContain('sudo tailscale set --operator=alice-example');
    expect(doc.next_actions).toContain(`sudo ${TS} up`);
    expect(doc.next_actions).toContain('gbrain mcp expose --funnel --yes');
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
  });
  test('NeedsLogin → up succeeds → continues to a full publish', async () => {
    const f = fakeTailnet({ backendState: 'NeedsLogin' });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    expect(checkOf(jsonDoc(f), 'tailscale.login')?.detail).toContain('signed in just now');
  });
  test('login runner opts: inherit, stdoutToStderr under --json, timeoutMs from GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS', async () => {
    const f = fakeTailnet({ backendState: 'NeedsLogin' });
    f.deps.env = { ...f.deps.env, GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS: '1234' };
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const up = f.recorded.find(r => r.argv[0] === 'sudo' && r.argv[2] === 'up')!;
    expect(up.opts).toEqual({ inherit: true, stdoutToStderr: true, timeoutMs: 1234 });
    const setOp = f.recorded.find(r => r.argv[0] === 'sudo' && r.argv[2] === 'set')!;
    expect(setOp.opts).toMatchObject({ inherit: true, stdoutToStderr: true });
    // non-json: stdout stays the terminal's
    const g = fakeTailnet({ backendState: 'NeedsLogin' });
    expect(await runMcpExpose(['--yes'], g.deps)).toBe(0);
    expect(g.recorded.find(r => r.argv[0] === 'sudo' && r.argv[2] === 'up')!.opts).toEqual({ inherit: true, stdoutToStderr: false, timeoutMs: 300_000 });
    // the non-interactive probes never inherit
    for (const r of g.recorded.filter(r => r.argv.includes('--json'))) expect(r.opts?.inherit).toBeUndefined();
  });
  test('daemon not running → exit 2 with the platform start hint', async () => {
    const f = fakeTailnet({ statusStdoutOverride: '', statusStderr: 'failed to connect to local Tailscale service; is Tailscale running?' });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ reason: 'tailscale_daemon_not_running' });
    expect(doc.next_actions).toContain('sudo systemctl enable --now tailscaled');
  });
  test('no MagicDNS name → exit 1 pointing at the DNS admin page', async () => {
    const f = fakeTailnet({ dnsName: null });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    expect(jsonDoc(f)).toMatchObject({ reason: 'tailscale_no_dns_name' });
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
  });
  test('pre-check: empty CertDomains → exit 2 tailscale_https_not_enabled, admin URL, and NO serve argv at all', async () => {
    const f = fakeTailnet({ certDomains: [] });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'tailscale_https_not_enabled' });
    expect(doc.message).toContain(TAILSCALE_ADMIN_DNS_URL);
    expect(doc.message).toContain('gbrain mcp expose --yes');
    expect(checkOf(doc, 'tailscale.identity')?.status).toBe('pending');
    expect(checkOf(doc, 'tailscale.publish')).toBeUndefined();
    expect(joinedCalls(f).some(c => c.includes('--bg') || c.includes('serve status'))).toBe(false);
    expect(existsSync(f.serveDir)).toBe(false);
    expect(doc.next_actions.join('\n')).toContain(TAILSCALE_ADMIN_DNS_URL);
  });
  test('pre-check: --funnel with funnelCapable=false → exit 2 tailscale_funnel_not_enabled with the ACL URL + KB link; capability absent → proceeds', async () => {
    const f = fakeTailnet({ funnelCapable: false });
    expect(await runMcpExpose(['--yes', '--funnel', '--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'tailscale_funnel_not_enabled' });
    expect(doc.message).toContain(TAILSCALE_ADMIN_ACL_URL);
    expect(doc.message).toContain(TAILSCALE_FUNNEL_KB_URL);
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
    // tailnet-only publish does not care about the funnel capability
    const g = fakeTailnet({ funnelCapable: false });
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(0);
    // capability present → funnel proceeds
    const h = fakeTailnet({ funnelCapable: true });
    expect(await runMcpExpose(['--yes', '--funnel', '--json'], h.deps)).toBe(0);
    expect(joinedCalls(h)).toContain(`${TS} funnel --bg 3131`);
    // field absent (older CLI) → proceeds and says the publish step decides
    const i = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--funnel', '--json'], i.deps)).toBe(0);
    expect(checkOf(jsonDoc(i), 'tailscale.identity')?.detail).toContain('publish step decides');
  });
  test('--funnel publishes on a Tailscale 1.102 node whose CapMap carries `funnel` + `…/cap/funnel-ports` (#5599)', async () => {
    const f = fakeTailnet({ capMap: {
      'default-auto-update': [], funnel: [], https: [],
      'https://tailscale.com/cap/funnel-ports?ports=443,8443,10000': [],
      'https://tailscale.com/cap/is-admin': [],
    } });
    expect(await runMcpExpose(['--yes', '--funnel', '--json'], f.deps)).toBe(0);
    expect(joinedCalls(f)).toContain(`${TS} funnel --bg 3131`);
  });
  test('publish failure is classified: https_not_enabled surfaces the admin URL, exit 1', async () => {
    const f = fakeTailnet({ publishStatus: 1, publishStderr: 'error: HTTPS certificates are not enabled for this tailnet; enable them in the admin console' });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc.reason).toBe('tailscale_https_not_enabled');
    expect(doc.message).toContain(TAILSCALE_ADMIN_DNS_URL);
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('https_not_enabled');
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
  });
  test('funnel_not_enabled → ACL admin URL', async () => {
    const f = fakeTailnet({ publishStatus: 1, publishStderr: 'Funnel is not enabled on your tailnet policy (node attribute funnel missing)' });
    expect(await runMcpExpose(['--yes', '--funnel', '--json'], f.deps)).toBe(1);
    expect(jsonDoc(f).message).toContain('https://login.tailscale.com/admin/acls');
  });
  test('publish timeout (status null) → tailscale_unknown with a run-it-by-hand hint', async () => {
    const f = fakeTailnet({ publishStatus: null, publishStderr: '\n(timed out after 60000ms)' });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc.reason).toBe('tailscale_unknown');
    expect(doc.message).toContain('did not finish within 60s');
    expect(doc.message).toContain('Run it by hand');
    expect(doc.next_actions).toContain('tailscale serve --bg 3131');
    const pub = f.recorded.find(r => r.argv[1] === 'serve' && r.argv[2] === '--bg')!;
    expect(pub.opts?.timeoutMs).toBe(60_000);
  });
  test('tailscale_publish_unconfirmed when --bg exits 0 but no handler appears', async () => {
    const f = fakeTailnet({ publishNoop: true });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc.reason).toBe('tailscale_publish_unconfirmed');
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('exited 0 but serve status shows no / handler');
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
  });
  test('funnel mismatch after publish → tailscale.publish warns with the off command, run still completes', async () => {
    const f = fakeTailnet({ publishedFunnel: true });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    const c = checkOf(doc, 'tailscale.publish')!;
    expect(c.status).toBe('warn');
    expect(c.detail).toContain('funnel=true (wanted false)');
    expect(f.stderr.join('\n')).toContain('tailscale funnel --https=443 --set-path=/ off');
  });
  test('a foreign :443 handler is refused without --force (next action is serve status, never --force) and taken over with it', async () => {
    const f = fakeTailnet({ existingHandlers: { 8080: false } });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc.reason).toBe('foreign_serve_config');
    expect(doc.message).toContain('tailscale serve already proxies :443 to');
    expect(doc.message).toContain('http://127.0.0.1:8080');
    expect(doc.message).toContain('--force');
    expect(doc.next_actions).toEqual(['tailscale serve status']);
    expect(doc.next_actions.join('\n')).not.toContain('--force');
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
    const g = fakeTailnet({ existingHandlers: { 8080: false } });
    expect(await runMcpExpose(['--yes', '--force', '--json'], g.deps)).toBe(0);
    expect(joinedCalls(g)).toContain(`${TS} serve --bg 3131`);
  });
  test('a foreground serve session in another terminal is refused even with --force', async () => {
    const f = fakeTailnet();
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => {
      if (argv.join(' ') === `${TS} serve status --json`) {
        f.calls.push(argv);
        return { status: 0, stdout: JSON.stringify({ Foreground: { '42': { Web: { [`${DNS}:443`]: { Handlers: { '/': { Proxy: 'http://127.0.0.1:9000' } } } } } } }), stderr: '' };
      }
      return inner(argv, o);
    };
    expect(await runMcpExpose(['--yes', '--force', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc.reason).toBe('foreign_serve_config');
    expect(doc.message).toContain('foreground');
    expect(doc.message).toContain('stop it there');
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
  });
  test('the claimed exemption: receipt for 3131 + handler for 3131, re-run with --port 4000 republishes without --force', async () => {
    const f = fakeTailnet({ existingHandlers: { 3131: false } });
    writeExposeReceipt(receiptPath(f.serveDir), fullReceipt(f));
    expect(await runMcpExpose(['--yes', '--port', '4000', '--json'], f.deps)).toBe(0);
    expect(joinedCalls(f)).toContain(`${TS} serve --bg 4000`);
    expect(readExposeReceipt(receiptPath(f.serveDir))?.port).toBe(4000);
  });
  test('switching our own handler from funnel to tailnet turns funnel off first', async () => {
    const f = fakeTailnet({ existingHandlers: { 3131: true } });
    writeExposeReceipt(receiptPath(f.serveDir), fullReceipt(f, { mode: 'funnel' }));
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const calls = joinedCalls(f);
    expect(calls.indexOf(`${TS} funnel --https=443 --set-path=/ off`)).toBeLessThan(calls.indexOf(`${TS} serve --bg 3131`));
    expect(calls.some(c => c.includes('reset'))).toBe(false);
    expect(readExposeReceipt(receiptPath(f.serveDir))?.mode).toBe('tailnet');
  });
});

describe('happy path: linux-systemd', () => {
  test('publishes, mints the token, installs the service (enable + restart), verifies, writes the receipt — no secret in any generated file', async () => {
    const f = fakeTailnet();
    mkdirSync(join(f.home, '.gbrain'), { recursive: true });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('exposed');
    for (const name of ['plan', 'consent', 'tailscale.binary', 'tailscale.login', 'tailscale.identity', 'tailscale.publish', 'admin_token', 'service', 'verify.local', 'verify.tailnet', 'receipt']) {
      expect(checkOf(doc, name)?.status).toBe('ok');
    }
    // receipt
    const receipt = readExposeReceipt(receiptPath(f.serveDir))!;
    expect(receipt).toMatchObject({
      version: 1, port: 3131, public_url: `https://${DNS}`, mcp_url: `https://${DNS}/mcp`, admin_url: `https://${DNS}/admin`, mode: 'tailnet', surface: 'full', enable_dcr: false,
      tailscale: { binary: TS, dns_name: DNS, tailscale_version: '1.80.0' },
      service: { target: 'linux-systemd', unit_path: f.deps.unitPath, plist_path: null, wrapper_path: wrapperPath(f.serveDir), state: 'running' },
      admin_token_file: adminTokenPath(f.serveDir), engine: 'pglite',
    });
    expect(receipt.created_at).toBe('2026-06-01T12:00:00.000Z');
    expect(doc.receipt).toEqual(receipt);
    // permissions
    expect(statSync(receiptPath(f.serveDir)).mode & 0o777).toBe(0o600);
    expect(statSync(adminTokenPath(f.serveDir)).mode & 0o777).toBe(0o600);
    expect(statSync(wrapperPath(f.serveDir)).mode & 0o777).toBe(0o755);
    expect(readFileSync(adminTokenPath(f.serveDir), 'utf-8').trim()).toBe(TOKEN);
    // no token literal anywhere except the token file; nothing printed either
    const files = { ...readAll(f.serveDir), ...readAll(join(f.home, '.config')) };
    for (const [path, content] of Object.entries(files)) if (path !== adminTokenPath(f.serveDir)) expect(content).not.toContain(TOKEN);
    expect(f.stdout.join('\n')).not.toContain(TOKEN);
    expect(f.stderr.join('\n')).not.toContain(TOKEN);
    // wrapper + unit shape
    const wrapper = readFileSync(wrapperPath(f.serveDir), 'utf-8');
    expect(wrapper).toContain(`GBRAIN_ADMIN_BOOTSTRAP_TOKEN="$(cat '${adminTokenPath(f.serveDir)}')"`);
    expect(wrapper).toContain(`serve --http --port 3131 --public-url https://${DNS} --surface full --advertise verbs`);
    expect(receipt.advertise).toBe('verbs');
    expect(wrapper).not.toContain('export GBRAIN_HOME');
    expect(readFileSync(f.deps.unitPath!, 'utf-8')).toContain(`ExecStart=${wrapperPath(f.serveDir)}`);
    // exec ledger: enable + restart (a reinstall relaunches the regenerated wrapper), never enable --now
    const calls = joinedCalls(f);
    expect(calls).toContain(`${TS} serve --bg 3131`);
    expect(calls).toContain('systemctl --user daemon-reload');
    expect(calls).toContain('systemctl --user enable gbrain-serve.service');
    expect(calls).toContain('systemctl --user restart gbrain-serve.service');
    expect(calls.indexOf('systemctl --user enable gbrain-serve.service')).toBeLessThan(calls.indexOf('systemctl --user restart gbrain-serve.service'));
    expect(calls.some(c => c.includes('--now'))).toBe(false);
    expect(calls).toContain('loginctl enable-linger');
    expect(calls.some(c => c.includes('funnel'))).toBe(false);
    expect(f.fetches).toContain('http://127.0.0.1:3131/health');
    expect(f.fetches).toContain(`https://${DNS}/health`);
    // human summary on stderr (json mode)
    const prose = f.stderr.join('\n');
    expect(prose).toContain('GBrain MCP server published on your tailnet');
    expect(prose).toContain(`MCP URL   https://${DNS}/mcp`);
    expect(prose).toContain('PGLite (single-writer)');
    expect(prose).toContain('fail with `live_serve`');
    expect(prose).not.toContain('wait on this server');
    expect(prose).toContain('gbrain mcp expose --status');
    expect(prose).toContain('owner session required');
    expect(prose).toContain('Native OAuth');
    expect(prose).toContain('Machine install');
    expect(doc.next_actions).toContain(`gbrain mcp admin login-link --url https://${DNS}/mcp --admin-token-file ${adminTokenPath(f.serveDir)}`);
    expect(doc.next_actions).toContain('gbrain mcp admin register --help');
    expect(doc.next_actions.join('\n')).toContain(`--url https://${DNS}/mcp`);
  });
  test('PGLite banner: local agents get the pre-mint + --token guidance and the scoped grant path, never a bare bootstrap harness', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    const prose = f.stderr.join('\n');
    expect(prose).toContain('gbrain auth create local-agents --scopes read,write');
    expect(prose).toContain('gbrain bootstrap harness --yes --port 3131 --token <value>');
    expect(prose).toContain(`gbrain mcp grant local-agents --harness <id> --profile memory-writer --source default --url http://127.0.0.1:3131/mcp --admin-token-file`);
    expect(prose).toContain('gbrain connect http://127.0.0.1:3131/mcp --harness <id> --credentials-file /private/local-agents.json --install');
    const actions: string[] = doc.next_actions;
    expect(actions.some(a => a.startsWith('gbrain bootstrap harness --yes --port 3131 --token'))).toBe(true);
    expect(actions).not.toContain('gbrain bootstrap harness --yes --port 3131');
    expect(actions.some(a => a.includes('--url http://127.0.0.1:3131/mcp --admin-token-file'))).toBe(true);
  });
  test('Postgres banner: plain bootstrap harness, no pre-mint talk', async () => {
    const f = fakeTailnet();
    f.deps.loadConfig = () => ({ engine: 'postgres', database_url: 'postgres://alice-example@localhost/brain' } as never);
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.receipt.engine).toBe('postgres');
    const prose = f.stderr.join('\n');
    expect(prose).toContain('Local agents     gbrain bootstrap harness --yes --port 3131');
    expect(prose).not.toContain('auth create');
    expect(prose).not.toContain('--token <value>');
    expect(prose).toContain('Engine    Postgres');
    expect(doc.next_actions).toContain('gbrain bootstrap harness --yes --port 3131');
  });
  test('--funnel publishes via funnel, bakes GBRAIN_HOME + surface + DCR, and the summary says public', async () => {
    const f = fakeTailnet();
    f.deps.env = { ...f.deps.env, GBRAIN_HOME: join(f.home, 'custom') };
    expect(await runMcpExpose(['--yes', '--funnel', '--port', '4000', '--surface', 'verbs', '--enable-dcr'], f.deps)).toBe(0);
    expect(joinedCalls(f)).toContain(`${TS} funnel --bg 4000`);
    const receipt = readExposeReceipt(receiptPath(f.serveDir))!;
    expect(receipt).toMatchObject({ mode: 'funnel', port: 4000, surface: 'verbs', enable_dcr: true });
    expect(receipt.advertise).toBeUndefined();
    const wrapper = readFileSync(wrapperPath(f.serveDir), 'utf-8');
    expect(wrapper).toContain(`export GBRAIN_HOME='${join(f.home, 'custom')}'`);
    expect(wrapper).toContain('--port 4000 --public-url https://your-machine.your-tailnet.ts.net --surface verbs --enable-dcr');
    expect(f.stdout.join('\n')).toContain('public (Funnel)');
    expect(f.stdout.join('\n')).toContain('bootstrap harness --yes --port 4000');
  });
  test('tailnet health pending → exit 2, status pending, receipt still written', async () => {
    const f = fakeTailnet({ tailnetHealthy: false });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'tailnet_health_pending' });
    expect(checkOf(doc, 'verify.tailnet')?.status).toBe('pending');
    expect(existsSync(receiptPath(f.serveDir))).toBe(true);
    expect(f.stderr.join('\n')).toContain('re-run `gbrain mcp expose --status` in a minute');
  });
  test('local health timeout → exit 2 local_health_timeout, verify.local warn, verify.tailnet skipped', async () => {
    const f = fakeTailnet({ localHealthyAfterStart: false });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'local_health_timeout' });
    expect(checkOf(doc, 'verify.local')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'verify.local')?.detail).toContain('timeout');
    expect(checkOf(doc, 'verify.tailnet')).toMatchObject({ status: 'skipped', detail: 'local server not confirmed yet' });
    expect(f.fetches.some(u => u.startsWith('https://'))).toBe(false);
    expect(f.stderr.join('\n')).toContain('did not answer within');
    expect(existsSync(receiptPath(f.serveDir))).toBe(true);
  });
  test('re-running with an existing receipt keeps created_at and is not a foreign listener', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const first = readExposeReceipt(receiptPath(f.serveDir))!;
    f.deps.now = () => new Date('2026-06-02T00:00:00.000Z');
    f.stdout.length = 0;
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const second = readExposeReceipt(receiptPath(f.serveDir))!;
    expect(second.created_at).toBe(first.created_at);
    expect(second.updated_at).toBe('2026-06-02T00:00:00.000Z');
    expect(checkOf(jsonDoc(f), 'admin_token')?.detail).toContain('reused');
  });

  test('an exposure from before the verbs listing default keeps listing everything when re-run; --surface full lists everything', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const { advertise: _dropped, ...older } = readExposeReceipt(receiptPath(f.serveDir))!;
    writeExposeReceipt(receiptPath(f.serveDir), older);
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    expect(readExposeReceipt(receiptPath(f.serveDir))!.advertise).toBeUndefined();
    expect(readFileSync(wrapperPath(f.serveDir), 'utf-8')).not.toContain('--advertise');

    const g = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--surface', 'full'], g.deps)).toBe(0);
    expect(readExposeReceipt(receiptPath(g.serveDir))!.advertise).toBeUndefined();
    expect(readFileSync(wrapperPath(g.serveDir), 'utf-8')).toContain(`--public-url https://${DNS} --surface full\n`);
  });
});

describe('hosted_option', () => {
  const hostedOf = (doc: { notices?: { code: string; user_message?: string }[] }) => doc.notices?.find(n => n.code === 'hosted_option');
  test('the run that writes the first receipt carries it; consent-pending, --dry-run, re-publish, --status and --remove do not', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--dry-run', '--json'], f.deps)).toBe(0);
    expect(hostedOf(jsonDoc(f))).toBeUndefined();
    f.stdout.length = 0;
    expect(await runMcpExpose(['--json'], f.deps)).toBe(2);
    const pending = jsonDoc(f);
    expect(pending.reason).toBe('confirmation_required');
    expect(hostedOf(pending)).toBeUndefined();
    expect(pending.user_message).not.toContain('gbrain.io');
    f.stdout.length = 0;
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const first = jsonDoc(f);
    expect(first.status).toBe('exposed');
    expect(hostedOf(first)).toMatchObject({ kind: 'coaching', contract_version: 1 });
    expect(hostedOf(first)?.user_message).toContain('https://gbrain.io/?ref=cli-mcp-expose');
    for (const args of [['--yes', '--json'], ['--status', '--json'], ['--remove', '--yes', '--json']]) {
      f.stdout.length = 0;
      await runMcpExpose(args, f.deps);
      expect(hostedOf(jsonDoc(f))).toBeUndefined();
    }
  });
  test('friction exits carry it every time; human output prints the one line', async () => {
    const f = fakeTailnet();
    f.deps.which = (n) => (n === 'systemctl' ? '/usr/bin/systemctl' : null);
    f.deps.fileExists = () => false;
    expect(await runMcpExpose(['--yes', '--no-install', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc.reason).toBe('tailscale_missing');
    expect(hostedOf(doc)?.user_message).toContain('?ref=cli-mcp-expose-friction');
    const login = fakeTailnet({ backendState: 'NeedsLogin', afterUp: 'NeedsLogin' });
    expect(await runMcpExpose(['--yes'], login.deps)).toBe(2);
    expect(login.stdout.join('\n')).toContain('Hosted option: gbrain.io runs GBrain for you, nothing to keep online: https://gbrain.io/?ref=cli-mcp-expose-friction  (hide: gbrain notices mute hosted_option)');
  });
  test('a muted owner sees nothing', async () => {
    const f = fakeTailnet();
    f.deps.mutedNotices = () => new Set(['hosted_option']);
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    expect(jsonDoc(f).notices).toBeUndefined();
  });
});

describe('happy path: darwin (launchd, app-bundle CLI)', () => {
  test('login pending → "Open the Tailscale app" guidance, plain `<app> up`, no sudo', async () => {
    const f = fakeMac({ backendState: 'NeedsLogin', afterUp: 'NeedsLogin' });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'tailscale_login_pending' });
    expect(doc.message).toContain('Open the Tailscale app and sign in');
    expect(doc.next_actions).toContain('Open the Tailscale app and sign in');
    expect(joinedCalls(f)).toContain(`${APP_TS} up`);
    expect(joinedCalls(f).some(c => c.startsWith('sudo'))).toBe(false);
    expect(checkOf(doc, 'tailscale.binary')?.detail).toBe(APP_TS);
  });
  test('launchd happy path: plist written 0644, bootout gui/<uid> then bootstrap gui/<uid>, state running, receipt target macos', async () => {
    const f = fakeMac();
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('exposed');
    expect(doc.receipt.service).toMatchObject({ target: 'macos', plist_path: f.deps.plistPath, unit_path: null, state: 'running' });
    expect(existsSync(f.deps.plistPath!)).toBe(true);
    expect(statSync(f.deps.plistPath!).mode & 0o777).toBe(0o644);
    expect(readFileSync(f.deps.plistPath!, 'utf-8')).toContain(`<string>${wrapperPath(f.serveDir)}</string>`);
    const calls = joinedCalls(f);
    expect(calls.indexOf(`launchctl bootout gui/501 ${f.deps.plistPath}`)).toBeGreaterThanOrEqual(0);
    expect(calls.indexOf(`launchctl bootout gui/501 ${f.deps.plistPath}`)).toBeLessThan(calls.indexOf(`launchctl bootstrap gui/501 ${f.deps.plistPath}`));
    expect(calls.some(c => c.startsWith('launchctl load') || c.startsWith('launchctl unload'))).toBe(false);
    expect(calls).toContain('launchctl print gui/501/com.gbrain.serve');
    expect(calls.some(c => c.startsWith('systemctl'))).toBe(false);
    expect(f.stderr.join('\n')).toContain('launchd com.gbrain.serve, running');
  });
  test('brew install path: after the cask, `open -a Tailscale` runs (non-fatal) and the run sleeps before the first status read', async () => {
    const f = fakeMac();
    let installed = false;
    const slept: number[] = [];
    f.deps.sleep = async (ms) => { slept.push(ms); };
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => {
      if (argv[0] === 'brew') { installed = true; f.calls.push(argv); f.recorded.push({ argv, opts: o }); return { status: 0, stdout: '', stderr: '' }; }
      if (argv[0] === 'open') { f.calls.push(argv); return { status: 1, stdout: '', stderr: 'LSOpenURLsWithRole() failed' }; }
      return inner(argv, o);
    };
    f.deps.fileExists = hermeticExists(f.home, (p) => p === APP_TS && installed);
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const calls = joinedCalls(f);
    const brewAt = calls.indexOf('brew install --cask tailscale-app');
    const openAt = calls.indexOf('open -a Tailscale');
    const statusAt = calls.indexOf(`${APP_TS} status --json`);
    expect(brewAt).toBeGreaterThanOrEqual(0);
    expect(openAt).toBeGreaterThan(brewAt);
    expect(statusAt).toBeGreaterThan(openAt);
    expect(slept.some(ms => ms >= 1000)).toBe(true);
    expect(checkOf(jsonDoc(f), 'tailscale.binary')?.detail).toContain(`installed: ${APP_TS}`);
  });
  test('after `open -a Tailscale` the run polls `status --json` at 1s: ready on the second poll → two poll reads then proceeds; never ready → 20 polls, then daemon-not-running pending', async () => {
    const DOWN = { status: 1, stdout: '', stderr: 'failed to connect to local Tailscale service; is Tailscale running?' };
    const brewMac = (readyAfterFailures: number) => {
      const f = fakeMac();
      let installed = false;
      let statusReads = 0;
      const slept: number[] = [];
      f.deps.sleep = async (ms) => { slept.push(ms); };
      const inner = f.deps.run!;
      f.deps.run = async (argv, o) => {
        if (argv[0] === 'brew') { installed = true; return { status: 0, stdout: '', stderr: '' }; }
        if (argv.join(' ') === `${APP_TS} status --json`) { statusReads++; f.calls.push(argv); if (statusReads <= readyAfterFailures) return DOWN; }
        return inner(argv, o);
      };
      f.deps.fileExists = hermeticExists(f.home, (p) => p === APP_TS && installed);
      return { f, slept, reads: () => statusReads };
    };
    // fast-ready: the first poll finds the daemon down, the second finds it up → the login step's own read is the third and the run proceeds
    const fast = brewMac(1);
    expect(await runMcpExpose(['--yes', '--json'], fast.f.deps)).toBe(0);
    expect(fast.slept).toEqual([1000, 1000]);
    expect(fast.reads()).toBe(3);
    expect(checkOf(jsonDoc(fast.f), 'tailscale.login')?.detail).toBe('Running');
    // exhausted: 20 polls at 1s, then the login step reports the daemon as not running
    const slow = brewMac(Number.POSITIVE_INFINITY);
    expect(await runMcpExpose(['--yes', '--json'], slow.f.deps)).toBe(2);
    expect(slow.slept).toEqual(Array(20).fill(1000));
    expect(slow.reads()).toBe(21);
    const doc = jsonDoc(slow.f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'tailscale_daemon_not_running' });
    expect(doc.next_actions).toContain('open -a Tailscale');
    expect(joinedCalls(slow.f).some(c => c.includes('--bg'))).toBe(false);
  });
});

describe('service edge cases', () => {
  test('a foreign listener on the port is refused BEFORE any serve --bg; --no-service publishes only', async () => {
    const f = fakeTailnet({ localListeningBefore: true });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc.reason).toBe('foreign_listener');
    expect(doc.message).toContain('Something already answers on 127.0.0.1:3131');
    expect(doc.message).toContain('If this is a gbrain server left behind by an interrupted `gbrain mcp expose`, run `gbrain mcp expose --remove --yes` first.');
    expect(doc.next_actions).toContain('gbrain mcp expose --yes --no-service');
    expect(doc.next_actions).toContain('gbrain mcp expose --remove --yes');
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
    expect(joinedCalls(f).some(c => c.includes('serve status'))).toBe(false);
    expect(checkOf(doc, 'tailscale.publish')).toBeUndefined();
    expect(existsSync(wrapperPath(f.serveDir))).toBe(false);
    expect(existsSync(f.deps.unitPath!)).toBe(false);
    expect(existsSync(adminTokenPath(f.serveDir))).toBe(false);
    const g = fakeTailnet({ localListeningBefore: true });
    expect(await runMcpExpose(['--yes', '--no-service', '--json'], g.deps)).toBe(0);
    const gdoc = jsonDoc(g);
    expect(checkOf(gdoc, 'service')?.status).toBe('skipped');
    expect(checkOf(gdoc, 'verify.local')?.status).toBe('ok');
    expect(readExposeReceipt(receiptPath(g.serveDir))?.service.state).toBe('skipped');
    expect(joinedCalls(g).some(c => c.startsWith('systemctl --user enable') || c.startsWith('systemctl --user restart'))).toBe(false);
  });
  test('a listener on a DIFFERENT port than the receipt is foreign; the receipt port itself is ours', async () => {
    const f = fakeTailnet({ localListeningBefore: true });
    writeExposeReceipt(receiptPath(f.serveDir), fullReceipt(f));
    expect(await runMcpExpose(['--yes', '--port', '4000', '--json'], f.deps)).toBe(1);
    expect(jsonDoc(f).reason).toBe('foreign_listener');
    const g = fakeTailnet({ localListeningBefore: true });
    writeExposeReceipt(receiptPath(g.serveDir), fullReceipt(g));
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(0);
  });
  test('--no-service with nothing listening skips the local wait and says so', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--no-service', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(checkOf(doc, 'verify.local')?.status).toBe('skipped');
    expect(checkOf(doc, 'verify.tailnet')?.status).toBe('skipped');
    expect(f.stderr.join('\n')).toContain('Nothing listens on 127.0.0.1:3131 yet');
    expect(f.stderr.join('\n')).toContain('--no-service does not change it');
    expect(doc.next_actions).toContain(`gbrain mcp admin login-link --url https://${DNS}/mcp --admin-token-file <existing-server-admin-token-file>`);
    expect(doc.next_actions.filter((action: string) => action.includes('--admin-token-file')).every((action: string) => action.includes('<existing-server-admin-token-file>'))).toBe(true);
  });
  test('--no-service re-run after a full install keeps the service block and does not rewrite the wrapper', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const before = readExposeReceipt(receiptPath(f.serveDir))!;
    expect(before.service.state).toBe('running');
    writeFileSync(wrapperPath(f.serveDir), '#!/bin/bash\n# sentinel: hand-edited\nexit 0\n');
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--yes', '--no-service', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    const after = readExposeReceipt(receiptPath(f.serveDir))!;
    expect(after.service).toEqual(before.service);
    expect(readFileSync(wrapperPath(f.serveDir), 'utf-8')).toContain('sentinel: hand-edited');
    expect(checkOf(doc, 'service')?.detail).toContain('kept as is');
    expect(checkOf(doc, 'verify.local')?.status).toBe('ok');
    expect(joinedCalls(f).some(c => c.startsWith('systemctl --user enable') || c.startsWith('systemctl --user restart') || c.startsWith('systemctl --user daemon-reload'))).toBe(false);
    expect(f.stderr.join('\n')).toContain('(kept, --no-service)');
  });
  test('no user bus (cloud sandbox) → manual service: wrapper written, foreground + nohup lines, exit 0', async () => {
    const f = fakeTailnet();
    f.deps.executionEnv = 'cloud-sandbox';
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(checkOf(doc, 'service')?.detail).toContain('manual');
    expect(checkOf(doc, 'verify.local')?.status).toBe('skipped');
    expect(existsSync(wrapperPath(f.serveDir))).toBe(true);
    expect(existsSync(f.deps.unitPath!)).toBe(false);
    expect(f.stderr.join('\n')).toContain('nohup');
    expect(doc.receipt.service).toMatchObject({ target: 'none', state: 'manual' });
    expect(joinedCalls(f).some(c => c.startsWith('systemctl'))).toBe(false);
  });
  test('--no-tailscale skips every tailscale step and keeps the server on loopback', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--no-tailscale', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    for (const name of ['tailscale.binary', 'tailscale.login', 'tailscale.identity', 'tailscale.publish']) expect(checkOf(doc, name)?.status).toBe('skipped');
    expect(doc.receipt.public_url).toBe('http://127.0.0.1:3131');
    expect(joinedCalls(f).some(c => c.startsWith(TS))).toBe(false);
  });
  test('service install failure → exit 1 service_install_failed, but a receipt (service stopped) is kept so --status/--remove can clean up', async () => {
    const f = fakeTailnet();
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => (argv.join(' ').startsWith('systemctl --user restart') ? { status: 1, stdout: '', stderr: 'Job for gbrain-serve.service failed' } : inner(argv, o));
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'service_install_failed' });
    const receipt = readExposeReceipt(receiptPath(f.serveDir))!;
    expect(receipt.service).toMatchObject({ target: 'linux-systemd', state: 'stopped', unit_path: f.deps.unitPath });
    expect(receipt.port).toBe(3131);
    expect(doc.receipt).toEqual(receipt);
    expect(doc.next_actions).toContain('gbrain mcp expose --remove --yes');
    // --remove sees it and clears the published handler
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    expect(joinedCalls(f)).toContain(`${TS} serve --https=443 --set-path=/ off`);
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
  });
  test('a symlinked token path is refused → structured error, nothing published', async () => {
    const f = fakeTailnet();
    mkdirSync(f.serveDir, { recursive: true });
    const victim = join(f.home, 'victim');
    writeFileSync(victim, 'keep\n');
    symlinkSync(victim, adminTokenPath(f.serveDir));
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'mcp_expose_failed' });
    expect(doc.message).toContain('symlink');
    expect(readFileSync(victim, 'utf-8')).toBe('keep\n');
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
  });
});

describe('--status', () => {
  test('without a receipt: human exit 0, --json exit 2 not_exposed', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--status'], f.deps)).toBe(0);
    expect(f.stdout.join('\n')).toContain('not exposed');
    const g = fakeTailnet();
    expect(await runMcpExpose(['--status', '--json'], g.deps)).toBe(2);
    expect(jsonDoc(g)).toMatchObject({ status: 'not_exposed', reason: 'not_exposed' });
  });
  test('after a publish: everything verifies → exit 0; a vanished handler → exit 1', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('exposed');
    for (const name of ['receipt', 'tailscale.publish', 'service', 'verify.local', 'verify.tailnet']) expect(checkOf(doc, name)?.status).toBe('ok');
    // knock the handler out from under us
    await f.run([TS, 'serve', '--https=443', '--set-path=/', 'off']);
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(1);
    const bad = jsonDoc(f);
    expect(bad.status).toBe('error');
    expect(checkOf(bad, 'tailscale.publish')?.status).toBe('fail');
    expect(bad.next_actions).toContain('gbrain mcp expose --yes');
  });
  test('a stopped service → service check fails, exit 1', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    f.stopService();
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'status_unhealthy' });
    expect(checkOf(doc, 'service')).toMatchObject({ status: 'fail' });
    expect(checkOf(doc, 'service')?.detail).toContain('stopped');
    expect(checkOf(doc, 'tailscale.publish')?.status).toBe('ok');
  });
  test('tailnet certificate still pending → status pending, exit 1 (only a full verify exits 0)', async () => {
    const f = fakeTailnet({ tailnetHealthy: false });
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(2);
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'tailnet_health_pending' });
    expect(checkOf(doc, 'verify.tailnet')?.status).toBe('pending');
    expect(checkOf(doc, 'verify.local')?.status).toBe('ok');
  });
});

describe('--remove', () => {
  test('stops the service, turns off ONLY our handler (funnel first), deletes wrapper + receipt, keeps token + Tailscale', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--funnel'], f.deps)).toBe(0);
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--json'], f.deps)).toBe(2); // consent needed
    expect(jsonDoc(f)).toMatchObject({ status: 'pending', reason: 'confirmation_required' });
    expect(existsSync(receiptPath(f.serveDir))).toBe(true);
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('removed');
    const calls = joinedCalls(f);
    expect(calls).toContain('systemctl --user disable --now gbrain-serve.service');
    expect(calls).toContain(`${TS} funnel --https=443 --set-path=/ off`);
    expect(calls.some(c => /reset|logout|uninstall|down/.test(c))).toBe(false);
    expect(calls.some(c => c.startsWith('sh -c') || c.startsWith('sudo'))).toBe(false);
    expect(existsSync(wrapperPath(f.serveDir))).toBe(false);
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
    expect(existsSync(f.deps.unitPath!)).toBe(false);
    expect(existsSync(adminTokenPath(f.serveDir))).toBe(true);
    expect(f.stderr.join('\n')).toContain('Tailscale itself (installed and signed in)');
    expect(f.stderr.join('\n')).toContain('admin token');
  });
  test('tailnet-mode --remove turns off with `serve --https=443 --set-path=/ off` (no funnel off)', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const calls = joinedCalls(f);
    expect(calls).toContain(`${TS} serve --https=443 --set-path=/ off`);
    expect(calls.some(c => c.includes('funnel'))).toBe(false);
    expect(checkOf(jsonDoc(f), 'tailscale.publish')?.detail).toContain('serve off: exit 0');
  });
  test('--remove with a FOREIGN port on :443 issues no `--https=443 --set-path=/ off` and reports nothing to turn off', async () => {
    const f = fakeTailnet({ existingHandlers: { 8080: false } });
    writeExposeReceipt(receiptPath(f.serveDir), {
      version: 1, created_at: 'x', updated_at: 'x', port: 3131, public_url: `https://${DNS}`, mcp_url: `https://${DNS}/mcp`, admin_url: `https://${DNS}/admin`,
      mode: 'tailnet', surface: 'full', enable_dcr: false, tailscale: { binary: TS, dns_name: DNS, tailscale_version: '1.80.0' },
      service: { target: 'linux-systemd', unit_path: null, plist_path: null, wrapper_path: wrapperPath(f.serveDir), state: 'skipped' },
      admin_token_file: adminTokenPath(f.serveDir), engine: 'pglite',
    });
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('removed');
    expect(joinedCalls(f).some(c => c.includes('--https=443 --set-path=/ off'))).toBe(false);
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('nothing to turn off');
    // the foreign handler is untouched
    const view = await f.run([TS, 'serve', 'status', '--json']);
    expect(view.stdout).toContain('http://127.0.0.1:8080');
  });
  test('interactive decline on --remove → status pending, exit 2, reason declined, receipt untouched', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    f.calls.length = 0;
    f.stdout.length = 0;
    f.deps.isTTY = true;
    f.deps.prompt = async () => 'no';
    expect(await runMcpExpose(['--remove', '--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'declined', message: 'Nothing changed: the confirmation was declined.', code: 'confirmation_required' });
    expect(checkOf(doc, 'consent')?.status).toBe('pending');
    expect(existsSync(receiptPath(f.serveDir))).toBe(true);
    expect(joinedCalls(f).some(c => c.includes('disable') || c.includes('off'))).toBe(false);
  });
  test('--remove --force also deletes the token; a second --remove is a no-op exit 0', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    expect(await runMcpExpose(['--remove', '--yes', '--force'], f.deps)).toBe(0);
    expect(existsSync(adminTokenPath(f.serveDir))).toBe(false);
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    expect(jsonDoc(f)).toMatchObject({ status: 'not_exposed' });
  });
  test('--remove on a manual (no supervisor) receipt names the leftover process and touches no systemctl', async () => {
    const f = fakeTailnet();
    f.deps.executionEnv = 'cloud-sandbox';
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    f.calls.length = 0;
    expect(await runMcpExpose(['--remove', '--yes'], f.deps)).toBe(0);
    expect(joinedCalls(f).some(c => c.startsWith('systemctl'))).toBe(false);
    expect(f.stdout.join('\n')).toContain('manually started server process');
    // the plan says what the step then does: nothing to stop through a supervisor, the wrapper file goes
    expect(f.stdout.join('\n')).toContain('Service   manual — nothing to stop here (stop the wrapper process yourself); the wrapper file is deleted below');
    expect(f.stdout.join('\n')).not.toContain('stop + remove');
  });
  test('--remove after a --no-service publish (target none, state skipped) → service "none installed", no manual-process note', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--no-service', '--json'], f.deps)).toBe(0);
    expect(jsonDoc(f).receipt.service).toMatchObject({ target: 'none', state: 'skipped' });
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(checkOf(doc, 'plan')?.detail).toContain('Service   none installed');
    expect(checkOf(doc, 'service')).toMatchObject({ status: 'skipped', detail: 'none installed' });
    expect(f.stderr.join('\n')).not.toContain('manually started server process');
  });
  test('--remove removes a service that exists even when the receipt says skipped (defensive probe)', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    // Rewrite the receipt as if the last run had been --no-service on an older build that dropped the block.
    const receipt = readExposeReceipt(receiptPath(f.serveDir))!;
    writeExposeReceipt(receiptPath(f.serveDir), { ...receipt, service: { ...receipt.service, unit_path: null, state: 'skipped' } });
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(joinedCalls(f)).toContain('systemctl --user disable --now gbrain-serve.service');
    expect(existsSync(f.deps.unitPath!)).toBe(false);
    expect(checkOf(doc, 'service')?.status).toBe('ok');
    expect(f.stderr.join('\n')).toContain('receipt says no service was installed');
  });
});

describe('never a stack trace', () => {
  test('an exploding dependency becomes a structured error, exit 1', async () => {
    const f = fakeTailnet();
    f.deps.run = async () => { throw new Error('spawn exploded'); };
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'mcp_expose_failed' });
    expect(doc.message).toContain('spawn exploded');
  });
  test('a broken existing receipt is treated as absent (unreadable JSON never crashes --status)', async () => {
    const f = fakeTailnet();
    mkdirSync(f.serveDir, { recursive: true });
    writeFileSync(receiptPath(f.serveDir), '{not json');
    expect(await runMcpExpose(['--status'], f.deps)).toBe(0);
    expect(f.stdout.join('\n')).toContain('not exposed');
  });
});

describe('engine detection + summary variants', () => {
  test('no brain config (null or a throwing loadConfig) → refused as no_brain_config before consent (a service would crash-loop); --no-service still publishes with engine unknown; bare engine hints resolve', async () => {
    for (const cfg of [() => null, () => { throw new Error('config unreadable'); }, () => ({})]) {
      const f = fakeTailnet();
      f.deps.loadConfig = cfg as never;
      expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
      const doc = jsonDoc(f);
      expect(doc).toMatchObject({ status: 'error', reason: 'no_brain_config' });
      expect(doc.message).toBe('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.');
      expect(checkOf(doc, 'plan')).toMatchObject({ status: 'fail' });
      expect(checkOf(doc, 'plan')?.detail).toContain('REFUSED: no brain is configured on this host');
      expect(checkOf(doc, 'consent')).toBeUndefined();
      expect(doc.next_actions).toContain('gbrain init');
      expect(doc.next_actions).toContain('gbrain mcp expose --yes --no-service');
      expect(joinedCalls(f).some(c => c.includes('--bg') || c.startsWith('systemctl --user enable'))).toBe(false);
      expect(f.fetches).toEqual([]);
      expect(existsSync(f.serveDir)).toBe(false);
    }
    // --no-service: the operator runs the server themselves → allowed, engine recorded as unknown with the init hint
    const g = fakeTailnet();
    g.deps.loadConfig = () => null;
    expect(await runMcpExpose(['--yes', '--no-service', '--json'], g.deps)).toBe(0);
    const gdoc = jsonDoc(g);
    expect(gdoc.receipt.engine).toBe('unknown');
    expect(checkOf(gdoc, 'plan')?.status).toBe('ok');
    expect(g.stderr.join('\n')).toContain('unknown (no brain config found');
    expect(gdoc.next_actions).toContain('gbrain bootstrap harness --yes --port 3131');
    expect(g.stderr.join('\n')).not.toContain('auth create');
    // --dry-run still prints the plan (with the refusal marked) and exits 0
    const h = fakeTailnet();
    h.deps.loadConfig = () => null;
    expect(await runMcpExpose(['--dry-run', '--json'], h.deps)).toBe(0);
    const hdoc = jsonDoc(h);
    expect(hdoc.status).toBe('planned');
    expect(checkOf(hdoc, 'plan')?.status).toBe('planned');
    expect(hdoc.plan.join('\n')).toContain('engine unknown');
    expect(hdoc.plan.join('\n')).toContain('WOULD BE REFUSED: no brain is configured on this host');
    const planOf = async (cfg: () => unknown, extra: string[] = []) => {
      const i = fakeTailnet();
      i.deps.loadConfig = cfg as never;
      expect(await runMcpExpose(['--dry-run', '--json', ...extra], i.deps)).toBe(0);
      return jsonDoc(i).plan.join('\n') as string;
    };
    expect(await planOf(() => { throw new Error('config unreadable'); })).toContain('engine unknown');
    expect(await planOf(() => ({ engine: 'postgres' }))).toContain('engine postgres');
    expect(await planOf(() => ({ engine: 'postgres' }))).not.toContain('REFUSED');
    expect(await planOf(() => ({ engine: 'pglite' }))).toContain('engine pglite');
    expect(await planOf(() => ({}))).toContain('engine unknown');
    expect(await planOf(() => null, ['--no-service'])).not.toContain('REFUSED');
  });
  test('the re-run hint re-renders every non-default publish flag (never --yes/--json); a non-JSON argument error goes to stderr only', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--port', '4000', '--surface', 'verbs', '--enable-dcr', '--no-install', '--no-service', '--json'], f.deps)).toBe(2);
    expect(jsonDoc(f).next_actions).toContain('gbrain mcp expose --port 4000 --surface verbs --enable-dcr --no-service --no-install --yes');
    const g = fakeTailnet();
    expect(await runMcpExpose(['--no-tailscale', '--json'], g.deps)).toBe(2);
    expect(jsonDoc(g).next_actions).toContain('gbrain mcp expose --no-tailscale --yes');
    const h = fakeTailnet();
    expect(await runMcpExpose(['--dry-run', '--remove'], h.deps)).toBe(1);
    expect(h.stdout).toEqual([]);
    expect(h.stderr.join('\n')).toContain('Conflicting setup arguments: --dry-run and --remove');
    expect(h.stderr.join('\n')).toContain('gbrain mcp expose --help');
  });
});

describe('service target + state edges', () => {
  test('no systemctl on PATH → manual target without probing; a dead user bus → manual too (probe bounded to 3s); a service that is not running after install → warn', async () => {
    const f = fakeTailnet();
    f.deps.which = (n) => (n === 'tailscale' ? TS : n === 'gbrain' ? '/usr/local/bin/gbrain' : null);
    expect(await runMcpExpose(['--dry-run', '--json'], f.deps)).toBe(0);
    expect(jsonDoc(f).plan.join('\n')).toContain('Service   manual — no user supervisor in this environment (no user bus)');
    expect(joinedCalls(f).some(c => c.startsWith('systemctl'))).toBe(false);
    const g = fakeTailnet({ userBusStatus: 1 });
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(0);
    const gdoc = jsonDoc(g);
    expect(joinedCalls(g)).toContain('systemctl --user is-system-running');
    expect(g.recorded.find(r => r.argv.join(' ') === 'systemctl --user is-system-running')!.opts?.timeoutMs).toBe(3_000);
    expect(gdoc.receipt.service).toMatchObject({ target: 'none', state: 'manual' });
    expect(joinedCalls(g).some(c => c.startsWith('systemctl --user enable'))).toBe(false);
    const h = fakeTailnet({ serviceActive: 'inactive' });
    expect(await runMcpExpose(['--yes', '--json'], h.deps)).toBe(0);
    const hdoc = jsonDoc(h);
    expect(checkOf(hdoc, 'service')).toMatchObject({ status: 'warn' });
    expect(checkOf(hdoc, 'service')?.detail).toContain('gbrain-serve.service, stopped');
    expect(hdoc.receipt.service.state).toBe('stopped');
    expect(f.stderr.join('\n')).not.toContain(TOKEN);
  });
  test('health polling follows the wall clock (an advancing `now` ends the budget long before the attempt cap) and a non-2xx answer is unhealthy', async () => {
    // Budget 100ms, interval 10ms → the attempt cap alone would allow 10 probes. pollHealth reads the
    // clock once for the deadline, then twice per attempt (remaining, left); each read advances `step`.
    //   step 30: deadline T+130 → probe@60, left 40 → sleep → probe@120, left -20 → exits on `left <= 0`  (2 poll probes)
    //   step 40: deadline T+140 → probe@80, left 20 → sleep → remaining@160 = -20 → exits on `attempt > 0 && remaining <= 0` (1 poll probe)
    for (const [step, pollProbes] of [[30, 2], [40, 1]] as const) {
      const f = fakeTailnet();
      let t = Date.parse('2026-06-01T12:00:00.000Z');
      f.deps.now = () => new Date((t += step));
      f.deps.localHealthMs = 100;
      f.deps.healthIntervalMs = 10;
      // The plan-step occupancy probe must see a CLOSED port (any answer counts as occupied); the
      // verify polls then get a 503, which is "answering but unhealthy".
      f.deps.fetch = async (url) => {
        f.fetches.push(url);
        if (!url.startsWith('http://127.0.0.1:')) return { ok: true, status: 200 };
        if (f.fetches.filter(u => u === url).length === 1) throw new Error('ECONNREFUSED');
        return { ok: false, status: 503 };
      };
      expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(2);
      const doc = jsonDoc(f);
      expect(doc).toMatchObject({ status: 'pending', reason: 'local_health_timeout' });
      // 1 probe in the plan step (foreign-listener check) + the poll attempts the clock allowed
      expect(f.fetches.filter(u => u === 'http://127.0.0.1:3131/health')).toHaveLength(1 + pollProbes);
      expect(f.fetches.some(u => u.startsWith('https://'))).toBe(false);
      expect(checkOf(doc, 'verify.local')).toMatchObject({ status: 'warn', detail: 'http://127.0.0.1:3131/health: timeout' });
      expect(checkOf(doc, 'verify.tailnet')).toMatchObject({ status: 'skipped', detail: 'local server not confirmed yet' });
    }
  });
});

describe('tailscale binary + login step edges', () => {
  test('status --json without JSON: an operator error → exit 1 tailscale_needs_operator; silence → tailscale_unknown; a killed probe → daemon pending (probe bounded to 15s)', async () => {
    const f = fakeTailnet({ statusStdoutOverride: 'Access denied', statusStderr: 'Access denied: serve requires the operator' });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'tailscale_needs_operator' });
    expect(doc.message).toContain('sudo tailscale set --operator=alice-example');
    expect(checkOf(doc, 'tailscale.login')).toMatchObject({ status: 'fail', detail: 'Access denied: serve requires the operator' });
    expect(joinedCalls(f).some(c => c.includes('--bg') || c.includes(' up'))).toBe(false);
    const g = fakeTailnet({ statusStdoutOverride: '', statusStderr: '' });
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(1);
    const gdoc = jsonDoc(g);
    expect(gdoc.reason).toBe('tailscale_unknown');
    expect(checkOf(gdoc, 'tailscale.login')?.detail).toBe('tailscale status printed no JSON');
    expect(gdoc.message).toContain('without output');
    const h = fakeTailnet();
    const inner = h.deps.run!;
    h.deps.run = async (argv, o) => {
      if (argv.join(' ') === `${TS} status --json`) { h.recorded.push({ argv, opts: o }); return { status: null, stdout: '', stderr: '\n(timed out after 15000ms)' }; }
      return inner(argv, o);
    };
    expect(await runMcpExpose(['--yes', '--json'], h.deps)).toBe(2);
    const hdoc = jsonDoc(h);
    expect(hdoc).toMatchObject({ status: 'pending', reason: 'tailscale_daemon_not_running' });
    expect(checkOf(hdoc, 'tailscale.login')?.detail).toContain('daemon not running');
    expect(hdoc.next_actions).toEqual(['sudo systemctl enable --now tailscaled', 'gbrain mcp expose --yes']);
    expect(h.recorded.find(r => r.argv.join(' ') === `${TS} status --json`)!.opts?.timeoutMs).toBe(15_000);
  });
  test('GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS that is not a positive number (abc, 0, -5, empty) falls back to the 300000ms default for `tailscale up`', async () => {
    for (const raw of ['abc', '0', '-5', '']) {
      const f = fakeTailnet({ backendState: 'NeedsLogin' });
      f.deps.env = { ...f.deps.env, GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS: raw };
      expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
      const up = f.recorded.find(r => r.argv[0] === 'sudo' && r.argv[2] === 'up')!;
      expect(up.opts?.timeoutMs).toBe(300_000);
    }
  });
  test('installer exits 0 but no binary appears → tailscale_install_failed names the download page', async () => {
    const f = fakeTailnet();
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => (argv[0] === 'sh' ? { status: 0, stdout: '', stderr: '' } : inner(argv, o));
    f.deps.which = (n) => (n === 'systemctl' ? '/usr/bin/systemctl' : null);
    f.deps.fileExists = () => false;
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'tailscale_install_failed' });
    expect(checkOf(doc, 'tailscale.binary')?.detail).toBe('install finished but no binary was found');
    expect(doc.message).toContain('https://tailscale.com/download');
    expect(existsSync(f.serveDir)).toBe(false);
  });
});

describe('publish step edges', () => {
  test('switching our own handler from tailnet to funnel is one atomic `funnel --bg` (no pre-off in that direction); raw TCP forwards and non-proxy handlers are described honestly', async () => {
    const f = fakeTailnet({ existingHandlers: { 3131: false } });
    writeExposeReceipt(receiptPath(f.serveDir), fullReceipt(f));
    expect(await runMcpExpose(['--yes', '--funnel', '--json'], f.deps)).toBe(0);
    const calls = joinedCalls(f);
    expect(calls).toContain(`${TS} funnel --bg 3131`);
    expect(calls.some(c => c.includes(' off'))).toBe(false);
    expect(readExposeReceipt(receiptPath(f.serveDir))?.mode).toBe('funnel');
    const serveStatus = (doc: unknown) => async (argv: string[], o: CommandRunOptions | undefined, inner: CommandRunner) =>
      (argv.join(' ') === `${TS} serve status --json` ? { status: 0, stdout: JSON.stringify(doc), stderr: '' } : inner(argv, o));
    const g = fakeTailnet();
    const ginner = g.deps.run!;
    const gview = serveStatus({ TCP: { '443': { TCPForward: '127.0.0.1:5432' } } });
    g.deps.run = (argv, o) => gview(argv, o, ginner);
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(1);
    const gdoc = jsonDoc(g);
    expect(gdoc.reason).toBe('foreign_serve_config');
    expect(gdoc.message).toContain('*:443/ -> raw TCP forward 127.0.0.1:5432');
    expect(gdoc.message).toContain('--force');
    const h = fakeTailnet();
    const hinner = h.deps.run!;
    const hview = serveStatus({ Web: { [`${DNS}:443`]: { Handlers: { '/': { Path: '/var/www' } } } } });
    h.deps.run = (argv, o) => hview(argv, o, hinner);
    expect(await runMcpExpose(['--yes', '--json'], h.deps)).toBe(1);
    expect(jsonDoc(h).message).toContain(`${DNS}:443/ -> (non-proxy handler)`);
  });
});

describe('--status edges', () => {
  test('after a --no-tailscale publish the tailscale + tailnet checks are skipped; after --no-service the service is reported skipped', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--no-tailscale'], f.deps)).toBe(0);
    f.stdout.length = 0;
    f.calls.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('exposed');
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'skipped', detail: 'published without Tailscale' });
    expect(checkOf(doc, 'verify.tailnet')).toMatchObject({ status: 'skipped', detail: 'no https public URL' });
    expect(checkOf(doc, 'service')?.status).toBe('ok');
    expect(f.calls.some(c => c[0] === TS)).toBe(false);
    const g = fakeTailnet({ localListeningBefore: true });
    expect(await runMcpExpose(['--yes', '--no-service'], g.deps)).toBe(0);
    g.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], g.deps)).toBe(0);
    const gdoc = jsonDoc(g);
    expect(gdoc.status).toBe('exposed');
    expect(checkOf(gdoc, 'service')).toMatchObject({ status: 'skipped', detail: 'installed with --no-service' });
    expect(joinedCalls(g).some(c => c.startsWith('systemctl --user is-active'))).toBe(false);
  });
  test('a handler whose funnel flag disagrees with the receipt warns (exit 1); a vanished tailscale binary fails the publish check', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    await f.run([TS, 'funnel', '--bg', '3131']); // someone flipped Funnel on by hand
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'status_unhealthy' });
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('funnel=true; receipt says tailnet');
    const g = fakeTailnet();
    expect(await runMcpExpose(['--yes'], g.deps)).toBe(0);
    g.deps.which = (n) => (n === 'systemctl' ? '/usr/bin/systemctl' : n === 'gbrain' ? '/usr/local/bin/gbrain' : null);
    g.deps.fileExists = hermeticExists(g.home, () => false); // the binary vanished; no candidate answers
    g.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], g.deps)).toBe(1);
    expect(checkOf(jsonDoc(g), 'tailscale.publish')).toMatchObject({ status: 'fail', detail: 'tailscale binary not found' });
  });
});

describe('one-click client links', () => {
  const MCP = `https://${DNS}/mcp`;
  const CLAUDE_LINE = `  Claude           https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=GBrain&connectorUrl=${encodeURIComponent(MCP)}`;
  const CURSOR_LINK = `cursor://anysphere.cursor-deeplink/mcp/install?name=gbrain&config=${encodeURIComponent(Buffer.from(JSON.stringify({ url: MCP })).toString('base64'))}`;
  const CLAUDE_LINK = CLAUDE_LINE.trim().slice('Claude'.length).trim();
  test('a Funnel publish prints the Claude and Cursor lines in the Next block', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--funnel'], f.deps)).toBe(0);
    const out = f.stdout.join('\n');
    const next = out.slice(out.indexOf('Next — choose the connection method'));
    expect(next).toContain(CLAUDE_LINE);
    expect(next).toContain(`  Cursor           ${CURSOR_LINK}`);
    expect(next).not.toContain('must be on your tailnet');
    expect(out).not.toContain(TOKEN);
  });
  test('a tailnet-only publish prints the Cursor line only, with the tailnet note', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const out = f.stdout.join('\n');
    expect(out).toContain(`  Cursor           ${CURSOR_LINK}`);
    expect(out).toContain('the Cursor machine must be on your tailnet');
    expect(out).not.toContain('claude.ai/customize');
  });
  test('--json carries install_links (Claude only with Funnel), and --status --json repeats them', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--funnel', '--json'], f.deps)).toBe(0);
    expect(jsonDoc(f).install_links).toEqual({ claude: CLAUDE_LINK, cursor: CURSOR_LINK });
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(0);
    expect(jsonDoc(f).install_links).toEqual({ claude: CLAUDE_LINK, cursor: CURSOR_LINK });
    const g = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(0);
    expect(jsonDoc(g).install_links).toEqual({ cursor: CURSOR_LINK });
    g.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], g.deps)).toBe(0);
    expect(jsonDoc(g).install_links).toEqual({ cursor: CURSOR_LINK });
  });
  test('human --status prints the link lines when everything verifies', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--funnel'], f.deps)).toBe(0);
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status'], f.deps)).toBe(0);
    const out = f.stdout.join('\n');
    expect(out).toContain(CLAUDE_LINE);
    expect(out).toContain(`  Cursor           ${CURSOR_LINK}`);
  });
  test('a non-https receipt URL (--no-tailscale) prints no link lines and no install_links key', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--no-tailscale'], f.deps)).toBe(0);
    expect(f.stdout.join('\n')).not.toMatch(/cursor:\/\/|claude\.ai|^ {2}(Claude|Cursor) /m);
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status'], f.deps)).toBe(0);
    expect(f.stdout.join('\n')).not.toMatch(/cursor:\/\/|claude\.ai/);
    const g = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--no-tailscale', '--json'], g.deps)).toBe(0);
    expect(jsonDoc(g).receipt.mcp_url).toBe('http://127.0.0.1:3131/mcp');
    expect('install_links' in jsonDoc(g)).toBe(false);
    g.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], g.deps)).toBe(0);
    expect('install_links' in jsonDoc(g)).toBe(false);
  });
});

describe('--remove edges', () => {
  test('binary gone → handler left with a warning; a --no-tailscale receipt has nothing to undo; a skipped receipt with no service → none installed (interactive yes); an undeletable wrapper is a note', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    f.deps.which = (n) => (n === 'systemctl' ? '/usr/bin/systemctl' : null);
    f.deps.fileExists = hermeticExists(f.home, () => false); // the binary vanished; no candidate answers
    f.stdout.length = 0;
    f.calls.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'warn', detail: 'tailscale binary not found; serve handler left as is' });
    expect(f.stderr.join('\n')).toContain('the tailscale serve handler (binary not found)');
    expect(joinedCalls(f).some(c => c.includes('off'))).toBe(false);
    // --no-tailscale receipt
    const g = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--no-tailscale'], g.deps)).toBe(0);
    g.stdout.length = 0;
    g.calls.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], g.deps)).toBe(0);
    const gdoc = jsonDoc(g);
    expect(checkOf(gdoc, 'plan')?.detail).toContain('Tailscale nothing to undo');
    expect(checkOf(gdoc, 'tailscale.publish')).toMatchObject({ status: 'skipped', detail: 'published without Tailscale' });
    expect(g.calls.some(c => c[0] === TS)).toBe(false);
    expect(g.stderr.join('\n')).toContain('Left in place: ~/.gbrain/serve/admin-token (admin token; pass --force to delete)');
    expect(g.stderr.join('\n')).not.toContain('Tailscale itself');
    // receipt says skipped, supervisor has nothing, unit file gone → none installed
    const h = fakeTailnet();
    expect(await runMcpExpose(['--yes'], h.deps)).toBe(0);
    const receipt = readExposeReceipt(receiptPath(h.serveDir))!;
    writeExposeReceipt(receiptPath(h.serveDir), { ...receipt, service: { ...receipt.service, unit_path: null, state: 'skipped' } });
    h.stopService();
    rmSync(h.deps.unitPath!);
    h.stdout.length = 0;
    h.calls.length = 0;
    h.deps.isTTY = true;
    h.deps.prompt = async () => 'YES';
    expect(await runMcpExpose(['--remove', '--json'], h.deps)).toBe(0);
    const hdoc = jsonDoc(h);
    expect(checkOf(hdoc, 'consent')?.detail).toBe('confirmed interactively');
    expect(checkOf(hdoc, 'service')).toMatchObject({ status: 'skipped', detail: 'none installed' });
    expect(joinedCalls(h)).toContain('systemctl --user is-active gbrain-serve.service');
    expect(joinedCalls(h).some(c => c.includes('disable'))).toBe(false);
    // a directory where the wrapper was: unlink fails, the run still completes
    const i = fakeTailnet();
    expect(await runMcpExpose(['--yes'], i.deps)).toBe(0);
    rmSync(wrapperPath(i.serveDir));
    mkdirSync(wrapperPath(i.serveDir));
    i.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], i.deps)).toBe(0);
    const idoc = jsonDoc(i);
    expect(idoc.status).toBe('removed');
    expect(i.stderr.join('\n')).toContain(`could not delete ${wrapperPath(i.serveDir)}`);
    expect(checkOf(idoc, 'receipt')?.detail).not.toContain('gbrain-serve.sh');
    expect(existsSync(receiptPath(i.serveDir))).toBe(false);
  });
  test('when `funnel off` only clears the funnel flag, `serve off` follows; a handler that survives both is reported and left in place', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--funnel'], f.deps)).toBe(0);
    const inner = f.deps.run!;
    let funnelOn = true;
    let handlerOn = true;
    f.deps.run = async (argv, o) => {
      const joined = argv.join(' ');
      if (joined === `${TS} serve status --json`) {
        const web = handlerOn ? { [`${DNS}:443`]: { Handlers: { '/': { Proxy: 'http://127.0.0.1:3131' } } } } : {};
        const allow = funnelOn && handlerOn ? { [`${DNS}:443`]: true } : {};
        return { status: 0, stdout: JSON.stringify({ TCP: { '443': { HTTPS: true } }, Web: web, AllowFunnel: allow }), stderr: '' };
      }
      if (joined === `${TS} funnel --https=443 --set-path=/ off`) { f.calls.push(argv); funnelOn = false; return { status: 0, stdout: '', stderr: '' }; }
      if (joined === `${TS} serve --https=443 --set-path=/ off`) { f.calls.push(argv); handlerOn = false; return { status: 0, stdout: '', stderr: '' }; }
      return inner(argv, o);
    };
    f.stdout.length = 0;
    f.calls.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    const calls = joinedCalls(f);
    expect(calls.indexOf(`${TS} funnel --https=443 --set-path=/ off`)).toBeGreaterThanOrEqual(0);
    expect(calls.indexOf(`${TS} funnel --https=443 --set-path=/ off`)).toBeLessThan(calls.indexOf(`${TS} serve --https=443 --set-path=/ off`));
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'ok', detail: 'funnel off: exit 0, serve off: exit 0' });
    // a handler that survives `off` is NOT a successful removal: the service is gone, but the receipt and the wrapper stay for the re-run
    const g = fakeTailnet();
    expect(await runMcpExpose(['--yes'], g.deps)).toBe(0);
    const ginner = g.deps.run!;
    g.deps.run = async (argv, o) => (argv[0] === TS && argv[2] === '--https=443' && argv[3] === '--set-path=/' && argv[4] === 'off' ? { status: 1, stdout: '', stderr: 'nope' } : ginner(argv, o));
    g.stdout.length = 0;
    g.calls.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], g.deps)).toBe(1);
    const gdoc = jsonDoc(g);
    expect(gdoc).toMatchObject({ status: 'error', reason: 'handler_not_removed' });
    expect(gdoc.message).toBe('the tailscale handler for port 3131 is still present; left in place: the wrapper and the receipt');
    expect(gdoc.receipt).not.toBeNull();
    expect(checkOf(gdoc, 'tailscale.publish')).toMatchObject({ status: 'fail' });
    expect(checkOf(gdoc, 'tailscale.publish')?.detail).toContain('serve off: exit 1');
    expect(checkOf(gdoc, 'tailscale.publish')?.detail).toContain('handler still present');
    expect(checkOf(gdoc, 'service')).toMatchObject({ status: 'ok' });
    expect(checkOf(gdoc, 'receipt')).toMatchObject({ status: 'skipped' });
    expect(checkOf(gdoc, 'receipt')?.detail).toContain('kept: the wrapper and the receipt');
    expect(gdoc.next_actions).toEqual(['tailscale serve status', 'gbrain mcp expose --remove --yes']);
    expect(g.stderr.join('\n')).toContain('Stopped here: the service was stopped and removed, but the tailscale handler for port 3131 is still present. Left in place: the wrapper and the receipt.');
    expect(joinedCalls(g)).toContain('systemctl --user disable --now gbrain-serve.service');
    expect(existsSync(g.deps.unitPath!)).toBe(false);
    expect(existsSync(receiptPath(g.serveDir))).toBe(true);
    expect(existsSync(wrapperPath(g.serveDir))).toBe(true);
    // once `off` works again the re-run finishes the job (the service step is now "none installed" — already removed)
    g.deps.run = ginner;
    g.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], g.deps)).toBe(0);
    expect(jsonDoc(g).status).toBe('removed');
    expect(existsSync(receiptPath(g.serveDir))).toBe(false);
    expect(existsSync(wrapperPath(g.serveDir))).toBe(false);
  });
  test('darwin: a malformed pre-existing token is regenerated with a note; --remove boots the launchd agent out and deletes the plist', async () => {
    const f = fakeMac();
    mkdirSync(f.serveDir, { recursive: true });
    writeFileSync(adminTokenPath(f.serveDir), 'not-a-token\n');
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(checkOf(doc, 'admin_token')?.detail).toContain('regenerated');
    expect(f.stderr.join('\n')).toContain('was regenerated');
    expect(readFileSync(adminTokenPath(f.serveDir), 'utf-8').trim()).toBe(TOKEN);
    f.stdout.length = 0;
    f.calls.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const rdoc = jsonDoc(f);
    expect(rdoc.status).toBe('removed');
    expect(joinedCalls(f)).toContain(`launchctl bootout gui/501 ${f.deps.plistPath}`);
    expect(joinedCalls(f).some(c => c.startsWith('launchctl unload'))).toBe(false);
    expect(joinedCalls(f).some(c => c.startsWith('systemctl') || c.startsWith('sudo'))).toBe(false);
    expect(existsSync(f.deps.plistPath!)).toBe(false);
    expect(checkOf(rdoc, 'plan')?.detail).toContain('launchd com.gbrain.serve');
    expect(checkOf(rdoc, 'service')?.detail).toContain(f.deps.plistPath!);
    expect(existsSync(adminTokenPath(f.serveDir))).toBe(true);
  });
});

describe('runMcp dispatch regression', () => {
  test('an unknown subcommand names expose in the error (verdict 1); the top-level help lists the expose forms (verdict untouched)', async () => {
    const savedExitCode = process.exitCode;
    const out: string[] = [];
    const logSpy = spyOn(console, 'log').mockImplementation(((...chunks: unknown[]) => { out.push(chunks.map(String).join(' ')); }) as never);
    try {
      _resetCliExitVerdictForTests();
      await runMcp(['bogus']);
      expect(JSON.parse(out.join('').trim())).toEqual({ status: 'error', reason: 'mcp_setup_failed', message: 'Expected mcp admin, grant, verify, adapters, profiles or expose' });
      expect(currentExitCode()).toBe(1);
      out.length = 0;
      _resetCliExitVerdictForTests();
      await runMcp([]);
      const help = out.join('\n');
      expect(help).toContain('gbrain mcp expose --status [--json]');
      expect(help).toContain('gbrain mcp expose --remove [--yes] [--json]');
      expect(help).toContain('See: gbrain mcp expose --help');
      expect(help).toContain('gbrain mcp admin --help');
      expect(currentExitCode()).toBe(0);
    } finally {
      logSpy.mockRestore();
      _resetCliExitVerdictForTests();
      process.exitCode = savedExitCode ?? 0;
    }
  });
});

describe('receipt shape guard, rollback, binary + path confinement', () => {
  test('a receipt that passes the old version/port/public_url guard but lacks the service/tailscale blocks is absent: --status not_exposed (exit 2 under --json), --remove nothing to remove (exit 0), no crash', async () => {
    const f = fakeTailnet();
    mkdirSync(f.serveDir, { recursive: true });
    writeFileSync(receiptPath(f.serveDir), JSON.stringify({ version: 1, port: 3131, public_url: `https://${DNS}`, mode: 'tailnet' }));
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(2);
    expect(jsonDoc(f)).toMatchObject({ status: 'not_exposed', reason: 'not_exposed' });
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    expect(jsonDoc(f)).toMatchObject({ status: 'not_exposed', reason: 'not_exposed' });
    expect(f.stderr.join('\n')).toContain('nothing to remove');
    // the receipt-less recovery only PROBES (supervisor state, serve status) — it changes nothing when nothing of ours is found
    expect(joinedCalls(f).every(c => c === 'systemctl --user is-system-running' || c === 'systemctl --user is-active gbrain-serve.service' || c === `${TS} serve status --json`)).toBe(true);
    expect(joinedCalls(f)).toContain(`${TS} serve status --json`);
    expect(f.fetches).toEqual([]);
    // the file itself is left alone (it is not ours to delete)
    expect(existsSync(receiptPath(f.serveDir))).toBe(true);
  });
  test('--status on a manual (cloud-sandbox) receipt once the operator started the server → exit 0, service ok (manual), no supervisor probed', async () => {
    const f = fakeTailnet();
    f.deps.executionEnv = 'cloud-sandbox';
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    f.deps.fetch = async (url) => { f.fetches.push(url); return { ok: true, status: 200 }; };
    f.stdout.length = 0;
    f.calls.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('exposed');
    expect(checkOf(doc, 'service')).toMatchObject({ status: 'ok' });
    expect(checkOf(doc, 'service')?.detail).toContain('manual');
    expect(checkOf(doc, 'verify.local')?.status).toBe('ok');
    expect(checkOf(doc, 'verify.tailnet')?.status).toBe('ok');
    expect(joinedCalls(f).some(c => c.startsWith('systemctl') || c.startsWith('launchctl'))).toBe(false);
    // check order is fixed regardless of which probe answered first
    expect(doc.checks.map((c: { name: string }) => c.name)).toEqual(['receipt', 'tailscale.publish', 'service', 'verify.local', 'verify.tailnet']);
  });
  test('--status after a service_install_failed partial receipt → exit 1 with the service check failing', async () => {
    const f = fakeTailnet();
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => (argv.join(' ').startsWith('systemctl --user restart') ? { status: 1, stdout: '', stderr: 'Job for gbrain-serve.service failed' } : inner(argv, o));
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    expect(jsonDoc(f).reason).toBe('service_install_failed');
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'status_unhealthy' });
    expect(checkOf(doc, 'service')).toMatchObject({ status: 'fail' });
    expect(checkOf(doc, 'service')?.detail).toContain('stopped');
    expect(checkOf(doc, 'tailscale.publish')?.status).toBe('ok');
    expect(doc.next_actions).toContain('gbrain mcp expose --yes');
  });
  test('rollback: a throw after this run published (no handler before) turns the fresh handler off, writes no receipt, exit 1; funnel uses funnel off; a pre-existing handler is left alone', async () => {
    const f = fakeTailnet();
    mkdirSync(f.serveDir, { recursive: true });
    symlinkSync(join(f.home, 'victim'), adminTokenPath(f.serveDir));
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'mcp_expose_failed' });
    expect(doc.message).toContain('symlink');
    expect(doc.message).toContain('turned off again');
    expect(doc.message).toContain('no receipt written');
    expect(checkOf(doc, 'rollback')).toMatchObject({ status: 'ok' });
    expect(checkOf(doc, 'rollback')?.detail).toContain('tailscale serve --https=443 --set-path=/ off');
    expect(checkOf(doc, 'internal')?.status).toBe('fail');
    const calls = joinedCalls(f);
    expect(calls.indexOf(`${TS} serve --bg 3131`)).toBeGreaterThanOrEqual(0);
    expect(calls.indexOf(`${TS} serve --bg 3131`)).toBeLessThan(calls.indexOf(`${TS} serve --https=443 --set-path=/ off`));
    expect(calls.some(c => c.includes('reset'))).toBe(false);
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
    expect((await f.run([TS, 'serve', 'status', '--json'])).stdout).not.toContain('127.0.0.1:3131');
    // --funnel → funnel off
    const h = fakeTailnet();
    mkdirSync(h.serveDir, { recursive: true });
    symlinkSync(join(h.home, 'victim'), adminTokenPath(h.serveDir));
    expect(await runMcpExpose(['--yes', '--funnel', '--json'], h.deps)).toBe(1);
    expect(joinedCalls(h)).toContain(`${TS} funnel --https=443 --set-path=/ off`);
    expect(existsSync(receiptPath(h.serveDir))).toBe(false);
    // a handler for our port existed before this run → left in place, no off at all
    const g = fakeTailnet({ existingHandlers: { 3131: false } });
    mkdirSync(g.serveDir, { recursive: true });
    symlinkSync(join(g.home, 'victim'), adminTokenPath(g.serveDir));
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(1);
    const gdoc = jsonDoc(g);
    expect(gdoc).toMatchObject({ status: 'error', reason: 'mcp_expose_failed' });
    expect(gdoc.message).toContain('left in place');
    expect(checkOf(gdoc, 'rollback')).toMatchObject({ status: 'skipped' });
    expect(joinedCalls(g)).toContain(`${TS} serve --bg 3131`);
    expect(joinedCalls(g).some(c => c.includes('--https=443 --set-path=/ off'))).toBe(false);
    expect(existsSync(receiptPath(g.serveDir))).toBe(false);
    expect((await g.run([TS, 'serve', 'status', '--json'])).stdout).toContain('127.0.0.1:3131');
    // a throw BEFORE publishing (or with --no-tailscale) has nothing to roll back
    const i = fakeTailnet();
    mkdirSync(i.serveDir, { recursive: true });
    symlinkSync(join(i.home, 'victim'), adminTokenPath(i.serveDir));
    expect(await runMcpExpose(['--yes', '--no-tailscale', '--json'], i.deps)).toBe(1);
    const idoc = jsonDoc(i);
    expect(idoc.reason).toBe('mcp_expose_failed');
    expect(checkOf(idoc, 'rollback')).toBeUndefined();
    expect(i.calls.some(c => c[0] === TS)).toBe(false);
  });
  test('a receipt binary that exists but is neither the discovered binary nor a known install location is never executed (--status and --remove); a known candidate is honored', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const planted = join(f.home, 'planted-tailscale');
    writeFileSync(planted, '#!/bin/sh\nexit 0\n');
    const receipt = readExposeReceipt(receiptPath(f.serveDir))!;
    writeExposeReceipt(receiptPath(f.serveDir), { ...receipt, tailscale: { ...receipt.tailscale, binary: planted } });
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(0);
    expect(joinedCalls(f)).toContain(`${TS} serve status --json`);
    expect(f.calls.some(c => c[0] === planted)).toBe(false);
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    expect(joinedCalls(f)).toContain(`${TS} serve --https=443 --set-path=/ off`);
    expect(f.calls.some(c => c[0] === planted)).toBe(false);
    expect(existsSync(planted)).toBe(true);
    // the macOS app-bundle CLI is not on PATH but IS a known candidate → the recorded path is used
    const g = fakeMac();
    expect(await runMcpExpose(['--yes'], g.deps)).toBe(0);
    expect(readExposeReceipt(receiptPath(g.serveDir))?.tailscale.binary).toBe(APP_TS);
    g.calls.length = 0;
    g.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], g.deps)).toBe(0);
    expect(joinedCalls(g)).toContain(`${APP_TS} serve status --json`);
  });
  test('rollback when the off command fails: exit 1 or a throwing runner → rollback warn, message says NOT turned off and keeps the original error, no receipt', async () => {
    for (const mode of ['exit-1', 'throw'] as const) {
      const f = fakeTailnet();
      mkdirSync(f.serveDir, { recursive: true });
      symlinkSync(join(f.home, 'victim'), adminTokenPath(f.serveDir));
      const inner = f.deps.run!;
      f.deps.run = async (argv, o) => {
        if (argv[0] === TS && argv[2] === '--https=443' && argv[3] === '--set-path=/' && argv[4] === 'off') {
          f.calls.push(argv);
          if (mode === 'throw') throw new Error('spawn exploded during off');
          return { status: 1, stdout: '', stderr: 'nope' };
        }
        return inner(argv, o);
      };
      expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
      const doc = jsonDoc(f);
      expect(doc).toMatchObject({ status: 'error', reason: 'mcp_expose_failed' });
      expect(doc.message).toContain('symlink');
      expect(doc.message).toContain('NOT turned off');
      expect(doc.message).toContain(mode === 'throw' ? 'spawn exploded during off' : 'exit 1');
      expect(doc.message).toContain('no receipt written');
      expect(checkOf(doc, 'rollback')).toMatchObject({ status: 'warn' });
      expect(checkOf(doc, 'rollback')?.detail).toContain('NOT turned off');
      expect(joinedCalls(f)).toContain(`${TS} serve --https=443 --set-path=/ off`);
      expect(existsSync(receiptPath(f.serveDir))).toBe(false);
    }
  });
  test('--remove hands the supervisor only the COMPUTED plist/unit path: a receipt pointing at ~/precious leaves it intact, still removes the real unit, and names the recorded path in "Left in place"', async () => {
    for (const [fake, field, unitOf] of [
      [fakeTailnet(), 'unit_path', (f: Fake) => f.deps.unitPath!],
      [fakeMac(), 'plist_path', (f: Fake) => f.deps.plistPath!],
    ] as const) {
      expect(await runMcpExpose(['--yes'], fake.deps)).toBe(0);
      const precious = join(fake.home, 'precious');
      writeFileSync(precious, 'keep me\n');
      const receipt = readExposeReceipt(receiptPath(fake.serveDir))!;
      writeExposeReceipt(receiptPath(fake.serveDir), { ...receipt, service: { ...receipt.service, [field]: precious } });
      expect(existsSync(unitOf(fake))).toBe(true);
      fake.stdout.length = 0;
      fake.calls.length = 0;
      expect(await runMcpExpose(['--remove', '--yes', '--json'], fake.deps)).toBe(0);
      const doc = jsonDoc(fake);
      expect(doc.status).toBe('removed');
      expect(existsSync(precious)).toBe(true);
      expect(readFileSync(precious, 'utf-8')).toBe('keep me\n');
      expect(existsSync(unitOf(fake))).toBe(false);
      expect(checkOf(doc, 'service')?.detail).toContain(unitOf(fake));
      expect(checkOf(doc, 'service')?.detail).not.toContain('precious');
      expect(joinedCalls(fake).some(c => c.includes('precious'))).toBe(false);
      expect(fake.stderr.join('\n')).toContain('~/precious (recorded in the receipt but not the expected location; not touched)');
      expect(existsSync(receiptPath(fake.serveDir))).toBe(false);
    }
  });
  test('--remove never unlinks a wrapper or token path outside the serve directory; each is named in "Left in place"', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const elsewhere = join(f.home, 'precious.sh');
    writeFileSync(elsewhere, 'keep\n');
    const receipt = readExposeReceipt(receiptPath(f.serveDir))!;
    writeExposeReceipt(receiptPath(f.serveDir), { ...receipt, service: { ...receipt.service, wrapper_path: elsewhere } });
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('removed');
    expect(existsSync(elsewhere)).toBe(true);
    expect(readFileSync(elsewhere, 'utf-8')).toBe('keep\n');
    expect(f.stderr.join('\n')).toContain('~/precious.sh (outside the serve directory; not touched)');
    expect(checkOf(doc, 'plan')?.detail).toContain('leave ~/precious.sh (outside the serve directory; not touched)');
    expect(checkOf(doc, 'receipt')?.detail).not.toContain('precious');
    expect(checkOf(doc, 'receipt')?.detail).toContain('expose.json');
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
    // --force with an out-of-dir token path leaves the token alone too
    const g = fakeTailnet();
    expect(await runMcpExpose(['--yes'], g.deps)).toBe(0);
    const tokenElsewhere = join(g.home, 'token-elsewhere');
    writeFileSync(tokenElsewhere, `${TOKEN}\n`);
    const greceipt = readExposeReceipt(receiptPath(g.serveDir))!;
    writeExposeReceipt(receiptPath(g.serveDir), { ...greceipt, admin_token_file: tokenElsewhere });
    g.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--force', '--json'], g.deps)).toBe(0);
    const gdoc = jsonDoc(g);
    expect(existsSync(tokenElsewhere)).toBe(true);
    expect(g.stderr.join('\n')).toContain('~/token-elsewhere (admin token outside the serve directory; not touched)');
    expect(checkOf(gdoc, 'plan')?.detail).toContain('Token     leave ~/token-elsewhere');
    expect(existsSync(wrapperPath(g.serveDir))).toBe(false);
  });
});

describe('occupied-port probe (any answer counts)', () => {
  test('a listener that 404s /health is still a foreign listener: refused before any tailscale serve argv; with --no-service it counts as "something listens"', async () => {
    const f = fakeTailnet();
    f.deps.fetch = async (url) => { f.fetches.push(url); if (url.startsWith('http://127.0.0.1:')) return { ok: false, status: 404 }; return { ok: true, status: 200 }; };
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'foreign_listener' });
    expect(doc.message).toContain('Something already answers on 127.0.0.1:3131');
    expect(checkOf(doc, 'service')?.detail).toContain('something already answers on 127.0.0.1:3131');
    expect(f.calls.some(c => c[0] === TS)).toBe(false);
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
    expect(existsSync(f.serveDir)).toBe(false);
    // a 500 is occupied too
    const g = fakeTailnet();
    g.deps.fetch = async (url) => (url.startsWith('http://127.0.0.1:') ? { ok: false, status: 500 } : { ok: true, status: 200 });
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(1);
    expect(jsonDoc(g).reason).toBe('foreign_listener');
    // --no-service: the occupant is the operator's server → the local wait runs (and, unhealthy, times out) instead of "Nothing listens"
    const h = fakeTailnet();
    h.deps.fetch = async (url) => { h.fetches.push(url); if (url.startsWith('http://127.0.0.1:')) return { ok: false, status: 404 }; return { ok: true, status: 200 }; };
    expect(await runMcpExpose(['--yes', '--no-service', '--json'], h.deps)).toBe(2);
    const hdoc = jsonDoc(h);
    expect(hdoc).toMatchObject({ status: 'pending', reason: 'local_health_timeout' });
    expect(checkOf(hdoc, 'verify.local')).toMatchObject({ status: 'warn' });
    expect(h.stderr.join('\n')).not.toContain('Nothing listens on 127.0.0.1:3131');
    // health itself still needs 2xx: a refused connection is neither occupied nor healthy
    const i = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--no-service', '--json'], i.deps)).toBe(0);
    expect(checkOf(jsonDoc(i), 'verify.local')?.status).toBe('skipped');
  });
});

describe('tailscale serve status fails closed', () => {
  /** Make the fake's `serve status --json` answer with `result` (a broken read) while everything else works. */
  const breakServeStatus = (f: Fake, result: { status: number | null; stdout: string; stderr: string }) => {
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => {
      if (argv.join(' ') === `${TS} serve status --json`) { f.calls.push(argv); f.recorded.push({ argv, opts: o }); return result; }
      return inner(argv, o);
    };
  };
  test('publish: a non-zero exit is classified (needs_operator), a killed read is unknown, exit 0 with non-JSON stdout is unknown — nothing is published in any case', async () => {
    const f = fakeTailnet();
    breakServeStatus(f, { status: 1, stdout: '', stderr: 'Access denied: serve requires the operator flag' });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'tailscale_needs_operator' });
    expect(doc.message).toContain('Could not read the current `tailscale serve status`, so nothing was published.');
    expect(doc.message).toContain('sudo tailscale set --operator=alice-example');
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'fail' });
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('could not read tailscale serve status (exit 1): needs_operator');
    expect(doc.next_actions).toContain('tailscale serve status --json');
    expect(joinedCalls(f).some(c => c.includes('--bg'))).toBe(false);
    expect(existsSync(f.serveDir)).toBe(false);
    const g = fakeTailnet();
    breakServeStatus(g, { status: null, stdout: '', stderr: '\n(timed out after 15000ms)' });
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(1);
    const gdoc = jsonDoc(g);
    expect(gdoc.reason).toBe('tailscale_unknown');
    expect(checkOf(gdoc, 'tailscale.publish')?.detail).toContain('killed or not spawned');
    expect(joinedCalls(g).some(c => c.includes('--bg'))).toBe(false);
    const h = fakeTailnet();
    breakServeStatus(h, { status: 0, stdout: 'Warning: serve is in a weird state\n', stderr: '' });
    expect(await runMcpExpose(['--yes', '--json'], h.deps)).toBe(1);
    const hdoc = jsonDoc(h);
    expect(hdoc.reason).toBe('tailscale_unknown');
    expect(checkOf(hdoc, 'tailscale.publish')?.detail).toContain('exit 0 but stdout was not a JSON object');
    expect(joinedCalls(h).some(c => c.includes('--bg'))).toBe(false);
    // an EMPTY document from exit 0 is a legitimately empty config → publish proceeds
    const i = fakeTailnet();
    const iinner = i.deps.run!;
    let published = false;
    i.deps.run = async (argv, o) => {
      if (argv.join(' ') === `${TS} serve status --json` && !published) return { status: 0, stdout: '', stderr: '' };
      if (argv[1] === 'serve' && argv[2] === '--bg') published = true;
      return iinner(argv, o);
    };
    expect(await runMcpExpose(['--yes', '--json'], i.deps)).toBe(0);
  });
  test('--remove: an unreadable serve status fails the tailscale check, keeps the receipt AND the wrapper, exit 1; a re-run once it reads again finishes the job', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const inner = f.deps.run!;
    let broken = true;
    f.deps.run = async (argv, o) => {
      if (broken && argv.join(' ') === `${TS} serve status --json`) { f.calls.push(argv); return { status: 1, stdout: '', stderr: 'failed to connect to local Tailscale service; is Tailscale running?' }; }
      return inner(argv, o);
    };
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'tailscale_serve_status_unreadable', message: 'could not read tailscale serve status; handler left as is' });
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'fail' });
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('could not read tailscale serve status (exit 1): daemon_not_running');
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('handler left as is');
    expect(checkOf(doc, 'receipt')).toMatchObject({ status: 'skipped' });
    expect(doc.receipt).not.toBeNull();
    expect(doc.next_actions).toContain('gbrain mcp expose --remove --yes');
    expect(joinedCalls(f).some(c => c.includes('--https=443 --set-path=/ off'))).toBe(false);
    expect(existsSync(receiptPath(f.serveDir))).toBe(true);
    expect(existsSync(wrapperPath(f.serveDir))).toBe(true);
    expect((await inner([TS, 'serve', 'status', '--json'])).stdout).toContain('127.0.0.1:3131');
    expect(f.stderr.join('\n')).toContain('run the removal again (the user already approved it: `gbrain mcp expose --remove --yes`)');
    // Tailscale is back → the same command completes the removal
    broken = false;
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    expect(jsonDoc(f).status).toBe('removed');
    expect(joinedCalls(f)).toContain(`${TS} serve --https=443 --set-path=/ off`);
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
    expect(existsSync(wrapperPath(f.serveDir))).toBe(false);
  });
  test('--status: an unreadable serve status is a failed tailscale.publish check (never "handler present"), exit 1', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    breakServeStatus(f, { status: 1, stdout: '', stderr: 'Access denied' });
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'status_unhealthy' });
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'fail' });
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('could not read tailscale serve status (exit 1): needs_operator');
    expect(doc.next_actions).toContain('tailscale serve status --json');
    // the other probes still ran and are reported in order
    expect(doc.checks.map((c: { name: string }) => c.name)).toEqual(['receipt', 'tailscale.publish', 'service', 'verify.local', 'verify.tailnet']);
    expect(checkOf(doc, 'service')?.status).toBe('ok');
    // exit 0 with junk on stdout is the same failure
    const g = fakeTailnet();
    expect(await runMcpExpose(['--yes'], g.deps)).toBe(0);
    breakServeStatus(g, { status: 0, stdout: 'not json at all', stderr: '' });
    g.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], g.deps)).toBe(1);
    expect(checkOf(jsonDoc(g), 'tailscale.publish')?.detail).toContain('exit 0 but stdout was not a JSON object');
  });
  test('--remove: a serve-status re-read that fails only AFTER `off` ran is a warn (could not re-read), the handler state is unknown — never claimed removed: receipt + wrapper kept, exit 1 handler_not_removed', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const inner = f.deps.run!;
    let offRan = false;
    f.deps.run = async (argv, o) => {
      if (argv[0] === TS && argv[2] === '--https=443' && argv[3] === '--set-path=/' && argv[4] === 'off') offRan = true;
      if (offRan && argv.join(' ') === `${TS} serve status --json`) { f.calls.push(argv); return { status: 1, stdout: '', stderr: 'Access denied' }; }
      return inner(argv, o);
    };
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'handler_not_removed' });
    expect(doc.message).toContain('could not be confirmed gone (tailscale serve status could not be re-read)');
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('serve off: exit 0');
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('could not re-read');
    expect(checkOf(doc, 'service')).toMatchObject({ status: 'ok' });
    expect(checkOf(doc, 'receipt')).toMatchObject({ status: 'skipped' });
    expect(doc.next_actions).toContain('gbrain mcp expose --remove --yes');
    expect(f.stderr.join('\n')).toContain('Stopped here: the service was stopped and removed, but the tailscale handler for port 3131 could not be confirmed gone');
    expect(joinedCalls(f)).toContain(`${TS} serve --https=443 --set-path=/ off`);
    expect(existsSync(receiptPath(f.serveDir))).toBe(true);
    expect(existsSync(wrapperPath(f.serveDir))).toBe(true);
  });
  test('publish: the POST-publish serve-status read failing is tailscale_publish_unconfirmed ("could not be read afterwards"), points at --remove --yes, writes no receipt', async () => {
    const f = fakeTailnet();
    const inner = f.deps.run!;
    let published = false;
    f.deps.run = async (argv, o) => {
      if (argv[0] === TS && argv[1] === 'serve' && argv[2] === '--bg') published = true;
      if (published && argv.join(' ') === `${TS} serve status --json`) { f.calls.push(argv); return { status: 1, stdout: '', stderr: 'Access denied' }; }
      return inner(argv, o);
    };
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'tailscale_publish_unconfirmed' });
    expect(doc.message).toContain('could not be read afterwards');
    expect(doc.message).toContain('--force');
    expect(doc.next_actions).toContain('gbrain mcp expose --remove --yes');
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('exited 0 but could not read tailscale serve status (exit 1): needs_operator');
    expect(joinedCalls(f)).toContain(`${TS} serve --bg 3131`);
    expect(checkOf(doc, 'admin_token')).toBeUndefined();
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
    expect(existsSync(f.serveDir)).toBe(false);
  });
});

describe('early receipt + receipt-less recovery', () => {
  test('the receipt is on disk right after the service step — before verify — and is rewritten with the settled state when verify never turns healthy', async () => {
    const f = fakeTailnet({ localHealthyAfterStart: false });
    const inner = f.deps.fetch!;
    const receiptSeenDuringVerify: boolean[] = [];
    f.deps.fetch = async (url, init) => {
      if (url.startsWith('http://127.0.0.1:') && f.fetches.length > 0) receiptSeenDuringVerify.push(existsSync(receiptPath(f.serveDir)));
      return inner(url, init);
    };
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(2);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'pending', reason: 'local_health_timeout' });
    // every verify poll (all local probes after the plan-step occupancy probe) saw the receipt already written
    expect(receiptSeenDuringVerify.length).toBeGreaterThan(0);
    expect(receiptSeenDuringVerify.every(Boolean)).toBe(true);
    const receipt = readExposeReceipt(receiptPath(f.serveDir))!;
    expect(receipt.service).toMatchObject({ target: 'linux-systemd', state: 'running', unit_path: f.deps.unitPath });
    expect(receipt.created_at).toBe('2026-06-01T12:00:00.000Z');
    expect(doc.receipt).toEqual(receipt);
    expect(checkOf(doc, 'receipt')?.status).toBe('ok');
  });
  test('a throw AFTER the early receipt leaves handler + service in place (no rollback) and points at --status / --remove', async () => {
    const f = fakeTailnet({ localHealthyAfterStart: false });
    f.deps.sleep = async () => { throw new Error('clock exploded'); };
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'mcp_expose_failed' });
    expect(doc.message).toContain('clock exploded');
    expect(doc.message).toContain('the receipt was already written');
    expect(checkOf(doc, 'rollback')).toMatchObject({ status: 'skipped' });
    expect(checkOf(doc, 'rollback')?.detail).toContain('receipt already written');
    expect(doc.next_actions).toContain('gbrain mcp expose --remove --yes');
    expect(joinedCalls(f).some(c => c.includes('--https=443 --set-path=/ off'))).toBe(false);
    expect(existsSync(receiptPath(f.serveDir))).toBe(true);
    expect((await f.run([TS, 'serve', 'status', '--json'])).stdout).toContain('127.0.0.1:3131');
    // and --remove cleans it all up
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
    expect((await f.run([TS, 'serve', 'status', '--json'])).stdout).not.toContain('127.0.0.1:3131');
  });
  test('an interrupted run (receipt deleted after a successful publish): --remove --yes still removes the unit + wrapper and turns the handler off, leaves the token', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    rmSync(receiptPath(f.serveDir));
    f.calls.length = 0;
    f.stdout.length = 0;
    // non-TTY without --yes: a plan + confirmation_required, nothing changed
    expect(await runMcpExpose(['--remove', '--json'], f.deps)).toBe(2);
    const pending = jsonDoc(f);
    expect(pending).toMatchObject({ status: 'pending', reason: 'confirmation_required' });
    expect(checkOf(pending, 'receipt')).toMatchObject({ status: 'warn' });
    expect(checkOf(pending, 'receipt')?.detail).toContain('recovering from what is on disk (port 3131)');
    expect(checkOf(pending, 'plan')?.detail).toContain('stop + remove systemd (user) gbrain-serve.service');
    expect(checkOf(pending, 'plan')?.detail).toContain('turn off the :443 handler proxying http://127.0.0.1:3131');
    expect(checkOf(pending, 'plan')?.detail).toContain(`delete ~/.gbrain/serve/gbrain-serve.sh`);
    expect(checkOf(pending, 'plan')?.detail).toContain('leave ~/.gbrain/serve/admin-token');
    expect(pending.next_actions).toContain('gbrain mcp expose --remove --yes');
    expect(f.stderr.join('\n')).toContain('Recovering without a receipt');
    expect(joinedCalls(f).some(c => c.includes('off') || c.includes('disable'))).toBe(false);
    expect(existsSync(wrapperPath(f.serveDir))).toBe(true);
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'removed', reason: 'recovered_without_receipt' });
    const calls = joinedCalls(f);
    expect(calls).toContain('systemctl --user disable --now gbrain-serve.service');
    expect(calls).toContain(`${TS} serve --https=443 --set-path=/ off`);
    expect(calls.some(c => /reset|logout|uninstall/.test(c))).toBe(false);
    expect(checkOf(doc, 'service')?.detail).toContain(f.deps.unitPath!);
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'ok', detail: 'serve off: exit 0' });
    expect(checkOf(doc, 'files')?.detail).toContain('gbrain-serve.sh');
    expect(existsSync(f.deps.unitPath!)).toBe(false);
    expect(existsSync(wrapperPath(f.serveDir))).toBe(false);
    expect(existsSync(adminTokenPath(f.serveDir))).toBe(true);
    expect((await f.run([TS, 'serve', 'status', '--json'])).stdout).not.toContain('127.0.0.1:3131');
    expect(f.stderr.join('\n')).toContain('Removed the leftovers of an interrupted publish.');
    expect(f.stderr.join('\n')).toContain('admin token; left without a receipt');
    // now truly nothing is left → the plain "nothing to remove"
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    expect(jsonDoc(f)).toMatchObject({ status: 'not_exposed', reason: 'not_exposed' });
  });
  test('recovery honors --port (a handler for another port is not ours), turns Funnel off first, and on darwin boots the agent out', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--funnel', '--port', '4000'], f.deps)).toBe(0);
    rmSync(receiptPath(f.serveDir));
    f.calls.length = 0;
    f.stdout.length = 0;
    // default port 3131: the handler proxies 4000 → not touched (service + wrapper still ours)
    expect(await runMcpExpose(['--remove', '--yes', '--port', '5000', '--json'], f.deps)).toBe(0);
    const other = jsonDoc(f);
    expect(other.status).toBe('removed');
    expect(checkOf(other, 'tailscale.publish')?.detail).toContain('no :443 handler proxies to port 5000');
    expect(joinedCalls(f).some(c => c.includes('--https=443 --set-path=/ off'))).toBe(false);
    expect((await f.run([TS, 'serve', 'status', '--json'])).stdout).toContain('127.0.0.1:4000');
    // right port: funnel off first, then serve off
    // (re-create the wrapper the previous recovery removed, as an interrupted run would have left it)
    writeFileSync(wrapperPath(f.serveDir), '#!/bin/bash\nexit 0\n');
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--port', '4000', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(checkOf(doc, 'plan')?.detail).toContain('(funnel first)');
    const calls = joinedCalls(f);
    expect(calls).toContain(`${TS} funnel --https=443 --set-path=/ off`);
    expect((await f.run([TS, 'serve', 'status', '--json'])).stdout).not.toContain('127.0.0.1:4000');
    expect(existsSync(wrapperPath(f.serveDir))).toBe(false);
    // darwin
    const g = fakeMac();
    expect(await runMcpExpose(['--yes'], g.deps)).toBe(0);
    rmSync(receiptPath(g.serveDir));
    g.calls.length = 0;
    g.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], g.deps)).toBe(0);
    expect(jsonDoc(g).reason).toBe('recovered_without_receipt');
    expect(joinedCalls(g)).toContain(`launchctl bootout gui/501 ${g.deps.plistPath}`);
    expect(existsSync(g.deps.plistPath!)).toBe(false);
    expect(joinedCalls(g)).toContain(`${APP_TS} serve --https=443 --set-path=/ off`);
  });
  test('recovery with only a stray wrapper removes just the wrapper; an unreadable serve status fails closed like the receipt path — service still removed, wrapper KEPT, exit 1 tailscale_serve_status_unreadable — and the re-run finishes the job', async () => {
    const f = fakeTailnet();
    mkdirSync(f.serveDir, { recursive: true });
    writeFileSync(wrapperPath(f.serveDir), '#!/bin/bash\nexit 0\n');
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.reason).toBe('recovered_without_receipt');
    expect(checkOf(doc, 'service')).toMatchObject({ status: 'skipped', detail: 'none found' });
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('nothing to turn off');
    expect(existsSync(wrapperPath(f.serveDir))).toBe(false);
    expect(joinedCalls(f).some(c => c.includes('disable') || c.includes('off'))).toBe(false);
    // stray wrapper + unreadable serve status: the handler cannot be checked, so the wrapper (the corroboration a re-run needs) stays and the exit is 1
    const h = fakeTailnet();
    mkdirSync(h.serveDir, { recursive: true });
    writeFileSync(wrapperPath(h.serveDir), '#!/bin/bash\nexit 0\n');
    const hinner = h.deps.run!;
    let hbroken = true;
    h.deps.run = async (argv, o) => (hbroken && argv.join(' ') === `${TS} serve status --json` ? { status: 1, stdout: '', stderr: 'Access denied' } : hinner(argv, o));
    expect(await runMcpExpose(['--remove', '--yes', '--json'], h.deps)).toBe(1);
    const hdoc = jsonDoc(h);
    expect(hdoc).toMatchObject({ status: 'error', reason: 'tailscale_serve_status_unreadable', message: 'could not read tailscale serve status; handler state unknown', receipt: null });
    expect(checkOf(hdoc, 'tailscale.publish')).toMatchObject({ status: 'fail' });
    expect(checkOf(hdoc, 'tailscale.publish')?.detail).toContain('could not read tailscale serve status (exit 1): needs_operator');
    expect(checkOf(hdoc, 'tailscale.publish')?.detail).toContain('handler state unknown');
    expect(checkOf(hdoc, 'files')).toMatchObject({ status: 'skipped' });
    expect(checkOf(hdoc, 'files')?.detail).toContain('kept: the wrapper');
    expect(checkOf(hdoc, 'plan')?.detail).toContain('cannot be checked — stops after the service step (exit 1)');
    expect(checkOf(hdoc, 'plan')?.detail).toContain('Files     keep ');
    expect(hdoc.next_actions).toEqual(['tailscale serve status --json', 'gbrain mcp expose --remove --yes']);
    expect(h.stderr.join('\n')).toContain('Stopped here: no service was found, but `tailscale serve status` could not be read');
    expect(h.stderr.join('\n')).not.toContain('Removed the leftovers');
    expect(existsSync(wrapperPath(h.serveDir))).toBe(true);
    expect(joinedCalls(h).some(c => c.includes('--set-path=/ off'))).toBe(false);
    // Tailscale reads again → the same command completes the recovery
    hbroken = false;
    h.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], h.deps)).toBe(0);
    expect(jsonDoc(h).reason).toBe('recovered_without_receipt');
    expect(existsSync(wrapperPath(h.serveDir))).toBe(false);
    // a full interrupted run (service + wrapper + handler, no receipt) with an unreadable serve status: the service IS uninstalled, the wrapper stays, exit 1; once readable the re-run turns the handler off
    const s = fakeTailnet();
    expect(await runMcpExpose(['--yes'], s.deps)).toBe(0);
    rmSync(receiptPath(s.serveDir));
    const sinner = s.deps.run!;
    let sbroken = true;
    s.deps.run = async (argv, o) => (sbroken && argv.join(' ') === `${TS} serve status --json` ? { status: 1, stdout: '', stderr: 'failed to connect to local Tailscale service; is Tailscale running?' } : sinner(argv, o));
    s.calls.length = 0;
    s.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], s.deps)).toBe(1);
    const sdoc = jsonDoc(s);
    expect(sdoc).toMatchObject({ status: 'error', reason: 'tailscale_serve_status_unreadable' });
    expect(checkOf(sdoc, 'service')).toMatchObject({ status: 'ok' });
    expect(joinedCalls(s)).toContain('systemctl --user disable --now gbrain-serve.service');
    expect(existsSync(s.deps.unitPath!)).toBe(false);
    expect(checkOf(sdoc, 'tailscale.publish')?.detail).toContain('could not read tailscale serve status (exit 1): daemon_not_running');
    expect(checkOf(sdoc, 'files')?.detail).toContain('kept: the wrapper');
    expect(existsSync(wrapperPath(s.serveDir))).toBe(true);
    expect(s.stderr.join('\n')).toContain('Stopped here: the service was stopped and removed, but `tailscale serve status` could not be read');
    expect((await sinner([TS, 'serve', 'status', '--json'])).stdout).toContain('127.0.0.1:3131');
    sbroken = false;
    s.calls.length = 0;
    s.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], s.deps)).toBe(0);
    expect(jsonDoc(s).reason).toBe('recovered_without_receipt');
    expect(joinedCalls(s)).toContain(`${TS} serve --https=443 --set-path=/ off`);
    expect(existsSync(wrapperPath(s.serveDir))).toBe(false);
    // nothing of ours anywhere AND serve status unreadable → still "nothing to remove", with the caveat recorded
    const i = fakeTailnet();
    const iinner = i.deps.run!;
    i.deps.run = async (argv, o) => (argv.join(' ') === `${TS} serve status --json` ? { status: 1, stdout: '', stderr: 'Access denied' } : iinner(argv, o));
    expect(await runMcpExpose(['--remove', '--yes', '--json'], i.deps)).toBe(0);
    const idoc = jsonDoc(i);
    expect(idoc).toMatchObject({ status: 'not_exposed' });
    expect(checkOf(idoc, 'tailscale.publish')?.detail).toContain('could not be checked');
  });
  test('a :443 handler for --port with NO other gbrain evidence is not proven ours: left alone (exit 0, note names the proxy target and --force); --force turns it off; a wrapper next to it is evidence enough', async () => {
    // handler only: another tool may proxy the same port — never turned off on a guess
    const f = fakeTailnet({ existingHandlers: { 3131: false } });
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'not_exposed', reason: 'not_exposed' });
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('a :443 handler proxies http://127.0.0.1:3131 but nothing else of gbrain\'s is here');
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('pass --force to turn it off');
    expect(doc.next_actions).toContain('gbrain mcp expose --remove --yes --force');
    expect(f.stderr.join('\n')).toContain('not proven to be ours');
    expect(f.stderr.join('\n')).toContain('not exposed — nothing to remove');
    expect(joinedCalls(f).some(c => c.includes('--https=443 --set-path=/ off') || c.includes('disable'))).toBe(false);
    expect((await f.run([TS, 'serve', 'status', '--json'])).stdout).toContain('127.0.0.1:3131');
    // --force: the operator vouches for it → turned off, and the plan says why
    const g = fakeTailnet({ existingHandlers: { 3131: false } });
    expect(await runMcpExpose(['--remove', '--yes', '--force', '--json'], g.deps)).toBe(0);
    const gdoc = jsonDoc(g);
    expect(gdoc.reason).toBe('recovered_without_receipt');
    expect(checkOf(gdoc, 'plan')?.detail).toContain('turn off the :443 handler proxying http://127.0.0.1:3131 (--force: no wrapper, unit or service corroborates it)');
    expect(joinedCalls(g)).toContain(`${TS} serve --https=443 --set-path=/ off`);
    expect(joinedCalls(g).some(c => c.includes('disable'))).toBe(false);
    expect(checkOf(gdoc, 'files')?.detail).toBe('removed nothing');
    expect((await g.run([TS, 'serve', 'status', '--json'])).stdout).not.toContain('127.0.0.1:3131');
    // the wrapper corroborates the handler → turned off without --force
    const h = fakeTailnet({ existingHandlers: { 3131: false } });
    mkdirSync(h.serveDir, { recursive: true });
    writeFileSync(wrapperPath(h.serveDir), '#!/bin/bash\nexit 0\n');
    expect(await runMcpExpose(['--remove', '--yes', '--json'], h.deps)).toBe(0);
    const hdoc = jsonDoc(h);
    expect(hdoc.reason).toBe('recovered_without_receipt');
    expect(checkOf(hdoc, 'plan')?.detail).not.toContain('--force');
    expect(joinedCalls(h)).toContain(`${TS} serve --https=443 --set-path=/ off`);
    expect(existsSync(wrapperPath(h.serveDir))).toBe(false);
    expect((await h.run([TS, 'serve', 'status', '--json'])).stdout).not.toContain('127.0.0.1:3131');
    // a non-TTY plan without --yes carries --force forward in the re-run hint
    const i = fakeTailnet({ existingHandlers: { 3131: false } });
    expect(await runMcpExpose(['--remove', '--force', '--json'], i.deps)).toBe(2);
    expect(jsonDoc(i).next_actions).toContain('gbrain mcp expose --remove --yes --force');
  });
});

describe('PGLite lock-holder warning', () => {
  test('a live holder that is not our own service adds a Lock plan line and a pglite_lock warn (run proceeds); our own running service, Postgres, or no holder → no warning', async () => {
    const f = fakeTailnet();
    const asked: string[] = [];
    f.deps.pgliteHolder = (dbPath) => { asked.push(dbPath); return { pid: 4242, serve: true }; };
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(asked).toEqual([join(f.home, 'brain.pglite')]);
    expect(checkOf(doc, 'pglite_lock')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'pglite_lock')?.detail).toBe('a live process holds this PGLite brain (pid 4242, gbrain serve): the service cannot start until it exits — stop it, or move to Postgres');
    expect(f.stderr.join('\n')).toContain('  Lock      a live process holds this PGLite brain (pid 4242, gbrain serve)');
    expect(doc.checks.findIndex((c: { name: string }) => c.name === 'pglite_lock')).toBe(doc.checks.findIndex((c: { name: string }) => c.name === 'plan') + 1);
    expect(doc.status).toBe('exposed');
    // a command string wins over the serve flag; a non-serve holder says gbrain
    const g = fakeTailnet();
    g.deps.pgliteHolder = () => ({ pid: 7, serve: false, command: 'gbrain doctor' });
    expect(await runMcpExpose(['--dry-run', '--json'], g.deps)).toBe(0);
    expect(jsonDoc(g).plan.join('\n')).toContain('(pid 7, gbrain doctor)');
    const g2 = fakeTailnet();
    g2.deps.pgliteHolder = () => ({ pid: 8, serve: false });
    expect(await runMcpExpose(['--dry-run', '--json'], g2.deps)).toBe(0);
    expect(jsonDoc(g2).plan.join('\n')).toContain('(pid 8, gbrain)');
    // our own managed service (receipt present, state running) is expected to hold the lock → no warning
    const h = fakeTailnet();
    expect(await runMcpExpose(['--yes'], h.deps)).toBe(0);
    h.deps.pgliteHolder = () => ({ pid: 4242, serve: true });
    h.stdout.length = 0;
    expect(await runMcpExpose(['--yes', '--json'], h.deps)).toBe(0);
    expect(checkOf(jsonDoc(h), 'pglite_lock')).toBeUndefined();
    // a receipt whose service is stopped does not explain the holder → warn
    const h2 = fakeTailnet();
    writeExposeReceipt(receiptPath(h2.serveDir), fullReceipt(h2, { service: { target: 'linux-systemd', unit_path: null, plist_path: null, wrapper_path: wrapperPath(h2.serveDir), state: 'stopped' } }));
    h2.deps.pgliteHolder = () => ({ pid: 4242, serve: true });
    expect(await runMcpExpose(['--dry-run', '--json'], h2.deps)).toBe(0);
    expect(checkOf(jsonDoc(h2), 'pglite_lock')).toMatchObject({ status: 'warn' });
    // Postgres never consults the probe
    const i = fakeTailnet();
    i.deps.loadConfig = () => ({ engine: 'postgres', database_url: 'postgres://alice-example@localhost/brain' } as never);
    i.deps.pgliteHolder = () => { throw new Error('must not be called'); };
    expect(await runMcpExpose(['--yes', '--json'], i.deps)).toBe(0);
    expect(checkOf(jsonDoc(i), 'pglite_lock')).toBeUndefined();
    // no holder → no warning
    const j = fakeTailnet();
    j.deps.pgliteHolder = () => null;
    expect(await runMcpExpose(['--yes', '--json'], j.deps)).toBe(0);
    expect(checkOf(jsonDoc(j), 'pglite_lock')).toBeUndefined();
  });
  test('the default probe reads the real PGLite lock file (a live pid → warn; absent → nothing) without opening the engine', async () => {
    const f = fakeTailnet();
    const lockDir = join(f.home, 'brain.pglite', '.gbrain-lock');
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(join(lockDir, 'lock'), JSON.stringify({ pid: process.pid, subcommand: 'serve' }));
    expect(await runMcpExpose(['--dry-run', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(checkOf(doc, 'pglite_lock')?.detail).toContain(`(pid ${process.pid}, gbrain serve)`);
    const g = fakeTailnet();
    expect(await runMcpExpose(['--dry-run', '--json'], g.deps)).toBe(0);
    expect(checkOf(jsonDoc(g), 'pglite_lock')).toBeUndefined();
  });
});

describe('scoped off + honest recovery (adversarial-review batch)', () => {
  /** Provoke a throw in the admin-token step AFTER this run published: a symlink where the token file goes. */
  const plantTokenSymlink = (f: Fake) => { mkdirSync(f.serveDir, { recursive: true }); symlinkSync(join(f.home, 'victim'), adminTokenPath(f.serveDir)); };
  const isOff = (argv: string[]) => argv[0] === TS && argv[2] === '--https=443' && argv[3] === '--set-path=/' && argv[4] === 'off';

  test('rollback re-reads serve status after `off`: an exit 0 that leaves the handler in place is NOT turned off (warn); an unreadable re-read is "state unknown" (warn) — never "turned off again"', async () => {
    // off exits 0 but the mount survives (the fake keeps its handler table untouched)
    const f = fakeTailnet();
    plantTokenSymlink(f);
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => (isOff(argv) ? (f.calls.push(argv), { status: 0, stdout: '', stderr: '' }) : inner(argv, o));
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'mcp_expose_failed' });
    expect(doc.message).toContain('NOT turned off (off exited 0 but the handler is still present');
    expect(doc.message).not.toContain('turned off again');
    expect(checkOf(doc, 'rollback')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'rollback')?.detail).toContain('tailscale serve --https=443 --set-path=/ off: NOT turned off');
    const calls = joinedCalls(f);
    expect(calls.indexOf(`${TS} serve --https=443 --set-path=/ off`)).toBeLessThan(calls.lastIndexOf(`${TS} serve status --json`));
    expect(existsSync(receiptPath(f.serveDir))).toBe(false);
    // off exits 0 (and really clears it) but the re-read fails → state unknown, warn
    const g = fakeTailnet();
    plantTokenSymlink(g);
    const ginner = g.deps.run!;
    let offRan = false;
    g.deps.run = async (argv, o) => {
      if (isOff(argv)) offRan = true;
      if (offRan && argv.join(' ') === `${TS} serve status --json`) return { status: 1, stdout: '', stderr: 'Access denied' };
      return ginner(argv, o);
    };
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(1);
    const gdoc = jsonDoc(g);
    expect(gdoc.message).toContain('state unknown (off exited 0 but tailscale serve status could not be re-read');
    expect(checkOf(gdoc, 'rollback')).toMatchObject({ status: 'warn' });
    expect(existsSync(receiptPath(g.serveDir))).toBe(false);
    // the happy rollback still claims "turned off again" only because the re-read shows the port gone
    const h = fakeTailnet();
    plantTokenSymlink(h);
    expect(await runMcpExpose(['--yes', '--json'], h.deps)).toBe(1);
    expect(jsonDoc(h).message).toContain('turned off again');
    expect(joinedCalls(h).filter(c => c === `${TS} serve status --json`).length).toBeGreaterThanOrEqual(3); // before, after publish, after off
  });

  test('--no-tailscale over a receipt that says the brain is published on the tailnet is refused before consent (tailscale_receipt_present); --dry-run marks it; a loopback receipt re-runs fine', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const before = readExposeReceipt(receiptPath(f.serveDir))!;
    f.calls.length = 0;
    f.stdout.length = 0;
    f.fetches.length = 0;
    expect(await runMcpExpose(['--yes', '--no-tailscale', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'tailscale_receipt_present' });
    expect(doc.message).toBe(`This brain is already published on your tailnet at https://${DNS}; run \`gbrain mcp expose --remove --yes\` first, or re-run without --no-tailscale.`);
    expect(checkOf(doc, 'plan')).toMatchObject({ status: 'fail' });
    expect(checkOf(doc, 'plan')?.detail).toContain(`Tailscale REFUSED (--no-tailscale): this brain is already published on your tailnet at https://${DNS}`);
    expect(checkOf(doc, 'consent')).toBeUndefined();
    expect(doc.next_actions).toEqual(['gbrain mcp expose --remove --yes', 'gbrain mcp expose --yes']);
    expect(doc.receipt).toEqual(before);
    expect(readExposeReceipt(receiptPath(f.serveDir))).toEqual(before);
    expect(joinedCalls(f).some(c => c.includes('--bg') || c.startsWith('systemctl --user enable') || c.startsWith('systemctl --user restart'))).toBe(false);
    expect(f.fetches).toEqual([]);
    // --dry-run: the plan shows the refusal, exit 0, nothing changed
    f.stdout.length = 0;
    expect(await runMcpExpose(['--dry-run', '--no-tailscale', '--json'], f.deps)).toBe(0);
    const ddoc = jsonDoc(f);
    expect(ddoc.status).toBe('planned');
    expect(ddoc.plan.join('\n')).toContain('Tailscale WOULD BE REFUSED (--no-tailscale)');
    // a receipt written by --no-tailscale (no dns_name) is not a tailnet mapping → the re-run is allowed
    const g = fakeTailnet();
    expect(await runMcpExpose(['--yes', '--no-tailscale'], g.deps)).toBe(0);
    g.stdout.length = 0;
    expect(await runMcpExpose(['--yes', '--no-tailscale', '--json'], g.deps)).toBe(0);
    expect(jsonDoc(g).status).toBe('exposed');
    // --funnel + --no-tailscale is still an argument conflict, not this refusal
    expect(() => parseExposeArgs(['--funnel', '--no-tailscale'])).toThrow('Conflicting');
  });

  test('funnel -> tailnet switch: Funnel is turned off first; when `serve --bg` then fails (non-zero, unconfirmed) the previous funnel shape is re-published and the receipt kept; a restore that fails says so', async () => {
    const failing = (f: Fake, serveBg: { status: number | null; stdout: string; stderr: string } | 'noop', funnelBgFails = false) => {
      const inner = f.deps.run!;
      f.deps.run = async (argv, o) => {
        if (argv[0] === TS && argv[1] === 'serve' && argv[2] === '--bg') {
          f.calls.push(argv);
          if (serveBg === 'noop') { await inner([TS, 'serve', 'status', '--json']); return { status: 0, stdout: '', stderr: '' }; }
          return serveBg;
        }
        if (funnelBgFails && argv[0] === TS && argv[1] === 'funnel' && argv[2] === '--bg') { f.calls.push(argv); return { status: 1, stdout: '', stderr: 'boom again' }; }
        return inner(argv, o);
      };
    };
    // non-zero publish → restored
    const f = fakeTailnet({ existingHandlers: { 3131: true } });
    writeExposeReceipt(receiptPath(f.serveDir), fullReceipt(f, { mode: 'funnel' }));
    failing(f, { status: 1, stdout: '', stderr: 'boom' });
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc.reason).toBe('tailscale_unknown');
    const calls = joinedCalls(f);
    const preOff = calls.indexOf(`${TS} funnel --https=443 --set-path=/ off`);
    expect(preOff).toBeGreaterThanOrEqual(0);
    expect(preOff).toBeLessThan(calls.indexOf(`${TS} serve --bg 3131`));
    expect(calls.indexOf(`${TS} serve --bg 3131`)).toBeLessThan(calls.indexOf(`${TS} funnel --bg 3131`));
    expect(checkOf(doc, 'tailscale.publish')?.detail).toContain('unknown: boom; the previous funnel handler was restored (tailscale funnel --bg 3131) and the existing receipt kept');
    expect(readExposeReceipt(receiptPath(f.serveDir))?.mode).toBe('funnel');
    const view = JSON.parse((await f.run([TS, 'serve', 'status', '--json'])).stdout);
    expect(JSON.stringify(view.Web)).toContain('127.0.0.1:3131');
    expect(view.AllowFunnel).toEqual({ [`${DNS}:443`]: true });
    // timeout (status null) → restored, and the run-by-hand hint stays
    const t = fakeTailnet({ existingHandlers: { 3131: true } });
    writeExposeReceipt(receiptPath(t.serveDir), fullReceipt(t, { mode: 'funnel' }));
    failing(t, { status: null, stdout: '', stderr: '\n(timed out after 60000ms)' });
    expect(await runMcpExpose(['--yes', '--json'], t.deps)).toBe(1);
    const tdoc = jsonDoc(t);
    expect(tdoc.reason).toBe('tailscale_unknown');
    expect(checkOf(tdoc, 'tailscale.publish')?.detail).toContain('timed out after 60s; the previous funnel handler was restored');
    expect(joinedCalls(t)).toContain(`${TS} funnel --bg 3131`);
    // unconfirmed (exit 0, no handler) → restored
    const u = fakeTailnet({ existingHandlers: { 3131: true } });
    writeExposeReceipt(receiptPath(u.serveDir), fullReceipt(u, { mode: 'funnel' }));
    failing(u, 'noop');
    expect(await runMcpExpose(['--yes', '--json'], u.deps)).toBe(1);
    const udoc = jsonDoc(u);
    expect(udoc.reason).toBe('tailscale_publish_unconfirmed');
    expect(checkOf(udoc, 'tailscale.publish')?.detail).toContain('exited 0 but serve status shows no / handler for port 3131; the previous funnel handler was restored');
    expect(readExposeReceipt(receiptPath(u.serveDir))?.mode).toBe('funnel');
    // the restore itself fails → said plainly, receipt still kept
    const g = fakeTailnet({ existingHandlers: { 3131: true } });
    writeExposeReceipt(receiptPath(g.serveDir), fullReceipt(g, { mode: 'funnel' }));
    failing(g, { status: 1, stdout: '', stderr: 'boom' }, true);
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(1);
    const gdoc = jsonDoc(g);
    expect(checkOf(gdoc, 'tailscale.publish')?.detail).toContain('the previous funnel handler could NOT be restored (tailscale funnel --bg 3131: exit 1) — run `tailscale serve status`; the existing receipt was kept');
    expect(readExposeReceipt(receiptPath(g.serveDir))?.mode).toBe('funnel');
    // no switch (fresh publish) → a failure carries no restore talk and issues no funnel argv at all
    const h = fakeTailnet({ publishStatus: 1, publishStderr: 'boom' });
    expect(await runMcpExpose(['--yes', '--json'], h.deps)).toBe(1);
    expect(checkOf(jsonDoc(h), 'tailscale.publish')?.detail).toBe('unknown: boom');
    expect(joinedCalls(h).some(c => c.includes('funnel'))).toBe(false);
  });

  test('linux login: `sudo` only in front of a system-installed binary — a ~/.local/bin/tailscale found on PATH is refused with tailscale_login_manual (exit 2, no sudo at all)', async () => {
    const f = fakeTailnet({ backendState: 'NeedsLogin' });
    const local = join(f.home, '.local', 'bin', 'tailscale');
    // re-point the fake at the user-local binary: PATH finds it, nothing under the system candidates
    const g = fakeTailnet({ backendState: 'NeedsLogin', binary: local });
    g.deps.which = (n) => (n === 'tailscale' ? local : n === 'systemctl' ? '/usr/bin/systemctl' : n === 'gbrain' ? '/usr/local/bin/gbrain' : null);
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(2);
    const doc = jsonDoc(g);
    expect(doc).toMatchObject({ status: 'pending', reason: 'tailscale_login_manual' });
    // the manual command names the discovered binary (it is outside sudo's secure_path, so a bare `sudo tailscale` would not find it) and says the operator is choosing to trust it
    expect(doc.message).toBe(`tailscale at ${local} 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): \`sudo ${local} set --operator=$USER && sudo ${local} up\`, then re-run: gbrain mcp expose --yes`);
    expect(checkOf(doc, 'tailscale.binary')?.detail).toBe(local);
    expect(checkOf(doc, 'tailscale.login')).toMatchObject({ status: 'pending' });
    expect(checkOf(doc, 'tailscale.login')?.detail).toContain('not a system install');
    expect(doc.next_actions).toEqual([`sudo ${local} set --operator=$USER && sudo ${local} up`, 'gbrain mcp expose --yes']);
    expect(joinedCalls(g).some(c => c.startsWith('sudo'))).toBe(false);
    expect(joinedCalls(g).some(c => c.includes(' up') || c.includes('--bg'))).toBe(false);
    expect(existsSync(g.serveDir)).toBe(false);
    // the system path (/usr/bin/tailscale) keeps the sudo login
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    expect(joinedCalls(f)).toContain(`sudo ${TS} set --operator=alice-example`);
    expect(joinedCalls(f)).toContain(`sudo ${TS} up`);
    // already Running: the guard is never consulted, a user-local binary publishes fine
    const h = fakeTailnet({ binary: local });
    h.deps.which = g.deps.which;
    expect(await runMcpExpose(['--yes', '--json'], h.deps)).toBe(0);
    expect(joinedCalls(h)).toContain(`${local} serve --bg 3131`);
    expect(joinedCalls(h).some(c => c.startsWith('sudo'))).toBe(false);
  });

  test('occupied-port probe counts an accepted TCP connect even when the HTTP fetch rejects (a non-HTTP listener): foreign_listener before anything is published; with --no-service it is "something listens"', async () => {
    const f = fakeTailnet();
    const probes: [string, number, number][] = [];
    f.deps.tcpProbe = async (host, port, timeoutMs) => { probes.push([host, port, timeoutMs]); return true; };
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'foreign_listener' });
    expect(probes).toEqual([['127.0.0.1', 3131, 1500]]);
    expect(f.fetches).toEqual(['http://127.0.0.1:3131/health']); // the fetch still ran (and rejected) — TCP alone decided
    expect(checkOf(doc, 'service')?.detail).toBe('something already answers on 127.0.0.1:3131 (a TCP connect was accepted or http://127.0.0.1:3131/health answered) and no expose receipt claims it');
    expect(f.calls.some(c => c[0] === TS)).toBe(false);
    expect(existsSync(f.serveDir)).toBe(false);
    // a tcpProbe that throws is "not listening", never a crash
    const g = fakeTailnet();
    g.deps.tcpProbe = async () => { throw new Error('probe exploded'); };
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(0);
    // --no-service: the TCP occupant is the operator's server → the local wait runs instead of "Nothing listens"
    const h = fakeTailnet();
    h.deps.tcpProbe = async () => true;
    expect(await runMcpExpose(['--yes', '--no-service', '--json'], h.deps)).toBe(2);
    expect(jsonDoc(h)).toMatchObject({ status: 'pending', reason: 'local_health_timeout' });
    expect(h.stderr.join('\n')).not.toContain('Nothing listens on 127.0.0.1:3131');
    // the help text says so
    expect(MCP_EXPOSE_HELP).toContain('a TCP connect that is accepted');
  });

  test('defaultTcpProbe: true against a real loopback listener, false against a closed port (sockets closed either way)', async () => {
    const server = createServer(c => c.destroy());
    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
    const port = (server.address() as { port: number }).port;
    try {
      expect(await defaultTcpProbe('127.0.0.1', port, 2_000)).toBe(true);
    } finally {
      await new Promise<void>(resolve => server.close(() => resolve()));
    }
    expect(await defaultTcpProbe('127.0.0.1', port, 2_000)).toBe(false);
  });

  test('--status without a receipt probes for leftovers: wrapper + unit + handler → one warn check each, exit 1 leftovers_without_receipt with the recovery command; a handler alone → --force; nothing → not_exposed', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    rmSync(receiptPath(f.serveDir));
    f.calls.length = 0;
    f.stdout.length = 0;
    f.fetches.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'leftovers_without_receipt' });
    expect(checkOf(doc, 'receipt')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'receipt')?.detail).toContain('leftovers of an interrupted publish');
    expect(checkOf(doc, 'service')).toMatchObject({ status: 'warn', detail: 'systemd (user) gbrain-serve.service is installed (running) without a receipt' });
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'warn', detail: 'a :443 handler proxies http://127.0.0.1:3131 without a receipt' });
    expect(checkOf(doc, 'files')).toMatchObject({ status: 'warn', detail: 'wrapper ~/.gbrain/serve/gbrain-serve.sh exists without a receipt' });
    expect(doc.next_actions).toEqual(['gbrain mcp expose --remove --yes']);
    expect(doc.message).toContain('run gbrain mcp expose --remove --yes');
    expect(f.fetches).toEqual([]); // read-only probes, no health fetches
    expect(joinedCalls(f).every(c => c === 'systemctl --user is-system-running' || c === 'systemctl --user is-active gbrain-serve.service' || c === `${TS} serve status --json`)).toBe(true);
    expect(f.stderr.join('\n')).toContain('Clean up: gbrain mcp expose --remove --yes');
    // human mode exits 1 too
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status'], f.deps)).toBe(1);
    expect(f.stdout.join('\n')).toContain('an interrupted `gbrain mcp expose` left these behind');
    // and the suggested command really cleans it up → then the plain not_exposed
    expect(await runMcpExpose(['--remove', '--yes'], f.deps)).toBe(0);
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(2);
    expect(jsonDoc(f)).toMatchObject({ status: 'not_exposed', reason: 'not_exposed' });
    // a handler alone (nothing else of gbrain's) → --force in the recovery command; --port is honored
    const g = fakeTailnet({ existingHandlers: { 4000: true } });
    expect(await runMcpExpose(['--status', '--port', '4000', '--json'], g.deps)).toBe(1);
    const gdoc = jsonDoc(g);
    expect(gdoc.reason).toBe('leftovers_without_receipt');
    expect(checkOf(gdoc, 'tailscale.publish')?.detail).toBe('a :443 handler proxies http://127.0.0.1:4000 (funnel) without a receipt');
    expect(checkOf(gdoc, 'service')).toBeUndefined();
    expect(checkOf(gdoc, 'files')).toBeUndefined();
    expect(gdoc.next_actions).toEqual(['gbrain mcp expose --remove --yes --force --port 4000']);
    // the default port does not see a handler for another port
    g.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], g.deps)).toBe(2);
    expect(jsonDoc(g)).toMatchObject({ status: 'not_exposed' });
    // an unreadable serve status alone is a caveat, not a leftover
    const h = fakeTailnet();
    const hinner = h.deps.run!;
    h.deps.run = async (argv, o) => (argv.join(' ') === `${TS} serve status --json` ? { status: 1, stdout: '', stderr: 'Access denied' } : hinner(argv, o));
    expect(await runMcpExpose(['--status', '--json'], h.deps)).toBe(2);
    const hdoc = jsonDoc(h);
    expect(hdoc).toMatchObject({ status: 'not_exposed' });
    expect(checkOf(hdoc, 'tailscale.publish')?.detail).toContain('could not be checked');
  });

  test('darwin --remove: a launchd bootout that fails for a real reason is a service warn and "the launchd job (bootout failed)" is left in place — with a receipt and without one', async () => {
    const f = fakeMac();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => (argv.join(' ').startsWith('launchctl bootout gui/') ? (f.calls.push(argv), { status: 1, stdout: '', stderr: 'Boot-out failed: 1: Operation not permitted' }) : inner(argv, o));
    f.calls.length = 0;
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('removed');
    expect(checkOf(doc, 'service')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'service')?.detail).toContain(`removed ${f.deps.plistPath}; launchctl bootout failed, so the job may still be loaded — check \`launchctl print gui/$(id -u)/com.gbrain.serve\``);
    expect(f.stderr.join('\n')).toContain('Note: launchctl bootout failed: Boot-out failed: 1: Operation not permitted');
    expect(f.stderr.join('\n')).toContain('Left in place: the launchd job (bootout failed);');
    expect(existsSync(f.deps.plistPath!)).toBe(false);
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'ok' });
    // the benign "not loaded" answer (the fake's default once the job is down) stays silent
    const g = fakeMac();
    expect(await runMcpExpose(['--yes'], g.deps)).toBe(0);
    g.stopService();
    g.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], g.deps)).toBe(0);
    expect(checkOf(jsonDoc(g), 'service')).toMatchObject({ status: 'ok' });
    expect(g.stderr.join('\n')).not.toContain('bootout failed');
    // receipt-less recovery reports it the same way, and the handler-not-removed message quotes the truthful service summary
    const h = fakeMac();
    expect(await runMcpExpose(['--yes'], h.deps)).toBe(0);
    rmSync(receiptPath(h.serveDir));
    const hinner = h.deps.run!;
    h.deps.run = async (argv, o) => {
      if (argv.join(' ').startsWith('launchctl bootout gui/')) return { status: 1, stdout: '', stderr: 'Boot-out failed: 1: Operation not permitted' };
      if (argv[0] === APP_TS && argv[2] === '--https=443' && argv[3] === '--set-path=/' && argv[4] === 'off') return { status: 1, stdout: '', stderr: 'nope' };
      return hinner(argv, o);
    };
    h.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], h.deps)).toBe(1);
    const hdoc = jsonDoc(h);
    expect(hdoc).toMatchObject({ status: 'error', reason: 'handler_not_removed' });
    expect(checkOf(hdoc, 'service')).toMatchObject({ status: 'warn' });
    expect(checkOf(hdoc, 'files')).toMatchObject({ status: 'skipped' });
    expect(checkOf(hdoc, 'files')?.detail).toContain('kept: the wrapper');
    expect(hdoc.next_actions).toEqual(['tailscale serve status', 'gbrain mcp expose --remove --yes']);
    expect(h.stderr.join('\n')).toContain('Stopped here: the service files were removed but the launchd bootout failed, but the tailscale handler for port 3131 is still present. Left in place: the wrapper.');
    expect(existsSync(wrapperPath(h.serveDir))).toBe(true);
    expect(existsSync(h.deps.plistPath!)).toBe(false);
  });

  test('receipt-less --remove with a surviving handler keeps the wrapper (corroboration for the re-run) and exits 1 handler_not_removed; without a wrapper the re-run hint carries --force', async () => {
    const f = fakeTailnet();
    expect(await runMcpExpose(['--yes'], f.deps)).toBe(0);
    rmSync(receiptPath(f.serveDir));
    const inner = f.deps.run!;
    f.deps.run = async (argv, o) => (isOff(argv) ? { status: 1, stdout: '', stderr: 'nope' } : inner(argv, o));
    f.stdout.length = 0;
    expect(await runMcpExpose(['--remove', '--yes', '--json'], f.deps)).toBe(1);
    const doc = jsonDoc(f);
    expect(doc).toMatchObject({ status: 'error', reason: 'handler_not_removed', receipt: null });
    expect(checkOf(doc, 'service')).toMatchObject({ status: 'ok' });
    expect(checkOf(doc, 'tailscale.publish')).toMatchObject({ status: 'fail' });
    expect(checkOf(doc, 'files')?.detail).toContain('kept: the wrapper');
    expect(doc.next_actions).toEqual(['tailscale serve status', 'gbrain mcp expose --remove --yes']);
    expect(existsSync(wrapperPath(f.serveDir))).toBe(true);
    expect(existsSync(f.deps.unitPath!)).toBe(false);
    // handler + --force, no wrapper: nothing to keep, the re-run needs --force again
    const g = fakeTailnet({ existingHandlers: { 3131: false } });
    const ginner = g.deps.run!;
    g.deps.run = async (argv, o) => (isOff(argv) ? { status: 1, stdout: '', stderr: 'nope' } : ginner(argv, o));
    expect(await runMcpExpose(['--remove', '--yes', '--force', '--json'], g.deps)).toBe(1);
    const gdoc = jsonDoc(g);
    expect(gdoc.reason).toBe('handler_not_removed');
    expect(gdoc.message).toBe('the tailscale handler for port 3131 is still present; left in place: nothing (no wrapper was found)');
    expect(gdoc.next_actions).toEqual(['tailscale serve status', 'gbrain mcp expose --remove --yes --force']);
    expect(g.stderr.join('\n')).toContain('Stopped here: no service was found, but the tailscale handler for port 3131 is still present.');
  });

  test('tailnet verify: a name-resolution failure is a warn ("this host cannot resolve …", MagicDNS hint) and exit 0 — on publish and on --status; other rejections keep the pending semantics', async () => {
    const f = fakeTailnet();
    const inner = f.deps.fetch!;
    f.deps.fetch = async (url, init) => (url.startsWith('https://') ? Promise.reject(new Error(`getaddrinfo ENOTFOUND ${DNS}`)) : inner(url, init));
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('exposed');
    expect(doc.reason).toBeUndefined();
    expect(checkOf(doc, 'verify.tailnet')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'verify.tailnet')?.detail).toBe(`https://${DNS}/health: this host cannot resolve ${DNS} (MagicDNS may be off here: \`tailscale set --accept-dns=true\`); devices that do resolve it may already reach the server`);
    expect(f.stderr.join('\n')).toContain(`Health    https://${DNS}/health: this host cannot resolve ${DNS}`);
    expect(f.stderr.join('\n')).not.toContain('still pending');
    expect(existsSync(receiptPath(f.serveDir))).toBe(true);
    // --status: same warn, exit 0 when everything else verifies
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(0);
    const sdoc = jsonDoc(f);
    expect(sdoc.status).toBe('exposed');
    expect(checkOf(sdoc, 'verify.tailnet')).toMatchObject({ status: 'warn' });
    expect(checkOf(sdoc, 'verify.tailnet')?.detail).toContain(`this host cannot resolve ${DNS}`);
    // the other spellings classify too
    for (const msg of ['fetch failed: EAI_AGAIN', 'Unable to connect. Is the computer able to access the url? failed to resolve host', 'Failed to resolve hostname']) {
      const g = fakeTailnet();
      const ginner = g.deps.fetch!;
      g.deps.fetch = async (url, init) => (url.startsWith('https://') ? Promise.reject(new Error(msg)) : ginner(url, init));
      expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(0);
      expect(checkOf(jsonDoc(g), 'verify.tailnet')?.status).toBe('warn');
    }
    // a refused / pending certificate is still `pending`, exit 2 (publish) and exit 1 (--status)
    const h = fakeTailnet({ tailnetHealthy: false });
    expect(await runMcpExpose(['--yes', '--json'], h.deps)).toBe(2);
    expect(jsonDoc(h)).toMatchObject({ status: 'pending', reason: 'tailnet_health_pending' });
    h.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], h.deps)).toBe(1);
    expect(jsonDoc(h)).toMatchObject({ status: 'pending', reason: 'tailnet_health_pending' });
  });

  test('tailnet verify under Bun: fetch rejects an unresolvable name EXACTLY like a refused connection, so the resolver decides — lookup ENOTFOUND is the warn (exit 0, publish and --status), a resolving lookup keeps pending, only classified codes count', async () => {
    // Bun 1.x: both an unresolvable host and a refused connection reject with this message / code, so no message match can tell them apart.
    const bunReject = () => Object.assign(new Error('Unable to connect. Is the computer able to access the url?'), { code: 'ConnectionRefused' });
    // (a) lookup says ENOTFOUND → this host cannot resolve the name → warn, exit 0
    const f = fakeTailnet();
    const inner = f.deps.fetch!;
    const looked: string[] = [];
    f.deps.fetch = async (url, init) => (url.startsWith('https://') ? Promise.reject(bunReject()) : inner(url, init));
    f.deps.lookup = async (host) => { looked.push(host); throw Object.assign(new Error('getaddrinfo ENOTFOUND'), { code: 'ENOTFOUND', syscall: 'getaddrinfo' }); };
    expect(await runMcpExpose(['--yes', '--json'], f.deps)).toBe(0);
    const doc = jsonDoc(f);
    expect(doc.status).toBe('exposed');
    expect(doc.reason).toBeUndefined();
    expect(checkOf(doc, 'verify.tailnet')).toMatchObject({ status: 'warn' });
    expect(checkOf(doc, 'verify.tailnet')?.detail).toBe(`https://${DNS}/health: this host cannot resolve ${DNS} (MagicDNS may be off here: \`tailscale set --accept-dns=true\`); devices that do resolve it may already reach the server`);
    // only the tailnet name reaches the resolver — the loopback probes (IP literal) never do
    expect(looked.length).toBeGreaterThan(0);
    expect([...new Set(looked)]).toEqual([DNS]);
    f.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], f.deps)).toBe(0);
    const sdoc = jsonDoc(f);
    expect(sdoc.status).toBe('exposed');
    expect(checkOf(sdoc, 'verify.tailnet')).toMatchObject({ status: 'warn' });
    expect(checkOf(sdoc, 'verify.tailnet')?.detail).toContain(`this host cannot resolve ${DNS}`);
    // (b) the same fetch failure while the name DOES resolve is a real "not reachable yet": pending (exit 2 on publish, 1 on --status)
    const g = fakeTailnet();
    const ginner = g.deps.fetch!;
    g.deps.fetch = async (url, init) => (url.startsWith('https://') ? Promise.reject(bunReject()) : ginner(url, init));
    g.deps.lookup = async () => {};
    expect(await runMcpExpose(['--yes', '--json'], g.deps)).toBe(2);
    const gdoc = jsonDoc(g);
    expect(gdoc).toMatchObject({ status: 'pending', reason: 'tailnet_health_pending' });
    expect(checkOf(gdoc, 'verify.tailnet')).toMatchObject({ status: 'pending' });
    g.stdout.length = 0;
    expect(await runMcpExpose(['--status', '--json'], g.deps)).toBe(1);
    expect(jsonDoc(g)).toMatchObject({ status: 'pending', reason: 'tailnet_health_pending' });
    // a resolver error that is NOT a resolution failure (a SERVFAIL, a cancelled query) proves nothing → still pending
    const k = fakeTailnet();
    const kinner = k.deps.fetch!;
    k.deps.fetch = async (url, init) => (url.startsWith('https://') ? Promise.reject(bunReject()) : kinner(url, init));
    k.deps.lookup = async () => { throw Object.assign(new Error('queryA ESERVFAIL'), { code: 'ESERVFAIL' }); };
    expect(await runMcpExpose(['--yes', '--json'], k.deps)).toBe(2);
    expect(jsonDoc(k)).toMatchObject({ status: 'pending', reason: 'tailnet_health_pending' });
    // the classifier: the resolver's code first, its message tokens second
    for (const code of ['ENOTFOUND', 'EAI_AGAIN', 'EAI_NONAME', 'EAI_NODATA', 'DNS_ENOTFOUND']) expect(isUnresolvedLookupError(Object.assign(new Error('x'), { code }))).toBe(true);
    expect(isUnresolvedLookupError(new Error('getaddrinfo EAI_AGAIN your-machine.your-tailnet.ts.net'))).toBe(true);
    expect(isUnresolvedLookupError(Object.assign(new Error('queryA ESERVFAIL'), { code: 'ESERVFAIL' }))).toBe(false);
    expect(isUnresolvedLookupError(new Error('Unable to connect. Is the computer able to access the url?'))).toBe(false);
  });

  test('the default resolver rejects reserved invalid names without consulting system DNS', async () => {
    const lookup = spyOn(dnsPromises, 'lookup').mockResolvedValue({ address: '127.0.0.1', family: 4 });
    try {
      for (const host of ['invalid', 'INVALID', 'invalid.', 'INVALID.', 'gbrain.invalid', 'gbrain.INVALID.', 'nested.gbrain.invalid.']) {
        await expect(defaultLookup(host)).rejects.toMatchObject({ code: 'ENOTFOUND' });
      }
      expect(lookup).not.toHaveBeenCalled();
    } finally {
      lookup.mockRestore();
    }
  });

  test('the default resolver preserves invalid label boundaries and delegates other names', async () => {
    const lookup = spyOn(dnsPromises, 'lookup').mockResolvedValue({ address: '127.0.0.1', family: 4 });
    const hosts = ['notinvalid', 'notinvalid.', 'gbrain.notinvalid', 'invalid.example', 'gbrain.invalid.example', 'invalid.example.'];
    try {
      for (const host of hosts) await expect(defaultLookup(host)).resolves.toBeUndefined();
      expect(lookup.mock.calls.map(([host]) => host)).toEqual(hosts);
    } finally {
      lookup.mockRestore();
    }
  });

  test('the default resolver still resolves localhost through the system resolver', async () => {
    await expect(defaultLookup('localhost')).resolves.toBeUndefined();
  });

  test('an unanswered lookup and unclassified resolver errors remain unknown', async () => {
    const deps = {
      fetch: async () => { throw Object.assign(new Error('Unable to connect. Is the computer able to access the url?'), { code: 'ConnectionRefused' }); },
      tcpProbe: async () => false,
      lookup: async () => new Promise<void>(() => {}),
      now: () => new Date(), sleep: async () => {}, healthIntervalMs: 1,
    };
    const url = 'https://diagnostic.example/health';
    expect(await tryFetch(deps, url, 25)).toEqual({ res: null, unresolved: false });
    for (const code of ['ETIMEDOUT', 'ESERVFAIL', 'ECANCELLED']) {
      expect(await tryFetch({ ...deps, lookup: async () => { throw Object.assign(new Error(code), { code }); } }, url, 25))
        .toEqual({ res: null, unresolved: false });
    }
  });

  test('the real default resolver: a .invalid name never resolves (RFC 6761; a resolver outage classifies as unresolved too), so Bun\'s refused-looking rejection is reported as unresolved', async () => {
    const url = 'https://gbrain-unresolvable-test.invalid/health';
    const outcome = await tryFetch({
      fetch: async () => { throw Object.assign(new Error('Unable to connect. Is the computer able to access the url?'), { code: 'ConnectionRefused' }); },
      tcpProbe: async () => false,
      lookup: defaultLookup,
      now: () => new Date(), sleep: async () => {}, healthIntervalMs: 1,
    }, url, 10_000);
    expect(outcome).toEqual({ res: null, unresolved: true });
    // and the same rejection for an IP literal / localhost never consults the resolver (no unresolved verdict)
    const probeDeps = { fetch: async () => { throw new Error('Unable to connect. Is the computer able to access the url?'); }, tcpProbe: async () => false, lookup: async () => { throw new Error('must not be consulted for an IP literal or localhost'); }, now: () => new Date(), sleep: async () => {}, healthIntervalMs: 1 };
    expect(await tryFetch(probeDeps, 'http://127.0.0.1:3131/health', 1_000)).toEqual({ res: null, unresolved: false });
    expect(await tryFetch(probeDeps, 'http://[::1]:3131/health', 1_000)).toEqual({ res: null, unresolved: false });
    expect(await tryFetch(probeDeps, 'http://localhost:3131/health', 1_000)).toEqual({ res: null, unresolved: false });
  }, 15_000);
});