fix(ci): reap fatal OpenCode process groups

.github/workflows/security-scan.yml

@@ -16,10 +16,10 @@
 # pull_request workflows upload to refs/pull/N/merge, so no single ref ever holds
 # all tools. Bundling at the workflow/check level is ref-independent.
 #
-# NOTE on dependency-review: dependency graph can be unavailable on some repos.
-# Treat that as "not enforceable here" instead of making the required workflow
-# unsatisfiable; keep medium-or-higher dependency findings hard-failing where the
-# API is supported.
+# NOTE on dependency-review: the dependency-graph comparison must return HTTP
+# 200 for the exact PR base/head pair before dependency review may run. Missing,
+# unsupported, unauthorized, timed-out, or otherwise non-200 evidence fails
+# closed so the required workflow never reports success by silently skipping it.
 #
 # NOTE on trivy-fs: it scans the whole repo, so a pre-existing FIXABLE
 # MEDIUM/HIGH/CRITICAL finding blocks every PR in that repo until it is fixed.
@@ -272,30 +272,25 @@ jobs:
           set -euo pipefail
 
           api_url="${GITHUB_API_URL:-https://api.github.com}"
-          response_file="$(mktemp)"
-          status="$(
-            curl -fsS -o "$response_file" -w '%{http_code}' \
+          if ! status="$(
+            curl -sS --connect-timeout 10 --max-time 30 \
+              -o /dev/null \
+              -w '%{http_code}' \
               -H "Accept: application/vnd.github+json" \
               -H "Authorization: Bearer ${GH_TOKEN}" \
               -H "X-GitHub-Api-Version: 2022-11-28" \
-              "${api_url}/repos/${REPOSITORY}/dependency-graph/compare/${BASE_SHA}...${HEAD_SHA}" \
-              || true
-          )"
-
-          if [ "$status" = "200" ]; then
-            echo "supported=true" >>"$GITHUB_OUTPUT"
-            exit 0
+              "${api_url}/repos/${REPOSITORY}/dependency-graph/compare/${BASE_SHA}...${HEAD_SHA}"
+          )"; then
+            echo "::error::Dependency review evidence request failed for ${REPOSITORY} at exact base ${BASE_SHA} and head ${HEAD_SHA}. Failing closed."
+            exit 1
           fi
 
-          if [ "$status" = "403" ] || [ "$status" = "404" ]; then
-            echo "::warning::Dependency review is unavailable for ${REPOSITORY}; skipping dependency-review hard gate."
-            echo "supported=false" >>"$GITHUB_OUTPUT"
-            exit 0
+          if [ "$status" != "200" ]; then
+            echo "::error::Dependency review evidence unavailable for ${REPOSITORY} at exact base ${BASE_SHA} and head ${HEAD_SHA}: HTTP ${status:-unavailable}. Failing closed."
+            exit 1
           fi
 
-          echo "::error::Dependency review support check failed with HTTP ${status}."
-          cat "$response_file"
-          exit 1
+          echo "supported=true" >>"$GITHUB_OUTPUT"
       - name: Dependency review
         if: steps.dependency_review_support.outputs.supported == 'true'
         uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0

CHANGELOG.md

@@ -13,6 +13,8 @@ Semantic Versioning where the repository publishes a release.
 
 ### Fixed
 
+- Made the required dependency-review support probe require both successful `curl` transport completion and exact HTTP 200 evidence before emitting `supported=true`; partial transfers and every other nonzero curl exit now fail closed even if an HTTP 200 status was already written.
+- Terminated fatal-provider OpenCode attempts as complete process groups instead of killing only the timeout wrapper, preventing descendant processes from retaining workflow pipes and stalling exact-head coverage evidence after the review launcher exits.
 - Bound each review-agent invocation key to the wrapper's complete canonical payload, including the base branch and requesting actor; altered fields with a valid-format key now fail before durable-leader election or forwarding, and wrapper write permission is job-scoped.
 - Bound both trusted-uv quality jobs to `github.event.pull_request.head.sha` and added a permanent two-checkout regression contract so exact-head compatibility, coverage, docstring, and compilation claims cannot silently measure GitHub's generated pull-request merge revision.
 - Made Strix treat only a single LiteLLM provider-error line containing NVIDIA NIM context and model-catalog 404 evidence as cross-model fallback evidence, rejecting cross-line signal assembly and provider-like target source literals; moved the public default to Nemotron 3 Super 120B and added a second NVIDIA hosted candidate before GitHub Models without neutralizing reported vulnerabilities.

docs/doctoring/dependency-review-support-probe.md

@@ -0,0 +1,38 @@
+# Dependency-review support probe fail-closed contract
+
+## Incident
+
+The required central `Security Scan` workflow probes GitHub's dependency-review compare endpoint before invoking `actions/dependency-review-action`. The probe already treated every HTTP status other than 200 as unavailable evidence. However, the shell command substitution appended `|| true`, so a transport-level `curl` failure could be converted into shell success. Because `curl --write-out '%{http_code}'` can emit an HTTP status even when the transfer itself later fails, an output of `200` paired with a nonzero curl exit status could incorrectly set `supported=true`.
+
+This is an evidence-integrity defect rather than a dependency vulnerability. A required security gate must not claim the dependency-review prerequisite is available unless both the transport command and the API status prove success.
+
+## Decision
+
+The support probe now has two independent fail-closed conditions:
+
+1. `curl` must exit successfully under the existing ten-second connection timeout and thirty-second total timeout; and
+2. the returned status text must be exactly `200` for the exact pull-request base/head comparison.
+
+The workflow discards the untrusted response body and writes `supported=true` only after both conditions pass. Timeout, partial transfer, connection failure, TLS failure, malformed or empty status output, HTTP 403/404, and every other non-200 response terminate the job. The dependency-review action, its immutable pin, its severity threshold, workflow permissions, API endpoint, API-version header, and credential identity are unchanged.
+
+## Test-first evidence
+
+`tests/test_dependency_review_support_probe.py` executes the exact shell body extracted from `.github/workflows/security-scan.yml` with an injected fake `curl`. The regression makes `curl` print HTTP `200` and then exit with code 18, representing a partial-transfer failure. The accepted contract is that the shell step exits nonzero, emits the existing fail-closed diagnostic, and never writes `supported=true` to `GITHUB_OUTPUT`.
+
+The regression was committed before the workflow repair so the defect remained observable independently of the implementation change.
+
+## Operational interpretation
+
+A failed support probe means dependency-review assurance is unavailable for that exact base/head pair. It is not permission to skip the dependency-review job and it must not be reclassified as success because another scanner passed. Retry after an infrastructure or GitHub service failure; remediate repository feature or authorization configuration for persistent 403/404 responses. Only a successful probe followed by the required dependency-review action can satisfy this part of the central supply-chain gate.
+
+## Rollback
+
+Rollback requires an independently reviewed replacement that preserves both transport-success and exact-HTTP-200 evidence. Restoring `|| true`, treating a nonzero curl exit as advisory, or allowing 403/404 to produce a successful skip would reintroduce the fail-open condition and is not an acceptable rollback.
+
+## APA 7th references
+
+GitHub. (2026). *REST API endpoints for dependency review*. GitHub Docs. Retrieved August 7, 2026, from https://docs.github.com/en/rest/dependency-graph/dependency-review
+
+The curl project. (2026). *curl: How to use*. Retrieved August 7, 2026, from https://curl.se/docs/manpage.html
+
+The curl project. (2026). *libcurl error codes*. Retrieved August 7, 2026, from https://curl.se/libcurl/c/libcurl-errors.html

docs/doctoring/opencode-process-group-termination.md

@@ -0,0 +1,27 @@
+# OpenCode fatal-provider process-group termination
+
+## Incident
+
+The exact-head coverage-evidence job for `.github` pull request #799 reached the repository test suite but did not complete inside its bounded measurement step. A focused reproduction identified `test_fatal_provider_error_kills_hung_opencode_run_early`: the launcher detected a fatal provider event and terminated the `timeout` wrapper, while a descendant fake `opencode` process could remain alive with inherited output pipes. The parent Python process then waited for end-of-file even though the launcher had returned.
+
+## Decision
+
+Each bounded `opencode run` starts in a new session with `setsid`. On a structured fatal-provider event, the launcher sends `SIGTERM` to the negative process-group identifier, waits for bounded group disappearance, and then sends `SIGKILL` to the same group if necessary. The ordinary timeout contract remains `timeout --kill-after=30s`; only the early-fatal cleanup boundary changes.
+
+The group signal is deliberately scoped to the session created for one model attempt. It does not target the workflow shell, unrelated model attempts, or the runner process. The production Ubuntu image already installs `util-linux`, which supplies `setsid`.
+
+## Verification
+
+The existing behavioral regression uses a fake provider that emits a fatal structured event and sleeps for 120 seconds. Before the change, the test exceeded its 30-second subprocess boundary because a descendant retained the capture pipes. With process-group termination, it completes in under 25 seconds and the complete model-pool test file remains eligible for the exact-head coverage job. Shell syntax validation and the repository-wide evidence command remain required before merge.
+
+## Rollback
+
+Rollback requires an independently reviewed change and a replacement mechanism that proves every descendant of a fatal model attempt is reaped without terminating unrelated runner work. Restoring PID-only termination is not acceptable because it reintroduces the pipe-retention failure mode.
+
+## APA 7th references
+
+IEEE & The Open Group. (2024). *The Open Group base specifications issue 8: System interfaces, `kill()`*. https://pubs.opengroup.org/onlinepubs/9799919799/functions/kill.html
+
+Free Software Foundation. (n.d.). *GNU Coreutils manual: `timeout`: Run a command with a time limit*. Retrieved August 7, 2026, from https://www.gnu.org/software/coreutils/manual/html_node/timeout-invocation.html
+
+Linux man-pages project. (2026, February 8). *setsid(2) — Linux manual page* (Linux man-pages 6.18). https://man7.org/linux/man-pages/man2/setsid.2.html

scripts/ci/run_opencode_review_model_pool.sh

@@ -465,7 +465,11 @@ run_one_model_attempt() {
 
 	rm -f "$opencode_json_file" "$opencode_stderr_file" "$opencode_export_file" "$candidate_output_file"
 	set +e
-	timeout --kill-after=30s "${run_timeout_seconds}s" \
+	# Start the timeout wrapper in its own session so a fatal-provider abort can
+	# terminate the complete provider process group. Killing only the timeout
+	# wrapper leaves descendants holding stdout/stderr pipes open, which can hang
+	# callers even after the review launcher itself exits.
+	setsid timeout --kill-after=30s "${run_timeout_seconds}s" \
 		env -u GH_TOKEN -u GITHUB_TOKEN -u OPENCODE_APP_TOKEN \
 		-u ACTIONS_ID_TOKEN_REQUEST_TOKEN -u ACTIONS_ID_TOKEN_REQUEST_URL \
 		opencode run "$(cat "$prompt_file")" \
@@ -484,12 +488,15 @@ run_one_model_attempt() {
 		if has_fatal_provider_error_event "$opencode_json_file"; then
 			printf 'OpenCode %s attempt %s/%s logged a fatal provider error while still running; killing the hung process instead of waiting out the %ss run timeout.\n' \
 				"$model_candidate" "$attempt" "$attempts" "$run_timeout_seconds"
-			kill "$opencode_pid" 2>/dev/null
+			# The setsid-launched timeout wrapper is also the process-group leader.
+			# Signal the negative PGID so opencode and any descendants cannot survive
+			# as pipe-holding orphans after the wrapper exits.
+			kill -TERM -- "-$opencode_pid" 2>/dev/null || true
 			for _ in $(seq 1 30); do
-				kill -0 "$opencode_pid" 2>/dev/null || break
+				kill -0 -- "-$opencode_pid" 2>/dev/null || break
 				sleep 1
 			done
-			kill -9 "$opencode_pid" 2>/dev/null
+			kill -KILL -- "-$opencode_pid" 2>/dev/null || true
 			break
 		fi
 		sleep "$fatal_poll_seconds"

tests/test_dependency_review_support_probe.py

@@ -0,0 +1,62 @@
+"""Behavioral regressions for the dependency-review capability probe."""
+
+from __future__ import annotations
+
+import os
+import stat
+import subprocess
+import textwrap
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def _support_probe_script() -> str:
+    """Extract the exact shell body used by the dependency-review support step."""
+    workflow = (
+        REPO_ROOT / ".github" / "workflows" / "security-scan.yml"
+    ).read_text(encoding="utf-8")
+    step_marker = "      - name: Check dependency review support\n"
+    step_start = workflow.index(step_marker)
+    run_marker = "        run: |\n"
+    run_start = workflow.index(run_marker, step_start) + len(run_marker)
+    run_end = workflow.index("\n      - name:", run_start)
+    return textwrap.dedent(workflow[run_start:run_end])
+
+
+def test_dependency_review_probe_rejects_curl_failure_with_http_200(tmp_path) -> None:
+    """A transport failure must fail closed even when curl printed HTTP 200."""
+    fake_bin = tmp_path / "bin"
+    fake_bin.mkdir()
+    fake_curl = fake_bin / "curl"
+    fake_curl.write_text("#!/bin/sh\nprintf '200'\nexit 18\n", encoding="utf-8")
+    fake_curl.chmod(fake_curl.stat().st_mode | stat.S_IXUSR)
+    github_output = tmp_path / "github-output.txt"
+    environment = os.environ.copy()
+    environment.update(
+        {
+            "PATH": f"{fake_bin}:{environment['PATH']}",
+            "GH_TOKEN": "test-token",
+            "BASE_SHA": "a" * 40,
+            "HEAD_SHA": "b" * 40,
+            "REPOSITORY": "ContextualWisdomLab/example",
+            "GITHUB_API_URL": "https://api.github.invalid",
+            "GITHUB_OUTPUT": str(github_output),
+        }
+    )
+
+    completed = subprocess.run(
+        ["bash", "-c", _support_probe_script()],
+        cwd=REPO_ROOT,
+        env=environment,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+    assert completed.returncode != 0
+    assert "Failing closed" in f"{completed.stdout}\n{completed.stderr}"
+    assert not github_output.exists() or "supported=true" not in github_output.read_text(
+        encoding="utf-8"
+    )

tests/test_required_workflow_queue_contract.py

@@ -826,15 +826,23 @@ def test_fix_scheduler_cancels_superseded_cron_runs() -> None:
     assert "cancel-in-progress: true" in workflow
 
 
-def test_security_scan_skips_dependency_review_when_dependency_graph_is_unavailable() -> (
-    None
-):
+def test_security_scan_fails_closed_when_dependency_review_is_unavailable() -> None:
+    """Only exact-head HTTP 200 evidence may enable dependency review."""
     workflow = workflow_text("security-scan.yml")
-
-    assert "id: dependency_review_support" in workflow
-    assert "/dependency-graph/compare/${BASE_SHA}...${HEAD_SHA}" in workflow
-    assert '"$status" = "403"' in workflow
-    assert '"$status" = "404"' in workflow
+    support = workflow_step(workflow, "Check dependency review support")
+
+    assert "id: dependency_review_support" in support
+    assert "/dependency-graph/compare/${BASE_SHA}...${HEAD_SHA}" in support
+    assert "--connect-timeout 10" in support
+    assert "--max-time 30" in support
+    assert '-o /dev/null' in support
+    assert 'if [ "$status" != "200" ]; then' in support
+    assert "Failing closed" in support
+    assert "exit 1" in support
+    assert 'echo "supported=true"' in support
+    assert "supported=false" not in support
+    assert '"$status" = "403"' not in support
+    assert '"$status" = "404"' not in support
     assert "steps.dependency_review_support.outputs.supported == 'true'" in workflow
 
 

tests/test_sandboxed_verify.py

@@ -1,6 +1,7 @@
 import json
 import runpy
 import shutil
+import subprocess
 import sys
 from pathlib import Path
 
@@ -132,12 +133,16 @@ def test_main_reports_allowed_env_network_stderr_timeout_and_kept_sandbox(monkey
     repo = tmp_path / "repo"
     repo.mkdir()
     monkeypatch.setenv("VISIBLE_TOKEN", "secret-value")
-    command = (
-        "import sys, time; "
-        "print('timeout-out', flush=True); "
-        "print('timeout-err', file=sys.stderr, flush=True); "
-        "time.sleep(2)"
-    )
+    command = [sys.executable, "-c", "raise SystemExit('must not execute')"]
+
+    def timeout_runner(command, cwd, env, timeout):
+        """Return deterministic partial streams at the timeout boundary."""
+        del cwd, env
+        raise subprocess.TimeoutExpired(
+            command, timeout, output="timeout-out\n", stderr="timeout-err\n"
+        )
+
+    monkeypatch.setattr(sandboxed_verify, "run_command", timeout_runner)
 
     exit_code = sandboxed_verify.main(
         [
@@ -153,9 +158,7 @@ def test_main_reports_allowed_env_network_stderr_timeout_and_kept_sandbox(monkey
             "--evidence-note",
             "needs private dependency",
             "--",
-            sys.executable,
-            "-c",
-            command,
+            *command,
         ]
     )
     captured = capsys.readouterr()
@@ -198,3 +201,17 @@ def test_module_main_entrypoint(monkeypatch, tmp_path):
             if module is not None:
                 sys.modules["scripts.ci.sandboxed_verify"] = module
     assert exc_info.value.code == 0
+
+
+def test_process_group_doctoring_uses_versioned_linux_man_pages_metadata() -> None:
+    """Cite the authoritative versioned setsid manual instead of its HTML renderer."""
+    doctoring = (
+        Path(__file__).resolve().parents[1]
+        / "docs"
+        / "doctoring"
+        / "opencode-process-group-termination.md"
+    ).read_text(encoding="utf-8")
+
+    assert "Linux man-pages project. (2026, February 8)." in doctoring
+    assert "*setsid(2) — Linux manual page* (Linux man-pages 6.18)." in doctoring
+    assert "Kerrisk, M. (n.d.). *setsid(2)" not in doctoring