@foldrun/core 0.3.0 → 0.4.0

package/src/budget.ts

@@ -0,0 +1,178 @@
+// A budget is a number and a period — what may be spent, and over what.
+//
+// One grammar, read in four places: an agent's `budget:` (the most that
+// agent may spend in one run), a flow's (the most one run may spend), a
+// workspace's and the account's (a cap over a window of time). The value
+// was a bare number meaning "per month" in a workspace or account file and
+// "per run" in a flow; it still is, and it can now also say which:
+//
+//     budget: 60            a number alone: per run in a flow or an agent,
+//                           per month in a workspace or the account
+//     budget: 60/day        or 60/week, 60/month
+//     budget: unlimited     no cap — the same as leaving the key out
+//
+// Unset means no limit. That is the platform's rule, not an accident of
+// parsing: a customer who has not written a cap has not asked for one, and
+// nothing here invents a default they would then have to find and raise.
+//
+// Windows follow the account's calendar (`timezone:` in AGENTS.md), the
+// same one the scheduler and "today" already use, because a daily cap that
+// resets at 10am Sydney time is not a daily cap anyone meant.
+
+export type BudgetPeriod = "run" | "day" | "week" | "month";
+
+export interface Budget {
+  usd: number;
+  period: BudgetPeriod;
+}
+
+/** Words that mean "no cap", case-insensitively. */
+const UNLIMITED = new Set(["unlimited", "none", "no limit", "no-limit", "off", "-", "~"]);
+
+const PERIODS: Record<string, BudgetPeriod> = {
+  run: "run",
+  day: "day",
+  daily: "day",
+  week: "week",
+  weekly: "week",
+  month: "month",
+  monthly: "month",
+};
+
+// `\d+(?:\.\d+)?` with an optional separator and one period word: every
+// part has one way to match, so a hostile string cannot make it backtrack.
+const FORM_RE = /^\$?(\d+(?:\.\d+)?)(?:\s*(?:\/|per|a|each)?\s*([a-z]+))?$/;
+
+/**
+ * The budget a frontmatter value declares, or null for "no cap".
+ *
+ * Lenient on purpose: a value nobody can read is treated as no cap rather
+ * than as a cap of zero, because refusing every run over a typo is the worse
+ * failure. `budgetProblem` is the strict reading, for lint and the editor.
+ */
+export function parseBudget(raw: unknown, defaultPeriod: BudgetPeriod): Budget | null {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw === "number") return Number.isFinite(raw) && raw > 0 ? { usd: raw, period: defaultPeriod } : null;
+  if (typeof raw !== "string") return null;
+  const s = raw.trim().toLowerCase();
+  if (!s || UNLIMITED.has(s)) return null;
+  const m = FORM_RE.exec(s);
+  if (!m) return null;
+  const usd = Number(m[1]);
+  if (!Number.isFinite(usd) || usd <= 0) return null;
+  const period = m[2] ? PERIODS[m[2]] : defaultPeriod;
+  if (!period) return null;
+  return { usd, period };
+}
+
+/**
+ * What is wrong with a `budget:` value, in a sentence, or null when it is
+ * fine. `allowed` names the periods this file may use — an agent's or a
+ * flow's budget is per run and nothing else; a workspace's or the account's
+ * is over time and never per run.
+ */
+export function budgetProblem(raw: unknown, allowed: BudgetPeriod[]): string | null {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw === "number") {
+    if (!Number.isFinite(raw) || raw < 0) return `budget: ${String(raw)} is not an amount in USD`;
+    return null;
+  }
+  if (typeof raw !== "string") return `budget: must be a number, "<number>/<day|week|month>", or unlimited`;
+  const s = raw.trim().toLowerCase();
+  if (!s || UNLIMITED.has(s)) return null;
+  const m = FORM_RE.exec(s);
+  if (!m) return `budget: "${raw}" is not a number, "<number>/<day|week|month>", or unlimited`;
+  if (m[2]) {
+    const period = PERIODS[m[2]];
+    if (!period) return `budget: "${m[2]}" is not a period — day, week or month`;
+    if (!allowed.includes(period)) {
+      return period === "run"
+        ? `budget: is per run here already — write the number alone`
+        : `budget: "${period}" does not apply here — this cap is per run; a cap over time belongs in the workspace's or the account's AGENTS.md`;
+    }
+  }
+  return null;
+}
+
+/** "$60/day", "$500/month", "$6/run". */
+export function formatBudget(b: Budget): string {
+  const usd = Number.isInteger(b.usd) ? String(b.usd) : b.usd.toFixed(2);
+  return `$${usd}/${b.period}`;
+}
+
+/** "today", "this week", "this month" — the window a spend is measured in. */
+export function windowName(period: BudgetPeriod): string {
+  return period === "day" ? "today" : period === "week" ? "this week" : period === "month" ? "this month" : "this run";
+}
+
+/** What to wait for when the cap is reached. */
+export function windowTurnsHint(period: BudgetPeriod): string {
+  return period === "day" ? "wait for tomorrow" : period === "week" ? "wait for next week" : "wait for the new month";
+}
+
+// ------------------------------------------------------------ the window
+
+function partsIn(timeZone: string, at: Date): { y: number; m: number; d: number; h: number; min: number; s: number; weekday: number } {
+  const f = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "numeric",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    weekday: "short",
+  });
+  const p: Record<string, string> = {};
+  for (const { type, value } of f.formatToParts(at)) p[type] = value;
+  const weekdays = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+  return {
+    y: Number(p.year),
+    m: Number(p.month),
+    d: Number(p.day),
+    h: Number(p.hour),
+    min: Number(p.minute),
+    s: Number(p.second),
+    weekday: weekdays.indexOf(p.weekday),
+  };
+}
+
+/** The zone's offset from UTC at an instant, in ms (positive east). */
+function offsetMs(timeZone: string, atMs: number): number {
+  const p = partsIn(timeZone, new Date(atMs));
+  return Date.UTC(p.y, p.m - 1, p.d, p.h, p.min, p.s) - Math.floor(atMs / 1000) * 1000;
+}
+
+/** Midnight at the start of a local calendar date, as a UTC instant. */
+function localMidnightMs(timeZone: string, y: number, m: number, d: number): number {
+  const naive = Date.UTC(y, m - 1, d);
+  let t = naive - offsetMs(timeZone, naive);
+  // Once more from the answer: across a DST change the first guess can be
+  // off by the shift, and the second pass lands on the real midnight.
+  const again = naive - offsetMs(timeZone, t);
+  if (again !== t) t = again;
+  return t;
+}
+
+/**
+ * When the current window began, as a UTC instant — the moment spend is
+ * summed from. Today's midnight, Monday's midnight, or the first of the
+ * month, all in the given calendar. A per-run budget has no window.
+ */
+export function windowStartMs(period: BudgetPeriod, timeZone: string, now = new Date()): number | null {
+  if (period === "run") return null;
+  let tz = timeZone;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+  } catch {
+    tz = "UTC";
+  }
+  const p = partsIn(tz, now);
+  if (period === "day") return localMidnightMs(tz, p.y, p.m, p.d);
+  if (period === "month") return localMidnightMs(tz, p.y, p.m, 1);
+  // Monday. Walk back on the naive calendar, then take that date's midnight.
+  const back = (p.weekday + 6) % 7;
+  const monday = new Date(Date.UTC(p.y, p.m - 1, p.d - back));
+  return localMidnightMs(tz, monday.getUTCFullYear(), monday.getUTCMonth() + 1, monday.getUTCDate());
+}

package/src/catalog.ts

@@ -23,6 +23,7 @@ import path from "node:path";
 import { dataRoot } from "./paths.ts";
 import { resolveModel, resolveTier, MODEL_TIERS, EFFORT_LEVELS, type Effort, type Tier, type FlowInfo } from "./store.ts";
 import type { FlowWarning } from "./flow-lint.ts";
+import { trimSlashes } from "./paths.ts";
 
 export interface CatalogModel {
   id: string;
@@ -115,7 +116,7 @@ export async function loadCatalog(baseUrl: string): Promise<Catalog | null> {
   if (cached && Date.now() - Date.parse(cached.fetchedAt) < TTL_MS) return cached;
 
   try {
-    const res = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/models`, {
+    const res = await fetch(`${trimSlashes(baseUrl)}/v1/models`, {
       signal: AbortSignal.timeout(10_000),
     });
     if (!res.ok) throw new Error(`${res.status}`);

package/src/confine.ts

@@ -148,7 +148,12 @@ export const isFilesystemTool = (toolName: string) => FS_TOOLS.has(toolName);
  */
 export function suggestPath(raw: string): string {
   const posix = raw.split(path.sep).join("/");
-  const m = posix.match(/(?:^|\/)(outputs|storage|state|memory|knowledge)\/(.+)$/);
+  // By segments, not by regex: an unanchored `(.+)$` re-scans from every
+  // slash, and this runs on a path an agent chose.
+  const KNOWN = ["outputs", "storage", "state", "memory", "knowledge"];
+  const segs = posix.split("/");
+  const at = segs.findIndex((seg, i) => KNOWN.includes(seg) && segs.slice(i + 1).join("/") !== "");
+  const m = at === -1 ? null : ([null, segs[at], segs.slice(at + 1).join("/")] as const);
   if (m) {
     const [, dir, rest] = m;
     return dir === "outputs"

package/src/egress.ts

@@ -35,6 +35,9 @@
 // platform's (it needs a long-lived process and a Service); the pod side is
 // here in core, because it is what the runner image runs.
 
+import { trimSlashes } from "./paths.ts";
+import type { TestEffect } from "./test-mode.ts";
+
 /** `${NAME}` — the shape a secret reference takes everywhere in foldrun. */
 export const PLACEHOLDER = /\$\{([A-Z][A-Z0-9_]*)\}/g;
 
@@ -51,7 +54,7 @@ export const MODEL_KEY_NAME = "FOLDRUN_MODEL_KEY";
  */
 export function viaEgress(egress: string | undefined | null, target: string): string {
   if (!egress) return target;
-  return `${egress.replace(/\/+$/, "")}/${target}`;
+  return `${trimSlashes(egress)}/${target}`;
 }
 
 /** The names referenced by placeholders in a string. */
@@ -86,6 +89,11 @@ export function hostOf(url: string): string | null {
 export interface EgressGrant {
   /** Secret name → the hosts that secret may be substituted for. */
   secrets: Record<string, { value: string; hosts: string[] }>;
+  /** Secret name → the vault entry it came from, as secret-health keys it:
+   *  "account:NAME" or "workspace:<ws>:NAME". Two workspaces each holding an
+   *  API_KEY are two credentials, and one's refusal must not paint the
+   *  other red. Absent for a secret whose origin the runner did not know. */
+  healthKeys?: Record<string, string>;
 }
 
 export interface EgressLease {
@@ -96,19 +104,27 @@ export interface EgressLease {
    *  lease URL first), so a store that is not this process's memory has
    *  to be told when the grant is complete. Call before every attempt. */
   commit(): Promise<void>;
-  /** One line per request, for the run trace. Drained by the runner. */
-  drainLog(): Promise<string[]>;
+  /** One line per request, for the run trace. Drained by the runner. A
+   *  line may carry a test-mode effect beside its text — what the proxy
+   *  refused or redirected on a test lease — for the run page to list. */
+  drainLog(): Promise<EgressLogLine[]>;
   /** The step is over: the lease is void and its values are dropped. */
   release(): Promise<void>;
 }
 
+export type EgressLogLine = string | { text: string; effect: TestEffect };
+
 /**
  * The seam the platform fills. `null` from `lease` (or no `egress` at all)
  * means "no proxy here" and the runner falls back to materialising, exactly
  * as it always did.
  */
 export interface EgressHooks {
-  lease(args: { tenant: string; runId: string; grant: EgressGrant }): Promise<EgressLease | null>;
+  /** `test` — the run is a test run: the proxy applies the outward-write
+   *  policy in test-mode.ts to every request on this lease. Carried on the
+   *  lease, not the request, because the pod is the party not trusted to
+   *  say so. */
+  lease(args: { tenant: string; runId: string; grant: EgressGrant; test?: boolean }): Promise<EgressLease | null>;
 }
 
 /** Strip a header set of the proxy's own and hop-by-hop headers. */

package/src/evals.ts

@@ -48,7 +48,7 @@ import {
   type Effort,
 } from "./store.ts";
 import { startFlowRun, loadFlow } from "./runner.ts";
-import { platform } from "./platform.ts";
+import { platform, platformQueues } from "./platform.ts";
 import type { FlowStep } from "./store.ts";
 
 export type Assertion =
@@ -80,6 +80,10 @@ export interface EvalInfo {
    *  `manual`: only when a person presses Run or the CLI asks — for a flow
    *  eval that costs a whole run and touches real systems every time. */
   trigger: "deploy" | "manual";
+  /** An eval's runs are test runs — nothing outward, state untouched —
+   *  unless the file says `live: true`. A flow eval that must really send
+   *  to prove itself opts in; nothing opts in by accident. */
+  live: boolean;
   cases: EvalCase[];
 }
 
@@ -187,6 +191,7 @@ export function parseEval(file: string, raw: string): EvalInfo {
     model: resolveModel(data.model ?? "fast"),
     effort: resolveEffort(data.effort ?? "low"),
     trigger: data.trigger === "manual" ? "manual" : "deploy",
+    live: data.live === true,
     cases,
   };
 }
@@ -286,7 +291,8 @@ export function promoteRunToEval(
   let expect: string[];
   if (opts.expect && opts.expect.length > 0) {
     expect = opts.expect.map((line) => {
-      const m = oneLine(line).match(/^([a-z-]+):\s*(.*)$/);
+      const m = oneLine(line).match(/^([a-z-]+):(.*)$/);
+      if (m) m[2] = m[2].trim();
       if (!m || !(ASSERTION_TYPES as readonly string[]).includes(m[1]) || !m[2]) {
         throw refuse(
           `"${line}" is not an assertion — expected one of ${ASSERTION_TYPES.map((t) => `${t}:`).join(", ")} followed by a value`,
@@ -325,7 +331,7 @@ export function promoteRunToEval(
         409,
       );
     }
-    content = `${existing.replace(/\s+$/, "")}\n\n${caseText}`;
+    content = `${existing.trimEnd()}\n\n${caseText}`;
   } else {
     // A flow eval costs a whole run and touches real systems, so it waits
     // for a person to press Run rather than following every push.
@@ -389,16 +395,20 @@ export interface EvalResult {
   error?: string;
 }
 
-/** Wait for a run to finish, with a ceiling so a hung agent can't hang an eval. */
 /**
  * A web replica never drives a run: it has no route to the cluster API and
  * no right to create a pod, by design — so an eval started there (a push,
  * the Run button) queues its run for the worker like any other. From 29 Aug
  * every eval on the split platform died at "pod create failed: connection
  * refused" for exactly this reason. A single process — the CLI, a laptop,
- * FOLDRUN_ROLE unset — still drives it right here, as it always did.
+ * no platform registered — still drives it right here, as it always did.
+ *
+ * The test is whether a platform owns the queue, not which role this
+ * process was started as: on a worker the role read "worker", the eval
+ * started its run in-process, and the run never passed through the
+ * account cap or the lanes the platform enforces on every other run.
  */
-const runsViaQueue = () => process.env.FOLDRUN_ROLE === "web";
+const runsViaQueue = () => platformQueues();
 
 async function beginEvalRun(
   tenant: string,
@@ -407,8 +417,9 @@ async function beginEvalRun(
   flowName: string,
   model?: string | null,
   effort?: string | null,
+  test = true,
 ) {
-  if (!runsViaQueue()) return startFlowRun(tenant, workspace, steps, flowName, model, [], effort);
+  if (!runsViaQueue()) return startFlowRun(tenant, workspace, steps, flowName, model, [], effort, null, { test });
   // The job carries a model override but no effort one, and driveRun cannot
   // re-read a flow called `eval:<name>`. Put the flow's defaults onto the
   // steps that have none — which is what nearest-wins resolves to anyway.
@@ -417,7 +428,7 @@ async function beginEvalRun(
     ...(s.model || !model ? {} : { model }),
     ...(s.effort || !effort ? {} : { effort }),
   }));
-  return platform.enqueueFlowRun(tenant, workspace, withDefaults, flowName, model ?? null, []);
+  return platform.enqueueFlowRun(tenant, workspace, withDefaults, flowName, model ?? null, [], null, { test });
 }
 
 // Waits for as long as the run runs. There was a cap here (5 minutes, then
@@ -558,7 +569,9 @@ export async function runEval(
             ? { ...s, instruction: `${s.instruction}\n\n<run_task>\n${testCase.task}\n</run_task>` }
             : s,
         );
-        run = await beginEvalRun(tenant, workspace, steps, `eval:${info.name}`, flow.model, flow.effort);
+        // Test unless the eval OR the flow says live: an eval that runs a
+        // flow written `live: true` was written by someone who knew.
+        run = await beginEvalRun(tenant, workspace, steps, `eval:${info.name}`, flow.model, flow.effort, !(info.live || flow.live));
       } else {
         if (!target) throw new Error("this eval names neither an agent nor a flow");
         run = await beginEvalRun(
@@ -566,6 +579,9 @@ export async function runEval(
           workspace,
           [{ agent: target, instruction: testCase.task, group: 1, optional: false }],
           `eval:${info.name}`,
+          undefined,
+          undefined,
+          !info.live,
         );
       }
       runId = run.id;

package/src/flow-lint.ts

@@ -20,6 +20,10 @@ export interface FlowWarning {
   line?: number;
   message: string;
   detail: string;
+  /** "error" for a value the parser could not read — `timeout: abc` — which
+   *  `foldrun check` must fail on rather than note. Absent means advisory,
+   *  which every structural warning in this file is. */
+  level?: "error" | "warn";
 }
 
 // Anaphora: phrases that only mean something if earlier output exists.
@@ -35,6 +39,18 @@ export interface KnownNames {
   agents: string[];
 }
 
+/** One @, something either side, a dot in the domain, no whitespace. Written
+ *  as string checks rather than a regex: the obvious pattern backtracks
+ *  polynomially on a domain full of dots, and a lint that can be made slow
+ *  by a flow file is a lint someone will turn off. */
+function looksLikeAddress(a: string): boolean {
+  const at = a.indexOf("@");
+  if (at < 1 || at !== a.lastIndexOf("@") || /\s/.test(a)) return false;
+  const domain = a.slice(at + 1);
+  const dot = domain.indexOf(".");
+  return dot > 0 && dot < domain.length - 1;
+}
+
 export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
   const warnings: FlowWarning[] = [];
   const agentNames = known ? new Set(known.agents) : null;
@@ -47,6 +63,71 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
   // eleven runs where one was meant. Nothing about the expression looks wrong,
   // which is exactly why it needs saying here rather than being discovered on
   // the bill.
+  // An approvers list only one word can satisfy. `approvers: [editors]` is
+  // a role that is not `admins` and not an address; mayApprove would then
+  // refuse every person, and the gate could only ever be answered by an
+  // emailed link. Said here rather than discovered at the gate.
+  const odd = (flow.approvers ?? []).filter((a) => a !== "admins" && !looksLikeAddress(a));
+  if (odd.length) {
+    warnings.push({
+      step: null,
+      message: `approvers: ${odd.join(", ")} — not an email address, and the only role word is admins`,
+      detail: "Each entry is an address that may answer this flow's gates, or the word `admins`. Anything else matches nobody, and a list nobody matches locks every gate.",
+    });
+  }
+  // A flow with an approvers list and no gate at all is a rule the author
+  // believes is in force and which does nothing — the worst kind of safety
+  // control.
+  if (flow.approvers?.length && !flow.steps.some((s) => s.approve || s.ask)) {
+    warnings.push({
+      step: null,
+      message: "approvers: is set but no step in this flow is a gate",
+      detail:
+        "Nothing here waits for a person, so the list has no effect. Mark the step that needs " +
+        "a second pair of eyes with `!` (or `approve: true`), or drop the approvers: line.",
+    });
+  }
+  // A deadline on a gate that does not exist reads as a safety net and is not
+  // one. Same reasoning, said separately because the fix is different.
+  if (flow.approveWithin && !flow.steps.some((s) => s.approve || s.ask)) {
+    warnings.push({
+      step: null,
+      message: "approve_within: is set but no step in this flow is a gate",
+      detail: "Nothing waits for a person, so nothing can expire. Mark a step with `!`, or drop the line.",
+    });
+  }
+  // A throttle no schedule can ever trip: the flow cannot run more often
+  // than its cron fires, so a floor below that interval never fires either.
+  // Cheap to write, silently pointless, and a reader will believe it.
+  if (flow.throttle && flow.trigger === "schedule" && flow.schedule) {
+    warnings.push({
+      step: null,
+      message: `throttle: on a scheduled flow — check it is shorter than the schedule, or it will drop runs you meant to happen`,
+      detail:
+        "A schedule already decides how often this runs. A throttle longer than the gap between " +
+        "fires silently skips them; if that is what you want, say it in the cron instead.",
+    });
+  }
+  // `idempotency:` only has a delivery to read on a trigger that receives
+  // one. On a schedule or a chained flow there is no request and no field,
+  // so the key is inert.
+  if (flow.idempotency && flow.trigger !== "webhook" && flow.trigger !== "email") {
+    warnings.push({
+      step: null,
+      message: `idempotency: has nothing to read on trigger: ${flow.trigger}`,
+      detail:
+        "A delivery id comes off an incoming request, so this only does something for " +
+        "trigger: webhook or trigger: email. On any other trigger it is ignored.",
+    });
+  }
+  // `catchup:` is about a fire that was missed, which only a clock can miss.
+  if (flow.catchup && flow.trigger !== "schedule") {
+    warnings.push({
+      step: null,
+      message: `catchup: has no effect on trigger: ${flow.trigger}`,
+      detail: "Only a schedule can miss a fire. Every other trigger happens when it happens.",
+    });
+  }
   if (flow.schedule) {
     const [, , dom, , dow] = flow.schedule.trim().split(/\s+/);
     if (dom && dow && dom !== "*" && dow !== "*") {
@@ -63,6 +144,9 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
 
   // Trigger shapes that can never fire, said at check time rather than
   // discovered as a flow that "never runs".
+  if (flow.budgetProblem) {
+    warnings.push({ step: null, message: flow.budgetProblem, detail: "A flow's `budget:` is the most one run may spend — a number in USD, or `unlimited`. A cap over a day, week or month belongs in the workspace's or the account's AGENTS.md, where it means every run put together." });
+  }
   if (flow.trigger === "once" && !flow.at) {
     warnings.push({ step: null, message: "trigger: once needs an `at:` instant", detail: "Write `at: 2026-09-05T09:00:00+10:00` (ISO 8601). Without a readable instant this flow never fires." });
   }
@@ -87,6 +171,22 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
   flow.steps.forEach((step, i) => {
     const inFirstGroup = step.group === firstGroup;
 
+    // A value the parser refused. Not advisory: the run would go ahead on
+    // a number the author never wrote — `timeout: 15m` ran as one second
+    // for as long as this was a coercion — so the check fails instead.
+    for (const problem of step.problems ?? []) {
+      warnings.push({
+        step: i,
+        line: step.line,
+        level: "error",
+        message: problem,
+        detail:
+          "The option is written but its value cannot be read, and a run would not do what the " +
+          "line says. Durations are seconds or 90s / 30m / 4h / 3d; counts are whole numbers " +
+          "within the key's cap (retry and loop at most 5, max at most 20).",
+      });
+    }
+
     // The first group starts with context = null. An instruction that points
     // at earlier output therefore points at nothing.
     if (inFirstGroup && step.instruction && REFERS_BACK.test(step.instruction)) {
@@ -133,6 +233,24 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
       }
     }
 
+    // Two options that read another option to mean anything.
+    if (step.parallel && !step.each) {
+      warnings.push({
+        step: i,
+        line: step.line,
+        message: `"${step.subflow ?? step.agent}" has parallel: but no each:`,
+        detail: "parallel: caps how many instances of a fan-out run at once. Without each: there is one instance, and the line does nothing.",
+      });
+    }
+    if ((step.schema !== undefined || step.schemaPath) && step.output !== "json") {
+      warnings.push({
+        step: i,
+        line: step.line,
+        message: `"${step.subflow ?? step.agent}" has schema: but no output: json`,
+        detail: "schema: describes the JSON value an output: json step returns. Without output: json nothing is parsed, so nothing is checked. Add `output: json`.",
+      });
+    }
+
     // A step's OTHER agent references — the ones no parser validates,
     // because they are options rather than the step's target. Both fail
     // silently and at the worst possible moment: a misspelled `delegate:`

package/src/host-env.ts

@@ -0,0 +1,51 @@
+// The environment a step's children start from, on the in-process path.
+//
+// Scripts, `verify:` shells and the SDK's own Bash tool used to inherit the
+// whole of process.env — which on a platform holds FOLDRUN_SECRET_KEY (the
+// key every tenant's vault and hook token derives from), the database URL,
+// the object-store and mail credentials, the Stripe key. `console.log(
+// process.env)` in a script tool was cross-tenant compromise. tool-test.ts
+// built a stripped base for the Test button; this is that base, made the one
+// definition, used everywhere a child is spawned host-side.
+//
+// A run container needs none of this: its process.env IS the boundary,
+// assembled from an allowlist on the host before the container started.
+//
+// What passes is what an interpreter needs to be found and to run, the
+// locale, the clock, the network's proxy settings, and the identifiers the
+// runner stamps on a step (FOLDRUN_RUN_*, FOLDRUN_STEP_*) so a script can
+// say which run made its records. The secrets an agent declares are layered
+// on top by the caller — by name, from the vault, never from the host.
+
+const EXACT = new Set([
+  "PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LANGUAGE",
+  "TZ", "TERM", "SHELL", "USER", "LOGNAME",
+  // The host's way to the network is the child's way to the network.
+  "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy",
+  "SSL_CERT_FILE", "SSL_CERT_DIR",
+  // Windows equivalents, harmless elsewhere.
+  "SYSTEMROOT", "COMSPEC", "PATHEXT", "WINDIR",
+]);
+
+const PREFIXES = ["LC_", "NODE_", "FOLDRUN_RUN_", "FOLDRUN_STEP_"];
+
+/** Does this name pass the allowlist? Exported so a test can pin the rule
+ *  rather than the list. */
+export function hostEnvAllowed(name: string): boolean {
+  return EXACT.has(name) || PREFIXES.some((p) => name.startsWith(p));
+}
+
+/**
+ * process.env, reduced to the allowlist. A fresh object every call, so a
+ * caller that layers secrets on top never writes into the host's own env.
+ */
+export function hostSafeEnv(from: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(from)) {
+    if (typeof v === "string" && hostEnvAllowed(k)) out[k] = v;
+  }
+  // Typed as ProcessEnv, not a string map: a host whose type augmentation
+  // makes a key required (Next declares NODE_ENV so) refuses a plain map at
+  // every spawn. The value is the same either way.
+  return out as NodeJS.ProcessEnv;
+}