toolroll 0.9.93 → 0.9.95

package/dist/flaky-cli.d.ts

@@ -0,0 +1,60 @@
+import { type FlakyList, type FlakyRow } from "./flaky.js";
+import type { Store } from "./store.js";
+export declare const FLAKY_DESCRIPTORS: readonly [{
+    readonly action: "list";
+    readonly synopsis: "tests with mixed outcomes under recorded conditions (read only)";
+    readonly mutation: "none";
+    readonly takesQuery: false;
+    readonly flags: readonly [{
+        readonly name: "repo";
+        readonly takesValue: true;
+        readonly meaning: "admitted project checkout root";
+    }, {
+        readonly name: "days";
+        readonly takesValue: true;
+        readonly meaning: "how far back to look (default 90)";
+    }, {
+        readonly name: "json";
+        readonly takesValue: false;
+        readonly meaning: "versioned structured response";
+    }, {
+        readonly name: "db";
+        readonly takesValue: true;
+        readonly meaning: "local Toolroll database";
+    }];
+}, {
+    readonly action: "show";
+    readonly synopsis: "one row's history, and the task that would fix it: flaky show <identity> (read only)";
+    readonly mutation: "none";
+    readonly takesQuery: true;
+    readonly flags: readonly [{
+        readonly name: "repo";
+        readonly takesValue: true;
+        readonly meaning: "admitted project checkout root";
+    }, {
+        readonly name: "days";
+        readonly takesValue: true;
+        readonly meaning: "how far back to look (default 90)";
+    }, {
+        readonly name: "json";
+        readonly takesValue: false;
+        readonly meaning: "versioned structured response";
+    }, {
+        readonly name: "db";
+        readonly takesValue: true;
+        readonly meaning: "local Toolroll database";
+    }];
+}];
+export type FlakyCliContext = {
+    store: Store;
+    write: (line: string) => void;
+    json: boolean;
+    now: Date;
+    actor: string | null;
+    repos: readonly string[];
+};
+/** A row's one line of status, the same words the page says. */
+export declare function flakyStatusWords(row: FlakyRow): string;
+/** How much of the window had per-test reporting, said plainly. */
+export declare function flakyCoverageWords(list: FlakyList): string;
+export declare function runFlakyCommand(positional: readonly string[], options: Map<string, string | true>, context: FlakyCliContext): number;

package/dist/flaky-cli.js

@@ -0,0 +1,60 @@
+/** `toolroll flaky list|show`: the flaky tests list from the terminal, read only. Rerunning stays `task regate`; fixing
+ * one is an ordinary task a person approves (`show` prints it). Nothing here starts a model or changes anything. */
+import { envelopeJson } from "./envelope.js";
+import { FLAKY_WINDOW_DAYS, flakyList, flakyShow } from "./flaky.js";
+const flags = [
+    { name: "repo", takesValue: true, meaning: "admitted project checkout root" },
+    { name: "days", takesValue: true, meaning: `how far back to look (default ${FLAKY_WINDOW_DAYS})` },
+    { name: "json", takesValue: false, meaning: "versioned structured response" },
+    { name: "db", takesValue: true, meaning: "local Toolroll database" },
+];
+export const FLAKY_DESCRIPTORS = [
+    { action: "list", synopsis: "tests with mixed outcomes under recorded conditions (read only)", mutation: "none", takesQuery: false, flags },
+    { action: "show", synopsis: "one row's history, and the task that would fix it: flaky show <identity> (read only)", mutation: "none", takesQuery: true, flags },
+];
+const day = (iso) => iso.slice(0, 10);
+/** A row's one line of status, the same words the page says. */
+export function flakyStatusWords(row) {
+    return row.status === "mixed outcomes" ? "Mixed outcomes" : row.status === "no failures since its file changed" ? "No failures since its file changed" : "Not enough recorded history";
+}
+/** How much of the window had per-test reporting, said plainly. */
+export function flakyCoverageWords(list) {
+    const checks = list.reported + list.unreported;
+    return `Reported by ${list.reported} of ${checks} check${checks === 1 ? "" : "s"}${list.unreported === 0 ? "" : `; ${list.unreported} had no per-test reporting`}.`;
+}
+const rowLine = (row) => `${row.name}\n  ${flakyStatusWords(row)} · ${row.observations} in window · last seen ${day(row.lastSeen)} · ${row.conditions.join(", ") || "conditions not recorded"} · ${row.hardFailures} hard failure${row.hardFailures === 1 ? "" : "s"} · ${row.sources.join(", ") || "no source recorded"}${row.fileChanged === null ? "" : ` · file changed ${day(row.fileChanged)}`}\n  ${row.key}`;
+export function runFlakyCommand(positional, options, context) {
+    const action = positional[0];
+    const command = action ? `flaky ${action}` : "flaky";
+    const fail = (reason, message) => { context.write(context.json ? envelopeJson({ ok: false, command, reason, message }) : message); return reason === "usage" ? 2 : 1; };
+    const ok = (result, lines) => { context.write(context.json ? envelopeJson({ ok: true, command, ...result }) : lines.join("\n")); return 0; };
+    if (!FLAKY_DESCRIPTORS.some(one => one.action === action))
+        return fail("usage", "Use flaky list | show <identity> [--repo PATH] [--days N].");
+    if (context.actor === null)
+        return fail("unauthenticated", "Sign in first: the remembered local login drives flaky commands.");
+    const given = options.get("repo");
+    const repo = typeof given === "string" ? given : context.repos.length === 1 ? context.repos[0] : null;
+    if (repo === null)
+        return fail("usage", "Use --repo with the project checkout root.");
+    if (!context.repos.includes(repo))
+        return fail("not-found", "That project is outside your access.");
+    const daysGiven = options.get("days");
+    const days = typeof daysGiven === "string" ? Number(daysGiven) : FLAKY_WINDOW_DAYS;
+    if (!Number.isSafeInteger(days) || days < 1 || days > 730)
+        return fail("usage", "--days takes a whole number from 1 to 730.");
+    if (action === "list") {
+        const list = flakyList(context.store, repo, context.now, days);
+        const history = list.complete ? [] : [`Not enough recorded history: test results are kept for 180 days, so ${days} days can't be counted in full.`];
+        if (list.rows.length === 0)
+            return ok({ list }, [...history, ...(list.complete ? ["No mixed outcomes recorded."] : []), flakyCoverageWords(list)]);
+        return ok({ list }, ["Mixed outcomes under recorded conditions", ...history, ...list.rows.map(rowLine), flakyCoverageWords(list), ...(list.notPaired === 0 ? [] : [`${list.notPaired} GitHub attempt pairing${list.notPaired === 1 ? "" : "s"} not paired.`]), "Not recorded: network, other processes, time of day."]);
+    }
+    const key = positional.slice(1).join(" ").trim();
+    if (key === "")
+        return fail("usage", "flaky show <identity from flaky list>");
+    const found = flakyShow(context.store, repo, key, context.now, days);
+    if (found === null)
+        return fail("not-found", "Nothing is recorded for that test in this project.");
+    return ok(found, [rowLine(found.row), ...found.history.map(one => `  ${day(one.at)} ${one.failed} failed, ${one.passed} passed · ${one.commit ?? "commit not recorded"} · ${one.conditions}`),
+        `Make a task to fix it: toolroll task add "${found.fix.title.replaceAll('"', "'")}" --goal "${found.fix.goal.replaceAll('"', "'")}" --repo ${repo}`]);
+}

package/dist/flaky.d.ts

@@ -1,12 +1,3 @@
-/**
- * Mixed outcomes under recorded conditions (docs/plans/learning-loops.md, "Flaky tests"): advisory only. Nothing here
- * changes a check's outcome, a verdict, an approval or a rerun; rerunning stays a person's `task regate`.
- *
- * Slice 1 holds the tracked identities an observation adds (`learning_watch`, reason `observation`): every Full check
- * with a handshake asks about them for 90 days (check-facts.ts learnRequestFor). Lesson notes (lesson-notes.ts) add
- * their own. This module and lesson-notes.ts are the only writers of `learning_watch`; release-auto's learning scan
- * (eval-hooks.ts learningWriteProblem) needs a person for any other. A policy path (release-auto.ts EVAL_POLICY).
- */
 import type { Store } from "./store.js";
 /** Track an identity a local observation named (one row per observation; first write wins, never rewritten). */
 export declare function watchObservation(store: Store, input: {
@@ -15,3 +6,78 @@ export declare function watchObservation(store: Store, input: {
     observation: number;
     now: Date;
 }): boolean;
+/** How far back the list looks, how long the pruned rows are kept, and how many runs clear a row (the plan's defaults). */
+export declare const FLAKY_WINDOW_DAYS = 90;
+export declare const FLAKY_RETAIN_DAYS = 180;
+export declare const FLAKY_CLEAR_RUNS = 20;
+/** What can be observed at all: a test case, a journey or its group, or a file, never `part:`, `upgrade:`, `check` or
+ * `unexplained`, and never a real-model journey (a model's behaviour isn't a test's flakiness). */
+export declare function observableIdentity(identity: string): boolean;
+/**
+ * Every observation one settled check adds, in the transaction that records its results (check-facts.ts): an in-check
+ * retry, and each identity that failed in one check and explicitly passed in another with equal tree, command, access,
+ * harness and conditions. A `file:` identity is observed only as "failed, then the whole check passed", and only when
+ * no case in that file names the failure. Idempotent: racing dispositions on one pair leave one row.
+ */
+export declare function recordObservations(store: Store, runId: number, now: Date): number[];
+/** The storage sweep's own step: observations older than the retention window go; nothing else deletes them. */
+export declare function pruneObservations(store: Store, now: Date): number;
+export type FlakyStatus = "mixed outcomes" | "no failures since its file changed" | "not enough recorded history";
+export type FlakyRow = {
+    /** The stable handle `flaky show` takes: the identity, or `github:<lane>`. */
+    key: string;
+    kind: "test" | "file" | "lane";
+    /** What the row says, as recorded: untrusted test text, escaped wherever it's shown. */
+    name: string;
+    observations: number;
+    lastSeen: string;
+    /** `<platform>-<arch>-node<major>`, or GitHub for a lane. */
+    conditions: string[];
+    /** Failures under recorded conditions that have no recorded pass. */
+    hardFailures: number;
+    sources: string[];
+    /** When the test's file last changed, as far as the recorded checks show; null when they don't. */
+    fileChanged: string | null;
+    status: FlakyStatus;
+};
+export type FlakyList = {
+    repo: string;
+    days: number;
+    rows: FlakyRow[];
+    /** False when the window reaches past what is kept, so a count there could be short. */
+    complete: boolean;
+    /** CI pairings refused, and how many checks in the window had no per-test reporting. */
+    notPaired: number;
+    unreported: number;
+    reported: number;
+};
+export type FlakyObservation = {
+    kind: "regate" | "same-tree" | "in-check-retry" | "github";
+    at: string;
+    failed: string;
+    passed: string;
+    commit: string | null;
+    conditions: string;
+};
+/** The test file an identity names, when it names one. */
+export declare function identityFile(identity: string): string | null;
+/** A readable name: `<file> › <test>`; a journey's group and name; a file with its limit said. */
+export declare function identityWords(identity: string): string;
+/** Every row for a project: reads only. `days` past the kept window is answered with `complete: false`, never a zero. */
+export declare function flakyList(store: Store, repo: string, now: Date, days?: number): FlakyList;
+/** How many rows the list has now, cheaply: no tree is read. */
+export declare function flakyCount(store: Store, repo: string, now: Date): number;
+/** One row's history, newest first: each observation with both checks (or the CI run and attempts). Null: no such row. */
+export declare function flakyShow(store: Store, repo: string, key: string, now: Date, days?: number): {
+    row: FlakyRow;
+    history: FlakyObservation[];
+    fix: {
+        title: string;
+        goal: string;
+    };
+} | null;
+/** The ordinary task "Make a task to fix it" files; a person approves it as usual. Never to skip or delete the test. */
+export declare function fixTaskOf(row: Pick<FlakyRow, "key" | "name" | "observations" | "conditions" | "kind">): {
+    title: string;
+    goal: string;
+};

package/dist/flaky.js

@@ -1,3 +1,19 @@
+/**
+ * Mixed outcomes under recorded conditions (docs/plans/learning-loops.md, "Flaky tests"): advisory only. Nothing here
+ * changes a check's outcome, a verdict, an approval or a rerun; rerunning stays a person's `task regate`.
+ *
+ * Observations are written here, in the transaction that records a check's results (recordObservations). Each adds a
+ * tracked identity (`learning_watch`, reason `observation`): every Full check with a handshake asks about it for 90
+ * days (check-facts.ts learnRequestFor). Lesson notes (lesson-notes.ts) add their own. This module and lesson-notes.ts
+ * are the only writers of `learning_watch`, and this one of `local_observation`; release-auto's learning scan
+ * (eval-hooks.ts learningWriteProblem) needs a person for any other. A policy path (release-auto.ts EVAL_POLICY).
+ *
+ * The list reads only. An infrastructure-class run is never an observation: a run's class is stamped after its check,
+ * so recording skips the runs already stamped and every read skips the rest.
+ */
+import { projectGitDir } from "./check-report.js";
+import { verifiedBlobs } from "./commit-extract.js";
+import { ciNotPaired, ciRepositoriesOf } from "./flaky-ci.js";
 /** Track an identity a local observation named (one row per observation; first write wins, never rewritten). */
 export function watchObservation(store, input) {
     if (input.repo.trim() === "" || input.identity.length < 1 || input.identity.length > 2600 || !Number.isSafeInteger(input.observation) || input.observation < 1) {
@@ -7,3 +23,242 @@ export function watchObservation(store, input) {
     ON CONFLICT (repo, identity, reason, source_ref) DO NOTHING`).run(input.repo, input.identity, `observation:${input.observation}`, input.now.toISOString());
     return Number(added.changes) === 1;
 }
+// ---- local observations --------------------------------------------------------------------------------------------
+/** How far back the list looks, how long the pruned rows are kept, and how many runs clear a row (the plan's defaults). */
+export const FLAKY_WINDOW_DAYS = 90;
+export const FLAKY_RETAIN_DAYS = 180;
+export const FLAKY_CLEAR_RUNS = 20;
+const DAY_MS = 86_400_000;
+/** Twin checks one settled check is compared with, observations it writes, and rows the list and a history read. */
+const TWINS_MAX = 50;
+const OBSERVED_MAX = 500;
+const ROWS_MAX = 200;
+const HISTORY_MAX = 100;
+/** Distinct trees one read of the list opens: past this, the rest of a row's status stays "mixed outcomes". */
+const TREES_MAX = 40;
+/** What can be observed at all: a test case, a journey or its group, or a file, never `part:`, `upgrade:`, `check` or
+ * `unexplained`, and never a real-model journey (a model's behaviour isn't a test's flakiness). */
+export function observableIdentity(identity) {
+    if (/^(?:journey|group):[^:]*:real(?::|$)/.test(identity))
+        return false;
+    return /^(?:unit|journey|group|file):./.test(identity);
+}
+const fileLevel = (identity) => identity.startsWith("file:");
+/** The explicit sources (docs/plans/learning-loops.md, "Explicit execution evidence"). */
+const EXPLICIT = "('report','learn')";
+/** A tree's facts as comparisons need them, or null (nothing comparable was recorded). */
+function comparableFact(store, runId) {
+    const row = store.handle.prepare("SELECT repo, task_ref, head, tree, command_digest, access, harness_digest, conditions_digest, purpose FROM check_fact WHERE run = ?").get(runId);
+    if (row === undefined || row["repo"] == null || row["tree"] == null || row["conditions_digest"] == null)
+        return null;
+    const text = (key) => row[key] == null ? null : String(row[key]);
+    return { repo: String(row["repo"]), taskRef: Number(row["task_ref"]), head: text("head"), tree: String(row["tree"]), commandDigest: text("command_digest"), access: text("access"), harness: text("harness_digest"), digest: String(row["conditions_digest"]), purpose: String(row["purpose"]) };
+}
+const infrastructure = (store, runId) => store.handle.prepare("SELECT 1 FROM run WHERE id = ? AND exec_class = 'infrastructure'").get(runId) !== undefined;
+/**
+ * Every observation one settled check adds, in the transaction that records its results (check-facts.ts): an in-check
+ * retry, and each identity that failed in one check and explicitly passed in another with equal tree, command, access,
+ * harness and conditions. A `file:` identity is observed only as "failed, then the whole check passed", and only when
+ * no case in that file names the failure. Idempotent: racing dispositions on one pair leave one row.
+ */
+export function recordObservations(store, runId, now) {
+    const fact = comparableFact(store, runId);
+    if (fact === null || infrastructure(store, runId))
+        return [];
+    const at = now.toISOString();
+    const added = [];
+    const insert = store.handle.prepare(`INSERT INTO local_observation (repo, identity, failed_run, passed_run, tree, conditions_digest, kind, observed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (identity, failed_run, passed_run) DO NOTHING`);
+    const observe = (identity, failed, passed, kind) => {
+        if (added.length >= OBSERVED_MAX || !observableIdentity(identity))
+            return;
+        const done = insert.run(fact.repo, identity, failed, passed, fact.tree, fact.digest, kind, at);
+        if (Number(done.changes) !== 1)
+            return;
+        const id = Number(done.lastInsertRowid);
+        added.push(id);
+        watchObservation(store, { repo: fact.repo, identity, observation: id, now });
+    };
+    // A nightly's in-run reruns are never observations; a retry inside any other check is.
+    if (fact.purpose !== "nightly") {
+        for (const row of store.handle.prepare(`SELECT DISTINCT identity FROM check_result WHERE run = ? AND state = 'passed-on-retry' AND source IN ${EXPLICIT}`).all(runId)) {
+            const identity = String(row["identity"]);
+            if (!fileLevel(identity))
+                observe(identity, runId, runId, "in-check-retry");
+        }
+    }
+    const twins = store.handle.prepare(`SELECT f.run, f.task_ref, f.head FROM check_fact f JOIN run r ON r.id = f.run
+    WHERE f.repo = ? AND f.tree = ? AND f.conditions_digest = ? AND f.command_digest IS ? AND f.access IS ? AND f.harness_digest IS ? AND f.run <> ?
+      AND (r.exec_class IS NULL OR r.exec_class <> 'infrastructure') ORDER BY f.run DESC LIMIT ?`).all(fact.repo, fact.tree, fact.digest, fact.commandDigest, fact.access, fact.harness, runId, TWINS_MAX);
+    const mixed = store.handle.prepare(`SELECT DISTINCT a.identity FROM check_result a JOIN check_result b ON b.identity = a.identity AND b.run = ? AND b.state = 'passed' AND b.source IN ${EXPLICIT}
+    WHERE a.run = ? AND a.state = 'failed' AND a.source IN ${EXPLICIT}`);
+    const received = (run, state) => store.handle.prepare("SELECT 1 FROM check_result WHERE run = ? AND identity = 'check' AND source = 'receipt' AND state = ?").get(run, state) !== undefined;
+    for (const twin of twins) {
+        const other = Number(twin["run"]);
+        const kind = Number(twin["task_ref"]) === fact.taskRef && (twin["head"] == null ? null : String(twin["head"])) === fact.head ? "regate" : "same-tree";
+        for (const row of mixed.all(runId, other))
+            observe(String(row["identity"]), other, runId, kind);
+        for (const row of mixed.all(other, runId))
+            observe(String(row["identity"]), runId, other, kind);
+        // File level: an earlier check failed in the file, this later one passed whole.
+        if (other < runId && received(runId, "passed") && received(other, "failed")) {
+            const failed = store.handle.prepare("SELECT identity, source FROM check_result WHERE run = ? AND state = 'failed'").all(other).map(row => String(row["identity"]));
+            for (const identity of new Set(failed.filter(fileLevel))) {
+                const prefix = `unit:${identity.slice("file:".length)}::`;
+                if (!failed.some(one => one.startsWith(prefix)))
+                    observe(identity, other, runId, kind);
+            }
+        }
+    }
+    return added;
+}
+/** The storage sweep's own step: observations older than the retention window go; nothing else deletes them. */
+export function pruneObservations(store, now) {
+    const cut = new Date(now.getTime() - FLAKY_RETAIN_DAYS * DAY_MS).toISOString();
+    return Number(store.handle.prepare("DELETE FROM local_observation WHERE observed_at < ?").run(cut).changes);
+}
+/** The test file an identity names, when it names one. */
+export function identityFile(identity) {
+    const unit = /^unit:(.+?)::/.exec(identity);
+    if (unit !== null)
+        return unit[1];
+    return identity.startsWith("file:") ? identity.slice("file:".length) : null;
+}
+/** A readable name: `<file> › <test>`; a journey's group and name; a file with its limit said. */
+export function identityWords(identity) {
+    const unit = /^unit:(.+?)::(.*)$/s.exec(identity);
+    if (unit !== null)
+        return `${unit[1]} › ${unit[2]}`;
+    const journey = /^journey:([^:]*):([^:]*):(.+?)::(.*)$/s.exec(identity);
+    if (journey !== null)
+        return `${journey[1]} journey ${journey[3]} › ${journey[4]}`;
+    const group = /^group:([^:]*):([^:]*):(.*)$/s.exec(identity);
+    if (group !== null)
+        return `${group[1]} journeys ${group[3]}`;
+    return fileLevel(identity) ? `${identity.slice("file:".length)} (file-level, not confirmed per test)` : identity;
+}
+const SOURCE_WORDS = { report: "Test report", learn: "Test report", log: "Check log", receipt: "Check result" };
+/** Whether results older than the kept window were pruned for this project. */
+function prunedBefore(store, repo, now) {
+    const cut = new Date(now.getTime() - FLAKY_RETAIN_DAYS * DAY_MS).toISOString();
+    return store.handle.prepare("SELECT 1 FROM check_fact WHERE repo = ? AND recorded_at < ? LIMIT 1").get(repo, cut) !== undefined;
+}
+/** Each tree's blob ids for the given files, read through verified objects, once per tree, within a budget. */
+function blobReader(repo, files) {
+    const gitDir = projectGitDir(repo);
+    const seen = new Map();
+    return (tree, file) => {
+        if (gitDir === null)
+            return undefined;
+        let read = seen.get(tree);
+        if (read === undefined) {
+            if (seen.size >= TREES_MAX)
+                return undefined;
+            try {
+                const blobs = verifiedBlobs(gitDir, tree, files);
+                read = blobs.ok ? new Map([...blobs.value].map(([path, one]) => [path, one.id])) : null;
+            }
+            catch {
+                read = null;
+            }
+            seen.set(tree, read);
+        }
+        return read === null ? undefined : read.get(file) ?? null;
+    };
+}
+/** What a row's recorded runs say since its file changed. `undefined` from the reader means a tree couldn't be read:
+ * the walk stops there and claims nothing. */
+function statusOf(store, repo, identity, blobAt, pruned) {
+    const file = identityFile(identity);
+    if (file === null || fileLevel(identity))
+        return { status: "mixed outcomes", fileChanged: null };
+    const rows = store.handle.prepare(`SELECT f.run, f.tree, f.recorded_at, MAX(CASE WHEN r.state IN ('failed','passed-on-retry') THEN 1 ELSE 0 END) AS failed, MAX(CASE WHEN r.state = 'passed' THEN 1 ELSE 0 END) AS passed
+    FROM check_result r JOIN check_fact f ON f.run = r.run WHERE f.repo = ? AND r.identity = ? AND r.source IN ${EXPLICIT} AND f.tree IS NOT NULL GROUP BY f.run ORDER BY f.run DESC LIMIT 200`).all(repo, identity);
+    if (rows.length === 0)
+        return { status: "mixed outcomes", fileChanged: null };
+    const newest = blobAt(String(rows[0]["tree"]), file);
+    if (newest === undefined)
+        return { status: "mixed outcomes", fileChanged: null };
+    let clean = 0, boundary = false, failedSince = false, earliest = null;
+    for (const row of rows) {
+        const here = blobAt(String(row["tree"]), file);
+        if (here === undefined)
+            return { status: "mixed outcomes", fileChanged: null };
+        if (here !== newest) {
+            boundary = true;
+            break;
+        }
+        earliest = String(row["recorded_at"]);
+        if (Number(row["failed"]) === 1) {
+            failedSince = true;
+            continue;
+        }
+        if (Number(row["passed"]) === 1)
+            clean++;
+    }
+    const fileChanged = boundary ? earliest : null;
+    if (failedSince)
+        return { status: "mixed outcomes", fileChanged };
+    if (clean >= FLAKY_CLEAR_RUNS)
+        return { status: "no failures since its file changed", fileChanged };
+    // Too few passes, and the file's change is older than the results kept: there's no telling, and no zero is shown.
+    return { status: !boundary && pruned ? "not enough recorded history" : "mixed outcomes", fileChanged };
+}
+/** Every row for a project: reads only. `days` past the kept window is answered with `complete: false`, never a zero. */
+export function flakyList(store, repo, now, days = FLAKY_WINDOW_DAYS) {
+    const span = Number.isSafeInteger(days) && days >= 1 && days <= 730 ? days : FLAKY_WINDOW_DAYS;
+    const since = new Date(now.getTime() - span * DAY_MS).toISOString();
+    const pruned = prunedBefore(store, repo, now);
+    const rows = store.handle.prepare(`SELECT o.identity, COUNT(DISTINCT o.tree || ':' || o.conditions_digest) AS observations, MAX(o.observed_at) AS last_seen
+    FROM local_observation o JOIN run a ON a.id = o.failed_run JOIN run b ON b.id = o.passed_run
+    WHERE o.repo = ? AND o.observed_at >= ? AND (a.exec_class IS NULL OR a.exec_class <> 'infrastructure') AND (b.exec_class IS NULL OR b.exec_class <> 'infrastructure')
+    GROUP BY o.identity ORDER BY last_seen DESC, o.identity LIMIT ?`).all(repo, since, ROWS_MAX);
+    const identities = rows.map(row => String(row["identity"]));
+    const blobAt = blobReader(repo, [...new Set(identities.flatMap(one => identityFile(one) ?? []))]);
+    const local = rows.map(row => {
+        const identity = String(row["identity"]);
+        const conditions = store.handle.prepare(`SELECT DISTINCT f.conditions_class FROM local_observation o JOIN check_fact f ON f.run = o.failed_run WHERE o.repo = ? AND o.identity = ? AND o.observed_at >= ? AND f.conditions_class IS NOT NULL ORDER BY 1`).all(repo, identity, since).map(one => String(one["conditions_class"]));
+        const sources = store.handle.prepare(`SELECT DISTINCT r.source FROM local_observation o JOIN check_result r ON r.identity = o.identity AND r.run IN (o.failed_run, o.passed_run) WHERE o.repo = ? AND o.identity = ? AND o.observed_at >= ? ORDER BY 1`).all(repo, identity, since).map(one => SOURCE_WORDS[String(one["source"])] ?? String(one["source"]));
+        const hard = store.handle.prepare(`SELECT COUNT(DISTINCT r.run) AS n FROM check_result r JOIN check_fact f ON f.run = r.run WHERE f.repo = ? AND r.identity = ? AND r.state = 'failed' AND f.recorded_at >= ? AND f.tree IS NOT NULL
+      AND NOT EXISTS (SELECT 1 FROM check_result p JOIN check_fact g ON g.run = p.run WHERE p.identity = r.identity AND p.state IN ('passed','passed-on-retry') AND g.repo = f.repo AND g.tree = f.tree AND g.conditions_digest = f.conditions_digest)`).get(repo, identity, since);
+        const read = statusOf(store, repo, identity, blobAt, pruned);
+        return { key: identity, kind: fileLevel(identity) ? "file" : "test", name: identityWords(identity), observations: Number(row["observations"]), lastSeen: String(row["last_seen"]),
+            conditions, hardFailures: Number(hard?.["n"] ?? 0), sources: [...new Set(sources)], fileChanged: read.fileChanged, status: read.status };
+    });
+    const lanes = store.handle.prepare(`SELECT lane_id, MAX(lane_name) AS lane_name, COUNT(*) AS observations, MAX(observed_at) AS last_seen FROM ci_flaky_observation WHERE repo = ? AND observed_at >= ? GROUP BY lane_id ORDER BY last_seen DESC, lane_id LIMIT ?`).all(repo, since, ROWS_MAX);
+    const ci = lanes.map(row => ({ key: `github:${String(row["lane_id"])}`, kind: "lane", name: `${String(row["lane_name"])} (GitHub CI)`, observations: Number(row["observations"]), lastSeen: String(row["last_seen"]),
+        conditions: ["GitHub CI"], hardFailures: 0, sources: ["GitHub"], fileChanged: null, status: "mixed outcomes" }));
+    const checks = store.handle.prepare("SELECT COUNT(*) AS n, SUM(CASE WHEN EXISTS (SELECT 1 FROM check_result r WHERE r.run = f.run AND r.source IN ('report','learn')) THEN 1 ELSE 0 END) AS reported FROM check_fact f WHERE f.repo = ? AND f.recorded_at >= ?").get(repo, since);
+    return { repo, days: span, rows: [...local, ...ci].sort((a, b) => b.lastSeen.localeCompare(a.lastSeen) || a.key.localeCompare(b.key)),
+        complete: !(span > FLAKY_RETAIN_DAYS && pruned), notPaired: ciNotPaired(store, ciRepositoriesOf(store, repo), since), reported: Number(checks?.["reported"] ?? 0), unreported: Number(checks?.["n"] ?? 0) - Number(checks?.["reported"] ?? 0) };
+}
+/** How many rows the list has now, cheaply: no tree is read. */
+export function flakyCount(store, repo, now) {
+    const since = new Date(now.getTime() - FLAKY_WINDOW_DAYS * DAY_MS).toISOString();
+    return Number(store.handle.prepare("SELECT (SELECT COUNT(DISTINCT identity) FROM local_observation WHERE repo = ? AND observed_at >= ?) + (SELECT COUNT(DISTINCT lane_id) FROM ci_flaky_observation WHERE repo = ? AND observed_at >= ?) AS n").get(repo, since, repo, since)?.["n"] ?? 0);
+}
+/** One row's history, newest first: each observation with both checks (or the CI run and attempts). Null: no such row. */
+export function flakyShow(store, repo, key, now, days = FLAKY_RETAIN_DAYS) {
+    const row = flakyList(store, repo, now, Math.max(days, FLAKY_WINDOW_DAYS)).rows.find(one => one.key === key);
+    if (row === undefined)
+        return null;
+    const history = row.kind === "lane"
+        ? store.handle.prepare(`SELECT workflow_run_id, head_sha, failed_attempt, failed_conclusion, passed_attempt, passed_conclusion, observed_at FROM ci_flaky_observation WHERE repo = ? AND lane_id = ? ORDER BY observed_at DESC, id DESC LIMIT ?`)
+            .all(repo, key.slice("github:".length), HISTORY_MAX).map(one => ({ kind: "github", at: String(one["observed_at"]), failed: `GitHub #${String(one["workflow_run_id"])} try ${String(one["failed_attempt"])}`,
+            passed: `try ${String(one["passed_attempt"])}`, commit: String(one["head_sha"]).slice(0, 7), conditions: "GitHub CI" }))
+        : store.handle.prepare(`SELECT o.kind, o.failed_run, o.passed_run, o.observed_at, f.head, f.conditions_class FROM local_observation o LEFT JOIN check_fact f ON f.run = o.failed_run WHERE o.repo = ? AND o.identity = ? ORDER BY o.observed_at DESC, o.id DESC LIMIT ?`)
+            .all(repo, key, HISTORY_MAX).map(one => ({ kind: String(one["kind"]), at: String(one["observed_at"]), failed: `build #${String(one["failed_run"])}`, passed: `build #${String(one["passed_run"])}`,
+            commit: one["head"] == null ? null : String(one["head"]).slice(0, 7), conditions: one["conditions_class"] == null ? "not recorded" : String(one["conditions_class"]) }));
+    return { row, history, fix: fixTaskOf(row) };
+}
+/** The ordinary task "Make a task to fix it" files; a person approves it as usual. Never to skip or delete the test. */
+export function fixTaskOf(row) {
+    // eslint-disable-next-line no-control-regex
+    const name = row.name.replace(/[\u0000-\u001f\u007f]+/g, " ").slice(0, 300);
+    const short = name.length > 72 ? `${name.slice(0, 71)}…` : name;
+    return { title: `Make this test reliable: ${short}`, goal: [
+            `Toolroll recorded mixed outcomes under recorded conditions for ${name}: ${row.observations} time${row.observations === 1 ? "" : "s"} it both failed and passed with the same code, command and recorded environment (${row.conditions.join(", ") || "not recorded"}).`,
+            row.kind === "lane" ? "It is a GitHub CI job, so the failing test isn't named: read that job's log to find it." : "",
+            "Find out why and make the test reliable. Never skip, delete or loosen the test, and don't add retries to hide it.",
+        ].filter(Boolean).join(" ") };
+}

package/dist/fleet-schema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The tables behind what happens to a result after its agent finishes (docs/plans/fleet-follow-through.md). v155 adds
+ * them and changes no saved row, so the updater's history check needs no rule for it.
+ *
+ * Every reader of these tables goes through `readingFleet`: a deploy reads with the candidate's code over the installed
+ * runtime's file before this version's migration has run (as buildReviewOf does), and a missing table is simply nothing
+ * to show. Writers run only in a process whose Store opened, and so migrated, the file.
+ */
+/** Who a finding's words are from. 'lead' (the lead drafted, a person confirmed) came after the first v155 builds, which
+ * this build's v155 step widens in place (store.ts widenFindingSources). */
+export declare const FINDING_SOURCES = "CHECK (source IN ('build-review', 'person', 'lead', 'check-failure'))";
+export declare const FINDING_SOURCES_BEFORE_LEAD = "CHECK (source IN ('build-review', 'person', 'check-failure'))";
+export declare const V155_SCHEMA = "\n-- A finding sent to the task that owns the code. It belongs to the task family, so a revision or repair inherits it.\n-- summary, action and excerpt can hold model output or repository text: they are data everywhere they are read.\nCREATE TABLE IF NOT EXISTS finding (\n  id            INTEGER PRIMARY KEY AUTOINCREMENT,\n  family_root   TEXT NOT NULL,\n  task_id       TEXT NOT NULL,\n  repo          TEXT,\n  source        TEXT NOT NULL CHECK (source IN ('build-review', 'person', 'lead', 'check-failure')),\n  source_key    TEXT UNIQUE,\n  source_run    INTEGER,\n  severity      TEXT CHECK (severity IS NULL OR severity IN ('HIGH', 'MEDIUM', 'LOW')),\n  file          TEXT,\n  line          INTEGER,\n  summary       TEXT NOT NULL,\n  action        TEXT NOT NULL,\n  excerpt       TEXT,\n  revision      TEXT,\n  state         TEXT NOT NULL DEFAULT 'open' CHECK (state IN ('open', 'accepted', 'rejected', 'with-person', 'closed')),\n  rounds        INTEGER NOT NULL DEFAULT 1,\n  sent_by       TEXT NOT NULL,\n  sent_at       TEXT NOT NULL,\n  delivered_run INTEGER,\n  delivered_how TEXT CHECK (delivered_how IS NULL OR delivered_how IN ('mailbox', 'brief')),\n  delivered_at  TEXT,\n  read_at       TEXT,\n  closed_by     TEXT,\n  closed_note   TEXT,\n  closed_at     TEXT\n);\nCREATE INDEX IF NOT EXISTS finding_family ON finding (family_root, state);\n-- What the owner answered. 'saved' until the attempt that wrote it settles: then 'counted', or 'refused' with the reason\n-- (an accepted answer on a run that changed nothing; a rejection that names no file in the code).\nCREATE TABLE IF NOT EXISTS finding_answer (\n  id        INTEGER PRIMARY KEY AUTOINCREMENT,\n  finding   INTEGER NOT NULL REFERENCES finding(id) ON DELETE CASCADE,\n  round     INTEGER NOT NULL,\n  run       INTEGER NOT NULL,\n  answer    TEXT NOT NULL CHECK (answer IN ('accepted', 'rejected')),\n  detail    TEXT NOT NULL,\n  file      TEXT,\n  line      INTEGER,\n  revision  TEXT,\n  state     TEXT NOT NULL DEFAULT 'saved' CHECK (state IN ('saved', 'counted', 'refused')),\n  problem   TEXT,\n  at        TEXT NOT NULL,\n  UNIQUE (finding, round, run)\n);\n-- One failed check on one revision of one task family: the UNIQUE key is what stops a second repair of the same failure.\n-- attempt is the repair ledger's (repair_chain) attempt this row drafted, when it drafted one.\nCREATE TABLE IF NOT EXISTS check_repair (\n  id           INTEGER PRIMARY KEY AUTOINCREMENT,\n  family_root  TEXT NOT NULL,\n  owner_task   TEXT NOT NULL,\n  repo         TEXT NOT NULL,\n  revision     TEXT NOT NULL,\n  failure_key  TEXT NOT NULL,\n  source_run   INTEGER NOT NULL,\n  state        TEXT NOT NULL CHECK (state IN ('waiting', 'repairing', 'rerunning', 'with-person', 'parked', 'fixed', 'closed')),\n  why          TEXT NOT NULL,\n  repair_task  TEXT,\n  attempt      INTEGER,\n  created_at   TEXT NOT NULL,\n  updated_at   TEXT NOT NULL,\n  UNIQUE (family_root, revision, failure_key)\n);\nCREATE INDEX IF NOT EXISTS check_repair_state ON check_repair (repo, state);\n-- A failing result saved before a change. The after side is never stored: it is read from the task's latest results,\n-- so a newer commit reads as out of date on its own.\nCREATE TABLE IF NOT EXISTS evidence_pair (\n  id             INTEGER PRIMARY KEY AUTOINCREMENT,\n  family_root    TEXT NOT NULL,\n  repo           TEXT,\n  before_run     INTEGER NOT NULL,\n  before_head    TEXT NOT NULL,\n  receipt_digest TEXT NOT NULL,\n  command_digest TEXT,\n  saved_by       TEXT NOT NULL,\n  saved_at       TEXT NOT NULL,\n  UNIQUE (family_root, before_run)\n);\n-- A bug fix's optional failing test first: asked for on the family; the agent's report beside it, shown as its own report.\nCREATE TABLE IF NOT EXISTS failing_first (\n  family_root TEXT PRIMARY KEY,\n  repo        TEXT,\n  asked_by    TEXT NOT NULL,\n  asked_at    TEXT NOT NULL,\n  report_run  INTEGER,\n  test        TEXT,\n  output      TEXT,\n  reported_at TEXT\n);\n-- What a provider said when an attempt failed, kept as data for a person. Nothing reads it to route work.\nCREATE TABLE IF NOT EXISTS provider_capture (\n  id          INTEGER PRIMARY KEY AUTOINCREMENT,\n  run         INTEGER NOT NULL UNIQUE,\n  repo        TEXT,\n  provider    TEXT NOT NULL,\n  model       TEXT,\n  auth_mode   TEXT,\n  exit_code   INTEGER,\n  code        TEXT,\n  text        TEXT NOT NULL,\n  hint        INTEGER NOT NULL DEFAULT 0 CHECK (hint IN (0, 1)),\n  label       TEXT CHECK (label IS NULL OR label IN ('exhausted', 'not-exhausted')),\n  labelled_by TEXT,\n  at          TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS provider_capture_provider ON provider_capture (provider, id);\n";
+export declare const V155_TABLES: readonly ["finding", "finding_answer", "check_repair", "evidence_pair", "failing_first", "provider_capture"];
+export declare const V155_STEPS: readonly ["follow-through-tables", "finding-sources"];
+/** One read, or `fallback` when the file predates v155. Any other error is real and goes on. */
+export declare function readingFleet<T>(read: () => T, fallback: T): T;

package/dist/fleet-schema.js

@@ -0,0 +1,135 @@
+/**
+ * The tables behind what happens to a result after its agent finishes (docs/plans/fleet-follow-through.md). v155 adds
+ * them and changes no saved row, so the updater's history check needs no rule for it.
+ *
+ * Every reader of these tables goes through `readingFleet`: a deploy reads with the candidate's code over the installed
+ * runtime's file before this version's migration has run (as buildReviewOf does), and a missing table is simply nothing
+ * to show. Writers run only in a process whose Store opened, and so migrated, the file.
+ */
+/** Who a finding's words are from. 'lead' (the lead drafted, a person confirmed) came after the first v155 builds, which
+ * this build's v155 step widens in place (store.ts widenFindingSources). */
+export const FINDING_SOURCES = "CHECK (source IN ('build-review', 'person', 'lead', 'check-failure'))";
+export const FINDING_SOURCES_BEFORE_LEAD = "CHECK (source IN ('build-review', 'person', 'check-failure'))";
+export const V155_SCHEMA = `
+-- A finding sent to the task that owns the code. It belongs to the task family, so a revision or repair inherits it.
+-- summary, action and excerpt can hold model output or repository text: they are data everywhere they are read.
+CREATE TABLE IF NOT EXISTS finding (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  family_root   TEXT NOT NULL,
+  task_id       TEXT NOT NULL,
+  repo          TEXT,
+  source        TEXT NOT NULL ${FINDING_SOURCES},
+  source_key    TEXT UNIQUE,
+  source_run    INTEGER,
+  severity      TEXT CHECK (severity IS NULL OR severity IN ('HIGH', 'MEDIUM', 'LOW')),
+  file          TEXT,
+  line          INTEGER,
+  summary       TEXT NOT NULL,
+  action        TEXT NOT NULL,
+  excerpt       TEXT,
+  revision      TEXT,
+  state         TEXT NOT NULL DEFAULT 'open' CHECK (state IN ('open', 'accepted', 'rejected', 'with-person', 'closed')),
+  rounds        INTEGER NOT NULL DEFAULT 1,
+  sent_by       TEXT NOT NULL,
+  sent_at       TEXT NOT NULL,
+  delivered_run INTEGER,
+  delivered_how TEXT CHECK (delivered_how IS NULL OR delivered_how IN ('mailbox', 'brief')),
+  delivered_at  TEXT,
+  read_at       TEXT,
+  closed_by     TEXT,
+  closed_note   TEXT,
+  closed_at     TEXT
+);
+CREATE INDEX IF NOT EXISTS finding_family ON finding (family_root, state);
+-- What the owner answered. 'saved' until the attempt that wrote it settles: then 'counted', or 'refused' with the reason
+-- (an accepted answer on a run that changed nothing; a rejection that names no file in the code).
+CREATE TABLE IF NOT EXISTS finding_answer (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  finding   INTEGER NOT NULL REFERENCES finding(id) ON DELETE CASCADE,
+  round     INTEGER NOT NULL,
+  run       INTEGER NOT NULL,
+  answer    TEXT NOT NULL CHECK (answer IN ('accepted', 'rejected')),
+  detail    TEXT NOT NULL,
+  file      TEXT,
+  line      INTEGER,
+  revision  TEXT,
+  state     TEXT NOT NULL DEFAULT 'saved' CHECK (state IN ('saved', 'counted', 'refused')),
+  problem   TEXT,
+  at        TEXT NOT NULL,
+  UNIQUE (finding, round, run)
+);
+-- One failed check on one revision of one task family: the UNIQUE key is what stops a second repair of the same failure.
+-- attempt is the repair ledger's (repair_chain) attempt this row drafted, when it drafted one.
+CREATE TABLE IF NOT EXISTS check_repair (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  family_root  TEXT NOT NULL,
+  owner_task   TEXT NOT NULL,
+  repo         TEXT NOT NULL,
+  revision     TEXT NOT NULL,
+  failure_key  TEXT NOT NULL,
+  source_run   INTEGER NOT NULL,
+  state        TEXT NOT NULL CHECK (state IN ('waiting', 'repairing', 'rerunning', 'with-person', 'parked', 'fixed', 'closed')),
+  why          TEXT NOT NULL,
+  repair_task  TEXT,
+  attempt      INTEGER,
+  created_at   TEXT NOT NULL,
+  updated_at   TEXT NOT NULL,
+  UNIQUE (family_root, revision, failure_key)
+);
+CREATE INDEX IF NOT EXISTS check_repair_state ON check_repair (repo, state);
+-- A failing result saved before a change. The after side is never stored: it is read from the task's latest results,
+-- so a newer commit reads as out of date on its own.
+CREATE TABLE IF NOT EXISTS evidence_pair (
+  id             INTEGER PRIMARY KEY AUTOINCREMENT,
+  family_root    TEXT NOT NULL,
+  repo           TEXT,
+  before_run     INTEGER NOT NULL,
+  before_head    TEXT NOT NULL,
+  receipt_digest TEXT NOT NULL,
+  command_digest TEXT,
+  saved_by       TEXT NOT NULL,
+  saved_at       TEXT NOT NULL,
+  UNIQUE (family_root, before_run)
+);
+-- A bug fix's optional failing test first: asked for on the family; the agent's report beside it, shown as its own report.
+CREATE TABLE IF NOT EXISTS failing_first (
+  family_root TEXT PRIMARY KEY,
+  repo        TEXT,
+  asked_by    TEXT NOT NULL,
+  asked_at    TEXT NOT NULL,
+  report_run  INTEGER,
+  test        TEXT,
+  output      TEXT,
+  reported_at TEXT
+);
+-- What a provider said when an attempt failed, kept as data for a person. Nothing reads it to route work.
+CREATE TABLE IF NOT EXISTS provider_capture (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  run         INTEGER NOT NULL UNIQUE,
+  repo        TEXT,
+  provider    TEXT NOT NULL,
+  model       TEXT,
+  auth_mode   TEXT,
+  exit_code   INTEGER,
+  code        TEXT,
+  text        TEXT NOT NULL,
+  hint        INTEGER NOT NULL DEFAULT 0 CHECK (hint IN (0, 1)),
+  label       TEXT CHECK (label IS NULL OR label IN ('exhausted', 'not-exhausted')),
+  labelled_by TEXT,
+  at          TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS provider_capture_provider ON provider_capture (provider, id);
+`;
+export const V155_TABLES = Object.freeze(["finding", "finding_answer", "check_repair", "evidence_pair", "failing_first", "provider_capture"]);
+export const V155_STEPS = Object.freeze(["follow-through-tables", "finding-sources"]);
+/** One read, or `fallback` when the file predates v155. Any other error is real and goes on. */
+export function readingFleet(read, fallback) {
+    try {
+        return read();
+    }
+    catch (error) {
+        if (/no such table: (finding|finding_answer|check_repair|evidence_pair|failing_first|provider_capture)\b/.test(String(error)))
+            return fallback;
+        throw error;
+    }
+}