toolroll 0.9.104 → 0.9.105

package/dist/dispose.js

@@ -1,21 +1,8 @@
-// Assignment tracking grants no repair authority or attempts.
 import { STORAGE_HOLD_PREFIX } from "./needs-you.js";
 import { blockAfterSignedOut } from "./fallback.js";
 import { authorizeCheckOnly } from "./check-only.js";
 import { proposeNewRoute } from "./route-change.js";
 import { originalTaskBase, focusedTestCommandSupported } from "./observations.js";
-/**
- * The build disposition service (Parity II Phase 2, v4 Q2 / v6 W1): the
- * operations that actually END an attempt — sealing parks, accepting
- * completions behind the completion fence, recording failures with their
- * strikes and holds, opening publication intents — extracted from tick's
- * and the standalone build command's finalizers into ONE place. The two
- * historical roads differ deliberately
- * (the standalone command completes no task, strikes nothing, publishes
- * nothing), and the policy record says so explicitly instead of forking
- * the logic: behavior on both is byte-identical to what the callers
- * inlined before.
- */
 import { createHash } from "node:crypto";
 import { interruptIfStopped, release, finalize, } from "./claim.js";
 import { bodyHashOf, publicationBody } from "./publish.js";
@@ -31,7 +18,6 @@ import { classifyGateFailure, describeGateFailure, gateFailureSummary } from "./
 import { propose, approve, liveReleaseOf, releaseCheckScope } from "./scope.js";
 import { headWithin } from "./names.js";
 import { recordExecClass } from "./route-store.js";
-/** The reasons tick classifies as the attempt itself breaking. */
 const TICK_FAILURE_REASONS = new Set([
     "agent",
     "agent-reported",
@@ -46,14 +32,9 @@ const TICK_FAILURE_REASONS = new Set([
     "setup",
     "revision-brief",
     "stopped",
-    // Phase 3 (C1): the gateway's typed refusals consume the task strike
-    // budget like every other infrastructure failure — the pre-claim skip
-    // keeps the NORMAL road from ever reaching here; these arms bound the
-    // races.
     "provider-unattested",
     "provider-protocol",
 ]);
-/** The standalone road's historical "broke" list — narrower, deliberately. */
 const STANDALONE_BROKE_REASONS = new Set([
     "agent",
     "agent-reported",
@@ -63,30 +44,16 @@ const STANDALONE_BROKE_REASONS = new Set([
     "timeout",
     "git",
 ]);
-/** A committed build whose approved check passed gets the project's one
- * automatic review when its review switch is on (build-review.ts). No-change
- * results and failed checks go straight to the person, as before. */
 export function maybeRequestAutoReview(store, repo, runId, committed, noChange, now, root = evidenceRoot(homedir())) {
     if (!committed || noChange)
         return;
     queueBuildReview(store, repo, runId, root, now);
 }
 export function disposeBuildOutcome(context, result) {
-    // Stop and every terminal side effect compete under the same SQLite
-    // write lock. A separate preliminary transaction leaves a completion gap.
     return context.store.transact(() => disposeBuildOutcomeLocked(context, result));
 }
 function disposeBuildOutcomeLocked(context, result) {
     const { store, policy, leaseId, runId, taskId, taskRef, runner, repo, branch, origin, provider, model, worktreePath, clock } = context;
-    // THE STOP FENCE at settlement (v52), before any arm below and inside
-    // its own transaction: a stop recorded against this attempt (or the
-    // ancestor it runs under) before this instant WINS — a late success is
-    // never accepted as done, a park is never sealed, a failure never takes
-    // a strike. The attempt ends as interrupted with its work preserved (a
-    // commit it made stays on the branch as a reviewable artifact), its
-    // stop settles, and the task waits under the stop's own hold. The
-    // already-sealed revision endings are exempt exactly as below: their
-    // finalizer fenced the stop itself, inside its own transaction.
     if (result.ok || (result.reason !== "plan-revised" && result.reason !== "plan-revision-blocked")) {
         const stopped = store.transact(() => {
             const run = store.getRun(runId);
@@ -117,8 +84,6 @@ function disposeBuildOutcomeLocked(context, result) {
         });
         if (!sealed.ok)
             return { kind: "park-fenced" };
-        // A park is the system working, and it ends any failure streak — on the
-        // loop's road. The standalone command never touched strikes.
         if (policy === "tick")
             store.resetStrikes(taskRef);
         return { kind: "parked", decisionId: sealed.decisionId };
@@ -135,15 +100,10 @@ function disposeBuildOutcomeLocked(context, result) {
         }
         if (leaseId === undefined)
             return { kind: "built-fenced" };
-        // The completion has to be *accepted*, not assumed — one transaction
-        // around the fenced release, the run's outcome, and the publication
-        // intent, so "done" and "this must reach a PR" cannot come apart.
         const sealed = store.transact(() => {
             const fence = finalize(store, leaseId, { kind: "complete", state: "done", now: clock() });
             if (!fence.ok)
                 return fence;
-            // The disowned arm (external dispatch, v4 §24): the tracker closed
-            // this mirror while it was being built.
             if (fence.arm === "disowned") {
                 store.finishRun(runId, { outcome: "failed", reason: "external-closed", committed: result.committed, now: clock() });
                 store.enqueueNotification({
@@ -161,9 +121,7 @@ function disposeBuildOutcomeLocked(context, result) {
                 committed: result.committed,
                 now: clock(),
             });
-            // A stated no-change publishes nothing.
             if (result.noChange !== true && result.committed) {
-                // The approval that built this commit allows one automatic recheck of it, should its verdict go missing.
                 authorizeCheckOnly(store, runId, clock());
                 const grant = store.publicationGrantFor(repo);
                 const headSha = store.getRun(runId)?.headRevision ?? null;
@@ -172,7 +130,6 @@ function disposeBuildOutcomeLocked(context, result) {
                     headSha !== null &&
                     headWithin(branch, grant.headPrefix) &&
                     (grant.selector === "all" || origin === "ours") &&
-                    // A nightly check or a release's task is never published (store.createPublicationIntent refuses both).
                     !nightlyTaskRef(store, taskRef) && !releaseTaskRef(store, taskRef)) {
                     const intentId = store.createPublicationIntent({
                         run: runId,
@@ -185,8 +142,6 @@ function disposeBuildOutcomeLocked(context, result) {
                         bodyHash: "",
                         draft: grant.draft,
                     }, clock());
-                    // The body's identity is computed from the rows this very
-                    // transaction made durable — reproducible after any crash.
                     const publication = store.publicationForRun(runId);
                     if (publication !== null) {
                         store.handle
@@ -200,8 +155,6 @@ function disposeBuildOutcomeLocked(context, result) {
         if (sealed.ok && sealed.arm === "disowned")
             return { kind: "disowned" };
         if (sealed.ok) {
-            // A concluded success ends the failure streak and its backoff — and
-            // proves the credential, clearing any quota stamp.
             store.resetStrikes(taskRef);
             store.clearQuota(runner, provider, model ?? "");
             maybeRequestAutoReview(store, repo, runId, result.committed, result.noChange === true, clock(), context.evidenceRoot);
@@ -220,27 +173,6 @@ function disposeBuildOutcomeLocked(context, result) {
         });
         return { kind: "built-fenced" };
     }
-    // ---- refusals and failures -----------------------------------------------
-    // THE ALREADY-SEALED ENDINGS (adaptive execution plans). Every other arm
-    // below ends the attempt itself — releases the claim, writes the run's
-    // outcome, counts what it costs. These two arrive with all of that
-    // already done: `finalize` (a `revision` ending) released the lease, appended the
-    // ledger row, placed the hold when one was owed, finished the run, and
-    // paged, all inside ONE fenced transaction — the planner road's shape,
-    // where claim.ts owns the ending and dispose only reports it.
-    //
-    // So this branch exists to do NOTHING, deliberately, and it is placed
-    // above the policy arms so that every road — tick and standalone —
-    // skips them alike.
-    //
-    // Falling through instead would be wrong twice over. `release()` would
-    // survive it (an already-released lease whose `released_by` is
-    // 'released' reads as this same lease's duplicate hand-back, not a
-    // fence), but `finishRun` overwrites unconditionally, so the sealed
-    // `finished_at` would be restamped by a second, later writer; and the
-    // bottom of the chain returns `invariant`, which means "the dispatcher
-    // broke a rule it was supposed to uphold" — the opposite of what
-    // happened here, where the machine worked exactly as designed.
     if (result.reason === "plan-revised" || result.reason === "plan-revision-blocked") {
         return { kind: "skipped", reason: result.reason };
     }
@@ -262,14 +194,12 @@ function disposeBuildOutcomeLocked(context, result) {
         return { kind: "recorded", outcome };
     }
     if (result.reason === "unapproved" || result.reason === "scope-changed") {
-        // Approval drifted between the prefilter and the builder's own gate.
         if (leaseId !== undefined)
             release(store, leaseId, clock());
         store.finishRun(runId, { outcome: "refused", reason: result.reason, now: clock() });
         return { kind: "skipped", reason: result.reason };
     }
     if (result.reason === "fenced") {
-        // The lease did not survive the build. Nothing is ours to release.
         store.finishRun(runId, { outcome: "refused", reason: "fenced", now: clock() });
         return { kind: "fenced" };
     }
@@ -285,18 +215,12 @@ function disposeBuildOutcomeLocked(context, result) {
         });
         return { kind: "malformed", sealed: sealed.ok };
     }
-    // A stop no operator asked for is the SERVICE stopping (the fence above
-    // already settled every task stop): hand the attempt back, never strike it.
     if (result.reason === "stopped" && policy === "tick" && leaseId !== undefined && store.getRun(runId)?.role === "builder") {
         const handed = finalize(store, leaseId, { kind: "hand-back", runId, taskId, message: result.message, now: clock() });
         return { kind: "handed-back", requeued: handed.requeued };
     }
     if (TICK_FAILURE_REASONS.has(result.reason)) {
-        // Results routing (v148): the raw reason's execution class, kept on the run before the mapping below folds
-        // timeouts and setup failures together (route-store.ts recordExecClass; first write wins).
         recordExecClass(store, runId, result.reason);
-        // One fenced transaction decides what the failure means. The
-        // classification trusts only what the machine itself observed.
         const failureClass = result.reason === "agent-reported"
             ? "agent-reported"
             : result.reason === "no-handoff"
@@ -308,9 +232,6 @@ function disposeBuildOutcomeLocked(context, result) {
                         : result.reason === "commit-failure"
                             ? "commit-failure"
                             : "unknown";
-        // The attempt's ending, in words, on the run itself: the class is what
-        // the strikes count, the message is what a person reads (an agent's
-        // own verdict was already recorded by the builder under the same key).
         if (result.reason !== "agent-reported" && result.message.trim() !== "") {
             store.recordOutcomeFacts(runId, { handoff: result.message });
         }
@@ -337,9 +258,6 @@ function disposeBuildOutcomeLocked(context, result) {
         };
     }
     if (result.reason === "protected-storage") {
-        // The storage check couldn't finish (protected-storage.ts): nothing spent,
-        // no strike. The words are kept on the run, the task holds and tries
-        // again on its own, and a person reads why and which program to allow.
         if (leaseId !== undefined)
             release(store, leaseId, clock());
         if (result.message.trim() !== "")
@@ -348,21 +266,12 @@ function disposeBuildOutcomeLocked(context, result) {
         holdForStorage(store, { taskRef, taskId, message: result.message }, clock());
         return { kind: "skipped", reason: "protected-storage" };
     }
-    // no-claim, not-yours, not-leased, protected-branch, wrong-branch:
-    // invariants the dispatcher was supposed to uphold.
     if (leaseId !== undefined)
         release(store, leaseId, clock());
     store.finishRun(runId, { outcome: "refused", reason: result.reason, now: clock() });
-    // A fallback agent not signed in to its plan: the task waits for a person's retry, never loops (fallback.ts).
     if (result.reason === "auth-mode" && blockAfterSignedOut(store, runId, clock()))
         return { kind: "skipped", reason: "fallback-signed-out" };
     if (result.reason === "stale-approval") {
-        // A deterministic refusal (setup review): the approval no longer
-        // matches the routing, and nothing about the next pass changes that.
-        // Retrying every pass wrote a thousand refused runs in minutes. So:
-        // release, record, HOLD the task under a backoff the approval door
-        // lifts, and page once per approval — the operator re-approves (or
-        // reconfigures the build agent) and the hold goes with the yes.
         if (leaseId !== undefined)
             release(store, leaseId, clock());
         store.finishRun(runId, { outcome: "refused", reason: "stale-approval", now: clock() });
@@ -371,15 +280,8 @@ function disposeBuildOutcomeLocked(context, result) {
     }
     return { kind: "invariant", reason: result.reason };
 }
-/** How long a task waits after the storage check couldn't finish before it tries again on its own. */
 export const STORAGE_RETRY_MS = 10 * 60_000;
 export { STORAGE_HOLD_PREFIX };
-/**
- * The storage HOLD: the check couldn't finish, so no launch can be fenced
- * now. The task waits STORAGE_RETRY_MS and tries again on its own (a person
- * who allowed access in Privacy & Security needn't do more), and "Try again"
- * (unhold) lifts it at once. One message per task an hour, with the words.
- */
 export function holdForStorage(store, args, now) {
     store.holdOwned({ taskRef: args.taskRef, ownerKind: "backoff", ownerId: `storage:${args.taskRef}`, reason: `${STORAGE_HOLD_PREFIX}${args.message}`, until: new Date(now.getTime() + STORAGE_RETRY_MS) }, now);
     store.enqueueNotification({
@@ -392,17 +294,8 @@ export function holdForStorage(store, args, now) {
         body: `${args.message}\nIt tries again on its own in ${STORAGE_RETRY_MS / 60_000} minutes.`,
     }, now);
 }
-/**
- * The stale-approval HOLD, shared by the post-build disposition above and
- * the tick's pre-admission refusal (v48 integrity): a pre-routing row
- * whose sealed profile no longer matches what would resolve is refused
- * BEFORE any run row exists — held under the backoff the approval door
- * lifts, paged once per approval — so the fail-closed admission never
- * turns into a refusal every pass.
- */
 export function holdStaleApproval(store, args, now) {
     const scope = store.getScope(args.taskId);
-    // Toolroll proposes the new exact route itself (route-change.ts): the person's one act is Approve, on one line.
     const proposed = proposeNewRoute(store, args.taskRef, args.taskId, now);
     store.holdOwned({
         taskRef: args.taskRef,
@@ -421,31 +314,15 @@ export function holdStaleApproval(store, args, now) {
         body: `${proposed?.words ?? args.message}\nNothing runs on it until it's approved again.`,
     }, now);
 }
-// ---- the bounded repair loop (v40, evidence-review-v1) --------------------
-/** Whether a run's proof reasons name a LIE about the signed terms — an
- * altered criterion statement, or an overclaimed changed path — rather
- * than a gap in the work. The exact phrases `adjudicate()` uses for those
- * two rules, and no others; the integrity stop's own predicate. */
 function isIntegrityRefutation(reasons) {
     return reasons.some(one => one.includes("was signed as") || one.includes("not in the sealed diff"));
 }
-/** Strict shrink: `to` is a proper subset of `from` — gnhf's no-progress
- * rule (docs/DESIGN.md:229), extended: an attempt that does not strictly
- * shrink the unresolved-criterion set counts as a failure. */
 function strictlyShrunk(from, to) {
     if (to.length >= from.length)
         return false;
     const fromSet = new Set(from);
     return to.every(id => fromSet.has(id));
 }
-/**
- * The chain's happy exit (v40): the instant one of its own attempts
- * reaches `verified` or `attested`, the chain is done. Checked at every
- * completed build's own verdict-save point — not only after a review —
- * since a review can never UPGRADE a verdict past what `adjudicate`
- * already found (foldReview's monotonicity), so only the structural save
- * can ever produce one of these two words.
- */
 export function maybeSettleRepairChain(store, taskId, verdict, now) {
     if (verdict !== "verified" && verdict !== "attested")
         return;
@@ -454,9 +331,6 @@ export function maybeSettleRepairChain(store, taskId, verdict, now) {
         return;
     store.settleRepairChain(chain.id, "resolved", now);
 }
-/** Read the sealed receipt, log and candidate inventory behind a failed gate
- * and say whether the failure is one no repair attempt could fix. An
- * unreadable or truncated inventory leaves the failure repairable. */
 function unrelatedGateFailure(store, evidenceRoot, failure, runId) {
     const receipt = JSON.parse(failure.receipt);
     let changed = null;
@@ -490,15 +364,10 @@ export function regateTask(store, taskId, now, approval) {
         return { ok: false, reason: "accepted-result", message: `${taskId}'s last result already reads ${verdict.verdict}; there is nothing to rerun` };
     if (store.proofAcceptance(last.id) !== null)
         return { ok: false, reason: "accepted-result", message: `${taskId}'s last result was accepted by an operator` };
-    // Rejected: the proof was refuted, or the machine never got a passing
-    // gate (a timed-out check reads "short", not "refuted"). A short verdict
-    // whose gate passed is a result awaiting review, not one to rerun.
     const machinePassed = verdict?.machineVerdict === "verified" || verdict?.machineVerdict === "attested";
     if (verdict === null || !(verdict.verdict === "refuted" || (verdict.verdict === "short" && !machinePassed))) {
         return { ok: false, reason: "not-rejected", message: `${taskId}'s last result is still being assessed; wait for it or stop it` };
     }
-    // A pushed or opened branch is revised through its pull request, never
-    // rerun underneath it; a live claim means an attempt is still running.
     const publication = store.publicationForRun(last.id);
     if (publication !== null && (publication.state === "pushed" || publication.state === "opened"))
         return { ok: false, reason: "published", message: `${taskId}'s last result is published; revise it through its pull request` };
@@ -509,25 +378,17 @@ export function regateTask(store, taskId, now, approval) {
         return { ok: false, reason: "no-attempt", message: `${taskId} has no scope` };
     const head = last.headRevision;
     const actor = approval.kind === "operator" ? approval.name : approval.kind === "release" ? approval.name : `mode ${approval.name}`;
-    // A release task: signed terms or a release check purpose (pipeline-speed.md, P0), each sealed with the approval.
     if (approval.kind === "release" && ((scope.candidate ?? null) === null || !releaseCheckScope(scope))) {
         return { ok: false, reason: "not-approved", message: `${taskId} isn't a release candidate; only a release reruns under its own approval` };
     }
-    // A prepared candidate (a release gate, the nightly check) already names the approved commit, and the builder loads
-    // exactly its tree on every attempt. The rerun keeps that scope and its approval as they are: nothing is proposed or
-    // sealed again, so a regate can never swap the approved commit, its release terms or the person's yes for others
-    // (2026-10-27: a regate rewrote release-0.9.73's candidate to its own build commit and the release refused it).
     if ((scope.candidate ?? null) !== null || releaseCheckScope(scope)) {
         const candidate = scope.candidate ?? null;
         if (candidate === null || scope.approvedDigest !== scope.digest || last.scopeDigest !== scope.digest) {
             return { ok: false, reason: "not-approved", message: `${taskId}'s approved commit or scope changed since attempt #${last.id}, or its approval no longer stands; approve its scope again instead` };
         }
-        // A release's task runs again only while its one approval still stands for it (the dispatch would refuse it anyway).
         const release = liveReleaseOf(store, taskId, "dispatch", now);
         if (release.applies && !release.ok)
             return { ok: false, reason: "not-approved", message: `${taskId} can't run again: ${release.why}` };
-        // Any other seal stands only while its authority does (an expired mode, a revoked approver): the queue would never
-        // dispatch it, so the regate says so instead of queueing a rerun that can't start.
         if (!store.modeApprovalLive(ref.id, now))
             return { ok: false, reason: "not-approved", message: `${taskId}'s approval no longer stands; approve its scope again instead` };
         return store.transact(() => {
@@ -555,8 +416,6 @@ export function regateTask(store, taskId, now, approval) {
             sealed = store.sealScopeApproval(taskId, actor, now, {}, { kind: "mode", modeDigest: approval.modeDigest });
         if (!sealed)
             return { ok: false, reason: "not-approved", message: `${taskId}'s rerun scope could not be approved` };
-        // A finished task returns to the queue; one already queued (a park, a
-        // stop) simply dispatches with the rerun scope on its next turn.
         if (store.getTask(taskId)?.state !== "queued") {
             const queued = store.requeueTask(taskId, actor, now);
             if (!queued.ok) {
@@ -568,29 +427,11 @@ export function regateTask(store, taskId, now, approval) {
         return { ok: true, run: last.id, head };
     });
 }
-/**
- * An explicitly requested repair from saved check or historical review findings.
- * Automatic calls are retired. Composes at
- * most one durable revision draft naming exactly the unmet criterion ids,
- * inheriting the source scope and rubric verbatim — or settles the chain
- * at one of its four independent stops (integrity, no-progress, attempts
- * cap; the fourth — existing spend/run rails — is the ordinary tick's own
- * job once a mode-approved draft dispatches as a normal builder run).
- *
- * Never dispatches anything itself: a mode-authorized draft is
- * auto-APPROVED here, but still builds through the ordinary tick, under
- * the ordinary rails and strikes — this function only ever composes a
- * task and, at most, one scope approval.
- */
 export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdict, now, cause = "review", automatic = false) {
     if (verdict !== "short" && verdict !== "refuted")
         return { kind: "none" };
-    // A review's findings go to the lead, and a person asks for their repair. A failed check is the one automatic road
-    // (check-repair.ts), and only under a mode a person signed for it, checked below.
     if (automatic && cause !== "verification")
         return { kind: "none" };
-    // One attempt per source run, ever (source_run UNIQUE) — checked first so
-    // a re-fired trigger is a silent no-op, never a duplicate.
     if (store.repairChainFor(sourceRunId) !== null)
         return { kind: "none" };
     const run = store.getRun(sourceRunId);
@@ -599,15 +440,8 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
     const stored = store.proofVerdictFor(sourceRunId);
     if (stored === null)
         return { kind: "none" };
-    // THE RERUN STOP (v70): this attempt was a rerun of the same commit — the
-    // scope names that commit as its prepared candidate and the commit has
-    // been attempted before. The machine has had its one retry; whatever
-    // rejected it this time, a failed check or a contradicting review, goes
-    // to a person. No repair draft, no third pass, on either road.
     {
         const rerunTask = store.refById(run.taskRef)?.externalId ?? "";
-        // A prepared candidate's attempts each record their own commit of the candidate's tree, so a rerun under the same
-        // approved scope is the same commit's check even when its head isn't the candidate itself.
         const rerunScope = store.getScope(rerunTask);
         const sameCommit = rerunScope !== null && (rerunScope.candidate === run.headRevision || ((rerunScope.candidate ?? null) !== null && rerunScope.digest === run.scopeDigest));
         if (run.headRevision && sameCommit && store.builderAttemptsAt(run.taskRef, run.headRevision) >= 2) {
@@ -645,8 +479,6 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
     const terms = mode === null ? null : modeTermsFromJson(mode.termsJson);
     let verification;
     if (cause === "verification") {
-        // A signed repair mode is required for this automatic producer. A person
-        // asking (check-repair.ts startCheckRepair) gets an unapproved draft instead.
         if ((automatic && terms?.repairAuto !== true) || run.finishedAt === null || !run.headRevision ||
             (run.outcome !== "built" && run.outcome !== "no-change"))
             return { kind: "none" };
@@ -662,16 +494,9 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
         }
         if (failure.kind !== "failed")
             return { kind: "none" };
-        // A failure the change cannot have caused — the whole gate timing out,
-        // or an untouched test's own timeout — is handed to a person, not to
-        // another code-writing attempt (2026-09-18: mayhem-spire run 1784
-        // drafted a repair for a balance probe the diff never touched).
         const unrelated = unrelatedGateFailure(store, evidenceRoot, failure, sourceRunId);
         if (unrelated !== null) {
             const taskId = store.refById(run.taskRef)?.externalId ?? "";
-            // One automatic rerun of the check on the same commit, under the mode
-            // that already authorizes automatic repair (a rerun is strictly less
-            // than a repair). A second failure on the same commit goes to a person.
             const rerunBefore = run.headRevision ? store.builderAttemptsAt(run.taskRef, run.headRevision) : 0;
             if (mode !== null && terms?.repairAuto === true && run.headRevision && rerunBefore < 2) {
                 const rerun = regateTask(store, taskId, now, { kind: "mode", name: mode.name, modeDigest: mode.digest });
@@ -694,8 +519,6 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
         .filter(row => cause === "review" && direct ? row.review?.judgement === (observation ? "cannot-tell" : "contradicts") : row.state === "missing" || row.state === "failed")
         .map(row => row.id)
         .sort();
-    // The project gate is independent of agent-reported criterion passes.
-    // This ledger target is not a new acceptance criterion or a changed verdict.
     if (verification !== undefined && !unresolved.includes("project checks"))
         unresolved.push("project checks");
     unresolved.sort();
@@ -705,32 +528,21 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
     const ref = brief === null ? null : store.lookupRef(brief.externalId);
     if (ref === null)
         return { kind: "none" };
-    // Never repair: a scout task (a report, not a branch — nothing to build
-    // back into).
     if (ref.deliverable === "report")
         return { kind: "none" };
-    // Never repair: a run already published or holding a merge blocker.
     const publication = store.publicationForRun(sourceRunId);
     if (publication !== null && !(verification !== undefined && publication.state === "intended" && publication.attempts === 0))
         return { kind: "none" };
-    // Never repair: a task with an open decision or a pending steering note.
     if (store.decisionsForTask(ref.id).some(d => d.state === "open" || d.state === "expired"))
         return { kind: "none" };
     if (store.pendingSteerCount(ref.id) > 0)
         return { kind: "none" };
-    // Never repair: a run whose proof was already accepted.
     if (store.proofAcceptance(sourceRunId) !== null)
         return { kind: "none" };
     const task = store.getTask(ref.externalId);
     const scope = store.getScope(ref.externalId);
     if (task === null || scope === null)
         return { kind: "none" };
-    // THE LINEAGE (contract handoff task 2): the chain this task CONTINUES
-    // is found through its revision ancestry, not only its own draft row —
-    // an annotation or CI detour between two repair attempts keeps the
-    // root, the attempts already spent, and the remaining automatic bound.
-    // The next attempt number is one past the chain's highest, whichever
-    // branch spent it; nothing resets because a person annotated a draft.
     const lineage = store.repairLineageOf(ref.externalId);
     if (lineage.problem !== undefined) {
         store.enqueueNotification({ source: { run: sourceRunId }, dedupeKey: `repair-lineage:${sourceRunId}`, kind: "repair-lineage", subject: `${ref.externalId}: repair ancestry needs attention`, body: lineage.problem, link: `/t/${encodeURIComponent(ref.externalId)}` }, now);
@@ -742,23 +554,16 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
     const auto = terms?.repairAuto === true;
     const basis = auto ? "mode" : "human";
     const modeDigest = auto && mode !== null ? mode.digest : null;
-    /** Settle the row this task continues when it is still open; a stop
-     * with no open row to settle records its own settled row instead. */
     const settleOrRecord = (outcome) => {
         if (priorChain !== null && priorChain.outcome === "drafted")
             store.settleRepairChain(priorChain.id, outcome, now);
         else
             store.recordRepairStop({ rootTask, sourceRun: sourceRunId, attempt, basis, modeDigest, unresolved, outcome }, now);
     };
-    // THE INTEGRITY STOP (unconditional, both roads): a refutation that lies
-    // about the signed terms is never handed back to the same machine
-    // unattended — park for a human instead.
     if (isIntegrityRefutation(stored.reasons)) {
         settleOrRecord("integrity-refused");
         return { kind: "stopped", reason: "repair-refused-integrity" };
     }
-    // THE NO-PROGRESS STOP (unconditional, both roads): two consecutive
-    // attempts that fail to strictly shrink the unresolved set.
     if (priorChain !== null) {
         const history = store.repairChainForRoot(rootTask).map(row => [...row.unresolved].sort());
         const sequence = [...history, unresolved];
@@ -772,16 +577,10 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
             }
         }
     }
-    // THE ATTEMPT CAP: bounds only the AUTOMATIC road (a mode's signed
-    // repairMaxAttempts) — the default road's loop is already bounded by
-    // requiring a fresh human "yes" for every attempt.
     if (auto && terms !== null && attempt > terms.repairMaxAttempts) {
         settleOrRecord("attempts-spent");
         return { kind: "stopped", reason: "repair-attempts-spent" };
     }
-    // THE DRAFT: no log content, no new instructions — exactly the unmet
-    // ids, their matrix detail sentences, and the reviewer's own
-    // contradiction notes.
     const contradictions = store.criterionReviewsFor(sourceRunId).filter(one => one.judgement === "contradicts");
     const unresolvedDetail = stored.matrix.filter(row => unresolved.includes(row.id)).map(row => ({ id: row.id, statement: row.statement, detail: row.detail }));
     const draftBrief = {
@@ -800,10 +599,6 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
     };
     const briefBytes = Buffer.from(JSON.stringify(draftBrief, null, 2), "utf8");
     const key = writeEvidenceFile(evidenceRoot, sourceRunId, `repair-brief-${sourceRunId}-${attempt}.json`, briefBytes);
-    // The draft files through the ONE revision boundary: the source's goal,
-    // exclusions, touches, rubric, risk, quality, posture, budget, overrides
-    // and pins are read from the SOURCE ROWS inside the seal — the scope
-    // read above is only the digest this draft binds to, re-proved there.
     const drafted = store.openRepairDraft({
         source: { task: ref.externalId, run: sourceRunId, scopeDigest: scope.digest },
         brief: { evidenceRoot, key, sha256: createHash("sha256").update(briefBytes).digest("hex"), bytes: briefBytes.length, capture: "machine-authored repair brief (exit 0)" },
@@ -822,9 +617,6 @@ export function maybeTriggerRepair(store, repo, evidenceRoot, sourceRunId, verdi
     let approved = false;
     if (auto && mode !== null) {
         const draftScope = store.getScope(drafted.id);
-        // A scope whose profile could not resolve is unapprovable by the human
-        // road; the mode road refuses the same way — the draft stays honestly
-        // unapproved rather than sealing an approval nobody could act on.
         if (draftScope?.profileState === "resolved") {
             approved = store.sealScopeApproval(drafted.id, `mode ${mode.name}`, now, {}, { kind: "mode", modeDigest: mode.digest });
         }