tumwater 0.4.2 → 0.4.3

package/dist/src/review/review.js

@@ -1,18 +1,16 @@
 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";
+export { REVIEW_FAILURE_LIMIT, 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,89 +21,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 while the
+ * reviewer's remaining seams stay in review-run.ts/review-followup.ts. */
+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;
@@ -120,22 +69,6 @@ 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;
@@ -164,67 +97,34 @@ async function reviewAttempt(ctx, state, summary, commitBody, highFriction, retr
         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) {
+            state.reviewResume = undefined;
+            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.reviewResume = undefined;
+    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 +141,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 +153,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/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

@@ -133,7 +133,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) {
@@ -254,13 +254,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>`
@@ -280,12 +273,6 @@ export function renderRoleMarkdown(p, now = Date.now()) {
     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"})`);

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

@@ -19,11 +19,11 @@ import { projectCapHit } from "../budget/budget.js";
 import { yieldMultiplierFor } from "../scheduling/backoff.js";
 import { quietHoursStatus } from "../scheduling/quiet-hours.js";
 import { assembleRunPrompt } from "../run/run-prompt.js";
-import { configForRole, resolvedModelFields, reviewedAfterMerge, reviewRunConfig, roleSeamTier, seamConcurrencyKey } from "../config/config-views.js";
-import { fallbackPair, modelFallbackView } from "../config/config-fallbacks.js";
+import { configForRole, resolvedModelFields, reviewedAfterMerge, reviewRunConfig, roleSeamTier } from "../config/config-views.js";
+import { fallbackPair } from "../config/config-fallbacks.js";
 import { fallbackModelPair, piModelsPath, seamContextWindowForRole } from "../pi/pi-models.js";
 import { readOpencodeCache } from "../agent/opencode/opencode-catalog.js";
-import { formatModelSelector } from "../config/model-selector.js";
+import { formatModelSelector } from "../config/config-model-selector.js";
 import { roleImageInfo } from "../agent/image-input.js";
 import { readPiListedModels } from "../pi/pi-listed-models.js";
 import { piSettingsPath, readPiDefaultModel } from "../pi/pi-settings.js";
@@ -32,11 +32,11 @@ import { readAccount, windowEntries } from "../agent/subscription-account.js";
 import { CONFIG_BASENAME, configPath, roleNotesPath } from "../paths.js";
 import { coverageRows, readQaCoverage } from "../run/qa-coverage.js";
 import { filingRows, readFeedbackFilings } from "../run/feedback-filings.js";
-import { readTextOrNull, statOrNull } from "../files/files.js";
+import { readRegularTextOrNull, statOrNull } from "../files/files.js";
 import { eventRole, eventUsage, readEvents } from "../events/event-read.js";
 import { finiteNumber, objectOrEmpty } from "../files/json-object.js";
 import { canonicalRoleId } from "./legacy-role-ids.js";
-import { orchestratorAlive, readOrchestratorInfo } from "../team/orchestrator-info.js";
+import { orchestratorAlive, readOrchestratorInfo } from "../team/team-orchestrator-info.js";
 /** The roles.<base>.<field> value the FILE actually holds, or undefined when the file never
  * set that field. Needed only for the seeded per-role fields: overlayDefaults fills every
  * built-in role's minRunIntervalSeconds from config.ts's catalog, so the merged config cannot
@@ -103,14 +103,6 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
         effective.provider === undefined &&
         effective.model === undefined;
     const piDefault = runsPiWithoutAModel ? readPiDefaultModel(piSettingsPath(modelsPath), root) : null;
-    // The role's provider key and its cap (plans/provider-concurrency.md §8): the same pure
-    // key the orchestrator's admission resolves for this role, answered from the same
-    // piDefault seam the orchestrator carries, so `tumwater role <id>` names the exact key
-    // whose cap bounds the role. The cap is the map's entry for that key, absent when no
-    // `maxConcurrentPerProvider` map is set or the key has no entry (then the role is bounded
-    // only by the team total, and the cap is omitted).
-    const providerKey = seamConcurrencyKey(effective, piDefault);
-    const providerCap = providerKey !== undefined ? cfg.maxConcurrentPerProvider?.[providerKey] : undefined;
     // The fallback story the operator sees: the declared pair, but the price-resolved pair when
     // one exists (a map with no `default` entry borrows another tier's free pair) and the
     // freeness verdict from the same read. `fallbackFree` false keeps the declared pair visible
@@ -135,9 +127,8 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
     const accounts = (b) => (b === "claude" ? claudeFallbackAccount : null);
     const freeFallback = declaredFallback ? fallbackModelPair(cfg, modelsPath, accounts, opencodeCatalog) : null;
     const fallback = freeFallback ?? declaredFallback;
-    // One state read serves both the model-fallback episode and the next-run preview below.
+    // One state read serves the next-run preview below.
     const state = loadRunnerState(root, role);
-    const episode = state.modelFallback;
     // The role's recent run outcomes, read from the event log (readEvents) so the command
     // answers with the team stopped and never touches live state. readEvents returns the log's
     // newest events in file (chronological) order, so filtering to this role's run_end events
@@ -233,7 +224,7 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
     let noteSavedAt = null;
     if (role !== DIRECTOR_ROLE) {
         const notesPath = roleNotesPath(root, role);
-        const text = readTextOrNull(notesPath);
+        const text = readRegularTextOrNull(notesPath);
         note = text !== null && text.trim() !== "" ? text : null;
         if (note !== null)
             noteSavedAt = statOrNull(notesPath)?.mtimeMs ?? null;
@@ -270,11 +261,8 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
             }
             : {}),
         backend: effective.agent ?? "pi",
-        ...(providerKey !== undefined ? { providerKey } : {}),
-        ...(providerCap !== undefined ? { providerCap } : {}),
         fallback,
         fallbackFree: freeFallback !== null,
-        modelFallback: modelFallbackView(episode, cfg, role),
         ...(account !== null ? { billing: account.billing, billingBackend } : {}),
         ...(billingWindow !== undefined ? { billingWindow } : {}),
         chainStep,
@@ -334,8 +322,8 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
             preview: true,
         })?.prompt ?? null,
         // The role's schedule — surfaced read-only from the same persisted state rolePayload
-        // already loaded for the model-fallback episode and the next-run preview, so no new
-        // read path exists and the collector stays one loadRunnerState per role. `lastRunEndedAt`
+        // already loaded for the next-run preview, so no new read path exists and the collector
+        // stays one loadRunnerState per role. `lastRunEndedAt`
         // is omitted (JSON unchanged) until the role has actually run.
         nextRunAt: state.nextRunAt,
         backoffSeconds: state.backoffSeconds,