@pmelab/gtd 60.1.0 → 62.0.0

package/src/replay/Tree.ts

@@ -43,3 +43,14 @@ export const diffTrees = (before: TreeView, after: TreeView): TreeDiff => {
 
 export const isEmptyDiff = (diff: TreeDiff): boolean =>
   diff.added.length === 0 && diff.modified.length === 0 && diff.deleted.length === 0
+
+export const withoutPath = (tree: TreeView, hidden: string): TreeView => {
+  let paths: readonly string[] | undefined
+  return {
+    paths: () => (paths ??= tree.paths().filter((path) => path !== hidden)),
+    read: (path) => (path === hidden ? undefined : tree.read(path)),
+    ...(tree.id !== undefined
+      ? { id: (path: string) => (path === hidden ? undefined : tree.id!(path)) }
+      : {}),
+  }
+}

package/src/replay/index.ts

@@ -12,8 +12,11 @@ export {
   formatSubject,
   isRecordableApproval,
   parseCommitMessage,
+  type CommitMessage,
   type CommitSpec,
   type JudgeVerdict,
+  type PinChange,
+  PIN_STATES,
 } from "./Trailers.js"
 export { accessShapeFault } from "./Access.js"
 export { formatFault } from "./Format.js"

package/src/step/LandStep.ts

@@ -8,6 +8,7 @@ import type { StateName } from "../workflow/index.js"
  */
 export type GitWrite =
   | { readonly kind: "commitAll"; readonly message: string }
+  | { readonly kind: "commitPath"; readonly path: string; readonly message: string }
   | { readonly kind: "commitClean"; readonly message: string }
   | { readonly kind: "updateRef"; readonly ref: string; readonly target: "HEAD" }
   | { readonly kind: "keepTurn"; readonly ref: string; readonly message: string }

package/src/step/RepoSnapshot.ts

@@ -19,6 +19,8 @@ export type Landing =
       readonly keepHistory?: string
       /** The kept ref this landing's turn goes to; the branch gets a marker commit instead. */
       readonly keepTurn?: string
+      /** The one path this landing commits; every other pending change stays pending. */
+      readonly only?: string
     }
 
 /**

package/src/step/planStart.test.ts

@@ -56,7 +56,6 @@ const start = (
         first: startRefusal === undefined ? { firstStep: "work" } : { refusal: startRefusal },
         commandLabel: req.commandLabel,
         vars: req.vars,
-        config: {},
       })
     }).pipe(Effect.provide(testLayers(repo))),
   )
@@ -177,7 +176,7 @@ describe("planStart", () => {
         kind: "gitWrite",
         write: {
           kind: "commitAll",
-          message: "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=\nGtd-Format: 1",
+          message: "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=\nGtd-Format: 2",
         },
       },
       { kind: "outcome", outcome: { kind: "commit", subject: "gtd(human): work" } },
@@ -196,7 +195,7 @@ describe("planStart", () => {
     if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
       throw new Error("expected a gitWrite step")
     expect(write.write.message).toBe(
-      "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=main\nGtd-Format: 1",
+      "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=main\nGtd-Format: 2",
     )
     const outcome = plan.steps.find((s) => s.kind === "outcome")
     expect(outcome).toEqual({

package/src/step/planStart.ts

@@ -7,7 +7,6 @@ import {
   ownFlagRefusal,
   resolveStartVars,
   StartFlags,
-  type ConfigFingerprint,
   type ResolvedWorkflow,
 } from "../workflow/index.js"
 import { formatCommitMessage, formatSubject } from "../replay/index.js"
@@ -70,8 +69,7 @@ const checkOverrides = (
  * `gtd start <name>`: start a brand NEW process on a workflow, writing an
  * opening commit that names the workflow's first step and carries a
  * `Gtd-Workflow:` trailer, every process setting as a `Gtd-Var:` trailer, plus
- * a `Gtd-Review-Base:` trailer when the workflow fixes the process's diff base,
- * and a `Gtd-Config:` trailer per config file.
+ * and a `Gtd-Review-Base:` trailer when the workflow fixes the process's diff base.
  * All validation is a REFUSAL, not an Effect failure.
  */
 export const planStart = (
@@ -83,7 +81,6 @@ export const planStart = (
     readonly first: { readonly firstStep: string } | { readonly refusal: string }
     readonly commandLabel: string
     readonly vars: Record<string, string>
-    readonly config: ConfigFingerprint
   },
 ): Effect.Effect<
   StartOutcome,
@@ -136,7 +133,6 @@ export const planStart = (
       workflow: name,
       ...(base !== undefined ? { reviewBase: base } : {}),
       vars,
-      config: start.config,
     })
     const steps: readonly LandStep[] = [
       { kind: "gitWrite", write: { kind: "commitAll", message } },

package/src/step/planStep.test.ts

@@ -39,7 +39,7 @@ describe("planStep — commit", () => {
     expect(outcome.steps).toEqual([
       {
         kind: "gitWrite",
-        write: { kind: "commitAll", message: "gtd(agent): await-answers\n\nGtd-Format: 1" },
+        write: { kind: "commitAll", message: "gtd(agent): await-answers\n\nGtd-Format: 2" },
       },
       { kind: "outcome", outcome: { kind: "commit", subject: "gtd(agent): await-answers" } },
     ])
@@ -59,7 +59,7 @@ describe("planStep — commit", () => {
       kind: "gitWrite",
       write: {
         kind: "commitAll",
-        message: "gtd(human): building → done\n\nGtd-Step: building#1\nGtd-Format: 1",
+        message: "gtd(human): building → done\n\nGtd-Step: building#1\nGtd-Format: 2",
       },
     })
     expect(outcome.steps.at(-1)).toEqual({
@@ -99,7 +99,7 @@ describe("planStep — commit", () => {
     expect(trailers[1]).toBe("Gtd-Cost: 1.5 m")
     expect(trailers[2]).toBe('Gtd-Judge: {"id":"q1","answer":true,"p":0.9}')
     expect(trailers[3]).toBe('Gtd-Judge: {"id":"q2","answer":"x","p":0.4}')
-    expect(trailers[4]).toBe("Gtd-Format: 1")
+    expect(trailers[4]).toBe("Gtd-Format: 2")
     expect(trailers).toHaveLength(5)
   })
 })
@@ -182,7 +182,7 @@ describe("planStep — keepTurn", () => {
       write: {
         kind: "keepTurn",
         ref: kept,
-        message: "gtd(agent): building → checking\n\nGtd-Step: building#1\nGtd-Format: 1",
+        message: "gtd(agent): building → checking\n\nGtd-Step: building#1\nGtd-Format: 2",
       },
     })
   })

package/src/step/planStep.ts

@@ -1,7 +1,7 @@
 import { formatCommitMessage, type JudgeVerdict } from "../replay/index.js"
 import type { StateName } from "../workflow/index.js"
-import type { LandStep } from "./LandStep.js"
-import type { RepoSnapshot } from "./RepoSnapshot.js"
+import type { GitWrite, LandStep } from "./LandStep.js"
+import type { Landing, RepoSnapshot } from "./RepoSnapshot.js"
 
 export type { JudgeVerdict }
 
@@ -35,6 +35,13 @@ const uncheckStep = (snapshot: RepoSnapshot): readonly LandStep[] =>
     ? [{ kind: "uncheck", file: snapshot.file }]
     : []
 
+const gitWriteOf = (landing: Extract<Landing, { kind: "commit" }>, message: string): GitWrite => {
+  if (landing.only !== undefined) return { kind: "commitPath", path: landing.only, message }
+  if (landing.keepTurn !== undefined) return { kind: "keepTurn", ref: landing.keepTurn, message }
+  if (landing.spec.approved !== undefined) return { kind: "commitClean", message }
+  return { kind: "commitAll", message }
+}
+
 export const planStep = (
   snapshot: RepoSnapshot,
   opts: {
@@ -84,12 +91,7 @@ export const planStep = (
       ...uncheckStep(snapshot),
       {
         kind: "gitWrite",
-        write:
-          landing.keepTurn !== undefined
-            ? { kind: "keepTurn", ref: landing.keepTurn, message }
-            : landing.spec.approved !== undefined
-              ? { kind: "commitClean", message }
-              : { kind: "commitAll", message },
+        write: gitWriteOf(landing, message),
       },
       ...(landing.keepHistory !== undefined
         ? [

package/src/testkit/TestRepo.test.ts

@@ -61,10 +61,12 @@ describe("testRepo", () => {
     expect(repo.subjects()).toEqual([
       "chore: initial commit",
       "gtd(agent): plan → build",
+      "gtd(check): pin → build",
       "gtd(agent): build → check",
       "gtd(check): check → sign-off",
     ])
     expect(repo.read("src/add.ts")).toContain("a + b")
+    expect(repo.read(".gtd/process.gtdpin")).toBeDefined()
   })
 
   it("runs a workflow given as gtd.config.ts source", async () => {
@@ -550,7 +552,8 @@ describe("testRepo", () => {
         trailers: { Refs: ["#1", "#2"] },
       })
       await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
-      expect(repo.commits().at(-1)!.trailers["Gtd-Step"]).toEqual(["plan#1"])
+      expect(repo.commits().at(-2)!.trailers["Gtd-Step"]).toEqual(["plan#1"])
+      expect(repo.commits().at(-1)!.trailers["Gtd-Pin"]).toEqual(["add"])
     })
 
     const greeter = {

package/src/testkit/TestRepo.ts

@@ -353,13 +353,15 @@ const expectedVerdict = (doc: BeatDocument): string => {
 
 const quoted = (names: readonly string[]): string => names.map((name) => `"${name}"`).join(", ")
 
-/** Who acts at `doc`: its scripted actor, or a check's own script under `checks: "run"`. A stall has none. */
+/** Who acts at `doc`: its scripted actor, or its own script at a pin beat or a check under `checks: "run"`. A stall has none. */
 const actorAt = (
   doc: BeatDocument,
   actors: Actors,
   checks: DriveOptions["checks"],
 ): { readonly scripted: boolean; readonly actor: ScriptedActor | undefined } => {
   if (doc.kind === "stalled") return { scripted: false, actor: undefined }
+  // A drive is a driver: pinning is its own business, not a step to script.
+  if (doc.pin !== undefined) return { scripted: false, actor: runsItsScript }
   if (Object.hasOwn(actors, doc.state)) return { scripted: true, actor: actors[doc.state] }
   const runs = checks === "run" && doc.actor === "check"
   return { scripted: false, actor: runs ? runsItsScript : undefined }

package/src/twins/EmittedScriptRecognizer.ts

@@ -7,6 +7,7 @@ import {
   commitAll,
   commitAsIs,
   commitClean,
+  commitPath,
   deleteRef,
   discardPending,
   hardResetTo,
@@ -24,6 +25,8 @@ import {
   contradictionMessage,
   modeContradictionSkipNotice,
   OUTCOME_MARKER,
+  pinScript,
+  unpinScript,
 } from "../emit/index.js"
 import {
   BUILT_IN_MODE_NAMES,
@@ -32,7 +35,7 @@ import {
   type SteeringFormat,
 } from "../steering/internal.js"
 import { refNameFault } from "../replay/index.js"
-import { renderFormat } from "../wire/index.js"
+import { PIN_PATH, renderFormat } from "../wire/index.js"
 import { applyFlowScript, rewritten } from "./FlowScripts.js"
 import type { InMemRepo } from "./InMemRepo.js"
 import type { CommandTable } from "./Layers.js"
@@ -174,6 +177,17 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
 
   if (block.startsWith("git add -A || exit 1\ngtd_sign_cfg=")) return recognizeKeepTurn(repo, block)
 
+  if (block.startsWith("git add -A -- ")) {
+    const [path, message] = extractQuotedTokens(block)
+    if (path === undefined || message === undefined || commitPath(path, message) !== block) {
+      return undefined
+    }
+    const failure = repo.commitPath(path, message)
+    return failure === undefined
+      ? { kind: "applied" }
+      : { kind: "failed", error: failure, status: 1 }
+  }
+
   if (block.startsWith("git add -A || exit 1\n")) {
     const [message] = extractQuotedTokens(conditionLine)
     if (message !== undefined && commitAll(message) === block) {
@@ -255,6 +269,22 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
   return undefined
 }
 
+/** What the in-memory `gtd bundle` prints: a pin header, and no engine behind it. */
+const IN_MEMORY_PIN = "gtdpin 1 gtd in-memory\n"
+
+/** A pin or unpin beat's script. */
+const recognizePinScripts = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
+  if (block === pinScript(PIN_PATH)) {
+    repo.writeFile(PIN_PATH, IN_MEMORY_PIN)
+    return { kind: "applied" }
+  }
+  if (block === unpinScript(PIN_PATH)) {
+    if (repo.readFile(PIN_PATH) !== undefined) repo.deleteFile(PIN_PATH)
+    return { kind: "applied" }
+  }
+  return undefined
+}
+
 /** The REAL `fileExistsGuard` block, re-derived from the extracted path and string-compared. The one recognizer that can report `{ kind: "stopped" }`: a real `exit 0` there ends the script successfully. */
 const recognizeFileExistsGuard = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
   const [file] = extractQuotedTokens(block)
@@ -694,6 +724,7 @@ const recognizersFor = (
   (block) => recognizeBinaryGuard(commands, block),
   (block) => (git ? recognizeGitBuilders(repo, block) : undefined),
   (block) => recognizeWriteLines(repo, block),
+  (block) => recognizePinScripts(repo, block),
   (block) => recognizeFailurePromptWrapper(repo, commands, block),
   (block) => recognizePresentationSubshell(repo, commands, block, git),
   (block) => recognizeModeContradictionSkipNotice(block),

package/src/twins/GitTiers.ts

@@ -21,6 +21,8 @@ import { Effect, Exit, Option } from "effect"
 import { Narrator, GitService, Host, type GitOperations, NodeServices } from "../platform/index.js"
 import {
   commitAll,
+  commitPath,
+  unpinScript,
   commitAsIs,
   commitClean,
   softResetTo,
@@ -1356,6 +1358,27 @@ export const runGitScriptContract = (makeTier: () => GitTier): void => {
     })
   })
 
+  describe("commitPath", () => {
+    it("commits the one path; every other pending change stays pending", () => {
+      t.seed.writeFile(".gtd/process.gtdpin", "pin")
+      t.seed.writeFile("other.ts", "export const y = 1")
+      run(t, commitPath(".gtd/process.gtdpin", "gtd(check): pin → building"))
+      expect(t.observe.headSubject()).toBe("gtd(check): pin → building")
+      expect(t.observe.headTouchedPaths()).toEqual([".gtd/process.gtdpin"])
+      expect(t.observe.statusPorcelain()).toContain("other.ts")
+      expect(t.observe.statusPorcelain()).not.toContain("process.gtdpin")
+    })
+
+    it("commits the path's deletion", () => {
+      t.seed.commit("feat: pinned", { ".gtd/process.gtdpin": "pin" })
+      run(t, unpinScript(".gtd/process.gtdpin"))
+      run(t, commitPath(".gtd/process.gtdpin", "gtd(check): unpin → idle"))
+      expect(t.observe.headTouchedPaths()).toEqual([".gtd/process.gtdpin"])
+      expect(t.observe.existsPath(".gtd/process.gtdpin")).toBe(false)
+      expect(t.observe.statusPorcelain().trim()).toBe("")
+    })
+  })
+
   describe("commitClean", () => {
     it("on a clean tree commits an empty commit with the message", () => {
       const headBefore = t.observe.resolveRef("HEAD")

package/src/twins/InMemRepo.ts

@@ -474,6 +474,20 @@ export class InMemRepo {
     this.resetHard()
   }
 
+  /** Twin of `GitScript.commitPath`: commits `path` as the worktree has it, every other staged change left staged. */
+  commitPath(path: string, message: string): string | undefined {
+    if (!this.worktree.has(path) && !this.headTree().has(path) && !this.index.has(path)) {
+      return `error: pathspec '${path}' did not match any file(s) known to git`
+    }
+    const staged = new Map(this.index)
+    this.index = new Map(this.headTree())
+    this.stage(path)
+    const failure = this.commitAsIs(message)
+    this.index = staged
+    this.stage(path)
+    return failure
+  }
+
   commitAllWithPrefix(prefix: string): string | undefined {
     this.index = new Map(this.worktree)
     return this.commitAsIs(prefix)

package/src/twins/PinBeats.ts

@@ -0,0 +1,33 @@
+import { Effect } from "effect"
+import { runCli } from "../cli/index.js"
+import type { PinMark } from "../wire/index.js"
+import { makeCapturingCliIo } from "./cliIo.js"
+import { applyEmittedScript } from "./EmittedScriptRecognizer.js"
+import type { InMemRepo } from "./InMemRepo.js"
+
+const gtd = async (repo: InMemRepo, ...args: string[]) => {
+  const { io, result } = makeCapturingCliIo(repo)
+  await Effect.runPromise(runCli(["node", "gtd.js", ...args], io))
+  return result()
+}
+
+const apply = (repo: InMemRepo, script: string): void => {
+  const outcome = applyEmittedScript(repo, new Map(), script)
+  if (!outcome.ok) throw new Error(outcome.error)
+}
+
+/**
+ * Takes the pending pin or unpin beat — `mark` alone when given — the way a
+ * driver does: its script, then its landing. Whether it took one.
+ */
+export const takePinBeat = async (repo: InMemRepo, mark?: PinMark): Promise<boolean> => {
+  const next = await gtd(repo, "next", "--json")
+  if (next.exitCode !== 0) return false
+  const beat = JSON.parse(next.stdout) as { readonly pin?: PinMark; readonly content: string }
+  if (beat.pin === undefined || (mark !== undefined && beat.pin !== mark)) return false
+  apply(repo, beat.content)
+  const land = await gtd(repo, "land", "--json")
+  if (land.exitCode !== 0) throw new Error(`gtd land exited ${land.exitCode}: ${land.stderr}`)
+  apply(repo, (JSON.parse(land.stdout) as { readonly script: string }).script)
+  return true
+}

package/src/twins/PinFile.test.ts

@@ -0,0 +1,107 @@
+import { execFileSync } from "node:child_process"
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { livePinFile, type PinFile } from "../platform/index.js"
+import { InMemRepo } from "./index.js"
+import { inMemPinFile } from "./PinFile.js"
+
+const PIN = ".gtd/process.gtdpin"
+
+interface Tier {
+  readonly root: string
+  /** The pin a launcher starting at the root finds. */
+  readonly pinFile: () => PinFile
+  readonly write: (path: string, content: string) => void
+  readonly remove: (path: string) => void
+  readonly commit: () => void
+}
+
+const liveTier = (): Tier => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-pinfile-")))
+  cleanups.push(() => rmSync(root, { recursive: true, force: true }))
+  const git = (...args: string[]) => execFileSync("git", args, { cwd: root, stdio: "ignore" })
+  git("init", "-q")
+  return {
+    root,
+    pinFile: () => livePinFile(root, PIN),
+    write: (path, content) => {
+      mkdirSync(dirname(join(root, path)), { recursive: true })
+      writeFileSync(join(root, path), content)
+    },
+    remove: (path) => rmSync(join(root, path)),
+    commit: () => {
+      git("add", "-A")
+      git("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "-m", "c")
+    },
+  }
+}
+
+const inMemTier = (): Tier => {
+  const repo = new InMemRepo()
+  const root = "/repo"
+  return {
+    root,
+    pinFile: () => inMemPinFile(repo, root, PIN),
+    write: (path, content) => repo.writeFile(path, content),
+    remove: (path) => repo.deleteFile(path),
+    commit: () => repo.seedCommit("c"),
+  }
+}
+
+const cleanups: (() => void)[] = []
+afterEach(() => cleanups.splice(0).forEach((cleanup) => cleanup()))
+
+const text = (pinFile: PinFile) => {
+  const found = pinFile()
+  return found && { path: found.path, content: Buffer.from(found.bytes).toString() }
+}
+
+describe.each([
+  ["live", liveTier],
+  ["in-memory", inMemTier],
+])("PinFile contract: %s", (_, make) => {
+  it("finds nothing without a pin", () => {
+    const tier = make()
+    tier.write("README.md", "x")
+    tier.commit()
+    expect(text(tier.pinFile())).toBeUndefined()
+  })
+
+  it("finds the worktree's pin, committed or not", () => {
+    const tier = make()
+    tier.write(PIN, "pinned")
+    expect(text(tier.pinFile())).toEqual({ path: join(tier.root, PIN), content: "pinned" })
+  })
+
+  it("prefers the worktree's pin over HEAD's", () => {
+    const tier = make()
+    tier.write(PIN, "committed")
+    tier.commit()
+    tier.write(PIN, "rewritten")
+    expect(text(tier.pinFile())?.content).toBe("rewritten")
+  })
+
+  it("falls back to HEAD's pin once the worktree's is deleted", () => {
+    const tier = make()
+    tier.write(PIN, "committed")
+    tier.commit()
+    tier.remove(PIN)
+    expect(text(tier.pinFile())).toEqual({ path: join(tier.root, PIN), content: "committed" })
+  })
+})
+
+describe("livePinFile", () => {
+  it("reads an unreadable pin as no pin's bytes", () => {
+    const tier = liveTier()
+    tier.write(`${PIN}/inside`, "x")
+    expect(text(tier.pinFile())).toEqual({ path: join(tier.root, PIN), content: "" })
+  })
+
+  it("finds nothing outside a repository", () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "gtd-pinfile-")))
+    cleanups.push(() => rmSync(dir, { recursive: true, force: true }))
+    expect(livePinFile(dir, PIN)()).toBeUndefined()
+  })
+})

package/src/twins/PinFile.ts

@@ -0,0 +1,12 @@
+import { join } from "node:path"
+import type { PinFile } from "../platform/index.js"
+import type { InMemRepo } from "./InMemRepo.js"
+
+export const inMemPinFile =
+  (repo: InMemRepo, root: string, path: string): PinFile =>
+  () => {
+    const content = repo.readFile(path) ?? repo.fileAtRef("HEAD", path) ?? undefined
+    return content === undefined
+      ? undefined
+      : { path: join(root, path), bytes: Buffer.from(content) }
+  }

package/src/twins/index.ts

@@ -11,3 +11,5 @@ export { applyFlowScript } from "./FlowScripts.js"
 export { gitTiers, runGitServiceContract, runGitScriptContract, type GitTier } from "./GitTiers.js"
 export { strictGitOperations } from "./StrictGitOperations.js"
 export { fakeGitOperations } from "./FakeGitOperations.js"
+export { takePinBeat } from "./PinBeats.js"
+export { inMemPinFile } from "./PinFile.js"

package/src/wire/BeatDocument.ts

@@ -1,6 +1,14 @@
 import type { BeatKind, Demand, DemandSession } from "./Demand.js"
 import type { BeatStatus, NextMatch, StatusChange } from "./BeatStatus.js"
-import type { Actor, ApprovalEntry, ModelCost, StateMode, StateName, StepAccess } from "./types.js"
+import type {
+  Actor,
+  ApprovalEntry,
+  ModelCost,
+  PinMark,
+  StateMode,
+  StateName,
+  StepAccess,
+} from "./types.js"
 import { WIRE_SCHEMA } from "./constants.js"
 
 /** `gtd next --json`'s `next` key — `null` when landing would commit nothing. */
@@ -27,20 +35,30 @@ const dispatchFieldsOf = (
   readonly validate: string | undefined
   readonly skills: readonly string[] | undefined
   readonly access: StepAccess | undefined
+  readonly pin: PinMark | undefined
 } => {
+  const none = {
+    session: undefined,
+    validate: undefined,
+    skills: undefined,
+    access: undefined,
+    pin: undefined,
+  }
   switch (demand.kind) {
     case "prompt":
       return {
+        ...none,
         session: demand.session,
         validate: demand.validate,
         skills: demand.skills,
         access: demand.access,
       }
+    case "script":
+      return { ...none, pin: demand.pin }
     case "capture":
     case "message":
-    case "script":
     case "stalled":
-      return { session: undefined, validate: undefined, skills: undefined, access: undefined }
+      return none
     default:
       return assertNeverDemand(demand)
   }
@@ -57,6 +75,8 @@ export interface BeatDocument {
   readonly model: string | undefined
   readonly system: string | undefined
   readonly validate: string | undefined
+  /** On a pin or unpin beat only: what its script does to `.gtd/process.gtdpin`. */
+  readonly pin: PinMark | undefined
   readonly log: string
   readonly state: StateName
   readonly actor: Actor
@@ -76,13 +96,13 @@ export interface BeatDocument {
 }
 
 /**
- * Flatten a `Demand` plus its `BeatStatus` into the single 25-key document
+ * Flatten a `Demand` plus its `BeatStatus` into the single 26-key document
  * `gtd next --json` emits — the ONLY place the two are joined. `cost`/
  * `costByModel` are omitted together, exactly when no cost was recorded
  * (`cost <= 0`).
  */
 export const beatDocument = (demand: Demand, status: BeatStatus): BeatDocument => {
-  const { session, validate, skills, access } = dispatchFieldsOf(demand)
+  const { session, validate, skills, access, pin } = dispatchFieldsOf(demand)
   const hasCost = status.cost > 0
   return {
     schema: WIRE_SCHEMA,
@@ -94,6 +114,7 @@ export const beatDocument = (demand: Demand, status: BeatStatus): BeatDocument =
     model: status.model,
     system: status.system,
     validate,
+    pin,
     log: status.log,
     state: status.state,
     actor: status.actor,

package/src/wire/Demand.ts

@@ -1,4 +1,11 @@
-import type { Actor, ContentKind, RenderedDemandSource, StateName, StepAccess } from "./types.js"
+import type {
+  Actor,
+  ContentKind,
+  PinMark,
+  RenderedDemandSource,
+  StateName,
+  StepAccess,
+} from "./types.js"
 
 /** The whole beat vocabulary a driver acts on — what to DO with a rest, not merely whether dispatching it is safe. */
 export type BeatKind = "capture" | "message" | "script" | "prompt" | "stalled"
@@ -72,7 +79,7 @@ export interface DemandSession {
 export type Demand =
   | { readonly kind: "capture"; readonly content: string }
   | { readonly kind: "message"; readonly content: string }
-  | { readonly kind: "script"; readonly content: string }
+  | { readonly kind: "script"; readonly content: string; readonly pin?: PinMark }
   | { readonly kind: "stalled"; readonly content: string }
   | {
       readonly kind: "prompt"
@@ -91,7 +98,10 @@ export type Demand =
  * any other kind.
  */
 export const demandOf = (input: {
-  readonly rendered: Pick<RenderedDemandSource, "actor" | "content" | "state" | "skills" | "access">
+  readonly rendered: Pick<
+    RenderedDemandSource,
+    "actor" | "content" | "state" | "skills" | "access" | "pin"
+  >
   readonly kind: BeatKind
   readonly session?: DemandSession
   readonly validate?: string
@@ -102,7 +112,7 @@ export const demandOf = (input: {
   const skills =
     rendered.skills !== undefined && rendered.skills.length > 0 ? rendered.skills : undefined
   const access = rendered.access ?? { read: null, write: null }
-  return kind === "prompt"
-    ? { kind, content, session, validate, skills, access }
-    : { kind, content }
+  if (kind === "prompt") return { kind, content, session, validate, skills, access }
+  if (kind === "script" && rendered.pin !== undefined) return { kind, content, pin: rendered.pin }
+  return { kind, content }
 }

package/src/wire/constants.ts

@@ -20,3 +20,6 @@ export const renderFormat = (fmt: string, ...args: readonly string[]): string =>
 /** The first line of the landing refusal for a turn that wrote outside its `write` access — a stable marker drivers and tests grep for. */
 export const ACCESS_REFUSAL =
   "gtd land: this turn wrote outside its write access — revert these paths, then run `gtd land` again:"
+
+/** Where a process keeps its pin: the engine and workflow it runs on, as `gtd bundle` prints them. */
+export const PIN_PATH = ".gtd/process.gtdpin"