@foldrun/core 0.5.0 → 0.7.0

package/dist/src/starter.js

@@ -40,6 +40,10 @@ foldrun_version: "0.1"
 # that declares the same key replaces it *whole* — base_url and token never
 # merge across scopes, so a provider block belongs entirely at one level.
 #
+# Your own model key needs no block: Settings → Model provider, or
+# \`foldrun account model set anthropic --key …\` (an API key, not a login).
+# A provider: block here or lower wins over it.
+#
 # provider:
 #   base_url: https://openrouter.ai/api
 #   token: \${OPENROUTER_API_KEY}
@@ -326,13 +330,14 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/runs/<id>/message\` | POST | tell a running step something; \`step\` picks one of a parallel group |
 | \`/flows\` · \`/flows/<f>\` | GET POST · POST DELETE PATCH | list, create, edit |
 | \`/flows/<f>/run\` | POST | start a flow |
-| \`/agents\` · \`/agents/<a>/run\` | GET POST · POST | list agents, run one |
+| \`/agents\` · \`/agents/<a>/run\` · \`/agents/import\` | GET POST · POST · GET POST | list agents, run one, copy one in from another workspace |
 | \`/evals\` · \`/evals/<e>/run\` | GET POST · POST | list evals, run one |
 | \`/tools/<t>/test\` | POST | exercise one tool alone |
 | \`/storage\` · \`/storage/download\` · \`/storage/upload-url\` · \`/storage/preview\` | GET POST PUT DELETE · GET · POST · GET | workspace files, any type; \`preview\` returns one parsed for reading |
 | \`/assets\` | POST | upload an asset |
 | \`/hooks/<f>/rotate\` | POST | new webhook token for a flow |
 | \`/notify/deliveries\` · \`/notify/deliveries/<id>/redeliver\` | GET · POST | every notify: webhook sent and each attempt; send one again |
+| \`/export\` · \`/import\` | GET · POST | the workspace, a flow (\`?kind=flow&name=\`) or an agent as a .zip; take one in (\`?dryRun=1\` first, \`?overwrite=1\` to replace) |
 | \`/restore\` | POST | the workspace's source back to a point in its history — \`dryRun\` first, then \`confirm\` |
 | \`/vocabulary\` | GET | what this workspace's documents may say |
 
@@ -442,10 +447,11 @@ subagents: [researcher]     # colleagues it may delegate a job to (own context,
 secrets: [CRM_TOKEN]        # keys the agent uses itself; a tool's own come with the tool
 limits: {web.search: 40, crm: 20, calls: 300}  # per step; a call past a limit is refused, never run
 timezone: Australia/Sydney  # the calendar it works to — IANA name or UTC+10
-provider: {}                # BYOK: your own model credential
+provider: {}                # BYOK for this agent; account-wide: \`foldrun account model set\`
 permissionMode: plan        # plan first, act once approved
 runtime:                    # only if scripts need packages
   packages: [requests]
+  system: [ffmpeg]          # Debian packages, apt-installed before the step
 ---
 
 You research a topic and report what you found...
@@ -459,8 +465,12 @@ flow's, else the workspace's AGENTS.md, else the account's, else UTC. It sets
 \`TZ\` and the date the agent is told, so a Sydney desk stamps the Sydney date.
 
 \`runtime:\` installs pip/npm packages in the sandbox each agent runs in. Pin
-versions the normal way (\`pandas>=2\`, \`lodash@^4\`). Python and Node are
-supported; anything else should ship as a committed binary.
+versions the normal way (\`pandas>=2\`, \`lodash@^4\`). \`system:\` adds Debian
+packages \u{2014} a program (\`ffmpeg\`), a library's headers for a pip package that
+compiles (\`libcairo2-dev\`, \`python3-dev\`), \`build-essential\` \u{2014} installed with
+apt before the step starts and cached, so later runs only unpack them. An agent that
+finds it needs something mid-run installs it itself with the \`install\` tool
+(apt, pip or npm), which every agent has; declaring is only a speed-up.
 
 Link documents to each other with \`[[wikilinks]]\` — the name, not the path.
 `,
@@ -482,3 +492,25 @@ expect:
         },
     ];
 }
+/**
+ * A new workspace with nothing in it to delete: its AGENTS.md, the
+ * .gitignore that keeps its secret key out of git, and the CLAUDE.md a coding
+ * tool reads. No example agents or flow.
+ *
+ * The starter's researcher and writer were a demo, and a person making a
+ * workspace for real work met them as clutter — "why does a new workspace
+ * have agents?" (owner, 2026-10-05). The agents worth having are usually ones
+ * already written in another workspace, which `agents/import` copies in; the
+ * example is still one flag away (`foldrun new <name> --starter`).
+ */
+export function blankWorkspaceFiles(workspace) {
+    const keep = new Set(["AGENTS.md", ".gitignore", "CLAUDE.md"]);
+    return starterFiles(workspace)
+        .filter((f) => keep.has(f.path))
+        .map((f) => f.path === "AGENTS.md"
+        ? {
+            ...f,
+            content: f.content.replace("description: A starter workspace — edit the agents, then run the flow.", "description: A new workspace — add an agent or import one from another workspace, then write a flow."),
+        }
+        : f);
+}

package/dist/src/step-exec.d.ts

@@ -238,8 +238,8 @@ export declare function checkVerify(agentDir: string, verify: string, ctx: {
      *  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
@@ -249,3 +249,23 @@ export declare function checkVerify(agentDir: string, verify: string, ctx: {
      *  person asked the run to stop. */
     signal?: AbortSignal;
 }): Promise<VerifyVerdict>;
+/**
+ * A toolless, fast-tier grading call: does the reply satisfy the sentence?
+ * Same shape as the eval judge, and answered with one word first so the
+ * verdict is a prefix test rather than a reading.
+ */
+export declare function judgePrompt(rubric: string, reply: string, work: string): string;
+/**
+ * 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 declare function sdkEnv(base: Record<string, string | undefined> | undefined, extra?: Record<string, string>): Record<string, string | undefined>;
+/** 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 declare function toolResultText(content: unknown): string;

package/dist/src/step-exec.js

@@ -188,6 +188,13 @@ async function executeStepInner(opts, runQuery) {
             // 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.
@@ -213,8 +220,10 @@ async function executeStepInner(opts, runQuery) {
             // 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
@@ -509,12 +518,25 @@ async function executeStepInner(opts, runQuery) {
                             ...(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.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`);
                 }
@@ -799,7 +821,13 @@ export async function checkVerify(agentDir, verify, ctx) {
             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) };
         }
@@ -811,7 +839,18 @@ export async function checkVerify(agentDir, verify, ctx) {
  * Same shape as the eval judge, and answered with one word first so the
  * verdict is a prefix test rather than a reading.
  */
-async function judgeReply(rubric, output, env, signal) {
+export function judgePrompt(rubric, reply, work) {
+    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, reply, work, env, signal) {
     const texts = [];
     const abortController = new AbortController();
     if (signal?.aborted)
@@ -819,15 +858,14 @@ async function judgeReply(rubric, output, env, signal) {
     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,
             },
@@ -898,3 +936,28 @@ function runVerify(agentDir, command, env, data, signal) {
         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, extra = {}) {
+    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) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((b) => !!b && b.type === "text" && typeof b.text === "string")
+        .map((b) => b.text)
+        .join(" ");
+}

package/dist/src/storage.d.ts

@@ -128,6 +128,10 @@ export declare function uploadUrl(tenant: string, workspace: string, rel: string
  * is worth writing when a workspace actually outgrows its quota, not before.
  */
 export declare function materializeFiles(tenant: string, workspace: string): Promise<string[]>;
+/** 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 declare function storageBaseline(tenant: string, workspace: string): Record<string, string>;
 /**
  * Take what the run left in `storage/` back into the store, stamped with the
  * run that wrote it.
@@ -136,7 +140,9 @@ export declare function materializeFiles(tenant: string, workspace: string): Pro
  * derived from the index, so anything on disk that the index does not already
  * describe with the same size and hash is, by construction, new work.
  */
-export declare function harvestFiles(tenant: string, workspace: string, by: string): Promise<{
+export declare function harvestFiles(tenant: string, workspace: string, by: string, opts?: {
+    changedFrom?: Record<string, string>;
+}): Promise<{
     saved: string[];
     errors: string[];
 }>;

package/dist/src/storage.js

@@ -686,6 +686,14 @@ export async function materializeFiles(tenant, workspace) {
     fs.mkdirSync(root, { recursive: true });
     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, workspace) {
+    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.
@@ -694,7 +702,7 @@ export async function materializeFiles(tenant, workspace) {
  * derived from the index, so anything on disk that the index does not already
  * describe with the same size and hash is, by construction, new work.
  */
-export async function harvestFiles(tenant, workspace, by) {
+export async function harvestFiles(tenant, workspace, by, opts = {}) {
     if (!fileStoreEnabled())
         return { saved: [], errors: [] };
     adoptLegacyFilesDir(workspaceDir(tenant, workspace));
@@ -729,6 +737,11 @@ export async function harvestFiles(tenant, workspace, by) {
                 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);
         }

package/dist/src/store.d.ts

@@ -188,6 +188,15 @@ export declare function fencedCodeBlock(body: string): {
  * failure costs something that cannot be taken back. See `lintFlow`.
  */
 export declare function toolIsOutward(data: Record<string, unknown>): boolean;
+/** How much of a tool.md body rides to the model with the tool. */
+export declare 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 declare function toolGuide(body: string | undefined, inlineProgram?: boolean): string | undefined;
 export declare function parseToolDef(data: Record<string, unknown>, fallbackName: string, body?: string): ToolDef | null;
 /**
  * Tools in a directory, in both shapes.
@@ -234,6 +243,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>;
     query: Record<string, string>;
     methods: string[];
@@ -846,6 +857,9 @@ export declare function setWorkspaceDescription(tenant: string, workspace: strin
  * 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 declare function blankTemplateFiles(workspace: string): DeployFile[];
 export declare function templateFiles(workspace: string): DeployFile[];
 export declare const AGENT_TEMPLATE: (name: string) => string;
 export declare const FLOW_TEMPLATE: (name: string, firstAgent: string) => string;
@@ -992,6 +1006,10 @@ export interface StepRecord {
         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
@@ -1337,6 +1355,12 @@ export declare 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 declare function runMeter(run: RunRecord): {
     tokenCostUsd: number;

package/dist/src/store.js

@@ -19,6 +19,7 @@
 // or an agent, and belongs in git.
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
+import { expandPlatformVars } from "./host-env.js";
 import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader } from "./history.js";
@@ -50,7 +51,7 @@ import { localeProblems } from "./locale.js";
 import { readBundle, syncIndex, appendLog, provenanceMarks, syncWorkspaceBundles, } from "./okf.js";
 import { readTransport, KINDS } from "./kinds.js";
 import { providerPreset, looksOpenAiShaped, PROTECTED_PARAMS } from "./providers.js";
-import { starterFiles, accountFiles } from "./starter.js";
+import { starterFiles, accountFiles, blankWorkspaceFiles } from "./starter.js";
 import { trimSlashes, MAX_EDITABLE_FILE } from "./paths.js";
 // Where workspaces live. The hosted app keeps many under data/; the CLI runs
 // against one folder, which is what `foldrun run ./my-desk` has to mean.
@@ -288,6 +289,18 @@ export function assertCanonicalCase(rel) {
 // trigger-log.jsonl: the scheduler's record of why a flow did or did not
 // 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) {
     const norm = rel.replaceAll("\\", "/");
@@ -299,6 +312,8 @@ export function isPlatformPath(rel) {
         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/");
 }
 /** What a deploy keeps whatever it ships — the rule above saveWorkspace's
@@ -483,7 +498,7 @@ export function buildMemoryIndex(dir, prefix = "") {
 // Workspace-scoped shared assets: skills/, memory/, tools/ sit beside agents/
 // and are available to every agent in that workspace.
 export function workspaceMemoryIndex(tenant, workspace) {
-    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
 // reads and never rewrites. Memory is what it *learned* and authors itself.
@@ -493,7 +508,7 @@ export function knowledgeIndex(dir, prefix = "") {
     return buildMemoryIndex(dir, prefix);
 }
 export function workspaceKnowledgeIndex(tenant, workspace) {
-    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
 // endpoint or a script — `type:` says which, and it's inferred when omitted
@@ -547,6 +562,28 @@ export function fencedCodeBlock(body) {
 export function toolIsOutward(data) {
     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, inlineProgram = false) {
+    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, fallbackName, body) {
     const name = typeof data.name === "string" ? data.name : fallbackName;
     // `transport:`, or a legacy `type: http|script|mcp` from before `type:` meant
@@ -580,18 +617,28 @@ export function parseToolDef(data, fallbackName, body) {
         };
     }
     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;
 }
 /**
  * Tools in a directory, in both shapes.
@@ -955,7 +1002,9 @@ export function parseApis(raw) {
         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),
@@ -2430,6 +2479,11 @@ export function setWorkspaceDescription(tenant, workspace, description) {
  * 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) {
+    return blankWorkspaceFiles(workspace).filter((f) => f.path === "AGENTS.md" || IN_WORKSPACE_DIR.test(f.path));
+}
 export function templateFiles(workspace) {
     // The starter minus what only matters on a laptop's disk: .gitignore
     // guards a local clone's secrets, but the hosted store never keeps
@@ -2579,7 +2633,25 @@ export function runOutputPath(tenant, workspace, runId, agent, rel) {
 }
 export function readRun(tenant, workspace, runId) {
     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;
+            if ((err.code === "ESTALE" || err.errno === -116) && i < attempts)
+                continue;
+            throw e;
+        }
+    }
 }
 export function writeRun(tenant, workspace, run) {
     const p = runFilePath(tenant, workspace, run.id);
@@ -2825,12 +2897,19 @@ export function runCost(run) {
  * 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) {
     let steps = 0;
     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;
@@ -2838,13 +2917,15 @@ export function runMeter(run) {
         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 };
 }
 /**
  * The compute meter for hold+work pricing: core-seconds and GiB-seconds

package/dist/src/subagents.js

@@ -71,7 +71,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/dist/src/test-mode.d.ts

@@ -103,8 +103,23 @@ export declare function divertedSummary(rel: string, was: Buffer | null, next: B
 export declare 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. */
-export declare function restoreDivertedDirs(wsRoot: string, before: Map<string, Buffer>, to: string, note: (rel: string, summary: string) => void): string[];
+ *  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 declare function restoreDivertedDirs(wsRoot: string, before: Map<string, Buffer>, to: string, note: (rel: string, summary: string) => void, handed?: Map<string, Buffer>): string[];
+/**
+ * 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 declare function overlayTestWrites(wsCopy: string, from: string): string[];
 /** `[test] ` in front of a headline, once. */
 export declare function testHeadline(summary: string): string;
 /** The env every test-run sandbox gets, beside its secrets. */