@foldrun/core 8.0.1 → 9.1.0

package/src/storage.ts

@@ -51,6 +51,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.ts";
 import { assertSafeName, workspaceDir, STORAGE_DIR, adoptLegacyFilesDir } from "./store.ts";
 
@@ -85,6 +86,30 @@ interface Index {
 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: Pick<FileRecord, "sha" | "size">[]): number {
+  const seen = new Map<string, number>();
+  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: string, workspace: string): void {
+  if (!fs.existsSync(workspaceDir(tenant, workspace))) {
+    throw Object.assign(new Error(`workspace ${workspace} not found`), { status: 404 });
+  }
+}
+
 // ---------- paths ----------
 
 /**
@@ -212,9 +237,7 @@ export function getFile(tenant: string, workspace: string, rel: string): FileRec
 export function usedBytes(tenant: string, workspace: string): number {
   // 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<string, number>();
-  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);
 }
 
 // ---------- the driver interface ----------
@@ -224,6 +247,15 @@ export interface Driver {
   put(key: string, body: Buffer, mime: string): Promise<void>;
   get(key: string): Promise<Buffer>;
   has(key: string): Promise<boolean>;
+  /** The object's real length, or null when there is none — what the store
+   *  holds, never what a browser said it sent (30 Oct 2026). */
+  size(key: string): Promise<number | null>;
+  /** The bytes as a stream, optionally one inclusive byte range — so a route
+   *  hands a file on without holding all of it in memory. */
+  open(key: string, range?: { start: number; end: number }): Promise<ReadableStream<Uint8Array>>;
+  /** Server-side copy to another key (s3 only — the fs driver's blobs move
+   *  with their directory). Used when a workspace is renamed. */
+  copy?(from: string, to: string): Promise<void>;
   remove(key: string): Promise<void>;
   /** A URL a browser can GET directly, or null when the driver has no such
    *  thing (fs) and the route must stream the bytes itself. */
@@ -232,7 +264,9 @@ export interface Driver {
   presignGet(key: string, filename: string, mime: string, ttlSec?: number, inlineType?: string): Promise<string | null>;
   /** A URL a browser can PUT directly to, so upload bytes never transit the
    *  dashboard process. Null on fs, where the route takes the body. */
-  presignPut(key: string, mime: string, ttlSec?: number): Promise<string | null>;
+  /** `size`: sign the length in, so the store refuses a PUT of any other
+   *  length (30 Oct 2026) — the per-file limit then holds at the bucket. */
+  presignPut(key: string, mime: string, ttlSec?: number, size?: number): Promise<string | null>;
 }
 
 // ---------- fs driver ----------
@@ -264,6 +298,18 @@ function fsDriver(tenant: string, workspace: string): Driver {
     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) as unknown as ReadableStream<Uint8Array>;
+    },
     async remove(key) {
       fs.rmSync(at(key), { force: true });
     },
@@ -435,10 +481,17 @@ function presign(
   ttlSec: number,
   extraQuery: Record<string, string> = {},
   now = new Date(),
+  extraHeaders: Record<string, string> = {},
 ): string {
   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: Record<string, string> = { host, ...Object.fromEntries(Object.entries(extraHeaders).map(([k, v]) => [k.toLowerCase(), v])) };
+  const signed = Object.keys(headers).sort();
 
   const query: Record<string, string> = {
     ...extraQuery,
@@ -446,7 +499,7 @@ function presign(
     "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 } : {}),
@@ -460,8 +513,8 @@ function presign(
     method,
     canonicalUri,
     canonicalQuery,
-    `host:${host}\n`,
-    "host",
+    signed.map((h) => `${h}:${headers[h].trim()}\n`).join(""),
+    signed.join(";"),
     "UNSIGNED-PAYLOAD",
   ].join("\n");
 
@@ -483,6 +536,7 @@ async function s3Request(
   key: string,
   body?: Buffer,
   mime?: string,
+  extra: Record<string, string> = {},
 ): Promise<Response> {
   const creds = await credentials(cfg);
   const { host, origin, canonicalUri } = target(cfg, key);
@@ -496,6 +550,9 @@ async function s3Request(
     "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("");
@@ -545,6 +602,27 @@ function s3Driver(cfg: S3Config): Driver {
       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 as ReadableStream<Uint8Array>;
+    },
+    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.
@@ -560,8 +638,8 @@ function s3Driver(cfg: S3Config): Driver {
         "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) });
     },
   };
 }
@@ -619,6 +697,9 @@ export async function putFile(
   body: Buffer,
   by: string,
 ): Promise<FileRecord> {
+  // 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:")) await announceFiles(tenant, workspace, [record.path], by);
@@ -666,20 +747,29 @@ async function putFileQuietly(
 }
 
 /** Register bytes a browser PUT straight to the bucket. Same bookkeeping as
- *  putFile, minus the bytes — the platform never saw them. */
+ *  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: string,
   workspace: string,
   rel: string,
   sha: string,
-  size: number,
+  _claimed: number,
   by: string,
 ): Promise<FileRecord> {
   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);
@@ -692,10 +782,21 @@ export async function registerUpload(
     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: string): Promise<never> => {
+    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);
   return record;
@@ -711,6 +812,36 @@ export async function readFileBytes(
   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: string, workspace: string, rel: string): Promise<number | null> {
+  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: string,
+  workspace: string,
+  rel: string,
+  range?: { start: number; end: number } | null,
+): Promise<{ record: FileRecord; size: number; body: ReadableStream<Uint8Array> } | null> {
+  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: string, workspace: string, rel: string): Promise<boolean> {
   const norm = assertFilePath(rel);
   const index = readIndex(tenant, workspace);
@@ -779,10 +910,83 @@ export async function uploadUrl(
   workspace: string,
   rel: string,
   sha: string,
+  size?: number,
 ): Promise<string | null> {
-  assertFilePath(rel);
+  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: string, workspace: string): string | null {
+  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: string, workspace: string): Promise<void> {
+  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: string, from: string, to: string): Promise<void> {
+  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/src/store.ts

@@ -26,14 +26,14 @@ import { EFFORT_LEVELS, FLOW_TRIGGERS } from "./frontmatter-fields.ts";
 import type { BrowserPodOutcome } from "./browser-pod.ts";
 import fs from "node:fs";
 import path from "node:path";
-import { recordRevision, registerTreeReader, type RevisionFile } from "./history.ts";
+import { recordRevision, registerTreeReader, assertCommitId, type RevisionFile } from "./history.ts";
 import { dataRoot, singleWorkspace, singleAccountRoot, entriesNoFollow } from "./paths.ts";
 import { platform } from "./platform.ts";
 import { toLF, asRaw } from "./eol.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { OperatorEvent } from "./operator.ts";
 import matter, { frontmatterErrorText, configMatter } from "./matter.ts";
-import { readAgentsMdKeys } from "./agents-md.ts";
+import { readAgentsMdKeys, patchFrontmatter } from "./agents-md.ts";
 
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
@@ -184,6 +184,19 @@ export function assertSafeName(name: string, kind: string) {
   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: unknown): name is string {
+  return typeof name === "string" && name !== "" && name !== "." && name !== ".." && !/[/\\\0]/.test(name);
+}
+
 export function workspaceDir(tenant: string, workspace: string) {
   const single = singleWorkspace();
   if (single) return path.resolve(single);
@@ -382,6 +395,9 @@ export function saveWorkspace(
   } = {},
 ) {
   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")) {
@@ -2856,6 +2872,13 @@ export function writeWorkspaceFile(
   if (content.length > MAX_EDITABLE_FILE) 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.
@@ -3069,6 +3092,15 @@ export function deleteWorkspace(tenant: string, workspace: string) {
   const dir = workspaceDir(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");
 }
 
@@ -3120,23 +3152,26 @@ export function renameWorkspace(tenant: string, from: string, to: string) {
   }
 }
 
-/** Set a workspace's description, in AGENTS.md, without touching anything else. */
-export function setWorkspaceDescription(tenant: string, workspace: string, description: string) {
+/** 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: string, workspace: string, description: string, meta: ChangeMeta = {}) {
   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) throw new Error("AGENTS.md has no frontmatter");
+  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,
+  });
 }
 
 /**

package/src/triggers.ts

@@ -15,7 +15,7 @@
 import crypto from "node:crypto";
 import { platform } from "./platform.ts";
 import { listFlows, readRun, runVerdict, type FlowInfo, type FlowStep, type RunRecord } from "./store.ts";
-import { getSecret } from "./secrets.ts";
+import { getSecret, signingSecretShown } from "./secrets.ts";
 
 /** The last step's result — the same reading runner.ts makes, kept local so
  *  this module never imports the runner (the queue imports both). */
@@ -273,7 +273,7 @@ export function verifyWebhookSignature(
   if (!flow.signature) return { ok: true, reason: "no signature required" };
   if (!flow.signingSecret) return { ok: false, reason: `signature: ${flow.signature} needs signing_secret: \${NAME}` };
   const secret = getSecret(tenant, flow.signingSecret, workspace);
-  if (!secret) return { ok: false, reason: `signing secret ${flow.signingSecret} is not set` };
+  if (!secret) return { ok: false, reason: `signing secret ${signingSecretShown(flow.signingSecret)} is not set` };
   const hmac = (data: string) => crypto.createHmac("sha256", secret.value).update(data).digest("hex");
   const fresh = (ts: number) => Math.abs(now / 1000 - ts) <= 300;
 

package/src/webhook.ts

@@ -57,7 +57,10 @@ export function rotateWebhook(tenant: string, workspace: string, flow: string):
   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);
 }
@@ -93,22 +96,39 @@ export function approveToken(tenant: string, workspace: string, runId: string):
     .slice(0, 32);
 }
 
+/** One parked `wait: event` gate: the step's index in the run record and
+ *  the moment it parked (the `t` of its "waiting for an external event"
+ *  trace line). */
+export interface EventGate {
+  step: number;
+  at: string;
+}
+
 /**
  * The token that releases a run parked on `wait: event`. Its own HMAC
  * family, so an approval link cannot double as an event URL or the reverse.
+ *
+ * With `gate`, the token is for that one park of that one step (30 Oct
+ * 2026). The per-run token released every later `wait: event` of the run,
+ * so a URL handed to a third party for the first gate also opened the
+ * second, and never expired. A gate's token dies with its park: the step
+ * released is no longer waiting, and parking again (a loop) stamps a new
+ * `at`. The per-run form, without `gate`, is what URLs printed before then
+ * carry — the events route still takes it for a step parked under it.
  */
-export function eventToken(tenant: string, workspace: string, runId: string): string {
+export function eventToken(tenant: string, workspace: string, runId: string, gate?: EventGate): string {
   return crypto
     .createHmac("sha256", installKey())
-    .update(`event:${tenant}/${workspace}/${runId}`)
+    .update(gate ? `event:${tenant}/${workspace}/${runId}#${gate.step}@${gate.at}` : `event:${tenant}/${workspace}/${runId}`)
     .digest("hex")
     .slice(0, 32);
 }
 
 /** The URL a `wait: event` step is released at — absolute when the install
- *  knows its origin, a path otherwise. */
-export function eventUrl(tenant: string, workspace: string, runId: string): string {
-  const p = `/api/events/${tenant}/${workspace}/${runId}?token=${eventToken(tenant, workspace, runId)}`;
+ *  knows its origin, a path otherwise. With `gate`, that step's own URL
+ *  (`&step=<index>`); the route finds the park's moment on the record. */
+export function eventUrl(tenant: string, workspace: string, runId: string, gate?: EventGate): string {
+  const p = `/api/events/${tenant}/${workspace}/${runId}?token=${eventToken(tenant, workspace, runId, gate)}${gate ? `&step=${gate.step}` : ""}`;
   const base = publicUrl();
   return base ? `${base}${p}` : p;
 }