@walkhi/code-relax 0.1.0-beta.1 → 0.1.0-beta.100

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

@@ -2,42 +2,51 @@ 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';
+import { desktopPermissionMode } from './platform/desktop-permission-mode.mjs';
 
-const syncTokenTtlMs = 30_000;
-const syncBufferMaxBytes = 8 * 1024 * 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));
-}
+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('该对话存在写入冲突，请稍后重试。');
+    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.connectionId = null;
     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.settingsNotifications = new events.SettingsNotifications();
     this.permissionOptions = new events.PermissionOptionsCache();
     this.subscriptions = new Map();
     this.usageCache = new events.UsageCache(value => this.emit('usage', value));
@@ -50,10 +59,16 @@ 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.connectionId = randomUUID();
     this.ready = false;
+    this.serverVersion = '';
     this.serverRequests.reset(randomUUID());
     socket.on('message', bytes => {
       let message;
@@ -64,19 +79,29 @@ 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 请求失败');
+        this.traceLifecycle('error', pending, { rpcCode: message.error.code,
+          writerError: writerConflictMessages.find(value => text.toLowerCase().includes(value)) || null });
+        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 {
+        this.traceLifecycle('complete', pending, { status: message.result?.status,
+          resultThreadId: message.result?.thread?.id, resultServiceTier: message.result?.serviceTier });
+        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('完整控制连接断开；发送结果可能未确认，请检查对话后再操作。'));
+        this.traceLifecycle('disconnected', pending);
+        pending.reject(new Error('Codex 内核连接断开；发送结果可能未确认，请检查对话后再操作。'));
       }
       this.pending.clear();
       this.serverRequests.reset(randomUUID());
@@ -92,51 +117,142 @@ 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. Its name
+      // may contain spaces ("Codex Desktop"); the slash delimits the version.
+      // Do not substitute the selected executable's pending version.
+      this.serverVersion = String(initialized?.userAgent || '').match(/^[^/]+\/([^\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;
+    const diagnostic = { method, requestId: id, threadId: params?.threadId, connectionId: this.connectionId,
+      ...(method === 'thread/settings/update' && params?.serviceTier !== undefined ? { serviceTier: params.serviceTier } : {}) };
+    this.traceLifecycle('begin', diagnostic);
     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' });
+        this.traceLifecycle('timeout', diagnostic);
+        if (['turn/start', 'turn/steer', 'thread/queue/add'].includes(method) && 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, ...diagnostic });
       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.traceLifecycle('send-error', diagnostic);
+        this.pending.delete(id);
+        clearTimeout(timer); pending.reject(error);
       });
     });
   }
 
+  traceLifecycle(phase, request, extra = {}) {
+    if (!['thread/start', 'thread/resume', 'thread/unsubscribe', 'thread/settings/update', 'thread/settings/updated'].includes(request.method)) return;
+    const threadId = value => typeof value === 'string' && /^[\w-]{1,80}$/.test(value) ? value : null;
+    const identity = this.diagnosticIdentity?.() || {};
+    console.info('[thread-lifecycle]', JSON.stringify({ time: new Date().toISOString(), bridgePid: process.pid,
+      kernelPid: identity.kernelPid ?? null, kernelCreated: identity.kernelCreated ?? null,
+      connectionId: request.connectionId, serverVersion: this.serverVersion, phase,
+      method: request.method, requestId: request.requestId, threadId: threadId(request.threadId),
+      ...([null, 'default', 'priority', 'fast'].includes(request.serviceTier) ? { serviceTier: request.serviceTier } : {}),
+      ...(extra.resultThreadId ? { resultThreadId: threadId(extra.resultThreadId) } : {}),
+      ...(extra.resultServiceTier !== undefined && [null, 'default', 'priority', 'fast'].includes(extra.resultServiceTier)
+        ? { resultServiceTier: extra.resultServiceTier } : {}),
+      ...(typeof extra.status === 'string' && /^[\w-]{1,40}$/.test(extra.status) ? { status: extra.status } : {}),
+      ...(typeof extra.rpcCode === 'number' ? { rpcCode: extra.rpcCode } : {}),
+      ...(extra.writerError ? { writerError: extra.writerError } : {}) }));
+  }
+
   async projects() {
     await this.connect();
     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 } : {}) });
+  startThread(target) {
+    return this.request('thread/start', target, result => {
+      // thread/start already subscribes this connection. Retain its authoritative
+      // empty snapshot before turn/start can emit events; immediately resuming
+      // would unnecessarily read history that may not have been persisted yet.
+      const thread = result.thread;
+      const record = { thread: { ...thread, turns: (thread.turns || []).map(turn => events.compactTurn(turn)) },
+        nextCursor: null, sequence: 0, recoverAfter: 0, changes: new Map(), changeBytes: 0,
+        tokens: new Map([[randomUUID(), { sequence: 0, expires: Date.now() + syncTokenTtlMs }]]) };
+      this.threads.set(thread.id, record);
+      this.contexts.set(thread.id, { model: result.model, thinking: result.reasoningEffort,
+        serviceTier: result.serviceTier ?? null, cwd: result.cwd, ...events.permissionState(result) });
+      this.scheduleCleanup(thread.id, this.slot(thread.id));
+      return result;
+    });
+  }
+
+  async send(args, { assertCurrent = () => {}, useGlobalPermissions = true } = {}) {
+    let submitted = false;
+    let sendPhase = 'connect';
+    try {
+      await this.connect();
+      sendPhase = 'writable';
+      this.requireWritable(args.threadId);
+      // Reading the live thread checks this service owns it without resume changing settings.
+      sendPhase = 'thread-read';
+      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') {
+        sendPhase = 'active-turn';
+        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;
+        sendPhase = 'turn-steer';
+        return await this.request('turn/steer', { threadId: args.threadId, expectedTurnId: active.id, input: args.input, ...source, ...(args.clientUserMessageId ? { clientUserMessageId: args.clientUserMessageId } : {}) },
+          result => ({ result, usage: { kind: 'steer', turnId: active.id } }));
+      }
+      sendPhase = 'permissions';
+      const permissions = useGlobalPermissions ? await events.globalPermissionOverrides((method, params) => this.request(method, params),
+        { ...this.contexts.get(args.threadId), desktopPermissionMode: await desktopPermissionMode(), model: args.model || this.contexts.get(args.threadId)?.model }, args.threadId) : {};
+      assertCurrent();
+      submitted = true;
+      sendPhase = 'turn-start';
+      return await this.request('turn/start', { ...args, ...permissions },
+        result => ({ result, usage: { kind: 'start', turnId: result?.turn?.id || null } }));
+    } catch (error) {
+      if (!submitted || messageDelivery.rejectedBeforeSubmission(error)) error.deliveryUnknown = false;
+      error.details = { ...(error.details && typeof error.details === 'object' ? error.details : {}), sendPhase,
+        ...(Number.isInteger(error.rpcCode) ? { rpcCode: error.rpcCode } : {}) };
+      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);
+  async prepareGoalActivation(threadId, { useGlobalPermissions = true } = {}) {
+    this.requireWritable(threadId);
+    const record = this.threads.get(threadId);
+    if (!record || record.needsReload || record.hydrating) throw new Error('请等待对话同步完成后再开始目标');
+    if (!useGlobalPermissions) return;
+    const request = (method, params) => this.request(method, params);
+    const permissions = await events.globalPermissionOverrides(request,
+      { ...this.contexts.get(threadId), desktopPermissionMode: await desktopPermissionMode() }, threadId);
+    if (Object.keys(permissions).length) await request('thread/settings/update', { threadId, ...permissions });
+  }
+
+  async findSentMessage(threadId, clientId, anchorItemId) {
+    await this.connect();
+    return messageDelivery.findMessage((method, params) => this.request(method, params), threadId, clientId, anchorItemId);
+  }
+
+  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());
     }));
@@ -145,11 +261,13 @@ export class SharedAppServer extends EventEmitter {
   notification(method, params) {
     this.serverRequests.notification(method, params);
     this.emit('notification', { method, params });
+    if (['thread/goal/updated', 'thread/goal/cleared'].includes(method)) return;
     if (method === 'thread/queue/changed') { this.emit('queue-changed', params.threadId); return; }
     if (method === 'account/rateLimits/updated') { this.usageCache.update(params); return; }
     const id = params.threadId;
     if (method === 'thread/settings/updated') {
       const settings = params.threadSettings;
+      this.traceLifecycle('notification', { method, threadId: id, connectionId: this.connectionId, serviceTier: settings.serviceTier ?? null });
       this.contexts.set(id, { ...this.contexts.get(id), model: settings.model, thinking: settings.effort, serviceTier: settings.serviceTier ?? null,
         cwd: settings.cwd, ...events.permissionState(settings) });
       this.settingsNotifications.set(id, settings);
@@ -162,11 +280,43 @@ export class SharedAppServer extends EventEmitter {
     }
     const record = this.threads.get(id);
     if (!record) return;
-    const turn = events.applyNotification(record.thread, method, params);
+    if (method === 'thread/name/updated') {
+      record.thread.name = params.threadName;
+      return; // Catalog metadata must not invalidate or replay message bodies.
+    }
+    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 }));
+      record.changeBytes += Buffer.byteLength(JSON.stringify({ method, params: appliedParams }));
       if (record.changeBytes > syncBufferMaxBytes) {
         record.recoverAfter = sequence;
         record.changes.clear(); record.changeBytes = 0;
@@ -174,53 +324,114 @@ 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);
+  }
+
+  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));
   }
 
-  async timeline(threadId) {
+  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: 10, sortDirection: 'desc', itemsView: 'full' } });
-        } catch (error) {
-          if (!isThreadWriterConflict(error)) throw error;
-          const read = await this.request('thread/read', { threadId, includeTurns: true });
-          const turns = Array.isArray(read.thread?.turns) ? read.thread.turns.slice(-10) : [];
-          const thread = { ...read.thread, turns, readOnly: true,
-            readOnlyReason: '该对话正在另一个 Codex 实例中使用。' };
-          record = { thread, 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 thread = { ...result.thread, turns: [...result.initialTurnsPage.data].reverse() };
-          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) });
-        }
+      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;
+        const settingsBeforeResume = this.settingsNotifications.get(threadId);
+        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, '该对话存在写入冲突，请稍后重试。');
+          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;
+          if (this.settingsNotifications.get(threadId) === settingsBeforeResume) {
+            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);
@@ -231,10 +442,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);
@@ -246,15 +465,39 @@ 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;
+      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;
+      if (this.ready && !record?.readOnly) await this.unsubscribeThread(threadId);
+      // Keep this queue registered until unsubscribe completes. A returning reader
+      // must enqueue its resume behind it, rather than creating a second queue.
+      if (this.subscriptions.get(threadId) !== slot) 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);
-    }).catch(error => this.emit('subscription-error', error));
+      if (!slot.users && !slot.readers) this.subscriptions.delete(threadId);
+      clearTimeout(slot.expiry);
+      this.serverRequests.forget(threadId);
+    }).catch(error => {
+      if (this.subscriptions.get(threadId) === slot && this.threads.get(threadId) === record && record) record.needsReload = true;
+      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) {
@@ -264,18 +507,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, chatRevision: requested?.chatRevision });
       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 },
@@ -283,25 +528,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 };
+      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) {
+  async history(threadId, cursor, options = {}) {
     await this.connect();
     if (!cursor) throw new Error('缺少历史分页游标。');
-    const result = await this.request('thread/turns/list', { threadId, cursor, limit: 10, sortDirection: 'desc', itemsView: 'full' });
-    return { thread: { id: threadId, turns: [...result.data].reverse() }, nextCursor: result.nextCursor ?? null };
+    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 interrupt(threadId, turnId) {
+    await this.connect();
+    this.requireWritable(threadId);
+    return this.request('turn/interrupt', { threadId, turnId });
   }
 
   async models() {
@@ -311,8 +658,14 @@ export class SharedAppServer extends EventEmitter {
       const result = await this.request('model/list', { limit: 100, ...(cursor ? { cursor } : {}) });
       models.push(...result.data); cursor = result.nextCursor;
     } while (cursor);
-    const config = await this.request('config/read', { includeLayers: false });
-    return { models: models.filter(model => !model.hidden), enabledReasoningEfforts: config.config?.desktop?.['enabled-reasoning-efforts'] ?? null };
+    let config, configWarning;
+    try { config = await this.request('config/read', { includeLayers: false }); }
+    catch (error) {
+      configWarning = `读取思考强度偏好失败：${error.message}`;
+      console.warn('[model-catalog]', configWarning);
+    }
+    return { models: models.filter(model => !model.hidden), enabledReasoningEfforts: config?.config?.desktop?.['enabled-reasoning-efforts'] ?? null,
+      ...(configWarning ? { configWarning } : {}) };
   }
 
   async usage() {
@@ -320,37 +673,46 @@ 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);
   }
 
   async readContext(threadId) {
-    const context = this.contexts.get(threadId);
-    if (context) await this.permissionOptions.read((method, params) => this.request(method, params), threadId, context);
-    return this.context(threadId);
+    const context = { ...this.contexts.get(threadId), desktopPermissionMode: await desktopPermissionMode() };
+    const permissions = await events.readGlobalPermissions((method, params) => this.request(method, params), context || {}, this.permissionOptions, threadId);
+    return { ...this.context(threadId), ...permissions };
+  }
+
+  async globalPermissions(mode, { threadId = '', cwd = '' } = {}) {
+    await this.connect();
+    if (threadId && !this.contexts.has(threadId)) throw new Error('对话设置尚未加载');
+    const context = { ...(threadId ? this.contexts.get(threadId) : { cwd }), desktopPermissionMode: await desktopPermissionMode() };
+    const request = (method, params) => this.request(method, params);
+    return mode === undefined ? events.readGlobalPermissions(request, context, this.permissionOptions, threadId)
+      : events.writeGlobalPermissions(request, mode, context, this.permissionOptions, 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(); }
-}
+  }
+
+  requireWritable(threadId) {
+    const record = this.threads.get(threadId);
+    if (record?.readOnly) throw new ThreadWriterConflictError(threadId, record.thread.readOnlyReason);
+  }
+
+  close() { this.socket?.close(); }
+}