tumwater 0.4.2 → 0.4.4

package/dist/src/run/run-verdict.js

@@ -1,3 +1,4 @@
+import { imageReroute } from "../agent/image-input.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { baseRoleOf } from "../roles/runner-ids.js";
 import { isDirty, deleteRef } from "../git/git.js";
@@ -9,6 +10,7 @@ import { errorMessage } from "../text/text.js";
 import { recordParity } from "./ci-parity.js";
 import { resetWorktreeToMain } from "../git/worktree.js";
 import { recordDismissedFiling, recordDismissedFlow } from "./run-dismiss.js";
+import { readPiListedModels } from "../pi/pi-listed-models.js";
 import { rejectedRefName } from "../paths.js";
 import { logEventBestEffort } from "../events/events.js";
 import { subscriptionWindowRejected } from "../agent/claude/claude-account.js";
@@ -23,6 +25,17 @@ function abortWithResume(s, ctx, pi, lastError, result, resumeCause) {
     ctx.pending.requeueForResume(s, ctx.userPrompt);
     return { result, resumeCause };
 }
+/** End a run as an unfulfilled error: record `lastError`, re-queue the raw prompt for a later
+ * fresh run (requeueUnfulfilled) and return the error outcome — the terminal the timeout and
+ * image-blind arms share, filed here so the "record lastError, re-queue unfulfilled, end as
+ * error" contract cannot drift between them (the resume-arming twin is abortWithResume above;
+ * failedRunArm's error path keeps its own split because it arms a resume for a dirty worktree
+ * and sets lastError before that choice). */
+function unfulfilledError(s, ctx, message) {
+    s.lastError = message;
+    ctx.pending.requeueUnfulfilled(ctx.userPrompt);
+    return { result: "error" };
+}
 /** Classify what the finished run left behind; null means the run is fulfillable and staging
  * should take over. Never throws: every branch returns an outcome, recording what went wrong
  * in `state.lastError` or a warning event. */
@@ -134,11 +147,9 @@ function progressingTimeoutArm(ctx) {
 function timeoutArm(ctx) {
     const { pi, state: s } = ctx;
     if (pi.timedOut) {
-        s.lastError = pi.errorMessage ?? "timed out";
         // The request never ran to completion and no work merged: put it back so the next
         // run retries it. (A killed run's half-done edits are discarded by the reset.)
-        ctx.pending.requeueUnfulfilled(ctx.userPrompt);
-        return { result: "error" };
+        return unfulfilledError(s, ctx, pi.errorMessage ?? "timed out");
     }
     return undefined;
 }
@@ -178,22 +189,73 @@ function budgetCappedArm(ctx) {
     }
     return undefined;
 }
+/** The failure message a run that ended on a blind read names when the agent gave none of its
+ * own: the image path the model could not see, unless the kill carried a more specific reason
+ * (pi.errorMessage). Shared by the two failing arms of imageBlindArm below — the one-hop-already
+ * branch and the no-reroute-target branch — so the "could not read the image" wording cannot
+ * drift between them. The reroute arm does NOT use it: its own lastError names the target's
+ * tier too. */
+function blindReadFailureMessage(pi, path) {
+    return pi.errorMessage ?? `read ${path}, but the model cannot read images`;
+}
 /** The image-blind decision: a run stopped the moment its agent read an image its model cannot
- * see fails with `lastError` and the prompt re-queues. The peer-tier reroute was subtracted
- * (part 5g/6), so a blind read is never handed to another tier (plans/image-input.md "Failing
- * the run"). */
+ * see. One hop to an image-capable reroute target is taken when one exists; otherwise the
+ * run fails and the prompt re-queues (plans/image-input.md "Failing the run"). */
 function imageBlindArm(ctx) {
     const { pi, state: s } = ctx;
     // A run the runner killed the moment its agent read an image its model cannot see
     // (plans/image-input.md "Failing the run"): pi strips such an image from the request, so
     // the agent was about to answer about a picture it never saw. The run was deliberately
     // stopped before it could work on, so its half-done edits are discarded exactly as a
-    // timed-out run's are — nothing to resume, and the prompt re-queues to run fresh later.
-    // The error backoff and streak apply as for any error.
+    // timed-out run's are — nothing to resume, and the prompt re-queues to run fresh on a
+    // model that CAN see, with one reroute hop to an image-capable target (the arm below). The
+    // error backoff and streak apply as for any error.
     if (pi.imageBlind) {
-        s.lastError = pi.errorMessage ?? `read ${pi.imageBlind.path}, but the model cannot read images`;
-        ctx.pending.requeueUnfulfilled(ctx.userPrompt);
-        return { result: "error" };
+        // One hop only (plans/image-input.md "Rerunning on a model that can read images"): a
+        // run that ALREADY started on the image-capable target and still read blind is not
+        // rerouted a second time — it fails, so a misreadable image cannot bounce the role
+        // between tiers forever. Set at run start by runPhase when it routes a run onto the
+        // target (blind-read handoff or attachment preflight).
+        if (s.imageRerouteActive) {
+            // No work was done (the run was killed at the first read): nothing to resume, and the
+            // prompt re-queues to run fresh later like any other error. The error backoff/streak
+            // apply as usual.
+            return unfulfilledError(s, ctx, blindReadFailureMessage(pi, pi.imageBlind.path));
+        }
+        // Otherwise, when the role's tier has an image-capable reroute target, the failed work
+        // is not discarded: the next run starts directly on that target over the kept worktree.
+        // The one-shot field carries the target seam plus the `from`/`path` facts the handoff
+        // note needs; the run ends `aborted` with the `image-reroute` resume cause, and
+        // applyRunOutcome schedules it promptly (nextRunAt = now) while planRunStart hands the
+        // kept worktree off to a FRESH session on the target.
+        const regime = ctx.rerouteRegime ?? "primary";
+        const target = ctx.config !== undefined ? imageReroute(ctx.config, ctx.role, regime, undefined, null, null, readPiListedModels(ctx.root))
+            : null;
+        if (target) {
+            const from = ctx.runModel ?? target.config.model ?? "the model";
+            s.imageReroute = {
+                tier: target.tier,
+                backend: target.config.agent ?? "pi",
+                provider: target.config.provider,
+                model: target.config.model,
+                thinking: target.config.thinking,
+                from,
+                path: pi.imageBlind.path,
+            };
+            s.lastError = `read ${pi.imageBlind.path}, but ${from} cannot read images — rerouting to ${target.tier}`;
+            ctx.pending.requeueForResume(s, ctx.userPrompt);
+            logEventBestEffort(ctx.root, {
+                source: ctx.role,
+                type: "image_reroute",
+                run: s.runs,
+                from,
+                to: target.config.model,
+                tier: target.tier,
+                preflight: false,
+            });
+            return { result: "aborted", resumeCause: "image-reroute" };
+        }
+        return unfulfilledError(s, ctx, blindReadFailureMessage(pi, pi.imageBlind.path));
     }
     return undefined;
 }
@@ -300,51 +362,67 @@ function noChangeArm(ctx, changed) {
         // diagnoseNoChange (src/verdict/no-change.ts) tells which, so the warning event below is
         // diagnosable on its own.
         const diagnosis = diagnoseNoChange(pi);
-        if (!pi.nothingToDo) {
-            ctx.warn(`the agent finished without changes and without declaring nothing-to-do` +
-                (diagnosis.notes.length ? ` (${diagnosis.notes.join(", ")})` : ""));
-        }
+        warnUndeclaredNoChange(ctx, pi, diagnosis.notes);
         // A cut-off run did real work and was NOT fulfilled: a director prompt goes back
         // to the inbox to rerun fresh; a role runner resumes the just-compacted session
         // next run (see the cutOff handling in run()).
         if (diagnosis.cutOff)
             ctx.pending.requeueForResume(s, ctx.userPrompt);
-        // A cut-off run did real work but was truncated before declaring its outcome: the FLOW
-        // line it left mid-stream is not a finished verdict, so recording it would advance the
-        // rotation past a check that did not complete. Only a run that was not cut off records.
-        if (ctx.flow && !diagnosis.cutOff) {
-            // The ledger only orders the qa menu, so a failed write warns rather than failing the run.
-            recordDismissedFlow(ctx, ctx.root, ctx.flow.flow, ctx.flow.result, ctx.flow.result === "bug" ? extractSummary(pi.finalText) ?? undefined : undefined);
-        }
-        // A fulfilled feedback run that filed records its per-install ledger entry and logs the
-        // issue_filed event so the filing is visible in the operator's activity feed. Recording is
-        // bookkeeping that never fails the run: a failed ledger write warns and the no_change
-        // outcome stands. A cut-off run records nothing — truncation is not a filing the run
-        // declared (the same guard the FLOW line carries).
-        if (ctx.filed && !diagnosis.cutOff) {
-            recordDismissedFiling(ctx, ctx.root, ctx.filed);
+        recordNoChangeBookkeeping(ctx, pi, diagnosis.cutOff);
+        return {
+            result: "no_change",
+            cutOff: diagnosis.cutOff || undefined,
+            summary: noChangeSummary(ctx, pi, diagnosis.cutOff),
+        };
+    }
+    return undefined;
+}
+/** Warn when a no-change run declared neither a sentinel nor nothing-to-do, so the non-
+ * compliance or truncation the diagnosis saw is diagnosable on its own. */
+function warnUndeclaredNoChange(ctx, pi, notes) {
+    if (!pi.nothingToDo) {
+        ctx.warn(`the agent finished without changes and without declaring nothing-to-do` +
+            (notes.length ? ` (${notes.join(", ")})` : ""));
+    }
+}
+/** A no-change run's bookkeeping: the qa flow, the filed feedback ledger entry and the ci
+ * parity coverage, each recorded only when its observer saw it and the run was not cut off. */
+function recordNoChangeBookkeeping(ctx, pi, cutOff) {
+    // A cut-off run did real work but was truncated before declaring its outcome: the FLOW
+    // line it left mid-stream is not a finished verdict, so recording it would advance the
+    // rotation past a check that did not complete. Only a run that was not cut off records.
+    if (ctx.flow && !cutOff) {
+        // The ledger only orders the qa menu, so a failed write warns rather than failing the run.
+        recordDismissedFlow(ctx, ctx.root, ctx.flow.flow, ctx.flow.result, ctx.flow.result === "bug" ? extractSummary(pi.finalText) ?? undefined : undefined);
+    }
+    // A fulfilled feedback run that filed records its per-install ledger entry and logs the
+    // issue_filed event so the filing is visible in the operator's activity feed. Recording is
+    // bookkeeping that never fails the run: a failed ledger write warns and the no_change
+    // outcome stands. A cut-off run records nothing — truncation is not a filing the run
+    // declared (the same guard the FLOW line carries).
+    if (ctx.filed && !cutOff) {
+        recordDismissedFiling(ctx, ctx.root, ctx.filed);
+    }
+    // A fulfilled ci run that declared its coverage records it in the parity ledger so the
+    // next fresh session's block knows what the last run covered (part 3/3). The ledger is
+    // bookkeeping that never fails the run: a failed write warns and the no_change outcome
+    // stands. A cut-off run records nothing — truncation is not a coverage the run declared.
+    if (ctx.ci && !cutOff) {
+        try {
+            recordParity(ctx.root, ctx.ci.sha, ctx.ci.result);
         }
-        // A fulfilled ci run that declared its coverage records it in the parity ledger so the
-        // next fresh session's block knows what the last run covered (part 3/3). The ledger is
-        // bookkeeping that never fails the run: a failed write warns and the no_change outcome
-        // stands. A cut-off run records nothing — truncation is not a coverage the run declared.
-        if (ctx.ci && !diagnosis.cutOff) {
-            try {
-                recordParity(ctx.root, ctx.ci.sha, ctx.ci.result);
-            }
-            catch (err) {
-                ctx.warn(`ci parity not recorded: ${errorMessage(err)}`);
-            }
+        catch (err) {
+            ctx.warn(`ci parity not recorded: ${errorMessage(err)}`);
         }
-        // A prompt-driven (director) run that answers a question in prose ends `no_change` with
-        // no SUMMARY block, so its reply would be lost — the dashboard reads a bare "No change"
-        // and the feed carries nothing (BUGS.md 2026-10-14). Keep the prose above the sentinel as
-        // the run's summary so `lastSummary` and the run_end event show the answer where the
-        // operator asked the question. A role runner's bare nothing-to-do stays summary-less.
-        const summary = ctx.userPrompt !== null && !diagnosis.cutOff
-            ? (extractNoChangeAnswer(pi.finalText) ?? undefined)
-            : undefined;
-        return { result: "no_change", cutOff: diagnosis.cutOff || undefined, summary };
     }
-    return undefined;
+}
+/** A prompt-driven (director) run that answers a question in prose ends `no_change` with
+ * no SUMMARY block, so its reply would be lost — the dashboard reads a bare "No change"
+ * and the feed carries nothing (BUGS.md 2026-10-14). Keep the prose above the sentinel as
+ * the run's summary so `lastSummary` and the run_end event show the answer where the
+ * operator asked the question. A role runner's bare nothing-to-do stays summary-less. */
+function noChangeSummary(ctx, pi, cutOff) {
+    return ctx.userPrompt !== null && !cutOff
+        ? (extractNoChangeAnswer(pi.finalText) ?? undefined)
+        : undefined;
 }

package/dist/src/run/stage-check.js

@@ -1,15 +1,14 @@
-/** The merge gate's deterministic checks, run BEFORE a changed run commits.
+/** The merge gate's checks that still refuse a change, plus staging-only heuristics for what a
+ * reviewer tends to reject, run BEFORE a changed run commits.
  *
- * The gate runs `backlogStructureReason` and `falseFixReason` at merge time, by which point
- * the author's session is over: a finding costs a queue slot, a verification, and a rejection that
- * discards the work (13 phantom-fix rejections between 2026-09-23 and 2026-10-02). Both checks
- * read the worktree and the change's merge-base, so the same questions can be asked at staging
- * time, while the authoring session can still be continued for one fix-up turn. This module
- * runs them over the run's uncommitted edits; the gate still has the final say.
- *
- * Scope mirrors the gate exactly: `backlogStructureReason` runs on every changed run, while
- * `falseFixReason` runs only for an exempt (doc-only) diff — the condition under which the gate
- * consults it.
+ * Since part 3m/3 the gate refuses only a brief-block edit, a protected edit and a leaked
+ * credential — the findings a later commit cannot repair. This module runs those same checks
+ * over the run's uncommitted edits while the authoring session can still be continued for one
+ * fix-up turn (a finding that reaches merge costs a queue slot, a verification, and a rejection
+ * that discards the work — 13 phantom-fix rejections between 2026-09-23 and 2026-10-02 priced
+ * that turn). The gate no longer refuses a false fix claim or a broken backlog structure —
+ * both are repairable by a later commit and reported by the main watch on main's tip — so
+ * those findings never spend the run's fix-up turn here.
  *
  * The git-level checks described next live across stage-path-checks.ts (`gitLevelFindings`),
  * stage-name-checks.ts and stage-prose-checks.ts, which this module appends.
@@ -20,8 +19,9 @@
  * files whose final newline the change removed. These stage the change (`git add -A`) to read
  * the index with git only, then restore the index to HEAD before returning: staging is a read
  * aid for the checks, not a change to the run's state. A git hiccup yields no finding rather
- * than failing the run. Unlike the backlog checks above, the gate does not run these: they are
- * heuristics for what a reviewer tends to reject, so neither path check looks inside record
+ * than failing the run. Unlike the gate's checks this module runs (which the gate also runs at
+ * merge time), the gate does not run these: they are heuristics for what a reviewer tends to
+ * reject, so neither path check looks inside record
  * prose (isRecordProse), where an old or not-yet-created path is correct as written.
  *
  * A fourth check, `staleNameFindings`, reports a compound identifier the change removed from a
@@ -59,11 +59,8 @@
 import path from "node:path";
 import { changedFiles } from "../git/git-diff.js";
 import { conflictMarkerReason } from "../merge/merge-git.js";
-import { isExemptDiff } from "../review/exemptions.js";
-import { backlogStructureReason } from "../backlog/backlog-structure.js";
 import { protectedEditReason } from "../review/protected-edits.js";
 import { secretLeakReason } from "../review/secret-leaks.js";
-import { falseFixReason } from "../verdict/fix-claim.js";
 import { changeBaseRev, fileContentAt } from "../git/git.js";
 import { readTextOrNull } from "../files/files.js";
 import { FINISHED_ARCHIVES, finishedArchiveOf, parseEntryDetails, } from "../backlog/backlog-md.js";
@@ -93,35 +90,24 @@ const pushReason = async (findings, check) => {
     if (reason)
         findings.push(reason);
 };
-/** The findings likely to get this uncommitted change rejected at merge, or an empty list when
- * it is clean: the merge gate's own deterministic checks plus the staging-only heuristics (plan
- * dependencies, path drift). Checks the worktree at `wt` against
- * `mainBranch`'s merge-base; `exemptPaths` are the config's review-exemption globs that scope
- * the false-fix check.
- *
- * Never throws: a check that fails yields no finding, so a git hiccup at staging time defers to
- * the gate instead of failing the run. */
-export async function stageCheckFindings(wt, mainBranch, exemptPaths, role) {
-    const files = await changedFiles(wt).catch(() => null);
-    if (files === null || files.length === 0)
-        return [];
-    const findings = [];
-    await pushReason(findings, backlogStructureReason(wt, mainBranch, files));
-    if (files.includes("PLANS.md")) {
-        const { head, base } = await headAndBase(wt, mainBranch, "PLANS.md");
-        // Finished plans are archived in PLANS-DONE.md (plans/backlog-archive.md): a requires clause
-        // naming a merged part resolves there, on both sides of the comparison alike.
-        const archived = parseEntryDetails(readTextOrNull(path.join(wt, PLANS_ARCHIVE)) ?? "", "Done").map((e) => e.title);
-        const dependency = base === undefined ? undefined : planDependencyFinding(head, base, archived);
-        if (dependency !== undefined)
-            findings.push(dependency);
-        const refusal = base === undefined ? undefined : ungroundedRefusalFinding("PLANS.md", head, base);
-        if (refusal !== undefined)
-            findings.push(refusal);
-    }
+/** The PLANS.md record findings: a requires clause naming a part the archive lacks, and an
+ * ungrounded refusal that cites another part. */
+async function plansFindings(wt, mainBranch) {
+    const { head, base } = await headAndBase(wt, mainBranch, "PLANS.md");
+    // Finished plans are archived in PLANS-DONE.md (plans/backlog-archive.md): a requires clause
+    // naming a merged part resolves there, on both sides of the comparison alike.
+    const archived = parseEntryDetails(readTextOrNull(path.join(wt, PLANS_ARCHIVE)) ?? "", "Done").map((e) => e.title);
+    const dependency = base === undefined ? undefined : planDependencyFinding(head, base, archived);
+    const refusal = base === undefined ? undefined : ungroundedRefusalFinding("PLANS.md", head, base);
+    return [dependency, refusal].filter((f) => f !== undefined);
+}
+/** The finished-archive findings: duplicates of entries the archive already holds, plus the
+ * acceptance greps of the plan entries the change finished (for a PLANS.md change). */
+async function archiveFindings(wt, mainBranch, files) {
     const baseRev = FINISHED_ARCHIVES.some((s) => files.includes(s.file) || files.includes(s.archive))
         ? await changeBaseRev(wt, mainBranch).catch(() => undefined)
         : undefined;
+    const findings = [];
     for (const spec of FINISHED_ARCHIVES) {
         if (baseRev === undefined || !(files.includes(spec.file) || files.includes(spec.archive)))
             continue;
@@ -144,12 +130,18 @@ export async function stageCheckFindings(wt, mainBranch, exemptPaths, role) {
         })().catch(() => []);
         findings.push(...greps);
     }
-    if (files.includes("BUGS.md")) {
-        const { head, base } = await headAndBase(wt, mainBranch, "BUGS.md");
-        const refusal = base === undefined ? undefined : ungroundedRefusalFinding("BUGS.md", head, base);
-        if (refusal !== undefined)
-            findings.push(refusal);
-    }
+    return findings;
+}
+/** The BUGS.md record finding: an ungrounded refusal that cites another bug. */
+async function bugsFindings(wt, mainBranch) {
+    const { head, base } = await headAndBase(wt, mainBranch, "BUGS.md");
+    const refusal = base === undefined ? undefined : ungroundedRefusalFinding("BUGS.md", head, base);
+    return refusal === undefined ? [] : [refusal];
+}
+/** The stray-placeholder findings: a `_None yet._` line a changed record still leaves in a
+ * section that holds entries. */
+async function placeholderFindings(wt, mainBranch, files) {
+    const findings = [];
     for (const file of PLACEHOLDER_FILES) {
         if (!files.includes(file))
             continue;
@@ -158,10 +150,28 @@ export async function stageCheckFindings(wt, mainBranch, exemptPaths, role) {
         if (stray !== undefined)
             findings.push(stray);
     }
+    return findings;
+}
+/** The findings likely to get this uncommitted change rejected at merge, or an empty list when
+ * it is clean: the merge gate's remaining checks over the change plus the staging-only
+ * heuristics (plan dependencies, path drift). Checks the worktree at `wt` against
+ * `mainBranch`'s merge-base.
+ *
+ * Never throws: a check that fails yields no finding, so a git hiccup at staging time defers to
+ * the gate instead of failing the run. */
+export async function stageCheckFindings(wt, mainBranch, role) {
+    const files = await changedFiles(wt).catch(() => null);
+    if (files === null || files.length === 0)
+        return [];
+    const findings = [];
+    if (files.includes("PLANS.md"))
+        findings.push(...(await plansFindings(wt, mainBranch)));
+    findings.push(...(await archiveFindings(wt, mainBranch, files)));
+    if (files.includes("BUGS.md"))
+        findings.push(...(await bugsFindings(wt, mainBranch)));
+    findings.push(...(await placeholderFindings(wt, mainBranch, files)));
     await pushReason(findings, protectedEditReason(wt, mainBranch, files, role));
     await pushReason(findings, secretLeakReason(wt, mainBranch, files));
-    if (isExemptDiff(files, exemptPaths))
-        await pushReason(findings, falseFixReason(wt, mainBranch, files));
     findings.push(...(await gitLevelFindings(wt, mainBranch).catch(() => [])));
     const markers = conflictMarkerReason(wt, files);
     if (markers !== undefined)

package/dist/src/run/stage-checks-shared.js

@@ -16,6 +16,34 @@ export const MAX_STALE_PATHS = 10;
 export function diffPlusPath(line) {
     return line.slice(4).replace(/^b\//, "");
 }
+/** Parse a `-U0` unified diff into each file's removed and added content lines, marker-stripped.
+ * The `diff --git` header names the file, and git's `---`/`+++` old/new path headers carry no
+ * content; `@@` hunk headers, context lines and the `\ No newline` marker match neither branch,
+ * so the walk records only real `-`/`+` content lines. Consumers keep only what they want — a
+ * JS-file filter, a trim-and-min-length rule, a compound-name extraction — from the per-file
+ * removed/added lists; stage-path-checks's movedSourceFindings and stage-name-checks's
+ * declaredNameDeltas each walked this same grammar before the helper. stage-prose-checks's
+ * detachedDocFindings and addedDiffLines are deliberately not folded here: both need each hunk's
+ * start-line count from the `@@` header, which this shape drops. */
+export function diffRemovedAdded(diff) {
+    const files = [];
+    let cur;
+    for (const line of diff.split("\n")) {
+        const header = /^diff --git a\/.* b\/(.*)$/.exec(line);
+        if (header) {
+            cur = { path: header[1], removed: [], added: [] };
+            files.push(cur);
+            continue;
+        }
+        if (!cur)
+            continue;
+        if (line.startsWith("-") && !line.startsWith("---"))
+            cur.removed.push(line.slice(1));
+        else if (line.startsWith("+") && !line.startsWith("+++"))
+            cur.added.push(line.slice(1));
+    }
+    return files;
+}
 /** Parse `git grep -n` stage output into `file:line:text` hits. `git grep -n` prints one
  * `path:line:text` per match, and the four name/path checks (stage-name-checks.ts's
  * staleNameFindings and movedNameFindings, stage-path-checks.ts's movedSourceFindings and