@pmelab/gtd 25.0.0 → 26.1.0

package/src/cli/Cli.test.ts

@@ -23,6 +23,7 @@ import {
   ToolCommands,
 } from "./index.js"
 import { EXIT_CODES, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
+import { Host } from "../platform/index.js"
 import { type CommandRequirements } from "./Cli.js"
 import { InMemRepo, testLayers } from "../testkit/index.js"
 import { CONFIG_SCAFFOLD } from "../install/index.js"
@@ -1164,6 +1165,30 @@ describe("runCli — layers() is never invoked for output/usage plans", () => {
   })
 })
 
+describe("runCli — a garbled GTD_FLAG_* value", () => {
+  it("exits 1 naming the variable", async () => {
+    const { io, captured } = capturingIo(
+      () =>
+        Layer.succeed(Host, {
+          root: "/",
+          home: "/",
+          scratchDir: "/",
+          realPath: (p: string) => Effect.succeed(p),
+          env: { GTD_FLAG_BETA: "ture" },
+        }) as unknown as Layer.Layer<CommandRequirements>,
+    )
+    await Effect.runPromise(
+      runCli(["node", "gtd.js", "next"], {
+        ...io,
+        flags: [{ name: "beta", owner: "pmelab", expiry: "2099-01-01", kind: "ops" }],
+      }),
+    )
+    expect(captured().exitCode).toBe(1)
+    expect(captured().stdout).toBe("")
+    expect(captured().stderr).toContain("GTD_FLAG_BETA")
+  })
+})
+
 describe("runCli — exit codes", () => {
   it("output plan: exit is never called (success) — --help and --version still exit 0", async () => {
     const { io, captured } = capturingIo(throwingLayers)
@@ -1206,7 +1231,7 @@ describe("runCli — exit codes", () => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
     repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-    repo.commitAllWithPrefix("gtd: init")
+    repo.seedCommit("gtd: init")
     const { io, captured } = capturingIo(() => testLayers(repo))
     await Effect.runPromise(runCli(["node", "gtd.js", "next", "--json=does.not.exist"], io))
     const { stdout, stderr, exitCode } = captured()
@@ -1291,7 +1316,7 @@ describe("runCli — stdout stays byte-empty on every failing surface", () => {
     // produce zero calls, not merely an empty joined string.
     const repo = new InMemRepo()
     repo.writeFile("README.md", "x\n")
-    repo.commitAllWithPrefix("chore: init gtd workflow")
+    repo.seedCommit("chore: init gtd workflow")
     repo.writeFile(".gtd/TODO.md", "## Open Questions\n\n###\n\nno question text.\n")
     const stdoutCalls: string[] = []
     const io: CliIo = {
@@ -1371,7 +1396,7 @@ describe("runCli — flush normalizes the artifact's trailing newline", () => {
     const repo = new InMemRepo()
     repo.writeFile(".gitignore", "node_modules\n")
     repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-    repo.commitAllWithPrefix("chore: initial commit")
+    repo.seedCommit("chore: initial commit")
     const { io, captured } = capturingIo(() => testLayers(repo))
     await Effect.runPromise(runCli(["node", "gtd.js", "land"], io))
     const { stdout } = captured()

package/src/cli/Cli.ts

@@ -1,6 +1,7 @@
 import { NodeContext } from "@effect/platform-node"
 import { Cause, Effect, Either, Layer } from "effect"
 import {
+  GtdError,
   GtdUsageError,
   Narrator,
   renderFailure,
@@ -9,6 +10,7 @@ import {
   Workspace,
   CommandRunner,
 } from "../platform/index.js"
+import { resolveFlags, type FlagDeclaration } from "../flags/index.js"
 import { GTD_VERSION } from "../install/index.js"
 import {
   ConfigDiscovery,
@@ -1270,6 +1272,8 @@ export interface CliIo {
    * writer when `false`.
    */
   readonly layers: (verbose: boolean) => Layer.Layer<CommandRequirements>
+  /** Test seam: the shipped registry is empty, so a garbled-value test cannot reach the failure path without injecting one. Drop it when the first real flag ships. */
+  readonly flags?: readonly FlagDeclaration[]
 }
 
 // The one write-to-stderr primitive nodeCliIo uses for both `stderr` (errors)
@@ -1403,7 +1407,14 @@ export const runCli = (argv: readonly string[], io: CliIo): Effect.Effect<void,
   }
 
   const out = bufferedArtifactOut(io)
-  return runCommand(plan.command, plan.json, out).pipe(
+  return Effect.flatMap(Host, ({ env }) =>
+    Effect.try({
+      // Validate only: the result is discarded so a garbled value fails before any command runs.
+      try: () => resolveFlags(env, io.flags),
+      catch: (e) => new GtdError((e as Error).message),
+    }),
+  ).pipe(
+    Effect.flatMap(() => runCommand(plan.command, plan.json, out)),
     // `flush()` fires here, on success, BEFORE `io.exit` — the one point
     // where the whole buffered artifact is known-complete and safe to hand
     // to stdout (a failure discards the buffer instead — see

package/src/cli/History.test.ts

@@ -36,7 +36,7 @@ const finishedProcess = async (repo: InMemRepo, file: string) => {
 const repoWithConfig = (): InMemRepo => {
   const repo = new InMemRepo()
   repo.writeFile("gtd.config.ts", CONFIG)
-  repo.commitAllWithPrefix("chore: add workflow")
+  repo.seedCommit("chore: add workflow")
   return repo
 }
 
@@ -90,7 +90,7 @@ describe("historyEntries", () => {
     const repo = repoWithConfig()
     const { entry: hash } = await finishedProcess(repo, "a.txt")
     repo.writeFile("x.txt", "x\n")
-    repo.commitAllWithPrefix("chore: bare tip")
+    repo.seedCommit("chore: bare tip")
     repo.updateRef(`refs/gtd/history/${hash}`, "HEAD")
     expect((await entries(repo))[0]?.branch).toBeNull()
   })

package/src/cli/Program.test.ts

@@ -60,7 +60,7 @@ const seed = (source: string, extra: Record<string, string> = {}): InMemRepo =>
   const repo = new InMemRepo()
   repo.writeFile("gtd.config.ts", source)
   for (const [path, content] of Object.entries(extra)) repo.writeFile(path, content)
-  repo.commitAllWithPrefix("chore: add custom workflow")
+  repo.seedCommit("chore: add custom workflow")
   return repo
 }
 
@@ -69,7 +69,7 @@ const seedBundled = (): InMemRepo => {
   const repo = new InMemRepo()
   repo.writeFile("README.md", "# test project\n")
   repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-  repo.commitAllWithPrefix("chore: init")
+  repo.seedCommit("chore: init")
   return repo
 }
 
@@ -199,7 +199,7 @@ describe("gtd --workflow <name> — the shipped workflows", () => {
     const repo = seedBundled()
     const base = repo.commitHistory().at(-1)!.hash
     repo.writeFile("scratch.txt", "more work\n")
-    repo.commitAllWithPrefix("chore: more work")
+    repo.seedCommit("chore: more work")
     const before = repo.commitHistory().length
     const { stdout, exitCode } = await run(
       repo,
@@ -288,7 +288,7 @@ describe("gtd next --json — log path emission", () => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
     repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-    repo.commitAllWithPrefix("gtd: init")
+    repo.seedCommit("gtd: init")
     return repo
   }
 
@@ -703,7 +703,7 @@ describe("gtd next — refuses when history diverges from what replay reaches",
   const diverged = async (): Promise<InMemRepo> => {
     const repo = await atWorking()
     repo.writeFile("WORK.md", "done\n")
-    repo.commitAllWithPrefix("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1")
+    repo.seedCommit("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1")
     return repo
   }
 
@@ -752,9 +752,7 @@ describe("a history written in a format this gtd does not read", () => {
     const repo = seed(IDLE_THEN_WORKING)
     await landTurn(repo, { "NOTE.md": "a note\n" })
     repo.writeFile("WORK.md", "done\n")
-    repo.commitAllWithPrefix(
-      "gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1\nGtd-Format: 2",
-    )
+    repo.seedCommit("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1\nGtd-Format: 2")
     return repo
   }
 
@@ -779,7 +777,7 @@ describe("a history written in a format this gtd does not read", () => {
   it("refuses even when a foreign subject hides the commit from the episode", async () => {
     const repo = seed(IDLE_THEN_WORKING)
     repo.writeFile("NOTE.md", "a note\n")
-    repo.commitAllWithPrefix("gtd2[human] idle -> working\n\nGtd-Format: 2")
+    repo.seedCommit("gtd2[human] idle -> working\n\nGtd-Format: 2")
     for (const command of ["next", "abandon"]) {
       const { exitCode, stderr } = await run(repo, command)
       expect(exitCode).toBe(1)
@@ -790,7 +788,7 @@ describe("a history written in a format this gtd does not read", () => {
   it("a commit gtd never wrote is not read for a format, even quoting the trailer", async () => {
     const repo = seed(IDLE_THEN_WORKING)
     repo.writeFile("NOTE.md", "a note\n")
-    repo.commitAllWithPrefix("feat: x\n\nGtd-Format: 2")
+    repo.seedCommit("feat: x\n\nGtd-Format: 2")
     expect((await run(repo, "next")).exitCode).toBe(0)
   })
 
@@ -798,7 +796,7 @@ describe("a history written in a format this gtd does not read", () => {
     const repo = seed(IDLE_THEN_WORKING)
     const base = repo.resolveRef("HEAD")!
     repo.writeFile("NOTE.md", "a note\n")
-    repo.commitAllWithPrefix("gtd(human): idle → working\n\nGtd-Step: idle#1\nGtd-Format: 2")
+    repo.seedCommit("gtd(human): idle → working\n\nGtd-Step: idle#1\nGtd-Format: 2")
     repo.updateRef(HISTORY_REF, repo.resolveRef("HEAD")!)
     repo.hardResetTo(base)
     const { exitCode, stderr } = await run(repo, "restore")
@@ -1949,7 +1947,7 @@ describe("gtd next/land --json=<path> — the select branch", () => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
     repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-    repo.commitAllWithPrefix("gtd: init")
+    repo.seedCommit("gtd: init")
     return repo
   }
 

package/src/edge/Edge.test.ts

@@ -19,7 +19,7 @@ import {
   type RestRequirements,
 } from "./Edge.js"
 import { GTD_VERSION } from "../install/index.js"
-import { processHistoryRef } from "../platform/index.js"
+import { keptRef, processHistoryRef } from "../platform/index.js"
 import { GitService, Workspace, type GitOperations, type WorkspaceOps } from "../platform/index.js"
 import { formatCommitMessage, type CommitSpec } from "../replay/index.js"
 import { contentHash } from "../workflow/index.js"
@@ -78,7 +78,7 @@ const headOf = (repo: InMemRepo): string => repo.resolveRef("HEAD")!
 const repoWith = (config: string, files: Files = {}): InMemRepo => {
   const repo = new InMemRepo()
   write(repo, { "gtd.config.ts": config, ...files })
-  repo.commitAllWithPrefix("chore: add workflow")
+  repo.seedCommit("chore: add workflow")
   return repo
 }
 
@@ -112,7 +112,7 @@ const enter = async (repo: InMemRepo, workflow: string, ...vars: string[]): Prom
 /** Commits an exact message — for trailers no landing writes on its own. */
 const commit = (repo: InMemRepo, spec: CommitSpec, files: Files = {}): string => {
   write(repo, files)
-  repo.commitAllWithPrefix(formatCommitMessage(spec))
+  repo.seedCommit(formatCommitMessage(spec))
   return headOf(repo)
 }
 
@@ -179,7 +179,7 @@ describe("currentRun", () => {
     const repo = repoWith(LINEAR)
     await land(repo, { "a.txt": "a\n" })
     repo.writeFile("b.txt", "b\n")
-    repo.commitAllWithPrefix("feat: unrelated")
+    repo.seedCommit("feat: unrelated")
     const run = await provide(currentRun, repo)
     expect(run.trace).toEqual([])
     expect(run.startParentHash).toBe(headOf(repo))
@@ -296,7 +296,7 @@ export const again = async () => {
       { "a.txt": "a\n" },
     )
     repo.writeFile("b.txt", "b\n")
-    repo.commitAllWithPrefix(
+    repo.seedCommit(
       [
         "gtd(agent): building → checking",
         "",
@@ -316,7 +316,7 @@ export const again = async () => {
     const repo = repoWith(LINEAR)
     const base = headOf(repo)
     repo.writeFile("later.txt", "later\n")
-    repo.commitAllWithPrefix("feat: later")
+    repo.seedCommit("feat: later")
     const before = headOf(repo)
     await enter(repo, "review", `base=${base}`)
     const run = await provide(currentRun, repo)
@@ -398,13 +398,13 @@ describe("history reads stay bounded by the episode, not the repository", () =>
   const repoWithHistory = (count: number): InMemRepo => {
     const repo = new InMemRepo()
     repo.writeFile("seed.txt", "0")
-    repo.commitAllWithPrefix("chore: seed 0")
+    repo.seedCommit("chore: seed 0")
     for (let i = 1; i < count; i++) {
       repo.writeFile("seed.txt", String(i))
-      repo.commitAllWithPrefix(`chore: seed ${i}`)
+      repo.seedCommit(`chore: seed ${i}`)
     }
     write(repo, { "gtd.config.ts": LINEAR })
-    repo.commitAllWithPrefix("chore: add workflow")
+    repo.seedCommit("chore: add workflow")
     return repo
   }
 
@@ -529,7 +529,7 @@ describe("summaryRun", () => {
     await land(repo, { "b.txt": "b\n" })
     await land(repo, { "c.txt": "c\n" })
     repo.writeFile("d.txt", "d\n")
-    repo.commitAllWithPrefix("chore: unrelated")
+    repo.seedCommit("chore: unrelated")
     const summary = await provide(summaryRun, repo)
     expect(summary.closingHash).toBeUndefined()
     expect(summary.trace).toEqual([])
@@ -638,7 +638,7 @@ export const base = (workflow, vars) => (workflow === "review" ? (vars.base ?? "
     const repo = repoWith(LOOP)
     const base = headOf(repo)
     repo.writeFile("later.txt", "later\n")
-    repo.commitAllWithPrefix("feat: later")
+    repo.seedCommit("feat: later")
     await enter(repo, "review", `base=${base}`)
     expect(reviewBaseFor(await provide(currentRest, repo))).toBe(base)
   })
@@ -850,7 +850,7 @@ describe("stalledAt", () => {
     const repo = repoWith(LINEAR)
     await enter(repo, "side")
     await land(repo, { "fix.txt": "x\n" })
-    repo.commitAllWithPrefix("gtd(agent): tidying")
+    repo.seedCommit("gtd(agent): tidying")
     const rest = await provide(currentRest, repo)
     expect(rest.state).toBe("tidying")
     expect(stalledAt(rest)).toBe(false)
@@ -1038,7 +1038,7 @@ describe("closedRunAt", () => {
     const tip = await land(repo, { "c.txt": "c\n" })
     const closed = await provide(closedRunAt(tip), repo)
     repo.writeFile("d.txt", "d\n")
-    repo.commitAllWithPrefix("chore: unrelated")
+    repo.seedCommit("chore: unrelated")
     const later = await provide(closedRunAt(tip), repo)
     expect(later).toEqual(closed)
     expect(later.closingHash).toBe(tip)
@@ -1146,6 +1146,103 @@ export const side = async () => {
   })
 })
 
+describe("keep steps", () => {
+  const KEEP = `import { agent, human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await agent("building", "build-prompt", { keep: true })
+  await agent("checking", "check-prompt")
+}
+`
+
+  const snapshotOf = async (repo: InMemRepo) =>
+    (await provide(snapshotFromRest(await provide(currentRest, repo)), repo)).landing
+
+  it("landing at a keep step carries keepTurn under refs/gtd/kept/<startHash>/<step>", async () => {
+    const repo = repoWith(KEEP)
+    const building = await land(repo, { "a.txt": "a\n" })
+    repo.writeFile("naive.txt", "naive\n")
+    const landing = await snapshotOf(repo)
+    if (landing.kind !== "commit") throw new Error(`expected commit, got ${landing.kind}`)
+    expect(landing.to).toBe("checking")
+    expect(landing.keepTurn).toBe(keptRef(building, "building"))
+    expect(landing.keepTurn).toBe(`refs/gtd/kept/${building}/building`)
+  })
+
+  it("a landing at a step that does not keep carries no keepTurn", async () => {
+    const repo = repoWith(KEEP)
+    repo.writeFile("a.txt", "a\n")
+    const landing = await snapshotOf(repo)
+    if (landing.kind !== "commit") throw new Error(`expected commit, got ${landing.kind}`)
+    expect(landing.keepTurn).toBeUndefined()
+  })
+
+  it("a clean tree at a keep step is still an attempt, never a keep", async () => {
+    const repo = repoWith(KEEP)
+    await land(repo, { "a.txt": "a\n" })
+    const landing = await snapshotOf(repo)
+    expect(landing.kind).toBe("attempt")
+  })
+
+  it("a marker at HEAD is not a stall: the process rests at the step after the keep", async () => {
+    const repo = repoWith(KEEP)
+    await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "naive.txt": "naive\n" })
+    expect(repo.readFile("naive.txt")).toBeUndefined()
+    expect(repo.lastCommitMessage()).toMatch(/\nGtd-Kept: [0-9a-f]{40}$/)
+    const rest = await provide(currentRest, repo)
+    expect(rest.state).toBe("checking")
+    expect(stalledAt(rest)).toBe(false)
+  })
+})
+
+describe("kept episode commits", () => {
+  const KEEP = `import { agent, human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await agent("building", "build-prompt", { keep: true })
+  await agent("checking", "check-prompt")
+}
+`
+
+  const keptRepo = async () => {
+    const repo = repoWith(KEEP)
+    await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "naive.txt": "naive\n" })
+    return repo
+  }
+
+  it("builds kept: { hash, tree } for a marker whose kept object exists", async () => {
+    const repo = await keptRepo()
+    const rest = await provide(currentRest, repo)
+    const marker = rest.setup.episode.at(-1)!
+    const hash = /Gtd-Kept: ([0-9a-f]{40})/.exec(repo.lastCommitMessage()!)![1]!
+    expect(marker.kept?.hash).toBe(hash)
+    expect(marker.kept?.tree.read("naive.txt")).toBe("naive\n")
+    expect(marker.tree.read("naive.txt")).toBeUndefined()
+  })
+
+  it("builds no kept for a marker whose kept object is missing", async () => {
+    const repo = await keptRepo()
+    const message = repo
+      .lastCommitMessage()!
+      .replace(/Gtd-Kept: [0-9a-f]{40}/, `Gtd-Kept: ${"ab".repeat(20)}`)
+    repo.hardResetTo("HEAD~1")
+    repo.commitAsIs(message)
+    const rest = await provide(currentRest, repo)
+    expect(rest.state).toBe("checking")
+    expect(rest.setup.episode.at(-1)!.kept).toBeUndefined()
+  })
+
+  it("builds no kept for a commit without the trailer", async () => {
+    const repo = await keptRepo()
+    const rest = await provide(currentRest, repo)
+    expect(rest.setup.episode.slice(0, -1).every((c) => c.kept === undefined)).toBe(true)
+  })
+})
+
 describe("historyTrail", () => {
   const finished = async (config = LINEAR) => {
     const repo = repoWith(config)
@@ -1158,7 +1255,7 @@ describe("historyTrail", () => {
   it("replays every commit of the closed run, with HEAD elsewhere", async () => {
     const { repo, building, checking, tip } = await finished()
     repo.writeFile("d.txt", "d\n")
-    repo.commitAllWithPrefix("chore: unrelated")
+    repo.seedCommit("chore: unrelated")
     const trail = await provide(historyTrail(tip), repo)
     expect(trail.tip).toBe(tip)
     expect(trail.ended).toBe("return")
@@ -1256,7 +1353,7 @@ export default async () => {
   it("refuses naming the config file that differs at the tip", async () => {
     const { repo, tip } = await finished()
     repo.writeFile("gtd.config.ts", `${LINEAR}\n// edited\n`)
-    repo.commitAllWithPrefix("chore: edit config")
+    repo.seedCommit("chore: edit config")
     const exit = await provideExit(historyTrail(tip), repo)
     expect(Exit.isFailure(exit)).toBe(true)
     expect(String(Exit.isFailure(exit) && exit.cause)).toContain("gtd.config.ts")
@@ -1266,7 +1363,7 @@ export default async () => {
     const { repo, tip } = await finished()
     repo.writeFile("gtd.config.ts", `import "./extra.ts"\n${LINEAR}`)
     repo.writeFile("extra.ts", "export {}\n")
-    repo.commitAllWithPrefix("chore: split config")
+    repo.seedCommit("chore: split config")
     const exit = await provideExit(historyTrail(tip), repo)
     expect(Exit.isFailure(exit)).toBe(true)
     expect(String(Exit.isFailure(exit) && exit.cause)).toContain("gtd.config.ts")

package/src/edge/Edge.ts

@@ -43,7 +43,7 @@ import type { ScopeAccess } from "../flows/index.js"
 import { steeringFormatFor } from "../steering/index.js"
 import { judgeJson, UNATTRIBUTED_MODEL, type ModelCost, type StepAccess } from "../wire/index.js"
 import { GTD_VERSION } from "../install/index.js"
-import { processHistoryRef } from "../platform/index.js"
+import { keptRef, processHistoryRef } from "../platform/index.js"
 import { isAbsolute, relative, resolve, sep } from "node:path"
 import { accessRefusal, type Landing, type RepoSnapshot } from "../step/index.js"
 
@@ -700,6 +700,7 @@ const promptDef = (
   ...optional("model", request.options.model),
   ...optional("system", request.options.system),
   ...optional("allowEmpty", request.options.allowEmpty),
+  ...optional("keep", request.options.keep),
   ...optional("skills", skills),
   ...optional("access", access),
 })
@@ -902,11 +903,19 @@ const setupFor = (
       run.episode.base === undefined
         ? { hash: EMPTY_TREE, tree: treeFromRecord({}) }
         : { hash: run.episode.base, tree: commitTree(workspace, run.episode.base) }
-    const episode: readonly EpisodeCommit[] = run.episode.commits.map((c) => ({
-      hash: c.hash,
-      message: c.message,
-      tree: commitTree(workspace, c.hash),
-    }))
+    const git = yield* GitService
+    const episode: EpisodeCommit[] = []
+    for (const c of run.episode.commits) {
+      const tip = parseCommitMessage(c.message).kept
+      // A plain `rev-parse --verify` of a missing 40-hex object succeeds; `^{commit}` does not.
+      const exists = tip !== undefined && Option.isSome(yield* git.readRefOption(`${tip}^{commit}`))
+      episode.push({
+        hash: c.hash,
+        message: c.message,
+        tree: commitTree(workspace, c.hash),
+        ...(exists ? { kept: { hash: tip, tree: commitTree(workspace, tip) } } : {}),
+      })
+    }
     let pendingMemo: ReadonlyMap<string, string | undefined> | undefined
     const setup: ReplaySetup = {
       def,
@@ -1167,6 +1176,12 @@ const closingTrailers = (branch: Option.Option<string>) => ({
 const isSettledNoop = (rest: Rest, to: StateName): boolean =>
   rest.changes.length === 0 && rest.stepDef.kind === "script" && to === rest.state
 
+// A clean tree has nothing to set aside (an allowEmpty keep step lands as an ordinary empty commit).
+const keptTurn = (rest: Rest) =>
+  rest.stepDef.keep === true && rest.changes.length > 0
+    ? { keepTurn: keptRef(rest.run.startHash, rest.state) }
+    : {}
+
 const landingTo = (rest: Rest, to: StateName, branch: Option.Option<string>): Landing => {
   if (isSettledNoop(rest, to)) return { kind: "noop", settled: true }
   // The landing that leaves the flow's first step starts the process: it
@@ -1191,6 +1206,7 @@ const landingTo = (rest: Rest, to: StateName, branch: Option.Option<string>): La
       ...(finishes ? closingTrailers(branch) : {}),
     },
     ...(finishes ? { keepHistory: processHistoryRef(rest.run.startHash) } : {}),
+    ...keptTurn(rest),
   }
 }
 

package/src/emit/GitScript.test.ts

@@ -1,5 +1,5 @@
 import { execFileSync, spawnSync } from "node:child_process"
-import { chmodSync, mkdtempSync, writeFileSync } from "node:fs"
+import { chmodSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { describe, expect, it } from "vitest"
@@ -11,6 +11,7 @@ import {
   discardPending,
   fetchHistoryRefs,
   hardResetTo,
+  keepTurn,
   mixedResetTo,
   pathspec,
   ScriptSurface,
@@ -61,7 +62,7 @@ const withFakeGit = (
 }
 
 const runWithFakeGit = (script: string, binDir: string): { status: number | null } =>
-  spawnSync("bash", ["-c", script], {
+  spawnSync("sh", ["-c", script], {
     env: { ...process.env, PATH: `${binDir}:${process.env["PATH"]}` },
     encoding: "utf8",
   })
@@ -74,6 +75,7 @@ const allBuilders: ReadonlyArray<[string, string]> = [
   ["hardResetTo", hardResetTo("HEAD~1")],
   ["discardPending", discardPending()],
   ["updateRef", updateRef("refs/worktree/gtd/review-head", "abc123")],
+  ["keepTurn", keepTurn("refs/gtd/kept/abc/build.naive", "gtd(agent): it's done\n\nGtd-Format: 1")],
   ["deleteRef", deleteRef("refs/worktree/gtd/review-head")],
 ]
 
@@ -285,3 +287,64 @@ describe("fetchHistoryRefs", () => {
     expect(runBashCheckSyntax(script)).toBe(0)
   })
 })
+
+describe("keepTurn", () => {
+  const block = keepTurn("refs/gtd/kept/abc/build.naive", "gtd(agent): done")
+
+  it("a branch update refused by the guard exits 1, deleting the kept ref after reset -q", () => {
+    const binDir = mkdtempSync(join(tmpdir(), "gitscript-fakebin-"))
+    const log = join(binDir, "log")
+    writeFileSync(
+      join(binDir, "git"),
+      [
+        "#!/bin/sh",
+        `echo "$*" >> '${log}'`,
+        `case "$1" in`,
+        `  rev-parse) echo head0 ;;`,
+        `  write-tree) echo tree0 ;;`,
+        `  commit-tree) echo commit0 ;;`,
+        `  config) echo false ;;`,
+        `  update-ref) [ "$2" = HEAD ] && exit 1; exit 0 ;;`,
+        `  *) exit 0 ;;`,
+        `esac`,
+      ].join("\n"),
+      { mode: 0o755 },
+    )
+    const result = runWithFakeGit(`set -eu\n${block}`, binDir)
+    expect(result.status).toBe(1)
+    const calls = readFileSync(log, "utf8").trim().split("\n")
+    expect(calls).toContain("update-ref HEAD commit0 head0")
+    const resetAt = calls.indexOf("reset -q")
+    expect(resetAt).toBeGreaterThan(-1)
+    expect(calls.slice(resetAt + 1)).toEqual([
+      "update-ref -d refs/gtd/kept/abc/build.naive/commit0",
+    ])
+    expect(calls).not.toContain("reset --hard HEAD")
+  })
+
+  it("a failed reset -q exits 1 and keeps the kept ref", () => {
+    const binDir = mkdtempSync(join(tmpdir(), "gitscript-fakebin-"))
+    const log = join(binDir, "log")
+    writeFileSync(
+      join(binDir, "git"),
+      [
+        "#!/bin/sh",
+        `echo "$*" >> '${log}'`,
+        `case "$1" in`,
+        `  rev-parse) echo head0 ;;`,
+        `  write-tree) echo tree0 ;;`,
+        `  commit-tree) echo commit0 ;;`,
+        `  config) echo false ;;`,
+        `  update-ref) [ "$2" = HEAD ] && exit 1; exit 0 ;;`,
+        `  reset) exit 1 ;;`,
+        `  *) exit 0 ;;`,
+        `esac`,
+      ].join("\n"),
+      { mode: 0o755 },
+    )
+    const result = runWithFakeGit(`set -eu\n${block}`, binDir)
+    expect(result.status).toBe(1)
+    const calls = readFileSync(log, "utf8").trim().split("\n")
+    expect(calls).not.toContain("update-ref -d refs/gtd/kept/abc/build.naive/commit0")
+  })
+})

package/src/emit/GitScript.ts

@@ -17,7 +17,7 @@ const commitAllowEmpty = (message: string): string => {
   return [
     `if ! out=$(git commit --allow-empty -m ${m} 2>&1); then`,
     `  case "$out" in`,
-    `    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m} ;;`,
+    `    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m} || exit 1 ;;`,
     `    *) printf '%s\\n' "$out" >&2; exit 1 ;;`,
     `  esac`,
     `fi`,
@@ -47,6 +47,37 @@ export const hardResetTo = (ref: string): string => `git reset --hard ${shellQuo
  */
 export const discardPending = (): string => `git add -A && git reset --hard HEAD`
 
+/**
+ * POSIX sh (runs under dash). The marker is a `commit-tree` over HEAD's own
+ * tree, so no hook runs on it and its tree is the pre-turn tree by
+ * construction; `commit-tree` ignores `commit.gpgSign`, hence the explicit
+ * `-S`, read (and failing closed) before any object or ref is written; the
+ * index is already staged by then, so an early exit leaves the turn staged.
+ * The kept ref is deleted only after `reset -q` succeeds: it is then the
+ * turn's only handle.
+ * The branch moves before the final hard reset, so if that reset fails the
+ * marker has landed and the turn is still in the working tree (kept ref
+ * present); every other failure leaves the branch untouched.
+ */
+export const keepTurn = (refPrefix: string, message: string): string => {
+  const keptRef = `${shellQuote(`${refPrefix}/`)}"$gtd_kept"`
+  return [
+    `git add -A || exit 1`,
+    `gtd_sign_cfg=$(git config --type=bool --default=false commit.gpgSign) || exit 1`,
+    `if [ "$gtd_sign_cfg" = true ]; then gtd_sign=-S; else gtd_sign=--no-gpg-sign; fi`,
+    `gtd_head=$(git rev-parse --verify HEAD) || exit 1`,
+    `gtd_tree=$(git write-tree) || exit 1`,
+    `gtd_kept=$(git commit-tree "$gtd_tree" -p "$gtd_head" -m ${shellQuote(message)}) || exit 1`,
+    `git update-ref ${keptRef} "$gtd_kept" || exit 1`,
+    `gtd_marker=$(printf '%s\\nGtd-Kept: %s' ${shellQuote(message)} "$gtd_kept")`,
+    `if ! gtd_tip=$(git commit-tree "$gtd_sign" "$gtd_head^{tree}" -p "$gtd_head" -m "$gtd_marker") || ! git update-ref HEAD "$gtd_tip" "$gtd_head"; then`,
+    `  git reset -q && git update-ref -d ${keptRef}`,
+    `  exit 1`,
+    `fi`,
+    `git reset --hard HEAD`,
+  ].join("\n")
+}
+
 export const updateRef = (ref: string, hash: string): string =>
   `git update-ref ${shellQuote(ref)} ${shellQuote(hash)}`
 
@@ -100,6 +131,8 @@ const renderGitWrite = (write: GitWrite): string => {
       return commitAll(write.message)
     case "updateRef":
       return updateRef(write.ref, write.target)
+    case "keepTurn":
+      return keepTurn(write.ref, write.message)
   }
 }
 

package/src/emit/index.ts

@@ -20,6 +20,7 @@ export {
   hardResetTo,
   discardPending,
   updateRef,
+  keepTurn,
   deleteRef,
   fetchHistoryRefs,
   type RunnableScript,