pmx-canvas 0.10.0 → 0.12.0

package/src/server/canvas-state.ts

@@ -12,7 +12,17 @@
  * the one-shot boot migration into SQLite was retired.
  */
 
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { createHash, randomUUID } from 'node:crypto';
+import {
+  prepareBoardMove,
+  type BoardMoveInput,
+  type BoardMovePreview,
+  type BoardMoveResult,
+  type MoveBoard,
+} from './board-move.js';
+import { boardMoveBoundary, recordCardRelocation } from './card-relocation.js';
+import { mutationHistory } from './mutation-history.js';
 import {
   DEFAULT_WORKSPACE_SETTINGS,
   workspaceSettingsPatchSchema,
@@ -43,6 +53,8 @@ import {
   openCanvasDb,
   saveStateToDB,
   loadStateFromDB,
+  boardStorageVersion,
+  assertBoardStorageVersion,
   saveSnapshotToDB,
   loadSnapshotFromDB,
   listSnapshotsFromDB,
@@ -364,6 +376,7 @@ export interface CanvasNodeUpdate {
   position?: { x: number; y: number };
   size?: { width: number; height: number };
   collapsed?: boolean;
+  zIndex?: number;
 }
 
 export type CanvasChangeType = 'pins' | 'nodes' | 'ax' | 'ax-timeline';
@@ -454,33 +467,232 @@ function isPersistedBlobRef(value: unknown): value is PersistedBlobRef {
   );
 }
 
+/** The mutable, board-owned partition. Workspace services remain on the manager. */
+interface LiveBoardState {
+  id: string | null;
+  disposed: boolean;
+  cleanup: Array<() => void>;
+  nodes: Map<string, CanvasNodeState>;
+  edges: Map<string, CanvasEdge>;
+  annotations: Map<string, CanvasAnnotation>;
+  viewport: ViewportState;
+  tour: Tour | undefined;
+  contextPinnedNodeIds: Set<string>;
+  contextPinMeta: Map<string, ContextPinMeta>;
+  storageVersion: number;
+  contentRevision: number;
+  revisionFloor: number;
+  deletionTombstones: NodeDeletionTombstone[];
+  generation: number;
+  saveTimer: ReturnType<typeof setTimeout> | null;
+  persistenceError: { message: string; at: string } | null;
+  ax: AxStateManager;
+}
+
 class CanvasStateManager {
-  private nodes = new Map<string, CanvasNodeState>();
-  private edges = new Map<string, CanvasEdge>();
-  private annotations = new Map<string, CanvasAnnotation>();
-  private _viewport: ViewportState = { x: 0, y: 0, scale: 1 };
-  private _tour: Tour | undefined;
+  private readonly boardExecution = new AsyncLocalStorage<LiveBoardState>();
+  private readonly liveBoards = new Map<string, LiveBoardState>();
+  private nextGeneration = 0;
+  private navigationGeneration = 0;
+  private readonly hostState: { capability: PmxAxHostCapability | null } = { capability: null };
+  private visibleBoard = this.createBoardState();
+
+  private get boardState(): LiveBoardState {
+    const board = this.boardExecution.getStore() ?? this.visibleBoard;
+    if (board.disposed) throw new OperationError('The target board was deleted or the workspace was replaced.', 409);
+    return board;
+  }
+
+  /** Identity for board-owned runtime caches. Never shared by a replacement board. */
+  get boardIdentity(): object {
+    return this.boardState;
+  }
+
+  onBoardDispose(cleanup: () => void): () => void {
+    const board = this.boardState;
+    board.cleanup.push(cleanup);
+    return () => {
+      const index = board.cleanup.indexOf(cleanup);
+      if (index >= 0) board.cleanup.splice(index, 1);
+    };
+  }
+
+  private disposeBoardRuntime(board: LiveBoardState): void {
+    for (const cleanup of board.cleanup.splice(0)) cleanup();
+  }
+
+  /** The human's navigation target, independent of the calling operation's board. */
+  get visibleBoardId(): string | null {
+    return this.visibleBoard.id;
+  }
+
+  get visibleBoardGeneration(): number {
+    return this.navigationGeneration;
+  }
+
+  get isBackgroundBoard(): boolean {
+    return this.boardState !== this.visibleBoard;
+  }
+
+  /** Execute on a live board without activating it, retaining ownership across awaits. */
+  withBoard<T>(id: string, fn: () => T): T {
+    const board = this.loadBoardState(id);
+    return this.boardExecution.run(board, fn);
+  }
+
+  /** Bind callbacks to their board, rather than the context of whoever invokes them. */
+  bindBoard<T extends unknown[], R>(fn: (...args: T) => R): (...args: T) => R {
+    const board = this.boardState;
+    return (...args) => this.boardExecution.run(board, () => fn(...args));
+  }
+
+  /** Viewer/global projections must not inherit the producer's board scope. */
+  withVisibleBoard<T>(fn: () => T): T {
+    return this.boardExecution.exit(fn);
+  }
+
+  /** Sweep resident runtime owners without loading the entire stored library. */
+  forEachLiveBoard(fn: () => void): void {
+    for (const board of new Set([this.visibleBoard, ...this.liveBoards.values()])) {
+      this.boardExecution.run(board, fn);
+    }
+  }
+
+  private loadBoardState(id: string): LiveBoardState {
+    const cached = this.liveBoards.get(id);
+    if (cached && this._db && cached.storageVersion === boardStorageVersion(this._db, id)) return cached;
+    if (cached?.saveTimer || cached?.persistenceError)
+      throw new OperationError(
+        `Board "${id}" changed in another writer. Reconcile unsaved edits before continuing.`,
+        409,
+      );
+    const state = this._db ? this.readProjectedBoard(id) : null;
+    if (!state) throw new OperationError(`Board "${id}" not found.`, 404);
+    const board = cached ?? this.createBoardState();
+    board.id = id;
+    this.boardExecution.run(board, () => {
+      this.initializePersistedWikiLinks(state, id);
+      this.applyPersistedState({ ...state, theme: this._theme });
+    });
+    this.liveBoards.set(id, board);
+    return board;
+  }
+
+  private createBoardState(): LiveBoardState {
+    return {
+      id: null,
+      disposed: false,
+      cleanup: [],
+      nodes: new Map(),
+      edges: new Map(),
+      annotations: new Map(),
+      viewport: { x: 0, y: 0, scale: 1 },
+      tour: undefined,
+      contextPinnedNodeIds: new Set(),
+      contextPinMeta: new Map(),
+      storageVersion: 0,
+      contentRevision: 0,
+      revisionFloor: 0,
+      deletionTombstones: [],
+      generation: ++this.nextGeneration,
+      saveTimer: null,
+      persistenceError: null,
+      ax: new AxStateManager(
+        {
+          getNodeIds: () => this.currentNodeIdSet(),
+          getDb: () => this._db,
+          scheduleSave: () => this.scheduleSave(),
+          notifyChange: (type) => this.notifyChange(type),
+          recordMutation: (info) => this.recordMutation(info),
+          suppressed: (fn) => this.suppressed(fn),
+        },
+        this.hostState,
+      ),
+    };
+  }
+
+  private get nodes() {
+    return this.boardState.nodes;
+  }
+  private get edges() {
+    return this.boardState.edges;
+  }
+  private get annotations() {
+    return this.boardState.annotations;
+  }
+  private get _viewport() {
+    return this.boardState.viewport;
+  }
+  private set _viewport(value: ViewportState) {
+    this.boardState.viewport = value;
+  }
+  private get _tour() {
+    return this.boardState.tour;
+  }
+  private set _tour(value: Tour | undefined) {
+    this.boardState.tour = value;
+  }
+  private get _contextPinnedNodeIds() {
+    return this.boardState.contextPinnedNodeIds;
+  }
+  private set _contextPinnedNodeIds(value: Set<string>) {
+    this.boardState.contextPinnedNodeIds = value;
+  }
+  private get _contextPinMeta() {
+    return this.boardState.contextPinMeta;
+  }
+  private set _contextPinMeta(value: Map<string, ContextPinMeta>) {
+    this.boardState.contextPinMeta = value;
+  }
+  private get _storageVersion() {
+    return this.boardState.storageVersion;
+  }
+  private set _storageVersion(value: number) {
+    this.boardState.storageVersion = value;
+  }
+  private get _contentRevision() {
+    return this.boardState.contentRevision;
+  }
+  private set _contentRevision(value: number) {
+    this.boardState.contentRevision = value;
+  }
+  private get _revisionFloor() {
+    return this.boardState.revisionFloor;
+  }
+  private set _revisionFloor(value: number) {
+    this.boardState.revisionFloor = value;
+  }
+  private get _deletionTombstones() {
+    return this.boardState.deletionTombstones;
+  }
+  private set _deletionTombstones(value: NodeDeletionTombstone[]) {
+    this.boardState.deletionTombstones = value;
+  }
+  private get _boardGeneration() {
+    return this.boardState.generation;
+  }
+  private set _boardGeneration(value: number) {
+    this.boardState.generation = value;
+  }
+  private get _saveTimer() {
+    return this.boardState.saveTimer;
+  }
+  private set _saveTimer(value: ReturnType<typeof setTimeout> | null) {
+    this.boardState.saveTimer = value;
+  }
+  private get _lastPersistenceError() {
+    return this.boardState.persistenceError;
+  }
+  private set _lastPersistenceError(value: LiveBoardState['persistenceError']) {
+    this.boardState.persistenceError = value;
+  }
+  private get ax() {
+    return this.boardState.ax;
+  }
+
   private _theme: CanvasTheme = 'harbor';
-  private _contextPinnedNodeIds = new Set<string>();
-  /** Who pinned each pin, when and why; kept only for ids in `_contextPinnedNodeIds`. */
-  private _contextPinMeta = new Map<string, ContextPinMeta>();
   private _workspaceRoot = process.cwd();
-  private _contentRevision = 0;
-  private _revisionFloor = 0;
-  private _deletionTombstones: NodeDeletionTombstone[] = [];
-
-  // ── AX state (canvas-bound + timeline + host partitions) ──────────
-  // Extracted into a dedicated manager (plan-007 Slice A). CanvasStateManager
-  // holds it and delegates its public AX methods so the SDK/HTTP/MCP surface is
-  // byte-stable; the manager receives the host hooks it needs as injected deps.
-  private readonly ax = new AxStateManager({
-    getNodeIds: () => this.currentNodeIdSet(),
-    getDb: () => this._db,
-    scheduleSave: () => this.scheduleSave(),
-    notifyChange: (type) => this.notifyChange(type),
-    recordMutation: (info) => this.recordMutation(info),
-    suppressed: (fn) => this.suppressed(fn),
-  });
+  private moveRuntimeBlockers: () => ReadonlyMap<string, string> = () => new Map();
 
   // ── Change listeners (for MCP resource notifications) ──────
   private _changeListeners: ((type: CanvasChangeType) => void)[] = [];
@@ -492,9 +704,15 @@ class CanvasStateManager {
    * — e.g. the long-lived MCP subscription — may ignore the return value).
    */
   onChange(cb: (type: CanvasChangeType) => void): () => void {
-    this._changeListeners.push(cb);
+    const owner = this.boardExecution.getStore();
+    const listener = owner
+      ? (type: CanvasChangeType) => {
+          if (owner === this.boardState) this.boardExecution.run(owner, () => cb(type));
+        }
+      : cb;
+    this._changeListeners.push(listener);
     return () => {
-      const i = this._changeListeners.indexOf(cb);
+      const i = this._changeListeners.indexOf(listener);
       if (i >= 0) this._changeListeners.splice(i, 1);
     };
   }
@@ -528,6 +746,7 @@ class CanvasStateManager {
   }
 
   private notifyChange(type: CanvasChangeType): void {
+    if (type === 'ax') this.refreshLiveWorkCards();
     // Iterate a snapshot: a listener (e.g. a blocking-wait via onChange) may dispose
     // itself synchronously here, and splicing the live array mid-iteration would skip
     // the next listener for this notification.
@@ -640,8 +859,29 @@ class CanvasStateManager {
     return { group, childIds, children };
   }
 
-  private normalizeNode(node: CanvasNodeState): CanvasNodeState {
+  private normalizeNode(
+    node: CanvasNodeState,
+    workItems?: PmxAxWorkItem[],
+    options: { boardId?: string; projectWork?: boolean } = {},
+  ): CanvasNodeState {
     const data = { ...node.data };
+    // These persisted fields are a derived display cache, never a second task record.
+    if (options.projectWork !== false && node.type === 'status' && typeof data.workItemId === 'string') {
+      const tasks =
+        typeof data.workItemBoardId === 'string' && data.workItemBoardId !== options.boardId
+          ? this.getWorkItemsOnBoard(data.workItemBoardId)
+          : (workItems ?? this.getWorkItems());
+      const task = tasks.find((item) => item.id === data.workItemId);
+      data.title = task?.title ?? 'Task unavailable';
+      data.detail = task?.detail ?? '';
+      data.liveWorkAvailable = !!task;
+      data.liveWorkSource = task?.agentId ?? task?.source ?? '';
+      delete data.progress;
+      delete data.content;
+      delete data.axWorkStatus;
+      if (task) data.workState = task.status;
+      else delete data.workState;
+    }
     // Lifecycle is optional metadata, never a card taxonomy or validation clock.
     delete data.categoryId;
     if (data.contentOrigin !== undefined && data.contentOrigin !== 'authored' && data.contentOrigin !== 'imported') {
@@ -665,6 +905,104 @@ class CanvasStateManager {
     };
   }
 
+  private refreshLiveWorkCards(): void {
+    const owner = this.boardState;
+    this.forEachLiveBoard(() => {
+      // Derived cache refreshes must not turn a clean stale board into an unsaved conflict.
+      if (
+        this.boardState !== owner &&
+        this._db &&
+        this._activeBoardId &&
+        !this._saveTimer &&
+        !this._lastPersistenceError &&
+        this._storageVersion !== boardStorageVersion(this._db, this._activeBoardId)
+      )
+        return;
+      this.refreshCurrentLiveWorkCards();
+    });
+  }
+
+  private refreshCurrentLiveWorkCards(preserveAttribution = false): void {
+    this.withSuppressedRecording(() => {
+      const tasks = this.getWorkItems();
+      for (const node of this.nodes.values()) {
+        if (node.type !== 'status' || typeof node.data.workItemId !== 'string') continue;
+        const next = this.normalizeNode(node, tasks);
+        if (!this.nodeContentChanged(node, next)) continue;
+        if (preserveAttribution) {
+          delete next.data.agentSummary;
+          delete next.data.summary;
+          this.nodes.set(node.id, {
+            ...next,
+            contentRevision: this.nextContentRevision(),
+            contentChangedAt: new Date().toISOString(),
+          });
+          this.scheduleSave();
+        } else this.updateNode(node.id, { data: next.data });
+      }
+    });
+  }
+
+  /** Reconcile a stored display cache and its cursor clock in the same SQLite transaction. */
+  private readProjectedBoard(boardId: string): PersistedCanvasState | null {
+    const db = this._db!;
+    // Validation inside another write must not change its captured versions or
+    // publish resident clocks before that outer transaction commits.
+    if (db.inTransaction) return loadStateFromDB(db, boardId);
+    const projected: CanvasNodeState[] = [];
+    let previousVersion = 0;
+    const state = db
+      .transaction(() => {
+        const state = loadStateFromDB(db, boardId);
+        if (!state) return null;
+        previousVersion = state.storageVersion ?? 0;
+        state.revisionState ??= { revision: 0, floor: 0, tombstones: [] };
+        const revision = state.revisionState;
+        state.nodes = state.nodes.map((node) => {
+          if (node.type !== 'status' || typeof node.data.workItemId !== 'string') return node;
+          const next = this.normalizeNode(node, state.ax?.workItems ?? [], { boardId });
+          if (!this.nodeContentChanged(node, next)) return node;
+          delete next.data.agentSummary;
+          delete next.data.summary;
+          next.contentRevision = ++revision.revision;
+          next.contentChangedAt = new Date().toISOString();
+          projected.push(next);
+          return next;
+        });
+        if (projected.length) state.storageVersion = saveStateToDB(db, boardId, state);
+        return state;
+      })
+      .immediate();
+    const live = this.liveBoards.get(boardId);
+    if (
+      state &&
+      projected.length &&
+      live &&
+      !live.saveTimer &&
+      !live.persistenceError &&
+      live.storageVersion === previousVersion
+    ) {
+      // Only the derived cache changed. Do not reinstall AX or renew approval TTLs.
+      this.boardExecution.run(live, () => {
+        for (const node of projected) this.nodes.set(node.id, structuredClone(node));
+        this._contentRevision = state.revisionState!.revision;
+        this._storageVersion = state.storageVersion!;
+      });
+    }
+    return state;
+  }
+
+  /** Call before capturing a context snapshot, never from per-node getters used during writes. */
+  refreshContextWorkCards(): void {
+    if (!this._db || !this._activeBoardId) return;
+    if (this._saveTimer || this._lastPersistenceError) {
+      this.refreshCurrentLiveWorkCards(true);
+      return;
+    }
+    const state = this.readProjectedBoard(this._activeBoardId);
+    if (state && state.storageVersion !== this._storageVersion) this.applyPersistedState(state, false);
+  }
+
   private nextContentRevision(): number {
     this._contentRevision += 1;
     return this._contentRevision;
@@ -705,7 +1043,9 @@ class CanvasStateManager {
   }
 
   private nodeForRead(node: CanvasNodeState): CanvasNodeState {
-    const resolved = this.resolveNodeDataBlobs(node);
+    const resolved = this.resolveNodeDataBlobs(
+      node.type === 'status' && typeof node.data.workItemId === 'string' ? this.normalizeNode(node) : node,
+    );
     return {
       ...resolved,
       pinned: resolved.pinned || this._contextPinnedNodeIds.has(resolved.id),
@@ -808,7 +1148,6 @@ class CanvasStateManager {
   // ── Persistence ────────────────────────────────────────────
   private _db: import('bun:sqlite').Database | null = null;
   private _dbPath: string | null = null;
-  private _saveTimer: ReturnType<typeof setTimeout> | null = null;
   readonly knowledge = new KnowledgeLifecycle(
     () => this._db,
     () => this.notifyChange('nodes'),
@@ -1038,7 +1377,7 @@ class CanvasStateManager {
     if (this._db) {
       try {
         const boardId = getActiveBoardIdFromDB(this._db);
-        const state = boardId ? loadStateFromDB(this._db, boardId) : null;
+        const state = boardId ? this.readProjectedBoard(boardId) : null;
         if (boardId && state) {
           this.initializePersistedWikiLinks(state, boardId);
           this.applyPersistedState(state);
@@ -1129,15 +1468,24 @@ class CanvasStateManager {
 
   // ── Boards ──────────────────────────────────────────────────
 
-  private _activeBoardId: string | null = null;
-  private _boardGeneration = 0;
+  private get _activeBoardId(): string | null {
+    return this.boardState.id;
+  }
+  private set _activeBoardId(id: string | null) {
+    this.boardState.id = id;
+    if (id) this.liveBoards.set(id, this.boardState);
+  }
 
   /** Invalidates asynchronous work whenever the loaded board state is replaced. */
   get boardGeneration(): number {
+    return this.boardExecution.getStore() ? this._boardGeneration : this.navigationGeneration;
+  }
+
+  get boardLifetimeGeneration(): number {
     return this._boardGeneration;
   }
 
-  /** The open board, or null on Home. */
+  /** The execution board, or the open board outside a scoped operation. */
   get activeBoardId(): string | null {
     return this._activeBoardId;
   }
@@ -1343,62 +1691,67 @@ class CanvasStateManager {
     let before: PersistedCanvasState | undefined;
     const activeLinkRevisions = new Map<string, number>();
     let activeRevision = this._contentRevision;
-    const result = db.transaction(() => {
-      const previous = requestId
-        ? db
-            .query<{ board_id: string; fingerprint: string; node: string }, [string]>(
-              'SELECT board_id, fingerprint, node FROM node_creation_requests WHERE request_id = ?',
-            )
-            .get(requestId)
-        : null;
-      if (previous) {
-        if (previous.board_id !== boardId || previous.fingerprint !== fingerprint)
-          throw new OperationError('requestId was already used with different creation input or destination.', 409);
-        // Return the original receipt even if the node has since been edited or removed.
-        return JSON.parse(previous.node) as T;
-      }
-      // Include pending edits in catalog resolution and durable relation clocks,
-      // without publishing or changing the active board before commit.
-      if (this._activeBoardId) saveStateToDB(db, this._activeBoardId, this.persistedState());
-      const state = loadStateFromDB(db, boardId);
-      if (!state) throw new OperationError(`Board "${boardId}" not found.`, 404);
-      const policies = [this.getPolicy(), state.ax?.policy];
-      if (policies.some((policy) => policy && (policy.scope || Object.keys(policy.agentScopes ?? {}).length)))
-        throw new OperationError('Destination/retry creation is refused while either board has a scope fence.', 403);
-      state.revisionState = {
-        ...state.revisionState,
-        revision: state.revisionState?.revision ?? 0,
-        floor: state.revisionState?.floor ?? 0,
-        tombstones: state.revisionState?.tombstones ?? [],
-      };
-      before = structuredClone(state);
-      const invalidations: Array<[string, string]> = [];
-      let next = build(state, (targetBoardId, nodeId) => invalidations.push([targetBoardId, nodeId]));
-      // Theme is workspace-global; never let an inactive projection overwrite it.
-      state.theme = this._theme;
-      saveStateToDB(db, boardId, state);
-      const invalidate = (targetBoardId: string, targetNodeId: string) => {
-        const revision = invalidateLinksInDB(db, targetBoardId, targetNodeId);
-        if (targetBoardId === this._activeBoardId && revision !== undefined) {
-          activeLinkRevisions.set(targetNodeId, revision);
-          activeRevision = Math.max(activeRevision, revision);
+    let activeStorageVersion = this._storageVersion;
+    const result = db
+      .transaction(() => {
+        const previous = requestId
+          ? db
+              .query<{ board_id: string; fingerprint: string; node: string }, [string]>(
+                'SELECT board_id, fingerprint, node FROM node_creation_requests WHERE request_id = ?',
+              )
+              .get(requestId)
+          : null;
+        if (previous) {
+          if (previous.board_id !== boardId || previous.fingerprint !== fingerprint)
+            throw new OperationError('requestId was already used with different creation input or destination.', 409);
+          // Return the original receipt even if the node has since been edited or removed.
+          return JSON.parse(previous.node) as T;
         }
-      };
-      for (const [targetBoardId, nodeId] of invalidations) invalidate(targetBoardId, nodeId);
-      if ('data' in next) invalidateIncomingLinksInDB(db, boardId, next.id, invalidate);
-      committed = loadStateFromDB(db, boardId)!;
-      next = ([...committed.nodes, ...committed.edges].find((candidate) => candidate.id === next.id) ?? next) as T;
-      if (active) activeRevision = committed.revisionState!.revision;
-      if (requestId)
-        db.run('INSERT INTO node_creation_requests VALUES (?, ?, ?, ?)', [
-          requestId,
-          boardId,
-          fingerprint,
-          JSON.stringify(next),
-        ]);
-      return next;
-    })();
+        // Include pending edits in catalog resolution and durable relation clocks,
+        // without publishing or changing the active board before commit.
+        this.stageLiveBoards(db);
+        const state = loadStateFromDB(db, boardId);
+        if (!state) throw new OperationError(`Board "${boardId}" not found.`, 404);
+        const policies = [this.getPolicy(), state.ax?.policy];
+        if (policies.some((policy) => policy && (policy.scope || Object.keys(policy.agentScopes ?? {}).length)))
+          throw new OperationError('Destination/retry creation is refused while either board has a scope fence.', 403);
+        state.revisionState = {
+          ...state.revisionState,
+          revision: state.revisionState?.revision ?? 0,
+          floor: state.revisionState?.floor ?? 0,
+          tombstones: state.revisionState?.tombstones ?? [],
+        };
+        before = structuredClone(state);
+        const invalidations: Array<[string, string]> = [];
+        let next = build(state, (targetBoardId, nodeId) => invalidations.push([targetBoardId, nodeId]));
+        // Theme is workspace-global; never let an inactive projection overwrite it.
+        state.theme = this._theme;
+        saveStateToDB(db, boardId, state);
+        const invalidate = (targetBoardId: string, targetNodeId: string) => {
+          const revision = invalidateLinksInDB(db, targetBoardId, targetNodeId);
+          if (targetBoardId === this._activeBoardId && revision !== undefined) {
+            activeLinkRevisions.set(targetNodeId, revision);
+            activeRevision = Math.max(activeRevision, revision);
+          }
+        };
+        for (const [targetBoardId, nodeId] of invalidations) invalidate(targetBoardId, nodeId);
+        if ('data' in next) invalidateIncomingLinksInDB(db, boardId, next.id, invalidate);
+        committed = loadStateFromDB(db, boardId)!;
+        next = ([...committed.nodes, ...committed.edges].find((candidate) => candidate.id === next.id) ?? next) as T;
+        if (active) activeRevision = committed.revisionState!.revision;
+        if (this._activeBoardId) activeStorageVersion = boardStorageVersion(db, this._activeBoardId);
+        if (requestId)
+          db.run('INSERT INTO node_creation_requests VALUES (?, ?, ?, ?)', [
+            requestId,
+            boardId,
+            fingerprint,
+            JSON.stringify(next),
+          ]);
+        return next;
+      })
+      .immediate();
     if (committed) {
+      this._storageVersion = activeStorageVersion;
       if (active) {
         const changed = committed.nodes.filter(
           (node) => JSON.stringify(before!.nodes.find((old) => old.id === node.id)) !== JSON.stringify(node),
@@ -1442,16 +1795,48 @@ class CanvasStateManager {
       }
       this._contentRevision = activeRevision;
       if (active || activeLinkRevisions.size) this.notifyChange('nodes');
+      this.reconcileStoredBoards();
     }
     return result;
   }
 
+  /** Called inside a transaction: publish no storage clocks until it commits. */
+  private stageLiveBoards(db: import('bun:sqlite').Database): void {
+    for (const board of this.liveBoards.values()) {
+      if (board !== this.boardState && !board.saveTimer && !board.persistenceError) continue;
+      this.boardExecution.run(board, () => saveStateToDB(db, board.id!, this.persistedState()));
+    }
+  }
+
+  /** A stored multi-board write retains each live owner's runtime and camera. */
+  private reconcileStoredBoards(ids: Iterable<string> = this.liveBoards.keys()): void {
+    if (!this._db) return;
+    for (const id of ids) {
+      const board = this.liveBoards.get(id);
+      if (!board) continue;
+      if (board.storageVersion === boardStorageVersion(this._db, board.id!)) continue;
+      const state = loadStateFromDB(this._db, board.id!)!;
+      this.boardExecution.run(board, () => {
+        if (board.saveTimer) clearTimeout(board.saveTimer);
+        board.saveTimer = null;
+        board.persistenceError = null;
+        this.applyPersistedState(state, false);
+        this.notifyChange('nodes');
+        this.notifyChange('pins');
+        this.notifyChange('ax');
+      });
+    }
+  }
+
   /** Read a board without activating it. This projection is not a write payload. */
   readBoard(
     id: string,
     includeBlobs = true,
   ): { board: CanvasBoard; state: PersistedCanvasState; layout: CanvasLayout } | null {
     if (!this._db) return null;
+    const live = this.liveBoards.get(id);
+    if (id !== this._activeBoardId && live && (live.saveTimer || live.persistenceError))
+      return this.boardExecution.run(live, () => this.readBoard(id, includeBlobs));
     const board = this.listBoards().find((entry) => entry.id === id);
     if (!board) return null;
     if (id === this._activeBoardId) {
@@ -1465,6 +1850,7 @@ class CanvasStateManager {
         board,
         layout,
         state: {
+          storageVersion: this._storageVersion,
           version: 1,
           theme: this._theme,
           tour: layout.tour,
@@ -1479,12 +1865,16 @@ class CanvasStateManager {
         },
       };
     }
-    const state = loadStateFromDB(this._db, id);
+    const state = this.readProjectedBoard(id);
     if (!state) return null;
     this.initializePersistedWikiLinks(state, id);
     const pins = new Set(state.contextPins);
     state.nodes = state.nodes.map((node) => ({
-      ...(includeBlobs ? this.resolveNodeDataBlobs(node) : node),
+      ...(node.type === 'status' && typeof node.data.workItemId === 'string'
+        ? this.normalizeNode(node, state.ax?.workItems ?? [], { boardId: id })
+        : includeBlobs
+          ? this.resolveNodeDataBlobs(node)
+          : node),
       pinned: node.pinned || pins.has(node.id),
     }));
     return {
@@ -1504,9 +1894,10 @@ class CanvasStateManager {
   /** Every board in the workspace, most recently opened first. */
   listBoards(): CanvasBoard[] {
     if (!this._db) return [];
-    return listBoardsFromDB(this._db).map((board) =>
-      board.id === this._activeBoardId ? { ...board, nodeCount: this.nodes.size } : board,
-    );
+    return listBoardsFromDB(this._db).map((board) => {
+      const live = this.liveBoards.get(board.id);
+      return live ? { ...board, nodeCount: live.nodes.size } : board;
+    });
   }
 
   storeAttachment(input: { boardId: string; name: string; mime: string; bytes: Uint8Array }): Attachment | null {
@@ -1549,10 +1940,15 @@ class CanvasStateManager {
       clearTimeout(this._saveTimer);
       this._saveTimer = null;
     }
-    return this._db.transaction(() => {
-      if (!this.saveToDisk()) throw new Error(this._lastPersistenceError?.message ?? 'Failed to save canvas state.');
-      return updateImport(this._db!, id, 'committed', { committedNodeIds: nodeIds });
-    })();
+    let storageVersion = this._storageVersion;
+    const result = this._db
+      .transaction(() => {
+        if (this._activeBoardId) storageVersion = saveStateToDB(this._db!, this._activeBoardId, this.persistedState());
+        return updateImport(this._db!, id, 'committed', { committedNodeIds: nodeIds });
+      })
+      .immediate();
+    this._storageVersion = storageVersion;
+    return result;
   }
 
   getContextBriefCursor(boardId: string, consumer: string): number | null {
@@ -1571,6 +1967,159 @@ class CanvasStateManager {
     return createBoardInDB(this._db, name, folder);
   }
 
+  /** The host supplies runtime ownership, not another copy of board state. */
+  setMoveRuntimeBlockers(read: () => ReadonlyMap<string, string>): void {
+    this.moveRuntimeBlockers = read;
+  }
+
+  moveSelectionToNewBoard(
+    input: BoardMoveInput,
+  ): { preview: BoardMovePreview } | { result: BoardMoveResult; replayed: boolean } {
+    const db = this._db;
+    if (!db) throw new OperationError('Moving cards requires persistent workspace storage.', 409);
+    const name = input.name.trim();
+    if (!name || name.length > 120) throw new OperationError('Board names must be 1–120 characters.');
+    if (!input.requestId.trim() || input.requestId.length > 200)
+      throw new OperationError('A move requires a requestId of 1–200 characters.');
+    const normalized = { ...input, name, nodeIds: [...new Set(input.nodeIds)].sort() };
+    const fingerprint = JSON.stringify({
+      sourceBoardId: input.sourceBoardId,
+      nodeIds: normalized.nodeIds,
+      name,
+      expectedRevision: input.expectedRevision,
+    });
+    let committed: PersistedCanvasState | undefined;
+    const perform = () => {
+      const previous = db
+        .query<{ fingerprint: string; result: string }, [string]>(
+          'SELECT fingerprint, result FROM board_moves WHERE request_id = ?',
+        )
+        .get(input.requestId);
+      if (previous && !input.preview) {
+        if (previous.fingerprint !== fingerprint)
+          throw new OperationError('requestId was already used for a different move.', 409);
+        return { result: JSON.parse(previous.result) as BoardMoveResult, replayed: true };
+      }
+      if (input.sourceBoardId !== this._activeBoardId)
+        throw new OperationError('The source board is no longer open. Preview the move again.', 409);
+      assertBoardStorageVersion(db, input.sourceBoardId, this._storageVersion);
+      const library = new Map<string, MoveBoard>();
+      for (const board of listBoardsFromDB(db)) {
+        const live = this.liveBoards.get(board.id);
+        const state =
+          live && (board.id === input.sourceBoardId || live.saveTimer || live.persistenceError)
+            ? this.boardExecution.run(live, () => this.persistedState(false))
+            : loadStateFromDB(db, board.id)!;
+        state.nodes = state.nodes.map((node) => this.resolveNodeDataBlobs(node));
+        library.set(board.id, { board, state });
+      }
+      const source = library.get(input.sourceBoardId)!;
+      const destinationId = `board-${randomUUID()}`;
+      const portalId = `board-portal-${randomUUID()}`;
+      const at = new Date().toISOString();
+      const plan = prepareBoardMove(
+        normalized,
+        library,
+        destinationId,
+        portalId,
+        listImports(db, input.sourceBoardId),
+        this.moveRuntimeBlockers(),
+        currentActor(),
+        at,
+      );
+      for (const id of plan.preview.affectedBoardIds) {
+        const policy = library.get(id)!.state.ax?.policy;
+        if (policy && (policy.scope || Object.keys(policy.agentScopes ?? {}).length))
+          plan.preview.blockers.push(`${id}: clear the scope fence before relocating board-owned cards/references`);
+      }
+      for (const [id, state] of plan.states) {
+        const original = library.get(id)?.state;
+        if (!original) continue;
+        const locked = humanPresence.lockedNodes(Date.now(), id);
+        for (const node of original.nodes)
+          if (
+            locked.has(node.id) &&
+            JSON.stringify(node) !== JSON.stringify(state.nodes.find((next) => next.id === node.id))
+          )
+            plan.preview.blockers.push(`${node.id}: being edited by ${locked.get(node.id)}`);
+      }
+      if (input.preview) return { preview: plan.preview };
+      if (plan.preview.blockers.length)
+        throw new OperationError('Move refused. Resolve the listed bindings, then preview again.', 409, {
+          blockers: plan.preview.blockers,
+        });
+      db.run(
+        'INSERT INTO boards (id, name, folder, created_at, relation_vocabulary, readme_node_id) VALUES (?, ?, ?, ?, ?, ?)',
+        [
+          destinationId,
+          name,
+          source.board.folder,
+          at,
+          JSON.stringify(source.board.relationVocabulary ?? null),
+          plan.preview.readmeNodeId,
+        ],
+      );
+      for (const [id, state] of plan.states) {
+        state.theme = this._theme;
+        saveStateToDB(db, id, this.externalizePersistedStateBlobs(state));
+        db.run(
+          'INSERT INTO board_move_boundaries VALUES (?, ?) ON CONFLICT(board_id) DO UPDATE SET request_id = excluded.request_id',
+          [id, input.requestId],
+        );
+      }
+      if (plan.preview.readmeNodeId) updateBoardInDB(db, input.sourceBoardId, { readmeNodeId: null });
+      for (const attachment of plan.preview.attachmentIds) {
+        db.run('UPDATE attachments SET board_id = ? WHERE id = ? AND board_id = ?', [
+          destinationId,
+          attachment,
+          input.sourceBoardId,
+        ]);
+        db.run('UPDATE document_imports SET board_id = ? WHERE attachment_id = ? AND board_id = ?', [
+          destinationId,
+          attachment,
+          input.sourceBoardId,
+        ]);
+      }
+      recordCardRelocation(db, input.requestId, input.sourceBoardId, destinationId, plan.preview.nodeIds);
+      const result: BoardMoveResult = {
+        sourceBoardId: input.sourceBoardId,
+        destinationBoardId: destinationId,
+        portalId,
+        nodeIds: plan.preview.nodeIds,
+        affectedBoardIds: [...plan.preview.affectedBoardIds, destinationId],
+      };
+      db.run('INSERT INTO board_moves VALUES (?, ?, ?, ?)', [input.requestId, fingerprint, JSON.stringify(result), at]);
+      committed = loadStateFromDB(db, input.sourceBoardId)!;
+      return { result, replayed: false };
+    };
+    const transaction = db.transaction(perform);
+    const result = input.preview ? transaction() : transaction.immediate();
+    if (committed) {
+      // This is not a board activation: retain the camera, runtime partition and
+      // mounted viewers. Only the committed nodes, relations and pins changed.
+      const retained = new Set(committed.nodes.map((node) => node.id));
+      const removed = [...this.nodes.keys()].filter((id) => !retained.has(id));
+      this.nodes.clear();
+      for (const node of committed.nodes) this.nodes.set(node.id, this.resolveNodeDataBlobs(node));
+      this.edges.clear();
+      for (const edge of committed.edges) this.edges.set(edge.id, edge);
+      this._contextPinnedNodeIds = new Set(committed.contextPins);
+      this._contextPinMeta = new Map(Object.entries(committed.contextPinMeta ?? {}));
+      this._storageVersion = committed.storageVersion!;
+      this._contentRevision = committed.revisionState!.revision;
+      this._revisionFloor = committed.revisionState!.floor;
+      this._deletionTombstones = [];
+      for (const id of removed) this.ax.revalidateAfterNodeRemoval(id);
+      mutationHistory.reset();
+      this._lastPersistenceError = null;
+      this.notifyChange('nodes');
+      this.notifyChange('pins');
+      this.notifyChange('ax');
+      if (result.result) this.reconcileStoredBoards(result.result.affectedBoardIds);
+    }
+    return result;
+  }
+
   updateBoard(
     id: string,
     patch: Pick<Parameters<typeof updateBoardInDB>[2], 'name' | 'folder' | 'mapPosition' | 'relationVocabulary'>,
@@ -1663,6 +2212,9 @@ class CanvasStateManager {
       delete data.axStep;
       delete data.axWorkStatus;
       delete data.workItemId;
+      delete data.workItemBoardId;
+      delete data.liveWorkAvailable;
+      delete data.liveWorkSource;
       delete data.approvalGateId;
       delete data.parentGroup;
       if (typeof node.data.parentGroup === 'string' && ids.has(node.data.parentGroup)) {
@@ -1769,35 +2321,35 @@ class CanvasStateManager {
   /** Deletes a board and its snapshots; deleting the open board returns to Home first. */
   deleteBoard(id: string): boolean {
     if (!this._db) return false;
-    if (id === this._activeBoardId && !this.switchBoard(null)) return false;
+    if (id === this.visibleBoard.id && !this.withVisibleBoard(() => this.switchBoard(null))) return false;
     // Reverse relations must include outgoing links still debounced on the open board.
-    if (this._saveTimer || this._lastPersistenceError) this.flushToDisk();
-    return deleteBoardFromDB(this._db, id, (boardId, nodeId) => this.invalidateRelationTarget(boardId, nodeId));
+    this.flushToDisk();
+    const removed = deleteBoardFromDB(this._db, id, (boardId, nodeId) =>
+      this.invalidateRelationTarget(boardId, nodeId),
+    );
+    if (removed) {
+      const board = this.liveBoards.get(id);
+      if (board) {
+        board.disposed = true;
+        this.disposeBoardRuntime(board);
+      }
+      this.liveBoards.delete(id);
+    }
+    return removed;
   }
 
   /**
-   * Save the open board, then open `id` (or Home for null). The canvas state is
-   * replaced wholesale; callers own the runtime side (undo history, app
-   * sessions, watchers, SSE) — see `openCanvasBoard` in canvas-operations.
+   * Save pending boards, then select the visible owner. Existing partitions
+   * remain live; canvas-operations starts the selected board's runtime/SSE.
    */
   switchBoard(id: string | null): boolean {
     if (!this._db) return false;
-    if (this._saveTimer) {
-      clearTimeout(this._saveTimer);
-      this._saveTimer = null;
-    }
-    if (!this.saveToDisk()) {
-      throw new Error(this._lastPersistenceError?.message ?? 'Failed to save canvas state before switching boards.');
-    }
-    let next = this.emptyPersistedState();
-    if (id) {
-      const state = loadStateFromDB(this._db, id);
-      if (!state) return false;
-      this.initializePersistedWikiLinks(state, id);
-      next = state;
-    }
-    this.applyPersistedState(next);
-    this._activeBoardId = id;
+    if (this.boardExecution.getStore())
+      throw new OperationError('Board-scoped operations cannot change navigation.', 409);
+    if (id && !getBoardFromDB(this._db, id)) return false;
+    this.flushToDisk();
+    this.visibleBoard = id ? this.loadBoardState(id) : this.createBoardState();
+    this.navigationGeneration = ++this.nextGeneration;
     setActiveBoardIdInDB(this._db, id);
     this.notifyChange('nodes');
     this.notifyChange('pins');
@@ -1835,20 +2387,27 @@ class CanvasStateManager {
   private scheduleSave(): void {
     if (!this._db) return;
     if (this._saveTimer) clearTimeout(this._saveTimer);
-    this._saveTimer = setTimeout(() => {
-      this._saveTimer = null;
-      this.saveToDisk();
-    }, SAVE_DEBOUNCE_MS);
+    this._saveTimer = setTimeout(
+      this.bindBoard(() => {
+        this._saveTimer = null;
+        this.saveToDisk();
+      }),
+      SAVE_DEBOUNCE_MS,
+    );
   }
 
   flushToDisk(): void {
     if (!this._db) return;
-    if (this._saveTimer) {
-      clearTimeout(this._saveTimer);
-      this._saveTimer = null;
-    }
-    if (!this.saveToDisk()) {
-      throw new Error(this._lastPersistenceError?.message ?? 'Failed to save canvas state.');
+    const current = this.boardState;
+    for (const board of new Set([this.visibleBoard, ...this.liveBoards.values()])) {
+      if (board !== current && !board.saveTimer && !board.persistenceError) continue;
+      this.boardExecution.run(board, () => {
+        if (this._saveTimer) {
+          clearTimeout(this._saveTimer);
+          this._saveTimer = null;
+        }
+        if (!this.saveToDisk()) throw new Error(this._lastPersistenceError?.message ?? 'Failed to save canvas state.');
+      });
     }
     if (this._db) {
       try {
@@ -1860,8 +2419,9 @@ class CanvasStateManager {
     }
   }
 
-  private persistedState(): PersistedCanvasState {
-    return this.externalizePersistedStateBlobs({
+  private persistedState(externalize = true): PersistedCanvasState {
+    const state: PersistedCanvasState = {
+      storageVersion: this._storageVersion,
       version: 1,
       theme: this._theme,
       tour: this._tour,
@@ -1873,7 +2433,8 @@ class CanvasStateManager {
       contextPinMeta: this.pinMetaRecord(),
       ax: this.getAxState(),
       revisionState: this.revisionState(),
-    });
+    };
+    return externalize ? this.externalizePersistedStateBlobs(state) : state;
   }
 
   /** Write current state to SQLite immediately. */
@@ -1887,7 +2448,7 @@ class CanvasStateManager {
       }
       const boardId = this.ensureActiveBoard();
       if (!boardId) return false;
-      saveStateToDB(this._db, boardId, this.persistedState());
+      this._storageVersion = saveStateToDB(this._db, boardId, this.persistedState());
       this._lastPersistenceError = null;
       return true;
     } catch (error) {
@@ -1903,18 +2464,20 @@ class CanvasStateManager {
     }
   }
 
-  private _lastPersistenceError: { message: string; at: string } | null = null;
-
   /** Health view of state persistence: ok until a save fails, ok again after the next success. */
   get persistenceHealth(): { ok: boolean; lastError: { message: string; at: string } | null } {
-    return { ok: this._lastPersistenceError === null, lastError: this._lastPersistenceError };
+    const lastError =
+      [this.visibleBoard, ...this.liveBoards.values()].find((board) => board.persistenceError)?.persistenceError ??
+      null;
+    return { ok: lastError === null, lastError };
   }
 
   /** Close the SQLite database cleanly. Call on server shutdown. */
   close(): void {
     // A failed debounce has no timer left, but its edits still need saving.
     // Leave the database and memory intact if the retry fails.
-    if (this._saveTimer || this._lastPersistenceError) this.flushToDisk();
+    if ([this.visibleBoard, ...this.liveBoards.values()].some((board) => board.saveTimer || board.persistenceError))
+      this.flushToDisk();
     if (this._db) {
       try {
         finalizeCanvasDbForClose(this._db);
@@ -1928,8 +2491,14 @@ class CanvasStateManager {
       }
       this._db = null;
     }
-    this._activeBoardId = null;
-    this._boardGeneration += 1;
+    for (const board of new Set([this.visibleBoard, ...this.liveBoards.values()])) {
+      board.disposed = true;
+      this.disposeBoardRuntime(board);
+    }
+    this.liveBoards.clear();
+    this.hostState.capability = null;
+    this.visibleBoard = this.createBoardState();
+    this.navigationGeneration = ++this.nextGeneration;
   }
 
   // ── Snapshots ───────────────────────────────────────────────
@@ -1939,12 +2508,17 @@ class CanvasStateManager {
     return join(this._workspaceRoot, PMX_CANVAS_DIR, SNAPSHOTS_SUBDIR);
   }
 
-  private applyPersistedState(state: PersistedCanvasState): void {
+  private applyPersistedState(state: PersistedCanvasState, replaced = true): void {
     // Validate the complete replacement before discarding any live board state.
+    // Keep the cached task fields as the revision comparison baseline. Display
+    // reads project fresh fields; explicit reconciliation stamps and saves them.
     const nodes = (Array.isArray(state.nodes) ? state.nodes : [])
       .filter((node) => node?.id)
-      .map((node) => structuredClone(this.normalizeNode(node)));
-    this._boardGeneration += 1;
+      .map((node) => structuredClone(this.normalizeNode(node, undefined, { projectWork: false })));
+    if (replaced) {
+      this._boardGeneration = ++this.nextGeneration;
+      if (this.boardState === this.visibleBoard) this.navigationGeneration = ++this.nextGeneration;
+    }
     this._tour = state.tour ? structuredClone(state.tour) : undefined;
     this.nodes.clear();
     this.edges.clear();
@@ -1952,6 +2526,7 @@ class CanvasStateManager {
     this._contextPinnedNodeIds.clear();
     this._contextPinMeta.clear();
     this.ax.resetCanvasBound();
+    this._storageVersion = state.storageVersion ?? 0;
     this._contentRevision = state.revisionState?.revision ?? 0;
     this._revisionFloor = state.revisionState?.floor ?? 0;
     this._deletionTombstones = structuredClone(state.revisionState?.tombstones ?? []);
@@ -2078,6 +2653,7 @@ class CanvasStateManager {
 
     try {
       const payload = this.externalizePersistedStateBlobs({
+        storageVersion: this._storageVersion,
         version: 1,
         theme: this._theme,
         viewport: this._viewport,
@@ -2173,6 +2749,7 @@ class CanvasStateManager {
   restoreSnapshot(idOrName: string): boolean {
     const resolved = this.readResolvedSnapshot(idOrName);
     if (!resolved || resolved.state.version !== 1) return false;
+    this.assertSnapshotRestorable(idOrName);
 
     const previousState: PersistedCanvasState = this.externalizePersistedStateBlobs({
       version: 1,
@@ -2213,7 +2790,11 @@ class CanvasStateManager {
 
     try {
       const revisionBeforeRestore = this._contentRevision;
-      this.applyPersistedState({ ...nextState, revisionState: this.revisionState() });
+      this.applyPersistedState({
+        ...nextState,
+        storageVersion: this._storageVersion,
+        revisionState: this.revisionState(),
+      });
       this.restampRestoredContent(previousState.nodes, previousState.edges, revisionBeforeRestore);
       this.scheduleSave();
       this.notifyChange('nodes');
@@ -2226,7 +2807,11 @@ class CanvasStateManager {
           const before = Array.from(this.nodes.values(), (node) => structuredClone(node));
           const edgesBefore = this.getEdges();
           const revisionBeforeReplay = this._contentRevision;
-          this.applyPersistedState({ ...nextState, revisionState: this.revisionState() });
+          this.applyPersistedState({
+            ...nextState,
+            storageVersion: this._storageVersion,
+            revisionState: this.revisionState(),
+          });
           this.restampRestoredContent(before, edgesBefore, revisionBeforeReplay);
           this.scheduleSave();
           this.notifyChange('nodes');
@@ -2237,7 +2822,11 @@ class CanvasStateManager {
           const before = Array.from(this.nodes.values(), (node) => structuredClone(node));
           const edgesBefore = this.getEdges();
           const revisionBeforeReplay = this._contentRevision;
-          this.applyPersistedState({ ...previousState, revisionState: this.revisionState() });
+          this.applyPersistedState({
+            ...previousState,
+            storageVersion: this._storageVersion,
+            revisionState: this.revisionState(),
+          });
           this.restampRestoredContent(before, edgesBefore, revisionBeforeReplay);
           this.scheduleSave();
           this.notifyChange('nodes');
@@ -2256,6 +2845,19 @@ class CanvasStateManager {
     }
   }
 
+  /** Old snapshots stay readable, but neither whole-board nor one-card restore crosses a move. */
+  assertSnapshotRestorable(idOrName: string): void {
+    if (!this._db || !this._activeBoardId) return;
+    const resolved = this.readResolvedSnapshot(idOrName);
+    if (!resolved) throw new OperationError('Snapshot not found.', 404);
+    assertBoardStorageVersion(this._db, this._activeBoardId, this._storageVersion);
+    if ((resolved.state.moveBoundary ?? null) !== boardMoveBoundary(this._db, this._activeBoardId))
+      throw new OperationError(
+        'This snapshot predates a move. Inspect it and reapply desired content to the current card, or restore a whole-library backup.',
+        409,
+      );
+  }
+
   /** Read a snapshot's data without restoring it (for diff). Resolves by ID or name. */
   getSnapshotData(idOrName: string): {
     name: string;
@@ -2452,18 +3054,22 @@ class CanvasStateManager {
           : (loadStateFromDB(this._db!, board.id)?.nodes ?? [])
       ).map((node) => ({ id: node.id, title: typeof node.data.title === 'string' ? node.data.title : node.id })),
     }));
-    this._db.transaction(() => {
-      for (const node of legacy) {
-        const resolved = this.resolveNodeDataBlobs(node);
-        const content = typeof resolved.data.content === 'string' ? resolved.data.content : '';
-        node.data = { ...node.data, wikiLinks: resolveWikiLinks(content, [], catalog) };
-        this._db!.run('UPDATE nodes SET data = ? WHERE board_id = ? AND id = ?', [
-          JSON.stringify(node.data),
-          boardId,
-          node.id,
-        ]);
-      }
-    })();
+    state.storageVersion = this._db
+      .transaction(() => {
+        assertBoardStorageVersion(this._db!, boardId, state.storageVersion ?? 0);
+        for (const node of legacy) {
+          const resolved = this.resolveNodeDataBlobs(node);
+          const content = typeof resolved.data.content === 'string' ? resolved.data.content : '';
+          node.data = { ...node.data, wikiLinks: resolveWikiLinks(content, [], catalog) };
+          this._db!.run('UPDATE nodes SET data = ? WHERE board_id = ? AND id = ?', [
+            JSON.stringify(node.data),
+            boardId,
+            node.id,
+          ]);
+        }
+        return boardStorageVersion(this._db!, boardId);
+      })
+      .immediate();
   }
 
   private bindWikiLinks(
@@ -2587,7 +3193,7 @@ class CanvasStateManager {
       description: `Added ${cloned.type} node "${(cloned.data.title as string) ?? cloned.id}"`,
       forward: this.suppressed(() => {
         this.nodes.set(cloned.id, {
-          ...structuredClone(cloned),
+          ...this.normalizeNode(structuredClone(cloned)),
           contentRevision: this.nextContentRevision(),
           contentChangedAt: new Date().toISOString(),
           lastEditedBy: currentActor(),
@@ -2638,6 +3244,14 @@ class CanvasStateManager {
   updateNode(id: string, patch: Partial<CanvasNodeState>, savedWikiLinks?: WikiLink[] | null): void {
     const existing = this.nodes.get(id);
     if (!existing) return;
+    if (
+      existing.type === 'status' &&
+      typeof existing.data.workItemId === 'string' &&
+      ((patch.type !== undefined && patch.type !== existing.type) ||
+        (patch.data && patch.data.workItemId !== existing.data.workItemId))
+    ) {
+      throw new OperationError('Live work card references are immutable.');
+    }
     if (patch.data) {
       if (patch.data.contentOrigin !== existing.data.contentOrigin) {
         throw new OperationError('Content origin is immutable after creation.');
@@ -2913,6 +3527,10 @@ class CanvasStateManager {
   }
 
   private invalidateRelationTarget(boardId: string, nodeId: string): void {
+    if (boardId !== this._activeBoardId && this.liveBoards.has(boardId)) {
+      this.withBoard(boardId, () => this.invalidateRelationTarget(boardId, nodeId));
+      return;
+    }
     if (boardId === this._activeBoardId) {
       const node = this.nodes.get(nodeId);
       if (node) {
@@ -3220,6 +3838,9 @@ class CanvasStateManager {
       if (update.collapsed !== undefined && update.collapsed !== existing.collapsed) {
         nextPatch.collapsed = update.collapsed;
       }
+      if (update.zIndex !== undefined && update.zIndex !== existing.zIndex) {
+        nextPatch.zIndex = update.zIndex;
+      }
       if (Object.keys(nextPatch).length === 0) {
         skipped++;
         continue;
@@ -3352,6 +3973,7 @@ class CanvasStateManager {
    */
   applyPersistedAxState(ax: unknown): void {
     this.ax.applyPersistedAx(ax);
+    this.refreshLiveWorkCards();
   }
 
   getAxFocus(): PmxAxFocusState {
@@ -3371,6 +3993,14 @@ class CanvasStateManager {
     return this.ax.getWorkItems();
   }
 
+  getWorkItemsOnBoard(boardId: string): PmxAxWorkItem[] {
+    if (boardId === this._activeBoardId) return this.getWorkItems();
+    const live = this.liveBoards.get(boardId);
+    if (live && (live.saveTimer || live.persistenceError))
+      return this.boardExecution.run(live, () => live.ax.getWorkItems());
+    return this._db ? (loadStateFromDB(this._db, boardId)?.ax?.workItems ?? []) : [];
+  }
+
   addWorkItem(
     input: {
       title: string;
@@ -3416,6 +4046,7 @@ class CanvasStateManager {
     for (const nodeId of nodeIds) {
       const node = this.nodes.get(nodeId);
       if (!node) continue;
+      if (node.type === 'status' && typeof node.data.workItemId === 'string') continue;
       // No-op guard: a title-/agentId-only work-item patch must not push
       // history entries and SSE churn for chips that aren't changing.
       if (node.data.axWorkStatus === status) continue;
@@ -3657,11 +4288,15 @@ class CanvasStateManager {
     return this.ax.getAxSteering(q);
   }
 
-  getPendingSteering(options: { consumer?: string; limit?: number } = {}): PmxAxSteeringMessage[] {
+  getPendingSteering(
+    options: { consumer?: string; limit?: number; addressedOnly?: boolean; offset?: number } = {},
+  ): PmxAxSteeringMessage[] {
     return this.ax.getPendingSteering(options);
   }
 
-  getPendingSteeringForContext(options: { consumer?: string; limit?: number } = {}): PmxAxSteeringMessage[] {
+  getPendingSteeringForContext(
+    options: { consumer?: string; limit?: number; addressedOnly?: boolean; offset?: number } = {},
+  ): PmxAxSteeringMessage[] {
     return this.ax.getPendingSteeringForContext(options);
   }
 
@@ -3685,6 +4320,8 @@ class CanvasStateManager {
       this._contextReadListener?.(boardId);
       return read;
     } catch (error) {
+      // Explicit receipts need a distinguishable outcome, not best-effort diagnostics.
+      if (input.deliveryId) throw error;
       logCanvasStateWarning('record context read failed', error);
       return null;
     }
@@ -3977,4 +4614,5 @@ class CanvasStateManager {
 // Module-level singleton — safe because Bun is single-threaded and this
 // module is imported once per process. Agent tools and the HTTP server share
 // the same instance; no locking needed.
+export const boardCatalogEpoch = randomUUID();
 export const canvasState = new CanvasStateManager();