@foldrun/core 2.14.3 → 4.0.0

package/src/run-container.ts

@@ -29,6 +29,7 @@ import { spawn, spawnSync } from "node:child_process";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { CAPTURE_CAP, isPlatformPath, type ApiSpec, type Effort, type ModelCall } from "./store.ts";
 import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.ts";
+import { refusedBack, refusedLine, keptLine, type RefusedPath } from "./copy-back.ts";
 import type { CallIo, EventExtra, ExecUsage } from "./step-exec.ts";
 import type { TokenPrice } from "./catalog.ts";
 import { isFileValue, fileContent } from "./secrets.ts";
@@ -47,6 +48,9 @@ import { parseBrowserPod, type BrowserPodOutcome } from "./browser-pod.ts";
  *  secrets in headers, assembled prompt, serializable MCP configs. */
 export interface ContainerStepInput {
   agentRel: string; // "agents/<name>" inside the workspace
+  /** 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;
@@ -229,6 +233,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[];
 }
 
 /**
@@ -333,6 +340,45 @@ export function hashTree(dir: string): Record<string, string> {
   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: string, runId: string, ref: string): string | null {
+  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: string, runId: string, ref: string, hashes: Record<string, string>): void {
+  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: string, runId: string, ref: string): Record<string, string> | undefined {
+  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 as Record<string, string>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Forget it once the step's copy-out is done. */
+export function dropHandedIn(workspaceRoot: string, runId: string, ref: string): void {
+  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
@@ -412,12 +458,28 @@ export function mergeAppends(was: Buffer | string | null, host: Buffer, next: Bu
   return Buffer.from(h.slice(0, end) + joined + stepAdded, "utf8");
 }
 
+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 function applyContainerChanges(
   hostWs: string,
   containerWs: string,
   baseline?: string | Record<string, string>,
   note?: (message: string) => void,
   divert?: WriteDivert,
+  opts: ApplyOptions = {},
 ): string[] {
   const applied: string[] = [];
   // Files a sandbox: own job's reply copied into this sandbox mid-step
@@ -425,6 +487,10 @@ export function applyContainerChanges(
   // 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: Record<string, string> = {};
   try {
     // Read here, on the host: a link the step planted is never followed,
@@ -433,7 +499,15 @@ export function applyContainerChanges(
     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 as Record<string, string>;
+      if (m && typeof m === "object" && !Array.isArray(m)) {
+        for (const [rel, h] of Object.entries(m as Record<string, unknown>)) {
+          // 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 {
     /* none copied back */
@@ -474,6 +548,17 @@ export function applyContainerChanges(
       const target = path.join(hostWs, rel);
       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
@@ -806,6 +891,7 @@ try {
     agentDir,
     workspaceRoot: "/workspace",
     libraryRoot: "/library",
+    configWrites: input.configWrites === true,
     prompt: input.prompt,
     model: input.model,
     effort: input.effort ?? null,
@@ -1491,6 +1577,9 @@ export function heldCores(cpus: string, isolation: string | undefined, available
 
 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;
@@ -1543,6 +1632,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
@@ -1912,8 +2005,17 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
     fs.mkdirSync(wsOut);
     const back = spawnSync(cli(), ["cp", `${containerId}:/workspace/.`, wsOut], { encoding: "utf8" });
     let applied: string[] = [];
+    const refused: RefusedPath[] = [];
+    const kept: RefusedPath[] = [];
     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)}`);
     }
@@ -1927,7 +2029,7 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
       phases,
     };
     args.emit("info", timingLine(timing));
-    return { ...outcome, timing, applied };
+    return { ...outcome, timing, applied, ...(refused.length ? { refused } : {}) };
   } finally {
     if (containerId) spawnSync(cli(), ["rm", "-f", containerId], { stdio: "ignore" });
     fs.rmSync(staging, { recursive: true, force: true });

package/src/runner.ts

@@ -3036,6 +3036,8 @@ async function runStep(
         tenant,
         input: {
           agentRel: path.relative(workspaceRoot, agentDir).replaceAll("\\", "/"),
+          // Its file tools inside the sandbox get the same allowance (FOL-96).
+          configWrites: step.approve === true && Boolean(step.approvedAt),
           prompt,
           model,
           effort,
@@ -3127,6 +3129,11 @@ async function runStep(
         network: { level: network.level, enforced: forward?.enforce === true },
         // A test run's state/ and storage/ changes come out under the run.
         divert: testRun && runId ? divertFor(runId) : undefined,
+        // Read at copy-out: what the host handed back into the sandbox.
+        handedBack: () => step.handedBack,
+        // A person approved this step before it ran: configuration and code
+        // it changes are kept, listed on the trail (FOL-96).
+        configWrites: step.approve === true && Boolean(step.approvedAt),
         test: testRun,
         // Resume: a sandbox a previous driver left running, recorded on the
         // step. Consumed once — a fresh attempt after this one (a retry, a
@@ -3332,6 +3339,11 @@ async function runStep(
       step.image = outcome.image ?? null;
       step.browserPod = outcome.browserPod ? { ...outcome.browserPod } : null;
       if (step.subagentOf && outcome.applied?.length) step.wrote = [...new Set([...(step.wrote ?? []), ...outcome.applied])];
+      if (outcome.refused?.length) {
+        const seen = new Map((step.refused ?? []).map((r) => [r.path, r]));
+        for (const r of outcome.refused) seen.set(r.path, r);
+        step.refused = [...seen.values()];
+      }
       if (outcome.status === "failed" && outcome.browserPod?.lost) {
         const decision = podLossDecision(outcome.browserPod);
         if (decision.rerun) {
@@ -3503,6 +3515,9 @@ async function runStep(
       const attemptInProcess = (modelEnv: Record<string, string | undefined>) => executeStep({
         agentDir,
         workspaceRoot,
+        // A person approved this step (its gate) before it ran: it may change
+        // configuration and code (FOL-96) — the desks' retro applies fixes so.
+        configWrites: step.approve === true && Boolean(step.approvedAt),
         libraryRoot: libraryDir(tenant),
         ...(subagents.length ? { subagents } : {}),
         // The colleagues' inbox, read after every tool call — the same hook
@@ -5241,6 +5256,21 @@ function driveRunInner(
           // Its files go back with the reply, so the delegating step's
           // sandbox has them too (delegate-tools.ts copyBackFiles).
           const back = readCopyBack(pDir, child.wrote ?? []);
+          // What goes back into the parent's sandbox, as the host sends it:
+          // its copy-out reads this, not the sandbox's own note (FOL-96).
+          if (back.files.length) {
+            parent.handedBack = { ...(parent.handedBack ?? {}) };
+            for (const f of back.files) {
+              const h = crypto.createHash("sha256").update(Buffer.from(f.base64, "base64")).digest("hex");
+              // Kept beside any earlier job's for the same path, never over
+              // it: either may be what the sandbox ends up holding.
+              const prev = parent.handedBack[f.path];
+              const all = prev === undefined ? [] : Array.isArray(prev) ? prev : [prev];
+              if (!all.includes(h)) all.push(h);
+              parent.handedBack[f.path] = all.length === 1 ? all[0] : all;
+            }
+            save();
+          }
           return {
             status,
             result: child.result ?? (errors || "(no reply)"),

package/src/step-exec.ts

@@ -87,6 +87,9 @@ export interface ExecOutcome {
 }
 
 export interface ExecOptions {
+  /** A person approved this step before it ran: its file tools may write
+   *  the workspace's configuration and code (confine.ts, FOL-96). */
+  configWrites?: boolean;
   /** What the step reports beyond its events (FOL-54 step 4): `metadata`
    *  sends each model call (`turn`); `full` also sends each tool call's input
    *  and output (`io`). Unset sends neither — the consult, the probe and any
@@ -520,7 +523,7 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
               }
             }
             const verdict = isFilesystemTool(hookInput.tool_name)
-              ? checkPaths(hookInput.tool_name, hookInput.tool_input as Record<string, unknown>, { agentDir, workspaceRoot, libraryRoot })
+              ? checkPaths(hookInput.tool_name, hookInput.tool_input as Record<string, unknown>, { agentDir, workspaceRoot, libraryRoot, configWrites: opts.configWrites })
               : null;
             if (verdict && !verdict.ok) {
               emit("error", verdict.reason!, via ? { subagent: via } : undefined);
@@ -560,7 +563,7 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
                 const again = hookInput.tool_name === "Bash"
                   ? checkBash(String(v.input.command ?? ""))
                   : isFilesystemTool(hookInput.tool_name)
-                    ? checkPaths(hookInput.tool_name, v.input, { agentDir, workspaceRoot, libraryRoot })
+                    ? checkPaths(hookInput.tool_name, v.input, { agentDir, workspaceRoot, libraryRoot, configWrites: opts.configWrites })
                     : { ok: true as const };
                 const granted = opts.allowed.includes(hookInput.tool_name) || opts.mcpNames.some((n) => hookInput.tool_name.startsWith(`mcp__${n}__`));
                 // The sub-agent guard read the ORIGINAL input: a rewrite of a
@@ -628,7 +631,7 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
           toolName === "Bash"
             ? checkBash(String(input.command ?? ""))
             : isFilesystemTool(toolName)
-              ? checkPaths(toolName, input, { agentDir, workspaceRoot, libraryRoot })
+              ? checkPaths(toolName, input, { agentDir, workspaceRoot, libraryRoot, configWrites: opts.configWrites })
               : { ok: true as const };
         if (!verdict.ok) {
           refund();

package/src/store.ts

@@ -3533,6 +3533,14 @@ export interface StepRecord {
   /** On an isolated sub-agent's run: the workspace paths its sandbox's
    *  changes were applied to — what its delegating step is told it wrote. */
   wrote?: string[];
+  /** What this step's sandbox changed that was not taken back to the
+   *  workspace: configuration and code, which a step proposes and a person
+   *  applies (copy-back.ts, FOL-96). */
+  refused?: { path: string; kind: "config" | "code" }[];
+  /** What the host handed back into this step's sandbox mid-step — its
+   *  `sandbox: own` jobs' files, path → sha256 — recorded HERE, on the host,
+   *  so the copy-out never has to take the sandbox's word for it (FOL-96). */
+  handedBack?: Record<string, string | string[]>;
   /**
    * Sandbox seconds this step rented, and how many of them were cold start.
    * Set only on the isolated path — an in-process step rents nothing, so