@pmelab/gtd 60.1.0 → 62.0.0

package/src/edge/Edge.ts

@@ -12,8 +12,6 @@ import {
 import {
   ConfigDiscovery,
   ConfigService,
-  changedConfigFiles,
-  contentHash,
   multilineSetting,
   resolveVars,
   resolveStartVars,
@@ -37,18 +35,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 +90,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 +112,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 +120,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,14 +163,14 @@ 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. */
   readonly approvals: readonly ApprovalEntry[]
   /** The process settings recorded in the process's first commit (empty for a process started before pinning existed). */
   readonly pinnedVars: Record<string, string>
-  /** Absent for a process started before recording existed. */
-  readonly pinnedConfig: { readonly commit: string; readonly files: ConfigFingerprint } | undefined
   /** HEAD's own gtd commit, when it is one — `empty` is whether it changed nothing. */
   readonly headTurn:
     | {
@@ -186,7 +193,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,
@@ -236,17 +244,6 @@ const runOf = (
     : Effect.fail(new Error(fault))
 }
 
-// The newest recording, not the first process commit's: the episode is
-// located by the CURRENT config's first step, so a config that renamed it can
-// move the boundary onto the start commit itself, or behind it.
-const pinnedConfigOf = (history: History): ProcessRun["pinnedConfig"] => {
-  for (let i = history.length - 1; i >= 0; i--) {
-    const files = parseCommitMessage(history[i]!.message).config
-    if (Object.keys(files).length > 0) return { commit: history[i]!.hash, files }
-  }
-  return undefined
-}
-
 const approvalEntryOf = (
   hash: string,
   message: ReturnType<typeof parseCommitMessage>,
@@ -267,8 +264,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,10 +281,10 @@ 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 },
-    pinnedConfig: pinnedConfigOf(history.slice(Math.max(location.baseIndex, 0))),
     headTurn: headTurnOf(head),
     closingHash,
     episode: {
@@ -320,6 +320,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
 }
 
@@ -402,37 +404,6 @@ const computeProcessRun = (
     runOf(history, locateEpisode(def, history)),
   )
 
-// A file matching its copy in the recording commit is unchanged: the hashes
-// are taken before the commit's own hooks run, and a hook may reformat it.
-const changedSinceStart = (
-  pinned: ProcessRun["pinnedConfig"],
-  current: ConfigFingerprint,
-  workspace: WorkspaceOps,
-): readonly string[] => {
-  if (pinned === undefined) return []
-  return changedConfigFiles(pinned.files, current).filter((path) => {
-    const committed = workspace.readCommittedSync(path, pinned.commit)
-    return (
-      current[path] === undefined ||
-      committed === undefined ||
-      contentHash(committed) !== current[path]
-    )
-  })
-}
-
-const warnConfigChanges = (
-  run: ProcessRun,
-  current: ConfigFingerprint,
-  workspace: WorkspaceOps,
-): Effect.Effect<void, never, Narrator> =>
-  Effect.gen(function* () {
-    const changed = changedSinceStart(run.pinnedConfig, current, workspace)
-    if (changed.length === 0) return
-    yield* (yield* Narrator).warn(
-      `gtd: warning: the config changed since this process started (${changed.join(", ")}) — the rest of the process replays under the changed config`,
-    )
-  })
-
 type ConfigRequirements = GitService | ConfigService | ConfigDiscovery | Narrator | Workspace | Host
 
 /** The run alone, never replaying — `gtd abandon` must work even when replay would refuse, short of a history it cannot read. */
@@ -849,13 +820,15 @@ 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
   readonly vars: Record<string, string>
   readonly env: Record<string, string>
-  /** What a landing that starts the process records. */
-  readonly config: ConfigFingerprint
   readonly changes: readonly PendingChange[]
   readonly memory: string | undefined
   readonly memoryResumed: boolean
@@ -985,13 +958,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,24 +981,26 @@ 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
-    // process the command is not acting on.
-    if (ref === undefined) yield* warnConfigChanges(run, configNow, workspace)
+    // Only the current rest notices, so a command must read it once — a
+    // second read notices twice. An earlier ref (restore's tip) is not the
+    // process the command acts on.
+    if (ref === undefined && config.drift.length > 0)
+      yield* (yield* Narrator).warn(
+        `gtd: notice: the live config differs from the pinned one (${config.drift.join(", ")}); \`gtd repin\` to switch`,
+      )
     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,
-      config: configNow,
       changes,
       memory: memory.key,
       memoryResumed: memory.resumed,
@@ -1035,6 +1012,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 +1131,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 +1143,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 +1161,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 +1291,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,8 +1311,54 @@ const landingTo = (
   }
 }
 
-const startTrailers = (rest: Rest, starts: boolean) =>
-  starts ? { vars: rest.vars, config: rest.config } : {}
+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 } : {})
 
 const outcomeMarks = (outcome: ReplayOutcome): readonly Mark[] =>
   outcome.kind === "rest" || outcome.kind === "ended" ? outcome.marks : []
@@ -1292,6 +1375,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)
@@ -1410,13 +1494,13 @@ export interface HistoryTrail {
   readonly versionWarning?: string
 }
 
-/** Repository-relative paths of the config files today's config and the process's own record name; one outside the repository cannot be read at a ref, so it is left out. */
-const inRepoConfigPaths = (
-  root: string,
-  files: readonly string[],
-  recorded: ConfigFingerprint,
-): readonly string[] => {
-  const paths = new Set<string>(Object.keys(recorded))
+/**
+ * Repository-relative paths of today's config files; one outside the
+ * repository cannot be read at a ref, so it is left out. A file only the old
+ * config read needs no check: whichever file imported it differs too.
+ */
+const inRepoConfigPaths = (root: string, files: readonly string[]): readonly string[] => {
+  const paths = new Set<string>()
   for (const file of files) paths.add(relative(root, resolve(root, file)).split(sep).join("/"))
   return [...paths].filter((p) => p !== "" && !p.startsWith("..") && !isAbsolute(p)).sort()
 }
@@ -1436,16 +1520,11 @@ const differingConfigPaths = (
   workspace: Workspace["Service"],
   root: string,
   config: { readonly fingerprint: ConfigFingerprint },
-  run: ProcessRun,
   hash: string,
 ) =>
   Effect.gen(function* () {
     const differing: string[] = []
-    for (const path of inRepoConfigPaths(
-      root,
-      Object.keys(config.fingerprint),
-      run.pinnedConfig?.files ?? {},
-    )) {
+    for (const path of inRepoConfigPaths(root, Object.keys(config.fingerprint))) {
       const atTip = yield* Effect.orElseSucceed(git.readFileAtRef(hash, path), () => undefined)
       if (atTip !== workspace.readSync(path)) differing.push(path)
     }
@@ -1531,7 +1610,7 @@ const replayFinishedProcess = (
     // A refusal is often caused by the version change, so it carries the warning.
     const withWarning = (err: Error): Error =>
       versionWarning === undefined ? err : new Error(`${err.message}\n${versionWarning}`)
-    const differing = yield* differingConfigPaths(git, workspace, host.root, config, run, hash)
+    const differing = yield* differingConfigPaths(git, workspace, host.root, config, hash)
     if (differing.length > 0)
       return yield* Effect.fail(
         withWarning(configRefusal(how.command, hash, differing, how.configReason)),

package/src/emit/GitScript.ts

@@ -12,12 +12,13 @@ export const pathspec = (paths: ReadonlyArray<string>): string => paths.map(shel
  * output rather than the exit code, so a genuinely rejected commit (a lint
  * error, a commit-msg hook) still fails.
  */
-const commitAllowEmpty = (message: string): string => {
+const commitAllowEmpty = (message: string, only?: string): string => {
   const m = shellQuote(message)
+  const paths = only === undefined ? "" : ` -- ${shellQuote(only)}`
   return [
-    `if ! out=$(git commit --allow-empty -m ${m} 2>&1); then`,
+    `if ! out=$(git commit --allow-empty -m ${m}${paths} 2>&1); then`,
     `  case "$out" in`,
-    `    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m} || exit 1 ;;`,
+    `    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m}${paths} || exit 1 ;;`,
     `    *) printf '%s\\n' "$out" >&2; exit 1 ;;`,
     `  esac`,
     `fi`,
@@ -31,6 +32,21 @@ export const CHANGED_SINCE_LAND =
 export const commitAll = (message: string): string =>
   `git add -A || exit 1\n${commitAllowEmpty(message)}`
 
+/** Commits `path` alone, as the worktree has it; every other pending change stays pending. */
+export const commitPath = (path: string, message: string): string =>
+  `git add -A -- ${shellQuote(path)} || exit 1\n${commitAllowEmpty(message, path)}`
+
+/** A pin beat's script. A failed `gtd bundle` leaves no half-written pin behind. */
+export const pinScript = (path: string): string => {
+  const p = shellQuote(path)
+  const slash = path.lastIndexOf("/")
+  const mkdir = slash === -1 ? "" : `mkdir -p ${shellQuote(path.slice(0, slash))}\n`
+  return `${mkdir}gtd bundle >${p} || { rm -f -- ${p}; exit 1; }`
+}
+
+/** An unpin beat's script, and `gtd abandon`'s removal of the pin. */
+export const unpinScript = (path: string): string => `rm -f -- ${shellQuote(path)}`
+
 /**
  * An approval records exactly the judged tree: HEAD is pinned before the
  * clean check and the commit is built over its tree with `commit-tree`, so no
@@ -151,6 +167,8 @@ const renderGitWrite = (write: GitWrite): string => {
   switch (write.kind) {
     case "commitAll":
       return commitAll(write.message)
+    case "commitPath":
+      return commitPath(write.path, write.message)
     case "commitClean":
       return commitClean(write.message)
     case "updateRef":

package/src/emit/index.ts

@@ -16,6 +16,9 @@ export {
   commitAll,
   commitAsIs,
   commitClean,
+  commitPath,
+  pinScript,
+  unpinScript,
   CHANGED_SINCE_LAND,
   softResetTo,
   mixedResetTo,

package/src/gherkin/messages.test.ts

@@ -45,6 +45,7 @@ describe("restDescription", () => {
         "  last commits:",
         "    chore: initial commit",
         "    gtd(agent): plan → sign-off",
+        "    gtd(check): pin → sign-off",
         '  actors never used: "repair" (scenario), "ready" (Background)',
       ].join("\n"),
     )

package/src/gherkin/module-config.feature

@@ -20,5 +20,6 @@ Feature: a scenario runs a workflow module from disk
     And the commit subjects end with:
       """
       gtd(agent): plan → sign-off
+      gtd(check): pin → sign-off
       """
 

package/src/gherkin/more-steps.feature

@@ -23,6 +23,7 @@ Feature: steps for checks, stalls, beat fields, commit bodies and the environmen
 
   Scenario: the resting step's fields are read by name
     When gtd starts workflow "tested"
+    And the process is driven
     Then the process rests at "build.plan"
     And the resting step's model is "smart"
     And the resting step's idle is "false"

package/src/gherkin/testkit.feature

@@ -43,6 +43,7 @@ Feature: testkit drives any workflow against the real engine
     And the commit subjects end with:
       """
       gtd(human): plan
+      gtd(check): pin → plan
       gtd(agent): plan → check
       gtd(check): check → ready
       gtd(judge): ready → ship
@@ -106,7 +107,7 @@ Feature: testkit drives any workflow against the real engine
     When gtd starts workflow "tiny"
     And the process is driven
     Then the process rests at "plan"
-    And the last commit subject is "gtd(human): plan"
+    And the last commit subject is "gtd(check): pin → plan"
 
   Scenario: a prompt asserted beside a script is checked at every visit, before the step acts
     Given step "check" is prompted with "npm test"

package/src/install/Install.ts

@@ -240,7 +240,13 @@ The \`kind\` field (\`--json=kind\`) selects what to do:
   Land it immediately, no display needed.
 - \`script\` — run \`--json=content\` with \`sh -c\`, appending its output to
   \`--json=log\`, and ignore its exit code — the outcome lives in the tree,
-  not in the exit code.
+  not in the exit code. Two script beats carry a \`pin\` mark: the **pin
+  beat** right after a process starts (\`pin: "add"\`, its script writes
+  \`gtd bundle\`'s output to \`.gtd/process.gtdpin\`) and the **unpin beat**
+  once the flow has ended (\`pin: "remove"\`, its script deletes that file).
+  Both run unattended, like any script beat. A driver may write or delete the
+  file its own way instead of running the script; either way it then lands,
+  and the unpin's landing is the commit that closes the process.
 - \`prompt\` — send plain \`gtd next\`'s own output to your agent CLI over
   stdin (it's the bare content at this kind, so no separate \`--json=content\`
   read is needed), using the accompanying \`session.id\`/\`session.resume\`/
@@ -284,7 +290,8 @@ skills, \`skills\` (an array of the skill names, already trimmed and split —
 \`label\`, \`file\`, \`mode\`, \`edges\`, \`judge\` (the pending judgment's rendered
 document). When a cost has been recorded (a prior \`gtd land --cost=<n>\`):
 \`cost\`, \`costByModel\`. Always \`approvals\` (an array of
-\`{step, name, email, commit}\`, \`[]\` when none).
+\`{step, name, email, commit}\`, \`[]\` when none). Only at a pin or unpin
+beat: \`pin\` (\`"add"\` or \`"remove"\`).
 
 \`gtd land\` fields, in fixed order: \`schema\`, \`script\` (the POSIX sh to run), \`settled\`
 (true for a no-op at a \`script\` rest — stop immediately, nothing more to