terramend 0.2.0

package/src/utils/activity.test.ts

@@ -0,0 +1,188 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createProcessOutputActivityTimeout, isActivityNoise } from "#app/utils/activity";
+
+describe("isActivityNoise", () => {
+  it("flags empty and whitespace-only chunks as noise", () => {
+    expect(isActivityNoise("")).toBe(true);
+    expect(isActivityNoise("   \n\t\n")).toBe(true);
+  });
+
+  it("flags pure mcp-proxy reconnect chatter as noise", () => {
+    expect(
+      isActivityNoise("[mcp-proxy] establishing new SSE stream for session ID abc-123\n"),
+    ).toBe(true);
+    expect(
+      isActivityNoise(
+        "[mcp-proxy] establishing new SSE stream for session ID a\n[mcp-proxy] received delete request\n",
+      ),
+    ).toBe(true);
+  });
+
+  it("flags provider-error retry lines as noise", () => {
+    expect(isActivityNoise("» provider error detected (rate_limit): ...\n")).toBe(true);
+  });
+
+  it("treats real agent output as activity", () => {
+    expect(isActivityNoise('{"type":"tool_use","id":"toolu_01"}\n')).toBe(false);
+    expect(isActivityNoise("Leaping into action...\n")).toBe(false);
+  });
+
+  it("treats mixed chunks (some noise + some real output) as activity", () => {
+    const mixed =
+      "[mcp-proxy] establishing new SSE stream for session ID abc\n" +
+      '{"type":"assistant_message"}\n';
+    expect(isActivityNoise(mixed)).toBe(false);
+  });
+
+  it("accepts Buffer input", () => {
+    expect(isActivityNoise(Buffer.from("[mcp-proxy] received delete request\n"))).toBe(true);
+    expect(isActivityNoise(Buffer.from('{"type":"tool_use"}\n'))).toBe(false);
+  });
+
+  it("flags chunks with only noise + blank lines as noise", () => {
+    const noiseWithBlanks =
+      "\n[mcp-proxy] establishing new SSE stream for session ID abc\n\n" +
+      "[mcp-proxy] received delete request\n\n";
+    expect(isActivityNoise(noiseWithBlanks)).toBe(true);
+  });
+
+  it("does not match the noise pattern mid-line", () => {
+    // `[mcp-proxy]` must anchor at start; embedded in agent output it's activity
+    expect(isActivityNoise("agent said: [mcp-proxy] was there\n")).toBe(false);
+    expect(isActivityNoise("context: provider error detected in log\n")).toBe(false);
+  });
+
+  it("flags debug-timestamp-prefixed noise lines", () => {
+    expect(
+      isActivityNoise("[2026-04-18T17:00:00.000Z] [mcp-proxy] establishing new SSE stream\n"),
+    ).toBe(true);
+    expect(
+      isActivityNoise("[2026-04-18T17:00:00.000Z] » provider error detected (rate_limit)\n"),
+    ).toBe(true);
+  });
+
+  it("flags our own monitor debug output (local-debug format)", () => {
+    // subprocess.ts's spawn activity check fires every 5s when debug is on;
+    // without this filter the outer timer would be reset each interval and
+    // the agent-hang detection (#12) silently fails in debug-enabled runs.
+    expect(
+      isActivityNoise(
+        "[2026-04-18T17:00:00.000Z] [DEBUG] spawn activity check: pid=123 idle=5000ms / 300000ms\n",
+      ),
+    ).toBe(true);
+    expect(
+      isActivityNoise(
+        "[2026-04-18T17:00:00.000Z] [DEBUG] spawn activity timer: pid=123 cmd=claude timeout=300000ms\n",
+      ),
+    ).toBe(true);
+    expect(
+      isActivityNoise(
+        "[2026-04-18T17:00:00.000Z] [DEBUG] process activity check: idle=120ms / 300000ms\n",
+      ),
+    ).toBe(true);
+  });
+
+  it("flags our own monitor debug output (GH-runner-debug ::debug:: format)", () => {
+    expect(isActivityNoise("::debug::spawn activity check: pid=123 idle=5000ms / 300000ms\n")).toBe(
+      true,
+    );
+    expect(isActivityNoise("::debug::process activity check: idle=120ms / 300000ms\n")).toBe(true);
+  });
+
+  it("does not blanket-filter other debug-prefixed lines", () => {
+    // the filter is scoped to our own monitor diagnostics so genuine agent
+    // output that coincidentally starts with [DEBUG] still counts as activity.
+    expect(isActivityNoise("[2026-04-18T17:00:00.000Z] [DEBUG] git auth server listening\n")).toBe(
+      false,
+    );
+    expect(isActivityNoise("::debug::agent stream chunk\n")).toBe(false);
+  });
+});
+
+describe("createProcessOutputActivityTimeout (debug-mode feedback loop)", () => {
+  // the monitor's own periodic diagnostic log used to travel through the
+  // wrapped process.stdout.write — in debug mode that meant the interval
+  // callback kept resetting the activity timer, so the timeout could never
+  // fire. guard against that regression by running the monitor under a
+  // simulated debug env with a tight timeout and confirming it still rejects.
+  const previousStepDebug = process.env.ACTIONS_STEP_DEBUG;
+
+  beforeEach(() => {
+    process.env.ACTIONS_STEP_DEBUG = "true";
+  });
+
+  afterEach(() => {
+    if (previousStepDebug === undefined) delete process.env.ACTIONS_STEP_DEBUG;
+    else process.env.ACTIONS_STEP_DEBUG = previousStepDebug;
+  });
+
+  it("still times out in debug mode even though the monitor emits periodic diagnostics", async () => {
+    const timeout = createProcessOutputActivityTimeout({
+      timeoutMs: 150,
+      checkIntervalMs: 20,
+    });
+    try {
+      await expect(timeout.promise).rejects.toThrow(/activity timeout/);
+    } finally {
+      timeout.stop();
+    }
+  });
+});
+
+describe("createProcessOutputActivityTimeout forceReject / stop disarming", () => {
+  // main.ts arms a 5min safety-net timer on inner-activity kill that later
+  // calls forceReject. when the agent succeeds first, main.ts calls stop().
+  // stop() must disarm forceReject — otherwise a late safety-net fire would
+  // reject a promise nothing is awaiting, re-creating the #12 zombie-run
+  // shape (unhandledRejection) or worse, failing a successful run.
+  it("forceReject rejects the promise with the given reason", async () => {
+    const timeout = createProcessOutputActivityTimeout({
+      timeoutMs: 60_000,
+      checkIntervalMs: 10_000,
+    });
+    try {
+      timeout.forceReject("safety-net fired");
+      await expect(timeout.promise).rejects.toThrow(/safety-net fired/);
+    } finally {
+      timeout.stop();
+    }
+  });
+
+  it("stop() disarms forceReject so a late safety-net fire is a no-op", async () => {
+    const timeout = createProcessOutputActivityTimeout({
+      timeoutMs: 60_000,
+      checkIntervalMs: 10_000,
+    });
+    // prevent unhandled-rejection noise if the assertion below ever regresses
+    timeout.promise.catch(() => {});
+
+    timeout.stop();
+    timeout.forceReject("late safety-net fire after run succeeded");
+
+    // race the promise against a short sleep; if forceReject reopened the
+    // rejection it would win the race. the sleep should always win.
+    const sentinel = Symbol("still-pending");
+    const winner = await Promise.race([
+      timeout.promise.then(
+        () => "resolved",
+        () => "rejected",
+      ),
+      new Promise((resolve) => setTimeout(() => resolve(sentinel), 50)),
+    ]);
+    expect(winner).toBe(sentinel);
+  });
+
+  it("forceReject is a no-op if the promise already rejected via the timer", async () => {
+    const timeout = createProcessOutputActivityTimeout({
+      timeoutMs: 60,
+      checkIntervalMs: 10,
+    });
+    try {
+      await expect(timeout.promise).rejects.toThrow(/activity timeout/);
+      // forceReject after timer rejection must not throw or double-reject
+      expect(() => timeout.forceReject("should be ignored")).not.toThrow();
+    } finally {
+      timeout.stop();
+    }
+  });
+});

package/src/utils/activity.ts

@@ -0,0 +1,210 @@
+import { performance } from "node:perf_hooks";
+
+function isMonitorDebugEnabled(): boolean {
+  return (
+    process.env.ACTIONS_STEP_DEBUG === "true" ||
+    process.env.RUNNER_DEBUG === "1" ||
+    process.env.LOG_LEVEL === "debug"
+  );
+}
+
+/**
+ * generic `spawn()` idle default for ordinary short-lived subprocesses (prep
+ * probes, package-manager invocations, dependency installs). these should be
+ * producing output steadily, so a comparatively tight budget catches a wedged
+ * command promptly. the long-silent-tool tolerance the agent harnesses need
+ * lives in AGENT_ACTIVITY_TIMEOUT_MS, applied explicitly at those sites.
+ */
+export const DEFAULT_ACTIVITY_TIMEOUT_MS = 300_000;
+
+/**
+ * flat idle budget for the agent activity watchdog (the outer process-output
+ * monitor, the v1 harness spawns, and the v2 inner event-silence watchdog).
+ * sized to exceed the worst-case legitimate silent tool window (issue #760:
+ * `checkout_pr` git fetch+deepen on a large monorepo, ~4-5min) with generous
+ * headroom, so no single in-flight tool call can be mistaken for a stall. a
+ * timeout this generous needs no suspend/resume bracketing — the cost of a
+ * genuinely hung run is only GitHub Actions minutes, not tokens.
+ */
+export const AGENT_ACTIVITY_TIMEOUT_MS = 900_000;
+export const DEFAULT_ACTIVITY_CHECK_INTERVAL_MS = 5_000;
+
+/**
+ * chunks whose every non-empty line matches one of these patterns do not
+ * count as agent activity. mcp-proxy SSE reconnects and provider-error
+ * retries happen on their own schedule and were keeping the outer activity
+ * timer alive long after the agent subprocess had been killed for inactivity,
+ * producing multi-hour zombie runs.
+ *
+ * both patterns anchor to the start of the (optionally debug-timestamped)
+ * log line so they don't accidentally match agent output that happens to
+ * mention "[mcp-proxy]" or "provider error detected" in analysis text.
+ */
+const DEBUG_TS_PREFIX = /^(?:\[\d{4}-\d{2}-\d{2}T[^\]]+\]\s+)?/.source;
+// our own internal monitors (this file's bypass + subprocess.ts's spawn
+// activity timer) emit high-frequency diagnostic logs when debug logging is
+// enabled. in the past those lines reached the wrapped process.stdout.write,
+// missed the noise check, and marked activity every interval — which in
+// debug-enabled runs kept the outer timer alive after the agent subprocess
+// was already dead, re-creating the #12 zombie-run bug. the `(?:spawn|process)
+// activity ` patterns below explicitly filter our own diagnostic lines in both
+// local-debug (`[DEBUG] …`) and GH-runner-debug (`::debug::…`) formats.
+export const ACTIVITY_NOISE_PATTERNS: readonly RegExp[] = [
+  new RegExp(`${DEBUG_TS_PREFIX}\\[mcp-proxy\\]`),
+  new RegExp(`${DEBUG_TS_PREFIX}» provider error detected`),
+  new RegExp(`${DEBUG_TS_PREFIX}\\[DEBUG\\]\\s+(?:spawn|process) activity `),
+  /^::debug::(?:spawn|process) activity /,
+];
+
+export function isActivityNoise(chunk: string | Uint8Array): boolean {
+  const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+  if (!text.trim()) return true;
+  return text.split("\n").every((line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return true;
+    return ACTIVITY_NOISE_PATTERNS.some((pattern) => pattern.test(trimmed));
+  });
+}
+
+type ActivityTimeoutContext = {
+  timeoutMs: number;
+  checkIntervalMs: number;
+};
+
+export type ActivityTimeout = {
+  promise: Promise<never>;
+  stop: () => void;
+  /** force the timeout to reject immediately with a custom reason */
+  forceReject: (reason: string) => void;
+};
+
+type OutputMonitorContext = {
+  timeoutMs: number;
+  checkIntervalMs: number;
+  onTimeout: (idleMs: number) => void;
+};
+
+type OutputMonitor = {
+  stop: () => void;
+};
+
+type WriteCallback = (error?: Error | null) => void;
+type WriteFunction = {
+  (chunk: string | Uint8Array, cb?: WriteCallback): boolean;
+  (chunk: string | Uint8Array, encoding?: BufferEncoding, cb?: WriteCallback): boolean;
+};
+
+// module-level activity tracking - allows agents to mark activity on any event
+let _lastActivity = performance.now();
+
+/**
+ * mark activity to reset the no-output timeout.
+ * call this whenever the agent emits any event, even if it isn't logged to stdout.
+ */
+export function markActivity(): void {
+  _lastActivity = performance.now();
+}
+
+/** get the time since last activity in milliseconds. */
+export function getIdleMs(): number {
+  return Math.round(performance.now() - _lastActivity);
+}
+
+function wrapWrite(original: WriteFunction, onActivity: () => void): WriteFunction {
+  const wrapped: WriteFunction = (
+    chunk: string | Uint8Array,
+    encodingOrCb?: BufferEncoding | WriteCallback,
+    cb?: WriteCallback,
+  ): boolean => {
+    if (!isActivityNoise(chunk)) {
+      onActivity();
+    }
+    if (typeof encodingOrCb === "function") {
+      return original(chunk, encodingOrCb);
+    }
+    return original(chunk, encodingOrCb, cb);
+  };
+  return wrapped;
+}
+
+function startProcessOutputMonitor(ctx: OutputMonitorContext): OutputMonitor {
+  let timedOut = false;
+
+  const originalStdoutWrite: WriteFunction = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite: WriteFunction = process.stderr.write.bind(process.stderr);
+
+  // stdout/stderr writes also mark activity
+  process.stdout.write = wrapWrite(originalStdoutWrite, markActivity);
+  process.stderr.write = wrapWrite(originalStderrWrite, markActivity);
+
+  // route the monitor's own diagnostics through the captured original write
+  // instead of log.debug — otherwise those lines feed back through the
+  // wrapped process.stdout.write, miss isActivityNoise, and call
+  // markActivity() themselves. in debug mode the periodic check below would
+  // then reset the timer every interval and the timeout would never fire,
+  // re-creating the exact zombie-run bug #12 was meant to kill.
+  const debugBypass = (msg: string): void => {
+    if (!isMonitorDebugEnabled()) return;
+    originalStdoutWrite(`[${new Date().toISOString()}] [DEBUG] ${msg}\n`);
+  };
+
+  debugBypass(`process activity monitor started: timeout=${ctx.timeoutMs}ms`);
+
+  const intervalId = setInterval(() => {
+    const idleMs = getIdleMs();
+    debugBypass(`process activity check: idle=${idleMs}ms / ${ctx.timeoutMs}ms`);
+    if (timedOut || idleMs <= ctx.timeoutMs) return;
+    timedOut = true;
+    ctx.onTimeout(idleMs);
+  }, ctx.checkIntervalMs);
+
+  function stop(): void {
+    clearInterval(intervalId);
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { stop };
+}
+
+export function createProcessOutputActivityTimeout(ctx: ActivityTimeoutContext): ActivityTimeout {
+  markActivity(); // reset baseline
+
+  let rejectFn: ((error: Error) => void) | null = null;
+  const promise = new Promise<never>((_, reject) => {
+    rejectFn = reject;
+  });
+
+  let monitor: OutputMonitor | null = null;
+  monitor = startProcessOutputMonitor({
+    timeoutMs: ctx.timeoutMs,
+    checkIntervalMs: ctx.checkIntervalMs,
+    onTimeout: (idleMs) => {
+      if (!rejectFn) return;
+      const idleSec = Math.round(idleMs / 1000);
+      if (monitor) {
+        monitor.stop();
+      }
+      const reject = rejectFn;
+      rejectFn = null;
+      reject(new Error(`activity timeout: no output for ${idleSec}s`));
+    },
+  });
+
+  return {
+    promise,
+    // stop() also disarms forceReject so a late safety-net fire can't reject
+    // the promise after the run has already succeeded.
+    stop: () => {
+      monitor?.stop();
+      rejectFn = null;
+    },
+    forceReject: (reason: string) => {
+      if (!rejectFn) return;
+      monitor?.stop();
+      const reject = rejectFn;
+      rejectFn = null;
+      reject(new Error(reason));
+    },
+  };
+}

package/src/utils/agent.test.ts

@@ -0,0 +1,251 @@
+import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { resolveAgent, resolveModel } from "#app/utils/agent";
+import { cleanupVertexCredentials, materializeVertexCredentials } from "#app/utils/vertex";
+
+const savedEnv = { ...process.env };
+
+const STRIPPED = [
+  /_API_KEY$/,
+  /^CLAUDE_CODE_OAUTH_TOKEN$/,
+  /^AWS_BEARER_TOKEN_BEDROCK$/,
+  /^AWS_ACCESS_KEY_ID$/,
+  /^AWS_SECRET_ACCESS_KEY$/,
+  /^AWS_SESSION_TOKEN$/,
+  /^AWS_REGION$/,
+  /^BEDROCK_MODEL_ID$/,
+  /^GOOGLE_APPLICATION_CREDENTIALS$/,
+  /^GOOGLE_CLOUD_PROJECT$/,
+  /^VERTEX_SERVICE_ACCOUNT_JSON$/,
+  /^VERTEX_LOCATION$/,
+  /^VERTEX_MODEL_ID$/,
+  /^TERRAMEND_SECRET_HOME$/,
+  /^TERRAMEND_MODEL$/,
+  /^TERRAMEND_AGENT$/,
+];
+
+beforeEach(() => {
+  for (const key of Object.keys(process.env)) {
+    if (STRIPPED.some((re) => re.test(key))) delete process.env[key];
+  }
+});
+
+afterEach(() => {
+  process.env = { ...savedEnv };
+});
+
+describe("resolveAgent", () => {
+  it("returns opencode by default", () => {
+    expect(resolveAgent({}).name).toBe("opencode");
+  });
+
+  it("routes anthropic/* to claude when ANTHROPIC_API_KEY is set", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-test";
+    expect(resolveAgent({ model: "anthropic/claude-opus-4-7" }).name).toBe("claude");
+  });
+
+  it("falls back to opencode for anthropic/* without claude-code creds", () => {
+    expect(resolveAgent({ model: "anthropic/claude-opus-4-7" }).name).toBe("opencode");
+  });
+
+  describe("bedrock routing", () => {
+    it("routes Anthropic Bedrock IDs to claude", () => {
+      process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
+      process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+      expect(resolveAgent({ model: "eu.anthropic.claude-opus-4-7" }).name).toBe("claude");
+    });
+
+    it("routes Anthropic Bedrock IDs (no region prefix) to claude", () => {
+      process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
+      process.env.BEDROCK_MODEL_ID = "anthropic.claude-haiku-4-5-20251001-v1:0";
+      expect(resolveAgent({ model: "anthropic.claude-haiku-4-5-20251001-v1:0" }).name).toBe(
+        "claude",
+      );
+    });
+
+    it("routes non-Anthropic Bedrock IDs to opencode", () => {
+      process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
+      process.env.BEDROCK_MODEL_ID = "amazon.nova-pro-v1:0";
+      expect(resolveAgent({ model: "amazon.nova-pro-v1:0" }).name).toBe("opencode");
+    });
+
+    it("routes Llama IDs to opencode", () => {
+      process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
+      process.env.BEDROCK_MODEL_ID = "eu.meta.llama4-scout-17b-instruct-v1:0";
+      expect(resolveAgent({ model: "eu.meta.llama4-scout-17b-instruct-v1:0" }).name).toBe(
+        "opencode",
+      );
+    });
+
+    it("accepts AWS access keys as auth", () => {
+      process.env.AWS_ACCESS_KEY_ID = "AKIA-test";
+      process.env.AWS_SECRET_ACCESS_KEY = "secret-test";
+      process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+      expect(resolveAgent({ model: "eu.anthropic.claude-opus-4-7" }).name).toBe("claude");
+    });
+
+    it("TERRAMEND_AGENT override wins over Anthropic auto-routing", () => {
+      process.env.TERRAMEND_AGENT = "opencode";
+      process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
+      process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+      expect(resolveAgent({ model: "eu.anthropic.claude-opus-4-7" }).name).toBe("opencode");
+    });
+  });
+
+  describe("vertex routing", () => {
+    it("routes Anthropic Vertex IDs to claude", () => {
+      process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
+      process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
+      expect(resolveAgent({ model: "claude-opus-4-1@20250805" }).name).toBe("claude");
+    });
+
+    it("routes Gemini Vertex IDs to opencode", () => {
+      process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
+      process.env.VERTEX_MODEL_ID = "gemini-2.5-pro";
+      expect(resolveAgent({ model: "gemini-2.5-pro" }).name).toBe("opencode");
+    });
+  });
+});
+
+describe("resolveModel", () => {
+  it("TERRAMEND_MODEL override wins", () => {
+    process.env.TERRAMEND_MODEL = "anthropic/claude-opus";
+    expect(resolveModel({ slug: "openai/gpt" })).toBe("anthropic/claude-opus-4-8");
+  });
+
+  it("TERRAMEND_MODEL bypasses bedrock routing entirely", () => {
+    process.env.TERRAMEND_MODEL = "openai/gpt";
+    process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+    expect(resolveModel({ slug: "bedrock/byok" })).toBe("openai/gpt-5.5");
+  });
+
+  it("resolves bedrock/byok to BEDROCK_MODEL_ID", () => {
+    process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+    expect(resolveModel({ slug: "bedrock/byok" })).toBe("eu.anthropic.claude-opus-4-7");
+  });
+
+  it("throws when bedrock/byok is selected without BEDROCK_MODEL_ID", () => {
+    expect(() => resolveModel({ slug: "bedrock/byok" })).toThrow("BEDROCK_MODEL_ID");
+  });
+
+  it("returns the alias resolve for normal slugs", () => {
+    expect(resolveModel({ slug: "openai/gpt" })).toBe("openai/gpt-5.5");
+  });
+
+  it("returns undefined for no slug + no TERRAMEND_MODEL", () => {
+    expect(resolveModel({})).toBeUndefined();
+  });
+
+  // regression: PR #720 review caught that `resolveCliModel("bedrock/byok")`
+  // returns the literal sentinel `"bedrock"` from the alias's `resolve`
+  // field. Without routing-aware handling, TERRAMEND_MODEL=bedrock/byok would
+  // leak that sentinel downstream and break agent dispatch.
+  it("TERRAMEND_MODEL=bedrock/byok defers to BEDROCK_MODEL_ID, not the sentinel", () => {
+    process.env.TERRAMEND_MODEL = "bedrock/byok";
+    process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+    expect(resolveModel({ slug: "openai/gpt" })).toBe("eu.anthropic.claude-opus-4-7");
+  });
+
+  it("TERRAMEND_MODEL=bedrock/byok throws if BEDROCK_MODEL_ID is missing", () => {
+    process.env.TERRAMEND_MODEL = "bedrock/byok";
+    expect(() => resolveModel({ slug: "openai/gpt" })).toThrow("BEDROCK_MODEL_ID");
+  });
+
+  it("resolves vertex/byok to VERTEX_MODEL_ID", () => {
+    process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
+    expect(resolveModel({ slug: "vertex/byok" })).toBe("claude-opus-4-1@20250805");
+  });
+
+  it("throws when vertex/byok is selected without VERTEX_MODEL_ID", () => {
+    expect(() => resolveModel({ slug: "vertex/byok" })).toThrow("VERTEX_MODEL_ID");
+  });
+
+  it("TERRAMEND_MODEL=vertex/byok defers to VERTEX_MODEL_ID, not the sentinel", () => {
+    process.env.TERRAMEND_MODEL = "vertex/byok";
+    process.env.VERTEX_MODEL_ID = "gemini-2.5-pro";
+    expect(resolveModel({ slug: "openai/gpt" })).toBe("gemini-2.5-pro");
+  });
+
+  it("TERRAMEND_MODEL=vertex/byok throws if VERTEX_MODEL_ID is missing", () => {
+    process.env.TERRAMEND_MODEL = "vertex/byok";
+    expect(() => resolveModel({ slug: "openai/gpt" })).toThrow("VERTEX_MODEL_ID");
+  });
+
+  it("passes a raw TERRAMEND_MODEL specifier through when it is not a registry alias", () => {
+    process.env.TERRAMEND_MODEL = "anthropic/claude-opus-4-6-20250514";
+    expect(resolveModel({ slug: "openai/gpt" })).toBe("anthropic/claude-opus-4-6-20250514");
+  });
+
+  it("returns undefined for an unknown slug (warn-and-auto-select path)", () => {
+    expect(resolveModel({ slug: "nope/not-a-model" })).toBeUndefined();
+  });
+});
+
+describe("resolveAgent — TERRAMEND_AGENT override and fallthroughs", () => {
+  it("returns the named agent for a valid TERRAMEND_AGENT", () => {
+    process.env.TERRAMEND_AGENT = "claude";
+    expect(resolveAgent({}).name).toBe("claude");
+  });
+
+  it("falls through to the default for an unknown TERRAMEND_AGENT", () => {
+    process.env.TERRAMEND_AGENT = "codex";
+    expect(resolveAgent({}).name).toBe("opencode");
+  });
+
+  it("unknown TERRAMEND_AGENT still honors Anthropic model routing", () => {
+    process.env.TERRAMEND_AGENT = "nope";
+    process.env.ANTHROPIC_API_KEY = "sk-test";
+    expect(resolveAgent({ model: "anthropic/claude-opus-4-7" }).name).toBe("claude");
+  });
+
+  it("routes anthropic/* to claude on CLAUDE_CODE_OAUTH_TOKEN alone", () => {
+    process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-token";
+    expect(resolveAgent({ model: "anthropic/claude-opus-4-7" }).name).toBe("claude");
+  });
+
+  it("falls through to opencode for an invalid model format even with claude creds", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-test";
+    expect(resolveAgent({ model: "no-slash-model" }).name).toBe("opencode");
+  });
+
+  it("ignores the bedrock route when AWS auth is missing", () => {
+    process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+    expect(resolveAgent({ model: "eu.anthropic.claude-opus-4-7" }).name).toBe("opencode");
+  });
+
+  it("ignores the vertex route when VERTEX_MODEL_ID does not match the model", () => {
+    process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
+    process.env.VERTEX_MODEL_ID = "some-other-model";
+    expect(resolveAgent({ model: "claude-opus-4-1@20250805" }).name).toBe("opencode");
+  });
+});
+
+describe("materializeVertexCredentials", () => {
+  it("writes service-account JSON outside tmpdir and defaults project from project_id", () => {
+    const dir = mkdtempSync(join(tmpdir(), "vertex-creds-test-"));
+    process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
+    process.env.TERRAMEND_SECRET_HOME = dir;
+    process.env.VERTEX_SERVICE_ACCOUNT_JSON = JSON.stringify({
+      project_id: "test-project",
+      client_email: "terramend@test-project.iam.gserviceaccount.com",
+    });
+
+    try {
+      const credentials = materializeVertexCredentials({ model: "claude-opus-4-1@20250805" });
+
+      if (!credentials) throw new Error("expected vertex credentials");
+      expect(credentials.credentialsPath).toContain(join(dir, ".terramend", "secrets"));
+      expect(process.env.GOOGLE_APPLICATION_CREDENTIALS).toBe(credentials.credentialsPath);
+      expect(process.env.GOOGLE_CLOUD_PROJECT).toBe("test-project");
+      expect(readFileSync(credentials.credentialsPath, "utf8")).toBe(
+        process.env.VERTEX_SERVICE_ACCOUNT_JSON,
+      );
+      expect(statSync(credentials.credentialsPath).mode & 0o777).toBe(0o600);
+      cleanupVertexCredentials(credentials);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});