@pmelab/gtd 26.0.0 → 27.0.0

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,

package/src/flags/index.ts

@@ -11,7 +11,6 @@ export interface FlagDeclaration {
   readonly kind: FlagKind
 }
 
-// fallow-ignore-next-line unused-export
 export const FLAGS = [] as const satisfies readonly FlagDeclaration[]
 
 /** A misspelt name is a compile error. */

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/Git.test.ts

@@ -1,6 +1,12 @@
+import { execFileSync } from "node:child_process"
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { NodeContext } from "@effect/platform-node"
 import { Cause, Effect, Exit } from "effect"
 import { describe, expect, it } from "vitest"
-import { InvalidRefError, resolvedRefOrCorrupted } from "./Git.js"
+import { GitService, InvalidRefError, resolvedRefOrCorrupted } from "./Git.js"
+import { Host } from "./index.js"
 import { gitTiers, runGitServiceContract, runGitScriptContract } from "../testkit/index.js"
 
 /**
@@ -45,3 +51,92 @@ for (const makeTier of gitTiers) {
     runGitScriptContract(makeTier)
   })
 }
+
+describe("diffPaths [Live]", () => {
+  it("stays repo-root-relative with diff.relative=true and a subdirectory cwd", async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-diffpaths-")))
+    try {
+      const git = (...args: string[]) =>
+        execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: "pipe" }).trim()
+      git("init")
+      git("config", "user.email", "test@test.com")
+      git("config", "user.name", "Test")
+      git("config", "commit.gpgsign", "false")
+      git("config", "diff.relative", "true")
+      mkdirSync(join(root, "sub"))
+      writeFileSync(join(root, "sub", "a.txt"), "a")
+      writeFileSync(join(root, "top.txt"), "t")
+      git("add", "-A")
+      git("commit", "-m", "one")
+      const base = git("rev-parse", "HEAD")
+      writeFileSync(join(root, "sub", "a.txt"), "b")
+      writeFileSync(join(root, "top.txt"), "u")
+      git("add", "-A")
+      git("commit", "-m", "two")
+      const tip = git("rev-parse", "HEAD")
+      const paths = await Effect.runPromise(
+        Effect.flatMap(GitService, (g) => g.diffPaths(base, tip)).pipe(
+          Effect.provide(GitService.Live),
+          Effect.provide(Host.layer({ root: join(root, "sub"), home: root, env: {} })),
+          Effect.provide(NodeContext.layer),
+        ),
+      )
+      expect([...paths].sort()).toEqual(["sub/a.txt", "top.txt"])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  // An exported GIT_DIR/GIT_WORK_TREE would send this test's commits to the real repo;
+  // the pinned config keeps a global commit.gpgsign or missing identity from failing them.
+  const cleanEnv = {
+    ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))),
+    GIT_CONFIG_COUNT: "3",
+    GIT_CONFIG_KEY_0: "commit.gpgsign",
+    GIT_CONFIG_VALUE_0: "false",
+    GIT_CONFIG_KEY_1: "user.email",
+    GIT_CONFIG_VALUE_1: "test@test.com",
+    GIT_CONFIG_KEY_2: "user.name",
+    GIT_CONFIG_VALUE_2: "Test",
+  }
+
+  it("reports a submodule pointer bump whatever diff.ignoreSubmodules and .gitmodules ignore say", async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-diffpaths-sm-")))
+    try {
+      const run = (cwd: string, ...args: string[]) =>
+        execFileSync("git", args, { cwd, encoding: "utf8", stdio: "pipe", env: cleanEnv }).trim()
+      const source = join(root, "source")
+      const repo = join(root, "super")
+      mkdirSync(source)
+      mkdirSync(repo)
+      run(source, "init")
+      writeFileSync(join(source, "f.txt"), "1")
+      run(source, "add", "-A")
+      run(source, "commit", "-m", "s1")
+      run(repo, "init")
+      run(repo, "config", "diff.ignoreSubmodules", "all")
+      run(repo, "-c", "protocol.file.allow=always", "submodule", "add", source, "sub")
+      run(repo, "config", "-f", ".gitmodules", "submodule.sub.ignore", "all")
+      run(repo, "add", "-A")
+      run(repo, "commit", "-m", "one")
+      const base = run(repo, "rev-parse", "HEAD")
+      const clone = join(repo, "sub")
+      writeFileSync(join(clone, "f.txt"), "2")
+      run(clone, "add", "-A")
+      run(clone, "commit", "-m", "s2")
+      run(repo, "add", "--force", "sub")
+      run(repo, "commit", "-m", "two")
+      const tip = run(repo, "rev-parse", "HEAD")
+      const paths = await Effect.runPromise(
+        Effect.flatMap(GitService, (g) => g.diffPaths(base, tip)).pipe(
+          Effect.provide(GitService.Live),
+          Effect.provide(Host.layer({ root: repo, home: root, env: {} })),
+          Effect.provide(NodeContext.layer),
+        ),
+      )
+      expect([...paths]).toEqual(["sub"])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})