@foldrun/core 0.3.0 → 0.5.0

package/src/run-container.ts

@@ -25,14 +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 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. */
@@ -57,14 +60,24 @@ 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. */
   budgetUsd?: number | null;
+  budgetNote?: string;
   price?: { input: number; output: number } | null;
   verify?: string;
   /** `output: json` — checked inside, where the reply is. */
   output?: "json";
+  /** `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[];
@@ -72,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";
 }
 
 /**
@@ -117,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;
 }
 
 /**
@@ -215,10 +247,72 @@ 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");
+
+/**
+ * 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: Buffer | string | null, host: Buffer, next: Buffer): Buffer | null {
+  // 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: string,
   containerWs: string,
   baseline?: string | Record<string, string>,
+  note?: (message: string) => void,
+  divert?: WriteDivert,
 ): string[] {
   const applied: string[] = [];
   const walk = (dir: string) => {
@@ -237,18 +331,60 @@ export function applyContainerChanges(
         continue;
       }
       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: Buffer = 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: Buffer | string | null | undefined;
       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: Buffer) =>
+        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)) continue;
+      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);
@@ -273,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.
+ *
+ * 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: 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 ----------
@@ -351,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
@@ -375,12 +543,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,
@@ -402,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,
@@ -420,15 +597,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,
@@ -443,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) {
@@ -462,30 +652,232 @@ 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
@@ -516,7 +908,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.
@@ -528,7 +923,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" : ""}`;
 }
 
 /**
@@ -536,10 +931,39 @@ export function runnerImageTag(): string {
  * has not been built before. `npm pack` of the installed core, so the image
  * runs the same bytes the server does.
  */
-export function ensureRunnerImage(): { tag: string; log: string[] } {
-  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: { 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()}` : "";
+  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 };
@@ -556,9 +980,23 @@ export function ensureRunnerImage(): { tag: string; log: string[] } {
     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 };
   } finally {
@@ -566,11 +1004,43 @@ export function ensureRunnerImage(): { tag: string; log: string[] } {
   }
 }
 
+/**
+ * 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 {
@@ -583,6 +1053,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") {
@@ -593,6 +1066,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" &&
@@ -643,6 +1118,8 @@ function ensureRunNetwork(): string {
 export interface RunInContainerArgs {
   workspaceRoot: string;
   libraryRoot: string;
+  /** The platform's gallery, staged under /library BEFORE the account library so the account's copies win. */
+  galleryRoot?: string;
   /** The account this step belongs to — the key for its dependency cache.
    *  Optional so an embedder that has no tenancy simply gets no cache. */
   tenant?: string;
@@ -666,6 +1143,66 @@ export interface RunInContainerArgs {
    *  (consumed 0), and before each output line it applies. The runner
    *  records these on the step, so the next driver knows where to attach. */
   checkpoint?: (ref: string, consumed: number) => void;
+  /** A test run: where state/ and storage/ changes go instead of the
+   *  workspace, and who to tell about each. See test-mode.ts. */
+  divert?: WriteDivert;
+  /** The run is a test run. An isolated executor labels the sandbox so the
+   *  cluster can cut its network down to the egress proxy: a script tool
+   *  calls the network directly, not through the proxy where the test-mode
+   *  policy lives, so without this a test run's script could still send. */
+  test?: boolean;
+}
+
+/** What a test run does with a write it must not apply. */
+export interface WriteDivert {
+  /** The directory the diverted files are written under, by their
+   *  workspace-relative path: runs/<id>/test-writes/. */
+  to: string;
+  note: (rel: string, summary: string) => void;
+}
+
+/**
+ * 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: Record<string, string>,
+  wsIn: string,
+  agentRel: string,
+  emit: (type: "info" | "error", text: string) => void,
+): Record<string, string> {
+  const containerEnv: Record<string, string> = {};
+  const stage = (k: string, content: string) => {
+    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
@@ -756,9 +1293,14 @@ 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)),
     });
     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 fs.mkdirSync(libIn, { recursive: true });
 
@@ -766,26 +1308,7 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
     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: Record<string, string> = {};
-    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(
@@ -821,14 +1344,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
@@ -903,7 +1438,7 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
     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)}`);
     }