@pmelab/gtd 62.1.0 → 64.0.0

package/src/replay/Replay.test.ts

@@ -1154,6 +1154,8 @@ describe("human({ approve })", () => {
     expect(outcome).toEqual({
       kind: "divergence",
       message: `gtd: commit ${hashOf(1).slice(0, 7)} completes approval gate "gate#1" but records no Gtd-Approved for it — the workflow changed under this process; run \`gtd abandon\` to start over`,
+      at: hashOf(0),
+      reached: "gate",
     })
   })
 
@@ -1224,7 +1226,7 @@ describe("pin commits", () => {
   const pinned = () =>
     new History()
       .land("human", "idle", 1, "build", { "NOTE.md": "n" })
-      .raw("gtd(check): pin → build\n\nGtd-Pin: add", { [PIN]: "gtdpin 1 gtd 1\n" })
+      .raw("gtd(check): gtd:pin → build\n\nGtd-Pin: add", { [PIN]: "gtdpin 1 gtd 1\n" })
 
   it("are never a turn: the next step answers from the commit after the pin", async () => {
     const flow = async () => {
@@ -1266,8 +1268,113 @@ describe("pin commits", () => {
       await agent("build", "b")
     }
     const h = pinned()
-      .land("agent", "build", 1, "unpin", { "a.ts": "a" })
-      .raw("gtd(check): unpin → idle\n\nGtd-Pin: remove", { [PIN]: null })
+      .land("agent", "build", 1, "gtd:unpin", { "a.ts": "a" })
+      .raw("gtd(check): gtd:unpin → idle\n\nGtd-Pin: remove", { [PIN]: null })
     expect((await replayOf(flow, h)).kind).toBe("ended")
   })
 })
+
+describe("replay: a repin's anchor", () => {
+  const anchorTo = (to: string, at: number): string =>
+    formatCommitMessage({ actor: "check", from: "gtd:pin", to, pin: "add", anchor: hashOf(at) })
+
+  // The old flow went idle → build → old; this one goes idle → build → check.
+  const anchoredHistory = (): History =>
+    new History()
+      .land("human", "idle", 1, "build", { "a.txt": "a" })
+      .land("agent", "build", 1, "old", { "b.txt": "b" })
+      .raw(anchorTo("build", 1))
+
+  it("records where replay diverged and the step it reached there", async () => {
+    const h = new History().land("human", "idle", 1, "fix", { "TODO.md": "go" })
+    const outcome = await replayOf(fixLoop, h)
+    expect(outcome).toMatchObject({ kind: "divergence", at: hashOf(1), reached: "check" })
+  })
+
+  it("rests at the anchored step, redone on the anchor's tree", async () => {
+    let afterBuild: readonly string[] = []
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("build", "p")
+      afterBuild = changes().map((c) => c.path)
+      await agent("check", "p")
+    }
+    expect(restName(await replayOf(flow, anchoredHistory()))).toBe("build#1")
+    const outcome = await replayOf(flow, anchoredHistory(), { pending: { "c.txt": "c" } })
+    expect(restName(outcome)).toBe("check#1")
+    expect(afterBuild).toEqual(["c.txt"])
+  })
+
+  it("fails changesSince() on a commit it set aside", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      changesSince(hashOf(2))
+      await agent("build", "p")
+    }
+    const outcome = await replayOf(flow, anchoredHistory())
+    expect(outcome.kind === "failed" && outcome.message).toContain("a repin set 0000000 aside")
+  })
+
+  it("diverges again when the flow reaches another step than the anchor names", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("make", "p")
+    }
+    expect(await replayOf(flow, anchoredHistory())).toMatchObject({
+      kind: "divergence",
+      at: hashOf(3),
+      reached: "make",
+    })
+  })
+
+  it("lets the flow code leading to the step read HEAD's tree", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("build", `seen: ${read("b.txt") ?? "nothing"}`)
+    }
+    const outcome = await replayOf(flow, anchoredHistory())
+    expect(outcome.kind === "rest" && outcome.rest.request).toMatchObject({ prompt: "seen: b" })
+  })
+
+  it("diverges when the flow ends where it names a step", async () => {
+    const outcome = await replayOf(async () => void (await human("idle")), anchoredHistory())
+    expect(outcome).toMatchObject({ kind: "divergence", at: hashOf(3), reached: undefined })
+  })
+
+  it("closes the process when it names the unpin and the flow ends", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "build", { "a.txt": "a" })
+      .land("agent", "build", 1, "old")
+      .raw(anchorTo("gtd:unpin", 1))
+    const outcome = await replayOf(async () => void (await human("idle")), h)
+    expect(outcome.kind).toBe("ended")
+  })
+
+  it("closes the process when a format 3 anchor names the unpin by its old name", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "build", { "a.txt": "a" })
+      .land("agent", "build", 1, "old")
+      .raw(`gtd(check): pin → unpin\n\nGtd-Pin: add\nGtd-Anchor: ${hashOf(1)}\nGtd-Format: 3`)
+    const outcome = await replayOf(async () => void (await human("idle")), h)
+    expect(outcome.kind).toBe("ended")
+  })
+
+  it("reads a format 4 anchor naming unpin as a step", async () => {
+    const outcome = await replayOf(
+      async () => void (await human("idle")),
+      new History()
+        .land("human", "idle", 1, "build", { "a.txt": "a" })
+        .land("agent", "build", 1, "old")
+        .raw(anchorTo("unpin", 1)),
+    )
+    expect(outcome).toMatchObject({ kind: "divergence", reached: undefined })
+  })
+
+  it("fails when it names no commit replay reads", async () => {
+    const h = anchoredHistory().raw(anchorTo("build", 2))
+    const outcome = await replayOf(async () => void (await human("idle")), h)
+    expect(outcome.kind === "failed" && outcome.message).toContain(
+      "which is no commit replay reads",
+    )
+  })
+})

package/src/replay/Replay.ts

@@ -29,10 +29,14 @@ import {
   type CommitMessage,
   type JudgeVerdict,
   type StepId,
-  PIN_STATES,
+  ENGINE_PREFIX,
+  pinStateIn,
 } from "./Trailers.js"
 
-const UNPIN_STATE = PIN_STATES.remove
+const namesUnpin = (commit: ParsedCommit): boolean => {
+  const unpin = pinStateIn(commit.parsed.format, "remove")
+  return unpin !== undefined && commit.parsed.parsed?.to === unpin
+}
 
 export interface EpisodeCommit {
   readonly hash: string
@@ -127,7 +131,14 @@ export type ReplayOutcome =
       readonly landed: ReachedStep | undefined
       readonly marks: readonly Mark[]
     }
-  | { readonly kind: "divergence"; readonly message: string }
+  | {
+      readonly kind: "divergence"
+      readonly message: string
+      /** The commit replay last stood on — where a repin anchors. */
+      readonly at: string
+      /** The step replay reached there; `undefined` when the flow ended instead. */
+      readonly reached: string | undefined
+    }
   | { readonly kind: "refused"; readonly message: string }
   | { readonly kind: "failed"; readonly message: string }
 
@@ -261,6 +272,38 @@ interface ParsedCommit extends EpisodeCommit {
   readonly parsed: CommitMessage
 }
 
+const anchorOf = (parsed: CommitMessage): string | undefined =>
+  parsed.pin === "add" ? parsed.anchor : undefined
+
+const isAnchor = (commit: ParsedCommit): boolean => anchorOf(commit.parsed) !== undefined
+
+/**
+ * The commits every anchor sets aside — those between the commit it names and
+ * itself — or a fault for an anchor naming no commit still read.
+ */
+export const setAsideBy = (
+  base: string,
+  all: readonly { readonly hash: string; readonly parsed: CommitMessage }[],
+): { readonly setAside: ReadonlySet<string> } | { readonly fault: string } => {
+  const setAside = new Set<string>()
+  if (all.every((c) => anchorOf(c.parsed) === undefined)) return { setAside }
+  let kept: string[] = []
+  for (const commit of all) {
+    const anchor = anchorOf(commit.parsed)
+    if (anchor !== undefined) {
+      const at = anchor === base ? -1 : kept.indexOf(anchor)
+      if (anchor !== base && at === -1) {
+        return {
+          fault: `gtd: commit ${short(commit.hash)} anchors the process at ${short(anchor)}, which is no commit replay reads in this episode`,
+        }
+      }
+      for (const hash of kept.splice(at + 1)) setAside.add(hash)
+    }
+    kept.push(commit.hash)
+  }
+  return { setAside }
+}
+
 /**
  * Replay one episode: run its entry flow, answering each step from the
  * episode's commits in order, until a step has no commit left — the rest.
@@ -323,10 +366,17 @@ const withoutPin = (input: ReplayInput): ReplayInput => {
 
 export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
   const input = withoutPin(raw)
-  const commits: readonly ParsedCommit[] = input.episode.commits.map((c) => ({
+  const all: readonly ParsedCommit[] = input.episode.commits.map((c) => ({
     ...c,
     parsed: parseCommitMessage(c.message),
   }))
+  const resolved = setAsideBy(input.episode.base.hash, all)
+  if ("fault" in resolved) return { kind: "failed", message: resolved.fault }
+  const setAside = resolved.setAside
+  const commits = all.filter((c) => !setAside.has(c.hash))
+  const pinned = (raw.episode.commits.at(-1)?.tree ?? raw.episode.base.tree)
+    .paths()
+    .includes(PIN_PATH)
 
   // Every replay re-derives base, commits and head() from whatever history
   // exists right now, so a hash a flow reads this same run (head()/start())
@@ -343,12 +393,27 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
   let pendingUsed = false
   let position: Position = input.episode.base
   // Never stands on a pin commit: `head()` names the turn, so a flow
-  // reverting it reverts the turn, not the pin.
+  // reverting it reverts the turn, not the pin. An anchor is the exception:
+  // replay stands on it for HEAD's tree, so the flow code leading to the step
+  // it names, and that step's actor, see the set-aside work in place.
+  // `changes()` keeps the previous position: the set-aside range counts as
+  // part of the last step replay read.
   const skipPins = (): void => {
-    while (cursor < commits.length && commits[cursor]!.parsed.pin !== undefined) cursor++
+    while (cursor < commits.length && commits[cursor]!.parsed.pin !== undefined) {
+      const commit = commits[cursor]!
+      cursor++
+      if (!isAnchor(commit)) continue
+      position = commit
+      const to = commit.parsed.parsed?.to
+      expectedNext =
+        to === undefined || namesUnpin(commit) ? undefined : { name: to, hash: commit.hash }
+      anchorPending = expectedNext !== undefined
+    }
   }
   let previousPosition: Position = input.episode.base
   let expectedNext: { readonly name: string; readonly hash: string } | undefined
+  // Whether `expectedNext` is an anchor's, which a flow that ends contradicts.
+  let anchorPending = false
   const occurrences = new Map<string, number>()
   const personas = new Map<string, Identity>()
   const scopes: ScopeOptions[] = []
@@ -547,18 +612,28 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
       : `gtd: "${step.name}" runs with a different model, system prompt, skills or file access than an earlier agent step in its conversation in memory scope "${step.memoryScope || "root"}" — a conversation has one identity`
   }
 
-  const DIVERGED = "the workflow changed under this process; run `gtd abandon` to start over"
+  const DIVERGED = pinned
+    ? "the workflow changed under this process; run `gtd repin` to continue under it from there, or `gtd abandon` to start over"
+    : "the workflow changed under this process; run `gtd abandon` to start over"
+
+  const diverged = (message: string, reached: ReachedStep | undefined): ReplayOutcome => ({
+    kind: "divergence",
+    message: `${message} — ${DIVERGED}`,
+    at: position.hash,
+    reached: reached?.name,
+  })
 
   // Checks a reached step against what the previous commit's subject promised
   // and against the persona of its scope — the reasons replay cannot go on.
   const blockerAt = (step: ReachedStep): ReplayOutcome | undefined => {
     const expected = expectedNext
     expectedNext = undefined
+    anchorPending = false
     if (expected !== undefined && expected.name !== step.name) {
-      return {
-        kind: "divergence",
-        message: `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}" — ${DIVERGED}`,
-      }
+      return diverged(
+        `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}"`,
+        step,
+      )
     }
     const error =
       unknownOptions(step) ?? approveConflict(step) ?? modeWithoutFile(step) ?? checkIdentity(step)
@@ -569,10 +644,10 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
     if (step.request.kind !== "human" || step.request.options.approve !== true) return undefined
     const approved = commit.parsed.approved
     if (approved !== undefined && formatStepId(approved.step) === expected) return undefined
-    return {
-      kind: "divergence" as const,
-      message: `gtd: commit ${short(commit.hash)} completes approval gate "${expected}" but records no Gtd-Approved for it — ${DIVERGED}`,
-    }
+    return diverged(
+      `gtd: commit ${short(commit.hash)} completes approval gate "${expected}" but records no Gtd-Approved for it`,
+      step,
+    )
   }
 
   const consumeCommit = (step: ReachedStep, commit: ParsedCommit): unknown => {
@@ -581,23 +656,29 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
     if (recorded === undefined || formatStepId(recorded) !== expected) {
       const what =
         recorded === undefined ? "records no step" : `records step "${formatStepId(recorded)}"`
-      return finish({
-        kind: "divergence",
-        message: `gtd: commit ${short(commit.hash)} ${what}, but replay expected "${expected}" — ${DIVERGED}`,
-      })
+      return finish(
+        diverged(
+          `gtd: commit ${short(commit.hash)} ${what}, but replay expected "${expected}"`,
+          step,
+        ),
+      )
     }
     const unapproved = missingApproval(step, commit, expected)
     if (unapproved !== undefined) return finish(unapproved)
     cursor++
     advance(commit)
+    expectNextOf(commit)
     skipPins()
     noteKept(step, commit)
-    const to = commit.parsed.parsed?.to
-    // A turn that ends a pinned process names the unpin, which is no step.
-    if (to !== undefined && to !== UNPIN_STATE) expectedNext = { name: to, hash: commit.hash }
     return replyFor(step.request, commit.parsed.judge)
   }
 
+  // A turn that ends a pinned process names the unpin, which is no step.
+  const expectNextOf = (commit: ParsedCommit): void => {
+    const to = commit.parsed.parsed?.to
+    if (to !== undefined && !namesUnpin(commit)) expectedNext = { name: to, hash: commit.hash }
+  }
+
   const noteKept = (step: ReachedStep, commit: ParsedCommit): void => {
     if (commit.parsed.kept === undefined) return
     if (commit.kept === undefined) keptTips.delete(step.name)
@@ -642,8 +723,8 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
 
   // gtd.config.ts is loaded without a type check.
   const requestFault = (request: Exclude<StepRequest, { kind: "restart" }>): string | undefined => {
-    if (Object.values(PIN_STATES).includes(scoped(request.name))) {
-      return `gtd: step "${scoped(request.name)}": the name is reserved for the pin and unpin beats — rename the step`
+    if (scoped(request.name).startsWith(ENGINE_PREFIX)) {
+      return `gtd: step "${scoped(request.name)}": the "${ENGINE_PREFIX}" prefix is reserved for gtd's own beats — rename the step`
     }
     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)`
@@ -679,16 +760,27 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
 
   const endOfFlow = (via: "return" | "restart"): ReplayOutcome => {
     skipPins()
+    if (anchorPending && cursor === commits.length) {
+      return diverged(
+        `gtd: the flow ended, but commit ${short(expectedNext!.hash)} continues the process at "${expectedNext!.name}"`,
+        undefined,
+      )
+    }
     return cursor < commits.length
-      ? {
-          kind: "divergence",
-          message: `gtd: the flow ended, but commit ${short(commits[cursor]!.hash)} continues the episode — ${DIVERGED}`,
-        }
+      ? diverged(
+          `gtd: the flow ended, but commit ${short(commits[cursor]!.hash)} continues the episode`,
+          undefined,
+        )
       : { kind: "ended", via, trace, landed, marks }
   }
 
   const changesSince = (hash: string): readonly Change[] => {
     const tree = treeAt(hash)
+    if (setAside.has(hash)) {
+      throw new Error(
+        `gtd: changesSince(${hash}): a repin set ${short(hash)} aside — pass a hash this run read from head() or start()`,
+      )
+    }
     if (tree === undefined) {
       throw new Error(
         `gtd: changesSince(${hash}): ${hash} is not the episode base or one of its commits — pass a hash this run read from head() or start(), not one captured earlier, read from state, or from another branch`,

package/src/replay/Trailers.test.ts

@@ -46,7 +46,7 @@ describe("the commit-message codec", () => {
       reviewBase: "abc",
     })
     expect(message).toBe(
-      "gtd(human): fix-precheck\n\nGtd-Workflow: fix\nGtd-Review-Base: abc\nGtd-Format: 2",
+      "gtd(human): fix-precheck\n\nGtd-Workflow: fix\nGtd-Review-Base: abc\nGtd-Format: 4",
     )
     expect(parseCommitMessage(message).workflow).toBe("fix")
     expect(parseCommitMessage("gtd(human): fix-precheck").workflow).toBeUndefined()
@@ -56,7 +56,7 @@ describe("the commit-message codec", () => {
     const one = formatCommitMessage({ actor: "human", to: "x", vars: { b: "2", a: "1", c: "" } })
     const two = formatCommitMessage({ actor: "human", to: "x", vars: { c: "", a: "1", b: "2" } })
     expect(one).toBe(two)
-    expect(one).toBe("gtd(human): x\n\nGtd-Var: a=1\nGtd-Var: b=2\nGtd-Var: c=\nGtd-Format: 2")
+    expect(one).toBe("gtd(human): x\n\nGtd-Var: a=1\nGtd-Var: b=2\nGtd-Var: c=\nGtd-Format: 4")
     expect(parseCommitMessage(one).vars).toEqual({ a: "1", b: "2", c: "" })
   })
 
@@ -81,8 +81,8 @@ describe("the commit-message codec", () => {
   it("reads a Gtd-Version carrying control bytes as unknown, and keeps spaces and parens", () => {
     const withVersion = (value: string) =>
       formatCommitMessage({ actor: "a", to: "b" }).replace(
-        "Gtd-Format: 2",
-        `Gtd-Version: ${value}\nGtd-Format: 2`,
+        "Gtd-Format: 4",
+        `Gtd-Version: ${value}\nGtd-Format: 4`,
       )
     expect(parseCommitMessage(withVersion("1.0\u001b]0;x\u0007")).version).toBeUndefined()
     expect(parseCommitMessage(withVersion("1.0\u009b")).version).toBeUndefined()
@@ -100,18 +100,18 @@ describe("the commit-message codec", () => {
 
   it("writes the current Gtd-Format when branch and version are written", () => {
     const message = formatCommitMessage({ actor: "a", to: "b", branch: "m", version: "1" })
-    expect(message.endsWith("Gtd-Format: 2")).toBe(true)
+    expect(message.endsWith("Gtd-Format: 4")).toBe(true)
   })
 
   it("writes Gtd-Format last on every message, even one with no other trailer", () => {
     const message = formatCommitMessage({ actor: "agent", to: "building" })
-    expect(message).toBe("gtd(agent): building\n\nGtd-Format: 2")
-    expect(parseCommitMessage(message).format).toBe(2)
+    expect(message).toBe("gtd(agent): building\n\nGtd-Format: 4")
+    expect(parseCommitMessage(message).format).toBe(4)
   })
 
   it("reads a message without Gtd-Format as format 1, and an explicit one as written", () => {
     expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Step: a#1").format).toBe(1)
-    expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Format: 2").format).toBe(2)
+    expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Format: 4").format).toBe(4)
     expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Format: two").format).toBe(1)
   })
 
@@ -149,7 +149,7 @@ describe("Gtd-Kept", () => {
   it("reads undefined when absent, and leaves Gtd-Format at the current format", () => {
     const parsed = parseCommitMessage(formatCommitMessage({ actor: "agent", to: "b" }))
     expect(parsed.kept).toBeUndefined()
-    expect(parsed.format).toBe(2)
+    expect(parsed.format).toBe(4)
   })
 })
 
@@ -289,7 +289,7 @@ describe("Gtd-Mark", () => {
     const at = lines.findIndex((l) => l.startsWith("Gtd-Mark:"))
     expect(lines[at - 1]).toMatch(/^Gtd-Judge:/)
     expect(lines[at + 1]).toMatch(/^Gtd-Approved:/)
-    expect(lines).toContain("Gtd-Format: 2")
+    expect(lines).toContain("Gtd-Format: 4")
   })
 
   it("writes nothing without marks", () => {

package/src/replay/Trailers.ts

@@ -70,8 +70,30 @@ export interface Approval {
 
 export type PinChange = PinMark
 
+/** Step names a workflow may not take: gtd's own beats live under it. */
+export const ENGINE_PREFIX = "gtd:"
+
 /** What a pin and an unpin beat rest at, and their commits name — neither is a step of the workflow. */
-export const PIN_STATES: Readonly<Record<PinChange, string>> = { add: "pin", remove: "unpin" }
+export const PIN_STATES: Readonly<Record<PinChange, string>> = {
+  add: `${ENGINE_PREFIX}pin`,
+  remove: `${ENGINE_PREFIX}unpin`,
+}
+
+/** The names formats 2 and 3 gave the pin beats, before `gtd:` reserved them. */
+export const LEGACY_PIN_STATES: Readonly<Record<PinChange, string>> = {
+  add: "pin",
+  remove: "unpin",
+}
+
+const SCOPED_PIN_FORMAT = 4
+
+/** The name a commit in `format` gives a pin beat; format 1 has none. */
+export const pinStateIn = (format: number, change: PinChange): string | undefined =>
+  format >= SCOPED_PIN_FORMAT
+    ? PIN_STATES[change]
+    : format >= 2
+      ? LEGACY_PIN_STATES[change]
+      : undefined
 
 export interface CommitMessage {
   readonly subject: string
@@ -94,6 +116,8 @@ export interface CommitMessage {
   readonly approved: Approval | undefined
   /** `Gtd-Pin`: a commit that adds or removes the pin — never a turn. */
   readonly pin: PinChange | undefined
+  /** `Gtd-Anchor`, on a repin's commit: replay sets aside every commit after this one; a non-hash value is skipped. */
+  readonly anchor: string | undefined
   readonly format: number
 }
 
@@ -153,6 +177,7 @@ interface Trailers {
   kept: string | undefined
   approved: Approval | undefined
   pin: PinChange | undefined
+  anchor: string | undefined
   readonly judge: JudgeVerdict[]
   readonly marks: Mark[]
   readonly vars: Record<string, string>
@@ -200,6 +225,9 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Pin": (value, into) => {
     if (value === "add" || value === "remove") into.pin ??= value
   },
+  "Gtd-Anchor": (value, into) => {
+    if (HASH_RE.test(value)) into.anchor ??= value
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -221,6 +249,7 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     kept: undefined,
     approved: undefined,
     pin: undefined,
+    anchor: undefined,
     judge: [],
     marks: [],
     vars: {},
@@ -250,6 +279,7 @@ export interface CommitSpec {
   /** Written after `Gtd-Mark`, before `Gtd-Branch`. */
   readonly approved?: Approval
   readonly pin?: PinChange
+  readonly anchor?: string
   readonly branch?: string
   readonly version?: string
 }
@@ -275,6 +305,7 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     ...(spec.marks ?? []).map((m) => `Gtd-Mark: ${m.name}=${m.value}`),
     ...trailer("Approved", spec.approved && encodeApproval(spec.approved)),
     ...trailer("Pin", spec.pin),
+    ...trailer("Anchor", spec.anchor),
     ...trailer("Branch", spec.branch),
     ...trailer("Version", spec.version),
     `Gtd-Format: ${HISTORY_FORMAT}`,

package/src/replay/index.ts

@@ -1,6 +1,7 @@
 export {
   replay,
   scopeRunStart,
+  setAsideBy,
   type EpisodeCommit,
   type ReachedStep,
   type ReplayOutcome,
@@ -16,6 +17,7 @@ export {
   type CommitSpec,
   type JudgeVerdict,
   type PinChange,
+  LEGACY_PIN_STATES,
   PIN_STATES,
 } from "./Trailers.js"
 export { accessShapeFault } from "./Access.js"

package/src/step/planStart.test.ts

@@ -176,7 +176,7 @@ describe("planStart", () => {
         kind: "gitWrite",
         write: {
           kind: "commitAll",
-          message: "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=\nGtd-Format: 2",
+          message: "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=\nGtd-Format: 4",
         },
       },
       { kind: "outcome", outcome: { kind: "commit", subject: "gtd(human): work" } },
@@ -195,7 +195,7 @@ describe("planStart", () => {
     if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
       throw new Error("expected a gitWrite step")
     expect(write.write.message).toBe(
-      "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=main\nGtd-Format: 2",
+      "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=main\nGtd-Format: 4",
     )
     const outcome = plan.steps.find((s) => s.kind === "outcome")
     expect(outcome).toEqual({

package/src/step/planStep.test.ts

@@ -39,7 +39,7 @@ describe("planStep — commit", () => {
     expect(outcome.steps).toEqual([
       {
         kind: "gitWrite",
-        write: { kind: "commitAll", message: "gtd(agent): await-answers\n\nGtd-Format: 2" },
+        write: { kind: "commitAll", message: "gtd(agent): await-answers\n\nGtd-Format: 4" },
       },
       { kind: "outcome", outcome: { kind: "commit", subject: "gtd(agent): await-answers" } },
     ])
@@ -59,7 +59,7 @@ describe("planStep — commit", () => {
       kind: "gitWrite",
       write: {
         kind: "commitAll",
-        message: "gtd(human): building → done\n\nGtd-Step: building#1\nGtd-Format: 2",
+        message: "gtd(human): building → done\n\nGtd-Step: building#1\nGtd-Format: 4",
       },
     })
     expect(outcome.steps.at(-1)).toEqual({
@@ -99,7 +99,7 @@ describe("planStep — commit", () => {
     expect(trailers[1]).toBe("Gtd-Cost: 1.5 m")
     expect(trailers[2]).toBe('Gtd-Judge: {"id":"q1","answer":true,"p":0.9}')
     expect(trailers[3]).toBe('Gtd-Judge: {"id":"q2","answer":"x","p":0.4}')
-    expect(trailers[4]).toBe("Gtd-Format: 2")
+    expect(trailers[4]).toBe("Gtd-Format: 4")
     expect(trailers).toHaveLength(5)
   })
 })
@@ -182,7 +182,7 @@ describe("planStep — keepTurn", () => {
       write: {
         kind: "keepTurn",
         ref: kept,
-        message: "gtd(agent): building → checking\n\nGtd-Step: building#1\nGtd-Format: 2",
+        message: "gtd(agent): building → checking\n\nGtd-Step: building#1\nGtd-Format: 4",
       },
     })
   })

package/src/testkit/TestRepo.test.ts

@@ -61,7 +61,7 @@ describe("testRepo", () => {
     expect(repo.subjects()).toEqual([
       "chore: initial commit",
       "gtd(agent): plan → build",
-      "gtd(check): pin → build",
+      "gtd(check): gtd:pin → build",
       "gtd(agent): build → check",
       "gtd(check): check → sign-off",
     ])

package/src/testkit/TestRepo.ts

@@ -1,5 +1,4 @@
 import { Effect } from "effect"
-import { PassThrough } from "node:stream"
 import { runCli } from "../cli/index.js"
 import { EXIT_OK, type BeatDocument } from "../wire/index.js"
 import {
@@ -450,8 +449,8 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
 
   // The modules are registered only while gtd runs, so nothing outlives the
   // call that loads them and no test can reach another's module.
-  const gtd = async (...args: string[]): Promise<CapturedCliResult> => {
-    const { io, result } = makeCapturingCliIo(repo, seenEnv())
+  const gtdWithStdin = async (stdin: string, ...args: string[]): Promise<CapturedCliResult> => {
+    const { io, result } = makeCapturingCliIo(repo, seenEnv(), {}, stdin)
     if (typeof workflow !== "string") registry().set(id, workflow)
     for (const [specifier, module] of modules) registry().set(moduleKey(specifier), module)
     try {
@@ -462,19 +461,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     }
     return result()
   }
-
-  // `gtd judge answer` reads its verdict off stdin, so it is swapped for the call.
-  const withStdin = async <T>(stdin: string, fn: () => Promise<T>): Promise<T> => {
-    const saved = Object.getOwnPropertyDescriptor(process, "stdin")
-    const fake = new PassThrough()
-    Object.defineProperty(process, "stdin", { value: fake, configurable: true })
-    fake.end(stdin)
-    try {
-      return await fn()
-    } finally {
-      if (saved) Object.defineProperty(process, "stdin", saved)
-    }
-  }
+  const gtd = (...args: string[]): Promise<CapturedCliResult> => gtdWithStdin("", ...args)
 
   const apply = (what: string, script: string): void => {
     if (script.length === 0) return
@@ -488,8 +475,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     stdin?: string,
     refused: (error: Error) => Error = (error) => error,
   ): Promise<CapturedCliResult> => {
-    const call = (...extra: string[]) =>
-      stdin === undefined ? gtd(...args, ...extra) : withStdin(stdin, () => gtd(...args, ...extra))
+    const call = (...extra: string[]) => gtdWithStdin(stdin ?? "", ...args, ...extra)
     const reported = await call()
     if (reported.exitCode !== EXIT_OK) throw refused(failed(`gtd ${args.join(" ")}`, reported))
     const script = await call("--json=script")