@foldrun/core 0.5.0 → 0.7.0

package/src/step-exec.ts

@@ -329,6 +329,13 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
       // declares no tools gets none, instead of seeing the full Claude
       // Code toolset and burning turns on denied calls.
       tools: opts.allowed,
+      // Stated, never left to the SDK. Unset, it chose its own mode for the
+      // login it ran under, and in auto mode its classifier refused a granted
+      // script before canUseTool saw it: "denied by the Claude Code auto mode
+      // classifier. Reason: [Irreversible Local Destruction]" for backlink-
+      // desk's outreach_reset, which only marks old bodies STALE (2026-10-04
+      // and 05). The decision is ours: canUseTool and the PreToolUse hook.
+      permissionMode: "default",
       // Deliberately NOT allowedTools: listing them there auto-approves and
       // skips canUseTool entirely, which is where confinement happens. The
       // toolset is still restricted by `tools` above.
@@ -354,8 +361,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
@@ -630,11 +639,23 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
             ...(block.is_error ? { err: true } : {}),
             ...(open.subagent ? { subagent: open.subagent } : {}),
           });
+          // Why it failed, on the trail. The span above carried only `err`,
+          // so a refused call left the agent's own guess as the only account
+          // of it: backlink-desk's outreach_reset "denied by the permission
+          // classifier" (run-muufboma-2t6l, 2026-10-05) could not be checked.
+          if (block.is_error) {
+            const why = toolResultText(block.content).replace(/\s+/g, " ").trim().slice(0, 300);
+            if (why) emit("error", `${open.name}: ${why}`, { call: block.tool_use_id, ...(open.subagent ? { subagent: open.subagent } : {}) });
+          }
           readPod(block.tool_use_id);
         }
       }
     } else if (message.type === "result") {
       status = message.subtype === "success" ? "completed" : "failed";
+      // Calls the SDK itself refused, which canUseTool never saw.
+      for (const d of ("permission_denials" in message && Array.isArray(message.permission_denials) ? message.permission_denials : [])) {
+        emit("error", `refused before it ran: ${String((d as { tool_name?: unknown }).tool_name ?? "a tool")}`);
+      }
       if (message.subtype === "error_max_turns") {
         emit("error", `stopped after ${opts.maxTurns ?? "its"} turns (max_turns: in the flow file) — the step did not finish`);
       }
@@ -875,8 +896,8 @@ export async function checkVerify(
      *  and `matches:` test this, because it is also what the run's headline
      *  is read from: a reporter that narrated between tool calls ("Now let
      *  me write the report…") failed `matches: ^BAD\b` with a correct
-     *  headline while the check read every turn joined. `judge:` still grades
-     *  the whole result. */
+     *  headline while the check read every turn joined. `judge:` grades this
+     *  too, as "the reply", with the whole result beside it as the work. */
     conclusion?: string | null;
     data?: unknown;
     /** The step's own model environment, for `judge:` — it grades on the
@@ -939,7 +960,13 @@ export async function checkVerify(
       return { ok, headline: ok ? "present and non-empty" : `${value} is missing or empty`, detail: "" };
     }
     case "judge": {
-      const verdict = await judgeReply(value, output, ctx.modelEnv ?? {}, ctx.signal);
+      // The reply is the final turn, as everywhere else; every turn goes
+      // beside it as the work, so a claim about what the step did can still
+      // be checked. Both as one <reply> failed `judge: the reply opens with
+      // GOOD` on a reply that did (fix-desk, run-muwevg72-7mza): the joined
+      // text opened with the narration before it.
+      const reply = ctx.conclusion?.trim() ? ctx.conclusion : output;
+      const verdict = await judgeReply(value, reply, output, ctx.modelEnv ?? {}, ctx.signal);
       const ok = /^\s*PASS\b/i.test(verdict);
       return { ok, headline: ok ? "PASS" : "FAIL", detail: verdict.slice(0, 300) };
     }
@@ -952,9 +979,24 @@ export async function checkVerify(
  * Same shape as the eval judge, and answered with one word first so the
  * verdict is a prefix test rather than a reading.
  */
+export function judgePrompt(rubric: string, reply: string, work: string): string {
+  const shown = reply.slice(0, 20_000);
+  const context = work.trim() && work.trim() !== reply.trim()
+    ? `Everything the step wrote while working, for context. "The reply" means only the reply block below, ` +
+      `never this:\n<work>\n${work.slice(-20_000)}\n</work>\n\n`
+    : "";
+  return (
+    `You are grading a reply against one requirement. Answer with PASS or FAIL as the ` +
+    `first word, then one sentence of reason.\n\nRequirement: ${rubric}\n\n` +
+    context +
+    `<reply>\n${shown}\n</reply>`
+  );
+}
+
 async function judgeReply(
   rubric: string,
-  output: string,
+  reply: string,
+  work: string,
   env: Record<string, string | undefined>,
   signal?: AbortSignal,
 ): Promise<string> {
@@ -964,16 +1006,14 @@ async function judgeReply(
   signal?.addEventListener("abort", () => abortController.abort(), { once: true });
   try {
     const q = query({
-      prompt:
-        `You are grading a reply against one requirement. Answer with PASS or FAIL as the ` +
-        `first word, then one sentence of reason.\n\nRequirement: ${rubric}\n\n` +
-        `<reply>\n${output.slice(0, 40_000)}\n</reply>`,
+      prompt: judgePrompt(rubric, reply, work),
       options: {
         model: "haiku",
         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 +1083,28 @@ 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" };
+}
+
+/** The text of a tool result, whichever shape it came in: a string, or a
+ *  list of content blocks of which only the text ones say anything. */
+export function toolResultText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((b): b is { type: "text"; text: string } => !!b && (b as { type?: unknown }).type === "text" && typeof (b as { text?: unknown }).text === "string")
+    .map((b) => b.text)
+    .join(" ");
+}

package/src/storage.ts

@@ -839,6 +839,14 @@ export async function materializeFiles(tenant: string, workspace: string): Promi
   return brought;
 }
 
+/** path → sha of every stored file: what `storage/` holds once
+ *  materializeFiles has run. A run keeps it to tell its own writes from the
+ *  files it was handed. */
+export function storageBaseline(tenant: string, workspace: string): Record<string, string> {
+  if (!fileStoreEnabled()) return {};
+  return Object.fromEntries(readIndex(tenant, workspace).files.map((f) => [f.path, f.sha]));
+}
+
 /**
  * Take what the run left in `storage/` back into the store, stamped with the
  * run that wrote it.
@@ -851,6 +859,7 @@ export async function harvestFiles(
   tenant: string,
   workspace: string,
   by: string,
+  opts: { changedFrom?: Record<string, string> } = {},
 ): Promise<{ saved: string[]; errors: string[] }> {
   if (!fileStoreEnabled()) return { saved: [], errors: [] };
   adoptLegacyFilesDir(workspaceDir(tenant, workspace));
@@ -885,6 +894,10 @@ export async function harvestFiles(
         // Same size is not proof, so confirm by hash before skipping a write.
         if (sha256(fs.readFileSync(abs)) === previous.sha) continue;
       }
+      // Only what the run itself changed: a file still holding the bytes it
+      // was handed is not this run's work, and the index may have moved on
+      // since (an upload while the run was going) — that must win.
+      if (opts.changedFrom && opts.changedFrom[norm] === sha256(fs.readFileSync(abs))) continue;
       await putFileQuietly(tenant, workspace, norm, fs.readFileSync(abs), by);
       saved.push(norm);
     } catch (err) {

package/src/store.ts

@@ -20,6 +20,7 @@
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
 
+import { expandPlatformVars } from "./host-env.ts";
 import type { BrowserPodOutcome } from "./browser-pod.ts";
 import fs from "node:fs";
 import path from "node:path";
@@ -57,7 +58,7 @@ import {
 } from "./okf.ts";
 import { readTransport, KINDS } from "./kinds.ts";
 import { providerPreset, looksOpenAiShaped, PROTECTED_PARAMS, type WireFormat, type AuthShape } from "./providers.ts";
-import { starterFiles, accountFiles } from "./starter.ts";
+import { starterFiles, accountFiles, blankWorkspaceFiles } from "./starter.ts";
 import { trimSlashes, MAX_EDITABLE_FILE } from "./paths.ts";
 
 // Where workspaces live. The hosted app keeps many under data/; the CLI runs
@@ -317,6 +318,19 @@ export function assertCanonicalCase(rel: string) {
 // fire (trigger-log.ts). Before it was listed here every deploy erased it.
 export const PLATFORM_FILES = ["secrets.json", "hooks.json", "hook-deliveries.jsonl", ".repo.json", "trigger-log.jsonl"];
 
+// The agent engine's own home files. Each step's sandbox runs the Claude
+// Agent SDK — the engine, whatever model answers — with its home in the
+// agent's folder, and the engine writes its settings (.claude.json, its
+// backups), plugin caches and the full transcript of every session
+// (.claude/projects/*.jsonl) there. Nothing in foldrun reads them. Copied
+// back after every step, they had piled up to 5,274 files and 19 MB in one
+// agent's folder on the box by 6 Oct 2026, carried every past conversation
+// into every sandbox, and their clashing rewrites were the "write-back
+// conflict on .claude.json" lines (and the big merges) of that day. A
+// workspace's own .claude/agents/*.md — Claude Code subagents an author
+// writes, imported as agents — sits at the workspace root and is untouched.
+const ENGINE_HOME_RE = /^agents\/[^/]+\/\.claude([./]|$)/;
+
 /** True for anything the platform, not the author or the agent, writes. */
 export function isPlatformPath(rel: string): boolean {
   const norm = rel.replaceAll("\\", "/");
@@ -325,6 +339,7 @@ export function isPlatformPath(rel: string): boolean {
   // are the vault, as far as anything outside the platform is concerned.
   if (/(^|\/)secrets\.json\./.test(norm)) return true;
   if (norm === "trigger-log.jsonl.tmp") return true;
+  if (ENGINE_HOME_RE.test(norm)) return true;
   return norm === "runs" || norm.startsWith("runs/") || norm === ".foldrun" || norm.startsWith(".foldrun/");
 }
 
@@ -531,7 +546,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 +558,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
@@ -625,6 +640,27 @@ export function toolIsOutward(data: Record<string, unknown>): boolean {
   return data.outward === true;
 }
 
+/** How much of a tool.md body rides to the model with the tool. */
+export const TOOL_GUIDE_MAX = 6000;
+
+/**
+ * The prose under a tool.md's frontmatter: how to call it, what it refuses,
+ * what its output means. Only `description:` used to reach the model, so
+ * agents invented what the body documented (5 Oct 2026). The fenced program
+ * of a single-file tool is code, not guidance, and stays out.
+ */
+export function toolGuide(body: string | undefined, inlineProgram = false): string | undefined {
+  if (!body) return undefined;
+  let text = body.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+  // Only a single-file tool's program is cut; in a `run:` tool every fenced
+  // block is an example of a call, which is exactly what the model needs.
+  const inline = inlineProgram ? fencedCodeBlock(text) : null;
+  if (inline) text = text.slice(0, inline.start) + text.slice(inline.end);
+  text = text.trim();
+  if (!text) return undefined;
+  return text.length > TOOL_GUIDE_MAX ? `${text.slice(0, TOOL_GUIDE_MAX)}\n\n[the rest of tool.md is cut here]` : text;
+}
+
 export function parseToolDef(data: Record<string, unknown>, fallbackName: string, body?: string): ToolDef | null {
   const name = typeof data.name === "string" ? data.name : fallbackName;
   // `transport:`, or a legacy `type: http|script|mcp` from before `type:` meant
@@ -659,16 +695,24 @@ export function parseToolDef(data: Record<string, unknown>, fallbackName: string
     };
   }
   if (kind === "script") {
+    // `guide` is the body's, never the frontmatter's: an author's `guide:`
+    // would otherwise ride to the model in place of the manual.
+    if ("guide" in data) { data = { ...data }; delete data.guide; }
     // The program is a run: path, or the file's own fenced code block — the
     // single-file form, which is what lets a script tool read and edit like
     // every other markdown document.
-    if (typeof data.run === "string") return { kind: "script", name, spec: { ...data, name } };
+    if (typeof data.run === "string") {
+      const guide = toolGuide(body);
+      return { kind: "script", name, spec: { ...data, name, ...(guide ? { guide } : {}) } };
+    }
     const inline = body ? fencedCode(body) : null;
     if (!inline) return null;
-    return { kind: "script", name, spec: { ...data, name, code: inline.code, codeExt: inline.ext } };
+    const guide = toolGuide(body, true);
+    return { kind: "script", name, spec: { ...data, name, code: inline.code, codeExt: inline.ext, ...(guide ? { guide } : {}) } };
   }
   const [spec] = parseApis([{ ...data, name }]);
-  return spec ? { kind: "http", name, spec } : null;
+  const guide = toolGuide(body);
+  return spec ? { kind: "http", name, spec: guide ? { ...spec, guide } : spec } : null;
 }
 
 /**
@@ -864,6 +908,8 @@ export interface ApiSpec {
   name: string;
   base: string;
   description: string;
+  /** The tool.md body, for the model (see toolGuide). */
+  guide?: string;
   headers: Record<string, string>; // values may contain ${SECRET_NAME}
   query: Record<string, string>; // always-appended query params (e.g. api keys)
   methods: string[]; // allowed HTTP methods; default GET only
@@ -1136,7 +1182,9 @@ export function parseApis(raw: unknown): ApiSpec[] {
     out.push({
       name: name.replace(/[^a-zA-Z0-9_]/g, "_"),
       ...(Number(e.timeout) > 0 ? { timeout: Number(e.timeout) } : {}),
-      base: trimSlashes(base),
+      // `${FOLDRUN_API_URL}` and `${FOLDRUN_PUBLIC_URL}` are the install's own
+      // addresses, filled here on the host so a desk never names one.
+      base: trimSlashes(expandPlatformVars(base)),
       description: typeof e.description === "string" ? e.description : "",
       headers: asRecordLocal(e.headers),
       query: asRecordLocal(e.query),
@@ -2875,6 +2923,12 @@ export function setWorkspaceDescription(tenant: string, workspace: string, descr
  * this copy still said `type: Agent` after the CLI's had moved to `kind:`,
  * so every workspace made from the dashboard was born in the old format.
  */
+/** What the dashboard's "Create workspace" makes: blank (blankWorkspaceFiles),
+ *  minus the laptop-only files, for the same reason as templateFiles. */
+export function blankTemplateFiles(workspace: string): DeployFile[] {
+  return blankWorkspaceFiles(workspace).filter((f) => f.path === "AGENTS.md" || IN_WORKSPACE_DIR.test(f.path));
+}
+
 export function templateFiles(workspace: string): DeployFile[] {
   // The starter minus what only matters on a laptop's disk: .gitignore
   // guards a local clone's secrets, but the hosted store never keeps
@@ -3085,6 +3139,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
@@ -3384,7 +3442,23 @@ export function runOutputPath(
 
 export function readRun(tenant: string, workspace: string, runId: string): RunRecord | null {
   const p = runFilePath(tenant, workspace, runId);
-  return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : null;
+  // EFS/NFS: writeRun() replaces this file by rename, so an open()+read()
+  // here can land on the just-unlinked inode and come back ESTALE (errno
+  // -116, surfaced by Node as "Unknown system error -116", syscall read).
+  // That isn't corruption — the next open() by path sees the committed new
+  // inode — so re-read a few times on ESTALE and rethrow anything else.
+  // (On dev-aws this surfaced as a CLI `--wait` call returning HTTP 500
+  // from waitForRun's poll while the run itself completed fine.)
+  const attempts = 5;
+  for (let i = 1; ; i++) {
+    try {
+      return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : null;
+    } catch (e) {
+      const err = e as NodeJS.ErrnoException;
+      if ((err.code === "ESTALE" || err.errno === -116) && i < attempts) continue;
+      throw e;
+    }
+  }
 }
 
 export function writeRun(tenant: string, workspace: string, run: RunRecord) {
@@ -3702,6 +3776,12 @@ export function runCost(run: RunRecord): number {
  * fan-out template is a row in the trace rather than work — billing any of
  * them would charge for steps the customer can see never executed, which is
  * the fastest way to lose an argument about an invoice.
+ *
+ * Tokens count only for steps that ran on the platform's own model
+ * credential. A step on the account's own key (`credential` "provider: …" —
+ * a provider: block, or Settings → Model) was paid for at the provider, and
+ * billing it again here charged a BYOK customer twice. And a carried step's
+ * tokens were billed where it ran, like its compute.
  */
 export function runMeter(run: RunRecord): {
   tokenCostUsd: number;
@@ -3716,17 +3796,19 @@ export function runMeter(run: RunRecord): {
   let computeSecs = 0;
   let smallSecs = 0;
   let netBytes = 0;
+  let tokenCostUsd = 0;
   for (const s of run.steps) {
     if (s.status !== "completed" && s.status !== "failed") continue;
     // A carried step ran — and was billed — in the run it was carried from.
     if (s.carriedFrom) continue;
     steps += 1;
+    if (!(s.credential ?? "").startsWith("provider:")) tokenCostUsd += s.costUsd ?? 0;
     const secs = s.computeSecs ?? 0;
     computeSecs += secs;
     if (s.size === "small") smallSecs += secs;
     netBytes += (s.actual?.rxBytes ?? 0) + (s.actual?.txBytes ?? 0);
   }
-  return { tokenCostUsd: runCost(run), steps, computeSecs, smallSecs, netBytes };
+  return { tokenCostUsd, steps, computeSecs, smallSecs, netBytes };
 }
 
 /**

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/src/tool-names.ts

@@ -49,8 +49,10 @@ export const BUILTIN_TOOLS = new Set([
   "NotebookEdit", "TodoWrite",
 ]);
 
-/** The platform's own groups, served in-process rather than by the SDK. */
-export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask"]);
+/** The platform's own groups, served in-process rather than by the SDK.
+ *  `install` is granted to every agent anyway (install-tool.ts); naming it is
+ *  accepted so a file that says so is not flagged. */
+export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask", "install"]);
 
 /** Would this name resolve to something the runtime provides? Built-ins win a
  *  clash, so a tool file of the same name is shadowed rather than granted. */

package/src/tool-test.ts

@@ -277,7 +277,14 @@ export async function testTool(
       });
     }
 
-    const names = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+    // The tool's own secrets, and the calling agent's `secrets:` — a run
+    // hands a script both. Testing gbp_read (whose agent, not the tool,
+    // declares GBP_OAUTH) said "GBP_OAUTH is not set" while every run of the
+    // same call worked (9 Oct 2026). Only an agent that grants the tool: the
+    // agents[0] stand-in above is there for its depth, not its keys.
+    const own = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+    const granting = caller && caller.ownTools.includes(def.name) ? caller.secrets : [];
+    const names = [...new Set([...own, ...granting])];
     const { env: stored, missing } = resolveSecrets(tenant, names, workspace);
     const live = await liveSecrets(stored, { tenant, workspace });
     if ("error" in live) {