@pmelab/gtd 64.3.0 → 66.0.0

package/src/cli/History.test.ts

@@ -10,6 +10,9 @@ import {
 import { runCli } from "./index.js"
 import { historyEntries, resolveHistoryRef, type HistoryEntry } from "./History.js"
 
+// A process runs on `gtd/<b>`; the recorded branch is the user's `<b>`.
+const USER_BRANCH = "main"
+
 const CONFIG = `import { agent, human } from "@pmelab/gtd/flows"
 
 export default async () => {
@@ -32,8 +35,9 @@ 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)
+  const branch = repo.branchName()
   await takePinBeat(repo, "remove")
-  return repo.resolveRef("HEAD")!
+  return repo.resolveRef(`refs/heads/${branch}`)!
 }
 
 const finishedProcess = async (repo: InMemRepo, file: string) => {
@@ -82,7 +86,7 @@ describe("historyEntries", () => {
     expect(list.map((e) => e.entry)).toEqual([second.entry, first.entry])
     expect(list[0]).toMatchObject({
       ref: `refs/gtd/history/${second.entry}`,
-      branch: repo.branchName(),
+      branch: USER_BRANCH,
       tip: second.tip,
       subject: "gtd(human): idle → building",
     })
@@ -169,16 +173,14 @@ describe("gtd history list", () => {
     const text = await gtd(repo, "history", "list")
     const line = text.stdout.trimEnd().split("\n")
     expect(line).toHaveLength(1)
-    expect(
-      line[0]!.startsWith(`${hash.slice(0, 7)} ${repo.branchName()} ${tip.slice(0, 7)} `),
-    ).toBe(true)
+    expect(line[0]!.startsWith(`${hash.slice(0, 7)} ${USER_BRANCH} ${tip.slice(0, 7)} `)).toBe(true)
     expect(line[0]!.endsWith(" gtd(human): idle → building")).toBe(true)
     const json = await gtd(repo, "history", "list", "--json")
     expect(JSON.parse(json.stdout)).toEqual([
       expect.objectContaining({
         ref: `refs/gtd/history/${hash}`,
         entry: hash,
-        branch: repo.branchName(),
+        branch: USER_BRANCH,
         tip,
         subject: "gtd(human): idle → building",
       }),
@@ -195,7 +197,7 @@ describe("gtd history show", () => {
     expect(out.exitCode).toBe(0)
     const lines = out.stdout.trimEnd().split("\n")
     expect(lines[0]).toBe(
-      `refs/gtd/history/${hash} (branch ${repo.branchName()}, tip ${tip.slice(0, 7)})`,
+      `refs/gtd/history/${hash} (branch ${USER_BRANCH}, tip ${tip.slice(0, 7)})`,
     )
     expect(out.stdout).toContain("gtd(human): idle → building")
     expect(lines[lines.length - 1]).toBe("ended (return)")
@@ -206,7 +208,7 @@ describe("gtd history show", () => {
     const { entry: hash, tip } = await finishedProcess(repo, "a.txt")
     const out = await gtd(repo, "history", "show", hash, "--json")
     const doc = JSON.parse(out.stdout)
-    expect(doc).toMatchObject({ entry: hash, tip, ended: "return", branch: repo.branchName() })
+    expect(doc).toMatchObject({ entry: hash, tip, ended: "return", branch: USER_BRANCH })
     expect(doc.steps.length).toBeGreaterThan(0)
     expect(doc.version).toHaveProperty("running")
   })

package/src/cli/Metrics.test.ts

@@ -233,8 +233,9 @@ 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)
+  const branch = repo.branchName()
   await takePinBeat(repo, "remove")
-  return repo.resolveRef("HEAD")!
+  return repo.resolveRef(`refs/heads/${branch}`)!
 }
 
 describe("readProcessMetrics", () => {

package/src/cli/Program.test.ts

@@ -1694,7 +1694,9 @@ export default async () => {
     const { exitCode, script } = await landAndApply(repo)
     expect(exitCode).toBe(0)
     expect(script).not.toContain("fmt-notes")
-    expect(repo.lastCommitSubject("HEAD~1")).toBe("gtd(agent): drafting → gtd:unpin")
+    expect(repo.lastCommitSubject(`${repo.resolveRef("gtd/main")}~1`)).toBe(
+      "gtd(agent): drafting → gtd:unpin",
+    )
   })
 
   it("`gtd next --json`'s `validate` field carries the mode's format command", async () => {
@@ -1974,7 +1976,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(check): gtd:unpin → idle")
+    expect(repo.lastCommitSubject("gtd/main")).toBe("gtd(check): gtd:unpin → idle")
 
     const { exitCode, stdout, stderr } = await run(repo, "base")
     expect(exitCode).toBe(1)

package/src/cli/Program.ts

@@ -9,6 +9,8 @@ import {
   type GitOperations,
   type HostOps,
   HISTORY_REF,
+  RESUME_BRANCH_REF,
+  processHistoryRef,
   readRetainedHistory,
   restorability,
   loopLogPath,
@@ -67,8 +69,14 @@ import {
   summaryRun,
   type RenderedRest,
 } from "../edge/index.js"
-import { formatCommitMessage, PIN_STATES } from "../replay/index.js"
-import { planStart, planStep as planStepPure, type JudgeVerdict } from "../step/index.js"
+import { formatCommitMessage, parseCommitMessage, PIN_STATES } from "../replay/index.js"
+import {
+  GTD_BRANCH_PREFIX,
+  userBranchOf,
+  planStart,
+  planStep as planStepPure,
+  type JudgeVerdict,
+} from "../step/index.js"
 import {
   BUILT_IN_MODE_NAMES,
   formatFromSpec,
@@ -85,6 +93,10 @@ import {
   deleteRef,
   hardResetTo,
   mixedResetTo,
+  switchBranchTo,
+  switchTo,
+  deleteBranch,
+  pushRef,
   unpinScript,
   repinScript,
   commitPath,
@@ -749,6 +761,29 @@ const runStartListCommand = (
     )
   })
 
+/**
+ * Back on `<b>` when the process ran on `gtd/<b>` and `<b>` moved only by its
+ * ships (whose `Gtd-Tip` the tip descends from): the rewind stops at the last
+ * ship, so the uncommitted changes are what it left unshipped.
+ */
+const abandonTarget = (current: Option.Option<string>, tip: string, startParent: string) =>
+  Effect.gen(function* () {
+    const git = yield* GitService
+    const userBranch = Option.isSome(current) ? userBranchOf(current.value) : undefined
+    const userTip =
+      userBranch === undefined
+        ? Option.none<string>()
+        : yield* git.readRefOption(`refs/heads/${userBranch}`)
+    if (userBranch === undefined || Option.isNone(userTip)) {
+      return { leaves: undefined, rewindTo: startParent }
+    }
+    if (userTip.value === startParent) return { leaves: userBranch, rewindTo: startParent }
+    const shipped = parseCommitMessage(yield* git.lastCommitMessage(userTip.value)).tip
+    return shipped !== undefined && (yield* git.isAncestor(shipped, tip))
+      ? { leaves: userBranch, rewindTo: userTip.value }
+      : { leaves: undefined, rewindTo: startParent }
+  })
+
 /**
  * Ends the process underway without completing it. Nothing is discarded: a
  * `git reset --mixed` to the process's start commit leaves every turn
@@ -766,6 +801,7 @@ const runAbandonCommand = (
   json: JsonMode,
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> =>
+  // fallow-ignore-next-line complexity
   Effect.gen(function* () {
     const git = yield* GitService
     const config = yield* (yield* ConfigService).load
@@ -790,17 +826,58 @@ const runAbandonCommand = (
     }
 
     const tip = yield* git.resolveRef("HEAD")
+    const historyRef = processHistoryRef(run.startHash)
+
+    const current = yield* git.currentBranch()
+    const { leaves, rewindTo } = yield* abandonTarget(current, tip, run.startParentHash)
+    const remote = config.historyRemote
 
     const steps: EmitStep[] = [
       { kind: "gitWrite", command: updateRef(HISTORY_REF, tip) },
-      { kind: "gitWrite", command: mixedResetTo(run.startParentHash) },
+      { kind: "gitWrite", command: updateRef(historyRef, tip) },
+      { kind: "gitWrite", command: mixedResetTo(rewindTo) },
       { kind: "gitWrite", command: unpinScript(PIN_PATH) },
-      { kind: "outcome", command: abandonedOutcome(restState, run.startParentHash, initial) },
+      ...(leaves !== undefined
+        ? [
+            { kind: "gitWrite", command: switchTo(leaves) } as const,
+            {
+              kind: "gitWrite",
+              command: deleteBranch(Option.getOrThrow(current)),
+            } as const,
+            { kind: "gitWrite", command: updateRef(RESUME_BRANCH_REF, tip) } as const,
+          ]
+        : [{ kind: "gitWrite", command: deleteRef(RESUME_BRANCH_REF) } as const]),
+      { kind: "outcome", command: abandonedOutcome(restState, rewindTo, initial) },
+      ...(remote !== undefined
+        ? [{ kind: "gitWrite", command: pushRef(remote, historyRef) } as const]
+        : []),
     ]
     const required = emitScripts(steps).required
     yield* writeScript(json, out, combinedScript(required, ""))
   })
 
+/**
+ * `gtd/<b>` when the abandon left it for `<b>` and HEAD is still on `<b>`. A
+ * `gtd/<b>` made since is reset only when the retained tip contains it — the
+ * `-C` switch would orphan anything else.
+ */
+const resumeBranch = (git: GitOperations, tip: string): Effect.Effect<string | undefined, Error> =>
+  Effect.gen(function* () {
+    if (Option.isNone(yield* git.readRefOption(RESUME_BRANCH_REF))) return undefined
+    const current = yield* git.currentBranch()
+    if (Option.isNone(current) || current.value.startsWith(GTD_BRANCH_PREFIX)) return undefined
+    const branch = `${GTD_BRANCH_PREFIX}${current.value}`
+    const existing = yield* git.readRefOption(`refs/heads/${branch}`)
+    if (Option.isSome(existing) && !(yield* git.isAncestor(existing.value, tip))) {
+      return yield* Effect.fail(
+        new Error(
+          `gtd restore: branch ${branch} holds commits the retained tip ${tip.slice(0, 7)} does not — merge or delete it first`,
+        ),
+      )
+    }
+    return branch
+  })
+
 /**
  * `gtd restore`: hard-reset HEAD back to the tip `gtd abandon` retained.
  *
@@ -834,7 +911,10 @@ const runRestoreCommand = (
     const tip = retained.value
 
     const headHash = yield* git.resolveRef("HEAD")
-    const check = yield* restorability(git, headHash, tip)
+    // Abandon after a ship leaves HEAD on `<b>` at the bare ship commit: its `Gtd-Tip` is on the retained tip.
+    const shippedTip = parseCommitMessage(yield* git.lastCommitMessage(headHash)).tip
+    const atShip = shippedTip !== undefined && (yield* git.isAncestor(shippedTip, tip))
+    const check = atShip ? { ok: true as const } : yield* restorability(git, headHash, tip)
     if (!check.ok) {
       return yield* Effect.fail(
         new Error(
@@ -847,9 +927,14 @@ const runRestoreCommand = (
     // A preview of the resulting state, resolved at tip directly since no reset has happened yet.
     const after = yield* restAt(tip)
 
+    const resumeOn = yield* resumeBranch(git, tip)
     const steps: EmitStep[] = [
-      { kind: "gitWrite", command: hardResetTo(tip) },
+      {
+        kind: "gitWrite",
+        command: resumeOn === undefined ? hardResetTo(tip) : switchBranchTo(resumeOn, tip),
+      },
       { kind: "gitWrite", command: deleteRef(HISTORY_REF) },
+      { kind: "gitWrite", command: deleteRef(RESUME_BRANCH_REF) },
       { kind: "outcome", command: restoredOutcome(tip, after.state) },
     ]
     const required = emitScripts(steps).required
@@ -1204,6 +1289,17 @@ const computeNextMatch = (rest: Rest): Effect.Effect<NextMatch | null> =>
     (target) => (target === undefined ? null : { target }),
   )
 
+/** A validator retry's content is the correction; a session that cannot resume needs the original prompt too, and one that can hands a driver that loses it `fresh`. */
+const retryContent = (
+  kind: BeatKind,
+  rendered: RenderedRest,
+  resumes: boolean,
+): { readonly rendered: RenderedRest; readonly fresh?: string } => {
+  if (kind !== "prompt" || rendered.original === undefined) return { rendered }
+  const joined = `${rendered.original}\n\n${rendered.content}`
+  return resumes ? { rendered, fresh: joined } : { rendered: { ...rendered, content: joined } }
+}
+
 /** Everything one beat needs beyond the resolved rest itself, gathered once so plain/`--json` can never describe different rests for the same beat — built as `wire`'s `Demand` (what to do) and `BeatStatus` (what no driver branches on), then flattened by `beatDocument` into the one wire-shaped object plain/`--json` both render from. */
 const gatherBeatDocument = (
   rest: Rest,
@@ -1222,9 +1318,11 @@ const gatherBeatDocument = (
         ? resolvedValidate.script
         : undefined
     const log = yield* loopLogPath
+    const retry = retryContent(kind, rendered, session?.resume === true)
     const demand = demandOf({
-      rendered,
+      rendered: retry.rendered,
       kind,
+      ...(retry.fresh !== undefined ? { fresh: retry.fresh } : {}),
       ...(session !== undefined
         ? { session: { id: session.sessionId, resume: session.resume } }
         : {}),

package/src/edge/Edge.test.ts

@@ -100,7 +100,8 @@ const applied = (repo: InMemRepo, script: string): string => {
 /**
  * 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.
+ * commit, or the closing commit when the turn led to the unpin (which leaves
+ * HEAD back on the user's branch).
  */
 const land = async (repo: InMemRepo, files: Files = {}): Promise<string> => {
   write(repo, files)
@@ -108,7 +109,8 @@ const land = async (repo: InMemRepo, files: Files = {}): Promise<string> => {
   if (exitCode !== 0) throw new Error(`gtd land exited ${exitCode}: ${stderr}${stdout}`)
   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 branch = repo.branchName()
+  return (await takePinBeat(repo, "remove")) ? headOf(repo, `refs/heads/${branch}`) : turn
 }
 
 const enter = async (repo: InMemRepo, workflow: string, ...vars: string[]): Promise<string> => {
@@ -206,7 +208,8 @@ 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(check): gtd:unpin → idle")
+    expect(repo.lastCommitSubject(closing)).toBe("gtd(check): gtd:unpin → idle")
+    repo.checkoutBranch("gtd/main")
     const next = await land(repo, { "d.txt": "d\n" })
     const run = await provide(currentRun, repo)
     expect(run.startParentHash).toBe(closing)
@@ -413,7 +416,12 @@ export const again = workflow(async () => {
       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: "checking", actor: "agent", 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 () => {
@@ -429,7 +437,12 @@ export const again = workflow(async () => {
       await land(repo)
       expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 4")
       const run = await provide(currentRun, repo)
-      expect(run.headTurn).toEqual({ state: "building", actor: "agent", empty: true, step: false })
+      expect(run.headTurn).toEqual({
+        state: "building",
+        actor: "agent",
+        empty: true,
+        step: false,
+      })
     })
 
     it("is undefined at a non-gtd HEAD", async () => {
@@ -560,7 +573,7 @@ describe("summaryRun", () => {
 
     const ordinary = await provide(currentRun, repo)
     expect(ordinary.trace).toEqual([])
-    expect(ordinary.startParentHash).toBe(closing)
+    expect(ordinary.startParentHash).toBe(boundary)
 
     const summary = await provide(summaryRun, repo)
     expect(summary.closingHash).toBe(closing)
@@ -645,14 +658,17 @@ describe("process marks", () => {
   })
 })
 
-const withTipMessage = (repo: InMemRepo, edit: (message: string) => string): GitOperations => {
+const withTipMessage = (
+  repo: InMemRepo,
+  edit: (message: string) => string,
+  edited = repo.resolveRef("HEAD"),
+): GitOperations => {
   const real = fakeGitOperations(repo)
-  const head = repo.resolveRef("HEAD")
   return {
     ...real,
     commitHistory: (base, tip) =>
       Effect.map(real.commitHistory(base, tip), (commits) =>
-        commits.map((c) => (c.hash === head ? { ...c, message: edit(c.message) } : c)),
+        commits.map((c) => (c.hash === edited ? { ...c, message: edit(c.message) } : c)),
       ),
   }
 }
@@ -683,7 +699,8 @@ export default workflow(async () => {
     if (exitCode !== 0) throw new Error(`gtd land exited ${exitCode}: ${stderr}${stdout}`)
     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 branch = repo.branchName()
+    return (await takePinBeat(repo, "remove")) ? headOf(repo, `refs/heads/${branch}`) : turn
   }
   type Rendered = {
     entryCommit: string
@@ -1366,7 +1383,7 @@ describe("finishing landings keep history", () => {
     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())
+    expect(landing.spec.branch).toBe("main")
   })
 
   it("restart() is a finish too", async () => {
@@ -1647,8 +1664,10 @@ export default async () => {
 
   it("warns, never refuses, when the recorded version differs", async () => {
     const { repo, tip } = await finished()
-    const git = withTipMessage(repo, (m) =>
-      m.replace(`Gtd-Version: ${GTD_VERSION}`, "Gtd-Version: 0.0.1"),
+    const git = withTipMessage(
+      repo,
+      (m) => m.replace(`Gtd-Version: ${GTD_VERSION}`, "Gtd-Version: 0.0.1"),
+      tip,
     )
     const trail = await Effect.runPromise(
       historyTrail(tip).pipe(
@@ -1663,7 +1682,7 @@ export default async () => {
 
   it("a missing recorded version counts as different", async () => {
     const { repo, tip } = await finished()
-    const git = withTipMessage(repo, (m) => m.replace(/Gtd-Version: .*\n?/, ""))
+    const git = withTipMessage(repo, (m) => m.replace(/Gtd-Version: .*\n?/, ""), tip)
     const trail = await Effect.runPromise(
       historyTrail(tip).pipe(
         Effect.provideService(GitService, git),
@@ -1677,8 +1696,10 @@ export default async () => {
   it("reads a recorded version carrying control bytes as unknown", async () => {
     const { repo, tip } = await finished()
     const raw = "1.0\u001b]0;x\u0007"
-    const git = withTipMessage(repo, (m) =>
-      m.replace(`Gtd-Version: ${GTD_VERSION}`, `Gtd-Version: ${raw}`),
+    const git = withTipMessage(
+      repo,
+      (m) => m.replace(`Gtd-Version: ${GTD_VERSION}`, `Gtd-Version: ${raw}`),
+      tip,
     )
     const trail = await Effect.runPromise(
       historyTrail(tip).pipe(