@foldrun/core 0.3.0 → 0.4.0

package/dist/src/provider-health.d.ts

@@ -0,0 +1,55 @@
+import { type ProviderSpec } from "./store.ts";
+export type HealthVerdict = "ok" | "credential" | "not-found" | "busy" | "unreachable" | "provider-error";
+export interface ProviderCheck {
+    /** How this provider is written in the file: its preset name, or its host. */
+    provider: string;
+    /** The model id actually asked for — what a run would send. */
+    model: string;
+    verdict: HealthVerdict;
+    ok: boolean;
+    status: number | null;
+    ms: number;
+    /** One sentence a person can act on, in the provider's own words where
+     *  they said anything useful. */
+    detail: string;
+}
+/**
+ * One request at the provider, in the wire format it speaks, asking for a
+ * single token. Never throws: an unreachable host is a verdict, not an
+ * exception, because this runs on a tick.
+ */
+export declare function checkProvider(tenant: string, workspace: string | null, spec: ProviderSpec, model: string): Promise<ProviderCheck>;
+/** A provider block in use, and where it is declared — because "which file
+ *  do I edit" is the next question after "this key is dead". */
+export interface ProviderInUse {
+    spec: ProviderSpec;
+    /** The workspace whose vault resolves this block's secrets. Null for the
+     *  account's own block, which resolves against the account vault. */
+    workspace: string | null;
+    /** Human-readable origin: "account", "rank-desk", "rank-desk/writer". */
+    declaredIn: string;
+    /** The model id a run would send for the cheapest tier, which is what a
+     *  health check should spend. */
+    model: string;
+}
+/**
+ * Every distinct provider block this account would actually use, read from
+ * the same three places a run reads them: the account, each workspace, each
+ * agent.
+ *
+ * Deduplicated by endpoint and token, because ten agents sharing one gateway
+ * are one credential and checking it ten times spends ten times as much to
+ * learn the same fact. The origin recorded is the first one seen, which is
+ * the broadest — an account block covers everything under it.
+ */
+export declare function providersInUse(tenant: string): ProviderInUse[];
+/**
+ * Check every provider this account uses, one at a time.
+ *
+ * Serial on purpose: this is housekeeping on a tick, the whole point is that
+ * it is cheap, and firing twelve model requests at once to save eight
+ * seconds nobody is waiting for would be a strange trade.
+ */
+export declare function checkAccountProviders(tenant: string): Promise<(ProviderCheck & {
+    declaredIn: string;
+})[]>;

package/dist/src/provider-health.js

@@ -0,0 +1,232 @@
+// Is the key still good?
+//
+// A customer's own model key can be revoked, expire, run out of credit or
+// have its base URL moved, and today the platform finds out the way the
+// customer does: a desk fails at five in the morning. Twenty-seven of the
+// thirty provider presets have never had an agent run through them from
+// this runtime at all, so "it worked when we set it up" is doing a lot of
+// work in that sentence.
+//
+// This is deliberately NOT the tool-loop probe next door. `foldrun probe`
+// asks "can this model drive an agent", which is a question about a model
+// and is asked once. This asks "does this endpoint still take our key",
+// which is a question about a credential and has to be asked repeatedly —
+// so it has to be cheap. One request, one token of output, no SDK, no tool
+// loop, no agent. A fraction of a cent, and it answers the thing that
+// actually breaks.
+//
+// It reads the same provider block a run reads, resolved the same way, so a
+// pass here means a run would reach the same place with the same key.
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { getSecret } from "./secrets.js";
+import { noteSecretUse, healthKey } from "./secret-health.js";
+import { accountDir, workspaceDir, listWorkspaces, listAgents, parseProvider } from "./store.js";
+/** How long to wait. A provider slower than this is not one a step should
+ *  be waiting on either, and the check must never hold a tick. */
+const TIMEOUT_MS = 15_000;
+/** What each status means for a credential, and what a person does about
+ *  it. Kept as a table because the mapping IS the feature: "401" tells you
+ *  nothing you can act on, "the key is no longer accepted" tells you
+ *  everything. */
+function verdictFor(status) {
+    if (status >= 200 && status < 300)
+        return { verdict: "ok", detail: "the key was accepted and the model answered" };
+    if (status === 401 || status === 403) {
+        return { verdict: "credential", detail: "the key is no longer accepted — revoked, rotated, or wrong for this endpoint" };
+    }
+    if (status === 402)
+        return { verdict: "credential", detail: "the account behind this key is out of credit" };
+    if (status === 404) {
+        return { verdict: "not-found", detail: "the endpoint or the model id does not exist there — check base_url and models:" };
+    }
+    if (status === 429) {
+        // Not a health problem. A busy provider is a provider that is working,
+        // and reporting it as broken would train people to ignore the alert.
+        return { verdict: "busy", detail: "rate limited right now — the key is fine" };
+    }
+    if (status >= 500)
+        return { verdict: "provider-error", detail: "the provider is failing at its end" };
+    return { verdict: "provider-error", detail: `unexpected HTTP ${status}` };
+}
+/** `${SECRET}` in a token or header, filled from this account's vault. */
+function resolve(tenant, workspace, raw) {
+    return raw.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => {
+        const hit = getSecret(tenant, name, workspace ?? undefined);
+        return hit ? hit.value : whole;
+    });
+}
+/**
+ * One request at the provider, in the wire format it speaks, asking for a
+ * single token. Never throws: an unreachable host is a verdict, not an
+ * exception, because this runs on a tick.
+ */
+export async function checkProvider(tenant, workspace, spec, model) {
+    const label = spec.name || (() => {
+        try {
+            return new URL(spec.baseUrl).host;
+        }
+        catch {
+            return spec.baseUrl || "provider";
+        }
+    })();
+    const began = Date.now();
+    const fail = (verdict, detail, status = null) => ({
+        provider: label,
+        model,
+        verdict,
+        ok: false,
+        status,
+        ms: Date.now() - began,
+        detail,
+    });
+    const token = resolve(tenant, workspace, spec.token);
+    if (!token || token.includes("${")) {
+        return fail("credential", `the secret named in provider.token is not in this account's vault (${spec.token})`);
+    }
+    if (!spec.baseUrl)
+        return fail("unreachable", "this provider block has no base_url");
+    // The three wire formats, each asking for the smallest possible answer.
+    const base = spec.baseUrl.replace(/\/+$/, "");
+    const anthropic = spec.format === "anthropic";
+    const url = anthropic
+        ? `${base}/v1/messages`
+        : spec.format === "responses"
+            ? `${base}/responses`
+            : `${base}/chat/completions`;
+    const body = anthropic
+        ? { model, max_tokens: 1, messages: [{ role: "user", content: "hi" }] }
+        : spec.format === "responses"
+            ? { model, max_output_tokens: 16, input: "hi" }
+            : { model, max_tokens: 1, messages: [{ role: "user", content: "hi" }] };
+    const headers = { "content-type": "application/json" };
+    // An Anthropic-format endpoint takes the key in whichever header its
+    // `auth:` says; everything else is a bearer token.
+    if (anthropic && spec.auth === "x-api-key") {
+        headers["x-api-key"] = token;
+        headers["anthropic-version"] = "2023-06-01";
+    }
+    else {
+        headers.authorization = `Bearer ${token}`;
+        if (anthropic)
+            headers["anthropic-version"] = "2023-06-01";
+    }
+    for (const [k, v] of Object.entries(spec.headers ?? {}))
+        headers[k.toLowerCase()] = resolve(tenant, workspace, v);
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        const { verdict, detail } = verdictFor(res.status);
+        // The check is itself a use of the credential, and the most informative
+        // one there is: it was made for exactly this purpose.
+        const named = spec.token.match(/^\$\{([A-Z][A-Z0-9_]*)\}$/)?.[1];
+        if (named) {
+            let host = spec.baseUrl;
+            try {
+                host = new URL(spec.baseUrl).host;
+            }
+            catch {
+                // an unparseable base_url is its own problem, reported above
+            }
+            const hit = getSecret(tenant, named, workspace ?? undefined);
+            noteSecretUse(tenant, healthKey(named, hit?.scope === "workspace" ? "workspace" : "account", workspace), { host, status: res.status });
+        }
+        // The provider's own words when it refused. They are the difference
+        // between "fix your key" and "fix your model id", and they are only
+        // ever in the body.
+        let said = "";
+        if (!res.ok) {
+            said = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 300);
+        }
+        return {
+            provider: label,
+            model,
+            verdict,
+            // Busy counts as healthy: the key worked, the provider is simply full.
+            ok: verdict === "ok" || verdict === "busy",
+            status: res.status,
+            ms: Date.now() - began,
+            detail: said ? `${detail} — ${said}` : detail,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return fail("unreachable", /timeout|aborted/i.test(message) ? `no answer within ${TIMEOUT_MS / 1000}s` : message);
+    }
+}
+/** The cheapest tier's id for a provider block: what it calls `fast`, or
+ *  our own fast model when it remaps nothing. */
+function cheapestModel(spec) {
+    return spec.models.fast || spec.models.default || spec.models.max || "claude-haiku-4-5-20251001";
+}
+function frontmatterOf(file) {
+    try {
+        return (matter(fs.readFileSync(file, "utf8")).data ?? {});
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Every distinct provider block this account would actually use, read from
+ * the same three places a run reads them: the account, each workspace, each
+ * agent.
+ *
+ * Deduplicated by endpoint and token, because ten agents sharing one gateway
+ * are one credential and checking it ten times spends ten times as much to
+ * learn the same fact. The origin recorded is the first one seen, which is
+ * the broadest — an account block covers everything under it.
+ */
+export function providersInUse(tenant) {
+    const out = [];
+    const seen = new Set();
+    const add = (raw, workspace, declaredIn) => {
+        const spec = parseProvider(raw);
+        if (!spec || !spec.baseUrl)
+            return;
+        // The token is part of the identity: the same gateway with two different
+        // keys is two credentials, and either can die on its own.
+        const key = `${workspace ?? ""}|${spec.baseUrl}|${spec.token}|${cheapestModel(spec)}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ spec, workspace, declaredIn, model: cheapestModel(spec) });
+    };
+    add(frontmatterOf(path.join(accountDir(tenant), "AGENTS.md")).provider, null, "account");
+    for (const ws of safeList(() => listWorkspaces(tenant))) {
+        const dir = workspaceDir(tenant, ws.name);
+        add(frontmatterOf(path.join(dir, "AGENTS.md")).provider, ws.name, ws.name);
+        for (const agent of safeList(() => listAgents(tenant, ws.name))) {
+            add(frontmatterOf(path.join(dir, "agents", agent.name, "agent.md")).provider, ws.name, `${ws.name}/${agent.name}`);
+        }
+    }
+    return out;
+}
+function safeList(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Check every provider this account uses, one at a time.
+ *
+ * Serial on purpose: this is housekeeping on a tick, the whole point is that
+ * it is cheap, and firing twelve model requests at once to save eight
+ * seconds nobody is waiting for would be a strange trade.
+ */
+export async function checkAccountProviders(tenant) {
+    const results = [];
+    for (const use of providersInUse(tenant)) {
+        const check = await checkProvider(tenant, use.workspace, use.spec, use.model);
+        results.push({ ...check, declaredIn: use.declaredIn });
+    }
+    return results;
+}

package/dist/src/run-container.d.ts

@@ -33,6 +33,7 @@ export interface ContainerStepInput {
     /** 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;
@@ -40,6 +41,9 @@ export interface ContainerStepInput {
     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;
     /** tools: [search] — the directories to search, as paths INSIDE the
      *  container (/workspace/…, /library/…). */
     search?: SearchRoot[];
@@ -131,7 +135,16 @@ export declare function allowedBack(rel: string): boolean;
  * step changed without the staging copy the first driver held in /tmp.
  */
 export declare function hashTree(dir: string): Record<string, string>;
-export declare function applyContainerChanges(hostWs: string, containerWs: string, baseline?: string | Record<string, string>): string[];
+/**
+ * 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 declare function mergeAppends(was: Buffer | string | null, host: Buffer, next: Buffer): Buffer | null;
+export declare function applyContainerChanges(hostWs: string, containerWs: string, baseline?: string | Record<string, string>, note?: (message: string) => void, divert?: WriteDivert): string[];
 /**
  * Where the driver builds venvs and npm prefixes, as an absolute path *inside*
  * the runner. Fixed, and it has to be: a venv bakes its own absolute path into
@@ -165,7 +178,17 @@ export declare 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 declare function ensureRunnerImage(): {
+/**
+ * `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.
+ */
+export declare function ensureRunnerImage(opts?: {
+    platform?: string;
+}): {
     tag: string;
     log: string[];
 };
@@ -176,12 +199,14 @@ export declare function parseDriverLine(line: string): {
     call?: string;
     ms?: number;
     err?: boolean;
-} | {
+} | ({
     e: "done";
-} & ContainerStepOutcome | null;
+} & ContainerStepOutcome) | null;
 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;
@@ -208,7 +233,35 @@ 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 declare function stageContainerEnv(env: Record<string, string>, wsIn: string, agentRel: string, emit: (type: "info" | "error", text: string) => void): Record<string, string>;
 /** 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. */

package/dist/src/run-container.js

@@ -23,6 +23,7 @@ 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";
@@ -123,7 +124,41 @@ export function hashTree(dir) {
         walk(dir);
     return out;
 }
-export function applyContainerChanges(hostWs, containerWs, baseline) {
+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 +179,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);
@@ -286,9 +360,9 @@ try {
 
   // 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,
@@ -333,10 +407,13 @@ try {
     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,
     // 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,
@@ -442,8 +519,17 @@ export function runnerImageTag() {
  * 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.
+ */
+export function ensureRunnerImage(opts = {}) {
+    const arch = opts.platform ? `-${opts.platform.split("/").pop()}` : "";
+    const tag = process.env.FOLDRUN_RUNNER_IMAGE ?? runnerImageTag() + arch;
     const log = [];
     if (process.env.FOLDRUN_RUNNER_IMAGE)
         return { tag, log };
@@ -463,7 +549,8 @@ 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] : []), "-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)}`);
         }
@@ -538,6 +625,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. */
@@ -628,6 +753,8 @@ export async function runStepInContainer(args) {
             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 +762,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 = [
@@ -770,7 +876,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)}`);