@pmelab/gtd 27.3.0 → 27.5.0

package/src/flags/index.ts

@@ -1,5 +1,5 @@
-// A flag may change how a step runs, never which step comes next: flags are not recorded in
-// history, so replay must not read them. No lint rule enforces this.
+// Flags are not recorded in history, so replay must not read the live value: flow code may
+// branch on a flag only through its pinned `flag_<name>` setting. No lint rule enforces this.
 
 export type FlagKind = "release" | "ops" | "experiment"
 
@@ -13,7 +13,9 @@ export interface FlagDeclaration {
   readonly defaultOn?: boolean
 }
 
-export const FLAGS = [] as const satisfies readonly FlagDeclaration[]
+export const FLAGS = [
+  { name: "naive_pass", owner: "pmelab", expiry: "2027-01-15", kind: "release" },
+] as const satisfies readonly FlagDeclaration[]
 
 /** A misspelt name is a compile error. */
 export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {
@@ -22,6 +24,12 @@ export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {
 
 const BOOL: Record<string, boolean> = { "0": false, false: false, "1": true, true: true }
 
+/** A `flag_<name>` setting's value as the pinned `"1"`/`"0"`, or undefined when garbled. */
+export const flagSettingValue = (raw: string): "0" | "1" | undefined => {
+  const key = raw.toLowerCase()
+  return Object.hasOwn(BOOL, key) ? (BOOL[key] ? "1" : "0") : undefined
+}
+
 export const resolveFlags = <const R extends readonly FlagDeclaration[] = typeof FLAGS>(
   env: Readonly<Record<string, string | undefined>>,
   registry: R = FLAGS as unknown as R,
@@ -41,3 +49,6 @@ export const resolveFlags = <const R extends readonly FlagDeclaration[] = typeof
   }
   return out as Flags<R>
 }
+
+export const flagSettings = (flags: Readonly<Record<string, boolean>>): Record<string, string> =>
+  Object.fromEntries(Object.entries(flags).map(([name, on]) => [`flag_${name}`, on ? "1" : "0"]))

package/src/flows/helpers.ts

@@ -2,6 +2,7 @@ import {
   changes,
   codeThreads,
   head,
+  human,
   judge,
   matches,
   openQuestions,
@@ -151,12 +152,14 @@ export interface DiffShapeOptions {
   readonly changes: readonly Change[]
   /** Globs in the `changes(pattern)` / `gtd strays` dialect. */
   readonly allow: readonly string[]
+  /** Exact paths never strays; compared by equality, so a `*` in one covers nothing else. */
+  readonly exempt?: readonly string[] | undefined
   readonly minP?: number | undefined
 }
 
 export interface DiffShapeResult {
   readonly choice: DiffShape
-  /** Sorted, equal to `gtd strays` for the same range and globs. */
+  /** Sorted, equal to `gtd strays` for the same range and globs, minus `exempt`. */
   readonly strays: readonly string[]
   /** Strays with a side that could not be read (sorted); `refactor-first` skipped the judge. */
   readonly unreadable: readonly string[]
@@ -197,7 +200,9 @@ export const judgeDiffShape = async (
   options: DiffShapeOptions,
 ): Promise<DiffShapeResult> => {
   const { changes: all, allow } = options
-  const isStray = (c: Change): boolean => !allow.some((pattern) => matches(c.path, pattern))
+  const exempt = options.exempt ?? []
+  const isStray = (c: Change): boolean =>
+    !exempt.includes(c.path) && !allow.some((pattern) => matches(c.path, pattern))
   const strayChanges: Change[] = all
     .filter(isStray)
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
@@ -250,3 +255,30 @@ export const judgeDiffShape = async (
       : "refactor-first"
   return { choice, strays, unreadable: [], judgment }
 }
+
+export const displayPath = (path: string): string =>
+  // eslint-disable-next-line no-control-regex -- the control range IS the point
+  /[\x00-\x1f\x7f-\x9f]/.test(path) ? JSON.stringify(path) : path
+
+const seamReport = (shape: DiffShapeResult): string => {
+  const unreadable = new Set(shape.unreadable)
+  const strays = shape.strays.map(
+    (path) => `- ${displayPath(path)}${unreadable.has(path) ? " (unreadable — not judged)" : ""}`,
+  )
+  return [
+    "Seam report: the judge found the diff's shape needs a refactor first. These paths stray outside the allowlist:",
+    "",
+    ...strays,
+    "",
+    "Landing a clean tree with `gtd land` approves this diff exactly as judged; edits are refused. To stop instead, run `gtd abandon`.",
+  ].join("\n")
+}
+
+/**
+ * Rest at an approval gate `name` showing the seam report — only when
+ * `shape.choice` is `refactor-first`. `land` and `reject` reach no step.
+ */
+export const seamGate = async (name: string, shape: DiffShapeResult): Promise<void> => {
+  if (shape.choice !== "refactor-first") return
+  await human(name, { message: seamReport(shape), approve: true })
+}

package/src/flows/runtime.ts

@@ -39,6 +39,13 @@ export interface HumanOptions extends SteeringOptions {
    * Without this a clean landing is a no-op: the gate waits for a change.
    */
   readonly acceptClean?: boolean | undefined
+  /**
+   * A sign-off gate: only a clean landing completes it, and that commit
+   * carries `Gtd-Approved: {"step":"<step>#<n>","name":"<name>","email":"<email>"}`.
+   * A dirty landing is refused. Implies `acceptClean`. Cannot be combined with
+   * `mode` or `file`: an approval records exactly the judged tree.
+   */
+  readonly approve?: boolean | undefined
 }
 
 export interface RunOptions extends SteeringOptions {}

package/src/install/Install.ts

@@ -246,7 +246,8 @@ skills, \`skills\` (an array of the skill names, already trimmed and split —
 (\`{read, write}\`, each an array of globs or \`null\` for unrestricted). When set: \`model\`, \`memory\`,
 \`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\`.
+\`cost\`, \`costByModel\`. Always \`approvals\` (an array of
+\`{step, name, email, commit}\`, \`[]\` when none).
 
 \`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

package/src/platform/Git.test.ts

@@ -3,7 +3,7 @@ import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "nod
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { NodeContext } from "@effect/platform-node"
-import { Cause, Effect, Exit } from "effect"
+import { Cause, Effect, Exit, Option } from "effect"
 import { describe, expect, it } from "vitest"
 import { GitService, InvalidRefError, resolvedRefOrCorrupted } from "./Git.js"
 import { Host } from "./index.js"
@@ -140,3 +140,27 @@ describe("diffPaths [Live]", () => {
     }
   })
 })
+
+describe("authorIdent [Live]", () => {
+  it("is none when git has no author identity", async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-ident-")))
+    try {
+      const git = (...args: string[]) =>
+        execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: "pipe" })
+      git("init")
+      git("config", "user.useConfigOnly", "true")
+      git("config", "user.name", "")
+      git("config", "user.email", "")
+      const ident = await Effect.runPromise(
+        Effect.flatMap(GitService, (g) => g.authorIdent()).pipe(
+          Effect.provide(GitService.Live),
+          Effect.provide(Host.layer({ root, home: root, env: {} })),
+          Effect.provide(NodeContext.layer),
+        ),
+      )
+      expect(Option.isNone(ident)).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})

package/src/platform/Git.ts

@@ -94,6 +94,15 @@ export interface GitReaderOperations {
   readonly changedPaths: (
     base?: string,
   ) => Effect.Effect<ReadonlyArray<{ readonly path: string; readonly status: string }>, Error>
+  /**
+   * The index vs `HEAD`, as `{path, status}` pairs — what a commit would carry
+   * that `changedPaths` misses when the worktree reverted a staged edit. Empty
+   * before the first commit.
+   */
+  readonly stagedPaths: () => Effect.Effect<
+    ReadonlyArray<{ readonly path: string; readonly status: string }>,
+    Error
+  >
   /**
    * Paths whose content differs between the trees of `base` and `tip`: added,
    * modified and deleted alike; a rename reports both paths (no rename
@@ -103,8 +112,12 @@ export interface GitReaderOperations {
    * working tree. Fails when either side does not resolve.
    */
   readonly diffPaths: (base: string, tip: string) => Effect.Effect<ReadonlyArray<string>, Error>
+  /** `git var GIT_AUTHOR_IDENT`'s name and email; `None` when git has no identity. */
+  readonly authorIdent: () => Effect.Effect<Option.Option<AuthorIdent>, Error>
 }
 
+export type AuthorIdent = { readonly name: string; readonly email: string }
+
 export interface GitWriterOperations {
   /**
    * `git add -A` then commit. `--allow-empty` is load-bearing: the machine
@@ -406,6 +419,17 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
         "--",
       ).pipe(Effect.map(splitNul)),
 
+    authorIdent: () =>
+      exec("git", "var", "GIT_AUTHOR_IDENT").pipe(
+        Effect.map((out) => {
+          const match = /^(.*?) <([^<>]*)> \d+ [+-]\d{4}$/.exec(out.trim())
+          return match === null || match[1] === "" || match[2] === ""
+            ? Option.none()
+            : Option.some({ name: match[1]!, email: match[2]! })
+        }),
+        Effect.catchAll(() => Effect.succeed(Option.none())),
+      ),
+
     changedPaths: (base?: string) =>
       Effect.gen(function* () {
         const ref = base ?? "HEAD"
@@ -443,6 +467,12 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
         return all
       }),
 
+    stagedPaths: () =>
+      exec("git", "diff", "--cached", "--name-status", "--no-renames", "-z", "HEAD").pipe(
+        Effect.catchAll(() => Effect.succeed("")),
+        Effect.map((out) => parseNameStatus(splitNul(out))),
+      ),
+
     resolveRef: (ref: string) =>
       exec("git", "rev-parse", "--verify", "--end-of-options", ref).pipe(
         Effect.map((s) => s.trim()),

package/src/platform/index.ts

@@ -15,6 +15,7 @@ export {
   type GitOperations,
   type GitReaderOperations,
   type GitWriterOperations,
+  type AuthorIdent,
 } from "./Git.js"
 export { Narrator, GtdError, GtdUsageError, renderFailure } from "./Commentary.js"
 export { CommandRunner } from "./CommandRunner.js"

package/src/replay/Format.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { formatFault } from "./Format.js"
+import { formatCommitMessage, formatFault, parseCommitMessage } from "./index.js"
 
 describe("the history format", () => {
   it("accepts a history entirely in the current format", () => {
@@ -18,3 +18,18 @@ describe("the history format", () => {
     )
   })
 })
+
+describe("Gtd-Approved and the history format", () => {
+  it("leaves Gtd-Format at 1 on a message carrying it", () => {
+    const message = formatCommitMessage({
+      actor: "human",
+      to: "b",
+      approved: { step: { name: "seam", occurrence: 1 }, name: "Test", email: "test@test.com" },
+    })
+    expect(message).toContain(
+      'Gtd-Approved: {"step":"seam#1","name":"Test","email":"test@test.com"}',
+    )
+    expect(message).toContain("Gtd-Format: 1")
+    expect(parseCommitMessage(message).format).toBe(1)
+  })
+})

package/src/replay/Replay.test.ts

@@ -1076,3 +1076,94 @@ describe("replay: access resolution", () => {
     expect(outcome.kind === "failed" && outcome.message).toContain('scope "a"')
   })
 })
+
+describe("human({ approve })", () => {
+  const gate: Flow = async () => {
+    await human("gate", { approve: true })
+    await human("after")
+  }
+  const sign = (step: string, occurrence: number) => ({
+    step: { name: step, occurrence },
+    name: "Test",
+    email: "test@test.com",
+  })
+  const approval = (approved?: ReturnType<typeof sign>): string =>
+    formatCommitMessage({
+      actor: "human",
+      from: "gate",
+      to: "after",
+      step: { name: "gate", occurrence: 1 },
+      ...(approved !== undefined ? { approved } : {}),
+    })
+
+  it("is accepted: no unknown-option failure, the gate is the rest", async () => {
+    const outcome = await replayOf(gate, new History())
+    expect(outcome.kind).toBe("rest")
+    if (outcome.kind === "rest") expect(outcome.rest.name).toBe("gate")
+  })
+
+  it("consumes a commit carrying a matching Gtd-Approved and continues past the gate", async () => {
+    const h = new History().raw(approval(sign("gate", 1)))
+    const outcome = await replayOf(gate, h)
+    expect(outcome.kind).toBe("rest")
+    if (outcome.kind === "rest") expect(outcome.rest.name).toBe("after")
+  })
+
+  it("diverges on a commit without Gtd-Approved", async () => {
+    const outcome = await replayOf(gate, new History().raw(approval()))
+    expect(outcome).toEqual({
+      kind: "divergence",
+      message: `gtd: commit ${hashOf(1).slice(0, 7)} completes approval gate "gate#1" but records no Gtd-Approved for it — the workflow changed under this process; run \`gtd abandon\` to start over`,
+    })
+  })
+
+  it("diverges on a Gtd-Approved naming another step, or another occurrence", async () => {
+    for (const other of [sign("elsewhere", 1), sign("gate", 2)]) {
+      const outcome = await replayOf(gate, new History().raw(approval(other)))
+      expect(outcome.kind).toBe("divergence")
+      expect(outcome.kind === "divergence" && outcome.message).toContain(
+        'completes approval gate "gate#1" but records no Gtd-Approved for it',
+      )
+    }
+  })
+
+  describe("refuses mode and file", () => {
+    const tail =
+      "in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing"
+    const outcomeOf = async (options: Record<string, unknown>) =>
+      replayOf(async () => {
+        await human("gate", options as never)
+      }, new History())
+
+    it.each([
+      [{ approve: true, mode: "review" }, "mode"],
+      [{ approve: true, file: ".gtd/REVIEW.md" }, "file"],
+      [{ approve: true, mode: "review", file: ".gtd/REVIEW.md" }, "mode, file"],
+    ])("fails on %j naming %s", async (options, keys) => {
+      expect(await outcomeOf(options)).toEqual({
+        kind: "failed",
+        message: `gtd: step "gate": approve cannot be combined with ${keys} ${tail}`,
+      })
+    })
+
+    it("replays approve with label or base, and approve: false with mode", async () => {
+      for (const options of [
+        { approve: true, label: "x" },
+        { approve: true, base: "start" },
+        { approve: false, mode: "review" },
+        { approve: true, mode: undefined },
+      ]) {
+        expect((await outcomeOf(options)).kind).toBe("rest")
+      }
+    })
+  })
+
+  it("does not demand Gtd-Approved at a plain human step", async () => {
+    const h = new History().land("human", "plain", 1, "after")
+    const outcome = await replayOf(async () => {
+      await human("plain")
+      await human("after")
+    }, h)
+    expect(outcome.kind).toBe("rest")
+  })
+})

package/src/replay/Replay.ts

@@ -236,7 +236,7 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 // 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"]),
-  human: new Set([...STEERING_OPTIONS, "message", "acceptClean"]),
+  human: new Set([...STEERING_OPTIONS, "message", "acceptClean", "approve"]),
   run: new Set(STEERING_OPTIONS),
   judge: new Set([...STEERING_OPTIONS, "message"]),
 }
@@ -249,6 +249,14 @@ const unknownOptions = (step: ReachedStep): string | undefined => {
   return `gtd: step "${step.name}": unknown key(s) ${unknown.join(", ")} in ${step.kind}() options`
 }
 
+const approveConflict = (step: ReachedStep): string | undefined => {
+  const request = step.request
+  if (request.kind !== "human" || request.options.approve !== true) return undefined
+  const keys = (["mode", "file"] as const).filter((key) => request.options[key] !== undefined)
+  if (keys.length === 0) return undefined
+  return `gtd: step "${step.name}": approve cannot be combined with ${keys.join(", ")} in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing`
+}
+
 export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   const commits: readonly ParsedCommit[] = input.episode.commits.map((c) => ({
     ...c,
@@ -485,10 +493,20 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         message: `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}" — ${DIVERGED}`,
       }
     }
-    const error = unknownOptions(step) ?? checkIdentity(step)
+    const error = unknownOptions(step) ?? approveConflict(step) ?? checkIdentity(step)
     return error === undefined ? undefined : { kind: "failed", message: error }
   }
 
+  const missingApproval = (step: ReachedStep, commit: ParsedCommit, expected: string) => {
+    if (step.request.kind !== "human" || step.request.options.approve !== true) return undefined
+    const approved = commit.parsed.approved
+    if (approved !== undefined && formatStepId(approved.step) === expected) return undefined
+    return {
+      kind: "divergence" as const,
+      message: `gtd: commit ${short(commit.hash)} completes approval gate "${expected}" but records no Gtd-Approved for it — ${DIVERGED}`,
+    }
+  }
+
   const consumeCommit = (step: ReachedStep, commit: ParsedCommit): unknown => {
     const recorded = commit.parsed.step
     const expected = formatStepId(step.id)
@@ -500,6 +518,8 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         message: `gtd: commit ${short(commit.hash)} ${what}, but replay expected "${expected}" — ${DIVERGED}`,
       })
     }
+    const unapproved = missingApproval(step, commit, expected)
+    if (unapproved !== undefined) return finish(unapproved)
     cursor++
     advance(commit)
     if (commit.parsed.kept !== undefined) {

package/src/replay/Trailers.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest"
-import { formatCommitMessage, parseCommitMessage, parseSubject } from "./Trailers.js"
+import {
+  formatCommitMessage,
+  isRecordableApproval,
+  parseCommitMessage,
+  parseSubject,
+} from "./Trailers.js"
 
 describe("the commit-message codec", () => {
   it("round-trips a step commit's subject and trailers", () => {
@@ -173,3 +178,107 @@ describe("Gtd-Kept", () => {
     expect(parsed.format).toBe(1)
   })
 })
+
+describe("Gtd-Approved", () => {
+  const approved = {
+    step: { name: "seam", occurrence: 2 },
+    name: "Ada Lovelace",
+    email: "ada@x.io",
+  }
+  const line = (value: string) => `gtd(human): a → b\n\nGtd-Approved: ${value}`
+
+  it("is written as one JSON line between Gtd-Judge and Gtd-Branch and round-trips", () => {
+    const message = formatCommitMessage({
+      actor: "human",
+      to: "next",
+      from: "seam",
+      step: { name: "seam", occurrence: 2 },
+      judge: [{ id: "v", answer: "yes", p: 1 }],
+      branch: "feat",
+      approved,
+    })
+    const lines = message.split("\n")
+    const at = lines.indexOf(
+      'Gtd-Approved: {"step":"seam#2","name":"Ada Lovelace","email":"ada@x.io"}',
+    )
+    expect(at).toBeGreaterThan(-1)
+    expect(lines[at - 1]).toMatch(/^Gtd-Judge:/)
+    expect(lines[at + 1]).toBe("Gtd-Branch: feat")
+    expect(parseCommitMessage(message).approved).toEqual(approved)
+  })
+
+  it.each([
+    ["a plain step", "seam"],
+    ["a step with a space and hash", "phase#1 review"],
+    ["a step with angle brackets", "a <b> c"],
+    ["a scoped step", "pkg.seam"],
+    ["a quote/backslash approver name", "seam", 'Ada "A" \\ L'],
+  ])("round-trips %s", (_label, stepName, approver = "Ada") => {
+    const a = { step: { name: stepName, occurrence: 3 }, name: approver, email: "a@x.io" }
+    expect(
+      parseCommitMessage(formatCommitMessage({ actor: "human", to: "b", approved: a })).approved,
+    ).toEqual(a)
+  })
+
+  it("reads undefined for the old shape, non-objects and bad fields", () => {
+    for (const value of [
+      "seam#1 Ada <a@x.io>",
+      "",
+      "[]",
+      '"x"',
+      "null",
+      '{"step":"seam#1","name":"Ada"}',
+      '{"step":"seam#1","name":"Ada","email":1}',
+      '{"step":"seam","name":"Ada","email":"a@x.io"}',
+      '{"step":"seam#0","name":"Ada","email":"a@x.io"}',
+    ]) {
+      expect(parseCommitMessage(line(value)).approved).toBe(undefined)
+    }
+  })
+
+  it("reads undefined for a control character in any field", () => {
+    for (const json of [
+      '{"step":"se\\u001bam#1","name":"Ada","email":"a@x.io"}',
+      '{"step":"seam#1","name":"Ada\\u0007","email":"a@x.io"}',
+      '{"step":"seam#1","name":"Ada","email":"a\\u0085@x.io"}',
+    ]) {
+      expect(parseCommitMessage(line(json)).approved).toBe(undefined)
+    }
+  })
+
+  it("reads undefined when absent", () => {
+    expect(parseCommitMessage(formatCommitMessage({ actor: "agent", to: "b" })).approved).toBe(
+      undefined,
+    )
+  })
+})
+
+describe("isRecordableApproval", () => {
+  const of = (name: string, email: string, occurrence = 1) => ({
+    step: { name: "gate", occurrence },
+    name,
+    email,
+  })
+
+  it("accepts ordinary, quoted, backslashed and angle-bracketed identities", () => {
+    for (const name of ["Ada", 'A "B"', "A\\B", "A <B>"]) {
+      expect(isRecordableApproval(of(name, "a@x.io"))).toBe(true)
+    }
+    expect(isRecordableApproval(of("Ada", "a<b>@x.io"))).toBe(true)
+  })
+
+  it("refuses a C1 control character in name or email", () => {
+    expect(isRecordableApproval(of("Ada\u0085", "a@x.io"))).toBe(false)
+    expect(isRecordableApproval(of("Ada", "a\u0085@x.io"))).toBe(false)
+  })
+
+  it("refuses a JS line terminator that would split the trailer on read", () => {
+    const name = "x\u2028Gtd-Branch: forged\u2028"
+    expect(isRecordableApproval(of(name, "a@x.io"))).toBe(false)
+    expect(isRecordableApproval(of("Ada", "a\u2029@x.io"))).toBe(false)
+  })
+
+  it("refuses an occurrence that does not read back", () => {
+    expect(isRecordableApproval(of("Ada", "a@x.io", 0))).toBe(false)
+  })
+})

package/src/replay/Trailers.ts

@@ -60,6 +60,12 @@ export interface CostEntry {
   readonly model: string | undefined
 }
 
+export interface Approval {
+  readonly step: StepId
+  readonly name: string
+  readonly email: string
+}
+
 export interface CommitMessage {
   readonly subject: string
   readonly parsed: ParsedSubject | undefined
@@ -77,6 +83,8 @@ export interface CommitMessage {
   readonly version: string | undefined
   /** The off-branch tip a keep step set aside; a non-hash value is skipped. */
   readonly kept: string | undefined
+  /** `Gtd-Approved`; a malformed or control-character value is skipped. */
+  readonly approved: Approval | undefined
   readonly format: number
 }
 
@@ -106,7 +114,7 @@ const CONFIG_RE = /^([0-9a-f]{16}) (.+)$/
 // JSON string. A control character is refused on read: history written by
 // someone else must never put escape sequences on a terminal.
 // eslint-disable-next-line no-control-regex -- the control range IS the point
-const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f]/
+const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/
 const encodePath = (path: string): string =>
   path.trim() !== path || path.startsWith('"') || CONTROL_CHARACTER.test(path)
     ? JSON.stringify(path)
@@ -115,6 +123,24 @@ const decodePath = (raw: string): string | undefined => {
   const path = raw.startsWith('"') ? parseJson(raw) : raw
   return typeof path === "string" && path !== "" && !CONTROL_CHARACTER.test(path) ? path : undefined
 }
+const decodeApproval = (raw: string): Approval | undefined => {
+  const parsed = parseJson(raw)
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
+  const { step, name, email } = parsed as Record<string, unknown>
+  if (typeof step !== "string" || typeof name !== "string" || typeof email !== "string")
+    return undefined
+  if ([step, name, email].some((field) => CONTROL_CHARACTER.test(field))) return undefined
+  const id = parseStepId(step)
+  return id === undefined ? undefined : { step: id, name, email }
+}
+const encodeApproval = ({ step, name, email }: Approval): string =>
+  JSON.stringify({ step: formatStepId(step), name, email })
+// The land-time refusal relies on this: an approval that would not read back
+// unchanged must never be written.
+export const isRecordableApproval = (approval: Approval): boolean => {
+  const back = decodeApproval(encodeApproval(approval))
+  return back !== undefined && encodeApproval(back) === encodeApproval(approval)
+}
 const FORMAT_RE = /^[1-9][0-9]*$/
 const HASH_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
 
@@ -125,6 +151,7 @@ interface Trailers {
   branch: string | undefined
   version: string | undefined
   kept: string | undefined
+  approved: Approval | undefined
   readonly judge: JudgeVerdict[]
   readonly vars: Record<string, string>
   readonly config: Record<string, string>
@@ -164,6 +191,9 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Kept": (value, into) => {
     if (HASH_RE.test(value)) into.kept ??= value
   },
+  "Gtd-Approved": (value, into) => {
+    into.approved ??= decodeApproval(value)
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -183,6 +213,7 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     branch: undefined,
     version: undefined,
     kept: undefined,
+    approved: undefined,
     judge: [],
     vars: {},
     config: {},
@@ -208,6 +239,8 @@ export interface CommitSpec {
   readonly config?: Readonly<Record<string, string>>
   readonly cost?: { readonly cost: number; readonly model?: string }
   readonly judge?: readonly JudgeVerdict[]
+  /** Written after `Gtd-Judge`, before `Gtd-Branch`. */
+  readonly approved?: Approval
   readonly branch?: string
   readonly version?: string
 }
@@ -230,6 +263,9 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     )
   }
   for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`)
+  if (spec.approved !== undefined) {
+    lines.push(`Gtd-Approved: ${encodeApproval(spec.approved)}`)
+  }
   if (spec.branch !== undefined) lines.push(`Gtd-Branch: ${spec.branch}`)
   if (spec.version !== undefined) lines.push(`Gtd-Version: ${spec.version}`)
   lines.push(`Gtd-Format: ${HISTORY_FORMAT}`)

package/src/replay/index.ts

@@ -2,7 +2,9 @@ export { replay, type EpisodeCommit, type ReachedStep, type ReplayOutcome } from
 export { treeFromRecord, type TreeView } from "./Tree.js"
 export {
   formatCommitMessage,
+  formatStepId,
   formatSubject,
+  isRecordableApproval,
   parseCommitMessage,
   type CommitSpec,
   type JudgeVerdict,