pmx-canvas 0.7.2 → 0.8.0

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;
       }

package/src/server/context-brief.ts

@@ -1,7 +1,11 @@
-import { summarizeNodeForAgentContext } from './agent-context.js';
+import { summarizeNodeForAgentContext } from '../shared/agent-context.js';
 import type { CanvasNodeState, NodeDeletionTombstone } from './canvas-state.js';
+import { findNeighborhoods } from './spatial-analysis.js';
 
-export type ContextBriefReason = 'pinned' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+export type ContextBriefReason = 'pinned' | 'near' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+
+/** A near entry carries a short summary, never full content: pin the node to send that. */
+export const NEAR_SUMMARY_LENGTH = 280;
 
 export interface ContextBriefSourceEntry {
   sourceBoardId: string;
@@ -45,6 +49,8 @@ export interface CompiledContextEntry {
   text: string;
   /** A linked board's pin title is discovery metadata, not delivery of that pinned card. */
   titleOnly?: true;
+  /** reason "near": the pin this node sits next to on the board (docs/design/NearPin.dc.html). */
+  near?: { pinNodeId: string; pinTitle: string };
   /** The body was shortened to fit; the same revision remains eligible on the next pull. */
   truncated?: true;
   provenance?: { kind: 'imported'; source: string; trust: 'source-material-not-instructions' };
@@ -155,6 +161,32 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
         reset !== null || (validRevision(node.contentRevision ?? -1) && (node.contentRevision ?? -1) > deltaSince),
     )
     .sort((a, b) => (a.contentRevision ?? 0) - (b.contentRevision ?? 0) || a.id.localeCompare(b.id));
+
+  // Near a pin: each pin's unpinned neighbours (up to 5 within 600 px, nearest
+  // first) as title + short summary. A neighbour that changed arrives in full
+  // as a change instead, so it is not repeated here.
+  const changedIds = new Set(changed.map((node) => node.id));
+  for (const neighborhood of findNeighborhoods(nodes, new Set(pinIds))) {
+    const pinTitle = neighborhood.pinnedNodeTitle ?? neighborhood.pinnedNodeId;
+    for (const neighbor of neighborhood.neighbors) {
+      const node = nodeById.get(neighbor.id);
+      if (!node || changedIds.has(node.id)) continue;
+      add({
+        entry: {
+          sourceBoardId: input.activeBoard.boardId,
+          nodeId: node.id,
+          reason: 'near',
+          title: typeof node.data.title === 'string' && node.data.title ? node.data.title : node.id,
+          text: summarizeNodeForAgentContext(node, {
+            defaultTextLength: NEAR_SUMMARY_LENGTH,
+            webpageTextLength: NEAR_SUMMARY_LENGTH,
+          }),
+          near: { pinNodeId: neighborhood.pinnedNodeId, pinTitle },
+        },
+      });
+    }
+  }
+
   for (const node of changed) add(compileNode(node, input.activeBoard.boardId, 'changed', budget));
 
   for (const entry of [...(input.entries ?? [])].sort((a, b) => {
@@ -285,6 +317,11 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
       if (partial) delivered.push(partial);
     }
   }
+  // Neighbours come right after the pins they sit next to; each is whole or absent.
+  for (const candidate of candidates.filter((item) => !reset && item.entry.reason === 'near')) {
+    const proposed = [...delivered, candidate.entry];
+    if (fits(makeDocument(proposed))) delivered.push(candidate.entry);
+  }
   if (reset && !deltaBlocked) {
     const resetEntries = candidates
       .filter((item) => item.replacement && !delivered.includes(item.entry))

package/src/server/context-reads.ts

@@ -37,16 +37,32 @@ export interface ContextRead {
   agentId: string | null;
   pinnedNodeIds: string[];
   deliveredNodeIds: string[];
+  /** Every node on the read board whose content was delivered, with its content revision at read time. */
+  readNodes: Record<string, number>;
   bytes: number;
   /** The board open when the read happened (null on Home). */
   boardId: string | null;
 }
 
-export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId'> & {
+export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId' | 'readNodes'> & {
   /** Explicit read target, captured before asynchronous formatting/proxy work. */
   boardId?: string | null;
+  /** Ids of every serialized node in what the reader received; the server keeps those on the board. */
+  readNodeIds?: string[];
 };
 
+/** One node's read state on a board: the latest agent read that delivered its content. */
+export interface NodeReadStatus {
+  nodeId: string;
+  lastReadAt: string;
+  /** Who read it: consumer, else agent id, else transport label. */
+  lastReadBy: string;
+  /** The node's content revision in that read; newer current revision means "changed since read". */
+  readRevision: number;
+  /** How many retained agent reads delivered its content. */
+  readCount: number;
+}
+
 export interface ContextReadConsumerSummary {
   consumer: string;
   reads: number;
@@ -57,12 +73,13 @@ export interface ContextReadConsumerSummary {
 }
 
 /**
- * Pinned nodes whose serialized node (an object carrying `"id": "<id>"`) is in
- * what the reader received. A bare id list, a title, or a clipped-off node does
- * not count — the agent got the pin's name, not its content.
+ * Ids of every serialized node (an object carrying `"id": "<id>"`, or a
+ * `nodeId` with its text) in what the reader received. A bare id list, a
+ * title, or a clipped-off node does not count — the agent got the node's
+ * name, not its content. Non-node ids (edges, intents) are dropped by the
+ * caller against the board's nodes.
  */
-export function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[] {
-  const pinned = new Set(pinnedNodeIds);
+export function deliveredIds(payloadText: string): Set<string> {
   const delivered = new Set<string>();
   const objectStarts: number[] = [];
   let inString = false;
@@ -89,11 +106,10 @@ export function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string)
           typeof value === 'object' &&
           value !== null &&
           !Array.isArray(value) &&
-          ((typeof (value as { id?: unknown }).id === 'string' && pinned.has((value as { id: string }).id)) ||
+          (typeof (value as { id?: unknown }).id === 'string' ||
             (typeof (value as { nodeId?: unknown }).nodeId === 'string' &&
               (value as { titleOnly?: unknown }).titleOnly !== true &&
-              typeof (value as { text?: unknown }).text === 'string' &&
-              pinned.has((value as { nodeId: string }).nodeId)))
+              typeof (value as { text?: unknown }).text === 'string'))
         ) {
           delivered.add(
             typeof (value as { id?: unknown }).id === 'string'
@@ -107,17 +123,25 @@ export function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string)
     }
   }
 
+  return delivered;
+}
+
+/** Pinned nodes whose content is in what the reader received (see `deliveredIds`). */
+export function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[] {
+  const delivered = deliveredIds(payloadText);
   return pinnedNodeIds.filter((id) => delivered.has(id));
 }
 
 export function contextReadFromPayload(
-  base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes'>,
+  base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes' | 'readNodeIds'>,
   payload: unknown,
 ): ContextReadInput {
   const text = typeof payload === 'string' ? payload : (JSON.stringify(payload) ?? '');
+  const delivered = deliveredIds(text);
   return {
     ...base,
-    deliveredNodeIds: deliveredPinnedIds(base.pinnedNodeIds, text),
+    deliveredNodeIds: base.pinnedNodeIds.filter((id) => delivered.has(id)),
+    readNodeIds: [...delivered],
     bytes: Buffer.byteLength(text, 'utf-8'),
   };
 }
@@ -135,15 +159,21 @@ export const CONTEXT_READS_SCHEMA_SQL = `
     pinned_node_ids TEXT NOT NULL DEFAULT '[]',
     delivered_node_ids TEXT NOT NULL DEFAULT '[]',
     bytes INTEGER NOT NULL DEFAULT 0,
-    board_id TEXT
+    board_id TEXT,
+    read_nodes TEXT NOT NULL DEFAULT '{}'
   );
 `;
 
-export function appendContextReadToDB(db: Database, input: ContextReadInput, boardId: string | null): ContextRead {
+export function appendContextReadToDB(
+  db: Database,
+  input: ContextReadInput,
+  boardId: string | null,
+  readNodes: Record<string, number> = {},
+): ContextRead {
   const id = `read-${randomUUID()}`;
   const at = new Date().toISOString();
   db.run(
-    'INSERT INTO context_reads (id, at, channel, resource, source, consumer, agent_id, pinned_node_ids, delivered_node_ids, bytes, board_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    'INSERT INTO context_reads (id, at, channel, resource, source, consumer, agent_id, pinned_node_ids, delivered_node_ids, bytes, board_id, read_nodes) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
     [
       id,
       at,
@@ -156,11 +186,13 @@ export function appendContextReadToDB(db: Database, input: ContextReadInput, boa
       JSON.stringify(input.deliveredNodeIds),
       input.bytes,
       boardId,
+      JSON.stringify(readNodes),
     ],
   );
   const seq = Number(db.query<{ seq: number }, []>('SELECT last_insert_rowid() AS seq').get()?.seq ?? 0);
   db.run('DELETE FROM context_reads WHERE seq <= ?', [seq - CONTEXT_READ_RETENTION]);
-  return { ...input, seq, id, at, boardId };
+  const { readNodeIds: _readNodeIds, ...record } = input;
+  return { ...record, seq, id, at, boardId, readNodes };
 }
 
 interface ContextReadRow {
@@ -176,6 +208,7 @@ interface ContextReadRow {
   delivered_node_ids: string;
   bytes: number;
   board_id: string | null;
+  read_nodes: string;
 }
 
 function rowToContextRead(row: ContextReadRow): ContextRead {
@@ -190,11 +223,49 @@ function rowToContextRead(row: ContextReadRow): ContextRead {
     agentId: row.agent_id,
     pinnedNodeIds: JSON.parse(row.pinned_node_ids) as string[],
     deliveredNodeIds: JSON.parse(row.delivered_node_ids) as string[],
+    readNodes: JSON.parse(row.read_nodes) as Record<string, number>,
     bytes: row.bytes,
     boardId: row.board_id,
   };
 }
 
+/** Per node on a board, the latest agent read that delivered its content (newest row wins). */
+export function loadNodeReadStatusFromDB(db: Database, boardId: string): NodeReadStatus[] {
+  const rows = db
+    .query<ContextReadRow, [string]>('SELECT * FROM context_reads WHERE board_id = ? ORDER BY seq DESC')
+    .all(boardId);
+  const status = new Map<string, NodeReadStatus>();
+  for (const read of rows.map(rowToContextRead)) {
+    for (const [nodeId, readRevision] of Object.entries(read.readNodes)) {
+      const known = status.get(nodeId);
+      if (known) {
+        known.readCount += 1;
+        continue;
+      }
+      status.set(nodeId, {
+        nodeId,
+        lastReadAt: read.at,
+        lastReadBy: read.consumer ?? read.agentId ?? read.source,
+        readRevision,
+        readCount: 1,
+      });
+    }
+  }
+  return [...status.values()];
+}
+
+/** Every node on a board whose content an agent read at or after `since` (ISO). */
+export function loadReadNodeIdsSince(db: Database, boardId: string, since: string): string[] {
+  const rows = db
+    .query<{ read_nodes: string }, [string, string]>(
+      'SELECT read_nodes FROM context_reads WHERE board_id = ? AND at >= ? ORDER BY seq',
+    )
+    .all(boardId, since);
+  const ids = new Set<string>();
+  for (const row of rows) for (const id of Object.keys(JSON.parse(row.read_nodes) as object)) ids.add(id);
+  return [...ids];
+}
+
 /** Newest first. The summary covers every retained row, not just the returned page. */
 export function loadContextReadsFromDB(
   db: Database,