@pmelab/gtd 26.0.0 → 27.0.0

package/src/step/planStep.test.ts

@@ -130,3 +130,56 @@ describe("planStep — keepHistory", () => {
     ).toBe(false)
   })
 })
+
+describe("planStep — keepTurn", () => {
+  const kept = "refs/gtd/kept/abc/building"
+
+  it("emits keepTurn in place of commitAll, carrying the step's own commit message", () => {
+    const s = snapshot({
+      state: "building",
+      stepDef: { actor: "agent", kind: "prompt" },
+      actor: "agent",
+      changes: [{ status: "A", path: "naive.txt" }],
+      landing: { ...commitTo("building", "checking", "agent"), keepTurn: kept },
+    })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps.map((step) => step.kind)).toEqual(["gitWrite", "outcome"])
+    expect(outcome.steps[0]).toEqual({
+      kind: "gitWrite",
+      write: {
+        kind: "keepTurn",
+        ref: kept,
+        message: "gtd(agent): building → checking\n\nGtd-Step: building#1\nGtd-Format: 1",
+      },
+    })
+  })
+
+  it("a finishing keep landing points the history ref after the marker", () => {
+    const s = snapshot({
+      state: "building",
+      stepDef: { actor: "agent", kind: "prompt" },
+      actor: "agent",
+      landing: {
+        ...commitTo("building", "idle", "agent"),
+        keepTurn: kept,
+        keepHistory: "refs/gtd/history/abc",
+      },
+    })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps.map((step) => step.kind)).toEqual(["gitWrite", "gitWrite", "outcome"])
+    expect(outcome.steps[0]).toMatchObject({ write: { kind: "keepTurn" } })
+    expect(outcome.steps[1]).toEqual({
+      kind: "gitWrite",
+      write: { kind: "updateRef", ref: "refs/gtd/history/abc", target: "HEAD" },
+    })
+  })
+
+  it("without keepTurn the landing stays a commitAll", () => {
+    const s = snapshot({ state: "building", stepDef: {}, landing: commitTo("building", "done") })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps[0]).toMatchObject({ write: { kind: "commitAll" } })
+  })
+})

package/src/step/planStep.ts

@@ -82,7 +82,13 @@ export const planStep = (
     subject,
     steps: [
       ...uncheckStep(snapshot),
-      { kind: "gitWrite", write: { kind: "commitAll", message } },
+      {
+        kind: "gitWrite",
+        write:
+          landing.keepTurn !== undefined
+            ? { kind: "keepTurn", ref: landing.keepTurn, message }
+            : { kind: "commitAll", message },
+      },
       ...(landing.keepHistory !== undefined
         ? [
             {

package/src/step/strayPaths.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest"
+import { strayPaths } from "./index.js"
+
+describe("strayPaths", () => {
+  it("returns the paths no glob matches, sorted", () => {
+    expect(strayPaths(["src/a.ts", "z.md", "a.md"], ["src/**"])).toEqual(["a.md", "z.md"])
+  })
+
+  it("an empty allowlist returns every touched path", () => {
+    expect(strayPaths(["b", "a"], [])).toEqual(["a", "b"])
+  })
+
+  it("an empty touched list returns []", () => {
+    expect(strayPaths([], ["src/**"])).toEqual([])
+    expect(strayPaths([], [])).toEqual([])
+  })
+})

package/src/step/strayPaths.ts

@@ -0,0 +1,8 @@
+import { globMatches } from "../wire/index.js"
+
+/** Globs use the `access.write` dialect (`globMatches`). */
+export const strayPaths = (
+  touched: ReadonlyArray<string>,
+  allow: ReadonlyArray<string>,
+): ReadonlyArray<string> =>
+  touched.filter((path) => !allow.some((glob) => globMatches(path, glob))).sort()

package/src/testkit/EmittedScriptRecognizer.test.ts

@@ -5,6 +5,7 @@ import {
   deleteRef,
   discardPending,
   hardResetTo,
+  keepTurn,
   mixedResetTo,
   softResetTo,
   updateRef,
@@ -40,7 +41,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     twin.writeFile("a.txt", "1")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, commitAll("gtd(agent): building"))
-    twin.commitAllWithPrefix("gtd(agent): building")
+    twin.seedCommit("gtd(agent): building")
 
     expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
@@ -84,15 +85,15 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("softResetTo: moves HEAD only, leaving index and worktree untouched", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const first = repo.resolveRef("HEAD")!
     repo.writeFile("b.txt", "2")
-    repo.commitAllWithPrefix("chore: second")
+    repo.seedCommit("chore: second")
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("b.txt", "2")
-    twin.commitAllWithPrefix("chore: second")
+    twin.seedCommit("chore: second")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, softResetTo(first))
     twin.softResetTo(first)
@@ -105,15 +106,15 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("mixedResetTo: moves HEAD and index, leaving the worktree untouched", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const first = repo.resolveRef("HEAD")!
     repo.writeFile("b.txt", "2")
-    repo.commitAllWithPrefix("chore: second")
+    repo.seedCommit("chore: second")
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("b.txt", "2")
-    twin.commitAllWithPrefix("chore: second")
+    twin.seedCommit("chore: second")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, mixedResetTo(first))
     twin.mixedResetTo(first)
@@ -125,15 +126,15 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("hardResetTo: moves HEAD, index, AND worktree", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const first = repo.resolveRef("HEAD")!
     repo.writeFile("b.txt", "2")
-    repo.commitAllWithPrefix("chore: second")
+    repo.seedCommit("chore: second")
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("b.txt", "2")
-    twin.commitAllWithPrefix("chore: second")
+    twin.seedCommit("chore: second")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, hardResetTo(first))
     twin.hardResetTo(first)
@@ -146,12 +147,12 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("discardPending: drops every pending change, tracked or untracked", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     repo.writeFile("a.txt", "changed")
     repo.writeFile("untracked.txt", "new")
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("a.txt", "changed")
     twin.writeFile("untracked.txt", "new")
 
@@ -167,11 +168,11 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("updateRef: points a repo-local ref at a commit hash", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const hash = repo.resolveRef("HEAD")!
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, updateRef("refs/gtd/base", hash))
     twin.updateRef("refs/gtd/base", hash)
@@ -184,11 +185,11 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("deleteRef: removes a repo-local ref (idempotently)", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     repo.updateRef("refs/gtd/base", repo.resolveRef("HEAD")!)
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.updateRef("refs/gtd/base", twin.resolveRef("HEAD")!)
 
     const result = applyEmittedScript(repo, NO_COMMANDS, deleteRef("refs/gtd/base"))
@@ -405,7 +406,7 @@ describe("applyEmittedScript — a tripped precondition stops the script", () =>
   it("fails at the precondition and never applies a subsequent recognizable block", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const actualHead = repo.resolveRef("HEAD")!
     const wrongHash = "0".repeat(40)
     expect(wrongHash).not.toBe(actualHead)
@@ -426,7 +427,7 @@ describe("applyEmittedScript — a tripped precondition stops the script", () =>
   it("a satisfied precondition is a no-op and lets the rest of the script run", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const actualHead = repo.resolveRef("HEAD")!
 
     const script = [preconditionHeadEquals(actualHead), commitAll("gtd(agent): lands")].join("\n\n")
@@ -442,7 +443,7 @@ describe("applyEmittedScript — a realistic assembled multi-block script", () =
   it("parses set -eu and a satisfied precondition alongside real builder blocks", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const first = repo.resolveRef("HEAD")!
 
     const script = [
@@ -464,11 +465,11 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
   it("an assembled commitAll applies exactly like commitAllWithPrefix", () => {
     const repo = new InMemRepo()
     repo.writeFile("base.txt", "0")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     repo.writeFile("a.txt", "1")
     const twin = new InMemRepo()
     twin.writeFile("base.txt", "0")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("a.txt", "1")
 
     const steps: readonly EmitStep[] = [
@@ -476,7 +477,7 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
     ]
     const { required } = emitScripts(steps)
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
-    twin.commitAllWithPrefix("gtd(agent): building")
+    twin.seedCommit("gtd(agent): building")
 
     expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
@@ -485,7 +486,7 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
   it("a squash's four gitWrite steps (retain, soft-reset, commit-as-is, discard) apply in order", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("gtd(agent): building")
+    repo.seedCommit("gtd(agent): building")
     const tip = repo.resolveRef("HEAD")!
     // Untracked, never staged — the index still matches the tip's own tree
     // exactly, mirroring the real flow where nothing `git add`s between the
@@ -537,11 +538,11 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
   it("a realistic assembled script — commitAll's gitWrite plus a trailing outcome step — applies exactly like commitAllWithPrefix, the outcome step contributing nothing", () => {
     const repo = new InMemRepo()
     repo.writeFile("base.txt", "0")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     repo.writeFile("a.txt", "1")
     const twin = new InMemRepo()
     twin.writeFile("base.txt", "0")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("a.txt", "1")
 
     const steps: readonly EmitStep[] = [
@@ -550,7 +551,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
     ]
     const { required } = emitScripts(steps)
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
-    twin.commitAllWithPrefix("gtd(agent): building")
+    twin.seedCommit("gtd(agent): building")
 
     expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
@@ -636,3 +637,30 @@ describe("applyEmittedScript — Emit.ts's combinedScript (the whole stdout of a
     expect(result.error).toContain("totally-unrecognized-required-command")
   })
 })
+
+describe("applyEmittedScript — keepTurn", () => {
+  const MESSAGE = "gtd(agent): a → b\n\nGtd-Step: a#1\nGtd-Format: 1"
+  const REF = "refs/gtd/kept/entry/a"
+
+  const seeded = (): InMemRepo => {
+    const repo = new InMemRepo()
+    repo.writeFile("base.txt", "0")
+    repo.seedCommit("chore: first")
+    repo.writeFile("turn.txt", "1")
+    return repo
+  }
+
+  it("fails loudly on a near-miss and applies nothing", () => {
+    const repo = seeded()
+    const before = snapshot(repo)
+    const nearMiss = keepTurn(REF, MESSAGE).replace(
+      "git reset --hard HEAD",
+      "git reset --soft HEAD",
+    )
+    const result = applyEmittedScript(repo, NO_COMMANDS, nearMiss)
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain("unrecognized script block")
+    expect(snapshot(repo)).toEqual(before)
+    expect(repo.resolveRef(REF)).toBeNull()
+  })
+})

package/src/testkit/EmittedScriptRecognizer.ts

@@ -9,6 +9,7 @@ import {
   deleteRef,
   discardPending,
   hardResetTo,
+  keepTurn,
   mixedResetTo,
   shellQuote,
   softResetTo,
@@ -30,6 +31,7 @@ import {
   steeringFormatFor,
   type SteeringFormat,
 } from "../steering/index.js"
+import { refNameFault } from "../replay/index.js"
 import { renderFormat } from "../wire/index.js"
 import { applyFlowScript, rewritten } from "./FlowScripts.js"
 import type { InMemRepo } from "./InMemRepo.js"
@@ -140,6 +142,20 @@ const conditionStatement = (block: string): string => {
   return end === -1 ? block.slice(start) : block.slice(start, end)
 }
 
+/** `keepTurn`: an invalid ref name fails before anything moves, as `git update-ref` does. */
+const recognizeKeepTurn = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
+  const [message, refDir] = extractQuotedTokens(block)
+  const ref = refDir?.slice(0, -1)
+  if (message === undefined || ref === undefined || keepTurn(ref, message) !== block) {
+    return undefined
+  }
+  if (refNameFault(ref) !== undefined) {
+    return { kind: "failed", error: `fatal: invalid ref format: ${ref}`, status: 128 }
+  }
+  const failure = repo.keepTurn(ref, message)
+  return failure === undefined ? { kind: "applied" } : { kind: "failed", error: failure, status: 1 }
+}
+
 // fallow-ignore-next-line complexity
 const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
   if (block === discardPending()) {
@@ -156,11 +172,15 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
   // quoted argument.
   const conditionLine = conditionStatement(block)
 
+  if (block.startsWith("git add -A || exit 1\ngtd_sign_cfg=")) return recognizeKeepTurn(repo, block)
+
   if (block.startsWith("git add -A || exit 1\n")) {
     const [message] = extractQuotedTokens(conditionLine)
     if (message !== undefined && commitAll(message) === block) {
-      repo.commitAllWithPrefix(message)
-      return { kind: "applied" }
+      const failure = repo.commitAllWithPrefix(message)
+      return failure === undefined
+        ? { kind: "applied" }
+        : { kind: "failed", error: failure, status: 1 }
     }
     return undefined
   }
@@ -168,8 +188,10 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
   if (block.startsWith("if ! out=$(git commit --allow-empty -m ")) {
     const [message] = extractQuotedTokens(conditionLine)
     if (message !== undefined && commitAsIs(message) === block) {
-      repo.commitAsIs(message)
-      return { kind: "applied" }
+      const failure = repo.commitAsIs(message)
+      return failure === undefined
+        ? { kind: "applied" }
+        : { kind: "failed", error: failure, status: 1 }
     }
     return undefined
   }

package/src/testkit/EmittedScripts.test.ts

@@ -3,6 +3,8 @@ import {
   abandonedOutcome,
   binaryGuard,
   combinedScript,
+  commitAll,
+  commitAsIs,
   emitScripts,
   failurePromptWrapper,
   fileExistsGuard,
@@ -11,6 +13,9 @@ import {
   withFileVar,
   type EmitStep,
 } from "../emit/index.js"
+import { Effect } from "effect"
+import { ScriptSurface } from "../emit/index.js"
+import { GitService } from "../platform/index.js"
 import { gitTiers, type GitTier, type ScriptedCommand } from "./index.js"
 
 // Every case runs through real `sh` — with this build's `gtd` on PATH — and
@@ -162,5 +167,182 @@ for (const makeTier of gitTiers) {
       expect(run(script(`gtd uncheck '${review}'`)).ok).toBe(true)
       expect(read(review)).toContain("- [ ] ./src/calc.ts#1-1")
     })
+
+    // The hook output carries the marker the emitted case retries on.
+    const RETRYABLE = "rejected: empty git commit"
+
+    describe("keepTurn", () => {
+      const PREFIX = "refs/gtd/kept/entry/build.naive"
+      const MESSAGE =
+        "gtd(agent): build.naive → build.next\n\nGtd-Step: build.naive#1\nGtd-Format: 1"
+      // As a landing renders it: under `set -eu`, which a failing update-ref relies on to stop.
+      const keepTurn = (ref: string, message: string) =>
+        ScriptSurface.render([{ kind: "gitWrite", write: { kind: "keepTurn", ref, message } }])
+      const git = <A>(f: (g: GitService["Type"]) => Effect.Effect<A, Error>) =>
+        t.provide(Effect.flatMap(GitService, f))
+      const keptTip = async () => {
+        const marker = await git((g) => g.lastCommitMessage())
+        return /Gtd-Kept: ([0-9a-f]+)/.exec(marker)?.[1] ?? ""
+      }
+
+      it("keeps the turn off the branch: HEAD's tree is the pre-turn tree, the marker carries the kept tip", async () => {
+        const before = t.observe.resolveRef("HEAD")
+        t.seed.writeFile("naive.txt", "naive\n")
+        expect(run(keepTurn(PREFIX, MESSAGE))).toMatchObject({ ok: true })
+
+        expect(read("naive.txt")).toBeUndefined()
+        expect(read("readme.txt")).toBe("hello")
+        expect(t.observe.statusPorcelain()).toBe("")
+        const kept = await keptTip()
+        expect(t.observe.resolveRef(`${PREFIX}/${kept}`)).toBe(kept)
+        expect(t.observe.resolveRef(`${kept}^`)).toBe(before)
+        expect(await git((g) => g.readFileAtRef(kept, "naive.txt"))).toBe("naive\n")
+        expect(t.observe.resolveRef("HEAD^")).toBe(before)
+        expect(t.observe.headTouchedPaths()).toEqual([])
+        const marker = await git((g) => g.lastCommitMessage())
+        expect(marker.trim()).toBe(`${MESSAGE}\nGtd-Kept: ${kept}`)
+      })
+
+      it("a re-keep files a second ref and leaves the first pass's", async () => {
+        t.seed.writeFile("naive.txt", "one\n")
+        expect(run(keepTurn(PREFIX, MESSAGE)).ok).toBe(true)
+        const first = await keptTip()
+        t.seed.writeFile("naive.txt", "two\n")
+        expect(run(keepTurn(PREFIX, MESSAGE)).ok).toBe(true)
+        const second = await keptTip()
+        expect(second).not.toBe(first)
+        expect(t.observe.refExists(`${PREFIX}/${first}`)).toBe(true)
+        expect(t.observe.refExists(`${PREFIX}/${second}`)).toBe(true)
+      })
+
+      it("an unwritable ref exits non-zero with HEAD and the working tree unchanged", () => {
+        const head = t.observe.resolveRef("HEAD")
+        t.seed.writeFile("naive.txt", "naive\n")
+        const result = run(keepTurn("refs/gtd/kept/entry/bad..name", MESSAGE))
+        expect(result.ok).toBe(false)
+        expect(result.status).not.toBe(0)
+        expect(t.observe.resolveRef("HEAD")).toBe(head)
+        expect(read("naive.txt")).toBe("naive\n")
+      })
+
+      it("a staging hook does not reach the marker: HEAD's tree stays the pre-turn tree", async () => {
+        const before = t.observe.resolveRef("HEAD")
+        t.seed.stagingHook("readme.txt", "hooked")
+        t.seed.writeFile("naive.txt", "naive\n")
+        expect(run(keepTurn(PREFIX, MESSAGE))).toMatchObject({ ok: true })
+
+        expect(t.observe.headTouchedPaths()).toEqual([])
+        expect(t.observe.resolveRef("HEAD^")).toBe(before)
+        expect(read("readme.txt")).toBe("hello")
+        expect(t.observe.statusPorcelain()).toBe("")
+        const kept = await keptTip()
+        expect(t.observe.resolveRef(`${PREFIX}/${kept}`)).toBe(kept)
+        expect(t.observe.resolveRef(`${kept}^`)).toBe(before)
+        expect(await git((g) => g.readFileAtRef(kept, "readme.txt"))).toBe("hello")
+        expect(await git((g) => g.readFileAtRef(kept, "naive.txt"))).toBe("naive\n")
+      })
+
+      for (const output of ["rejected", "lint error"]) {
+        it(`a rejecting hook ("${output}") does not stop the marker`, async () => {
+          const before = t.observe.resolveRef("HEAD")
+          t.seed.rejectingHook(output)
+          t.seed.writeFile("naive.txt", "naive\n")
+          expect(run(keepTurn(PREFIX, MESSAGE))).toMatchObject({ ok: true })
+
+          const kept = await keptTip()
+          expect(kept).not.toBe("")
+          expect(t.observe.resolveRef(`${PREFIX}/${kept}`)).toBe(kept)
+          expect(t.observe.resolveRef("HEAD^")).toBe(before)
+          expect(t.observe.headTouchedPaths()).toEqual([])
+          expect(t.observe.statusPorcelain()).toBe("")
+          expect(await git((g) => g.readFileAtRef(kept, "naive.txt"))).toBe("naive\n")
+        })
+      }
+
+      it("a failing signer alone puts the turn back in the working tree and drops its kept ref", async () => {
+        const head = t.observe.resolveRef("HEAD")
+        t.seed.failingSigner()
+        t.seed.writeFile("naive.txt", "naive\n")
+        const status = t.observe.statusPorcelain()
+        const result = run(keepTurn(PREFIX, MESSAGE))
+        expect(result.ok).toBe(false)
+        expect(result.status).toBe(1)
+        expect(result.output).toContain("failed to sign")
+        expect(t.observe.statusPorcelain()).toBe(status)
+        expect(t.observe.resolveRef("HEAD")).toBe(head)
+        expect(read("naive.txt")).toBe("naive\n")
+        expect(await git((g) => g.listRefs(`${PREFIX}/`))).toEqual([])
+      })
+    })
+
+    describe("commitAll", () => {
+      it("a staging hook's edit lands in the commit", () => {
+        t.seed.stagingHook("readme.txt", "hooked")
+        t.seed.writeFile("a.txt", "a\n")
+        expect(run(commitAll("gtd(agent): building")).ok).toBe(true)
+        expect(t.observe.headTouchedPaths().toSorted()).toEqual(["a.txt", "readme.txt"])
+        expect(read("readme.txt")).toBe("hooked")
+      })
+
+      it("hook output with shell metacharacters reaches stderr verbatim", () => {
+        const output = "bad $HOME $(echo x) `id`"
+        t.seed.rejectingHook(output)
+        t.seed.writeFile("a.txt", "a\n")
+        const result = run(commitAll("gtd(agent): building"))
+        expect(result.ok).toBe(false)
+        expect(result.output).toContain(output)
+      })
+
+      it("fails with status 1 and HEAD unchanged when the commit cannot be written even without hooks", () => {
+        const head = t.observe.resolveRef("HEAD")
+        t.seed.rejectingHook(RETRYABLE)
+        t.seed.failingSigner()
+        t.seed.writeFile("a.txt", "a\n")
+        const result = run(commitAll("gtd(agent): building"))
+        expect(result.ok).toBe(false)
+        expect(result.status).toBe(1)
+        expect(result.output).toContain("failed to sign")
+        expect(t.observe.resolveRef("HEAD")).toBe(head)
+      })
+
+      it("fails with status 1 when only the signer fails, no hook having triggered the retry", () => {
+        const head = t.observe.resolveRef("HEAD")
+        t.seed.failingSigner()
+        t.seed.writeFile("a.txt", "a\n")
+        const result = run(commitAll("gtd(agent): building"))
+        expect(result.ok).toBe(false)
+        expect(result.status).toBe(1)
+        expect(result.output).toContain("failed to sign")
+        expect(t.observe.resolveRef("HEAD")).toBe(head)
+      })
+    })
+
+    describe("commitAsIs", () => {
+      it("a non-retryable hook rejection fails with status 1 and leaves HEAD and the index unchanged", () => {
+        const head = t.observe.resolveRef("HEAD")
+        t.seed.writeFile("a.txt", "a\n")
+        t.seed.stageAll()
+        t.seed.rejectingHook("rejected")
+        const staged = t.observe.statusPorcelain()
+        const result = run(commitAsIs("gtd(agent): as-is"))
+        expect(result.ok).toBe(false)
+        expect(result.status).toBe(1)
+        expect(result.output).toContain("rejected")
+        expect(t.observe.resolveRef("HEAD")).toBe(head)
+        expect(t.observe.statusPorcelain()).toBe(staged)
+      })
+
+      it("a failing signer with no hook fails with status 1 and leaves HEAD unchanged", () => {
+        const head = t.observe.resolveRef("HEAD")
+        t.seed.writeFile("a.txt", "a\n")
+        t.seed.stageAll()
+        t.seed.failingSigner()
+        const result = run(commitAsIs("gtd(agent): as-is"))
+        expect(result.ok).toBe(false)
+        expect(result.status).toBe(1)
+        expect(result.output).toContain("failed to sign")
+        expect(t.observe.resolveRef("HEAD")).toBe(head)
+      })
+    })
   })
 }

package/src/testkit/FakeGitOperations.ts

@@ -40,6 +40,8 @@ const makeGitReaderOps = (repo: InMemRepo, root: string): GitReaderOperations =>
   },
 
   readRefOption: (ref: string) => {
+    // Live `rev-parse --verify` echoes a bare 40-hex id even when no such object exists.
+    if (/^[0-9a-f]{40}$/.test(ref)) return Effect.succeed(Option.some(ref))
     const hash = repo.resolveRef(ref)
     return Effect.succeed(hash !== null ? Option.some(hash) : Option.none<string>())
   },
@@ -74,12 +76,18 @@ const makeGitReaderOps = (repo: InMemRepo, root: string): GitReaderOperations =>
     Effect.succeed(repo.subjectHistory(pageSize, skip, head)),
 
   changedPaths: (base?: string) => Effect.succeed(repo.changedPathsWorktree(base)),
+
+  diffPaths: (base: string, tip: string) => tryCatch(() => repo.diffPaths(base, tip)),
 })
 
+const failOn = (output: string | undefined): void => {
+  if (output !== undefined) throw new Error(output)
+}
+
 const makeGitWriterOps = (repo: InMemRepo): GitWriterOperations => ({
-  commitAllWithPrefix: (prefix: string) => tryCatch(() => repo.commitAllWithPrefix(prefix)),
+  commitAllWithPrefix: (prefix: string) => tryCatch(() => failOn(repo.commitAllWithPrefix(prefix))),
   softResetTo: (ref: string) => tryCatch(() => repo.softResetTo(ref)),
-  commitAsIs: (message: string) => tryCatch(() => repo.commitAsIs(message)),
+  commitAsIs: (message: string) => tryCatch(() => failOn(repo.commitAsIs(message))),
   discardPending: () => tryCatch(() => repo.discardPending()),
   updateRef: (ref: string, hash: string) => tryCatch(() => repo.updateRef(ref, hash)),
   deleteRef: (ref: string) => tryCatch(() => repo.deleteRef(ref)),