@zgeoff/atc 2.16.0 → 2.17.0

package/src/workspace/collect-remote-refs.ts

@@ -0,0 +1,154 @@
+import { createGitAskpass } from './create-git-askpass';
+import type { GitCredential } from './create-git-askpass';
+import { runGit } from './run-git';
+
+export interface RemoteRef {
+  // The short name: `main`, `feat/x`, `v1.0`.
+  readonly name: string;
+  readonly kind: 'branch' | 'tag';
+
+  // The commit the ref points at; an annotated tag's is the commit it
+  // peels to.
+  readonly sha: string;
+}
+
+interface RemoteRefListing {
+  readonly ok: true;
+
+  // The branch the upstream's HEAD points at, or null when it reports none.
+  readonly head: string | null;
+  readonly refs: readonly RemoteRef[];
+
+  // Every listed ref by full name, each annotated tag's peeled `^{}` entry
+  // beside it, for resolving one ref the way a clone does.
+  readonly byName: ReadonlyMap<string, string>;
+}
+
+interface RemoteRefRefusal {
+  readonly ok: false;
+  readonly code: 'clone_failed' | 'credential_missing';
+  readonly message: string;
+}
+
+// How long a listing may take: a host that never answers holds a client
+// waiting on it no longer than this.
+const REMOTE_TIMEOUT_MS = 20_000;
+
+/**
+ * Lists an upstream's branches and tags and the branch its HEAD points at,
+ * through one `git ls-remote` that authenticates exactly as a clone of the
+ * same URL does: through the host's git config, or through a private
+ * askpass helper for an env credential. git never prompts. A listing git
+ * cannot read is refused as `clone_failed` with git's own message, and so
+ * is one that takes longer than the time limit, 20 s unless given. git
+ * fetches only over `transports`.
+ */
+export async function collectRemoteRefs(
+  url: string,
+  credential: GitCredential | undefined,
+  transports: readonly string[],
+  timeoutMs: number = REMOTE_TIMEOUT_MS,
+): Promise<RemoteRefListing | RemoteRefRefusal> {
+  const askpass = await createGitAskpass(credential);
+
+  if (!askpass.ok) {
+    return askpass;
+  }
+
+  let listed: Awaited<ReturnType<typeof runGit>>;
+
+  try {
+    const sshEnv = await buildSSHTimeoutEnv(timeoutMs);
+
+    listed = await runGit(
+      [
+        ...askpass.args,
+        ...buildHTTPTimeoutArgs(timeoutMs),
+        'ls-remote',
+        '--symref',
+        '--',
+        url,
+        'HEAD',
+        'refs/heads/*',
+        'refs/tags/*',
+      ],
+      { env: { ...askpass.env, ...sshEnv }, timeoutMs, transports },
+    );
+  } finally {
+    await askpass[Symbol.asyncDispose]();
+  }
+
+  if (listed.timedOut) {
+    return {
+      ok: false,
+      code: 'clone_failed',
+      message: `git ls-remote did not answer within ${timeoutMs / 1000} s`,
+    };
+  }
+
+  if (listed.exitCode !== 0) {
+    return { ok: false, code: 'clone_failed', message: listed.stderr.trim() };
+  }
+
+  return parseListing(listed.stdout);
+}
+
+// An ssh connection that takes longer than the limit is given up by ssh.
+// A host that chose its own ssh command keeps it.
+async function buildSSHTimeoutEnv(timeoutMs: number): Promise<Readonly<Record<string, string>>> {
+  if (process.env['GIT_SSH_COMMAND'] !== undefined || process.env['GIT_SSH'] !== undefined) {
+    return {};
+  }
+
+  const configured = await runGit(['config', '--get', 'core.sshCommand']);
+
+  if (configured.exitCode === 0 && configured.stdout.trim() !== '') {
+    return {};
+  }
+
+  const seconds = String(Math.max(1, Math.ceil(timeoutMs / 1000)));
+
+  return { GIT_SSH_COMMAND: `ssh -o ConnectTimeout=${seconds}` };
+}
+
+// An HTTP transfer that moves under a byte a second for the whole limit is
+// given up by git itself.
+function buildHTTPTimeoutArgs(timeoutMs: number): string[] {
+  const seconds = String(Math.max(1, Math.ceil(timeoutMs / 1000)));
+
+  return ['-c', 'http.lowSpeedLimit=1', '-c', `http.lowSpeedTime=${seconds}`];
+}
+
+const SYMREF_PREFIX = 'ref: refs/heads/';
+
+function parseListing(stdout: string): RemoteRefListing {
+  const byName = new Map<string, string>();
+
+  let head: string | null = null;
+
+  for (const line of stdout.split('\n')) {
+    const [left = '', name = ''] = line.split('\t');
+
+    if (name === 'HEAD' && left.startsWith(SYMREF_PREFIX)) {
+      head = left.slice(SYMREF_PREFIX.length);
+    } else if (name.startsWith('refs/heads/') || name.startsWith('refs/tags/')) {
+      byName.set(name, left);
+    }
+  }
+
+  const refs: RemoteRef[] = [];
+
+  for (const [name, sha] of byName) {
+    if (name.startsWith('refs/heads/')) {
+      refs.push({ name: name.slice('refs/heads/'.length), kind: 'branch', sha });
+    } else if (!name.endsWith('^{}')) {
+      refs.push({
+        name: name.slice('refs/tags/'.length),
+        kind: 'tag',
+        sha: byName.get(`${name}^{}`) ?? sha,
+      });
+    }
+  }
+
+  return { ok: true, head, refs, byName };
+}

package/src/workspace/create-git-askpass.ts

@@ -0,0 +1,84 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export interface GitCredential {
+  readonly kind: 'env';
+  readonly name: string;
+}
+
+interface GitAskpass {
+  readonly ok: true;
+
+  // What each network git command takes: the variables that point it at
+  // the helper, and the arguments that switch the host's credential
+  // helpers off.
+  readonly env: Readonly<Record<string, string>>;
+  readonly args: readonly string[];
+  [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+interface MissingCredential {
+  readonly ok: false;
+  readonly code: 'credential_missing';
+  readonly message: string;
+}
+
+const ASKPASS_SECRET_VAR = 'ATC_GIT_ASKPASS_SECRET';
+
+// Username prompts get a fixed name that GitHub and GitLab both accept
+// alongside a token; password prompts get the token.
+const ASKPASS_SCRIPT = `#!/bin/sh
+case "$1" in
+  Username*) printf '%s\\n' x-access-token ;;
+  *) printf '%s\\n' "$${ASKPASS_SECRET_VAR}" ;;
+esac
+`;
+
+/**
+ * Selects how network git commands authenticate. Without a credential they
+ * authenticate through the host's own git config, and the result adds
+ * nothing. An env credential is read from the named variable and handed to
+ * git only through a private askpass helper, never through the command line
+ * or the URL, with the host's credential helpers switched off so none of
+ * them stores the token. Disposing the result deletes the helper.
+ */
+export async function createGitAskpass(
+  credential: GitCredential | undefined,
+): Promise<GitAskpass | MissingCredential> {
+  if (credential === undefined) {
+    return { ok: true, env: {}, args: [], [Symbol.asyncDispose]: async () => {} };
+  }
+
+  const secret = process.env[credential.name];
+
+  if (secret === undefined || secret === '') {
+    return {
+      ok: false,
+      code: 'credential_missing',
+      message: 'the credential environment variable is unset or empty',
+    };
+  }
+
+  const dir = await mkdtemp(join(tmpdir(), 'atc-askpass-'));
+
+  const helper = join(dir, 'askpass');
+
+  // A helper that cannot be written leaves no directory behind.
+  try {
+    await writeFile(helper, ASKPASS_SCRIPT, { mode: 0o700 });
+  } catch (error) {
+    await rm(dir, { recursive: true, force: true });
+
+    throw error;
+  }
+
+  return {
+    ok: true,
+    env: { GIT_ASKPASS: helper, [ASKPASS_SECRET_VAR]: secret },
+    args: ['-c', 'credential.helper='],
+    [Symbol.asyncDispose]: async () => {
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}

package/src/workspace/create-workspace-clone.ts

@@ -1,19 +1,18 @@
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { rm } from 'node:fs/promises';
 import { checkWorkspaceCompleteness } from './check-workspace-completeness';
+import { createGitAskpass } from './create-git-askpass';
+import type { GitCredential } from './create-git-askpass';
+import { findRemoteRef } from './find-remote-ref';
 import { runGit } from './run-git';
 import type { WorkspaceSource } from './workspace-source';
 
-interface GitCredential {
-  readonly kind: 'env';
-  readonly name: string;
-}
-
 interface CloneRequest {
   readonly source: Extract<WorkspaceSource, { readonly kind: 'git' }>;
   readonly dir: string;
   readonly credential?: GitCredential;
+
+  // The transports git may fetch over.
+  readonly transports: readonly string[];
 }
 
 interface CreatedClone {
@@ -59,7 +58,7 @@ type IncompleteCheckout = Exclude<
 export async function createWorkspaceClone(
   request: CloneRequest,
 ): Promise<CloneRefusal | CreatedClone | IncompleteCheckout> {
-  const askpass = await createAskpass(request.credential);
+  const askpass = await createGitAskpass(request.credential);
 
   if (!askpass.ok) {
     return askpass;
@@ -72,63 +71,12 @@ export async function createWorkspaceClone(
   }
 }
 
-interface Askpass {
-  readonly ok: true;
-  readonly env: Readonly<Record<string, string>>;
-  readonly args: readonly string[];
-  [Symbol.asyncDispose]: () => Promise<void>;
-}
-
-const ASKPASS_SECRET_VAR = 'ATC_GIT_ASKPASS_SECRET';
-
-// Username prompts get a fixed name that GitHub and GitLab both accept
-// alongside a token; password prompts get the token.
-const ASKPASS_SCRIPT = `#!/bin/sh
-case "$1" in
-  Username*) printf '%s\\n' x-access-token ;;
-  *) printf '%s\\n' "$${ASKPASS_SECRET_VAR}" ;;
-esac
-`;
-
-async function createAskpass(
-  credential: GitCredential | undefined,
-): Promise<Askpass | CloneRefusal> {
-  if (credential === undefined) {
-    return { ok: true, env: {}, args: [], [Symbol.asyncDispose]: async () => {} };
-  }
-
-  const secret = process.env[credential.name];
-
-  if (secret === undefined || secret === '') {
-    return {
-      ok: false,
-      code: 'credential_missing',
-      message: 'the credential environment variable is unset or empty',
-    };
-  }
-
-  const dir = await mkdtemp(join(tmpdir(), 'atc-askpass-'));
-
-  const helper = join(dir, 'askpass');
-
-  await writeFile(helper, ASKPASS_SCRIPT, { mode: 0o700 });
-
-  return {
-    ok: true,
-    env: { GIT_ASKPASS: helper, [ASKPASS_SECRET_VAR]: secret },
-    args: ['-c', 'credential.helper='],
-    [Symbol.asyncDispose]: async () => {
-      await rm(dir, { recursive: true, force: true });
-    },
-  };
-}
-
 async function createCloneAtRef(
   request: CloneRequest,
   env: Readonly<Record<string, string>>,
   args: readonly string[],
 ): Promise<CloneRefusal | CreatedClone | IncompleteCheckout> {
-  const target = await resolveRef(request.source, env, args);
+  const target = await resolveRef(request, env, args);
 
   if (!target.ok) {
     return target;
@@ -147,7 +95,7 @@ async function createCloneAtRef(
       request.source.url,
       request.dir,
     ],
-    { env },
+    { env, transports: request.transports },
   );
 
   if (clone.exitCode !== 0) {
@@ -175,9 +123,9 @@ async function createCloneAtRef(
 
     await rm(request.dir, { recursive: true, force: true });
 
-    return target.branch === null && present.exitCode !== 0
-      ? { ok: false, code: 'ref_not_found', message: `origin has no commit ${target.sha}` }
-      : { ok: false, code: 'clone_failed', message: checkout.stderr.trim() };
+    return present.exitCode === 0
+      ? { ok: false, code: 'clone_failed', message: checkout.stderr.trim() }
+      : { ok: false, code: 'ref_not_found', message: `origin has no commit ${target.sha}` };
   }
 
   const complete = await checkWorkspaceCompleteness(request.dir, target.sha);
@@ -203,20 +151,26 @@ const SHA_PATTERN = /^(?:[\da-f]{40}|[\da-f]{64})$/u;
  * Pins a ref to a commit before cloning, so the checkout is exactly the
  * commit the ref pointed at when asked, whatever lands on the branch meanwhile.
  * A branch wins over a same-named tag, and an annotated tag resolves to the
- * commit it points at.
+ * commit it points at. A source already pinned to a commit keeps it, and
+ * its ref only decides whether the checkout is on a branch: a ref that
+ * names a branch upstream checks the commit out as that branch.
  */
 async function resolveRef(
-  source: Extract<WorkspaceSource, { readonly kind: 'git' }>,
+  request: CloneRequest,
   env: Readonly<Record<string, string>>,
   args: readonly string[],
 ): Promise<CloneRefusal | ResolvedRef> {
+  const source = request.source;
+
   if (SHA_PATTERN.test(source.ref)) {
     return { ok: true, sha: source.ref, branch: null };
   }
 
+  const pinned = source.sha;
+
   const listed = await runGit(
     [...args, 'ls-remote', '--', source.url, source.ref, `${source.ref}^{}`],
-    { env },
+    { env, transports: request.transports },
   );
 
   if (listed.exitCode !== 0) {
@@ -234,18 +188,17 @@ async function resolveRef(
       }),
   );
 
-  const name = source.ref.replace(/^refs\/(?:heads|tags)\//u, '');
-  const branchSHA = refs.get(`refs/heads/${name}`);
+  const match = findRemoteRef(refs, source.ref);
 
-  if (branchSHA !== undefined && !source.ref.startsWith('refs/tags/')) {
-    return { ok: true, sha: branchSHA, branch: name };
+  if (pinned !== undefined) {
+    return { ok: true, sha: pinned, branch: match?.branch ?? null };
   }
 
-  const tagSHA = refs.get(`refs/tags/${name}^{}`) ?? refs.get(`refs/tags/${name}`);
-
-  if (tagSHA !== undefined && !source.ref.startsWith('refs/heads/')) {
-    return { ok: true, sha: tagSHA, branch: null };
+  if (match !== null) {
+    return { ok: true, ...match };
   }
 
+  const name = source.ref.replace(/^refs\/(?:heads|tags)\//u, '');
+
   return { ok: false, code: 'ref_not_found', message: `origin has no branch or tag '${name}'` };
 }

package/src/workspace/expand-git-shorthand.ts

@@ -0,0 +1,13 @@
+// A bare `owner/repo`, with or without `.git`.
+const SHORTHAND_PATTERN = /^(?<name>[\w-][\w.-]*\/[\w.-]+?)(?:\.git)?$/u;
+
+/**
+ * Expands the `owner/repo` shorthand a `session.spawn` git workspace may
+ * hold to its GitHub https URL, and returns any other URL as it is. The
+ * shorthand is the spawn API's alone: every other path takes full URLs.
+ */
+export function expandGitShorthand(raw: string): string {
+  const name = SHORTHAND_PATTERN.exec(raw.trim())?.groups?.['name'];
+
+  return name === undefined ? raw : `https://github.com/${name}.git`;
+}

package/src/workspace/find-remote-ref.ts

@@ -0,0 +1,34 @@
+interface RemoteRefMatch {
+  readonly sha: string;
+
+  // The branch the ref names, or null for a tag.
+  readonly branch: string | null;
+}
+
+/**
+ * Finds the commit a ref points at among the refs an upstream lists, keyed
+ * by full ref name with each annotated tag's peeled `^{}` entry beside it.
+ * A bare name matches a branch before a same-named tag, a `refs/heads/` or
+ * `refs/tags/` name matches only that kind, and an annotated tag resolves
+ * to the commit it points at. Null when the upstream has no such branch or
+ * tag.
+ */
+export function findRemoteRef(
+  refs: ReadonlyMap<string, string>,
+  ref: string,
+): RemoteRefMatch | null {
+  const name = ref.replace(/^refs\/(?:heads|tags)\//u, '');
+  const branchSHA = refs.get(`refs/heads/${name}`);
+
+  if (branchSHA !== undefined && !ref.startsWith('refs/tags/')) {
+    return { sha: branchSHA, branch: name };
+  }
+
+  const tagSHA = refs.get(`refs/tags/${name}^{}`) ?? refs.get(`refs/tags/${name}`);
+
+  if (tagSHA !== undefined && !ref.startsWith('refs/heads/')) {
+    return { sha: tagSHA, branch: null };
+  }
+
+  return null;
+}

package/src/workspace/normalize-git-url.ts

@@ -4,15 +4,14 @@ type NormalizedGitURL =
 
 const SCHEME_PATTERN = /^[a-z][a-z\d+.-]*:\/\//iu;
 const SCP_PATTERN = /^(?:[^@/:\s]+@)?[^@/:\s]+:[^@\s]+$/u;
-const SHORTHAND_PATTERN = /^[\w.-]+\/[\w.-]+$/u;
 
 /**
  * Reduces a repository URL to a form that carries no credential, so it can be
  * recorded, shown, and handed to another host. An http(s) URL loses its
  * userinfo, query, and fragment, where tokens ride. Any other scheme URL
  * loses its password but keeps its user, which is a login name such as
- * `git`. An scp-style `git@host:owner/repo` and a local path pass through,
- * and a bare `owner/repo` expands to its GitHub https URL.
+ * `git`. An scp-style `git@host:owner/repo` and a local path pass through.
+ * Anything else, a bare `owner/repo` included, is refused.
  */
 export function normalizeGitURL(raw: string): NormalizedGitURL {
   const trimmed = raw.trim();
@@ -25,10 +24,6 @@ export function normalizeGitURL(raw: string): NormalizedGitURL {
     return { ok: true, url: trimmed };
   }
 
-  if (SHORTHAND_PATTERN.test(trimmed) && !trimmed.startsWith('.')) {
-    return { ok: true, url: `https://github.com/${trimmed.replace(/\.git$/u, '')}.git` };
-  }
-
   if (SCP_PATTERN.test(trimmed)) {
     return { ok: true, url: trimmed };
   }

package/src/workspace/resolve-git-url.ts

@@ -0,0 +1,46 @@
+import { checkGitTransport } from './check-git-transport';
+import { checkURLCredentials } from './check-url-credentials';
+import { normalizeGitURL } from './normalize-git-url';
+
+type ResolvedGitURL =
+  | { readonly ok: true; readonly url: string }
+  | {
+      readonly ok: false;
+      readonly code: 'credential_in_url' | 'invalid_git_url';
+      readonly message: string;
+    };
+
+/**
+ * Resolves the URL a git workspace source is fetched from: it normalizes
+ * to its credential-free form, and that form must use one of `transports`, both checked
+ * before any git runs. Then the raw URL and the normalized form must each
+ * reach git without a credential. `cwd` is the directory whose git config
+ * the `insteadOf` rewrites are read from.
+ */
+export async function resolveGitURL(
+  raw: string,
+  cwd: string,
+  transports: readonly string[],
+): Promise<ResolvedGitURL> {
+  const normalized = normalizeGitURL(raw);
+
+  if (!normalized.ok) {
+    return normalized;
+  }
+
+  const transport = checkGitTransport(normalized.url, transports);
+
+  if (!transport.ok) {
+    return transport;
+  }
+
+  const plain = await checkURLCredentials(raw, cwd);
+
+  if (!plain.ok) {
+    return plain;
+  }
+
+  const expanded = await checkURLCredentials(normalized.url, cwd);
+
+  return expanded.ok ? normalized : expanded;
+}

package/src/workspace/resolve-path-source.ts

@@ -4,6 +4,9 @@ import { runGit } from './run-git';
 
 interface PathSourceOptions {
   readonly allowDirty?: 'refuse' | 'warn';
+
+  // The transports git may fetch over when it asks origin for its refs.
+  readonly transports: readonly string[];
 }
 
 interface ResolvedPathSource {
@@ -42,7 +45,7 @@ interface PathSourceRefusal {
  */
 export async function resolvePathSource(
   path: string,
-  options: PathSourceOptions = {},
+  options: PathSourceOptions,
 ): Promise<PathSourceRefusal | ResolvedPathSource> {
   if (statSync(path, { throwIfNoEntry: false })?.isDirectory() !== true) {
     return { ok: false, code: 'not_a_git_repo', message: `${path} is not a directory` };
@@ -118,7 +121,7 @@ export async function resolvePathSource(
     return { ok: false, code: url.code, message: `origin of ${root}: ${url.message}` };
   }
 
-  const pushed = await isOnOrigin(root, sha);
+  const pushed = await isOnOrigin(root, sha, options.transports);
 
   if (!pushed) {
     return { ok: false, code: 'unpushed_head', message: `${sha} is not on origin; push it first` };
@@ -152,7 +155,11 @@ function hasSubmodules(listing: string): boolean {
  * it without network access; failing that, origin's advertised ref tips are
  * checked, which catches a push whose tracking ref was never fetched.
  */
-async function isOnOrigin(root: string, sha: string): Promise<boolean> {
+async function isOnOrigin(
+  root: string,
+  sha: string,
+  transports: readonly string[],
+): Promise<boolean> {
   const tracking = await runGit(['branch', '-r', '--contains', sha, '--list', 'origin/*'], {
     cwd: root,
   });
@@ -161,7 +168,7 @@ async function isOnOrigin(root: string, sha: string): Promise<boolean> {
     return true;
   }
 
-  const advertised = await runGit(['ls-remote', 'origin'], { cwd: root });
+  const advertised = await runGit(['ls-remote', 'origin'], { cwd: root, transports });
 
   return (
     advertised.exitCode === 0 &&

package/src/workspace/run-git.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_GIT_TRANSPORTS } from '../shared/default-git-transports';
 import { REPOSITORY_ENV_VARS } from './repository-env-vars';
 
 interface GitRunOptions {
@@ -5,19 +6,31 @@ interface GitRunOptions {
   readonly env?: Readonly<Record<string, string>>;
   readonly input?: string;
   readonly isolated?: boolean;
+
+  // How long the command may run before it is stopped and reported as
+  // timed out; unset waits as long as git takes.
+  readonly timeoutMs?: number;
+
+  // The transports git may fetch over; https and ssh when unset.
+  readonly transports?: readonly string[];
 }
 
 interface GitRun {
   readonly exitCode: number;
   readonly stdout: string;
   readonly stderr: string;
+  readonly timedOut: boolean;
 }
 
 /**
  * Runs one git command to completion, feeding it any given input, and
- * returns its exit code and output.
+ * returns its exit code and output. A command given a time limit is
+ * stopped once it passes it, with every process it started, and reported
+ * as timed out.
  * git never prompts on a terminal here, since the daemon has none to answer
- * with, and its messages stay in the C locale so callers can read them.
+ * with, its messages stay in the C locale so callers can read them, and it
+ * fetches only over the transports it is given, https and ssh unless told
+ * otherwise, whatever URL a host config rewrite or a submodule hands it.
  * Variables that pin git to some other repository, such as the `GIT_DIR` a
  * git hook exports, are dropped so the command acts on its own directory.
  *
@@ -60,19 +73,54 @@ export async function runGit(
       ...(isolated ? ISOLATED_ENV : {}),
       GIT_TERMINAL_PROMPT: '0',
       LC_ALL: 'C',
+      GIT_ALLOW_PROTOCOL: (options.transports ?? DEFAULT_GIT_TRANSPORTS).join(':'),
     },
     stdin: options.input === undefined ? 'ignore' : Buffer.from(options.input),
     stdout: 'pipe',
     stderr: 'pipe',
+
+    // A command with a time limit leads its own process group, so stopping
+    // it stops the helpers it started, such as `git remote-http`, too.
+    detached: options.timeoutMs !== undefined,
   });
 
-  const [stdout, stderr, exitCode] = await Promise.all([
+  const finished = Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),
     proc.exited,
   ]);
 
-  return { exitCode, stdout, stderr };
+  if (options.timeoutMs === undefined) {
+    const [stdout, stderr, exitCode] = await finished;
+
+    return { exitCode, stdout, stderr, timedOut: false };
+  }
+
+  // A stopped git can leave a helper holding its pipes open, so a timeout
+  // answers without waiting for them to close.
+  const limit = Promise.withResolvers<null>();
+
+  const timer = setTimeout(() => {
+    limit.resolve(null);
+  }, options.timeoutMs);
+
+  const settled = await Promise.race([finished, limit.promise]);
+
+  clearTimeout(timer);
+
+  if (settled === null) {
+    try {
+      process.kill(-proc.pid, 'SIGKILL');
+    } catch {
+      // The group already exited.
+    }
+
+    return { exitCode: -1, stdout: '', stderr: '', timedOut: true };
+  }
+
+  const [stdout, stderr, exitCode] = settled;
+
+  return { exitCode, stdout, stderr, timedOut: false };
 }
 
 function collectHostEnv(): Record<string, string | undefined> {