airaknit 1.1.2-rc.9

package/src/runner/runner-nats.ts

@@ -0,0 +1,323 @@
+import { connect, type NatsConnection, type Subscription } from "@nats-io/transport-node"
+import { wsconnect } from "@nats-io/nats-core"
+import { Kvm } from "@nats-io/kv"
+import { spawnSync } from "node:child_process"
+import { LOG_PREFIX } from "../shared/branding"
+import {
+  runnerCmdSubject,
+  runnerHeartbeatSubject,
+  RUNNER_REGISTRY_BUCKET,
+  PROTOCOL_VERSION,
+  type RunnerCapabilities,
+  type StartTurnCommand,
+  type CancelTurnCommand,
+  type RespondToolCommand,
+  type StopChatPtyCommand,
+  type RunnerRegistration,
+  type RunnerHeartbeat,
+} from "../shared/runner-protocol"
+import type { AgentProvider } from "../shared/types"
+import { resolveClaudeBinary } from "../server/claude-pty/resolve-binary.adapter"
+import type { RunnerAgent } from "./runner-agent"
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+export const RUNNER_RECONNECT_OPTIONS = {
+  maxReconnectAttempts: -1,
+  reconnectTimeWait: 750,
+  pingInterval: 15_000,
+  maxPingOut: 3,
+} as const
+
+export interface ConnectRunnerOptions {
+  natsUrl: string
+  token?: string | undefined
+  connectFn?: typeof connect
+}
+
+export async function connectRunner(
+  options: ConnectRunnerOptions,
+): Promise<NatsConnection> {
+  const { natsUrl, token } = options
+  // ws:// or wss:// → connect through the server's /nats-ws proxy (same path the
+  // browser uses, over the tunneled HTTP port) via wsconnect. Otherwise use the
+  // TCP transport. Bun provides a global WebSocket, so wsconnect works here.
+  const isWs = /^wss?:\/\//i.test(natsUrl)
+  const connectFn = options.connectFn ?? (isWs ? wsconnect : connect)
+  return connectFn({
+    servers: natsUrl,
+    ...(token ? { token } : {}),
+    ...RUNNER_RECONNECT_OPTIONS,
+  })
+}
+
+export interface ShutdownConnectionOptions {
+  drainTimeoutMs?: number
+}
+
+export async function shutdownConnection(
+  nc: NatsConnection,
+  options: ShutdownConnectionOptions = {},
+): Promise<void> {
+  const drainTimeoutMs = options.drainTimeoutMs ?? 3_000
+  try {
+    await Promise.race([
+      nc.drain(),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error("drain timeout")), drainTimeoutMs),
+      ),
+    ])
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    console.warn(LOG_PREFIX, `runner drain timeout or failed: ${message} — falling back to close()`)
+    await nc.close().catch((closeError) => {
+      const closeMessage = closeError instanceof Error ? closeError.message : String(closeError)
+      console.warn(LOG_PREFIX, `runner close() also failed: ${closeMessage}`)
+    })
+  }
+}
+
+/**
+ * Probe which agent providers are actually installed on this runner.
+ * A provider is present if its binary resolves successfully. Errors are caught
+ * and treated as "not installed" so a bad probe never crashes registration.
+ *
+ * Exported for testing only — callers within this module use `probeProviders()`.
+ */
+export async function probeProviders(
+  _resolveClaudeBinary?: typeof resolveClaudeBinary,
+): Promise<RunnerCapabilities> {
+  const resolver = _resolveClaudeBinary ?? resolveClaudeBinary
+  const providers: AgentProvider[] = []
+
+  // Probe claude (SDK provider)
+  try {
+    await resolver({ env: process.env, homeDir: process.env.HOME ?? process.env.USERPROFILE ?? "" })
+    providers.push("claude")
+    // claude-pty is the same claude binary driven through a PTY (the
+    // claude-pty driver) rather than the SDK. It has no separate binary, so
+    // if claude resolves, claude-pty is available too. Advertise it explicitly
+    // — otherwise the server's capability gate refuses every claude-pty turn.
+    providers.push("claude-pty")
+  } catch {
+    // claude binary not found — exclude claude and claude-pty from capabilities
+  }
+
+  // Probe codex via which (mirrors resolveCodexBinary in turn-factories.ts)
+  try {
+    const which = spawnSync("which", ["codex"], { encoding: "utf-8", timeout: 3000 })
+    if (which.status === 0 && which.stdout.trim()) {
+      providers.push("codex")
+    }
+  } catch {
+    // which failed — exclude codex
+  }
+
+  console.warn(LOG_PREFIX, `Probed capabilities: providers=[${providers.join(", ")}]`)
+  return { providers }
+}
+
+export interface RunnerNatsHandlerOptions {
+  nc: NatsConnection
+  agent: RunnerAgent
+  runnerId: string
+  heartbeatIntervalMs?: number
+  /** Override the capability probe for testing — if provided, skips the real probe. */
+  _probeProviders?: () => Promise<RunnerCapabilities>
+}
+
+export class RunnerNatsHandler {
+  private readonly nc: NatsConnection
+  private readonly agent: RunnerAgent
+  private readonly runnerId: string
+  private readonly heartbeatIntervalMs: number
+  private readonly _probeProviders: () => Promise<RunnerCapabilities>
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  private subscriptions: Subscription[] = []
+  // Cache the registration shape so heartbeats can update lastSeenAt without
+  // re-constructing the full object each time.
+  private registration: RunnerRegistration | null = null
+  // Cached KV handle for the registry bucket — reused across heartbeat
+  // lastSeenAt writes instead of re-opening (kvm.open) on every beat.
+  private registryKv: Awaited<ReturnType<Kvm["open"]>> | null = null
+
+  constructor(options: RunnerNatsHandlerOptions) {
+    this.nc = options.nc
+    this.agent = options.agent
+    this.runnerId = options.runnerId
+    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 10_000
+    this._probeProviders = options._probeProviders ?? probeProviders
+  }
+
+  async start(): Promise<void> {
+    // Register in KV
+    await this.register()
+
+    // Subscribe to commands
+    this.subscribeCommand("start_turn", async (data) => {
+      const cmd = JSON.parse(data) as StartTurnCommand
+      await this.agent.startTurn(cmd)
+    })
+
+    this.subscribeCommand("cancel_turn", async (data) => {
+      const cmd = JSON.parse(data) as CancelTurnCommand
+      await this.agent.cancel(cmd.chatId)
+    })
+
+    this.subscribeCommand("respond_tool", async (data) => {
+      const cmd = JSON.parse(data) as RespondToolCommand
+      await this.agent.respondTool(cmd.chatId, cmd.toolUseId, cmd.result)
+    })
+
+    this.subscribeCommand("stop_chat_pty", async (data) => {
+      const cmd = JSON.parse(data) as StopChatPtyCommand
+      this.agent.stopChatPty(cmd.chatId)
+    })
+
+    this.subscribeCommand("shutdown", async () => {
+      this.dispose()
+    })
+
+    // Flush to ensure subscriptions are visible to other connections
+    await this.nc.flush()
+
+    // Start heartbeat
+    this.heartbeatTimer = setInterval(() => this.publishHeartbeat(), this.heartbeatIntervalMs)
+    this.publishHeartbeat()
+  }
+
+  dispose(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = null
+    }
+    for (const sub of this.subscriptions) {
+      sub.unsubscribe()
+    }
+    this.subscriptions = []
+  }
+
+  private subscribeCommand(cmd: string, handler: (data: string) => Promise<void>): void {
+    const subject = runnerCmdSubject(this.runnerId, cmd)
+    const sub = this.nc.subscribe(subject)
+    this.subscriptions.push(sub)
+    // Observability (decision 0012): confirm each command subscription is actually
+    // established, and surface it if the subscription loop ever ends/errors (e.g. a
+    // permission denial would otherwise be silent — unlike the oauth sub which logs).
+    console.warn(LOG_PREFIX, `subscribed to command subject ${subject}`)
+
+    void (async () => {
+      try {
+        for await (const msg of sub) {
+          // Observability (decision 0012): log on receipt so we can tell whether a
+          // command actually reaches the runner (vs the subscription being silently
+          // denied or messages never delivered).
+          console.warn(LOG_PREFIX, `received command ${cmd} on ${subject}`)
+          try {
+            const data = decoder.decode(msg.data)
+            await handler(data)
+            msg.respond(encoder.encode(JSON.stringify({ ok: true })))
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            console.warn(LOG_PREFIX, `Runner command ${cmd} failed: ${message}`)
+            msg.respond(encoder.encode(JSON.stringify({ ok: false, error: message })))
+          }
+        }
+        console.warn(LOG_PREFIX, `command subscription ${subject} ended (iterator closed)`)
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        console.warn(LOG_PREFIX, `command subscription ${subject} ERRORED: ${message}`)
+      }
+    })()
+  }
+
+  private async register(): Promise<void> {
+    // Allow tests to simulate a protocol skew via RUNNER_PROTOCOL_VERSION env.
+    const protocolVersion = Number(process.env.RUNNER_PROTOCOL_VERSION ?? PROTOCOL_VERSION)
+
+    // Probe installed providers — defensive: a probe error excludes that provider, never crashes.
+    let capabilities: RunnerCapabilities
+    try {
+      capabilities = await this._probeProviders()
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      console.warn(LOG_PREFIX, `Capability probe failed (defaulting to empty): ${message}`)
+      capabilities = { providers: [] }
+    }
+
+    const registration: RunnerRegistration = {
+      runnerId: this.runnerId,
+      pid: process.pid,
+      startedAt: Date.now(),
+      providers: capabilities.providers,
+      protocolVersion,
+      capabilities,
+      lastSeenAt: Date.now(),
+    }
+    this.registration = registration
+    try {
+      const kvm = new Kvm(this.nc)
+      const kvStore = await kvm.create(RUNNER_REGISTRY_BUCKET, {
+        max_bytes: 1024 * 1024,
+      })
+      this.registryKv = kvStore
+      await kvStore.put(this.runnerId, encoder.encode(JSON.stringify(registration)))
+    } catch (error) {
+      // KV bucket may already exist — try to open instead
+      try {
+        const kvm = new Kvm(this.nc)
+        const kvStore = await kvm.open(RUNNER_REGISTRY_BUCKET)
+        this.registryKv = kvStore
+        await kvStore.put(this.runnerId, encoder.encode(JSON.stringify(registration)))
+      } catch (innerError) {
+        const message = innerError instanceof Error ? innerError.message : String(innerError)
+        console.warn(LOG_PREFIX, `Runner KV registration failed: ${message}`)
+      }
+    }
+  }
+
+  private publishHeartbeat(): void {
+    const heartbeat: RunnerHeartbeat = {
+      runnerId: this.runnerId,
+      activeChatIds: [...this.agent.activeTurns.keys()],
+      ts: Date.now(),
+    }
+    try {
+      this.nc.publish(
+        runnerHeartbeatSubject(this.runnerId),
+        encoder.encode(JSON.stringify(heartbeat))
+      )
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.warn(LOG_PREFIX, `runner heartbeat publish failed: ${message}`)
+    }
+    // Update lastSeenAt in KV on every heartbeat so the discover path (no live
+    // subscription) has a fresh TTL signal. Fire-and-forget; a missed write just
+    // means the cached value ages naturally — still bounded by heartbeatIntervalMs.
+    this.updateLastSeenAt()
+  }
+
+  private updateLastSeenAt(): void {
+    if (!this.registration) return
+    const updated: RunnerRegistration = { ...this.registration, lastSeenAt: Date.now() }
+    this.registration = updated
+    void (async () => {
+      try {
+        // Reuse the cached KV handle from register(); open once if absent.
+        if (!this.registryKv) {
+          this.registryKv = await new Kvm(this.nc).open(RUNNER_REGISTRY_BUCKET)
+        }
+        await this.registryKv.put(this.runnerId, encoder.encode(JSON.stringify(updated)))
+      } catch {
+        // Best-effort; drop the (possibly stale) handle so the next beat re-opens.
+        this.registryKv = null
+      }
+    })()
+  }
+
+  /** Test-only wrapper for the private heartbeat publisher. */
+  publishHeartbeatForTest(): void {
+    this.publishHeartbeat()
+  }
+}

package/src/runner/runner-pair.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Tests for the runner pair flow (PR2 Stage 2).
+ *
+ * Spins up a real embedded server on a dedicated port, exercises the
+ * POST /api/pairing/exchange path, and checks that writeRunnerCredential
+ * is called with the correct shape. Uses a real pairing code issued by
+ * the server (integration-style, same pattern as pairing-endpoints.test.ts).
+ *
+ * Also tests error propagation (expired/consumed → throws, unknown → throws).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdtempSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { startServer } from "../server/server"
+import { pairRunner } from "./runner-pair"
+import { readRunnerCredential } from "./runner-credential"
+
+type StartedServer = Awaited<ReturnType<typeof startServer>>
+
+async function post(port: number, pathname: string, body?: unknown): Promise<Response> {
+  return fetch(`http://127.0.0.1:${port}${pathname}`, {
+    method: "POST",
+    headers: body !== undefined ? { "Content-Type": "application/json" } : {},
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  })
+}
+
+describe("runner-pair (integration)", () => {
+  let started: StartedServer | null = null
+  let natsDataDir: string
+  let runnerHome: string
+  let savedRunnerHome: string | undefined
+
+  beforeEach(() => {
+    natsDataDir = mkdtempSync(join(tmpdir(), "pr2-pair-flow-nats-"))
+    runnerHome = mkdtempSync(join(tmpdir(), "pr2-pair-flow-home-"))
+    savedRunnerHome = process.env.TINKARIA_RUNNER_HOME
+    process.env.TINKARIA_RUNNER_HOME = runnerHome
+  })
+
+  afterEach(async () => {
+    await started?.stop()
+    started = null
+    rmSync(natsDataDir, { recursive: true, force: true })
+    rmSync(runnerHome, { recursive: true, force: true })
+    if (savedRunnerHome === undefined) {
+      delete process.env.TINKARIA_RUNNER_HOME
+    } else {
+      process.env.TINKARIA_RUNNER_HOME = savedRunnerHome
+    }
+    delete process.env.NATS_AUTH_MODE
+    delete process.env.NATS_DATA_DIR
+  })
+
+  test("pairRunner: exchange succeeds and credential is written", async () => {
+    process.env.NATS_AUTH_MODE = "callout"
+    process.env.NATS_DATA_DIR = natsDataDir
+    started = await startServer({ port: 4391, host: "127.0.0.1", strictPort: true })
+    const port = started.port
+
+    // Issue a pairing code via the server.
+    const issueRes = await post(port, "/api/pairing/code")
+    expect(issueRes.status).toBe(200)
+    const { code } = await issueRes.json() as { code: string }
+
+    // Run the pair flow.
+    await pairRunner({ serverUrl: `http://127.0.0.1:${port}`, code })
+
+    // Credential file should now exist and have the right shape.
+    const cred = await readRunnerCredential()
+    expect(cred).not.toBeNull()
+    expect(cred!.runnerId).toMatch(/^runner-/)
+    expect(typeof cred!.token).toBe("string")
+    expect(typeof cred!.natsUrl).toBe("string")
+    expect(typeof cred!.natsWsUrl).toBe("string")
+    expect(typeof cred!.pairedAt).toBe("number")
+    // Runner connects via the server's /nats-ws proxy (tunneled HTTP port),
+    // derived from the paired server URL — not the raw NATS TCP port.
+    expect(cred!.natsWsProxyUrl).toBe(`ws://127.0.0.1:${port}/nats-ws`)
+  }, 30_000)
+
+  test("pairRunner: consumed code throws with status 410", async () => {
+    process.env.NATS_AUTH_MODE = "callout"
+    process.env.NATS_DATA_DIR = natsDataDir
+    started = await startServer({ port: 4392, host: "127.0.0.1", strictPort: true })
+    const port = started.port
+
+    const { code } = await post(port, "/api/pairing/code").then((r) => r.json()) as { code: string }
+    // First exchange succeeds.
+    await pairRunner({ serverUrl: `http://127.0.0.1:${port}`, code })
+    // Second exchange of same code should throw (consumed).
+    await expect(pairRunner({ serverUrl: `http://127.0.0.1:${port}`, code })).rejects.toThrow(/consumed|410/i)
+  }, 30_000)
+
+  test("pairRunner: unknown code throws with status 400", async () => {
+    process.env.NATS_AUTH_MODE = "callout"
+    process.env.NATS_DATA_DIR = natsDataDir
+    started = await startServer({ port: 4393, host: "127.0.0.1", strictPort: true })
+    const port = started.port
+
+    await expect(
+      pairRunner({ serverUrl: `http://127.0.0.1:${port}`, code: "aaaaa-bbbbb-cccccc" })
+    ).rejects.toThrow(/unknown|400/i)
+  }, 30_000)
+})

package/src/runner/runner-pair.ts

@@ -0,0 +1,81 @@
+/**
+ * Runner pair flow (PR2 Stage 2).
+ *
+ * POSTs a pairing code to `POST /api/pairing/exchange` on the given server,
+ * then persists the returned credential via writeRunnerCredential.
+ *
+ * Usage (CLI subcommand wired in runner.ts):
+ *   bun run src/runner/runner.ts pair --server <url> --code <code>
+ */
+
+import { writeRunnerCredential } from "./runner-credential"
+
+export interface PairRunnerOptions {
+  serverUrl: string
+  code: string
+}
+
+/**
+ * Exchange a pairing code for a durable runner credential and write it to disk.
+ * Throws if the server returns a non-OK status (expired, consumed, unknown, etc.).
+ */
+export async function pairRunner({ serverUrl, code }: PairRunnerOptions): Promise<void> {
+  // The exchange RESPONSE carries the durable runner credential. Over plain HTTP
+  // to a non-loopback host, a network-path attacker could capture it. Loopback /
+  // WireGuard tailnet links are encrypted at the network layer; warn otherwise.
+  // (Hard TLS requirement for non-loopback pairing is a pre-multi-tenant gate — decision 0008.)
+  try {
+    const u = new URL(serverUrl)
+    const loopback = u.hostname === "127.0.0.1" || u.hostname === "localhost" || u.hostname === "::1"
+    if (u.protocol !== "https:" && !loopback) {
+      console.warn(
+        `[tinkaria] WARNING: pairing over non-loopback HTTP (${u.host}) — the runner credential is sent in the clear. Use HTTPS or pair over a WireGuard/tailnet link.`
+      )
+    }
+  } catch {
+    // malformed URL — let fetch surface the error below
+  }
+
+  const url = `${serverUrl.replace(/\/$/, "")}/api/pairing/exchange`
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code }),
+  })
+
+  if (!res.ok) {
+    let errorDetail: string
+    try {
+      const body = await res.json() as { error?: string }
+      errorDetail = body.error ?? res.statusText
+    } catch {
+      errorDetail = res.statusText
+    }
+    throw new Error(`Pairing exchange failed (${res.status}): ${errorDetail}`)
+  }
+
+  const { runnerId, token, natsUrl, natsWsUrl } = await res.json() as {
+    runnerId: string
+    token: string
+    natsUrl: string
+    natsWsUrl: string
+  }
+
+  // Derive the server's /nats-ws proxy URL from the server we paired against, so
+  // the runner connects over the SAME tunneled HTTP port as the browser (e.g.
+  // https://host -> wss://host/nats-ws) instead of the raw NATS TCP port, which
+  // is often not tunneled and can drop server->runner pushes over the tailnet.
+  let natsWsProxyUrl: string | undefined
+  try {
+    const u = new URL(serverUrl)
+    const wsProtocol = u.protocol === "https:" ? "wss:" : "ws:"
+    natsWsProxyUrl = `${wsProtocol}//${u.host}/nats-ws`
+  } catch {
+    // malformed server URL — leave undefined; runner falls back to natsUrl (TCP)
+  }
+
+  await writeRunnerCredential({ runnerId, token, natsUrl, natsWsUrl, natsWsProxyUrl, pairedAt: Date.now() })
+
+  console.warn(`[tinkaria] Runner paired — runnerId: ${runnerId}`)
+  console.warn(`[tinkaria] Credential written. Start the runner with: bun run src/runner/runner.ts`)
+}

package/src/runner/runner.test.ts

@@ -0,0 +1,135 @@
+import { describe, test, expect, afterEach } from "bun:test"
+import { NatsServer } from "@lagz0ne/nats-embedded"
+import { connect } from "@nats-io/transport-node"
+import { jetstreamManager, RetentionPolicy, StorageType } from "@nats-io/jetstream"
+import { Kvm } from "@nats-io/kv"
+import { mkdtempSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import {
+  runnerCmdSubject,
+  RUNNER_EVENTS_STREAM,
+  ALL_RUNNER_EVENTS,
+  RUNNER_REGISTRY_BUCKET,
+  type RunnerRegistration,
+} from "../shared/runner-protocol"
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+describe("runner process", () => {
+  let server: NatsServer
+  let proc: ReturnType<typeof Bun.spawn> | null = null
+  let tmpDir: string | null = null
+
+  afterEach(async () => {
+    if (proc) {
+      proc.kill("SIGTERM")
+      await proc.exited
+      proc = null
+    }
+    await server?.stop()
+    if (tmpDir) {
+      rmSync(tmpDir, { recursive: true, force: true })
+      tmpDir = null
+    }
+  })
+
+  test("starts, registers in KV, and accepts start_turn commands", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "runner-test-"))
+    server = await NatsServer.start({ jetstream: true, storeDir: tmpDir })
+    const nc = await connect({ servers: server.url })
+
+    // Create required stream
+    const jsm = await jetstreamManager(nc)
+    await jsm.streams.add({
+      name: RUNNER_EVENTS_STREAM,
+      subjects: [ALL_RUNNER_EVENTS],
+      retention: RetentionPolicy.Limits,
+      storage: StorageType.File,
+      max_age: 5 * 60 * 1_000_000_000,
+      max_msgs: 10_000,
+      max_bytes: 64 * 1024 * 1024,
+    })
+
+    const runnerId = `test-runner-${Date.now()}`
+    proc = Bun.spawn(["bun", "run", "src/runner/runner.ts"], {
+      env: {
+        ...process.env,
+        NATS_URL: server.url,
+        RUNNER_ID: runnerId,
+      },
+      stdio: ["ignore", "pipe", "inherit"],
+    })
+
+    // Wait for runner to start and register
+    await new Promise((r) => setTimeout(r, 1000))
+
+    // Verify KV registration
+    const kvm = new Kvm(nc)
+    const kvStore = await kvm.open(RUNNER_REGISTRY_BUCKET)
+    const entry = await kvStore.get(runnerId)
+    expect(entry).toBeDefined()
+    const reg = JSON.parse(decoder.decode(entry!.value)) as RunnerRegistration
+    expect(reg.runnerId).toBe(runnerId)
+
+    // Verify it responds to commands (start_turn will fail since there's no real Claude API key, but it should respond)
+    const reply = await nc.request(
+      runnerCmdSubject(runnerId, "start_turn"),
+      encoder.encode(JSON.stringify({
+        chatId: "test-chat",
+        provider: "claude",
+        content: "test",
+        model: "test-model",
+        planMode: false,
+        appendUserPrompt: true,
+        workspaceLocalPath: "/tmp",
+        sessionToken: null,
+        chatTitle: "Test",
+        existingMessageCount: 0,
+        workspaceId: "p1",
+      })),
+      { timeout: 5000 }
+    )
+    const response = JSON.parse(decoder.decode(reply.data))
+    // The start_turn will succeed (the turn factory will fail, but the command handler responds ok before the turn runs)
+    expect(response).toHaveProperty("ok")
+
+    await nc.drain()
+  })
+
+  test("shuts down cleanly on SIGTERM", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "runner-test-"))
+    server = await NatsServer.start({ jetstream: true, storeDir: tmpDir })
+    const nc = await connect({ servers: server.url })
+
+    const jsm = await jetstreamManager(nc)
+    await jsm.streams.add({
+      name: RUNNER_EVENTS_STREAM,
+      subjects: [ALL_RUNNER_EVENTS],
+      retention: RetentionPolicy.Limits,
+      storage: StorageType.File,
+      max_age: 5 * 60 * 1_000_000_000,
+      max_msgs: 10_000,
+      max_bytes: 64 * 1024 * 1024,
+    })
+
+    proc = Bun.spawn(["bun", "run", "src/runner/runner.ts"], {
+      env: {
+        ...process.env,
+        NATS_URL: server.url,
+        RUNNER_ID: "runner-sigterm-test",
+      },
+      stdio: ["ignore", "pipe", "inherit"],
+    })
+
+    await new Promise((r) => setTimeout(r, 500))
+
+    proc.kill("SIGTERM")
+    const exitCode = await proc.exited
+    expect(exitCode).toBe(0)
+    proc = null
+
+    await nc.drain()
+  })
+})