@pmelab/gtd 26.0.0 → 27.0.0

package/dist/testkit.mjs

@@ -1,7 +1,7 @@
 import { checkScript, configProblems, configure, installContext, isFactoryWorkflow, moveScript, protocolMismatch, removeScript, restoreScript, revertScript, showScript, t as flows_exports } from "./flows.mjs";
-import { O as renderFormat, T as ACCESS_REFUSAL, _ as demandOf, a as landFields, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, i as judgeJson, l as renderLandPlain, m as statusOf, n as resolveSession, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches } from "./chunks/wire-DA7q2ikx.mjs";
+import { E as ACCESS_REFUSAL, _ as demandOf, a as landFields, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches } from "./chunks/wire-BY1S-obW.mjs";
 import { C as headingSections, S as headingSectionBodies, a as unansweredQuestions, b as parseThreadsWithFindings, n as openThreads, r as steeringFormatFor, s as parseCodeThreads, t as BUILT_IN_MODE_NAMES, w as formatFinding } from "./chunks/steering-DVILanVf.mjs";
-import { $ as makeSemaphore, $i as toJSON, $n as mapBoth, $r as none$1, $t as provideMerge$1, A as catchTag, Ai as getOption, An as scopeTag, Ar as interrupt$2, At as sync$2, B as flatten$4, Bi as isSome, Bn as make$16, Br as tap$1, Bt as unsafeMakeSemaphore$1, C as all$1, Ci as unsafeFromArray, Cn as isInterruptedOnly, Cr as exitFailCause, Ct as scope, D as async, Di as Tag, Dn as ensuring$3, Dr as fiberId, Dt as serviceOption, E as asVoid$1, Ei as GenericTag, En as squash, Er as exitZipRight, Et as scopedWith$1, F as exit, Fi as filter$1, Fn as sequential, Fr as onInterrupt, Ft as tryPromise, G as forkScoped, Gi as isLeft, Gn as Class, Gr as withFiberRuntime, Gt as zipRight$3, H as forEach$2, Hi as match$4, Hn as set$1, Hr as uninterruptibleMask$1, Ht as withFiberRuntime$1, I as fail$5, Ii as flatMap$5, In as bind, Ir as scopeClose, It as try_, J as interrupt$4, Ji as right, Jn as die, Jr as empty$6, Jt as TaggedError$1, K as gen, Ki as left, Kn as spanTag, Kr as zipRight$1, Kt as zipWith, L as failCause$4, Li as fromNullable, Ln as bindTo, Lr as succeed$4, Lt as uninterruptible$1, M as dieMessage, Mi as empty$5, Mn as inheritAll$1, Mr as interruptFiber, Mt as tapErrorCause, N as either, Ni as fromIterable, Nn as interruptAllAs$1, Nr as interruptible$1, Nt as timeout, O as catchAll$1, Oi as add, On as forEachConcurrentDiscard, Or as fiberRefLocally, Ot as succeed$6, P as ensuring$2, Pi as splitAt, Pn as join$3, Pr as map$3, Pt as tryMap, Q as logWarning, Qi as format, Qn as map$5, Qr as make$19, Qt as provide$1, R as fiberIdWith, Ri as getOrElse, Rn as sleep, Rr as suspend$4, Rt as uninterruptibleMask, S as addFinalizer$1, Si as toArray, Sn as isInterrupted, Sr as exitFail, St as sandbox, T as as, Ti as unsafeHead, Tn as reduceWithContext, Tr as exitVoid, Tt as scoped$4, U as forkDaemon, Ui as none, Un as update$1, Ur as void_$2, Ut as zip$1, V as fnUntraced, Vi as map$8, Vn as modify$1, Vr as uninterruptible, Vt as when, W as forkIn, Wi as some, Wn as TypeId$10, Wr as whenEffect, Wt as zipLeft, X as intoDeferred, Xi as BaseProto, Xn as failCause$3, Xr as combineAll, Xt as fromEffect$5, Y as interruptible, Yi as pipeArguments, Yn as fail$4, Yr as combine, Yt as tagged, Z as isEffect, Zi as NodeInspectSymbol, Zn as isFailure, Zr as ids, Zt as mergeAll$2, _ as decodeSync, _i as prepend, _n as failureOrCause, _r as deferredMake, _t as repeat, a as Literal, aa as constVoid, ai as decode, an as forkIn$1, ar as as$1, at as matchCauseEffect, b as acquireRelease, bi as take$2, bn as interruptors, br as deferredUnsafeMake, bt as runPromiseExit$1, c as String$, ca as pipe, ci as appendAll, cn as addFinalizer, cr as catchAll, ct as onError, d as Union, di as filter, dn as extend, dr as deferredComplete, dt as orElseSucceed, ea as equals, ei as get$4, en as scoped$3, er as match$3, et as map$4, f as between, fi as fromIterable$1, fn as fork, fr as deferredFail, ft as promise, gi as of, gn as fail$3, gr as deferredIsDone, gt as raceWith, hi as map$7, hn as die$1, hr as deferredInterruptWith, ht as race, i as Defect, ia as constUndefined, ii as size$2, in as updateContext$1, ir as zipRight$2, it as matchCause, j as die$2, ji as omit, jn as _await$2, jr as interruptAsFiber, jt as tap, k as catchAllCause, ki as get$5, kn as scopeMake, kr as flatMap$3, kt as suspend$5, l as Struct, li as drop, ln as addFinalizerExit, lr as currentContext$1, lt as orDie, m as optional$1, mi as isEmpty$2, mn as NoSuchElementException, mr as deferredInterrupt, mt as provideService, n as Boolean$, na as constFalse, ni as set$2, nn as unsafeFork, nr as void_$3, nt as mapError, o as Never, oa as dual, oi as isFinite, on as unsafeMakeSemaphore, or as asVoid, ot as matchEffect, p as decodeUnknown, pi as isChunk, pn as make$18, pr as deferredFailCause, pt as provide$2, q as ignore, qi as match$2, qn as all, qr as DeferredTypeId$1, qt as spaced$1, r as Cause, ra as constTrue, ri as has, rn as unsafeRunPromiseExit, rr as zip$2, rt as match$5, s as Number$, sa as identity, si as append$1, sn as Scope, sr as asyncInterrupt, st as negate, t as Array$, ta as hasProperty, ti as make$17, tn as succeed$3, tr as succeed$5, tt as mapBoth$1, u as TaggedError, ui as empty$4, un as close, ur as deferredAwait, ut as orElse, v as encodeSync, vi as reduce, vn as flipCauseOption, vr as deferredSucceed, vt as retry, w as annotateLogs, wi as unsafeGet, wn as map$6, wr as exitSucceed, wt as scopeWith, x as acquireUseRelease$2, xi as takeRight, xn as isDieType, xr as exitAs, xt as runtime, y as _void, yi as reverse, yn as interrupt$3, yr as deferredUnsafeDone, yt as runPromise, z as flatMap$4, zi as isNone, zn as get$3, zr as sync$1, zt as unsafeMakeLatch } from "./chunks/Schema-B5yK7QrT.mjs";
+import { $ as logWarning, $i as format, $n as map$5, $r as make$19, $t as provide$1, A as catchIf, Ai as get$5, An as scopeMake, Ar as flatMap$3, At as suspend$5, B as flatMap$4, Bi as isNone, Bn as get$3, Br as sync$1, Bt as unsafeMakeLatch, C as all$1, Ci as toArray, Cn as isInterrupted, Cr as exitFail, Ct as sandbox, D as async, Di as GenericTag, Dn as squash, Dr as exitZipRight, Dt as scopedWith$1, E as asVoid$1, Ei as unsafeHead, En as reduceWithContext, Er as exitVoid, Et as scoped$4, F as ensuring$2, Fi as splitAt, Fn as join$3, Fr as map$3, Ft as tryMap, G as forkIn, Gi as some, Gn as TypeId$10, Gr as whenEffect, Gt as zipLeft, H as fnUntraced, Hi as map$8, Hn as modify$1, Hr as uninterruptible, Ht as when, I as exit, Ii as filter$1, In as sequential, Ir as onInterrupt, It as tryPromise, J as ignore, Ji as match$2, Jn as all, Jr as DeferredTypeId$1, Jt as spaced$1, K as forkScoped, Ki as isLeft, Kn as Class, Kr as withFiberRuntime, Kt as zipRight$3, L as fail$5, Li as flatMap$5, Ln as bind, Lr as scopeClose, Lt as try_, M as die$2, Mi as omit, Mn as _await$2, Mr as interruptAsFiber, Mt as tap, N as dieMessage, Ni as empty$5, Nn as inheritAll$1, Nr as interruptFiber, Nt as tapErrorCause, O as catchAll$1, Oi as Tag, On as ensuring$3, Or as fiberId, Ot as serviceOption, P as either, Pi as fromIterable, Pn as interruptAllAs$1, Pr as interruptible$1, Pt as timeout, Q as isEffect, Qi as NodeInspectSymbol, Qn as isFailure, Qr as ids, Qt as mergeAll$2, R as failCause$4, Ri as fromNullable, Rn as bindTo, Rr as succeed$4, Rt as uninterruptible$1, S as addFinalizer$1, Si as takeRight, Sn as isDieType, Sr as exitAs, St as runtime, T as as, Ti as unsafeGet, Tn as map$6, Tr as exitSucceed, Tt as scopeWith, U as forEach$2, Ui as match$4, Un as set$1, Ur as uninterruptibleMask$1, Ut as withFiberRuntime$1, V as flatten$4, Vi as isSome, Vn as make$16, Vr as tap$1, Vt as unsafeMakeSemaphore$1, W as forkDaemon, Wi as none, Wn as update$1, Wr as void_$2, Wt as zip$1, X as interruptible, Xi as pipeArguments, Xn as fail$4, Xr as combine, Xt as tagged, Y as interrupt$4, Yi as right, Yn as die, Yr as empty$6, Yt as TaggedError$1, Z as intoDeferred, Zi as BaseProto, Zn as failCause$3, Zr as combineAll, Zt as fromEffect$5, _ as decodeSync, _i as of, _n as fail$3, _r as deferredIsDone, _t as raceWith, a as Literal, aa as constUndefined, ai as size$2, an as updateContext$1, ar as zipRight$2, at as matchCause, b as acquireRelease, bi as reverse, bn as interrupt$3, br as deferredUnsafeDone, bt as runPromise, c as String$, ca as identity, ci as append$1, cn as Scope, cr as asyncInterrupt, ct as negate, d as Union, di as empty$4, dn as close, dr as deferredAwait, dt as orElse, ea as toJSON, ei as none$1, en as provideMerge$1, er as mapBoth, et as makeSemaphore, f as between, fi as filter, fn as extend, fr as deferredComplete, ft as orElseSucceed, gi as map$7, gn as die$1, gr as deferredInterruptWith, gt as race, hi as isEmpty$2, hn as NoSuchElementException, hr as deferredInterrupt, ht as provideService, i as Defect, ia as constTrue, ii as has, in as unsafeRunPromiseExit, ir as zip$2, it as match$5, j as catchTag, ji as getOption, jn as scopeTag, jr as interrupt$2, jt as sync$2, k as catchAllCause, ki as add, kn as forEachConcurrentDiscard, kr as fiberRefLocally, kt as succeed$6, l as Struct, la as pipe, li as appendAll, ln as addFinalizer, lr as catchAll, lt as onError, m as optional$1, mi as isChunk, mn as make$18, mr as deferredFailCause, mt as provide$2, n as Boolean$, na as hasProperty, ni as make$17, nn as succeed$3, nr as succeed$5, nt as mapBoth$1, o as Never, oa as constVoid, oi as decode, on as forkIn$1, or as as$1, ot as matchCauseEffect, p as decodeUnknown, pi as fromIterable$1, pn as fork, pr as deferredFail, pt as promise, q as gen, qi as left, qn as spanTag, qr as zipRight$1, qt as zipWith, r as Cause, ra as constFalse, ri as set$2, rn as unsafeFork, rr as void_$3, rt as mapError, s as Number$, sa as dual, si as isFinite, sn as unsafeMakeSemaphore, sr as asVoid, st as matchEffect, t as Array$, ta as equals, ti as get$4, tn as scoped$3, tr as match$3, tt as map$4, u as TaggedError, ui as drop, un as addFinalizerExit, ur as currentContext$1, ut as orDie, v as encodeSync, vi as prepend, vn as failureOrCause, vr as deferredMake, vt as repeat, w as annotateLogs, wi as unsafeFromArray, wn as isInterruptedOnly, wr as exitFailCause, wt as scope, x as acquireUseRelease$2, xi as take$2, xn as interruptors, xr as deferredUnsafeMake, xt as runPromiseExit$1, y as _void, yi as reduce, yn as flipCauseOption, yr as deferredSucceed, yt as retry, z as fiberIdWith, zi as getOrElse, zn as sleep, zr as suspend$4, zt as uninterruptibleMask } from "./chunks/Schema-CyImoHTj.mjs";
 import { createRequire } from "node:module";
 import * as Crypto from "node:crypto";
 import { createHash } from "node:crypto";
@@ -5401,6 +5401,7 @@ const makeGitImpl = (executor, root) => {
 		}))),
 		hasCommits: () => exec("git", "rev-parse", "--verify", "HEAD").pipe(map$4(() => true), catchAll$1(() => succeed$6(false))),
 		readFileAtRef: (ref, path) => exec("git", "show", `${ref}:${path}`),
+		diffPaths: (base, tip) => exec("git", "diff", "--name-only", "-z", "--no-renames", "--no-relative", "--ignore-submodules=none", "--end-of-options", base, tip, "--").pipe(map$4(splitNul)),
 		changedPaths: (base) => gen(function* () {
 			const ref = base ?? "HEAD";
 			const nameStatusOut = yield* exec("git", "diff", "--name-status", "-z", ref).pipe(catchAll$1(() => succeed$6("")));
@@ -6071,6 +6072,8 @@ const HISTORY_REF = "refs/worktree/gtd/history";
 /** One ref per finished process, kept past the branch's deletion; distinct from the per-worktree `HISTORY_REF`. */
 const PROCESS_HISTORY_PREFIX = "refs/gtd/history/";
 const processHistoryRef = (hash) => `${PROCESS_HISTORY_PREFIX}${hash}`;
+/** Directory of a step's turns set aside by `keep: true`, each at `<this>/<kept hash>`; own namespace, so history list/show/fetch never see it. */
+const keptRef = (entry, step) => `refs/gtd/kept/${entry}/${step}`;
 const readRetainedHistory = (git) => git.readRefOption(HISTORY_REF);
 /**
 * Whether resetting to `tipHash` is safe: HEAD must be an ancestor of
@@ -6770,6 +6773,22 @@ const accessShapeFault = (value) => {
 const sameGlobs = (a, b) => a === void 0 || b === void 0 ? a === b : a.length === b.length && a.every((g, i) => g === b[i]);
 const sameAccess = (a, b) => sameGlobs(a?.read, b?.read) && sameGlobs(a?.write, b?.write);
 //#endregion
+//#region src/replay/RefName.ts
+const FORBIDDEN = /[\u0000- \u007f~^:?*[\\]/;
+/** Why `name` cannot be (part of) a git ref name, or `undefined` when it can. */
+const refNameFault = (name) => {
+	if (name === "") return "it is empty";
+	if (FORBIDDEN.test(name)) return "it contains a space, control character or one of ~^:?*[\\";
+	if (name.includes("..")) return "it contains \"..\"";
+	if (name.includes("@{")) return "it contains \"@{\"";
+	if (name.endsWith(".")) return "it ends with \".\"";
+	for (const part of name.split("/")) {
+		if (part === "") return "it has an empty \"/\" component";
+		if (part.startsWith(".")) return "a component starts with \".\"";
+		if (part.endsWith(".lock")) return "a component ends with \".lock\"";
+	}
+};
+//#endregion
 //#region src/replay/Tree.ts
 const treeFromRecord = (files) => ({
 	paths: () => Object.keys(files).sort(),
@@ -6864,6 +6883,7 @@ const decodePath = (raw) => {
 	return typeof path === "string" && path !== "" && !CONTROL_CHARACTER$1.test(path) ? path : void 0;
 };
 const FORMAT_RE = /^[1-9][0-9]*$/;
+const HASH_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const TRAILER_READERS = {
 	"Gtd-Step": (value, into) => {
 		into.step ??= parseStepId(value);
@@ -6893,6 +6913,9 @@ const TRAILER_READERS = {
 	"Gtd-Version": (value, into) => {
 		if (value !== "") into.version ??= value;
 	},
+	"Gtd-Kept": (value, into) => {
+		if (HASH_RE.test(value)) into.kept ??= value;
+	},
 	"Gtd-Format": (value, into) => {
 		if (FORMAT_RE.test(value)) into.format ??= Number(value);
 	},
@@ -6913,6 +6936,7 @@ const parseCommitMessage = (message) => {
 		reviewBase: void 0,
 		branch: void 0,
 		version: void 0,
+		kept: void 0,
 		judge: [],
 		vars: {},
 		config: {},
@@ -7027,7 +7051,8 @@ const KNOWN_OPTIONS = {
 		...STEERING_OPTIONS,
 		"model",
 		"system",
-		"allowEmpty"
+		"allowEmpty",
+		"keep"
 	]),
 	human: /* @__PURE__ */ new Set([
 		...STEERING_OPTIONS,
@@ -7059,6 +7084,7 @@ const replay = async (input) => {
 	const scopeCallIds = [];
 	let scopeCallCount = 0;
 	const trace = [];
+	const keptTips = /* @__PURE__ */ new Map();
 	let landed;
 	let outcome;
 	let signal;
@@ -7218,6 +7244,12 @@ const replay = async (input) => {
 		}
 		cursor++;
 		advance(commit);
+		if (commit.parsed.kept !== void 0) if (commit.kept === void 0) keptTips.delete(step.name);
+		else keptTips.set(step.name, {
+			hash: commit.kept.hash,
+			before: commit.tree,
+			after: commit.kept.tree
+		});
 		const to = commit.parsed.parsed?.to;
 		if (to !== void 0) expectedNext = {
 			name: to,
@@ -7225,6 +7257,21 @@ const replay = async (input) => {
 		};
 		return replyFor(step.request, commit.parsed.judge);
 	};
+	const landPending = (step, pending) => {
+		pendingUsed = true;
+		landed = step;
+		const keeping = step.request.kind === "agent" && step.request.options.keep === true;
+		if (keeping) keptTips.set(step.name, {
+			hash: "",
+			before: position.tree,
+			after: pending.tree
+		});
+		advance({
+			hash: "",
+			tree: keeping ? position.tree : pending.tree
+		});
+		return replyFor(step.request, pending.verdicts ?? []);
+	};
 	const answer = (step) => {
 		while (cursor < commits.length && isAttemptAt(commits[cursor], step.name)) cursor++;
 		const commit = commits[cursor];
@@ -7235,17 +7282,18 @@ const replay = async (input) => {
 			trace,
 			landed
 		});
-		pendingUsed = true;
-		landed = step;
-		advance({
-			hash: "",
-			tree: input.pending.tree
-		});
-		return replyFor(step.request, input.pending.verdicts ?? []);
+		return landPending(step, input.pending);
 	};
 	const requestFault = (request) => {
 		if (request.kind === "run" && typeof request.body !== "string") return `gtd: step "${scoped(request.name)}": a run() body is a shell script string — decide in flow code, then render the script (see checkScript and friends)`;
-		return request.kind === "agent" ? scopeAccessFault() : void 0;
+		if (request.kind !== "agent") return void 0;
+		const name = scoped(request.name);
+		if (request.options.keep === true) {
+			if (request.options.allowEmpty === true) return `gtd: step "${name}": keep: true cannot be combined with allowEmpty — a turn that changes nothing has nothing to keep`;
+			const refFault = name.includes("/") ? "it contains \"/\"" : refNameFault(name);
+			if (refFault !== void 0) return `gtd: step "${name}": keep: true files the turn under a git ref named after the step, but ${refFault}`;
+		}
+		return scopeAccessFault();
 	};
 	const handleStep = async (request) => {
 		if (outcome !== void 0) throw new Stop();
@@ -7328,6 +7376,13 @@ const replay = async (input) => {
 				faults: findings.filter((f) => f.message.startsWith(`Code thread at ${c.path}:${t.line + 1}: `)).map((f) => f.message)
 			}));
 		}),
+		kept: (name) => {
+			const tip = keptTips.get(scoped(name));
+			return tip === void 0 ? void 0 : {
+				hash: tip.hash,
+				changes: changesBetween(tip.before, tip.after)
+			};
+		},
 		vars: input.vars,
 		env: input.env,
 		start: () => input.start,
@@ -8293,7 +8348,11 @@ const planStep = (snapshot, opts = {}) => {
 			...uncheckStep(snapshot),
 			{
 				kind: "gitWrite",
-				write: {
+				write: landing.keepTurn !== void 0 ? {
+					kind: "keepTurn",
+					ref: landing.keepTurn,
+					message
+				} : {
 					kind: "commitAll",
 					message
 				}
@@ -8409,6 +8468,10 @@ const resolveBase = (commandLabel, value) => gen(function* () {
 	return mergeBase.value;
 });
 //#endregion
+//#region src/step/strayPaths.ts
+/** Globs use the `access.write` dialect (`globMatches`). */
+const strayPaths = (touched, allow) => touched.filter((path) => !allow.some((glob) => globMatches(path, glob))).sort();
+//#endregion
 //#region src/edge/Edge.ts
 const EMPTY_TREE$1 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const ACTORS = /* @__PURE__ */ new Set([
@@ -8768,6 +8831,7 @@ const promptDef = (common, request, skills, access) => ({
 	...optional("model", request.options.model),
 	...optional("system", request.options.system),
 	...optional("allowEmpty", request.options.allowEmpty),
+	...optional("keep", request.options.keep),
 	...optional("skills", skills),
 	...optional("access", access)
 });
@@ -8882,11 +8946,21 @@ const setupFor = (config, run, workspace, host, startOverrides = {}) => gen(func
 		hash: run.episode.base,
 		tree: commitTree(workspace, run.episode.base)
 	};
-	const episode = run.episode.commits.map((c) => ({
-		hash: c.hash,
-		message: c.message,
-		tree: commitTree(workspace, c.hash)
-	}));
+	const git = yield* GitService;
+	const episode = [];
+	for (const c of run.episode.commits) {
+		const tip = parseCommitMessage(c.message).kept;
+		const exists = tip !== void 0 && isSome(yield* git.readRefOption(`${tip}^{commit}`));
+		episode.push({
+			hash: c.hash,
+			message: c.message,
+			tree: commitTree(workspace, c.hash),
+			...exists ? { kept: {
+				hash: tip,
+				tree: commitTree(workspace, tip)
+			} } : {}
+		});
+	}
 	let pendingMemo;
 	return {
 		resolved,
@@ -9062,6 +9136,7 @@ const closingTrailers = (branch) => ({
 	...isSome(branch) ? { branch: branch.value } : {}
 });
 const isSettledNoop = (rest, to) => rest.changes.length === 0 && rest.stepDef.kind === "script" && to === rest.state;
+const keptTurn = (rest) => rest.stepDef.keep === true && rest.changes.length > 0 ? { keepTurn: keptRef(rest.run.startHash, rest.state) } : {};
 const landingTo = (rest, to, branch) => {
 	if (isSettledNoop(rest, to)) return {
 		kind: "noop",
@@ -9086,7 +9161,8 @@ const landingTo = (rest, to, branch) => {
 			} : {},
 			...finishes ? closingTrailers(branch) : {}
 		},
-		...finishes ? { keepHistory: processHistoryRef(rest.run.startHash) } : {}
+		...finishes ? { keepHistory: processHistoryRef(rest.run.startHash) } : {},
+		...keptTurn(rest)
 	};
 };
 /**
@@ -9223,7 +9299,7 @@ const commitAllowEmpty = (message) => {
 	return [
 		`if ! out=$(git commit --allow-empty -m ${m} 2>&1); then`,
 		`  case "$out" in`,
-		`    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m} ;;`,
+		`    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m} || exit 1 ;;`,
 		`    *) printf '%s\\n' "$out" >&2; exit 1 ;;`,
 		`  esac`,
 		`fi`
@@ -9245,6 +9321,36 @@ const hardResetTo = (ref) => `git reset --hard ${shellQuote(ref)}`;
 * `GitWriterOperations.discardPending` for why it's kept anyway.
 */
 const discardPending = () => `git add -A && git reset --hard HEAD`;
+/**
+* POSIX sh (runs under dash). The marker is a `commit-tree` over HEAD's own
+* tree, so no hook runs on it and its tree is the pre-turn tree by
+* construction; `commit-tree` ignores `commit.gpgSign`, hence the explicit
+* `-S`, read (and failing closed) before any object or ref is written; the
+* index is already staged by then, so an early exit leaves the turn staged.
+* The kept ref is deleted only after `reset -q` succeeds: it is then the
+* turn's only handle.
+* The branch moves before the final hard reset, so if that reset fails the
+* marker has landed and the turn is still in the working tree (kept ref
+* present); every other failure leaves the branch untouched.
+*/
+const keepTurn = (refPrefix, message) => {
+	const keptRef = `${shellQuote(`${refPrefix}/`)}"$gtd_kept"`;
+	return [
+		`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_kept=$(git commit-tree "$gtd_tree" -p "$gtd_head" -m ${shellQuote(message)}) || exit 1`,
+		`git update-ref ${keptRef} "$gtd_kept" || exit 1`,
+		`gtd_marker=$(printf '%s\\nGtd-Kept: %s' ${shellQuote(message)} "$gtd_kept")`,
+		`if ! gtd_tip=$(git commit-tree "$gtd_sign" "$gtd_head^{tree}" -p "$gtd_head" -m "$gtd_marker") || ! git update-ref HEAD "$gtd_tip" "$gtd_head"; then`,
+		`  git reset -q && git update-ref -d ${keptRef}`,
+		`  exit 1`,
+		`fi`,
+		`git reset --hard HEAD`
+	].join("\n");
+};
 const updateRef = (ref, hash) => `git update-ref ${shellQuote(ref)} ${shellQuote(hash)}`;
 /** `git update-ref -d <ref>` — idempotent: deleting a missing ref is already a no-op in real git. */
 const deleteRef = (ref) => `git update-ref -d ${shellQuote(ref)}`;
@@ -9277,6 +9383,7 @@ const renderGitWrite = (write) => {
 	switch (write.kind) {
 		case "commitAll": return commitAll(write.message);
 		case "updateRef": return updateRef(write.ref, write.target);
+		case "keepTurn": return keepTurn(write.ref, write.message);
 	}
 };
 /**
@@ -9661,6 +9768,24 @@ const writeSelection = (out, fields, path) => gen(function* () {
 	else if (selection.kind === "unknown") return yield* fail$5(new SelectorUsageError(`gtd: unknown --json selector "${selection.path}" — see \`gtd --help\``));
 });
 //#endregion
+//#region src/cli/Strays.ts
+const resolveSide = (git, side) => git.resolveRef(`${side}^{commit}`).pipe(mapError(() => new GtdError(`gtd strays: unknown revision '${side}'`)));
+/** stdout carries the array alone; the summary is ungated stderr so a quiet run still explains its exit code, the per-path lines are narration. */
+const runStraysCommand = (command, json, out) => gen(function* () {
+	const git = yield* GitService;
+	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);
+	const strays = strayPaths(touched, command.globs);
+	const total = touched.length;
+	if (json.kind === "select") yield* writeSelection(out, strays, json.path).pipe(catchIf((error) => error instanceof SelectorUsageError && /^\d+$/.test(json.path), () => _void));
+	else out.write(`${JSON.stringify(strays)}\n`);
+	for (const path of strays) yield* narrator.narrate(`stray: ${JSON.stringify(path)}`);
+	yield* narrator.warn(strays.length === 0 ? `gtd strays: no strays — ${total} touched files, all inside the allowlist` : `gtd strays: ${strays.length} of ${total} touched files outside the allowlist`);
+	return strays.length === 0 ? 0 : 10;
+});
+//#endregion
 //#region src/cli/History.ts
 /** Newest tip first. */
 const historyEntries = gen(function* () {
@@ -10313,7 +10438,8 @@ const needsOf = (kind) => {
 		case "lsp":
 		case "install":
 		case "loop":
-		case "judgeRun": return "none";
+		case "judgeRun":
+		case "strays": return "none";
 		case "check":
 		case "uncheck": return "fs";
 		default: return "state";
@@ -10322,10 +10448,13 @@ const needsOf = (kind) => {
 /**
 * Dispatches to the named `run*Command` handler for every `Command.kind` —
 * the counterpart of `Cli.ts`'s `parseArgv`, which has already validated
-* every field a handler receives. A command choosing its own exit code is
-* unrepresentable: every branch returns `Effect<void>`, and `Cli.ts`'s
-* `runCli` supplies `EXIT_OK` once, after this Effect succeeds.
+* every field a handler receives. Only `strays` chooses its exit code; every
+* other branch returns `Effect<void>` and resolves to `EXIT_OK`.
 */
+const dispatchCommand = (command, json, out) => {
+	if (command.kind === "strays") return runStraysCommand(command, json, out);
+	return as(dispatchVoidCommand(command, json, out), 0);
+};
 const dispatchVoidCommand = (command, json, out) => {
 	switch (command.kind) {
 		case "lsp": return runLspCommand();
@@ -10365,7 +10494,7 @@ const dispatchVoidCommand = (command, json, out) => {
 * so a refusal writes nothing and emits no script by construction.
 */
 const runCommand$1 = (command, json, out) => {
-	const dispatch = dispatchVoidCommand(command, json, out);
+	const dispatch = dispatchCommand(command, json, out);
 	if (needsOf(command.kind) !== "state") return dispatch;
 	return gen(function* () {
 		const git = yield* GitService;
@@ -10378,7 +10507,7 @@ const runCommand$1 = (command, json, out) => {
 			warn: () => _void
 		}));
 		for (const warning of config.warnings) yield* narrator.warn(`gtd: warning: ${formatDiagnostic(warning)}`);
-		yield* dispatch;
+		return yield* dispatch;
 	});
 };
 //#endregion
@@ -10393,13 +10522,13 @@ const FLAGS = [
 		name: "--json",
 		arity: "optional",
 		repeatable: false,
-		scope: (kind) => kind === "next" || kind === "land" || kind === "judge" || kind === "judgeAnswer" || kind === "doors" || kind === "historyList" || kind === "historyShow",
+		scope: (kind) => kind === "next" || kind === "land" || kind === "judge" || kind === "judgeAnswer" || kind === "doors" || kind === "historyList" || kind === "historyShow" || kind === "strays",
 		decode: ([raw]) => right(raw ?? ""),
-		scopeError: "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show` — every other command prints plain text; see `gtd install` for the driver protocol briefing",
+		scopeError: "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show`/`gtd strays` — every other command prints plain text; see `gtd install` for the driver protocol briefing",
 		valueHint: "<path>",
 		help: [
 			"(gtd next/gtd land/gtd judge/gtd judge answer/gtd doors/gtd history",
-			"list/gtd history show only) output structured JSON. Bare --json prints the whole document;",
+			"list/gtd history show/gtd strays only) output structured JSON. Bare --json prints the whole document;",
 			"--json=<path> (a dotted key path into that document, e.g.",
 			"kind, content, session.id) prints just that value: a",
 			"scalar raw and unquoted, a boolean as true/false, a list",
@@ -10908,6 +11037,28 @@ const COMMAND_ROWS = [
 			"every question, with nothing on stdout"
 		]
 	},
+	{
+		token: "strays",
+		kind: "strays",
+		arity: {
+			name: "range",
+			variadic: "glob"
+		},
+		details: [
+			"List the files <range> (<base>..<tip>, an empty side is HEAD)",
+			"touched in its committed net diff that match none of the",
+			"globs. Anchored at the repo root: * stays within one path",
+			"segment, ** crosses them, everything else is literal — quote",
+			"globs in the shell. stdout: a sorted JSON array, [] when",
+			"clean; stderr: a summary, plus one stray: line per path with",
+			"--verbose. --json=<n> picks one entry, nothing past the end;",
+			"a symlink is a path like any other, never followed; a",
+			"submodule counts as its path, whatever diff.ignoreSubmodules",
+			"or .gitmodules ignore say. Runs in any git repository, no",
+			"process needed. Exits 10 when",
+			"strays were found, 1 on an unknown revision, 2 on a bad range"
+		]
+	},
 	{
 		token: "history list",
 		kind: "historyList",
@@ -11250,6 +11401,22 @@ const parseArgv = (argv) => {
 		json,
 		verbose
 	};
+	if (kind === "strays") {
+		const [range, ...globs] = restPositionals;
+		const at = range.indexOf("..");
+		if (at < 0 || range.includes("...") || range.indexOf("..", at + 1) >= 0) return usagePlan(`gtd strays: <range> must be <base>..<tip> (an empty side is HEAD) — got '${range}'`, jsonSeen);
+		return {
+			kind: "command",
+			command: {
+				kind: "strays",
+				base: range.slice(0, at) || "HEAD",
+				tip: range.slice(at + 2) || "HEAD",
+				globs
+			},
+			json,
+			verbose
+		};
+	}
 	if (kind === "uncheck") return {
 		kind: "command",
 		command: {
@@ -11328,9 +11495,9 @@ const runCli = (argv, io) => {
 	return flatMap$4(Host, ({ env }) => try_({
 		try: () => resolveFlags(env, io.flags),
 		catch: (e) => new GtdError(e.message)
-	})).pipe(flatMap$4(() => runCommand$1(plan.command, plan.json, out)), map$4(() => {
+	})).pipe(flatMap$4(() => runCommand$1(plan.command, plan.json, out)), map$4((code) => {
 		out.flush();
-		io.exit(0);
+		io.exit(code);
 	}), provide$2(io.layers(plan.verbose)), sandbox, catchAll$1((cause) => isInterruptedOnly(cause) ? failCause$4(cause) : report(io, plan.json.kind !== "off")(cause)));
 };
 //#endregion
@@ -11406,6 +11573,7 @@ var InMemRepo = class InMemRepo {
 		return this.head !== null;
 	}
 	resolveRef(ref) {
+		if (ref.endsWith("^{commit}")) return this.resolveRef(ref.slice(0, -9));
 		if (/^[0-9a-f]{40}$/.test(ref)) return this.commits.has(ref) ? ref : null;
 		const tildeMatch = /^(HEAD|[0-9a-f]{40})(~(\d+)|\^)?$/.exec(ref);
 		if (tildeMatch) {
@@ -11526,6 +11694,10 @@ var InMemRepo = class InMemRepo {
 	changedPathsWorktree(base) {
 		return diffTrees(this.treeAt(base), new Map(this.worktree));
 	}
+	diffPaths(base, tip) {
+		for (const ref of [base, tip]) if (this.resolveRef(ref) === null) throw new Error(`Invalid ref: ${ref}`);
+		return diffTrees(this.treeAt(base), this.treeAt(tip)).map((e) => e.path);
+	}
 	/** The worktree content of `path`, or `undefined` when absent. A LIVE read — never a snapshot. */
 	readFile(path) {
 		return this.worktree.get(path);
@@ -11578,8 +11750,12 @@ var InMemRepo = class InMemRepo {
 	stageAll() {
 		this.index = new Map(this.worktree);
 	}
-	/** Commit whatever is currently staged (the index) verbatim, with no implicit staging first — mirrors `git commit --allow-empty -m <message>` after a soft reset. */
-	commitAsIs(message) {
+	/** Seeded failure modes (see `GitTierSeed`): a pre-commit hook printing this and exiting 1, and a signer that cannot write. */
+	hookRejection = void 0;
+	signingFails = false;
+	/** Seeded: a pre-commit hook writing and staging this file. */
+	hookStages = void 0;
+	writeCommit(message) {
 		const tree = new Map(this.index);
 		const parent = this.head;
 		const hash = makeHash(message, parent, tree);
@@ -11594,27 +11770,59 @@ var InMemRepo = class InMemRepo {
 		this.head = hash;
 		this.branches.set(this.currentBranch, hash);
 	}
-	/** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
-	discardPending() {
-		this.index = new Map(this.worktree);
-		this.resetHard();
+	/**
+	* Twin of the emitted `git commit --allow-empty` if/case retry: a hook
+	* rejection printing "empty git commit" retries without hooks, any other
+	* rejection fails; a failing signer fails either attempt. Commits whatever is
+	* staged verbatim, like `git commit` after a soft reset.
+	*/
+	commitAsIs(message) {
+		if (this.hookRejection !== void 0 && !this.hookRejection.includes("empty git commit")) return this.hookRejection;
+		if (this.signingFails) return "error: gpg failed to sign the data";
+		if (this.hookStages !== void 0) {
+			this.worktree.set(this.hookStages.path, this.hookStages.content);
+			this.index.set(this.hookStages.path, this.hookStages.content);
+		}
+		this.writeCommit(message);
 	}
-	commitAllWithPrefix(prefix) {
+	/** Setup commit: stages everything, and throws if a failure is seeded, as the Live tier's hooks and signer would. */
+	seedCommit(message) {
+		if (this.hookRejection !== void 0 || this.hookStages !== void 0 || this.signingFails) throw new Error("seedCommit after a seeded commit failure");
 		this.index = new Map(this.worktree);
+		this.writeCommit(message);
+	}
+	/** Twin of `GitScript.keepTurn`: no hook runs; `signingFails` fails the marker. */
+	keepTurn(refPrefix, message) {
+		this.stageAll();
 		const tree = new Map(this.index);
-		const message = prefix;
 		const parent = this.head;
 		const hash = makeHash(message, parent, tree);
-		const commit = {
+		this.commits.set(hash, {
 			hash,
 			message,
 			files: new Map(tree),
 			parent,
 			seq: this.nextSeq++
-		};
-		this.commits.set(hash, commit);
-		this.head = hash;
-		this.branches.set(this.currentBranch, hash);
+		});
+		const ref = `${refPrefix}/${hash}`;
+		this.refs.set(ref, hash);
+		this.index = new Map(this.headTree());
+		if (this.signingFails) {
+			this.refs.delete(ref);
+			return "error: gpg failed to sign the data";
+		}
+		this.writeCommit(`${message}\nGtd-Kept: ${hash}`);
+		this.index = new Map(tree);
+		this.resetHard();
+	}
+	/** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
+	discardPending() {
+		this.index = new Map(this.worktree);
+		this.resetHard();
+	}
+	commitAllWithPrefix(prefix) {
+		this.index = new Map(this.worktree);
+		return this.commitAsIs(prefix);
 	}
 	static EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 	softResetTo(ref) {
@@ -11767,6 +11975,7 @@ const makeGitReaderOps = (repo, root) => ({
 		return content !== null ? succeed$6(content) : fail$5(/* @__PURE__ */ new Error(`path not found at ${ref}: ${path}`));
 	},
 	readRefOption: (ref) => {
+		if (/^[0-9a-f]{40}$/.test(ref)) return succeed$6(some(ref));
 		const hash = repo.resolveRef(ref);
 		return succeed$6(hash !== null ? some(hash) : none());
 	},
@@ -11787,12 +11996,16 @@ const makeGitReaderOps = (repo, root) => ({
 	gitCommonDir: () => succeed$6(`${root}/.git`),
 	commitHistory: (base, head) => succeed$6(repo.commitHistory(base, head)),
 	subjectHistory: (pageSize, skip, head) => succeed$6(repo.subjectHistory(pageSize, skip, head)),
-	changedPaths: (base) => succeed$6(repo.changedPathsWorktree(base))
+	changedPaths: (base) => succeed$6(repo.changedPathsWorktree(base)),
+	diffPaths: (base, tip) => tryCatch(() => repo.diffPaths(base, tip))
 });
+const failOn = (output) => {
+	if (output !== void 0) throw new Error(output);
+};
 const makeGitWriterOps = (repo) => ({
-	commitAllWithPrefix: (prefix) => tryCatch(() => repo.commitAllWithPrefix(prefix)),
+	commitAllWithPrefix: (prefix) => tryCatch(() => failOn(repo.commitAllWithPrefix(prefix))),
 	softResetTo: (ref) => tryCatch(() => repo.softResetTo(ref)),
-	commitAsIs: (message) => tryCatch(() => repo.commitAsIs(message)),
+	commitAsIs: (message) => tryCatch(() => failOn(repo.commitAsIs(message))),
 	discardPending: () => tryCatch(() => repo.discardPending()),
 	updateRef: (ref, hash) => tryCatch(() => repo.updateRef(ref, hash)),
 	deleteRef: (ref) => tryCatch(() => repo.deleteRef(ref)),
@@ -11921,6 +12134,13 @@ const missingToolCommands = {
 };
 /** The fine-grained `GitService` layer alone — for unit tests that need only git. */
 const gitTestLayer = (repo, root = "/repo") => succeed$1(GitService, fakeGitOperations(repo, root));
+/**
+* The one sanctioned leak of the real `process.env` into the in-memory `Host`:
+* the runner's `GTD_FLAG_*` state, so a flag-on `npm test` state exercises the
+* flag in memory as it does live. A test asserting one flag side sets the flag
+* itself; explicit env wins.
+*/
+const ambientFlagEnv = (env = process.env) => Object.fromEntries(Object.entries(env).filter((e) => e[0].startsWith("GTD_FLAG_") && e[1] !== void 0));
 /** Every layer `makeProgram` needs — `CommandRequirements`'s return type here IS the guarantee: a new port added there fails this function's typecheck instead of silently under-providing. */
 function testLayers(repo, opts = {}) {
 	const root = opts.root ?? "/repo";
@@ -11928,7 +12148,10 @@ function testLayers(repo, opts = {}) {
 	return mergeAll$1(gitTestLayer(repo, root), succeed$1(Workspace, makeInMemoryWorkspaceOps(repo, root)), Host.layer({
 		root,
 		home,
-		env: opts.env ?? {},
+		env: {
+			...ambientFlagEnv(),
+			...opts.env
+		},
 		realPath: () => succeed$6(root)
 	}), ConfigService.Live, makeInMemoryConfigDiscovery(repo, root), Narrator.layer(opts.narrate ?? (() => {}), opts.verbose ?? true), succeed$1(ToolCommands, {
 		...missingToolCommands,
@@ -12295,25 +12518,51 @@ const conditionStatement = (block) => {
 	const end = block.indexOf(CONDITION_TERMINATOR, start);
 	return end === -1 ? block.slice(start) : block.slice(start, end);
 };
+/** `keepTurn`: an invalid ref name fails before anything moves, as `git update-ref` does. */
+const recognizeKeepTurn = (repo, block) => {
+	const [message, refDir] = extractQuotedTokens(block);
+	const ref = refDir?.slice(0, -1);
+	if (message === void 0 || ref === void 0 || keepTurn(ref, message) !== block) return;
+	if (refNameFault(ref) !== void 0) return {
+		kind: "failed",
+		error: `fatal: invalid ref format: ${ref}`,
+		status: 128
+	};
+	const failure = repo.keepTurn(ref, message);
+	return failure === void 0 ? { kind: "applied" } : {
+		kind: "failed",
+		error: failure,
+		status: 1
+	};
+};
 const recognizeGitBuilders = (repo, block) => {
 	if (block === discardPending()) {
 		repo.discardPending();
 		return { kind: "applied" };
 	}
 	const conditionLine = conditionStatement(block);
+	if (block.startsWith("git add -A || exit 1\ngtd_sign_cfg=")) return recognizeKeepTurn(repo, block);
 	if (block.startsWith("git add -A || exit 1\n")) {
 		const [message] = extractQuotedTokens(conditionLine);
 		if (message !== void 0 && commitAll(message) === block) {
-			repo.commitAllWithPrefix(message);
-			return { kind: "applied" };
+			const failure = repo.commitAllWithPrefix(message);
+			return failure === void 0 ? { kind: "applied" } : {
+				kind: "failed",
+				error: failure,
+				status: 1
+			};
 		}
 		return;
 	}
 	if (block.startsWith("if ! out=$(git commit --allow-empty -m ")) {
 		const [message] = extractQuotedTokens(conditionLine);
 		if (message !== void 0 && commitAsIs(message) === block) {
-			repo.commitAsIs(message);
-			return { kind: "applied" };
+			const failure = repo.commitAsIs(message);
+			return failure === void 0 ? { kind: "applied" } : {
+				kind: "failed",
+				error: failure,
+				status: 1
+			};
 		}
 		return;
 	}
@@ -12850,7 +13099,7 @@ const testRepo = (options) => {
 	const id = `module-${++registered}`;
 	repo.writeFile("gtd.config.ts", typeof workflow === "string" ? workflow : moduleSource(id, workflow));
 	for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content);
-	repo.commitAllWithPrefix("chore: initial commit");
+	repo.seedCommit("chore: initial commit");
 	const gtd = async (...args) => {
 		const { io, result } = makeCapturingCliIo(repo, env);
 		if (typeof workflow !== "string") registry().set(id, workflow);
@@ -12918,7 +13167,7 @@ const testRepo = (options) => {
 		read: (path) => repo.readFile(path),
 		write: (path, content) => repo.writeFile(path, content),
 		remove: (path) => repo.deleteFile(path),
-		commit: (message) => repo.commitAllWithPrefix(message),
+		commit: (message) => repo.seedCommit(message),
 		show: (ref, path) => repo.fileAtRef(ref, path) ?? void 0,
 		runScript: (script) => {
 			const flow = applyFlowScript(repo, /* @__PURE__ */ new Map(), script);
@@ -12958,6 +13207,14 @@ const testRepo = (options) => {
 };
 //#endregion
 //#region src/testkit/GitTiers.ts
+const writeRejectingHook = (hooksDir, output) => {
+	mkdirSync(hooksDir, { recursive: true });
+	writeFileSync(join(hooksDir, "pre-commit"), `#!/bin/sh\ncat >&2 <<'GTD_HOOK_EOF'\n${output}\nGTD_HOOK_EOF\nexit 1\n`, { mode: 493 });
+};
+const writeStagingHook = (hooksDir, path, content) => {
+	mkdirSync(hooksDir, { recursive: true });
+	writeFileSync(join(hooksDir, "pre-commit"), `#!/bin/sh\nprintf '%s' ${shellQuote(content)} > ${shellQuote(path)} && git add ${shellQuote(path)}\nexit 0\n`, { mode: 493 });
+};
 /** No-op — these tests assert on git/config behavior, not narration. */
 const noopNarratorLayer = Narrator.layer(() => {}, false);
 const gitExecIn = (dir, ...args) => execSync(`git ${args.join(" ")}`, {
@@ -13007,7 +13264,6 @@ const makeLiveTier = (initialCommit = true) => {
 		root,
 		capabilities: {
 			onDiskContent: true,
-			commitHooks: true,
 			linkedWorktrees: true,
 			directoryChainConfig: true,
 			remotes: true
@@ -13035,7 +13291,22 @@ const makeLiveTier = (initialCommit = true) => {
 			},
 			stageAll: () => gitExec("add", "-A"),
 			updateRef: (ref, hash) => gitExec("update-ref", ref, hash),
-			mixedReset: (ref) => gitExec("reset", "--mixed", ref)
+			mixedReset: (ref) => gitExec("reset", "--mixed", ref),
+			rejectingHook: (output) => {
+				const hooks = join(root, ".git/hooks");
+				gitExec("config", "core.hooksPath", hooks);
+				writeRejectingHook(hooks, output);
+			},
+			stagingHook: (path, content) => {
+				const hooks = join(root, ".git/hooks");
+				gitExec("config", "core.hooksPath", hooks);
+				writeStagingHook(hooks, path, content);
+			},
+			failingSigner: () => {
+				gitExec("config", "commit.gpgsign", "true");
+				gitExec("config", "gpg.format", "openpgp");
+				gitExec("config", "gpg.program", "false");
+			}
 		},
 		observe: {
 			resolveRef: (ref) => gitExec("rev-parse", ref),
@@ -13101,7 +13372,7 @@ const makeInMemTier = (initialCommit = true) => {
 	const repo = new InMemRepo();
 	if (initialCommit) {
 		repo.writeFile("readme.txt", "hello");
-		repo.commitAllWithPrefix("init: first commit");
+		repo.seedCommit("init: first commit");
 	}
 	const gitLayer = gitTestLayer(repo, IN_MEM_ROOT);
 	const provide = (eff) => runPromise(eff.pipe(provide$2(gitLayer), provide$2(noopNarratorLayer)));
@@ -13111,7 +13382,6 @@ const makeInMemTier = (initialCommit = true) => {
 		root: IN_MEM_ROOT,
 		capabilities: {
 			onDiskContent: false,
-			commitHooks: false,
 			linkedWorktrees: false,
 			directoryChainConfig: true,
 			remotes: false
@@ -13122,17 +13392,29 @@ const makeInMemTier = (initialCommit = true) => {
 		seed: {
 			commit: (message, files = { "file.txt": message }) => {
 				for (const [path, content] of Object.entries(files)) repo.writeFile(path, content);
-				repo.commitAllWithPrefix(message);
+				repo.seedCommit(message);
 			},
 			writeFile: (path, content) => repo.writeFile(path, content),
 			deleteFile: (path) => repo.deleteFile(path),
 			commitDeletion: (path, message) => {
 				repo.deleteFile(path);
-				repo.commitAllWithPrefix(message);
+				repo.seedCommit(message);
 			},
 			stageAll: () => repo.stageAll(),
 			updateRef: (ref, hash) => repo.updateRef(ref, hash),
-			mixedReset: (ref) => repo.mixedResetTo(ref)
+			mixedReset: (ref) => repo.mixedResetTo(ref),
+			rejectingHook: (output) => {
+				repo.hookRejection = output;
+			},
+			stagingHook: (path, content) => {
+				repo.hookStages = {
+					path,
+					content
+				};
+			},
+			failingSigner: () => {
+				repo.signingFails = true;
+			}
 		},
 		observe: {
 			resolveRef: (ref) => {
@@ -13193,7 +13475,7 @@ const PATHOLOGICAL_PATHS = [
 	}
 ];
 /**
-* Exercise all 21 `GitOperations` methods identically against `makeTier()` —
+* Exercise every `GitOperations` methods identically against `makeTier()` —
 * called once per tier by `src/platform/Git.test.ts`. A capability-gated group
 * (`t.capabilities.X`) is skipped, not faked, on a tier that can't support it.
 */
@@ -13228,7 +13510,8 @@ const runGitServiceContract = (makeTier) => {
 			g.subjectHistory(10, 0),
 			g.readFileAtRef("HEAD", "second.txt"),
 			g.changedPaths(),
-			g.changedPaths("HEAD~1")
+			g.changedPaths("HEAD~1"),
+			g.diffPaths("HEAD~1", "HEAD")
 		]));
 		expect(await t.observe.snapshot()).toBe(before);
 		await runGit(t, (g) => g.updateRef("refs/gtd/marker", t.observe.resolveRef("HEAD")));
@@ -13463,16 +13746,6 @@ const runGitServiceContract = (makeTier) => {
 			const history = await runGit(t, (g) => g.commitHistory());
 			expect(history[history.length - 1]?.message).toBe("gtd: grilled");
 		});
-		it.skipIf(!capabilities.commitHooks)("retries with --no-verify when a hook blocks the empty commit", async () => {
-			const hookPath = join(t.root, ".git/hooks/pre-commit");
-			writeFileSync(hookPath, `#!/bin/sh\necho "lint-staged prevented an empty git commit." >&2\nexit 1\n`);
-			execSync(`chmod +x "${hookPath}"`);
-			const headBefore = t.observe.resolveRef("HEAD");
-			await runGit(t, (g) => g.commitAllWithPrefix("gtd: grilled"));
-			expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore);
-			const history = await runGit(t, (g) => g.commitHistory());
-			expect(history[history.length - 1]?.message).toBe("gtd: grilled");
-		});
 	});
 	describe("commitAsIs", () => {
 		it("commits exactly what's staged, ignoring later worktree writes (the squash mechanic)", async () => {
@@ -13491,6 +13764,29 @@ const runGitServiceContract = (makeTier) => {
 			expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore);
 		});
 	});
+	describe.each([["commitAllWithPrefix", (g) => g.commitAllWithPrefix("gtd: building")], ["commitAsIs", (g) => g.commitAsIs("gtd: building")]])("%s seeded commit failures", (_name, commit) => {
+		it("retries with --no-verify when a hook blocks the empty commit", async () => {
+			t.seed.rejectingHook("lint-staged prevented an empty git commit.");
+			const headBefore = t.observe.resolveRef("HEAD");
+			await runGit(t, commit);
+			expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore);
+			const history = await runGit(t, (g) => g.commitHistory());
+			expect(history[history.length - 1]?.message).toBe("gtd: building");
+		});
+		it("fails on a hook rejection that is not the empty-commit one, leaving HEAD unchanged", async () => {
+			t.seed.rejectingHook("lint error");
+			const headBefore = t.observe.resolveRef("HEAD");
+			expect(isFailure(await runGitExit(t, commit))).toBe(true);
+			expect(t.observe.resolveRef("HEAD")).toBe(headBefore);
+		});
+		it("fails both attempts when the signer cannot write, leaving HEAD unchanged", async () => {
+			t.seed.rejectingHook("rejected: empty git commit");
+			t.seed.failingSigner();
+			const headBefore = t.observe.resolveRef("HEAD");
+			expect(isFailure(await runGitExit(t, commit))).toBe(true);
+			expect(t.observe.resolveRef("HEAD")).toBe(headBefore);
+		});
+	});
 	describe("softResetTo", () => {
 		it("moves HEAD back but keeps worktree changes from second commit", async () => {
 			const firstHash = t.observe.resolveRef("HEAD");
@@ -13538,6 +13834,20 @@ const runGitServiceContract = (makeTier) => {
 		it("readRefOption is None for a ref that doesn't exist — never a failure", async () => {
 			expect((await runGit(t, (g) => g.readRefOption("refs/gtd/nonexistent")))._tag).toBe("None");
 		});
+		it("readRefOption of <hash>^{commit} is Some for an existing commit", async () => {
+			const head = t.observe.resolveRef("HEAD");
+			const resolved = await runGit(t, (g) => g.readRefOption(`${head}^{commit}`));
+			expect(resolved._tag).toBe("Some");
+			if (resolved._tag === "Some") expect(resolved.value).toBe(head);
+		});
+		it("readRefOption of <hash>^{commit} is None for a 40-hex hash with no object", async () => {
+			const missing = "0123456789abcdef0123456789abcdef01234567";
+			expect((await runGit(t, (g) => g.readRefOption(`${missing}^{commit}`)))._tag).toBe("None");
+		});
+		it("readRefOption of a bare 40-hex hash with no object is Some", async () => {
+			const missing = "0123456789abcdef0123456789abcdef01234567";
+			expect((await runGit(t, (g) => g.readRefOption(missing)))._tag).toBe("Some");
+		});
 		it("deleteRef removes a ref idempotently (deleting twice is a no-op)", async () => {
 			const head = t.observe.resolveRef("HEAD");
 			await runGit(t, (g) => g.updateRef("refs/gtd/marker", head));
@@ -13606,6 +13916,71 @@ const runGitServiceContract = (makeTier) => {
 			expect(isFailure(await runGitExit(t, (g) => g.readFileAtRef("HEAD", "nonexistent.txt")))).toBe(true);
 		});
 	});
+	describe("diffPaths", () => {
+		const sorted = (paths) => [...paths].sort();
+		it("reports added, modified and deleted paths between two commits", async () => {
+			t.seed.commit("chore: seed", {
+				"mod.txt": "one",
+				"del.txt": "bye"
+			});
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.writeFile("mod.txt", "two");
+			t.seed.stageAll();
+			t.seed.commitDeletion("del.txt", "chore: delete");
+			t.seed.commit("feat: add", {
+				"add.txt": "new",
+				"mod.txt": "two"
+			});
+			const tip = t.observe.resolveRef("HEAD");
+			const paths = await runGit(t, (g) => g.diffPaths(base, tip));
+			expect(sorted(paths)).toEqual([
+				"add.txt",
+				"del.txt",
+				"mod.txt"
+			]);
+		});
+		it("reports both paths of a rename", async () => {
+			t.seed.commit("chore: seed", { "old.txt": "same content unique-marker\n" });
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.deleteFile("old.txt");
+			t.seed.commit("refactor: rename", { "new.txt": "same content unique-marker\n" });
+			const tip = t.observe.resolveRef("HEAD");
+			expect(sorted(await runGit(t, (g) => g.diffPaths(base, tip)))).toEqual(["new.txt", "old.txt"]);
+		});
+		it("omits a file changed then restored between the endpoints", async () => {
+			t.seed.commit("chore: seed", { "flip.txt": "one" });
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.commit("chore: change", { "flip.txt": "two" });
+			t.seed.commit("chore: restore", { "flip.txt": "one" });
+			const tip = t.observe.resolveRef("HEAD");
+			expect(await runGit(t, (g) => g.diffPaths(base, tip))).toEqual([]);
+		});
+		it("never reports staged, unstaged or untracked changes", async () => {
+			t.seed.commit("chore: seed", {
+				"a.txt": "a",
+				"b.txt": "b"
+			});
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.writeFile("a.txt", "staged");
+			t.seed.stageAll();
+			t.seed.writeFile("b.txt", "unstaged");
+			t.seed.writeFile("untracked.txt", "u");
+			expect(await runGit(t, (g) => g.diffPaths(base, "HEAD"))).toEqual([]);
+		});
+		it("is [] for diffPaths(x, x)", async () => {
+			const head = t.observe.resolveRef("HEAD");
+			expect(await runGit(t, (g) => g.diffPaths(head, head))).toEqual([]);
+		});
+		for (const { label, path } of PATHOLOGICAL_PATHS) it(`reports a path containing ${label}, verbatim`, async () => {
+			const base = t.observe.resolveRef("HEAD");
+			t.seed.commit("feat: pathological", { [path]: "content" });
+			expect(await runGit(t, (g) => g.diffPaths(base, "HEAD"))).toEqual([path]);
+		});
+		it("fails when either side does not resolve", async () => {
+			expect(isFailure(await runGitExit(t, (g) => g.diffPaths("totally-invalid-ref-xyz", "HEAD")))).toBe(true);
+			expect(isFailure(await runGitExit(t, (g) => g.diffPaths("HEAD", "totally-invalid-ref-xyz")))).toBe(true);
+		});
+	});
 	describe("changedPaths", () => {
 		it("unions a tracked modification, a tracked deletion, and an untracked addition, deduplicated by path", async () => {
 			t.seed.commit("chore: seed", {