@pmelab/gtd 60.1.0 → 62.0.0

package/dist/testkit/gherkin.mjs

@@ -1,4 +1,4 @@
-import { n as runsItsScript, r as testRepo } from "../chunks/testkit-BhTey1Do.mjs";
+import { n as runsItsScript, r as testRepo } from "../chunks/testkit-XQeYCNMn.mjs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { After, AfterAll, Given, QuickPickleWorld, Then, When, setWorldConstructor } from "quickpickle";

package/dist/testkit.mjs

@@ -1,3 +1,3 @@
 import { H as installContext } from "./chunks/flows-DENt0uWV.mjs";
-import { a as verdictWhen, i as verdict, n as runsItsScript, o as whenPrompted, r as testRepo, t as inTurn } from "./chunks/testkit-BhTey1Do.mjs";
+import { a as verdictWhen, i as verdict, n as runsItsScript, o as whenPrompted, r as testRepo, t as inTurn } from "./chunks/testkit-XQeYCNMn.mjs";
 export { inTurn, installContext, runsItsScript, testRepo, verdict, verdictWhen, whenPrompted };

package/dist/wire.mjs

@@ -1,2 +1,2 @@
-import { A as WIRE_SCHEMA, C as EXIT_RUNTIME_ERROR, D as EXIT_USAGE_ERROR, E as EXIT_STRAYS_FOUND, O as ACCESS_REFUSAL, S as EXIT_OK, T as EXIT_SIGTERM, _ as BEAT_KINDS, a as renderScriptJson, b as stallDiagnosis, c as landProseText, d as renderLandPlain, f as DEMAND_BRIEFING, g as statusOf, h as renderBeatJson, i as judgeJson, j as renderFormat, k as UNATTRIBUTED_MODEL, l as noopText, m as beatDocument, n as resolveSession, o as scriptFields, p as renderBeatPlain, r as selectPath, s as landFields, t as globMatches, u as renderLandJson, v as beatKindOf, w as EXIT_SIGINT, x as EXIT_CODES, y as demandOf } from "./chunks/wire-DZ8R1RU9.mjs";
-export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_STRAYS_FOUND, EXIT_USAGE_ERROR, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, renderScriptJson, resolveSession, scriptFields, selectPath, stallDiagnosis, statusOf };
+import { A as UNATTRIBUTED_MODEL, C as EXIT_RUNTIME_ERROR, D as EXIT_USAGE_ERROR, E as EXIT_STRAYS_FOUND, M as renderFormat, O as ACCESS_REFUSAL, S as EXIT_OK, T as EXIT_SIGTERM, _ as BEAT_KINDS, a as renderScriptJson, b as stallDiagnosis, c as landProseText, d as renderLandPlain, f as DEMAND_BRIEFING, g as statusOf, h as renderBeatJson, i as judgeJson, j as WIRE_SCHEMA, k as PIN_PATH, l as noopText, m as beatDocument, n as resolveSession, o as scriptFields, p as renderBeatPlain, r as selectPath, s as landFields, t as globMatches, u as renderLandJson, v as beatKindOf, w as EXIT_SIGINT, x as EXIT_CODES, y as demandOf } from "./chunks/wire-CPNSm_9N.mjs";
+export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_STRAYS_FOUND, EXIT_USAGE_ERROR, PIN_PATH, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, renderScriptJson, resolveSession, scriptFields, selectPath, stallDiagnosis, statusOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "60.1.0",
+  "version": "62.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/cli/Cli.ts

@@ -632,6 +632,7 @@ const flagHeader = (row: FlagRow): string => {
 
 const GLOBAL_OPTIONS: readonly (readonly [string, string])[] = [
   ["-v, --verbose", "Narrate on stderr what gtd resolved"],
+  ["--live", "Run this gtd, not the process's pin; it may misread the process"],
   ["-h, --help", "Print help; gtd <command> --help for one command"],
   ["-V, --version", "Print the version"],
   ["--", "End the options: every word after it is an argument"],
@@ -643,7 +644,11 @@ const EXTRA_TOPICS: readonly (readonly [string, string, string])[] = [
     "Print help for gtd or one command",
     "Print gtd's overview, or with <command> that command's own help.",
   ],
-  ["version", "Print the version", "Print gtd's version."],
+  [
+    "version",
+    "Print the version",
+    "Print gtd's version, and the version of a pinned process's gtd.",
+  ],
 ]
 
 const EXAMPLES = `  $ gtd start                                   list what can start

package/src/cli/History.test.ts

@@ -1,6 +1,12 @@
 import { Effect, Exit } from "effect"
 import { describe, expect, it } from "vitest"
-import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
+import {
+  applyEmittedScript,
+  InMemRepo,
+  makeCapturingCliIo,
+  takePinBeat,
+  testLayers,
+} from "../twins/index.js"
 import { runCli } from "./index.js"
 import { historyEntries, resolveHistoryRef, type HistoryEntry } from "./History.js"
 
@@ -12,7 +18,9 @@ export default async () => {
 }
 `
 
+/** Lands `files` as one turn, taking a pin beat before it and an unpin beat after it as a driver does. */
 const land = async (repo: InMemRepo, files: Record<string, string>): Promise<string> => {
+  await takePinBeat(repo, "add")
   for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
   const { io, result } = makeCapturingCliIo(repo)
   await Effect.runPromise(runCli(["node", "gtd.js", "land", "--json"], io))
@@ -24,6 +32,7 @@ const land = async (repo: InMemRepo, files: Record<string, string>): Promise<str
     (JSON.parse(stdout) as { script: string }).script,
   )
   if (!outcome.ok) throw new Error(outcome.error)
+  await takePinBeat(repo, "remove")
   return repo.resolveRef("HEAD")!
 }
 

package/src/cli/Launch.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { GTD_VERSION, PIN_KEY } from "../install/index.js"
+import { launchFor } from "./Launch.js"
+
+const pin =
+  (header = "gtdpin 1 gtd 1.2.3") =>
+  () => ({
+    path: "/repo/.gtd/process.gtdpin",
+    bytes: Buffer.from(`${header}\n`),
+  })
+const argv = (...words: string[]) => ["node", "gtd", ...words]
+
+describe("launchFor", () => {
+  afterEach(() => {
+    delete (globalThis as { [PIN_KEY]?: unknown })[PIN_KEY]
+  })
+
+  it("hands a state command over to the pin", () => {
+    expect(launchFor(argv("next"), pin())).toMatchObject({ kind: "pin", version: "1.2.3" })
+  })
+
+  it("never hands over from inside a pin", () => {
+    ;(globalThis as { [PIN_KEY]?: unknown })[PIN_KEY] = { version: "1.2.3" }
+    expect(launchFor(argv("next"), pin())).toEqual({ kind: "live", argv: argv("next") })
+  })
+
+  it("strips --live, but keeps one after --", () => {
+    expect(launchFor(argv("--live", "start", "--", "--live"), pin())).toEqual({
+      kind: "live",
+      argv: argv("start", "--", "--live"),
+    })
+    expect(launchFor(argv("start", "--", "--live"), pin())).toMatchObject({
+      kind: "pin",
+      argv: argv("start", "--", "--live"),
+    })
+  })
+
+  it("leaves the version to this gtd without a pin, and for a file that is no pin", () => {
+    expect(launchFor(argv("-V"), () => undefined)).toEqual({ kind: "live", argv: argv("-V") })
+    expect(launchFor(argv("version"), pin("garbage"))).toEqual({
+      kind: "output",
+      stdout: `${GTD_VERSION}\n`,
+    })
+  })
+
+  it("names a newer pin's version even when it cannot run it", () => {
+    expect(launchFor(argv("--version"), pin("gtdpin 9 gtd 99.0.0"))).toEqual({
+      kind: "output",
+      stdout: `${GTD_VERSION} (this process is pinned to gtd 99.0.0)\n`,
+    })
+  })
+})

package/src/cli/Launch.ts

@@ -0,0 +1,143 @@
+import type { PinFile } from "../platform/index.js"
+import { GTD_VERSION, PIN_KEY } from "../install/index.js"
+import { PIN_FORMAT, pinHeader, readPin } from "../workflow/index.js"
+import { EXIT_RUNTIME_ERROR } from "../wire/index.js"
+import { parseArgv } from "./Cli.js"
+import type { Command } from "./Program.js"
+
+/** What the core a pin carries lacks, or what must read the live state: these never hand over. */
+const LIVE_KINDS: ReadonlySet<Command["kind"]> = new Set<Command["kind"]>([
+  "ui",
+  "lsp",
+  "guide",
+  "bundle",
+  "historyList",
+  "historyShow",
+  "historyMetrics",
+  "historyJudges",
+  "historyFetch",
+])
+
+export type Launch =
+  | { readonly kind: "live"; readonly argv: readonly string[] }
+  | {
+      readonly kind: "pin"
+      readonly argv: readonly string[]
+      readonly path: string
+      readonly version: string
+      /** Unpacked only when run: its failure is the hand-over's. */
+      readonly source: () => string
+    }
+  | { readonly kind: "output"; readonly stdout: string }
+  | { readonly kind: "refuse"; readonly message: string }
+
+const LIVE_FLAG = "--live"
+
+// Only before `--`: after it, `--live` is an argument.
+const optionWords = (argv: readonly string[]): readonly string[] => {
+  const end = argv.indexOf("--", 2)
+  return argv.slice(2, end < 0 ? undefined : end)
+}
+
+const withoutLiveFlag = (argv: readonly string[]): readonly string[] => {
+  const end = argv.indexOf("--", 2)
+  return argv.filter((word, i) => word !== LIVE_FLAG || i < 2 || (end >= 0 && i > end))
+}
+
+/**
+ * Whether this gtd runs the command or hands it to the process's pin. A pin
+ * this gtd cannot run is refused, never guessed at; a usage error the live
+ * parser finds is still the pin's to judge, since its engine may read
+ * another CLI.
+ */
+export const launchFor = (argv: readonly string[], pinFile: PinFile): Launch => {
+  // The engine a pin carries is this same code: once inside one, never hand over again.
+  if ((globalThis as { [PIN_KEY]?: unknown })[PIN_KEY] !== undefined) return { kind: "live", argv }
+  const live = optionWords(argv).includes(LIVE_FLAG)
+  const rest = withoutLiveFlag(argv)
+  if (live) return { kind: "live", argv: rest }
+  const plan = parseArgv(rest)
+  const version = plan.kind === "output" && plan.stdout === `${GTD_VERSION}\n`
+  if (plan.kind === "output" && !version) return { kind: "live", argv: rest }
+  if (plan.kind === "command" && LIVE_KINDS.has(plan.command.kind))
+    return { kind: "live", argv: rest }
+  const found = pinFile()
+  if (found === undefined) return { kind: "live", argv: rest }
+  const header = pinHeader(found.bytes)
+  if (version)
+    return {
+      kind: "output",
+      stdout:
+        header === undefined
+          ? plan.stdout
+          : `${GTD_VERSION} (this process is pinned to gtd ${header.version})\n`,
+    }
+  if (header === undefined || header.format !== PIN_FORMAT) {
+    const what =
+      header === undefined
+        ? "is no pin this gtd can read"
+        : `is pin format ${header.format}, made by gtd ${header.version}`
+    return {
+      kind: "refuse",
+      message: `gtd: ${found.path} ${what}; gtd ${GTD_VERSION} runs pin format ${PIN_FORMAT} — upgrade gtd (\`gtd --live\` runs this gtd instead, and may misread the process)`,
+    }
+  }
+  return {
+    kind: "pin",
+    argv: rest,
+    path: found.path,
+    version: header.version,
+    source: () => readPin(found.bytes).source,
+  }
+}
+
+export interface Launcher {
+  readonly stdout: (chunk: string) => void
+  readonly stderr: (chunk: string) => void
+  readonly exit: (code: number) => void
+  readonly live: (argv: readonly string[]) => void | Promise<void>
+  readonly pin: (launch: Extract<Launch, { kind: "pin" }>) => Promise<void>
+}
+
+const isJsonFlag = (word: string): boolean => word === "--json" || word.startsWith("--json=")
+
+// The CLI's own error envelope too, which a `--json` driver reads.
+const refusalText = (argv: readonly string[], message: string): string =>
+  (optionWords(argv).some(isJsonFlag)
+    ? `${JSON.stringify({ state: "error", prompt: message })}\n`
+    : "") + `${message}\n`
+
+const runPin = async (
+  launch: Extract<Launch, { kind: "pin" }>,
+  launcher: Launcher,
+): Promise<void> => {
+  const words = optionWords(launch.argv)
+  if (words.includes("--verbose") || words.includes("-v"))
+    launcher.stderr(`launcher: running the pin ${launch.path} (gtd ${launch.version})\n`)
+  try {
+    await launcher.pin(launch)
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    launcher.stderr(`gtd: could not run the pin ${launch.path}: ${reason}\n`)
+    launcher.exit(EXIT_RUNTIME_ERROR)
+  }
+}
+
+export const runLauncher = async (
+  argv: readonly string[],
+  pinFile: PinFile,
+  launcher: Launcher,
+): Promise<void> => {
+  const launch = launchFor(argv, pinFile)
+  switch (launch.kind) {
+    case "live":
+      return launcher.live(launch.argv)
+    case "output":
+      return launcher.stdout(launch.stdout)
+    case "refuse":
+      launcher.stderr(refusalText(argv, launch.message))
+      return launcher.exit(EXIT_RUNTIME_ERROR)
+    case "pin":
+      return runPin(launch, launcher)
+  }
+}

package/src/cli/Metrics.test.ts

@@ -1,6 +1,12 @@
 import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
-import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
+import {
+  applyEmittedScript,
+  InMemRepo,
+  makeCapturingCliIo,
+  takePinBeat,
+  testLayers,
+} from "../twins/index.js"
 import { runCli } from "./index.js"
 import { processMetrics, readProcessMetrics, totalMetrics, type MetricCommit } from "./Metrics.js"
 
@@ -213,7 +219,9 @@ export default async () => {
 }
 `
 
+/** Lands `files` as one turn, taking a pin beat before it and an unpin beat after it as a driver does. */
 const land = async (repo: InMemRepo, files: Record<string, string>): Promise<string> => {
+  await takePinBeat(repo, "add")
   for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
   const { io, result } = makeCapturingCliIo(repo)
   await Effect.runPromise(runCli(["node", "gtd.js", "land", "--json"], io))
@@ -225,6 +233,7 @@ const land = async (repo: InMemRepo, files: Record<string, string>): Promise<str
     (JSON.parse(stdout) as { script: string }).script,
   )
   if (!outcome.ok) throw new Error(outcome.error)
+  await takePinBeat(repo, "remove")
   return repo.resolveRef("HEAD")!
 }
 

package/src/cli/Program.test.ts

@@ -18,7 +18,13 @@ vi.mock("node:os", async (importOriginal) => ({
 import { runCli, type Command } from "./index.js"
 import { EXIT_USAGE_ERROR, stallDiagnosis, noopText, WIRE_SCHEMA } from "../wire/index.js"
 import { needsOf, runCommand, SelectorUsageError, type CommandRequirements } from "./Program.js"
-import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../twins/index.js"
+import {
+  InMemRepo,
+  makeCapturingCliIo,
+  testLayers,
+  applyEmittedScript,
+  takePinBeat,
+} from "../twins/index.js"
 import {
   commitAll,
   DID_NOT_RUN_COMMENT,
@@ -27,7 +33,6 @@ import {
   restoredOutcome,
 } from "../emit/index.js"
 import { GitService, HISTORY_REF, Host } from "../platform/index.js"
-import { contentHash } from "../workflow/index.js"
 import { WORKFLOWS_REPO } from "../install/index.js"
 
 const run = async (
@@ -39,13 +44,14 @@ const run = async (
   return result()
 }
 
-/** Lands via `gtd land --json` and applies the emitted script, as a driver would. */
+/** Lands via `gtd land --json` and applies the emitted script, then takes the pin or unpin beat it leads to, as a driver would. */
 const landAndApply = async (
   repo: InMemRepo,
 ): Promise<{ readonly exitCode: number; readonly script: string }> => {
   const { stdout, exitCode } = await run(repo, "land", "--json")
   const script = exitCode === 0 ? (JSON.parse(stdout) as { readonly script: string }).script : ""
   if (exitCode === 0) expect(applyEmittedScript(repo, new Map(), script).ok).toBe(true)
+  if (exitCode === 0) await takePinBeat(repo)
   return { exitCode, script }
 }
 
@@ -104,7 +110,7 @@ export const hotfix = workflow(
     expect(exitCode).toBe(0)
     expect(stdout).toContain(
       commitAll(
-        `gtd(human): working\n\nGtd-Workflow: hotfix\nGtd-Var: greeting=hello\nGtd-Config: ${contentHash(WORKFLOW)} gtd.config.ts\nGtd-Format: 1`,
+        `gtd(human): working\n\nGtd-Workflow: hotfix\nGtd-Var: greeting=hello\nGtd-Format: 2`,
       ),
     )
     expect(repo.commitHistory()).toHaveLength(before)
@@ -190,6 +196,9 @@ export const hotfix = workflow(
     const { stdout } = await run(repo, "start", "hotfix")
     expect(applyEmittedScript(repo, new Map(), stdout).ok).toBe(true)
     expect(repo.lastCommitSubject()).toBe("gtd(human): working")
+    const pin = JSON.parse((await run(repo, "next", "--json")).stdout) as Record<string, unknown>
+    expect(pin).toMatchObject({ kind: "script", state: "pin", actor: "check", pin: "add" })
+    expect(await takePinBeat(repo, "add")).toBe(true)
     const next = JSON.parse((await run(repo, "next", "--json")).stdout) as Record<string, unknown>
     expect(next.kind).toBe("prompt")
     expect(next.state).toBe("working")
@@ -496,6 +505,7 @@ export const resume = workflow(work)
     const repo = seed(WORKFLOW)
     const { stdout: entry } = await run(repo, "start", "resume")
     expect(applyEmittedScript(repo, new Map(), entry).ok).toBe(true)
+    await takePinBeat(repo, "add")
     const { stdout, exitCode } = await run(repo, "next", "--json")
     expect(exitCode).toBe(0)
     expect(JSON.parse(stdout).kind).toBe("prompt")
@@ -775,20 +785,20 @@ describe("gtd next — refuses when history diverges from what replay reaches",
     expect(repo.commitHistory()).toHaveLength(before)
 
     expect(applyEmittedScript(repo, new Map(), stdout).ok).toBe(true)
-    expect(repo.commitHistory()).toHaveLength(before - 2)
+    expect(repo.commitHistory()).toHaveLength(before - 3)
   })
 })
 
 describe("a history written in a format this gtd does not read", () => {
   // The exact wording is pinned in Format.test.ts; this is the part that proves the format gate fired.
-  const FOREIGN = "is written in history format 2, but this gtd reads format 1"
+  const FOREIGN = "is written in history format 3, but this gtd reads formats 1 to 2"
 
   /** A step commit that would also diverge, so only the format gate can explain the refusal. */
   const foreignStep = async (): Promise<InMemRepo> => {
     const repo = seed(IDLE_THEN_WORKING)
     await landTurn(repo, { "NOTE.md": "a note\n" })
     repo.writeFile("WORK.md", "done\n")
-    repo.seedCommit("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1\nGtd-Format: 2")
+    repo.seedCommit("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1\nGtd-Format: 3")
     return repo
   }
 
@@ -813,7 +823,7 @@ describe("a history written in a format this gtd does not read", () => {
   it("refuses even when a foreign subject hides the commit from the episode", async () => {
     const repo = seed(IDLE_THEN_WORKING)
     repo.writeFile("NOTE.md", "a note\n")
-    repo.seedCommit("gtd2[human] idle -> working\n\nGtd-Format: 2")
+    repo.seedCommit("gtd2[human] idle -> working\n\nGtd-Format: 3")
     for (const command of ["next", "abandon"]) {
       const { exitCode, stderr } = await run(repo, command)
       expect(exitCode).toBe(1)
@@ -824,7 +834,7 @@ describe("a history written in a format this gtd does not read", () => {
   it("a commit gtd never wrote is not read for a format, even quoting the trailer", async () => {
     const repo = seed(IDLE_THEN_WORKING)
     repo.writeFile("NOTE.md", "a note\n")
-    repo.seedCommit("feat: x\n\nGtd-Format: 2")
+    repo.seedCommit("feat: x\n\nGtd-Format: 3")
     expect((await run(repo, "next")).exitCode).toBe(0)
   })
 
@@ -832,7 +842,7 @@ describe("a history written in a format this gtd does not read", () => {
     const repo = seed(IDLE_THEN_WORKING)
     const base = repo.resolveRef("HEAD")!
     repo.writeFile("NOTE.md", "a note\n")
-    repo.seedCommit("gtd(human): idle → working\n\nGtd-Step: idle#1\nGtd-Format: 2")
+    repo.seedCommit("gtd(human): idle → working\n\nGtd-Step: idle#1\nGtd-Format: 3")
     repo.updateRef(HISTORY_REF, repo.resolveRef("HEAD")!)
     repo.hardResetTo(base)
     const { exitCode, stderr } = await run(repo, "restore")
@@ -1390,10 +1400,10 @@ export default async () => {
     expect(await nextOf(repo)).toEqual({ target: "accepted" })
   })
 
-  it("a turn that finishes the flow targets the initial step", async () => {
+  it("a turn that finishes a pinned flow targets the unpin", async () => {
     const repo = await atWorking()
     repo.writeFile("REVIEW.md", "an updated review\n")
-    expect(await nextOf(repo)).toMatchObject({ target: "idle" })
+    expect(await nextOf(repo)).toMatchObject({ target: "unpin" })
   })
 
   it("plain gtd next shows the same preview as a `Next:` line", async () => {
@@ -1476,7 +1486,7 @@ export default async () => {
     expect((JSON.parse(stdout) as { readonly script: string }).script).toContain("git commit")
   })
 
-  it("a clean run that finishes the flow lands an ordinary commit re-entering the initial step", async () => {
+  it("a clean run that finishes a pinned flow lands an ordinary commit at the unpin", async () => {
     const repo = await atChecking(REENTRY_WORKFLOW)
     const { stdout, exitCode } = await run(repo, "land", "--json")
     expect(exitCode).toBe(0)
@@ -1485,7 +1495,7 @@ export default async () => {
     expect(script).not.toContain("git reset --mixed")
     expect(script).not.toContain("nothing to retain")
     expect(applyEmittedScript(repo, new Map(), script).ok).toBe(true)
-    expect(repo.lastCommitSubject()).toBe("gtd(check): checking → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): checking → unpin")
   })
 
   it("the same rest with a pending change lands an ordinary commit too", async () => {
@@ -1523,7 +1533,7 @@ export default async () => {
     expect(parsed.script).toContain("nothing to do")
   })
 
-  it("gtd land --json a decision that re-enters the initial step reports settled:false, idle:true, state:idle", async () => {
+  it("gtd land --json a decision that ends a pinned flow reports settled:false, idle:false, state:unpin", async () => {
     const repo = await atChecking(REENTRY_WORKFLOW)
     const { stdout, exitCode } = await run(repo, "land", "--json")
     expect(exitCode).toBe(0)
@@ -1533,8 +1543,8 @@ export default async () => {
       readonly state: string
     }
     expect(parsed.settled).toBe(false)
-    expect(parsed.idle).toBe(true)
-    expect(parsed.state).toBe("idle")
+    expect(parsed.idle).toBe(false)
+    expect(parsed.state).toBe("unpin")
   })
 
   it("gtd land --json an ordinary commit reports settled:false", async () => {
@@ -1683,7 +1693,7 @@ export default async () => {
     const { exitCode, script } = await landAndApply(repo)
     expect(exitCode).toBe(0)
     expect(script).not.toContain("fmt-notes")
-    expect(repo.lastCommitSubject()).toBe("gtd(agent): drafting → idle")
+    expect(repo.lastCommitSubject("HEAD~1")).toBe("gtd(agent): drafting → unpin")
   })
 
   it("`gtd next --json`'s `validate` field carries the mode's format command", async () => {
@@ -1867,7 +1877,7 @@ export default workflow(
   it("writes the rendered summary, with a trailing newline, counting the human turns after the entry commit", async () => {
     const repo = await reviewed()
     const history = repo.commitHistory()
-    const entryHash = history[history.length - 3]!.hash
+    const entryHash = history[history.length - 4]!.hash
     const tipHash = history[history.length - 1]!.hash
 
     const { exitCode, stdout } = await run(repo, "summary")
@@ -1961,7 +1971,7 @@ export default async () => {
   it("refuses once the process has closed and HEAD rests at the initial step again", async () => {
     const repo = await atDeciding()
     await landTurn(repo)
-    expect(repo.lastCommitSubject()).toBe("gtd(human): deciding → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): unpin → idle")
 
     const { exitCode, stdout, stderr } = await run(repo, "base")
     expect(exitCode).toBe(1)

package/src/cli/Program.ts

@@ -47,6 +47,7 @@ import {
   type StatusChange,
   selectPath,
   EXIT_OK,
+  PIN_PATH,
 } from "../wire/index.js"
 import {
   currentRest,
@@ -80,6 +81,7 @@ import {
   deleteRef,
   hardResetTo,
   mixedResetTo,
+  unpinScript,
   ScriptSurface,
   updateRef,
   type RunnableScript,
@@ -617,7 +619,6 @@ const startWorkflow = (
         first: started,
         commandLabel,
         vars: varOverrides,
-        config: rest.config,
       },
     )
     if (plan.kind === "refusal") {
@@ -799,6 +800,7 @@ const runAbandonCommand = (
     const steps: EmitStep[] = [
       { kind: "gitWrite", command: updateRef(HISTORY_REF, tip) },
       { kind: "gitWrite", command: mixedResetTo(run.startParentHash) },
+      { kind: "gitWrite", command: unpinScript(PIN_PATH) },
       { kind: "outcome", command: abandonedOutcome(restState, run.startParentHash, initial) },
     ]
     const required = emitScripts(steps).required
@@ -1060,7 +1062,7 @@ const runCodeThreadsCheckCommand = (): Effect.Effect<void, Error, CommandRequire
     const workspace = yield* Workspace
     const changed = yield* git.changedPaths(rest.run.diffBase)
     const lines = changed
-      .filter((c) => c.status !== "D")
+      .filter((c) => c.status !== "D" && c.path !== PIN_PATH)
       .flatMap(({ path }) => {
         const { threads, findings } = parseCodeThreads(path, workspace.atPath(path) ?? "")
         return [

package/src/cli/Strays.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect"
 import { GitService, GtdError, Narrator, type GitOperations } from "../platform/index.js"
 import { strayPaths } from "../step/index.js"
-import { EXIT_OK, EXIT_STRAYS_FOUND } from "../wire/index.js"
+import { EXIT_OK, EXIT_STRAYS_FOUND, PIN_PATH } from "../wire/index.js"
 import {
   SelectorUsageError,
   writeSelection,
@@ -31,7 +31,8 @@ export const runStraysCommand = (
     const narrator = yield* Narrator
     const base = yield* resolveSide(git, command.base)
     const tip = yield* resolveSide(git, command.tip)
-    const touched = yield* git.diffPaths(base, tip)
+    // The pin is the engine's, never a turn's, so it is never a stray either.
+    const touched = (yield* git.diffPaths(base, tip)).filter((path) => path !== PIN_PATH)
     const strays = strayPaths(touched, command.globs)
     const total = touched.length
 

package/src/cli/index.ts

@@ -12,3 +12,4 @@ export {
   type LiveToolCommands,
 } from "./Cli.js"
 export { ToolCommands, type UiRequest } from "./ToolCommands.js"
+export { runLauncher } from "./Launch.js"