infraweaver 0.1.0

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.ts

@@ -0,0 +1,245 @@
+import type { Agent } from "#app/agents/index";
+import { agents } from "#app/agents/index";
+import { DOCS_URL } from "#app/brand";
+import {
+  BEDROCK_MODEL_ID_ENV,
+  getModelProvider,
+  isBedrockAnthropicId,
+  isVertexAnthropicId,
+  OPENAI_COMPATIBLE_MODEL_ID_ENV,
+  resolveCliModel,
+  resolveDisplayAlias,
+  VERTEX_MODEL_ID_ENV,
+} from "#app/models";
+import {
+  buildUnavailableModelError,
+  hasProviderKeyForModel,
+  selectFallbackModelIfNeeded,
+} from "#app/utils/byokFallback";
+import { log } from "#app/utils/cli";
+import {
+  OPENAI_COMPATIBLE_BASE_URL_ENV,
+  isOpenAiCompatibleRoute,
+} from "#app/utils/openaiCompatible";
+import { VERTEX_SERVICE_ACCOUNT_JSON_ENV } from "#app/utils/vertex";
+import { hasEnvVar } from "#app/utils/env";
+
+function hasClaudeCodeAuth(): boolean {
+  return hasEnvVar("CLAUDE_CODE_OAUTH_TOKEN") || hasEnvVar("ANTHROPIC_API_KEY");
+}
+
+function hasBedrockAuth(): boolean {
+  return (
+    hasEnvVar("AWS_BEARER_TOKEN_BEDROCK") ||
+    (hasEnvVar("AWS_ACCESS_KEY_ID") && hasEnvVar("AWS_SECRET_ACCESS_KEY"))
+  );
+}
+
+function hasVertexAuth(): boolean {
+  return hasEnvVar(VERTEX_SERVICE_ACCOUNT_JSON_ENV);
+}
+
+/**
+ * resolve a single slug to its CLI-ready model string. routing aliases
+ * (e.g. `bedrock/byok`) defer to their backing env var instead of the
+ * sentinel stored in `resolve`. shared between INFRAWEAVER_MODEL override
+ * and repo-config slug resolution so both paths get the same routing
+ * semantics — without this helper, `INFRAWEAVER_MODEL=bedrock/byok` would
+ * leak the literal sentinel string `"bedrock"` downstream.
+ */
+function resolveSlug(slug: string): string | undefined {
+  const alias = resolveDisplayAlias(slug);
+  if (alias?.routing === "bedrock") {
+    const bedrockId = process.env[BEDROCK_MODEL_ID_ENV]?.trim();
+    if (!bedrockId) {
+      throw new Error(
+        `${BEDROCK_MODEL_ID_ENV} env var is required when the model is set to "${slug}". ` +
+          `set it to an AWS Bedrock model ID from the Bedrock console. ` +
+          `see ${DOCS_URL}/bedrock for setup.`,
+      );
+    }
+    return bedrockId;
+  }
+  if (alias?.routing === "vertex") {
+    const vertexId = process.env[VERTEX_MODEL_ID_ENV]?.trim();
+    if (!vertexId) {
+      throw new Error(
+        `${VERTEX_MODEL_ID_ENV} env var is required when the model is set to "${slug}". ` +
+          `set it to a Google Vertex AI model ID from Model Garden. ` +
+          `see ${DOCS_URL}/vertex for setup.`,
+      );
+    }
+    return vertexId;
+  }
+  if (alias?.routing === "openai-compatible") {
+    const modelId = process.env[OPENAI_COMPATIBLE_MODEL_ID_ENV]?.trim();
+    if (!modelId) {
+      throw new Error(
+        `${OPENAI_COMPATIBLE_MODEL_ID_ENV} env var is required when the model is set to "${slug}". ` +
+          `set it to the model id your endpoint serves (and ${OPENAI_COMPATIBLE_BASE_URL_ENV} to the endpoint URL). ` +
+          `see ${DOCS_URL}/openai-compatible for setup.`,
+      );
+    }
+    return modelId;
+  }
+  return resolveCliModel(slug);
+}
+
+/**
+ * resolve the effective model for this run.
+ *
+ * priority:
+ *   1. INFRAWEAVER_MODEL env var — resolved through the alias registry first,
+ *      so values like "anthropic/claude-opus" become "anthropic/claude-opus-4-7".
+ *      raw specifiers (e.g. "anthropic/claude-opus-4-6") pass through unchanged.
+ *      always wins — bypasses Bedrock routing entirely. to test a different
+ *      Bedrock model, change `BEDROCK_MODEL_ID`, not `INFRAWEAVER_MODEL`.
+ *   2. slug from repo config / payload → alias registry. routing slugs
+ *      (e.g. `bedrock/byok`) defer to a separate env var (`BEDROCK_MODEL_ID`).
+ *   3. undefined — agent will auto-select.
+ */
+export function resolveModel(ctx: {
+  slug?: string | undefined;
+}): string | undefined {
+  const envModel = process.env.INFRAWEAVER_MODEL?.trim();
+  if (envModel) {
+    return resolveSlug(envModel) ?? envModel;
+  }
+
+  if (ctx.slug) {
+    const resolved = resolveSlug(ctx.slug);
+    if (resolved) {
+      return resolved;
+    }
+    log.warning(`» unknown model slug "${ctx.slug}" — agent will auto-select`);
+  }
+
+  return undefined;
+}
+
+export function resolveAgent(ctx: { model?: string | undefined }): Agent {
+  // 1. explicit env var override (escape hatch)
+  const envAgent = process.env.INFRAWEAVER_AGENT?.trim();
+  if (envAgent) {
+    if (envAgent in agents) {
+      return agents[envAgent as keyof typeof agents];
+    }
+    log.warning(
+      `» unknown INFRAWEAVER_AGENT="${envAgent}" — falling through to auto-select`,
+    );
+  }
+
+  // 2. Bedrock routing: when BEDROCK_MODEL_ID is the resolved model, route
+  //    Anthropic IDs through claude-code (which supports Bedrock natively
+  //    once CLAUDE_CODE_USE_BEDROCK=1) and everything else through opencode's
+  //    `amazon-bedrock` provider.
+  if (
+    ctx.model &&
+    hasBedrockAuth() &&
+    process.env[BEDROCK_MODEL_ID_ENV]?.trim() === ctx.model
+  ) {
+    return isBedrockAnthropicId(ctx.model) ? agents.claude : agents.opencode;
+  }
+
+  // 3. Vertex routing: same shape as Bedrock, but Anthropic Vertex IDs are
+  //    anchored `claude-*` IDs and non-Anthropic models use opencode's
+  //    `google-vertex` provider.
+  if (
+    ctx.model &&
+    hasVertexAuth() &&
+    process.env[VERTEX_MODEL_ID_ENV]?.trim() === ctx.model
+  ) {
+    return isVertexAnthropicId(ctx.model) ? agents.claude : agents.opencode;
+  }
+
+  // 3b. OpenAI-compatible BYOK endpoint: always opencode (the custom-provider
+  //     block speaks the OpenAI wire format; claude-code is never involved).
+  //     Checked before the Anthropic branch so an endpoint whose model id starts
+  //     with "anthropic/" can't be mis-routed to claude-code.
+  if (ctx.model && isOpenAiCompatibleRoute(ctx.model)) {
+    return agents.opencode;
+  }
+
+  // 4. if model is Anthropic and Claude Code credentials are available, use Claude Code
+  if (ctx.model) {
+    try {
+      const provider = getModelProvider(ctx.model);
+      if (provider === "anthropic" && hasClaudeCodeAuth()) {
+        return agents.claude;
+      }
+    } catch {
+      // invalid model format — fall through
+    }
+  }
+
+  // 5. default: OpenCode (universal, supports all providers)
+  return agents.opencode;
+}
+
+/**
+ * The single BYOK model gate: resolve the slug, pick the harness, and run the
+ * fallback decision in one place. Throws the actionable authorized-model list
+ * on the `unavailable` decision (key present but model unroutable — fail loudly,
+ * never silently downgrade).
+ */
+export interface ModelGateResult {
+  /** 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 to log at the orchestration layer */
+  warnings: string[];
+  /** whether the caller should still run `validateAgentApiKey` */
+  validate: boolean;
+}
+
+export function resolveModelWithGating(input: {
+  slug?: string | undefined;
+  authorized: Set<string>;
+}): ModelGateResult {
+  const initialModel = resolveModel({ slug: input.slug });
+  const initialAgent = resolveAgent({ model: initialModel });
+
+  const decision = selectFallbackModelIfNeeded({
+    resolvedModel: initialModel,
+    authorized: input.authorized,
+    providerKeyPresent: initialModel
+      ? hasProviderKeyForModel(initialModel)
+      : false,
+    agentName: initialAgent.name,
+  });
+
+  if (decision.kind === "unavailable") {
+    throw new Error(
+      buildUnavailableModelError({
+        model: decision.model,
+        authorized: input.authorized,
+      }),
+    );
+  }
+
+  if (decision.kind === "fallback") {
+    return {
+      model: decision.to,
+      effectiveSlug: decision.to,
+      agent: resolveAgent({ model: decision.to }),
+      fallback: { from: decision.from, to: decision.to },
+      warnings: [
+        `» fell back from ${decision.from} to ${decision.to} — no provider key present in runner env. add a provider key in repo secrets to use ${decision.from} instead.`,
+      ],
+      validate: false,
+    };
+  }
+
+  return {
+    model: initialModel,
+    effectiveSlug: input.slug,
+    agent: initialAgent,
+    warnings: [],
+    validate: true,
+  };
+}

package/src/utils/agentHangReport.ts

@@ -0,0 +1,180 @@
+import { PRODUCT_NAME } from "#app/brand";
+
+const MAX_STDERR_BYTES = 3000;
+
+/**
+ * mutable per-run handle the agent harness writes to as a run progresses.
+ * the action's outer try/catch in `main.ts` reads this off `toolState` when
+ * the activity-timeout watchdog wins the race against the harness's own
+ * catch — the bare timer reject reason ("activity timeout: no output for
+ * 302s") tells the user nothing actionable, but `recentStderr` +
+ * `lastProviderError` together usually point straight at the upstream cause.
+ *
+ * `recentStderr` is shared by reference with the harness's bounded ring
+ * buffer, so the diagnostic always reflects the latest captured tail.
+ */
+export type AgentDiagnostic = {
+  /** display label for the agent, e.g. "Infraweaver". used in the headline. */
+  label: string;
+  /** shared reference to the harness's bounded stderr ring buffer. */
+  recentStderr: string[];
+  /** most-recent provider-error label from `detectProviderError`, if any. */
+  lastProviderError: string | undefined;
+  /** count of stdout events successfully parsed before the failure. */
+  eventCount: number;
+};
+
+/**
+ * Build a user-facing markdown body for an agent hang or failure.
+ *
+ * Rendered into both the PR progress comment and the GitHub Actions job
+ * summary. Returns `null` when no diagnostic is available, which signals to
+ * the caller to fall back to its bare-error rendering.
+ *
+ * `errorMessage` is the underlying timer / spawn reject string (e.g.
+ * `activity timeout: no output for 301s`). The idle seconds are parsed out
+ * of it for the hang explanation — total runtime would overstate the stall
+ * for runs that streamed for a long time before going quiet.
+ */
+export function formatAgentHangBody(input: {
+  diagnostic: AgentDiagnostic | undefined;
+  isHang: boolean;
+  errorMessage: string;
+}): string | null {
+  if (!input.diagnostic) return null;
+
+  // billing exhaustion (CreditsError / FreeUsageLimitError / spending cap /
+  // Insufficient balance) is mis-classified as transient by upstream harnesses
+  // and the run only ends when the activity-timeout watchdog fires (see #778).
+  // when we recognise the billing label, replace the generic "stalled — auth
+  // error" headline with a billing-specific CTA that names the actual remedy.
+  if (input.diagnostic.lastProviderError === "provider billing exhausted") {
+    return formatBillingExhaustedBody(input.diagnostic);
+  }
+
+  const verb = input.isHang ? "stalled" : "failed";
+  const cause = input.diagnostic.lastProviderError
+    ? ` — likely cause: \`${input.diagnostic.lastProviderError}\``
+    : "";
+  const headline = `**${input.diagnostic.label} ${verb}**${cause}`;
+
+  const explanation = formatExplanation({
+    isHang: input.isHang,
+    errorMessage: input.errorMessage,
+  });
+  const parts = [
+    headline,
+    "",
+    `${explanation} ${formatEventsPart(input.diagnostic)}`,
+  ];
+
+  const tail = renderStderrTail(input.diagnostic.recentStderr);
+  if (tail) {
+    // pick a fence longer than any backtick run in the body so a stderr line
+    // containing ``` (provider error JSON occasionally embeds it) can't
+    // terminate the fence early and corrupt the rest of the markdown.
+    const fence = pickFence(tail);
+    parts.push(
+      "",
+      "<details><summary>Recent agent stderr</summary>",
+      "",
+      fence,
+      tail,
+      fence,
+      "",
+      "</details>",
+    );
+  }
+
+  return parts.join("\n");
+}
+
+function formatExplanation(input: {
+  isHang: boolean;
+  errorMessage: string;
+}): string {
+  if (!input.isHang)
+    return `The agent exited unexpectedly: ${input.errorMessage}`;
+  const idleSec = parseIdleSec(input.errorMessage);
+  if (idleSec === undefined) {
+    return "The agent stopped emitting events and was killed by the activity-timeout watchdog.";
+  }
+  return `The agent stopped emitting events for ${idleSec}s and was killed by the activity-timeout watchdog.`;
+}
+
+function parseIdleSec(message: string): number | undefined {
+  const match = /no output for (\d+)s/.exec(message);
+  return match ? Number(match[1]) : undefined;
+}
+
+function formatEventsPart(diagnostic: AgentDiagnostic): string {
+  if (diagnostic.eventCount > 0) {
+    return `${diagnostic.eventCount} events were processed before the failure.`;
+  }
+  // when the provider-error label already names the cause in the headline,
+  // the reachability nudge below contradicts it (e.g. an immediate 401 also
+  // produces zero events but isn't a reachability problem). suppress it.
+  if (diagnostic.lastProviderError)
+    return "No events were emitted before the failure.";
+  return "No events were emitted — check whether the model provider is reachable.";
+}
+
+function renderStderrTail(lines: readonly string[]): string {
+  if (lines.length === 0) return "";
+  const joined = lines.join("\n");
+  if (joined.length <= MAX_STDERR_BYTES) return joined;
+  return `... (older lines truncated)\n${joined.slice(-MAX_STDERR_BYTES)}`;
+}
+
+function pickFence(content: string): string {
+  let max = 0;
+  for (const match of content.matchAll(/`+/g)) {
+    if (match[0].length > max) max = match[0].length;
+  }
+  return "`".repeat(Math.max(3, max + 1));
+}
+
+/**
+ * Pull a billing URL out of the captured stderr if the provider helpfully
+ * embedded one (OpenCode Zen does — Anthropic and Gemini do not). Restricted
+ * to known billing/console hosts so a stray URL elsewhere in the buffer
+ * can't masquerade as the remedy link.
+ */
+function extractBillingUrl(lines: readonly string[]): string | undefined {
+  const urlPattern =
+    /https:\/\/(?:opencode\.ai\/[^\s"]*billing[^\s"]*|console\.anthropic\.com[^\s"]*|console\.cloud\.google\.com[^\s"]*billing[^\s"]*)/i;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const m = urlPattern.exec(lines[i] ?? "");
+    if (m) return m[0];
+  }
+  return undefined;
+}
+
+function formatBillingExhaustedBody(diagnostic: AgentDiagnostic): string {
+  const headline = `**${diagnostic.label} stopped** — your model provider returned a billing-exhausted response.`;
+
+  const billingUrl = extractBillingUrl(diagnostic.recentStderr);
+  const cta = billingUrl
+    ? `Top up your provider balance, then re-run: [${billingUrl}](${billingUrl})`
+    : "Top up your model-provider balance (or rotate to a key with remaining credits) and re-run.";
+  const explanation = `The agent kept retrying the request because the provider marked the failure as transient. ${PRODUCT_NAME}'s activity-timeout watchdog ended the run after no further events were emitted.`;
+
+  const parts = [headline, "", explanation, "", cta];
+
+  const tail = renderStderrTail(diagnostic.recentStderr);
+  if (tail) {
+    const fence = pickFence(tail);
+    parts.push(
+      "",
+      "<details><summary>Recent agent stderr</summary>",
+      "",
+      fence,
+      tail,
+      fence,
+      "",
+      "</details>",
+    );
+  }
+
+  return parts.join("\n");
+}

package/src/utils/annotations.ts

@@ -0,0 +1,56 @@
+/**
+ * GitHub PR inline annotations (2d).
+ *
+ * Turns the active scan concerns into GitHub Actions annotation descriptors so
+ * they show up inline on the PR's "Files changed" view and in the check summary.
+ * A NEW high/critical finding (the gate set) is an `error` annotation; everything
+ * else active is a `warning`. The list is capped (GitHub only renders the first
+ * handful per level, and a flood of annotations is noise) — the SARIF upload +
+ * the dashboard carry the full set.
+ *
+ * Pure: returns descriptors; the caller emits them via `@actions/core`.
+ */
+import { PRODUCT_NAME } from "#app/brand";
+import type { Concern } from "#app/mcp/terraform/types";
+import { redactSecrets } from "#app/utils/redact";
+
+/** Max annotations emitted per run (GitHub throttles display well below this). */
+export const MAX_ANNOTATIONS = 50;
+
+export interface FindingAnnotation {
+  level: "error" | "warning";
+  message: string;
+  title: string;
+  file: string;
+  startLine: number;
+}
+
+/**
+ * Build annotation descriptors for the active concerns. `gatingIds` is the set of
+ * concern ids that fail the gate (new high/critical) — those become `error`s,
+ * sorted first so they survive the cap. Concerns with no file location are skipped
+ * (an annotation needs a file to anchor to).
+ */
+export function buildFindingAnnotations(
+  active: Concern[],
+  gatingIds: ReadonlySet<string>,
+  max: number = MAX_ANNOTATIONS,
+): FindingAnnotation[] {
+  const anchored = active.filter((c) => c.location.file && c.location.file !== "-");
+  // Gate-failing findings first so they're never dropped by the cap.
+  const ordered = [...anchored].sort((a, b) => {
+    const ga = gatingIds.has(a.id) ? 0 : 1;
+    const gb = gatingIds.has(b.id) ? 0 : 1;
+    return ga - gb;
+  });
+  return ordered.slice(0, max).map((c) => ({
+    level: gatingIds.has(c.id) ? "error" : "warning",
+    // LLM02: redact repo-derived evidence before it renders as a durable PR annotation.
+    message: redactSecrets(
+      c.remediation_hint ? `${c.evidence} — ${c.remediation_hint}` : c.evidence,
+    ),
+    title: `${PRODUCT_NAME}: ${c.rule_id}`,
+    file: c.location.file,
+    startLine: c.location.line ?? 1,
+  }));
+}