Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

108 KB
Raw Blame
import { homedir } from 'node:os';

import {
  OK_DESKTOP_TERMINAL_ENV,
  OK_HOSTED_AGENT_ENV,
  posixOkManagedBinDir,
  shellSingleQuote,
} from '@inkeep/open-knowledge-core';
import { TERMINAL_SHELL_NOTICE_REASONS } from '@inkeep/open-knowledge-core/desktop-bridge';
import { describe, expect, test, vi } from 'vitest';

vi.mock('node:os', async (importOriginal) => {
  const actual = await importOriginal<typeof import('node:os')>();
  return { ...actual, homedir: vi.fn(actual.homedir) };
});

import { isTerminalPlatform } from '../../src/shared/terminal-platform.ts';
import {
  buildLaunchEnv,
  buildShellArgs,
  buildShellEnv,
  type HostReapProcess,
  installHostReaping,
  installPtyImportFailureReply,
  type PtyCreateMessage,
  type PtyHostHandle,
  type PtyHostIncomingMessage,
  type PtyHostOutgoingMessage,
  type PtyProcessLike,
  type PtySpawnOptions,
  resolveShell,
  type SpawnPty,
  setupPtyHost,
} from '../../src/utility/pty-host.ts';
import {
  type ConptyCursorSyncHost,
  CURSOR_POSITION_QUERY,
  createConptyCursorSyncHost,
} from '../support/conpty-cursor-sync-host.test-helper.ts';

interface FakePty extends PtyProcessLike {
  writes: string[];
  resizes: Array<[number, number]>;
  killCount: number;
  killSignals: Array<string | undefined>;
  killThrows: boolean;
  pauseCount: number;
  resumeCount: number;
  emitData(data: string): void;
  emitExit(event: { exitCode: number | undefined; signal?: number }): void;
}

function makeFakePty(): FakePty {
  let onData: ((data: string) => void) | null = null;
  let onExit: ((event: { exitCode: number | undefined; signal?: number }) => void) | null = null;
  return {
    pid: 4242,
    writes: [],
    resizes: [],
    killCount: 0,
    killThrows: false,
    pauseCount: 0,
    resumeCount: 0,
    onData(listener) {
      onData = listener;
    },
    onExit(listener) {
      onExit = listener;
    },
    write(data) {
      this.writes.push(data);
    },
    resize(cols, rows) {
      this.resizes.push([cols, rows]);
    },
    killSignals: [] as Array<string | undefined>,
    kill(signal?: string) {
      this.killCount += 1;
      this.killSignals.push(signal);
      if (this.killThrows) throw Object.assign(new Error('kill ESRCH'), { code: 'ESRCH' });
    },
    pause() {
      this.pauseCount += 1;
    },
    resume() {
      this.resumeCount += 1;
    },
    emitData(data) {
      onData?.(data);
    },
    emitExit(event) {
      onExit?.(event);
    },
  };
}

interface Harness {
  fire(message: PtyHostIncomingMessage): void;
  fireRaw(data: unknown): void;
  posted: PtyHostOutgoingMessage[];
  spawnCalls: Array<{ file: string; args: string[] | string; options: PtySpawnOptions }>;
  materializedSupportFiles: Array<{
    cwd: string;
    file: NonNullable<import('@inkeep/open-knowledge-core').TerminalLaunchCommand['supportFile']>;
  }>;
  handle: ReturnType<typeof setupPtyHost>;
}

function makeHarness(opts?: {
  pty?: FakePty;
  spawn?: SpawnPty;
  env?: Record<string, string | undefined>;
  platform?: NodeJS.Platform;
  userInfoShell?: () => string | null;
  shellExists?: (path: string) => boolean;
  pathProbe?: (command: string, env: Record<string, string | undefined>) => string | null;
  listDirectory?: (path: string) => readonly string[];
  cliBinDir?: string;
  logger?: {
    warn: (o: Record<string, unknown>) => void;
    info?: (o: Record<string, unknown>) => void;
  };
  exitHost?: (code: number) => void;
  flushLogger?: () => void;
  shutdownMs?: number;
  materializeSupportFile?: (
    cwd: string,
    file: NonNullable<import('@inkeep/open-knowledge-core').TerminalLaunchCommand['supportFile']>,
  ) => void;
}): Harness {
  let handler: ((event: { data: unknown }) => void) | null = null;
  const posted: PtyHostOutgoingMessage[] = [];
  const spawnCalls: Array<{ file: string; args: string[] | string; options: PtySpawnOptions }> = [];
  const materializedSupportFiles: Harness['materializedSupportFiles'] = [];
  const pty = opts?.pty ?? makeFakePty();
  const spawn: SpawnPty =
    opts?.spawn ??
    ((file, args, options) => {
      spawnCalls.push({ file, args, options });
      return pty;
    });
  const handle = setupPtyHost({
    parentPort: {
      on(_event, h) {
        handler = h;
      },
      postMessage(value) {
        posted.push(value);
      },
    },
    spawn,
    exitHost: opts?.exitHost,
    flushLogger: opts?.flushLogger,
    shutdownMs: opts?.shutdownMs,
    env: opts?.env ?? { SHELL: '/bin/zsh', PATH: '/usr/bin' },
    platform: opts?.platform ?? 'darwin',
    userInfoShell: opts?.userInfoShell,
    shellExists: opts?.shellExists,
    pathProbe: opts?.pathProbe,
    listDirectory: opts?.listDirectory,
    cliBinDir: opts?.cliBinDir,
    materializeSupportFile:
      opts?.materializeSupportFile ??
      ((cwd, file) => {
        materializedSupportFiles.push({ cwd, file });
      }),
    logger: opts?.logger,
  });
  return {
    fire: (message) => handler?.({ data: message }),
    fireRaw: (data) => handler?.({ data }),
    posted,
    spawnCalls,
    materializedSupportFiles,
    handle,
  };
}

const CREATE = (over?: Partial<PtyCreateMessage>): PtyCreateMessage => ({
  type: 'create',
  ptyId: 'p1',
  cwd: '/project/root',
  cols: 80,
  rows: 24,
  ...over,
});

describe('setupPtyHost — create', () => {
  test('spawns the login interactive shell at the project root', () => {
    const h = makeHarness({ env: { SHELL: '/bin/bash', PATH: '/usr/bin' } });
    h.fire(CREATE());
    expect(h.spawnCalls).toHaveLength(1);
    expect(h.spawnCalls[0]?.file).toBe('/bin/bash');
    expect(h.spawnCalls[0]?.args).toEqual(['-l', '-i']);
    expect(h.spawnCalls[0]?.options.cwd).toBe('/project/root');
    expect(h.spawnCalls[0]?.options.cols).toBe(80);
    expect(h.spawnCalls[0]?.options.rows).toBe(24);
  });

  test('Linux creates the PTY with interactive non-login argv', () => {
    const h = makeHarness({
      platform: 'linux',
      env: { SHELL: '/bin/bash', PATH: '/usr/bin' },
      shellExists: (path) => path === '/bin/bash',
    });
    h.fire(CREATE());

    expect(h.spawnCalls[0]?.file).toBe('/bin/bash');
    expect(h.spawnCalls[0]?.args).toEqual(['-i']);
    expect(h.spawnCalls[0]?.args).not.toContain('-l');
  });

  test('Windows prefers the bundled ConPTY dll on the first spawn', () => {
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows' },
      shellExists: () => false,
      pathProbe: () => null,
    });
    h.fire(CREATE({ cwd: 'C:\\project' }));

    expect(h.spawnCalls).toHaveLength(1);
    expect(h.spawnCalls[0]?.options.useConptyDll).toBe(true);
  });

  test('Windows probes pwsh on PATH once per host instead of once per tab', () => {
    let probeCalls = 0;
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows' },
      shellExists: (path) => path === 'C:\\tools\\pwsh.exe',
      pathProbe: () => {
        probeCalls += 1;
        return 'C:\\tools\\pwsh.exe';
      },
    });

    h.fire(CREATE({ ptyId: 'p1', cwd: 'C:\\project' }));
    h.fire(CREATE({ ptyId: 'p2', cwd: 'C:\\project' }));

    expect(probeCalls).toBe(1);
    expect(h.spawnCalls.map((call) => call.file)).toEqual([
      'C:\\tools\\pwsh.exe',
      'C:\\tools\\pwsh.exe',
    ]);
  });

  test('Windows retries a PATH probe that did not produce a verdict', () => {
    let probeCalls = 0;
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows' },
      shellExists: () => false,
      pathProbe: () => {
        probeCalls += 1;
        return null;
      },
      listDirectory: () => [],
    });

    h.fire(CREATE({ ptyId: 'p1', cwd: 'C:\\project' }));
    h.fire(CREATE({ ptyId: 'p2', cwd: 'C:\\project' }));

    expect(probeCalls).toBe(2);
  });

  test('bakes a launch command into a non-history `-c` spawn with an interactive exec tail', () => {
    const env = { SHELL: '/bin/zsh', PATH: '/usr/bin' };
    const h = makeHarness({ env });
    h.fire(CREATE({ launchCommand: "claude 'do the thing'" }));
    const [managedBinDir] = buildShellEnv(env, { platform: 'darwin' }).managedBinDirs;
    expect(managedBinDir).toBeDefined();
    expect(h.spawnCalls[0]?.file).toBe('/bin/zsh');
    expect(h.spawnCalls[0]?.args).toEqual([
      '-l',
      '-i',
      '-c',
      `case ":$PATH:" in *:'${managedBinDir}':*) ;; *) PATH='${managedBinDir}'"\${PATH:+:$PATH}" ;; esac; export PATH; claude 'do the thing'; exec '/bin/zsh' -l -i`,
    ]);
  });

  test('handleCreate threads the logger, so a POSIX terminal with no home leaves a trace', () => {
    vi.mocked(homedir).mockReturnValueOnce('');
    const warnings: Record<string, unknown>[] = [];
    const h = makeHarness({
      platform: 'linux',
      env: { SHELL: '/bin/bash', PATH: '/usr/bin' },
      shellExists: (path) => path === '/bin/bash',
      logger: { warn: (entry) => warnings.push(entry) },
    });
    h.fire(CREATE());
    expect(
      warnings,
      'buildShellEnv warns through an injected logger, so dropping `logger: deps.logger` at the handleCreate call site would silently lose the terminal-side missing-home diagnostic',
    ).toContainEqual({ event: 'pty-host-no-ok-managed-home', platform: 'linux' });
  });

  test('records the resolved shell command family on POSIX, the platform where the question has an answer', () => {
    const entries: Record<string, unknown>[] = [];
    const h = makeHarness({
      platform: 'linux',
      env: { SHELL: '/usr/bin/fish', PATH: '/usr/bin' },
      shellExists: (path) => path === '/usr/bin/fish',
      logger: { warn: () => {}, info: (entry) => entries.push(entry) },
    });

    h.fire(CREATE());

    expect(
      entries,
      'the win32 sibling of this assertion cannot see this field (it is undefined there by construction, and toContainEqual reads an undefined-valued key as absent), so without this test the non-win32 path the field exists for is unasserted from both directions',
    ).toContainEqual({
      event: 'pty-host-shell-resolved',
      platform: 'linux',
      rung: 'env-shell',
      shellCommandFamily: 'fish',
    });
  });

  test('falls back to /bin/zsh when SHELL is unset', () => {
    const h = makeHarness({ env: { PATH: '/usr/bin' } });
    h.fire(CREATE());
    expect(h.spawnCalls[0]?.file).toBe('/bin/zsh');
  });

  test('honors an explicit shell override', () => {
    const h = makeHarness({ env: { SHELL: '/bin/bash' } });
    h.fire(CREATE({ cwd: '/x', cols: 10, rows: 10, shell: '/usr/bin/fish' }));
    expect(h.spawnCalls[0]?.file).toBe('/usr/bin/fish');
  });

  test('strips desktop-only env markers from the child shell env', () => {
    const h = makeHarness({
      env: {
        SHELL: '/bin/zsh',
        PATH: '/usr/bin',
        HOME: '/Users/alice',
        OK_ELECTRON_PROTOCOL_HOST: '1',
        OK_LOCK_KIND: 'interactive',
        [OK_HOSTED_AGENT_ENV]: '1',
      },
    });
    h.fire(CREATE());
    const env = h.spawnCalls[0]?.options.env ?? {};
    expect(env.OK_ELECTRON_PROTOCOL_HOST).toBeUndefined();
    expect(env.OK_LOCK_KIND).toBeUndefined();
    expect(env[OK_HOSTED_AGENT_ENV]).toBeUndefined();
    expect(env.PATH).toBe('/Users/alice/.ok/bin:/usr/bin');
  });

  test('marks the shell as the OK Desktop terminal (OK_DESKTOP_TERMINAL=1)', () => {
    const h = makeHarness({ env: { SHELL: '/bin/zsh', [OK_DESKTOP_TERMINAL_ENV]: '' } });
    h.fire(CREATE());
    const env = h.spawnCalls[0]?.options.env ?? {};
    expect(env[OK_DESKTOP_TERMINAL_ENV]).toBe('1');
  });

  test('prepends ~/.ok/bin to the child PATH so `ok` resolves regardless of rc consent', () => {
    const h = makeHarness({
      env: { SHELL: '/bin/zsh', PATH: '/usr/bin:/bin', HOME: '/Users/alice' },
    });
    h.fire(CREATE());
    const env = h.spawnCalls[0]?.options.env ?? {};
    expect(env.PATH).toBe('/Users/alice/.ok/bin:/usr/bin:/bin');
  });

  test('does not duplicate ~/.ok/bin when the parent PATH already carries it', () => {
    const h = makeHarness({
      env: {
        SHELL: '/bin/zsh',
        PATH: '/opt/x:/Users/alice/.ok/bin:/usr/bin',
        HOME: '/Users/alice',
      },
    });
    h.fire(CREATE());
    const env = h.spawnCalls[0]?.options.env ?? {};
    expect(env.PATH).toBe('/opt/x:/Users/alice/.ok/bin:/usr/bin');
  });

  test('falls back to the home the CLI installer used when the env carries no HOME', () => {
    const h = makeHarness({ env: { SHELL: '/bin/zsh', PATH: '/usr/bin' } });
    h.fire(CREATE());
    const env = h.spawnCalls[0]?.options.env ?? {};
    expect(
      env.PATH,
      'index.ts installs the CLI under osHomedir(), not process.env.HOME, so a terminal that skipped the grant here would omit a directory that exists on disk, and would disagree with the probe children that do resolve it',
    ).toBe(`${posixOkManagedBinDir(homedir())}:/usr/bin`);
  });
});

describe('setupPtyHost — streaming', () => {
  test('forwards shell output as data messages tagged with the ptyId', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE({ ptyId: 'abc' }));
    pty.emitData('hello ');
    pty.emitData('world');
    expect(h.posted).toEqual([
      { type: 'data', ptyId: 'abc', data: 'hello ' },
      { type: 'data', ptyId: 'abc', data: 'world' },
    ]);
  });

  test('writes renderer input to the pty', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE());
    h.fire({ type: 'input', ptyId: 'p1', data: 'ls -la\r' });
    expect(pty.writes).toEqual(['ls -la\r']);
  });

  test('resizes the pty', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE());
    h.fire({ type: 'resize', ptyId: 'p1', cols: 120, rows: 40 });
    expect(pty.resizes).toEqual([[120, 40]]);
  });

  test('kills the pty on a kill message', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE());
    h.fire({ type: 'kill', ptyId: 'p1' });
    expect(pty.killCount).toBe(1);
  });

  test('escalates a hung kill to SIGKILL when onExit never fires', async () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE());
    h.fire({ type: 'kill', ptyId: 'p1' });
    expect(pty.killCount).toBe(1);
    await new Promise((resolve) => setTimeout(resolve, 300));
    expect(pty.killCount).toBe(2);
    expect(pty.killSignals).toEqual([undefined, 'SIGKILL']);
  });

  test('cancels SIGKILL escalate after onExit', async () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE());
    h.fire({ type: 'kill', ptyId: 'p1' });
    pty.emitExit({ exitCode: 0 });
    await new Promise((resolve) => setTimeout(resolve, 300));
    expect(pty.killCount).toBe(1);
  });

  test('does not escalate SIGKILL after killActiveSessions', async () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE());
    h.handle.killActive();
    expect(pty.killCount).toBe(1);
    await new Promise((resolve) => setTimeout(resolve, 300));
    expect(pty.killCount).toBe(1);
  });

  test('logs a reap-failed warning when kill throws a non-ESRCH error', () => {
    const pty = makeFakePty();
    pty.kill = () => {
      throw Object.assign(new Error('kill EPERM'), { code: 'EPERM' });
    };
    const warnings: Record<string, unknown>[] = [];
    const h = makeHarness({ pty, logger: { warn: (o) => warnings.push(o) } });
    h.fire(CREATE());
    expect(() => h.fire({ type: 'kill', ptyId: 'p1' })).not.toThrow();
    expect(warnings).toContainEqual(
      expect.objectContaining({ event: 'pty-host-reap-failed', code: 'EPERM' }),
    );
  });

  test('routes pause/resume backpressure to the active pty', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE());
    h.fire({ type: 'pause', ptyId: 'p1' });
    h.fire({ type: 'resume', ptyId: 'p1' });
    expect(pty.pauseCount).toBe(1);
    expect(pty.resumeCount).toBe(1);
  });
});

const PWSH = 'C:\\Program Files\\PowerShell\\7\\pwsh.exe';
const FOCUS_OUT = '\u001b[O';
const FOCUS_IN = '\u001b[I';
const SHIFT_F3 = '\u001b[1;2R';
const RECORDED_CURSOR_REPORT = '\u001b[13;81R';
const SMOKE_SPAWN_SIZE = { cols: 222, rows: 13 };
const MOVED_SIZE = { cols: 101, rows: 52 };
const POST_MOVE_COMMAND = 'Write-Output "PROCESS_after-move=$PID"';

interface TerminalLink {
  send(data: string): void;
  resize(cols: number, rows: number): void;
  received(): string;
}

interface XtermSide {
  readonly sent: readonly string[];
  type(text: string): void;
  report(sequence: string): void;
  resize(size: { cols: number; rows: number }): void;
  answerCursorQueries(): void;
}

function createXtermSide(link: TerminalLink): XtermSide {
  const sent: string[] = [];
  let answered = 0;
  const send = (data: string): void => {
    sent.push(data);
    link.send(data);
  };
  return {
    sent,
    type(text) {
      for (const key of text) send(key);
    },
    report: send,
    resize({ cols, rows }) {
      link.resize(cols, rows);
    },
    answerCursorQueries() {
      const asked = link.received().split(CURSOR_POSITION_QUERY).length - 1;
      for (; answered < asked; answered += 1) send(RECORDED_CURSOR_REPORT);
    },
  };
}

function rendererReceived(h: Harness, ptyId: string): string {
  return h.posted
    .flatMap((message) =>
      message.type === 'data' && message.ptyId === ptyId ? [message.data] : [],
    )
    .join('');
}

function ptyHostLink(h: Harness, ptyId: string): TerminalLink {
  return {
    send: (data) => h.fire({ type: 'input', ptyId, data }),
    resize: (cols, rows) => h.fire({ type: 'resize', ptyId, cols, rows }),
    received: () => rendererReceived(h, ptyId),
  };
}

function startBundledConptySession(host: ConptyCursorSyncHost): { h: Harness; xterm: XtermSide } {
  const h = makeHarness({
    platform: 'win32',
    env: { SystemRoot: 'C:\\Windows', ProgramFiles: 'C:\\Program Files' },
    shellExists: (path) => path === PWSH,
    pathProbe: () => PWSH,
    spawn: () => host,
  });
  h.fire(CREATE({ cwd: 'C:\\project', ...SMOKE_SPAWN_SIZE }));
  return { h, xterm: createXtermSide(ptyHostLink(h, 'p1')) };
}

interface RecordedRetriedQuery {
  attempt: string;
  command: string;
  typedBeforeFirstQuery: string;
  typedBetweenQueries: string;
  typedBeforeReplies: string;
  shellRan: string;
}

const RECORDED_RETRIED_QUERIES: readonly RecordedRetriedQuery[] = [
  {
    attempt: 'bundled #10 of run 36140409827',
    command: 'Write-Output "PROCESS_1e6a4905ac984ac483cff50173bdb9b9=$PID"',
    typedBeforeFirstQuery: 'W',
    typedBetweenQueries: '',
    typedBeforeReplies: '',
    shellRan: 'Wite-Output "PROCESS_1e6a4905ac984ac483cff50173bdb9b9=$PID"',
  },
  {
    attempt: 'bundled #32 of run 36140409827',
    command: 'Write-Output "PROCESS_4b7e8901d77d4c309c337676fe637047=$PID"',
    typedBeforeFirstQuery: 'W',
    typedBetweenQueries: '',
    typedBeforeReplies: 'r',
    shellRan: 'Wrte-Output "PROCESS_4b7e8901d77d4c309c337676fe637047=$PID"',
  },
  {
    attempt: 'bundled #16 of run 36138023695',
    command: 'Write-Output "PROCESS_a292934b75004134ab1f29723a1243cb=$PID"',
    typedBeforeFirstQuery: 'W',
    typedBetweenQueries: 'ri',
    typedBeforeReplies: '',
    shellRan: 'Wrie-Output "PROCESS_a292934b75004134ab1f29723a1243cb=$PID"',
  },
  {
    attempt: 'bundled #18 of run 36138023695',
    command: 'Write-Output "PROCESS_8446c9b807c94289a86014529d59b33e=$PID"',
    typedBeforeFirstQuery: 'Write-Output',
    typedBetweenQueries: '',
    typedBeforeReplies: '',
    shellRan: 'Write-Output"PROCESS_8446c9b807c94289a86014529d59b33e=$PID"',
  },
];

function replayRetriedQuery(
  xterm: XtermSide,
  host: ConptyCursorSyncHost,
  recorded: RecordedRetriedQuery,
): void {
  const typedBeforeReplies =
    recorded.typedBeforeFirstQuery + recorded.typedBetweenQueries + recorded.typedBeforeReplies;
  if (!recorded.command.startsWith(typedBeforeReplies)) {
    throw new Error(
      `${recorded.attempt}: the keys typed before the replies must begin its command`,
    );
  }
  xterm.report(FOCUS_OUT);
  xterm.resize(MOVED_SIZE);
  xterm.report(FOCUS_IN);
  xterm.type(recorded.typedBeforeFirstQuery);
  host.shellReadsScreenBufferInfo();
  xterm.type(recorded.typedBetweenQueries);
  host.cursorSyncWaitTimesOut();
  host.shellReadsScreenBufferInfo();
  xterm.type(recorded.typedBeforeReplies);
  xterm.answerCursorQueries();
  xterm.type(`${recorded.command.slice(typedBeforeReplies.length)}\r`);
}

describe('setupPtyHost — cursor-position queries from the console host', () => {
  test.each(RECORDED_RETRIED_QUERIES)(
    'a query the bundled ConPTY host re-issued after its wait expired does not cost the shell a typed key ($attempt)',
    (recorded) => {
      const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
      const { xterm } = startBundledConptySession(host);

      replayRetriedQuery(xterm, host, recorded);

      expect(host.cursorQueriesIssued).toBe(2);
      expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([recorded.command]);
      expect(host.keysReadByShell.join(''), 'the keys the shell read').toBe(
        `${recorded.command}\r`,
      );
    },
  );

  test('a second query raised by a later resize while the first is unanswered does not cost the shell a typed key, even from a host that stops re-asking after a timeout', () => {
    const host = createConptyCursorSyncHost({
      ...SMOKE_SPAWN_SIZE,
      afterTimedOutQuery: 'stops-asking',
    });
    const { xterm } = startBundledConptySession(host);

    xterm.resize(MOVED_SIZE);
    xterm.type('W');
    host.shellReadsScreenBufferInfo();
    host.cursorSyncWaitTimesOut();
    host.shellReadsScreenBufferInfo();
    expect(host.cursorQueriesIssued).toBe(1);
    xterm.resize(SMOKE_SPAWN_SIZE);
    xterm.type('r');
    host.shellReadsScreenBufferInfo();
    expect(host.cursorQueriesIssued).toBe(2);
    xterm.answerCursorQueries();
    xterm.type(`${POST_MOVE_COMMAND.slice('Wr'.length)}\r`);

    expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([POST_MOVE_COMMAND]);
    expect(host.keysReadByShell.join(''), 'the keys the shell read').toBe(`${POST_MOVE_COMMAND}\r`);
  });

  test('a re-issued query split across output chunks is still recognized, so its late reply does not cost the shell a typed key', () => {
    const recorded = RECORDED_RETRIED_QUERIES[1] as RecordedRetriedQuery;
    const host = createConptyCursorSyncHost({
      ...SMOKE_SPAWN_SIZE,
      queryOutput: (queryNumber) =>
        queryNumber === 1 ? ['\u001b[?25l\u001b[', '6n'] : ['\u001b', '[6n\u001b[?25h'],
    });
    const { xterm } = startBundledConptySession(host);

    replayRetriedQuery(xterm, host, recorded);

    expect(host.cursorQueriesIssued).toBe(2);
    expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([recorded.command]);
    expect(host.keysReadByShell.join(''), 'the keys the shell read').toBe(`${recorded.command}\r`);
  });

  test('a query answered before the wait expires still reaches the host, which takes the cursor position from the reply', () => {
    const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const { xterm } = startBundledConptySession(host);

    xterm.resize(MOVED_SIZE);
    xterm.type('W');
    host.shellReadsScreenBufferInfo();
    xterm.answerCursorQueries();
    expect(host.cursorReportsConsumed).toEqual([{ row: 13, column: 81 }]);
    xterm.type(`${POST_MOVE_COMMAND.slice('W'.length)}\r`);
    host.shellReadsScreenBufferInfo();

    expect(host.cursorQueriesIssued).toBe(1);
    expect(host.inputReceived.join('')).toBe(xterm.sent.join(''));
    expect(host.linesAcceptedByShell).toEqual([POST_MOVE_COMMAND]);
  });

  test('a query split across output chunks still reaches the renderer intact, and its reply still reaches the host', () => {
    const host = createConptyCursorSyncHost({
      ...SMOKE_SPAWN_SIZE,
      queryOutput: () => ['\u001b[', '6n'],
    });
    const { h, xterm } = startBundledConptySession(host);

    xterm.resize(MOVED_SIZE);
    xterm.type('W');
    host.shellReadsScreenBufferInfo();
    xterm.answerCursorQueries();
    xterm.type(`${POST_MOVE_COMMAND.slice('W'.length)}\r`);

    expect(rendererReceived(h, 'p1')).toBe(host.outputEmitted.join(''));
    expect(host.cursorReportsConsumed).toEqual([{ row: 13, column: 81 }]);
    expect(host.inputReceived.join('')).toBe(xterm.sent.join(''));
    expect(host.linesAcceptedByShell).toEqual([POST_MOVE_COMMAND]);
  });

  test('a Shift+F3 the user types after the host query was answered still reaches the host unchanged', () => {
    const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const { xterm } = startBundledConptySession(host);

    xterm.resize(MOVED_SIZE);
    xterm.type('W');
    host.shellReadsScreenBufferInfo();
    xterm.answerCursorQueries();
    xterm.type('rite-Output');
    xterm.report(SHIFT_F3);
    xterm.type('rX\r');

    expect(host.inputReceived.join('')).toBe(xterm.sent.join(''));
    expect(host.linesAcceptedByShell).toEqual(['WXrite-Output']);
  });

  test.each(['darwin', 'linux'] as const)(
    'on %s, a shell application that asks for the cursor position twice gets both replies',
    (platform) => {
      const pty = makeFakePty();
      const h = makeHarness({
        pty,
        platform,
        env: { SHELL: '/bin/bash', PATH: '/usr/bin' },
        shellExists: (path) => path === '/bin/bash',
      });
      h.fire(CREATE());
      const xterm = createXtermSide(ptyHostLink(h, 'p1'));

      pty.emitData(CURSOR_POSITION_QUERY);
      pty.emitData(CURSOR_POSITION_QUERY);
      xterm.answerCursorQueries();

      expect(pty.writes.join('')).toBe(RECORDED_CURSOR_REPORT.repeat(2));
    },
  );
});

describe('ConPTY cursor-sync host model — conformance to the recorded attempts', () => {
  test.each(RECORDED_RETRIED_QUERIES)(
    'fed the recorded bytes with nothing in between, it runs the command the shell ran in $attempt',
    (recorded) => {
      const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
      const xterm = createXtermSide({
        send: (data) => host.write(data),
        resize: (cols, rows) => host.resize(cols, rows),
        received: () => host.outputEmitted.join(''),
      });

      replayRetriedQuery(xterm, host, recorded);

      expect(host.linesAcceptedByShell).toEqual([recorded.shellRan]);
    },
  );
});

const WINDOWS_PWSH_SESSION = {
  platform: 'win32',
  env: { SystemRoot: 'C:\\Windows', ProgramFiles: 'C:\\Program Files' },
  shellExists: (path: string) => path === PWSH,
  pathProbe: () => PWSH,
} as const;
const VIM_START_UP_PROBES = [
  { probe: '\u001b[2;1H\u25bd\u001b[6n', reply: '\u001b[2;2R' },
  { probe: '\u001b[3;1H\u001bPzz\u001b\\\u001b[0%m\u001b[6n', reply: '\u001b[3;1R' },
] as const;
const DECXCPR_REPLY = '\u001b[?13;81R';
const SPLIT_QUERY_OUTPUT = (queryNumber: number): readonly string[] =>
  queryNumber === 1 ? ['\u001b[?25l\u001b[', '6n'] : ['\u001b', '[6n\u001b[?25h'];
const CURSOR_REPORT_DROPPED = {
  level: 'warn',
  entry: { event: 'pty-host-cursor-report-dropped', ptyId: 'p1' },
} as const;

function openWindowsTerminal(h: Harness, ptyId = 'p1'): XtermSide {
  h.fire(CREATE({ ptyId, cwd: 'C:\\project', ...SMOKE_SPAWN_SIZE }));
  return createXtermSide(ptyHostLink(h, ptyId));
}

function spawnInTurn(...ptys: PtyProcessLike[]): SpawnPty {
  const unspawned = [...ptys];
  return () => {
    const next = unspawned.shift();
    if (next === undefined) throw new Error('the host spawned more ptys than the test prepared');
    return next;
  };
}

function rendererChunks(h: Harness, ptyId: string): string[] {
  return h.posted.flatMap((message) =>
    message.type === 'data' && message.ptyId === ptyId ? [message.data] : [],
  );
}

function answerVimStartUpProbes(pty: FakePty, xterm: XtermSide): void {
  for (const { probe } of VIM_START_UP_PROBES) pty.emitData(probe);
  for (const { reply } of VIM_START_UP_PROBES) xterm.report(reply);
}

function answerOnlyTheFirstRetriedQuery(host: ConptyCursorSyncHost, xterm: XtermSide): void {
  xterm.resize(MOVED_SIZE);
  host.shellReadsScreenBufferInfo();
  host.cursorSyncWaitTimesOut();
  host.shellReadsScreenBufferInfo();
  xterm.report(RECORDED_CURSOR_REPORT);
}

function typeWithShiftF3(xterm: XtermSide): void {
  xterm.type('Write-Output');
  xterm.report(SHIFT_F3);
  xterm.type('rX\r');
}

describe("setupPtyHost — cursor-position replies outside the console host's resize sync", () => {
  test('with no size change since the session started, a Windows application that asks for the cursor position twice gets both replies', () => {
    const pty = makeFakePty();
    const xterm = openWindowsTerminal(makeHarness({ pty, ...WINDOWS_PWSH_SESSION }));

    pty.emitData(CURSOR_POSITION_QUERY);
    pty.emitData(CURSOR_POSITION_QUERY);
    xterm.answerCursorQueries();

    expect(pty.writes).toEqual([RECORDED_CURSOR_REPORT, RECORDED_CURSOR_REPORT]);
  });

  test.each([
    {
      size: 'the size it was created at',
      settle: (_pty: FakePty, xterm: XtermSide) => xterm.resize(SMOKE_SPAWN_SIZE),
    },
    {
      size: 'the size a finished sync left',
      settle: (pty: FakePty, xterm: XtermSide) => {
        xterm.resize(MOVED_SIZE);
        pty.emitData(CURSOR_POSITION_QUERY);
        xterm.answerCursorQueries();
        xterm.resize(MOVED_SIZE);
      },
    },
  ])(
    "a resize to the size the session already has withholds neither reply to vim's two start-up probes ($size)",
    ({ settle }) => {
      const pty = makeFakePty();
      const h = makeHarness({ pty, ...WINDOWS_PWSH_SESSION });
      const xterm = openWindowsTerminal(h);

      settle(pty, xterm);
      answerVimStartUpProbes(pty, xterm);

      expect(rendererReceived(h, 'p1')).toContain(
        VIM_START_UP_PROBES.map(({ probe }) => probe).join(''),
      );
      expect(pty.writes).toEqual(xterm.sent);
    },
  );

  test("once the console host's post-resize query is answered, vim's two start-up probes get both replies", () => {
    const pty = makeFakePty();
    const xterm = openWindowsTerminal(makeHarness({ pty, ...WINDOWS_PWSH_SESSION }));

    xterm.resize(MOVED_SIZE);
    pty.emitData(CURSOR_POSITION_QUERY);
    xterm.answerCursorQueries();
    answerVimStartUpProbes(pty, xterm);

    expect(pty.writes).toEqual([
      RECORDED_CURSOR_REPORT,
      ...VIM_START_UP_PROBES.map(({ reply }) => reply),
    ]);
  });

  test.each([
    { lookalike: 'a DECXCPR request', output: '\u001b[?6n' },
    { lookalike: 'a status request with code 16', output: '\u001b[16n' },
    { lookalike: 'the query text without its escape', output: '[6n' },
  ])(
    'a lookalike of the cursor query in host output during the resize sync is not taken for one, so a Shift+F3 typed after the real query was answered still reaches the host ($lookalike)',
    ({ output }) => {
      const host = createConptyCursorSyncHost({
        ...SMOKE_SPAWN_SIZE,
        queryOutput: () => [output, CURSOR_POSITION_QUERY],
      });
      const { xterm } = startBundledConptySession(host);

      xterm.resize(MOVED_SIZE);
      xterm.type('W');
      host.shellReadsScreenBufferInfo();
      xterm.answerCursorQueries();
      xterm.type('rite-Output');
      xterm.report(SHIFT_F3);
      xterm.type('rX\r');

      expect(host.cursorReportsConsumed).toEqual([{ row: 13, column: 81 }]);
      expect(host.inputReceived).toEqual(xterm.sent);
      expect(host.linesAcceptedByShell).toEqual(['WXrite-Output']);
    },
  );

  test('a surplus reply outstanding in one Windows session does not withhold a Shift+F3 typed in another', () => {
    const asking = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const typing = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const h = makeHarness({ ...WINDOWS_PWSH_SESSION, spawn: spawnInTurn(asking, typing) });
    const askingXterm = openWindowsTerminal(h, 'asking');
    const typingXterm = openWindowsTerminal(h, 'typing');

    answerOnlyTheFirstRetriedQuery(asking, askingXterm);
    typeWithShiftF3(typingXterm);

    expect(asking.cursorQueriesIssued).toBe(2);
    expect(asking.cursorReportsConsumed).toEqual([{ row: 13, column: 81 }]);
    expect(typing.inputReceived).toEqual(typingXterm.sent);
    expect(typing.linesAcceptedByShell).toEqual(['WXrite-Output']);
  });

  test('a create that replaces a live Windows session under the same id starts with no reply outstanding', () => {
    const replaced = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const replacement = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const h = makeHarness({ ...WINDOWS_PWSH_SESSION, spawn: spawnInTurn(replaced, replacement) });

    answerOnlyTheFirstRetriedQuery(replaced, openWindowsTerminal(h));
    const xterm = openWindowsTerminal(h);
    typeWithShiftF3(xterm);

    expect(replaced.cursorQueriesIssued).toBe(2);
    expect(replacement.inputReceived).toEqual(xterm.sent);
    expect(replacement.linesAcceptedByShell).toEqual(['WXrite-Output']);
  });
});

describe("setupPtyHost — an application's cursor-position queries inside the console host's resize sync", () => {
  test('after a size change, before the console host asks for the cursor position, an application that asks for it twice before either reply, as vim does at start-up, gets only its first reply: the second is withheld with one warn record, and input after that reaches the host', () => {
    const records: Array<{ level: 'warn' | 'info'; entry: Record<string, unknown> }> = [];
    const pty = makeFakePty();
    const h = makeHarness({
      pty,
      ...WINDOWS_PWSH_SESSION,
      logger: {
        warn: (entry) => records.push({ level: 'warn', entry }),
        info: (entry) => records.push({ level: 'info', entry }),
      },
    });
    const xterm = openWindowsTerminal(h);
    const recordsAtStart = records.length;
    const recordsSinceStart = () => records.slice(recordsAtStart);
    const [vimFirstProbe, vimSecondProbe] = VIM_START_UP_PROBES;

    xterm.resize(MOVED_SIZE);
    answerVimStartUpProbes(pty, xterm);

    expect(rendererReceived(h, 'p1'), 'the output the renderer received').toBe(
      vimFirstProbe.probe + vimSecondProbe.probe,
    );
    expect(xterm.sent, 'the replies the renderer sent').toEqual([
      vimFirstProbe.reply,
      vimSecondProbe.reply,
    ]);
    expect(pty.writes, 'the input written to the host').toEqual([vimFirstProbe.reply]);
    expect(recordsSinceStart(), 'the records after both replies').toEqual([CURSOR_REPORT_DROPPED]);

    xterm.report(SHIFT_F3);
    answerVimStartUpProbes(pty, xterm);

    expect(
      pty.writes,
      'the input written to the host after the Shift+F3 and the second vim start',
    ).toEqual([vimFirstProbe.reply, SHIFT_F3, vimFirstProbe.reply, vimSecondProbe.reply]);
    expect(recordsSinceStart(), 'the records after the Shift+F3 and the second vim start').toEqual([
      CURSOR_REPORT_DROPPED,
    ]);
  });
});

describe("setupPtyHost — the surplus reply to the console host's resize sync", () => {
  test('while the surplus reply is outstanding, a DECXCPR reply and input that carries a reply among other bytes reach the host unchanged, and the surplus reply is still withheld', () => {
    const pty = makeFakePty();
    const xterm = openWindowsTerminal(makeHarness({ pty, ...WINDOWS_PWSH_SESSION }));
    const notALoneReply = [
      DECXCPR_REPLY,
      `x${RECORDED_CURSOR_REPORT}`,
      `${RECORDED_CURSOR_REPORT}x`,
      `\u001b[200~${RECORDED_CURSOR_REPORT}\u001b[201~`,
    ];

    xterm.resize(MOVED_SIZE);
    pty.emitData(CURSOR_POSITION_QUERY);
    pty.emitData(CURSOR_POSITION_QUERY);
    xterm.report(RECORDED_CURSOR_REPORT);
    for (const input of notALoneReply) xterm.report(input);
    expect(pty.writes).toEqual([RECORDED_CURSOR_REPORT, ...notALoneReply]);

    xterm.report(RECORDED_CURSOR_REPORT);

    expect(pty.writes, 'the input written once the surplus reply arrived').toEqual([
      RECORDED_CURSOR_REPORT,
      ...notALoneReply,
    ]);
  });

  test('a session on the OS ConPTY, after the bundled dll failed to load, also keeps a re-issued query from costing the shell a typed key', () => {
    const recorded = RECORDED_RETRIED_QUERIES[0] as RecordedRetriedQuery;
    const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const spawnOptions: PtySpawnOptions[] = [];
    const xterm = openWindowsTerminal(
      makeHarness({
        ...WINDOWS_PWSH_SESSION,
        spawn: (_file, _args, options) => {
          spawnOptions.push(options);
          if (spawnOptions.length === 1) {
            throw new Error('Cannot find conpty.dll beside conpty.node');
          }
          return host;
        },
      }),
    );

    replayRetriedQuery(xterm, host, recorded);

    expect(spawnOptions.map((options) => options.useConptyDll)).toEqual([true, false]);
    expect(host.cursorQueriesIssued).toBe(2);
    expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([recorded.command]);
    expect(host.keysReadByShell.join(''), 'the keys the shell read').toBe(`${recorded.command}\r`);
  });

  test('each console host resize sync that withholds replies leaves exactly one warn record, naming its session and with no reply bytes in it, however many replies it withholds, and a reply that reaches the host leaves none', () => {
    const records: Array<{ level: 'warn' | 'info'; entry: Record<string, unknown> }> = [];
    const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const xterm = openWindowsTerminal(
      makeHarness({
        ...WINDOWS_PWSH_SESSION,
        spawn: () => host,
        logger: {
          warn: (entry) => records.push({ level: 'warn', entry }),
          info: (entry) => records.push({ level: 'info', entry }),
        },
      }),
    );
    const recordsAtStart = records.length;
    const recordsSinceStart = () => records.slice(recordsAtStart);

    xterm.resize(MOVED_SIZE);
    xterm.type('W');
    host.shellReadsScreenBufferInfo();
    host.cursorSyncWaitTimesOut();
    host.shellReadsScreenBufferInfo();
    host.cursorSyncWaitTimesOut();
    host.shellReadsScreenBufferInfo();
    expect(host.cursorQueriesIssued).toBe(3);

    xterm.report(RECORDED_CURSOR_REPORT);
    expect(host.cursorReportsConsumed).toEqual([{ row: 13, column: 81 }]);
    expect(recordsSinceStart(), 'after the reply the host consumed').toEqual([]);

    xterm.report(RECORDED_CURSOR_REPORT);
    expect(recordsSinceStart(), 'after the first surplus reply').toEqual([CURSOR_REPORT_DROPPED]);

    xterm.report(RECORDED_CURSOR_REPORT);
    xterm.type(`${POST_MOVE_COMMAND.slice('W'.length)}\r`);
    expect(
      recordsSinceStart(),
      'after the second surplus reply of the same sync and the typed command',
    ).toEqual([CURSOR_REPORT_DROPPED]);

    xterm.resize(SMOKE_SPAWN_SIZE);
    host.shellReadsScreenBufferInfo();
    host.cursorSyncWaitTimesOut();
    host.shellReadsScreenBufferInfo();
    expect(host.cursorQueriesIssued).toBe(5);
    xterm.report(RECORDED_CURSOR_REPORT);
    xterm.report(RECORDED_CURSOR_REPORT);

    expect(host.cursorReportsConsumed, 'the replies the host consumed').toEqual([
      { row: 13, column: 81 },
      { row: 13, column: 81 },
    ]);
    expect(recordsSinceStart(), 'after the surplus reply of the next sync').toEqual([
      CURSOR_REPORT_DROPPED,
      CURSOR_REPORT_DROPPED,
    ]);
  });

  test('each warn record names the Windows session whose surplus reply it withheld, when two sessions in one window each withhold one', () => {
    const records: Array<{ level: 'warn' | 'info'; entry: Record<string, unknown> }> = [];
    const recorded = RECORDED_RETRIED_QUERIES[0] as RecordedRetriedQuery;
    const firstTab = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const secondTab = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const h = makeHarness({
      ...WINDOWS_PWSH_SESSION,
      spawn: spawnInTurn(firstTab, secondTab),
      logger: {
        warn: (entry) => records.push({ level: 'warn', entry }),
        info: (entry) => records.push({ level: 'info', entry }),
      },
    });
    const firstTabXterm = openWindowsTerminal(h, 'first-tab');
    const secondTabXterm = openWindowsTerminal(h, 'second-tab');
    const recordsAtStart = records.length;

    replayRetriedQuery(firstTabXterm, firstTab, recorded);
    replayRetriedQuery(secondTabXterm, secondTab, recorded);

    expect(records.slice(recordsAtStart)).toEqual([
      { level: 'warn', entry: { event: 'pty-host-cursor-report-dropped', ptyId: 'first-tab' } },
      { level: 'warn', entry: { event: 'pty-host-cursor-report-dropped', ptyId: 'second-tab' } },
    ]);
  });

  test.each([
    {
      shape: 'each query in its own chunk',
      recorded: RECORDED_RETRIED_QUERIES[2] as RecordedRetriedQuery,
      queryOutput: undefined,
    },
    {
      shape: 'each query split across chunks',
      recorded: RECORDED_RETRIED_QUERIES[1] as RecordedRetriedQuery,
      queryOutput: SPLIT_QUERY_OUTPUT,
    },
  ])(
    'in a retried-query replay, the renderer gets the host output chunk for chunk and the host gets every renderer message but the surplus reply ($shape)',
    ({ recorded, queryOutput }) => {
      const host = createConptyCursorSyncHost({ ...SMOKE_SPAWN_SIZE, queryOutput });
      const { h, xterm } = startBundledConptySession(host);

      replayRetriedQuery(xterm, host, recorded);

      expect(host.cursorQueriesIssued).toBe(2);
      expect(rendererChunks(h, 'p1'), 'the output the renderer received').toEqual(
        host.outputEmitted,
      );
      expect(xterm.sent.filter((message) => message === RECORDED_CURSOR_REPORT)).toHaveLength(2);
      const surplusReply = xterm.sent.lastIndexOf(RECORDED_CURSOR_REPORT);
      expect(host.inputReceived, 'the input the host received').toEqual(
        xterm.sent.filter((_message, index) => index !== surplusReply),
      );
    },
  );
});

const CMD_EXE = 'C:\\Windows\\System32\\cmd.exe';
const WINDOWS_POWERSHELL = 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe';

describe("setupPtyHost — the console host's cursor query in its output", () => {
  test('when the console host re-issued its query before the pty-host read the first, both queries arrive in one output chunk and only the first reply reaches the host', () => {
    const pty = makeFakePty();
    const xterm = openWindowsTerminal(makeHarness({ pty, ...WINDOWS_PWSH_SESSION }));

    xterm.resize(MOVED_SIZE);
    pty.emitData(CURSOR_POSITION_QUERY + CURSOR_POSITION_QUERY);
    xterm.answerCursorQueries();

    expect(xterm.sent, 'the replies the renderer sent').toEqual([
      RECORDED_CURSOR_REPORT,
      RECORDED_CURSOR_REPORT,
    ]);
    expect(pty.writes, 'the input written to the host').toEqual([RECORDED_CURSOR_REPORT]);
  });

  test.each([
    { split: 'one byte per chunk', queryOutput: () => [...CURSOR_POSITION_QUERY] },
    { split: 'split before its last byte', queryOutput: () => ['\u001b[6', 'n'] },
  ])(
    'a re-issued query the console host writes across output chunks is still recognized, so its late reply does not cost the shell a typed key ($split)',
    ({ queryOutput }) => {
      const recorded = RECORDED_RETRIED_QUERIES[0] as RecordedRetriedQuery;
      const host = createConptyCursorSyncHost({ ...SMOKE_SPAWN_SIZE, queryOutput });
      const { h, xterm } = startBundledConptySession(host);

      replayRetriedQuery(xterm, host, recorded);

      expect(host.cursorQueriesIssued).toBe(2);
      expect(rendererChunks(h, 'p1'), 'the output the renderer received').toEqual(
        host.outputEmitted,
      );
      expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([recorded.command]);
      expect(host.keysReadByShell.join(''), 'the keys the shell read').toBe(
        `${recorded.command}\r`,
      );
    },
  );

  test('output that only begins a cursor query before the next chunk breaks it off is not completed by later output, so a Shift+F3 typed after the real query was answered still reaches the host', () => {
    const host = createConptyCursorSyncHost({
      ...SMOKE_SPAWN_SIZE,
      queryOutput: () => ['\u001b[', '?25h', '6n', CURSOR_POSITION_QUERY],
    });
    const { xterm } = startBundledConptySession(host);

    xterm.resize(MOVED_SIZE);
    xterm.type('W');
    host.shellReadsScreenBufferInfo();
    xterm.answerCursorQueries();
    xterm.type('rite-Output');
    xterm.report(SHIFT_F3);
    xterm.type('rX\r');

    expect(host.cursorReportsConsumed).toEqual([{ row: 13, column: 81 }]);
    expect(host.inputReceived).toEqual(xterm.sent);
    expect(host.linesAcceptedByShell).toEqual(['WXrite-Output']);
  });
});

describe("setupPtyHost — the console host's resize sync after any size change, in any Windows session", () => {
  test.each([
    { dimension: 'width', size: { cols: MOVED_SIZE.cols, rows: SMOKE_SPAWN_SIZE.rows } },
    { dimension: 'height', size: { cols: SMOKE_SPAWN_SIZE.cols, rows: MOVED_SIZE.rows } },
  ])(
    "a resize that changes only the $dimension also keeps the console host's re-issued query from costing the shell a typed key",
    ({ size }) => {
      const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
      const { xterm } = startBundledConptySession(host);

      xterm.resize(size);
      xterm.type('W');
      host.shellReadsScreenBufferInfo();
      host.cursorSyncWaitTimesOut();
      host.shellReadsScreenBufferInfo();
      xterm.answerCursorQueries();
      xterm.type(`${POST_MOVE_COMMAND.slice('W'.length)}\r`);

      expect(host.cursorQueriesIssued).toBe(2);
      expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([POST_MOVE_COMMAND]);
      expect(host.keysReadByShell.join(''), 'the keys the shell read').toBe(
        `${POST_MOVE_COMMAND}\r`,
      );
    },
  );

  test("a second move, after the console host's first resize sync was answered, also keeps the host's re-issued query from costing the shell a typed key", () => {
    const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const { xterm } = startBundledConptySession(host);

    xterm.resize(MOVED_SIZE);
    host.shellReadsScreenBufferInfo();
    xterm.answerCursorQueries();
    expect(host.cursorReportsConsumed).toEqual([{ row: 13, column: 81 }]);
    xterm.resize(SMOKE_SPAWN_SIZE);
    xterm.type('W');
    host.shellReadsScreenBufferInfo();
    host.cursorSyncWaitTimesOut();
    host.shellReadsScreenBufferInfo();
    xterm.answerCursorQueries();
    xterm.type(`${POST_MOVE_COMMAND.slice('W'.length)}\r`);

    expect(host.cursorQueriesIssued).toBe(3);
    expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([POST_MOVE_COMMAND]);
    expect(host.keysReadByShell.join(''), 'the keys the shell read').toBe(`${POST_MOVE_COMMAND}\r`);
  });

  test.each([
    {
      session: 'a cmd.exe shell',
      shellExists: () => false,
      create: CREATE({ cwd: 'C:\\project', ...SMOKE_SPAWN_SIZE }),
      spawned: { file: CMD_EXE, args: [] },
    },
    {
      session: 'a Windows PowerShell shell',
      shellExists: (path: string) => path === WINDOWS_POWERSHELL,
      create: CREATE({ cwd: 'C:\\project', ...SMOKE_SPAWN_SIZE }),
      spawned: { file: WINDOWS_POWERSHELL, args: [] },
    },
    {
      session: 'an agent launched through cmd /K',
      shellExists: () => false,
      create: CREATE({
        cwd: 'C:\\project',
        ...SMOKE_SPAWN_SIZE,
        launchCommand: { executable: 'claude', args: [] },
      }),
      spawned: { file: CMD_EXE, args: '/K claude' },
    },
  ])(
    "in a Windows session with $session, only the first reply to the console host's retried query reaches the host",
    ({ shellExists, create, spawned }) => {
      const pty = makeFakePty();
      const h = makeHarness({
        pty,
        platform: 'win32',
        env: { SystemRoot: 'C:\\Windows', ComSpec: CMD_EXE },
        shellExists,
        pathProbe: () => null,
        listDirectory: () => [],
      });
      h.fire(create);
      const xterm = createXtermSide(ptyHostLink(h, 'p1'));

      xterm.resize(MOVED_SIZE);
      pty.emitData(CURSOR_POSITION_QUERY);
      pty.emitData(CURSOR_POSITION_QUERY);
      xterm.answerCursorQueries();

      expect(h.spawnCalls.map(({ file, args }) => ({ file, args }))).toEqual([spawned]);
      expect(xterm.sent, 'the replies the renderer sent').toEqual([
        RECORDED_CURSOR_REPORT,
        RECORDED_CURSOR_REPORT,
      ]);
      expect(pty.writes, 'the input written to the host').toEqual([RECORDED_CURSOR_REPORT]);
    },
  );
});

describe("setupPtyHost — replies across the console host's resize syncs", () => {
  test("after both replies to the console host's retried query came back, a Shift+F3 the user types reaches the host", () => {
    const pty = makeFakePty();
    const xterm = openWindowsTerminal(makeHarness({ pty, ...WINDOWS_PWSH_SESSION }));

    xterm.resize(MOVED_SIZE);
    pty.emitData(CURSOR_POSITION_QUERY);
    pty.emitData(CURSOR_POSITION_QUERY);
    xterm.answerCursorQueries();
    expect(xterm.sent, 'the replies the renderer sent').toEqual([
      RECORDED_CURSOR_REPORT,
      RECORDED_CURSOR_REPORT,
    ]);
    const writtenBeforeTheKey = pty.writes.length;

    xterm.report(SHIFT_F3);

    expect(pty.writes.slice(writtenBeforeTheKey), 'the input written for the key').toEqual([
      SHIFT_F3,
    ]);
  });

  test.each([
    {
      unmatched: 'a late reply from an application',
      aroundTheMove: (pty: FakePty, xterm: XtermSide) => {
        pty.emitData(CURSOR_POSITION_QUERY);
        xterm.resize(MOVED_SIZE);
        xterm.answerCursorQueries();
      },
      bytes: RECORDED_CURSOR_REPORT,
    },
    {
      unmatched: 'a Shift+F3 typed after the move',
      aroundTheMove: (_pty: FakePty, xterm: XtermSide) => {
        xterm.resize(MOVED_SIZE);
        xterm.report(SHIFT_F3);
      },
      bytes: SHIFT_F3,
    },
  ])(
    "a lone reply that no console host query is waiting for ($unmatched) reaches the host, and the surplus reply to the host's retried query after the move is still withheld",
    ({ aroundTheMove, bytes }) => {
      const pty = makeFakePty();
      const xterm = openWindowsTerminal(makeHarness({ pty, ...WINDOWS_PWSH_SESSION }));

      aroundTheMove(pty, xterm);
      pty.emitData(CURSOR_POSITION_QUERY);
      pty.emitData(CURSOR_POSITION_QUERY);
      xterm.answerCursorQueries();

      expect(xterm.sent, 'the input the renderer sent').toEqual([
        bytes,
        RECORDED_CURSOR_REPORT,
        RECORDED_CURSOR_REPORT,
      ]);
      expect(pty.writes, 'the input written to the host').toEqual([bytes, RECORDED_CURSOR_REPORT]);
    },
  );

  test("a size change while the console host's query is unanswered still lets the reply reach the host, which then asks no more", () => {
    const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const { xterm } = startBundledConptySession(host);

    xterm.resize(MOVED_SIZE);
    xterm.type('W');
    host.shellReadsScreenBufferInfo();
    xterm.resize(SMOKE_SPAWN_SIZE);
    xterm.answerCursorQueries();
    expect(host.cursorReportsConsumed, 'the replies the host consumed').toEqual([
      { row: 13, column: 81 },
    ]);
    xterm.type(`${POST_MOVE_COMMAND.slice('W'.length)}\r`);
    host.shellReadsScreenBufferInfo();

    expect(host.cursorQueriesIssued).toBe(1);
    expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([POST_MOVE_COMMAND]);
  });

  test("after a retried sync whose second reply never came back, the console host's next post-resize query still gets its reply", () => {
    const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const { xterm } = startBundledConptySession(host);

    answerOnlyTheFirstRetriedQuery(host, xterm);
    xterm.resize(SMOKE_SPAWN_SIZE);
    host.shellReadsScreenBufferInfo();
    expect(host.cursorQueriesIssued).toBe(3);
    xterm.report(RECORDED_CURSOR_REPORT);
    xterm.type(`${POST_MOVE_COMMAND}\r`);

    expect(host.cursorReportsConsumed, 'the replies the host consumed').toEqual([
      { row: 13, column: 81 },
      { row: 13, column: 81 },
    ]);
    expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([POST_MOVE_COMMAND]);
  });

  test("a surplus reply that arrives only after the next move is withheld, and the console host's retried query after that move costs the shell no typed key either", () => {
    const host = createConptyCursorSyncHost(SMOKE_SPAWN_SIZE);
    const { xterm } = startBundledConptySession(host);

    xterm.resize(MOVED_SIZE);
    xterm.type('W');
    host.shellReadsScreenBufferInfo();
    host.cursorSyncWaitTimesOut();
    host.shellReadsScreenBufferInfo();
    xterm.report(RECORDED_CURSOR_REPORT);
    xterm.resize(SMOKE_SPAWN_SIZE);
    xterm.report(RECORDED_CURSOR_REPORT);
    xterm.type('r');
    host.shellReadsScreenBufferInfo();
    host.cursorSyncWaitTimesOut();
    host.shellReadsScreenBufferInfo();
    xterm.report(RECORDED_CURSOR_REPORT);
    xterm.report(RECORDED_CURSOR_REPORT);
    xterm.type(`${POST_MOVE_COMMAND.slice('Wr'.length)}\r`);

    expect(host.cursorQueriesIssued).toBe(4);
    expect(host.cursorReportsConsumed, 'the replies the host consumed').toEqual([
      { row: 13, column: 81 },
      { row: 13, column: 81 },
    ]);
    expect(host.linesAcceptedByShell, 'the command the shell ran').toEqual([POST_MOVE_COMMAND]);
    expect(host.keysReadByShell.join(''), 'the keys the shell read').toBe(`${POST_MOVE_COMMAND}\r`);
  });

  test("vim's probe, arriving between the first reply to the console host's retried query and the surplus one, still gets its reply while the surplus is withheld", () => {
    const pty = makeFakePty();
    const xterm = openWindowsTerminal(makeHarness({ pty, ...WINDOWS_PWSH_SESSION }));
    const [vimFirstProbe] = VIM_START_UP_PROBES;

    xterm.resize(MOVED_SIZE);
    pty.emitData(CURSOR_POSITION_QUERY);
    pty.emitData(CURSOR_POSITION_QUERY);
    xterm.report(RECORDED_CURSOR_REPORT);
    pty.emitData(vimFirstProbe.probe);
    xterm.report(RECORDED_CURSOR_REPORT);
    xterm.report(vimFirstProbe.reply);

    expect(pty.writes, 'the input written to the host').toEqual([
      RECORDED_CURSOR_REPORT,
      vimFirstProbe.reply,
    ]);
  });
});

describe("setupPtyHost — bytes that only resemble the console host's resize sync", () => {
  test.each([
    { input: 'Ctrl+Up', bytes: '\u001b[1;5A' },
    { input: 'Shift+F1', bytes: '\u001b[1;2P' },
    { input: 'the reply text without its escape', bytes: '[13;81R' },
  ])(
    'a key or text that only resembles a reply ($input) reaches the host while the surplus reply is outstanding, and the surplus reply is still withheld',
    ({ bytes }) => {
      const pty = makeFakePty();
      const xterm = openWindowsTerminal(makeHarness({ pty, ...WINDOWS_PWSH_SESSION }));

      xterm.resize(MOVED_SIZE);
      pty.emitData(CURSOR_POSITION_QUERY);
      pty.emitData(CURSOR_POSITION_QUERY);
      xterm.report(RECORDED_CURSOR_REPORT);
      xterm.report(bytes);
      expect(pty.writes, 'the input written before the surplus reply').toEqual([
        RECORDED_CURSOR_REPORT,
        bytes,
      ]);

      xterm.report(RECORDED_CURSOR_REPORT);

      expect(xterm.sent, 'the input the renderer sent').toEqual([
        RECORDED_CURSOR_REPORT,
        bytes,
        RECORDED_CURSOR_REPORT,
      ]);
      expect(pty.writes, 'the input written once the surplus reply arrived').toEqual([
        RECORDED_CURSOR_REPORT,
        bytes,
      ]);
    },
  );

  test("output with no cursor query in it, such as the echo of a key typed before the next move, does not let an earlier sync's surplus reply reach the host", () => {
    const pty = makeFakePty();
    const xterm = openWindowsTerminal(makeHarness({ pty, ...WINDOWS_PWSH_SESSION }));

    xterm.resize(MOVED_SIZE);
    pty.emitData(CURSOR_POSITION_QUERY);
    pty.emitData(CURSOR_POSITION_QUERY);
    xterm.report(RECORDED_CURSOR_REPORT);
    xterm.type('W');
    xterm.resize(SMOKE_SPAWN_SIZE);
    pty.emitData('W');
    xterm.report(RECORDED_CURSOR_REPORT);

    expect(xterm.sent, 'the input the renderer sent').toEqual([
      RECORDED_CURSOR_REPORT,
      'W',
      RECORDED_CURSOR_REPORT,
    ]);
    expect(pty.writes, 'the input written to the host').toEqual([RECORDED_CURSOR_REPORT, 'W']);
  });
});

describe('setupPtyHost — exit', () => {
  test('emits an exit message with exitCode and a null signal when none', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE({ ptyId: 'e1' }));
    pty.emitExit({ exitCode: 0, signal: undefined });
    expect(h.posted.at(-1)).toEqual({ type: 'exit', ptyId: 'e1', exitCode: 0, signal: null });
  });

  test('passes the signal through on a signal-killed exit (crash)', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE({ ptyId: 'e2' }));
    pty.emitExit({ exitCode: 0, signal: 9 });
    expect(h.posted.at(-1)).toEqual({ type: 'exit', ptyId: 'e2', exitCode: 0, signal: 9 });
  });

  test('forwards an undefined native exitCode for main-side normalization', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE({ ptyId: 'race' }));
    pty.emitExit({ exitCode: undefined });

    expect(h.posted.at(-1)).toEqual({
      type: 'exit',
      ptyId: 'race',
      exitCode: undefined,
      signal: null,
    });
  });

  test('a dead pty does not forward late data (active-id guard)', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE({ ptyId: 'g1' }));
    pty.emitExit({ exitCode: 0 });
    const before = h.posted.length;
    pty.emitData('straggler bytes');
    expect(h.posted.length).toBe(before);
  });
});

describe('setupPtyHost — Windows session that ends before its shell attached', () => {
  const WINDOWS_HOST = {
    platform: 'win32',
    env: { SystemRoot: 'C:\\Windows' },
    shellExists: () => false,
    pathProbe: () => null,
  } as const;
  const endings = (posted: PtyHostOutgoingMessage[]) =>
    posted.filter((message) => message.type === 'exit' || message.type === 'spawn-error');

  test('a pty that exits while still reporting pid 0 is reported as never started', () => {
    const pty = Object.assign(makeFakePty(), { pid: 0 });
    const h = makeHarness({ pty, ...WINDOWS_HOST });
    h.fire(CREATE({ ptyId: 'unattached', cwd: 'C:\\project' }));
    pty.emitExit({ exitCode: -1, signal: undefined });

    expect(endings(h.posted)).toEqual([
      { type: 'spawn-error', ptyId: 'unattached', shellNeverAttached: true, exitCode: -1 },
    ]);
  });

  test('a pty whose shell attached and then exited -1 without output is still a shell exit', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty, ...WINDOWS_HOST });
    h.fire(CREATE({ ptyId: 'attached', cwd: 'C:\\project' }));
    pty.emitExit({ exitCode: -1, signal: undefined });

    expect(endings(h.posted)).toEqual([
      { type: 'exit', ptyId: 'attached', exitCode: -1, signal: null },
    ]);
  });

  test('a never-attached pty that ends during shutdown still lets the host exit', () => {
    const pty = Object.assign(makeFakePty(), { pid: 0 });
    const exitHost = vi.fn();
    const h = makeHarness({ pty, exitHost, ...WINDOWS_HOST });
    h.fire(CREATE({ ptyId: 'unattached', cwd: 'C:\\project' }));
    h.fire({ type: 'shutdown' });
    expect(exitHost).not.toHaveBeenCalled();

    pty.emitExit({ exitCode: -1, signal: undefined });

    expect(exitHost).toHaveBeenCalledTimes(1);
    expect(exitHost).toHaveBeenCalledWith(0);
  });
});

describe('setupPtyHost — containment (AC5: host survives a PTY failure)', () => {
  test.each([
    'Cannot find conpty.dll beside conpty.node',
    'Failed to get conpty.node module handle: 126',
    'Failed to get conpty.node module file name: 126',
    'Failed to load conpty.dll: bad image',
  ])('retries deterministic loader failure %s once with the OS backend', (loaderError) => {
    const pty = makeFakePty();
    const calls: PtySpawnOptions[] = [];
    const warnings: Record<string, unknown>[] = [];
    const spawn: SpawnPty = (_file, _args, options) => {
      calls.push(options);
      if (calls.length === 1) throw new Error(loaderError);
      return pty;
    };
    const h = makeHarness({
      spawn,
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows' },
      shellExists: () => false,
      pathProbe: () => null,
      logger: { warn: (event) => warnings.push(event) },
    });
    h.fire(CREATE({ cwd: 'C:\\project' }));

    expect(calls.map((options) => options.useConptyDll)).toEqual([true, false]);
    expect(warnings).toContainEqual(
      expect.objectContaining({ event: 'pty-host-conpty-dll-fallback' }),
    );
    pty.emitData('fallback alive');
    expect(h.posted).toContainEqual({ type: 'data', ptyId: 'p1', data: 'fallback alive' });
  });

  test('does not retry a non-loader Windows spawn failure', () => {
    const calls: PtySpawnOptions[] = [];
    const spawn: SpawnPty = (_file, _args, options) => {
      calls.push(options);
      throw new Error('EMFILE: too many open files');
    };
    const h = makeHarness({
      spawn,
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows' },
      shellExists: () => false,
      pathProbe: () => null,
    });
    h.fire(CREATE({ cwd: 'C:\\project' }));

    expect(calls).toHaveLength(1);
    expect(h.posted.at(-1)).toEqual({
      type: 'spawn-error',
      ptyId: 'p1',
      message: 'EMFILE: too many open files',
    });
  });

  test('contains a failed OS-backend retry as the existing spawn-error contract', () => {
    let calls = 0;
    const spawn: SpawnPty = () => {
      calls += 1;
      if (calls === 1) throw new Error('Cannot find conpty.dll beside conpty.node');
      throw new Error('CreatePseudoConsole failed');
    };
    const h = makeHarness({
      spawn,
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows' },
      shellExists: () => false,
      pathProbe: () => null,
    });
    h.fire(CREATE({ cwd: 'C:\\project' }));

    expect(calls).toBe(2);
    expect(h.posted.at(-1)).toEqual({
      type: 'spawn-error',
      ptyId: 'p1',
      message: 'CreatePseudoConsole failed',
    });
  });

  test('a synchronous spawn throw surfaces as spawn-error, not a crash', () => {
    const spawn: SpawnPty = () => {
      throw Object.assign(new Error('EMFILE: too many open files'), { code: 'EMFILE' });
    };
    const h = makeHarness({ spawn });
    expect(() => h.fire(CREATE())).not.toThrow();
    expect(h.posted).toEqual([
      { type: 'spawn-error', ptyId: 'p1', message: 'EMFILE: too many open files' },
    ]);
  });

  test('a non-Error spawn throw still surfaces a string spawn-error message', () => {
    const spawn: SpawnPty = () => {
      throw 'EMFILE: too many open files';
    };
    const h = makeHarness({ spawn });
    h.fire(CREATE());
    expect(h.posted).toEqual([
      { type: 'spawn-error', ptyId: 'p1', message: 'EMFILE: too many open files' },
    ]);
  });

  test('the host keeps routing after a spawn failure', () => {
    const goodPty = makeFakePty();
    let calls = 0;
    const spawn: SpawnPty = () => {
      calls += 1;
      if (calls === 1) throw new Error('spawn blew up');
      return goodPty;
    };
    const h = makeHarness({ spawn });
    h.fire(CREATE({ ptyId: 'bad' }));
    h.fire(CREATE({ ptyId: 'good' }));
    goodPty.emitData('alive');
    expect(h.posted).toContainEqual({ type: 'data', ptyId: 'good', data: 'alive' });
  });

  test('swallows an ESRCH from killing an already-exited pty', () => {
    const pty = makeFakePty();
    pty.killThrows = true;
    const h = makeHarness({ pty });
    h.fire(CREATE());
    expect(() => h.fire({ type: 'kill', ptyId: 'p1' })).not.toThrow();
    expect(pty.killCount).toBe(1);
  });
});

describe('setupPtyHost — addressing', () => {
  test('ignores input/resize/kill/pause/resume for an unknown ptyId', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE({ ptyId: 'real' }));
    h.fire({ type: 'input', ptyId: 'ghost', data: 'x' });
    h.fire({ type: 'resize', ptyId: 'ghost', cols: 1, rows: 1 });
    h.fire({ type: 'kill', ptyId: 'ghost' });
    h.fire({ type: 'pause', ptyId: 'ghost' });
    h.fire({ type: 'resume', ptyId: 'ghost' });
    expect(pty.writes).toEqual([]);
    expect(pty.resizes).toEqual([]);
    expect(pty.killCount).toBe(0);
    expect(pty.pauseCount).toBe(0);
    expect(pty.resumeCount).toBe(0);
  });

  test('killActive reaps the live pty (window-close / quit)', () => {
    const pty = makeFakePty();
    const h = makeHarness({ pty });
    h.fire(CREATE());
    h.handle.killActive();
    expect(pty.killCount).toBe(1);
    h.handle.killActive();
    expect(pty.killCount).toBe(1);
  });

  test('a create reusing a live ptyId reaps the stale shell before replacing it (no orphan)', () => {
    const first = makeFakePty();
    const second = makeFakePty();
    const ptys = [first, second];
    let n = 0;
    const spawn: SpawnPty = () => ptys[n++] ?? makeFakePty();
    const h = makeHarness({ spawn });

    h.fire(CREATE({ ptyId: 'dup' }));
    expect(first.killCount).toBe(0);
    h.fire(CREATE({ ptyId: 'dup' }));
    expect(first.killCount).toBe(1);

    second.emitData('alive');
    expect(h.posted).toContainEqual({ type: 'data', ptyId: 'dup', data: 'alive' });
    const before = h.posted.length;
    first.emitData('orphan');
    expect(h.posted.length).toBe(before);
  });
});

describe('setupPtyHost — concurrent sessions', () => {
  function makeMultiHarness(ptys: FakePty[]): Harness {
    let n = 0;
    const spawn: SpawnPty = () => ptys[n++] ?? makeFakePty();
    return makeHarness({ spawn });
  }

  test('a second create with a new id adds a session and leaves the first running', () => {
    const a = makeFakePty();
    const b = makeFakePty();
    const h = makeMultiHarness([a, b]);
    h.fire(CREATE({ ptyId: 'a' }));
    h.fire(CREATE({ ptyId: 'b' }));
    expect(a.killCount).toBe(0);
    expect(b.killCount).toBe(0);
    a.emitData('a-still-here');
    expect(h.posted).toContainEqual({ type: 'data', ptyId: 'a', data: 'a-still-here' });
  });

  test('both sessions stream concurrently, each tagged with its own ptyId', () => {
    const a = makeFakePty();
    const b = makeFakePty();
    const h = makeMultiHarness([a, b]);
    h.fire(CREATE({ ptyId: 'a' }));
    h.fire(CREATE({ ptyId: 'b' }));
    a.emitData('from-a');
    b.emitData('from-b');
    expect(h.posted).toContainEqual({ type: 'data', ptyId: 'a', data: 'from-a' });
    expect(h.posted).toContainEqual({ type: 'data', ptyId: 'b', data: 'from-b' });
  });

  test('input/resize/kill/pause/resume each act only on the addressed session', () => {
    const a = makeFakePty();
    const b = makeFakePty();
    const h = makeMultiHarness([a, b]);
    h.fire(CREATE({ ptyId: 'a' }));
    h.fire(CREATE({ ptyId: 'b' }));

    h.fire({ type: 'input', ptyId: 'a', data: 'ls\r' });
    h.fire({ type: 'resize', ptyId: 'b', cols: 100, rows: 30 });
    h.fire({ type: 'pause', ptyId: 'a' });
    h.fire({ type: 'resume', ptyId: 'b' });
    h.fire({ type: 'kill', ptyId: 'a' });

    expect(a.writes).toEqual(['ls\r']);
    expect(b.writes).toEqual([]);
    expect(b.resizes).toEqual([[100, 30]]);
    expect(a.resizes).toEqual([]);
    expect(a.pauseCount).toBe(1);
    expect(b.pauseCount).toBe(0);
    expect(b.resumeCount).toBe(1);
    expect(a.resumeCount).toBe(0);
    expect(a.killCount).toBe(1);
    expect(b.killCount).toBe(0);
  });

  test('one session exiting removes only its entry and leaves the other running', () => {
    const a = makeFakePty();
    const b = makeFakePty();
    const h = makeMultiHarness([a, b]);
    h.fire(CREATE({ ptyId: 'a' }));
    h.fire(CREATE({ ptyId: 'b' }));

    a.emitExit({ exitCode: 0 });
    expect(h.posted).toContainEqual({ type: 'exit', ptyId: 'a', exitCode: 0, signal: null });

    const before = h.posted.length;
    a.emitData('straggler');
    expect(h.posted.length).toBe(before);
    b.emitData('still-alive');
    expect(h.posted).toContainEqual({ type: 'data', ptyId: 'b', data: 'still-alive' });

    h.fire({ type: 'input', ptyId: 'b', data: 'x' });
    expect(b.writes).toEqual(['x']);
  });

  test('killActive reaps every session in the map (window/quit reap)', () => {
    const a = makeFakePty();
    const b = makeFakePty();
    const c = makeFakePty();
    const h = makeMultiHarness([a, b, c]);
    h.fire(CREATE({ ptyId: 'a' }));
    h.fire(CREATE({ ptyId: 'b' }));
    h.fire(CREATE({ ptyId: 'c' }));

    h.handle.killActive();
    expect(a.killCount).toBe(1);
    expect(b.killCount).toBe(1);
    expect(c.killCount).toBe(1);

    h.handle.killActive();
    expect(a.killCount).toBe(1);
    expect(b.killCount).toBe(1);
    expect(c.killCount).toBe(1);
  });

  test('killActive keeps reaping after one session throws ESRCH (already exited)', () => {
    const a = makeFakePty();
    a.killThrows = true;
    const b = makeFakePty();
    const h = makeMultiHarness([a, b]);
    h.fire(CREATE({ ptyId: 'a' }));
    h.fire(CREATE({ ptyId: 'b' }));
    expect(() => h.handle.killActive()).not.toThrow();
    expect(a.killCount).toBe(1);
    expect(b.killCount).toBe(1);
  });

  test('an internal shutdown message reaps every session and exits once', () => {
    const a = makeFakePty();
    const b = makeFakePty();
    const ptys = [a, b];
    const exitCodes: number[] = [];
    let flushCount = 0;
    let n = 0;
    const h = makeHarness({
      spawn: () => ptys[n++] ?? makeFakePty(),
      exitHost: (code) => exitCodes.push(code),
      flushLogger: () => {
        flushCount += 1;
      },
    });
    h.fire(CREATE({ ptyId: 'a' }));
    h.fire(CREATE({ ptyId: 'b' }));

    h.fireRaw({ type: 'shutdown' });
    expect(a.killCount).toBe(1);
    expect(b.killCount).toBe(1);
    expect(exitCodes).toEqual([]);

    a.emitExit({ exitCode: 0 });
    expect(exitCodes).toEqual([]);
    b.emitExit({ exitCode: 0 });
    expect(exitCodes).toEqual([0]);
    expect(flushCount).toBe(1);

    h.fireRaw({ type: 'shutdown' });
    expect(a.killCount).toBe(1);
    expect(b.killCount).toBe(1);
    expect(exitCodes).toEqual([0]);
    expect(flushCount).toBe(1);
  });

  test('shutdown exits on the host-local deadline when a deferred Windows kill never exits', async () => {
    const pty = makeFakePty();
    const exitCodes: number[] = [];
    const warnings: Record<string, unknown>[] = [];
    const h = makeHarness({
      pty,
      shutdownMs: 1,
      exitHost: (code) => exitCodes.push(code),
      logger: { warn: (event) => warnings.push(event) },
    });
    h.fire(CREATE());

    h.fireRaw({ type: 'shutdown' });
    await new Promise((resolve) => setTimeout(resolve, 10));

    expect(pty.killCount).toBe(1);
    expect(exitCodes).toEqual([0]);
    expect(warnings).toContainEqual({ event: 'pty-host-shutdown-deadline', remaining: 1 });
  });
});

describe('setupPtyHost — incoming message validation (asIncomingMessage guard)', () => {
  function makeLogger() {
    const warnings: Array<Record<string, unknown>> = [];
    return { warn: (o: Record<string, unknown>) => warnings.push(o), warnings };
  }

  test('drops a message with a missing ptyId (no spawn, warns) so it cannot defeat the active-id guard', () => {
    const logger = makeLogger();
    const h = makeHarness({ logger });
    h.fireRaw({ type: 'create', cwd: '/x', cols: 80, rows: 24 });
    expect(h.spawnCalls).toHaveLength(0);
    expect(logger.warnings.length).toBeGreaterThan(0);
  });

  test('drops a message with an empty-string ptyId', () => {
    const logger = makeLogger();
    const h = makeHarness({ logger });
    h.fireRaw({ type: 'input', ptyId: '', data: 'x' });
    expect(logger.warnings.length).toBeGreaterThan(0);
  });

  test('a null or non-object message does not throw and is dropped', () => {
    const logger = makeLogger();
    const h = makeHarness({ logger });
    expect(() => h.fireRaw(null)).not.toThrow();
    expect(() => h.fireRaw('garbage')).not.toThrow();
    expect(h.spawnCalls).toHaveLength(0);
    expect(logger.warnings.length).toBeGreaterThan(0);
  });

  test('accepts a create with a string launchCommand and bakes it', () => {
    const h = makeHarness();
    h.fireRaw({
      type: 'create',
      ptyId: 'p1',
      cwd: '/x',
      cols: 80,
      rows: 24,
      launchCommand: "x 'y'",
    });
    expect(h.spawnCalls).toHaveLength(1);
    const [managedBinDir] = buildShellEnv({}, { platform: 'darwin' }).managedBinDirs;
    expect(managedBinDir).toBeDefined();
    expect(h.spawnCalls[0]?.args).toEqual([
      '-l',
      '-i',
      '-c',
      `case ":$PATH:" in *:'${managedBinDir}':*) ;; *) PATH='${managedBinDir}'"\${PATH:+:$PATH}" ;; esac; export PATH; x 'y'; exec '/bin/zsh' -l -i`,
    ]);
  });

  test('accepts a structured POSIX launch, quotes its argv and hands its env to the login alone', () => {
    const h = makeHarness();
    h.fireRaw({
      type: 'create',
      ptyId: 'p1',
      cwd: '/x',
      cols: 80,
      rows: 24,
      launchCommand: {
        executable: '/rt/bin/npx',
        args: ['-y', '@augmentcode/[email protected]', '--acp', 'login'],
        env: { AUGGIE_LOGIN_FLOW: 'terminal' },
        pathPrepend: ['/rt/bin'],
      },
    });
    expect(h.spawnCalls).toHaveLength(1);
    const [managedBinDir] = buildShellEnv({}, { platform: 'darwin' }).managedBinDirs;
    expect(h.spawnCalls[0]?.args).toEqual([
      '-l',
      '-i',
      '-c',
      `case ":$PATH:" in *:'${managedBinDir}':*) ;; *) PATH='${managedBinDir}'"\${PATH:+:$PATH}" ;; esac; case ":$PATH:" in *:'/rt/bin':*) ;; *) PATH='/rt/bin'"\${PATH:+:$PATH}" ;; esac; export PATH; (export AUGGIE_LOGIN_FLOW="$OK_TERMINAL_LAUNCH_ENV_0"; exec '/rt/bin/npx' '-y' '@augmentcode/[email protected]' '--acp' 'login'); unset OK_TERMINAL_LAUNCH_ENV_0; exec '/bin/zsh' -l -i`,
    ]);
    expect(h.spawnCalls[0]?.options.env?.OK_TERMINAL_LAUNCH_ENV_0).toBe('terminal');
    expect(h.spawnCalls[0]?.options.env).not.toHaveProperty('AUGGIE_LOGIN_FLOW');
    expect(h.spawnCalls[0]?.args).not.toContain('terminal');
    expect(h.spawnCalls[0]?.options.env?.PATH).not.toContain('/rt/bin');
  });

  test('drops a structured launch whose env names, values or PATH dirs are malformed', () => {
    const h = makeHarness();
    h.fireRaw({
      type: 'create',
      ptyId: 'p1',
      cwd: '/x',
      cols: 80,
      rows: 24,
      launchCommand: { executable: 'agent', args: ['login'], env: { A: 1 } },
    });
    h.fireRaw({
      type: 'create',
      ptyId: 'p3',
      cwd: '/x',
      cols: 80,
      rows: 24,
      launchCommand: { executable: 'agent', args: ['login'], env: { '--split-string': 'x' } },
    });
    h.fireRaw({
      type: 'create',
      ptyId: 'p5',
      cwd: '/x',
      cols: 80,
      rows: 24,
      launchCommand: {
        executable: 'agent',
        args: ['login'],
        env: { OK_TERMINAL_LAUNCH_ENV_0: 'the slot the launch itself uses' },
      },
    });
    h.fireRaw({
      type: 'create',
      ptyId: 'p4',
      cwd: '/x',
      cols: 80,
      rows: 24,
      launchCommand: {
        executable: 'agent',
        args: ['login'],
        env: { OK: `a${String.fromCharCode(0)}b` },
      },
    });
    h.fireRaw({
      type: 'create',
      ptyId: 'p2',
      cwd: '/x',
      cols: 80,
      rows: 24,
      launchCommand: { executable: 'agent', args: ['login'], pathPrepend: [''] },
    });
    expect(h.spawnCalls).toHaveLength(0);
  });

  test('accepts a structured Windows launch and composes it after shell resolution', () => {
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows', ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
      shellExists: () => false,
      pathProbe: () => null,
      listDirectory: () => [],
    });
    h.fireRaw({
      type: 'create',
      ptyId: 'p1',
      cwd: 'C:\\project',
      cols: 80,
      rows: 24,
      launchCommand: { executable: 'claude', args: [] },
    });
    expect(h.spawnCalls).toHaveLength(1);
    expect(h.spawnCalls[0]?.args).toBe('/K claude');
  });

  test('materializes Claude settings beneath the cwd before composing a cmd-safe launch', () => {
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows', ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
      shellExists: () => false,
      pathProbe: () => null,
      listDirectory: () => [],
    });
    const supportFile = {
      kind: 'claude-settings' as const,
      relativePath: '.ok/local/terminal/claude-settings-mcp-tools.json',
      contents: '{"enabledMcpjsonServers":["open-knowledge"]}',
    };
    h.fireRaw({
      type: 'create',
      ptyId: 'p1',
      cwd: 'C:\\project',
      cols: 80,
      rows: 24,
      launchCommand: {
        executable: 'claude',
        args: ['--settings', supportFile.relativePath],
        supportFile,
      },
    });

    expect(h.materializedSupportFiles).toEqual([{ cwd: 'C:\\project', file: supportFile }]);
    expect(h.spawnCalls[0]?.args).toBe(
      '/K claude --settings .ok/local/terminal/claude-settings-mcp-tools.json',
    );
  });

  test('opens a bare Claude launch when the settings support file cannot be written', () => {
    const logger = makeLogger();
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows', ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
      shellExists: () => false,
      pathProbe: () => null,
      listDirectory: () => [],
      logger,
      materializeSupportFile: () => {
        throw Object.assign(new Error('EROFS: read-only file system'), { code: 'EROFS' });
      },
    });
    h.fireRaw({
      type: 'create',
      ptyId: 'p1',
      cwd: 'C:\\project',
      cols: 80,
      rows: 24,
      launchCommand: {
        executable: 'claude',
        args: ['--settings', '.ok/local/terminal/claude-settings-mcp-tools.json'],
        supportFile: {
          kind: 'claude-settings',
          relativePath: '.ok/local/terminal/claude-settings-mcp-tools.json',
          contents: '{"enabledMcpjsonServers":["open-knowledge"]}',
        },
      },
    });

    expect(h.posted.filter((m) => m.type === 'spawn-error')).toHaveLength(0);
    expect(h.spawnCalls).toHaveLength(1);
    expect(h.spawnCalls[0]?.args).toBe('/K claude');
    expect(
      logger.warnings.some((w) => w.event === 'pty-host-support-file-materialize-failed'),
    ).toBe(true);
    expect(h.posted).toContainEqual({
      type: 'shell-notice',
      ptyId: 'p1',
      notice: 'support-file-degraded',
      reason: 'write-failed',
    });
  });

  test('rejects a support-file path outside the owned terminal settings directory', () => {
    const logger = makeLogger();
    const h = makeHarness({ logger });
    h.fireRaw({
      type: 'create',
      ptyId: 'p1',
      cwd: '/x',
      cols: 80,
      rows: 24,
      launchCommand: {
        executable: 'claude',
        args: ['--settings', '../../settings.json'],
        supportFile: {
          kind: 'claude-settings',
          relativePath: '../../settings.json',
          contents: '{}',
        },
      },
    });

    expect(h.spawnCalls).toHaveLength(0);
    expect(h.materializedSupportFiles).toHaveLength(0);
    expect(logger.warnings.length).toBeGreaterThan(0);
  });

  test('drops a create whose launchCommand has neither supported shape', () => {
    const logger = makeLogger();
    const h = makeHarness({ logger });
    h.fireRaw({ type: 'create', ptyId: 'p1', cwd: '/x', cols: 80, rows: 24, launchCommand: 123 });
    expect(h.spawnCalls).toHaveLength(0);
    expect(logger.warnings.length).toBeGreaterThan(0);
  });

  test('an unknown message type lands in the default warn branch (forward-compat)', () => {
    const logger = makeLogger();
    const h = makeHarness({ logger });
    h.fireRaw({ type: 'bogus-future-type', ptyId: 'p1' });
    expect(h.spawnCalls).toHaveLength(0);
    expect(logger.warnings.length).toBeGreaterThan(0);
  });

  test.each([...TERMINAL_SHELL_NOTICE_REASONS])(
    'accepts a create carrying the shared reason %s and relays it verbatim',
    (reason) => {
      const h = makeHarness({
        platform: 'win32',
        env: { SystemRoot: 'C:\\Windows' },
        shellExists: () => false,
        pathProbe: () => null,
        listDirectory: () => [],
      });

      h.fireRaw({
        type: 'create',
        ptyId: 'p1',
        cwd: 'C:\\project',
        cols: 80,
        rows: 24,
        shellInvalidReason: reason,
      });

      expect(h.spawnCalls).toHaveLength(1);
      expect(h.posted).toContainEqual({
        type: 'shell-notice',
        ptyId: 'p1',
        notice: 'invalid-shell-override',
        reason,
      });
    },
  );

  test('drops a create whose shellInvalidReason is outside the shared reason set', () => {
    const logger = makeLogger();
    const h = makeHarness({ logger });
    h.fireRaw({
      type: 'create',
      ptyId: 'p1',
      cwd: '/x',
      cols: 80,
      rows: 24,
      shellInvalidReason: 'config-unreadable-ish',
    });
    expect(h.spawnCalls).toHaveLength(0);
    expect(logger.warnings.length).toBeGreaterThan(0);
  });
});

describe('buildShellArgs', () => {
  test('a plain tab follows the platform interactive-shell convention', () => {
    expect(buildShellArgs('darwin', '/bin/zsh', undefined, [])).toEqual(['-l', '-i']);
    expect(buildShellArgs('darwin', '/bin/zsh', '', [])).toEqual(['-l', '-i']);
    expect(buildShellArgs('linux', '/bin/bash', undefined, [])).toEqual(['-i']);
    expect(buildShellArgs('linux', '/bin/bash', '', [])).toEqual(['-i']);
  });

  test('a macOS launch keeps login flags in the launcher and exec tail', () => {
    expect(buildShellArgs('darwin', '/bin/zsh', "codex 'hi'", [])).toEqual([
      '-l',
      '-i',
      '-c',
      "codex 'hi'; exec '/bin/zsh' -l -i",
    ]);
  });

  test('a Linux launch is interactive without forcing login semantics', () => {
    expect(buildShellArgs('linux', '/bin/bash', "codex 'hi'", [])).toEqual([
      '-i',
      '-c',
      "codex 'hi'; exec '/bin/bash' -i",
    ]);
  });

  test('reasserts the managed bin dir in the launched CLI command on macOS', () => {
    expect(buildShellArgs('darwin', '/bin/zsh', "codex 'hi'", ['/managed/bin'])).toEqual([
      '-l',
      '-i',
      '-c',
      // biome-ignore lint/suspicious/noTemplateCurlyInString: shell parameter expansion in an expected command string, not a JS template placeholder
      "case \":$PATH:\" in *:'/managed/bin':*) ;; *) PATH='/managed/bin'\"${PATH:+:$PATH}\" ;; esac; export PATH; codex 'hi'; exec '/bin/zsh' -l -i",
    ]);
  });

  test('reasserts the managed bin dir in the launched CLI command on Linux', () => {
    expect(buildShellArgs('linux', '/bin/bash', 'claude', ['/managed/bin'])).toEqual([
      '-i',
      '-c',
      // biome-ignore lint/suspicious/noTemplateCurlyInString: shell parameter expansion in an expected command string, not a JS template placeholder
      "case \":$PATH:\" in *:'/managed/bin':*) ;; *) PATH='/managed/bin'\"${PATH:+:$PATH}\" ;; esac; export PATH; claude; exec '/bin/bash' -i",
    ]);
  });

  test('a structured POSIX launch reasserts its own dirs ahead of the managed ones', () => {
    expect(
      buildShellArgs(
        'linux',
        '/bin/bash',
        { executable: '/rt/bin/npx', args: ['-y', 'pkg@1', 'login'], pathPrepend: ['/rt/bin'] },
        ['/managed/bin'],
      ),
    ).toEqual([
      '-i',
      '-c',
      // biome-ignore lint/suspicious/noTemplateCurlyInString: shell parameter expansion in an expected command string, not a JS template placeholder
      "case \":$PATH:\" in *:'/managed/bin':*) ;; *) PATH='/managed/bin'\"${PATH:+:$PATH}\" ;; esac; case \":$PATH:\" in *:'/rt/bin':*) ;; *) PATH='/rt/bin'\"${PATH:+:$PATH}\" ;; esac; export PATH; '/rt/bin/npx' '-y' 'pkg@1' 'login'; exec '/bin/bash' -i",
    ]);
  });

  test('several env values map each slot onto the same name in the script and in the spawn env', () => {
    const h = makeHarness();
    const env = { ZDOTDIR: '/agent/zdot', AUGGIE_HOME: '/agent/home' };
    h.fireRaw({
      type: 'create',
      ptyId: 'p1',
      cwd: '/x',
      cols: 80,
      rows: 24,
      launchCommand: { executable: 'agent', args: ['login'], env },
    });
    const call = h.spawnCalls[0];
    if (!call) throw new Error('no spawn');
    const script = call.args[3] ?? '';
    expect(script).toContain(
      `(export ZDOTDIR="$OK_TERMINAL_LAUNCH_ENV_0" AUGGIE_HOME="$OK_TERMINAL_LAUNCH_ENV_1"; exec agent 'login'); unset OK_TERMINAL_LAUNCH_ENV_0 OK_TERMINAL_LAUNCH_ENV_1; exec`,
    );
    const pairs = [...script.matchAll(/(\w+)="\$(OK_TERMINAL_LAUNCH_ENV_\d+)"/g)].map((match) => [
      match[1] ?? '',
      match[2] ?? '',
    ]);
    expect(pairs).toEqual([
      ['ZDOTDIR', 'OK_TERMINAL_LAUNCH_ENV_0'],
      ['AUGGIE_HOME', 'OK_TERMINAL_LAUNCH_ENV_1'],
    ]);
    for (const [name, slot] of pairs) {
      expect(call.options.env?.[slot]).toBe(env[name as keyof typeof env]);
      expect(call.options.env).not.toHaveProperty(name);
    }
  });

  test('a structured launch under fish uses fish quoting for every argument', () => {
    expect(
      buildShellArgs(
        'linux',
        '/usr/bin/fish',
        { executable: 'agent', args: ["it\\'s", 'trailing\\'], env: { A: "x'y" } },
        [],
      ),
    ).toEqual([
      '-i',
      '-c',
      `begin; set -lx A "$OK_TERMINAL_LAUNCH_ENV_0"; agent 'it\\\\\\'s' 'trailing\\\\'; end; set -e OK_TERMINAL_LAUNCH_ENV_0; exec '/usr/bin/fish' -i`,
    ]);
  });

  test('a structured launch leaves a bare command name unquoted so shell aliases still resolve', () => {
    expect(
      buildShellArgs(
        'darwin',
        '/bin/zsh',
        { executable: 'claude', args: ['--settings', '{}'] },
        [],
      ),
    ).toEqual(['-l', '-i', '-c', "claude '--settings' '{}'; exec '/bin/zsh' -l -i"]);
  });

  test('a structured launch quotes an executable that is a path or carries shell syntax', () => {
    for (const executable of ['/opt/my tools/claude', '$(touch pwned)', '-claude', 'a;b']) {
      const script = buildShellArgs('darwin', '/bin/zsh', { executable, args: [] }, [])[3];
      expect(script).toBe(`${shellSingleQuote(executable)}; exec '/bin/zsh' -l -i`);
    }
    expect(buildShellArgs('linux', '/usr/bin/fish', { executable: "o'k\\", args: [] }, [])[2]).toBe(
      "'o\\'k\\\\'; exec '/usr/bin/fish' -i",
    );
  });

  test('uses fish list syntax for the reassert when the terminal shell is fish', () => {
    expect(buildShellArgs('linux', '/usr/bin/fish', 'claude', ['/managed/bin'])).toEqual([
      '-i',
      '-c',
      "if not contains '/managed/bin' $PATH; set -gx PATH '/managed/bin' $PATH; end; claude; exec '/usr/bin/fish' -i",
    ]);
  });

  test('a host with no grantable managed dir composes exactly the pre-reassert argv', () => {
    expect(buildShellArgs('darwin', '/bin/zsh', "codex 'hi'", [])).toEqual([
      '-l',
      '-i',
      '-c',
      "codex 'hi'; exec '/bin/zsh' -l -i",
    ]);
  });

  test('a plain interactive tab is never reasserted, so typed commands keep the user PATH order', () => {
    expect(buildShellArgs('darwin', '/bin/zsh', undefined, ['/managed/bin'])).toEqual(['-l', '-i']);
    expect(buildShellArgs('linux', '/bin/bash', undefined, ['/managed/bin'])).toEqual(['-i']);
  });

  test('single-quotes the shell path in the exec tail (space/quote-safe)', () => {
    expect(buildShellArgs('linux', "/odd path/o'sh", "claude 'x'", [])).toEqual([
      '-i',
      '-c',
      "claude 'x'; exec '/odd path/o'\\''sh' -i",
    ]);
    expect(buildShellArgs('darwin', "/odd path/o'sh", "claude 'x'", [])).toEqual([
      '-l',
      '-i',
      '-c',
      "claude 'x'; exec '/odd path/o'\\''sh' -l -i",
    ]);
  });
});

describe('buildShellEnv', () => {
  test('strips markers, drops undefined, preserves the rest, marks the desktop terminal', () => {
    const { env } = buildShellEnv({
      PATH: '/usr/bin',
      HOME: '/Users/x',
      OK_ELECTRON_PROTOCOL_HOST: '1',
      OK_LOCK_KIND: 'interactive',
      ELECTRON_RUN_AS_NODE: '1',
      GDK_PIXBUF_MODULEDIR: '/app/lib/gdk-pixbuf',
      GDK_PIXBUF_MODULE_FILE: '/app/lib/loaders.cache',
      ELECTRON_TRASH: 'gio',
      GDK_THEME: 'Adwaita',
      MAYBE: undefined,
    });
    expect(env).toEqual({
      PATH: '/Users/x/.ok/bin:/usr/bin',
      HOME: '/Users/x',
      ELECTRON_TRASH: 'gio',
      GDK_THEME: 'Adwaita',
      [OK_DESKTOP_TERMINAL_ENV]: '1',
    });
  });

  test('win32 prepends the packaged CLI bin using the inherited PATH key casing', () => {
    const { env } = buildShellEnv(
      {
        Path: 'C:\\Windows\\System32;C:\\Tools',
        HOME: 'C:\\Users\\alice',
      },
      { platform: 'win32', cliBinDir: 'C:\\Program Files\\Open Knowledge\\resources\\cli\\bin' },
    );

    expect(env.Path).toBe(
      'C:\\Program Files\\Open Knowledge\\resources\\cli\\bin;C:\\Windows\\System32;C:\\Tools',
    );
    expect(env.PATH).toBeUndefined();
    expect(env.Path).not.toContain('.ok\\bin');
  });
});

describe('resolveShell', () => {
  const shellExists = (paths: string[]) => (path: string) => paths.includes(path);

  test('macOS preserves override, $SHELL, and zsh fallback behavior', () => {
    expect(
      resolveShell({ SHELL: '/bin/bash' }, { platform: 'darwin', override: '/usr/bin/fish' }),
    ).toBe('/usr/bin/fish');
    expect(resolveShell({ SHELL: '/bin/bash' }, { platform: 'darwin' })).toBe('/bin/bash');
    expect(resolveShell({}, { platform: 'darwin' })).toBe('/bin/zsh');
    expect(resolveShell({ SHELL: '' }, { platform: 'darwin' })).toBe('/bin/zsh');
  });

  test('Linux prefers $SHELL, then the passwd shell', () => {
    expect(
      resolveShell(
        { SHELL: '/usr/bin/fish' },
        {
          platform: 'linux',
          userInfoShell: () => '/bin/zsh',
          shellExists: shellExists(['/usr/bin/fish', '/bin/zsh']),
        },
      ),
    ).toBe('/usr/bin/fish');
    expect(
      resolveShell(
        { SHELL: '' },
        {
          platform: 'linux',
          userInfoShell: () => '/bin/zsh',
          shellExists: shellExists(['/bin/zsh']),
        },
      ),
    ).toBe('/bin/zsh');
  });

  test('Linux treats false-style and nonexistent configured shells as unset', () => {
    for (const configuredShell of [
      '/bin/false',
      '/usr/bin/false',
      '/usr/sbin/nologin',
      '/missing',
    ]) {
      expect(
        resolveShell(
          { SHELL: configuredShell },
          {
            platform: 'linux',
            userInfoShell: () => '/bin/fish',
            shellExists: shellExists(['/bin/fish']),
          },
        ),
      ).toBe('/bin/fish');
    }
  });

  test('Linux falls back through bash to sh when passwd lookup is absent', () => {
    expect(
      resolveShell(
        {},
        {
          platform: 'linux',
          userInfoShell: () => null,
          shellExists: shellExists(['/bin/bash', '/bin/sh']),
        },
      ),
    ).toBe('/bin/bash');
    expect(
      resolveShell(
        {},
        {
          platform: 'linux',
          userInfoShell: () => null,
          shellExists: shellExists(['/bin/sh']),
        },
      ),
    ).toBe('/bin/sh');
  });

  test('Linux logs and falls back when passwd lookup throws', () => {
    const warnings: Record<string, unknown>[] = [];

    expect(
      resolveShell(
        {},
        {
          platform: 'linux',
          userInfoShell: () => {
            throw Object.assign(new Error('no passwd entry'), { code: 'ENOENT' });
          },
          shellExists: shellExists(['/bin/bash', '/bin/sh']),
          logger: { warn: (data) => warnings.push(data) },
        },
      ),
    ).toBe('/bin/bash');
    expect(warnings).toContainEqual({
      event: 'pty-host-user-info-shell-failed',
      code: 'ENOENT',
    });
  });

  test('Linux ignores a false-style passwd shell before falling back', () => {
    expect(
      resolveShell(
        {},
        {
          platform: 'linux',
          userInfoShell: () => '/bin/false',
          shellExists: shellExists(['/bin/false', '/bin/bash', '/bin/sh']),
        },
      ),
    ).toBe('/bin/bash');
  });

  describe('win32 ladder', () => {
    const programFilesPwsh = 'C:\\Program Files\\PowerShell\\7\\pwsh.exe';
    const windowsPowerShell = 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe';
    const cmd = 'C:\\Windows\\System32\\cmd.exe';
    const baseEnv = {
      ProgramFiles: 'C:\\Program Files',
      SystemRoot: 'C:\\Windows',
      LOCALAPPDATA: 'C:\\Users\\alice\\AppData\\Local',
      PATH: 'C:\\Windows\\System32',
      PATHEXT: '.COM;.EXE;.BAT;.CMD',
    };

    test('honors an existing absolute override before probing PATH', () => {
      let probes = 0;
      expect(
        resolveShell(baseEnv, {
          platform: 'win32',
          override: 'D:\\Shells\\pwsh.exe',
          shellExists: shellExists(['D:\\Shells\\pwsh.exe']),
          pathProbe: () => {
            probes += 1;
            return 'C:\\PATH\\pwsh.exe';
          },
        }),
      ).toBe('D:\\Shells\\pwsh.exe');
      expect(probes).toBe(0);
    });

    test('uses the PATHEXT-aware PATH probe before known-install backstops', () => {
      expect(
        resolveShell(baseEnv, {
          platform: 'win32',
          pathProbe: (command, env) => {
            expect(command).toBe('pwsh');
            expect(env.PATHEXT).toBe('.COM;.EXE;.BAT;.CMD');
            return 'D:\\Portable\\pwsh.exe';
          },
          shellExists: shellExists(['D:\\Portable\\pwsh.exe', programFilesPwsh]),
        }),
      ).toBe('D:\\Portable\\pwsh.exe');
    });

    test('falls back to the Program Files PowerShell 7 install', () => {
      expect(
        resolveShell(baseEnv, {
          platform: 'win32',
          pathProbe: () => null,
          shellExists: shellExists([programFilesPwsh]),
        }),
      ).toBe(programFilesPwsh);
    });

    test('scans the WindowsApps PowerShell package aliases after Program Files', () => {
      const windowsApps = 'C:\\Users\\alice\\AppData\\Local\\Microsoft\\WindowsApps';
      const alias = `${windowsApps}\\Microsoft.PowerShell_8wekyb3d8bbwe\\pwsh.exe`;
      expect(
        resolveShell(baseEnv, {
          platform: 'win32',
          pathProbe: () => null,
          listDirectory: (path) =>
            path === windowsApps ? ['Other.App_123', 'Microsoft.PowerShell_8wekyb3d8bbwe'] : [],
          shellExists: shellExists([alias]),
        }),
      ).toBe(alias);
    });

    test('falls through to Windows PowerShell 5.1', () => {
      expect(
        resolveShell(baseEnv, {
          platform: 'win32',
          pathProbe: () => null,
          listDirectory: () => [],
          shellExists: shellExists([windowsPowerShell]),
        }),
      ).toBe(windowsPowerShell);
    });

    test('uses a case-insensitive ComSpec key before the cmd.exe floor', () => {
      expect(
        resolveShell(
          { ...baseEnv, ComSpec: undefined, cOmSpEc: 'D:\\Windows\\cmd.exe' },
          {
            platform: 'win32',
            pathProbe: () => null,
            listDirectory: () => [],
            shellExists: shellExists(['D:\\Windows\\cmd.exe']),
          },
        ),
      ).toBe('D:\\Windows\\cmd.exe');
    });

    test('uses the absolute cmd.exe floor and never consults SHELL', () => {
      expect(
        resolveShell(
          { ...baseEnv, SHELL: '/bin/zsh' },
          {
            platform: 'win32',
            pathProbe: () => null,
            listDirectory: () => [],
            shellExists: shellExists([]),
          },
        ),
      ).toBe(cmd);
    });

    test('empty and whitespace overrides are unset without an invalid-override notice', () => {
      for (const override of ['', '   ', '\t']) {
        const h = makeHarness({
          platform: 'win32',
          env: baseEnv,
          shellExists: shellExists([windowsPowerShell]),
          pathProbe: () => null,
          listDirectory: () => [],
        });
        h.fire(CREATE({ shell: override }));
        expect(h.spawnCalls[0]?.file).toBe(windowsPowerShell);
        expect(h.posted).not.toContainEqual(
          expect.objectContaining({
            type: 'shell-notice',
            ptyId: 'p1',
            notice: 'invalid-shell-override',
            reason: expect.any(String),
          }),
        );
      }
    });

    test('an invalid override logs, emits a notice, and continues down the ladder', () => {
      const warnings: Record<string, unknown>[] = [];
      const h = makeHarness({
        platform: 'win32',
        env: baseEnv,
        shellExists: shellExists([windowsPowerShell]),
        pathProbe: () => null,
        listDirectory: () => [],
        logger: { warn: (entry) => warnings.push(entry) },
      });

      h.fire(CREATE({ shell: 'C:\\Missing\\pwsh.exe' }));

      expect(h.spawnCalls[0]?.file).toBe(windowsPowerShell);
      expect(h.posted).toContainEqual({
        type: 'shell-notice',
        ptyId: 'p1',
        notice: 'invalid-shell-override',
        reason: 'not-found',
      });
      expect(warnings).toContainEqual(
        expect.objectContaining({
          event: 'pty-host-shell-override-invalid',
          platform: 'win32',
          reason: 'not-found',
        }),
      );
    });

    test('logs the selected bounded-cardinality ladder rung', () => {
      const entries: Record<string, unknown>[] = [];
      const h = makeHarness({
        platform: 'win32',
        env: baseEnv,
        shellExists: shellExists([programFilesPwsh]),
        pathProbe: () => null,
        logger: { warn: () => {}, info: (entry) => entries.push(entry) },
      });

      h.fire(CREATE());

      expect(entries).toContainEqual({
        event: 'pty-host-shell-resolved',
        platform: 'win32',
        rung: 'pwsh-known-install',
      });
    });
  });
});

test('buildShellArgs uses empty argv for every win32 shell rung', () => {
  expect(
    buildShellArgs('win32', 'C:\\Program Files\\PowerShell\\7\\pwsh.exe', undefined, []),
  ).toEqual([]);
  expect(buildShellArgs('win32', 'C:\\Windows\\System32\\cmd.exe', undefined, [])).toEqual([]);
  expect(buildShellArgs('win32', 'C:\\Program Files\\Git\\bin\\bash.exe', undefined, [])).toEqual(
    [],
  );
});

describe('buildShellArgs Windows launch composition', () => {
  test('PowerShell uses -NoExit + EncodedCommand and preserves structured JSON', () => {
    const args = buildShellArgs(
      'win32',
      'C:\\Program Files\\PowerShell\\7\\pwsh.exe',
      {
        executable: 'native.exe',
        args: ['--settings', '{"nested":"a\'b"}'],
      },
      [],
    );
    expect(Array.isArray(args)).toBe(true);
    if (!Array.isArray(args)) throw new Error('expected PowerShell argv');
    expect(args.slice(0, 2)).toEqual(['-NoExit', '-EncodedCommand']);
    expect(Buffer.from(args[2] ?? '', 'base64').toString('utf16le')).toBe(
      "& 'native.exe' '--settings' '{\"nested\":\"a''b\"}'",
    );
  });

  test('cmd uses node-pty string mode so CRT quote remarshal is bypassed', () => {
    expect(
      buildShellArgs(
        'win32',
        'C:\\Windows\\System32\\cmd.exe',
        {
          executable: 'claude',
          args: [],
        },
        [],
      ),
    ).toBe('/K claude');
  });

  test('Git Bash preserves the structured launch through parser-inert base64 arguments', () => {
    const shell = 'C:\\Program Files\\Git\\bin\\bash.exe';
    const launchTokens = [
      'codex',
      '-c',
      'mcp_servers.open-knowledge.default_tools_approval_mode=approve',
      "apostrophe'and space",
    ];
    const args = buildShellArgs(
      'win32',
      shell,
      {
        executable: launchTokens[0] ?? '',
        args: launchTokens.slice(1),
      },
      [],
    );
    expect(Array.isArray(args)).toBe(true);
    if (!Array.isArray(args)) throw new Error('expected Git Bash argv');

    expect(args.slice(0, 3)).toEqual(['--login', '-i', '-c']);
    expect(args[3]).toContain('base64 -d');
    expect(args[4]).toBe('bash');
    expect(
      Buffer.from(args[5] ?? '', 'base64')
        .toString('utf8')
        .split('\u0000'),
    ).toEqual([...launchTokens, '']);
  });

  test('the host reports the resolved Windows shell family before spawning', () => {
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows', ProgramFiles: 'C:\\Program Files' },
      shellExists: (path) => path.endsWith('pwsh.exe'),
    });
    h.fire(CREATE());
    expect(h.posted).toContainEqual({
      type: 'shell-notice',
      ptyId: 'p1',
      notice: 'shell-resolved',
      shellFamily: 'powershell',
    });
  });

  test('an unsupported override degrades a structured launch to a plain interactive shell', () => {
    const warnings: Record<string, unknown>[] = [];
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows', ProgramFiles: 'C:\\Program Files' },
      shellExists: (path) => ['C:\\Tools\\fish.exe', 'C:\\Tools\\pwsh.exe'].includes(path),
      logger: { warn: (entry) => warnings.push(entry) },
    });

    h.fire(
      CREATE({
        shell: 'C:\\Tools\\fish.exe',
        launchCommand: {
          executable: 'claude',
          args: ['--settings', '.ok/local/terminal/claude-settings-mcp-tools.json'],
          supportFile: {
            kind: 'claude-settings',
            relativePath: '.ok/local/terminal/claude-settings-mcp-tools.json',
            contents: '{"enabledMcpjsonServers":["open-knowledge"]}',
          },
        },
      }),
    );

    expect(h.spawnCalls).toHaveLength(1);
    expect(h.spawnCalls[0]?.file).toBe('C:\\Tools\\fish.exe');
    expect(h.spawnCalls[0]?.args).toEqual([]);
    expect(h.materializedSupportFiles).toHaveLength(0);
    expect(h.posted).toContainEqual({
      type: 'shell-notice',
      ptyId: 'p1',
      notice: 'invalid-shell-override',
      reason: 'unsupported-family',
    });
    expect(h.posted).not.toContainEqual(expect.objectContaining({ type: 'spawn-error' }));
    expect(warnings).toContainEqual(
      expect.objectContaining({
        event: 'pty-host-launch-degraded-unsupported-shell',
        platform: 'win32',
        rung: 'override',
      }),
    );

    h.fire(
      CREATE({
        ptyId: 'p2',
        shell: 'C:\\Tools\\pwsh.exe',
        launchCommand: { executable: 'claude', args: [] },
      }),
    );
    expect(h.spawnCalls).toHaveLength(2);
    expect(h.spawnCalls[1]?.file).toBe('C:\\Tools\\pwsh.exe');
    expect(h.spawnCalls[1]?.args).not.toEqual([]);
  });

  test('an unsupported override also degrades a managed command tab to a plain shell', () => {
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows' },
      shellExists: (path) => ['C:\\Tools\\fish.exe', 'C:\\Tools\\pwsh.exe'].includes(path),
    });

    h.fire(
      CREATE({
        shell: 'C:\\Tools\\fish.exe',
        launchCommand: { executable: 'git', args: ['status'] },
      }),
    );

    expect(h.spawnCalls).toHaveLength(1);
    expect(h.spawnCalls[0]).toMatchObject({ file: 'C:\\Tools\\fish.exe', args: [] });
    expect(h.posted).toContainEqual({
      type: 'shell-notice',
      ptyId: 'p1',
      notice: 'invalid-shell-override',
      reason: 'unsupported-family',
    });
    expect(h.posted).not.toContainEqual(expect.objectContaining({ type: 'spawn-error' }));

    h.fire(
      CREATE({
        ptyId: 'p2',
        shell: 'C:\\Tools\\pwsh.exe',
        launchCommand: { executable: 'git', args: ['status'] },
      }),
    );
    expect(h.spawnCalls).toHaveLength(2);
    expect(h.spawnCalls[1]?.file).toBe('C:\\Tools\\pwsh.exe');
    expect(h.spawnCalls[1]?.args).not.toEqual([]);
  });

  test('a structured launch composition failure aborts only that create request', () => {
    const warnings: Record<string, unknown>[] = [];
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows' },
      shellExists: (path) => path === 'C:\\Tools\\pwsh.exe',
      logger: { warn: (entry) => warnings.push(entry) },
    });

    h.fire(
      CREATE({
        shell: 'C:\\Tools\\pwsh.exe',
        launchCommand: { executable: 'agent.cmd', args: ['safe', '" & calc & "'] },
      }),
    );

    expect(h.spawnCalls).toHaveLength(0);
    expect(h.posted).toContainEqual(
      expect.objectContaining({
        type: 'spawn-error',
        ptyId: 'p1',
        launchFailure: 'unsafe-argument',
      }),
    );
    expect(h.posted).not.toContainEqual(
      expect.objectContaining({ type: 'spawn-error', message: expect.any(String) }),
    );
    expect(warnings).toContainEqual(
      expect.objectContaining({
        event: 'pty-host-launch-compose-failed',
        platform: 'win32',
        rung: 'override',
        launchFailure: 'unsafe-argument',
      }),
    );

    h.fire(CREATE({ ptyId: 'p2', shell: 'C:\\Tools\\pwsh.exe' }));
    expect(h.spawnCalls).toHaveLength(1);
    expect(h.spawnCalls[0]?.file).toBe('C:\\Tools\\pwsh.exe');
  });

  test('an unsupported override keeps plain tabs usable with a capability notice', () => {
    const warnings: Record<string, unknown>[] = [];
    const h = makeHarness({
      platform: 'win32',
      env: { SystemRoot: 'C:\\Windows' },
      shellExists: (path) => path === 'C:\\Tools\\fish.exe',
      logger: { warn: (entry) => warnings.push(entry) },
    });

    h.fire(CREATE({ shell: 'C:\\Tools\\fish.exe' }));

    expect(h.spawnCalls[0]?.file).toBe('C:\\Tools\\fish.exe');
    expect(h.posted).toContainEqual({
      type: 'shell-notice',
      ptyId: 'p1',
      notice: 'invalid-shell-override',
      reason: 'unsupported-family',
    });
    expect(h.posted).not.toContainEqual(
      expect.objectContaining({ type: 'shell-notice', notice: 'shell-resolved' }),
    );
    expect(warnings).toContainEqual({
      event: 'pty-host-shell-override-capability-limited',
      platform: 'win32',
      reason: 'unsupported-family',
    });
  });
});

describe('node-pty import failure', () => {
  test('a Linux-capable host replies to create with the existing spawn-error contract', () => {
    expect(isTerminalPlatform('linux')).toBe(true);

    let handler = null as ((event: { data: unknown }) => void) | null;
    const posted: PtyHostOutgoingMessage[] = [];
    const warnings: Array<{ data: Record<string, unknown>; message: string }> = [];
    installPtyImportFailureReply(
      {
        on(_event, nextHandler) {
          handler = nextHandler;
        },
        postMessage(message) {
          posted.push(message);
        },
      },
      new Error('node-pty Linux prebuild could not be loaded'),
      {
        warn(data, message) {
          warnings.push({ data, message });
        },
      },
    );

    handler?.({
      data: {
        type: 'create',
        ptyId: 'linux-pty',
        cwd: '/project',
        cols: 80,
        rows: 24,
      },
    });

    expect(posted).toEqual([
      {
        type: 'spawn-error',
        ptyId: 'linux-pty',
        message: 'node-pty Linux prebuild could not be loaded',
      },
    ]);
    expect(warnings).toEqual([
      {
        data: {
          event: 'pty-host-import-failed',
          error: 'node-pty Linux prebuild could not be loaded',
        },
        message: 'node-pty import failed',
      },
    ]);
  });
});

class FakeReapProcess implements HostReapProcess {
  exitCodes: number[] = [];
  private readonly listeners = new Map<string, Array<() => void>>();
  on(event: 'exit' | NodeJS.Signals, listener: () => void): void {
    const arr = this.listeners.get(event) ?? [];
    arr.push(listener);
    this.listeners.set(event, arr);
  }
  exit(code?: number): void {
    this.exitCodes.push(code ?? 0);
  }
  emit(event: 'exit' | NodeJS.Signals): void {
    for (const listener of this.listeners.get(event) ?? []) listener();
  }
}

function makeReapHandle(): { handle: PtyHostHandle; killCount: () => number } {
  let count = 0;
  return {
    handle: {
      killActive() {
        count += 1;
      },
    },
    killCount: () => count,
  };
}

describe('installHostReaping', () => {
  test('SIGTERM reaps the active pty and exits the host', () => {
    const { handle, killCount } = makeReapHandle();
    const proc = new FakeReapProcess();
    installHostReaping(handle, proc);
    proc.emit('SIGTERM');
    expect(killCount()).toBe(1);
    expect(proc.exitCodes).toEqual([0]);
  });

  test('SIGINT and SIGHUP also reap + exit', () => {
    for (const signal of ['SIGINT', 'SIGHUP'] as const) {
      const { handle, killCount } = makeReapHandle();
      const proc = new FakeReapProcess();
      installHostReaping(handle, proc);
      proc.emit(signal);
      expect(killCount()).toBe(1);
      expect(proc.exitCodes).toEqual([0]);
    }
  });

  test('a plain exit reaps without re-triggering exit (sync backstop)', () => {
    const { handle, killCount } = makeReapHandle();
    const proc = new FakeReapProcess();
    installHostReaping(handle, proc);
    proc.emit('exit');
    expect(killCount()).toBe(1);
    expect(proc.exitCodes).toEqual([]);
  });

  test('reaping is idempotent across multiple teardown events', () => {
    const { handle, killCount } = makeReapHandle();
    const proc = new FakeReapProcess();
    installHostReaping(handle, proc);
    proc.emit('SIGTERM');
    proc.emit('exit');
    proc.emit('SIGINT');
    expect(killCount()).toBe(1);
    expect(proc.exitCodes).toEqual([0, 0]);
  });
});

describe('buildLaunchEnv', () => {
  test('a string launch keeps the shell env as is', () => {
    const env = { PATH: '/usr/bin', A: '1' };
    expect(buildLaunchEnv('darwin', env, "codex 'hi'")).toBe(env);
  });

  test('a structured launch parks its env in slot variables and leaves PATH to the command on POSIX', () => {
    expect(
      buildLaunchEnv(
        'darwin',
        { PATH: '/usr/bin', A: '1' },
        { executable: 'x', args: [], env: { B: '2' }, pathPrepend: ['/rt/bin'] },
      ),
    ).toEqual({ PATH: '/usr/bin', A: '1', OK_TERMINAL_LAUNCH_ENV_0: '2' });
  });

  test("a method env name never reaches the shell's startup environment", () => {
    const env = buildLaunchEnv(
      'darwin',
      { PATH: '/usr/bin', HOME: '/Users/me' },
      {
        executable: 'agent',
        args: ['login'],
        env: { ZDOTDIR: '/tmp/agent-owned', HOME: '/tmp/agent-owned', BASH_ENV: '/tmp/x.sh' },
      },
    );
    expect(env).toEqual({
      PATH: '/usr/bin',
      HOME: '/Users/me',
      OK_TERMINAL_LAUNCH_ENV_0: '/tmp/agent-owned',
      OK_TERMINAL_LAUNCH_ENV_1: '/tmp/agent-owned',
      OK_TERMINAL_LAUNCH_ENV_2: '/tmp/x.sh',
    });
    expect(env).not.toHaveProperty('ZDOTDIR');
    expect(env).not.toHaveProperty('BASH_ENV');
  });

  test('a structured launch puts its PATH dirs first on Windows', () => {
    expect(
      buildLaunchEnv(
        'win32',
        { Path: 'C:\\Windows', A: '1' },
        { executable: 'x', args: [], pathPrepend: ['C:\\rt\\bin'] },
      ),
    ).toEqual({ Path: 'C:\\rt\\bin;C:\\Windows', A: '1' });
  });
});