terramend 0.2.0

package/src/utils/runErrorRenderer.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import { renderRunError } from "#app/utils/runErrorRenderer";
+
+const repo = { owner: "acme", name: "widget" };
+
+describe("renderRunError BYOK provider billing exhausted (#835)", () => {
+  const deepseekRaw =
+    '» provider error detected (provider billing exhausted): ERROR providerID=deepseek modelID=deepseek-v4-pro error={"name":"AI_APICallError","message":"Insufficient Balance"}';
+
+  const anthropicRaw =
+    "APIError: Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits.";
+
+  const opencodeZenRaw = "CreditsError: account out of free usage";
+
+  it("renders DeepSeek billing-exhausted with provider-specific dashboard link", () => {
+    const result = renderRunError({
+      errorMessage: deepseekRaw,
+      repo,
+      agentDiagnostic: undefined,
+    });
+    expect(result.summary).toContain("`deepseek` account is out of credit");
+    expect(result.summary).toContain("https://platform.deepseek.com/top_up");
+    expect(result.summary).toContain("### ❌ Terramend failed");
+    expect(result.comment).toContain("`deepseek` account is out of credit");
+    expect(result.comment).not.toContain("### ❌ Terramend failed");
+  });
+
+  it("matches Anthropic 'credit balance is too low' (#835 Anthropic case)", () => {
+    const result = renderRunError({
+      errorMessage: anthropicRaw,
+      repo,
+      agentDiagnostic: undefined,
+    });
+    expect(result.comment).toContain("out of credit");
+  });
+
+  it("matches OpenCode Zen CreditsError shape", () => {
+    const result = renderRunError({
+      errorMessage: opencodeZenRaw,
+      repo,
+      agentDiagnostic: undefined,
+    });
+    expect(result.comment).toContain("out of credit");
+  });
+
+  it("falls through to a generic CTA when providerID cannot be parsed", () => {
+    const result = renderRunError({
+      errorMessage: "Insufficient balance — provider response with no providerID tag",
+      repo,
+      agentDiagnostic: undefined,
+    });
+    expect(result.comment).toContain("Your provider account is out of credit");
+    expect(result.comment).not.toContain("Your your");
+    expect(result.comment).toContain("Top up your provider account");
+  });
+});
+
+describe("renderRunError ProviderModelNotFoundError (#816)", () => {
+  const staleFreeRaw =
+    'ProviderModelNotFoundError: {"providerID":"opencode","modelID":"retired-free-model","suggestions":["deepseek-v4-flash-free"]}';
+
+  const bigPickleRaw =
+    'ProviderModelNotFoundError: {"providerID":"opencode","modelID":"big-pickle","suggestions":[]}';
+
+  it("renders actionable copy for a stale free fallback model id", () => {
+    const result = renderRunError({
+      errorMessage: staleFreeRaw,
+      repo,
+      agentDiagnostic: undefined,
+    });
+    expect(result.summary).toContain("Terramend's free fallback model is no longer available");
+    expect(result.summary).toContain("`acme/widget`");
+    expect(result.summary).toContain("retired-free-model");
+    expect(result.comment).toBe(result.summary);
+  });
+
+  it("renders the same classifier when big-pickle is missing from opencode catalog", () => {
+    const result = renderRunError({
+      errorMessage: bigPickleRaw,
+      repo,
+      agentDiagnostic: undefined,
+    });
+    expect(result.summary).toContain("Terramend's free fallback model is no longer available");
+    expect(result.summary).toContain("big-pickle");
+  });
+
+  it("does not misclassify unrelated failures as fallback-catalog errors", () => {
+    const result = renderRunError({
+      errorMessage: "activity timeout after 900s",
+      repo,
+      agentDiagnostic: undefined,
+    });
+    expect(result.summary).not.toContain("free fallback model is no longer available");
+  });
+});

package/src/utils/runErrorRenderer.ts

@@ -0,0 +1,259 @@
+/**
+ * Classify + render the error thrown out of the main run try-block into a
+ * pair of user-facing markdown bodies — one for the GitHub Actions job
+ * summary tab, one for the PR progress comment.
+ *
+ * Classifications, in dispatch order (first match wins; the api-key
+ * branch additionally folds in the activity-timeout hang body as a
+ * sub-source so a hang masking an api-key error still surfaces the api-key
+ * CTA):
+ *
+ *   1. `BillingError` — either the proxy-token mint already threw one (402
+ *      handled inline) or the agent runtime surfaced an OpenRouter
+ *      "key budget exhausted" string mid-run. Both render via
+ *      `formatBillingErrorSummary` so the user sees actionable copy.
+ *
+ *   2. BYOK provider billing-exhausted (#835) — DeepSeek "Insufficient
+ *      Balance", Anthropic "credit balance is too low", OpenCode Zen
+ *      `CreditsError`, Gemini "spending cap". Checked before api-key auth
+ *      because billing-exhausted responses often carry 401 status codes
+ *      that `isApiKeyAuthError` would otherwise mis-classify.
+ *
+ *   3. API-key auth error — `isApiKeyAuthError` sniffs the raw error string
+ *      (or the activity-timeout hang body when present, since that's where
+ *      the underlying provider error often lands); `formatApiKeyErrorSummary`
+ *      renders provider + console-link copy.
+ *
+ *   4. ProviderModelNotFoundError — stale free-fallback model id no longer
+ *      in the OpenCode catalog; renders a nudge to add a BYOK key.
+ *
+ *   5. Activity-timeout hang — `errorMessage` starts with
+ *      `"activity timeout"` or `"agent still pending"` AND none of the
+ *      above matched. The harness keeps structured diagnostic state on
+ *      `toolState.agentDiagnostic`; `formatAgentHangBody` renders that into
+ *      the job summary. The PR comment instead collapses to a one-line
+ *      `**Run failed.** [View the logs →]` — the watchdog jargon, event
+ *      counts, and benign stderr tail are operator-grade detail that only
+ *      alarm the average user. The one exception is a hang masking billing
+ *      exhaustion (#778), where `formatAgentHangBody` emits an actionable
+ *      top-up CTA that the comment keeps verbatim.
+ *
+ *   6. Default — the job summary gets a plain-English lead sentence plus the
+ *      raw error in a fenced code block under the `### ❌ Terramend failed`
+ *      banner; the PR comment collapses to the same one-line logs link as
+ *      the hang case, since the raw internal string helps nobody on the PR.
+ *
+ * Net: the actionable classifications (billing, API-key, model-not-found)
+ * render identical bodies on both surfaces; the non-actionable ones (hang,
+ * generic) keep the forensics in the Actions job summary and show a calm
+ * one-liner in the PR comment, whose footer already carries Terramend
+ * branding + rerun links.
+ */
+
+import type { AgentDiagnostic } from "#app/utils/agentHangReport";
+import { formatAgentHangBody } from "#app/utils/agentHangReport";
+import { formatApiKeyErrorSummary, isApiKeyAuthError } from "#app/utils/apiKeys";
+import { BillingError, formatBillingErrorSummary } from "#app/utils/billingErrors";
+import {
+  extractProviderId,
+  isProviderBillingExhausted,
+  isRouterKeylimitExhaustedError,
+} from "#app/utils/providerErrors";
+
+export type RenderedRunError = {
+  summary: string;
+  comment: string;
+};
+
+function isProviderModelNotFoundError(message: string): boolean {
+  return message.includes("ProviderModelNotFoundError");
+}
+
+/**
+ * Generic failure copy for any shape not caught by a more specific classifier
+ * (billing / api-key / hang / model-not-found). A plain-English lead sentence
+ * so the user isn't staring at a raw internal string like
+ * `opencode prompt failed: fetch failed`, followed by the actual error in a
+ * fenced code block for anyone who needs the detail. Shared by both surfaces;
+ * the job summary adds the `### ❌ Terramend failed` banner on top.
+ */
+function formatGenericFailure(errorMessage: string): string {
+  return [
+    "Terramend ran into an unexpected error and couldn't finish this run. The underlying error is below — re-trigger Terramend to try again, and reach out to support if it keeps happening.",
+    "",
+    "```",
+    errorMessage,
+    "```",
+  ].join("\n");
+}
+
+/**
+ * Minimal PR-comment body for non-actionable failures (hangs, unexpected
+ * errors). The forensic detail (event counts, stderr tail, raw error) stays
+ * in the Actions job summary; the comment the average user sees is one calm
+ * line plus a link to the logs. The footer appended by `reportErrorToComment`
+ * already carries rerun / model context.
+ */
+function formatMinimalFailureComment(repo: { owner: string; name: string }): string {
+  const runId = process.env.GITHUB_RUN_ID;
+  if (!runId) return "**Run failed.**";
+  const server = process.env.GITHUB_SERVER_URL ?? "https://github.com";
+  const url = `${server}/${repo.owner}/${repo.name}/actions/runs/${runId}`;
+  return `**Run failed.** [View the logs →](${url})`;
+}
+
+/**
+ * Best-known billing top-up URL per provider. Conservative list: only
+ * providers we've actually classified billing-exhaustion shapes for in
+ * `providerErrors.ts`. Unknown providers fall through to a generic CTA.
+ */
+const PROVIDER_BILLING_URLS: Record<string, string> = {
+  deepseek: "https://platform.deepseek.com/top_up",
+  anthropic: "https://console.anthropic.com/settings/billing",
+  openai: "https://platform.openai.com/account/billing",
+  google: "https://aistudio.google.com/usage",
+  opencode: "https://opencode.ai/zen",
+};
+
+/**
+ * `extractProviderId` only fires when the harness emits `providerID=...`
+ * (OpenCode log shape). Direct-provider errors (e.g. Anthropic SDK throwing
+ * `"Your credit balance is too low to access the Anthropic API"`) carry no
+ * such tag, so map their distinctive copy to a provider id here so the
+ * dashboard link is reachable.
+ *
+ * Pattern is intentionally tight (Anthropic-specific phrasing only) to
+ * avoid mis-tagging non-Anthropic billing-exhausted errors that happen to
+ * mention `"Anthropic API"` in passing — the broader phrase appears in
+ * fallback-chain agent prompt text and OpenCode harness logs.
+ */
+function detectProviderId(message: string): string | null {
+  const harnessId = extractProviderId(message);
+  if (harnessId) return harnessId;
+  if (/credit balance is too low/i.test(message)) return "anthropic";
+  return null;
+}
+
+function formatProviderBillingExhausted(input: { errorMessage: string }): string {
+  const providerId = detectProviderId(input.errorMessage);
+  const dashboardUrl = providerId ? PROVIDER_BILLING_URLS[providerId] : undefined;
+
+  const headline = providerId
+    ? `**Your \`${providerId}\` account is out of credit.**`
+    : "**Your provider account is out of credit.**";
+  const cta = dashboardUrl
+    ? `[Top up \`${providerId}\` →](${dashboardUrl})`
+    : "Top up your provider account, then re-trigger Terramend.";
+
+  return [
+    headline,
+    "",
+    "Terramend detected a billing-exhausted response from your provider — the agent stopped before completing this run.",
+    "",
+    cta,
+    "",
+    `\`\`\`\n${input.errorMessage}\n\`\`\``,
+  ].join("\n");
+}
+
+function formatProviderModelNotFoundSummary(input: {
+  owner: string;
+  name: string;
+  raw: string;
+}): string {
+  return (
+    `Terramend's free fallback model is no longer available in OpenCode's catalog. ` +
+    `Add an API key for your configured model in the Terramend console for \`${input.owner}/${input.name}\`, ` +
+    `or contact support if this persists.\n\n` +
+    `\`\`\`\n${input.raw}\n\`\`\``
+  );
+}
+
+export function renderRunError(input: {
+  errorMessage: string;
+  repo: { owner: string; name: string };
+  agentDiagnostic: AgentDiagnostic | undefined;
+}): RenderedRunError {
+  // reclassify mid-run OpenRouter "key budget exhausted" as BillingError so
+  // the user gets the same actionable copy as a /api/proxy-token 402.
+  const billingError = isRouterKeylimitExhaustedError(input.errorMessage)
+    ? new BillingError(input.errorMessage, { code: "router_keylimit_exhausted" })
+    : null;
+
+  if (billingError) {
+    const body = formatBillingErrorSummary(billingError, input.repo.owner);
+    return { summary: body, comment: body };
+  }
+
+  // gated on isHang because the harness sets `agentDiagnostic` on entry, so
+  // any non-hang throw that hits the outer catch (e.g. post-success
+  // output_schema validator, or a late cleanup throw after the run already
+  // succeeded) would otherwise render "Terramend failed" with stale event
+  // counts and silently drop the real errorMessage.
+  const isHang =
+    input.errorMessage.startsWith("activity timeout") ||
+    input.errorMessage.startsWith("agent still pending");
+  const hangBody = isHang
+    ? formatAgentHangBody({
+        diagnostic: input.agentDiagnostic,
+        isHang: true,
+        errorMessage: input.errorMessage,
+      })
+    : null;
+
+  // BYOK provider billing-exhausted (DeepSeek "Insufficient Balance",
+  // Anthropic "credit balance is too low", OpenCode Zen `CreditsError` /
+  // `FreeUsageLimitError`, Gemini "spending cap"). distinct from the Router
+  // billing branches above — Router uses `BillingError`, this uses the agent
+  // log payload classified by `isProviderBillingExhausted`. see #835.
+  //
+  // checked BEFORE api-key auth: providers commonly return 401 (DeepSeek,
+  // Gemini) or include `"API Error: 401"` in the error body for billing
+  // exhaustion, which `isApiKeyAuthError` would otherwise match — surfacing
+  // a "rotate your key" CTA when the actual fix is "top up credits".
+  if (isProviderBillingExhausted(input.errorMessage)) {
+    const body = formatProviderBillingExhausted({ errorMessage: input.errorMessage });
+    return { summary: `### ❌ Terramend failed\n\n${body}`, comment: body };
+  }
+
+  const apiKeySource = hangBody ?? input.errorMessage;
+  const apiKeyErrorSummary = isApiKeyAuthError(apiKeySource)
+    ? formatApiKeyErrorSummary({
+        owner: input.repo.owner,
+        name: input.repo.name,
+        raw: apiKeySource,
+      })
+    : null;
+
+  if (apiKeyErrorSummary) {
+    return { summary: apiKeyErrorSummary, comment: apiKeyErrorSummary };
+  }
+
+  if (isProviderModelNotFoundError(input.errorMessage)) {
+    const body = formatProviderModelNotFoundSummary({
+      owner: input.repo.owner,
+      name: input.repo.name,
+      raw: input.errorMessage,
+    });
+    return { summary: body, comment: body };
+  }
+
+  if (hangBody) {
+    // a hang masking billing exhaustion (#778) renders an actionable top-up
+    // CTA inside `hangBody` — keep that in the comment. every other hang is
+    // non-actionable noise for the average user, so the comment collapses to
+    // a one-liner and the diagnostic stays in the Actions job summary.
+    const isBillingExhausted =
+      input.agentDiagnostic?.lastProviderError === "provider billing exhausted";
+    return {
+      summary: `### ❌ Terramend failed\n\n${hangBody}`,
+      comment: isBillingExhausted ? hangBody : formatMinimalFailureComment(input.repo),
+    };
+  }
+
+  const genericBody = formatGenericFailure(input.errorMessage);
+  return {
+    summary: `### ❌ Terramend failed\n\n${genericBody}`,
+    comment: formatMinimalFailureComment(input.repo),
+  };
+}

package/src/utils/runFixture.ts

@@ -0,0 +1,76 @@
+// in-process fixture runner used by `dev-run.ts` (and any future host-side
+// runner). does NOT know about Docker — that's `docker.ts`'s job. when run
+// inside the local docker container, this is what executes after the entrypoint.
+import { execSync } from "node:child_process";
+import { mkdtemp } from "node:fs/promises";
+import { devNull, tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentResult } from "#app/agents/shared";
+import { type Inputs, main } from "#app/main";
+import { log } from "#app/utils/cli";
+import { ensureGitHubToken } from "#app/utils/github";
+import { setupTestRepo } from "#app/utils/setup";
+
+export async function run(inputsOrPrompt: Inputs | string): Promise<AgentResult> {
+  await ensureGitHubToken();
+
+  // dev-run.ts is a CI-emulator — isolate it from the developer's user- and
+  // system-scope gitconfig so checks like `validatePushDestination` see the
+  // raw stored remote URL instead of values mutated by `url.*.insteadOf`
+  // rewrites (a common SSH-auth convenience on dev boxes). CI runners have
+  // empty gitconfigs so this is a no-op there; locally it makes `pnpm dev:run`
+  // and real runs produce identical git state. `os.devNull` canonicalizes
+  // the null device across Unix (`/dev/null`) and Windows (`\\.\nul`).
+  process.env.GIT_CONFIG_GLOBAL = devNull;
+  process.env.GIT_CONFIG_SYSTEM = devNull;
+
+  const tempParent = await mkdtemp(join(tmpdir(), "terramend-dev-run-"));
+  const tempDir = join(tempParent, "repo");
+  const originalCwd = process.cwd();
+
+  try {
+    setupTestRepo({ tempDir });
+    process.chdir(tempDir);
+
+    // optional pre-agent setup (e.g. seed symlinks for adversarial fixtures).
+    if (process.env.TERRAMEND_TEST_REPO_SETUP) {
+      log.info("» running repo setup commands...");
+      execSync(process.env.TERRAMEND_TEST_REPO_SETUP, { cwd: tempDir, stdio: "pipe" });
+    }
+
+    // tell main() to use the cloned tempDir instead of the GHA workspace path.
+    process.env.GITHUB_WORKSPACE = tempDir;
+
+    const inputs: Inputs =
+      typeof inputsOrPrompt === "string" ? { prompt: inputsOrPrompt } : inputsOrPrompt;
+
+    for (const [key, value] of Object.entries(inputs)) {
+      if (value !== undefined && value !== null) {
+        process.env[`INPUT_${key.toUpperCase()}`] = String(value);
+      }
+    }
+
+    const result: AgentResult = await main();
+    process.chdir(originalCwd);
+
+    if (result.success) {
+      log.success("Action completed successfully");
+      return { success: true, output: result.output || undefined, error: undefined };
+    }
+    log.error(`Action failed: ${result.error || "Unknown error"}`);
+    return { success: false, error: result.error || undefined, output: undefined };
+  } catch (err) {
+    const errorMessage = (err as Error).message;
+    log.error(`Error: ${errorMessage}`);
+    return { success: false, error: errorMessage, output: undefined };
+  } finally {
+    process.chdir(originalCwd);
+    // sandbox isolation may create files with non-host ownership; rmSync
+    // can't always delete those, so escalate.
+    try {
+      execSync(`sudo rm -rf "${tempParent}"`, { stdio: "ignore" });
+    } catch {
+      // best-effort cleanup.
+    }
+  }
+}

package/src/utils/runLifecycle.ts

@@ -0,0 +1,237 @@
+/**
+ * End-of-run cleanup phases extracted out of `main.ts`. Three shapes:
+ *
+ *   - `persistRunArtifacts`: best-effort post-review cleanup + summary +
+ *     learnings persistence. Shared by both the success path and the
+ *     error-catch path; idempotent (each step has its own guard against
+ *     double-execution).
+ *
+ *   - `finalizeSuccessRun`: success-only — calls `persistRunArtifacts`
+ *     first, then surfaces harness-side failures in the progress comment,
+ *     deletes stranded progress comments, writes the GitHub Actions job
+ *     summary, and emits the structured output marker.
+ *
+ *   - `writeRunErrorOutputs`: error-only — writes the rendered error
+ *     summary to the Actions summary tab and mirrors it to the PR
+ *     progress comment. The catch path calls this and then
+ *     `persistRunArtifacts` separately so the rendered error lands before
+ *     the persistence calls, in case the latter throw.
+ *
+ * All three swallow their own non-fatal errors (`log.debug` or empty
+ * `catch {}`) so a cleanup failure can't flip an already-decided run
+ * outcome.
+ */
+
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as core from "@actions/core";
+import type { AgentResult } from "#app/agents/shared";
+import { deleteProgressComment } from "#app/mcp/comment";
+import type { ToolContext } from "#app/mcp/server";
+import { buildSarifReport } from "#app/mcp/terraform/findings";
+import type { ToolState } from "#app/toolState";
+import { formatUsageSummary, log, writeSummary } from "#app/utils/cli";
+import { reportErrorToComment } from "#app/utils/errorReport";
+import { persistLearnings } from "#app/utils/learnings";
+import { persistSummary } from "#app/utils/prSummary";
+import { postReviewCleanup } from "#app/utils/reviewCleanup";
+import { type RenderedRunError, renderRunError } from "#app/utils/runErrorRenderer";
+
+/**
+ * Best-effort cleanup shared by both run-end paths:
+ *   1. post-review cleanup (dispatch follow-up re-review on submitted reviews)
+ *   2. persist the agent-edited PR summary tmpfile
+ *   3. persist the agent-edited repo-level learnings tmpfile
+ *
+ * Each step is idempotent and swallows its own errors. Safe to call from
+ * both `main()`'s success path and its catch path.
+ */
+export async function persistRunArtifacts(toolContext: ToolContext): Promise<void> {
+  await postReviewCleanup(toolContext).catch((error) => {
+    log.debug(`post-review cleanup failed: ${error}`);
+  });
+  await persistSummary(toolContext);
+  await persistLearnings(toolContext);
+}
+
+/**
+ * Run the success-path cleanup waterfall:
+ *
+ *   1. shared best-effort cleanup via `persistRunArtifacts`
+ *   2. when the harness returned `success=false` (e.g. unsubmitted-review
+ *      gate exhausted retries, stop-hook persistently failing), render via
+ *      `renderRunError` and surface the error in BOTH the progress comment
+ *      (rendered.comment) and the Actions job summary (rendered.summary,
+ *      prepended below in step 4) — same classifier as the catch path so
+ *      the user sees it instead of a deleted-comment void / empty summary
+ *      tab
+ *   3. when the run succeeded, some write landed (`wasUpdated`), but the
+ *      progress comment was never finalized via `report_progress`, delete
+ *      the stranded comment (abandoned checklist, or a substantive artifact
+ *      written via another MCP write tool that skipped report_progress). a
+ *      run where NO write landed keeps its comment for handleAgentResult to
+ *      salvage into — see the `wasUpdated` guard below and #868
+ *   4. write the GitHub Actions step summary (best-effort — a write
+ *      failure must not throw past this point because we'd hit the outer
+ *      catch and clobber any progress comment we just wrote)
+ *   5. emit the structured output marker for tests + workflow consumers
+ */
+export async function finalizeSuccessRun(input: {
+  toolContext: ToolContext;
+  toolState: ToolState;
+  result: AgentResult;
+  repo: { owner: string; name: string };
+}): Promise<void> {
+  await persistRunArtifacts(input.toolContext);
+
+  // shared rendering for the !success branch — same classifier as the
+  // outer catch path (BillingError reclassify → hang → BYOK billing →
+  // api-key → generic), so a harness-returned `{success: false}` lands an
+  // actionable error block in the job summary alongside the matching body
+  // in the progress comment. hang and generic get the `### ❌ Terramend
+  // failed` H3 banner; BillingError, BYOK billing, and api-key render
+  // their own provider-specific framing (no banner). renders once; reused
+  // for both surfaces below.
+  const rendered = !input.result.success
+    ? renderRunError({
+        errorMessage: input.result.error || "agent run failed",
+        repo: input.repo,
+        agentDiagnostic: input.toolState.agentDiagnostic,
+      })
+    : null;
+
+  // `createIfMissing: true` is load-bearing for silent triggers
+  // (IncrementalReview / pull_request_synchronize / auto-label) that have
+  // no progress comment to update — without it, terminal failures like
+  // BYOK billing exhaustion land only in the GH job summary, which most
+  // users never open. `reportErrorToComment` no-ops when both progress
+  // comment AND issue context are absent. see #835.
+  if (rendered) {
+    await reportErrorToComment({
+      toolState: input.toolState,
+      error: rendered.comment,
+      createIfMissing: true,
+    }).catch((error) => {
+      log.debug(`failure error report failed: ${error}`);
+    });
+  }
+
+  // create_pull_request_review owns its own deletion (see mcp/review.ts), so
+  // progressComment is already null by the time we get here for that path.
+  // uses finalSummaryWritten (not todoTracker.enabled or wasUpdated) so
+  // cleanup survives API failures in report_progress where cancel() ran but
+  // the write didn't succeed, and isn't fooled by writes to *other* artifacts.
+  //
+  // the extra `wasUpdated` guard preserves the comment when NO write landed at
+  // all: that's the case handleAgentResult salvages (raw-text answer / failed
+  // report_progress) by writing the agent's result into this very comment, or
+  // — when there's nothing to salvage — reports the failure into it. deleting
+  // here would strand the user with a vanished "Leaping into action" comment
+  // and a no-op error report (see #868).
+  if (
+    input.result.success &&
+    input.toolState.progressComment &&
+    input.toolState.wasUpdated &&
+    !input.toolState.finalSummaryWritten
+  ) {
+    await deleteProgressComment(input.toolContext).catch((error) => {
+      log.debug(`stranded progress comment cleanup failed: ${error}`);
+    });
+  }
+
+  try {
+    const usageSummary = formatUsageSummary(input.toolState.usageEntries);
+    const body = input.toolState.lastProgressBody || input.result.output;
+    const parts = [rendered?.summary, body, usageSummary].filter(Boolean);
+    if (parts.length > 0) {
+      await writeSummary(parts.join("\n\n"));
+    }
+  } catch (error) {
+    log.debug(`job summary write failed: ${error}`);
+  }
+
+  if (input.toolState.output) {
+    log.info(`::terramend-output::${Buffer.from(input.toolState.output).toString("base64")}`);
+    core.setOutput("result", input.toolState.output);
+  }
+
+  await emitFindingsOutputs(input.toolState);
+}
+
+/**
+ * §5.4 — when a deterministic scan ran this run (`terraform_scan` populated
+ * `lastScanConcerns`), expose its reported concern set to downstream workflow
+ * steps: the `findings-count` / `findings-sarif-path` action outputs, plus a
+ * safety-net SARIF write so modes that don't prompt the agent to call
+ * `terraform_emit_sarif` (Review) — or a Remediate run where the agent skipped
+ * that optional step — still surface a Code-Scanning artifact.
+ *
+ * When the agent already emitted a SARIF via `terraform_emit_sarif`
+ * (`toolState.emittedSarifPath` set), this defers to that file — points the
+ * output at it, does not rewrite — so an agent report at a lower threshold or
+ * custom path is never clobbered. Otherwise it writes the safety-net file using
+ * the canonical `buildSarifReport` (the same builder the tool uses), so there is
+ * only ever one SARIF format.
+ *
+ * Unset outputs when no scan ran; `0` + a results-free SARIF when the scan was
+ * clean — so a workflow gate can distinguish "clean scan" from "not scanned".
+ * Best-effort like every other finalize step: an emit failure must not flip the
+ * run outcome.
+ */
+async function emitFindingsOutputs(toolState: ToolState): Promise<void> {
+  const concerns = toolState.lastScanConcerns;
+  if (!concerns) return;
+  try {
+    core.setOutput("findings-count", String(concerns.length));
+    if (toolState.emittedSarifPath) {
+      core.setOutput("findings-sarif-path", toolState.emittedSarifPath);
+      log.info(
+        `» findings output: ${concerns.length} concern(s), SARIF at ${toolState.emittedSarifPath} (agent-emitted)`,
+      );
+      return;
+    }
+    const sarifPath = join(process.env.GITHUB_WORKSPACE ?? process.cwd(), "terramend.sarif");
+    await writeFile(sarifPath, `${JSON.stringify(buildSarifReport(concerns), null, 2)}\n`);
+    core.setOutput("findings-sarif-path", sarifPath);
+    log.info(`» findings output: ${concerns.length} concern(s), SARIF at ${sarifPath}`);
+  } catch (error) {
+    log.debug(`findings output emit failed: ${error}`);
+  }
+}
+
+/**
+ * Write the rendered error to the GitHub Actions job summary tab + mirror
+ * to the PR progress comment when one exists. Catch path only.
+ *
+ * `lastProgressBody` and the usage table are appended to the summary so the
+ * partial work the agent did before failing isn't lost.
+ *
+ * `createIfMissing: true` is symmetric with `finalizeSuccessRun` — silent
+ * triggers (IncrementalReview / pull_request_synchronize / auto-label) that
+ * throw past `finalizeSuccessRun` (e.g. timeout race kills the agent
+ * mid-billing-exhausted-retry) reach this catch path with no progress
+ * comment to update, and without `createIfMissing` the terminal error
+ * lands only in the GH job summary that most users never open. see #835.
+ */
+export async function writeRunErrorOutputs(input: {
+  rendered: RenderedRunError;
+  toolState: ToolState;
+}): Promise<void> {
+  try {
+    const usageSummary = formatUsageSummary(input.toolState.usageEntries);
+    const parts = [input.rendered.summary, input.toolState.lastProgressBody, usageSummary].filter(
+      Boolean,
+    );
+    await writeSummary(parts.join("\n\n"));
+  } catch {}
+
+  try {
+    await reportErrorToComment({
+      toolState: input.toolState,
+      error: input.rendered.comment,
+      createIfMissing: true,
+    });
+  } catch {
+    // error reporting failed, but don't let it mask the original error
+  }
+}