@blackbelt-technology/pi-agent-dashboard 0.4.1 → 0.4.2

package/packages/server/src/__tests__/session-order-reboot.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Tests for the user-resume-intent gate that protects sessionOrder from
+ * spurious mutation during bridge auto-reattach on dashboard reboot.
+ *
+ * The actual gate lives inside the `sessionManager.onChange` closure in
+ * `server.ts`. To keep this test focused and avoid spinning up a full
+ * server, we replicate the exact algorithm the closure runs and assert
+ * the four scenarios from `specs/session-filtering/spec.md`.
+ *
+ * The algorithm tested here is intentionally a verbatim copy of the
+ * server.ts implementation \u2014 if one drifts from the other, both this
+ * test and the production code are out of sync.
+ *
+ * See change: preserve-session-order-on-reboot.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { createPendingResumeIntentRegistry } from "../pending-resume-intent-registry.js";
+import { createSessionOrderManager } from "../session-order-manager.js";
+import type { PreferencesStore } from "../preferences-store.js";
+
+// In-memory PreferencesStore mock matching the slice of the interface
+// `sessionOrderManager` consumes.
+function makePrefs(): PreferencesStore {
+  let order: Record<string, string[]> = {};
+  return {
+    getSessionOrder: () => order,
+    setSessionOrder: (o) => { order = o; },
+    getPinnedDirectories: () => [],
+    setPinnedDirectories: () => {},
+    pinDirectory: () => {},
+    unpinDirectory: () => {},
+    reorderPinnedDirs: () => {},
+    flush: () => {},
+    dispose: () => {},
+  };
+}
+
+interface BroadcastEvent {
+  type: "sessions_reordered";
+  cwd: string;
+  sessionIds: string[];
+}
+
+/**
+ * Executes the exact ended\u2192alive branch from `server.ts`'s onChange hook
+ * against the supplied state. Returns the broadcast that would have been
+ * emitted (or null when the branch returned early).
+ *
+ * Mirrors the post-`top-of-tier-on-status-change` semantics: user-intent
+ * resume calls `moveToFront` (always brings the id to the top) instead
+ * of insert-if-absent.
+ */
+function endedToAlive(
+  sessionId: string,
+  cwd: string,
+  endedSessionIds: Set<string>,
+  pendingResumeIntents: ReturnType<typeof createPendingResumeIntentRegistry>,
+  sessionOrderManager: ReturnType<typeof createSessionOrderManager>,
+): BroadcastEvent | null {
+  // Mirror server.ts:onChange ended\u2192alive branch verbatim.
+  // Post-`differentiate-resume-intent-by-trigger`: 3-way switch on the
+  // consumed intent ("front" | "keep" | null).
+  endedSessionIds.delete(sessionId);
+  const intent = pendingResumeIntents.consume(sessionId);
+  if (intent === null) return null;
+  if (intent === "keep") return null; // dropped slot wins; no mutation, no broadcast
+  sessionOrderManager.moveToFront(cwd, sessionId);
+  const next = sessionOrderManager.getOrder(cwd) ?? [];
+  return { type: "sessions_reordered", cwd, sessionIds: next };
+}
+
+describe("ended\u2192alive sessionOrder gate", () => {
+  let endedSessionIds: Set<string>;
+  let pendingResumeIntents: ReturnType<typeof createPendingResumeIntentRegistry>;
+  let sessionOrderManager: ReturnType<typeof createSessionOrderManager>;
+  const cwd = "/project";
+
+  beforeEach(() => {
+    endedSessionIds = new Set();
+    pendingResumeIntents = createPendingResumeIntentRegistry();
+    sessionOrderManager = createSessionOrderManager(makePrefs());
+  });
+
+  it("user Resume click prepends id and emits broadcast", () => {
+    // Pre-state: existing alive order [B, A, C], session X is ended.
+    sessionOrderManager.insert(cwd, "C");
+    sessionOrderManager.insert(cwd, "A");
+    sessionOrderManager.insert(cwd, "B");
+    endedSessionIds.add("X");
+
+    // User-initiated resume tags the intent before spawn.
+    pendingResumeIntents.record("X", "front");
+
+    const broadcast = endedToAlive("X", cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+
+    expect(broadcast).not.toBeNull();
+    expect(broadcast!.sessionIds[0]).toBe("X"); // prepended
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["X", "B", "A", "C"]);
+  });
+
+  it("drag-to-resume preserves dropped slot (intent: \"keep\")", () => {
+    // Pre-state: alive [A, C], ended id "B" was just dragged into slot 1
+    // via reorder_sessions which writes the order BEFORE resume_session
+    // fires.
+    //
+    // Post change `differentiate-resume-intent-by-trigger`, drag-to-resume
+    // tags `keep` so the dropped slot survives the resume round-trip.
+    sessionOrderManager.reorder(cwd, ["A", "B", "C"]);
+    endedSessionIds.add("B");
+
+    // resume_session handler with placement: "keep" tags accordingly.
+    pendingResumeIntents.record("B", "keep");
+
+    const broadcast = endedToAlive("B", cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+
+    // No broadcast — the earlier reorder_sessions already broadcast,
+    // and the order didn't change here.
+    expect(broadcast).toBeNull();
+    // B stays at the dropped slot.
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["A", "B", "C"]);
+  });
+
+  it("button resume after drag (last-write-wins) moves id to front", () => {
+    // User drags X into the middle (tags "keep"), then before the bridge
+    // re-registers, clicks Resume on X (tags "front"). Last-write-wins:
+    // X surfaces at the top.
+    sessionOrderManager.reorder(cwd, ["A", "X", "B"]);
+    endedSessionIds.add("X");
+
+    pendingResumeIntents.record("X", "keep");
+    pendingResumeIntents.record("X", "front");
+
+    const broadcast = endedToAlive("X", cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+
+    expect(broadcast).not.toBeNull();
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["X", "A", "B"]);
+  });
+
+  it("bridge auto-reattach on reboot leaves order untouched and emits no broadcast", () => {
+    // Pre-state: user had reordered the alive tier to [B, A, C]; B was
+    // running, dashboard rebooted, scan classified all as ended, but B's
+    // pi process was still alive and just reattached.
+    sessionOrderManager.reorder(cwd, ["B", "A", "C"]);
+    endedSessionIds.add("B");
+
+    // No record() call \u2014 nothing tagged the intent.
+    const broadcast = endedToAlive("B", cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+
+    expect(broadcast).toBeNull();
+    // Order is preserved exactly.
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["B", "A", "C"]);
+    // endedSessionIds was still cleared so the next alive\u2192ended fires.
+    expect(endedSessionIds.has("B")).toBe(false);
+  });
+
+  it("multiple bridge reattaches on reboot emit zero broadcasts", () => {
+    sessionOrderManager.reorder(cwd, ["A", "B", "C", "D", "E"]);
+    for (const id of ["A", "B", "C", "D", "E"]) endedSessionIds.add(id);
+
+    const broadcasts: BroadcastEvent[] = [];
+    for (const id of ["A", "B", "C", "D", "E"]) {
+      const b = endedToAlive(id, cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+      if (b) broadcasts.push(b);
+    }
+
+    expect(broadcasts).toEqual([]);
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["A", "B", "C", "D", "E"]);
+  });
+
+  it("stale intent is discarded; reattach classified as non-user", () => {
+    let nowMs = 1_000_000;
+    const clock = () => nowMs;
+    const r = createPendingResumeIntentRegistry({ ttlMs: 100, now: clock });
+
+    sessionOrderManager.reorder(cwd, ["A", "B", "C"]);
+    endedSessionIds.add("X");
+
+    r.record("X", "front"); // user clicked Resume but spawn failed
+    nowMs += 200; // 200 ms later, well past the 100 ms TTL
+
+    // Now a legitimate bridge reattach happens for the same id.
+    const broadcast = endedToAlive("X", cwd, endedSessionIds, r, sessionOrderManager);
+
+    expect(broadcast).toBeNull();
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["A", "B", "C"]);
+  });
+
+  it("intent is single-use \u2014 a second reattach after the same record() is treated as auto", () => {
+    // Edge case: bridge sends two session_register messages back-to-back
+    // (e.g. a bridge reload mid-resume). First consume() wins; second
+    // sees no intent.
+    sessionOrderManager.insert(cwd, "A");
+    endedSessionIds.add("X");
+
+    pendingResumeIntents.record("X", "front");
+
+    const first = endedToAlive("X", cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+    expect(first).not.toBeNull();
+    expect(first!.sessionIds[0]).toBe("X");
+
+    // Simulate a second transition for the same id.
+    endedSessionIds.add("X");
+    const second = endedToAlive("X", cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+
+    expect(second).toBeNull();
+    // X is still in the order from the first call \u2014 no further mutation.
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["X", "A"]);
+  });
+
+  it("end → resume → end → resume cycle always lands id at index 0", () => {
+    // Regression for `top-of-tier-on-status-change`: pre-fix the
+    // ended→alive branch used insert-if-absent, so on the second resume
+    // the id was still in the order list and stayed at its previous
+    // position. With moveToFront, every user-intent resume re-prepends.
+    sessionOrderManager.reorder(cwd, ["A", "B", "X", "C"]);
+
+    // Cycle 1: X ends, X resumes.
+    sessionOrderManager.remove(cwd, "X");
+    endedSessionIds.add("X");
+    pendingResumeIntents.record("X", "front");
+    const r1 = endedToAlive("X", cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+    expect(r1).not.toBeNull();
+    expect(sessionOrderManager.getOrder(cwd)[0]).toBe("X");
+
+    // Cycle 2: X ends again, X resumes. With insert-if-absent this
+    // would no-op (X is already in the list); with moveToFront X jumps
+    // to the top regardless.
+    sessionOrderManager.remove(cwd, "X");
+    endedSessionIds.add("X");
+    pendingResumeIntents.record("X", "front");
+    const r2 = endedToAlive("X", cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+    expect(r2).not.toBeNull();
+    expect(sessionOrderManager.getOrder(cwd)[0]).toBe("X");
+
+    // Cycle 3.
+    sessionOrderManager.remove(cwd, "X");
+    endedSessionIds.add("X");
+    pendingResumeIntents.record("X", "front");
+    endedToAlive("X", cwd, endedSessionIds, pendingResumeIntents, sessionOrderManager);
+    expect(sessionOrderManager.getOrder(cwd)[0]).toBe("X");
+  });
+});

package/packages/server/src/__tests__/session-scanner.test.ts

@@ -184,6 +184,50 @@ describe("session-scanner", () => {
     expect(meta.cwd).toBe("/test");
   });
 
+  it("should preserve persisted contextWindow over inferred stats value when model unchanged", () => {
+    // Regression: pi's JSONL has no turn_end/contextUsage events, so
+    // extractSessionStats falls back to inferContextWindow(model) which
+    // hardcodes Claude → 200_000. The persisted .meta.json value (written
+    // from a live turn_end carrying e.g. 1_000_000 for Sonnet 1M) must win.
+    const dir = createSessionDir("--test-cwd--");
+    const sf = createJsonl(dir, "2026-03-30T21-39-43-034Z_ctx-id.jsonl", { id: "ctx-id", cwd: "/ctx" });
+
+    writeSessionMeta(sf, {
+      cwd: "/ctx",
+      model: "anthropic/claude-sonnet-4-20250514",
+      contextWindow: 1_000_000, // truth from a live turn_end
+      cachedAt: 1000, // stale — forces re-extract
+    });
+    fs.utimesSync(sf, new Date(), new Date());
+
+    const result = scanAllSessions(tmpDir);
+    expect(result.sessions[0].contextWindow).toBe(1_000_000);
+
+    // Should also persist the preserved value, not the inferred 200k.
+    const meta = JSON.parse(fs.readFileSync(metaPath(sf), "utf-8"));
+    expect(meta.contextWindow).toBe(1_000_000);
+  });
+
+  it("should adopt inferred contextWindow when model changes", () => {
+    // If the user switched models, the persisted contextWindow no longer
+    // applies — fall back to whatever stats reports for the new model.
+    const dir = createSessionDir("--test-cwd--");
+    const sf = createJsonl(dir, "2026-03-30T21-39-43-034Z_chg-id.jsonl", { id: "chg-id", cwd: "/chg" });
+
+    writeSessionMeta(sf, {
+      cwd: "/chg",
+      model: "openai/gpt-4o", // different model from the mock's anthropic/claude-...
+      contextWindow: 128_000,
+      cachedAt: 1000,
+    });
+    fs.utimesSync(sf, new Date(), new Date());
+
+    const result = scanAllSessions(tmpDir);
+    // Mock returns model=anthropic/claude-..., contextWindow=200000 → adopt it
+    expect(result.sessions[0].model).toBe("anthropic/claude-sonnet-4-20250514");
+    expect(result.sessions[0].contextWindow).toBe(200_000);
+  });
+
   it("should set hidden from meta", () => {
     const dir = createSessionDir("--test-cwd--");
     const sf = createJsonl(dir, "2026-03-30T21-39-43-034Z_hidden-id.jsonl", { id: "hidden-id", cwd: "/test" });

package/packages/server/src/__tests__/subscription-handler.test.ts

@@ -135,6 +135,46 @@ describe("handleSubscribe — stale lastSeq detection", () => {
     expect(clearReplaying).toHaveBeenCalledWith(ctx.ws, "s1", 3);
   });
 
+  it("forwards session.contextWindow into directoryService.loadSessionEvents on lazy load", async () => {
+    // Regression: ended sessions opened from disk must replay with the
+    // persisted contextWindow (e.g. 1M Sonnet beta) instead of the legacy
+    // 200k Claude inference. The wiring lives in subscription-handler:160 —
+    // this test pins that loadSessionEvents is invoked with session.contextWindow
+    // as its 3rd argument so future refactors cannot silently drop it.
+    // See change: fix-context-window-reload.
+    const loadSessionEvents = vi.fn(async () => ({ success: true, events: [] }));
+    const directoryService = { loadSessionEvents } as any;
+    const ctx = createMockContext({ directoryService });
+
+    // Restore an ENDED session with sessionFile + persisted contextWindow.
+    // No events in the store → falls into the lazy-load branch.
+    // (`restore()` takes the full DashboardSession; `register()` does not
+    // accept contextWindow as a registration param.)
+    ctx.sessionManager.restore({
+      id: "s-ctx",
+      cwd: "/test",
+      source: "tui",
+      status: "ended",
+      startedAt: 1000,
+      endedAt: 2000,
+      tokensIn: 0,
+      tokensOut: 0,
+      cost: 0,
+      contextWindow: 1_000_000,
+      sessionFile: "/sessions/s-ctx.jsonl",
+      sessionDir: "/sessions",
+      hidden: false,
+    } as any);
+
+    const subs = new Set<string>();
+    handleSubscribe({ type: "subscribe", sessionId: "s-ctx" }, subs, ctx);
+
+    await new Promise((r) => setTimeout(r, 20));
+
+    expect(loadSessionEvents).toHaveBeenCalledTimes(1);
+    expect(loadSessionEvents).toHaveBeenCalledWith("s-ctx", "/sessions/s-ctx.jsonl", 1_000_000);
+  });
+
   it("does full replay when lastSeq is 0", async () => {
     const ctx = createMockContext();
     for (let i = 0; i < 3; i++) ctx.eventStore.insertEvent("s1", makeEvent());

package/packages/server/src/__tests__/translate-path-source.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import { translatePathSource } from "../package-manager-wrapper.js";
+
+describe("translatePathSource", () => {
+	const fromLocal = "/abs/project/.pi";
+	const toGlobal = "/Users/u/.pi/agent";
+	const toLocal = "/abs/other/.pi";
+
+	it("rel-path → global resolves to absolute against fromSettingsDir", () => {
+		expect(
+			translatePathSource({
+				originalSource: "..",
+				fromSettingsDir: fromLocal,
+				toSettingsDir: toGlobal,
+				toScope: "global",
+			}),
+		).toBe(path.resolve("/abs/project/.pi/.."));
+	});
+
+	it("./foo → global resolves to absolute", () => {
+		expect(
+			translatePathSource({
+				originalSource: "./foo",
+				fromSettingsDir: fromLocal,
+				toSettingsDir: toGlobal,
+				toScope: "global",
+			}),
+		).toBe(path.resolve("/abs/project/.pi/foo"));
+	});
+
+	it("abs-path → local stays absolute when relative form escapes >2 levels", () => {
+		// /abs/project from /abs/other/.pi  →  ../../project (2 ups, OK)
+		// /tmp/foo     from /abs/other/.pi  →  ../../../tmp/foo (3 ups, escape)
+		expect(
+			translatePathSource({
+				originalSource: "/tmp/foo",
+				fromSettingsDir: fromLocal,
+				toSettingsDir: toLocal,
+				toScope: "local",
+			}),
+		).toBe("/tmp/foo");
+	});
+
+	it("abs-path → local goes relative when within 2 levels", () => {
+		expect(
+			translatePathSource({
+				originalSource: "/abs/project",
+				fromSettingsDir: fromLocal,
+				toSettingsDir: toLocal,
+				toScope: "local",
+			}),
+		).toBe("../../project");
+	});
+
+	it("abs-path equal to toSettingsDir collapses to '.'", () => {
+		expect(
+			translatePathSource({
+				originalSource: "/abs/other/.pi",
+				fromSettingsDir: fromLocal,
+				toSettingsDir: toLocal,
+				toScope: "local",
+			}),
+		).toBe(".");
+	});
+
+	it("abs-path → global stays absolute", () => {
+		expect(
+			translatePathSource({
+				originalSource: "/abs/project/vendor/x",
+				fromSettingsDir: fromLocal,
+				toSettingsDir: toGlobal,
+				toScope: "global",
+			}),
+		).toBe("/abs/project/vendor/x");
+	});
+});

package/packages/server/src/__tests__/ui-decorators-replay.test.ts

@@ -0,0 +1,209 @@
+import { describe, it, expect, vi } from "vitest";
+import { handleSubscribe, replayUiState } from "../browser-handlers/subscription-handler.js";
+import { createMemoryEventStore } from "../memory-event-store.js";
+import { createMemorySessionManager } from "../memory-session-manager.js";
+import type { BrowserHandlerContext } from "../browser-handlers/handler-context.js";
+import type { DecoratorDescriptor, ExtensionUiModule } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+/**
+ * Phase-2 (`add-extension-ui-decorations`) server contract:
+ *
+ *   - `replayUiState` sends `ui_modules_list` + `ui_data_list`* (Phase 1) THEN
+ *     one `ext_ui_decorator` per cached `Session.uiDecorators` entry.
+ *   - Replay decorators NEVER carry `removed: true`.
+ *   - Replay ordering: events → pending UI requests → ui_modules_list →
+ *     ui_data_list → ext_ui_decorator.
+ *   - Cache write/delete semantics: upsert under `${kind}:${namespace}:${id}`;
+ *     `removed: true` deletes the entry; deleting an absent key is a no-op
+ *     but still broadcasts.
+ */
+
+function module1(): ExtensionUiModule {
+  return {
+    kind: "management-modal",
+    id: "m1",
+    command: "/m1",
+    title: "M1",
+    view: { kind: "table", dataEvent: "m1:rows", fields: [{ key: "id", label: "ID", kind: "text" }] },
+  };
+}
+
+function footer(namespace: string, id: string, text: string): DecoratorDescriptor {
+  return { kind: "footer-segment", namespace, id, payload: { text } };
+}
+
+function gate(namespace: string, id: string, flowId: string, available: boolean): DecoratorDescriptor {
+  return { kind: "gate", namespace, id, payload: { flowId, available } };
+}
+
+function createCtx(overrides: Partial<BrowserHandlerContext> = {}): BrowserHandlerContext {
+  return {
+    ws: { readyState: 1, OPEN: 1, bufferedAmount: 0 } as any,
+    sessionManager: createMemorySessionManager(),
+    eventStore: createMemoryEventStore(() => false),
+    piGateway: { sendToSession: vi.fn() } as any,
+    headlessPidRegistry: {} as any,
+    pendingResumeRegistry: {} as any,
+    sendTo: vi.fn(),
+    broadcast: vi.fn(),
+    getSubscribers: () => [],
+    trackUiRequest: vi.fn(),
+    replayPendingUiRequests: vi.fn(),
+    markReplaying: vi.fn(),
+    clearReplaying: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe("replayUiState — Phase-2 decorator replay", () => {
+  it("sends one ext_ui_decorator per uiDecorators entry after the Phase-1 batches", () => {
+    const ctx = createCtx();
+    ctx.sessionManager.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    const fA = footer("judo", "model-state", "3 mut");
+    const fB = footer("flows", "progress", "step 2/5");
+    const gC = gate("judo", "save", "judo:save", false);
+    ctx.sessionManager.update("s1", {
+      uiModules: [module1()],
+      uiDataMap: { "m1:rows": [{ id: 1 }] },
+      uiDecorators: {
+        [`footer-segment:judo:model-state`]: fA,
+        [`footer-segment:flows:progress`]: fB,
+        [`gate:judo:save`]: gC,
+      },
+    });
+
+    replayUiState(ctx.ws, "s1", ctx);
+
+    const calls = (ctx.sendTo as any).mock.calls.map(([, m]: any) => m);
+    // 1 modules + 1 data + 3 decorators
+    expect(calls).toHaveLength(5);
+    expect(calls[0]).toMatchObject({ type: "ui_modules_list" });
+    expect(calls[1]).toMatchObject({ type: "ui_data_list", event: "m1:rows" });
+    const decoratorCalls = calls.slice(2);
+    for (const m of decoratorCalls) {
+      expect(m.type).toBe("ext_ui_decorator");
+      expect(m.sessionId).toBe("s1");
+      // Replay NEVER sets removed: true — only live entries are replayed.
+      expect(m.removed).toBeUndefined();
+    }
+    const keys = decoratorCalls.map((m: any) => `${m.descriptor.kind}:${m.descriptor.namespace}:${m.descriptor.id}`).sort();
+    expect(keys).toEqual([
+      "footer-segment:flows:progress",
+      "footer-segment:judo:model-state",
+      "gate:judo:save",
+    ]);
+  });
+
+  it("does not send any ext_ui_decorator when uiDecorators is missing or empty", () => {
+    const ctx = createCtx();
+    ctx.sessionManager.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    ctx.sessionManager.update("s1", { uiModules: [module1()] });
+    replayUiState(ctx.ws, "s1", ctx);
+    const calls = (ctx.sendTo as any).mock.calls.map(([, m]: any) => m);
+    expect(calls.some((m: any) => m.type === "ext_ui_decorator")).toBe(false);
+
+    (ctx.sendTo as any).mockClear();
+    ctx.sessionManager.update("s1", { uiDecorators: {} });
+    replayUiState(ctx.ws, "s1", ctx);
+    const calls2 = (ctx.sendTo as any).mock.calls.map(([, m]: any) => m);
+    expect(calls2.some((m: any) => m.type === "ext_ui_decorator")).toBe(false);
+  });
+});
+
+describe("handleSubscribe — replay ordering with decorators", () => {
+  it("replay order is events → pending UI → ui_modules_list → ui_data_list → ext_ui_decorator", async () => {
+    const ctx = createCtx();
+    ctx.sessionManager.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    ctx.sessionManager.update("s1", {
+      uiModules: [module1()],
+      uiDataMap: { "m1:rows": [{ id: 1 }] },
+      uiDecorators: { [`footer-segment:judo:x`]: footer("judo", "x", "live") },
+    });
+    ctx.eventStore.insertEvent("s1", { eventType: "x", timestamp: Date.now(), data: {} });
+
+    handleSubscribe({ type: "subscribe", sessionId: "s1", lastSeq: 0 }, new Set(), ctx);
+    await new Promise((r) => setTimeout(r, 30));
+
+    const calls = (ctx.sendTo as any).mock.calls.map(([, m]: any) => m);
+    const eventReplayIdx = calls.findIndex((m: any) => m.type === "event_replay");
+    const modulesIdx = calls.findIndex((m: any) => m.type === "ui_modules_list");
+    const dataIdx = calls.findIndex((m: any) => m.type === "ui_data_list");
+    const decoratorIdx = calls.findIndex((m: any) => m.type === "ext_ui_decorator");
+
+    expect(eventReplayIdx).toBeGreaterThanOrEqual(0);
+    expect(modulesIdx).toBeGreaterThan(eventReplayIdx);
+    expect(dataIdx).toBeGreaterThan(modulesIdx);
+    expect(decoratorIdx).toBeGreaterThan(dataIdx);
+    // replayPendingUiRequests is called between event replay and replayUiState.
+    expect((ctx.replayPendingUiRequests as any).mock.calls.length).toBeGreaterThan(0);
+  });
+});
+
+/**
+ * The cache upsert/delete contract is implemented inside `event-wiring.ts`'s
+ * `ext_ui_decorator` switch arm. We exercise it through a thin reducer
+ * mirroring the production code; the same logic is exercised end-to-end via
+ * `replayUiState` (which reads `Session.uiDecorators` directly).
+ */
+describe("ext_ui_decorator cache reducer (mirrors event-wiring contract)", () => {
+  type DecoratorMsg = {
+    type: "ext_ui_decorator";
+    sessionId: string;
+    descriptor: DecoratorDescriptor;
+    removed?: boolean;
+  };
+
+  function applyDecoratorMsg(
+    sessionMgr: ReturnType<typeof createMemorySessionManager>,
+    msg: DecoratorMsg,
+  ): void {
+    const session = sessionMgr.get(msg.sessionId);
+    if (!session) return;
+    const key = `${msg.descriptor.kind}:${msg.descriptor.namespace}:${msg.descriptor.id}`;
+    const next = { ...(session.uiDecorators ?? {}) };
+    if (msg.removed) delete next[key];
+    else next[key] = msg.descriptor;
+    sessionMgr.update(msg.sessionId, { uiDecorators: next });
+  }
+
+  it("upserts under composite key", () => {
+    const mgr = createMemorySessionManager();
+    mgr.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    applyDecoratorMsg(mgr, { type: "ext_ui_decorator", sessionId: "s1", descriptor: footer("judo", "x", "v1") });
+    expect(mgr.get("s1")?.uiDecorators).toEqual({
+      "footer-segment:judo:x": expect.objectContaining({ payload: { text: "v1" } }),
+    });
+
+    // Upsert overwrites the value at the same key.
+    applyDecoratorMsg(mgr, { type: "ext_ui_decorator", sessionId: "s1", descriptor: footer("judo", "x", "v2") });
+    expect((mgr.get("s1")!.uiDecorators!["footer-segment:judo:x"].payload as any).text).toBe("v2");
+  });
+
+  it("removed: true deletes the entry", () => {
+    const mgr = createMemorySessionManager();
+    mgr.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    applyDecoratorMsg(mgr, { type: "ext_ui_decorator", sessionId: "s1", descriptor: footer("judo", "x", "v1") });
+    expect(mgr.get("s1")?.uiDecorators).toHaveProperty("footer-segment:judo:x");
+
+    applyDecoratorMsg(mgr, { type: "ext_ui_decorator", sessionId: "s1", descriptor: footer("judo", "x", "v1"), removed: true });
+    expect(mgr.get("s1")?.uiDecorators).not.toHaveProperty("footer-segment:judo:x");
+  });
+
+  it("removed: true on an absent key is a no-op", () => {
+    const mgr = createMemorySessionManager();
+    mgr.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    applyDecoratorMsg(mgr, { type: "ext_ui_decorator", sessionId: "s1", descriptor: footer("judo", "absent", "v"), removed: true });
+    expect(mgr.get("s1")?.uiDecorators).toEqual({});
+  });
+
+  it("different namespaces are stored independently", () => {
+    const mgr = createMemorySessionManager();
+    mgr.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    applyDecoratorMsg(mgr, { type: "ext_ui_decorator", sessionId: "s1", descriptor: footer("judo", "ms", "j") });
+    applyDecoratorMsg(mgr, { type: "ext_ui_decorator", sessionId: "s1", descriptor: footer("flows", "ms", "f") });
+    expect(Object.keys(mgr.get("s1")!.uiDecorators!).sort()).toEqual([
+      "footer-segment:flows:ms",
+      "footer-segment:judo:ms",
+    ]);
+  });
+});