toolroll 0.9.14 → 0.9.15

package/dist/browser-crew.d.ts

@@ -4,7 +4,8 @@ import type { WorkIndexItem, WorkIndexPage } from './work-index.js';
 /** The index is navigation only. Controls retain their exact owning task, run,
  * decision and approval ceremony; opening a result keeps its saved execution. */
 export declare function browserWorkActionHref(item: WorkIndexItem): string | null;
-/** Render an already-admitted page without repeating its database query. */
+/** Render an already-admitted page without repeating its database query. Every task reads its one headline, the
+ * same words as the Tasks list, task page and result page. */
 export declare function browserCrewFromIndex(page: WorkIndexPage, conversationId?: string): {
     crew: BrowserCrewItem[];
     crewTruncated: boolean;

package/dist/browser-crew.js

@@ -32,7 +32,8 @@ export function browserWorkActionHref(item) {
                         : action.code === 'start-worker' || action.code === 'repair-dependency' ? '#run-status' : '';
     return `/t/${encodeURIComponent(item.rootId)}?version=${encodeURIComponent(taskId)}` + anchor;
 }
-/** Render an already-admitted page without repeating its database query. */
+/** Render an already-admitted page without repeating its database query. Every task reads its one headline, the
+ * same words as the Tasks list, task page and result page. */
 export function browserCrewFromIndex(page, conversationId) {
     const link = (href) => conversationId && href.startsWith('/chat?') ? href + '&conversation=' + encodeURIComponent(conversationId) : href;
     const rows = page.items.map(summary => {

package/dist/browser-workspace.d.ts

@@ -7,11 +7,11 @@ export { browserCrewFromIndex, browserWorkActionHref } from './browser-crew.js';
 import type { Store } from './store.js';
 import type { WorkSummaryAccess } from './work-summary.js';
 import type { StatusTone } from './workspace-ui.js';
-import type { Ask } from './needs-you.js';
+import type { Ask, AskChip } from './needs-you.js';
 import type { WorkIndexGroup } from './work-index.js';
 import type { AssignmentCard } from './assignment-ui.js';
 import type { TaskStatus } from './task-status.js';
-import type { ResultActs } from './result-acts.js';
+import type { AcceptLabel, ResultActFacts, ResultActs } from './result-acts.js';
 import type { FirstRunStep, FirstTaskSuggestion, JourneyStep } from './first-run.js';
 export type BrowserProject = {
     name: string;
@@ -125,8 +125,10 @@ export type BrowserTasksView = {
             tone: StatusTone;
             token: string;
         };
-        /** What a Needs you row asks (its chip); null for every other row. */
+        /** What a Needs you row asks: its group. */
         ask: Ask | null;
+        /** The row's chip under its group: the specific ask (Plan, Result, Mismatch, Plan changed, Failed, Builder offline), or none. */
+        chip: AskChip | null;
         group: BrowserTaskGroup;
         action: BrowserLink | null;
         detail: string | null;
@@ -367,17 +369,41 @@ export type BrowserTaskView = {
     rebuild?: {
         action: string;
     } | null;
-    /** A failed task's recorded reason in one line (the run's reason, the failing check's last error line, or that none was
-     * recorded) and where its log lines are; and Retry itself, with an optional note. */
-    failure?: {
+    /** What a failed task missed, in one line (the requirement it missed, the failing check's error line, or the stop
+     * reason), the evidence line behind it, one suggestion of what to change, and where to see it (its build's result
+     * page, or that exact check-log line); and Retry itself, its note starting with the suggestion. */
+    failure?: BrowserFailure | null;
+    retry?: {
+        action: string;
+        note?: string;
+    } | null;
+    /** Run checks in place, on a status row that offers it: posts and comes back to this page. */
+    runChecks?: BrowserRunChecks | null;
+    /** A live build: the step it is on (or stuck on, with the act that helps), and the earlier attempts that stopped
+     * before it, folded into one quiet line. */
+    progress?: {
         line: string;
-        link: {
-            label: string;
-            href: string;
+        stuck: {
+            step: number;
+            why: string | null;
+            line: string;
+            action: BrowserLink | null;
         } | null;
     } | null;
-    retry?: {
+    /** Stop, on the Building card: the exact live build's stop form (posts its run id). */
+    stop?: {
         action: string;
+        run: number;
+    } | null;
+    /** The Building card's link to the live build's own record ("Build #N record", /r/<id>). */
+    record?: BrowserLink | null;
+    earlier?: {
+        summary: string;
+        attempts: {
+            label: string;
+            href: string;
+            text: string | null;
+        }[];
     } | null;
     /** Server cards that may need a person now (stop/resume, scope prompt, plan, live attempt). */
     lead: {
@@ -470,6 +496,12 @@ export type BrowserResultPanel = {
             returnTo: string;
         } | null;
     } | null;
+    /** The Requirements row's counts, so it updates as the person answers their checks (null when it doesn't count them). */
+    requirements?: {
+        met: number;
+        total: number;
+        yours: number;
+    } | null;
     /** Storage limits on saved output (shortened logs or diffs): shown on request. */
     limits: string[];
     tabs: {
@@ -518,13 +550,19 @@ export type BrowserCheckItem = {
     }[];
 };
 /** The result's one decision: what Accept is called, why it isn't plain
- * Accept, and what pressing it does. */
+ * Accept and finish, and what pressing it does. `base`: the same words before
+ * the person's own checks, which the page adds as they answer them. */
 export type BrowserResultDecision = {
-    label: "Accept" | "Accept without checks";
+    label: AcceptLabel;
     ready: boolean;
     why: string | null;
     effect: string;
     sentence: string;
+    base?: {
+        label: AcceptLabel;
+        ready: boolean;
+        why: string | null;
+    };
 };
 /** A Needs you action: a link, (Confirm it stopped) a form behind the password, (Build again) one
  * button, or (on the result itself) Accept, which records the person's acceptance; `note` asks why
@@ -587,12 +625,17 @@ export type BrowserResultView = {
             detail: string;
             control: string;
         } | null;
+        /** Accept and finish: the exact receipt read; `accept` when the one request also records the person's acceptance
+         * (`note`: the words over the reason field it asks for, or null for none). */
         complete: {
             action: string;
             receipt: string;
             run: number;
+            accept?: {
+                note: string | null;
+            } | null;
         } | null;
-        /** Words for the result's Accept: Mark complete when offered, else the Needs you acceptance. */
+        /** Words for the result's Accept: Accept and finish when offered, else the Needs you acceptance. */
         decision: BrowserResultDecision | null;
         checks: {
             detail: string;
@@ -617,12 +660,24 @@ export type BrowserResultView = {
         } | null;
         /** The one ink act that resolves the result, the one outline act beside it, and why it can't be accepted yet (result-acts.ts). */
         acts: ResultActs;
+        /** The facts the acts were chosen from, so the page chooses again as the person answers their checks. */
+        actFacts?: ResultActFacts;
         /** Run checks on this result's commit: the project's check, when it didn't run. */
-        runChecks: {
-            action: string;
-            level: "quick" | "full";
-            returnTo: string;
-        } | null;
+        runChecks: BrowserRunChecks | null;
+        /** A failed build's result: what it missed and the suggestion Retry's note starts with; Retry itself when the task
+         * can be retried from here. Null for every other result. */
+        failure?: (BrowserFailure & {
+            retry: {
+                action: string;
+                note: string;
+            } | null;
+            /** A failed task's delivered result, accepted only in outline with a reason (the task's accept-proof). */
+            acceptAnyway?: {
+                action: string;
+                run: number;
+                returnTo: string;
+            } | null;
+        }) | null;
         /** The raw run record, under Details: its facts and the full record. */
         record: {
             build: number;
@@ -635,6 +690,7 @@ export type BrowserResultView = {
         /** The signed scope; null when none was filed. */
         intent: {
             approval: string;
+            approvedAt: string | null;
             html: string;
         } | null;
         noRun: string | null;
@@ -647,6 +703,20 @@ export type BrowserResultView = {
         }[];
     } | null;
 };
+export type BrowserFailure = {
+    line: string;
+    evidence: string | null;
+    suggestion: string;
+    link: {
+        label: string;
+        href: string;
+    } | null;
+};
+export type BrowserRunChecks = {
+    action: string;
+    level: "quick" | "full";
+    returnTo: string;
+};
 /** One zone on a flow's canvas: its step, where it leads, and where it sits. */
 export type BrowserFlowStage = {
     id: string;

package/dist/chat-actions.d.ts

@@ -202,7 +202,7 @@ export declare const CHAT_ACTIONS: {
         readonly password: true;
     };
     readonly result_accept: {
-        readonly label: "Mark complete";
+        readonly label: "Accept and finish";
         readonly protected: true;
         readonly password: false;
     };

package/dist/chat-actions.js

@@ -12,7 +12,7 @@ import { approve, authenticateApprover, describeScope, scopeAuthorityOf, } from
 import { readVerifiedArtifact, scanForSecrets } from "./evidence.js";
 import { readAuthModeStrict } from "./keys.js";
 import { parseProof } from "./proof.js";
-import { assignmentOf, checkAssignmentAsOperator } from "./assignment.js";
+import { acceptAndCompleteAsOperator, assignmentOf } from "./assignment.js";
 import { getDecision, recordDecision, retireDecision } from "./project-memory.js";
 import { resumeTaskStop, taskControlOf } from "./task-control.js";
 import { addToolTo, catalogTool, projectToolsOf, removeToolFrom, toolCommandLine, validateToolSpec } from "./project-tools.js";
@@ -108,7 +108,7 @@ export const CHAT_ACTIONS = {
     decision_record: { label: "Record decision", protected: false, password: false },
     decision_retire: { label: "Retire decision", protected: false, password: false },
     scope_approve: { label: "Approve work", protected: true, password: true },
-    result_accept: { label: "Mark complete", protected: true, password: false },
+    result_accept: { label: "Accept and finish", protected: true, password: false },
     task_cancel: { label: "Cancel task", protected: true, password: false },
     task_resume: { label: "Resume task", protected: true, password: true },
 };
@@ -1098,7 +1098,9 @@ export function executeSharedAction(store, who, id, payload, now, options) {
                     throw Error("The comparison terms changed. Nothing was approved.");
             }
             else if (payload.operation === "result_accept") {
-                const completed = checkAssignmentAsOperator(store, task, String(payload.state["receipt"] ?? ""), who, now, options.root);
+                // Accept and finish, as on the result page: whether a check only the person makes is accepted
+                // too is decided inside the same transaction, against the receipt as it stands.
+                const completed = acceptAndCompleteAsOperator(store, task, { runId: null, receiptDigest: String(payload.state["receipt"] ?? ""), note: null }, who, now, options.root);
                 if (!completed.ok)
                     throw Error(completed.message);
             }
@@ -1125,7 +1127,7 @@ export function executeSharedAction(store, who, id, payload, now, options) {
             const said = payload.operation === "skill_test"
                 ? "Skill test created. Existing approval rules apply."
                 : payload.operation === "result_accept"
-                    ? "Marked complete. The recorded checks are unchanged."
+                    ? "Accepted and finished. The recorded checks are unchanged."
                     : payload.operation === "scope_approve"
                         ? "The exact work is approved."
                         : payload.operation === "task_cancel"

package/dist/chat-delivery-state.d.ts

@@ -76,7 +76,7 @@ export type ChatContent = {
         label: string;
         path: string;
     };
-    /** More link buttons after `link`: [Look first] beside [Merge] or [Mark complete]. */
+    /** More link buttons after `link`: [Look first] beside [Merge] or [Accept and finish]. */
     also?: Array<{
         label: string;
         path: string;

package/dist/chat-voice.d.ts

@@ -24,7 +24,7 @@ export type FinishedFact = {
     checks: "passed" | "failed" | "not-run" | "off" | null;
     report: boolean;
     completedBy: string | null;
-    /** An open pull request carries this result: the ask is "Merge it?" rather than "Mark it complete?". */
+    /** An open pull request carries this result: the ask is "Merge it?" rather than "Accept and finish it?". */
     pullRequest?: boolean;
     /** The lead did this (built it, or marked it complete), so the lead says "I". */
     lead?: boolean;
@@ -40,10 +40,10 @@ export type FinishedFact = {
 /** The two buttons under a result ready for a person: the real next step, then a look first. */
 export declare const READY_ACTIONS: {
     readonly merge: "Merge";
-    readonly complete: "Mark complete";
+    readonly complete: "Accept and finish";
     readonly look: "Look first";
 };
-/** Whether this line asks for the result's next step, so it carries [Merge] or [Mark complete] and [Look first]. */
+/** Whether this line asks for the result's next step, so it carries [Merge] or [Accept and finish] and [Look first]. */
 export declare function asksToFinish(fact: FinishedFact): boolean;
 /** One update, said plainly: what happened, then what happens next. The lead says "I" for what it did. */
 export declare function finishedLine(fact: FinishedFact): string;

package/dist/chat-voice.js

@@ -42,8 +42,8 @@ export function inSentence(summary) {
     return /^\p{Lu}\p{Ll}/u.test(summary) ? summary[0].toLowerCase() + summary.slice(1) : summary;
 }
 /** The two buttons under a result ready for a person: the real next step, then a look first. */
-export const READY_ACTIONS = { merge: "Merge", complete: "Mark complete", look: "Look first" };
-/** Whether this line asks for the result's next step, so it carries [Merge] or [Mark complete] and [Look first]. */
+export const READY_ACTIONS = { merge: "Merge", complete: "Accept and finish", look: "Look first" };
+/** Whether this line asks for the result's next step, so it carries [Merge] or [Accept and finish] and [Look first]. */
 export function asksToFinish(fact) {
     return fact.update == null && fact.headline === "Ready for review" && !fact.report;
 }
@@ -61,7 +61,7 @@ export function finishedLine(fact) {
             if (fact.report)
                 return fact.lead === true ? `I wrote up ${lower}. The report is ready to read.` : `${name}: the report is ready to read.`;
             if (fact.checks === "passed")
-                return `${ready}. Your tests passed. ${fact.pullRequest === true ? "Merge it?" : "Mark it complete?"}`;
+                return `${ready}. Your tests passed. ${fact.pullRequest === true ? "Merge it?" : "Accept and finish it?"}`;
             if (fact.checks === "off")
                 return `${ready}. Checks are off for this project, so look it over first.`;
             return `${ready}, but no tests ran. Look it over first.`;

package/dist/demo.js

@@ -97,6 +97,57 @@ const DEMO_HANDOFF = {
     followUps: [],
     decisionsIncorporated: [],
 };
+/** The failed demo build: it took the flag out of settlement and config, but
+ * not out of the admin override, and its own report says so. */
+const DEMO_FAILED_PATCH = `diff --git a/src/payout.ts b/src/payout.ts
+index 7c1d2e3..5a1f0c7 100644
+--- a/src/payout.ts
++++ b/src/payout.ts
+@@ -18,9 +18,5 @@ export function settleAll(rows: PayoutRow[]): number {
+-  if (config.LEGACY_PAYOUT) {
+-    return rows.reduce((sum, row) => sum + legacySettle(row), 0);
+-  }
+-
+-  return rows.reduce((sum, row) => sum + settle(row.cents, row.rate), 0);
++  return rows.reduce((sum, row) => sum + settle(row.cents, row.rate), 0);
+ }
+diff --git a/src/config.ts b/src/config.ts
+index 2b3c4d5..8e9f0a1 100644
+--- a/src/config.ts
++++ b/src/config.ts
+@@ -4,8 +4,6 @@ export const config = {
+   PAYOUT_BATCH_SIZE: 500,
+-  // Retired once every merchant is on the new settlement path.
+-  LEGACY_PAYOUT: process.env.LEGACY_PAYOUT === "1",
+   PAYOUT_CURRENCY: "USD",
+ };
+`;
+const DEMO_FAILED_HANDOFF = {
+    schema: 1,
+    outcome: "built",
+    committed: true,
+    conclusion: "Removed LEGACY_PAYOUT from settlement and config. The admin override still reads it, so one reference remains.",
+    changes: ["Dropped the legacy settlement branch in src/payout.ts.", "Removed the LEGACY_PAYOUT flag from src/config.ts."],
+    verification: ["Searched the codebase for LEGACY_PAYOUT after the change."],
+    followUps: [],
+    decisionsIncorporated: [],
+};
+const DEMO_FAILED_PROOF = {
+    version: 1,
+    criteria: [
+        {
+            id: "c1",
+            statement: "No reference to LEGACY_PAYOUT remains in the codebase.",
+            verdict: "met",
+            how: "Removed the flag and the settlement branch behind it.",
+            evidence: [{ kind: "changed-path", ref: "src/payout.ts" }, { kind: "changed-path", ref: "src/config.ts" }],
+        },
+    ],
+    checks: [],
+    changed: ["src/payout.ts", "src/config.ts"],
+    caveats: ["c1: src/admin/overrides.ts still reads LEGACY_PAYOUT for the per-merchant override toggle, so one reference remains."],
+    screenshots: [],
+};
 /** The evidence bundle's own manifest (Acceptance Contract v2 demo): the
  * seeded sandbox answers its OWN signed rubric by exact id, with typed
  * evidence references — the same shape a real builder writes — so a
@@ -472,14 +523,15 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     store.finishRun(buildingPriorRun, { outcome: "refused", reason: "plan-revised", now: hoursAgo(1.6) });
     // The board's "building" lane keys off a live claim — take one through
     // the real claim machinery so the card wears worker and lease honestly.
-    acquire(store, buildingRef, "night-shift-1", {
+    const liveClaim = acquire(store, buildingRef, "night-shift-1", {
         now: hoursAgo(0.4),
         token: nightShift.token,
         ttlMs: 4 * 3_600_000,
     });
     const liveRun = store.startRun({
         taskRef: buildingRef,
-        leaseId: "demo-lease-live",
+        // The claim's own lease, so the build reads as live: the run the task's current claim owns.
+        leaseId: liveClaim.ok ? liveClaim.claim.leaseId : "demo-lease-live",
         runner: "night-shift-1",
         branch: `toolroll/${building}`,
         worktree: join(repos.api, ".demo-worktree-2"),
@@ -603,6 +655,34 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         now: hoursAgo(6),
         ...presentedRoute(store, store.refFor("built-in", failed).id, "builder"),
     });
+    // What the failed build left: its saved changes, its report and the
+    // machine's reading of them. It removed the flag from settlement but left
+    // the admin override reading it, and said so in its own note — so the
+    // signed requirement is missed, and the task card can name it.
+    store.stampRun(failedRun, { baseRevision: "4b825dc642cb6eb9a060e54bf8d69288fbee4904", scopeDigest: failedProposed.digest });
+    store.recordOutcomeFacts(failedRun, { headRevision: "5a1f0c7e2b9d4e6f8a0b1c2d3e4f5a6b7c8d9e0f" });
+    storeEvidence(store, evidenceRoot, failedRun, "terminal-diff", "terminal-diff.patch", Buffer.from(DEMO_FAILED_PATCH, "utf8"), "git diff --no-ext-diff --no-textconv --no-color 4b825dc6..HEAD (exit 0) [demo: synthetic]", hoursAgo(5.6));
+    const failedStat = {
+        schema: 1, base: "4b825dc642cb6eb9a060e54bf8d69288fbee4904", head: "5a1f0c7e2b9d4e6f8a0b1c2d3e4f5a6b7c8d9e0f",
+        fileCount: 2, additions: 1, deletions: 7, binaryCount: 0,
+        files: [{ path: "src/payout.ts", additions: 1, deletions: 5 }, { path: "src/config.ts", additions: 0, deletions: 2 }],
+        filesTruncated: false,
+    };
+    storeEvidence(store, evidenceRoot, failedRun, "diff-stat", "diff-stat.json", budgetedStatJson(failedStat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(5.6));
+    storeEvidence(store, evidenceRoot, failedRun, "handoff", "handoff.json", Buffer.from(JSON.stringify(DEMO_FAILED_HANDOFF, null, 2), "utf8"), "composed at completion [demo: synthetic]", hoursAgo(5.6));
+    storeEvidence(store, evidenceRoot, failedRun, "proof", "proof.json", Buffer.from(JSON.stringify(DEMO_FAILED_PROOF, null, 2), "utf8"), "agent-authored proof (validated, re-serialized) [demo: synthetic]", hoursAgo(5.6));
+    const failedAdjudicated = adjudicate({
+        proofArtifactPresent: true,
+        proofParse: parseProof(JSON.stringify(DEMO_FAILED_PROOF)),
+        handoffPresent: true,
+        terminalDiffPresent: true,
+        terminalDiffCaptureStatus: "ok",
+        diffStat: { captured: true, truncated: false, paths: new Set(failedStat.files.map(one => one.path)) },
+        verifyCommand: { configured: false },
+        screenshots: [],
+        approvedCriteria: failedProposed.acceptance,
+    });
+    store.saveProofVerdict(failedRun, failedAdjudicated.verdict, failedAdjudicated.reasons, hoursAgo(5.5), failedAdjudicated.matrix);
     store.finishRun(failedRun, {
         outcome: "failed",
         reason: "acceptance",

package/dist/disclosure.d.ts

@@ -0,0 +1,6 @@
+/** One disclosure glyph everywhere: the chevron. It points right while a fold is shut and turns down when it opens,
+ * on the server pages, the enhanced folds (workspace-motion.ts) and the React views (lucide's ChevronRight). Every
+ * other marker (the native triangle, ▸/▾, +/−, ⌄ and the old arrows) is turned off here, last, so no page can bring
+ * a second glyph back. A summary that carries its own icon keeps it. Drawn with two borders: the page's content
+ * policy allows no image, not even a data: one. */
+export declare const DISCLOSURE_CSS: string;

package/dist/disclosure.js

@@ -0,0 +1,13 @@
+/** One disclosure glyph everywhere: the chevron. It points right while a fold is shut and turns down when it opens,
+ * on the server pages, the enhanced folds (workspace-motion.ts) and the React views (lucide's ChevronRight). Every
+ * other marker (the native triangle, ▸/▾, +/−, ⌄ and the old arrows) is turned off here, last, so no page can bring
+ * a second glyph back. A summary that carries its own icon keeps it. Drawn with two borders: the page's content
+ * policy allows no image, not even a data: one. */
+export const DISCLOSURE_CSS = `details>summary{list-style:none}details>summary::-webkit-details-marker{display:none}` +
+    `details>summary::after{content:none!important}` +
+    `details>summary:not(:has(>svg))::before{content:""!important;display:inline-block;flex:none;box-sizing:border-box;width:7px!important;height:7px!important;` +
+    `margin:0 .55rem 0 .2rem!important;padding:0!important;position:static!important;vertical-align:.1em;font-size:0;background:none!important;` +
+    `border:0 solid currentColor!important;border-right-width:1.5px!important;border-bottom-width:1.5px!important;opacity:.65;` +
+    `transform:rotate(-45deg)!important;transition:transform .15s ease}` +
+    `details[open]>summary:not(:has(>svg))::before{transform:rotate(45deg)!important}` +
+    `@media (prefers-reduced-motion:reduce){details>summary::before{transition:none!important}}`;

package/dist/lead-status.js

@@ -90,14 +90,14 @@ export function taskWaitSnapshot(store, taskId, now, watchedRun) {
         if (outcome !== "built" && outcome !== "no-change")
             return answer("Failed", "Inspect attempt", true, 1, "failed");
         if (state !== "done")
-            return answer("Ready", "Review result", true, 0, "ready");
+            return answer("Ready", "Open result", true, 0, "ready");
     }
     // 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");
+        return answer("Ready", "Open result", true, 0, "ready");
     if (state === "failed" || state === "cancelled")
         return answer("Failed", state === "cancelled" ? "Review cancellation" : "Inspect failure", true, 1, "failed");
     const decision = store.handle.prepare(`SELECT decision.id FROM run INDEXED BY lead_status_task_run

package/dist/needs-you.d.ts

@@ -35,6 +35,30 @@ export declare const NEEDS: Readonly<Record<NeedKey, Need>>;
 export type Ask = "decide" | "review" | "unblock";
 export declare const ASKS: readonly Ask[];
 export declare const ASK_LABEL: Readonly<Record<Ask, string>>;
+/** A waiting row's chip: the specific thing asked, never its group's own word (no "Decide" chip under Decide).
+ * Null: the group heading and the row's sentence already say it, so the row wears no chip. */
+export type AskChip = "Plan" | "Result" | "Mismatch" | "Plan changed" | "Failed" | "Builder offline";
+/** `mismatch`: the saved report doesn't match its changes; `planChanged`: the plan changed after it was built. */
+export declare function askChipOf(read: {
+    headline: string;
+    need?: NeedKey | null;
+    mismatch?: boolean;
+    planChanged?: boolean;
+    ask?: Ask | null;
+}): AskChip | null;
+/** Why a saved result can't simply be accepted yet, in its own words (each Review row says its own reason,
+ * never a boilerplate line). The facts are the ones the Tasks list and the task page both read. */
+export type ResultHoldUp = {
+    hold: string | null;
+    planChanged: boolean;
+    unapproved: boolean;
+    running: boolean;
+    unfinished: boolean;
+    noCommit: boolean;
+    question: boolean;
+    report: boolean;
+};
+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. */
@@ -83,4 +107,28 @@ export declare function isInternalErrorReason(reason: string | null | undefined)
 /** A failed attempt in one plain line: its recorded reason in words (first line only, about 140 characters at most),
  * that it stopped with an internal error when the reason is machine output, or that none was recorded. */
 export declare function failedAttemptSentence(reason: string | null | undefined): string;
+export declare const GENERAL_SUGGESTION = "Say what to do differently this time.";
+export declare function stopSuggestionOf(reason: string | null | undefined): string;
+/** The suggestion for a requirement the result missed: make sure of it before handing off. */
+export declare function missedRequirementSuggestion(statement: string): string;
+/** The suggestion for a check that failed on the result: make it pass, starting with the line it ended on. */
+export declare function failingCheckSuggestion(line: string): string;
+/** What a failed attempt missed, in plain words: what failed (the missed requirement, the failing check's line or the
+ * stop reason), the evidence line behind it, and one suggestion of what to change (Retry's note starts with it). */
+export type FailureExplanation = {
+    kind: "requirement" | "check" | "reason";
+    line: string;
+    evidence: string | null;
+    suggestion: string;
+    link: {
+        label: string;
+        href: string;
+    } | null;
+};
+/** The line for a missed requirement: “Missed: <statement>”, cut to one line. */
+export declare function missedRequirementLine(statement: string): string;
+/** The longest note Retry's field takes. */
+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 {};

package/dist/needs-you.js

@@ -28,7 +28,7 @@ export const NEEDS = {
     "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" } },
+    "review-result": { sentence: () => "Check the result, then accept it or ask for changes.", action: { code: "open-result", label: "Open 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" } },
@@ -36,6 +36,41 @@ export const NEEDS = {
 };
 export const ASKS = ["decide", "review", "unblock"];
 export const ASK_LABEL = { decide: "Decide", review: "Review", unblock: "Unblock" };
+/** `mismatch`: the saved report doesn't match its changes; `planChanged`: the plan changed after it was built. */
+export function askChipOf(read) {
+    if (read.headline === "Failed")
+        return "Failed";
+    if (read.planChanged === true || read.need === "rebuild")
+        return "Plan changed";
+    if (read.mismatch === true)
+        return "Mismatch";
+    if (read.headline === "Ready for review" || read.need === "review-result" || read.ask === "review")
+        return "Result";
+    if (read.need === "approval")
+        return "Plan";
+    if (read.need === "start-builder" || read.need === "connect-builder")
+        return "Builder offline";
+    return null;
+}
+export function resultHoldUpSentence(facts) {
+    if (facts.hold != null && facts.hold.trim() !== "" && !hasInternalWords(facts.hold))
+        return `On hold: ${facts.hold.trim().replace(/[.\s]*$/, "")}. Release the hold to accept it.`;
+    if (facts.hold != null)
+        return "A hold is on this result. Release it to accept the result.";
+    if (facts.planChanged)
+        return "The plan changed after this was built. Build it again to the current plan.";
+    if (facts.unapproved)
+        return "The current plan isn't approved. Approve it, then review the result.";
+    if (facts.question)
+        return "A question is still open. Answer it, then review the result.";
+    if (facts.running)
+        return "A build is still running on this task.";
+    if (facts.unfinished)
+        return "An earlier attempt never finished. Check it, then review the result.";
+    if (facts.noCommit)
+        return facts.report ? "The report is missing or incomplete. Open it to see what was saved." : "The build saved no commit to review. Open the result to see what was kept.";
+    return "Open the result to see what it needs before you can accept it.";
+}
 export const NEED_ASK = {
     approval: "decide", card: "decide", answer: "decide", questions: "decide", "choose-project": "decide", "define-task": "decide",
     "fix-request": "decide", "choose-agent": "decide",
@@ -138,6 +173,7 @@ export const RUN_REASON_WORDS = {
     "reviewer-error": "the review failed",
     "malformed-report": "the scout's report was malformed",
     "attempts-exhausted": "it failed too many times in a row",
+    "plan-revised": "the plan changed, so a fresh attempt took over",
 };
 /** A run's recorded reason in words. A recorded code is never shown as it is
  * stored: one with no words of its own reads as an unexpected stop; a reason
@@ -190,3 +226,59 @@ export function failedAttemptSentence(reason) {
         : `${words.slice(0, REASON_LINE_LIMIT - 1).replace(/\s+\S*$/, "").replace(/[,;:\s]+$/, "")}…`;
     return `${line.charAt(0).toUpperCase()}${line.slice(1)}${line.endsWith("…") ? "" : "."}`;
 }
+/** What to change before the next attempt, by a stopped run's recorded reason: one plain suggestion, the note Retry
+ * starts with. A reason with no suggestion of its own gets the general one. */
+const STOP_SUGGESTIONS = {
+    acceptance: "Before handing off, check each signed requirement against the changes.",
+    timeout: "Split the work into smaller steps, or name the one part to finish first.",
+    "no-op": "Say exactly which files or behaviour should change.",
+    agent: "Say what to do differently this time, or name the part to try first.",
+    "agent-reported": "Answer what the agent said it was missing, or narrow the task.",
+    "provider-init": "Check the agent is signed in and installed, then retry.",
+    "spawn-failed": "Check the agent is signed in and installed, then retry.",
+    "auth-expired": "Sign the agent in again, then retry.",
+    "provider-protocol": "Retry as it is; if it stops the same way, try another agent.",
+    setup: "Fix the project's setup step, then retry.",
+    git: "Make sure the project's branch is clean and reachable, then retry.",
+    "commit-failure": "Make sure the project's commit hooks pass, then retry.",
+    "moved-head": "Retry: the next attempt starts from where the branch is now.",
+    "moved-branch": "Retry: the next attempt starts from where the branch is now.",
+    "retryable-infra": "Retry as it is.",
+    interrupted: "Retry as it is.",
+    orphaned: "Retry as it is.",
+    capability: "Add what the project is missing, then retry.",
+    "attempts-exhausted": "Say what to do differently this time, or narrow the task.",
+};
+export const GENERAL_SUGGESTION = "Say what to do differently this time.";
+export function stopSuggestionOf(reason) {
+    const code = reason?.trim() ?? "";
+    return STOP_SUGGESTIONS[code] ?? GENERAL_SUGGESTION;
+}
+/** A signed requirement in the middle of a sentence: its first letter lowered unless it starts a name or an acronym. */
+function inSentence(statement) {
+    const plain = statement.trim().replace(/[.\s]+$/, "");
+    return /^[A-Z][a-z]/.test(plain) ? `${plain.charAt(0).toLowerCase()}${plain.slice(1)}` : plain;
+}
+/** The suggestion for a requirement the result missed: make sure of it before handing off. */
+export function missedRequirementSuggestion(statement) {
+    return `Before handing off, make sure ${inSentence(statement)}.`;
+}
+/** The suggestion for a check that failed on the result: make it pass, starting with the line it ended on. */
+export function failingCheckSuggestion(line) {
+    return `Make the check pass. It ended on: ${line.replace(/[.\s]+$/, "")}.`;
+}
+/** The line for a missed requirement: “Missed: <statement>”, cut to one line. */
+export function missedRequirementLine(statement) {
+    const plain = statement.trim().replace(/\s+/g, " ").replace(/[.\s]+$/, "");
+    const cut = plain.length <= REASON_LINE_LIMIT - 10 ? plain : `${plain.slice(0, REASON_LINE_LIMIT - 11).replace(/\s+\S*$/, "")}…`;
+    return `Missed a requirement: ${cut}${cut.endsWith("…") ? "" : "."}`;
+}
+/** The longest note Retry's field takes. */
+export 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 function retryNoteOf(suggestion) {
+    const plain = suggestion.trim();
+    if (plain.length <= RETRY_NOTE_LIMIT)
+        return plain;
+    return `${plain.slice(0, RETRY_NOTE_LIMIT - 1).replace(/\s+\S*$/, "").replace(/[,;:\s]+$/, "")}…`;
+}