@runuai/host 0.4.3 → 0.5.0

package/db/migrations/0009_host_agent_sessions.sql

@@ -0,0 +1,15 @@
+-- ADR-061: durable agent sessions. One row per (task, agent) tracking the
+-- live in-container runner and how far the host has consumed its outbox —
+-- the byte offset is what makes a host restart resume instead of respawn.
+CREATE TABLE `host_agent_sessions` (
+	`task_id` text NOT NULL,
+	`agent_id` text NOT NULL,
+	`session_dir` text NOT NULL,
+	`container_name` text NOT NULL,
+	`kind` text NOT NULL,
+	`outbox_offset` integer DEFAULT 0 NOT NULL,
+	`status` text DEFAULT 'running' NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL,
+	PRIMARY KEY(`task_id`, `agent_id`)
+);

package/db/migrations/meta/_journal.json

@@ -64,6 +64,13 @@
       "when": 1779900009000,
       "tag": "0008_host_mcp_connections",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1779900010000,
+      "tag": "0009_host_agent_sessions",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -121,6 +121,39 @@ export type NewHostProjectEnv = typeof hostProjectEnv.$inferInsert;
 // is sealed with the host master key in single-column `ct.nonce` base64 form
 // (same packing as host_project_env). The cloud only ever holds the non-secret
 // metadata; acks never echo secrets back.
+// ---------------------------------------------------------------------------
+// host_agent_sessions — ADR-061 durable agent sessions. One row per
+// (task, agent): where the live in-container runner's session dir is and how
+// far the host has consumed its outbox. The byte offset is what turns a host
+// restart into "resume tailing" instead of "kill and respawn"; attachability
+// itself is judged live off the runner's heartbeat file, not this row.
+// ---------------------------------------------------------------------------
+
+export const hostAgentSessions = sqliteTable(
+  "host_agent_sessions",
+  {
+    taskId: text("task_id").notNull(),
+    agentId: text("agent_id").notNull(),
+    // Host-side absolute path of the session dir (on the workspace mount,
+    // identical in-container — task-up bind-mounts the workspace at its own
+    // host path).
+    sessionDir: text("session_dir").notNull(),
+    containerName: text("container_name").notNull(),
+    kind: text("kind").notNull(), // "claude" | "codex" | ...
+    outboxOffset: integer("outbox_offset", { mode: "number" })
+      .notNull()
+      .default(0),
+    status: text("status").notNull().default("running"), // running|closed
+    createdAt: integer("created_at", { mode: "number" }).notNull(),
+    updatedAt: integer("updated_at", { mode: "number" }).notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.taskId, t.agentId] }),
+  }),
+);
+
+export type HostAgentSession = typeof hostAgentSessions.$inferSelect;
+
 export const mcpConnections = sqliteTable("host_mcp_connections", {
   id: text("id").primaryKey(), // cloud uai_mcp_connections id
   userId: text("user_id").notNull(),

package/lib/agents/claude.ts

@@ -21,7 +21,7 @@
  */
 
 import { newId } from "../ulid";
-import { dockerExecArgs, LineProcess } from "./proc";
+import { createAgentTransport, type LineTransport } from "./transport";
 import { register } from "./registry";
 import type {
   AgentEvent,
@@ -193,11 +193,12 @@ export class ClaudeSession implements AgentSession {
   readonly agentId: string;
   readonly kind: AgentKind = "claude";
 
-  private readonly proc: LineProcess;
+  private readonly proc: LineTransport;
   private readonly handlers = new Set<AgentEventHandler>();
   private closed = false;
 
   constructor(args: {
+    taskId: string;
     agent: RosterAgent;
     containerName: string;
     systemPreamble: string;
@@ -231,16 +232,20 @@ export class ClaudeSession implements AgentSession {
     // it needs CLAUDE_CODE_OAUTH_TOKEN (from `claude setup-token`) or an
     // API key. These live in the host-agent's env (never the cloud, ADR-015);
     // only ones actually set are forwarded.
-    const { command, args: argv } = dockerExecArgs(
-      args.containerName,
-      "claude",
+    // ADR-061: durable by default — the CLI is owned by an in-container
+    // runner and survives host restarts (attach resumes it); legacy pipes
+    // behind UAI_DURABLE_SESSIONS=0. Claude is host-side stateless, so a
+    // live runner can be re-attached (allowAttach).
+    this.proc = createAgentTransport({
+      taskId: args.taskId,
+      agentId: this.agentId,
+      containerName: args.containerName,
+      cli: "claude",
       cliArgs,
-      ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
-      args.agentEnv ?? {},
-    );
-    this.proc = new LineProcess({
-      command,
-      args: argv,
+      passEnv: ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+      explicitEnv: args.agentEnv ?? {},
+      allowAttach: true,
+      kind: "claude",
       debugLabel: `claude:${this.agentId}`,
     });
     this.proc.onLine((line) => {
@@ -349,6 +354,6 @@ register({
         process.env.ANTHROPIC_API_KEY ||
         process.env.ANTHROPIC_AUTH_TOKEN,
     ),
-  create: async ({ agent, containerName, systemPreamble, agentEnv }) =>
-    new ClaudeSession({ agent, containerName, systemPreamble, agentEnv }),
+  create: async ({ taskId, agent, containerName, systemPreamble, agentEnv }) =>
+    new ClaudeSession({ taskId, agent, containerName, systemPreamble, agentEnv }),
 });

package/lib/agents/codex.ts

@@ -33,7 +33,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { newId } from "../ulid";
-import { dockerExecArgs, LineProcess } from "./proc";
+import { createAgentTransport, type LineTransport } from "./transport";
 import { register } from "./registry";
 import type {
   AgentEvent,
@@ -213,7 +213,7 @@ export class CodexSession implements AgentSession {
   readonly agentId: string;
   readonly kind: AgentKind = "codex";
 
-  private readonly proc: LineProcess;
+  private readonly proc: LineTransport;
   private readonly handlers = new Set<AgentEventHandler>();
   private readonly systemPreamble: string;
   private closed = false;
@@ -231,6 +231,7 @@ export class CodexSession implements AgentSession {
   private readonly ready: Promise<void>;
 
   constructor(args: {
+    taskId: string;
     agent: RosterAgent;
     containerName: string;
     systemPreamble: string;
@@ -251,16 +252,22 @@ export class CodexSession implements AgentSession {
       codexArgs.push("-c", `model_reasoning_effort=${args.agent.effort}`);
     }
     codexArgs.push("app-server");
-    const { command, args: argv } = dockerExecArgs(
-      args.containerName,
-      "codex",
-      codexArgs,
-      [],
-      args.agentEnv ?? {},
-    );
-    this.proc = new LineProcess({
-      command,
-      args: argv,
+    // ADR-061: the CLI is owned by an in-container runner (durable across
+    // host restarts); legacy pipes behind UAI_DURABLE_SESSIONS=0. Codex
+    // re-handshakes per host process (initialize + thread/start live in this
+    // object), so a leftover runner is never attached — allowAttach:false
+    // stops it and spawns fresh. Its final output before the stop still
+    // reaches the cloud via the outbox.
+    this.proc = createAgentTransport({
+      taskId: args.taskId,
+      agentId: this.agentId,
+      containerName: args.containerName,
+      cli: "codex",
+      cliArgs: codexArgs,
+      passEnv: [],
+      explicitEnv: args.agentEnv ?? {},
+      allowAttach: false,
+      kind: "codex",
       debugLabel: `codex:${this.agentId}`,
     });
     this.proc.onLine((line) => this.onLine(line));
@@ -538,6 +545,6 @@ register({
     existsSync(
       join(process.env.UAI_OWNER_HOME?.trim() || homedir(), ".codex", "auth.json"),
     ),
-  create: async ({ agent, containerName, systemPreamble, agentEnv }) =>
-    new CodexSession({ agent, containerName, systemPreamble, agentEnv }),
+  create: async ({ taskId, agent, containerName, systemPreamble, agentEnv }) =>
+    new CodexSession({ taskId, agent, containerName, systemPreamble, agentEnv }),
 });

package/lib/agents/durable-proc.ts

@@ -0,0 +1,306 @@
+/**
+ * DurableProcess (ADR-061) — LineProcess's durable twin. Instead of holding
+ * the agent CLI's pipes, it talks to the in-container runner
+ * (runner/runner.mjs) through two append-only JSONL files on the
+ * task-workspace bind mount:
+ *
+ *   writeLine()  → append to <sessionDir>/inbox.jsonl
+ *   onLine()     ← poll-tail <sessionDir>/outbox.jsonl from a byte offset
+ *
+ * The CLI's lifetime is decoupled from this object: dropping it (host
+ * restart) leaves the runner and CLI running; `attach()` with the persisted
+ * outbox offset resumes exactly where consumption stopped. `close()` is the
+ * real teardown — it sends the runner a stop control.
+ *
+ * Exit is observed via the runner's `{"__uai":"exit"}` meta line, with a
+ * stale-heartbeat check as the backstop for a killed container. Meta lines
+ * never reach onLine handlers — adapters see the same protocol stream
+ * LineProcess gave them.
+ */
+
+import { spawn } from "node:child_process";
+import {
+  closeSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  promises as fsp,
+  readSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ExitHandler, LineHandler } from "./proc";
+
+const POLL_MS = 75;
+/** Runner beats every 5 s; 25 s of silence without an exit meta = dead. */
+const HEARTBEAT_STALE_MS = 25_000;
+/** After close(), how long to wait for the exit meta before giving up. */
+const CLOSE_GRACE_MS = 8_000;
+
+/** Host-side absolute path of the bundled in-container runner script. */
+export function runnerScriptPath(): string {
+  return fileURLToPath(new URL("../../runner/runner.mjs", import.meta.url));
+}
+
+export interface DurableProcessOptions {
+  /** Session dir as seen FROM THE HOST (on the workspace bind mount). */
+  hostSessionDir: string;
+  /**
+   * Command that launches the runner (e.g. `docker exec -d … node
+   * /opt/uai/runner.mjs <containerSessionDir> -- claude …`). Omit to ATTACH
+   * to a runner that is already alive (boot reconciliation).
+   */
+  spawnCommand?: { command: string; args: string[] };
+  /** Resume consumption from this outbox byte offset (attach path). */
+  initialOutboxOffset?: number;
+  /** Called after each poll batch whose lines were delivered — persist this
+   *  offset so a host restart resumes here instead of replaying. */
+  onOffsetAdvance?: (offset: number) => void;
+  /** Called the moment close() is requested (before the runner has actually
+   *  died) — lets the owner mark the session unattachable immediately, so a
+   *  re-create during the teardown grace window spawns fresh instead of
+   *  attaching to a dying runner. */
+  onCloseRequested?: () => void;
+  /** Mirrors LineProcess: log raw traffic when UAI_DEBUG_AGENTS is set. */
+  debugLabel?: string;
+}
+
+interface RunnerMeta {
+  __uai: string;
+  code?: number | null;
+  stderrTail?: string;
+}
+
+export class DurableProcess {
+  private readonly dir: string;
+  private readonly outboxPath: string;
+  private readonly inboxPath: string;
+  private readonly heartbeatPath: string;
+
+  private readonly lineHandlers = new Set<LineHandler>();
+  private readonly exitHandlers = new Set<ExitHandler>();
+
+  private offset: number;
+  private lineBuf = "";
+  private stderrBuf = "";
+  private closed = false;
+  private detached = false;
+  private sawSpawnMeta = false;
+  private readonly startedAt = Date.now();
+  private poller: ReturnType<typeof setInterval> | null = null;
+  private closeTimer: ReturnType<typeof setTimeout> | null = null;
+  private inboxChain: Promise<void> = Promise.resolve();
+  private readonly onOffsetAdvance: ((offset: number) => void) | null;
+  private readonly onCloseRequested: (() => void) | null;
+  private readonly debug: string | null;
+
+  constructor(opts: DurableProcessOptions) {
+    this.dir = opts.hostSessionDir;
+    this.outboxPath = join(this.dir, "outbox.jsonl");
+    this.inboxPath = join(this.dir, "inbox.jsonl");
+    this.heartbeatPath = join(this.dir, "heartbeat");
+    this.offset = opts.initialOutboxOffset ?? 0;
+    this.onOffsetAdvance = opts.onOffsetAdvance ?? null;
+    this.onCloseRequested = opts.onCloseRequested ?? null;
+    this.debug =
+      opts.debugLabel && process.env.UAI_DEBUG_AGENTS ? opts.debugLabel : null;
+
+    mkdirSync(this.dir, { recursive: true });
+
+    if (opts.spawnCommand) {
+      if (this.debug) {
+        this.log(
+          `spawn: ${opts.spawnCommand.command} ${opts.spawnCommand.args.join(" ")}`,
+        );
+      }
+      const child = spawn(opts.spawnCommand.command, opts.spawnCommand.args, {
+        stdio: ["ignore", "ignore", "pipe"],
+      });
+      child.stderr?.setEncoding("utf8");
+      child.stderr?.on("data", (chunk: string) => {
+        this.stderrBuf = (this.stderrBuf + chunk).slice(-8192);
+      });
+      // `docker exec -d` exits 0 immediately on success; non-zero means the
+      // runner never started (bad container, bad mount) — fail loudly now.
+      child.on("exit", (code) => {
+        if (code !== null && code !== 0) this.finish(null);
+      });
+      child.on("error", () => this.finish(null));
+      child.unref();
+    } else {
+      this.sawSpawnMeta = true; // attach: the runner pre-exists
+    }
+
+    this.poller = setInterval(() => this.poll(), POLL_MS);
+  }
+
+  private log(msg: string): void {
+    console.error(`[uai-agent ${this.debug}] ${msg}`);
+  }
+
+  // ---- outbox tail ---------------------------------------------------------
+
+  private poll(): void {
+    if (this.closed || this.detached) return;
+    let fd: number;
+    try {
+      fd = openSync(this.outboxPath, "r");
+    } catch {
+      this.checkLiveness();
+      return; // outbox not created yet
+    }
+    const before = this.offset;
+    try {
+      const size = fstatSync(fd).size;
+      while (this.offset < size) {
+        const len = Math.min(size - this.offset, 256 * 1024);
+        const buf = Buffer.alloc(len);
+        const read = readSync(fd, buf, 0, len, this.offset);
+        if (read <= 0) break;
+        this.offset += read;
+        this.lineBuf += buf.toString("utf8", 0, read);
+        this.drainLines();
+      }
+    } finally {
+      closeSync(fd);
+    }
+    if (this.offset !== before && this.onOffsetAdvance && !this.closed) {
+      try {
+        this.onOffsetAdvance(this.offset);
+      } catch {
+        // Persistence hiccup — the next batch retries with a larger offset.
+      }
+    }
+    this.checkLiveness();
+  }
+
+  private drainLines(): void {
+    let nl: number;
+    while ((nl = this.lineBuf.indexOf("\n")) >= 0) {
+      const line = this.lineBuf.slice(0, nl).trim();
+      this.lineBuf = this.lineBuf.slice(nl + 1);
+      if (line.length === 0) continue;
+      if (line.startsWith('{"__uai"')) {
+        this.handleMeta(line);
+        continue;
+      }
+      if (this.debug) this.log(`<- ${line.slice(0, 1000)}`);
+      for (const h of this.lineHandlers) {
+        try {
+          h(line);
+        } catch {
+          // A broken handler must not wedge the tail loop.
+        }
+      }
+    }
+  }
+
+  private handleMeta(line: string): void {
+    let meta: RunnerMeta;
+    try {
+      meta = JSON.parse(line) as RunnerMeta;
+    } catch {
+      return;
+    }
+    if (meta.__uai === "spawn") {
+      this.sawSpawnMeta = true;
+    } else if (meta.__uai === "exit") {
+      if (typeof meta.stderrTail === "string" && meta.stderrTail) {
+        this.stderrBuf = meta.stderrTail.slice(-8192);
+      }
+      if (this.debug) this.log(`exit meta: code ${meta.code ?? null}`);
+      this.finish(typeof meta.code === "number" ? meta.code : null);
+    }
+  }
+
+  /** Backstop: no exit meta, but the runner stopped beating → it's gone. */
+  private checkLiveness(): void {
+    const path = this.sawSpawnMeta ? this.heartbeatPath : null;
+    if (!path) {
+      // Runner never wrote anything; give the spawn a grace window.
+      if (Date.now() - this.startedAt > HEARTBEAT_STALE_MS) this.finish(null);
+      return;
+    }
+    try {
+      const age = Date.now() - statSync(path).mtimeMs;
+      if (age > HEARTBEAT_STALE_MS) this.finish(null);
+    } catch {
+      if (Date.now() - this.startedAt > HEARTBEAT_STALE_MS) this.finish(null);
+    }
+  }
+
+  private finish(code: number | null): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.poller) clearInterval(this.poller);
+    if (this.closeTimer) clearTimeout(this.closeTimer);
+    for (const h of this.exitHandlers) h(code);
+  }
+
+  // ---- LineProcess-compatible surface ---------------------------------------
+
+  onLine(handler: LineHandler): void {
+    this.lineHandlers.add(handler);
+  }
+
+  onExit(handler: ExitHandler): void {
+    this.exitHandlers.add(handler);
+  }
+
+  /** Serialise `value` as one JSONL line appended to the runner's inbox. */
+  writeLine(value: unknown): void {
+    if (this.closed || this.detached) return;
+    const json = JSON.stringify(value);
+    if (this.debug) this.log(`-> ${json.slice(0, 1000)}`);
+    // Chain appends so concurrent writes can't interleave bytes.
+    this.inboxChain = this.inboxChain
+      .then(() => fsp.appendFile(this.inboxPath, `${json}\n`))
+      .catch(() => {
+        // Disk error — liveness checks will surface a dead session.
+      });
+  }
+
+  get stderrTail(): string {
+    return this.stderrBuf;
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  /** Consumed-outbox byte offset — persist this to survive host restarts. */
+  get outboxOffset(): number {
+    return this.offset;
+  }
+
+  /**
+   * Stop consuming WITHOUT touching the runner — the host-restart path in
+   * miniature (a replaced consumer, a shutting-down host). The CLI lives on;
+   * a later attach() resumes from the persisted offset.
+   */
+  detach(): void {
+    if (this.detached || this.closed) return;
+    this.detached = true;
+    if (this.poller) clearInterval(this.poller);
+    if (this.closeTimer) clearTimeout(this.closeTimer);
+  }
+
+  /** Real teardown: ask the runner to stop its CLI, then observe the exit. */
+  async close(): Promise<void> {
+    if (this.closed || this.detached) return;
+    try {
+      this.onCloseRequested?.();
+    } catch {
+      // Bookkeeping only — never blocks the teardown itself.
+    }
+    try {
+      await this.inboxChain;
+      await fsp.appendFile(this.inboxPath, '{"__uai":"stop"}\n');
+    } catch {
+      // Inbox unwritable — fall through to the grace timer.
+    }
+    this.closeTimer = setTimeout(() => this.finish(null), CLOSE_GRACE_MS);
+  }
+}

package/lib/agents/transport.ts

@@ -0,0 +1,229 @@
+/**
+ * Agent transport selection (ADR-061). Adapters call createAgentTransport()
+ * where they used to build a LineProcess directly; it returns either:
+ *
+ *  - legacy pipes (`docker exec -i <cli>`, LineProcess) when
+ *    UAI_DURABLE_SESSIONS=0, or
+ *  - the durable path: an in-container runner owning the CLI, driven through
+ *    inbox/outbox files on the workspace mount (DurableProcess).
+ *
+ * Durable mode makes host restarts transparent WITHOUT orchestrator
+ * changes: the orchestrator's lazy respawn calls factory.create as always,
+ * and this helper quietly ATTACHES to a still-live runner (fresh heartbeat +
+ * a `running` host_agent_sessions row) at the persisted outbox offset
+ * instead of spawning a new CLI — the agent's in-memory context survives.
+ * Adapters that re-handshake per process (codex) pass allowAttach:false and
+ * get a fresh runner each create — the stale predecessor is asked to stop
+ * via its inbox first.
+ *
+ * The runner script is COPIED into each session dir (not bind-mounted):
+ * every existing container already sees the workspace at its identical host
+ * path, so durable sessions work for containers created before this
+ * feature, and each spawn ships the runner version matching this host.
+ */
+
+import { copyFileSync, mkdirSync, statSync, promises as fsp } from "node:fs";
+import { join } from "node:path";
+
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../db";
+import { taskWorkspaceDir } from "../env";
+import { DurableProcess, runnerScriptPath } from "./durable-proc";
+import { LineProcess, dockerExecArgs, type ExitHandler, type LineHandler } from "./proc";
+
+/** The shared surface adapters program against (LineProcess's shape). */
+export interface LineTransport {
+  onLine(handler: LineHandler): void;
+  onExit(handler: ExitHandler): void;
+  writeLine(value: unknown): void;
+  readonly stderrTail: string;
+  readonly isClosed: boolean;
+  close(): Promise<void>;
+}
+
+export interface AgentTransportOptions {
+  taskId: string;
+  agentId: string;
+  containerName: string;
+  /** CLI + args exactly as they'd follow `docker exec -i <container>`. */
+  cli: string;
+  cliArgs: string[];
+  /** Env names forwarded from the host's own env (`-e NAME`). */
+  passEnv?: string[];
+  /** Explicit per-exec env values (`-e NAME=value`). */
+  explicitEnv?: Record<string, string>;
+  /**
+   * Whether a live runner from a previous host process may be attached to.
+   * True for stateless adapters (claude); false for ones whose host-side
+   * protocol state can't outlive the host process (codex handshake).
+   */
+  allowAttach: boolean;
+  kind: string;
+  debugLabel?: string;
+}
+
+/** Runner heartbeat is 5 s; older than this = not attachable. */
+const ATTACH_HEARTBEAT_FRESH_MS = 20_000;
+
+function durableEnabled(): boolean {
+  return process.env.UAI_DURABLE_SESSIONS !== "0";
+}
+
+export function createAgentTransport(opts: AgentTransportOptions): LineTransport {
+  if (!durableEnabled()) {
+    const { command, args } = dockerExecArgs(
+      opts.containerName,
+      opts.cli,
+      opts.cliArgs,
+      opts.passEnv ?? [],
+      opts.explicitEnv ?? {},
+    );
+    return new LineProcess({ command, args, debugLabel: opts.debugLabel });
+  }
+
+  const db = getDb();
+  const row = db
+    .select()
+    .from(schema.hostAgentSessions)
+    .where(
+      and(
+        eq(schema.hostAgentSessions.taskId, opts.taskId),
+        eq(schema.hostAgentSessions.agentId, opts.agentId),
+      ),
+    )
+    .get();
+
+  const persistOffset = (offset: number): void => {
+    db.update(schema.hostAgentSessions)
+      .set({ outboxOffset: offset, updatedAt: Date.now() })
+      .where(
+        and(
+          eq(schema.hostAgentSessions.taskId, opts.taskId),
+          eq(schema.hostAgentSessions.agentId, opts.agentId),
+        ),
+      )
+      .run();
+  };
+  const markClosed = (): void => {
+    db.update(schema.hostAgentSessions)
+      .set({ status: "closed", updatedAt: Date.now() })
+      .where(
+        and(
+          eq(schema.hostAgentSessions.taskId, opts.taskId),
+          eq(schema.hostAgentSessions.agentId, opts.agentId),
+        ),
+      )
+      .run();
+  };
+
+  // ---- Attach: a previous host process left this agent's runner alive. ----
+  if (opts.allowAttach && row && row.status === "running" && heartbeatFresh(row.sessionDir)) {
+    const proc = new DurableProcess({
+      hostSessionDir: row.sessionDir,
+      initialOutboxOffset: row.outboxOffset,
+      onOffsetAdvance: persistOffset,
+      onCloseRequested: markClosed,
+      debugLabel: opts.debugLabel,
+    });
+    proc.onExit(markClosed);
+    return proc;
+  }
+
+  // ---- Spawn a fresh runner, asking any predecessor to stop. --------------
+  // Unconditional (not gated on row.status): a runner falsely marked closed
+  // by a stale-heartbeat verdict may still be alive, and a stop appended to
+  // a dead session's inbox is harmless — this is what guarantees one live
+  // CLI per (task, agent).
+  if (row) {
+    void fsp
+      .appendFile(join(row.sessionDir, "inbox.jsonl"), '{"__uai":"stop"}\n')
+      .catch(() => {
+        // Dir already gone / runner already dead — nothing to stop.
+      });
+  }
+
+  const sessionDir = join(
+    taskWorkspaceDir(opts.taskId),
+    ".uai",
+    "sessions",
+    opts.agentId,
+    String(Date.now()),
+  );
+  mkdirSync(sessionDir, { recursive: true });
+  // Ship this host's runner with the session: works in containers created
+  // before this feature (the workspace is mounted at its host path) and
+  // never skews against the host version.
+  const runnerInSession = join(sessionDir, "runner.mjs");
+  copyFileSync(runnerScriptPath(), runnerInSession);
+
+  const envArgs: string[] = [];
+  for (const name of opts.passEnv ?? []) {
+    if (process.env[name]) envArgs.push("-e", name);
+  }
+  for (const [name, value] of Object.entries(opts.explicitEnv ?? {})) {
+    envArgs.push("-e", `${name}=${value}`);
+  }
+
+  const proc = new DurableProcess({
+    hostSessionDir: sessionDir,
+    onOffsetAdvance: persistOffset,
+    onCloseRequested: markClosed,
+    debugLabel: opts.debugLabel,
+    spawnCommand: {
+      command: "docker",
+      args: [
+        "exec",
+        "-d",
+        ...envArgs,
+        opts.containerName,
+        "node",
+        runnerInSession, // identical path in-container (workspace self-mount)
+        sessionDir,
+        "--",
+        opts.cli,
+        ...opts.cliArgs,
+      ],
+    },
+  });
+
+  const now = Date.now();
+  db.insert(schema.hostAgentSessions)
+    .values({
+      taskId: opts.taskId,
+      agentId: opts.agentId,
+      sessionDir,
+      containerName: opts.containerName,
+      kind: opts.kind,
+      outboxOffset: 0,
+      status: "running",
+      createdAt: now,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [schema.hostAgentSessions.taskId, schema.hostAgentSessions.agentId],
+      set: {
+        sessionDir,
+        containerName: opts.containerName,
+        kind: opts.kind,
+        outboxOffset: 0,
+        status: "running",
+        updatedAt: now,
+      },
+    })
+    .run();
+
+  proc.onExit(markClosed);
+  return proc;
+}
+
+function heartbeatFresh(sessionDir: string): boolean {
+  try {
+    return (
+      Date.now() - statSync(join(sessionDir, "heartbeat")).mtimeMs <
+      ATTACH_HEARTBEAT_FRESH_MS
+    );
+  } catch {
+    return false;
+  }
+}

package/lib/mcp-connections.ts

@@ -368,31 +368,23 @@ async function oauthComplete(connectionId: string, code: string): Promise<McpAck
     throw new Error("connection has no pending OAuth flow");
   }
 
-  const body = new URLSearchParams({
-    grant_type: "authorization_code",
-    code,
-    redirect_uri: row.redirectUri,
-    client_id: row.clientId,
-    code_verifier: unpack(row.pkceVerifierEnc),
-    // RFC 8707, mirrored from the authorize request.
-    resource: row.url,
-  });
-  const headers: Record<string, string> = {
-    "content-type": "application/x-www-form-urlencoded",
-    accept: "application/json",
-  };
-  if (row.clientSecretEnc) {
-    headers.authorization =
-      "Basic " +
-      Buffer.from(`${row.clientId}:${unpack(row.clientSecretEnc)}`).toString(
-        "base64",
-      );
-  }
-  const res = await timedFetch(row.tokenEndpoint, { method: "POST", headers, body });
-  const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-  if (!res.ok || typeof json.access_token !== "string") {
+  const { ok, status, json } = await postTokenEndpoint(
+    row.tokenEndpoint,
+    {
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: row.redirectUri,
+      client_id: row.clientId,
+      code_verifier: unpack(row.pkceVerifierEnc),
+      // RFC 8707, mirrored from the authorize request.
+      resource: row.url,
+    },
+    row.clientId,
+    row.clientSecretEnc ? unpack(row.clientSecretEnc) : undefined,
+  );
+  if (!ok || typeof json.access_token !== "string") {
     const detail =
-      typeof json.error === "string" ? json.error : `status ${res.status}`;
+      typeof json.error === "string" ? json.error : `status ${status}`;
     throw new Error(`token exchange failed (${detail})`);
   }
 
@@ -473,6 +465,54 @@ export async function authHeaderFor(
   return { name: "authorization", value: `Bearer ${secret.accessToken}` };
 }
 
+/**
+ * POST a token-endpoint request. A client secret rides HTTP Basic first
+ * (RFC 6749's MUST-support method, what DCR vendors expect); on failure it
+ * retries once with `client_secret` in the body (client_secret_post) —
+ * some manual-creds vendors (Slack's user-token endpoint) only read body
+ * credentials and answer Basic with bad_client_secret.
+ */
+async function postTokenEndpoint(
+  tokenEndpoint: string,
+  params: Record<string, string>,
+  clientId: string,
+  clientSecret: string | undefined,
+): Promise<{ ok: boolean; status: number; json: Record<string, unknown> }> {
+  const attempt = async (mode: "basic" | "post") => {
+    const body = new URLSearchParams(params);
+    const headers: Record<string, string> = {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json",
+    };
+    if (clientSecret) {
+      if (mode === "basic") {
+        headers.authorization =
+          "Basic " +
+          Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+      } else {
+        body.set("client_secret", clientSecret);
+      }
+    }
+    const res = await timedFetch(tokenEndpoint, {
+      method: "POST",
+      headers,
+      body,
+    });
+    const json = (await res.json().catch(() => ({}))) as Record<
+      string,
+      unknown
+    >;
+    return {
+      ok: res.ok && typeof json.access_token === "string",
+      status: res.status,
+      json,
+    };
+  };
+  const basic = await attempt("basic");
+  if (basic.ok || !clientSecret) return basic;
+  return attempt("post");
+}
+
 async function refreshTokens(
   row: schema.McpConnection,
   secret: OauthSecret,
@@ -480,27 +520,19 @@ async function refreshTokens(
   if (!secret.refreshToken || !row.tokenEndpoint || !row.clientId) {
     throw new Error("access token expired and no refresh token is stored");
   }
-  const body = new URLSearchParams({
-    grant_type: "refresh_token",
-    refresh_token: secret.refreshToken,
-    client_id: row.clientId,
-    resource: row.url,
-  });
-  const headers: Record<string, string> = {
-    "content-type": "application/x-www-form-urlencoded",
-    accept: "application/json",
-  };
-  if (row.clientSecretEnc) {
-    headers.authorization =
-      "Basic " +
-      Buffer.from(`${row.clientId}:${unpack(row.clientSecretEnc)}`).toString(
-        "base64",
-      );
-  }
-  const res = await timedFetch(row.tokenEndpoint, { method: "POST", headers, body });
-  const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-  if (!res.ok || typeof json.access_token !== "string") {
-    throw new Error(`token refresh failed (status ${res.status})`);
+  const { ok, status, json } = await postTokenEndpoint(
+    row.tokenEndpoint,
+    {
+      grant_type: "refresh_token",
+      refresh_token: secret.refreshToken,
+      client_id: row.clientId,
+      resource: row.url,
+    },
+    row.clientId,
+    row.clientSecretEnc ? unpack(row.clientSecretEnc) : undefined,
+  );
+  if (!ok || typeof json.access_token !== "string") {
+    throw new Error(`token refresh failed (status ${status})`);
   }
   const next: OauthSecret = {
     accessToken: json.access_token,

package/lib/mcp-gateway.ts

@@ -19,7 +19,7 @@
 import { appendFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { randomBytes, timingSafeEqual } from "node:crypto";
-import { Readable } from "node:stream";
+import { Readable, pipeline } from "node:stream";
 import { resolve } from "node:path";
 
 import { env } from "./env";
@@ -31,7 +31,11 @@ const BIND = process.env.UAI_MCP_GATEWAY_BIND ?? "127.0.0.1";
 /** MCP request bodies are small JSON-RPC frames; cap so audit parsing (and a
  *  hostile container) can't balloon host memory. Responses stream freely. */
 const MAX_BODY_BYTES = 4 * 1024 * 1024;
-const UPSTREAM_TIMEOUT_MS = 120_000;
+/** Bounds the upstream CONNECT (until response headers) only. The response
+ *  BODY must never be time-bounded: MCP streamable-HTTP clients hold SSE
+ *  streams open indefinitely, and an abort mid-pipe once took the whole host
+ *  process down as an unhandled Readable 'error' (2026-07-13). */
+const UPSTREAM_CONNECT_TIMEOUT_MS = 60_000;
 
 export interface TaskMcpConnection {
   id: string;
@@ -181,15 +185,29 @@ async function handle(req: IncomingMessage, res: ServerResponse): Promise<void>
     if (typeof v === "string") headers[name] = v;
   }
 
+  // The controller lives for the whole exchange: the timer only guards the
+  // connect phase (cleared once headers land), and a client hang-up reaps the
+  // upstream so dead streams don't accumulate.
+  const controller = new AbortController();
+  res.on("close", () => controller.abort());
+
   const attempt = async (forceRefresh: boolean): Promise<Response> => {
     const auth = await authHeaderFor(conn, forceRefresh);
     if (auth) headers[auth.name] = auth.value;
-    return fetch(conn.url, {
-      method: req.method,
-      headers,
-      body: body ?? undefined,
-      signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
-    });
+    const connectTimer = setTimeout(
+      () => controller.abort(),
+      UPSTREAM_CONNECT_TIMEOUT_MS,
+    );
+    try {
+      return await fetch(conn.url, {
+        method: req.method,
+        headers,
+        body: body ?? undefined,
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(connectTimer);
+    }
   };
 
   let upstream: Response;
@@ -220,8 +238,17 @@ async function handle(req: IncomingMessage, res: ServerResponse): Promise<void>
   }
   res.writeHead(upstream.status, resHeaders);
   if (upstream.body) {
-    Readable.fromWeb(upstream.body as Parameters<typeof Readable.fromWeb>[0]).pipe(
+    // pipeline (NOT .pipe) so a mid-stream error — client gone, upstream
+    // reset, abort — tears both ends down instead of crashing the process
+    // as an unhandled Readable 'error'.
+    pipeline(
+      Readable.fromWeb(upstream.body as Parameters<typeof Readable.fromWeb>[0]),
       res,
+      (err) => {
+        if (err && err.name !== "AbortError") {
+          audit({ taskId, slug, stream: "ended", error: err.name });
+        }
+      },
     );
   } else {
     res.end();

package/lib/orchestrator.ts

@@ -92,6 +92,10 @@ interface Channel {
   /** Per-agent respawn counter — bounded so a broken agent can't
    *  loop forever rewriting its config. */
   respawns: Map<string, number>;
+  /** When each agent last burned a respawn — a budget older than the
+   *  cooldown resets, so a task self-heals once the underlying failure
+   *  (missing CLI, broken config) clears instead of needing an operator. */
+  respawnLastAt: Map<string, number>;
   /** ADR-049: humans in the chat (from the latest channel spec). */
   humans: ChannelHuman[];
   /** ADR-053: wire the Playwright MCP browser at session start. */
@@ -109,6 +113,8 @@ interface Channel {
 
 /** Hard cap on automatic respawns per agent per channel lifetime. */
 const MAX_RESPAWNS_PER_AGENT = 5;
+/** A burned respawn budget resets after this quiet period (see reconcile). */
+const RESPAWN_COOLDOWN_MS = 10 * 60_000;
 
 /** Substrings in an agent's error output that mean "config was
  *  unlinked between runs" — repair-and-respawn covers the common
@@ -240,6 +246,7 @@ class Orchestrator {
       openTurns: new Set(),
       interrupted: new Set(),
       respawns: new Map(),
+      respawnLastAt: new Map(),
       humans: spec.humans ?? [],
       browserTesting: spec.browserTesting === true,
       mcpConnections: spec.mcpConnections ?? [],
@@ -273,7 +280,14 @@ class Orchestrator {
         (ok) => {
           if (!ok) channel.sessionsReady = null;
         },
-        () => {
+        (err: unknown) => {
+          // A start failure retries on the next ensure — but it must be
+          // VISIBLE: an unlogged throw here once looped silently every ~2s
+          // while a task sat dead with no sessions and no trace.
+          console.warn(
+            `[orchestrator] ${channel.taskId}: session start failed: ` +
+              `${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
+          );
           channel.sessionsReady = null;
         },
       );
@@ -306,14 +320,23 @@ class Orchestrator {
 
   /** Spawn sessions for roster agents added after the initial start. */
   private async reconcileSessions(channel: Channel): Promise<void> {
-    const missing = channel.roster.filter(
-      (agent) =>
-        !channel.sessions.has(agent.id) &&
-        !channel.spawning.has(agent.id) &&
-        // Crash-loop budget: an agent whose session keeps dying stops being
-        // respawned after MAX_RESPAWNS_PER_AGENT (the exit paths increment).
-        (channel.respawns.get(agent.id) ?? 0) <= MAX_RESPAWNS_PER_AGENT,
-    );
+    const missing = channel.roster.filter((agent) => {
+      if (channel.sessions.has(agent.id) || channel.spawning.has(agent.id)) {
+        return false;
+      }
+      // Crash-loop budget: an agent whose session keeps dying stops being
+      // respawned after MAX_RESPAWNS_PER_AGENT (the exit paths increment) —
+      // but a budget that has been cold for RESPAWN_COOLDOWN_MS resets, so
+      // the task heals itself once the cause (a missing CLI on the shared
+      // volume, a broken config) is fixed, instead of staying dead until a
+      // host restart.
+      if ((channel.respawns.get(agent.id) ?? 0) > MAX_RESPAWNS_PER_AGENT) {
+        const lastAt = channel.respawnLastAt.get(agent.id) ?? 0;
+        if (Date.now() - lastAt < RESPAWN_COOLDOWN_MS) return false;
+        channel.respawns.set(agent.id, 0);
+      }
+      return true;
+    });
     if (missing.length === 0) return;
 
     const task = getHostTask(channel.taskId);
@@ -613,6 +636,7 @@ class Orchestrator {
         // after a double SIGKILL). Bounded by the respawn budget, checked in
         // reconcileSessions.
         channel.respawns.set(agentId, (channel.respawns.get(agentId) ?? 0) + 1);
+        channel.respawnLastAt.set(agentId, Date.now());
         channel.sessions.delete(agentId);
         break;
       }
@@ -635,6 +659,7 @@ class Orchestrator {
         // Same zombie hazard as the error path — a session whose process
         // ended (even cleanly) can never carry another turn.
         channel.respawns.set(agentId, (channel.respawns.get(agentId) ?? 0) + 1);
+        channel.respawnLastAt.set(agentId, Date.now());
         channel.sessions.delete(agentId);
         break;
     }
@@ -653,6 +678,7 @@ class Orchestrator {
   ): Promise<void> {
     const tries = (channel.respawns.get(agentId) ?? 0) + 1;
     channel.respawns.set(agentId, tries);
+    channel.respawnLastAt.set(agentId, Date.now());
 
     if (tries > MAX_RESPAWNS_PER_AGENT) {
       this.emitHost({

package/lib/standard-image.ts

@@ -238,6 +238,12 @@ async function upgradeVolumeAgentClis(): Promise<void> {
   const upgrade = await run("docker", [
     "run",
     "--rm",
+    // The container NAME is the mutex: overlapping boots (or a crash-looping
+    // service) must never race two npm installs on the shared volume — that
+    // once left it with no `claude` at all (2026-07-13). Docker rejects the
+    // duplicate name; we treat that as "already upgrading, skip".
+    "--name",
+    "uai-cli-upgrade",
     "-u",
     "root",
     "-w",
@@ -250,6 +256,10 @@ async function upgradeVolumeAgentClis(): Promise<void> {
     `npm install -g ${pkgs} >/dev/null 2>&1 || { rm -rf ${scopeDirs}; npm install -g ${pkgs} >/dev/null 2>&1; } && asdf reshim nodejs >/dev/null 2>&1; ` +
       bins.map((b) => `printf '%s ' "$(${b} --version 2>/dev/null | head -1)"`).join("; "),
   ]);
+  if (upgrade.code !== 0 && /already in use/i.test(upgrade.stderr)) {
+    console.log("[host-agent] agent CLI upgrade already running — skipped");
+    return;
+  }
   if (upgrade.code === 0) {
     console.log(
       `[host-agent] agent CLIs current on ${ASDF_DATA_VOLUME}: ${upgrade.stdout.trim()}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",
@@ -40,6 +40,7 @@
     "db",
     "scripts/agent",
     "scripts/install",
+    "runner",
     "images/standard",
     "ui",
     "README.md",

package/runner/runner.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * uai session runner (ADR-061) — runs INSIDE the task container and owns an
+ * agent CLI process, so the CLI's lifetime is decoupled from the host
+ * process. The host talks to it only through files on the task-workspace
+ * bind mount (no sockets/FIFOs — they don't cross the macOS↔VM boundary):
+ *
+ *   <sessionDir>/inbox.jsonl   host appends; runner tails → CLI stdin
+ *   <sessionDir>/outbox.jsonl  CLI stdout lines verbatim + __uai meta lines
+ *   <sessionDir>/heartbeat     rewritten every HEARTBEAT_MS (host checks mtime)
+ *   <sessionDir>/runner.json   pid, protocol, argv, startedAt
+ *
+ * Meta lines are `{"__uai":"spawn"|"exit", ...}`; the host filters them out
+ * before handing lines to the protocol adapters. Control lines the host
+ * appends to the inbox use the same shape (`{"__uai":"stop"}`); everything
+ * else in the inbox goes to the CLI's stdin untouched.
+ *
+ * Plain Node ≥18, dependency-free, ESM. Testable outside docker: point it
+ * at a tmp dir and any line-oriented fake CLI.
+ *
+ * Usage: node runner.mjs <sessionDir> -- <command> [args...]
+ */
+
+import { spawn } from "node:child_process";
+import { appendFileSync, mkdirSync, openSync, readSync, fstatSync, closeSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import process from "node:process";
+
+const PROTOCOL = 1;
+const POLL_MS = 50;
+const HEARTBEAT_MS = 5_000;
+const STDERR_CAP = 8 * 1024;
+const STOP_GRACE_MS = 5_000;
+
+// ---- argv ------------------------------------------------------------------
+
+const sep = process.argv.indexOf("--");
+const sessionDir = process.argv[2];
+if (!sessionDir || sep < 0 || sep + 1 >= process.argv.length) {
+  process.stderr.write("usage: runner.mjs <sessionDir> -- <command> [args...]\n");
+  process.exit(2);
+}
+const command = process.argv[sep + 1];
+const args = process.argv.slice(sep + 2);
+
+mkdirSync(sessionDir, { recursive: true });
+const inboxPath = join(sessionDir, "inbox.jsonl");
+const outboxPath = join(sessionDir, "outbox.jsonl");
+const heartbeatPath = join(sessionDir, "heartbeat");
+const runnerJsonPath = join(sessionDir, "runner.json");
+
+// Single append point — appendFileSync with O_APPEND keeps lines atomic for
+// the sizes we write; the runner is the outbox's only writer.
+function outbox(line) {
+  appendFileSync(outboxPath, line.endsWith("\n") ? line : `${line}\n`);
+}
+function meta(kind, extra = {}) {
+  outbox(JSON.stringify({ __uai: kind, ts: Date.now(), ...extra }));
+}
+
+// ---- the CLI ---------------------------------------------------------------
+
+// The runner is launched through the container's asdf `node` shim, which
+// exports its resolved version (ASDF_NODEJS_VERSION et al.) into our env.
+// Passing that through would pin the CLI's own asdf shim to the WORKSPACE's
+// node version — "No claude executable found for nodejs X" when the agent
+// CLIs are installed under a different one. Strip ASDF_* so the CLI shim
+// resolves exactly as a direct `docker exec <cli>` would.
+const cliEnv = { ...process.env };
+for (const key of Object.keys(cliEnv)) {
+  if (key.startsWith("ASDF_")) delete cliEnv[key];
+}
+
+const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"], env: cliEnv });
+
+writeFileSync(
+  runnerJsonPath,
+  JSON.stringify({
+    protocol: PROTOCOL,
+    runnerPid: process.pid,
+    cliPid: child.pid ?? null,
+    command,
+    args,
+    startedAt: Date.now(),
+  }),
+);
+meta("spawn", { protocol: PROTOCOL, runnerPid: process.pid, cliPid: child.pid ?? null });
+
+let stderrTail = "";
+child.stderr?.setEncoding("utf8");
+child.stderr?.on("data", (chunk) => {
+  stderrTail = (stderrTail + chunk).slice(-STDERR_CAP);
+});
+
+// CLI stdout → outbox, complete lines only (partial line buffered).
+let stdoutBuf = "";
+child.stdout?.setEncoding("utf8");
+child.stdout?.on("data", (chunk) => {
+  stdoutBuf += chunk;
+  for (;;) {
+    const nl = stdoutBuf.indexOf("\n");
+    if (nl < 0) break;
+    const line = stdoutBuf.slice(0, nl);
+    stdoutBuf = stdoutBuf.slice(nl + 1);
+    if (line.trim().length > 0) outbox(line);
+  }
+});
+
+let exiting = false;
+child.on("exit", (code, signal) => {
+  if (exiting) return;
+  exiting = true;
+  if (stdoutBuf.trim().length > 0) outbox(stdoutBuf); // flush the partial tail
+  meta("exit", { code, signal: signal ?? null, stderrTail });
+  process.exit(0);
+});
+child.on("error", (err) => {
+  if (exiting) return;
+  exiting = true;
+  meta("exit", { code: null, signal: null, stderrTail: String(err?.message ?? err) });
+  process.exit(0);
+});
+
+// ---- inbox tail → CLI stdin --------------------------------------------------
+
+let inboxOffset = 0; // fresh session dir per spawn — always start at 0
+let inboxBuf = "";
+
+function stopCli() {
+  if (exiting) return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    /* already gone */
+  }
+  setTimeout(() => {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      /* already gone */
+    }
+  }, STOP_GRACE_MS).unref();
+}
+
+function handleInboxLine(line) {
+  if (line.trim().length === 0) return;
+  if (line.startsWith('{"__uai"')) {
+    try {
+      const ctl = JSON.parse(line);
+      if (ctl.__uai === "stop") stopCli();
+    } catch {
+      /* malformed control — ignore */
+    }
+    return;
+  }
+  try {
+    child.stdin?.write(`${line}\n`);
+  } catch {
+    /* EPIPE after CLI death — the exit meta already tells the host */
+  }
+}
+
+function pollInbox() {
+  let fd;
+  try {
+    fd = openSync(inboxPath, "r");
+  } catch {
+    return; // inbox not created yet
+  }
+  try {
+    const size = fstatSync(fd).size;
+    if (size > inboxOffset) {
+      const len = size - inboxOffset;
+      const buf = Buffer.alloc(len);
+      const read = readSync(fd, buf, 0, len, inboxOffset);
+      inboxOffset += read;
+      inboxBuf += buf.toString("utf8", 0, read);
+      for (;;) {
+        const nl = inboxBuf.indexOf("\n");
+        if (nl < 0) break;
+        const line = inboxBuf.slice(0, nl);
+        inboxBuf = inboxBuf.slice(nl + 1);
+        handleInboxLine(line);
+      }
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+setInterval(pollInbox, POLL_MS);
+
+// ---- heartbeat ---------------------------------------------------------------
+
+function beat() {
+  try {
+    writeFileSync(heartbeatPath, `${process.pid} ${Date.now()}\n`);
+  } catch {
+    /* disk hiccup — next beat retries */
+  }
+}
+beat();
+setInterval(beat, HEARTBEAT_MS);
+
+// The runner dies only with its CLI (or on stop/SIGTERM) — never because a
+// host-side consumer went away. That is the entire point (ADR-061).
+process.on("SIGTERM", stopCli);
+process.on("SIGINT", stopCli);