@botcord/daemon 0.1.1

package/src/gateway/runtimes/codex.ts

@@ -0,0 +1,312 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { agentCodexHomeDir, ensureAgentCodexHome } from "../../agent-workspace.js";
+import { NdjsonStreamAdapter, type NdjsonEventCtx } from "./ndjson-stream.js";
+import {
+  firstExistingPath,
+  readCommandVersion,
+  resolveCommandOnPath,
+  type ProbeDeps,
+} from "./probe.js";
+import type { RuntimeProbeResult, RuntimeRunOptions, StreamBlock } from "../types.js";
+
+const CODEX_DESKTOP_BUNDLE_PATH = "/Applications/Codex.app/Contents/Resources/codex";
+/** Codex UUIDv7 / v4 session ids are 36-char dashed hex; reject anything else to keep argv safe. */
+const CODEX_SESSION_ID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+/** Resolve the Codex CLI executable via PATH or macOS desktop bundle. */
+export function resolveCodexCommand(deps: ProbeDeps = {}): string | null {
+  const onPath = resolveCommandOnPath("codex", deps);
+  if (onPath) return onPath;
+  return firstExistingPath([CODEX_DESKTOP_BUNDLE_PATH], deps);
+}
+
+function resolveCodexGlobalNpmEntry(): string | null {
+  try {
+    const globalRoot = execFileSync("npm", ["root", "-g"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+    if (!globalRoot) return null;
+    const candidate = path.join(globalRoot, "@openai", "codex", "bin", "codex.js");
+    return existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Probe whether the Codex CLI is installed and report its version. */
+export function probeCodex(deps: ProbeDeps = {}): RuntimeProbeResult {
+  const command = resolveCodexCommand(deps);
+  if (command) {
+    return {
+      available: true,
+      path: command,
+      version: readCommandVersion(command, [], deps) ?? undefined,
+    };
+  }
+  const npmEntry = resolveCodexGlobalNpmEntry();
+  if (npmEntry) {
+    return {
+      available: true,
+      path: npmEntry,
+      version: readCommandVersion(process.execPath, [npmEntry], deps) ?? undefined,
+    };
+  }
+  return { available: false };
+}
+
+/**
+ * Codex adapter — spawns `codex exec [resume <sid>] --json ...` and parses the
+ * JSONL event stream.
+ *
+ * Event shape (abridged):
+ *   {"type":"thread.started","thread_id":"<uuid>"}
+ *   {"type":"turn.started"}
+ *   {"type":"item.started","item":{"type":"command_execution", ...}}
+ *   {"type":"item.completed","item":{"type":"agent_message","text":"..."}}
+ *   {"type":"turn.completed","usage":{...}}
+ *
+ * `codex exec` does not report USD cost — only token usage — so `costUsd` is
+ * not populated from this adapter.
+ *
+ * ## systemContext injection: per-agent CODEX_HOME + AGENTS.md
+ *
+ * Codex has no `--append-system-prompt` equivalent. Its documented way to
+ * inject instructions that do NOT land in the stored transcript is the
+ * `AGENTS.md` loaded from `<CODEX_HOME>/AGENTS.md` (alongside the user-global
+ * `~/.codex/AGENTS.md` and the cwd's `<cwd>/AGENTS.md`).
+ *
+ * This adapter therefore:
+ *   1. Points `CODEX_HOME` at a per-agent directory:
+ *      `~/.botcord/agents/<accountId>/codex-home/`
+ *   2. Writes `opts.systemContext` to `<CODEX_HOME>/AGENTS.md` atomically
+ *      (tmp + rename) before spawning the child.
+ *   3. Leaves the positional prompt as just `opts.text` — no more prepending
+ *      systemContext to the transcript.
+ *
+ * With the transcript no longer accumulating systemContext, resume is safe to
+ * turn back on: `thread.started.thread_id` is persisted as `newSessionId`, and
+ * when the next turn arrives with a sessionId the adapter runs `exec resume
+ * <sid>` instead of `exec`. The per-agent CODEX_HOME also isolates codex's
+ * `sessions/` directory from `~/.codex/sessions/`, so daemon-owned sessions
+ * don't pollute the user's interactive session picker.
+ *
+ * ## `exec resume` flag quirk
+ *
+ * `codex exec resume` accepts a smaller flag set than `codex exec` — notably
+ * `-s / --sandbox` is NOT accepted on `resume`. We therefore express sandbox
+ * policy as `-c sandbox_mode="..."` (a `-c` override works on both
+ * subcommands) and the same tail of flags applies to both paths.
+ */
+export class CodexAdapter extends NdjsonStreamAdapter {
+  readonly id = "codex" as const;
+
+  private readonly explicitBinary: string | undefined;
+  private resolvedBinary: string | null = null;
+
+  constructor(opts?: { binary?: string }) {
+    super();
+    this.explicitBinary = opts?.binary ?? process.env.BOTCORD_CODEX_BIN;
+  }
+
+  probe(): RuntimeProbeResult {
+    return probeCodex();
+  }
+
+  /**
+   * Validate the sessionId shape and materialize the per-agent CODEX_HOME +
+   * AGENTS.md before handing off to the base adapter's spawn loop. Both steps
+   * must run BEFORE `super.run()` because `spawnEnv()` and `buildArgs()` are
+   * called synchronously from inside it and read the filesystem state we set
+   * up here.
+   */
+  override async run(opts: RuntimeRunOptions) {
+    if (opts.sessionId && !CODEX_SESSION_ID_RE.test(opts.sessionId)) {
+      throw new Error(`codex: invalid sessionId "${opts.sessionId}" (expected UUID)`);
+    }
+    if (opts.accountId) {
+      try {
+        ensureAgentCodexHome(opts.accountId);
+        writeCodexAgentsMd(opts.accountId, opts.systemContext);
+      } catch (err) {
+        // Writing AGENTS.md should never abort the turn — log and fall
+        // through. The child will spawn without the dynamic systemContext,
+        // which degrades to "codex replies without this turn's memory
+        // snapshot" rather than silence.
+        // eslint-disable-next-line no-console
+        console.warn("codex: failed to prepare CODEX_HOME/AGENTS.md", err);
+      }
+    }
+    return super.run(opts);
+  }
+
+  protected resolveBinary(): string {
+    if (this.explicitBinary) return this.explicitBinary;
+    if (this.resolvedBinary) return this.resolvedBinary;
+    // Use the executable resolver only — probeCodex's npm-global fallback
+    // yields a `.js` path that can't be spawned directly.
+    this.resolvedBinary = resolveCodexCommand() ?? "codex";
+    return this.resolvedBinary;
+  }
+
+  /**
+   * `extraArgs` are passed as Codex CLI flags (inserted before `--`), not
+   * prompt text. Use the route config's `extraArgs` for flags like
+   * `-c model="..."`, not for extra prompt content.
+   *
+   * Layout for fresh session:  `exec   <tail> -- <prompt>`
+   * Layout for resume:         `exec resume <sid> <tail> -- <prompt>`
+   *
+   * Both paths share the same `<tail>`: sandbox/approval policy (as `-c`
+   * overrides so `resume` accepts them), `--skip-git-repo-check`, `--json`,
+   * and operator `extraArgs`.
+   */
+  protected buildArgs(opts: RuntimeRunOptions): string[] {
+    const tail: string[] = [];
+
+    // Sandbox / approval policy. Expressed as `-c` overrides because
+    // `codex exec resume` rejects `-s` / `--full-auto`. `-c` works on both
+    // the fresh `exec` and `exec resume` paths.
+    //  - owner turn: bypass approvals + sandbox (owner trusts their agent)
+    //  - non-owner turn: `workspace-write` sandbox + on-request approvals
+    const hasSandboxOverride =
+      opts.extraArgs?.some(
+        (a) =>
+          a === "-s" ||
+          a.startsWith("--sandbox") ||
+          a === "--full-auto" ||
+          a === "--dangerously-bypass-approvals-and-sandbox" ||
+          a.startsWith("-c sandbox_mode=") ||
+          a.startsWith("-csandbox_mode="),
+      ) ?? false;
+    if (!hasSandboxOverride) {
+      if (opts.trustLevel === "owner") {
+        tail.push(
+          "-c",
+          'sandbox_mode="danger-full-access"',
+          "-c",
+          'approval_policy="never"',
+        );
+      } else {
+        tail.push(
+          "-c",
+          'sandbox_mode="workspace-write"',
+          "-c",
+          'approval_policy="on-request"',
+        );
+      }
+    }
+    tail.push("--skip-git-repo-check", "--json");
+    if (opts.extraArgs?.length) tail.push(...opts.extraArgs);
+
+    // `--` separates flags from positionals so a prompt starting with `-`
+    // can never be parsed as an option. `systemContext` is NOT prepended to
+    // the prompt any more — it lives in `<CODEX_HOME>/AGENTS.md` written by
+    // `run()` — so the transcript stays clean across resumes.
+    const prompt = opts.text;
+    if (opts.sessionId) {
+      return ["exec", "resume", opts.sessionId, ...tail, "--", prompt];
+    }
+    return ["exec", ...tail, "--", prompt];
+  }
+
+  protected spawnEnv(opts: RuntimeRunOptions): NodeJS.ProcessEnv {
+    const env: NodeJS.ProcessEnv = {
+      ...process.env,
+      // Keep JSONL free of ANSI codes regardless of user terminal settings.
+      FORCE_COLOR: "0",
+      NO_COLOR: "1",
+    };
+    if (opts.accountId) {
+      env.CODEX_HOME = agentCodexHomeDir(opts.accountId);
+    }
+    return env;
+  }
+
+  protected handleEvent(raw: unknown, ctx: NdjsonEventCtx): void {
+    const obj = raw as {
+      type?: string;
+      thread_id?: string;
+      item?: { type?: string; text?: string };
+      error?: { message?: string } | string;
+      turn?: { status?: string; error?: { message?: string } };
+    };
+
+    ctx.emitBlock(normalizeBlock(obj, ctx.seq));
+
+    // Persist the thread_id so the next turn on this session key resumes
+    // instead of spawning fresh. Safe now that systemContext lives in
+    // AGENTS.md rather than the transcript.
+    if (obj.type === "thread.started") {
+      if (typeof obj.thread_id === "string") {
+        ctx.state.newSessionId = obj.thread_id;
+      }
+      return;
+    }
+
+    if (obj.type === "item.completed" && obj.item?.type === "agent_message") {
+      if (typeof obj.item.text === "string") {
+        ctx.appendAssistantText(obj.item.text);
+        // The last agent_message is the final reply.
+        ctx.state.finalText = obj.item.text;
+      }
+      return;
+    }
+
+    if (obj.type === "turn.completed" && obj.turn?.status === "failed") {
+      const msg = obj.turn.error?.message;
+      if (typeof msg === "string" && msg) ctx.state.errorText = msg;
+      return;
+    }
+
+    if (obj.type === "error") {
+      ctx.state.errorText =
+        typeof obj.error === "string"
+          ? obj.error
+          : obj.error?.message ?? "codex error";
+    }
+  }
+}
+
+/**
+ * Atomically overwrite `<CODEX_HOME>/AGENTS.md` with `systemContext`. codex
+ * reads this file at process start, so the write must complete before spawn.
+ * An empty or missing systemContext writes an empty file — deleting would
+ * race with a prior turn's file still being readable; empty is simpler and
+ * codex treats it as "no user-global AGENTS.md".
+ */
+function writeCodexAgentsMd(accountId: string, systemContext: string | undefined): void {
+  const dir = agentCodexHomeDir(accountId);
+  // ensureAgentCodexHome already mkdir's dir; defensive mkdir here too for
+  // code paths that invoke this helper directly (tests, future callers).
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const target = path.join(dir, "AGENTS.md");
+  const tmp = path.join(dir, `.AGENTS.md.${process.pid}.tmp`);
+  writeFileSync(tmp, systemContext ?? "", { mode: 0o600 });
+  renameSync(tmp, target);
+}
+
+function normalizeBlock(obj: any, seq: number): StreamBlock {
+  let kind: StreamBlock["kind"] = "other";
+  const type: string | undefined = obj?.type;
+  const itemType: string | undefined = obj?.item?.type;
+
+  if (type === "thread.started" || type === "turn.started" || type === "turn.completed") {
+    kind = "system";
+  } else if (type === "item.completed" && itemType === "agent_message") {
+    kind = "assistant_text";
+  } else if (type === "item.started" || type === "item.completed") {
+    if (
+      itemType === "command_execution" ||
+      itemType === "file_change" ||
+      itemType === "mcp_tool_call" ||
+      itemType === "web_search"
+    ) {
+      kind = "tool_use";
+    }
+  }
+  return { raw: obj, kind, seq };
+}

package/src/gateway/runtimes/gemini.ts

@@ -0,0 +1,43 @@
+import {
+  readCommandVersion,
+  resolveCommandOnPath,
+  type ProbeDeps,
+} from "./probe.js";
+import type {
+  RuntimeAdapter,
+  RuntimeProbeResult,
+  RuntimeRunOptions,
+  RuntimeRunResult,
+} from "../types.js";
+
+/** Resolve the Gemini CLI executable on PATH. */
+export function resolveGeminiCommand(deps: ProbeDeps = {}): string | null {
+  return resolveCommandOnPath("gemini", deps);
+}
+
+/** Probe whether the Gemini CLI is installed and report its version. */
+export function probeGemini(deps: ProbeDeps = {}): RuntimeProbeResult {
+  const command = resolveGeminiCommand(deps);
+  if (!command) return { available: false };
+  return {
+    available: true,
+    path: command,
+    version: readCommandVersion(command, [], deps) ?? undefined,
+  };
+}
+
+/**
+ * Gemini adapter stub — probe() is wired up so `botcord-daemon doctor` can report it.
+ * run() is not implemented yet; routing a turn here will surface the error upstream.
+ */
+export class GeminiAdapter implements RuntimeAdapter {
+  readonly id = "gemini" as const;
+
+  probe(): RuntimeProbeResult {
+    return probeGemini();
+  }
+
+  async run(_opts: RuntimeRunOptions): Promise<RuntimeRunResult> {
+    throw new Error("gemini adapter not implemented");
+  }
+}

package/src/gateway/runtimes/ndjson-stream.ts

@@ -0,0 +1,225 @@
+import { spawn } from "node:child_process";
+import { consoleLogger } from "../log.js";
+import type {
+  RuntimeAdapter,
+  RuntimeProbeResult,
+  RuntimeRunOptions,
+  RuntimeRunResult,
+  StreamBlock,
+} from "../types.js";
+
+/**
+ * Mutable state threaded through event callbacks while a single turn runs.
+ * The base class reads these fields to assemble the final RuntimeRunResult.
+ */
+export interface NdjsonRunState {
+  /** Session id to persist for `--resume`. Seeded with the incoming sessionId. */
+  newSessionId: string;
+  /** Final text reported by a terminal "result"/"completed" event, if any. */
+  finalText: string;
+  /** Streamed assistant text chunks; concatenated as a fallback when finalText is empty. */
+  assistantTextChunks: string[];
+  /** Running byte total of everything pushed to assistantTextChunks. */
+  assistantTextBytes: number;
+  /** True once the per-turn text cap was hit; further chunks are dropped. */
+  assistantTextCapped: boolean;
+  costUsd?: number;
+  errorText?: string;
+}
+
+/** Per-event context handed to subclasses from the ndjson dispatch loop. */
+export interface NdjsonEventCtx {
+  state: NdjsonRunState;
+  /** 1-based sequence within this turn, identical to what `onBlock` would see. */
+  seq: number;
+  /** Forward a normalized StreamBlock to the caller's onBlock handler. */
+  emitBlock: (block: StreamBlock) => void;
+  /**
+   * Push streamed assistant text while respecting the per-turn byte cap.
+   * Subclasses should use this instead of `state.assistantTextChunks.push(...)`.
+   */
+  appendAssistantText: (text: string) => void;
+}
+
+const log = consoleLogger;
+
+/**
+ * Common scaffold for CLI adapters that emit newline-delimited JSON on stdout.
+ * Subclasses plug in:
+ *   - resolveBinary() — which executable to spawn
+ *   - buildArgs()     — argv tail (excluding the binary itself)
+ *   - handleEvent()   — how to interpret one parsed JSON object
+ *
+ * The base class handles spawn, abort wiring, stderr capping, line splitting,
+ * and exit-code error synthesis so every new runtime only writes the parts
+ * that are actually runtime-specific.
+ */
+/** How much stderr is retained for error reporting. */
+const STDERR_TAIL_CAP = 8 * 1024;
+/** How much of the retained stderr is included in the synthesized exit-code error. */
+const STDERR_ERROR_SNIPPET = 500;
+/** Cap on total streamed assistant text bytes per turn — guards against a runaway CLI. */
+const ASSISTANT_TEXT_CAP = 1 * 1024 * 1024;
+/** Grace period between SIGTERM and SIGKILL when an abort is requested. */
+const KILL_GRACE_MS = 5_000;
+
+/** Base class for runtime adapters that drive a CLI emitting newline-delimited JSON. */
+export abstract class NdjsonStreamAdapter implements RuntimeAdapter {
+  abstract readonly id: string;
+
+  probe?(): RuntimeProbeResult;
+
+  protected abstract resolveBinary(opts: RuntimeRunOptions): string;
+  protected abstract buildArgs(opts: RuntimeRunOptions): string[];
+  protected abstract handleEvent(obj: unknown, ctx: NdjsonEventCtx): void;
+
+  /** Override to tweak env (FORCE_COLOR=0, NO_COLOR=1, etc). */
+  protected spawnEnv(_opts: RuntimeRunOptions): NodeJS.ProcessEnv {
+    return process.env;
+  }
+
+  async run(opts: RuntimeRunOptions): Promise<RuntimeRunResult> {
+    if (opts.signal.aborted) {
+      return {
+        text: "",
+        newSessionId: opts.sessionId ?? "",
+        error: `${this.id} aborted before spawn`,
+      };
+    }
+
+    const binary = this.resolveBinary(opts);
+    const args = this.buildArgs(opts);
+
+    log.debug(`${this.id} spawn`, {
+      cwd: opts.cwd,
+      sessionId: opts.sessionId,
+      argv: args,
+    });
+
+    const child = spawn(binary, args, {
+      cwd: opts.cwd,
+      env: this.spawnEnv(opts),
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    // Attach abort listener immediately — spawn is synchronous, but a racing
+    // `.abort()` between `spawn` and a listener added later would be lost.
+    let killTimer: ReturnType<typeof setTimeout> | null = null;
+    const onAbort = () => {
+      if (child.killed) return;
+      child.kill("SIGTERM");
+      // Escalate to SIGKILL if the child ignores the polite request.
+      killTimer = setTimeout(() => {
+        if (!child.killed) {
+          log.warn(`${this.id} did not exit after SIGTERM; sending SIGKILL`);
+          try {
+            child.kill("SIGKILL");
+          } catch {
+            // best-effort
+          }
+        }
+      }, KILL_GRACE_MS);
+      if (typeof killTimer.unref === "function") killTimer.unref();
+    };
+    opts.signal.addEventListener("abort", onAbort, { once: true });
+
+    const state: NdjsonRunState = {
+      newSessionId: opts.sessionId ?? "",
+      finalText: "",
+      assistantTextChunks: [],
+      assistantTextBytes: 0,
+      assistantTextCapped: false,
+    };
+
+    const appendAssistantText = (text: string): void => {
+      if (!text) return;
+      if (state.assistantTextCapped) return;
+      const budget = ASSISTANT_TEXT_CAP - state.assistantTextBytes;
+      if (budget <= 0) {
+        state.assistantTextCapped = true;
+        log.warn(`${this.id} assistant text exceeded ${ASSISTANT_TEXT_CAP} bytes; dropping further chunks`);
+        return;
+      }
+      if (text.length > budget) {
+        state.assistantTextChunks.push(text.slice(0, budget));
+        state.assistantTextBytes += budget;
+        state.assistantTextCapped = true;
+        log.warn(`${this.id} assistant text hit ${ASSISTANT_TEXT_CAP}-byte cap`);
+        return;
+      }
+      state.assistantTextChunks.push(text);
+      state.assistantTextBytes += text.length;
+    };
+
+    let stderrTail = "";
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk: string) => {
+      stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_CAP);
+    });
+
+    let seq = 0;
+    let stdoutBuf = "";
+    child.stdout!.setEncoding("utf8");
+    const dispatchLine = (line: string) => {
+      if (!line) return;
+      let obj: unknown;
+      try {
+        obj = JSON.parse(line);
+      } catch {
+        log.warn(`${this.id} non-json stdout line`, { line: line.slice(0, 200) });
+        return;
+      }
+      seq += 1;
+      try {
+        this.handleEvent(obj, {
+          state,
+          seq,
+          emitBlock: (b) => opts.onBlock?.(b),
+          appendAssistantText,
+        });
+      } catch (err) {
+        log.warn(`${this.id} event handler threw`, { err: String(err) });
+      }
+    };
+
+    child.stdout!.on("data", (chunk: string) => {
+      stdoutBuf += chunk;
+      let idx: number;
+      while ((idx = stdoutBuf.indexOf("\n")) !== -1) {
+        const line = stdoutBuf.slice(0, idx).trim();
+        stdoutBuf = stdoutBuf.slice(idx + 1);
+        dispatchLine(line);
+      }
+    });
+
+    let code = 0;
+    try {
+      code = await new Promise<number>((resolve, reject) => {
+        child.on("error", reject);
+        child.on("close", (c) => resolve(c ?? 0));
+      });
+    } finally {
+      opts.signal.removeEventListener("abort", onAbort);
+      if (killTimer) clearTimeout(killTimer);
+    }
+
+    // Flush any final line that lacked a terminating newline.
+    const residual = stdoutBuf.trim();
+    if (residual) dispatchLine(residual);
+
+    if (code !== 0 && !state.errorText) {
+      state.errorText = `${this.id} exited with code ${code}: ${stderrTail.slice(-STDERR_ERROR_SNIPPET)}`;
+    }
+
+    const rawText = state.finalText || state.assistantTextChunks.join("").trim();
+    const text =
+      rawText.length > ASSISTANT_TEXT_CAP ? rawText.slice(0, ASSISTANT_TEXT_CAP) : rawText;
+
+    return {
+      text,
+      newSessionId: state.newSessionId,
+      ...(state.costUsd !== undefined ? { costUsd: state.costUsd } : {}),
+      ...(state.errorText ? { error: state.errorText } : {}),
+    };
+  }
+}

package/src/gateway/runtimes/probe.ts

@@ -0,0 +1,73 @@
+import { execFileSync, type ExecFileSyncOptions } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/** Injection seam for PATH resolution + version probes, so tests can stub syscalls. */
+export interface ProbeDeps {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  homeDir?: string;
+  execFileSyncFn?: typeof execFileSync;
+  existsSyncFn?: (p: string) => boolean;
+}
+
+function normalizeExecOutput(raw: Buffer | string | null | undefined): string {
+  return Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw ?? "");
+}
+
+/** Resolve a command name on PATH via `which`/`where`; returns null when missing. */
+export function resolveCommandOnPath(command: string, deps: ProbeDeps = {}): string | null {
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  const execFn = deps.execFileSyncFn ?? execFileSync;
+  const locator = platform === "win32" ? "where" : "which";
+  try {
+    const out = normalizeExecOutput(
+      execFn(locator, [command], {
+        stdio: ["ignore", "pipe", "ignore"],
+        env,
+      } as ExecFileSyncOptions),
+    );
+    const resolved = out.trim().split(/\r?\n/)[0];
+    return resolved || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Return the first path in `candidates` that exists on disk, or null. */
+export function firstExistingPath(candidates: string[], deps: ProbeDeps = {}): string | null {
+  const exists = deps.existsSyncFn ?? existsSync;
+  for (const c of candidates) {
+    if (exists(c)) return c;
+  }
+  return null;
+}
+
+/** Run `<command> [...args] --version` and return the first output line, or null. */
+export function readCommandVersion(
+  command: string,
+  args: string[] = [],
+  deps: ProbeDeps = {},
+): string | null {
+  const env = deps.env ?? process.env;
+  const execFn = deps.execFileSyncFn ?? execFileSync;
+  try {
+    const out = normalizeExecOutput(
+      execFn(command, [...args, "--version"], {
+        stdio: ["ignore", "pipe", "pipe"],
+        env,
+        timeout: 5000,
+      } as ExecFileSyncOptions),
+    );
+    return out.trim().split(/\r?\n/)[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Join `relativePath` against HOME (falls back to empty when unset). */
+export function resolveHomePath(relativePath: string, deps: ProbeDeps = {}): string {
+  const home = deps.homeDir ?? deps.env?.HOME ?? process.env.HOME ?? "";
+  return path.join(home, relativePath);
+}