terramend 0.2.0

package/src/utils/learnings.test.ts

@@ -0,0 +1,87 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  LEARNINGS_FILE_NAME,
+  learningsFilePath,
+  readLearningsFile,
+  seedLearningsFile,
+} from "#app/utils/learnings";
+
+describe("learnings tmpfile round-trip", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "terramend-learnings-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("writes the verbatim DB body to disk and reads it back unchanged", async () => {
+    const current = [
+      "## Build & test",
+      "",
+      "- run tests with `pnpm -r test`",
+      "",
+      "## Architecture",
+      "",
+      "- workers in `worker/`",
+    ].join("\n");
+    const path = await seedLearningsFile({ tmpdir: dir, current });
+    expect(path).toBe(learningsFilePath(dir));
+    expect(path.endsWith(LEARNINGS_FILE_NAME)).toBe(true);
+
+    expect(await readFile(path, "utf8")).toBe(current);
+    expect(await readLearningsFile(path)).toBe(current);
+  });
+
+  it("seeds an empty file when the repo has no learnings yet, round-trip is empty string", async () => {
+    const path = await seedLearningsFile({ tmpdir: dir, current: null });
+    expect(await readFile(path, "utf8")).toBe("");
+    expect(await readLearningsFile(path)).toBe("");
+  });
+
+  it("returns null when the file is missing (treated as no-change by persist)", async () => {
+    expect(await readLearningsFile(learningsFilePath(dir))).toBeNull();
+  });
+
+  it("trims trailing whitespace so editor newlines never trigger a spurious PATCH", async () => {
+    const current = "## Build & test\n\n- one fact";
+    const path = await seedLearningsFile({ tmpdir: dir, current });
+    await writeFile(path, `${current}\n\n  `, "utf8");
+    expect(await readLearningsFile(path)).toBe(current);
+  });
+
+  it("truncates over-cap bodies at the last newline boundary so the next-seed TOC parse stays clean", async () => {
+    const padding = `${"x".repeat(80)}\n`.repeat(1300);
+    const oversized = `## Build & test\n\n${padding}`;
+    const path = await seedLearningsFile({ tmpdir: dir, current: null });
+    await writeFile(path, oversized, "utf8");
+    const read = await readLearningsFile(path);
+    expect(read).toBeTruthy();
+    expect(read?.length).toBeLessThanOrEqual(100_000);
+    const tailLine = read?.split("\n").pop() ?? "";
+    expect(/^x+$/.test(tailLine)).toBe(true);
+    expect(tailLine.length).toBe(80);
+  });
+
+  it("falls back to a hard truncate when the only newline is far above the cap (giant single line)", async () => {
+    const oversized = `## Build & test\n${"x".repeat(110_000)}`;
+    const path = await seedLearningsFile({ tmpdir: dir, current: null });
+    await writeFile(path, oversized, "utf8");
+    const read = await readLearningsFile(path);
+    expect(read).toBeTruthy();
+    expect(read?.length).toBe(100_000);
+    expect(read?.startsWith("## Build & test\n")).toBe(true);
+  });
+
+  it("preserves legacy free-text without scaffolding or wrapping", async () => {
+    const legacy = "- this is some old free-text bullet\n- another one";
+    const path = await seedLearningsFile({ tmpdir: dir, current: legacy });
+    expect(await readFile(path, "utf8")).toBe(legacy);
+    expect(await readLearningsFile(path)).toBe(legacy);
+  });
+});

package/src/utils/learnings.ts

@@ -0,0 +1,138 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ToolContext } from "#app/mcp/server";
+import { apiFetch } from "#app/utils/apiFetch";
+import { isBackendConfigured } from "#app/utils/apiUrl";
+import { log } from "#app/utils/cli";
+import { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary } from "#app/utils/learningsTruncate";
+
+export { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary };
+
+/**
+ * Repo-level learnings — operational facts about a repo (setup steps, test
+ * commands, conventions, gotchas) that accumulate across agent runs and feed
+ * back into future runs as durable context. Modeled on the PR-summary tmpfile
+ * pattern (see action/utils/prSummary.ts):
+ *
+ *   1. server seeds `terramend-learnings.md` with the verbatim body of
+ *      `Repo.learnings` (or empty for fresh repos), and parses headings
+ *      server-side (`utils/learningsToc.ts`) — the parsed TOC is rendered
+ *      into the LEARNINGS prompt section, not into the file
+ *   2. the agent reads the TOC in the prompt and uses listed line ranges
+ *      to read just the sections relevant to the current task — file can
+ *      grow large, but only targeted ranges hit the agent's context
+ *   3. agent edits the file in place at end-of-run during the reflection
+ *      turn (see action/agents/postRun.ts buildLearningsReflectionPrompt)
+ *   4. main.ts reads the file back at end-of-run and PATCHes
+ *      `/api/repo/[owner]/[repo]/learnings` if the body changed
+ *
+ * Edit-in-place avoids stuffing the entire learnings list into both the
+ * prompt context and an `update_learnings` MCP tool call (which previously
+ * required passing the FULL merged list as a string parameter — an
+ * output-token tax that grew linearly with the learnings size).
+ *
+ * Section structure is agent-curated. The reflection prompt teaches
+ * hierarchy + a soft 300-line-per-section cap to keep TOC ranges
+ * agent-targetable on long-lived repos; there is no fixed taxonomy.
+ */
+
+export const LEARNINGS_FILE_NAME = "terramend-learnings.md";
+
+export function learningsFilePath(tmpdir: string): string {
+  return join(tmpdir, LEARNINGS_FILE_NAME);
+}
+
+/** seed the rolling learnings tmpfile with the verbatim DB body (or empty
+ * string for fresh repos). returns the absolute path. the parsed TOC is
+ * carried separately via `RepoSettings.learningsHeadings` and rendered
+ * into the prompt by `resolveInstructions`, so the file on disk is just
+ * the body — no markers, no scaffold, no in-file TOC. */
+export async function seedLearningsFile(params: {
+  tmpdir: string;
+  current: string | null;
+}): Promise<string> {
+  const path = learningsFilePath(params.tmpdir);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, params.current ?? "", "utf8");
+  return path;
+}
+
+/** read the agent-edited learnings file. returns null when the file is
+ * missing or unreadable (treated as "no change"). caps content at the
+ * server's max length to avoid a 400 round-trip. */
+export async function readLearningsFile(path: string): Promise<string | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  return truncateAtLineBoundary(raw.trim(), MAX_LEARNINGS_LENGTH);
+}
+
+/**
+ * Read the agent-edited repo-level learnings tmpfile and PATCH it to
+ * `Repo.learnings`.
+ *
+ * Best-effort: any failure is logged and does not affect the run's success
+ * status. Skips the PATCH when the file is byte-trim-identical to its seed —
+ * the agent didn't touch it, so writing the same content back would just
+ * burn a `LearningsRevision` row and an API round-trip.
+ *
+ * `ctx.toolState.model` is forwarded so `LearningsRevision.model` keeps
+ * populating; it powers the per-revision attribution badge in the UI
+ * history view.
+ *
+ * `learningsPersistAttempted` guards against double-execution between the
+ * normal end-of-run path and the SIGINT/SIGTERM handler.
+ */
+export async function persistLearnings(ctx: ToolContext): Promise<void> {
+  const filePath = ctx.toolState.learningsFilePath;
+  if (!filePath) return;
+  if (ctx.toolState.learningsPersistAttempted) return;
+  ctx.toolState.learningsPersistAttempted = true;
+  // dormant open-core seam: with no backend configured (standalone BYOK), there
+  // is nowhere to persist repo learnings — no-op silently instead of PATCHing
+  // the default marketing host and warning on its 404.
+  if (!isBackendConfigured()) {
+    log.debug("no backend configured (API_URL unset) — skipping learnings persist");
+    return;
+  }
+  const current = await readLearningsFile(filePath);
+  if (current === null) {
+    log.debug(`learnings tmpfile missing or unreadable at ${filePath} — skipping persist`);
+    return;
+  }
+  const seed = ctx.toolState.learningsSeed?.trim() ?? "";
+  if (current === seed) {
+    log.debug("learnings tmpfile unchanged from seed — skipping persist");
+    return;
+  }
+  try {
+    const response = await apiFetch({
+      path: `/api/repo/${ctx.repo.owner}/${ctx.repo.name}/learnings`,
+      method: "PATCH",
+      headers: {
+        authorization: `Bearer ${ctx.apiToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        learnings: current,
+        model: ctx.toolState.model,
+      }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+      const error = await response.text().catch(() => "(no body)");
+      // promoted from debug → warning: this path means the agent edited the
+      // file (we already short-circuited the unchanged-from-seed case above)
+      // but the PATCH dropped it on the floor. silently losing real work is
+      // worse than the noise of a CI warning.
+      log.warning(`learnings persist failed (${response.status}): ${error}`);
+      return;
+    }
+    log.info("» learnings updated");
+  } catch (err) {
+    log.warning(`learnings persist failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

package/src/utils/learningsTocRender.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import { buildLearningsSection, renderLearningsToc } from "#app/utils/instructions";
+import type { LearningsHeading } from "#app/utils/runContext";
+
+const h = (depth: 1 | 2 | 3 | 4 | 5 | 6, title: string, startLine: number, endLine: number) => ({
+  depth,
+  title,
+  startLine,
+  endLine,
+});
+
+describe("renderLearningsToc", () => {
+  it("renders flat h2 list with parenthesized ranges, no hashes or backticks", () => {
+    const headings: LearningsHeading[] = [
+      h(2, "Build & test", 1, 18),
+      h(2, "Architecture", 19, 60),
+    ];
+    expect(renderLearningsToc(headings)).toBe(
+      `- Build & test (L1-L18)
+- Architecture (L19-L60)`,
+    );
+  });
+
+  it("indents deeper headings 2 spaces per depth level past the shallowest", () => {
+    const headings: LearningsHeading[] = [
+      h(2, "Build & test", 1, 42),
+      h(3, "Local", 3, 18),
+      h(3, "CI", 19, 42),
+      h(2, "Architecture", 43, 210),
+      h(3, "Background workers", 80, 210),
+    ];
+    expect(renderLearningsToc(headings)).toBe(
+      `- Build & test (L1-L42)
+  - Local (L3-L18)
+  - CI (L19-L42)
+- Architecture (L43-L210)
+  - Background workers (L80-L210)`,
+    );
+  });
+
+  it("treats the shallowest depth as the root column when no h2 is present", () => {
+    const headings: LearningsHeading[] = [h(3, "Only h3", 1, 5), h(4, "Sub h4", 2, 5)];
+    expect(renderLearningsToc(headings)).toBe(
+      `- Only h3 (L1-L5)
+  - Sub h4 (L2-L5)`,
+    );
+  });
+
+  it("supports depths up through h6 with stable 2-space indent steps", () => {
+    const headings: LearningsHeading[] = [
+      h(2, "Two", 1, 10),
+      h(3, "Three", 2, 10),
+      h(4, "Four", 3, 10),
+      h(5, "Five", 4, 10),
+      h(6, "Six", 5, 10),
+    ];
+    expect(renderLearningsToc(headings)).toBe(
+      `- Two (L1-L10)
+  - Three (L2-L10)
+    - Four (L3-L10)
+      - Five (L4-L10)
+        - Six (L5-L10)`,
+    );
+  });
+});
+
+describe("buildLearningsSection", () => {
+  it("returns empty string when no file path (seed step failed)", () => {
+    expect(buildLearningsSection({ filePath: null, headings: [] })).toBe("");
+  });
+
+  it("renders the no-headings affordance when the body has no structure", () => {
+    const out = buildLearningsSection({
+      filePath: "/tmp/run-1/terramend-learnings.md",
+      headings: [],
+    });
+    expect(out).toContain("************* LEARNINGS *************");
+    expect(out).toContain("/tmp/run-1/terramend-learnings.md");
+    expect(out).toContain("no headings yet");
+    expect(out).toContain("structure it with");
+    // does not include a TOC list when there are no headings
+    expect(out).not.toMatch(/\(L\d+-L\d+\)/);
+  });
+
+  it("intro phrasing does not assert prior runs — works for fresh empty repos too", () => {
+    const out = buildLearningsSection({
+      filePath: "/tmp/run-1/terramend-learnings.md",
+      headings: [],
+    });
+    // load-bearing: fresh repos have zero previous runs. the prior copy
+    // ("accumulated by previous agent runs") was a lie in that case.
+    expect(out).not.toContain("accumulated by previous agent runs");
+    expect(out).toContain("maintained across runs");
+  });
+
+  it("renders the TOC inline with the file path and heading guidance", () => {
+    const out = buildLearningsSection({
+      filePath: "/tmp/run-1/terramend-learnings.md",
+      headings: [h(2, "Build & test", 1, 18), h(2, "Architecture", 19, 60)],
+    });
+    expect(out).toContain("************* LEARNINGS *************");
+    expect(out).toContain("/tmp/run-1/terramend-learnings.md");
+    expect(out).toContain("- Build & test (L1-L18)");
+    expect(out).toContain("- Architecture (L19-L60)");
+    expect(out).toContain("Each range starts at the section heading line");
+    // re-read affordance: ranges reflect the run-start snapshot, so the
+    // agent needs an explicit nudge to re-read after any mid-run edits.
+    // mid-run edits shift the line numbers of every later section, not
+    // just the edited one — wording is explicit about that.
+    expect(out).toContain("run-start snapshot");
+    expect(out).toContain("any edit shifts the line numbers of every later section");
+    // explicit "no hashes, no backticks" in the rendered list
+    expect(out).not.toContain("- `## Build");
+    expect(out).not.toContain("`## Build");
+  });
+});

package/src/utils/learningsTruncate.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary } from "#app/utils/learningsTruncate";
+
+describe("truncateAtLineBoundary", () => {
+  it("returns the body unchanged when within the cap", () => {
+    expect(truncateAtLineBoundary("short body", 100)).toBe("short body");
+    expect(truncateAtLineBoundary("exact", 5)).toBe("exact");
+  });
+
+  it("truncates at the last newline before the cap", () => {
+    const body = "line one\nline two\nline three tail beyond";
+    const result = truncateAtLineBoundary(body, 25);
+    expect(result).toBe("line one\nline two");
+  });
+
+  it("hard-slices when the head contains no newline", () => {
+    const body = "x".repeat(50);
+    expect(truncateAtLineBoundary(body, 10)).toBe("x".repeat(10));
+  });
+
+  it("hard-slices when the head starts with a newline (lastNewline at 0)", () => {
+    const body = `\n${"y".repeat(50)}`;
+    expect(truncateAtLineBoundary(body, 10)).toBe(`\n${"y".repeat(9)}`);
+  });
+
+  it("hard-slices instead of discarding a giant trailing line", () => {
+    // one short line, then a single line far longer than the 4096 tolerance
+    const body = `header\n${"z".repeat(10_000)}`;
+    const cap = 6000;
+    const result = truncateAtLineBoundary(body, cap);
+    // keeping only "header" would discard ~6KB; the hard slice is preferred
+    expect(result).toHaveLength(cap);
+    expect(result.startsWith("header\n")).toBe(true);
+  });
+
+  it("exports a six-figure cap for the learnings body", () => {
+    expect(MAX_LEARNINGS_LENGTH).toBe(100_000);
+  });
+});

package/src/utils/learningsTruncate.ts

@@ -0,0 +1,42 @@
+/**
+ * pure string helpers for capping and line-boundary-truncating the
+ * `Repo.learnings` body. lives in its own module (vs alongside
+ * `learnings.ts`) so the proprietary root app can re-export it through
+ * `action/internal/index.ts` without dragging the entire MCP type graph
+ * along — `learnings.ts` imports `ToolContext` for its runtime helpers,
+ * and pulling that into the SDK-facing `internal` barrel expands the
+ * type graph reachable from root `tsc` and `cf-worker-indexing` to every
+ * tool module under `action/mcp/`. keeping these helpers MCP-free is the
+ * cheap structural fix.
+ *
+ * see `action/utils/learnings.ts` for the full learnings-file lifecycle.
+ */
+
+/** maximum size of `Repo.learnings` body in chars. action truncates the
+ * read-back BEFORE the PATCH to avoid sending an oversized payload; the
+ * server applies the same truncation as a defense-in-depth backstop (any
+ * caller that misses the client-side step would otherwise persist a
+ * mid-line tail, breaking the next-run TOC parse).
+ *
+ * raised from 10k → 100k once the TOC affordance landed: with line-range
+ * reads via the server-parsed TOC the agent doesn't ingest the whole
+ * file, so the cap is governed by curation discipline rather than a
+ * tight byte ceiling. 100k holds ~400-500 short bullets. */
+export const MAX_LEARNINGS_LENGTH = 100_000;
+
+/** truncate at the last newline boundary before `cap` so we don't leave
+ * a partial line at the tail (a half-truncated `## Headi` confuses the
+ * server's next-seed TOC parse and shrinks visible structure). falls
+ * back to a hard `slice` when the line boundary would discard a large
+ * run of content — i.e. when the tail of `head` is one giant line (rare:
+ * minified pastes, fenced log dumps). losing a partial last line is
+ * preferable to losing kilobytes of body. */
+const TRUNCATION_LINE_BOUNDARY_TOLERANCE = 4096;
+export function truncateAtLineBoundary(body: string, cap: number): string {
+  if (body.length <= cap) return body;
+  const head = body.slice(0, cap);
+  const lastNewline = head.lastIndexOf("\n");
+  if (lastNewline <= 0) return head;
+  if (cap - lastNewline > TRUNCATION_LINE_BOUNDARY_TOLERANCE) return head;
+  return head.slice(0, lastNewline);
+}

package/src/utils/lifecycle.test.ts

@@ -0,0 +1,195 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { LIFECYCLE_HOOK_TIMEOUT_MS } from "#app/lifecycle";
+import { describeSetupFailure, executeLifecycleHook } from "#app/utils/lifecycle";
+import {
+  SPAWN_ACTIVITY_TIMEOUT_CODE,
+  SPAWN_TIMEOUT_CODE,
+  SpawnTimeoutError,
+  spawn,
+} from "#app/utils/subprocess";
+
+// executeLifecycleHook shells out (bash for the hook, git for the
+// normalize-after pass) — mock spawn so the tests stay subprocess-free and
+// OS-independent. error classes / codes stay real.
+vi.mock("#app/utils/subprocess", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("#app/utils/subprocess")>();
+  return { ...actual, spawn: vi.fn() };
+});
+
+const spawnMock = vi.mocked(spawn);
+
+function ok(stdout = "", stderr = "", exitCode = 0) {
+  return { stdout, stderr, exitCode, durationMs: 1 };
+}
+
+beforeEach(() => {
+  spawnMock.mockReset();
+  spawnMock.mockResolvedValue(ok());
+});
+
+describe("LIFECYCLE_HOOK_TIMEOUT_MS", () => {
+  it("is ten minutes", () => {
+    expect(LIFECYCLE_HOOK_TIMEOUT_MS).toBe(600_000);
+  });
+});
+
+describe("describeSetupFailure", () => {
+  it("returns an empty string when there was no failure", () => {
+    expect(describeSetupFailure(undefined)).toBe("");
+  });
+
+  it("describes a non-zero exit with its output", () => {
+    const text = describeSetupFailure({ kind: "exit", exitCode: 3, output: "pnpm install died" });
+    expect(text).toContain("exited with code 3");
+    expect(text).toContain("pnpm install died");
+  });
+
+  it("falls back to (empty) when the exit produced no output", () => {
+    expect(describeSetupFailure({ kind: "exit", exitCode: 1, output: "" })).toContain("(empty)");
+  });
+
+  it("describes a timeout", () => {
+    expect(describeSetupFailure({ kind: "timeout" })).toContain("timed out");
+  });
+
+  it("describes a spawn failure with the spawn error", () => {
+    expect(describeSetupFailure({ kind: "spawn", spawnError: "ENOENT bash" })).toContain(
+      "failed to start: ENOENT bash",
+    );
+  });
+});
+
+describe("executeLifecycleHook", () => {
+  it("is a no-op when no script is configured", async () => {
+    const result = await executeLifecycleHook({ event: "setup", script: null });
+    expect(result).toEqual({});
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it("returns no warning when the hook exits 0", async () => {
+    const result = await executeLifecycleHook({ event: "setup", script: "true" });
+    expect(result).toEqual({});
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    const opts = spawnMock.mock.calls[0]?.[0];
+    expect(opts?.cmd).toBe("bash");
+    expect(opts?.args).toEqual(["-c", "true"]);
+    expect(opts?.timeout).toBe(LIFECYCLE_HOOK_TIMEOUT_MS);
+  });
+
+  it("returns a structured exit failure with stderr preferred over stdout", async () => {
+    spawnMock.mockResolvedValue(ok("stdout text", "stderr text\n", 2));
+    const result = await executeLifecycleHook({ event: "setup", script: "exit 2" });
+    expect(result.failure).toEqual({ kind: "exit", exitCode: 2, output: "stderr text" });
+    expect(result.warning).toContain("failed with exit code 2");
+    expect(result.warning).toContain("stderr text");
+  });
+
+  it("falls back to stdout when stderr is empty", async () => {
+    spawnMock.mockResolvedValue(ok("only stdout\n", "", 1));
+    const result = await executeLifecycleHook({ event: "post-checkout", script: "exit 1" });
+    expect(result.failure).toEqual({ kind: "exit", exitCode: 1, output: "only stdout" });
+  });
+
+  it("classifies a spawn timeout as a non-retryable timeout failure", async () => {
+    spawnMock.mockRejectedValue(new SpawnTimeoutError("hook timed out", SPAWN_TIMEOUT_CODE));
+    const result = await executeLifecycleHook({ event: "setup", script: "sleep 9999" });
+    expect(result.failure).toEqual({ kind: "timeout" });
+    expect(result.warning).toContain("timed out after 10min");
+    expect(result.warning).toContain("do NOT retry");
+  });
+
+  it("classifies an activity timeout as a timeout failure too", async () => {
+    spawnMock.mockRejectedValue(new SpawnTimeoutError("idle", SPAWN_ACTIVITY_TIMEOUT_CODE));
+    const result = await executeLifecycleHook({ event: "setup", script: "sleep 9999" });
+    expect(result.failure).toEqual({ kind: "timeout" });
+  });
+
+  it("classifies any other throw as a retryable spawn failure", async () => {
+    spawnMock.mockRejectedValue(new Error("ENOENT: bash not found"));
+    const result = await executeLifecycleHook({ event: "setup", script: "true" });
+    expect(result.failure).toEqual({ kind: "spawn", spawnError: "ENOENT: bash not found" });
+    expect(result.warning).toContain("failed to spawn");
+    expect(result.warning).toContain("retry the operation");
+  });
+
+  describe("normalizeWorkingTreeAfter", () => {
+    function gitCalls(): string[][] {
+      return spawnMock.mock.calls
+        .map((c) => c[0])
+        .filter((opts) => opts?.cmd === "git")
+        .map((opts) => opts?.args ?? []);
+    }
+
+    it("discards tracked drift the hook introduced on a previously clean tree", async () => {
+      // call order: git diff (pre) → bash hook → git diff (post) → git restore
+      let diffCalls = 0;
+      spawnMock.mockImplementation(async (opts) => {
+        if (opts.cmd === "git" && opts.args?.[0] === "diff") {
+          diffCalls += 1;
+          return ok(diffCalls === 1 ? "" : "pnpm-lock.yaml\npackage.json\n");
+        }
+        return ok();
+      });
+      const result = await executeLifecycleHook({
+        event: "setup",
+        script: "pnpm install",
+        normalizeWorkingTreeAfter: true,
+      });
+      expect(result).toEqual({});
+      expect(gitCalls()).toEqual([
+        ["diff", "--name-only", "HEAD"],
+        ["diff", "--name-only", "HEAD"],
+        ["restore", "--staged", "--worktree", "."],
+      ]);
+    });
+
+    it("skips normalization when the tree had pre-existing tracked changes", async () => {
+      spawnMock.mockImplementation(async (opts) => {
+        if (opts.cmd === "git" && opts.args?.[0] === "diff") return ok("preexisting.ts\n");
+        return ok();
+      });
+      await executeLifecycleHook({
+        event: "setup",
+        script: "pnpm install",
+        normalizeWorkingTreeAfter: true,
+      });
+      // only the pre-hook snapshot ran; no post-hook diff, no restore.
+      expect(gitCalls()).toEqual([["diff", "--name-only", "HEAD"]]);
+    });
+
+    it("does nothing when the hook leaves the tree clean", async () => {
+      await executeLifecycleHook({
+        event: "setup",
+        script: "true",
+        normalizeWorkingTreeAfter: true,
+      });
+      expect(gitCalls()).toEqual([
+        ["diff", "--name-only", "HEAD"],
+        ["diff", "--name-only", "HEAD"],
+      ]);
+    });
+
+    it("still normalizes when the hook itself failed", async () => {
+      let diffCalls = 0;
+      spawnMock.mockImplementation(async (opts) => {
+        if (opts.cmd === "git" && opts.args?.[0] === "diff") {
+          diffCalls += 1;
+          return ok(diffCalls === 1 ? "" : "pnpm-lock.yaml\n");
+        }
+        if (opts.cmd === "bash") return ok("", "boom", 1);
+        return ok();
+      });
+      const result = await executeLifecycleHook({
+        event: "setup",
+        script: "pnpm install && exit 1",
+        normalizeWorkingTreeAfter: true,
+      });
+      expect(result.failure).toEqual({ kind: "exit", exitCode: 1, output: "boom" });
+      expect(gitCalls()).toEqual([
+        ["diff", "--name-only", "HEAD"],
+        ["diff", "--name-only", "HEAD"],
+        ["restore", "--staged", "--worktree", "."],
+      ]);
+    });
+  });
+});