feat(runtime): admit cross-epoch graph results

apps/desktop/src/main/__tests__/agent-graph-panel.test.ts

@@ -4,10 +4,33 @@ import { parseHTML } from 'linkedom';
 import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
+import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
 import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
 
 type GraphListener = () => void;
 
+interface DeferredRead {
+ started: Promise<void>;
+ release(): void;
+}
+
+interface DeferredReadGate extends DeferredRead {
+ markStarted(): void;
+ waitForRelease: Promise<void>;
+}
+
+function deferredReadGate(): DeferredReadGate {
+ let markStarted = () => {};
+ let release = () => {};
+ const started = new Promise<void>((resolve) => {
+ markStarted = resolve;
+ });
+ const waitForRelease = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ return { started, markStarted, release, waitForRelease };
+}
+
 const originalGlobals = {
  document: globalThis.document,
  window: globalThis.window,
@@ -59,11 +82,18 @@ function snapshot(
  };
 }
 
-function installGraphRenderer(initial: AgentGraphClientSnapshot): {
+function installGraphRenderer(
+ initial: AgentGraphClientSnapshot,
+ historical: readonly AgentGraphClientSnapshot[] = [],
+): {
  container: Element;
  root: Root;
  setSnapshot(next: AgentGraphClientSnapshot): Promise<void>;
+ evict(graphId: string): void;
  renderSession(sessionId: string): Promise<void>;
+ holdNextEpochList(sessionId: string): DeferredRead;
+ holdNextSnapshot(graphId: string): DeferredRead;
+ stopCalls: string[];
 } {
  const { document, window } = parseHTML('<div id="root"></div>');
  const matchMedia = (media: string) => ({
@@ -88,15 +118,54 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  IS_REACT_ACT_ENVIRONMENT: true,
  });
 
- const snapshots = new Map<string, AgentGraphClientSnapshot>([
- [initial.rootSessionId, initial],
- ]);
+ const snapshots = new Map(
+ [initial, ...historical].map((entry) => [entry.graphId, entry] as const),
+ );
+ const currentGraphIds = new Map<string, string>();
+ for (const entry of [initial, ...historical]) {
+ if (!currentGraphIds.has(entry.rootSessionId)) {
+ currentGraphIds.set(entry.rootSessionId, entry.graphId);
+ }
+ }
  const listeners = new Set<GraphListener>();
+ const epochListGates = new Map<string, DeferredReadGate>();
+ const snapshotGates = new Map<string, DeferredReadGate>();
+ const stopCalls: string[] = [];
  (window as unknown as { maka: unknown }).maka = {
  graphs: {
- getSnapshot: async (sessionId: string) => {
- const next = snapshots.get(sessionId);
- if (!next) throw new Error(`missing graph snapshot for ${sessionId}`);
+ listEpochs: async (sessionId: string) => {
+ const gate = epochListGates.get(sessionId);
+ if (gate) {
+ epochListGates.delete(sessionId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const currentGraphId = currentGraphIds.get(sessionId);
+ const entries = [...snapshots.values()]
+ .filter((entry) => entry.rootSessionId === sessionId)
+ .sort((left, right) => Number(right.graphId === currentGraphId) - Number(left.graphId === currentGraphId));
+ return {
+ epochs: entries.map((entry, index) => ({
+ epoch: entries.length - index,
+ graphId: entry.graphId,
+ createdAt: index + 1,
+ current: currentGraphIds.get(sessionId) === entry.graphId,
+ })),
+ truncated: false,
+ };
+ },
+ getSnapshot: async (sessionId: string, options?: { graphId?: string }) => {
+ const graphId = options?.graphId ?? currentGraphIds.get(sessionId);
+ const gate = graphId ? snapshotGates.get(graphId) : undefined;
+ if (gate && graphId) {
+ snapshotGates.delete(graphId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const next = graphId ? snapshots.get(graphId) : undefined;
+ if (!next || next.rootSessionId !== sessionId) {
+ throw new Error(`missing graph snapshot for ${sessionId}`);
+ }
  return next;
  },
  inspectOperator: async () => {
@@ -108,7 +177,9 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  listeners.delete(listener);
  };
  },
- stop: async () => undefined,
+ stop: async (sessionId: string) => {
+ stopCalls.push(sessionId);
+ },
  },
  };
 
@@ -119,12 +190,16 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  container,
  root,
  async setSnapshot(next) {
- snapshots.set(next.rootSessionId, next);
+ snapshots.set(next.graphId, next);
+ currentGraphIds.set(next.rootSessionId, next.graphId);
  await act(async () => {
  for (const listener of [...listeners]) listener();
  await Promise.resolve();
  });
  },
+ evict(graphId) {
+ snapshots.delete(graphId);
+ },
  async renderSession(sessionId) {
  await act(async () => {
  root.render(
@@ -138,6 +213,17 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  await Promise.resolve();
  });
  },
+ holdNextEpochList(sessionId) {
+ const gate = deferredReadGate();
+ epochListGates.set(sessionId, gate);
+ return gate;
+ },
+ holdNextSnapshot(graphId) {
+ const gate = deferredReadGate();
+ snapshotGates.set(graphId, gate);
+ return gate;
+ },
+ stopCalls,
  };
 }
 
@@ -160,6 +246,126 @@ async function renderPanel(
 }
 
 describe('AgentGraphPanel dismiss', () => {
+ it('keeps the new session loading when a disposed read settles later', async () => {
+ const sessionA = snapshot({ graphId: 'graph-a', status: 'active' });
+ const sessionB = snapshot({
+ graphId: 'graph-b',
+ status: 'active',
+ rootSessionId: 'session-2',
+ });
+ const harness = installGraphRenderer(sessionA, [sessionB]);
+ const readA = harness.holdNextEpochList('session-1');
+ await harness.renderSession('session-1');
+ await readA.started;
+
+ const readB = harness.holdNextEpochList('session-2');
+ await harness.renderSession('session-2');
+ await readB.started;
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readA.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readB.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Agent Graph/);
+ await act(async () => harness.root.unmount());
+ });
+
+ it('switches to a historical epoch without exposing current-graph controls', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ assert.match(harness.container.textContent ?? '', /Stop graph/);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ const historyRead = harness.holdNextSnapshot('graph-1');
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await historyRead.started;
+ });
+
+ assert.match(harness.container.textContent ?? '', /#1 · History \(read-only\)/);
+ assert.doesNotMatch(harness.container.textContent ?? '', /Stop graph/);
+ assert.equal(harness.container.querySelector('.maka-agent-graph-dismiss'), null);
+ assert.deepEqual(harness.stopCalls, []);
+ await act(async () => {
+ historyRead.release();
+ await Promise.resolve();
+ });
+ await act(async () => harness.root.unmount());
+ });
+
+ it('resumes following the current epoch after the selected history expires', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const combobox = () => harness.container.querySelector('[role="combobox"]')?.textContent ?? '';
+ assert.match(combobox(), /#1 · History \(read-only\)/);
+
+ // The selected epoch leaves the bounded directory while the graph rolls over.
+ harness.evict('graph-1');
+ await harness.setSnapshot(snapshot({ graphId: 'graph-3', status: 'active' }));
+ assert.match(combobox(), /#2 · Current/);
+
+ // Follow restored: the next rollover refreshes the panel instead of
+ // staying pinned on the fallback graph.
+ await harness.setSnapshot(snapshot({ graphId: 'graph-4', status: 'waiting' }));
+ assert.match(combobox(), /#3 · Current/);
+ await act(async () => harness.root.unmount());
+ });
+
  it('shows dismiss only after the graph has settled', async () => {
  const active = await renderPanel(snapshot({ graphId: 'graph-1', status: 'active' }));
  assert.ok(active.container.querySelector('.maka-agent-graph-panel'));

apps/desktop/src/main/__tests__/agent-graph-panel.test.ts

@@ -4,10 +4,33 @@ import { parseHTML } from 'linkedom';
 import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
+import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
 import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
 
 type GraphListener = () => void;
 
+interface DeferredRead {
+ started: Promise<void>;
+ release(): void;
+}
+
+interface DeferredReadGate extends DeferredRead {
+ markStarted(): void;
+ waitForRelease: Promise<void>;
+}
+
+function deferredReadGate(): DeferredReadGate {
+ let markStarted = () => {};
+ let release = () => {};
+ const started = new Promise<void>((resolve) => {
+ markStarted = resolve;
+ });
+ const waitForRelease = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ return { started, markStarted, release, waitForRelease };
+}
+
 const originalGlobals = {
  document: globalThis.document,
  window: globalThis.window,
@@ -59,11 +82,18 @@ function snapshot(
  };
 }
 
-function installGraphRenderer(initial: AgentGraphClientSnapshot): {
+function installGraphRenderer(
+ initial: AgentGraphClientSnapshot,
+ historical: readonly AgentGraphClientSnapshot[] = [],
+): {
  container: Element;
  root: Root;
  setSnapshot(next: AgentGraphClientSnapshot): Promise<void>;
+ evict(graphId: string): void;
  renderSession(sessionId: string): Promise<void>;
+ holdNextEpochList(sessionId: string): DeferredRead;
+ holdNextSnapshot(graphId: string): DeferredRead;
+ stopCalls: string[];
 } {
  const { document, window } = parseHTML('<div id="root"></div>');
  const matchMedia = (media: string) => ({
@@ -88,15 +118,54 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  IS_REACT_ACT_ENVIRONMENT: true,
  });
 
- const snapshots = new Map<string, AgentGraphClientSnapshot>([
- [initial.rootSessionId, initial],
- ]);
+ const snapshots = new Map(
+ [initial, ...historical].map((entry) => [entry.graphId, entry] as const),
+ );
+ const currentGraphIds = new Map<string, string>();
+ for (const entry of [initial, ...historical]) {
+ if (!currentGraphIds.has(entry.rootSessionId)) {
+ currentGraphIds.set(entry.rootSessionId, entry.graphId);
+ }
+ }
  const listeners = new Set<GraphListener>();
+ const epochListGates = new Map<string, DeferredReadGate>();
+ const snapshotGates = new Map<string, DeferredReadGate>();
+ const stopCalls: string[] = [];
  (window as unknown as { maka: unknown }).maka = {
  graphs: {
- getSnapshot: async (sessionId: string) => {
- const next = snapshots.get(sessionId);
- if (!next) throw new Error(`missing graph snapshot for ${sessionId}`);
+ listEpochs: async (sessionId: string) => {
+ const gate = epochListGates.get(sessionId);
+ if (gate) {
+ epochListGates.delete(sessionId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const currentGraphId = currentGraphIds.get(sessionId);
+ const entries = [...snapshots.values()]
+ .filter((entry) => entry.rootSessionId === sessionId)
+ .sort((left, right) => Number(right.graphId === currentGraphId) - Number(left.graphId === currentGraphId));
+ return {
+ epochs: entries.map((entry, index) => ({
+ epoch: entries.length - index,
+ graphId: entry.graphId,
+ createdAt: index + 1,
+ current: currentGraphIds.get(sessionId) === entry.graphId,
+ })),
+ truncated: false,
+ };
+ },
+ getSnapshot: async (sessionId: string, options?: { graphId?: string }) => {
+ const graphId = options?.graphId ?? currentGraphIds.get(sessionId);
+ const gate = graphId ? snapshotGates.get(graphId) : undefined;
+ if (gate && graphId) {
+ snapshotGates.delete(graphId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const next = graphId ? snapshots.get(graphId) : undefined;
+ if (!next || next.rootSessionId !== sessionId) {
+ throw new Error(`missing graph snapshot for ${sessionId}`);
+ }
  return next;
  },
  inspectOperator: async () => {
@@ -108,7 +177,9 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  listeners.delete(listener);
  };
  },
- stop: async () => undefined,
+ stop: async (sessionId: string) => {
+ stopCalls.push(sessionId);
+ },
  },
  };
 
@@ -119,12 +190,16 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  container,
  root,
  async setSnapshot(next) {
- snapshots.set(next.rootSessionId, next);
+ snapshots.set(next.graphId, next);
+ currentGraphIds.set(next.rootSessionId, next.graphId);
  await act(async () => {
  for (const listener of [...listeners]) listener();
  await Promise.resolve();
  });
  },
+ evict(graphId) {
+ snapshots.delete(graphId);
+ },
  async renderSession(sessionId) {
  await act(async () => {
  root.render(
@@ -138,6 +213,17 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  await Promise.resolve();
  });
  },
+ holdNextEpochList(sessionId) {
+ const gate = deferredReadGate();
+ epochListGates.set(sessionId, gate);
+ return gate;
+ },
+ holdNextSnapshot(graphId) {
+ const gate = deferredReadGate();
+ snapshotGates.set(graphId, gate);
+ return gate;
+ },
+ stopCalls,
  };
 }
 
@@ -160,6 +246,126 @@ async function renderPanel(
 }
 
 describe('AgentGraphPanel dismiss', () => {
+ it('keeps the new session loading when a disposed read settles later', async () => {
+ const sessionA = snapshot({ graphId: 'graph-a', status: 'active' });
+ const sessionB = snapshot({
+ graphId: 'graph-b',
+ status: 'active',
+ rootSessionId: 'session-2',
+ });
+ const harness = installGraphRenderer(sessionA, [sessionB]);
+ const readA = harness.holdNextEpochList('session-1');
+ await harness.renderSession('session-1');
+ await readA.started;
+
+ const readB = harness.holdNextEpochList('session-2');
+ await harness.renderSession('session-2');
+ await readB.started;
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readA.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readB.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Agent Graph/);
+ await act(async () => harness.root.unmount());
+ });
+
+ it('switches to a historical epoch without exposing current-graph controls', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ assert.match(harness.container.textContent ?? '', /Stop graph/);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ const historyRead = harness.holdNextSnapshot('graph-1');
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await historyRead.started;
+ });
+
+ assert.match(harness.container.textContent ?? '', /#1 · History \(read-only\)/);
+ assert.doesNotMatch(harness.container.textContent ?? '', /Stop graph/);
+ assert.equal(harness.container.querySelector('.maka-agent-graph-dismiss'), null);
+ assert.deepEqual(harness.stopCalls, []);
+ await act(async () => {
+ historyRead.release();
+ await Promise.resolve();
+ });
+ await act(async () => harness.root.unmount());
+ });
+
+ it('resumes following the current epoch after the selected history expires', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const combobox = () => harness.container.querySelector('[role="combobox"]')?.textContent ?? '';
+ assert.match(combobox(), /#1 · History \(read-only\)/);
+
+ // The selected epoch leaves the bounded directory while the graph rolls over.
+ harness.evict('graph-1');
+ await harness.setSnapshot(snapshot({ graphId: 'graph-3', status: 'active' }));
+ assert.match(combobox(), /#2 · Current/);
+
+ // Follow restored: the next rollover refreshes the panel instead of
+ // staying pinned on the fallback graph.
+ await harness.setSnapshot(snapshot({ graphId: 'graph-4', status: 'waiting' }));
+ assert.match(combobox(), /#3 · Current/);
+ await act(async () => harness.root.unmount());
+ });
+
  it('shows dismiss only after the graph has settled', async () => {
  const active = await renderPanel(snapshot({ graphId: 'graph-1', status: 'active' }));
  assert.ok(active.container.querySelector('.maka-agent-graph-panel'));

apps/desktop/src/main/__tests__/agent-graph-panel.test.ts

@@ -4,10 +4,33 @@ import { parseHTML } from 'linkedom';
 import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
+import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
 import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
 
 type GraphListener = () => void;
 
+interface DeferredRead {
+ started: Promise<void>;
+ release(): void;
+}
+
+interface DeferredReadGate extends DeferredRead {
+ markStarted(): void;
+ waitForRelease: Promise<void>;
+}
+
+function deferredReadGate(): DeferredReadGate {
+ let markStarted = () => {};
+ let release = () => {};
+ const started = new Promise<void>((resolve) => {
+ markStarted = resolve;
+ });
+ const waitForRelease = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ return { started, markStarted, release, waitForRelease };
+}
+
 const originalGlobals = {
  document: globalThis.document,
  window: globalThis.window,
@@ -59,11 +82,18 @@ function snapshot(
  };
 }
 
-function installGraphRenderer(initial: AgentGraphClientSnapshot): {
+function installGraphRenderer(
+ initial: AgentGraphClientSnapshot,
+ historical: readonly AgentGraphClientSnapshot[] = [],
+): {
  container: Element;
  root: Root;
  setSnapshot(next: AgentGraphClientSnapshot): Promise<void>;
+ evict(graphId: string): void;
  renderSession(sessionId: string): Promise<void>;
+ holdNextEpochList(sessionId: string): DeferredRead;
+ holdNextSnapshot(graphId: string): DeferredRead;
+ stopCalls: string[];
 } {
  const { document, window } = parseHTML('<div id="root"></div>');
  const matchMedia = (media: string) => ({
@@ -88,15 +118,54 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  IS_REACT_ACT_ENVIRONMENT: true,
  });
 
- const snapshots = new Map<string, AgentGraphClientSnapshot>([
- [initial.rootSessionId, initial],
- ]);
+ const snapshots = new Map(
+ [initial, ...historical].map((entry) => [entry.graphId, entry] as const),
+ );
+ const currentGraphIds = new Map<string, string>();
+ for (const entry of [initial, ...historical]) {
+ if (!currentGraphIds.has(entry.rootSessionId)) {
+ currentGraphIds.set(entry.rootSessionId, entry.graphId);
+ }
+ }
  const listeners = new Set<GraphListener>();
+ const epochListGates = new Map<string, DeferredReadGate>();
+ const snapshotGates = new Map<string, DeferredReadGate>();
+ const stopCalls: string[] = [];
  (window as unknown as { maka: unknown }).maka = {
  graphs: {
- getSnapshot: async (sessionId: string) => {
- const next = snapshots.get(sessionId);
- if (!next) throw new Error(`missing graph snapshot for ${sessionId}`);
+ listEpochs: async (sessionId: string) => {
+ const gate = epochListGates.get(sessionId);
+ if (gate) {
+ epochListGates.delete(sessionId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const currentGraphId = currentGraphIds.get(sessionId);
+ const entries = [...snapshots.values()]
+ .filter((entry) => entry.rootSessionId === sessionId)
+ .sort((left, right) => Number(right.graphId === currentGraphId) - Number(left.graphId === currentGraphId));
+ return {
+ epochs: entries.map((entry, index) => ({
+ epoch: entries.length - index,
+ graphId: entry.graphId,
+ createdAt: index + 1,
+ current: currentGraphIds.get(sessionId) === entry.graphId,
+ })),
+ truncated: false,
+ };
+ },
+ getSnapshot: async (sessionId: string, options?: { graphId?: string }) => {
+ const graphId = options?.graphId ?? currentGraphIds.get(sessionId);
+ const gate = graphId ? snapshotGates.get(graphId) : undefined;
+ if (gate && graphId) {
+ snapshotGates.delete(graphId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const next = graphId ? snapshots.get(graphId) : undefined;
+ if (!next || next.rootSessionId !== sessionId) {
+ throw new Error(`missing graph snapshot for ${sessionId}`);
+ }
  return next;
  },
  inspectOperator: async () => {
@@ -108,7 +177,9 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  listeners.delete(listener);
  };
  },
- stop: async () => undefined,
+ stop: async (sessionId: string) => {
+ stopCalls.push(sessionId);
+ },
  },
  };
 
@@ -119,12 +190,16 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  container,
  root,
  async setSnapshot(next) {
- snapshots.set(next.rootSessionId, next);
+ snapshots.set(next.graphId, next);
+ currentGraphIds.set(next.rootSessionId, next.graphId);
  await act(async () => {
  for (const listener of [...listeners]) listener();
  await Promise.resolve();
  });
  },
+ evict(graphId) {
+ snapshots.delete(graphId);
+ },
  async renderSession(sessionId) {
  await act(async () => {
  root.render(
@@ -138,6 +213,17 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  await Promise.resolve();
  });
  },
+ holdNextEpochList(sessionId) {
+ const gate = deferredReadGate();
+ epochListGates.set(sessionId, gate);
+ return gate;
+ },
+ holdNextSnapshot(graphId) {
+ const gate = deferredReadGate();
+ snapshotGates.set(graphId, gate);
+ return gate;
+ },
+ stopCalls,
  };
 }
 
@@ -160,6 +246,126 @@ async function renderPanel(
 }
 
 describe('AgentGraphPanel dismiss', () => {
+ it('keeps the new session loading when a disposed read settles later', async () => {
+ const sessionA = snapshot({ graphId: 'graph-a', status: 'active' });
+ const sessionB = snapshot({
+ graphId: 'graph-b',
+ status: 'active',
+ rootSessionId: 'session-2',
+ });
+ const harness = installGraphRenderer(sessionA, [sessionB]);
+ const readA = harness.holdNextEpochList('session-1');
+ await harness.renderSession('session-1');
+ await readA.started;
+
+ const readB = harness.holdNextEpochList('session-2');
+ await harness.renderSession('session-2');
+ await readB.started;
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readA.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readB.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Agent Graph/);
+ await act(async () => harness.root.unmount());
+ });
+
+ it('switches to a historical epoch without exposing current-graph controls', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ assert.match(harness.container.textContent ?? '', /Stop graph/);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ const historyRead = harness.holdNextSnapshot('graph-1');
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await historyRead.started;
+ });
+
+ assert.match(harness.container.textContent ?? '', /#1 · History \(read-only\)/);
+ assert.doesNotMatch(harness.container.textContent ?? '', /Stop graph/);
+ assert.equal(harness.container.querySelector('.maka-agent-graph-dismiss'), null);
+ assert.deepEqual(harness.stopCalls, []);
+ await act(async () => {
+ historyRead.release();
+ await Promise.resolve();
+ });
+ await act(async () => harness.root.unmount());
+ });
+
+ it('resumes following the current epoch after the selected history expires', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const combobox = () => harness.container.querySelector('[role="combobox"]')?.textContent ?? '';
+ assert.match(combobox(), /#1 · History \(read-only\)/);
+
+ // The selected epoch leaves the bounded directory while the graph rolls over.
+ harness.evict('graph-1');
+ await harness.setSnapshot(snapshot({ graphId: 'graph-3', status: 'active' }));
+ assert.match(combobox(), /#2 · Current/);
+
+ // Follow restored: the next rollover refreshes the panel instead of
+ // staying pinned on the fallback graph.
+ await harness.setSnapshot(snapshot({ graphId: 'graph-4', status: 'waiting' }));
+ assert.match(combobox(), /#3 · Current/);
+ await act(async () => harness.root.unmount());
+ });
+
  it('shows dismiss only after the graph has settled', async () => {
  const active = await renderPanel(snapshot({ graphId: 'graph-1', status: 'active' }));
  assert.ok(active.container.querySelector('.maka-agent-graph-panel'));

apps/desktop/src/main/__tests__/agent-graph-panel.test.ts

@@ -4,10 +4,33 @@ import { parseHTML } from 'linkedom';
 import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
+import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
 import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
 
 type GraphListener = () => void;
 
+interface DeferredRead {
+ started: Promise<void>;
+ release(): void;
+}
+
+interface DeferredReadGate extends DeferredRead {
+ markStarted(): void;
+ waitForRelease: Promise<void>;
+}
+
+function deferredReadGate(): DeferredReadGate {
+ let markStarted = () => {};
+ let release = () => {};
+ const started = new Promise<void>((resolve) => {
+ markStarted = resolve;
+ });
+ const waitForRelease = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ return { started, markStarted, release, waitForRelease };
+}
+
 const originalGlobals = {
  document: globalThis.document,
  window: globalThis.window,
@@ -59,11 +82,18 @@ function snapshot(
  };
 }
 
-function installGraphRenderer(initial: AgentGraphClientSnapshot): {
+function installGraphRenderer(
+ initial: AgentGraphClientSnapshot,
+ historical: readonly AgentGraphClientSnapshot[] = [],
+): {
  container: Element;
  root: Root;
  setSnapshot(next: AgentGraphClientSnapshot): Promise<void>;
+ evict(graphId: string): void;
  renderSession(sessionId: string): Promise<void>;
+ holdNextEpochList(sessionId: string): DeferredRead;
+ holdNextSnapshot(graphId: string): DeferredRead;
+ stopCalls: string[];
 } {
  const { document, window } = parseHTML('<div id="root"></div>');
  const matchMedia = (media: string) => ({
@@ -88,15 +118,54 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  IS_REACT_ACT_ENVIRONMENT: true,
  });
 
- const snapshots = new Map<string, AgentGraphClientSnapshot>([
- [initial.rootSessionId, initial],
- ]);
+ const snapshots = new Map(
+ [initial, ...historical].map((entry) => [entry.graphId, entry] as const),
+ );
+ const currentGraphIds = new Map<string, string>();
+ for (const entry of [initial, ...historical]) {
+ if (!currentGraphIds.has(entry.rootSessionId)) {
+ currentGraphIds.set(entry.rootSessionId, entry.graphId);
+ }
+ }
  const listeners = new Set<GraphListener>();
+ const epochListGates = new Map<string, DeferredReadGate>();
+ const snapshotGates = new Map<string, DeferredReadGate>();
+ const stopCalls: string[] = [];
  (window as unknown as { maka: unknown }).maka = {
  graphs: {
- getSnapshot: async (sessionId: string) => {
- const next = snapshots.get(sessionId);
- if (!next) throw new Error(`missing graph snapshot for ${sessionId}`);
+ listEpochs: async (sessionId: string) => {
+ const gate = epochListGates.get(sessionId);
+ if (gate) {
+ epochListGates.delete(sessionId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const currentGraphId = currentGraphIds.get(sessionId);
+ const entries = [...snapshots.values()]
+ .filter((entry) => entry.rootSessionId === sessionId)
+ .sort((left, right) => Number(right.graphId === currentGraphId) - Number(left.graphId === currentGraphId));
+ return {
+ epochs: entries.map((entry, index) => ({
+ epoch: entries.length - index,
+ graphId: entry.graphId,
+ createdAt: index + 1,
+ current: currentGraphIds.get(sessionId) === entry.graphId,
+ })),
+ truncated: false,
+ };
+ },
+ getSnapshot: async (sessionId: string, options?: { graphId?: string }) => {
+ const graphId = options?.graphId ?? currentGraphIds.get(sessionId);
+ const gate = graphId ? snapshotGates.get(graphId) : undefined;
+ if (gate && graphId) {
+ snapshotGates.delete(graphId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const next = graphId ? snapshots.get(graphId) : undefined;
+ if (!next || next.rootSessionId !== sessionId) {
+ throw new Error(`missing graph snapshot for ${sessionId}`);
+ }
  return next;
  },
  inspectOperator: async () => {
@@ -108,7 +177,9 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  listeners.delete(listener);
  };
  },
- stop: async () => undefined,
+ stop: async (sessionId: string) => {
+ stopCalls.push(sessionId);
+ },
  },
  };
 
@@ -119,12 +190,16 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  container,
  root,
  async setSnapshot(next) {
- snapshots.set(next.rootSessionId, next);
+ snapshots.set(next.graphId, next);
+ currentGraphIds.set(next.rootSessionId, next.graphId);
  await act(async () => {
  for (const listener of [...listeners]) listener();
  await Promise.resolve();
  });
  },
+ evict(graphId) {
+ snapshots.delete(graphId);
+ },
  async renderSession(sessionId) {
  await act(async () => {
  root.render(
@@ -138,6 +213,17 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  await Promise.resolve();
  });
  },
+ holdNextEpochList(sessionId) {
+ const gate = deferredReadGate();
+ epochListGates.set(sessionId, gate);
+ return gate;
+ },
+ holdNextSnapshot(graphId) {
+ const gate = deferredReadGate();
+ snapshotGates.set(graphId, gate);
+ return gate;
+ },
+ stopCalls,
  };
 }
 
@@ -160,6 +246,126 @@ async function renderPanel(
 }
 
 describe('AgentGraphPanel dismiss', () => {
+ it('keeps the new session loading when a disposed read settles later', async () => {
+ const sessionA = snapshot({ graphId: 'graph-a', status: 'active' });
+ const sessionB = snapshot({
+ graphId: 'graph-b',
+ status: 'active',
+ rootSessionId: 'session-2',
+ });
+ const harness = installGraphRenderer(sessionA, [sessionB]);
+ const readA = harness.holdNextEpochList('session-1');
+ await harness.renderSession('session-1');
+ await readA.started;
+
+ const readB = harness.holdNextEpochList('session-2');
+ await harness.renderSession('session-2');
+ await readB.started;
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readA.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readB.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Agent Graph/);
+ await act(async () => harness.root.unmount());
+ });
+
+ it('switches to a historical epoch without exposing current-graph controls', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ assert.match(harness.container.textContent ?? '', /Stop graph/);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ const historyRead = harness.holdNextSnapshot('graph-1');
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await historyRead.started;
+ });
+
+ assert.match(harness.container.textContent ?? '', /#1 · History \(read-only\)/);
+ assert.doesNotMatch(harness.container.textContent ?? '', /Stop graph/);
+ assert.equal(harness.container.querySelector('.maka-agent-graph-dismiss'), null);
+ assert.deepEqual(harness.stopCalls, []);
+ await act(async () => {
+ historyRead.release();
+ await Promise.resolve();
+ });
+ await act(async () => harness.root.unmount());
+ });
+
+ it('resumes following the current epoch after the selected history expires', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const combobox = () => harness.container.querySelector('[role="combobox"]')?.textContent ?? '';
+ assert.match(combobox(), /#1 · History \(read-only\)/);
+
+ // The selected epoch leaves the bounded directory while the graph rolls over.
+ harness.evict('graph-1');
+ await harness.setSnapshot(snapshot({ graphId: 'graph-3', status: 'active' }));
+ assert.match(combobox(), /#2 · Current/);
+
+ // Follow restored: the next rollover refreshes the panel instead of
+ // staying pinned on the fallback graph.
+ await harness.setSnapshot(snapshot({ graphId: 'graph-4', status: 'waiting' }));
+ assert.match(combobox(), /#3 · Current/);
+ await act(async () => harness.root.unmount());
+ });
+
  it('shows dismiss only after the graph has settled', async () => {
  const active = await renderPanel(snapshot({ graphId: 'graph-1', status: 'active' }));
  assert.ok(active.container.querySelector('.maka-agent-graph-panel'));

apps/desktop/src/main/__tests__/agent-graph-panel.test.ts

@@ -4,10 +4,33 @@ import { parseHTML } from 'linkedom';
 import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
+import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
 import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
 
 type GraphListener = () => void;
 
+interface DeferredRead {
+ started: Promise<void>;
+ release(): void;
+}
+
+interface DeferredReadGate extends DeferredRead {
+ markStarted(): void;
+ waitForRelease: Promise<void>;
+}
+
+function deferredReadGate(): DeferredReadGate {
+ let markStarted = () => {};
+ let release = () => {};
+ const started = new Promise<void>((resolve) => {
+ markStarted = resolve;
+ });
+ const waitForRelease = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ return { started, markStarted, release, waitForRelease };
+}
+
 const originalGlobals = {
  document: globalThis.document,
  window: globalThis.window,
@@ -59,11 +82,18 @@ function snapshot(
  };
 }
 
-function installGraphRenderer(initial: AgentGraphClientSnapshot): {
+function installGraphRenderer(
+ initial: AgentGraphClientSnapshot,
+ historical: readonly AgentGraphClientSnapshot[] = [],
+): {
  container: Element;
  root: Root;
  setSnapshot(next: AgentGraphClientSnapshot): Promise<void>;
+ evict(graphId: string): void;
  renderSession(sessionId: string): Promise<void>;
+ holdNextEpochList(sessionId: string): DeferredRead;
+ holdNextSnapshot(graphId: string): DeferredRead;
+ stopCalls: string[];
 } {
  const { document, window } = parseHTML('<div id="root"></div>');
  const matchMedia = (media: string) => ({
@@ -88,15 +118,54 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  IS_REACT_ACT_ENVIRONMENT: true,
  });
 
- const snapshots = new Map<string, AgentGraphClientSnapshot>([
- [initial.rootSessionId, initial],
- ]);
+ const snapshots = new Map(
+ [initial, ...historical].map((entry) => [entry.graphId, entry] as const),
+ );
+ const currentGraphIds = new Map<string, string>();
+ for (const entry of [initial, ...historical]) {
+ if (!currentGraphIds.has(entry.rootSessionId)) {
+ currentGraphIds.set(entry.rootSessionId, entry.graphId);
+ }
+ }
  const listeners = new Set<GraphListener>();
+ const epochListGates = new Map<string, DeferredReadGate>();
+ const snapshotGates = new Map<string, DeferredReadGate>();
+ const stopCalls: string[] = [];
  (window as unknown as { maka: unknown }).maka = {
  graphs: {
- getSnapshot: async (sessionId: string) => {
- const next = snapshots.get(sessionId);
- if (!next) throw new Error(`missing graph snapshot for ${sessionId}`);
+ listEpochs: async (sessionId: string) => {
+ const gate = epochListGates.get(sessionId);
+ if (gate) {
+ epochListGates.delete(sessionId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const currentGraphId = currentGraphIds.get(sessionId);
+ const entries = [...snapshots.values()]
+ .filter((entry) => entry.rootSessionId === sessionId)
+ .sort((left, right) => Number(right.graphId === currentGraphId) - Number(left.graphId === currentGraphId));
+ return {
+ epochs: entries.map((entry, index) => ({
+ epoch: entries.length - index,
+ graphId: entry.graphId,
+ createdAt: index + 1,
+ current: currentGraphIds.get(sessionId) === entry.graphId,
+ })),
+ truncated: false,
+ };
+ },
+ getSnapshot: async (sessionId: string, options?: { graphId?: string }) => {
+ const graphId = options?.graphId ?? currentGraphIds.get(sessionId);
+ const gate = graphId ? snapshotGates.get(graphId) : undefined;
+ if (gate && graphId) {
+ snapshotGates.delete(graphId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const next = graphId ? snapshots.get(graphId) : undefined;
+ if (!next || next.rootSessionId !== sessionId) {
+ throw new Error(`missing graph snapshot for ${sessionId}`);
+ }
  return next;
  },
  inspectOperator: async () => {
@@ -108,7 +177,9 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  listeners.delete(listener);
  };
  },
- stop: async () => undefined,
+ stop: async (sessionId: string) => {
+ stopCalls.push(sessionId);
+ },
  },
  };
 
@@ -119,12 +190,16 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  container,
  root,
  async setSnapshot(next) {
- snapshots.set(next.rootSessionId, next);
+ snapshots.set(next.graphId, next);
+ currentGraphIds.set(next.rootSessionId, next.graphId);
  await act(async () => {
  for (const listener of [...listeners]) listener();
  await Promise.resolve();
  });
  },
+ evict(graphId) {
+ snapshots.delete(graphId);
+ },
  async renderSession(sessionId) {
  await act(async () => {
  root.render(
@@ -138,6 +213,17 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  await Promise.resolve();
  });
  },
+ holdNextEpochList(sessionId) {
+ const gate = deferredReadGate();
+ epochListGates.set(sessionId, gate);
+ return gate;
+ },
+ holdNextSnapshot(graphId) {
+ const gate = deferredReadGate();
+ snapshotGates.set(graphId, gate);
+ return gate;
+ },
+ stopCalls,
  };
 }
 
@@ -160,6 +246,126 @@ async function renderPanel(
 }
 
 describe('AgentGraphPanel dismiss', () => {
+ it('keeps the new session loading when a disposed read settles later', async () => {
+ const sessionA = snapshot({ graphId: 'graph-a', status: 'active' });
+ const sessionB = snapshot({
+ graphId: 'graph-b',
+ status: 'active',
+ rootSessionId: 'session-2',
+ });
+ const harness = installGraphRenderer(sessionA, [sessionB]);
+ const readA = harness.holdNextEpochList('session-1');
+ await harness.renderSession('session-1');
+ await readA.started;
+
+ const readB = harness.holdNextEpochList('session-2');
+ await harness.renderSession('session-2');
+ await readB.started;
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readA.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readB.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Agent Graph/);
+ await act(async () => harness.root.unmount());
+ });
+
+ it('switches to a historical epoch without exposing current-graph controls', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ assert.match(harness.container.textContent ?? '', /Stop graph/);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ const historyRead = harness.holdNextSnapshot('graph-1');
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await historyRead.started;
+ });
+
+ assert.match(harness.container.textContent ?? '', /#1 · History \(read-only\)/);
+ assert.doesNotMatch(harness.container.textContent ?? '', /Stop graph/);
+ assert.equal(harness.container.querySelector('.maka-agent-graph-dismiss'), null);
+ assert.deepEqual(harness.stopCalls, []);
+ await act(async () => {
+ historyRead.release();
+ await Promise.resolve();
+ });
+ await act(async () => harness.root.unmount());
+ });
+
+ it('resumes following the current epoch after the selected history expires', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const combobox = () => harness.container.querySelector('[role="combobox"]')?.textContent ?? '';
+ assert.match(combobox(), /#1 · History \(read-only\)/);
+
+ // The selected epoch leaves the bounded directory while the graph rolls over.
+ harness.evict('graph-1');
+ await harness.setSnapshot(snapshot({ graphId: 'graph-3', status: 'active' }));
+ assert.match(combobox(), /#2 · Current/);
+
+ // Follow restored: the next rollover refreshes the panel instead of
+ // staying pinned on the fallback graph.
+ await harness.setSnapshot(snapshot({ graphId: 'graph-4', status: 'waiting' }));
+ assert.match(combobox(), /#3 · Current/);
+ await act(async () => harness.root.unmount());
+ });
+
  it('shows dismiss only after the graph has settled', async () => {
  const active = await renderPanel(snapshot({ graphId: 'graph-1', status: 'active' }));
  assert.ok(active.container.querySelector('.maka-agent-graph-panel'));

apps/desktop/src/main/__tests__/agent-graph-panel.test.ts

@@ -4,10 +4,33 @@ import { parseHTML } from 'linkedom';
 import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
+import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
 import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
 
 type GraphListener = () => void;
 
+interface DeferredRead {
+ started: Promise<void>;
+ release(): void;
+}
+
+interface DeferredReadGate extends DeferredRead {
+ markStarted(): void;
+ waitForRelease: Promise<void>;
+}
+
+function deferredReadGate(): DeferredReadGate {
+ let markStarted = () => {};
+ let release = () => {};
+ const started = new Promise<void>((resolve) => {
+ markStarted = resolve;
+ });
+ const waitForRelease = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ return { started, markStarted, release, waitForRelease };
+}
+
 const originalGlobals = {
  document: globalThis.document,
  window: globalThis.window,
@@ -59,11 +82,18 @@ function snapshot(
  };
 }
 
-function installGraphRenderer(initial: AgentGraphClientSnapshot): {
+function installGraphRenderer(
+ initial: AgentGraphClientSnapshot,
+ historical: readonly AgentGraphClientSnapshot[] = [],
+): {
  container: Element;
  root: Root;
  setSnapshot(next: AgentGraphClientSnapshot): Promise<void>;
+ evict(graphId: string): void;
  renderSession(sessionId: string): Promise<void>;
+ holdNextEpochList(sessionId: string): DeferredRead;
+ holdNextSnapshot(graphId: string): DeferredRead;
+ stopCalls: string[];
 } {
  const { document, window } = parseHTML('<div id="root"></div>');
  const matchMedia = (media: string) => ({
@@ -88,15 +118,54 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  IS_REACT_ACT_ENVIRONMENT: true,
  });
 
- const snapshots = new Map<string, AgentGraphClientSnapshot>([
- [initial.rootSessionId, initial],
- ]);
+ const snapshots = new Map(
+ [initial, ...historical].map((entry) => [entry.graphId, entry] as const),
+ );
+ const currentGraphIds = new Map<string, string>();
+ for (const entry of [initial, ...historical]) {
+ if (!currentGraphIds.has(entry.rootSessionId)) {
+ currentGraphIds.set(entry.rootSessionId, entry.graphId);
+ }
+ }
  const listeners = new Set<GraphListener>();
+ const epochListGates = new Map<string, DeferredReadGate>();
+ const snapshotGates = new Map<string, DeferredReadGate>();
+ const stopCalls: string[] = [];
  (window as unknown as { maka: unknown }).maka = {
  graphs: {
- getSnapshot: async (sessionId: string) => {
- const next = snapshots.get(sessionId);
- if (!next) throw new Error(`missing graph snapshot for ${sessionId}`);
+ listEpochs: async (sessionId: string) => {
+ const gate = epochListGates.get(sessionId);
+ if (gate) {
+ epochListGates.delete(sessionId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const currentGraphId = currentGraphIds.get(sessionId);
+ const entries = [...snapshots.values()]
+ .filter((entry) => entry.rootSessionId === sessionId)
+ .sort((left, right) => Number(right.graphId === currentGraphId) - Number(left.graphId === currentGraphId));
+ return {
+ epochs: entries.map((entry, index) => ({
+ epoch: entries.length - index,
+ graphId: entry.graphId,
+ createdAt: index + 1,
+ current: currentGraphIds.get(sessionId) === entry.graphId,
+ })),
+ truncated: false,
+ };
+ },
+ getSnapshot: async (sessionId: string, options?: { graphId?: string }) => {
+ const graphId = options?.graphId ?? currentGraphIds.get(sessionId);
+ const gate = graphId ? snapshotGates.get(graphId) : undefined;
+ if (gate && graphId) {
+ snapshotGates.delete(graphId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const next = graphId ? snapshots.get(graphId) : undefined;
+ if (!next || next.rootSessionId !== sessionId) {
+ throw new Error(`missing graph snapshot for ${sessionId}`);
+ }
  return next;
  },
  inspectOperator: async () => {
@@ -108,7 +177,9 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  listeners.delete(listener);
  };
  },
- stop: async () => undefined,
+ stop: async (sessionId: string) => {
+ stopCalls.push(sessionId);
+ },
  },
  };
 
@@ -119,12 +190,16 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  container,
  root,
  async setSnapshot(next) {
- snapshots.set(next.rootSessionId, next);
+ snapshots.set(next.graphId, next);
+ currentGraphIds.set(next.rootSessionId, next.graphId);
  await act(async () => {
  for (const listener of [...listeners]) listener();
  await Promise.resolve();
  });
  },
+ evict(graphId) {
+ snapshots.delete(graphId);
+ },
  async renderSession(sessionId) {
  await act(async () => {
  root.render(
@@ -138,6 +213,17 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  await Promise.resolve();
  });
  },
+ holdNextEpochList(sessionId) {
+ const gate = deferredReadGate();
+ epochListGates.set(sessionId, gate);
+ return gate;
+ },
+ holdNextSnapshot(graphId) {
+ const gate = deferredReadGate();
+ snapshotGates.set(graphId, gate);
+ return gate;
+ },
+ stopCalls,
  };
 }
 
@@ -160,6 +246,126 @@ async function renderPanel(
 }
 
 describe('AgentGraphPanel dismiss', () => {
+ it('keeps the new session loading when a disposed read settles later', async () => {
+ const sessionA = snapshot({ graphId: 'graph-a', status: 'active' });
+ const sessionB = snapshot({
+ graphId: 'graph-b',
+ status: 'active',
+ rootSessionId: 'session-2',
+ });
+ const harness = installGraphRenderer(sessionA, [sessionB]);
+ const readA = harness.holdNextEpochList('session-1');
+ await harness.renderSession('session-1');
+ await readA.started;
+
+ const readB = harness.holdNextEpochList('session-2');
+ await harness.renderSession('session-2');
+ await readB.started;
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readA.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readB.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Agent Graph/);
+ await act(async () => harness.root.unmount());
+ });
+
+ it('switches to a historical epoch without exposing current-graph controls', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ assert.match(harness.container.textContent ?? '', /Stop graph/);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ const historyRead = harness.holdNextSnapshot('graph-1');
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await historyRead.started;
+ });
+
+ assert.match(harness.container.textContent ?? '', /#1 · History \(read-only\)/);
+ assert.doesNotMatch(harness.container.textContent ?? '', /Stop graph/);
+ assert.equal(harness.container.querySelector('.maka-agent-graph-dismiss'), null);
+ assert.deepEqual(harness.stopCalls, []);
+ await act(async () => {
+ historyRead.release();
+ await Promise.resolve();
+ });
+ await act(async () => harness.root.unmount());
+ });
+
+ it('resumes following the current epoch after the selected history expires', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const combobox = () => harness.container.querySelector('[role="combobox"]')?.textContent ?? '';
+ assert.match(combobox(), /#1 · History \(read-only\)/);
+
+ // The selected epoch leaves the bounded directory while the graph rolls over.
+ harness.evict('graph-1');
+ await harness.setSnapshot(snapshot({ graphId: 'graph-3', status: 'active' }));
+ assert.match(combobox(), /#2 · Current/);
+
+ // Follow restored: the next rollover refreshes the panel instead of
+ // staying pinned on the fallback graph.
+ await harness.setSnapshot(snapshot({ graphId: 'graph-4', status: 'waiting' }));
+ assert.match(combobox(), /#3 · Current/);
+ await act(async () => harness.root.unmount());
+ });
+
  it('shows dismiss only after the graph has settled', async () => {
  const active = await renderPanel(snapshot({ graphId: 'graph-1', status: 'active' }));
  assert.ok(active.container.querySelector('.maka-agent-graph-panel'));

apps/desktop/src/main/__tests__/agent-graph-panel.test.ts

@@ -4,10 +4,33 @@ import { parseHTML } from 'linkedom';
 import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
+import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
 import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
 
 type GraphListener = () => void;
 
+interface DeferredRead {
+ started: Promise<void>;
+ release(): void;
+}
+
+interface DeferredReadGate extends DeferredRead {
+ markStarted(): void;
+ waitForRelease: Promise<void>;
+}
+
+function deferredReadGate(): DeferredReadGate {
+ let markStarted = () => {};
+ let release = () => {};
+ const started = new Promise<void>((resolve) => {
+ markStarted = resolve;
+ });
+ const waitForRelease = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ return { started, markStarted, release, waitForRelease };
+}
+
 const originalGlobals = {
  document: globalThis.document,
  window: globalThis.window,
@@ -59,11 +82,18 @@ function snapshot(
  };
 }
 
-function installGraphRenderer(initial: AgentGraphClientSnapshot): {
+function installGraphRenderer(
+ initial: AgentGraphClientSnapshot,
+ historical: readonly AgentGraphClientSnapshot[] = [],
+): {
  container: Element;
  root: Root;
  setSnapshot(next: AgentGraphClientSnapshot): Promise<void>;
+ evict(graphId: string): void;
  renderSession(sessionId: string): Promise<void>;
+ holdNextEpochList(sessionId: string): DeferredRead;
+ holdNextSnapshot(graphId: string): DeferredRead;
+ stopCalls: string[];
 } {
  const { document, window } = parseHTML('<div id="root"></div>');
  const matchMedia = (media: string) => ({
@@ -88,15 +118,54 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  IS_REACT_ACT_ENVIRONMENT: true,
  });
 
- const snapshots = new Map<string, AgentGraphClientSnapshot>([
- [initial.rootSessionId, initial],
- ]);
+ const snapshots = new Map(
+ [initial, ...historical].map((entry) => [entry.graphId, entry] as const),
+ );
+ const currentGraphIds = new Map<string, string>();
+ for (const entry of [initial, ...historical]) {
+ if (!currentGraphIds.has(entry.rootSessionId)) {
+ currentGraphIds.set(entry.rootSessionId, entry.graphId);
+ }
+ }
  const listeners = new Set<GraphListener>();
+ const epochListGates = new Map<string, DeferredReadGate>();
+ const snapshotGates = new Map<string, DeferredReadGate>();
+ const stopCalls: string[] = [];
  (window as unknown as { maka: unknown }).maka = {
  graphs: {
- getSnapshot: async (sessionId: string) => {
- const next = snapshots.get(sessionId);
- if (!next) throw new Error(`missing graph snapshot for ${sessionId}`);
+ listEpochs: async (sessionId: string) => {
+ const gate = epochListGates.get(sessionId);
+ if (gate) {
+ epochListGates.delete(sessionId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const currentGraphId = currentGraphIds.get(sessionId);
+ const entries = [...snapshots.values()]
+ .filter((entry) => entry.rootSessionId === sessionId)
+ .sort((left, right) => Number(right.graphId === currentGraphId) - Number(left.graphId === currentGraphId));
+ return {
+ epochs: entries.map((entry, index) => ({
+ epoch: entries.length - index,
+ graphId: entry.graphId,
+ createdAt: index + 1,
+ current: currentGraphIds.get(sessionId) === entry.graphId,
+ })),
+ truncated: false,
+ };
+ },
+ getSnapshot: async (sessionId: string, options?: { graphId?: string }) => {
+ const graphId = options?.graphId ?? currentGraphIds.get(sessionId);
+ const gate = graphId ? snapshotGates.get(graphId) : undefined;
+ if (gate && graphId) {
+ snapshotGates.delete(graphId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const next = graphId ? snapshots.get(graphId) : undefined;
+ if (!next || next.rootSessionId !== sessionId) {
+ throw new Error(`missing graph snapshot for ${sessionId}`);
+ }
  return next;
  },
  inspectOperator: async () => {
@@ -108,7 +177,9 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  listeners.delete(listener);
  };
  },
- stop: async () => undefined,
+ stop: async (sessionId: string) => {
+ stopCalls.push(sessionId);
+ },
  },
  };
 
@@ -119,12 +190,16 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  container,
  root,
  async setSnapshot(next) {
- snapshots.set(next.rootSessionId, next);
+ snapshots.set(next.graphId, next);
+ currentGraphIds.set(next.rootSessionId, next.graphId);
  await act(async () => {
  for (const listener of [...listeners]) listener();
  await Promise.resolve();
  });
  },
+ evict(graphId) {
+ snapshots.delete(graphId);
+ },
  async renderSession(sessionId) {
  await act(async () => {
  root.render(
@@ -138,6 +213,17 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  await Promise.resolve();
  });
  },
+ holdNextEpochList(sessionId) {
+ const gate = deferredReadGate();
+ epochListGates.set(sessionId, gate);
+ return gate;
+ },
+ holdNextSnapshot(graphId) {
+ const gate = deferredReadGate();
+ snapshotGates.set(graphId, gate);
+ return gate;
+ },
+ stopCalls,
  };
 }
 
@@ -160,6 +246,126 @@ async function renderPanel(
 }
 
 describe('AgentGraphPanel dismiss', () => {
+ it('keeps the new session loading when a disposed read settles later', async () => {
+ const sessionA = snapshot({ graphId: 'graph-a', status: 'active' });
+ const sessionB = snapshot({
+ graphId: 'graph-b',
+ status: 'active',
+ rootSessionId: 'session-2',
+ });
+ const harness = installGraphRenderer(sessionA, [sessionB]);
+ const readA = harness.holdNextEpochList('session-1');
+ await harness.renderSession('session-1');
+ await readA.started;
+
+ const readB = harness.holdNextEpochList('session-2');
+ await harness.renderSession('session-2');
+ await readB.started;
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readA.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readB.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Agent Graph/);
+ await act(async () => harness.root.unmount());
+ });
+
+ it('switches to a historical epoch without exposing current-graph controls', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ assert.match(harness.container.textContent ?? '', /Stop graph/);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ const historyRead = harness.holdNextSnapshot('graph-1');
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await historyRead.started;
+ });
+
+ assert.match(harness.container.textContent ?? '', /#1 · History \(read-only\)/);
+ assert.doesNotMatch(harness.container.textContent ?? '', /Stop graph/);
+ assert.equal(harness.container.querySelector('.maka-agent-graph-dismiss'), null);
+ assert.deepEqual(harness.stopCalls, []);
+ await act(async () => {
+ historyRead.release();
+ await Promise.resolve();
+ });
+ await act(async () => harness.root.unmount());
+ });
+
+ it('resumes following the current epoch after the selected history expires', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const combobox = () => harness.container.querySelector('[role="combobox"]')?.textContent ?? '';
+ assert.match(combobox(), /#1 · History \(read-only\)/);
+
+ // The selected epoch leaves the bounded directory while the graph rolls over.
+ harness.evict('graph-1');
+ await harness.setSnapshot(snapshot({ graphId: 'graph-3', status: 'active' }));
+ assert.match(combobox(), /#2 · Current/);
+
+ // Follow restored: the next rollover refreshes the panel instead of
+ // staying pinned on the fallback graph.
+ await harness.setSnapshot(snapshot({ graphId: 'graph-4', status: 'waiting' }));
+ assert.match(combobox(), /#3 · Current/);
+ await act(async () => harness.root.unmount());
+ });
+
  it('shows dismiss only after the graph has settled', async () => {
  const active = await renderPanel(snapshot({ graphId: 'graph-1', status: 'active' }));
  assert.ok(active.container.querySelector('.maka-agent-graph-panel'));

apps/desktop/src/main/__tests__/agent-graph-panel.test.ts

@@ -4,10 +4,33 @@ import { parseHTML } from 'linkedom';
 import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
+import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
 import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
 
 type GraphListener = () => void;
 
+interface DeferredRead {
+ started: Promise<void>;
+ release(): void;
+}
+
+interface DeferredReadGate extends DeferredRead {
+ markStarted(): void;
+ waitForRelease: Promise<void>;
+}
+
+function deferredReadGate(): DeferredReadGate {
+ let markStarted = () => {};
+ let release = () => {};
+ const started = new Promise<void>((resolve) => {
+ markStarted = resolve;
+ });
+ const waitForRelease = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ return { started, markStarted, release, waitForRelease };
+}
+
 const originalGlobals = {
  document: globalThis.document,
  window: globalThis.window,
@@ -59,11 +82,18 @@ function snapshot(
  };
 }
 
-function installGraphRenderer(initial: AgentGraphClientSnapshot): {
+function installGraphRenderer(
+ initial: AgentGraphClientSnapshot,
+ historical: readonly AgentGraphClientSnapshot[] = [],
+): {
  container: Element;
  root: Root;
  setSnapshot(next: AgentGraphClientSnapshot): Promise<void>;
+ evict(graphId: string): void;
  renderSession(sessionId: string): Promise<void>;
+ holdNextEpochList(sessionId: string): DeferredRead;
+ holdNextSnapshot(graphId: string): DeferredRead;
+ stopCalls: string[];
 } {
  const { document, window } = parseHTML('<div id="root"></div>');
  const matchMedia = (media: string) => ({
@@ -88,15 +118,54 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  IS_REACT_ACT_ENVIRONMENT: true,
  });
 
- const snapshots = new Map<string, AgentGraphClientSnapshot>([
- [initial.rootSessionId, initial],
- ]);
+ const snapshots = new Map(
+ [initial, ...historical].map((entry) => [entry.graphId, entry] as const),
+ );
+ const currentGraphIds = new Map<string, string>();
+ for (const entry of [initial, ...historical]) {
+ if (!currentGraphIds.has(entry.rootSessionId)) {
+ currentGraphIds.set(entry.rootSessionId, entry.graphId);
+ }
+ }
  const listeners = new Set<GraphListener>();
+ const epochListGates = new Map<string, DeferredReadGate>();
+ const snapshotGates = new Map<string, DeferredReadGate>();
+ const stopCalls: string[] = [];
  (window as unknown as { maka: unknown }).maka = {
  graphs: {
- getSnapshot: async (sessionId: string) => {
- const next = snapshots.get(sessionId);
- if (!next) throw new Error(`missing graph snapshot for ${sessionId}`);
+ listEpochs: async (sessionId: string) => {
+ const gate = epochListGates.get(sessionId);
+ if (gate) {
+ epochListGates.delete(sessionId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const currentGraphId = currentGraphIds.get(sessionId);
+ const entries = [...snapshots.values()]
+ .filter((entry) => entry.rootSessionId === sessionId)
+ .sort((left, right) => Number(right.graphId === currentGraphId) - Number(left.graphId === currentGraphId));
+ return {
+ epochs: entries.map((entry, index) => ({
+ epoch: entries.length - index,
+ graphId: entry.graphId,
+ createdAt: index + 1,
+ current: currentGraphIds.get(sessionId) === entry.graphId,
+ })),
+ truncated: false,
+ };
+ },
+ getSnapshot: async (sessionId: string, options?: { graphId?: string }) => {
+ const graphId = options?.graphId ?? currentGraphIds.get(sessionId);
+ const gate = graphId ? snapshotGates.get(graphId) : undefined;
+ if (gate && graphId) {
+ snapshotGates.delete(graphId);
+ gate.markStarted();
+ await gate.waitForRelease;
+ }
+ const next = graphId ? snapshots.get(graphId) : undefined;
+ if (!next || next.rootSessionId !== sessionId) {
+ throw new Error(`missing graph snapshot for ${sessionId}`);
+ }
  return next;
  },
  inspectOperator: async () => {
@@ -108,7 +177,9 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  listeners.delete(listener);
  };
  },
- stop: async () => undefined,
+ stop: async (sessionId: string) => {
+ stopCalls.push(sessionId);
+ },
  },
  };
 
@@ -119,12 +190,16 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  container,
  root,
  async setSnapshot(next) {
- snapshots.set(next.rootSessionId, next);
+ snapshots.set(next.graphId, next);
+ currentGraphIds.set(next.rootSessionId, next.graphId);
  await act(async () => {
  for (const listener of [...listeners]) listener();
  await Promise.resolve();
  });
  },
+ evict(graphId) {
+ snapshots.delete(graphId);
+ },
  async renderSession(sessionId) {
  await act(async () => {
  root.render(
@@ -138,6 +213,17 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
  await Promise.resolve();
  });
  },
+ holdNextEpochList(sessionId) {
+ const gate = deferredReadGate();
+ epochListGates.set(sessionId, gate);
+ return gate;
+ },
+ holdNextSnapshot(graphId) {
+ const gate = deferredReadGate();
+ snapshotGates.set(graphId, gate);
+ return gate;
+ },
+ stopCalls,
  };
 }
 
@@ -160,6 +246,126 @@ async function renderPanel(
 }
 
 describe('AgentGraphPanel dismiss', () => {
+ it('keeps the new session loading when a disposed read settles later', async () => {
+ const sessionA = snapshot({ graphId: 'graph-a', status: 'active' });
+ const sessionB = snapshot({
+ graphId: 'graph-b',
+ status: 'active',
+ rootSessionId: 'session-2',
+ });
+ const harness = installGraphRenderer(sessionA, [sessionB]);
+ const readA = harness.holdNextEpochList('session-1');
+ await harness.renderSession('session-1');
+ await readA.started;
+
+ const readB = harness.holdNextEpochList('session-2');
+ await harness.renderSession('session-2');
+ await readB.started;
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readA.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+ await act(async () => {
+ readB.release();
+ await Promise.resolve();
+ });
+ assert.match(harness.container.textContent ?? '', /Agent Graph/);
+ await act(async () => harness.root.unmount());
+ });
+
+ it('switches to a historical epoch without exposing current-graph controls', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ assert.match(harness.container.textContent ?? '', /Stop graph/);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ const historyRead = harness.holdNextSnapshot('graph-1');
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await historyRead.started;
+ });
+
+ assert.match(harness.container.textContent ?? '', /#1 · History \(read-only\)/);
+ assert.doesNotMatch(harness.container.textContent ?? '', /Stop graph/);
+ assert.equal(harness.container.querySelector('.maka-agent-graph-dismiss'), null);
+ assert.deepEqual(harness.stopCalls, []);
+ await act(async () => {
+ historyRead.release();
+ await Promise.resolve();
+ });
+ await act(async () => harness.root.unmount());
+ });
+
+ it('resumes following the current epoch after the selected history expires', async () => {
+ const current = snapshot({ graphId: 'graph-2', status: 'active' });
+ const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+ const harness = installGraphRenderer(current, [previous]);
+ await act(async () => {
+ harness.root.render(
+ createElement(AgentGraphPanel, {
+ rootSessionId: 'session-1',
+ enabled: true,
+ locale: 'en',
+ onOpenSession: () => undefined,
+ }),
+ );
+ await Promise.resolve();
+ });
+
+ const selector = harness.container.querySelector('[role="combobox"]');
+ assert.ok(selector);
+ await act(async () => {
+ (selector as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+ option.textContent?.includes('History'),
+ );
+ assert.ok(historyOption);
+ await act(async () => {
+ (historyOption as HTMLElement).click();
+ await Promise.resolve();
+ });
+ const combobox = () => harness.container.querySelector('[role="combobox"]')?.textContent ?? '';
+ assert.match(combobox(), /#1 · History \(read-only\)/);
+
+ // The selected epoch leaves the bounded directory while the graph rolls over.
+ harness.evict('graph-1');
+ await harness.setSnapshot(snapshot({ graphId: 'graph-3', status: 'active' }));
+ assert.match(combobox(), /#2 · Current/);
+
+ // Follow restored: the next rollover refreshes the panel instead of
+ // staying pinned on the fallback graph.
+ await harness.setSnapshot(snapshot({ graphId: 'graph-4', status: 'waiting' }));
+ assert.match(combobox(), /#3 · Current/);
+ await act(async () => harness.root.unmount());
+ });
+
  it('shows dismiss only after the graph has settled', async () => {
  const active = await renderPanel(snapshot({ graphId: 'graph-1', status: 'active' }));
  assert.ok(active.container.querySelector('.maka-agent-graph-panel'));