@pmelab/gtd 60.1.0 → 62.0.0

package/src/platform/PinFile.ts

@@ -0,0 +1,61 @@
+import { execFileSync } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { registerHooks } from "node:module"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+
+/** A process's pin as the launcher found it: the file's bytes and where its engine runs from. */
+export interface FoundPin {
+  readonly path: string
+  readonly bytes: Uint8Array
+}
+
+/**
+ * Where the launcher looks for a pin: the worktree's copy, else HEAD's — so
+ * the landing after an unpin beat deleted the file still runs on the pin.
+ */
+export type PinFile = () => FoundPin | undefined
+
+// `cwd`, as the engine's own root is: gtd runs only at the worktree root, and
+// a relocated `$GIT_DIR` leaves no `.git` to walk up to. A file that cannot be
+// read counts as no pin, so the launcher refuses it rather than crashing.
+export const livePinFile =
+  (cwd: string, path: string): PinFile =>
+  () => {
+    const file = join(cwd, path)
+    if (existsSync(file)) {
+      try {
+        return { path: file, bytes: readFileSync(file) }
+      } catch {
+        return { path: file, bytes: new Uint8Array() }
+      }
+    }
+    try {
+      const bytes = execFileSync("git", ["show", `HEAD:${path}`], {
+        cwd,
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+      return { path: file, bytes }
+    } catch {
+      return undefined
+    }
+  }
+
+/**
+ * Runs a pin's module as this process's main program. Node refuses an unknown
+ * extension, so a load hook serves the unpacked source under the pin's own
+ * URL — `import.meta.url` stays a file in the repository.
+ */
+export const runPinModule = async (path: string, source: string): Promise<void> => {
+  const url = pathToFileURL(path).href
+  // A pin read from HEAD has no file behind its URL, which Node's own resolve refuses.
+  registerHooks({
+    resolve: (specifier, context, nextResolve) =>
+      specifier === url ? { url, shortCircuit: true } : nextResolve(specifier, context),
+    load: (requested, context, nextLoad) =>
+      requested === url
+        ? { format: "module", source, shortCircuit: true }
+        : nextLoad(requested, context),
+  })
+  await import(url)
+}

package/src/platform/index.ts

@@ -29,3 +29,4 @@ export {
   readRetainedHistory,
   restorability,
 } from "./RetainedHistory.js"
+export { livePinFile, runPinModule, type PinFile } from "./PinFile.js"

package/src/replay/Format.test.ts

@@ -2,25 +2,31 @@ import { describe, expect, it } from "vitest"
 import { formatCommitMessage, formatFault, parseCommitMessage } from "./index.js"
 
 describe("the history format", () => {
-  it("accepts a history entirely in the current format", () => {
-    expect(formatFault([{ hash: "a".repeat(40), format: 1 }])).toBeUndefined()
+  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: 1 },
+        { hash: "b".repeat(40), format: 2 },
+      ]),
+    ).toBeUndefined()
     expect(formatFault([])).toBeUndefined()
   })
 
   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: 2 },
-      { hash: "c".repeat(40), format: 3 },
+      { hash: "b".repeat(40), format: 3 },
+      { hash: "c".repeat(40), format: 4 },
     ])
     expect(fault).toBe(
-      "gtd: commit bbbbbbb is written in history format 2, but this gtd reads format 1 — run a gtd release that reads format 2 to continue this process",
+      "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",
     )
   })
 })
 
 describe("Gtd-Approved and the history format", () => {
-  it("leaves Gtd-Format at 1 on a message carrying it", () => {
+  it("writes the current format on a message carrying it", () => {
     const message = formatCommitMessage({
       actor: "human",
       to: "b",
@@ -29,7 +35,28 @@ 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: 1")
-    expect(parseCommitMessage(message).format).toBe(1)
+    expect(message).toContain("Gtd-Format: 2")
+    expect(parseCommitMessage(message).format).toBe(2)
+  })
+})
+
+describe("Gtd-Pin", () => {
+  it("round-trips add and remove, after Gtd-Mark and before Gtd-Branch", () => {
+    const message = formatCommitMessage({
+      actor: "check",
+      from: "unpin",
+      to: "idle",
+      pin: "remove",
+      branch: "main",
+    })
+    expect(message).toBe(
+      "gtd(check): unpin → idle\n\nGtd-Pin: remove\nGtd-Branch: main\nGtd-Format: 2",
+    )
+    expect(parseCommitMessage(message).pin).toBe("remove")
+    expect(parseCommitMessage("gtd(check): 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()
   })
 })

package/src/replay/Format.ts

@@ -1,14 +1,17 @@
 // 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. A bump that keeps reading the previous format widens the check below.
-export const HISTORY_FORMAT = 1
+// untouched. Format 2 adds pin commits, which format 1 would replay as turns.
+export const HISTORY_FORMAT = 2
+const OLDEST_READABLE_FORMAT = 1
 
 const short = (hash: string): string => hash.slice(0, 7)
 
 export const formatFault = (
   commits: readonly { readonly hash: string; readonly format: number }[],
 ): string | undefined => {
-  const foreign = commits.find((c) => c.format !== HISTORY_FORMAT)
+  const foreign = commits.find(
+    (c) => c.format < OLDEST_READABLE_FORMAT || c.format > HISTORY_FORMAT,
+  )
   if (foreign === undefined) return undefined
-  return `gtd: commit ${short(foreign.hash)} is written in history format ${foreign.format}, but this gtd reads format ${HISTORY_FORMAT} — run a gtd release that reads format ${foreign.format} to continue this process`
+  return `gtd: commit ${short(foreign.hash)} is written in history format ${foreign.format}, but this gtd reads formats ${OLDEST_READABLE_FORMAT} to ${HISTORY_FORMAT} — run a gtd release that reads format ${foreign.format} to continue this process`
 }

package/src/replay/Replay.test.ts

@@ -6,6 +6,7 @@ import {
   changes,
   changesSince,
   codeThreads,
+  head,
   human,
   judge,
   kept,
@@ -1217,3 +1218,56 @@ describe("human({ approve })", () => {
     expect(outcome.kind).toBe("rest")
   })
 })
+
+describe("pin commits", () => {
+  const PIN = ".gtd/process.gtdpin"
+  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" })
+
+  it("are never a turn: the next step answers from the commit after the pin", async () => {
+    const flow = async () => {
+      await human("idle")
+      await agent("build", "b")
+      await agent("check", "c")
+    }
+    const h = pinned().land("agent", "build", 1, "check", { "a.ts": "a" })
+    expect(restName(await replayOf(flow, h))).toBe("check#1")
+  })
+
+  it("hide the pin from every tree flow code reads, so a turn's changes leave it out", async () => {
+    let seen: { readonly changed: readonly string[]; readonly pin: string | undefined } | undefined
+    const flow = async () => {
+      await human("idle")
+      await agent("build", "b")
+      seen = { changed: changes().map((c) => c.path), pin: read(PIN) }
+      await agent("check", "c")
+    }
+    const h = pinned().land("agent", "build", 1, "check", { "a.ts": "a" })
+    await replayOf(flow, h)
+    expect(seen).toEqual({ changed: ["a.ts"], pin: undefined })
+  })
+
+  it("are never what head() names: a flow reverting the start reverts the turn", async () => {
+    let named: string | undefined
+    const flow = async () => {
+      await human("idle")
+      named = head()
+      await agent("build", "b")
+    }
+    await replayOf(flow, pinned())
+    expect(named).toBe(hashOf(1))
+  })
+
+  it("trailing an ended flow are no divergence", async () => {
+    const flow = async () => {
+      await human("idle")
+      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 })
+    expect((await replayOf(flow, h)).kind).toBe("ended")
+  })
+})

package/src/replay/Replay.ts

@@ -20,17 +20,20 @@ import {
   threads,
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
-import { globMatches } from "../wire/index.js"
+import { globMatches, PIN_PATH } from "../wire/index.js"
 import { refNameFault } from "./RefName.js"
-import { diffTrees, isEmptyDiff, type TreeView } from "./Tree.js"
+import { diffTrees, isEmptyDiff, withoutPath, type TreeView } from "./Tree.js"
 import {
   formatStepId,
   parseCommitMessage,
   type CommitMessage,
   type JudgeVerdict,
   type StepId,
+  PIN_STATES,
 } from "./Trailers.js"
 
+const UNPIN_STATE = PIN_STATES.remove
+
 export interface EpisodeCommit {
   readonly hash: string
   readonly message: string
@@ -297,7 +300,29 @@ const modeWithoutFile = (step: ReachedStep): string | undefined => {
   return `gtd: step "${step.name}": mode requires file in ${step.kind}() options — name the steering file the mode checks`
 }
 
-export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
+// The pin is the engine's, not the process's: flow code never sees it, so a
+// pin commit is an empty diff replay can step over.
+const withoutPin = (input: ReplayInput): ReplayInput => {
+  const hide = (tree: TreeView): TreeView => withoutPath(tree, PIN_PATH)
+  return {
+    ...input,
+    episode: {
+      base: { ...input.episode.base, tree: hide(input.episode.base.tree) },
+      commits: input.episode.commits.map((c) => ({
+        ...c,
+        tree: hide(c.tree),
+        ...(c.kept !== undefined ? { kept: { ...c.kept, tree: hide(c.kept.tree) } } : {}),
+      })),
+    },
+    ...(input.startTree !== undefined ? { startTree: hide(input.startTree) } : {}),
+    ...(input.pending !== undefined
+      ? { pending: { ...input.pending, tree: hide(input.pending.tree) } }
+      : {}),
+  }
+}
+
+export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
+  const input = withoutPin(raw)
   const commits: readonly ParsedCommit[] = input.episode.commits.map((c) => ({
     ...c,
     parsed: parseCommitMessage(c.message),
@@ -317,6 +342,11 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   let cursor = 0
   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.
+  const skipPins = (): void => {
+    while (cursor < commits.length && commits[cursor]!.parsed.pin !== undefined) cursor++
+  }
   let previousPosition: Position = input.episode.base
   let expectedNext: { readonly name: string; readonly hash: string } | undefined
   const occurrences = new Map<string, number>()
@@ -560,20 +590,25 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     if (unapproved !== undefined) return finish(unapproved)
     cursor++
     advance(commit)
-    if (commit.parsed.kept !== undefined) {
-      if (commit.kept === undefined) keptTips.delete(step.name)
-      else
-        keptTips.set(step.name, {
-          hash: commit.kept.hash,
-          before: commit.tree,
-          after: commit.kept.tree,
-        })
-    }
+    skipPins()
+    noteKept(step, commit)
     const to = commit.parsed.parsed?.to
-    if (to !== undefined) expectedNext = { name: to, hash: commit.hash }
+    // 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 => {
+    if (commit.parsed.kept === undefined) return
+    if (commit.kept === undefined) keptTips.delete(step.name)
+    else
+      keptTips.set(step.name, {
+        hash: commit.kept.hash,
+        before: commit.tree,
+        after: commit.kept.tree,
+      })
+  }
+
   const landPending = (step: ReachedStep, pending: NonNullable<typeof input.pending>): unknown => {
     pendingUsed = true
     landed = step
@@ -587,7 +622,10 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   }
 
   const answer = (step: ReachedStep): unknown => {
-    while (cursor < commits.length && isAttemptAt(commits[cursor]!, step.name)) cursor++
+    while (cursor < commits.length && isAttemptAt(commits[cursor]!, step.name)) {
+      cursor++
+      skipPins()
+    }
     const commit = commits[cursor]
     if (commit !== undefined) return consumeCommit(step, commit)
     if (input.pending === undefined || pendingUsed) {
@@ -604,6 +642,9 @@ export const replay = async (input: 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 (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)`
     }
@@ -636,13 +677,15 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     return blocker === undefined ? answer(step) : finish(blocker)
   }
 
-  const endOfFlow = (via: "return" | "restart"): ReplayOutcome =>
-    cursor < commits.length
+  const endOfFlow = (via: "return" | "restart"): ReplayOutcome => {
+    skipPins()
+    return cursor < commits.length
       ? {
           kind: "divergence",
           message: `gtd: the flow ended, but commit ${short(commits[cursor]!.hash)} continues the episode — ${DIVERGED}`,
         }
       : { kind: "ended", via, trace, landed, marks }
+  }
 
   const changesSince = (hash: string): readonly Change[] => {
     const tree = treeAt(hash)
@@ -714,13 +757,14 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     // At the rest, trailing attempts sit above the last step commit: the head a
     // prompt names is the commit the process actually stands on.
     head: () => {
-      const rest = commits.slice(cursor)
+      const rest = commits.slice(cursor).filter((c) => c.parsed.pin === undefined)
       return rest.length > 0 && rest.every((c) => c.parsed.step === undefined)
         ? rest[rest.length - 1]!.hash
         : position.hash
     },
   }
 
+  skipPins()
   installContext(context)
   try {
     // A pre-upgrade flow destructuring `{ entry }` reads `undefined` (an

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: 1",
+      "gtd(human): fix-precheck\n\nGtd-Workflow: fix\nGtd-Review-Base: abc\nGtd-Format: 2",
     )
     expect(parseCommitMessage(message).workflow).toBe("fix")
     expect(parseCommitMessage("gtd(human): fix-precheck").workflow).toBeUndefined()
@@ -56,47 +56,10 @@ 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: 1")
+    expect(one).toBe("gtd(human): x\n\nGtd-Var: a=1\nGtd-Var: b=2\nGtd-Var: c=\nGtd-Format: 2")
     expect(parseCommitMessage(one).vars).toEqual({ a: "1", b: "2", c: "" })
   })
 
-  it("writes Gtd-Config trailers sorted by path, after Gtd-Var, and reads paths with spaces back", () => {
-    const message = formatCommitMessage({
-      actor: "human",
-      to: "x",
-      vars: { a: "1" },
-      config: { "lib/my flow.ts": "0123456789abcdef", "gtd.config.ts": "deadbeefdeadbeef" },
-    })
-    expect(message).toBe(
-      "gtd(human): x\n\nGtd-Var: a=1\nGtd-Config: deadbeefdeadbeef gtd.config.ts\nGtd-Config: 0123456789abcdef lib/my flow.ts\nGtd-Format: 1",
-    )
-    expect(parseCommitMessage(message).config).toEqual({
-      "gtd.config.ts": "deadbeefdeadbeef",
-      "lib/my flow.ts": "0123456789abcdef",
-    })
-  })
-
-  it("round-trips a Gtd-Config path that git or the trailer syntax would alter", () => {
-    const config = {
-      " lead.ts": "0123456789abcdef",
-      "trail.ts ": "0123456789abcdef",
-      '"q.ts': "0123456789abcdef",
-    }
-    const message = formatCommitMessage({ actor: "human", to: "x", config })
-    expect(message).toContain('Gtd-Config: 0123456789abcdef " lead.ts"')
-    expect(parseCommitMessage(message).config).toEqual(config)
-  })
-
-  it("ignores a Gtd-Config trailer without a 16-digit hex hash, without a path, or with a control character in its path", () => {
-    const read = (value: string) =>
-      parseCommitMessage(`gtd(human): x\n\nGtd-Config: ${value}`).config
-    expect(read("zzzzzzzzzzzzzzzz gtd.config.ts")).toEqual({})
-    expect(read("deadbeef gtd.config.ts")).toEqual({})
-    expect(read("deadbeefdeadbeef")).toEqual({})
-    expect(read("deadbeefdeadbeef a\x1b]0;x\x07.ts")).toEqual({})
-    expect(read('deadbeefdeadbeef "a\\u001b.ts"')).toEqual({})
-  })
-
   it("round-trips Gtd-Branch and Gtd-Version, after Gtd-Judge and before Gtd-Format", () => {
     const message = formatCommitMessage({
       actor: "agent",
@@ -118,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: 1",
-        `Gtd-Version: ${value}\nGtd-Format: 1`,
+        "Gtd-Format: 2",
+        `Gtd-Version: ${value}\nGtd-Format: 2`,
       )
     expect(parseCommitMessage(withVersion("1.0\u001b]0;x\u0007")).version).toBeUndefined()
     expect(parseCommitMessage(withVersion("1.0\u009b")).version).toBeUndefined()
@@ -135,15 +98,15 @@ describe("the commit-message codec", () => {
     expect(parsed.version).toBeUndefined()
   })
 
-  it("keeps Gtd-Format at 1 when branch and version are written", () => {
+  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: 1")).toBe(true)
+    expect(message.endsWith("Gtd-Format: 2")).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: 1")
-    expect(parseCommitMessage(message).format).toBe(1)
+    expect(message).toBe("gtd(agent): building\n\nGtd-Format: 2")
+    expect(parseCommitMessage(message).format).toBe(2)
   })
 
   it("reads a message without Gtd-Format as format 1, and an explicit one as written", () => {
@@ -183,10 +146,10 @@ describe("Gtd-Kept", () => {
     expect(parseCommitMessage(`gtd(agent): a → b\n\nGtd-Kept: ${hash}0`).kept).toBeUndefined()
   })
 
-  it("reads undefined when absent, and leaves Gtd-Format at 1", () => {
+  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(1)
+    expect(parsed.format).toBe(2)
   })
 })
 
@@ -326,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: 1")
+    expect(lines).toContain("Gtd-Format: 2")
   })
 
   it("writes nothing without marks", () => {

package/src/replay/Trailers.ts

@@ -4,6 +4,7 @@
 // command unusable.
 
 import type { Mark } from "../flows/index.js"
+import type { PinMark } from "../wire/index.js"
 import { HISTORY_FORMAT } from "./Format.js"
 
 const TRANSITION_SEP = " → "
@@ -67,6 +68,11 @@ export interface Approval {
   readonly email: string
 }
 
+export type PinChange = PinMark
+
+/** 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 interface CommitMessage {
   readonly subject: string
   readonly parsed: ParsedSubject | undefined
@@ -77,8 +83,6 @@ export interface CommitMessage {
   /** `Gtd-Mark`, in order; a malformed or control-character line is skipped. */
   readonly marks: readonly Mark[]
   readonly vars: Readonly<Record<string, string>>
-  /** Written only on a process's first commit. */
-  readonly config: Readonly<Record<string, string>>
   readonly reviewBase: string | undefined
   readonly cost: readonly CostEntry[]
   /** Written only on a process's finishing landing. */
@@ -88,6 +92,8 @@ export interface CommitMessage {
   readonly kept: string | undefined
   /** `Gtd-Approved`; a malformed or control-character value is skipped. */
   readonly approved: Approval | undefined
+  /** `Gtd-Pin`: a commit that adds or removes the pin — never a turn. */
+  readonly pin: PinChange | undefined
   readonly format: number
 }
 
@@ -112,20 +118,10 @@ const parseJson = (raw: string): unknown => {
 const TRAILER_RE = /^(Gtd-[A-Za-z-]+):[ \t]*(.*?)[ \t]*$/gm
 const COST_RE = /^([0-9]+(?:\.[0-9]+)?)(?:[ \t]+(.+))?$/
 const VAR_RE = /^([^=\s]+)=(.*)$/
-const CONFIG_RE = /^([0-9a-f]{16}) (.+)$/
-// A path git's message cleanup or the trailer syntax would alter travels as a
-// JSON string. A control character is refused on read: history written by
-// someone else must never put escape sequences on a terminal.
+// A control character is refused on read: history written by someone else
+// must never put escape sequences on a terminal.
 // eslint-disable-next-line no-control-regex -- the control range IS the point
 const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/
-const encodePath = (path: string): string =>
-  path.trim() !== path || path.startsWith('"') || CONTROL_CHARACTER.test(path)
-    ? JSON.stringify(path)
-    : path
-const decodePath = (raw: string): string | undefined => {
-  const path = raw.startsWith('"') ? parseJson(raw) : raw
-  return typeof path === "string" && path !== "" && !CONTROL_CHARACTER.test(path) ? path : undefined
-}
 const decodeApproval = (raw: string): Approval | undefined => {
   const parsed = parseJson(raw)
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
@@ -156,10 +152,10 @@ interface Trailers {
   version: string | undefined
   kept: string | undefined
   approved: Approval | undefined
+  pin: PinChange | undefined
   readonly judge: JudgeVerdict[]
   readonly marks: Mark[]
   readonly vars: Record<string, string>
-  readonly config: Record<string, string>
   readonly cost: CostEntry[]
   format: number | undefined
 }
@@ -184,11 +180,6 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
     const kv = VAR_RE.exec(value)
     if (kv !== null) into.vars[kv[1]!] = kv[2]!
   },
-  "Gtd-Config": (value, into) => {
-    const entry = CONFIG_RE.exec(value)
-    const path = entry === null ? undefined : decodePath(entry[2]!)
-    if (path !== undefined) into.config[path] = entry![1]!
-  },
   "Gtd-Review-Base": (value, into) => {
     into.reviewBase ??= value.split(/\s/)[0]
   },
@@ -206,6 +197,9 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Approved": (value, into) => {
     into.approved ??= decodeApproval(value)
   },
+  "Gtd-Pin": (value, into) => {
+    if (value === "add" || value === "remove") into.pin ??= value
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -226,10 +220,10 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     version: undefined,
     kept: undefined,
     approved: undefined,
+    pin: undefined,
     judge: [],
     marks: [],
     vars: {},
-    config: {},
     cost: [],
     format: undefined,
   }
@@ -249,13 +243,13 @@ export interface CommitSpec {
   readonly workflow?: string
   readonly reviewBase?: string
   readonly vars?: Readonly<Record<string, string>>
-  readonly config?: Readonly<Record<string, string>>
   readonly cost?: { readonly cost: number; readonly model?: string }
   readonly judge?: readonly JudgeVerdict[]
   /** Written after `Gtd-Judge`, before `Gtd-Approved`. */
   readonly marks?: readonly Mark[]
   /** Written after `Gtd-Mark`, before `Gtd-Branch`. */
   readonly approved?: Approval
+  readonly pin?: PinChange
   readonly branch?: string
   readonly version?: string
 }
@@ -264,27 +258,27 @@ const sortedEntries = (record: Readonly<Record<string, string>> = {}): [string,
   Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
 
 /** Trailer order is fixed so the same spec always yields the same bytes. */
+const trailer = (name: string, value: string | undefined): readonly string[] =>
+  value === undefined ? [] : [`Gtd-${name}: ${value}`]
+
+const costValue = (cost: CommitSpec["cost"]): string | undefined =>
+  cost === undefined ? undefined : `${cost.cost}${cost.model !== undefined ? ` ${cost.model}` : ""}`
+
 export const formatCommitMessage = (spec: CommitSpec): string => {
-  const lines: string[] = []
-  if (spec.step !== undefined) lines.push(`Gtd-Step: ${formatStepId(spec.step)}`)
-  if (spec.workflow !== undefined) lines.push(`Gtd-Workflow: ${spec.workflow}`)
-  if (spec.reviewBase !== undefined) lines.push(`Gtd-Review-Base: ${spec.reviewBase}`)
-  for (const [name, value] of sortedEntries(spec.vars)) lines.push(`Gtd-Var: ${name}=${value}`)
-  for (const [path, hash] of sortedEntries(spec.config))
-    lines.push(`Gtd-Config: ${hash} ${encodePath(path)}`)
-  if (spec.cost !== undefined) {
-    lines.push(
-      `Gtd-Cost: ${spec.cost.cost}${spec.cost.model !== undefined ? ` ${spec.cost.model}` : ""}`,
-    )
-  }
-  for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`)
-  for (const m of spec.marks ?? []) lines.push(`Gtd-Mark: ${m.name}=${m.value}`)
-  if (spec.approved !== undefined) {
-    lines.push(`Gtd-Approved: ${encodeApproval(spec.approved)}`)
-  }
-  if (spec.branch !== undefined) lines.push(`Gtd-Branch: ${spec.branch}`)
-  if (spec.version !== undefined) lines.push(`Gtd-Version: ${spec.version}`)
-  lines.push(`Gtd-Format: ${HISTORY_FORMAT}`)
+  const lines = [
+    ...trailer("Step", spec.step && formatStepId(spec.step)),
+    ...trailer("Workflow", spec.workflow),
+    ...trailer("Review-Base", spec.reviewBase),
+    ...sortedEntries(spec.vars).map(([name, value]) => `Gtd-Var: ${name}=${value}`),
+    ...trailer("Cost", costValue(spec.cost)),
+    ...(spec.judge ?? []).map((verdict) => `Gtd-Judge: ${JSON.stringify(verdict)}`),
+    ...(spec.marks ?? []).map((m) => `Gtd-Mark: ${m.name}=${m.value}`),
+    ...trailer("Approved", spec.approved && encodeApproval(spec.approved)),
+    ...trailer("Pin", spec.pin),
+    ...trailer("Branch", spec.branch),
+    ...trailer("Version", spec.version),
+    `Gtd-Format: ${HISTORY_FORMAT}`,
+  ]
   const subject = formatSubject(spec.actor, spec.to, spec.from)
   return `${subject}\n\n${lines.join("\n")}`
 }