@foldrun/core 2.4.0 → 2.6.0

package/dist/src/issues.js

@@ -0,0 +1,302 @@
+// Issues: what went wrong, kept open until a person closes it (FOL-54 step 3).
+//
+// The overview used to list "needs attention" from each flow's newest run in
+// the last day, so a later success hid a failure and anything older than a
+// day vanished on its own. An issue is the same thing going wrong again —
+// one desk's flow failing at one agent, or ending BLOCKED or BAD, or one
+// platform cause across every desk — with when it was first and last seen,
+// how many times, which runs, and what to do. It stays open until someone
+// resolves it; a later good run is shown ("fine since …") but closes nothing.
+// (Closing on its own is opt-in, per flow — step 4.)
+//
+// Issues are derived from the runs; only what people did to them is stored
+// (IssueState: acknowledged, snoozed, resolved, reopened, with a history).
+// A run after the issue was resolved opens it again. Pure: the browser, the
+// API and the CLI read the same function.
+/** The model refusing the credential, as the runner sees it (runner.ts
+ *  isAuthRefusal reads this one pattern, so a refusal the runner retries on
+ *  is the same refusal an issue groups by — Codex review). */
+export const AUTH_REFUSAL = /API Error: 401|access token has (been revoked|expired)|OAuth token (has )?(been )?(revoked|expired)|Failed to authenticate/i;
+// On 2026-09-30 every browser step on every desk failed "login-checker: pod
+// never became ready" — the nightly prune had deleted the runner image — and
+// the overview listed it as a dozen separate desk failures, each looking like
+// that desk's login-checker was broken; on 2026-09-29 the worker could not
+// reach the Kubernetes API for eight minutes ("pod create failed … dial tcp
+// 10.43.0.1:443: i/o timeout"). These are the failures no edit to a
+// flow can cause or fix; they are grouped into one item that says so.
+const PLATFORM_CAUSES = [
+    {
+        key: "sandbox",
+        label: "Run sandboxes cannot start",
+        fix: "the runner image or the node — not the desks. Rerun once it is fixed.",
+        test: /pod never became ready|pod create failed|ImagePullBackOff|ErrImagePull|failed to pull image|sandbox (never started|failed to start)/i,
+    },
+    {
+        key: "model-auth",
+        label: "The model credential is refused",
+        fix: "the Claude sign-in expired or was revoked; sign in again, then rerun.",
+        test: new RegExp(`${AUTH_REFUSAL.source}|refresh token expired|authentication_error|invalid x-api-key|(claude|anthropic|model)[^\\n]{0,40}\\b401\\b|\\b401\\b[^\\n]{0,40}(claude|anthropic|model)`, "i"),
+    },
+    {
+        key: "model-cap",
+        label: "The model usage cap is reached",
+        fix: "runs resume when the cap resets; nothing to change in the desks.",
+        test: /weekly (usage )?limit|usage limit (reached|exceeded)|reached your (weekly|usage) limit/i,
+    },
+    {
+        // The provider out of capacity is not the account's cap: it passes in
+        // minutes, not at a reset (Codex review).
+        key: "model-busy",
+        label: "The model provider is overloaded",
+        fix: "the provider's capacity, not the desks; rerun in a few minutes.",
+        test: /overloaded_error|\b529\b[^\n]{0,40}overloaded|overloaded[^\n]{0,40}\b529\b/i,
+    },
+    {
+        key: "worker",
+        label: "The platform lost the run",
+        fix: "a worker restarted mid-run; rerun it.",
+        test: /worker (restarted|was restarted|died|lost)|run was orphaned|lost its worker/i,
+    },
+];
+/** Whether a failure reason is the platform's, and which kind. */
+export function platformCause(reason) {
+    if (!reason)
+        return null;
+    const hit = PLATFORM_CAUSES.find((c) => c.test.test(reason));
+    return hit ? { key: hit.key, label: hit.label, fix: hit.fix } : null;
+}
+/** A short stable id from the issue's key (FNV-1a, 64 bits as two halves). */
+function idOf(key) {
+    let a = 0x811c9dc5, b = 0x01000193 ^ key.length;
+    for (let i = 0; i < key.length; i++) {
+        const c = key.charCodeAt(i);
+        a = Math.imul(a ^ c, 0x01000193) >>> 0;
+        b = Math.imul(b ^ c, 0x5bd1e995) >>> 0;
+    }
+    return `iss_${a.toString(36)}${b.toString(36)}`;
+}
+/** Which issue a run belongs to, or null when it is not a problem. */
+export function issueKeyOf(r) {
+    if (r.missed)
+        return { id: idOf(`missed\u0000${r.workspace}\u0000${r.what}`), kind: "missed", agent: null, cause: null };
+    if (r.outcome === "failed") {
+        const cause = platformCause(r.failure?.reason);
+        if (cause)
+            return { id: idOf(`platform\u0000${cause.key}`), kind: "platform", agent: null, cause };
+        const agent = r.failure?.agent ?? null;
+        return { id: idOf(`failed\u0000${r.workspace}\u0000${r.what}\u0000${agent ?? ""}`), kind: "failed", agent, cause: null };
+    }
+    if (r.outcome === "blocked" || r.outcome === "bad") {
+        return { id: idOf(`${r.outcome}\u0000${r.workspace}\u0000${r.what}`), kind: r.outcome, agent: null, cause: null };
+    }
+    return null;
+}
+const ACTION = {
+    failed: "Read why it failed, fix the flow or agent, then rerun",
+    blocked: "Clear what it is waiting on (a login, a key, an input), then rerun",
+    bad: "Read what it found and decide what to do",
+    missed: "Check why it did not start: the flow or the account paused, out of credit, or the scheduler down — then run it by hand",
+};
+const lastOf = (h, actions) => [...h].reverse().find((e) => actions.includes(e.action)) ?? null;
+/**
+ * Every issue the runs show, with what people did to them folded in.
+ * `states` is keyed by issue id. Resolved issues are kept (with their last
+ * occurrences) while their runs are still in the window, so their history
+ * can be read; a status filter is the caller's.
+ */
+export function foldIssues(runs, states, now, 
+/** `autoClose(workspace, flow)`: the flow says `issues: auto-close`, so a
+ *  run that goes fine after a failure closes it (FOL-72 step 7). Never a
+ *  platform cause or a missed schedule — those stay until a person says. */
+opts = {}) {
+    // When it went wrong (or right): its end, else its start. A run that
+    // started before a resolve and failed after it is news, and of two
+    // overlapping failures the one that ended last is the newest (Codex review).
+    const occurred = (r) => r.finishedAt ?? r.startedAt;
+    const all = [...runs].sort((a, b) => occurred(a).localeCompare(occurred(b)));
+    // The last run of each desk's flow to finish, to say "fine since" — only
+    // when it is itself fine, and finished after the issue's last occurrence
+    // (a success between two failures, or one that overlapped a later
+    // failure, is not a recovery — Codex review).
+    const newestDone = new Map();
+    for (const r of all) {
+        if (r.outcome === "running" || r.outcome === "queued" || r.outcome === "waiting")
+            continue;
+        const k = `${r.workspace}\u0000${r.what}`;
+        const cur = newestDone.get(k);
+        if (!cur || occurred(r) >= occurred(cur))
+            newestDone.set(k, r);
+    }
+    const fine = (o) => o === "good" || o === "done" || o === "quiet";
+    const groups = new Map();
+    for (const r of all) {
+        const key = issueKeyOf(r);
+        if (!key)
+            continue;
+        const g = groups.get(key.id) ?? { key, runs: [] };
+        g.runs.push(r);
+        groups.set(key.id, g);
+    }
+    const out = [];
+    for (const [id, { key, runs: hit }] of groups) {
+        const history = states[id]?.history ?? [];
+        const res = lastOf(history, ["resolve", "reopen"]);
+        // Replay the runs and the resolves/reopens in time order: a run going
+        // wrong after a resolve starts a new episode, a resolve closes the
+        // current one, a reopen carries it on. The issue shows its current (or
+        // last closed) episode — never every one ever closed. A run that ended
+        // at the moment of a resolve was closed by it. (Codex review, in rounds.)
+        // In a flow that says `issues: auto-close`, every run of it that went
+        // fine closes the episode as a resolve would, marked as the platform's.
+        const auto = key.kind !== "platform" && key.kind !== "missed" && hit[0] && opts.autoClose?.(hit[0].workspace, hit[0].what) === true;
+        const fineRuns = auto ? all.filter((r) => r.workspace === hit[0].workspace && r.what === hit[0].what && fine(r.outcome)) : [];
+        const timeline = [
+            ...hit.map((r) => ({ t: occurred(r), order: 0, run: r, act: null })),
+            ...history.filter((e) => e.action === "resolve" || e.action === "reopen").map((e) => ({ t: e.at, order: 1, run: null, act: e.action })),
+            ...fineRuns.map((r) => ({ t: occurred(r), order: 1, run: null, act: "auto" })),
+        ].sort((a, b) => a.t.localeCompare(b.t) || a.order - b.order);
+        let shown = [];
+        let closed = false;
+        let closedBy = null;
+        let autoAt = null;
+        // The last time the platform closed it: an acknowledge or a snooze from
+        // before then belongs to the episode it closed (Codex review).
+        let lastAutoClose = null;
+        let episodes = 0;
+        for (const ev of timeline) {
+            if (ev.run) {
+                if (closed || !shown.length) {
+                    shown = [];
+                    episodes++;
+                }
+                closed = false;
+                shown.push(ev.run);
+            }
+            else if (ev.act === "resolve" || (ev.act === "auto" && shown.length)) {
+                closed = true;
+                closedBy = ev.act === "auto" ? "auto" : "person";
+                if (ev.act === "auto") {
+                    autoAt = ev.t;
+                    lastAutoClose = ev.t;
+                }
+            }
+            else if (ev.act === "reopen")
+                closed = false;
+        }
+        if (!shown.length)
+            continue;
+        const resolvedAt = closed ? (closedBy === "auto" ? autoAt : res?.action === "resolve" ? res.at : null) : null;
+        const newest = shown[shown.length - 1];
+        // A snooze holds while its time has not come and, for "until N more",
+        // while fewer than N have happened since it.
+        const current = (e) => (e && (!lastAutoClose || e.at > lastAutoClose) ? e : null);
+        const snoozeEv = current(lastOf(history, ["snooze", "resolve", "reopen"]));
+        const since = snoozeEv?.action === "snooze" ? shown.filter((r) => occurred(r) > snoozeEv.at).length : 0;
+        const snoozeLeft = snoozeEv?.action === "snooze" && snoozeEv.untilCount ? Math.max(0, snoozeEv.untilCount - since) : null;
+        const snoozeHolds = snoozeEv?.action === "snooze" &&
+            (!snoozeEv.until || Date.parse(snoozeEv.until) > now) &&
+            (snoozeLeft === null || snoozeLeft > 0) &&
+            Boolean(snoozeEv.until || snoozeEv.untilCount);
+        const status = (() => {
+            if (resolvedAt)
+                return "resolved";
+            if (snoozeHolds)
+                return "snoozed";
+            const ack = current(lastOf(history, ["acknowledge", "resolve", "reopen"]));
+            if (ack?.action === "acknowledge")
+                return "acknowledged";
+            return "open";
+        })();
+        const ack = current(lastOf(history, ["acknowledge", "resolve", "reopen"]));
+        const flowKey = `${newest.workspace}\u0000${newest.what}`;
+        const last = key.kind === "platform" ? null : newestDone.get(flowKey) ?? null;
+        const ok = last && fine(last.outcome) && occurred(last) > occurred(newest) ? occurred(last) : null;
+        const workspaces = [...new Set(shown.map((r) => r.workspace))].sort();
+        out.push({
+            id,
+            kind: key.kind,
+            status,
+            workspace: newest.workspace,
+            workspaces,
+            what: key.cause ? key.cause.label : newest.what,
+            agent: key.agent,
+            reason: key.kind === "missed"
+                ? newest.headline ?? `due ${newest.startedAt}, no run started`
+                : key.cause
+                    ? newest.failure ? `${newest.failure.agent}: ${newest.failure.reason}` : key.cause.label
+                    : newest.failure ? `${newest.failure.agent}: ${newest.failure.reason}` : newest.headline?.trim() || newest.outcome,
+            action: key.cause ? `Fix ${key.cause.fix}` : ACTION[key.kind],
+            firstSeen: occurred(shown[0]),
+            lastSeen: occurred(newest),
+            count: shown.length,
+            runs: shown.slice(-20).reverse().map((r) => ({ workspace: r.workspace, id: r.id, at: occurred(r), ...(r.missed ? { missed: true } : {}) })),
+            recoveredAt: ok,
+            acknowledged: ack?.action === "acknowledge" ? { at: ack.at, by: ack.by } : null,
+            snoozedUntil: status === "snoozed" && snoozeEv?.until ? snoozeEv.until : null,
+            snoozedFor: status === "snoozed" ? snoozeLeft : null,
+            regressed: episodes > 1,
+            sinceRevision: shown[0].revision ?? null,
+            // Only while it is resolved; once it happens again, the history says it was.
+            resolved: status === "resolved"
+                ? closedBy === "auto"
+                    ? { at: resolvedAt, by: "auto: a later run went fine" }
+                    : res
+                        ? { at: res.at, by: res.by }
+                        : null
+                : null,
+            history,
+        });
+    }
+    const rank = { open: 0, acknowledged: 1, snoozed: 2, resolved: 3 };
+    const kindRank = { platform: 0, missed: 1, failed: 2, blocked: 3, bad: 4 };
+    return out.sort((a, b) => rank[a.status] - rank[b.status] || kindRank[a.kind] - kindRank[b.kind] || b.lastSeen.localeCompare(a.lastSeen));
+}
+/** An issue still asking for someone: open or acknowledged, not snoozed or resolved. */
+export const isActiveIssue = (i) => i.status === "open" || i.status === "acknowledged";
+/**
+ * What the run doctor needs to look at an issue: its newest run, the
+ * workspace that run is in (the assistant works inside one), and the
+ * question the run page's Doctor button asks — so the issue's button, the
+ * CLI's `issues doctor` and the run page put it the same way. Null for a
+ * missed schedule, which has no run to read.
+ */
+export function issueDoctor(issue) {
+    const run = issue.runs.find((r) => !r.missed);
+    if (!run || issue.kind === "missed")
+        return null;
+    const ended = issue.kind === "blocked" ? "end BLOCKED" : issue.kind === "bad" ? "end BAD" : "fail";
+    return { workspace: run.workspace, runId: run.id, prompt: `Doctor: why did run ${run.id} ${ended}, and how do I fix it?` };
+}
+/** Parse "30m", "4h", "1d", "1w" into milliseconds; null if not one. */
+export function snoozeMs(s) {
+    const m = /^(\d+)\s*(m|h|d|w)$/.exec(s.trim());
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    const unit = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 7 * 86_400_000 }[m[2]];
+    return n > 0 ? n * unit : null;
+}
+/** One person's act on an issue, appended to its history. Refuses a snooze
+ *  with no future `until`. Pure: the caller stores the result. */
+export function applyIssueAction(state, ev, now) {
+    if (ev.action === "snooze" && !(ev.until && Date.parse(ev.until) > now) && !(typeof ev.untilCount === "number" && ev.untilCount > 0)) {
+        throw new Error("a snooze needs a time in the future, or a number of times it may happen again");
+    }
+    const history = [...(state?.history ?? []), ev];
+    // Bounded: an issue snoozed every morning for a year is still one row. The
+    // newest of each kind of act is always kept, whatever its age, because the
+    // issue's state is read from them — dropping the last resolve would bring
+    // back what it closed (Codex review).
+    if (history.length <= 100)
+        return { history };
+    const keep = new Set(history.map((_, i) => i).slice(-100));
+    for (const a of ["acknowledge", "snooze", "resolve", "reopen"]) {
+        const i = history.map((e) => e.action).lastIndexOf(a);
+        if (i >= 0)
+            keep.add(i);
+    }
+    // Every resolve and reopen: the episodes an issue shows are replayed from
+    // them, and each one is a person's act, so there are few (Codex review).
+    history.forEach((e, i) => (e.action === "resolve" || e.action === "reopen") && keep.add(i));
+    return { history: history.filter((_, i) => keep.has(i)) };
+}

package/dist/src/judge-verdict.d.ts

@@ -0,0 +1,19 @@
+/** The line to end a judge prompt with. */
+export declare const JUDGE_VERDICT_INSTRUCTION = "Check each part against the text in a few short sentences. Then, on the last line and alone, write exactly PASS or FAIL \u2014 PASS only if every part holds.";
+/**
+ * The judge's verdict: the PASS or FAIL alone on its last line, with the
+ * reasoning before it as the detail. An answer in the old shape (the word
+ * first) still reads; one with no verdict at all is a FAIL that says so.
+ */
+export declare function judgeVerdict(text: string): {
+    passed: boolean;
+    detail: string;
+};
+/** `judge:` in AGENTS.md — the model and effort every judge in the workspace
+ *  grades with, unless an eval names its own. `model` is a tier or alias as
+ *  anywhere else; what is wrong with the block, in words, for check. */
+export declare function parseJudge(raw: unknown): {
+    model?: string;
+    effort?: string;
+    problems: string[];
+};

package/dist/src/judge-verdict.js

@@ -0,0 +1,54 @@
+// What a judge said: the PASS or FAIL alone on its last line, after its
+// reasoning. Shared by the eval judge (evals.ts) and a flow step's
+// `verify: judge:` (step-exec.ts), which ask for the same shape.
+//
+// The word comes last because, asked for it first, a judge commits before
+// it has looked and then argues the other way — "FAIL … which meets the
+// criterion" (vaza evals, 21 Oct 2026).
+import { EFFORT_LEVELS } from "./frontmatter-fields.js";
+/** The line to end a judge prompt with. */
+export const JUDGE_VERDICT_INSTRUCTION = "Check each part against the text in a few short sentences. Then, on the last line and alone, write exactly PASS or FAIL — PASS only if every part holds.";
+/**
+ * The judge's verdict: the PASS or FAIL alone on its last line, with the
+ * reasoning before it as the detail. An answer in the old shape (the word
+ * first) still reads; one with no verdict at all is a FAIL that says so.
+ */
+export function judgeVerdict(text) {
+    const lines = text.trim().split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    const word = (l) => /^[*_`#\s]*(PASS|FAIL)[*_`.\s]*$/i.exec(l ?? "")?.[1]?.toUpperCase();
+    let verdict = word(lines[lines.length - 1]);
+    let reason = lines.slice(0, -1).join(" ");
+    if (!verdict) {
+        const first = /^[*_`#\s]*(PASS|FAIL)\b[*_`:.\s-]*(.*)$/i.exec(lines[0] ?? "");
+        if (first) {
+            verdict = first[1].toUpperCase();
+            reason = [first[2], ...lines.slice(1)].join(" ").trim();
+        }
+    }
+    if (!verdict)
+        return { passed: false, detail: `judge gave no PASS or FAIL: ${text.trim().slice(0, 300) || "nothing"}` };
+    // The end of the reasoning is the part that decided it.
+    const why = reason.length > 400 ? `…${reason.slice(-400)}` : reason;
+    return { passed: verdict === "PASS", detail: `${verdict}${why ? ` — ${why}` : ""}` };
+}
+/** `judge:` in AGENTS.md — the model and effort every judge in the workspace
+ *  grades with, unless an eval names its own. `model` is a tier or alias as
+ *  anywhere else; what is wrong with the block, in words, for check. */
+export function parseJudge(raw) {
+    if (raw === undefined || raw === null)
+        return { problems: [] };
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return { problems: ["judge: is a block — {model: fast | default | max, effort: low…max}"] };
+    const o = raw;
+    const problems = [];
+    for (const k of Object.keys(o))
+        if (k !== "model" && k !== "effort")
+            problems.push(`judge: ${k} — not a key; the keys are model and effort`);
+    const model = typeof o.model === "string" && o.model.trim() ? o.model.trim() : undefined;
+    if (o.model !== undefined && !model)
+        problems.push("judge: model — a tier (fast, default, max), an alias or a model id");
+    const effort = typeof o.effort === "string" && EFFORT_LEVELS.includes(o.effort.trim()) ? o.effort.trim() : undefined;
+    if (o.effort !== undefined && !effort)
+        problems.push(`judge: effort ${String(o.effort)} — low, medium, high, xhigh or max`);
+    return { ...(model ? { model } : {}), ...(effort ? { effort } : {}), problems };
+}

package/dist/src/library.js

@@ -14,7 +14,7 @@ import { platform } from "./platform.js";
 import fs from "node:fs";
 import path from "node:path";
 import { dataRoot, singleWorkspace, singleAccountRoot, MAX_EDITABLE_FILE } from "./paths.js";
-import matter from "gray-matter";
+import matter from "./matter.js";
 import { KINDS } from "./kinds.js";
 import { recordRevision, registerTreeReader } from "./history.js";
 import { assertSafeName, assertCanonicalCase, buildMemoryIndex, parseToolDef, readToolDir, syncBundleFor, listWorkspaces, listAgents, workspaceDir, } from "./store.js";

package/dist/src/limits.d.ts

@@ -1,6 +1,11 @@
 export type Limits = Record<string, number>;
 /** The key that caps every call in the step. */
 export declare const TOTAL_KEY = "calls";
+/** The key that caps one identical call: a model asking the same tool the
+ *  same thing over and over is stuck, and every repeat is spend. Each call
+ *  also counts under `repeat:<hash of tool and input>`; `repeat: N` caps
+ *  every one of those. */
+export declare const REPEAT_KEY = "repeat";
 /** One spelling for comparing: `desk-email` and `desk_email` are the same
  *  tool (a script tool's SDK name has its dashes made underscores). */
 export declare function normKey(key: string): string;
@@ -34,6 +39,9 @@ export declare function toolOwners(apiOwners: Record<string, string>, scripts: {
  * name, its input, and the owners map.
  */
 export declare function limitKeysFor(toolName: string, input: Record<string, unknown> | undefined, owners?: Record<string, string>): string[];
+/** What step-exec counts one call under: limitKeysFor's keys and the
+ *  call's own `repeat:` key, for `limits: repeat`. */
+export declare function callKeysFor(toolName: string, input: Record<string, unknown> | undefined, owners?: Record<string, string>): string[];
 export interface LimitRefusal {
     key: string;
     used: number;

package/dist/src/limits.js

@@ -6,6 +6,7 @@
 //     web: 150            # every web action together
 //     crm: 20             # an API, script or MCP tool, by the name it is granted as
 //     calls: 300          # every tool call in the step, whatever the tool
+//     repeat: 5           # the same call — one tool, the same input — at most this often
 //
 // Counted per step and enforced in step-exec.ts's PreToolUse hook — the one
 // place every call passes, the step's own and its sub-agents', on the
@@ -17,10 +18,27 @@
 //
 // Nearest wins per key: the account's AGENTS.md, then the workspace's, then
 // the agent's own `limits:`, then a flow step's `limits:` option.
+import crypto from "node:crypto";
 import { WEB_ACTIONS } from "./providers.js";
 import { DELEGATE_TOOLS } from "./subagents.js";
 /** The key that caps every call in the step. */
 export const TOTAL_KEY = "calls";
+/** The key that caps one identical call: a model asking the same tool the
+ *  same thing over and over is stuck, and every repeat is spend. Each call
+ *  also counts under `repeat:<hash of tool and input>`; `repeat: N` caps
+ *  every one of those. */
+export const REPEAT_KEY = "repeat";
+/** JSON with its keys sorted, so `{a,b}` and `{b,a}` are the same call. */
+function stable(v) {
+    if (Array.isArray(v))
+        return `[${v.map(stable).join(",")}]`;
+    if (v && typeof v === "object")
+        return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${stable(v[k])}`).join(",")}}`;
+    return JSON.stringify(v) ?? "null";
+}
+function repeatKey(toolName, input) {
+    return `${REPEAT_KEY}:${crypto.createHash("sha1").update(`${toolName}\0${stable(input ?? {})}`).digest("hex").slice(0, 16)}`;
+}
 /** SDK built-ins, counted under the foldrun group that grants them — and
  *  under their own SDK name, so `Bash: 5` works for a Claude Code file. */
 const BUILTIN_GROUP = {
@@ -36,6 +54,7 @@ const PLATFORM_SERVERS = {
     foldrun_history: "history",
     foldrun_desks: "desks",
     foldrun_ask: "ask",
+    foldrun_peers: "peers",
 };
 /** One spelling for comparing: `desk-email` and `desk_email` are the same
  *  tool (a script tool's SDK name has its dashes made underscores). */
@@ -72,7 +91,7 @@ export function readLimits(raw, where = "limits") {
     for (const [key, value] of flat) {
         const k = key.trim();
         if (!KEY_RE.test(k)) {
-            problems.push(`${where}: "${k}" is not a key — a tool's name, web.<action>, or calls.`);
+            problems.push(`${where}: "${k}" is not a key — a tool's name, web.<action>, calls, or repeat.`);
             continue;
         }
         if (k.includes(".")) {
@@ -169,6 +188,11 @@ export function limitKeysFor(toolName, input, owners = {}) {
     keys.push(toolName);
     return keys;
 }
+/** What step-exec counts one call under: limitKeysFor's keys and the
+ *  call's own `repeat:` key, for `limits: repeat`. */
+export function callKeysFor(toolName, input, owners = {}) {
+    return [...limitKeysFor(toolName, input, owners), repeatKey(toolName, input)];
+}
 /**
  * One step's counts. `take` checks every key the call counts under and
  * either refuses — counting nothing — or counts it under all of them.
@@ -187,7 +211,8 @@ export class CallCounter {
     take(keys) {
         const norm = [...new Set(keys.map(normKey))];
         for (const k of norm) {
-            const l = this.limits.get(k);
+            const repeat = k.startsWith(`${REPEAT_KEY}:`);
+            const l = this.limits.get(repeat ? REPEAT_KEY : k);
             if (!l)
                 continue;
             const used = this.used.get(k) ?? 0;
@@ -195,7 +220,9 @@ export class CallCounter {
                 this.refused++;
                 return {
                     key: l.key, used, limit: l.limit,
-                    message: `limit reached: ${l.key} ${used} of ${l.limit} in this step — work with what you have, or say what more you would need`,
+                    message: repeat
+                        ? `limit reached: this exact call (same tool, same input) ${used} of ${l.limit} times in this step — repeating it will not change the answer; try something different, or say what is stuck`
+                        : `limit reached: ${l.key} ${used} of ${l.limit} in this step — work with what you have, or say what more you would need`,
                 };
             }
         }
@@ -218,7 +245,11 @@ export class CallCounter {
     summary() {
         if (!this.active)
             return null;
-        const parts = [...this.limits.entries()].map(([k, l]) => `${l.key} ${this.used.get(k) ?? 0}/${l.limit}`);
+        // repeat: the most any one call was made, against its cap.
+        const most = (k) => k === REPEAT_KEY
+            ? Math.max(0, ...[...this.used.entries()].filter(([u]) => u.startsWith(`${REPEAT_KEY}:`)).map(([, n]) => n))
+            : this.used.get(k) ?? 0;
+        const parts = [...this.limits.entries()].map(([k, l]) => `${l.key} ${most(k)}/${l.limit}`);
         return `limits: ${parts.join(", ")}${this.refused ? ` — ${this.refused} call${this.refused === 1 ? "" : "s"} refused` : ""}`;
     }
 }
@@ -248,7 +279,7 @@ export function limitKeyProblems(limits, ctx) {
         return [n];
     }).map(normKey));
     for (const key of Object.keys(limits)) {
-        if (key === TOTAL_KEY)
+        if (key === TOTAL_KEY || key === REPEAT_KEY)
             continue;
         const base = key.startsWith("web.") ? "web" : key;
         const n = normKey(base);

package/dist/src/linkable.js

@@ -13,7 +13,7 @@
 // real workspace, so a future rename fails a test instead of a run.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.js";
 import { STORAGE_DIR } from "./store.js";
 /** The directories a bare [[name]] may point at, matching the resolver. */
 export const LINKABLE_DIRS = [STORAGE_DIR, "state", "knowledge", "memory", "skills", "outputs"];

package/dist/src/matter.d.ts

@@ -0,0 +1,42 @@
+import grayMatter from "gray-matter";
+import { type Job } from "./frontmatter-fields.ts";
+type Options = NonNullable<Parameters<typeof grayMatter>[1]>;
+export interface JobFold {
+    /** A key lifted out of a block, and the block it was in. */
+    folded: Map<string, Job>;
+    /** A key set both at the top and inside a block: the top one is kept, and
+     *  check refuses the file (config/conflict). */
+    conflicts: Map<string, Job>;
+}
+/** What the fold did to this data, or null when it had no blocks. */
+export declare function jobFold(data: unknown): JobFold | null;
+declare function matter(input: string, options?: Options): grayMatter.GrayMatterFile<string>;
+declare namespace matter {
+    var stringify: typeof grayMatter.stringify;
+    var test: typeof grayMatter.test;
+}
+/**
+ * matter(), for the three files that hold configuration — an agent, a flow,
+ * AGENTS.md — with the four job blocks read as flat keys. Every reader of
+ * those files goes through this (tests/jobs.test.ts holds them to it);
+ * knowledge, memory, skills and every other document keep matter(), so a
+ * note's own `governance:` is its own (Codex debate, 21 Oct 2026).
+ */
+export declare function configMatter(input: string, options?: Options): grayMatter.GrayMatterFile<string>;
+export default matter;
+/** The first line of a YAML parse error, with where it is: what a person
+ *  needs to fix the file, without the parser's excerpt. */
+export declare function frontmatterErrorText(err: unknown): string;
+/** The 1-based file line a YAML parse error points at, when it says. The
+ *  text gray-matter hands the parser starts with the newline after the
+ *  opening `---`, so the parser's 0-based line is the file's 1-based one. */
+export declare function frontmatterErrorLine(err: unknown): number | undefined;
+/** Frontmatter as the runtime reads a skill: strictly first, then once more
+ *  with every unquoted value that holds a colon quoted (the commonest way a
+ *  hand-written SKILL.md breaks, and one other skills clients forgive), and
+ *  empty when even that fails. `lenient` says the second read was needed. */
+export declare function parseLenient(raw: string): {
+    data: Record<string, unknown>;
+    lenient: boolean;
+    failed: boolean;
+};