Add resumable test-level scheduler

Add test listing and opt-in machine-readable per-test timing results. Schedule selected tests into suite-ordered batches with per-test watchdogs, timeout resume, union accounting, timing history, changed/failed selectors, and Valgrind result aggregation. Route opt-in smart runs through scripts/test.sh and document the iteration flow.

Validation: build-dev, lint, scheduler syntax and shell checks, listing and five-suite comparison, full smart run, timeout resume proof, same-build parallel baseline, and bounded Valgrind runs. See the acceptance report for results and remaining Valgrind coverage.

Author: ngallodev

AGENTS.md

@@ -7,6 +7,9 @@
   files and the compiler cache.
 - Prefer `scripts/test.sh --suites <suite>` for local validation. This uses the
   incremental test runner; choose the smallest relevant suite set.
+- For resumable per-test iteration, use `scripts/test.sh --smart` with
+  `--suites`, `--changed`, `--tests`, or `--failed`; use `--dry-run` on
+  `scripts/testsched/schedule.py` to inspect its timing based plan.
 - Do not use `scripts/build.sh` or the default `scripts/test.sh` for ordinary
   iteration. Those are clean, complete venue gates for GitHub, Jenkins, and
   release validation.

CONTRIBUTING.md

@@ -2,6 +2,15 @@
 
 Contributions are welcome. This guide covers setup, testing, and PR guidelines.
 
+### Fast test iteration
+
+Use `scripts/test.sh --smart` to schedule individual tests in resumable batches.
+Narrow a run with `--suites 'cli daemon_ipc'`, `--tests suite:test,...`,
+`--changed [BASE]`, or `--failed`; `--jobs N` controls concurrency. Add
+`--tool valgrind` for per-test memcheck runs. `--dry-run` is available on the
+scheduler (`python3 scripts/testsched/schedule.py --runner build/c/test-runner --dry-run`).
+The regular `scripts/test.sh` remains the full CI venue gate.
+
 > **Important**: This project is a **pure C binary** (rewritten from Go in v0.5.0). Please submit C code, not Go. Go PRs may be ported but cannot be merged directly.
 
 ## Build from Source

scripts/test.sh

@@ -5,19 +5,42 @@
 
 set -euo pipefail
 
+SMART=0
+SMART_ARGS=()
+FILTERED_ARGS=()
+while (($#)); do
+    case "$1" in
+        --smart) SMART=1; shift ;;
+        --dry-run) SMART_ARGS+=(--dry-run); shift ;;
+        --tool|--jobs|--tests) SMART_ARGS+=("$1" "${2:?$1 needs a value}"); shift 2 ;;
+        --changed)
+            SMART_ARGS+=(--changed)
+            if (($# > 1)) && [[ "$2" != -* ]]; then SMART_ARGS+=("$2"); shift 2; else shift; fi ;;
+        --failed) SMART_ARGS+=(--failed); shift ;;
+        *) FILTERED_ARGS+=("$1"); shift ;;
+    esac
+done
+set -- "${FILTERED_ARGS[@]}"
+if [ "$SMART" -eq 0 ] && [ "${#SMART_ARGS[@]}" -gt 0 ]; then
+    echo "test.sh: scheduler options require --smart" >&2
+    exit 2
+fi
+
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$ROOT"
 
 usage() {
     cat <<'EOF'
-Usage: scripts/test.sh [--suites LIST] [--phase PHASE] [--arch ARCH] [VAR=VAL ...]
+Usage: scripts/test.sh [--smart [--tool valgrind] [--suites LIST|--changed [BASE]|--failed] [--jobs N]] [--suites LIST] [--phase PHASE] [--arch ARCH] [VAR=VAL ...]
 
 The canonical test entry: identical in local CI, PR CI, dry run and release.
 DEFAULT (no --suites) is exactly what CI runs: static contract checks
 (Step 0a-0t), a CLEAN sanitizer build, every suite via the parallel harness,
 then the prod-binary regression guards (Steps 4-6).
 
 Modes:
+  --smart        Test-level resumable iteration scheduler; accepts --suites,
+                 --tests, --changed [BASE], --failed, --tool valgrind, --jobs.
   (default)      The venue leg. Clean build (scripts/clean.sh) + all suites +
                  all contract steps. This is the shape every gate runs.
   --suites LIST  ITERATION mode: comma- or space-separated suite names, e.g.
@@ -269,6 +292,25 @@ if [ "$TSAN" -eq 1 ]; then
     exit "$?"
 fi
 
+if [ "$SMART" -eq 1 ]; then
+    BUILD_JOBS="$NPROC"
+    if [[ " ${SMART_ARGS[*]} " == *" --tool valgrind "* ]] && [ "$SANITIZE_GIVEN" -eq 0 ]; then
+        if [ "$BUILD_JOBS" -gt 16 ]; then BUILD_JOBS=16; fi
+        if [ "$BUILD_DIR" = "build/c" ]; then
+            BUILD_DIR="build/c-valgrind"
+            MAKE_ARGS+=("BUILD_DIR=$BUILD_DIR")
+        fi
+        MAKE_ARGS+=("SANITIZE=")
+        EXPECTED_SANITIZED=0
+    fi
+    make -j"$BUILD_JOBS" -f Makefile.cbm "$BUILD_DIR/test-runner" ${MAKE_ARGS[@]+"${MAKE_ARGS[@]}"}
+    assert_test_runner_build_config "$BUILD_DIR/test-runner" "$EXPECTED_SANITIZED"
+    MODE=asan; [ "$EXPECTED_SANITIZED" -eq 1 ] || MODE=plain
+    SCHED_ARGS=(--runner "$BUILD_DIR/test-runner" --mode "$MODE")
+    if [ -n "$SUITES" ]; then read -r -a SUITE_ARGS <<< "$SUITES"; SCHED_ARGS+=(--suites "${SUITE_ARGS[@]}"); fi
+    exec python3 "$ROOT/scripts/testsched/schedule.py" "${SCHED_ARGS[@]}" "${SMART_ARGS[@]}"
+fi
+
 # ── Iteration mode (--suites): incremental rebuild + subset run ──
 # The documented fast path: no clean, no contract steps, no prod-binary
 # guards — those all still gate every merge through the default full run.