gentle-pi 2.1.2 → 2.2.0

package/lib/review-relay-contract.ts

@@ -0,0 +1,16 @@
+// gentle-pi.review-relay/v1 — the Pi host relay handshake (gentle-pi#311 P4,
+// provider side gentle-ai#3249/#3254).
+//
+// gentle-ai admits `pi` as a host-mediated runtime identity only when the
+// launcher that relays the invocation declares this exact contract through
+// this exact environment variable. Any other value (or none) keeps Pi
+// fail-closed at admission, before any repository, target, or authority work.
+// That refusal is correct provider behavior and is never worked around here;
+// the single central gentle-ai process runner injects this declaration on
+// every invocation the extension makes.
+//
+// Both values are compiled constants: the contract identity is versioned by
+// release, never by configuration.
+
+export const GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV = "GENTLE_PI_REVIEW_RELAY_CONTRACT";
+export const GENTLE_PI_REVIEW_RELAY_CONTRACT = "gentle-pi.review-relay/v1";

package/lib/sdd-preflight.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -394,6 +394,57 @@ function copyDirectoryFiles(
 	return { copied, skipped };
 }
 
+// Assets retired by gentle-pi#311 P5: the Pi-owned adversarial review actors.
+// The refuter and validator verdicts now execute through Go-owned pi
+// processes via provider-rendered self-contained vectors, so these agent
+// definitions have no runtime consumer. The migration manifests under
+// assets/migrations are append-only legacy-hash HISTORY (adoption evidence
+// for force-installs) with no removal semantics, so history stays untouched
+// and retirement happens here: an installed copy is deleted only when its
+// content hash proves package ownership (current manifest or legacy
+// history); user-modified copies are left in place and only lose managed
+// ownership.
+const RETIRED_MANAGED_ASSETS = Object.freeze([
+	"agents/review-refuter.md",
+	"agents/review-validator.md",
+]);
+
+function removeRetiredManagedAssets(
+	agentHome: string,
+	manifest: ManagedAssetsManifest,
+): void {
+	let legacyHashes: Record<string, readonly string[]> | undefined;
+	for (const ownershipKey of RETIRED_MANAGED_ASSETS) {
+		const installedPath = join(agentHome, ...ownershipKey.split("/"));
+		if (!existsSync(installedPath)) {
+			delete manifest.assets[ownershipKey];
+			continue;
+		}
+		let installedContent: string | undefined;
+		try {
+			installedContent = readFileSync(installedPath, "utf8");
+		} catch {
+			installedContent = undefined;
+		}
+		if (installedContent === undefined) continue;
+		const installedHash = managedAssetHash(installedContent);
+		const managed = manifest.assets[ownershipKey] === installedHash;
+		const legacy = (legacyHashes ??= readLegacyManagedAssetHashes())[ownershipKey]?.includes(
+			managedAssetHash(legacyComparableAssetContent(ownershipKey, installedContent)),
+		) === true;
+		if (managed || legacy) {
+			try {
+				rmSync(installedPath);
+			} catch {
+				continue;
+			}
+		}
+		// Managed copies are gone; user-modified copies stay but stop being
+		// package-managed either way.
+		delete manifest.assets[ownershipKey];
+	}
+}
+
 export function installSddAssets(
 	_cwd: string,
 	force: boolean,
@@ -407,6 +458,7 @@ export function installSddAssets(
 			(cachedLegacyAssetHashes ??= readLegacyManagedAssetHashes());
 	}
 	const manifest = readManagedAssetsManifest(manifestPath);
+	removeRetiredManagedAssets(agentHome, manifest);
 	const agents = copyDirectoryFiles(
 		join(ASSETS_DIR, "agents"),
 		join(agentHome, "agents"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",
@@ -39,10 +39,13 @@
   "scripts": {
 	"build:transaction-runner": "node scripts/build-git-commit-transaction-runner.mjs --write",
 	"check:transaction-runner": "node scripts/build-git-commit-transaction-runner.mjs --check",
+	"check:provider-contract": "node scripts/check-provider-contract.mjs",
     "postinstall": "node scripts/install-gentle-ai.mjs",
-    "test": "node --experimental-strip-types --test tests/*.test.ts && pnpm run test:harness",
+    "test": "node --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",
     "test:harness": "node --experimental-strip-types tests/runtime-harness.mjs",
     "test:dev-binary": "node --experimental-strip-types --test tests/devbinary/*.devtest.ts",
+    "test:cross-lane": "node tests/crosslane/cross-lane.mjs",
+    "test:maintainer": "node --experimental-strip-types --test tests/maintainer/*.maintest.ts",
 	"test:packed-runner": "node scripts/test-packed-runner.mjs",
     "prepack": "pnpm test && node scripts/verify-package-files.mjs",
     "prepublishOnly": "pnpm test && node scripts/verify-package-files.mjs && pnpm run test:packed-runner"

package/runtime/gentle-ai-binary.mjs

@@ -1,6 +1,7 @@
 // Generated by scripts/build-git-commit-transaction-runner.mjs. Do not edit.
 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,
@@ -8,6 +9,7 @@ import {
 	GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,
 	GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH,
 	GENTLE_AI_WINDOWS_SOURCE_TAG,
+	INSTALLER_VERSION,
 	isGentleAiWindowsGoVersionSupported,
 	isWindowsGoSumdbSourceTarget,
 	resolveGentleAiReleaseAsset,
@@ -15,7 +17,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 {
 	         code = GENTLE_AI_BINARY_MISSING_CODE;
@@ -43,6 +48,165 @@ function sha256(value        )         {
 	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 class GentleAiDevBinaryOverrideError extends Error {
+	         code = GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE;
+	         source                        ;
+	         origin        ;
+	constructor(source                        , origin        , reason        ) {
+		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                                          ;
+
+/** Testing-only environment overlay; production code never calls this. */
+export function setGentleAiDevBinaryEnvironmentForTesting(environment                                          )       {
+	devBinaryEnvironmentTestingOverlay = environment;
+}
+
+function ambientDevBinaryEnvironment()                               {
+	return devBinaryEnvironmentTestingOverlay ?? { env: process.env, home: homedir() };
+}
+
+export function gentleAiDevBinaryRegistrationPath(environment                               = ambientDevBinaryEnvironment())         {
+	const configHome = environment.env.GENTLE_PI_CONFIG_HOME ?? join(environment.home, ".pi", "gentle-ai");
+	return join(configHome, "dev-binary.json");
+}
+
+function validateDevBinary(source                        , origin        , path        , platform        )                            {
+	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                              ;
+	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        ;
+	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        )         {
+	let contents        ;
+	try {
+		contents = readFileSync(registrationPath, "utf8");
+	} catch {
+		throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "could not be read");
+	}
+	let parsed         ;
+	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                           ;
+	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                               = ambientDevBinaryEnvironment(),
+	platform = process.platform,
+)                                        {
+	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                               = ambientDevBinaryEnvironment())          {
+	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        ,
+	environment                               = ambientDevBinaryEnvironment(),
+	platform = process.platform,
+)                                                                    {
+	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                               = ambientDevBinaryEnvironment())          {
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	if (!existsSync(registrationPath)) return false;
+	rmSync(registrationPath);
+	return true;
+}
+
 function isConfined(path        , directory        )          {
 	const relativePath = relative(directory, path);
 	return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
@@ -107,7 +271,14 @@ export function resolveGentleAiBinary(
 	packageRoot = dirname(dirname(fileURLToPath(import.meta.url))),
 	platform = process.platform,
 	readBinary                           = readFileSync,
+	environment                               = ambientDevBinaryEnvironment(),
 )         {
+	// 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/runtime/git-commit-transaction.mjs

@@ -181,13 +181,68 @@ function absoluteGitPath(cwd        , name        )         {
 	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        , args                   )                                     {
+	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                                                                                           ;
+		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        )                     {
+	try {
+		return git(cwd, ["rev-parse", "--verify", "HEAD"]);
+	} catch (error) {
+		const detail = error                                                ;
+		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        )                    {
 	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);
@@ -242,11 +297,11 @@ function decodeRecord(value         )                          {
 	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]          ).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"]         ) {
+	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"]         ) {
 		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          ) < 0) throw new Error("commit transaction hook count is invalid");
@@ -438,7 +493,7 @@ export function prepareCommitTransactionInvocation(input
  )                              {
 	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();
@@ -541,7 +596,7 @@ function validateNativeTree(result                      , lineageId        , tre
 }
 
 function createRecord(binding                   , invocation                             , now            )                          {
-	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();
@@ -556,7 +611,7 @@ function createRecord(binding                   , invocation
 		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,
@@ -572,13 +627,17 @@ function createRecord(binding                   , invocation
 function assertInvocationMatches(binding                   , record                         , invocation                             )       {
 	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                   , record                         , now            )                                      {
 	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);
@@ -685,14 +744,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");
 		}
@@ -702,7 +762,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;
@@ -783,7 +843,7 @@ export function abandonCommitTransaction(cwd        )                          {
 	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(); }