Expose runtime repo binding state without serializing browser file handles - PR_26130_005-runtime-handle-state-visibility

Author: DavidQ

.gitignore

@@ -19,6 +19,8 @@ tests/results/
 tmp/
 
 # Codex files
+docs/dev/codex_commands.md
+docs/dev/commit_comment.txt
 codex_changed_files.txt
 docs/dev/reports/codex_changed_files.txt
 codex_review.diff

docs/dev/reports/PR_26130_005-runtime-handle-state-visibility.md

@@ -0,0 +1,74 @@
+# PR_26130_005-runtime-handle-state-visibility
+
+## Summary
+
+- Added serializable runtime binding metadata to Workspace Manager V2 repo references and hydrated tool `workspace` sections: `hasLiveRepoHandle`, `sourceBindingState`, `boundManifestPath`, and `bindingSource`.
+- Kept live FileSystem handles out of sessionStorage, persisted toolState context, and Session Inspector JSON; stored metadata only.
+- Session Inspector V2 now logs runtime binding status for selected repo/tool entries without rendering a handle object.
+- Workspace Manager V2 now logs runtime handle acquired, rebound, lost, and invalidated states.
+
+## Scope
+
+Changed only Workspace Manager V2 runtime binding visibility/status, Session Inspector V2 visibility, and the Workspace Manager V2 Playwright coverage.
+
+No `start_of_day` files were modified.
+
+## Validation
+
+- `node --check tools/workspace-manager-v2/js/WorkspaceManagerV2App.js`
+- `node --check tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js`
+- `node --check tools/session-inspector-v2/js/SessionInspectorV2App.js`
+- `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list -g "loads Gravity Well|restores sessionStorage toolState read-only|rebinds restored session Save"`: 3 passed
+- `npm run test:workspace-v2`: 22 passed
+- `git diff --check`: passed
+
+Full samples smoke test was skipped because this PR is limited to Workspace Manager V2 runtime handle visibility/status and does not modify shared sample loading, sample manifests, or broad sample runtime behavior.
+
+## Playwright Coverage
+
+Playwright impacted: Yes.
+
+Validated behavior:
+
+- Repo selection stores runtime binding visibility metadata in `workspace.repo.reference`.
+- Hydrated tool workspace sessions include save-capable binding metadata while the active workspace manifest remains free of runtime-only fields.
+- Session Inspector V2 shows runtime binding status metadata for repo/tool entries and does not render `handle`, `repoHandle`, or `fileSystemHandle` objects.
+- Restored sessionStorage toolState without a live repo folder handle reports `hasLiveRepoHandle=false`, keeps Save disabled, and logs the required rebind action.
+- Repo folder selection rebinds the restored toolState to the real `game.manifest.json` source and restores save-capable metadata.
+
+Expected pass behavior: runtime metadata is visible, serializable, and accurate; Save remains disabled without a live handle and enabled only for dirty toolState with a live binding.
+
+Expected fail behavior: tests fail if runtime metadata is missing, a live handle object appears in session/tool JSON, Session Inspector omits binding status, or Save becomes available without a live writable binding.
+
+## V8 Coverage
+
+Runtime JavaScript coverage from `npm run test:workspace-v2`:
+
+- `(88%) tools/workspace-manager-v2/js/WorkspaceManagerV2App.js - executed lines 913/913; executed functions 42/48`
+- `(90%) tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js - executed lines 1502/1502; executed functions 140/155`
+- `(93%) tools/session-inspector-v2/js/SessionInspectorV2App.js - executed lines 337/337; executed functions 42/45`
+
+Guardrail warnings: none.
+
+## Manual Test
+
+1. Open `tools/workspace-manager-v2/index.html`.
+2. Pick the repo folder and open Asteroids.
+3. Launch Session Inspector V2 from the Workspace Manager V2 tool tiles.
+4. Select `workspace.repo.reference` and `workspace.tools.asset-manager-v2`.
+5. Expected: JSON/status show `hasLiveRepoHandle`, `sourceBindingState`, `boundManifestPath`, and `bindingSource`; no live handle object is rendered.
+6. Return to Workspace Manager V2.
+7. Expected: repo/game/tool enablement and Save/Close dirty-state behavior remain intact.
+
+Out of scope: full sample launch validation. Sample smoke remains skipped until a dedicated sample alignment phase.
+
+## Changed Files
+
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`
+- `docs/dev/reports/PR_26130_005-runtime-handle-state-visibility.md`
+- `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `tools/session-inspector-v2/js/SessionInspectorV2App.js`
+- `tools/workspace-manager-v2/js/WorkspaceManagerV2App.js`
+- `tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js`

playwright.config.cjs

@@ -21,7 +21,7 @@ module.exports = {
   use: {
     headless: false,
     launchOptions: {
-      slowMo: 100
+      slowMo: 50
     },
     trace: "on"
   }

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -288,6 +288,23 @@ async function readWorkspaceSessionHydration(page) {
   });
 }
 
+function expectRuntimeBindingMetadata(metadata, {
+  bindingSource = "game.manifest.json",
+  boundManifestPath = "/games/Asteroids/game.manifest.json",
+  hasLiveRepoHandle = true,
+  sourceBindingState = "bound"
+} = {}) {
+  expect(metadata).toMatchObject({
+    bindingSource,
+    boundManifestPath,
+    hasLiveRepoHandle,
+    sourceBindingState
+  });
+  expect(metadata.handle).toBeUndefined();
+  expect(metadata.repoHandle).toBeUndefined();
+  expect(metadata.fileSystemHandle).toBeUndefined();
+}
+
 async function dirtyPaletteToolState(page, swatch) {
   await page.evaluate((nextSwatch) => {
     const app = window.__workspaceManagerV2App;
@@ -1491,14 +1508,21 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         tiles.every((tile) => Array.from(tile.querySelectorAll(".workspace-manager-v2__tool-tile-action"), (action) => action.textContent.trim()).join("|") === "How To Use|Read Me")
       ))).toBe(true);
       await selectMockRepo(page);
-      expect(await readWorkspaceSessionHydration(page)).toMatchObject({
+      const selectedRepoHydration = await readWorkspaceSessionHydration(page);
+      expect(selectedRepoHydration).toMatchObject({
         repoReference: {
           displayName: "HTML-JavaScript-Gaming",
           handleName: "HTML-JavaScript-Gaming",
           kind: "file-system-directory-handle-reference"
         },
         toolKeys: []
       });
+      expectRuntimeBindingMetadata(selectedRepoHydration.repoReference, {
+        bindingSource: "showDirectoryPicker",
+        boundManifestPath: "",
+        hasLiveRepoHandle: true,
+        sourceBindingState: "repo-handle-acquired"
+      });
       const compactCenterLayout = await page.evaluate(() => {
         const getRect = (selector) => {
           const element = document.querySelector(selector);
@@ -1542,6 +1566,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"toolId"/);
       await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"workspaceManifest"/);
       await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"workspaceMetadata"/);
+      await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"hasLiveRepoHandle"/);
+      await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"sourceBindingState"/);
       await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/samples\//);
       await expect(page.locator("#pickRepoBtn")).toBeDisabled();
       await expect(page.locator("#activeGameSelect")).toBeDisabled();
@@ -1550,6 +1576,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#cancelWorkspaceButton")).toBeEnabled();
       await expect(page.locator("#activeGameContent button")).toHaveCount(0);
       const selectedGameHydration = await readWorkspaceSessionHydration(page);
+      expectRuntimeBindingMetadata(selectedGameHydration.repoReference);
       expect(selectedGameHydration.toolKeys).toEqual([
         "workspace.tools.asset-manager-v2",
         "workspace.tools.palette-manager-v2",
@@ -1603,7 +1630,12 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         assetsPath: "games/Asteroids/assets",
         repoReferenceKey: "workspace.repo.reference"
       });
+      expectRuntimeBindingMetadata(selectedGameHydration.workspaceByTool["asset-manager-v2"]);
+      expectRuntimeBindingMetadata(selectedGameHydration.workspaceByTool["palette-manager-v2"]);
+      expectRuntimeBindingMetadata(selectedGameHydration.workspaceByTool["preview-generator-v2"]);
+      expectRuntimeBindingMetadata(selectedGameHydration.workspaceByTool["session-inspector-v2"]);
       expect(selectedGameHydration.toolSessions["asset-manager-v2"].state).toBeUndefined();
+      expect(JSON.stringify(selectedGameHydration.toolSessions)).not.toMatch(/getDirectoryHandle|createWritable|FileSystemDirectoryHandle/);
       expect(Object.keys(selectedGameHydration.dataByTool["asset-manager-v2"].assets)).toHaveLength(14);
       expect(selectedGameHydration.toolSessions["templates-v2"]).toBeUndefined();
       expect(Object.values(selectedGameHydration.dirtyByTool)).toEqual([
@@ -1677,6 +1709,21 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#sessionInspectorV2EntryList [data-session-inspector-v2-entry-id='sessionStorage:workspace.tools.preview-generator-v2']")).toHaveCount(1);
       await expect(page.locator("#sessionInspectorV2EntryList [data-session-inspector-v2-entry-id='sessionStorage:workspace.tools.session-inspector-v2']")).toHaveCount(1);
       await expect(page.locator("#sessionInspectorV2EntryList [data-session-inspector-v2-entry-id='sessionStorage:workspace.tools.templates-v2']")).toHaveCount(0);
+      await page.locator('[data-session-inspector-v2-entry-id="sessionStorage:workspace.tools.asset-manager-v2"]').click();
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).toContainText('"hasLiveRepoHandle": true');
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).toContainText('"sourceBindingState": "bound"');
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).toContainText('"boundManifestPath": "/games/Asteroids/game.manifest.json"');
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).toContainText('"bindingSource": "game.manifest.json"');
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).not.toContainText('"handle":');
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).not.toContainText('"repoHandle":');
+      await expect(page.locator("#statusLog")).toHaveValue(/INFO Runtime binding status for sessionStorage:workspace\.tools\.asset-manager-v2: hasLiveRepoHandle=true; sourceBindingState=bound; boundManifestPath=\/games\/Asteroids\/game\.manifest\.json; bindingSource=game\.manifest\.json\./);
+      await page.locator('[data-session-inspector-v2-entry-id="sessionStorage:workspace.repo.reference"]').click();
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).toContainText('"hasLiveRepoHandle": true');
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).toContainText('"sourceBindingState": "bound"');
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).toContainText('"boundManifestPath": "/games/Asteroids/game.manifest.json"');
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).toContainText('"bindingSource": "game.manifest.json"');
+      await expect(page.locator("#sessionInspectorV2JsonOutput")).not.toContainText('"handle":');
+      await expect(page.locator("#statusLog")).toHaveValue(/INFO Runtime binding status for sessionStorage:workspace\.repo\.reference: hasLiveRepoHandle=true; sourceBindingState=bound; boundManifestPath=\/games\/Asteroids\/game\.manifest\.json; bindingSource=game\.manifest\.json\./);
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
       await expectWorkspaceReturnedFromTool(page);
@@ -1760,6 +1807,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       expect(storedContext.toolId).toBeUndefined();
       expect(storedContext.activePalette).toBeUndefined();
       expect(storedContext.workspaceManifest).toBeUndefined();
+      expect(storedContext.hasLiveRepoHandle).toBeUndefined();
+      expect(storedContext.sourceBindingState).toBeUndefined();
       expect(storedContext.gameId).toBe("Asteroids");
       expect(storedContext.gameRoot).toBe("games/Asteroids/");
       expect(storedContext.assetsPath).toBe("games/Asteroids/assets");
@@ -2291,6 +2340,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       const restoredState = await page.evaluate(() => ({
         activeGameManifestPath: window.__workspaceManagerV2App.activeGame.manifestPath,
         hasRepoHandle: Boolean(window.__workspaceManagerV2App.activeRepoHandle),
+        repoReference: JSON.parse(sessionStorage.getItem("workspace.repo.reference")),
         requiresRepoHandle: window.__workspaceManagerV2App.activeToolStateRequiresRepoHandle,
         writes: JSON.parse(sessionStorage.getItem("workspace.repo.manifestWrites") || "[]")
       }));
@@ -2300,6 +2350,13 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         writes: []
       });
       expect(restoredState.activeGameManifestPath).toBe(`sessionStorage:${hostContextId}`);
+      expectRuntimeBindingMetadata(restoredState.repoReference, {
+        bindingSource: "sessionStorage restore",
+        boundManifestPath: `sessionStorage:${hostContextId}`,
+        hasLiveRepoHandle: false,
+        sourceBindingState: "missing-live-repo-handle"
+      });
+      await expect(page.locator("#statusLog")).toHaveValue(new RegExp(`WARN Runtime handle lost: hasLiveRepoHandle=false; sourceBindingState=missing-live-repo-handle; boundManifestPath=sessionStorage:${hostContextId}; bindingSource=sessionStorage restore\\. Required action: Pick Repo Folder to rebind game\\.manifest\\.json before Save or tool launch\\.`));
 
       await page.evaluate(() => window.__workspaceManagerV2App.saveWorkspaceSession());
       await expect(page.locator("#statusLog")).toHaveValue(new RegExp(`FAIL Save blocked: missing live repo folder handle for active toolState; active game source=sessionStorage:${hostContextId}; context\\.gameId=Asteroids; context\\.gameRoot=games/Asteroids/\\. Required action: Pick Repo Folder to rebind game\\.manifest\\.json before Save\\.`));
@@ -2310,14 +2367,17 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         activeGameManifestKind: window.__workspaceManagerV2App.activeGame.manifestKind,
         activeGameManifestPath: window.__workspaceManagerV2App.activeGame.manifestPath,
         hasRepoHandle: Boolean(window.__workspaceManagerV2App.activeRepoHandle),
+        repoReference: JSON.parse(sessionStorage.getItem("workspace.repo.reference")),
         requiresRepoHandle: window.__workspaceManagerV2App.activeToolStateRequiresRepoHandle
       }));
-      expect(reboundState).toEqual({
+      expect(reboundState).toMatchObject({
         activeGameManifestKind: "game-manifest",
         activeGameManifestPath: "/games/Asteroids/game.manifest.json",
         hasRepoHandle: true,
         requiresRepoHandle: false
       });
+      expectRuntimeBindingMetadata(reboundState.repoReference);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Runtime handle rebound: hasLiveRepoHandle=true; sourceBindingState=bound; boundManifestPath=\/games\/Asteroids\/game\.manifest\.json; bindingSource=repo-folder-rebind\./);
 
       await page.locator("#saveWorkspaceButton").click();
       await expect(page.locator("#statusLog")).toHaveValue(/OK Save source binding: \/games\/Asteroids\/game\.manifest\.json\./);
@@ -2327,9 +2387,12 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#statusLog")).toHaveValue(/OK Save dirty\/clean validation: 1 dirty toolState payload persisted; 1 toolState key marked clean\./);
       const saveState = await page.evaluate((contextId) => ({
         paletteSession: JSON.parse(sessionStorage.getItem("workspace.tools.palette-manager-v2")),
+        repoReference: JSON.parse(sessionStorage.getItem("workspace.repo.reference")),
         savedContext: JSON.parse(sessionStorage.getItem(contextId)),
         writes: JSON.parse(sessionStorage.getItem("workspace.repo.manifestWrites") || "[]")
       }), hostContextId);
+      expectRuntimeBindingMetadata(saveState.repoReference);
+      expectRuntimeBindingMetadata(saveState.paletteSession.workspace);
       expect(saveState.paletteSession.dirty).toEqual({
         isDirty: false,
         reason: null,

tools/session-inspector-v2/js/SessionInspectorV2App.js

@@ -94,7 +94,36 @@ export class SessionInspectorV2App {
     this.dirty.render(entry);
     if (entry) {
       this.statusLog.info(`Selected ${entry.storageType}:${entry.key}.`);
+      const runtimeBinding = this.runtimeBindingForEntry(entry);
+      if (runtimeBinding) {
+        this.statusLog.info(`Runtime binding status for ${entry.storageType}:${entry.key}: hasLiveRepoHandle=${runtimeBinding.hasLiveRepoHandle}; sourceBindingState=${runtimeBinding.sourceBindingState}; boundManifestPath=${runtimeBinding.boundManifestPath || "(none)"}; bindingSource=${runtimeBinding.bindingSource || "(none)"}.`);
+      }
+    }
+  }
+
+  runtimeBindingForEntry(entry) {
+    const value = entry?.parseOk ? entry.parsedValue : null;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return null;
+    }
+    const candidate = Object.prototype.hasOwnProperty.call(value, "hasLiveRepoHandle")
+      ? value
+      : value.workspace;
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+      return null;
+    }
+    if (!Object.prototype.hasOwnProperty.call(candidate, "hasLiveRepoHandle")
+      || !Object.prototype.hasOwnProperty.call(candidate, "sourceBindingState")
+      || !Object.prototype.hasOwnProperty.call(candidate, "boundManifestPath")
+      || !Object.prototype.hasOwnProperty.call(candidate, "bindingSource")) {
+      return null;
     }
+    return {
+      hasLiveRepoHandle: candidate.hasLiveRepoHandle === true,
+      sourceBindingState: String(candidate.sourceBindingState || "unknown"),
+      boundManifestPath: String(candidate.boundManifestPath || ""),
+      bindingSource: String(candidate.bindingSource || "")
+    };
   }
 
   deleteEntry(entryId) {