@foldrun/core 2.3.0 → 2.5.0

package/dist/src/agent-activity.d.ts

@@ -0,0 +1,5 @@
+import type { RunSummary } from "./store.ts";
+/** Agent name → the ISO time of its latest step that ran. */
+export declare function agentLastRuns(runs: RunSummary[]): Map<string, string>;
+/** Whole days since `iso`, or null for never. */
+export declare function daysSince(iso: string | null | undefined, now?: number): number | null;

package/dist/src/agent-activity.js

@@ -0,0 +1,31 @@
+// 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.
+/** 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) {
+    const last = new Map();
+    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, now = Date.now()) {
+    if (!iso)
+        return null;
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? Math.floor((now - t) / 86_400_000) : null;
+}

package/dist/src/agent-import.js

@@ -14,7 +14,7 @@
 // were about somebody else's desk.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.js";
 import { assertSafeName, listWorkspaceFiles, readWorkspaceFile, writeWorkspaceFile, workspaceDir, workspaceTools, listWorkspaces, } from "./store.js";
 import { libraryDir, libraryTools } from "./library.js";
 import { isRuntimeTool, toolEntryName } from "./tool-names.js";

package/dist/src/agent-tools.js

@@ -16,7 +16,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.js";
 import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { resolveModel, resolveEffort } from "./store.js";

package/dist/src/agents-md.js

@@ -8,7 +8,7 @@
 // else in the file is untouched. Null removes the key.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.js";
 const FRONT = /^(---\r?\n)([\s\S]*?)(\r?\n---)(\r?\n|$)/;
 /** The frontmatter of a directory's AGENTS.md (or project.md), or {}. */
 export function readAgentsMdKeys(dir) {

package/dist/src/alerts.d.ts

@@ -0,0 +1,60 @@
+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;
+}
+/** The config, and what is wrong with it in words (for `foldrun check`). */
+export declare function parseAlerts(raw: unknown): {
+    config: AlertConfig | null;
+    problems: string[];
+};
+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;
+    }[];
+}
+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 declare function evaluateAlerts(cfg: AlertConfig, facts: AlertFacts, workspace: string, now: number): Alert[];

package/dist/src/alerts.js

@@ -0,0 +1,161 @@
+// `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.
+const KEYS = ["failure_rate", "min_runs", "credits_day", "run_minutes", "stale_days", "cost_spike", "runs_per_hour", "new_host"];
+const num = (v) => {
+    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) {
+    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;
+    const problems = [];
+    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 = { 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]]) {
+        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[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 };
+}
+/** How few earlier runs a flow needs before its average means anything. */
+const SPIKE_MIN_RUNS = 3;
+/** What crosses its threshold now. */
+export function evaluateAlerts(cfg, facts, workspace, now) {
+    const out = [];
+    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();
+        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/dist/src/browser-pod.js

@@ -169,6 +169,10 @@ export function classifyCall(tool, input, ctx = {}) {
         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}`);

package/dist/src/capture.d.ts

@@ -0,0 +1,23 @@
+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 declare 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 declare function redactionsFor(secrets: Record<string, string | undefined>): [string, string][];
+/** Masked, then cut to the cap. */
+export declare function maskCall(text: string, redactSecrets: (text: string) => string): {
+    text: string;
+    cut: boolean;
+};
+export declare 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;

package/dist/src/capture.js

@@ -0,0 +1,80 @@
+// 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.js";
+import { writeCapturedCall, CAPTURE_CAP } from "./store.js";
+import { isFileValue, fileContent } from "./secrets.js";
+/** 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) {
+    const out = new Map();
+    const add = (v, name) => {
+        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, redactSecrets) {
+    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, runId, callId, tool, io, 
+/** The step's own scrub: its resolved secret values → `[redacted:NAME]`. */
+redactSecrets) {
+    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;
+    }
+}

package/dist/src/compare.d.ts

@@ -0,0 +1,57 @@
+import type { RunRecord } from "./store.ts";
+export interface StepSide {
+    status: string;
+    instruction: string;
+    model?: string;
+    secs: number | null;
+    tokensIn: number;
+    tokensOut: number;
+    modelCalls: number;
+    /** Tool name → how many calls. */
+    tools: Record<string, number>;
+    toolErrors: number;
+    /** The first errors it wrote, each one line. */
+    errors: string[];
+    /** The first line of what it concluded. */
+    said: string | null;
+}
+export interface StepDiff {
+    /** 1-based, as the trace numbers steps. */
+    step: number;
+    agent: string;
+    base: StepSide | null;
+    run: StepSide | null;
+    /** What differs, in words, most telling first; [] when nothing does. */
+    changes: string[];
+}
+export interface RunComparison {
+    base: {
+        id: string;
+        status: string;
+        startedAt: string;
+        revision: string | null;
+    };
+    run: {
+        id: string;
+        status: string;
+        startedAt: string;
+        revision: string | null;
+    };
+    revisionChanged: boolean;
+    /** Files changed between the two revisions; null when that cannot be said. */
+    changedFiles: string[] | null;
+    steps: StepDiff[];
+}
+export declare function compareRuns(base: RunRecord, run: RunRecord, changedFiles?: string[] | null): RunComparison;
+/** The run to compare a run with when none is named: the newest earlier run
+ *  of the same flow that finished well (completed, not BLOCKED or BAD), or
+ *  null. `outcomeOf` is the caller's, so this stays free of the verdict reader. */
+export declare function lastGoodBefore<R extends {
+    id: string;
+    flow: string;
+    startedAt: string;
+}>(runs: R[], run: {
+    id: string;
+    flow: string;
+    startedAt: string;
+}, good: (r: R) => boolean): R | null;

package/dist/src/compare.js

@@ -0,0 +1,116 @@
+// Two runs of one flow side by side (FOL-72 step 6): "why did this get
+// worse" read off the records — which files changed between the revisions
+// they ran, and step by step what differs: status, the instruction, the
+// model, time, tokens, model calls, the tools it used and the errors it hit.
+// Pure; the caller hands in the changed files (history.ts changedPathsBetween).
+const firstLine = (s, n = 200) => {
+    const l = (s ?? "").split("\n").map((x) => x.trim()).find(Boolean);
+    return l ? l.slice(0, n) : null;
+};
+function side(s) {
+    const tools = {};
+    let toolErrors = 0;
+    for (const e of s.events) {
+        if (e.type !== "tool")
+            continue;
+        // A pair is one call: count the call, and its completion's error.
+        if (e.ms == null)
+            tools[e.text] = (tools[e.text] ?? 0) + 1;
+        else if (e.err)
+            toolErrors++;
+    }
+    const start = s.startedAt ? Date.parse(s.startedAt) : NaN;
+    const end = s.finishedAt ? Date.parse(s.finishedAt) : NaN;
+    return {
+        status: s.status,
+        instruction: s.instruction,
+        ...(s.model ? { model: s.model } : {}),
+        secs: Number.isFinite(start) && Number.isFinite(end) ? Math.max(0, Math.round((end - start) / 1000)) : null,
+        tokensIn: s.tokens?.input ?? 0,
+        tokensOut: s.tokens?.output ?? 0,
+        modelCalls: s.calls?.length ?? s.turns ?? 0,
+        tools,
+        toolErrors,
+        errors: s.events.filter((e) => e.type === "error").slice(0, 3).map((e) => firstLine(e.text) ?? ""),
+        said: firstLine(s.conclusion ?? s.result),
+    };
+}
+const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
+/** Much more or much less: by a quarter and by a real amount. */
+const moved = (a, b, floor) => Math.abs(b - a) >= floor && (a === 0 ? b > 0 : Math.abs(b - a) / a >= 0.25);
+function changes(a, b) {
+    if (!a && b)
+        return ["new step: not in the base run"];
+    if (a && !b)
+        return ["not in this run"];
+    if (!a || !b)
+        return [];
+    const out = [];
+    if (a.status !== b.status)
+        out.push(`status: ${a.status} → ${b.status}`);
+    const newErrors = b.errors.filter((e) => !a.errors.includes(e));
+    if (newErrors.length)
+        out.push(`new error: ${newErrors[0]}`);
+    if (a.instruction.trim() !== b.instruction.trim())
+        out.push("instruction changed");
+    if ((a.model ?? "") !== (b.model ?? ""))
+        out.push(`model: ${a.model ?? "default"} → ${b.model ?? "default"}`);
+    if (b.toolErrors > a.toolErrors)
+        out.push(`tool errors: ${a.toolErrors} → ${b.toolErrors}`);
+    const names = new Set([...Object.keys(a.tools), ...Object.keys(b.tools)]);
+    const toolDiff = [...names]
+        .map((n) => ({ n, d: (b.tools[n] ?? 0) - (a.tools[n] ?? 0) }))
+        .filter((x) => x.d !== 0)
+        .sort((x, y) => Math.abs(y.d) - Math.abs(x.d))
+        .slice(0, 4)
+        .map((x) => `${x.d > 0 ? "+" : "−"}${x.n} ×${Math.abs(x.d)}`);
+    if (toolDiff.length)
+        out.push(`tools: ${toolDiff.join(", ")}`);
+    if (a.secs !== null && b.secs !== null && moved(a.secs, b.secs, 10))
+        out.push(`took ${a.secs}s → ${b.secs}s`);
+    if (moved(a.tokensIn, b.tokensIn, 5000))
+        out.push(`tokens in ${k(a.tokensIn)} → ${k(b.tokensIn)}`);
+    if (moved(a.modelCalls, b.modelCalls, 3))
+        out.push(`model calls ${a.modelCalls} → ${b.modelCalls}`);
+    if (a.said !== b.said && b.said)
+        out.push(`said: ${b.said}`);
+    return out;
+}
+/** Steps lined up: the flow's own steps by position where the agents agree,
+ *  fan-out instances by agent and order. */
+function align(a, b) {
+    const pairs = [];
+    const used = new Set();
+    b.forEach((s, i) => {
+        let j = a[i] && a[i].agent === s.agent && !used.has(i) ? i : -1;
+        if (j < 0)
+            j = a.findIndex((x, m) => !used.has(m) && x.agent === s.agent);
+        if (j >= 0)
+            used.add(j);
+        pairs.push([j >= 0 ? a[j] : null, s]);
+    });
+    a.forEach((s, m) => !used.has(m) && pairs.push([s, null]));
+    return pairs;
+}
+export function compareRuns(base, run, changedFiles = null) {
+    const head = (r) => ({ id: r.id, status: r.status, startedAt: r.startedAt, revision: r.revision ?? null });
+    return {
+        base: head(base),
+        run: head(run),
+        revisionChanged: (base.revision ?? null) !== (run.revision ?? null),
+        changedFiles,
+        steps: align(base.steps, run.steps).map(([a, b], i) => {
+            const sa = a ? side(a) : null;
+            const sb = b ? side(b) : null;
+            return { step: b ? run.steps.indexOf(b) + 1 : i + 1, agent: (b ?? a).agent, base: sa, run: sb, changes: changes(sa, sb) };
+        }),
+    };
+}
+/** The run to compare a run with when none is named: the newest earlier run
+ *  of the same flow that finished well (completed, not BLOCKED or BAD), or
+ *  null. `outcomeOf` is the caller's, so this stays free of the verdict reader. */
+export function lastGoodBefore(runs, run, good) {
+    return (runs
+        .filter((r) => r.flow === run.flow && r.id !== run.id && r.startedAt < run.startedAt && good(r))
+        .sort((a, b) => b.startedAt.localeCompare(a.startedAt))[0] ?? null);
+}

package/dist/src/completions.js

@@ -37,6 +37,7 @@ const TOOL_GROUPS = [
     { label: "code", hint: "Bash — runs anything in the sandbox" },
     { label: "web", hint: "search, fetch, browse, crawl, map, extract, answer, monitor — providers under web:" },
     { label: "ask", hint: "ask_person — ask the person running the desk mid-step, and wait for the answer" },
+    { label: "peers", hint: "peers_list + peers_message — the colleagues running beside it in its parallel group, and a message to one of them" },
     { label: "install", hint: "install apt, pip or npm packages mid-step — every agent has it; disallowedTools: [install] removes it" },
 ];
 const SDK_TOOL_NAMES = [

package/dist/src/deploy.d.ts

@@ -47,7 +47,27 @@ export interface DeployResult extends DeployPlan {
  * other things is the normal case, not an error.
  */
 export declare const SUBAGENT_IMPORT_DIRS: readonly [".agents/agents", ".claude/agents"];
-export declare function readTree(dir: string): DeployFile[];
+/** Bounds for a reader that only looks at the text (the checks, the
+ *  assistant): on 20 Oct 2026 the daily rescan read one desk's 1.2 GB of
+ *  state/ into a 2 GB heap and crash-looped the worker. A deploy sets none. */
+export interface ReadTreeOptions {
+    /** Data (DATA_PATH) larger than this is left out, unread. */
+    maxDataFileBytes?: number;
+    /** Data past this many bytes in all, or this many files, is left out. */
+    maxDataBytes?: number;
+    maxDataFiles?: number;
+    /** Everything else past this many bytes in all: readTree throws
+     *  TreeTooLarge rather than return a part of the definitions, which a
+     *  check would read as missing agents and flows. */
+    maxSourceBytes?: number;
+    /** Each data file left out, and its size. */
+    onSkip?: (path: string, bytes: number) => void;
+}
+export declare class TreeTooLarge extends Error {
+    /** What an HTTP route answers with it. */
+    readonly status = 413;
+}
+export declare function readTree(dir: string, opts?: ReadTreeOptions): DeployFile[];
 /**
  * Everything wrong with an incoming workspace, before any of it is live.
  *
@@ -77,6 +97,21 @@ export declare function unopenedFrontmatter(raw: string): string | null;
  * advice (an agent that could leak, an unpinned package) is for `foldrun
  * check` and the Checks page, not for every deploy's output.
  */
+/**
+ * What `deploy_block:` in AGENTS.md refuses (FOL-58). `none`, the default:
+ * the scanner's findings are warnings and the deploy goes ahead, as it always
+ * did. `secrets`: a key or password written into a file is refused.
+ * `security`: every security finding is — secrets, hidden or injected text,
+ * the lethal trifecta, pipe-to-shell, an unpinned MCP server, a step that
+ * acts outside with no check or approval. A
+ * `foldrun-ignore` with a reason still accepts one.
+ */
+export declare const DEPLOY_BLOCK_MODES: readonly ["none", "secrets", "security"];
+export type DeployBlockMode = (typeof DEPLOY_BLOCK_MODES)[number];
+/** The workspace's own AGENTS.md, else the account's, else none. */
+export declare function deployBlockMode(files: DeployFile[], accountKeys: Record<string, unknown>): DeployBlockMode;
+/** The findings `mode` turns into refusals, as deploy issues. */
+export declare function deployBlockers(files: DeployFile[], mode: DeployBlockMode, options?: ScanOptions): DeployIssue[];
 export declare function deployWarnings(files: DeployFile[]): DeployIssue[];
 /**
  * Everything the platform can say about a workspace's files, as findings