feat(scripts): add failure log dump option

Extend wait-for-gh-run.sh with --failure-logs and fold docs under a How to Git Push section.

AGENTS.md

@@ -39,7 +39,9 @@ Examples:
 - `fix(core/codex): handle SIGINT in on_exec_command_begin to avoid orphaned child`
 - `docs(agents): clarify commit-message expectations`
 
-## Git Push Policy (Do Not Rebase On Push Requests)
+## How to Git Push
+
+### Merge-and-Push Policy (Do Not Rebase)
 
 When the user asks you to "push" local work:
 
@@ -90,10 +92,11 @@ This architecture separates concerns between execution logic (core), UI state ma
 - Prefer snapshot assertions (`assert_snapshot!`) or rich string comparisons so UI regressions are obvious. Keep snapshots deterministic by trimming trailing space and driving commit ticks just like the existing tests do.
 - When adding fixtures or updating snapshots, gate rewrites behind an opt-in env var (e.g., `UPDATE_IDEAL=1`) so baseline refreshes remain explicit.
 
-## Monitoring Release Workflows
+### Monitor Release Workflows After Pushing
 
 - Use `scripts/wait-for-gh-run.sh` to follow GitHub Actions releases without spamming manual `gh` commands.
-- Typical release check: `scripts/wait-for-gh-run.sh --workflow Release --branch main`.
-- If you already know the ID (e.g., from a push webhook), run `scripts/wait-for-gh-run.sh --run <run-id>`.
+- Typical release check right after a push: `scripts/wait-for-gh-run.sh --workflow Release --branch main`.
+- If you already know the run ID (e.g., from webhook output), run `scripts/wait-for-gh-run.sh --run <run-id>`.
 - Adjust the poll cadence via `--interval <seconds>` (defaults to 8). The script exits 0 on success and 1 on failure, so it can gate local automation.
+- Pass `--failure-logs` to automatically dump logs for any job that does not finish successfully.
 - Dependencies: GitHub CLI (`gh`) and `jq` must be available in `PATH`.

scripts/wait-for-gh-run.sh

@@ -18,6 +18,7 @@ Options:
   -w, --workflow NAME    Workflow name or filename to pick the latest run.
   -b, --branch BRANCH    Branch to filter when selecting a run (default: main).
   -i, --interval SECONDS Polling interval in seconds (default: 8).
+  -L, --failure-logs     Print logs for any job that does not finish successfully.
   -h, --help             Show this help message.
 
 Either --run or --workflow must be supplied.
@@ -35,6 +36,7 @@ RUN_ID=""
 WORKFLOW=""
 BRANCH="main"
 INTERVAL="8"
+PRINT_FAILURE_LOGS=false
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -54,6 +56,10 @@ while [[ $# -gt 0 ]]; do
       INTERVAL="${2:-}"
       shift 2
       ;;
+    -L|--failure-logs)
+      PRINT_FAILURE_LOGS=true
+      shift
+      ;;
     -h|--help)
       usage
       exit 0
@@ -142,6 +148,18 @@ while true; do
       echo "Run $RUN_ID succeeded." >&2
       exit 0
     else
+      if [[ "$PRINT_FAILURE_LOGS" == true ]]; then
+        echo "Collecting logs for failed jobs..." >&2
+        jq -r '.jobs[]? | select((.conclusion // "") != "success") | "\(.databaseId)\t\(.name // "(no name)")"' <<<"$json" \
+          | while IFS=$'\t' read -r job_id job_name; do
+              [[ -z "$job_id" ]] && continue
+              echo "--- Logs for job: $job_name (ID $job_id) ---" >&2
+              if ! gh run view "$RUN_ID" --log --job "$job_id" 2>&1; then
+                echo "(failed to fetch logs for job $job_id)" >&2
+              fi
+              echo "--- End logs for job: $job_name ---" >&2
+            done
+      fi
       echo "Run $RUN_ID finished with conclusion '$conclusion'." >&2
       exit 1
     fi