@pmelab/gtd 64.3.0 → 66.0.0

package/src/emit/GitScript.ts

@@ -12,8 +12,11 @@ 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, only?: string): string => {
-  const m = shellQuote(message)
+const commitAllowEmpty = (message: string, only?: string): string =>
+  commitWordAllowEmpty(shellQuote(message), only)
+
+/** `commitAllowEmpty` over a message that is already a shell word. */
+const commitWordAllowEmpty = (m: string, only?: string): string => {
   const paths = only === undefined ? "" : ` -- ${shellQuote(only)}`
   return [
     `if ! out=$(git commit --allow-empty -m ${m}${paths} 2>&1); then`,
@@ -36,6 +39,29 @@ export const commitAll = (message: string): string =>
 export const commitPath = (path: string, message: string): string =>
   `git add -A -- ${shellQuote(path)} || exit 1\n${commitAllowEmpty(message, path)}`
 
+/**
+ * A `run()` body that records its own failure instead of failing the beat: the
+ * status and the last 50 output lines go to `path`, and the script exits zero
+ * so the turn lands. The file is COMMITTED (and force-pushed with a history
+ * remote), hence the cap.
+ */
+export const failRestScript = (body: string, path: string): string => {
+  const p = shellQuote(path)
+  const slash = path.lastIndexOf("/")
+  return [
+    `rm -f -- ${p}`,
+    `gtd_run_status=0`,
+    `gtd_run_out="$( {`,
+    body,
+    `} 2>&1 )" || gtd_run_status=$?`,
+    `printf '%s\\n' "$gtd_run_out"`,
+    `if [ "$gtd_run_status" -ne 0 ]; then`,
+    `  mkdir -p ${shellQuote(path.slice(0, slash))}`,
+    `  printf 'exit %s\\n%s\\n' "$gtd_run_status" "$(printf '%s\\n' "$gtd_run_out" | tail -n 50)" >${p}`,
+    `fi`,
+  ].join("\n")
+}
+
 /** 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)
@@ -123,6 +149,77 @@ export const keepTurn = (refPrefix: string, message: string): string => {
   ].join("\n")
 }
 
+/** `git switch -C <branch> [<start>]`: create or reset the branch, carrying pending changes over. */
+export const switchBranchTo = (branch: string, start?: string): string =>
+  `git switch -q -C ${shellQuote(branch)}${start === undefined ? "" : ` ${shellQuote(start)}`}`
+
+/** `git switch <branch>`: an existing branch, carrying pending changes over. */
+export const switchTo = (branch: string): string => `git switch -q ${shellQuote(branch)}`
+
+/** `switchTo` that, when pending changes block it, stays put and says so: the landing already happened. */
+export const switchBack = (branch: string): string =>
+  [
+    `if ! git switch -q ${shellQuote(branch)} 2>/dev/null; then`,
+    `  printf '%s\\n' ${shellQuote(`gtd: pending changes keep HEAD off ${branch}; switch to it once they are committed or stashed`)}`,
+    `fi`,
+  ].join("\n")
+
+export const deleteBranch = (branch: string): string => `git branch -q -D ${shellQuote(branch)}`
+
+/**
+ * Force-pushes one ref to a remote. A failed push exits non-zero with the retry
+ * on stderr: it runs after the closing commit has landed, so the commit stands.
+ */
+export const pushRef = (remote: string, ref: string): string => {
+  const retry = `git push --force ${shellQuote(remote)} ${shellQuote(`${ref}:${ref}`)}`
+  return [
+    `if ! ${retry}; then`,
+    `  printf '%s\\n' ${shellQuote(`gtd: pushing ${ref} failed — retry: ${retry}`)} >&2`,
+    `  exit 1`,
+    `fi`,
+  ].join("\n")
+}
+
+/**
+ * A ship step's landing, in one block because the landing commit's
+ * `Gtd-Shipped` trailer names the squash it makes first. The squash carries
+ * the staged tree with `.gtd/` as `<branch>` has it, built in a scratch index; `<branch>` moves by
+ * compare-and-swap against `parent`, so a branch moved since the decision
+ * fails the script before the landing commits. `commit-tree` ignores
+ * `commit.gpgSign`, so it is read here.
+ */
+export const shipCommit = (
+  branch: string,
+  parent: string,
+  shipMessage: string,
+  historyRef: string,
+  message: string,
+): string =>
+  [
+    `gtd_ship_parent=${shellQuote(parent)}`,
+    `gtd_ship_branch=${shellQuote(branch)}`,
+    `gtd_ship_history=${shellQuote(historyRef)}`,
+    `gtd_ship_message=${shellQuote(shipMessage)}`,
+    `gtd_land_message=${shellQuote(message)}`,
+    `git add -A || exit 1`,
+    `gtd_sign_cfg=$(git config --type=bool --default=false commit.gpgSign) || exit 1`,
+    `if [ "$gtd_sign_cfg" = true ]; then gtd_sign=-S; else gtd_sign=--no-gpg-sign; fi`,
+    `gtd_head=$(git rev-parse --verify HEAD) || exit 1`,
+    `gtd_tree=$(git write-tree) || exit 1`,
+    `gtd_index=$(git rev-parse --git-path gtd-ship-index) || exit 1`,
+    `rm -f -- "$gtd_index"`,
+    `GIT_INDEX_FILE="$gtd_index" git read-tree "$gtd_tree" || exit 1`,
+    `GIT_INDEX_FILE="$gtd_index" git rm -r -q --cached --ignore-unmatch -- .gtd || exit 1`,
+    `git ls-tree -r "$gtd_ship_parent" -- .gtd | GIT_INDEX_FILE="$gtd_index" git update-index --index-info || exit 1`,
+    `gtd_ship_tree=$(GIT_INDEX_FILE="$gtd_index" git write-tree) || exit 1`,
+    `rm -f -- "$gtd_index"`,
+    `gtd_ship_trailers=$(printf "Gtd-History: %s\\nGtd-Tip: %s" "$gtd_ship_history" "$gtd_head")`,
+    `gtd_shipped=$(git commit-tree "$gtd_sign" "$gtd_ship_tree" -p "$gtd_ship_parent" -m "$gtd_ship_message" -m "$gtd_ship_trailers") || exit 1`,
+    `git update-ref -m "gtd: ship" "refs/heads/$gtd_ship_branch" "$gtd_shipped" "$gtd_ship_parent" || exit 1`,
+    `gtd_message=$(printf "%s\\nGtd-Shipped: %s" "$gtd_land_message" "$gtd_shipped")`,
+    commitWordAllowEmpty(`"$gtd_message"`),
+  ].join("\n")
+
 export const updateRef = (ref: string, hash: string): string =>
   `git update-ref ${shellQuote(ref)} ${shellQuote(hash)}`
 
@@ -170,21 +267,25 @@ const renderOutcome = (outcome: Outcome): string => {
   }
 }
 
-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":
-      return updateRef(write.ref, write.target)
-    case "keepTurn":
-      return keepTurn(write.ref, write.message)
-  }
+type Renderers = {
+  readonly [K in GitWrite["kind"]]: (write: Extract<GitWrite, { kind: K }>) => string
+}
+
+const GIT_WRITES: Renderers = {
+  commitAll: (w) => commitAll(w.message),
+  commitPath: (w) => commitPath(w.path, w.message),
+  commitClean: (w) => commitClean(w.message),
+  updateRef: (w) => updateRef(w.ref, w.target),
+  keepTurn: (w) => keepTurn(w.ref, w.message),
+  switchBranch: (w) => switchBranchTo(w.branch),
+  switchTo: (w) => switchBack(w.branch),
+  pushRef: (w) => pushRef(w.remote, w.ref),
+  ship: (w) => shipCommit(w.branch, w.parent, w.shipMessage, w.historyRef, w.message),
 }
 
+const renderGitWrite = (write: GitWrite): string =>
+  (GIT_WRITES[write.kind] as (write: GitWrite) => string)(write)
+
 /**
  * Wraps `command` so a non-zero exit prints `prompt` plus the command's
  * captured output before propagating that exit code — mirrors `Emit.ts`'s

package/src/emit/index.ts

@@ -18,6 +18,7 @@ export {
   commitClean,
   commitPath,
   pinScript,
+  failRestScript,
   repinScript,
   unpinScript,
   CHANGED_SINCE_LAND,
@@ -28,6 +29,12 @@ export {
   updateRef,
   keepTurn,
   deleteRef,
+  switchBranchTo,
+  switchBack,
+  switchTo,
+  deleteBranch,
+  pushRef,
+  shipCommit,
   fetchHistoryRefs,
   type RunnableScript,
   ScriptSurface,

package/src/flows/config.ts

@@ -21,6 +21,8 @@ export interface GtdConfig {
   readonly ui?: UiSettings
   readonly skills?: Readonly<Record<string, readonly string[]>>
   readonly access?: Readonly<Record<string, ScopeAccess>>
+  /** A remote name: every finished or abandoned process force-pushes its history ref there. */
+  readonly historyRemote?: string
 }
 
 export interface ConfigProblem {
@@ -28,7 +30,7 @@ export interface ConfigProblem {
   readonly message: string
 }
 
-const CONFIG_KEYS = ["modes", "ui", "skills", "access"] as const
+const CONFIG_KEYS = ["modes", "ui", "skills", "access", "historyRemote"] as const
 const MODE_KEYS = ["format", "validate"] as const
 const UI_KEYS = ["port", "host", "cert", "key", "format"] as const
 
@@ -113,6 +115,10 @@ export const configProblems = (value: unknown): readonly ConfigProblem[] => {
     ...unknownKeys(value, CONFIG_KEYS, []),
     ...(value.modes === undefined ? [] : recordOf(value.modes, ["modes"], "modes", modeProblems)),
     ...(value.ui === undefined ? [] : uiProblems(value.ui, ["ui"])),
+    ...(value.historyRemote === undefined ||
+    (typeof value.historyRemote === "string" && value.historyRemote.trim() !== "")
+      ? []
+      : [{ path: ["historyRemote"], message: "must be a non-empty remote name" }]),
     ...(value.skills === undefined
       ? []
       : recordOf(value.skills, ["skills"], "skill-name arrays", (v, path) =>

package/src/flows/helpers.ts

@@ -12,6 +12,7 @@ import {
   settings,
   threads,
   type Change,
+  type Changes,
   type JudgeAnswer,
   type Judgment,
 } from "./runtime.js"
@@ -78,15 +79,19 @@ const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".
 /** The last step's changes outside `.gtd/`. */
 export const codeChanges = (): readonly Change[] => changes().filter((c) => isCode(c.path))
 
+/** Validator form of `requireProgress`: the agent-addressed error, or `undefined` when the turn is valid. */
+export const progressErrors = (file: string, turnChanges: Changes): string | undefined => {
+  const change = turnChanges.get(file)
+  if (change?.status !== "deleted") return undefined
+  if (turnChanges.some((c) => isCode(c.path))) return undefined
+  if ((change.before ?? "").trim().startsWith("NOTHING ACTIONABLE")) return undefined
+  return `${file} was deleted without addressing its instructions — implement the changes it lists (then delete it), don't just remove the file. Its content was:\n${change.before ?? ""}`
+}
+
 /** Refuse a turn whose only change deletes `file` — unless it says it found nothing to do. */
 export const requireProgress = (file: string): void => {
-  const change = changes().get(file)
-  if (change?.status !== "deleted") return
-  if (codeChanges().length > 0) return
-  if ((change.before ?? "").trim().startsWith("NOTHING ACTIONABLE")) return
-  refuse(
-    `gtd land: feedback-progress: ${file} was deleted without addressing its instructions — implement the changes it lists (then delete it), don't just remove the file.`,
-  )
+  const error = progressErrors(file, changes())
+  if (error !== undefined) refuse(`gtd land: feedback-progress: ${error}`)
 }
 
 /** Refuse a turn that leaves a question in `file` unanswered. An untouched tree is silence, and allowed. */
@@ -135,23 +140,36 @@ export const requireThreadsClosed = (file: string): void => {
   )
 }
 
+/** Validator form of `requireReplies`: the agent-addressed error, or `undefined` when every thread is answered. */
+export const repliesErrors = (file: string): string | undefined => {
+  const open = [...threadLines(file, "agent"), ...codeThreadLines("agent")]
+  if (open.length === 0) return undefined
+  return `${countOf(open)} thread(s) in ${file} or code comments still wait on the agent — append one "- A:" reply to each (one "A:" comment line, same token and indentation, directly below a code thread's last line), or fold a concluded thread and delete it:\n${open.join("\n")}`
+}
+
 /** Refuse an agent turn that leaves a thread in `file`, or a code thread in a changed file, waiting on the agent (its last entry is `H:`) or with a syntax fault. */
 export const requireReplies = (file: string): void => {
-  const open = [...threadLines(file, "agent"), ...codeThreadLines("agent")]
-  if (open.length === 0) return
-  refuse(
-    `gtd land: unanswered-threads: ${countOf(open)} thread(s) in ${file} or code comments still wait on the agent — append one "- A:" reply to each (one "A:" comment line, same token and indentation, directly below a code thread's last line), or fold a concluded thread and delete it:\n${open.join("\n")}`,
-  )
+  const error = repliesErrors(file)
+  if (error !== undefined) refuse(`gtd land: unanswered-threads: ${error}`)
 }
 
-/** Refuse a turn that did not undo the code edits `edited` recorded, back to their content before `base`. */
-export const requireRevert = (edited: readonly Change[], base: string): void => {
+const revertFix = (edited: readonly Change[], base: string): string | undefined => {
   const residue = edited.filter((c) => read(c.path) !== c.before).map((c) => c.path)
-  if (residue.length === 0) return
+  if (residue.length === 0) return undefined
   const quoted = residue.map((path) => `'${path.replace(/'/g, "'\\''")}'`).join(" ")
-  refuse(
-    `gtd land: require-revert: ${residue.join(", ")} still differ from ${base}~1 — the revert did not take. Run \`git checkout ${base}~1 -- ${quoted}\`, then \`gtd land\` again.`,
-  )
+  return `${residue.join(", ")} still differ from ${base}~1 — the revert did not take. Run \`git checkout ${base}~1 -- ${quoted}\``
+}
+
+/** Validator form of `requireRevert`: reads the tree, not the turn's changes. */
+export const revertErrors = (edited: readonly Change[], base: string): string | undefined => {
+  const fix = revertFix(edited, base)
+  return fix === undefined ? undefined : `${fix}.`
+}
+
+/** Refuse a turn that did not undo the code edits `edited` recorded, back to their content before `base`. */
+export const requireRevert = (edited: readonly Change[], base: string): void => {
+  const fix = revertFix(edited, base)
+  if (fix !== undefined) refuse(`gtd land: require-revert: ${fix}, then \`gtd land\` again.`)
 }
 
 const SHAPES = ["land", "refactor-first", "reject"] as const

package/src/flows/index.test.ts

@@ -34,10 +34,12 @@ describe("@pmelab/gtd/flows", () => {
         "moveScript",
         "numeric",
         "openQuestions",
+        "progressErrors",
         "quote",
         "read",
         "refuse",
         "removeScript",
+        "repliesErrors",
         "requireAnswers",
         "requireProgress",
         "requireReplies",
@@ -45,6 +47,7 @@ describe("@pmelab/gtd/flows", () => {
         "requireThreadsClosed",
         "restart",
         "restoreScript",
+        "revertErrors",
         "revertScript",
         "run",
         "scope",
@@ -53,6 +56,7 @@ describe("@pmelab/gtd/flows", () => {
         "sections",
         "settings",
         "settingsOf",
+        "ship",
         "showScript",
         "skillsFor",
         "start",

package/src/flows/index.ts

@@ -28,6 +28,7 @@ export {
   sections,
   settings,
   settingsOf,
+  ship,
   skillsFor,
   start,
   threads,
@@ -47,6 +48,8 @@ export {
   type JudgeQuestion,
   type JudgeQuestionInput,
   type JudgeSpec,
+  type ValidateResult,
+  type ValidateTurn,
   type Judgment,
   type KeptTip,
   type Mark,
@@ -58,6 +61,7 @@ export {
   type ScopeOptions,
   type Section,
   type Settings,
+  type ShipOptions,
   type SkillsExport,
   type Steering,
   type SteeringOptions,
@@ -76,11 +80,14 @@ export {
   hasThreadFor,
   judgeDiffShape,
   numeric,
+  progressErrors,
+  repliesErrors,
   requireAnswers,
   requireProgress,
   requireReplies,
   requireRevert,
   requireThreadsClosed,
+  revertErrors,
   seamGate,
   wrote,
   type Check,

package/src/flows/runtime.ts

@@ -37,9 +37,25 @@ type SteeringFile =
 /** A steering-file declaration shared by the steps that rest on one. `mode` requires `file`. */
 export type SteeringOptions = SteeringCommon & SteeringFile
 
+/** What a validator is told about the work so far. */
+export interface ValidateTurn {
+  /** Every change since before the first try, minus the files the validator's own steps wrote. */
+  readonly changes: Changes
+}
+
+export type ValidateResult = string | readonly string[] | undefined
+
 interface AgentCommon {
   readonly model?: string | undefined
   readonly system?: string | undefined
+  /** Runs after each landed turn; errors it returns become the correction the next try gets. Only `check`, `run` and `judge` may run inside. */
+  readonly validate?: ((turn: ValidateTurn) => Promise<ValidateResult>) | undefined
+  /** Retries before `exhausted` runs. Default 3. */
+  readonly cap?: number | undefined
+  /** Runs once `cap` retries failed; default rests at a `<name>.invalid` gate. The validator then runs again. */
+  readonly exhausted?: ((errors: readonly string[]) => Promise<void>) | undefined
+  /** The retry's `content`, instead of the default lead-in plus the errors. */
+  readonly correction?: ((errors: readonly string[]) => string) | undefined
 }
 
 export type AgentOptions = SteeringOptions &
@@ -89,7 +105,20 @@ export type HumanOptions = HumanCommon &
       })
   )
 
-export type RunOptions = SteeringOptions
+export type RunOptions = SteeringOptions & {
+  /**
+   * `"rest"`: a non-zero exit is recorded in the tree and the process rests at
+   * the step as `stalled`; any tree change runs the script again, and only a
+   * zero exit advances. Without it a failing body lands and the flow carries on.
+   */
+  readonly onFail?: "rest" | undefined
+}
+
+/** A ship step rests on no steering file. */
+export type ShipOptions = SteeringCommon & {
+  readonly file?: undefined
+  readonly mode?: undefined
+}
 
 export type JudgePrimitive = "noul" | "choice" | "score"
 
@@ -196,6 +225,8 @@ export type StepRequest =
       readonly name: string
       readonly prompt: string
       readonly options: AgentOptions
+      /** On a validator retry: the step's original prompt (`prompt` is then the correction). */
+      readonly original?: string
     }
   | { readonly kind: "human"; readonly name: string; readonly options: HumanOptions }
   | {
@@ -204,6 +235,12 @@ export type StepRequest =
       readonly body: string
       readonly options: RunOptions
     }
+  | {
+      readonly kind: "ship"
+      readonly name: string
+      readonly message: string
+      readonly options: ShipOptions
+    }
   | {
       readonly kind: "judge"
       readonly name: string
@@ -312,9 +349,84 @@ const ctx = (): FlowContext => {
 
 // ── Steps ───────────────────────────────────────────────────────────────────
 
+// While a validator runs: its step's name, and the paths its own steps changed. Keyed by the
+// replay's context: a validator suspended at a rest never unwinds, so a global would leak.
+type Validating = { readonly name: string; readonly paths: Set<string> }
+const validatingBy = new WeakMap<FlowContext, Validating>()
+
+const DEFAULT_CAP = 3
+
+const noValidatorStep = (kind: string, name: string): void => {
+  const validating = validatingBy.get(ctx())
+  if (validating !== undefined) {
+    throw new Error(
+      `gtd: step "${name}": ${kind}() cannot run inside the validator of "${validating.name}" — a validator may only run check, run and judge steps`,
+    )
+  }
+}
+
+const noteValidatorPaths = (): void => {
+  const validating = validatingBy.get(ctx())
+  if (validating !== undefined) for (const c of ctx().changes()) validating.paths.add(c.path)
+}
+
+const errorList = (result: ValidateResult): readonly string[] =>
+  result === undefined ? [] : typeof result === "string" ? [result] : result
+
 /** An agent turn: `prompt` is emitted, the driver lands the diff. */
-export const agent = (name: string, prompt: string, options: AgentOptions = {}): Promise<void> =>
-  ctx().step({ kind: "agent", name, prompt, options }) as Promise<void>
+export const agent = async (
+  name: string,
+  prompt: string,
+  options: AgentOptions = {},
+): Promise<void> => {
+  noValidatorStep("agent", name)
+  const context = ctx()
+  const { validate, cap = DEFAULT_CAP, exhausted, correction } = options
+  const base = typeof validate === "function" ? context.head() : ""
+  await context.step({ kind: "agent", name, prompt, options })
+  if (typeof validate !== "function") return
+
+  const own = new Set<string>()
+  // Paths an agent turn or a person changed. Whatever changed since the last validator returned
+  // is theirs — even on a path a validator `run` (lint --fix) wrote in an earlier round.
+  const agentPaths = new Set<string>()
+  let validated = base
+  const validateNow = async (): Promise<readonly string[]> => {
+    for (const c of context.changesSince(validated)) agentPaths.add(c.path)
+    const turn: ValidateTurn = {
+      get changes() {
+        return toChanges(
+          context.changesSince(base).filter((c) => !own.has(c.path) || agentPaths.has(c.path)),
+        )
+      },
+    }
+    validatingBy.set(context, { name, paths: own })
+    try {
+      return errorList(await scope(`${name}.validate`, () => validate(turn)))
+    } finally {
+      validatingBy.delete(context)
+      validated = context.head()
+    }
+  }
+
+  let errors = await validateNow()
+  let retries = 0
+  while (errors.length > 0) {
+    if (retries >= cap) {
+      if (exhausted !== undefined) await exhausted(errors)
+      else await human(`${name}.invalid`, errors.join("\n"), { acceptClean: true })
+      retries = 0
+    } else {
+      retries++
+      const text =
+        correction !== undefined
+          ? correction(errors)
+          : `The result did not pass validation. Fix these errors:\n\n${errors.join("\n")}\n`
+      await context.step({ kind: "agent", name, prompt: text, options, original: prompt })
+    }
+    errors = await validateNow()
+  }
+}
 
 // `Omit` over a union collapses it; this keeps each member's own rules.
 type OmitEach<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
@@ -330,8 +442,9 @@ export const human: Human = (
   name: string,
   messageOrOptions?: string | HumanOptions,
   options?: OmitEach<HumanOptions, "message">,
-): Promise<void> =>
-  ctx().step({
+): Promise<void> => {
+  noValidatorStep("human", name)
+  return ctx().step({
     kind: "human",
     name,
     options:
@@ -339,10 +452,27 @@ export const human: Human = (
         ? { ...options, message: messageOrOptions }
         : (messageOrOptions ?? {}),
   }) as Promise<void>
+}
 
 /** A check: `body` runs at the edge and its effect on the tree is committed. */
-export const run = (name: string, body: string, options: RunOptions = {}): Promise<void> =>
-  ctx().step({ kind: "run", name, body, options }) as Promise<void>
+export const run = async (name: string, body: string, options: RunOptions = {}): Promise<void> => {
+  await ctx().step({ kind: "run", name, body, options })
+  noteValidatorPaths()
+}
+
+/**
+ * Squashes HEAD's tree, with `.gtd/` as the user's branch has it, into one commit on the user's branch
+ * with `message`, and moves that branch there; HEAD stays on `gtd/<b>`.
+ * Resolves to the new commit's hash, or `undefined` when nothing shipped.
+ */
+export const ship = (
+  name: string,
+  message: string,
+  options: ShipOptions = {},
+): Promise<string | undefined> => {
+  noValidatorStep("ship", name)
+  return ctx().step({ kind: "ship", name, message, options }) as Promise<string | undefined>
+}
 
 /** A judge gate: resolves to what the judge answered, for the flow to decide on. */
 export const judge = <const Q extends readonly JudgeQuestionInput[] = readonly JudgeQuestion[]>(
@@ -354,17 +484,25 @@ export const judge = <const Q extends readonly JudgeQuestionInput[] = readonly J
   const canonical = questions.map((q) =>
     q.primitive === "yesno" ? { ...q, primitive: "noul" as const } : (q as JudgeQuestion),
   )
-  return ctx().step({
-    kind: "judge",
-    name,
-    questions: canonical,
-    evidence,
-    options,
-  }) as Promise<Judgment<Q[number]["id"]>>
+  return ctx()
+    .step({
+      kind: "judge",
+      name,
+      questions: canonical,
+      evidence,
+      options,
+    })
+    .then((judgment) => {
+      noteValidatorPaths()
+      return judgment as Judgment<Q[number]["id"]>
+    })
 }
 
 /** End the episode from any depth. The next episode starts the flow afresh. */
-export const restart = (): Promise<never> => ctx().step({ kind: "restart" }) as Promise<never>
+export const restart = (): Promise<never> => {
+  noValidatorStep("restart", "restart")
+  return ctx().step({ kind: "restart" }) as Promise<never>
+}
 
 /** Refuse the pending turn: nothing lands, the process stays where it rests. */
 export const refuse = (message: string): never => ctx().refuse(message)

package/src/install/Install.ts

@@ -83,6 +83,7 @@ while :; do
       model="$(gtd next --json=model)"
       system="$(gtd next --json=system)"
       validate="$(gtd next --json=validate)"
+      fresh="$(gtd next --json=fresh)"
       log="$(gtd next --json=log)"
       # \`model\` is a hint, not a model name — gtd-workflows' default ships
       # \`smart\` and \`base\`, which \`claude --model\` rejects. Resolve them
@@ -125,8 +126,14 @@ while :; do
       then first=--resume second=--session-id
       else first=--session-id second=--resume
       fi
+      # A validator retry resumes with the correction alone; a session that
+      # cannot resume starts over with \`fresh\`, the original prompt plus it.
+      second_prompt="$log.prompt"
+      if [ "$second" = --session-id ] && [ -n "\${fresh:-}" ]
+      then printf '%s\\n' "$fresh" >"$log.fresh" && second_prompt="$log.fresh"
+      fi
       turn "$first" "$session_id" <"$log.prompt" ||
-        { [ "$ran" = false ] && turn "$second" "$session_id" <"$log.prompt"; } || {
+        { [ "$ran" = false ] && turn "$second" "$session_id" <"$second_prompt"; } || {
         echo "agent turn failed — see $log" >&2
         exit 1
       }
@@ -140,7 +147,7 @@ while :; do
           exit 1
         }
       done
-      rm -f "$log.prompt" ;;
+      rm -f "$log.prompt" "$log.fresh" ;;
   esac
 
   # Read every value the landing needs BEFORE piping the script to \`sh\`:

package/src/platform/Git.test.ts

@@ -87,17 +87,13 @@ describe("diffPaths [Live]", () => {
   })
 
   // An exported GIT_DIR/GIT_WORK_TREE would send this test's commits to the real repo;
-  // the pinned config keeps a global commit.gpgsign or missing identity from failing them.
-  const cleanEnv = {
-    ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))),
-    GIT_CONFIG_COUNT: "3",
-    GIT_CONFIG_KEY_0: "commit.gpgsign",
-    GIT_CONFIG_VALUE_0: "false",
-    GIT_CONFIG_KEY_1: "user.email",
-    GIT_CONFIG_VALUE_1: "test@test.com",
-    GIT_CONFIG_KEY_2: "user.name",
-    GIT_CONFIG_VALUE_2: "Test",
-  }
+  // the suite's isolated global config keeps a developer's signing setup out.
+  const cleanEnv = Object.fromEntries(
+    Object.entries(process.env).filter(
+      ([key]) =>
+        !key.startsWith("GIT_") || key === "GIT_CONFIG_GLOBAL" || key === "GIT_CONFIG_NOSYSTEM",
+    ),
+  )
 
   it("reports a submodule pointer bump whatever diff.ignoreSubmodules and .gitmodules ignore say", async () => {
     const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-diffpaths-sm-")))

package/src/platform/NodeSync.ts

@@ -39,6 +39,8 @@ const infoOf = (stats: Stats): FileInfo => ({
         ? "file"
         : "other",
   uid: process.platform === "win32" ? undefined : stats.uid,
+  // git records 100755 from the owner execute bit alone.
+  ...(process.platform === "win32" ? {} : { executable: (stats.mode & 0o100) !== 0 }),
 })
 
 export const nodeSyncIo: SyncIo = {