@pmelab/gtd 62.1.0 → 63.0.0

package/src/replay/Replay.ts

@@ -127,7 +127,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 +268,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 +362,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 +389,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 || to === UNPIN_STATE ? 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 +608,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 +640,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,21 +652,27 @@ 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)
+    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
-    // 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)
   }
 
   const noteKept = (step: ReachedStep, commit: ParsedCommit): void => {
@@ -679,16 +756,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: 3",
     )
     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: 3")
     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: 3",
+        `Gtd-Version: ${value}\nGtd-Format: 3`,
       )
     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: 3")).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: 3")
+    expect(parseCommitMessage(message).format).toBe(3)
   })
 
   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: 3").format).toBe(3)
     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(3)
   })
 })
 
@@ -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: 3")
   })
 
   it("writes nothing without marks", () => {

package/src/replay/Trailers.ts

@@ -94,6 +94,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 +155,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 +203,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 +227,7 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     kept: undefined,
     approved: undefined,
     pin: undefined,
+    anchor: undefined,
     judge: [],
     marks: [],
     vars: {},
@@ -250,6 +257,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 +283,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,

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: 3",
         },
       },
       { 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: 3",
     )
     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: 3" },
       },
       { 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: 3",
       },
     })
     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: 3")
     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: 3",
       },
     })
   })