@pmelab/gtd 60.0.0 → 61.0.0

package/src/edge/Edge.test.ts

@@ -30,6 +30,7 @@ import {
   applyEmittedScript,
   makeCapturingCliIo,
   makeInMemoryWorkspaceOps,
+  takePinBeat,
   testLayers,
 } from "../twins/index.js"
 
@@ -74,7 +75,7 @@ const write = (repo: InMemRepo, files: Files): void => {
   for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
 }
 
-const headOf = (repo: InMemRepo): string => repo.resolveRef("HEAD")!
+const headOf = (repo: InMemRepo, ref = "HEAD"): string => repo.resolveRef(ref)!
 
 const repoWith = (config: string, files: Files = {}): InMemRepo => {
   const repo = new InMemRepo()
@@ -95,19 +96,27 @@ const applied = (repo: InMemRepo, script: string): string => {
   return headOf(repo)
 }
 
-/** Lands the pending turn the way a driver does — `gtd land --json`, then its script — and returns the new HEAD. */
+/**
+ * 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.
+ */
 const land = async (repo: InMemRepo, files: Files = {}): Promise<string> => {
   write(repo, files)
   const { stdout, stderr, exitCode } = await cli(repo, "land", "--json")
   if (exitCode !== 0) throw new Error(`gtd land exited ${exitCode}: ${stderr}${stdout}`)
-  return applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+  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 enter = async (repo: InMemRepo, workflow: string, ...vars: string[]): Promise<string> => {
   const flags = vars.flatMap((v) => ["--var", v])
   const { stdout, stderr, exitCode } = await cli(repo, "start", workflow, ...flags)
   if (exitCode !== 0) throw new Error(`gtd start exited ${exitCode}: ${stderr}`)
-  return applied(repo, stdout)
+  const opening = applied(repo, stdout)
+  await takePinBeat(repo, "add")
+  return opening
 }
 
 /** Commits an exact message — for trailers no landing writes on its own. */
@@ -174,7 +183,11 @@ describe("currentRun", () => {
       { state: "checking", hash: checking, actor: "agent" },
     ])
     expect(run.episode.base).toBe(boundary)
-    expect(run.episode.commits.map((c) => c.hash)).toEqual([building, checking])
+    expect(run.episode.commits.map((c) => c.message.split("\n")[0])).toEqual([
+      "gtd(human): idle → building",
+      "gtd(check): pin → building",
+      "gtd(agent): building → checking",
+    ])
   })
 
   it("a non-gtd commit on top of a process bounds a fresh episode", async () => {
@@ -192,7 +205,7 @@ 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(agent): checking → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): unpin → idle")
     const next = await land(repo, { "d.txt": "d\n" })
     const run = await provide(currentRun, repo)
     expect(run.startParentHash).toBe(closing)
@@ -203,8 +216,8 @@ describe("currentRun", () => {
     const repo = repoWith(LINEAR)
     const before = headOf(repo)
     const opening = await enter(repo, "side")
-    expect(repo.lastCommitMessage()).toBe(
-      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Config: ${contentHash(LINEAR)} gtd.config.ts\nGtd-Format: 1`,
+    expect(repo.lastCommitMessage(opening)).toBe(
+      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Config: ${contentHash(LINEAR)} gtd.config.ts\nGtd-Format: 2`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -216,7 +229,7 @@ describe("currentRun", () => {
       { state: "tidying", hash: fixed, actor: "agent" },
     ])
     expect(run.episode.base).toBe(opening)
-    expect(run.episode.commits.map((c) => c.hash)).toEqual([fixed])
+    expect(run.episode.commits.map((c) => c.hash)).toEqual([headOf(repo, `${fixed}~1`), fixed])
   })
 
   it("a workflow starting at the default's initial step still opens its own episode, not the empty tree", async () => {
@@ -236,8 +249,8 @@ export const again = workflow(async () => {
     const repo = repoWith(STARTS_AT_INITIAL)
     const before = headOf(repo)
     const opening = await enter(repo, "again")
-    expect(repo.lastCommitMessage()).toBe(
-      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Config: ${contentHash(STARTS_AT_INITIAL)} gtd.config.ts\nGtd-Format: 1`,
+    expect(repo.lastCommitMessage(opening)).toBe(
+      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Config: ${contentHash(STARTS_AT_INITIAL)} gtd.config.ts\nGtd-Format: 2`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -374,15 +387,23 @@ export const again = workflow(async () => {
     it("describes a step commit that changed something", async () => {
       const repo = repoWith(LINEAR)
       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: "building", actor: "human", 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 () => {
+      const repo = repoWith(LINEAR)
+      await land(repo, { "a.txt": "a\n" })
+      expect(repo.lastCommitSubject()).toBe("gtd(check): pin → building")
+      expect((await provide(currentRun, repo)).headTurn).toBeUndefined()
     })
 
     it("describes an attempt: a step-less, empty commit", async () => {
       const repo = repoWith(LINEAR)
       await land(repo, { "a.txt": "a\n" })
       await land(repo)
-      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 1")
+      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 2")
       const run = await provide(currentRun, repo)
       expect(run.headTurn).toEqual({ state: "building", actor: "agent", empty: true, step: false })
     })
@@ -469,12 +490,14 @@ describe("history reads stay bounded by the episode, not the repository", () =>
     const raceyGit: GitOperations = {
       ...base,
       subjectHistory: (pageSize, skip, head) =>
-        Effect.tap(base.subjectHistory(pageSize, skip, head), () => {
-          if (!moved) {
-            moved = true
-            repo.hardResetTo(boundary)
-          }
-        }),
+        Effect.tap(base.subjectHistory(pageSize, skip, head), () =>
+          Effect.sync(() => {
+            if (!moved) {
+              moved = true
+              repo.hardResetTo(boundary)
+            }
+          }),
+        ),
     }
 
     const run = await provideWithGit(currentRun, raceyGit, repo)
@@ -521,7 +544,8 @@ describe("summaryRun", () => {
     expect(summary.trace).toEqual([
       { state: "building", hash: building, actor: "human" },
       { state: "checking", hash: checking, actor: "agent" },
-      { state: "idle", hash: closing, actor: "agent" },
+      { state: "unpin", hash: headOf(repo, `${closing}~1`), actor: "agent" },
+      { state: "idle", hash: closing, actor: "check" },
     ])
   })
 
@@ -633,7 +657,9 @@ export default workflow(async () => {
       `--model=${model}`,
     )
     if (exitCode !== 0) throw new Error(`gtd land exited ${exitCode}: ${stderr}${stdout}`)
-    return applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+    const turn = applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+    await takePinBeat(repo, "add")
+    return (await takePinBeat(repo, "remove")) ? headOf(repo) : turn
   }
   type Rendered = {
     entryCommit: string
@@ -709,6 +735,7 @@ describe("restAt", () => {
       )
       expect(exitCode).toBe(0)
       await applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+      await takePinBeat(repo, "add")
     }
     const { cost } = await provide(currentRest, repo)
     expect(cost.total).toBe(11)
@@ -804,6 +831,7 @@ export const review = workflow(async () => {
   it("is the base the resting step names", async () => {
     const repo = repoWith(LOOP)
     const first = await land(repo, { "a.txt": "a\n" })
+    expect(repo.lastCommitSubject()).toBe("gtd(check): pin → checkpoint")
     expect(reviewBaseFor(await provide(currentRest, repo))).toBe(first)
     await land(repo, { "b.txt": "b\n" })
     expect(reviewBaseFor(await provide(currentRest, repo))).toBe(first)
@@ -1041,8 +1069,8 @@ export default workflow(async () => {
 
   it("an ordinary start's first commit pins every process setting, sorted by name", async () => {
     const repo = repoWith(LINEAR)
-    await land(repo, { "a.txt": "a\n" })
-    expect(repo.lastCommitMessage()).toContain(
+    const start = await land(repo, { "a.txt": "a\n" })
+    expect(repo.lastCommitMessage(start)).toContain(
       "\n\nGtd-Step: idle#1\nGtd-Var: base=\nGtd-Var: reviewer=nobody",
     )
     await land(repo)
@@ -1263,13 +1291,34 @@ describe("finishing landings keep history", () => {
     return landing
   }
 
+  /** Lands the turn that ends the flow, and runs the unpin beat's script without landing it. */
+  const toUnpin = async (repo: InMemRepo, files: Files) => {
+    write(repo, files)
+    const turn = await cli(repo, "land", "--json")
+    applied(repo, (JSON.parse(turn.stdout) as { readonly script: string }).script)
+    const beat = await cli(repo, "next", "--json")
+    applied(repo, (JSON.parse(beat.stdout) as { readonly content: string }).content)
+  }
+
+  it("a pinned process's last turn lands at the unpin, keeping no history yet", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    repo.writeFile("c.txt", "c\n")
+    const landing = await landingOf(repo)
+    expect(landing.to).toBe("unpin")
+    expect(landing.keepHistory).toBeUndefined()
+    expect(landing.spec.version).toBeUndefined()
+  })
+
   it("flow return: keeps refs/gtd/history/<startHash>, records version and branch", async () => {
     const repo = repoWith(LINEAR)
     const building = await land(repo, { "a.txt": "a\n" })
     await land(repo, { "b.txt": "b\n" })
-    repo.writeFile("c.txt", "c\n")
+    await toUnpin(repo, { "c.txt": "c\n" })
     const landing = await landingOf(repo)
     expect(landing.to).toBe("idle")
+    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())
@@ -1285,7 +1334,7 @@ export default async () => {
 }
 `)
     const building = await land(repo, { "a.txt": "a\n" })
-    repo.writeFile("b.txt", "b\n")
+    await toUnpin(repo, { "b.txt": "b\n" })
     const landing = await landingOf(repo)
     expect(landing.to).toBe("idle")
     expect(landing.keepHistory).toBe(processHistoryRef(building))
@@ -1312,7 +1361,7 @@ export default async () => {
     const repo = repoWith(LINEAR)
     const building = await land(repo, { "a.txt": "a\n" })
     await land(repo, { "b.txt": "b\n" })
-    repo.writeFile("c.txt", "c\n")
+    await toUnpin(repo, { "c.txt": "c\n" })
     const detached: GitOperations = {
       ...fakeGitOperations(repo),
       currentBranch: () => Effect.succeed(Option.none()),
@@ -1336,7 +1385,7 @@ export const side = workflow(async () => {
 })
 `)
     const opening = await enter(repo, "side")
-    repo.writeFile("a.txt", "a\n")
+    await toUnpin(repo, { "a.txt": "a\n" })
     const landing = await landingOf(repo)
     expect(landing.to).toBe("idle")
     expect(landing.keepHistory).toBe(processHistoryRef(opening))
@@ -1466,14 +1515,20 @@ describe("historyTrail", () => {
     const trail = await provide(historyTrail(tip), repo)
     expect(trail.tip).toBe(tip)
     expect(trail.ended).toBe("return")
-    expect(trail.steps.map((s) => s.hash)).toEqual([building, checking, tip])
+    expect(trail.steps.map((s) => s.hash)).toEqual([
+      building,
+      checking,
+      headOf(repo, `${tip}~1`),
+      tip,
+    ])
     expect(trail.steps[2]).toMatchObject({
-      subject: "gtd(agent): checking → idle",
+      subject: "gtd(agent): checking → unpin",
       actor: "agent",
       from: "checking",
-      to: "idle",
+      to: "unpin",
       verdicts: [],
     })
+    expect(trail.steps[3]).toMatchObject({ subject: "gtd(check): unpin → idle", actor: "check" })
     expect(trail.steps[0]).toMatchObject({ actor: "human", to: "building" })
   })
 
@@ -1626,7 +1681,7 @@ export default async () => {
         )
       }).pipe(Effect.provide(testLayers(repo, {}))),
     )
-    expect(trail.steps).toHaveLength(3)
+    expect(trail.steps).toHaveLength(4)
     expect(calls).toBe(1)
   })
 

package/src/edge/Edge.ts

@@ -37,18 +37,23 @@ import {
   isRecordableApproval,
   parseCommitMessage,
   replay,
+  type CommitMessage,
   scopeRunStart,
   treeFromRecord,
   type EpisodeCommit,
   type JudgeVerdict,
+  type PinChange,
+  PIN_STATES,
   type ReachedStep,
   type ReplayOutcome,
   type TreeView,
 } from "../replay/index.js"
 import type { Mark, ScopeAccess, SummaryContext } from "../flows/index.js"
 import { steeringFormatFor } from "../steering/index.js"
+import { pinScript, unpinScript } from "../emit/index.js"
 import {
   judgeJson,
+  PIN_PATH,
   UNATTRIBUTED_MODEL,
   type ApprovalEntry,
   type ModelCost,
@@ -87,6 +92,16 @@ interface EpisodeLocation {
   readonly processStart: number
 }
 
+const isOpening = ({ parsed, step }: CommitMessage): boolean =>
+  parsed !== undefined &&
+  step === undefined &&
+  parsed.from === undefined &&
+  parsed.actor === "human"
+
+// A pin commit's subject may name the first step; it bounds nothing.
+const boundsEpisode = (def: WorkflowDefinition, { parsed, pin }: CommitMessage): boolean =>
+  pin !== "add" && (parsed === undefined || !ACTORS.has(parsed.actor) || parsed.to === def.initial)
+
 /**
  * Where the episode HEAD belongs to begins, read off subjects alone. Walking
  * back from HEAD: a bare `gtd(human): <step>` commit with no `Gtd-Step` is what
@@ -99,13 +114,7 @@ interface EpisodeLocation {
 const locateEpisode = (def: WorkflowDefinition, history: History): EpisodeLocation => {
   for (let i = history.length - 1; i >= 0; i--) {
     const message = parseCommitMessage(history[i]!.message)
-    const subject = message.parsed
-    const opening =
-      subject !== undefined &&
-      message.step === undefined &&
-      subject.from === undefined &&
-      subject.actor === "human"
-    if (opening) {
+    if (isOpening(message)) {
       return {
         workflow: message.workflow,
         legacyOpening: message.workflow === undefined,
@@ -113,7 +122,7 @@ const locateEpisode = (def: WorkflowDefinition, history: History): EpisodeLocati
         processStart: i,
       }
     }
-    if (subject === undefined || !ACTORS.has(subject.actor) || subject.to === def.initial) {
+    if (boundsEpisode(def, message)) {
       return { workflow: undefined, legacyOpening: false, baseIndex: i, processStart: i + 1 }
     }
   }
@@ -156,6 +165,8 @@ export interface ProcessRun {
   readonly trace: readonly TraceEntry[]
   readonly costEntries: readonly CostEntry[]
   readonly judgeVerdicts: readonly JudgeVerdictEntry[]
+  /** Whether a pin commit has landed in this process. */
+  readonly pinCommitted: boolean
   /** Every process commit's `Gtd-Mark`s, oldest first. */
   readonly marks: readonly Mark[]
   /** Oldest first. */
@@ -186,7 +197,8 @@ const headTurnOf = (head: History[number] | undefined): ProcessRun["headTurn"] =
   if (head === undefined) return undefined
   const message = parseCommitMessage(head.message)
   const subject = message.parsed
-  if (subject === undefined || !ACTORS.has(subject.actor)) return undefined
+  if (subject === undefined || !ACTORS.has(subject.actor) || message.pin !== undefined)
+    return undefined
   return {
     state: subject.to,
     actor: subject.actor,
@@ -267,8 +279,11 @@ const buildRun = (
   location: EpisodeLocation,
   closingHash: string | undefined,
 ): ProcessRun => {
-  const processCommits = history.slice(location.processStart)
-  const parsed = processCommits.map((c) => parseCommitMessage(c.message))
+  const allProcessCommits = history.slice(location.processStart)
+  const allParsed = allProcessCommits.map((c) => parseCommitMessage(c.message))
+  // A pin commit is no turn; the unpin commit stays, as the one that closes the process.
+  const processCommits = allProcessCommits.filter((_, i) => allParsed[i]!.pin !== "add")
+  const parsed = allParsed.filter((m) => m.pin !== "add")
   const first = parsed[0]
   const startParentHash = hashAt(history, location.processStart - 1) ?? EMPTY_TREE
   const head = history[history.length - 1]
@@ -281,6 +296,7 @@ const buildRun = (
     trace: processCommits.map((c, i) => traceEntryOf(c.hash, parsed[i]!)),
     costEntries: parsed.flatMap((m, i) => costEntriesOf(processCommits[i]!.hash, m)),
     judgeVerdicts: parsed.flatMap((m) => m.judge),
+    pinCommitted: allParsed.some((m) => m.pin === "add"),
     marks: parsed.flatMap((m) => m.marks),
     approvals: processCommits.flatMap((c, i) => approvalEntryOf(c.hash, parsed[i]!)),
     pinnedVars: { ...first?.vars },
@@ -320,6 +336,8 @@ const subjectIsBoundary = (def: WorkflowDefinition, subject: string): boolean =>
   const parsed = parseCommitMessage(subject).parsed
   if (parsed === undefined || !ACTORS.has(parsed.actor)) return true
   if (parsed.actor === "human" && parsed.from === undefined) return false
+  // A pin commit's subject can name the first step; it bounds nothing.
+  if (parsed.actor === "check" && parsed.from === PIN_STATES.add) return false
   return parsed.to === def.initial
 }
 
@@ -849,6 +867,10 @@ interface ResolvedRest {
  * before any mutation.
  */
 interface Rest extends ResolvedRest {
+  /** Set at a pin or unpin beat; `step` is then the step the flow reached around it. */
+  readonly pin: PinChange | undefined
+  /** Whether HEAD's tree carries the pin. */
+  readonly pinned: boolean
   readonly step: ReachedStep
   readonly trace: readonly ReachedStep[]
   readonly run: ProcessRun
@@ -985,13 +1007,15 @@ export const restAt = (
     // staying true; passing a pending tree here would make it serve a stale
     // steering file on every cache hit.
     const outcome = yield* Effect.promise(() => replayFor(setup))
-    const error = replayError(outcome)
-    if (error !== undefined || outcome.kind !== "rest") {
-      return yield* Effect.fail(error ?? new Error("gtd: replay found no rest"))
+    const pinned = headHasPin(workspace, run)
+    const pin = pinBeatAt(outcome, run, def, pinned)
+    const resting = restingOn(outcome, pin)
+    if (resting === undefined) {
+      return yield* Effect.fail(replayError(outcome) ?? new Error("gtd: replay found no rest"))
     }
-    const step = outcome.rest
-    yield* (yield* Narrator).narrate(`rest resolved: ${step.name} (awaits ${step.actor})`)
-    const stepDef = stepDefOf(step)
+    const { reached, step } = resting
+    const { stepDef, state, memory } = restFacts(pin, step, reached.trace, run)
+    yield* (yield* Narrator).narrate(`rest resolved: ${state} (awaits ${stepDef.actor})`)
     if (stepDef.mode !== undefined && def.modes[stepDef.mode] === undefined) {
       return yield* Effect.fail(
         new Error(
@@ -1006,7 +1030,6 @@ export const restAt = (
             path: e.path,
           }))
         : []
-    const memory = memoryOf(outcome.trace, run)
     const configNow = config.fingerprint
     // Only the current rest warns, so a command must read it once — a second
     // read warns twice. An earlier ref (restore's tip) would warn about a
@@ -1015,11 +1038,13 @@ export const restAt = (
     return {
       def,
       workflowName: resolved.name,
-      state: step.name,
+      state,
       stepDef,
-      actor: step.actor,
+      actor: stepDef.actor,
+      pin,
+      pinned,
       step,
-      trace: outcome.trace,
+      trace: reached.trace,
       run,
       vars,
       env,
@@ -1035,6 +1060,66 @@ export const restAt = (
 
 export const currentRest: Effect.Effect<Rest, Error, RestRequirements> = restAt(undefined)
 
+/** The step the process rests at and the trace that reached it — at an unpin, the flow's last step. */
+const restingOn = (outcome: ReplayOutcome, pin: PinChange | undefined) => {
+  if (outcome.kind === "rest") return { reached: outcome, step: outcome.rest }
+  if (outcome.kind !== "ended" || pin !== "remove") return undefined
+  const step = outcome.trace.at(-1)
+  return step === undefined ? undefined : { reached: outcome, step }
+}
+
+/** A pin or unpin beat has its own script, no step's, and no agent memory. */
+const restFacts = (
+  pin: PinChange | undefined,
+  step: ReachedStep,
+  trace: readonly ReachedStep[],
+  run: ProcessRun,
+) =>
+  pin === undefined
+    ? { stepDef: stepDefOf(step), state: step.name, memory: memoryOf(trace, run) }
+    : {
+        stepDef: pinStepDef(pin),
+        state: PIN_STATES[pin],
+        memory: { key: undefined, resumed: false },
+      }
+
+const headHasPin = (workspace: WorkspaceOps, run: ProcessRun): boolean => {
+  const head = run.episode.commits.at(-1)?.hash ?? run.episode.base
+  return head !== undefined && workspace.treeSync(head).has(PIN_PATH)
+}
+
+const underwayAt = (run: ProcessRun, step: ReachedStep, def: WorkflowDefinition): boolean =>
+  run.workflow !== undefined || step.name !== def.initial || step.id.occurrence !== 1
+
+/**
+ * A started process pins first — again, should a turn have deleted the pin;
+ * a pinned flow that ended unpins before the closing commit.
+ */
+const pinBeatAt = (
+  outcome: ReplayOutcome,
+  run: ProcessRun,
+  def: WorkflowDefinition,
+  pinned: boolean,
+): PinChange | undefined => {
+  if (flowEnded(outcome, run, def)) return pinned || run.pinCommitted ? "remove" : undefined
+  if (outcome.kind !== "rest" || pinned) return undefined
+  return underwayAt(run, outcome.rest, def) ? "add" : undefined
+}
+
+// A default-workflow process back at the first step has ended, as a returned flow has.
+const flowEnded = (outcome: ReplayOutcome, run: ProcessRun, def: WorkflowDefinition): boolean =>
+  outcome.kind === "ended" ||
+  (outcome.kind === "rest" &&
+    run.workflow === undefined &&
+    outcome.rest.name === def.initial &&
+    underwayAt(run, outcome.rest, def))
+
+const pinStepDef = (pin: PinChange): StepDef => ({
+  actor: "check",
+  kind: "script",
+  content: pin === "add" ? pinScript(PIN_PATH) : unpinScript(PIN_PATH),
+})
+
 type EndedOutcome = Extract<ReplayOutcome, { kind: "ended" }>
 type UnendedOutcome = Exclude<ReplayOutcome, { kind: "ended" }>
 
@@ -1094,6 +1179,7 @@ export interface RenderedRest extends RestHints {
   readonly content: string
   readonly memory?: string
   readonly memoryResumed: boolean
+  readonly pin?: PinChange
 }
 
 export const renderRest = (rest: Rest): Effect.Effect<RenderedRest, Error> =>
@@ -1105,6 +1191,7 @@ export const renderRest = (rest: Rest): Effect.Effect<RenderedRest, Error> =>
     ...rest.hints,
     ...(rest.memory !== undefined ? { memory: rest.memory } : {}),
     memoryResumed: rest.memoryResumed,
+    ...(rest.pin !== undefined ? { pin: rest.pin } : {}),
   })
 
 /**
@@ -1122,9 +1209,7 @@ export const stalledAt = (rest: Rest): boolean =>
 
 /** No process is underway: the default workflow's first step, first visit — a dirty tree there is a turn not yet landed, not a process. */
 export const noProcessUnderway = (rest: Rest): boolean =>
-  rest.run.workflow === undefined &&
-  rest.state === rest.def.initial &&
-  rest.step.id.occurrence === 1
+  rest.pin === undefined && !underwayAt(rest.run, rest.step, rest.def)
 
 /** `idle` means exactly one thing: no process underway, clean tree. */
 export const restIsIdle = (rest: Rest): boolean =>
@@ -1254,15 +1339,15 @@ const landingTo = (
   if (refused !== undefined) return refused
   // Landing on the first step while a process is underway ends it (flow
   // return and `restart()` alike); the script then points the history ref at
-  // that very commit.
-  const finishes = underway && to === rest.def.initial
+  // that very commit. A pinned process ends one beat later, at the unpin.
+  const { finishes, landsAt } = endingOf(rest, to, underway)
   return {
     kind: "commit",
-    to,
+    to: landsAt,
     spec: {
       actor: rest.actor,
       from: rest.state,
-      to,
+      to: landsAt,
       step: rest.step.id,
       ...(marks.length > 0 && { marks }),
       ...approvedTrailer(rest, approver),
@@ -1274,6 +1359,53 @@ const landingTo = (
   }
 }
 
+const endingOf = (rest: Rest, to: StateName, underway: boolean) => {
+  const ends = underway && to === rest.def.initial
+  return { finishes: ends && !rest.pinned, landsAt: ends && rest.pinned ? PIN_STATES.remove : to }
+}
+
+/** A pin or unpin commit carries the pin alone; the unpin commit closes the process. */
+const pinLanding = (rest: Rest, pin: PinChange, branch: Option.Option<string>): Landing => {
+  const change = rest.changes.find((c) => c.path === PIN_PATH)?.status
+  return pin === "add" ? pinCommit(rest, change) : unpinCommit(rest, change, branch)
+}
+
+const pinCommit = (rest: Rest, change: string | undefined): Landing => {
+  if (change === undefined || change === "D") return pinRefusal("add")
+  const to = rest.step.name
+  return {
+    kind: "commit",
+    to,
+    spec: { actor: rest.actor, from: rest.state, to, pin: "add" },
+    only: PIN_PATH,
+  }
+}
+
+const unpinCommit = (
+  rest: Rest,
+  change: string | undefined,
+  branch: Option.Option<string>,
+): Landing => {
+  if (change !== "D" && rest.pinned) return pinRefusal("remove")
+  const to = rest.def.initial
+  return {
+    kind: "commit",
+    to,
+    spec: { actor: rest.actor, from: rest.state, to, pin: "remove", ...closingTrailers(branch) },
+    keepHistory: processHistoryRef(rest.run.startHash),
+    // A turn already deleted the pin: the closing commit has no path of its own.
+    ...(rest.pinned ? { only: PIN_PATH } : {}),
+  }
+}
+
+const pinRefusal = (pin: PinChange): Landing => ({
+  kind: "refusal",
+  message:
+    pin === "add"
+      ? `gtd land: ${PIN_PATH} is missing — run the pin beat's script (\`gtd next --json=content\`); if its \`gtd bundle\` fails, fix what it reports, or run \`gtd abandon\``
+      : `gtd land: ${PIN_PATH} is still there — run the unpin beat's script (\`gtd next --json=content\`), then land`,
+})
+
 const startTrailers = (rest: Rest, starts: boolean) =>
   starts ? { vars: rest.vars, config: rest.config } : {}
 
@@ -1292,6 +1424,7 @@ const decideLanding = (
   approver: Option.Option<AuthorIdent>,
 ): Effect.Effect<Landing, Error> =>
   Effect.gen(function* () {
+    if (rest.pin !== undefined) return pinLanding(rest, rest.pin, branch)
     const unapproved = approvalRefusal(rest, approver)
     if (unapproved !== undefined) return unapproved
     const early = cleanLanding(rest)
@@ -1319,7 +1452,7 @@ const decideLanding = (
 export const previewLanding = (rest: Rest): Effect.Effect<StateName | undefined> =>
   decideLanding(rest, undefined, Option.none(), Option.none()).pipe(
     Effect.map((landing) => (landing.kind === "commit" ? landing.to : undefined)),
-    Effect.catchAll(() => Effect.succeed(undefined)),
+    Effect.catch(() => Effect.succeed(undefined)),
   )
 
 /** Every fact the pure landing planner needs, read once: the rest, its steering file, and the landing decision. */
@@ -1432,8 +1565,8 @@ const configRefusal = (
   )
 
 const differingConfigPaths = (
-  git: GitService["Type"],
-  workspace: Workspace["Type"],
+  git: GitService["Service"],
+  workspace: Workspace["Service"],
   root: string,
   config: { readonly fingerprint: ConfigFingerprint },
   run: ProcessRun,