Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

48.0 KB
Raw Blame
import { type ChildProcess, type StdioOptions, spawn } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { closeSync, constants, createReadStream, existsSync, statSync } from 'node:fs';
import { access, chmod, readFile, stat } from 'node:fs/promises';
import { homedir } from 'node:os';
import { basename, delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
import { stripVTControlCharacters } from 'node:util';
import {
  augmentAgentSpawnPath,
  envWithoutDevChannel,
  OK_HOSTED_AGENT_ENV,
} from '@inkeep/open-knowledge-core';
import { okUserHomeDir } from '@inkeep/open-knowledge-core/server';
import { z } from 'zod';
import {
  tracedMkdir,
  tracedMkdirSync,
  tracedOpenUnlinkedSync,
  tracedRm,
  tracedWriteFile,
  tracedWriteFileSync,
} from '../fs-traced.ts';
import type { PinoLogger } from '../logger.ts';
import { downloadToFileWithSha, extractArchive, isWithin, sanitizeSegment } from './archive.ts';
import {
  ACQUISITION_DETAIL_MAX_CHARS,
  createDiagnosticStderrCapture,
  redactDiagnostic,
} from './diagnostics.ts';
import { mergeLoginShellPath, preferLoginShellPath } from './login-shell-path.ts';
import type { ManagedRuntime } from './managed-runtime.ts';
import type { CustomAgentEntry, RegistryAgent, RegistryBinaryTarget } from './registry.ts';
import { STALE_INSTALL_ARTIFACT_AGE_MS, stagedInstall } from './staged-install.ts';

export type ResolvedLaunch = {
  cmd: string;
  args: string[];
  env: Record<string, string>;
  pathFromOverlay: boolean;
} & ({ kind: 'npx' } | { kind: 'uvx' } | { kind: 'binary' } | { kind: 'custom' });

export type NpxCacheEntry = string & { readonly __brand: 'NpxCacheEntry' };

export const MINIMUM_NPX_NODE_MAJOR = 22;

const NPX_REFUSE_INSTALL = ['--yes=false', '--loglevel=error'] as const;

export class AgentLaunchError extends Error {
  readonly machineDetail?: string;
  readonly npxCacheEntry?: NpxCacheEntry;
  readonly code:
    | 'unsupported-platform'
    | 'no-distribution'
    | 'install-failed'
    | 'command-not-found';
  constructor(
    code: AgentLaunchError['code'],
    message: string,
    options?: ErrorOptions & { machineDetail?: string; npxCacheEntry?: NpxCacheEntry },
  ) {
    super(message, options);
    this.name = 'AgentLaunchError';
    this.code = code;
    this.npxCacheEntry = options?.npxCacheEntry;
    this.machineDetail =
      options?.machineDetail === undefined
        ? undefined
        : redactDiagnostic(options.machineDetail).slice(-ACQUISITION_DETAIL_MAX_CHARS);
  }
}

function defaultBinaryCacheDir(): string {
  return join(okUserHomeDir(), 'acp-agents');
}

function isDir(dir: string): boolean {
  try {
    return statSync(dir).isDirectory();
  } catch {
    return false;
  }
}

export function mergedEnv(overlay?: Record<string, string>): Record<string, string> {
  const base: Record<string, string> = {};
  for (const [k, v] of Object.entries(envWithoutDevChannel(process.env))) {
    if (k.toLowerCase() === 'npm_config_overrides') continue;
    base[k] = v;
  }
  base[pathKey(base)] = augmentAgentSpawnPath(envPath(base), {
    platform: process.platform,
    homeDir: homedir(),
    isDir,
    delimiter,
  });
  return { ...base, ...overlay };
}

export function agentSpawnPath(): string | undefined {
  return envPath(mergedEnv());
}

export function overlaySetsPath(overlay?: Record<string, string>): boolean {
  return overlay !== undefined && Object.keys(overlay).some((k) => k.toLowerCase() === 'path');
}

export function withHostedAgentMarker(env: Record<string, string>): Record<string, string> {
  return { ...env, [OK_HOSTED_AGENT_ENV]: '1' };
}

type PrepareRegistryLaunch = (launch: ResolvedLaunch) => Promise<ResolvedLaunch | null>;

type ProbedNpmOutcome = 'exact' | 'release-age-bounded';

type NpmPackageResolution = {
  outcome: 'forwarded' | ProbedNpmOutcome;
  acquired: string;
  elapsedMs: number;
};

type ResolvedNpmAcquisition =
  | { outcome: ProbedNpmOutcome; acquired: string; source: 'memo'; elapsedMs: 0 }
  | (NpmPackageResolution & { source: 'probe' | 'joined' });

type RegistryAcquisitionOptions = {
  reacquire?: boolean;
  install?: boolean;
  onAcquiring?: () => void;
  onResolved?: (resolution: ResolvedNpmAcquisition) => void;
};

export function resolveRegistryLaunch(
  agent: RegistryAgent,
  platformKey: string | null,
  log: PinoLogger,
  binaryCacheDir?: string,
): Promise<ResolvedLaunch>;
export function resolveRegistryLaunch(
  agent: RegistryAgent,
  platformKey: string | null,
  log: PinoLogger,
  binaryCacheDir: string | undefined,
  prepare: PrepareRegistryLaunch,
  acquisition?: RegistryAcquisitionOptions,
): Promise<ResolvedLaunch | null>;
export async function resolveRegistryLaunch(
  agent: RegistryAgent,
  platformKey: string | null,
  log: PinoLogger,
  binaryCacheDir: string = defaultBinaryCacheDir(),
  prepare?: PrepareRegistryLaunch,
  acquisition?: RegistryAcquisitionOptions,
): Promise<ResolvedLaunch | null> {
  let acquiringReported = false;
  const reporting: RegistryAcquisitionOptions = {
    ...acquisition,
    onAcquiring: () => {
      if (acquiringReported) return;
      acquiringReported = true;
      acquisition?.onAcquiring?.();
    },
  };
  const dist = agent.distribution;
  if (dist.npx !== undefined) {
    const raw: ResolvedLaunch = {
      cmd: 'npx',
      args: ['-y', dist.npx.package, ...(dist.npx.args ?? [])],
      env: mergedEnv(dist.npx.env),
      kind: 'npx',
      pathFromOverlay: overlaySetsPath(dist.npx.env),
    };
    const launch = prepare === undefined ? raw : await prepare(raw);
    if (launch === null) return null;
    const pin =
      /^(?<name>(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+)@(?<version>(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))$/.exec(
        dist.npx.package,
      );
    if (pin?.groups === undefined) return launch;
    const acquired = await acquireNpmPackage(
      launch,
      pin.groups.name,
      pin.groups.version,
      log,
      reporting,
    );
    if (acquisition?.install === true) {
      await ensureNpmPackageInstalled(launch, acquired, log, reporting);
      return { ...launch, args: [...NPX_REFUSE_INSTALL, acquired, ...(dist.npx.args ?? [])] };
    }
    return { ...launch, args: ['-y', acquired, ...(dist.npx.args ?? [])] };
  }
  if (dist.uvx !== undefined) {
    const pin = /^(?<name>[A-Za-z0-9][A-Za-z0-9._-]*)(?:==|@)(?<version>\d+\.\d+\.\d+)$/.exec(
      dist.uvx.package,
    );
    const args =
      pin?.groups === undefined
        ? [dist.uvx.package]
        : [
            '--from',
            `${pin.groups.name}<=${pin.groups.version}`,
            '--isolated',
            '--upgrade-package',
            pin.groups.name,
            pin.groups.name,
          ];
    const launch: ResolvedLaunch = {
      cmd: 'uvx',
      args: [...args, ...(dist.uvx.args ?? [])],
      env: mergedEnv(dist.uvx.env),
      kind: 'uvx',
      pathFromOverlay: overlaySetsPath(dist.uvx.env),
    };
    return prepare === undefined ? launch : prepare(launch);
  }
  if (dist.binary !== undefined) {
    if (platformKey === null || dist.binary[platformKey] === undefined) {
      throw new AgentLaunchError(
        'unsupported-platform',
        `${agent.name} has no build for this platform`,
      );
    }
    const target = dist.binary[platformKey];
    const root = await ensureBinaryInstalled(agent.id, agent.version, target, binaryCacheDir, log, {
      onDownloadStart: reporting.onAcquiring,
    });
    const cmd = resolve(root, target.cmd.replace(/\\/g, '/'));
    if (!isWithin(root, cmd)) {
      throw new AgentLaunchError(
        'install-failed',
        `${agent.name} manifest cmd escapes its archive`,
      );
    }
    const launch: ResolvedLaunch = {
      cmd,
      args: [...(target.args ?? [])],
      env: mergedEnv(target.env),
      kind: 'binary',
      pathFromOverlay: overlaySetsPath(target.env),
    };
    return prepare === undefined ? launch : prepare(launch);
  }
  throw new AgentLaunchError('no-distribution', `${agent.name} has no supported distribution`);
}

const npmPackedPackage = z.object({
  name: z.string(),
  version: z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/),
});
export const npmPackResult = z
  .union([
    z.array(npmPackedPackage),
    z.record(z.string(), npmPackedPackage).transform((packages) => Object.values(packages)),
  ])
  .pipe(z.tuple([npmPackedPackage]));

function stableVersionAtMost(version: string, ceiling: string): boolean {
  const upper = ceiling.split('.').map(BigInt);
  for (const [i, part] of version.split('.').map(BigInt).entries()) {
    if (part !== upper[i]) return part < upper[i];
  }
  return true;
}

function datedNpmRefusal(detail: string): boolean {
  return /\bETARGET\b/.test(detail) && /with a date before/.test(detail);
}

export function packageAcquisitionFailure(
  launch: ResolvedLaunch,
  detail: string,
  cause?: unknown,
): AgentLaunchError | null {
  const npmRefusal = launch.kind === 'npx' && datedNpmRefusal(detail);
  const uvRefusal =
    launch.kind === 'uvx' &&
    /No solution found when resolving tool dependencies/.test(detail) &&
    /filtered by `exclude-newer`/.test(detail);
  if (!npmRefusal && !uvRefusal) return null;
  return new AgentLaunchError(
    'install-failed',
    "No allowed release is available under your package manager's release-date policy. Try again after an allowed release becomes available.",
    { cause, machineDetail: detail },
  );
}

const NPM_ENOENT_PATH_LINES: readonly RegExp[] = [
  /^npm (?:error|ERR!) path (.+?)\s*$/m,
  /ENOENT: no such file or directory, open '([^'\n]+)'/,
];

const NPX_CACHE_PACKAGE_JSON =
  /^((?:[A-Za-z]:)?[\\/](?:.*[\\/])?_npx[\\/][0-9a-f]{8,64})[\\/]package\.json$/i;

const PARENT_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;

export function staleNpxCacheEntry(detail: string): NpxCacheEntry | null {
  if (!/\bENOENT\b/.test(detail)) return null;
  for (const pattern of NPM_ENOENT_PATH_LINES) {
    const path = pattern.exec(detail)?.[1];
    const entry = path === undefined ? undefined : NPX_CACHE_PACKAGE_JSON.exec(path)?.[1];
    if (entry !== undefined && !PARENT_SEGMENT.test(entry)) return entry as NpxCacheEntry;
  }
  return null;
}

export function npxInstallRefused(detail: string): boolean {
  return /^npm (?:error|ERR!) npx canceled due to missing packages and no YES option: /m.test(
    stripVTControlCharacters(detail),
  );
}

function refusesNpxInstall(args: readonly string[]): boolean {
  return NPX_REFUSE_INSTALL.every((flag, index) => args[index] === flag);
}

export function allowNpxInstall(args: readonly string[]): string[] {
  return refusesNpxInstall(args) ? ['-y', ...args.slice(NPX_REFUSE_INSTALL.length)] : [...args];
}

export function refusedNpxPackage(args: readonly string[]): string | undefined {
  return refusesNpxInstall(args) ? args[NPX_REFUSE_INSTALL.length] : undefined;
}

async function npmCommand(launch: ResolvedLaunch): Promise<string | null> {
  let npx = launch.cmd;
  if (!isPathQualified(npx)) {
    if (process.platform === 'win32') npx = resolveWindowsCommand(npx, envPath(launch.env));
    else {
      for (const dir of (envPath(launch.env) ?? '').split(delimiter)) {
        if (dir !== '' && (await isExecutableFile(join(dir, npx)))) {
          npx = join(dir, npx);
          break;
        }
      }
    }
  }
  if (!isPathQualified(npx))
    throw new AgentLaunchError(
      'install-failed',
      'Could not locate npm for the selected agent runtime.',
    );
  const npm = join(dirname(npx), basename(npx).replace(/^npx/i, 'npm'));
  return (await isExecutableFile(npm)) ? npm : null;
}

async function probeNpmPackage(
  launch: ResolvedLaunch,
  descriptor: string,
  cmd: string,
): Promise<{ code: number | null; stdout: string; detail: string }> {
  const child = spawnAcpAgent({
    ...launch,
    kind: 'npx',
    cmd,
    args: ['pack', descriptor, '--dry-run', '--ignore-scripts', '--json'],
  });
  let stdout = '';
  let stderr = '';
  let size = 0;
  let failure: string | undefined;
  const stop = (message: string): void => {
    if (failure !== undefined) return;
    failure = message;
    void terminateAgentTree(child, { graceMs: 100 });
  };
  const timer = setTimeout(() => stop('npm package acquisition timed out.'), 30_000);
  timer.unref();
  child.stdout?.setEncoding('utf8');
  child.stderr?.setEncoding('utf8');
  child.stdout?.on('data', (chunk: string) => {
    size += Buffer.byteLength(chunk);
    if (size > 16 * 1024 * 1024) stop('npm package acquisition output exceeded its limit.');
    else stdout += chunk;
  });
  const stderrCapture = createDiagnosticStderrCapture((line) => {
    stderr = `${stderr}${line}\n`.slice(-ACQUISITION_DETAIL_MAX_CHARS);
  });
  child.stderr?.on('end', stderrCapture.end);
  child.stderr?.on('data', (chunk: string) => {
    size += Buffer.byteLength(chunk);
    stderrCapture.write(chunk);
    if (size > 16 * 1024 * 1024) stop('npm package acquisition output exceeded its limit.');
  });
  child.once('error', (err) => {
    failure = err.message;
  });
  try {
    const code = await new Promise<number | null>((resolvePromise) =>
      child.once('close', resolvePromise),
    );
    const detail = `${stdout}\n${stderr}`.trim();
    if (failure !== undefined)
      throw new AgentLaunchError('install-failed', failure, { machineDetail: detail });
    return { code, stdout, detail };
  } finally {
    clearTimeout(timer);
    await terminateAgentTree(child, { graceMs: 100 });
  }
}

const ACQUISITION_FRESHNESS_MS = 60 * 60 * 1000;

type HeldNpmPackage = {
  acquired: string;
  outcome: ProbedNpmOutcome;
  probedAt: number;
};

type AcquiredNpmPackage =
  | { state: 'probing'; probe: Promise<NpmPackageResolution> }
  | ({ state: 'held' } & HeldNpmPackage)
  | ({ state: 'revalidating'; probe: Promise<NpmPackageResolution> } & HeldNpmPackage);

const acquiredNpmPackages = new Map<string, AcquiredNpmPackage>();

type InstalledNpmPackage = { state: 'installing'; install: Promise<void> } | { state: 'installed' };

const installedNpmPackages = new Map<string, InstalledNpmPackage>();

export function resetAcquisitionCache(): void {
  acquiredNpmPackages.clear();
  installedNpmPackages.clear();
}

function sortedLaunchEnv(launch: ResolvedLaunch): [string, string][] {
  return Object.entries(launch.env).sort(([left], [right]) =>
    left < right ? -1 : left > right ? 1 : 0,
  );
}

function acquisitionKey(launch: ResolvedLaunch, name: string, ceiling: string): string {
  return JSON.stringify([launch.cmd, sortedLaunchEnv(launch), name, ceiling]);
}

export function ensureNpmPackageInstalled(
  launch: ResolvedLaunch,
  acquired: string,
  log: PinoLogger,
  acquisition: RegistryAcquisitionOptions,
): Promise<void> {
  const key = JSON.stringify([launch.cmd, sortedLaunchEnv(launch), acquired]);
  const cached = installedNpmPackages.get(key);
  if (cached?.state === 'installing') {
    acquisition.onAcquiring?.();
    return cached.install;
  }
  if (cached?.state === 'installed' && acquisition.reacquire !== true) return Promise.resolve();
  acquisition.onAcquiring?.();
  const install = installNpmPackage(launch, acquired, log);
  const entry: InstalledNpmPackage = { state: 'installing', install };
  installedNpmPackages.set(key, entry);
  const replace = (next: InstalledNpmPackage | null): void => {
    if (installedNpmPackages.get(key) !== entry) return;
    if (next === null) installedNpmPackages.delete(key);
    else installedNpmPackages.set(key, next);
  };
  void install.then(
    () => replace({ state: 'installed' }),
    () => replace(null),
  );
  return install;
}

async function installNpmPackage(
  launch: ResolvedLaunch,
  acquired: string,
  log: PinoLogger,
): Promise<void> {
  const startedAt = Date.now();
  const installLaunch = {
    ...launch,
    kind: 'npx' as const,
    args: ['--yes', `--package=${acquired}`, '--call=exit 0'],
  };
  let stderr = '';
  let rawStderr = '';
  const stderrCapture = createDiagnosticStderrCapture(
    (line) => {
      stderr = `${stderr}${line}\n`.slice(-ACQUISITION_DETAIL_MAX_CHARS);
    },
    (rawLine) => {
      rawStderr = `${rawStderr}${rawLine}\n`.slice(-ACQUISITION_DETAIL_MAX_CHARS);
    },
  );
  const { code, signal, spawnFailure } =
    process.platform === 'win32'
      ? await runPipedInstall(installLaunch, acquired, stderrCapture, log)
      : await runFileBackedInstall(installLaunch, acquired, stderrCapture, log);
  if (spawnFailure === undefined && code === 0) {
    log.info(
      { package: acquired, elapsedMs: Date.now() - startedAt },
      '[acp-launch] agent package installed',
    );
    return;
  }
  const detail = `${stderr}${spawnFailure ?? ''}`.trim() || (signal ?? `exit code ${code}`);
  const npxCacheEntry = staleNpxCacheEntry(rawStderr) ?? undefined;
  if (npxCacheEntry === undefined) {
    const refusal = spawnFailure === undefined ? packageAcquisitionFailure(launch, detail) : null;
    if (refusal !== null) throw refusal;
  }
  throw new AgentLaunchError('install-failed', `Could not install ${acquired}.`, {
    machineDetail: detail,
    npxCacheEntry,
  });
}

interface InstallExit {
  code: number | null;
  signal: NodeJS.Signals | null;
  spawnFailure: string | undefined;
}

type DiagnosticStderrCapture = ReturnType<typeof createDiagnosticStderrCapture>;

function awaitInstallExit(
  child: ChildProcess,
  acquired: string,
  log: PinoLogger,
): Promise<InstallExit> {
  let spawnFailure: string | undefined;
  child.once('spawn', () => {
    log.info({ package: acquired, installPid: child.pid }, '[acp-launch] installing agent package');
  });
  child.once('error', (err) => {
    spawnFailure = err.message;
  });
  return new Promise((resolvePromise) =>
    child.once('close', (code, signal) => resolvePromise({ code, signal, spawnFailure })),
  );
}

async function runFileBackedInstall(
  launch: ResolvedLaunch & { kind: 'npx' },
  acquired: string,
  capture: DiagnosticStderrCapture,
  log: PinoLogger,
): Promise<InstallExit> {
  const stderrPath = join(acpNpxIsolatedCwd(), `.install-stderr-${process.pid}-${randomUUID()}`);
  let fd: number;
  try {
    fd = tracedOpenUnlinkedSync(stderrPath);
  } catch (err) {
    return {
      code: null,
      signal: null,
      spawnFailure: err instanceof Error ? err.message : String(err),
    };
  }
  try {
    return await awaitInstallExit(
      spawnLaunch(launch, undefined, ['ignore', 'ignore', fd]),
      acquired,
      log,
    );
  } finally {
    await replayInstallStderr(fd, capture).catch((err: unknown) => {
      log.warn(
        { err, package: acquired },
        '[acp-launch] could not read the agent package install output',
      );
    });
  }
}

async function replayInstallStderr(fd: number, capture: DiagnosticStderrCapture): Promise<void> {
  try {
    for await (const chunk of createReadStream('', {
      fd,
      start: 0,
      encoding: 'utf8',
      autoClose: false,
    })) {
      capture.write(chunk);
    }
  } finally {
    capture.end();
    closeSync(fd);
  }
}

/* UPSTREAM(libuv/libuv#1659, microsoft/terminal#12464): an inherited stdio descriptor drops
   CREATE_NO_WINDOW and Windows Terminal may show the console cmd.exe then opens. */
function runPipedInstall(
  launch: ResolvedLaunch & { kind: 'npx' },
  acquired: string,
  capture: DiagnosticStderrCapture,
  log: PinoLogger,
): Promise<InstallExit> {
  const child = spawnAcpAgent(launch);
  child.stdin?.end();
  child.stdout?.resume();
  child.stderr?.setEncoding('utf8');
  child.stderr?.on('data', capture.write);
  child.stderr?.on('end', capture.end);
  return awaitInstallExit(child, acquired, log);
}

function heldNpmPackage(entry: AcquiredNpmPackage | undefined): HeldNpmPackage | null {
  return entry === undefined || entry.state === 'probing' ? null : entry;
}

function openNpmProbe(entry: AcquiredNpmPackage | undefined): Promise<NpmPackageResolution> | null {
  return entry === undefined || entry.state === 'held' ? null : entry.probe;
}

function heldPackageStillCurrent(held: HeldNpmPackage): boolean {
  return held.outcome === 'exact' || Date.now() - held.probedAt < ACQUISITION_FRESHNESS_MS;
}

function acquireNpmPackage(
  launch: ResolvedLaunch,
  name: string,
  ceiling: string,
  log: PinoLogger,
  acquisition?: RegistryAcquisitionOptions,
): Promise<string> {
  const key = acquisitionKey(launch, name, ceiling);
  const cached = acquiredNpmPackages.get(key);
  const held = heldNpmPackage(cached);
  if (acquisition?.reacquire !== true && held !== null && heldPackageStillCurrent(held)) {
    acquisition?.onResolved?.({
      acquired: held.acquired,
      outcome: held.outcome,
      source: 'memo',
      elapsedMs: 0,
    });
    return Promise.resolve(held.acquired);
  }
  const joined = openNpmProbe(cached);
  if (joined !== null) acquisition?.onAcquiring?.();
  const probe = joined ?? beginNpmAcquisition(key, held, launch, name, ceiling, log, acquisition);
  const source: 'probe' | 'joined' = joined === null ? 'probe' : 'joined';
  return probe.then((resolved) => {
    acquisition?.onResolved?.({ ...resolved, source });
    return resolved.acquired;
  });
}

function beginNpmAcquisition(
  key: string,
  held: HeldNpmPackage | null,
  launch: ResolvedLaunch,
  name: string,
  ceiling: string,
  log: PinoLogger,
  acquisition?: RegistryAcquisitionOptions,
): Promise<NpmPackageResolution> {
  const probe = acquireNpmPackageUncached(launch, name, ceiling, log, acquisition);
  const entry: AcquiredNpmPackage =
    held === null ? { state: 'probing', probe } : { ...held, state: 'revalidating', probe };
  acquiredNpmPackages.set(key, entry);
  const replace = (next: AcquiredNpmPackage | null): void => {
    if (acquiredNpmPackages.get(key) !== entry) return;
    if (next === null) acquiredNpmPackages.delete(key);
    else acquiredNpmPackages.set(key, next);
  };
  const restore = (): void => replace(held === null ? null : { ...held, state: 'held' });
  void probe.then((resolved) => {
    if (resolved.outcome === 'forwarded') restore();
    else
      replace({
        state: 'held',
        acquired: resolved.acquired,
        outcome: resolved.outcome,
        probedAt: Date.now(),
      });
  }, restore);
  return probe;
}

async function acquireNpmPackageUncached(
  launch: ResolvedLaunch,
  name: string,
  ceiling: string,
  log: PinoLogger,
  acquisition?: RegistryAcquisitionOptions,
): Promise<NpmPackageResolution> {
  let descriptor = `${name}@${ceiling}`;
  const npm = await npmCommand(launch);
  if (npm === null) {
    log.warn(
      { package: descriptor },
      '[acp-launch] package acquisition probe skipped: no executable npm sibling; forwarding the catalog pin to npx',
    );
    return { outcome: 'forwarded', acquired: descriptor, elapsedMs: 0 };
  }
  acquisition?.onAcquiring?.();
  const probeStartedAt = Date.now();
  let result = await probeNpmPackage(launch, descriptor, npm);
  let bounded = false;
  if (result.code !== 0 && datedNpmRefusal(result.detail)) {
    bounded = true;
    descriptor = `${name}@0.0.0 - ${ceiling}`;
    result = await probeNpmPackage(launch, descriptor, npm);
  }
  if (result.code !== 0) {
    const policy = bounded && /\b(?:ETARGET|ENOVERSIONS)\b/.test(result.detail);
    throw new AgentLaunchError(
      'install-failed',
      policy
        ? `No release of ${name} at or below ${ceiling} is available under your package manager's release-date policy. Try again after an allowed release becomes available.`
        : `Could not acquire ${descriptor}.`,
      { machineDetail: result.detail },
    );
  }
  let selected: z.infer<typeof npmPackedPackage>;
  try {
    [selected] = npmPackResult.parse(JSON.parse(result.stdout));
  } catch (cause) {
    throw new AgentLaunchError(
      'install-failed',
      'npm returned invalid package acquisition metadata.',
      { cause, machineDetail: result.detail },
    );
  }
  if (
    selected.name !== name ||
    !stableVersionAtMost(selected.version, ceiling) ||
    (!bounded && selected.version !== ceiling)
  ) {
    throw new AgentLaunchError(
      'install-failed',
      `npm returned ${selected.name}@${selected.version} outside the requested constraint ${descriptor}.`,
      { machineDetail: result.detail },
    );
  }
  return {
    outcome: bounded ? 'release-age-bounded' : 'exact',
    acquired: `${name}@${selected.version}`,
    elapsedMs: Date.now() - probeStartedAt,
  };
}

export function resolveCustomLaunch(entry: CustomAgentEntry): ResolvedLaunch {
  return {
    cmd: entry.command,
    args: [...(entry.args ?? [])],
    env: mergedEnv(entry.env),
    kind: 'custom',
    pathFromOverlay: overlaySetsPath(entry.env),
  };
}

export function rewriteLaunchToManagedRuntime(
  launch: ResolvedLaunch,
  runtime: ManagedRuntime,
): ResolvedLaunch {
  const env = { ...launch.env };
  env[pathKey(env)] = prependPath(runtime.binDir, envPath(env));
  const pathFromOverlay = launch.pathFromOverlay;
  if (runtime.kind === 'node') {
    env.npm_config_cache = runtime.cacheDir;
    return { cmd: runtime.npxBin, args: [...launch.args], env, kind: 'npx', pathFromOverlay };
  }
  env.UV_CACHE_DIR = runtime.cacheDir;
  return { cmd: runtime.uvxBin, args: [...launch.args], env, kind: 'uvx', pathFromOverlay };
}

export function withLoginShellPath(launch: ResolvedLaunch, loginShellPath: string): ResolvedLaunch {
  return { ...launch, env: withLoginShellPathEnv(launch.env, loginShellPath) };
}

export function withPreferredLoginShellPath(
  launch: ResolvedLaunch,
  loginShellPath: string,
): ResolvedLaunch {
  const env = { ...launch.env };
  env[pathKey(env)] = preferLoginShellPath(envPath(env), loginShellPath, delimiter);
  return { ...launch, env };
}

export function withLoginShellPathEnv(
  env: Record<string, string>,
  loginShellPath: string,
): Record<string, string> {
  const next = { ...env };
  next[pathKey(next)] = mergeLoginShellPath(envPath(next), loginShellPath, delimiter);
  return next;
}

function pathKey(env: Record<string, string>): string {
  for (const k of Object.keys(env)) {
    if (k.toLowerCase() === 'path') return k;
  }
  return 'PATH';
}

function prependPath(dir: string, existing: string | undefined): string {
  return existing !== undefined && existing !== '' ? `${dir}${delimiter}${existing}` : dir;
}

export interface EnsureBinaryInstallOptions {
  fetchImpl?: typeof fetch;
  onDownloadStart?: () => void;
  beforeCommit?: () => Promise<void>;
  commitLockTimeoutMs?: number;
}

async function findInstalledBinary(
  versionDir: string,
  target: RegistryBinaryTarget,
  log: PinoLogger,
): Promise<string | null> {
  try {
    if (!(await stat(versionDir)).isDirectory()) return null;
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
      log.warn({ err, versionDir }, '[acp-launch] could not inspect cached agent binary');
    }
    return null;
  }

  const cmdPath = resolve(versionDir, target.cmd.replace(/\\/g, '/'));
  if (!isWithin(versionDir, cmdPath)) return null;
  if (!(await isExecutableFile(cmdPath))) {
    return null;
  }
  return versionDir;
}

class DeterministicInstallError extends Error {}

function installFailureMarkerPath(agentDir: string, version: string): string {
  return join(agentDir, `.install-failed-${sanitizeSegment(version)}`);
}

async function readInstallFailureMarker(
  markerPath: string,
  target: RegistryBinaryTarget,
  log: PinoLogger,
): Promise<string | null> {
  let mtimeMs: number;
  let raw: string;
  try {
    mtimeMs = (await stat(markerPath)).mtimeMs;
    raw = await readFile(markerPath, 'utf8');
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
      log.warn({ err, markerPath }, '[acp-launch] could not read the install failure marker');
    }
    return null;
  }
  if (Date.now() - mtimeMs > STALE_INSTALL_ARTIFACT_AGE_MS) return null;
  try {
    const parsed = JSON.parse(raw) as Record<string, unknown>;
    if (
      parsed.archive !== target.archive ||
      parsed.cmd !== target.cmd ||
      parsed.sha256 !== (target.sha256 ?? null)
    ) {
      return null;
    }
    return typeof parsed.reason === 'string' ? parsed.reason : null;
  } catch {
    log.warn(
      { markerPath },
      '[acp-launch] install failure marker is malformed — treating it as absent',
    );
    return null;
  }
}

async function writeInstallFailureMarker(
  markerPath: string,
  target: RegistryBinaryTarget,
  reason: string,
  log: PinoLogger,
): Promise<void> {
  const payload = JSON.stringify({
    archive: target.archive,
    cmd: target.cmd,
    sha256: target.sha256 ?? null,
    reason,
  });
  await tracedWriteFile(markerPath, payload).catch((err) => {
    log.warn({ err, markerPath }, '[acp-launch] could not record the failed binary install');
  });
}

interface InFlightBinaryInstall {
  result: Promise<string>;
  downloading: boolean;
  downloadStartListeners: Array<() => void>;
}

const inFlightBinaryInstalls = new Map<string, InFlightBinaryInstall>();

export function ensureBinaryInstalled(
  id: string,
  version: string,
  target: RegistryBinaryTarget,
  cacheDir: string,
  log: PinoLogger,
  opts: EnsureBinaryInstallOptions = {},
): Promise<string> {
  const key = JSON.stringify([
    resolve(cacheDir),
    id,
    version,
    target.archive,
    target.cmd,
    target.sha256 ?? null,
  ]);
  const running = inFlightBinaryInstalls.get(key);
  if (running !== undefined) {
    if (opts.onDownloadStart !== undefined) {
      if (running.downloading) opts.onDownloadStart();
      else running.downloadStartListeners.push(opts.onDownloadStart);
    }
    return running.result;
  }
  const entry: InFlightBinaryInstall = {
    result: Promise.resolve(''),
    downloading: false,
    downloadStartListeners: opts.onDownloadStart === undefined ? [] : [opts.onDownloadStart],
  };
  entry.result = installBinary(id, version, target, cacheDir, log, {
    ...opts,
    onDownloadStart: () => {
      entry.downloading = true;
      for (const notify of entry.downloadStartListeners) notify();
    },
  }).finally(() => inFlightBinaryInstalls.delete(key));
  inFlightBinaryInstalls.set(key, entry);
  return entry.result;
}

async function installBinary(
  id: string,
  version: string,
  target: RegistryBinaryTarget,
  cacheDir: string,
  log: PinoLogger,
  opts: EnsureBinaryInstallOptions,
): Promise<string> {
  const versionDir = join(cacheDir, sanitizeSegment(id), sanitizeSegment(version));
  const markerPath = installFailureMarkerPath(dirname(versionDir), version);
  try {
    return await stagedInstall<string>({
      versionDir,
      stagingLabel: sanitizeSegment(version),
      findInstalled: () => findInstalledBinary(versionDir, target, log),
      prepare: async (stagingDir) => {
        const remembered = await readInstallFailureMarker(markerPath, target, log);
        if (remembered !== null) {
          throw new Error(
            `${remembered} (remembered from a recent attempt — retried when the manifest changes or after a day)`,
          );
        }
        await tracedRm(markerPath, { force: true });
        opts.onDownloadStart?.();
        log.info({ id, version, archive: target.archive }, '[acp-launch] downloading agent binary');
        const isZip = /\.zip$/i.test(new URL(target.archive).pathname);
        const archivePath = join(stagingDir, isZip ? 'archive.zip' : 'archive.tar.gz');
        const downloadStartedAt = Date.now();
        const sha = await downloadToFileWithSha(target.archive, archivePath, {
          fetchImpl: opts.fetchImpl,
          onRetry: ({ attempt, receivedBytes, totalBytes, resumeFromBytes, error }) =>
            log.warn(
              { id, version, attempt, receivedBytes, totalBytes, resumeFromBytes, err: error },
              '[acp-launch] agent binary download interrupted, retrying',
            ),
        });
        log.info(
          { id, version, elapsedMs: Date.now() - downloadStartedAt },
          '[acp-launch] agent binary downloaded',
        );
        if (target.sha256 !== undefined) {
          if (sha !== target.sha256.toLowerCase()) {
            throw new Error(`archive checksum mismatch: expected ${target.sha256}, got ${sha}`);
          }
        } else {
          log.warn(
            { id, version, archive: target.archive },
            '[acp-launch] manifest carries no sha256 for the binary archive — installing unverified',
          );
        }

        const extractDir = join(stagingDir, 'extracted');
        await tracedMkdir(extractDir, { recursive: true });
        await extractArchive(archivePath, extractDir, isZip);
        const cmdPath = resolve(extractDir, target.cmd.replace(/\\/g, '/'));
        if (!isWithin(extractDir, cmdPath)) {
          throw new DeterministicInstallError('manifest cmd escapes the extracted archive');
        }
        await chmod(cmdPath, 0o755).catch(() => {});
        if (!(await isExecutableFile(cmdPath))) {
          throw new DeterministicInstallError(
            `extracted agent archive has no usable command at ${target.cmd}`,
          );
        }
        return extractDir;
      },
      log,
      logPrefix: '[acp-launch]',
      logContext: { id, version },
      installedMessage: 'agent binary installed',
      missingAfterCommitMessage: 'installed agent binary not found after extract',
      beforeCommit: opts.beforeCommit,
      commitLockTimeoutMs: opts.commitLockTimeoutMs,
    });
  } catch (err) {
    if (err instanceof DeterministicInstallError) {
      await writeInstallFailureMarker(markerPath, target, err.message, log);
    }
    throw new AgentLaunchError(
      'install-failed',
      `installing ${id}@${version} failed: ${err instanceof Error ? err.message : String(err)}`,
      { cause: err },
    );
  }
}

export async function preflightLaunch(launch: ResolvedLaunch): Promise<void> {
  if (await isLaunchable(launch.cmd, envPath(launch.env))) return;
  throw new AgentLaunchError('command-not-found', missingCommandHint(launch));
}

function missingCommandHint(launch: ResolvedLaunch): string {
  switch (launch.kind) {
    case 'npx':
      return `\`${launch.cmd}\` was not found. This agent runs through npx, which ships with Node.js — install Node.js (https://nodejs.org) and make sure it is on your PATH.`;
    case 'uvx':
      return `\`${launch.cmd}\` was not found. This agent runs through uvx, which ships with uv — install uv (https://docs.astral.sh/uv/getting-started/installation/) and make sure it is on your PATH.`;
    case 'binary':
      return `the agent binary at ${launch.cmd} is missing or not executable.`;
    case 'custom':
      return `\`${launch.cmd}\` was not found on your PATH. A desktop app launched from the Dock or Finder doesn't inherit your shell's PATH, so an agent installed only in a shell-configured location won't be visible here — use an absolute path to the command, or install it to a standard location.`;
  }
}

export function brokenInterpreterHint(launch: ResolvedLaunch, detail: string): string {
  const cause =
    launch.kind === 'uvx'
      ? 'That usually means its uv is broken. Reinstall or repair uv and try again.'
      : 'That usually means its Node.js is broken — on macOS a common cause is a Homebrew `node` whose `icu4c` library was upgraded out from under it. Reinstall or repair Node.js and try again.';
  return `\`${launch.cmd}\` is installed but failed to run (${detail}). ${cause}`;
}

export function unrepairableManagedRuntimeHint(launch: ResolvedLaunch, detail: string): string {
  const runtime = launch.kind === 'uvx' ? 'uv' : 'Node.js';
  return `OK downloaded a fresh copy of ${runtime} and it still can't run (${detail}). Something on this machine is stopping it — antivirus, a security policy, or an unsupported CPU are the usual causes.`;
}

export function incompatibleManagedRuntimeHint(detail: string): string {
  return `OK's private Node.js runtime is incompatible (${detail}). Update Open Knowledge and try again.`;
}

export function undeletableManagedRuntimeHint(launch: ResolvedLaunch, detail: string): string {
  const runtime = launch.kind === 'uvx' ? 'uv' : 'Node.js';
  return `OK's own copy of ${runtime} is damaged (${detail}) and couldn't be replaced — another agent may still be using it. Close other agent threads and try again.`;
}

export function declinedRepairHint(launch: ResolvedLaunch): string {
  const runtime = launch.kind === 'uvx' ? 'uv' : 'Node.js';
  return `OK's own copy of ${runtime} is damaged and can't run this agent. Start the agent again to let OK download a fresh copy.`;
}

export function expiredRepairHint(launch: ResolvedLaunch): string {
  const runtime = launch.kind === 'uvx' ? 'uv' : 'Node.js';
  return `OK's own copy of ${runtime} is damaged and can't run this agent. The offer to download a fresh copy expired before it was answered — start the agent again to get it back.`;
}

export function expiredFallbackHint(launch: ResolvedLaunch, base: string): string {
  const runtime = launch.kind === 'uvx' ? 'uv' : 'Node.js';
  return `${base} The offer to download a private copy of ${runtime} expired before it was answered — start the agent again to get it back.`;
}

const PROBE_OUTPUT_MAX = 2_000;
const PROBE_DETAIL_MAX = 300;

export function probeInterpreterHealth(
  launch: ResolvedLaunch,
  timeoutMs = 5_000,
  log?: PinoLogger,
): Promise<string | null> {
  const win = process.platform === 'win32';
  const resolved = win ? resolveWindowsCommand(launch.cmd, envPath(launch.env)) : launch.cmd;
  const wrap = win && /\.(cmd|bat)$/i.test(resolved);
  const { cmd, args } = wrap
    ? windowsCmdWrap(resolved, ['--version'])
    : { cmd: resolved, args: ['--version'] };
  return new Promise((settleProbe) => {
    let child: ChildProcess;
    try {
      child = spawn(cmd, args, {
        env: launch.env,
        stdio: ['ignore', 'ignore', 'pipe'],
        shell: false,
        detached: !win,
        windowsHide: true,
        windowsVerbatimArguments: wrap,
      });
    } catch (err) {
      settleProbe(err instanceof Error ? err.message : String(err));
      return;
    }
    let stderr = '';
    child.stderr?.setEncoding('utf8');
    child.stderr?.on('data', (chunk: string) => {
      if (stderr.length < PROBE_OUTPUT_MAX) stderr += chunk;
    });
    let settled = false;
    const settle = (detail: string | null): void => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      settleProbe(detail);
    };
    const timer = setTimeout(() => {
      terminateAgentTree(child, { graceMs: 0, forceWaitMs: 0 }).catch(() => {});
      log?.debug(
        { cmd: launch.cmd, kind: launch.kind, timeoutMs },
        '[acp-launch] interpreter health probe timed out — proceeding with the launch',
      );
      settle(null);
    }, timeoutMs);
    timer.unref?.();
    child.on('error', (err) => settle(err.message));
    child.on('exit', (code, signal) => {
      if (signal === null && (code === null || code === 0)) {
        settle(null);
        return;
      }
      const firstStderrLine = stderr
        .split('\n')
        .map((line) => line.trim())
        .find((line) => line !== '');
      const reason = signal ?? `exit code ${code}`;
      settle(
        firstStderrLine !== undefined
          ? `${reason}: ${firstStderrLine.slice(0, PROBE_DETAIL_MAX)}`
          : reason,
      );
    });
  });
}

export function probeNpxNodeCompatibility(
  launch: ResolvedLaunch,
  timeoutMs = 5_000,
  log?: PinoLogger,
): Promise<string | null> {
  const win = process.platform === 'win32';
  const resolved = resolveNpxNodeCommand(launch);
  return new Promise((settleProbe) => {
    let child: ChildProcess;
    try {
      child = spawn(resolved, ['--version'], {
        env: launch.env,
        stdio: ['ignore', 'pipe', 'pipe'],
        shell: false,
        detached: !win,
        windowsHide: true,
      });
    } catch (err) {
      settleProbe(
        `Node.js version probe could not start: ${err instanceof Error ? err.message : String(err)}`,
      );
      return;
    }
    let stdout = '';
    let stderr = '';
    child.stdout?.setEncoding('utf8');
    child.stdout?.on('data', (chunk: string) => {
      if (stdout.length < PROBE_OUTPUT_MAX) stdout += chunk;
    });
    child.stderr?.setEncoding('utf8');
    child.stderr?.on('data', (chunk: string) => {
      if (stderr.length < PROBE_OUTPUT_MAX) stderr += chunk;
    });
    let settled = false;
    const settle = (detail: string | null): void => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      settleProbe(detail);
    };
    const timer = setTimeout(() => {
      terminateAgentTree(child, { graceMs: 0, forceWaitMs: 0 }).catch(() => {});
      log?.debug(
        { cmd: launch.cmd, kind: launch.kind, timeoutMs },
        '[acp-launch] Node.js compatibility probe timed out — proceeding with the launch',
      );
      settle(null);
    }, timeoutMs);
    timer.unref?.();
    child.on('error', (err) => settle(`Node.js version probe failed: ${err.message}`));
    child.on('close', (code, signal) => {
      if (signal !== null || (code !== null && code !== 0)) {
        const firstStderrLine = stderr
          .split('\n')
          .map((line) => line.trim())
          .find((line) => line !== '');
        const reason = signal ?? `exit code ${code}`;
        settle(
          firstStderrLine === undefined
            ? `Node.js version probe failed with ${reason}`
            : `Node.js version probe failed with ${reason}: ${firstStderrLine.slice(0, PROBE_DETAIL_MAX)}`,
        );
        return;
      }
      const version = stdout.trim();
      const match = /^v?(\d+)(?:\.|$)/.exec(version);
      if (match === null) {
        settle(
          version === ''
            ? 'Node.js version probe returned no version'
            : `Node.js reported an unrecognized version: ${version.slice(0, PROBE_DETAIL_MAX)}`,
        );
        return;
      }
      const major = Number.parseInt(match[1] ?? '', 10);
      settle(
        major >= MINIMUM_NPX_NODE_MAJOR
          ? null
          : `Node.js ${version} is incompatible; Node.js ${MINIMUM_NPX_NODE_MAJOR} or newer is required`,
      );
    });
  });
}

export function incompatibleNodeHint(launch: ResolvedLaunch, detail: string): string {
  return `\`${launch.cmd}\` cannot run this agent with the selected Node.js runtime (${detail}). Upgrade Node.js or let Open Knowledge download a private compatible copy.`;
}

export function expiredIncompatibleNodeHint(launch: ResolvedLaunch, detail: string): string {
  return `\`${launch.cmd}\` cannot run this agent with the selected Node.js runtime (${detail}). The offer to download a private compatible copy of Node.js expired before it was answered — upgrade Node.js, or start the agent again to get it back.`;
}

export function envPath(env: Record<string, string>): string | undefined {
  for (const [k, v] of Object.entries(env)) {
    if (k.toLowerCase() === 'path') return v;
  }
  return process.env.PATH;
}

export function isPathQualified(cmd: string): boolean {
  const win = process.platform === 'win32';
  return isAbsolute(cmd) || cmd.includes('/') || (win && cmd.includes('\\'));
}

async function isLaunchable(cmd: string, pathEnv: string | undefined): Promise<boolean> {
  const win = process.platform === 'win32';
  if (isPathQualified(cmd)) {
    return isExecutableFile(cmd);
  }
  const exts = win
    ? [
        '',
        ...(process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
          .split(';')
          .map((e) => e.trim())
          .filter((e) => e !== ''),
      ]
    : [''];
  for (const dir of (pathEnv ?? '').split(delimiter)) {
    if (dir === '') continue;
    for (const ext of exts) {
      if (await isExecutableFile(join(dir, cmd + ext))) return true;
    }
  }
  return false;
}

async function isExecutableFile(candidate: string): Promise<boolean> {
  try {
    const st = await stat(candidate);
    if (!st.isFile()) return false;
    if (process.platform === 'win32') return true;
    await access(candidate, constants.X_OK);
    return true;
  } catch {
    return false;
  }
}

export function resolveWindowsCommand(cmd: string, pathEnv: string | undefined): string {
  if (isAbsolute(cmd) || cmd.includes('\\') || cmd.includes('/')) return cmd;
  const exts = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
    .split(';')
    .map((e) => e.trim())
    .filter((e) => e !== '');
  for (const dir of (pathEnv ?? '').split(delimiter)) {
    if (dir === '') continue;
    for (const ext of exts) {
      const candidate = join(dir, cmd + ext);
      try {
        if (statSync(candidate).isFile()) return candidate;
      } catch {}
    }
  }
  return cmd;
}

export function resolveNpxNodeCommand(
  launch: ResolvedLaunch,
  platform: NodeJS.Platform = process.platform,
): string {
  if (platform !== 'win32') return 'node';
  const pathEnv = envPath(launch.env);
  const resolvedNpx = resolveWindowsCommand(launch.cmd, pathEnv);
  const npxWasResolved =
    resolvedNpx !== launch.cmd ||
    isAbsolute(resolvedNpx) ||
    resolvedNpx.includes('/') ||
    resolvedNpx.includes('\\');
  if (npxWasResolved) {
    const siblingNode = join(dirname(resolvedNpx), 'node.exe');
    try {
      if (statSync(siblingNode).isFile()) return siblingNode;
    } catch {}
  }
  return resolveWindowsCommand('node', pathEnv);
}

function quoteCmdArg(arg: string): string {
  if (arg === '') return '""';
  return /[\s"&()<>^|%]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg;
}

export function windowsCmdWrap(cmd: string, args: string[]): { cmd: string; args: string[] } {
  const inner = [`"${cmd}"`, ...args.map(quoteCmdArg)].join(' ');
  return { cmd: process.env.ComSpec ?? 'cmd.exe', args: ['/d', '/s', '/c', `"${inner}"`] };
}

function acpNpxIsolatedCwd(): string {
  const dir = join(okUserHomeDir(), 'acp-npx-cwd');
  tracedMkdirSync(dir, { recursive: true, mode: 0o700 });
  const marker = join(dir, 'package.json');
  if (!existsSync(marker)) {
    tracedWriteFileSync(
      marker,
      `${JSON.stringify({ name: 'openknowledge-acp-npx-isolated', version: '0.0.0', private: true }, null, 2)}\n`,
    );
  }
  return dir;
}

export function spawnAcpAgent(launch: ResolvedLaunch & { kind: 'npx' }): ChildProcess;
export function spawnAcpAgent(
  launch: Exclude<ResolvedLaunch, { kind: 'npx' }>,
  projectCwd: string,
): ChildProcess;
export function spawnAcpAgent(launch: ResolvedLaunch, projectCwd?: string): ChildProcess {
  return spawnLaunch(launch, projectCwd, ['pipe', 'pipe', 'pipe']);
}

function spawnLaunch(
  launch: ResolvedLaunch,
  projectCwd: string | undefined,
  stdio: StdioOptions,
): ChildProcess {
  if (launch.kind === 'npx' && projectCwd !== undefined) {
    throw new Error('spawnAcpAgent does not accept a project cwd for npx launches.');
  }
  if (projectCwd === undefined ? launch.kind !== 'npx' : !isAbsolute(projectCwd)) {
    throw new Error(`spawnAcpAgent requires an absolute cwd, got: ${projectCwd}`);
  }
  const cwd = launch.kind === 'npx' ? acpNpxIsolatedCwd() : projectCwd;
  const win = process.platform === 'win32';
  const resolved = win ? resolveWindowsCommand(launch.cmd, envPath(launch.env)) : launch.cmd;
  const wrap = win && /\.(cmd|bat)$/i.test(resolved);
  const { cmd, args } = wrap
    ? windowsCmdWrap(resolved, launch.args)
    : { cmd: resolved, args: launch.args };
  return spawn(cmd, args, {
    cwd,
    env: withHostedAgentMarker(launch.env),
    stdio,
    shell: false,
    detached: !win,
    windowsHide: true,
    windowsVerbatimArguments: wrap,
  });
}

function hasExited(child: ChildProcess): boolean {
  return child.exitCode !== null || child.signalCode !== null;
}

function awaitExit(child: ChildProcess, timeoutMs: number): Promise<boolean> {
  if (hasExited(child)) return Promise.resolve(true);
  return new Promise((resolvePromise) => {
    const onExit = (): void => {
      clearTimeout(timer);
      resolvePromise(true);
    };
    const timer = setTimeout(() => {
      child.removeListener('exit', onExit);
      resolvePromise(false);
    }, timeoutMs);
    timer.unref?.();
    child.once('exit', onExit);
  });
}

function signalAgentGroup(child: ChildProcess, signal: NodeJS.Signals): void {
  const pid = child.pid;
  if (pid === undefined || hasExited(child)) return;
  try {
    process.kill(-pid, signal);
    return;
  } catch {}
  try {
    child.kill(signal);
  } catch {}
}

export async function terminateAgentTree(
  child: ChildProcess,
  opts: { graceMs: number; forceWaitMs?: number },
): Promise<boolean> {
  const forceWaitMs = opts.forceWaitMs ?? 2_000;
  if (hasExited(child)) return true;
  if (process.platform === 'win32') {
    if (child.pid !== undefined) {
      try {
        spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
          stdio: 'ignore',
          shell: false,
          windowsHide: true,
        }).unref();
      } catch {
        try {
          child.kill('SIGKILL');
        } catch {}
      }
    }
    return awaitExit(child, Math.max(opts.graceMs, forceWaitMs));
  }
  signalAgentGroup(child, 'SIGTERM');
  if (await awaitExit(child, opts.graceMs)) return true;
  signalAgentGroup(child, 'SIGKILL');
  return awaitExit(child, forceWaitMs);
}