tumwater 0.4.2 → 0.4.4

package/dist/src/review/review.js

@@ -1,18 +1,15 @@
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
-import { changeBaseRev, headOf, patchId } from "../git/git.js";
+import { changeBaseRev, headOf } from "../git/git.js";
 import { aheadOfMainFiles } from "../git/git-diff.js";
 import { resetWorktreeToMain } from "../git/worktree.js";
 import { recordReview } from "../run/run-apply.js";
-import { reviewedAfterMerge } from "../config/config-views.js";
-import { errorMessage, parseNonNegativeInt } from "../text/text.js";
+import { sleepInterruptible } from "../run/run-timing.js";
+import { parseNonNegativeInt } from "../text/text.js";
 import { firstReason } from "../text/phrases.js";
 import { isExemptDiff } from "./exemptions.js";
-import { idleWithoutProviderLease } from "../concurrency/provider-lease.js";
-import { setMergeStage } from "../merge/merge-slot.js";
+import { idleWithoutPermit } from "../concurrency/run-permit.js";
 import { gateBuildPrecheck } from "./review-precheck.js";
 import { diffRuleReasons } from "./diff-rules.js";
-export { REVIEW_FAILURE_LIMIT } from "./review-run.js";
-import { restoreReviewedHead, runReviewer, withRuns } from "./review-run.js";
 /** In-place retries of a failed reviewer run within one verify, after the first run. */
 const REVIEW_RETRIES = 2;
 /** The pause before each retry (ReviewContext.retryDelayMs overrides it in tests). */
@@ -23,92 +20,40 @@ const REVIEW_RETRY_DELAY_ENV = "TUMWATER_REVIEW_RETRY_DELAY_MS";
 /** The pause before each retry: the context override wins; else the tunable env knob read through
  * the shared plain-decimal rule (parseNonNegativeInt — a 0 ms delay, the test-suite's setting, is
  * valid). A malformed spelling falls back to REVIEW_RETRY_DELAY_MS rather than silently becoming
- * NaN: `sleepUnlessAborted(NaN)` resolves at ~0 ms and the retries would fire back-to-back instead
+ * NaN: `sleepInterruptible(NaN)` resolves at ~0 ms and the retries would fire back-to-back instead
  * of 30 s apart. */
 export function reviewRetryDelayMs(ctxRetryDelayMs) {
     const raw = process.env[REVIEW_RETRY_DELAY_ENV];
     return ctxRetryDelayMs ?? (raw === undefined ? REVIEW_RETRY_DELAY_MS : (parseNonNegativeInt(raw) ?? REVIEW_RETRY_DELAY_MS));
 }
-/** A second pool slot for the gate check, or null when the context cannot lease one, none is free
- * right now, or the lease failed (the check then runs first, in the change's own slot). */
-async function leaseCheckSlot(ctx, head) {
-    if (!ctx.leaseCheckSlot)
-        return null;
-    try {
-        return await ctx.leaseCheckSlot(head);
-    }
-    catch (err) {
-        warnEventBestEffort(ctx.root, ctx.role, `no second workspace for the gate check (${errorMessage(err)}); running it before the review`);
-        return null;
-    }
-}
-/** Start the gate check in `lease`'s checkout of `head`. A rejection is recorded, not applied:
- * resetting the change's branch is left to reviewAttempt, after the reviewer has stopped. */
-function startOverlappedCheck(ctx, state, head, lease) {
-    const overlap = { abort: new AbortController(), done: false };
-    const reject = async (reasons) => {
-        overlap.rejectedReasons = reasons;
-        return { decision: "rejected", detail: firstReason(reasons) };
-    };
-    overlap.gate = gateBuildPrecheck({ ...ctx, wt: lease.dir }, state, head, reject)
-        .then((pre) => {
-        overlap.done = true;
-        if (pre.resolved)
-            overlap.abort.abort();
-        else
-            setMergeStage(ctx.root, ctx.role, "reviewing");
-        return pre;
-    }, (err) => {
-        overlap.done = true;
-        overlap.abort.abort();
-        throw err;
-    })
-        .finally(() => lease.release());
-    overlap.gate.catch(() => { }); // surfaced where reviewAttempt awaits it
-    return overlap;
-}
-/** Run the adversarial review gate over everything ahead of main in `wt` and update `state`
+/** Run the deterministic review gate over everything ahead of main in `wt` and update `state`
  * accordingly. Shared by the run path (after commitAll) and leftover recovery
- * (leftover.ts's recoverLeftover) — every path
+ * (runner-leftover.ts's recoverLeftover) — every path
  * that can move a commit into main routes through here, so no crash or abort path smuggles
  * unreviewed work in:
  * - gate disabled, or an already-approved HEAD, or an exempt (doc-only) diff → merge as-is;
- * - a new HEAD carrying an approved patch (approvedPatchIds) → approved after the
- *   build pre-check, with no reviewer run;
- * - approve → record lastApprovedHead and its patch-id, and discard the reviewer's stray
- *   working-tree edits (its only output channel is the verdict);
+ * - approve → a passing build pre-check records lastApprovedHead and approves, with no
+ *   reviewer run; every merged change is judged once, after it lands, by the post-landing
+ *   review (part 3g/3, reviewMergedCommit, run by the merge pipeline's post-review drain);
  * - reject → reset the branch to main, record reasons in state.lastReview (injected into the
  *   role's next run prompt), log review_rejected;
- * - fail with an unparseable reply (the reviewer ran to completion but emitted no VERDICT) →
- *   one capped follow-up turn on the reviewer's own session asks for the missing line
- *   (mirroring requestSummary — BUGS.md 2026-09-29); only a follow-up that also yields
- *   nothing counts the strike. Leave the commit on the branch for the next run's re-review,
- *   counting consecutive failures per HEAD; past REVIEW_FAILURE_LIMIT discard the leftover
- *   with a warning.
- * - fail because the run itself failed (transport/spawn/timeout, pi.ok false) → leave the
- *   commit and do NOT advance the count: the reviewer never judged the diff, so the failure
- *   is evidence about the backend, never about the commit (BUGS.md 2026-09-20).
  * - the declared check fails, and fails again on its one re-run → reject with the check's
- *   reasons, no pi run, when main's own tip is green (or has no verdict); when main is red too,
- *   fail without advancing the count and leave the commit — the failure is main's. Never throws.
+ *   reasons when main's own tip is green (or has no verdict); when main is red too, fail
+ *   without advancing the count and leave the commit — the failure is main's. Never throws.
  * `highFriction` marks a change whose authoring run burned more than the configured turn/time
- * thresholds (plans/refusal-and-thrash.md): the flag rides along in the review prompt so the
- * reviewer applies extra scrutiny to whether the work should exist at all. */
-async function reviewAttempt(ctx, state, summary, commitBody, highFriction, retry) {
+ * thresholds (plans/refusal-and-thrash.md): kept for the caller's convenience. */
+async function reviewAttempt(ctx, state, _summary, _commitBody, _highFriction, retry) {
     const { root, role, wt, mainBranch, config } = ctx;
     if (!config.review.enabled) {
-        state.reviewResume = undefined;
         return { decision: "exempt" };
     }
     const head = await headOf(wt, "HEAD");
-    // The one reject path: every rejection of this HEAD — deterministic build-check failure or
-    // model verdict — shares this bookkeeping. Record lastReview (injected into the role's next
+    // The one reject path: every rejection of this HEAD — the deterministic build-check
+    // outcome — shares this bookkeeping. Record lastReview (injected into the role's next
     // run prompt), reset the failure count (a verdict about this HEAD is a successful review
     // either way), discard the branch by resetting it to main, and log review_rejected.
-    // Callers attach `run` when a pi run was consumed.
     const reject = async (reasons, durationMs) => {
         recordReview(state, "reject", reasons, head);
-        state.reviewResume = undefined;
         state.unreviewFailures = 0;
         await resetWorktreeToMain(wt, mainBranch);
         logEventBestEffort(root, {
@@ -120,111 +65,57 @@ async function reviewAttempt(ctx, state, summary, commitBody, highFriction, retr
         });
         return { decision: "rejected", detail: firstReason(reasons) };
     };
-    // Every exit below that keeps the change leaves the worktree at the head this gate reviewed.
-    const keep = async (r) => {
-        await restoreReviewedHead(wt, head, root, role);
-        return r;
-    };
-    // Settle the attempt on an overlapped check that did not pass: the sequential pre-check's own
-    // outcome, with the reviewer's run (when one started) dropped and no verdict recorded. A
-    // rejection is applied now, after the reviewer stopped touching the tree; every other outcome
-    // keeps the change at the head the gate reviewed.
-    const settleFailedCheck = async (o, pre, pi) => {
-        state.reviewResume = undefined;
-        const settled = o.rejectedReasons
-            ? await reject(o.rejectedReasons)
-            : await keep(pre.resolved ?? { decision: "failed", detail: "the gate check did not complete" });
-        return pi ? withRuns(settled, pi, null, null) : settled;
-    };
     // Already reviewed this exact HEAD (e.g. a merge_blocked retry): do not burn another run.
     if (state.lastApprovedHead === head) {
-        state.reviewResume = undefined;
         return { decision: "approved" };
     }
     const files = await aheadOfMainFiles(wt, mainBranch);
-    // The five deterministic diff rules (conflict markers, protected edits, secret leaks, a false
-    // fix claim on an exempt md-only diff, and backlog structure) are judged by diffRuleReasons in
-    // the gate's own order and scope — the one call site the gate and the main watch share (the
-    // watch runs them on main's tip, "Every commit is verified on main, part 1/3"). A rejection is
-    // a hard stop and deterministic, like the pre-check below: no pi run consumed, reasons
-    // injected into the author's next run. A conflict marker must not merge raw `<<<<<<<` lines
-    // (PLANS.md "Robust conflict landing, part 2/2"), and an md-only diff skips the reviewer, so
-    // each rule below is what catches a change the reviewer would never see: an edit to the brief
-    // prompt block or PRINCIPLES.md (protectedEditReason), a leaked credential
-    // (secretLeakReason), an md-only fix claim with no backing code (falseFixReason, BUGS.md
-    // 2026-09-22), and a duplicated or dropped `## ` section heading (backlogStructureReason,
-    // PLANS.md 2026-09-25).
+    // The three deterministic diff rules the gate rejects on (a brief-block edit, a protected
+    // edit and a secret leak) are judged by diffRuleReasons in the "gate" scope — the same rules
+    // the main watch runs on main's tip, but a narrower set: a conflict marker, a false fix claim
+    // on an exempt md-only diff, and a broken backlog structure are all repairable by a later
+    // commit, so they stop refusing a diff pre-merge and the watch reports them on main's tip
+    // instead ("Every commit is verified on main, part 3m/3"). A rejection is a hard stop and
+    // deterministic, like the pre-check below: no pi run consumed, reasons injected into the
+    // author's next run. A brief edit or a leaked credential must not merge raw (PLANS.md
+    // "Robust conflict landing, part 2/2"), and an md-only diff skips the reviewer, so each rule
+    // below is what catches a change the reviewer would never see: an edit to the brief prompt
+    // block or PRINCIPLES.md (protectedEditReason), and a leaked credential (secretLeakReason).
     const baseRev = await changeBaseRev(wt, mainBranch);
     const exempt = isExemptDiff(files, config.review.exemptPaths);
-    const [firstFinding] = await diffRuleReasons(wt, baseRev, files, role, exempt);
+    const [firstFinding] = await diffRuleReasons(wt, baseRev, files, role, exempt, "gate");
     if (firstFinding !== undefined)
         return reject([firstFinding]);
     if (exempt) {
-        state.reviewResume = undefined;
         return { decision: "exempt" };
     }
     // Deterministic build pre-check — after BOTH early returns above (an md-only diff cannot
-    // break the build) and before any reviewer run or the phase/event that would show
-    // "reviewing": a deterministic rejection never shows as reviewing on the dashboards. Both
-    // gate callers (the run path and leftover.ts's recoverLeftover) get it for free. Its run,
-    // flake re-run, and attribution live in review-precheck.ts (the check run itself lives in
-    // runScopedBuildCheck, shared with the merge path's in-lock re-check); a resolved result
-    // here is returned verbatim and a pass hands the verified head to the merge path below.
-    // The pre-check sets the merge cell's stage (a no-op outside a queued merge) —
-    // "build-check" while it runs, "reviewing" when the reviewer run starts below.
-    // A retried attempt keeps the first attempt's passing pre-check (a green, or a red naming
-    // only main's known failures): the tree is the same head.
-    // A review judges a diff, not a sha: a head carrying exactly the patch this role's last
-    // approval judged (the approved head cleanly rebased onto a moved main) reuses that verdict
-    // instead of paying a second reviewer run. Only the model review is reused — the pre-check
-    // has just run on this tree (a failure rejected it there), and its verifiedHead rides on the
-    // result as for any approval.
-    const reviewedPatchId = (await patchId(wt, mainBranch, head)) ?? undefined;
-    const patchApproved = reviewedPatchId !== undefined && state.approvedPatchIds?.includes(reviewedPatchId) === true;
-    // The check runs alongside the reviewer when a second pool slot is free right now (Fast merge
-    // part 12): it starts here, in its own checkout of this head, while the reviewer run below
-    // starts in the change's own slot. An already-approved patch has no reviewer to overlap, and
-    // with no free slot (or no way to lease one) the check runs first, as it always did.
-    const afterMerge = reviewedAfterMerge(config, role);
-    let overlap;
+    // break the build): a deterministic rejection never shows as reviewing on the dashboards.
+    // Both gate callers (the run path and runner-leftover.ts's recoverLeftover) get it for free.
+    // Its run, flake re-run, and attribution live in review-precheck.ts (the check run itself
+    // lives in runScopedBuildCheck, shared with the merge path's in-lock re-check); a resolved
+    // result here is returned verbatim and a pass hands the verified head to the merge path below.
+    // The pre-check always runs in the change's own slot. A retried attempt keeps the first
+    // attempt's passing pre-check (a green, or a red naming only main's known failures): the
+    // tree is the same head.
     if (!retry.pre) {
-        const lease = patchApproved || afterMerge ? null : await leaseCheckSlot(ctx, head);
-        if (lease)
-            overlap = startOverlappedCheck(ctx, state, head, lease);
-        else {
-            const pre = await gateBuildPrecheck(ctx, state, head, reject);
-            if (pre.resolved) {
-                state.reviewResume = undefined;
-                return pre.resolved;
-            }
-            retry.pre = { verifiedHead: pre.verifiedHead, knownMainFailures: pre.knownMainFailures };
+        const pre = await gateBuildPrecheck(ctx, state, head, reject);
+        if (pre.resolved) {
+            return pre.resolved;
         }
+        retry.pre = { verifiedHead: pre.verifiedHead, knownMainFailures: pre.knownMainFailures };
     }
-    const knownMainFailures = retry.pre?.knownMainFailures;
-    // A role listed in review.afterMerge merges on its gate alone: the deterministic rejects and the
-    // pre-check above still ran, and the merged commit is reviewed after it lands
-    // (reviewMergedCommit, run by the merge pipeline's post-review drain).
-    if (afterMerge && retry.pre) {
-        state.reviewResume = undefined;
-        state.lastApprovedHead = head;
-        return { decision: "approved", verifiedHead: retry.pre.verifiedHead };
-    }
-    if (patchApproved && retry.pre) {
-        state.reviewResume = undefined;
-        state.lastApprovedHead = head;
-        return { decision: "approved", verifiedHead: retry.pre.verifiedHead };
-    }
-    return runReviewer(ctx, state, {
-        head, overlap, knownMainFailures, retry, summary, commitBody, highFriction,
-        reviewedPatchId, reject, keep, settleFailedCheck,
-    });
+    // A passing pre-check approves: the gate runs no model reviewer, and every merge is judged
+    // once, after it lands, by the post-landing review (part 3g/3, reviewMergedCommit).
+    state.lastApprovedHead = head;
+    return { decision: "approved", verifiedHead: retry.pre.verifiedHead };
 }
 /** Review the change ahead of main, retrying a failed reviewer run in place (twice, 30 s apart)
  * before the attempt ends `failed`: a run that timed out, was killed, died in transport or at
  * the provider, or stated no VERDICT after its recovery turn. A resumable session is resumed,
  * otherwise the retry starts fresh (reviewAttempt). A configuration error and an abort are not
  * retried. While the reviewer's provider is held the retry waits for the hold to lift and
- * costs nothing. Each pause runs without the caller's team permit (idleWithoutProviderLease):
+ * costs nothing. Each pause runs without the caller's team permit (idleWithoutPermit):
  * a verification hands its lease back while it waits and takes it back before the next attempt.
  * See reviewAttempt for the rest of the gate's contract. */
 export async function reviewAheadOfMain(ctx, state, summary, commitBody, highFriction) {
@@ -241,10 +132,10 @@ export async function reviewAheadOfMain(ctx, state, summary, commitBody, highFri
         warnEventBestEffort(ctx.root, ctx.role, `the reviewer run failed (${result.detail ?? "no detail"}) — ${held ? "waiting for the provider hold to lift, then " : ""}retrying the review in place`);
         // The pause holds no team permit: a verification's lease is handed back while it waits and
         // re-taken before the next attempt, so a reviewer that keeps failing does not starve the roles.
-        await idleWithoutProviderLease(async () => {
-            await sleepUnlessAborted(delayMs, ctx.signal);
+        await idleWithoutPermit(async () => {
+            await sleepInterruptible(delayMs, ctx.signal);
             while (ctx.reviewHeld?.() && !ctx.signal?.aborted)
-                await sleepUnlessAborted(Math.min(delayMs, 5000), ctx.signal);
+                await sleepInterruptible(Math.min(delayMs, 5000), ctx.signal);
         }, ctx.signal);
         if (ctx.signal?.aborted)
             return { decision: "failed", aborted: true };
@@ -253,16 +144,3 @@ export async function reviewAheadOfMain(ctx, state, summary, commitBody, highFri
         retry.attempt += 1;
     }
 }
-function sleepUnlessAborted(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal?.aborted)
-            return resolve();
-        const done = () => {
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", done);
-            resolve();
-        };
-        const timer = setTimeout(done, ms);
-        signal?.addEventListener("abort", done, { once: true });
-    });
-}

package/dist/src/review/secret-leaks.js

@@ -32,47 +32,57 @@ export function secretEnvValues(env) {
     }
     return out;
 }
-/** The credentials pi stores: literal `apiKey`s and header values in `models.json`, and the
- * `key`/`access`/`refresh` fields (plus secret-named `env` values) of the sibling `auth.json`.
- * `$NAME` interpolations (secretEnvValues covers those) and `!command` values are skipped. A
- * missing or torn file yields nothing; never throws. */
-export function piCredentialValues(modelsPath = piModelsPath()) {
+/** Push `value` into `out` as a credential named `name`, unless it is not a string, is a `$NAME`
+ * interpolation or `!command`, or fails `looksLikeSecret`. */
+function addPiSecret(out, name, value) {
+    if (typeof value !== "string" || value.startsWith("$") || value.startsWith("!"))
+        return;
+    if (looksLikeSecret(value))
+        out.push({ name, value });
+}
+function modelsJsonCredentials(modelsPath) {
     const out = [];
-    const add = (name, value) => {
-        if (typeof value !== "string" || value.startsWith("$") || value.startsWith("!"))
-            return;
-        if (looksLikeSecret(value))
-            out.push({ name, value });
-    };
     const models = readJsonFile(modelsPath);
     if (models && isJsonObject(models.providers)) {
         for (const [p, cfg] of Object.entries(models.providers)) {
             if (!isJsonObject(cfg))
                 continue;
-            add(`models.json ${p}.apiKey`, cfg.apiKey);
+            addPiSecret(out, `models.json ${p}.apiKey`, cfg.apiKey);
             if (isJsonObject(cfg.headers)) {
-                for (const [h, v] of Object.entries(cfg.headers))
-                    add(`models.json ${p}.headers.${h}`, v);
+                for (const [h, v] of Object.entries(cfg.headers)) {
+                    addPiSecret(out, `models.json ${p}.headers.${h}`, v);
+                }
             }
         }
     }
+    return out;
+}
+function authJsonCredentials(modelsPath) {
+    const out = [];
     const auth = readJsonFile(path.join(path.dirname(modelsPath), "auth.json"));
     if (auth) {
         for (const [p, cred] of Object.entries(auth)) {
             if (!isJsonObject(cred))
                 continue;
             for (const f of ["key", "access", "refresh"])
-                add(`auth.json ${p}.${f}`, cred[f]);
+                addPiSecret(out, `auth.json ${p}.${f}`, cred[f]);
             if (isJsonObject(cred.env)) {
                 for (const [n, v] of Object.entries(cred.env)) {
                     if (SECRET_NAME.test(n))
-                        add(`auth.json ${p}.env.${n}`, v);
+                        addPiSecret(out, `auth.json ${p}.env.${n}`, v);
                 }
             }
         }
     }
     return out;
 }
+/** The credentials pi stores: literal `apiKey`s and header values in `models.json`, and the
+ * `key`/`access`/`refresh` fields (plus secret-named `env` values) of the sibling `auth.json`.
+ * `$NAME` interpolations (secretEnvValues covers those) and `!command` values are skipped. A
+ * missing or torn file yields nothing; never throws. */
+export function piCredentialValues(modelsPath = piModelsPath()) {
+    return [...modelsJsonCredentials(modelsPath), ...authJsonCredentials(modelsPath)];
+}
 /** Every secret the gate knows: secret-named environment values (named `$NAME`) then pi's stored
  * credentials (named `pi <file> <path>`), the first entry winning when two share a value. */
 export function knownSecrets(env = process.env, modelsPath = piModelsPath()) {

package/dist/src/roles/legacy-role-migration.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { deleteRefIfAt, refSha } from "../git/git.js";
-import { gitTry, runGit } from "../git/git-run.js";
+import { runGit } from "../git/git-run.js";
 import { branchName, mergeRefName, rejectedRefName, reviewSessionDir, roleInboxDir, roleNotesPath, sessionDir, statePath } from "../paths.js";
 import { errorMessage } from "../text/text.js";
 import { LEGACY_ROLE_IDS } from "./legacy-role-ids.js";
@@ -72,8 +72,11 @@ export async function migrateLegacyRoleIds(root, legacy = LEGACY_ROLE_IDS) {
                     return null;
                 if ((await refSha(root, to)) !== null)
                     return `kept ${from} and ${to}: both exist`;
-                if ((await gitTry(root, "update-ref", to, sha)) === null)
-                    throw new Error(`update-ref ${to} failed`);
+                // runGit, not gitTry: a failure here is reported verbatim into notes.failed, and gitTry
+                // would swallow the cause (git's stderr and exit code), leaving a bare `update-ref ${to}
+                // failed` with no reason to act on — the sibling branch move above propagates the same
+                // GitError through runGit, so this stays in family.
+                await runGit(root, ["update-ref", to, sha]);
                 await deleteRefIfAt(root, from, sha);
                 return `moved ${from} to ${to}`;
             });

package/dist/src/roles/role-catalog.js

@@ -4,7 +4,7 @@
  * in roles.ts. Pure catalog data — the shared instruction fragments role prompts embed live in
  * role-guidance.ts (import-only downward, so prompt assembly depends on both without a cycle).
  * roles.ts re-exports ROLES and Role, so every existing importer keeps its import path. */
-import { backlogMoveGuidance, CHECK_DECLARATION_MARKER, CONVERGENCE_HOLD_MARKER, DECOMPOSITION_GUIDANCE, NEEDS_REVIEW_NOTE, PLAN_QUEUE_GUIDANCE, PLAN_SIZING, searchGuidance, VALIDATION_GAP_GUIDANCE, VALIDATION_GAP_QUERY, VALIDATION_GAP_TALLY, } from "./role-guidance.js";
+import { backlogMoveGuidance, CHECK_DECLARATION_MARKER, CONVERGENCE_HOLD_MARKER, DECOMPOSITION_GUIDANCE, NEEDS_REVIEW_NOTE, PLAN_DEFECT_MARKER, PLAN_DEFECT_NOTE, PLAN_QUEUE_GUIDANCE, PLAN_SIZING, searchGuidance, VALIDATION_GAP_GUIDANCE, VALIDATION_GAP_QUERY, VALIDATION_GAP_TALLY, } from "./role-guidance.js";
 import { roleCommitGrep } from "./legacy-role-ids.js";
 import { NOTHING_TO_DO } from "../verdict/reply-contract.js";
 /** The trailer the readme role's commits carry and its `git log --grep` reads back; git parses
@@ -50,8 +50,10 @@ export const ROLES = [
    6. Mark the plan done in PLANS.md — ${backlogMoveGuidance("PLANS.md", "## Planned", "## Done", "PLANS-DONE.md", "done")}
    7. Verify last, after the PLANS.md edit, so one run of the project's check covers everything
       you changed (see "Leave the project working" below).
-A plan that resists implementation is a finding: refuse it with the objection recorded rather
-than forcing it.`,
+A plan whose approach or criteria are wrong is a finding the plan role owns, not a refusal:
+append ${PLAN_DEFECT_NOTE} under its heading with the objection recorded, skip it, and implement
+the next available plan that fits — do not force it. Reserve **Refused …** for a plan that
+should not be done at all, which is the user's call to decide.`,
     },
     {
         id: "bugfix",
@@ -113,6 +115,12 @@ within that budget, there is nothing to do.`,
         the quoted objections and the code they name and rewrite the plan so an implementation
         following it would answer each — correcting the approach or the anchors, tightening the
         acceptance criteria, or splitting it per PLAN_SIZING — then remove the note.
+      - A plan carrying a ${PLAN_DEFECT_MARKER} note (the feature implementer found the plan's
+        approach or criteria wrong) also outranks adding another plan: read the objection after the
+        marker and the code it names and rewrite the plan so an implementation following it would
+        answer it — correcting the approach or the anchors, tightening the acceptance criteria,
+        splitting it per PLAN_SIZING, or refusing it with the objection recorded when it should not
+        be done at all — then remove the note. That replan is this run's task.
       - A plan carrying a **Needs review …** note that quotes the reviewer's surviving objections
         (a final-round rejection — \`rejected after <N> review rounds\`) also outranks adding another
         plan: read the quoted objections and the code they name, then rewrite the plan so an

package/dist/src/roles/role-guidance.js

@@ -125,11 +125,6 @@ export const VALIDATION_GAP_QUERY = `grep -snE '\\*\\*Validation gap:\\*\\* (${V
  * feature role appends (gate-notes.ts) also begins with this prefix, so it reads as a Needs-review
  * note and is classified by entryHold accordingly. */
 export const NEEDS_REVIEW_PREFIX = `**Needs review `;
-/** The tag text before a held count, read by the backlog (backlog-eligibility's heldCount) so
- * the note form and the parser cannot drift. No writer emits `(held N)` anymore — the feature
- * note is flat — but heldCount still parses the tag from a Needs-review note line already on
- * disk until part 2f/6 removes the reader. */
-export const HELD_TAG_PREFIX = `(held `;
 /** The markdown note the feature role appends to a plan it cannot finish in one run, so the plan
  * role can split it. Mirrors the **Refused …** note convention: a note the next fresh run reads,
  * with no code parsing it. Defined once so the feature and plan texts and the director's routing
@@ -137,7 +132,7 @@ export const HELD_TAG_PREFIX = `(held `;
  * flat, so a new hold never escalates to the operator's desk. */
 export const NEEDS_REVIEW_NOTE = `${NEEDS_REVIEW_PREFIX}<YYYY-MM-DD> by feature: too large for one run**`;
 /** The literal reason the automatic convergence hold writes into a held plan's note
- * (holdEntryAfterExhaustion, src/runner/revision.ts, builds the note as
+ * (holdEntryAfterExhaustion, src/runner/runner-revision.ts, builds the note as
  * `**Needs review … by <role>: could not converge — <surviving objections>**`, INV-BH4).
  * Exported so the writer and the reader share one literal: it sits between holdEntryAfterExhaustion
  * (which writes the note) and the plan role's charter (role-catalog.ts `find`) which reads it, so
@@ -146,12 +141,21 @@ export const NEEDS_REVIEW_NOTE = `${NEEDS_REVIEW_PREFIX}<YYYY-MM-DD> by feature:
  * each hold to its own action without matching on a second literal. Add no second spelling of
  * this text. */
 export const CONVERGENCE_HOLD_MARKER = "could not converge";
-/** The marker a lifted hold leaves behind, so a split or rewrite carried the count instead of
- * letting it reset: `**Previously held N**` on the note's line. No writer emits this anymore (the
- * plan role's split no longer carries a count) and heldCount no longer reads it, so it is inert;
- * withoutHeldForOperatorNotes still drops a surviving `**Previously held N−1**` line beside a
- * released at-threshold note until part 2f/6 retires the count machinery. */
-export const PRIOR_HELD_PREFIX = `**Previously held `;
+/** The literal marker the feature role writes inside a Needs-review note when a planned entry's
+ * approach or acceptance criteria resists implementation, so the plan role re-specifies the plan
+ * instead of the refusal landing on the human user's desk. Mirrors the convergence hold: the note
+ * reads `**Needs review <YYYY-MM-DD> by feature: plan defect — <objection>**`, carrying this
+ * text only in the note body after the prefix, so entryHold classes it as a plain needs-review
+ * hold and the feature role (which reads a Needs-review note as a park) skips it. Exported so the
+ * feature charter (which tells the feature role to write it) and the plan charter (which reads it
+ * to replan) share one literal like the convergence marker does. Add no second spelling of this
+ * text. */
+export const PLAN_DEFECT_MARKER = "plan defect";
+/** The template for the replan hand-back note the feature role appends to a planned entry whose
+ * approach or criteria are wrong, routing it to the plan role instead of a Refused note. The
+ * objection the feature role recorded goes after the marker's dash, so the plan charter can name
+ * it (`the objection after the marker`) without parsing the note body itself. */
+export const PLAN_DEFECT_NOTE = `${NEEDS_REVIEW_PREFIX}<YYYY-MM-DD> by feature: ${PLAN_DEFECT_MARKER} — <objection>**`;
 /** The literal marker the plan role writes as its own line under the PLANS.md `## Planned` entry
  * that declares this project's deterministic check, and the feature role reads as that entry's
  * identity. It is the one decision point between the two no-check notes (gate-notes.ts

package/dist/src/roles/role-render.js

@@ -2,9 +2,7 @@ import { joinParts } from "../text/text.js";
 import { agree, shortSpanPhrase } from "../text/phrases.js";
 import { compactTokens, usd } from "../text/format.js";
 import { clockHm, formatAge, formatTimestamp, humanAgo, nextRunPhrase, secondsUntil } from "../text/datetime.js";
-import { claudeWindowLabel } from "../agent/claude/claude-account.js";
-import { windowLabel } from "../agent/subscription-account.js";
-import { backendDefaultLabel, backendDisplayName } from "../agent/backend-traits.js";
+import { backendDefaultLabel } from "../agent/backend-traits.js";
 import { yieldMultiplierSuffix } from "../scheduling/backoff.js";
 import { quietWindowEnd } from "../scheduling/quiet-hours.js";
 /** The terminal's view of one role — what `tumwater role <id>` prints, rendered as Markdown
@@ -133,7 +131,7 @@ function modelLine(p) {
 /** A fallback pair as one readable token, agent-qualified exactly like modelLine — a non-pi
  * backend (its `agent`, or a provider that names one, `claude`) is named as the selector's
  * namespace; a pi pair keeps `provider/model`; neither half present falls back to the
- * backend-default label. One home for the Model fallback and Budget fallback lines, so a
+ * backend-default label. One home for the Budget fallback line, so a
  * claude fallback reads `claude/claude-sonnet-5-5`, not a bare id (PLANS.md "Mixed claude +
  * pi fleets, part 3/4" gap 7). */
 function fallbackPairLabel(fb, backendDefault) {
@@ -147,26 +145,11 @@ function fallbackPairLabel(fb, backendDefault) {
         return fb.provider;
     return backendDefault;
 }
-/** The backend-and-window label the role view shows for a non-claude backend's window:
- * `backendDisplayName(billingBackend)` beside `windowLabel(windowType)` — "Codex 7d" for a
- * codex subscription (plans/codex-backend.md part 3c/9), so a reader knows whose window it
- * is. Claude keeps today's bare window type ("5h") so its role view stays byte-identical. */
-function billingWindowLabel(billingBackend, windowType) {
-    const type = windowType !== undefined ? windowLabel(windowType) : "";
-    const backend = billingBackend !== undefined && billingBackend !== "claude" ? backendDisplayName(billingBackend) : "";
-    return [backend, type].filter(Boolean).join(" ");
-}
-/** Why a tier moved down its fallback chain, as the role view words it. The window phrase
- * names the backend in play ("Codex 7d window used up") when a non-claude backend moved the
- * role; claude keeps today's wording byte-identical, and an unknown backend falls back to
- * today's hardcoded "Claude". */
-function chainReasonPhrase(reason, billingBackend, windowType) {
+/** Why a tier moved down its fallback chain, as the role view words it. */
+function chainReasonPhrase(reason) {
     switch (reason) {
         case "window":
-            if (billingBackend !== undefined && billingBackend !== "claude") {
-                return `${billingWindowLabel(billingBackend, windowType)} window used up`;
-            }
-            return `${windowType !== undefined ? claudeWindowLabel(windowType) : "Claude"} window used up`;
+            return "window used up";
         case "reserve":
             return "window reserve reached";
         case "cap":
@@ -186,7 +169,7 @@ function chainStepLine(p) {
     if (!c)
         return null;
     const resets = c.returnsAt !== undefined ? `, resets ${clockHm(c.returnsAt)}` : "";
-    return `- Running on fallback ${c.step} of ${c.of} (${chainReasonPhrase(c.reason, p.billingBackend, p.billingWindow)}${resets})`;
+    return `- Running on fallback ${c.step} of ${c.of} (${chainReasonPhrase(c.reason)}${resets})`;
 }
 /** One recent run outcome as a Markdown bullet line — `<time> · <result> · <span> —
  * <summary>` — so `tumwater role <id>` and the TUI notes view read a role's discrete
@@ -254,13 +237,6 @@ export function renderRoleMarkdown(p, now = Date.now()) {
     // fallback's own documented state). `unknown` when it cannot be known (a non-pi seam, an
     // unresolvable pair, a model with no declared window).
     lines.push(`- Context window: ${p.contextWindow === null ? "unknown" : `${compactTokens(p.contextWindow)} tokens`}`);
-    // Per-provider concurrency cap (plans/provider-concurrency.md §8): name the key whose cap
-    // bounds the role's concurrent runs, plus the cap itself. Present only while
-    // `maxConcurrentPerProvider` maps this seam's key — a cap-less default team has no
-    // resolvable key entry, so its role view renders no new line and stays byte-identical.
-    if (p.providerKey !== undefined && p.providerCap !== undefined) {
-        lines.push(`- Provider: ${p.providerKey} (cap ${p.providerCap})`);
-    }
     // Image input (plans/image-input.md "Surfaces", part 5/5): whether this role's own model
     // reads images, and — when it cannot — where a run that reads an image reroutes. Not just
     // `yes`/`no`: a text-only role that falls back names the target, so `tumwater role <id>`
@@ -274,18 +250,6 @@ export function renderRoleMarkdown(p, now = Date.now()) {
                 : "no"
             : "unknown";
     lines.push(`- Images: ${images}`);
-    // Whether the review gate reviews this role's commits after they merge (role-view.ts's
-    // reviewedAfterMerge). Present only while review.enabled is on and review.afterMerge lists
-    // the role's base id — a pre-merge-reviewed role or a gate-off config omits the line.
-    if (p.reviewedAfterMerge) {
-        lines.push(`- Review: after merge (a rejected change stays on main with the reviewer's recorded reasons)`);
-    }
-    // Model failure fallback, part 2/2: name the off-model pair, when the episode began, and
-    // the provider-class failure that tripped it, so `tumwater role <id>` explains the state.
-    if (p.modelFallback) {
-        const pair = fallbackPairLabel(p.modelFallback, backendDefault(p));
-        lines.push(`- Model fallback: ${pair} — on fallback since ${formatTimestamp(p.modelFallback.since)} (primary failing: ${p.modelFallback.reason})`);
-    }
     if (p.fallback) {
         const pair = fallbackPairLabel(p.fallback, backendDefault(p));
         lines.push(`- Over-cap model: ${pair} (${p.fallbackFree ? "free" : "priced"})`);
@@ -296,10 +260,7 @@ export function renderRoleMarkdown(p, now = Date.now()) {
     // The claude seam's billing (plans/agent-backends.md §7/§8, PLANS.md part 6d/7): absent on
     // a pi seam, so its role view is byte-identical to before.
     if (p.billing) {
-        const window = p.billing === "subscription" && p.billingWindow
-            ? ` (${billingWindowLabel(p.billingBackend, p.billingWindow)} window)`
-            : "";
-        lines.push(`- Billing: ${p.billing === "api" ? "API" : p.billing}${window}`);
+        lines.push(`- Billing: ${p.billing === "api" ? "API" : p.billing}`);
     }
     lines.push(`- Min run interval: ${p.minRunIntervalSeconds}s`);
     if (p.instances !== undefined)