zooid 0.6.1 → 0.7.0

package/src/observability/file-sink.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest'
+import { mkdtemp, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { rmSync } from 'node:fs'
+import { JsonlSink, shouldCaptureUpdate, type Verbosity } from './file-sink.js'
+
+describe('JsonlSink', () => {
+  let dir: string
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'zooid-obs-sink-'))
+  })
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('appends one JSON object per line and survives close+reopen', async () => {
+    const path = join(dir, 'agent-docs.acp.jsonl')
+    const sink1 = new JsonlSink(path)
+    await sink1.write({ a: 1 })
+    await sink1.write({ b: 2 })
+    await sink1.close()
+    const sink2 = new JsonlSink(path)
+    await sink2.write({ c: 3 })
+    await sink2.close()
+    const text = await readFile(path, 'utf8')
+    const lines = text.trim().split('\n').map((l) => JSON.parse(l))
+    expect(lines).toEqual([{ a: 1 }, { b: 2 }, { c: 3 }])
+  })
+
+  it('truncates string fields longer than 4 KB on a top-level cap', async () => {
+    const path = join(dir, 'big.jsonl')
+    const sink = new JsonlSink(path, { maxStringLen: 4096 })
+    const big = 'x'.repeat(10_000)
+    await sink.write({ a: big })
+    await sink.close()
+    const line = JSON.parse((await readFile(path, 'utf8')).trim())
+    expect(line.a.length).toBeLessThanOrEqual(4096 + '…[truncated]'.length)
+    expect(line.a.endsWith('…[truncated]')).toBe(true)
+  })
+})
+
+describe('shouldCaptureUpdate (default verbosity)', () => {
+  const cases: Array<[string, boolean]> = [
+    ['tool_call', true],
+    ['tool_call_update', true],
+    ['plan', true],
+    ['available_commands_update', true],
+    ['current_mode_update', true],
+    ['user_message_chunk', true],
+    ['agent_message_chunk', false],
+    ['agent_thought_chunk', false],
+  ]
+  it.each(cases)('default(%s) → %s', (variant, expected) => {
+    const v: Verbosity = 'default'
+    expect(shouldCaptureUpdate(v, variant)).toBe(expected)
+  })
+
+  it('verbose-thoughts captures thought chunks but not message chunks', () => {
+    expect(shouldCaptureUpdate('verbose-thoughts', 'agent_thought_chunk')).toBe(true)
+    expect(shouldCaptureUpdate('verbose-thoughts', 'agent_message_chunk')).toBe(false)
+  })
+
+  it('verbose captures everything', () => {
+    expect(shouldCaptureUpdate('verbose', 'agent_message_chunk')).toBe(true)
+    expect(shouldCaptureUpdate('verbose', 'agent_thought_chunk')).toBe(true)
+  })
+})

package/src/observability/file-sink.ts

@@ -0,0 +1,78 @@
+import { createWriteStream, type WriteStream } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+export type Verbosity = 'default' | 'verbose-thoughts' | 'verbose'
+
+export interface JsonlSinkOpts {
+  /** Truncate any single string field longer than this. Default 4 KB. */
+  maxStringLen?: number
+}
+
+const TRUNC_MARKER = '…[truncated]'
+
+export class JsonlSink {
+  private stream: WriteStream | null = null
+  private readonly maxStringLen: number
+  private readonly readyPromise: Promise<void>
+
+  constructor(
+    private readonly path: string,
+    opts: JsonlSinkOpts = {},
+  ) {
+    this.maxStringLen = opts.maxStringLen ?? 4096
+    this.readyPromise = (async () => {
+      await mkdir(dirname(this.path), { recursive: true })
+      this.stream = createWriteStream(this.path, { flags: 'a' })
+    })()
+  }
+
+  async write(obj: unknown): Promise<void> {
+    await this.readyPromise
+    const capped = capStrings(obj, this.maxStringLen)
+    const line = JSON.stringify(capped) + '\n'
+    return new Promise((resolve, reject) => {
+      this.stream!.write(line, (err) => (err ? reject(err) : resolve()))
+    })
+  }
+
+  async close(): Promise<void> {
+    await this.readyPromise
+    return new Promise((resolve) => {
+      this.stream!.end(() => resolve())
+    })
+  }
+}
+
+function capStrings(v: unknown, max: number): unknown {
+  if (typeof v === 'string') {
+    return v.length <= max ? v : v.slice(0, max) + TRUNC_MARKER
+  }
+  if (Array.isArray(v)) return v.map((x) => capStrings(x, max))
+  if (v && typeof v === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const [k, val] of Object.entries(v)) out[k] = capStrings(val, max)
+    return out
+  }
+  return v
+}
+
+const DEFAULT_VARIANTS = new Set([
+  'tool_call',
+  'tool_call_update',
+  'plan',
+  'available_commands_update',
+  'current_mode_update',
+  'user_message_chunk',
+])
+
+export function shouldCaptureUpdate(
+  verbosity: Verbosity,
+  variant: string,
+): boolean {
+  if (verbosity === 'verbose') return true
+  if (verbosity === 'verbose-thoughts') {
+    return DEFAULT_VARIANTS.has(variant) || variant === 'agent_thought_chunk'
+  }
+  return DEFAULT_VARIANTS.has(variant)
+}

package/src/observability/observability.integration.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest'
+import { mkdtemp, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { rmSync } from 'node:fs'
+import { wireAgentCapture } from './capture-agent.js'
+import { resolveLogPaths, ensureDayFolder } from './paths.js'
+import type { TapEvent } from '@zooid/core'
+
+describe('agent capture end-to-end', () => {
+  let dataDir: string
+  beforeEach(async () => {
+    dataDir = await mkdtemp(join(tmpdir(), 'zooid-obs-int-'))
+  })
+  afterEach(() => {
+    rmSync(dataDir, { recursive: true, force: true })
+  })
+
+  it('writes one JSONL line per tap event with envelope + turn correlation', async () => {
+    const now = new Date('2026-05-06T10:00:00Z')
+    const paths = resolveLogPaths({ dataDir, now })
+    await ensureDayFolder(paths)
+
+    const cap = wireAgentCapture({
+      agent: 'docs',
+      paths,
+      verbosity: 'default',
+      matrixContext: () => ({ room_id: '!abc:localhost', event_id: '$xyz' }),
+      now: () => now,
+    })
+
+    const events: TapEvent[] = [
+      {
+        kind: 'turn_started',
+        agentId: 'docs',
+        sessionId: 'sess_1',
+        turnId: 'turn_1',
+        promptText: 'write the overview page',
+      },
+      {
+        kind: 'session_update',
+        agentId: 'docs',
+        sessionId: 'sess_1',
+        turnId: 'turn_1',
+        update: {
+          sessionUpdate: 'tool_call',
+          toolCallId: 'tc_1',
+          kind: 'edit',
+          title: 'edit overview.md',
+        } as never,
+      },
+      {
+        kind: 'session_update',
+        agentId: 'docs',
+        sessionId: 'sess_1',
+        turnId: 'turn_1',
+        update: {
+          sessionUpdate: 'tool_call_update',
+          toolCallId: 'tc_1',
+          status: 'completed',
+        } as never,
+      },
+      {
+        kind: 'session_update',
+        agentId: 'docs',
+        sessionId: 'sess_1',
+        turnId: 'turn_1',
+        update: {
+          sessionUpdate: 'agent_message_chunk',
+          content: { type: 'text', text: 'done' },
+        } as never,
+      },
+      {
+        kind: 'turn_completed',
+        agentId: 'docs',
+        sessionId: 'sess_1',
+        turnId: 'turn_1',
+        stopReason: 'end_turn',
+      },
+    ]
+    for (const e of events) cap.onTap(e)
+    await cap.close()
+
+    const text = await readFile(paths.agentTap('docs'), 'utf8')
+    const lines = text.trim().split('\n').map((l) => JSON.parse(l))
+
+    expect(lines.map((l) => l.kind)).toEqual([
+      'turn_started',
+      'session_update',
+      'session_update',
+      'turn_completed',
+    ])
+    for (const l of lines) {
+      expect(l.ts).toBe('2026-05-06T10:00:00.000Z')
+      expect(l.agent).toBe('docs')
+      expect(l.session_id).toBe('sess_1')
+      expect(l.turn_id).toBe('turn_1')
+      expect(l.matrix).toEqual({ room_id: '!abc:localhost', event_id: '$xyz' })
+    }
+  })
+
+  it('thought chunks are dropped by default but kept under verbose-thoughts', async () => {
+    const paths = resolveLogPaths({ dataDir, now: new Date('2026-05-06T10:00:00Z') })
+    await ensureDayFolder(paths)
+    const cap = wireAgentCapture({
+      agent: 'docs',
+      paths,
+      verbosity: 'verbose-thoughts',
+      matrixContext: () => null,
+      now: () => new Date('2026-05-06T10:00:00Z'),
+    })
+    cap.onTap({
+      kind: 'session_update',
+      agentId: 'docs',
+      sessionId: 's',
+      turnId: 't',
+      update: {
+        sessionUpdate: 'agent_thought_chunk',
+        content: { type: 'text', text: 'thinking…' },
+      } as never,
+    })
+    cap.onTap({
+      kind: 'session_update',
+      agentId: 'docs',
+      sessionId: 's',
+      turnId: 't',
+      update: {
+        sessionUpdate: 'agent_message_chunk',
+        content: { type: 'text', text: 'output' },
+      } as never,
+    })
+    await cap.close()
+    const lines = (await readFile(paths.agentTap('docs'), 'utf8'))
+      .trim()
+      .split('\n')
+      .map((l) => JSON.parse(l))
+    expect(lines).toHaveLength(1)
+    expect(lines[0].notification.sessionUpdate).toBe('agent_thought_chunk')
+  })
+
+  it('omits matrix context cleanly when not running on Matrix', async () => {
+    const paths = resolveLogPaths({ dataDir, now: new Date('2026-05-06T10:00:00Z') })
+    await ensureDayFolder(paths)
+    const cap = wireAgentCapture({
+      agent: 'echo',
+      paths,
+      verbosity: 'default',
+      matrixContext: () => null,
+      now: () => new Date('2026-05-06T10:00:00Z'),
+    })
+    cap.onTap({
+      kind: 'turn_started',
+      agentId: 'echo',
+      sessionId: 's',
+      turnId: 't',
+      promptText: 'ping',
+    })
+    await cap.close()
+    const line = JSON.parse((await readFile(paths.agentTap('echo'), 'utf8')).trim())
+    expect(line.matrix).toBeUndefined()
+  })
+})

package/src/observability/paths.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest'
+import { mkdtemp, mkdir, readlink, readdir, writeFile, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { rmSync } from 'node:fs'
+import { resolveLogPaths, ensureDayFolder, pruneOldDays } from './paths.js'
+
+describe('observability paths', () => {
+  let dataDir: string
+  beforeEach(async () => {
+    dataDir = await mkdtemp(join(tmpdir(), 'zooid-obs-paths-'))
+  })
+  afterEach(() => {
+    rmSync(dataDir, { recursive: true, force: true })
+  })
+
+  it('places each source under logs/YYYY-MM-DD/', () => {
+    const p = resolveLogPaths({ dataDir, now: new Date('2026-05-06T10:00:00Z') })
+    expect(p.dayDir).toBe(join(dataDir, 'logs', '2026-05-06'))
+    expect(p.tuwunelLog).toBe(join(p.dayDir, 'tuwunel.log'))
+    expect(p.daemonLog).toBe(join(p.dayDir, 'daemon.log'))
+    expect(p.devLog).toBe(join(p.dayDir, 'dev.log'))
+    expect(p.agentLog('docs')).toBe(join(p.dayDir, 'agent-docs.log'))
+    expect(p.agentTap('docs')).toBe(join(p.dayDir, 'agent-docs.acp.jsonl'))
+    expect(p.todayLink).toBe(join(dataDir, 'logs', 'today'))
+  })
+
+  it('uses local-time date, not UTC', () => {
+    // 2026-05-06 23:30 UTC is 2026-05-07 in many timezones; we want the
+    // day the user *started* the session by their wall clock.
+    const local = new Date(2026, 4, 6, 23, 30) // month is 0-indexed: May = 4
+    const p = resolveLogPaths({ dataDir, now: local })
+    expect(p.dayDir).toBe(join(dataDir, 'logs', '2026-05-06'))
+  })
+
+  it('ensureDayFolder creates the dir and points today→ at it', async () => {
+    const p = resolveLogPaths({ dataDir, now: new Date('2026-05-06T10:00:00Z') })
+    await ensureDayFolder(p)
+    const linkTarget = await readlink(p.todayLink)
+    expect(linkTarget).toBe('2026-05-06')
+    const s = await stat(p.dayDir)
+    expect(s.isDirectory()).toBe(true)
+  })
+
+  it('ensureDayFolder repoints today→ when the day rolls over', async () => {
+    const day1 = resolveLogPaths({ dataDir, now: new Date('2026-05-06T10:00:00Z') })
+    await ensureDayFolder(day1)
+    const day2 = resolveLogPaths({ dataDir, now: new Date('2026-05-07T10:00:00Z') })
+    await ensureDayFolder(day2)
+    expect(await readlink(day2.todayLink)).toBe('2026-05-07')
+  })
+
+  it('pruneOldDays removes folders older than retainDays', async () => {
+    const logs = join(dataDir, 'logs')
+    for (const d of ['2026-04-20', '2026-05-01', '2026-05-05', '2026-05-06']) {
+      await mkdir(join(logs, d), { recursive: true })
+      await writeFile(join(logs, d, 'tuwunel.log'), 'x')
+    }
+    const removed = await pruneOldDays({
+      dataDir,
+      now: new Date('2026-05-06T10:00:00Z'),
+      retainDays: 3,
+    })
+    expect(removed.sort()).toEqual(['2026-04-20', '2026-05-01'])
+    const remaining = (await readdir(logs)).sort()
+    expect(remaining).toEqual(['2026-05-05', '2026-05-06'])
+  })
+
+  it('pruneOldDays with retainDays=0 is a no-op', async () => {
+    const logs = join(dataDir, 'logs')
+    await mkdir(join(logs, '2024-01-01'), { recursive: true })
+    const removed = await pruneOldDays({
+      dataDir,
+      now: new Date('2026-05-06T10:00:00Z'),
+      retainDays: 0,
+    })
+    expect(removed).toEqual([])
+  })
+
+  it('pruneOldDays ignores non-date entries (the today symlink, junk)', async () => {
+    const logs = join(dataDir, 'logs')
+    await mkdir(join(logs, '2026-05-06'), { recursive: true })
+    await mkdir(join(logs, 'not-a-date'), { recursive: true })
+    const p = resolveLogPaths({ dataDir, now: new Date('2026-05-06T10:00:00Z') })
+    await ensureDayFolder(p)
+    const removed = await pruneOldDays({
+      dataDir,
+      now: new Date('2026-05-06T10:00:00Z'),
+      retainDays: 1,
+    })
+    expect(removed).toEqual([])
+  })
+
+  it('treats its dataDir argument as the data root: logs become a top-level sibling', () => {
+    // Pre-ZOD041 we passed the matrix dir, so logs landed at <matrix>/logs/.
+    // Post-ZOD041 we pass the root, so logs land at <root>/logs/ (matrix is its sibling).
+    const root = '/abs/data'
+    const p = resolveLogPaths({ dataDir: root, now: new Date('2026-05-06T10:00:00Z') })
+    expect(p.logsDir).toBe('/abs/data/logs')
+    expect(p.dayDir).toBe('/abs/data/logs/2026-05-06')
+    // Sanity: NOT under matrix.
+    expect(p.logsDir.startsWith('/abs/data/matrix')).toBe(false)
+  })
+})

package/src/observability/paths.ts

@@ -0,0 +1,94 @@
+import { mkdir, readdir, rm, symlink, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export interface LogPaths {
+  dataDir: string
+  logsDir: string
+  dayDir: string
+  daySlug: string
+  todayLink: string
+  tuwunelLog: string
+  daemonLog: string
+  devLog: string
+  agentLog: (agentName: string) => string
+  agentTap: (agentName: string) => string
+}
+
+export interface ResolveOpts {
+  dataDir: string
+  /** Defaults to `new Date()`. Tests pin this for determinism. */
+  now?: Date
+}
+
+// Local-time slug — we want the wall-clock day a session started, not UTC.
+function localDateSlug(d: Date): string {
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}-${m}-${day}`
+}
+
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/
+
+export function resolveLogPaths({ dataDir, now }: ResolveOpts): LogPaths {
+  const slug = localDateSlug(now ?? new Date())
+  const logsDir = join(dataDir, 'logs')
+  const dayDir = join(logsDir, slug)
+  return {
+    dataDir,
+    logsDir,
+    dayDir,
+    daySlug: slug,
+    todayLink: join(logsDir, 'today'),
+    tuwunelLog: join(dayDir, 'tuwunel.log'),
+    daemonLog: join(dayDir, 'daemon.log'),
+    devLog: join(dayDir, 'dev.log'),
+    agentLog: (n) => join(dayDir, `agent-${n}.log`),
+    agentTap: (n) => join(dayDir, `agent-${n}.acp.jsonl`),
+  }
+}
+
+export async function ensureDayFolder(p: LogPaths): Promise<void> {
+  await mkdir(p.dayDir, { recursive: true })
+  // Symlink target is the relative slug so the link survives a moved data dir.
+  try {
+    await unlink(p.todayLink)
+  } catch {
+    // may not exist
+  }
+  await symlink(p.daySlug, p.todayLink)
+}
+
+export interface PruneOpts {
+  dataDir: string
+  now?: Date
+  retainDays: number
+}
+
+export async function pruneOldDays(opts: PruneOpts): Promise<string[]> {
+  if (opts.retainDays <= 0) return []
+  const logsDir = join(opts.dataDir, 'logs')
+  let entries: string[]
+  try {
+    entries = await readdir(logsDir)
+  } catch {
+    return []
+  }
+  const today = opts.now ?? new Date()
+  const cutoff = new Date(
+    today.getFullYear(),
+    today.getMonth(),
+    today.getDate() - opts.retainDays + 1,
+  ).getTime()
+  const removed: string[] = []
+  for (const name of entries) {
+    if (!DAY_RE.test(name)) continue
+    const [y, m, d] = name.split('-').map(Number)
+    const t = new Date(y, m - 1, d).getTime()
+    if (t < cutoff) {
+      await rm(join(logsDir, name), { recursive: true, force: true })
+      removed.push(name)
+    }
+  }
+  return removed
+}

package/src/services/tuwunel.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { buildRunArgs } from './tuwunel.js'
+
+describe('buildRunArgs', () => {
+  const base = {
+    name: 'zooid-tuwunel',
+    image: 'ghcr.io/matrix-construct/tuwunel:latest',
+    hostPort: 8448,
+    paths: {
+      dataDir: '/abs/data/matrix',
+      dbDir: '/abs/data/matrix/db',
+      mediaDir: '/abs/data/matrix/media',
+      configDir: '/abs/data/matrix/config',
+      registrationsDir: '/abs/data/matrix/config/registrations',
+      tuwunelTomlPath: '/abs/data/matrix/config/tuwunel.toml',
+      appserviceYamlPath: '/abs/data/matrix/config/registrations/zooid.yaml',
+      envPath: '/abs/data/matrix/config/.env',
+    },
+  }
+
+  it('uses docker by default, mounts persistent volumes and config read-only', () => {
+    const args = buildRunArgs({ ...base, engine: 'docker' })
+    expect(args[0]).toBe('run')
+    expect(args).toContain('--rm')
+    // Foregrounded so the parent process owns Tuwunel's stdio (logs).
+    expect(args).not.toContain('-d')
+    expect(args).toContain('--name')
+    expect(args).toContain('zooid-tuwunel')
+    expect(args).toContain('-p')
+    expect(args).toContain('8448:8448')
+    expect(args).toContain('/abs/data/matrix/db:/var/lib/tuwunel/db')
+    expect(args).toContain('/abs/data/matrix/media:/var/lib/tuwunel/media')
+    expect(args).toContain(
+      '/abs/data/matrix/config/tuwunel.toml:/etc/tuwunel/tuwunel.toml:ro',
+    )
+    expect(args).toContain(
+      '/abs/data/matrix/config/registrations:/var/lib/tuwunel/registrations:ro',
+    )
+    // ZOD041 deliberately does NOT mount ${dataRoot}/logs into the container.
+    // Today the daemon captures tuwunel's stdout/stderr via captureChildToFile
+    // — there's no internal tuwunel log directive yet. A future cycle that flips
+    // tuwunel.toml to write its own logs can add the mount alongside that change.
+    expect(args.some((a) => a.endsWith(':/var/log/tuwunel'))).toBe(false)
+    expect(args).toContain('TUWUNEL_CONFIG=/etc/tuwunel/tuwunel.toml')
+    expect(args[args.length - 1]).toBe(base.image)
+  })
+
+  it('engine: podman switches the binary (caller chooses), args are identical', () => {
+    const docker = buildRunArgs({ ...base, engine: 'docker' })
+    const podman = buildRunArgs({ ...base, engine: 'podman' })
+    expect(podman).toEqual(docker)
+  })
+
+  it('honors a custom container name and host port', () => {
+    const args = buildRunArgs({
+      ...base,
+      name: 'my-zooid-tuwunel',
+      hostPort: 9000,
+      engine: 'docker',
+    })
+    expect(args).toContain('my-zooid-tuwunel')
+    expect(args).toContain('9000:8448')
+  })
+})

package/src/services/tuwunel.ts

@@ -0,0 +1,91 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import type { Paths } from '../bootstrap/paths.js'
+
+export interface TuwunelOpts {
+  name: string
+  image?: string
+  hostPort: number
+  paths: Paths
+  engine: 'docker' | 'podman'
+}
+
+const DEFAULT_IMAGE = 'ghcr.io/matrix-construct/tuwunel:latest'
+
+export function buildRunArgs(opts: TuwunelOpts): string[] {
+  const image = opts.image ?? DEFAULT_IMAGE
+  return [
+    'run',
+    '--rm',
+    '--name',
+    opts.name,
+    '-p',
+    `${opts.hostPort}:8448`,
+    '-v',
+    `${opts.paths.dbDir}:/var/lib/tuwunel/db`,
+    '-v',
+    `${opts.paths.mediaDir}:/var/lib/tuwunel/media`,
+    '-v',
+    `${opts.paths.tuwunelTomlPath}:/etc/tuwunel/tuwunel.toml:ro`,
+    '-v',
+    `${opts.paths.registrationsDir}:/var/lib/tuwunel/registrations:ro`,
+    '-e',
+    'TUWUNEL_CONFIG=/etc/tuwunel/tuwunel.toml',
+    image,
+  ]
+}
+
+export class TuwunelService {
+  private child: ChildProcess | null = null
+  constructor(private readonly opts: TuwunelOpts) {}
+
+  start(): ChildProcess {
+    this.child = spawn(this.opts.engine, buildRunArgs(this.opts), {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    return this.child
+  }
+
+  async stop(): Promise<void> {
+    // Foregrounded container: kill the engine process; --rm cleans up after.
+    if (this.child && this.child.exitCode === null) {
+      this.child.kill('SIGTERM')
+      await new Promise<void>((resolve) => {
+        this.child!.on('exit', () => resolve())
+      })
+    }
+    this.child = null
+    // Defensive: the parent may have died while the container was running, in
+    // which case --rm doesn't fire. `<engine> stop` is a no-op if it's already
+    // gone (errors are swallowed).
+    await execEngine(this.opts.engine, ['stop', this.opts.name]).catch(() => {})
+  }
+
+  async waitHealthy(opts: { url: string; timeoutMs: number }): Promise<void> {
+    const deadline = Date.now() + opts.timeoutMs
+    while (Date.now() < deadline) {
+      try {
+        const r = await fetch(`${opts.url}/_matrix/client/versions`)
+        if (r.ok) return
+      } catch {
+        // not yet
+      }
+      await new Promise((resolve) => setTimeout(resolve, 500))
+    }
+    throw new Error(
+      `Tuwunel did not become healthy at ${opts.url} in ${opts.timeoutMs}ms`,
+    )
+  }
+}
+
+function execEngine(engine: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(engine, args, { stdio: 'pipe' })
+    let stderr = ''
+    child.stderr.on('data', (b) => (stderr += String(b)))
+    child.on('exit', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(`${engine} ${args.join(' ')} failed: ${stderr.trim()}`))
+    })
+    child.on('error', reject)
+  })
+}