@runuai/host 0.4.2 → 0.5.0

package/db/migrations/0008_host_mcp_connections.sql

@@ -0,0 +1,18 @@
+-- ADR-057: user-authed MCP connections. Secrets sealed with the host master
+-- key (ct.nonce base64, like host_project_env.value_enc); the cloud holds only
+-- non-secret metadata.
+CREATE TABLE `host_mcp_connections` (
+	`id` text PRIMARY KEY NOT NULL,
+	`user_id` text NOT NULL,
+	`url` text NOT NULL,
+	`auth_kind` text NOT NULL,
+	`token_endpoint` text,
+	`redirect_uri` text,
+	`client_id` text,
+	`client_secret_enc` text,
+	`pkce_verifier_enc` text,
+	`secret_enc` text,
+	`status` text DEFAULT 'pending' NOT NULL,
+	`scopes` text,
+	`updated_at` integer NOT NULL
+);

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

@@ -57,6 +57,20 @@
       "when": 1779900008000,
       "tag": "0007_host_github_token_kind",
       "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "6",
+      "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

@@ -115,3 +115,64 @@ export const hostProjectEnv = sqliteTable(
 
 export type HostProjectEnv = typeof hostProjectEnv.$inferSelect;
 export type NewHostProjectEnv = typeof hostProjectEnv.$inferInsert;
+
+// User-authed MCP connections (ADR-057). One row per cloud connection id; all
+// secret material (static header, OAuth client secret, PKCE verifier, tokens)
+// 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(),
+  url: text("url").notNull(),
+  // "oauth" | "token" | "none"
+  authKind: text("auth_kind").notNull(),
+  // OAuth machinery discovered at probe time.
+  tokenEndpoint: text("token_endpoint"),
+  redirectUri: text("redirect_uri"),
+  clientId: text("client_id"),
+  clientSecretEnc: text("client_secret_enc"),
+  // PKCE verifier held between probe and oauth.complete.
+  pkceVerifierEnc: text("pkce_verifier_enc"),
+  // Sealed JSON: {"headerName","headerValue"} (token kind) or
+  // {"accessToken","refreshToken","expiresAt"} (oauth kind). Null for "none".
+  secretEnc: text("secret_enc"),
+  status: text("status").notNull().default("pending"), // pending|connected
+  scopes: text("scopes"),
+  updatedAt: integer("updated_at", { mode: "number" }).notNull(),
+});
+
+export type McpConnection = typeof mcpConnections.$inferSelect;

package/images/standard/Dockerfile

@@ -70,6 +70,21 @@ RUN apt-get update \
       zsh \
  && rm -rf /var/lib/apt/lists/*
 
+# ADR-053: agent browser (Playwright/Chromium) runtime libs + the watchable
+# display stack (Xvfb → x11vnc → noVNC). Baked here because the
+# per-container background apt raced session start (headless-stuck MCP
+# server, viewer lagging the preview by minutes — Debian's novnc drags a
+# large Python tree). The Chromium BINARY still comes from the shared
+# uai-playwright volume (downloaded once per host); these are its deps.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
+      libxkbcommon0 libatspi2.0-0 libxcomposite1 libxdamage1 libxfixes3 \
+      libxrandr2 libgbm1 libasound2 libpango-1.0-0 libcairo2 \
+      fonts-liberation fonts-unifont \
+      xvfb x11vnc novnc websockify \
+ && rm -rf /var/lib/apt/lists/*
+
 # GitHub CLI (`gh`) — used by the ship/PR flow inside the container.
 RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
       | tee /usr/share/keyrings/githubcli-archive-keyring.gpg >/dev/null \

package/lib/agent-cli.ts

@@ -212,6 +212,11 @@ async function main() {
       break;
     }
     case "whoami ": case "whoami undefined": out({ apiUrl: API_URL }); break;
+    case "react heart": case "react check": case "react x": {
+      const r = await api("POST", "/api/agent/react", { emoji: action, msg: flags.msg || undefined });
+      out((r.reacted ? "reacted to " : "un-reacted from ") + r.messageId);
+      break;
+    }
     default:
       console.error([
         "uai — agent CLI. Commands:",
@@ -222,6 +227,7 @@ async function main() {
         "  uai memory search <query>",
         "  uai memory save <text> [--project id] [--tags a,b]",
         "  uai memory delete <id>",
+        "  uai react <heart|check|x> [--msg #id]   (no --msg = the message you were last handed)",
         "  uai whoami",
       ].join("\\n"));
       process.exit(argv.length ? 1 : 0);

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,
@@ -35,10 +35,11 @@ import type {
 // resolves these aliases to the current dated snapshots, so this list is
 // stable across point releases. UPDATE WHEN MODELS CHANGE (new family or a
 // retired alias). Order is display order in the cloud picker.
-const CLAUDE_MODELS = ["opus", "sonnet", "haiku"];
+const CLAUDE_MODELS = ["fable", "opus", "sonnet", "haiku"];
 
-// Opus ("opus" alias = Opus 4.8) is the default: the strongest coding model
-// for the interactive loop. Update alongside CLAUDE_MODELS.
+// Opus ("opus" alias = Opus 4.8) stays the default; "fable" (Claude
+// Fable 5, the Mythos-class flagship) is opt-in per agent. Update
+// alongside CLAUDE_MODELS.
 const CLAUDE_DEFAULT_MODEL = "opus";
 
 // Reasoning levels passed through via `claude --effort <level>`. Taken from
@@ -192,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;
@@ -230,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) => {
@@ -348,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,
@@ -49,6 +49,9 @@ import type {
 // Sourced from that picker; UPDATE WHEN MODELS CHANGE. Order = display order
 // in the cloud picker. Legacy models remain reachable via config.toml.
 const CODEX_MODELS = [
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "gpt-5.6-luna",
   "gpt-5.5",
   "gpt-5.4",
   "gpt-5.4-mini",
@@ -57,16 +60,20 @@ const CODEX_MODELS = [
   "gpt-5.2",
 ];
 
-// gpt-5.5 is Codex's current frontier coding model. Update alongside
-// CODEX_MODELS. When an agent's model is null the adapter omits the override
-// entirely and Codex uses the user's own configured default.
-const CODEX_DEFAULT_MODEL = "gpt-5.5";
+// gpt-5.6-sol is Codex's current frontier coding model (the CLI default).
+// Update alongside CODEX_MODELS. When an agent's model is null the adapter
+// omits the override entirely and Codex uses the user's own configured
+// default.
+const CODEX_DEFAULT_MODEL = "gpt-5.6-sol";
 
-// Reasoning levels set via `-c model_reasoning_effort=<level>`. "xhigh" is the
-// picker's "Extra high". UPDATE WHEN CODEX CHANGES its reasoning levels.
-const CODEX_EFFORTS = ["low", "medium", "high", "xhigh"];
+// Reasoning levels set via `-c model_reasoning_effort=<level>`. "xhigh" is
+// the picker's "Extra high"; gpt-5.6 added "max" and "ultra" (ultra =
+// maximum reasoning with automatic task delegation). UPDATE WHEN CODEX
+// CHANGES its reasoning levels.
+const CODEX_EFFORTS = ["low", "medium", "high", "xhigh", "max", "ultra"];
 
-// medium is Codex's default reasoning level. Update alongside CODEX_EFFORTS.
+// medium stays OUR default (the 5.6 CLI defaults to low — too light for
+// agentic task work). Update alongside CODEX_EFFORTS.
 const CODEX_DEFAULT_EFFORT = "medium";
 
 // ---------------------------------------------------------------------------
@@ -206,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;
@@ -224,6 +231,7 @@ export class CodexSession implements AgentSession {
   private readonly ready: Promise<void>;
 
   constructor(args: {
+    taskId: string;
     agent: RosterAgent;
     containerName: string;
     systemPreamble: string;
@@ -244,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));
@@ -531,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);
+  }
+}