@zgeoff/atc 3.3.0 → 3.4.0

package/src/test-utils/build-stub-peer-socket.ts

@@ -0,0 +1,81 @@
+/**
+ * A peer socket for tests that drive a daemon connection without a socket:
+ * while accepting, it takes every byte at once, as a peer with room does,
+ * and keeps what the daemon wrote; while not, it takes none and returns 0,
+ * as a socket whose kernel buffer is full does, so backpressure is a switch
+ * instead of a buffer race. It starts accepting, and `setAccepting` flips
+ * it. It ignores the end of the connection. `collectFrames`
+ * parses each complete line written so far as one protocol frame, in order.
+ * `waitForAnswer` resolves with the frame answering the request id once the
+ * daemon has written it, that id left out, so two answers compare whole.
+ */
+export function buildStubPeerSocket() {
+  const decoder = new TextDecoder();
+  const waiters = new Map<number, PromiseWithResolvers<Record<string, unknown>>>();
+
+  let accepting = true;
+  let written = '';
+
+  const collectFrames = (): Record<string, unknown>[] =>
+    written
+      .split('\n')
+      .slice(0, -1)
+      .map((line): Record<string, unknown> => toFrame(JSON.parse(line)));
+
+  return {
+    socket: {
+      // oxlint-disable-next-line prefer-readonly-parameter-types -- a readonly view cannot satisfy the writer contract; the stub never mutates chunks
+      write: (data: Uint8Array): number => {
+        if (!accepting) {
+          return 0;
+        }
+
+        written += decoder.decode(data, { stream: true });
+
+        // Frames are parsed only for a pending wait, so a stray line fails
+        // the read that looks at it rather than the daemon's write.
+        for (const frame of waiters.size === 0 ? [] : collectFrames()) {
+          const id = frame['id'];
+          const waiter = typeof id === 'number' ? waiters.get(id) : undefined;
+
+          if (waiter !== undefined) {
+            waiters.delete(Number(id));
+            waiter.resolve(buildAnswer(frame));
+          }
+        }
+
+        return data.length;
+      },
+      end: () => {},
+    },
+    setAccepting: (value: boolean) => {
+      accepting = value;
+    },
+    collectFrames,
+    waitForAnswer: (id: number): Promise<Record<string, unknown>> => {
+      const found = collectFrames().find((frame) => frame['id'] === id);
+
+      if (found !== undefined) {
+        return Promise.resolve(buildAnswer(found));
+      }
+
+      const waiter = Promise.withResolvers<Record<string, unknown>>();
+
+      waiters.set(id, waiter);
+
+      return waiter.promise;
+    },
+  };
+}
+
+function toFrame(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(`a protocol frame is a JSON object, not ${JSON.stringify(value)}`);
+  }
+
+  return Object.fromEntries(Object.entries(value));
+}
+
+function buildAnswer(frame: Readonly<Record<string, unknown>>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(frame).filter(([key]) => key !== 'id'));
+}

package/src/test-utils/build-stub-picker-host.ts

@@ -0,0 +1,36 @@
+import type { DroppedAnswer } from '../client/spawn-picker';
+
+/**
+ * The client a spawn picker runs inside, reduced to the reactions it
+ * records: `counts` holds how many times the picker asked for a status
+ * draw, returned to the screen the flow came from, attached a session, and
+ * dropped an answer, and `dropped` holds the kind of each dropped answer
+ * in order. `countReactions` returns the sum of every count, for a daemon
+ * stand-in that waits on the picker to react. Attaching resolves at once.
+ */
+export function buildStubPickerHost() {
+  const counts = { renders: 0, exits: 0, attached: 0, drops: 0 };
+  const dropped: DroppedAnswer[] = [];
+
+  return {
+    counts,
+    dropped,
+    countReactions: (): number => counts.renders + counts.exits + counts.attached + counts.drops,
+    scheduleStatus: (): void => {
+      counts.renders += 1;
+    },
+    toBase: (): void => {
+      counts.exits += 1;
+    },
+    attach: (): Promise<void> => {
+      counts.attached += 1;
+
+      return Promise.resolve();
+    },
+    onDropAnswer: (kind: DroppedAnswer): void => {
+      counts.drops += 1;
+
+      dropped.push(kind);
+    },
+  };
+}

package/src/test-utils/build-stub-proxied-agent-adapter.ts

@@ -0,0 +1,29 @@
+import type { AgentAdapter } from '../agents/agent-adapter';
+import { buildStubBrokeredAgentAdapter } from './build-stub-brokered-agent-adapter';
+
+interface StubProxiedAgentAdapterConfig {
+  readonly id: string;
+}
+
+/**
+ * An agent adapter for daemon tests that takes the GLM credential from
+ * impd's broker, as the brokered stand-in does, and that always starts
+ * behind the broker, but whose guest spawn plans a proxy variable of its
+ * own: `https_proxy` set to http://proxy.example:3128, beside a `sleep 30`.
+ * Every other member is the brokered stand-in's.
+ */
+export function buildStubProxiedAgentAdapter(config: StubProxiedAgentAdapterConfig): AgentAdapter {
+  return {
+    ...buildStubBrokeredAgentAdapter({
+      id: config.id,
+      brokerRequired: true,
+      isSelected: () => true,
+    }),
+    planGuestSpawn: () => ({
+      bin: 'sleep',
+      args: ['30'],
+      files: {},
+      env: { https_proxy: 'http://proxy.example:3128' },
+    }),
+  };
+}

package/src/test-utils/build-stub-pty-provider.ts

@@ -0,0 +1,53 @@
+import type {
+  ExecutionCapabilities,
+  ExecutionProvider,
+  HarnessSpec,
+} from '../daemon/execution-provider';
+import { LocalPTYProvider } from '../daemon/local-pty-provider';
+
+interface StubPTYProviderConfig {
+  // The provider kind the stand-in reports, such as the kind a target's
+  // config selects; the local provider's own kind when absent.
+  readonly kind?: string;
+
+  // Capabilities that differ from the local provider's.
+  readonly capabilities?: Partial<ExecutionCapabilities>;
+
+  // Called with each harness spec before the harness starts.
+  readonly onSpawn?: (spec: HarnessSpec) => void;
+  readonly prepareHost?: ExecutionProvider['prepareHost'];
+  readonly suspendHost?: ExecutionProvider['suspendHost'];
+  readonly destroyHost?: ExecutionProvider['destroyHost'];
+}
+
+/**
+ * An execution provider for daemon tests that runs every harness on a real
+ * local pseudo-terminal, as the `local-pty` provider does, under whatever
+ * kind and capabilities the test gives it, so a target of any kind starts
+ * a real process. Each spawn is reported to `onSpawn` first. Host
+ * readying, sleeping, and destroying take the test's own operations when
+ * given, and the local provider's otherwise: readying always succeeds, and
+ * a sleep or a destroy rejects.
+ */
+export function buildStubPTYProvider(config: StubPTYProviderConfig = {}): ExecutionProvider {
+  const local = new LocalPTYProvider();
+
+  const onSpawn = config.onSpawn ?? (() => {});
+
+  return {
+    kind: config.kind ?? local.kind,
+    remote: false,
+    capabilities: { ...local.capabilities, ...config.capabilities },
+    prepareHost: config.prepareHost ?? local.prepareHost,
+    spawnHarness: (spec) => {
+      onSpawn(spec);
+
+      return local.spawnHarness(spec);
+    },
+    transferArchive: local.transferArchive,
+    runCommand: local.runCommand,
+    suspendHost: config.suspendHost ?? local.suspendHost,
+    destroyHost: config.destroyHost ?? local.destroyHost,
+    dispose: local.dispose,
+  };
+}

package/src/test-utils/build-stub-recording-atc.ts

@@ -0,0 +1,10 @@
+/**
+ * The script of a stand-in `atc` that records each run: it appends
+ * `args:<arguments>`, `session:<$ATC_SESSION_ID>`, and `stdin:<what it
+ * read>` to the log, each on its own line, and exits 0.
+ */
+export function buildStubRecordingATC(log: string): string {
+  return `#!/bin/sh
+{ printf 'args:%s\\n' "$*"; printf 'session:%s\\n' "$ATC_SESSION_ID"; printf 'stdin:'; cat; printf '\\n'; } >> '${log}'
+`;
+}

package/src/test-utils/build-stub-signed-in-gh.ts

@@ -0,0 +1,18 @@
+/**
+ * The script of a stand-in `gh` that is signed in. It appends each command
+ * line it runs to `$HOME/gh-argv`. `gh config …` prints `https`. A
+ * repository listing of the signed-in account, `gh repo list --limit …`,
+ * prints one public repository, `me/dots`, and a listing of an owner,
+ * `gh repo list <owner> --limit …`, prints one private repository,
+ * `acme/app`, each in the JSON shape `gh repo list` prints.
+ */
+export function buildStubSignedInGH(): string {
+  return `#!/bin/sh
+printf '%s\\n' "$*" >> "$HOME/gh-argv"
+case "$1 $3" in
+  "config "*) echo https ;;
+  "repo --limit") echo '[{"nameWithOwner":"me/dots","description":"dotfiles","isPrivate":false,"url":"https://github.com/me/dots","sshUrl":"git@github.com:me/dots.git"}]' ;;
+  *) echo '[{"nameWithOwner":"acme/app","description":"","isPrivate":true,"url":"https://github.com/acme/app","sshUrl":"git@github.com:acme/app.git"}]' ;;
+esac
+`;
+}

package/src/test-utils/build-stub-signed-out-gh.ts

@@ -0,0 +1,8 @@
+/**
+ * The script of a stand-in `gh` that is signed out: every command prints
+ * gh's own sign-in hint to stderr and exits 4, as the real one does before
+ * `gh auth login`. The hint is gh 2.99.0's text, byte for byte.
+ */
+export function buildStubSignedOutGH(): string {
+  return "#!/bin/sh\nprintf '%s\\n%s\\n' 'To get started with GitHub CLI, please run:  gh auth login' 'Alternatively, populate the GH_TOKEN environment variable with a GitHub API authentication token.' >&2\nexit 4\n";
+}

package/src/test-utils/build-stub-soft-kill-provider.ts

@@ -0,0 +1,29 @@
+import type { ExecutionProvider, HarnessHandle } from '../daemon/execution-provider';
+import { LocalPTYProvider } from '../daemon/local-pty-provider';
+
+/**
+ * An execution provider of kind `no-forced-kill` that runs every harness on
+ * this machine through the local terminal provider, but whose harnesses
+ * have no forced kill to send, as a remote provider's have none: a harness
+ * that ignores its kill keeps running.
+ */
+export function buildStubSoftKillProvider(): ExecutionProvider {
+  const local = new LocalPTYProvider();
+
+  return {
+    kind: 'no-forced-kill',
+    remote: false,
+    capabilities: local.capabilities,
+    prepareHost: local.prepareHost,
+    spawnHarness: (spec): HarnessHandle => {
+      const { killForced: _killForced, ...handle } = local.spawnHarness(spec);
+
+      return handle;
+    },
+    transferArchive: local.transferArchive,
+    runCommand: local.runCommand,
+    suspendHost: local.suspendHost,
+    destroyHost: local.destroyHost,
+    dispose: local.dispose,
+  };
+}

package/src/test-utils/build-stub-targets.ts

@@ -0,0 +1,58 @@
+import type { ExecutionTarget } from '../daemon/build-execution-targets';
+import { buildTargetIdentity } from '../daemon/build-target-identity';
+import type { TargetConfig } from '../shared/collect-targets';
+import { buildStubPTYProvider } from './build-stub-pty-provider';
+
+// What a target's provider does in place of the local one's: the
+// capabilities it adds and the host preparation, sleep, and destroy it runs.
+type HostOverride = Omit<
+  NonNullable<Parameters<typeof buildStubPTYProvider>[0]>,
+  'kind' | 'onSpawn'
+>;
+
+interface StubTargetsConfig {
+  // Each spawn appends its target's id here, in order.
+  readonly spawned: string[];
+
+  // Host operations of their own for the targets they name.
+  readonly hosts?: Readonly<Record<string, HostOverride>>;
+}
+
+/**
+ * The daemon's execution targets for configured target entries, as the
+ * config load or the targets section parse gives them, in their order:
+ * each `local-pty` entry runs its harnesses on a real local
+ * pseudo-terminal through a stand-in provider that appends the entry's id
+ * to `spawned` on every spawn and takes the host operations `hosts` gives
+ * it, and an entry of any other kind has no provider, as a provider this
+ * daemon lacks leaves it. Each target's identity is the real one for its
+ * kind and options.
+ */
+export function buildStubTargets(
+  targets: readonly TargetConfig[],
+
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- the stand-in appends to the caller's spawn list
+  config: StubTargetsConfig,
+): ExecutionTarget[] {
+  const hosts: Readonly<Record<string, HostOverride>> = { ...config.hosts };
+
+  const providers = new Map(
+    targets.map((target) => [
+      target.id,
+      buildStubPTYProvider({
+        onSpawn: () => {
+          config.spawned.push(target.id);
+        },
+        ...hosts[target.id],
+      }),
+    ]),
+  );
+
+  return targets.map((target) => ({
+    id: target.id,
+    kind: target.provider,
+    options: target.options,
+    identity: buildTargetIdentity(target.provider, target.options),
+    provider: target.provider === 'local-pty' ? (providers.get(target.id) ?? null) : null,
+  }));
+}

package/src/test-utils/build-stub-terminal.ts

@@ -0,0 +1,19 @@
+/**
+ * A terminal that keeps every chunk written to it, in order, and draws
+ * nothing. `getText` returns everything written. `mark` returns a position
+ * at the end of what is written so far, and `getTextSince` returns only
+ * what was written after that position, so a test reads only the output of
+ * the action it checks.
+ */
+export function buildStubTerminal() {
+  const chunks: string[] = [];
+
+  return {
+    write: (chunk: string): void => {
+      chunks.push(chunk);
+    },
+    getText: (): string => chunks.join(''),
+    mark: (): number => chunks.length,
+    getTextSince: (mark: number): string => chunks.slice(mark).join(''),
+  };
+}

package/src/test-utils/build-stub-timeout-scheduler.ts

@@ -0,0 +1,48 @@
+// One timer the scheduler started: its delay, what it runs, and whether it
+// is still pending, has run, or was cancelled.
+interface StubTimer {
+  readonly ms: number;
+  readonly onTimeout: () => void;
+  state: 'pending' | 'ran' | 'cancelled';
+}
+
+/**
+ * A timeout scheduler for code that takes one in place of `setTimeout`: no
+ * timer ever runs on its own. `schedule` records the timer and returns what
+ * cancels it, as a real scheduler does; `runTimer` runs the oldest pending
+ * timer of the given delay and throws when none is pending, so a test both
+ * proves the code asked for that delay and moves time past it.
+ * `collectDelays` returns the delay of every timer in the order the code
+ * started them, and `collectPendingDelays` those neither run nor cancelled.
+ */
+export function buildStubTimeoutScheduler() {
+  const timers: StubTimer[] = [];
+
+  return {
+    schedule: (onTimeout: () => void, ms: number): (() => void) => {
+      const timer: StubTimer = { ms, onTimeout, state: 'pending' };
+
+      timers.push(timer);
+
+      return () => {
+        timer.state = timer.state === 'pending' ? 'cancelled' : timer.state;
+      };
+    },
+    runTimer: (ms: number): void => {
+      const timer = timers.find(
+        (candidate) => candidate.state === 'pending' && candidate.ms === ms,
+      );
+
+      if (timer === undefined) {
+        throw new Error(`no pending timer of ${ms} ms`);
+      }
+
+      timer.state = 'ran';
+
+      timer.onTimeout();
+    },
+    collectDelays: (): number[] => timers.map((timer) => timer.ms),
+    collectPendingDelays: (): number[] =>
+      timers.filter((timer) => timer.state === 'pending').map((timer) => timer.ms),
+  };
+}

package/src/test-utils/build-stub-tui-claude.ts

@@ -0,0 +1,47 @@
+import { join } from 'node:path';
+
+const CLI_PATH = join(import.meta.dir, '..', 'cli.ts');
+
+/**
+ * The script of a stand-in `claude` for the TUI suites. It prints
+ * `FAKE_CLAUDE_UP args: ` and its arguments at start and again on every
+ * SIGWINCH, as the real one repaints on a resize. It reports `SessionStart`
+ * through the real reporter with session id `fake-1` and transcript
+ * `$HOME/fake-transcript.jsonl`, then a permission `Notification`, and
+ * echoes each line it reads as `GOT:<line>` for five minutes. Scenario files
+ * in `$HOME` change it: `fake-claude-events.jsonl` replaces the
+ * notification with its hook lines, and a run with `--resume` among its
+ * arguments touches `fake-claude-resume-held` and waits, before it prints
+ * or reports anything, while `fake-claude-hold-resume` exists.
+ */
+export function buildStubTUIClaude(): string {
+  const report = `"${process.execPath}" "${CLI_PATH}" hook-report`;
+
+  return `#!/usr/bin/env bash
+ARGS="$*"
+case "$ARGS" in *--resume*)
+  if [ -f "$HOME/fake-claude-hold-resume" ]; then
+    touch "$HOME/fake-claude-resume-held"
+    while [ -f "$HOME/fake-claude-hold-resume" ]; do sleep 0.05; done
+  fi ;;
+esac
+paint() { echo "FAKE_CLAUDE_UP args: $ARGS"; }
+trap paint WINCH
+paint
+printf '{"hook_event_name":"SessionStart","session_id":"fake-1","transcript_path":"'"$HOME"'/fake-transcript.jsonl"}' | ${report}
+if [ -f "$HOME/fake-claude-events.jsonl" ]; then
+  while IFS= read -r ev; do
+    [ -n "$ev" ] || continue
+    sleep 0.3
+    printf '%s' "$ev" | ${report}
+  done < "$HOME/fake-claude-events.jsonl"
+else
+  sleep 0.3
+  printf '{"hook_event_name":"Notification","session_id":"fake-1","message":"needs permission"}' | ${report}
+fi
+# bash 3.2 read -t takes whole seconds; a fraction times out immediately
+for _ in $(seq 1 300); do
+  if read -t 1 -r line; then echo "GOT:$line"; fi
+done
+`;
+}

package/src/test-utils/build-stub-tui-grok.ts

@@ -0,0 +1,53 @@
+import { join } from 'node:path';
+
+const CLI_PATH = join(import.meta.dir, '..', 'cli.ts');
+
+/**
+ * The script of a stand-in `grok` for the TUI suites. It prints
+ * `FAKE_GROK_UP args: ` and its arguments at start and again on every
+ * SIGWINCH, reports `session_start` through the real reporter with session
+ * id `fake-grok-1` and its working directory, then a `permission_prompt`
+ * notification, prints `FAKE_GROK_HOOKS_DONE`, and echoes each line it
+ * reads as `GOT:<line>` for five minutes. Scenario files in `$HOME` change
+ * it: `fake-grok-events.jsonl` replaces the notification with its hook
+ * lines, `fake-grok-hold-start` skips every report, and while
+ * `fake-grok-defer-start` exists it touches `fake-grok-start-deferred` and
+ * waits before it reports.
+ */
+export function buildStubTUIGrok(): string {
+  const report = `"${process.execPath}" "${CLI_PATH}" hook-report`;
+
+  return `#!/usr/bin/env bash
+ARGS="$*"
+paint() { echo "FAKE_GROK_UP args: $ARGS"; }
+trap paint WINCH
+paint
+idle() {
+  for _ in $(seq 1 300); do
+    if read -t 1 -r line; then echo "GOT:$line"; fi
+  done
+}
+if [ -f "$HOME/fake-grok-hold-start" ]; then
+  idle
+  exit 0
+fi
+if [ -f "$HOME/fake-grok-defer-start" ]; then
+  touch "$HOME/fake-grok-start-deferred"
+  while [ -f "$HOME/fake-grok-defer-start" ]; do sleep 0.05; done
+fi
+printf '{"hookEventName":"session_start","sessionId":"fake-grok-1","cwd":"%s"}' "$PWD" | ${report}
+if [ -f "$HOME/fake-grok-events.jsonl" ]; then
+  sleep 0.3
+  while IFS= read -r ev; do
+    [ -n "$ev" ] || continue
+    printf '%s' "$ev" | ${report}
+    sleep 0.2
+  done < "$HOME/fake-grok-events.jsonl"
+else
+  sleep 0.3
+  printf '{"hookEventName":"notification","sessionId":"fake-grok-1","notificationType":"permission_prompt","message":"allow edit?"}' | ${report}
+fi
+echo "FAKE_GROK_HOOKS_DONE"
+idle
+`;
+}

package/src/test-utils/build-stub-wait-clock.ts

@@ -0,0 +1,23 @@
+/**
+ * A clock for a polling wait that moves only when the wait waits it out:
+ * `now` starts at zero, and `wait` records the milliseconds it was asked to
+ * wait in `waits`, moves `now` forward by them, and resolves at once. A
+ * deadline then passes after a known number of attempts, with no real time
+ * spent.
+ */
+export function buildStubWaitClock() {
+  const waits: number[] = [];
+  let elapsed = 0;
+
+  return {
+    waits,
+    now: () => elapsed,
+    wait: (ms: number): Promise<void> => {
+      waits.push(ms);
+
+      elapsed += ms;
+
+      return Promise.resolve();
+    },
+  };
+}

package/src/test-utils/build-target-options-from-config.ts

@@ -0,0 +1,37 @@
+import { buildTargetIdentity } from '../daemon/build-target-identity';
+import type { DaemonOptions } from '../daemon/daemon';
+import type { ExecutionProvider } from '../daemon/execution-provider';
+import { collectTargets } from '../shared/collect-targets';
+
+interface RawTargetConfig {
+  // The raw `targets` key of a config file.
+  readonly targets?: unknown;
+
+  // The raw `defaultTarget` key of a config file.
+  readonly defaultTarget?: unknown;
+}
+
+/**
+ * Turns the raw target keys of a config file into daemon options through
+ * the real parse. Each parsed target takes the provider that the factory
+ * for its kind builds for its id, or no provider when no factory serves its
+ * kind, and every parse error passes through as a target config error.
+ */
+export function buildTargetOptionsFromConfig(
+  raw: RawTargetConfig,
+  factories: ReadonlyMap<string, (id: string) => ExecutionProvider>,
+): Required<Pick<DaemonOptions, 'targets' | 'defaultTarget' | 'targetErrors'>> {
+  const parsed = collectTargets(raw.targets, raw.defaultTarget);
+
+  return {
+    targets: parsed.targets.map((target) => ({
+      id: target.id,
+      kind: target.provider,
+      options: target.options,
+      identity: buildTargetIdentity(target.provider, target.options),
+      provider: factories.get(target.provider)?.(target.id) ?? null,
+    })),
+    defaultTarget: parsed.defaultTarget,
+    targetErrors: parsed.errors,
+  };
+}

package/src/test-utils/collect-process-tree.ts

@@ -0,0 +1,75 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface TreeProcess {
+  readonly pid: number;
+  readonly argv: readonly string[];
+  readonly env: Readonly<Record<string, string>>;
+}
+
+/**
+ * Collects the argv and environment of every live process descended from
+ * the root process, read from `/proc`, so a test can check what a child
+ * was started with while it still runs. The root itself is left out. A
+ * process that exits during the scan is left out too. Linux only, since
+ * only Linux has `/proc`.
+ */
+export async function collectProcessTree(rootPID: number): Promise<TreeProcess[]> {
+  const entries = await readdir('/proc');
+
+  const pids = entries.filter((entry) => /^\d+$/u.test(entry));
+
+  const parents = new Map<string, string>();
+
+  for (const pid of pids) {
+    const stat = await readFile(join('/proc', pid, 'stat'), 'utf8').catch(() => '');
+
+    // The fields after the parenthesised command name start with the state,
+    // then the parent pid.
+    parents.set(pid, stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1] ?? '');
+  }
+
+  const root = String(rootPID);
+  const tree: TreeProcess[] = [];
+
+  for (const pid of pids) {
+    if (!isDescendant(parents, pid, root)) {
+      continue;
+    }
+
+    const cmdline = await readFile(join('/proc', pid, 'cmdline'), 'utf8').catch(() => null);
+    const environ = await readFile(join('/proc', pid, 'environ'), 'utf8').catch(() => null);
+
+    if (cmdline === null || environ === null) {
+      continue;
+    }
+
+    tree.push({
+      pid: Number(pid),
+      argv: splitNullTerminated(cmdline),
+      env: Object.fromEntries(
+        splitNullTerminated(environ).map((entry) => {
+          const equals = entry.indexOf('=');
+
+          return [entry.slice(0, equals), entry.slice(equals + 1)];
+        }),
+      ),
+    });
+  }
+
+  return tree;
+}
+
+function isDescendant(parents: ReadonlyMap<string, string>, pid: string, root: string): boolean {
+  let ancestor = parents.get(pid);
+
+  while (ancestor !== undefined && ancestor !== root) {
+    ancestor = parents.get(ancestor);
+  }
+
+  return ancestor === root;
+}
+
+function splitNullTerminated(text: string): string[] {
+  return text.split('\0').filter((entry) => entry !== '');
+}