[codex] Normalize persisted session JSON strings (#51)

Author: nedtwigg

docs/specs/layout.md

@@ -271,6 +271,8 @@ Pane IDs are session IDs. `TerminalPane` calls `getOrCreateTerminal(id)` on Reac
 
 Layout, scrollback, cwd, minimized items, and alert state are saved to persistent storage via a debounced save (500ms). Saves are triggered by layout changes, panel add/remove, and a 30s periodic interval. Saves are flushed immediately on PTY exit, `pagehide`, and extension shutdown requests.
 
+Saved snapshots are read through `readPersistedSession()`, which accepts the canonical object shape and defensively parses a JSON-stringified blob before validation and migration. This keeps malformed storage inert while covering hosts that hand back serialized JSON instead of the parsed object.
+
 On startup, recovery is priority-based:
 1. **Resume** (webview hidden/shown, live PTYs): request PTY list + replay data from platform, `resumeTerminal()` for each (500ms timeout). If the saved session covers every live PTY, restore the saved dockview layout when its visible panel set matches and reattach saved minimized items as doors. This still counts as a live resume when every live session is minimized, so recovery must not fall through to cold restore just because the visible `paneIds` list is empty.
 2. **Restore** (app restart, cold start): restore layout from serialized dockview state, `restoreTerminal()` for each pane with saved cwd + scrollback, and spawn each PTY with the current default shell selection

docs/specs/vscode.md

@@ -244,6 +244,8 @@ interface PersistedDoor {
 5. Graceful shutdown: save state -> SIGTERM -> 2s wait -> force kill
 6. On activate: saved state loaded and passed to routers for cold-start restore
 
+Every saved-session entry point must pass through `readPersistedSession()`. That reader accepts both the canonical parsed object and a JSON-stringified session blob before validating/migrating, which covers VS Code state APIs that may hand back the inner serialized JSON string.
+
 ### Theme integration
 
 Two-layer CSS variable system: VS Code injects `--vscode-*` tokens; `lib/src/theme.css` maps them directly to semantic `--color-*` tokens for use in Tailwind utility classes. The webview entry point installs `installVscodeThemeVarResolver()` before React renders. That resolver reads VSCode-provided variables, materializes only missing MouseTerm-consumed variables on `body.style`, and watches `body`/`html` class and style mutations so theme changes recompute those materialized values.

lib/src/lib/session-migration.test.ts

@@ -201,6 +201,28 @@ describe('readPersistedSession', () => {
     expect(readPersistedSession(v3)).toBe(v3);
   });
 
+  it('reads a JSON-stringified v3 blob', () => {
+    const v3 = {
+      version: 3 as const,
+      layout: null,
+      panes: [{ id: 'pane-a', title: 'Pane A', cwd: null, scrollback: 'saved output', resumeCommand: null }],
+      doors: [],
+    };
+
+    expect(readPersistedSession(JSON.stringify(v3))).toEqual(v3);
+  });
+
+  it('decodes escaped control bytes in JSON-stringified scrollback', () => {
+    const v3 = {
+      version: 3 as const,
+      layout: null,
+      panes: [{ id: 'pane-a', title: 'Pane A', cwd: null, scrollback: '\u001b[31mred', resumeCommand: null }],
+      doors: [],
+    };
+
+    expect(readPersistedSession(JSON.stringify(v3))?.panes[0].scrollback).toBe('\x1b[31mred');
+  });
+
   it('migrates a v2 blob on read (numeric TODO → boolean)', () => {
     const v2 = {
       version: 2 as const,
@@ -254,6 +276,8 @@ describe('readPersistedSession', () => {
     expect(readPersistedSession(undefined)).toBeNull();
     expect(readPersistedSession({ version: 99 })).toBeNull();
     expect(readPersistedSession('not an object')).toBeNull();
+    expect(readPersistedSession('{')).toBeNull();
+    expect(readPersistedSession(JSON.stringify({ version: 99 }))).toBeNull();
     expect(readPersistedSession({ version: 2, layout: null, panes: 'nope' })).toBeNull();
     expect(readPersistedSession({ version: 2, layout: null, panes: [], doors: {} })).toBeNull();
     expect(readPersistedSession({ version: 1, layout: null, panes: [] as const, detached: {} })).toBeNull();

lib/src/lib/session-types.ts

@@ -191,9 +191,19 @@ export function migrateSessionV2toV3(v2: PersistedSessionV2): PersistedSession {
 }
 
 export function readPersistedSession(raw: unknown): PersistedSession | null {
-  if (!isRecord(raw)) return null;
-  if (isPersistedSessionV3(raw)) return raw;
-  if (isPersistedSessionV2(raw)) return migrateSessionV2toV3(raw);
-  if (isPersistedSessionV1(raw)) return migrateSessionV2toV3(migrateSessionV1toV2(raw));
+  const value = parseJsonString(raw);
+  if (!isRecord(value)) return null;
+  if (isPersistedSessionV3(value)) return value;
+  if (isPersistedSessionV2(value)) return migrateSessionV2toV3(value);
+  if (isPersistedSessionV1(value)) return migrateSessionV2toV3(migrateSessionV1toV2(value));
   return null;
 }
+
+function parseJsonString(raw: unknown): unknown {
+  if (typeof raw !== 'string') return raw;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}