@openchambery/web 1.19.12 → 1.19.13-beta.1

package/server/lib/notifications/apns-runtime.test.js

@@ -1175,3 +1175,131 @@ describe('apns live activity host-relay compatibility', () => {
     expect(apnsCalls).toHaveLength(0);
   });
 });
+
+describe('apns live activity refresh', () => {
+  it('sends nothing when no snapshot changed', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse({ ok: true, results: [] }));
+    vi.stubGlobal('fetch', fetchMock);
+    process.env.OPENCHAMBER_PUSH_RELAY_URL = 'https://relay.test/v1/push/send';
+    const deps = makeDeps();
+    const runtime = createApnsRuntime(deps);
+    await runtime.addOrUpdateLiveActivityToken('s1', 'la-token', 'act-1', 'live', [
+      { sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 },
+    ]);
+
+    fetchMock.mockClear();
+    await runtime.refreshLiveActivityTokens({ computeSnapshot: async () => null });
+    expect(fetchMock.mock.calls.filter(isLiveActivitySend)).toHaveLength(0);
+    const store = JSON.parse(await deps.fsPromises.readFile('/tmp/apns-tokens.json'));
+    expect(store.liveActivityTokensBySession.s1).toHaveLength(1);
+  });
+
+  it('pushes an update with the recomputed snapshot and bumps the event version monotonically', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse({ ok: true, results: [] }));
+    vi.stubGlobal('fetch', fetchMock);
+    process.env.OPENCHAMBER_PUSH_RELAY_URL = 'https://relay.test/v1/push/send';
+    const deps = makeDeps();
+    const runtime = createApnsRuntime(deps);
+    await runtime.addOrUpdateLiveActivityToken('s1', 'la-token', 'act-1', 'live', [
+      { sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 },
+    ]);
+
+    fetchMock.mockClear();
+    await runtime.refreshLiveActivityTokens({
+      computeSnapshot: async () => ({
+        items: [{ sessionId: 'ses_1', title: 'One', status: 'retry', startedAt: 1 }],
+      }),
+    });
+    const sent = JSON.parse(fetchMock.mock.calls.find(isLiveActivitySend)[1].body);
+    expect(sent.tokens).toEqual(['la-token']);
+    expect(sent.event).toBe('update');
+    expect(sent.contentState.status).toBe('retry');
+    expect(sent.contentState.workingCount).toBe(1);
+    expect(sent.contentState.items[0]).toMatchObject({ sessionID: 'ses_1', status: 'retry' });
+    expect(sent.staleDate).toBeGreaterThan(0);
+    expect(sent.dismissalDate).toBeUndefined();
+
+    const store = JSON.parse(await deps.fsPromises.readFile('/tmp/apns-tokens.json'));
+    expect(store.liveActivityTokensBySession.s1[0].snapshot[0].status).toBe('retry');
+    const firstVersion = store.liveActivityEventVersions.live;
+
+    fetchMock.mockClear();
+    await runtime.refreshLiveActivityTokens({
+      computeSnapshot: async () => ({
+        items: [{ sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 }],
+      }),
+    });
+    const second = JSON.parse(fetchMock.mock.calls.find(isLiveActivitySend)[1].body);
+    expect(second.contentState.eventVersion).toBeGreaterThan(firstVersion);
+  });
+
+  it('ends and clears the token when nothing is working anymore', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse({ ok: true, results: [] }));
+    vi.stubGlobal('fetch', fetchMock);
+    process.env.OPENCHAMBER_PUSH_RELAY_URL = 'https://relay.test/v1/push/send';
+    const deps = makeDeps();
+    const runtime = createApnsRuntime(deps);
+    await runtime.addOrUpdateLiveActivityToken('s1', 'la-token', 'act-1', 'live', [
+      { sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 },
+    ]);
+
+    fetchMock.mockClear();
+    await runtime.refreshLiveActivityTokens({
+      computeSnapshot: async () => ({
+        items: [{ sessionId: 'ses_1', title: 'One', status: 'complete', startedAt: 1, endedAt: 5 }],
+      }),
+    });
+    const sent = JSON.parse(fetchMock.mock.calls.find(isLiveActivitySend)[1].body);
+    expect(sent.event).toBe('end');
+    expect(sent.contentState.status).toBe('complete');
+    expect(sent.dismissalDate).toBeGreaterThan(0);
+    expect(sent.staleDate).toBeUndefined();
+
+    const store = JSON.parse(await deps.fsPromises.readFile('/tmp/apns-tokens.json'));
+    expect(store.liveActivityTokensBySession.s1).toBeUndefined();
+  });
+
+  it('groups entries with identical snapshots into one send and keeps distinct snapshots separate', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse({ ok: true, results: [] }));
+    vi.stubGlobal('fetch', fetchMock);
+    process.env.OPENCHAMBER_PUSH_RELAY_URL = 'https://relay.test/v1/push/send';
+    const runtime = createApnsRuntime(makeDeps());
+    await runtime.addOrUpdateLiveActivityToken('s1', 'la-token-a', 'act-1', 'live', [
+      { sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 },
+    ]);
+    await runtime.addOrUpdateLiveActivityToken('s2', 'la-token-b', 'act-2', 'live', [
+      { sessionId: 'ses_2', title: 'Two', status: 'working', startedAt: 2 },
+    ]);
+
+    fetchMock.mockClear();
+    await runtime.refreshLiveActivityTokens({
+      computeSnapshot: async (entry) => {
+        if (entry.token === 'la-token-a') {
+          return { items: [{ sessionId: 'ses_1', title: 'One', status: 'retry', startedAt: 1 }] };
+        }
+        return { items: [{ sessionId: 'ses_2', title: 'Two', status: 'retry', startedAt: 2 }] };
+      },
+    });
+    const sends = fetchMock.mock.calls.filter(isLiveActivitySend).map((call) => JSON.parse(call[1].body));
+    expect(sends).toHaveLength(2);
+  });
+
+  it('treats a computeSnapshot rejection as skip, not failure', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse({ ok: true, results: [] }));
+    vi.stubGlobal('fetch', fetchMock);
+    process.env.OPENCHAMBER_PUSH_RELAY_URL = 'https://relay.test/v1/push/send';
+    const deps = makeDeps();
+    const runtime = createApnsRuntime(deps);
+    await runtime.addOrUpdateLiveActivityToken('s1', 'la-token', 'act-1', 'live', [
+      { sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 },
+    ]);
+
+    fetchMock.mockClear();
+    await expect(runtime.refreshLiveActivityTokens({
+      computeSnapshot: async () => {
+        throw new Error('boom');
+      },
+    })).resolves.toBeUndefined();
+    expect(fetchMock.mock.calls.filter(isLiveActivitySend)).toHaveLength(0);
+  });
+});

package/server/lib/notifications/apns-titles.js

@@ -16,7 +16,7 @@ export const APNS_LOCALES = Object.freeze([
   'ja',
 ]);
 
-/** @typedef {'ready'|'error'|'question'|'permission'|'goal_complete'|'goal_blocked'|'goal_budget'|'update'} ApnsTitleType */
+/** @typedef {'ready'|'error'|'question'|'permission'|'goal_complete'|'goal_blocked'|'goal_budget'|'task_complete'|'task_error'|'update'} ApnsTitleType */
 
 const TITLES = Object.freeze({
   en: Object.freeze({
@@ -27,6 +27,8 @@ const TITLES = Object.freeze({
     goal_complete: 'Goal completed',
     goal_blocked: 'Goal blocked',
     goal_budget: 'Token budget reached',
+    task_complete: 'Scheduled task completed',
+    task_error: 'Scheduled task failed',
     update: 'Update',
     session: 'Session',
   }),
@@ -38,6 +40,8 @@ const TITLES = Object.freeze({
     goal_complete: 'Objectif atteint',
     goal_blocked: 'Objectif bloqué',
     goal_budget: 'Budget de tokens atteint',
+    task_complete: 'Tâche planifiée terminée',
+    task_error: 'Échec de la tâche planifiée',
     update: 'Mise à jour',
     session: 'Session',
   }),
@@ -49,6 +53,8 @@ const TITLES = Object.freeze({
     goal_complete: '目标已完成',
     goal_blocked: '目标受阻',
     goal_budget: '已达用量上限',
+    task_complete: '定时任务已完成',
+    task_error: '定时任务失败',
     update: '有新进展',
     session: '会话',
   }),
@@ -60,6 +66,8 @@ const TITLES = Object.freeze({
     goal_complete: '目標已完成',
     goal_blocked: '目標受阻',
     goal_budget: '已達用量上限',
+    task_complete: '排程任務已完成',
+    task_error: '排程任務失敗',
     update: '有新進展',
     session: '工作階段',
   }),
@@ -71,6 +79,8 @@ const TITLES = Object.freeze({
     goal_complete: 'Цілі досягнуто',
     goal_blocked: 'Цілі заблоковано',
     goal_budget: 'Досягнуто ліміт токенів',
+    task_complete: 'Заплановане завдання виконано',
+    task_error: 'Заплановане завдання не вдалося',
     update: 'Оновлення',
     session: 'Сесія',
   }),
@@ -82,6 +92,8 @@ const TITLES = Object.freeze({
     goal_complete: 'Objetivo completado',
     goal_blocked: 'Objetivo bloqueado',
     goal_budget: 'Presupuesto de tokens alcanzado',
+    task_complete: 'Tarea programada completada',
+    task_error: 'La tarea programada falló',
     update: 'Actualización',
     session: 'Sesión',
   }),
@@ -93,6 +105,8 @@ const TITLES = Object.freeze({
     goal_complete: 'Objetivo concluído',
     goal_blocked: 'Objetivo bloqueado',
     goal_budget: 'Orçamento de tokens atingido',
+    task_complete: 'Tarefa agendada concluída',
+    task_error: 'A tarefa agendada falhou',
     update: 'Atualização',
     session: 'Sessão',
   }),
@@ -104,6 +118,8 @@ const TITLES = Object.freeze({
     goal_complete: '목표 완료',
     goal_blocked: '목표 차단됨',
     goal_budget: '토큰 한도 도달',
+    task_complete: '예약 작업 완료',
+    task_error: '예약 작업 실패',
     update: '업데이트',
     session: '세션',
   }),
@@ -115,6 +131,8 @@ const TITLES = Object.freeze({
     goal_complete: 'Cel ukończony',
     goal_blocked: 'Cel zablokowany',
     goal_budget: 'Osiągnięto limit tokenów',
+    task_complete: 'Zadanie zaplanowane ukończone',
+    task_error: 'Zadanie zaplanowane nie powiodło się',
     update: 'Aktualizacja',
     session: 'Sesja',
   }),
@@ -126,6 +144,8 @@ const TITLES = Object.freeze({
     goal_complete: '目標完了',
     goal_blocked: '目標がブロックされました',
     goal_budget: 'トークン上限に達しました',
+    task_complete: 'スケジュールタスクが完了しました',
+    task_error: 'スケジュールタスクに失敗しました',
     update: '更新',
     session: 'セッション',
   }),

package/server/lib/notifications/live-activity-refresh-runtime.js

@@ -0,0 +1,185 @@
+// Periodic Live Activity snapshot refresh for iOS devices that registered a
+// Live Activity push token. While the app is foreground/connected the UI keeps
+// its own ActivityKit state fresh; once iOS suspends or kills the app, only
+// APNs can move the on-screen activity. Completion/error/title already push
+// event-driven (runtime.js → sendLiveActivityEnd); this runtime covers the
+// busy phase: every interval it recomputes each persisted token's snapshot
+// from the authoritative session-status snapshot and pushes an update only
+// when something actually changed (APNs budgets Live Activity updates per
+// hour, so unchanged snapshots never send).
+//
+// Interval: default 30s, override with OPENCHAMBER_LIVE_ACTIVITY_REFRESH_INTERVAL_MS
+// (milliseconds; `0` disables the timer). Snapshots use unix seconds, matching
+// the persisted token store (apns-runtime.js parseLiveActivitySnapshot).
+
+export const LIVE_ACTIVITY_REFRESH_DEFAULT_INTERVAL_MS = 30_000;
+export const LIVE_ACTIVITY_REFRESH_ITEM_LIMIT = 4; // mirrors the UI catalog cap
+export const LIVE_ACTIVITY_REFRESH_TITLE_MAX = 80;
+
+export const resolveLiveActivityRefreshIntervalMs = (env = process.env) => {
+  const raw = env?.OPENCHAMBER_LIVE_ACTIVITY_REFRESH_INTERVAL_MS;
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return LIVE_ACTIVITY_REFRESH_DEFAULT_INTERVAL_MS;
+  }
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return LIVE_ACTIVITY_REFRESH_DEFAULT_INTERVAL_MS;
+  return Math.floor(parsed);
+};
+
+const liveActivityItemIsWorking = (status) => status !== 'complete' && status !== 'error';
+
+// Session-side sub-states the server has no authoritative source for. The UI
+// derives them from live permission/question/message-delta channels; once it is
+// gone we keep the last row state instead of flickering back to `working`.
+const LIVE_ACTIVITY_PRESERVED_ROW_STATUSES = new Set(['permission', 'input', 'tool']);
+
+const mapSessionStatusToRowStatus = (sessionStatus) => {
+  if (sessionStatus === 'retry') return 'retry';
+  if (sessionStatus === 'busy') return 'working';
+  return null; // idle / unknown → terminal
+};
+
+const nextRowStatus = (currentRowStatus, sessionStatus) => {
+  if (sessionStatus === 'busy') {
+    if (LIVE_ACTIVITY_PRESERVED_ROW_STATUSES.has(currentRowStatus)) return currentRowStatus;
+    return 'working'; // including stale → working (server connection is authoritative here)
+  }
+  if (sessionStatus === 'retry') return 'retry';
+  return 'complete';
+};
+
+const capLiveActivityItems = (items) => {
+  if (items.length <= LIVE_ACTIVITY_REFRESH_ITEM_LIMIT) return items;
+  const working = items.filter((item) => liveActivityItemIsWorking(item.status));
+  const settled = items
+    .filter((item) => !liveActivityItemIsWorking(item.status))
+    .sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
+  const next = [...working];
+  for (const item of settled) {
+    if (next.length >= LIVE_ACTIVITY_REFRESH_ITEM_LIMIT) break;
+    next.push(item);
+  }
+  return next.slice(0, LIVE_ACTIVITY_REFRESH_ITEM_LIMIT);
+};
+
+const liveActivityItemsSignature = (items) => items
+  .map((item) => `${item.sessionId}\0${item.title}\0${item.status}\0${item.endedAt ?? ''}`)
+  .join('\n');
+
+/**
+ * Recompute one entry's snapshot from the authoritative session-state snapshot.
+ * Returns `{ items }` (unix seconds) when something changed, `null` to skip.
+ * Rows for sessions with no live server state are preserved as-is (never guess
+ * terminal from missing data); new busy/retry sessions join only when the
+ * injected resolver confirms sidebar visibility.
+ */
+export const computeLiveActivityRefreshSnapshot = async (input) => {
+  const { entry, sessionStates, resolveSession, nowMs } = input;
+  const nowSeconds = Math.floor(nowMs / 1000);
+  const previous = Array.isArray(entry.snapshot) ? entry.snapshot : [];
+  const items = [];
+  const seen = new Set();
+
+  for (const item of previous) {
+    if (!item || typeof item.sessionId !== 'string') continue;
+    seen.add(item.sessionId);
+    const state = sessionStates[item.sessionId];
+    if (!state) {
+      items.push(item); // no authoritative state → keep the last known row
+      continue;
+    }
+    const rowStatus = nextRowStatus(item.status, state.status);
+    if (rowStatus === item.status) {
+      items.push(item);
+      continue;
+    }
+    if (rowStatus === 'complete') {
+      items.push({
+        ...item,
+        status: 'complete',
+        endedAt: item.endedAt ?? nowSeconds,
+      });
+      continue;
+    }
+    items.push({ ...item, status: rowStatus });
+  }
+
+  const additions = [];
+  for (const [sessionId, state] of Object.entries(sessionStates || {})) {
+    if (seen.has(sessionId)) continue;
+    const mapped = mapSessionStatusToRowStatus(state?.status);
+    if (mapped === null || mapped === 'complete') continue;
+    let candidate = null;
+    try {
+      candidate = await resolveSession(sessionId);
+    } catch {
+      candidate = null;
+    }
+    if (!candidate || candidate.visible !== true) continue;
+    additions.push({
+      sessionId,
+      title: typeof candidate.title === 'string' ? candidate.title.slice(0, LIVE_ACTIVITY_REFRESH_TITLE_MAX) : '',
+      status: mapped,
+      startedAt: nowSeconds,
+    });
+  }
+
+  const merged = capLiveActivityItems([...items, ...additions]);
+  if (liveActivityItemsSignature(merged) === liveActivityItemsSignature(previous)) return null;
+  return { items: merged };
+};
+
+/**
+ * Owns the refresh interval. One tick snapshots the authoritative session
+ * states once, then hands every persisted Live Activity entry to
+ * `refreshLiveActivityTokens` (apns-runtime.js), which skips entries whose
+ * computed snapshot is unchanged. Overlapping ticks are dropped, not queued.
+ */
+export const createLiveActivityRefreshRuntime = (deps) => {
+  const {
+    intervalMs,
+    refreshLiveActivityTokens,
+    getSessionStateSnapshot,
+    resolveSession,
+  } = deps;
+  let timer = null;
+  let ticking = false;
+
+  const tick = async () => {
+    if (ticking) return;
+    ticking = true;
+    try {
+      const sessionStates = getSessionStateSnapshot();
+      const nowMs = Date.now();
+      await refreshLiveActivityTokens({
+        computeSnapshot: (entry) => computeLiveActivityRefreshSnapshot({
+          entry,
+          sessionStates,
+          resolveSession,
+          nowMs,
+        }),
+      });
+    } catch (error) {
+      console.warn('[Live Activity refresh] tick failed:', error?.message ?? error);
+    } finally {
+      ticking = false;
+    }
+  };
+
+  const start = () => {
+    if (timer || !(intervalMs > 0)) return;
+    timer = setInterval(() => {
+      void tick();
+    }, intervalMs);
+    timer.unref?.();
+  };
+
+  const dispose = () => {
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+
+  return { start, dispose, tick };
+};

package/server/lib/notifications/live-activity-refresh-runtime.test.js

@@ -0,0 +1,242 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  LIVE_ACTIVITY_REFRESH_DEFAULT_INTERVAL_MS,
+  computeLiveActivityRefreshSnapshot,
+  createLiveActivityRefreshRuntime,
+  resolveLiveActivityRefreshIntervalMs,
+} from './live-activity-refresh-runtime.js';
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe('resolveLiveActivityRefreshIntervalMs', () => {
+  it('defaults to 30s', () => {
+    expect(resolveLiveActivityRefreshIntervalMs({})).toBe(LIVE_ACTIVITY_REFRESH_DEFAULT_INTERVAL_MS);
+    expect(resolveLiveActivityRefreshIntervalMs({
+      OPENCHAMBER_LIVE_ACTIVITY_REFRESH_INTERVAL_MS: '  ',
+    })).toBe(LIVE_ACTIVITY_REFRESH_DEFAULT_INTERVAL_MS);
+  });
+
+  it('honours explicit overrides including disable', () => {
+    expect(resolveLiveActivityRefreshIntervalMs({
+      OPENCHAMBER_LIVE_ACTIVITY_REFRESH_INTERVAL_MS: '45000',
+    })).toBe(45_000);
+    expect(resolveLiveActivityRefreshIntervalMs({
+      OPENCHAMBER_LIVE_ACTIVITY_REFRESH_INTERVAL_MS: '0',
+    })).toBe(0);
+  });
+
+  it('falls back to the default for invalid values', () => {
+    expect(resolveLiveActivityRefreshIntervalMs({
+      OPENCHAMBER_LIVE_ACTIVITY_REFRESH_INTERVAL_MS: 'abc',
+    })).toBe(LIVE_ACTIVITY_REFRESH_DEFAULT_INTERVAL_MS);
+    expect(resolveLiveActivityRefreshIntervalMs({
+      OPENCHAMBER_LIVE_ACTIVITY_REFRESH_INTERVAL_MS: '-5',
+    })).toBe(LIVE_ACTIVITY_REFRESH_DEFAULT_INTERVAL_MS);
+  });
+});
+
+describe('computeLiveActivityRefreshSnapshot', () => {
+  const baseInput = (overrides = {}) => ({
+    entry: { token: 't', sessionId: 'live', snapshot: [] },
+    sessionStates: {},
+    resolveSession: async () => null,
+    nowMs: 1_700_000_000_000,
+    ...overrides,
+  });
+
+  it('maps idle to complete with endedAt and marks the snapshot changed', async () => {
+    const result = await computeLiveActivityRefreshSnapshot(baseInput({
+      entry: {
+        token: 't',
+        sessionId: 'live',
+        snapshot: [{ sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 }],
+      },
+      sessionStates: { ses_1: { status: 'idle' } },
+    }));
+    expect(result).toEqual({
+      items: [{
+        sessionId: 'ses_1',
+        title: 'One',
+        status: 'complete',
+        startedAt: 1,
+        endedAt: Math.floor(1_700_000_000_000 / 1000),
+      }],
+    });
+  });
+
+  it('keeps server-side-only sub-states while the session stays busy', async () => {
+    const snapshot = [{ sessionId: 'ses_1', title: 'One', status: 'permission', startedAt: 1 }];
+    const result = await computeLiveActivityRefreshSnapshot(baseInput({
+      entry: { token: 't', sessionId: 'live', snapshot },
+      sessionStates: { ses_1: { status: 'busy' } },
+    }));
+    expect(result).toBeNull();
+  });
+
+  it('recovers stale rows to working while busy', async () => {
+    const result = await computeLiveActivityRefreshSnapshot(baseInput({
+      entry: {
+        token: 't',
+        sessionId: 'live',
+        snapshot: [{ sessionId: 'ses_1', title: 'One', status: 'stale', startedAt: 1 }],
+      },
+      sessionStates: { ses_1: { status: 'busy' } },
+    }));
+    expect(result?.items[0].status).toBe('working');
+  });
+
+  it('maps retry sessions to the retry row status', async () => {
+    const result = await computeLiveActivityRefreshSnapshot(baseInput({
+      entry: {
+        token: 't',
+        sessionId: 'live',
+        snapshot: [{ sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 }],
+      },
+      sessionStates: { ses_1: { status: 'retry' } },
+    }));
+    expect(result?.items[0].status).toBe('retry');
+  });
+
+  it('preserves rows whose session has no authoritative server state', async () => {
+    const snapshot = [{ sessionId: 'ses_gone', title: 'Gone', status: 'working', startedAt: 1 }];
+    const result = await computeLiveActivityRefreshSnapshot(baseInput({
+      entry: { token: 't', sessionId: 'live', snapshot },
+      sessionStates: {},
+    }));
+    expect(result).toBeNull();
+  });
+
+  it('adds new busy sessions only when the resolver marks them visible', async () => {
+    const resolveSession = vi.fn(async (sessionId) => (
+      sessionId === 'ses_child'
+        ? { title: 'Child', visible: false }
+        : { title: 'New Task', visible: true }
+    ));
+    const result = await computeLiveActivityRefreshSnapshot(baseInput({
+      entry: { token: 't', sessionId: 'live', snapshot: [] },
+      sessionStates: {
+        ses_new: { status: 'busy' },
+        ses_child: { status: 'busy' },
+        ses_idle: { status: 'idle' },
+      },
+      resolveSession,
+    }));
+    expect(result?.items).toHaveLength(1);
+    expect(result?.items[0]).toMatchObject({ sessionId: 'ses_new', title: 'New Task', status: 'working' });
+    expect(resolveSession).not.toHaveBeenCalledWith('ses_idle');
+  });
+
+  it('skips new sessions when the resolver throws or resolves empty', async () => {
+    const result = await computeLiveActivityRefreshSnapshot(baseInput({
+      entry: { token: 't', sessionId: 'live', snapshot: [] },
+      sessionStates: { ses_new: { status: 'busy' } },
+      resolveSession: async () => {
+        throw new Error('boom');
+      },
+    }));
+    expect(result).toBeNull();
+  });
+
+  it('caps merged rows at the catalog limit, working rows first', async () => {
+    const snapshot = [1, 2, 3, 4, 5].map((n) => ({
+      sessionId: `ses_${n}`,
+      title: `S${n}`,
+      status: 'complete',
+      startedAt: n,
+      endedAt: n,
+    }));
+    const result = await computeLiveActivityRefreshSnapshot(baseInput({
+      entry: { token: 't', sessionId: 'live', snapshot },
+      sessionStates: { ses_new: { status: 'busy' } },
+      resolveSession: async () => ({ title: 'New', visible: true }),
+    }));
+    expect(result?.items).toHaveLength(4);
+    expect(result?.items.some((item) => item.sessionId === 'ses_new')).toBe(true);
+    // Most recently settled rows survive the cap.
+    expect(result?.items.some((item) => item.sessionId === 'ses_5')).toBe(true);
+    expect(result?.items.some((item) => item.sessionId === 'ses_1')).toBe(false);
+  });
+
+  it('returns null when nothing changed', async () => {
+    const snapshot = [
+      { sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 },
+      { sessionId: 'ses_2', title: 'Two', status: 'complete', startedAt: 2, endedAt: 3 },
+    ];
+    const result = await computeLiveActivityRefreshSnapshot(baseInput({
+      entry: { token: 't', sessionId: 'live', snapshot },
+      sessionStates: { ses_1: { status: 'busy' } },
+    }));
+    expect(result).toBeNull();
+  });
+});
+
+describe('createLiveActivityRefreshRuntime', () => {
+  it('ticks the refresh with one session-state snapshot for all entries', async () => {
+    const refreshLiveActivityTokens = vi.fn(async () => {});
+    const runtime = createLiveActivityRefreshRuntime({
+      intervalMs: LIVE_ACTIVITY_REFRESH_DEFAULT_INTERVAL_MS,
+      refreshLiveActivityTokens,
+      getSessionStateSnapshot: () => ({ ses_1: { status: 'busy' } }),
+      resolveSession: async () => null,
+    });
+    await runtime.tick();
+
+    expect(refreshLiveActivityTokens).toHaveBeenCalledTimes(1);
+    const arg = refreshLiveActivityTokens.mock.calls[0][0];
+    expect(typeof arg.computeSnapshot).toBe('function');
+    const result = await arg.computeSnapshot({
+      token: 't',
+      sessionId: 'live',
+      snapshot: [{ sessionId: 'ses_1', title: 'One', status: 'working', startedAt: 1 }],
+    });
+    expect(result).toBeNull();
+  });
+
+  it('drops overlapping ticks instead of queueing them', async () => {
+    let release;
+    const gate = new Promise((resolve) => { release = resolve; });
+    const refreshLiveActivityTokens = vi.fn(async () => { await gate; });
+    const runtime = createLiveActivityRefreshRuntime({
+      intervalMs: 1000,
+      refreshLiveActivityTokens,
+      getSessionStateSnapshot: () => ({}),
+      resolveSession: async () => null,
+    });
+    const first = runtime.tick();
+    await runtime.tick(); // overlapping → dropped
+    release();
+    await first;
+    expect(refreshLiveActivityTokens).toHaveBeenCalledTimes(1);
+  });
+
+  it('never schedules a timer when disabled (interval 0) and disposes cleanly', async () => {
+    vi.useFakeTimers();
+    const refreshLiveActivityTokens = vi.fn(async () => {});
+    const runtime = createLiveActivityRefreshRuntime({
+      intervalMs: 0,
+      refreshLiveActivityTokens,
+      getSessionStateSnapshot: () => ({}),
+      resolveSession: async () => null,
+    });
+    runtime.start();
+    await vi.advanceTimersByTimeAsync(120_000);
+    expect(refreshLiveActivityTokens).not.toHaveBeenCalled();
+
+    const enabled = createLiveActivityRefreshRuntime({
+      intervalMs: 30_000,
+      refreshLiveActivityTokens,
+      getSessionStateSnapshot: () => ({}),
+      resolveSession: async () => null,
+    });
+    enabled.start();
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(refreshLiveActivityTokens).toHaveBeenCalledTimes(1);
+    enabled.dispose();
+    await vi.advanceTimersByTimeAsync(120_000);
+    expect(refreshLiveActivityTokens).toHaveBeenCalledTimes(1);
+  });
+});