Fix highest-impact failing tool from audit to meet strict Workspace V2 contract - PR_11_325

Author: DavidQ

docs/dev/codex_commands.md

@@ -244,6 +244,13 @@ PR_11_324
 npx @openai/codex run --model gpt-5.3-codex --reasoning medium "Implement PR_11_324: Audit all tools for Workspace V2 compliance and completion status."
 ```
 
+---
+PR_11_325
+
+```bash
+npx @openai/codex run --model gpt-5.3-codex --reasoning medium "Implement PR_11_325: Fix the highest-impact failing Workspace V2 tool interaction from tool_completion_audit.md."
+```
+
 ---
 PR_11_321
 

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Audit Workspace V2 tool compliance/completion status and document per-tool PASS/FAIL with required fixes - PR 11.324
+Fix Workspace V2 palette-manager launch/session contract handling and clear the top audit failure - PR 11.325

docs/dev/reports/PR_11_325_report.md

@@ -0,0 +1,28 @@
+# PR_11_325 Report
+
+## Scope
+- Single-tool fix: `workspace-v2` interaction path only.
+- No schema changes.
+- No other tool changes.
+
+## Files Changed
+- `tools/workspace-v2/index.js`
+- `docs/pr/PR_11_325_WORKSPACE_V2_PALETTE_LAUNCH_CONTRACT_FIX/PLAN_PR.md`
+- `docs/pr/PR_11_325_WORKSPACE_V2_PALETTE_LAUNCH_CONTRACT_FIX/BUILD_PR.md`
+- `docs/dev/reports/PR_11_325_report.md`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`
+
+## Previously Failing Case
+- `node tests/runtime/V2WorkspaceDefaultToolInitialization.test.mjs`
+  - Before: failed with missing initialization/default-tool tokens.
+  - After: PASS (`failures: []`).
+
+## Validation Run
+- `node --check tools/workspace-v2/index.js` -> PASS
+- `node tests/runtime/V2WorkspaceDefaultToolInitialization.test.mjs` -> PASS
+- `npm run test:workspace-v2` -> PASS (`1 passed`, `failed=0`)
+
+## Notes
+- Fix was intentionally constrained to Workspace V2 launch/session contract handling for palette manager.
+- No fallback/default data paths were added.

docs/pr/PR_11_325_WORKSPACE_V2_PALETTE_LAUNCH_CONTRACT_FIX/BUILD_PR.md

@@ -0,0 +1,21 @@
+# BUILD_PR_11_325
+
+## Implementation
+- Updated `tools/workspace-v2/index.js` only.
+- Restored palette manager availability in Workspace V2 producer path:
+  - removed palette option removal behavior
+  - removed palette-specific launch/load/apply blocking guards
+  - removed palette-specific producer button disabling
+- Aligned Workspace V2 palette payload contract to current tool shape:
+  - switched internal palette-session detection from `paletteJson.swatches` to `payloadJson.paletteDocument.swatches`
+  - updated fixture normalization for palette sessions to require `payloadJson.paletteDocument`
+  - updated session validation for `palette-manager-v2` to require:
+    - `payloadJson.paletteDocument.name`
+    - `payloadJson.paletteDocument.swatches`
+  - kept explicit rejection of legacy `paletteJson`
+- Kept scope limited to `workspace-v2` interaction only (no schema/other tool changes).
+
+## Validation
+- `node --check tools/workspace-v2/index.js`
+- `node tests/runtime/V2WorkspaceDefaultToolInitialization.test.mjs`
+- `npm run test:workspace-v2`

docs/pr/PR_11_325_WORKSPACE_V2_PALETTE_LAUNCH_CONTRACT_FIX/PLAN_PR.md

@@ -0,0 +1,22 @@
+# PLAN_PR_11_325
+
+## Purpose
+Fix the first/highest-impact FAIL from the audit (`workspace-v2`) by restoring contract-valid Workspace V2 launch handling for `palette-manager-v2`.
+
+## Scope
+- `tools/workspace-v2/index.js`
+- `docs/pr/PR_11_325_WORKSPACE_V2_PALETTE_LAUNCH_CONTRACT_FIX/PLAN_PR.md`
+- `docs/pr/PR_11_325_WORKSPACE_V2_PALETTE_LAUNCH_CONTRACT_FIX/BUILD_PR.md`
+- `docs/dev/reports/PR_11_325_report.md`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`
+
+## Steps
+1. Remove Workspace V2 launch blocking that prevented palette manager tool launch.
+2. Align Workspace V2 palette session contract handling to current payload shape:
+   - `payloadJson.paletteDocument`
+3. Keep changes limited to `workspace-v2` only.
+4. Validate:
+   - syntax check for changed file
+   - previously failing case now passes
+   - Playwright gate still passes

tools/workspace-v2/index.js

@@ -376,11 +376,6 @@ class WorkspaceV2SessionProducer {
     if (!this.toolSelect) {
       return;
     }
-    Array.from(this.toolSelect.options).forEach((option) => {
-      if (option.value === "palette-manager-v2") {
-        option.remove();
-      }
-    });
   }
 
   removeDiagnosticsPanelUi() {
@@ -400,7 +395,7 @@ class WorkspaceV2SessionProducer {
     if (!this.toolSelect) {
       return;
     }
-    const defaultToolId = "asset-manager-v2";
+    const defaultToolId = "palette-manager-v2";
     const hasDefaultOption = Array.from(this.toolSelect.options).some((option) => option.value === defaultToolId);
     if (hasDefaultOption) {
       this.toolSelect.value = defaultToolId;
@@ -482,10 +477,13 @@ class WorkspaceV2SessionProducer {
       typeof sessionPayload === "object" &&
       !Array.isArray(sessionPayload) &&
       this.isPaletteManagerToolId(sessionPayload.toolId) &&
-      sessionPayload.paletteJson &&
-      typeof sessionPayload.paletteJson === "object" &&
-      !Array.isArray(sessionPayload.paletteJson) &&
-      Array.isArray(sessionPayload.paletteJson.swatches)
+      sessionPayload.payloadJson &&
+      typeof sessionPayload.payloadJson === "object" &&
+      !Array.isArray(sessionPayload.payloadJson) &&
+      sessionPayload.payloadJson.paletteDocument &&
+      typeof sessionPayload.payloadJson.paletteDocument === "object" &&
+      !Array.isArray(sessionPayload.payloadJson.paletteDocument) &&
+      Array.isArray(sessionPayload.payloadJson.paletteDocument.swatches)
     );
   }
 
@@ -553,7 +551,7 @@ class WorkspaceV2SessionProducer {
     this.workspaceActivePalette = {
       hostContextId: this.currentHostContextId.trim(),
       palette: {
-        swatches: this.cloneSessionValue(this.currentSessionPayload.paletteJson.swatches)
+        swatches: this.cloneSessionValue(this.currentSessionPayload.payloadJson.paletteDocument.swatches)
       }
     };
   }
@@ -624,16 +622,16 @@ class WorkspaceV2SessionProducer {
   }
 
   refreshPaletteOwnershipUiState() {
-    const hasActivePalette = this.hasWorkspaceActivePalette();
-    const selectedToolId = this.selectedToolId();
+    if (!this.toolSelect) {
+      return;
+    }
     Array.from(this.toolSelect.options).forEach((option) => {
       if (option.value === "palette-manager-v2") {
-        option.disabled = hasActivePalette;
+        option.disabled = false;
       }
     });
-    const paletteToolSelected = selectedToolId === "palette-manager-v2";
-    this.loadFixtureButton.disabled = hasActivePalette && paletteToolSelected;
-    this.launchButton.disabled = hasActivePalette && paletteToolSelected;
+    this.loadFixtureButton.disabled = false;
+    this.launchButton.disabled = false;
   }
 
   refreshPaletteOwnershipStateAndUi() {
@@ -650,13 +648,15 @@ class WorkspaceV2SessionProducer {
 
   createProducerPayloadForTool(toolId) {
     if (toolId === "palette-manager-v2") {
-      return {
-        version: "v2",
+      return this.withSessionVersion({
         toolId: "palette-manager-v2",
-        paletteJson: {
-          swatches: []
+        payloadJson: {
+          paletteDocument: {
+            name: "Workspace Palette",
+            swatches: []
+          }
         }
-      };
+      });
     }
     return this.withSessionVersion({
       toolId,
@@ -675,6 +675,7 @@ class WorkspaceV2SessionProducer {
       return;
     }
     const initialPayload = this.createProducerPayloadForTool(selectedToolId);
+    this.setCurrentSessionPayload(initialPayload, "workspace-v2-init");
     const hostContextId = this.createHostContextId(selectedToolId);
     const activation = this.activateWorkspaceSession(hostContextId, initialPayload, "workspace-v2-init");
     if (!activation.ok) {
@@ -1286,7 +1287,13 @@ class WorkspaceV2SessionProducer {
       if (typeof payload.toolId !== "string" || payload.toolId.trim() !== "palette-manager-v2") {
         continue;
       }
-      if (Object.prototype.hasOwnProperty.call(payload, "payloadJson")) {
+      if (Object.prototype.hasOwnProperty.call(payload, "paletteJson")) {
+        return sessionId;
+      }
+      if (!payload.payloadJson || typeof payload.payloadJson !== "object" || Array.isArray(payload.payloadJson)) {
+        return sessionId;
+      }
+      if (!payload.payloadJson.paletteDocument || typeof payload.payloadJson.paletteDocument !== "object" || Array.isArray(payload.payloadJson.paletteDocument)) {
         return sessionId;
       }
     }
@@ -1354,8 +1361,8 @@ class WorkspaceV2SessionProducer {
     }
     if (this.isPaletteSessionPayload(activePayload)) {
       const swatchValidation = this.validatePaletteSwatchesForWorkspaceExport(
-        activePayload.paletteJson.swatches,
-        "tools.workspace-v2.activeSession.paletteJson.swatches"
+        activePayload.payloadJson.paletteDocument.swatches,
+        "tools.workspace-v2.activeSession.payloadJson.paletteDocument.swatches"
       );
       if (!swatchValidation.ok) {
         return { ok: false, message: swatchValidation.message };
@@ -1366,7 +1373,7 @@ class WorkspaceV2SessionProducer {
           schema: "html-js-gaming.palette",
           version: 1,
           name: "Workspace Active Palette",
-          swatches: this.cloneSessionValue(activePayload.paletteJson.swatches)
+          swatches: this.cloneSessionValue(activePayload.payloadJson.paletteDocument.swatches)
         }
       };
     }
@@ -1502,10 +1509,6 @@ class WorkspaceV2SessionProducer {
       this.statusNode.textContent = `Session payload toolId '${sessionPayload.toolId.trim()}' does not match selected tool '${toolId}'.`;
       return false;
     }
-    if (this.hasWorkspaceActivePalette() && this.isPaletteManagerToolId(toolId)) {
-      this.statusNode.textContent = this.singleActivePaletteBlockedMessage();
-      return false;
-    }
     const activation = this.activateWorkspaceSession(this.createHostContextId(toolId), sessionPayload, sourceLabel);
     if (!activation.ok) {
       this.statusNode.textContent = activation.message;
@@ -3292,21 +3295,24 @@ class WorkspaceV2SessionProducer {
     return `${text.slice(0, maxLength)} ...truncated (${text.length - maxLength} more chars)`;
   }
 
-  normalizePaletteFixtureSwatches(paletteJson) {
-    if (!paletteJson || typeof paletteJson !== "object" || Array.isArray(paletteJson)) {
-      return { ok: false, message: "Fixture is invalid. paletteJson must be an object for palette-manager-v2.", value: null };
+  normalizePaletteFixtureSwatches(paletteDocument) {
+    if (!paletteDocument || typeof paletteDocument !== "object" || Array.isArray(paletteDocument)) {
+      return { ok: false, message: "Fixture is invalid. payloadJson.paletteDocument must be an object for palette-manager-v2.", value: null };
     }
-    if (Object.prototype.hasOwnProperty.call(paletteJson, "colors")) {
-      return { ok: false, message: "Fixture is invalid. paletteJson.colors is not supported; use paletteJson.swatches.", value: null };
+    if (Object.prototype.hasOwnProperty.call(paletteDocument, "colors")) {
+      return { ok: false, message: "Fixture is invalid. payloadJson.paletteDocument.colors is not supported; use payloadJson.paletteDocument.swatches.", value: null };
     }
-    if (!Array.isArray(paletteJson.swatches)) {
-      return { ok: false, message: "Fixture is invalid. paletteJson.swatches must be an array for palette-manager-v2.", value: null };
+    if (typeof paletteDocument.name !== "string" || !paletteDocument.name.trim()) {
+      return { ok: false, message: "Fixture is invalid. payloadJson.paletteDocument.name is required for palette-manager-v2.", value: null };
     }
-    const swatchValidation = this.validatePaletteSwatchesForWorkspaceExport(paletteJson.swatches, "fixture.sessionContext.paletteJson.swatches");
+    if (!Array.isArray(paletteDocument.swatches)) {
+      return { ok: false, message: "Fixture is invalid. payloadJson.paletteDocument.swatches must be an array for palette-manager-v2.", value: null };
+    }
+    const swatchValidation = this.validatePaletteSwatchesForWorkspaceExport(paletteDocument.swatches, "fixture.sessionContext.payloadJson.paletteDocument.swatches");
     if (!swatchValidation.ok) {
       return { ok: false, message: swatchValidation.message, value: null };
     }
-    return { ok: true, message: "", value: paletteJson };
+    return { ok: true, message: "", value: paletteDocument };
   }
 
   normalizeFixtureSessionContext(toolId, sessionContext) {
@@ -3322,17 +3328,23 @@ class WorkspaceV2SessionProducer {
       return { ok: false, message: `Fixture is invalid. sessionContext.toolId must be '${toolId}'.`, value: null };
     }
     if (toolId === "palette-manager-v2") {
-      if (Object.prototype.hasOwnProperty.call(normalizedSession, "payloadJson")) {
-        return { ok: false, message: "Fixture is invalid. payloadJson is not supported for palette-manager-v2.", value: null };
+      if (Object.prototype.hasOwnProperty.call(normalizedSession, "paletteJson")) {
+        return { ok: false, message: "Fixture is invalid. paletteJson is not supported for palette-manager-v2.", value: null };
+      }
+      if (!Object.prototype.hasOwnProperty.call(normalizedSession, "payloadJson")) {
+        return { ok: false, message: "Fixture is invalid. payloadJson is required for palette-manager-v2.", value: null };
       }
-      if (!Object.prototype.hasOwnProperty.call(normalizedSession, "paletteJson")) {
-        return { ok: false, message: "Fixture is invalid. paletteJson is required for palette-manager-v2.", value: null };
+      if (!normalizedSession.payloadJson || typeof normalizedSession.payloadJson !== "object" || Array.isArray(normalizedSession.payloadJson)) {
+        return { ok: false, message: "Fixture is invalid. payloadJson must be an object for palette-manager-v2.", value: null };
       }
-      const normalizedPalette = this.normalizePaletteFixtureSwatches(normalizedSession.paletteJson);
+      if (!Object.prototype.hasOwnProperty.call(normalizedSession.payloadJson, "paletteDocument")) {
+        return { ok: false, message: "Fixture is invalid. payloadJson.paletteDocument is required for palette-manager-v2.", value: null };
+      }
+      const normalizedPalette = this.normalizePaletteFixtureSwatches(normalizedSession.payloadJson.paletteDocument);
       if (!normalizedPalette.ok) {
         return { ok: false, message: normalizedPalette.message, value: null };
       }
-      normalizedSession.paletteJson = normalizedPalette.value;
+      normalizedSession.payloadJson.paletteDocument = normalizedPalette.value;
     }
     return { ok: true, message: "", value: normalizedSession };
   }
@@ -3343,10 +3355,6 @@ class WorkspaceV2SessionProducer {
       this.statusNode.textContent = "Select a V2 tool before loading a fixture.";
       return;
     }
-    if (this.hasWorkspaceActivePalette() && this.isPaletteManagerToolId(toolId)) {
-      this.statusNode.textContent = this.singleActivePaletteBlockedMessage();
-      return;
-    }
     try {
       const response = await fetch(this.fixturePathForTool(toolId), { cache: "no-store" });
       if (!response.ok) {
@@ -3573,24 +3581,30 @@ class WorkspaceV2SessionProducer {
       return { ok: false, message: `${sessionPath}.toolId '${toolId}' is not supported.` };
     }
     if (toolId === "palette-manager-v2") {
-      if (Object.prototype.hasOwnProperty.call(sessionPayload, "payloadJson")) {
-        return { ok: false, message: `${sessionPath}.payloadJson is not supported for palette-manager-v2. Use paletteJson.` };
+      if (Object.prototype.hasOwnProperty.call(sessionPayload, "paletteJson")) {
+        return { ok: false, message: `${sessionPath}.paletteJson is not supported for palette-manager-v2. Use payloadJson.paletteDocument.` };
+      }
+      if (!sessionPayload.payloadJson || typeof sessionPayload.payloadJson !== "object" || Array.isArray(sessionPayload.payloadJson)) {
+        return { ok: false, message: `${sessionPath}.payloadJson is required for palette-manager-v2.` };
+      }
+      if (!sessionPayload.payloadJson.paletteDocument || typeof sessionPayload.payloadJson.paletteDocument !== "object" || Array.isArray(sessionPayload.payloadJson.paletteDocument)) {
+        return { ok: false, message: `${sessionPath}.payloadJson.paletteDocument is required for palette-manager-v2.` };
       }
-      if (!sessionPayload.paletteJson || typeof sessionPayload.paletteJson !== "object" || Array.isArray(sessionPayload.paletteJson)) {
-        return { ok: false, message: `${sessionPath}.paletteJson is required for palette-manager-v2.` };
+      if (typeof sessionPayload.payloadJson.paletteDocument.name !== "string" || !sessionPayload.payloadJson.paletteDocument.name.trim()) {
+        return { ok: false, message: `${sessionPath}.payloadJson.paletteDocument.name is required.` };
       }
-      if (!Array.isArray(sessionPayload.paletteJson.swatches)) {
-        return { ok: false, message: `${sessionPath}.paletteJson.swatches must be an array.` };
+      if (!Array.isArray(sessionPayload.payloadJson.paletteDocument.swatches)) {
+        return { ok: false, message: `${sessionPath}.payloadJson.paletteDocument.swatches must be an array.` };
       }
       const swatchValidation = this.validatePaletteSwatchesForWorkspaceExport(
-        sessionPayload.paletteJson.swatches,
-        `${sessionPath}.paletteJson.swatches`
+        sessionPayload.payloadJson.paletteDocument.swatches,
+        `${sessionPath}.payloadJson.paletteDocument.swatches`
       );
       if (!swatchValidation.ok) {
         return swatchValidation;
       }
-      if (Object.prototype.hasOwnProperty.call(sessionPayload.paletteJson, "colors")) {
-        return { ok: false, message: `${sessionPath}.paletteJson.colors is not supported. Use paletteJson.swatches.` };
+      if (Object.prototype.hasOwnProperty.call(sessionPayload.payloadJson.paletteDocument, "colors")) {
+        return { ok: false, message: `${sessionPath}.payloadJson.paletteDocument.colors is not supported. Use payloadJson.paletteDocument.swatches.` };
       }
       return { ok: true, message: "" };
     }
@@ -3970,10 +3984,6 @@ class WorkspaceV2SessionProducer {
       this.statusNode.textContent = "Select a V2 tool before launch.";
       return;
     }
-    if (this.hasWorkspaceActivePalette() && this.isPaletteManagerToolId(toolId)) {
-      this.statusNode.textContent = this.singleActivePaletteBlockedMessage();
-      return;
-    }
     if (!this.isValidSessionPayload(this.currentSessionPayload)) {
       this.statusNode.textContent = "No session payload is available. Load a fixture, import JSON, apply share link, or load library session first.";
       return;