Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

70.7 KB
Raw Blame
import { describe, expect, it, vi } from 'vitest';

import { AppServerHost, CodexNativeInitializationStoppedError } from './host.js';
import type { Logger } from '../../../interfaces/logger.js';
import type { Transport, LineHandler, StderrHandler, CloseHandler } from './transport.js';

/** 任何请求都永不回应的 transport — 模拟远端 daemon bootstrap 挂死 / SSH 通道无响应。 */
class HangingTransport implements Transport {
  private readonly closeHandlers = new Set<CloseHandler>();

  async writeLine(_line: string): Promise<void> {
    // 请求照收, 永远不回 response → initialize 挂起。
  }

  onLine(_handler: LineHandler): () => void {
    return () => {};
  }

  onClose(handler: CloseHandler): () => void {
    this.closeHandlers.add(handler);
    return () => this.closeHandlers.delete(handler);
  }

  onStderr(_handler: StderrHandler): () => void {
    return () => {};
  }

  async close(reason = 'test close'): Promise<void> {
    for (const handler of this.closeHandlers) handler({ reason });
  }
}

/** 所有请求延迟 respondDelayMs 回应的 transport — initialize 最终能完成。 */
class DelayedTransport implements Transport {
  private readonly lineHandlers = new Set<LineHandler>();
  private readonly closeHandlers = new Set<CloseHandler>();

  constructor(private readonly respondDelayMs: number) {}

  async writeLine(line: string): Promise<void> {
    const msg = JSON.parse(line) as { id?: unknown };
    if (msg.id == null) return; // notification (initialized 等), 无 response
    setTimeout(() => {
      const result = {
        userAgent: 'mock-codex/test',
        codexHome: '/tmp/codex-home',
        platformOs: 'linux',
      };
      for (const handler of this.lineHandlers) handler(JSON.stringify({ id: msg.id, result }));
    }, this.respondDelayMs);
  }

  onLine(handler: LineHandler): () => void {
    this.lineHandlers.add(handler);
    return () => this.lineHandlers.delete(handler);
  }

  onClose(handler: CloseHandler): () => void {
    this.closeHandlers.add(handler);
    return () => this.closeHandlers.delete(handler);
  }

  onStderr(_handler: StderrHandler): () => void {
    return () => {};
  }

  async close(reason = 'test close'): Promise<void> {
    for (const handler of this.closeHandlers) handler({ reason });
  }
}

class RejectedInitializeTransport implements Transport {
  private readonly lineHandlers = new Set<LineHandler>();
  private readonly closeHandlers = new Set<CloseHandler>();
  closed = false;

  async writeLine(line: string): Promise<void> {
    const message = JSON.parse(line) as { id?: unknown; method?: string };
    if (message.id == null || message.method !== 'initialize') return;
    for (const handler of this.lineHandlers) {
      handler(JSON.stringify({
        id: message.id,
        error: { code: -32_000, message: 'initialize boom' },
      }));
    }
  }

  onLine(handler: LineHandler): () => void {
    this.lineHandlers.add(handler);
    return () => this.lineHandlers.delete(handler);
  }

  onClose(handler: CloseHandler): () => void {
    this.closeHandlers.add(handler);
    return () => this.closeHandlers.delete(handler);
  }

  onStderr(_handler: StderrHandler): () => void {
    return () => {};
  }

  async close(reason = 'test close'): Promise<void> {
    if (this.closed) return;
    this.closed = true;
    for (const handler of this.closeHandlers) handler({ reason });
  }
}

class NotificationTransport implements Transport {
  private readonly lineHandlers = new Set<LineHandler>();
  private readonly closeHandlers = new Set<CloseHandler>();
  readonly lines: string[] = [];

  constructor(
    private readonly resultForMethod?: (method: string) => unknown,
  ) {}

  async writeLine(line: string): Promise<void> {
    this.lines.push(line);
    const msg = JSON.parse(line) as { id?: unknown; method?: string };
    if (msg.id == null) return;
    const result = msg.method === 'initialize'
      ? {
          userAgent: 'mock-codex/test',
          codexHome: '/tmp/codex-home',
          platformOs: 'linux',
        }
      : this.resultForMethod?.(msg.method ?? '') ?? {};
    this.emit({ id: msg.id, result });
  }

  onLine(handler: LineHandler): () => void {
    this.lineHandlers.add(handler);
    return () => this.lineHandlers.delete(handler);
  }

  onClose(handler: CloseHandler): () => void {
    this.closeHandlers.add(handler);
    return () => this.closeHandlers.delete(handler);
  }

  onStderr(_handler: StderrHandler): () => void {
    return () => {};
  }

  async close(reason = 'test close'): Promise<void> {
    for (const handler of this.closeHandlers) handler({ reason });
  }

  emit(message: unknown): void {
    const line = JSON.stringify(message);
    for (const handler of this.lineHandlers) handler(line);
  }
}

describe('concrete writer candidate proof', () => {
  it.each(['request', 'notification', 'subscription'])('retains %s evidence until confirmed process exit', async (source) => {
    const transports: NotificationTransport[] = [];
    const host = new AppServerHost({ createTransport: () => {
      const transport = new NotificationTransport(); transports.push(transport); return transport;
    }, logger, clientInfo: { name: 'test', version: '0' } });
    try {
      await host.ensureStarted();
      expect(host.writerCandidate).toBeNull();
      await host.request('thread/loaded/list');
      expect(host.writerCandidate).toBeNull();
      if (source === 'request') await host.request('thread/resume', { threadId: 'source' });
      if (source === 'notification') transports[0].emit({ method: 'thread/started', params: { thread: { id: 'source' } } });
      if (source === 'subscription') host.subscribeThread('source', {});
      const proof = host.writerCandidate;
      expect(proof).not.toBeNull();
      const close = vi.spyOn(transports[0], 'close').mockRejectedValueOnce(new Error('exit not proven'));
      await expect(host.shutdown('test', { throwOnTransportError: true })).rejects.toThrow('exit not proven');
      expect(host.writerCandidate).toBe(proof);
      close.mockRestore();
      await host.shutdown('confirmed', { throwOnTransportError: true });
      expect(host.writerCandidate).toBeNull();
      await host.ensureStarted();
      expect(host.writerCandidate).toBeNull();
      // A late old notification cannot turn the replacement into an old writer.
      transports[0].emit({ method: 'thread/started', params: { thread: { id: 'source' } } });
      expect(host.writerCandidate).toBeNull();
      await host.request('thread/start');
      expect(host.writerCandidate).not.toBe(proof);
      expect(host.writerCandidate).not.toBeNull();
    } finally { await host.retire(); }
  });
});

describe('AppServerHost isolated account lifecycle', () => {
  it.each([false, true])('rejects persistent native policy before task dispatch (OAuth: %s)', async oauth => {
    const transport = new NotificationTransport(() => ({ config: { cli_auth_credentials_store: 'file' } }));
    const readTokens = vi.fn(async () => ({ accessToken: 'fixture-token', chatgptAccountId: 'account-b' }));
    const host = new AppServerHost({ createTransport: () => transport, logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' }, requireEphemeralAuth: true,
      ...(oauth ? { externalAuth: { readTokens } } : {}),
    });
    try {
      await expect(host.request('thread/resume', { threadId: 'fixture' })).rejects.toThrow('isolated account authentication');
      const methods = transport.lines.map(line => JSON.parse(line).method);
      expect(methods).not.toContain('account/login/start');
      expect(methods).not.toContain('thread/resume');
      expect(readTokens).not.toHaveBeenCalled();
    } finally { await host.retire(); }
  });

  it('never installs a credential read that finishes after retirement', async () => {
    const transport = new NotificationTransport(() => ({ config: { cli_auth_credentials_store: 'ephemeral' } }));
    let resolve!: (value: { accessToken: string; chatgptAccountId: string }) => void;
    const readTokens = vi.fn(() => new Promise<{ accessToken: string; chatgptAccountId: string }>(done => { resolve = done; }));
    const host = new AppServerHost({ createTransport: () => transport, logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' }, externalAuth: { readTokens },
    });
    const pending = host.ensureStarted();
    const rejected = expect(pending).rejects.toThrow();
    await vi.waitFor(() => expect(readTokens).toHaveBeenCalledOnce());
    const retiring = host.retire();
    resolve({ accessToken: 'late-fixture-secret', chatgptAccountId: 'account-b' });
    await retiring;
    await rejected;
    expect(transport.lines.join('\n')).not.toContain('late-fixture-secret');
  });
});

describe('AppServerHost assistant text delta routing', () => {
  it('subscribes to dedicated agentMessage deltas and routes them to the owning thread', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const initialize = transport.lines
      .map((line) => JSON.parse(line) as { method?: string; params?: { capabilities?: { optOutNotificationMethods?: string[] } } })
      .find((message) => message.method === 'initialize');
    expect(initialize?.params?.capabilities?.optOutNotificationMethods).not.toContain(
      'item/agentMessage/delta',
    );

    const agentMessageDelta = vi.fn();
    const subscription = host.subscribeThread('thread-1', { agentMessageDelta });
    const params = {
      threadId: 'thread-1',
      turnId: 'turn-1',
      itemId: 'msg-1',
      delta: 'Hello',
    };
    transport.emit({ method: 'item/agentMessage/delta', params });

    expect(agentMessageDelta).toHaveBeenCalledOnce();
    expect(agentMessageDelta).toHaveBeenCalledWith(params);

    await subscription.release();
    await host.shutdown();
  });
});

// 保护: account/rateLimits/updated 按 limitId 去重后, 不变的快照不再重复广播 (原先每
// ~3.5s 一条 account_usage), 但内容变化仍立即下发, 且晚到的 subscriber 仍能经 replay
// 立即拿到当前配额 (Codex chip 冷启动依赖它)。
describe('AppServerHost account rate limit fan-out', () => {
  it('drops only consecutive duplicate snapshots (keeping bucket order) and still replays the latest to late subscribers', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();
    const early = vi.fn();
    const earlySubscription = host.subscribeThread('thread-1', { accountRateLimitsUpdated: early });
    const snapshot = (limitId: string, usedPercent: number) => ({
      method: 'account/rateLimits/updated',
      params: { rateLimits: { limitId, primary: { usedPercent, windowDurationMins: 300, resetsAt: 1 } } },
    });

    transport.emit(snapshot('codex', 10));
    transport.emit(snapshot('codex', 10));
    transport.emit(snapshot('codex_spark', 10));
    transport.emit(snapshot('codex', 10));
    transport.emit(snapshot('codex', 20));

    expect(early.mock.calls.map(([p]) => [p.rateLimits.limitId, p.rateLimits.primary.usedPercent])).toEqual([
      ['codex', 10],
      ['codex_spark', 10],
      ['codex', 10],
      ['codex', 20],
    ]);

    transport.emit(snapshot('codex', 20));
    const late = vi.fn();
    const lateSubscription = host.subscribeThread('thread-2', { accountRateLimitsUpdated: late });
    expect(late.mock.calls.map(([p]) => [p.rateLimits.limitId, p.rateLimits.primary.usedPercent])).toEqual([
      ['codex_spark', 10],
      ['codex', 20],
    ]);
    expect(early).toHaveBeenCalledTimes(4);

    // 无 limitId 的稀疏更新不去重, 且仅在它是最新一条时才排在回放最后。
    const sparse = { method: 'account/rateLimits/updated', params: { rateLimits: { primary: { usedPercent: 30, windowDurationMins: 300, resetsAt: 1 } } } };
    transport.emit(sparse);
    transport.emit(sparse);
    expect(early).toHaveBeenCalledTimes(5);
    const afterSparse = vi.fn();
    const sparseSubscription = host.subscribeThread('thread-3', { accountRateLimitsUpdated: afterSparse });
    expect(afterSparse.mock.calls.map(([p]) => p.rateLimits.limitId ?? null)).toEqual(['codex_spark', 'codex', null]);
    await sparseSubscription.release();

    await earlySubscription.release();
    await lateSubscription.release();
    await host.shutdown();
  });
});

describe('AppServerHost custom Provider subagent policy', () => {
  const routes = [
    {
      providerId: 'images-a',
      modelProviderId: 'cindy_custom_aaaaaaaaaaaaaaaaaaaa',
      capabilities: { imageGeneration: true },
      responseModels: ['image-a', 'image-a-alt'],
    },
    {
      providerId: 'images-b',
      modelProviderId: 'cindy_custom_bbbbbbbbbbbbbbbbbbbb',
      capabilities: { imageGeneration: true },
      responseModels: ['image-b'],
    },
  ];

  function policy(
    root: { providerId: string; model: string },
    child?: { providerId: string; catalogModel: string },
  ) {
    const host = new AppServerHost({
      createTransport: () => new HangingTransport(),
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
      codexCustomProviderRoutes: routes,
      ...(child
        ? { subagentRoute: { ...child, reasoningEffort: null } }
        : {}),
    });
    return host.getCustomProviderThreadPolicy(root.providerId, root.model);
  }

  it('does not affect a non-image parent', () => {
    expect(policy({ providerId: 'images-a', model: 'text-a' }, {
      providerId: 'images-b',
      catalogModel: 'image-b',
    })).toEqual({
      dynamicIdentity: false,
      disableSubagents: false,
      disableModelOverrides: false,
    });
  });

  it.each([
    ['same Provider eligible child', 'images-a', 'image-a-alt', false],
    ['same Provider non-Responses child', 'images-a', 'text-a', true],
    ['different Provider child', 'images-b', 'image-b', true],
  ] as const)('%s', (_label, providerId, catalogModel, disableSubagents) => {
    expect(policy(
      { providerId: 'images-a', model: 'image-a' },
      { providerId, catalogModel },
    )).toEqual({
      dynamicIdentity: true,
      disableSubagents,
      disableModelOverrides: true,
    });
  });

  it('allows the second dynamic Provider with its own matching child', () => {
    expect(policy(
      { providerId: 'images-b', model: 'image-b' },
      { providerId: 'images-b', catalogModel: 'image-b' },
    )).toEqual({
      dynamicIdentity: true,
      disableSubagents: false,
      disableModelOverrides: true,
    });
  });
});

describe('AppServerHost shutdown completion', () => {
  it.each([false, true])('shutdown and retire wait for the same process (failure=%s)', async (fails) => {
    const transport = new NotificationTransport();
    let finish!: () => void;
    let fail!: (error: Error) => void;
    const completion = new Promise<void>((resolve, reject) => { finish = resolve; fail = reject; });
    const close = vi.spyOn(transport, 'close').mockImplementation(() => completion);
    const onRetired = vi.fn();
    const host = new AppServerHost({ createTransport: () => transport, logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' }, onRetired });
    await host.ensureStarted();
    const settled = vi.fn();
    const shutdown = host.shutdown().then(settled);
    const retire = host.retire('retire', { throwOnTransportError: true });
    const retirement = fails
      ? expect(retire).rejects.toThrow('exit not confirmed')
      : expect(retire).resolves.toBeUndefined();
    await Promise.resolve();
    await expect(host.ensureStarted()).rejects.toThrow('after retirement');
    expect(onRetired).not.toHaveBeenCalled();
    expect(settled).not.toHaveBeenCalled();
    if (fails) fail(new Error('exit not confirmed'));
    else finish();
    await Promise.all([shutdown, retirement]);
    expect(close).toHaveBeenCalledOnce();
    expect(onRetired).toHaveBeenCalledTimes(fails ? 0 : 1);
    if (fails) {
      await expect(host.shutdown('retry', { throwOnTransportError: true })).rejects.toThrow('exit not confirmed');
      expect(onRetired).not.toHaveBeenCalled();
      close.mockResolvedValue(undefined);
      await Promise.all([host.retire(), host.retire('late exit', { throwOnTransportError: true })]);
      expect(onRetired).toHaveBeenCalledOnce();
      await expect(retire).rejects.toThrow('exit not confirmed');
    }
    await host.retire();
    expect(close).toHaveBeenCalledTimes(fails ? 3 : 1);
    expect(onRetired).toHaveBeenCalledOnce();
    await expect(host.ensureStarted()).rejects.toThrow('after retirement');
  });

  it('rechecks failed shutdown before restarting and respects retirement during that recheck', async () => {
    const transport = new NotificationTransport();
    const close = vi.spyOn(transport, 'close').mockRejectedValue(new Error('exit not confirmed'));
    const createTransport = vi.fn().mockReturnValueOnce(transport).mockReturnValue(new NotificationTransport());
    const onRetired = vi.fn();
    const host = new AppServerHost({ createTransport, logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' }, onRetired });
    await host.ensureStarted();
    await expect(host.shutdown('failed', { throwOnTransportError: true })).rejects.toThrow('exit not confirmed');
    await expect(host.ensureStarted()).rejects.toThrow('exit not confirmed');
    expect(createTransport).toHaveBeenCalledOnce();
    close.mockResolvedValue(undefined);
    await host.ensureStarted();
    expect(createTransport).toHaveBeenCalledTimes(2);

    const nextTransport = createTransport.mock.results[1]!.value as NotificationTransport;
    const nextClose = vi.spyOn(nextTransport, 'close').mockRejectedValue(new Error('exit not confirmed'));
    await host.shutdown();
    let finish!: () => void;
    nextClose.mockImplementation(() => new Promise<void>((resolve) => { finish = resolve; }));
    const restart = expect(host.ensureStarted()).rejects.toThrow('after retirement');
    const retiring = host.retire('retire during recheck', { throwOnTransportError: true });
    await vi.waitFor(() => expect(nextClose).toHaveBeenCalledTimes(2));
    finish();
    await Promise.all([restart, retiring]);
    expect(createTransport).toHaveBeenCalledTimes(2);
    expect(onRetired).toHaveBeenCalledOnce();
  });

  it('blocks bootstrap retry until the failed process has exited', async () => {
    const failed = new RejectedInitializeTransport();
    let finish!: () => void;
    vi.spyOn(failed, 'close').mockImplementation(() => new Promise<void>((resolve) => { finish = resolve; }));
    const createTransport = vi.fn().mockReturnValueOnce(failed).mockReturnValue(new NotificationTransport());
    const host = new AppServerHost({ createTransport, logger, clientInfo: { name: 'cindy-test', version: '0.0.0' } });
    const failure = expect(host.ensureStarted()).rejects.toThrow('initialize boom');
    await vi.waitFor(() => expect(failed.close).toHaveBeenCalledOnce());
    await expect(host.ensureStarted()).rejects.toThrow('during shutdown');
    expect(createTransport).toHaveBeenCalledOnce();
    finish();
    await failure;
    await host.ensureStarted();
    expect(createTransport).toHaveBeenCalledTimes(2);
    await host.shutdown();
  });

  it('recovers when subscribing synchronously reports a closed startup transport', async () => {
    const failed = new NotificationTransport();
    let finish!: () => void;
    vi.spyOn(failed, 'onClose').mockImplementation((handler) => { handler({ reason: 'closed on subscribe' }); return () => {}; });
    vi.spyOn(failed, 'close').mockImplementation(() => new Promise<void>((resolve) => { finish = resolve; }));
    const createTransport = vi.fn().mockReturnValueOnce(failed).mockReturnValue(new NotificationTransport());
    const host = new AppServerHost({ createTransport, logger, clientInfo: { name: 'cindy-test', version: '0.0.0' } });
    const failure = expect(host.ensureStarted()).rejects.toThrow();
    await vi.waitFor(() => expect(failed.close).toHaveBeenCalledOnce());
    await expect(host.ensureStarted()).rejects.toThrow('during shutdown');
    finish();
    await failure;
    await host.ensureStarted();
    expect(createTransport).toHaveBeenCalledTimes(2);
    await host.shutdown();
  });
});

describe('AppServerHost MCP readiness', () => {
  it('releases Host-owned resources only on terminal retire and only once', async () => {
    const onRetired = vi.fn(async () => undefined);
    const host = new AppServerHost({
      createTransport: () => new NotificationTransport(),
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
      onRetired,
    });

    await host.shutdown('transport recovery');
    expect(onRetired).not.toHaveBeenCalled();
    await Promise.all([
      host.retire('task finished'),
      host.retire('duplicate cleanup'),
    ]);
    expect(onRetired).toHaveBeenCalledOnce();
  });

  it('retries a negative tool probe instead of permanently caching it', async () => {
    let available = false;
    const transport = new NotificationTransport((method) => (
      method === 'mcpServerStatus/list'
        ? {
            data: [{
              name: 'node_repl',
              tools: available ? { js: {} } : {},
              authStatus: 'notApplicable',
            }],
            nextCursor: null,
          }
        : {}
    ));
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
      codexBrowserUseStartupTimeoutMs: 10,
    });

    await expect(host.waitForMcpTool('node_repl', 'js')).resolves.toBe(false);
    available = true;
    await expect(host.waitForMcpTool('node_repl', 'js')).resolves.toBe(true);

    await host.shutdown();
  });

  it('re-probes MCP readiness after the app-server respawns', async () => {
    const firstTransport = new NotificationTransport((method) => (
      method === 'mcpServerStatus/list'
        ? {
            data: [{ name: 'node_repl', tools: { js: {} }, authStatus: 'notApplicable' }],
            nextCursor: null,
          }
        : {}
    ));
    const secondTransport = new NotificationTransport((method) => (
      method === 'mcpServerStatus/list'
        ? {
            data: [{ name: 'node_repl', tools: {}, authStatus: 'notApplicable' }],
            nextCursor: null,
          }
        : {}
    ));
    const transports = [firstTransport, secondTransport];
    const createTransport = vi.fn(() => transports.shift() ?? secondTransport);
    const host = new AppServerHost({
      createTransport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
      codexBrowserUseStartupTimeoutMs: 10,
    });

    await expect(host.waitForMcpTool('node_repl', 'js')).resolves.toBe(true);
    await host.shutdown();
    await expect(host.waitForMcpTool('node_repl', 'js')).resolves.toBe(false);

    expect(createTransport).toHaveBeenCalledTimes(2);
    await host.shutdown();
  });
});

const logger: Logger = {
  trace: vi.fn(),
  debug: vi.fn(),
  info: vi.fn(),
  warn: vi.fn(),
  error: vi.fn(),
  fatal: vi.fn(),
  child: () => logger,
};

describe('native SQLite initialization recovery', () => {
  class FailedNativeTransport extends NotificationTransport {
    failed = false;
    closeGate: Promise<void> = Promise.resolve();
    override async writeLine(line: string) {
      this.lines.push(line);
      this.failed = true;
      await super.close('native SQLite exited');
    }
    nativeSqliteInitializationFailed() { return this.failed; }
    override async close(reason?: string) { await this.closeGate; await super.close(reason); }
  }

  it('shares recovery, waits for close, and sends the task only to the replacement', async () => {
    const failed = new FailedNativeTransport();
    let release!: () => void;
    failed.closeGate = new Promise(resolve => { release = resolve; });
    const healthy = new NotificationTransport();
    const createTransport = vi.fn().mockReturnValueOnce(failed).mockReturnValue(healthy);
    const host = new AppServerHost({ createTransport, logger, clientInfo: { name: 'test', version: '0' } });
    try {
      const first = host.ensureStarted();
      expect(host.ensureStarted()).toBe(first);
      await vi.waitFor(() => expect(failed.failed).toBe(true));
      expect(createTransport).toHaveBeenCalledTimes(1);
      release();
      await first;
      await host.request('thread/start', {});
      expect(createTransport).toHaveBeenCalledTimes(2);
      expect(failed.lines.map(line => JSON.parse(line).method)).toEqual(['initialize']);
      expect(healthy.lines.map(line => JSON.parse(line).method)).toEqual(['initialize', 'thread/start']);
    } finally { release(); await host.retire(); }
  });

  it.each(['exhaust', 'shutdown', 'retire', 'timeout', 'close-failure'] as const)('stops recovery on %s', async mode => {
    let release!: () => void;
    const gate = new Promise<void>(resolve => { release = resolve; });
    const failed = new FailedNativeTransport();
    if (mode !== 'exhaust') failed.closeGate = gate;
    if (mode === 'close-failure') failed.close = vi.fn(async () => { await gate; throw new Error('exit unconfirmed'); });
    const createTransport = vi.fn(() => mode === 'exhaust' ? new FailedNativeTransport() : failed);
    const host = new AppServerHost({ createTransport, logger, clientInfo: { name: 'test', version: '0' } });
    const started = mode === 'timeout' ? host.ensureStartedWithTimeout(10, 'fixture') : host.ensureStarted();
    const rejection = expect(started).rejects.toThrow(mode === 'timeout' ? /timed out/ : mode === 'close-failure' ? /exit unconfirmed/ : /initialization stopped/);
    if (mode === 'exhaust') {
      await rejection;
      expect(createTransport).toHaveBeenCalledTimes(3);
    } else {
      await vi.waitFor(() => expect(failed.failed).toBe(true));
      const stopped = mode === 'shutdown' ? host.shutdown() : mode === 'retire' ? host.retire() : undefined;
      if (mode === 'timeout') await rejection;
      release();
      await rejection;
      await stopped;
      await new Promise(resolve => setTimeout(resolve, 0));
      expect(createTransport).toHaveBeenCalledTimes(1);
    }
    await host.retire();
  });

  it('does not retry an initialize RPC rejection', async () => {
    const createTransport = vi.fn(() => new RejectedInitializeTransport());
    const host = new AppServerHost({ createTransport, logger, clientInfo: { name: 'test', version: '0' } });
    await expect(host.ensureStarted()).rejects.not.toBeInstanceOf(CodexNativeInitializationStoppedError);
    expect(createTransport).toHaveBeenCalledTimes(1);
    await host.retire();
  });

  it('does not retry credential installation after native initialization', async () => {
    const transport = new NotificationTransport(() => ({ config: { cli_auth_credentials_store: 'ephemeral' } }));
    const createTransport = vi.fn(() => transport);
    const host = new AppServerHost({ createTransport, logger, clientInfo: { name: 'test', version: '0' },
      externalAuth: { readTokens: async () => { throw new Error('synthetic official account rejected'); } },
    });
    await expect(host.request('thread/start', {})).rejects.toThrow('Codex account authentication is unavailable or has changed');
    expect(createTransport).toHaveBeenCalledTimes(1);
    expect(transport.lines.map(line => JSON.parse(line).method)).not.toContain('thread/start');
    await host.retire();
  });

  it('never replays a task RPC failure after initialize', async () => {
    const transport = new NotificationTransport(method => {
      if (method === 'thread/start') throw new Error('synthetic task write failed');
      return {};
    });
    const createTransport = vi.fn(() => transport);
    const host = new AppServerHost({ createTransport, logger, clientInfo: { name: 'test', version: '0' } });
    await expect(host.request('thread/start', {})).rejects.toThrow();
    expect(createTransport).toHaveBeenCalledTimes(1);
    expect(transport.lines.filter(line => JSON.parse(line).method === 'thread/start')).toHaveLength(1);
    await host.retire();
  });
});

describe('AppServerHost.request startup timeout', () => {
  it.each([undefined, 1000])('checks dispatch after the final startup await (timeout=%s)', async (timeoutMs) => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({ createTransport: () => transport, logger, clientInfo: { name: 'test', version: '0' } });
    try {
      await host.ensureStarted();
      let release!: () => void;
      const gate = new Promise<void>((resolve) => { release = resolve; });
      const ensure = host.ensureStarted.bind(host);
      vi.spyOn(host, 'ensureStarted').mockImplementationOnce(async () => { await gate; return ensure(); });
      let valid = true;
      const beforeDispatch = vi.fn(() => { if (!valid) throw new Error('route expired'); });
      const pending = host.request('thread/start', {}, { timeoutMs, beforeDispatch });
      expect(beforeDispatch).not.toHaveBeenCalled();
      valid = false;
      release();
      await expect(pending).rejects.toThrow('route expired');
      expect(transport.lines.some((line) => JSON.parse(line).method === 'thread/start')).toBe(false);
      valid = true;
      await host.request('thread/start', {}, { timeoutMs, beforeDispatch });
      expect(transport.lines.filter((line) => JSON.parse(line).method === 'thread/start')).toHaveLength(1);
    } finally { await host.shutdown(); }
  });

  it('bounds a hung ensureStarted by the caller-provided timeoutMs (greptile R6 P1)', async () => {
    // 冷启动 / transport 重建时 ensureStarted 本身也可能永不返回 — 调用方显式
    // 给的 timeoutMs 必须同样覆盖启动路径, 否则「关键 RPC 加超时」形同虚设。
    const host = new AppServerHost({
      createTransport: () => new HangingTransport(),
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });

    await expect(host.request('turn/start', {}, { timeoutMs: 50 })).rejects.toThrow(
      'app-server startup (for turn/start) timed out after 50ms',
    );

    await host.shutdown();
  });

  it('keeps the in-flight bootstrap reusable for a later request after a startup timeout', async () => {
    // 超时只截断本次等待 — bootstrap 仍在后台继续 (startPromise 保留),
    // 后续 request 直接复用, 不重新 spawn。
    const createTransport = vi.fn(() => new DelayedTransport(60));
    const host = new AppServerHost({
      createTransport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });

    await expect(host.request('turn/start', {}, { timeoutMs: 20 })).rejects.toThrow(
      /app-server startup.*timed out/,
    );

    // 后台 bootstrap (60ms) 完成后, 同一个 startPromise 直接可用。
    await expect(host.request('turn/start', {}, { timeoutMs: 1_000 })).resolves.toMatchObject({
      userAgent: 'mock-codex/test',
    });
    expect(createTransport).toHaveBeenCalledTimes(1);

    await host.shutdown();
  });

  it('treats timeoutMs as an overall deadline across startup + request (copilot R9)', async () => {
    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
    // timeoutMs 不是「startup 一次 + request 再一次」的双重施加: startup 用掉
    // 的预算要从 request 里扣, 最坏等待仍是 1× timeoutMs — 否则 60s 关键 RPC
    // 在冷启动路径上最坏拖到 ~120s, UI 长时间卡 generating。
    // fake clock 下 DelayedTransport(40): startup 精确用掉 40ms,
    // 50ms overall deadline 只剩 10ms 给 request; 若误变成 2× 语义则要到 90ms。
    const host = new AppServerHost({
      createTransport: () => new DelayedTransport(40),
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });

    try {
      const request = host.request('turn/start', {}, { timeoutMs: 50 });
      const settled = vi.fn();
      void request.then(settled, settled);
      const rejection = expect(request).rejects.toThrow(
        'codex app-server turn/start timed out after 10ms',
      );

      await vi.advanceTimersByTimeAsync(49);
      expect(settled).not.toHaveBeenCalled();

      await vi.advanceTimersByTimeAsync(1);
      await rejection;
      expect(settled).toHaveBeenCalledTimes(1);
    } finally {
      await host.shutdown();
      vi.useRealTimers();
    }
  });
});

describe('AppServerHost.ensureStartedWithTimeout', () => {
  it('closes the failed transport when initialize rejects', async () => {
    const transport = new RejectedInitializeTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });

    await expect(host.ensureStarted()).rejects.toThrow('initialize boom');

    expect(transport.closed).toBe(true);
    await host.shutdown();
  });

  it('rejects when startup hangs past the budget and keeps the shared bootstrap reusable (codex R13 P1)', async () => {
    // startSession 的 initialize 直调与 request() 的 startup deadline 同款语义:
    // 超时只截断本次等待, startPromise 后台继续, 后续调用直接复用不重新 spawn。
    const createTransport = vi.fn(() => new DelayedTransport(60));
    const host = new AppServerHost({
      createTransport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });

    await expect(host.ensureStartedWithTimeout(20, 'startSession initialize')).rejects.toThrow(
      'app-server startup (for startSession initialize) timed out after 20ms',
    );

    // 后台 bootstrap (60ms) 完成后, 同一个 startPromise 直接可用。
    await expect(host.ensureStartedWithTimeout(1_000, 'startSession initialize')).resolves.toMatchObject({
      userAgent: 'mock-codex/test',
    });
    expect(createTransport).toHaveBeenCalledTimes(1);

    await host.shutdown();
  });
});

describe('AppServerHost descendant thread routing', () => {
  it('routes child and grandchild thread/started events to the root subscription', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const descendantThreadStarted = vi.fn();
    const subscription = host.subscribeThread('root-thread', {
      descendantThreadStarted,
    });

    transport.emit({
      method: 'thread/started',
      params: {
        thread: {
          id: 'child-thread',
          parentThreadId: 'root-thread',
        },
      },
    });
    transport.emit({
      method: 'thread/started',
      params: {
        thread: {
          id: 'grandchild-thread',
          parentThreadId: 'child-thread',
        },
      },
    });

    expect(descendantThreadStarted).toHaveBeenNthCalledWith(1, {
      thread: {
        id: 'child-thread',
        parentThreadId: 'root-thread',
      },
    });
    expect(descendantThreadStarted).toHaveBeenNthCalledWith(2, {
      thread: {
        id: 'grandchild-thread',
        parentThreadId: 'child-thread',
      },
    });

    await subscription.release();
    transport.emit({
      method: 'thread/started',
      params: {
        thread: {
          id: 'great-grandchild-thread',
          parentThreadId: 'grandchild-thread',
        },
      },
    });
    expect(descendantThreadStarted).toHaveBeenCalledTimes(2);

    await host.shutdown();
  });

  it('rebuilds buffered descendant lineage when the root subscribes after child starts', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    // Cross-thread notifications can arrive out of lineage order. Both starts are
    // buffered under their own child ids because the root has not subscribed yet.
    transport.emit({
      method: 'thread/started',
      params: {
        thread: {
          id: 'grandchild-thread',
          parentThreadId: 'child-thread',
        },
      },
    });
    transport.emit({
      method: 'thread/started',
      params: {
        thread: {
          id: 'child-thread',
          parentThreadId: 'root-thread',
        },
      },
    });

    const descendantThreadStarted = vi.fn();
    const subscription = host.subscribeThread('root-thread', {
      descendantThreadStarted,
    });

    expect(descendantThreadStarted).toHaveBeenCalledTimes(2);
    expect(descendantThreadStarted).toHaveBeenCalledWith({
      thread: {
        id: 'child-thread',
        parentThreadId: 'root-thread',
      },
    });
    expect(descendantThreadStarted).toHaveBeenCalledWith({
      thread: {
        id: 'grandchild-thread',
        parentThreadId: 'child-thread',
      },
    });

    await subscription.release();
    await host.shutdown();
  });

  it('registerDescendantLineage routes child notifications without any thread/started (codex 0.145)', async () => {
    // 0.145 只对显式 thread/start / fork RPC 发 thread/started;spawn 出的子线程
    // 只有 item / turn / tokenUsage 通知。血缘必须能由 Cindy 侧(从 spawn item)
    // 主动登记,否则这些通知全部在 TTL 缓冲里过期,子代理卡永久转圈。
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const descendantNotification = vi.fn();
    const descendantThreadStarted = vi.fn();
    const subscription = host.subscribeThread('root-thread', {
      descendantNotification,
      descendantThreadStarted,
    });

    // 早到:子线程通知先于 spawn item 被处理,落进 TTL 缓冲。
    transport.emit({
      method: 'turn/started',
      params: { threadId: 'child-thread', turn: { id: 'turn-1' } },
    });

    host.registerDescendantLineage('child-thread', 'root-thread');

    // 缓冲的早到通知按序补投,后续通知实时路由;全程没有任何 thread/started。
    transport.emit({
      method: 'turn/completed',
      params: { threadId: 'child-thread', turn: { id: 'turn-1', status: 'completed' } },
    });
    expect(descendantNotification).toHaveBeenNthCalledWith(
      1,
      'child-thread',
      'turn/started',
      { threadId: 'child-thread', turn: { id: 'turn-1' } },
    );
    expect(descendantNotification).toHaveBeenNthCalledWith(
      2,
      'child-thread',
      'turn/completed',
      { threadId: 'child-thread', turn: { id: 'turn-1', status: 'completed' } },
    );

    // 血缘重复:新版 codex 补发同一条边的 thread/started 不重复建边、不重放缓冲,
    // 但通知本身仍要转发——它携带的 thread.model 是实际模型的唯一观测入口(codex review)。
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'child-thread', parentThreadId: 'root-thread', model: 'gpt-5.6-terra' } },
    });
    expect(descendantThreadStarted).toHaveBeenCalledTimes(1);
    expect(descendantThreadStarted).toHaveBeenCalledWith({
      thread: { id: 'child-thread', parentThreadId: 'root-thread', model: 'gpt-5.6-terra' },
    });
    expect(descendantNotification).toHaveBeenCalledTimes(2);

    await subscription.release();
    await host.shutdown();
  });

  it('replays a buffered child thread/started before draining ordinary notifications', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    // Root subscription is late. The child metadata and lifecycle arrive first,
    // then the root spawn item is buffered under the root id.
    transport.emit({
      method: 'thread/started',
      params: {
        thread: {
          id: 'child-thread',
          parentThreadId: 'root-thread',
          model: 'codex/gpt-5.6-sol',
        },
      },
    });
    transport.emit({
      method: 'turn/started',
      params: { threadId: 'child-thread', turn: { id: 'child-turn' } },
    });
    transport.emit({
      method: 'item/started',
      params: {
        threadId: 'root-thread',
        turnId: 'root-turn',
        item: { id: 'spawn-1', type: 'subAgentActivity', agentThreadId: 'child-thread' },
      },
    });

    const observed: string[] = [];
    const subscription = host.subscribeThread('root-thread', {
      itemStarted: () => {
        observed.push('spawn');
        host.registerDescendantLineage('child-thread', 'root-thread');
      },
      descendantThreadStarted: (params) => {
        observed.push(`model:${params.thread.model ?? ''}`);
      },
      descendantNotification: (_threadId, method) => {
        observed.push(method);
      },
    });

    expect(observed).toEqual([
      'spawn',
      'model:codex/gpt-5.6-sol',
      'turn/started',
    ]);

    await subscription.release();
    await host.shutdown();
  });

  it('registerDescendantLineage unlocks a buffered grandchild thread/started chain', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const descendantThreadStarted = vi.fn();
    const subscription = host.subscribeThread('root-thread', {
      descendantThreadStarted,
    });

    // 孙线程的 thread/started(新版 codex 才会发)先到,此时子线程尚无血缘,缓冲。
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'grandchild-thread', parentThreadId: 'child-thread' } },
    });
    expect(descendantThreadStarted).not.toHaveBeenCalled();

    // 子线程血缘由 spawn item 路径登记 → 缓冲中的孙线程血缘应被递归重建。
    host.registerDescendantLineage('child-thread', 'root-thread');
    expect(descendantThreadStarted).toHaveBeenCalledWith({
      thread: { id: 'grandchild-thread', parentThreadId: 'child-thread' },
    });

    await subscription.release();
    await host.shutdown();
  });

  it('routes descendant server requests to the root subscription handlers', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const commandExecutionApproval = vi.fn(async () => ({ decision: 'accept' as const }));
    const fileChangeApproval = vi.fn(async () => ({ decision: 'accept' as const }));
    const mcpServerElicitation = vi.fn(async () => ({
      action: 'accept' as const,
      content: { value: 'ok' },
      _meta: null,
    }));
    const permissionsApproval = vi.fn(async () => ({
      permissions: { network: true },
      scope: 'turn' as const,
    }));
    const requestUserInput = vi.fn(async (_params, meta) => ({
      answers: { q1: { answers: [`request:${String(meta.requestId)}`] } },
    }));
    const dynamicToolCall = vi.fn(async (_params, meta) => ({
      contentItems: [{ type: 'inputText' as const, text: `request:${String(meta.requestId)}` }],
      success: true,
    }));
    const subscription = host.subscribeThread('root-thread', {
      commandExecutionApproval,
      fileChangeApproval,
      mcpServerElicitation,
      permissionsApproval,
      requestUserInput,
      dynamicToolCall,
    });

    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'child-thread', parentThreadId: 'root-thread' } },
    });

    const requests = [
      {
        id: 'server-command',
        method: 'item/commandExecution/requestApproval',
        params: { threadId: 'child-thread', turnId: 'turn-1', itemId: 'item-1' },
        expected: { decision: 'accept' },
      },
      {
        id: 'server-file',
        method: 'item/fileChange/requestApproval',
        params: { threadId: 'child-thread', turnId: 'turn-1', itemId: 'item-2' },
        expected: { decision: 'accept' },
      },
      {
        id: 'server-elicitation',
        method: 'mcpServer/elicitation/request',
        params: {
          threadId: 'child-thread',
          turnId: 'turn-1',
          serverName: 'test-mcp',
          mode: 'form',
          _meta: null,
          message: 'Confirm',
          requestedSchema: {},
        },
        expected: { action: 'accept', content: { value: 'ok' }, _meta: null },
      },
      {
        id: 'server-permissions',
        method: 'item/permissions/requestApproval',
        params: {
          threadId: 'child-thread',
          turnId: 'turn-1',
          itemId: 'item-3',
          permissions: { network: true },
        },
        expected: { permissions: { network: true }, scope: 'turn' },
      },
      {
        id: 'server-input',
        method: 'item/tool/requestUserInput',
        params: {
          threadId: 'child-thread',
          turnId: 'turn-1',
          itemId: 'item-4',
          questions: [],
        },
        expected: { answers: { q1: { answers: ['request:server-input'] } } },
      },
      {
        id: 'server-tool',
        method: 'item/tool/call',
        params: {
          threadId: 'child-thread',
          turnId: 'turn-1',
          callId: 'call-1',
          namespace: null,
          tool: 'test_tool',
          arguments: {},
        },
        expected: {
          contentItems: [{ type: 'inputText', text: 'request:server-tool' }],
          success: true,
        },
      },
    ] as const;

    const initialLineCount = transport.lines.length;
    for (const request of requests) {
      transport.emit(request);
    }

    await vi.waitFor(() => {
      expect(transport.lines.length).toBe(initialLineCount + requests.length);
    });
    const responses = transport.lines
      .slice(initialLineCount)
      .map((line) => JSON.parse(line) as { id: string; result: unknown });
    expect(responses).toEqual(
      requests.map((request) => ({ id: request.id, result: request.expected })),
    );
    expect(commandExecutionApproval).toHaveBeenCalledWith(
      expect.objectContaining({ threadId: 'child-thread' }),
    );
    expect(fileChangeApproval).toHaveBeenCalledWith(
      expect.objectContaining({ threadId: 'child-thread' }),
    );
    expect(mcpServerElicitation).toHaveBeenCalledWith(
      expect.objectContaining({ threadId: 'child-thread' }),
    );
    expect(permissionsApproval).toHaveBeenCalledWith(
      expect.objectContaining({ threadId: 'child-thread' }),
    );
    expect(requestUserInput).toHaveBeenCalledWith(
      expect.objectContaining({ threadId: 'child-thread' }),
      { requestId: 'server-input' },
    );
    expect(dynamicToolCall).toHaveBeenCalledWith(
      expect.objectContaining({ threadId: 'child-thread' }),
      { requestId: 'server-tool' },
    );

    await subscription.release();
    await host.shutdown();
  });

  it('briefly waits for descendant lineage before declining an MCP elicitation', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const mcpServerElicitation = vi.fn(async () => ({
      action: 'accept' as const,
      content: { value: 'ok' },
      _meta: null,
    }));
    const subscription = host.subscribeThread('root-thread', { mcpServerElicitation });
    const initialLineCount = transport.lines.length;

    // The request is dispatched asynchronously. Emit the lineage notification
    // immediately afterwards to reproduce the observed cross-message race.
    transport.emit({
      id: 'early-elicitation',
      method: 'mcpServer/elicitation/request',
      params: {
        threadId: 'child-thread',
        turnId: 'turn-1',
        serverName: 'node_repl',
        mode: 'form',
        _meta: null,
        message: 'Confirm',
        requestedSchema: {},
      },
    });
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'child-thread', parentThreadId: 'root-thread' } },
    });

    await vi.waitFor(() => {
      expect(transport.lines.length).toBe(initialLineCount + 1);
    });
    expect(JSON.parse(transport.lines.at(-1)!)).toEqual({
      id: 'early-elicitation',
      result: { action: 'accept', content: { value: 'ok' }, _meta: null },
    });
    expect(mcpServerElicitation).toHaveBeenCalledWith(
      expect.objectContaining({ threadId: 'child-thread', serverName: 'node_repl' }),
    );

    await subscription.release();
    await host.shutdown();
  });

  it('keeps known descendant request dispatch synchronous before a resolved notification', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const order: string[] = [];
    const subscription = host.subscribeThread('root-thread', {
      requestUserInput: vi.fn(async () => {
        order.push('request');
        return { answers: {} };
      }),
      serverRequestResolved: vi.fn(() => {
        order.push('resolved');
      }),
    });
    transport.emit({
      id: 'known-request',
      method: 'item/tool/requestUserInput',
      params: {
        threadId: 'root-thread',
        turnId: 'root-turn',
        itemId: 'input',
        questions: [{ id: 'q1', header: 'Q', question: 'Continue?', options: [] }],
      },
    });
    transport.emit({
      method: 'serverRequest/resolved',
      params: { threadId: 'root-thread', requestId: 'known-request' },
    });

    await vi.waitFor(() => {
      expect(order).toEqual(['request', 'resolved']);
    });

    await subscription.release();
    await host.shutdown();
  });

  it('registers provisional descendant request brokers before replaying resolved notifications', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const order: string[] = [];
    const subscription = host.subscribeThread('root-thread', {
      requestUserInput: vi.fn(async (_params, meta) => {
        order.push(`request:${String(meta.requestId)}`);
        return { answers: {} };
      }),
      dynamicToolCall: vi.fn(async (_params, meta) => {
        order.push(`request:${String(meta.requestId)}`);
        return { contentItems: [], success: false };
      }),
      descendantNotification: (_threadId, method, params) => {
        if (method !== 'serverRequest/resolved') return;
        order.push(`resolved:${String((params as { requestId: string }).requestId)}`);
      },
    });

    host.reserveDescendantLineage('child-thread', 'root-thread');
    transport.emit({
      id: 'pending-input',
      method: 'item/tool/requestUserInput',
      params: {
        threadId: 'child-thread',
        turnId: 'child-turn',
        itemId: 'input',
        questions: [{ id: 'q1', header: 'Q', question: 'Continue?', options: [] }],
      },
    });
    transport.emit({
      id: 'pending-tool',
      method: 'item/tool/call',
      params: {
        threadId: 'child-thread',
        turnId: 'child-turn',
        callId: 'tool',
        namespace: null,
        tool: 'ask_user',
        arguments: {},
      },
    });
    transport.emit({
      method: 'serverRequest/resolved',
      params: { threadId: 'child-thread', requestId: 'pending-input' },
    });
    transport.emit({
      method: 'serverRequest/resolved',
      params: { threadId: 'child-thread', requestId: 'pending-tool' },
    });

    host.registerDescendantLineage('child-thread', 'root-thread');

    await vi.waitFor(() => {
      expect(order).toEqual([
        'request:pending-input',
        'request:pending-tool',
        'resolved:pending-input',
        'resolved:pending-tool',
      ]);
    });

    await subscription.release();
    await host.shutdown();
  });

  it('declines an MCP elicitation whose lineage stays unknown for the bounded window', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
      notificationBufferTtlMs: 20,
    });
    await host.ensureStarted();

    const mcpServerElicitation = vi.fn();
    const subscription = host.subscribeThread('root-thread', { mcpServerElicitation });
    const initialLineCount = transport.lines.length;
    transport.emit({
      id: 'unknown-elicitation',
      method: 'mcpServer/elicitation/request',
      params: {
        threadId: 'unknown-thread',
        turnId: 'turn-1',
        serverName: 'node_repl',
        mode: 'form',
        _meta: null,
        message: 'Confirm',
        requestedSchema: {},
      },
    });

    await vi.waitFor(() => {
      expect(transport.lines.length).toBe(initialLineCount + 1);
    });
    expect(JSON.parse(transport.lines.at(-1)!)).toEqual({
      id: 'unknown-elicitation',
      result: { action: 'decline', content: null, _meta: null },
    });
    expect(mcpServerElicitation).not.toHaveBeenCalled();

    await subscription.release();
    await host.shutdown();
  });

  it('holds all descendant server requests behind a pending spawn claim until commit', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
      notificationBufferTtlMs: 20,
    });
    await host.ensureStarted();

    const subscription = host.subscribeThread('root-thread', {
      commandExecutionApproval: vi.fn(async () => ({ decision: 'accept' as const })),
      fileChangeApproval: vi.fn(async () => ({ decision: 'accept' as const })),
      permissionsApproval: vi.fn(async () => ({ permissions: { network: true }, scope: 'turn' as const })),
      requestUserInput: vi.fn(async () => ({ answers: { q1: { answers: ['ok'] } } })),
      dynamicToolCall: vi.fn(async () => ({
        contentItems: [{ type: 'inputText' as const, text: 'ok' }],
        success: true,
      })),
      mcpServerElicitation: vi.fn(async () => ({
        action: 'accept' as const,
        content: { value: 'ok' },
        _meta: null,
      })),
    });

    const requests = [
      { id: 'pending-command', method: 'item/commandExecution/requestApproval', params: { threadId: 'child-thread', turnId: 'child-turn', itemId: 'command' } },
      { id: 'pending-file', method: 'item/fileChange/requestApproval', params: { threadId: 'child-thread', turnId: 'child-turn', itemId: 'file' } },
      { id: 'pending-permissions', method: 'item/permissions/requestApproval', params: { threadId: 'child-thread', turnId: 'child-turn', itemId: 'permissions', permissions: { network: true } } },
      { id: 'pending-input', method: 'item/tool/requestUserInput', params: { threadId: 'child-thread', turnId: 'child-turn', itemId: 'input', questions: [] } },
      { id: 'pending-tool', method: 'item/tool/call', params: { threadId: 'child-thread', turnId: 'child-turn', callId: 'tool', namespace: null, tool: 'test', arguments: {} } },
      { id: 'pending-elicitation', method: 'mcpServer/elicitation/request', params: { threadId: 'child-thread', turnId: 'child-turn', serverName: 'test-mcp', mode: 'form', _meta: null, message: 'Confirm', requestedSchema: {} } },
    ] as const;
    const initialLineCount = transport.lines.length;
    for (const request of requests) transport.emit(request);

    // The parent spawn is known, but not yet accepted by turn reconciliation.
    host.reserveDescendantLineage('child-thread', 'root-thread');
    await Promise.resolve();
    expect(transport.lines).toHaveLength(initialLineCount);

    host.registerDescendantLineage('child-thread', 'root-thread');
    await vi.waitFor(() => {
      expect(transport.lines).toHaveLength(initialLineCount + requests.length);
    });

    const responses = transport.lines
      .slice(initialLineCount)
      .map((line) => JSON.parse(line) as { id: string; result: unknown });
    expect(responses.map((response) => response.id)).toEqual(requests.map((request) => request.id));

    await subscription.release();
    await host.shutdown();
  });

  it('keeps pending child buffers alive until commit and drops them on discard', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
      notificationBufferTtlMs: 10,
    });
    await host.ensureStarted();

    const descendantThreadStarted = vi.fn();
    const descendantNotification = vi.fn();
    const subscription = host.subscribeThread('root-thread', {
      descendantThreadStarted,
      descendantNotification,
    });

    host.reserveDescendantLineage('child-thread', 'root-thread');
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'child-thread', parentThreadId: 'root-thread', model: 'gpt-5.6-terra' } },
    });
    transport.emit({
      method: 'turn/completed',
      params: { threadId: 'child-thread', turn: { id: 'child-turn', status: 'completed' } },
    });
    await new Promise((resolve) => setTimeout(resolve, 30));
    expect(descendantThreadStarted).not.toHaveBeenCalled();
    expect(descendantNotification).not.toHaveBeenCalled();

    host.registerDescendantLineage('child-thread', 'root-thread');
    expect(descendantThreadStarted).toHaveBeenCalledWith({
      thread: { id: 'child-thread', parentThreadId: 'root-thread', model: 'gpt-5.6-terra' },
    });
    expect(descendantNotification).toHaveBeenCalledWith(
      'child-thread',
      'turn/completed',
      { threadId: 'child-thread', turn: { id: 'child-turn', status: 'completed' } },
    );

    host.reserveDescendantLineage('orphan-child', 'root-thread');
    transport.emit({
      method: 'turn/completed',
      params: { threadId: 'orphan-child', turn: { id: 'orphan-turn', status: 'completed' } },
    });
    host.discardPendingDescendantLineage('orphan-child', 'root-thread');
    transport.emit({
      method: 'turn/completed',
      params: { threadId: 'orphan-child', turn: { id: 'late-turn', status: 'completed' } },
    });
    expect(descendantNotification).not.toHaveBeenCalledWith(
      'orphan-child',
      expect.anything(),
      expect.anything(),
    );

    await subscription.release();
    await host.shutdown();
  });
});

describe('AppServerHost descendant notification routing', () => {
  it('routes descendant item/tokenUsage/turn notifications to the root descendant channel only', async () => {
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const descendantNotification = vi.fn();
    const itemStarted = vi.fn();
    const tokenUsageUpdated = vi.fn();
    const turnCompleted = vi.fn();
    const turnDiffUpdated = vi.fn();
    const subscription = host.subscribeThread('root-thread', {
      descendantNotification,
      itemStarted,
      tokenUsageUpdated,
      turnCompleted,
      turnDiffUpdated,
    });

    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'child-thread', parentThreadId: 'root-thread' } },
    });
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'grandchild-thread', parentThreadId: 'child-thread' } },
    });

    const childItem = {
      method: 'item/started',
      params: { threadId: 'child-thread', turnId: 'turn-c1', item: { id: 'i-1', type: 'commandExecution' } },
    };
    const childUsage = {
      method: 'thread/tokenUsage/updated',
      params: { threadId: 'child-thread', turnId: 'turn-c1', tokenUsage: { total: { totalTokens: 42 } } },
    };
    const grandchildTurn = {
      method: 'turn/completed',
      params: { threadId: 'grandchild-thread', turn: { id: 'turn-g1', status: 'completed' } },
    };
    const childDiff = {
      method: 'turn/diff/updated',
      params: { threadId: 'child-thread', turnId: 'turn-c1', diff: 'diff --git a/a b/a' },
    };
    transport.emit(childItem);
    transport.emit(childUsage);
    transport.emit(grandchildTurn);
    transport.emit(childDiff);

    expect(descendantNotification.mock.calls).toEqual([
      ['child-thread', 'item/started', childItem.params],
      ['child-thread', 'thread/tokenUsage/updated', childUsage.params],
      ['grandchild-thread', 'turn/completed', grandchildTurn.params],
      ['child-thread', 'turn/diff/updated', childDiff.params],
    ]);
    // 关键隔离:子线程事件绝不能进主线程 handler —— 否则子代理的 exec 会被渲染成
    // 主会话自己的工具调用,并污染主 turn 的 usage 与状态机。
    expect(itemStarted).not.toHaveBeenCalled();
    expect(tokenUsageUpdated).not.toHaveBeenCalled();
    expect(turnCompleted).not.toHaveBeenCalled();
    expect(turnDiffUpdated).not.toHaveBeenCalled();

    // 主线程自己的同名事件照旧走主通道。
    transport.emit({
      method: 'item/started',
      params: { threadId: 'root-thread', turnId: 'turn-r1', item: { id: 'i-2', type: 'commandExecution' } },
    });
    const rootDiff = {
      method: 'turn/diff/updated',
      params: { threadId: 'root-thread', turnId: 'turn-r1', diff: 'diff --git a/b b/b' },
    };
    transport.emit(rootDiff);
    expect(itemStarted).toHaveBeenCalledTimes(1);
    expect(turnDiffUpdated).toHaveBeenCalledWith(rootDiff.params);
    expect(descendantNotification).toHaveBeenCalledTimes(4);

    await subscription.release();
    transport.emit(childItem);
    expect(descendantNotification).toHaveBeenCalledTimes(4);
    // thread/started 只走专用的 descendantThreadStarted,不重复出现在本通道。
    expect(descendantNotification.mock.calls.some(([, method]) => method === 'thread/started')).toBe(false);

    await host.shutdown();
  });

  it('keeps buffering notifications for threads with no known lineage', async () => {
    // 未知线程仍走 TTL 缓冲(解 subscribe 竞争);只有血缘已知的子线程才就地收口。
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    transport.emit({
      method: 'item/started',
      params: { threadId: 'late-thread', turnId: 'turn-1', item: { id: 'i-1', type: 'commandExecution' } },
    });

    const itemStarted = vi.fn();
    const descendantNotification = vi.fn();
    const subscription = host.subscribeThread('late-thread', { itemStarted, descendantNotification });
    expect(itemStarted).toHaveBeenCalledTimes(1);
    expect(descendantNotification).not.toHaveBeenCalled();

    await subscription.release();
    await host.shutdown();
  });
});
describe('AppServerHost buffered descendant notification replay', () => {
  it('replays a child thread\'s pre-subscribe item/usage/turn notifications in arrival order', async () => {
    // thread/started 与该 child 的 item / usage / turn 全部早于 root 的 subscribeThread 到达时,
    // 它们分别缓存在 **child id** 下。root 侧的 drain 只排空 root id 的队列,这些永远排不到 →
    // 早期工具数、token 丢失,漏掉 turn/completed 还会让卡片永久停在 running(codex review)。
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    // 订阅之前:child 与 grandchild 的血缘 + 各自的业务通知全部先到。
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'child-thread', parentThreadId: 'root-thread' } },
    });
    const childItem = {
      method: 'item/started',
      params: { threadId: 'child-thread', turnId: 't1', item: { id: 'i-1', type: 'commandExecution' } },
    };
    const childUsage = {
      method: 'thread/tokenUsage/updated',
      params: { threadId: 'child-thread', turnId: 't1', tokenUsage: { total: { totalTokens: 99 } } },
    };
    const childTurnEnd = {
      method: 'turn/completed',
      params: { threadId: 'child-thread', turn: { id: 't1', status: 'completed' } },
    };
    transport.emit(childItem);
    transport.emit(childUsage);
    transport.emit(childTurnEnd);
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'grandchild-thread', parentThreadId: 'child-thread' } },
    });
    transport.emit({
      method: 'item/started',
      params: { threadId: 'grandchild-thread', turnId: 't2', item: { id: 'i-2', type: 'mcpToolCall' } },
    });

    const descendantNotification = vi.fn();
    const descendantThreadStarted = vi.fn();
    const itemStarted = vi.fn();
    const subscription = host.subscribeThread('root-thread', {
      descendantNotification,
      descendantThreadStarted,
      itemStarted,
    });

    // 血缘照旧重建(child + grandchild)。
    expect(descendantThreadStarted).toHaveBeenCalledTimes(2);
    // 关键:child 的三条业务通知按到达顺序补投,grandchild 的也补投。
    expect(descendantNotification.mock.calls).toEqual([
      ['child-thread', 'item/started', childItem.params],
      ['child-thread', 'thread/tokenUsage/updated', childUsage.params],
      ['child-thread', 'turn/completed', childTurnEnd.params],
      [
        'grandchild-thread',
        'item/started',
        { threadId: 'grandchild-thread', turnId: 't2', item: { id: 'i-2', type: 'mcpToolCall' } },
      ],
    ]);
    // thread/started 不进本通道(有专用 handler),也不得重复投递业务通知到主线程通道。
    expect(descendantNotification.mock.calls.some(([, method]) => method === 'thread/started')).toBe(false);
    expect(itemStarted).not.toHaveBeenCalled();

    // 补投过一次后不再重复:同一批不会因后续血缘重建被投第二遍。
    descendantNotification.mockClear();
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'great-grandchild', parentThreadId: 'grandchild-thread' } },
    });
    expect(descendantNotification).not.toHaveBeenCalled();

    await subscription.release();
    await host.shutdown();
  });

  it('rescans buffered lineage when a live thread/started unlocks an already-buffered grandchild', async () => {
    // 与上一例的区别:root **已经订阅**,而孙线程的 thread/started 先于父线程到达。此时孙的
    // 血缘无从判断 → 连同它的业务通知一起缓存在孙自己的 id 下。父线程随后建立血缘时,原实现
    // 只排空父线程那一条队列(而且按契约跳过 thread/started),不再扫待解析的后代血缘 →
    // 孙线程的 tool / token / 终态通知一直烂在缓冲区,卡片漏计并可能持续显示运行中(review)。
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const descendantNotification = vi.fn();
    const descendantThreadStarted = vi.fn();
    const itemStarted = vi.fn();
    const subscription = host.subscribeThread('root-thread', {
      descendantNotification,
      descendantThreadStarted,
      itemStarted,
    });

    // 逆序:孙先到(父线程此刻还没有血缘),连它的业务通知一起被缓冲。
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'grandchild-thread', parentThreadId: 'child-thread' } },
    });
    const grandchildItem = {
      method: 'item/started',
      params: { threadId: 'grandchild-thread', turnId: 't2', item: { id: 'i-2', type: 'mcpToolCall' } },
    };
    const grandchildTurnEnd = {
      method: 'turn/completed',
      params: { threadId: 'grandchild-thread', turn: { id: 't2', status: 'completed' } },
    };
    transport.emit(grandchildItem);
    transport.emit(grandchildTurnEnd);
    expect(descendantThreadStarted).not.toHaveBeenCalled();
    expect(descendantNotification).not.toHaveBeenCalled();

    // 父线程血缘到达:必须顺带把孙线程解锁并补投它的缓冲通知。
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'child-thread', parentThreadId: 'root-thread' } },
    });

    expect(descendantThreadStarted).toHaveBeenCalledTimes(2);
    expect(descendantNotification.mock.calls).toEqual([
      ['grandchild-thread', 'item/started', grandchildItem.params],
      ['grandchild-thread', 'turn/completed', grandchildTurnEnd.params],
    ]);
    // 后代通知不得漏进主线程通道(否则子代理的工具会被渲染成主会话自己的调用)。
    expect(itemStarted).not.toHaveBeenCalled();

    // 孙线程血缘已建立:它之后的通知直接走 descendant 通道,不再进缓冲。
    descendantNotification.mockClear();
    transport.emit({
      method: 'item/started',
      params: { threadId: 'grandchild-thread', turnId: 't3', item: { id: 'i-3', type: 'webSearch' } },
    });
    expect(descendantNotification).toHaveBeenCalledTimes(1);

    await subscription.release();
    await host.shutdown();
  });

  it('resolves a deep buffered lineage chain from a single live thread/started', async () => {
    // 三代逆序:曾孙 → 孙 全部先到,最后才到子线程对 root 的血缘。一次重建要沿链解开。
    const transport = new NotificationTransport();
    const host = new AppServerHost({
      createTransport: () => transport,
      logger,
      clientInfo: { name: 'cindy-test', version: '0.0.0' },
    });
    await host.ensureStarted();

    const descendantNotification = vi.fn();
    const descendantThreadStarted = vi.fn();
    const subscription = host.subscribeThread('root-thread', {
      descendantNotification,
      descendantThreadStarted,
    });

    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'great-grandchild', parentThreadId: 'grandchild-thread' } },
    });
    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'grandchild-thread', parentThreadId: 'child-thread' } },
    });
    transport.emit({
      method: 'item/started',
      params: { threadId: 'great-grandchild', turnId: 't9', item: { id: 'i-9', type: 'commandExecution' } },
    });
    expect(descendantThreadStarted).not.toHaveBeenCalled();

    transport.emit({
      method: 'thread/started',
      params: { thread: { id: 'child-thread', parentThreadId: 'root-thread' } },
    });

    // child + grandchild + great-grandchild 三代血缘全部建立,曾孙的工具通知补投到位。
    expect(descendantThreadStarted).toHaveBeenCalledTimes(3);
    expect(descendantNotification.mock.calls).toEqual([
      [
        'great-grandchild',
        'item/started',
        { threadId: 'great-grandchild', turnId: 't9', item: { id: 'i-9', type: 'commandExecution' } },
      ],
    ]);

    await subscription.release();
    await host.shutdown();
  });
});