@runuai/host 0.4.3 → 0.6.0

package/lib/orchestrator.ts

@@ -92,10 +92,16 @@ 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. */
   browserTesting: boolean;
+  /** ADR-062: shared-files mount mode ("off" | "ro" | "rw") for the preamble. */
+  sharedFiles: string;
   /** ADR-057: the owner's MCP connections exposed through the host gateway. */
   mcpConnections: Array<{ id: string; slug: string }>;
   /** Last connection set written into the container (skip repeat execs —
@@ -109,6 +115,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
@@ -174,6 +182,7 @@ class Orchestrator {
     }
     channel.humans = spec.humans ?? [];
     channel.browserTesting = spec.browserTesting === true;
+    channel.sharedFiles = spec.sharedFiles ?? "ro";
     channel.mcpConnections = spec.mcpConnections ?? [];
     for (const agent of channel.roster) {
       channel.preambles.set(
@@ -187,6 +196,7 @@ class Orchestrator {
           spec.branch,
           channel.humans,
           channel.browserTesting,
+          channel.sharedFiles,
         ),
       );
     }
@@ -214,6 +224,7 @@ class Orchestrator {
           spec.branch,
           spec.humans,
           spec.browserTesting,
+          spec.sharedFiles ?? "ro",
         ),
       );
       // ADR-046: materialise this agent's skills to its per-agent SKILL.md in
@@ -240,8 +251,10 @@ class Orchestrator {
       openTurns: new Set(),
       interrupted: new Set(),
       respawns: new Map(),
+      respawnLastAt: new Map(),
       humans: spec.humans ?? [],
       browserTesting: spec.browserTesting === true,
+      sharedFiles: spec.sharedFiles ?? "ro",
       mcpConnections: spec.mcpConnections ?? [],
       spawning: new Set(),
     };
@@ -273,7 +286,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;
         },
       );
@@ -295,6 +315,7 @@ class Orchestrator {
   private async ensureMcpConfig(channel: Channel): Promise<void> {
     const fingerprint = JSON.stringify(channel.mcpConnections.map((c) => c.id));
     if (channel.mcpConfigFingerprint === fingerprint) return;
+    const hadPrevious = channel.mcpConfigFingerprint !== undefined;
     channel.mcpConfigFingerprint = fingerprint;
     await setupMcpTaskConfig(
       channel.taskId,
@@ -302,18 +323,62 @@ class Orchestrator {
       channel.mcpConnections,
       channel.roster.some((a) => a.kind === "codex"),
     );
+    // Agent CLIs read MCP servers once, at process start — and durable
+    // sessions (ADR-061) make processes long-lived, so without this a
+    // connection added mid-task stays invisible indefinitely. Recycle IDLE
+    // sessions so the change actually reaches the agents; busy agents keep
+    // their turn (and in-memory context) and pick it up on a later change or
+    // natural respawn. Trade-off: a recycled agent loses its in-memory
+    // context and is re-briefed from chat — same as any respawn, and better
+    // than never seeing the connection the user just added. Skipped on the
+    // channel's first fingerprint (sessions just spawned with this config).
+    if (hadPrevious) await this.recycleIdleSessions(channel);
+  }
+
+  /** Close + respawn every session with no open turn (MCP set changed). */
+  private async recycleIdleSessions(channel: Channel): Promise<void> {
+    let recycled = 0;
+    for (const [agentId, session] of [...channel.sessions]) {
+      if (channel.openTurns.has(agentId)) continue; // never mid-turn
+      if (channel.spawning.has(agentId)) continue;
+      channel.sessions.delete(agentId);
+      try {
+        // close() flips the adapter's `closed` flag first, so the session's
+        // exit is suppressed — no budget increment, no agent.exit noise, no
+        // race with the respawn below (recoverClaudeAgent's pattern).
+        await session.close();
+      } catch {
+        // Already dead — close is idempotent for our adapters.
+      }
+      recycled += 1;
+    }
+    if (recycled > 0) {
+      console.log(
+        `[orchestrator] ${channel.taskId}: recycled ${recycled} idle session(s) for MCP config change`,
+      );
+      await this.reconcileSessions(channel);
+    }
   }
 
   /** 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 +678,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 +701,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 +720,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({
@@ -925,6 +993,7 @@ export function buildSystemPreamble(
   taskBranch: string,
   humans?: ChannelHuman[],
   browserTesting?: boolean,
+  sharedFiles?: string,
 ): string {
   const channelList = roster
     .map((a) =>
@@ -1065,6 +1134,31 @@ export function buildSystemPreamble(
     "part of the project. Never review, edit, stage, commit, or flag it;",
     "treat it as ignored, even though git may show it as untracked.",
     "",
+    // ADR-062: shared files — only when this container actually carries the
+    // mounts (task-up drops a marker; pre-feature containers have none).
+    ...(sharedFiles &&
+    sharedFiles !== "off" &&
+    existsSync(join(workspacePath, ".uai", "files-mounted"))
+      ? [
+          "## Shared files",
+          "",
+          `Non-code files (${sharedFiles === "rw" ? "read-write" : "READ-ONLY"} for this task):`,
+          "- `/workspace/files/org` — the org's shared files (logos, specs,",
+          "  datasets), visible to every task in the org on this host.",
+          "- `/workspace/files/me` — the task owner's personal files, shared",
+          "  across their tasks on this host.",
+          ...(sharedFiles === "rw"
+            ? [
+                "When producing artifacts for humans, write them here (use a",
+                "subdirectory named after the task to avoid collisions).",
+              ]
+            : [
+                "Read-only here: to hand a file back, use the chat attachment",
+                "flow instead.",
+              ]),
+          "",
+        ]
+      : []),
     // ADR-046: link/document skills are materialised to a per-agent SKILL.md.
     // Point the agent at its own file (package skills are handled below).
     ...((agent.skills ?? []).some((s) => s.type !== "package")

package/lib/shared-files.ts

@@ -0,0 +1,156 @@
+/**
+ * ADR-062 shared files — host-side handler for the `filesOp` bridge command.
+ * Two roots per host: org files (per host+org) and personal files (per
+ * host+user), both under <workspaceRoot>/shared/. The cloud is a window
+ * only; this module is the sole writer host-side.
+ *
+ * SECURITY: the cloud relays paths from browsers, and containers mount these
+ * same dirs — every path is treated as hostile. Two gates on every op:
+ * `resolveInsideRoot` (relative-only, ".."-free, resolved-prefix check) and
+ * `assertRealInsideRoot` (realpath containment, so a symlink the container
+ * planted inside a rw mount cannot point ops outside the root).
+ */
+
+import { promises as fsp } from "node:fs";
+import { dirname, join, normalize, resolve, sep } from "node:path";
+
+import type { FilesEntry, FilesOpInput, FilesOpValue } from "../src/protocol";
+import { env } from "./env";
+
+/** Max bytes returned per read chunk (base64 expands ~4/3; WS cap is 16MB). */
+const MAX_READ_CHUNK = 4 * 1024 * 1024;
+/** Max bytes accepted per write chunk. */
+const MAX_WRITE_CHUNK = 8 * 1024 * 1024;
+/** Max entries returned by a single list. */
+const MAX_LIST_ENTRIES = 2_000;
+
+/**
+ * Filesystem-safe directory name for an org/user id. Personal org ids are
+ * `personal:<userId>` — the colon breaks docker's short-syntax bind spec
+ * (src:dst:mode), so it is mapped to "_". MUST stay in lockstep with the
+ * identical mapping in scripts/agent/task-up.sh (shared_fs_name).
+ */
+export function sharedDirName(id: string): string {
+  return id.replace(/:/g, "_");
+}
+
+export function sharedRoot(scope: "org" | "me", orgId: string, userId: string): string {
+  return scope === "org"
+    ? resolve(env.workspaceRoot, "shared", "orgs", sharedDirName(orgId))
+    : resolve(env.workspaceRoot, "shared", "users", sharedDirName(userId));
+}
+
+function resolveInsideRoot(root: string, relPath: string): string {
+  // Relative paths only — an absolute path is rejected, never reinterpreted.
+  if (/^[/\\]/.test(relPath) || /^[A-Za-z]:/.test(relPath)) {
+    throw new Error("invalid path");
+  }
+  const cleaned = normalize(relPath);
+  if (
+    cleaned.split(/[/\\]/).some((seg) => seg === "..") ||
+    cleaned.includes("\0")
+  ) {
+    throw new Error("invalid path");
+  }
+  const target = resolve(root, cleaned);
+  if (target !== root && !target.startsWith(root + sep)) {
+    throw new Error("invalid path");
+  }
+  return target;
+}
+
+/**
+ * String containment (resolveInsideRoot) can't see symlinks the container
+ * planted inside a rw mount — `root/evil → /` would pass it. Walk up from
+ * the target to its deepest EXISTING ancestor, realpath it, and require the
+ * REAL location to stay inside the real root (ADR-062 "no symlink escapes").
+ */
+async function assertRealInsideRoot(root: string, target: string): Promise<void> {
+  const realRoot = await fsp.realpath(root);
+  let probe = target;
+  for (;;) {
+    try {
+      const real = await fsp.realpath(probe);
+      if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+        throw new Error("invalid path");
+      }
+      return;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      const parent = dirname(probe);
+      if (parent === probe) throw new Error("invalid path");
+      probe = parent;
+    }
+  }
+}
+
+export async function handleFilesOp(input: FilesOpInput): Promise<FilesOpValue> {
+  if (!input.orgId && input.scope === "org") throw new Error("missing orgId");
+  if (!input.userId && input.scope === "me") throw new Error("missing userId");
+  const root = sharedRoot(input.scope, input.orgId, input.userId);
+  await fsp.mkdir(root, { recursive: true });
+  const target = resolveInsideRoot(root, input.path ?? "");
+  await assertRealInsideRoot(root, target);
+
+  switch (input.op) {
+    case "list": {
+      const names = await fsp.readdir(target);
+      const entries: FilesEntry[] = [];
+      for (const name of names.slice(0, MAX_LIST_ENTRIES)) {
+        try {
+          const st = await fsp.lstat(join(target, name));
+          entries.push({
+            name,
+            dir: st.isDirectory(),
+            size: st.isDirectory() ? 0 : st.size,
+            mtimeMs: st.mtimeMs,
+          });
+        } catch {
+          // Raced deletion — skip.
+        }
+      }
+      entries.sort((a, b) =>
+        a.dir === b.dir ? a.name.localeCompare(b.name) : a.dir ? -1 : 1,
+      );
+      return { entries };
+    }
+    case "read": {
+      const st = await fsp.stat(target);
+      if (st.isDirectory()) throw new Error("is a directory");
+      const offset = Math.max(0, input.offset ?? 0);
+      const length = Math.min(input.length ?? MAX_READ_CHUNK, MAX_READ_CHUNK);
+      const fh = await fsp.open(target, "r");
+      try {
+        const buf = Buffer.alloc(Math.min(length, Math.max(0, st.size - offset)));
+        const { bytesRead } = await fh.read(buf, 0, buf.length, offset);
+        return {
+          dataBase64: buf.subarray(0, bytesRead).toString("base64"),
+          size: st.size,
+          eof: offset + bytesRead >= st.size,
+        };
+      } finally {
+        await fh.close();
+      }
+    }
+    case "write": {
+      if (target === root) throw new Error("invalid path");
+      const data = Buffer.from(input.dataBase64 ?? "", "base64");
+      if (data.length > MAX_WRITE_CHUNK) throw new Error("chunk too large");
+      await fsp.mkdir(resolve(target, ".."), { recursive: true });
+      await fsp.writeFile(target, data, { flag: input.append ? "a" : "w" });
+      return {};
+    }
+    case "mkdir": {
+      if (target === root) throw new Error("invalid path");
+      await fsp.mkdir(target, { recursive: true });
+      return {};
+    }
+    case "delete": {
+      if (target === root) throw new Error("invalid path");
+      await fsp.rm(target, { recursive: true, force: true });
+      return {};
+    }
+    default:
+      throw new Error(`unknown op: ${String(input.op)}`);
+  }
+}

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.6.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);

package/scripts/agent/task-up.sh

@@ -121,6 +121,28 @@ fi
 
 mkdir -p "$task_workspace"
 
+# ADR-062 shared files: two host-resident roots mounted into the container
+# when the task's mode isn't "off". Created here so Docker doesn't create
+# them root-owned at mount time. Mode defaults to ro; org mount only when
+# the cloud sent an org id (older clouds won't).
+shared_files_mode=$(jq -r '.[0].shared_files // "ro"' <<<"$task_json")
+shared_owner_org=$(jq -r '.[0].owner_org_id // ""' <<<"$task_json")
+shared_owner_user=$(jq -r '.[0].owner_user_id // ""' <<<"$task_json")
+# Colons break docker's src:dst:mode bind syntax, and personal org ids are
+# "personal:<userId>" — map ":" to "_". MUST match sharedDirName() in
+# host-agent/lib/shared-files.ts.
+shared_owner_org=$(printf '%s' "$shared_owner_org" | tr ':' '_')
+shared_owner_user=$(printf '%s' "$shared_owner_user" | tr ':' '_')
+shared_root="$UAI_WORKSPACE_ROOT/shared"
+if [ "$shared_files_mode" != "off" ]; then
+  [ -n "$shared_owner_org" ] && mkdir -p "$shared_root/orgs/$shared_owner_org"
+  [ -n "$shared_owner_user" ] && mkdir -p "$shared_root/users/$shared_owner_user"
+  # Marker for the preamble: only containers that actually carry the mounts
+  # get the "## Shared files" briefing (pre-feature containers don't).
+  mkdir -p "$task_workspace/.uai"
+  : > "$task_workspace/.uai/files-mounted"
+fi
+
 # Iterate using jq -c so each project is a single JSON object per line.
 # Bash 3.2 friendly: a while-read loop rather than mapfile/readarray.
 while IFS= read -r project_obj; do
@@ -313,6 +335,20 @@ fi
   # ADR-053: host-wide Playwright browser cache. Always mounted (harmless
   # when browser testing is off); Chromium downloads once per HOST.
   printf '      - "%s:/opt/pw-browsers"\n' "$PW_VOLUME"
+  # ADR-062 shared files (org + personal) at /workspace/files/{org,me};
+  # ro/rw fixed here for the container's lifetime.
+  if [ "$shared_files_mode" != "off" ]; then
+    shared_suffix=""
+    [ "$shared_files_mode" = "ro" ] && shared_suffix=":ro"
+    if [ -n "$shared_owner_org" ]; then
+      printf '      - "%s/orgs/%s:/workspace/files/org%s"\n' \
+        "$shared_root" "$shared_owner_org" "$shared_suffix"
+    fi
+    if [ -n "$shared_owner_user" ]; then
+      printf '      - "%s/users/%s:/workspace/files/me%s"\n' \
+        "$shared_root" "$shared_owner_user" "$shared_suffix"
+    fi
+  fi
   printf '    ports:\n'
   # code-server (the Editor tunnel) is the only auto-published port. Preview
   # ports are NOT published at task-up (ADR-043 Stage 2: opt-in previews) —