pmx-canvas 0.8.2 → 0.9.1

package/src/client/state/sse-bridge.ts

@@ -1,5 +1,8 @@
 import { findOpenCanvasPosition } from '../utils/placement.js';
-import { ownsCamera } from './presentation';
+import { refreshKnowledge } from './knowledge-store';
+import { applyWorkspaceSettings } from './workspace-settings';
+import { cameraSchema, tourStopSchema } from '../../shared/tour.js';
+import { ownsCamera, playStop, presentationError, presenting, presentStop, recordingCamera } from './presentation';
 import { isHostedWorkbench, workbenchFetch } from './workbench-transport';
 import { normalizeExtAppToolResult } from '../utils/ext-app-tool-result.js';
 import type { CanvasAnnotation, CanvasEdge, CanvasNodeState, NodeActor } from '../types';
@@ -11,8 +14,12 @@ import {
   axSurfaceState,
   bringToFront,
   cancelViewportAnimation,
+  commitViewport,
   canvasTheme,
   connectionStatus,
+  contextPinsRevision,
+  contextPinsPendingWrites,
+  refreshContextPins,
   replaceContextPinsFromServer,
   edges,
   focusNode,
@@ -30,8 +37,18 @@ import {
   reconnectDelay,
   resetCanvasInteractionState,
 } from './canvas-store';
-import { applyBoards, loadBoards, setBoardSwitchHandler } from './boards-store';
+import {
+  activeBoardId,
+  applyBoards,
+  boardGeneration,
+  catalogEpoch,
+  connectBoardCatalog,
+  loadBoards,
+  memoryGraphRevision,
+  setBoardSwitchHandler,
+} from './boards-store';
 import { applyContextStatus, refreshContextStatus } from './context-status-store';
+import { refreshContextChip } from './context-chip-store';
 import {
   fetchAgentPresence,
   fetchAxSurfaceState,
@@ -41,9 +58,9 @@ import {
   tabAgentKey,
 } from './intent-bridge';
 import { agentActivity, applyPresenceSnapshot, sessionActive } from './presence-store';
-import { applyHumanSnapshot, startHumanPresence } from './human-store';
+import { applyHumanSnapshot, humanClientId, startHumanPresence, stopHumanPresence } from './human-store';
 import type { HumanPresenceSnapshot } from '../../shared/human-presence.js';
-import { applySessionReceipt, dismissSessionReceipt, refreshTimeline } from './session-store';
+import { activityLens, applySessionReceipt, dismissSessionReceipt, refreshTimeline } from './session-store';
 import { initSessionThemeOverride, themeOverrideActive } from './theme-override';
 import { DEFAULT_POSITIONS, makeNodeState } from './node-factory';
 import { invalidateTokenCache } from '../theme/tokens';
@@ -64,14 +81,19 @@ let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 // "opens" (headers pass through) but no event ever arrives. Fallback: if the
 // stream produces no event at all within the watchdog window, switch to
 // polling GET /api/workbench/poll, which returns buffered events (or a full
-// connect snapshot) as a normal response every couple of seconds. The same
+// connect snapshot) as a completed response as soon as an event arrives. The same
 // EVENT_HANDLERS map serves both transports. `?transport=poll` forces polling
 // from the start; `?transport=sse` disables the fallback.
 const SSE_FIRST_EVENT_WATCHDOG_MS = 3000;
 const POLL_INTERVAL_MS = 2000;
+const POLL_WAIT_MS = 1000;
+const POLL_LIVE_INTERVAL_MS = 80;
 const POLL_ERROR_INTERVAL_MS = 5000;
+// Bound headers AND body, including host transports that ignore AbortSignal.
+const POLL_REQUEST_TIMEOUT_MS = 10000;
 let pollingMode = false;
 let pollTimer: ReturnType<typeof setTimeout> | null = null;
+let pollAbort: AbortController | null = null;
 let pollSeq: number | null = null;
 let pollGeneration = 0;
 let sseFirstEventWatchdog: ReturnType<typeof setTimeout> | null = null;
@@ -369,6 +391,7 @@ function parseCanvasNode(raw: Record<string, unknown>): CanvasNodeState | null {
     collapsed: raw.collapsed === true,
     pinned: raw.pinned === true,
     contentRevision: typeof raw.contentRevision === 'number' ? raw.contentRevision : 0,
+    linksRevision: typeof raw.linksRevision === 'number' ? raw.linksRevision : 0,
     ...(isActor(raw.createdBy) ? { createdBy: raw.createdBy } : {}),
     ...(isActor(raw.lastEditedBy) ? { lastEditedBy: raw.lastEditedBy } : {}),
     data,
@@ -391,10 +414,18 @@ function parseCanvasEdge(raw: Record<string, unknown>): CanvasEdge | null {
     id: raw.id,
     from: raw.from,
     to: raw.to,
+    ...(typeof raw.toBoardId === 'string' ? { toBoardId: raw.toBoardId } : {}),
     type: raw.type,
+    ...(typeof raw.kind === 'string' ? { kind: raw.kind } : {}),
+    ...(typeof raw.reason === 'string' ? { reason: raw.reason } : {}),
     ...(typeof raw.label === 'string' ? { label: raw.label } : {}),
     ...(raw.style === 'solid' || raw.style === 'dashed' || raw.style === 'dotted' ? { style: raw.style } : {}),
     ...(raw.animated === true ? { animated: true } : {}),
+    ...(typeof raw.revision === 'number' ? { revision: raw.revision } : {}),
+    ...(isActor(raw.changedBy) ? { changedBy: raw.changedBy } : {}),
+    ...(typeof raw.changedAt === 'string' ? { changedAt: raw.changedAt } : {}),
+    ...(isActor(raw.createdBy) ? { createdBy: raw.createdBy } : {}),
+    ...(typeof raw.createdAt === 'string' ? { createdAt: raw.createdAt } : {}),
   };
 }
 
@@ -471,10 +502,9 @@ function handleAgentSessionEnded(data: Record<string, unknown>): void {
   applySessionReceipt(data);
 }
 
-let stopHumanPresence: (() => void) | null = null;
 let boardResyncGeneration = 0;
 let layoutRevision = 0;
-let pinsRevision = 0;
+let pendingBoardLayout: Record<string, unknown> | null = null;
 
 function handleHumanPresence(data: Record<string, unknown>): void {
   applyHumanSnapshot(data as Partial<HumanPresenceSnapshot>);
@@ -485,32 +515,61 @@ function handleHumanPresence(data: Record<string, unknown>): void {
  * a different board now, so take its layout like a fresh connection would —
  * camera included — and drop what belonged to the old board.
  */
-function resyncForBoardSwitch(): void {
+function resyncForBoardSwitch(initial: boolean): void {
+  const pending = pendingBoardLayout;
+  pendingBoardLayout = null;
+  if (initial) {
+    // Untagged initial fetches may already have supplied the layout. Tagged
+    // SSE waits here for the first catalog to identify its owner.
+    if (pending?.boardId === activeBoardId.value) handleCanvasLayoutUpdate(pending);
+    return;
+  }
+  const boardId = activeBoardId.value;
   const generation = ++boardResyncGeneration;
   savedLayout = null;
   hasInitialServerLayout.value = false;
   resetIntents();
   resetCanvasInteractionState();
   resetAttentionBridge();
-  dismissSessionReceipt();
+  applyServerCanvasLayout({ nodes: [], edges: [] });
+  if (pending?.boardId === activeBoardId.value) handleCanvasLayoutUpdate(pending);
+  // Keep the change available when visiting another board, so its Open board
+  // action can bring the person back to Undo. Home still clears board chrome.
+  if (activeBoardId.value === null) dismissSessionReceipt();
+  if (activityLens.value?.kind === 'receipt') activityLens.value = null;
   applyContextStatus({});
   axSurfaceState.value = null;
   void refreshAxSurface();
   const layoutAtRequest = layoutRevision;
-  const pinsAtRequest = pinsRevision;
-  void fetchCanvasState().then((layout) => {
+  const pinsAtRequest = contextPinsRevision;
+  void fetchCanvasState(boardId).then((layout) => {
     if (generation === boardResyncGeneration && layoutAtRequest === layoutRevision)
-      handleCanvasLayoutUpdate({ layout });
+      handleCanvasLayoutUpdate({ layout, boardId });
   });
   void requestJson<{ nodeIds?: unknown }>('fetchPinnedContext', '/api/canvas/pinned-context', {}).then((data) => {
-    if (generation === boardResyncGeneration && pinsAtRequest === pinsRevision)
+    if (generation === boardResyncGeneration && pinsAtRequest === contextPinsRevision)
       handleContextPinsChanged({ nodeIds: data.nodeIds });
   });
 }
 setBoardSwitchHandler(resyncForBoardSwitch);
 
 function handleConnected(data: Record<string, unknown>): void {
+  memoryGraphRevision.value++;
+  // A current connection authorizes catalogs from this server run. Old HTTP
+  // continuations and buffered layouts cannot cross the snapshot boundary.
+  boardResyncGeneration++;
+  pendingBoardLayout = null;
+  // The following snapshot is a fresh baseline, including lower revisions after
+  // a restart/restore. Keep same-board editors and their text selections mounted.
+  hasInitialServerLayout.value = false;
+  if (typeof data.catalogEpoch === 'string') connectBoardCatalog(data.catalogEpoch);
+  // A same-bundle daemon restart keeps drafts alive but rotates its human capability.
+  // Install it before connect-time requests or presence heartbeats can write.
+  if (!isHostedWorkbench() && typeof data.workbenchToken === 'string') {
+    (window as Window & { __PMX_WORKBENCH_TOKEN?: string }).__PMX_WORKBENCH_TOKEN = data.workbenchToken;
+  }
   sessionId.value = (data.sessionId as string) || '';
+  applyWorkspaceSettings(data.workspaceSettings);
   connectionStatus.value = 'connected';
   // Hosted writes capture the active board. Load its identity before reporting
   // the viewport, rather than sending a spurious Home precondition on boot.
@@ -522,11 +581,12 @@ function handleConnected(data: Record<string, unknown>): void {
   // keep it live from here on.
   void fetchAgentPresence().then(applyPresenceSnapshot);
   void refreshContextStatus();
+  refreshContextChip();
   // Human collaborators (phase 8): announce this tab and read who else is here.
   // An `?agent=<key>` tab is an AGENT's view — it must not heartbeat a human
   // guest cursor (its writes already book as the agent).
-  stopHumanPresence?.();
-  if (!tabAgentKey && !isHostedWorkbench()) stopHumanPresence = startHumanPresence();
+  stopHumanPresence();
+  if (!tabAgentKey && !isHostedWorkbench()) startHumanPresence();
   void requestJson<Partial<HumanPresenceSnapshot> | null>(
     'fetchHumanPresence',
     '/api/canvas/human-presence',
@@ -942,6 +1002,9 @@ function handleCanvasResponseComplete(data: Record<string, unknown>): void {
 // ── Agent canvas tool events ──────────────────────────────────
 
 function handleCanvasLayoutUpdate(data: Record<string, unknown>): void {
+  // Even an inactive board can affect library links. This invalidates a read;
+  // the ownership guards below still control applying the canvas snapshot.
+  memoryGraphRevision.value++;
   const layout = data.layout as
     | {
         nodes?: Array<Record<string, unknown>>;
@@ -951,6 +1014,22 @@ function handleCanvasLayoutUpdate(data: Record<string, unknown>): void {
       }
     | undefined;
   if (!layout?.nodes) return;
+  // Board IDs repeat on A → B → A and after restores. Only the accepted
+  // activation may establish its camera/content baseline.
+  if (typeof data.boardGeneration === 'number') {
+    if (data.catalogEpoch !== catalogEpoch || (boardGeneration !== null && data.boardGeneration < boardGeneration))
+      return;
+    if (boardGeneration === null || data.boardGeneration > boardGeneration) {
+      pendingBoardLayout = data;
+      return;
+    }
+  }
+  // The server sends a switched board's layout before boards-changed. Do not
+  // mount it under the previous owner, even when card IDs happen to match.
+  if (data.boardId !== undefined && data.boardId !== activeBoardId.value) {
+    pendingBoardLayout = data;
+    return;
+  }
   layoutRevision += 1;
   const shouldApplyViewport = !hasInitialServerLayout.value;
   hasInitialServerLayout.value = true;
@@ -986,6 +1065,8 @@ function handleCanvasLayoutUpdate(data: Record<string, unknown>): void {
   );
 
   syncAttentionFromSse({ event: 'canvas-layout-update', data });
+  // Content changes move the brief's size and can clip it (debounced, so a burst fetches once).
+  refreshContextChip(1_000);
 }
 
 function reconnectDelayMs(attempt: number): number {
@@ -1007,7 +1088,8 @@ function handleCanvasFocusNode(data: Record<string, unknown>): void {
 }
 
 function handleCanvasViewportUpdate(data: Record<string, unknown>): void {
-  if (ownsCamera()) return;
+  // A delayed echo of this tab's earlier commit must not cancel its newer gesture.
+  if (ownsCamera() || data.clientId === humanClientId) return;
   const viewport = data.viewport as Record<string, unknown> | undefined;
   if (!viewport) return;
   const x = typeof viewport.x === 'number' ? viewport.x : 0;
@@ -1017,6 +1099,40 @@ function handleCanvasViewportUpdate(data: Record<string, unknown>): void {
   replaceViewport({ x, y, scale });
 }
 
+// Tour steps and camera moves animate locally; a deterministic capture owns
+// its camera outright and ignores both.
+function handleCanvasTourStep(data: Record<string, unknown>): void {
+  if (recordingCamera.value) return;
+  // A human stepping in one tab moves tabs already presenting; only a
+  // `present` step (the agent's default) starts presenting elsewhere.
+  if (!presenting.value && data.present !== true) return;
+  const stop = tourStopSchema.safeParse(data.stop);
+  if (stop.success) presentStop(stop.data);
+}
+
+function handleCanvasTourExit(): void {
+  if (recordingCamera.value) return;
+  presenting.value = false;
+  presentationError.value = '';
+}
+
+function handleCanvasCameraMove(data: Record<string, unknown>): void {
+  if (recordingCamera.value) return;
+  const stop = tourStopSchema.safeParse(data.stop);
+  if (!stop.success) return;
+  try {
+    // The presentation camera is local; otherwise the end camera becomes the
+    // board viewport — unrecorded, so a camera move is never an undo step.
+    playStop(stop.data, presenting.value ? undefined : (end) => commitViewport(end, { recordHistory: false }));
+  } catch {
+    // Target not in this tab's layout yet: take the server's resolved camera.
+    const fallback = cameraSchema.safeParse(data.viewport);
+    if (!fallback.success) return;
+    cancelViewportAnimation();
+    replaceViewport(fallback.data);
+  }
+}
+
 function handleContextUsage(data: Record<string, unknown>): void {
   const id = 'context-main';
   const existing = nodes.value.get(id);
@@ -1042,15 +1158,17 @@ function handleThemeChanged(data: Record<string, unknown>): void {
 }
 
 function handleContextPinsChanged(data: Record<string, unknown>): void {
-  pinsRevision += 1;
+  memoryGraphRevision.value++;
   const nodeIds = Array.isArray(data.nodeIds) ? data.nodeIds.filter((id): id is string => typeof id === 'string') : [];
-  replaceContextPinsFromServer(nodeIds);
+  if (contextPinsPendingWrites === 0) replaceContextPinsFromServer(nodeIds);
   syncAttentionFromSse({ event: 'context-pins-changed', data });
   void refreshContextStatus();
+  refreshContextChip();
 }
 
 function handleContextStatusChanged(): void {
   void refreshContextStatus();
+  refreshContextChip();
 }
 
 // AX state changes arrive as per-primitive deltas; rather than reduce them, treat
@@ -1128,13 +1246,22 @@ export const EVENT_HANDLERS: Record<string, (data: Record<string, unknown>) => v
   'ext-app-result': handleExtAppResult,
   'context-pins-changed': handleContextPinsChanged,
   'context-status-changed': handleContextStatusChanged,
-  'boards-changed': applyBoards,
+  'knowledge-changed': () => void refreshKnowledge(),
+  'lifecycle-changed': () => void refreshKnowledge(),
+  'boards-changed': (data) => {
+    applyBoards(data);
+    refreshContextChip();
+  },
   'canvas-layout-update': handleCanvasLayoutUpdate,
   'canvas-focus-node': handleCanvasFocusNode,
   'canvas-viewport-update': handleCanvasViewportUpdate,
+  'canvas-tour-step': handleCanvasTourStep,
+  'canvas-tour-exit': handleCanvasTourExit,
+  'canvas-camera-move': handleCanvasCameraMove,
   'context-usage': handleContextUsage,
   'trace-state': handleTraceState,
   'theme-changed': handleThemeChanged,
+  'settings-changed': (data) => applyWorkspaceSettings(data.workspaceSettings),
   'canvas-prompt-created': handleCanvasPromptCreated,
   'canvas-prompt-status': handleCanvasPromptStatus,
   'canvas-response-start': handleCanvasResponseStart,
@@ -1174,6 +1301,12 @@ function startPollingTransport(): () => void {
   pollingMode = true;
   pollGeneration += 1;
   const generation = pollGeneration;
+  pollAbort?.abort();
+  const controller = new AbortController();
+  pollAbort = controller;
+  // MCP-app polls are host tool calls, not direct HTTP requests. Keep their
+  // existing cadence; HTTP clients can park one request until an event arrives.
+  const longPolling = !isHostedWorkbench();
   connectionStatus.value = 'connecting';
   // Server-run identity from the last poll response. The event seq counter
   // restarts at 0 on every server boot, so a cursor from a previous run can
@@ -1183,22 +1316,39 @@ function startPollingTransport(): () => void {
 
   const pollOnce = async (): Promise<void> => {
     if (generation !== pollGeneration) return;
+    const requestController = new AbortController();
+    let deadline: ReturnType<typeof setTimeout> | undefined;
     try {
       const params = new URLSearchParams();
-      if (pollSeq !== null) params.set('since', String(pollSeq));
+      if (pollSeq !== null) {
+        params.set('since', String(pollSeq));
+        if (longPolling) params.set('waitMs', String(POLL_WAIT_MS));
+      }
       const sid = sessionId.value;
       if (sid) params.set('session', sid);
       const query = params.toString();
-      const response = await workbenchFetch(`/api/workbench/poll${query ? `?${query}` : ''}`);
-      if (generation !== pollGeneration) return;
-      if (!response.ok) throw new Error(`poll failed with HTTP ${response.status}`);
-      const body = (await response.json()) as {
-        ok: boolean;
-        seq: number;
-        snapshot: boolean;
-        sessionId?: string;
-        events: Array<{ event: string; payload: unknown }>;
-      };
+      const pinsAtRequest = contextPinsRevision;
+      const body = await Promise.race([
+        (async () => {
+          const response = await workbenchFetch(`/api/workbench/poll${query ? `?${query}` : ''}`, {
+            signal: AbortSignal.any([controller.signal, requestController.signal]),
+          });
+          if (!response.ok) throw new Error(`poll failed with HTTP ${response.status}`);
+          return (await response.json()) as {
+            ok: boolean;
+            seq: number;
+            snapshot: boolean;
+            sessionId?: string;
+            events: Array<{ event: string; payload: unknown }>;
+          };
+        })(),
+        new Promise<never>((_, reject) => {
+          deadline = setTimeout(() => {
+            requestController.abort();
+            reject(new Error('poll request timed out'));
+          }, POLL_REQUEST_TIMEOUT_MS);
+        }),
+      ]);
       if (generation !== pollGeneration) return;
       if (!body.ok) throw new Error('poll returned ok: false');
       const priorSession = lastPollSessionId;
@@ -1222,13 +1372,55 @@ function startPollingTransport(): () => void {
         resetIntents();
         responseToThreadMap.clear();
       }
-      for (const entry of body.events) dispatchWorkbenchEvent(entry.event, entry.payload);
+      // A poll may have captured pins before a newer human click or write acknowledgement.
+      // Skip only those pin frames, then read the canonical set so peer changes and server
+      // normalization still arrive even though the event cursor advances past the old batch.
+      const acceptPins = pinsAtRequest === contextPinsRevision && contextPinsPendingWrites === 0;
+      let skippedPins = false;
+      // Full layouts in a buffered poll can predate an HTTP refresh. Replaying
+      // an obsolete empty layout would detach a live editor before its card
+      // reappears. Keep the last snapshot across bookkeeping frames only:
+      // commands (focus, tours, deltas, etc.) still need their preceding layout.
+      const supersededLayouts = new Set<(typeof body.events)[number]>();
+      if (!body.snapshot && hasInitialServerLayout.value) {
+        let previousLayout: (typeof body.events)[number] | undefined;
+        for (const entry of body.events) {
+          const data = entry.payload as Record<string, unknown>;
+          const sameActivation =
+            data.catalogEpoch === catalogEpoch &&
+            data.boardGeneration === boardGeneration &&
+            (entry.event === 'boards-changed' ? data.activeBoardId : data.boardId) === activeBoardId.value;
+          if (entry.event === 'canvas-layout-update' && sameActivation) {
+            if (previousLayout) supersededLayouts.add(previousLayout);
+            previousLayout = entry;
+          } else if (
+            !(entry.event === 'boards-changed' && sameActivation) &&
+            !['agent-presence', 'human-presence', 'ax-intent', 'ax-intent-clear'].includes(entry.event)
+          ) {
+            previousLayout = undefined;
+          }
+        }
+      }
+      for (const entry of body.events) {
+        if (supersededLayouts.has(entry)) continue;
+        if (entry.event === 'context-pins-changed' && !acceptPins) {
+          skippedPins = true;
+          continue;
+        }
+        dispatchWorkbenchEvent(entry.event, entry.payload);
+      }
+      if (skippedPins) {
+        void refreshContextPins();
+        void refreshContextStatus();
+        refreshContextChip();
+      }
       dispatchedOnce = true;
       pollSeq = body.seq;
       reconnectAttempt.value = 0;
       reconnectDelay.value = 0;
       connectionStatus.value = 'connected';
-      pollTimer = setTimeout(() => void pollOnce(), POLL_INTERVAL_MS);
+      // Bound busy-stream request rate without imposing a two-second cursor gap.
+      pollTimer = setTimeout(() => void pollOnce(), longPolling ? POLL_LIVE_INTERVAL_MS : POLL_INTERVAL_MS);
     } catch (err) {
       if (generation !== pollGeneration) return;
       console.warn('[sse-bridge] poll transport error:', err);
@@ -1236,14 +1428,19 @@ function startPollingTransport(): () => void {
       reconnectAttempt.value += 1;
       reconnectDelay.value = POLL_ERROR_INTERVAL_MS;
       pollTimer = setTimeout(() => void pollOnce(), POLL_ERROR_INTERVAL_MS);
+    } finally {
+      clearTimeout(deadline);
     }
   };
   void pollOnce();
 
   return () => {
+    stopHumanPresence();
     pollGeneration += 1;
     pollingMode = false;
     pollSeq = null;
+    controller.abort();
+    if (pollAbort === controller) pollAbort = null;
     if (pollTimer) {
       clearTimeout(pollTimer);
       pollTimer = null;
@@ -1252,6 +1449,8 @@ function startPollingTransport(): () => void {
 }
 
 export function connectSSE(): () => void {
+  boardResyncGeneration++;
+  pendingBoardLayout = null;
   // Host-default theming: a ?theme= param applies before the first server
   // frame so an embedding host panel never flashes the server-global theme.
   initSessionThemeOverride(applyCanvasTheme);
@@ -1302,6 +1501,7 @@ export function connectSSE(): () => void {
 
   for (const [event] of Object.entries(EVENT_HANDLERS)) {
     source.addEventListener(event, (e) => {
+      if (eventSource !== source) return;
       gotFirstEvent = true;
       try {
         dispatchWorkbenchEvent(event, JSON.parse((e as MessageEvent).data));
@@ -1336,6 +1536,7 @@ export function connectSSE(): () => void {
   };
 
   return () => {
+    stopHumanPresence();
     if (reconnectTimer) {
       clearTimeout(reconnectTimer);
       reconnectTimer = null;
@@ -1348,6 +1549,8 @@ export function connectSSE(): () => void {
       pollGeneration += 1;
       pollingMode = false;
       pollSeq = null;
+      pollAbort?.abort();
+      pollAbort = null;
       if (pollTimer) {
         clearTimeout(pollTimer);
         pollTimer = null;

package/src/client/state/workspace-settings.ts

@@ -0,0 +1,11 @@
+import { computed, signal } from '@preact/signals';
+import { workspaceSettingsSchema, type WorkspaceSettings } from '../../shared/workspace-settings.js';
+
+export const workspaceSettings = signal<WorkspaceSettings | null>(null);
+export const agentSessionsEnabled = computed(() => workspaceSettings.value?.agentSessions ?? false);
+export const knowledgeLifecycleEnabled = computed(() => workspaceSettings.value?.knowledgeLifecycle ?? false);
+
+export function applyWorkspaceSettings(value: unknown): void {
+  const parsed = workspaceSettingsSchema.safeParse(value);
+  if (parsed.success) workspaceSettings.value = parsed.data;
+}