@pmelab/gtd 25.0.0 → 26.1.0

package/src/flags/index.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest"
+import { FLAGS, resolveFlags, type FlagDeclaration, type Flags } from "./index.js"
+
+const registry = [
+  { name: "alpha", owner: "pmelab", expiry: "2020-01-01", kind: "release" },
+  { name: "new_review", owner: "pmelab", expiry: "2099-01-01", kind: "ops" },
+] as const satisfies readonly FlagDeclaration[]
+
+describe("resolveFlags", () => {
+  it.each(["1", "true", "TRUE", "True"])("%s turns a flag on", (value) => {
+    expect(resolveFlags({ GTD_FLAG_ALPHA: value }, registry).alpha).toBe(true)
+  })
+
+  it.each(["0", "false", "FALSE"])("%s turns a flag off", (value) => {
+    expect(resolveFlags({ GTD_FLAG_ALPHA: value }, registry).alpha).toBe(false)
+  })
+
+  it("reads unset and empty as off, with every declared flag a key", () => {
+    expect(resolveFlags({ GTD_FLAG_NEW_REVIEW: "" }, registry)).toEqual({
+      alpha: false,
+      new_review: false,
+    })
+  })
+
+  it.each(["ture", "constructor", "__proto__", "toString"])(
+    "throws naming the variable, not the value %s",
+    (value) => {
+      expect(() => resolveFlags({ GTD_FLAG_NEW_REVIEW: value }, registry)).toThrow(
+        /^GTD_FLAG_NEW_REVIEW must be 1, 0, true or false$/,
+      )
+    },
+  )
+
+  it("reports the first garbled flag in registry order", () => {
+    expect(() => resolveFlags({ GTD_FLAG_NEW_REVIEW: "x", GTD_FLAG_ALPHA: "y" }, registry)).toThrow(
+      /^GTD_FLAG_ALPHA /,
+    )
+  })
+
+  it("ignores an undeclared GTD_FLAG_* key with a garbled value", () => {
+    expect(() => resolveFlags({ GTD_FLAG_NOPE: "ture" }, registry)).not.toThrow()
+  })
+
+  it("resolves a flag past its expiry like any other", () => {
+    expect(registry[0].expiry < new Date().toISOString().slice(0, 10)).toBe(true)
+    expect(resolveFlags({ GTD_FLAG_ALPHA: "1" }, registry).alpha).toBe(true)
+    expect(resolveFlags({ GTD_FLAG_ALPHA: "0" }, registry).alpha).toBe(false)
+    expect(resolveFlags({}, registry).alpha).toBe(false)
+  })
+
+  it("Flags<R> rejects a misspelt name", () => {
+    const flags: Flags<typeof registry> = resolveFlags({}, registry)
+    // @ts-expect-error misspelt flag name
+    void flags.alpah
+  })
+})
+
+describe("FLAGS", () => {
+  it("declares settable, unique variable names", () => {
+    // Vacuous while FLAGS is empty; guards the first declared flag.
+    const names = (FLAGS as readonly FlagDeclaration[]).map(({ name }) => {
+      expect(name).toMatch(/^[a-z][a-z0-9_]*$/)
+      return name
+    })
+    expect(new Set(names).size).toBe(names.length)
+  })
+})

package/src/flags/index.ts

@@ -0,0 +1,38 @@
+// A flag may change how a step runs, never which step comes next: flags are not recorded in
+// history, so replay must not read them. No lint rule enforces this.
+
+export type FlagKind = "release" | "ops" | "experiment"
+
+export interface FlagDeclaration {
+  readonly name: string
+  readonly owner: string
+  /** ISO `YYYY-MM-DD`; never enforced at runtime. */
+  readonly expiry: string
+  readonly kind: FlagKind
+}
+
+export const FLAGS = [] as const satisfies readonly FlagDeclaration[]
+
+/** A misspelt name is a compile error. */
+export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {
+  readonly [N in R[number]["name"]]: boolean
+}
+
+const BOOL: Record<string, boolean> = { "": false, "0": false, false: false, "1": true, true: true }
+
+export const resolveFlags = <const R extends readonly FlagDeclaration[] = typeof FLAGS>(
+  env: Readonly<Record<string, string | undefined>>,
+  registry: R = FLAGS as unknown as R,
+): Flags<R> => {
+  const out: Record<string, boolean> = {}
+  for (const { name } of registry) {
+    const variable = `GTD_FLAG_${name.toUpperCase()}`
+    const raw = env[variable] ?? ""
+    const key = raw.toLowerCase()
+    if (!Object.hasOwn(BOOL, key)) {
+      throw new Error(`${variable} must be 1, 0, true or false`)
+    }
+    out[name] = BOOL[key]!
+  }
+  return out as Flags<R>
+}

package/src/flows/runtime.test.ts

@@ -4,6 +4,7 @@ import {
   FlowsProtocolError,
   head,
   installContext,
+  kept,
   protocolMismatch,
   type FlowContext,
 } from "./runtime.js"
@@ -52,3 +53,35 @@ describe("the flows protocol handshake", () => {
     )
   })
 })
+
+describe("kept()", () => {
+  const change = { path: "a.ts", status: "added", before: undefined, after: "a" } as const
+  const withKept = (tip: unknown) =>
+    installContext({
+      kept: (name: string) => (name === "naive" ? tip : undefined),
+    } as unknown as FlowContext)
+
+  it("returns undefined as given", () => {
+    withKept(undefined)
+    expect(kept("naive")).toBeUndefined()
+  })
+
+  it("wraps a tip's changes with paths and get", () => {
+    withKept({ hash: "abc", changes: [change] })
+    const tip = kept("naive")
+    expect(tip?.hash).toBe("abc")
+    expect(tip?.changes.paths).toEqual(["a.ts"])
+    expect(tip?.changes.get("a.ts")?.after).toBe("a")
+    expect(tip?.changes.get("b.ts")).toBeUndefined()
+    expect(tip?.changes).toHaveLength(1)
+    expect(kept("other")).toBeUndefined()
+  })
+
+  it("throws the upgrade message on a context without kept, protocol still 1", () => {
+    installContext(context)
+    expect(() => kept("naive")).toThrow(
+      "gtd: kept() needs a newer gtd — upgrade the gtd that runs it",
+    )
+    expect(FLOWS_PROTOCOL).toBe(1)
+  })
+})

package/src/flows/runtime.ts

@@ -24,6 +24,12 @@ export interface AgentOptions extends SteeringOptions {
    * is an attempt: recorded, but the process stays at the step (a stall).
    */
   readonly allowEmpty?: boolean | undefined
+  /**
+   * Set the turn aside: its tip goes to `refs/gtd/kept/<entry>/<step>/<hash>` and the
+   * branch stays where it was, a marker commit recording that the step ran.
+   * The step's full name must be usable as a git ref component.
+   */
+  readonly keep?: boolean | undefined
 }
 
 export interface HumanOptions extends SteeringOptions {
@@ -157,6 +163,10 @@ export interface FlowContext {
   readonly skillsFor: (localName: string) => readonly string[]
   /** The folded access the memory scope `localName` lands in resolves to; `file` is the step's own steering file. */
   readonly accessFor: (localName: string, file?: string) => AccessDef
+  /** Absent on an engine older than `kept`. */
+  readonly kept?: (
+    name: string,
+  ) => { readonly hash: string; readonly changes: readonly Change[] } | undefined
 }
 
 /**
@@ -302,6 +312,27 @@ export const changesSince = (hash: string, pattern?: string): Changes => {
   )
 }
 
+export interface KeptTip {
+  /** The kept commit. `""` while the keeping turn is still pending (a landing decision): never branch on it, the landed replay sees the real hash. */
+  readonly hash: string
+  /** The kept tip against the commit it diverged from. */
+  readonly changes: Changes
+}
+
+/**
+ * The latest kept tip of step `name` (scoped from here, same as `agent()`) in
+ * this episode, or `undefined` when none.
+ */
+export const kept = (name: string): KeptTip | undefined => {
+  const context = ctx()
+  // FLOWS_PROTOCOL stays 1, so an older engine's context simply lacks `kept`.
+  if (typeof context.kept !== "function") {
+    throw new Error("gtd: kept() needs a newer gtd — upgrade the gtd that runs it")
+  }
+  const tip = context.kept(name)
+  return tip === undefined ? undefined : { hash: tip.hash, changes: toChanges(tip.changes) }
+}
+
 /** The commit the process stands on at this point of the flow. */
 export const head = (): string => ctx().head()
 

package/src/platform/RetainedHistory.test.ts

@@ -4,6 +4,7 @@ import { strictGitOperations as stubGit } from "../testkit/index.js"
 import {
   clearRetainedHistory,
   HISTORY_REF,
+  keptRef,
   PROCESS_HISTORY_PREFIX,
   processHistoryRef,
   readRetainedHistory,
@@ -77,3 +78,11 @@ describe("processHistoryRef", () => {
     expect(HISTORY_REF.startsWith(PROCESS_HISTORY_PREFIX)).toBe(false)
   })
 })
+
+describe("keptRef", () => {
+  it("keys a kept tip by entry and step, outside the finished-process namespace", () => {
+    const entry = "a".repeat(40)
+    expect(keptRef(entry, "build.naive")).toBe(`refs/gtd/kept/${entry}/build.naive`)
+    expect(keptRef(entry, "build.naive").startsWith(PROCESS_HISTORY_PREFIX)).toBe(false)
+  })
+})

package/src/platform/RetainedHistory.ts

@@ -9,6 +9,9 @@ export const PROCESS_HISTORY_PREFIX = "refs/gtd/history/"
 
 export const processHistoryRef = (hash: string): string => `${PROCESS_HISTORY_PREFIX}${hash}`
 
+/** Directory of a step's turns set aside by `keep: true`, each at `<this>/<kept hash>`; own namespace, so history list/show/fetch never see it. */
+export const keptRef = (entry: string, step: string): string => `refs/gtd/kept/${entry}/${step}`
+
 export const readRetainedHistory = (
   git: GitOperations,
 ): Effect.Effect<Option.Option<string>, Error> => git.readRefOption(HISTORY_REF)

package/src/platform/Workspace.test.ts

@@ -83,7 +83,7 @@ const makeInMemTier = (): WorkspaceTier => {
     writeWorking: (path, content) => repo.writeFile(path, content),
     commit: (path, content) => {
       repo.writeFile(path, content)
-      repo.commitAllWithPrefix(`commit ${path}`)
+      repo.seedCommit(`commit ${path}`)
     },
     provide: (eff) =>
       Effect.runPromise(eff.pipe(Effect.provide(Layer.succeed(Workspace, workspaceOps)))),

package/src/platform/index.ts

@@ -21,6 +21,7 @@ export { CommandRunner } from "./CommandRunner.js"
 export { loopLogPath } from "./WorktreeState.js"
 export {
   HISTORY_REF,
+  keptRef,
   processHistoryRef,
   PROCESS_HISTORY_PREFIX,
   readRetainedHistory,

package/src/replay/RefName.test.ts

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process"
+import { describe, expect, it } from "vitest"
+import { refNameFault } from "./RefName.js"
+
+// The predicate's owner: it must agree with git, or an invalid keep name only fails at landing.
+describe("refNameFault", () => {
+  it.each([
+    "a",
+    "a.b",
+    "build.naive",
+    "-a",
+    "ünï",
+    "a@b",
+    "a/b",
+    "a.",
+    "a//b",
+    "/a",
+    "a/",
+    "@",
+    "a@{b",
+    "a..b",
+    "a b",
+    "a~b",
+    "a^b",
+    "a:b",
+    "a?b",
+    "a*b",
+    "a[b",
+    "a\\b",
+    "a\tb",
+    ".a",
+    "a.lock",
+    "a/.b",
+    "a.lock/b",
+    "",
+  ])("agrees with git check-ref-format for %j", (name) => {
+    const git = spawnSync("git", ["check-ref-format", `refs/gtd/kept/e/${name}`])
+    expect(refNameFault(name) === undefined).toBe(git.status === 0)
+  })
+})

package/src/replay/RefName.ts

@@ -0,0 +1,19 @@
+// A kept ref is `refs/gtd/kept/<entry>/<step>`: the step's full name must survive `git check-ref-format`.
+
+// eslint-disable-next-line no-control-regex -- the control range IS the point
+const FORBIDDEN = /[\u0000- \u007f~^:?*[\\]/
+
+/** Why `name` cannot be (part of) a git ref name, or `undefined` when it can. */
+export const refNameFault = (name: string): string | undefined => {
+  if (name === "") return "it is empty"
+  if (FORBIDDEN.test(name)) return "it contains a space, control character or one of ~^:?*[\\"
+  if (name.includes("..")) return 'it contains ".."'
+  if (name.includes("@{")) return 'it contains "@{"'
+  if (name.endsWith(".")) return 'it ends with "."'
+  for (const part of name.split("/")) {
+    if (part === "") return 'it has an empty "/" component'
+    if (part.startsWith(".")) return 'a component starts with "."'
+    if (part.endsWith(".lock")) return 'a component ends with ".lock"'
+  }
+  return undefined
+}

package/src/replay/Replay.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest"
+import { beforeEach, describe, expect, it } from "vitest"
 import fc from "fast-check"
 import {
   FLOWS_PROTOCOL,
@@ -8,6 +8,7 @@ import {
   codeThreads,
   human,
   judge,
+  kept,
   read,
   refuse,
   restart,
@@ -32,6 +33,7 @@ interface Commit {
   readonly hash: string
   readonly message: string
   readonly tree: TreeView
+  readonly kept?: { readonly hash: string; readonly tree: TreeView }
 }
 
 const hashOf = (n: number): string => n.toString(16).padStart(40, "0")
@@ -64,12 +66,19 @@ class History {
     return this
   }
 
-  raw(message: string, edit: Record<string, string | null> = {}): this {
+  raw(
+    message: string,
+    edit: Record<string, string | null> = {},
+    keptTip?: { hash: string; files: Record<string, string> },
+  ): this {
     this.apply(edit)
     this.commits.push({
       hash: hashOf(this.counter++),
       message,
       tree: treeFromRecord({ ...this.files }),
+      ...(keptTip !== undefined
+        ? { kept: { hash: keptTip.hash, tree: treeFromRecord(keptTip.files) } }
+        : {}),
     })
     return this
   }
@@ -600,6 +609,188 @@ describe("replay", () => {
   })
 })
 
+describe("replay: keep", () => {
+  let seen: { read?: string | undefined; changes?: number }
+  beforeEach(() => {
+    seen = {}
+  })
+  const keepFlow =
+    (name = "naive"): Flow =>
+    async () => {
+      await human("idle")
+      await agent(name, "p", { keep: true })
+      seen.read = read("naive.txt")
+      seen.changes = changes().length
+      await human("after")
+    }
+
+  it("accepts keep as an agent option", async () => {
+    const h = new History().land("human", "idle", 1, "naive", {})
+    const outcome = await replayOf(keepFlow(), h)
+    expect(outcome.kind).toBe("rest")
+    expect(restName(outcome)).toBe("naive#1")
+  })
+
+  it("a pending turn completes the keep step but replay stays on the pre-turn tree", async () => {
+    const h = new History().land("human", "idle", 1, "naive", {})
+    const outcome = await replayOf(keepFlow(), h, { pending: { "naive.txt": "naive\n" } })
+    expect(restName(outcome)).toBe("after#1")
+    expect(outcome.kind === "rest" && outcome.landed?.name).toBe("naive")
+    expect(seen.read).toBeUndefined()
+    expect(seen.changes).toBe(0)
+  })
+
+  it("a marker commit answers its step and the next step is reached", async () => {
+    const marker = formatCommitMessage({
+      actor: "agent",
+      from: "naive",
+      to: "after",
+      step: { name: "naive", occurrence: 1 },
+    })
+    const h = new History()
+      .land("human", "idle", 1, "naive", {})
+      .raw(`${marker}\nGtd-Kept: ${hashOf(77)}`)
+    const outcome = await replayOf(keepFlow(), h)
+    expect(restName(outcome)).toBe("after#1")
+    expect(seen.read).toBeUndefined()
+    expect(seen.changes).toBe(0)
+  })
+
+  it("rejects keep together with allowEmpty", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("naive", "p", { keep: true, allowEmpty: true })
+    }
+    const h = new History().land("human", "idle", 1, "naive", {})
+    const outcome = await replayOf(flow, h)
+    expect(outcome.kind === "failed" && outcome.message).toContain("allowEmpty")
+  })
+
+  it.each(["a b", "a..b", "a~b", "a.lock", "a:b", "a/b"])(
+    "fails naming the step when %j is not a valid ref component",
+    async (name) => {
+      const h = new History().land("human", "idle", 1, name, {})
+      const outcome = await replayOf(keepFlow(name), h)
+      expect(outcome.kind).toBe("failed")
+      expect(outcome.kind === "failed" && outcome.message).toContain(`step "${name}"`)
+    },
+  )
+
+  it("does not check the name of a step that does not keep", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("a b", "p")
+    }
+    const h = new History().land("human", "idle", 1, "a b", {})
+    expect(restName(await replayOf(flow, h))).toBe("a b#1")
+  })
+})
+
+describe("replay: kept()", () => {
+  const markerFor = (name: string, to: string, occurrence = 1, tip = hashOf(77)): string =>
+    `${formatCommitMessage({
+      actor: "agent",
+      from: name,
+      to,
+      step: { name, occurrence },
+    })}\nGtd-Kept: ${tip}`
+
+  type Tip = ReturnType<typeof kept>
+  let seen: { before?: Tip; after?: Tip }
+  beforeEach(() => {
+    seen = {}
+  })
+  const flow =
+    (name = "naive"): Flow =>
+    async () => {
+      await human("idle")
+      seen.before = kept(name)
+      await agent("naive", "p", { keep: true })
+      seen.after = kept(name)
+      await human("after")
+    }
+
+  it("returns the newest consumed marker's hash and its diff against the marker's tree", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "naive", { "base.txt": "b\n" })
+      .raw(
+        markerFor("naive", "after"),
+        {},
+        { hash: hashOf(77), files: { "base.txt": "b\n", "naive.ts": "export const n = 1\n" } },
+      )
+    const outcome = await replayOf(flow(), h)
+    expect(restName(outcome)).toBe("after#1")
+    expect(seen.after?.hash).toBe(hashOf(77))
+    expect(seen.after?.changes.map((c) => [c.path, c.status, c.after])).toEqual([
+      ["naive.ts", "added", "export const n = 1\n"],
+    ])
+  })
+
+  it("the newest of two passes wins", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "naive", {})
+      .raw(markerFor("naive", "naive", 1, hashOf(70)), {}, { hash: hashOf(70), files: { a: "1" } })
+      .raw(markerFor("naive", "after", 2, hashOf(71)), {}, { hash: hashOf(71), files: { a: "2" } })
+    const twice: Flow = async () => {
+      await human("idle")
+      await agent("naive", "p", { keep: true })
+      await agent("naive", "p", { keep: true })
+      seen.after = kept("naive")
+      await human("after")
+    }
+    await replayOf(twice, h)
+    expect(seen.after?.hash).toBe(hashOf(71))
+    expect(seen.after?.changes.get("a")?.after).toBe("2")
+  })
+
+  it("is undefined for a step that never kept", async () => {
+    const h = new History().land("human", "idle", 1, "naive", {}).land("agent", "naive", 1, "after")
+    expect(restName(await replayOf(flow(), h))).toBe("after#1")
+    expect(seen.after).toBeUndefined()
+  })
+
+  it("is undefined when the marker's kept object is gone", async () => {
+    const h = new History().land("human", "idle", 1, "naive", {}).raw(markerFor("naive", "after"))
+    expect(restName(await replayOf(flow(), h))).toBe("after#1")
+    expect(seen.after).toBeUndefined()
+  })
+
+  it("resolves the name through scope() like agent()", async () => {
+    const scoped: Flow = async () => {
+      await human("idle")
+      await scope("build", async () => {
+        await agent("naive", "p", { keep: true })
+        seen.after = kept("naive")
+      })
+      seen.before = kept("naive")
+      await human("after")
+    }
+    const h = new History()
+      .land("human", "idle", 1, "build.naive", {})
+      .raw(markerFor("build.naive", "after"), {}, { hash: hashOf(77), files: { "x.ts": "x" } })
+    await replayOf(scoped, h)
+    expect(seen.after?.hash).toBe(hashOf(77))
+    expect(seen.before).toBeUndefined()
+  })
+
+  it('shows the pending tip with hash "" during the landing decision', async () => {
+    const h = new History().land("human", "idle", 1, "naive", {})
+    const outcome = await replayOf(flow(), h, { pending: { "naive.ts": "n\n" } })
+    expect(restName(outcome)).toBe("after#1")
+    expect(seen.after?.hash).toBe("")
+    expect(seen.after?.changes.map((c) => [c.path, c.status])).toEqual([["naive.ts", "added"]])
+  })
+
+  it("does not show a marker the flow has not consumed yet", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "naive", {})
+      .raw(markerFor("naive", "after"), {}, { hash: hashOf(77), files: { "x.ts": "x" } })
+    await replayOf(flow(), h)
+    expect(seen.before).toBeUndefined()
+    expect(seen.after?.hash).toBe(hashOf(77))
+  })
+})
+
 describe("replay: skills resolution", () => {
   interface Tiers {
     skills?: Record<string, readonly string[]>

package/src/replay/Replay.ts

@@ -21,6 +21,7 @@ import {
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
 import { globMatches } from "../wire/index.js"
+import { refNameFault } from "./RefName.js"
 import { diffTrees, isEmptyDiff, type TreeView } from "./Tree.js"
 import {
   formatStepId,
@@ -34,6 +35,8 @@ export interface EpisodeCommit {
   readonly hash: string
   readonly message: string
   readonly tree: TreeView
+  /** Present when the commit carries Gtd-Kept and that object still exists. */
+  readonly kept?: { readonly hash: string; readonly tree: TreeView }
 }
 
 /**
@@ -232,7 +235,7 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 // The option keys each step accepts. A gtd.config.ts is evaluated without a
 // type check, so a misspelt key would otherwise be silently ignored.
 const KNOWN_OPTIONS: Readonly<Record<StepKind, ReadonlySet<string>>> = {
-  agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty"]),
+  agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty", "keep"]),
   human: new Set([...STEERING_OPTIONS, "message", "acceptClean"]),
   run: new Set(STEERING_OPTIONS),
   judge: new Set([...STEERING_OPTIONS, "message"]),
@@ -275,6 +278,11 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   const scopeCallIds: number[] = []
   let scopeCallCount = 0
   const trace: ReachedStep[] = []
+  // Newest consumed keep per scoped step name; `before` is the tree the kept turn diverged from.
+  const keptTips = new Map<
+    string,
+    { readonly hash: string; readonly before: TreeView; readonly after: TreeView }
+  >()
   let landed: ReachedStep | undefined
   let outcome: ReplayOutcome | undefined
   let signal: (() => void) | undefined
@@ -494,11 +502,32 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     }
     cursor++
     advance(commit)
+    if (commit.parsed.kept !== undefined) {
+      if (commit.kept === undefined) keptTips.delete(step.name)
+      else
+        keptTips.set(step.name, {
+          hash: commit.kept.hash,
+          before: commit.tree,
+          after: commit.kept.tree,
+        })
+    }
     const to = commit.parsed.parsed?.to
     if (to !== undefined) expectedNext = { name: to, hash: commit.hash }
     return replyFor(step.request, commit.parsed.judge)
   }
 
+  const landPending = (step: ReachedStep, pending: NonNullable<typeof input.pending>): unknown => {
+    pendingUsed = true
+    landed = step
+    // A kept turn is set aside: replay stays on the pre-turn tree, as it will once the marker lands.
+    const keeping = step.request.kind === "agent" && step.request.options.keep === true
+    if (keeping) {
+      keptTips.set(step.name, { hash: "", before: position.tree, after: pending.tree })
+    }
+    advance({ hash: "", tree: keeping ? position.tree : pending.tree })
+    return replyFor(step.request, pending.verdicts ?? [])
+  }
+
   const answer = (step: ReachedStep): unknown => {
     while (cursor < commits.length && isAttemptAt(commits[cursor]!, step.name)) cursor++
     const commit = commits[cursor]
@@ -506,10 +535,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     if (input.pending === undefined || pendingUsed) {
       return finish({ kind: "rest", rest: step, trace, landed })
     }
-    pendingUsed = true
-    landed = step
-    advance({ hash: "", tree: input.pending.tree })
-    return replyFor(step.request, input.pending.verdicts ?? [])
+    return landPending(step, input.pending)
   }
 
   // gtd.config.ts is loaded without a type check.
@@ -517,7 +543,20 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     if (request.kind === "run" && typeof request.body !== "string") {
       return `gtd: step "${scoped(request.name)}": a run() body is a shell script string — decide in flow code, then render the script (see checkScript and friends)`
     }
-    return request.kind === "agent" ? scopeAccessFault() : undefined
+    if (request.kind !== "agent") return undefined
+    const name = scoped(request.name)
+    if (request.options.keep === true) {
+      // A clean allowEmpty keep would land an ordinary commit with no Gtd-Kept: a silent skip.
+      if (request.options.allowEmpty === true) {
+        return `gtd: step "${name}": keep: true cannot be combined with allowEmpty — a turn that changes nothing has nothing to keep`
+      }
+      // "/" would let one step's ref directory collide with another step's ref (git refuses `a` and `a/b` together).
+      const refFault = name.includes("/") ? 'it contains "/"' : refNameFault(name)
+      if (refFault !== undefined) {
+        return `gtd: step "${name}": keep: true files the turn under a git ref named after the step, but ${refFault}`
+      }
+    }
+    return scopeAccessFault()
   }
 
   const handleStep = async (request: StepRequest): Promise<unknown> => {
@@ -611,6 +650,12 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
               .map((f) => f.message),
           }))
         }),
+    kept: (name) => {
+      const tip = keptTips.get(scoped(name))
+      return tip === undefined
+        ? undefined
+        : { hash: tip.hash, changes: changesBetween(tip.before, tip.after) }
+    },
     vars: input.vars,
     env: input.env,
     start: () => input.start,