toolroll 0.9.7 → 0.9.9

package/dist/lead-status.js

@@ -1,10 +1,10 @@
 /** Cheap lead-facing status. Every fact comes from indexed SQLite records;
  * this module never opens a repository, retained evidence, or a live log. */
-import { COMPLETION_ACTION } from "./result-completion.js";
+import { familyCompleted } from "./result-completion.js";
 import { windowLabel } from "./provider-limits.js";
 import { openAuthPauses, signInCommand, signInReason } from "./provider-auth.js";
 import { BUILT_IN, checkSuitesOf } from "./store.js";
-import { workIndexPage } from "./work-index.js";
+import { workIndexPage, workReadyForReview } from "./work-index.js";
 const maybeNumber = (value) => value === null || value === undefined || !Number.isInteger(Number(value)) ? null : Number(value);
 const CHECK_COLUMNS = "rc.status AS check_status, rc.exit_code AS check_exit_code, rc.suites_json AS check_suites_json";
 function checkOf(row) {
@@ -90,9 +90,9 @@ export function taskWaitSnapshot(store, taskId, now, watchedRun) {
         if (state !== "done")
             return answer("Ready", "Review result", true, 0, "ready");
     }
-    const completion = result === undefined ? undefined : store.handle.prepare(`SELECT 1 AS hit FROM action_ledger INDEXED BY work_completion
-    WHERE task_id = ? AND action = ? AND source = 'work' AND run_id = ? LIMIT 1`).get(taskId, COMPLETION_ACTION, Number(result["id"]));
-    if (state === "done" && completion !== undefined)
+    // A completed family is Complete from any of its tasks.
+    const completed = state === "done" && familyCompleted(store, taskId);
+    if (completed)
         return answer("Complete", "No action needed", true, 0, "complete");
     if (state === "done")
         return answer("Ready", "Review result", true, 0, "ready");
@@ -113,7 +113,7 @@ export function taskWaitSnapshot(store, taskId, now, watchedRun) {
         return answer("Needs a person", next, true, 1, "needs-person");
     }
     if (task["plan"] === "drafted")
-        return answer("Needs a person", "Review plan", true, 1, "needs-person");
+        return answer("Needs a person", "Approve plan", true, 1, "needs-person");
     if (Number(task["strikes"] ?? 0) >= 3)
         return answer("Needs a person", "Review repeated failures", true, 1, "needs-person");
     // An admitted attempt is already the work being watched. Its immutable
@@ -168,6 +168,15 @@ function queueReason(row) {
     return "ready for a worker";
 }
 /** Whole-installation status, deliberately aggregated and bounded. */
+/** The one-off repair on start. An older build left finished runs' process
+ * exits unrecorded and counted completed families as waiting; nothing about
+ * a status is stored, so recording every exit that can now be proven and
+ * re-deriving each open task's headline from the shared projection clears
+ * them. What can't be proven stays as it was. */
+export function repairStaleStatuses(store, now) {
+    const exitsRecorded = store.recordFinishedRunExits(now);
+    return { exitsRecorded, readyForReview: workReadyForReview(store, now, { principal: "operator", repos: null, includeUnplaced: true }, 0).count };
+}
 export function installationStatus(store, now) {
     const runningRows = store.handle.prepare(`SELECT run.id, run.role, run.phase, ref.external_id AS task
     FROM run INDEXED BY work_unfinished
@@ -208,22 +217,10 @@ export function installationStatus(store, now) {
         if (queuedTasks.length < 8)
             queuedTasks.push({ task: String(row["id"]), reason });
     }
-    const waitingCount = Number(store.handle.prepare(`SELECT COUNT(*) AS n FROM task INDEXED BY task_by_state
-    JOIN task_ref AS ref INDEXED BY sqlite_autoindex_task_ref_1 ON ref.backend = ? AND ref.external_id = task.id
-    WHERE task.state = 'done' AND EXISTS (SELECT 1 FROM run INDEXED BY work_result
-      WHERE run.task_ref = ref.id AND run.finished_at IS NOT NULL AND run.role IN ('builder','scout'))
-      AND NOT EXISTS (SELECT 1 FROM action_ledger INDEXED BY work_completion
-        WHERE action_ledger.task_id = task.id AND action_ledger.action = ? AND action_ledger.source = 'work'
-          AND action_ledger.run_id = (SELECT id FROM run INDEXED BY work_result WHERE task_ref = ref.id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1))`)
-        .get(BUILT_IN, COMPLETION_ACTION)?.["n"] ?? 0);
-    const waitingRows = store.handle.prepare(`SELECT task.id AS task, result.id, ${CHECK_COLUMNS}
-    FROM task INDEXED BY task_done_recent
-    JOIN task_ref AS ref INDEXED BY sqlite_autoindex_task_ref_1 ON ref.backend = ? AND ref.external_id = task.id
-    JOIN run AS result ON result.id = (SELECT id FROM run INDEXED BY work_result WHERE task_ref = ref.id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1)
-    LEFT JOIN run_check AS rc ON rc.run = result.id
-    WHERE task.state = 'done' AND NOT EXISTS (SELECT 1 FROM action_ledger INDEXED BY work_completion
-      WHERE action_ledger.task_id = task.id AND action_ledger.action = ? AND action_ledger.source = 'work' AND action_ledger.run_id = result.id)
-    ORDER BY task.updated_at DESC, task.id DESC LIMIT 5`).all(BUILT_IN, COMPLETION_ACTION);
+    // One per family, from the same projection as the Tasks list: a completed
+    // family (root or any revision) and a superseded version never count.
+    const ready = workReadyForReview(store, now, { principal: "operator", repos: null, includeUnplaced: true }, 5);
+    const checkRow = (run) => store.handle.prepare(`SELECT ${CHECK_COLUMNS} FROM run_check AS rc WHERE rc.run = ?`).get(run);
     // Run ids grow with time, so the newest finished release check is the
     // first finished row down the partial index.
     const release = store.handle.prepare(`SELECT run.id, run.finished_at, ${CHECK_COLUMNS}, ref.external_id AS task
@@ -240,7 +237,7 @@ export function installationStatus(store, now) {
             reasons: [...reasons].map(([reason, count]) => ({ reason, count })).sort((a, b) => b.count - a.count || a.reason.localeCompare(b.reason)),
             tasks: queuedTasks,
         },
-        waitingForReview: { count: waitingCount, results: waitingRows.map(row => ({ task: String(row["task"]), run: Number(row["id"]), check: checkOf(row) })) },
+        waitingForReview: { count: ready.count, results: ready.results.map(one => ({ task: one.taskId, run: one.run, check: checkOf(one.run === null ? undefined : checkRow(one.run)) })) },
         releaseCheck: release === undefined ? null : { task: String(release["task"]), run: Number(release["id"]), finishedAt: release["finished_at"] == null ? null : String(release["finished_at"]), check: checkOf(release) },
         planWindows: store.handle.prepare(`SELECT provider, window, used_percent, window_minutes, resets_at, reached, plan, observed_at
       FROM provider_limit INDEXED BY sqlite_autoindex_provider_limit_1 ORDER BY provider, window`).all().map(row => ({
@@ -271,7 +268,7 @@ export function renderInstallationStatus(status) {
     }
     lines.push(status.running.count === 0 ? "Building: none" : `Building: ${status.running.count} — ${status.running.tasks.map(one => `${one.task} (#${one.run}, ${one.phase})`).join(", ")}${status.running.count > status.running.tasks.length ? ", …" : ""}`);
     lines.push(status.queued.count === 0 ? "Queued: none" : `Queued: ${status.queued.count} — ${status.queued.tasks.map(one => `${one.task} (${one.reason})`).join(", ")}${status.queued.count > status.queued.tasks.length ? ", …" : ""}`);
-    lines.push(status.waitingForReview.count === 0 ? "Ready for review: none" : `Ready for review: ${status.waitingForReview.count} — ${status.waitingForReview.results.map(one => `${one.task} (#${one.run})`).join(", ")}${status.waitingForReview.count > status.waitingForReview.results.length ? ", …" : ""}`);
+    lines.push(status.waitingForReview.count === 0 ? "Ready for review: none" : `Ready for review: ${status.waitingForReview.count} — ${status.waitingForReview.results.map(one => one.run === null ? one.task : `${one.task} (#${one.run})`).join(", ")}${status.waitingForReview.count > status.waitingForReview.results.length ? ", …" : ""}`);
     if (status.releaseCheck === null) {
         lines.push("Release check: none recorded");
     }

package/dist/modes.d.ts

@@ -29,7 +29,9 @@ export type ModeTerms = {
     planAuto: boolean;
     /** Attended mint without the per-mint password — signer only (D8). */
     quickMint: boolean;
-    /** Historical signed field; new modes leave it false and no worker consumes it. */
+    /** Historical signed field; new modes leave it false and no worker consumes
+     * it. Automatic review is the project's review switch (review-switch.ts),
+     * on by default while a hands-off mode is active. */
     reviewAuto: boolean;
     /** Historical signed retry term, retained for digest and audit compatibility. */
     reviewRetryAuto: boolean;

package/dist/modes.js

@@ -157,7 +157,9 @@ export function modeWords(terms) {
         terms.planAuto
             ? "plans for your pre-authorized filings auto-approve only when the goal, exclusions, paths, acceptance criteria, risk, budget, and agent route remain exactly unchanged; provide a goal, paths and acceptance criteria upfront; amendments and unresolved questions still wait for you"
             : "planner-generated plans wait for your approval",
-        "finished work and saved checks go to the lead or user; no separate model review runs",
+        terms.name === "hands-off"
+            ? "automatic review is on for this project unless you turn it off (`toolroll review off --repo <path>`): each finished build whose check passes (or that finishes, with checks Off) gets one read-only review by the project's review agent; a HIGH finding sends it back once as a revision filed under this mode, a HIGH on that revision comes to you, MEDIUM and LOW findings come to you as suggested follow-ups, and a review that fails or times out never holds the work — it reaches you marked not reviewed"
+            : "finished work and saved checks go to the lead or user; automatic review runs only where a project turns it on (`toolroll review on --repo <path>`)",
         ...(terms.reviewAuto || terms.reviewRetryAuto
             ? ["historical review grants are retained on record but no longer schedule work"] : []),
         terms.perAttemptBudgetMicrousd === null

package/dist/needs-you.d.ts

@@ -0,0 +1,55 @@
+/** Every reason a task, result or flow card can wait on a person, in one
+ * place: the plain sentence it shows and the one action that resolves it
+ * (task-status.ts reads it for every surface). A reason no person can act
+ * on is not Needs you: it is a Waiting reason, worded as what it waits for.
+ *
+ * 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" | "confirm-stopped" | "check-stopped" | "hold" | "choose-project" | "define-task" | "fix-request" | "choose-agent" | "fix-dependency" | "add-requirement" | "connect-builder" | "start-builder" | "vanished" | "review-result" | "rebuild" | "earlier-version" | "other";
+/** What the work waits for when no person can act. */
+export type WaitKey = "build-stopping" | "other-computer" | "card-reply" | "card-time" | "card-ci";
+/** 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" | "confirm-stopped" | "inspect-hold" | "place-task" | "write-scope" | "select-agent" | "repair-dependency" | "repair-capability" | "start-worker" | "reconcile-run" | "open-result" | "retry-task" | "inspect-task";
+export type NeedAction = {
+    code: NeedActionCode;
+    label: string;
+};
+/** `build`: the run a sentence names; `provider`: the agent that signed out. */
+export type NeedContext = {
+    build?: number | null;
+    provider?: string | null;
+};
+/** `useReason`: which recorded reasons say what is needed better than the default words. */
+type Need = {
+    sentence: (context: NeedContext) => string;
+    action: NeedAction;
+    useReason?: (reason: string) => boolean;
+    /** How a kept reason reads: by default the reason alone. */
+    withReason?: (reason: string) => string;
+};
+export declare const NEEDS: Readonly<Record<NeedKey, Need>>;
+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;
+/** 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;
+export declare function waitSentence(key: WaitKey | undefined, reason: string | null, context?: NeedContext): string;
+/** A finished run Toolroll can't prove stopped (store.stopQuiescenceFact):
+ * a person can confirm it only when nothing of it may still be running.
+ * `unknown`: Toolroll can't check, so the person confirms they checked. */
+export declare function processNeedOf(fact: {
+    run: number;
+    kind: "open" | "alive" | "elsewhere" | "unprovable" | "unknown";
+} | null): {
+    need: "confirm-stopped" | "check-stopped";
+    build: number;
+} | {
+    wait: WaitKey;
+    build: number;
+} | null;
+/** Dispatch and work-index codes that wait on a person, as their need. */
+export declare const CODE_NEED: Readonly<Record<string, NeedKey>>;
+export {};

package/dist/needs-you.js

@@ -0,0 +1,83 @@
+/** Every reason a task, result or flow card can wait on a person, in one
+ * place: the plain sentence it shows and the one action that resolves it
+ * (task-status.ts reads it for every surface). A reason no person can act
+ * on is not Needs you: it is a Waiting reason, worded as what it waits for.
+ *
+ * The words never name the machine's internals; `plainSentence` keeps a
+ * recorded reason only when it is free of them. */
+const always = () => true;
+const build = (context) => context.build == null ? "the last build" : `build #${context.build}`;
+const Build = (context) => context.build == null ? "The last build" : `Build #${context.build}`;
+export const NEEDS = {
+    approval: { sentence: () => "Review the plan and approve it to start.", action: { code: "approve-scope", label: "Approve plan" } },
+    card: { sentence: () => "This card is waiting for your approval.", action: { code: "approve-card", label: "Approve card" } },
+    answer: { sentence: () => "Answer the question so the work can continue.", action: { code: "answer-decision", label: "Answer the question" }, useReason: always },
+    questions: { sentence: () => "Too many questions are open. Answer one so this task can start.", action: { code: "inspect-decisions", label: "Answer questions" } },
+    "sign-in": { sentence: context => `${context.provider ?? "Your agent"} needs you to sign in again. The task starts on its own after.`, action: { code: "sign-in", label: "Sign in again" }, useReason: reason => /sign in|API key/i.test(reason) },
+    "confirm-stopped": { sentence: context => `Toolroll can't confirm ${build(context)} stopped. Nothing from it is running.`, action: { code: "confirm-stopped", label: "Confirm it stopped" } },
+    // Toolroll can't look at all: never "nothing is running"; the person checks, says so, then confirms.
+    "check-stopped": { sentence: context => `Toolroll can't check whether ${build(context)} stopped. Make sure nothing from it is running, then confirm.`, action: { code: "confirm-stopped", label: "Confirm it stopped" } },
+    hold: { sentence: () => "A hold is keeping this task from starting. Review it to release it.", action: { code: "inspect-hold", label: "Review hold" } },
+    "choose-project": { sentence: () => "Choose a project so a builder can start.", action: { code: "place-task", label: "Choose a project" } },
+    "define-task": { sentence: () => "Say what the task should do so it can be planned.", action: { code: "write-scope", label: "Define the task" } },
+    "fix-request": { sentence: () => "The request can't be planned as written. Edit it so the planner can start.", action: { code: "write-scope", label: "Edit the request" } },
+    "choose-agent": { sentence: () => "Choose an agent to build this.", action: { code: "select-agent", label: "Choose an agent" } },
+    "fix-dependency": { sentence: () => "A task this one waits on didn't finish. Fix or remove it so this one can start.", action: { code: "repair-dependency", label: "Fix the required task" },
+        useReason: reason => /didn't finish|did not finish|before it finished/i.test(reason), withReason: reason => `${reason.replace(/[.\s]*$/, ".")} Fix or remove it so this one can start.` },
+    "add-requirement": { sentence: () => "This project is missing something the task needs. Add it so a builder can start.", action: { code: "repair-capability", label: "Add the requirement" } },
+    "connect-builder": { sentence: () => "No builder works on this project yet. Connect one so the task can start.", action: { code: "start-worker", label: "Connect a builder" } },
+    "start-builder": { sentence: () => "The builder for this project is offline. Start it and the task begins on its own.", action: { code: "start-worker", label: "Start the builder" } },
+    vanished: { sentence: context => `${Build(context)} stopped without finishing. Check it, then retry.`, action: { code: "reconcile-run", label: "Check the build" } },
+    "review-result": { sentence: () => "Check the result, then accept it or ask for changes.", action: { code: "open-result", label: "Review result" } },
+    // Accepting it would not help: it was built to terms that are no longer the plan.
+    rebuild: { sentence: context => `${Build(context)} was made to an earlier plan. Build it again to the current plan.`, action: { code: "retry-task", label: "Build again" } },
+    "earlier-version": { sentence: () => "An earlier version of this task still needs you. Finish it first.", action: { code: "inspect-task", label: "Open earlier version" } },
+    other: { sentence: () => "Open the task to see what it needs from you.", action: { code: "inspect-task", label: "Open the task" }, useReason: always },
+};
+export const WAITS = {
+    "build-stopping": context => `Waiting for ${build(context)} to stop. Nothing is needed from you.`,
+    "other-computer": context => `Waiting for the computer that ran ${build(context)} to confirm it stopped.`,
+    "card-reply": () => "Waiting for a reply.",
+    "card-time": () => "Waiting before moving on.",
+    "card-ci": () => "Waiting for the pull request's checks.",
+};
+/** Words that name the machine's internals; no Needs you or Waiting sentence carries them. */
+export const BANNED_WORDS = ["witness", "unproven", "quiescence", "quiescent", "digest", "scope digest"];
+const BANNED = new RegExp(`\\b(?:${BANNED_WORDS.join("|")})\\b`, "i");
+export const hasInternalWords = (text) => BANNED.test(text);
+/** The sentence for a need: its recorded reason when the need keeps one and
+ * it reads plainly, otherwise the need's own words. */
+export function needSentence(key, reason, context = {}) {
+    const need = NEEDS[key];
+    const plain = reason?.trim() || null;
+    if (need.useReason === undefined || plain === null || !need.useReason(plain) || hasInternalWords(plain))
+        return need.sentence(context);
+    return need.withReason === undefined ? plain : need.withReason(plain);
+}
+export function waitSentence(key, reason, context = {}) {
+    if (key !== undefined)
+        return WAITS[key](context);
+    const plain = reason?.trim() || null;
+    return plain !== null && !hasInternalWords(plain) ? plain : "Waiting for the work to continue on its own.";
+}
+/** A finished run Toolroll can't prove stopped (store.stopQuiescenceFact):
+ * a person can confirm it only when nothing of it may still be running.
+ * `unknown`: Toolroll can't check, so the person confirms they checked. */
+export function processNeedOf(fact) {
+    if (fact === null)
+        return null;
+    if (fact.kind === "unprovable")
+        return { need: "confirm-stopped", build: fact.run };
+    if (fact.kind === "unknown")
+        return { need: "check-stopped", build: fact.run };
+    return { wait: fact.kind === "elsewhere" ? "other-computer" : "build-stopping", build: fact.run };
+}
+/** Dispatch and work-index codes that wait on a person, as their need. */
+export const CODE_NEED = {
+    "signed-out": "sign-in", "needs-approval": "approval", "waiting-decision": "answer", "decision-queue": "answer",
+    "needs-project": "choose-project", "needs-scope": "define-task", "planner-source": "fix-request", "needs-agent-profile": "choose-agent",
+    "terminal-dependency": "fix-dependency", "missing-requirement": "add-requirement", "no-worker-registered": "connect-builder",
+    "no-worker-online": "start-builder", "vanished-run": "vanished", "needs-verification": "review-result", "proof-refuted": "review-result",
+    "no-build-record": "review-result", "verification-needed": "review-result", "evidence-mismatch": "review-result",
+    "record-incomplete": "review-result", "evidence-damaged": "review-result",
+};

package/dist/operate.d.ts

@@ -37,6 +37,8 @@ export type OperateOptions = {
     releaseIo?: ReleaseIo;
     /** Injected by tests: the bin whose real path says how Toolroll was installed. */
     installBin?: string;
+    /** Injected by tests: where `storage` looks for leftover test temp folders (default: the temp folder and /tmp). */
+    tempRoots?: readonly string[];
     openDatabase?: (file: string) => Store;
     now?: Date;
     /**