@openchambery/web 2.0.0-beta.26 → 2.0.0-beta.29

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

@@ -4,8 +4,8 @@ Server-side watcher that regenerates a session's sidebar title from the
 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`). This module auto-refreshes sparsely (first user
+OpenCode starts its own initial title through `SessionTitle.generate`.
+This module auto-refreshes sparsely (first user
 admission 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
@@ -127,6 +127,8 @@ and other session updates keep the existing ordering timestamp unchanged.
 `sessionTitleRefreshEnabled` in OpenChamber settings (Settings → Chat,
 default on) controls background title refreshes. Explicit smart-title actions
 still run when background refresh is disabled.
+The gate controls model generation, not synchronization of an already committed
+title authority; reconciliation continues without additional model calls.
 
 Settings → Summary AI controls the title model and the optional
 `summarySessionTitlePrompt` override. The configured custom API receives the
@@ -134,10 +136,36 @@ title transcript only after the user explicitly selects that source.
 
 ## Manual rename contract
 
-After this module writes a title, further auto-refreshes only proceed while
-`session.title === titleRefresh.lastAutoTitle` (or the title is still the
-OpenCode default). Renaming in the sidebar breaks that equality and stops
-auto updates for that session.
+OpenChamber owns the title once it generates one or the user renames it here.
+`metadata.openchamber.titleAuthority` stores `{ sessionID, title, revision,
+source }` on the OpenCode session via the metadata store. `sessionID` prevents
+forks inheriting a parent's title lock. Existing `lastAutoTitle` records are not
+promoted: they cannot distinguish an external manual rename from native generation.
+
+`session-access.js` commits the authority before writing the official
+`session.update({ sessionID, title })`. A conditional metadata mutation checks
+the revision captured before model generation, so a late model result cannot
+undo a newer manual rename. Even output equal to the current title claims
+ownership. Sidebar rename commits a new manual authority before its official
+title update. Smart-title requests explicitly allow a new summary generation.
+Ordinary follow-up messages still do not regenerate titles.
+
+Native `session.renamed`, full session updates and Host metadata writes trigger
+coalesced per-session reconciliation. It reads current authority and upstream
+title, writes only on drift, then verifies again. Duplicate/out-of-order events
+are hints, never authority. Retries use exponential backoff capped at 60 seconds;
+404 and shutdown stop pending work. Connection/startup recovery checks persisted
+owned sessions serially, without model calls. Failed upstream writes retain the
+durable intent and report failure rather than claiming successful synchronization.
+
+List/detail and live/replayed rename projections retain the owned title while
+repair runs; the real OpenCode `session.title` is repaired as well. The upstream
+API has no atomic title lock, so other OpenCode clients can briefly observe a
+conflicting write until repair completes. A running, connected Host is required
+for repair; restart/reconnect recovers missed writes. Direct OpenCode renames
+(manual or generated) cannot replace an owned title: rename in OpenChamber to
+change it. Extension-only VS Code receives shared metadata/projection behavior,
+but repair requires a connected OpenChamber Host.
 
 ## Limitations
 
@@ -154,5 +182,5 @@ same file descriptors. This does not perform image recognition or file parsing.
 - Lives in the web server, so VS Code (extension-only) does not generate
   refreshes; it still receives `session.updated` title changes produced by a
   web/desktop instance of the same OpenCode server.
-- First OpenCode-generated title (no `titleRefresh` metadata yet) may be
-  replaced once the conversation has 2+ real user turns — that is intentional.
+- First OpenCode-generated titles may be replaced by OpenChamber's initial title,
+  regardless of which model completes first.

package/server/lib/session-title/native-runtime.test.js

@@ -55,6 +55,29 @@ it.each([false, true])('runs a Host smart-title request and clears loading (mode
   }
 });
 
+it('does not start a pending initial title over a manual authority committed before generation', async () => {
+  vi.useFakeTimers();
+  const generate = vi.fn();
+  const session = { id: 'ses_manual', title: 'Manual', metadata: { openchamber: {
+    titleAuthority: { sessionID: 'ses_manual', title: 'Manual', revision: 'manual', source: 'manual' },
+  } } };
+  const runtime = createSessionTitleRuntime({
+    sessionAccess: {
+      get: async () => session,
+      messages: async () => [{ info: { id: 'u1', role: 'user' }, parts: [{ type: 'text', text: 'Initial work' }] }],
+      update: async () => {},
+    },
+    getSmallModelService: async () => ({ generateSmallModelText: generate }),
+    isTitleRefreshEnabled: () => true,
+  });
+  try {
+    runtime.processPayload({ type: 'session.created', data: { sessionID: session.id } });
+    runtime.processPayload({ type: 'session.execution.succeeded', data: { sessionID: session.id } });
+    await vi.runAllTimersAsync();
+    expect(generate).not.toHaveBeenCalled();
+  } finally { runtime.stop(); }
+});
+
 it('uses the real v2 client and publishes the generated title without another session click', async () => {
   vi.useFakeTimers();
   configureServerOpenCodeFetchGate(null, { allowMissingContract: true });
@@ -85,6 +108,12 @@ it('uses the real v2 client and publishes the generated title without another se
     buildOpenCodeUrl: (path) => `http://opencode${path}`,
     getOpenCodeAuthHeaders: () => ({}),
     readSessionMetadata: async () => metadata,
+    mutateSessionMetadata: async (_id, decide) => {
+      const decision = decide(metadata);
+      if (!decision.ok) return { committed: false };
+      metadata = mergeMetadataPatch(metadata, decision.patch);
+      return { committed: true, metadata };
+    },
     persistSessionMetadata: async (_id, patch) => {
       metadata = mergeMetadataPatch(metadata, patch);
       events.push({ type: 'metadata', metadata: structuredClone(metadata) });
@@ -105,6 +134,19 @@ it('uses the real v2 client and publishes the generated title without another se
     expect(events.at(-1)).toMatchObject({ type: 'session', row: { title: 'Title refresh', directory: '/repo' } });
     expect(metadata.openchamber.titleRefresh.isGenerating).toBeUndefined();
     expect(requests).toContain('PATCH /api/session/ses_title');
+    session.title = 'Late native title';
+    runtime.processPayload({ type: 'session.renamed', created: 2000, data: {
+      sessionID: session.id, title: session.title,
+    } });
+    await vi.runAllTimersAsync();
+    expect(session.title).toBe('Title refresh');
+    expect(events.at(-1)).toMatchObject({ type: 'session', row: { title: 'Title refresh' } });
+    const writes = requests.filter((request) => request.startsWith('PATCH')).length;
+    runtime.processPayload({ type: 'session.renamed', created: 500, data: {
+      sessionID: session.id, title: 'Replayed stale title',
+    } });
+    await vi.runAllTimersAsync();
+    expect(requests.filter((request) => request.startsWith('PATCH'))).toHaveLength(writes);
   } finally {
     runtime.stop();
   }

package/server/lib/session-title/runtime.js

@@ -46,8 +46,8 @@ const FORK_TITLE_RE = / \(fork #\d+\)$/;
 const MULTI_RUN_GROUP_SLUG = /^[a-z0-9](?:[a-z0-9-]{0,48}[a-z0-9])?$/;
 const MULTI_RUN_GROUP = /^g[1-9]\d*$/;
 
-// Hard generation switch (default on). When off, no small-model calls and no
-// title writes happen. Existing titles stay untouched.
+// Generation switch (default on). Existing owned titles still reconcile when
+// generation is off; explicit smart-title requests also remain available.
 const isSessionTitleRefreshEnabled = () => {
   try {
     const raw = fs.readFileSync(OPENCHAMBER_SETTINGS_FILE, 'utf8');
@@ -603,6 +603,8 @@ export const createSessionTitleRuntime = ({
 
     const currentTitle = typeof session.title === 'string' ? session.title : '';
     if (looksLikeMultiRunSessionTitle(currentTitle)) return;
+    const authority = session.metadata?.openchamber?.titleAuthority;
+    if (!forceRefresh && authority?.sessionID === sessionId && authority.source === 'manual') return;
 
     const meta = readTitleRefreshMeta(session);
     const canRefreshForkTitle = forkFirstRefresh && isForkedSessionTitle(currentTitle);
@@ -700,12 +702,7 @@ export const createSessionTitleRuntime = ({
     }
 
     const nextTitle = cleanGeneratedTitle(generated?.text);
-    if (!nextTitle) return;
-    if (nextTitle === currentTitle) {
-      // Still stamp metadata so we do not keep re-calling for the same tail.
-      lastGeneratedAtBySession.set(sessionId, now());
-      return;
-    }
+    if (!nextTitle || stopped) return;
 
     // Re-check before write: user may have renamed, or a new message arrived.
     const freshSession = await openCodeFetch(`/session/${encodeURIComponent(sessionId)}`, { directory })
@@ -742,6 +739,8 @@ export const createSessionTitleRuntime = ({
       method: 'PATCH',
       body: {
         title: nextTitle,
+        expectedTitleRevision: session.metadata?.openchamber?.titleAuthority?.sessionID === sessionId
+          ? session.metadata.openchamber.titleAuthority.revision : null,
         metadata: {
           openchamber: {
             titleRefresh: {
@@ -777,6 +776,16 @@ export const createSessionTitleRuntime = ({
   const processPayload = (payload, directoryHint = '') => {
     if (stopped) return;
     directoryHint = directoryHint || payload?.location?.directory || '';
+    if (payload?.type === 'server.connected') {
+      void sessionAccess?.reconcileAll?.().catch((error) => {
+        console.warn('[session-title] recovery failed:', error?.message || error);
+      });
+    }
+    if (payload?.type === 'session.renamed' || payload?.type === 'session.updated'
+      || payload?.type === 'openchamber:session-metadata') {
+      const data = payload.data ?? payload.properties ?? {};
+      sessionAccess?.reconcile?.(data.sessionID ?? data.info?.id ?? data.id, directoryHint);
+    }
     const createdSession = extractCreatedSession(payload);
     if (createdSession) {
       if (isForkedSessionTitle(createdSession.title)) {
@@ -848,6 +857,7 @@ export const createSessionTitleRuntime = ({
 
   const stop = () => {
     stopped = true;
+    sessionAccess?.stop?.();
     for (const { timer } of timers.values()) {
       clearTimeout(timer);
     }

package/server/lib/session-title/session-access.js

@@ -1,5 +1,6 @@
 import { makeOpenCodeV2Client } from '../opencode/v2-client.js';
-import { projectSessionWithHostMetadata } from '../session-metadata/session-projection.js';
+import { projectSessionWithHostMetadata, readSessionTitleAuthority } from '../session-metadata/session-projection.js';
+import { randomUUID } from 'node:crypto';
 import { projectSessionMessageRecords } from '../session-turn-pages/session-message-projection.js';
 
 /** Title reads use OpenCode; title-refresh metadata and its notifications belong to the Host. */
@@ -8,8 +9,15 @@ export function createTitleSessionAccess({
   getOpenCodeAuthHeaders,
   readSessionMetadata,
   persistSessionMetadata,
+  mutateSessionMetadata,
+  listSessionMetadata = async () => ({}),
   publishSession,
 }) {
+  const pending = new Map();
+  let stopped = false;
+  let recovery = null;
+  let recoveryTimer = null;
+  let recoveryFailures = 0;
   const client = () => makeOpenCodeV2Client({
     baseUrl: buildOpenCodeUrl('/', '').replace(/\/$/, ''),
     authHeaders: getOpenCodeAuthHeaders(),
@@ -17,23 +25,120 @@ export function createTitleSessionAccess({
   const options = () => ({ signal: AbortSignal.timeout(30_000) });
   const get = async (sessionID) => {
     const session = await client().session.get({ sessionID }, options());
-    return projectSessionWithHostMetadata(session, await readSessionMetadata(sessionID));
+    const metadata = await readSessionMetadata(sessionID);
+    const authority = readSessionTitleAuthority(sessionID, metadata);
+    if (authority && authority.title !== session.title) reconcile(sessionID);
+    return projectSessionWithHostMetadata(session, metadata);
+  };
+
+  // Coalesce only pending work; settled sessions retain no in-memory entry.
+  const reconcile = (sessionID, directory = '') => {
+    if (stopped || !sessionID) return;
+    const existing = pending.get(sessionID);
+    if (existing) { existing.dirty = true; return; }
+    const state = { dirty: false, timer: null, failures: 0, repaired: false };
+    pending.set(sessionID, state);
+    const run = async () => {
+      state.dirty = false;
+      try {
+        const metadata = await readSessionMetadata(sessionID);
+        const authority = readSessionTitleAuthority(sessionID, metadata);
+        if (!authority || stopped) { pending.delete(sessionID); return; }
+        const session = await client().session.get({ sessionID }, options());
+        if (stopped) return;
+        if (session.title !== authority.title) {
+          await client().session.update({ sessionID, title: authority.title }, options());
+          state.repaired = true;
+          // Always verify after a write, even if its echo was lost or reordered.
+          state.dirty = true;
+        } else {
+          const latest = await readSessionMetadata(sessionID);
+          if (readSessionTitleAuthority(sessionID, latest)?.revision !== authority.revision) {
+            state.dirty = true;
+          } else if (state.repaired && !stopped) {
+            state.repaired = false;
+            await publishSession(projectSessionWithHostMetadata(session, latest), directory);
+          }
+        }
+        state.failures = 0;
+      } catch (error) {
+        if (Number(error?.status ?? error?.statusCode) === 404 || error?._tag === 'SessionNotFoundError') {
+          pending.delete(sessionID);
+          return;
+        }
+        state.failures += 1;
+        state.dirty = true;
+        if (state.failures === 1) console.warn('[session-title] reconciliation failed:', error?.message || error);
+      } finally {
+        if (stopped) { pending.delete(sessionID); return; }
+        if (pending.get(sessionID) !== state) return;
+        if (state.dirty) {
+          state.timer = setTimeout(run, state.failures ? Math.min(60_000, 1000 * 2 ** Math.min(state.failures - 1, 6)) : 0);
+          state.timer.unref?.();
+        } else pending.delete(sessionID);
+      }
+    };
+    state.timer = setTimeout(run, 0);
+    state.timer.unref?.();
+  };
+  const reconcileAll = () => {
+    if (stopped) return Promise.resolve();
+    if (recovery) return recovery;
+    clearTimeout(recoveryTimer);
+    recovery = (async () => {
+      const entries = await listSessionMetadata();
+      recoveryFailures = 0;
+      for (const [id, metadata] of Object.entries(entries)) {
+        if (stopped) return;
+        if (!readSessionTitleAuthority(id, metadata)) continue;
+        // Serial discovery bounds reconnect reads; only drift queues repair.
+        try { await get(id); } catch { reconcile(id); }
+      }
+    })().catch((error) => {
+      recoveryFailures += 1;
+      if (!stopped) {
+        recoveryTimer = setTimeout(() => { void reconcileAll(); }, Math.min(60_000, 1000 * 2 ** Math.min(recoveryFailures - 1, 6)));
+        recoveryTimer.unref?.();
+      }
+      if (recoveryFailures === 1) console.warn('[session-title] recovery failed:', error?.message || error);
+    }).finally(() => { recovery = null; });
+    return recovery;
   };
   return {
     get,
+    reconcile,
+    reconcileAll,
+    stop() {
+      stopped = true;
+      clearTimeout(recoveryTimer);
+      for (const state of pending.values()) clearTimeout(state.timer);
+      pending.clear();
+    },
     async messages(sessionID, _directory, limit) {
       const page = await client().message.list({ sessionID, limit, order: 'desc' }, options());
       if (!Array.isArray(page?.data)) throw new Error('Session title: invalid message page');
       return projectSessionMessageRecords([...page.data].reverse());
     },
     async update(sessionID, directory, patch) {
+      if (stopped) return;
       if (typeof patch.title === 'string') {
+        const result = await mutateSessionMetadata(sessionID, (metadata) => {
+          const current = readSessionTitleAuthority(sessionID, metadata);
+          if ((current?.revision ?? null) !== (patch.expectedTitleRevision ?? null)) return { ok: false };
+          return { ok: true, patch: { openchamber: {
+            titleAuthority: { sessionID, title: patch.title, revision: randomUUID(), source: 'summary' },
+            titleRefresh: patch.metadata?.openchamber?.titleRefresh ?? {},
+          } } };
+        });
+        if (!result.committed || stopped) return;
+        // Durable intent survives failed writes and process restarts.
+        reconcile(sessionID, directory);
         await client().session.update({ sessionID, title: patch.title }, options());
       }
       // Never write the complete metadata snapshot back: goal/archive/ownership
       // may have changed while the title model was running.
       const refresh = patch.metadata?.openchamber?.titleRefresh;
-      if (refresh) {
+      if (refresh && typeof patch.title !== 'string') {
         await persistSessionMetadata(sessionID, { openchamber: { titleRefresh: refresh } });
       }
       if (typeof patch.title === 'string' || (refresh && Object.hasOwn(refresh, 'isGenerating'))) {

package/server/lib/session-title/session-access.test.js

@@ -1,4 +1,4 @@
-import { beforeEach, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
 import { mergeMetadataPatch } from '../session-metadata/session-metadata-store.js';
 
 const { api } = vi.hoisted(() => ({ api: {
@@ -8,17 +8,21 @@ const { api } = vi.hoisted(() => ({ api: {
 vi.mock('../opencode/v2-client.js', () => ({ makeOpenCodeV2Client: () => api }));
 import { createTitleSessionAccess } from './session-access.js';
 
-beforeEach(() => vi.resetAllMocks());
+const accesses = [];
+beforeEach(() => { vi.resetAllMocks(); vi.useFakeTimers(); });
+afterEach(() => { for (const access of accesses.splice(0)) access.stop(); vi.useRealTimers(); });
 
 function fixture() {
   let metadata = { openchamber: {
     goal: { status: 'active' },
     titleRefresh: { isGenerating: true, requestedAt: 1000, lastError: 'old failure', failedAt: 1 },
   } };
-  api.session.get.mockResolvedValue({
+  const session = {
     id: 'ses_title', title: 'Updated title', location: { directory: '/repo' },
     time: { created: 10, updated: 20 },
-  });
+  };
+  api.session.get.mockImplementation(async () => structuredClone(session));
+  api.session.update.mockImplementation(async ({ title }) => { session.title = title; });
   const persist = vi.fn(async (_id, patch) => { metadata = mergeMetadataPatch(metadata, patch); });
   const publish = vi.fn();
   const access = createTitleSessionAccess({
@@ -26,9 +30,17 @@ function fixture() {
     getOpenCodeAuthHeaders: () => ({}),
     readSessionMetadata: async () => metadata,
     persistSessionMetadata: persist,
+    mutateSessionMetadata: async (id, decide) => {
+      const decision = decide(metadata);
+      if (!decision.ok) return { committed: false, metadata };
+      await persist(id, decision.patch);
+      return { committed: true, metadata };
+    },
+    listSessionMetadata: async () => ({ ses_title: metadata }),
     publishSession: publish,
   });
-  return { access, persist, publish, metadata: () => metadata };
+  accesses.push(access);
+  return { access, persist, publish, session, metadata: () => metadata };
 }
 
 it('publishes the full authoritative title row and clears Host loading without overwriting unrelated state', async () => {
@@ -42,6 +54,7 @@ it('publishes the full authoritative title row and clears Host loading without o
   expect(api.session.update.mock.calls[0][0]).toEqual({ sessionID: 'ses_title', title: 'Updated title' });
   expect(f.metadata()).toEqual({ openchamber: {
     goal: { status: 'active' }, titleRefresh: { lastAutoTitle: 'Updated title' },
+    titleAuthority: { sessionID: 'ses_title', title: 'Updated title', revision: expect.any(String), source: 'summary' },
   } });
   expect(f.publish).toHaveBeenCalledWith(expect.objectContaining({
     id: 'ses_title', title: 'Updated title', directory: '/repo', metadata: f.metadata(),
@@ -72,14 +85,119 @@ it('publishes a full loading row before the new session exists in client catalog
   expect(api.session.update).not.toHaveBeenCalled();
 });
 
-it('does not publish success on a failed title write', async () => {
+it('retains durable intent and retries a failed upstream title write without publishing success', async () => {
   const f = fixture();
   api.session.update.mockRejectedValue(new Error('offline'));
   await expect(f.access.update('ses_title', '/repo', {
     title: 'Failed', metadata: { openchamber: { titleRefresh: { lastAutoTitle: 'Failed' } } },
   })).rejects.toThrow('offline');
-  expect(f.persist).not.toHaveBeenCalled();
+  expect(f.metadata().openchamber.titleAuthority.title).toBe('Failed');
   expect(f.publish).not.toHaveBeenCalled();
+  api.session.update.mockImplementation(async ({ title }) => { f.session.title = title; });
+  await vi.runAllTimersAsync();
+  expect(f.session.title).toBe('Failed');
+});
+
+it.each(['before', 'after', 'during'])('rectifies upstream title writes %s our write', async (timing) => {
+  const f = fixture();
+  if (timing === 'before') f.session.title = 'Native';
+  await f.access.update('ses_title', '/repo', { title: 'Ours' });
+  if (timing !== 'before') f.session.title = 'Native';
+  if (timing === 'during') {
+    api.session.update.mockImplementationOnce(async () => { f.session.title = 'Native again'; });
+  }
+  for (let i = 0; i < 100; i++) f.access.reconcile('ses_title');
+  await vi.runAllTimersAsync();
+  expect(f.session.title).toBe('Ours');
+  expect(api.session.update.mock.calls.length).toBeLessThanOrEqual(3);
+  const writes = api.session.update.mock.calls.length;
+  f.access.reconcile('ses_title');
+  await vi.runAllTimersAsync();
+  expect(api.session.update).toHaveBeenCalledTimes(writes);
+});
+
+it('rejects stale generation after a manual rename and repairs from the newest authority', async () => {
+  const f = fixture();
+  await f.access.update('ses_title', '/repo', { title: 'Summary' });
+  const previous = f.metadata().openchamber.titleAuthority.revision;
+  await f.persist('ses_title', { openchamber: { titleAuthority: {
+    sessionID: 'ses_title', title: 'Manual', revision: 'manual-1', source: 'manual',
+  } } });
+  await f.access.update('ses_title', '/repo', { title: 'Late summary', expectedTitleRevision: previous });
+  await vi.runAllTimersAsync();
+  expect(f.session.title).toBe('Manual');
+  expect(f.metadata().openchamber.titleAuthority.source).toBe('manual');
+});
+
+it('re-reads authority when manual rename lands during an upstream repair', async () => {
+  const f = fixture();
+  await f.access.update('ses_title', '/repo', { title: 'Summary' });
+  f.session.title = 'Native';
+  api.session.get.mockImplementationOnce(async () => {
+    await f.persist('ses_title', { openchamber: { titleAuthority: {
+      sessionID: 'ses_title', title: 'Manual', revision: 'manual-2', source: 'manual',
+    } } });
+    return structuredClone(f.session);
+  });
+  await vi.runAllTimersAsync();
+  expect(f.session.title).toBe('Manual');
+  expect(f.publish.mock.calls.at(-1)[0].title).toBe('Manual');
+});
+
+it('recovers missed rename events after reconnect without regenerating a title', async () => {
+  const f = fixture();
+  await f.persist('ses_title', { openchamber: { titleAuthority: {
+    sessionID: 'ses_title', title: 'Durable', revision: 'saved', source: 'summary',
+  } } });
+  await f.access.reconcileAll();
+  await vi.runAllTimersAsync();
+  expect(f.session.title).toBe('Durable');
+});
+
+it('does not adopt inherited fork authority or legacy lastAutoTitle as a lock', async () => {
+  const f = fixture();
+  await f.persist('ses_title', { openchamber: {
+    titleRefresh: { lastAutoTitle: 'Old summary' },
+    titleAuthority: { sessionID: 'ses_parent', title: 'Parent', revision: 'parent' },
+  } });
+  f.access.reconcile('ses_title');
+  await vi.runAllTimersAsync();
+  expect(api.session.update).not.toHaveBeenCalled();
+});
+
+it('does not write a title if durable authority persistence fails', async () => {
+  const f = fixture();
+  f.persist.mockRejectedValue(new Error('disk unavailable'));
+  await expect(f.access.update('ses_title', '/repo', { title: 'Unsaved' })).rejects.toThrow('disk unavailable');
+  await vi.runAllTimersAsync();
+  expect(api.session.update).not.toHaveBeenCalled();
+  expect(f.publish).not.toHaveBeenCalled();
+});
+
+it('stops repair after authoritative deletion', async () => {
+  const f = fixture();
+  await f.persist('ses_title', { openchamber: { titleAuthority: {
+    sessionID: 'ses_title', title: 'Durable', revision: 'saved',
+  } } });
+  api.session.get.mockRejectedValue(Object.assign(new Error('deleted'), { status: 404 }));
+  f.access.reconcile('ses_title');
+  await vi.runAllTimersAsync();
+  expect(api.session.get).toHaveBeenCalledTimes(1);
+  expect(api.session.update).not.toHaveBeenCalled();
+});
+
+it('backs off transient failures and cancels retry on stop', async () => {
+  const f = fixture();
+  await f.persist('ses_title', { openchamber: { titleAuthority: {
+    sessionID: 'ses_title', title: 'Durable', revision: 'saved',
+  } } });
+  api.session.get.mockRejectedValue(new Error('offline'));
+  f.access.reconcile('ses_title');
+  await vi.advanceTimersByTimeAsync(3000);
+  expect(api.session.get).toHaveBeenCalledTimes(3);
+  f.access.stop();
+  await vi.advanceTimersByTimeAsync(60_000);
+  expect(api.session.get).toHaveBeenCalledTimes(3);
 });
 
 it('does not turn a failed or malformed message read into empty success', async () => {

package/server/lib/tts/DOCUMENTATION.md

@@ -43,7 +43,8 @@ This module provides server-side Text-to-Speech services using OpenAI's TTS API.
 ## TTSService methods
 
 ### `isAvailable()`
-Returns boolean indicating whether OpenAI API key is configured (checks environment variable `OPENAI_API_KEY` or OpenCode auth file).
+Returns a Promise of boolean after reading the current OpenCode selected credential.
+Credential-source failure rejects; logout clears the previously constructed client.
 
 ### `generateSpeechStream(options)`
 Generates speech and returns as a web stream for direct streaming to clients.
@@ -81,10 +82,11 @@ Returns object with:
 Returns Buffer containing MP3 audio data.
 
 ## API key resolution
-OpenAI API keys are resolved in order:
-1. Environment variable `OPENAI_API_KEY`.
-2. OpenCode auth file (`auth.openai`, `auth.codex`, or `auth.chatgpt`).
-3. Supports both string format (just token) and object format (with `access` or `token` fields).
+Explicit request API key/custom base URL remains supported. Otherwise the host
+reads the current OpenCode credential API (`openai`, `codex`, `chatgpt` aliases),
+using API `key` or OAuth `access`. There is no host-local environment/file fallback
+that could substitute another account for a remote service. A credential read
+failure propagates; selected-account changes replace the client and logout clears it.
 
 ## Usage in web server
 The TTS module is used by `packages/web/server/index.js` for:

package/server/lib/tts/credential-source.test.js

@@ -0,0 +1,23 @@
+import { afterEach, expect, it } from 'vitest';
+import { configureOpenCodeCredentials } from '../opencode/auth.js';
+import { TTSService } from './service.js';
+
+afterEach(() => configureOpenCodeCredentials(null));
+
+it('TTS clears its old client after logout and obtains a new client after account switching', async () => {
+  let token = 'first';
+  configureOpenCodeCredentials(() => ({ credential: { list: async () => token ? [{ id: 'selected', integrationID: 'openai', active: true, value: { type: 'key', key: token } }] : [] } }));
+  const service = new TTSService();
+  const first = await service._getClient();
+  expect(await service.isAvailable()).toBe(true);
+  token = 'second';
+  expect(await service._getClient()).not.toBe(first);
+  token = '';
+  expect(await service.isAvailable()).toBe(false);
+  expect(await service._getClient()).toBeNull();
+});
+
+it('TTS does not present credential read failure as unavailable success', async () => {
+  configureOpenCodeCredentials(() => ({ credential: { list: async () => { throw new Error('private'); } } }));
+  await expect(new TTSService().isAvailable()).rejects.toThrow(/^Unable to read OpenCode credentials$/);
+});

package/server/lib/tts/routes.js

@@ -62,7 +62,7 @@ export function registerTtsRoutes(app, { sayTTSCapability }) {
       const { ttsService } = await getTtsModule();
 
       // Check availability - server-configured key, client-provided key, or custom server URL
-      const hasServerKey = ttsService.isAvailable();
+      const hasServerKey = await ttsService.isAvailable();
       const hasClientKey = apiKey && typeof apiKey === 'string' && apiKey.trim().length > 0;
       const hasCustomBaseURL = typeof normalizedBaseURL === 'string' && normalizedBaseURL.length > 0;
       
@@ -134,7 +134,7 @@ export function registerTtsRoutes(app, { sayTTSCapability }) {
     try {
       const { ttsService } = await getTtsModule();
       res.json({
-        available: ttsService.isAvailable(),
+        available: await ttsService.isAvailable(),
         voices: [
           'alloy', 'ash', 'ballad', 'coral', 'echo', 'fable',
           'nova', 'onyx', 'sage', 'shimmer', 'verse', 'marin', 'cedar'