@pmelab/gtd 62.1.0 → 64.0.0

package/src/platform/Workspace.ts

@@ -1,38 +1,22 @@
-import { execFileSync } from "node:child_process"
-import { createHash } from "node:crypto"
-import {
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  readlinkSync,
-  renameSync,
-  writeFileSync,
-} from "node:fs"
-import { dirname, isAbsolute, join } from "node:path"
-import { Context, Effect, Layer } from "effect"
+import { Context, Effect, Layer, Path } from "effect"
 import { GitService, type GitOperations } from "./Git.js"
-import { Host } from "./Host.js"
+import { Host, type HostOps } from "./Host.js"
+import { nodeSyncIo } from "./NodeSync.js"
+import type { SyncIo } from "./SyncIo.js"
 
 const toError = (e: unknown): Error => (e instanceof Error ? e : new Error(String(e)))
 
-// A tree listing, or one committed file, can overflow execFileSync's 1 MB default.
-const MAX_BUFFER = 256 * 1024 * 1024
 const HASH_CHUNK = 500
+const encoder = new TextEncoder()
 
 /** A full sha1 or sha256 object id — the only refs an immutable, disk-cached read is safe to key on. */
 const isObjectHash = (ref: string): boolean => /^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(ref)
 
 const GTD_CACHE_SUBDIR = "gtd-cache"
 
-const treeCachePath = (commonDir: string, hash: string): string =>
-  join(commonDir, GTD_CACHE_SUBDIR, "trees", hash)
-
-const blobCachePath = (commonDir: string, id: string): string =>
-  join(commonDir, GTD_CACHE_SUBDIR, "blobs", id)
-
-const readTextCache = (path: string): string | undefined => {
+const readTextCache = (io: SyncIo, path: string): string | undefined => {
   try {
-    return readFileSync(path, "utf8")
+    return io.readText(path)
   } catch {
     return undefined
   }
@@ -46,20 +30,26 @@ const readTextCache = (path: string): string | undefined => {
  * cache is a best-effort speedup, never a correctness dependency, and the
  * alternative — failing a gtd command over a cache write — is worse.
  */
-const writeTextCacheAtomic = (path: string, content: string): void => {
+const writeTextCacheAtomic = (
+  io: SyncIo,
+  paths: Path.Path,
+  pid: number,
+  path: string,
+  content: string,
+): void => {
   try {
-    mkdirSync(dirname(path), { recursive: true })
-    const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`
-    writeFileSync(tmp, content, "utf8")
-    renameSync(tmp, path)
+    io.makeDirectory(paths.dirname(path))
+    const tmp = `${path}.tmp-${pid}-${Math.random().toString(36).slice(2)}`
+    io.writeText(tmp, content)
+    io.rename(tmp, path)
   } catch {
     // A full disk or read-only git dir silently disables the cache.
   }
 }
 
 /** A commit's `path → blob id` map, serialized as JSON. `undefined` on ANY read failure — missing, truncated, unparseable — so the caller falls back to asking git. */
-const readTreeCache = (commonDir: string, hash: string): Map<string, string> | undefined => {
-  const raw = readTextCache(treeCachePath(commonDir, hash))
+const readTreeCache = (io: SyncIo, file: string): Map<string, string> | undefined => {
+  const raw = readTextCache(io, file)
   if (raw === undefined) return undefined
   try {
     const parsed: unknown = JSON.parse(raw)
@@ -75,8 +65,13 @@ const readTreeCache = (commonDir: string, hash: string): Map<string, string> | u
   }
 }
 
-const writeTreeCache = (commonDir: string, hash: string, tree: ReadonlyMap<string, string>): void =>
-  writeTextCacheAtomic(treeCachePath(commonDir, hash), JSON.stringify(Object.fromEntries(tree)))
+const writeTreeCache = (
+  io: SyncIo,
+  paths: Path.Path,
+  pid: number,
+  file: string,
+  tree: ReadonlyMap<string, string>,
+): void => writeTextCacheAtomic(io, paths, pid, file, JSON.stringify(Object.fromEntries(tree)))
 
 /**
  * One raw `git log --raw` diff entry, already resolved to what it does to a
@@ -177,19 +172,14 @@ const parseLsTree = (out: string): Map<string, string> => {
  * check `ok` before doing so.
  */
 const fetchTree = (
+  io: SyncIo,
   root: string,
   ref: string,
 ): { readonly ok: boolean; readonly entries: Map<string, string> } => {
   try {
     return {
       ok: true,
-      entries: parseLsTree(
-        execFileSync("git", ["ls-tree", "-r", "-z", "--full-tree", ref], {
-          cwd: root,
-          encoding: "utf8",
-          maxBuffer: MAX_BUFFER,
-        }),
-      ),
+      entries: parseLsTree(io.git(root, ["ls-tree", "-r", "-z", "--full-tree", ref])),
     }
   } catch {
     return { ok: false, entries: new Map() }
@@ -263,8 +253,8 @@ export interface WorkspaceOps {
   readonly writeAtPath: (path: string, content: string) => Effect.Effect<void, Error>
 }
 
-const assertRepoRelative = (path: string): string => {
-  if (isAbsolute(path)) {
+const assertRepoRelative = (paths: Path.Path, path: string): string => {
+  if (paths.isAbsolute(path)) {
     throw new Error(
       `Workspace: "${path}" is an absolute path — this member takes repo-relative paths only (use "atPath"/"writeAtPath" to read/write outside the repo)`,
     )
@@ -272,24 +262,6 @@ const assertRepoRelative = (path: string): string => {
   return path
 }
 
-const readFileOrAbsent = (path: string): string | undefined => {
-  try {
-    return readFileSync(path, "utf8")
-  } catch (e) {
-    if ((e as NodeJS.ErrnoException).code === "ENOENT") return undefined
-    throw e
-  }
-}
-
-const lstatOrAbsent = (path: string): ReturnType<typeof lstatSync> | undefined => {
-  try {
-    return lstatSync(path)
-  } catch (e) {
-    if ((e as NodeJS.ErrnoException).code === "ENOENT") return undefined
-    throw e
-  }
-}
-
 /** One replayed commit: its hash and the (already-`\n`-stripped) `--raw -z` body `parseRawDiff` consumes. */
 interface RawLogEntry {
   readonly hash: string
@@ -304,27 +276,24 @@ interface RawLogEntry {
  * bounds no longer match git's own history.
  */
 const runRawLogReplay = (
+  io: SyncIo,
   root: string,
   base: string | undefined,
   head: string,
   commits: readonly string[],
 ): readonly RawLogEntry[] => {
   const range = base !== undefined ? `${base}..${head}` : head
-  const out = execFileSync(
-    "git",
-    [
-      "log",
-      "--first-parent",
-      "--reverse",
-      "-z",
-      "--raw",
-      "-r",
-      "--no-abbrev",
-      "--format=%x01%H",
-      range,
-    ],
-    { cwd: root, encoding: "utf8", maxBuffer: MAX_BUFFER },
-  )
+  const out = io.git(root, [
+    "log",
+    "--first-parent",
+    "--reverse",
+    "-z",
+    "--raw",
+    "-r",
+    "--no-abbrev",
+    "--format=%x01%H",
+    range,
+  ])
   const chunks = out.split("\x01").filter((c) => c.length > 0)
   if (chunks.length !== commits.length) {
     throw new Error(
@@ -363,11 +332,19 @@ const foldRawDiffs = (
 }
 
 const makeWorkspaceOps = (
-  root: string,
+  { root, pid }: HostOps,
   git: GitOperations,
   commonDir: string | undefined,
+  paths: Path.Path,
+  io: SyncIo,
 ): WorkspaceOps => {
-  const resolveAny = (path: string): string => (isAbsolute(path) ? path : join(root, path))
+  const resolveAny = (path: string): string =>
+    paths.isAbsolute(path) ? path : paths.join(root, path)
+  const repoPath = (path: string): string => paths.join(root, assertRepoRelative(paths, path))
+  const treeCachePath = (dir: string, hash: string): string =>
+    paths.join(dir, GTD_CACHE_SUBDIR, "trees", hash)
+  const blobCachePath = (dir: string, id: string): string =>
+    paths.join(dir, GTD_CACHE_SUBDIR, "blobs", id)
 
   // Per-PROCESS memo, on the workspace instance rather than any one replay's
   // `TreeView` — an immutable key (a commit hash, a blob id) can never serve
@@ -381,18 +358,18 @@ const makeWorkspaceOps = (
     const memoHit = treeMemo.get(hash)
     if (memoHit !== undefined) return memoHit
     if (commonDir === undefined) return undefined
-    const cached = readTreeCache(commonDir, hash)
+    const cached = readTreeCache(io, treeCachePath(commonDir, hash))
     if (cached !== undefined) treeMemo.set(hash, cached)
     return cached
   }
 
   const rememberTree = (hash: string, tree: ReadonlyMap<string, string>): void => {
     treeMemo.set(hash, tree)
-    if (commonDir !== undefined) writeTreeCache(commonDir, hash, tree)
+    if (commonDir !== undefined)
+      writeTreeCache(io, paths, pid, treeCachePath(commonDir, hash), tree)
   }
 
-  const readSync = (path: string): string | undefined =>
-    readFileOrAbsent(join(root, assertRepoRelative(path)))
+  const readSync = (path: string): string | undefined => io.readText(repoPath(path))
 
   /**
    * A blob's content, keyed on its OWN id rather than a (path, ref) pair —
@@ -405,7 +382,7 @@ const makeWorkspaceOps = (
     const memoHit = blobMemo.get(id)
     if (memoHit !== undefined) return memoHit
     if (commonDir !== undefined) {
-      const cached = readTextCache(blobCachePath(commonDir, id))
+      const cached = readTextCache(io, blobCachePath(commonDir, id))
       if (cached !== undefined) {
         blobMemo.set(id, cached)
         return cached
@@ -413,23 +390,20 @@ const makeWorkspaceOps = (
     }
     let content: string
     try {
-      content = execFileSync("git", ["cat-file", "-p", id], {
-        cwd: root,
-        encoding: "utf8",
-        maxBuffer: MAX_BUFFER,
-      })
+      content = io.git(root, ["cat-file", "-p", id])
     } catch {
       return undefined
     }
     blobMemo.set(id, content)
-    if (commonDir !== undefined) writeTextCacheAtomic(blobCachePath(commonDir, id), content)
+    if (commonDir !== undefined)
+      writeTextCacheAtomic(io, paths, pid, blobCachePath(commonDir, id), content)
     return content
   }
 
   // A raw, synchronous `git show <ref>:<path>` — the sync counterpart to
   // `committed`, for replay, which can't `yield*` mid-flow. Bypasses the Effect-based `GitOperations`
   // entirely, the same escape `readSync` already takes around the Effect
-  // `FileSystem` — both are raw Node calls, not a second git abstraction.
+  // `FileSystem` — both go through the sync port, not a second git abstraction.
   // ANY failure (missing ref, missing path at that ref, git not on PATH)
   // folds to `undefined`, matching `committed`'s own catch-all-as-absence.
   //
@@ -439,17 +413,13 @@ const makeWorkspaceOps = (
   // is never cached here, since it can move mid-process (a landing commit),
   // and goes straight to `git show` as before.
   const readCommittedSync = (path: string, ref = "HEAD"): string | undefined => {
-    const relPath = assertRepoRelative(path)
+    const relPath = assertRepoRelative(paths, path)
     if (isObjectHash(ref)) {
       const id = treeSync(ref).get(relPath)
       return id === undefined ? undefined : readBlobSync(id)
     }
     try {
-      return execFileSync("git", ["show", `${ref}:${relPath}`], {
-        cwd: root,
-        encoding: "utf8",
-        maxBuffer: MAX_BUFFER,
-      })
+      return io.git(root, ["show", `${ref}:${relPath}`])
     } catch {
       return undefined
     }
@@ -464,7 +434,7 @@ const makeWorkspaceOps = (
       const cached = peekTree(ref)
       if (cached !== undefined) return cached
     }
-    const { ok, entries } = fetchTree(root, ref)
+    const { ok, entries } = fetchTree(io, root, ref)
     if (!ok) {
       if (onFailure === "throw") {
         throw new Error(`gtd: failed to read the tree at "${ref}" — git ls-tree did not succeed`)
@@ -510,7 +480,7 @@ const makeWorkspaceOps = (
         }
 
         const head = commits[commits.length - 1]!
-        const replay = runRawLogReplay(root, base, head, commits)
+        const replay = runRawLogReplay(io, root, base, head, commits)
         for (const [hash, tree] of foldRawDiffs(baseTree, replay, rememberTree))
           result.set(hash, tree)
         return result
@@ -518,13 +488,7 @@ const makeWorkspaceOps = (
       catch: toError,
     })
 
-  const gitSync = (args: readonly string[], input?: string): string =>
-    execFileSync("git", args, {
-      cwd: root,
-      encoding: "utf8",
-      maxBuffer: MAX_BUFFER,
-      ...(input !== undefined ? { input } : {}),
-    })
+  const gitSync = (args: readonly string[]): string => io.git(root, args)
 
   // A path git status reports is re-hashed the way `git add` would store it;
   // every other path keeps HEAD's blob id, so an untouched file is never
@@ -544,13 +508,13 @@ const makeWorkspaceOps = (
     for (const record of status.split("\0")) {
       if (record.length < 4) continue
       const path = record.slice(3).replace(/\/$/, "")
-      const stat = lstatOrAbsent(join(root, path))
+      const stat = io.lstat(paths.join(root, path))
       if (stat === undefined) entries.delete(path)
-      else if (stat.isSymbolicLink()) {
-        entries.set(path, blobId(readlinkSync(join(root, path), "utf8")))
-      } else if (stat.isDirectory()) {
+      else if (stat.type === "symlink") {
+        entries.set(path, blobId(io.readLink(paths.join(root, path))))
+      } else if (stat.type === "directory") {
         // Only a directory holding its own repository is committed, as a gitlink.
-        if (lstatOrAbsent(join(root, path, ".git")) === undefined) entries.delete(path)
+        if (io.lstat(paths.join(root, path, ".git")) === undefined) entries.delete(path)
         else entries.set(path, gitlinkOf(path))
       } else files.push(path)
     }
@@ -567,10 +531,7 @@ const makeWorkspaceOps = (
   /** A submodule's (or embedded repository's) checked-out commit — what `git add` records for it. */
   const gitlinkOf = (path: string): string | undefined => {
     try {
-      return execFileSync("git", ["rev-parse", "HEAD"], {
-        cwd: join(root, path),
-        encoding: "utf8",
-      }).trim()
+      return io.git(paths.join(root, path), ["rev-parse", "HEAD"]).trim()
     } catch {
       return undefined
     }
@@ -579,11 +540,8 @@ const makeWorkspaceOps = (
   let objectFormat: string | undefined
   const blobId = (content: string): string => {
     objectFormat ??= gitSync(["rev-parse", "--show-object-format"]).trim()
-    const bytes = Buffer.from(content, "utf8")
-    return createHash(objectFormat === "sha256" ? "sha256" : "sha1")
-      .update(`blob ${bytes.length}\0`)
-      .update(bytes)
-      .digest("hex")
+    const bytes = encoder.encode(content)
+    return io.hash(objectFormat === "sha256" ? "sha256" : "sha1", `blob ${bytes.length}\0`, bytes)
   }
 
   return {
@@ -594,19 +552,19 @@ const makeWorkspaceOps = (
     read: (path) => Effect.try({ try: () => readSync(path), catch: toError }),
     write: (path, content) =>
       Effect.try({
-        try: () => writeFileSync(join(root, assertRepoRelative(path)), content, "utf8"),
+        try: () => io.writeText(repoPath(path), content),
         catch: toError,
       }),
     committed: (path, ref = "HEAD") =>
-      Effect.try({ try: () => assertRepoRelative(path), catch: toError }).pipe(
+      Effect.try({ try: () => assertRepoRelative(paths, path), catch: toError }).pipe(
         Effect.flatMap((relPath) =>
           git.readFileAtRef(ref, relPath).pipe(Effect.catch(() => Effect.succeed(undefined))),
         ),
       ),
     readCommittedSync,
-    atPath: (path) => readFileOrAbsent(resolveAny(path)),
+    atPath: (path) => io.readText(resolveAny(path)),
     writeAtPath: (path, content) =>
-      Effect.try({ try: () => writeFileSync(resolveAny(path), content, "utf8"), catch: toError }),
+      Effect.try({ try: () => io.writeText(resolveAny(path), content), catch: toError }),
   }
 }
 
@@ -614,8 +572,9 @@ export class Workspace extends Context.Service<Workspace, WorkspaceOps>()("Works
   static Live = Layer.effect(
     Workspace,
     Effect.gen(function* () {
-      const { root } = yield* Host
+      const host = yield* Host
       const git = yield* GitService
+      const paths = yield* Path.Path
       // Resolved once per process, not lazily inside a sync method: the
       // common dir is git's own concern to answer, and every cache read/
       // write below is synchronous. A repo whose common dir can't be
@@ -625,7 +584,7 @@ export class Workspace extends Context.Service<Workspace, WorkspaceOps>()("Works
       const commonDir = yield* git
         .gitCommonDir()
         .pipe(Effect.catch(() => Effect.succeed(undefined)))
-      return makeWorkspaceOps(root, git, commonDir)
+      return makeWorkspaceOps(host, git, commonDir, paths, nodeSyncIo)
     }),
   )
 }

package/src/platform/WorktreeState.test.ts

@@ -11,14 +11,14 @@ import { join } from "node:path"
 import { mkdtempSync, realpathSync } from "node:fs"
 import { execSync } from "node:child_process"
 import { tmpdir } from "node:os"
-import { Effect, Layer } from "effect"
+import { Effect, Layer, type Path } from "effect"
 import { describe, expect, it } from "vitest"
 import { loopLogPath, worktreeGitDir } from "./WorktreeState.js"
 import { GitService, Host, Workspace, NodeServices } from "./index.js"
 import { InMemRepo, testLayers } from "../twins/index.js"
 
 const provide = <A>(
-  eff: Effect.Effect<A, never, Host | Workspace>,
+  eff: Effect.Effect<A, never, Host | Path.Path | Workspace>,
   repo: InMemRepo,
   opts: {
     readonly root?: string
@@ -112,9 +112,13 @@ describe("worktreeGitDir [real git]", () => {
   const runIn = (root: string) => {
     const hostLayer = Host.layer({ root, home: root, env: {} })
     const gitLayer = GitService.Live.pipe(Layer.provide(Layer.merge(hostLayer, NodeServices.layer)))
-    const workspaceLayer = Workspace.Live.pipe(Layer.provide(Layer.merge(hostLayer, gitLayer)))
+    const workspaceLayer = Workspace.Live.pipe(
+      Layer.provide(Layer.mergeAll(hostLayer, gitLayer, NodeServices.layer)),
+    )
     return Effect.runPromise(
-      worktreeGitDir.pipe(Effect.provide(Layer.mergeAll(hostLayer, workspaceLayer))),
+      worktreeGitDir.pipe(
+        Effect.provide(Layer.mergeAll(hostLayer, workspaceLayer, NodeServices.layer)),
+      ),
     )
   }
 

package/src/platform/WorktreeState.ts

@@ -1,5 +1,4 @@
-import { isAbsolute, join } from "node:path"
-import { Effect } from "effect"
+import { Effect, Path } from "effect"
 import { Host } from "./Host.js"
 import { Workspace } from "./Workspace.js"
 
@@ -11,9 +10,10 @@ const GITDIR_POINTER = /^gitdir:\s*(.+)$/m
  * read failure or a `.git` file with no `gitdir:` line both fall back to
  * `".git"`, which is also correct for the in-memory test tier.
  */
-export const worktreeGitDir: Effect.Effect<string, never, Host | Workspace> = Effect.gen(
-  function* () {
+export const worktreeGitDir: Effect.Effect<string, never, Host | Path.Path | Workspace> =
+  Effect.gen(function* () {
     const { root } = yield* Host
+    const path = yield* Path.Path
     const workspace = yield* Workspace
     const content = yield* workspace
       .read(".git")
@@ -21,9 +21,8 @@ export const worktreeGitDir: Effect.Effect<string, never, Host | Workspace> = Ef
     const pointer = content === undefined ? null : GITDIR_POINTER.exec(content)
     if (pointer === null) return ".git"
     const gitdir = pointer[1]!.trim()
-    return isAbsolute(gitdir) ? gitdir : join(root, gitdir)
-  },
-)
+    return path.isAbsolute(gitdir) ? gitdir : path.join(root, gitdir)
+  })
 
 /**
  * The per-worktree loop log path `gtd next --json` reports as `log`.
@@ -34,17 +33,20 @@ export const worktreeGitDir: Effect.Effect<string, never, Host | Workspace> = Ef
  * doesn't want that (e.g. the e2e suite) must scrub it before invoking gtd.
  * Advisory only — gtd neither creates nor truncates the file.
  */
-export const loopLogPath: Effect.Effect<string, never, Host | Workspace> = Effect.gen(function* () {
-  const { root, env } = yield* Host
-  const override = env.GTD_LOOP_LOG
-  if (override !== undefined && override !== "") return override
+export const loopLogPath: Effect.Effect<string, never, Host | Path.Path | Workspace> = Effect.gen(
+  function* () {
+    const { root, env } = yield* Host
+    const path = yield* Path.Path
+    const override = env.GTD_LOOP_LOG
+    if (override !== undefined && override !== "") return override
 
-  const gitDirEnv = env.GIT_DIR
-  if (gitDirEnv !== undefined && gitDirEnv !== "") {
-    const gitDir = isAbsolute(gitDirEnv) ? gitDirEnv : join(root, gitDirEnv)
-    return join(gitDir, "gtd-loop.log")
-  }
+    const gitDirEnv = env.GIT_DIR
+    if (gitDirEnv !== undefined && gitDirEnv !== "") {
+      const gitDir = path.isAbsolute(gitDirEnv) ? gitDirEnv : path.join(root, gitDirEnv)
+      return path.join(gitDir, "gtd-loop.log")
+    }
 
-  const gitDir = yield* worktreeGitDir
-  return join(gitDir, "gtd-loop.log")
-})
+    const gitDir = yield* worktreeGitDir
+    return path.join(gitDir, "gtd-loop.log")
+  },
+)

package/src/platform/index.ts

@@ -1,7 +1,8 @@
 /**
- * gtd's two ports onto its environment: `Workspace` (repo file content —
- * working-tree reads/writes plus the read-at-ref path) and `Host` (root,
- * home, env, scratch). `GitService` moved in alongside `Workspace` since
+ * gtd's ports onto its environment: `Workspace` (repo file content —
+ * working-tree reads/writes plus the read-at-ref path), `Host` (root,
+ * home, env, scratch, process identity, stdio) and `SyncIo`, the reads that
+ * must stay synchronous, which only `Node*.ts` implements against Node. `GitService` moved in alongside `Workspace` since
  * `committed` IS `git.readFileAtRef` — one module owns every read.
  *
  * Seam rule, stated once: a seam is a `Context.Service` unless the consuming
@@ -9,7 +10,14 @@
  * reads are that exception, and use the `*Sync` members.
  */
 export { Workspace, type WorkspaceOps } from "./Workspace.js"
-export { Host, type HostOps } from "./Host.js"
+export {
+  Host,
+  nodeStdio,
+  scratchDirOf,
+  type HostOps,
+  type NodeProcess,
+  type Stdio,
+} from "./Host.js"
 export {
   GitService,
   type GitOperations,
@@ -29,4 +37,9 @@ export {
   readRetainedHistory,
   restorability,
 } from "./RetainedHistory.js"
-export { livePinFile, runPinModule, type PinFile } from "./PinFile.js"
+export { livePinFile, runPinModule } from "./NodePinFile.js"
+export type { PinFile } from "./PinFile.js"
+export type { FileInfo, SyncIo } from "./SyncIo.js"
+export { nodeSyncIo } from "./NodeSync.js"
+export { pureHash } from "./Sha.js"
+export * as NodeRuntime from "./NodeRuntime.js"

package/src/replay/Format.test.ts

@@ -3,11 +3,13 @@ import { formatCommitMessage, formatFault, parseCommitMessage } from "./index.js
 
 describe("the history format", () => {
   it("accepts a history in the current format and in the one before it", () => {
-    expect(formatFault([{ hash: "a".repeat(40), format: 2 }])).toBeUndefined()
+    expect(formatFault([{ hash: "a".repeat(40), format: 4 }])).toBeUndefined()
     expect(
       formatFault([
         { hash: "a".repeat(40), format: 1 },
         { hash: "b".repeat(40), format: 2 },
+        { hash: "c".repeat(40), format: 3 },
+        { hash: "d".repeat(40), format: 4 },
       ]),
     ).toBeUndefined()
     expect(formatFault([])).toBeUndefined()
@@ -16,11 +18,11 @@ describe("the history format", () => {
   it("names the first foreign commit, the found and readable formats, and what to do", () => {
     const fault = formatFault([
       { hash: "a".repeat(40), format: 1 },
-      { hash: "b".repeat(40), format: 3 },
-      { hash: "c".repeat(40), format: 4 },
+      { hash: "b".repeat(40), format: 5 },
+      { hash: "c".repeat(40), format: 6 },
     ])
     expect(fault).toBe(
-      "gtd: commit bbbbbbb is written in history format 3, but this gtd reads formats 1 to 2 — run a gtd release that reads format 3 to continue this process",
+      "gtd: commit bbbbbbb is written in history format 5, but this gtd reads formats 1 to 4 — run a gtd release that reads format 5 to continue this process",
     )
   })
 })
@@ -35,8 +37,8 @@ describe("Gtd-Approved and the history format", () => {
     expect(message).toContain(
       'Gtd-Approved: {"step":"seam#1","name":"Test","email":"test@test.com"}',
     )
-    expect(message).toContain("Gtd-Format: 2")
-    expect(parseCommitMessage(message).format).toBe(2)
+    expect(message).toContain("Gtd-Format: 4")
+    expect(parseCommitMessage(message).format).toBe(4)
   })
 })
 
@@ -44,19 +46,39 @@ describe("Gtd-Pin", () => {
   it("round-trips add and remove, after Gtd-Mark and before Gtd-Branch", () => {
     const message = formatCommitMessage({
       actor: "check",
-      from: "unpin",
+      from: "gtd:unpin",
       to: "idle",
       pin: "remove",
       branch: "main",
     })
     expect(message).toBe(
-      "gtd(check): unpin → idle\n\nGtd-Pin: remove\nGtd-Branch: main\nGtd-Format: 2",
+      "gtd(check): gtd:unpin → idle\n\nGtd-Pin: remove\nGtd-Branch: main\nGtd-Format: 4",
     )
     expect(parseCommitMessage(message).pin).toBe("remove")
-    expect(parseCommitMessage("gtd(check): pin → a\n\nGtd-Pin: add").pin).toBe("add")
+    expect(parseCommitMessage("gtd(check): gtd:pin → a\n\nGtd-Pin: add").pin).toBe("add")
   })
 
   it("reads an unknown value as no pin", () => {
-    expect(parseCommitMessage("gtd(check): pin → a\n\nGtd-Pin: frozen").pin).toBeUndefined()
+    expect(parseCommitMessage("gtd(check): gtd:pin → a\n\nGtd-Pin: frozen").pin).toBeUndefined()
+  })
+})
+
+describe("Gtd-Anchor", () => {
+  it("round-trips after Gtd-Pin, and reads a non-hash value as no anchor", () => {
+    const anchor = "a".repeat(40)
+    const message = formatCommitMessage({
+      actor: "check",
+      from: "gtd:pin",
+      to: "b",
+      pin: "add",
+      anchor,
+    })
+    expect(message).toBe(
+      `gtd(check): gtd:pin → b\n\nGtd-Pin: add\nGtd-Anchor: ${anchor}\nGtd-Format: 4`,
+    )
+    expect(parseCommitMessage(message).anchor).toBe(anchor)
+    expect(
+      parseCommitMessage("gtd(check): gtd:pin → b\n\nGtd-Anchor: HEAD~2").anchor,
+    ).toBeUndefined()
   })
 })

package/src/replay/Format.ts

@@ -1,7 +1,10 @@
 // Bump only when what replay reads back out of git changes incompatibly — the
 // package version must not stand in for it, since most majors leave history
-// untouched. Format 2 adds pin commits, which format 1 would replay as turns.
-export const HISTORY_FORMAT = 2
+// untouched. Format 2 adds pin commits, which format 1 would replay as turns;
+// format 3 adds the anchor, whose set-aside commits format 2 would replay;
+// format 4 renames the pin beats `gtd:pin`/`gtd:unpin`, which format 3 would
+// read as steps.
+export const HISTORY_FORMAT = 4
 const OLDEST_READABLE_FORMAT = 1
 
 const short = (hash: string): string => hash.slice(0, 7)