@foldrun/core 0.2.0

package/dist/src/storage.js

@@ -0,0 +1,640 @@
+// Files: the bytes a workspace holds that are not its source.
+//
+// Everything else in a workspace is markdown you diff and commit — agents,
+// flows, skills, memory. This is the other half: a price list somebody
+// uploaded, a PDF an agent produced, a CSV it scraped. Opaque bytes, often
+// large, with no frontmatter and nothing to review in a pull request.
+//
+// Keeping the two apart is the whole design. `saveWorkspace` already refuses
+// anything outside WORKSPACE_DIRS, so a deploy cannot carry a 40MB PNG into
+// the source tree; and `storage/` is not in WORKSPACE_DIRS, so the file tree,
+// the graph and the git export never see one. A workspace stays reviewable.
+//
+//   Agents never learn a storage API. A run gets `storage/` materialised into
+//   its workspace copy and writes there with plain Read/Write/Bash; what it
+//   leaves behind is harvested back into the store afterwards, stamped with
+//   the run that made it. The model's mental model is a folder, because the
+//   rest of this runtime's is too.
+//
+// Two drivers behind one interface:
+//
+//   fs   the default. Blobs under data/<tenant>/storage/<workspace>/blobs/.
+//        No account, no credentials, no network — the CLI on a laptop gets
+//        the same feature the hosted platform has.
+//
+//   s3   any S3-compatible endpoint; Cloudflare R2 is what the hosted
+//        platform runs. Chosen over a self-hosted store for one blunt
+//        reason: run pods are denied RFC1918 egress by NetworkPolicy, so an
+//        in-cluster MinIO/Garage would need a hole punched in the one rule
+//        that makes the sandbox true, while a public S3 endpoint is already
+//        reachable and needs no credentials inside the pod — a presigned URL
+//        is a URL. R2 specifically because agents and people both download,
+//        and R2 does not bill egress.
+//
+// The index is always local, whichever driver holds the bytes. It is small,
+// it is what the dashboard lists, and it is already inside the backup that
+// covers data/ — paying an S3 round trip to render a table would be a worse
+// version of a file read.
+//
+// Config (s3 driver):
+//
+//   FOLDRUN_STORAGE_DRIVER        fs | s3          default fs
+//   FOLDRUN_S3_ENDPOINT         https://<account>.r2.cloudflarestorage.com
+//   FOLDRUN_S3_BUCKET           bucket name
+//   FOLDRUN_S3_REGION           default auto (R2's region)
+//   FOLDRUN_S3_ACCESS_KEY_ID
+//   FOLDRUN_S3_SECRET_ACCESS_KEY
+//   FOLDRUN_S3_PATH_STYLE       default true — R2 speaks path style
+//   FOLDRUN_STORAGE_MAX_MB        per object, default 512
+//   FOLDRUN_STORAGE_QUOTA_MB      per workspace, default 5120
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { dataRoot, singleWorkspace } from "./paths.js";
+import { assertSafeName, workspaceDir, STORAGE_DIR, adoptLegacyFilesDir } from "./store.js";
+/** The directory a run sees, and the one this module mirrors into it.
+ *  Declared in store.ts, where saveWorkspace also needs it; re-exported so
+ *  callers of this module do not need to know that. */
+export { STORAGE_DIR };
+// ---------- limits ----------
+const maxBytes = () => Number(process.env.FOLDRUN_STORAGE_MAX_MB ?? 512) * 1024 * 1024;
+const quotaBytes = () => Number(process.env.FOLDRUN_STORAGE_QUOTA_MB ?? 5120) * 1024 * 1024;
+// ---------- paths ----------
+/**
+ * Hosted only. On a laptop `storage/` is just a folder in the user's own
+ * project — they can see it, open it, and put a PDF in it with Finder — and
+ * an index plus a second hardlinked copy under data/ would be bookkeeping
+ * for a problem nobody has. The store exists to give many tenants a shared
+ * bucket and a provenance trail; one person with one directory has neither
+ * question to answer.
+ *
+ * Everything public here checks this first and does nothing, so the CLI runs
+ * the same driveRun the platform does and simply skips the mirror.
+ */
+export function fileStoreEnabled() {
+    return singleWorkspace() === null;
+}
+function storeDir(tenant, workspace) {
+    if (!fileStoreEnabled()) {
+        throw new Error("the file store is not used in single-workspace mode — storage/ is a plain folder");
+    }
+    assertSafeName(tenant, "tenant");
+    assertSafeName(workspace, "workspace");
+    // Upgrade an install that predates the rename, the first time the store is
+    // resolved. data/<tenant>/files/ becomes data/<tenant>/storage/.
+    adoptLegacyFilesDir(path.join(dataRoot(), tenant));
+    return path.join(dataRoot(), tenant, STORAGE_DIR, workspace);
+}
+function indexPath(tenant, workspace) {
+    return path.join(storeDir(tenant, workspace), "index.json");
+}
+/** The object key. Tenant-first so a bucket policy can be written per tenant,
+ *  and content-addressed so objects are immutable — no cache invalidation,
+ *  no partially-overwritten object, and a repeated upload is a no-op. */
+export function blobKey(tenant, workspace, sha) {
+    return `t/${tenant}/w/${workspace}/blobs/${sha}`;
+}
+/**
+ * Reject anything that isn't a plain relative path under storage/.
+ *
+ * This runs on names that came from an upload form *and* on paths harvested
+ * out of a container, so it is the boundary for both directions. `..` is the
+ * obvious one; a leading slash and a Windows drive letter are the two that
+ * path.normalize alone will happily keep.
+ */
+export function assertFilePath(rel) {
+    const norm = rel.replaceAll("\\", "/").replace(/^\.\//, "");
+    if (!norm || norm.length > 400)
+        throw new Error(`illegal file path: ${rel}`);
+    if (path.isAbsolute(norm) || /^[a-zA-Z]:/.test(norm))
+        throw new Error(`illegal file path: ${rel}`);
+    if (norm.split("/").some((s) => s === "" || s === "." || s === "..")) {
+        throw new Error(`illegal file path: ${rel}`);
+    }
+    // Control characters survive a normalize and break every header they touch.
+    if (/[\u0000-\u001f\u007f]/.test(norm))
+        throw new Error(`illegal file path: ${rel}`);
+    return norm;
+}
+// ---------- mime ----------
+const MIME = {
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".md": "text/markdown",
+    ".txt": "text/plain",
+    ".html": "text/html",
+    ".xml": "application/xml",
+    ".yaml": "text/yaml",
+    ".yml": "text/yaml",
+    ".zip": "application/zip",
+    ".gz": "application/gzip",
+    ".tar": "application/x-tar",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".mp3": "audio/mpeg",
+    ".mp4": "video/mp4",
+    ".wav": "audio/wav",
+};
+export function mimeFor(rel) {
+    return MIME[path.extname(rel).toLowerCase()] ?? "application/octet-stream";
+}
+// ---------- the index ----------
+export function readIndex(tenant, workspace) {
+    if (!fileStoreEnabled())
+        return { version: 1, files: [] };
+    try {
+        const raw = JSON.parse(fs.readFileSync(indexPath(tenant, workspace), "utf8"));
+        if (!Array.isArray(raw?.files))
+            return { version: 1, files: [] };
+        return { version: 1, files: raw.files };
+    }
+    catch {
+        return { version: 1, files: [] };
+    }
+}
+/** Write-and-rename. A half-written index is a workspace that has lost every
+ *  file it owns, which is not a state worth risking to save a syscall. */
+function writeIndex(tenant, workspace, index) {
+    const file = indexPath(tenant, workspace);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(index, null, 2));
+    fs.renameSync(tmp, file);
+}
+export function listStorage(tenant, workspace) {
+    return readIndex(tenant, workspace).files.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+export function getFile(tenant, workspace, rel) {
+    const norm = assertFilePath(rel);
+    return readIndex(tenant, workspace).files.find((f) => f.path === norm) ?? null;
+}
+export function usedBytes(tenant, workspace) {
+    // Distinct blobs, not records: two names for identical bytes occupy one
+    // object, and billing the tenant twice for it would be a lie.
+    const seen = new Map();
+    for (const f of readIndex(tenant, workspace).files)
+        seen.set(f.sha, f.size);
+    return [...seen.values()].reduce((a, b) => a + b, 0);
+}
+// ---------- fs driver ----------
+/** Where the fs driver keeps a blob. Exported because the run mirror
+ *  hardlinks straight to it rather than reading and rewriting the bytes. */
+export function blobPath(tenant, workspace, sha) {
+    return path.join(storeDir(tenant, workspace), "blobs", sha);
+}
+function fsDriver(tenant, workspace) {
+    const blobs = path.join(storeDir(tenant, workspace), "blobs");
+    const at = (key) => path.join(blobs, key.split("/").pop());
+    return {
+        kind: "fs",
+        async put(key, body) {
+            fs.mkdirSync(blobs, { recursive: true });
+            const target = at(key);
+            // Content-addressed: identical bytes are already there. Skipping the
+            // write also keeps mtime stable, which the hardlink mirror relies on.
+            if (fs.existsSync(target))
+                return;
+            const tmp = `${target}.${process.pid}.tmp`;
+            fs.writeFileSync(tmp, body);
+            fs.renameSync(tmp, target);
+        },
+        async get(key) {
+            return fs.readFileSync(at(key));
+        },
+        async has(key) {
+            return fs.existsSync(at(key));
+        },
+        async remove(key) {
+            fs.rmSync(at(key), { force: true });
+        },
+        async presignGet() {
+            return null;
+        },
+        async presignPut() {
+            return null;
+        },
+    };
+}
+export function s3Config() {
+    const endpoint = process.env.FOLDRUN_S3_ENDPOINT;
+    const bucket = process.env.FOLDRUN_S3_BUCKET;
+    const accessKeyId = process.env.FOLDRUN_S3_ACCESS_KEY_ID;
+    const secretAccessKey = process.env.FOLDRUN_S3_SECRET_ACCESS_KEY;
+    if (!endpoint || !bucket || !accessKeyId || !secretAccessKey)
+        return null;
+    return {
+        endpoint: endpoint.replace(/\/+$/, ""),
+        bucket,
+        // R2 has one region and calls it `auto`. AWS callers set their own.
+        region: process.env.FOLDRUN_S3_REGION ?? "auto",
+        accessKeyId,
+        secretAccessKey,
+        pathStyle: process.env.FOLDRUN_S3_PATH_STYLE !== "false",
+    };
+}
+const sha256 = (b) => crypto.createHash("sha256").update(b).digest("hex");
+const hmac = (key, data) => crypto.createHmac("sha256", key).update(data, "utf8").digest();
+/** RFC 3986. encodeURIComponent leaves !'()* alone and SigV4 does not. */
+function uriEncode(s, keepSlash = false) {
+    const out = encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    return keepSlash ? out.replaceAll("%2F", "/") : out;
+}
+function stamps(now) {
+    const amzDate = now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+    return { amzDate, dateStamp: amzDate.slice(0, 8) };
+}
+function signingKey(cfg, dateStamp) {
+    const kDate = hmac(`AWS4${cfg.secretAccessKey}`, dateStamp);
+    const kRegion = hmac(kDate, cfg.region);
+    const kService = hmac(kRegion, "s3");
+    return hmac(kService, "aws4_request");
+}
+/** Where a key lives, split into the host and the canonical path SigV4 signs. */
+function target(cfg, key) {
+    const url = new URL(cfg.endpoint);
+    const encoded = uriEncode(key, true);
+    if (cfg.pathStyle) {
+        return { host: url.host, origin: url.origin, canonicalUri: `/${cfg.bucket}/${encoded}` };
+    }
+    const host = `${cfg.bucket}.${url.host}`;
+    return { host, origin: `${url.protocol}//${host}`, canonicalUri: `/${encoded}` };
+}
+/**
+ * A presigned URL — SigV4 in the query string, so the browser (or a run pod)
+ * needs no credentials and no SDK, just the link.
+ *
+ * `extraQuery` carries the response-header overrides. That is where the one
+ * security property that matters here comes from: every download is signed
+ * with `response-content-disposition: attachment`, so an HTML file an agent
+ * wrote can never render as a page on any origin. Without it, "the agent
+ * produced a report.html" and "stored XSS" are the same event.
+ */
+function presign(cfg, method, key, ttlSec, extraQuery = {}, now = new Date()) {
+    const { host, origin, canonicalUri } = target(cfg, key);
+    const { amzDate, dateStamp } = stamps(now);
+    const scope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
+    const query = {
+        ...extraQuery,
+        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
+        "X-Amz-Credential": `${cfg.accessKeyId}/${scope}`,
+        "X-Amz-Date": amzDate,
+        "X-Amz-Expires": String(ttlSec),
+        "X-Amz-SignedHeaders": "host",
+    };
+    const canonicalQuery = Object.keys(query)
+        .sort()
+        .map((k) => `${uriEncode(k)}=${uriEncode(query[k])}`)
+        .join("&");
+    const canonicalRequest = [
+        method,
+        canonicalUri,
+        canonicalQuery,
+        `host:${host}\n`,
+        "host",
+        "UNSIGNED-PAYLOAD",
+    ].join("\n");
+    const stringToSign = [
+        "AWS4-HMAC-SHA256",
+        amzDate,
+        scope,
+        sha256(canonicalRequest),
+    ].join("\n");
+    const signature = hmac(signingKey(cfg, dateStamp), stringToSign).toString("hex");
+    return `${origin}${canonicalUri}?${canonicalQuery}&X-Amz-Signature=${signature}`;
+}
+/** The header-signed form, for the calls the platform itself makes. */
+async function s3Request(cfg, method, key, body, mime) {
+    const { host, origin, canonicalUri } = target(cfg, key);
+    const { amzDate, dateStamp } = stamps(new Date());
+    const scope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
+    const payloadHash = sha256(body ?? Buffer.alloc(0));
+    const headers = {
+        host,
+        "x-amz-content-sha256": payloadHash,
+        "x-amz-date": amzDate,
+        ...(mime ? { "content-type": mime } : {}),
+    };
+    const signed = Object.keys(headers).sort();
+    const canonicalHeaders = signed.map((h) => `${h}:${headers[h].trim()}\n`).join("");
+    const signedHeaders = signed.join(";");
+    const canonicalRequest = [
+        method,
+        canonicalUri,
+        "",
+        canonicalHeaders,
+        signedHeaders,
+        payloadHash,
+    ].join("\n");
+    const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256(canonicalRequest)].join("\n");
+    const signature = hmac(signingKey(cfg, dateStamp), stringToSign).toString("hex");
+    const res = await fetch(`${origin}${canonicalUri}`, {
+        method,
+        body: body,
+        headers: {
+            ...headers,
+            Authorization: `AWS4-HMAC-SHA256 Credential=${cfg.accessKeyId}/${scope}, ` +
+                `SignedHeaders=${signedHeaders}, Signature=${signature}`,
+        },
+    });
+    return res;
+}
+function s3Driver(cfg) {
+    const fail = async (res, what) => {
+        throw new Error(`s3 ${what} failed: ${res.status} ${(await res.text()).slice(0, 300)}`);
+    };
+    return {
+        kind: "s3",
+        async put(key, body, mime) {
+            const res = await s3Request(cfg, "PUT", key, body, mime);
+            if (!res.ok)
+                await fail(res, "put");
+        },
+        async get(key) {
+            const res = await s3Request(cfg, "GET", key);
+            if (!res.ok)
+                await fail(res, "get");
+            return Buffer.from(await res.arrayBuffer());
+        },
+        async has(key) {
+            const res = await s3Request(cfg, "HEAD", key);
+            return res.ok;
+        },
+        async remove(key) {
+            const res = await s3Request(cfg, "DELETE", key);
+            // 404 on delete is the desired end state, not an error.
+            if (!res.ok && res.status !== 404)
+                await fail(res, "delete");
+        },
+        async presignGet(key, filename, mime, ttlSec = 300) {
+            return presign(cfg, "GET", key, ttlSec, {
+                // Never inline. See presign()'s note — this is the XSS boundary.
+                "response-content-disposition": `attachment; filename="${filename.replace(/["\\]/g, "")}"`,
+                "response-content-type": mime,
+            });
+        },
+        async presignPut(key, _mime, ttlSec = 600) {
+            return presign(cfg, "PUT", key, ttlSec);
+        },
+    };
+}
+/**
+ * The driver in force. `fs` unless S3 is both selected and configured —
+ * a half-set environment falls back rather than failing at the first upload,
+ * because a dashboard that boots and stores locally beats one that 500s.
+ */
+export function driverFor(tenant, workspace) {
+    if (process.env.FOLDRUN_STORAGE_DRIVER === "s3") {
+        const cfg = s3Config();
+        if (cfg)
+            return s3Driver(cfg);
+    }
+    return fsDriver(tenant, workspace);
+}
+// ---------- the store ----------
+/**
+ * Record bytes the platform already holds. Used by the upload route on the fs
+ * driver and by the run harvest on both.
+ */
+/**
+ * trigger: storage — tell the flows watching a prefix that files landed.
+ * Called after an index write, never before: a flow that starts on a file
+ * must find the file there. Dynamic import, because the queue imports the
+ * runner, which imports this module.
+ */
+async function announceFiles(tenant, workspace, paths, by) {
+    try {
+        const { fireStorageTriggers } = await import("./triggers.js");
+        await fireStorageTriggers(tenant, workspace, paths, by);
+    }
+    catch (err) {
+        console.error(`[foldrun] storage trigger ${tenant}/${workspace}:`, err instanceof Error ? err.message : err);
+    }
+}
+export async function putFile(tenant, workspace, rel, body, by) {
+    const record = await putFileQuietly(tenant, workspace, rel, body, by);
+    // A run's copy-back announces once, for all its files, from harvestFiles.
+    if (!by.startsWith("run:"))
+        await announceFiles(tenant, workspace, [record.path], by);
+    return record;
+}
+async function putFileQuietly(tenant, workspace, rel, body, by) {
+    const norm = assertFilePath(rel);
+    if (body.length > maxBytes()) {
+        throw new Error(`${norm} is ${Math.round(body.length / 1e6)}MB — the limit is ${maxBytes() / 1e6}MB`);
+    }
+    const sha = sha256(body);
+    const index = readIndex(tenant, workspace);
+    const previous = index.files.find((f) => f.path === norm);
+    if (previous?.sha === sha)
+        return previous; // same bytes, same name: nothing happened
+    const projected = usedBytes(tenant, workspace) - (previous?.size ?? 0) + body.length;
+    if (projected > quotaBytes()) {
+        throw new Error(`workspace file quota exceeded (${quotaBytes() / 1e6}MB)`);
+    }
+    const driver = driverFor(tenant, workspace);
+    await driver.put(blobKey(tenant, workspace, sha), body, mimeFor(norm));
+    const record = {
+        path: norm,
+        sha,
+        size: body.length,
+        mime: mimeFor(norm),
+        updatedAt: new Date().toISOString(),
+        by,
+    };
+    writeIndex(tenant, workspace, {
+        version: 1,
+        files: [...index.files.filter((f) => f.path !== norm), record],
+    });
+    if (previous)
+        await collect(tenant, workspace, previous.sha);
+    return record;
+}
+/** Register bytes a browser PUT straight to the bucket. Same bookkeeping as
+ *  putFile, minus the bytes — the platform never saw them. */
+export async function registerUpload(tenant, workspace, rel, sha, size, by) {
+    const norm = assertFilePath(rel);
+    if (!/^[0-9a-f]{64}$/.test(sha))
+        throw new Error("expected a sha256");
+    const driver = driverFor(tenant, workspace);
+    // Trust nothing the browser said about whether the PUT landed.
+    if (!(await driver.has(blobKey(tenant, workspace, sha)))) {
+        throw new Error("no object at that key — the upload did not complete");
+    }
+    const index = readIndex(tenant, workspace);
+    const previous = index.files.find((f) => f.path === norm);
+    const record = {
+        path: norm,
+        sha,
+        size,
+        mime: mimeFor(norm),
+        updatedAt: new Date().toISOString(),
+        by,
+    };
+    writeIndex(tenant, workspace, {
+        version: 1,
+        files: [...index.files.filter((f) => f.path !== norm), record],
+    });
+    if (previous && previous.sha !== sha)
+        await collect(tenant, workspace, previous.sha);
+    await announceFiles(tenant, workspace, [record.path], by);
+    return record;
+}
+export async function readFileBytes(tenant, workspace, rel) {
+    const record = getFile(tenant, workspace, rel);
+    if (!record)
+        return null;
+    return driverFor(tenant, workspace).get(blobKey(tenant, workspace, record.sha));
+}
+export async function deleteFile(tenant, workspace, rel) {
+    const norm = assertFilePath(rel);
+    const index = readIndex(tenant, workspace);
+    const record = index.files.find((f) => f.path === norm);
+    if (!record)
+        return false;
+    writeIndex(tenant, workspace, { version: 1, files: index.files.filter((f) => f.path !== norm) });
+    await collect(tenant, workspace, record.sha);
+    // The run mirror is a cache of the index, so it follows the index.
+    fs.rmSync(path.join(workspaceDir(tenant, workspace), STORAGE_DIR, norm), { force: true });
+    return true;
+}
+/** Drop a blob once the last record naming it is gone. */
+async function collect(tenant, workspace, sha) {
+    if (readIndex(tenant, workspace).files.some((f) => f.sha === sha))
+        return;
+    try {
+        await driverFor(tenant, workspace).remove(blobKey(tenant, workspace, sha));
+    }
+    catch {
+        // A leaked blob costs storage; a delete that throws mid-request costs the
+        // user their action. The index is already correct, so this is the safe
+        // side to fail on.
+    }
+}
+/** A link the browser can follow, or null when the route must stream it. */
+export async function downloadUrl(tenant, workspace, record) {
+    return driverFor(tenant, workspace).presignGet(blobKey(tenant, workspace, record.sha), path.basename(record.path), record.mime);
+}
+/** A link the browser can PUT to, plus the key it will land at. Null on fs. */
+export async function uploadUrl(tenant, workspace, rel, sha) {
+    assertFilePath(rel);
+    if (!/^[0-9a-f]{64}$/.test(sha))
+        throw new Error("expected a sha256");
+    return driverFor(tenant, workspace).presignPut(blobKey(tenant, workspace, sha), mimeFor(rel));
+}
+// ---------- the run mirror ----------
+/**
+ * Put the workspace's files on disk under `<workspace>/storage/`, where a run
+ * copies them into its container like any other directory.
+ *
+ * On the fs driver this is a hardlink: the blob and the mirror are the same
+ * inode, so a 2GB corpus costs 2GB once, not twice. On s3 it is a download,
+ * and the mirror is a cache — a second run over the same files fetches
+ * nothing.
+ *
+ * Not pruned. A workspace that churns hundreds of large files will hold a
+ * copy of each on the PVC until someone deletes the record, and the quota is
+ * what stops that becoming a full disk. Pruning wants an LRU that knows no
+ * run is currently reading the file it is about to remove, and that bookkeeping
+ * is worth writing when a workspace actually outgrows its quota, not before.
+ */
+export async function materializeFiles(tenant, workspace) {
+    if (!fileStoreEnabled())
+        return [];
+    adoptLegacyFilesDir(workspaceDir(tenant, workspace));
+    const root = path.join(workspaceDir(tenant, workspace), STORAGE_DIR);
+    const driver = driverFor(tenant, workspace);
+    const brought = [];
+    for (const record of readIndex(tenant, workspace).files) {
+        const target = path.join(root, record.path);
+        try {
+            const stat = fs.statSync(target);
+            // Same size is not proof — a date bumped by a day is the same length
+            // as the date before it. Confirm by hash, as the harvest does, before
+            // trusting the mirror: a stale copy here rides into the pod, and the
+            // harvest then writes it back over the upload that should have won.
+            if (stat.size === record.size && sha256(fs.readFileSync(target)) === record.sha)
+                continue;
+        }
+        catch {
+            // not there yet
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        if (driver.kind === "fs") {
+            const blob = blobPath(tenant, workspace, record.sha);
+            fs.rmSync(target, { force: true });
+            try {
+                fs.linkSync(blob, target);
+            }
+            catch {
+                fs.copyFileSync(blob, target); // different filesystem, or a hardlink limit
+            }
+        }
+        else {
+            fs.writeFileSync(target, await driver.get(blobKey(tenant, workspace, record.sha)));
+        }
+        brought.push(record.path);
+    }
+    fs.mkdirSync(root, { recursive: true });
+    return brought;
+}
+/**
+ * Take what the run left in `storage/` back into the store, stamped with the
+ * run that wrote it.
+ *
+ * Compares against the index rather than a pre-run snapshot: the mirror is
+ * 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) {
+    if (!fileStoreEnabled())
+        return { saved: [], errors: [] };
+    adoptLegacyFilesDir(workspaceDir(tenant, workspace));
+    const root = path.join(workspaceDir(tenant, workspace), STORAGE_DIR);
+    if (!fs.existsSync(root))
+        return { saved: [], errors: [] };
+    const known = new Map(readIndex(tenant, workspace).files.map((f) => [f.path, f]));
+    const saved = [];
+    const errors = [];
+    const out = [];
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue; // a symlink out of the tree is not a file
+            out.push(abs);
+        }
+    };
+    walk(root);
+    for (const abs of out) {
+        const rel = path.relative(root, abs).replaceAll("\\", "/");
+        try {
+            const norm = assertFilePath(rel);
+            const stat = fs.statSync(abs);
+            const previous = known.get(norm);
+            if (previous && previous.size === stat.size) {
+                // Same size is not proof, so confirm by hash before skipping a write.
+                if (sha256(fs.readFileSync(abs)) === previous.sha)
+                    continue;
+            }
+            await putFileQuietly(tenant, workspace, norm, fs.readFileSync(abs), by);
+            saved.push(norm);
+        }
+        catch (err) {
+            errors.push(`${rel}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (saved.length)
+        await announceFiles(tenant, workspace, saved, by);
+    return { saved, errors };
+}