@foldrun/core 2.14.2 → 3.0.0

package/dist/src/confine.d.ts

@@ -11,6 +11,9 @@ export interface Roots {
     workspaceRoot: string;
     /** The account library: readable, never writable. */
     libraryRoot: string;
+    /** A person approved this step before it ran (an approval gate): its
+     *  writes to the workspace's configuration and code are allowed. */
+    configWrites?: boolean;
 }
 export declare const isFilesystemTool: (toolName: string) => boolean;
 /**

package/dist/src/confine.js

@@ -29,6 +29,7 @@
 // ordinary deliverable — so the rule names the two directories it applies to.
 import fs from "node:fs";
 import path from "node:path";
+import { refusedBack } from "./copy-back.js";
 /**
  * A path with its symlinks resolved, as far as it exists.
  *
@@ -274,6 +275,19 @@ export function checkPaths(toolName, input, roots) {
                     `concept file instead.`,
             };
         }
+        // Configuration and code are a person's: the same list a sandbox's
+        // copy-back refuses (copy-back.ts, FOL-96), so a step that runs on this
+        // host, with no sandbox between it and the files, is held to the same
+        // rule by its file tools. Its shell is not confined here — isolation is.
+        const asConfig = isWrite && !inLibrary && !roots.configWrites ? refusedBack(within) : null;
+        if (asConfig) {
+            return {
+                ok: false,
+                reason: `${toolName} was denied: "${raw}" is this workspace's ${asConfig === "config" ? "configuration" : "code"}, ` +
+                    `which a run does not change. Say what should change and why in your answer — a person ` +
+                    `applies it (or it becomes a Proposed fix). Your own notes go to outputs/ or workspace/memory/.`,
+            };
+        }
         // Hand the real path back to the tool, so the virtual prefix the prompt
         // advertises is one the agent can actually open — unless the step's
         // `workspace` link already opens it. Then the path is left as written,

package/dist/src/copy-back.d.ts

@@ -0,0 +1,17 @@
+import { type Kind } from "./kinds.ts";
+/** A path a step changed that was not taken back, and why. */
+export interface RefusedPath {
+    path: string;
+    kind: "config" | "code";
+}
+/** The path shapes one kind's files take, inside a workspace. */
+export declare function kindPatterns(kind: Kind): RegExp[];
+/** Whether a step's write to `rel` (workspace-relative) is refused on the way
+ *  back, and as what; null when it is data and may come back. */
+export declare function refusedBack(rel: string): "config" | "code" | null;
+/** The trail's line for a step's refused writes. */
+/** The trail's line for config and code a person-approved step changed and
+ *  that were kept (an approval gate before the step: the person read what
+ *  it would do — the desks' retro applies approved fixes this way). */
+export declare function keptLine(kept: readonly RefusedPath[]): string;
+export declare function refusedLine(refused: readonly RefusedPath[]): string;

package/dist/src/copy-back.js

@@ -0,0 +1,74 @@
+// What a run's sandbox may hand back to the workspace (FOL-96, 27 Oct 2026).
+//
+// A step's file changes come back from its sandbox (run-container.ts
+// applyContainerChanges — the docker and the k8s runner both), and until now
+// everything came back that was not platform-owned, knowledge or hooks. So a
+// step steered by a page it read could rewrite AGENTS.md, an agent.md or a
+// flow — its own tools:, network:, a provider: block, a new scheduled flow —
+// and every later run, the next step of the same run included, ran on it.
+//
+// Configuration and code are a person's to change. A step that wants a
+// change proposes it (Proposed fixes, the assistant), and a person applies
+// it; a step that writes one anyway has the write refused, and the run's
+// trail names it. What steps legitimately write — state/, memory/, storage/,
+// an agent's own outputs — comes back as before.
+//
+// The list is not written here. It is read off the kinds (kinds.ts), whose
+// every row must say what its files are, so a kind added later is classified
+// the moment it exists — tsc refuses a row without `copyBack`.
+import { KINDS, ALL_KINDS, SUBAGENT_IMPORT_DIRS, WORKSPACE_CONFIG_FILES } from "./kinds.js";
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const NAME = "\u0000";
+/** Where an agent's own folder is — the scope agent-level kinds live under. */
+const AGENT_SCOPE = KINDS.agents.file(NAME).split(NAME)[0]; // "agents/"
+/** The path shapes one kind's files take, inside a workspace. */
+export function kindPatterns(kind) {
+    const meta = KINDS[kind];
+    const file = meta.file(NAME);
+    // An agent's folder is a scope as well as a document: everything else in
+    // it is the agent's working directory. Its document is the one file.
+    if (kind === "agents") {
+        const [head, tail] = file.split(NAME);
+        return [new RegExp(`^${escape(head)}[^/]+${escape(tail)}$`)];
+    }
+    // Every other kind owns its top-level folder — a file document's siblings
+    // (a tool's script beside its .md) and a folder document's contents alike.
+    const root = file.split("/")[0];
+    const out = [new RegExp(`^${escape(root)}/`)];
+    if (meta.scopes.includes("agent"))
+        out.push(new RegExp(`^${escape(AGENT_SCOPE)}[^/]+/${escape(root)}/`));
+    return out;
+}
+const RULES = [
+    ...WORKSPACE_CONFIG_FILES.map((f) => ({ re: new RegExp(`^${escape(f)}$`), kind: "config" })),
+    // Single-file subagents another tool wrote: a deploy imports them as agents.
+    ...[...new Set(SUBAGENT_IMPORT_DIRS.map((d) => d.split("/")[0]))].map((d) => ({ re: new RegExp(`^${escape(d)}/`), kind: "config" })),
+    ...ALL_KINDS.flatMap((k) => {
+        const cls = KINDS[k].copyBack;
+        return cls === "data" ? [] : kindPatterns(k).map((re) => ({ re, kind: cls }));
+    }),
+];
+/** Whether a step's write to `rel` (workspace-relative) is refused on the way
+ *  back, and as what; null when it is data and may come back. */
+export function refusedBack(rel) {
+    const norm = rel.replaceAll("\\", "/").replace(/^\.\//, "");
+    for (const r of RULES)
+        if (r.re.test(norm))
+            return r.kind;
+    return null;
+}
+/** The trail's line for a step's refused writes. */
+/** The trail's line for config and code a person-approved step changed and
+ *  that were kept (an approval gate before the step: the person read what
+ *  it would do — the desks' retro applies approved fixes this way). */
+export function keptLine(kept) {
+    const shown = kept.slice(0, 20).map((r) => `${r.path} (${r.kind})`).join(", ");
+    const more = kept.length > 20 ? ` and ${kept.length - 20} more` : "";
+    return `kept with approval: ${shown}${more} — configuration or code this step changed, kept because a person approved the step before it ran`;
+}
+export function refusedLine(refused) {
+    const shown = refused.slice(0, 20).map((r) => `${r.path} (${r.kind})`).join(", ");
+    const more = refused.length > 20 ? ` and ${refused.length - 20} more` : "";
+    return (`refused path: ${shown}${more} — a step cannot change the workspace's configuration or code; ` +
+        `the workspace keeps its own copy. Propose the change instead (Proposed fixes), and a person applies it.`);
+}

package/dist/src/deploy.d.ts

@@ -1,4 +1,5 @@
 import { type DeployFile } from "./store.ts";
+import { SUBAGENT_IMPORT_DIRS } from "./kinds.ts";
 import { type ScanFinding, type ScanOptions } from "./scan.ts";
 /**
  * Is this path, relative to a workspace root, one `readTree` would carry?
@@ -46,7 +47,7 @@ export interface DeployResult extends DeployPlan {
  * skipped rather than rejected, because a workspace living in a repo alongside
  * other things is the normal case, not an error.
  */
-export declare const SUBAGENT_IMPORT_DIRS: readonly [".agents/agents", ".claude/agents"];
+export { SUBAGENT_IMPORT_DIRS };
 /** Bounds for a reader that only looks at the text (the checks, the
  *  assistant): on 20 Oct 2026 the daily rescan read one desk's 1.2 GB of
  *  state/ into a 2 GB heap and crash-looped the worker. A deploy sets none. */

package/dist/src/deploy.js

@@ -26,6 +26,7 @@ import { libraryTools } from "./library.js";
 import { lintFlow, regexProblem } from "./flow-lint.js";
 import { parseEval } from "./evals.js";
 import { refNames } from "./refs.js";
+import { SUBAGENT_IMPORT_DIRS } from "./kinds.js";
 import matter, { configMatter } from "./matter.js";
 import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.js";
 import { conformanceIssues } from "./okf.js";
@@ -74,12 +75,9 @@ export function isSourcePath(rel) {
  * skipped rather than rejected, because a workspace living in a repo alongside
  * other things is the normal case, not an error.
  */
-// Where single-file subagents authored by other tools are found, in
-// precedence order: the vendor-neutral cross-client location first, then any
-// tool-specific one for pragmatic compatibility. Extend the tail, never the
-// head. Shared by the deploy import (readTree) and the CLI checker so the two
-// agree on what counts as an agent.
-export const SUBAGENT_IMPORT_DIRS = [".agents/agents", ".claude/agents"];
+// Where single-file subagents authored by other tools are found — declared
+// with the kinds (kinds.ts), which the copy-back rule reads too.
+export { SUBAGENT_IMPORT_DIRS };
 /** What agents write as they run, not what anyone authored: state/ and
  *  memory/, the workspace's or one agent's. */
 const DATA_PATH = /^(?:agents\/[^/]+\/)?(?:state|memory)\//;

package/dist/src/frontmatter-fields.js

@@ -116,7 +116,7 @@ const FLOW = [
     { key: "every", type: ["string", "number"], help: "trigger: watch — how often" },
     { key: "path", type: "string", help: "trigger: storage — the prefix under storage/" },
     { key: "filter", type: "object", validated: true, help: "webhook, email, flow or storage trigger: the fields a delivery must have to start a run — e.g. {action: [opened], sender: {type: {not_in: [Bot]}}}" },
-    { key: "idempotency", type: "string", help: "a header name, or body:<field>, that marks a repeat delivery" },
+    { key: "idempotency", type: ["string", "boolean"], help: "a header name, or body:<field>, that marks a repeat delivery; none (or false) to turn off (signature: github defaults to x-github-delivery)" },
     { key: "debounce", type: ["string", "number"], help: "wait for a burst to end" },
     { key: "throttle", type: ["string", "number"], help: "at most one run per window" },
     { key: "sla", type: ["string", "number"], help: "tell someone when a run outlives it" },

package/dist/src/kinds.d.ts

@@ -1,6 +1,12 @@
 /** Where a document can live. Nearest wins at read time. */
 export type Scope = "account" | "workspace" | "agent";
 export type Kind = "agents" | "flows" | "evals" | "tools" | "hooks" | "skills" | "memory" | "knowledge" | "scripts";
+/** How a run's write to a kind's files is treated on the way back. */
+export type CopyBackClass = "config" | "code" | "data";
+/** Workspace files that are configuration without being a kind: the shared
+ *  context and its pre-rename name. */
+export declare const WORKSPACE_CONFIG_FILES: readonly ["AGENTS.md", "project.md"];
+export declare const SUBAGENT_IMPORT_DIRS: readonly [".agents/agents", ".claude/agents"];
 export interface KindMeta {
     kind: Kind;
     /** Singular noun, for buttons and prose. */
@@ -23,6 +29,14 @@ export interface KindMeta {
     hint: string;
     /** Path relative to the scope root. */
     file: (name: string) => string;
+    /**
+     * What a run's sandbox writing one of these means (copy-back.ts):
+     * `config` grants or changes what runs and how, `code` is something a
+     * later step executes — neither is ever taken back from a step, which
+     * proposes the change instead — and `data` is what steps legitimately
+     * write. Required, so a new kind cannot become copy-back-able unnoticed.
+     */
+    copyBack: CopyBackClass;
     /** Starting content. */
     template: (name: string, ctx?: TemplateContext) => string;
 }

package/dist/src/kinds.js

@@ -35,6 +35,15 @@
 // Everything downstream — creation templates, `foldrun init`, the scaffolder,
 // the dashboard's New button — reads this table. Adding a kind means adding a
 // row here and nothing else; that is the point.
+/** Workspace files that are configuration without being a kind: the shared
+ *  context and its pre-rename name. */
+export const WORKSPACE_CONFIG_FILES = ["AGENTS.md", "project.md"];
+// Where single-file subagents authored by other tools are found, in
+// precedence order: the vendor-neutral cross-client location first, then any
+// tool-specific one for pragmatic compatibility. Extend the tail, never the
+// head. Shared by the deploy import (deploy.ts readTree), the CLI checker
+// and the copy-back rule, so all three agree on what counts as an agent.
+export const SUBAGENT_IMPORT_DIRS = [".agents/agents", ".claude/agents"];
 const envName = (name) => name.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
 /**
  * A slug as a starting display label: `house-style` → `House style`.
@@ -50,6 +59,7 @@ const titleCase = (slug) => {
 export const KINDS = {
     agents: {
         kind: "agents",
+        copyBack: "config",
         one: "agent",
         docType: null,
         docKey: null,
@@ -73,6 +83,7 @@ this text is the whole of the agent's instructions.
     },
     evals: {
         kind: "evals",
+        copyBack: "config",
         one: "eval",
         docType: null,
         docKey: null,
@@ -95,6 +106,7 @@ expect:
     },
     flows: {
         kind: "flows",
+        copyBack: "config",
         one: "flow",
         docType: null,
         docKey: null,
@@ -113,6 +125,7 @@ trigger: manual
     },
     tools: {
         kind: "tools",
+        copyBack: "config",
         one: "tool",
         docType: null,
         docKey: null,
@@ -139,6 +152,7 @@ tools: [${name}]
     },
     hooks: {
         kind: "hooks",
+        copyBack: "code",
         one: "hook",
         docType: null,
         docKey: null,
@@ -169,6 +183,7 @@ it reads the event as JSON on stdin and prints one JSON answer —
     // a decision, so the sidebar has no door for it.
     knowledge: {
         kind: "knowledge",
+        copyBack: "data",
         one: "knowledge doc",
         docType: "Reference",
         // OKF's field and OKF's vocabulary — `Reference` is only the starting point.
@@ -190,6 +205,7 @@ The reference content. Agents read this and never rewrite it.
     },
     memory: {
         kind: "memory",
+        copyBack: "data",
         one: "memory",
         docType: "Fact",
         // OKF's field and OKF's vocabulary — `Fact` is only the starting point.
@@ -216,6 +232,7 @@ The fact.
     },
     skills: {
         kind: "skills",
+        copyBack: "config",
         one: "skill",
         docType: null,
         docKey: null,
@@ -235,6 +252,7 @@ Step-by-step instructions. Bundle code in this folder's scripts/ if it needs any
     },
     scripts: {
         kind: "scripts",
+        copyBack: "code",
         one: "script",
         // Code, not a document — no frontmatter to carry either field. A tool
         // file points at it.

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

@@ -3,6 +3,7 @@ import type { PeerInfo } from "./operator.ts";
 import { type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { type ApiSpec, type Effort, type ModelCall } from "./store.ts";
+import { type RefusedPath } from "./copy-back.ts";
 import type { CallIo, EventExtra, ExecUsage } from "./step-exec.ts";
 import type { TokenPrice } from "./catalog.ts";
 import { type RuntimeSpec } from "./runtime.ts";
@@ -19,6 +20,9 @@ import { type BrowserPodOutcome } from "./browser-pod.ts";
  *  secrets in headers, assembled prompt, serializable MCP configs. */
 export interface ContainerStepInput {
     agentRel: string;
+    /** A person approved this step before it ran: its file tools may write
+     *  configuration and code inside the sandbox too (FOL-96). */
+    configWrites?: boolean;
     prompt: string;
     model: string;
     effort?: Effort | null;
@@ -195,6 +199,9 @@ export interface ContainerStepOutcome {
      *  applyContainerChanges returned. An isolated sub-agent's reply names
      *  them to the step that delegated (delegate-tools.ts). */
     applied?: string[];
+    /** What the step changed that was not taken back: configuration and code
+     *  (copy-back.ts). On the step record and in the trail. */
+    refused?: RefusedPath[];
 }
 /**
  * The one place the timing line is worded, so the docker and k8s traces
@@ -229,6 +236,20 @@ 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>;
+/**
+ * Where the host keeps what a sandbox was handed (hashTree), for a driver
+ * that inherits the step: under the run's own folder, which is platform-
+ * owned — never staged into a sandbox, never copied back, erased with the
+ * run (deleteRun). It used to ride into the pod beside the input and be
+ * read back from there, where the step could rewrite it (FOL-96).
+ */
+export declare function handedInPath(workspaceRoot: string, runId: string, ref: string): string | null;
+/** Note what a sandbox was handed, on the host. */
+export declare function writeHandedIn(workspaceRoot: string, runId: string, ref: string, hashes: Record<string, string>): void;
+/** What the host noted a sandbox was handed, or undefined. */
+export declare function readHandedIn(workspaceRoot: string, runId: string, ref: string): Record<string, string> | undefined;
+/** Forget it once the step's copy-out is done. */
+export declare function dropHandedIn(workspaceRoot: string, runId: string, ref: string): void;
 /**
  * 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
@@ -249,7 +270,21 @@ export declare const APPLY_MTIMES_JS: string;
  * 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[];
+export interface ApplyOptions {
+    /** What the host handed back into this sandbox mid-step — a `sandbox: own`
+     *  job's files (delegate-tools.ts), path → sha256 — as the HOST recorded
+     *  it (StepRecord.handedBack). The sandbox's own note of the same is only
+     *  believed where it agrees with this: a step can write that note. */
+    handedBack?: Record<string, string | string[]>;
+    /** Told of every path the step changed that was not taken back because it
+     *  is configuration or code (copy-back.ts). */
+    onRefused?: (refused: RefusedPath) => void;
+    /** A person approved the step before it ran: configuration and code it
+     *  changed come back, each told to onKept instead of refused. */
+    allowConfig?: boolean;
+    onKept?: (kept: RefusedPath) => void;
+}
+export declare function applyContainerChanges(hostWs: string, containerWs: string, baseline?: string | Record<string, string>, note?: (message: string) => void, divert?: WriteDivert, opts?: ApplyOptions): 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
@@ -304,7 +339,7 @@ export declare function runtimeCacheMount(tenant: string | undefined): {
     target: string;
 } | null;
 /** The runner container's entrypoint, as JS text: written into the image as driver.mjs, so it must be plain JS — a TypeScript cast here broke every step on v2026.10.21.5 (tests/run-container.test.ts checks it). */
-export declare const DRIVER = "// The runner container's entrypoint. Reads one step, executes it with the\n// same core the server uses, speaks JSONL on stdout, exits.\nimport fs from \"node:fs\";\nconst input = JSON.parse(fs.readFileSync(\"/opt/runner/job/input.json\", \"utf8\"));\n// Start-up marks (run-container.ts#STARTUP_PHASES): which phase just ended,\n// on the sandbox's clock. A worker that does not know a mark skips the line.\nconst mark = (name) => process.stdout.write(JSON.stringify({ e: \"mark\", name, at: Date.now() }) + \"\\n\");\nmark(\"driver\");\nlet modelSpoke = false;\nconst emit = (type, text, extra) => {\n  // The model's first text or tool call is where start-up ends and the\n  // step's own work begins \u2014 runtime and tool lines before it are set-up.\n  if (!modelSpoke && (type === \"text\" || type === \"tool\")) { modelSpoke = true; mark(\"model\"); }\n  process.stdout.write(JSON.stringify({ e: \"event\", type, text, ...extra }) + \"\\n\");\n};\n// What this sandbox actually touched, read at the last moment from the\n// kernel's own books: cgroup v2 for CPU busy-time and peak memory,\n// /proc/net/dev for bytes on the wire. Every read is best-effort \u2014 gVisor\n// exposes some of these files and not others depending on version, and a\n// metric we cannot read is null, never guessed. Reservation is what is\n// billed; these exist so the reservation can be right-sized.\nfunction readActuals() {\n  // fs from the module's own import \u2014 the driver is ESM, and a require()\n  // here threw on every call, silently nulling every metric it guarded.\n  const read = (p) => { try { return fs.readFileSync(p, \"utf8\"); } catch { return null; } };\n  // Two cgroup dialects: v2 (cpu.stat, microseconds; memory.peak) on a\n  // plain runtime, v1-style controllers under gVisor (cpuacct.usage,\n  // NANOseconds; memory.max_usage_in_bytes) \u2014 probed on the real cluster,\n  // not assumed. Whichever answers wins; both silent means null.\n  const cpuStat = read(\"/sys/fs/cgroup/cpu.stat\");\n  const usage = cpuStat?.match(/^usage_usec (\\d+)/m);\n  const cpuacctNs = usage ? NaN : Number(read(\"/sys/fs/cgroup/cpuacct/cpuacct.usage\")?.trim());\n  // Time the CPU cap held the sandbox back: v2's throttled_usec in the same\n  // cpu.stat, v1's throttled_time (nanoseconds) under gVisor. Large against\n  // busy time means the step wanted more cores than its class gives.\n  const throttledUs = cpuStat?.match(/^throttled_usec (\\d+)/m);\n  const throttledNs = throttledUs ? null : read(\"/sys/fs/cgroup/cpu/cpu.stat\")?.match(/^throttled_time (\\d+)/m);\n  const peak =\n    read(\"/sys/fs/cgroup/memory.peak\") ??\n    read(\"/sys/fs/cgroup/memory/memory.max_usage_in_bytes\") ??\n    read(\"/sys/fs/cgroup/memory/memory.usage_in_bytes\");\n  let rx = 0, tx = 0, sawNet = false;\n  const net = read(\"/proc/net/dev\");\n  if (net) {\n    for (const line of net.split(\"\\n\").slice(2)) {\n      const m = line.trim().match(/^(\\S+):\\s+(\\d+)(?:\\s+\\d+){7}\\s+(\\d+)/);\n      if (m && m[1] !== \"lo\") { rx += Number(m[2]); tx += Number(m[3]); sawNet = true; }\n    }\n  }\n  return {\n    busyCpuSecs: usage\n      ? Number(usage[1]) / 1e6\n      : Number.isFinite(cpuacctNs) && cpuacctNs > 0\n        ? cpuacctNs / 1e9\n        : null,\n    peakMemBytes: peak ? Number(peak.trim()) || null : null,\n    throttledSecs: throttledUs ? Number(throttledUs[1]) / 1e6 : throttledNs ? Number(throttledNs[1]) / 1e9 : null,\n    rxBytes: sawNet ? rx : null,\n    txBytes: sawNet ? tx : null,\n  };\n}\n\ntry {\n  // Runtime state (venvs, npm prefixes) lands in the agent user's real home\n  // \u2014 writable, inside the container, gone with it.\n  process.env.FOLDRUN_DATA = \"/home/agent/.foldrun\";\n  const { executeStep } = await import(\"@foldrun/core/step-exec\");\n  const { buildApiTools } = await import(\"@foldrun/core/api-tools\");\n  const { buildScriptTools } = await import(\"@foldrun/core/script-tools\");\n  const { buildConsultTools } = await import(\"@foldrun/core/agent-tools\");\n  const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import(\"@foldrun/core/context-tools\");\n  const { httpChannel, buildAskTool, buildPeerTools, inboxReader } = await import(\"@foldrun/core/operator\");\n  const { buildDelegateTools } = await import(\"@foldrun/core/delegate-tools\");\n  const { startTranslator } = await import(\"@foldrun/core/translator\");\n  const { prepareRuntime } = await import(\"@foldrun/core/runtime\");\n  const { materializeFileSecrets } = await import(\"@foldrun/core/secret-files\");\n  const { paidWebActions } = await import(\"@foldrun/core/browser-pod\");\n  mark(\"imports\");\n\n  const agentDir = \"/workspace/\" + input.agentRel;\n  // HOME is where a bare relative path lands when anything resolves one\n  // outside cwd \u2014 and root's /root is outside the workspace, so such a read\n  // was refused by confinement with a path the agent never typed. Its own\n  // directory is both the truthful answer and the safe one.\n  // @file secrets crossed as content; materialise them to 0600 paths inside\n  // the container (a host path from the other side would not exist here).\n  const env = materializeFileSecrets(agentDir, { ...process.env, HOME: agentDir }).env;\n  // Caches go to the sandbox user's own home, not to HOME: the Claude CLI's\n  // logs, fontconfig, Mesa and gstreamer all follow XDG_CACHE_HOME, and under\n  // agents/<name>/.cache they were copied back after every step \u2014 3,855 files\n  // across 179 agent folders on the box by 17 Oct 2026, read by nothing.\n  env.XDG_CACHE_HOME = \"/home/agent/.cache\";\n\n  // The declared runtime, built in here \u2014 pip and npm have the network, which\n  // the host side may not. It lands in .foldrun/runner/.runtimes, which the\n  // executors mount from a per-tenant directory (run-container.ts#RUNTIME_CACHE):\n  // the first step for a given fingerprint installs, every later one finds\n  // .ready and skips. With no mount it still works, just fresh every time \u2014\n  // which is what this used to be unconditionally. The log says which happened.\n  const runtime = input.runtime\n    ? prepareRuntime(\"runner\", input.runtime)\n    : { interpreters: {}, env: {}, log: [], error: null };\n  for (const line of runtime.log) emit(\"info\", \"runtime: \" + line);\n  if (runtime.error) emit(\"error\", \"runtime: \" + runtime.error);\n  // The step's own environment gets it too, not only the script tools: an\n  // agent that runs \"python3 x.py\" or a shebang script through Bash should\n  // meet the packages its runtime declared, not the image's bare python.\n  Object.assign(env, runtime.env);\n\n  // install: what the agent finds it needs mid-step. apt goes through the\n  // root start-up's helper (install-helper.ts); pip and npm land in a\n  // directory of this container's own, on the paths from the first turn.\n  const { buildInstallTool, INSTALL_TOOL } = await import(\"@foldrun/core/install-tool\");\n  const { stepInstallEnv, INSTALL_SOCKET } = await import(\"@foldrun/core/runtime\");\n  const installDir = \"/home/agent/.foldrun/step\";\n  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);\n  if (installing) Object.assign(env, stepInstallEnv(installDir, env));\n  const install = installing\n    ? buildInstallTool({\n        dir: installDir,\n        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,\n        cacheRoot: \"/home/agent/.foldrun/runner/.runtimes\",\n        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + \"/bin/python\" : \"python3\",\n        env,\n        emit,\n      })\n    : { server: null };\n\n  // API and script tools, rebuilt in here from their specs. Secrets were\n  // substituted into API headers before the input crossed the boundary, so\n  // buildApiTools gets an already-resolved environment. verify: gets the\n  // container's own environment, whole: it is the boundary, assembled on\n  // the host from an allowlist, and the declared secrets are in it.\n  // A long result is kept in a file only when the agent can read it back.\n  // (tool-output.ts canReadBack, inlined: the driver imports core by subpath.)\n  const keepIn = { dir: agentDir, readable: () => (input.allowed ?? []).some((t) => t === \"Read\" || t === \"Grep\") };\n  // A declared secret named like a model variable crosses as\n  // FOLDRUN_DECLARED_<NAME> (runner.ts, FOL-19): the model keeps its own\n  // settings, and the agent's API and script tools and verify: get the value\n  // back under the name it declared. Built here, after the runtime and any\n  // mid-step install have added their paths to env.\n  const toolEnv = { ...env };\n  for (const [k, v] of Object.entries(env)) if (k.startsWith(\"FOLDRUN_DECLARED_\")) toolEnv[k.slice(\"FOLDRUN_DECLARED_\".length)] = v;\n  const api = buildApiTools(\"\", input.apis, undefined, { env: toolEnv, missing: [] }, keepIn);\n  const script = buildScriptTools(\n    agentDir,\n    input.scripts,\n    toolEnv,\n    \"/library/scripts\",\n    runtime.interpreters,\n    null,\n    keepIn.readable,\n  );\n  // The translator, when the provider speaks Chat Completions: a loopback\n  // server for the length of this step. Its env replaces the endpoint the\n  // host assembled; the provider's real URL and key stay inside it.\n  const translator = input.translator ? await startTranslator(input.translator) : null;\n  if (translator) {\n    Object.assign(env, translator.env);\n    emit(\"info\", \"translator: listening on \" + translator.baseUrl + \" for \" + (input.translator.label ?? input.translator.upstreamBase));\n  }\n  const consult = buildConsultTools(input.consults ?? [], env, emit);\n  // The platform's own two groups, rebuilt from values like everything else.\n  const search = buildSearchTools(input.search ?? []);\n  const history = input.history?.length ? buildHistoryTools(input.history) : { server: null };\n  const desks = input.desks?.length ? buildDeskTools(input.desks) : { server: null };\n  // A person in the loop, over the proxy this step's lease already names:\n  // ask_person when tools: [ask], and the run's inbox after every tool call.\n  const channel = httpChannel(env.FOLDRUN_EGRESS);\n  const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };\n  const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };\n  const inbox = channel ? inboxReader(channel, emit) : undefined;\n  // sandbox: own sub-agents: a tool each, whose job runs in its own sandbox\n  // on the worker, reached over the same proxy door.\n  const delegate = input.delegates?.length ? buildDelegateTools({ specs: input.delegates, channel, emit, timeoutSec: input.timeoutSec, workspaceRoot: \"/workspace\" }) : { server: null };\n\n  // Keyless cloud identities (FOLDRUN_IDENTITIES): each token file kept\n  // fresh through the proxy's /identity door, which mints only what this\n  // step's lease was granted. Fetched before the step starts, renewed five\n  // minutes before it expires (with jitter); a failure is said and retried.\n  // Plain JS: this text is the driver, not TypeScript.\n  const identityNames = (env.FOLDRUN_IDENTITIES || \"\").split(\",\").filter(Boolean);\n  if (identityNames.length) {\n    // No backslashes: this sits inside a template literal, which eats them.\n    const ep = new RegExp(\"^(https?://[^/]+)/e/([A-Za-z0-9_-]{16,})/?$\").exec(env.FOLDRUN_EGRESS || \"\");\n    const dir = env.FOLDRUN_IDENTITY_DIR || \"/tmp/foldrun-identity\";\n    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });\n    const keepFresh = async (name) => {\n      let wait = 30000;\n      try {\n        if (!ep) throw new Error(\"no egress proxy to ask\");\n        const res = await fetch(ep[1] + \"/identity/\" + ep[2] + \"/\" + name, { signal: AbortSignal.timeout(15000) });\n        const body = await res.json().catch(() => ({}));\n        if (!res.ok || !body.token) throw new Error((body.error && body.error.message) || (\"proxy answered \" + res.status));\n        const file = dir + \"/\" + name.toLowerCase() + \".jwt\";\n        fs.writeFileSync(file + \".tmp\", body.token, { mode: 0o600 });\n        fs.renameSync(file + \".tmp\", file);\n        wait = Math.max(30000, body.expiresAt - Date.now() - 300000 + Math.floor(Math.random() * 60000) - 30000);\n      } catch (err) {\n        emit(\"error\", \"identity \" + name + \": \" + (err && err.message ? err.message : String(err)) + \" \u2014 trying again in 30s\");\n      }\n      setTimeout(() => { void keepFresh(name); }, wait).unref();\n    };\n    await Promise.all(identityNames.map(keepFresh));\n  }\n\n  mark(\"tools\");\n  const outcome = await executeStep({\n    agentDir,\n    workspaceRoot: \"/workspace\",\n    libraryRoot: \"/library\",\n    prompt: input.prompt,\n    model: input.model,\n    effort: input.effort ?? null,\n    systemPrompt: input.systemPrompt,\n    allowed: input.allowed,\n    mcpNames: input.mcpNames,\n    mcpServers: {\n      ...(api.server ? { foldrun_apis: api.server } : {}),\n      ...(script.server ? { foldrun_scripts: script.server } : {}),\n      ...(consult.server ? { foldrun_agents: consult.server } : {}),\n      ...(search.server ? { foldrun_search: search.server } : {}),\n      ...(history.server ? { foldrun_history: history.server } : {}),\n      ...(desks.server ? { foldrun_desks: desks.server } : {}),\n      ...(ask.server ? { foldrun_ask: ask.server } : {}),\n      ...(peers.server ? { foldrun_peers: peers.server } : {}),\n      ...(delegate.server ? { foldrun_delegate: delegate.server } : {}),\n      ...(install.server ? { foldrun_install: install.server } : {}),\n      ...input.mcpServers,\n    },\n    ...(inbox ? { inbox } : {}),\n    ...(input.subagents?.length ? { subagents: input.subagents } : {}),\n    env,\n    timeoutSec: input.timeoutSec,\n    budgetUsd: input.budgetUsd,\n    budgetNote: input.budgetNote,\n    price: input.price,\n    verify: input.verify,\n    verifyEnv: toolEnv,\n    ...(typeof input.judgeModel === \"string\" ? { judgeModel: input.judgeModel } : {}),\n    ...(typeof input.judgeEffort === \"string\" ? { judgeEffort: input.judgeEffort } : {}),\n    output: input.output,\n    schema: input.schema,\n    maxTurns: input.maxTurns,\n    ...(input.capture === \"metadata\" || input.capture === \"full\" ? { capture: input.capture } : {}),\n    ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),\n    ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),\n    // Slim browsing: the platform put this step on the slim image to browse\n    // through the account's pod, and named the file the web tool logs its\n    // reconnects to. A lost pod stops the step; what it wrote decides what\n    // the runner does next (browser-pod.ts).\n    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env), ...(env.FOLDRUN_BROWSER_INIT ? { browseInit: env.FOLDRUN_BROWSER_INIT } : {}) } } : {}),\n    // The container is the boundary; the SDK's own bash sandbox here would\n    // only block declared network use (SSH, curl) for no added safety.\n    sandboxBash: false,\n    emit,\n  });\n  for (const line of api.drainLog()) emit(\"info\", \"api: \" + line);\n  for (const line of script.drainLog()) emit(\"info\", \"script: \" + line);\n  if (translator) {\n    for (const line of translator.drainLog()) emit(\"info\", line.startsWith(\"translator\") ? line : \"translator: \" + line);\n    await translator.close();\n  }\n  // A consult's spend belongs to the step that asked.\n  const consultCost = consult.drainCost();\n  if (consultCost > 0) outcome.costUsd = (outcome.costUsd ?? 0) + consultCost;\n  if (consultCost > 0 && typeof outcome.turnsCostUsd === \"number\") outcome.turnsCostUsd += consultCost;\n  process.stdout.write(JSON.stringify({ e: \"done\", ...outcome, res: readActuals() }) + \"\\n\");\n  process.exit(0);\n} catch (err) {\n  emit(\"error\", err instanceof Error ? err.message : String(err));\n  // The failure path reports actuals too \u2014 a step that died eleven minutes\n  // in still held its slice for eleven minutes, and the failed runs are\n  // exactly the ones whose resource story gets read.\n  let res = null;\n  try { res = readActuals(); } catch { /* the reading must never mask the error */ }\n  process.stdout.write(JSON.stringify({ e: \"done\", status: \"failed\", result: null, costUsd: null, res }) + \"\\n\");\n  process.exit(0);\n}\n";
+export declare const DRIVER = "// The runner container's entrypoint. Reads one step, executes it with the\n// same core the server uses, speaks JSONL on stdout, exits.\nimport fs from \"node:fs\";\nconst input = JSON.parse(fs.readFileSync(\"/opt/runner/job/input.json\", \"utf8\"));\n// Start-up marks (run-container.ts#STARTUP_PHASES): which phase just ended,\n// on the sandbox's clock. A worker that does not know a mark skips the line.\nconst mark = (name) => process.stdout.write(JSON.stringify({ e: \"mark\", name, at: Date.now() }) + \"\\n\");\nmark(\"driver\");\nlet modelSpoke = false;\nconst emit = (type, text, extra) => {\n  // The model's first text or tool call is where start-up ends and the\n  // step's own work begins \u2014 runtime and tool lines before it are set-up.\n  if (!modelSpoke && (type === \"text\" || type === \"tool\")) { modelSpoke = true; mark(\"model\"); }\n  process.stdout.write(JSON.stringify({ e: \"event\", type, text, ...extra }) + \"\\n\");\n};\n// What this sandbox actually touched, read at the last moment from the\n// kernel's own books: cgroup v2 for CPU busy-time and peak memory,\n// /proc/net/dev for bytes on the wire. Every read is best-effort \u2014 gVisor\n// exposes some of these files and not others depending on version, and a\n// metric we cannot read is null, never guessed. Reservation is what is\n// billed; these exist so the reservation can be right-sized.\nfunction readActuals() {\n  // fs from the module's own import \u2014 the driver is ESM, and a require()\n  // here threw on every call, silently nulling every metric it guarded.\n  const read = (p) => { try { return fs.readFileSync(p, \"utf8\"); } catch { return null; } };\n  // Two cgroup dialects: v2 (cpu.stat, microseconds; memory.peak) on a\n  // plain runtime, v1-style controllers under gVisor (cpuacct.usage,\n  // NANOseconds; memory.max_usage_in_bytes) \u2014 probed on the real cluster,\n  // not assumed. Whichever answers wins; both silent means null.\n  const cpuStat = read(\"/sys/fs/cgroup/cpu.stat\");\n  const usage = cpuStat?.match(/^usage_usec (\\d+)/m);\n  const cpuacctNs = usage ? NaN : Number(read(\"/sys/fs/cgroup/cpuacct/cpuacct.usage\")?.trim());\n  // Time the CPU cap held the sandbox back: v2's throttled_usec in the same\n  // cpu.stat, v1's throttled_time (nanoseconds) under gVisor. Large against\n  // busy time means the step wanted more cores than its class gives.\n  const throttledUs = cpuStat?.match(/^throttled_usec (\\d+)/m);\n  const throttledNs = throttledUs ? null : read(\"/sys/fs/cgroup/cpu/cpu.stat\")?.match(/^throttled_time (\\d+)/m);\n  const peak =\n    read(\"/sys/fs/cgroup/memory.peak\") ??\n    read(\"/sys/fs/cgroup/memory/memory.max_usage_in_bytes\") ??\n    read(\"/sys/fs/cgroup/memory/memory.usage_in_bytes\");\n  let rx = 0, tx = 0, sawNet = false;\n  const net = read(\"/proc/net/dev\");\n  if (net) {\n    for (const line of net.split(\"\\n\").slice(2)) {\n      const m = line.trim().match(/^(\\S+):\\s+(\\d+)(?:\\s+\\d+){7}\\s+(\\d+)/);\n      if (m && m[1] !== \"lo\") { rx += Number(m[2]); tx += Number(m[3]); sawNet = true; }\n    }\n  }\n  return {\n    busyCpuSecs: usage\n      ? Number(usage[1]) / 1e6\n      : Number.isFinite(cpuacctNs) && cpuacctNs > 0\n        ? cpuacctNs / 1e9\n        : null,\n    peakMemBytes: peak ? Number(peak.trim()) || null : null,\n    throttledSecs: throttledUs ? Number(throttledUs[1]) / 1e6 : throttledNs ? Number(throttledNs[1]) / 1e9 : null,\n    rxBytes: sawNet ? rx : null,\n    txBytes: sawNet ? tx : null,\n  };\n}\n\ntry {\n  // Runtime state (venvs, npm prefixes) lands in the agent user's real home\n  // \u2014 writable, inside the container, gone with it.\n  process.env.FOLDRUN_DATA = \"/home/agent/.foldrun\";\n  const { executeStep } = await import(\"@foldrun/core/step-exec\");\n  const { buildApiTools } = await import(\"@foldrun/core/api-tools\");\n  const { buildScriptTools } = await import(\"@foldrun/core/script-tools\");\n  const { buildConsultTools } = await import(\"@foldrun/core/agent-tools\");\n  const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import(\"@foldrun/core/context-tools\");\n  const { httpChannel, buildAskTool, buildPeerTools, inboxReader } = await import(\"@foldrun/core/operator\");\n  const { buildDelegateTools } = await import(\"@foldrun/core/delegate-tools\");\n  const { startTranslator } = await import(\"@foldrun/core/translator\");\n  const { prepareRuntime } = await import(\"@foldrun/core/runtime\");\n  const { materializeFileSecrets } = await import(\"@foldrun/core/secret-files\");\n  const { paidWebActions } = await import(\"@foldrun/core/browser-pod\");\n  mark(\"imports\");\n\n  const agentDir = \"/workspace/\" + input.agentRel;\n  // HOME is where a bare relative path lands when anything resolves one\n  // outside cwd \u2014 and root's /root is outside the workspace, so such a read\n  // was refused by confinement with a path the agent never typed. Its own\n  // directory is both the truthful answer and the safe one.\n  // @file secrets crossed as content; materialise them to 0600 paths inside\n  // the container (a host path from the other side would not exist here).\n  const env = materializeFileSecrets(agentDir, { ...process.env, HOME: agentDir }).env;\n  // Caches go to the sandbox user's own home, not to HOME: the Claude CLI's\n  // logs, fontconfig, Mesa and gstreamer all follow XDG_CACHE_HOME, and under\n  // agents/<name>/.cache they were copied back after every step \u2014 3,855 files\n  // across 179 agent folders on the box by 17 Oct 2026, read by nothing.\n  env.XDG_CACHE_HOME = \"/home/agent/.cache\";\n\n  // The declared runtime, built in here \u2014 pip and npm have the network, which\n  // the host side may not. It lands in .foldrun/runner/.runtimes, which the\n  // executors mount from a per-tenant directory (run-container.ts#RUNTIME_CACHE):\n  // the first step for a given fingerprint installs, every later one finds\n  // .ready and skips. With no mount it still works, just fresh every time \u2014\n  // which is what this used to be unconditionally. The log says which happened.\n  const runtime = input.runtime\n    ? prepareRuntime(\"runner\", input.runtime)\n    : { interpreters: {}, env: {}, log: [], error: null };\n  for (const line of runtime.log) emit(\"info\", \"runtime: \" + line);\n  if (runtime.error) emit(\"error\", \"runtime: \" + runtime.error);\n  // The step's own environment gets it too, not only the script tools: an\n  // agent that runs \"python3 x.py\" or a shebang script through Bash should\n  // meet the packages its runtime declared, not the image's bare python.\n  Object.assign(env, runtime.env);\n\n  // install: what the agent finds it needs mid-step. apt goes through the\n  // root start-up's helper (install-helper.ts); pip and npm land in a\n  // directory of this container's own, on the paths from the first turn.\n  const { buildInstallTool, INSTALL_TOOL } = await import(\"@foldrun/core/install-tool\");\n  const { stepInstallEnv, INSTALL_SOCKET } = await import(\"@foldrun/core/runtime\");\n  const installDir = \"/home/agent/.foldrun/step\";\n  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);\n  if (installing) Object.assign(env, stepInstallEnv(installDir, env));\n  const install = installing\n    ? buildInstallTool({\n        dir: installDir,\n        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,\n        cacheRoot: \"/home/agent/.foldrun/runner/.runtimes\",\n        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + \"/bin/python\" : \"python3\",\n        env,\n        emit,\n      })\n    : { server: null };\n\n  // API and script tools, rebuilt in here from their specs. Secrets were\n  // substituted into API headers before the input crossed the boundary, so\n  // buildApiTools gets an already-resolved environment. verify: gets the\n  // container's own environment, whole: it is the boundary, assembled on\n  // the host from an allowlist, and the declared secrets are in it.\n  // A long result is kept in a file only when the agent can read it back.\n  // (tool-output.ts canReadBack, inlined: the driver imports core by subpath.)\n  const keepIn = { dir: agentDir, readable: () => (input.allowed ?? []).some((t) => t === \"Read\" || t === \"Grep\") };\n  // A declared secret named like a model variable crosses as\n  // FOLDRUN_DECLARED_<NAME> (runner.ts, FOL-19): the model keeps its own\n  // settings, and the agent's API and script tools and verify: get the value\n  // back under the name it declared. Built here, after the runtime and any\n  // mid-step install have added their paths to env.\n  const toolEnv = { ...env };\n  for (const [k, v] of Object.entries(env)) if (k.startsWith(\"FOLDRUN_DECLARED_\")) toolEnv[k.slice(\"FOLDRUN_DECLARED_\".length)] = v;\n  const api = buildApiTools(\"\", input.apis, undefined, { env: toolEnv, missing: [] }, keepIn);\n  const script = buildScriptTools(\n    agentDir,\n    input.scripts,\n    toolEnv,\n    \"/library/scripts\",\n    runtime.interpreters,\n    null,\n    keepIn.readable,\n  );\n  // The translator, when the provider speaks Chat Completions: a loopback\n  // server for the length of this step. Its env replaces the endpoint the\n  // host assembled; the provider's real URL and key stay inside it.\n  const translator = input.translator ? await startTranslator(input.translator) : null;\n  if (translator) {\n    Object.assign(env, translator.env);\n    emit(\"info\", \"translator: listening on \" + translator.baseUrl + \" for \" + (input.translator.label ?? input.translator.upstreamBase));\n  }\n  const consult = buildConsultTools(input.consults ?? [], env, emit);\n  // The platform's own two groups, rebuilt from values like everything else.\n  const search = buildSearchTools(input.search ?? []);\n  const history = input.history?.length ? buildHistoryTools(input.history) : { server: null };\n  const desks = input.desks?.length ? buildDeskTools(input.desks) : { server: null };\n  // A person in the loop, over the proxy this step's lease already names:\n  // ask_person when tools: [ask], and the run's inbox after every tool call.\n  const channel = httpChannel(env.FOLDRUN_EGRESS);\n  const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };\n  const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };\n  const inbox = channel ? inboxReader(channel, emit) : undefined;\n  // sandbox: own sub-agents: a tool each, whose job runs in its own sandbox\n  // on the worker, reached over the same proxy door.\n  const delegate = input.delegates?.length ? buildDelegateTools({ specs: input.delegates, channel, emit, timeoutSec: input.timeoutSec, workspaceRoot: \"/workspace\" }) : { server: null };\n\n  // Keyless cloud identities (FOLDRUN_IDENTITIES): each token file kept\n  // fresh through the proxy's /identity door, which mints only what this\n  // step's lease was granted. Fetched before the step starts, renewed five\n  // minutes before it expires (with jitter); a failure is said and retried.\n  // Plain JS: this text is the driver, not TypeScript.\n  const identityNames = (env.FOLDRUN_IDENTITIES || \"\").split(\",\").filter(Boolean);\n  if (identityNames.length) {\n    // No backslashes: this sits inside a template literal, which eats them.\n    const ep = new RegExp(\"^(https?://[^/]+)/e/([A-Za-z0-9_-]{16,})/?$\").exec(env.FOLDRUN_EGRESS || \"\");\n    const dir = env.FOLDRUN_IDENTITY_DIR || \"/tmp/foldrun-identity\";\n    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });\n    const keepFresh = async (name) => {\n      let wait = 30000;\n      try {\n        if (!ep) throw new Error(\"no egress proxy to ask\");\n        const res = await fetch(ep[1] + \"/identity/\" + ep[2] + \"/\" + name, { signal: AbortSignal.timeout(15000) });\n        const body = await res.json().catch(() => ({}));\n        if (!res.ok || !body.token) throw new Error((body.error && body.error.message) || (\"proxy answered \" + res.status));\n        const file = dir + \"/\" + name.toLowerCase() + \".jwt\";\n        fs.writeFileSync(file + \".tmp\", body.token, { mode: 0o600 });\n        fs.renameSync(file + \".tmp\", file);\n        wait = Math.max(30000, body.expiresAt - Date.now() - 300000 + Math.floor(Math.random() * 60000) - 30000);\n      } catch (err) {\n        emit(\"error\", \"identity \" + name + \": \" + (err && err.message ? err.message : String(err)) + \" \u2014 trying again in 30s\");\n      }\n      setTimeout(() => { void keepFresh(name); }, wait).unref();\n    };\n    await Promise.all(identityNames.map(keepFresh));\n  }\n\n  mark(\"tools\");\n  const outcome = await executeStep({\n    agentDir,\n    workspaceRoot: \"/workspace\",\n    libraryRoot: \"/library\",\n    configWrites: input.configWrites === true,\n    prompt: input.prompt,\n    model: input.model,\n    effort: input.effort ?? null,\n    systemPrompt: input.systemPrompt,\n    allowed: input.allowed,\n    mcpNames: input.mcpNames,\n    mcpServers: {\n      ...(api.server ? { foldrun_apis: api.server } : {}),\n      ...(script.server ? { foldrun_scripts: script.server } : {}),\n      ...(consult.server ? { foldrun_agents: consult.server } : {}),\n      ...(search.server ? { foldrun_search: search.server } : {}),\n      ...(history.server ? { foldrun_history: history.server } : {}),\n      ...(desks.server ? { foldrun_desks: desks.server } : {}),\n      ...(ask.server ? { foldrun_ask: ask.server } : {}),\n      ...(peers.server ? { foldrun_peers: peers.server } : {}),\n      ...(delegate.server ? { foldrun_delegate: delegate.server } : {}),\n      ...(install.server ? { foldrun_install: install.server } : {}),\n      ...input.mcpServers,\n    },\n    ...(inbox ? { inbox } : {}),\n    ...(input.subagents?.length ? { subagents: input.subagents } : {}),\n    env,\n    timeoutSec: input.timeoutSec,\n    budgetUsd: input.budgetUsd,\n    budgetNote: input.budgetNote,\n    price: input.price,\n    verify: input.verify,\n    verifyEnv: toolEnv,\n    ...(typeof input.judgeModel === \"string\" ? { judgeModel: input.judgeModel } : {}),\n    ...(typeof input.judgeEffort === \"string\" ? { judgeEffort: input.judgeEffort } : {}),\n    output: input.output,\n    schema: input.schema,\n    maxTurns: input.maxTurns,\n    ...(input.capture === \"metadata\" || input.capture === \"full\" ? { capture: input.capture } : {}),\n    ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),\n    ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),\n    // Slim browsing: the platform put this step on the slim image to browse\n    // through the account's pod, and named the file the web tool logs its\n    // reconnects to. A lost pod stops the step; what it wrote decides what\n    // the runner does next (browser-pod.ts).\n    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env), ...(env.FOLDRUN_BROWSER_INIT ? { browseInit: env.FOLDRUN_BROWSER_INIT } : {}) } } : {}),\n    // The container is the boundary; the SDK's own bash sandbox here would\n    // only block declared network use (SSH, curl) for no added safety.\n    sandboxBash: false,\n    emit,\n  });\n  for (const line of api.drainLog()) emit(\"info\", \"api: \" + line);\n  for (const line of script.drainLog()) emit(\"info\", \"script: \" + line);\n  if (translator) {\n    for (const line of translator.drainLog()) emit(\"info\", line.startsWith(\"translator\") ? line : \"translator: \" + line);\n    await translator.close();\n  }\n  // A consult's spend belongs to the step that asked.\n  const consultCost = consult.drainCost();\n  if (consultCost > 0) outcome.costUsd = (outcome.costUsd ?? 0) + consultCost;\n  if (consultCost > 0 && typeof outcome.turnsCostUsd === \"number\") outcome.turnsCostUsd += consultCost;\n  process.stdout.write(JSON.stringify({ e: \"done\", ...outcome, res: readActuals() }) + \"\\n\");\n  process.exit(0);\n} catch (err) {\n  emit(\"error\", err instanceof Error ? err.message : String(err));\n  // The failure path reports actuals too \u2014 a step that died eleven minutes\n  // in still held its slice for eleven minutes, and the failed runs are\n  // exactly the ones whose resource story gets read.\n  let res = null;\n  try { res = readActuals(); } catch { /* the reading must never mask the error */ }\n  process.stdout.write(JSON.stringify({ e: \"done\", status: \"failed\", result: null, costUsd: null, res }) + \"\\n\");\n  process.exit(0);\n}\n";
 /** 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 declare const UV_VERSION = "0.11.25";
@@ -437,6 +472,9 @@ export declare function dockerCpus(cpus: string, available?: number): string | n
 export declare function heldCores(cpus: string, isolation: string | undefined, available?: number): number;
 export interface RunInContainerArgs {
     workspaceRoot: string;
+    /** A person approved this step before it ran: configuration and code it
+     *  changed are kept, not refused (copy-back.ts, FOL-96). */
+    configWrites?: boolean;
     libraryRoot: string;
     /** The platform's gallery, staged under /library BEFORE the account library so the account's copies win. */
     galleryRoot?: string;
@@ -495,6 +533,10 @@ export interface RunInContainerArgs {
     /** 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;
+    /** What the host handed back into this sandbox mid-step (StepRecord.
+     *  handedBack), read at copy-out — kept on the host, never read back from
+     *  the sandbox alone (FOL-96). */
+    handedBack?: () => Record<string, string | string[]> | undefined;
     /** 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

package/dist/src/run-container.js

@@ -25,6 +25,7 @@ import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import { CAPTURE_CAP, isPlatformPath } from "./store.js";
 import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.js";
+import { refusedBack, refusedLine, keptLine } from "./copy-back.js";
 import { isFileValue, fileContent } from "./secrets.js";
 import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET } from "./runtime.js";
 import { egressCaSh } from "./network.js";
@@ -176,6 +177,46 @@ export function hashTree(dir) {
         walk(dir);
     return out;
 }
+/**
+ * Where the host keeps what a sandbox was handed (hashTree), for a driver
+ * that inherits the step: under the run's own folder, which is platform-
+ * owned — never staged into a sandbox, never copied back, erased with the
+ * run (deleteRun). It used to ride into the pod beside the input and be
+ * read back from there, where the step could rewrite it (FOL-96).
+ */
+export function handedInPath(workspaceRoot, runId, ref) {
+    const safe = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/;
+    if (!safe.test(runId) || !safe.test(ref))
+        return null;
+    return path.join(workspaceRoot, "runs", runId, "sandbox", `${ref}.json`);
+}
+/** Note what a sandbox was handed, on the host. */
+export function writeHandedIn(workspaceRoot, runId, ref, hashes) {
+    const file = handedInPath(workspaceRoot, runId, ref);
+    if (!file)
+        return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(hashes));
+}
+/** What the host noted a sandbox was handed, or undefined. */
+export function readHandedIn(workspaceRoot, runId, ref) {
+    const file = handedInPath(workspaceRoot, runId, ref);
+    if (!file)
+        return undefined;
+    try {
+        const m = JSON.parse(fs.readFileSync(file, "utf8"));
+        return m && typeof m === "object" && !Array.isArray(m) ? m : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Forget it once the step's copy-out is done. */
+export function dropHandedIn(workspaceRoot, runId, ref) {
+    const file = handedInPath(workspaceRoot, runId, ref);
+    if (file)
+        fs.rmSync(file, { force: true });
+}
 /**
  * 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
@@ -258,13 +299,17 @@ export function mergeAppends(was, host, next) {
     const joined = hostAdded && !hostAdded.endsWith("\n") ? hostAdded + "\n" : hostAdded;
     return Buffer.from(h.slice(0, end) + joined + stepAdded, "utf8");
 }
-export function applyContainerChanges(hostWs, containerWs, baseline, note, divert) {
+export function applyContainerChanges(hostWs, containerWs, baseline, note, divert, opts = {}) {
     const applied = [];
     // Files a sandbox: own job's reply copied into this sandbox mid-step
     // (delegate-tools.ts copyBackFiles), path → sha256 of what was written: for
     // those, that is what the step started from. The job's change is already on
     // the workspace; read against the older baseline it came back as the
     // step's own and was merged in a second time (Codex review, 23 Oct 2026).
+    // The sandbox notes which it actually wrote (a conflict goes beside the
+    // file instead), but the step can write that note too, so an entry counts
+    // only where the host handed exactly those bytes back (FOL-96).
+    const handedBack = opts.handedBack ?? {};
     let imported = {};
     try {
         // Read here, on the host: a link the step planted is never followed,
@@ -273,8 +318,16 @@ export function applyContainerChanges(hostWs, containerWs, baseline, note, diver
         const file = path.join(dir, "copied-back.json");
         if (fs.lstatSync(dir).isDirectory() && fs.lstatSync(file).isFile()) {
             const m = JSON.parse(fs.readFileSync(file, "utf8"));
-            if (m && typeof m === "object" && !Array.isArray(m))
-                imported = m;
+            if (m && typeof m === "object" && !Array.isArray(m)) {
+                for (const [rel, h] of Object.entries(m)) {
+                    // Every version the host handed back for the path counts: two jobs
+                    // can return the same file, and the sandbox may hold the first
+                    // (the second went beside a parent edit as a conflict copy).
+                    const ok = handedBack[rel];
+                    if (typeof h === "string" && (Array.isArray(ok) ? ok.includes(h) : ok === h))
+                        imported[rel] = h;
+                }
+            }
         }
     }
     catch {
@@ -322,6 +375,18 @@ export function applyContainerChanges(hostWs, containerWs, baseline, note, diver
             const hostNow = fs.existsSync(target) ? fs.readFileSync(target) : null;
             if (hostNow && hostNow.equals(next))
                 continue;
+            // Configuration and code are a person's (copy-back.ts): refused here,
+            // after "did the step change it" and before any merge, conflict copy
+            // or test divert — so none of those can carry it to the workspace,
+            // and the next step is staged from the workspace's own copy.
+            const refused = refusedBack(rel);
+            if (refused && opts.allowConfig) {
+                opts.onKept?.({ path: rel.replaceAll("\\", "/"), kind: refused });
+            }
+            else if (refused) {
+                opts.onRefused?.({ path: rel.replaceAll("\\", "/"), kind: refused });
+                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
@@ -646,6 +711,7 @@ try {
     agentDir,
     workspaceRoot: "/workspace",
     libraryRoot: "/library",
+    configWrites: input.configWrites === true,
     prompt: input.prompt,
     model: input.model,
     effort: input.effort ?? null,
@@ -1643,8 +1709,19 @@ export async function runStepInContainer(args) {
         fs.mkdirSync(wsOut);
         const back = spawnSync(cli(), ["cp", `${containerId}:/workspace/.`, wsOut], { encoding: "utf8" });
         let applied = [];
+        const refused = [];
+        const kept = [];
         if (back.status === 0) {
-            applied = applyContainerChanges(args.workspaceRoot, wsOut, wsIn, (m) => args.emit("error", m), args.divert);
+            applied = applyContainerChanges(args.workspaceRoot, wsOut, wsIn, (m) => args.emit("error", m), args.divert, {
+                handedBack: args.handedBack?.(),
+                onRefused: (r) => refused.push(r),
+                allowConfig: args.configWrites === true,
+                onKept: (r) => kept.push(r),
+            });
+            if (refused.length)
+                args.emit("info", refusedLine(refused));
+            if (kept.length)
+                args.emit("info", keptLine(kept));
         }
         else {
             args.emit("error", `copy-out failed — the step's file changes were lost:\n${back.stderr.slice(0, 500)}`);
@@ -1658,7 +1735,7 @@ export async function runStepInContainer(args) {
             phases,
         };
         args.emit("info", timingLine(timing));
-        return { ...outcome, timing, applied };
+        return { ...outcome, timing, applied, ...(refused.length ? { refused } : {}) };
     }
     finally {
         if (containerId)