@foldrun/core 2.4.0 → 2.6.0

package/dist/src/frontmatter-schema.js

@@ -1,10 +1,12 @@
 // Checking frontmatter against frontmatter-fields.ts: the values, not just
 // the names. Node-side (it reads store's parsers); the browser takes the
 // field list alone from frontmatter-fields.ts.
-import { FRONTMATTER } from "./frontmatter-fields.js";
+import { FRONTMATTER, JOBS } from "./frontmatter-fields.js";
+import { jobFold } from "./matter.js";
 import { resolveEffort, parseDuration, parseInstant, parseRate, STEP_OPTION_KEYS } from "./store.js";
 import { budgetProblem } from "./budget.js";
 import { cronProblem } from "./cron.js";
+import { modelSecretCollision } from "./model-credential.js";
 export { FRONTMATTER, schemaKindOf } from "./frontmatter-fields.js";
 /** A value for a message: a scalar as written, anything else by its shape.
  *  Never String() of a map — its `toString` is whatever the YAML says. */
@@ -29,6 +31,7 @@ const CHECKS = {
         apis: apisProblem,
         budget: (v) => budgetProblem(v, ["run"]),
         ask: (v) => askProblem(v),
+        secrets: modelSecretCollision,
     },
     "agents-md": {
         budget: (v) => budgetProblem(v, ["day", "week", "month"]),
@@ -52,6 +55,7 @@ const CHECKS = {
         transport: (v) => (["http", "script", "mcp"].includes(String(v).toLowerCase()) ? null : `"${String(v)}" is not a transport — http, script or mcp`),
         methods: methodsProblem,
         rate: (v) => (parseRate(v) ? null : `"${shown(v)}" is not a rate — N/s, N/minute, N/hour, or a number per second, above 0`),
+        secrets: modelSecretCollision,
     },
     "eval": {
         effort: (v) => (resolveEffort(v) ? null : `"${String(v)}" is not an effort — low, medium, high, xhigh or max; the judge runs at none`),
@@ -77,7 +81,33 @@ export function frontmatterProblems(kind, data, near) {
     const fields = FRONTMATTER[kind];
     const known = fields.map((f) => f.key);
     const out = [];
+    // The four job blocks (matter.ts folds them): a key set both ways, and a
+    // key left in a block that does not hold it.
+    const fold = jobFold(data);
+    for (const [key, job] of fold?.conflicts ?? []) {
+        out.push({ key, rule: "config/conflict", level: "error", message: `\`${key}:\` is set twice — at the top and inside \`${job}:\`. Only the top one would be read; keep one` });
+    }
+    for (const { name: job } of JOBS) {
+        const block = data[job];
+        if (!block || typeof block !== "object" || Array.isArray(block))
+            continue;
+        for (const inner of Object.keys(block)) {
+            const spec = fields.find((f) => f.key === inner);
+            const message = spec?.job
+                ? `\`${inner}:\` is a ${spec.job} field, not a ${job} one — move it into \`${spec.job}:\` or to the top. Inside \`${job}:\` it is not read`
+                : spec
+                    ? `\`${inner}:\` belongs to none of the four jobs — write it at the top. Inside \`${job}:\` it is not read`
+                    : `\`${inner}:\` inside \`${job}:\` is not a field foldrun reads${belongsIn(inner, kind) ? ` here — it is read in ${belongsIn(inner, kind)}` : ""}; it is ignored`;
+            // A real setting in the wrong block is a setting silently not applied
+            // — a guardrail written under governance: guards nothing — so it is an
+            // error (Codex debate). A word foldrun does not read at all is a note.
+            out.push({ key: inner, rule: "config/misplaced", level: spec ? "error" : "info", message });
+        }
+    }
     for (const [key, value] of Object.entries(data)) {
+        // A block holding only misplaced keys is reported above, key by key.
+        if (JOBS.some((j) => j.name === key) && value && typeof value === "object" && !Array.isArray(value))
+            continue;
         const spec = fields.find((f) => f.key === key);
         const check = CHECKS[kind]?.[key];
         if (!spec) {
@@ -92,7 +122,8 @@ export function frontmatterProblems(kind, data, near) {
                 out.push({ key, rule: "config/unknown-field", level: "warn", message: `\`${key}:\` is not read on an agent — it is a step option: indent it under the step in the flow (\`   ${key}: ${shown(value)}\`). Here it is ignored` });
             }
             else if (home) {
-                out.push({ key, rule: "config/unknown-field", level: "warn", message: `\`${key}:\` is read in ${home}, not in ${kind === "agents-md" ? "AGENTS.md" : kind === "eval" ? "an eval" : `a ${kind}`} — here it is ignored` });
+                const where = fold?.folded.get(key);
+                out.push({ key, rule: "config/unknown-field", level: "warn", message: `\`${key}:\`${where ? ` (inside \`${where}:\`)` : ""} is read in ${home}, not in ${kind === "agents-md" ? "AGENTS.md" : kind === "eval" ? "an eval" : `a ${kind}`} — here it is ignored` });
             }
             else {
                 out.push({ key, rule: "config/unknown-field", level: "info", message: `\`${key}:\` is not a field foldrun reads; it is ignored` });

package/dist/src/frontmatter-text.d.ts

@@ -0,0 +1,31 @@
+export interface KeySpan {
+    /** The key's line. */
+    at: number;
+    /** One past its last line. */
+    end: number;
+    /** What its line starts with. */
+    indent: string;
+    /** The block header's line, when it is inside one. */
+    block: number | null;
+}
+/** Thrown for a key a writer cannot edit in place: one that is, or may be,
+ *  inside a block not written one key per line (`guardrail: {…}`, an alias).
+ *  Rewriting it would mean re-serialising the person's YAML, and adding the
+ *  key at the top beside it would be a config/conflict — so the writer says
+ *  what to write instead. */
+export declare class InlineBlockError extends Error {
+    status: number;
+    constructor(key: string, block: string);
+}
+/**
+ * Where a key is written in frontmatter lines: at the top, or a direct child
+ * of one of the four job blocks (`guardrail:` and so on). Every writer that
+ * edits a key as text reads it here, so a file written in blocks is edited
+ * where it is — never given a second, flat copy that check would refuse as
+ * config/conflict. A key inside an inline block map throws InlineBlockError.
+ */
+export declare function keySpan(lines: string[], key: string): KeySpan | null;
+/** A block header left with nothing under it is removed with its last key.
+ *  Blank lines and comments between it and its next key do not count as
+ *  nothing: the header stays while any indented key follows them. */
+export declare function dropEmptyBlock(lines: string[], header: number): string[];

package/dist/src/frontmatter-text.js

@@ -0,0 +1,102 @@
+// Frontmatter edited as text, where it is written: at the top or inside one
+// of the four job blocks. No node imports — the flow canvas (flow-patterns.ts)
+// runs in the browser and edits frontmatter with it too.
+/** A block header on its own line — an anchor and a trailing `# comment`
+ *  allowed. */
+const JOB_BLOCK = /^["']?(governance|guardrail|observability|evaluation)["']?\s*:\s*(&\S+\s*)?(#.*)?$/;
+/** Any other block header: an inline map, an alias, a tag — a form these
+ *  writers do not edit. */
+const JOB_OTHER = /^["']?(governance|guardrail|observability|evaluation)["']?\s*:\s*\S/;
+/** An inline map closed on its own line: `guardrail: {network: [a.com]}`. */
+const JOB_ONE_LINE = /^["']?(governance|guardrail|observability|evaluation)["']?\s*:\s*\{.*\}\s*(#.*)?$/;
+const indentOf = (l) => l.match(/^[ \t]*/)?.[0].length ?? 0;
+/** Thrown for a key a writer cannot edit in place: one that is, or may be,
+ *  inside a block not written one key per line (`guardrail: {…}`, an alias).
+ *  Rewriting it would mean re-serialising the person's YAML, and adding the
+ *  key at the top beside it would be a config/conflict — so the writer says
+ *  what to write instead. */
+export class InlineBlockError extends Error {
+    status = 409;
+    constructor(key, block) {
+        super(`\`${key}\` may be inside \`${block}:\`, which is not written one key per line — write \`${block}:\` one key per line to change it here, or edit the file`);
+    }
+}
+/** A comment or blank line: neither ends a block nor is one of its keys. */
+const filler = (l) => l.trim() === "" || /^\s*#/.test(l);
+/**
+ * Where a key is written in frontmatter lines: at the top, or a direct child
+ * of one of the four job blocks (`guardrail:` and so on). Every writer that
+ * edits a key as text reads it here, so a file written in blocks is edited
+ * where it is — never given a second, flat copy that check would refuse as
+ * config/conflict. A key inside an inline block map throws InlineBlockError.
+ */
+export function keySpan(lines, key) {
+    const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const span = (at, indent, block) => {
+        let end = at + 1;
+        // The key continues while lines are indented deeper, are an item of its
+        // list written at its own indent (YAML allows `key:\n- a`), or are blank
+        // lines and comments inside it.
+        while (end < lines.length &&
+            (filler(lines[end]) ||
+                indentOf(lines[end]) > indent.length ||
+                (indentOf(lines[end]) === indent.length && /^[ \t]*-(\s|$)/.test(lines[end]))))
+            end++;
+        // Blank lines and comments at its foot, no deeper than the key, belong
+        // to what follows.
+        while (end > at + 1 && filler(lines[end - 1]) && (lines[end - 1].trim() === "" || indentOf(lines[end - 1]) <= indent.length))
+            end--;
+        return { at, end, indent, block };
+    };
+    // A key may be quoted: `"network": none`.
+    const named = `["']?${k}["']?\\s*:`;
+    const top = lines.findIndex((l) => new RegExp(`^${named}`).test(l));
+    if (top !== -1)
+        return span(top, "", null);
+    for (let h = 0; h < lines.length; h++) {
+        const other = !JOB_BLOCK.test(lines[h]) && JOB_OTHER.exec(lines[h]);
+        if (other) {
+            // One closed line can be read: refuse only if the key is in it. Any
+            // other form (a map over several lines, an alias) cannot be, so any
+            // key not found at the top is refused rather than added beside it.
+            if (!JOB_ONE_LINE.test(lines[h]) || new RegExp(`[{,]\\s*${named}`).test(lines[h]))
+                throw new InlineBlockError(key, other[1]);
+            continue;
+        }
+        if (!JOB_BLOCK.test(lines[h]))
+            continue;
+        // Its children sit at the indent of its first indented line; a deeper
+        // line of the same name belongs to one of them, not to the block.
+        // Comments and blank lines, indented or not, do not end it.
+        let child = -1;
+        let merged = false;
+        for (let n = h + 1; n < lines.length && (/^[ \t]/.test(lines[n]) || filler(lines[n])); n++) {
+            if (filler(lines[n]))
+                continue;
+            if (child === -1)
+                child = indentOf(lines[n]);
+            if (indentOf(lines[n]) !== child)
+                continue;
+            const m = new RegExp(`^([ \t]+)${named}`).exec(lines[n]);
+            if (m)
+                return span(n, m[1], h);
+            if (/^[ \t]+<<\s*:/.test(lines[n]))
+                merged = true;
+        }
+        // `<<: *policy` may bring the key in from elsewhere: not one this text
+        // edit can see, so it is refused rather than added beside it.
+        if (merged)
+            throw new InlineBlockError(key, JOB_BLOCK.exec(lines[h])[1]);
+    }
+    return null;
+}
+/** A block header left with nothing under it is removed with its last key.
+ *  Blank lines and comments between it and its next key do not count as
+ *  nothing: the header stays while any indented key follows them. */
+export function dropEmptyBlock(lines, header) {
+    let n = header + 1;
+    while (n < lines.length && filler(lines[n]))
+        n++;
+    const next = lines[n];
+    return next === undefined || !/^[ \t]+\S/.test(next) ? [...lines.slice(0, header), ...lines.slice(header + 1)] : lines;
+}

package/dist/src/history.d.ts

@@ -86,6 +86,10 @@ export declare function listRevisions(tenant: string, scope: string, opts?: {
     limit?: number;
 }): RevisionSummary[];
 export declare function readRevision(tenant: string, scope: string, id: string, forPath?: string): Revision | null;
+/** The files changed after revision `from` up to and including `to`, in a
+ *  scope — what differs between the versions two runs ran (FOL-72). Null
+ *  when either is unknown or `to` is not after `from`. */
+export declare function changedPathsBetween(tenant: string, scope: string, from: string | null, to: string | null): string[] | null;
 /** The most recent revision id for a scope — what a change is attributed
  *  to when nothing more specific (a deployed commit) is on record. */
 export declare function latestRevisionId(tenant: string, scope: string): string | null;

package/dist/src/history.js

@@ -344,6 +344,21 @@ export function readRevision(tenant, scope, id, forPath) {
     const rev = JSON.parse(fs.readFileSync(file, "utf8"));
     return forPath ? { ...rev, files: rev.files.filter((f) => f.path === forPath) } : rev;
 }
+/** The files changed after revision `from` up to and including `to`, in a
+ *  scope — what differs between the versions two runs ran (FOL-72). Null
+ *  when either is unknown or `to` is not after `from`. */
+export function changedPathsBetween(tenant, scope, from, to) {
+    if (!from || !to)
+        return null;
+    if (from === to)
+        return [];
+    const revs = listRevisions(tenant, scope, { limit: 500 }); // newest first
+    const ti = revs.findIndex((r) => r.id === to || r.commit === to);
+    const fi = revs.findIndex((r) => r.id === from || r.commit === from);
+    if (ti < 0 || fi < 0 || ti > fi)
+        return null;
+    return [...new Set(revs.slice(ti, fi).flatMap((r) => r.paths))].sort();
+}
 /** The most recent revision id for a scope — what a change is attributed
  *  to when nothing more specific (a deployed commit) is on record. */
 export function latestRevisionId(tenant, scope) {

package/dist/src/hooks.js

@@ -30,7 +30,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { spawn } from "node:child_process";
-import matter from "gray-matter";
+import matter from "./matter.js";
 export const HOOK_EVENTS = ["tool.call", "tool.result", "step.start", "step.end"];
 /** Events that decide something before it happens: a failure refuses. */
 const GATES = new Set(["tool.call", "step.start"]);

package/dist/src/insights.d.ts

@@ -0,0 +1,30 @@
+import type { RunRecord } from "./store.ts";
+export type InsightKind = "cache" | "big-result" | "retry-loop" | "timeout";
+export interface Insight {
+    id: string;
+    kind: InsightKind;
+    workspace: string;
+    agent: string;
+    tool?: string;
+    title: string;
+    /** Why it happens, in a sentence. */
+    why: string;
+    fix: string;
+    /** About how many credits it cost in the window; null when not money. */
+    credits: number | null;
+    /** How many steps showed it. */
+    steps: number;
+    /** The newest runs it was seen in, at most 5. */
+    evidence: {
+        workspace: string;
+        runId: string;
+        step: number;
+    }[];
+}
+type Run = RunRecord & {
+    workspace: string;
+};
+export declare function findInsights(runs: Run[], opts?: {
+    minSteps?: number;
+}): Insight[];
+export {};

package/dist/src/insights.js

@@ -0,0 +1,152 @@
+// Insights (FOL-72 step 8): the problems that recur without failing anything,
+// found in the runs with no setup — each with its evidence, what it costs and
+// what to do. The operator's "3 problems, here is why" instead of a list of
+// runs. Pure: the API, the Observe page and `foldrun insights` read the same.
+//
+//   cache      an agent re-reads a big prompt uncached, step after step
+//   big-result a tool's result is large and every later model call sends it again
+//   retry-loop a tool errors again and again inside one step
+//   timeout    steps that use most of their `timeout:` — the next bigger input fails
+//
+// Costs are estimates in credits from the steps' own token costs (a credit
+// is a cent of USD), said as "about".
+/** A cached input token costs about a tenth of a fresh one. */
+const CACHE_SAVING = 0.9;
+/** Characters to tokens, roughly, for text in a conversation. */
+const CHARS_PER_TOKEN = 4;
+const BIG_RESULT = 20_000;
+const stepRefs = (hits) => [...hits].sort((a, b) => b.run.startedAt.localeCompare(a.run.startedAt)).slice(0, 5).map((h) => ({ workspace: h.run.workspace, runId: h.run.id, step: h.index + 1 }));
+const credits = (usd) => Math.round(usd * 100);
+export function findInsights(runs, opts = {}) {
+    const min = opts.minSteps ?? 3;
+    const steps = [];
+    for (const run of runs)
+        run.steps.forEach((s, index) => {
+            if (s.status === "completed" || s.status === "failed")
+                steps.push({ run, index, s });
+        });
+    const out = [];
+    const byAgent = new Map();
+    for (const x of steps) {
+        const k = `${x.run.workspace}\u0000${x.s.agent}`;
+        (byAgent.get(k) ?? byAgent.set(k, []).get(k)).push(x);
+    }
+    for (const [k, list] of byAgent) {
+        const [workspace, agent] = k.split("\u0000");
+        // cache: big inputs, little of it from the cache, on most of its steps.
+        const measured = list.filter((x) => x.s.tokens && x.s.tokens.cacheRead !== undefined && x.s.tokens.input >= 20_000);
+        const poor = measured.filter((x) => (x.s.tokens.cacheRead ?? 0) / x.s.tokens.input < 0.3);
+        if (poor.length >= min && poor.length >= measured.length / 2) {
+            const usd = poor.reduce((n, x) => {
+                const t = x.s.tokens;
+                const uncached = Math.max(0, t.input - (t.cacheRead ?? 0)) / Math.max(1, t.input);
+                return n + (x.s.costUsd ?? 0) * uncached * CACHE_SAVING * 0.5;
+            }, 0);
+            const rate = Math.round((100 * poor.reduce((n, x) => n + (x.s.tokens.cacheRead ?? 0), 0)) / Math.max(1, poor.reduce((n, x) => n + x.s.tokens.input, 0)));
+            out.push({
+                id: `cache/${workspace}/${agent}`,
+                kind: "cache",
+                workspace,
+                agent,
+                title: `${agent} reads its prompt mostly uncached (${rate}% from the cache)`,
+                why: "Each call sends a large prompt that the model's cache rarely serves: something near its start changes from call to call (a date, a run id, a file listing), or the steps are spaced further apart than the cache lasts.",
+                fix: "Keep what changes (dates, ids, the task) at the end of the agent's prompt and the large fixed part first; run its steps closer together.",
+                credits: credits(usd),
+                steps: poor.length,
+                evidence: stepRefs(poor),
+            });
+        }
+        // big-result: a tool's result over 20k characters with calls after it,
+        // each of which sends it again.
+        const big = new Map();
+        for (const x of list) {
+            const callsAfter = (at) => (x.s.calls ?? []).filter((c) => c.at > at).length;
+            const turns = x.s.calls?.length ?? x.s.turns ?? 0;
+            for (const e of x.s.events) {
+                if (e.type !== "tool" || e.ms == null || (e.bytes ?? 0) < BIG_RESULT)
+                    continue;
+                const after = x.s.calls ? callsAfter(e.t) : Math.max(0, turns - 1);
+                if (after < 2)
+                    continue;
+                const tokensResent = ((e.bytes ?? 0) / CHARS_PER_TOKEN) * after;
+                const input = Math.max(1, x.s.tokens?.input ?? 0);
+                const share = Math.min(1, tokensResent / input);
+                const b = big.get(e.text) ?? { hits: [], usd: 0, chars: 0 };
+                if (!b.hits.includes(x))
+                    b.hits.push(x);
+                b.usd += (x.s.costUsd ?? 0) * share;
+                b.chars = Math.max(b.chars, e.bytes ?? 0);
+                big.set(e.text, b);
+            }
+        }
+        for (const [tool, b] of big) {
+            if (b.hits.length < min)
+                continue;
+            out.push({
+                id: `big-result/${workspace}/${agent}/${tool}`,
+                kind: "big-result",
+                workspace,
+                agent,
+                tool,
+                title: `${tool} hands ${agent} results up to ${Math.round(b.chars / 1000)}k characters, sent again on every later call`,
+                why: "A tool result stays in the conversation, so every model call after it pays for it again.",
+                fix: `Have ${tool} return less (filter, a summary, or write the bulk to a file and return the path), or split the step so the big read ends it.`,
+                credits: credits(b.usd),
+                steps: b.hits.length,
+                evidence: stepRefs(b.hits),
+            });
+        }
+        // retry-loop: one tool erroring three or more times in a step.
+        const loops = new Map();
+        for (const x of list) {
+            const errs = new Map();
+            for (const e of x.s.events)
+                if (e.type === "tool" && e.ms != null && e.err)
+                    errs.set(e.text, (errs.get(e.text) ?? 0) + 1);
+            for (const [tool, n] of errs)
+                if (n >= 3)
+                    (loops.get(tool) ?? loops.set(tool, []).get(tool)).push(x);
+        }
+        for (const [tool, hits] of loops) {
+            if (hits.length < Math.min(min, 2))
+                continue;
+            out.push({
+                id: `retry-loop/${workspace}/${agent}/${tool}`,
+                kind: "retry-loop",
+                workspace,
+                agent,
+                tool,
+                title: `${agent} keeps retrying ${tool} after it errors`,
+                why: "The tool fails the same way and the agent tries again instead of stopping — every attempt is a model call and a tool call.",
+                fix: `Read one of the errors (the trace's input / output): fix the tool or its input, or tell ${agent} in its prompt to stop after one failure and say BLOCKED with why.`,
+                credits: credits(hits.reduce((n, x) => n + (x.s.costUsd ?? 0) * 0.3, 0)),
+                steps: hits.length,
+                evidence: stepRefs(hits),
+            });
+        }
+        // timeout: steps that took 80% or more of their timeout.
+        const tight = list.filter((x) => {
+            if (!x.s.timeout || !x.s.startedAt || !x.s.finishedAt)
+                return false;
+            const secs = (Date.parse(x.s.finishedAt) - Date.parse(x.s.startedAt)) / 1000;
+            return secs >= 0.8 * x.s.timeout;
+        });
+        if (tight.length >= Math.min(min, 2)) {
+            const limit = tight[0].s.timeout;
+            out.push({
+                id: `timeout/${workspace}/${agent}`,
+                kind: "timeout",
+                workspace,
+                agent,
+                title: `${agent} uses most of its ${limit}s timeout`,
+                why: "Steps finish just inside their limit; a slightly bigger input or a slow site and they are cut off.",
+                fix: "Raise timeout: on the step, or give the agent less to do per step (each: to fan out, a smaller batch).",
+                credits: null,
+                steps: tight.length,
+                evidence: stepRefs(tight),
+            });
+        }
+    }
+    const order = { "retry-loop": 0, timeout: 1, "big-result": 2, cache: 3 };
+    return out.sort((a, b) => (b.credits ?? -1) - (a.credits ?? -1) || order[a.kind] - order[b.kind]);
+}

package/dist/src/issues.d.ts

@@ -0,0 +1,140 @@
+import type { Outcome } from "./outcome.ts";
+export type IssueKind = "platform" | "failed" | "blocked" | "bad" | "missed";
+export type IssueStatus = "open" | "acknowledged" | "snoozed" | "resolved";
+export type IssueAction = "acknowledge" | "snooze" | "resolve" | "reopen";
+/** As much of a run as an issue needs (the overview's RunLite carries it). */
+export interface IssueRun {
+    workspace: string;
+    id: string;
+    /** The flow's name, or "agent: x" / "eval: y". */
+    what: string;
+    outcome: Outcome;
+    startedAt: string;
+    finishedAt?: string | null;
+    failure?: {
+        agent: string;
+        reason: string;
+    } | null;
+    headline?: string | null;
+    /** The revision the run ran (RunRecord.revision), for "regressed since". */
+    revision?: string | null;
+    /** Not a run: a scheduled fire that started none (FOL-72 step 7). Its
+     *  `startedAt` is when it was due; its id is `missed-<when>`. */
+    missed?: boolean;
+}
+export interface IssueEvent {
+    at: string;
+    /** Who: a person's email, or a key's label. */
+    by: string;
+    action: IssueAction;
+    /** Snoozed until, ISO. */
+    until?: string;
+    /** Or snoozed until it happens this many more times. */
+    untilCount?: number;
+    note?: string;
+}
+/** What people did to one issue. Stored; the rest is derived. */
+export interface IssueState {
+    history: IssueEvent[];
+}
+export interface Issue {
+    id: string;
+    kind: IssueKind;
+    status: IssueStatus;
+    /** The desk; for a platform issue, the newest desk it hit. */
+    workspace: string;
+    /** For a platform issue, every desk it hit. */
+    workspaces: string[];
+    /** The flow (or agent run); for a platform issue, what broke. */
+    what: string;
+    /** The agent the failure was at, for a failed issue. */
+    agent: string | null;
+    /** Why, from the newest run: its failure, or its summary line. */
+    reason: string;
+    /** What to do about it, in plain words. */
+    action: string;
+    /** Since it was last resolved (or ever): when the first and the latest of
+     *  its runs went wrong (their end, else their start), how many. */
+    firstSeen: string;
+    lastSeen: string;
+    count: number;
+    /** The newest runs it covers, newest first, at most 20; a missed
+     *  schedule's are the fires that started nothing (`missed`). */
+    runs: {
+        workspace: string;
+        id: string;
+        at: string;
+        missed?: boolean;
+    }[];
+    /** The newest run of the same flow went fine after the last occurrence. */
+    recoveredAt: string | null;
+    acknowledged: {
+        at: string;
+        by: string;
+    } | null;
+    snoozedUntil: string | null;
+    /** Snoozed until it happens this many more times: how many are left. */
+    snoozedFor: number | null;
+    /** It was resolved before and came back: this episode follows a resolve. */
+    regressed: boolean;
+    /** The revision the first run of this episode ran — "since abc1234". */
+    sinceRevision: string | null;
+    resolved: {
+        at: string;
+        by: string;
+    } | null;
+    history: IssueEvent[];
+}
+/** 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 declare const AUTH_REFUSAL: RegExp;
+/** A failure that is the platform's, not the desk's. */
+export interface PlatformCause {
+    key: string;
+    /** What broke, in the words a person would use. */
+    label: string;
+    /** What to do about it. None of it is editing the desk. */
+    fix: string;
+}
+/** Whether a failure reason is the platform's, and which kind. */
+export declare function platformCause(reason: string | null | undefined): PlatformCause | null;
+/** Which issue a run belongs to, or null when it is not a problem. */
+export declare function issueKeyOf(r: IssueRun): {
+    id: string;
+    kind: IssueKind;
+    agent: string | null;
+    cause: PlatformCause | null;
+} | 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 declare function foldIssues(runs: Iterable<IssueRun>, states: Record<string, IssueState>, now: number, 
+/** `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?: {
+    autoClose?: (workspace: string, what: string) => boolean;
+}): Issue[];
+/** An issue still asking for someone: open or acknowledged, not snoozed or resolved. */
+export declare const isActiveIssue: (i: Issue) => boolean;
+/**
+ * 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 declare function issueDoctor(issue: Pick<Issue, "kind" | "runs">): {
+    workspace: string;
+    runId: string;
+    prompt: string;
+} | null;
+/** Parse "30m", "4h", "1d", "1w" into milliseconds; null if not one. */
+export declare function snoozeMs(s: string): number | 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 declare function applyIssueAction(state: IssueState | null, ev: IssueEvent, now: number): IssueState;