Add smart lane scheduling and reusable Playwright runtime sessions to reduce redundant startup and deterministic rerun waste - PR_26146_029-lane-session-reuse-and-smart-scheduling

Author: ToolboxAid

.gitignore

@@ -17,6 +17,7 @@ NEXT_COMMAND.txt
 node_modules/
 tests/results/
 tmp/
+scripts/untracked/
 
 # Codex files
 docs/dev/codex_commands.md
@@ -33,3 +34,5 @@ docs/dev/reports/playwright_v8_coverage_report.txt
 
 *.mp4
 *.mkv
+
+

docs/dev/reports/dependency_gating_report.md

@@ -0,0 +1,32 @@
+# Dependency Gating Report
+
+Generated: 2026-05-26T19:04:26.917Z
+Status: PASS
+
+## Gate Order
+
+1. Zero-browser preflight must pass.
+2. Lane compilation must pass.
+3. Deterministic lane dependency validation must pass.
+4. Only dependency-eligible targeted lanes may be scheduled.
+
+## Lane Dependency Graph
+
+| Lane | Selected | Status | Dependencies | Affected Surface | Reason |
+| --- | --- | --- | --- | --- | --- |
+| workspace-contract | No | SKIP | none | Workspace Manager V2 contract and lifecycle behavior | Lane was not selected, so dependency-gated runtime scheduling skipped it. |
+| tool-runtime | Yes | PASS | none | First-class tool runtime behavior | Lane has no lane dependencies and is eligible after preflight and compilation pass. |
+| integration | Yes | PASS | none | Workspace, tool, game index, and manifest handoff behavior | Lane has no lane dependencies and is eligible after preflight and compilation pass. |
+| engine-src | No | SKIP | none | src/ engine and shared runtime capability behavior | Lane was not selected, so dependency-gated runtime scheduling skipped it. |
+| samples | No | SKIP | none | Affected samples lane, on request only | Lane was not selected, so dependency-gated runtime scheduling skipped it. |
+
+## Dependency Failures Caught Pre-Runtime
+
+No deterministic dependency failures were found before runtime.
+
+## Enforcement Notes
+
+- Invalid dependency graphs block runtime before Playwright startup.
+- Dependency failures do not trigger fallback reruns or unrelated lane execution.
+- Workspace V2 is scheduled only when the workspace-contract lane is explicitly selected.
+- Samples remain on-request only and are not implicit dependency gates.

docs/dev/reports/lane_compilation_report.md

@@ -1,35 +1,26 @@
 # Lane Compilation Report
 
-Generated: 2026-05-26
-PR: PR_26146_028-zero-browser-preflight-and-lane-compilation
+Generated: 2026-05-26T19:04:26.917Z
+Status: PASS
 
-## Summary
+## Lane Graph
 
-Status: PASS
-Lane compilation failures: none
-Runtime discovery failures prevented: none needed
+| Lane | Status | Affected Surface | Targets | Commands | Reason |
+| --- | --- | --- | --- | --- | --- |
+| workspace-contract | SKIP | Workspace Manager V2 contract and lifecycle behavior | none | npm.cmd run test:workspace-v2 | Lane was not selected. |
+| tool-runtime | PASS | First-class tool runtime behavior | tests/playwright/tools/AssetManagerV2.spec.mjs; tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs; tests/playwright/tools/CollisionInspectorV2.spec.mjs | C:\nvm4w\nodejs\node.exe C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\node_modules\@playwright\test\cli.js test tests/playwright/tools/AssetManagerV2.spec.mjs --grep "launch guard|temporary UAT context|rejects non-Workspace" --project=playwright --workers=1 --reporter=list; C:\nvm4w\nodejs\node.exe C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\node_modules\@playwright\test\cli.js test tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list | Lane graph, command shape, targets, fixtures, and ownership compile before runtime. |
+| integration | PASS | Workspace, tool, game index, and manifest handoff behavior | tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs | C:\nvm4w\nodejs\node.exe C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\node_modules\@playwright\test\cli.js test tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs --grep Pong --project=playwright --workers=1 --reporter=list | Lane graph, command shape, targets, fixtures, and ownership compile before runtime. |
+| engine-src | SKIP | src/ engine and shared runtime capability behavior | scripts/run-node-test-files.mjs; tests/core/EngineCoreBoundaryBaseline.test.mjs; tests/core/FrameClock.test.mjs; tests/core/FixedTicker.test.mjs; tests/assets/AssetLoaderSystem.test.mjs; tests/audio/AudioService.test.mjs; tests/input/InputMap.test.mjs; tests/input/KeyboardState.test.mjs; tests/input/MouseState.test.mjs; tests/input/GamepadInputAdapter.test.mjs; tests/input/GamepadHapticsService.test.mjs; tests/render/Renderer.test.mjs | C:\nvm4w\nodejs\node.exe scripts/run-node-test-files.mjs tests/core/EngineCoreBoundaryBaseline.test.mjs tests/core/FrameClock.test.mjs tests/core/FixedTicker.test.mjs tests/assets/AssetLoaderSystem.test.mjs tests/audio/AudioService.test.mjs tests/input/InputMap.test.mjs tests/input/KeyboardState.test.mjs tests/input/MouseState.test.mjs tests/input/GamepadInputAdapter.test.mjs tests/input/GamepadHapticsService.test.mjs tests/render/Renderer.test.mjs | Lane was not selected. |
+| samples | SKIP | Affected samples lane, on request only | scripts/run-node-test-files.mjs; tests/samples/SamplesProgramCombinedPass.test.mjs; tests/samples/FullscreenRuleEnforcement.test.mjs | C:\nvm4w\nodejs\node.exe scripts/run-node-test-files.mjs tests/samples/SamplesProgramCombinedPass.test.mjs tests/samples/FullscreenRuleEnforcement.test.mjs | Lane was not selected. |
 
-## Compiled Lane Graph
+## Compilation Failures
 
-| Lane | Status | Runtime Execution | Targets | Reason |
-| --- | --- | --- | --- | --- |
-| workspace-contract | PASS | Skipped | `npm run test:workspace-v2` | Lane definition compiles and fixture path resolves; not selected for affected runtime validation. |
-| tool-runtime | PASS | Executed | `tests/playwright/tools/AssetManagerV2.spec.mjs`; `tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs`; `tests/playwright/tools/CollisionInspectorV2.spec.mjs` | Selected affected lane. Targets are inside `tests/playwright/tools`; grep pipe is Node-argv safe. |
-| integration | PASS | Executed | `tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs` | Selected affected lane. Target is inside `tests/playwright/integration`. |
-| engine-src | PASS | Skipped | node engine/src test files | Lane definition compiles; not affected by this PR. |
-| samples | PASS | Skipped | node samples test files | Lane definition compiles; samples lane remains on-request and sample scope was not active. |
+No lane compilation failures.
 
-## Compilation Rules
+## Deterministic Setup Rules
 
 - Unknown lanes fail before runtime.
-- Missing targets, fixtures, or helper imports fail before runtime.
+- Missing targets or fixtures fail before runtime.
 - Playwright targets must stay inside the owning lane directory.
-- Shell-sensitive grep values must use the Node CLI argv path.
+- Shell-sensitive grep values must be passed through the Node CLI argv path.
 - Deterministic lane-definition failures do not trigger fallback reruns or full lane escalation.
-
-## Runtime Savings Observations
-
-- Lane graph resolution happens before browser startup.
-- Invalid targeted lane setup cannot fall through into runtime discovery.
-- Tool-runtime combines Preview Generator V2 and Collision Inspector V2 into one Playwright CLI invocation.
-- Workspace V2 was not scheduled for this PR.

docs/dev/reports/lane_runtime_optimization_report.md

@@ -0,0 +1,35 @@
+# Lane Runtime Optimization Report
+
+Generated: 2026-05-26T19:04:26.917Z
+Status: PASS
+
+## Runtime Cost Summary
+
+Reused runtime sessions: 2
+Prevented redundant browser launches: 1
+Prevented redundant lane execution: 3
+Baseline Playwright/browser launches: 4
+Scheduled Playwright/browser launches: 3
+
+## Scheduled Lane Order
+
+1. tool-runtime
+2. integration
+
+## Scheduling Blockers
+
+No zero-browser, compilation, or dependency blockers were found.
+
+## Lane Plans
+
+| Lane | Baseline Browser Launches | Scheduled Browser Launches | Commands | Reason |
+| --- | --- | --- | --- | --- |
+| tool-runtime | 3 | 2 | C:\nvm4w\nodejs\node.exe C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\node_modules\@playwright\test\cli.js test tests/playwright/tools/AssetManagerV2.spec.mjs --grep "launch guard|temporary UAT context|rejects non-Workspace" --project=playwright --workers=1 --reporter=list; C:\nvm4w\nodejs\node.exe C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\node_modules\@playwright\test\cli.js test tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list | Tool runtime lane validates focused tool behavior without treating unrelated stale product assertions as blockers. |
+| integration | 1 | 1 | C:\nvm4w\nodejs\node.exe C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\node_modules\@playwright\test\cli.js test tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs --grep Pong --project=playwright --workers=1 --reporter=list | Integration lane validates explicit cross-surface handoffs only; broad all-game thumbnail coverage is outside the default targeted lane. |
+
+## Runtime Savings Observations
+
+- Zero-browser preflight, lane compilation, and dependency validation run once per targeted runner invocation.
+- Compatible Playwright specs with matching options are kept in shared CLI invocations to avoid redundant browser startup.
+- Unselected lanes are not scheduled after isolated targeted lane failures.
+- Workspace V2 and samples lanes are not escalated unless explicitly selected.

docs/dev/reports/playwright_structure_audit.md

@@ -1,6 +1,6 @@
 # Playwright Structure Audit
 
-Generated: 2026-05-26T18:25:51.107Z
+Generated: 2026-05-26T19:04:26.887Z
 Status: PASS
 
 ## Lane Directories

docs/dev/reports/static_validation_report.md

@@ -1,14 +1,14 @@
 # Static Validation Report
 
-Generated: 2026-05-26T18:25:51.151Z
+Generated: 2026-05-26T19:04:26.914Z
 Status: PASS
 Static only: No
 Dry run: No
 
 ## Requested Lanes
 
-- integration
 - tool-runtime
+- integration
 
 ## Prevented Launches
 

docs/dev/reports/testing_lane_execution_report.md

@@ -1,50 +1,72 @@
 # Testing Lane Execution Report
 
-Generated: 2026-05-26
-PR: PR_26146_028-zero-browser-preflight-and-lane-compilation
+Generated: 2026-05-26T19:05:55.095Z
+Dry run: No
 
 ## Summary
 
-PASS: 3
+PASS: 2
 WARN: 0
 FAIL: 0
 SKIP: 3
 
 ## Full Samples Smoke
 
 Status: SKIP
-Reason: This PR changes zero-browser preflight, lane compilation, and targeted lane routing only. No sample JSON, shared sample loader, or sample framework files were changed.
+Reason: Skipped because changed files do not modify sample JSON or shared sample loader/framework behavior.
 
-## Executed and Skipped Lanes
+## Preflight
 
-| Lane / Check | Status | Executed/Skipped Reason | Affected Surface | Evidence |
-| --- | --- | --- | --- | --- |
-| zero-browser-preflight | PASS | Executed first to prove deterministic setup checks run before Playwright runtime initialization. | Placement, ownership, registrations, imports, fixtures, helpers, grep, quoting, lane references, lane configuration | `npm run test:playwright:zero-browser` passed and wrote zero-browser plus lane compilation reports. |
-| tool-runtime | PASS | Executed because lane compilation and zero-browser routing changed. | Asset Manager V2, Preview Generator V2, Collision Inspector V2 runtime tests | `PLAYWRIGHT_BROWSERS_PATH=0 node ./scripts/run-targeted-test-lanes.mjs --lanes integration,tool-runtime`; Asset Manager focused subset 5 passed, Preview Generator and Collision Inspector combined run 11 passed. |
-| integration | PASS | Executed because the integration lane remains part of the affected compiled lane graph. | Game index preview manifest handoff | Same combined runner command; focused Pong handoff subset 3 passed. |
-| workspace-contract | SKIP | Skipped because zero-browser preflight does not require Workspace V2 launch and Workspace V2 runtime wiring was not changed. | Workspace Manager V2 contract/lifecycle behavior | Not run. |
-| engine-src | SKIP | Skipped because no `src/`, engine Playwright, or node engine lane targets changed. | src/ engine/shared runtime behavior | Not run. |
-| samples | SKIP | Skipped because samples are on-request or affected-sample only and this PR did not impact samples. | On-request samples lane | Not run. |
+Status: PASS
+Reason: Runner preflight and Playwright structure audit passed before expensive lane execution.
+Command: C:\nvm4w\nodejs\node.exe scripts/audit-playwright-test-locations.mjs
+Details: Lane tool-runtime grep pattern is passed as a literal Node argv value: launch guard|temporary UAT context|rejects non-Workspace
+
+## Dependency Gate
+
+Status: PASS
+Reason: No deterministic dependency failures before runtime.
+
+## Runtime Scheduling
 
-## Prevented Launches and Fast-Fail Reasons
+Status: PASS
+Scheduled lane order: tool-runtime, integration
+Reused runtime sessions: 2
+Prevented redundant browser launches: 1
+Prevented redundant lane execution: 3
 
-- Prevented browser launches: 0 in this validation run because no deterministic pre-runtime failures were found.
-- Fast-fail reasons: none.
-- If preflight finds placement, helper ownership, import, fixture, lane reference, lane configuration, grep, or quoting failures, the runner exits before Playwright/browser startup.
+## Validation Sequence
+
+- PASS zero-browser preflight first: `npm run test:playwright:zero-browser`
+- PASS lane compilation validation second: `node ./scripts/run-targeted-test-lanes.mjs --zero-browser-only --lanes tool-runtime,integration`
+- PASS affected targeted runtime lanes after dependency validation: `PLAYWRIGHT_BROWSERS_PATH=0 node ./scripts/run-targeted-test-lanes.mjs --lanes tool-runtime,integration`
+- SKIP Workspace V2 lane: no Workspace V2 contract behavior was changed, and workspace-contract lane was not in scope.
+- SKIP full samples smoke: changed files do not modify sample JSON or shared sample loader/framework behavior.
+
+## Lanes
+
+| Lane | Status | Executed/Skipped Reason | Affected Surface | Fixtures / Inputs |
+| --- | --- | --- | --- | --- |
+| workspace-contract | SKIP | Lane was not selected for this targeted run. | Workspace Manager V2 contract and lifecycle behavior | tests/fixtures/workspace-v2/uat.manifest.json; mocked File System Access repo handles; explicit game manifest/toolState payloads |
+| tool-runtime | PASS | Tool runtime lane validates focused tool behavior without treating unrelated stale product assertions as blockers. | First-class tool runtime behavior | tool-specific mocked repo/file picker inputs; explicit manifest/toolState launch contexts |
+| integration | PASS | Integration lane validates explicit cross-surface handoffs only; broad all-game thumbnail coverage is outside the default targeted lane. | Workspace, tool, game index, and manifest handoff behavior | repo game manifests; manifest preview asset roles; repo-served browser pages |
+| engine-src | SKIP | Lane was not selected for this targeted run. | src/ engine and shared runtime capability behavior | explicit node unit fixtures; fresh in-memory localStorage/sessionStorage mocks per file |
+| samples | SKIP | Lane was not selected for this targeted run. | Affected samples lane, on request only | sample metadata and validation artifacts; sample structure fixtures |
 
-## Corrected Ownership Drift
+## Commands
 
-- No new misplaced tests or helpers were found in this PR.
-- Existing corrections remain enforced: Asteroids game specs under `tests/playwright/games`, integration handoff under `tests/playwright/integration`, documented game fixtures only in tool tests.
+### workspace-contract
+- SKIP
 
-## Runtime Savings Observations
+### tool-runtime
+- PASS C:\nvm4w\nodejs\node.exe C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\node_modules\@playwright\test\cli.js test tests/playwright/tools/AssetManagerV2.spec.mjs --grep "launch guard|temporary UAT context|rejects non-Workspace" --project=playwright --workers=1 --reporter=list
+- PASS C:\nvm4w\nodejs\node.exe C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\node_modules\@playwright\test\cli.js test tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list
 
-- Zero-browser preflight ran before browser startup.
-- Affected lanes ran in one Node lane-runner process.
-- Preview Generator V2 and Collision Inspector V2 ran through one Playwright CLI invocation.
-- Workspace V2, engine/src, samples, and full samples smoke were not started.
+### integration
+- PASS C:\nvm4w\nodejs\node.exe C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\node_modules\@playwright\test\cli.js test tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs --grep Pong --project=playwright --workers=1 --reporter=list
 
-## Static Validation
+### engine-src
+- SKIP
 
-- PASS `node --check scripts/run-targeted-test-lanes.mjs`
-- PASS `node --check scripts/audit-playwright-test-locations.mjs`
+### samples
+- SKIP