@plainconceptsplatform/workflows 0.21.0 → 0.24.0

package/loops/actions/attach-screenshots/action.yml

@@ -0,0 +1,100 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/attach-screenshots/action.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Attach screenshots
+description: Post screenshots captured by agent-browser to the linked issue as a single comment.
+inputs:
+  token:
+    description: GitHub token with issues:write access.
+    required: true
+  issue-number:
+    description: Issue number to comment on.
+    required: true
+  pr-number:
+    description: Pull request number being verified.
+    required: true
+  screenshots-dir:
+    description: Directory containing screenshots and plan.json.
+    required: true
+  screenshot-count:
+    description: Number of screenshots captured (0 if none).
+    required: false
+    default: '0'
+  app-started:
+    description: Whether the app started successfully.
+    required: false
+    default: 'false'
+  enabled:
+    description: Whether visual verification was enabled.
+    required: false
+    default: 'true'
+runs:
+  using: composite
+  steps:
+    - name: Attach screenshots to issue
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+        ISSUE: ${{ inputs.issue-number }}
+        PR: ${{ inputs.pr-number }}
+        SCREENSHOTS_DIR: ${{ inputs.screenshots-dir }}
+        SCREENSHOT_COUNT: ${{ inputs.screenshot-count }}
+        APP_STARTED: ${{ inputs.app-started }}
+        ENABLED: ${{ inputs.enabled }}
+      run: |
+        set -euo pipefail
+
+        if [ "$ENABLED" != "true" ]; then
+          echo "Visual verification disabled; nothing to attach."
+          exit 0
+        fi
+
+        if [ -f "$SCREENSHOTS_DIR/plan.json" ] && [ "$APP_STARTED" = "true" ] && [ "$SCREENSHOT_COUNT" -gt 0 ]; then
+          # Build the comment body from the plan's descriptions.
+          body=$(jq -r --arg pr "$PR" '
+            "<!-- agent-visual-verify -->\n## Visual verification for PR #" + $pr + "\n",
+            (.waypoints | to_entries[] |
+              "**\(.key + 1). " + (.value.description // .value.expect // "waypoint") + "**\n" +
+              "Selector: `" + (.value.selector // "n/a") + "`\n"
+            )
+          ' "$SCREENSHOTS_DIR/plan.json")
+
+          # Collect all screenshot files.
+          attaches=()
+          for png in "$SCREENSHOTS_DIR"/*.png; do
+            [ -f "$png" ] || continue
+            attaches+=("$png")
+          done
+
+          if [ ${#attaches[@]} -gt 0 ]; then
+            gh issue comment "$ISSUE" --repo "$REPO" \
+              --body "attach" \
+              "${attaches[@]/#/--attach=}" \
+              --body-file - <<< "$body" 2>/dev/null || \
+            {
+              # Fallback: gh CLI does not support --body-file with --attach in all versions.
+              # Post the body as the comment and attach each screenshot individually.
+              gh issue comment "$ISSUE" --repo "$REPO" --body "$body"
+              for png in "${attaches[@]}"; do
+                gh issue comment "$ISSUE" --repo "$REPO" --attach "$png" --body ""
+              done
+            }
+            echo "Attached ${#attaches[@]} screenshots to issue #$ISSUE"
+          else
+            gh issue comment "$ISSUE" --repo "$REPO" --body "$body"
+            echo "No screenshots found; posted plan summary only"
+          fi
+        else
+          # App didn't start or no plan was produced. Post a warning.
+          reason="visual verification could not produce screenshots"
+          if [ "$APP_STARTED" != "true" ]; then
+            reason="$reason (app did not start)"
+          elif [ ! -f "$SCREENSHOTS_DIR/plan.json" ]; then
+            reason="$reason (no verification plan was written)"
+          fi
+
+          gh issue comment "$ISSUE" --repo "$REPO" --body \
+            "<!-- agent-visual-verify -->## Visual verification for PR #$PR
+
+⚠ $reason. The merge proceeds without visual evidence."
+          echo "Posted warning: $reason"
+        fi

package/loops/actions/classify-route/action.yml

@@ -1,100 +1,100 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/actions/classify-route/action.yml. Update with workflows update --force; consumer edits may be overwritten.
-name: Classify route
-description: Classify the triggering event into exactly one route, and resolve the issue a gated pull request closes.
-inputs:
-  token:
-    description: GitHub token with pull-requests read access.
-    required: true
-outputs:
-  route:
-    description: The single route this event selects, or `none`.
-    value: ${{ steps.classify.outputs.route }}
-  issue-number:
-    description: Issue number the route operates on.
-    value: ${{ steps.classify.outputs.issue-number }}
-  pr-number:
-    description: Pull request number the route operates on.
-    value: ${{ steps.classify.outputs.pr-number }}
-  linked-issue:
-    description: Issue the pull request closes. Empty for routes that do not target one.
-    value: ${{ steps.linked-issue.outputs.issue }}
-  ci-conclusion:
-    description: Conclusion reported by the CI run that triggered a merge-gate route.
-    value: ${{ steps.classify.outputs.ci-conclusion }}
-  ci-run-id:
-    description: Workflow run ID of that CI run.
-    value: ${{ steps.classify.outputs.ci-run-id }}
-  merge-gate-attempts:
-    description: Failed merge-gate attempts already made against this CI verdict.
-    value: ${{ steps.classify.outputs.merge-gate-attempts }}
-  implement-attempts:
-    description: Implement runs already made for this issue that died before producing an answer.
-    value: ${{ steps.classify.outputs.implement-attempts }}
-  refine-mode:
-    description: first or rerefine.
-    value: ${{ steps.classify.outputs.refine-mode }}
-  triage-mode:
-    description: first or retriage.
-    value: ${{ steps.classify.outputs.triage-mode }}
-  trigger-kind:
-    description: scheduled or manual.
-    value: ${{ steps.classify.outputs.trigger-kind }}
-runs:
-  using: composite
-  steps:
-    - name: Classify the event
-      id: classify
-      shell: bash
-      env:
-        EVENT: ${{ github.event_name }}
-        ACTION: ${{ github.event.action }}
-        LABEL: ${{ github.event.label.name }}
-        ISSUE_LABELS: ${{ toJSON(github.event.issue.labels.*.name) }}
-        ISSUE_STATE: ${{ github.event.issue.state }}
-        EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
-        EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
-        COMMENT_ON_PR: ${{ github.event.issue.pull_request != '' }}
-        COMMENT_SENDER_TYPE: ${{ github.event.comment.user.type }}
-        ACTOR: ${{ github.actor }}
-        RUN_PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}
-        RUN_CONCLUSION: ${{ github.event.workflow_run.conclusion }}
-        RUN_ID: ${{ github.event.workflow_run.id }}
-        SCHEDULE: ${{ github.event.schedule }}
-        OPERATION: ${{ github.event.inputs.operation }}
-        INPUT_ISSUE_NUMBER: ${{ github.event.inputs.issue-number }}
-        INPUT_PR_NUMBER: ${{ github.event.inputs.pr-number }}
-        INPUT_MODE: ${{ github.event.inputs.mode }}
-        INPUT_CI_CONCLUSION: ${{ github.event.inputs.ci-conclusion }}
-        INPUT_CI_RUN_ID: ${{ github.event.inputs.ci-run-id }}
-        INPUT_ATTEMPTS_SO_FAR: ${{ github.event.inputs.attempts_so_far }}
-        INPUT_TRIGGER_KIND: ${{ github.event.inputs.trigger-kind }}
-      run: |
-        set -euo pipefail
-
-        bash "${GITHUB_ACTION_PATH}/classify-route.sh" | tee "$RUNNER_TEMP/route.env"
-        cat "$RUNNER_TEMP/route.env" >> "$GITHUB_OUTPUT"
-
-        route="$(sed -n 's/^route=//p' "$RUNNER_TEMP/route.env")"
-        reason="$(sed -n 's/^error=//p' "$RUNNER_TEMP/route.env")"
-
-        if [ "$route" = "none" ] && [ -n "$reason" ]; then
-          echo "::notice::No route for this event: $reason"
-        fi
-
-    - name: Resolve the issue the pull request closes
-      id: linked-issue
-      if: steps.classify.outputs.route == 'merge-gate' || steps.classify.outputs.route == 'apply-review'
-      shell: bash
-      env:
-        GH_TOKEN: ${{ inputs.token }}
-        REPO: ${{ github.repository }}
-        PR_NUMBER: ${{ steps.classify.outputs.pr-number }}
-      run: |
-        set -euo pipefail
-
-        issue="$(gh pr view "$PR_NUMBER" --repo "$REPO" \
-          --json closingIssuesReferences \
-          --jq '.closingIssuesReferences[0].number // empty')"
-
-        echo "issue=${issue}" >> "$GITHUB_OUTPUT"
-        echo "Pull request #${PR_NUMBER} closes issue #${issue:-<none>}"
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/classify-route/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Classify route
+description: Classify the triggering event into exactly one route, and resolve the issue a gated pull request closes.
+inputs:
+  token:
+    description: GitHub token with pull-requests read access.
+    required: true
+outputs:
+  route:
+    description: The single route this event selects, or `none`.
+    value: ${{ steps.classify.outputs.route }}
+  issue-number:
+    description: Issue number the route operates on.
+    value: ${{ steps.classify.outputs.issue-number }}
+  pr-number:
+    description: Pull request number the route operates on.
+    value: ${{ steps.classify.outputs.pr-number }}
+  linked-issue:
+    description: Issue the pull request closes. Empty for routes that do not target one.
+    value: ${{ steps.linked-issue.outputs.issue }}
+  ci-conclusion:
+    description: Conclusion reported by the CI run that triggered a merge-gate route.
+    value: ${{ steps.classify.outputs.ci-conclusion }}
+  ci-run-id:
+    description: Workflow run ID of that CI run.
+    value: ${{ steps.classify.outputs.ci-run-id }}
+  merge-gate-attempts:
+    description: Failed merge-gate attempts already made against this CI verdict.
+    value: ${{ steps.classify.outputs.merge-gate-attempts }}
+  attempts:
+    description: Runs already made for this piece of work that died before producing an answer. Carried by every worker that re-dispatches itself, so the budget is bounded.
+    value: ${{ steps.classify.outputs.attempts }}
+  refine-mode:
+    description: first or rerefine.
+    value: ${{ steps.classify.outputs.refine-mode }}
+  triage-mode:
+    description: first or retriage.
+    value: ${{ steps.classify.outputs.triage-mode }}
+  trigger-kind:
+    description: scheduled or manual.
+    value: ${{ steps.classify.outputs.trigger-kind }}
+runs:
+  using: composite
+  steps:
+    - name: Classify the event
+      id: classify
+      shell: bash
+      env:
+        EVENT: ${{ github.event_name }}
+        ACTION: ${{ github.event.action }}
+        LABEL: ${{ github.event.label.name }}
+        ISSUE_LABELS: ${{ toJSON(github.event.issue.labels.*.name) }}
+        ISSUE_STATE: ${{ github.event.issue.state }}
+        EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+        EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
+        COMMENT_ON_PR: ${{ github.event.issue.pull_request != '' }}
+        COMMENT_SENDER_TYPE: ${{ github.event.comment.user.type }}
+        ACTOR: ${{ github.actor }}
+        RUN_PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}
+        RUN_CONCLUSION: ${{ github.event.workflow_run.conclusion }}
+        RUN_ID: ${{ github.event.workflow_run.id }}
+        SCHEDULE: ${{ github.event.schedule }}
+        OPERATION: ${{ github.event.inputs.operation }}
+        INPUT_ISSUE_NUMBER: ${{ github.event.inputs.issue-number }}
+        INPUT_PR_NUMBER: ${{ github.event.inputs.pr-number }}
+        INPUT_MODE: ${{ github.event.inputs.mode }}
+        INPUT_CI_CONCLUSION: ${{ github.event.inputs.ci-conclusion }}
+        INPUT_CI_RUN_ID: ${{ github.event.inputs.ci-run-id }}
+        INPUT_ATTEMPTS_SO_FAR: ${{ github.event.inputs.attempts_so_far }}
+        INPUT_TRIGGER_KIND: ${{ github.event.inputs.trigger-kind }}
+      run: |
+        set -euo pipefail
+
+        bash "${GITHUB_ACTION_PATH}/classify-route.sh" | tee "$RUNNER_TEMP/route.env"
+        cat "$RUNNER_TEMP/route.env" >> "$GITHUB_OUTPUT"
+
+        route="$(sed -n 's/^route=//p' "$RUNNER_TEMP/route.env")"
+        reason="$(sed -n 's/^error=//p' "$RUNNER_TEMP/route.env")"
+
+        if [ "$route" = "none" ] && [ -n "$reason" ]; then
+          echo "::notice::No route for this event: $reason"
+        fi
+
+    - name: Resolve the issue the pull request closes
+      id: linked-issue
+      if: steps.classify.outputs.route == 'merge-gate' || steps.classify.outputs.route == 'apply-review'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+        PR_NUMBER: ${{ steps.classify.outputs.pr-number }}
+      run: |
+        set -euo pipefail
+
+        issue="$(gh pr view "$PR_NUMBER" --repo "$REPO" \
+          --json closingIssuesReferences \
+          --jq '.closingIssuesReferences[0].number // empty')"
+
+        echo "issue=${issue}" >> "$GITHUB_OUTPUT"
+        echo "Pull request #${PR_NUMBER} closes issue #${issue:-<none>}"

package/loops/actions/classify-route/classify-route.sh

@@ -28,7 +28,7 @@ is_issue_number() {
 
 classify_route() {
   local route="none" error=""
-  local issue_number="" pr_number="" ci_conclusion="" ci_run_id="" merge_gate_attempts="0" implement_attempts="0"
+  local issue_number="" pr_number="" ci_conclusion="" ci_run_id="" merge_gate_attempts="0" attempts="0"
   local refine_mode="" triage_mode="" trigger_kind=""
 
   case "${EVENT:-}" in
@@ -190,13 +190,12 @@ classify_route() {
           if is_issue_number "${INPUT_ISSUE_NUMBER:-}"; then
             route="${OPERATION}"
             issue_number="${INPUT_ISSUE_NUMBER}"
-            if [ "$OPERATION" = "refine" ]; then
-              refine_mode="${INPUT_MODE:-first}"
-            else
-              # The implement worker re-dispatches itself when a run dies before doing any work,
-              # and carries the count so the budget is bounded.
-              implement_attempts="${INPUT_ATTEMPTS_SO_FAR:-0}"
-            fi
+            # Both, not one or the other. A worker re-dispatches itself when a run dies before
+            # doing any work and carries the count so the budget is bounded; refine also carries
+            # the mode it was started in. Written as an if/else, a refine retry arrived as attempt
+            # zero every time and could never reach the park.
+            [ "$OPERATION" = "refine" ] && refine_mode="${INPUT_MODE:-first}"
+            attempts="${INPUT_ATTEMPTS_SO_FAR:-0}"
           else
             error="operation '${OPERATION}' needs a positive issue-number, got '${INPUT_ISSUE_NUMBER:-}'"
           fi
@@ -206,6 +205,7 @@ classify_route() {
             route="triage"
             issue_number="${INPUT_ISSUE_NUMBER}"
             triage_mode="${INPUT_MODE:-first}"
+            attempts="${INPUT_ATTEMPTS_SO_FAR:-0}"
           else
             error="operation 'triage' needs a positive issue-number, got '${INPUT_ISSUE_NUMBER:-}'"
           fi
@@ -214,6 +214,7 @@ classify_route() {
           if is_issue_number "${INPUT_PR_NUMBER:-}"; then
             route="apply-review"
             pr_number="${INPUT_PR_NUMBER}"
+            attempts="${INPUT_ATTEMPTS_SO_FAR:-0}"
           else
             error="operation 'apply-review' needs a positive pr-number, got '${INPUT_PR_NUMBER:-}'"
           fi
@@ -257,7 +258,7 @@ pr-number=${pr_number}
 ci-conclusion=${ci_conclusion}
 ci-run-id=${ci_run_id}
 merge-gate-attempts=${merge_gate_attempts}
-implement-attempts=${implement_attempts}
+attempts=${attempts}
 refine-mode=${refine_mode}
 triage-mode=${triage_mode}
 trigger-kind=${trigger_kind}

package/loops/actions/decide-agent-retry/action.yml

@@ -0,0 +1,72 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/decide-agent-retry/action.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Decide agent retry
+description: Say whether an agent job that failed is worth running again, from how long it ran and how many attempts have been made.
+inputs:
+  token:
+    description: GitHub token with actions read access, used to read this run's own jobs.
+    required: true
+  attempts-so-far:
+    description: Attempts already made against this piece of work. Empty counts as none.
+    required: false
+    default: '0'
+  park-at:
+    description: Stop retrying once this many attempts have been made.
+    required: true
+  under-minutes:
+    description: Only a run shorter than this is repeated.
+    required: true
+outputs:
+  retry:
+    description: '"true" when this failure is worth repeating.'
+    value: ${{ steps.decide.outputs.retry }}
+  next:
+    description: The attempt number a retry would be.
+    value: ${{ steps.decide.outputs.next }}
+  minutes:
+    description: How long the agent job ran, or -1 when that could not be read.
+    value: ${{ steps.decide.outputs.minutes }}
+runs:
+  using: composite
+  steps:
+    # A run that died in three minutes produced no answer, so repeating it costs three minutes. A
+    # run that worked for half an hour and then failed produced an answer that was wrong, and
+    # repeating it buys the same wrong answer half an hour later. Duration is what separates them,
+    # and it needs no model and no log parsing to read.
+    #
+    # Written once here because the rule was in the implement worker alone, and refine, triage and
+    # apply-review parked instead -- an Odyssey refine died in three minutes on
+    # `Model 'glm-5-3' not found`, a gateway fault that clears in seconds, and waited on the
+    # janitor's six-hourly sweep. Five copies of sixty lines is how one rule becomes five.
+    - name: Decide whether this failure is worth repeating
+      id: decide
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+        RUN_ID: ${{ github.run_id }}
+        ATTEMPTS: ${{ inputs.attempts-so-far }}
+        PARK_AT: ${{ inputs.park-at }}
+        UNDER_MINUTES: ${{ inputs.under-minutes }}
+      run: |
+        set -euo pipefail
+        # The agent job belongs to this same run: a called workflow shares the caller's run id.
+        read -r started finished <<<"$(gh api "repos/$REPO/actions/runs/$RUN_ID/jobs?per_page=100" \
+          --jq '[.jobs[] | select(.name | endswith("agent"))] | last // empty
+                | "\(.started_at // "") \(.completed_at // "")"')"
+        minutes=-1
+        if [ -n "${started:-}" ] && [ -n "${finished:-}" ]; then
+          minutes=$(( ( $(date -u -d "$finished" +%s) - $(date -u -d "$started" +%s) ) / 60 ))
+        fi
+        attempts="${ATTEMPTS:-0}"
+        [ -n "$attempts" ] || attempts=0
+        retry=false
+        # An unknown duration is treated as a long run: never retry on a guess.
+        if [ "$minutes" -ge 0 ] && [ "$minutes" -lt "$UNDER_MINUTES" ] && [ "$attempts" -lt "$PARK_AT" ]; then
+          retry=true
+        fi
+        {
+          echo "retry=$retry"
+          echo "next=$((attempts + 1))"
+          echo "minutes=$minutes"
+        } >> "$GITHUB_OUTPUT"
+        echo "agent job ran for ${minutes}m; attempts so far ${attempts}; retry=${retry}"

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -240,14 +240,14 @@ assert "merge-gate dispatch defaults its attempt count to zero" 0 \
   "$(route_field merge-gate-attempts EVENT=workflow_dispatch OPERATION=merge-gate INPUT_PR_NUMBER=7)"
 assert "merge-gate dispatch forwards the attempt count" 3 \
   "$(route_field merge-gate-attempts EVENT=workflow_dispatch OPERATION=merge-gate INPUT_PR_NUMBER=7 INPUT_ATTEMPTS_SO_FAR=3)"
-# The implement worker re-dispatches itself when a run dies before producing an answer, so the
-# count has to survive the round trip or the budget never advances and the retry never stops.
-assert "implement dispatch defaults its attempt count to zero" 0 \
-  "$(route_field implement-attempts EVENT=workflow_dispatch OPERATION=implement INPUT_ISSUE_NUMBER=42)"
+# A worker re-dispatches itself when a run dies before producing an answer, so the count has to
+# survive the round trip or the budget never advances and the retry never stops. The field is
+# `attempts` for every route now: it was `implement-attempts`, set in the else-branch of a test
+# on refine, so a refine retry arrived as attempt zero and could never reach the park.
+assert "a dispatch defaults its attempt count to zero" 0 \
+  "$(route_field attempts EVENT=workflow_dispatch OPERATION=implement INPUT_ISSUE_NUMBER=42)"
 assert "implement dispatch forwards the attempt count" 2 \
-  "$(route_field implement-attempts EVENT=workflow_dispatch OPERATION=implement INPUT_ISSUE_NUMBER=42 INPUT_ATTEMPTS_SO_FAR=2)"
-assert "a refine dispatch carries no implement attempts" 0 \
-  "$(route_field implement-attempts EVENT=workflow_dispatch OPERATION=refine INPUT_ISSUE_NUMBER=42 INPUT_ATTEMPTS_SO_FAR=2)"
+  "$(route_field attempts EVENT=workflow_dispatch OPERATION=implement INPUT_ISSUE_NUMBER=42 INPUT_ATTEMPTS_SO_FAR=2)"
 assert_route "release dispatch needs no numbers" release \
   EVENT=workflow_dispatch OPERATION=release
 assert_route "reconcile-bot-pr-runs dispatch needs no numbers" reconcile-bot-pr-runs \
@@ -1522,6 +1522,14 @@ if [ -f "$GATE_VALIDATOR" ] && worker_installed merge-gate; then
   gate_case "remediated with two pushes"         invalid    "$(gate_items "$(gate_comment remediated),${gate_push},${gate_push}")" failure low
   gate_case "an assessment carrying a push"      invalid    "$(gate_items "$(gate_comment assessed),${gate_push}")" success low
 
+  # Correctness remediation: the agent found the diff does not satisfy the acceptance
+  # criteria, pushed a fix, and emitted remediated. The validator treats this the same as a
+  # CI-failure or conflict remediation -- one push and the remediated word -- regardless of
+  # what acceptanceCriteriaMet says in the report. The next gate cycle re-evaluates the fix.
+  gate_unmet_remedied='{\"findings\":[{\"verified\":false,\"severity\":\"medium\",\"category\":\"correctness\",\"file\":\"src/app.ts\",\"line\":42,\"finding\":\"criterion X not implemented\"}],\"recoverability\":\"high\",\"acceptanceCriteriaMet\":false,\"confidence\":0.9}'
+  gate_case "remediated for unmet acceptance criteria" \
+                                                 remediated  "$(gate_items "$(gate_comment remediated "$gate_unmet_remedied"),${gate_push}")" success low
+
   # Output from a worker version that predates the disposition table. Applying its vocabulary
   # would merge on a word this validator no longer means the same thing by.
   gate_case "the old merge vocabulary is refused"  invalid  '{"items":[{"type":"add_comment","item_number":7,"body":"<!-- agent-merge-gate -->\\n**Verdict:** merge"}]}' success low
@@ -1644,6 +1652,44 @@ if worker_installed merge-gate; then
   if [ "$GATE_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+echo "── Visual verify wiring ───────────────────────────────────────────────────"
+
+# The merge-gate's conclude job dispatches agent-visual-verify before merging when the outcome
+# is auto-merge and VISUAL_VERIFY_ENABLED is true. Each of these is one line an edit could drop
+# with nothing going red: a missing dispatch step, a missing env var, or a missing worker file.
+if worker_installed merge-gate; then
+  VV_OK=1
+
+  vv() {
+    grep -qE "$1" "$2" || { VV_OK=0; echo "FAIL: $3" >&2; }
+  }
+
+  # The dispatch step exists and runs only on auto-merge with the feature flag on.
+  vv 'name: Run visual verification' "$MERGE_GATE_WORKER_MD" 'merge-gate has no visual-verify dispatch step'
+  vv "outcome == 'auto-merge'.*VISUAL_VERIFY_ENABLED == 'true'" "$MERGE_GATE_WORKER_MD" 'visual-verify dispatch has wrong guard'
+  vv 'continue-on-error: true' "$MERGE_GATE_WORKER_MD" 'visual-verify dispatch must not block the merge'
+
+  # The env vars the worker needs.
+  vv 'VISUAL_VERIFY_ENABLED:' "$MERGE_GATE_WORKER_MD" 'merge-gate missing VISUAL_VERIFY_ENABLED env var'
+  vv 'VISUAL_VERIFY_START_COMMAND:' "$MERGE_GATE_WORKER_MD" 'merge-gate missing VISUAL_VERIFY_START_COMMAND env var'
+
+  # The worker file exists.
+  VV_WORKER_MD="${WORKFLOWS_DIR}/agent-visual-verify.md"
+  if [ ! -f "$VV_WORKER_MD" ]; then
+    VV_OK=0
+    echo "FAIL: agent-visual-verify.md does not exist" >&2
+  fi
+
+  # The attach-screenshots action exists.
+  VV_ATTACH="${HERE}/../attach-screenshots/action.yml"
+  if [ ! -f "$VV_ATTACH" ]; then
+    VV_OK=0
+    echo "FAIL: attach-screenshots/action.yml does not exist" >&2
+  fi
+
+  if [ "$VV_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
 echo "── Expression functions ──────────────────────────────────────────────────"
 
 # GitHub's expression language has eleven functions and no more. There is no `split()`, no
@@ -1940,6 +1986,69 @@ if worker_installed audit; then
   if [ "$AUDIT_EMPTY_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+echo "── Retrying a run that died early ────────────────────────────────────────"
+
+# A run that died before producing anything is worth repeating; one that worked and then failed
+# produced an answer that was wrong, and repeating it buys the same wrong answer later. Only the
+# implement worker knew that. An Odyssey refine died in three minutes on `Model 'glm-5-3' not
+# found` -- a gateway fault that clears in seconds -- parked, and waited on the janitor's
+# six-hourly sweep.
+RETRY_OK=1
+for route in refine implement triage apply-review; do
+  worker_md="${WORKFLOWS_DIR}/agent-${route}.md"
+  [ -f "$worker_md" ] || continue
+
+  # Both halves. A worker with only the park is the state this fixes; one with only the retry
+  # never stops trying.
+  if [ "$(count -cE "^ *if:.*steps\.decide\.outputs\.retry == 'true'" "$worker_md")" -eq 0 ] ||
+     [ "$(count -cE "^ *if:.*steps\.decide\.outputs\.retry != 'true'" "$worker_md")" -eq 0 ]; then
+    RETRY_OK=0
+    echo "FAIL: agent-${route} does not have both a retry and a park path, so an early failure either never repeats or never stops" >&2
+  fi
+
+  # Each worker re-dispatches its own route. `-f operation=implement` pasted into refine produces
+  # a plausible run doing the wrong work, and nothing anywhere goes red.
+  # Only the retry dispatch: it is the line that also carries the attempt count. implement
+  # dispatches reconcile-bot-pr-runs too, after it opens a pull request, and that is not a retry.
+  # Only the retry dispatch: it is the line that also carries the attempt count. implement
+  # dispatches reconcile-bot-pr-runs too, after it opens a pull request, and that is not a retry.
+  #
+  # Both greps go through `count`. A worker with no retry dispatch matches nothing, grep exits 1,
+  # and under `set -o pipefail` that killed the whole suite after printing the failure above it --
+  # the tally never ran, so a mutation that removed a retry branch looked like it had been caught
+  # when in fact nothing after it had been checked.
+  dispatched=$(count -E 'operation=[a-z-]+.*attempts_so_far' "$worker_md" \
+    | { count -oE 'operation=[a-z-]+' || true; } | sed 's/operation=//' | sort -u | tr '\n' ' ')
+  dispatched="${dispatched% }"
+  if [ -n "$dispatched" ] && [ "$dispatched" != "$route" ]; then
+    RETRY_OK=0
+    echo "FAIL: agent-${route} re-dispatches '${dispatched}' rather than its own route; that run would do the wrong work and still look healthy" >&2
+  fi
+
+  # The count has to survive the round trip or the park is never reached.
+  if ! grep -qE '^      attempts_so_far:' "$worker_md"; then
+    RETRY_OK=0
+    echo "FAIL: agent-${route} does not take attempts_so_far, so every retry arrives as the first and the budget never binds" >&2
+  fi
+  if [ "$(count -cF 'attempts_so_far: ${{ needs.classify.outputs.attempts }}' "$ROUTER_YML")" -eq 0 ]; then
+    RETRY_OK=0
+    echo "FAIL: the router does not pass classify's attempts to its workers" >&2
+  fi
+done
+
+# The classifier carries the count for every dispatched route. refine needs its mode *and* its
+# count: written as an if/else, a refine retry arrived as attempt zero every time.
+for op in refine implement triage; do
+  got=$(route_field attempts EVENT=workflow_dispatch OPERATION="$op" INPUT_ISSUE_NUMBER=42 INPUT_ATTEMPTS_SO_FAR=3)
+  assert "a dispatched ${op} carries its attempt count" 3 "$got"
+done
+assert "a dispatched apply-review carries its attempt count" 3 \
+  "$(route_field attempts EVENT=workflow_dispatch OPERATION=apply-review INPUT_PR_NUMBER=9 INPUT_ATTEMPTS_SO_FAR=3)"
+assert "a dispatched refine still carries its mode alongside the count" rerefine \
+  "$(route_field refine-mode EVENT=workflow_dispatch OPERATION=refine INPUT_ISSUE_NUMBER=42 INPUT_MODE=rerefine INPUT_ATTEMPTS_SO_FAR=3)"
+
+if [ "$RETRY_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
 echo "── Ways a run ends with nothing ──────────────────────────────────────────"
 
 # A run can end without a pull request in five ways and they need different answers. One sentence