@foldrun/core 0.4.0 → 0.6.0

package/src/run-container.ts

@@ -25,15 +25,17 @@ import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { isPlatformPath, type ApiSpec, type Effort } from "./store.ts";
-import { divertedSummary, isDivertedPath } from "./test-mode.ts";
+import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.ts";
 import type { EventExtra } from "./step-exec.ts";
 import { isFileValue, fileContent } from "./secrets.ts";
 import { safeTenantSegment, type RuntimeSpec } from "./runtime.ts";
-import { dataRoot } from "./paths.ts";
 import type { ScriptSpec } from "./script-tools.ts";
 import type { ConsultSpec } from "./agent-tools.ts";
+import type { SubagentSpec } from "./subagents.ts";
+import { isOperatorEvent, type OperatorEvent } from "./operator.ts";
 import type { SearchRoot, RunDigest } from "./context-tools.ts";
 import type { TranslatorSpec } from "./translator.ts";
+import { parseBrowserPod, type BrowserPodOutcome } from "./browser-pod.ts";
 
 /** What crosses the boundary. Everything in here is values — pre-resolved
  *  secrets in headers, assembled prompt, serializable MCP configs. */
@@ -58,6 +60,8 @@ export interface ContainerStepInput {
    *  their agent.md files host-side. The driver rebuilds the consult tools
    *  in here; the callees run toolless, so nothing else need cross. */
   consults: ConsultSpec[];
+  /** `subagents:` — built host-side (runner.ts), plain JSON. */
+  subagents?: SubagentSpec[];
   timeoutSec?: number;
   /** The step's spend ceiling and the model's per-token price — see
    *  step-exec.ts. Values, so the driver can enforce them in the pod. */
@@ -70,6 +74,10 @@ export interface ContainerStepInput {
   /** `schema:` and `max_turns:`, resolved host-side — see ExecOptions. */
   schema?: Record<string, unknown> | boolean;
   maxTurns?: number;
+  /** `limits:` resolved host-side, and the SDK-name → foldrun-name map the
+   *  count reads (limits.ts) — enforced in the pod by the same hook. */
+  limits?: Record<string, number>;
+  toolOwners?: Record<string, string>;
   /** tools: [search] — the directories to search, as paths INSIDE the
    *  container (/workspace/…, /library/…). */
   search?: SearchRoot[];
@@ -77,10 +85,19 @@ export interface ContainerStepInput {
   history?: RunDigest[];
   /** tools: [desks] — the account's other workspaces' runs, gathered host-side. */
   desks?: RunDigest[];
+  /** tools: [ask] — ask_person, and how long it may wait for an answer. */
+  ask?: { timeoutSec: number };
   /** A Chat-Completions provider: the driver starts the runtime's translator
    *  on loopback and points the SDK at it. Null or absent: the env's
    *  ANTHROPIC_BASE_URL is spoken to directly. */
   translator?: TranslatorSpec | null;
+  /** A granted tool acts outward (`outward: true`): an executor that could
+   *  put a browsing step on the slim image keeps this one on the full image,
+   *  where a browser in the step is always there (browser-pod.ts). */
+  outward?: boolean;
+  /** "full" — this attempt must have the full image: the re-run after the
+   *  browser pod was lost. Absent lets the executor choose. */
+  image?: "full";
 }
 
 /**
@@ -122,11 +139,21 @@ export interface ContainerStepOutcome {
   data?: unknown;
   costUsd: number | null;
   usage?: { inputTokens: number; outputTokens: number } | null;
+  /** Every turn priced at its own model, when sub-agents ran on others —
+   *  see ExecOutcome.turnsCostUsd. */
+  turnsCostUsd?: number;
   /** What the sandbox actually touched — see the driver's readActuals. */
   res?: StepActuals | null;
   /** Set by the isolated executors only — an in-process step rents no
    *  sandbox, so it has no compute seconds to bill. */
   timing?: StepTiming | null;
+  /** Which runner image the sandbox ran, as the executor chose it: `pod`
+   *  when a browsing step ran on slim and browsed through the account's
+   *  browser pod. Absent from an executor with one image. */
+  image?: { variant: "full" | "slim"; why?: string; pod?: boolean } | null;
+  /** The pod's reconnects and, when it was lost, what the step had written —
+   *  see ExecOutcome.browserPod. */
+  browserPod?: BrowserPodOutcome;
 }
 
 /**
@@ -220,6 +247,33 @@ export function hashTree(dir: string): Record<string, string> {
   return out;
 }
 
+/**
+ * Every file's mtime under `dir`, relative path to milliseconds — so a copy
+ * that cannot carry times can have them put back. `kubectl cp` unpacks with
+ * `tar -m`, which stamps every file with the moment it landed; on 2026-09-24
+ * gbp-desk's reply-sheet check ("pending-replies.json written in the last
+ * hour") passed on a file last written on 2026-09-13, and the poster sent
+ * nothing. Every freshness check in every flow was answering "yes".
+ */
+export function mtimeManifest(dir: string): Record<string, number> {
+  const out: Record<string, number> = {};
+  const walk = (d: string) => {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const abs = path.join(d, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) walk(abs);
+      else out[path.relative(dir, abs).replaceAll("\\", "/")] = fs.statSync(abs).mtimeMs;
+    }
+  };
+  if (fs.existsSync(dir)) walk(dir);
+  return out;
+}
+
+/** The in-pod half of mtimeManifest: a node one-liner, run as root before `go`. */
+export const APPLY_MTIMES_JS =
+  `const fs=require("fs"),p=require("path");const m=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));` +
+  `for(const [r,t] of Object.entries(m)){try{fs.utimesSync(p.join(process.argv[2],r),t/1000,t/1000)}catch{}}`;
+
 const sha = (b: Buffer) => crypto.createHash("sha256").update(b).digest("hex");
 
 /**
@@ -355,25 +409,55 @@ export function applyContainerChanges(
 export const RUNTIME_CACHE = "/home/agent/.foldrun/runner/.runtimes";
 
 /**
- * The per-tenant directory backing that mount, or null when there is none.
+ * Where the platform's shared runtime layer is mounted, read-only, in a run
+ * pod — and read-write, one entry at a time, in the pod that builds an entry
+ * for it (foldrun-platform runtime-warm.ts). A fixed path for the same reason
+ * as RUNTIME_CACHE: a venv hard-codes its own location. Laid out as
+ * <FOLDRUN_DATA>/shared/.runtimes so the builder's prepareRuntime("shared", …)
+ * lands exactly here with FOLDRUN_DATA=/opt/foldrun-runtimes.
+ */
+export const SHARED_RUNTIMES = "/opt/foldrun-runtimes/shared/.runtimes";
+
+/** Docker's own volume-name charset: a leading alphanumeric, then
+ *  alphanumerics plus `_ . -`. The mount source is handed straight to the
+ *  daemon, so it is validated against this rather than assumed. */
+const DOCKER_VOLUME_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+
+/**
+ * The per-tenant runtime cache mount — a Docker NAMED volume and the fixed
+ * path it mounts at — or null when there is none.
  *
- * Per-tenant, not shared. A shared cache would store one copy of pandas
- * instead of one per account, but it would also be mutable state that one
- * tenant's step writes and another tenant's step then *executes* — a poisoned
- * venv arriving as a trusted local file, which is precisely the path gVisor,
- * the capability drop and the egress policy all exist to close. Disk is the
- * cheaper thing to spend. If the duplication ever stops being cheap, the fix
- * is a read-only mount filled by a trusted builder, not a writable shared one.
+ * A named volume, not a host path. The run's `docker create` is issued to the
+ * host daemon over the mounted socket, and that daemon cannot resolve a path
+ * under the platform's own FOLDRUN_DATA — which under compose is itself a named
+ * volume, or a directory Docker Desktop has not shared — so `-v <hostpath>:…`
+ * failed with "mounts denied". A named volume is resolved by the daemon, needs
+ * no host sharing, and on first use is seeded from the image's mount point,
+ * which the runner image creates owned by the agent user (the DOCKERFILE below,
+ * `${RUNTIME_CACHE}`) — so the fresh cache is writable without a host-side chown.
  *
- * Deliberately NOT under `<tenant>/.runtimes`, which is the *host* cache: the
- * venvs there carry host absolute paths and would be unusable inside a runner.
- * Two roots, so a hit is always a real hit.
+ * Per-tenant, not shared. A shared cache would store one copy of pandas instead
+ * of one per account, but it would also be mutable state that one tenant's step
+ * writes and another tenant's step then *executes* — a poisoned venv arriving
+ * as a trusted local file, which is precisely the path gVisor, the capability
+ * drop and the egress policy all exist to close. Disk is the cheaper thing to
+ * spend. One volume per tenant keeps that boundary; each carries a
+ * `foldrun.io/tenant` label so it can be found and pruned (self-hosting/README.md).
+ *
+ * The venvs inside carry the runner's own absolute paths, distinct from the
+ * host's `<tenant>/.runtimes` cache — two roots, so a hit is always a real hit.
  */
-export function runtimeCacheDir(tenant: string | undefined): string | null {
+export function runtimeCacheMount(
+  tenant: string | undefined,
+): { source: string; target: string } | null {
   if (process.env.FOLDRUN_RUNTIME_CACHE === "off") return null;
   const safe = tenant ? safeTenantSegment(tenant) : null;
   if (!safe) return null;
-  return path.join(dataRoot(), safe, ".runtimes-sandbox");
+  const source = `foldrun-rt-${safe}`;
+  // safeTenantSegment already yields Docker's charset and `foldrun-rt-` is a
+  // safe leading token — but the source is what the daemon binds, so prove it.
+  if (!DOCKER_VOLUME_NAME.test(source)) return null;
+  return { source, target: RUNTIME_CACHE };
 }
 
 // ---------- the runner image ----------
@@ -433,9 +517,11 @@ try {
   const { buildScriptTools } = await import("@foldrun/core/script-tools");
   const { buildConsultTools } = await import("@foldrun/core/agent-tools");
   const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import("@foldrun/core/context-tools");
+  const { httpChannel, buildAskTool, inboxReader } = await import("@foldrun/core/operator");
   const { startTranslator } = await import("@foldrun/core/translator");
   const { prepareRuntime } = await import("@foldrun/core/runtime");
   const { materializeFileSecrets } = await import("@foldrun/core/secret-files");
+  const { paidWebActions } = await import("@foldrun/core/browser-pod");
 
   const agentDir = "/workspace/" + input.agentRel;
   // HOME is where a bare relative path lands when anything resolves one
@@ -457,6 +543,10 @@ try {
     : { interpreters: {}, env: {}, log: [], error: null };
   for (const line of runtime.log) emit("info", "runtime: " + line);
   if (runtime.error) emit("error", "runtime: " + runtime.error);
+  // The step's own environment gets it too, not only the script tools: an
+  // agent that runs "python3 x.py" or a shebang script through Bash should
+  // meet the packages its runtime declared, not the image's bare python.
+  Object.assign(env, runtime.env);
 
   // API and script tools, rebuilt in here from their specs. Secrets were
   // substituted into API headers before the input crossed the boundary, so
@@ -484,6 +574,11 @@ try {
   const search = buildSearchTools(input.search ?? []);
   const history = input.history?.length ? buildHistoryTools(input.history) : { server: null };
   const desks = input.desks?.length ? buildDeskTools(input.desks) : { server: null };
+  // A person in the loop, over the proxy this step's lease already names:
+  // ask_person when tools: [ask], and the run's inbox after every tool call.
+  const channel = httpChannel(env.FOLDRUN_EGRESS);
+  const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };
+  const inbox = channel ? inboxReader(channel, emit) : undefined;
 
   const outcome = await executeStep({
     agentDir,
@@ -502,8 +597,11 @@ try {
       ...(search.server ? { foldrun_search: search.server } : {}),
       ...(history.server ? { foldrun_history: history.server } : {}),
       ...(desks.server ? { foldrun_desks: desks.server } : {}),
+      ...(ask.server ? { foldrun_ask: ask.server } : {}),
       ...input.mcpServers,
     },
+    ...(inbox ? { inbox } : {}),
+    ...(input.subagents?.length ? { subagents: input.subagents } : {}),
     env,
     timeoutSec: input.timeoutSec,
     budgetUsd: input.budgetUsd,
@@ -514,6 +612,12 @@ try {
     output: input.output,
     schema: input.schema,
     maxTurns: input.maxTurns,
+    ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),
+    // Slim browsing: the platform put this step on the slim image to browse
+    // through the account's pod, and named the file the web tool logs its
+    // reconnects to. A lost pod stops the step; what it wrote decides what
+    // the runner does next (browser-pod.ts).
+    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env), ...(env.FOLDRUN_BROWSER_INIT ? { browseInit: env.FOLDRUN_BROWSER_INIT } : {}) } } : {}),
     // The container is the boundary; the SDK's own bash sandbox here would
     // only block declared network use (SSH, curl) for no added safety.
     sandboxBash: false,
@@ -528,6 +632,7 @@ try {
   // A consult's spend belongs to the step that asked.
   const consultCost = consult.drainCost();
   if (consultCost > 0) outcome.costUsd = (outcome.costUsd ?? 0) + consultCost;
+  if (consultCost > 0 && typeof outcome.turnsCostUsd === "number") outcome.turnsCostUsd += consultCost;
   process.stdout.write(JSON.stringify({ e: "done", ...outcome, res: readActuals() }) + "\\n");
   process.exit(0);
 } catch (err) {
@@ -542,35 +647,251 @@ try {
 }
 `;
 
+// Core itself is installed in a stage of its own (CORE_STAGE) and only the
+// result is copied in: the tarball and the package README — which explains
+// foldrun to a person reading the repo, and which no step reads — stay in
+// that stage and never become a layer of the image. Owner rule, 2026-10-02:
+// foldrun's own docs live in git, not in containers.
+const CORE_STAGE = `FROM base AS core
+WORKDIR /opt/runner
+COPY foldrun-core.tgz ./
+RUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\
+ && npm cache clean --force >/dev/null 2>&1 \\
+ && rm -f foldrun-core.tgz node_modules/@foldrun/core/README.md
+`;
+
 // docker cp writes root-owned files, so the entrypoint starts as root for
 // exactly two commands — chown the copied-in trees, drop to the agent user —
 // and the run flags grant only the three capabilities those two commands
 // need. By the time any model-directed code executes, the process is uid
 // 10001 with no capabilities at all.
-const DOCKERFILE = `FROM node:22-slim
+const CORE_INSTALL = `WORKDIR /opt/runner
+COPY --from=core --chown=agent:agent /opt/runner/ ./
+COPY --chown=agent:agent driver.mjs entry.sh ./
+RUN mkdir -p /workspace /library /opt/runner/job ${RUNTIME_CACHE} ${SHARED_RUNTIMES} \\
+ && chown agent:agent /opt/runner \\
+ && chown -R agent:agent /workspace /library /opt/runner/job /home/agent/.foldrun /opt/foldrun-runtimes \\
+ && chmod +x /opt/runner/entry.sh
+ENTRYPOINT ["/opt/runner/entry.sh"]
+`;
+
+/** The uv release copied into the image. Pinned: a floating uv is a floating
+ *  resolver, and the runtime cache is keyed on the declaration, not on it. */
+export const UV_VERSION = "0.11.25";
+
+/** How many times a best-effort engine download is tried before the build
+ *  gives up on it, and the wait before the second and third (15s, then 30s).
+ *  A GitHub release or Google's apt mirror that blinks for a minute used to
+ *  cost the engine outright; on x86_64 that now fails the build, so a
+ *  transient blip would fail a deploy. */
+export const ENGINE_DOWNLOAD_ATTEMPTS = 3;
+
+/** `retry <engine> <command…>`: one shell function, defined at the top of each
+ *  RUN that downloads an engine (a RUN is its own shell). Its lines start
+ *  "runner image:" like every engine line, and go to stderr so a quiet
+ *  install (>/dev/null) still shows them — the deploy greps them into the
+ *  step summary (buildFailureSummary). */
+export const RETRY_SH = `retry() { what=$1; shift; n=1; until "$@"; do if [ "$n" -ge ${ENGINE_DOWNLOAD_ATTEMPTS} ]; then echo "runner image: $what - download failed $n times, giving up" >&2; return 1; fi; echo "runner image: $what - download failed (attempt $n of ${ENGINE_DOWNLOAD_ATTEMPTS}), retrying in $((n * 15))s" >&2; sleep $((n * 15)); n=$((n + 1)); done; }`;
+
+/** The base both targets start from, pinned by digest. The tag alone floats:
+ *  `node:22-slim` is re-pushed for every Node patch and Debian point release,
+ *  and will change Debian release when the Node image decides to, so the
+ *  same runner tag — a hash of this text — could hold different bytes on two
+ *  rebuilds. With the digest in the text, new base bytes mean a new tag.
+ *
+ *  Debian 13 (trixie), not the 12 that `node:22-slim` still names: its glibc
+ *  (2.41) runs Lightpanda past 0.3.6, which wants 2.38; Debian 12 has 2.36.
+ *  Python is 3.13 here (3.11 on 12): runtime.ts checkEntry rebuilds a cached
+ *  venv whose interpreter moved, once per declaration.
+ *
+ *  Raise it on purpose (foldrun-infra/README.md, "Runner images"): read the
+ *  current digest of the tag, put it here, build both targets on both arches
+ *  and make one browse call per engine on the full image:
+ *    docker buildx imagetools inspect node:22-trixie-slim --format '{{json .Manifest}}' | jq -r .digest
+ *  The digest names the multi-arch index, so the one pin serves amd64 and
+ *  arm64 alike. */
+export const NODE_BASE = "node:22-trixie-slim@sha256:b26b04c123d9ff8ab646ceb18b9d75a1173acf64b9a401094b906d27b29338d4";
+
+// Two images from one file, as build targets.
+//
+//   full  (the default, the last stage) — everything, browsers included. The
+//         per-account browser pod runs it, and so does any step that may
+//         browse, because the tool falls back to in-pod Chromium whenever
+//         the pod is unavailable or the run is a test.
+//   slim  — the same base, core and Playwright *client*, no browsers. About
+//         a quarter of the size: the browsers were 1.4 GB of a 3.1 GB image
+//         that every step pulled and every step started, whether or not it
+//         ever opened a page. A step that grants no browsing runs this
+//         (run-k8s.ts picks), and its declared packages arrive at run time
+//         through the runtime cache — uv is in the base for exactly that.
+//
+// The browsers sit BELOW the core install in `full`, as they always have,
+// so a core change rebuilds one thin layer and not 1.4 GB of Chromium.
+export const DOCKERFILE = `FROM ${NODE_BASE} AS base
 RUN apt-get update \\
  && apt-get install -y --no-install-recommends python3 python3-venv ca-certificates bash util-linux tar openssh-client sshpass git curl \\
  && rm -rf /var/lib/apt/lists/* \\
  && useradd -m -u 10001 agent
+# uv builds the declared python environments (runtime.ts): a fraction of
+# pip's time, and it can fetch a pinned python the image does not carry.
+COPY --from=ghcr.io/astral-sh/uv:${UV_VERSION} /uv /uvx /usr/local/bin/
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/browser NODE_PATH=/usr/local/lib/node_modules
+
+${CORE_STAGE}
+FROM base AS slim
+# Fonts, because a step that draws text without a browser still needs them:
+# the full image gets 51 from Playwright's --with-deps, slim had none, so from
+# 2026-09-29 (when non-browsing steps moved to slim) every resvg/sharp diagram
+# rendered its labels as empty boxes — expert-witness-desk's validator failed
+# four passes on a post image that was "three empty boxes". DejaVu covers
+# Latin, Greek and Cyrillic in a few MB; fontconfig is how renderers find it.
+# DejaVu alone still drew emoji, Chinese, Japanese, Korean, Devanagari and
+# Thai as empty boxes (reproduced 2026-10-01 with resvg-js 2.6 and sharp
+# 0.34), so four more, the smallest set that drew all of them — 8 MB:
+#   Symbola     emoji and symbols, as outlines. NOT Noto Color Emoji (10 MB):
+#               resvg draws nothing from its bitmap glyphs, so a resvg
+#               diagram kept its empty boxes.
+#   WenQuanYi Micro Hei   Chinese, Japanese kana and Korean Hangul, one file.
+#   Lohit Devanagari, Loma   Hindi and Thai.
+# Here, not in base, so the full image's browser layers stay cached.
+RUN apt-get update \\
+ && apt-get install -y --no-install-recommends fonts-dejavu-core fontconfig fonts-symbola fonts-wqy-microhei fonts-lohit-deva fonts-tlwg-loma-otf \\
+ && rm -rf /var/lib/apt/lists/* \\
+ && fc-cache -f >/dev/null
+# The Playwright client only, the same pinned version as the browser pod's
+# server (the wire protocol is version-locked), so a tool that imports it
+# still loads; there is nothing here for it to launch.
+# npm's download cache is dropped in the same layer: it was 190 MB of every
+# image, read by nothing after the build.
+RUN npm install -g playwright@1.63.0 axe-core@4.13.0 >/dev/null && npm cache clean --force >/dev/null 2>&1
+${CORE_INSTALL}
+FROM base AS browsers
 # Real browsers, because directories and portals increasingly render with
-# JavaScript and WebFetch sees only the empty shell. Chromium is the one the
+# JavaScript and a plain fetch sees only the empty shell. Chromium is the one the
 # browser tool drives by default; Firefox and WebKit (Safari's engine) are
 # there for an agent asked to see a page the way those render it. Installed
 # to a fixed path the agent user can read (the default cache would be
 # root's HOME). The browsers' own sandboxes are disabled at launch time — in
 # this platform the container/gVisor IS the sandbox, and the two fight.
-ENV PLAYWRIGHT_BROWSERS_PATH=/opt/browser NODE_PATH=/usr/local/lib/node_modules
-RUN npm install -g playwright@1 >/dev/null \\
+# Pinned exactly, not @1: web browse's numbered elements use ariaSnapshot's
+# "ai" mode (1.59+), and the per-account browser pod runs this same image, so
+# a floating version would move both under a working tool on any rebuild.
+# Raise it on purpose, with the gallery tests and one real call.
+# axe-core beside it is web browse's mode=a11y: one file the tool injects
+# into the page; without it the mode falls back to its own shorter checks.
+# Xvfb by name: the browser pod starts it at boot and web browse starts one
+# per call for headless: false. It used to arrive only as one of Playwright's
+# --with-deps packages, so a Playwright bump that dropped it would have
+# broken every windowed browser without a word. No xauth: nothing here runs
+# xvfb-run, and Xvfb started without -auth takes the local client as it is.
+RUN apt-get update \\
+ && apt-get install -y --no-install-recommends xvfb \\
+ && rm -rf /var/lib/apt/lists/*
+# Google Chrome and Chrome beta come from Google's apt repository, which
+# Playwright adds; each is tried ENGINE_DOWNLOAD_ATTEMPTS times. Only on
+# x86_64: Google ships no Linux Chrome for arm64, so there it is not tried.
+RUN npm install -g playwright@1.63.0 axe-core@4.13.0 >/dev/null \\
  && playwright install --with-deps chromium firefox webkit >/dev/null \\
- && chmod -R a+rX /opt/browser
-WORKDIR /opt/runner
-COPY foldrun-core.tgz driver.mjs entry.sh ./
-RUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\
- && mkdir -p /workspace /library /opt/runner/job ${RUNTIME_CACHE} \\
- && chown -R agent:agent /workspace /library /opt/runner /home/agent/.foldrun \\
- && chmod +x /opt/runner/entry.sh
-ENTRYPOINT ["/opt/runner/entry.sh"]
-`;
+ && ${RETRY_SH} \\
+ && if [ "$(uname -m)" = x86_64 ]; then \\
+      retry chrome playwright install --with-deps chrome >/dev/null || echo "runner image: chrome not installed - engine: chrome would fall back to chromium" >&2; \\
+      retry chrome-beta playwright install --with-deps chrome-beta >/dev/null || echo "runner image: chrome-beta not installed" >&2; \\
+    else echo "runner image: no Google Chrome for $(uname -m) - engine: chrome falls back to chromium"; fi \\
+ && chmod -R a+rX /opt/browser \\
+ && npm cache clean --force >/dev/null 2>&1
+# Lightpanda (engine: lightpanda): a browser that runs the JavaScript and
+# never draws — a fraction of Chromium's memory for reading and filling
+# pages. Its own program, which web browse starts beside a call and drives
+# over the DevTools protocol; shipped unmodified (AGPL-3.0). Pinned by
+# checksum (GitHub's own asset digests, checked again here). 0.4.1 since the
+# move to Debian 13: 0.3.7 on wants glibc 2.38, and Debian 12's 2.36 held it
+# at 0.3.6. An arch without a build leaves the engine out, and the tool says
+# so when asked for it. Each download (with its checksum) is tried
+# ENGINE_DOWNLOAD_ATTEMPTS times before the engine is left out.
+# Raise it on purpose: the new release's two sha256s, then one
+# engine=lightpanda call on each arch.
+RUN arch=$(uname -m) \\
+ && case "$arch" in \\
+      x86_64) sum=1d40801e72c0bc61b2cbd3f3562bcfc46de7b79e0568f33f686b64f2e587610a ;; \\
+      aarch64) sum=664775c7f5ab69cc3189954c7f9345e25c167cb4dace016173e629f9a5e82c42 ;; \\
+      *) sum= ;; \\
+    esac \\
+ && mkdir -p /opt/browser/lightpanda \\
+ && ${RETRY_SH} \\
+ && fetch() { curl -fsSL -o /opt/browser/lightpanda/lightpanda "https://github.com/lightpanda-io/browser/releases/download/0.4.1/lightpanda-$arch-linux" \\
+      && echo "$sum  /opt/browser/lightpanda/lightpanda" | sha256sum -c - >/dev/null; } \\
+ && if [ -n "$sum" ] && retry lightpanda fetch; then \\
+      chmod a+rx /opt/browser/lightpanda/lightpanda && /opt/browser/lightpanda/lightpanda version; \\
+    else rm -f /opt/browser/lightpanda/lightpanda; echo "runner image: lightpanda not installed for $arch - engine: lightpanda says so when asked" >&2; fi
+# Obscura (engine: obscura): a headless browser in Rust around V8 that does
+# draw — screenshots, a raster PDF, a screencast — light like Lightpanda.
+# Apache-2.0. The plain build, not -stealth: this platform does not help a
+# page not see automation. Two binaries, obscura and obscura-worker, which
+# must sit side by side. Pinned by checksum; glibc 2.35 is its floor, so
+# Debian 13 (2.41) runs it. As above, a download is tried
+# ENGINE_DOWNLOAD_ATTEMPTS times, then a failed one leaves the engine out.
+RUN arch=$(uname -m) \\
+ && case "$arch" in \\
+      x86_64) sum=1534d1e6ddaf3d080ec4091eb41d0a4d8cc042a48b607d3c410fc13b482a9eec ;; \\
+      aarch64) sum=5ecf980bca3060236a7a86ec7ed83d943e6598ee87caa46d20325d90bc75f979 ;; \\
+      *) sum= ;; \\
+    esac \\
+ && mkdir -p /opt/browser/obscura \\
+ && ${RETRY_SH} \\
+ && fetch() { curl -fsSL -o /tmp/obscura.tgz "https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.3/obscura-$arch-linux.tar.gz" \\
+      && echo "$sum  /tmp/obscura.tgz" | sha256sum -c - >/dev/null; } \\
+ && if [ -n "$sum" ] && retry obscura fetch \\
+      && tar -xzf /tmp/obscura.tgz -C /opt/browser/obscura obscura obscura-worker; then \\
+      chmod a+rx /opt/browser/obscura/obscura /opt/browser/obscura/obscura-worker && /opt/browser/obscura/obscura --version; \\
+    else rm -rf /opt/browser/obscura/*; echo "runner image: obscura not installed for $arch - engine: obscura says so when asked" >&2; fi \\
+ && rm -f /tmp/obscura.tgz
+# What this image actually has, written down: /opt/browser/engines.json, one
+# entry per engine (its path and version, or null when the install above
+# left it out) plus Xvfb. Chromium's version is its own --version (dotted,
+# so FOLDRUN_RUNNER_ENGINES carries it: a pinned user_agent on engine
+# chromium is compared with it, not with Google Chrome's) then the build.
+# web browse reads it for its "built without" answer, and the deploy reads
+# it to report the engines beside the version.
+# On x86_64 a missing engine FAILS the build: every engine ships for that
+# arch, so a gap there is a failed download, and an image that quietly lacks
+# the Chrome or Lightpanda a desk names would fail those runs instead. A
+# failed build leaves the previous image running and says why. Elsewhere
+# (arm64 has no Google Chrome) the gap is recorded and the image ships.
+RUN node -e ' \\
+  const fs = require("fs"), cp = require("child_process"), pw = require("playwright"); \\
+  const at = (p) => (p && fs.existsSync(p) ? p : null); \\
+  const ver = (bin, args) => { try { return cp.execFileSync(bin, args, { timeout: 30000, stdio: ["ignore", "pipe", "ignore"] }).toString().trim().split("\\n")[0] || null; } catch { return null; } }; \\
+  const one = (p, v) => (p ? { path: p, version: v } : null); \\
+  const pwBuild = (p) => (p ? (p.match(/(chromium|firefox|webkit)-(\\d+)/) || [])[0] || null : null); \\
+  const lp = at("/opt/browser/lightpanda/lightpanda"); \\
+  const cr = at(pw.chromium.executablePath()); \\
+  const ob = at("/opt/browser/obscura/obscura-worker") && at("/opt/browser/obscura/obscura"); \\
+  const engines = { \\
+    chromium: one(cr, cr && [ver(cr, ["--version"]), pwBuild(cr)].filter(Boolean).join(" ")), \\
+    chrome: one(at("/opt/google/chrome/chrome"), ver("/opt/google/chrome/chrome", ["--version"])), \\
+    "chrome-beta": one(at("/opt/google/chrome-beta/chrome"), ver("/opt/google/chrome-beta/chrome", ["--version"])), \\
+    firefox: one(at(pw.firefox.executablePath()), pwBuild(pw.firefox.executablePath())), \\
+    webkit: one(at(pw.webkit.executablePath()), pwBuild(pw.webkit.executablePath())), \\
+    lightpanda: one(lp, lp && ver(lp, ["version"])), \\
+    obscura: one(ob, ob && ver(ob, ["--version"])), \\
+  }; \\
+  const xvfb = ver("sh", ["-c", "command -v Xvfb"]); \\
+  const arch = cp.execFileSync("uname", ["-m"]).toString().trim(); \\
+  const manifest = { arch, playwright: require("playwright/package.json").version, engines, xvfb }; \\
+  fs.writeFileSync("/opt/browser/engines.json", JSON.stringify(manifest, null, 2) + "\\n"); \\
+  console.log(JSON.stringify(manifest)); \\
+  const missing = ["chromium", "chrome", "firefox", "webkit", "lightpanda", "obscura"].filter((e) => !engines[e]).concat(xvfb ? [] : ["Xvfb"]); \\
+  if (missing.length && arch === "x86_64") { \\
+    console.error("runner image: MISSING ENGINES on x86_64: " + missing.join(", ")); \\
+    console.error("runner image: every engine ships for x86_64, so a missing one is a failed download (the retry lines above say which) - failing the build"); \\
+    process.exit(1); \\
+  } \\
+  if (missing.length) console.error("runner image: built without " + missing.join(", ") + " on " + arch); \\
+ ' \\
+ && chmod a+r /opt/browser/engines.json
+
+FROM browsers AS full
+${CORE_INSTALL}`;
 
 const ENTRY = `#!/bin/sh
 set -e
@@ -601,7 +922,10 @@ function corePackageDir(): string {
   throw new Error("could not locate @foldrun/core's package root");
 }
 
-export function runnerImageTag(): string {
+/** Which build target of the runner image (see DOCKERFILE). */
+export type RunnerVariant = "full" | "slim";
+
+export function runnerImageTag(variant: RunnerVariant = "full"): string {
   // The fingerprint hashes the *built code*, not the version — a version
   // string that nobody bumped would pin every future run to the runner
   // image of whatever core happened to build first.
@@ -613,7 +937,7 @@ export function runnerImageTag(): string {
       if (fs.statSync(abs).isFile()) hash.update(String(entry)).update(fs.readFileSync(abs));
     }
   }
-  return `foldrun-runner:${hash.digest("hex").slice(0, 12)}`;
+  return `foldrun-runner:${hash.digest("hex").slice(0, 12)}${variant === "slim" ? "-slim" : ""}`;
 }
 
 /**
@@ -629,11 +953,31 @@ export function runnerImageTag(): string {
  * (tonistiigi/binfmt); the publisher does that itself, every time, because
  * the registration does not survive a reboot.
  */
-export function ensureRunnerImage(opts: { platform?: string } = {}): { tag: string; log: string[] } {
+/**
+ * Which image a step runs in: an explicit FOLDRUN_RUNNER_IMAGE when one is
+ * set, otherwise the content-hash tag core builds itself. `explicit` is what
+ * ensureRunnerImage checks to skip the build — an empty string is *not* an
+ * image name (it is `docker build -t ""` → "repository name must have at
+ * least one component"), so it falls through to the content-hash tag exactly
+ * as an unset value does. Pure, so the resolution is testable without docker.
+ */
+export function runnerImageRef(
+  opts: { platform?: string; variant?: RunnerVariant } = {},
+): { tag: string; explicit: boolean } {
+  // Each variant has its own override: FOLDRUN_RUNNER_IMAGE names the full
+  // image as it always has, FOLDRUN_RUNNER_SLIM_IMAGE the slim one.
+  const set = opts.variant === "slim" ? process.env.FOLDRUN_RUNNER_SLIM_IMAGE : process.env.FOLDRUN_RUNNER_IMAGE;
+  if (set) return { tag: set, explicit: true };
   const arch = opts.platform ? `-${opts.platform.split("/").pop()}` : "";
-  const tag = process.env.FOLDRUN_RUNNER_IMAGE ?? runnerImageTag() + arch;
+  return { tag: runnerImageTag(opts.variant) + arch, explicit: false };
+}
+
+export function ensureRunnerImage(
+  opts: { platform?: string; variant?: RunnerVariant } = {},
+): { tag: string; log: string[] } {
+  const { tag, explicit } = runnerImageRef(opts);
   const log: string[] = [];
-  if (process.env.FOLDRUN_RUNNER_IMAGE) return { tag, log };
+  if (explicit) return { tag, log };
 
   const have = spawnSync(cli(), ["image", "inspect", tag], { stdio: "ignore" });
   if (have.status === 0) return { tag, log };
@@ -650,10 +994,23 @@ export function ensureRunnerImage(opts: { platform?: string } = {}): { tag: stri
     fs.writeFileSync(path.join(build, "entry.sh"), ENTRY);
     fs.writeFileSync(path.join(build, "Dockerfile"), DOCKERFILE);
     log.push(`building runner image ${tag} (first run only)`);
-    const args = ["build", ...(opts.platform ? ["--platform", opts.platform] : []), "-t", tag, build];
+    const args = [
+      "build",
+      ...(opts.platform ? ["--platform", opts.platform] : []),
+      "--target",
+      opts.variant ?? "full",
+      "-t",
+      tag,
+      build,
+    ];
     const out = spawnSync(cli(), args, { encoding: "utf8" });
     if (out.status !== 0) {
-      throw new Error(`runner image build failed:\n${(out.stderr || out.stdout).slice(-2000)}`);
+      const full = `${out.stdout ?? ""}\n${out.stderr ?? ""}`;
+      // The whole log beside the summary, for a person on the build machine:
+      // the error names the file; the summary is what CI shows.
+      const logFile = path.join(os.tmpdir(), "foldrun-runner-build.log");
+      try { fs.writeFileSync(logFile, full); } catch { /* the summary still says what failed */ }
+      throw new Error(`runner image build failed (full log: ${logFile}):\n${buildFailureSummary(full)}`);
     }
     return { tag, log };
   } finally {
@@ -661,11 +1018,43 @@ export function ensureRunnerImage(opts: { platform?: string } = {}): { tag: stri
   }
 }
 
+/**
+ * What a failed runner build's error says: the lines that name the failure,
+ * then the end of the log. Only the last 2000 characters used to survive,
+ * and BuildKit ends a failed RUN by echoing the instruction — the engines
+ * probe is a long one — so "chrome missing" scrolled out of the very error
+ * that existed to say it. Every engine line the DOCKERFILE prints starts
+ * "runner image:" (the retries, the giving up, the MISSING ENGINES line);
+ * those are kept, from anywhere in the log, with BuildKit's "#12 3.456 "
+ * prefix taken off, and so are BuildKit's own ERROR lines (each cut short:
+ * they quote the whole instruction). Pure, so it is tested on fixtures.
+ */
+export function buildFailureSummary(log: string, opts: { tail?: number; maxLines?: number } = {}): string {
+  const tail = opts.tail ?? 1500;
+  const maxLines = opts.maxLines ?? 40;
+  const seen = new Set<string>();
+  const key: string[] = [];
+  for (const raw of log.split("\n")) {
+    const line = raw.replace(/^#\d+ \d+(\.\d+)? /, "").trim();
+    if (!/^runner image:|^ERROR\b|^error:/i.test(line) && !/did not complete successfully/.test(line)) continue;
+    const cut = line.length > 300 ? line.slice(0, 300) + " …" : line;
+    if (seen.has(cut)) continue;
+    seen.add(cut);
+    key.push(cut);
+  }
+  // The ones that say what is missing first: a reader stops at the top.
+  key.sort((a, b) => Number(/MISSING ENGINES/.test(b)) - Number(/MISSING ENGINES/.test(a)));
+  const head = key.length
+    ? key.slice(0, maxLines).map((l) => `  ${l}`).join("\n") + (key.length > maxLines ? `\n  … ${key.length - maxLines} more` : "")
+    : "  (no engine or ERROR line in the log)";
+  return `${head}\n--- the last ${tail} characters of the build log ---\n${log.slice(-tail)}`;
+}
+
 // ---------- running one step ----------
 
 export function parseDriverLine(
   line: string,
-): { e: "event"; type: "text" | "tool" | "info" | "error"; text: string; call?: string; ms?: number; err?: boolean } | { e: "done" } & ContainerStepOutcome | null {
+): { e: "event"; type: "text" | "tool" | "info" | "error"; text: string; call?: string; ms?: number; err?: boolean; operator?: OperatorEvent; subagent?: string; check?: boolean } | { e: "done" } & ContainerStepOutcome | null {
   const trimmed = line.trim();
   if (!trimmed.startsWith("{")) return null;
   try {
@@ -678,6 +1067,9 @@ export function parseDriverLine(
         ...(typeof parsed.call === "string" ? { call: parsed.call } : {}),
         ...(typeof parsed.ms === "number" ? { ms: parsed.ms } : {}),
         ...(parsed.err === true ? { err: true } : {}),
+        ...(isOperatorEvent(parsed.operator) ? { operator: parsed.operator } : {}),
+        ...(typeof parsed.subagent === "string" && /^[a-z0-9-]{1,64}$/.test(parsed.subagent) ? { subagent: parsed.subagent } : {}),
+        ...(parsed.check === true ? { check: true } : {}),
       };
     }
     if (parsed.e === "done") {
@@ -688,6 +1080,8 @@ export function parseDriverLine(
         conclusion: typeof parsed.conclusion === "string" ? parsed.conclusion : null,
         ...("data" in parsed ? { data: parsed.data } : {}),
         costUsd: typeof parsed.costUsd === "number" ? parsed.costUsd : null,
+        ...(typeof parsed.turnsCostUsd === "number" ? { turnsCostUsd: parsed.turnsCostUsd } : {}),
+        ...(parseBrowserPod(parsed.browserPod) ? { browserPod: parseBrowserPod(parsed.browserPod)! } : {}),
         usage:
           parsed.usage &&
           typeof parsed.usage.inputTokens === "number" &&
@@ -913,8 +1307,18 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
     const wsIn = path.join(staging, "workspace");
     fs.cpSync(args.workspaceRoot, wsIn, {
       recursive: true,
+      // Times too: a verify that asks "was this written in the last hour?"
+      // is asking about the step, and a copy stamped "now" answers yes for a
+      // file untouched since last week (see mtimeManifest).
+      preserveTimestamps: true,
       filter: (src) => !isPlatformPath(path.relative(args.workspaceRoot, src)),
     });
+    // A test run: what its earlier steps wrote, over the real files (the
+    // copy is the baseline too, so only this step's own writes come back).
+    if (args.divert) {
+      const laid = overlayTestWrites(wsIn, args.divert.to);
+      if (laid.length) args.emit("info", `test: this step sees ${laid.length} file${laid.length === 1 ? "" : "s"} earlier steps of this run wrote`);
+    }
     const libIn = path.join(staging, "library");
     if (args.galleryRoot && fs.existsSync(args.galleryRoot)) fs.cpSync(args.galleryRoot, libIn, { recursive: true });
     if (fs.existsSync(args.libraryRoot)) fs.cpSync(args.libraryRoot, libIn, { recursive: true });
@@ -960,14 +1364,26 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
     // host itself stays reachable, which is the one door this needs.
     flags.push("--add-host", "host.docker.internal:host-gateway");
 
-    // The dependency cache: this tenant's built venvs and npm prefixes,
-    // mounted where prepareRuntime already looks. Created host-side rather
-    // than left to the daemon so it belongs to the platform user; the
-    // entrypoint hands the mount point itself to the agent user.
-    const cacheDir = runtimeCacheDir(args.tenant);
-    if (cacheDir) {
-      fs.mkdirSync(cacheDir, { recursive: true });
-      flags.push("-v", `${cacheDir}:${RUNTIME_CACHE}`);
+    // The dependency cache: this tenant's built venvs and npm prefixes, in a
+    // per-tenant Docker named volume mounted where prepareRuntime already looks.
+    // Not a host path — the daemon on the far end of the socket cannot resolve
+    // the platform's FOLDRUN_DATA (runtimeCacheMount explains).
+    const cacheMount = runtimeCacheMount(args.tenant);
+    if (cacheMount) {
+      // Create the volume WITH labels first: `docker create -v` auto-creates it
+      // but cannot label it, and an unlabelled volume is unfindable and
+      // unprunable later. Idempotent — a no-op when it already exists. The
+      // segment is the one runtimeCacheMount already validated, so the
+      // assertions below cannot fire when cacheMount is non-null.
+      const seg = safeTenantSegment(args.tenant!)!;
+      const vol = spawnSync(cli(), [
+        "volume", "create",
+        "--label", "foldrun.io/kind=runtime-cache",
+        "--label", `foldrun.io/tenant=${seg}`,
+        cacheMount.source,
+      ], { encoding: "utf8" });
+      if (vol.status !== 0) throw new Error(`docker volume create failed:\n${vol.stderr}`);
+      flags.push("-v", `${cacheMount.source}:${cacheMount.target}`);
     }
 
     // The rent clock starts here: staging the workspace is host work, but