fix(kwok): fail fast on unworkable timeout margin at derive time

The derive step validated job_timeout_minutes as a positive integer but
never checked that the resulting sync-gate budget (job_timeout_minutes*60
- 240s margin) clears the SYNC_BUDGET_FLOOR_SECONDS floor consumed by
compute_sync_budget. A misconfigured caller (small job_timeout_minutes, or
a future bump to the 240s margin) would compute an already-past or
barely-positive deadline that only surfaced at the first sync gate — after
Go setup, kind prep, and make build had already burned CI minutes.

Add the same floor check at derive time so misconfiguration fails before
any of that work starts. The 120 literal is hand-synced with
SYNC_BUDGET_FLOOR_SECONDS in kwok/scripts/lib/sync-budget.sh and is
guarded by sync-budget_test.sh, same contract as the existing 240s margin
sync check.

Signed-off-by: Carlos Eduardo Arango Gutierrez <eduardoa@nvidia.com>

Author: ArangoGutierrez

.github/actions/kwok-test/action.yml

@@ -107,6 +107,14 @@ runs:
           echo "::error::job_timeout_minutes must be a positive integer, no leading zeros, got '${JOB_TIMEOUT_MINUTES}'"
           exit 1
         fi
+        # 120 must equal SYNC_BUDGET_FLOOR_SECONDS in kwok/scripts/lib/sync-budget.sh
+        # (hand-synced literal, guarded by sync-budget_test.sh — same contract as the
+        # 240s margin). A budget under the floor would compute an already-unusable
+        # deadline that only fails later, inside the job, after setup burned CI minutes.
+        if (( 10#${JOB_TIMEOUT_MINUTES} * 60 - 240 < 120 )); then
+          echo "::error::job_timeout_minutes=${JOB_TIMEOUT_MINUTES} leaves no usable sync budget after the 240s diagnostics margin (need >= 6)"
+          exit 1
+        fi
         KWOK_SYNC_DEADLINE_EPOCH=$(( $(date +%s) + 10#${JOB_TIMEOUT_MINUTES} * 60 - 240 ))
         echo "KWOK_SYNC_DEADLINE_EPOCH=${KWOK_SYNC_DEADLINE_EPOCH}" >> "$GITHUB_ENV"
         echo "KWOK_SYNC_DEADLINE_EPOCH=${KWOK_SYNC_DEADLINE_EPOCH} (job_timeout_minutes=${JOB_TIMEOUT_MINUTES}, margin=240s, job kill in ~$(( 10#${JOB_TIMEOUT_MINUTES} * 60 ))s)"

docs/contributor/tests.md

@@ -387,8 +387,10 @@ sits within ~60 s of job start — from its `job_timeout_minutes` input
 must equal that caller's `timeout-minutes`; currently `18` for the
 KWOK jobs) minus a 240 s margin reserved for chainsaw catch-block
 diagnostics, pod verification, and debug-artifact upload. The input
-must be a positive integer with no leading zeros; the step fails fast
-otherwise. Local runs leave it unset and keep the fixed defaults above.
+must be a positive integer with no leading zeros, and must leave at
+least 120 s of usable budget after the 240 s margin (i.e. `>= 6`); the
+step fails fast otherwise. Local runs leave it unset and keep the
+fixed defaults above.
 
 The Git-source lanes (`flux-git`, `argocd-git`) additionally honor
 `KWOK_GITEA_HOST_PORT` (default `3300`), `KWOK_GITEA_USER` (default

kwok/scripts/lib/sync-budget_test.sh

@@ -98,8 +98,50 @@ tier3_shard_out=$(job_timeout_sync "${REPO_ROOT}/.github/workflows/kwok-tier3-sh
 check "kwok-tier3-shard-job-timeout-in-sync" 0 "test:jtm=18,tm=18" \
     0 "$(echo "${tier3_shard_out}" | grep '^test:')"
 
+# 10-11. Margin-floor guard in the "Derive sync-gate deadline" step
+# (action.yml): job_timeout_minutes must leave >= SYNC_BUDGET_FLOOR_SECONDS
+# of usable budget after the 240s diagnostics margin, or the step must fail
+# fast before toolchain setup + make build burn CI minutes. Extracted
+# straight from action.yml (not reimplemented here) so this always exercises
+# THIS checkout's actual CI logic, never a stale copy.
+ACTION_YML="${REPO_ROOT}/.github/actions/kwok-test/action.yml"
+
+# extract_derive_step <file> -> the dedented run: block of the "Derive
+# sync-gate deadline" step.
+extract_derive_step() {
+    local file="$1"
+    awk '
+        /^    - name: Derive sync-gate deadline$/ { in_step=1; next }
+        in_step && /^      run: \|$/ { in_run=1; next }
+        in_run && /^    - name:/ { exit }
+        in_run { sub(/^        /, ""); print }
+    ' "${file}"
+}
+
+# run_derive_step <job_timeout_minutes> -> sets got_rc, got_env_file
+# (caller-owned temp file, removed by caller). -eo pipefail mirrors the
+# composite step's actual shell (`shell: bash` -> bash -eo pipefail) so a
+# future set -e interaction cannot diverge between CI and this harness.
+run_derive_step() {
+    local jtm="$1"
+    got_env_file=$(mktemp)
+    JOB_TIMEOUT_MINUTES="${jtm}" GITHUB_ENV="${got_env_file}" \
+        bash -eo pipefail -c "$(extract_derive_step "${ACTION_YML}")" > /dev/null 2>&1
+    got_rc=$?
+}
+
+run_derive_step 5
+check "derive-step-below-floor-fails" 1 "" "${got_rc}" ""
+rm -f "${got_env_file}"
+
+run_derive_step 6
+env_has_deadline="no"
+grep -q '^KWOK_SYNC_DEADLINE_EPOCH=' "${got_env_file}" && env_has_deadline="yes"
+check "derive-step-at-floor-boundary-succeeds" 0 "yes" "${got_rc}" "${env_has_deadline}"
+rm -f "${got_env_file}"
+
 if (( fails > 0 )); then
     echo "${fails} test(s) failed"
     exit 1
 fi
-echo "All 9 tests passed"
+echo "All 11 tests passed"