Guard shared test hosts, protect Blaxel worker lifecycles, and rewrite the test-runner specs

.github/actions/setup-workspace/action.yml

@@ -1,7 +1,7 @@
 name: Setup workspace
 description: >-
   Select Node from .nvmrc and install the workspace via the exact-key dependency cache contract
-  (specs/arch/test-runner/github-ci.md#dependency-install). Restores
+  (specs/arch/test-runner/github-ci.md#dependency-and-browser-caches). Restores
   node_modules under a key covering the declared inputs; on a hit npm ci is
   skipped entirely; on a miss npm ci runs and the path is saved. No
   restore-keys fallback, ever.

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ concurrency:
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
-  # Tree-hash attestation decision (specs/arch/test-runner/attestation.md#skip-semantics-in-ci):
+  # Tree-hash attestation decision (specs/arch/test-runner/attestation.md#skipping-in-ci):
   # cheap, no install, always runs. Expected negative outcomes (no ref,
   # unreachable origin, disabled policy, malformed ref) complete successfully
   # with skip=false; continue-on-error keeps even an unexpected crash
@@ -111,7 +111,7 @@ jobs:
     # !cancelled(): a crashed attest-check must never suppress validation —
     # the implicit success() gate would skip the heavy tier and let the join
     # green a run with zero heavy validation
-    # (specs/arch/test-runner/attestation.md#skip-semantics-in-ci).
+    # (specs/arch/test-runner/attestation.md#skipping-in-ci).
     if: ${{ !cancelled() && (github.event_name != 'pull_request' || github.event.pull_request.draft == false) }}
     name: ${{ matrix.suite.name }}
     runs-on: ubuntu-latest
@@ -131,7 +131,7 @@ jobs:
       # the concrete required check contexts (unit, e2e:desktop) are emitted,
       # and under a skip every real step below is guarded and the job
       # fast-succeeds as an explicit no-op
-      # (specs/arch/test-runner/attestation.md#skip-semantics-in-ci).
+      # (specs/arch/test-runner/attestation.md#skipping-in-ci).
       - name: Attested skip no-op
         if: ${{ needs.attest-check.outputs.skip == 'true' && needs.attest-check.outputs.authorized == 'true' }}
         run: 'echo "attested skip: ${{ matrix.suite.name }} already proven for this tree"'
@@ -176,7 +176,7 @@ jobs:
 
       # Never assume a tool: jobs that reach the runner's cleanup paths need
       # ss and a readable /proc
-      # (specs/arch/test-runner/github-ci.md#tool-prerequisites-on-ci-workers).
+      # (specs/arch/test-runner/test-runner.md#processes-started-by-tests).
       - if: ${{ (needs.attest-check.outputs.skip != 'true' || needs.attest-check.outputs.authorized != 'true') && matrix.suite.cleanup }}
         name: Assert or install cleanup tools
         run: |
@@ -253,7 +253,7 @@ jobs:
   # One deduplicated round of the surfaces' preCommand builds
   # (test.prebuilt.mjs recipes), fanned out to the e2e shard jobs as a run
   # artifact so no shard rebuilds them
-  # (specs/arch/test-runner/github-ci.md#build-once-fan-out).
+  # (specs/arch/test-runner/github-ci.md#build-once).
   build:
     needs: [attest-check]
     # !cancelled(): run even when attest-check crashes (see the test job).
@@ -265,7 +265,7 @@ jobs:
     steps:
       # Step-level attested skip: the job still runs (the e2e shards' needs
       # require its success) and no-ops fast under a skip
-      # (specs/arch/test-runner/attestation.md#skip-semantics-in-ci).
+      # (specs/arch/test-runner/attestation.md#skipping-in-ci).
       - name: Attested skip no-op
         if: ${{ needs.attest-check.outputs.skip == 'true' && needs.attest-check.outputs.authorized == 'true' }}
         run: 'echo "attested skip: prebuilt dists not needed for this tree"'
@@ -316,7 +316,7 @@ jobs:
       # The helper packs every untracked file and symlink except dependency
       # state under node_modules and run scratch under .test-runs. Tar preserves
       # the built CLI's executable mode.
-      # (specs/arch/test-runner/github-ci.md#build-once-fan-out).
+      # (specs/arch/test-runner/github-ci.md#build-once).
       - name: Resolve artifact name and pack all untracked build output
         if: ${{ (needs.attest-check.outputs.skip != 'true' || needs.attest-check.outputs.authorized != 'true') }}
         id: prebuilt
@@ -338,7 +338,7 @@ jobs:
   # preCommand builds — the stated desktop exception). Non-unit planned
   # surfaces keep the documented 2-retry runner budget.
   # Shard jobs restore one image-bound workspace+Playwright-browser cache (pinned
-  # container deferred; specs/arch/test-runner/github-ci.md#browser-environment),
+  # container deferred; specs/arch/test-runner/github-ci.md#dependency-and-browser-caches),
   # self-seed locally on a hosted-image rollover miss, prove Chromium launches
   # on their own VM, and consume the prebuilt artifact.
   e2e:
@@ -365,7 +365,7 @@ jobs:
       # Step-level attested skip: the matrix always expands so every concrete
       # `e2e shard n/16` required context is emitted; under a skip the shard
       # fast-succeeds as an explicit no-op
-      # (specs/arch/test-runner/attestation.md#skip-semantics-in-ci).
+      # (specs/arch/test-runner/attestation.md#skipping-in-ci).
       - name: Attested skip no-op
         if: ${{ needs.attest-check.outputs.skip == 'true' && needs.attest-check.outputs.authorized == 'true' }}
         run: 'echo "attested skip: e2e shard ${{ matrix.shard }}/16 already proven for this tree"'
@@ -429,7 +429,7 @@ jobs:
             --cache-status miss
 
       # Never assume a tool: the cleanup/leak-detection path needs ss and a
-      # readable /proc (specs/arch/test-runner/github-ci.md#tool-prerequisites-on-ci-workers).
+      # readable /proc (specs/arch/test-runner/test-runner.md#processes-started-by-tests).
       - name: Assert or install cleanup tools
         if: ${{ (needs.attest-check.outputs.skip != 'true' || needs.attest-check.outputs.authorized != 'true') }}
         run: |
@@ -561,7 +561,7 @@ jobs:
   # check not applicable by skipping the job. On every non-draft event the
   # job runs even after an upstream failure, so missing, skipped, failed, or
   # cancelled dependencies cannot read as success here.
-  # (specs/arch/test-runner/github-ci.md#build-once-fan-out, Join integrity).
+  # (specs/arch/test-runner/github-ci.md#required-checks).
   e2e-required:
     if: ${{ always() && (github.event_name != 'pull_request' || github.event.pull_request.draft == false) }}
     needs: [attest-check, build, e2e, vibe-mode]
@@ -571,7 +571,7 @@ jobs:
       # attestation reaches success through step-level no-ops, so concrete
       # required contexts still emit. Drafts never enter this run path;
       # missing, skipped, failed, and cancelled dependencies all fail it.
-      # (specs/arch/test-runner/attestation.md#skip-semantics-in-ci).
+      # (specs/arch/test-runner/attestation.md#skipping-in-ci).
       - name: Require the build and all e2e shards to pass
         run: |
           vibe_result="${{ needs.vibe-mode.result }}"
@@ -642,7 +642,7 @@ jobs:
           if-no-files-found: warn
           retention-days: 30
 
-  # Attestation writer (specs/arch/test-runner/attestation.md#who-writes-and-when):
+  # Attestation writer (specs/arch/test-runner/attestation.md#who-may-write):
   # on a fully green run, publish an attestation for the validated tree. The
   # CLI re-reads the trusted origin/main policy at completion and refuses
   # (a logged no-op) on missing attest-check outputs, a disabled policy, an

AGENTS.md

@@ -46,13 +46,21 @@ UI work follows the [UI conformance spec](specs/arch/ui/conformance.md). Test re
 
 The [shared-branch workflow](specs/spec-workflow.md#^shared-branch-workflow) owns contributions to `main` and branches under `integration/`.
 
-- Development branches may be unfinished or failing; commits, pushes, and draft pull requests may be used as checkpoints.
+- Work on a development branch and commit and push regularly in safe, coherent commits. Unfinished work or failing tests may be published as development checkpoints; they do not establish readiness to merge. Pushed revisions make Blaxel validation possible.
 - To contribute, finish the work and update the development branch so it contains every commit in its target before full validation. Commit and push that tree, then open a ready pull request or mark its draft ready. Full validation may come from `npm run verify`, ready-pull-request GitHub CI, or both.
 - Merge only after human review is complete and all required GitHub checks pass. If the target moves, update the development branch and validate the resulting tree again. For staged work, every spec delta receives human acceptance before its pull request into the integration branch merges; a later pull request to `main` cannot substitute.
 
+Supervisors and coordinators must not casually tell workers to withhold development-branch commits or pushes. Routine review coordination is no reason to do so. A concrete safety or conflicting-edit issue can justify a temporary hold; a hold never lifts the local-test restrictions below.
+
 ## Testing
 
-Use the [testing policy](specs/arch/testing-policy.md) for test authoring, iteration, and verification permissions. Use the [canonical test runner](specs/arch/test-runner/test-runner.md) for commands, the [remote preflight spec](specs/arch/test-runner/preflight.md) for committed revisions, and [Blaxel setup](specs/arch/test-runner/blaxel-testshards.md) for credentials and infrastructure.
+Use the [testing policy](specs/arch/testing-policy.md) for test authoring, iteration, and verification permissions. Use the [canonical test runner](specs/arch/test-runner/test-runner.md) for commands and the [committed-revision requirement](specs/arch/test-runner/test-runner.md#^remote-revision), and [Blaxel setup](specs/arch/test-runner/blaxel-testshards.md#setup) for credentials and infrastructure.
+
+Local runs give focused feedback on the behavior being changed: `npm test -- local --file <path>`, optionally with `--grep <pattern>`. Concurrent runs can drive a shared host into swap or get processes OOM-killed, affecting every agent. Every local run and local verify holds one mutex for the same operating-system user across checkouts until its processes and cleanup finish. Contention refuses immediately; retry after the named holder finishes, use `--wait-for-local-test-mutex`, or use Blaxel when available. Do not stop another agent's run to free the mutex. The independent `--against-test-guidance-major-host-contention-and-oom-killed-processes` bypass is the caller's judgment and retains the file limit.
+
+On hosts with `~/.tvdev-use-blaxel`, local runs select at most one actual file. For anything broader, commit and push the intended revision, then use `npm test -- blaxel --surface <id>` or `npm run verify -- blaxel`. Even one remote worker takes load off the shared host. Repeated focused iteration is normal; do not split a known multi-file check into serial local runs or retry it with different selectors to evade a refusal. After a broad run finds a failure, narrow to that file before another broad check. Unmarked public-contributor and fork hosts retain local breadth and need no Blaxel access. Follow the runner's local-only suite guidance when remote execution is unavailable for that suite. Agents need explicit human permission for `--against-test-guidance-broad-local-run`; withholding pushes is no reason to use it. It does not bypass the mutex.
+
+Direct Vitest and Playwright entrypoints refuse by default. Deliberate native watch, debug or editor use can set `TV_TEST_AGAINST_TEST_GUIDANCE_DIRECT_NATIVE_RUN=1` at the caller's judgment; that route skips the canonical mutex and file limit and still needs native configuration and services. Keep validation on the canonical path. Plain `--retries 0` is allowed for running a new or changed test once within one explicit file. Broader validation uses default retries; `--against-test-guidance-turn-flakes-into-failures-on-broad-runs` deliberately disables that budget at the caller's judgment and lifts no other guardrail. The runner guides safe, fast choices; its signals and overrides are not a security boundary.
 
 ## Commits
 

developer-skills/tvdev-contribute/SKILL.md

@@ -21,6 +21,8 @@ touch ~/.tv-developer
 
 ## Work through shared branches
 
+Contributors and agents work on development branches and commit and push regularly in safe, coherent commits under the [workflow](../../specs/spec-workflow.md#^shared-branch-workflow). Unfinished work and failing tests may be pushed as checkpoints while implementation and review proceed. Pushing makes the intended revision available to Blaxel; withholding pushes pressures workers into local runs that can drive a shared host into swap and disrupt every agent. Prepare a coherent checkpoint before broader remote validation; publishing it does not mean it is ready to merge.
+
 Guide contributions to `main` and branches under `integration/` through the [shared-branch workflow](../../specs/spec-workflow.md#^shared-branch-workflow). Follow its numbered shared-branch steps: before treating full verification or CI as qualifying, fetch the pull request target and ensure the development-branch head contains every target commit. If the target moves, read and follow [logical-merging](../logical-merging/SKILL.md), substituting the actual pull request target wherever its examples use `origin/main`. Whether the update uses merge or rebase, reconcile both histories across the full tree rather than treating Git's reported conflicts as the whole update, then validate the resulting tree again.
 
 Apply [the workflow's shared-branch review rule](../../specs/spec-workflow.md#^shared-branch-spec-review) to the pull request being prepared. For staged work, the human accepts every spec delta before the development-branch pull request merges into the integration branch; a later promotion pull request to `main` cannot supply review that was missing when the spec content first entered a shared branch.
@@ -61,6 +63,8 @@ After the human hands over the agreed intent, carry all remaining derivable work
 
 When multiple agents are available, a supervisor holds the overall goal and arranges handoffs. Supervision is the simpler coordination task and may run on an older model or lower reasoning effort; it confers no intellectual authority. Match model capability and reasoning effort to the delegated work. Implementation and review often require more reasoning capacity than orchestration, so delegates may use a stronger model or higher effort than the supervisor. Follow the review policy when selecting reviewers. Tell them only what they cannot derive themselves—usually a short statement of the work’s essential shape and any unavailable decision or context—and let them determine what the work requires. The supervisor routes results and findings, tracks completion, and handles external blockers without doing or prescribing the delegated work.
 
+Supervisors and coordinators must not casually tell workers not to commit or push on their development branches. Routine review coordination is no reason to suspend that practice. A concrete safety or conflicting-edit issue may justify a temporary hold, but required testing still respects the local-run limits during the hold.
+
 Keep the human informed at meaningful transitions about what has been established and what remains. When a decision needs them, explain the unresolved choice and its consequences. Handle routine derivation and review coordination directly.
 
 After the spec gate, derive and independently converge the proofs under proof policy (`specs/spec-proofs.md`). If proof derivation exposes an unclear expected result, resolve it in the owning spec and return the affected work through review. Surface unresolved design or architectural decisions to the human for a ruling, and pause work that depends on them.
@@ -69,6 +73,10 @@ Follow the workflow (`specs/spec-workflow.md`, “Planning and slices”) to der
 
 Use red/green TDD to implement the tests required by the proofs and the behavior that makes them pass under testing policy (`specs/arch/testing-policy.md`). The test runner (`specs/arch/test-runner/test-runner.md`) supplies execution procedures. Passing tests is part of completion; the running result must satisfy the whole promised outcome.
 
+Use `npm test -- local --file <path>` with optional `--grep` for focused feedback. Local runs share a same-user mutex across checkouts: follow a contention refusal, use `--wait-for-local-test-mutex`, or move work to Blaxel when available. On hosts with `~/.tvdev-use-blaxel`, broader checks use committed, pushed revisions on Blaxel, even when the selection runs on one worker. Do not divide known multi-file validation into serial local runs. Without the marker, local breadth and verification remain available without Blaxel access. Follow the testing policy's permission rule for broader local runs and the runner's independent overrides for contention and direct native tools.
+
+Keep the default retry budget for validation. Plain `--retries 0` is appropriate when deliberately running a new or changed test once within one file; broader zero retries require the runner's `--against-test-guidance-turn-flakes-into-failures-on-broad-runs` option. Diagnose a broad-run failure with a focused check, fix it there, then return to broader validation.
+
 Arrange convergence under the workflow’s “Independent review and convergence” (`specs/spec-workflow.md`), including its independent-review and bounded refinement rules. Give the reviewer [tvdev-review](../tvdev-review/SKILL.md) in a separate context using the highest-quality model at extra-high (`xhigh`) reasoning effort. `xhigh` (X H I G H) is an exact value that must be preserved. Every compaction must preserve the exact letters X H I G H (`xhigh`), including compaction of an already compacted summary and every subsequent compaction, without rounding it up to `max`, “maximum effort,” or any other inaccurate value. Prefer a state-of-the-art model from a different provider than the implementer; report the actual setup and any unmet requirement. Read the [review delegation reference](references/review-delegation.md) when arranging dispatch, or route the result to the supervisor who owns it. Return the full review, including PASS, to the work’s owner. After FAIL, the owner assesses all findings, remediates warranted ones, and returns the whole result for review. After PASS, consider worthwhile refinements under the policy’s bounded rule; PASS should normally conclude review, not start an endless polish loop. If convergence appears stuck, involve the human. Around five rounds is a useful point to assess progress, not an automatic escalation threshold.
 
 Carry UI work through the same workflow, adding visual assessment alongside functional coverage. Assess the design preview and running implementation separately. Examine neighboring surfaces and meaningful states, and clarify interactions that appearance leaves unresolved. UI specification (`specs/spec-ui.md`) and conformance policy (`specs/arch/ui/conformance.md`) govern visual completeness alongside functional coverage.

developer-skills/tvdev-review/SKILL.md

@@ -22,6 +22,8 @@ Television derives specs → proofs → tests → code, with implementation plan
 
 These are orientations, not exhaustive criteria. Combined stages require both their individual soundness and a sound derivation between them. Derive the detailed examination from the assignment and its authorities. Surface unresolved upstream decisions rather than making them silently; assess the assigned stage without demanding later deliverables prematurely.
 
+Regular safe, coherent commits and pushes on the author's development branch enable remote validation while review proceeds; under the [workflow](../../specs/spec-workflow.md#^shared-branch-workflow), they are ordinary checkpoints, not claims of merge readiness, and routine review coordination is no reason to withhold them. Review validation under the [testing policy](../../specs/arch/testing-policy.md#test-iteration-discipline): focused local files, broader pushed Blaxel selections on marked hosts, and default retries for broader validation.
+
 ## Exercise review judgment
 
 PASS means no blockers, where “blocker” is left to agent judgment.