@foldrun/core 2.4.0 → 2.5.0

package/dist/src/trace-tree.js

@@ -0,0 +1,156 @@
+// A run as one tree (FOL-72 step 5): run → step → model call → tool call,
+// each with when it started and ended, what it cost in tokens and how it
+// ended — the waterfall every agent-tracing tool opens on. Built from the
+// run record alone (steps, step.calls, the paired tool events), so the run
+// page, GET …/runs/<id>/trace and `foldrun report --tree` read one function.
+//
+// A tool call nests under the model call that asked for it: its event names
+// the call (`inCall`) since 19 Oct 2026; older records are matched by time,
+// to the last model call that answered before the tool started. Pure: no
+// node imports, so the browser can use it.
+const ms = (iso) => {
+    if (!iso)
+        return null;
+    const t = Date.parse(iso);
+    return Number.isNaN(t) ? null : t;
+};
+function stepStatus(s) {
+    if (s.status === "completed")
+        return "ok";
+    if (s.status === "failed")
+        return "error";
+    if (s.status === "running")
+        return "running";
+    if (s.status === "awaiting-approval")
+        return "waiting";
+    if (s.status === "skipped")
+        return "skipped";
+    return "pending";
+}
+/** Tool events paired: the call's start, its duration, whether it erred. */
+function toolCalls(events) {
+    const byCall = new Map();
+    const out = [];
+    for (const e of events) {
+        if (e.type !== "tool")
+            continue;
+        if (e.call && e.ms != null && byCall.has(e.call)) {
+            const open = byCall.get(e.call);
+            open.end = (open.start ?? ms(e.t) ?? 0) + e.ms;
+            open.err ||= e.err === true;
+            open.captured ||= e.captured === true;
+            continue;
+        }
+        const c = { e, start: ms(e.t), end: null, err: e.err === true, captured: e.captured === true };
+        if (e.call)
+            byCall.set(e.call, c);
+        out.push(c);
+    }
+    return out;
+}
+function modelSpan(c, step) {
+    const at = ms(c.at);
+    return {
+        id: `s${step}/m${c.attempt && c.attempt > 1 ? `${c.attempt}.` : ""}${c.n}`,
+        kind: "model",
+        label: c.model ?? "model",
+        // The request went out `ms` before the response began arriving.
+        start: at !== null ? at - c.ms : null,
+        end: at,
+        status: "ok",
+        tokens: c.tokens,
+        ...(c.model ? { model: c.model } : {}),
+        ...(c.stop ? { stop: c.stop } : {}),
+        ...(c.subagent ? { subagent: c.subagent } : {}),
+        step,
+        children: [],
+    };
+}
+function stepSpan(s, i, now) {
+    const first = s.events[0] ? ms(s.events[0].t) : null;
+    const last = s.events.length ? ms(s.events[s.events.length - 1].t) : null;
+    const status = stepStatus(s);
+    const span = {
+        id: `s${i}`,
+        kind: "step",
+        label: s.agent,
+        start: ms(s.startedAt) ?? first,
+        end: ms(s.finishedAt) ?? (status === "running" ? now : last),
+        status,
+        ...(s.tokens ? { tokens: { input: s.tokens.input, output: s.tokens.output, cacheRead: s.tokens.cacheRead ?? 0, cacheWrite: s.tokens.cacheWrite ?? 0 } } : {}),
+        costUsd: s.costUsd ?? null,
+        ...(s.model ? { model: s.model } : {}),
+        step: i,
+        children: [],
+    };
+    const models = (s.calls ?? []).map((c) => ({ c, span: modelSpan(c, i) }));
+    const byId = new Map(models.map((m) => [m.c.id, m.span]));
+    const homeOf = (e, start) => {
+        if (e.inCall && byId.has(e.inCall))
+            return byId.get(e.inCall);
+        // Older records: the last model call (of the same agent) that answered
+        // before the tool started.
+        const same = models.filter((m) => (m.c.subagent ?? null) === (e.subagent ?? null) && m.span.end !== null && start !== null && m.span.end <= start + 50);
+        return same.length ? same[same.length - 1].span : span;
+    };
+    for (const t of toolCalls(s.events)) {
+        const home = homeOf(t.e, t.start);
+        const tool = {
+            id: `s${i}/t:${t.e.call ?? `${t.start}`}`,
+            kind: "tool",
+            label: t.e.text,
+            start: t.start,
+            end: t.end ?? (status === "running" ? now : t.start),
+            status: t.err ? "error" : t.end === null && status === "running" ? "running" : "ok",
+            ...(t.e.call ? { call: t.e.call } : {}),
+            ...(t.captured ? { captured: true } : {}),
+            ...(t.e.subagent ? { subagent: t.e.subagent } : {}),
+            step: i,
+            children: [],
+        };
+        home.children.push(tool);
+    }
+    // A model call lasts until the last tool it asked for has finished.
+    for (const m of models) {
+        const ends = m.span.children.map((c) => c.end).filter((x) => x !== null);
+        if (ends.length && m.span.end !== null)
+            m.span.end = Math.max(m.span.end, ...ends);
+    }
+    span.children.push(...models.map((m) => m.span));
+    // Errors, as leaves: why the step failed, read without opening the trace.
+    s.events.forEach((e, k) => {
+        if (e.type !== "error")
+            return;
+        span.children.push({ id: `s${i}/e${k}`, kind: "error", label: "error", start: ms(e.t), end: ms(e.t), status: "error", text: e.text, step: i, children: [] });
+    });
+    span.children.sort((a, b) => (a.start ?? Infinity) - (b.start ?? Infinity));
+    return span;
+}
+export function buildTraceTree(run, now = Date.now()) {
+    const status = run.status === "completed" ? "ok" : run.status === "failed" ? "error" : run.status === "awaiting-approval" ? "waiting" : run.status === "queued" ? "pending" : "running";
+    return {
+        id: "run",
+        kind: "run",
+        label: run.flow,
+        start: ms(run.startedAt),
+        end: ms(run.finishedAt) ?? (status === "running" || status === "waiting" ? now : null),
+        status,
+        children: run.steps.map((s, i) => stepSpan(s, i, now)),
+    };
+}
+/** The ids from the root to the first thing that went wrong — what the
+ *  view opens on; [] when nothing did. A failed tool beats the step's error
+ *  line, which beats the failed step itself. */
+export function failurePath(root) {
+    let best = null;
+    const rank = (s) => (s.kind === "tool" ? 3 : s.kind === "error" ? 2 : s.kind === "step" ? 1 : 0);
+    const walk = (s, path) => {
+        const here = [...path, s.id];
+        if (s.status === "error" && s.kind !== "run" && (!best || rank(s) > best.rank))
+            best = { path: here, rank: rank(s) };
+        for (const c of s.children)
+            walk(c, here);
+    };
+    walk(root, []);
+    return best ? best.path : [];
+}

package/dist/src/translator.d.ts

@@ -28,6 +28,11 @@ export interface TranslatorSpec {
     /** The provider block's `params:` — merged into the outgoing body after
      *  the translation, so a file can set what this format does not model. */
     params?: Record<string, unknown>;
+    /** `prompt_cache_key` for an endpoint that routes its prompt cache by
+     *  one (OpenAI, Mistral): the same key for every request that shares a
+     *  prefix — one per agent (prompt-layers.ts). Unset where the preset
+     *  does not say the parameter is understood. */
+    cacheKey?: string;
     /** How the endpoint is named in the trace. */
     label?: string;
     /** The step's egress lease, when the sandbox must not hold the key: the
@@ -77,6 +82,7 @@ export declare function toChatCompletions(req: Json, opts: {
     maxTokensParam?: "max_tokens" | "max_completion_tokens";
     reasoningEffort?: boolean;
     stream: boolean;
+    cacheKey?: string;
     /** Merged in last, so the file wins over the translation. */
     params?: Record<string, unknown>;
 }, drop?: Dropped): Json;
@@ -93,6 +99,7 @@ export declare function toChatCompletions(req: Json, opts: {
 export declare function toResponses(req: Json, opts: {
     reasoningEffort?: boolean;
     stream: boolean;
+    cacheKey?: string;
     params?: Record<string, unknown>;
 }, drop?: Dropped): Json;
 /** A finished Chat Completion as an Anthropic message. Pure. */
@@ -173,5 +180,6 @@ export declare function translatorSpecFor(spec: {
     name?: string | null;
     maxTokensParam?: "max_tokens" | "max_completion_tokens";
     reasoningEffort?: boolean;
+    cacheKey?: string;
 }): TranslatorSpec | null;
 export {};

package/dist/src/translator.js

@@ -123,6 +123,8 @@ function imagePart(block) {
  */
 export function toChatCompletions(req, opts, drop = dropped()) {
     const out = { model: req.model, stream: opts.stream };
+    if (opts.cacheKey)
+        out.prompt_cache_key = opts.cacheKey;
     const messages = [];
     const system = textOf(req.system);
     if (system)
@@ -285,6 +287,8 @@ export function toChatCompletions(req, opts, drop = dropped()) {
  */
 export function toResponses(req, opts, drop = dropped()) {
     const out = { model: req.model, stream: opts.stream, store: false };
+    if (opts.cacheKey)
+        out.prompt_cache_key = opts.cacheKey;
     const system = textOf(req.system);
     if (system)
         out.instructions = system;
@@ -904,8 +908,8 @@ export async function startTranslator(spec) {
             const drop = dropped();
             const responses = spec.wire === "responses";
             const outbound = responses
-                ? toResponses(body, { reasoningEffort: spec.reasoningEffort, params: spec.params, stream }, drop)
-                : toChatCompletions(body, { maxTokensParam: spec.maxTokensParam, reasoningEffort: spec.reasoningEffort, params: spec.params, stream }, drop);
+                ? toResponses(body, { reasoningEffort: spec.reasoningEffort, params: spec.params, cacheKey: spec.cacheKey, stream }, drop)
+                : toChatCompletions(body, { maxTokensParam: spec.maxTokensParam, reasoningEffort: spec.reasoningEffort, params: spec.params, cacheKey: spec.cacheKey, stream }, drop);
             for (const line of drop.lines())
                 if (!log.includes(line))
                     log.push(line);
@@ -1051,6 +1055,7 @@ export function translatorSpecFor(spec) {
         params: spec.params,
         maxTokensParam: spec.maxTokensParam,
         reasoningEffort: spec.reasoningEffort,
+        ...(spec.cacheKey ? { cacheKey: spec.cacheKey } : {}),
         label: spec.name ? `${spec.name} (${spec.baseUrl})` : spec.baseUrl,
     };
 }

package/dist/src/trigger-log.d.ts

@@ -1,7 +1,7 @@
 /** What became of one trigger firing. `started` is here too: without it the
  *  log answers "why did nothing run" and not "how often does anything",
  *  and the ratio is the whole point of the page. */
-export type TriggerOutcome = "started" | "duplicate" | "throttled" | "debounced" | "quarantined" | "paused" | "overlap-skipped" | "missed" | "failed";
+export type TriggerOutcome = "started" | "duplicate" | "throttled" | "debounced" | "quarantined" | "paused" | "halted" | "overlap-skipped" | "missed" | "failed";
 export interface TriggerEvent {
     t: string;
     flow: string;

package/dist/src/workspace-check.d.ts

@@ -0,0 +1,18 @@
+import type { DeployFile } from "./store.ts";
+import type { ScanFinding, ScanOptions } from "./scan.ts";
+/** What the checks read of a workspace, at most. Data (state/ and memory/,
+ *  what agents write) past these is left out and named; the rest past its
+ *  budget is not read at all (TreeTooLarge). On 20 Oct 2026 the daily
+ *  rescan read 1.2 GB of one desk's state/ into a 2 GB heap and crash-looped
+ *  the worker. The rest is 64 MiB because a deploy is 10 MiB a push. */
+export declare const CHECK_LIMITS: {
+    readonly maxDataFileBytes: number;
+    readonly maxDataBytes: number;
+    readonly maxDataFiles: 5000;
+    readonly maxSourceBytes: number;
+};
+/** A workspace as the checks read it: the deploy's tree within CHECK_LIMITS.
+ *  Read once and hand it to everything that checks. */
+export declare function checkTree(dir: string, onSkip?: (path: string, bytes: number) => void): DeployFile[];
+export declare function checkOptions(tenant: string, workspace: string): ScanOptions;
+export declare function checkWorkspace(tenant: string, workspace: string, tree?: DeployFile[]): ScanFinding[];

package/dist/src/workspace-check.js

@@ -0,0 +1,34 @@
+// One workspace's findings, as the Checks page, `GET …/check` and the daily
+// rescan see them (FOL-58): the deploy's checks and the whole scanner, with
+// what the files alone do not carry — the account's network: and the
+// outward tools of the library and the workspace, nearest wins.
+import { accountDir, workspaceDir, workspaceTools } from "./store.js";
+import { readAgentsMdKeys } from "./agents-md.js";
+import { libraryTools } from "./library.js";
+import { checkFiles, readTree } from "./deploy.js";
+/** What the checks read of a workspace, at most. Data (state/ and memory/,
+ *  what agents write) past these is left out and named; the rest past its
+ *  budget is not read at all (TreeTooLarge). On 20 Oct 2026 the daily
+ *  rescan read 1.2 GB of one desk's state/ into a 2 GB heap and crash-looped
+ *  the worker. The rest is 64 MiB because a deploy is 10 MiB a push. */
+export const CHECK_LIMITS = {
+    maxDataFileBytes: 5 * 1024 * 1024,
+    maxDataBytes: 32 * 1024 * 1024,
+    maxDataFiles: 5000,
+    maxSourceBytes: 64 * 1024 * 1024,
+};
+/** A workspace as the checks read it: the deploy's tree within CHECK_LIMITS.
+ *  Read once and hand it to everything that checks. */
+export function checkTree(dir, onSkip) {
+    return readTree(dir, { ...CHECK_LIMITS, onSkip });
+}
+export function checkOptions(tenant, workspace) {
+    const tools = { ...libraryTools(tenant), ...workspaceTools(tenant, workspace) };
+    const outwardTools = Object.entries(tools).filter(([, d]) => d.outward === true).map(([n]) => n);
+    // AGENTS.md, or the older project.md, as the runner reads it (Codex review).
+    const accountNetwork = readAgentsMdKeys(accountDir(tenant)).network;
+    return { outwardTools, accountNetwork };
+}
+export function checkWorkspace(tenant, workspace, tree = checkTree(workspaceDir(tenant, workspace))) {
+    return checkFiles(tree, checkOptions(tenant, workspace));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -53,7 +53,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.285",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.296",
     "gray-matter": "^4.0.3",
     "zod": "4.4.3"
   },

package/src/agent-activity.ts

@@ -0,0 +1,32 @@
+// When each agent last did anything — the question an account with hundreds
+// of agents has to be able to answer before it can retire the ones nobody
+// uses. Read from the run index (listRunSummaries), so it covers what the
+// install keeps: runs older than its retention are gone, and an agent whose
+// last run was pruned reads as never run.
+
+import type { RunSummary } from "./store.ts";
+
+/** A step that started counts; one that was skipped or never reached does not. */
+const RAN = new Set(["running", "completed", "failed", "awaiting-approval"]);
+
+/** Agent name → the ISO time of its latest step that ran. */
+export function agentLastRuns(runs: RunSummary[]): Map<string, string> {
+  const last = new Map<string, string>();
+  for (const run of runs) {
+    for (const step of run.steps ?? []) {
+      if (!step.agent || !RAN.has(step.status)) continue;
+      const at = step.startedAt ?? run.startedAt;
+      if (!at) continue;
+      const prev = last.get(step.agent);
+      if (!prev || at > prev) last.set(step.agent, at);
+    }
+  }
+  return last;
+}
+
+/** Whole days since `iso`, or null for never. */
+export function daysSince(iso: string | null | undefined, now = Date.now()): number | null {
+  if (!iso) return null;
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? Math.floor((now - t) / 86_400_000) : null;
+}

package/src/agent-import.ts

@@ -15,7 +15,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.ts";
 import {
   assertSafeName,
   listWorkspaceFiles,

package/src/agent-tools.ts

@@ -17,7 +17,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.ts";
 import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { resolveModel, resolveEffort, type Effort } from "./store.ts";

package/src/agents-md.ts

@@ -9,7 +9,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.ts";
 
 const FRONT = /^(---\r?\n)([\s\S]*?)(\r?\n---)(\r?\n|$)/;
 

package/src/alerts.ts

@@ -0,0 +1,190 @@
+// `alerts:` — the thresholds a workspace wants to hear about (FOL-72 step 7):
+//
+//   alerts:
+//     failure_rate: 30%     # of its runs that finished in the last 24 hours
+//     min_runs: 5           # …once at least this many have (default 5)
+//     credits_day: 2000     # credits charged in the last 24 hours
+//     run_minutes: 45       # a run still going after this long
+//     stale_days: 30        # an agent that has not run in this many days
+//     cost_spike: 3         # a run that cost this many times its flow's 7-day average
+//     runs_per_hour: 20     # one flow started this many times in an hour
+//     new_host: true        # an agent reached a site it never reached before
+//
+// In AGENTS.md (the workspace's, else the account's). The watchdog evaluates
+// them on its tick and tells `notify:` once per rule a day (a slow run once
+// per run), as event `alert`. Pure: `foldrun check` and the watchdog read the
+// same parse.
+
+import type { Outcome } from "./outcome.ts";
+
+export interface AlertConfig {
+  failureRate?: number;
+  minRuns: number;
+  creditsDay?: number;
+  runMinutes?: number;
+  staleDays?: number;
+  costSpike?: number;
+  runsPerHour?: number;
+  /** Told after a run (platform host-watch.ts), not on the watchdog's tick. */
+  newHost?: boolean;
+}
+
+const KEYS = ["failure_rate", "min_runs", "credits_day", "run_minutes", "stale_days", "cost_spike", "runs_per_hour", "new_host"];
+
+const num = (v: unknown): number | null => {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.trim() && Number.isFinite(Number(v.trim()))) return Number(v.trim());
+  return null;
+};
+
+/** The config, and what is wrong with it in words (for `foldrun check`). */
+export function parseAlerts(raw: unknown): { config: AlertConfig | null; problems: string[] } {
+  if (raw === undefined || raw === null) return { config: null, problems: [] };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { config: null, problems: ["alerts: is a block — failure_rate, min_runs, credits_day, run_minutes, stale_days, cost_spike, runs_per_hour, new_host"] };
+  }
+  const o = raw as Record<string, unknown>;
+  const problems: string[] = [];
+  for (const k of Object.keys(o)) if (!KEYS.includes(k)) problems.push(`alerts: ${k} — not a threshold; the keys are ${KEYS.join(", ")}`);
+  const cfg: AlertConfig = { minRuns: 5 };
+  if (o.failure_rate !== undefined) {
+    const s = String(o.failure_rate).trim();
+    const pct = /^(\d+(?:\.\d+)?)\s*%$/.exec(s);
+    const v = pct ? Number(pct[1]) / 100 : num(o.failure_rate);
+    if (v === null || v <= 0 || v > 1) problems.push(`alerts: failure_rate ${s} — a share of runs, like 30% or 0.3`);
+    else cfg.failureRate = v;
+  }
+  for (const [key, field, min] of [["min_runs", "minRuns", 1], ["credits_day", "creditsDay", 1], ["run_minutes", "runMinutes", 1], ["stale_days", "staleDays", 1], ["cost_spike", "costSpike", 1.5], ["runs_per_hour", "runsPerHour", 2]] as const) {
+    if (o[key] === undefined) continue;
+    const v = num(o[key]);
+    if (v === null || v < min) problems.push(`alerts: ${key} ${String(o[key])} — a number, at least ${min}`);
+    else (cfg as unknown as Record<string, number>)[field] = v;
+  }
+  if (o.new_host !== undefined) {
+    if (typeof o.new_host !== "boolean") problems.push(`alerts: new_host ${String(o.new_host)} — true or false`);
+    else if (o.new_host) cfg.newHost = true;
+  }
+  const any = cfg.newHost === true || cfg.failureRate !== undefined || cfg.creditsDay !== undefined || cfg.runMinutes !== undefined || cfg.staleDays !== undefined || cfg.costSpike !== undefined || cfg.runsPerHour !== undefined;
+  return { config: any ? cfg : null, problems };
+}
+
+export interface AlertFacts {
+  /** Outcomes of the runs started in the last 24 hours. */
+  outcomes: Outcome[];
+  /** Credits are cents: USD charged in the last 24 hours. */
+  chargedUsd: number;
+  /** Runs still going. */
+  live: { id: string; flow: string; startedAt: string }[];
+  /** For stale_days: each agent, when it last ran (null: not in the runs
+   *  kept), and since when it has existed — an agent added yesterday is not
+   *  stale for never having run. */
+  agents?: { name: string; lastRunAt: string | null; since: string }[];
+  /** For cost_spike and runs_per_hour: the runs of the last seven days,
+   *  test runs left out. costUsd is what its steps cost. */
+  runs?: { id: string; flow: string; startedAt: string; finishedAt: string | null; costUsd: number }[];
+}
+
+/** How few earlier runs a flow needs before its average means anything. */
+const SPIKE_MIN_RUNS = 3;
+
+export interface Alert {
+  /** What the once-a-day memory is keyed by: the rule, or the rule and run. */
+  key: string;
+  headline: string;
+  detail: string;
+  runId?: string;
+  flow?: string;
+  /** Said once for this key, however long it stays true (a slow run, an
+   *  idle spell); the watchdog's notice memory is pruned after a week, so
+   *  a condition that lasts is said again weekly at most. */
+  once?: boolean;
+}
+
+/** What crosses its threshold now. */
+export function evaluateAlerts(cfg: AlertConfig, facts: AlertFacts, workspace: string, now: number): Alert[] {
+  const out: Alert[] = [];
+  if (cfg.failureRate !== undefined) {
+    const finished = facts.outcomes.filter((o) => o === "failed" || o === "good" || o === "done" || o === "quiet" || o === "blocked" || o === "bad");
+    const failed = finished.filter((o) => o === "failed").length;
+    if (finished.length >= cfg.minRuns && failed / finished.length >= cfg.failureRate) {
+      out.push({
+        key: "failure_rate",
+        headline: `⚠ ${workspace}: ${failed} of its last ${finished.length} runs failed`,
+        detail: `${Math.round((100 * failed) / finished.length)}% in the last 24 hours, over the ${Math.round(cfg.failureRate * 100)}% in alerts: failure_rate. Its Issues show what broke.`,
+      });
+    }
+  }
+  if (cfg.creditsDay !== undefined) {
+    const credits = Math.round(facts.chargedUsd * 100);
+    if (credits >= cfg.creditsDay) {
+      out.push({
+        key: "credits_day",
+        headline: `⚠ ${workspace} was charged ${credits.toLocaleString("en")} credits in a day`,
+        detail: `Over the ${cfg.creditsDay.toLocaleString("en")} in alerts: credits_day, in the last 24 hours. Observe shows which flows and agents.`,
+      });
+    }
+  }
+  if (cfg.runMinutes !== undefined) {
+    for (const r of facts.live) {
+      const mins = (now - Date.parse(r.startedAt)) / 60_000;
+      if (mins >= cfg.runMinutes) {
+        out.push({
+          key: `run_minutes/${r.id}`,
+          runId: r.id,
+          flow: r.flow,
+          headline: `⚠ ${workspace}: ${r.flow} has been running ${Math.round(mins)} minutes`,
+          detail: `Run ${r.id} is past the ${cfg.runMinutes} minutes in alerts: run_minutes — still going, maybe stuck. Stop it from its page if it is.`,
+        });
+      }
+    }
+  }
+  if (cfg.costSpike !== undefined && facts.runs) {
+    // A run that finished in the last day, against the runs of its flow that
+    // finished before it in the week: once per run.
+    const done = facts.runs.filter((r) => r.finishedAt).sort((a, b) => a.finishedAt!.localeCompare(b.finishedAt!));
+    for (const r of done) {
+      if (now - Date.parse(r.finishedAt!) > 86_400_000) continue;
+      const before = done.filter((o) => o.flow === r.flow && o.id !== r.id && o.finishedAt! < r.finishedAt!);
+      if (before.length < SPIKE_MIN_RUNS) continue;
+      const mean = before.reduce((n, o) => n + o.costUsd, 0) / before.length;
+      if (mean <= 0 || r.costUsd < cfg.costSpike * mean) continue;
+      out.push({
+        key: `cost_spike/${r.id}`,
+        runId: r.id,
+        flow: r.flow,
+        headline: `${workspace}: a ${r.flow} run cost ${(r.costUsd / mean).toFixed(1)}× its usual`,
+        detail: `Run ${r.id} cost $${r.costUsd.toFixed(2)} against an average of $${mean.toFixed(2)} over its last ${before.length} runs this week — past the ${cfg.costSpike}× in alerts: cost_spike. Its page shows which step spent it.`,
+      });
+    }
+  }
+  if (cfg.runsPerHour !== undefined && facts.runs) {
+    const hour = facts.runs.filter((r) => now - Date.parse(r.startedAt) <= 3_600_000);
+    const byFlow = new Map<string, number>();
+    for (const r of hour) byFlow.set(r.flow, (byFlow.get(r.flow) ?? 0) + 1);
+    for (const [flow, n] of byFlow) {
+      if (n < cfg.runsPerHour) continue;
+      out.push({
+        key: `runs_per_hour/${flow}`,
+        flow,
+        headline: `${workspace}: ${flow} started ${n} times in an hour`,
+        detail: `Past the ${cfg.runsPerHour} in alerts: runs_per_hour — a loop, a webhook sender retrying, or a schedule written wrong. Its Triggers page shows what started each; throttle: or debounce: caps it, and Settings → Pause stops it now.`,
+      });
+    }
+  }
+  if (cfg.staleDays !== undefined) {
+    for (const a of facts.agents ?? []) {
+      const from = Date.parse(a.lastRunAt ?? a.since);
+      if (!Number.isFinite(from)) continue;
+      const days = Math.floor((now - from) / 86_400_000);
+      if (days < cfg.staleDays) continue;
+      out.push({
+        // Keyed by the run it last made, so a run and a new idle spell are news again.
+        key: `stale_days/${a.name}/${a.lastRunAt ?? "never"}`,
+        once: true,
+        headline: `${workspace}: agent ${a.name} has not run in ${days} days`,
+        detail: `${a.lastRunAt ? `Its last step started ${a.lastRunAt.slice(0, 10)}` : "No run kept on record has used it"} — past the ${cfg.staleDays} days in alerts: stale_days. If nothing needs it any more, retire it: delete agents/${a.name}/ and redeploy, so it holds no tools or secrets nobody watches.`,
+      });
+    }
+  }
+  return out;
+}

package/src/browser-pod.ts

@@ -159,6 +159,9 @@ export function classifyCall(tool: string, input: Record<string, unknown> | unde
   const [, server, name] = mcp;
   if (READ_SERVERS.has(server)) return { write: false };
   if (server === "foldrun_ask") return write("a question to a person");
+  // tools: [peers] — reading the roster changes nothing; a message to a
+  // colleague is said, and a re-run would say it twice.
+  if (server === "foldrun_peers") return name === "peers_list" ? { write: false } : write("a message to a colleague");
   if (server === "foldrun_scripts") {
     if (name !== "web") return write(`script ${name}`);
     const action = String(args.action ?? "").trim().toLowerCase();

package/src/capture.ts

@@ -0,0 +1,88 @@
+// A tool call's content, from a step's event to the file beside its run
+// (FOL-54 step 4), masked twice: the step's own secrets by value (the
+// runner's redact, from redactionsFor), then anything shaped like a
+// credential or a private key — a key the agent read from a file or a page
+// is not in the vault, and is still a key. Masked first, cut second, so a
+// secret on the cap's edge is never kept half. Recording never fails the step.
+
+import { redactText } from "./scan.ts";
+import { writeCapturedCall, CAPTURE_CAP } from "./store.ts";
+import { isFileValue, fileContent } from "./secrets.ts";
+import type { CallIo } from "./step-exec.ts";
+
+/** How much past the cap a step sends, so masking sees a secret whole
+ *  before the cut (a value longer than this is a file secret, which is also
+ *  masked line by line). */
+export const CAPTURE_SLACK = 4096;
+
+/**
+ * What the step's scrub replaces: every secret value it holds → its name,
+ * longest first. An `@file` secret (a key, a certificate) by its content, not
+ * its stored form; a multi-line value also line by line, because a file is
+ * read back a line at a time (the Read tool numbers each); and every value
+ * also as it appears inside JSON, where `"` `\` and newlines are escaped — a
+ * tool's input is JSON. Values under 8 characters are skipped: a two-letter
+ * secret would redact half the language, and anything that short is not one.
+ */
+export function redactionsFor(secrets: Record<string, string | undefined>): [string, string][] {
+  const out = new Map<string, string>();
+  const add = (v: string, name: string) => {
+    if (v.length >= 8 && !out.has(v)) out.set(v, name);
+  };
+  for (const [name, raw] of Object.entries(secrets)) {
+    if (typeof raw !== "string") continue;
+    for (const v of isFileValue(raw) ? [raw, fileContent(raw)] : [raw]) {
+      add(v, name);
+      add(v.trim(), name);
+      const escaped = JSON.stringify(v).slice(1, -1);
+      if (escaped !== v) add(escaped, name);
+      if (/\r?\n/.test(v.trim())) {
+        for (const line of v.split(/\r?\n/)) {
+          const l = line.trim();
+          if (l.length >= 16) add(l, name);
+        }
+      }
+    }
+  }
+  return [...out.entries()].sort((a, b) => b[0].length - a[0].length);
+}
+
+// A private key's whole block — scan.ts names a key header and leaves the
+// body, which is right for a finding and wrong for a stored output.
+// Unterminated too: a key cut short, or printed without its END line, is
+// masked to the end of the text.
+const PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|$(?![\s\S]))/g;
+
+/** Masked, then cut to the cap. */
+export function maskCall(text: string, redactSecrets: (text: string) => string): { text: string; cut: boolean } {
+  const masked = redactText(redactSecrets(text)).replace(PRIVATE_KEY, "[redacted:private key]");
+  return masked.length > CAPTURE_CAP ? { text: masked.slice(0, CAPTURE_CAP), cut: true } : { text: masked, cut: false };
+}
+
+export function recordCallIo(
+  workspaceRoot: string,
+  runId: string,
+  callId: string,
+  tool: string,
+  io: CallIo,
+  /** The step's own scrub: its resolved secret values → `[redacted:NAME]`. */
+  redactSecrets: (text: string) => string,
+): boolean {
+  try {
+    const input = io.input === undefined ? null : maskCall(io.input, redactSecrets);
+    const output = io.output === undefined ? null : maskCall(io.output, redactSecrets);
+    writeCapturedCall(workspaceRoot, runId, {
+      id: callId,
+      tool,
+      // Which part was cut, each on its own: in the sandbox (the whole was
+      // longer than what was sent) or here, after masking.
+      ...(input ? { input: input.text, ...(io.inputChars !== undefined ? { inputChars: io.inputChars } : {}), ...(input.cut || (io.inputChars ?? 0) > io.input!.length ? { inputCut: true } : {}) } : {}),
+      ...(output ? { output: output.text, ...(io.outputChars !== undefined ? { outputChars: io.outputChars } : {}), ...(output.cut || (io.outputChars ?? 0) > io.output!.length ? { outputCut: true } : {}) } : {}),
+      ...(io.truncated || input?.cut || output?.cut ? { truncated: true } : {}),
+    });
+    return true;
+  } catch (err) {
+    console.error(`[capture] ${tool} (${callId}) for ${runId}:`, err instanceof Error ? err.message : err);
+    return false;
+  }
+}