toolroll 0.9.104 → 0.9.105

package/dist/first-run.js

@@ -1,25 +1,11 @@
-/**
- * The first run: four plain steps to a first result, and three first tasks
- * to try. Everything here is derived from live facts on each render; the
- * list retires permanently with the first Ready result (the
- * 'first-success-at' installation fact). A suggestion only drafts words in
- * the composer: nothing is filed until the person sends it and confirms.
- */
 import { run } from "./exec.js";
 import { hardenedGit } from "./teardown-git.js";
 import { githubIssues } from "./issues.js";
 import { START_BUILDER_HREF } from "./needs-you.js";
 export const SIGN_IN_COMMAND = "claude auth login";
 export const SANDBOX_COMMAND = "npx toolroll demo";
-/** How a person starts on a real project (the demo hands off to this). */
-export const START_COMMAND = "npx toolroll up";
-/** How it works, once, above the composer until the first request. */
-export const HOW_IT_WORKS = "Ask for a change. The lead writes a short plan; you approve it; an agent builds it on its own branch; it's Ready when your tests pass.";
-/**
- * The one command that gets an agent signed in on this computer: sign in to the CLI that's installed (Claude Code
- * first, then Codex), or install Claude Code and sign in, written for this operating system's shell. Unknown states
- * (not checked yet) get the install-and-sign-in command, which is right on a fresh machine and harmless otherwise.
- */
+export const START_COMMAND = "npx toolroll";
+export const HOW_IT_WORKS = "Ask for a change. You approve a short plan; an agent builds it on its own branch; it comes back Ready with the result and its check status.";
 export function signInCommandFor(states, platform) {
     const installed = (state) => state !== undefined && state !== "not-installed";
     if (installed(states?.claude))
@@ -28,7 +14,6 @@ export function signInCommandFor(states, platform) {
         return "codex login";
     return `npm install -g @anthropic-ai/claude-code${platform === "win32" ? ";" : " &&"} ${SIGN_IN_COMMAND}`;
 }
-/** The steps (the builder step is added by withBuilderStep), each done or with the one action that does it; null once the first result has arrived. */
 export function firstRunSteps(facts) {
     if (facts.firstResultAt !== null)
         return null;
@@ -40,13 +25,11 @@ export function firstRunSteps(facts) {
         { key: "task", title: "Your first task", done: facts.hasTask, action: facts.hasTask ? null : { kind: "link", label: "New task", href: "/tasks/new" } },
     ];
 }
-/** The builder step, before the first task: under `toolroll serve` nothing connects a builder, and a task filed then
- * waits forever, so the steps never all read done without one. It leads to Start a builder, which shows the command. */
 export function withBuilderStep(steps, connected) {
     if (steps === null)
         return null;
-    const builder = { key: "builder", title: "Builder connected", done: connected,
-        action: connected ? null : { kind: "link", label: "Start a builder", href: START_BUILDER_HREF } };
+    const builder = { key: "builder", title: "Taking work", done: connected,
+        action: connected ? null : { kind: "link", label: "Start taking work", href: START_BUILDER_HREF } };
     const task = steps.findIndex(one => one.key === "task");
     return task < 0 ? [...steps, builder] : [...steps.slice(0, task), builder, ...steps.slice(task)];
 }
@@ -56,10 +39,7 @@ export const GENERIC_FIRST_TASKS = [
     { source: "generic", label: "Improve the README's setup section", draft: "Improve the setup section of the README so a newcomer can install and run the project." },
 ];
 const clip = (text, max) => (text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text);
-/** Issue titles and TODO text are written by anyone: keep only what a person can see, so the draft they send is the
- * draft the lead reads (no control, format, zero-width, bidi, tag or variation-selector characters). */
 export const visibleText = (text) => text.replace(/[\p{Cf}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]/gu, "").replace(/[\p{Cc}\s]+/gu, " ").trim();
-/** Three first tasks: open GitHub issues first, then TODO or FIXME comments, then safe generic ones. */
 export function firstTaskSuggestions(found) {
     const fromIssues = found.issues.map(({ number, title: raw }) => {
         const title = visibleText(raw);
@@ -72,8 +52,6 @@ export function firstTaskSuggestions(found) {
     return [...fromIssues, ...fromTodos, ...GENERIC_FIRST_TASKS].slice(0, 3);
 }
 const SKIPPED = /(^|\/)(node_modules|dist|build|vendor|third_party|\.git)\//;
-/** `git grep -z -n` records ("file\0line\0text\n") to TODO or FIXME notes, one per file. NUL-separated so a
- * file name with a colon or a newline in it is still one file name. */
 export function parseTodoLines(stdout, limit = 3) {
     const found = [];
     const seen = new Set();
@@ -91,9 +69,7 @@ export function parseTodoLines(stdout, limit = 3) {
     }
     return found;
 }
-/** The TODO search: no colour and no column whatever the person's git config says, NUL after each file name. */
 export const TODO_GREP_ARGS = ["-c", "grep.column=false", "grep", "--no-color", "-z", "-n", "-I", "-w", "--max-count=1", "-E", "TODO|FIXME"];
-/** Read the project's own sources for suggestions: its open issues through the `gh` login, then its TODO comments. Failures fall through quietly. */
 export async function findFirstTasks(repo, runner = run) {
     let issues = [];
     try {
@@ -107,7 +83,6 @@ export async function findFirstTasks(repo, runner = run) {
     let todos = [];
     if (issues.length < 3) {
         try {
-            // The project's repository is shared with builds that can write its config: the hardened read (teardown-git.ts).
             const result = await (runner === run ? hardenedGit(run, "read") : runner)("git", [...TODO_GREP_ARGS], { cwd: repo, timeoutMs: 5_000 });
             if (result.code === 0 || result.stdout !== "")
                 todos = parseTodoLines(result.stdout);
@@ -118,7 +93,6 @@ export async function findFirstTasks(repo, runner = run) {
     }
     return firstTaskSuggestions({ issues, todos });
 }
-/** "First result in 7 min": how long after the installation began its first Ready result arrived. */
 export function firstResultWords(since, at) {
     const minutes = Math.round((Date.parse(at) - Date.parse(since)) / 60_000);
     if (!Number.isFinite(minutes) || minutes < 0)
@@ -133,44 +107,24 @@ export function firstResultWords(since, at) {
     }
     return `First result in ${Math.round(minutes / (24 * 60))} days`;
 }
-/** A task's five steps, as a person reads them: the one label set the task page's rows, chat's first-task journey and
- * the progress line all read. */
 export const JOURNEY_STEPS = [["plan", "Plan"], ["approve", "Approval"], ["build", "Build"], ["checks", "Checks"], ["ready", "Ready"]];
-/**
- * Where the first task stands on Plan → Approval → Build → Checks → Ready, from the one stage every surface reads
- * (task-status.ts). Waiting for a worker before approval is still the plan; after approval it is the build. `built`:
- * the build finished with a result.
- */
 export function firstTaskJourney(read, approved, built = false) {
     const at = read.stage === "finished" || read.stage === "complete" ? { index: 5, stuck: false }
         : read.stage === "checking" || read.stage === "reviewing" ? { index: 3, stuck: false }
             : read.stage === "building" ? { index: 2, stuck: false }
-                // Waiting on nothing a person does: the build finished and is settling.
                 : read.stage === "waiting" ? { index: built ? 3 : approved ? 2 : 0, stuck: false }
                     : read.stage === "needs-you" && read.need === "approval" ? { index: 1, stuck: false }
                         : read.stage === "planning" ? { index: 0, stuck: false }
                             : read.stage === "queued" ? { index: approved ? 2 : 0, stuck: false }
-                                // A build that finished but isn't Ready (its checks failed or didn't run, or it needs a decision) stopped at Checks.
                                 : { index: built ? 3 : approved ? 2 : 0, stuck: true };
     return JOURNEY_STEPS.map(([key, label], index) => ({ key, label,
         state: index < at.index ? "done" : index === at.index ? (at.stuck ? "stuck" : "current") : "todo" }));
 }
-/**
- * Any task's road (the step rows on its page): the first task's five steps, told only
- * from recorded facts. Approval is done only when the plan was approved (a rewritten plan waiting on approval
- * stands there again); a task that never needed one shows it skipped. Checks is done only when the approved check
- * passed; a running, missing or Off check says so, and with no checks fact it is skipped. A failed check, or one that
- * can't be read, stops the road at Checks: Ready isn't done (fail closed), even on a task a person marked complete.
- * A research report has no Checks step: a report stopped there stops at
- * Ready. The step that waits on a person carries `needsYou`.
- */
 export function taskRoad(read, approved, built, facts) {
     const replan = read.stage === "needs-you" && read.need === "replan";
     const plainApproved = approved && !replan;
     let steps = firstTaskJourney(replan ? { stage: "needs-you", need: "approval" } : read, plainApproved, built);
     const complete = read.stage === "complete";
-    // A finished build that waits on something other than its check (a hold, a decision) stops after Checks, at Ready,
-    // when its check passed, didn't run or is Off: the road never calls a passing check stuck.
     let waitsAtReady = false;
     steps = steps.map(step => {
         if (step.key === "approve" && step.state === "done" && !plainApproved)
@@ -194,7 +148,6 @@ export function taskRoad(read, approved, built, facts) {
         }
         if (step.key !== "checks" || (step.state !== "done" && step.state !== "current"))
             return step;
-        // At Checks now: only a recorded failure, an unreadable check or a running check changes how it reads.
         if (step.state === "current")
             return facts.checks === "failed" ? { ...step, state: "stuck", say: "Checks failed" }
                 : facts.checks === "unreadable" ? { ...step, state: "stuck", say: "Checks unreadable" }
@@ -211,7 +164,6 @@ export function taskRoad(read, approved, built, facts) {
     });
     if (waitsAtReady)
         steps = steps.map(step => step.key === "ready" ? { ...step, state: "stuck" } : step);
-    // A road stopped at Checks (failed, or unreadable) has not reached Ready.
     const at = steps.find(step => step.key === "checks");
     if (facts.report !== true && at !== undefined && at.state === "stuck") {
         steps = steps.map(step => step.key === "ready" && step.state === "done" ? { ...step, state: "todo" } : step);
@@ -230,10 +182,8 @@ export const WELCOME_AGENTS = [
     { id: "claude", name: "Claude Code", signIn: SIGN_IN_COMMAND, install: "npm install -g @anthropic-ai/claude-code" },
     { id: "codex", name: "Codex", signIn: "codex login", install: "npm install -g @openai/codex" },
 ];
-/** The sample project's folder name under the project folder. */
 export const SAMPLE_PROJECT_NAME = "toolroll-sample";
 const SIGNED_IN = new Set(["connected", "key-works", "key-present"]);
-/** The welcome's three steps (Agent · Project · First task) from live facts, the same for every screen that shows them. */
 export function welcomeModel(facts) {
     const join = facts.platform === "win32" ? ";" : " &&";
     const agents = WELCOME_AGENTS.map((one) => {
@@ -258,14 +208,11 @@ export function welcomeModel(facts) {
         project: { done: projectDone, projects: [...facts.projects], sample, notTakingWork: hasProject && !facts.ready },
         task: { done: facts.hasTask, open: taskOpen, starters: taskOpen ? starters : [] },
     };
-    // The next step a page can move: the agent only when there is something to click (Use this one); its sign-in is a
-    // command on the computer, so a project or the first task leads meanwhile.
     const agentAct = !signedIn ? false : facts.inUse === null && agents.some(one => one.canUse);
     const next = agentAct ? "agent" : !projectDone ? "project" : !facts.hasTask ? "task" : null;
     const left = [model.agent.done, model.project.done, model.task.done].filter(done => !done).length;
     return { ...model, next, left };
 }
-/** First tasks for the sample project: the changes its README suggests. */
 export const SAMPLE_FIRST_TASKS = [
     { source: "generic", label: "Round prices to whole cents", draft: "Round priceWithDiscount's result to whole cents and add a test for it." },
     { source: "generic", label: "Refuse a negative discount", draft: "Make priceWithDiscount refuse a negative discount with a clear error, and test it." },

package/dist/first-tasks-child.js

@@ -1,8 +1,3 @@
-/**
- * Started only by learning-look.ts: one project's first-task suggestions (first-run.ts findFirstTasks), in a process
- * of its own so the hardened git's synchronous reads of the project's folder never hold the console's thread. Its one
- * argument is JSON naming the project; it prints the suggestions as JSON and ends.
- */
 import { findFirstTasks } from "./first-run.js";
 const input = JSON.parse(process.argv[2] ?? "null");
 if (input === null || typeof input.repo !== "string" || input.repo === "" || input.repo.includes("\0"))

package/dist/flaky-ci.js

@@ -1,29 +1,12 @@
-/**
- * GitHub CI attempts as mixed outcomes (docs/plans/learning-loops.md, "A CI observation"): read-only, lane level, never
- * mixed with local pairs, no test name (logs aren't fetched). Only workflow runs Toolroll already knows by id are read:
- * the watched branch's push runs (`branch_check_run`) and the nightly's runs (`github_nightly_watch`). PR runs aren't
- * read: Toolroll records no run id for them.
- *
- * For a run on attempt n > 1, attempts n-1 and n are read with the exact-attempt reader and paired per lane. A pairing
- * needs exactly one job per lane in each attempt, both attempts read whole, the same run and commit, an earlier
- * `failure` that got past setup and a later `success`. Anything else is rejected and counted, never guessed.
- *
- * The only writer of `ci_flaky_observation` and `ci_pairing_rejected`. Nothing here reruns anything or changes a check,
- * a verdict or an approval. A policy path (release-auto.ts EVAL_POLICY).
- */
 import { createHash } from "node:crypto";
 import { failedBeforeTests } from "./github-jobs.js";
 import { githubNightlyOf, laneIdOf, readAttemptJobs, readRun, resolveLane } from "./nightly-github.js";
-/** How old a known run may be and still be read, how many runs one pass reads, and each read's limit. */
 const RECENT_MS = 14 * 86_400_000;
 const RUNS_PER_PASS = 30;
 const READ_MS = 15_000;
-/** How often a project is read at most. */
 export const CI_READ_EVERY_MS = 30 * 60_000;
 const RETAIN_MS = 180 * 86_400_000;
-/** The service cursor a project's reads keep (a cursor key can't hold a path). */
 export const ciCursorKey = (repo) => `flaky-ci:${createHash("sha256").update(repo).digest("hex").slice(0, 32)}`;
-/** The GitHub repositories this project's records name: the nightly's opt-in and its failed-checks triggers. */
 export function ciRepositoriesOf(store, repo) {
     const slugs = new Set();
     const nightly = githubNightlyOf(store, repo);
@@ -35,11 +18,10 @@ export function ciRepositoriesOf(store, repo) {
             if (config.kind === "github" && config.watch === "checks" && typeof config.repo === "string")
                 slugs.add(config.repo);
         }
-        catch { /* an unreadable trigger names nothing */ }
+        catch { }
     }
     return [...slugs];
 }
-/** The runs Toolroll knows by id for this project and repository, newest first. */
 function knownRuns(store, repo, slug, now) {
     const since = new Date(now.getTime() - RECENT_MS).toISOString();
     const branch = store.handle.prepare("SELECT run_id, head_sha FROM branch_check_run WHERE lower(repo) = lower(?) AND run_created_at >= ? ORDER BY run_created_at DESC, run_id DESC LIMIT ?").all(slug, since, RUNS_PER_PASS)
@@ -50,7 +32,6 @@ function knownRuns(store, repo, slug, now) {
     const seen = new Set();
     return [...branch, ...nightly].filter(one => !seen.has(one.id) && seen.add(one.id) !== undefined).slice(0, RUNS_PER_PASS);
 }
-/** Pair one run's attempts n-1 and n. A pair already decided isn't read again. */
 export async function observeCiRun(store, input) {
     const { repo, slug, now } = input;
     const get = (path) => input.gh(path, READ_MS);
@@ -91,7 +72,6 @@ export async function observeCiRun(store, input) {
                     continue;
                 }
                 const first = a[0], second = b[0];
-                // A lane that passed both times is the ordinary case, not a pairing refused.
                 if (first.conclusion === "success" && second.conclusion === "success")
                     continue;
                 if (first.conclusion !== "failure" || second.conclusion !== "success") {
@@ -121,7 +101,6 @@ export async function observeCiRun(store, input) {
     });
     return { observed, rejected };
 }
-/** One project's pass over its known runs. A read that fails records nothing and is tried on the next pass. */
 export async function observeCiAttempts(store, repo, gh, now) {
     const result = { read: 0, observed: 0, rejected: 0 };
     for (const slug of ciRepositoriesOf(store, repo)) {
@@ -134,14 +113,12 @@ export async function observeCiAttempts(store, repo, gh, now) {
     }
     return result;
 }
-/** The storage sweep's own step: CI rows older than the retention window go; nothing else deletes them. */
 export function pruneCiObservations(store, now) {
     const cut = new Date(now.getTime() - RETAIN_MS).toISOString();
     const observed = store.handle.prepare("DELETE FROM ci_flaky_observation WHERE observed_at < ?").run(cut);
     const rejected = store.handle.prepare("DELETE FROM ci_pairing_rejected WHERE at < ?").run(cut);
     return Number(observed.changes) + Number(rejected.changes);
 }
-/** Pairings refused since `since` for these repositories. */
 export function ciNotPaired(store, repositories, since) {
     if (repositories.length === 0)
         return 0;

package/dist/flaky-cli.js

@@ -1,5 +1,3 @@
-/** `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 = [
@@ -13,11 +11,9 @@ export const FLAKY_DESCRIPTORS = [
     { 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`}.`;

package/dist/flaky.js

@@ -1,20 +1,6 @@
-/**
- * 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) {
         throw new Error("a tracked identity needs its project, a bounded identity and the observation that named it");
@@ -23,30 +9,22 @@ 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)
@@ -55,12 +33,6 @@ function comparableFact(store, runId) {
     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))
@@ -79,7 +51,6 @@ export function recordObservations(store, runId, now) {
         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"]);
@@ -100,7 +71,6 @@ export function recordObservations(store, runId, now) {
             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))) {
@@ -112,19 +82,16 @@ export function recordObservations(store, runId, now) {
     }
     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)
@@ -138,12 +105,10 @@ export function identityWords(identity) {
     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();
@@ -166,8 +131,6 @@ function blobReader(repo, files) {
         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))
@@ -201,10 +164,8 @@ function statusOf(store, repo, identity, blobAt, pruned) {
         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();
@@ -232,12 +193,10 @@ export function flakyList(store, repo, now, days = FLAKY_WINDOW_DAYS) {
     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)
@@ -251,9 +210,7 @@ export function flakyShow(store, repo, key, now, days = FLAKY_RETAIN_DAYS) {
             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: [

package/dist/fleet-schema.js

@@ -1,13 +1,3 @@
-/**
- * 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 = `
@@ -122,7 +112,6 @@ CREATE INDEX IF NOT EXISTS provider_capture_provider ON provider_capture (provid
 `;
 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();

package/dist/flow-actions.js

@@ -1,23 +1,3 @@
-/**
- * Steps that reach outside (v87): a web request, an email, and a call to one
- * of the project's tools (its MCP servers). Each runs in the worker's step
- * pass (flow-steps.ts), once per visit of a card.
- *
- * - Web request: the address's scheme and host are written out in the
- *   zone (flows.ts refuses fill-ins there); fill-ins in its path and query
- *   are encoded, so a card can never change where a request goes. Secrets
- *   ({{secret.NAME}}) are filled into headers only, from a 0600 file per
- *   project beside the database, and never reach a log, a card or a chat.
- * - Email: through the operator's own mail server (Settings → Email), with
- *   the password in a 0600 file beside the database. Recipients are checked
- *   addresses; the subject can't carry a line break.
- * - Tool: the project's own MCP server, started like its Test button starts
- *   it, with the project's tool secrets and nothing else of ours.
- *
- * A refusal (a 4xx, a rejected recipient, a tool that says it failed) is an
- * answer: the card takes its failure path. Trouble reaching a service is
- * tried again, like every step.
- */
 import { redactSecretAssignments } from "./builder.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { fillFlowText } from "./flows.js";
@@ -30,7 +10,6 @@ import { ALL_CREDENTIAL_ENV } from "./provider.js";
 const clip = (text, cap) => text.length <= cap ? text : `${text.slice(0, cap - 1)}…`;
 const blank = (text) => redactSecretAssignments(redactSecretLines(text, scanForSecrets(text)));
 const scrub = scrubSecrets;
-/** Fill every string inside a JSON value, leaving its shape alone: a card's text can never break out of a string. */
 function fillJson(value, fill) {
     if (typeof value === "string")
         return fill(value);
@@ -40,7 +19,6 @@ function fillJson(value, fill) {
         return Object.fromEntries(Object.entries(value).map(([key, one]) => [key, fillJson(one, fill)]));
     return value;
 }
-// ---- secrets for web requests and scripts: flow-secrets.ts (a leaf module) ----------
 export { flowSecretNames, readFlowSecrets, scrubSecrets, SECRET_NAME, setFlowSecret } from "./flow-secrets.js";
 export async function runRequest(stage, card, repo, io) {
     const request = stage.request;
@@ -109,13 +87,9 @@ export async function runRequest(stage, card, repo, io) {
         return { state: "retry", said: `${where} answered ${response.status}${first === "" ? "" : `: ${first}`}.`, log };
     return { state: "failed", said: `${where} refused it (${response.status})${first === "" ? "" : `: ${first}`}.`, log, output: answered };
 }
-// ---- email ----------------------------------------------------------------------
-/** The operator's mail server: everything but the password is shown back. */
-/** Whether Send email steps can send: a connected Google account or a mail server. */
 export function sendingReady(dir) {
     return googleConnected(dir) !== null || readEmailSettings(dir) !== null;
 }
-/** The account Send email steps send from, signed in: Google when connected, else the mail server. */
 export async function sendingAccount(dir, fetcher) {
     if (googleConnected(dir) !== null) {
         const token = await googleAccessToken(dir, fetcher);
@@ -126,12 +100,9 @@ export async function sendingAccount(dir, fetcher) {
     const server = readEmailSettings(dir);
     return server === null ? { ok: false, said: "Email isn't set up yet. Add your mail server in Settings → Email.", permanent: false } : { ok: true, settings: server };
 }
-/** The production sender: the operator's mail server through nodemailer. */
 export const sendThroughServer = async (settings, mail) => {
-    // nodemailer loads when mail is sent, not with every command that imports this module.
     const { default: nodemailer } = await import("nodemailer");
     const transport = nodemailer.createTransport({
-        // A password never travels unencrypted: with a sign-in, the connection must be (or become) TLS.
         host: settings.host, port: settings.port, secure: settings.secure, requireTLS: !settings.secure && settings.user !== "",
         ...(settings.accessToken !== undefined ? { auth: { type: "OAuth2", user: settings.user, accessToken: settings.accessToken } } : settings.user === "" ? {} : { auth: { user: settings.user, pass: settings.password } }),
         connectionTimeout: 15_000, greetingTimeout: 15_000, socketTimeout: 30_000,
@@ -166,7 +137,6 @@ export async function sendEmail(stage, card, io, thread = null) {
     const body = clip(fillFlowText(email.body, text), 20_000);
     if (body.trim() === "")
         return { state: "failed", said: "The email would be empty." };
-    // To someone the card is already writing with (or who emailed it): the email stays in that thread.
     const source = card.source?.mail;
     const known = thread ?? (source?.id ? { inReplyTo: source.id, references: [...source.references, source.id].slice(-20), people: new Set([source.from]) } : null);
     const threaded = known !== null && to.some(one => known.people.has(one.toLowerCase())) ? { inReplyTo: known.inReplyTo, references: known.references } : {};
@@ -176,7 +146,6 @@ export async function sendEmail(stage, card, io, thread = null) {
         return { state: sent.permanent ? "failed" : "retry", said: sent.said, log };
     return { state: "passed", said: `Emailed ${to.join(", ")}.`, log, output: `Sent to ${to.join(", ")}: “${subject}”`, mail: { id: sent.id, to } };
 }
-/** Whether the zone's tool is one of the project's, or what to say while it waits. */
 export function toolWaiting(store, stage, repo) {
     const wanted = stage.tool?.server ?? "";
     return projectToolsOf(store, repo).some(one => one.name === wanted) ? null : `There's no tool called ${wanted || "(none)"} in this project. Add it on the Tools page.`;