@walkhi/code-relax 0.1.0-beta.3 → 0.1.0-beta.30

package/dist/src/shared-app-server.mjs

@@ -2,49 +2,52 @@ import WebSocket from 'ws';
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
 import events from '../shared/app-server-events.cjs';
+import messageDelivery from '../shared/message-delivery.cjs';
 import serverRequests from '../shared/server-requests.cjs';
 
-const syncTokenTtlMs = 30_000;
-const syncBufferMaxBytes = 8 * 1024 * 1024;
-const historyPageMaxTurns = 8;
-const historyPageMaxBytes = 500 * 1024;
-const turnItemPageSize = 50;
-const writerConflictMessages = ['already has an active writer', 'already has a live local writer'];
-
-export class ThreadWriterConflictError extends Error {
-  constructor(threadId, message) {
-    super('该对话正在另一个 Codex 实例中使用。');
-    this.name = 'ThreadWriterConflictError';
-    this.code = 'thread_writer_owned_elsewhere';
-    this.threadId = threadId;
-    this.readOnly = true;
-    this.details = message;
-  }
-}
-
-export function isThreadWriterConflict(error) {
-  const message = String(error?.message || error).toLowerCase();
-  return error instanceof ThreadWriterConflictError || writerConflictMessages.some(text => message.includes(text));
-}
+const syncTokenTtlMs = 30_000;
+const syncBufferMaxBytes = 8 * 1024 * 1024;
+const historyPageMaxTurns = 8;
+const historyPageMaxBytes = 500 * 1024;
+const writerConflictMessages = ['already has an active writer', 'already has a live local writer'];
+
+export class ThreadWriterConflictError extends Error {
+  constructor(threadId, message) {
+    super('该对话正在另一个 Codex 实例中使用。');
+    this.name = 'ThreadWriterConflictError';
+    this.code = 'thread_writer_owned_elsewhere';
+    this.threadId = threadId;
+    this.readOnly = true;
+    this.details = message;
+  }
+}
+
+export function isThreadWriterConflict(error) {
+  const message = String(error?.message || error).toLowerCase();
+  return error instanceof ThreadWriterConflictError || writerConflictMessages.some(text => message.includes(text));
+}
 
 // Connect to the Desktop's existing execution service; never spawn or adopt a task.
 export class SharedAppServer extends EventEmitter {
   constructor(url) {
     super();
     const address = new URL(url);
-    if (address.protocol !== 'ws:' || address.hostname !== '127.0.0.1') throw new Error('完整控制必须使用本机回环 WebSocket。');
+    if (address.protocol !== 'ws:' || address.hostname !== '127.0.0.1') throw new Error('Codex 内核必须使用本机回环 WebSocket。');
     this.url = url;
+    this.serverVersion = '';
     this.epoch = randomUUID();
     this.sequence = 0;
     this.pending = new Map();
-    this.serverRequests = new serverRequests.Store(randomUUID(), id => this.emit('requests-changed', id));
+    this.serverRequests = new serverRequests.Store(randomUUID(), id => {
+      this.emit('requests-changed', id);
+      this.releaseInactiveThread(id);
+    });
     this.threads = new Map();
     this.contexts = new Map();
     this.settingsNotifications = new Map();
-    this.permissionOptions = new events.PermissionOptionsCache();
-    this.subscriptions = new Map();
-    this.operationGroups = new Map();
-    this.usageCache = new events.UsageCache(value => this.emit('usage', value));
+    this.permissionOptions = new events.PermissionOptionsCache();
+    this.subscriptions = new Map();
+    this.usageCache = new events.UsageCache(value => this.emit('usage', value));
   }
 
   async connect() {
@@ -54,10 +57,15 @@ export class SharedAppServer extends EventEmitter {
     return this.connecting;
   }
 
+  openSocket() {
+    return new WebSocket(this.url, { handshakeTimeout: 5000 });
+  }
+
   async open() {
-    const socket = new WebSocket(this.url, { handshakeTimeout: 5000 });
+    const socket = await this.openSocket();
     this.socket = socket;
     this.ready = false;
+    this.serverVersion = '';
     this.serverRequests.reset(randomUUID());
     socket.on('message', bytes => {
       let message;
@@ -68,24 +76,28 @@ export class SharedAppServer extends EventEmitter {
       if (!pending) return;
       this.pending.delete(message.id);
       clearTimeout(pending.timer);
-      if (message.error) {
-        const text = String(message.error.message || 'app-server 请求失败');
-        pending.reject(writerConflictMessages.some(value => text.toLowerCase().includes(value))
-          ? new ThreadWriterConflictError(pending.threadId, text)
-          : Object.assign(new Error(text), { rpcCode: message.error.code, details: message.error.data }));
-      }
-      else pending.resolve(message.result);
+      if (message.error) {
+        const text = String(message.error.message || 'app-server 请求失败');
+        pending.reject(writerConflictMessages.some(value => text.toLowerCase().includes(value))
+          ? new ThreadWriterConflictError(pending.threadId, text)
+          : Object.assign(new Error(text), { rpcCode: message.error.code, details: message.error.data,
+            ...(/^invalid cursor:/i.test(text) ? { code: 'history_cursor_expired' } : {}) }));
+      }
+      else {
+        try { pending.resolve(pending.transform(message.result)); }
+        catch (error) { pending.reject(error); }
+      }
     });
     socket.on('close', () => {
       this.ready = false;
+      this.serverVersion = '';
       for (const pending of this.pending.values()) {
         clearTimeout(pending.timer);
-        pending.reject(new Error('完整控制连接断开；发送结果可能未确认，请检查对话后再操作。'));
+        pending.reject(new Error('Codex 内核连接断开；发送结果可能未确认，请检查对话后再操作。'));
       }
-      this.pending.clear();
-      this.serverRequests.reset(randomUUID());
-      this.threads.clear();
-      this.operationGroups.clear();
+      this.pending.clear();
+      this.serverRequests.reset(randomUUID());
+      this.threads.clear();
       for (const slot of this.subscriptions.values()) clearTimeout(slot.expiry);
       this.subscriptions.clear();
       this.contexts.clear();
@@ -97,24 +109,32 @@ export class SharedAppServer extends EventEmitter {
     socket.on('error', () => {}); // open/request reports the connection error to the caller.
     await new Promise((resolve, reject) => { socket.once('open', resolve); socket.once('error', reject); });
     try {
-      await this.request('initialize', { clientInfo: { name: 'codex_remote_shared', version: '1.0.0' }, capabilities: { experimentalApi: true } });
+      const initialized = await this.request('initialize', { clientInfo: { name: 'codex_remote_shared', version: '1.0.0' }, capabilities: { experimentalApi: true } });
+      // The first user-agent product reports the running server build, not the
+      // selected executable that may only take effect after a future restart.
+      this.serverVersion = String(initialized?.userAgent || '').match(/^[^\s/]+\/([^\s]+)/)?.[1] || '';
       socket.send(JSON.stringify({ method: 'initialized' }));
       this.ready = true;
       this.usageCache.read(() => this.request('account/rateLimits/read')).catch(error => this.emit('usage-error', error));
     } catch (error) { socket.close(); throw error; }
   }
 
-  request(method, params) {
+  request(method, params, transform = value => value) {
     const id = ++this.sequence;
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error(`${method} 超时；不会自动重发，请先检查对话。`));
+        const error = Object.assign(new Error(`${method} 超时；不会自动重发，请先检查对话。`),
+          { code: 'app_server_request_timeout' });
+        if ((method === 'turn/start' || method === 'turn/steer') && this.pending.has(id)) {
+          messageDelivery.retainLateResult(this.pending.get(id), error);
+        } else { this.pending.delete(id); reject(error); }
       }, 30000);
-      this.pending.set(id, { resolve, reject, timer, threadId: params?.threadId });
+      this.pending.set(id, { resolve, reject, timer, transform, threadId: params?.threadId });
       this.socket.send(JSON.stringify({ id, method, params }), error => {
-        if (!error || !this.pending.delete(id)) return;
-        clearTimeout(timer); reject(error);
+        const pending = this.pending.get(id);
+        if (!error || !pending) return;
+        this.pending.delete(id);
+        clearTimeout(timer); pending.reject(error);
       });
     });
   }
@@ -124,24 +144,39 @@ export class SharedAppServer extends EventEmitter {
     return events.readProjects((method, params) => this.request(method, params));
   }
 
-  async send(args) {
-    await this.connect();
-    this.requireWritable(args.threadId);
-    // Reading the live thread checks this service owns it without resume changing settings.
-    const { thread } = await this.request('thread/read', { threadId: args.threadId, includeTurns: false });
-    const status = typeof thread.status === 'string' ? thread.status : thread.status?.type;
-    if (status === 'active') {
-      const live = await this.request('thread/read', { threadId: args.threadId, includeTurns: true });
-      const active = live.thread.turns?.findLast(turn => turn.status === 'inProgress');
-      if (!active) throw new Error('活动轮次已变化，请刷新后再发送。');
-      return this.request('turn/steer', { threadId: args.threadId, expectedTurnId: active.id, input: args.input, ...(args.clientUserMessageId ? { clientUserMessageId: args.clientUserMessageId } : {}) });
+  async send(args, { assertCurrent = () => {} } = {}) {
+    let submitted = false;
+    try {
+      await this.connect();
+      this.requireWritable(args.threadId);
+      // Reading the live thread checks this service owns it without resume changing settings.
+      const { thread } = await this.request('thread/read', { threadId: args.threadId, includeTurns: false });
+      assertCurrent();
+      const status = typeof thread.status === 'string' ? thread.status : thread.status?.type;
+      if (status === 'active') {
+        const page = await this.request('thread/turns/list', {
+          threadId: args.threadId, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded',
+        });
+        const active = page.data?.[0];
+        assertCurrent();
+        if (active?.status !== 'inProgress') throw new Error('活动轮次已变化，请刷新后再发送。');
+        const { turnTrigger, ...source } = events.mobileTurnSource(args.clientUserMessageId, args.responsesapiClientMetadata?.code_relax_input === 'speech_to_text');
+        submitted = true;
+        const result = await this.request('turn/steer', { threadId: args.threadId, expectedTurnId: active.id, input: args.input, ...source, ...(args.clientUserMessageId ? { clientUserMessageId: args.clientUserMessageId } : {}) });
+        return { result, usage: { kind: 'steer', turnId: active.id } };
+      }
+      submitted = true;
+      const result = await this.request('turn/start', args);
+      return { result, usage: { kind: 'start', turnId: result?.turn?.id || null } };
+    } catch (error) {
+      if (!submitted || messageDelivery.rejectedBeforeSubmission(error)) error.deliveryUnknown = false;
+      throw error;
     }
-    return this.request('turn/start', args);
   }
 
-  respondApproval(threadId, body) {
-    if (!this.ready || this.socket?.readyState !== WebSocket.OPEN) throw new Error('完整控制未连接');
-    this.requireWritable(threadId);
+  respondApproval(threadId, body) {
+    if (!this.ready || this.socket?.readyState !== WebSocket.OPEN) throw new Error('Codex 内核未就绪');
+    this.requireWritable(threadId);
     return this.serverRequests.respond(threadId, body, message => new Promise((resolve, reject) => {
       this.socket.send(JSON.stringify(message), error => error ? reject(error) : resolve());
     }));
@@ -164,20 +199,42 @@ export class SharedAppServer extends EventEmitter {
     if (method === 'thread/tokenUsage/updated') {
       this.contexts.set(id, { ...this.contexts.get(id), tokenUsage: params.tokenUsage });
       return;
-    }
-    const record = this.threads.get(id);
-    if (!record) return;
-    const current = params.turn?.id ? record.thread.turns?.find(turn => turn.id === params.turn.id) : null;
-    const groupedHistory = current?.items?.some(item => item?.type === 'lazyOperationGroup');
-    const appliedParams = groupedHistory && method === 'turn/completed' && Array.isArray(params.turn?.items)
-      ? { ...params, turn: { ...params.turn,
-        items: params.turn.items.filter(item => ['userMessage', 'agentMessage'].includes(item?.type)) } }
-      : params;
-    const turn = events.applyNotification(record.thread, method, appliedParams);
+    }
+    const record = this.threads.get(id);
+    if (!record) return;
+    const stub = record.thread.turns?.find(turn => turn.cacheStub && turn.id === (params.turn?.id || params.turnId));
+    if (stub && !['thread/status/changed', 'thread/name/updated'].includes(method)) {
+      record.needsReload = true;
+      this.emit('history-invalidated', id);
+      return;
+    }
+    if (!this.isThreadObserved(id, record)) {
+      // Keep task/approval lifecycle metadata, not an invisible growing transcript.
+      record.needsReload = true;
+      if (params.turn) events.applyNotification(record.thread, method, { ...params, turn: { ...params.turn, items: [] } });
+      else if (method === 'thread/status/changed') record.thread.status = params.status;
+      record.thread.turns = (record.thread.turns || []).slice(-1).map(turn => ({ ...turn, items: [] }));
+      record.changes.clear(); record.changeBytes = 0;
+      if (['turn/completed', 'thread/status/changed'].includes(method)) this.releaseInactiveThread(id);
+      return;
+    }
+    const current = record.thread.turns?.find(turn => turn.id === (params.turn?.id || params.turnId));
+    if (method === 'item/completed' && !record.hydrating && current?.itemPage?.olderCursor && !current.items.some(item => item.id === params.item?.id)) return;
+    // Current app-server completion summaries carry the terminal answer, not
+    // an unrequested history page. Its ID may be new during snapshot handoff.
+    const visibleParams = (record.hydrating || current?.itemPage?.olderCursor) && method === 'turn/completed'
+      && params.turn?.itemsView !== 'summary' && Array.isArray(params.turn?.items)
+      ? { ...params, turn: { ...params.turn,
+        items: params.turn.items.filter(item => current?.items?.some(loaded => loaded.id === item.id)) } }
+      : params;
+    const appliedParams = { ...visibleParams,
+      ...(visibleParams.item ? { item: events.compactItem(visibleParams.item) } : {}),
+      ...(visibleParams.turn ? { turn: events.compactTurn(visibleParams.turn) } : {}) };
+    const turn = events.applyNotification(record.thread, method, appliedParams);
     if (turn) {
       const sequence = ++record.sequence;
       record.changes.set(turn.id, { sequence, turn });
-      record.changeBytes += Buffer.byteLength(JSON.stringify({ method, params: appliedParams }));
+      record.changeBytes += Buffer.byteLength(JSON.stringify({ method, params: appliedParams }));
       if (record.changeBytes > syncBufferMaxBytes) {
         record.recoverAfter = sequence;
         record.changes.clear(); record.changeBytes = 0;
@@ -185,61 +242,111 @@ export class SharedAppServer extends EventEmitter {
       this.emit('turn', { thread: record.thread, turn, sequence,
         immediate: ['turn/completed', 'item/completed'].includes(method) });
     }
-    if (method === 'turn/completed') record.thread.turns = record.thread.turns.slice(-10);
+    if (method === 'turn/completed' && record.thread.turns.length > 10) {
+      record.thread.turns = record.thread.turns.slice(-10);
+      // Native cursors are opaque; obtain a matching boundary before the next snapshot.
+      record.historyTrimmed = true;
+    }
+    if (['turn/completed', 'thread/status/changed'].includes(method)) this.releaseInactiveThread(id);
   }
 
-  async timeline(threadId, pageOptions = {}) {
+  matchesUpdatedAt(thread, updatedAt) {
+    const status = typeof thread.status === 'string' ? thread.status : thread.status?.type;
+    const latest = thread.turns?.at(-1);
+    return Number(updatedAt) > 0 && status !== 'active' && latest?.status !== 'inProgress'
+      && Math.floor(Number(thread.updatedAt)) === Math.floor(Number(updatedAt));
+  }
+
+  resumeTimeline(threadId, apply) {
+    return this.request('thread/resume', { threadId, excludeTurns: true,
+      initialTurnsPage: { limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' } }, value => {
+      if (!Array.isArray(value.initialTurnsPage?.data)) throw new Error('Codex 内核未返回分页历史。');
+      return apply(value);
+    });
+  }
+
+  initialTurnsPage(_threadId, resumed) { return resumed.initialTurnsPage; }
+
+  async timeline(threadId, pageOptions = {}, knownSync) {
     await this.connect();
     const slot = this.slot(threadId);
+    slot.readers++;
     const task = slot.tail.then(async () => {
-      let record = this.threads.get(threadId);
-      if (record?.readOnly) {
-        this.threads.delete(threadId);
-        this.contexts.delete(threadId);
-        record = null;
-      }
-      if (!record) {
-        let result;
-        try {
-          result = await this.request('thread/resume', { threadId, excludeTurns: true,
-            initialTurnsPage: { limit: 1, sortDirection: 'desc', itemsView: 'summary' } });
-        } catch (error) {
-          if (!isThreadWriterConflict(error)) throw error;
-          const [read, page] = await Promise.all([
-            this.request('thread/read', { threadId, includeTurns: false }),
-            this.request('thread/turns/list', {
-              threadId, limit: historyPageMaxTurns, sortDirection: 'desc', itemsView: 'summary',
-            }),
-          ]);
-          const compact = await Promise.all([...(page.data || [])].reverse().map(turn => this.compactTurn(threadId, turn)));
-          const turns = this.fitTurns({ thread: read.thread }, compact, pageOptions);
-          const thread = { ...read.thread, turns, readOnly: true,
-            readOnlyReason: '该对话正在另一个 Codex 实例中使用。' };
-          record = { thread, nextCursor: page.nextCursor ?? null, sequence: 0, recoverAfter: 0,
-            changes: new Map(), changeBytes: 0, tokens: new Map(), readOnly: true };
-          this.threads.set(threadId, record);
-          result = null;
-        }
-        if (result) {
-          if (!Array.isArray(result.initialTurnsPage?.data)) throw new Error('完整控制未返回分页历史。');
-          const compact = await Promise.all([...result.initialTurnsPage.data].reverse().map(turn => this.compactTurn(threadId, turn)));
-          const thread = { ...result.thread, turns: compact };
-          record = { thread, nextCursor: result.initialTurnsPage.nextCursor ?? null, sequence: 0,
-            recoverAfter: 0, changes: new Map(), changeBytes: 0, tokens: new Map() };
-          this.threads.set(threadId, record);
-          this.contexts.set(threadId, { ...this.contexts.get(threadId), model: result.model, thinking: result.reasoningEffort, serviceTier: result.serviceTier ?? null,
-            cwd: result.cwd, ...events.permissionState(result) });
-          await this.extendHistoryRecord(threadId, record, pageOptions);
-        }
+      let record = this.threads.get(threadId), metadataReused = false;
+      // Seconds are the product's cache-update granularity. Active work still
+      // uses the received sequence so an in-progress reply can keep advancing.
+      const knownToken = record?.tokens.get(knownSync?.id);
+      const unchanged = Boolean(!pageOptions.reconcileObserved && record && !record.readOnly && !record.needsReload && !record.hydrating
+        && (this.matchesUpdatedAt(record.thread, knownSync?.updatedAt)
+          || (knownSync?.epoch === this.epoch && Number.isSafeInteger(knownSync.seq)
+            && knownToken && knownToken.expires > Date.now()
+            && knownToken.sequence === knownSync.seq && record.sequence === knownSync.seq)));
+      if (unchanged) {
+        const id = randomUUID();
+        record.tokens.set(id, { sequence: record.sequence, expires: Date.now() + syncTokenTtlMs });
+        this.scheduleCleanup(threadId, slot);
+        return { thread: { ...record.thread, turns: [] }, notModified: true,
+          sync: { id, epoch: this.epoch, seq: record.sequence } };
+      }
+      // Snapshot refreshes must not reset the sequence or tokens of live subscribers.
+      const previous = record?.readOnly ? null : record;
+      if (record?.readOnly || record?.needsReload) this.contexts.delete(threadId);
+      if (pageOptions.reconcileObserved || !record || record.readOnly || record.needsReload || record.historyTrimmed || record.metadataOnly) {
+        let result, snapshot;
+        try {
+          result = await this.resumeTimeline(threadId, value => {
+            const retained = new Map((previous?.thread.turns || []).map(turn => [turn.id, turn]));
+            record = { thread: { ...value.thread, turns: [...value.initialTurnsPage.data].reverse().map(turn => ({
+              ...turn, items: retained.get(turn.id)?.items || [],
+              ...(retained.get(turn.id)?.itemPage ? { itemPage: retained.get(turn.id).itemPage } : {}),
+            })) },
+              nextCursor: value.initialTurnsPage.nextCursor ?? null,
+              sequence: previous?.sequence ?? 0, recoverAfter: previous?.recoverAfter ?? 0,
+              changes: previous?.changes ?? new Map(), changeBytes: previous?.changeBytes ?? 0,
+              tokens: previous?.tokens ?? new Map(), hydrating: true };
+            this.threads.set(threadId, record);
+            snapshot = events.beginSnapshot(record.thread);
+            return value;
+          }, pageOptions);
+        } catch (error) {
+          snapshot?.close();
+          if (!isThreadWriterConflict(error)) throw error;
+          record = await this.readOnlyRecord(threadId, pageOptions, '该对话正在另一个 Codex 实例中使用。');
+          result = null;
+        }
+        if (result) try {
+          const page = await this.initialTurnsPage(threadId, result);
+          if (!Array.isArray(page?.data)) throw new Error('Codex 内核未返回分页历史。');
+          const live = new Map(record.thread.turns.map(turn => [turn.id, turn]));
+          record.thread.turns = [...page.data].reverse().map(turn => {
+            const current = live.get(turn.id);
+            live.delete(turn.id);
+            return current ? Object.assign(current, { ...turn, ...current }) : { ...turn, items: [] };
+          }).concat([...live.values()]);
+          record.nextCursor = page.nextCursor ?? null;
+          metadataReused = Boolean(!pageOptions.reconcileObserved && !snapshot.changed()
+            && this.matchesUpdatedAt(record.thread, knownSync?.updatedAt));
+          if (metadataReused) {
+            record.metadataOnly = true;
+            record.thread.turns = record.thread.turns.map(turn => ({ ...turn, items: [], cacheStub: true }));
+          } else await Promise.all(page.data.map(turn => this.compactTurn(threadId, turn, null, page => snapshot.merge(page), 20)));
+          record.hydrating = false;
+          this.contexts.set(threadId, { ...this.contexts.get(threadId), model: result.model, thinking: result.reasoningEffort, serviceTier: result.serviceTier ?? null,
+            cwd: result.cwd, ...events.permissionState(result) });
+        } finally { snapshot?.close(); }
       }
       const id = randomUUID(), expires = Date.now() + syncTokenTtlMs;
       record.tokens.set(id, { sequence: record.sequence, expires });
       this.scheduleCleanup(threadId, slot);
-      return { thread: record.thread, nextCursor: record.nextCursor,
+      return { thread: metadataReused ? { ...record.thread, turns: [] } : record.thread,
+        ...(metadataReused ? { notModified: true } : {}),
+        nextCursor: this.historyCursor(threadId, record.thread.turns[0], record.nextCursor),
         sync: { id, epoch: this.epoch, seq: record.sequence } };
-    });
+    }).finally(() => { slot.readers--; });
     slot.tail = task.catch(() => {});
     task.catch(() => {
+      const record = this.threads.get(threadId);
+      if (record?.hydrating) { record.needsReload = true; record.hydrating = false; this.scheduleCleanup(threadId, slot); }
       if (!slot.users && !this.threads.has(threadId) && this.subscriptions.get(threadId) === slot) {
         clearTimeout(slot.expiry);
         this.subscriptions.delete(threadId);
@@ -250,10 +357,18 @@ export class SharedAppServer extends EventEmitter {
 
   slot(threadId) {
     let slot = this.subscriptions.get(threadId);
-    if (!slot) { slot = { users: 0, tail: Promise.resolve(), expiry: null }; this.subscriptions.set(threadId, slot); }
+    if (!slot) { slot = { users: 0, readers: 0, tail: Promise.resolve(), expiry: null }; this.subscriptions.set(threadId, slot); }
     return slot;
   }
 
+  keepSnapshotAlive(threadId, sync) {
+    const token = this.threads.get(threadId)?.tokens.get(sync?.id);
+    const slot = this.subscriptions.get(threadId);
+    if (!token || !slot || sync.epoch !== this.epoch) return;
+    token.expires = Date.now() + syncTokenTtlMs;
+    this.scheduleCleanup(threadId, slot);
+  }
+
   scheduleCleanup(threadId, slot) {
     clearTimeout(slot.expiry);
     const record = this.threads.get(threadId);
@@ -265,18 +380,34 @@ export class SharedAppServer extends EventEmitter {
   cleanup(threadId, slot) {
     const record = this.threads.get(threadId), now = Date.now();
     if (record) for (const [id, token] of record.tokens) if (token.expires <= now) record.tokens.delete(id);
-    if (slot.users) { clearTimeout(slot.expiry); slot.expiry = null; return; }
+    if (slot.users || slot.readers) { clearTimeout(slot.expiry); slot.expiry = null; return; }
     if (record?.tokens.size) { this.scheduleCleanup(threadId, slot); return; }
+    if (this.keepThreadLoaded(threadId, record)) { clearTimeout(slot.expiry); slot.expiry = null; return; }
     slot.tail = slot.tail.then(async () => {
-      if (slot.users || this.threads.get(threadId)?.tokens.size) return;
-      this.threads.delete(threadId); this.contexts.delete(threadId); this.permissionOptions.delete(threadId);
-      this.operationGroups.delete(threadId);
+      if (this.subscriptions.get(threadId) !== slot) return;
+      if (slot.users || slot.readers || this.threads.get(threadId)?.tokens.size || this.keepThreadLoaded(threadId, this.threads.get(threadId))) return;
+      this.threads.delete(threadId); this.contexts.delete(threadId); this.permissionOptions.delete(threadId);
       this.subscriptions.delete(threadId); clearTimeout(slot.expiry);
-      if (this.ready && !record?.readOnly) await this.request('thread/unsubscribe', { threadId });
-      this.serverRequests.forget(threadId);
+      if (this.ready && !record?.readOnly) await this.unsubscribeThread(threadId);
+      this.serverRequests.forget(threadId);
     }).catch(error => this.emit('subscription-error', error));
   }
 
+  keepThreadLoaded(threadId, record) {
+    if (!record || record.readOnly) return false;
+    const status = typeof record.thread.status === 'string' ? record.thread.status : record.thread.status?.type;
+    return status === 'active' || record.thread.turns?.some(turn => turn.status === 'inProgress')
+      || this.serverRequests.list(threadId).length > 0;
+  }
+
+  releaseInactiveThread(threadId) {
+    // Run after the current notification has updated both request and turn state.
+    queueMicrotask(() => {
+      const slot = this.subscriptions?.get(threadId);
+      if (slot && !slot.users && this.ready) this.cleanup(threadId, slot);
+    });
+  }
+
   async acquire(threadId, requested) {
     const slot = this.slot(threadId);
     let record = this.threads.get(threadId), token;
@@ -284,18 +415,20 @@ export class SharedAppServer extends EventEmitter {
       token = record.tokens.get(requested.id);
       if (!token || token.expires <= Date.now() || token.sequence !== requested.after) token = undefined;
     }
-    let snapshot = false, catchup;
-    if (!record || !token) {
-      const fresh = await this.timeline(threadId);
+    let snapshot = false, catchup, confirmed = false;
+    if (!record || !token || record.needsReload
+      || ((record.historyTrimmed || record.metadataOnly) && requested.after < record.recoverAfter)) {
+      const fresh = await this.timeline(threadId, {}, { updatedAt: requested?.updatedAt });
       record = this.threads.get(threadId); token = record.tokens.get(fresh.sync.id);
       requested = { id: fresh.sync.id, epoch: fresh.sync.epoch, after: fresh.sync.seq };
-      snapshot = true;
+      snapshot = fresh.notModified !== true;
+      confirmed = !snapshot;
     }
     slot.users++; record.tokens.delete(requested.id); clearTimeout(slot.expiry);
     const current = record.sequence;
     if (!snapshot && requested.after < record.recoverAfter) snapshot = true;
     if (!snapshot && current > requested.after) {
-      const turns = [...record.changes.values()].filter(change => change.sequence > requested.after)
+      const turns = [...record.changes.values()].filter(change => change.sequence > requested.after && !change.turn.cacheStub)
         .sort((left, right) => record.thread.turns.findIndex(turn => turn.id === left.turn.id)
           - record.thread.turns.findIndex(turn => turn.id === right.turn.id)).map(change => change.turn);
       catchup = { thread: { ...record.thread, turns },
@@ -303,148 +436,127 @@ export class SharedAppServer extends EventEmitter {
     }
     const release = () => {
       slot.users--;
+      // Retain the observed snapshot briefly when switching away. A later check
+      // must match the client's consumed sequence, never just this release time.
+      if (this.threads.get(threadId) === record && !record.readOnly) {
+        record.tokens.set(requested.id, { sequence: record.sequence, expires: Date.now() + syncTokenTtlMs });
+      }
       this.cleanup(threadId, slot);
       return slot.tail;
     };
-    return { record: { thread: record.thread, nextCursor: record.nextCursor,
+    return { record: { thread: record.thread, nextCursor: this.historyCursor(threadId, record.thread.turns[0], record.nextCursor),
       sync: { id: requested.id, epoch: this.epoch, seq: current, ...(snapshot ? { reset: true } : {}) } },
-      snapshot, catchup, release };
-  }
-
-  pageSettings(options = {}) {
-    return {
-      maxTurns: Math.max(1, Math.min(historyPageMaxTurns, Number(options.maxTurns) || historyPageMaxTurns)),
-      maxBytes: Math.max(1, Number(options.maxBytes) || historyPageMaxBytes),
-      measure: typeof options.measure === 'function' ? options.measure : value => Buffer.byteLength(JSON.stringify(value)),
-    };
-  }
-
-  async compactTurn(threadId, turn) {
-    const compact = events.compactTurn(turn);
-    if (!turn?.id) return compact;
-    const batches = [];
-    let cursor;
-    do {
-      const page = await this.request('thread/items/list', {
-        threadId, turnId: turn.id, ...(cursor ? { cursor } : {}),
-        limit: 100, sortDirection: 'desc',
-      });
-      if (!Array.isArray(page.data)) throw new Error('完整控制未返回单轮条目索引。');
-      batches.push(page.data.map(entry => events.compactItem(entry.item)));
-      cursor = page.nextCursor ?? null;
-    } while (cursor);
-    const items = batches.reverse().flatMap(batch => batch.reverse());
-    const groups = new Map(), skeleton = [];
-    let operationItems = [];
-    const flushOperations = () => {
-      if (!operationItems.length) return;
-      const visibleItems = operationItems.filter(item => item?.type !== 'reasoning');
-      operationItems = [];
-      if (!visibleItems.length) return;
-      const groupId = `g${groups.size + 1}`;
-      const outline = operationOutline(visibleItems, false);
-      groups.set(groupId, visibleItems);
-      skeleton.push({ type: 'lazyOperationGroup', id: `${turn.id}:${groupId}`,
-        turnId: turn.id, groupId, title: outline.title, count: visibleItems.length });
-    };
-    for (const item of items) {
-      if (['userMessage', 'agentMessage', 'imageGeneration'].includes(item?.type)) {
-        flushOperations();
-        skeleton.push(item);
-      } else operationItems.push(item);
-    }
-    flushOperations();
-    let threadGroups = this.operationGroups.get(threadId);
-    if (!threadGroups) { threadGroups = new Map(); this.operationGroups.set(threadId, threadGroups); }
-    threadGroups.set(turn.id, groups);
-    return { ...compact, items: skeleton };
-  }
-
-  async operationGroupItems(threadId, turnId, groupId, offset) {
-    await this.connect();
-    const items = this.operationGroups.get(threadId)?.get(turnId)?.get(groupId);
-    if (!items) throw new Error('操作组已失效，请重新打开对话。');
-    const start = Math.max(0, Number(offset) || 0);
-    const pageItems = items.slice(start, start + turnItemPageSize);
-    const nextOffset = start + pageItems.length < items.length ? start + pageItems.length : null;
-    return { turnId, groupId, items: pageItems, nextOffset, total: items.length };
-  }
-
-  async turnContext(threadId, turnId) {
-    await this.connect();
-    if (!threadId || !turnId) throw new Error('缺少图片所属的对话或轮次。');
-    return this.compactTurn(threadId, { id: turnId });
-  }
-
-  fitTurns(base, turns, options = {}) {
-    const settings = this.pageSettings(options), accepted = [];
-    let firstOversized = false;
-    for (let index = turns.length - 1; index >= 0 && accepted.length < settings.maxTurns; index--) {
-      const candidate = [turns[index], ...accepted];
-      const candidateBytes = settings.measure({ ...base, thread: { ...base.thread, turns: candidate } });
-      if (accepted.length >= 2 && candidateBytes > settings.maxBytes) break;
-      accepted.unshift(turns[index]);
-      if (accepted.length === 1) firstOversized = candidateBytes > settings.maxBytes;
-      if (firstOversized || (accepted.length >= 2 && candidateBytes > settings.maxBytes)) break;
-    }
-    return accepted;
-  }
-
-  async extendHistoryRecord(threadId, record, options = {}) {
-    const settings = this.pageSettings(options);
-    if (!record.nextCursor || !record.thread.turns.length) return;
-    const firstOversized = settings.measure({ thread: record.thread, nextCursor: record.nextCursor }) > settings.maxBytes;
-    if (firstOversized) return;
-    while (record.nextCursor && record.thread.turns.length < settings.maxTurns) {
-      const cursor = record.nextCursor;
-      const page = await this.request('thread/turns/list', {
-        threadId, cursor, limit: 1, sortDirection: 'desc', itemsView: 'summary',
-      });
-      if (!Array.isArray(page.data) || !page.data.length) {
-        record.nextCursor = page.nextCursor ?? null;
-        break;
-      }
-      const candidate = [await this.compactTurn(threadId, page.data[0]), ...record.thread.turns];
-      const value = { thread: { ...record.thread, turns: candidate }, nextCursor: page.nextCursor ?? null };
-      if (record.thread.turns.length >= 2 && settings.measure(value) > settings.maxBytes) break;
-      record.thread.turns = candidate;
-      record.nextCursor = page.nextCursor ?? null;
-      if (record.thread.turns.length >= 2 && settings.measure(value) > settings.maxBytes) break;
-    }
-  }
-
-  async history(threadId, cursor, options = {}) {
-    await this.connect();
-    if (!cursor) throw new Error('缺少历史分页游标。');
-    const settings = this.pageSettings(options), turns = [];
-    let firstOversized = false;
-    let nextCursor = cursor;
-    while (nextCursor && turns.length < settings.maxTurns) {
-      const pageCursor = nextCursor;
-      const page = await this.request('thread/turns/list', {
-        threadId, cursor: pageCursor, limit: 1, sortDirection: 'desc', itemsView: 'summary',
-      });
-      if (!Array.isArray(page.data) || !page.data.length) {
-        nextCursor = page.nextCursor ?? null;
-        break;
-      }
-      const compact = await this.compactTurn(threadId, page.data[0]);
-      const candidate = [compact, ...turns];
-      const value = { thread: { id: threadId, turns: candidate }, nextCursor: page.nextCursor ?? null };
-      const candidateBytes = settings.measure(value);
-      if (turns.length >= 2 && candidateBytes > settings.maxBytes) break;
-      turns.unshift(compact);
-      nextCursor = page.nextCursor ?? null;
-      if (turns.length === 1) firstOversized = candidateBytes > settings.maxBytes;
-      if (firstOversized || (turns.length >= 2 && candidateBytes > settings.maxBytes)) break;
-    }
-    return { thread: { id: threadId, turns }, nextCursor };
-  }
-
-  async interrupt(threadId, turnId) {
-    await this.connect();
-    this.requireWritable(threadId);
-    return this.request('turn/interrupt', { threadId, turnId });
+      snapshot, catchup, confirmed, release };
+  }
+
+  pageSettings(options = {}) {
+    return {
+      maxTurns: Math.max(1, Math.min(historyPageMaxTurns, Number(options.maxTurns) || historyPageMaxTurns)),
+      maxBytes: Math.max(1, Number(options.maxBytes) || historyPageMaxBytes),
+      measure: typeof options.measure === 'function' ? options.measure : value => Buffer.byteLength(JSON.stringify(value)),
+    };
+  }
+
+  historyCursor(threadId, turn, turnCursor) {
+    const itemCursor = turn?.itemPage?.olderCursor;
+    if (!itemCursor && !turnCursor) return null;
+    // Upstream history cursors identify stored positions, not this observer.
+    return JSON.stringify({ threadId, turnId: itemCursor ? turn.id : null,
+      itemCursor: itemCursor || null, turnCursor: turnCursor || null });
+  }
+
+  async compactTurn(threadId, turn, cursor = null, apply, limit = 100) {
+    if (!turn?.id) return events.compactTurn(turn);
+    return this.request('thread/items/list', {
+      threadId, turnId: turn.id, ...(cursor ? { cursor } : {}), limit, sortDirection: 'desc',
+    }, page => {
+      const result = this.projectItemPage(threadId, turn, cursor, page);
+      apply?.(result); return result;
+    });
+  }
+
+  isThreadObserved(threadId, record) {
+    const slot = this.subscriptions.get(threadId);
+    return Boolean(slot?.users || slot?.readers || record.tokens.size);
+  }
+
+  unsubscribeThread(threadId) { return this.request('thread/unsubscribe', { threadId }); }
+
+  async readOnlyRecord(threadId, pageOptions, reason) {
+    const [read, page] = await Promise.all([
+      this.request('thread/read', { threadId, includeTurns: false }),
+      this.request('thread/turns/list', { threadId, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' }),
+    ]);
+    const compact = await Promise.all([...(page.data || [])].reverse().map(turn => this.compactTurn(threadId, turn)));
+    const turns = this.fitTurns({ thread: read.thread }, compact, pageOptions);
+    const thread = { ...read.thread, turns, readOnly: true, readOnlyReason: reason };
+    const record = { thread, nextCursor: page.nextCursor ?? null, sequence: 0, recoverAfter: 0,
+      changes: new Map(), changeBytes: 0, tokens: new Map(), readOnly: true };
+    this.threads.set(threadId, record);
+    this.contexts.set(threadId, { model: thread.model, thinking: thread.reasoningEffort, cwd: thread.cwd });
+    return record;
+  }
+
+  projectItemPage(threadId, turn, cursor, page) {
+    const compact = events.compactTurn(turn);
+    if (!Array.isArray(page.data)) throw new Error('Codex 内核未返回单轮条目索引。');
+    if (page.nextCursor && page.nextCursor === cursor) throw new Error('条目分页游标未推进。');
+    if (page.data.some(entry => entry.turnId !== turn.id)) throw new Error('条目所属轮次不匹配。');
+    const items = [...page.data].reverse().map(entry => events.compactItem(entry.item));
+    return { ...compact, items, itemPage: { olderCursor: page.nextCursor ?? null,
+      hasLoadedOldest: !page.nextCursor, oldestItemId: items[0]?.id || null,
+      newestItemId: items.at(-1)?.id || null, requestedCursor: cursor, projection: 'mobile-skeleton' } };
+  }
+
+  async turnContext(threadId, turnId) {
+    await this.connect();
+    if (!threadId || !turnId) throw new Error('缺少图片所属的对话或轮次。');
+    let turn = await this.compactTurn(threadId, { id: turnId });
+    while (turn.itemPage.olderCursor) {
+      const older = await this.compactTurn(threadId, { id: turnId }, turn.itemPage.olderCursor);
+      turn = { ...turn, items: [...older.items, ...turn.items], itemPage: older.itemPage };
+    }
+    return turn;
+  }
+
+  fitTurns(base, turns, options = {}) {
+    const settings = this.pageSettings(options), accepted = [];
+    let firstOversized = false;
+    for (let index = turns.length - 1; index >= 0 && accepted.length < settings.maxTurns; index--) {
+      const candidate = [turns[index], ...accepted];
+      const candidateBytes = settings.measure({ ...base, thread: { ...base.thread, turns: candidate } });
+      if (accepted.length >= 2 && candidateBytes > settings.maxBytes) break;
+      accepted.unshift(turns[index]);
+      if (accepted.length === 1) firstOversized = candidateBytes > settings.maxBytes;
+      if (firstOversized || (accepted.length >= 2 && candidateBytes > settings.maxBytes)) break;
+    }
+    return accepted;
+  }
+
+  async history(threadId, cursor, options = {}) {
+    await this.connect();
+    if (!cursor) throw new Error('缺少历史分页游标。');
+    let position;
+    try { position = JSON.parse(cursor); } catch { position = null; }
+    if (position?.threadId !== threadId) throw Object.assign(new Error('历史游标不属于当前对话。'), { code: 'history_cursor_expired' });
+    if (position.itemCursor && position.turnId) {
+      const turn = await this.compactTurn(threadId, { id: position.turnId }, position.itemCursor, undefined, options.itemLimit ?? 100);
+      return { thread: { id: threadId, turns: [turn] },
+        nextCursor: this.historyCursor(threadId, turn, position.turnCursor) };
+    }
+    const page = await this.request('thread/turns/list', {
+      threadId, cursor: position.turnCursor, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded',
+    });
+    if (!Array.isArray(page.data)) throw new Error('Codex 内核未返回轮次分页。');
+    if (page.nextCursor && page.nextCursor === position.turnCursor) throw new Error('轮次分页游标未推进。');
+    const turns = page.data.length ? [await this.compactTurn(threadId, page.data[0], null, undefined, options.itemLimit ?? 100)] : [];
+    return { thread: { id: threadId, turns }, nextCursor: this.historyCursor(threadId, turns[0], page.nextCursor) };
+  }
+
+  async interrupt(threadId, turnId) {
+    await this.connect();
+    this.requireWritable(threadId);
+    return this.request('turn/interrupt', { threadId, turnId });
   }
 
   async models() {
@@ -463,16 +575,16 @@ export class SharedAppServer extends EventEmitter {
     return this.usageCache.read(() => this.request('account/rateLimits/read'));
   }
 
-  async settings(threadId, model, effort, serviceTier) {
-    await this.connect();
-    this.requireWritable(threadId);
-    await events.updateSettings((method, params) => this.request(method, params), this.contexts, this.settingsNotifications, threadId, model, effort, serviceTier);
+  async settings(threadId, model, effort, serviceTier) {
+    await this.connect();
+    this.requireWritable(threadId);
+    await events.updateSettings((method, params) => this.request(method, params), this.contexts, threadId, model, effort, serviceTier);
     return this.context(threadId);
   }
 
-  async permissions(threadId, mode) {
-    await this.connect();
-    this.requireWritable(threadId);
+  async permissions(threadId, mode) {
+    await this.connect();
+    this.requireWritable(threadId);
     await events.updatePermissions((method, params) => this.request(method, params), this.contexts, this.settingsNotifications, this.permissionOptions, threadId, mode);
     return this.context(threadId);
   }
@@ -483,30 +595,17 @@ export class SharedAppServer extends EventEmitter {
     return this.context(threadId);
   }
 
-  context(threadId) {
+  context(threadId) {
     const context = this.permissionOptions.context(threadId, this.contexts.get(threadId) || {}), usage = context.tokenUsage;
     const usedTokens = usage?.last?.totalTokens, contextWindow = usage?.modelContextWindow;
     return { ...context, available: Boolean(contextWindow), usedTokens, contextWindow,
       usedPercent: contextWindow ? 100 * usedTokens / contextWindow : 0 };
-  }
-
-  requireWritable(threadId) {
-    const record = this.threads.get(threadId);
-    if (record?.readOnly) throw new ThreadWriterConflictError(threadId, record.thread.readOnlyReason);
-  }
-
-  close() { this.socket?.close(); }
-}
-
-function operationOutline(items, hasMore) {
-  const types = new Set(items.map(item => item?.type));
-  const parts = [];
-  if (types.has('fileChange')) parts.push('编辑了文件');
-  if (types.has('commandExecution')) parts.push('运行了命令');
-  if (types.has('mcpToolCall') || types.has('dynamicToolCall')) parts.push('调用了工具');
-  if (types.has('webSearch')) parts.push('搜索了网页');
-  if (types.has('imageView')) parts.push('查看了图像');
-  if (types.has('collabAgentToolCall') || types.has('subAgentActivity')) parts.push('处理了子任务');
-  const available = hasMore || items.some(item => item && !['userMessage', 'agentMessage'].includes(item.type));
-  return { available, title: parts.length ? `${parts.join(' · ')}${hasMore ? '等' : ''}` : '执行过程' };
-}
+  }
+
+  requireWritable(threadId) {
+    const record = this.threads.get(threadId);
+    if (record?.readOnly) throw new ThreadWriterConflictError(threadId, record.thread.readOnlyReason);
+  }
+
+  close() { this.socket?.close(); }
+}