@codedrifters/configulator 0.0.354 → 0.0.355

package/lib/index.mjs

@@ -13440,7 +13440,36 @@ function renderIssueWorkerSkillBody(task, lines) {
     "",
     `Route matched issues to \`.claude/agents/${task.agent}.md\` and`,
     "execute its phase-specific workflow.",
-    "",
+    ""
+  );
+  if (task.taskId === "worker-issue") {
+    lines.push(
+      "## Feedback-pull scan (runs before issue selection)",
+      "",
+      "Because you run autonomously (scheduled mode), **also scan for PRs",
+      "needing feedback work before scanning the issue queue** \u2014 and",
+      "prefer them. The pr-reviewer hands fixes off by applying a durable",
+      "`review:needs-worker` marker on the PR (it cannot spawn you in",
+      "session). Pull that marker instead of waiting for an explicit push:",
+      "",
+      "```bash",
+      "gh pr list --state open --label 'review:needs-worker' \\",
+      "  --json number,labels,headRefName,updatedAt",
+      "```",
+      "",
+      "If any open PR carries an unconsumed `review:needs-worker` fix-list,",
+      "enter **feedback mode** for the highest-priority match (no explicit",
+      "`feedback mode: PR #<n>` push required) and run the issue-worker's",
+      "feedback-mode phases: apply the fix-list, push, write the",
+      "worker-report comment, and **clear `review:needs-worker`** (leave",
+      "`review:fixing` for the reviewer's confirm pass). Only when no PR",
+      "needs a worker do you fall through to the issue-queue selection",
+      "above. See the **Invocation Mode** and **Phase 1** sections of",
+      "`.claude/agents/issue-worker.md` for the full contract.",
+      ""
+    );
+  }
+  lines.push(
     "## Recommended model",
     "",
     `**${capitalize(task.recommendedModel)}** \u2014 see`,
@@ -15786,15 +15815,31 @@ var issueWorkerSubAgent = {
     "  **not** create a new branch and you do **not** open a new PR \u2014 you",
     "  push additional commits to the same branch.",
     "",
-    "**You are in feedback mode if and only if the invocation prompt that",
-    "started this session contains the literal phrase `feedback mode: PR #<n>`",
-    "(where `<n>` is the PR number).** This mirrors the `scheduled mode` /",
-    "`non-interactive` string-match convention above. Otherwise, default to",
-    "normal mode.",
+    "You enter feedback mode in one of **two** ways:",
+    "",
+    "1. **Pushed (explicit).** The invocation prompt that started this",
+    "   session contains the literal phrase `feedback mode: PR #<n>`",
+    "   (where `<n>` is the PR number). This mirrors the `scheduled",
+    "   mode` / `non-interactive` string-match convention above and works",
+    "   in both interactive and scheduled invocations (a human asks you",
+    "   to fix a PR, or the orchestrator hands one off as a stopgap).",
+    "2. **Pulled (autonomous, scheduled only).** In **scheduled mode**,",
+    "   even without an explicit `feedback mode: PR #<n>` push, you also",
+    "   discover PRs needing feedback work by scanning open PRs for the",
+    "   durable `review:needs-worker` marker (see Phase 1). When you pick",
+    "   one up, you enter feedback mode for that PR autonomously. This is",
+    "   how the reviewer's pull-based hand-off completes without any",
+    "   depth-2 sub-agent spawn \u2014 the reviewer applies the marker, you",
+    "   pull it.",
+    "",
+    "Otherwise, default to normal mode. The explicit `feedback mode: PR",
+    "#<n>` push path always wins: when present, work that PR and do not",
+    "scan the queue.",
     "",
     "Interactive vs scheduled and normal vs feedback are independent axes.",
     "Feedback mode can run interactively (a human asks you to fix a PR) or",
-    "on a schedule (the pr-reviewer hands off the PR). The interactive",
+    "on a schedule (autonomously pulled from the `review:needs-worker`",
+    "queue, or pushed by the orchestrator). The interactive",
     "pause-before-commit rule (Phase 6) applies in either work mode.",
     "",
     "When in feedback mode, the per-phase behaviour changes as documented",
@@ -15802,12 +15847,13 @@ var issueWorkerSubAgent = {
     "",
     "| Phase | Normal mode | Feedback mode |",
     "|-------|-------------|---------------|",
-    "| 1. Select an Issue | Pick from queue or use provided issue number | **Skip.** Use the PR number from the invocation prompt. |",
+    "| 1. Select an Issue | Pick from queue or use provided issue number | **Pushed:** use the PR number from the prompt. **Pulled (scheduled):** scan open PRs for `review:needs-worker`, pick the highest-priority match. Feedback PRs are preferred over fresh issues. |",
     "| 2. Claim the Issue | Toggle status labels on the issue | **Skip.** The issue is already `status:in-progress`. |",
     "| 3. Set Up | Checkout default branch, create new branch | Checkout the existing PR branch via `gh pr view` and `git checkout <headRefName>`. |",
     "| 4. Implement | Read issue AC, implement | Read most-recent reviewer-authored fix-list comment on the PR, parse JSON, apply each item. |",
     "| 5. Verify | Unchanged | Unchanged. |",
     "| 6. Commit and Push | Conventional commit, interactive pause | Commit message `fix(review): <summary> (PR #<n>)`. Pause behaviour unchanged. `git push` (no `-u`). |",
+    "| 6.5. Complete the hand-off | n/a | Write the structured worker-report comment, then **clear `review:needs-worker`** (leave `review:fixing` for the reviewer's confirm pass). |",
     "| 7. Open a PR | Open a new PR | **Skip.** |",
     "| 8. Update Status | Set issue to `status:ready-for-review` | **Skip.** PR is still open; issue stays `status:in-progress`. |",
     "| 9. Branch Cleanup | Poll for merge, delete branch | **Skip.** Return control to the pr-reviewer without polling. |",
@@ -15817,9 +15863,40 @@ var issueWorkerSubAgent = {
     ...PROJECT_CONTEXT_READER_SECTION,
     "## Phase 1: Select an Issue",
     "",
-    "**Feedback mode:** Skip this phase entirely. Extract the PR number from",
-    "the `feedback mode: PR #<n>` phrase in your invocation prompt and use",
-    "it for the rest of the workflow.",
+    "**Feedback mode (pushed):** When the invocation prompt contains an",
+    "explicit `feedback mode: PR #<n>` phrase, skip the rest of this phase.",
+    "Extract the PR number from that phrase and use it for the rest of the",
+    "workflow. The explicit push always wins \u2014 do not scan the queue.",
+    "",
+    "**Feedback-pull discovery (scheduled mode, no explicit push).** Before",
+    "scanning the issue queue, check for PRs needing feedback work. This is",
+    "how the pr-reviewer's pull-based hand-off completes: the reviewer",
+    "applies a durable `review:needs-worker` marker and exits; you discover",
+    "it here. **Feedback PRs are preferred over fresh issues** \u2014 a queued",
+    "fix-list is a half-finished unit of work and should land before a new",
+    "one starts.",
+    "",
+    "Scan open PRs carrying the marker, sorted highest-priority first:",
+    "",
+    "```bash",
+    "gh pr list --state open --label 'review:needs-worker' \\",
+    "  --json number,labels,headRefName,updatedAt",
+    "```",
+    "",
+    "For each candidate, confirm it carries an **unconsumed** reviewer",
+    "fix-list \u2014 a `review:needs-worker` label that the reviewer applied",
+    "alongside a `## Reviewer: fix list for @issue-worker` comment whose",
+    "` ```json fix-list ` block has not yet been applied by a worker",
+    "(no newer worker-report comment from you). Pick the **highest-priority**",
+    "match (use the linked issue's `priority:*` label; break ties by oldest",
+    "`updatedAt`). Enter feedback mode for that PR **without** requiring an",
+    "explicit `feedback mode: PR #<n>` push, and run Phases 3\u20136.5 against",
+    "it. If no PR carries an unconsumed `review:needs-worker` marker, fall",
+    "through to normal-mode issue selection below.",
+    "",
+    "(Interactive sessions do **not** auto-pull \u2014 a human who wants a",
+    "specific PR fixed passes `feedback mode: PR #<n>` explicitly. The",
+    "autonomous pull is scheduled-mode only.)",
     "",
     "**Normal mode:**",
     "If an issue number was provided in your instructions, use that issue.",
@@ -16173,6 +16250,47 @@ var issueWorkerSubAgent = {
     "git push -u origin <branch-name>",
     "```",
     "",
+    "## Phase 6.5: Complete the Feedback Hand-off",
+    "",
+    "**Normal mode:** Skip this phase entirely.",
+    "",
+    "**Feedback mode:** After the fix commits are pushed (Phase 6), close",
+    "the pull-based hand-off so the pr-reviewer's confirm pass can pick it",
+    "up.",
+    "",
+    "1. **Write the structured worker-report comment** on the PR. It is",
+    "   the record the reviewer's confirm pass reads to react on source",
+    "   comments and re-evaluate AC/CI. Include: the PR number, the commit",
+    "   SHAs you pushed (or the rebased head SHA for a synthetic-rebase",
+    "   item), and a per-item outcome keyed by `comment_id` \u2014 `handled`",
+    "   or `failed` (with a short reason for each failure). This is the",
+    "   same structured report you would otherwise return to the caller in",
+    "   the pushed-feedback case; post it as a PR comment so a separate",
+    "   reviewer session can consume it.",
+    "",
+    "   ```bash",
+    "   gh pr comment <pr-number> --body-file <worker-report-path>",
+    "   ```",
+    "",
+    "2. **Clear the `review:needs-worker` marker.** This signals the",
+    "   reviewer that the delegation has been consumed. Leave the",
+    "   `review:fixing` lease in place \u2014 the reviewer's confirm pass",
+    "   releases it after reacting and re-evaluating. Clearing the marker",
+    "   is what flips the PR into the lease-without-marker state the",
+    "   confirm pass keys on.",
+    "",
+    "   ```bash",
+    "   gh pr edit <pr-number> --remove-label 'review:needs-worker'",
+    "   ```",
+    "",
+    "Do **not** remove `review:fixing` yourself, and do **not** re-enable",
+    "auto-merge \u2014 both belong to the reviewer's confirm pass. If you could",
+    "not apply any item (every item `failed`), still write the report and",
+    "still clear `review:needs-worker`: the reviewer's confirm pass reacts",
+    "`thinking_face` on the failed items and falls through to the",
+    "human-required hand-off via `review:awaiting-human`. Leaving the",
+    "marker applied on a total failure would wedge the PR.",
+    "",
     "## Phase 7: Open a PR",
     "",
     "**Feedback mode:** Skip this phase entirely. The PR already exists; you",
@@ -16219,9 +16337,13 @@ var issueWorkerSubAgent = {
     "## Phase 9: Branch Cleanup",
     "",
     "**Feedback mode:** Skip this phase entirely. Do not poll the PR state",
-    "and do not delete the local branch. Return control to the pr-reviewer",
-    "with the structured report from Phase 4 (PR number, commit SHAs pushed,",
-    "items handled by `comment_id`, items that failed to apply).",
+    "and do not delete the local branch. You have already posted the",
+    "structured worker-report comment and cleared `review:needs-worker` in",
+    "Phase 6.5 \u2014 the pr-reviewer's confirm pass picks up the hand-off from",
+    "the lease-without-marker label state. Return control to the caller",
+    "with the same structured report (PR number, commit SHAs pushed, items",
+    "handled by `comment_id`, items that failed to apply) so a pushing",
+    "orchestrator can log it.",
     "",
     "**Normal mode:**",
     "",
@@ -16289,7 +16411,24 @@ var issueWorkerSubAgent = {
     "    with a `BLOCKED_ON_SCOPE` report if the classifier returns",
     "    `large`. Never claim, branch, or implement a `large` issue \u2014",
     "    the orchestrator must decompose it first. See the **Scope gate**",
-    "    section in `CLAUDE.md` for the contract."
+    "    section in `CLAUDE.md` for the contract.",
+    "15. **Prefer feedback PRs over fresh issues (scheduled mode).** When",
+    "    running autonomously, scan open PRs for the `review:needs-worker`",
+    "    marker **before** scanning the issue queue, and pick up the",
+    "    highest-priority unconsumed fix-list first. A half-finished PR",
+    "    should land before a new unit of work starts. The explicit",
+    "    `feedback mode: PR #<n>` push always overrides both scans.",
+    "16. **Clear `review:needs-worker`, never `review:fixing`.** On",
+    "    completing a feedback hand-off (Phase 6.5), write the structured",
+    "    worker-report comment and remove **only** the",
+    "    `review:needs-worker` marker. The `review:fixing` lease belongs",
+    "    to the reviewer's confirm pass \u2014 never remove it yourself, and",
+    "    never re-enable auto-merge. Clear the marker even when every item",
+    "    failed, so a crashed delegation does not wedge the PR.",
+    "17. **Auto-pull only in scheduled mode.** The autonomous",
+    "    `review:needs-worker` scan is scheduled-mode only. In an",
+    "    interactive session, never auto-pull a feedback PR \u2014 a human who",
+    "    wants one fixed passes `feedback mode: PR #<n>` explicitly."
   ].join("\n")
 };
 var ORCHESTRATOR_CONVENTIONS_PREAMBLE = [
@@ -17845,8 +17984,12 @@ var prReviewerSubAgent = {
     "  conflicting files). The guards and classification are identical to",
     "  the Phase 4 entry point.",
     "- **On the procedure returning `delegated`:** a rebase has been",
-    "  delegated to `issue-worker`; stop this pass. A human re-invokes",
-    "  the reviewer once the worker pushes the rebased branch.",
+    "  durably queued for `issue-worker` (the PR now carries",
+    "  `review:needs-worker` and the `review:fixing` lease); stop this",
+    "  pass. A top-level `issue-worker` session pulls the marker and",
+    "  pushes the rebased branch, then a follow-up reviewer pass confirms",
+    "  the result and releases the lease \u2014 no human re-invocation is",
+    "  required for the loop to complete.",
     "- **On the procedure returning `skipped` (a guard denied delegation",
     "  or the guards failed):** fall back to the original hard reject \u2014",
     "  post the merge-conflict rejection comment and stop. Use this",
@@ -18267,14 +18410,20 @@ var prReviewerSubAgent = {
     "",
     "When the invocation guard above permits delegation **and** Phase 3.5",
     "queued one or more `in-scope` items, the reviewer hands the fix work",
-    "off to `issue-worker` in feedback mode. The reviewer never edits the",
-    "PR's branch itself.",
-    "",
-    "Run the steps below in order. Steps (a) through (g) apply in **both**",
-    "`auto-merge` and `human-required` review modes. Step (h) is",
-    "auto-merge-only \u2014 in `human-required` mode the reviewer skips it,",
-    "leaves `review:awaiting-human` applied, and lets the human own the",
-    "final merge.",
+    "off to `issue-worker` via a **pull-based** marker. The reviewer never",
+    "edits the PR's branch itself and never spawns `issue-worker` in",
+    "session \u2014 it posts the fix-list, applies the `review:needs-worker`",
+    "marker, holds the `review:fixing` lease across sessions, and exits.",
+    "A top-level `issue-worker` session pulls the work; a later reviewer",
+    "pass confirms it via the **Shared Procedure: Confirm a Completed",
+    "Delegation**.",
+    "",
+    "Run steps (a) through (e) below in order. They apply in **both**",
+    "`auto-merge` and `human-required` review modes \u2014 the mode-specific",
+    "auto-merge decision is deferred to the confirm pass, which only",
+    "re-enables auto-merge in `auto-merge` mode (in `human-required` mode",
+    "the confirm pass leaves `review:awaiting-human` applied and lets the",
+    "human own the final merge).",
     "",
     "#### a. Handle AC drift first",
     "",
@@ -18373,103 +18522,48 @@ var prReviewerSubAgent = {
     "(or `--body` if the body is short). Capture the resulting comment id",
     "in memory so Phase 4.5 can cite the fix-list URL in the sticky.",
     "",
-    "#### e. Invoke `issue-worker` in feedback mode",
-    "",
-    "Hand the fix work off to the `issue-worker` sub-agent. The invocation",
-    "prompt **must** contain the literal phrase `feedback mode: PR #<n>`",
-    "(with the actual PR number substituted) so the worker enters its",
-    "feedback-mode branch instead of selecting a new issue. The prompt",
-    "must also include the repository (`{{repository.owner}}/{{repository.name}}`)",
-    "and the PR number explicitly \u2014 do not rely on the worker inferring",
-    "either from context.",
-    "",
-    "Wait for the worker to return its structured report. The report",
-    "lists, per item, the `comment_id` and a status of `handled` or",
-    "`failed` (with a short failure reason for the latter). If the worker",
-    "errors out without returning a report, treat **every** item as failed",
-    "and proceed to step (f) so source comments still get a reaction.",
-    "",
-    "#### f. Process the worker's report",
-    "",
-    "For every item the worker reports:",
+    "#### e. Apply the `review:needs-worker` marker and exit `delegated`",
     "",
-    "- **`handled`** \u2014 react `rocket` on the original source comment to",
-    "  signal the accepted change has landed. Use the same comment",
-    "  endpoint the comment originated from (`issues/comments/...` for",
-    "  PR-level, `pulls/comments/...` for inline).",
-    "- **`failed`** \u2014 react `thinking_face` (`content=confused`) on the",
-    "  original source comment **and** post a reply on the same thread",
-    "  explaining why the fix could not be applied (cite the failure",
-    "  reason returned by the worker).",
+    "Hand the fix work off to `issue-worker` **by marker, not by spawn**.",
+    "Do **not** invoke `issue-worker` via the `Agent` tool from this pass:",
+    "the reviewer frequently runs at depth-1 (the orchestrator's PR sweep",
+    "dispatches it as a sub-agent), and the runtime forbids a depth-1",
+    "sub-agent from spawning a depth-2 sub-agent \u2014 an in-session dispatch",
+    "would silently abort and the fix-list would never be consumed.",
+    "Instead, apply the durable `review:needs-worker` marker so a",
+    "top-level `issue-worker` session discovers the PR and pulls the",
+    "fix-list:",
     "",
     "```bash",
-    "# Rocket reaction on a successfully handled PR-level comment",
-    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/comments/<comment-id>/reactions \\",
-    "  -X POST -f content=rocket",
-    "",
-    "# thinking_face + reply on a failed item",
-    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/comments/<comment-id>/reactions \\",
-    "  -X POST -f content=confused",
-    "gh pr comment <pr-number> --body '<failure explanation citing the worker report>'",
-    "```",
-    "",
-    "#### g. Release the `review:fixing` lease",
-    "",
-    "Remove the lease label so the PR is open for the next delegation",
-    "pass. Always run this step \u2014 even when the worker reported every",
-    "item as failed:",
-    "",
-    "```bash",
-    "gh pr edit <pr-number> --remove-label 'review:fixing'",
+    "gh pr edit <pr-number> --add-label 'review:needs-worker'",
     "```",
     "",
-    "#### h. Conditionally re-enable auto-merge (auto-merge mode only)",
-    "",
-    "Re-enable squash auto-merge **only if all four** of the following",
-    "conditions hold. If any condition fails, leave auto-merge disabled",
-    "and let the next reviewer pass re-evaluate:",
-    "",
-    "1. The review mode decided in Phase 2.75 is still `auto-merge`",
-    "   (re-evaluate against the current PR labels in case a maintainer",
-    "   added `review:human-required` between passes).",
-    "2. **All** acceptance criteria are met against the **updated** diff",
-    "   produced by the worker \u2014 re-run the Phase 3 comparison; do not",
-    "   reuse the pre-delegation result.",
-    "3. **No** unresolved `thinking_face` reactions authored by the",
-    "   reviewer remain on any PR comment \u2014 including the AC-drift",
-    "   pushbacks added in step (a) and the failure pushbacks added in",
-    "   step (f).",
-    "4. CI is green or still pending (any failing required check",
-    "   disqualifies re-enablement). Resolve CI via the **CI",
-    "   Verification** section, including the Actions-runs fallback on a",
-    "   fine-grained-PAT 403.",
-    "",
-    "When all four hold, re-enable auto-merge with the same command used",
-    "in the auto-merge branch below:",
-    "",
-    "```bash",
-    "gh pr merge <pr-number> --auto --squash --delete-branch \\",
-    "  --subject '<conventional-commit-title>' \\",
-    "  --body '<extended-description>'",
-    "```",
-    "",
-    "In `human-required` mode, **skip step (h) entirely**. The",
-    "`review:awaiting-human` label stays applied (re-add it if a previous",
-    "step removed it), and the human reviewer owns the final merge",
-    "decision.",
-    "",
-    "#### i. Update the sticky summary",
-    "",
-    "After step (g) (and step (h) when applicable) completes, fall through",
-    "to Phase 4.5 to update the sticky `## Reviewer notes` comment with",
-    "the new state. Cite at minimum:",
+    "Then **exit this pass returning `delegated`**, holding the",
+    "`review:fixing` lease across sessions. Do **not** wait for the",
+    "worker, do **not** process a report, and do **not** re-enable",
+    "auto-merge in this pass. The worker applies the fix-list in its own",
+    "top-level session, pushes, writes a structured worker-report comment,",
+    "and clears `review:needs-worker`. A **subsequent** reviewer pass",
+    "detects the lease-without-marker state and runs the **Shared",
+    "Procedure: Confirm a Completed Delegation** below \u2014 that is where the",
+    "`rocket` / `thinking_face` reactions, the AC/CI re-evaluation, the",
+    "auto-merge re-enablement, and the `review:fixing` release happen.",
+    "",
+    "Before exiting, fall through to Phase 4.5 to update the sticky",
+    "`## Reviewer notes` comment with the delegation state. Cite at",
+    "minimum:",
     "",
     "- The fix-list comment URL produced in step (d).",
-    "- The commit SHAs the worker pushed (from its structured report).",
-    "- Per-item outcome (`handled` / `failed`) with the source comment URL.",
-    "- The auto-merge re-enablement decision and reason (which of the",
-    "  four conditions, if any, blocked it).",
-    "- The next-step the human or the next reviewer pass should take.",
+    "- That the PR now carries `review:needs-worker` and is awaiting a",
+    "  top-level `issue-worker` pass.",
+    "- That `review:fixing` is held across sessions until a confirm pass",
+    "  releases it.",
+    "- The next-step: a top-level `issue-worker` run pulls the fix-list,",
+    "  then a follow-up reviewer pass confirms.",
+    "",
+    "Per-item `handled` / `failed` outcomes, the pushed commit SHAs, and",
+    "the auto-merge decision are recorded on the **confirm pass**, not",
+    "here \u2014 this pass has not yet seen the worker's result.",
     "",
     "### If all acceptance criteria are met and CI is green",
     "",
@@ -18901,28 +18995,37 @@ var prReviewerSubAgent = {
     "   ```",
     "   ```",
     "",
-    "4. **Invoke `issue-worker` in feedback mode** with the same prompt",
-    "   shape used by the in-scope-fix flow: include the literal phrase",
-    "   `feedback mode: PR #<n>` plus the repository identifier",
-    "   (`{{repository.owner}}/{{repository.name}}`).",
-    "",
-    "5. **Process the worker's report** for the synthetic item using the",
-    "   same logic as step (f) of the in-scope-fix flow \u2014 `handled` reacts",
-    "   `rocket` on the fix-list comment; `failed` reacts `thinking_face`",
-    "   and posts a reply citing the worker's failure reason.",
-    "",
-    "6. **Release the `review:fixing` lease** with",
-    "   `gh pr edit <pr-number> --remove-label 'review:fixing'`. Always",
-    "   run this step.",
+    "4. **Apply the durable `review:needs-worker` marker** so a",
+    "   subsequent (top-level) `issue-worker` pass discovers the PR and",
+    "   pulls the fix-list. Do **not** spawn `issue-worker` yourself \u2014 the",
+    "   reviewer often runs at depth-1 (the orchestrator's PR sweep",
+    "   dispatches it as a sub-agent) where nested sub-agent spawning is",
+    "   forbidden, so an in-session `Agent` dispatch would silently abort.",
+    "   The hand-off is pull-based: the marker is the signal, the",
+    "   `review:fixing` lease (acquired in step 2) is held **across",
+    "   sessions** until the worker clears the marker and a later reviewer",
+    "   pass confirms.",
     "",
-    "7. **Do not re-enable auto-merge in the same pass.** After delegation,",
-    "   exit and let a human re-invoke the reviewer. The next pass will",
-    "   re-evaluate `mergeStateStatus` (or `mergeable`) against the",
-    "   rebased branch and re-enable auto-merge through the normal flow.",
+    "   ```bash",
+    "   gh pr edit <pr-number> --add-label 'review:needs-worker'",
+    "   ```",
     "",
-    "Return `delegated` to the caller when delegation completes",
-    "(regardless of the worker's outcome \u2014 the delegation itself is the",
-    "action taken).",
+    "5. **Exit returning `delegated`.** The delegation is complete for",
+    "   this pass: the fix-list is posted, the lease is held, and the",
+    "   marker is set. Do **not** wait for the worker, do **not** process",
+    "   a worker report, and do **not** re-enable auto-merge in this pass.",
+    "   The worker runs in its own top-level session; a **subsequent**",
+    "   reviewer pass detects the worker finished (PR carries",
+    "   `review:fixing` but **not** `review:needs-worker`), reacts on the",
+    "   source comment, re-evaluates AC/CI against the rebased branch,",
+    "   re-enables auto-merge, and releases the `review:fixing` lease. See",
+    "   the **Confirm pass** section below.",
+    "",
+    "Return `delegated` to the caller once the marker is applied and the",
+    "fix-list posted \u2014 the delegation itself is the action taken. Unlike a",
+    "merge, `delegated` does **not** imply the fix landed in this pass; it",
+    "means the work is durably queued for the pull-based consumer and a",
+    "later confirm pass will finish the loop.",
     "",
     "### Fallback",
     "",
@@ -18936,6 +19039,89 @@ var prReviewerSubAgent = {
     "gh pr comment <pr-number> --body 'Branch is BEHIND <default-branch> with conflicts. <short reason delegation was skipped \u2014 e.g. human-required mode, generated-file conflicts, or in-flight review:fixing lease>. A human (or the next reviewer pass after rebase) will need to resolve.'",
     "```",
     "",
+    "## Shared Procedure: Confirm a Completed Delegation",
+    "",
+    "Delegation is **pull-based and spans sessions**: the reviewer that",
+    "posts a fix-list never finishes the loop in the same pass. It posts",
+    "the fix-list, acquires the `review:fixing` lease, applies the durable",
+    "`review:needs-worker` marker, and exits returning `delegated`. A",
+    "**separate** top-level `issue-worker` session then discovers the",
+    "marker, applies the fix-list (an editorial fix or a rebase), pushes,",
+    "writes a structured worker-report comment, and **clears**",
+    "`review:needs-worker` \u2014 leaving `review:fixing` in place for the",
+    "reviewer to release. The confirm pass below is how a later reviewer",
+    "pass closes the loop. It runs in **both** delegation flows (the",
+    "Phase 4 in-scope-fix flow and the Shared Conflict-Resolution",
+    "Procedure) \u2014 the marker, not the flow, is what a confirm pass keys",
+    "on.",
+    "",
+    "### Detecting a completed delegation",
+    "",
+    "Early in any reviewer pass (after Phase 2 gathers labels), inspect",
+    "the PR's labels for the **lease-without-marker** state:",
+    "",
+    "- `review:fixing` is **present** (a delegation lease is held), **and**",
+    "- `review:needs-worker` is **absent** (the worker cleared its marker",
+    "  on completion).",
+    "",
+    "When both hold, a delegation the previous pass kicked off has been",
+    "consumed and pushed by the worker. Run the confirm steps below before",
+    "proceeding with the rest of the pass.",
+    "",
+    "When **both** `review:fixing` and `review:needs-worker` are present,",
+    "the delegation is still in flight (the worker has not yet picked it",
+    "up or has not finished). Do **not** re-post the fix-list and do",
+    "**not** re-acquire the lease \u2014 log the in-flight state to the sticky",
+    "summary and exit; a later pass confirms once the worker clears the",
+    "marker.",
+    "",
+    "### Confirm steps",
+    "",
+    "1. **Read the worker's report.** Find the most recent structured",
+    "   worker-report comment the `issue-worker` posted on the PR (it",
+    "   cites the pushed commit SHAs and a per-item `handled` / `failed`",
+    "   outcome keyed by `comment_id`). Use it to drive the reactions",
+    "   below \u2014 the same per-item logic the in-session report processing",
+    "   used to perform.",
+    "2. **React on the source comments.** For each item:",
+    "   - **`handled`** \u2014 react `rocket` on the original source comment",
+    "     (the fix-list comment for a synthetic rebase item) to signal the",
+    "     accepted change has landed.",
+    "   - **`failed`** \u2014 react `thinking_face` (`content=confused`) on the",
+    "     source comment and post a reply citing the worker's failure",
+    "     reason.",
+    "3. **Re-evaluate AC/CI against the rebased branch.** Re-run the Phase",
+    "   3 acceptance-criteria comparison and the **CI Verification** check",
+    "   against the **updated** head SHA the worker pushed \u2014 do not reuse",
+    "   any pre-delegation result.",
+    "4. **Conditionally re-enable auto-merge** under the same four",
+    "   conditions as the in-scope-fix flow's step (h): mode still",
+    "   `auto-merge`, all AC met against the updated diff, no unresolved",
+    "   `thinking_face` pushbacks, and CI green-or-pending.",
+    "5. **Release the `review:fixing` lease** \u2014 always, even when an item",
+    "   failed:",
+    "",
+    "   ```bash",
+    "   gh pr edit <pr-number> --remove-label 'review:fixing'",
+    "   ```",
+    "",
+    "6. **Update the sticky summary** with the per-item outcomes, the",
+    "   commit SHAs from the worker report, and the auto-merge decision.",
+    "",
+    "### Stale-lease reclaim",
+    "",
+    "A crashed worker must not wedge a PR forever. A `review:fixing` lease",
+    "is **reclaimable** when it has no `review:needs-worker` companion",
+    "**and** no consuming worker is making progress \u2014 i.e. the lease is",
+    "older than the stale threshold (the same in-progress threshold the",
+    "maintenance sweep applies, 72h by default) with no worker-report",
+    "comment newer than the fix-list. The reclaim is wired into the",
+    "maintenance sweep, not a reviewer pass: the sweep flags such a PR",
+    "with `status:needs-attention` so a human clears the orphaned",
+    "`review:fixing` lease and re-triggers the reviewer. See the",
+    "**Stale-lease reclaim** subsection of the `pr-review-feedback-protocol`",
+    "rule for the full lifecycle.",
+    "",
     "## Phase 5: Branch Cleanup and Issue Closure Verification",
     "",
     "Skip this phase entirely when the review mode from Phase 2.75 is",
@@ -18999,7 +19185,7 @@ var prReviewerSubAgent = {
     "Linked issue: #<issue-number>",
     "Review mode: <auto-merge | human-required>",
     "Reason: <short explanation from Phase 2.75>",
-    "Verdict: AUTO_MERGE_ENABLED | AWAITING_HUMAN | NEEDS_CHANGES | INELIGIBLE | BLOCKED",
+    "Verdict: AUTO_MERGE_ENABLED | AWAITING_HUMAN | DELEGATED_TO_WORKER | NEEDS_CHANGES | INELIGIBLE | BLOCKED",
     "",
     "Acceptance criteria:",
     "  [x] <criterion> \u2014 <evidence>",
@@ -19011,12 +19197,22 @@ var prReviewerSubAgent = {
     "  - Suggested: <items>",
     "  - Nitpick: <items>",
     "",
-    "Action taken: <enable-auto-merge | label-awaiting-human | commented-on-the-pr | none>",
+    "Action taken: <enable-auto-merge | label-awaiting-human | delegated-to-worker | confirmed-delegation | commented-on-the-pr | none>",
     "Branch updated: <yes | not needed | failed (<reason>) | delegated (PR #<n>) | n/a>",
     "Branch state: <merged | open | closed>",
     "Issue state: <closed | open>",
     "```",
     "",
+    "**`DELEGATED_TO_WORKER` semantics.** This verdict means the reviewer",
+    "posted a fix-list, applied the `review:needs-worker` marker, and",
+    "exited holding the `review:fixing` lease \u2014 the fix-list is **durably",
+    "queued** for a top-level `issue-worker` pass, but it has **not** yet",
+    "been applied in this pass. `delegated` is never a terminal",
+    "completion: the loop closes only when a top-level worker consumes the",
+    "marker and a later reviewer confirm pass releases the lease. Likewise",
+    "`Branch updated: delegated (PR #<n>)` records that a rebase was",
+    "queued for the worker, not that the branch is already current.",
+    "",
     "---",
     "",
     "## Rules",
@@ -19038,7 +19234,7 @@ var prReviewerSubAgent = {
     "   to `human-required`, Phase 4 applies `review:awaiting-human` and",
     "   exits. Even if every acceptance criterion is met and CI is green,",
     "   `gh pr merge --auto` is forbidden in that mode.",
-    "6. **Never push commits to the PR's branch yourself.** The reviewer is a decision-maker and orchestrator, not an implementer. When in-scope review comments require code changes **and** the PR carries the `origin:issue-worker` label (or the invocation prompt explicitly allows human-authored PRs via `--allow-human-author`), delegate the fix by posting a fix-list comment on the PR and invoking `issue-worker` in feedback mode. You must never call `git commit`, `git push`, `git rebase`, or `gh pr edit` against the head branch from this agent \u2014 all branch mutations belong to `issue-worker`.",
+    "6. **Never push commits to the PR's branch yourself.** The reviewer is a decision-maker and orchestrator, not an implementer. When in-scope review comments require code changes **and** the PR carries the `origin:issue-worker` label (or the invocation prompt explicitly allows human-authored PRs via `--allow-human-author`), delegate the fix **by marker, not by spawn**: post a fix-list comment on the PR, apply the `review:needs-worker` label, hold the `review:fixing` lease, and exit returning `delegated`. Do **not** invoke `issue-worker` via the `Agent` tool \u2014 the reviewer often runs at depth-1 where nested sub-agent spawning is forbidden, so an in-session dispatch would silently abort. A top-level `issue-worker` session pulls the marker and applies the fix; a later reviewer confirm pass releases the lease. You must never call `git commit`, `git push`, `git rebase`, or `gh pr edit` against the head branch from this agent \u2014 all branch mutations belong to `issue-worker`.",
     "7. **Do not implement code.** You review, decide, and orchestrate. If",
     "   the PR needs code changes and delegation is not permitted by Rule",
     "   #6, comment and stop \u2014 do not attempt to fix it yourself.",
@@ -19074,15 +19270,21 @@ var prReviewerSubAgent = {
     "    in a way that satisfies the reviewer (who then replaces the",
     "    `thinking_face` with `+1`), or by applying the `review:auto-ok`",
     "    label as an explicit override.",
-    "14. **Never re-enable auto-merge while disputes or human-required",
-    "    hand-offs are still in flight.** After delegating fixes via the",
-    "    Phase 4 flow, the reviewer may only run `gh pr merge --auto`",
-    "    again when **no** unresolved `thinking_face` reactions authored",
-    "    by the reviewer remain on any PR comment **and** the",
-    "    `review:awaiting-human` label is **not** present on the PR. Any",
-    "    AC-drift pushback, any failed-fix pushback, and any human-required",
-    "    hand-off all keep auto-merge disabled until the human resolves",
-    "    the underlying state.",
+    "14. **Never re-enable auto-merge while disputes, human-required",
+    "    hand-offs, or an in-flight delegation are still pending.** The",
+    "    auto-merge re-enable happens on the **confirm pass** (the Shared",
+    "    Procedure: Confirm a Completed Delegation), never on the pass",
+    "    that posts the fix-list. A confirm pass may only run",
+    "    `gh pr merge --auto` when the PR carries `review:fixing` but",
+    "    **not** `review:needs-worker` (the worker finished and cleared",
+    "    its marker), **and** **no** unresolved `thinking_face` reactions",
+    "    authored by the reviewer remain on any PR comment, **and** the",
+    "    `review:awaiting-human` label is **not** present. While",
+    "    `review:needs-worker` is still applied the delegation is",
+    "    unconsumed and auto-merge stays disabled. Any AC-drift pushback,",
+    "    any failed-fix pushback, and any human-required hand-off all keep",
+    "    auto-merge disabled until the human resolves the underlying",
+    "    state.",
     "15. **Restrict `gh pr update-branch` on `human-required` PRs.** The",
     "    `update-branch` step is permitted when the review mode is",
     "    `auto-merge`, **or** when the mode is `human-required` **and**",
@@ -19578,20 +19780,36 @@ function buildPrReviewBundle(policy = resolvePrReviewPolicy()) {
           "PR state. The sections below document the conventions humans need",
           "to read and drive that loop.",
           "",
-          "### Trigger Model: Human-Triggered, Single-Pass",
+          "### Trigger Model: Single-Pass, Pull-Based Delegation",
           "",
           "Each reviewer pass runs exactly once and does not self-chain. A",
-          "human re-invokes `/review-pr <n>` (or `/review-prs`) whenever the",
-          "PR state changes enough to warrant another look \u2014 a new comment,",
-          "a new commit, a resolved pushback, a label flip. The reviewer",
-          "never reschedules itself and never loops back after handing off to",
-          "`issue-worker`: the worker's run is the terminal step of that",
-          "pass, and a human must re-invoke the reviewer to see the follow-up",
-          "reactions and the auto-merge re-enablement decision.",
-          "",
-          "This keeps the loop cheap to reason about: every agent action is",
-          "traceable to a specific human invocation, and there is no",
-          "background automation to pause or cancel.",
+          "human (or a scheduled PR-review sweep) re-invokes",
+          "`/review-pr <n>` (or `/review-prs`) whenever the PR state changes",
+          "enough to warrant another look \u2014 a new comment, a new commit, a",
+          "resolved pushback, a label flip, or a worker clearing the",
+          "`review:needs-worker` marker. The reviewer never reschedules",
+          "itself.",
+          "",
+          "Delegation is **pull-based, not push-based**. The reviewer does",
+          "**not** spawn `issue-worker` in session \u2014 it frequently runs at",
+          "depth-1 (the orchestrator's PR sweep dispatches it as a",
+          "sub-agent), and the runtime forbids a depth-1 sub-agent from",
+          "spawning a depth-2 sub-agent, so an in-session dispatch would",
+          "silently abort. Instead the pass that decides to delegate posts a",
+          "fix-list, applies the durable `review:needs-worker` marker, holds",
+          "the `review:fixing` lease, and exits. A **separate** top-level",
+          "`issue-worker` session discovers the marker, applies the",
+          "fix-list, pushes, writes a worker-report comment, and clears",
+          "`review:needs-worker`. A later reviewer pass then confirms the",
+          "result and releases the lease. The worker's run is therefore",
+          "**not** the terminal step of the delegating reviewer pass \u2014 the",
+          "loop spans three passes (delegate \u2192 worker \u2192 confirm).",
+          "",
+          "This keeps the loop cheap to reason about: every step is",
+          "traceable to a label state on the PR, and the producer",
+          "(`pr-reviewer`, at any depth) never depends on a depth-2",
+          "sub-agent spawn to reach the consumer (`issue-worker`, always",
+          "top-level).",
           "",
           "### Reaction State Machine",
           "",
@@ -19673,6 +19891,60 @@ function buildPrReviewBundle(policy = resolvePrReviewPolicy()) {
           "report per-item outcomes and the reviewer can apply `rocket` or",
           "`thinking_face` to the correct source comment on the next pass.",
           "",
+          "### Cross-Session `review:fixing` Lease Lifecycle",
+          "",
+          "Delegation hand-off is **pull-based and spans three passes**. Two",
+          "labels coordinate it: the `review:fixing` lease (mutual exclusion)",
+          "and the `review:needs-worker` marker (durable work signal). The",
+          "lease is held **across sessions** \u2014 it is acquired by the",
+          "reviewer pass that posts the fix-list and released only by a",
+          "later reviewer confirm pass, never within a single pass.",
+          "",
+          "| Step | Actor | Labels after the step |",
+          "|------|-------|-----------------------|",
+          "| **1. Delegate** | `pr-reviewer` | Posts the fix-list, **acquires** `review:fixing`, **applies** `review:needs-worker`, exits `delegated`. PR carries both labels. |",
+          "| **2. Consume** | `issue-worker` (top-level) | Discovers `review:needs-worker`, applies the fix-list, pushes, writes a worker-report comment, **clears** `review:needs-worker`. PR carries `review:fixing` only. |",
+          "| **3. Confirm** | `pr-reviewer` | Detects `review:fixing` **without** `review:needs-worker`, reacts on source comments from the worker report, re-evaluates AC/CI, re-enables auto-merge (auto-merge mode), **releases** `review:fixing`. PR carries neither label. |",
+          "",
+          "Key invariants:",
+          "",
+          "- The producer (`pr-reviewer`) **never spawns** the consumer",
+          "  (`issue-worker`) in session. The reviewer can run at depth-1,",
+          "  where nested sub-agent spawning is forbidden; the marker is the",
+          "  hand-off, not an `Agent` dispatch.",
+          "- The lease being held while `review:needs-worker` is still",
+          "  present means the delegation is **in flight** \u2014 a reviewer pass",
+          "  that sees both labels logs the in-flight state and exits without",
+          "  re-posting the fix-list or re-acquiring the lease.",
+          "- The lease being held **without** `review:needs-worker` is the",
+          "  **confirm trigger** \u2014 exactly one delegation has been consumed",
+          "  and is awaiting confirmation.",
+          "- `delegated` is never a terminal completion. A PR is only done",
+          "  when the confirm pass releases the lease and (in auto-merge",
+          "  mode) re-enables auto-merge.",
+          "",
+          "#### Stale-lease reclaim",
+          "",
+          "A crashed or never-launched worker must not wedge a PR by holding",
+          "the lease forever. The **maintenance sweep** (not a reviewer pass)",
+          "owns reclaim. A `review:fixing` lease is **reclaimable** when",
+          "**both** hold:",
+          "",
+          "- The PR carries `review:fixing` but **not**",
+          "  `review:needs-worker` \u2014 there is no in-flight worker still",
+          "  expected to clear the marker, **yet**",
+          "- No worker-report comment newer than the fix-list exists, **and**",
+          "  the fix-list comment is older than the stale in-progress",
+          "  threshold the maintenance sweep applies (72h by default).",
+          "",
+          "Together these mean a delegation was kicked off, the marker was",
+          "consumed-or-dropped, but no worker result ever landed \u2014 the lease",
+          "is orphaned. The maintenance sweep flags such a PR with",
+          "`status:needs-attention` so a human clears the orphaned",
+          "`review:fixing` label and re-triggers the reviewer; the sweep",
+          "never silently force-releases the lease, mirroring the",
+          "stale-issue policy of flagging rather than auto-resetting.",
+          "",
           "### Sticky `## Reviewer notes` Comment",
           "",
           "Every PR has **one** canonical reviewer-notes comment. The",
@@ -19704,10 +19976,13 @@ function buildPrReviewBundle(policy = resolvePrReviewPolicy()) {
           "",
           "### Label Glossary",
           "",
-          "Five review-workflow labels drive the feedback loop. Consumers",
-          "that adopt this workflow are responsible for creating them in",
-          "their own repos (the same way they create `priority:*` and",
-          "`status:*` labels).",
+          "Six review-workflow labels drive the feedback loop. They are",
+          "**contributed by the pr-review bundle's label set** and auto-sync",
+          "into every consumer's label registry \u2014 the same way the",
+          "`type:*` / `priority:*` / `status:*` taxonomy ships. Consumers do",
+          "**not** hand-declare them, so they survive a label sync run with",
+          "`deleteOtherLabels: true` that would otherwise prune a",
+          "locally-created label.",
           "",
           "| Label | Purpose |",
           "|-------|---------|",
@@ -19715,7 +19990,8 @@ function buildPrReviewBundle(policy = resolvePrReviewPolicy()) {
           "| `review:human-required` | Force human review regardless of what the policy would otherwise decide. The reviewer never enables auto-merge on a PR carrying this label. |",
           "| `review:auto-ok` | Force auto-merge regardless of what the policy would otherwise decide. **Also resolves outstanding `thinking_face` pushbacks** as an explicit maintainer override; the reviewer logs the override in the sticky summary. |",
           "| `review:awaiting-human` | Set by the reviewer when it completes its work on a `human-required` PR and is handing off the final merge decision. Cleared by a human (or by `review:auto-ok` flipping the PR back to `auto-merge` mode). |",
-          "| `review:fixing` | Short-lived lease held by the reviewer while an `issue-worker` feedback-mode delegation is mid-run. Released automatically at the end of Phase 4 step (g). Contention on this label means a prior delegation crashed without releasing it and needs human investigation. |",
+          "| `review:fixing` | **Cross-session** delegation lease. Acquired by the reviewer pass that posts a fix-list; held across the worker's run; released only by a later reviewer **confirm** pass (PR carries `review:fixing` but not `review:needs-worker`). A lease held without `review:needs-worker` past the stale threshold with no worker report is orphaned and is flagged by the maintenance sweep for human reclaim. |",
+          "| `review:needs-worker` | **Durable hand-off marker.** Applied by the reviewer alongside the fix-list so a top-level `issue-worker` session discovers the PR and pulls the work (the reviewer cannot spawn the worker in session \u2014 it may run at depth-1). Cleared by the worker when it finishes applying the fix-list, which is what triggers the reviewer's confirm pass. |",
           "",
           "### Reviewing Human-Authored PRs: the `--allow-human-author` Flag",
           "",
@@ -19777,7 +20053,12 @@ function buildPrReviewBundle(policy = resolvePrReviewPolicy()) {
       {
         name: "review:fixing",
         color: "D4C5F9",
-        description: "Short-lived lease while issue-worker applies feedback fixes"
+        description: "Cross-session lease held from fix-list post until a confirm pass releases it"
+      },
+      {
+        name: "review:needs-worker",
+        color: "1D76DB",
+        description: "Durable marker: a reviewer fix-list awaits a top-level issue-worker pass"
       }
     ]
   };