@foldrun/core 0.3.0 → 0.5.0

package/dist/src/run-container.js

@@ -23,9 +23,11 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import { isPlatformPath } from "./store.js";
+import { divertedSummary, isDivertedPath } from "./test-mode.js";
 import { isFileValue, fileContent } from "./secrets.js";
 import { safeTenantSegment } from "./runtime.js";
-import { dataRoot } from "./paths.js";
+import { isOperatorEvent } from "./operator.js";
+import { parseBrowserPod } from "./browser-pod.js";
 /**
  * The one place the timing line is worded, so the docker and k8s traces
  * read the same and a cold-start regression is greppable across both.
@@ -123,7 +125,69 @@ export function hashTree(dir) {
         walk(dir);
     return out;
 }
-export function applyContainerChanges(hostWs, containerWs, baseline) {
+/**
+ * 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) {
+    const out = {};
+    const walk = (d) => {
+        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) => crypto.createHash("sha256").update(b).digest("hex");
+/**
+ * Both sides changed a file the step was handed. When each is the handed-in
+ * content with lines added on the end — a ledger, history.md, a .jsonl — the
+ * answer is the base, then the host's additions, then the step's. Only the
+ * base's hash may be known, so the base is found as the longest shared
+ * leading run of whole lines whose hash matches. Anything else is null: a
+ * real conflict, which the caller must not settle by dropping one side.
+ */
+export function mergeAppends(was, host, next) {
+    // Both sides created the same new file: no shared base to append to, and
+    // joining two JSON documents is corruption, not a merge.
+    if (was === null)
+        return null;
+    const h = host.toString("utf8");
+    const n = next.toString("utf8");
+    let common = 0;
+    const max = Math.min(h.length, n.length);
+    while (common < max && h.charCodeAt(common) === n.charCodeAt(common))
+        common++;
+    for (let end = common; end >= 0; end--) {
+        if (end > 0 && h[end - 1] !== "\n")
+            continue;
+        const prefix = h.slice(0, end);
+        const matches = typeof was === "string" ? sha(Buffer.from(prefix, "utf8")) === was : Buffer.from(prefix, "utf8").equals(was);
+        if (!matches)
+            continue;
+        const hostAdded = h.slice(end);
+        const stepAdded = n.slice(end);
+        const joined = hostAdded && !hostAdded.endsWith("\n") ? hostAdded + "\n" : hostAdded;
+        return Buffer.from(prefix + joined + stepAdded, "utf8");
+    }
+    return null;
+}
+export function applyContainerChanges(hostWs, containerWs, baseline, note, divert) {
     const applied = [];
     const walk = (dir) => {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -144,22 +208,61 @@ export function applyContainerChanges(hostWs, containerWs, baseline) {
             }
             if (!allowedBack(rel))
                 continue;
-            const next = fs.readFileSync(abs);
-            // Untouched by this step: whatever the host says now is more current
-            // than what we handed in, including a change made while it ran.
+            let next = fs.readFileSync(abs);
+            // What the step was handed: its bytes (a staging dir) or its hash.
+            // null when the file did not exist then; undefined when no baseline.
+            let was;
             if (typeof baseline === "string") {
-                const was = path.join(baseline, rel);
-                if (fs.existsSync(was) && fs.readFileSync(was).equals(next))
-                    continue;
+                const p = path.join(baseline, rel);
+                was = fs.existsSync(p) ? fs.readFileSync(p) : null;
             }
             else if (baseline) {
-                const was = baseline[rel.replaceAll("\\", "/")];
-                if (was && was === crypto.createHash("sha256").update(next).digest("hex"))
-                    continue;
+                was = baseline[rel.replaceAll("\\", "/")] ?? null;
             }
+            const same = (b) => was === null || was === undefined ? false : typeof was === "string" ? sha(b) === was : b.equals(was);
+            // Untouched by this step: whatever the host says now is more current
+            // than what we handed in, including a change made while it ran.
+            if (same(next))
+                continue;
             const target = path.join(hostWs, rel);
-            if (fs.existsSync(target) && fs.readFileSync(target).equals(next))
+            const hostNow = fs.existsSync(target) ? fs.readFileSync(target) : null;
+            if (hostNow && hostNow.equals(next))
                 continue;
+            // The host moved too since the step was handed its copy — another run
+            // or a person wrote it. Writing the step's copy over it erased the
+            // other run's ledger rows on 2026-09-14. Merge appends; keep both
+            // sides of anything else.
+            const hostMoved = was !== undefined && hostNow !== null && !same(hostNow);
+            if (hostMoved) {
+                const merged = mergeAppends(was ?? null, hostNow, next);
+                if (merged) {
+                    next = merged;
+                }
+                else {
+                    const ext = path.extname(rel);
+                    const stem = rel.slice(0, rel.length - ext.length);
+                    const conflictRel = `${stem}.conflict-${Date.now().toString(36)}${ext}`;
+                    const conflictAbs = path.join(hostWs, conflictRel);
+                    fs.mkdirSync(path.dirname(conflictAbs), { recursive: true });
+                    fs.writeFileSync(conflictAbs, next);
+                    applied.push(conflictRel);
+                    note?.(`write-back conflict on ${rel.replaceAll("\\", "/")}: it changed on the workspace while this step ran, ` +
+                        `and not only by appending — kept the workspace's version; this step's version is ${conflictRel.replaceAll("\\", "/")}`);
+                    continue;
+                }
+            }
+            // A test run's state/ and storage/ writes land under the run, not on
+            // the workspace: the step ran against the real files and its output
+            // is kept where a person can read it, but the next real run starts
+            // from state a test never touched. Decided after the merge so the
+            // diverted copy is what WOULD have been written, conflicts included.
+            if (divert && isDivertedPath(rel)) {
+                const aside = path.join(divert.to, rel);
+                fs.mkdirSync(path.dirname(aside), { recursive: true });
+                fs.writeFileSync(aside, next);
+                divert.note(rel.replaceAll("\\", "/"), divertedSummary(rel.replaceAll("\\", "/"), hostNow, next));
+                continue;
+            }
             fs.mkdirSync(path.dirname(target), { recursive: true });
             fs.writeFileSync(target, next);
             applied.push(rel);
@@ -181,27 +284,54 @@ export function applyContainerChanges(hostWs, containerWs, baseline) {
  */
 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.
+ *
+ * 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.
  *
- * 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.
+ * 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).
  *
- * 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.
+ * 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) {
+export function runtimeCacheMount(tenant) {
     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 ----------
 const DRIVER = `// The runner container's entrypoint. Reads one step, executes it with the
@@ -259,9 +389,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
@@ -283,12 +415,16 @@ 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
-  // buildApiTools gets an already-resolved environment. (verify: needs no
-  // separate env either — the container's own environment already carries
-  // the declared secrets, which is why executeStep gets verifyEnv: {}.)
+  // buildApiTools gets an already-resolved environment. verify: gets the
+  // container's own environment, whole: it is the boundary, assembled on
+  // the host from an allowlist, and the declared secrets are in it.
   const api = buildApiTools("", input.apis, undefined, { env, missing: [] });
   const script = buildScriptTools(
     agentDir,
@@ -310,6 +446,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,
@@ -328,15 +469,27 @@ 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,
+    budgetNote: input.budgetNote,
     price: input.price,
     verify: input.verify,
-    verifyEnv: {},
+    verifyEnv: env,
     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) } } : {}),
     // 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,
@@ -351,6 +504,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) {
@@ -369,30 +523,227 @@ try {
 // 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 foldrun-core.tgz driver.mjs entry.sh ./
+RUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\
+ && npm cache clean --force >/dev/null 2>&1 \\
+ && mkdir -p /workspace /library /opt/runner/job ${RUNTIME_CACHE} ${SHARED_RUNTIMES} \\
+ && chown -R agent:agent /workspace /library /opt/runner /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
+
+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
 chown -R agent:agent /workspace /library /opt/runner/job
@@ -422,7 +773,7 @@ function corePackageDir() {
     }
     throw new Error("could not locate @foldrun/core's package root");
 }
-export function runnerImageTag() {
+export function runnerImageTag(variant = "full") {
     // 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.
@@ -435,17 +786,42 @@ export function runnerImageTag() {
                 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" : ""}`;
 }
 /**
  * Build the runner image if this exact (core version, driver, dockerfile)
  * has not been built before. `npm pack` of the installed core, so the image
  * runs the same bytes the server does.
  */
-export function ensureRunnerImage() {
-    const tag = process.env.FOLDRUN_RUNNER_IMAGE ?? runnerImageTag();
+/**
+ * `platform`: build for another architecture — "linux/arm64" on the amd64
+ * box, through QEMU — and name the result with the arch appended so it never
+ * shadows the native image in the daemon. Only the publisher asks for this;
+ * a step always runs the native image. Needs binfmt registered on the host
+ * (tonistiigi/binfmt); the publisher does that itself, every time, because
+ * the registration does not survive a reboot.
+ */
+/**
+ * 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 = {}) {
+    // 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()}` : "";
+    return { tag: runnerImageTag(opts.variant) + arch, explicit: false };
+}
+export function ensureRunnerImage(opts = {}) {
+    const { tag, explicit } = runnerImageRef(opts);
     const log = [];
-    if (process.env.FOLDRUN_RUNNER_IMAGE)
+    if (explicit)
         return { tag, log };
     const have = spawnSync(cli(), ["image", "inspect", tag], { stdio: "ignore" });
     if (have.status === 0)
@@ -463,9 +839,26 @@ export function ensureRunnerImage() {
         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 out = spawnSync(cli(), ["build", "-t", tag, build], { encoding: "utf8" });
+        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 };
     }
@@ -473,6 +866,39 @@ export function ensureRunnerImage() {
         fs.rmSync(build, { recursive: true, force: true });
     }
 }
+/**
+ * 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, opts = {}) {
+    const tail = opts.tail ?? 1500;
+    const maxLines = opts.maxLines ?? 40;
+    const seen = new Set();
+    const key = [];
+    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) {
     const trimmed = line.trim();
@@ -488,6 +914,9 @@ export function parseDriverLine(line) {
                 ...(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") {
@@ -498,6 +927,8 @@ export function parseDriverLine(line) {
                 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" &&
                     typeof parsed.usage.outputTokens === "number"
@@ -538,6 +969,44 @@ function ensureRunNetwork() {
     }
     return RUN_NETWORK;
 }
+/**
+ * What crosses into the container as its environment, and how.
+ *
+ * A docker --env-file is one `KEY=value` per line and cannot carry a
+ * newline. @file secrets are multi-line by nature (a PEM key, a cert), so
+ * they are staged as files NOW, into the copied-in workspace, and the env
+ * carries the container path — the one place a path is stable across the
+ * boundary. A plain secret whose value happens to hold a newline gets the
+ * same treatment, and the trace says so: it used to be dropped from the
+ * env file without a word, and the step failed later, elsewhere, on a
+ * variable that read as unset. Everything else goes through the env file.
+ */
+export function stageContainerEnv(env, wsIn, agentRel, emit) {
+    const containerEnv = {};
+    const stage = (k, content) => {
+        const rel = path.join(agentRel, ".secret-files", k.toLowerCase());
+        const abs = path.join(wsIn, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(abs, content, { mode: 0o600 });
+        return `/workspace/${rel.replaceAll("\\", "/")}`;
+    };
+    for (const [k, v] of Object.entries(env)) {
+        if (typeof v !== "string")
+            continue;
+        if (isFileValue(v)) {
+            containerEnv[k] = stage(k, fileContent(v));
+        }
+        else if (/[\r\n]/.test(v)) {
+            containerEnv[k] = stage(k, v);
+            emit("info", `${k} holds a line break and cannot cross as an environment variable — ` +
+                `passed as a file instead; $${k} is its path in the sandbox`);
+        }
+        else {
+            containerEnv[k] = v;
+        }
+    }
+    return containerEnv;
+}
 /** The limits a size class reserves. Large is the install's configured
  *  limits unchanged, so existing installs bill and behave identically;
  *  small defaults to a quarter-ish slice and is env-tunable. */
@@ -625,9 +1094,15 @@ export async function runStepInContainer(args) {
         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)),
         });
         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 });
         else
@@ -635,28 +1110,7 @@ export async function runStepInContainer(args) {
         const jobIn = path.join(staging, "job");
         fs.mkdirSync(jobIn);
         fs.writeFileSync(path.join(jobIn, "input.json"), JSON.stringify(args.input, null, 2));
-        // @file secrets are multi-line (a PEM key, a cert), and a docker
-        // --env-file cannot carry a newline. So they are staged as files *now*,
-        // into the copied-in workspace, and the env carries the container path —
-        // the one place a path is stable across the boundary. Everything else
-        // goes through the env file. (Without this the key silently vanished:
-        // the old filter dropped any value with a newline, and ssh got an empty
-        // -i path.)
-        const containerEnv = {};
-        for (const [k, v] of Object.entries(args.env)) {
-            if (typeof v !== "string")
-                continue;
-            if (isFileValue(v)) {
-                const rel = path.join(args.input.agentRel, ".secret-files", k.toLowerCase());
-                const abs = path.join(wsIn, rel);
-                fs.mkdirSync(path.dirname(abs), { recursive: true, mode: 0o700 });
-                fs.writeFileSync(abs, fileContent(v), { mode: 0o600 });
-                containerEnv[k] = `/workspace/${rel.replaceAll("\\", "/")}`;
-            }
-            else if (!v.includes("\n")) {
-                containerEnv[k] = v;
-            }
-        }
+        const containerEnv = stageContainerEnv(args.env, wsIn, args.input.agentRel, args.emit);
         const envFile = path.join(staging, "env");
         fs.writeFileSync(envFile, Object.entries(containerEnv).map(([k, v]) => `${k}=${v}`).join("\n"), { mode: 0o600 });
         const flags = [
@@ -685,14 +1139,27 @@ export async function runStepInContainer(args) {
         // Docker Desktop. The run bridge has inter-container traffic off; the
         // 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
         // from `create` to `rm` the sandbox is a resource the platform pays for.
@@ -770,7 +1237,7 @@ export async function runStepInContainer(args) {
         fs.mkdirSync(wsOut);
         const back = spawnSync(cli(), ["cp", `${containerId}:/workspace/.`, wsOut], { encoding: "utf8" });
         if (back.status === 0) {
-            applyContainerChanges(args.workspaceRoot, wsOut, wsIn);
+            applyContainerChanges(args.workspaceRoot, wsOut, wsIn, (m) => args.emit("error", m), args.divert);
         }
         else {
             args.emit("error", `copy-out failed — the step's file changes were lost:\n${back.stderr.slice(0, 500)}`);