@runuai/host 0.4.2 → 0.5.0

package/lib/orchestrator.ts

@@ -50,8 +50,14 @@ import {
   loadTaskCliSecret,
   writeAgentCli,
 } from "./agent-cli";
+import { setupBrowserTesting } from "./browser-testing";
+import { setupMcpTaskConfig } from "./mcp-gateway";
 import { env } from "./env";
-import type { ChannelEnsureInput, HostEvent } from "../src/protocol";
+import type {
+  ChannelEnsureInput,
+  ChannelHuman,
+  HostEvent,
+} from "../src/protocol";
 
 export type HostEventSubscriber = (event: HostEvent) => void;
 
@@ -86,10 +92,29 @@ 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-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 —
+   *  ensure runs on every message). Live sessions read MCP config at spawn,
+   *  so a mid-task write takes effect on the next (re)spawn. */
+  mcpConfigFingerprint?: string;
+  /** Agents with a reconcile-spawn in flight (ADR-049 mid-task adds) — guards
+   *  against a concurrent ensure double-spawning the same new agent. */
+  spawning: Set<string>;
 }
 
 /** 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
@@ -133,6 +158,44 @@ class Orchestrator {
 
   registerChannelSpec(spec: ChannelEnsureInput): void {
     this.channelSpecs.set(spec.taskId, spec);
+    // ADR-049: the cloud re-sends the spec on every message AND right after a
+    // mid-task roster/participant change. If the channel is already live,
+    // fold the fresh spec in: append new roster agents (their sessions spawn
+    // in the reconcile pass of ensureSessions) and rebuild every preamble so
+    // a later respawn briefs agents with the CURRENT roster + humans.
+    const channel = this.channels.get(spec.taskId);
+    if (channel) this.refreshChannel(channel, spec);
+  }
+
+  /** Fold a fresh channel spec into a live channel (ADR-049). */
+  private refreshChannel(channel: Channel, spec: ChannelEnsureInput): void {
+    const known = new Set(channel.roster.map((a) => a.id));
+    for (const agent of spec.agents) {
+      if (!known.has(agent.id)) {
+        channel.roster.push(agent);
+        // Per-agent link/document skills, like getOrCreateChannel does at
+        // channel birth. Best-effort.
+        writeAgentSkills(channel.taskId, agent);
+      }
+    }
+    channel.humans = spec.humans ?? [];
+    channel.browserTesting = spec.browserTesting === true;
+    channel.mcpConnections = spec.mcpConnections ?? [];
+    for (const agent of channel.roster) {
+      channel.preambles.set(
+        agent.id,
+        buildSystemPreamble(
+          channel.roster,
+          agent,
+          spec.projects,
+          spec.globalContext,
+          spec.workspacePath,
+          spec.branch,
+          channel.humans,
+          channel.browserTesting,
+        ),
+      );
+    }
   }
 
   private async getOrCreateChannel(taskId: string): Promise<Channel | null> {
@@ -155,6 +218,8 @@ class Orchestrator {
           spec.globalContext,
           spec.workspacePath,
           spec.branch,
+          spec.humans,
+          spec.browserTesting,
         ),
       );
       // ADR-046: materialise this agent's skills to its per-agent SKILL.md in
@@ -181,6 +246,11 @@ class Orchestrator {
       openTurns: new Set(),
       interrupted: new Set(),
       respawns: new Map(),
+      respawnLastAt: new Map(),
+      humans: spec.humans ?? [],
+      browserTesting: spec.browserTesting === true,
+      mcpConnections: spec.mcpConnections ?? [],
+      spawning: new Set(),
     };
     this.channels.set(taskId, channel);
     return channel;
@@ -197,7 +267,7 @@ class Orchestrator {
    *
    * Returns whether sessions are ready.
    */
-  private ensureSessions(channel: Channel): Promise<boolean> {
+  private async ensureSessions(channel: Channel): Promise<boolean> {
     // Memoized: every caller awaits the SAME in-flight start, so a concurrent
     // deliver() can't observe "ready" while the sessions map is still empty
     // (startSessions awaits docker work before populating it — the old boolean
@@ -210,12 +280,107 @@ 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;
         },
       );
     }
-    return channel.sessionsReady;
+    const ready = await channel.sessionsReady;
+    // ADR-049 reconcile pass: spawn any roster agent that has no live session
+    // yet — the initial batch, host-restart recovery, and mid-task adds all
+    // converge here. No-op when every roster agent has a session.
+    if (ready) {
+      await this.reconcileSessions(channel);
+      // ADR-057: keep the container's MCP configs current so a connection
+      // added mid-task lands (effective at each session's next spawn).
+      await this.ensureMcpConfig(channel);
+    }
+    return ready;
+  }
+
+  /** Write the task's MCP configs when the connection set changed. */
+  private async ensureMcpConfig(channel: Channel): Promise<void> {
+    const fingerprint = JSON.stringify(channel.mcpConnections.map((c) => c.id));
+    if (channel.mcpConfigFingerprint === fingerprint) return;
+    channel.mcpConfigFingerprint = fingerprint;
+    await setupMcpTaskConfig(
+      channel.taskId,
+      channel.containerName,
+      channel.mcpConnections,
+      channel.roster.some((a) => a.kind === "codex"),
+    );
+  }
+
+  /** Spawn sessions for roster agents added after the initial start. */
+  private async reconcileSessions(channel: Channel): Promise<void> {
+    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);
+    if (!task || task.statusMirror !== "running") return;
+
+    for (const agent of missing) channel.spawning.add(agent.id);
+    try {
+      // Same per-agent materialisation the initial start does: package
+      // skills (idempotent — only the new agents' installs run), and the
+      // shared `uai` CLI rewritten for the full roster.
+      await installPackageSkills(channel.taskId, missing);
+      if (channel.browserTesting) {
+        await setupBrowserTesting(
+          channel.taskId,
+          channel.containerName,
+          channel.roster.some((a) => a.kind === "codex"),
+        );
+      }
+      const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
+      const cliSecret = loadTaskCliSecret(channel.taskId);
+      writeAgentCli(channel.taskId, channel.roster, apiUrl);
+
+      for (const agent of missing) {
+        const session = await this.factory.create({
+          taskId: channel.taskId,
+          agent,
+          containerName: channel.containerName,
+          systemPreamble: channel.preambles.get(agent.id) ?? "",
+          agentEnv: agentCliEnv(
+            channel.taskId,
+            agent,
+            task.ownerUserId,
+            apiUrl,
+            cliSecret,
+          ),
+        });
+        channel.sessions.set(agent.id, session);
+        session.onEvent((event) => {
+          void this.handleAgentEvent(channel, agent.id, event);
+        });
+      }
+    } finally {
+      for (const agent of missing) channel.spawning.delete(agent.id);
+    }
   }
 
   private async startSessions(channel: Channel): Promise<boolean> {
@@ -246,6 +411,21 @@ class Orchestrator {
     // tasks. Never throws.
     await installPackageSkills(channel.taskId, channel.roster);
 
+    // ADR-053: wire the Playwright MCP browser (configs + backgrounded
+    // Chromium install) before agents spawn. Idempotent + best-effort.
+    if (channel.browserTesting) {
+      await setupBrowserTesting(
+        channel.taskId,
+        channel.containerName,
+        channel.roster.some((a) => a.kind === "codex"),
+      );
+    }
+
+    // ADR-057: the owner's MCP connections, reached through the host gateway
+    // (tokens never enter the container) — written BEFORE agents spawn so
+    // first sessions load them.
+    await this.ensureMcpConfig(channel);
+
     // ADR-048: write the in-container `uai` CLI (apiUrl only, no token) into the
     // workspace. Each agent's OWN task token — carrying only ITS permissions — is
     // injected per-agent via its docker exec env below, so per-persona permissions
@@ -449,6 +629,15 @@ class Orchestrator {
           agentId,
           reason: event.message,
         });
+        // The session is DEAD — drop it so the reconciling ensureSessions
+        // respawns it on the next delivery/ensure. Without this the agent
+        // becomes a zombie: the map still holds the dead session and every
+        // later deliver "succeeds" into a closed pipe (found live 2026-07-08
+        // 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;
       }
       case "turn_complete": {
@@ -467,6 +656,11 @@ class Orchestrator {
         break;
       }
       case "exit":
+        // 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;
     }
   }
@@ -484,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({
@@ -754,12 +949,49 @@ export function buildSystemPreamble(
   globalContext: string | undefined,
   workspacePath: string,
   taskBranch: string,
+  humans?: ChannelHuman[],
+  browserTesting?: boolean,
 ): string {
   const channelList = roster
     .map((a) =>
       a.id === agent.id ? `@${a.id} (${a.label}, you)` : `@${a.id} (${a.label})`,
     )
     .join(", ");
+  // ADR-049: with several humans in the chat, brief the agent on who they are
+  // and how to address one specifically. Single-human tasks keep the original
+  // wording byte-identical.
+  const multiHuman = (humans?.length ?? 0) > 1;
+  const humanList = (humans ?? [])
+    .map((h) => `@${h.handle} (${h.name}${h.isOwner ? ", task owner" : ""})`)
+    .join(", ");
+  const humanIntro = multiHuman
+    ? [
+        `SEVERAL humans share this channel: ${humanList}. Their messages`,
+        "arrive prefixed with the sender's name so you can tell them apart.",
+        "`@you` still works and reaches the human you're currently talking",
+        "to (whoever last addressed you); to reach a SPECIFIC human, mention",
+        "their handle instead (e.g. `@" +
+          (humans?.[0]?.handle ?? "name") +
+          "`). Mentioning a human sends a",
+        "NOTIFICATION, so use it sparingly — only when you actually need",
+        "them: a decision you can't make, a blocker, an approval, or you've",
+        "finished your work and are handing it back. For everything else —",
+        "status updates, thinking out loud, a direct reply to something they",
+        "just asked, acknowledgments — post in the channel WITHOUT",
+        "@-mentioning; they can read the channel and don't need a ping for",
+        "every message.",
+      ]
+    : [
+        "The human you're working with is **@you**. @-mentioning them sends a",
+        "NOTIFICATION, so use it sparingly — only when you actually need them: a",
+        "decision you can't make, a blocker, an approval, or you've finished your",
+        "work and are handing it back for them to act on (e.g. `@you which`",
+        "`approach do you prefer?` or `@you done — PR is up for review`). For",
+        "everything else — status updates, thinking out loud, a direct reply to",
+        "something they just asked, acknowledgments — post in the channel WITHOUT",
+        "@-mentioning @you; they can read the channel and don't need a ping for",
+        "every message. Do NOT reflexively end messages with @you.",
+      ];
   const projectLines =
     projects.length === 0
       ? ["(none mounted)"]
@@ -781,15 +1013,7 @@ export function buildSystemPreamble(
     "",
     `Agents in this channel: ${channelList}.`,
     "",
-    "The human you're working with is **@you**. @-mentioning them sends a",
-    "NOTIFICATION, so use it sparingly — only when you actually need them: a",
-    "decision you can't make, a blocker, an approval, or you've finished your",
-    "work and are handing it back for them to act on (e.g. `@you which`",
-    "`approach do you prefer?` or `@you done — PR is up for review`). For",
-    "everything else — status updates, thinking out loud, a direct reply to",
-    "something they just asked, acknowledgments — post in the channel WITHOUT",
-    "@-mentioning @you; they can read the channel and don't need a ping for",
-    "every message. Do NOT reflexively end messages with @you.",
+    ...humanIntro,
     "",
     "An agent only receives a message when it is explicitly @-mentioned",
     "(or addressed by the human) — so always @-mention the agent (or @you)",
@@ -827,6 +1051,15 @@ export function buildSystemPreamble(
     "context (e.g. the human shared a file or instruction with another",
     "agent); it's appended live, so re-read it for the latest.",
     "",
+    "Two channel conventions (ADR-050): (1) If your reply @-mentions nobody,",
+    "uai hands it back to whoever prompted you — so when you're ANSWERING,",
+    "just answer plainly; you don't need to re-mention the asker. Mention",
+    "someone only to bring them in or hand work off. (2) You may occasionally",
+    "receive a `[channel check-in]` asking you to catch up on the channel.",
+    "Read the transcript, and speak ONLY if you have something substantive to",
+    "add; otherwise reply with exactly `PASS` — a PASS reply is discarded and",
+    "never shown to anyone, so it is always a safe way to decline a turn.",
+    "",
     "Hand off when you finish your part of the work. When you've made",
     "and committed your changes, or completed a review, end your reply by",
     "@-mentioning the agent who should act next and telling them what you",
@@ -886,6 +1119,28 @@ export function buildSystemPreamble(
           "",
         ]
       : []),
+    // ADR-053: the in-container browser, when the project opted in.
+    ...(browserTesting
+      ? [
+          "## Browser",
+          "",
+          "This container has a headless Chromium available through the",
+          "`browser` MCP server (Playwright). Use it to VERIFY UI work",
+          "end-to-end — the dev server you're building runs in this same",
+          "container, so navigate to `http://localhost:<port>` directly.",
+          "Prefer accessibility snapshots for navigation and assertions;",
+          "take an actual screenshot only when rendering matters (vision",
+          "input is expensive). To show a screenshot in the chat, save it",
+          "under `/workspace/.uai/attachments/<name>.png` and reference it",
+          "in your reply as `[image: /workspace/.uai/attachments/<name>.png]`.",
+          "Your browser runs on a virtual display the humans can WATCH live",
+          "(the \"browser\" preview) — nothing for you to do about that.",
+          "The first browser launch in a fresh container may take a minute",
+          "while Chromium's system deps finish installing — retry once if",
+          "it fails immediately after task start.",
+          "",
+        ]
+      : []),
     // ADR-048: tell agents with permissions about their `uai` CLI.
     ...((agent.permissions?.length ?? 0) > 0
       ? [
@@ -904,7 +1159,12 @@ export function buildSystemPreamble(
             (agent.permissions?.includes("memory.read")
               ? ", `memory search <query>`"
               : "") +
-            ".",
+            ", `react <heart|check|x> [--msg #id]`.",
+          "**Reacting:** `uai react check` is a lightweight ack of the message",
+          "you were last handed — use it to acknowledge an instruction or",
+          "approve a proposal without spending a whole reply (❌ = disagree,",
+          "❤️ = appreciation). Messages in chat.md carry their `#id` if you",
+          "want to react to an older one. Reactions wake nobody.",
           ...(agent.permissions?.includes("tasks.create")
             ? [
                 "**Creating a task in Uai:** when a human asks you to create/file/",

package/lib/standard-image.ts

@@ -17,7 +17,9 @@
  */
 
 import { spawn } from "node:child_process";
-import { dirname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** Pinned, host-wide constants (must match task-up.sh and the compose gen). */
@@ -57,6 +59,40 @@ export function standardRuntimes(): Array<{
   }));
 }
 
+/** Image label carrying the build-context content hash (rebuild trigger). */
+const CONTEXT_HASH_LABEL = "com.runuai.context-hash";
+
+/**
+ * Content-hash the build context (every file under images/standard, sorted
+ * by relative path). Null when the context can't be read — the caller then
+ * keeps whatever image exists.
+ */
+async function hashBuildContext(): Promise<string | null> {
+  try {
+    const root = standardImageDir();
+    const files: string[] = [];
+    const walk = async (dir: string, prefix: string): Promise<void> => {
+      for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) await walk(join(dir, entry.name), rel);
+        else files.push(rel);
+      }
+    };
+    await walk(root, "");
+    files.sort();
+    const hash = createHash("sha256");
+    for (const rel of files) {
+      hash.update(rel);
+      hash.update("\0");
+      hash.update(await readFile(join(root, rel)));
+      hash.update("\0");
+    }
+    return hash.digest("hex").slice(0, 32);
+  } catch {
+    return null;
+  }
+}
+
 /** Absolute path to the standard image build context. */
 function standardImageDir(): string {
   const here = dirname(fileURLToPath(import.meta.url));
@@ -177,6 +213,65 @@ async function ensureVolumeAgentClis(): Promise<void> {
   }
 }
 
+/**
+ * Upgrade the shared volume's agent CLIs to latest — once per HOST START, not
+ * per task. Per-task installs would add npm latency to every task-up, race
+ * concurrent starts on the shared volume, and give a broken vendor release a
+ * fleet-wide blast radius with no rollback; host restarts are the deliberate
+ * update moment (sessions respawn then anyway, and a bad release is one
+ * `UAI_AGENT_CLI_AUTOUPDATE=0` + manual pin away from contained). Running
+ * sessions keep their already-loaded process; new spawns pick up the new bin.
+ * Best-effort: an offline registry just logs and keeps the current versions.
+ */
+async function upgradeVolumeAgentClis(): Promise<void> {
+  if (process.env.UAI_AGENT_CLI_AUTOUPDATE === "0") {
+    console.log("[host-agent] agent CLI auto-update disabled (UAI_AGENT_CLI_AUTOUPDATE=0)");
+    return;
+  }
+  const pkgs = VOLUME_AGENT_CLIS.map((c) => `${c.pkg}@latest`).join(" ");
+  const bins = VOLUME_AGENT_CLIS.map((c) => c.bin);
+  // npm's in-place upgrade renames the old package dir, which fails with
+  // ENOTEMPTY while (or right after) live sessions held it open through the
+  // volume. Fallback: remove the scoped dirs and install fresh — safe at host
+  // start, when the previous sessions' execs are gone.
+  const scopeDirs = "/opt/asdf-data/installs/nodejs/*/lib/node_modules/@anthropic-ai /opt/asdf-data/installs/nodejs/*/lib/node_modules/@openai";
+  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",
+    "/home/node",
+    "-v",
+    `${ASDF_DATA_VOLUME}:/opt/asdf-data`,
+    STANDARD_IMAGE_TAG,
+    "bash",
+    "-lc",
+    `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()}`,
+    );
+  } else {
+    console.warn(
+      `[host-agent] agent CLI upgrade skipped (exit ${upgrade.code ?? "spawn"}) — ` +
+        `tasks keep the volume's current versions. ${upgrade.stderr.trim().slice(0, 200)}`,
+    );
+  }
+}
+
 /**
  * Ensure the standard image and the shared asdf data volume exist, and that the
  * agent CLIs are present inside the volume. Builds the image only when `docker
@@ -196,24 +291,51 @@ export async function ensureStandardImage(): Promise<void> {
     if (vol.code === null) return;
   }
 
-  // 2. Ensure the image is built.
+  // 2. Ensure the image is built AND current. "Present" is not enough — a
+  //    Dockerfile change used to no-op forever because we only built when
+  //    inspect failed (found live 2026-07-08: ADR-053's baked packages never
+  //    landed). The build context is content-hashed into an image label;
+  //    a mismatch triggers a rebuild (layer cache keeps it cheap).
   let imageReady = false;
-  const inspect = await run("docker", ["image", "inspect", STANDARD_IMAGE_TAG]);
-  if (inspect.code === 0) {
-    console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} present`);
-    imageReady = true;
-  } else if (inspect.code === null) {
+  const contextHash = await hashBuildContext();
+  const inspect = await run("docker", [
+    "image",
+    "inspect",
+    "-f",
+    `{{index .Config.Labels "${CONTEXT_HASH_LABEL}"}}`,
+    STANDARD_IMAGE_TAG,
+  ]);
+  if (inspect.code === null) {
     console.warn(
       "[host-agent] docker unavailable; skipping standard image build. " +
         "Tasks will fail until docker is running.",
     );
     return;
+  }
+  const labeledHash = inspect.code === 0 ? inspect.stdout.trim() : null;
+  if (inspect.code === 0 && contextHash !== null && labeledHash === contextHash) {
+    console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} current`);
+    imageReady = true;
+  } else if (inspect.code === 0 && contextHash === null) {
+    // Can't hash (packaged install without the context?) — keep the image.
+    console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} present`);
+    imageReady = true;
   } else {
     const context = standardImageDir();
     console.log(
-      `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
+      inspect.code === 0
+        ? `[host-agent] standard image ${STANDARD_IMAGE_TAG} stale (context changed) — rebuilding from ${context}`
+        : `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
     );
-    const build = await run("docker", ["build", "-t", STANDARD_IMAGE_TAG, context]);
+    const build = await run("docker", [
+      "build",
+      "-t",
+      STANDARD_IMAGE_TAG,
+      ...(contextHash !== null
+        ? ["--label", `${CONTEXT_HASH_LABEL}=${contextHash}`]
+        : []),
+      context,
+    ]);
     if (build.code === 0) {
       console.log(`[host-agent] built standard image ${STANDARD_IMAGE_TAG}`);
       imageReady = true;
@@ -223,10 +345,15 @@ export async function ensureStandardImage(): Promise<void> {
           "continuing. Tasks needing the image will surface this error.\n" +
           build.stderr.trim(),
       );
+      // A stale-but-working image is better than none.
+      imageReady = labeledHash !== null;
     }
   }
 
   // 3. Reconcile the agent CLIs into the shared volume (it shadows the image's
   //    shims, so a stale volume can be missing one — the claude-127 bug).
-  if (imageReady) await ensureVolumeAgentClis();
+  if (imageReady) {
+    await ensureVolumeAgentClis();
+    await upgradeVolumeAgentClis();
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.4.2",
+  "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",