fix(scheduler): fail after summarized action errors

.github/workflows/pr-review-merge-scheduler.yml

@@ -889,8 +889,12 @@ jobs:
               # PR_REVIEW_MERGE_TOKEN does not cover it. The automation can never
               # merge those PRs regardless, so this is a skipped, non-fatal
               # "unavailable" repository, not a failure the sweep can act on. Any
-              # other non-zero exit is a genuine per-repository failure.
-              if printf '%s' "$sweep_output" | grep -qF "Resource not accessible by integration"; then
+              # other non-zero exit is a genuine per-repository failure. A
+              # versioned scheduler payload proves the repository was readable
+              # and the failure was an attempted per-PR action, even when that
+              # action's API error contains the same 403 wording.
+              if printf '%s' "$sweep_output" | grep -qF "Resource not accessible by integration" &&
+                ! printf '%s' "$sweep_output" | grep -qF '"schema_version": "pr-review-merge-scheduler/v2"'; then
                 echo "::warning::Skipping ${repo_full_name}: the sweep credential lacks access (HTTP 403 Resource not accessible by integration). Install the OpenCode app on this repository or grant PR_REVIEW_MERGE_TOKEN access to include it in the sweep."
                 unavailable=$((unavailable + 1))
                 unavailable_repos+=("$repo_full_name")

CHANGELOG.md

@@ -35,10 +35,14 @@ Semantic Versioning where the repository publishes a release.
 
 ### Fixed
 
-- Parsed `opencode.jsonc` as JSONC (stripping `//` and `/* */` comments outside string literals) in the reasoning-effort guard and its contract tests, instead of raw `json.loads`, which rejected the file the moment it carried its first explanatory comment (added for the `contextual-orchestrator` provider block) with `Expecting property name enclosed in double quotes`. Comment markers inside string values, such as the `$schema` URL, are left untouched.
-- Download the pinned `uv` 0.12.1 exporter from the official GitHub Releases URL instead of `releases.astral.sh`, which now returns HTTP 403 and blocks org-wide OpenCode `coverage-evidence`. The SHA-256 pin is unchanged. The opener may follow one hop onto `release-assets.githubusercontent.com` or `objects.githubusercontent.com` and still rejects every other host, userinfo, non-HTTPS scheme, and nondefault port (ContextualWisdomLab/.github#1109).
-- Compared the trusted `uv` executable's post-install `--version` output against the real GitHub Releases build's full string, `uv 0.12.1 (x86_64-unknown-linux-gnu)`, instead of the bare `uv 0.12.1` the prior check required; the genuine release binary always prints the target triple, so every installation was failing the pin check immediately after the archive download itself was fixed (ContextualWisdomLab/.github#1109).
-- Excluded relative `-r` and `--requirement` referrers from generated flat base-lock publication while retaining bounded include syntax diagnostics and discovering independently complete direct `.txt` children of `requirements` directories.
+ - Parsed `opencode.jsonc` as JSONC (stripping `//` and `/* */` comments outside string literals) in the reasoning-effort guard and its contract tests, instead of raw `json.loads`, which rejected the file the moment it carried its first explanatory comment (added for the `contextual-orchestrator` provider block) with `Expecting property name enclosed in double quotes`. Comment markers inside string values, such as the `$schema` URL, are left untouched.
+ - Download the pinned `uv` 0.12.1 exporter from the official GitHub Releases URL instead of `releases.astral.sh`, which now returns HTTP 403 and blocks org-wide OpenCode `coverage-evidence`. The SHA-256 pin is unchanged. The opener may follow one hop onto `release-assets.githubusercontent.com` or `objects.githubusercontent.com` and still rejects every other host, userinfo, non-HTTPS scheme, and nondefault port (ContextualWisdomLab/.github#1109).
+ - Compared the trusted `uv` executable's post-install `--version` output against the real GitHub Releases build's full string, `uv 0.12.1 (x86_64-unknown-linux-gnu)`, instead of the bare `uv 0.12.1` the prior check required; the genuine release binary always prints the target triple, so every installation was failing the pin check immediately after the archive download itself was fixed (ContextualWisdomLab/.github#1109).
+ - Excluded relative `-r` and `--requirement` referrers from generated flat base-lock publication while retaining bounded include syntax diagnostics and discovering independently complete direct `.txt` children of `requirements` directories.
+ - Made pull-request scheduler mutation and dispatch failures fail the targeted workflow and organization sweep after the complete structured decision summary is emitted, while ordinary policy waits remain successful.
+ - Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context.
+ - Made pull-request scheduler mutation and dispatch failures fail the targeted workflow and organization sweep after the complete structured decision summary is emitted, while ordinary policy waits remain successful.
+ - Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context.
 - Refused a conflict-scope repository root whose immediate parent is a symbolic link, so a swapped parent cannot redirect the canonical worktree after the last-component check (CWE-367).
 - Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context.
 - Bounded the Strix quality self-test's deterministic timeout fixtures to 3-second process and 5-second fake-sleep budgets so exact-head policy evidence completes inside the existing job limit without changing production Strix scanner timeouts, providers, credentials, or review semantics.

docs/doctoring/pr-review-merge-scheduler.md

@@ -0,0 +1,34 @@
+# PR review and merge scheduler
+
+## Terminal result policy
+
+The scheduler isolates a failed mutation or dispatch to its pull request and
+continues the bounded scan. It emits the human-readable lines, job summary, and
+versioned JSON decision payload for every inspected pull request before choosing
+the process result.
+
+An `action_error` is a material execution failure, so one or more such decisions
+produce a non-zero terminal result after the summary is written. Policy outcomes
+such as `wait`, `block`, `skip`, and deferred capacity do not make an otherwise
+healthy scheduler invocation fail.
+
+A targeted single-pull-request run and the organization sweep use the same
+terminal policy. The organization sweep preserves each repository's captured
+summary, records that repository as failed, finishes its bounded repository
+walk, and then fails the job. A repository is classified as unavailable only
+when the scheduler fails before emitting its versioned structured payload and
+the error proves that the sweep credential cannot read the repository.
+
+This separation keeps ordinary governance waits visible without reporting them
+as incidents, while preventing a failed merge, update, auto-merge, or review
+dispatch from producing a passing workflow result.
+
+## References (APA 7th)
+
+GitHub. (n.d.). *Workflow commands for GitHub Actions*. GitHub Docs. Retrieved
+August 16, 2026, from
+https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands-for-github-actions
+
+GitHub. (n.d.). *Workflow syntax for GitHub Actions*. GitHub Docs. Retrieved
+August 16, 2026, from
+https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax

scripts/ci/pr_review_merge_scheduler.py

@@ -2787,6 +2787,17 @@ def print_summary(
     )
 
 
+def scheduler_exit_code(decisions: list[Decision]) -> int:
+    """Return failure after a complete scan when a requested action failed.
+
+    Ordinary policy outcomes remain successful scheduler executions.  A caught
+    ``action_error`` is different: the scheduler attempted a mutation or
+    dispatch and could not complete it.  The caller must receive that failure
+    only after :func:`print_summary` has preserved every per-PR decision.
+    """
+    return 1 if any(decision.action == "action_error" for decision in decisions) else 0
+
+
 def markdown_cell(value: object) -> str:
     """Escape a value for a compact GitHub Actions summary table cell."""
     return str(value).replace("|", "\\|").replace("\n", "<br>")
@@ -3805,7 +3816,7 @@ def main(argv: list[str]) -> int:
         base_branch=args.base_branch,
         project_flow=args.project_flow,
     )
-    return 0
+    return scheduler_exit_code(decisions)
 
 
 if __name__ == "__main__":  # pragma: no cover

tests/test_pr_review_merge_scheduler.py

@@ -4527,7 +4527,7 @@ def fake_inspect(repo, pr, **kwargs):
     monkeypatch.setattr(sched, "fetch_open_prs", lambda repo, max_prs: prs)
     monkeypatch.setattr(sched, "inspect_pr", fake_inspect)
 
-    assert sched.main(["--repo", "owner/repo", "--base-branch", "main", "--project-flow", "github"]) == 0
+    assert sched.main(["--repo", "owner/repo", "--base-branch", "main", "--project-flow", "github"]) == 1
     assert seen == [1, 2]
     output = capsys.readouterr().out
     assert "PR #1: action_error: Command failed (1): gh pr merge 1; GraphQL: Resource not accessible by integration" in output
@@ -4616,7 +4616,7 @@ def fake_inspect(repo, pr, **kwargs):
     monkeypatch.setattr(sched, "fetch_open_prs", lambda repo, max_prs: prs)
     monkeypatch.setattr(sched, "inspect_pr", fake_inspect)
 
-    assert sched.main(["--repo", "owner/repo", "--base-branch", "main", "--project-flow", "github"]) == 0
+    assert sched.main(["--repo", "owner/repo", "--base-branch", "main", "--project-flow", "github"]) == 1
     assert seen == [1, 2, 3]
     output = capsys.readouterr().out
     assert "PR #1: action_error:" in output

tests/test_required_workflow_queue_contract.py

@@ -816,6 +816,7 @@ def test_org_queue_sweep_treats_inaccessible_repositories_as_non_fatal() -> None
     # The 403 signal is classified as a skipped, non-fatal "unavailable" repo.
     assert "ORG_SWEEP_MAX_UNAVAILABLE" in workflow
     assert 'grep -qF "Resource not accessible by integration"' in workflow
+    assert "grep -qF '\"schema_version\": \"pr-review-merge-scheduler/v2\"'" in workflow
     assert "unavailable=$((unavailable + 1))" in workflow
     assert 'unavailable_repos+=("$repo_full_name")' in workflow
     assert "the sweep credential lacks access (HTTP 403" in workflow
@@ -832,6 +833,37 @@ def test_org_queue_sweep_treats_inaccessible_repositories_as_non_fatal() -> None
     assert "ORG_SWEEP_MAX_UNAVAILABLE must be a non-negative integer" in workflow
 
 
+def test_scheduler_action_errors_propagate_after_structured_summary() -> None:
+    """Targeted and organization scans must fail after retaining their summary."""
+    workflow = workflow_text("pr-review-merge-scheduler.yml")
+
+    targeted = workflow.split("      - name: Inspect PR review and merge queue", 1)[1].split(
+        "\n  org-queue-sweep:", 1
+    )[0]
+    assert 'python3 scripts/ci/pr_review_merge_scheduler.py "${args[@]}"' in targeted
+    assert "continue-on-error: true" not in targeted
+    assert "|| true" not in targeted
+
+    org_sweep = workflow.split("  org-queue-sweep:", 1)[1]
+    assert 'sweep_output="$(python3 scripts/ci/pr_review_merge_scheduler.py "${args[@]}" 2>&1)"' in org_sweep
+    assert "sweep_rc=$?" in org_sweep
+    assert 'if [ "$sweep_rc" -ne 0 ]; then' in org_sweep
+    assert "grep -qF '\"schema_version\": \"pr-review-merge-scheduler/v2\"'" in org_sweep
+    assert "failures=$((failures + 1))" in org_sweep
+
+
+def test_scheduler_exit_policy_is_documented() -> None:
+    """Keep the doctoring record bound to the terminal action_error contract."""
+    policy = (REPO_ROOT / "docs/doctoring/pr-review-merge-scheduler.md").read_text(
+        encoding="utf-8"
+    )
+
+    assert "action_error" in policy
+    assert "non-zero" in policy
+    assert "targeted" in policy
+    assert "organization sweep" in policy
+
+
 def test_fix_scheduler_cancels_superseded_cron_runs() -> None:
     workflow = workflow_text("pr-review-fix-scheduler.yml")