pmx-canvas 0.7.3 → 0.8.2

package/src/server/board-export.ts

@@ -208,6 +208,8 @@ async function collect(
   if (!read) return null;
   const { board, state } = read;
   const theme = canvasThemeScheme(state.theme ?? canvasState.theme);
+  // Exports collapse to a scheme; surface documents take the theme that draws it.
+  const surfaceTheme = theme === 'light' ? 'daylight' : 'harbor';
   const remoteImages = new Set<string>();
   const links = new Set<string>();
   const frameNetworkDestinations = new Set<string>();
@@ -383,7 +385,8 @@ async function collect(
         const html = text(data.html) || text(data.content);
         collectFrameNetworkDestinations(html, frameNetworkDestinations);
         manifest.frames += 1;
-        if (withFrames) card.frame = buildHtmlSurfaceDocument(html, { theme, title, inlineThemeCss: themeCss });
+        if (withFrames)
+          card.frame = buildHtmlSurfaceDocument(html, { theme: surfaceTheme, title, inlineThemeCss: themeCss });
         break;
       }
       case 'mermaid':
@@ -395,7 +398,7 @@ async function collect(
               '<script src="/canvas/mermaid-entry.js"></script>',
               `<script src="${MERMAID_SRC}"></script>`,
             ),
-            { theme, title, inlineThemeCss: themeCss },
+            { theme: surfaceTheme, title, inlineThemeCss: themeCss },
           );
         }
         break;

package/src/server/canvas-db.ts

@@ -6,6 +6,7 @@
  */
 
 import { Database } from 'bun:sqlite';
+import type { ActorAttribution } from './attribution.js';
 import { CONTEXT_READS_SCHEMA_SQL } from './context-reads.js';
 import { MIGRATED_SNAPSHOT_CATEGORY, normalizeBoardCategory } from '../shared/boards.js';
 import { tourSchema, type Tour } from '../shared/tour.js';
@@ -48,7 +49,7 @@ const SCHEMA_VERSION = 2;
 
 export type CanvasTheme = CanvasThemeName;
 
-export function normalizeCanvasTheme(value: unknown, fallback: CanvasTheme = 'dark'): CanvasTheme {
+export function normalizeCanvasTheme(value: unknown, fallback: CanvasTheme = 'harbor'): CanvasTheme {
   return normalizeCanvasThemeName(value, fallback);
 }
 
@@ -122,6 +123,7 @@ const SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS context_pins (
     board_id TEXT NOT NULL,
     node_id TEXT NOT NULL,
+    meta TEXT,
     PRIMARY KEY (board_id, node_id)
   );
 
@@ -185,6 +187,7 @@ const SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS snapshot_pins (
     snapshot_id TEXT NOT NULL,
     node_id TEXT NOT NULL,
+    meta TEXT,
     PRIMARY KEY (snapshot_id, node_id)
   );
 
@@ -335,10 +338,29 @@ export interface PersistedCanvasState {
   edges: CanvasEdge[];
   annotations?: CanvasAnnotation[];
   contextPins: string[];
+  /** Who pinned each context pin, when and why; pins without an entry have an unknown pinner. */
+  contextPinMeta?: Record<string, ContextPinMeta>;
   ax?: PmxAxState;
   revisionState?: PersistedRevisionState;
 }
 
+export interface ContextPinMeta {
+  pinnedBy: ActorAttribution;
+  pinnedAt: string;
+  reason?: string;
+}
+
+function pinMetaJson(state: PersistedCanvasState, nodeId: string): string | null {
+  const meta = state.contextPinMeta?.[nodeId];
+  return meta ? JSON.stringify(meta) : null;
+}
+
+function pinMetaFromRows(rows: Array<{ node_id: string; meta: string | null }>): Record<string, ContextPinMeta> {
+  const meta: Record<string, ContextPinMeta> = {};
+  for (const row of rows) if (row.meta) meta[row.node_id] = JSON.parse(row.meta) as ContextPinMeta;
+  return meta;
+}
+
 export interface PersistedRevisionState {
   revision: number;
   floor: number;
@@ -400,6 +422,9 @@ export function openCanvasDb(dbPath: string, options: OpenCanvasDbOptions = {}):
   ensureColumn(db, 'ax_steering', 'agent_id', 'agent_id TEXT');
   ensureColumn(db, 'ax_steering', 'target', 'target TEXT');
   ensureColumn(db, 'context_reads', 'board_id', 'board_id TEXT');
+  ensureColumn(db, 'context_reads', 'read_nodes', "read_nodes TEXT NOT NULL DEFAULT '{}'");
+  ensureColumn(db, 'context_pins', 'meta', 'meta TEXT');
+  ensureColumn(db, 'snapshot_pins', 'meta', 'meta TEXT');
   ensureColumn(db, 'boards', 'category', 'category TEXT');
   ensureColumn(db, 'boards', 'readme_node_id', 'readme_node_id TEXT');
   ensureColumn(db, 'nodes', 'attribution', "attribution TEXT NOT NULL DEFAULT '{}' ");
@@ -470,6 +495,7 @@ function migrateToBoards(db: Database, dbPath: string, boardName: string): void
       if (existing.has(table)) db.exec(`ALTER TABLE ${table} RENAME TO ${table}_v1`);
     }
     if (existing.has('snapshots')) ensureColumn(db, 'snapshots', 'board_id', 'board_id TEXT');
+    if (existing.has('snapshot_pins')) ensureColumn(db, 'snapshot_pins', 'meta', 'meta TEXT');
     db.exec(SCHEMA_SQL);
 
     if (hasBoard) {
@@ -552,10 +578,10 @@ function snapshotsToBoards(db: Database): void {
       `INSERT INTO annotations (board_id, ${annotationColumns}) SELECT ?, ${annotationColumns} FROM snapshot_annotations WHERE snapshot_id = ?`,
       [boardId, snapshot.id],
     );
-    db.run('INSERT INTO context_pins (board_id, node_id) SELECT ?, node_id FROM snapshot_pins WHERE snapshot_id = ?', [
-      boardId,
-      snapshot.id,
-    ]);
+    db.run(
+      'INSERT INTO context_pins (board_id, node_id, meta) SELECT ?, node_id, meta FROM snapshot_pins WHERE snapshot_id = ?',
+      [boardId, snapshot.id],
+    );
     const ax = meta.get('ax_state');
     if (ax) db.run("INSERT INTO ax_state (board_id, key, value) VALUES (?, 'state', ?)", [boardId, ax]);
     deleteSnapshotFromDB(db, snapshot.id);
@@ -775,10 +801,12 @@ export function saveStateToDB(db: Database, boardId: string, state: PersistedCan
     }
     deleteMissingRows(db, 'annotations', 'id', boardId, new Set(annotations.map((annotation) => annotation.id)));
 
-    // Save context pins (node_id is the whole row — nothing to update)
-    const insertPin = db.prepare('INSERT OR IGNORE INTO context_pins (board_id, node_id) VALUES (?, ?)');
+    // Save context pins with who pinned them
+    const insertPin = db.prepare(
+      'INSERT INTO context_pins (board_id, node_id, meta) VALUES (?, ?, ?) ON CONFLICT(board_id, node_id) DO UPDATE SET meta = excluded.meta WHERE context_pins.meta IS NOT excluded.meta',
+    );
     for (const pinId of state.contextPins) {
-      insertPin.run(boardId, pinId);
+      insertPin.run(boardId, pinId, pinMetaJson(state, pinId));
     }
     deleteMissingRows(db, 'context_pins', 'node_id', boardId, new Set(state.contextPins));
 
@@ -905,9 +933,11 @@ export function loadStateFromDB(db: Database, boardId?: string): PersistedCanvas
   // Load context pins
   interface PinRow {
     node_id: string;
+    meta: string | null;
   }
-  const pinRows = db.query<PinRow, [string]>('SELECT node_id FROM context_pins WHERE board_id = ?').all(id);
+  const pinRows = db.query<PinRow, [string]>('SELECT node_id, meta FROM context_pins WHERE board_id = ?').all(id);
   const contextPins = pinRows.map((row) => row.node_id);
+  const contextPinMeta = pinMetaFromRows(pinRows);
 
   const axRow = db
     .query<{ value: string }, [string, string]>('SELECT value FROM ax_state WHERE board_id = ? AND key = ?')
@@ -925,6 +955,7 @@ export function loadStateFromDB(db: Database, boardId?: string): PersistedCanvas
     edges,
     annotations,
     contextPins,
+    contextPinMeta,
     ax: parsePersistedAxState(axRow?.value),
     revisionState: revisionRaw ? (JSON.parse(revisionRaw) as PersistedRevisionState) : undefined,
   };
@@ -1191,9 +1222,9 @@ export function saveSnapshotToDB(
     }
 
     // Insert snapshot pins
-    const insertPin = db.prepare('INSERT INTO snapshot_pins (snapshot_id, node_id) VALUES (?, ?)');
+    const insertPin = db.prepare('INSERT INTO snapshot_pins (snapshot_id, node_id, meta) VALUES (?, ?, ?)');
     for (const pinId of state.contextPins) {
-      insertPin.run(snapshot.id, pinId);
+      insertPin.run(snapshot.id, pinId, pinMetaJson(state, pinId));
     }
     db.run('INSERT INTO snapshot_meta (snapshot_id, key, value) VALUES (?, ?, ?)', [
       snapshot.id,
@@ -1348,11 +1379,13 @@ export function loadSnapshotFromDB(
   // Load snapshot pins
   interface PinRow {
     node_id: string;
+    meta: string | null;
   }
   const pinRows = db
-    .query<PinRow, [string]>('SELECT node_id FROM snapshot_pins WHERE snapshot_id = ?')
+    .query<PinRow, [string]>('SELECT node_id, meta FROM snapshot_pins WHERE snapshot_id = ?')
     .all(snapshotRow.id);
   const contextPins = pinRows.map((row) => row.node_id);
+  const contextPinMeta = pinMetaFromRows(pinRows);
 
   return {
     snapshot,
@@ -1364,6 +1397,7 @@ export function loadSnapshotFromDB(
       edges,
       annotations,
       contextPins,
+      contextPinMeta,
       ax: parsePersistedAxState(metaMap.get('ax_state')),
       revisionState: metaMap.has('revision_state')
         ? (JSON.parse(metaMap.get('revision_state')!) as PersistedRevisionState)

package/src/server/canvas-geometry.ts

@@ -0,0 +1,64 @@
+import type { CanvasNodeState, CanvasNodeUpdate } from './canvas-state.js';
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function finite(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+/** Flat fields take precedence over nested aliases; absent axes remain absent. */
+export function resolveCreateGeometry(body: Record<string, unknown>) {
+  const position = record(body.position);
+  const size = record(body.size);
+  return {
+    x: finite(body.x) ?? finite(position.x),
+    y: finite(body.y) ?? finite(position.y),
+    width: finite(body.width) ?? finite(size.width),
+    height: finite(body.height) ?? finite(size.height),
+  };
+}
+
+/** Guards and PATCH execution must resolve aliases and single-axis moves identically. */
+export function resolvePatchGeometry(body: Record<string, unknown>, existing: CanvasNodeState) {
+  const { x, y, width, height } = resolveCreateGeometry(body);
+  return {
+    ...(x !== undefined || y !== undefined
+      ? { position: { x: x ?? existing.position.x, y: y ?? existing.position.y } }
+      : {}),
+    ...(width !== undefined || height !== undefined
+      ? { size: { width: width ?? existing.size.width, height: height ?? existing.size.height } }
+      : {}),
+  };
+}
+
+export function validateCanvasNodePatch(patch: { position?: unknown; size?: unknown }): string | null {
+  if (patch.position !== undefined) {
+    const position = record(patch.position);
+    if (finite(position.x) === undefined || finite(position.y) === undefined) {
+      return 'Position must contain finite x and y values.';
+    }
+  }
+  if (patch.size !== undefined) {
+    const size = record(patch.size);
+    const width = finite(size.width);
+    const height = finite(size.height);
+    if (width === undefined || height === undefined) return 'Size must contain finite width and height values.';
+    if (width <= 0 || height <= 0) return 'Size width and height must be greater than zero.';
+  }
+  return null;
+}
+
+/** Invalid patches cannot count as explicit child-position overrides. */
+export function validCanvasNodeUpdates(input: unknown): CanvasNodeUpdate[] {
+  if (!Array.isArray(input)) return [];
+  return input.filter((value: unknown): value is CanvasNodeUpdate => {
+    const update = record(value);
+    return (
+      typeof update.id === 'string' &&
+      (update.collapsed === undefined || typeof update.collapsed === 'boolean') &&
+      validateCanvasNodePatch(update) === null
+    );
+  });
+}

package/src/server/canvas-operations.ts

@@ -23,6 +23,7 @@ import {
 import { mutationHistory } from './mutation-history.js';
 import { intentRegistry } from './intent-registry.js';
 import { clampCreateNodeSize } from './canvas-validation.js';
+import { validCanvasNodeUpdates } from './canvas-geometry.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
@@ -393,7 +394,7 @@ export function buildJsonRenderNodeUpdate(
 ): { data: Record<string, unknown>; spec: JsonRenderSpec } {
   if (node.type !== 'json-render') throw new Error(`Node "${node.id}" is not a json-render node.`);
   const spec = normalizeAndValidateJsonRenderSpec(input.spec);
-  const title = input.title?.trim() || inferJsonRenderNodeTitle(spec);
+  const title = input.title?.trim() || pickString(node.data, 'title') || inferJsonRenderNodeTitle(spec);
   // Bump specVersion so the viewer URL changes: the iframe src is keyed on
   // nodeId + ?v=specVersion, and the viewer only reads the spec at document
   // load. Without the bump the src is byte-identical after a content update,
@@ -730,26 +731,6 @@ export async function syncCanvasRuntimeBackends(
   return { rehydrated, failed };
 }
 
-export function validateCanvasNodePatch(patch: {
-  position?: { x: number; y: number };
-  size?: { width: number; height: number };
-}): string | null {
-  if (patch.position) {
-    if (!Number.isFinite(patch.position.x) || !Number.isFinite(patch.position.y)) {
-      return 'Position must contain finite x and y values.';
-    }
-  }
-  if (patch.size) {
-    if (!Number.isFinite(patch.size.width) || !Number.isFinite(patch.size.height)) {
-      return 'Size must contain finite width and height values.';
-    }
-    if (patch.size.width <= 0 || patch.size.height <= 0) {
-      return 'Size width and height must be greater than zero.';
-    }
-  }
-  return null;
-}
-
 let codeGraphTimer: ReturnType<typeof setTimeout> | null = null;
 
 function shouldTreatFileContentAsPath(input: CanvasAddNodeInput): boolean {
@@ -1406,22 +1387,23 @@ export function arrangeCanvasNodes(layout: CanvasArrangeMode): { arranged: numbe
 }
 
 export function applyCanvasNodeUpdates(updates: CanvasNodeUpdate[]): { applied: number; skipped: number } {
-  const safe = updates.filter((update) => validateCanvasNodePatch(update) === null);
-  return canvasState.applyUpdates(safe);
+  return canvasState.applyUpdates(validCanvasNodeUpdates(updates));
 }
 
 export function setCanvasContextPins(
   nodeIds: string[],
   mode: CanvasPinMode = 'set',
+  reason?: string,
 ): { count: number; nodeIds: string[] } {
   const normalizePins = (ids: string[]): string[] =>
     ids.filter((id, index) => ids.indexOf(id) === index).slice(0, MAX_CONTEXT_PINS);
   const normalizedNodeIds = normalizePins(nodeIds);
+  const options = reason ? { reason } : {};
   if (mode === 'set') {
-    canvasState.setContextPins(normalizedNodeIds);
+    canvasState.setContextPins(normalizedNodeIds, options);
   } else if (mode === 'add') {
     const current = Array.from(canvasState.contextPinnedNodeIds);
-    canvasState.setContextPins(normalizePins([...current, ...normalizedNodeIds]));
+    canvasState.setContextPins(normalizePins([...current, ...normalizedNodeIds]), options);
   } else {
     const current = Array.from(canvasState.contextPinnedNodeIds);
     canvasState.setContextPins(current.filter((id) => !normalizedNodeIds.includes(id)));

package/src/server/canvas-state.ts

@@ -55,6 +55,7 @@ import {
   setActiveBoardIdInDB,
   type CanvasBoard,
   finalizeCanvasDbForClose,
+  type ContextPinMeta,
   type PersistedCanvasState,
   type CanvasTheme,
   type AxTimelineQuery,
@@ -115,9 +116,12 @@ import { currentActor, unknownActor, type ActorAttribution } from './attribution
 import {
   appendContextReadToDB,
   loadContextReadsFromDB,
+  loadNodeReadStatusFromDB,
+  loadReadNodeIdsSince,
   type ContextRead,
   type ContextReadConsumerSummary,
   type ContextReadInput,
+  type NodeReadStatus,
 } from './context-reads.js';
 
 function logCanvasStateWarning(action: string, error: unknown, details?: Record<string, unknown>): void {
@@ -411,8 +415,10 @@ class CanvasStateManager {
   private annotations = new Map<string, CanvasAnnotation>();
   private _viewport: ViewportState = { x: 0, y: 0, scale: 1 };
   private _tour: Tour | undefined;
-  private _theme: CanvasTheme = 'dark';
+  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;
@@ -450,6 +456,8 @@ class CanvasStateManager {
 
   // ── Work-item change listener (single slot, for live workboard refresh) ──
   private _workItemsChangedListener: (() => void) | null = null;
+  /** Single slot (architecture rule 8): server.ts tells the workbench a read landed. Never MCP. */
+  private _contextReadListener: ((boardId: string | null) => void) | null = null;
 
   /**
    * Register THE work-item change listener (single slot, last-write-wins).
@@ -457,6 +465,10 @@ class CanvasStateManager {
    * status mirror), so live views like the workboard can rebuild from the
    * fresh work-item list.
    */
+  setContextReadListener(listener: ((boardId: string | null) => void) | null): void {
+    this._contextReadListener = listener;
+  }
+
   setWorkItemsChangedListener(listener: (() => void) | null): void {
     this._workItemsChangedListener = listener;
   }
@@ -687,8 +699,9 @@ class CanvasStateManager {
     }
   }
 
-  private recomputeParentGroupBounds(groupId: string | undefined): void {
-    if (!groupId) return;
+  private recomputeParentGroupBounds(groupId: string | undefined, visited = new Set<string>()): void {
+    if (!groupId || visited.has(groupId)) return;
+    visited.add(groupId);
     const snapshot = this.getGroupSnapshot(groupId);
     if (!snapshot) return;
     if (snapshot.group.data.frameMode === 'manual') return;
@@ -701,6 +714,10 @@ class CanvasStateManager {
       position: { x: bounds.x, y: bounds.y },
       size: { width: bounds.width, height: bounds.height },
     });
+    // Only the affected ancestor chain may re-fit. Never repair unrelated
+    // automatic frames as a side effect of an otherwise scoped child update.
+    const parentId = snapshot.group.data.parentGroup;
+    if (typeof parentId === 'string') this.recomputeParentGroupBounds(parentId, visited);
   }
 
   private compactGroupChildren(groupId: string, layout: 'grid' | 'column' | 'flow' = 'grid'): void {
@@ -1121,6 +1138,7 @@ class CanvasStateManager {
           edges: layout.edges,
           annotations: layout.annotations,
           contextPins: Array.from(this._contextPinnedNodeIds),
+          contextPinMeta: this.pinMetaRecord(),
           revisionState: this.revisionState(),
         },
       };
@@ -1478,6 +1496,7 @@ class CanvasStateManager {
         edges: Array.from(this.edges.values()),
         annotations: Array.from(this.annotations.values()),
         contextPins: Array.from(this._contextPinnedNodeIds),
+        contextPinMeta: this.pinMetaRecord(),
         ax: this.getAxState(),
         revisionState: this.revisionState(),
       });
@@ -1540,6 +1559,7 @@ class CanvasStateManager {
     this.edges.clear();
     this.annotations.clear();
     this._contextPinnedNodeIds.clear();
+    this._contextPinMeta.clear();
     this.ax.resetCanvasBound();
     this._contentRevision = state.revisionState?.revision ?? 0;
     this._revisionFloor = state.revisionState?.floor ?? 0;
@@ -1571,7 +1591,10 @@ class CanvasStateManager {
     }
     if (Array.isArray(state.contextPins)) {
       for (const pinId of state.contextPins) {
-        if (this.nodes.has(pinId)) this._contextPinnedNodeIds.add(pinId);
+        if (!this.nodes.has(pinId)) continue;
+        this._contextPinnedNodeIds.add(pinId);
+        const meta = state.contextPinMeta?.[pinId];
+        if (meta) this._contextPinMeta.set(pinId, structuredClone(meta));
       }
     }
     this.ax.applyPersistedAx(state.ax);
@@ -1677,6 +1700,7 @@ class CanvasStateManager {
         edges: Array.from(this.edges.values()),
         annotations: Array.from(this.annotations.values()),
         contextPins: Array.from(this._contextPinnedNodeIds),
+        contextPinMeta: this.pinMetaRecord(),
         ax: this.getAxState(),
         revisionState: this.revisionState(),
       });
@@ -1774,6 +1798,7 @@ class CanvasStateManager {
       edges: Array.from(this.edges.values(), (edge) => structuredClone(edge)),
       annotations: Array.from(this.annotations.values(), (annotation) => structuredClone(annotation)),
       contextPins: Array.from(this._contextPinnedNodeIds),
+      contextPinMeta: this.pinMetaRecord(),
       ax: this.getAxState(),
       revisionState: this.revisionState(),
     });
@@ -1788,6 +1813,7 @@ class CanvasStateManager {
         ? resolved.state.annotations.map((annotation) => structuredClone(annotation))
         : [],
       contextPins: Array.isArray(resolved.state.contextPins) ? [...resolved.state.contextPins] : [],
+      contextPinMeta: resolved.state.contextPinMeta ? structuredClone(resolved.state.contextPinMeta) : undefined,
       ax: resolved.state.ax ? structuredClone(resolved.state.ax) : createEmptyAxState(),
       revisionState: resolved.state.revisionState ? structuredClone(resolved.state.revisionState) : undefined,
     };
@@ -2062,7 +2088,6 @@ class CanvasStateManager {
       // moved child's requested coordinates. Compaction is opt-in (group
       // create/add with childLayout, or arrange).
       this.recomputeParentGroupBounds(parentGroupId);
-      this.reflowAllGroups();
     }
     this.scheduleSave();
     this.notifyChange('nodes');
@@ -2093,6 +2118,7 @@ class CanvasStateManager {
     const cloned = existing ? structuredClone(existing) : null;
     const oldAxState = this.getAxState();
     const wasPinned = this._contextPinnedNodeIds.has(id);
+    const pinMeta = this._contextPinMeta.get(id);
     // The enclosing group's membership before this removal — restored verbatim on undo.
     let enclosingBefore: { id: string; children: string[] } | null = null;
     // A removed group DISSOLVES: its children are released — into the enclosing
@@ -2127,6 +2153,7 @@ class CanvasStateManager {
     this.nodes.delete(id);
     this.removeEdgesForNode(id);
     this._contextPinnedNodeIds.delete(id);
+    this._contextPinMeta.delete(id);
     // Re-normalize canvas-bound AX against the surviving node set. This strips the
     // dangling node ref from work items / approval gates / elicitations / mode
     // requests (re-anchored) and drops node-anchored review annotations (removed).
@@ -2191,7 +2218,10 @@ class CanvasStateManager {
             }
           }
           for (const edge of connectedEdges) this.addEdge(structuredClone(edge));
-          if (wasPinned) this._contextPinnedNodeIds.add(id);
+          if (wasPinned) {
+            this._contextPinnedNodeIds.add(id);
+            if (pinMeta) this._contextPinMeta.set(id, pinMeta);
+          }
           this.ax.applyPersistedAx(oldAxState);
           this.scheduleSave();
           this.notifyChange('nodes');
@@ -2444,7 +2474,6 @@ class CanvasStateManager {
     for (const groupId of touchedParentGroups) {
       this.recomputeParentGroupBounds(groupId);
     }
-    if (touchedParentGroups.size > 0) this.reflowAllGroups();
 
     if (applied > 0) {
       this.scheduleSave();
@@ -2849,13 +2878,41 @@ class CanvasStateManager {
   recordContextRead(input: ContextReadInput, boardId: string | null = this._activeBoardId): ContextRead | null {
     if (!this._db) return null;
     try {
-      return appendContextReadToDB(this._db, input, boardId);
+      const read = appendContextReadToDB(this._db, input, boardId, this.readRevisions(input, boardId));
+      this._contextReadListener?.(boardId);
+      return read;
     } catch (error) {
       logCanvasStateWarning('record context read failed', error);
       return null;
     }
   }
 
+  /** The delivered ids that are nodes on the read board, each with its content revision now. */
+  private readRevisions(input: ContextReadInput, boardId: string | null): Record<string, number> {
+    if (!boardId) return {};
+    const nodes =
+      boardId === this._activeBoardId ? [...this.nodes.values()] : (this.readBoard(boardId, false)?.state.nodes ?? []);
+    const byId = new Map(nodes.map((node) => [node.id, node.contentRevision ?? 0]));
+    const revisions: Record<string, number> = {};
+    for (const id of input.readNodeIds ?? input.deliveredNodeIds) {
+      const revision = byId.get(id);
+      if (revision !== undefined) revisions[id] = revision;
+    }
+    return revisions;
+  }
+
+  /** Per node on a board, the latest agent read that delivered its content. */
+  getNodeReadStatus(boardId: string | null = this._activeBoardId): NodeReadStatus[] {
+    if (!this._db || !boardId) return [];
+    return loadNodeReadStatusFromDB(this._db, boardId);
+  }
+
+  /** Nodes on a board whose content an agent read at or after `since` (ISO). */
+  getReadNodeIdsSince(boardId: string | null, since: string): string[] {
+    if (!this._db || !boardId) return [];
+    return loadReadNodeIdsSince(this._db, boardId, since);
+  }
+
   getContextReads(limit?: number): { reads: ContextRead[]; summary: ContextReadConsumerSummary[] } {
     return this._db ? loadContextReadsFromDB(this._db, limit) : { reads: [], summary: [] };
   }
@@ -2869,25 +2926,57 @@ class CanvasStateManager {
     return this.ax.getAxTimeline(q);
   }
 
-  setContextPins(nodeIds: string[]): void {
+  /**
+   * Replace the pin set. Newly pinned nodes are attributed to the current
+   * actor (with `reason` when given); pins that stay keep their attribution.
+   * `restore` re-applies saved attribution, so undo does not re-attribute.
+   */
+  setContextPins(nodeIds: string[], options: { reason?: string; restore?: Map<string, ContextPinMeta> } = {}): void {
     const oldPins = Array.from(this._contextPinnedNodeIds);
+    const oldMeta = new Map(this._contextPinMeta);
+    const pinnedAt = new Date().toISOString();
     this._contextPinnedNodeIds.clear();
     for (const id of nodeIds) {
-      if (this.nodes.has(id)) {
-        this._contextPinnedNodeIds.add(id);
-      }
-    }
+      if (!this.nodes.has(id)) continue;
+      this._contextPinnedNodeIds.add(id);
+      const meta =
+        options.restore?.get(id) ??
+        (oldPins.includes(id) ? oldMeta.get(id) : undefined) ??
+        (oldPins.includes(id)
+          ? undefined
+          : { pinnedBy: currentActor(), pinnedAt, ...(options.reason ? { reason: options.reason } : {}) });
+      if (meta) this._contextPinMeta.set(id, meta);
+    }
+    for (const id of [...this._contextPinMeta.keys()]) {
+      if (!this._contextPinnedNodeIds.has(id)) this._contextPinMeta.delete(id);
+    }
+    const newMeta = new Map(this._contextPinMeta);
     this.scheduleSave();
     this.notifyChange('pins');
     this.recordMutation({
       operationType: 'setPins',
       description: `Set context pins (${this._contextPinnedNodeIds.size} nodes)`,
-      forward: this.suppressed(() => this.setContextPins([...nodeIds])),
-      inverse: this.suppressed(() => this.setContextPins(oldPins)),
+      forward: this.suppressed(() => this.setContextPins([...nodeIds], { restore: newMeta })),
+      inverse: this.suppressed(() => this.setContextPins(oldPins, { restore: oldMeta })),
     });
   }
 
+  /** Who pinned each current pin, when and why (pins with an unknown pinner are absent). */
+  getContextPinMeta(): Record<string, ContextPinMeta> {
+    return this.pinMetaRecord();
+  }
+
+  private pinMetaRecord(): Record<string, ContextPinMeta> {
+    const record: Record<string, ContextPinMeta> = {};
+    for (const id of this._contextPinnedNodeIds) {
+      const meta = this._contextPinMeta.get(id);
+      if (meta) record[id] = structuredClone(meta);
+    }
+    return record;
+  }
+
   clearContextPins(): void {
+    this._contextPinMeta.clear();
     this._contextPinnedNodeIds.clear();
     this.scheduleSave();
     this.notifyChange('pins');
@@ -3019,6 +3108,7 @@ class CanvasStateManager {
     this.edges.clear();
     this.annotations.clear();
     this._contextPinnedNodeIds.clear();
+    this._contextPinMeta.clear();
     // Clears canvas-bound AX state (focus, work items, approvals, review annotations).
     // Timeline tables (ax_events/ax_evidence/ax_steering) and host capability are
     // deliberately retained per the AX state-partition policy.

package/src/server/canvas-validation.ts

@@ -71,13 +71,27 @@ function fullyContains(group: CanvasNodeState, child: CanvasNodeState): boolean
   );
 }
 
-function isGroupChildPair(group: CanvasNodeState, child: CanvasNodeState): boolean {
-  if (group.type !== 'group') return false;
+function isDirectGroupChild(group: CanvasNodeState, child: CanvasNodeState): boolean {
   if (child.data.parentGroup === group.id) return true;
   const children = group.data.children;
   return Array.isArray(children) && children.includes(child.id);
 }
 
+/** True when `child` sits anywhere inside `group` — a nested group's members are
+ *  inside every ancestor frame, not overlapping it. */
+function isGroupChildPair(group: CanvasNodeState, child: CanvasNodeState, byId: Map<string, CanvasNodeState>): boolean {
+  if (group.type !== 'group') return false;
+  const seen = new Set<string>();
+  let current: CanvasNodeState | undefined = child;
+  while (current && !seen.has(current.id)) {
+    if (isDirectGroupChild(group, current)) return true;
+    seen.add(current.id);
+    const parentId: unknown = current.data.parentGroup;
+    current = typeof parentId === 'string' ? byId.get(parentId) : undefined;
+  }
+  return false;
+}
+
 function pair(a: CanvasNodeState, b: CanvasNodeState): CanvasValidationPair {
   return {
     aId: a.id,
@@ -101,6 +115,7 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
   const containments: CanvasContainmentIssue[] = [];
   const containmentViolations: CanvasContainmentIssue[] = [];
   const groupFrameOverlaps: CanvasValidationPair[] = [];
+  const byId = new Map(layout.nodes.map((node) => [node.id, node]));
 
   for (let i = 0; i < layout.nodes.length; i++) {
     const a = layout.nodes[i]!;
@@ -108,11 +123,11 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
       const b = layout.nodes[j]!;
       if (!overlaps(a, b)) continue;
 
-      if (isGroupChildPair(a, b)) {
+      if (isGroupChildPair(a, b, byId)) {
         (fullyContains(a, b) ? containments : containmentViolations).push(containment(a, b));
         continue;
       }
-      if (isGroupChildPair(b, a)) {
+      if (isGroupChildPair(b, a, byId)) {
         (fullyContains(b, a) ? containments : containmentViolations).push(containment(b, a));
         continue;
       }