@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/shared/lib/workspace/project-settings.test.ts

@@ -0,0 +1,350 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Pins the workspace-folder settings boundary: the row -> config projection,
+ * the untrusted JSON -> patch parser, the partial UPDATE builder and the
+ * destructive folder delete. A mistake here is user-visible (a cleared path,
+ * a lost accent, a folder deleted without its sessions) and irreversible, so
+ * each branch gets a case. The legacy-project migration is pinned too: it must
+ * write once, respect its marker, and never re-run over a current database.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { createDb, type DbClient } from '@/server/lib/db/client';
+import {
+  deleteWorkspaceFolder,
+  parseFolderSettingsPatch,
+  projectConfigFromFolder,
+  updateWorkspaceFolder,
+  type WorkspaceFolderRow,
+} from '@/shared/lib/workspace/project-settings';
+import { migrateLegacyProjectSettings } from '@/shared/lib/workspace/project-settings-migration';
+import { removeDir } from '@/test-support/remove-dir';
+
+const SCHEMA = `
+  CREATE TABLE workspace_folders (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    project_path TEXT,
+    model TEXT,
+    accent_color TEXT,
+    icon TEXT,
+    custom_icon_url TEXT,
+    is_pinned INTEGER DEFAULT 0,
+    is_expanded INTEGER DEFAULT 0
+  );
+  CREATE TABLE sessions (id TEXT PRIMARY KEY, folder_id INTEGER);
+  CREATE TABLE files (id TEXT PRIMARY KEY, session_id TEXT);
+  CREATE TABLE deleted_workspaces (project_path TEXT PRIMARY KEY);
+  CREATE TABLE app_settings (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+`;
+
+let workRoot = '';
+let dbCounter = 0;
+beforeAll(() => {
+  workRoot = mkdtempSync(path.join(os.tmpdir(), 'omp-project-settings-'));
+});
+/** Connections this file opened; closed first (Windows EBUSY on delete). */
+const opened: DbClient[] = [];
+afterAll(() => {
+  for (const db of opened.splice(0)) db.raw.close();
+  removeDir(workRoot);
+});
+/** A fresh database so one test's rows cannot reach another. */
+async function freshDb(): Promise<DbClient> {
+  const db = createDb(path.join(workRoot, `db-${dbCounter++}.sqlite`));
+  opened.push(db);
+  await db.exec(SCHEMA);
+  return db;
+}
+
+async function insertFolder(db: DbClient, name: string, projectPath: string | null): Promise<number> {
+  const result = await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', [name, projectPath]);
+  return result.lastID;
+}
+
+async function folderRow(db: DbClient, id: number): Promise<Record<string, unknown> | undefined> {
+  return db.get('SELECT * FROM workspace_folders WHERE id = ?', [id]);
+}
+
+describe('projectConfigFromFolder', () => {
+  test('maps a fully populated row', () => {
+    const row: WorkspaceFolderRow = {
+      id: 7,
+      name: 'kabmo',
+      project_path: '/work/kabmo',
+      model: 'DeepSeek-V3',
+      accent_color: '#38bdf8',
+      icon: 'code',
+      custom_icon_url: 'https://cdn/icon.png',
+      is_pinned: 1,
+      is_expanded: 1,
+    };
+    expect(projectConfigFromFolder(row)).toEqual({
+      id: 'folder-7',
+      folderId: 7,
+      name: 'kabmo',
+      path: '/work/kabmo',
+      model: 'DeepSeek-V3',
+      accentColor: '#38bdf8',
+      icon: 'code',
+      customIconUrl: 'https://cdn/icon.png',
+      isPinned: true,
+      isExpanded: true,
+    });
+  });
+
+  test('substitutes documented defaults for null/empty columns', () => {
+    const config = projectConfigFromFolder({ id: 3, name: 'bare' });
+    expect(config).toEqual({
+      id: 'folder-3',
+      folderId: 3,
+      name: 'bare',
+      path: '',
+      model: 'Not selected',
+      accentColor: '',
+      icon: 'default',
+      customIconUrl: undefined,
+      isPinned: false,
+      isExpanded: false,
+    });
+  });
+
+  test('only the literal 1 flags pinned/expanded, and an empty icon url is dropped', () => {
+    const config = projectConfigFromFolder({
+      id: 1,
+      name: 'x',
+      is_pinned: 0,
+      is_expanded: null,
+      custom_icon_url: '',
+    });
+    expect(config.isPinned).toBe(false);
+    expect(config.isExpanded).toBe(false);
+    expect(config.customIconUrl).toBeUndefined();
+  });
+});
+
+describe('parseFolderSettingsPatch', () => {
+  test('non-records yield an empty patch', () => {
+    expect(parseFolderSettingsPatch(null)).toEqual({});
+    expect(parseFolderSettingsPatch('nope')).toEqual({});
+    expect(parseFolderSettingsPatch([1])).toEqual({});
+    expect(parseFolderSettingsPatch(undefined)).toEqual({});
+  });
+
+  test('trims strings and turns a blank path into an explicit null', () => {
+    expect(parseFolderSettingsPatch({ name: '  hello  ', projectPath: '  /work/x  ' })).toEqual({
+      name: 'hello',
+      projectPath: '/work/x',
+    });
+    expect(parseFolderSettingsPatch({ projectPath: '   ' })).toEqual({ projectPath: null });
+  });
+
+  test('keeps model/accent/icon verbatim and ignores non-strings', () => {
+    expect(parseFolderSettingsPatch({ model: 'gpt', accentColor: '#fff', icon: 'star', name: 5 })).toEqual({
+      model: 'gpt',
+      accentColor: '#fff',
+      icon: 'star',
+    });
+  });
+
+  test('accepts customIconUrl as a string or an explicit null', () => {
+    expect(parseFolderSettingsPatch({ customIconUrl: 'https://x/y.png' })).toEqual({ customIconUrl: 'https://x/y.png' });
+    expect(parseFolderSettingsPatch({ customIconUrl: null })).toEqual({ customIconUrl: null });
+    expect(parseFolderSettingsPatch({ customIconUrl: 3 })).toEqual({});
+  });
+
+  test('coerces boolean flags from booleans and their string forms', () => {
+    expect(parseFolderSettingsPatch({ isPinned: true, isExpanded: false })).toEqual({
+      isPinned: true,
+      isExpanded: false,
+    });
+    expect(parseFolderSettingsPatch({ isPinned: 'true', isExpanded: 'false' })).toEqual({
+      isPinned: true,
+      isExpanded: false,
+    });
+  });
+
+  test('drops flags of any other type', () => {
+    expect(parseFolderSettingsPatch({ isPinned: 1, isExpanded: 'yes' })).toEqual({});
+    expect(parseFolderSettingsPatch({})).toEqual({});
+  });
+});
+
+describe('updateWorkspaceFolder', () => {
+  test('an empty patch or an empty name performs no write', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'keep', null);
+    expect(await updateWorkspaceFolder(db, String(id), {})).toBe(false);
+    expect(await updateWorkspaceFolder(db, String(id), { name: '' })).toBe(false);
+    expect((await folderRow(db, id))?.name).toBe('keep');
+  });
+
+  test('writes only the supplied fields and encodes booleans as 1/0', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'keep', '/old');
+    const ok = await updateWorkspaceFolder(db, String(id), {
+      name: 'renamed',
+      isPinned: true,
+      isExpanded: false,
+      model: 'GPT-4o',
+    });
+    expect(ok).toBe(true);
+    const row = await folderRow(db, id);
+    expect(row?.name).toBe('renamed');
+    expect(row?.is_pinned).toBe(1);
+    expect(row?.is_expanded).toBe(0);
+    expect(row?.model).toBe('GPT-4o');
+    expect(row?.project_path).toBe('/old');
+  });
+
+  test('an explicit null projectPath clears the binding', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'bound', '/work/x');
+    expect(await updateWorkspaceFolder(db, String(id), { projectPath: null })).toBe(true);
+    expect((await folderRow(db, id))?.project_path).toBeNull();
+  });
+
+  test('returns false when the folder id does not exist', async () => {
+    const db = await freshDb();
+    expect(await updateWorkspaceFolder(db, '9999', { name: 'x' })).toBe(false);
+  });
+});
+
+describe('deleteWorkspaceFolder', () => {
+  test('returns false for an unknown folder', async () => {
+    const db = await freshDb();
+    expect(await deleteWorkspaceFolder(db, '404')).toBe(false);
+  });
+
+  test('tombstones the project path and cascades sessions and files', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'doomed', '/work/doomed');
+    const other = await insertFolder(db, 'safe', '/work/safe');
+    await db.run('INSERT INTO sessions (id, folder_id) VALUES (?, ?)', ['s1', id]);
+    await db.run('INSERT INTO sessions (id, folder_id) VALUES (?, ?)', ['s2', other]);
+    await db.run('INSERT INTO files (id, session_id) VALUES (?, ?)', ['f1', 's1']);
+    await db.run('INSERT INTO files (id, session_id) VALUES (?, ?)', ['f2', 's2']);
+
+    expect(await deleteWorkspaceFolder(db, String(id))).toBe(true);
+    expect(await folderRow(db, id)).toBeNull();
+    expect(await db.get('SELECT * FROM sessions WHERE id = ?', ['s1'])).toBeNull();
+    expect(await db.get('SELECT * FROM files WHERE id = ?', ['f1'])).toBeNull();
+    expect(await db.get('SELECT * FROM sessions WHERE id = ?', ['s2'])).toBeTruthy();
+    expect(await db.get('SELECT * FROM files WHERE id = ?', ['f2'])).toBeTruthy();
+    const tombstone = await db.get<{ project_path: string }>('SELECT project_path FROM deleted_workspaces');
+    expect(tombstone?.project_path).toBe('/work/doomed');
+  });
+
+  test('a folder without a project path is deleted without a tombstone', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'unbound', null);
+    expect(await deleteWorkspaceFolder(db, String(id))).toBe(true);
+    expect(await db.all('SELECT * FROM deleted_workspaces')).toEqual([]);
+  });
+});
+
+describe('migrateLegacyProjectSettings', () => {
+  async function seedLegacy(db: DbClient, value: string): Promise<void> {
+    await db.run('INSERT OR REPLACE INTO app_settings (key, value) VALUES (?, ?)', ['omp_projects_config', value]);
+  }
+
+  async function markerValue(db: DbClient): Promise<string | undefined> {
+    const row = await db.get<{ value: string }>('SELECT value FROM app_settings WHERE key = ?', [
+      'omp_projects_config_migrated',
+    ]);
+    return row?.value;
+  }
+
+  test('a current database (marker present) is left untouched', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'kabmo', '/work/kabmo');
+    await db.run('INSERT INTO app_settings (key, value) VALUES (?, ?)', ['omp_projects_config_migrated', '1']);
+    await seedLegacy(db, JSON.stringify([{ name: 'kabmo', path: '/work/kabmo', model: 'X' }]));
+
+    await migrateLegacyProjectSettings(db);
+    expect((await folderRow(db, id))?.model).toBeNull();
+  });
+
+  test('without a legacy row it writes nothing, marker included', async () => {
+    const db = await freshDb();
+    await migrateLegacyProjectSettings(db);
+    expect(await markerValue(db)).toBeUndefined();
+  });
+
+  test('unparseable legacy JSON aborts without marking', async () => {
+    const db = await freshDb();
+    await seedLegacy(db, '{not json');
+    await migrateLegacyProjectSettings(db);
+    expect(await markerValue(db)).toBeUndefined();
+  });
+
+  test('matches by project path and fills defaults for missing fields', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'kabmo', '/work/kabmo');
+    await seedLegacy(db, JSON.stringify([{ path: '/work/kabmo' }]));
+
+    await migrateLegacyProjectSettings(db);
+    const row = await folderRow(db, id);
+    expect(row?.model).toBe('Not selected');
+    expect(row?.accent_color).toBe('');
+    expect(row?.icon).toBe('default');
+    expect(row?.custom_icon_url).toBeNull();
+    expect(await markerValue(db)).toBe('1');
+  });
+
+  test('carries the legacy fields through when present', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'anything', '/work/x');
+    await seedLegacy(
+      db,
+      JSON.stringify([{ path: '/work/x', model: 'GPT-4o', accentColor: '#abc', icon: 'star', customIconUrl: 'https://i' }]),
+    );
+
+    await migrateLegacyProjectSettings(db);
+    const row = await folderRow(db, id);
+    expect(row?.model).toBe('GPT-4o');
+    expect(row?.accent_color).toBe('#abc');
+    expect(row?.icon).toBe('star');
+    expect(row?.custom_icon_url).toBe('https://i');
+  });
+
+  test('falls back to a case-insensitive name match', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'Kabmo', null);
+    await seedLegacy(db, JSON.stringify([{ name: 'kabmo', model: 'DeepSeek-R1' }]));
+
+    await migrateLegacyProjectSettings(db);
+    expect((await folderRow(db, id))?.model).toBe('DeepSeek-R1');
+  });
+
+  test('skips legacy entries that match no folder and still marks done', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'unrelated', '/work/other');
+    await seedLegacy(db, JSON.stringify([{ path: '/work/nowhere' }, null, 'garbage']));
+
+    await migrateLegacyProjectSettings(db);
+    expect((await folderRow(db, id))?.model).toBeNull();
+    expect(await markerValue(db)).toBe('1');
+  });
+
+  test('a non-array legacy document falls back to the default project list', async () => {
+    const db = await freshDb();
+    const id = await insertFolder(db, 'kabmo', '/Users/rajebdev/JatisMobile/kabmo');
+    await seedLegacy(db, JSON.stringify({ projects: [] }));
+
+    await migrateLegacyProjectSettings(db);
+    const row = await folderRow(db, id);
+    expect(row?.model).toBe('Not selected');
+    expect(row?.accent_color).toBe('#38bdf8');
+    expect(row?.icon).toBe('default');
+    expect(await markerValue(db)).toBe('1');
+  });
+});

package/src/shared/lib/workspace/project-settings.ts

@@ -0,0 +1,139 @@
+import type { DbClient } from '@/server/lib/db/client';
+import type { ProjectConfigItem } from '@/shared/types';
+import { isRecord } from '@/shared/lib/util/guards';
+
+export interface WorkspaceFolderRow {
+  id: number;
+  name: string;
+  project_path?: string | null;
+  model?: string | null;
+  accent_color?: string | null;
+  icon?: string | null;
+  custom_icon_url?: string | null;
+  is_pinned?: number | null;
+  is_expanded?: number | null;
+}
+
+export interface FolderSettingsPatch {
+  name?: string;
+  projectPath?: string | null;
+  model?: string;
+  accentColor?: string;
+  icon?: string;
+  customIconUrl?: string | null;
+  isPinned?: boolean;
+  isExpanded?: boolean;
+}
+
+export function projectConfigFromFolder(folder: WorkspaceFolderRow): ProjectConfigItem {
+  return {
+    id: `folder-${folder.id}`,
+    folderId: folder.id,
+    name: folder.name,
+    path: folder.project_path ?? '',
+    model: folder.model || 'Not selected',
+    accentColor: folder.accent_color || '',
+    icon: folder.icon || 'default',
+    customIconUrl: folder.custom_icon_url || undefined,
+    isPinned: folder.is_pinned === 1,
+    isExpanded: folder.is_expanded === 1,
+  };
+}
+
+function readBoolean(value: unknown): boolean | undefined {
+  if (typeof value === 'boolean') return value;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return undefined;
+}
+
+export function parseFolderSettingsPatch(value: unknown): FolderSettingsPatch {
+  if (!isRecord(value)) return {};
+
+  const patch: FolderSettingsPatch = {};
+  if (typeof value.name === 'string') patch.name = value.name.trim();
+  if (typeof value.projectPath === 'string') patch.projectPath = value.projectPath.trim() || null;
+  if (typeof value.model === 'string') patch.model = value.model;
+  if (typeof value.accentColor === 'string') patch.accentColor = value.accentColor;
+  if (typeof value.icon === 'string') patch.icon = value.icon;
+  if (typeof value.customIconUrl === 'string') patch.customIconUrl = value.customIconUrl;
+  if (value.customIconUrl === null) patch.customIconUrl = null;
+
+  const isPinned = readBoolean(value.isPinned);
+  if (isPinned !== undefined) patch.isPinned = isPinned;
+  const isExpanded = readBoolean(value.isExpanded);
+  if (isExpanded !== undefined) patch.isExpanded = isExpanded;
+
+  return patch;
+}
+
+export async function updateWorkspaceFolder(
+  db: DbClient,
+  folderId: string,
+  patch: FolderSettingsPatch,
+): Promise<boolean> {
+  const assignments: string[] = [];
+  const values: Array<string | number | null> = [];
+
+  if (patch.name !== undefined && patch.name !== '') {
+    assignments.push('name = ?');
+    values.push(patch.name);
+  }
+  if (patch.projectPath !== undefined) {
+    assignments.push('project_path = ?');
+    values.push(patch.projectPath);
+  }
+  if (patch.model !== undefined) {
+    assignments.push('model = ?');
+    values.push(patch.model);
+  }
+  if (patch.accentColor !== undefined) {
+    assignments.push('accent_color = ?');
+    values.push(patch.accentColor);
+  }
+  if (patch.icon !== undefined) {
+    assignments.push('icon = ?');
+    values.push(patch.icon);
+  }
+  if (patch.customIconUrl !== undefined) {
+    assignments.push('custom_icon_url = ?');
+    values.push(patch.customIconUrl);
+  }
+  if (patch.isPinned !== undefined) {
+    assignments.push('is_pinned = ?');
+    values.push(patch.isPinned ? 1 : 0);
+  }
+  if (patch.isExpanded !== undefined) {
+    assignments.push('is_expanded = ?');
+    values.push(patch.isExpanded ? 1 : 0);
+  }
+
+  if (assignments.length === 0) return false;
+
+  values.push(folderId);
+  const result = await db.run(
+    `UPDATE workspace_folders SET ${assignments.join(', ')} WHERE id = ?`,
+    values,
+  );
+  return Boolean(result.changes);
+}
+
+export async function deleteWorkspaceFolder(db: DbClient, folderId: string): Promise<boolean> {
+  const folder = await db.get('SELECT id, project_path FROM workspace_folders WHERE id = ?', [folderId]);
+  if (!folder) return false;
+
+  if (folder.project_path) {
+    await db.run(
+      'INSERT OR REPLACE INTO deleted_workspaces (project_path) VALUES (?)',
+      [folder.project_path],
+    );
+  }
+
+  const sessionRows = await db.all('SELECT id FROM sessions WHERE folder_id = ?', [folderId]);
+  for (const session of sessionRows) {
+    await db.run('DELETE FROM files WHERE session_id = ?', [session.id]);
+  }
+  await db.run('DELETE FROM sessions WHERE folder_id = ?', [folderId]);
+  await db.run('DELETE FROM workspace_folders WHERE id = ?', [folderId]);
+  return true;
+}

package/src/shared/lib/workspace/refresh-cadence.test.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Pins the two time-shaped contracts Kabmo reasons about everywhere.
+ *
+ * `refresh-cadence.ts` is the single table every poll/throttle reads, so a
+ * value drifting (or two related values crossing) changes how often the app
+ * touches disk and network. The retry schedule's length, monotonicity and sum
+ * are what the spawn-wait budget is documented as.
+ *
+ * `relativeTimeAgo` is the only place a sidebar row's age is rendered, so each
+ * bucket boundary and the year cutoff are pinned rather than the implementation.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  BROWSER_POLL_MS,
+  SESSION_META_RETRY_SCHEDULE_MS,
+  SIDEBAR_DATA_TTL_MS,
+  STREAM_HEARTBEAT_MS,
+} from '@/shared/lib/workspace/refresh-cadence';
+import { relativeTimeAgo } from '@/shared/lib/workspace/relative-time';
+
+describe('refresh cadences', () => {
+  test('the documented millisecond values', () => {
+    expect(BROWSER_POLL_MS).toBe(1_000);
+    expect(STREAM_HEARTBEAT_MS).toBe(30_000);
+  });
+
+  test('the sidebar dataset TTL stays short', () => {
+    // The sidebar rides the realtime socket, so nothing polls this cache; the
+    // TTL only dedupes concurrent resolves of one publish burst, and a
+    // structure publish invalidates it outright.
+    expect(SIDEBAR_DATA_TTL_MS).toBe(4_000);
+  });
+
+  test('the spawn retry schedule is front-loaded, non-decreasing and finite', () => {
+    const schedule = SESSION_META_RETRY_SCHEDULE_MS;
+    expect(schedule).toHaveLength(12);
+    expect(schedule[0]).toBe(250);
+    for (let i = 1; i < schedule.length; i++) {
+      expect(schedule[i]).toBeGreaterThanOrEqual(schedule[i - 1]);
+    }
+    // Documented budget: 13 attempts over ~15.5s.
+    const total = schedule.reduce((sum, delay) => sum + delay, 0);
+    expect(total).toBe(15_500);
+    expect(schedule.length + 1).toBe(13);
+  });
+});
+
+describe('relativeTimeAgo', () => {
+  const now = Date.UTC(2026, 0, 15, 12, 0, 0);
+  const ago = (ms: number): string | null => relativeTimeAgo(now - ms, now);
+
+  const SECOND = 1_000;
+  const MINUTE = 60 * SECOND;
+  const HOUR = 60 * MINUTE;
+  const DAY = 24 * HOUR;
+
+  test('missing or unparseable input yields null', () => {
+    expect(relativeTimeAgo(null, now)).toBeNull();
+    expect(relativeTimeAgo(undefined, now)).toBeNull();
+    expect(relativeTimeAgo('', now)).toBeNull();
+    expect(relativeTimeAgo('not a date', now)).toBeNull();
+  });
+
+  test('a future timestamp still reads as now', () => {
+    expect(relativeTimeAgo(now + 5 * MINUTE, now)).toBe('now');
+  });
+
+  test('the sub-minute bucket covers up to 44s', () => {
+    expect(ago(0)).toBe('now');
+    expect(ago(30 * SECOND)).toBe('now');
+    expect(ago(44 * SECOND)).toBe('now');
+  });
+
+  test('minute/hour/day/week buckets at their boundaries', () => {
+    expect(ago(45 * SECOND)).toBe('1m');
+    expect(ago(59 * SECOND)).toBe('1m');
+    expect(ago(30 * MINUTE)).toBe('30m');
+    expect(ago(59 * MINUTE)).toBe('59m');
+    expect(ago(HOUR)).toBe('1h');
+    expect(ago(23 * HOUR)).toBe('23h');
+    expect(ago(DAY)).toBe('1d');
+    expect(ago(6 * DAY)).toBe('6d');
+    expect(ago(7 * DAY)).toBe('1w');
+    expect(ago(28 * DAY)).toBe('4w');
+  });
+
+  test('past five weeks it falls back to a calendar date', () => {
+    // 35 days before 2026-01-15 is 2025-12-11: same-year? No — a different
+    // year, so the year is appended.
+    expect(ago(35 * DAY)).toBe('11 Dec 2025');
+    // 56 days before is 2025-11-20, still a different year.
+    expect(ago(56 * DAY)).toBe('20 Nov 2025');
+  });
+
+  test('a same-year date older than five weeks omits the year', () => {
+    const later = Date.UTC(2026, 8, 30, 12, 0, 0);
+    expect(relativeTimeAgo(Date.UTC(2026, 2, 3, 6, 0, 0), later)).toBe('3 Mar');
+  });
+
+  test('parses an ISO string the same as its epoch millis', () => {
+    const iso = '2026-01-15T11:30:00.000Z';
+    expect(relativeTimeAgo(iso, now)).toBe(relativeTimeAgo(Date.parse(iso), now));
+    expect(relativeTimeAgo(iso, now)).toBe('30m');
+  });
+
+  test('defaults `now` to the wall clock', () => {
+    expect(relativeTimeAgo(Date.now(), Date.now())).toBe('now');
+    expect(relativeTimeAgo(Date.now() - 5 * MINUTE)).toBe('5m');
+  });
+});

package/src/shared/lib/workspace/refresh-cadence.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Single source of truth for the timings Kabmo still reasons about.
+ *
+ * Most of what used to live here is gone: the panel, sidebar, git, schedule and
+ * repo-discovery polls were replaced by the realtime socket's topics, so only
+ * the CDP screencast poll, the transports' keepalive, the server-side dataset
+ * TTL and the spawn retry backoff remain.
+ *
+ * Keep them here so a cost/freshness trade-off can be reasoned about in one
+ * place. Imported by client hooks, shared browser modules, and server routes
+ * alike — this module must stay free of `node:`/`Bun.*` imports.
+ */
+
+/**
+ * Nested-repo discovery and the sidebar's schedule badge both ride realtime
+ * topics (`repos:<root>`, the schedule topic), so neither has a poll cadence
+ * here: the server republishes the moment the underlying state changes.
+ */
+
+/**
+ * CDP state/screencast poll. Latency-sensitive — the browser panel streams a
+ * live page, so this one stays tight on purpose.
+ */
+export const BROWSER_POLL_MS = 1_000;
+
+/**
+ * Keep-alive comment frame for long-lived SSE/WS transports (agent bridge and
+ * browser stream). Not a data refresh — it keeps proxies from reaping an idle
+ * connection.
+ */
+export const STREAM_HEARTBEAT_MS = 30_000;
+
+/**
+ * TTL for the server-side sidebar dataset scan (`loadOmpSidebarData`). Nothing
+ * polls this cache — the sidebar rides the realtime socket — so the TTL only
+ * dedupes concurrent resolves of one publish burst; a structure publish
+ * invalidates it outright.
+ */
+export const SIDEBAR_DATA_TTL_MS = 4_000;
+
+/**
+ * Retry backoff (ms) used while waiting for a freshly spawned omp session's
+ * JSONL to carry the user turn. Each entry is the delay BEFORE the next
+ * attempt; attempt 1 runs immediately, so the total attempt count is
+ * `length + 1` and the elapsed budget is the sum (~15.5s over 13 attempts).
+ *
+ * Front-loaded on purpose: omp usually writes the turn within a second, so the
+ * early 250ms probes land the real title fast, while the 2s tail keeps watching
+ * a slow spawn without spending 40 requests to do it.
+ */
+export const SESSION_META_RETRY_SCHEDULE_MS: readonly number[] = [
+  250, 250, 500, 500, 1_000, 1_000, 2_000, 2_000, 2_000, 2_000, 2_000, 2_000,
+];

package/src/shared/lib/workspace/relative-time.ts

@@ -0,0 +1,25 @@
+/** Compact relative age for sidebar rows: `now`, `5m`, `3h`, `2d`, `6w`, or a
+ *  `DD MMM` date once the timestamp is older than a year. Returns null for a
+ *  missing/unparseable timestamp so callers can omit the column entirely. */
+export function relativeTimeAgo(value: string | number | null | undefined, now: number = Date.now()): string | null {
+  if (value === null || value === undefined || value === '') return null;
+  const ms = typeof value === 'number' ? value : Date.parse(value);
+  if (Number.isNaN(ms)) return null;
+
+  const seconds = Math.round((now - ms) / 1000);
+  if (seconds < 45) return 'now';
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.round(hours / 24);
+  if (days < 7) return `${days}d`;
+  const weeks = Math.round(days / 7);
+  if (weeks < 5) return `${weeks}w`;
+
+  const date = new Date(ms);
+  const sameYear = date.getFullYear() === new Date(now).getFullYear();
+  const day = date.getDate();
+  const month = date.toLocaleString('en-US', { month: 'short' });
+  return sameYear ? `${day} ${month}` : `${day} ${month} ${date.getFullYear()}`;
+}