@foldrun/core 0.4.0 → 0.6.0

package/dist/src/confine.js

@@ -62,7 +62,7 @@ const PATH_KEYS = [
     "edits", // NotebookEdit-style payloads are checked via file_path too
 ];
 const DENIED_WITHIN = [
-    /(^|\/)secrets\.json$/,
+    /(^|\/)secrets\.json(\.[^/]+)?$/, // and its lock and temp files
     /(^|\/)runs(\/|$)/,
 ];
 /**
@@ -96,6 +96,8 @@ const VIRTUAL = [
     { prefix: "workspace/", root: (r) => r.workspaceRoot, readOnly: false },
 ];
 const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+/** Workspace-level directories an agent's own folder must never grow. */
+const SHARED_DIRS = new Set(["storage", "state", "workspace"]);
 // Only the built-in filesystem tools get path checks. foldrun's own MCP tools
 // are already confined at their own layer — script paths by resolveRunPath,
 // APIs by their declared base URL — and their arguments are not filesystem
@@ -141,11 +143,40 @@ export function suggestPath(raw) {
     }
     return `Use a path relative to your agent directory, or workspace/<dir>/… for the workspace root (workspace/storage/, workspace/state/).`;
 }
+/**
+ * A path an author wrote in a flow or an agent wrote in a tool call, as an
+ * absolute path: `workspace/…` from the workspace root, anything else from
+ * the agent's own folder (so the older `../../storage/x` lands in the same
+ * place as `workspace/storage/x`). Confinement is the caller's: this only
+ * says where the path points.
+ */
+export function resolveAgentPath(workspaceRoot, agentDir, raw) {
+    const p = raw.trim();
+    if (p === "workspace" || p === "workspace/")
+        return path.resolve(workspaceRoot);
+    if (p.startsWith("workspace/"))
+        return path.resolve(workspaceRoot, p.slice("workspace/".length));
+    return path.resolve(agentDir, p);
+}
+/** True when `abs` is `root` or under it. */
+export function isWithin(root, abs) {
+    const rel = path.relative(path.resolve(root), path.resolve(abs));
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
 /** Expand a virtual prefix to a real absolute path, or null if it has none. */
 export function expandVirtual(raw, roots) {
+    // The SDK resolves a relative path against the cwd BEFORE canUseTool sees
+    // it, so `workspace/storage/x.json` arrives as
+    // `<agentDir>/workspace/storage/x.json` and never matched a prefix. The
+    // write then made a literal `workspace/` folder inside the agent's own
+    // directory and reported success: gbp-desk's reply-sheet, 2026-09-24, whose
+    // approved replies never reached the poster. Read the prefix off the path
+    // relative to the agent directory as well as off the raw one.
+    const rel = path.isAbsolute(raw) ? path.relative(roots.agentDir, raw).split(path.sep).join("/") : null;
+    const candidate = rel !== null && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : raw;
     for (const v of VIRTUAL) {
-        if (raw.startsWith(v.prefix)) {
-            return { abs: path.resolve(v.root(roots), raw.slice(v.prefix.length)), readOnly: v.readOnly };
+        if (candidate.startsWith(v.prefix)) {
+            return { abs: path.resolve(v.root(roots), candidate.slice(v.prefix.length)), readOnly: v.readOnly };
         }
     }
     return null;
@@ -205,6 +236,25 @@ export function checkPaths(toolName, input, roots) {
                     `environment variables, and the run journal is not yours to read or rewrite.`,
             };
         }
+        // storage/, state/ and workspace/ belong to the workspace. The same name
+        // under an agent's own folder is always a missing prefix — `storage/x`
+        // written from agents/<name>/ — and the write used to succeed there,
+        // where no other agent looks: gbp-desk's approved replies, lawyer-desk's
+        // batch, five files in all by 2026-09-24. Refuse it with the path that
+        // was meant; the model takes the correction on its next turn.
+        if (isWrite && !virtual) {
+            const own = path.relative(real(path.resolve(roots.agentDir)), abs).split(path.sep).join("/");
+            const [top, ...rest] = own.split("/");
+            if (!own.startsWith("..") && rest.length && SHARED_DIRS.has(top)) {
+                const meant = top === "workspace" ? `workspace/${rest.join("/")}` : `workspace/${top}/${rest.join("/")}`;
+                return {
+                    ok: false,
+                    reason: `${toolName} was denied: "${raw}" would create ${top}/ inside your own agent folder, where no ` +
+                        `other agent or run looks. Did you mean ${meant}? Shared files go under workspace/ ` +
+                        `(workspace/storage/, workspace/state/, workspace/memory/); your own scratch goes to outputs/.`,
+                };
+            }
+        }
         if (isWrite && READ_ONLY_WITHIN.some((re) => re.test(within))) {
             return {
                 ok: false,
@@ -218,6 +268,30 @@ export function checkPaths(toolName, input, roots) {
         if (virtual)
             rewritten = { ...(rewritten ?? input), [key]: abs };
     }
+    // Glob searches from `path` (the cwd when absent) and its PATTERN never
+    // climbs: `../../storage/draft/*.md` answered "No files found" with the
+    // files there (run-munef2am-439a), and an expanded `workspace/storage/*.md`
+    // is an absolute pattern the tool does not search by either. Split such a
+    // pattern at its first wildcard: the fixed directories become `path`, the
+    // rest stays the pattern — so both spellings find what is there.
+    if (toolName === "Glob") {
+        const cur = { ...input, ...(rewritten ?? {}) };
+        const pattern = typeof cur.pattern === "string" ? cur.pattern : "";
+        const climbs = pattern.startsWith("../");
+        if (pattern && (climbs || path.isAbsolute(pattern)) && (cur.path === undefined || cur.path === "")) {
+            const absPattern = climbs ? path.resolve(roots.agentDir, pattern) : pattern;
+            const segs = absPattern.split("/");
+            const wild = segs.findIndex((seg) => /[*?[{]/.test(seg));
+            if (wild > 0 && wild < segs.length) {
+                const base = segs.slice(0, wild).join("/") || "/";
+                const inWorkspace = !path.relative(workspace, real(base)).startsWith("..");
+                const inLibrary = !path.relative(library, real(base)).startsWith("..");
+                if (inWorkspace || inLibrary) {
+                    rewritten = { ...(rewritten ?? input), path: base, pattern: segs.slice(wild).join("/") };
+                }
+            }
+        }
+    }
     return { ok: true, updatedInput: rewritten };
 }
 // A shell can defeat any argument-level path check, so Bash is handled
@@ -301,3 +375,144 @@ export function checkBash(command) {
     }
     return { ok: true };
 }
+// ------------------------------------------------------------ workspace link
+/**
+ * `workspace/…` for a shell. The file tools expand the prefix themselves
+ * (expandVirtual above), but Bash, a script an agent runs, a scripts: tool
+ * and a shell `verify:` see only the filesystem — and there `workspace/` was
+ * a folder that did not exist, so the one spelling the docs teach worked in
+ * Read and failed in `cat`. For the length of a step the agent's folder holds
+ * a `workspace` link to the workspace root (`../..`), and nothing else.
+ *
+ * Why only for a step: a permanent link inside the tree it points at is a
+ * cycle, and anything that walks the tree following links walks it forever
+ * (a `shared` link was tried that way and reverted). Every walker this
+ * platform runs over a workspace skips links (storage harvest, the source
+ * listing, tar, the container copy-back), and the link is gone before the
+ * step's files are read back.
+ *
+ * Counted, because the parallel instances of one agent (`each:`, a fan-out)
+ * share its folder in one process: the last one out removes it. A real
+ * folder already called `workspace` (a stray from before the prefix was
+ * expanded) is left alone and reported — linking over it would hide files.
+ */
+const workspaceLinks = new Map();
+export function linkWorkspace(agentDir, workspaceRoot) {
+    const link = path.join(agentDir, "workspace");
+    const target = path.relative(path.resolve(agentDir), path.resolve(workspaceRoot)) || ".";
+    const held = workspaceLinks.get(link) ?? 0;
+    let note = null;
+    let own = false;
+    if (held > 0) {
+        own = true;
+    }
+    else {
+        try {
+            const st = fs.lstatSync(link);
+            if (st.isSymbolicLink()) {
+                // Left by a step that ended without its cleanup — adopt it when it
+                // points where ours would, replace it when it does not.
+                if (fs.readlinkSync(link) !== target) {
+                    fs.unlinkSync(link);
+                    fs.symlinkSync(target, link, "dir");
+                }
+                own = true;
+            }
+            else {
+                note =
+                    `agents/${path.basename(agentDir)}/workspace/ is a real folder, so a shell command's ` +
+                        `workspace/… reaches it rather than the workspace root — move what it holds to the ` +
+                        `workspace's own storage/ or state/ and delete it`;
+            }
+        }
+        catch {
+            try {
+                fs.symlinkSync(target, link, "dir");
+                own = true;
+            }
+            catch (err) {
+                note = `could not link workspace/ for the shell: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+    }
+    if (own)
+        workspaceLinks.set(link, held + 1);
+    let released = false;
+    return {
+        note,
+        release: () => {
+            if (!own || released)
+                return;
+            released = true;
+            const left = (workspaceLinks.get(link) ?? 1) - 1;
+            if (left > 0) {
+                workspaceLinks.set(link, left);
+                return;
+            }
+            workspaceLinks.delete(link);
+            try {
+                if (fs.lstatSync(link).isSymbolicLink())
+                    fs.unlinkSync(link);
+            }
+            catch {
+                // already gone
+            }
+        },
+    };
+}
+/**
+ * A Node program started THROUGH the link is still its own main module.
+ *
+ * `node workspace/tools/x/run.mjs` loads the file by its real path —
+ * import.meta.url says `<ws>/tools/x/run.mjs` — while process.argv[1] keeps
+ * the path as typed, `<ws>/agents/a/workspace/tools/x/run.mjs`. The usual
+ * entry-point check, `import.meta.url === pathToFileURL(process.argv[1]).href`,
+ * was then false: the program did nothing, exited 0, and a `verify:` that
+ * ran it passed on every input.
+ *
+ * The fix rides NODE_OPTIONS into every child a step starts (the model's
+ * Bash, a shell `verify:`, a scripts: tool, the Test button): a preload that
+ * rewrites argv[1] to its real path, and only when it goes through this
+ * link. `--preserve-symlinks-main` was the obvious flag and the wrong one:
+ * it applies to EVERY linked entry point, and a `node_modules/.bin` shim
+ * then resolves `require("../lib/x.js")` beside the shim and fails.
+ *
+ * A data: URL rather than a file, so nothing has to be shipped to wherever
+ * the step runs (host, run container, pod, a runtime: venv). Node ≥ 20.6
+ * reads `--import` from NODE_OPTIONS; the runner image is Node 22. Python
+ * needs nothing: `python3 workspace/x.py` is `__main__` however it is
+ * reached.
+ */
+const MAIN_PRELOAD = [
+    `import{realpathSync}from"node:fs";`,
+    `import{resolve,sep,delimiter}from"node:path";`,
+    `const l=process.env.FOLDRUN_WORKSPACE_LINK,a=process.argv[1];`,
+    `if(l&&a){const f=resolve(a);`,
+    `if(l.split(delimiter).some(k=>k&&f.startsWith(k+sep))){`,
+    `try{process.argv[1]=realpathSync(f)}catch{}}}`,
+].join("");
+const MAIN_IMPORT = `--import=data:text/javascript,${encodeURIComponent(MAIN_PRELOAD)}`;
+/**
+ * `env` plus what makes `node workspace/…` its own main module (above):
+ * the link's path(s) in FOLDRUN_WORKSPACE_LINK, the preload appended to
+ * NODE_OPTIONS — after what it held, or the host's when it held nothing.
+ * Idempotent, and harmless where no link exists: the preload matches only
+ * a path under it.
+ */
+export function workspaceLinkEnv(env, agentDir) {
+    const link = path.join(path.resolve(agentDir), "workspace");
+    let real = link;
+    try {
+        real = path.join(fs.realpathSync(agentDir), "workspace");
+    }
+    catch {
+        // not there yet — the lexical path is the one a shell would type
+    }
+    const held = env.NODE_OPTIONS ?? process.env.NODE_OPTIONS ?? "";
+    const options = held.includes(MAIN_IMPORT) ? held : [held.trim(), MAIN_IMPORT].filter(Boolean).join(" ");
+    return {
+        ...env,
+        FOLDRUN_WORKSPACE_LINK: [...new Set([link, real])].join(path.delimiter),
+        NODE_OPTIONS: options,
+    };
+}

package/dist/src/container.d.ts

@@ -15,6 +15,13 @@ export interface ContainerRunOptions {
     agentDir: string;
     /** Extra read-only mounts: host path → container path. */
     readOnly?: Record<string, string>;
+    /** Workspace paths a script was handed as `workspace/…`: copied in at
+     *  `container` before it runs, and what it created or changed under them
+     *  copied back to `host` after — the host's workspace link, as a copy. */
+    staged?: {
+        host: string;
+        container: string;
+    }[];
     image: string;
     argv: string[];
     env: Record<string, string>;
@@ -28,3 +35,5 @@ export declare function runInContainer(opts: ContainerRunOptions): Promise<{
     code: number | null;
     out: string;
 }>;
+/** Write `from` over `to` where the bytes differ; recurse into folders. */
+export declare function syncChanged(from: string, to: string): void;

package/dist/src/container.js

@@ -9,6 +9,7 @@
 // Falls back to host execution when Docker isn't available, so local
 // development keeps working with zero configuration.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { dataRoot } from "./paths.js";
 import { spawnSync, spawn } from "node:child_process";
@@ -135,16 +136,41 @@ export async function runInContainer(opts) {
     }
     const cid = (created.stdout ?? "").trim();
     try {
-        // The agent's own directory becomes /workspace…
-        const copied = docker(["cp", `${opts.agentDir}/.`, `${cid}:/workspace`], 120_000);
-        if (copied.status !== 0) {
-            return { code: null, out: `copy in failed: ${(copied.stderr ?? "").slice(-300)}` };
-        }
+        // The agent's own directory becomes /workspace… — its entries staged
+        // like the workspace paths below (a scratch copy, opened up for the
+        // script's user, one tar), minus the step's `workspace` link. A step
+        // holds that link (→ ../..) so the shell can say workspace/…, and
+        // `docker cp` refuses a link that climbs out of what it copies
+        // ("invalid symlink"), so every Docker-run script failed before it
+        // started. And `docker cp` lands files as root while scripts run as
+        // `agent`, so a script could never write its own outputs/.
+        const own = fs
+            .readdirSync(opts.agentDir)
+            .filter((name) => {
+            if (name !== "workspace")
+                return true;
+            try {
+                return !fs.lstatSync(path.join(opts.agentDir, name)).isSymbolicLink();
+            }
+            catch {
+                return false;
+            }
+        })
+            .map((name) => ({ host: path.join(opts.agentDir, name), container: `/workspace/${name}` }));
+        const copiedIn = stageIn(CLI, cid, own, ["/workspace"]);
+        if (copiedIn)
+            return { code: null, out: `copy in failed: ${copiedIn}` };
         // …and any shared directories land at their declared paths.
         for (const [host, mount] of Object.entries(opts.readOnly ?? {})) {
             if (fs.existsSync(host))
                 docker(["cp", `${host}/.`, `${cid}:${mount}`], 120_000);
         }
+        const staged = opts.staged ?? [];
+        if (staged.length) {
+            const failed = stageIn(CLI, cid, staged);
+            if (failed)
+                return { code: null, out: `copy in failed: ${failed}` };
+        }
         const result = await new Promise((resolve) => {
             const child = spawn(CLI, ["start", "-a", cid], { timeout: opts.timeoutMs });
             let out = "";
@@ -164,9 +190,93 @@ export async function runInContainer(opts) {
         });
         // Bring deliverables back so outputs/ behaves the same either way.
         docker(["cp", `${cid}:/workspace/outputs/.`, path.join(opts.agentDir, "outputs")], 120_000);
+        for (const s of staged)
+            stageBack(CLI, cid, s);
         return result;
     }
     finally {
         docker(["rm", "-f", cid], 30_000);
     }
 }
+/**
+ * Copy the staged workspace paths into a created container: one tar, built
+ * in a scratch directory that mirrors the container paths, extracted at /.
+ * A path that does not exist yet (an output the script is told to write)
+ * gets its parent directory, so the write has somewhere to land.
+ */
+function stageIn(cli, cid, staged, dirs = []) {
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-stage-"));
+    try {
+        for (const d of dirs)
+            fs.mkdirSync(path.join(scratch, d), { recursive: true });
+        for (const { host, container } of staged) {
+            const dest = path.join(scratch, container);
+            if (fs.existsSync(host)) {
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.cpSync(host, dest, { recursive: true, dereference: false });
+            }
+            else {
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+            }
+        }
+        // `docker cp` lands files as root and scripts run as `agent`: these are
+        // scratch copies, so open them up for the script to write into.
+        openUp(scratch);
+        const top = fs.readdirSync(scratch);
+        const r = spawnSync("sh", ["-c", 'dir="$1"; cli="$2"; dest="$3"; shift 3; tar --no-xattrs -C "$dir" -cf - -- "$@" | "$cli" cp - "$dest"', "sh", scratch, cli, `${cid}:/`, ...top], { encoding: "utf8", timeout: 120_000, env: { ...process.env, COPYFILE_DISABLE: "1" } });
+        return r.status === 0 ? null : (r.stderr ?? "").slice(-300);
+    }
+    finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * Copy back what the script created or changed under one staged path. Files
+ * whose bytes did not change are left alone, so an input keeps its mtime —
+ * freshness checks read it.
+ */
+function stageBack(cli, cid, s) {
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-stage-"));
+    try {
+        const out = path.join(scratch, "x");
+        const got = spawnSync(cli, ["cp", `${cid}:${s.container}`, out], { encoding: "utf8", timeout: 120_000 });
+        if (got.status !== 0 || !fs.existsSync(out))
+            return;
+        syncChanged(out, s.host);
+    }
+    finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** Write `from` over `to` where the bytes differ; recurse into folders. */
+export function syncChanged(from, to) {
+    const st = fs.lstatSync(from);
+    if (st.isSymbolicLink())
+        return;
+    if (st.isDirectory()) {
+        fs.mkdirSync(to, { recursive: true });
+        for (const name of fs.readdirSync(from))
+            syncChanged(path.join(from, name), path.join(to, name));
+        return;
+    }
+    const next = fs.readFileSync(from);
+    if (fs.existsSync(to) && fs.statSync(to).isFile() && fs.readFileSync(to).equals(next))
+        return;
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.writeFileSync(to, next);
+}
+/** Directories 0777, files writable by all (exec bits kept): a scratch tree only. */
+function openUp(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, entry.name);
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            fs.chmodSync(p, 0o777);
+            openUp(p);
+        }
+        else {
+            fs.chmodSync(p, fs.statSync(p).mode | 0o666);
+        }
+    }
+}

package/dist/src/context-tools.d.ts

@@ -1,7 +1,7 @@
 import { createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
 import type { RunRecord } from "./store.ts";
 export interface SearchRoot {
-    /** How the agent should name the place: "knowledge/", "../../memory/". */
+    /** How the agent should name the place: "knowledge/", "workspace/memory/". */
     label: string;
     /** The directory, absolute. */
     dir: string;

package/dist/src/deploy.d.ts

@@ -1,4 +1,14 @@
 import { type DeployFile } from "./store.ts";
+/**
+ * Is this path, relative to a workspace root, one `readTree` would carry?
+ *
+ * The same question the walk above asks, asked of a path that is not on this
+ * machine — what the platform lists for a workspace, so `foldrun status` and
+ * `foldrun pull` compare like with like. Without it the comparison counted
+ * every run artefact and bookkeeping file the platform keeps as a local
+ * deletion, and every status was a wall of red.
+ */
+export declare function isSourcePath(rel: string): boolean;
 export interface DeployIssue {
     where: string;
     message: string;
@@ -11,11 +21,18 @@ export interface DeployPlan {
     updated: string[];
     /** Empty when the deploy is safe to apply. */
     issues: DeployIssue[];
+    /** Advisory, non-blocking: a deploy proceeds with these. Today this is
+     *  the outward-without-a-gate lint — the same one `foldrun check` fails
+     *  on, surfaced here so a push over the API is not the last to hear it. */
+    warnings: DeployIssue[];
     /** Set when a run is in flight, which blocks the swap. */
     blockedBy: string[];
 }
 export interface DeployResult extends DeployPlan {
     applied: boolean;
+    /** Set when `expectRemoved` was given and the deploy would have removed
+     *  paths outside it: those paths. The deploy was refused, nothing changed. */
+    unexpectedRemovals?: string[];
     /** The commit this workspace is now running, when the caller knows it. */
     commit: string | null;
     preserved: number;
@@ -37,6 +54,13 @@ export declare function readTree(dir: string): DeployFile[];
  * not on disk yet. A deploy that would leave the workspace failing its own
  * checker should not be a deploy.
  */
+/** Best-effort warnings for a deploy: an agent's `web:` warnings (see
+ *  webWarnings), and the outward gate — a step whose agent grants
+ *  a workspace tool marked `outward: true` and has no `verify:`/gate. Reads
+ *  only the deployed files, so a library or gallery outward tool is not seen
+ *  here — `foldrun check`, which resolves every scope, remains the real gate.
+ *  Non-blocking by decision: the deploy proceeds and says so. */
+export declare function deployWarnings(files: DeployFile[]): DeployIssue[];
 export declare function deployIssues(files: DeployFile[]): DeployIssue[];
 /**
  * Runs that make this a bad moment to swap the files under them.
@@ -57,6 +81,15 @@ export interface DeployOptions {
     message?: string;
     /** Apply even while runs are in flight. */
     force?: boolean;
+    /**
+     * The removals a person confirmed from a dry run. When given, the deploy
+     * is refused (applied: false, `unexpectedRemovals` set) if it would remove
+     * anything not in this list — a run can write new storage/ outputs between
+     * the question and the answer, and a yes to one list is not a yes to
+     * another. Checked in the same synchronous call that writes, so there is
+     * no window between the check and the swap. Absent: no check, as before.
+     */
+    expectRemoved?: string[];
 }
 /**
  * Deploy a file list to a workspace, if it checks out.