@foldrun/core 2.4.0 → 2.6.0

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.6.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 { configMatter } from "./matter.ts";
 import {
   assertSafeName,
   listWorkspaceFiles,
@@ -99,7 +99,7 @@ export function importAgent(
     let content = readWorkspaceFile(tenant, from, src);
     const rel = src.slice(`agents/${agent}/`.length);
     if (rel === "agent.md") {
-      front = matter(content).data as Record<string, unknown>;
+      front = configMatter(content).data as Record<string, unknown>;
       // The folder is the name flows address; a `name:` that disagrees with
       // it is the first thing check would complain about.
       if (name !== agent) content = content.replace(/^(---\r?\n(?:[\s\S]*?\r?\n)?)name:[^\n]*$/m, `$1name: ${name}`);

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 { configMatter } from "./matter.ts";
 import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { resolveModel, resolveEffort, type Effort } from "./store.ts";
@@ -51,7 +51,7 @@ export function gatherConsults(
       missing.push(name);
       continue;
     }
-    const parsed = matter(fs.readFileSync(file, "utf8"));
+    const parsed = configMatter(fs.readFileSync(file, "utf8"));
     consults.push({
       name,
       systemPrompt:

package/src/agents-md.ts

@@ -9,7 +9,12 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter, { configMatter } from "./matter.ts";
+import { keySpan, dropEmptyBlock } from "./frontmatter-text.ts";
+import { guardEdit } from "./frontmatter-guard.ts";
+import { JOBS, FOLDABLE } from "./frontmatter-fields.ts";
+
+export { keySpan };
 
 const FRONT = /^(---\r?\n)([\s\S]*?)(\r?\n---)(\r?\n|$)/;
 
@@ -19,7 +24,7 @@ export function readAgentsMdKeys(dir: string): Record<string, unknown> {
     const file = path.join(dir, name);
     if (!fs.existsSync(file)) continue;
     try {
-      return (matter(fs.readFileSync(file, "utf8")).data ?? {}) as Record<string, unknown>;
+      return (configMatter(fs.readFileSync(file, "utf8")).data ?? {}) as Record<string, unknown>;
     } catch {
       return {};
     }
@@ -37,8 +42,31 @@ function dumpKey(key: string, value: unknown): string[] {
 
 /** The text of `content` with each key in `patch` replaced (or removed for
  *  null), everything else byte for byte as it was. A file with no
- *  frontmatter gets one. */
+ *  frontmatter gets one. Read back before it is returned (frontmatter-guard
+ *  .ts): an edit that would not parse, would change another key or would
+ *  double one into its block throws UnsafeEditError (409). */
 export function patchFrontmatter(content: string, patch: Record<string, unknown | null>): string {
+  // The guard reads the result folded (matter.ts configMatter), so a patch
+  // that writes a whole job block is checked as the keys it holds: each
+  // field the block may hold may change, and each one it sets reads back.
+  const changed = new Set<string>();
+  const expect: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(patch)) {
+    changed.add(key);
+    const job = JOBS.find((j) => j.name === key)?.name;
+    if (!job) {
+      expect[key] = value;
+      continue;
+    }
+    for (const k of FOLDABLE[job]) changed.add(k);
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      for (const [k, v] of Object.entries(value)) if (FOLDABLE[job].has(k)) expect[k] = v;
+    }
+  }
+  return guardEdit(content, patchFrontmatterText(content, patch), [...changed], expect);
+}
+
+function patchFrontmatterText(content: string, patch: Record<string, unknown | null>): string {
   const m = content.match(FRONT);
   let open = "---\n";
   let body = "";
@@ -52,18 +80,15 @@ export function patchFrontmatter(content: string, patch: Record<string, unknown
   }
   let lines = body === "" ? [] : body.split("\n");
   for (const [key, value] of Object.entries(patch)) {
-    const at = lines.findIndex((l) => new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:`).test(l));
-    let end = at;
-    if (at !== -1) {
-      end = at + 1;
-      // The block continues while lines are indented or blank-inside-block.
-      while (end < lines.length && (/^[ \t]/.test(lines[end]) || lines[end].trim() === "")) end++;
-      // A blank line at the block's foot belongs to what follows.
-      while (end > at + 1 && lines[end - 1].trim() === "") end--;
+    // Where it is written now — at the top or inside its job block — is
+    // where it is edited; a key written nowhere is added at the top.
+    const where = keySpan(lines, key);
+    const replacement = value === null || value === undefined ? [] : dumpKey(key, value).map((l) => `${where?.indent ?? ""}${l}`);
+    if (!where) lines = [...lines, ...replacement];
+    else {
+      lines = [...lines.slice(0, where.at), ...replacement, ...lines.slice(where.end)];
+      if (!replacement.length && where.block !== null) lines = dropEmptyBlock(lines, where.block);
     }
-    const replacement = value === null || value === undefined ? [] : dumpKey(key, value);
-    if (at === -1) lines = [...lines, ...replacement];
-    else lines = [...lines.slice(0, at), ...replacement, ...lines.slice(end)];
   }
   const front = lines.length ? `${open}${lines.join("\n")}${close}` : "";
   if (!front) return rest.replace(/^(\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;
+  }
+}