Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Persistent user service for `gbrain serve --http` — installed by
* `gbrain mcp expose`, torn down by `--remove`.
*
* Mirrors the hardening of the autopilot installer (src/commands/autopilot.ts)
* without importing it: single-quote-escaped paths in the wrapper, plist
* normalized to 0644 (launchd rejects group-writable agents), domain-explicit
* `launchctl bootout gui/<uid>` before `bootstrap gui/<uid>` (launchd; the
* legacy `unload`/`load` pair only when the installed launchctl does not know
* the modern verbs; a bootstrap that fails while launchd is still unloading
* the old job is retried with a pause) / enable + restart (systemd) so a
* reinstall relaunches the
* job, the running bun's directory prepended to PATH (rc files bail early
* under a supervisor), `~/.gbrain/env`
* sourced with `set -a`, and the admin token read from its 0600 file at RUN
* time — the secret never lands in the plist, unit, or wrapper.
*
* Every filesystem and exec effect goes through injectable paths / a
* `CommandRunner`, so tests run in a tmpdir with a fake runner and never touch
* `process.env`.
*
* Every file this module writes or reads under `~/.gbrain/serve` (token,
* wrapper, receipt) refuses a symlink at the target path: a planted link could
* otherwise redirect a 0600 secret or a 0755 executable somewhere else.
*/
import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
import { dirname, join, resolve as resolvePath } from 'node:path';
import { fileURLToPath } from 'node:url';
import { randomBytes } from 'node:crypto';
import { gbrainPath } from './config.ts';
import { shellQuote } from './mcp-registration.ts';
import type { ExecutionEnvironment } from './execution-env.ts';
import type { CommandResult, CommandRunner } from './tailscale.ts';
export const SERVE_LAUNCHD_LABEL = 'com.gbrain.serve';
export const SERVE_SYSTEMD_UNIT = 'gbrain-serve.service';
export type ServiceTarget = 'macos' | 'linux-systemd' | 'none';
// ---------------------------------------------------------------------------
// Paths (all under gbrainPath('serve') so GBRAIN_HOME is honored)
// ---------------------------------------------------------------------------
export function serveDir(): string { return gbrainPath('serve'); }
export function adminTokenPath(dir: string = serveDir()): string { return join(dir, 'admin-token'); }
export function wrapperPath(dir: string = serveDir()): string { return join(dir, 'gbrain-serve.sh'); }
export function receiptPath(dir: string = serveDir()): string { return join(dir, 'expose.json'); }
export function serveLogPath(dir: string = serveDir()): string { return join(dir, 'serve.log'); }
export function serveErrPath(dir: string = serveDir()): string { return join(dir, 'serve.err'); }
export function launchdPlistPath(home: string): string { return join(home, 'Library', 'LaunchAgents', `${SERVE_LAUNCHD_LABEL}.plist`); }
export function systemdUnitPath(home: string): string { return join(home, '.config', 'systemd', 'user', SERVE_SYSTEMD_UNIT); }
/** The installed serve service's restart command on this platform; null when no serve service is installed. */
export function serveServiceRestartArgv(service: { platform: string; home: string; uid: number }): string[] | null {
if (service.platform === 'darwin' && existsSync(launchdPlistPath(service.home))) return ['launchctl', 'kickstart', '-k', `gui/${service.uid}/${SERVE_LAUNCHD_LABEL}`];
if (service.platform === 'linux' && existsSync(systemdUnitPath(service.home))) return ['systemctl', '--user', 'restart', SERVE_SYSTEMD_UNIT];
return null;
}
/**
* True when the installed serve service starts `wrapper` (this brain's `wrapperPath()` by default). The launchd
* label and the systemd unit are one per OS user, so on a host with several brains the service may start another
* GBRAIN_HOME's wrapper; false then, and for a missing or unreadable service file.
*/
export function serveServiceRunsWrapper(platform: string, home: string, wrapper: string = wrapperPath()): boolean {
try {
if (platform === 'darwin') return readFileSync(launchdPlistPath(home), 'utf8').includes(`<string>${escapeXml(wrapper)}</string>`);
if (platform === 'linux') return readFileSync(systemdUnitPath(home), 'utf8').split('\n').includes(`ExecStart=${systemdArg(wrapper)}`);
} catch { /* no readable service file: not this brain's */ }
return false;
}
// ---------------------------------------------------------------------------
// Target detection (pure — probe results are passed in)
// ---------------------------------------------------------------------------
export interface ServiceTargetSignals {
platform: string;
executionEnv: ExecutionEnvironment;
/** Result of `systemctl --user is-system-running` (null: not probed / no systemctl). */
userBus?: { status: number | null; stdout: string } | null;
}
/**
* - darwin → launchd user agent, always.
* - anything that is not a normal machine (cloud sandbox, ephemeral
* container) → none: no supervisor survives there.
* - linux with a WORKING user bus (`is-system-running` exits 0 or reports
* running/degraded) → systemd user unit.
* - otherwise none (the caller prints the manual recipe).
*/
export function detectServiceTarget(signals: ServiceTargetSignals): ServiceTarget {
if (signals.platform === 'darwin') return 'macos';
if (signals.executionEnv !== 'local') return 'none';
if (signals.platform !== 'linux') return 'none';
const bus = signals.userBus;
if (!bus) return 'none';
if (bus.status === 0) return 'linux-systemd';
if (/\b(running|degraded)\b/i.test(bus.stdout)) return 'linux-systemd';
return 'none';
}
export const SYSTEMCTL_USER_BUS_PROBE_ARGV: readonly string[] = ['systemctl', '--user', 'is-system-running'];
// ---------------------------------------------------------------------------
// Symlink refusal (shared by every write/read under the serve dir)
// ---------------------------------------------------------------------------
/** Throws a clear error when `path` exists AND is a symlink; a missing path is fine. */
export function refuseSymlink(path: string, what: string): void {
let link = false;
try { link = lstatSync(path).isSymbolicLink(); } catch { return; }
if (link) throw new Error(`refusing to use ${what} at ${path}: it is a symlink (remove it and re-run)`);
}
// ---------------------------------------------------------------------------
// gbrain CLI resolution for the wrapper
// ---------------------------------------------------------------------------
export interface ResolveGbrainCommandDeps {
which?: (name: string) => string | null;
execPath?: string;
argv1?: string;
/** `import.meta.url` of this module (a compiled binary reports a `/$bunfs/` path). */
metaUrl?: string;
fileExists?: (path: string) => boolean;
}
/** Bun's own runtime binary (`bun`, `bun-profile`, `bun.exe`), as opposed to a compiled gbrain. */
const BUN_RUNTIME_RE = /(^|[\\/])bun(-[a-z0-9-]+)?(\.exe)?$/i;
/** A compiled binary's embedded entrypoint: `/$bunfs/root/...` (POSIX) or `B:\~BUN\...` (Windows). */
const VIRTUAL_ENTRY_RE = /\$bunfs|~BUN/;
/**
* argv prefix baked into the wrapper: `[<gbrain shim>]`, or `[<execPath>]`
* when the running binary is a compiled gbrain (whatever its basename — a
* compiled Bun binary reports its embedded sources under `/$bunfs/` and has
* no real script in `argv[1]`), else `[<bun>, <abs cli.ts>]` when that
* `cli.ts` exists on disk; without it, `[<execPath>]` again rather than a
* path that cannot run. The wrapper falls back to `type -P gbrain` at run
* time when argv[0] is gone.
*/
export function resolveServeGbrainCommand(deps: ResolveGbrainCommandDeps = {}): string[] {
const which = deps.which ?? ((name: string) => { try { return Bun.which(name, { PATH: process.env.PATH ?? '' }); } catch { return null; } });
const onPath = which('gbrain');
if (onPath) return [onPath];
const exec = deps.execPath ?? process.execPath ?? '';
const arg1 = deps.argv1 ?? process.argv[1] ?? '';
const metaUrl = deps.metaUrl ?? import.meta.url;
const fileExists = deps.fileExists ?? ((p: string) => { try { return existsSync(p); } catch { return false; } });
const compiled = VIRTUAL_ENTRY_RE.test(metaUrl) || (!!exec && !BUN_RUNTIME_RE.test(exec) && (!arg1 || VIRTUAL_ENTRY_RE.test(arg1)));
if (compiled && exec) return [exec];
if (exec.endsWith('/gbrain') || exec.endsWith('\\gbrain.exe')) return [exec];
if (arg1.endsWith('/gbrain') || arg1.endsWith('\\gbrain.exe')) return [arg1];
let cliTs: string | null = null;
try { cliTs = resolvePath(dirname(fileURLToPath(metaUrl)), '..', 'cli.ts'); } catch { cliTs = null; }
if (cliTs && fileExists(cliTs)) return [exec || 'bun', cliTs];
return [exec || 'bun'];
}
// ---------------------------------------------------------------------------
// Renderers
// ---------------------------------------------------------------------------
export interface ServeCommandParams {
port: number;
publicUrl: string;
surface?: 'verbs' | 'starter' | 'full';
/** `serve --advertise`: what tools/list shows clients without their own surface. */
advertise?: 'verbs' | 'starter' | 'full' | null;
enableDcr?: boolean;
}
/** `serve --http --port N --public-url URL [--surface X] [--advertise Y] [--enable-dcr]` as argv. */
export function serveCommandArgv(p: ServeCommandParams): string[] {
const argv = ['serve', '--http', '--port', String(p.port), '--public-url', p.publicUrl];
if (p.surface) argv.push('--surface', p.surface);
if (p.advertise) argv.push('--advertise', p.advertise);
if (p.enableDcr) argv.push('--enable-dcr');
return argv;
}
export interface WrapperParams extends ServeCommandParams {
/** From resolveServeGbrainCommand: `[gbrain]` or `[bun, cli.ts]`. */
gbrainCommand: string[];
adminTokenPath: string;
/** `~/.gbrain/env` (absolute). */
gbrainEnvFile: string;
/** Installer's GBRAIN_HOME, baked when present (the supervisor passes no env). */
gbrainHome?: string;
/** Directory of the running bun (dirname(process.execPath)); '' skips the prefix. */
runtimeDir?: string;
}
const sq = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
export function renderServeWrapper(p: WrapperParams): string {
const serveArgs = serveCommandArgv(p).map(shellQuote).join(' ');
const [program, ...programArgs] = p.gbrainCommand;
const programTail = programArgs.map(sq).join(' ');
const runtimeDir = p.runtimeDir ?? '';
const runtimePrefix = runtimeDir && runtimeDir !== '.' ? `${sq(runtimeDir)}:` : '';
const homeLine = p.gbrainHome
? `# Baked at install: the supervisor does not pass the installer's env.\nexport GBRAIN_HOME=${sq(p.gbrainHome)}\n`
: '';
return `#!/bin/bash
# Auto-generated by \`gbrain mcp expose\` — runs the gbrain MCP server under the
# user service. Re-run \`gbrain mcp expose\` to regenerate; \`--remove\` deletes it.
# Shell profiles are sourced best-effort for API keys (zshenv first: it is the
# only zsh file non-interactive shells read).
[ -f ~/.zshenv ] && source ~/.zshenv 2>/dev/null
[ -f ~/.zshrc ] && source ~/.zshrc 2>/dev/null
[ -f ~/.bashrc ] && source ~/.bashrc 2>/dev/null
# gbrain-owned env file (KEY=value lines, auto-exported), sourced last so it wins.
[ -f ${sq(p.gbrainEnvFile)} ] && { set -a; source ${sq(p.gbrainEnvFile)} 2>/dev/null; set +a; }
# rc files bail early under a supervisor, so put the running bun on PATH ourselves.
export PATH=${runtimePrefix}"$HOME/.bun/bin:$PATH"
${homeLine}# The admin token is read from its 0600 file at RUN time; it never lands in
# this wrapper, the plist, or the unit.
if [ ! -r ${sq(p.adminTokenPath)} ]; then
echo "$(date -u +%FT%TZ) [gbrain-serve] admin token file missing or unreadable:" ${sq(p.adminTokenPath)} "- re-run: gbrain mcp expose" >&2
exit 1
fi
GBRAIN_ADMIN_BOOTSTRAP_TOKEN="$(cat ${sq(p.adminTokenPath)})"
export GBRAIN_ADMIN_BOOTSTRAP_TOKEN
cd "$HOME"
_gbrain=${sq(program)}
if [ ! -x "$_gbrain" ]; then
_resolved=$(type -P gbrain 2>/dev/null)
if [ -n "$_resolved" ]; then
echo "$(date -u +%FT%TZ) [gbrain-serve] baked CLI path is gone:" ${sq(program)} "- using $_resolved"
exec "$_resolved" ${serveArgs}
fi
echo "$(date -u +%FT%TZ) [gbrain-serve] gbrain CLI not found at" ${sq(program)} "nor on PATH; re-run: gbrain mcp expose" >&2
exit 1
fi
exec "$_gbrain"${programTail ? ` ${programTail}` : ''} ${serveArgs}
`;
}
export function escapeXml(s: string): string {
return s.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, ''');
}
export interface LaunchdParams { wrapperPath: string; home: string; logPath: string; errPath: string }
export function renderServeLaunchdPlist(p: LaunchdParams): string {
return `<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>${escapeXml(SERVE_LAUNCHD_LABEL)}</string>
<key>ProgramArguments</key><array>
<string>${escapeXml(p.wrapperPath)}</string>
</array>
<key>WorkingDirectory</key><string>${escapeXml(p.home)}</string>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>ThrottleInterval</key><integer>30</integer>
<key>StandardOutPath</key><string>${escapeXml(p.logPath)}</string>
<key>StandardErrorPath</key><string>${escapeXml(p.errPath)}</string>
</dict>
</plist>
`;
}
export interface SystemdParams { wrapperPath: string; logPath: string; errPath: string }
/** systemd specifier escaping (`%h` etc. expand in every path-like setting): `%` → `%%`. */
export function systemdSpecifierEscape(s: string): string {
return s.replace(/%/g, '%%');
}
/**
* ExecStart quoting: `%` → `%%` (specifiers), `$` → `$$` (environment
* expansion), then double-quote when the path carries whitespace or quotes.
*/
export function systemdArg(s: string): string {
const escaped = systemdSpecifierEscape(s).replace(/\$/g, '$$$$');
return /[\s"'\\]/.test(escaped) ? `"${escaped.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"` : escaped;
}
export function renderServeSystemdUnit(p: SystemdParams): string {
return `[Unit]
Description=GBrain MCP server (gbrain serve --http)
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=300
StartLimitBurst=10
[Service]
Type=simple
ExecStart=${systemdArg(p.wrapperPath)}
Restart=always
RestartSec=10
StandardOutput=append:${systemdSpecifierEscape(p.logPath)}
StandardError=append:${systemdSpecifierEscape(p.errPath)}
[Install]
WantedBy=default.target
`;
}
// ---------------------------------------------------------------------------
// Admin token
// ---------------------------------------------------------------------------
export const ADMIN_TOKEN_SHAPE = /^[A-Za-z0-9_-]{32,}$/;
export interface EnsureAdminTokenResult {
path: string;
/** 'created' (no file), 'reused' (valid file), 'regenerated' (file present but malformed). */
action: 'created' | 'reused' | 'regenerated';
}
/** `openSync(path, 'wx', 0o600)`: the file is born 0600 and never exists briefly with looser bits. */
function writeTokenExclusive(path: string, token: string): void {
const fd = openSync(path, 'wx', 0o600);
try { writeSync(fd, `${token}\n`); } finally { closeSync(fd); }
chmodSync(path, 0o600);
}
/**
* Ensure `path` holds a token `resolveBootstrapToken` accepts (dir 0700,
* file 0600, 64 hex chars from 32 random bytes). Reuses a valid file so the
* dashboard session survives re-runs; regenerates a malformed one
* (unlink + exclusive recreate). Refuses a symlink at `path`. Never returns
* the token itself.
*/
export function ensureAdminToken(path: string, deps: { randomHex?: () => string } = {}): EnsureAdminTokenResult {
const randomHex = deps.randomHex ?? (() => randomBytes(32).toString('hex'));
refuseSymlink(path, 'the admin token file');
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
try { chmodSync(dirname(path), 0o700); } catch { /* best effort */ }
const readCurrent = (): string => { try { return readFileSync(path, 'utf-8').trim(); } catch { return ''; } };
let action: EnsureAdminTokenResult['action'] = 'created';
if (existsSync(path)) {
if (ADMIN_TOKEN_SHAPE.test(readCurrent())) {
try { chmodSync(path, 0o600); } catch { /* best effort */ }
return { path, action: 'reused' };
}
action = 'regenerated';
unlinkSync(path);
}
try {
writeTokenExclusive(path, randomHex());
} catch (error) {
// Lost a race with a concurrent writer: a valid token that appeared in the
// meantime is reused; anything else is replaced.
if (!(error instanceof Error && 'code' in error && (error as NodeJS.ErrnoException).code === 'EEXIST')) throw error;
if (ADMIN_TOKEN_SHAPE.test(readCurrent())) return { path, action: 'reused' };
unlinkSync(path);
writeTokenExclusive(path, randomHex());
action = 'regenerated';
}
return { path, action };
}
// ---------------------------------------------------------------------------
// Install / uninstall / state
// ---------------------------------------------------------------------------
export type ServiceState = 'running' | 'loaded' | 'stopped' | 'not-installed' | 'manual' | 'unknown';
export interface InstallServiceParams {
target: ServiceTarget;
wrapperPath: string;
wrapperContent: string;
home: string;
logPath: string;
errPath: string;
run: CommandRunner;
/** Override the launchd plist path (default `<home>/Library/LaunchAgents/<label>.plist`). */
plistPath?: string;
/** Override the systemd unit path (default `<home>/.config/systemd/user/<unit>`). */
unitPath?: string;
/** launchd domain owner for `bootout`/`bootstrap gui/<uid>` (default: the running process's uid, else 501). */
uid?: number;
/** Wait between launchd bootstrap settle retries (default `setTimeout`; tests inject a no-op). */
sleep?: (ms: number) => Promise<void>;
}
export interface InstallServiceResult {
target: ServiceTarget;
wrapper_path: string;
plist_path: string | null;
unit_path: string | null;
/** Non-fatal notes (linger hint, unload noise). */
notes: string[];
/** Set when the supervisor refused the job; the caller reports a failed check. */
error?: string;
}
/** One-line reason for a failed supervisor call: its output, or the exit status when it printed nothing. */
function describeFailure(r: CommandResult): string {
return (r.stderr || r.stdout).trim() || `exit ${r.status}`;
}
/** `launchctl bootstrap/bootout` (or legacy `load/unload`), `systemctl --user enable/restart/disable` may block on a wedged manager. */
const SUPERVISOR_CHANGE_TIMEOUT_MS = 60_000;
/** Read-only probes and reloads: `launchctl print`, `daemon-reload`, `is-active`, `loginctl enable-linger`. */
const SUPERVISOR_PROBE_TIMEOUT_MS = 15_000;
/** The launchctl on this Mac predates the domain-explicit verbs (macOS < 10.11 era, or a stripped build). */
const LAUNCHCTL_LEGACY_RE = /Unknown command|unrecognized|not found/i;
/**
* `bootstrap` right after `bootout` can fail while launchd is still tearing
* the old job down: "Bootstrap failed: 5: Input/output error", "37: Operation
* already in progress". Transient — retried with a pause.
*/
const LAUNCHCTL_SETTLE_RE = /Input\/output error|already in progress|\b5\b|\b37\b/;
const LAUNCHCTL_SETTLE_RETRIES = 5;
const LAUNCHCTL_SETTLE_MS = 1_000;
/** A `bootout` of a job that is not loaded — expected on a fresh install or after a manual removal, never reported. */
const LAUNCHCTL_NOT_LOADED_RE = /No such process|not loaded|Could not find|not find service/i;
function defaultUid(): number {
return typeof process.getuid === 'function' ? process.getuid() : 501;
}
interface LaunchctlVerbs { modern: 'bootout' | 'bootstrap'; legacy: 'unload' | 'load' }
/**
* `launchctl <modern> gui/<uid> <plist>` (domain-explicit), falling back to
* the legacy `launchctl <legacy> <plist>` ONLY when launchctl itself does not
* know the verb (non-zero exit whose stderr says so). `verb` names the call
* whose result is returned. A "not loaded" bootout failure is returned as
* is; callers ignore it.
*/
async function launchctl(run: CommandRunner, uid: number, plist: string, verbs: LaunchctlVerbs): Promise<{ result: CommandResult; verb: LaunchctlVerbs['modern'] | LaunchctlVerbs['legacy'] }> {
const r = await run(['launchctl', verbs.modern, `gui/${uid}`, plist], { timeoutMs: SUPERVISOR_CHANGE_TIMEOUT_MS });
if (typeof r.status === 'number' && r.status !== 0 && LAUNCHCTL_LEGACY_RE.test(r.stderr)) {
return { result: await run(['launchctl', verbs.legacy, plist], { timeoutMs: SUPERVISOR_CHANGE_TIMEOUT_MS }), verb: verbs.legacy };
}
return { result: r, verb: verbs.modern };
}
function writeExecutable(path: string, content: string, mode: number, what: string): void {
refuseSymlink(path, what);
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, content, { mode });
chmodSync(path, mode);
}
export async function installServeService(p: InstallServiceParams): Promise<InstallServiceResult> {
const result: InstallServiceResult = { target: p.target, wrapper_path: p.wrapperPath, plist_path: null, unit_path: null, notes: [] };
writeExecutable(p.wrapperPath, p.wrapperContent, 0o755, 'the serve wrapper');
if (p.target === 'macos') {
const plist = p.plistPath ?? launchdPlistPath(p.home);
writeExecutable(plist, renderServeLaunchdPlist({ wrapperPath: p.wrapperPath, home: p.home, logPath: p.logPath, errPath: p.errPath }), 0o644, 'the launchd plist');
result.plist_path = plist;
// Bootout-before-bootstrap: `bootstrap` over a loaded agent errors, and a
// running server must relaunch to pick up a regenerated wrapper anyway.
// The bootout failure ("not loaded" on a fresh install) is ignored.
const uid = p.uid ?? defaultUid();
const sleep = p.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
await launchctl(p.run, uid, plist, { modern: 'bootout', legacy: 'unload' });
let boot = await launchctl(p.run, uid, plist, { modern: 'bootstrap', legacy: 'load' });
let retries = 0;
while (boot.result.status !== 0 && retries < LAUNCHCTL_SETTLE_RETRIES && LAUNCHCTL_SETTLE_RE.test(boot.result.stderr)) {
retries++;
await sleep(LAUNCHCTL_SETTLE_MS);
boot = await launchctl(p.run, uid, plist, { modern: 'bootstrap', legacy: 'load' });
}
if (boot.result.status !== 0) result.error = `launchctl ${boot.verb} failed: ${describeFailure(boot.result)}${retries ? ` (after ${retries} settle ${retries === 1 ? 'retry' : 'retries'})` : ''}`;
else if (retries) result.notes.push(`launchctl ${boot.verb} succeeded after ${retries} settle ${retries === 1 ? 'retry' : 'retries'} (launchd was still unloading the previous job)`);
return result;
}
if (p.target === 'linux-systemd') {
const unit = p.unitPath ?? systemdUnitPath(p.home);
writeExecutable(unit, renderServeSystemdUnit({ wrapperPath: p.wrapperPath, logPath: p.logPath, errPath: p.errPath }), 0o644, 'the systemd unit');
result.unit_path = unit;
const reload = await p.run(['systemctl', '--user', 'daemon-reload'], { timeoutMs: SUPERVISOR_PROBE_TIMEOUT_MS });
if (reload.status !== 0) result.notes.push(`systemctl --user daemon-reload: ${describeFailure(reload)}`);
const enable = await p.run(['systemctl', '--user', 'enable', SERVE_SYSTEMD_UNIT], { timeoutMs: SUPERVISOR_CHANGE_TIMEOUT_MS });
if (enable.status !== 0) {
result.error = `systemctl --user enable ${SERVE_SYSTEMD_UNIT} failed: ${describeFailure(enable)}`;
return result;
}
// `restart` (not `enable --now`): a reinstall regenerates the wrapper and
// the running server must relaunch to pick it up; on a fresh install
// restart simply starts it.
const restart = await p.run(['systemctl', '--user', 'restart', SERVE_SYSTEMD_UNIT], { timeoutMs: SUPERVISOR_CHANGE_TIMEOUT_MS });
if (restart.status !== 0) {
result.error = `systemctl --user restart ${SERVE_SYSTEMD_UNIT} failed: ${describeFailure(restart)}`;
return result;
}
// Without linger the user manager stops at logout and takes the server with it.
const linger = await p.run(['loginctl', 'enable-linger'], { timeoutMs: SUPERVISOR_PROBE_TIMEOUT_MS });
if (linger.status !== 0) result.notes.push('loginctl enable-linger failed; the server stops when you log out. Fix: sudo loginctl enable-linger "$USER"');
return result;
}
return result;
}
export interface UninstallServiceParams {
target: ServiceTarget;
home: string;
run: CommandRunner;
plistPath?: string | null;
unitPath?: string | null;
/** launchd domain owner for `bootout gui/<uid>` (default: the running process's uid, else 501). */
uid?: number;
}
export interface UninstallServiceResult {
removed: string[];
/** Non-fatal notes; a `launchctl bootout failed: …` / `launchctl unload failed: …` line means the launchd job may still be loaded. */
notes: string[];
}
/** True when `uninstallServeService` could not boot the launchd job out for a reason other than "not loaded". */
export function launchdBootoutFailed(r: UninstallServiceResult): boolean {
return r.notes.some(n => /^launchctl (bootout|unload) failed:/.test(n));
}
export async function uninstallServeService(p: UninstallServiceParams): Promise<UninstallServiceResult> {
const out: UninstallServiceResult = { removed: [], notes: [] };
if (p.target === 'macos') {
const plist = p.plistPath ?? launchdPlistPath(p.home);
const boot = await launchctl(p.run, p.uid ?? defaultUid(), plist, { modern: 'bootout', legacy: 'unload' });
// A job that was not loaded is the expected answer; anything else means
// the job may still be running and the caller has to say so.
if (boot.result.status !== 0 && !LAUNCHCTL_NOT_LOADED_RE.test(boot.result.stderr)) out.notes.push(`launchctl ${boot.verb} failed: ${describeFailure(boot.result)}`);
if (existsSync(plist)) { unlinkSync(plist); out.removed.push(plist); }
return out;
}
if (p.target === 'linux-systemd') {
const unit = p.unitPath ?? systemdUnitPath(p.home);
const disable = await p.run(['systemctl', '--user', 'disable', '--now', SERVE_SYSTEMD_UNIT], { timeoutMs: SUPERVISOR_CHANGE_TIMEOUT_MS });
if (disable.status !== 0) out.notes.push(`systemctl --user disable --now: ${describeFailure(disable)}`);
if (existsSync(unit)) { unlinkSync(unit); out.removed.push(unit); }
await p.run(['systemctl', '--user', 'daemon-reload'], { timeoutMs: SUPERVISOR_PROBE_TIMEOUT_MS });
return out;
}
return out;
}
export async function serveServiceState(p: { target: ServiceTarget; run: CommandRunner; uid?: number }): Promise<ServiceState> {
if (p.target === 'macos') {
const uid = p.uid ?? defaultUid();
const r = await p.run(['launchctl', 'print', `gui/${uid}/${SERVE_LAUNCHD_LABEL}`], { timeoutMs: SUPERVISOR_PROBE_TIMEOUT_MS });
if (r.status === null) return 'unknown';
if (r.status !== 0) return 'not-installed';
return /state\s*=\s*running/i.test(r.stdout) ? 'running' : 'loaded';
}
if (p.target === 'linux-systemd') {
const r = await p.run(['systemctl', '--user', 'is-active', SERVE_SYSTEMD_UNIT], { timeoutMs: SUPERVISOR_PROBE_TIMEOUT_MS });
if (r.status === null) return 'unknown';
const word = r.stdout.trim().split(/\s+/)[0] ?? '';
if (word === 'active' || word === 'activating' || word === 'reloading') return 'running';
if (word === 'inactive' || word === 'failed' || word === 'deactivating') {
return /could not be found|not-found|no such/i.test(r.stderr) ? 'not-installed' : 'stopped';
}
return r.status === 0 ? 'running' : 'unknown';
}
return 'manual';
}
// ---------------------------------------------------------------------------
// Receipt
// ---------------------------------------------------------------------------
export interface ExposeReceipt {
version: 1;
created_at: string;
updated_at: string;
port: number;
public_url: string;
mcp_url: string;
admin_url: string;
mode: 'tailnet' | 'funnel';
surface: 'verbs' | 'starter' | 'full';
/** The serve's `--advertise`; absent on exposures written before the verbs listing default (they list everything). */
advertise?: 'verbs' | 'starter' | 'full';
enable_dcr: boolean;
tailscale: { binary: string | null; dns_name: string | null; tailscale_version: string | null };
service: { target: ServiceTarget; unit_path: string | null; plist_path: string | null; wrapper_path: string; state: ServiceState | 'skipped' };
admin_token_file: string;
engine: 'pglite' | 'postgres' | 'unknown';
}
const RECEIPT_MODES: readonly string[] = ['tailnet', 'funnel'];
const RECEIPT_TARGETS: readonly string[] = ['macos', 'linux-systemd', 'none'];
const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
const isStringOrNull = (v: unknown): v is string | null => v === null || typeof v === 'string';
/**
* Structural guard for a parsed receipt. Every field `--status` / `--remove`
* dereference without a null check must be present with the right type;
* anything less is treated as "no receipt" rather than crashing mid-command.
*/
function isExposeReceipt(v: unknown): v is ExposeReceipt {
if (!isRecord(v)) return false;
if (v.version !== 1 || typeof v.port !== 'number' || typeof v.public_url !== 'string') return false;
if (typeof v.mcp_url !== 'string' || typeof v.admin_url !== 'string' || typeof v.admin_token_file !== 'string') return false;
if (typeof v.mode !== 'string' || !RECEIPT_MODES.includes(v.mode)) return false;
const service = v.service;
if (!isRecord(service) || typeof service.wrapper_path !== 'string' || typeof service.state !== 'string') return false;
if (typeof service.target !== 'string' || !RECEIPT_TARGETS.includes(service.target)) return false;
if (!isStringOrNull(service.plist_path) || !isStringOrNull(service.unit_path)) return false;
const tailscale = v.tailscale;
if (!isRecord(tailscale) || !isStringOrNull(tailscale.binary) || !isStringOrNull(tailscale.dns_name)) return false;
return true;
}
/** Malformed, partial or missing → null; a symlink at `path` throws (never follow a planted link). */
export function readExposeReceipt(path: string): ExposeReceipt | null {
refuseSymlink(path, 'the expose receipt');
try {
if (!existsSync(path)) return null;
const parsed: unknown = JSON.parse(readFileSync(path, 'utf-8'));
return isExposeReceipt(parsed) ? parsed : null;
} catch {
return null;
}
}
export function writeExposeReceipt(path: string, receipt: ExposeReceipt): void {
refuseSymlink(path, 'the expose receipt');
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
writeFileSync(path, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
chmodSync(path, 0o600);
}