toolroll 0.9.13 → 0.9.15

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",
@@ -90,3 +125,160 @@ export const CODE_NEED = {
     "no-build-record": "review-result", "verification-needed": "review-result", "evidence-mismatch": "review-result",
     "record-incomplete": "review-result", "evidence-damaged": "review-result",
 };
+/** A stopped run's recorded reason code, in words (the run record, the thread, a failed task's status). */
+export const RUN_REASON_WORDS = {
+    agent: "the agent failed",
+    "agent-reported": "the agent reported it could not finish",
+    "no-op": "nothing changed when something should have",
+    "no-handoff": "the agent stopped before handing off; its work was kept and it is being resumed",
+    "moved-head": "the branch moved underneath the build",
+    "moved-branch": "the branch moved underneath the build",
+    timeout: "ran out of time",
+    git: "a git step failed",
+    "malformed-decision": "the agent's question was malformed",
+    "malformed-plan": "the plan was malformed",
+    fenced: "another worker took the task over",
+    unapproved: "the scope was not approved",
+    "scope-changed": "the scope changed after approval",
+    capability: "a requirement was missing",
+    setup: "the workspace preparation step failed",
+    "provider-init": "the agent could not start",
+    "commit-failure": "the commit failed",
+    "protected-branch": "refused to touch a protected branch",
+    "wrong-branch": "the checkout was on the wrong branch",
+    "not-leased": "the lease was not valid",
+    "no-claim": "the lease was not valid",
+    "not-yours": "the lease was not valid",
+    "no-run-record": "the run record was missing",
+    "missing-mailbox": "the resume mailbox could not be read",
+    "unreadable-mailbox": "the resume mailbox could not be read",
+    "revision-brief": "the revision brief could not be read",
+    "repaired-park": "resumed from a parked question",
+    stopped: "stopped by the operator",
+    acceptance: "the result didn't meet its signed requirements",
+    evidence: "its evidence could not be saved",
+    interrupted: "the attempt was interrupted",
+    orphaned: "the attempt lost its worker",
+    "retryable-infra": "a temporary problem on the machine stopped it",
+    unknown: "the attempt stopped unexpectedly",
+    "spawn-failed": "the agent process could not start",
+    "provider-protocol": "the agent's reply could not be read",
+    "auth-expired": "the agent's sign-in expired",
+    "budget-unenforceable": "its spending limit could not be enforced",
+    "stale-source": "the request changed while the plan was being made",
+    "stale-approval": "the approval no longer matched the scope",
+    "source-invalid": "the plan's source could not be recorded",
+    "external-closed": "the linked issue was closed while it was being built",
+    "repair-admission": "the repair could not start",
+    "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
+ * already written as words (it has a space) is said as written. */
+export function runReasonWords(reason) {
+    const known = RUN_REASON_WORDS[reason];
+    if (known !== undefined)
+        return known;
+    if (reason.startsWith("decision:"))
+        return "the agent asked a question";
+    return /\s/.test(reason.trim()) ? reason.trim() : "the attempt stopped unexpectedly";
+}
+/** The latest finished build attempt among a task's runs (any order), whatever its outcome: planning and reviewing
+ * are not attempts, and an older failure never stands in for a newer attempt. */
+export function latestFinishedAttempt(runs) {
+    let latest = null;
+    // Ended means a finish time or an outcome: a reconcile can mark a run failed without stamping finished_at.
+    for (const run of runs)
+        if ((run.finishedAt !== null || (run.outcome ?? null) !== null) && run.role !== "planner" && run.role !== "reviewer" && (latest === null || run.id > latest.id))
+            latest = run;
+    return latest;
+}
+export const NO_REASON_RECORDED = "No reason was recorded for this attempt.";
+export const INTERNAL_ERROR = "The attempt stopped with an internal error.";
+/** About as long as one plain line reads. */
+export const REASON_LINE_LIMIT = 140;
+/** A recorded reason that is machine output, not words: a stack trace, a file path or "Error:" text. Its detail
+ * belongs behind a link, never in the line itself. */
+export function isInternalErrorReason(reason) {
+    const text = reason?.trim() ?? "";
+    if (text === "" || RUN_REASON_WORDS[text] !== undefined)
+        return false;
+    return /\b[A-Za-z]*(?:Error|Exception):/.test(text) // Error:, TypeError:, SomeException:
+        || /^\s*at\s+\S+/m.test(text) && /\n/.test(text) // a stack frame below the first line
+        // An absolute path of two or more segments (/Users/…, ~/x/y): plain sentences may name a project file (src/ledger.ts).
+        || /(?:^|[\s(“"'])~?\/(?:[\w.@-]+\/)+[\w.@-]+/.test(text)
+        || /[A-Za-z]:\\/.test(text) // C:\…
+        || /\.[cm]?[jt]sx?:\d+/.test(text); // ledger.ts:14
+}
+/** 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 function failedAttemptSentence(reason) {
+    const code = reason?.trim() ?? "";
+    if (code === "")
+        return NO_REASON_RECORDED;
+    if (isInternalErrorReason(code))
+        return INTERNAL_ERROR;
+    const words = runReasonWords(code.split(/\r?\n/, 1)[0].trim()).replace(/\s+/g, " ").replace(/[.\s]+$/, "");
+    const line = words.length <= REASON_LINE_LIMIT ? words
+        : `${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]+$/, "")}…`;
+}

package/dist/result-acts.d.ts

@@ -3,7 +3,9 @@
  * most one outline act beside it. A result that can't be accepted says why
  * in one line before them.
  *
- *   everything met                      → Accept
+ *   everything met                      → Accept and finish
+ *   a "You check this one" unanswered   → the next check, then Accept without your check
+ *   a check you marked Not right        → Request changes, then Accept anyway
  *   checks queued or running            → Checks running (disabled), then Accept without checks
  *   checks didn't run, a check exists   → Run checks, then Accept without checks
  *   report and changes disagree,
@@ -11,12 +13,19 @@
  *                                         never Accept as ink, even with no form here
  *   a Needs you form resolves it        → that form (Build again, Confirm it stopped)
  *   saved notes or a failing PR         → Revise / Draft a repair task
+ *   a failed build                      → Retry (its note starts with what to change), then Run checks when they
+ *                                         didn't run; never Accept: a failed build is not a result to accept
+ *   a failed task's delivered result    → Retry, then Accept anyway (in outline, with a reason) where it may be
+ *                                         accepted; Run checks stays in its Checks row
  *
- * Accepting means what it always meant: the same forms post to the same
- * endpoints. This only decides which one is ink. */
-export type ResultActKind = "accept" | "checks-running" | "run-checks" | "request-changes" | "rebuild" | "confirm-stopped" | "revise" | "draft-repair";
+ * Accepting finishes the task in one request (Accept and finish): the person's
+ * acceptance, when one is owed, and the completion together. This only decides
+ * which act is ink; the page recomputes it as the person answers each check. */
+/** The words over the reason field an Accept of a refuted result requires. */
+export declare const ACCEPT_NEEDS_REASON = "Accepting needs a reason";
+export type ResultActKind = "retry" | "accept" | "accept-anyway" | "next-check" | "checks-running" | "run-checks" | "request-changes" | "rebuild" | "confirm-stopped" | "revise" | "draft-repair";
 export type ResultActFacts = {
-    /** An Accept this page can post (Mark complete, or the person's acceptance); `ready`: every requirement met and checks passed. */
+    /** An Accept this page can post (Accept and finish, or the person's acceptance alone); `ready`: every requirement met and checks passed. */
     accept: {
         ready: boolean;
     } | null;
@@ -32,6 +41,16 @@ export type ResultActFacts = {
     need: "rebuild" | "confirm-stopped" | null;
     /** Saved notes ready to become a revision, or a failing pull request's repair. */
     next: "revise" | "draft-repair" | null;
+    /** A failed build: `retry` when the task can be retried from here; `acceptAnyway` when it delivered a result that
+     * may still be accepted, with a reason. */
+    failed?: {
+        retry: boolean;
+        acceptAnyway?: boolean;
+    } | null;
+    /** "You check this one" items not answered yet on this page. */
+    unanswered?: number;
+    /** Items the person marked Not right. */
+    notRight?: number;
 };
 export type ResultActs = {
     /** The one ink act, or null when nothing waits on the person. */
@@ -42,3 +61,30 @@ export type ResultActs = {
     line: string | null;
 };
 export declare function resultActsOf(facts: ResultActFacts): ResultActs;
+/** The words a result's Accept wears and the one line before it, given the
+ * server's words for everything but the person's own checks (`base`) and how
+ * those stand on this page: an unanswered check names itself; a check marked
+ * Not right says so; otherwise the base words stand. */
+export type AcceptLabel = "Accept and finish" | "Accept without checks" | "Accept without your check" | "Accept anyway";
+export declare function acceptWithChecksOf(base: {
+    label: AcceptLabel;
+    ready: boolean;
+    why: string | null;
+}, checks: {
+    unanswered: readonly string[];
+    notRight: readonly string[];
+}): {
+    label: AcceptLabel;
+    ready: boolean;
+    why: string | null;
+};
+/** The Requirements row as the person answers their checks: each Looks right is met, each answer leaves "You check". */
+export declare function requirementsWordsOf(req: {
+    met: number;
+    total: number;
+    yours: number;
+}, looked: number, notRight: number): {
+    text: string;
+    done: boolean;
+    short: boolean;
+};

package/dist/result-acts.js

@@ -3,7 +3,9 @@
  * most one outline act beside it. A result that can't be accepted says why
  * in one line before them.
  *
- *   everything met                      → Accept
+ *   everything met                      → Accept and finish
+ *   a "You check this one" unanswered   → the next check, then Accept without your check
+ *   a check you marked Not right        → Request changes, then Accept anyway
  *   checks queued or running            → Checks running (disabled), then Accept without checks
  *   checks didn't run, a check exists   → Run checks, then Accept without checks
  *   report and changes disagree,
@@ -11,12 +13,24 @@
  *                                         never Accept as ink, even with no form here
  *   a Needs you form resolves it        → that form (Build again, Confirm it stopped)
  *   saved notes or a failing PR         → Revise / Draft a repair task
+ *   a failed build                      → Retry (its note starts with what to change), then Run checks when they
+ *                                         didn't run; never Accept: a failed build is not a result to accept
+ *   a failed task's delivered result    → Retry, then Accept anyway (in outline, with a reason) where it may be
+ *                                         accepted; Run checks stays in its Checks row
  *
- * Accepting means what it always meant: the same forms post to the same
- * endpoints. This only decides which one is ink. */
+ * Accepting finishes the task in one request (Accept and finish): the person's
+ * acceptance, when one is owed, and the completion together. This only decides
+ * which act is ink; the page recomputes it as the person answers each check. */
+/** The words over the reason field an Accept of a refuted result requires. */
+export const ACCEPT_NEEDS_REASON = "Accepting needs a reason";
 export function resultActsOf(facts) {
     const request = facts.canRequest ? "request-changes" : null;
     const accept = facts.accept === null ? null : "accept";
+    if (facts.failed != null) {
+        const checks = facts.runChecks && !facts.checksRunning ? "run-checks" : facts.checksRunning ? "checks-running" : null;
+        const anyway = facts.failed.acceptAnyway === true ? "accept-anyway" : null;
+        return facts.failed.retry ? { primary: "retry", secondary: anyway ?? checks, line: null } : { primary: checks, secondary: anyway, line: null };
+    }
     if (facts.need !== null)
         return { primary: facts.need, secondary: request, line: null };
     if (facts.next !== null)
@@ -24,6 +38,11 @@ export function resultActsOf(facts) {
     // Can't be accepted yet: Accept is never the ink act, even when the feedback form isn't here.
     if (facts.blocked !== null)
         return { primary: request, secondary: accept, line: facts.blocked };
+    // The person's own checks come first: the next one is ink until each is answered.
+    if (accept !== null && (facts.unanswered ?? 0) > 0)
+        return { primary: "next-check", secondary: accept, line: null };
+    if (accept !== null && (facts.notRight ?? 0) > 0)
+        return { primary: request, secondary: accept, line: null };
     if (facts.checksRunning)
         return { primary: "checks-running", secondary: accept ?? request, line: null };
     if (facts.accept === null)
@@ -34,3 +53,17 @@ export function resultActsOf(facts) {
         return { primary: "run-checks", secondary: "accept", line: null };
     return { primary: "accept", secondary: request, line: null };
 }
+export function acceptWithChecksOf(base, checks) {
+    const named = (all) => `“${all[0].replace(/[.!?]+$/, "")}”${all.length > 1 ? ` and ${all.length - 1} more` : ""}`;
+    if (checks.unanswered.length > 0)
+        return { label: "Accept without your check", ready: false, why: `Not checked yet: ${named(checks.unanswered)}.` };
+    if (checks.notRight.length > 0)
+        return { label: "Accept anyway", ready: false, why: `You marked ${named(checks.notRight)} not right.` };
+    return base;
+}
+/** The Requirements row as the person answers their checks: each Looks right is met, each answer leaves "You check". */
+export function requirementsWordsOf(req, looked, notRight) {
+    const met = req.met + looked;
+    const yours = Math.max(0, req.yours - looked - notRight);
+    return { text: `${met} of ${req.total} met${yours > 0 ? ` · You check ${yours}` : ""}`, done: met === req.total, short: req.total - met - yours > 0 };
+}

package/dist/result-review.d.ts

@@ -149,9 +149,10 @@ export declare const RESULT_FACT_KEYS: readonly ["run", "head", "base", "head-so
  * (place, lead, task, user) are not facts and are left out. */
 export declare function resultFactsFromHtml(html: string): Record<string, string>[];
 /** Where a result form may send its reader back: the review cockpit's
- * own deep link, the chat's result detail, or the run page. Anything else
- * lands on the run page. Matched exactly — never a bare open redirect. */
-export declare function resultReturnTarget(raw: string | null | undefined, runId: number): string;
+ * own deep link, the chat's result detail, the page of a task named in
+ * `tasks` (the run's own), or the run page. Anything else lands on the run
+ * page. Matched exactly — never a bare open redirect. */
+export declare function resultReturnTarget(raw: string | null | undefined, runId: number, tasks?: readonly string[]): string;
 /** A form's own request token, minted per render — the same shape the
  * chat composer uses. A replayed submission carries the same token, so
  * the server can recognise it and mint nothing twice. */

package/dist/result-review.js

@@ -149,9 +149,10 @@ export function resultFactsFromHtml(html) {
     return found;
 }
 /** Where a result form may send its reader back: the review cockpit's
- * own deep link, the chat's result detail, or the run page. Anything else
- * lands on the run page. Matched exactly — never a bare open redirect. */
-export function resultReturnTarget(raw, runId) {
+ * own deep link, the chat's result detail, the page of a task named in
+ * `tasks` (the run's own), or the run page. Anything else lands on the run
+ * page. Matched exactly — never a bare open redirect. */
+export function resultReturnTarget(raw, runId, tasks = []) {
     if (raw !== null && raw !== undefined) {
         const review = /^\/review\?result=[A-Za-z0-9._~%-]{1,200}(?:&run=([0-9]{1,15}))?(?:&tab=(?:summary|changes|checks))?$/.exec(raw);
         if (review !== null && (review[1] === undefined || Number(review[1]) === runId))
@@ -159,6 +160,9 @@ export function resultReturnTarget(raw, runId) {
         const chat = /^\/chat\?task=([A-Za-z0-9._~%-]{1,200})&result=([0-9]{1,15})(?:&conversation=[A-Za-z0-9-]{1,128})?$/.exec(raw);
         if (chat !== null && Number(chat[2]) === runId)
             return raw;
+        // The run's own task page, which offered Run checks in place; never another task's.
+        if (tasks.some(task => raw === `/t/${encodeURIComponent(task)}`))
+            return raw;
     }
     return `/r/${runId}`;
 }

package/dist/serve.d.ts

@@ -208,6 +208,9 @@ export declare function createDecisionServer(options: ServeOptions): DecisionSer
  * text, never to a 500. The scheme is a constant, never data.
  */
 export declare function editorFileHref(worktree: string, path: string, line?: number | null): string | null;
+/** Earlier versions of a task still in flight, in plain words: queued
+ * while they only wait, running once one has started; null when none. */
+export declare function earlierVersionsWords(active: number, running: number): string | null;
 /** The Agents view every console surface renders (v47): the SAME
  * projection the CLI prints — who plans, builds, and revises,
  * whether each was recommended, overridden, or pinned, its reasons, and