@openchambery/web 2.0.0-beta.9 → 2.0.0

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
@@ -50,18 +50,21 @@ extension-only VS Code retains the limitation below.
       assistant reply run concurrently. Generation publishes `isGenerating` via
       the existing Host metadata path, then the final title through `session.updated`.
       Later user admissions/idle events do not regenerate the initial title.
-      The legacy first-idle edge remains a fallback when no admission was observed.
-      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.
+       If `session.created` was missed, the admission's session read recovers
+       an empty/default title with no previous auto-title metadata and starts
+       immediately. The legacy first-idle edge remains a fallback when no
+       admission was observed.
+       A fork title (`(fork #n)`) refreshes on its first newly-admitted user
+       message, bypassing inherited title metadata and throttle without waiting
+       for the assistant. Legacy message-only events retain the idle fallback.
      If the fork's `session.created` was lost (SSE reconnect gap, server or
      OpenCode restart), the first newly-created user message lazily re-registers
      the pending fork from the session read inside `recordUserActivity` (fork
      title + message created after the fork + activity timestamp not yet past
-     the fork time), so the first-reply refresh still fires.
+      the fork time), so the first-send refresh still fires.
      Ordinary later idle transitions do **not** arm another refresh. Any
       `busy`/`retry` status or a fresh user `message.updated` still clears an
-      ordinary already-armed timer; an admitted first-title timer is exempt.
+       ordinary already-armed timer; admitted initial/fork-title timers are exempt.
      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).
@@ -124,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
@@ -131,18 +136,51 @@ 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
 
 Title language follows the user's real message text. Assistant responses, tool
 output, and transcript labels provide context without selecting the title language.
 
+Attachments do not gate title generation. Admission retains user text plus at
+most eight bounded filename/MIME descriptors, never attachment bytes or URLs.
+Attachment-only messages also start generation; the text-only summary model can
+name the attachment subject from those descriptors, but is explicitly told that
+file contents are not included. Transcript-based/manual generation uses the
+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,15 +134,30 @@ 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();
   }
 });
 
-it('starts the first title from admitted user text while the assistant is still running', async () => {
+it.each(['new', 'missed-create', 'fork', 'missed-fork-create'].flatMap((scenario) =>
+  ['text', 'text-and-file', 'file-only'].map((content) => ({ scenario, content })),
+))('starts the first title before assistant completion ($scenario, $content)', async ({ scenario, content }) => {
   vi.useFakeTimers();
   const session = {
-    id: 'ses_first', title: '', time: { created: 1, updated: 1 },
+    id: 'ses_first', title: scenario.includes('fork') ? 'Original (fork #1)' : '', time: { created: 1, updated: 1 },
     metadata: {},
   };
   let finishTitle;
@@ -135,26 +179,36 @@ it('starts the first title from admitted user text while the assistant is still
   });
   const emit = (type, data) => runtime.processPayload({ type, data, created: 1000, location: { directory: '/repo' } });
   try {
-    emit('session.created', { sessionID: session.id, location: { directory: '/repo' } });
+    if (!scenario.startsWith('missed')) {
+      emit('session.created', { sessionID: session.id, title: session.title, time: session.time, location: { directory: '/repo' } });
+    }
     emit('session.inbox.enqueued', { sessionID: session.id, inboxID: 'msg_synthetic', item: {
       type: 'synthetic', delivery: 'steer', payload: { text: 'Internal instructions' },
     } });
     await vi.runAllTimersAsync();
     expect(generate).not.toHaveBeenCalled();
     emit('session.inbox.enqueued', { sessionID: session.id, inboxID: 'msg_first', item: {
-      type: 'user', delivery: 'steer', payload: { text: 'Implement a session title generator' },
+      type: 'user', delivery: 'steer', payload: {
+        text: content === 'file-only' ? '' : 'Implement a session title generator',
+        ...(content !== 'text' ? { files: [{ name: 'title-bug.png', mime: 'image/png', source: { type: 'inline' }, data: 'YQ=='.repeat(100_000) }] } : {}),
+      },
     } });
     emit('session.execution.started', { sessionID: session.id });
     emit('session.status', { sessionID: session.id, status: { type: 'busy' } });
     await vi.runAllTimersAsync();
     expect(generate).toHaveBeenCalledTimes(1);
-    expect(generate.mock.calls[0][0].prompt).toContain('Implement a session title generator');
+    const prompt = generate.mock.calls[0][0].prompt;
+    if (content !== 'file-only') expect(prompt).toContain('Implement a session title generator');
+    if (content !== 'text') expect(prompt).toContain('title-bug.png');
+    expect(prompt).not.toContain('YQ==');
+    expect(prompt.length).toBeLessThan(4000);
     expect(session.metadata.openchamber?.titleRefresh?.isGenerating).toBe(true);
     expect(access.messages).not.toHaveBeenCalled();
     finishTitle({ text: 'Session titles', providerID: 'test', modelID: 'test' });
     await vi.runAllTimersAsync();
     expect(session.title).toBe('Session titles');
     expect(session.metadata.openchamber.titleRefresh.isGenerating).toBeUndefined();
+    expect(access.messages).not.toHaveBeenCalled();
     emit('session.execution.succeeded', { sessionID: session.id });
     emit('session.inbox.enqueued', { sessionID: session.id, inboxID: 'msg_second', item: {
       type: 'user', delivery: 'steer', payload: { text: 'Follow up on the implementation' },

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

@@ -1,7 +1,7 @@
 // Session title refresh: regenerate the sidebar title from the conversation's
 // MAIN SUBJECT (overall feature / goal), not just the last wrap-up utterance.
 // OpenCode only titles once from the first user message. Auto refresh is sparse
-// for title stability: first idle of a new session, first newly-sent reply on a
+// for title stability: first user admission of a new session, first send on a
 // fork, plus explicit smart-title / forced refresh. Continuing the same work
 // should keep naming the thing being done — not "commit and push". This
 // watcher throttles to at most one refresh per session every TITLE_THROTTLE_MS
@@ -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');
@@ -201,13 +201,22 @@ const extractUserMessage = (payload) => {
     const item = properties.item;
     if (typeof properties.sessionID !== 'string' || item?.type !== 'user') return null;
     const text = typeof item.payload?.text === 'string' ? item.payload.text.slice(0, TRANSCRIPT_USER_CHAR_LIMIT) : '';
+    const files = Array.isArray(item.payload?.files) ? item.payload.files.slice(0, 8) : [];
+    const parts = [
+      ...(text.trim() ? [{ type: 'text', text }] : []),
+      ...files.filter((file) => file && typeof file === 'object').map((file) => ({
+        type: 'file',
+        filename: typeof file.name === 'string' ? file.name.slice(0, 200) : '',
+        mime: typeof file.mime === 'string' ? file.mime.slice(0, 100) : '',
+      })),
+    ];
     return {
       sessionId: properties.sessionID,
       createdAt: payload.created ?? 0,
       directory: payload.location?.directory ?? '',
-      initialRecord: text.trim() ? {
+      initialRecord: parts.length ? {
         info: { id: properties.inboxID, role: 'user' },
-        parts: [{ type: 'text', text }],
+        parts,
       } : null,
     };
   }
@@ -230,7 +239,13 @@ const messagePartsToText = (message) => {
     ? TRANSCRIPT_ASSISTANT_CHAR_LIMIT
     : TRANSCRIPT_USER_CHAR_LIMIT;
   return parts
-    .map((part) => (part?.type === 'text' && typeof part.text === 'string' ? part.text : ''))
+    .map((part) => {
+      if (part?.type === 'text' && typeof part.text === 'string') return part.text;
+      if (part?.type !== 'file') return '';
+      const filename = typeof part.filename === 'string' ? part.filename.slice(0, 200) : '';
+      const mime = typeof part.mime === 'string' ? part.mime.slice(0, 100) : '';
+      return `[Attachment: ${filename || mime || 'file'}${filename && mime ? ` (${mime})` : ''}; contents not included]`;
+    })
     .filter(Boolean)
     .join('\n')
     .slice(0, charLimit);
@@ -495,7 +510,7 @@ export const createSessionTitleRuntime = ({
     });
   };
 
-  const recordUserActivity = async (sessionId, directory, createdAt) => {
+  const recordUserActivity = async (sessionId, directory, createdAt, initialRecord) => {
     if (!Number.isFinite(createdAt) || createdAt <= 0) return;
     const session = await openCodeFetch(`/session/${encodeURIComponent(sessionId)}`, { directory })
       .catch(() => null);
@@ -508,7 +523,7 @@ export const createSessionTitleRuntime = ({
     // never learned about the fork. The first newly-created user message on a
     // fork-titled session (message created after the fork, before any activity
     // timestamp advanced past the fork) rebuilds that pending entry so the
-    // matching idle still triggers the first-refresh. Idempotent: the normal
+    // first admission can trigger the refresh. Idempotent: the normal
     // session.created path already holds a pending entry, and once activity
     // advances past the fork time later messages never re-register.
     const forkCreated = Number(session?.time?.created);
@@ -526,6 +541,26 @@ export const createSessionTitleRuntime = ({
       });
     }
 
+    // Recover first-send admission even when session.created was missed.
+    // Use the admitted text: the message projection may not exist yet.
+    if (initialRecord && !stopped && !inflight.has(sessionId) && !initialRefreshes.has(sessionId)
+      && !forkFirstRefreshes.has(sessionId) && !session.parentID && !isSystemOwnedSession(session)) {
+      const pendingFork = forkFirstSendPending.get(sessionId);
+      const firstForkSend = pendingFork && createdAt > pendingFork.createdAt;
+      const untitled = !session.title || isDefaultSessionTitle(session.title);
+      if (firstForkSend || (untitled && !meta.generatedAt && !meta.lastAutoTitle)) {
+        newSessions.delete(sessionId);
+        if (firstForkSend) {
+          forkFirstSendPending.delete(sessionId);
+          forkFirstRefreshes.add(sessionId);
+        } else {
+          initialRefreshes.add(sessionId);
+        }
+        initialUserMessages.set(sessionId, initialRecord);
+        armTimer(sessionId, directory, 0);
+      }
+    }
+
     const previous = Number(meta.titleRefresh.activityUpdatedAt);
     const activityUpdatedAt = Number.isFinite(previous) ? Math.max(previous, createdAt) : createdAt;
     if (activityUpdatedAt === previous) return;
@@ -568,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);
@@ -665,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 })
@@ -683,7 +715,7 @@ export const createSessionTitleRuntime = ({
       return;
     }
 
-    const latestMessages = await fetchRecentMessages(sessionId, directory);
+    const latestMessages = initialUserMessage ? null : await fetchRecentMessages(sessionId, directory);
     const latestAssistantId = (() => {
       if (!latestMessages) return null;
       for (let i = latestMessages.length - 1; i >= 0; i -= 1) {
@@ -707,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: {
@@ -742,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)) {
@@ -777,7 +821,7 @@ export const createSessionTitleRuntime = ({
           initialRefreshes.add(status.sessionId);
           armTimer(status.sessionId, status.directory || directoryHint, 0);
         }
-      } else if (!initialRefreshes.has(status.sessionId)) {
+      } else if (!initialRefreshes.has(status.sessionId) && !forkFirstRefreshes.has(status.sessionId)) {
         clearTimer(status.sessionId);
       }
       return;
@@ -797,6 +841,7 @@ export const createSessionTitleRuntime = ({
         userMessage.sessionId,
         userMessage.directory || directoryHint,
         userMessage.createdAt,
+        userMessage.initialRecord,
       ).catch((error) => {
         console.warn('[session-title] failed to record user activity:', error?.message || error);
       });
@@ -804,7 +849,7 @@ export const createSessionTitleRuntime = ({
       // session settles. Only a message created after the timer was armed
       // means the user actually moved on.
       const armed = timers.get(userMessage.sessionId);
-      if (armed && !initialRefreshes.has(userMessage.sessionId) && userMessage.createdAt >= armed.armedAt) {
+      if (armed && !initialRefreshes.has(userMessage.sessionId) && !forkFirstRefreshes.has(userMessage.sessionId) && userMessage.createdAt >= armed.armedAt) {
         clearTimer(userMessage.sessionId);
       }
     }
@@ -812,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'))) {