terramend 0.2.0

package/src/utils/payload.ts

@@ -0,0 +1,371 @@
+import { isAbsolute, resolve } from "node:path";
+import * as core from "@actions/core";
+import { type } from "arktype";
+import type { AuthorPermission, PayloadEvent } from "#app/external";
+import { BUILTIN_MODE_NAMES } from "#app/modes";
+import { log } from "#app/utils/cli";
+import { parseRemediationCommand } from "#app/utils/remediationCommand";
+import type { RepoSettings } from "#app/utils/runContext";
+import { validateCompatibility } from "#app/utils/versioning";
+import packageJson from "#package.json" with { type: "json" };
+
+// tool permission enum types for inputs
+const ShellPermissionInput = type.enumerated("disabled", "restricted", "enabled");
+const PushPermissionInput = type.enumerated("disabled", "restricted", "enabled");
+
+// schema for JSON payload passed via prompt (internal dispatch invocation)
+// note: permissions are intentionally NOT included here to prevent injection attacks
+// permissions are derived from event.authorPermission instead
+export const JsonPayload = type({
+  "~terramend": "true",
+  version: "string",
+  "model?": "string | undefined",
+  prompt: "string",
+  "triggerer?": "string | undefined",
+
+  "eventInstructions?": "string",
+  "previousRunsNote?": "string",
+  "event?": "object",
+  "timeout?": "string | undefined",
+  "progressComment?": type({
+    id: "string",
+    type: "'issue' | 'review'",
+  }).or("undefined"),
+  "generateSummary?": "boolean | undefined",
+});
+
+// permission levels that indicate collaborator status (have push access)
+const COLLABORATOR_PERMISSIONS: AuthorPermission[] = ["admin", "maintain", "write"];
+
+// check if the event author has collaborator-level permissions
+function isCollaborator(event: PayloadEvent): boolean {
+  const perm = event.authorPermission;
+  return perm !== undefined && COLLABORATOR_PERMISSIONS.includes(perm);
+}
+
+// inputs schema - action inputs from core.getInput()
+// note: tool permissions use .or("undefined") because getInput() || undefined
+// explicitly sets the property to undefined when empty, which is different from
+// the property being absent. arktype's "prop?" means "optional to include" but
+// if included, must match the type - so we need to explicitly allow undefined.
+export const Inputs = type({
+  prompt: "string",
+  "model?": type.string.or("undefined"),
+  "mode?": type.string.or("undefined"),
+  "timeout?": type.string.or("undefined"),
+  "push?": PushPermissionInput.or("undefined"),
+  "shell?": ShellPermissionInput.or("undefined"),
+  "cwd?": type.string.or("undefined"),
+  "output_schema?": type.string.or("undefined"),
+  // Terraform remediation config (all optional; defaults applied downstream)
+  "scan_scope?": type.string.or("undefined"),
+  "severity_threshold?": type.string.or("undefined"),
+  "max_prs?": type.string.or("undefined"),
+  "allowed_paths?": type.string.or("undefined"),
+  "base_branch?": type.string.or("undefined"),
+  "allow_replace?": type.string.or("undefined"),
+  "protected_paths?": type.string.or("undefined"),
+  "autonomy_threshold?": type.string.or("undefined"),
+  "gitleaks?": type.string.or("undefined"),
+  "cost_increase_block_usd?": type.string.or("undefined"),
+  "module_catalogue?": type.string.or("undefined"),
+  "terratest?": type.string.or("undefined"),
+  "terraform_mcp?": type.string.or("undefined"),
+  "review_instructions?": type.string.or("undefined"),
+  "fp_filtering_instructions?": type.string.or("undefined"),
+});
+
+export type Inputs = typeof Inputs.infer;
+
+function isPayloadEvent(value: unknown): value is PayloadEvent {
+  return typeof value === "object" && value !== null && "trigger" in value;
+}
+
+function resolveCwd(cwd: string | undefined): string | undefined {
+  const workspace = process.env.GITHUB_WORKSPACE;
+  if (!cwd) return workspace;
+  if (isAbsolute(cwd)) return cwd;
+  return workspace ? resolve(workspace, cwd) : cwd;
+}
+
+export type ResolvedPromptInput = string | typeof JsonPayload.infer;
+
+export function resolvePromptInput(): ResolvedPromptInput {
+  const prompt = core.getInput("prompt", { required: true });
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(prompt);
+  } catch {
+    // JSON parse error is fine (plain text prompt)
+    return prompt;
+  }
+
+  if (!parsed || typeof parsed !== "object" || !("~terramend" in parsed)) {
+    // if it doesn't look like a terramend payload, return the plain text prompt
+    return prompt;
+  }
+
+  // validation errors should propagate
+  const jsonPayload = JsonPayload.assert(parsed);
+  validateCompatibility(jsonPayload.version, packageJson.version);
+  return jsonPayload;
+}
+
+function resolveNonPromptInputs() {
+  return Inputs.omit("prompt").assert({
+    model: core.getInput("model") || undefined,
+    mode: core.getInput("mode") || undefined,
+    timeout: core.getInput("timeout") || undefined,
+    cwd: core.getInput("cwd") || undefined,
+    push: core.getInput("push") || undefined,
+    shell: core.getInput("shell") || undefined,
+    scan_scope: core.getInput("scan_scope") || undefined,
+    severity_threshold: core.getInput("severity_threshold") || undefined,
+    max_prs: core.getInput("max_prs") || undefined,
+    allowed_paths: core.getInput("allowed_paths") || undefined,
+    base_branch: core.getInput("base_branch") || undefined,
+    allow_replace: core.getInput("allow_replace") || undefined,
+    protected_paths: core.getInput("protected_paths") || undefined,
+    autonomy_threshold: core.getInput("autonomy_threshold") || undefined,
+    gitleaks: core.getInput("gitleaks") || undefined,
+    cost_increase_block_usd: core.getInput("cost_increase_block_usd") || undefined,
+    module_catalogue: core.getInput("module_catalogue") || undefined,
+    terratest: core.getInput("terratest") || undefined,
+    terraform_mcp: core.getInput("terraform_mcp") || undefined,
+    review_instructions: core.getInput("review_instructions") || undefined,
+    fp_filtering_instructions: core.getInput("fp_filtering_instructions") || undefined,
+  });
+}
+
+/**
+ * Canonicalize the `mode` input against the built-in mode names
+ * (case-insensitive). Returns the canonical name (e.g. "remediate" →
+ * "Remediate") when it matches a built-in mode, letting CI pin a mode
+ * deterministically. Unknown non-empty values warn and return undefined so the
+ * agent falls back to prompt-driven `select_mode` — mirroring how an unknown
+ * `model` slug degrades to auto-select rather than hard-failing the run.
+ */
+export function parseMode(raw: string | undefined): string | undefined {
+  const v = raw?.trim();
+  if (!v) return undefined;
+  const match = BUILTIN_MODE_NAMES.find((name) => name.toLowerCase() === v.toLowerCase());
+  if (!match) {
+    log.warning(
+      `» unknown mode "${v}" — agent will select a mode (valid: ${BUILTIN_MODE_NAMES.join(", ")})`,
+    );
+    return undefined;
+  }
+  return match;
+}
+
+/** parse scan_scope; "diff" or "full" (default). */
+function parseScanScope(raw: string | undefined): "diff" | "full" | undefined {
+  const v = raw?.trim().toLowerCase();
+  return v === "diff" || v === "full" ? v : undefined;
+}
+
+const SEVERITY_VALUES = new Set(["critical", "high", "medium", "low", "info"]);
+
+/** parse the severity_threshold input; undefined when unset or not a valid level. */
+function parseSeverityThreshold(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  const v = raw.trim().toLowerCase();
+  return SEVERITY_VALUES.has(v) ? v : undefined;
+}
+
+/** parse max_prs; a positive integer, else undefined (downstream default is 1). */
+function parseMaxPrs(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = Number.parseInt(raw.trim(), 10);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+
+/** parse cost_increase_block_usd; a positive number of dollars/month, else
+ * undefined (no cost escalation). */
+function parseCostIncreaseBlock(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = Number.parseFloat(raw.trim());
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/** parse a comma-separated glob list (allowed_paths / protected_paths);
+ * undefined when unset or empty after trimming. */
+function parseGlobList(raw: string | undefined): string[] | undefined {
+  if (!raw) return undefined;
+  const globs = raw
+    .split(",")
+    .map((g) => g.trim())
+    .filter(Boolean);
+  return globs.length > 0 ? globs : undefined;
+}
+
+/** parse a boolean-ish action input ("true"/"1"/"yes" → true). undefined/unset
+ * and any other value → false. */
+function parseBooleanInput(raw: string | undefined): boolean {
+  if (!raw) return false;
+  return ["true", "1", "yes", "on"].includes(raw.trim().toLowerCase());
+}
+
+/** parse the base_branch override; trims and strips a leading `refs/heads/`,
+ * undefined when unset (downstream resolves the run-start branch / default). */
+export function parseBaseBranch(raw: string | undefined): string | undefined {
+  const v = raw?.trim().replace(/^refs\/heads\//, "");
+  return v || undefined;
+}
+
+/** parse the comma-separated allow_replace list — resource addresses (or globs,
+ * or `*`/`all`) permitted to be destroyed/replaced; undefined when unset. */
+export function parseAllowReplace(raw: string | undefined): string[] | undefined {
+  if (!raw) return undefined;
+  const entries = raw
+    .split(",")
+    .map((a) => a.trim())
+    .filter(Boolean);
+  return entries.length > 0 ? entries : undefined;
+}
+
+const isTerramend = (actor: string | null | undefined): boolean => {
+  actor = actor?.replace("[bot]", "");
+  return !!actor && (actor === "terramend" || actor === "terramenddev");
+};
+
+export function resolvePayload(
+  resolvedPromptInput: ResolvedPromptInput,
+  repoSettings: RepoSettings,
+) {
+  const [prompt, jsonPayload] =
+    typeof resolvedPromptInput !== "string"
+      ? [resolvedPromptInput.prompt, resolvedPromptInput]
+      : [resolvedPromptInput, undefined];
+
+  const inputs = resolveNonPromptInputs();
+
+  // resolve event - use type guard for jsonPayload.event, fallback to unknown trigger
+  const rawEvent = jsonPayload?.event;
+  const event: PayloadEvent = isPayloadEvent(rawEvent) ? rawEvent : { trigger: "unknown" };
+
+  const model = jsonPayload?.model ?? inputs.model ?? repoSettings.model ?? undefined;
+
+  // determine shell permission - strictest setting wins
+  // precedence: disabled > restricted > enabled
+  // non-collaborators always get at least "restricted"
+  const isNonCollaborator = !isCollaborator(event);
+  const repoShell = repoSettings.shell ?? "restricted";
+  const inputShell = inputs.shell;
+
+  // resolve shell: start with repo setting, then apply restrictions
+  let resolvedShell = repoShell;
+
+  // input can only make it stricter (disabled > restricted > enabled)
+  if (inputShell === "disabled") {
+    resolvedShell = "disabled";
+  } else if (inputShell === "restricted" && resolvedShell === "enabled") {
+    resolvedShell = "restricted";
+  }
+
+  // non-collaborators get at least "restricted" (can't have "enabled")
+  if (isNonCollaborator && resolvedShell === "enabled") {
+    resolvedShell = "restricted";
+  }
+
+  // build payload - precedence: inputs > repoSettings > fallbacks
+  // note: modes are NOT in payload - they come from repoSettings in main()
+  return {
+    "~terramend": true as const,
+    version: jsonPayload?.version ?? packageJson.version,
+    model,
+    // deterministic mode pin for CI (action input only — not accepted from the
+    // JSON payload, which is the internal dispatch surface). undefined → the
+    // agent chooses via select_mode as before.
+    mode: parseMode(inputs.mode),
+    prompt,
+    triggerer:
+      jsonPayload?.triggerer ??
+      // it's not a common use case but GITHUB_ACTOR can be a user when the workflow is manually triggered by a user through GitHub Actions UI
+      (!isTerramend(process.env.GITHUB_ACTOR) ? process.env.GITHUB_ACTOR : undefined),
+    eventInstructions: jsonPayload?.eventInstructions,
+    previousRunsNote: jsonPayload?.previousRunsNote,
+    event,
+    timeout: inputs.timeout ?? jsonPayload?.timeout,
+    cwd: resolveCwd(inputs.cwd),
+    progressComment: jsonPayload?.progressComment,
+    generateSummary: jsonPayload?.generateSummary,
+
+    // permissions: inputs > repoSettings > fallbacks
+    push: inputs.push ?? repoSettings.push ?? "restricted",
+    shell: resolvedShell,
+
+    // Terraform remediation config — consumed by mcp/terraform.ts + the
+    // Remediate mode. Defaults are applied at the consumer, not here, so
+    // "unset" stays distinguishable from an explicit value.
+    scanScope: parseScanScope(inputs.scan_scope),
+    severityThreshold: parseSeverityThreshold(inputs.severity_threshold),
+    maxPrs: parseMaxPrs(inputs.max_prs),
+    allowedPaths: parseGlobList(inputs.allowed_paths),
+    // §2.7 — globs the fixer must never auto-modify (inverse of allowed_paths).
+    protectedPaths: parseGlobList(inputs.protected_paths),
+    // §3.9 — minimum severity at which a security concern escalates to a human.
+    autonomyThreshold: parseSeverityThreshold(inputs.autonomy_threshold),
+    // §2.8 — opt in to the external gitleaks engine on top of the built-in
+    // secret scanner (best-effort; degrades to built-in only when absent).
+    gitleaks: parseBooleanInput(inputs.gitleaks),
+    // §4.16-next — monthly $ increase at/above which a fix is escalated to a
+    // human (needs-human). undefined disables cost escalation.
+    costIncreaseBlockUsd: parseCostIncreaseBlock(inputs.cost_increase_block_usd),
+    // §4.14 + module catalogue — operator-approved modules a fix/generation
+    // should prefer; raw string, structured by `parseModuleCatalogue` in the
+    // `list_modules` tool.
+    moduleCatalogue: inputs.module_catalogue,
+    // §28 — opt in to scaffolding a Go Terratest smoke test + a native
+    // `*.tftest.hcl` (both plan the module directly) when generating a reusable
+    // module; also widens the push allow-list so the test files can be written.
+    terratest: parseBooleanInput(inputs.terratest),
+    // P2.2 — opt in to HashiCorp's terraform-mcp-server as a second MCP server
+    // for the agent (live Terraform Registry knowledge: current module versions
+    // and provider argument shapes). Requires docker on the runner; degrades
+    // green with a note when absent. See utils/terraformMcp.ts.
+    terraformMcp: parseBooleanInput(inputs.terraform_mcp),
+    // §3.12 — a `@terramend fix …` command parsed from the triggering comment
+    // body (the prompt), scoping the run to a specific concern/severity/file.
+    // null when the prompt isn't a recognised command.
+    remediationCommand: parseRemediationCommand(prompt),
+    // explicit base-branch override; when unset the effective base is resolved
+    // at PR time (run-start branch → repo default) — see resolveBaseBranch.
+    baseBranch: parseBaseBranch(inputs.base_branch),
+    // resource addresses the operator allows the remediation to destroy/replace
+    // — consumed by the destroy-block guardrail (mcp/guardrails.ts). Unset means
+    // no destructive change to a stateful resource is permitted.
+    allowReplace: parseAllowReplace(inputs.allow_replace),
+    // §5.5 — org-specific review policy + FP precedents from the workflow file
+    // (owner-controlled, same trust surface as repo settings). merged into the
+    // Review mode instructions in main() via mergeReviewModeInstructions.
+    reviewInstructions: inputs.review_instructions,
+    fpFilteringInstructions: inputs.fp_filtering_instructions,
+  };
+}
+
+export type ResolvedPayload = ReturnType<typeof resolvePayload>;
+
+/**
+ * Parse and validate the optional `output_schema` action input. Returns the
+ * parsed object when present, or `undefined` when absent. Throws on invalid
+ * JSON or non-object payloads — these are workflow-author errors that should
+ * surface immediately, not silently degrade to "no schema".
+ */
+export function resolveOutputSchema(): Record<string, unknown> | undefined {
+  const raw = core.getInput("output_schema");
+  if (!raw) return undefined;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`invalid output_schema: not valid JSON`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`invalid output_schema: must be a JSON object`);
+  }
+  log.info("» structured output schema provided — output will be required");
+  return parsed as Record<string, unknown>;
+}

package/src/utils/postApiFetch.ts

@@ -0,0 +1,51 @@
+/** stdlib-only Terramend API fetch for entryPost.ts (no node_modules). */
+
+type PostApiFetchOptions = {
+  path: string;
+  method?: string | undefined;
+  headers?: Record<string, string> | undefined;
+  body?: string | undefined;
+};
+
+function getApiUrl(): string {
+  return process.env.API_URL || "https://terramend.com";
+}
+
+export async function postApiFetch(options: PostApiFetchOptions): Promise<Response> {
+  const url = new URL(options.path, getApiUrl());
+
+  const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET;
+  if (bypassSecret) {
+    url.searchParams.set("x-vercel-protection-bypass", bypassSecret);
+  }
+
+  const headers: Record<string, string> = {
+    ...options.headers,
+  };
+
+  if (bypassSecret) {
+    headers["x-vercel-protection-bypass"] = bypassSecret;
+  }
+
+  if (!options.body) {
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === "content-type") delete headers[key];
+    }
+  }
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 30_000);
+
+  try {
+    const init: RequestInit = {
+      method: options.method ?? "GET",
+      headers,
+      signal: controller.signal,
+    };
+    if (options.body) init.body = options.body;
+
+    return await fetch(url, init);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/utils/prSummary.test.ts

@@ -0,0 +1,224 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ToolContext } from "#app/mcp/server";
+import {
+  fetchPreviousSnapshot,
+  persistSummary,
+  readSummaryFile,
+  SUMMARY_FILE_NAME,
+  SUMMARY_SCAFFOLD,
+  seedSummaryFile,
+  summaryFilePath,
+} from "#app/utils/prSummary";
+
+vi.mock("#app/utils/apiFetch", () => ({
+  apiFetch: vi.fn(),
+}));
+
+vi.mock("#app/utils/cli", () => ({
+  log: {
+    info: vi.fn(),
+    debug: vi.fn(),
+    warning: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+vi.mock("#app/utils/patchWorkflowRunFields", () => ({
+  patchWorkflowRunFields: vi.fn(async () => undefined),
+}));
+
+import { apiFetch } from "#app/utils/apiFetch";
+import { patchWorkflowRunFields } from "#app/utils/patchWorkflowRunFields";
+
+const apiFetchMock = vi.mocked(apiFetch);
+const patchMock = vi.mocked(patchWorkflowRunFields);
+
+const TEMP = mkdtempSync(join(tmpdir(), "terramend-pr-summary-"));
+
+afterAll(() => {
+  rmSync(TEMP, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+// long enough to clear the 60-char minimum snapshot length
+const LONG_SNAPSHOT = `# PR summary\n\n${"meaningful cross-run context. ".repeat(4)}`.trim();
+
+let dirCounter = 0;
+function freshDir(): string {
+  dirCounter += 1;
+  return join(TEMP, `run-${dirCounter}`);
+}
+
+describe("summaryFilePath", () => {
+  it("joins the tmpdir with the well-known file name", () => {
+    expect(summaryFilePath("/tmp/run")).toBe(join("/tmp/run", SUMMARY_FILE_NAME));
+  });
+});
+
+describe("seedSummaryFile", () => {
+  it("seeds with the scaffold on first runs (no previous snapshot)", async () => {
+    const dir = freshDir();
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: null });
+    expect(path).toBe(summaryFilePath(dir));
+    await expect(readFile(path, "utf8")).resolves.toBe(SUMMARY_SCAFFOLD);
+  });
+
+  it("seeds with the previous snapshot when it is substantive", async () => {
+    const dir = freshDir();
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: LONG_SNAPSHOT });
+    await expect(readFile(path, "utf8")).resolves.toBe(LONG_SNAPSHOT);
+  });
+
+  it("falls back to the scaffold when the previous snapshot is too short", async () => {
+    const dir = freshDir();
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: "tiny" });
+    await expect(readFile(path, "utf8")).resolves.toBe(SUMMARY_SCAFFOLD);
+  });
+});
+
+describe("readSummaryFile", () => {
+  it("returns null when the file does not exist", async () => {
+    await expect(readSummaryFile(join(TEMP, "missing.md"))).resolves.toBeNull();
+  });
+
+  it("returns null when the content is below the sanity minimum", async () => {
+    const dir = freshDir();
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: null });
+    // the scaffold itself is above the minimum; overwrite with something tiny
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(path, "  short  ", "utf8");
+    await expect(readSummaryFile(path)).resolves.toBeNull();
+  });
+
+  it("returns the trimmed content for valid snapshots", async () => {
+    const dir = freshDir();
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: `${LONG_SNAPSHOT}\n\n` });
+    await expect(readSummaryFile(path)).resolves.toBe(LONG_SNAPSHOT);
+  });
+
+  it("caps oversized snapshots at the maximum length", async () => {
+    const dir = freshDir();
+    const huge = "x".repeat(40_000);
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: huge });
+    const read = await readSummaryFile(path);
+    expect(read).toHaveLength(32_768);
+    expect(huge.startsWith(read ?? "")).toBe(true);
+  });
+});
+
+describe("fetchPreviousSnapshot", () => {
+  function ctxWith(token: string | undefined): ToolContext {
+    return {
+      githubInstallationToken: token,
+      repo: { owner: "acme", name: "infra" },
+    } as unknown as ToolContext;
+  }
+
+  it("returns null without an installation token", async () => {
+    await expect(fetchPreviousSnapshot(ctxWith(undefined), 7)).resolves.toBeNull();
+    expect(apiFetchMock).not.toHaveBeenCalled();
+  });
+
+  it("returns null on non-ok responses", async () => {
+    apiFetchMock.mockResolvedValueOnce({ ok: false } as Response);
+    await expect(fetchPreviousSnapshot(ctxWith("tok"), 7)).resolves.toBeNull();
+  });
+
+  it("returns the snapshot from the API response", async () => {
+    apiFetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ snapshot: "previous summary" }),
+    } as Response);
+
+    await expect(fetchPreviousSnapshot(ctxWith("tok"), 7)).resolves.toBe("previous summary");
+    expect(apiFetchMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        path: "/api/repo/acme/infra/pr/7/summary-comment",
+        method: "GET",
+        headers: { authorization: "Bearer tok" },
+      }),
+    );
+  });
+
+  it("returns null for empty or missing snapshots", async () => {
+    apiFetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ snapshot: "" }),
+    } as Response);
+    await expect(fetchPreviousSnapshot(ctxWith("tok"), 7)).resolves.toBeNull();
+
+    apiFetchMock.mockResolvedValueOnce({ ok: true, json: async () => ({}) } as Response);
+    await expect(fetchPreviousSnapshot(ctxWith("tok"), 7)).resolves.toBeNull();
+  });
+
+  it("returns null when the API call throws", async () => {
+    apiFetchMock.mockRejectedValueOnce(new Error("network down"));
+    await expect(fetchPreviousSnapshot(ctxWith("tok"), 7)).resolves.toBeNull();
+  });
+});
+
+describe("persistSummary", () => {
+  function ctxWith(toolState: Record<string, unknown>): ToolContext {
+    return { toolState } as unknown as ToolContext;
+  }
+
+  it("does nothing when no summary file was seeded", async () => {
+    await persistSummary(ctxWith({}));
+    expect(patchMock).not.toHaveBeenCalled();
+  });
+
+  it("does nothing when persistence was already attempted", async () => {
+    await persistSummary(ctxWith({ summaryFilePath: "/tmp/x.md", summaryPersistAttempted: true }));
+    expect(patchMock).not.toHaveBeenCalled();
+  });
+
+  it("skips the PATCH when the file is missing or invalid", async () => {
+    const toolState: Record<string, unknown> = {
+      summaryFilePath: join(TEMP, "never-written.md"),
+    };
+    await persistSummary(ctxWith(toolState));
+    expect(toolState.summaryPersistAttempted).toBe(true);
+    expect(patchMock).not.toHaveBeenCalled();
+  });
+
+  it("skips the PATCH when the agent never edited the seed", async () => {
+    const dir = freshDir();
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: LONG_SNAPSHOT });
+    await persistSummary(ctxWith({ summaryFilePath: path, summarySeed: `${LONG_SNAPSHOT}\n` }));
+    expect(patchMock).not.toHaveBeenCalled();
+  });
+
+  it("persists the snapshot when the agent edited the file", async () => {
+    const dir = freshDir();
+    const edited = `${LONG_SNAPSHOT}\n\n## What changed\n\n- reviewed the auth flow end to end`;
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: edited });
+    const ctx = ctxWith({ summaryFilePath: path, summarySeed: SUMMARY_SCAFFOLD });
+
+    await persistSummary(ctx);
+
+    expect(patchMock).toHaveBeenCalledWith(ctx, { summarySnapshot: edited });
+  });
+
+  it("persists even without a recorded seed", async () => {
+    const dir = freshDir();
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: LONG_SNAPSHOT });
+    await persistSummary(ctxWith({ summaryFilePath: path }));
+    expect(patchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("swallows PATCH failures (best-effort)", async () => {
+    const dir = freshDir();
+    const path = await seedSummaryFile({ tmpdir: dir, previousSnapshot: LONG_SNAPSHOT });
+    patchMock.mockRejectedValueOnce(new Error("api down"));
+
+    await expect(persistSummary(ctxWith({ summaryFilePath: path }))).resolves.toBeUndefined();
+  });
+});