@foldrun/core 8.0.1 → 9.0.0

package/dist/src/storage.js

@@ -50,6 +50,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { Readable } from "node:stream";
 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.
@@ -59,6 +60,29 @@ 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;
+/** The bytes a set of records occupies: distinct blobs, not records — two
+ *  names for identical bytes are one object. A size that is not a positive
+ *  number counts as nothing: indexes written before 30 Oct 2026 hold sizes a
+ *  browser claimed, and a negative one used to lower the total. */
+function bytesOf(files) {
+    const seen = new Map();
+    for (const f of files)
+        seen.set(f.sha, Number.isFinite(f.size) && f.size > 0 ? f.size : 0);
+    return [...seen.values()].reduce((a, b) => a + b, 0);
+}
+/**
+ * Refuse a workspace that is not there, as a 404 (30 Oct 2026).
+ *
+ * The store is keyed by workspace *name* and used to be created for any safe
+ * name on first write, so an editor got a fresh quota for every name they
+ * invented — stores no workspace list shows and no delete reaches. Every
+ * write here, and the routes that read, ask this first.
+ */
+export function requireWorkspace(tenant, workspace) {
+    if (!fs.existsSync(workspaceDir(tenant, workspace))) {
+        throw Object.assign(new Error(`workspace ${workspace} not found`), { status: 404 });
+    }
+}
 // ---------- paths ----------
 /**
  * Hosted only. On a laptop `storage/` is just a folder in the user's own
@@ -178,10 +202,7 @@ export function getFile(tenant, workspace, rel) {
 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);
+    return bytesOf(readIndex(tenant, workspace).files);
 }
 // ---------- fs driver ----------
 /** Where the fs driver keeps a blob. Exported because the run mirror
@@ -211,6 +232,19 @@ function fsDriver(tenant, workspace) {
         async has(key) {
             return fs.existsSync(at(key));
         },
+        async size(key) {
+            try {
+                const st = fs.statSync(at(key));
+                return st.isFile() ? st.size : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async open(key, range) {
+            const stream = fs.createReadStream(at(key), range ? { start: range.start, end: range.end } : {});
+            return Readable.toWeb(stream);
+        },
         async remove(key) {
             fs.rmSync(at(key), { force: true });
         },
@@ -338,17 +372,23 @@ function target(cfg, key) {
  * 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, creds, method, key, ttlSec, extraQuery = {}, now = new Date()) {
+function presign(cfg, creds, method, key, ttlSec, extraQuery = {}, now = new Date(), extraHeaders = {}) {
     const { host, origin, canonicalUri } = target(cfg, key);
     const { amzDate, dateStamp } = stamps(now);
     const scope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
+    // Headers the request must carry exactly as signed. `content-length` on an
+    // upload is the one that matters: the store then refuses a body of any
+    // other length, so a presigned PUT cannot be used to park 5 GB under a key
+    // that was asked for as 2 MB (30 Oct 2026).
+    const headers = { host, ...Object.fromEntries(Object.entries(extraHeaders).map(([k, v]) => [k.toLowerCase(), v])) };
+    const signed = Object.keys(headers).sort();
     const query = {
         ...extraQuery,
         "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
         "X-Amz-Credential": `${creds.accessKeyId}/${scope}`,
         "X-Amz-Date": amzDate,
         "X-Amz-Expires": String(ttlSec),
-        "X-Amz-SignedHeaders": "host",
+        "X-Amz-SignedHeaders": signed.join(";"),
         // A role's credentials are only valid with their token, and the token
         // is part of what is signed.
         ...(creds.sessionToken ? { "X-Amz-Security-Token": creds.sessionToken } : {}),
@@ -361,8 +401,8 @@ function presign(cfg, creds, method, key, ttlSec, extraQuery = {}, now = new Dat
         method,
         canonicalUri,
         canonicalQuery,
-        `host:${host}\n`,
-        "host",
+        signed.map((h) => `${h}:${headers[h].trim()}\n`).join(""),
+        signed.join(";"),
         "UNSIGNED-PAYLOAD",
     ].join("\n");
     const stringToSign = [
@@ -375,7 +415,7 @@ function presign(cfg, creds, method, key, ttlSec, extraQuery = {}, now = new Dat
     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) {
+async function s3Request(cfg, method, key, body, mime, extra = {}) {
     const creds = await credentials(cfg);
     const { host, origin, canonicalUri } = target(cfg, key);
     const { amzDate, dateStamp } = stamps(new Date());
@@ -387,6 +427,9 @@ async function s3Request(cfg, method, key, body, mime) {
         "x-amz-date": amzDate,
         ...(creds.sessionToken ? { "x-amz-security-token": creds.sessionToken } : {}),
         ...(mime ? { "content-type": mime } : {}),
+        // range on a streamed read, x-amz-copy-source on a copy. Lower-case,
+        // because the canonical form is.
+        ...Object.fromEntries(Object.entries(extra).map(([k, v]) => [k.toLowerCase(), v])),
     };
     const signed = Object.keys(headers).sort();
     const canonicalHeaders = signed.map((h) => `${h}:${headers[h].trim()}\n`).join("");
@@ -433,6 +476,31 @@ function s3Driver(cfg) {
             const res = await s3Request(cfg, "HEAD", key);
             return res.ok;
         },
+        async size(key) {
+            const res = await s3Request(cfg, "HEAD", key);
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                await fail(res, "head");
+            const n = Number(res.headers.get("content-length"));
+            return Number.isSafeInteger(n) && n >= 0 ? n : null;
+        },
+        async open(key, range) {
+            const res = await s3Request(cfg, "GET", key, undefined, undefined, range ? { range: `bytes=${range.start}-${range.end}` } : {});
+            if (!res.ok || !res.body)
+                await fail(res, "get");
+            return res.body;
+        },
+        async copy(from, to) {
+            // CopyObject: the bytes move inside the store, never through here.
+            const res = await s3Request(cfg, "PUT", to, undefined, undefined, {
+                "x-amz-copy-source": `/${cfg.bucket}/${uriEncode(from, true)}`,
+            });
+            // S3 can answer 200 with an <Error> body when a copy fails part-way.
+            const text = res.ok ? await res.text() : "";
+            if (!res.ok || /<Error>/.test(text))
+                throw new Error(`s3 copy failed: ${res.status} ${text.slice(0, 300)}`);
+        },
         async remove(key) {
             const res = await s3Request(cfg, "DELETE", key);
             // 404 on delete is the desired end state, not an error.
@@ -449,8 +517,8 @@ function s3Driver(cfg) {
                 "response-content-type": safe ?? mime,
             });
         },
-        async presignPut(key, _mime, ttlSec = 600) {
-            return presign(cfg, await credentials(cfg), "PUT", key, ttlSec);
+        async presignPut(key, _mime, ttlSec = 600, size) {
+            return presign(cfg, await credentials(cfg), "PUT", key, ttlSec, {}, new Date(), size === undefined ? {} : { "content-length": String(size) });
         },
     };
 }
@@ -499,6 +567,9 @@ async function announceFiles(tenant, workspace, paths, by) {
     }
 }
 export async function putFile(tenant, workspace, rel, body, by) {
+    // A person's upload. A run's harvest writes through putFileQuietly, into a
+    // workspace that was there when the run began.
+    requireWorkspace(tenant, workspace);
     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:"))
@@ -538,14 +609,23 @@ async function putFileQuietly(tenant, workspace, rel, body, by) {
     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) {
+ *  putFile, minus the bytes — the platform never saw them.
+ *
+ *  `_claimed` is the size the browser says it sent, kept for the callers that
+ *  pass it and never believed (30 Oct 2026): the record, the per-file limit
+ *  and the quota all use the length the store reports. It used to store the
+ *  claim, so an object registered as 0 bytes (or -1e12) sat outside every
+ *  limit and lowered the quota line for everything after it. */
+export async function registerUpload(tenant, workspace, rel, sha, _claimed, by) {
     const norm = assertFilePath(rel);
     if (!/^[0-9a-f]{64}$/.test(sha))
         throw new Error("expected a sha256");
+    requireWorkspace(tenant, workspace);
     const driver = driverFor(tenant, workspace);
-    // Trust nothing the browser said about whether the PUT landed.
-    if (!(await driver.has(blobKey(tenant, workspace, sha)))) {
+    const key = blobKey(tenant, workspace, sha);
+    // Trust nothing the browser said: not that the PUT landed, not its size.
+    const size = await driver.size(key);
+    if (size === null) {
         throw new Error("no object at that key — the upload did not complete");
     }
     const index = readIndex(tenant, workspace);
@@ -558,10 +638,22 @@ export async function registerUpload(tenant, workspace, rel, sha, size, by) {
         updatedAt: new Date().toISOString(),
         by,
     };
-    writeIndex(tenant, workspace, {
-        version: 1,
-        files: [...index.files.filter((f) => f.path !== norm), record],
-    });
+    const files = [...index.files.filter((f) => f.path !== norm), record];
+    // putFile's two limits, on the real length. A refused object is removed:
+    // nothing names it, so it would sit in the bucket unreachable and billed —
+    // unless a record already names these bytes, which are then not ours to drop.
+    const refuse = async (message) => {
+        if (!index.files.some((f) => f.sha === sha))
+            await driver.remove(key).catch(() => { });
+        throw new Error(message);
+    };
+    if (size > maxBytes()) {
+        await refuse(`${norm} is ${Math.round(size / 1e6)}MB — the limit is ${maxBytes() / 1e6}MB`);
+    }
+    if (bytesOf(files) > quotaBytes() && bytesOf(files) > bytesOf(index.files)) {
+        await refuse(`workspace file quota exceeded (${quotaBytes() / 1e6}MB)`);
+    }
+    writeIndex(tenant, workspace, { version: 1, files });
     if (previous && previous.sha !== sha)
         await collect(tenant, workspace, previous.sha);
     await announceFiles(tenant, workspace, [record.path], by);
@@ -573,6 +665,32 @@ export async function readFileBytes(tenant, workspace, rel) {
         return null;
     return driverFor(tenant, workspace).get(blobKey(tenant, workspace, record.sha));
 }
+/** A stored file's real length, from the store — a stat or a HEAD, never a
+ *  read. Null when there is no such record or no object behind it. */
+export async function storedSize(tenant, workspace, rel) {
+    const record = getFile(tenant, workspace, rel);
+    if (!record)
+        return null;
+    return driverFor(tenant, workspace).size(blobKey(tenant, workspace, record.sha));
+}
+/**
+ * A stored file as a stream, with its real length — for a route that passes
+ * the bytes on (a download, a public link) rather than reading them whole
+ * into memory. Null when there is no such record or no object behind it.
+ * `range` is inclusive and must lie inside the file (storedSize first, then
+ * byteRange, when the caller honours a Range header).
+ */
+export async function openFile(tenant, workspace, rel, range) {
+    const record = getFile(tenant, workspace, rel);
+    if (!record)
+        return null;
+    const driver = driverFor(tenant, workspace);
+    const key = blobKey(tenant, workspace, record.sha);
+    const size = await driver.size(key);
+    if (size === null)
+        return null;
+    return { record, size, body: await driver.open(key, range ?? undefined) };
+}
 export async function deleteFile(tenant, workspace, rel) {
     const norm = assertFilePath(rel);
     const index = readIndex(tenant, workspace);
@@ -624,11 +742,90 @@ export function previewType(rel) {
     return PREVIEW_TYPES[path.extname(rel).toLowerCase()] ?? null;
 }
 /** 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);
+export async function uploadUrl(tenant, workspace, rel, sha, size) {
+    const norm = 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));
+    requireWorkspace(tenant, workspace);
+    // The limits, before a byte moves, and the length signed into the URL so
+    // the bucket refuses any other (30 Oct 2026). registerUpload checks the
+    // real object again; this is what keeps an oversized one from ever landing
+    // — an object that is PUT and never registered was otherwise unbounded.
+    if (size !== undefined) {
+        if (!Number.isSafeInteger(size) || size <= 0)
+            throw new Error("size must be the file's length in bytes, a whole number above 0");
+        if (size > maxBytes())
+            throw new Error(`${norm} is ${Math.round(size / 1e6)}MB — the limit is ${maxBytes() / 1e6}MB`);
+        const files = readIndex(tenant, workspace).files;
+        const next = [...files.filter((f) => f.path !== norm), { sha, size }];
+        if (bytesOf(next) > quotaBytes() && bytesOf(next) > bytesOf(files)) {
+            throw new Error(`workspace file quota exceeded (${quotaBytes() / 1e6}MB)`);
+        }
+    }
+    return driverFor(tenant, workspace).presignPut(blobKey(tenant, workspace, sha), mimeFor(norm), undefined, size);
+}
+// ---------- a workspace deleted or renamed ----------
+/** The store's directory for a name, without the workspace check —
+ *  for the two calls below, which run when the folder is gone or moving. */
+function storeDirOf(tenant, workspace) {
+    if (!fileStoreEnabled())
+        return null;
+    return storeDir(tenant, workspace);
+}
+/**
+ * Drop everything a workspace stored: every object its index names, then the
+ * index (30 Oct 2026). Called when a workspace is deleted — the store is kept
+ * by name beside the folder, so it used to outlive it: the files stayed
+ * downloadable under the old name, public links kept serving them, and a new
+ * workspace given the same name inherited them. Best effort per object (a
+ * leaked object costs storage; the index going is what makes them
+ * unreachable), and a no-op when there is no store.
+ */
+export async function purgeWorkspaceStorage(tenant, workspace) {
+    const dir = storeDirOf(tenant, workspace);
+    if (!dir || !fs.existsSync(dir))
+        return;
+    const driver = driverFor(tenant, workspace);
+    if (driver.kind !== "fs") {
+        const shas = new Set(readIndex(tenant, workspace).files.map((f) => f.sha));
+        for (const sha of shas)
+            await driver.remove(blobKey(tenant, workspace, sha)).catch(() => { });
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+}
+/**
+ * Move a workspace's stored files to its new name (30 Oct 2026). A rename
+ * used to move the folder only: the renamed workspace lost its files, and
+ * the old name kept them for whoever took it next.
+ *
+ * On fs the blobs live under the store's directory, so moving the directory
+ * is the whole move. On s3 an object's key carries the workspace name, so
+ * every object is copied first; only once all copies landed does the index
+ * move and the old objects go. A copy that fails leaves the store under the
+ * old name, whole, and throws — the caller can put the folder back.
+ *
+ * Whatever a store under the new name held is dropped first: it belonged to a
+ * workspace of that name that no longer exists, never to this one.
+ */
+export async function moveWorkspaceStorage(tenant, from, to) {
+    const src = storeDirOf(tenant, from);
+    const dest = storeDirOf(tenant, to);
+    if (!src || !dest || src === dest)
+        return;
+    if (fs.existsSync(dest))
+        await purgeWorkspaceStorage(tenant, to);
+    if (!fs.existsSync(src))
+        return;
+    const driver = driverFor(tenant, from);
+    const shas = driver.kind === "fs" ? [] : [...new Set(readIndex(tenant, from).files.map((f) => f.sha))];
+    if (shas.length && !driver.copy)
+        throw new Error(`the ${driver.kind} store cannot move files to a new workspace name`);
+    for (const sha of shas)
+        await driver.copy(blobKey(tenant, from, sha), blobKey(tenant, to, sha));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.renameSync(src, dest);
+    for (const sha of shas)
+        await driver.remove(blobKey(tenant, from, sha)).catch(() => { });
 }
 // ---------- the run mirror ----------
 /**

package/dist/src/store.d.ts

@@ -54,6 +54,16 @@ export declare function adoptLegacyFilesDir(parent: string): void;
  */
 export declare function adoptLegacyVersionKey(dir: string): void;
 export declare function assertSafeName(name: string, kind: string): void;
+/**
+ * A name that is ONE folder under its parent — agents/<name>, never a path.
+ * Wider than SAFE_NAME on purpose: an agent imported from
+ * `.claude/agents/code_reviewer.md` keeps that file's name, and a run of it
+ * must keep working. What it refuses is what makes a name a path: a
+ * separator, a dot segment, a NUL. 30 Oct 2026: POST …/agents/<agent>/run
+ * and the runner joined the name unchecked, so `..%2F..%2F<tenant>%2F…`
+ * reached another account's agent.
+ */
+export declare function isOneSegment(name: unknown): name is string;
 export declare function workspaceDir(tenant: string, workspace: string): string;
 /**
  * The account root — where `library/`, account secrets and the account-wide
@@ -908,8 +918,16 @@ export declare function renameImpact(tenant: string, workspace: string): {
  * there is nothing to migrate and nothing to lose.
  */
 export declare function renameWorkspace(tenant: string, from: string, to: string): void;
-/** Set a workspace's description, in AGENTS.md, without touching anything else. */
-export declare function setWorkspaceDescription(tenant: string, workspace: string, description: string): void;
+/** Set a workspace's description, in AGENTS.md, without touching anything else.
+ *
+ *  30 Oct 2026: the value was spliced in as `description: ${text}`, so a
+ *  newline in it wrote any other key (notify:, network_enforce:, past the
+ *  settings' allowed list), and String.replace read `$'` / `$&` in it as
+ *  patterns; the write went around writeWorkspaceFile, so History never saw
+ *  it. Now the key is written as YAML (patchFrontmatter, which reads the
+ *  result back and refuses an edit that changed any other key) and saved
+ *  through writeWorkspaceFile, as a revision. */
+export declare function setWorkspaceDescription(tenant: string, workspace: string, description: string, meta?: ChangeMeta): void;
 /**
  * Starter files for "+ New workspace" in the dashboard.
  *

package/dist/src/store.js

@@ -24,12 +24,12 @@ import { expandPlatformVars } from "./host-env.js";
 import { FLOW_TRIGGERS } from "./frontmatter-fields.js";
 import fs from "node:fs";
 import path from "node:path";
-import { recordRevision, registerTreeReader } from "./history.js";
+import { recordRevision, registerTreeReader, assertCommitId } from "./history.js";
 import { dataRoot, singleWorkspace, singleAccountRoot, entriesNoFollow } from "./paths.js";
 import { platform } from "./platform.js";
 import { toLF, asRaw } from "./eol.js";
 import matter, { frontmatterErrorText, configMatter } from "./matter.js";
-import { readAgentsMdKeys } from "./agents-md.js";
+import { readAgentsMdKeys, patchFrontmatter } from "./agents-md.js";
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
  * for the CLI: `foldrun probe` used to import gray-matter itself, which is
@@ -174,6 +174,18 @@ export function assertSafeName(name, kind) {
     if (!SAFE_NAME.test(name))
         throw new Error(`invalid ${kind} "${name}" — kebab-case only`);
 }
+/**
+ * A name that is ONE folder under its parent — agents/<name>, never a path.
+ * Wider than SAFE_NAME on purpose: an agent imported from
+ * `.claude/agents/code_reviewer.md` keeps that file's name, and a run of it
+ * must keep working. What it refuses is what makes a name a path: a
+ * separator, a dot segment, a NUL. 30 Oct 2026: POST …/agents/<agent>/run
+ * and the runner joined the name unchecked, so `..%2F..%2F<tenant>%2F…`
+ * reached another account's agent.
+ */
+export function isOneSegment(name) {
+    return typeof name === "string" && name !== "" && name !== "." && name !== ".." && !/[/\\\0]/.test(name);
+}
 export function workspaceDir(tenant, workspace) {
     const single = singleWorkspace();
     if (single)
@@ -343,6 +355,10 @@ export function saveWorkspace(tenant, workspace, files,
 meta = {}) {
     if (files.length > 500)
         throw new Error("too many files");
+    // The commit becomes the revision's id: refused here, before the tree is
+    // replaced, never after it (history.ts assertCommitId).
+    if (meta.commit)
+        assertCommitId(meta.commit);
     for (const f of files) {
         const norm = path.normalize(f.path);
         if (norm.startsWith("..") || path.isAbsolute(norm) || norm.startsWith("runs")) {
@@ -2377,6 +2393,14 @@ export function writeWorkspaceFile(tenant, workspace, rel, content, meta = {}) {
         throw new Error("file too large");
     matter(content); // reject files whose frontmatter doesn't parse
     const dir = workspaceDir(tenant, workspace);
+    // A write goes INTO a workspace; it never makes one. The mkdir below is
+    // recursive, so until 30 Oct 2026 a write to a name that did not exist
+    // created that workspace — with workspace:write alone, past the
+    // workspace:manage role and the plan's workspace count that POST
+    // /api/workspaces, deploy and import apply. Those create through
+    // saveWorkspace / applyImport, not through here.
+    if (!fs.existsSync(dir))
+        throw Object.assign(new Error(`workspace ${workspace} not found`), { status: 404 });
     const p = path.join(dir, assertEditablePath(rel));
     // Before anything is created: mkdir below would otherwise make folders
     // through a linked directory too.
@@ -2587,6 +2611,15 @@ export function deleteWorkspace(tenant, workspace) {
     if (!fs.existsSync(dir))
         throw new Error(`workspace ${workspace} not found`);
     fs.rmSync(dir, { recursive: true, force: true });
+    // Its file store too, kept by name beside the folder (storage.ts). Until
+    // 30 Oct 2026 the store outlived the delete: its files stayed downloadable
+    // and shared, and the next workspace given this name inherited them. The
+    // index going is what makes them unreachable; the API route first calls
+    // purgeWorkspaceStorage, which also removes the objects from a bucket
+    // (async, so it cannot live in here).
+    if (!singleWorkspace()) {
+        fs.rmSync(path.join(dataRoot(), tenant, STORAGE_DIR, workspace), { recursive: true, force: true });
+    }
     workspaceChanged(tenant, workspace, "delete");
 }
 /**
@@ -2634,24 +2667,26 @@ export function renameWorkspace(tenant, from, to) {
         fs.writeFileSync(agentsMd, raw.replace(/^name:.*$/m, `name: ${to}`));
     }
 }
-/** Set a workspace's description, in AGENTS.md, without touching anything else. */
-export function setWorkspaceDescription(tenant, workspace, description) {
+/** Set a workspace's description, in AGENTS.md, without touching anything else.
+ *
+ *  30 Oct 2026: the value was spliced in as `description: ${text}`, so a
+ *  newline in it wrote any other key (notify:, network_enforce:, past the
+ *  settings' allowed list), and String.replace read `$'` / `$&` in it as
+ *  patterns; the write went around writeWorkspaceFile, so History never saw
+ *  it. Now the key is written as YAML (patchFrontmatter, which reads the
+ *  result back and refuses an edit that changed any other key) and saved
+ *  through writeWorkspaceFile, as a revision. */
+export function setWorkspaceDescription(tenant, workspace, description, meta = {}) {
     const file = path.join(workspaceDir(tenant, workspace), "AGENTS.md");
     if (!fs.existsSync(file))
         throw new Error("this workspace has no AGENTS.md");
     const raw = fs.readFileSync(file, "utf8");
-    const block = raw.match(/^(---\r?\n)([\s\S]*?)(\r?\n---)/);
-    if (!block)
+    if (!/^---\r?\n[\s\S]*?\r?\n---/.test(raw))
         throw new Error("AGENTS.md has no frontmatter");
-    const [, open, body, close] = block;
-    const lines = body.split("\n");
-    const at = lines.findIndex((l) => /^description:/.test(l));
-    const line = `description: ${description}`;
-    if (at === -1)
-        lines.push(line);
-    else
-        lines[at] = line;
-    fs.writeFileSync(file, raw.replace(open + body + close, open + lines.join("\n") + close));
+    writeWorkspaceFile(tenant, workspace, "AGENTS.md", patchFrontmatter(raw, { description }), {
+        message: "settings: description",
+        ...meta,
+    });
 }
 /**
  * Starter files for "+ New workspace" in the dashboard.

package/dist/src/webhook.js

@@ -42,7 +42,11 @@ export function rotateWebhook(tenant, workspace, flow) {
     const hooks = readHooks(tenant, workspace);
     hooks[flow] = { gen: (hooks[flow]?.gen ?? 0) + 1, rotatedAt: new Date().toISOString() };
     const file = hooksFile(tenant, workspace);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
+    // Into a workspace that exists, never making one (30 Oct 2026): the mkdir
+    // here turned a rotate under a mistyped name into a workspace holding only
+    // hooks.json, past the plan's workspace count.
+    if (!fs.existsSync(path.dirname(file)))
+        throw Object.assign(new Error(`workspace ${workspace} not found`), { status: 404 });
     fs.writeFileSync(file, JSON.stringify(hooks, null, 2));
     return webhookPath(tenant, workspace, flow);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "8.0.1",
+  "version": "9.0.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "FSL-1.1-ALv2",
   "type": "module",

package/src/history.ts

@@ -98,6 +98,16 @@ const historyDir = (tenant: string, scope: string) => {
   return path.join(dataRoot(), tenant, ".history", scope);
 };
 
+/** Refuse (400) a deploy's `commit` that cannot be a revision id. A writer
+ *  calls this BEFORE it writes: checked only in recordRevision, after the
+ *  files were replaced, a bad commit left the new source live with no
+ *  revision, no snapshot and no audit entry (30 Oct 2026). */
+export function assertCommitId(commit: string) {
+  if (typeof commit !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._@-]{0,120}$/.test(commit)) {
+    throw Object.assign(new Error(`commit "${String(commit).slice(0, 130)}" is not a commit id — letters, digits and . _ @ -, at most 121 characters`), { status: 400 });
+  }
+}
+
 /** A local revision id: sortable by time, unique enough, visibly not a sha. */
 export function newRevisionId(now = new Date()): string {
   return `r-${now.getTime().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
@@ -121,8 +131,16 @@ export function recordRevision(
 
   const dir = historyDir(tenant, scope);
   fs.mkdirSync(dir, { recursive: true });
+  // A commit is the revision's id only the first time it is recorded. A
+  // second deploy of one commit (a CI re-run after a dashboard edit), or a
+  // `commit` that names a revision already here, overwrote that revision's
+  // record and its snapshot (30 Oct 2026) — History could no longer restore
+  // to it. It gets its own id now; `commit` still says which one it was,
+  // and a restore by commit (resolveRevision) still finds it.
+  if (meta.commit) assertCommitId(meta.commit);
+  const commitId = meta.commit && !fs.existsSync(path.join(dir, `${meta.commit}.json`)) ? meta.commit : null;
   const rev: Revision = {
-    id: meta.id ?? meta.commit ?? newRevisionId(),
+    id: meta.id ?? commitId ?? newRevisionId(),
     at: new Date().toISOString(),
     by: meta.by ?? "system",
     message: meta.message ?? describe(changed),
@@ -301,7 +319,11 @@ export function resolveRevision(
     hit = all.find((r) => Date.parse(r.at) <= moment);
   } else {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/.test(t)) throw Object.assign(new Error(`not a revision or a time: ${to}`), { status: 400 });
-    hit = all.find((r) => r.id === t || r.commit === t || (t.length >= 7 && r.commit?.startsWith(t)));
+    // An exact id first, then a commit: a commit deployed twice is recorded
+    // once under its own id and again under a fresh one naming it (30 Oct
+    // 2026, recordRevision), and newest-first with one predicate answered
+    // the first revision's id with the second's snapshot.
+    hit = all.find((r) => r.id === t) ?? all.find((r) => r.commit === t || (t.length >= 7 && r.commit?.startsWith(t)));
   }
   return hit ? { id: hit.id, at: hit.at, by: hit.by, message: hit.message } : null;
 }
@@ -409,8 +431,13 @@ export function changedPathsBetween(tenant: string, scope: string, from: string
   if (!from || !to) return null;
   if (from === to) return [];
   const revs = listRevisions(tenant, scope, { limit: 500 }); // newest first
-  const ti = revs.findIndex((r) => r.id === to || r.commit === to);
-  const fi = revs.findIndex((r) => r.id === from || r.commit === from);
+  // An exact id before a commit, as resolveRevision.
+  const at = (x: string) => {
+    const byId = revs.findIndex((r) => r.id === x);
+    return byId >= 0 ? byId : revs.findIndex((r) => r.commit === x);
+  };
+  const ti = at(to);
+  const fi = at(from);
   if (ti < 0 || fi < 0 || ti > fi) return null;
   return [...new Set(revs.slice(ti, fi).flatMap((r) => r.paths))].sort();
 }

package/src/hooks.ts

@@ -44,6 +44,11 @@ export const HOOK_TIMEOUT_MAX = 120;
 export const HOOK_CODE_MAX = 100 * 1024;
 const NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
 
+/** A hook's name: its folder's name, never a path. */
+export function isHookName(name: unknown): name is string {
+  return typeof name === "string" && NAME.test(name);
+}
+
 export interface HookDef {
   name: string;
   /** The folder holding hook.md and run.mjs. */
@@ -139,6 +144,15 @@ export function resolveHooks(args: {
   for (const name of args.names) {
     if (seen.has(name)) continue;
     seen.add(name);
+    // Checked before the name is joined to anything (30 Oct 2026): readHookDef
+    // tested only basename(dir), so `../../<tenant>/workspaces/<ws>/hooks/<h>`
+    // passed, and the hook test route answered which folders exist anywhere
+    // on the server — on a laptop it would have run that run.mjs. An error,
+    // not missing: a step refuses either way, and the name is the problem.
+    if (!isHookName(name)) {
+      errors.push(`"${name}" is not a hook name — lowercase letters, digits and dashes (the hook's folder name)`);
+      continue;
+    }
     const own = path.join(args.workspaceRoot, "hooks", name);
     const shared = path.join(args.libraryRoot, "hooks", name);
     const dir = fs.existsSync(own) ? own : fs.existsSync(shared) ? shared : null;

package/src/library.ts

@@ -282,6 +282,9 @@ export function deleteLibraryPath(
 ) {
   const norm = path.normalize(rel);
   if (norm.startsWith("..") || path.isAbsolute(norm)) throw new Error(`illegal path: ${rel}`);
+  // "." (or "./", "a/..") is the shelf itself: one call took every shared
+  // tool or skill from every workspace (30 Oct 2026). Name what goes.
+  if (norm === "." || norm === "./") throw new Error(`illegal path: ${rel} — name the file or folder to delete, not the whole ${kind} shelf`);
   const target = path.join(libraryDir(tenant, kind), norm);
   const gone: { path: string; before: string | null; after: null }[] = [];
   if (fs.existsSync(target)) {