fix(ci): reap fatal OpenCode process groups

CHANGELOG.md

@@ -13,6 +13,7 @@ Semantic Versioning where the repository publishes a release.
 
 ### Fixed
 
+- 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/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_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