@openchambery/web 1.18.2-beta.4 → 1.18.2-beta.40

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

@@ -0,0 +1,176 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createNotificationTriggerRuntime } from './runtime.js';
+
+const defaultSettings = {
+  notifyOnCompletion: true,
+  notifyOnQuestion: true,
+  notificationMode: 'always',
+  nativeNotificationsEnabled: true,
+};
+
+const createRuntime = (overrides = {}) => {
+  const emitDesktopNotification = vi.fn(() => true);
+  const broadcastUiNotification = vi.fn();
+  const sendPushToAllUiSessions = vi.fn(async () => {});
+  const sendApnsToAllUiSessions = vi.fn(async () => {});
+  const runtime = createNotificationTriggerRuntime({
+    readSettingsFromDisk: vi.fn(async () => defaultSettings),
+    prepareNotificationLastMessage: vi.fn(async ({ message }) => message || ''),
+    buildTemplateVariables: vi.fn(async () => ({ session_name: 'Session' })),
+    extractLastMessageText: vi.fn(() => ''),
+    fetchLastAssistantMessageText: vi.fn(async () => ''),
+    resolveNotificationTemplate: vi.fn((template) => template),
+    shouldApplyResolvedTemplateMessage: vi.fn(() => true),
+    emitDesktopNotification,
+    broadcastUiNotification,
+    sendPushToAllUiSessions,
+    sendApnsToAllUiSessions,
+    isAnyInteractiveClientVisible: () => false,
+    buildOpenCodeUrl: (path) => `http://opencode.test${path}`,
+    getOpenCodeAuthHeaders: () => ({}),
+    getIsWindowFocused: () => false,
+    ...overrides,
+  });
+  return {
+    runtime,
+    emitDesktopNotification,
+    broadcastUiNotification,
+    sendPushToAllUiSessions,
+    sendApnsToAllUiSessions,
+  };
+};
+
+const jsonResponse = (body, status = 200) => new Response(JSON.stringify(body), {
+  status,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe('notification trigger runtime smallModel suppression', () => {
+  it('skips ready notifications for smallModel sessions', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+      id: 'ses_small',
+      parentID: null,
+      metadata: { openchamber: { smallModel: { purpose: 'session-title' } } },
+    })));
+
+    const { runtime, emitDesktopNotification, sendPushToAllUiSessions } = createRuntime();
+    await runtime.maybeSendPushForTrigger({
+      type: 'message.updated',
+      properties: {
+        directory: '/repo',
+        info: {
+          id: 'msg_1',
+          sessionID: 'ses_small',
+          role: 'assistant',
+          finish: 'stop',
+          mode: 'build',
+          modelID: 'small',
+        },
+      },
+    });
+
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+    expect(sendPushToAllUiSessions).not.toHaveBeenCalled();
+  });
+
+  it('skips ready notifications synthesized from session.idle for smallModel sessions', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+      id: 'ses_small',
+      parentID: null,
+      metadata: { openchamber: { smallModel: { purpose: 'commit' } } },
+    })));
+
+    const { runtime, emitDesktopNotification, sendPushToAllUiSessions } = createRuntime();
+    await runtime.maybeSendPushForTrigger({
+      type: 'session.idle',
+      properties: {
+        directory: '/repo',
+        sessionID: 'ses_small',
+      },
+    });
+
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+    expect(sendPushToAllUiSessions).not.toHaveBeenCalled();
+  });
+
+  it('skips question notifications for smallModel sessions', async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+      id: 'ses_small',
+      parentID: null,
+      metadata: { openchamber: { smallModel: { purpose: 'session-title' } } },
+    })));
+
+    const { runtime, emitDesktopNotification, sendPushToAllUiSessions } = createRuntime();
+    await runtime.maybeSendPushForTrigger({
+      type: 'question.asked',
+      properties: {
+        directory: '/repo',
+        sessionID: 'ses_small',
+        questions: [{ header: 'Input needed', question: 'Continue?' }],
+      },
+    });
+    await vi.runAllTimersAsync();
+
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+    expect(sendPushToAllUiSessions).not.toHaveBeenCalled();
+  });
+
+  it('skips permission notifications for smallModel sessions', async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+      id: 'ses_small',
+      parentID: null,
+      metadata: { openchamber: { smallModel: { purpose: 'session-title' } } },
+    })));
+
+    const { runtime, emitDesktopNotification, sendPushToAllUiSessions } = createRuntime();
+    await runtime.maybeSendPushForTrigger({
+      type: 'permission.asked',
+      properties: {
+        directory: '/repo',
+        sessionID: 'ses_small',
+        id: 'perm_1',
+        permission: 'edit',
+      },
+    });
+    await vi.runAllTimersAsync();
+
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+    expect(sendPushToAllUiSessions).not.toHaveBeenCalled();
+  });
+
+  it('still notifies ordinary root sessions', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+      id: 'ses_root',
+      parentID: null,
+      title: 'Ordinary',
+      metadata: {},
+    })));
+
+    const { runtime, emitDesktopNotification, sendPushToAllUiSessions } = createRuntime();
+    await runtime.maybeSendPushForTrigger({
+      type: 'message.updated',
+      properties: {
+        directory: '/repo',
+        info: {
+          id: 'msg_2',
+          sessionID: 'ses_root',
+          role: 'assistant',
+          finish: 'stop',
+          mode: 'build',
+          modelID: 'gpt',
+        },
+      },
+    });
+
+    expect(emitDesktopNotification).toHaveBeenCalledTimes(1);
+    expect(sendPushToAllUiSessions).toHaveBeenCalledTimes(1);
+  });
+});

package/server/lib/opencode/DOCUMENTATION.md

@@ -28,7 +28,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/static-routes-runtime.js`: static asset/SPA fallback route registration and manifest route wiring.
 - `packages/web/server/lib/opencode/feature-routes-runtime.js`: feature route composition runtime for dynamic import-backed config/skill/provider route registration.
 - `packages/web/server/lib/conversations/`: combined create-session-and-prompt orchestration (OpenChamber-owned, registered before generic proxy).
-- `packages/web/server/lib/session-turn-pages/`: turn-window session message pagination (`GET /api/openchamber/sessions/:sessionID/messages`) and anchor reconcile (`GET .../messages/reconcile`); loops official OpenCode `session.messages` for turn pages and head→anchor gap recovery with continuation/budgets/`resetRequired`; registered before generic proxy. See `session-turn-pages/DOCUMENTATION.md`.
+- `packages/web/server/lib/session-turn-pages/`: turn-window session message pagination (`GET /api/openchamber/sessions/:sessionID/messages`), anchor reconcile (`GET .../messages/reconcile`), Changes L2/L3 (`GET .../changes`), and exact message L1 projection (`GET /api/session/:sessionID/message/:messageID`); loops official OpenCode `session.messages` for turn pages and head→anchor gap recovery with continuation/budgets/`resetRequired`; all registered before generic proxy. L1 first-packet / SSE / exact-message paths keep `summary.diffs` as a slim `{ file, status?, additions, deletions }` list plus additive `diffCount`/`hasDiffs` (patch bodies stay on L3). See `session-turn-pages/DOCUMENTATION.md`.
 - `packages/web/server/lib/opencode/opencode-resolution-runtime.js`: OpenCode binary resolution snapshot runtime for settings routes and diagnostics.
 - `packages/web/server/lib/opencode/tunnel-wiring-runtime.js`: active loopback-port wiring shared by pairing/LAN URLs and the private relay host.
 - `packages/web/server/lib/opencode/startup-pipeline-runtime.js`: server startup tail orchestration runtime for terminal/proxy/static/start-listen flow.

package/server/lib/opencode/feature-routes-runtime.test.js

@@ -27,10 +27,19 @@ describe('feature routes runtime composition', () => {
     const source = await fs.readFile(new URL('./feature-routes-runtime.js', import.meta.url), 'utf8');
     expect(source).toContain("import { registerSessionTurnPageRoutes } from '../session-turn-pages/routes.js';");
     expect(source).toMatch(/registerSessionTurnPageRoutes\(app, \{[\s\S]*buildOpenCodeUrl,[\s\S]*getOpenCodeAuthHeaders,/);
-    // OpenChamber-owned turn-page/reconcile registration comment + call stay before end of feature composition.
+    // OpenChamber-owned turn-page/reconcile/changes/exact-message registration stays before end of feature composition.
     expect(source).toContain('// OpenChamber-owned turn-window messages API — must register before generic proxy.');
     const turnIdx = source.indexOf('registerSessionTurnPageRoutes(app,');
     expect(turnIdx).toBeGreaterThan(-1);
+    // Exact message + Changes live inside registerSessionTurnPageRoutes (same Host composition Electron reuses).
+    const routesSource = await fs.readFile(new URL('../session-turn-pages/routes.js', import.meta.url), 'utf8');
+    expect(routesSource).toContain("app.get('/api/session/:sessionID/message/:messageID'");
+    expect(routesSource).toContain("app.get('/api/openchamber/sessions/:sessionID/changes'");
+    const exactIdx = routesSource.indexOf("app.get('/api/session/:sessionID/message/:messageID'");
+    const changesIdx = routesSource.indexOf("app.get('/api/openchamber/sessions/:sessionID/changes'");
+    const messagesIdx = routesSource.indexOf("app.get('/api/openchamber/sessions/:sessionID/messages'");
+    expect(exactIdx).toBeGreaterThan(messagesIdx);
+    expect(changesIdx).toBeGreaterThan(exactIdx);
   });
 
   it('removes broken SSE clients while continuing worktree topology broadcasts', () => {

package/server/lib/session-index/DOCUMENTATION.md

@@ -13,14 +13,20 @@ newest 20 root-session summaries per runtime and directory. It never stores
 messages, attachments, permissions, provider data, or model metadata.
 Sessions titled `smartfetch-secondary` are temporary SmartFetch model calls;
 the index excludes them from every snapshot and clears prior summaries when a
-matching session update arrives. System-owned sessions are excluded by
-authoritative metadata only: a non-empty
-`metadata.openchamber.assistant.assistantID` or
-`metadata.openchamber.scheduledTask.taskID`. Title prefixes are human labels and
-never participate in this filter. Metadata is the ownership/isolation signal;
-`time.archived` is archive state; titles are for recognition. The index does
+  matching session update arrives. System-owned sessions are excluded by
+  authoritative metadata only: a non-empty
+  `metadata.openchamber.assistant.assistantID`,
+  `metadata.openchamber.scheduledTask.taskID`, or
+  `metadata.openchamber.smallModel.purpose`. Title prefixes are human labels and
+  never participate in this filter. Metadata is the ownership/isolation signal;
+`time.archived` is archive state; `time.pinned` is OpenChamber-owned pin state
+(persisted as `pinned_at`, rescued across directory rebuilds, never overwritten
+by live OpenCode upserts); titles are for recognition. The index does
 not cache system sessions, so cold-start and live upserts stay aligned with
 ordinary sidebar lists.
+Pin and unpin use `POST` / `DELETE`
+`/api/openchamber/session-index/session/:id/pin`, update `pinned_at`, then
+`publishChange()` so revision tips broadcast `openchamber:session-index-changed`.
 
 The server-side global OpenCode event subscriber writes session summary events
 directly into this index. User `message.updated` events and `session.idle`

package/server/lib/session-index/routes.js

@@ -62,4 +62,38 @@ export const registerSessionIndexRoutes = (app, { sessionIndexService, sessionIn
     }
     res.json({ available: true, session: hit });
   });
+
+  app.post('/api/openchamber/session-index/session/:id/pin', (req, res) => {
+    if (!sessionIndexService) return unsupported(res);
+    if (typeof sessionIndexService.setPinned !== 'function') {
+      return res.status(501).json({ error: 'Session pin is unavailable' });
+    }
+    const sessionId = req.params.id;
+    if (typeof sessionId !== 'string' || !sessionId.trim()) {
+      return res.status(400).json({ error: 'sessionId is required' });
+    }
+    const changed = sessionIndexService.setPinned(sessionId.trim());
+    if (!changed) {
+      return res.status(404).json({ error: 'session_not_found', sessionId: sessionId.trim() });
+    }
+    sessionIndexSyncRuntime?.publishChange?.();
+    res.status(204).end();
+  });
+
+  app.delete('/api/openchamber/session-index/session/:id/pin', (req, res) => {
+    if (!sessionIndexService) return unsupported(res);
+    if (typeof sessionIndexService.clearPinned !== 'function') {
+      return res.status(501).json({ error: 'Session unpin is unavailable' });
+    }
+    const sessionId = req.params.id;
+    if (typeof sessionId !== 'string' || !sessionId.trim()) {
+      return res.status(400).json({ error: 'sessionId is required' });
+    }
+    const changed = sessionIndexService.clearPinned(sessionId.trim());
+    if (!changed) {
+      return res.status(404).json({ error: 'session_not_found', sessionId: sessionId.trim() });
+    }
+    sessionIndexSyncRuntime?.publishChange?.();
+    res.status(204).end();
+  });
 };

package/server/lib/session-index/routes.test.js

@@ -137,4 +137,80 @@ describe('session index routes', () => {
     expect(res.statusCode).toBe(404);
     expect(res.body).toMatchObject({ error: 'session_not_found' });
   });
+
+  it('pins a session and publishes a session-index change', () => {
+    const { app, route } = registry();
+    const setPinned = vi.fn(() => true);
+    const publishChange = vi.fn();
+    registerSessionIndexRoutes(app, {
+      sessionIndexService: {
+        snapshot: () => ({ directories: [] }),
+        setPinned,
+      },
+      sessionIndexSyncRuntime: { publishChange },
+    });
+    const res = response();
+
+    route('POST', '/api/openchamber/session-index/session/:id/pin')(
+      { params: { id: 'ses_abc' } },
+      res,
+    );
+
+    expect(setPinned).toHaveBeenCalledWith('ses_abc');
+    expect(publishChange).toHaveBeenCalledTimes(1);
+    expect(res.statusCode).toBe(204);
+  });
+
+  it('unpins a session and publishes a session-index change', () => {
+    const { app, route } = registry();
+    const clearPinned = vi.fn(() => true);
+    const publishChange = vi.fn();
+    registerSessionIndexRoutes(app, {
+      sessionIndexService: {
+        snapshot: () => ({ directories: [] }),
+        clearPinned,
+      },
+      sessionIndexSyncRuntime: { publishChange },
+    });
+    const res = response();
+
+    route('DELETE', '/api/openchamber/session-index/session/:id/pin')(
+      { params: { id: 'ses_abc' } },
+      res,
+    );
+
+    expect(clearPinned).toHaveBeenCalledWith('ses_abc');
+    expect(publishChange).toHaveBeenCalledTimes(1);
+    expect(res.statusCode).toBe(204);
+  });
+
+  it('returns 404 for pin and unpin when the session is missing', () => {
+    const { app, route } = registry();
+    const publishChange = vi.fn();
+    registerSessionIndexRoutes(app, {
+      sessionIndexService: {
+        snapshot: () => ({ directories: [] }),
+        setPinned: () => false,
+        clearPinned: () => false,
+      },
+      sessionIndexSyncRuntime: { publishChange },
+    });
+
+    const pinRes = response();
+    route('POST', '/api/openchamber/session-index/session/:id/pin')(
+      { params: { id: 'ses_missing' } },
+      pinRes,
+    );
+    expect(pinRes.statusCode).toBe(404);
+    expect(pinRes.body).toMatchObject({ error: 'session_not_found' });
+
+    const unpinRes = response();
+    route('DELETE', '/api/openchamber/session-index/session/:id/pin')(
+      { params: { id: 'ses_missing' } },
+      unpinRes,
+    );
+    expect(unpinRes.statusCode).toBe(404);
+    expect(unpinRes.body).toMatchObject({ error: 'session_not_found' });
+    expect(publishChange).not.toHaveBeenCalled();
+  });
 });

package/server/lib/session-index/service.js

@@ -15,6 +15,7 @@ const isSystemSession = (session) => {
   if (!openchamber || typeof openchamber !== 'object') return false;
   if (nonEmptySystemID(openchamber.assistant?.assistantID)) return true;
   if (nonEmptySystemID(openchamber.scheduledTask?.taskID)) return true;
+  if (nonEmptySystemID(openchamber.smallModel?.purpose)) return true;
   return false;
 };
 
@@ -116,6 +117,7 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
       updated_at INTEGER NOT NULL,
       activity_updated_at INTEGER NOT NULL,
       archived_at INTEGER NOT NULL DEFAULT 0,
+      pinned_at INTEGER,
       status TEXT,
       status_changed_at INTEGER NOT NULL DEFAULT 0,
       parent_id TEXT,
@@ -139,6 +141,12 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
     CREATE INDEX IF NOT EXISTS session_child_parent
       ON session_child(runtime_key, directory, parent_id);
   `);
+  const sessionSummaryColumns = new Set(
+    db.prepare("SELECT name FROM pragma_table_info('session_summary')").all().map((column) => column.name),
+  );
+  if (!sessionSummaryColumns.has('pinned_at')) {
+    db.exec('ALTER TABLE session_summary ADD COLUMN pinned_at INTEGER');
+  }
   db.prepare('INSERT OR REPLACE INTO session_index_meta(key, value) VALUES (?, ?)')
     .run('schema_version', String(SCHEMA_VERSION));
 
@@ -165,7 +173,7 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
   const deleteDirectoryRows = db.prepare('DELETE FROM session_summary WHERE runtime_key = ? AND directory = ?');
   const existingSummaryState = db.prepare(`
     SELECT session_id, has_children AS hasChildren, activity_updated_at AS activityUpdatedAt,
-      status, status_changed_at AS statusChangedAt
+      status, status_changed_at AS statusChangedAt, pinned_at AS pinnedAt
     FROM session_summary WHERE runtime_key = ? AND directory = ?
   `);
   const readSummary = db.prepare(`
@@ -183,8 +191,8 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
     LIMIT 1 OFFSET ?
   `);
   const insertSummary = db.prepare(`
-    INSERT INTO session_summary(runtime_key, directory, session_id, title, created_at, updated_at, activity_updated_at, archived_at, status, status_changed_at, parent_id, has_children, assistant_id, assistant_name)
-    VALUES (@runtimeKey, @directory, @id, @title, @createdAt, @updatedAt, @activityUpdatedAt, @archivedAt, @status, @statusChangedAt, @parentID, @hasChildren, @assistantID, @assistantName)
+    INSERT INTO session_summary(runtime_key, directory, session_id, title, created_at, updated_at, activity_updated_at, archived_at, pinned_at, status, status_changed_at, parent_id, has_children, assistant_id, assistant_name)
+    VALUES (@runtimeKey, @directory, @id, @title, @createdAt, @updatedAt, @activityUpdatedAt, @archivedAt, @pinnedAt, @status, @statusChangedAt, @parentID, @hasChildren, @assistantID, @assistantName)
   `);
   const upsertSummary = db.prepare(`
     INSERT INTO session_summary(runtime_key, directory, session_id, title, created_at, updated_at, activity_updated_at, archived_at, status, status_changed_at, parent_id, has_children, assistant_id, assistant_name)
@@ -259,6 +267,7 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
       insertSummary.run({
         ...summary,
         activityUpdatedAt: Math.max(summary.activityUpdatedAt, toTimestamp(previous?.activityUpdatedAt)),
+        pinnedAt: previous?.pinnedAt != null ? toTimestamp(previous.pinnedAt) : null,
         status: typeof previous?.status === 'string' ? previous.status : null,
         statusChangedAt: toTimestamp(previous?.statusChangedAt),
         hasChildren: toBooleanInt(summary.hasChildren ?? Boolean(previous?.hasChildren)),
@@ -364,6 +373,7 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
       sessions: db.prepare(`
         SELECT session_id AS id, title, created_at AS createdAt, updated_at AS updatedAt,
           activity_updated_at AS activityUpdatedAt, archived_at AS archivedAt,
+          pinned_at AS pinnedAt,
           status, status_changed_at AS statusChangedAt, parent_id AS parentID,
           has_children AS hasChildren, assistant_id AS assistantID, assistant_name AS assistantName
         FROM session_summary WHERE runtime_key = ? AND directory = ?
@@ -373,7 +383,12 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
           id: session.id,
           title: session.title,
           directory: directory.directory,
-          time: { created: session.createdAt, updated: session.updatedAt, ...(session.archivedAt ? { archived: session.archivedAt } : {}) },
+          time: {
+            created: session.createdAt,
+            updated: session.updatedAt,
+            ...(session.archivedAt ? { archived: session.archivedAt } : {}),
+            ...(session.pinnedAt ? { pinned: session.pinnedAt } : {}),
+          },
           metadata: {
             openchamber: {
               titleRefresh: { activityUpdatedAt: session.activityUpdatedAt },
@@ -465,6 +480,38 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
     return result.changes > 0;
   };
 
+  const summaryExists = db.prepare(`
+    SELECT 1 AS present FROM session_summary
+    WHERE runtime_key = ? AND session_id = ?
+    LIMIT 1
+  `);
+
+  const setPinned = (sessionID, pinnedAt = Date.now()) => {
+    if (typeof sessionID !== 'string' || !sessionID) return false;
+    const timestamp = toTimestamp(pinnedAt);
+    if (!timestamp) return false;
+    const key = runtimeKey();
+    if (!summaryExists.get(key, sessionID)) return false;
+    db.prepare(`
+      UPDATE session_summary
+      SET pinned_at = ?
+      WHERE runtime_key = ? AND session_id = ?
+    `).run(timestamp, key, sessionID);
+    return true;
+  };
+
+  const clearPinned = (sessionID) => {
+    if (typeof sessionID !== 'string' || !sessionID) return false;
+    const key = runtimeKey();
+    if (!summaryExists.get(key, sessionID)) return false;
+    db.prepare(`
+      UPDATE session_summary
+      SET pinned_at = NULL
+      WHERE runtime_key = ? AND session_id = ?
+    `).run(key, sessionID);
+    return true;
+  };
+
   const replaceChildSessions = db.transaction((directory, parentSessionID, children) => {
     const normalizedDirectory = normalizeDirectory(directory);
     if (!normalizedDirectory || typeof parentSessionID !== 'string' || !parentSessionID) return false;
@@ -487,6 +534,8 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
     upsertAndReportChange,
     touchActivity,
     updateStatus,
+    setPinned,
+    clearPinned,
     remove,
     findBySessionId,
     replaceChildSessions,

package/server/lib/session-index/service.test.js

@@ -68,7 +68,7 @@ describe('Electron session index', () => {
     service.close();
   });
 
-  it('excludes Assistant and Scheduled system sessions from ordinary sidebar summaries', () => {
+  it('excludes Assistant, Scheduled, and smallModel system sessions from ordinary sidebar summaries', () => {
     const runtimeRef = { value: 'http://runtime-a.test' };
     const service = createService(runtimeRef);
     const assistantSession = {
@@ -79,11 +79,15 @@ describe('Electron session index', () => {
       ...session('ses_scheduled', 99),
       metadata: { openchamber: { scheduledTask: { taskID: 'task_1' } } },
     };
+    const smallModelSession = {
+      ...session('ses_small_model', 97),
+      metadata: { openchamber: { smallModel: { purpose: 'session-title' } } },
+    };
     const ordinary = session('ses_ordinary', 98);
 
     service.replaceDirectory({
       directory: '/repo',
-      sessions: [assistantSession, scheduledSession, ordinary],
+      sessions: [assistantSession, scheduledSession, smallModelSession, ordinary],
       cursor: null,
       hasMore: false,
     });
@@ -91,6 +95,7 @@ describe('Electron session index', () => {
 
     service.upsert(assistantSession);
     service.upsert(scheduledSession);
+    service.upsert(smallModelSession);
     expect(service.snapshot().directories[0].sessions.map((item) => item.id)).toEqual(['ses_ordinary']);
     service.close();
   });
@@ -318,4 +323,69 @@ describe('Electron session index', () => {
     expect(rebuilt.snapshot().directories).toEqual([]);
     rebuilt.close();
   });
+
+  it('exposes time.pinned in snapshots and clears it on unpin', () => {
+    const runtimeRef = { value: 'http://runtime-a.test' };
+    const service = createService(runtimeRef);
+    service.replaceDirectory({ directory: '/repo', sessions: [session('ses_a', 10)], cursor: null, hasMore: false });
+
+    expect(service.setPinned('ses_a', 55)).toBe(true);
+    expect(service.snapshot().directories[0].sessions[0].time).toMatchObject({
+      created: 9,
+      updated: 10,
+      pinned: 55,
+    });
+
+    expect(service.clearPinned('ses_a')).toBe(true);
+    expect(service.snapshot().directories[0].sessions[0].time).toEqual({
+      created: 9,
+      updated: 10,
+    });
+    service.close();
+  });
+
+  it('rescues pinned_at across replaceDirectory rebuilds', () => {
+    const runtimeRef = { value: 'http://runtime-a.test' };
+    const service = createService(runtimeRef);
+    service.replaceDirectory({ directory: '/repo', sessions: [session('ses_a', 10)], cursor: null, hasMore: false });
+    expect(service.setPinned('ses_a', 77)).toBe(true);
+
+    service.replaceDirectory({
+      directory: '/repo',
+      sessions: [session('ses_a', 20)],
+      cursor: null,
+      hasMore: false,
+      now: 2000,
+    });
+
+    expect(service.snapshot().directories[0].sessions[0].time).toMatchObject({
+      updated: 20,
+      pinned: 77,
+    });
+    service.close();
+  });
+
+  it('does not let live upsert overwrite pinned_at', () => {
+    const runtimeRef = { value: 'http://runtime-a.test' };
+    const service = createService(runtimeRef);
+    service.replaceDirectory({ directory: '/repo', sessions: [session('ses_a', 10)], cursor: null, hasMore: false });
+    expect(service.setPinned('ses_a', 88)).toBe(true);
+
+    service.upsert(session('ses_a', 30));
+
+    expect(service.snapshot().directories[0].sessions[0].time.pinned).toBe(88);
+    service.close();
+  });
+
+  it('removes pinned rows when an archived upsert deletes the session', () => {
+    const runtimeRef = { value: 'http://runtime-a.test' };
+    const service = createService(runtimeRef);
+    service.replaceDirectory({ directory: '/repo', sessions: [session('ses_a', 10)], cursor: null, hasMore: false });
+    expect(service.setPinned('ses_a', 99)).toBe(true);
+
+    expect(service.upsert({ ...session('ses_a', 11), time: { created: 9, updated: 11, archived: 12 } })).toBe(true);
+    expect(service.snapshot().directories[0].sessions).toEqual([]);
+    expect(service.clearPinned('ses_a')).toBe(false);
+    service.close();
+  });
 });

package/server/lib/session-title/DOCUMENTATION.md

@@ -5,10 +5,11 @@ conversation's **main subject** (overall feature / goal) with the small model
 (`lib/small-model`), then PATCHes `title` plus `metadata.openchamber.titleRefresh`.
 
 OpenCode only auto-titles once from the first user message
-(`SessionPrompt.ensureTitle`). Long sessions often need a refresh; this module
-keeps the sidebar title aligned with the durable work being done — not the last
-wrap-up utterance like "commit and push" — throttled to at most once per 5
-minutes per session.
+(`SessionPrompt.ensureTitle`). This module auto-refreshes sparsely (first idle
+of a new session, first newly-sent reply on a fork) and on explicit smart-title
+requests, naming the durable work being done — not the last wrap-up utterance
+like "commit and push". Background auto refreshes still respect a 5-minute
+throttle (`TITLE_THROTTLE_MS`) when a refresh is armed.
 
 ## Flow
 
@@ -16,19 +17,23 @@ minutes per session.
    fan-out (`index.js` → `globalMessageStreamHub.subscribeEvent`), same
    pattern as session-assist. Purely event-driven — dormant sessions never
    generate anything.
-2. A newly observed root `session.created` generates its first title immediately
-   on the first `session.status: idle`. A fork title (`(fork #n)`) waits for its
-   first newly-created user message; the matching assistant completion triggers
-   an immediate title refresh that bypasses inherited title metadata and throttle.
-   Later idle transitions arm a 15-second quiet timer; any `busy`/`retry` status
-   or a fresh user `message.updated` clears it.
-   A sidebar smart-title request sets `titleRefresh.requestedAt`; its
-   `session.updated` event arms the same flow immediately.
+  2. Auto title refresh is intentionally sparse (title stability first). A newly
+    observed root `session.created` generates its first title immediately on the
+    first `session.status: idle`. A fork title (`(fork #n)`) waits for its first
+    newly-created user message; the matching assistant completion triggers an
+    immediate title refresh that bypasses inherited title metadata and throttle.
+    Ordinary later idle transitions do **not** arm another refresh. Any
+    `busy`/`retry` status or a fresh user `message.updated` still clears an
+    already-armed timer (so initial/fork timers cancel if the user keeps going).
+    A sidebar smart-title request sets `titleRefresh.requestedAt`; its
+    `session.updated` event arms the same flow immediately (forced / manual
+    refresh is unaffected by the background gate).
   3. On fire:
     - Skip when Settings → Chat → session title refresh is off.
     - Skip system-owned sessions whose metadata carries a non-empty
-      `openchamber.assistant.assistantID` or `openchamber.scheduledTask.taskID`
-      (fixed Assistant / scheduled titles must not be rewritten). Early
+      `openchamber.assistant.assistantID`, `openchamber.scheduledTask.taskID`, or
+      `openchamber.smallModel.purpose`
+      (fixed Assistant / scheduled / small-model titles must not be rewritten). Early
       `session.created` and smart-title request extraction skip the same
       metadata when present so timers are not armed.
     - Skip sub-agent sessions (`parentID`), multi-run/fusion structural titles,