ci(free): per-shard sub-shard k in the CI plan (--shard-jobs), free_jobs and windows_jobs dispatch inputs (k=1 defaults)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

.github/workflows/free-tests.yml

@@ -32,13 +32,21 @@ on:
         description: 'Runner-sizing experiments only: shard count, 1-40 (empty keeps FREE_SUITE_SHARDS)'
         type: string
         default: ''
+      free_jobs:
+        description: 'Runner-sizing experiments only: sub-shards per CI shard (--shard-jobs), 1-8 (empty keeps FREE_SUITE_JOBS)'
+        type: string
+        default: ''
 
-# The one source of the free-suite runner and shard count. pull_request and
-# push runs never see workflow_dispatch inputs, so free-plan resolves these
-# (or a dispatch override) into outputs that free-suite reads.
+# The one source of the free-suite runner, shard count and sub-shards per
+# shard. pull_request and push runs never see workflow_dispatch inputs, so
+# free-plan resolves these (or a dispatch override) into outputs and the plan
+# that free-suite reads. FREE_SUITE_JOBS is k in `--ci-plan --shard-jobs k`:
+# each shard runs min(k, its parallel files) sandboxed sub-shards side by side
+# (scripts/lib/shard-jobs.ts); the exclusive host-state shard stays one child.
 env:
   FREE_SUITE_RUNNER: ubicloud-standard-2
   FREE_SUITE_SHARDS: '20'
+  FREE_SUITE_JOBS: '1'
 
 # Keyed on the PR number, not head_ref: a bare branch name carries no fork
 # prefix, so same-name branches from two forks would share one group and a
@@ -76,10 +84,12 @@ jobs:
         env:
           RUNNER_OVERRIDE: ${{ inputs.free_runner }}
           SHARDS_OVERRIDE: ${{ inputs.free_shards }}
+          JOBS_OVERRIDE: ${{ inputs.free_jobs }}
         run: |
           set -euo pipefail
           runner="${RUNNER_OVERRIDE:-$FREE_SUITE_RUNNER}"
           shards="${SHARDS_OVERRIDE:-$FREE_SUITE_SHARDS}"
+          jobs="${JOBS_OVERRIDE:-$FREE_SUITE_JOBS}"
           case "$runner" in
             ubicloud-standard-2|ubicloud-standard-4|ubicloud-standard-8) ;;
             *) echo "::error::free_runner '$runner' is not ubicloud-standard-2, -4 or -8"; exit 1 ;;
@@ -88,10 +98,14 @@ jobs:
             ''|*[!0-9]*) echo "::error::free_shards '$shards' is not a whole number"; exit 1 ;;
           esac
           if [ "$shards" -lt 1 ] || [ "$shards" -gt 40 ]; then echo "::error::free_shards $shards is outside 1-40"; exit 1; fi
-          if [ "$runner" != "$FREE_SUITE_RUNNER" ] || [ "$shards" != "$FREE_SUITE_SHARDS" ]; then
-            echo "- Runner-sizing experiment: $shards shards on $runner (defaults $FREE_SUITE_SHARDS on $FREE_SUITE_RUNNER); not a PR or train Free Tests result" >> "$GITHUB_STEP_SUMMARY"
+          case "$jobs" in
+            ''|*[!0-9]*) echo "::error::free_jobs '$jobs' is not a whole number"; exit 1 ;;
+          esac
+          if [ "$jobs" -lt 1 ] || [ "$jobs" -gt 8 ]; then echo "::error::free_jobs $jobs is outside 1-8"; exit 1; fi
+          if [ "$runner" != "$FREE_SUITE_RUNNER" ] || [ "$shards" != "$FREE_SUITE_SHARDS" ] || [ "$jobs" != "$FREE_SUITE_JOBS" ]; then
+            echo "- Runner-sizing experiment: $shards shards on $runner at $jobs sub-shards each (defaults $FREE_SUITE_SHARDS on $FREE_SUITE_RUNNER at $FREE_SUITE_JOBS); not a PR or train Free Tests result" >> "$GITHUB_STEP_SUMMARY"
           fi
-          matrix=$(bun run scripts/test-free-shards.ts --ci-plan "$RUNNER_TEMP/free-plan.json" --shards "$shards")
+          matrix=$(bun run scripts/test-free-shards.ts --ci-plan "$RUNNER_TEMP/free-plan.json" --shards "$shards" --shard-jobs "$jobs")
           echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
           echo "runner=$runner" >> "$GITHUB_OUTPUT"
       - name: Seed growth ratchet (60 s ceiling, shrink-only allowlist)

.github/workflows/windows-free-tests.yml

@@ -34,6 +34,10 @@ on:
         description: Record per-file Windows durations (artifact) instead of running the lane
         type: boolean
         default: false
+      windows_jobs:
+        description: 'Sub-shard experiments only: sub-shards per Windows shard (--shard-jobs), 1-4 (empty keeps WINDOWS_FREE_JOBS). Never cite such a run as a PR result.'
+        type: string
+        default: ''
   # free-durations-record.yml calls the recording path weekly.
   workflow_call:
     inputs:
@@ -41,6 +45,11 @@ on:
         type: boolean
         default: false
 
+# k in `--ci-plan --shard-jobs k`: each Windows shard runs min(k, its parallel
+# files) sandboxed sub-shards side by side (scripts/lib/shard-jobs.ts).
+env:
+  WINDOWS_FREE_JOBS: '1'
+
 concurrency:
   group: windows-free-${{ github.event.pull_request.number || github.run_id }}
   cancel-in-progress: true
@@ -69,8 +78,18 @@ jobs:
         # 4-vCPU Windows runner, so the lane lands near 4 min with setup.
         env:
           GSTACK_FREE_TEST_DURATIONS: scripts/free-test-durations-windows.json
+          JOBS_OVERRIDE: ${{ inputs.windows_jobs }}
         run: |
-          matrix=$(bun run scripts/test-free-shards.ts --windows-only --ci-plan "$RUNNER_TEMP/windows-plan.json" --shards 6)
+          set -euo pipefail
+          jobs="${JOBS_OVERRIDE:-$WINDOWS_FREE_JOBS}"
+          case "$jobs" in
+            ''|*[!0-9]*) echo "::error::windows_jobs '$jobs' is not a whole number"; exit 1 ;;
+          esac
+          if [ "$jobs" -lt 1 ] || [ "$jobs" -gt 4 ]; then echo "::error::windows_jobs $jobs is outside 1-4"; exit 1; fi
+          if [ "$jobs" != "$WINDOWS_FREE_JOBS" ]; then
+            echo "- Sub-shard experiment: $jobs sub-shards per Windows shard (default $WINDOWS_FREE_JOBS); not a PR Windows Free Tests result" >> "$GITHUB_STEP_SUMMARY"
+          fi
+          matrix=$(bun run scripts/test-free-shards.ts --windows-only --ci-plan "$RUNNER_TEMP/windows-plan.json" --shards 6 --shard-jobs "$jobs")
           echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
         with: