@foldrun/core 8.0.1 → 9.1.0

package/dist/src/notify.js

@@ -33,7 +33,8 @@
 import crypto from "node:crypto";
 import { readAgentsMd } from "./runner.js";
 import { accountDir, workspaceDir, runCost, readFlow, runVerdict } from "./store.js";
-import { getSecret } from "./secrets.js";
+import { getSecret, secretSites, signingSecretShown, accountSecretUsableIn } from "./secrets.js";
+import { siteCovers } from "./network.js";
 import { publicUrl } from "./webhook.js";
 import { approveLinkPath, approveLinkTtlMs } from "./approvals.js";
 import { noteSecretUse, healthKey } from "./secret-health.js";
@@ -61,12 +62,16 @@ export function platformMail(tenant) {
         return { key, from: platform.setting("FOLDRUN_EMAIL_FROM") || "foldrun <hello@foldrun.io>" };
     return own;
 }
-/** The account's own Resend key and sender, or null when it has none. */
-export function accountMail(tenant) {
-    const own = getSecret(tenant, "RESEND_API_KEY");
+/** The account's own Resend key and sender, or null when it has none.
+ *  With a workspace — mail a workspace's run causes — an account key or
+ *  sender limited to other workspaces is not used (30 Oct 2026); the
+ *  account's own mail (resets, invites) names none and is not limited. */
+export function accountMail(tenant, workspace) {
+    const usable = (name) => !workspace || accountSecretUsableIn(tenant, name, workspace);
+    const own = usable("RESEND_API_KEY") ? getSecret(tenant, "RESEND_API_KEY") : null;
     if (!own)
         return null;
-    const from = getSecret(tenant, "EMAIL_FROM")?.value?.trim() || "foldrun <onboarding@resend.dev>";
+    const from = (usable("EMAIL_FROM") ? getSecret(tenant, "EMAIL_FROM")?.value?.trim() : "") || "foldrun <onboarding@resend.dev>";
     return { key: own.value, from };
 }
 /**
@@ -79,8 +84,17 @@ export function accountMail(tenant) {
  * owner's bin. The platform's key is the fallback for an account that set
  * none, so `notify:` works before anyone has configured mail at all.
  */
-export function notifyMail(tenant) {
-    return accountMail(tenant) ?? platformMail(tenant);
+export function notifyMail(tenant, workspace) {
+    if (!workspace)
+        return accountMail(tenant) ?? platformMail(tenant);
+    // A workspace's notification: the account's sender only where it may be
+    // used, else the platform's — never platformMail's fall back to the
+    // account's own key, which would walk around the limit.
+    const own = accountMail(tenant, workspace);
+    if (own)
+        return own;
+    const key = process.env.FOLDRUN_RESEND_API_KEY;
+    return key ? { key, from: platform.setting("FOLDRUN_EMAIL_FROM") || "foldrun <hello@foldrun.io>" } : null;
 }
 /** Was the mail sent on the account's own key? Only then is a refusal from
  *  Resend a fact about a secret the account holds. Recording a platform-key
@@ -145,7 +159,7 @@ export function signatureHeaders(tenant, workspace, config, body) {
         return {};
     const secret = getSecret(tenant, config.signingSecret, workspace);
     if (!secret) {
-        console.error(`[foldrun] notify: signing_secret names ${config.signingSecret}, which is not in the vault for ${tenant}/${workspace} — sending unsigned`);
+        console.error(`[foldrun] notify: signing_secret names ${signingSecretShown(config.signingSecret)}, which is not in the vault for ${tenant}/${workspace} — sending unsigned`);
         return {};
     }
     const timestamp = Math.floor(Date.now() / 1000).toString();
@@ -180,15 +194,80 @@ export function newDeliveryId() {
     return `dlv_${crypto.randomUUID().replace(/-/g, "")}`;
 }
 /** The URL with ${SECRET}s resolved, and how it may be shown: a Slack hook
- *  URL is itself a credential, so it is never echoed resolved. */
+ *  URL is itself a credential, so it is never echoed resolved.
+ *
+ *  A secret bound to sites (`foldrun secrets sites`) is filled only when the
+ *  resolved URL's host is one of them — the rule the egress proxy and the
+ *  tool tester keep (30 Oct 2026). Before, notify.url filled any secret into
+ *  any host, so an editor could write `https://their.server/?k=${STRIPE_KEY}`
+ *  and press Test. The host is read AFTER filling, because the usual shape is
+ *  the whole URL as one secret (`${SLACK_WEBHOOK_URL}`, bound to
+ *  hooks.slack.com). An unbound secret fills as it does for an agent's
+ *  `secrets:` and a tool test — workspace first, then the account — since
+ *  binding is how an account says where a value may go. `refused` says why
+ *  `url` is null when a binding stopped it; `filled` maps each value put
+ *  into the URL to its name, so an error that echoes the URL can be scrubbed. */
 export function webhookTarget(tenant, workspace, config = notifyConfig(tenant, workspace)) {
     const raw = config?.url ?? "";
+    const filled = {};
+    // Every name put in, kept apart from `filled` (value → name, for
+    // scrubbing): two secrets with the same value would otherwise leave only
+    // the last name there, and the first one's binding would go unchecked.
+    const used = new Set();
     const url = raw.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => {
         const hit = getSecret(tenant, name, workspace);
+        if (hit) {
+            filled[hit.value] = name;
+            used.add(name);
+        }
         return hit ? hit.value : whole;
     });
     const shown = raw.includes("${") ? raw : raw ? `${raw.slice(0, 40)}${raw.length > 40 ? "…" : ""}` : "none";
-    return { url: !url || url.includes("${") ? null : url, shown };
+    if (!url || url.includes("${"))
+        return { url: null, shown, filled: {} };
+    const bound = secretSites(tenant, [...used], workspace);
+    if (Object.keys(bound).length) {
+        let host = "";
+        try {
+            host = new URL(url).hostname;
+        }
+        catch {
+            // Not a URL: no host can be one of its sites.
+        }
+        const offSite = Object.entries(bound).filter(([, sites]) => !host || !sites.some((site) => siteCovers(site, host))).map(([n]) => n);
+        if (offSite.length) {
+            return {
+                url: null,
+                shown,
+                filled: {},
+                // The host is not echoed: it is read from the FILLED url, so
+                // `https://${KEY}.their.server/` would print the key back.
+                refused: `${offSite.join(", ")} ${offSite.length === 1 ? "is" : "are"} bound to other sites than notify.url's host — not sent`,
+            };
+        }
+    }
+    return { url, shown, filled };
+}
+/** An error about a request to a resolved notify.url, with every secret value
+ *  put back as its ${NAME} — a redirect refusal quotes the URL it was sent to,
+ *  and the delivery log that keeps it is read by every viewer. */
+function scrubTarget(text, filled) {
+    let out = text;
+    // Longest first, so a value inside another is not half-replaced.
+    for (const value of Object.keys(filled).sort((a, b) => b.length - a.length)) {
+        if (!value)
+            continue;
+        const variants = new Set([value]);
+        try {
+            variants.add(encodeURI(value)).add(encodeURIComponent(value));
+        }
+        catch {
+            // A lone surrogate cannot be encoded, so it cannot appear encoded.
+        }
+        for (const v of variants)
+            out = out.split(v).join(`\${${filled[value]}}`);
+    }
+    return out;
 }
 /**
  * One attempt at one delivery, against the workspace's notify: as it reads
@@ -204,10 +283,13 @@ export async function attemptWebhook(tenant, workspace, d) {
     if (!config?.url) {
         return { ...base, ok: false, statusCode: null, durationMs: 0, response: null, error: "this workspace's notify: has no url any more" };
     }
-    const { url } = webhookTarget(tenant, workspace, config);
+    const { url, refused, filled } = webhookTarget(tenant, workspace, config);
     if (!url) {
-        return { ...base, ok: false, statusCode: null, durationMs: 0, response: null, error: "the secret named in notify.url is not in this account's vault" };
+        return { ...base, ok: false, statusCode: null, durationMs: 0, response: null, error: refused ?? "the secret named in notify.url is not in this account's vault" };
     }
+    // A URL that carries a secret is a credential: a redirect is followed only
+    // within the origin it was sent to, as the tool tester does.
+    const carriesSecret = Object.keys(filled).length > 0;
     try {
         const res = await fetchUntrusted(url, {
             method: "POST",
@@ -222,7 +304,7 @@ export async function attemptWebhook(tenant, workspace, d) {
             },
             body: d.body,
             signal: AbortSignal.timeout(Number(process.env.FOLDRUN_WEBHOOK_TIMEOUT_MS) || 8000),
-        });
+        }, { sameOrigin: carriesSecret });
         const text = (await res.text().catch(() => "")).slice(0, 500);
         return {
             ...base,
@@ -235,7 +317,7 @@ export async function attemptWebhook(tenant, workspace, d) {
     }
     catch (err) {
         const why = err instanceof Error ? (err.name === "TimeoutError" ? "timed out" : err.message) : String(err);
-        return { ...base, ok: false, statusCode: null, durationMs: Date.now() - started, response: null, error: why.slice(0, 500) };
+        return { ...base, ok: false, statusCode: null, durationMs: Date.now() - started, response: null, error: scrubTarget(why, filled).slice(0, 500) };
     }
 }
 /**
@@ -335,7 +417,7 @@ export async function sendPlainNotificationOutcome(tenant, workspace, msg) {
     };
     try {
         if (config.email) {
-            const mail = notifyMail(tenant);
+            const mail = notifyMail(tenant, workspace);
             if (!mail)
                 return no;
             const r = await sendMail({
@@ -386,7 +468,7 @@ export async function sendTestNotification(tenant, workspace) {
     const headline = "\u2713 test notification";
     const detail = `Sent from ${workspace} at ${sent}. If you are reading this, failures and approval gates will reach you here too.`;
     if (config.email) {
-        const mail = notifyMail(tenant);
+        const mail = notifyMail(tenant, workspace);
         if (!mail) {
             return {
                 ok: false,
@@ -411,9 +493,9 @@ export async function sendTestNotification(tenant, workspace) {
     // The destination is echoed back with the secret still unresolved: a
     // Slack webhook URL is itself a credential, and a page that prints it is
     // a page that leaks it into a screenshot.
-    const { url, shown } = webhookTarget(tenant, workspace, config);
+    const { url, shown, refused } = webhookTarget(tenant, workspace, config);
     if (!url) {
-        return { ok: false, destination: shown, detail: `the secret named in notify.url is not in this account's vault` };
+        return { ok: false, destination: shown, detail: refused ?? `the secret named in notify.url is not in this account's vault` };
     }
     const payload = JSON.stringify({ text: `${headline} — ${detail}`, workspace, status: "test", summary: detail });
     // One attempt, recorded in the delivery log like any other — and the way
@@ -424,7 +506,7 @@ export async function sendTestNotification(tenant, workspace) {
         ? {
             ok: true,
             destination: shown,
-            detail: `${config.signingSecret ? "accepted, signed with " + config.signingSecret : "accepted"} (delivery ${r.deliveryId})`,
+            detail: `${config.signingSecret ? "accepted, signed with " + signingSecretShown(config.signingSecret) : "accepted"} (delivery ${r.deliveryId})`,
         }
         : { ok: false, destination: shown, detail: `${r.statusCode ? `HTTP ${r.statusCode} — ` : ""}${r.detail.replace(/\s+/g, " ").slice(0, 400)}` };
 }
@@ -510,7 +592,7 @@ export async function sendRunNotification(tenant, workspace, run) {
     };
     try {
         if (config.email) {
-            const mail = notifyMail(tenant);
+            const mail = notifyMail(tenant, workspace);
             if (!mail) {
                 console.error(`[foldrun] notify: email configured but no mail credential — set RESEND_API_KEY (and EMAIL_FROM) on the account ${tenant}, or FOLDRUN_RESEND_API_KEY on the platform`);
                 return false;
@@ -554,8 +636,9 @@ export async function sendRunNotification(tenant, workspace, run) {
         }
         // ${SECRET} so the Slack URL — itself a credential — can live in the
         // vault instead of in a file that gets committed.
-        if (!webhookTarget(tenant, workspace, config).url) {
-            console.error(`[foldrun] notify: secret in URL not set for ${tenant}/${workspace}`);
+        const target = webhookTarget(tenant, workspace, config);
+        if (!target.url) {
+            console.error(`[foldrun] notify: ${target.refused ?? "secret in URL not set"} for ${tenant}/${workspace}`);
             return false;
         }
         const event = blocked ? "blocked" : run.status;

package/dist/src/package.d.ts

@@ -20,7 +20,11 @@ export interface Package {
 /** An error the API layer turns into a status rather than a 500. */
 export declare class PackageError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    /** `cause`: the error underneath a 500, so an HTTP caller can log it and
+     *  answer without it — a Node error names the server's paths (30 Oct 2026). */
+    constructor(message: string, status: number, opts?: {
+        cause?: unknown;
+    });
 }
 export declare const MANIFEST_FILE = "foldrun-package.json";
 export declare function isPackagedPath(rel: string): boolean;

package/dist/src/package.js

@@ -37,8 +37,10 @@ import { zip, unzip, ZipError } from "./zip.js";
 /** An error the API layer turns into a status rather than a 500. */
 export class PackageError extends Error {
     status;
-    constructor(message, status) {
-        super(message);
+    /** `cause`: the error underneath a 500, so an HTTP caller can log it and
+     *  answer without it — a Node error names the server's paths (30 Oct 2026). */
+    constructor(message, status, opts) {
+        super(message, opts);
         this.status = status;
     }
 }
@@ -371,7 +373,7 @@ export function applyImport(tenant, workspace, pkg, opts = {}) {
                 // best effort — the error below is the one to report
             }
         }
-        throw new PackageError(`the import could not be written, and nothing was kept: ${err instanceof Error ? err.message : String(err)}`, 500);
+        throw new PackageError(`the import could not be written, and nothing was kept: ${err instanceof Error ? err.message : String(err)}`, 500, { cause: err });
     }
     for (const c of changes) {
         const abs = path.join(dir, c.path);

package/dist/src/runner.js

@@ -41,7 +41,7 @@ import { ASK_TOOL, PEER_TOOLS, applyOperatorEvent, askPromptLine, askTimeoutSec,
 import { sendPlainNotification } from "./notify.js";
 import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError, retiredToolNames, retiredToolError } from "./tool-names.js";
 import { refNames } from "./refs.js";
-import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, isSplicedRecord, runSummary, verdictOf, sumAttempts, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
+import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, isSplicedRecord, runSummary, verdictOf, sumAttempts, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, isOneSegment, } from "./store.js";
 import { canReadBack } from "./tool-output.js";
 import { PromptLayers, promptCacheKey } from "./prompt-layers.js";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf } from "./catalog.js";
@@ -4694,8 +4694,12 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     // resuming around.
                     if (step.status !== "pending")
                         continue;
-                    const aDir = path.join(pDir, "agents", step.agent);
-                    if (!fs.existsSync(path.join(aDir, "agent.md"))) {
+                    // One folder under agents/, never a path (30 Oct 2026): an ad-hoc
+                    // run's agent came from the URL, and `../../<tenant>/…` joined here
+                    // ran another account's agent. Refused as not found, before the
+                    // existence check could answer for a path outside.
+                    const aDir = isOneSegment(step.agent) ? path.join(pDir, "agents", step.agent) : null;
+                    if (!aDir || !fs.existsSync(path.join(aDir, "agent.md"))) {
                         step.status = "failed";
                         step.events.push({
                             t: new Date().toISOString(),
@@ -4800,15 +4804,18 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 if (needsApproval.length) {
                     for (const step of needsApproval) {
                         step.status = "awaiting-approval";
+                        const t = new Date().toISOString();
                         step.events.push({
-                            t: new Date().toISOString(),
+                            t,
                             type: "info",
                             // ask: is the same gate carrying a question — the answer
                             // arrives as the approval note and rides into the prompt.
+                            // An event URL is this step's and this park's alone (30 Oct
+                            // 2026): the index and this line's `t` are in its token.
                             text: step.ask
                                 ? `waiting for an answer: ${step.ask}`
                                 : step.waitFor === "event"
-                                    ? `waiting for an external event — release it with POST ${eventUrl(tenant, workspace, run.id)}`
+                                    ? `waiting for an external event — release it with POST ${eventUrl(tenant, workspace, run.id, { step: run.steps.indexOf(step), at: t })}`
                                     : "waiting for approval before running",
                         });
                     }
@@ -4918,8 +4925,9 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // step of the flow (isSplicedRecord). It gets no delegateJob of its
                 // own: depth one.
                 const delegateFor = (parent) => async (agent, job, cancelled) => {
-                    const dir = path.join(pDir, "agents", agent);
-                    if (!fs.existsSync(path.join(dir, "agent.md")))
+                    // One folder under agents/, never a path — as the group check above.
+                    const dir = isOneSegment(agent) ? path.join(pDir, "agents", agent) : null;
+                    if (!dir || !fs.existsSync(path.join(dir, "agent.md")))
                         return { status: "failed", result: `${agent} is not an agent in this workspace` };
                     // A stable id on both records: an index into run.steps moves when a
                     // rescue or a fan-out is spliced in before the child.
@@ -5335,8 +5343,8 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 const rescueStep = async (step) => {
                     if (!step.onFail)
                         return;
-                    const rescuerDir = path.join(pDir, "agents", step.onFail);
-                    if (!fs.existsSync(path.join(rescuerDir, "agent.md"))) {
+                    const rescuerDir = isOneSegment(step.onFail) ? path.join(pDir, "agents", step.onFail) : null;
+                    if (!rescuerDir || !fs.existsSync(path.join(rescuerDir, "agent.md"))) {
                         step.events.push({
                             t: new Date().toISOString(),
                             type: "error",

package/dist/src/scan.js

@@ -202,6 +202,27 @@ export const SCAN_RULES = [
         title: "A required frontmatter field is missing",
         help: "A skill with no description is never loaded: the model chooses skills by their descriptions.",
     },
+    {
+        // 30 Oct 2026: check and the scheduler read a schedule with the same
+        // cronCanFire (core cron.ts), so check says what the scheduler does.
+        id: "config/cron-never-fires",
+        category: "config",
+        level: "warn",
+        title: "A schedule that names a day no month has",
+        help: "`0 0 30 2 *` is a valid cron — every field is in range — but no February has a 30th, so the flow never runs and the " +
+            "scheduler never lists a next run for it. Pick a day every named month has, or add a weekday (either then matches).",
+    },
+    {
+        // 30 Oct 2026: a signing secret is looked up in the vault by name.
+        id: "secret/signing-secret-value",
+        category: "secret",
+        level: "warn",
+        title: "A signing_secret: that holds a value, not a secret's name",
+        help: "A flow's `signing_secret:` and `notify: signing_secret:` name a vault entry (`WEBHOOK_SIGNING_KEY`, or `${WEBHOOK_SIGNING_KEY}`). " +
+            "Anything else is looked up as a name and never found — every signed delivery is refused, every notification goes unsigned — " +
+            "and the value itself is deployed and versioned in plain text. Put it in the vault (`foldrun secrets set NAME`), write the name, and rotate it.",
+        owasp: ["ASI03"],
+    },
     {
         id: "check/ignore-needs-reason",
         category: "config",

package/dist/src/secrets.d.ts

@@ -31,8 +31,15 @@ interface StoredSecret {
      *  these sites alone. Metadata, not a value, so it is stored in the clear
      *  beside the ciphertext and survives the value being set again. */
     sites?: string[];
+    /** An ACCOUNT secret limited to these workspaces (GitHub's "selected
+     *  repositories" for an organisation secret). Absent: every workspace may
+     *  use it, as before. Every other workspace is answered as if it were not
+     *  set (getSecret). Metadata like `sites`: in the clear, and in the seal
+     *  of a bound record. Never on a workspace's own record. */
+    workspaces?: string[];
     /** 2: sealed with the record's place as AAD — account, scope, name, kind,
-     *  key and sites (vaultAad). Absent: the older, unbound form. */
+     *  key, sites and, when limited, workspaces (vaultAad). Absent: the older,
+     *  unbound form. */
     v?: 2;
 }
 type SecretsFile = Record<string, StoredSecret>;
@@ -44,7 +51,30 @@ declare const writeBound: () => boolean;
  */
 export declare function mutateVaultFile(file: string, change: (all: SecretsFile) => SecretsFile | null): SecretsFile;
 export declare const SECRET_NAME: RegExp;
-export declare function setSecret(tenant: string, name: string, value: string, workspace?: string, kind?: SecretKind): void;
+/**
+ * How a `signing_secret:` is shown in an answer, a log line or a delivery
+ * record: the name it holds, and only a name (30 Oct 2026). It is meant to
+ * name a vault entry, but nothing stopped the value itself being written
+ * there, and notify's test send echoed it back to the dashboard as "signed
+ * with <it>". Anything that is not a secret name is described, never
+ * repeated (foldrun check flags it as secret/signing-secret-value).
+ */
+export declare function signingSecretShown(name: string): string;
+/**
+ * Which workspaces an ACCOUNT secret may be used in, given with the value so
+ * both are sealed in one locked write (30 Oct 2026): a new secret created
+ * and limited in two calls was open to every workspace between them, and
+ * stayed open if the second failed. `workspaces` undefined keeps what the
+ * record has; null opens it to every workspace; a list limits it.
+ * `exists` is asked about each name under the vault lock, so a workspace
+ * deleted meanwhile is not granted (the delete takes its name off every
+ * list under the same lock — retargetSecretWorkspaces).
+ */
+export interface SecretLimit {
+    workspaces?: string[] | null;
+    exists?: (workspace: string) => boolean;
+}
+export declare function setSecret(tenant: string, name: string, value: string, workspace?: string, kind?: SecretKind, limit?: SecretLimit): void;
 /**
  * Bind a secret to sites, or unbind it (an empty list). The secret must
  * exist in that scope. Sites are `api.example.com` or `*.example.com` — no
@@ -71,11 +101,61 @@ export declare function decryptValue(tenant: string, rec: {
     data: string;
     k?: "tenant";
 } | undefined): string | null;
-/** Nearest wins: a workspace secret shadows an account one of the same name. */
+/** Nearest wins: a workspace secret shadows an account one of the same name.
+ *  An account secret limited to some workspaces (setSecretWorkspaces) is
+ *  absent for every other — the answer a secret that was never set gets, on
+ *  every path that resolves one for a workspace: runs, tool tests, notify,
+ *  the egress proxy, MCP servers. Without a workspace it is the account's
+ *  own use (its model key, its mail sender), which no list limits. */
 export declare function getSecret(tenant: string, name: string, workspace?: string): {
     value: string;
     scope: SecretScope;
 } | null;
+/** May the ACCOUNT's secret `name` be used for this workspace? True when it
+ *  is not limited (or not set); for callers that read the account's copy on
+ *  a workspace's behalf without getSecret's workspace-first lookup — the
+ *  account's mail sender for a workspace's notifications (notify.ts). */
+export declare function accountSecretUsableIn(tenant: string, name: string, workspace: string): boolean;
+/**
+ * Limit an account secret to some workspaces, or lift the limit (null).
+ * An empty list means no workspace may use it. Returns the list as stored,
+ * sorted, or null.
+ *
+ * `exists` is asked about each name under the vault lock (the API passes
+ * "is there such a workspace"), so it cannot grant a name a delete has just
+ * taken off every list. `ifWorkspaces`, when given, is the list the caller
+ * saw (null: every workspace): a list changed since is refused (409), so
+ * two admins editing it at once do not silently overwrite each other.
+ *
+ * The record is sealed (v2) whatever it was, whatever
+ * FOLDRUN_VAULT_WRITE_BOUND says: a list in the clear on an unbound record
+ * could be stripped on disk to open the secret to every workspace; sealed,
+ * a stripped list makes it unreadable. Every reader since 29 Oct 2026 reads v2.
+ */
+export declare function setSecretWorkspaces(tenant: string, name: string, workspaces: string[] | null, opts?: {
+    exists?: (workspace: string) => boolean;
+    ifWorkspaces?: string[] | null;
+}): string[] | null;
+/**
+ * A workspace is being renamed (to: its new name) or deleted (to: null):
+ * every account secret limited to it follows. Without this a rename quietly
+ * cut the workspace off its secrets, and a delete left the name on the list
+ * for the next workspace given it.
+ *
+ * `failed` names the records that hold the name but will not open with this
+ * install's keys: they are left exactly as they are, so the old name is
+ * STILL on their list — a key restored later would bring the grant back.
+ * The caller must not report the rename or delete as clean while any are
+ * left (the API refuses it, naming them: set them again, or delete them).
+ *
+ * Names, not ids: a grant naming a workspace's immutable id would survive a
+ * rename untouched and could never pass to a new workspace given an old
+ * name — the stronger design, not built yet (30 Oct 2026).
+ */
+export declare function retargetSecretWorkspaces(tenant: string, from: string, to: string | null): {
+    changed: string[];
+    failed: string[];
+};
 export declare function deleteSecret(tenant: string, name: string, workspace?: string): void;
 export interface SecretEntry {
     name: string;
@@ -89,6 +169,8 @@ export interface SecretEntry {
     /** The sites it is bound to — the proxy fills it for these and no other,
      *  and it never enters a sandbox. Absent when unbound. */
     sites?: string[];
+    /** An account secret limited to these workspaces; absent: every one. */
+    workspaces?: string[];
 }
 export declare function listSecrets(tenant: string, workspace?: string): SecretEntry[];
 export declare function resolveSecrets(tenant: string, names: string[], workspace?: string): {
@@ -154,7 +236,7 @@ export interface OAuth2Config {
 export declare const OAUTH_REFRESH_TRIES = 3;
 /** Wait before try n (1-based retry): 1s, 3s — FOLDRUN_OAUTH_RETRY_MS scales it for tests. */
 export declare function oauthRetryDelayMs(n: number): number;
-export declare function setOAuth2Secret(tenant: string, name: string, config: OAuth2Config, workspace?: string): void;
+export declare function setOAuth2Secret(tenant: string, name: string, config: OAuth2Config, workspace?: string, limit?: SecretLimit): void;
 export declare function isOAuth2Value(value: string): boolean;
 /**
  * The cache key for a live token: SHA-256 over the kind, the account and the
@@ -205,8 +287,8 @@ export interface ServiceAccountConfig {
      *  a Workspace admin grants it. Absent, the account acts as itself. */
     subject?: string;
 }
-export declare function setServiceAccountSecret(tenant: string, name: string, config: ServiceAccountConfig, workspace?: string): void;
-export declare function setFileSecret(tenant: string, name: string, content: string, workspace?: string): void;
+export declare function setServiceAccountSecret(tenant: string, name: string, config: ServiceAccountConfig, workspace?: string, limit?: SecretLimit): void;
+export declare function setFileSecret(tenant: string, name: string, content: string, workspace?: string, limit?: SecretLimit): void;
 export declare function isFileValue(value: string): boolean;
 export declare function fileContent(value: string): string;
 export interface SshConfig {
@@ -217,7 +299,7 @@ export interface SshConfig {
     private_key?: string;
     password?: string;
 }
-export declare function setSshSecret(tenant: string, name: string, config: SshConfig, workspace?: string): void;
+export declare function setSshSecret(tenant: string, name: string, config: SshConfig, workspace?: string, limit?: SecretLimit): void;
 export declare function isSshValue(value: string): boolean;
 export declare function sshConfigOf(value: string): SshConfig;
 /** A client certificate for mutual TLS: presented by the egress proxy, on its
@@ -232,14 +314,14 @@ export interface ClientCertConfig {
     passphrase?: string;
     export?: boolean;
 }
-export declare function setClientCertSecret(tenant: string, name: string, config: ClientCertConfig, workspace?: string): void;
+export declare function setClientCertSecret(tenant: string, name: string, config: ClientCertConfig, workspace?: string, limit?: SecretLimit): void;
 /** A keyless cloud identity: no credential at all, only the audience the
  *  platform's signed tokens are for. A step that declares it gets a token
  *  file the sandbox driver keeps fresh through the egress proxy. */
 export interface IdentityConfig {
     audience: string;
 }
-export declare function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string): void;
+export declare function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string, limit?: SecretLimit): void;
 export declare function isIdentityValue(value: string): boolean;
 export declare function identityOf(value: string): IdentityConfig;
 export declare function isClientCertValue(value: string): boolean;
@@ -260,7 +342,7 @@ export interface ApiConfig {
 /** `Authorization: Basic …` from a username and password (RFC 7617 §2):
  *  UTF-8, no colon in the username, no control characters in either. */
 export declare function basicAuthorization(username: string, password: string): string;
-export declare function setApiSecret(tenant: string, name: string, config: ApiConfig, workspace?: string): void;
+export declare function setApiSecret(tenant: string, name: string, config: ApiConfig, workspace?: string, limit?: SecretLimit): void;
 export declare function isApiValue(value: string): boolean;
 export declare function apiConfigOf(value: string): ApiConfig;
 /**