toolroll 0.9.93 → 0.9.95

package/dist/work-summary.js

@@ -2,6 +2,8 @@
  * State, decisions, approval, process custody and proof still belong to
  * their existing owners. Action hints are navigation/proposal guidance,
  * never credentials or permission to bypass an owning operation. */
+import { heldFindingCount } from "./findings.js";
+import { machineChecked } from "./machine-check.js";
 import { resultCheckLevel } from "./result-follow-ups.js";
 import { diagnoseTaskDispatch } from "./dispatch.js";
 import { isAlive } from "./runner.js";
@@ -27,7 +29,7 @@ export function workDecisionAction(taskId, decision, principal) {
         access: principal === "operator" ? "operator-control" : "proposal-only", retry: "refresh-before-acting" };
 }
 const PROPOSABLE = new Set(["answer-decision", "write-scope", "unhold"]);
-const READ_ACTIONS = new Set(["open-result", "open-pr", "inspect-task", "inspect-run", "inspect-stop", "inspect-decisions"]);
+const READ_ACTIONS = new Set(["open-result", "open-pr", "inspect-task", "inspect-findings", "inspect-run", "inspect-stop", "inspect-decisions"]);
 /** Pure counterpart for callers already holding the same facts. */
 export function workSummaryOf(facts, principal, resultDisplay) {
     const status = workStatusOf(facts, resultDisplay);
@@ -47,6 +49,8 @@ export function workSummaryOf(facts, principal, resultDisplay) {
             primary = make("resume-run", status.action.label, { runId: facts.control.run });
         else if (status.token === "waiting-decision" && questionAction !== null)
             primary = questionAction;
+        else if (status.token === "finding-held")
+            primary = make("inspect-findings", status.action.label);
         else if (facts.dispatch?.code === "vanished-run")
             primary = make("reconcile-run", "Check the unfinished attempt", { runId: facts.unfinishedRunId ?? null });
         else if (status.action.kind === "open-result" || status.action.kind === "open-review")
@@ -94,9 +98,10 @@ export function taskWorkSummaryOf(store, taskId, now, access) {
     const publication = result === null ? null : store.publicationForRun(result.id);
     const facts = {
         id: task.id, title: task.title, repo: ref.repo, state: task.state, updatedAt: task.updatedAt,
+        ...(machineChecked(store, task.id) ? { machine: true } : {}),
         dispatch: diagnoseTaskDispatch(store, taskId, now, access.dependencyRepos ?? null), liveRunId: live?.id ?? null,
         unfinishedRunId: runs.find(one => one.outcome === null && one.role !== "reviewer")?.id ?? null,
-        control: taskControlOf(store, ref.id, now), openDecision: openWorkDecisionOf(store, ref.id, now),
+        control: taskControlOf(store, ref.id, now), openDecision: openWorkDecisionOf(store, ref.id, now), heldFindings: heldFindingCount(store, taskId),
         result: result === null ? null : {
             runId: result.id, role: result.role, outcome: result.outcome,
             verdict: proof?.verdict ?? null, reasons: proof?.reasons ?? [], accepted: store.proofAcceptance(result.id) !== null,

package/dist/workspace-ui.d.ts

@@ -26,7 +26,7 @@ import { type ChecksFact } from "./task-status.js";
 import { type Html } from "./html.js";
 /** The Work destination's views — shortcuts over the same rows, never a
  * persisted state. All is the default. */
-export type WorkView = "all" | "needs-you" | "running" | "queued" | "completed" | "archived";
+export type WorkView = "all" | "needs-you" | "ready" | "running" | "queued" | "completed" | "archived";
 export declare const WORK_VIEWS: readonly {
     key: WorkView;
     label: string;
@@ -106,7 +106,7 @@ export type NextAction = {
     label: string;
     /** Where the act lives — the page, not a URL, so every surface can
      * build its own link (a task page anchors, a row links out). */
-    kind: "open-result" | "open-review" | "open-task" | "open-run" | "open-pr";
+    kind: "open-result" | "open-review" | "open-task" | "open-findings" | "open-run" | "open-pr";
 };
 export type DisplayStatus = {
     /** The stable `data-work-status` token pages and tests key off. */
@@ -154,6 +154,8 @@ export declare function receiptPublicationWords(publication: PublicationFacts):
  * already reads elsewhere. */
 export type WorkFacts = {
     id: string;
+    /** The machine runs this task's check on a prepared candidate; no agent runs (machine-check.ts). */
+    machine?: boolean;
     title: string;
     repo: string | null;
     state: TaskState;
@@ -173,6 +175,8 @@ export type WorkFacts = {
         question: string;
         overdue: boolean;
     } | null;
+    /** Findings of this task's family that used their rounds and wait on a person (findings.ts). */
+    heldFindings?: number;
 };
 export type WorkStatus = DisplayStatus & {
     /** Which shortcut views list this row; `all` always does. */
@@ -233,7 +237,7 @@ export declare function lastErrorLineOf(log: string): {
     text: string;
 } | null;
 /** The result page's own sentence when the decision is on it. */
-export declare const RESULT_DECISION_SENTENCE = "Review the change, then accept it or ask for changes.";
+export declare const RESULT_DECISION_SENTENCE = "Review the change, then accept it or send it back.";
 /** What the result page's Accept says, from facts it already shows: the
  * recorded checks, the requirements not met, whether the saved proof reads,
  * and what the button posts. "Accept and finish" only when everything is met

package/dist/workspace-ui.js

@@ -16,22 +16,25 @@
  * observed" name observed publication records, and deployment is never
  * claimed without one.
  */
+import { lastIncludedWords } from './memory-use.js';
 import { ACCEPT_NEEDS_REASON, FAILED_CHECK, cantAcceptYetOf, evidenceProblemOf } from "./result-acts.js";
 export { ACCEPT_NEEDS_REASON, cantAcceptYetOf, evidenceProblemOf };
 import { manualReviewOnly, plainReasonWords } from "./proof.js";
 import { CHECK_COMMAND_CHANGED, CHECK_UNREADABLE, OPEN_RESULT, approvedCheckOf, approvedCheckStateOf, plainReasonOf, stageOfCode, taskStatusOf, workToneOf } from "./task-status.js";
 import { whenUtc } from "./when-html.js";
+import { NEEDS } from "./needs-you.js";
 import { html, postForm } from "./html.js";
 export const WORK_VIEWS = [
     { key: "all", label: "All", hint: "Every task in view, most urgent first.", empty: "Nothing is in progress. Describe work in chat or add a task, and it appears here." },
     { key: "needs-you", label: "Needs you", hint: "Tasks waiting on an answer, approval, or your inspection.", empty: "Nothing needs you right now. Queued and running work continues on its own." },
+    { key: "ready", label: "Ready", hint: "Results waiting for you to accept or send back.", empty: "Nothing is ready for review." },
     { key: "running", label: "Running", hint: "Attempts a builder owns right now.", empty: "Nothing is running right now. Approved tasks start when a builder with capacity is connected." },
     { key: "queued", label: "Queued", hint: "Tasks that start on their own: waiting for a builder, a dependency or a retry.", empty: "Nothing is queued." },
-    { key: "completed", label: "Finished", hint: "Tasks the lead or user has marked complete. Recorded check results remain available.", empty: "Nothing has finished in this view yet." },
-    { key: "archived", label: "Archived", hint: "Tasks put away by you or by tidy. Their history and results are kept.", empty: "Nothing is put away." },
+    { key: "completed", label: "Finished", hint: "Tasks the lead or you accepted. Recorded check results stay available.", empty: "Nothing has finished in this view yet." },
+    { key: "archived", label: "Archived", hint: "Tasks archived by you or automatically. Their history and results are kept.", empty: "Nothing is archived." },
 ];
 export function parseWorkView(raw) {
-    return raw === "needs-you" || raw === "running" || raw === "queued" || raw === "completed" || raw === "archived" ? raw : "all";
+    return raw === "needs-you" || raw === "ready" || raw === "running" || raw === "queued" || raw === "completed" || raw === "archived" ? raw : "all";
 }
 /** The review facts from the store's bounded retry projection — the same
  * reading `diagnoseTaskDispatch` makes, so every surface starts from one
@@ -141,8 +144,8 @@ function machineVerdictWords(result, check) {
         return `the approved check failed against it${exit === null ? "" : ` (exit ${exit})`}`;
     }
     if (problem === "mismatched")
-        return "its evidence did not match the sealed record";
-    return "its required evidence was missing";
+        return "its saved files didn't match the record";
+    return "its required files were missing";
 }
 /** The approved check passed (task-status.ts approvedCheckStateOf): its own pass, or checks Off covered by a passing
  * release check. A re-run underway keeps the pass it had. */
@@ -180,7 +183,7 @@ function storedResultStatusOf(result, publication) {
             // Acceptance records a person's decision; it neither proves nor
             // disproves anything about the checks. The machine's own verdict is
             // restated as recorded.
-            detail: withPublication(`An approver accepted this result by hand, and the recorded exception says why. The machine's verdict is unchanged: ${machineVerdictWords(result, check)}.`),
+            detail: withPublication(`An approver accepted this result by hand, and their reason says why. The checks are unchanged: ${machineVerdictWords(result, check)}.`),
             tone: "done",
             action: { label: "Open the recorded exception", kind: "open-review" },
         };
@@ -228,16 +231,16 @@ function storedResultStatusOf(result, publication) {
         // at adjudication; only a verdict-less no-change reads its two
         // presence facts here.
         return result.recordComplete === false && result.verdict === null
-            ? { token: "record-incomplete", label: "No-change result, record incomplete", detail: "The build concluded nothing needed to change, but its handoff or sealed diff is missing.", tone: "problem", action: { label: "Open the record", kind: "open-run" } }
-            : { token: "no-change", label: "No changes were needed", detail: withPublication("The build concluded nothing needed to change; its handoff and sealed diff are on record."), tone: "done", action: { label: OPEN_RESULT, kind: "open-result" } };
+            ? { token: "record-incomplete", label: "No-change result, record incomplete", detail: "The build concluded nothing needed to change, but its handoff or saved diff is missing.", tone: "problem", action: { label: "Open the record", kind: "open-run" } }
+            : { token: "no-change", label: "No changes were needed", detail: withPublication("The build concluded nothing needed to change; its handoff and saved diff are on record."), tone: "done", action: { label: OPEN_RESULT, kind: "open-result" } };
     }
     if (result.verdict === null) {
         return {
             token: "verification-needed",
-            label: "Result saved — verification needed",
-            detail: withPublication("No verification result is recorded for this build."),
+            label: "No check result for this build yet",
+            detail: withPublication("No check result for this build yet. Run checks on it."),
             tone: "problem",
-            action: { label: "See what is missing", kind: "open-review" },
+            action: { label: "Run checks", kind: "open-review" },
         };
     }
     // Any verdict short of a pass the check confirms: never "passed" when the check can't be read now.
@@ -250,8 +253,8 @@ function storedResultStatusOf(result, publication) {
     if (result.verdict === "attested" && !passedNow(check)) {
         return {
             token: "agent-attested",
-            label: "Result saved — checks reported by the agent",
-            detail: withPublication("No independent project check ran; the checks listed are the agent's own report."),
+            label: "Ready · no project check set up",
+            detail: withPublication("No project check is set up, so the checks listed are the agent's own report."),
             tone: "neutral",
             action: { label: OPEN_RESULT, kind: "open-result" },
         };
@@ -322,11 +325,14 @@ const DISPATCH_ACTION_LABELS = {
     "inspect-hold": "Review hold",
     "repair-dependency": "Review required task",
     "repair-capability": "Review missing requirement",
-    "start-worker": "Check connection",
+    "start-worker": "Start the builder",
     "retry-review": "Review retry options",
     "resume-run": "Review pause",
 };
 export function dispatchActionLabel(dispatch) {
+    // One label everywhere for the builder (needs-you.ts NEEDS): Connect a builder, or Start the builder.
+    if (dispatch?.action === "start-worker")
+        return dispatch.code === "no-worker-registered" ? NEEDS["connect-builder"].action.label : NEEDS["start-builder"].action.label;
     return dispatch?.action == null ? "View task details" : DISPATCH_ACTION_LABELS[dispatch.action];
 }
 /** Result tokens a done task can wear, as the shared stage they mean. A
@@ -376,7 +382,7 @@ export function reportMismatchesOf(reasons, criteria, changes) {
             return [{ text: plainReasonWords(reason), ...place(review[1]), note: null, reason }];
         const unsigned = UNSIGNED_NOTE.exec(reason);
         if (unsigned !== null)
-            return [{ text: `The report's note ${unsigned[1]} is about ${unsigned[2]}, which isn't one of the signed requirements: ${unsigned[3]}`, path: null, lines: null, inChanges: null, note: Number(unsigned[1]), reason }];
+            return [{ text: `The report's note ${unsigned[1]} is about ${unsigned[2]}, which isn't one of the approved requirements: ${unsigned[3]}`, path: null, lines: null, inChanges: null, note: Number(unsigned[1]), reason }];
         if (FAILED_CHECK.test(reason))
             return [];
         return [{ text: sentenceOf(plainReasonWords(reason)), path: null, lines: null, inChanges: null, note: note === null ? null : Number(note), reason }];
@@ -419,7 +425,7 @@ export function lastErrorLineOf(log) {
     return (stderr >= 0 ? pick(stderr + 1, lines.length) : null) ?? pick(0, stderr >= 0 ? stderr : lines.length);
 }
 /** The result page's own sentence when the decision is on it. */
-export const RESULT_DECISION_SENTENCE = "Review the change, then accept it or ask for changes.";
+export const RESULT_DECISION_SENTENCE = "Review the change, then accept it or send it back.";
 export function acceptWordsOf(facts) {
     const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
     const parts = [
@@ -435,7 +441,7 @@ export function acceptWordsOf(facts) {
         : facts.publishing === "pull-request" ? "Finishes the task. No pull request opens; you can open one from the task after."
             : facts.publishing === "off" ? "Finishes the task. The branch stays; publishing isn't set up."
                 : "Finishes the task. Nothing is published.";
-    return { label: ready ? "Accept and finish" : "Accept without checks", ready, why: ready ? null : `${joined.charAt(0).toUpperCase()}${joined.slice(1)}.`, effect };
+    return { label: ready ? "Accept" : "Accept without checks", ready, why: ready ? null : `${joined.charAt(0).toUpperCase()}${joined.slice(1)}.`, effect };
 }
 export function resultHeadlineOf(status) {
     const read = RESULT_NEEDS_YOU.has(status.token) ? { stage: "needs-you", need: "other" }
@@ -454,8 +460,8 @@ export function workStatusOf(facts, resultDisplay) {
         : stageOfCode(status.token, { needsPerson: status.views.includes("needs-you"), planning: facts.dispatch?.code === "running" && facts.dispatch.role === "planner", operatorHold: facts.dispatch?.action === "unhold" });
     const stage = done && read.stage !== "needs-you" && read.stage !== "failed" ? "finished" : read.stage;
     const level = facts.result?.checkLevel ?? null;
-    const shared = taskStatusOf({ stage, ...(read.need === undefined ? {} : { need: read.need }), reason: plainReasonOf(stage, status.token, status.detail),
-        report: facts.result?.role === "scout", checks: stage !== "finished" ? null : VERIFIED_RESULT.has(status.token) ? { status: "passed", exitCode: null, head: null, level }
+    const shared = taskStatusOf({ stage, ...(read.need === undefined ? {} : { need: read.need }), ...(read.wait === undefined ? {} : { wait: read.wait }), reason: plainReasonOf(stage, status.token, status.detail),
+        report: facts.result?.role === "scout", ...(facts.machine === true ? { machine: true } : {}), checks: stage !== "finished" ? null : VERIFIED_RESULT.has(status.token) ? { status: "passed", exitCode: null, head: null, level }
             : level === "off" ? { status: "not-run", exitCode: null, head: null, level } : null });
     return { ...status, label: shared.headline, tone: workToneOf(shared.headline), detail: stage === "finished" && level !== "off" ? status.detail : shared.sentence };
 }
@@ -464,7 +470,8 @@ function workStatusWordsOf(facts, resultDisplay) {
     const result = facts.state === "done" ? resultDisplay ?? resultStatusOf(facts.result, facts.publication) : null;
     const running = facts.liveRunId !== null || (dispatch?.condition === "running" && !REVIEW_TOKENS.has(dispatch.code));
     const question = (facts.state === "queued" || facts.state === "running" || facts.state === "done") ? facts.openDecision ?? null : null;
-    const needs = (dispatch !== null && !REVIEW_TOKENS.has(dispatch.code) && needsPerson(dispatch)) || question !== null;
+    const held = (facts.heldFindings ?? 0) > 0 && facts.state !== "cancelled";
+    const needs = (dispatch !== null && !REVIEW_TOKENS.has(dispatch.code) && needsPerson(dispatch)) || question !== null || held;
     const views = ["all"];
     if (needs)
         views.push("needs-you");
@@ -474,6 +481,10 @@ function workStatusWordsOf(facts, resultDisplay) {
         views.push("queued");
     if (facts.state === "done")
         views.push("completed");
+    const findingWords = (behind) => ({
+        token: "finding-held", label: "Needs you", detail: NEEDS.finding.sentence({}), tone: "attention", action: { label: NEEDS.finding.action.label, kind: "open-findings" }, views, rank: 0,
+        ...(behind === null ? {} : { diagnostics: [behind] }),
+    });
     const dispatchWords = (tone, rank, action) => ({
         token: dispatch?.code ?? "unknown",
         label: dispatch?.summary ?? "Status unknown",
@@ -486,7 +497,7 @@ function workStatusWordsOf(facts, resultDisplay) {
     // The control projection knows whether a stop has actually settled.
     // A still-live claim alone cannot distinguish Running from Stopping.
     if (facts.control?.kind === "stopping") {
-        return { token: "stopping", label: "Stopping…", detail: facts.control.detail ?? "The attempt is ending. Its work is preserved; resume becomes available after its processes exit.", tone: "attention", action: { label: "View stop details", kind: "open-task" }, views, rank: 0 };
+        return { token: "stopping", label: "Stopping…", detail: facts.control.detail ?? "The attempt is ending. Its work is preserved; resume becomes available after its processes exit.", tone: "attention", action: { label: "View stop details", kind: "open-task" }, views, rank: 1 };
     }
     if (facts.control?.kind === "paused") {
         return { token: "stopped", label: "Paused", detail: "The stopped attempt's work is preserved. Resuming requires confirmation and checks the current approval again.", tone: "attention", action: { label: "Review pause", kind: "open-task" }, views, rank: 0 };
@@ -499,6 +510,8 @@ function workStatusWordsOf(facts, resultDisplay) {
                 tone: "attention", action: { label: "Answer question", kind: "open-task" }, views, rank: 0,
                 diagnostics: [{ token: result.token, label: result.label, detail: result.detail, tone: result.tone }] };
         }
+        if (held && result.tone !== "problem")
+            return findingWords({ token: result.token, label: result.label, detail: result.detail, tone: result.tone });
         return { ...result, views, rank: needs ? 0 : 3 };
     }
     if (facts.state === "cancelled") {
@@ -513,6 +526,8 @@ function workStatusWordsOf(facts, resultDisplay) {
             }),
         };
     }
+    if (held && facts.state !== "failed")
+        return findingWords(dispatch === null ? null : { token: dispatch.code, label: dispatch.summary, detail: dispatch.detail, tone: running ? "live" : "attention" });
     if (running) {
         return dispatchWords("live", 1, { label: "Watch the build", kind: facts.liveRunId === null ? "open-task" : "open-run" });
     }
@@ -529,7 +544,7 @@ function workStatusWordsOf(facts, resultDisplay) {
 }
 /** The counts each view tab wears — from the same rows the page lists. */
 export function workCounts(rows) {
-    const counts = { all: 0, "needs-you": 0, running: 0, queued: 0, completed: 0, archived: 0 };
+    const counts = { all: 0, "needs-you": 0, ready: 0, running: 0, queued: 0, completed: 0, archived: 0 };
     for (const row of rows)
         for (const view of row.views)
             counts[view] += 1;
@@ -557,7 +572,7 @@ export function learningHtml(view, csrf, canManage, source) {
     const act = (action, label, lesson) => canManage && csrf ? postForm('/settings/learning/change', html `<button type="submit">${label}</button>`, { hidden: { ...base, action, ...(lesson ? { lesson: lesson.id, version: lesson.version, sha: lesson.sha } : {}) } }) : '';
     const evidence = (list, run) => list.map(one => html `<li><a href="/r/${String(one.runId ?? run)}/evidence/${one.artifactId}">Source #${one.artifactId}</a><blockquote>${one.excerpt}</blockquote><code>${one.sha256}</code></li>`);
     const lessons = view.lessons.filter(l => source === undefined || l.source === source);
-    const cards = lessons.map(l => html `<article class="card" data-lesson="${l.id}"><p><strong>${l.payload.observation}</strong></p><p>${l.payload.action}</p><p class="meta">${l.payload.kind === 'system' ? 'System suggestion · No change applied' : l.status === 'adopted' ? 'Adopted advice' : l.status === 'disabled' ? 'Disabled' : 'Proposed lesson'}</p><details><summary>Source and use</summary><p><a href="/r/${l.source}">Result #${l.source}</a> · <a href="/r/${l.reviewer}">Review #${l.reviewer}</a></p><p>${l.payload.paths.join(', ')} · ${l.payload.phases.join(', ')} · ${{ darwin: "macOS", win32: "Windows", linux: "Linux" }[l.payload.platform] ?? l.payload.platform}</p><ul>${evidence(l.payload.evidence, l.source)}</ul>${l.payload.kind !== 'project' ? '' : html `<p class="meta">${l.status === 'proposed' ? 'Save permits advisory reuse when enabled and applicable. It does not prove a remedy works.' : 'Disabling affects future runs. Active snapshots, code and approvals stay unchanged.'}</p>${l.status === 'proposed' ? act('adopt', 'Save lesson', l) : ''}`}</details>${l.payload.kind === 'project' && l.status === 'adopted' ? act('disable', 'Disable lesson', l) : ''}</article>`);
+    const cards = lessons.map(l => html `<article class="card" data-lesson="${l.id}"><p><strong>${l.payload.observation}</strong></p><p>${l.payload.action}</p><p class="meta">${lastIncludedWords(view.use.get(`lesson:${l.id}`))}</p><p class="meta">${l.payload.kind === 'system' ? 'System suggestion · No change applied' : l.status === 'adopted' ? 'Adopted advice' : l.status === 'disabled' ? 'Disabled' : 'Proposed lesson'}</p><details><summary>Source and use</summary><p><a href="/r/${l.source}">Result #${l.source}</a> · <a href="/r/${l.reviewer}">Review #${l.reviewer}</a></p><p>${l.payload.paths.join(', ')} · ${l.payload.phases.join(', ')} · ${{ darwin: "macOS", win32: "Windows", linux: "Linux" }[l.payload.platform] ?? l.payload.platform}</p><ul>${evidence(l.payload.evidence, l.source)}</ul>${l.payload.kind !== 'project' ? '' : html `<p class="meta">${l.status === 'proposed' ? 'Save permits advisory reuse when enabled and applicable. It does not prove a remedy works.' : 'Disabling affects future runs. Active snapshots, code and approvals stay unchanged.'}</p>${l.status === 'proposed' ? act('adopt', 'Save lesson', l) : ''}`}</details>${l.payload.kind === 'project' && l.status === 'adopted' ? act('disable', 'Disable lesson', l) : ''}</article>`);
     if (source !== undefined)
         return lessons.length ? html `<details class="learning result-learning"><summary>Learned from this task</summary>${cards}<a href="/settings/learning?repo=${encodeURIComponent(view.repo)}">Learning settings</a></details>` : html ``;
     const history = view.events.map(ev => html `<article class="card" data-learning-event="${ev.action}"><p><strong>${{ assessment: { propose: 'Learning suggested', none: 'No lesson needed', unassessed: 'Learning not assessed', invalid: 'Learning assessment invalid' }[ev.after] ?? 'Learning not assessed', proposal: 'Suggestion recorded', adopt: 'Lesson adopted', disable: 'Lesson disabled', reset: 'Learning reset', enable: 'Reuse enabled', pause: 'Reuse paused', reuse: 'Run context saved', failure: 'Learning issue', capture: 'Capture finished' }[ev.action] ?? ev.action}</strong>${ev.action === "reuse" ? ` · ${ev.after}` : ""}</p><p class="meta">${whenUtc(ev.at)} · ${ev.actor}${ev.run === null ? '' : html ` · <a href="/r/${ev.run}">Run #${ev.run}</a>${ev.outcome === null ? "" : ` · ${ev.outcome}`}`}</p><details><summary>Details</summary><p>${ev.before} → ${ev.after}</p><p>${ev.reason}</p>${ev.lesson === null ? '' : html `<p>Lesson #${ev.lesson}</p>`}<ul>${evidence(ev.evidence, ev.run)}</ul>${ev.snapshot === null ? "" : html `<details><summary>Exact context</summary><pre>${ev.snapshot}</pre></details>`}</details></article>`);

package/dist/worktree.d.ts

@@ -96,7 +96,7 @@ export type LeaseResult = {
 };
 export type LeaseFailure = "held" | "dirty" | "git" | "unverified" | "unknown-runner" | "in-use";
 /** Why storage retention left a checkout in place. */
-export type KeptWhy = "has changes" | "has commits" | "unreadable" | "git refused";
+export type KeptWhy = "has changes" | "has commits" | "not on its branch" | "unreadable" | "git refused";
 /**
  * The note a lease leaves in the checkout, naming the process holding it.
  *
@@ -291,15 +291,24 @@ export declare class WorktreePool {
      * or remote. Reads only, through `git` when given (teardown's hardened git).
      */
     inspect(path: string, git?: Git): Promise<"clean" | KeptWhy>;
+    /**
+     * Whether a checkout a task may still come back to can go, beyond `inspect`: a later lease of its branch must make the
+     * same checkout, and every commit its task recorded must outlive it (git's garbage collection counts a worktree's HEAD
+     * and reflog; once they go only a branch holds a commit). So: the folder is the pool's own, the checkout belongs to its
+     * project by the plane's record (`boundDirs`, not its `.git` file), its HEAD is its recorded branch, every recorded
+     * `heads` commit is on a branch, and no ref lives only in this worktree. Reads only; anything unreadable keeps it.
+     */
+    proveRecreatable(row: WorktreeRow, heads: readonly string[]): Promise<"clean" | KeptWhy>;
     /**
      * Keep storage in check: remove the working copies nobody needs any more. Of `rows`, a checkout goes when it is
      * let go, nothing holds it, `wanted` says it may go (asked again right before it goes, so a task coming back or a
      * lease since keeps it) and `inspect` finds it clean, then clean still right before it goes (git refuses an edit
      * made after that). Only the working copy goes: its branch, and so every commit,
      * stays, and a later lease of the same branch makes a new one. At most `max` go per pass. Every git command goes
-     * through `git` when given: landed cleanup passes its hardened teardown git (teardown-git.ts).
+     * through `git` when given: landed cleanup passes its hardened teardown git (teardown-git.ts). `proof` is asked last,
+     * inside the reservation, for what `inspect` doesn't cover (idle cleanup: `proveRecreatable`).
      */
-    prune(rows: readonly WorktreeRow[], wanted: (row: WorktreeRow, fresh: boolean) => boolean | Promise<boolean>, max?: number, git?: Git): Promise<{
+    prune(rows: readonly WorktreeRow[], wanted: (row: WorktreeRow, fresh: boolean) => boolean | Promise<boolean>, max?: number, git?: Git, proof?: (row: WorktreeRow) => Promise<"clean" | KeptWhy>): Promise<{
         removed: WorktreeRow[];
         kept: {
             path: string;

package/dist/worktree.js

@@ -22,17 +22,19 @@
  * synced folder like OneDrive or Dropbox, where a sync client racing an agent
  * over `.git` internals corrupts both.
  */
+import { INCIDENT_QUIET_MS, recentGitIncident } from "./git-incident.js";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, writeFileSync, rmSync, realpathSync, mkdirSync, readdirSync, renameSync } from "node:fs";
 import { hostname } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { run } from "./exec.js";
 import { currentBootId, provenDeadByBootChange } from "./boot-identity.js";
+import { currentMachineId, isThisMachine } from "./machine-identity.js";
 import { HANDOFF_PREFIX, MAILBOX_SUFFIX, looksLikeProtocolFile, readMailbox } from "./evidence.js";
 import { parseHandoff } from "./decision.js";
 import { diskBytes } from "./storage.js";
 import { markNeverIndex } from "./never-index.js";
-import { checkoutGit, teardownGit } from "./teardown-git.js";
+import { checkoutGit, gitIncidentRecord, teardownGit } from "./teardown-git.js";
 /**
  * The note a lease leaves in the checkout, naming the process holding it.
  *
@@ -55,7 +57,8 @@ const reservationPath = (path) => `${path}.occupancy`;
 function reservation(path) {
     try {
         const note = JSON.parse(readFileSync(reservationPath(path), "utf8"));
-        if (Number.isSafeInteger(note.pid) && note.pid > 0 && typeof note.host === "string" && typeof note.token === "string")
+        if (Number.isSafeInteger(note.pid) && note.pid > 0 && typeof note.host === "string" && typeof note.token === "string"
+            && (note.machineId === undefined || note.machineId === null || typeof note.machineId === "string"))
             return note;
     }
     catch (error) {
@@ -66,9 +69,9 @@ function reservation(path) {
     return { pid: 0, host: "unknown", bootId: null, token: "unknown" };
 }
 function reservationAlive(note) {
-    if (note.pid === 0 || note.host !== hostname())
+    if (note.pid === 0 || !isThisMachine(note))
         return true;
-    if (note.bootId !== null && provenDeadByBootChange(note))
+    if (note.bootId !== null && provenDeadByBootChange(note, { host: note.host, bootId: currentBootId() }))
         return false;
     try {
         process.kill(note.pid, 0);
@@ -81,7 +84,7 @@ function reservationAlive(note) {
 /** A short store transaction arbitrates marker creation/recovery, never git, a scan or deletion.
  * Atomic rename publishes a complete owner; a crash cannot leave a half-written reservation. */
 function reserveCheckout(store, path) {
-    const note = { pid: process.pid, host: hostname(), bootId: currentBootId(), token: randomBytes(12).toString("hex") };
+    const note = { pid: process.pid, host: hostname(), bootId: currentBootId(), token: randomBytes(12).toString("hex"), machineId: currentMachineId() };
     const file = reservationPath(path), temp = `${file}.${note.token}`;
     const held = store.transact(() => {
         const prior = reservation(path);
@@ -155,6 +158,18 @@ function safePoolPath(root, target) {
     }
     return true;
 }
+/** The checkout itself, strictly inside the pool as real paths, reached by real folders only: never a link out of it. */
+function insidePool(root, path) {
+    if (!safePoolPath(root, path))
+        return false;
+    try {
+        const real = realpathSync(path), base = realpathSync(root);
+        return real !== base && real.startsWith(base + sep) && lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function normalisePath(path) {
     return path.replace(/\\/g, "/").replace(/\/+$/, "");
 }
@@ -178,12 +193,12 @@ export function recordWorktreeProcess(store, path, runner, pid, leaseEpoch) {
     // verified boot change nothing of it survives, and the checkout is free
     // without a PID probe that a reused pid could answer wrongly.
     const bootId = currentBootId();
-    writeFileSync(join(path, MARKER), `${pid} ${runner} group ${bootId ?? "unknown"} ${hostname()}\n`, "utf8");
+    writeFileSync(join(path, MARKER), `${pid} ${runner} group ${bootId ?? "unknown"} ${hostname()} ${currentMachineId() ?? "unknown"}\n`, "utf8");
 }
 /** Read-only occupancy witness shared with stop settlement. */
 export function worktreeProcessOccupancy(path) {
     const reserved = reservation(path);
-    if (reserved !== null && (reserved.pid !== process.pid || reserved.host !== hostname()) && reservationAlive(reserved))
+    if (reserved !== null && (reserved.pid !== process.pid || !isThisMachine(reserved)) && reservationAlive(reserved))
         return { held: true, by: reserved.pid };
     const note = join(path, MARKER);
     if (!existsSync(note))
@@ -193,7 +208,9 @@ export function worktreeProcessOccupancy(path) {
     if (!Number.isInteger(pid) || pid <= 0)
         return { held: false };
     const noteHost = parts[4];
-    if (noteHost !== undefined && noteHost !== hostname())
+    // The sixth word (v150) is the writer's machine id; "unknown", or a note from before it, is matched by name.
+    const noteMachine = parts[5] === undefined || parts[5] === "unknown" ? null : parts[5];
+    if (noteHost !== undefined && !isThisMachine({ host: noteHost, machineId: noteMachine }))
         return { held: true, by: pid };
     if (pid === process.pid && parts[2] !== "group")
         return { held: false };
@@ -201,7 +218,7 @@ export function worktreeProcessOccupancy(path) {
     // that cannot exist any more; a note without a boot id (legacy) or a
     // boot this host cannot verify keeps the probe below.
     const noteBoot = parts[3];
-    if (noteBoot !== undefined && noteHost !== undefined && provenDeadByBootChange({ host: noteHost, bootId: noteBoot }))
+    if (noteBoot !== undefined && noteHost !== undefined && provenDeadByBootChange({ host: noteHost, bootId: noteBoot }, { host: noteHost, bootId: currentBootId() }))
         return { held: false };
     // A shell/provider can exit before its descendants. A recorded POSIX
     // process group remains an owner until that whole group has gone.
@@ -650,7 +667,7 @@ export class WorktreePool {
     /** Leave a note naming the process holding this checkout. */
     mark(path, runner, pid = process.pid) {
         try {
-            writeFileSync(join(path, MARKER), `${pid} ${runner} process ${currentBootId() ?? "unknown"} ${hostname()}\n`, "utf8");
+            writeFileSync(join(path, MARKER), `${pid} ${runner} process ${currentBootId() ?? "unknown"} ${hostname()} ${currentMachineId() ?? "unknown"}\n`, "utf8");
             return true;
         }
         catch {
@@ -837,6 +854,9 @@ export class WorktreePool {
      * or remote. Reads only, through `git` when given (teardown's hardened git).
      */
     async inspect(path, git = this.teardown) {
+        // A checkout that had a git incident lately is left alone (git-incident.ts): nothing re-runs git there each pass.
+        if (quietAfterIncident(path))
+            return "unreadable";
         const dirty = await this.isDirty(path, true, git);
         if (dirty !== false)
             return dirty === null ? "unreadable" : "has changes";
@@ -846,15 +866,51 @@ export class WorktreePool {
             return "unreadable";
         return own.stdout.trim() === "" ? "clean" : "has commits";
     }
+    /**
+     * Whether a checkout a task may still come back to can go, beyond `inspect`: a later lease of its branch must make the
+     * same checkout, and every commit its task recorded must outlive it (git's garbage collection counts a worktree's HEAD
+     * and reflog; once they go only a branch holds a commit). So: the folder is the pool's own, the checkout belongs to its
+     * project by the plane's record (`boundDirs`, not its `.git` file), its HEAD is its recorded branch, every recorded
+     * `heads` commit is on a branch, and no ref lives only in this worktree. Reads only; anything unreadable keeps it.
+     */
+    async proveRecreatable(row, heads) {
+        if (quietAfterIncident(row.path))
+            return "unreadable";
+        if (row.branch === "unknown" || !insidePool(this.options.root, row.path) || heads.some(one => !/^[0-9a-f]{40,64}$/.test(one)))
+            return "unreadable";
+        const git = teardownGit(this.runner, { repo: row.repo });
+        const head = await git(row.path, [...READ_ONLY, "symbolic-ref", "-q", "HEAD"]);
+        if (head.code === 1)
+            return "not on its branch";
+        if (head.code !== 0)
+            return "unreadable";
+        if (head.stdout.trim() !== `refs/heads/${row.branch}`)
+            return "not on its branch";
+        const branch = await git(row.repo, [...READ_ONLY, "rev-parse", "--verify", "--quiet", `refs/heads/${row.branch}^{commit}`]);
+        if (branch.code !== 0)
+            return "unreadable";
+        if (heads.length > 0) {
+            const unheld = await git(row.repo, [...READ_ONLY, "rev-list", "-1", ...heads, "--not", "--branches"]);
+            if (unheld.code !== 0)
+                return "unreadable";
+            if (unheld.stdout.trim() !== "")
+                return "has commits";
+        }
+        const own = await git(row.path, [...READ_ONLY, "for-each-ref", "--count=1", "refs/worktree", "refs/bisect", "refs/rewritten"]);
+        if (own.code !== 0)
+            return "unreadable";
+        return own.stdout.trim() === "" ? "clean" : "has commits";
+    }
     /**
      * Keep storage in check: remove the working copies nobody needs any more. Of `rows`, a checkout goes when it is
      * let go, nothing holds it, `wanted` says it may go (asked again right before it goes, so a task coming back or a
      * lease since keeps it) and `inspect` finds it clean, then clean still right before it goes (git refuses an edit
      * made after that). Only the working copy goes: its branch, and so every commit,
      * stays, and a later lease of the same branch makes a new one. At most `max` go per pass. Every git command goes
-     * through `git` when given: landed cleanup passes its hardened teardown git (teardown-git.ts).
+     * through `git` when given: landed cleanup passes its hardened teardown git (teardown-git.ts). `proof` is asked last,
+     * inside the reservation, for what `inspect` doesn't cover (idle cleanup: `proveRecreatable`).
      */
-    async prune(rows, wanted, max = Infinity, git = this.teardown) {
+    async prune(rows, wanted, max = Infinity, git = this.teardown, proof) {
         const removed = [];
         const kept = [];
         const idle = (row, releasedAt) => row !== null && row.runner === null && row.releasedAt === releasedAt && !this.inUse(row.path).held;
@@ -888,6 +944,11 @@ export class WorktreePool {
                 const allowed = wanted(now, true);
                 if (!(typeof allowed === "boolean" ? allowed : await allowed))
                     continue;
+                const proven = proof === undefined ? "clean" : await proof(now);
+                if (proven !== "clean") {
+                    kept.push({ path: row.path, why: proven });
+                    continue;
+                }
                 const gone = await this.removeCleanCopy(row, git);
                 if (gone !== "removed") {
                     kept.push({ path: row.path, why: gone });
@@ -931,7 +992,7 @@ export class WorktreePool {
                 return { ok: false, message: `${row.path} is in use` };
             // Held while it slims: another process's lease sees this process in it.
             try {
-                writeFileSync(note, `${process.pid} storage-retention slimming ${currentBootId() ?? "unknown"} ${hostname()}\n`, "utf8");
+                writeFileSync(note, `${process.pid} storage-retention slimming ${currentBootId() ?? "unknown"} ${hostname()} ${currentMachineId() ?? "unknown"}\n`, "utf8");
                 held = true;
             }
             catch {
@@ -989,7 +1050,7 @@ export class WorktreePool {
         // Held while it goes: another process's lease sees this process in it (the busy map is this process's only).
         const note = join(row.path, MARKER);
         try {
-            writeFileSync(note, `${process.pid} storage-retention removing ${currentBootId() ?? "unknown"} ${hostname()}\n`, "utf8");
+            writeFileSync(note, `${process.pid} storage-retention removing ${currentBootId() ?? "unknown"} ${hostname()} ${currentMachineId() ?? "unknown"}\n`, "utf8");
         }
         catch {
             return false;
@@ -1065,3 +1126,19 @@ function firstLine(text) {
     const [line = ""] = text.trim().split("\n");
     return line;
 }
+/** Whether a checkout had a git incident within INCIDENT_QUIET_MS (by its real path, as incidents record it). */
+function quietAfterIncident(path) {
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch {
+        return false;
+    }
+    try {
+        return recentGitIncident(gitIncidentRecord(), real, new Date(Date.now() - INCIDENT_QUIET_MS));
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.93",
+  "version": "0.9.95",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"
@@ -133,6 +133,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.79",
+    "@json-render/core": "0.22.0",
     "@slack/socket-mode": "3.1.1",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",