@foldrun/core 0.5.0 → 0.6.0

package/src/runner.ts

@@ -15,12 +15,13 @@ import { browserPodLine, podLossDecision, RERAN_ON_FULL } from "./browser-pod.ts
 import { eventUrl } from "./webhook.ts";
 import { runStepInContainer, sizeLimits, killRunSandboxes, type StepTiming } from "./run-container.ts";
 import { hostSafeEnv } from "./host-env.ts";
+import { resolveModelCredential, credentialLine } from "./model-credential.ts";
 import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-schema.ts";
 import { EGRESS_ENV, MODEL_KEY_NAME, addGrant, hostOf, placeholderNames, proxyModelEnv, unsubstitute, type EgressGrant } from "./egress.ts";
 import { explainRefusal, isRefusalStatus, refusalFromLine, supplyNote, type SupplyState } from "./refusal.ts";
 import { platform } from "./platform.ts";
 import { healthKey } from "./secret-health.ts";
-import { TEST_WRITES_DIR, restoreDivertedDirs, snapshotDivertedDirs, testHeadline, testModeEnv, withholdSecrets } from "./test-mode.ts";
+import { TEST_WRITES_DIR, overlayTestWrites, restoreDivertedDirs, snapshotDivertedDirs, testHeadline, testModeEnv, withholdSecrets } from "./test-mode.ts";
 
 /** Does this process run steps in a sandbox — the container core ships, or
  *  one the platform registered (a pod)? */
@@ -85,7 +86,7 @@ import { attachOperations, prefetchOpenApi } from "./openapi.ts";
 import { buildSearchTools, buildHistoryTools, buildDeskTools, digestRuns, type SearchRoot, type RunDigest } from "./context-tools.ts";
 import { startTranslator, translatorSpecFor, type TranslatorSpec } from "./translator.ts";
 import { providerPreset } from "./providers.ts";
-import { buildScriptTools, parseScripts, type ExecutionContext } from "./script-tools.ts";
+import { buildScriptTools, parseScripts, type ExecutionContext, type ScriptSpec } from "./script-tools.ts";
 import { libraryDir, libraryTools, libraryMemoryIndex } from "./library.ts";
 import { fingerprint, mergeRuntimes, parseRuntime, prepareRuntime, type PreparedRuntime, type RuntimeSpec } from "./runtime.ts";
 import { materializeFiles, harvestFiles } from "./storage.ts";
@@ -760,8 +761,7 @@ function agentContext(
       `\`${workspace}\` workspace. Every path in this prompt is relative to it — ` +
       `\`outputs/\` is yours, and \`workspace/\` is the workspace root, in every tool ` +
       `and in the shell: the shared file store is \`workspace/storage/\`, what runs ` +
-      `carry forward is \`workspace/state/\`. (\`../../\` reaches the same root and ` +
-      `still works, so a path like \`../../knowledge/\` below is \`workspace/knowledge/\`.) ` +
+      `carry forward is \`workspace/state/\`, its knowledge \`workspace/knowledge/\`. ` +
       `Absolute paths are outside the workspace and will be refused.\n\n` +
       // A flow's whole point is that a later step works on what an earlier one
       // produced, and each agent writes to its own outputs/. A run showed what
@@ -812,24 +812,7 @@ function agentContext(
   // skills for a few tokens each.
   // Own skills, then the workspace's, then the workspace library — nearest
   // definition of a name wins, so a team default can be overridden locally.
-  const skills: DiscoveredSkill[] = [];
-  const seenSkills = new Set<string>();
-  const addSkills = (dir: string, prefix: string, subdir = "skills") => {
-    for (const skill of discoverSkills(dir, subdir)) {
-      if (seenSkills.has(skill.name)) continue;
-      seenSkills.add(skill.name);
-      skills.push({ ...skill, path: `${prefix}${skill.path}`, dir: skill.dir ? `${prefix}${skill.dir}` : null });
-    }
-  };
-  const workspaceRoot = path.join(agentDir, "..", "..");
-  addSkills(agentDir, "");
-  addSkills(workspaceRoot, "../../"); // the workspace's skills/
-  // The cross-client convention: skills any skills-compatible tool installs
-  // under .agents/skills/ are visible here too, and vice versa. Scanned after
-  // the native location so a foldrun-native skill wins a name clash, but both
-  // are discovered. project scope only — foldrun workspaces are self-contained.
-  addSkills(workspaceRoot, "../../", ".agents/skills");
-  addSkills(path.join(libraryDir(tenant)), "../../../../library/"); // the account library
+  const skills = skillsInScope(agentDir, tenant);
 
   // A skill with `when:` only loads when the run carries a matching tag —
   // so an agent with 119 skills costs 119 lines of context only when every
@@ -919,7 +902,7 @@ function agentContext(
   };
 
   const own = listDir(path.join(agentDir, "scripts"), "scripts/");
-  const shared = listDir(path.join(agentDir, "..", "..", "scripts"), "../../scripts/");
+  const shared = listDir(path.join(agentDir, "..", "..", "scripts"), "workspace/scripts/");
   // The library's path depends on where this run executes: isolated runs see
   // it at /library, host runs at its real location. Printing the host path
   // into a container's prompt handed the model files it could never open.
@@ -1237,17 +1220,18 @@ function agentContext(
   let runtime: PreparedRuntime = { interpreters: {}, env: {}, log: [], error: null };
 
   if (executor === "docker" && !grantsOnly) {
-    const image = ensureImage(runtimeSpec);
+    // The script image also carries what the scripts' own languages need: a
+    // .mjs tool with no runtime: block still needs node in its container.
+    // Here only — the run container and the host have node already, and a
+    // spec there sets off the runtime build for nothing.
+    const image = ensureImage(mergeRuntimes(runtimeSpec, scriptLanguages(scriptSpecs)));
     runtimeLog.push(...image.log);
     runtimeError = image.error;
     if (!image.error) {
       exec = {
         executor: "docker",
         image: image.tag,
-        mounts: {
-          [path.resolve(agentDir, "..", "..", "scripts")]: "/workspace-scripts",
-          [libraryDir(tenant, "scripts")]: "/library-scripts",
-        },
+        mounts: scriptMounts(agentDir, tenant),
         // Only agents that granted something reaching out — an `apis:` entry
         // or one of their own tools — get egress.
         network: parseApis(front.apis).length > 0 || ownToolNames(front).length > 0,
@@ -1506,8 +1490,8 @@ function agentContext(
     ? [
         { label: "knowledge/", dir: path.join(agentDir, "knowledge") },
         { label: "memory/", dir: path.join(agentDir, "memory") },
-        { label: "../../knowledge/", dir: path.join(wsRoot, "knowledge") },
-        { label: "../../memory/", dir: path.join(wsRoot, "memory") },
+        { label: "workspace/knowledge/", dir: path.join(wsRoot, "knowledge") },
+        { label: "workspace/memory/", dir: path.join(wsRoot, "memory") },
         { label: "workspace/state/", dir: path.join(wsRoot, "state") },
         { label: `workspace/${STORAGE_DIR}/`, dir: path.join(wsRoot, STORAGE_DIR) },
         { label: "outputs/", dir: path.join(agentDir, "outputs") },
@@ -1969,6 +1953,16 @@ async function runStep(
     // And one more only when something written could not be read as a zone.
     for (const problem of clock.problems) push("error", problem);
     if (providerLabel) push("info", `provider: ${providerLabel}`);
+    // Which credential the model is called with, on the record: an agent
+    // that names a provider uses its own; otherwise the platform's (in a
+    // run container) or this process's — never a login that just happens
+    // to be on the machine (model-credential.ts).
+    const credential = providerLabel ? null : resolveModelCredential(isolatedRun() ? platformModelEnv() : process.env);
+    step.credential = credential ? credential.label : `provider: ${providerLabel}`;
+    if (credential) {
+      const line = credentialLine(credential);
+      push(line.type, line.text);
+    }
     for (const w of providerWarnings) push("error", w);
     // A level that wrote a language nobody can read was skipped, not obeyed.
     for (const l of language.lines) push("info", l);
@@ -2617,9 +2611,13 @@ async function runStep(
           };
           const again = { ...lastArgs, input: { ...lastArgs.input, image: "full" as const }, resume: null };
           await lease?.commit();
-          outcome = await runTracked(again);
-          step.image = outcome.image ?? { variant: "full", why: "re-run after the browser pod was lost" };
+          // Before the call, not after: a re-run that throws (the full
+          // sandbox never started) is still the full go on the record — its
+          // failed row read "slim" when this was set only on success.
+          step.image = { variant: "full", why: "re-run after the browser pod was lost" };
           step.browserPod = { ...first.browserPod!, fallback: RERAN_ON_FULL };
+          outcome = await runTracked(again);
+          step.image = outcome.image ?? step.image;
         } else {
           push("error", decision.message);
           step.browserPod = { ...outcome.browserPod, failure: decision.message };
@@ -2692,9 +2690,13 @@ async function runStep(
         push("info", `test: ${name} withheld from scripts — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from scripts` } });
       }
       const stepSecrets = held.env;
+      // The model credential for this machine's Claude Code — the agent's
+      // own provider when it names one. The host allowlist drops it, so
+      // without this every in-process step ran on the machine's login.
+      const localModelEnv: Record<string, string> = Object.keys(providerEnv).length ? providerEnv : resolveModelCredential().env;
       const consultTools = buildConsultTools(
         consults,
-        { ...hostSafeEnv(), ...stepSecrets, ...providerEnv },
+        { ...hostSafeEnv(), ...stepSecrets, ...localModelEnv },
         (type, text) => push(type, text),
       );
       // On this machine nobody can write in and there is no proxy: the
@@ -2763,6 +2765,10 @@ async function runStep(
       // under the run and the originals come back.
       const attemptThrough = async (modelEnv: Record<string, string | undefined>, spec: TranslatorSpec | null) => {
         const before = testRun ? snapshotDivertedDirs(workspaceRoot) : null;
+        // What earlier steps of this test run wrote, laid over the real files
+        // for this attempt; restoreDivertedDirs puts the originals back.
+        const handed =
+          before && runId && overlayTestWrites(workspaceRoot, divertFor(runId).to).length ? snapshotDivertedDirs(workspaceRoot) : before;
         const t = spec ? await startTranslator(spec) : null;
         try {
           return await attemptInProcess(t ? { ...modelEnv, ...t.env } : modelEnv);
@@ -2773,12 +2779,12 @@ async function runStep(
           }
           if (before && runId) {
             const d = divertFor(runId);
-            restoreDivertedDirs(workspaceRoot, before, d.to, d.note);
+            restoreDivertedDirs(workspaceRoot, before, d.to, d.note, handed ?? before);
           }
         }
       };
       let credentialUsed = platformModelCredential();
-      let outcome = await attemptThrough(providerEnv, translator);
+      let outcome = await attemptThrough(localModelEnv, translator);
       // Same rule as the isolated path: a credential that rotated under the
       // step is waited out and retried before anything else is considered.
       if (outcome.status === "failed" && isAuthRefusal(lastRefusal)) {
@@ -2788,7 +2794,7 @@ async function runStep(
           push("info", "the credential rotated under this step; retrying on the new one");
           credentialUsed = rotated;
           lastRefusal = "";
-          outcome = await attemptThrough(providerEnv, translator);
+          outcome = await attemptThrough(localModelEnv, translator);
         } else {
           push("info", "the credential did not change — this is the key itself, not a rotation");
         }
@@ -2800,7 +2806,7 @@ async function runStep(
         push("info", `provider busy (${lastRefusal.slice(0, 60)}) — waiting ${(wait / 1000).toFixed(1)}s, attempt ${n} of ${OVERLOAD_RETRIES}`);
         await sleep(wait);
         lastRefusal = "";
-        outcome = await attemptThrough(providerEnv, translator);
+        outcome = await attemptThrough(localModelEnv, translator);
       }
       // Same rule as the isolated path: one retry, on a refusal, on the
       // declared or platform second supply.
@@ -4824,3 +4830,82 @@ export function runResult(run: RunRecord): string | null {
   }
   return null;
 }
+
+/**
+ * What a Docker-run script sees of the workspace and the account: their
+ * scripts/ and their tools/, read-only. A folder tool's code lives in its
+ * tools/<name>/ folder, not in scripts/ — without those two mounts every
+ * folder tool (the hello template's wordcount among them) was handed a host
+ * path the container did not have, and failed on every call. A gallery tool
+ * nobody installed runs from the gallery's own shelf, so that is mounted too
+ * when there is one. A folder that does not exist is skipped by the copy.
+ */
+export function scriptMounts(agentDir: string, tenant: string): Record<string, string> {
+  const workspaceRoot = path.resolve(agentDir, "..", "..");
+  const mounts: Record<string, string> = {
+    [path.join(workspaceRoot, "scripts")]: "/workspace-scripts",
+    [path.join(workspaceRoot, "tools")]: "/workspace-tools",
+    [libraryDir(tenant, "scripts")]: "/library-scripts",
+    [libraryDir(tenant, "tools")]: "/library-tools",
+  };
+  const gallery = platform.galleryDir();
+  if (gallery) mounts[path.join(gallery, "tools")] = "/gallery-tools";
+  return mounts;
+}
+
+/**
+ * The skills an agent can see, nearest first, each with the path the agent
+ * is told to read it at. Own skills, then the workspace's, then the
+ * workspace's `.agents/skills/` (the cross-client convention, scanned after
+ * the native location so a foldrun-native skill wins a name clash), then the
+ * account library. The nearest definition of a name wins.
+ *
+ * The workspace's are written `workspace/skills/…`, the one spelling for the
+ * workspace root, which the file tools expand themselves. `../../skills/…`
+ * left the model to resolve it against a path it had to guess, and on the
+ * hello template it climbed one level too far and was refused.
+ */
+export function skillsInScope(agentDir: string, tenant: string): DiscoveredSkill[] {
+  const skills: DiscoveredSkill[] = [];
+  const seen = new Set<string>();
+  const add = (dir: string, prefix: string, subdir = "skills") => {
+    for (const skill of discoverSkills(dir, subdir)) {
+      if (seen.has(skill.name)) continue;
+      seen.add(skill.name);
+      skills.push({ ...skill, path: `${prefix}${skill.path}`, dir: skill.dir ? `${prefix}${skill.dir}` : null });
+    }
+  };
+  const workspaceRoot = path.join(agentDir, "..", "..");
+  add(agentDir, "");
+  add(workspaceRoot, "workspace/");
+  add(workspaceRoot, "workspace/", ".agents/skills");
+  // The account library keeps its relative path: `account/` is expanded by
+  // the file tools only, and a skill's bundled scripts are run from the shell.
+  add(path.join(libraryDir(tenant)), "../../../../library/");
+  return skills;
+}
+
+/**
+ * The interpreters a set of scripts needs, read from what they are: the
+ * extension of `run:` (or of inline code), or an explicit `interpreter:`.
+ * Docker's script image is built from the runtime spec, and the base one is
+ * Python only, so a JavaScript tool that declared no `runtime:` (the demo's
+ * inline crm-upload, any folder tool's run.mjs) failed with no node to run
+ * it. Python is named too whenever a .py script is present, because asking
+ * for node alone builds on node:22-slim, which has no python3. Null when
+ * nothing beyond the default is needed.
+ */
+export function scriptLanguages(scripts: ScriptSpec[]): RuntimeSpec | null {
+  const kind = (sc: ScriptSpec) => {
+    const via = (sc.interpreter ?? "").split(/[\\/]/).pop() ?? "";
+    if (/^node/.test(via)) return "node";
+    if (/^python/.test(via)) return "python";
+    const ext = (sc.run ? path.extname(sc.run) : sc.codeExt ?? "").toLowerCase();
+    if ([".js", ".mjs", ".cjs", ".ts"].includes(ext)) return "node";
+    if (ext === ".py") return "python";
+    return null;
+  };
+  const kinds = new Set(scripts.map(kind));
+  if (!kinds.has("node")) return null;
+  return { node: true, ...(kinds.has("python") ? { python: true } : {}), packages: [], npm: [] };
+}

package/src/script-tools.ts

@@ -234,12 +234,16 @@ export function runScript(
     // Container path: same command, executed inside an isolated container
     // with only the agent's directory (plus declared shared dirs) mounted.
     if (exec && exec.executor === "docker") {
+      // `workspace/…` is the workspace root on the host (the step's link)
+      // and in a run container; here there is no link, so each such
+      // argument is staged: copied in, pointed at, and copied back after.
+      const workspaceRoot = path.resolve(cwd, "..", "..");
+      const staged: { host: string; container: string }[] = [];
       const inContainer = (p: string) => {
-        if (p.startsWith(path.resolve(cwd))) return p.replace(path.resolve(cwd), "/workspace");
-        for (const [host, mount] of Object.entries(exec.mounts)) {
-          if (p.startsWith(host)) return p.replace(host, mount);
-        }
-        return p;
+        const w = stageWorkspaceArg(p, workspaceRoot);
+        if (!w) return containerPath(p, cwd, exec.mounts);
+        if (!staged.some((s) => s.host === w.host)) staged.push(w);
+        return w.container;
       };
       const argv = [
         // The interpreter inside the image, not the host's venv path.
@@ -251,6 +255,7 @@ export function runScript(
       runInContainer({
         agentDir: path.resolve(cwd),
         readOnly: exec.mounts,
+        staged,
         image: exec.image,
         argv,
         env,
@@ -292,6 +297,39 @@ export function runScript(
   });
 }
 
+/**
+ * A host path as the script's container sees it: under the agent's own
+ * directory it is /workspace, under a mounted folder it is that mount, and
+ * anything else (an argument that only looks like a path) is left alone.
+ * Containment, not a text prefix: `<ws>/scripts-old/x.py` is not under
+ * `<ws>/scripts`. The longest mount wins, so a nested one is not shadowed.
+ */
+export function containerPath(p: string, agentDir: string, mounts: Record<string, string>): string {
+  if (!path.isAbsolute(p)) return p;
+  const under = (root: string) => {
+    const rel = path.relative(root, p);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel)) ? rel : null;
+  };
+  const own = under(path.resolve(agentDir));
+  if (own !== null) return path.posix.join("/workspace", own.split(path.sep).join("/"));
+  const hit = Object.entries(mounts)
+    .map(([host, mount]) => ({ mount, rel: under(path.resolve(host)), len: host.length }))
+    .filter((m) => m.rel !== null)
+    .sort((a, b) => b.len - a.len)[0];
+  return hit ? path.posix.join(hit.mount, hit.rel!.split(path.sep).join("/")) : p;
+}
+
+/** Where a `workspace/…` script argument is staged in a script container,
+ *  or null when it is not one (or climbs out of the workspace). */
+export function stageWorkspaceArg(arg: string, workspaceRoot: string): { host: string; container: string } | null {
+  if (arg !== "workspace" && !arg.startsWith("workspace/")) return null;
+  const rel = arg.slice("workspace".length).replace(/^\/+/, "");
+  const host = path.resolve(workspaceRoot, rel);
+  const within = path.relative(workspaceRoot, host);
+  if (within.startsWith("..") || path.isAbsolute(within)) return null;
+  return { host, container: path.posix.join("/workspace-root", within.split(path.sep).join("/")) };
+}
+
 export interface ExecutionContext {
   /** "docker" nests each script in its own container; "sandbox" spawns it
    *  directly inside the isolation the step already has. */

package/src/step-exec.ts

@@ -354,8 +354,10 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
       // With sub-agents, the SDK would also offer its built-in ones
       // (general-purpose has every tool the session has). Only the declared
       // ones may run; the guard in the hook below refuses the rest as well.
-      env: subagents ? { ...(opts.env ?? process.env), CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS: "1" } : opts.env,
+      env: sdkEnv(opts.env, subagents ? { CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS: "1" } : {}),
       mcpServers: opts.mcpServers,
+      // Only the servers foldrun passes. See sdkEnv for the claude.ai half.
+      strictMcpConfig: true,
       // canUseTool is only asked when the SDK wants permission, and it never
       // asks for a read inside the cwd — so `Read workspace/storage/x` went
       // to `<agentDir>/workspace/storage/x` unchecked and unrewritten. On
@@ -973,7 +975,8 @@ async function judgeReply(
         systemPrompt: "You grade text against a stated requirement. Be strict and literal.",
         tools: [],
         settingSources: [],
-        env,
+        env: sdkEnv(env),
+        strictMcpConfig: true,
         maxTurns: 1,
         abortController,
       },
@@ -1043,3 +1046,17 @@ function runVerify(
     child.on("close", (code) => resolve({ code, out }));
   });
 }
+
+/**
+ * The environment an Agent SDK session starts with: the step's, minus the
+ * connectors of whoever is signed in to claude.ai on this machine. Claude
+ * Code loads an account's claude.ai MCP servers (Docs, Drive, …) unless told
+ * not to, and `settingSources: []` does not reach them — they come with the
+ * login, not from a settings file. A local `foldrun run` handed every agent
+ * the person's own connectors: the hello template's agents reported that
+ * "the only tools I have are the Claude Docs ones". `strictMcpConfig` keeps
+ * the rest of the on-disk MCP configuration out; this keeps the account's.
+ */
+export function sdkEnv(base: Record<string, string | undefined> | undefined, extra: Record<string, string> = {}): Record<string, string | undefined> {
+  return { ...(base ?? process.env), ...extra, ENABLE_CLAUDEAI_MCP_SERVERS: "false" };
+}

package/src/store.ts

@@ -531,7 +531,7 @@ export function buildMemoryIndex(dir: string, prefix = ""): string | null {
 // Workspace-scoped shared assets: skills/, memory/, tools/ sit beside agents/
 // and are available to every agent in that workspace.
 export function workspaceMemoryIndex(tenant: string, workspace: string): string | null {
-  return buildMemoryIndex(path.join(workspaceDir(tenant, workspace), "memory"), "../../memory/");
+  return buildMemoryIndex(path.join(workspaceDir(tenant, workspace), "memory"), "workspace/memory/");
 }
 
 // Knowledge is what you *gave* an agent — stable reference material an agent
@@ -543,7 +543,7 @@ export function knowledgeIndex(dir: string, prefix = ""): string | null {
 }
 
 export function workspaceKnowledgeIndex(tenant: string, workspace: string): string | null {
-  return knowledgeIndex(path.join(workspaceDir(tenant, workspace), "knowledge"), "../../knowledge/");
+  return knowledgeIndex(path.join(workspaceDir(tenant, workspace), "knowledge"), "workspace/knowledge/");
 }
 
 // One noun for capability. A tools/<name>.md file declares either an HTTP
@@ -3085,6 +3085,10 @@ export interface StepRecord {
    *  through the account's browser pod. The last attempt's; absent where
    *  the executor has one image (docker, in-process). */
   image?: { variant: "full" | "slim"; why?: string; pod?: boolean } | null;
+  /** Which model credential the step ran on, by its variable — "API key
+   *  (ANTHROPIC_API_KEY)", "Claude login token (CLAUDE_CODE_OAUTH_TOKEN)",
+   *  "provider: …" — or "none set" (model-credential.ts). */
+  credential?: string;
   /** Slim browsing through the account's pod (browser-pod.ts): reconnect
    *  tries and how many got through; when the pod was lost, why and what
    *  the step had written by then; and what happened — `fallback` (the

package/src/subagents.ts

@@ -97,7 +97,7 @@ export function subagentPrompt(o: {
     `# Where you are\n\n` +
       `You are ${o.name}, a sub-agent started by ${o.parent} to do one job and report back. ` +
       `You work in ${o.parent}'s directory, \`agents/${o.parent}/\` in the \`${o.workspace}\` workspace: ` +
-      `\`../../\` is the workspace root, its knowledge is at \`../../knowledge/\`, and absolute paths are refused. ` +
+      `\`workspace/\` is the workspace root, its knowledge is at \`workspace/knowledge/\`, and absolute paths are refused. ` +
       `You have only the tools listed for you. When the job is done, reply with what you found or made — ` +
       `your reply is all ${o.parent} sees of your work, so put the facts and file paths in it.`,
     ...(o.shared?.trim() ? [o.shared.trim()] : []),

package/src/test-mode.ts

@@ -18,7 +18,9 @@
 //     a test run; the env var says TEST_MODE_WITHHELD instead, so a script
 //     that forgot to check fails at the provider with an auth error
 //   - the write-back: state/ and storage/ go INTO the sandbox as usual and
-//     come out into runs/<id>/test-writes/ instead of the real directories
+//     come out into runs/<id>/test-writes/ instead of the real directories;
+//     the next step's copy has those writes laid over it (overlayTestWrites),
+//     so the run reads its own work and the workspace never sees it
 //
 // Nothing here weakens a live run: every function is a no-op unless the run
 // says `test: true`.
@@ -270,25 +272,32 @@ export function snapshotDivertedDirs(wsRoot: string): Map<string, Buffer> {
 
 /** Undo a step's writes to the diverted directories, keeping each changed
  *  or new file under `to` by its workspace-relative path. Deletions are
- *  undone too — the original is put back. Returns what was set aside. */
+ *  undone too — the original is put back. `handed` is what the step was
+ *  given when that was more than the workspace (the run's earlier test
+ *  writes, laid over it): only what the step changed from THAT is its
+ *  write. Returns what was set aside. */
 export function restoreDivertedDirs(
   wsRoot: string,
   before: Map<string, Buffer>,
   to: string,
   note: (rel: string, summary: string) => void,
+  handed: Map<string, Buffer> = before,
 ): string[] {
   const now = snapshotDivertedDirs(wsRoot);
   const aside: string[] = [];
   for (const [rel, next] of now) {
-    const was = before.get(rel) ?? null;
-    if (was && was.equals(next)) continue;
-    const dest = path.join(to, rel);
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.writeFileSync(dest, next);
-    aside.push(rel);
-    note(rel, divertedSummary(rel, was, next));
-    if (was) fs.writeFileSync(path.join(wsRoot, rel), was);
-    else fs.rmSync(path.join(wsRoot, rel), { force: true });
+    const given = handed.get(rel) ?? null;
+    if (!(given && given.equals(next))) {
+      const dest = path.join(to, rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, next);
+      aside.push(rel);
+      note(rel, divertedSummary(rel, before.get(rel) ?? null, next));
+    }
+    const orig = before.get(rel);
+    if (orig) {
+      if (!orig.equals(next)) fs.writeFileSync(path.join(wsRoot, rel), orig);
+    } else fs.rmSync(path.join(wsRoot, rel), { force: true });
   }
   for (const [rel, was] of before) {
     if (now.has(rel)) continue;
@@ -300,6 +309,37 @@ export function restoreDivertedDirs(
   return aside;
 }
 
+/**
+ * A test run's later steps see what its earlier steps wrote. Those writes
+ * are kept under runs/<id>/test-writes/, never on the workspace, so each
+ * step's copy of the workspace gets them laid over it — otherwise a step
+ * reads the real files, and a flow that hands work on through storage/
+ * tests something no live run does: on 2026-10-03 a strata-desk test run's
+ * compiler wrote today's PASS report, and the mailer was handed the
+ * morning's FAIL one and refused. Times are kept, so a verify that asks
+ * whether a file is fresh answers for the step that wrote it. Returns the
+ * workspace-relative paths laid over.
+ */
+export function overlayTestWrites(wsCopy: string, from: string): string[] {
+  const laid: string[] = [];
+  for (const dir of TEST_DIVERTED_DIRS) {
+    const root = path.join(from, dir);
+    if (!fs.existsSync(root)) continue;
+    for (const entry of fs.readdirSync(root, { recursive: true, withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const abs = path.join(entry.parentPath, entry.name);
+      const rel = path.relative(from, abs).replaceAll("\\", "/");
+      const dest = path.join(wsCopy, rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(abs, dest);
+      const st = fs.statSync(abs);
+      fs.utimesSync(dest, st.atime, st.mtime);
+      laid.push(rel);
+    }
+  }
+  return laid;
+}
+
 /** `[test] ` in front of a headline, once. */
 export function testHeadline(summary: string): string {
   return summary.startsWith("[test]") ? summary : `[test] ${summary}`;

package/templates/blog-desk/agents/writer/agent.md

@@ -2,7 +2,7 @@
 name: writer
 description: Turns a brief into a short draft.
 tools:
-  - files
+  - write
 ---
 
 Write a short draft from the brief you were given. Save it to outputs/draft.md.

package/templates/hello/agents/curator/agent.md

@@ -3,12 +3,12 @@ name: curator
 description: Reviews what the workspace has remembered — stale, duplicated or contradicting facts — and tidies memory without inventing anything.
 model: default
 tools:
-  - files
+  - write
   - search
   - history
 ---
 
-You look after this workspace's memory: the files under `../../memory/` and
+You look after this workspace's memory: the files under `workspace/memory/` and
 under each agent's `memory/`. Agents write there one fact per file, and nobody
 prunes it, so over months it gains duplicates, facts that later runs
 contradicted, and notes that stopped being true.
@@ -27,6 +27,6 @@ Do exactly this:
      move it to `workspace/state/` if it is still useful, else delete it.
    - Anything you are not sure about: leave it, and list it in your report.
 3. Never write a fact you did not find in a file or a run. Never touch
-   `knowledge/` — that is what people gave the agents, and it is theirs.
+   `workspace/knowledge/` — that is what people gave the agents, and it is theirs.
 4. Reply with a one-line headline (how many files reviewed, merged, corrected,
    removed), then the list of what you changed and what you left for a person.

package/templates/hello/agents/notetaker/agent.md

@@ -3,7 +3,7 @@ name: notetaker
 description: Reads the house style, writes one short note, checks its length, and records what it learned.
 model: fast
 tools:
-  - files
+  - write
   - wordcount
 ---
 
@@ -16,7 +16,7 @@ Do exactly this, in order:
 2. Draft two sentences about rain gauges, then call the `wordcount` tool on
    your draft. If it reports more than 2 sentences, cut it down and check
    again. Save the final text to `outputs/note.md`.
-3. Write one thing you learned to `../../memory/` as a new file — one fact,
+3. Write one thing you learned to `workspace/memory/` as a new file — one fact,
    plain markdown, a sentence or two. The platform records who wrote it.
 4. Update `workspace/state/publishing.md`: increase the note count by one and set
    the last topic to what you wrote about. Keep it as markdown.