gentle-pi 2.1.2 → 2.2.0

package/extensions/sdd-init.ts

@@ -775,11 +775,29 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Auto-detect project stack and bootstrap openspec/config.yaml for SDD.",
 		handler: async (_args: unknown, ctx: any) => {
-			await ensureSddPreflight(ctx, {
+			const prefs = await ensureSddPreflight(ctx, {
 				pi,
 				installAssets: (cwd) => installSddAssets(cwd, false),
 				applyModelConfig: () => applySavedModelConfig(ctx),
 			});
+
+			const detection = detectProject(ctx.cwd);
+			const testSummary = detection.testCommand
+				? `strict TDD enabled with \`${detection.testCommand}\``
+				: "strict TDD disabled because no test runner was detected";
+			const layerSummary = `unit: ${detection.commands.unit.length}, integration: ${detection.commands.integration.length}, e2e: ${detection.commands.e2e.length}`;
+
+			const shouldCreateOpenSpec =
+				prefs.artifactStore === "openspec" ||
+				prefs.artifactStore === "both";
+			if (!shouldCreateOpenSpec) {
+				ctx.ui.notify(
+					`SDD initialized for ${prefs.artifactStore}: detected ${detection.stack.join(", ") || "project"}; ${testSummary}; tests found: ${layerSummary}.`,
+					"info",
+				);
+				return;
+			}
+
 			const configPath = join(ctx.cwd, CONFIG_REL_PATH);
 			if (existsSync(configPath)) {
 				ctx.ui.notify(
@@ -789,15 +807,10 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			const detection = detectProject(ctx.cwd);
 			ensureOpenSpecDirs(ctx.cwd);
 			mkdirSync(dirname(configPath), { recursive: true });
 			writeFileSync(configPath, renderConfig(detection));
 
-			const testSummary = detection.testCommand
-				? `strict TDD enabled with \`${detection.testCommand}\``
-				: "strict TDD disabled because no test runner was detected";
-			const layerSummary = `unit: ${detection.commands.unit.length}, integration: ${detection.commands.integration.length}, e2e: ${detection.commands.e2e.length}`;
 			ctx.ui.notify(
 				`Wrote ${CONFIG_REL_PATH}: detected ${detection.stack.join(", ") || "project"}; ${testSummary}; tests found: ${layerSummary}.`,
 				"info",

package/extensions/skill-registry.ts

@@ -21,7 +21,7 @@ const EXCLUDE_NAMES = new Set(["_shared", "skill-registry"]);
 const EXCLUDE_PREFIXES = ["sdd-"];
 const ATL_IGNORE_ENTRY = ".atl/";
 const WATCH_DEBOUNCE_MS = 500;
-const REGISTRY_SCHEMA_VERSION = 6;
+const REGISTRY_SCHEMA_VERSION = 7;
 const NO_SKILL_REGISTRY_FLAG = "no-skill-registry";
 const NO_SKILL_REGISTRY_ENV = "GENTLE_PI_NO_SKILL_REGISTRY";
 const LEGACY_PROJECT_REGISTRY_REL_PATH = ".pi/extensions/skill-registry.ts";
@@ -253,7 +253,14 @@ async function fingerprint(files: string[]): Promise<string> {
 	for (const file of files) {
 		try {
 			const info = await stat(file);
-			lines.push(`${file}:${info.mtimeMs}:${info.size}`);
+			let contentHash: string;
+			try {
+				contentHash = createHash("sha1").update(await readFile(file)).digest("hex");
+			} catch {
+				lines.push(`${file}:unreadable`);
+				continue;
+			}
+			lines.push(`${file}:${info.mtimeMs}:${info.size}:${contentHash}`);
 		} catch {
 			lines.push(`${file}:missing`);
 		}
@@ -526,6 +533,7 @@ export const __testing = {
 	normalizeSkillDescription,
 	parseFrontmatter,
 	renderRegistry,
+	regenerateRegistry,
 	shouldSkipSkillRegistryStartup,
 	shouldSkipDuplicateExtensionLoad,
 	startSkillRegistryWatcher,

package/extensions/startup-banner.ts

@@ -553,7 +553,9 @@ export default function (pi: ExtensionAPI) {
         if (selected.startsWith("Rose:")) config.showRose = !config.showRose;
         else if (selected.startsWith("Text logo:")) config.showTextLogo = !config.showTextLogo;
         else if (selected.startsWith("Color:")) {
-          config.color = await ctx.ui.select("Startup banner color", [...BANNER_COLORS]) as BannerColor;
+          const color = await ctx.ui.select("Startup banner color", [...BANNER_COLORS]);
+          if (!color) return;
+          config.color = color as BannerColor;
         }
         await writeBannerConfig(config);
         notifyBannerConfig(ctx, config);
@@ -577,9 +579,13 @@ export default function (pi: ExtensionAPI) {
       handler: async (args, ctx) => {
         const config = await readBannerConfig();
         const requested = String(args ?? "").trim() as BannerColor;
-        config.color = BANNER_COLORS.includes(requested)
-          ? requested
-          : await ctx.ui.select("Startup banner color", [...BANNER_COLORS]) as BannerColor;
+        if (BANNER_COLORS.includes(requested)) {
+          config.color = requested;
+        } else {
+          const selected = await ctx.ui.select("Startup banner color", [...BANNER_COLORS]);
+          if (!selected) return;
+          config.color = selected as BannerColor;
+        }
         await writeBannerConfig(config);
         notifyBannerConfig(ctx, config);
       },

package/lib/gentle-ai-binary.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import {
 	GENTLE_AI_INSTALL_METHOD,
@@ -7,6 +8,7 @@ import {
 	GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,
 	GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH,
 	GENTLE_AI_WINDOWS_SOURCE_TAG,
+	INSTALLER_VERSION,
 	isGentleAiWindowsGoVersionSupported,
 	isWindowsGoSumdbSourceTarget,
 	resolveGentleAiReleaseAsset,
@@ -14,7 +16,10 @@ import {
 import { fileURLToPath } from "node:url";
 
 export const GENTLE_AI_BINARY_MISSING_CODE = "package-local-binary-missing";
-export const GENTLE_AI_VERSION = "2.2.2";
+// Derived from the one authoritative pinned version in
+// scripts/gentle-ai-installer.mjs rather than repeating the literal here, so
+// the two can never independently drift apart the way they once did.
+export const GENTLE_AI_VERSION = INSTALLER_VERSION;
 
 export class PackageLocalGentleAiBinaryMissingError extends Error {
 	readonly code = GENTLE_AI_BINARY_MISSING_CODE;
@@ -42,6 +47,165 @@ function sha256(value: Buffer): string {
 	return createHash("sha256").update(value).digest("hex");
 }
 
+// ---------------------------------------------------------------------------
+// Dev-binary override — the maintainer field-test lane.
+//
+// Two explicit activation paths, in precedence order:
+//   1. GENTLE_PI_GENTLE_AI_DEV_BINARY (session override, absolute path), then
+//   2. the persistent registration file at
+//      <GENTLE_PI_CONFIG_HOME|~/.pi/gentle-ai>/dev-binary.json with the strict
+//      shape {"schema":"gentle-pi.dev-binary/v1","path":"<absolute path>"}.
+//
+// The registration deliberately pins no digest: it is the unpinned field-test
+// mode, and the binary at that path changes on every rebuild. Every resolution
+// re-validates the file and recomputes the sha256, so a rebuilt binary is
+// followed automatically with a fresh digest and no re-registration.
+//
+// Guardrails per resolution: absolute path, regular non-symlink file, POSIX
+// executable. Any failure — including a malformed registration document or a
+// registered-but-missing binary — is a typed error naming its origin, never a
+// silent fallback to the pinned binary: silently running the pin while the
+// maintainer believes he is field-testing main is the worst possible outcome.
+// With neither activation path present, the pinned supply-chain resolution
+// below stays byte-identical.
+// ---------------------------------------------------------------------------
+
+export const GENTLE_AI_DEV_BINARY_ENV = "GENTLE_PI_GENTLE_AI_DEV_BINARY";
+export const GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA = "gentle-pi.dev-binary/v1";
+export const GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE = "dev-binary-override-invalid";
+
+export interface GentleAiDevBinaryEnvironment {
+	env: Record<string, string | undefined>;
+	home: string;
+}
+
+export interface GentleAiDevBinaryOverride {
+	source: "env" | "registration";
+	/** The env var name or registration file path that selected this binary. */
+	origin: string;
+	path: string;
+	sha256: string;
+}
+
+export class GentleAiDevBinaryOverrideError extends Error {
+	readonly code = GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE;
+	readonly source: "env" | "registration";
+	readonly origin: string;
+	constructor(source: "env" | "registration", origin: string, reason: string) {
+		super(`${GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE}: ${origin} ${reason}. Fix or remove the override; the pinned binary is never used silently while an override is declared.`);
+		this.name = "GentleAiDevBinaryOverrideError";
+		this.source = source;
+		this.origin = origin;
+	}
+}
+
+let devBinaryEnvironmentTestingOverlay: GentleAiDevBinaryEnvironment | undefined;
+
+/** Testing-only environment overlay; production code never calls this. */
+export function setGentleAiDevBinaryEnvironmentForTesting(environment: GentleAiDevBinaryEnvironment | undefined): void {
+	devBinaryEnvironmentTestingOverlay = environment;
+}
+
+function ambientDevBinaryEnvironment(): GentleAiDevBinaryEnvironment {
+	return devBinaryEnvironmentTestingOverlay ?? { env: process.env, home: homedir() };
+}
+
+export function gentleAiDevBinaryRegistrationPath(environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment()): string {
+	const configHome = environment.env.GENTLE_PI_CONFIG_HOME ?? join(environment.home, ".pi", "gentle-ai");
+	return join(configHome, "dev-binary.json");
+}
+
+function validateDevBinary(source: "env" | "registration", origin: string, path: string, platform: string): GentleAiDevBinaryOverride {
+	if (typeof path !== "string" || path.length === 0) throw new GentleAiDevBinaryOverrideError(source, origin, "declares an empty dev binary path");
+	if (!isAbsolute(path)) throw new GentleAiDevBinaryOverrideError(source, origin, `must name an absolute path, received "${path}"`);
+	let details: ReturnType<typeof lstatSync>;
+	try {
+		details = lstatSync(path);
+	} catch {
+		throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which does not exist`);
+	}
+	if (!details.isFile() || details.isSymbolicLink()) throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which is not a regular non-symlink file`);
+	if (platform !== "win32" && (details.mode & 0o111) === 0) throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which is not a POSIX executable`);
+	let digest: string;
+	try {
+		digest = sha256(readFileSync(path));
+	} catch {
+		throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which could not be read`);
+	}
+	return { source, origin, path, sha256: digest };
+}
+
+function readDevBinaryRegistration(registrationPath: string): string {
+	let contents: string;
+	try {
+		contents = readFileSync(registrationPath, "utf8");
+	} catch {
+		throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "could not be read");
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(contents);
+	} catch {
+		throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "is not valid JSON");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "must be a JSON object");
+	const record = parsed as Record<string, unknown>;
+	const keys = Object.keys(record).sort();
+	if (keys.length !== 2 || keys[0] !== "path" || keys[1] !== "schema") throw new GentleAiDevBinaryOverrideError("registration", registrationPath, `must carry exactly the keys "schema" and "path"`);
+	if (record.schema !== GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA) throw new GentleAiDevBinaryOverrideError("registration", registrationPath, `must declare schema ${GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA}`);
+	if (typeof record.path !== "string" || record.path.length === 0) throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "must declare a non-empty string path");
+	return record.path;
+}
+
+/**
+ * Resolves the active dev-binary override, if any. Returns undefined only when
+ * neither activation path is present; a present-but-invalid override always
+ * throws a typed GentleAiDevBinaryOverrideError naming its origin.
+ */
+export function resolveGentleAiDevBinaryOverride(
+	environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment(),
+	platform = process.platform,
+): GentleAiDevBinaryOverride | undefined {
+	const envValue = environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	if (envValue !== undefined && envValue.length > 0) return validateDevBinary("env", GENTLE_AI_DEV_BINARY_ENV, envValue, platform);
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	if (!existsSync(registrationPath)) return undefined;
+	return validateDevBinary("registration", registrationPath, readDevBinaryRegistration(registrationPath), platform);
+}
+
+/**
+ * Cheap presence probe: is a dev-binary override declared at all? Used by the
+ * native CLI to select the unpinned version gate without hashing the binary.
+ * Declared-but-invalid still counts as configured — the resolution path will
+ * fail loudly with the typed error instead of quietly using the pin.
+ */
+export function gentleAiDevBinaryOverrideConfigured(environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment()): boolean {
+	const envValue = environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	if (envValue !== undefined && envValue.length > 0) return true;
+	return existsSync(gentleAiDevBinaryRegistrationPath(environment));
+}
+
+/** Validates and persistently registers a dev binary; returns the fresh override. */
+export function registerGentleAiDevBinary(
+	path: string,
+	environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment(),
+	platform = process.platform,
+): { registrationPath: string; override: GentleAiDevBinaryOverride } {
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	const validated = validateDevBinary("registration", registrationPath, path, platform);
+	mkdirSync(dirname(registrationPath), { recursive: true });
+	writeFileSync(registrationPath, `${JSON.stringify({ schema: GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA, path })}\n`);
+	return { registrationPath, override: validated };
+}
+
+/** Deletes the persistent registration; returns whether one existed. */
+export function unregisterGentleAiDevBinary(environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment()): boolean {
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	if (!existsSync(registrationPath)) return false;
+	rmSync(registrationPath);
+	return true;
+}
+
 function isConfined(path: string, directory: string): boolean {
 	const relativePath = relative(directory, path);
 	return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
@@ -106,7 +270,14 @@ export function resolveGentleAiBinary(
 	packageRoot = dirname(dirname(fileURLToPath(import.meta.url))),
 	platform = process.platform,
 	readBinary: (path: string) => Buffer = readFileSync,
+	environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment(),
 ): string {
+	// The explicit dev-binary override wins over the pinned supply-chain path.
+	// Its typed errors propagate: a declared override never falls back to the
+	// pin. Without a declared override this call returns undefined and the
+	// pinned resolution below is byte-identical to the pre-override behavior.
+	const override = resolveGentleAiDevBinaryOverride(environment, platform);
+	if (override !== undefined) return override.path;
 	const binaryPath = gentleAiBinaryPath(packageRoot, platform);
 	const versionDirectory = dirname(binaryPath);
 	const manifestPath = join(versionDirectory, "integrity.json");

package/lib/git-commit-transaction.ts

@@ -77,8 +77,8 @@ interface CommitTransactionRecordBody {
 	command: string;
 	command_hash: string;
 	arguments: readonly string[];
-	original_head: string;
-	original_head_tree: string;
+	original_head?: string;
+	original_head_tree?: string;
 	original_index_tree: string;
 	original_index_hash: string;
 	authorized_pre_hook_tree: string;
@@ -180,13 +180,68 @@ function absoluteGitPath(cwd: string, name: string): string {
 	return isAbsolute(value) ? value : resolve(cwd, value);
 }
 
+// Runs a probe that may exit nonzero as an expected signal (absent ref, unborn
+// HEAD). Returns the exit status and trimmed stdout. Timeout and I/O failures
+// propagate instead of being masked as a status, so callers fail closed.
+function probeGit(cwd: string, args: readonly string[]): { status: number; stdout: string } {
+	try {
+		const stdout = execFileSync("git", args, {
+			cwd,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "pipe"],
+			timeout: GIT_TIMEOUT_MS,
+			windowsHide: true,
+		});
+		return { status: 0, stdout: stdout.trim() };
+	} catch (error) {
+		const detail = error as NodeJS.ErrnoException & { killed?: boolean; status?: number; stdout?: string | Buffer };
+		if (detail.code === "ETIMEDOUT" || detail.killed === true) throw error;
+		if (typeof detail.status === "number") return { status: detail.status, stdout: typeof detail.stdout === "string" ? detail.stdout.trim() : "" };
+		throw error;
+	}
+}
+
+// Resolves HEAD to a commit SHA, or undefined only for a valid unborn symbolic
+// HEAD (symbolic HEAD pointing at a branch with no commits). Timeout, I/O,
+// corruption, and all other failures propagate (fail closed on uncertain HEAD
+// state). Classification uses status-based probes, not localized stderr text.
+function resolveHead(cwd: string): string | undefined {
+	try {
+		return git(cwd, ["rev-parse", "--verify", "HEAD"]);
+	} catch (error) {
+		const detail = error as NodeJS.ErrnoException & { killed?: boolean };
+		if (detail.code === "ETIMEDOUT" || detail.killed === true) throw error;
+		if (typeof detail.status !== "number") throw error;
+		const symbolic = probeGit(cwd, ["symbolic-ref", "--quiet", "HEAD"]);
+		if (symbolic.status !== 0) throw error;
+		// show-ref --verify --quiet distinguishes: status 1 = ref absent (valid
+		// unborn), status 0 = ref exists and valid (rethrow original HEAD error),
+		// any other status (128, etc.) = corruption/missing object (fail closed).
+		const refProbe = probeGit(cwd, ["show-ref", "--verify", "--quiet", symbolic.stdout]);
+		if (refProbe.status === 1) return undefined;
+		throw error;
+	}
+}
+
 function repositoryBinding(cwd: string): RepositoryBinding {
 	const root = realpathSync(git(cwd, ["rev-parse", "--show-toplevel"]));
 	const commonDirValue = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
 	const gitDirValue = git(root, ["rev-parse", "--path-format=absolute", "--git-dir"]);
 	const commonDir = realpathSync(commonDirValue);
 	const gitDir = realpathSync(gitDirValue);
-	const roots = git(root, ["rev-list", "--max-parents=0", "HEAD"]).split(/\r?\n/).filter(Boolean).sort();
+	// Preserve the durable repository identity across the unborn-handling
+	// upgrade: a born repository keeps the byte-for-byte previous formula
+	// `sha256(canonicalJson({ common_directory: commonDir, roots }))` with
+	// `roots` the sorted root commits reachable from HEAD. An unborn
+	// repository has no HEAD, so `rev-list HEAD` cannot run; resolveHead
+	// already classifies HEAD state and propagates timeout/corruption/I/O
+	// failures rather than masking them, so the unborn branch gets a
+	// deterministic safe roots representation (the empty set) without
+	// hiding real errors.
+	const head = resolveHead(root);
+	const roots = head === undefined
+		? []
+		: git(root, ["rev-list", "--max-parents=0", "HEAD"]).split(/\r?\n/).filter(Boolean).sort();
 	const repositoryId = sha256(canonicalJson({ common_directory: commonDir, roots }));
 	const worktreeKey = sha256(gitDir).slice("sha256:".length, "sha256:".length + 24);
 	const stateDir = join(commonDir, "gentle-pi", "commit-transactions", worktreeKey);
@@ -241,11 +296,11 @@ function decodeRecord(value: unknown): CommitTransactionRecord {
 	if (record.schema !== TRANSACTION_SCHEMA) throw new Error("commit transaction record schema is incompatible");
 	for (const field of [
 		"transaction_id", "repository_id", "repository_root", "common_directory", "git_directory",
-		"command", "command_hash", "original_head", "original_head_tree", "original_index_tree",
+		"command", "command_hash", "original_index_tree",
 		"original_index_hash", "authorized_pre_hook_tree", "state", "created_at", "updated_at", "record_hash",
 	]) if (typeof record[field] !== "string" || (record[field] as string).length === 0) throw new Error(`commit transaction record ${field} is invalid`);
 	if (!isStringArray(record.arguments) || !isStringArray(record.invocation_ids) || !isStringArray(record.lineage_history)) throw new Error("commit transaction record arrays are invalid");
-	for (const field of ["post_hook_tree", "post_hook_index_hash", "authorized_tree", "authority_revision", "gate_context_hash", "committed_head", "committed_tree", "git_created_head", "git_created_tree", "error"] as const) {
+	for (const field of ["original_head", "original_head_tree", "post_hook_tree", "post_hook_index_hash", "authorized_tree", "authority_revision", "gate_context_hash", "committed_head", "committed_tree", "git_created_head", "git_created_tree", "error"] as const) {
 		if (record[field] !== undefined && typeof record[field] !== "string") throw new Error(`commit transaction record ${field} is invalid`);
 	}
 	if (!Number.isSafeInteger(record.hook_runs) || (record.hook_runs as number) < 0) throw new Error("commit transaction hook count is invalid");
@@ -437,7 +492,7 @@ export function prepareCommitTransactionInvocation(input: {
 }): CommitTransactionInvocation {
 	assertSafeCommitArguments(input.arguments);
 	const binding = repositoryBinding(input.cwd);
-	const head = git(binding.root, ["rev-parse", "--verify", "HEAD"]);
+	const head = resolveHead(binding.root);
 	const currentTree = git(binding.root, ["write-tree"]);
 	if (currentTree !== input.authorization.intendedTree) throw new Error("commit transaction pre-hook index no longer matches its controller authorization");
 	let transactionId = randomUUID();
@@ -540,7 +595,7 @@ function validateNativeTree(result: NativeValidateResult, lineageId: string, tre
 }
 
 function createRecord(binding: RepositoryBinding, invocation: CommitTransactionInvocation, now: () => Date): CommitTransactionRecord {
-	const head = git(binding.root, ["rev-parse", "--verify", "HEAD"]);
+	const head = resolveHead(binding.root);
 	const tree = git(binding.root, ["write-tree"]);
 	if (tree !== invocation.authorization.intendedTree) throw new Error("commit transaction index changed after controller authorization");
 	const timestamp = now().toISOString();
@@ -555,7 +610,7 @@ function createRecord(binding: RepositoryBinding, invocation: CommitTransactionI
 		command_hash: invocation.commandHash,
 		arguments: [...invocation.arguments],
 		original_head: head,
-		original_head_tree: git(binding.root, ["rev-parse", "--verify", "HEAD^{tree}"]),
+		original_head_tree: head === undefined ? undefined : git(binding.root, ["rev-parse", "--verify", "HEAD^{tree}"]),
 		original_index_tree: tree,
 		original_index_hash: indexFingerprint(binding.root),
 		authorized_pre_hook_tree: invocation.authorization.intendedTree,
@@ -571,13 +626,17 @@ function createRecord(binding: RepositoryBinding, invocation: CommitTransactionI
 function assertInvocationMatches(binding: RepositoryBinding, record: CommitTransactionRecord, invocation: CommitTransactionInvocation): void {
 	if (record.repository_id !== binding.repositoryId || record.repository_root !== binding.root || record.common_directory !== binding.commonDir || record.git_directory !== binding.gitDir) throw new Error("commit transaction repository identity changed");
 	if (record.transaction_id !== invocation.transactionId || record.command_hash !== invocation.commandHash || record.command !== invocation.command || canonicalJson(record.arguments) !== canonicalJson(invocation.arguments)) throw new Error("commit transaction exact retry does not match the durable command intent");
-	if (git(binding.root, ["rev-parse", "--verify", "HEAD"]) !== record.original_head) throw new Error("commit transaction HEAD changed before reconciliation");
+	if (resolveHead(binding.root) !== record.original_head) throw new Error("commit transaction HEAD changed before reconciliation");
 }
 
 function recoverCompletedCommit(binding: RepositoryBinding, record: CommitTransactionRecord, now: () => Date): CommitTransactionResult | undefined {
 	if (record.state !== COMMIT_TRANSACTION_STATE.COMMIT_RUNNING && record.state !== COMMIT_TRANSACTION_STATE.COMMITTED) return undefined;
-	const head = git(binding.root, ["rev-parse", "--verify", "HEAD"]);
+	const head = resolveHead(binding.root);
 	if (head === record.original_head) return undefined;
+	if (head === undefined) {
+		transition(binding, record, COMMIT_TRANSACTION_STATE.INCIDENT, { error: "HEAD disappeared during commit transaction" }, now);
+		throw new Error("commit transaction incident: HEAD disappeared during commit; publication remains blocked");
+	}
 	const tree = git(binding.root, ["rev-parse", "--verify", "HEAD^{tree}"]);
 	if (record.git_created_head === undefined || record.git_created_tree === undefined || head !== record.git_created_head || tree !== record.git_created_tree || tree !== record.authorized_tree) {
 		transition(binding, record, COMMIT_TRANSACTION_STATE.INCIDENT, { committed_head: head, committed_tree: tree, error: "HEAD identity differs from the exact Git-created authorized commit" }, now);
@@ -684,14 +743,15 @@ export async function runGitCommitTransaction(
 		const commit = await runProcess("git", ["-c", `core.hooksPath=${proxy}`, "commit", ...invocation.arguments], binding.root);
 		if (dependencies.failpoint === "after-commit-before-proof") throw new Error("commit transaction test interruption after Git returned");
 		record = readRecord(binding.activePath) ?? record;
-		const head = git(binding.root, ["rev-parse", "--verify", "HEAD"]);
-		const headTree = git(binding.root, ["rev-parse", "--verify", "HEAD^{tree}"]);
-		if (head !== record.original_head && head === record.git_created_head && headTree === record.git_created_tree && headTree === record.authorized_tree) {
+		const head = resolveHead(binding.root);
+		const headTree = head === undefined ? undefined : git(binding.root, ["rev-parse", "--verify", "HEAD^{tree}"]);
+		const headChanged = head !== record.original_head;
+		if (headChanged && head === record.git_created_head && headTree === record.git_created_tree && headTree === record.authorized_tree) {
 			const committed = transition(binding, record, COMMIT_TRANSACTION_STATE.COMMITTED, { committed_head: head, committed_tree: headTree, ...(commit.code === 0 && commit.signal === null ? {} : { error: `Git returned ${commit.signal ?? `exit ${commit.code}`} after creating the authorized commit` }) }, now);
 			archive(binding, committed);
-			return { transactionId: record.transaction_id, status: "committed", head, tree: headTree };
+			return { transactionId: record.transaction_id, status: "committed", head: head!, tree: headTree! };
 		}
-		if (head !== record.original_head) {
+		if (headChanged) {
 			transition(binding, record, COMMIT_TRANSACTION_STATE.INCIDENT, { committed_head: head, committed_tree: headTree, error: "HEAD identity differs from the exact Git-created authorized commit" }, now);
 			throw new Error("commit transaction incident: HEAD identity changed after Git created the authorized commit; publication remains blocked");
 		}
@@ -701,7 +761,7 @@ export async function runGitCommitTransaction(
 		if (record !== undefined && dependencies.signal?.aborted === true && existsSync(binding.activePath)) {
 			try {
 				const active = readRecord(binding.activePath) ?? record;
-				if (git(binding.root, ["rev-parse", "--verify", "HEAD"]) === active.original_head) transition(binding, active, COMMIT_TRANSACTION_STATE.INTERRUPTED, { error: "commit transaction was cancelled" }, now);
+				if (resolveHead(binding.root) === active.original_head) transition(binding, active, COMMIT_TRANSACTION_STATE.INTERRUPTED, { error: "commit transaction was cancelled" }, now);
 			} catch { /* retain the earlier durable state */ }
 		}
 		throw error;
@@ -782,7 +842,7 @@ export function abandonCommitTransaction(cwd: string): CommitTransactionRecord {
 	try {
 		const record = readRecord(binding.activePath);
 		if (record === undefined) throw new Error("active commit transaction disappeared during recovery");
-		if (git(binding.root, ["rev-parse", "--verify", "HEAD"]) !== record.original_head) throw new Error("cannot abandon a commit transaction after HEAD changed; reconcile the committed tree instead");
+		if (resolveHead(binding.root) !== record.original_head) throw new Error("cannot abandon a commit transaction after HEAD changed; reconcile the committed tree instead");
 		const abandoned = transition(binding, record, COMMIT_TRANSACTION_STATE.ABANDONED, { error: "explicitly abandoned without changing HEAD or index" }, now);
 		return archive(binding, abandoned);
 	} finally { releaseLock(); }