@foldrun/core 2.5.0 → 2.7.0

package/src/scan.ts

@@ -27,7 +27,7 @@
 // reported, because "why is this allowed?" is the question a reviewer asks.
 
 import crypto from "node:crypto";
-import matter from "./matter.ts";
+import matter, { frontmatterErrorLine, frontmatterErrorText, parseLenient, configMatter } from "./matter.ts";
 import { refNames } from "./refs.ts";
 import { resolveNetwork } from "./network.ts";
 import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.ts";
@@ -223,6 +223,35 @@ export const SCAN_RULES: readonly ScanRule[] = [
       "`effort: extreme`, `size: giant`, `trigger: sometimes`, a cron the scheduler cannot read: each is ignored or falls back, " +
       "so the agent or flow quietly does something else. The message lists what the field takes.",
   },
+  {
+    id: "config/conflict",
+    category: "config",
+    level: "error",
+    title: "A field set twice: at the top and inside its job block",
+    help:
+      "`limits:` at the top and `limits:` inside `guardrail:` cannot both be meant. The top one would be read and the other " +
+      "quietly ignored, so the file is refused until one is removed.",
+  },
+  {
+    id: "config/misplaced",
+    category: "config",
+    level: "error",
+    title: "A field inside the wrong job block",
+    help:
+      "Each of the four blocks (governance, guardrail, observability, evaluation) holds its own fields. A setting written in " +
+      "another block is not read — a guardrail under governance: guards nothing — so the file is refused until it is moved " +
+      "to the block the message names, or to the top. A word foldrun does not read at all is only a note.",
+  },
+  {
+    id: "config/invalid-frontmatter",
+    category: "config",
+    level: "warn",
+    title: "Frontmatter that YAML cannot read",
+    help:
+      "A value with a colon followed by a space (`description: the format (Markdown, ::: directives)`) ends the YAML. " +
+      "foldrun reads a skill like that by quoting the value, but the dashboard editor and the source API refuse to save it, " +
+      "and other tools that read the file may not. Quote the value: `description: \"…\"`.",
+  },
   {
     id: "config/missing-field",
     category: "config",
@@ -601,17 +630,31 @@ export function nearestField(key: string, known: readonly string[]): string | nu
 }
 
 function keyLine(lines: string[], key: string): number | undefined {
-  const re = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:`);
-  const i = lines.findIndex((l) => re.test(l));
-  return i >= 0 ? i + 1 : undefined;
+  const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const top = new RegExp(`^${k}\\s*:`);
+  const i = lines.findIndex((l) => top.test(l));
+  if (i >= 0) return i + 1;
+  // A key inside one of the four job blocks: indented, under its header.
+  const inner = new RegExp(`^\\s+${k}\\s*:`);
+  let inBlock = false;
+  for (let n = 0; n < lines.length; n++) {
+    const l = lines[n]!;
+    if (/^(governance|guardrail|observability|evaluation)\s*:\s*(#.*)?$/.test(l)) inBlock = true;
+    else if (/^\S/.test(l)) inBlock = false;
+    else if (inBlock && inner.test(l)) return n + 1;
+  }
+  return undefined;
 }
 
 /** Read-only: gray-matter caches by content, so two files with the same
  *  text share one object, and writing to it would leak between them. */
-function frontOf(content: string): Record<string, unknown> | null {
+function frontOf(content: string, filePath?: string): Record<string, unknown> | null {
   if (!/^?---\r?\n/.test(content)) return null;
   try {
-    return matter(content).data as Record<string, unknown>;
+    // An agent, a flow or AGENTS.md reads its job blocks as flat keys, as
+    // the runtime does; every other document is read as written.
+    const kind = filePath ? schemaKindOf(filePath) : null;
+    return (kind === "agent" || kind === "flow" || kind === "agents-md" ? configMatter(content) : matter(content)).data as Record<string, unknown>;
   } catch {
     return null; // a frontmatter YAML cannot read is check's finding, not ours
   }
@@ -773,6 +816,16 @@ const VENDORED = /(?:^|\/)(?:node_modules|\.venv|venv|site-packages|__pycache__|
  *  since a key in a log here is a key in the workspace (seen live on
  *  17 Oct 2026: zero-width characters in a CLI MCP log, reported as hidden
  *  text). */
+/** The definition files a deploy refuses outright when their frontmatter does
+ *  not parse (deploy.ts deployIssues): the workspace's own, by these paths.
+ *  Everything else the platform reads frontmatter from — skills, and the
+ *  account library's agents, tools and hooks — is the scanner's to report. */
+export const STRICT_FRONTMATTER_PATH = /^(AGENTS\.md|agents\/[^/]+\/agent\.md|flows\/[^/]+\.md|tools\/[^/]+\.md|tools\/[^/]+\/tool\.md|evals\/[^/]+\.md|hooks\/[^/]+\/hook\.md|\.claude\/agents\/[^/]+\.md)$/;
+
+/** A skill file in either layout the runtime discovers: <name>/SKILL.md, or
+ *  the flat <name>.md, under skills/ or .agents/skills/, in the library too. */
+const SKILL_FILE = /(?:^|\/)skills\/(?:[^/]+\/SKILL\.md|[^/]+\.md)$/;
+
 const RUNTIME_WRITTEN = /(?:^|\/)(?:\.cache|\.npm|\.local|\.pnpm-store|\.yarn|\.foldrun)\//;
 
 /** Text files only — a PNG read as UTF-8 is noise to every rule here. */
@@ -833,9 +886,34 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
     scanSupplyChain(f, lines, push);
 
     const schema = schemaKindOf(f.path);
+    // Frontmatter YAML cannot read. Until 2026-10-21 nothing reported it for
+    // a skill or a library file: frontOf below reads it as "no frontmatter"
+    // and moves on, and the deploy's own refusal covers only the workspace's
+    // definition files. A vaza.ai skill with `description: … (Markdown,
+    // frontmatter, ::: directives) …` deployed clean, ran (the runtime quotes
+    // the value and retries), and was refused by the source API on its next
+    // save.
+    if ((schema || SKILL_FILE.test(f.path)) && !STRICT_FRONTMATTER_PATH.test(f.path) && /^\uFEFF?---\r?\n/.test(f.content)) {
+      let err: unknown = null;
+      try {
+        matter(f.content);
+      } catch (e) {
+        err = e;
+      }
+      if (err) {
+        const isSkill = schema === "skill" || SKILL_FILE.test(f.path);
+        const read = parseLenient(f.content);
+        const what = isSkill && !read.failed
+          ? "foldrun reads this skill anyway by quoting the value, but the dashboard editor and the source API refuse to save it, and other skills clients may not load it"
+          : isSkill
+            ? "the runtime reads it as empty, so the skill has no name or description and is never loaded"
+            : "the runtime cannot read this file";
+        push("config/invalid-frontmatter", f.path, frontmatterErrorLine(err), `config/invalid-frontmatter ${frontmatterErrorText(err)}`, `${frontmatterErrorText(err)} ${what === "the runtime cannot read this file" ? "The runtime cannot read this file" : what.replace(/^foldrun/, "foldrun").replace(/^the/, "The")}.`);
+      }
+    }
     // A skill with no frontmatter at all is the clearest one that never
     // loads: read it as empty, so its required fields are reported.
-    const data = schema || docKind(f.path) ? (frontOf(f.content) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
+    const data = schema || docKind(f.path) ? (frontOf(f.content, f.path) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
     if (!data) continue;
     if (schema) {
       for (const p of frontmatterProblems(schema, data, nearestField)) {
@@ -859,7 +937,7 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
   }
   // project.md is the older name the runtime still reads (Codex review, FOL-58).
   const workspaceMd = files.find((f) => f.path === "AGENTS.md") ?? files.find((f) => f.path === "project.md");
-  scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content)?.network : undefined });
+  scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content, "AGENTS.md")?.network : undefined });
   for (const m of more.values()) {
     findings.push({ rule: m.rule, level: m.level ?? scanRule(m.rule)?.level ?? "warn", file: m.file, message: `and ${m.n} more like this in this file, not listed`, fingerprint: m.hash.digest("hex").slice(0, 16), truncated: true });
   }

package/src/secret-files.ts

@@ -21,7 +21,7 @@ import path from "node:path";
 import {
   isFileValue, fileContent,
   isSshValue, sshConfigOf,
-  isApiValue, apiConfigOf,
+  isApiValue, apiConfigOf, isClientCertValue, clientCertOf,
 } from "./secrets.ts";
 
 // POSIX single-quoting: the one escape sh actually honours inside ' is none,
@@ -46,7 +46,7 @@ export function materializeFileSecrets(
   env: Record<string, string>,
 ): { env: Record<string, string>; dir: string | null } {
   const entries = Object.entries(env).filter(
-    ([, v]) => typeof v === "string" && (isFileValue(v) || isSshValue(v) || isApiValue(v)),
+    ([, v]) => typeof v === "string" && (isFileValue(v) || isSshValue(v) || isApiValue(v) || isClientCertValue(v)),
   );
   if (entries.length === 0) return { env, dir: null };
 
@@ -62,6 +62,26 @@ export function materializeFileSecrets(
       const file = path.join(dir, name.toLowerCase());
       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/src/secrets.ts

@@ -88,7 +88,7 @@ function secretsFile(tenant: string, workspace?: 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;
@@ -236,6 +236,11 @@ export function setSecretSites(tenant: string, name: string, sites: string[], wo
     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 delete rec.sites;
     return all;
@@ -545,7 +550,9 @@ export function rotateMasterKey(
 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"
@@ -573,9 +580,14 @@ export function setOAuth2Secret(
   config: OAuth2Config,
   workspace?: string,
 ) {
-  for (const field of ["token_url", "client_id", "client_secret"] as const) {
+  for (const field of ["token_url", "client_id"] as const) {
     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)");
   }
@@ -597,11 +609,67 @@ export function isOAuth2Value(value: string): boolean {
 const tokenCache = new Map<string, { token: string; expiresAt: number }>();
 const inFlight = new Map<string, Promise<string>>();
 
-async function exchange(config: OAuth2Config, cacheKey: string): Promise<string> {
-  const cached = tokenCache.get(cacheKey);
-  if (cached && cached.expiresAt > Date.now()) return cached.token;
+/**
+ * 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: "oauth2" | "sa", storedValue: string, tenant?: string): string {
+  return crypto.createHash("sha256").update(JSON.stringify([kind, tenant ?? "", storedValue])).digest("hex");
+}
 
-  const pending = inFlight.get(cacheKey);
+/**
+ * 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: string, name: string, workspace: string | undefined, usedValue: string, refreshToken: string): boolean {
+  if (!isOAuth2Value(usedValue)) return false;
+  const config = JSON.parse(usedValue.slice(OAUTH2_PREFIX.length)) as OAuth2Config;
+  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;
+}
+
+/** An oauth2 refresh's outcome: the access token and, when the provider
+ *  rotated it, the new refresh token — kept with the cache entry so every
+ *  copy of the old credential (another secret name, another scope) that is
+ *  served this token also gets the new refresh token written back. */
+interface OAuthLive { token: string; expiresAt: number; rotated?: string }
+const oauthCache = new Map<string, OAuthLive>();
+const oauthFlight = new Map<string, Promise<OAuthLive>>();
+
+/** 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: string, live: OAuthLive): void {
+  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: OAuth2Config, cacheKey: string): Promise<OAuthLive> {
+  const cached = oauthCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) return cached;
+
+  const pending = oauthFlight.get(cacheKey);
   if (pending) return pending;
 
   const flight = (async () => {
@@ -609,7 +677,7 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<string>
       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"
@@ -639,6 +707,7 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<string>
     if (!res) throw lastNetwork instanceof Error ? lastNetwork : new Error(String(lastNetwork));
     const payload = (await res.json().catch(() => ({}))) as {
       access_token?: string;
+      refresh_token?: string;
       expires_in?: number;
       error?: string;
       error_description?: string;
@@ -649,15 +718,21 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<string>
       );
     }
     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: OAuthLive = { 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);
   }
 }
 
@@ -685,13 +760,21 @@ export async function materializeSecrets(
         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);
         const link = ctx ? await platform.noteOAuthRefresh(ctx, name, message).catch(() => undefined) : undefined;
@@ -706,7 +789,7 @@ export async function materializeSecrets(
         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)}`);
       }
@@ -737,6 +820,10 @@ export interface ServiceAccountConfig {
   scope: string; // space-separated
   /** 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 function setServiceAccountSecret(
@@ -751,7 +838,12 @@ export function setServiceAccountSecret(
   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: ServiceAccountConfig = { ...config, ...(config.subject !== undefined ? { subject: config.subject.trim() } : {}) };
+  setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(stored), workspace, "service-account");
 }
 
 function base64url(input: Buffer | string): string {
@@ -770,7 +862,9 @@ async function exchangeServiceAccount(config: ServiceAccountConfig, cacheKey: st
     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,
@@ -898,14 +992,134 @@ export function sshConfigOf(value: string): SshConfig {
 // never appears in the bash command at all.
 
 const API_PREFIX = "@api ";
+const CLIENT_CERT_PREFIX = "@client-cert ";
+
+/** 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 function setClientCertSecret(tenant: string, name: string, config: ClientCertConfig, workspace?: string) {
+  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: ClientCertConfig = {
+    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 ";
+
+/** 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 function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string) {
+  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: string): boolean {
+  return value.startsWith(IDENTITY_PREFIX);
+}
+
+export function identityOf(value: string): IdentityConfig {
+  return JSON.parse(value.slice(IDENTITY_PREFIX.length));
+}
+
+export function isClientCertValue(value: string): boolean {
+  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: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(env).filter(([, v]) => typeof v !== "string" || !isClientCertValue(v) || clientCertOf(v).export === true));
+}
+
+export function clientCertOf(value: string): ClientCertConfig {
+  return JSON.parse(value.slice(CLIENT_CERT_PREFIX.length));
+}
 
 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 function basicAuthorization(username: string, password: string): string {
+  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: string, name: string, config: ApiConfig, workspace?: string) {
-  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: URL | null = 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) {
     if (!/^[A-Za-z0-9-]+$/.test(h)) throw new Error(`"${h}" is not a valid header name`);

package/src/starter.ts

@@ -62,6 +62,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}
@@ -492,6 +508,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.