feat(desktop): persist and restore UI state across restarts (NeuralNomadsAI#578)

## Summary

- Restore the primary desktop client's window bounds, zoom, workspace
tabs, active sessions, drafts, bounded attachments, scroll positions,
and panel layout across launches.
- Keep additional Electron and Tauri processes independent: they still
start normally but do not read or write the shared native snapshot.
- Add translated settings to disable startup restoration or clear the
saved state.

## Implementation

- Persist a versioned, bounded snapshot atomically in Electron and
Tauri, preserving unknown future envelopes until an explicit clear.
- Elect one primary process with stale-owner recovery and process
identity checks, then protect renderer access with per-document
capability tokens.
- Flush renderer state before close, quit, reload, and app-owned
navigation with bounded failure handling and fresh token rotation.
- Reconcile partial or timed-out workspace hydration without losing
unsent prompt state or resurrecting explicitly cleared drafts,
attachments, sessions, or tabs.
- Correlate restore-created workspaces so cancellation and delayed SSE
events cannot produce ghost tabs.
- Harden workspace launch cancellation and cross-platform process
cleanup so failed starts cannot orphan detached POSIX, WSL, or Windows
children; incomplete shutdown exits nonzero.

The restored shell state remains local to the desktop client. Durable
semantic session properties continue to use OpenCode session metadata
separately.

## Validation

pm run typecheck --workspace @neuralnomads/codenomad
- Electron native suite: 43 passed
- Tauri suite: 54 passed
- Focused UI restore, reconciliation, attachment, authority, and race
suites passed
- Focused server workspace runtime, manager, process identity, route,
and shutdown suites passed
- pm run build
- pm run build:tauri
- git diff --check
- 16-pass adversarial review loop completed with final No findings
- extensivly optimized, tested and used day by day

## Platform notes

- Native menu reloads and app-owned navigation have awaited durability
guarantees. Browser-engine crashes or forced process termination remain
inherently best effort.
- Process cleanup uses identity-guarded platform adapters and fails
conservatively when target ownership cannot be proven.

Author: pascalandr

package-lock.json

@@ -0,0 +1,62 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import {
+  electClientStateProcess,
+  isPidAlive,
+  REGISTRATION_LOCK_WAIT_MS,
+  removeProcessOwnerLockIfOwned,
+  removeRunningMarkerIfOwned,
+  type ProcessOwner,
+} from "./client-state-process"
+import { getProcessStartIdentity } from "./client-state-process-identity"
+
+const [directory, runToken, startPath, registrationWaitArgument, primaryPausedPath, primaryReleasePath] =
+  process.argv.slice(2)
+if (!directory || !runToken || !startPath) {
+  throw new Error("Expected election directory, run token, and start path")
+}
+
+while (!existsSync(startPath)) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5)
+}
+
+const owner: ProcessOwner = {
+  pid: process.pid,
+  runToken,
+  processStartIdentity: getProcessStartIdentity(process.pid),
+}
+const primaryLockPath = join(directory, "client-state.primary.lock")
+const registrationLockPath = join(directory, "client-state.registration.lock")
+const registrationLockWaitMs = registrationWaitArgument
+  ? Number(registrationWaitArgument)
+  : REGISTRATION_LOCK_WAIT_MS
+const warnings: string[] = []
+const election = electClientStateProcess(
+  directory,
+  owner,
+  { primaryLockPath, registrationLockPath },
+  (message, error) => warnings.push(`${message}: ${String(error)}`),
+  isPidAlive,
+  registrationLockWaitMs,
+  () => {
+    if (!primaryPausedPath || !primaryReleasePath) {
+      return
+    }
+    try {
+      writeFileSync(primaryPausedPath, JSON.stringify(owner), { encoding: "utf8", flag: "wx" })
+    } catch {
+      // Only the contender that published the synchronization point owns the pause gate.
+      return
+    }
+    while (!existsSync(primaryReleasePath)) {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5)
+    }
+  },
+)
+
+process.stdout.write(`${JSON.stringify({ isPrimary: election.isPrimary, owner, warnings })}\n`)
+process.stdin.resume()
+process.stdin.once("end", () => {
+  removeRunningMarkerIfOwned(election.runningMarkerPath, owner)
+  removeProcessOwnerLockIfOwned(primaryLockPath, owner)
+})

packages/electron-app/electron/main/client-state-election-child.ts

@@ -0,0 +1,76 @@
+import assert from "node:assert/strict"
+import { mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import test from "node:test"
+import { ClientStateManager } from "./client-state"
+import {
+  createClientStateIPCHandlers,
+  shouldResetRendererAccessTokenForNavigation,
+} from "./client-state-ipc-handlers"
+
+test("only trusted full main-frame navigation resets renderer access", () => {
+  const trusted = (url: string) => new URL(url).origin === "http://127.0.0.1:3000"
+
+  assert.equal(
+    shouldResetRendererAccessTokenForNavigation("http://127.0.0.1:3000/reload", false, true, trusted),
+    true,
+  )
+  assert.equal(
+    shouldResetRendererAccessTokenForNavigation("http://127.0.0.1:3000/frame", false, false, trusted),
+    false,
+  )
+  assert.equal(
+    shouldResetRendererAccessTokenForNavigation("http://127.0.0.1:3000/#route", true, true, trusted),
+    false,
+  )
+  assert.equal(
+    shouldResetRendererAccessTokenForNavigation("https://untrusted.example/reload", false, true, trusted),
+    false,
+  )
+})
+
+test("client-state handlers require the claimed nonempty renderer token", async (testContext) => {
+  const directory = mkdtempSync(join(tmpdir(), "codenomad-client-state-ipc-"))
+  const manager = new ClientStateManager(directory)
+  const handlers = createClientStateIPCHandlers(manager)
+  testContext.after(async () => {
+    await manager.drainAndReleasePrimary().catch(() => {})
+    rmSync(directory, { recursive: true, force: true })
+  })
+
+  assert.throws(() => handlers.claimAccess(""), /nonempty string/)
+  assert.throws(() => handlers.load("not-claimed"), /has not been claimed/)
+  assert.equal(handlers.claimAccess("trusted-renderer-token"), true)
+  assert.equal(handlers.claimAccess("trusted-renderer-token"), true)
+  assert.throws(() => handlers.claimAccess("child-frame-token"), /does not match/)
+
+  for (const invoke of [
+    () => handlers.load("child-frame-token"),
+    () => handlers.save("child-frame-token", { denied: true }),
+    () => handlers.setRestoreEnabled("child-frame-token", false),
+    () => handlers.clear("child-frame-token"),
+  ]) {
+    assert.throws(invoke, /has not been claimed/)
+  }
+
+  assert.equal(await handlers.save("trusted-renderer-token", { shutdownFlush: true }), true)
+  assert.deepEqual(handlers.load("trusted-renderer-token").snapshot, { shutdownFlush: true })
+})
+
+test("trusted renderer navigation reset invalidates the old token before a new claim", async (testContext) => {
+  const directory = mkdtempSync(join(tmpdir(), "codenomad-client-state-token-reset-"))
+  const manager = new ClientStateManager(directory)
+  const handlers = createClientStateIPCHandlers(manager)
+  testContext.after(async () => {
+    await manager.drainAndReleasePrimary().catch(() => {})
+    rmSync(directory, { recursive: true, force: true })
+  })
+
+  handlers.claimAccess("first-document")
+  manager.resetRendererAccessToken()
+
+  assert.throws(() => handlers.load("first-document"), /has not been claimed/)
+  assert.equal(handlers.claimAccess("reloaded-document"), true)
+  assert.equal(handlers.load("reloaded-document").isPrimary, true)
+})

packages/electron-app/electron/main/client-state-ipc-handlers.test.ts

@@ -0,0 +1,52 @@
+import type { ClientStateManager } from "./client-state"
+
+export function shouldResetRendererAccessTokenForNavigation(
+  url: string,
+  isInPlace: boolean,
+  isMainFrame: boolean,
+  isTrustedOrigin: (url: string) => boolean,
+): boolean {
+  return isMainFrame && !isInPlace && isTrustedOrigin(url)
+}
+
+export function createRendererAccessNavigationCommitHandler(
+  clientState: Pick<ClientStateManager, "resetRendererAccessToken">,
+  isTrustedOrigin: (url: string) => boolean,
+) {
+  return (url: string, isInPlace: boolean, isMainFrame: boolean): void => {
+    if (shouldResetRendererAccessTokenForNavigation(url, isInPlace, isMainFrame, isTrustedOrigin)) {
+      clientState.resetRendererAccessToken()
+    }
+  }
+}
+
+export function createClientStateIPCHandlers(clientState: ClientStateManager) {
+  const requireAccess = (token: unknown) => clientState.assertRendererAccessToken(token)
+
+  return {
+    claimAccess(token: unknown) {
+      return clientState.claimClientStateAccess(token)
+    },
+    load(token: unknown) {
+      requireAccess(token)
+      return clientState.loadClientState()
+    },
+    save(token: unknown, snapshot: unknown) {
+      requireAccess(token)
+      return clientState.saveClientState(snapshot)
+    },
+    setRestoreEnabled(token: unknown, enabled: unknown) {
+      requireAccess(token)
+      if (typeof enabled !== "boolean") {
+        throw new TypeError("Restore enabled must be a boolean")
+      }
+      return clientState.setRestoreEnabled(enabled)
+    },
+    clear(token: unknown) {
+      requireAccess(token)
+      return clientState.clearClientState()
+    },
+  }
+}
+
+export type ClientStateIPCHandlers = ReturnType<typeof createClientStateIPCHandlers>

packages/electron-app/electron/main/client-state-ipc-handlers.ts

@@ -0,0 +1,68 @@
+import { ipcMain, type BrowserWindow, type IpcMainInvokeEvent } from "electron"
+import type { ClientStateManager } from "./client-state"
+import {
+  createClientStateIPCHandlers,
+  createRendererAccessNavigationCommitHandler,
+} from "./client-state-ipc-handlers"
+import { isAllowedRendererOrigin } from "./permissions"
+
+function validateSender(event: IpcMainInvokeEvent, mainWindow: BrowserWindow, getAllowedOrigins: () => string[]) {
+  if (
+    mainWindow.isDestroyed() ||
+    event.sender !== mainWindow.webContents ||
+    event.senderFrame !== mainWindow.webContents.mainFrame
+  ) {
+    throw new Error("Client state IPC is only available to the local main window")
+  }
+
+  const allowedOrigins = getAllowedOrigins()
+  const currentUrl = mainWindow.webContents.getURL()
+  if (
+    !isAllowedRendererOrigin(currentUrl, allowedOrigins) ||
+    !isAllowedRendererOrigin(event.senderFrame.url, allowedOrigins) ||
+    new URL(currentUrl).origin !== new URL(event.senderFrame.url).origin
+  ) {
+    throw new Error("Client state IPC is not available to the current renderer origin")
+  }
+}
+
+export function setupClientStateIPC(
+  mainWindow: BrowserWindow,
+  clientState: ClientStateManager,
+  getAllowedOrigins: () => string[],
+) {
+  const handlers = createClientStateIPCHandlers(clientState)
+  const handleNavigationCommit = createRendererAccessNavigationCommitHandler(
+    clientState,
+    (url) => isAllowedRendererOrigin(url, getAllowedOrigins()),
+  )
+
+  ipcMain.handle("client-state:claimAccess", async (event, token: unknown) => {
+    validateSender(event, mainWindow, getAllowedOrigins)
+    return handlers.claimAccess(token)
+  })
+
+  ipcMain.handle("client-state:load", async (event, token: unknown) => {
+    validateSender(event, mainWindow, getAllowedOrigins)
+    return handlers.load(token)
+  })
+
+  ipcMain.handle("client-state:save", async (event, token: unknown, snapshot: unknown) => {
+    validateSender(event, mainWindow, getAllowedOrigins)
+    return handlers.save(token, snapshot)
+  })
+
+  ipcMain.handle("client-state:setRestoreEnabled", async (event, token: unknown, enabled: unknown) => {
+    validateSender(event, mainWindow, getAllowedOrigins)
+    return handlers.setRestoreEnabled(token, enabled)
+  })
+
+  ipcMain.handle("client-state:clear", async (event, token: unknown) => {
+    validateSender(event, mainWindow, getAllowedOrigins)
+    return handlers.clear(token)
+  })
+
+  mainWindow.webContents.on("did-navigate", (_event, url) => {
+    handleNavigationCommit(url, false, true)
+  })
+}

packages/electron-app/electron/main/client-state-ipc.ts

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import type { App, BrowserWindow } from "electron"
+import { ClientStateLifecycle } from "./client-state-lifecycle"
+import type { ClientStateManager } from "./client-state"
+import type { CliProcessManager } from "./process-manager"
+import type { WindowStateTracker } from "./window-state"
+
+function createHarness(options: { rendererFlush?: () => Promise<unknown>; timeoutMs?: number } = {}) {
+  const handlers = new Map<string, (event?: { preventDefault(): void }) => void>()
+  let nativeFlushes = 0
+  let rendererFlushes = 0
+  let primaryReleases = 0
+  let cliStops = 0
+  let exits = 0
+  const window = {
+    on: (event: string, handler: () => void) => {
+      handlers.set(event, handler)
+    },
+    isDestroyed: () => false,
+    close: () => {},
+    webContents: {
+      isDestroyed: () => false,
+      getURL: () => "http://127.0.0.1:43123/workspace",
+      executeJavaScript: () => {
+        rendererFlushes += 1
+        return options.rendererFlush?.() ?? Promise.resolve()
+      },
+    },
+  } as unknown as BrowserWindow
+  const app = { on: () => {}, quit: () => {}, exit: () => { exits += 1 } } as unknown as App
+  const clientStateManager = {
+    isPrimary: true,
+    drainAndReleasePrimary: async () => { primaryReleases += 1 },
+  } as ClientStateManager
+  const cliManager = { stop: async () => { cliStops += 1 } } as unknown as CliProcessManager
+  const lifecycle = new ClientStateLifecycle({
+    app,
+    clientStateManager,
+    cliManager,
+    getMainWindow: () => window,
+    getAllWindows: () => [window],
+    getAllowedRendererOrigins: () => ["http://127.0.0.1:43123"],
+    isTrustedRendererOrigin: () => true,
+    windowsSessionEndFlushTimeoutMs: options.timeoutMs,
+    rendererFlushTimeoutMs: options.timeoutMs === undefined ? undefined : options.timeoutMs * 2,
+    isWindows: true,
+  })
+  const tracker = { flush: async () => { nativeFlushes += 1 } } as unknown as WindowStateTracker
+  lifecycle.attachMainWindow(window, tracker)
+  return {
+    handlers,
+    lifecycle,
+    getNativeFlushes: () => nativeFlushes,
+    getRendererFlushes: () => rendererFlushes,
+    getPrimaryReleases: () => primaryReleases,
+    getCliStops: () => cliStops,
+    getExits: () => exits,
+  }
+}
+
+test("Windows session termination flushes renderer and native client state once", async () => {
+  const harness = createHarness()
+
+  let prevented = false
+  harness.handlers.get("query-session-end")?.({ preventDefault: () => { prevented = true } })
+  harness.handlers.get("session-end")?.()
+  await (harness.lifecycle as any).windowsSessionEndFlush
+  await new Promise((resolve) => setImmediate(resolve))
+
+  assert.equal(prevented, true)
+  assert.equal(harness.getRendererFlushes(), 1)
+  assert.equal(harness.getNativeFlushes(), 1)
+  assert.equal(harness.getPrimaryReleases(), 1)
+  assert.equal(harness.getCliStops(), 1)
+  assert.equal(harness.getExits(), 1)
+})
+
+test("Windows session termination flush is globally bounded", async () => {
+  const harness = createHarness({ rendererFlush: () => new Promise(() => {}), timeoutMs: 20 })
+  const startedAt = Date.now()
+
+  harness.handlers.get("query-session-end")?.({ preventDefault: () => {} })
+  await (harness.lifecycle as any).windowsSessionEndFlush
+  await new Promise((resolve) => setImmediate(resolve))
+
+  assert.ok(Date.now() - startedAt < 500)
+  assert.equal(harness.getRendererFlushes(), 1)
+  assert.equal(harness.getNativeFlushes(), 0)
+  assert.equal(harness.getPrimaryReleases(), 0)
+  assert.equal(harness.getCliStops(), 0)
+  assert.equal(harness.getExits(), 1)
+})