infraweaver 0.1.0

package/src/utils/log.ts

@@ -0,0 +1,452 @@
+/**
+ * Logging utilities that work well in both local and GitHub Actions environments
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as core from "@actions/core";
+import { table } from "table";
+import { type AgentUsage, formatCostUsd } from "#app/agents/shared";
+import { isGitHubActions, isInsideDocker } from "#app/utils/globals";
+import { redactSecrets } from "#app/utils/redact";
+
+// --- log prefix via AsyncLocalStorage ---
+
+type LogContext = { prefix: string };
+
+const logContext = new AsyncLocalStorage<LogContext>();
+
+const MAGENTA = "\x1b[35m";
+const RESET = "\x1b[0m";
+
+/** run `fn` with every log line prefixed by `prefix` (e.g. "[task-label]") in magenta */
+export function withLogPrefix<T>(prefix: string, fn: () => Promise<T>): Promise<T> {
+  return logContext.run({ prefix }, fn);
+}
+
+function prefixLines(message: string): string {
+  const ctx = logContext.getStore();
+  if (!ctx) return message;
+  const colored = `${MAGENTA}${ctx.prefix}${RESET} `;
+  return message
+    .split("\n")
+    .map((line) => `${colored}${line}`)
+    .join("\n");
+}
+
+/** plain-text prefix (no ANSI) for GitHub Actions group names */
+function prefixPlain(name: string): string {
+  const ctx = logContext.getStore();
+  if (!ctx) return name;
+  return `${ctx.prefix} ${name}`;
+}
+
+// --- log sink ----------------------------------------------------------------
+
+type LogSink = "actions" | "stderr";
+
+let sink: LogSink = "actions";
+
+/**
+ * Route ALL log output to stderr instead of `@actions/core` (which writes to
+ * stdout). Required before starting a stdio MCP server: stdout is the JSON-RPC
+ * channel there, and a single stray diagnostic line corrupts the framing.
+ * The GitHub Action path never calls this — its sink stays `@actions/core`.
+ */
+export function setLogSink(next: LogSink): void {
+  sink = next;
+}
+
+/**
+ * info-level line via the active sink.
+ *
+ * Scrub secret-shaped substrings here, at the single sink primitive, so redaction
+ * is truly sink-independent. `formatArgs` already redacts the `info`/`success`/`debug`
+ * lines, but `box`/`table`/`separator`/`group` build their content directly and reach
+ * the sink through this function without passing through `formatArgs` — without this
+ * pass a secret printed via `log.box(...)` would leak in cleartext on stderr/local.
+ * `redactSecrets` is idempotent and allocation-light on the no-secret path, so the
+ * double-pass on the already-redacted lines is cheap.
+ */
+function emitInfo(line: string): void {
+  const safe = redactSecrets(line);
+  if (sink === "stderr") {
+    process.stderr.write(`${safe}\n`);
+    return;
+  }
+  core.info(safe);
+}
+
+const isRunnerDebugEnabled = () => core.isDebug();
+
+const isLocalDebugEnabled = () =>
+  process.env.LOG_LEVEL === "debug" || process.env.ACTIONS_STEP_DEBUG === "true";
+
+const isDebugEnabled = () => isLocalDebugEnabled() || isRunnerDebugEnabled();
+
+/** timestamp prefix for debug mode — empty string when debug is off */
+function ts(): string {
+  return isDebugEnabled() ? `[${new Date().toISOString()}] ` : "";
+}
+
+/**
+ * Format arguments into a single string for logging.
+ *
+ * The joined line is passed through {@link redactSecrets} so secret-shaped
+ * substrings are scrubbed regardless of the active sink — `core.setSecret` only masks
+ * on the GitHub `actions` sink, leaving stderr (every stdio MCP server) and local dev
+ * unmasked.
+ */
+function formatArgs(args: unknown[]): string {
+  const joined = args
+    .map((arg) => {
+      if (typeof arg === "string") return arg;
+      if (arg instanceof Error) return `${arg.message}\n${arg.stack}`;
+      return JSON.stringify(arg);
+    })
+    .join(" ");
+  return redactSecrets(joined);
+}
+
+/**
+ * Start a collapsed group (GitHub Actions) or regular group (local)
+ */
+function startGroup(name: string): void {
+  const prefixed = prefixPlain(name);
+  if (sink === "stderr") {
+    emitInfo(`▼ ${prefixed}`);
+    return;
+  }
+  if (isGitHubActions) {
+    core.startGroup(prefixed);
+  } else {
+    console.group(prefixed);
+  }
+}
+
+/**
+ * End a collapsed group
+ */
+function endGroup(): void {
+  if (sink === "stderr") return;
+  if (isGitHubActions) {
+    core.endGroup();
+  } else {
+    console.groupEnd();
+  }
+}
+
+/**
+ * Run a callback within a collapsed group
+ */
+function group(name: string, fn: () => void): void {
+  startGroup(name);
+  fn();
+  endGroup();
+}
+
+/**
+ * Print a formatted box with text (for console output)
+ */
+function boxString(
+  text: string,
+  options?: {
+    title?: string;
+    maxWidth?: number;
+    indent?: string;
+    padding?: number;
+  },
+): string {
+  const { title, maxWidth = 80, indent = "", padding = 1 } = options || {};
+
+  const lines = text.trim().split("\n");
+  const wrappedLines: string[] = [];
+
+  for (const line of lines) {
+    if (line.length <= maxWidth - padding * 2) {
+      wrappedLines.push(line);
+    } else {
+      const words = line.split(" ");
+      let currentLine = "";
+
+      for (const word of words) {
+        const testLine = currentLine ? `${currentLine} ${word}` : word;
+        if (testLine.length <= maxWidth - padding * 2) {
+          currentLine = testLine;
+        } else {
+          if (currentLine) {
+            wrappedLines.push(currentLine);
+            currentLine = "";
+          }
+          // wrap long words by breaking them into chunks
+          const maxLineLength = maxWidth - padding * 2;
+          let remainingWord = word;
+          while (remainingWord.length > maxLineLength) {
+            wrappedLines.push(remainingWord.substring(0, maxLineLength));
+            remainingWord = remainingWord.substring(maxLineLength);
+          }
+          currentLine = remainingWord;
+        }
+      }
+
+      if (currentLine) {
+        wrappedLines.push(currentLine);
+      }
+    }
+  }
+
+  const maxLineLength = Math.max(...wrappedLines.map((line) => line.length));
+  const contentBoxWidth = maxLineLength + padding * 2;
+
+  // ensure box width is at least as wide as the title line when title exists
+  const titleLineLength = title ? ` ${title} `.length : 0;
+  const boxWidth = Math.max(contentBoxWidth, titleLineLength);
+
+  let result = "";
+
+  if (title) {
+    const titleLine = ` ${title} `;
+    const titlePadding = Math.max(0, boxWidth - titleLine.length);
+    result += `${indent}┌${titleLine}${"─".repeat(titlePadding)}┐\n`;
+  }
+
+  if (!title) {
+    result += `${indent}┌${"─".repeat(boxWidth)}┐\n`;
+  }
+
+  for (const line of wrappedLines) {
+    const paddedLine = line.padEnd(maxLineLength);
+    result += `${indent}│${" ".repeat(padding)}${paddedLine}${" ".repeat(padding)}│\n`;
+  }
+
+  result += `${indent}└${"─".repeat(boxWidth)}┘`;
+
+  return result;
+}
+
+/**
+ * Print a formatted box with text
+ */
+function box(
+  text: string,
+  options?: {
+    title?: string;
+    maxWidth?: number;
+  },
+): void {
+  const boxContent = boxString(text, options);
+  emitInfo(prefixLines(boxContent));
+}
+
+/**
+ * Overwrite the job summary with the given text.
+ * Skips if:
+ * - Not in GitHub Actions
+ * - Running inside Docker (CI tests inherit host env vars but can't access host paths)
+ * - GITHUB_STEP_SUMMARY not set
+ */
+export async function writeSummary(text: string): Promise<void> {
+  if (!isGitHubActions) return;
+
+  // CI tests run in Docker with GITHUB_ACTIONS=true inherited from host,
+  // but the GITHUB_STEP_SUMMARY path points to a host filesystem location
+  // that doesn't exist inside the container
+  if (isInsideDocker) return;
+
+  if (!process.env.GITHUB_STEP_SUMMARY) return;
+
+  // LLM02: the job summary includes raw agent output — scrub secrets before it
+  // lands in the durable GitHub Actions step summary. Idempotent + no-op on clean text.
+  await core.summary.addRaw(redactSecrets(text)).write({ overwrite: true });
+}
+
+/**
+ * Print a formatted table using the table package
+ */
+function printTable(
+  rows: Array<Array<{ data: string; header?: boolean } | string>>,
+  options?: {
+    title?: string;
+  },
+): void {
+  const { title } = options || {};
+
+  // Convert rows to string arrays for the table package
+  const tableData = rows.map((row) =>
+    row.map((cell) => {
+      if (typeof cell === "string") {
+        return cell;
+      }
+      return cell.data;
+    }),
+  );
+
+  const formatted = table(tableData);
+
+  if (title) {
+    emitInfo(prefixLines(`\n${title}`));
+  }
+  emitInfo(prefixLines(`\n${formatted}\n`));
+}
+
+/**
+ * Print a separator line
+ */
+function separator(length: number = 50): void {
+  const separatorText = "─".repeat(length);
+  emitInfo(prefixLines(separatorText));
+}
+
+/**
+ * Main logging utility object - import this once and access all utilities
+ */
+export const log = {
+  /** Print info message */
+  info: (...args: unknown[]): void => {
+    emitInfo(prefixLines(`${ts()}${formatArgs(args)}`));
+  },
+
+  /** Print a warning message. Use only for warnings that should be displayed in the job summary. */
+  warning: (...args: unknown[]): void => {
+    if (sink === "stderr") {
+      emitInfo(prefixLines(`${ts()}warning: ${formatArgs(args)}`));
+      return;
+    }
+    core.warning(prefixLines(`${ts()}${formatArgs(args)}`));
+  },
+
+  /** Print an error message. Use only for errors that should be displayed in the job summary. */
+  error: (...args: unknown[]): void => {
+    if (sink === "stderr") {
+      emitInfo(prefixLines(`${ts()}error: ${formatArgs(args)}`));
+      return;
+    }
+    core.error(prefixLines(`${ts()}${formatArgs(args)}`));
+  },
+
+  /** Print success message */
+  success: (...args: unknown[]): void => {
+    emitInfo(prefixLines(`${ts()}» ${formatArgs(args)}`));
+  },
+
+  /** Print debug message (only when debug mode is enabled) */
+  debug: (...args: unknown[]): void => {
+    if (sink === "actions" && isRunnerDebugEnabled()) {
+      core.debug(prefixLines(formatArgs(args)));
+      return;
+    }
+    if (isLocalDebugEnabled()) {
+      emitInfo(prefixLines(`${ts()}[DEBUG] ${formatArgs(args)}`));
+    }
+  },
+
+  /** Print a formatted box with text */
+  box,
+
+  /** Print a formatted table using the table package */
+  table: printTable,
+
+  /** Print a separator line */
+  separator,
+
+  /** Start a collapsed group (GitHub Actions) or regular group (local) */
+  startGroup,
+
+  /** End a collapsed group */
+  endGroup,
+
+  /** Run a callback within a collapsed group */
+  group,
+
+  /** Log tool call information to console with formatted output */
+  toolCall: ({ toolName, input }: { toolName: string; input: unknown }): void => {
+    const inputFormatted = formatJsonValue(input);
+    const output = inputFormatted !== "{}" ? `» ${toolName}(${inputFormatted})` : `» ${toolName}()`;
+
+    log.info(output.trimEnd());
+  },
+};
+
+/**
+ * Format a value as JSON, using compact format for simple values and pretty-printed for complex ones
+ */
+export function formatJsonValue(value: unknown): string {
+  const compact = JSON.stringify(value);
+  return compact.length > 80 || compact.includes("\n") ? JSON.stringify(value, null, 2) : compact;
+}
+
+/**
+ * Format a multi-line string with proper indentation for tool call output
+ * First line has the label, subsequent lines are indented 4 spaces
+ */
+export function formatIndentedField(label: string, content: string): string {
+  if (!content.includes("\n")) {
+    return `  ${label}: ${content}\n`;
+  }
+
+  const lines = content.split("\n");
+  let formatted = `  ${label}: ${lines[0]}\n`;
+  for (let i = 1; i < lines.length; i++) {
+    formatted += `    ${lines[i]}\n`;
+  }
+  return formatted;
+}
+
+/**
+ * format aggregated usage data as a markdown table for the GitHub step summary.
+ *
+ * columns mirror the per-run stdout token table emitted by `logTokenTable`
+ * (Input / Cache Read / Cache Write / Output / Total / Cost ($)) so the job
+ * summary and the in-run logs can be compared row-for-row.
+ *
+ * notes:
+ *   - `AgentUsage.inputTokens` is the sum of non-cached input + cache read
+ *     + cache write (set that way by both agent harnesses' `buildUsage`),
+ *     so the non-cached Input column is recovered by subtracting cache fields.
+ *   - `costUsd` is sourced from models.dev (OpenCode) or `total_cost_usd`
+ *     (Claude CLI). absent rows show `—` so per-agent coverage is obvious.
+ */
+export function formatUsageSummary(entries: AgentUsage[]): string {
+  if (entries.length === 0) return "";
+
+  const header = "| Agent | Input | Cache Read | Cache Write | Output | Total | Cost ($) |";
+  const separatorRow = "| --- | ---: | ---: | ---: | ---: | ---: | ---: |";
+  const fmt = (n: number) => n.toLocaleString("en-US");
+
+  const nonCachedInput = (e: AgentUsage): number =>
+    Math.max(0, e.inputTokens - (e.cacheReadTokens ?? 0) - (e.cacheWriteTokens ?? 0));
+  const totalFor = (e: AgentUsage): number =>
+    nonCachedInput(e) + (e.cacheReadTokens ?? 0) + (e.cacheWriteTokens ?? 0) + e.outputTokens;
+  const costCell = (e: AgentUsage): string =>
+    typeof e.costUsd === "number" && e.costUsd > 0 ? formatCostUsd(e.costUsd) : "—";
+
+  const rows = entries.map(
+    (e) =>
+      `| ${e.agent} | ${fmt(nonCachedInput(e))} | ${fmt(e.cacheReadTokens ?? 0)} | ${fmt(e.cacheWriteTokens ?? 0)} | ${fmt(e.outputTokens)} | ${fmt(totalFor(e))} | ${costCell(e)} |`,
+  );
+
+  const totalsRows: string[] = [];
+  if (entries.length > 1) {
+    const totalInput = entries.reduce((sum, e) => sum + nonCachedInput(e), 0);
+    const totalOutput = entries.reduce((sum, e) => sum + e.outputTokens, 0);
+    const totalCacheRead = entries.reduce((sum, e) => sum + (e.cacheReadTokens ?? 0), 0);
+    const totalCacheWrite = entries.reduce((sum, e) => sum + (e.cacheWriteTokens ?? 0), 0);
+    const grandTotal = totalInput + totalCacheRead + totalCacheWrite + totalOutput;
+    const totalCostUsd = entries.reduce((sum, e) => sum + (e.costUsd ?? 0), 0);
+    const totalCostCell = totalCostUsd > 0 ? `**${formatCostUsd(totalCostUsd)}**` : "—";
+    totalsRows.push(
+      `| **Total** | **${fmt(totalInput)}** | **${fmt(totalCacheRead)}** | **${fmt(totalCacheWrite)}** | **${fmt(totalOutput)}** | **${fmt(grandTotal)}** | ${totalCostCell} |`,
+    );
+  }
+
+  return [
+    "<details>",
+    "<summary>Usage</summary>",
+    "",
+    header,
+    separatorRow,
+    ...rows,
+    ...totalsRows,
+    "",
+    "</details>",
+  ].join("\n");
+}

package/src/utils/modelResolver.ts

@@ -0,0 +1,105 @@
+import type { Agent } from "#app/agents/index";
+import { resolveAgent, resolveModelWithGating } from "#app/utils/agent";
+import { validateAgentApiKey } from "#app/utils/apiKeys";
+import { installCodexAuth } from "#app/utils/codexHome";
+import {
+  captureAuthorizedModels,
+  captureBaselineModels,
+  getAuthorizedModels,
+} from "#app/utils/openCodeModels";
+import { applyManagedProxy, applyModelEnv, type ProxyMint } from "#app/utils/proxyModel";
+import type { AccountPlan } from "#app/utils/runContext";
+
+/**
+ * The single owner of the model decision. "Which model runs, on which harness,
+ * with what auth" used to be smeared across main.ts and four utils; the two
+ * entry points here are the whole story:
+ *
+ *   1. {@link captureModelAuthority} — the ordered BYOK-authority capture
+ *      (baseline → Codex auth.json → authorized set), returned as an explicit
+ *      value instead of hidden module state the caller must remember to
+ *      sequence correctly.
+ *   2. {@link resolveRunModel} — BYOK gate → managed-proxy overlay → env
+ *      patch → api-key validation, returning the routed model + harness.
+ *
+ * The building blocks stay where they are (catalog in models.ts, gate in
+ * agent.ts, proxy overlay in proxyModel.ts); this module owns their
+ * composition and ordering.
+ */
+
+/**
+ * Capture the BYOK model authority in the one order that is correct:
+ * the BASELINE set (what OpenCode can route from the runner's pre-existing
+ * env alone) must be snapshotted BEFORE Codex auth.json is materialized, and
+ * the AUTHORIZED set after — their diff is the Codex credential's
+ * contribution, logged by the capture. Returns the authorized set, the
+ * authoritative input for {@link resolveRunModel}.
+ */
+export function captureModelAuthority(opencodeCliPath: string): Set<string> {
+  captureBaselineModels(opencodeCliPath);
+  installCodexAuth();
+  captureAuthorizedModels(opencodeCliPath);
+  return getAuthorizedModels();
+}
+
+export interface RoutedRunModel {
+  /** the effective model that will run (post-fallback); undefined → auto-select */
+  model: string | undefined;
+  /** the slug to surface in footers/logs */
+  effectiveSlug: string | undefined;
+  /** the harness resolved for the effective model */
+  agent: Agent;
+  /** set only when the free safety-net fallback engaged */
+  fallback?: { from: string; to: string };
+  /** operator warnings for the caller to log */
+  warnings: string[];
+}
+
+/**
+ * Resolve the model + auth for this run in one call: the BYOK gate (resolve
+ * slug → pick harness → free-fallback decision), the managed EU Bedrock proxy
+ * overlay (a no-op unless PAYG with no BYO key), the env patch the routing
+ * needs, and the api-key validation the gate asks for. Throws the actionable
+ * authorized-model list on an unavailable model, a `BillingError` when the
+ * managed path needs a payment method, and the missing-key error when
+ * validation fails — all before any agent runs.
+ */
+export async function resolveRunModel(input: {
+  slug: string | undefined;
+  plan: AccountPlan;
+  credential: string;
+  authorized: Set<string>;
+  repo: { owner: string; name: string };
+  mint?: ProxyMint;
+}): Promise<RoutedRunModel> {
+  const routed = await applyManagedProxy({
+    gate: resolveModelWithGating({ slug: input.slug, authorized: input.authorized }),
+    plan: input.plan,
+    credential: input.credential,
+    resolveAgent,
+    ...(input.slug ? { slug: input.slug } : {}),
+    ...(input.mint ? { mint: input.mint } : {}),
+  });
+
+  if (routed.envToApply) {
+    applyModelEnv(routed.envToApply);
+  }
+
+  if (routed.validate) {
+    validateAgentApiKey({
+      agent: routed.agent,
+      model: routed.model ?? routed.effectiveSlug,
+      authorized: input.authorized,
+      owner: input.repo.owner,
+      name: input.repo.name,
+    });
+  }
+
+  return {
+    model: routed.model,
+    effectiveSlug: routed.effectiveSlug,
+    agent: routed.agent,
+    warnings: routed.warnings,
+    ...(routed.fallback ? { fallback: routed.fallback } : {}),
+  };
+}

package/src/utils/moduleFetch.ts

@@ -0,0 +1,138 @@
+/**
+ * Org-private cross-repo module fetch (the HepCare shape).
+ *
+ * Referencing a private module from another repo in your org works today
+ * (`git::https://github.com/acme/tf-modules.git//aws/s3?ref=…`), but FETCHING it
+ * at `terraform init` does not: the action's own git is locked down (ASKPASS,
+ * `credential.helper=`) and the job token is single-repo, so terraform's child
+ * `git clone` of the module repo has no credential. This module supplies a
+ * scoped one — a PAT / GitHub App token / fine-grained token the operator passes
+ * as `module_fetch_token`.
+ *
+ * Mechanism: Git's `GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_n` / `GIT_CONFIG_VALUE_n`
+ * env injection (Git ≥ 2.31). We add an `http.https://<host>/.extraheader`
+ * carrying a Basic auth header (the same pattern actions/checkout uses), scoped
+ * to the terraform subprocess only — no global/file config is mutated and the
+ * token never lands on disk.
+ *
+ * SSH / deploy-key sources (`git::ssh://…` / `git::git@host:…`) are a separate
+ * transport: `module_fetch_ssh_key` supplies a private key, which — unlike the
+ * token — MUST exist as a file for `ssh -i`. We write it 0600 into the run's
+ * tmpdir (wiped at run end), never the home dir or a committed path, and point a
+ * scoped `GIT_SSH_COMMAND` at it. Both credentials can apply in one run (HTTPS
+ * token for `git::https`, SSH key for `git::ssh`); they're independent env.
+ */
+import { chmodSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** the `x-access-token:<token>` Basic header value Git sends per request. */
+function basicAuthHeader(token: string): string {
+  const encoded = Buffer.from(`x-access-token:${token}`).toString("base64");
+  return `Authorization: Basic ${encoded}`;
+}
+
+/**
+ * Build the `GIT_CONFIG_*` env that authorises `git clone` of a private module
+ * over HTTPS for each host. Pure (token + hosts in, env out) so it is unit-
+ * testable without a real git. Empty/whitespace hosts are dropped; hosts are
+ * de-duplicated case-insensitively. Returns an empty object only when no usable
+ * host remains (the caller treats that as "no module-fetch credential").
+ */
+export function buildModuleFetchGitEnv(token: string, hosts: string[]): Record<string, string> {
+  const seen = new Set<string>();
+  const uniqueHosts: string[] = [];
+  for (const h of hosts) {
+    const host = h.trim().toLowerCase();
+    if (!host || seen.has(host)) continue;
+    seen.add(host);
+    uniqueHosts.push(host);
+  }
+  if (uniqueHosts.length === 0) return {};
+
+  const header = basicAuthHeader(token);
+  const env: Record<string, string> = { GIT_CONFIG_COUNT: String(uniqueHosts.length) };
+  uniqueHosts.forEach((host, i) => {
+    env[`GIT_CONFIG_KEY_${i}`] = `http.https://${host}/.extraheader`;
+    env[`GIT_CONFIG_VALUE_${i}`] = header;
+  });
+  return env;
+}
+
+/**
+ * The hosts a module-fetch credential should authorise: always github.com, plus
+ * the GitHub host the run executes against (a GitHub Enterprise Server instance
+ * via `GITHUB_SERVER_URL`) when it differs. Reads the env; pure given it.
+ */
+export function moduleFetchHosts(serverUrl = process.env.GITHUB_SERVER_URL): string[] {
+  const hosts = ["github.com"];
+  if (serverUrl) {
+    try {
+      const host = new URL(serverUrl).hostname;
+      // de-dupe case-insensitively: on github.com-hosted runs GITHUB_SERVER_URL
+      // is https://github.com, so the seeded host would otherwise repeat.
+      if (host && !hosts.some((h) => h.toLowerCase() === host.toLowerCase())) hosts.push(host);
+    } catch {
+      /* malformed GITHUB_SERVER_URL — fall back to github.com only */
+    }
+  }
+  return hosts;
+}
+
+function defaultWriteKey(path: string, contents: string): void {
+  // mode on writeFileSync is honoured on POSIX (the GitHub Actions runner); the
+  // explicit chmod is belt-and-suspenders for an existing-file overwrite + Windows
+  // local dev (where ssh applies its own perms model).
+  writeFileSync(path, contents, { mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    /* best-effort — ssh still refuses a world-readable key on POSIX */
+  }
+}
+
+/**
+ * Build the SSH env for fetching a private `git::ssh://…` module. The key MUST be
+ * a file for `ssh -i`, so it is written 0600 into `keyDir` (the run's tmpdir,
+ * wiped at run end) — never the home dir, never committed. `IdentitiesOnly=yes`
+ * stops ssh falling back to an agent or other keys; `StrictHostKeyChecking=accept-new`
+ * trusts the host on first use rather than the interactive prompt that would hang a
+ * headless run. Pure given an injected writer (so it is unit-testable without fs).
+ * Returns `{}` for a blank key.
+ */
+export function buildModuleFetchSshEnv(
+  sshKey: string,
+  keyDir: string,
+  writeKey: (path: string, contents: string) => void = defaultWriteKey,
+): Record<string, string> {
+  const key = sshKey.trim();
+  if (!key) return {};
+  const keyPath = join(keyDir, "module_fetch_key");
+  // ssh rejects a key without a trailing newline.
+  writeKey(keyPath, key.endsWith("\n") ? key : `${key}\n`);
+  const sshPath = keyPath.replace(/\\/g, "/"); // GIT_SSH_COMMAND is shell-parsed
+  return {
+    GIT_SSH_COMMAND: `ssh -i "${sshPath}" -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`,
+  };
+}
+
+/**
+ * Resolve the module-fetch git env for a run, or undefined when neither a
+ * `module_fetch_token` (HTTPS) nor a `module_fetch_ssh_key` (SSH) was supplied
+ * (the common case — public/registry/local modules need no credential). The result
+ * is merged into the env of the `terraform init`/`plan` invocations so private
+ * cross-repo modules resolve. SSH activates only when `opts.sshKeyDir` is given (a
+ * writable scratch dir for the ephemeral key — the run's tmpdir at the real sites).
+ */
+export function resolveModuleFetchEnv(
+  payload: { moduleFetchToken?: string | undefined; moduleFetchSshKey?: string | undefined },
+  opts: { sshKeyDir?: string; writeKey?: (path: string, contents: string) => void } = {},
+): Record<string, string> | undefined {
+  const env: Record<string, string> = {};
+  const token = payload.moduleFetchToken?.trim();
+  if (token) Object.assign(env, buildModuleFetchGitEnv(token, moduleFetchHosts()));
+  const sshKey = payload.moduleFetchSshKey?.trim();
+  if (sshKey && opts.sshKeyDir) {
+    Object.assign(env, buildModuleFetchSshEnv(sshKey, opts.sshKeyDir, opts.writeKey));
+  }
+  return Object.keys(env).length > 0 ? env : undefined;
+}