@pmelab/gtd 24.2.0 → 24.3.0

package/dist/gtd.bundle.mjs

@@ -6826,7 +6826,7 @@ var init_label = __esmMin((() => {
 }));
 //#endregion
 //#region node_modules/effect/dist/esm/internal/core-effect.js
-var annotateLogs$1, asSome, try_$1, catchTag$1, diffFiberRefs, bind, bindTo, match$4, fiberRefs, ignore$1, logWithLevel, logWarning$1, logError$1, mapErrorCause, negate$1, patchFiberRefs, promise$1, provideService$1, provideServiceEffect, sandbox$1, sleep$1, succeedNone, summarized, tapErrorCause$1, tryPromise$1, tryMap$1, updateFiberRefs, when$1, serviceOption$1;
+var annotateLogs$1, asSome, try_$1, catchTag$1, diffFiberRefs, bind, bindTo, match$4, fiberRefs, ignore$1, logWithLevel, logWarning$1, logError$1, mapErrorCause, negate$1, orElseSucceed$1, patchFiberRefs, promise$1, provideService$1, provideServiceEffect, sandbox$1, sleep$1, succeedNone, summarized, tapErrorCause$1, tryPromise$1, tryMap$1, updateFiberRefs, when$1, serviceOption$1;
 var init_core_effect = __esmMin((() => {
 	init_Clock();
 	init_Context();
@@ -6910,6 +6910,7 @@ var init_core_effect = __esmMin((() => {
 		onSuccess: succeed$8
 	}));
 	negate$1 = (self) => map$8(self, (b) => !b);
+	orElseSucceed$1 = /*#__PURE__*/ dual(2, (self, evaluate) => orElse$2(self, () => sync$2(evaluate)));
 	patchFiberRefs = (patch) => updateFiberRefs((fiberId, fiberRefs) => pipe(patch, patch$2(fiberId, fiberRefs)));
 	promise$1 = (evaluate) => evaluate.length >= 1 ? async_((resolve, signal) => {
 		try {
@@ -11426,7 +11427,7 @@ var init_MutableQueue = __esmMin((() => {
 }));
 //#endregion
 //#region node_modules/effect/dist/esm/Effect.js
-var isEffect, all$1, forEach$2, async, withFiberRuntime, fail$7, failCause$2, die, dieMessage, gen, promise, succeed$3, suspend$5, sync$1, _void, catchAll, catchAllCause, catchTag, ignore, sandbox, retry, try_, tryMap, tryPromise, interrupt, interruptible, uninterruptible, uninterruptibleMask, as, asVoid, map$4, mapBoth$1, mapError$1, negate, acquireRelease, acquireUseRelease$2, addFinalizer, ensuring$2, onError, scope$1, scopeWith, scopedWith$1, scoped$3, fiberIdWith, forkDaemon, forkIn, forkScoped, timeout, provide$1, provideService, serviceOption, either, exit$1, intoDeferred, when, flatMap$4, andThen, flatten$5, race, raceWith, tap, tapErrorCause, repeat, match$2, matchCause, matchCauseEffect, matchEffect, logWarning, logError, annotateLogs, orDie, orElse$1, runtime, unsafeMakeSemaphore, makeSemaphore, unsafeMakeLatch, runFork$1, runSync, zip$1, zipLeft, zipRight$1, zipWith, fnUntraced;
+var isEffect, all$1, forEach$2, async, withFiberRuntime, fail$7, failCause$2, die, dieMessage, gen, promise, succeed$3, suspend$5, sync$1, _void, catchAll, catchAllCause, catchTag, ignore, sandbox, retry, try_, tryMap, tryPromise, interrupt, interruptible, uninterruptible, uninterruptibleMask, as, asVoid, map$4, mapBoth$1, mapError$1, negate, acquireRelease, acquireUseRelease$2, addFinalizer, ensuring$2, onError, scope$1, scopeWith, scopedWith$1, scoped$3, fiberIdWith, forkDaemon, forkIn, forkScoped, timeout, provide$1, provideService, serviceOption, either, exit$1, intoDeferred, when, flatMap$4, andThen, flatten$5, race, raceWith, tap, tapErrorCause, repeat, match$2, matchCause, matchCauseEffect, matchEffect, logWarning, logError, annotateLogs, orDie, orElse$1, orElseSucceed, runtime, unsafeMakeSemaphore, makeSemaphore, unsafeMakeLatch, runFork$1, runSync, zip$1, zipLeft, zipRight$1, zipWith, fnUntraced;
 var init_Effect = __esmMin((() => {
 	init_core_effect();
 	init_core();
@@ -11507,6 +11508,7 @@ var init_Effect = __esmMin((() => {
 	annotateLogs = annotateLogs$1;
 	orDie = orDie$1;
 	orElse$1 = orElse$2;
+	orElseSucceed = orElseSucceed$1;
 	runtime = runtime$1;
 	unsafeMakeSemaphore = unsafeMakeSemaphore$1;
 	makeSemaphore = makeSemaphore$1;
@@ -20243,8 +20245,17 @@ const resolvedRefOrCorrupted = (ref, hash) => /^[0-9a-f]{40}$/.test(hash) ? succ
 const makeGitImpl = (executor, root) => {
 	const exec = (...args) => run$4(root, ...args).pipe(provide$1(succeed$2(CommandExecutor, executor)));
 	return {
-		lastCommitSubject: (ref = "HEAD") => exec("git", "log", "-1", "--pretty=%s", ref).pipe(map$4((s) => s.trim())),
-		lastCommitMessage: () => exec("git", "log", "-1", "--pretty=%B").pipe(map$4((s) => s.trim())),
+		lastCommitSubject: (ref = "HEAD") => exec("git", "log", "-1", "--pretty=%s", "--end-of-options", ref).pipe(map$4((s) => s.trim())),
+		lastCommitMessage: (ref = "HEAD") => exec("git", "log", "-1", "--pretty=%B", "--end-of-options", ref).pipe(map$4((s) => s.trim())),
+		currentBranch: () => exec("git", "symbolic-ref", "--quiet", "--short", "HEAD").pipe(map$4((s) => s.trim()), map$4((name) => some(name)), catchAll(() => succeed$3(none$4()))),
+		listRefs: (prefix) => exec("git", "for-each-ref", "--sort=-committerdate", "--format=%(refname)%09%(objectname)%09%(committerdate:iso-strict)", prefix).pipe(map$4((out) => out.split("\n").filter((line) => line.length > 0).map((line) => {
+			const [ref = "", hash = "", date = ""] = line.split("	");
+			return {
+				ref,
+				hash,
+				date
+			};
+		}))),
 		hasCommits: () => exec("git", "rev-parse", "--verify", "HEAD").pipe(map$4(() => true), catchAll(() => succeed$3(false))),
 		readFileAtRef: (ref, path) => exec("git", "show", `${ref}:${path}`),
 		changedPaths: (base) => gen(function* () {
@@ -20264,7 +20275,7 @@ const makeGitImpl = (executor, root) => {
 			}
 			return all;
 		}),
-		resolveRef: (ref) => exec("git", "rev-parse", "--verify", ref).pipe(map$4((s) => s.trim()), flatMap$4((hash) => resolvedRefOrCorrupted(ref, hash))),
+		resolveRef: (ref) => exec("git", "rev-parse", "--verify", "--end-of-options", ref).pipe(map$4((s) => s.trim()), flatMap$4((hash) => resolvedRefOrCorrupted(ref, hash))),
 		readRefOption: (ref) => exec("git", "rev-parse", "--verify", "--quiet", ref).pipe(map$4((s) => some(s.trim())), catchAll(() => succeed$3(none$4()))),
 		isAncestor: (a, b) => run$4(root, "git", "merge-base", "--is-ancestor", a, b).pipe(provide$1(succeed$2(CommandExecutor, executor)), map$4(() => true), catchAll(() => succeed$3(false))),
 		mergeBase: (a, b) => exec("git", "merge-base", a, b).pipe(map$4((s) => some(s.trim())), catchAll(() => succeed$3(none$4()))),
@@ -20920,6 +20931,9 @@ const loopLogPath = gen(function* () {
 init_esm();
 /** Per-worktree (`refs/worktree/gtd/*`) so linked worktrees sharing one `.git` don't clobber each other's retained history. */
 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}`;
 const readRetainedHistory = (git) => git.readRefOption(HISTORY_REF);
 /**
 * Whether resetting to `tipHash` is safe: HEAD must be an ancestor of
@@ -37547,6 +37561,12 @@ const TRAILER_READERS = {
 	"Gtd-Review-Base": (value, into) => {
 		into.reviewBase ??= value.split(/\s/)[0];
 	},
+	"Gtd-Branch": (value, into) => {
+		if (value !== "") into.branch ??= value;
+	},
+	"Gtd-Version": (value, into) => {
+		if (value !== "") into.version ??= value;
+	},
 	"Gtd-Format": (value, into) => {
 		if (FORMAT_RE.test(value)) into.format ??= Number(value);
 	},
@@ -37565,6 +37585,8 @@ const parseCommitMessage = (message) => {
 		step: void 0,
 		workflow: void 0,
 		reviewBase: void 0,
+		branch: void 0,
+		version: void 0,
 		judge: [],
 		vars: {},
 		config: {},
@@ -37590,6 +37612,8 @@ const formatCommitMessage = (spec) => {
 	for (const [path, hash] of sortedEntries(spec.config)) lines.push(`Gtd-Config: ${hash} ${encodePath(path)}`);
 	if (spec.cost !== void 0) lines.push(`Gtd-Cost: ${spec.cost.cost}${spec.cost.model !== void 0 ? ` ${spec.cost.model}` : ""}`);
 	for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`);
+	if (spec.branch !== void 0) lines.push(`Gtd-Branch: ${spec.branch}`);
+	if (spec.version !== void 0) lines.push(`Gtd-Version: ${spec.version}`);
 	lines.push(`Gtd-Format: 1`);
 	return `${formatSubject(spec.actor, spec.to, spec.from)}\n\n${lines.join("\n")}`;
 };
@@ -38902,6 +38926,14 @@ const planStep = (snapshot, opts = {}) => {
 					message
 				}
 			},
+			...landing.keepHistory !== void 0 ? [{
+				kind: "gitWrite",
+				write: {
+					kind: "updateRef",
+					ref: landing.keepHistory,
+					target: "HEAD"
+				}
+			}] : [],
 			outcome
 		]
 	};
@@ -39214,25 +39246,38 @@ const currentRun = gen(function* () {
 	const config = yield* (yield* ConfigService).load;
 	return yield* computeProcessRun(git, config.workflow);
 });
-/** The process HEAD closes or sits inside — `gtd summary`'s run. */
-const summaryRun = gen(function* () {
-	const git = yield* GitService;
-	const def = (yield* (yield* ConfigService).load).workflow;
-	const headEntry = (yield* git.subjectHistory(1, 0))[0];
-	if (headEntry === void 0) {
+const runAtTip = (git, def, tip) => gen(function* () {
+	if (tip === void 0) {
 		const history = yield* historyUpTo(git, def, void 0);
 		return yield* runOf(history, locateEpisode(def, history));
 	}
-	if (!(parseCommitMessage(headEntry.subject).parsed?.to === def.initial)) {
-		const history = yield* historyUpTo(git, def, headEntry.hash);
+	if (!(parseCommitMessage(tip.subject).parsed?.to === def.initial)) {
+		const history = yield* historyUpTo(git, def, tip.hash);
 		return yield* runOf(history, locateEpisode(def, history));
 	}
-	const parentRef = `${headEntry.hash}~1`;
+	const parentRef = `${tip.hash}~1`;
 	const before = yield* historyUpTo(git, def, parentRef);
 	const location = locateEpisode(def, before);
-	let closing = yield* git.commitHistory(parentRef, headEntry.hash);
-	if (closing.length === 0) closing = yield* git.commitHistory(void 0, headEntry.hash);
-	return yield* runOf([...before, ...closing], { ...location }, headEntry.hash);
+	let closing = yield* git.commitHistory(parentRef, tip.hash);
+	if (closing.length === 0) closing = yield* git.commitHistory(void 0, tip.hash);
+	return yield* runOf([...before, ...closing], { ...location }, tip.hash);
+});
+/** The process HEAD closes or sits inside — `gtd summary`'s run. */
+const summaryRun = gen(function* () {
+	const git = yield* GitService;
+	const def = (yield* (yield* ConfigService).load).workflow;
+	return yield* runAtTip(git, def, (yield* git.subjectHistory(1, 0))[0]);
+});
+/** The process whose finishing commit is `tip` — reads from `tip`'s own ancestry, so it works when no branch reaches it. */
+const closedRunAt = (tip) => gen(function* () {
+	const git = yield* GitService;
+	const def = (yield* (yield* ConfigService).load).workflow;
+	const hash = yield* git.resolveRef(tip);
+	const subject = yield* git.lastCommitSubject(hash);
+	return yield* runAtTip(git, def, {
+		hash,
+		subject
+	});
 });
 const commitTree = (workspace, hash) => {
 	let entries;
@@ -39452,13 +39497,7 @@ const costByModel = (entries) => {
 		cost
 	})).sort((a, b) => b.cost - a.cost || a.model.localeCompare(b.model));
 };
-/** Resolve the rest at `ref`, or at HEAD when `ref` is `undefined`. */
-const restAt = (ref, startOverrides = {}) => gen(function* () {
-	const git = yield* GitService;
-	const config = yield* (yield* ConfigService).load;
-	const workspace = yield* Workspace;
-	const host = yield* Host;
-	const run = yield* computeProcessRun(git, config.workflow, ref);
+const setupFor = (config, run, workspace, host, startOverrides = {}) => gen(function* () {
 	const resolved = yield* workflowOf(config, run);
 	const def = resolved.def;
 	const { vars, env } = settingsFor(resolved, run.pinnedVars, host.env, startOverrides);
@@ -39482,19 +39521,34 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 		tree: commitTree(workspace, c.hash)
 	}));
 	let pendingMemo;
-	const setup = {
+	return {
+		resolved,
 		def,
-		run,
 		vars,
 		env,
-		budget,
-		skills,
-		access,
-		workspace,
-		base,
-		episode,
-		pendingWorktree: () => pendingMemo ??= workspace.worktreeSync()
+		setup: {
+			def,
+			run,
+			vars,
+			env,
+			budget,
+			skills,
+			access,
+			workspace,
+			base,
+			episode,
+			pendingWorktree: () => pendingMemo ??= workspace.worktreeSync()
+		}
 	};
+});
+/** Resolve the rest at `ref`, or at HEAD when `ref` is `undefined`. */
+const restAt = (ref, startOverrides = {}) => gen(function* () {
+	const git = yield* GitService;
+	const config = yield* (yield* ConfigService).load;
+	const workspace = yield* Workspace;
+	const host = yield* Host;
+	const run = yield* computeProcessRun(git, config.workflow, ref);
+	const { resolved, def, vars, env, setup } = yield* setupFor(config, run, workspace, host, startOverrides);
 	const outcome = yield* promise(() => replayFor(setup));
 	const error = replayError(outcome);
 	if (error !== void 0 || outcome.kind !== "rest") return yield* fail$7(error ?? /* @__PURE__ */ new Error("gtd: replay found no rest"));
@@ -39636,14 +39690,21 @@ const initialStepRefusal = (workflow, step, initial) => workflow !== void 0 && s
 	kind: "refusal",
 	message: `gtd: workflow "${workflow}" reaches step "${step}", the default workflow's first step — that is where a finished process waits, so a started process must never land there; rename the step`
 } : void 0;
-const landingTo = (rest, to) => {
-	if (rest.changes.length === 0 && rest.stepDef.kind === "script" && to === rest.state) return {
+const closingTrailers = (branch) => ({
+	version: GTD_VERSION,
+	...isSome(branch) ? { branch: branch.value } : {}
+});
+const isSettledNoop = (rest, to) => rest.changes.length === 0 && rest.stepDef.kind === "script" && to === rest.state;
+const landingTo = (rest, to, branch) => {
+	if (isSettledNoop(rest, to)) return {
 		kind: "noop",
 		settled: true
 	};
-	const starts = noProcessUnderway(rest) && to !== rest.def.initial;
+	const underway = !noProcessUnderway(rest);
+	const starts = !underway && to !== rest.def.initial;
 	const refused = starts ? multilineRefusal(rest.vars) : void 0;
 	if (refused !== void 0) return refused;
+	const finishes = underway && to === rest.def.initial;
 	return {
 		kind: "commit",
 		to,
@@ -39655,8 +39716,10 @@ const landingTo = (rest, to) => {
 			...starts ? {
 				vars: rest.vars,
 				config: rest.config
-			} : {}
-		}
+			} : {},
+			...finishes ? closingTrailers(branch) : {}
+		},
+		...finishes ? { keepHistory: processHistoryRef(rest.run.startHash) } : {}
 	};
 };
 /**
@@ -39664,7 +39727,7 @@ const landingTo = (rest, to) => {
 * replay with the working tree as the pending turn. The target step is
 * computed by replaying, never matched.
 */
-const decideLanding = (rest, verdicts) => gen(function* () {
+const decideLanding = (rest, verdicts, branch) => gen(function* () {
 	const early = cleanLanding(rest);
 	if (early !== void 0) return early;
 	if (rest.stepDef.kind === "prompt" && rest.stepDef.access?.write != null) {
@@ -39680,13 +39743,14 @@ const decideLanding = (rest, verdicts) => gen(function* () {
 	}));
 	const to = yield* landingTarget(outcome, rest);
 	if (typeof to !== "string") return to;
-	return landingTo(rest, to);
+	return landingTo(rest, to, branch);
 });
 /** Where landing the pending turn would leave the process, or `undefined` when it would land nothing. */
-const previewLanding = (rest) => decideLanding(rest, void 0).pipe(map$4((landing) => landing.kind === "commit" ? landing.to : void 0), catchAll(() => succeed$3(void 0)));
+const previewLanding = (rest) => decideLanding(rest, void 0, none$4()).pipe(map$4((landing) => landing.kind === "commit" ? landing.to : void 0), catchAll(() => succeed$3(void 0)));
 /** Every fact the pure landing planner needs, read once: the rest, its steering file, and the landing decision. */
 const snapshotFromRest = (rest, verdicts) => gen(function* () {
-	const landing = yield* decideLanding(rest, verdicts);
+	const branch = yield* (yield* GitService).currentBranch();
+	const landing = yield* decideLanding(rest, verdicts, branch);
 	return {
 		stepDef: rest.stepDef,
 		state: rest.state,
@@ -39717,6 +39781,66 @@ const summaryFor = (run) => gen(function* () {
 		...settingsFor(resolved, run.pinnedVars, host.env)
 	});
 });
+/** Repository-relative paths of the config files today's config and the process's own record name; one outside the repository cannot be read at a ref, so it is left out. */
+const inRepoConfigPaths = (root, files, recorded) => {
+	const paths = new Set(Object.keys(recorded));
+	for (const file of files) paths.add(relative(root, resolve(root, file)).split(sep).join("/"));
+	return [...paths].filter((p) => p !== "" && !p.startsWith("..") && !isAbsolute(p)).sort();
+};
+const configRefusal = (tip, paths) => /* @__PURE__ */ new Error(`gtd history: refused — config differs at ${tip.slice(0, 7)}: ${paths.join(", ")}. A history ref replays under today's config, so it is unreadable after the config changes`);
+const differingConfigPaths = (git, workspace, root, config, run, hash) => gen(function* () {
+	const differing = [];
+	for (const path of inRepoConfigPaths(root, config.workflowFiles, run.pinnedConfig?.files ?? {})) if ((yield* orElseSucceed(git.readFileAtRef(hash, path), () => void 0)) !== workspace.readSync(path)) differing.push(path);
+	return differing;
+});
+const notClosedError = (hash, outcome) => outcome.kind === "rest" ? /* @__PURE__ */ new Error(`gtd history: ${hash.slice(0, 7)} does not close a process under today's config`) : replayError(outcome) ?? /* @__PURE__ */ new Error("gtd history: replay failed");
+const historySteps = (run) => {
+	const messages = new Map(run.episode.commits.map((c) => [c.hash, c.message]));
+	return run.trace.map((entry) => {
+		const message = parseCommitMessage(messages.get(entry.hash) ?? "");
+		return {
+			hash: entry.hash,
+			subject: (messages.get(entry.hash) ?? "").split("\n")[0] ?? "",
+			actor: entry.actor,
+			from: message.parsed?.from,
+			to: entry.state,
+			verdicts: message.judge
+		};
+	});
+};
+const versionWarningFor = (recorded) => recorded === GTD_VERSION ? void 0 : `gtd: warning: this history was recorded by ${recorded === void 0 ? "an unknown gtd version" : `gtd ${recorded}`} and is replayed by gtd ${GTD_VERSION} — a workflow imported from @pmelab/gtd/workflows may have changed since`;
+/**
+* Replays the closed run at `tip` under today's config. The workflow is not
+* fingerprinted for a version change: one imported from `@pmelab/gtd/workflows`
+* moves with every upgrade, and the version warning is the only signal.
+*/
+const historyTrail = (tip) => gen(function* () {
+	const git = yield* GitService;
+	const config = yield* (yield* ConfigService).load;
+	const workspace = yield* Workspace;
+	const host = yield* Host;
+	const hash = yield* git.resolveRef(tip);
+	const run = yield* closedRunAt(hash);
+	const differing = yield* differingConfigPaths(git, workspace, host.root, config, run, hash);
+	if (differing.length > 0) return yield* fail$7(configRefusal(hash, differing));
+	const { setup } = yield* setupFor(config, run, workspace, host);
+	yield* workspace.episodeTrees(run.episode.base, run.episode.commits.map((c) => c.hash));
+	const outcome = yield* promise(() => replayFor(setup));
+	if (outcome.kind !== "ended") return yield* fail$7(notClosedError(hash, outcome));
+	const steps = historySteps(run);
+	const recorded = parseCommitMessage(yield* git.lastCommitMessage(hash)).version;
+	const versionWarning = versionWarningFor(recorded);
+	return {
+		tip: hash,
+		steps,
+		ended: outcome.via,
+		version: {
+			recorded,
+			running: GTD_VERSION
+		},
+		...versionWarning !== void 0 ? { versionWarning } : {}
+	};
+});
 //#endregion
 //#region src/emit/GitScript.ts
 const shellQuote$1 = (value) => `'${value.replace(/'/g, "'\\''")}'`;
@@ -39738,13 +39862,24 @@ const commitAllowEmpty = (message) => {
 		`fi`
 	].join("\n");
 };
-/** `git add -A` then `commitAllowEmpty`, joined with `&&` so a failing `git add` never reaches the commit. */
-const commitAll = (message) => `git add -A &&\n${commitAllowEmpty(message)}`;
+/** `git add -A || exit 1` (an `&&` left side would not abort under `set -e`) then `commitAllowEmpty`. */
+const commitAll = (message) => `git add -A || exit 1\n${commitAllowEmpty(message)}`;
 const mixedResetTo = (ref) => `git reset --mixed ${shellQuote$1(ref)}`;
 const hardResetTo = (ref) => `git reset --hard ${shellQuote$1(ref)}`;
 const updateRef = (ref, hash) => `git update-ref ${shellQuote$1(ref)} ${shellQuote$1(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$1(ref)}`;
+/**
+* No `+` on the refspec: a local ref the remote's tip does not descend from
+* fails the fetch instead of being overwritten (a fast-forward still applies).
+*/
+const fetchHistoryRefs = (remote) => [
+	`set -eu`,
+	`before=$(git for-each-ref --format='x' 'refs/gtd/history/' | wc -l)`,
+	`git fetch ${shellQuote$1(remote)} 'refs/gtd/history/*:refs/gtd/history/*'`,
+	`after=$(git for-each-ref --format='x' 'refs/gtd/history/' | wc -l)`,
+	`printf '%s history refs arrived\\n' "$((after - before))"`
+].join("\n");
 /** Marks an emitted block as print-only — mirrors `OutcomeScript.ts`'s `OUTCOME_MARKER` verbatim, so `src/testkit/EmittedScriptRecognizer.ts` recognizes either path's output identically. */
 const OUTCOME_MARKER$1 = "# gtd: outcome (print-only)";
 const printfLine$1 = (fmt, args) => `${OUTCOME_MARKER$1}\nprintf ${shellQuote$1(fmt.replace(/\n/g, "\\n"))} ${args.join(" ")}`;
@@ -39762,6 +39897,7 @@ const renderOutcome = (outcome) => {
 const renderGitWrite = (write) => {
 	switch (write.kind) {
 		case "commitAll": return commitAll(write.message);
+		case "updateRef": return updateRef(write.ref, write.target);
 	}
 };
 /**
@@ -40133,10 +40269,9 @@ init_esm();
 */
 var ToolCommands = class extends Tag("ToolCommands")() {};
 //#endregion
-//#region src/cli/Program.ts
+//#region src/cli/Output.ts
 init_esm();
 init_wire();
-init_steering();
 /**
 * A command-level failure that should exit like a CLI usage error (2), not a
 * generic runtime failure (1): an unknown `--json=<path>` selector, or a
@@ -40146,12 +40281,97 @@ init_steering();
 * about the resolved rest's own state.
 */
 var SelectorUsageError = class extends Error {};
-/** The `--json=<path>` select branch, shared by all three emitting commands so none drift on the unknown-selector message. `absent` writes nothing and lets the caller's success path continue. */
+/** The `--json=<path>` select branch, shared by the emitting commands so none drift on the unknown-selector message. `absent` writes nothing and lets the caller's success path continue. */
 const writeSelection = (out, fields, path) => gen(function* () {
 	const selection = selectPath(fields, path);
 	if (selection.kind === "value") out.write(`${selection.text}\n`);
 	else if (selection.kind === "unknown") return yield* fail$7(new SelectorUsageError(`gtd: unknown --json selector "${selection.path}" — see \`gtd --help\``));
 });
+//#endregion
+//#region src/cli/History.ts
+init_esm();
+/** Newest tip first. */
+const historyEntries = gen(function* () {
+	const git = yield* GitService;
+	const refs = (yield* git.listRefs(PROCESS_HISTORY_PREFIX)).filter(({ ref }) => ENTRY_HASH.test(ref.slice(17)));
+	return yield* forEach$2(refs, ({ ref, hash, date }) => gen(function* () {
+		const entry = ref.slice(17);
+		return {
+			ref,
+			entry,
+			branch: parseCommitMessage(yield* git.lastCommitMessage(hash)).branch ?? null,
+			tip: hash,
+			date,
+			subject: yield* git.lastCommitSubject(entry)
+		};
+	}));
+});
+const ENTRY_HASH = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+const HEX = /^[0-9a-f]+$/i;
+/**
+* Lookup order: full ref; then entry hash or hex prefix (unique → it, several
+* → fail listing them); then branch name (newest tip first, as `entries` is
+* ordered). A hex-looking name that matches no entry still resolves as a
+* branch. No match → fail.
+*/
+const resolveHistoryRef = (arg, entries) => {
+	const byRef = entries.find((e) => e.ref === arg);
+	if (byRef !== void 0) return succeed$3(byRef);
+	if (HEX.test(arg)) {
+		const lower = arg.toLowerCase();
+		const matches = entries.filter((e) => e.entry.toLowerCase().startsWith(lower));
+		if (matches.length === 1) return succeed$3(matches[0]);
+		if (matches.length > 1) return fail$7(/* @__PURE__ */ new Error(`gtd history: "${arg}" is ambiguous — it matches:\n${matches.map((e) => `  ${e.entry} ${e.branch ?? "-"}`).join("\n")}`));
+	}
+	const byBranch = entries.find((e) => e.branch === arg);
+	if (byBranch !== void 0) return succeed$3(byBranch);
+	return fail$7(/* @__PURE__ */ new Error(`gtd history: no history ref matches "${arg}"`));
+};
+const seven = (hash) => hash.slice(0, 7);
+/** Writes `document` per `json` (bare → whole, `=path` → one value); returns false for `off`. */
+const writeJson = (json, out, document) => gen(function* () {
+	if (json.kind === "off") return false;
+	if (json.kind === "document") out.write(`${JSON.stringify(document)}\n`);
+	else yield* writeSelection(out, document, json.path);
+	return true;
+});
+const runHistoryListCommand = (json, out) => gen(function* () {
+	const entries = yield* historyEntries;
+	if (yield* writeJson(json, out, entries)) return;
+	if (entries.length === 0) {
+		out.write("no history refs; run gtd history fetch | sh to pull them\n");
+		return;
+	}
+	out.write(entries.map((e) => `${seven(e.entry)} ${e.branch ?? "-"} ${seven(e.tip)} ${e.date} ${e.subject}\n`).join(""));
+});
+const runHistoryShowCommand = (ref, json, out) => gen(function* () {
+	const entry = yield* resolveHistoryRef(ref, yield* historyEntries);
+	const trail = yield* historyTrail(entry.tip);
+	const document = {
+		ref: entry.ref,
+		entry: entry.entry,
+		branch: entry.branch,
+		...trail
+	};
+	if (yield* writeJson(json, out, document)) return;
+	if (trail.versionWarning !== void 0) yield* (yield* Narrator).warn(trail.versionWarning);
+	const lines = [`${entry.ref} (branch ${entry.branch ?? "-"}, tip ${seven(entry.tip)})`];
+	for (const step of trail.steps) {
+		lines.push(`${seven(step.hash)} ${step.subject}`);
+		for (const v of step.verdicts) lines.push(`  judge ${v.id} = ${v.answer} (p=${v.p})`);
+	}
+	lines.push(`ended (${trail.ended})`);
+	out.write(`${lines.join("\n")}\n`);
+});
+/** Prints the script and never runs git: gtd's promise that it only decides and prints. */
+const runHistoryFetchCommand = (remote, out) => sync$1(() => {
+	out.write(`${combinedScript(fetchHistoryRefs(remote), "")}\n`);
+});
+//#endregion
+//#region src/cli/Program.ts
+init_esm();
+init_wire();
+init_steering();
 const selfGtd = () => {
 	const script = process.argv[1];
 	return script === void 0 ? ["gtd"] : [process.execPath, script];
@@ -40773,6 +40993,9 @@ const dispatchVoidCommand = (command, json, out) => {
 		case "judge": return runJudgeCommand(json, out);
 		case "judgeAnswer": return runJudgeAnswerCommand(json, out);
 		case "judgeRun": return runJudgeRunCommand(command, out);
+		case "historyList": return runHistoryListCommand(json, out);
+		case "historyShow": return runHistoryShowCommand(command.ref, json, out);
+		case "historyFetch": return runHistoryFetchCommand(command.remote, out);
 	}
 };
 /**
@@ -40813,13 +41036,13 @@ const FLAGS = [
 		name: "--json",
 		arity: "optional",
 		repeatable: false,
-		scope: (kind) => kind === "next" || kind === "land" || kind === "judge" || kind === "judgeAnswer" || kind === "doors",
+		scope: (kind) => kind === "next" || kind === "land" || kind === "judge" || kind === "judgeAnswer" || kind === "doors" || kind === "historyList" || kind === "historyShow",
 		decode: ([raw]) => right(raw ?? ""),
-		scopeError: "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors` — 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` — 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 only) output",
-			"structured JSON. Bare --json prints the whole document;",
+			"(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;",
 			"--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",
@@ -41327,6 +41550,44 @@ const COMMAND_ROWS = [
 			"repository. jev and llm exit 1 when they cannot answer",
 			"every question, with nothing on stdout"
 		]
+	},
+	{
+		token: "history list",
+		kind: "historyList",
+		arity: "none",
+		details: [
+			"List the finished processes kept behind refs/gtd/history/*,",
+			"newest first: entry, branch, tip, date and subject per line.",
+			"--json prints one array of { ref, entry, branch, tip, date,",
+			"subject }. Writes nothing and never replays; with no refs it",
+			"hints at `gtd history fetch | sh` and still exits 0"
+		]
+	},
+	{
+		token: "history show",
+		kind: "historyShow",
+		arity: { name: "ref" },
+		details: [
+			"Replay one kept process under today's config and print its",
+			"steps and judge verdicts. <ref> is a full ref, an entry hash",
+			"(or unique prefix) or a branch name. Refuses (exit 1) when a",
+			"config file differs from its content at the ref's tip. A",
+			"version mismatch only warns on stderr. --json prints the",
+			"trail as one document; writes nothing"
+		]
+	},
+	{
+		token: "history fetch",
+		kind: "historyFetch",
+		arity: {
+			name: "remote",
+			optional: true
+		},
+		details: [
+			"Print a script that fetches every refs/gtd/history/* from",
+			"<remote> (default origin) and reports how many arrived — run",
+			"it with `gtd history fetch | sh`. Never runs git itself"
+		]
 	}
 ];
 const commandByToken = (token) => COMMAND_ROWS.find((r) => r.token === token);
@@ -41346,7 +41607,7 @@ const flagHeader = (row) => {
 };
 const renderHelp = () => {
 	const commandBlocks = COMMAND_ROWS.map((row) => {
-		const header = row.arity === "none" ? row.token : "names" in row.arity ? `${row.token} <${row.arity.names[0]}> <${row.arity.names[1]}>` : "variadic" in row.arity ? `${row.token} <${row.arity.name}> [${row.arity.variadic}...]` : `${row.token} <${row.arity.name}>`;
+		const header = row.arity === "none" ? row.token : "names" in row.arity ? `${row.token} <${row.arity.names[0]}> <${row.arity.names[1]}>` : "variadic" in row.arity ? `${row.token} <${row.arity.name}> [${row.arity.variadic}...]` : "optional" in row.arity ? `${row.token} [${row.arity.name}]` : `${row.token} <${row.arity.name}>`;
 		return renderBlock(header, row.details);
 	});
 	return `Usage: gtd [command] [options]\n\nCommands:\n${[
@@ -41457,6 +41718,7 @@ const conflictViolation = (present) => {
 const arityError = (cmd, rest, arity) => {
 	if (arity === "none") return rest.length > 0 ? `gtd ${cmd}: too many arguments — expected none, got: ${rest.join(", ")}` : void 0;
 	if ("names" in arity) return pairArityError(cmd, rest, arity.names);
+	if ("optional" in arity) return rest.length > 1 ? `gtd ${cmd}: too many arguments — expected at most one ${arity.name}, got: ${rest.join(", ")}` : void 0;
 	if (rest.length === 0) return `gtd ${cmd}: missing ${arity.name} argument`;
 	if (!("variadic" in arity) && rest.length > 1) return `gtd ${cmd}: too many arguments — expected one ${arity.name}, got: ${rest.join(", ")}`;
 };
@@ -41507,7 +41769,9 @@ const parseArgv = (argv) => {
 		kind: "output",
 		stdout: renderHelp()
 	};
-	const row = first === void 0 ? void 0 : commandByToken(first);
+	const isHistory = first === "history";
+	const row = first === void 0 ? void 0 : commandByToken(isHistory ? `history ${positionals[1] ?? ""}` : first);
+	if (isHistory && row === void 0) return usagePlan("gtd history: expected a subcommand — list, show <ref> or fetch [remote]", jsonSeen);
 	const judgeAnswer = row?.kind === "judge" && positionals[1] === "answer";
 	const selectsStart = workflowPresent && first === void 0;
 	const judgeRun = row?.kind === "judge" && positionals[1] === "run";
@@ -41518,11 +41782,11 @@ const parseArgv = (argv) => {
 		if (first === void 0) return usagePlan("gtd: missing command — gtd decides and prints, a driver executes; run `gtd install`, or copy one from https://github.com/pmelab/gtd/blob/main/docs/driver.md's \"A complete minimal driver\" section and run that, or see usage above (`gtd --help`)", jsonSeen, renderHelp());
 		return usagePlan(`unknown command '${first}'`, jsonSeen);
 	}
-	const restPositionals = first === void 0 ? positionals : positionals.slice(judgeAnswer || judgeRun ? 2 : 1);
+	const restPositionals = first === void 0 ? positionals : positionals.slice(judgeAnswer || judgeRun || isHistory ? 2 : 1);
 	if (kind === "start" && first === void 0) {
 		if (restPositionals.length > 0) return usagePlan(`gtd: too many arguments — expected none, got: ${restPositionals.join(", ")}`, jsonSeen);
 	} else {
-		const arityMsg = kind === "check" && restPositionals.length === 0 && present.has("--open-threads") ? void 0 : arityError(first, restPositionals, row.arity);
+		const arityMsg = kind === "check" && restPositionals.length === 0 && present.has("--open-threads") ? void 0 : arityError(isHistory ? row.token : first, restPositionals, row.arity);
 		if (arityMsg !== void 0) return usagePlan(arityMsg, jsonSeen);
 	}
 	const violation = scopeViolation(kind, present);
@@ -41611,6 +41875,24 @@ const parseArgv = (argv) => {
 			verbose
 		};
 	}
+	if (kind === "historyShow") return {
+		kind: "command",
+		command: {
+			kind: "historyShow",
+			ref: restPositionals[0]
+		},
+		json,
+		verbose
+	};
+	if (kind === "historyFetch") return {
+		kind: "command",
+		command: {
+			kind: "historyFetch",
+			remote: restPositionals[0] ?? "origin"
+		},
+		json,
+		verbose
+	};
 	if (kind === "uncheck") return {
 		kind: "command",
 		command: {