@pmelab/gtd 60.1.0 → 61.0.0

package/dist/testkit/gherkin.mjs

@@ -1,4 +1,4 @@
-import { n as runsItsScript, r as testRepo } from "../chunks/testkit-BhTey1Do.mjs";
+import { n as runsItsScript, r as testRepo } from "../chunks/testkit-C9sq0x07.mjs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { After, AfterAll, Given, QuickPickleWorld, Then, When, setWorldConstructor } from "quickpickle";

package/dist/testkit.mjs

@@ -1,3 +1,3 @@
 import { H as installContext } from "./chunks/flows-DENt0uWV.mjs";
-import { a as verdictWhen, i as verdict, n as runsItsScript, o as whenPrompted, r as testRepo, t as inTurn } from "./chunks/testkit-BhTey1Do.mjs";
+import { a as verdictWhen, i as verdict, n as runsItsScript, o as whenPrompted, r as testRepo, t as inTurn } from "./chunks/testkit-C9sq0x07.mjs";
 export { inTurn, installContext, runsItsScript, testRepo, verdict, verdictWhen, whenPrompted };

package/dist/wire.mjs

@@ -1,2 +1,2 @@
-import { A as WIRE_SCHEMA, C as EXIT_RUNTIME_ERROR, D as EXIT_USAGE_ERROR, E as EXIT_STRAYS_FOUND, O as ACCESS_REFUSAL, S as EXIT_OK, T as EXIT_SIGTERM, _ as BEAT_KINDS, a as renderScriptJson, b as stallDiagnosis, c as landProseText, d as renderLandPlain, f as DEMAND_BRIEFING, g as statusOf, h as renderBeatJson, i as judgeJson, j as renderFormat, k as UNATTRIBUTED_MODEL, l as noopText, m as beatDocument, n as resolveSession, o as scriptFields, p as renderBeatPlain, r as selectPath, s as landFields, t as globMatches, u as renderLandJson, v as beatKindOf, w as EXIT_SIGINT, x as EXIT_CODES, y as demandOf } from "./chunks/wire-DZ8R1RU9.mjs";
-export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_STRAYS_FOUND, EXIT_USAGE_ERROR, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, renderScriptJson, resolveSession, scriptFields, selectPath, stallDiagnosis, statusOf };
+import { A as UNATTRIBUTED_MODEL, C as EXIT_RUNTIME_ERROR, D as EXIT_USAGE_ERROR, E as EXIT_STRAYS_FOUND, M as renderFormat, O as ACCESS_REFUSAL, S as EXIT_OK, T as EXIT_SIGTERM, _ as BEAT_KINDS, a as renderScriptJson, b as stallDiagnosis, c as landProseText, d as renderLandPlain, f as DEMAND_BRIEFING, g as statusOf, h as renderBeatJson, i as judgeJson, j as WIRE_SCHEMA, k as PIN_PATH, l as noopText, m as beatDocument, n as resolveSession, o as scriptFields, p as renderBeatPlain, r as selectPath, s as landFields, t as globMatches, u as renderLandJson, v as beatKindOf, w as EXIT_SIGINT, x as EXIT_CODES, y as demandOf } from "./chunks/wire-CPNSm_9N.mjs";
+export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_STRAYS_FOUND, EXIT_USAGE_ERROR, PIN_PATH, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, renderScriptJson, resolveSession, scriptFields, selectPath, stallDiagnosis, statusOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "60.1.0",
+  "version": "61.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/cli/History.test.ts

@@ -1,6 +1,12 @@
 import { Effect, Exit } from "effect"
 import { describe, expect, it } from "vitest"
-import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
+import {
+  applyEmittedScript,
+  InMemRepo,
+  makeCapturingCliIo,
+  takePinBeat,
+  testLayers,
+} from "../twins/index.js"
 import { runCli } from "./index.js"
 import { historyEntries, resolveHistoryRef, type HistoryEntry } from "./History.js"
 
@@ -12,7 +18,9 @@ export default async () => {
 }
 `
 
+/** Lands `files` as one turn, taking a pin beat before it and an unpin beat after it as a driver does. */
 const land = async (repo: InMemRepo, files: Record<string, string>): Promise<string> => {
+  await takePinBeat(repo, "add")
   for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
   const { io, result } = makeCapturingCliIo(repo)
   await Effect.runPromise(runCli(["node", "gtd.js", "land", "--json"], io))
@@ -24,6 +32,7 @@ const land = async (repo: InMemRepo, files: Record<string, string>): Promise<str
     (JSON.parse(stdout) as { script: string }).script,
   )
   if (!outcome.ok) throw new Error(outcome.error)
+  await takePinBeat(repo, "remove")
   return repo.resolveRef("HEAD")!
 }
 

package/src/cli/Metrics.test.ts

@@ -1,6 +1,12 @@
 import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
-import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
+import {
+  applyEmittedScript,
+  InMemRepo,
+  makeCapturingCliIo,
+  takePinBeat,
+  testLayers,
+} from "../twins/index.js"
 import { runCli } from "./index.js"
 import { processMetrics, readProcessMetrics, totalMetrics, type MetricCommit } from "./Metrics.js"
 
@@ -213,7 +219,9 @@ export default async () => {
 }
 `
 
+/** Lands `files` as one turn, taking a pin beat before it and an unpin beat after it as a driver does. */
 const land = async (repo: InMemRepo, files: Record<string, string>): Promise<string> => {
+  await takePinBeat(repo, "add")
   for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
   const { io, result } = makeCapturingCliIo(repo)
   await Effect.runPromise(runCli(["node", "gtd.js", "land", "--json"], io))
@@ -225,6 +233,7 @@ const land = async (repo: InMemRepo, files: Record<string, string>): Promise<str
     (JSON.parse(stdout) as { script: string }).script,
   )
   if (!outcome.ok) throw new Error(outcome.error)
+  await takePinBeat(repo, "remove")
   return repo.resolveRef("HEAD")!
 }
 

package/src/cli/Program.test.ts

@@ -18,7 +18,13 @@ vi.mock("node:os", async (importOriginal) => ({
 import { runCli, type Command } from "./index.js"
 import { EXIT_USAGE_ERROR, stallDiagnosis, noopText, WIRE_SCHEMA } from "../wire/index.js"
 import { needsOf, runCommand, SelectorUsageError, type CommandRequirements } from "./Program.js"
-import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../twins/index.js"
+import {
+  InMemRepo,
+  makeCapturingCliIo,
+  testLayers,
+  applyEmittedScript,
+  takePinBeat,
+} from "../twins/index.js"
 import {
   commitAll,
   DID_NOT_RUN_COMMENT,
@@ -39,13 +45,14 @@ const run = async (
   return result()
 }
 
-/** Lands via `gtd land --json` and applies the emitted script, as a driver would. */
+/** Lands via `gtd land --json` and applies the emitted script, then takes the pin or unpin beat it leads to, as a driver would. */
 const landAndApply = async (
   repo: InMemRepo,
 ): Promise<{ readonly exitCode: number; readonly script: string }> => {
   const { stdout, exitCode } = await run(repo, "land", "--json")
   const script = exitCode === 0 ? (JSON.parse(stdout) as { readonly script: string }).script : ""
   if (exitCode === 0) expect(applyEmittedScript(repo, new Map(), script).ok).toBe(true)
+  if (exitCode === 0) await takePinBeat(repo)
   return { exitCode, script }
 }
 
@@ -104,7 +111,7 @@ export const hotfix = workflow(
     expect(exitCode).toBe(0)
     expect(stdout).toContain(
       commitAll(
-        `gtd(human): working\n\nGtd-Workflow: hotfix\nGtd-Var: greeting=hello\nGtd-Config: ${contentHash(WORKFLOW)} gtd.config.ts\nGtd-Format: 1`,
+        `gtd(human): working\n\nGtd-Workflow: hotfix\nGtd-Var: greeting=hello\nGtd-Config: ${contentHash(WORKFLOW)} gtd.config.ts\nGtd-Format: 2`,
       ),
     )
     expect(repo.commitHistory()).toHaveLength(before)
@@ -190,6 +197,9 @@ export const hotfix = workflow(
     const { stdout } = await run(repo, "start", "hotfix")
     expect(applyEmittedScript(repo, new Map(), stdout).ok).toBe(true)
     expect(repo.lastCommitSubject()).toBe("gtd(human): working")
+    const pin = JSON.parse((await run(repo, "next", "--json")).stdout) as Record<string, unknown>
+    expect(pin).toMatchObject({ kind: "script", state: "pin", actor: "check", pin: "add" })
+    expect(await takePinBeat(repo, "add")).toBe(true)
     const next = JSON.parse((await run(repo, "next", "--json")).stdout) as Record<string, unknown>
     expect(next.kind).toBe("prompt")
     expect(next.state).toBe("working")
@@ -496,6 +506,7 @@ export const resume = workflow(work)
     const repo = seed(WORKFLOW)
     const { stdout: entry } = await run(repo, "start", "resume")
     expect(applyEmittedScript(repo, new Map(), entry).ok).toBe(true)
+    await takePinBeat(repo, "add")
     const { stdout, exitCode } = await run(repo, "next", "--json")
     expect(exitCode).toBe(0)
     expect(JSON.parse(stdout).kind).toBe("prompt")
@@ -775,20 +786,20 @@ describe("gtd next — refuses when history diverges from what replay reaches",
     expect(repo.commitHistory()).toHaveLength(before)
 
     expect(applyEmittedScript(repo, new Map(), stdout).ok).toBe(true)
-    expect(repo.commitHistory()).toHaveLength(before - 2)
+    expect(repo.commitHistory()).toHaveLength(before - 3)
   })
 })
 
 describe("a history written in a format this gtd does not read", () => {
   // The exact wording is pinned in Format.test.ts; this is the part that proves the format gate fired.
-  const FOREIGN = "is written in history format 2, but this gtd reads format 1"
+  const FOREIGN = "is written in history format 3, but this gtd reads formats 1 to 2"
 
   /** A step commit that would also diverge, so only the format gate can explain the refusal. */
   const foreignStep = async (): Promise<InMemRepo> => {
     const repo = seed(IDLE_THEN_WORKING)
     await landTurn(repo, { "NOTE.md": "a note\n" })
     repo.writeFile("WORK.md", "done\n")
-    repo.seedCommit("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: 3")
     return repo
   }
 
@@ -813,7 +824,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.seedCommit("gtd2[human] idle -> working\n\nGtd-Format: 2")
+    repo.seedCommit("gtd2[human] idle -> working\n\nGtd-Format: 3")
     for (const command of ["next", "abandon"]) {
       const { exitCode, stderr } = await run(repo, command)
       expect(exitCode).toBe(1)
@@ -824,7 +835,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.seedCommit("feat: x\n\nGtd-Format: 2")
+    repo.seedCommit("feat: x\n\nGtd-Format: 3")
     expect((await run(repo, "next")).exitCode).toBe(0)
   })
 
@@ -832,7 +843,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.seedCommit("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: 3")
     repo.updateRef(HISTORY_REF, repo.resolveRef("HEAD")!)
     repo.hardResetTo(base)
     const { exitCode, stderr } = await run(repo, "restore")
@@ -1390,10 +1401,10 @@ export default async () => {
     expect(await nextOf(repo)).toEqual({ target: "accepted" })
   })
 
-  it("a turn that finishes the flow targets the initial step", async () => {
+  it("a turn that finishes a pinned flow targets the unpin", async () => {
     const repo = await atWorking()
     repo.writeFile("REVIEW.md", "an updated review\n")
-    expect(await nextOf(repo)).toMatchObject({ target: "idle" })
+    expect(await nextOf(repo)).toMatchObject({ target: "unpin" })
   })
 
   it("plain gtd next shows the same preview as a `Next:` line", async () => {
@@ -1476,7 +1487,7 @@ export default async () => {
     expect((JSON.parse(stdout) as { readonly script: string }).script).toContain("git commit")
   })
 
-  it("a clean run that finishes the flow lands an ordinary commit re-entering the initial step", async () => {
+  it("a clean run that finishes a pinned flow lands an ordinary commit at the unpin", async () => {
     const repo = await atChecking(REENTRY_WORKFLOW)
     const { stdout, exitCode } = await run(repo, "land", "--json")
     expect(exitCode).toBe(0)
@@ -1485,7 +1496,7 @@ export default async () => {
     expect(script).not.toContain("git reset --mixed")
     expect(script).not.toContain("nothing to retain")
     expect(applyEmittedScript(repo, new Map(), script).ok).toBe(true)
-    expect(repo.lastCommitSubject()).toBe("gtd(check): checking → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): checking → unpin")
   })
 
   it("the same rest with a pending change lands an ordinary commit too", async () => {
@@ -1523,7 +1534,7 @@ export default async () => {
     expect(parsed.script).toContain("nothing to do")
   })
 
-  it("gtd land --json a decision that re-enters the initial step reports settled:false, idle:true, state:idle", async () => {
+  it("gtd land --json a decision that ends a pinned flow reports settled:false, idle:false, state:unpin", async () => {
     const repo = await atChecking(REENTRY_WORKFLOW)
     const { stdout, exitCode } = await run(repo, "land", "--json")
     expect(exitCode).toBe(0)
@@ -1533,8 +1544,8 @@ export default async () => {
       readonly state: string
     }
     expect(parsed.settled).toBe(false)
-    expect(parsed.idle).toBe(true)
-    expect(parsed.state).toBe("idle")
+    expect(parsed.idle).toBe(false)
+    expect(parsed.state).toBe("unpin")
   })
 
   it("gtd land --json an ordinary commit reports settled:false", async () => {
@@ -1683,7 +1694,7 @@ export default async () => {
     const { exitCode, script } = await landAndApply(repo)
     expect(exitCode).toBe(0)
     expect(script).not.toContain("fmt-notes")
-    expect(repo.lastCommitSubject()).toBe("gtd(agent): drafting → idle")
+    expect(repo.lastCommitSubject("HEAD~1")).toBe("gtd(agent): drafting → unpin")
   })
 
   it("`gtd next --json`'s `validate` field carries the mode's format command", async () => {
@@ -1867,7 +1878,7 @@ export default workflow(
   it("writes the rendered summary, with a trailing newline, counting the human turns after the entry commit", async () => {
     const repo = await reviewed()
     const history = repo.commitHistory()
-    const entryHash = history[history.length - 3]!.hash
+    const entryHash = history[history.length - 4]!.hash
     const tipHash = history[history.length - 1]!.hash
 
     const { exitCode, stdout } = await run(repo, "summary")
@@ -1961,7 +1972,7 @@ export default async () => {
   it("refuses once the process has closed and HEAD rests at the initial step again", async () => {
     const repo = await atDeciding()
     await landTurn(repo)
-    expect(repo.lastCommitSubject()).toBe("gtd(human): deciding → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): unpin → idle")
 
     const { exitCode, stdout, stderr } = await run(repo, "base")
     expect(exitCode).toBe(1)

package/src/cli/Program.ts

@@ -47,6 +47,7 @@ import {
   type StatusChange,
   selectPath,
   EXIT_OK,
+  PIN_PATH,
 } from "../wire/index.js"
 import {
   currentRest,
@@ -80,6 +81,7 @@ import {
   deleteRef,
   hardResetTo,
   mixedResetTo,
+  unpinScript,
   ScriptSurface,
   updateRef,
   type RunnableScript,
@@ -799,6 +801,7 @@ const runAbandonCommand = (
     const steps: EmitStep[] = [
       { kind: "gitWrite", command: updateRef(HISTORY_REF, tip) },
       { kind: "gitWrite", command: mixedResetTo(run.startParentHash) },
+      { kind: "gitWrite", command: unpinScript(PIN_PATH) },
       { kind: "outcome", command: abandonedOutcome(restState, run.startParentHash, initial) },
     ]
     const required = emitScripts(steps).required
@@ -1060,7 +1063,7 @@ const runCodeThreadsCheckCommand = (): Effect.Effect<void, Error, CommandRequire
     const workspace = yield* Workspace
     const changed = yield* git.changedPaths(rest.run.diffBase)
     const lines = changed
-      .filter((c) => c.status !== "D")
+      .filter((c) => c.status !== "D" && c.path !== PIN_PATH)
       .flatMap(({ path }) => {
         const { threads, findings } = parseCodeThreads(path, workspace.atPath(path) ?? "")
         return [

package/src/cli/Strays.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect"
 import { GitService, GtdError, Narrator, type GitOperations } from "../platform/index.js"
 import { strayPaths } from "../step/index.js"
-import { EXIT_OK, EXIT_STRAYS_FOUND } from "../wire/index.js"
+import { EXIT_OK, EXIT_STRAYS_FOUND, PIN_PATH } from "../wire/index.js"
 import {
   SelectorUsageError,
   writeSelection,
@@ -31,7 +31,8 @@ export const runStraysCommand = (
     const narrator = yield* Narrator
     const base = yield* resolveSide(git, command.base)
     const tip = yield* resolveSide(git, command.tip)
-    const touched = yield* git.diffPaths(base, tip)
+    // The pin is the engine's, never a turn's, so it is never a stray either.
+    const touched = (yield* git.diffPaths(base, tip)).filter((path) => path !== PIN_PATH)
     const strays = strayPaths(touched, command.globs)
     const total = touched.length
 

package/src/edge/Edge.test.ts

@@ -30,6 +30,7 @@ import {
   applyEmittedScript,
   makeCapturingCliIo,
   makeInMemoryWorkspaceOps,
+  takePinBeat,
   testLayers,
 } from "../twins/index.js"
 
@@ -74,7 +75,7 @@ const write = (repo: InMemRepo, files: Files): void => {
   for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
 }
 
-const headOf = (repo: InMemRepo): string => repo.resolveRef("HEAD")!
+const headOf = (repo: InMemRepo, ref = "HEAD"): string => repo.resolveRef(ref)!
 
 const repoWith = (config: string, files: Files = {}): InMemRepo => {
   const repo = new InMemRepo()
@@ -95,19 +96,27 @@ const applied = (repo: InMemRepo, script: string): string => {
   return headOf(repo)
 }
 
-/** Lands the pending turn the way a driver does — `gtd land --json`, then its script — and returns the new HEAD. */
+/**
+ * Lands the pending turn the way a driver does — `gtd land --json`, then its
+ * script, then the pin or unpin beat it leads to — and returns the turn's
+ * commit, or the closing commit when the turn led to the unpin.
+ */
 const land = async (repo: InMemRepo, files: Files = {}): Promise<string> => {
   write(repo, files)
   const { stdout, stderr, exitCode } = await cli(repo, "land", "--json")
   if (exitCode !== 0) throw new Error(`gtd land exited ${exitCode}: ${stderr}${stdout}`)
-  return applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+  const turn = applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+  await takePinBeat(repo, "add")
+  return (await takePinBeat(repo, "remove")) ? headOf(repo) : turn
 }
 
 const enter = async (repo: InMemRepo, workflow: string, ...vars: string[]): Promise<string> => {
   const flags = vars.flatMap((v) => ["--var", v])
   const { stdout, stderr, exitCode } = await cli(repo, "start", workflow, ...flags)
   if (exitCode !== 0) throw new Error(`gtd start exited ${exitCode}: ${stderr}`)
-  return applied(repo, stdout)
+  const opening = applied(repo, stdout)
+  await takePinBeat(repo, "add")
+  return opening
 }
 
 /** Commits an exact message — for trailers no landing writes on its own. */
@@ -174,7 +183,11 @@ describe("currentRun", () => {
       { state: "checking", hash: checking, actor: "agent" },
     ])
     expect(run.episode.base).toBe(boundary)
-    expect(run.episode.commits.map((c) => c.hash)).toEqual([building, checking])
+    expect(run.episode.commits.map((c) => c.message.split("\n")[0])).toEqual([
+      "gtd(human): idle → building",
+      "gtd(check): pin → building",
+      "gtd(agent): building → checking",
+    ])
   })
 
   it("a non-gtd commit on top of a process bounds a fresh episode", async () => {
@@ -192,7 +205,7 @@ describe("currentRun", () => {
     await land(repo, { "a.txt": "a\n" })
     await land(repo, { "b.txt": "b\n" })
     const closing = await land(repo, { "c.txt": "c\n" })
-    expect(repo.lastCommitSubject()).toBe("gtd(agent): checking → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): unpin → idle")
     const next = await land(repo, { "d.txt": "d\n" })
     const run = await provide(currentRun, repo)
     expect(run.startParentHash).toBe(closing)
@@ -203,8 +216,8 @@ describe("currentRun", () => {
     const repo = repoWith(LINEAR)
     const before = headOf(repo)
     const opening = await enter(repo, "side")
-    expect(repo.lastCommitMessage()).toBe(
-      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Config: ${contentHash(LINEAR)} gtd.config.ts\nGtd-Format: 1`,
+    expect(repo.lastCommitMessage(opening)).toBe(
+      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Config: ${contentHash(LINEAR)} gtd.config.ts\nGtd-Format: 2`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -216,7 +229,7 @@ describe("currentRun", () => {
       { state: "tidying", hash: fixed, actor: "agent" },
     ])
     expect(run.episode.base).toBe(opening)
-    expect(run.episode.commits.map((c) => c.hash)).toEqual([fixed])
+    expect(run.episode.commits.map((c) => c.hash)).toEqual([headOf(repo, `${fixed}~1`), fixed])
   })
 
   it("a workflow starting at the default's initial step still opens its own episode, not the empty tree", async () => {
@@ -236,8 +249,8 @@ export const again = workflow(async () => {
     const repo = repoWith(STARTS_AT_INITIAL)
     const before = headOf(repo)
     const opening = await enter(repo, "again")
-    expect(repo.lastCommitMessage()).toBe(
-      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Config: ${contentHash(STARTS_AT_INITIAL)} gtd.config.ts\nGtd-Format: 1`,
+    expect(repo.lastCommitMessage(opening)).toBe(
+      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Config: ${contentHash(STARTS_AT_INITIAL)} gtd.config.ts\nGtd-Format: 2`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -374,15 +387,23 @@ export const again = workflow(async () => {
     it("describes a step commit that changed something", async () => {
       const repo = repoWith(LINEAR)
       await land(repo, { "a.txt": "a\n" })
+      await land(repo, { "b.txt": "b\n" })
       const run = await provide(currentRun, repo)
-      expect(run.headTurn).toEqual({ state: "building", actor: "human", empty: false, step: true })
+      expect(run.headTurn).toEqual({ state: "checking", actor: "agent", empty: false, step: true })
+    })
+
+    it("is undefined at a pin commit, which is no turn", async () => {
+      const repo = repoWith(LINEAR)
+      await land(repo, { "a.txt": "a\n" })
+      expect(repo.lastCommitSubject()).toBe("gtd(check): pin → building")
+      expect((await provide(currentRun, repo)).headTurn).toBeUndefined()
     })
 
     it("describes an attempt: a step-less, empty commit", async () => {
       const repo = repoWith(LINEAR)
       await land(repo, { "a.txt": "a\n" })
       await land(repo)
-      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 1")
+      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 2")
       const run = await provide(currentRun, repo)
       expect(run.headTurn).toEqual({ state: "building", actor: "agent", empty: true, step: false })
     })
@@ -523,7 +544,8 @@ describe("summaryRun", () => {
     expect(summary.trace).toEqual([
       { state: "building", hash: building, actor: "human" },
       { state: "checking", hash: checking, actor: "agent" },
-      { state: "idle", hash: closing, actor: "agent" },
+      { state: "unpin", hash: headOf(repo, `${closing}~1`), actor: "agent" },
+      { state: "idle", hash: closing, actor: "check" },
     ])
   })
 
@@ -635,7 +657,9 @@ export default workflow(async () => {
       `--model=${model}`,
     )
     if (exitCode !== 0) throw new Error(`gtd land exited ${exitCode}: ${stderr}${stdout}`)
-    return applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+    const turn = applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+    await takePinBeat(repo, "add")
+    return (await takePinBeat(repo, "remove")) ? headOf(repo) : turn
   }
   type Rendered = {
     entryCommit: string
@@ -711,6 +735,7 @@ describe("restAt", () => {
       )
       expect(exitCode).toBe(0)
       await applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+      await takePinBeat(repo, "add")
     }
     const { cost } = await provide(currentRest, repo)
     expect(cost.total).toBe(11)
@@ -806,6 +831,7 @@ export const review = workflow(async () => {
   it("is the base the resting step names", async () => {
     const repo = repoWith(LOOP)
     const first = await land(repo, { "a.txt": "a\n" })
+    expect(repo.lastCommitSubject()).toBe("gtd(check): pin → checkpoint")
     expect(reviewBaseFor(await provide(currentRest, repo))).toBe(first)
     await land(repo, { "b.txt": "b\n" })
     expect(reviewBaseFor(await provide(currentRest, repo))).toBe(first)
@@ -1043,8 +1069,8 @@ export default workflow(async () => {
 
   it("an ordinary start's first commit pins every process setting, sorted by name", async () => {
     const repo = repoWith(LINEAR)
-    await land(repo, { "a.txt": "a\n" })
-    expect(repo.lastCommitMessage()).toContain(
+    const start = await land(repo, { "a.txt": "a\n" })
+    expect(repo.lastCommitMessage(start)).toContain(
       "\n\nGtd-Step: idle#1\nGtd-Var: base=\nGtd-Var: reviewer=nobody",
     )
     await land(repo)
@@ -1265,13 +1291,34 @@ describe("finishing landings keep history", () => {
     return landing
   }
 
+  /** Lands the turn that ends the flow, and runs the unpin beat's script without landing it. */
+  const toUnpin = async (repo: InMemRepo, files: Files) => {
+    write(repo, files)
+    const turn = await cli(repo, "land", "--json")
+    applied(repo, (JSON.parse(turn.stdout) as { readonly script: string }).script)
+    const beat = await cli(repo, "next", "--json")
+    applied(repo, (JSON.parse(beat.stdout) as { readonly content: string }).content)
+  }
+
+  it("a pinned process's last turn lands at the unpin, keeping no history yet", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    repo.writeFile("c.txt", "c\n")
+    const landing = await landingOf(repo)
+    expect(landing.to).toBe("unpin")
+    expect(landing.keepHistory).toBeUndefined()
+    expect(landing.spec.version).toBeUndefined()
+  })
+
   it("flow return: keeps refs/gtd/history/<startHash>, records version and branch", async () => {
     const repo = repoWith(LINEAR)
     const building = await land(repo, { "a.txt": "a\n" })
     await land(repo, { "b.txt": "b\n" })
-    repo.writeFile("c.txt", "c\n")
+    await toUnpin(repo, { "c.txt": "c\n" })
     const landing = await landingOf(repo)
     expect(landing.to).toBe("idle")
+    expect(landing.spec.pin).toBe("remove")
     expect(landing.keepHistory).toBe(processHistoryRef(building))
     expect(landing.spec.version).toBe(GTD_VERSION)
     expect(landing.spec.branch).toBe(repo.branchName())
@@ -1287,7 +1334,7 @@ export default async () => {
 }
 `)
     const building = await land(repo, { "a.txt": "a\n" })
-    repo.writeFile("b.txt", "b\n")
+    await toUnpin(repo, { "b.txt": "b\n" })
     const landing = await landingOf(repo)
     expect(landing.to).toBe("idle")
     expect(landing.keepHistory).toBe(processHistoryRef(building))
@@ -1314,7 +1361,7 @@ export default async () => {
     const repo = repoWith(LINEAR)
     const building = await land(repo, { "a.txt": "a\n" })
     await land(repo, { "b.txt": "b\n" })
-    repo.writeFile("c.txt", "c\n")
+    await toUnpin(repo, { "c.txt": "c\n" })
     const detached: GitOperations = {
       ...fakeGitOperations(repo),
       currentBranch: () => Effect.succeed(Option.none()),
@@ -1338,7 +1385,7 @@ export const side = workflow(async () => {
 })
 `)
     const opening = await enter(repo, "side")
-    repo.writeFile("a.txt", "a\n")
+    await toUnpin(repo, { "a.txt": "a\n" })
     const landing = await landingOf(repo)
     expect(landing.to).toBe("idle")
     expect(landing.keepHistory).toBe(processHistoryRef(opening))
@@ -1468,14 +1515,20 @@ describe("historyTrail", () => {
     const trail = await provide(historyTrail(tip), repo)
     expect(trail.tip).toBe(tip)
     expect(trail.ended).toBe("return")
-    expect(trail.steps.map((s) => s.hash)).toEqual([building, checking, tip])
+    expect(trail.steps.map((s) => s.hash)).toEqual([
+      building,
+      checking,
+      headOf(repo, `${tip}~1`),
+      tip,
+    ])
     expect(trail.steps[2]).toMatchObject({
-      subject: "gtd(agent): checking → idle",
+      subject: "gtd(agent): checking → unpin",
       actor: "agent",
       from: "checking",
-      to: "idle",
+      to: "unpin",
       verdicts: [],
     })
+    expect(trail.steps[3]).toMatchObject({ subject: "gtd(check): unpin → idle", actor: "check" })
     expect(trail.steps[0]).toMatchObject({ actor: "human", to: "building" })
   })
 
@@ -1628,7 +1681,7 @@ export default async () => {
         )
       }).pipe(Effect.provide(testLayers(repo, {}))),
     )
-    expect(trail.steps).toHaveLength(3)
+    expect(trail.steps).toHaveLength(4)
     expect(calls).toBe(1)
   })