@foldrun/core 2.5.0 → 2.7.0

package/dist/src/secret-files.js

@@ -17,7 +17,7 @@
 // deleted the keys the other was still using.
 import fs from "node:fs";
 import path from "node:path";
-import { isFileValue, fileContent, isSshValue, sshConfigOf, isApiValue, apiConfigOf, } from "./secrets.js";
+import { isFileValue, fileContent, isSshValue, sshConfigOf, isApiValue, apiConfigOf, isClientCertValue, clientCertOf, } from "./secrets.js";
 // POSIX single-quoting: the one escape sh actually honours inside ' is none,
 // so close, backslash-quote, reopen. Wrapper scripts embed hosts, users and
 // header values through this and nothing else.
@@ -34,7 +34,7 @@ function writeWrapper(dir, name, body) {
  * Plain values pass through untouched.
  */
 export function materializeFileSecrets(agentDir, env) {
-    const entries = Object.entries(env).filter(([, v]) => typeof v === "string" && (isFileValue(v) || isSshValue(v) || isApiValue(v)));
+    const entries = Object.entries(env).filter(([, v]) => typeof v === "string" && (isFileValue(v) || isSshValue(v) || isApiValue(v) || isClientCertValue(v)));
     if (entries.length === 0)
         return { env, dir: null };
     const parent = path.join(agentDir, ".secret-files");
@@ -50,6 +50,27 @@ export function materializeFileSecrets(agentDir, env) {
             fs.writeFileSync(file, fileContent(value), { mode: 0o600 });
             out[name] = file;
         }
+        else if (isClientCertValue(value)) {
+            // Only an exported certificate reaches here as itself (the runner
+            // withholds the rest): its parts as files, $NAME the certificate.
+            const c = clientCertOf(value);
+            if (!c.export) {
+                delete out[name];
+                continue;
+            }
+            const cert = path.join(dir, `${name.toLowerCase()}.crt`);
+            const key = path.join(dir, `${name.toLowerCase()}.key`);
+            fs.writeFileSync(cert, c.cert, { mode: 0o600 });
+            fs.writeFileSync(key, c.key, { mode: 0o600 });
+            out[name] = cert;
+            out[`${name}_CERT`] = cert;
+            out[`${name}_KEY`] = key;
+            if (c.passphrase) {
+                const pass = path.join(dir, `${name.toLowerCase()}.pass`);
+                fs.writeFileSync(pass, c.passphrase, { mode: 0o600 });
+                out[`${name}_PASSPHRASE_FILE`] = pass;
+            }
+        }
         else if (isSshValue(value)) {
             const ssh = sshConfigOf(value);
             const dest = `${ssh.user}@${ssh.host}`;

package/dist/src/secrets.d.ts

@@ -15,7 +15,7 @@ export declare function installKeyMaterial(): string;
 /** How the stored value is used at run time — "oauth2"/"service-account"
  *  are refreshed into live tokens, "file"/"ssh"/"api" are materialised into
  *  the run's scratch. Plain values have no kind. */
-export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api";
+export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api" | "client-cert" | "identity";
 interface StoredSecret {
     iv: string;
     tag: string;
@@ -133,7 +133,9 @@ export declare function rotateMasterKey(tenant: string, from: string, to: string
 export interface OAuth2Config {
     token_url: string;
     client_id: string;
-    client_secret: string;
+    /** Absent for a public client (an app with no secret, connected with
+     *  PKCE): its refresh sends client_id and refresh_token only. */
+    client_secret?: string;
     /** Required for the refresh grant; absent for client_credentials. */
     refresh_token?: string;
     /** "refresh_token" (default — user-consented) or "client_credentials"
@@ -150,6 +152,24 @@ export declare const OAUTH_REFRESH_TRIES = 3;
 export declare function oauthRetryDelayMs(n: number): number;
 export declare function setOAuth2Secret(tenant: string, name: string, config: OAuth2Config, workspace?: string): void;
 export declare function isOAuth2Value(value: string): boolean;
+/**
+ * The cache key for a live token: SHA-256 over the kind, the account and the
+ * WHOLE stored config — credential material included (client secret, refresh
+ * token, private key, subject, scopes, token URL). A caller can only hit an
+ * entry it could have minted itself. Both maps are process-wide, so a key of
+ * names alone (`sa:${name}:${issuer}`, `${name}:${client_id}:…`) once let a
+ * second account with the same names be handed the first one's token
+ * (Codex debate, 22 Oct 2026).
+ */
+export declare function tokenCacheKey(kind: "oauth2" | "sa", storedValue: string, tenant?: string): string;
+/**
+ * A provider that rotates refresh tokens (RFC 9700 §2.2.2) answered a refresh
+ * with a new one: write it back where the old one is stored — the workspace
+ * copy, else the account's — but only while that copy still holds the value
+ * this refresh used (compare-and-set), so two refreshes racing cannot put an
+ * older token over a newer one. Returns whether a copy was replaced.
+ */
+export declare function replaceOAuth2RefreshToken(tenant: string, name: string, workspace: string | undefined, usedValue: string, refreshToken: string): boolean;
 /**
  * Swap every oauth2 recipe in an env map for a live access token. The one
  * async moment in secret resolution, kept out of the sync paths: callers
@@ -171,6 +191,10 @@ export interface ServiceAccountConfig {
     scope: string;
     /** JWT audience — usually the same as token_url. */
     audience?: string;
+    /** The JWT bearer grant's subject (RFC 7523 §3): the user the account acts
+     *  as, where the provider allows it — Google's domain-wide delegation, once
+     *  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;
@@ -187,10 +211,46 @@ export interface SshConfig {
 export declare function setSshSecret(tenant: string, name: string, config: SshConfig, workspace?: string): 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
+ *  own connection, to the exact hosts the secret is bound to — the sandbox
+ *  never holds the key. `export` puts it in the sandbox as files instead,
+ *  only when asked for (a step with no egress proxy). */
+export interface ClientCertConfig {
+    /** PEM certificate, chain included. */
+    cert: string;
+    /** PEM private key. */
+    key: string;
+    passphrase?: string;
+    export?: boolean;
+}
+export declare function setClientCertSecret(tenant: string, name: string, config: ClientCertConfig, workspace?: string): 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 isIdentityValue(value: string): boolean;
+export declare function identityOf(value: string): IdentityConfig;
+export declare function isClientCertValue(value: string): boolean;
+/** An environment without the client certificates that were not saved with
+ *  `export`: those are the egress proxy's to present, never a program's. */
+export declare function withoutHeldCerts(env: Record<string, string>): Record<string, string>;
+export declare function clientCertOf(value: string): ClientCertConfig;
 export interface ApiConfig {
     base_url?: string;
     headers: Record<string, string>;
+    /** Username and password for HTTP Basic (RFC 7617): stored as the
+     *  `Authorization: Basic …` header they make, never kept apart. */
+    basic?: {
+        username: string;
+        password: string;
+    };
 }
+/** `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 isApiValue(value: string): boolean;
 export declare function apiConfigOf(value: string): ApiConfig;

package/dist/src/secrets.js

@@ -200,6 +200,11 @@ export function setSecretSites(tenant, name, sites, workspace) {
         if (clean.length && (rec.kind === "file" || rec.kind === "ssh" || rec.kind === "api")) {
             throw new Error(`${name} is a ${rec.kind} secret, unpacked inside the sandbox — only a value sent in a request can be bound to sites`);
         }
+        // A client certificate is presented by the egress proxy to the exact
+        // hosts named — never to a whole domain on a wildcard.
+        if (rec.kind === "client-cert" && clean.some((s) => s.startsWith("*."))) {
+            throw new Error(`${name} is a client certificate — bind it to exact hosts, not a wildcard`);
+        }
         if (clean.length)
             rec.sites = clean;
         else
@@ -459,10 +464,15 @@ export function oauthRetryDelayMs(n) {
     return base * (n === 1 ? 1 : 3);
 }
 export function setOAuth2Secret(tenant, name, config, workspace) {
-    for (const field of ["token_url", "client_id", "client_secret"]) {
+    for (const field of ["token_url", "client_id"]) {
         if (!config[field]?.trim())
             throw new Error(`oauth2 secret needs ${field}`);
     }
+    // A public client (PKCE, no secret) refreshes with its client id alone;
+    // client credentials are nothing without the secret.
+    if (config.grant_type === "client_credentials" && !config.client_secret?.trim()) {
+        throw new Error("oauth2 secret needs client_secret for client_credentials");
+    }
     if (config.grant_type !== "client_credentials" && !config.refresh_token?.trim()) {
         throw new Error("oauth2 secret needs refresh_token (or grant_type: client_credentials)");
     }
@@ -481,11 +491,62 @@ export function isOAuth2Value(value) {
 // steps must not hit Google twenty times in one second.
 const tokenCache = new Map();
 const inFlight = new Map();
+/**
+ * The cache key for a live token: SHA-256 over the kind, the account and the
+ * WHOLE stored config — credential material included (client secret, refresh
+ * token, private key, subject, scopes, token URL). A caller can only hit an
+ * entry it could have minted itself. Both maps are process-wide, so a key of
+ * names alone (`sa:${name}:${issuer}`, `${name}:${client_id}:…`) once let a
+ * second account with the same names be handed the first one's token
+ * (Codex debate, 22 Oct 2026).
+ */
+export function tokenCacheKey(kind, storedValue, tenant) {
+    return crypto.createHash("sha256").update(JSON.stringify([kind, tenant ?? "", storedValue])).digest("hex");
+}
+/**
+ * A provider that rotates refresh tokens (RFC 9700 §2.2.2) answered a refresh
+ * with a new one: write it back where the old one is stored — the workspace
+ * copy, else the account's — but only while that copy still holds the value
+ * this refresh used (compare-and-set), so two refreshes racing cannot put an
+ * older token over a newer one. Returns whether a copy was replaced.
+ */
+export function replaceOAuth2RefreshToken(tenant, name, workspace, usedValue, refreshToken) {
+    if (!isOAuth2Value(usedValue))
+        return false;
+    const config = JSON.parse(usedValue.slice(OAUTH2_PREFIX.length));
+    const next = OAUTH2_PREFIX + JSON.stringify({ ...config, refresh_token: refreshToken });
+    for (const scope of workspace ? [workspace, undefined] : [undefined]) {
+        let replaced = false;
+        mutateVaultFile(secretsFile(tenant, scope), (all) => {
+            const rec = all[name];
+            if (rec && decrypt(tenant, rec) === usedValue) {
+                all[name] = { ...rec, ...encryptValue(tenant, next), updatedAt: new Date().toISOString() };
+                replaced = true;
+            }
+            return all;
+        });
+        if (replaced)
+            return true;
+    }
+    return false;
+}
+const oauthCache = new Map();
+const oauthFlight = new Map();
+/** Cache an access token, sweeping expired entries as it goes: a rotating
+ *  provider changes the stored config — and so the key — on every refresh,
+ *  and expired entries would otherwise pile up for the life of the process. */
+function cacheOAuth(key, live) {
+    const now = Date.now();
+    for (const [k, v] of oauthCache)
+        if (v.expiresAt <= now)
+            oauthCache.delete(k);
+    oauthCache.set(key, live);
+}
 async function exchange(config, cacheKey) {
-    const cached = tokenCache.get(cacheKey);
+    const cached = oauthCache.get(cacheKey);
     if (cached && cached.expiresAt > Date.now())
-        return cached.token;
-    const pending = inFlight.get(cacheKey);
+        return cached;
+    const pending = oauthFlight.get(cacheKey);
     if (pending)
         return pending;
     const flight = (async () => {
@@ -493,7 +554,7 @@ async function exchange(config, cacheKey) {
             grant_type: config.grant_type ?? "refresh_token",
             ...(config.grant_type === "client_credentials" ? {} : { refresh_token: config.refresh_token }),
             client_id: config.client_id,
-            client_secret: config.client_secret,
+            ...(config.client_secret ? { client_secret: config.client_secret } : {}),
             ...(config.extra ?? {}),
         });
         // A network blip is retried; a provider's answer is not. "fetch failed"
@@ -530,15 +591,21 @@ async function exchange(config, cacheKey) {
             throw new Error(`token refresh failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`);
         }
         const ttl = Math.max(60, (payload.expires_in ?? 3600) - 60) * 1000;
-        tokenCache.set(cacheKey, { token: payload.access_token, expiresAt: Date.now() + ttl });
-        return payload.access_token;
+        // A rotated refresh token replaces the old one, which the provider may
+        // now refuse; dropping it broke the next refresh for rotating providers.
+        const rotated = payload.refresh_token && config.grant_type !== "client_credentials" && payload.refresh_token !== config.refresh_token
+            ? payload.refresh_token
+            : undefined;
+        const live = { token: payload.access_token, expiresAt: Date.now() + ttl, ...(rotated ? { rotated } : {}) };
+        cacheOAuth(cacheKey, live);
+        return live;
     })();
-    inFlight.set(cacheKey, flight);
+    oauthFlight.set(cacheKey, flight);
     try {
         return await flight;
     }
     finally {
-        inFlight.delete(cacheKey);
+        oauthFlight.delete(cacheKey);
     }
 }
 /**
@@ -565,13 +632,23 @@ ctx) {
                 throw new Error(`secret ${name}: stored oauth2 config is unreadable`);
             }
             try {
-                // Fingerprint the WHOLE refresh token, not its first 8 chars: Google
-                // refresh tokens share a long common prefix, so an 8-char slice could
-                // collide two distinct grants onto one cache entry and hand one the
-                // other's access token. Hashed so the token is not held in a Map key.
-                const grantMaterial = config.refresh_token ?? config.grant_type ?? "";
-                const fp = crypto.createHash("sha256").update(grantMaterial).digest("hex").slice(0, 16);
-                out[name] = await exchange(config, `${name}:${config.client_id}:${fp}`);
+                const live = await exchange(config, tokenCacheKey("oauth2", value, ctx?.tenant));
+                out[name] = live.token;
+                if (live.rotated) {
+                    // This caller's copy takes the new refresh token (compare-and-set:
+                    // a copy already updated, or changed since, is left alone), and the
+                    // access token is cached under the config as it is now stored, so
+                    // the next run does not refresh again.
+                    const next = OAUTH2_PREFIX + JSON.stringify({ ...config, refresh_token: live.rotated });
+                    try {
+                        if (ctx)
+                            replaceOAuth2RefreshToken(ctx.tenant, name, ctx.workspace, value, live.rotated);
+                    }
+                    catch {
+                        // The access token is good either way; the next refresh says if not.
+                    }
+                    cacheOAuth(tokenCacheKey("oauth2", next, ctx?.tenant), { token: live.token, expiresAt: live.expiresAt });
+                }
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -590,7 +667,7 @@ ctx) {
                 throw new Error(`secret ${name}: stored service account config is unreadable`);
             }
             try {
-                out[name] = await exchangeServiceAccount(config, `sa:${name}:${config.issuer}`);
+                out[name] = await exchangeServiceAccount(config, tokenCacheKey("sa", value, ctx?.tenant));
             }
             catch (err) {
                 throw new Error(`secret ${name}: ${err instanceof Error ? err.message : String(err)}`);
@@ -619,7 +696,14 @@ export function setServiceAccountSecret(tenant, name, config, workspace) {
     if (!/BEGIN [A-Z ]{0,40}PRIVATE KEY/.test(config.private_key)) {
         throw new Error("private_key must be a PEM key (from the service account JSON)");
     }
-    setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(config), workspace, "service-account");
+    if (config.subject !== undefined) {
+        if (typeof config.subject !== "string" || !config.subject.trim())
+            throw new Error("subject is the user to act as — leave it out to act as the account itself");
+        if (config.subject.length > 320 || /[\u0000-\u001f\u007f\s]/.test(config.subject.trim()))
+            throw new Error("subject is one identifier, no spaces or control characters");
+    }
+    const stored = { ...config, ...(config.subject !== undefined ? { subject: config.subject.trim() } : {}) };
+    setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(stored), workspace, "service-account");
 }
 function base64url(input) {
     return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -636,7 +720,9 @@ async function exchangeServiceAccount(config, cacheKey) {
         const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
         const claim = base64url(JSON.stringify({
             iss: config.issuer,
-            sub: config.issuer,
+            // The subject is part of the stored config, so of the cache key: two
+            // subjects never share a token (tokenCacheKey).
+            sub: config.subject || config.issuer,
             scope: config.scope,
             aud: config.audience ?? config.token_url,
             iat: now,
@@ -737,8 +823,108 @@ export function sshConfigOf(value) {
 // wrapper with the headers baked in — `"$NAME" /v1/charges` — so the secret
 // never appears in the bash command at all.
 const API_PREFIX = "@api ";
+const CLIENT_CERT_PREFIX = "@client-cert ";
+export function setClientCertSecret(tenant, name, config, workspace) {
+    if (!/-----BEGIN CERTIFICATE-----/.test(config.cert ?? ""))
+        throw new Error("cert must be a PEM certificate");
+    if (!/-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----/.test(config.key ?? ""))
+        throw new Error("key must be a PEM private key");
+    // The pair must match: a certificate presented with another key's proof
+    // fails at the server, after the request has gone.
+    let matches = false;
+    try {
+        const key = crypto.createPrivateKey({ key: config.key, ...(config.passphrase ? { passphrase: config.passphrase } : {}) });
+        matches = new crypto.X509Certificate(config.cert).checkPrivateKey(key);
+    }
+    catch (err) {
+        throw new Error(`the certificate or key cannot be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!matches)
+        throw new Error("the key does not belong to the certificate");
+    const stored = {
+        cert: config.cert,
+        key: config.key,
+        ...(config.passphrase ? { passphrase: config.passphrase } : {}),
+        ...(config.export ? { export: true } : {}),
+    };
+    if (!SECRET_NAME.test(name))
+        throw new Error(`secret name "${name}" must be UPPER_SNAKE_CASE`);
+    const sealed = encryptValue(tenant, CLIENT_CERT_PREFIX + JSON.stringify(stored));
+    // Written under the vault's own lock, with the binding checked in the same
+    // step: a value set over a secret keeps its site binding, and a wildcard
+    // one would present the certificate to a whole domain.
+    mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+        const sites = all[name]?.sites;
+        if (sites?.some((site) => site.startsWith("*."))) {
+            throw new Error(`${name} is bound to ${sites.join(", ")} — a client certificate is bound to exact hosts; unbind the wildcard first`);
+        }
+        all[name] = { ...sealed, updatedAt: new Date().toISOString(), kind: "client-cert", ...(sites?.length ? { sites } : {}) };
+        return all;
+    });
+}
+const IDENTITY_PREFIX = "@identity ";
+export function setIdentitySecret(tenant, name, config, workspace) {
+    const audience = typeof config.audience === "string" ? config.audience.trim() : "";
+    if (!audience)
+        throw new Error("an identity needs an audience — the value your cloud's trust expects in aud");
+    if (audience.length > 600 || /[\u0000-\u001f\u007f]/.test(audience))
+        throw new Error("audience is one value, at most 600 characters, no control characters");
+    setSecret(tenant, name, IDENTITY_PREFIX + JSON.stringify({ audience }), workspace, "identity");
+}
+export function isIdentityValue(value) {
+    return value.startsWith(IDENTITY_PREFIX);
+}
+export function identityOf(value) {
+    return JSON.parse(value.slice(IDENTITY_PREFIX.length));
+}
+export function isClientCertValue(value) {
+    return value.startsWith(CLIENT_CERT_PREFIX);
+}
+/** An environment without the client certificates that were not saved with
+ *  `export`: those are the egress proxy's to present, never a program's. */
+export function withoutHeldCerts(env) {
+    return Object.fromEntries(Object.entries(env).filter(([, v]) => typeof v !== "string" || !isClientCertValue(v) || clientCertOf(v).export === true));
+}
+export function clientCertOf(value) {
+    return JSON.parse(value.slice(CLIENT_CERT_PREFIX.length));
+}
+/** `Authorization: Basic …` from a username and password (RFC 7617 §2):
+ *  UTF-8, no colon in the username, no control characters in either. */
+export function basicAuthorization(username, password) {
+    if (typeof username !== "string" || typeof password !== "string")
+        throw new Error("basic needs username and password");
+    if (!username)
+        throw new Error("basic needs a username");
+    if (username.includes(":"))
+        throw new Error("a Basic username cannot contain a colon (RFC 7617)");
+    if (/[\u0000-\u001f\u007f]/.test(username) || /[\u0000-\u001f\u007f]/.test(password))
+        throw new Error("Basic credentials cannot contain control characters");
+    return `Basic ${Buffer.from(`${username}:${password}`, "utf8").toString("base64")}`;
+}
 export function setApiSecret(tenant, name, config, workspace) {
-    const headers = Object.entries(config.headers ?? {});
+    let all = { ...(config.headers ?? {}) };
+    if (config.basic) {
+        if (Object.keys(all).some((h) => h.toLowerCase() === "authorization")) {
+            throw new Error("give either basic or an Authorization header, not both");
+        }
+        // Credentials in the clear over http are leaked ones: https, or loopback.
+        const base = config.base_url?.trim();
+        if (base) {
+            let u = null;
+            try {
+                u = new URL(base);
+            }
+            catch {
+                u = null;
+            }
+            const loopback = u?.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1");
+            if (!u || (u.protocol !== "https:" && !loopback))
+                throw new Error("Basic credentials need an https base_url");
+        }
+        all = { ...all, Authorization: basicAuthorization(config.basic.username, config.basic.password) };
+    }
+    config = { ...(config.base_url ? { base_url: config.base_url } : {}), headers: all };
+    const headers = Object.entries(all);
     if (headers.length === 0)
         throw new Error("api secret needs at least one header");
     for (const [h, v] of headers) {

package/dist/src/starter.js

@@ -55,6 +55,22 @@ foldrun_version: "0.1"
 #
 # The token is sent as a bearer credential. A gateway that wants it as a key
 # header asks for that by name: headers: { x-api-key: \${THE_SECRET} }.
+#
+# The four jobs of running agents, each a block — or write the same keys at
+# the top; one place or the other, never both:
+#
+# governance:          # who answers for it, what it may spend and ship
+#   owner: you@example.com
+#   budget: 60/month
+#   deploy_block: secrets
+# guardrail:           # what agents may reach and call
+#   limits: {calls: 300, repeat: 5}
+#   network: trusted
+# observability:       # what is recorded, and who is told
+#   notify: {email: you@example.com, events: [failed]}
+#   alerts: {failure_rate: 30%}
+# evaluation:          # how work is judged
+#   judge: {model: fast}
 ---
 
 # ${account}
@@ -476,6 +492,13 @@ runtime:                    # only if scripts need packages
 You research a topic and report what you found...
 \`\`\`
 
+The fields that do one of the four jobs of running agents may be grouped
+under it — \`governance:\` (owner, budget), \`guardrail:\` (limits, network,
+hooks, disallowedTools, permissionMode, secrets), and in AGENTS.md also
+\`observability:\` (alerts, telemetry, notify, capture) and \`evaluation:\`
+(judge). A block reads exactly as the same keys at the top; a key written
+both ways is refused (\`config/conflict\`). \`foldrun docs four-jobs\`.
+
 Only \`name\` and the prose are required. Every other field widens or narrows
 what the agent can reach, and the default is narrow.
 

package/dist/src/step-exec.d.ts

@@ -104,6 +104,11 @@ export interface ExecOptions {
      *  `matches: re`, `file: path`, `judge: sentence`) — see checkVerify. */
     verify?: string;
     verifyEnv?: Record<string, string>;
+    /** The model `verify: judge:` grades with — the workspace's `judge:` from
+     *  AGENTS.md, resolved; absent, the fast tier. */
+    judgeModel?: string;
+    /** And how long it thinks — `judge: {effort}`; absent, the SDK's default. */
+    judgeEffort?: Effort;
     /** `output: json` — the reply must carry one JSON value; extracting it is
      *  part of finishing the step, and failing to is failing the step. */
     output?: "json";
@@ -301,14 +306,17 @@ export declare function checkVerify(agentDir: string, verify: string, ctx: {
     /** The step's own model environment, for `judge:` — it grades on the
      *  fast tier through the same credential the step rode. */
     modelEnv?: Record<string, string | undefined>;
+    /** The judge's model and effort (the workspace's `judge:`). */
+    judgeModel?: string;
+    judgeEffort?: Effort;
     /** Ends a shell check or a judge mid-way: the step's clock ran out, or a
      *  person asked the run to stop. */
     signal?: AbortSignal;
 }): Promise<VerifyVerdict>;
 /**
  * A toolless, fast-tier grading call: does the reply satisfy the sentence?
- * Same shape as the eval judge, and answered with one word first so the
- * verdict is a prefix test rather than a reading.
+ * Same shape as the eval judge: reasoning first, then the verdict alone on
+ * the last line (judge-verdict.ts says why).
  */
 export declare function judgePrompt(rubric: string, reply: string, work: string): string;
 /**

package/dist/src/step-exec.js

@@ -7,6 +7,7 @@
 // assembles the system prompt and builds MCP servers, then hands this the
 // results. That is what lets the same function run somewhere the vault, the
 // library and the account do not exist.
+import { judgeVerdict, JUDGE_VERDICT_INSTRUCTION } from "./judge-verdict.js";
 import { runHook, runToolCallHooks, matchesTool, hookLine, resolveHooks } from "./hooks.js";
 import fs from "node:fs";
 import os from "node:os";
@@ -901,6 +902,8 @@ async function executeStepInner(opts, runQuery) {
                 data,
                 modelEnv: opts.env,
                 signal: halt.signal,
+                ...(opts.judgeModel ? { judgeModel: opts.judgeModel } : {}),
+                ...(opts.judgeEffort ? { judgeEffort: opts.judgeEffort } : {}),
             });
         }
         finally {
@@ -1045,17 +1048,17 @@ export async function checkVerify(agentDir, verify, ctx) {
             // GOOD` on a reply that did (fix-desk, run-muwevg72-7mza): the joined
             // text opened with the narration before it.
             const reply = ctx.conclusion?.trim() ? ctx.conclusion : output;
-            const verdict = await judgeReply(value, reply, output, ctx.modelEnv ?? {}, ctx.signal);
-            const ok = /^\s*PASS\b/i.test(verdict);
-            return { ok, headline: ok ? "PASS" : "FAIL", detail: verdict.slice(0, 300) };
+            const said = await judgeReply(value, reply, output, ctx.modelEnv ?? {}, ctx.signal, ctx.judgeModel, ctx.judgeEffort);
+            const { passed: ok, detail } = judgeVerdict(said);
+            return { ok, headline: ok ? "PASS" : "FAIL", detail };
         }
     }
     return { ok: false, headline: `unknown check "${kind}"`, detail: "" };
 }
 /**
  * A toolless, fast-tier grading call: does the reply satisfy the sentence?
- * Same shape as the eval judge, and answered with one word first so the
- * verdict is a prefix test rather than a reading.
+ * Same shape as the eval judge: reasoning first, then the verdict alone on
+ * the last line (judge-verdict.ts says why).
  */
 export function judgePrompt(rubric, reply, work) {
     const shown = reply.slice(0, 20_000);
@@ -1063,12 +1066,11 @@ export function judgePrompt(rubric, reply, work) {
         ? `Everything the step wrote while working, for context. "The reply" means only the reply block below, ` +
             `never this:\n<work>\n${work.slice(-20_000)}\n</work>\n\n`
         : "";
-    return (`You are grading a reply against one requirement. Answer with PASS or FAIL as the ` +
-        `first word, then one sentence of reason.\n\nRequirement: ${rubric}\n\n` +
+    return (`You are grading a reply against one requirement. ${JUDGE_VERDICT_INSTRUCTION}\n\nRequirement: ${rubric}\n\n` +
         context +
         `<reply>\n${shown}\n</reply>`);
 }
-async function judgeReply(rubric, reply, work, env, signal) {
+async function judgeReply(rubric, reply, work, env, signal, model = "haiku", effort) {
     const texts = [];
     const abortController = new AbortController();
     if (signal?.aborted)
@@ -1078,7 +1080,8 @@ async function judgeReply(rubric, reply, work, env, signal) {
         const q = query({
             prompt: judgePrompt(rubric, reply, work),
             options: {
-                model: "haiku",
+                model,
+                ...(effort ? { effort } : {}),
                 systemPrompt: "You grade text against a stated requirement. Be strict and literal.",
                 tools: [],
                 settingSources: [],

package/dist/src/store.d.ts

@@ -3,6 +3,7 @@ import type { BrowserPodOutcome } from "./browser-pod.ts";
 import { singleWorkspace } from "./paths.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { OperatorEvent } from "./operator.ts";
+import { frontmatterErrorText } from "./matter.ts";
 /**
  * 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
@@ -640,9 +641,7 @@ export interface AgentAssets {
 }
 export declare function agentAssets(tenant: string, workspace: string, agent: string): AgentAssets;
 export declare function listAgents(tenant: string, workspace: string): AgentInfo[];
-/** The first line of a YAML parse error, with where it is: what a person
- *  needs to fix the file, without the parser's excerpt. */
-export declare function frontmatterErrorText(err: unknown): string;
+export { frontmatterErrorText };
 /** The option keys a step actually has. An indented `word: rest` that is
  *  NOT one of these is a line of the instruction — "Warning: do not
  *  publish" is prose that happens to contain a colon, and it used to be
@@ -1069,6 +1068,14 @@ export interface StepAttempt {
 export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs" | "turns">;
 export { type TokenUsage, type PromptLayerRecord, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens, promptLayersChanged, promptCacheNote } from "./tokens.ts";
 import { type TokenUsage, type PromptLayerRecord } from "./tokens.ts";
+/** The marker rescueStep puts in a rescue's instruction; how a rescue record
+ *  written before `rescueOf` existed is still recognised. */
+export declare const RESCUE_MARKER = "<rescue>\nYou are taking this step over:";
+/** Is this record an on-fail rescue rather than a step of the flow? */
+export declare function isRescueRecord(step: {
+    rescueOf?: string;
+    instruction?: string | null;
+}): boolean;
 export interface StepRecord {
     agent: string;
     instruction: string;
@@ -1228,6 +1235,13 @@ export interface StepRecord {
      *  actually executed in. Carried steps provide context and are never
      *  billed again — the original run's ledger line already paid for them. */
     carriedFrom?: string;
+    /** Set on an on-fail rescue record (runner.ts rescueStep): the agent of the
+     *  failed step it took over. A rescue is not a step of the flow: a resumed
+     *  drive must not launch it as one of its group, and a re-run must not
+     *  copy it as work (21 Oct 2026: one rerun carried 77 fixers as pending
+     *  steps). Records written before this field are recognised by their
+     *  instruction's `<rescue>` block instead — see isRescueRecord. */
+    rescueOf?: string;
     /**
      * Sandbox seconds this step rented, and how many of them were cold start.
      * Set only on the isolated path — an in-process step rents nothing, so