docs(pregate): remote-gate reason codes, paid-file handling and measured keyed/keyless timing

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

CONTRIBUTING.md

@@ -187,7 +187,7 @@ the new defaults.
 | Run one free test file while repairing | `bun test <file>` | Free, seconds | Never bare `bun test` for the suite |
 | Run full free acceptance before publishing | `bun run test` | Free, a few minutes | Bun 1.4.2 |
 | Run the full free suite from a small machine | `bun run test:ubicloud` | Free suite on a billed 16-vCPU VM, about 5 minutes | `UBICLOUD_API_KEY` |
-| Clear pregate's test tier on a machine under 8 cores ([remote gate](docs/pregate.md#remote-gate)) | `gstack-pregate --stage tests --remote --spend-cap 2 --timeout 2700 --allow-repo-commands` (same command keyed or keyless) | Keyed: one billed 16-vCPU VM, worst case $0.38; keyless: free, the selected files run locally in parallel shards | Keyed: `UBICLOUD_API_KEY`; keyless: nothing |
+| Clear pregate's test tier on a machine under 8 cores ([remote gate](docs/pregate.md#remote-gate)) | `gstack-pregate --stage tests --remote --spend-cap 2 --timeout 2700 --allow-repo-commands` (same command keyed or keyless) | Keyed: one billed 16-vCPU VM, about 7 minutes and $0.06 for the whole free tier, worst case $0.38; keyless: free, local parallel shards, practical for small selections only (98 files took 103 s on 4 cores) | Keyed: `UBICLOUD_API_KEY`; keyless: nothing |
 | Run the curated Windows-safe subset | `bun run test:windows` (CI: six `windows-latest` jobs) | Free | Windows, Git Bash |
 | Refresh the Windows duration seed | `gh workflow run windows-free-tests.yml --ref <branch> -f record_durations=true`, then commit the `free-test-durations-windows` artifact | Free CI runners | Pushed branch, `gh` with workflow rights |
 | Run a native Windows or Dia qualification campaign | `gh workflow run native-qualification.yml --ref <branch> -f mode=<mode>` ([modes](docs/TESTING_INTERNALS.md#windows-free-lane)) | Free CI runners | Pushed branch, `gh` with workflow rights |

docs/pregate.md

@@ -246,16 +246,43 @@ the cap cannot buy a 20-minute run at the size's list price (`UBI_SIZE`,
 default `standard-16`), checks the tree and the planned file set on the VM
 before any test runs, and reports `spent=` from billed minutes. Without a key
 it runs the same files locally in parallel shards
-(`test-free-shards.ts --files-from`) and reports `spent=0`. The command is the
-same either way (`--remote` always needs a cap; the keyless path spends
-nothing). `--timeout 2700` keeps pregate's default 600 s deadline from cutting
-off a slow VM run inside its 45-minute wall (the VM's teardown runs in its own
-session, so a pregate timeout never strands it):
+(`test-free-shards.ts --files-from`) and reports `spent=0`, after a
+`backend=local (N cores; not the CI environment)` line. Paid test files in the
+selection (skill-e2e and the other paid globs in `test/helpers/paid-test-set.ts`)
+are named and left to the paid PR gate; a selection of only paid files reports
+`tests=0`, which never clears the obligation. The command is the same either way
+(`--remote` always needs a cap; the keyless path spends nothing). `--timeout
+2700` keeps pregate's default 600 s deadline from cutting off a slow VM run
+inside its 45-minute wall (the VM's teardown runs in its own session, so a
+pregate timeout never strands it):
 
 ```bash
 gstack-pregate --stage tests --remote --spend-cap 2 --timeout 2700 --allow-repo-commands
 ```
 
+Measured (October 2026): keyed, all 1,280 free files on standard-16 took 404 s
+from start to teardown (create 24 s, setup 72 s, tests 250 s) for $0.06.
+Keyless on 4 cores, 98 files took 103 s, and a 798-file pregate selection took
+3,550 s in an earlier wave, so keyless is practical for small selections only. A large selection on a small
+machine needs a key, or a `--timeout` longer than the run. Keyless also runs in
+your environment, not CI's: a file that needs what setup-free-suite.sh installs
+(Playwright's Chromium, Xvfb) fails locally until you install it.
+
+Every refusal line starts with a reason code:
+
+| code | exit | meaning |
+|---|---|---|
+| `PREGATE_REMOTE_USAGE` | 2 | an input is missing or malformed; run it through `gstack-pregate --stage tests --remote` |
+| `PREGATE_REMOTE_TREE_MISMATCH` | 3 | the working tree is not `PREGATE_TREE`; nothing uploaded, nothing spent |
+| `PREGATE_REMOTE_TREE_MOVED` | 3 | the tree changed during the run (the moved paths are listed); no result reported |
+| `PREGATE_REMOTE_VM_TREE` | 3 | the VM's unpacked tree or planned file set differs from what was checked locally |
+| `PREGATE_REMOTE_NO_RESULT` | 1 | test-free-shards printed no result (a rejected file list) |
+| `PREGATE_REMOTE_PAID_ONLY` | 0 | every selected file is a paid test file; `tests=0` cannot clear |
+| `PREGATE_REMOTE_CAP_TOO_LOW` | 5 | the cap cannot buy a 20-minute run at the size's price; nothing created |
+| `PREGATE_REMOTE_NO_PRICE` | 5 | `UBI_SIZE` has no list price in the script |
+| `PREGATE_REMOTE_INFRA` | 4 | create, setup, SSH or the wall timeout failed; the VM, its teardown line and `spent=` follow |
+| `PREGATE_REMOTE_INTERRUPTED` | 130 | TERM or INT; ubi-runner tears the VM down on its own |
+
 <a id="guards"></a>
 ## Guards and the lane-done rule
 

scripts/ubicloud/pregate-remote.sh

@@ -27,10 +27,12 @@
 # teardown) times the size's price. Without a key it runs the same files
 # locally in parallel shards and reports spent=0.
 #
-# Exit codes: 0 pass; 1 test failures (or a rejected file list); 2 missing
-# input; 3 tree or plan mismatch (or the tree moved during the run); 4
-# infrastructure failure (create, setup, SSH, wall timeout); 5 the spend cap
-# refuses the run. Nothing is uploaded or spent before the local tree check.
+# Exit codes: 0 pass (or a paid-only selection, tests=0); 1 test failures (or
+# a rejected file list); 2 missing input; 3 tree or plan mismatch (or the tree
+# moved during the run); 4 infrastructure failure (create, setup, SSH, wall
+# timeout); 5 the spend cap refuses the run. Every refusal line starts with a
+# PREGATE_REMOTE_* reason code (docs/pregate.md#remote-gate). Nothing is
+# uploaded or spent before the local tree check.
 set -euo pipefail
 # Keep heredoc bodies on temp files, not the pipe window (test/heredoc-pipe-deadlock.test.ts).
 BASH_COMPAT=50