@pmelab/gtd 35.0.0 → 37.0.0

package/src/cli/Cli.ts

@@ -35,7 +35,7 @@ import {
   type JsonMode,
 } from "./Program.js"
 import type { ToolCommands } from "./ToolCommands.js"
-import { EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
+import { EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR, parseContextWindow } from "../wire/index.js"
 
 export type { Command, CommandRequirements } from "./Program.js"
 export { needsOf, standaloneKinds } from "./Program.js"
@@ -90,6 +90,13 @@ const nonNegativeNumber = (raw: string, flag: string): Either.Either<number, str
   return Either.right(n)
 }
 
+const share = (raw: string, flag: string): Either.Either<number, string> => {
+  const n = Number(raw)
+  return raw.trim() !== "" && n > 0 && n <= 1
+    ? Either.right(n)
+    : Either.left(`gtd: ${flag} must be a share of the context window in (0, 1] — got "${raw}"`)
+}
+
 const FLAGS: readonly FlagRow[] = [
   {
     name: "--json",
@@ -245,6 +252,41 @@ const FLAGS: readonly FlagRow[] = [
       "GTD_JUDGE_MODEL, then judge.json, then sonnet",
     ],
   },
+  {
+    name: "--soft",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "contextHook",
+    decode: ([raw]) => share(raw ?? "", "--soft"),
+    scopeError: "gtd: --soft is only valid for `gtd context-hook`",
+    valueHint: "<share>",
+    help: ["(gtd context-hook only) the soft limit; default 0.6"],
+  },
+  {
+    name: "--hard",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "contextHook",
+    decode: ([raw]) => share(raw ?? "", "--hard"),
+    scopeError: "gtd: --hard is only valid for `gtd context-hook`",
+    valueHint: "<share>",
+    help: ["(gtd context-hook only) the hard limit; default 0.7"],
+  },
+  {
+    name: "--window",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "contextHook",
+    decode: ([raw]) => {
+      const window = parseContextWindow(raw)
+      return window !== undefined
+        ? Either.right(window)
+        : Either.left(`gtd: --window must be a positive integer — got "${raw ?? ""}"`)
+    },
+    scopeError: "gtd: --window is only valid for `gtd context-hook`",
+    valueHint: "<tokens>",
+    help: ["(gtd context-hook only) the model's context window in", "tokens; default 200000"],
+  },
   {
     name: "--slice",
     arity: 1,
@@ -593,6 +635,22 @@ const COMMAND_ROWS: readonly CommandRow[] = [
       "~/.config/gtd/loop.json); see docs/driver.md",
     ],
   },
+  {
+    token: "context-hook",
+    kind: "contextHook",
+    arity: "none",
+    details: [
+      "A Claude Code PostToolUse and PreCompact hook that stops an",
+      "agent turn at a share of its context window. Reads the",
+      "hook's input on stdin and the context the transcript's",
+      "latest assistant message used. Past --soft it blocks with a",
+      "request to end the turn with a handoff note; past --hard,",
+      "or at PreCompact, it stops the turn with a stopReason",
+      'starting "gtd: context limit". Prints nothing otherwise,',
+      "and for a subagent's tool call. Always exits 0 on valid",
+      "input; see docs/driver.md",
+    ],
+  },
   {
     token: "summary",
     kind: "summary",
@@ -1182,6 +1240,9 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     readonly "--provider"?: "fixed" | "jev" | "llm"
     readonly "--answers"?: string
     readonly "--slice"?: string
+    readonly "--soft"?: number
+    readonly "--hard"?: number
+    readonly "--window"?: number
   }
 
   // `present.has("--json")` alone can't distinguish bare `--json` (no value
@@ -1285,6 +1346,20 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     }
   }
 
+  if (kind === "contextHook") {
+    return {
+      kind: "command",
+      command: {
+        kind: "contextHook",
+        ...(bag["--soft"] !== undefined ? { soft: bag["--soft"] } : {}),
+        ...(bag["--hard"] !== undefined ? { hard: bag["--hard"] } : {}),
+        ...(bag["--window"] !== undefined ? { window: bag["--window"] } : {}),
+      },
+      json,
+      verbose,
+    }
+  }
+
   if (kind === "summary") {
     return {
       kind: "command",

package/src/cli/Program.test.ts

@@ -1686,6 +1686,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
     uncheck: { kind: "uncheck", file: ".gtd/REVIEW.md" },
     install: { kind: "install" },
     loop: { kind: "loop" },
+    contextHook: { kind: "contextHook" },
     summary: { kind: "summary" },
     base: { kind: "base" },
     judge: { kind: "judge" },

package/src/cli/Program.ts

@@ -162,6 +162,12 @@ export type Command =
   | { readonly kind: "uncheck"; readonly file: string }
   | { readonly kind: "install" }
   | { readonly kind: "loop" }
+  | {
+      readonly kind: "contextHook"
+      readonly soft?: number
+      readonly hard?: number
+      readonly window?: number
+    }
   | { readonly kind: "summary"; readonly slice?: string }
   | { readonly kind: "base" }
   | { readonly kind: "judge" }
@@ -434,6 +440,24 @@ const readStdin = (): Effect.Effect<string, Error> =>
     catch: (e) => (e instanceof Error ? e : new Error(String(e))),
   })
 
+/** Stdout is written once: a hook reads one JSON document, or none. */
+const runContextHookCommand = (
+  command: Extract<Command, { kind: "contextHook" }>,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, ToolCommands> =>
+  Effect.gen(function* () {
+    const tools = yield* ToolCommands
+    const input = yield* readStdin()
+    out.write(
+      yield* tools.contextHook({
+        input,
+        ...(command.soft !== undefined ? { soft: command.soft } : {}),
+        ...(command.hard !== undefined ? { hard: command.hard } : {}),
+        ...(command.window !== undefined ? { window: command.window } : {}),
+      }),
+    )
+  })
+
 /** Stdout is written once, after the answerer resolves — a rejection leaves it empty. */
 const runJudgeRunCommand = (
   command: Extract<Command, { kind: "judgeRun" }>,
@@ -1189,6 +1213,7 @@ export const needsOf = (kind: Command["kind"]): Needs => {
     case "lsp":
     case "install":
     case "loop":
+    case "contextHook":
     case "judgeRun":
     case "strays":
       return "none"
@@ -1207,6 +1232,7 @@ export const standaloneKinds = (): readonly Command["kind"][] => [
   "uncheck",
   "install",
   "loop",
+  "contextHook",
   "judgeRun",
   "strays",
 ]
@@ -1278,6 +1304,8 @@ const dispatchVoidCommand = (
       return runInstallCommand(out)
     case "loop":
       return runLoopCommand()
+    case "contextHook":
+      return runContextHookCommand(command, out)
     case "summary":
       return runSummaryCommand(out, command.slice)
     case "base":

package/src/cli/ToolCommands.ts

@@ -1,6 +1,7 @@
 import { Context } from "effect"
 import type { Effect } from "effect"
 import type { UiSettings } from "../flows/index.js"
+import type { ContextHookRequest } from "../wire/index.js"
 
 /** How to run THIS gtd — a driver (the loop, the LSP) never reads a different version's state than the one it ships with. */
 export type SelfGtd = readonly [string, ...string[]]
@@ -38,6 +39,8 @@ export class ToolCommands extends Context.Tag("ToolCommands")<
     ) => Effect.Effect<void, Error>
     readonly lsp: (gtd: SelfGtd) => Effect.Effect<void, Error>
     readonly loop: (gtd: SelfGtd) => Effect.Effect<void, Error>
+    /** The hook's stdout: a JSON document, or empty to let the turn go on. */
+    readonly contextHook: (request: ContextHookRequest) => Effect.Effect<string, Error>
     readonly judge: (request: JudgeRequest) => Promise<string>
   }
 >() {}

package/src/edge/Edge.ts

@@ -54,6 +54,7 @@ import {
   type ModelCost,
   type SliceEntry,
   type StepAccess,
+  type StepContextLimit,
 } from "../wire/index.js"
 
 import { GTD_VERSION } from "../install/index.js"
@@ -722,6 +723,13 @@ type RequestOf<K extends ReachedStep["request"]["kind"]> = Extract<
   { kind: K }
 >
 
+const stepContext = (
+  context: { readonly soft?: number | undefined; readonly hard?: number | undefined } | undefined,
+): StepContextLimit | undefined =>
+  context === undefined
+    ? undefined
+    : { ...optional("soft", context.soft), ...optional("hard", context.hard) }
+
 const promptDef = (
   common: StepCommon,
   request: RequestOf<"agent">,
@@ -735,6 +743,7 @@ const promptDef = (
   ...optional("system", request.options.system),
   ...optional("allowEmpty", request.options.allowEmpty),
   ...optional("keep", request.options.keep),
+  ...optional("context", stepContext(request.options.context)),
   ...optional("skills", skills),
   ...optional("access", access),
 })
@@ -850,6 +859,7 @@ export interface RestHints {
   readonly mode?: string
   readonly skills?: readonly string[]
   readonly access?: StepAccess
+  readonly context?: StepContextLimit
 }
 
 const hintsOf = (def: StepDef): RestHints => ({
@@ -861,6 +871,7 @@ const hintsOf = (def: StepDef): RestHints => ({
   ...optional("mode", def.mode),
   ...optional("skills", def.skills),
   ...optional("access", def.access),
+  ...optional("context", def.context),
 })
 
 const normalizeStatus = (raw: string): ChangeStatus => (raw === "A" ? "A" : raw === "D" ? "D" : "M")

package/src/flows/runtime.ts

@@ -16,9 +16,18 @@ export interface SteeringOptions {
   readonly base?: string | undefined
 }
 
+/** Shares of the model's context window at which a driver stops the turn — `gtd next --json`'s `context`. */
+export interface ContextLimitOptions {
+  /** Ask the agent to wrap up with a handoff note. Driver default 0.6. */
+  readonly soft?: number | undefined
+  /** Stop the turn outright. Driver default 0.7. */
+  readonly hard?: number | undefined
+}
+
 export interface AgentOptions extends SteeringOptions {
   readonly model?: string | undefined
   readonly system?: string | undefined
+  readonly context?: ContextLimitOptions | undefined
   /**
    * A turn that changes nothing completes the step. Without this an empty turn
    * is an attempt: recorded, but the process stays at the step (a stall).
@@ -115,6 +124,8 @@ export interface ScopeOptions {
   readonly model?: string | undefined
   /** The system prompt every agent step inside runs with, unless it sets its own. */
   readonly system?: string | undefined
+  /** The context limit every agent step inside runs with; a nested scope's or a step's own replaces it key by key. */
+  readonly context?: ContextLimitOptions | undefined
   /** The skill names every agent step inside declares — `gtd next --json`'s `skills`. A nested scope inherits it unless it sets its own. */
   readonly skills?: readonly string[] | undefined
   /** The file access every agent step inside runs with — `gtd next --json`'s `access`. A nested scope inherits it; its own replaces it wholesale. */

package/src/flows/scripts.ts

@@ -55,25 +55,31 @@ export const checkScript = (command: string, options: CheckScriptOptions): strin
   ].join("\n")
 }
 
-/**
- * Reverse-apply `commit`'s changes to the working tree. A failure — the
- * patch no longer applies — writes `failure` and git's error to `report`,
- * since a failed revert and one with nothing to undo both leave the tree clean.
- */
-export const revertScript = (commit: string, report: string, failure: string): string => {
+const patchScript = (
+  commit: string,
+  report: string,
+  failure: string,
+  reverse: boolean,
+  exclude: readonly string[] = [],
+): string => {
+  const paths =
+    exclude.length === 0
+      ? ""
+      : ` . ${exclude.map((p) => quote(`:(exclude,literal)${p}`)).join(" ")}`
   const range = `${quote(`${commit}^`)} ${quote(commit)}`
   const error = quote(`${report}.output`)
   return [
     "#!/usr/bin/env sh",
     "set +e",
-    `if ! git diff --quiet ${range} --; then`,
+    `if ! git diff --quiet ${range} --${paths}; then`,
     `  mkdir -p "$(dirname ${quote(report)})"`,
-    `  git diff --binary ${range} -- | git apply -R 2> ${error}`,
+    // Pinned flags: a user's diff.noprefix, color.ui, diff.external, textconv or apply.whitespace would change the patch.
+    `  git diff --binary --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ ${range} --${paths} | git apply --whitespace=nowarn${reverse ? " -R" : ""} 2> ${error}`,
     "  code=$?",
     '  if [ "$code" -ne 0 ]; then',
     "    {",
     `      printf '%s\\n\\n' ${quote(failure)}`,
-    `      if [ -s ${error} ]; then cat ${error}; else printf 'Reverting it exited %s and produced no output.\\n' "$code"; fi`,
+    `      if [ -s ${error} ]; then cat ${error}; else printf '${reverse ? "Reverting" : "Applying"} it exited %s and produced no output.\\n' "$code"; fi`,
     `    } > ${quote(report)}`,
     "  fi",
     `  rm -f ${error}`,
@@ -82,6 +88,22 @@ export const revertScript = (commit: string, report: string, failure: string): s
   ].join("\n")
 }
 
+/**
+ * Reverse-apply `commit`'s changes to the working tree. A failure — the
+ * patch no longer applies — writes `failure` and git's error to `report`,
+ * since a failed revert and one with nothing to undo both leave the tree clean.
+ */
+export const revertScript = (commit: string, report: string, failure: string): string =>
+  patchScript(commit, report, failure, true)
+
+/** Apply `commit`'s changes outside `exclude` to the working tree; a failure is reported as `revertScript`'s is. */
+export const applyScript = (
+  commit: string,
+  report: string,
+  failure: string,
+  exclude: readonly string[] = [],
+): string => patchScript(commit, report, failure, false, exclude)
+
 /**
  * Undo the edits one commit made to `paths`: each goes back to its content
  * before `commit` — or away, when `commit` added it — but only while it is

package/src/replay/Replay.ts

@@ -8,6 +8,7 @@ import {
   type ScopeAccess,
   type AccessDef,
   type ScopeOptions,
+  type ContextLimitOptions,
   type StepRequest,
   type Flow,
   type Mark,
@@ -21,7 +22,7 @@ import {
   unansweredQuestions,
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
-import { globMatches } from "../wire/index.js"
+import { contextLimitFault, contextShapeFault, globMatches } from "../wire/index.js"
 import { refNameFault } from "./RefName.js"
 import { IMPLICIT_SLICE, SLICE_NAME, type SliceSpan } from "./Slices.js"
 import { diffTrees, isEmptyDiff, type TreeView } from "./Tree.js"
@@ -207,6 +208,28 @@ const budgeted = (
   return { evidence: bounded, truncated }
 }
 
+// The innermost of `chain`, named by its full path.
+const scopeLabel = (chain: readonly ScopeOptions[]): string => {
+  const path = chain.flatMap((o) => (o.name === undefined ? [] : [o.name])).join(".")
+  if (chain.at(-1)?.name !== undefined) return `scope "${path}"`
+  return path === "" ? "an unnamed scope" : `an unnamed scope inside "${path}"`
+}
+
+// Key by key, innermost last: a scope or step that sets only `hard` keeps the outer `soft`.
+const inheritedContext = (
+  layers: readonly (ContextLimitOptions | undefined)[],
+): ContextLimitOptions | undefined =>
+  layers.reduce<ContextLimitOptions | undefined>(
+    (merged, layer) =>
+      layer === undefined
+        ? merged
+        : {
+            ...merged,
+            ...Object.fromEntries(Object.entries(layer).filter(([, value]) => value !== undefined)),
+          },
+    undefined,
+  )
+
 interface Identity {
   readonly model: string | undefined
   readonly system: string | undefined
@@ -243,7 +266,7 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 // The option keys each step accepts. A gtd.config.ts is evaluated without a
 // type check, so a misspelt key would otherwise be silently ignored.
 const KNOWN_OPTIONS: Readonly<Record<StepKind, ReadonlySet<string>>> = {
-  agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty", "keep"]),
+  agent: new Set([...STEERING_OPTIONS, "model", "system", "context", "allowEmpty", "keep"]),
   human: new Set([...STEERING_OPTIONS, "message", "acceptClean", "approve"]),
   run: new Set(STEERING_OPTIONS),
   judge: new Set([...STEERING_OPTIONS, "message"]),
@@ -426,11 +449,13 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         if (s.model !== undefined) persona.model = s.model
         if (s.system !== undefined) persona.system = s.system
       }
+      const context = inheritedContext([...scopes.map((s) => s.context), request.options.context])
       return {
         ...request,
         options: {
           ...persona,
           ...request.options,
+          ...(context === undefined ? {} : { context }),
         },
       }
     }
@@ -575,6 +600,28 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     return landPending(step, input.pending)
   }
 
+  // Each layer on its own first, so a bad scope or workflow option is named as
+  // such rather than blamed on the step it reached; then the merged limit.
+  const scopeContextFault = (): string | undefined => {
+    for (const [i, s] of scopes.entries()) {
+      const fault = s.context === undefined ? undefined : contextShapeFault(s.context)
+      if (fault !== undefined)
+        return `the context of ${scopeLabel(scopes.slice(0, i + 1))}: ${fault}`
+    }
+    return undefined
+  }
+
+  const resolvedContextFault = (
+    request: Extract<StepRequest, { kind: "agent" }>,
+  ): string | undefined => {
+    const own = request.options.context
+    const layered = scopeContextFault() ?? (own === undefined ? undefined : contextShapeFault(own))
+    if (layered !== undefined) return layered
+    const resolved = resolve(request)
+    const context = resolved.kind === "agent" ? resolved.options.context : undefined
+    return context === undefined ? undefined : contextLimitFault(context)
+  }
+
   // gtd.config.ts is loaded without a type check.
   const requestFault = (request: Exclude<StepRequest, { kind: "restart" }>): string | undefined => {
     if (request.kind === "run" && typeof request.body !== "string") {
@@ -582,6 +629,8 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     }
     if (request.kind !== "agent") return undefined
     const name = scoped(request.name)
+    const contextFault = resolvedContextFault(request)
+    if (contextFault !== undefined) return `gtd: step "${name}": ${contextFault}`
     if (request.options.keep === true) {
       // A clean allowEmpty keep would land an ordinary commit with no Gtd-Kept: a silent skip.
       if (request.options.allowEmpty === true) {

package/src/testkit/FlowScripts.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest"
 import {
+  applyScript,
   checkScript,
   moveScript,
   removeScript,
@@ -178,6 +179,63 @@ for (const makeTier of gitTiers) {
       })
     })
 
+    describe("applyScript", () => {
+      it("replays a commit's modifications, additions and deletions onto the working tree", () => {
+        t.seed.commit("feat: base", { "mod.txt": "before", "gone.txt": "g" })
+        t.seed.writeFile("mod.txt", "after")
+        t.seed.writeFile("added.txt", "new")
+        t.seed.deleteFile("gone.txt")
+        t.seed.stageAll()
+        t.seed.commit("feat: change", {})
+        const commit = t.observe.resolveRef("HEAD")
+        t.seed.writeFile("gone.txt", "g")
+        t.seed.deleteFile("added.txt")
+        t.seed.stageAll()
+        t.seed.commit("revert: change", { "mod.txt": "before" })
+        const head = t.observe.resolveRef("HEAD")
+        expect(run(applyScript(commit, REPORT, "could not apply")).ok).toBe(true)
+        expect(read("mod.txt")).toBe("after")
+        expect(read("added.txt")).toBe("new")
+        expect(read("gone.txt")).toBeUndefined()
+        expect(read(REPORT)).toBeUndefined()
+        expect(t.observe.resolveRef("HEAD")).toBe(head)
+      })
+
+      it("leaves excluded paths as they are", () => {
+        t.seed.commit("feat: base", { "a.txt": "a0", ".gtd/R.md": "r0" })
+        t.seed.commit("feat: change", { "a.txt": "a1", ".gtd/R.md": "r1", ".gtd/new.md": "n" })
+        const commit = t.observe.resolveRef("HEAD")
+        t.seed.commit("revert: change", { "a.txt": "a0", ".gtd/R.md": "r2" })
+        t.seed.commitDeletion(".gtd/new.md", "revert: change")
+        expect(run(applyScript(commit, REPORT, "could not apply", [".gtd"])).ok).toBe(true)
+        expect(read(REPORT)).toBeUndefined()
+        expect(read("a.txt")).toBe("a1")
+        expect(read(".gtd/R.md")).toBe("r2")
+        expect(read(".gtd/new.md")).toBeUndefined()
+      })
+
+      it("does nothing for a commit with nothing to apply", () => {
+        t.seed.commit("feat: empty", {})
+        const commit = t.observe.resolveRef("HEAD")
+        expect(run(applyScript(commit, REPORT, "could not apply")).ok).toBe(true)
+        expect(read(REPORT)).toBeUndefined()
+        expect(t.observe.statusPorcelain()).toBe("")
+      })
+
+      it("reports a commit that cannot apply, leaving the tree untouched", () => {
+        t.seed.commit("feat: base", { "a.txt": "a0" })
+        t.seed.commit("feat: change", { "a.txt": "a1", "b.txt": "b1" })
+        const commit = t.observe.resolveRef("HEAD")
+        t.seed.commitDeletion("b.txt", "revert: change")
+        t.seed.commit("revert: change", { "a.txt": "a0" })
+        t.seed.writeFile("b.txt", "other")
+        expect(run(applyScript(commit, REPORT, "could not apply")).ok).toBe(true)
+        expect(read(REPORT)).toMatch(/^could not apply\n\n\S/)
+        expect(read("a.txt")).toBe("a0")
+        expect(read("b.txt")).toBe("other")
+      })
+    })
+
     describe("checkScript", () => {
       const options = { report: REPORT, stamp: "abc1234" }
 

package/src/testkit/FlowScripts.ts

@@ -5,6 +5,7 @@
 // `sh` and this twin, so the two cannot drift apart silently.
 
 import {
+  applyScript,
   checkScript,
   moveScript,
   removeScript,
@@ -129,44 +130,80 @@ const recognizeRestore = (repo: InMemRepo, script: string): FlowScriptResult | u
 
 const PATCH_FAILED = "error: patch does not apply"
 
+const outside = (path: string, exclude: readonly string[]): boolean =>
+  !exclude.some((e) => path === e || path.startsWith(`${e}/`))
+
+/** Why `path` blocks the patch, `undefined` when it is exactly as `from` has it. */
+const blocking = (repo: InMemRepo, path: string, from: string, to: string): string | undefined => {
+  const expected = repo.fileAtRef(from, path)
+  const current = repo.readFile(path) ?? null
+  if (current === expected) return undefined
+  if (current === null || expected === null || repo.fileAtRef(to, path) === null) {
+    return `${PATCH_FAILED}: ${path}`
+  }
+  throw new Error(
+    `testkit: cannot tell in memory whether the patch of ${from}..${to} applies to the hand-edited ${path} — run this @live`,
+  )
+}
+
 /**
- * `git diff C^ C | git apply -R`, which is all or nothing. A file still
- * exactly as `C` left it reverts; a file gone, or one `C` added and that
- * changed since, fails the whole patch. A file `C` modified and that changed
- * since may still apply through its context — that needs real git, so it
- * throws rather than guess.
+ * `git diff C^ C | git apply [-R]`, which is all or nothing. A file exactly
+ * as the side being undone (`from`) has it moves to the other side (`to`); a
+ * file missing where `from` has one, or present where `from` has none, fails
+ * the whole patch. A file both sides have that differs from `from` may still
+ * apply through its context — that needs real git, so `blocking` throws
+ * rather than guess.
  */
-const reverseApply = (repo: InMemRepo, commit: string): string | undefined => {
+const patch = (
+  repo: InMemRepo,
+  commit: string,
+  reverse: boolean,
+  exclude: readonly string[],
+): string | undefined => {
   const parent = `${commit}^`
+  const [from, to] = reverse ? [commit, parent] : [parent, commit]
   const paths = new Set([...repo.pathsAtRef(parent), ...repo.pathsAtRef(commit)])
-  const changed = [...paths].filter((p) => repo.fileAtRef(parent, p) !== repo.fileAtRef(commit, p))
+  const changed = [...paths].filter(
+    (p) => repo.fileAtRef(parent, p) !== repo.fileAtRef(commit, p) && outside(p, exclude),
+  )
   for (const path of changed) {
-    const after = repo.fileAtRef(commit, path)
-    const current = repo.readFile(path) ?? null
-    if (current === after) continue
-    if (current === null || after === null || repo.fileAtRef(parent, path) === null) {
-      return `${PATCH_FAILED}: ${path}`
-    }
-    throw new Error(
-      `testkit: cannot tell in memory whether reverting ${commit} applies to the hand-edited ${path} — run this @live`,
-    )
+    const error = blocking(repo, path, from, to)
+    if (error !== undefined) return error
   }
   for (const path of changed) {
-    const before = repo.fileAtRef(parent, path)
-    if (before === null) repo.deleteFile(path)
-    else repo.writeFile(path, before)
+    const content = repo.fileAtRef(to, path)
+    if (content === null) repo.deleteFile(path)
+    else repo.writeFile(path, content)
   }
   return undefined
 }
 
-const recognizeRevert = (repo: InMemRepo, script: string): FlowScriptResult | undefined => {
+interface ParsedPatch {
+  readonly commit: string
+  readonly failure: string
+  readonly report: string
+  readonly exclude: readonly string[]
+}
+
+const parsePatch = (script: string): ParsedPatch | undefined => {
   const lines = script.split("\n")
-  const [, commit] = words(lines.find((l) => l.startsWith("if ! git diff --quiet ")) ?? "")
+  const [, commit, ...pathspecs] = words(
+    lines.find((l) => l.startsWith("if ! git diff --quiet ")) ?? "",
+  )
   const [, failure] = words(lines.find((l) => l.includes("printf '%s\\n\\n' ")) ?? "")
   const [report] = words(lines.find((l) => l.startsWith("    } > ")) ?? "")
   if (commit === undefined || failure === undefined || report === undefined) return undefined
-  if (revertScript(commit, report, failure) !== script) return undefined
-  const error = reverseApply(repo, commit)
+  const exclude = pathspecs.map((p) => p.replace(/^:\(exclude,literal\)/, ""))
+  return { commit, failure, report, exclude }
+}
+
+const recognizePatch = (repo: InMemRepo, script: string): FlowScriptResult | undefined => {
+  const parsed = parsePatch(script)
+  if (parsed === undefined) return undefined
+  const { commit, failure, report, exclude } = parsed
+  const reverse = revertScript(commit, report, failure) === script
+  if (!reverse && applyScript(commit, report, failure, exclude) !== script) return undefined
+  const error = patch(repo, commit, reverse, reverse ? [] : exclude)
   if (error !== undefined) repo.writeFile(report, `${failure}\n\n${error}\n`)
   return ok()
 }
@@ -319,7 +356,7 @@ export const applyFlowScript = (
     recognizeRemove(repo, script) ??
     recognizeMove(repo, script) ??
     recognizeShow(repo, script) ??
-    recognizeRevert(repo, script) ??
+    recognizePatch(repo, script) ??
     recognizeRestore(repo, script) ??
     recognizeCheck(repo, commands, script)
   )

package/src/testkit/Layers.ts

@@ -206,6 +206,7 @@ const missingToolCommands: ToolCommands["Type"] = {
   ui: missingTool("ui"),
   lsp: missingTool("lsp"),
   loop: missingTool("loop"),
+  contextHook: missingTool("context-hook"),
   judge: () =>
     Promise.reject(
       new Error("gtd judge run: ToolCommands has no test double wired into testLayers()"),