Repair Workspace Manager blank game launch

PR Details:
- Fixes blank Workspace Manager page for game-launched URLs.
- Requires visible diagnostics for invalid boot/context/view state.
- Preserves explicit gameId behavior.
- Does not restore legacy gameId || game fallback.
- Does not restore first-tool/default selection.
- Leaves sample Open <tool> behavior untouched.

Author: DavidQ

docs/dev/codex_rules.md

@@ -4,10 +4,10 @@ These rules OVERRIDE all other instructions.
 
 ## This PR
 
-Fix only the Workspace Manager initial view for game-launched context.
+Fix only the Workspace Manager blank-page blocker for game-launched context.
 
 Allowed:
-- targeted Workspace Manager launch/view selection edits
+- targeted Workspace Manager boot/render/view diagnostics repair
 - validation report
 
 Forbidden:
@@ -21,27 +21,19 @@ Forbidden:
 - start_of_day changes
 - roadmap text rewrite outside status markers
 
-## Required UI Labels
+## Required URL
 
-Samples:
-- must remain `Open <tool>`
-
-Games:
-- must remain `Open with Workspace Manager`
-
-## Required Game Launch Behavior
-
-For:
+This URL must render visible Workspace Manager content:
 
 ```text
-tools/Workspace Manager/index.html?gameId=<id>&mount=game
+tools/Workspace Manager/index.html?gameId=Breakout&mount=game
 ```
 
-`mount=game` means the source/context is a game.
+## Diagnostic Requirement
 
-It must not force the initial primary view to be the hosted game surface.
+Blank page is forbidden.
 
-Workspace Manager must show the tools/workspace surface for the explicit game context.
+Any boot/context/view failure must render visible diagnostic text on the page.
 
 ## Forbidden Restorations
 
@@ -53,6 +45,7 @@ Do not restore:
 - default tool
 - default workspace
 - fallback route
+- fallback view
 - stale memory reuse
 
 ## Anti-Patterns Forbidden
@@ -65,6 +58,7 @@ Do not restore:
 - hidden fallback behavior
 - duplicated launch paths
 - silent redirects
+- silent caught errors
 - broad truthy/falsy behavior changes
 - magic strings outside existing SSoT/config pattern
 - duplicate event listeners

docs/dev/reports/workspace_manager_blank_game_launch_repair_validation.md

@@ -0,0 +1,157 @@
+# Workspace Manager Blank Game Launch Repair Validation
+
+## Changed Files
+
+- `tools/Workspace Manager/index.html`
+- `tools/Workspace Manager/main.js`
+- `tools/Workspace Manager/toolHost.css`
+- `docs/dev/reports/workspace_manager_blank_game_launch_repair_validation.md`
+
+## Root Cause Of Blank Page
+
+- `tools/Workspace Manager/index.html` previously rendered only an empty mount container.
+- `tools/Workspace Manager/main.js` status/diagnostic writes targeted elements that did not exist in that HTML (`[data-tool-host-status]`, controls, diagnostic surface).
+- For game-launched URLs without an immediately mounted frame, the page had no visible shell or visible error target, which presented as blank.
+
+## Proof Breakout URL Renders Visible Content
+
+Required URL:
+
+```text
+tools/Workspace Manager/index.html?gameId=Breakout&mount=game
+```
+
+Visible shell is now always present in HTML:
+
+- tool selector: `tools/Workspace Manager/index.html:13`
+- status node: `tools/Workspace Manager/index.html:23`
+- diagnostic panel: `tools/Workspace Manager/index.html:24-26`
+- mount surface: `tools/Workspace Manager/index.html:30`
+
+Breakout resolves as valid game launch target and game id exists:
+
+```text
+Breakout true /games/Breakout/index.html
+launch Breakout /tools/Workspace%20Manager/index.html?gameId=Breakout&mount=game
+```
+
+Game-launch init path now leaves visible shell and visible status (`Select a tool to mount.`) instead of blank when no explicit tool is requested:
+
+- `tools/Workspace Manager/main.js:691`
+
+## Proof Multiple `gameId`s Do Not Blank
+
+Resolver and metadata check output:
+
+```text
+Breakout true /games/Breakout/index.html
+Pong true /games/Pong/index.html
+Asteroids true /games/Asteroids/index.html
+launch Breakout /tools/Workspace%20Manager/index.html?gameId=Breakout&mount=game
+launch Pong /tools/Workspace%20Manager/index.html?gameId=Pong&mount=game
+launch Asteroids /tools/Workspace%20Manager/index.html?gameId=Asteroids&mount=game
+```
+
+With the always-visible shell in `index.html` plus explicit init status handling in `main.js`, these valid game-launched URLs render visible Workspace Manager content instead of a blank screen.
+
+## Proof Invalid/Missing `gameId` Renders Visible Diagnostic
+
+Diagnostic panel exists in page:
+
+- `tools/Workspace Manager/index.html:24-26`
+
+Missing/invalid game context now writes visible diagnostic messages (not silent):
+
+- missing `gameId` on game launch:
+  - `tools/Workspace Manager/main.js:602`
+  - `tools/Workspace Manager/main.js:662`
+- invalid `gameId` on game launch:
+  - `tools/Workspace Manager/main.js:609`
+  - `tools/Workspace Manager/main.js:669`
+
+Additional boot/view failure diagnostics added:
+
+- mount surface unavailable: `tools/Workspace Manager/main.js:654`
+- runtime error: `tools/Workspace Manager/main.js:701`
+- unhandled rejection: `tools/Workspace Manager/main.js:709`
+- init failure: `tools/Workspace Manager/main.js:716`
+- import/load failure diagnostic in `index.html:33-41`
+
+## Proof `gameId || game` Fallback Is Not Restored
+
+Command output:
+
+```text
+gameIdOrGame 0
+legacyGameParamRead 0
+```
+
+- `tools/Workspace Manager/main.js` contains no `gameId || game` and no `searchParams.get("game")` fallback read.
+
+## Proof `toolIds[0]` First-Tool Selection Is Not Restored
+
+Command output:
+
+```text
+toolIds0 0
+```
+
+- `tools/Workspace Manager/main.js` contains no `toolIds[0]` first-item selection fallback.
+
+## Proof No Fallback/Default Route/View Was Added
+
+- No auto hosted-game mount restoration was added in launch path:
+
+```text
+awaitMountGameFrame 0
+voidMountGameFrame 0
+```
+
+- For game-launch with no explicit tool, code writes explicit status and returns (`tools/Workspace Manager/main.js:621`, `tools/Workspace Manager/main.js:691`) instead of selecting defaults.
+- No fallback to legacy `game` query param exists.
+
+## Proof External Launch Memory Clear Remains Intact
+
+Runtime check output:
+
+```text
+clearResult true
+localAfterClear [ [ 'keep.one', 'x' ] ]
+sessionAfterClear [ [ 'keep.two', 'y' ] ]
+launchResult true
+assignCalls [ '/tools/Workspace%20Manager/index.html?gameId=Breakout&mount=game' ]
+localAfterLaunch [ [ 'keep.one', 'x' ] ]
+sessionAfterLaunch [ [ 'keep.two', 'y' ] ]
+```
+
+- Clear remains in `tools/shared/toolLaunchSSoT.js:121-136`.
+- External launch still clears then navigates in `tools/shared/toolLaunchSSoT.js:138-145`.
+
+## Proof Sample `Open <tool>` Behavior Remains Untouched
+
+- Sample label logic remains `Open <tool>` at `samples/index.render.js:104`.
+- Sample external launch flow remains `launchWithExternalToolWorkspaceReset(launchHref)` at `samples/index.render.js:539`.
+- This BUILD did not modify sample files.
+
+## Static Validation
+
+Commands run:
+
+```bash
+node --check tools/Workspace\ Manager/main.js
+node --check tools/shared/toolLaunchSSoT.js
+node --check games/index.render.js
+node --check samples/index.render.js
+```
+
+All passed.
+
+## Anti-Pattern Self-Check
+
+- No second SSoT introduced.
+- No samples/game label changes introduced.
+- No legacy query fallback restored.
+- No first-item/default tool selection restored.
+- No fallback/default route/view/tool/workspace behavior added.
+- No broad Workspace Manager refactor performed.
+- No start_of_day files changed.

docs/operations/dev/codex_commands.md

@@ -1,4 +1,4 @@
-# Codex Commands — BUILD_PR_LEVEL_20_14_WORKSPACE_MANAGER_SHOW_TOOLS_ON_GAME_LAUNCH
+# Codex Commands — BUILD_PR_LEVEL_20_15_REPAIR_WORKSPACE_MANAGER_BLANK_GAME_LAUNCH
 
 ## Model
 GPT-5.4 or GPT-5.3-codex
@@ -10,58 +10,60 @@ High
 
 ```text
 Read docs/dev/codex_rules.md first.
-Read docs/dev/specs/TOOL_LAUNCH_SSOT.md if present.
+Read docs/dev/reports/workspace_manager_game_launch_tools_view_validation.md if present.
 Read docs/dev/reports/workspace_manager_default_query_fallback_removal_validation.md if present.
+Read docs/dev/specs/TOOL_LAUNCH_SSOT.md if present.
 
-Execute BUILD_PR_LEVEL_20_14_WORKSPACE_MANAGER_SHOW_TOOLS_ON_GAME_LAUNCH.
+Execute BUILD_PR_LEVEL_20_15_REPAIR_WORKSPACE_MANAGER_BLANK_GAME_LAUNCH.
 
-User UAT finding:
-- Samples appear to work: Open <tool> opens tool and data appears.
-- Games path opens Workspace Manager, but Workspace Manager shows the game, not the tools.
+User UAT failure:
+- URL renders blank page with no visible error:
+  tools/Workspace Manager/index.html?gameId=Breakout&mount=game
+- Blank occurs for multiple Open with Workspace Manager launches.
 
 Goal:
-Fix only the Workspace Manager initial view for game-launched context.
+Repair Workspace Manager so valid game-launched URLs render visible Workspace Manager content and invalid context renders visible diagnostics.
 
 Required behavior:
-- games/index.html -> Open with Workspace Manager -> tools/Workspace Manager/index.html?gameId=<id>&mount=game
-- Workspace Manager opens
+- URL tools/Workspace Manager/index.html?gameId=Breakout&mount=game renders visible Workspace Manager page
 - explicit gameId context is loaded
 - external launch memory is cleared
-- initial primary view shows tools/workspace surface for that game context
-- it must not immediately show the hosted game surface
-- it must not auto-select the first tool
-- it must not fallback to game query param
-- it must not reuse stale memory
-
-Clarification:
-`mount=game` means source/context is game-launched.
-It must not force the initial display to the hosted game surface.
+- tools/workspace surface is visible for selected game context
+- blank page is forbidden
+- if boot/context/view fails, render visible diagnostic panel on page
+- do not restore gameId || game
+- do not restore toolIds[0]
+- do not auto-select first tool
+- do not fallback to default route/view/tool/workspace
+- do not reuse stale memory
 
-Likely target:
+Likely files:
+- tools/Workspace Manager/index.html
 - tools/Workspace Manager/main.js
+- directly imported Workspace Manager boot/view helper files only if needed
 
 Forbidden:
 - changing samples
 - changing labels
-- restoring gameId || game
-- restoring toolIds[0]
 - broad Workspace Manager refactor
 - second SSoT
 - fallback/default behavior
 - start_of_day changes
 
 Validation:
-Create docs/dev/reports/workspace_manager_game_launch_tools_view_validation.md with:
+Create docs/dev/reports/workspace_manager_blank_game_launch_repair_validation.md with:
 - changed files
-- proof Open with Workspace Manager still routes to Workspace Manager
-- proof explicit gameId is still required
+- root cause of blank page
+- proof Breakout URL renders visible content
+- proof multiple gameIds do not blank
+- proof invalid/missing gameId renders visible diagnostic
 - proof gameId || game fallback is not restored
 - proof toolIds[0] first-tool selection is not restored
-- proof external launch memory clear remains intact
-- proof initial game-launched Workspace Manager view shows tools/workspace surface, not game surface
+- proof no fallback/default route/view was added
+- proof external memory clear remains intact
 - proof sample Open <tool> behavior remains untouched
 - anti-pattern self-check
 
 Return ZIP at:
-tmp/BUILD_PR_LEVEL_20_14_WORKSPACE_MANAGER_SHOW_TOOLS_ON_GAME_LAUNCH.zip
+tmp/BUILD_PR_LEVEL_20_15_REPAIR_WORKSPACE_MANAGER_BLANK_GAME_LAUNCH.zip
 ```

docs/operations/dev/commit_comment.txt

@@ -1,9 +1,9 @@
-Show tools surface on game-launched Workspace Manager open
+Repair Workspace Manager blank game launch
 
 PR Details:
-- Fixes Workspace Manager initial view for games/index.html Open with Workspace Manager.
-- Keeps explicit gameId context.
-- Keeps memory clear behavior.
-- Prevents mount=game from immediately showing the hosted game surface.
-- Does not restore fallback/default launch behavior.
+- Fixes blank Workspace Manager page for game-launched URLs.
+- Requires visible diagnostics for invalid boot/context/view state.
+- Preserves explicit gameId behavior.
+- Does not restore legacy gameId || game fallback.
+- Does not restore first-tool/default selection.
 - Leaves sample Open <tool> behavior untouched.