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

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

@@ -1,611 +1,615 @@
-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 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('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.releaseInactiveThread(id);
-    });
-    this.threads = new Map();
-    this.contexts = new Map();
-    this.settingsNotifications = new Map();
-    this.permissionOptions = new events.PermissionOptionsCache();
-    this.subscriptions = new Map();
-    this.usageCache = new events.UsageCache(value => this.emit('usage', value));
-  }
-
-  async connect() {
-    if (this.socket?.readyState === WebSocket.OPEN && this.ready) return;
-    if (this.connecting) return this.connecting;
-    this.connecting = this.open().finally(() => { this.connecting = null; });
-    return this.connecting;
-  }
-
-  openSocket() {
-    return new WebSocket(this.url, { handshakeTimeout: 5000 });
-  }
-
-  async open() {
-    const socket = await this.openSocket();
-    this.socket = socket;
-    this.ready = false;
-    this.serverVersion = '';
-    this.serverRequests.reset(randomUUID());
-    socket.on('message', bytes => {
-      let message;
-      try { message = JSON.parse(bytes.toString()); } catch { socket.close(); return; }
-      if (message.method && message.id !== undefined) { this.serverRequests.receive(message); return; }
-      if (message.method) { this.notification(message.method, message.params || {}); return; }
-      const pending = this.pending.get(message.id);
-      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,
-            ...(/^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('Codex 内核连接断开；发送结果可能未确认，请检查对话后再操作。'));
-      }
-      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();
-      this.settingsNotifications.clear();
-      this.permissionOptions.clear();
-      this.usageCache.reset();
-      this.emit('disconnected');
-    });
-    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 {
-      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, transform = value => value) {
-    const id = ++this.sequence;
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        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, transform, threadId: params?.threadId });
-      this.socket.send(JSON.stringify({ id, method, params }), error => {
-        const pending = this.pending.get(id);
-        if (!error || !pending) return;
-        this.pending.delete(id);
-        clearTimeout(timer); pending.reject(error);
-      });
-    });
-  }
-
-  async projects() {
-    await this.connect();
-    return events.readProjects((method, params) => this.request(method, params));
-  }
-
-  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;
-    }
-  }
-
-  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());
-    }));
-  }
-
-  notification(method, params) {
-    this.serverRequests.notification(method, params);
-    this.emit('notification', { method, params });
-    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.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);
-      this.emit('settings', id);
-      return;
-    }
-    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 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 }));
-      if (record.changeBytes > syncBufferMaxBytes) {
-        record.recoverAfter = sequence;
-        record.changes.clear(); record.changeBytes = 0;
-      }
-      this.emit('turn', { thread: record.thread, turn, sequence,
-        immediate: ['turn/completed', 'item/completed'].includes(method) });
-    }
-    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));
-  }
-
-  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), 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: 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);
-      }
-    });
-    return task;
-  }
-
-  slot(threadId) {
-    let slot = this.subscriptions.get(threadId);
-    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);
-    const expiries = record ? [...record.tokens.values()].map(token => token.expires) : [];
-    const next = expiries.length ? Math.max(1, Math.min(...expiries) - Date.now()) : 1;
-    slot.expiry = setTimeout(() => this.cleanup(threadId, slot), next);
-  }
-
-  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 || 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 (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.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;
-    if (record && requested?.epoch === this.epoch && requested.id && Number.isSafeInteger(requested.after)) {
-      token = record.tokens.get(requested.id);
-      if (!token || token.expires <= Date.now() || token.sequence !== requested.after) token = undefined;
-    }
-    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 = 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 && !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 },
-        sync: { id: requested.id, epoch: this.epoch, fromSeq: requested.after + 1, toSeq: current } };
-    }
-    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: this.historyCursor(threadId, record.thread.turns[0], record.nextCursor),
-      sync: { id: requested.id, epoch: this.epoch, seq: current, ...(snapshot ? { reset: true } : {}) } },
-      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() {
-    await this.connect();
-    const models = []; let cursor;
-    do {
-      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 };
-  }
-
-  async usage() {
-    await this.connect();
-    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, threadId, model, effort, serviceTier);
-    return this.context(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);
-  }
-
-  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(); }
-}
+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 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('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.releaseInactiveThread(id);
+    });
+    this.threads = new Map();
+    this.contexts = new Map();
+    this.settingsNotifications = new Map();
+    this.permissionOptions = new events.PermissionOptionsCache();
+    this.subscriptions = new Map();
+    this.usageCache = new events.UsageCache(value => this.emit('usage', value));
+  }
+
+  async connect() {
+    if (this.socket?.readyState === WebSocket.OPEN && this.ready) return;
+    if (this.connecting) return this.connecting;
+    this.connecting = this.open().finally(() => { this.connecting = null; });
+    return this.connecting;
+  }
+
+  openSocket() {
+    return new WebSocket(this.url, { handshakeTimeout: 5000 });
+  }
+
+  async open() {
+    const socket = await this.openSocket();
+    this.socket = socket;
+    this.ready = false;
+    this.serverVersion = '';
+    this.serverRequests.reset(randomUUID());
+    socket.on('message', bytes => {
+      let message;
+      try { message = JSON.parse(bytes.toString()); } catch { socket.close(); return; }
+      if (message.method && message.id !== undefined) { this.serverRequests.receive(message); return; }
+      if (message.method) { this.notification(message.method, message.params || {}); return; }
+      const pending = this.pending.get(message.id);
+      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,
+            ...(/^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('Codex 内核连接断开；发送结果可能未确认，请检查对话后再操作。'));
+      }
+      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();
+      this.settingsNotifications.clear();
+      this.permissionOptions.clear();
+      this.usageCache.reset();
+      this.emit('disconnected');
+    });
+    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 {
+      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, transform = value => value) {
+    const id = ++this.sequence;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        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, transform, threadId: params?.threadId });
+      this.socket.send(JSON.stringify({ id, method, params }), error => {
+        const pending = this.pending.get(id);
+        if (!error || !pending) return;
+        this.pending.delete(id);
+        clearTimeout(timer); pending.reject(error);
+      });
+    });
+  }
+
+  async projects() {
+    await this.connect();
+    return events.readProjects((method, params) => this.request(method, params));
+  }
+
+  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;
+        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 } }));
+      }
+      submitted = true;
+      return await this.request('turn/start', args,
+        result => ({ result, usage: { kind: 'start', turnId: result?.turn?.id || null } }));
+    } catch (error) {
+      if (!submitted || messageDelivery.rejectedBeforeSubmission(error)) error.deliveryUnknown = false;
+      throw error;
+    }
+  }
+
+  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());
+    }));
+  }
+
+  notification(method, params) {
+    this.serverRequests.notification(method, params);
+    this.emit('notification', { method, params });
+    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.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);
+      this.emit('settings', id);
+      return;
+    }
+    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;
+    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: appliedParams }));
+      if (record.changeBytes > syncBufferMaxBytes) {
+        record.recoverAfter = sequence;
+        record.changes.clear(); record.changeBytes = 0;
+      }
+      this.emit('turn', { thread: record.thread, turn, sequence,
+        immediate: ['turn/completed', 'item/completed'].includes(method) });
+    }
+    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));
+  }
+
+  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), 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: 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);
+      }
+    });
+    return task;
+  }
+
+  slot(threadId) {
+    let slot = this.subscriptions.get(threadId);
+    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);
+    const expiries = record ? [...record.tokens.values()].map(token => token.expires) : [];
+    const next = expiries.length ? Math.max(1, Math.min(...expiries) - Date.now()) : 1;
+    slot.expiry = setTimeout(() => this.cleanup(threadId, slot), next);
+  }
+
+  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 || 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 (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.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;
+    if (record && requested?.epoch === this.epoch && requested.id && Number.isSafeInteger(requested.after)) {
+      token = record.tokens.get(requested.id);
+      if (!token || token.expires <= Date.now() || token.sequence !== requested.after) token = undefined;
+    }
+    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 = 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 && !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 },
+        sync: { id: requested.id, epoch: this.epoch, fromSeq: requested.after + 1, toSeq: current } };
+    }
+    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: this.historyCursor(threadId, record.thread.turns[0], record.nextCursor),
+      sync: { id: requested.id, epoch: this.epoch, seq: current, ...(snapshot ? { reset: true } : {}) } },
+      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() {
+    await this.connect();
+    const models = []; let cursor;
+    do {
+      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 };
+  }
+
+  async usage() {
+    await this.connect();
+    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, threadId, model, effort, serviceTier);
+    return this.context(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);
+  }
+
+  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(); }
+}