toolroll 0.9.93 → 0.9.95

package/dist/memory-use.js

@@ -0,0 +1,109 @@
+/**
+ * "Last included in a run" (docs/plans/learning-loops.md): one `memory_use` row per lesson, reference and decision in a
+ * run's frozen context, written in the transaction that freezes it. The only writer of `memory_use`; release-auto's
+ * learning scan (eval-hooks.ts learningWriteProblem) needs a person for any other. A policy path (release-auto.ts
+ * EVAL_POLICY).
+ *
+ * Usage, never benefit: nothing here says a run did better for having an item, and nothing reads it for authority. Old
+ * snapshots are backfilled from their own sha-verified bytes and nothing is inferred: a knowledge snapshot from before
+ * `capturedAt` has no time and no version, so its rows say so. Lead chat contexts aren't snapshotted and aren't counted.
+ */
+import { createHash } from "node:crypto";
+import { readKnowledgeSelection } from "./contracts/project-knowledge.js";
+const sha = (text) => createHash("sha256").update(text).digest("hex");
+/** A run's role as a phase of the work. */
+export const phaseOfRole = (role) => role === "planner" ? "plan" : role === "reviewer" ? "review" : "build";
+function insertUse(store, row) {
+    store.handle.prepare(`INSERT INTO memory_use (run, repo, kind, item, version, phase, included_at) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT (run, kind, item) DO NOTHING`)
+        .run(row.run, row.repo, row.kind, row.item, row.version, row.phase, row.at);
+}
+/** Every reference and decision in a run's frozen knowledge. Called in the transaction that freezes it; advisory, so a
+ * failure leaves the run's context exactly as it was. */
+export function recordKnowledgeUse(store, input) {
+    const { selection } = input, phase = phaseOfRole(input.role), at = selection.capturedAt ?? null;
+    try {
+        store.savepoint(() => {
+            for (const ref of selection.references)
+                insertUse(store, { run: input.run, repo: input.repo, kind: "reference", item: ref.id, version: selection.capturedAt === undefined ? null : selection.revision, phase, at });
+            for (const one of selection.decisions ?? [])
+                insertUse(store, { run: input.run, repo: input.repo, kind: "decision", item: String(one.id), version: one.revision ?? null, phase, at });
+        });
+    }
+    catch { /* advisory: the run's context is unchanged */ }
+}
+/** The lessons in a run's frozen learning payload (its last line is the record). */
+function lessonsOf(payload) {
+    try {
+        const record = JSON.parse(payload.trim().split("\n").at(-1));
+        if (typeof record.phase !== "string" || !Array.isArray(record.lessons))
+            return null;
+        const lessons = record.lessons.flatMap((one) => { const l = one; return Number.isSafeInteger(l.id) && Number.isSafeInteger(l.version) ? [{ id: Number(l.id), version: Number(l.version) }] : []; });
+        return { phase: record.phase, lessons };
+    }
+    catch {
+        return null;
+    }
+}
+/** Every lesson in a run's frozen learning context. As recordKnowledgeUse. */
+export function recordLessonUse(store, input) {
+    const read = lessonsOf(input.payload);
+    if (read === null)
+        return;
+    try {
+        store.savepoint(() => { for (const one of read.lessons)
+            insertUse(store, { run: input.run, repo: input.repo, kind: "lesson", item: String(one.id), version: one.version, phase: read.phase, at: input.at }); });
+    }
+    catch { /* advisory: the run's context is unchanged */ }
+}
+const CURSOR_LESSONS = "memory-use:backfill-lessons", CURSOR_KNOWLEDGE = "memory-use:backfill-knowledge";
+/**
+ * Backfill from snapshots older than this feature, a bounded batch at a time (the watch loop's learning pass): each
+ * snapshot's sha is verified first. Lesson rows take the snapshot's own time and version; knowledge rows from a snapshot
+ * with no `capturedAt` have no version and no time. Returns how many snapshots were read.
+ */
+export function backfillMemoryUse(store, now, limit = 200) {
+    const lessonFrom = store.serviceCursor(CURSOR_LESSONS), knowledgeFrom = store.serviceCursor(CURSOR_KNOWLEDGE);
+    const lessons = store.handle.prepare("SELECT run, repo, payload, sha, created_at FROM learning_snapshot WHERE run > ? ORDER BY run LIMIT ?").all(lessonFrom, limit);
+    const knowledge = store.handle.prepare("SELECT k.run, k.repo, k.payload, k.sha, r.role FROM knowledge_snapshot k JOIN run r ON r.id = k.run WHERE k.run > ? ORDER BY k.run LIMIT ?").all(knowledgeFrom, limit);
+    store.transact(() => {
+        for (const row of lessons) {
+            const payload = String(row["payload"]);
+            if (sha(payload) === row["sha"])
+                recordLessonUse(store, { run: Number(row["run"]), repo: String(row["repo"]), payload, at: String(row["created_at"]) });
+        }
+        for (const row of knowledge) {
+            const payload = String(row["payload"]);
+            if (sha(payload) !== row["sha"])
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(payload);
+            }
+            catch {
+                continue;
+            }
+            const read = readKnowledgeSelection(parsed);
+            if (read.ok)
+                recordKnowledgeUse(store, { run: Number(row["run"]), repo: String(row["repo"]), role: String(row["role"]), selection: read.value });
+        }
+        if (lessons.length > 0)
+            store.setServiceCursor(CURSOR_LESSONS, Number(lessons.at(-1)["run"]), now);
+        if (knowledge.length > 0)
+            store.setServiceCursor(CURSOR_KNOWLEDGE, Number(knowledge.at(-1)["run"]), now);
+    });
+    return lessons.length + knowledge.length;
+}
+/** A project's usage, by `<kind>:<item>`: its newest run, that run's time and how many runs had it. */
+export function memoryUseOf(store, repo) {
+    const rows = store.handle.prepare(`SELECT u.kind, u.item, u.run AS last_run, u.included_at, t.runs FROM memory_use u
+    JOIN (SELECT kind, item, MAX(run) AS last_run, COUNT(*) AS runs FROM memory_use WHERE repo = ? GROUP BY kind, item) t ON t.kind = u.kind AND t.item = u.item AND t.last_run = u.run WHERE u.repo = ?`).all(repo, repo);
+    return new Map(rows.map(row => [`${String(row["kind"])}:${String(row["item"])}`, { lastRun: Number(row["last_run"]), lastAt: row["included_at"] == null ? null : String(row["included_at"]), runs: Number(row["runs"]) }]));
+}
+const DAY = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
+/** "Last included in a run: #4410, Nov 3 · 41 runs"; "#2210 (time not recorded)" for a backfilled row; "Not included yet". */
+export function lastIncludedWords(use) {
+    if (use === undefined)
+        return "Not included yet";
+    const runs = `${use.runs.toLocaleString("en-US")} run${use.runs === 1 ? "" : "s"}`;
+    return `Last included in a run: #${use.lastRun}${use.lastAt === null ? " (time not recorded)" : `, ${DAY.format(new Date(use.lastAt))}`} · ${runs}`;
+}

package/dist/merge-checklist.d.ts

@@ -0,0 +1,55 @@
+/** "Can I merge?" (docs/plans/plain-toolroll.md P1.6): one checklist per task, read from the records the task page,
+ * the result page and the pull request row already read, with nothing recomputed and nothing checked live. Each row
+ * says one fact about the task's current result; a blocker carries one existing act the person can take: Run checks,
+ * Retry, or Ask the agent to fix (Send back with a note naming the blocker). Nothing here acts: it is a read, and every
+ * act it names is the person's own post through its usual door.
+ *
+ * Rows Toolroll keeps no record of (up to date with main; conflicts outside a batch check) say so, rather than guess:
+ * GitHub shows them on the pull request. */
+import { type AssignmentAccess, type AssignmentSnapshot } from "./assignment.js";
+import { type Store } from "./store.js";
+export declare const CHECKLIST_KEYS: readonly ["plan", "build", "checks", "requirements", "pull-request", "pr-ci", "up-to-date", "conflicts", "comments", "release"];
+export type ChecklistKey = (typeof CHECKLIST_KEYS)[number];
+/** yes: done; no: in the way (with its act when one exists); waiting: under way, nothing to do yet; unknown: Toolroll
+ * keeps no record of it; skip: doesn't apply to this task. */
+export type ChecklistMark = "yes" | "no" | "waiting" | "unknown" | "skip";
+/** The existing act a blocker carries. `fix`: Send back, with `note` as its feedback (empty: send the saved notes). */
+export type ChecklistAct = {
+    kind: "run-checks";
+    run: number;
+} | {
+    kind: "retry";
+    taskId: string;
+} | {
+    kind: "fix";
+    run: number;
+    note: string;
+};
+export type ChecklistRow = {
+    key: ChecklistKey;
+    label: string;
+    mark: ChecklistMark;
+    say: string;
+    act: ChecklistAct | null;
+};
+export type MergeChecklist = {
+    taskId: string;
+    activeTaskId: string;
+    run: number | null;
+    head: string | null;
+    /** yes: nothing Toolroll records is in the way; no: something is (the first `no` row); not-yet: only waiting rows. */
+    answer: "yes" | "no" | "not-yet" | "merged";
+    sentence: string;
+    rows: ChecklistRow[];
+};
+export declare const CHECKLIST_LABELS: Readonly<Record<ChecklistKey, string>>;
+/** The one sentence for a row Toolroll keeps no record of. */
+export declare const NOT_RECORDED = "Toolroll doesn't record this. The pull request on GitHub shows it.";
+/** The act labels, the same words the result page uses. */
+export declare const CHECKLIST_ACT_LABELS: Readonly<Record<ChecklistAct["kind"], string>>;
+/** The checklist for a task's current result, as `access` may see it; null when the task isn't visible there. */
+export declare function mergeChecklistOf(store: Store, taskId: string, now: Date, access: AssignmentAccess, root?: string): MergeChecklist | null;
+/** The checklist from an assignment snapshot already read (the task page reads one). */
+export declare function checklistFromAssignment(store: Store, taskId: string, assignment: AssignmentSnapshot): MergeChecklist;
+/** The checklist as plain lines (the CLI, the lead, the TUI): the answer, then one line per row that applies. */
+export declare function checklistLines(list: MergeChecklist): string[];

package/dist/merge-checklist.js

@@ -0,0 +1,182 @@
+/** "Can I merge?" (docs/plans/plain-toolroll.md P1.6): one checklist per task, read from the records the task page,
+ * the result page and the pull request row already read, with nothing recomputed and nothing checked live. Each row
+ * says one fact about the task's current result; a blocker carries one existing act the person can take: Run checks,
+ * Retry, or Ask the agent to fix (Send back with a note naming the blocker). Nothing here acts: it is a read, and every
+ * act it names is the person's own post through its usual door.
+ *
+ * Rows Toolroll keeps no record of (up to date with main; conflicts outside a batch check) say so, rather than guess:
+ * GitHub shows them on the pull request. */
+import { assignmentOf } from "./assignment.js";
+import { pullRequestFollowOf, pullRequestViewOf, publishingOf } from "./pull-request-flow.js";
+import { releaseCiHoldOf, releaseCiRunningOf } from "./release-ci-hold.js";
+import { isRevisionFeedback } from "./result-review.js";
+import { approvalOf, deployGateScope } from "./scope.js";
+import { shipChecksForTask } from "./store.js";
+import { approvedCheckStateOf } from "./task-status.js";
+export const CHECKLIST_KEYS = ["plan", "build", "checks", "requirements", "pull-request", "pr-ci", "up-to-date", "conflicts", "comments", "release"];
+export const CHECKLIST_LABELS = {
+    plan: "Plan approved",
+    build: "Build finished",
+    checks: "Project checks passed on this commit",
+    requirements: "Requirements met",
+    "pull-request": "Pull request open",
+    "pr-ci": "PR CI passed on this exact commit",
+    "up-to-date": "Up to date with main",
+    conflicts: "No conflicts",
+    comments: "Review comments answered",
+    release: "Release check passed",
+};
+/** The one sentence for a row Toolroll keeps no record of. */
+export const NOT_RECORDED = "Toolroll doesn't record this. The pull request on GitHub shows it.";
+/** The act labels, the same words the result page uses. */
+export const CHECKLIST_ACT_LABELS = { "run-checks": "Run checks", retry: "Retry", fix: "Ask the agent to fix" };
+const short = (sha) => sha == null ? "this commit" : sha.slice(0, 7);
+/** The checklist for a task's current result, as `access` may see it; null when the task isn't visible there. */
+export function mergeChecklistOf(store, taskId, now, access, root) {
+    const assignment = assignmentOf(store, taskId, now, access, root);
+    if (assignment === null)
+        return null;
+    return checklistFromAssignment(store, taskId, assignment);
+}
+/** The checklist from an assignment snapshot already read (the task page reads one). */
+export function checklistFromAssignment(store, taskId, assignment) {
+    const active = assignment.activeTaskId;
+    const scope = store.getScope(active);
+    const task = store.getTask(active);
+    const receipt = assignment.receipt;
+    const run = receipt?.runId ?? null;
+    const head = receipt?.head ?? null;
+    const rows = [];
+    const row = (key, mark, say, act = null) => rows.push({ key, label: CHECKLIST_LABELS[key], mark, say, act });
+    // Plan approved: the approval as dispatch reads it.
+    if (scope === null)
+        row("plan", "no", "There's no plan yet.");
+    else if (approvalOf(scope).approved)
+        row("plan", "yes", scope.approvedBy == null ? "Approved." : `Approved by ${scope.approvedBy}.`);
+    else
+        row("plan", "no", "The plan waits for your approval.");
+    // Build finished: a result is recorded; a failed task retries.
+    if (task?.state === "failed")
+        row("build", "no", "The last build failed.", { kind: "retry", taskId: active });
+    else if (receipt !== null)
+        row("build", "yes", `Build #${receipt.runId} finished.`);
+    else if (assignment.state === "working" || assignment.state === "checking")
+        row("build", "waiting", "Building now.");
+    else
+        row("build", "waiting", "Nothing is built yet.");
+    // Project checks on this commit: the approved check as the Checks row reads it.
+    const check = receipt === null ? null : approvedCheckStateOf(receipt.checks);
+    if (receipt === null || check === null)
+        row("checks", "waiting", "Waits for a build.");
+    else if (check === "passed")
+        row("checks", "yes", receipt.checks.release != null && receipt.checks.status !== "passed" ? `Covered by release check #${receipt.checks.release.run}.` : `Passed on ${short(head)}.`);
+    else if (check === "failed")
+        row("checks", "no", `Failed on ${short(head)}${receipt.checks.exitCode === null ? "" : ` (exit ${receipt.checks.exitCode})`}.`, { kind: "fix", run: receipt.runId, note: `The project checks failed on ${short(head)}${receipt.checks.exitCode === null ? "" : ` (exit ${receipt.checks.exitCode})`}. Fix them so they pass.` });
+    else if (check === "running")
+        row("checks", "waiting", "Running now.");
+    else if (check === "off")
+        row("checks", "waiting", "Checks are off for this project; they run at release.");
+    else
+        row("checks", "no", check === "unreadable" ? "The check result couldn't be read." : "No check ran on this commit.", { kind: "run-checks", run: receipt.runId });
+    // Requirements: the result's own blockers, as Accept reads them.
+    const criteria = assignment.readiness?.blockers.filter(one => one.key === "criteria" || one.key === "high") ?? [];
+    if (receipt === null)
+        row("requirements", "waiting", "Waits for a build.");
+    else if (criteria.length > 0)
+        row("requirements", "no", criteria[0].message, { kind: "fix", run: receipt.runId, note: criteria.map(one => one.message).join("\n") });
+    else if (assignment.readiness?.verdict === "refuted")
+        row("requirements", "no", "The result doesn't match its plan.", { kind: "fix", run: receipt.runId, note: "The result doesn't match its plan. Fix it so it does." });
+    else
+        row("requirements", "yes", "Every requirement is met.");
+    // The pull request and its CI, as the task's pull request row reads them.
+    const view = run === null ? null : pullRequestViewOf(store, run);
+    const publishing = publishingOf(store, assignment.repo);
+    let merged = false;
+    if (view === null) {
+        if (!publishing.on) {
+            row("pull-request", "skip", "This project doesn't open pull requests.");
+            row("pr-ci", "skip", "No pull request.");
+        }
+        else {
+            row("pull-request", "waiting", receipt === null ? "Opens once it's built and accepted." : "Opens when you accept it.");
+            row("pr-ci", "waiting", "Runs once the pull request opens.");
+        }
+    }
+    else {
+        merged = view.state === "merged";
+        if (merged)
+            row("pull-request", "yes", view.prNumber === null ? "Merged." : `#${view.prNumber} merged.`);
+        else if (view.state === "opening")
+            row("pull-request", "waiting", "Opening now.");
+        else if (view.state === "failed" || view.state === "closed")
+            row("pull-request", "no", view.detail);
+        else
+            row("pull-request", "yes", `#${view.prNumber} is open.`);
+        const publication = store.publicationForRun(view.runId);
+        const follow = publication === null ? null : pullRequestFollowOf(store, publication.id);
+        const ship = shipChecksForTask(store, active);
+        const exact = publication !== null && follow !== null && follow.readyHead === publication.headSha;
+        if (merged)
+            row("pr-ci", "yes", "Merged.");
+        else if (view.state === "ready" || (view.state === "waiting" && view.fullCheck !== null))
+            row("pr-ci", exact ? "yes" : "waiting", exact ? `Passed on ${short(publication.headSha)}.` : "Passed, on an earlier commit.");
+        else if (view.state === "failing") {
+            const failing = ship?.checks.filter(one => one.state === "failed").map(one => one.workflow === null ? one.name : `${one.workflow} / ${one.name}`) ?? [];
+            const said = `Failed on ${short(publication?.headSha)}${failing.length === 0 ? "" : `: ${failing.slice(0, 3).join(", ")}${failing.length > 3 ? ", …" : ""}`}.`;
+            // A revision Toolroll already filed with the failure is the fix under way: no second one from here.
+            if (view.revisionTask !== null)
+                row("pr-ci", "no", `${said} Revision ${view.revisionTask} was filed with the failure.`);
+            else
+                row("pr-ci", "no", said, receipt === null ? null : { kind: "fix", run: receipt.runId, note: `PR CI failed on ${short(publication?.headSha)}${failing.length === 0 ? "" : ` (${failing.join(", ")})`}. Fix it so it passes.` });
+        }
+        else if (view.state === "running")
+            row("pr-ci", "waiting", "Running now.");
+        else if (view.state === "opening")
+            row("pr-ci", "waiting", "Runs once the pull request opens.");
+        else
+            row("pr-ci", view.state === "failed" || view.state === "closed" ? "skip" : "waiting", view.state === "failed" || view.state === "closed" ? "No open pull request." : "No CI has reported yet.");
+    }
+    // Up to date with main and conflicts: Toolroll keeps no record of either, except a batch check's conflict.
+    row("up-to-date", merged ? "yes" : "unknown", merged ? "Merged." : NOT_RECORDED);
+    if (merged)
+        row("conflicts", "yes", "Merged.");
+    else if (receipt?.checks.batch?.state === "conflict")
+        row("conflicts", "no", "It conflicted with another result in its batch check.", { kind: "fix", run: receipt.runId, note: "It conflicts with another change. Rebase it on main and resolve the conflict." });
+    else
+        row("conflicts", "unknown", NOT_RECORDED);
+    // Review comments: the saved notes and pull request review comments not yet sent back.
+    const notes = run === null ? [] : store.liveDiffComments(run).filter(one => isRevisionFeedback(one));
+    if (run === null)
+        row("comments", "waiting", "Waits for a build.");
+    else if (notes.length === 0)
+        row("comments", "yes", "None open.");
+    else
+        row("comments", "no", `${notes.length} note${notes.length === 1 ? "" : "s"} not sent back yet.`, { kind: "fix", run, note: "" });
+    // A release: its own check, as the release card reads it.
+    if (scope !== null && deployGateScope(scope)) {
+        if (releaseCiHoldOf(store, active) !== null || releaseCiRunningOf(store, active) !== null)
+            row("release", "waiting", "GitHub's checks are still running.");
+        else if (receipt !== null && receipt.checks.level === "full" && receipt.checks.status === "passed")
+            row("release", "yes", `The full check passed on ${short(head)}.`);
+        else if (receipt !== null && receipt.checks.status === "failed")
+            row("release", "no", "The release check failed.", { kind: "fix", run: receipt.runId, note: "The release check failed. Fix it so it passes." });
+        else
+            row("release", "waiting", "The release check hasn't run on this commit yet.");
+    }
+    else
+        row("release", "skip", "Not a release.");
+    const first = rows.find(one => one.mark === "no");
+    const unknown = rows.filter(one => one.mark === "unknown").map(one => one.label.toLowerCase());
+    const answer = merged ? "merged" : first !== undefined ? "no" : rows.some(one => one.mark === "waiting") ? "not-yet" : "yes";
+    const sentence = answer === "merged" ? "Already merged."
+        : answer === "no" ? `Not yet: ${first.label.toLowerCase()} — ${first.say}`
+            : answer === "not-yet" ? `Not yet: ${rows.find(one => one.mark === "waiting").label.toLowerCase()} — ${rows.find(one => one.mark === "waiting").say}`
+                : `Yes, as far as Toolroll records.${unknown.length === 0 ? "" : ` Check ${unknown.join(" and ")} on GitHub.`}`;
+    return { taskId, activeTaskId: active, run, head, answer, sentence, rows };
+}
+/** The checklist as plain lines (the CLI, the lead, the TUI): the answer, then one line per row that applies. */
+export function checklistLines(list) {
+    const MARK = { yes: "✓", no: "✗", waiting: "…", unknown: "?", skip: "–" };
+    return [`Can I merge ${list.activeTaskId}? ${list.sentence}`,
+        ...list.rows.filter(one => one.mark !== "skip").map(one => `  ${MARK[one.mark]} ${one.label}: ${one.say}${one.act === null ? "" : ` [${CHECKLIST_ACT_LABELS[one.act.kind]}]`}`)];
+}

package/dist/modes.d.ts

@@ -53,12 +53,10 @@ export type ModeTerms = {
      * fallback; fallback chains were removed in v115). Always false on new
      * modes; retained for digest and audit compatibility. */
     allowPaidFallback: boolean;
-    /** Whether this mode AUTHORIZES the bounded repair loop to draft AND
-     * auto-approve its own repair attempts (v40, evidence-review-v1) — the
-     * same precedent as the old paid-fallback grant: legacy modes default FALSE, a
-     * new authority is never inherited, only freshly signed. Without it, a
-     * short/refuted run with named unresolved criteria still gets exactly
-     * one drafted repair — it simply waits unapproved. */
+    /** Whether this mode AUTHORIZES repairing a failed check: drafting and
+     * auto-approving each attempt (check-repair.ts). Legacy modes default FALSE,
+     * a new authority is never inherited, only freshly signed. Without it a
+     * failed check waits for a person, whose repair takes the normal approval. */
     repairAuto: boolean;
     /** The signed cap on repair attempts per chain (0..3), counted over the
      * chain rooted at the original task. Meaningless (read as 0) unless
@@ -78,6 +76,8 @@ export type ModeTerms = {
     absoluteExpiry: string;
 };
 export declare const MODE_MAX_DAYS = 7;
+/** Repairs of one failed check's chain: what a person can start, and what the console's choice signs. The CLI signs 1 to 3. */
+export declare const CHECK_REPAIR_LIMIT = 2;
 /** The presets are STARTING POINTS the ceremony renders in full — the
  * signature always covers the resolved terms, never a label. */
 export declare function presetTerms(name: ModeName, absoluteExpiry: string): ModeTerms;

package/dist/modes.js

@@ -17,6 +17,8 @@ import { createHash } from "node:crypto";
 import { CHAT_PROVIDERS, isChatProvider } from "./contracts/chat-tables.js";
 import { canonicalJson } from "./canonical-json.js";
 export const MODE_MAX_DAYS = 7;
+/** Repairs of one failed check's chain: what a person can start, and what the console's choice signs. The CLI signs 1 to 3. */
+export const CHECK_REPAIR_LIMIT = 2;
 /** The presets are STARTING POINTS the ceremony renders in full — the
  * signature always covers the resolved terms, never a label. */
 export function presetTerms(name, absoluteExpiry) {
@@ -181,7 +183,7 @@ export function modeWords(terms) {
         ...(terms.allowPaidFallback
             ? ["a historical paid-fallback grant is retained on record but no longer used"] : []),
         ...(terms.repairAuto
-            ? ["historical automatic repair grants are retained on record but no longer schedule work"] : []),
+            ? [`a failed check repairs itself, at most ${terms.repairMaxAttempts} ${terms.repairMaxAttempts === 1 ? "try" : "tries"} per task, inside the plan you approved and under the limits above; a repair that plan doesn't cover, and the last failure, come to you`] : []),
         ...(terms.chatApprove
             ? [`your paired ${chatNames(chatApproveChatsOf(terms))} chat may approve this repository's plans and merge its ready pull requests, two taps each, without your password; a plan that widens permissions, exceeds the per-attempt cap above or touches protected paths still opens Toolroll`] : []),
         `everything above ends at ${terms.absoluteExpiry.slice(0, 16).replace("T", " ")} — revoking it earlier is one click, and every act it covered falls back to its own ceremony`,

package/dist/needs-you.d.ts

@@ -6,11 +6,14 @@
  * The words never name the machine's internals; `plainSentence` keeps a
  * recorded reason only when it is free of them. */
 /** What a person is asked for. */
-export type NeedKey = "approval" | "card" | "answer" | "questions" | "sign-in" | "stop-unproven" | "hold" | "choose-project" | "define-task" | "fix-request" | "choose-agent" | "fix-dependency" | "add-requirement" | "connect-builder" | "start-builder" | "vanished" | "review-result" | "rebuild" | "replan" | "earlier-version" | "other";
+export type NeedKey = "approval" | "card" | "answer" | "questions" | "sign-in" | "stop-unproven" | "hold" | "storage" | "choose-project" | "define-task" | "fix-request" | "choose-agent" | "fix-dependency" | "add-requirement" | "connect-builder" | "start-builder" | "vanished" | "review-result" | "rebuild" | "replan" | "earlier-version" | "history" | "finding" | "other";
 /** What the work waits for when no person can act. */
-export type WaitKey = "build-stopping" | "build-finishing" | "build-checking" | "other-computer" | "card-reply" | "card-time" | "card-ci";
+export type WaitKey = "build-stopping" | "build-finishing" | "build-checking" | "other-computer" | "card-reply" | "card-time" | "card-ci" | "plan-next" | "research-next" | "builders-busy" | "retry-later" | "app-update" | "other-task";
 /** The action's code: the WorkAction that owns the act, or one of the acts a surface renders itself. */
-export type NeedActionCode = "approve-scope" | "approve-card" | "answer-decision" | "inspect-decisions" | "sign-in" | "recheck-stopped" | "inspect-hold" | "place-task" | "write-scope" | "select-agent" | "repair-dependency" | "repair-capability" | "start-worker" | "reconcile-run" | "open-result" | "retry-task" | "inspect-task";
+/** The reason a storage hold carries before the check's own words (dispose.ts holdForStorage; dispatch.ts and
+ * work-index.ts read it back). */
+export declare const STORAGE_HOLD_PREFIX = "protected-storage \u2014 ";
+export type NeedActionCode = "approve-scope" | "approve-card" | "answer-decision" | "inspect-decisions" | "sign-in" | "recheck-stopped" | "inspect-hold" | "place-task" | "write-scope" | "select-agent" | "repair-dependency" | "repair-capability" | "start-worker" | "reconcile-run" | "open-result" | "retry-task" | "inspect-task" | "inspect-findings" | "unhold";
 export type NeedAction = {
     code: NeedActionCode;
     label: string;
@@ -23,10 +26,13 @@ export declare const START_BUILDER_HREF = "/start-builder";
 export declare const startBuilderHref: (taskId: string | null) => string;
 /** What starts a builder: run on the machine where the project lives, in the project's folder. */
 export declare const START_BUILDER_COMMAND = "toolroll up";
-/** `build`: the run a sentence names; `provider`: the agent that signed out. */
+/** `build`: the run a sentence names; `provider`: the agent that signed out; `task`: another task it names (an
+ * earlier version); `retry`: when Toolroll tries again, in words ("in 4 minutes"). */
 export type NeedContext = {
     build?: number | null;
     provider?: string | null;
+    task?: string | null;
+    retry?: string | null;
 };
 /** `useReason`: which recorded reasons say what is needed better than the default words. */
 type Need = {
@@ -69,9 +75,9 @@ export type ResultHoldUp = {
 export declare function resultHoldUpSentence(facts: Partial<ResultHoldUp>): string;
 export declare const NEED_ASK: Readonly<Record<NeedKey, Ask>>;
 export declare const WAITS: Readonly<Record<WaitKey, (context: NeedContext) => string>>;
-/** Words that name the machine's internals; no Needs you or Waiting sentence carries them. */
-export declare const BANNED_WORDS: readonly ["witness", "unproven", "quiescence", "quiescent", "digest", "scope digest"];
-export declare const hasInternalWords: (text: string) => boolean;
+/** Words that name the machine's internals (plain-words.ts, the one table); no Needs you or Waiting sentence carries
+ * them, and a recorded reason that does is replaced by the need's own words. */
+export { BANNED_WORDS, PLAIN_WORDS, bannedWordsIn, hasInternalWords } from "./plain-words.js";
 /** The sentence for a need: its recorded reason when the need keeps one and
  * it reads plainly, otherwise the need's own words. */
 export declare function needSentence(key: NeedKey, reason: string | null, context?: NeedContext): string;
@@ -89,7 +95,24 @@ export declare function processNeedOf(fact: {
     wait: WaitKey;
     build: number;
 } | null;
-/** Dispatch and work-index codes that wait on a person, as their need. */
+/** The stages a code reads as (task-status.ts TaskStage). */
+export type CodeStage = "queued" | "planning" | "needs-you" | "waiting" | "building" | "checking" | "reviewing" | "finished" | "complete" | "failed" | "stopped";
+/** Every dispatch and work-index code, as what it means for a person (docs/plans/plain-toolroll.md P1.2): a need with
+ * the act that resolves it, a wait (worded as what it waits for), or a plain state. A code is exactly one of these.
+ * `act` is the work-index row's own act for the code, the same act it had before this table: a need keeps its act, a
+ * wait offers none. `stopped` and `failed` keep their own act too (Resume, Retry). */
+export type CodeReading = {
+    stage: CodeStage;
+    need?: NeedKey;
+    wait?: WaitKey;
+    act?: NeedActionCode | "inspect-stop" | "resume-run" | "unhold" | "answer-agent" | "inspect-run" | null;
+};
+export declare const CODE_READING: Readonly<Record<string, CodeReading>>;
+/** A code that waits on Toolroll or another task: no person is asked. */
+export declare const isWaitCode: (code: string) => boolean;
+/** Notification kinds that need nothing from a person: they stay in the activity log and never ping a phone. */
+export declare const ACTIVITY_ONLY_KINDS: ReadonlySet<string>;
+/** Dispatch and work-index codes that wait on a person, as their need (read from CODE_READING). */
 export declare const CODE_NEED: Readonly<Record<string, NeedKey>>;
 /** A stopped run's recorded reason code, in words (the run record, the thread, a failed task's status). */
 export declare const RUN_REASON_WORDS: Readonly<Record<string, string>>;
@@ -139,4 +162,3 @@ export declare function missedRequirementLine(statement: string): string;
 export declare const RETRY_NOTE_LIMIT = 500;
 /** Retry's note, prefilled with the suggestion: cut to what the field takes, at a word, so the form always posts. */
 export declare function retryNoteOf(suggestion: string): string;
-export {};