Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

56.9 KB
Raw Blame
import { type ChildProcess, execFileSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  rmSync,
  utimesSync,
  writeFileSync,
} from 'node:fs';
import { homedir, tmpdir } from 'node:os';
import { delimiter, join } from 'node:path';
import { OK_HOSTED_AGENT_ENV } from '@inkeep/open-knowledge-core';
import { afterEach, describe, expect, test, vi } from 'vitest';
import { pid1Reaps } from '../../../../test-support/capabilities.test-helper.ts';
import { getLogger, type PinoLogger } from '../logger.ts';
import { withLocalAcquisitionRegistry } from './acquisition-contract.test-helper.ts';
import { createDiagnosticStderrCapture } from './diagnostics.ts';
import {
  AgentLaunchError,
  brokenInterpreterHint,
  declinedRepairHint,
  ensureBinaryInstalled,
  incompatibleNodeHint,
  isPathQualified,
  MINIMUM_NPX_NODE_MAJOR,
  mergedEnv,
  npxInstallRefused,
  overlaySetsPath,
  packageAcquisitionFailure,
  preflightLaunch,
  probeInterpreterHealth,
  probeNpxNodeCompatibility,
  type ResolvedLaunch,
  resolveCustomLaunch,
  resolveNpxNodeCommand,
  resolveRegistryLaunch,
  resolveWindowsCommand,
  spawnAcpAgent,
  staleNpxCacheEntry,
  terminateAgentTree,
  undeletableManagedRuntimeHint,
  unrepairableManagedRuntimeHint,
  windowsCmdWrap,
  withHostedAgentMarker,
  withLoginShellPath,
  withPreferredLoginShellPath,
} from './launch.ts';
import {
  registryPackage,
  spawnNpxWithProjectCwd,
  withAcquisitionHome,
} from './package-acquisition.test-helper.ts';
import type { RegistryBinaryTarget } from './registry.ts';

describe('package acquisition descriptor boundaries', () => {
  test.each([
    'is-number',
    'is-number@latest',
    'is-number@^7.0.0',
    '[email protected] - 7.0.0',
    '@scope/[email protected]',
    'alias@npm:[email protected]',
    'git+https://github.com/example/agent.git',
    'https://example.com/agent-1.2.3.tgz',
    'file:./agent',
  ])('compatibility control: npm descriptor %s retains its caller contract', async (descriptor) => {
    await withAcquisitionHome(async () => {
      const env = {
        npm_config_registry: 'https://registry.example.test/',
        npm_config_before: '2020-01-01',
        'npm_config_//registry.example.test/:_authToken': 'fixture-token',
        ACP_FIXTURE: 'preserved',
      };
      const launch = await resolveRegistryLaunch(
        registryPackage(descriptor, 'npx', env),
        null,
        getLogger('descriptor-test'),
      );
      expect(launch.args).toEqual(['-y', descriptor, '--version']);
      expect(launch.env).toMatchObject(env);
    });
  });

  test.each(['@agentclientprotocol/[email protected]'])(
    'compatibility control: admissible stable %s uses its package version instead of the catalog version',
    async (descriptor) => {
      await withLocalAcquisitionRegistry(async () => {
        const launch = await resolveRegistryLaunch(
          registryPackage(descriptor),
          null,
          getLogger('descriptor-test'),
        );
        expect(launch.args).toEqual(['-y', descriptor, '--version']);
      });
    },
    90_000,
  );

  test.each(['[email protected]', 'ruff==0.12.0'])(
    'stable Python descriptor %s emits an isolated bounded native tool request',
    async (descriptor) => {
      await withAcquisitionHome(async () => {
        const env = {
          UV_EXCLUDE_NEWER: '2025-01-01',
          UV_INDEX_URL: 'https://python.example.test/simple',
        };
        const launch = await resolveRegistryLaunch(
          registryPackage(descriptor, 'uvx', env),
          null,
          getLogger('descriptor-test'),
        );
        expect(launch.args).toEqual([
          '--from',
          'ruff<=0.12.0',
          '--isolated',
          '--upgrade-package',
          'ruff',
          'ruff',
          '--version',
        ]);
        expect(launch.env).toMatchObject(env);
      });
    },
  );

  test.each([
    'ruff',
    'ruff>=0.12.0',
    'ruff==0.12.0rc1',
    'ruff@latest',
    'git+https://example.com/ruff.git',
  ])(
    'compatibility control: non-stable Python descriptor %s passes through',
    async (descriptor) => {
      const launch = await resolveRegistryLaunch(
        registryPackage(descriptor, 'uvx'),
        null,
        getLogger('descriptor-test'),
      );
      expect(launch.args).toEqual([descriptor, '--version']);
    },
  );

  test('compatibility control: binary and custom launch contracts are outside package admission', async () => {
    expect(
      resolveCustomLaunch({
        id: 'custom',
        name: 'Custom',
        command: 'node',
        args: ['script.js'],
        env: { ACP_FIXTURE: 'custom' },
      }),
    ).toMatchObject({
      kind: 'custom',
      cmd: 'node',
      args: ['script.js'],
      env: { ACP_FIXTURE: 'custom' },
    });
    await expect(
      resolveRegistryLaunch(
        { id: 'binary', name: 'Binary', version: '1.2.3', distribution: { binary: {} } },
        null,
        getLogger('descriptor-test'),
      ),
    ).rejects.toMatchObject({ code: 'unsupported-platform' });
  });

  test.each(['[email protected] - 1.2.3', '@scope/[email protected] - 1.2.3', 'agent<=1.2.3'])(
    'compatibility control: Windows transports %s as one quoted operand',
    (operand) => {
      const wrapped = windowsCmdWrap('C:\\Program Files\\nodejs\\npm.cmd', [
        'pack',
        operand,
        '--json',
      ]);
      expect(wrapped.args[3]).toContain(`"${operand}"`);
      expect(wrapped.args.slice(0, 3)).toEqual(['/d', '/s', '/c']);
    },
  );
});

describe('mergedEnv PATH augmentation', () => {
  test('an explicit overlay PATH is used verbatim — augmentation repairs only the inherited base', () => {
    const key = 'PATH' in process.env ? 'PATH' : 'Path';
    const out = mergedEnv({ [key]: '/sentinel/only' });
    expect(out[key]).toBe('/sentinel/only');
  });

  test('appends without dropping any existing PATH entry', () => {
    const key = 'PATH' in process.env ? 'PATH' : 'Path';
    const after = new Set((mergedEnv()[key] ?? '').split(delimiter));
    for (const dir of (process.env[key] ?? '').split(delimiter).filter(Boolean)) {
      expect(after.has(dir)).toBe(true);
    }
  });

  test('preserves non-PATH process.env entries', () => {
    expect(mergedEnv().HOME).toBe(process.env.HOME);
  });

  test('drops inherited `npm_config_overrides` while preserving user-set npm env', () => {
    const priors = {
      npm_config_overrides: process.env.npm_config_overrides,
      npm_config_userconfig: process.env.npm_config_userconfig,
      'npm_config_//registry.example.com/:_authToken':
        process.env['npm_config_//registry.example.com/:_authToken'],
      npm_config_registry: process.env.npm_config_registry,
      NPM_CONFIG_STRICT_PEER_DEPENDENCIES: process.env.NPM_CONFIG_STRICT_PEER_DEPENDENCIES,
    };
    process.env.npm_config_overrides = '{"@modelcontextprotocol/sdk>zod":"^3.25.7"}';
    process.env.npm_config_userconfig = '/home/user/.npmrc-override';
    process.env['npm_config_//registry.example.com/:_authToken'] = 'secret';
    process.env.npm_config_registry = 'https://registry.example.com/';
    process.env.NPM_CONFIG_STRICT_PEER_DEPENDENCIES = 'true';
    try {
      const out = mergedEnv();
      expect(out.npm_config_overrides).toBeUndefined();
      expect(out.npm_config_userconfig).toBe('/home/user/.npmrc-override');
      expect(out['npm_config_//registry.example.com/:_authToken']).toBe('secret');
      expect(out.npm_config_registry).toBe('https://registry.example.com/');
      expect(out.NPM_CONFIG_STRICT_PEER_DEPENDENCIES).toBe('true');
    } finally {
      for (const [k, v] of Object.entries(priors)) {
        if (v === undefined) delete process.env[k];
        else process.env[k] = v;
      }
    }
  });

  test('managed-runtime overlay wins over a pnpm-broadcast `npm_config_cache` base', () => {
    const prior = process.env.npm_config_cache;
    process.env.npm_config_cache = '/pnpm/broadcast/cache';
    try {
      const out = mergedEnv({ npm_config_cache: '/tmp/managed-node-cache' });
      expect(out.npm_config_cache).toBe('/tmp/managed-node-cache');
    } finally {
      if (prior === undefined) delete process.env.npm_config_cache;
      else process.env.npm_config_cache = prior;
    }
  });

  test('keeps the dev channel away from agents, whose MCP children may run a CLI that predates it', () => {
    const prior = process.env.OK_CHANNEL;
    process.env.OK_CHANNEL = 'dev';
    try {
      expect(mergedEnv().OK_CHANNEL).toBeUndefined();
    } finally {
      if (prior === undefined) delete process.env.OK_CHANNEL;
      else process.env.OK_CHANNEL = prior;
    }
  });

  test('passes a shipped channel through to agents', () => {
    const prior = process.env.OK_CHANNEL;
    process.env.OK_CHANNEL = 'beta';
    try {
      expect(mergedEnv().OK_CHANNEL).toBe('beta');
    } finally {
      if (prior === undefined) delete process.env.OK_CHANNEL;
      else process.env.OK_CHANNEL = prior;
    }
  });

  test('overlaySetsPath sees PATH under any spelling', () => {
    expect(overlaySetsPath({ Path: '/x' })).toBe(true);
    expect(overlaySetsPath({ PATH: '/x' })).toBe(true);
    expect(overlaySetsPath({ HOME: '/x' })).toBe(false);
    expect(overlaySetsPath(undefined)).toBe(false);
  });
});

describe('withLoginShellPath', () => {
  const key = 'PATH' in process.env ? 'PATH' : 'Path';

  test('appends the login shell PATH to the launch env, key spelling preserved', () => {
    const out = withLoginShellPath(
      { cmd: 'npx', args: [], env: { [key]: '/usr/bin' }, kind: 'npx', pathFromOverlay: false },
      `/nvm/bin${delimiter}/usr/bin`,
    );
    expect(out.env[key]).toBe(`/usr/bin${delimiter}/nvm/bin`);
    expect(out.cmd).toBe('npx');
  });

  test('leaves the rest of the env untouched', () => {
    const out = withLoginShellPath(
      {
        cmd: 'npx',
        args: ['-y', 'pkg'],
        env: { [key]: '/usr/bin', TOKEN: 'keep' },
        kind: 'npx',
        pathFromOverlay: false,
      },
      '/nvm/bin',
    );
    expect(out.env.TOKEN).toBe('keep');
    expect(out.args).toEqual(['-y', 'pkg']);
  });
});

describe('withPreferredLoginShellPath', () => {
  const key = 'PATH' in process.env ? 'PATH' : 'Path';

  test('promotes the login-shell PATH ahead of an incompatible inherited runtime', () => {
    const out = withPreferredLoginShellPath(
      {
        cmd: 'npx',
        args: ['-y', 'pkg'],
        env: { [key]: `/old-node/bin${delimiter}/usr/bin`, TOKEN: 'keep' },
        kind: 'npx',
        pathFromOverlay: false,
      },
      `/new-node/bin${delimiter}/usr/bin`,
    );
    expect(out.env[key]).toBe(`/new-node/bin${delimiter}/usr/bin${delimiter}/old-node/bin`);
    expect(out.env.TOKEN).toBe('keep');
  });
});

describe('isPathQualified', () => {
  test('a bare name is PATH-searched; a located command is not', () => {
    expect(isPathQualified('npx')).toBe(false);
    expect(isPathQualified('./agent')).toBe(true);
    expect(isPathQualified('/opt/agent/bin/agent')).toBe(true);
  });
});

const isAlive = (pid: number): boolean => {
  try {
    process.kill(pid, 0);
    return true;
  } catch {
    return false;
  }
};

const plainEnv = (overlay: Record<string, string> = {}): Record<string, string> => {
  const env: Record<string, string> = {};
  for (const [k, v] of Object.entries(process.env)) {
    if (v !== undefined) env[k] = v;
  }
  return { ...env, ...overlay };
};

const launchFor = (
  script: string,
  overlay?: Record<string, string>,
): ResolvedLaunch & { kind: 'custom' } => ({
  cmd: 'node',
  args: [script],
  env: plainEnv(overlay),
  kind: 'custom',
  pathFromOverlay: overlaySetsPath(overlay),
});

const realSetTimeout = globalThis.setTimeout;

const realTimePause = (ms: number): Promise<void> =>
  new Promise((resolve) => {
    realSetTimeout(resolve, ms);
  });

async function waitFor(pred: () => boolean, ms: number, what: string): Promise<void> {
  const deadline = Date.now() + ms;
  while (!pred()) {
    if (Date.now() > deadline) throw new Error(`timed out waiting for ${what}`);
    await realTimePause(25);
  }
}

let dirs: string[] = [];
let strayChildren: ChildProcess[] = [];
const GRANDCHILD_SELF_EXIT_MS = 60_000;
const log = getLogger('acp-launch-test');
function tmp(): string {
  const d = mkdtempSync(join(tmpdir(), 'acp-launch-test-'));
  dirs.push(d);
  return d;
}
afterEach(() => {
  for (const child of strayChildren) child.kill('SIGKILL');
  strayChildren = [];
  for (const d of dirs) rmSync(d, { recursive: true, force: true });
  dirs = [];
});

function buildBinaryTarball(
  dir: string,
  label = 'agent',
): { bytes: Buffer; sha: string; target: RegistryBinaryTarget } {
  const treeRoot = join(dir, `tree-${label}`);
  const command = join(treeRoot, 'package', 'bin', 'agent');
  mkdirSync(join(command, '..'), { recursive: true });
  writeFileSync(command, `#!/bin/sh\necho ${label}\n`, { mode: 0o755 });
  const tarPath = join(dir, `${label}.tar.gz`);
  execFileSync('tar', ['-czf', tarPath, '-C', treeRoot, 'package']);
  const bytes = readFileSync(tarPath);
  return {
    bytes,
    sha: createHash('sha256').update(bytes).digest('hex'),
    target: {
      archive: `https://example.com/${label}.tar.gz`,
      cmd: './package/bin/agent',
    },
  };
}

function binaryFetch(bytes: Buffer): typeof fetch {
  return (async () =>
    new Response(new Uint8Array(bytes), {
      status: 200,
      headers: { 'content-length': String(bytes.length) },
    })) as unknown as typeof fetch;
}

describe('ensureBinaryInstalled', () => {
  test('stages beside the destination before downloading', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const agentDir = join(cacheDir, 'test-agent');
    let observedStagingDir: string | undefined;
    const baseFetch = binaryFetch(artifact.bytes);
    const inspectingFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
      observedStagingDir = readdirSync(agentDir).find((name) => name.startsWith('.install-'));
      return baseFetch(input, init);
    }) as typeof fetch;

    const installed = await ensureBinaryInstalled(
      'test-agent',
      '1.0.0',
      { ...artifact.target, sha256: artifact.sha },
      cacheDir,
      log,
      { fetchImpl: inspectingFetch },
    );

    expect(installed).toBe(join(agentDir, '1.0.0'));
    expect(observedStagingDir).toBeDefined();
    expect(readdirSync(agentDir)).not.toContain(observedStagingDir);
    expect(existsSync(join(installed, 'package', 'bin', 'agent'))).toBe(true);
  });

  test('removes crash-orphaned staging directories on the next install', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const staleDir = join(cacheDir, 'test-agent', '.install-1.0.0-orphaned');
    mkdirSync(staleDir, { recursive: true });
    writeFileSync(join(staleDir, 'partial-archive'), 'partial');
    const staleTime = new Date(Date.now() - 25 * 60 * 60 * 1_000);
    utimesSync(staleDir, staleTime, staleTime);

    await ensureBinaryInstalled(
      'test-agent',
      '1.0.0',
      { ...artifact.target, sha256: artifact.sha },
      cacheDir,
      log,
      { fetchImpl: binaryFetch(artifact.bytes) },
    );

    expect(existsSync(staleDir)).toBe(false);
  });

  test('a second install of the same binary joins the download already running', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const target = { ...artifact.target, sha256: artifact.sha };
    let downloads = 0;
    const baseFetch = binaryFetch(artifact.bytes);
    const countingFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
      downloads += 1;
      return baseFetch(input, init);
    }) as typeof fetch;
    const started: string[] = [];

    const installed = await Promise.all([
      ensureBinaryInstalled('test-agent', '1.0.0', target, cacheDir, log, {
        fetchImpl: countingFetch,
        onDownloadStart: () => started.push('first'),
      }),
      ensureBinaryInstalled('test-agent', '1.0.0', target, cacheDir, log, {
        fetchImpl: countingFetch,
        onDownloadStart: () => started.push('second'),
      }),
    ]);

    expect(downloads).toBe(1);
    expect(installed[0]).toBe(installed[1]);
    expect(started.sort()).toEqual(['first', 'second']);
  });

  test('an install that joins after the download started is told it is installing', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const target = { ...artifact.target, sha256: artifact.sha };
    const { promise: responseGate, resolve: releaseResponse } = Promise.withResolvers<void>();
    const baseFetch = binaryFetch(artifact.bytes);
    const gatedFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
      await responseGate;
      return baseFetch(input, init);
    }) as typeof fetch;
    const { promise: firstStarted, resolve: markFirstStarted } = Promise.withResolvers<void>();
    const started: string[] = [];

    const first = ensureBinaryInstalled('test-agent', '1.0.0', target, cacheDir, log, {
      fetchImpl: gatedFetch,
      onDownloadStart: () => {
        started.push('first');
        markFirstStarted();
      },
    });
    await firstStarted;
    const second = ensureBinaryInstalled('test-agent', '1.0.0', target, cacheDir, log, {
      fetchImpl: gatedFetch,
      onDownloadStart: () => started.push('second'),
    });

    expect(started).toEqual(['first', 'second']);
    releaseResponse();
    expect(await second).toBe(await first);
  });

  test('concurrent installers adopt the first completed binary', async () => {
    const firstSource = tmp();
    const secondSource = tmp();
    const cacheDir = tmp();
    const first = buildBinaryTarball(firstSource, 'first');
    const second = buildBinaryTarball(secondSource, 'second');
    let arrivals = 0;
    const { promise: commitGate, resolve: releaseCommit } = Promise.withResolvers<void>();
    const beforeCommit = async () => {
      arrivals += 1;
      if (arrivals === 2) releaseCommit();
      await commitGate;
    };
    const installMessages: string[] = [];
    const concurrentLog = {
      info: (_context: unknown, message?: string) => {
        if (message !== undefined) installMessages.push(message);
      },
      warn: log.warn.bind(log),
    } as PinoLogger;
    const install = (artifact: ReturnType<typeof buildBinaryTarball>) =>
      ensureBinaryInstalled(
        'test-agent',
        '1.0.0',
        { ...artifact.target, sha256: artifact.sha },
        cacheDir,
        concurrentLog,
        { fetchImpl: binaryFetch(artifact.bytes), beforeCommit },
      );

    const installed = await Promise.all([install(first), install(second)]);

    expect(arrivals).toBe(2);
    expect(installed[0]).toBe(installed[1]);
    expect(
      installMessages.filter((message) => message === '[acp-launch] agent binary installed'),
    ).toHaveLength(1);
    expect(readFileSync(join(installed[0], 'package', 'bin', 'agent'), 'utf8')).toMatch(
      /echo (first|second)/,
    );
    expect(
      readdirSync(join(cacheDir, 'test-agent')).some((name) => name.startsWith('.install-')),
    ).toBe(false);
  });

  test('replaces an incomplete existing directory instead of accepting it', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const versionDir = join(cacheDir, 'test-agent', '1.0.0');
    mkdirSync(versionDir, { recursive: true });
    writeFileSync(join(versionDir, 'partial'), 'incomplete');

    const installed = await ensureBinaryInstalled(
      'test-agent',
      '1.0.0',
      { ...artifact.target, sha256: artifact.sha },
      cacheDir,
      log,
      { fetchImpl: binaryFetch(artifact.bytes) },
    );

    expect(installed).toBe(versionDir);
    expect(existsSync(join(versionDir, 'partial'))).toBe(false);
    expect(existsSync(join(versionDir, 'package', 'bin', 'agent'))).toBe(true);
  });

  test('adopts a completed binary when the commit lock times out', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const versionDir = join(cacheDir, 'test-agent', '1.0.0');
    const command = join(versionDir, 'package', 'bin', 'agent');

    const installed = await ensureBinaryInstalled(
      'test-agent',
      '1.0.0',
      { ...artifact.target, sha256: artifact.sha },
      cacheDir,
      log,
      {
        fetchImpl: binaryFetch(artifact.bytes),
        commitLockTimeoutMs: 100,
        beforeCommit: async () => {
          mkdirSync(join(command, '..'), { recursive: true });
          writeFileSync(command, '#!/bin/sh\necho winner\n', { mode: 0o755 });
          const lockPath = `${versionDir}.install.lock`;
          writeFileSync(lockPath, 'held');
          const future = new Date(Date.now() + 60_000);
          utimesSync(lockPath, future, future);
        },
      },
    );

    expect(installed).toBe(versionDir);
    expect(readFileSync(command, 'utf8')).toContain('winner');
  });

  test('rejects a lock timeout when no completed binary is available', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const versionDir = join(cacheDir, 'test-agent', '1.0.0');

    const installation = ensureBinaryInstalled(
      'test-agent',
      '1.0.0',
      { ...artifact.target, sha256: artifact.sha },
      cacheDir,
      log,
      {
        fetchImpl: binaryFetch(artifact.bytes),
        commitLockTimeoutMs: 100,
        beforeCommit: async () => {
          const lockPath = `${versionDir}.install.lock`;
          writeFileSync(lockPath, 'held');
          const future = new Date(Date.now() + 60_000);
          utimesSync(lockPath, future, future);
        },
      },
    );

    await expect(installation).rejects.toMatchObject({
      name: 'AgentLaunchError',
      code: 'install-failed',
    });
    await expect(installation).rejects.toThrow(/could not acquire file lock/i);
    expect(existsSync(versionDir)).toBe(false);
    expect(
      readdirSync(join(cacheDir, 'test-agent')).some((name) => name.startsWith('.install-')),
    ).toBe(false);
  });

  test('rejects a checksum mismatch without committing or leaving staging behind', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const agentDir = join(cacheDir, 'test-agent');
    const versionDir = join(agentDir, '1.0.0');

    let caught: unknown;
    try {
      await ensureBinaryInstalled(
        'test-agent',
        '1.0.0',
        { ...artifact.target, sha256: '0'.repeat(64) },
        cacheDir,
        log,
        { fetchImpl: binaryFetch(artifact.bytes) },
      );
    } catch (err) {
      caught = err;
    }

    expect(caught).toMatchObject({
      name: 'AgentLaunchError',
      code: 'install-failed',
      message: expect.stringContaining('checksum mismatch'),
      cause: expect.any(Error),
    });
    expect(existsSync(versionDir)).toBe(false);
    expect(readdirSync(agentDir).some((name) => name.startsWith('.install-'))).toBe(false);
  });

  test('reuses a valid cached binary without downloading again', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const target = { ...artifact.target, sha256: artifact.sha };
    const installed = await ensureBinaryInstalled('test-agent', '1.0.0', target, cacheDir, log, {
      fetchImpl: binaryFetch(artifact.bytes),
    });
    const failFetch = (async () => {
      throw new Error('cached install attempted an unexpected download');
    }) as typeof fetch;

    const cached = await ensureBinaryInstalled('test-agent', '1.0.0', target, cacheDir, log, {
      fetchImpl: failFetch,
    });

    expect(cached).toBe(installed);
  });

  test('rejects an archive whose command path is a directory', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);

    await expect(
      ensureBinaryInstalled(
        'test-agent',
        '1.0.0',
        { ...artifact.target, cmd: './package/bin', sha256: artifact.sha },
        cacheDir,
        log,
        { fetchImpl: binaryFetch(artifact.bytes) },
      ),
    ).rejects.toThrow(/no usable command/i);
  });

  test('installs with a loud warning when the manifest omits sha256', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const warnMessages: string[] = [];
    const warnLog = {
      info: log.info.bind(log),
      warn: (_context: unknown, message?: string) => {
        if (message !== undefined) warnMessages.push(message);
      },
    } as PinoLogger;

    const installed = await ensureBinaryInstalled(
      'test-agent',
      '1.0.0',
      artifact.target,
      cacheDir,
      warnLog,
      { fetchImpl: binaryFetch(artifact.bytes) },
    );

    expect(installed).toBe(join(cacheDir, 'test-agent', '1.0.0'));
    expect(existsSync(join(installed, 'package', 'bin', 'agent'))).toBe(true);
    expect(warnMessages.some((message) => message.includes('no sha256'))).toBe(true);
  });

  test('rejects a manifest cmd that escapes the extracted archive', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);

    await expect(
      ensureBinaryInstalled(
        'test-agent',
        '1.0.0',
        { ...artifact.target, cmd: '../outside-agent', sha256: artifact.sha },
        cacheDir,
        log,
        { fetchImpl: binaryFetch(artifact.bytes) },
      ),
    ).rejects.toMatchObject({
      name: 'AgentLaunchError',
      code: 'install-failed',
      message: expect.stringContaining('escapes the extracted archive'),
    });
    expect(existsSync(join(cacheDir, 'test-agent', '1.0.0'))).toBe(false);
  });

  test('a deterministic manifest failure is remembered and fails fast without re-downloading', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const agentDir = join(cacheDir, 'test-agent');
    const badTarget = { ...artifact.target, cmd: './package/bin/missing', sha256: artifact.sha };

    await expect(
      ensureBinaryInstalled('test-agent', '1.0.0', badTarget, cacheDir, log, {
        fetchImpl: binaryFetch(artifact.bytes),
      }),
    ).rejects.toThrow(/no usable command/i);
    expect(existsSync(join(agentDir, '.install-failed-1.0.0'))).toBe(true);

    let fetched = 0;
    const countingFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
      fetched += 1;
      return binaryFetch(artifact.bytes)(input, init);
    }) as typeof fetch;
    const remembered = await ensureBinaryInstalled(
      'test-agent',
      '1.0.0',
      badTarget,
      cacheDir,
      log,
      { fetchImpl: countingFetch },
    ).catch((err: unknown) => err);
    expect(remembered).toMatchObject({
      name: 'AgentLaunchError',
      code: 'install-failed',
      message: expect.stringContaining('remembered from a recent attempt'),
    });
    expect(fetched).toBe(0);

    const installed = await ensureBinaryInstalled(
      'test-agent',
      '1.0.0',
      { ...artifact.target, sha256: artifact.sha },
      cacheDir,
      log,
      { fetchImpl: countingFetch },
    );
    expect(fetched).toBe(1);
    expect(existsSync(join(installed, 'package', 'bin', 'agent'))).toBe(true);
    expect(existsSync(join(agentDir, '.install-failed-1.0.0'))).toBe(false);
  });

  test('a failure marker past its day cap does not block a retry', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const target = { ...artifact.target, sha256: artifact.sha };
    const agentDir = join(cacheDir, 'test-agent');
    const markerPath = join(agentDir, '.install-failed-1.0.0');
    mkdirSync(agentDir, { recursive: true });
    writeFileSync(
      markerPath,
      JSON.stringify({
        archive: target.archive,
        cmd: target.cmd,
        sha256: target.sha256,
        reason: 'old failure',
      }),
    );
    const staleTime = new Date(Date.now() - 25 * 60 * 60 * 1_000);
    utimesSync(markerPath, staleTime, staleTime);

    const installed = await ensureBinaryInstalled('test-agent', '1.0.0', target, cacheDir, log, {
      fetchImpl: binaryFetch(artifact.bytes),
    });

    expect(existsSync(join(installed, 'package', 'bin', 'agent'))).toBe(true);
    expect(existsSync(markerPath)).toBe(false);
  });

  test('a malformed archive URL fails through the install-failed contract without orphaning staging', async () => {
    const cacheDir = tmp();
    const agentDir = join(cacheDir, 'test-agent');

    await expect(
      ensureBinaryInstalled(
        'test-agent',
        '1.0.0',
        { archive: 'not a url', cmd: './bin/agent' },
        cacheDir,
        log,
        {
          fetchImpl: (async () => {
            throw new Error('should not fetch');
          }) as typeof fetch,
        },
      ),
    ).rejects.toMatchObject({ name: 'AgentLaunchError', code: 'install-failed' });
    expect(readdirSync(agentDir).some((name) => name.startsWith('.install-'))).toBe(false);
  });

  test('the fast path sweeps a stale lockfile orphaned by a crashed commit', async () => {
    const source = tmp();
    const cacheDir = tmp();
    const artifact = buildBinaryTarball(source);
    const target = { ...artifact.target, sha256: artifact.sha };
    await ensureBinaryInstalled('test-agent', '1.0.0', target, cacheDir, log, {
      fetchImpl: binaryFetch(artifact.bytes),
    });
    const orphanedLock = join(cacheDir, 'test-agent', '1.0.0.install.lock');
    writeFileSync(orphanedLock, 'held by a crashed process');
    const staleTime = new Date(Date.now() - 25 * 60 * 60 * 1_000);
    utimesSync(orphanedLock, staleTime, staleTime);

    await ensureBinaryInstalled('test-agent', '1.0.0', target, cacheDir, log, {
      fetchImpl: (async () => {
        throw new Error('fast path must not download');
      }) as typeof fetch,
    });

    expect(existsSync(orphanedLock)).toBe(false);
  });
});

describe('hosted-agent marker', () => {
  test('sets the marker and leaves the rest of the env alone', () => {
    const out = withHostedAgentMarker({ FOO: 'bar' });
    expect(out[OK_HOSTED_AGENT_ENV]).toBe('1');
    expect(out.FOO).toBe('bar');
  });

  test('wins over a launch env that already set the key — hosting is our fact, not the agent config’s', () => {
    expect(withHostedAgentMarker({ [OK_HOSTED_AGENT_ENV]: '0' })[OK_HOSTED_AGENT_ENV]).toBe('1');
  });

  test('a really-spawned agent receives it in its environment', async () => {
    const dir = tmp();
    const script = join(dir, 'echo-marker.js');
    writeFileSync(
      script,
      [
        "const fs = require('node:fs');",
        `fs.writeFileSync(process.argv[1] + '.tmp', String(process.env.${OK_HOSTED_AGENT_ENV} ?? 'ABSENT'));`,
        "fs.renameSync(process.argv[1] + '.tmp', process.argv[1] + '.out');",
      ].join('\n'),
    );
    const child = spawnAcpAgent(launchFor(script), dir);
    if (child.pid !== undefined) strayChildren.push(child);
    await waitFor(() => existsSync(`${script}.out`), 10_000, 'spawned agent to report its env');
    expect(readFileSync(`${script}.out`, 'utf8')).toBe('1');
  });
});

describe('spawnAcpAgent — cwd isolation for npx launches', () => {
  function makeEchoCwdScript(dir: string): string {
    const script = join(dir, 'echo-cwd.js');
    writeFileSync(
      script,
      [
        "const fs = require('node:fs');",
        "fs.writeFileSync(process.argv[1] + '.tmp', process.cwd());",
        "fs.renameSync(process.argv[1] + '.tmp', process.argv[1] + '.out');",
      ].join('\n'),
    );
    return script;
  }

  test('npx-kind spawns use an isolated cwd without accepting a project cwd', async () => {
    const dir = tmp();
    const script = makeEchoCwdScript(dir);
    const launch: ResolvedLaunch = {
      cmd: 'node',
      args: [script],
      env: plainEnv(),
      kind: 'npx',
      pathFromOverlay: false,
    };
    expect(() => {
      spawnNpxWithProjectCwd(launch, dir);
    }).toThrow('spawnAcpAgent does not accept a project cwd for npx launches.');
    const child = spawnAcpAgent(launch);
    if (child.pid !== undefined) strayChildren.push(child);
    await waitFor(() => existsSync(`${script}.out`), 10_000, 'spawned agent to report its cwd');
    const observed = readFileSync(`${script}.out`, 'utf8');
    expect(observed).not.toBe(dir);
    expect(observed.endsWith('/.ok/acp-npx-cwd')).toBe(true);
  });

  test('the isolated cwd carries a private marker package.json so arborist walk terminates there', () => {
    const dir =
      spawnAcpAgent({
        cmd: 'node',
        args: ['-e', ''],
        env: plainEnv(),
        kind: 'npx',
        pathFromOverlay: false,
      }).spawnargs === undefined
        ? ''
        : '';
    const markerPath = join(process.env.HOME ?? homedir(), '.ok', 'acp-npx-cwd', 'package.json');
    const marker = JSON.parse(readFileSync(markerPath, 'utf8'));
    expect(marker.private).toBe(true);
    expect(marker.overrides).toBeUndefined();
    void dir;
  });

  test.each(['uvx', 'binary', 'custom'] as const)(
    '%s-kind spawns still run from the record cwd (agent contract)',
    async (kind) => {
      const dir = tmp();
      const script = makeEchoCwdScript(dir);
      const launch: Exclude<ResolvedLaunch, { kind: 'npx' }> = {
        cmd: 'node',
        args: [script],
        env: plainEnv(),
        kind,
        pathFromOverlay: false,
      };
      const child = spawnAcpAgent(launch, dir);
      if (child.pid !== undefined) strayChildren.push(child);
      await waitFor(() => existsSync(`${script}.out`), 10_000, 'spawned agent to report its cwd');
      const observed = readFileSync(`${script}.out`, 'utf8');
      expect(observed.endsWith(dir) || dir.endsWith(observed)).toBe(true);
    },
  );
});

describe('preflightLaunch', () => {
  const catchErr = (p: Promise<unknown>): Promise<unknown> => p.then(() => null).catch((e) => e);

  test('a path-qualified command that exists resolves', async () => {
    await expect(
      preflightLaunch({
        cmd: process.execPath,
        args: [],
        env: {},
        kind: 'custom',
        pathFromOverlay: false,
      }),
    ).resolves.toBeUndefined();
  });

  test('a missing npx surfaces an actionable Node.js hint', async () => {
    const err = await catchErr(
      preflightLaunch({
        cmd: 'npx',
        args: ['-y', 'x'],
        env: { PATH: '' },
        kind: 'npx',
        pathFromOverlay: true,
      }),
    );
    expect(err).toBeInstanceOf(AgentLaunchError);
    expect((err as AgentLaunchError).code).toBe('command-not-found');
    expect((err as AgentLaunchError).message).toContain('Node.js');
  });

  test('a missing uvx surfaces an actionable uv hint', async () => {
    const err = await catchErr(
      preflightLaunch({
        cmd: 'uvx',
        args: [],
        env: { PATH: '' },
        kind: 'uvx',
        pathFromOverlay: true,
      }),
    );
    expect(err).toBeInstanceOf(AgentLaunchError);
    expect((err as AgentLaunchError).message).toContain('uv');
  });

  test('a bare command is found via a PATH search', async () => {
    const dir = tmp();
    const name = process.platform === 'win32' ? 'fakeagent.cmd' : 'fakeagent';
    writeFileSync(join(dir, name), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
    await expect(
      preflightLaunch({
        cmd: 'fakeagent',
        args: [],
        env: { PATH: dir },
        kind: 'custom',
        pathFromOverlay: true,
      }),
    ).resolves.toBeUndefined();
  });

  test('a missing binary distribution reports the offending path', async () => {
    const missing = join(tmp(), 'does-not-exist-agent');
    const err = await catchErr(
      preflightLaunch({
        cmd: missing,
        args: [],
        env: {},
        kind: 'binary',
        pathFromOverlay: false,
      }),
    );
    expect(err).toBeInstanceOf(AgentLaunchError);
    expect((err as AgentLaunchError).code).toBe('command-not-found');
    expect((err as AgentLaunchError).message).toContain(missing);
  });
});

describe.skipIf(process.platform === 'win32')('probeInterpreterHealth', () => {
  const fakeNpx = (body: string): ResolvedLaunch => {
    const dir = tmp();
    writeFileSync(join(dir, 'npx'), `#!/bin/sh\n${body}\n`, { mode: 0o755 });
    return {
      cmd: 'npx',
      args: ['-y', '@fake/agent'],
      env: { PATH: dir },
      kind: 'npx',
      pathFromOverlay: true,
    };
  };

  test('an interpreter that answers --version is healthy', async () => {
    await expect(probeInterpreterHealth(fakeNpx('exit 0'))).resolves.toBeNull();
  });

  test('a non-zero exit reports the code and the first stderr line', async () => {
    const detail = await probeInterpreterHealth(fakeNpx('echo "cannot find module" >&2\nexit 3'));
    expect(detail).toContain('exit code 3');
    expect(detail).toContain('cannot find module');
  });

  test('a crash reports the signal with the linker message', async () => {
    const detail = await probeInterpreterHealth(
      fakeNpx('echo "dyld[1]: Library not loaded: libicui18n.74.dylib" >&2\nkill -ABRT $$'),
    );
    expect(detail).toContain('SIGABRT');
    expect(detail).toContain('libicui18n.74.dylib');
  });

  test('a failure with a silent stderr still reports the exit code', async () => {
    expect(await probeInterpreterHealth(fakeNpx('exit 9'))).toBe('exit code 9');
  });

  test('an unspawnable command reports the spawn error rather than throwing', async () => {
    const detail = await probeInterpreterHealth({
      cmd: join(tmp(), 'not-a-real-npx'),
      args: [],
      env: {},
      kind: 'npx',
      pathFromOverlay: false,
    });
    expect(detail).not.toBeNull();
  });

  test('a hung probe times out as healthy and does not leak the process', async (ctx) => {
    ctx.skip(!pid1Reaps, 'PID 1 must reap the orphans this test waits on');
    const dir = tmp();
    const kidPidFile = join(dir, 'kid.pid');
    writeFileSync(
      join(dir, 'npx'),
      `#!/bin/sh\n(n=0; while [ "$n" -lt ${GRANDCHILD_SELF_EXIT_MS / 50} ]; do /bin/sleep 0.05; n=$((n + 1)); done) &\necho $! > ${kidPidFile}\nwait\n`,
      { mode: 0o755 },
    );
    const launch: ResolvedLaunch = {
      cmd: 'npx',
      args: [],
      env: { PATH: dir },
      kind: 'npx',
      pathFromOverlay: true,
    };
    const publishedKidPid = (): string =>
      existsSync(kidPidFile) ? readFileSync(kidPidFile, 'utf8').trim() : '';

    const PROBE_TIMEOUT_MS = 500;
    let kidPid = 0;
    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
    try {
      let settledEarly: string | null | undefined;
      const verdict = probeInterpreterHealth(launch, PROBE_TIMEOUT_MS).then(
        (detail) => (settledEarly = detail),
      );

      await waitFor(
        () => publishedKidPid() !== '' || settledEarly !== undefined,
        5_000,
        'the fixture to publish its grandchild pid',
      );
      kidPid = Number(publishedKidPid());

      expect(
        settledEarly,
        'the probe settled before the fixture ever published a grandchild pid',
      ).toBeUndefined();
      expect(
        Number.isInteger(kidPid) && kidPid > 0,
        `the fixture published an unusable grandchild pid: ${JSON.stringify(publishedKidPid())}`,
      ).toBe(true);
      expect(isAlive(kidPid), 'the fixture published a grandchild pid already dead').toBe(true);

      await realTimePause(PROBE_TIMEOUT_MS + 100);
      expect(
        isAlive(kidPid),
        'the probe deadline fired on real time — the fake-timer hold is not in effect',
      ).toBe(true);

      await vi.advanceTimersByTimeAsync(PROBE_TIMEOUT_MS);
      await expect(verdict).resolves.toBeNull();
    } finally {
      await vi.runAllTimersAsync();
      vi.useRealTimers();
    }
    await waitFor(() => !isAlive(kidPid), 5_000, 'the detached grandchild to die');
  }, 20_000);
});

describe.skipIf(process.platform === 'win32')('probeNpxNodeCompatibility', () => {
  const launchWithNodeVersion = (body: string): ResolvedLaunch => {
    const dir = tmp();
    writeFileSync(join(dir, 'node'), `#!/bin/sh\n${body}\n`, { mode: 0o755 });
    return {
      cmd: 'npx',
      args: ['-y', '@fake/agent'],
      env: { PATH: dir },
      kind: 'npx',
      pathFromOverlay: true,
    };
  };

  test(`accepts Node ${MINIMUM_NPX_NODE_MAJOR}`, async () => {
    await expect(
      probeNpxNodeCompatibility(launchWithNodeVersion(`echo v${MINIMUM_NPX_NODE_MAJOR}.0.0`)),
    ).resolves.toBeNull();
  });

  test('rejects a runnable Node 16 with the found and required versions', async () => {
    const detail = await probeNpxNodeCompatibility(launchWithNodeVersion('echo v16.14.2'));
    expect(detail).toContain('Node.js v16.14.2 is incompatible');
    expect(detail).toContain(`Node.js ${MINIMUM_NPX_NODE_MAJOR} or newer is required`);
  });

  test('fails closed when the runtime does not report a recognizable version', async () => {
    await expect(
      probeNpxNodeCompatibility(launchWithNodeVersion('echo unknown')),
    ).resolves.toContain('unrecognized version');
  });

  test('a hung version probe times out as unknown instead of incompatible', async () => {
    await expect(
      probeNpxNodeCompatibility(launchWithNodeVersion('while :; do /bin/sleep 1; done'), 100),
    ).resolves.toBeNull();
  });

  test('fails closed when Node is missing from the selected PATH', async () => {
    const launch: ResolvedLaunch = {
      cmd: 'npx',
      args: ['-y', '@fake/agent'],
      env: { PATH: tmp() },
      kind: 'npx',
      pathFromOverlay: true,
    };
    await expect(probeNpxNodeCompatibility(launch)).resolves.toContain(
      'Node.js version probe failed',
    );
  });

  test('fails closed when Node exits successfully without a version', async () => {
    await expect(probeNpxNodeCompatibility(launchWithNodeVersion('exit 0'))).resolves.toContain(
      'returned no version',
    );
  });

  test('the dead-end hint explains compatibility rather than claiming Node is missing', () => {
    const launch = launchWithNodeVersion('echo v16.14.2');
    const hint = incompatibleNodeHint(launch, 'Node.js v16.14.2 is incompatible');
    expect(hint).toContain('selected Node.js runtime');
    expect(hint).toContain('private compatible copy');
    expect(hint).not.toContain('was not found');
  });
});

describe('brokenInterpreterHint', () => {
  test('names Node.js for npx and points at the Homebrew icu4c cause', () => {
    const hint = brokenInterpreterHint(
      { cmd: 'npx', args: [], env: {}, kind: 'npx', pathFromOverlay: false },
      'SIGABRT',
    );
    expect(hint).toContain('Node.js');
    expect(hint).toContain('icu4c');
    expect(hint).not.toContain('was not found');
  });

  test('names uv for uvx, with no Node-specific cause pasted in', () => {
    const hint = brokenInterpreterHint(
      { cmd: 'uvx', args: [], env: {}, kind: 'uvx', pathFromOverlay: false },
      'exit code 1',
    );
    expect(hint).toContain('uv');
    expect(hint).not.toContain('Node.js');
    expect(hint).not.toContain('node');
    expect(hint).not.toContain('icu4c');
  });

  test("a replacement that still won't run blames the machine, not the user", () => {
    const hint = unrepairableManagedRuntimeHint(
      {
        cmd: '/home/u/.ok/runtimes/node/bin/npx',
        args: [],
        env: {},
        kind: 'npx',
        pathFromOverlay: false,
      },
      'SIGABRT',
    );
    expect(hint).toContain('SIGABRT');
    expect(hint).not.toContain('delete that directory');
    expect(hint).not.toContain('Reinstall or repair');
    expect(hint).not.toContain('icu4c');
  });

  test('the managed-runtime hints name uv for a uvx runtime', () => {
    const uvx: ResolvedLaunch = {
      cmd: '/home/u/.ok/runtimes/uv/uvx',
      args: [],
      env: {},
      kind: 'uvx',
      pathFromOverlay: false,
    };
    for (const hint of [
      unrepairableManagedRuntimeHint(uvx, 'SIGABRT'),
      undeletableManagedRuntimeHint(uvx, 'SIGABRT'),
      declinedRepairHint(uvx),
    ]) {
      expect(hint).toContain('uv');
      expect(hint).not.toContain('Node.js');
    }
  });

  test('the un-replaceable hint does not claim a fresh copy was tried', () => {
    const hint = undeletableManagedRuntimeHint(
      {
        cmd: '/home/u/.ok/runtimes/node/bin/npx',
        args: [],
        env: {},
        kind: 'npx',
        pathFromOverlay: false,
      },
      'SIGABRT',
    );
    expect(hint).toContain('damaged');
    expect(hint).not.toContain('downloaded a fresh copy');
  });

  test('the declined-repair hint says damaged, not missing', () => {
    const hint = declinedRepairHint({
      cmd: '/home/u/.ok/runtimes/node/bin/npx',
      args: [],
      env: {},
      kind: 'npx',
      pathFromOverlay: false,
    });
    expect(hint).toContain('damaged');
    expect(hint).not.toContain("isn't installed");
  });
});

describe('windows cmd wrapping (spawn on Windows)', () => {
  test('resolveWindowsCommand leaves path-qualified commands untouched', () => {
    expect(resolveWindowsCommand('C:\\x\\uvx.exe', 'C:\\x')).toBe('C:\\x\\uvx.exe');
    expect(resolveWindowsCommand('/usr/bin/uvx', undefined)).toBe('/usr/bin/uvx');
  });

  test('resolveWindowsCommand picks the .cmd/.exe, never a bare extensionless file', () => {
    const dir = tmp();
    writeFileSync(join(dir, 'npx'), '#!/bin/sh\n');
    writeFileSync(join(dir, 'npx.cmd'), '@echo off\n');
    const resolved = resolveWindowsCommand('npx', dir);
    expect(resolved).not.toBe(join(dir, 'npx'));
    if (resolved !== 'npx') expect(/\.cmd$/i.test(resolved)).toBe(true);
  });

  test('the npx compatibility probe selects the node.exe beside the resolved shim', () => {
    const priorPathExt = process.env.PATHEXT;
    try {
      process.env.PATHEXT = '.cmd;.exe';
      const earlier = tmp();
      const npmBin = tmp();
      writeFileSync(join(earlier, 'node.exe'), 'unrelated node');
      writeFileSync(join(npmBin, 'npx.cmd'), '@echo off\n');
      writeFileSync(join(npmBin, 'node.exe'), 'npm shim node');
      const launch: ResolvedLaunch = {
        cmd: 'npx',
        args: ['-y', '@fake/agent'],
        env: { PATH: [earlier, npmBin].join(delimiter) },
        kind: 'npx',
        pathFromOverlay: true,
      };

      expect(resolveNpxNodeCommand(launch, 'win32')).toBe(join(npmBin, 'node.exe'));
    } finally {
      if (priorPathExt === undefined) delete process.env.PATHEXT;
      else process.env.PATHEXT = priorPathExt;
    }
  });

  test('outer-quotes the whole command so a spaced launcher path survives /s', () => {
    const { cmd, args } = windowsCmdWrap('C:\\Program Files\\nodejs\\npx.cmd', ['-y', 'pkg']);
    expect(cmd.toLowerCase()).toContain('cmd');
    expect(args.slice(0, 3)).toEqual(['/d', '/s', '/c']);
    expect(args[3]).toBe('""C:\\Program Files\\nodejs\\npx.cmd" -y pkg"');
  });

  test('quotes args that would otherwise split or be interpreted by cmd', () => {
    const { args } = windowsCmdWrap('tool', ['a b', 'safe', 'a&b', '']);
    expect(args[3]).toBe('""tool" "a b" safe "a&b" """');
  });
});

describe('terminateAgentTree', () => {
  test('a compliant agent exits on SIGTERM within the grace window', async () => {
    const dir = tmp();
    const script = join(dir, 'compliant.mjs');
    writeFileSync(script, 'setInterval(() => {}, 1000);\n');
    const child = spawnAcpAgent(launchFor(script), dir);
    if (child.pid !== undefined) strayChildren.push(child);
    await waitFor(() => child.pid !== undefined, 2_000, 'spawn');

    const dead = await terminateAgentTree(child, { graceMs: 3_000 });
    expect(dead).toBe(true);
    expect(child.pid !== undefined && isAlive(child.pid)).toBe(false);
    expect(child.signalCode).toBe('SIGTERM');
  });

  test('a SIGTERM-ignoring wrapper AND its grandchild both die via group escalation', async () => {
    const dir = tmp();
    const kidPidFile = join(dir, 'kid.pid');
    const script = join(dir, 'stubborn.mjs');
    writeFileSync(
      script,
      [
        "import { spawn } from 'node:child_process';",
        "import { renameSync, writeFileSync } from 'node:fs';",
        "process.on('SIGTERM', () => {});",
        'const kid = spawn(process.execPath, [',
        "  '-e',",
        `  "process.on('SIGTERM', () => {}); setTimeout(() => process.exit(0), ${GRANDCHILD_SELF_EXIT_MS});",`,
        "], { stdio: 'ignore' });",
        "const pendingPidFile = process.env.KID_PID_FILE + '.pending';",
        'writeFileSync(pendingPidFile, String(kid.pid));',
        'renameSync(pendingPidFile, process.env.KID_PID_FILE);',
        'setInterval(() => {}, 1000);',
        '',
      ].join('\n'),
    );
    const child = spawnAcpAgent(launchFor(script, { KID_PID_FILE: kidPidFile }), dir);
    if (child.pid !== undefined) strayChildren.push(child);
    await waitFor(() => existsSync(kidPidFile), 5_000, 'grandchild pid file');
    const kidPid = Number(readFileSync(kidPidFile, 'utf8'));
    expect(Number.isInteger(kidPid) && kidPid > 0).toBe(true);
    expect(isAlive(kidPid)).toBe(true);

    const dead = await terminateAgentTree(child, { graceMs: 250 });
    expect(dead).toBe(true);
    expect(child.pid !== undefined && isAlive(child.pid)).toBe(false);
    await waitFor(() => !isAlive(kidPid), 2_000, 'grandchild death');
  });
});

describe('startup package policy classification', () => {
  const launch: ResolvedLaunch = {
    cmd: 'npx',
    args: [],
    env: {},
    kind: 'npx',
    pathFromOverlay: false,
  };
  test.each([
    'npm error code E401',
    'npm error code EINTEGRITY',
    'npm error code ECONNREFUSED',
    'npm error code ETARGET\nnpm error notarget No matching version found',
  ])('preserves the initialization failure for %s', (stderr) => {
    expect(packageAcquisitionFailure(launch, stderr)).toBeNull();
  });
  test('recognizes only a dated npm target refusal', () => {
    const detail =
      'npm error code ETARGET\nnpm error notarget No matching version found with a date before 1970-01-01';
    const cause = new Error('initialize transport closed');
    expect(packageAcquisitionFailure(launch, detail, cause)).toMatchObject({
      code: 'install-failed',
      cause,
      machineDetail: detail,
      message: expect.stringContaining('release-date policy'),
    });
  });
  test('distinguishes uv cutoff refusal from another dependency failure', () => {
    const uv: ResolvedLaunch = { ...launch, kind: 'uvx' };
    const generic = 'No solution found when resolving tool dependencies';
    expect(packageAcquisitionFailure(uv, generic)).toBeNull();
    expect(
      packageAcquisitionFailure(uv, `${generic}\nversions were filtered by \`exclude-newer\``),
    ).toMatchObject({ code: 'install-failed' });
  });
});

describe('staleNpxCacheEntry', () => {
  const npm11 = [
    'npm error code ENOENT',
    'npm error syscall open',
    'npm error path /Users/andrew/.npm/_npx/4142609e2aa780f6/package.json',
    'npm error errno -2',
    "npm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '/Users/andrew/.npm/_npx/4142609e2aa780f6/package.json'",
    'npm error enoent This is related to npm not being able to find a file.',
  ].join('\n');

  test('names the npx cache entry npm could not read', () => {
    expect(staleNpxCacheEntry(npm11)).toBe('/Users/andrew/.npm/_npx/4142609e2aa780f6');
  });

  test('reads the older npm ERR! spelling and a Windows cache path', () => {
    const detail =
      'npm ERR! code ENOENT\r\nnpm ERR! path C:\\Users\\Ann Smith\\AppData\\Local\\npm-cache\\_npx\\1a2b3c4d5e6f7a8b\\package.json\r\nnpm ERR! errno -4058\r\n';
    expect(staleNpxCacheEntry(detail)).toBe(
      'C:\\Users\\Ann Smith\\AppData\\Local\\npm-cache\\_npx\\1a2b3c4d5e6f7a8b',
    );
  });

  test('falls back to the quoted path of the failed open', () => {
    const detail =
      "npm error code ENOENT\nnpm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '/home/ann/.cache/npm/_npx/deadbeef00/package.json'";
    expect(staleNpxCacheEntry(detail)).toBe('/home/ann/.cache/npm/_npx/deadbeef00');
  });

  test.each([
    [
      'a failure other than ENOENT',
      'npm error code E401\nnpm error path /Users/andrew/.npm/_npx/4142609e2aa780f6/package.json',
    ],
    [
      'a path outside the npx cache',
      'npm error code ENOENT\nnpm error path /Users/andrew/project/package.json',
    ],
    [
      'a cache entry that is not a hash',
      'npm error code ENOENT\nnpm error path /Users/andrew/.npm/_npx/not-a-hash/package.json',
    ],
    [
      'a file other than package.json',
      'npm error code ENOENT\nnpm error path /Users/andrew/.npm/_npx/4142609e2aa780f6/package-lock.json',
    ],
    [
      'a relative path',
      'npm error code ENOENT\nnpm error path .npm/_npx/4142609e2aa780f6/package.json',
    ],
    [
      'a parent segment',
      'npm error code ENOENT\nnpm error path /tmp/../_npx/4142609e2aa780f6/package.json',
    ],
  ])('ignores %s', (_label, detail) => {
    expect(staleNpxCacheEntry(detail)).toBeNull();
  });
});

describe('npxInstallRefused', () => {
  const refusal =
    'npm error npx canceled due to missing packages and no YES option: ["[email protected]"]';

  test("recognizes npm's refusal to install a missing package", () => {
    expect(npxInstallRefused(`${refusal}\n`)).toBe(true);
  });

  test('reads the older npm ERR! spelling', () => {
    expect(
      npxInstallRefused(
        'npm ERR! npx canceled due to missing packages and no YES option: ["[email protected]"]\r\n',
      ),
    ).toBe(true);
  });

  test('finds the refusal after an npm notice line', () => {
    expect(
      npxInstallRefused(
        `npm notice New major version of npm available! 11.19.0 -> 12.2.0\n${refusal}\n`,
      ),
    ).toBe(true);
  });

  test('reads a refusal npm printed with color=always', () => {
    expect(
      npxInstallRefused(
        '\u001b[1mnpm\u001b[22m \u001b[31merror\u001b[39m npx canceled due to missing packages and no YES option: ["[email protected]"]\n',
      ),
    ).toBe(true);
  });

  test.each([
    [
      'a missing file',
      "npm error code ENOENT\nnpm error syscall open\nnpm error path /Users/andrew/.npm/_npx/4142609e2aa780f6/package.json\nnpm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '/Users/andrew/.npm/_npx/4142609e2aa780f6/package.json'",
    ],
    ['a missing version', 'npm error code ETARGET\nnpm error notarget No matching version found'],
  ])('ignores %s', (_label, detail) => {
    expect(npxInstallRefused(detail)).toBe(false);
  });
});

test('diagnostic stderr hands each kept line to the raw inspector before redaction', () => {
  const raw: string[] = [];
  const lines: string[] = [];
  const capture = createDiagnosticStderrCapture(
    (line) => lines.push(line),
    (line) => raw.push(line),
  );
  capture.write('npm error path /Users/andrew/.npm/_npx/4142609e2aa780f6/package.json\n');
  capture.write(`https://alice:${'x'.repeat(16_000)}\n`);
  capture.end();
  expect(raw).toEqual(['npm error path /Users/andrew/.npm/_npx/4142609e2aa780f6/package.json']);
  expect(lines).toEqual([
    'npm error path ~/.npm/_npx/4142609e2aa780f6/package.json',
    '[oversized diagnostic line omitted]',
  ]);
});

test.each(['npx', 'uvx'] as const)('%s startup policy diagnostics redact credentials', (kind) => {
  const signature =
    kind === 'npx'
      ? 'ETARGET No matching version found with a date before 1970-01-01'
      : 'No solution found when resolving tool dependencies; filtered by `exclude-newer`';
  const detail = `https://alice:fixture-long-secret${'z'.repeat(16_000)}@registry.example.test/pkg\n${signature} https://[email protected]:[email protected]/pkg https://alice:[email protected]/pkg https://[email protected]/simple https://github_pat_${'a'.repeat(30)}@registry.example.test/pkg Authorization: Bearer fixture-token`;
  const failure = packageAcquisitionFailure(
    { cmd: kind, args: [], env: {}, kind, pathFromOverlay: false },
    detail,
  );
  expect(failure?.machineDetail).toContain(signature);
  expect(failure?.machineDetail).not.toMatch(
    /fixture-secret|fixture-multi-secret|fixture-long-secret|fixture-token|github_pat_|0123456789abcdef|z{20}/,
  );
});

test.each([
  'https://[email protected]/simple Authorization: Bearer fixture-token\n',
  'https://[email protected]:[email protected]/simple Authorization: Bearer fixture-token\n',
])('diagnostic stderr redaction is independent of chunk boundaries: %s', (input) => {
  for (let split = 0; split <= input.length; split += 1) {
    const lines: string[] = [];
    const capture = createDiagnosticStderrCapture((line) => lines.push(line));
    capture.write(input.slice(0, split));
    capture.write(input.slice(split));
    capture.end();
    expect(lines.join('\n')).toContain('pypi.company.com/simple');
    expect(lines.join('\n')).not.toMatch(/0123456789abcdef|fixture-token|fixture-multi-secret/);
  }
});

test('diagnostic stderr omits oversized lines through their end and resumes safely', () => {
  const lines: string[] = [];
  const capture = createDiagnosticStderrCapture((line) => lines.push(line));
  capture.write(`https://alice:${'x'.repeat(16_000)}`);
  capture.write('[email protected]');
  capture.write('\nnext diagnostic\n');
  capture.end();
  expect(lines).toEqual(['[oversized diagnostic line omitted]', 'next diagnostic']);
});

test('diagnostic stderr flushes a final line without a newline', () => {
  const lines: string[] = [];
  const capture = createDiagnosticStderrCapture((line) => lines.push(line));
  capture.write('https://[email protected]/simple');
  capture.end();
  expect(lines).toEqual(['https://***@pypi.company.com/simple']);
});