@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/node_modules/@metro-labs/daemon/src/monitor/api.ts

@@ -0,0 +1,132 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { subscribeEvents, type MetroEvent } from '@metro-labs/core/events';
+import { eventInScope } from '../agents/scope.js';
+import { hasAnyKey } from '../agents/keys.js';
+import {
+  allowedAgents,
+  authenticate,
+} from '../mcp/request-identity.js';
+
+const KEEPALIVE_MS = 25_000;
+
+const monitorEnabled = (): boolean => hasAnyKey();
+
+function cors(req: IncomingMessage): Record<string, string> {
+  return {
+    'access-control-allow-origin': req.headers.origin ?? '*',
+    'access-control-allow-methods': 'GET, OPTIONS',
+    'access-control-allow-headers': 'Authorization, Content-Type',
+    'access-control-max-age': '86400',
+    vary: 'Origin',
+  };
+}
+
+function sendJson(
+  res: ServerResponse,
+  req: IncomingMessage,
+  status: number,
+  body: unknown,
+): void {
+  res.writeHead(status, { 'content-type': 'application/json', ...cors(req) });
+  res.end(JSON.stringify(body));
+}
+
+function startTailStream(
+  req: IncomingMessage,
+  res: ServerResponse,
+  allowed: Set<string>,
+): void {
+  res.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache, no-transform',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+    ...cors(req),
+  });
+  const timers: { keepalive?: ReturnType<typeof setInterval> } = {};
+  const subs: { stop?: () => void } = {};
+  let done = false;
+  const cleanup = (): void => {
+    if (done) return;
+    done = true;
+    subs.stop?.();
+    if (timers.keepalive) clearInterval(timers.keepalive);
+    try {
+      res.end();
+    } catch {
+      log.debug('monitor: tail cleanup end failed');
+    }
+  };
+  const write = (chunk: string): void => {
+    if (done) return;
+    if (res.destroyed || res.writableEnded) {
+      cleanup();
+      return;
+    }
+    try {
+      res.write(chunk);
+    } catch (err) {
+      log.debug({ err: errMsg(err) }, 'monitor: tail write failed');
+      cleanup();
+    }
+  };
+  write(': metro monitor tail (live)\n\n');
+  let id = 0;
+  subs.stop = subscribeEvents((e: MetroEvent): void => {
+    if (!eventInScope(allowed, e.line)) return;
+    id += 1;
+    write(`id: ${id}\nevent: live\ndata: ${JSON.stringify(e)}\n\n`);
+  });
+  timers.keepalive = setInterval(() => {
+    write(': keepalive\n\n');
+  }, KEEPALIVE_MS);
+  timers.keepalive.unref?.();
+  req.on('close', cleanup);
+  req.on('error', cleanup);
+}
+
+function routeApi(
+  req: IncomingMessage,
+  res: ServerResponse,
+  path: string,
+  allowed: Set<string>,
+): void {
+  if (path === '/api/tail') {
+    if (req.method !== 'GET') {
+      sendJson(res, req, 405, { error: 'method not allowed' });
+      return;
+    }
+    startTailStream(req, res, allowed);
+    return;
+  }
+  sendJson(res, req, 404, { error: 'not found' });
+}
+
+function preflight(req: IncomingMessage, res: ServerResponse): boolean {
+  if (!monitorEnabled()) {
+    sendJson(res, req, 404, { error: 'not found' });
+    return true;
+  }
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  return false;
+}
+
+export function handleMonitorRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): boolean {
+  const path = (req.url ?? '').split('?', 2)[0] ?? '';
+  if (!path.startsWith('/api/')) return false;
+  if (preflight(req, res)) return true;
+  const identity = authenticate(req);
+  if (!identity) {
+    sendJson(res, req, 401, { error: 'unauthorized' });
+    return true;
+  }
+  routeApi(req, res, path, allowedAgents(identity));
+  return true;
+}

package/runtime/node_modules/@metro-labs/daemon/src/monitor/run-event.ts

@@ -0,0 +1,139 @@
+import { classifyEvent, userSelf, type BufferedEvent, type MetroEvent, type RunEvent, type RunEventMetadata } from '@metro-labs/core/events';
+import { isRecord } from '@metro-labs/core/is-record';
+import { Line } from '@metro-labs/core/lines';
+import { STATIONS } from '@metro-labs/core/station-names';
+import { accountFromLine, allowlistForLine, lineReceives, senderPermitted } from '../agents/map.js';
+import { eventInScope } from '../agents/scope.js';
+
+const TEXT_MAX = 8_000;
+const FIELD_MAX = 512;
+const LINE_MAX = 2_048;
+const ACCOUNT_STATIONS = new Set<string>(STATIONS);
+const KINDS = new Set(['msg', 'reply', 'react', 'edit', 'delete', 'system']);
+
+function safeText(value: unknown, max: number): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  return value.slice(0, max).replace(/https?:\/\/[^\s<>"']+|\/(?:attach|api\/uploads|api\/webhooks|api\/threema)\/[^\s<>"']*/gi, (url) => /\/(?:attach|api\/uploads|api\/webhooks|api\/threema)\//i.test(url) ? '[private link]' : url).slice(0, max);
+}
+
+function validLine(line: string): boolean {
+  return typeof line === 'string' && line.length <= LINE_MAX && /^metro:\/\/[a-z][a-z0-9-]*\/[^\s?#]+$/.test(line) && !line.includes('//', 8) && !line.endsWith('/');
+}
+
+const isSelf = (line: string): boolean => line === userSelf();
+const isSynthetic = (payload: unknown): boolean => isRecord(payload) && (payload.contentType === 'attachmentSaved' || payload.contentType === 'attachmentFailed' || payload.contentType === 'transcript');
+
+function sameAccount(line: string, other: string): boolean {
+  if (!validLine(other)) return false;
+  const a = accountFromLine(line);
+  const b = accountFromLine(other);
+  return a !== undefined && b !== undefined && a.station === b.station && a.accountId === b.accountId;
+}
+
+function permittedTraffic(event: MetroEvent): boolean {
+  if (!isSelf(event.to) && !sameAccount(event.line, event.to)) return false;
+  const allowlist = allowlistForLine(event.line);
+  if (isSelf(event.from)) return !isSynthetic(event.payload) || senderPermitted(allowlist, '');
+  return sameAccount(event.line, event.from) && senderPermitted(allowlist, event.from, event.senderVerified);
+}
+
+function visible(event: MetroEvent, allowed: Set<string>): boolean {
+  if (!validLine(event.line) || !eventInScope(allowed, event.line) || !lineReceives(event.line)) return false;
+  const station = Line.station(event.line);
+  if (station !== event.station) return false;
+  if (!ACCOUNT_STATIONS.has(station)) return station === 'claude' && event.event?.type === 'system' && event.isPrivate !== true;
+  return permittedTraffic(event);
+}
+
+function attachmentType(value: unknown): 'image' | 'video' | 'audio' | 'file' {
+  if (!isRecord(value)) return 'file';
+  const mime = typeof value.mime === 'string' ? value.mime : value.contentType;
+  for (const kind of ['image', 'video', 'audio'] as const) {
+    if (value.kind === kind || (typeof mime === 'string' && mime.startsWith(`${kind}/`))) return kind;
+  }
+  return 'file';
+}
+
+function attachmentMetadata(payload: unknown): RunEventMetadata {
+  if (!isRecord(payload)) return {};
+  const saved = payload.contentType === 'attachmentSaved';
+  const failed = payload.contentType === 'attachmentFailed';
+  if (saved || failed) return {
+    attachmentCount: 1,
+    attachmentTypes: [attachmentType(payload)],
+    attachmentStatus: saved ? 'saved' : 'failed',
+    attachmentFor: safeText(payload.attachmentFor, FIELD_MAX),
+  };
+  if (!Array.isArray(payload.attachments) || payload.attachments.length === 0) return {};
+  return {
+    attachmentCount: payload.attachments.length,
+    attachmentTypes: [...new Set(payload.attachments.slice(0, 100).map(attachmentType))],
+  };
+}
+
+function reactionMetadata(event: MetroEvent): RunEventMetadata {
+  if (event.event?.type !== 'react') return {};
+  return {
+    emoji: safeText(event.event.emoji, 32),
+    ...(isRecord(event.payload) && typeof event.payload.removed === 'boolean' ? { removed: event.payload.removed } : {}),
+  };
+}
+
+function metadata(event: MetroEvent, system: boolean): RunEventMetadata {
+  const attachments = attachmentMetadata(event.payload);
+  if (system) return attachments;
+  const structured = event.event;
+  return {
+    ...attachments,
+    ...(typeof event.isPrivate === 'boolean' ? { isPrivate: event.isPrivate } : {}),
+    ...(typeof event.senderVerified === 'boolean' ? { senderVerified: event.senderVerified } : {}),
+    ...(typeof event.mentionsSelf === 'boolean' ? { mentionsSelf: event.mentionsSelf } : {}),
+    ...(typeof event.replyToSelf === 'boolean' ? { replyToSelf: event.replyToSelf } : {}),
+    ...reactionMetadata(event),
+    ...(structured !== undefined && 'targetId' in structured ? { targetId: safeText(structured.targetId, FIELD_MAX) } : {}),
+  };
+}
+
+function messageFields(event: MetroEvent, system: boolean): Partial<RunEvent> & { truncated: boolean } {
+  if (system) return { truncated: false };
+  return {
+    lineName: safeText(event.lineName, FIELD_MAX),
+    from: safeText(event.from, LINE_MAX),
+    fromName: safeText(event.fromName, FIELD_MAX),
+    fromDisplayName: safeText(event.fromDisplayName, FIELD_MAX),
+    to: safeText(event.to, LINE_MAX),
+    text: safeText(event.text, TEXT_MAX),
+    truncated: typeof event.text === 'string' && event.text.length > TEXT_MAX,
+  };
+}
+
+function validIdentity(event: MetroEvent): boolean {
+  return typeof event.id === 'string' && event.id.length <= FIELD_MAX
+    && typeof event.ts === 'string' && event.ts.length <= 64 && Number.isFinite(Date.parse(event.ts));
+}
+
+const replyId = (event: MetroEvent): string | undefined => event.replyTo ?? (event.event?.type === 'reply' ? event.event.replyTo : undefined);
+const accountId = (event: MetroEvent): string | null => ACCOUNT_STATIONS.has(event.station) ? accountFromLine(event.line)?.accountId ?? null : null;
+
+export function runEvent(entry: BufferedEvent, agentId: string): RunEvent | null {
+  const { event, busSeq } = entry;
+  if (!visible(event, new Set([agentId])) || !validIdentity(event)) return null;
+  const structured = event.event ?? classifyEvent(event);
+  if (!KINDS.has(structured.type)) return null;
+  const system = structured.type === 'system' || isSynthetic(event.payload);
+  return {
+    ...messageFields(event, system),
+    id: safeText(event.id, FIELD_MAX) ?? '',
+    seq: busSeq,
+    ts: new Date(event.ts).toISOString(),
+    kind: system ? 'system' : structured.type,
+    direction: system ? 'system' : isSelf(event.from) ? 'outbound' : 'inbound',
+    agentId,
+    station: event.station,
+    accountId: accountId(event),
+    line: event.line,
+    messageId: safeText(event.messageId, FIELD_MAX),
+    replyTo: safeText(replyId(event), FIELD_MAX),
+    metadata: metadata(event, system),
+  };
+}

package/runtime/node_modules/@metro-labs/daemon/src/monitor/run-events.ts

@@ -0,0 +1,101 @@
+import { createHash, randomUUID } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { bufferedSince, BUS_BUFFER_MAX, currentBusSeq, type BufferedEvent, type RunEvent, type RunEventsPage } from '@metro-labs/core/events';
+import { ID_RE } from '@metro-labs/core/ids';
+import { ApiError } from '@metro-labs/http/api-error';
+import { sessionRoute } from '@metro-labs/http/api-http';
+import { accountEnabled, allowlistForAccount, knownAccounts, knownAgentIds } from '../agents/map.js';
+import { runEvent } from './run-event.js';
+
+const EPOCH = randomUUID();
+const DEFAULT_LIMIT = 100;
+const PAGE_BYTES_MAX = 1_000_000;
+const CURSOR_RE = /^([a-f0-9-]{36}):([a-f0-9]{64}):(0|[1-9]\d{0,15})$/;
+
+interface Cursor { epoch: string; policy: string; seq: number }
+interface Query { agentId: string; limit: number; cursor: Cursor | null }
+
+function cursorOf(raw: string | null): Cursor | null {
+  if (raw === null) return null;
+  const match = CURSOR_RE.exec(raw);
+  if (!match || !Number.isSafeInteger(Number(match[3]))) throw new ApiError('invalid run events cursor', 400);
+  return { epoch: match[1] ?? '', policy: match[2] ?? '', seq: Number(match[3]) };
+}
+
+function limitOf(raw: string | null): number {
+  if (raw === null) return DEFAULT_LIMIT;
+  const limit = Number(raw);
+  if (!/^[1-9]\d{0,2}$/.test(raw) || limit > BUS_BUFFER_MAX) throw new ApiError('limit must be between 1 and 500', 400);
+  return limit;
+}
+
+function queryOf(url: string): Query {
+  const params = new URL(url, 'http://localhost').searchParams;
+  for (const key of params.keys()) {
+    if (!['agent', 'limit', 'cursor'].includes(key) || params.getAll(key).length !== 1) throw new ApiError('invalid run events query', 400);
+  }
+  const agentId = params.get('agent') ?? '';
+  if (!ID_RE.test(agentId)) throw new ApiError('agent must be an agent id', 400);
+  return { agentId, limit: limitOf(params.get('limit')), cursor: cursorOf(params.get('cursor')) };
+}
+
+function policyOf(agentId: string, owner: string): string {
+  const accounts = knownAccounts().filter((account) => account.agentId === agentId).map(({ station, id }) => [
+    station, id, accountEnabled(station, id), allowlistForAccount(station, id) ?? [],
+  ]);
+  return createHash('sha256').update(JSON.stringify([owner, agentId, accounts])).digest('hex');
+}
+
+function bounded(events: RunEvent[], limit: number): RunEvent[] {
+  const rows: RunEvent[] = [];
+  let bytes = 0;
+  for (const event of events.slice(0, limit)) {
+    bytes += Buffer.byteLength(JSON.stringify(event)) + 1;
+    if (bytes > PAGE_BYTES_MAX) break;
+    rows.push(event);
+  }
+  return rows;
+}
+
+function resetNeeded(cursor: Cursor | null, policy: string, oldest: number, newest: number): boolean {
+  return cursor === null || cursor.epoch !== EPOCH || cursor.policy !== policy || cursor.seq < oldest - 1 || cursor.seq > newest;
+}
+
+function page(query: Query, owner: string): RunEventsPage {
+  const { agentId, limit, cursor } = query;
+  if (!knownAgentIds().includes(agentId)) throw new ApiError('no such agent', 404);
+  const policy = policyOf(agentId, owner);
+  const buffered = bufferedSince(0);
+  const newest = currentBusSeq();
+  const oldest = buffered[0]?.busSeq ?? newest + 1;
+  const reset = resetNeeded(cursor, policy, oldest, newest);
+  const visible = buffered.filter((entry) => reset || entry.busSeq > (cursor?.seq ?? newest)).flatMap((entry) => {
+    const event = runEvent(entry, agentId);
+    return event === null ? [] : [event];
+  });
+  const pending = reset ? visible.slice(-limit) : visible;
+  const events = bounded(pending, limit);
+  const hasMore = pending.length > events.length;
+  return {
+    events, cursor: `${EPOCH}:${policy}:${pageSeq(events, hasMore, newest)}`, hasMore, reset,
+    retention: retention(buffered, agentId),
+  };
+}
+
+const pageSeq = (events: RunEvent[], hasMore: boolean, newest: number): number => hasMore ? events.at(-1)?.seq ?? newest : newest;
+function retention(buffered: BufferedEvent[], agentId: string): RunEventsPage['retention'] {
+  let oldestAt: string | null = null;
+  for (const entry of buffered) {
+    const event = runEvent(entry, agentId);
+    if (event === null) continue;
+    oldestAt = event.ts;
+    break;
+  }
+  return { capacity: BUS_BUFFER_MAX, oldestAt, oldestSeq: buffered[0]?.busSeq ?? null };
+}
+
+export function handleRunEventsRequest(req: IncomingMessage, res: ServerResponse): boolean {
+  return sessionRoute(req, res, {
+    methods: { '/api/run/events': ['GET'] }, admin: false, label: 'run-events',
+  }, (session) => Promise.resolve(page(queryOf(req.url ?? ''), session.subject)));
+}

package/runtime/node_modules/@metro-labs/daemon/src/net/tunnel.ts

@@ -0,0 +1,323 @@
+import { execFile, spawn, type ChildProcess } from 'node:child_process';
+import { Resolver } from 'node:dns/promises';
+import { request as httpsRequest } from 'node:https';
+import { errMsg, log } from '@metro-labs/core/log';
+import { localOwner } from '../agents/file-admin.js';
+
+const RESTART_DELAY_MS = 2_000;
+const RESTART_DELAY_MAX_MS = 30_000;
+const TAKEN_RE = /listener already exists/i;
+const ADOPTED_MISSES = 2;
+const adoptedCheckMs = (): number => Number(process.env.METRO_TUNNEL_WATCH_MS) || 30_000;
+const FUNNEL_ON_RE = /\(Funnel on\)/i;
+
+export const tunnelWanted = (): boolean => process.env.METRO_TUNNEL?.trim() === 'tailscale';
+
+const FUNNEL_URL_RE = /https:\/\/[a-z0-9-]+(?:\.[a-z0-9-]+)+\.ts\.net(?::\d{2,5})?(?=[\s/]|$)/i;
+const SILENT_MS = 20_000;
+
+export const funnelUrlIn = (text: string): string | null =>
+  FUNNEL_URL_RE.exec(text)?.[0]?.toLowerCase() ?? null;
+
+export interface Adopted {
+  url: string | null;
+  hint: string;
+  alive?: () => Promise<boolean>;
+}
+
+export interface TunnelDriver {
+  name: string;
+  command: string;
+  args: string[];
+  urlIn: (text: string) => string | null;
+  adopt?: () => Promise<Adopted>;
+}
+
+const runText = (command: string, args: string[]): Promise<string> =>
+  new Promise((resolve) => {
+    execFile(command, args, { encoding: 'utf8', timeout: 10_000 }, (_err, stdout, stderr) => {
+      resolve(`${stdout}\n${stderr}`);
+    });
+  });
+
+export type Probe = (url: string, owner: string | null) => Promise<boolean>;
+
+const PROBE_MS = 5_000;
+const PUBLIC_RESOLVERS = ['1.1.1.1', '8.8.8.8'];
+
+async function publicAddresses(host: string): Promise<string[]> {
+  const found = await Promise.all(
+    PUBLIC_RESOLVERS.map(async (server) => {
+      const resolver = new Resolver();
+      resolver.setServers([server]);
+      const [v4, v6] = await Promise.all([resolver.resolve4(host).catch(() => []), resolver.resolve6(host).catch(() => [])]);
+      return [...v4, ...v6];
+    }),
+  );
+  return [...new Set(found.flat())];
+}
+
+function modeThrough(ip: string, host: string): Promise<{ mode?: unknown; owner?: unknown } | null> {
+  return new Promise((resolve) => {
+    const req = httpsRequest(
+      { host: ip, servername: host, port: 443, path: '/api/mode', method: 'GET', headers: { host }, timeout: PROBE_MS },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (c: Buffer) => chunks.push(c));
+        res.on('end', () => {
+          try {
+            resolve(res.statusCode === 200 ? (JSON.parse(Buffer.concat(chunks).toString('utf8')) as { mode?: unknown }) : null);
+          } catch {
+            resolve(null);
+          }
+        });
+      },
+    );
+    req.on('timeout', () => {
+      req.destroy();
+    });
+    req.on('error', () => {
+      resolve(null);
+    });
+    req.end();
+  });
+}
+
+async function daemonAnswersAt(url: string, owner: string | null): Promise<boolean> {
+  const host = new URL(url).host;
+  const addresses = await publicAddresses(host);
+  if (addresses.length === 0) return false;
+  const body = await modeThrough(addresses[0] ?? '', host);
+  return body !== null && body.mode === 'local' && (owner === null || body.owner === owner);
+}
+
+export function nodeNameIn(statusJson: string): string | null {
+  try {
+    const parsed: unknown = JSON.parse(statusJson);
+    const self = typeof parsed === 'object' && parsed !== null ? (parsed as { Self?: { DNSName?: unknown } }).Self : undefined;
+    const name = typeof self?.DNSName === 'string' ? self.DNSName.replace(/\.$/, '').toLowerCase() : '';
+    return name === '' ? null : name;
+  } catch {
+    return null;
+  }
+}
+
+async function adoptFunnel(bin: string, port: number, probe: Probe, owner: () => string | null): Promise<Adopted> {
+  const name = nodeNameIn(await runText(bin, ['status', '--json']));
+  const watched = (url: string): Adopted => ({
+    url,
+    hint: `a Funnel already publishes this daemon at ${url}; using it`,
+    alive: () => probe(url, owner()),
+  });
+  if (name !== null) {
+    const url = `https://${name}`;
+    if (await probe(url, owner())) return watched(url);
+  }
+  const found = funnelAlreadyServing(await runText(bin, ['funnel', 'status']), port);
+  return found.url === null ? found : watched(found.url);
+}
+
+export function funnelAlreadyServing(status: string, port: number): Adopted {
+  const lines = status.split('\n');
+  const target = `http://127.0.0.1:${String(port)}`;
+  for (const [i, line] of lines.entries()) {
+    if (line.trimStart().startsWith('#')) continue;
+    const url = funnelUrlIn(line);
+    if (url === null) continue;
+    const body = lines.slice(i + 1, i + 6).join('\n');
+    if (!body.includes(target)) continue;
+    if (FUNNEL_ON_RE.test(line)) return { url, hint: `a Funnel already publishes this daemon at ${url}; using it` };
+    return {
+      url: null,
+      hint: `${url} is a tailnet-only serve config on this node, not a Funnel; run: tailscale serve reset`,
+    };
+  }
+  return { url: null, hint: 'port 443 is held by another serve config on this node; run: tailscale serve reset' };
+}
+
+function tailscaleBin(): string {
+  const configured = process.env.METRO_TAILSCALE_BIN?.trim() ?? '';
+  return configured === '' ? 'tailscale' : configured;
+}
+
+export const funnelDriver = (
+  port: number,
+  bin = tailscaleBin(),
+  probe: Probe = daemonAnswersAt,
+  owner: () => string | null = localOwner,
+): TunnelDriver => ({
+  name: 'tailscale funnel',
+  command: bin,
+  args: ['funnel', String(port)],
+  urlIn: funnelUrlIn,
+  adopt: () => adoptFunnel(bin, port, probe, owner),
+});
+
+let liveUrl: string | null = null;
+
+export const currentTunnelUrl = (): string | null => liveUrl;
+
+export type Resolves = (host: string) => Promise<boolean>;
+
+const RESOLVE_EVERY_MS = 3_000;
+const RESOLVE_GIVE_UP_MS = 180_000;
+
+async function resolvesPublicly(host: string): Promise<boolean> {
+  return (await publicAddresses(host)).length > 0;
+}
+
+async function untilResolvable(host: string, resolves: Resolves): Promise<boolean> {
+  const deadline = Date.now() + RESOLVE_GIVE_UP_MS;
+  while (Date.now() < deadline) {
+    if (await resolves(host)) return true;
+    await new Promise((r) => setTimeout(r, RESOLVE_EVERY_MS));
+  }
+  return false;
+}
+
+
+export class Tunnel {
+  private child: ChildProcess | null = null;
+  private closed = false;
+  private output: string[] = [];
+  private restartDelay = RESTART_DELAY_MS;
+  private watch: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private driver: TunnelDriver,
+    private onUrl: (url: string) => void = () => undefined,
+    private resolves: Resolves = resolvesPublicly,
+    private onChange: () => void = () => undefined,
+  ) {}
+
+  private setUrl(url: string | null): void {
+    liveUrl = url;
+    this.onChange();
+  }
+
+  private noticeUrl(text: string): void {
+    const url = this.driver.urlIn(text);
+    if (url === null || url === liveUrl) return;
+    this.setUrl(url);
+    this.restartDelay = RESTART_DELAY_MS;
+    log.info({ url }, `${this.driver.name} up; waiting for its name to resolve`);
+    this.announceWhenResolvable(url).catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, `${this.driver.name}: announce failed`);
+    });
+  }
+
+  private async announceWhenResolvable(url: string): Promise<void> {
+    const resolved = await untilResolvable(new URL(url).host, this.resolves);
+    if (liveUrl !== url) return;
+    if (!resolved) log.warn({ url }, `${this.driver.name} name still not resolving; announcing anyway`);
+    this.onUrl(url);
+  }
+
+  private read(d: Buffer | string): void {
+    const text = (typeof d === 'string' ? d : d.toString('utf8')).trim();
+    if (text === '') return;
+    this.output.push(text);
+    log.debug({ output: text }, this.driver.name);
+    this.noticeUrl(text);
+  }
+
+  private silentCheck(): void {
+    if (this.closed || liveUrl !== null || this.child === null) return;
+    log.warn(
+      { output: this.output.join('\n') },
+      `${this.driver.name}: no public address after ${String(SILENT_MS / 1000)}s; its own output follows`,
+    );
+  }
+
+  start(): void {
+    if (this.closed) return;
+    log.info({ command: this.driver.command, args: this.driver.args }, `${this.driver.name} starting`);
+    this.output = [];
+    const child = spawn(this.driver.command, this.driver.args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    this.child = child;
+    child.stdout?.on('data', (d: Buffer | string) => {
+      this.read(d);
+    });
+    child.stderr?.on('data', (d: Buffer | string) => {
+      this.read(d);
+    });
+    setTimeout(() => {
+      this.silentCheck();
+    }, SILENT_MS).unref();
+    child.on('exit', (code) => {
+      this.child = null;
+      this.setUrl(null);
+      if (this.closed) return;
+      this.afterExit(code).catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, `${this.driver.name}: exit handling failed`);
+      });
+    });
+    child.on('error', (err) => {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        this.closed = true;
+        log.error(
+          { command: this.driver.command },
+          `${this.driver.name}: the binary is not installed, so there is no public address; install it and restart`,
+        );
+        return;
+      }
+      log.warn({ err: errMsg(err) }, `${this.driver.name} spawn error`);
+    });
+  }
+
+  private async afterExit(code: number | null): Promise<void> {
+    const output = this.output.join('\n');
+    if (this.driver.adopt !== undefined && TAKEN_RE.test(output)) {
+      const found = await this.driver.adopt();
+      if (this.closed) return;
+      if (found.url !== null) {
+        log.info({ url: found.url }, `${this.driver.name}: ${found.hint}`);
+        this.noticeUrl(found.url);
+        if (found.alive !== undefined) this.watchAdopted(found.url, found.alive);
+        return;
+      }
+      log.error({ output }, `${this.driver.name}: ${found.hint}`);
+    } else log.warn({ code, output: this.output.slice(-5).join('\n') }, `${this.driver.name} exited; restarting`);
+    setTimeout(() => {
+      this.start();
+    }, this.restartDelay);
+    this.restartDelay = Math.min(this.restartDelay * 2, RESTART_DELAY_MAX_MS);
+  }
+
+  private watchAdopted(url: string, alive: () => Promise<boolean>): void {
+    let misses = 0;
+    const tick = async (): Promise<void> => {
+      if (this.closed || liveUrl !== url) {
+        this.unwatch();
+        return;
+      }
+      misses = (await alive()) ? 0 : misses + 1;
+      if (misses < ADOPTED_MISSES) return;
+      this.unwatch();
+      log.warn({ url }, `${this.driver.name}: the Funnel this daemon adopted no longer answers; publishing our own`);
+      this.setUrl(null);
+      this.restartDelay = RESTART_DELAY_MS;
+      this.start();
+    };
+    this.unwatch();
+    this.watch = setInterval(() => {
+      tick().catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, `${this.driver.name}: adopted-funnel check failed`);
+      });
+    }, adoptedCheckMs());
+    this.watch.unref();
+  }
+
+  private unwatch(): void {
+    if (this.watch !== null) clearInterval(this.watch);
+    this.watch = null;
+  }
+
+  stop(): void {
+    this.closed = true;
+    this.unwatch();
+    this.child?.kill('SIGINT');
+    this.child = null;
+    this.setUrl(null);
+  }
+}