@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/utils/enhanced-paste.ts

@@ -0,0 +1,230 @@
+import type { ImageContent } from "@prometheus-ai/ai";
+
+const OSC5522_PREFIX = "\x1b]5522;";
+const OSC_TERMINATOR_ST = "\x1b\\";
+const OSC_TERMINATOR_BEL = "\x07";
+const PASTE_EVENT_NAME_BASE64 = Buffer.from("Paste event", "utf8").toString("base64");
+
+const IMAGE_MIME_PRIORITY = ["image/png", "image/jpeg", "image/webp", "image/gif"] as const;
+const TEXT_MIME_TYPE = "text/plain";
+/** Kitty's "give me the list of available MIME types" sentinel — see `TARGETS_MIME` in `kitty/clipboard.py`. */
+const MIME_LISTING_TARGET = ".";
+
+type PasteReadKind = "image" | "text";
+
+export interface Osc5522Packet {
+	metadata: Map<string, string>;
+	payload: string;
+}
+
+interface PasteListingState {
+	phase: "listing";
+	mimes: string[];
+	kittyDotPayload?: true;
+	pw?: string;
+	loc?: string;
+}
+
+interface PasteReadState {
+	phase: "reading";
+	kind: PasteReadKind;
+	mimeType: string;
+	chunks: string[];
+}
+
+type PasteState = PasteListingState | PasteReadState;
+
+export interface EnhancedPasteHandlers {
+	write(data: string): void;
+	pasteText(text: string): void;
+	pasteImage(image: ImageContent): void | Promise<void>;
+	showStatus(message: string): void;
+}
+
+export function isOsc5522Packet(data: string): boolean {
+	return data.startsWith(OSC5522_PREFIX) && (data.endsWith(OSC_TERMINATOR_ST) || data.endsWith(OSC_TERMINATOR_BEL));
+}
+
+function decodeBase64Utf8(value: string): string | undefined {
+	try {
+		return Buffer.from(value, "base64").toString("utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+function parseMetadata(raw: string): Map<string, string> {
+	const metadata = new Map<string, string>();
+	for (const part of raw.split(":")) {
+		const eq = part.indexOf("=");
+		if (eq <= 0) continue;
+		metadata.set(part.slice(0, eq), part.slice(eq + 1));
+	}
+	return metadata;
+}
+
+export function parseOsc5522Packet(data: string): Osc5522Packet | undefined {
+	if (!isOsc5522Packet(data)) return undefined;
+	const bodyEnd = data.endsWith(OSC_TERMINATOR_BEL) ? data.length - 1 : data.length - OSC_TERMINATOR_ST.length;
+	const body = data.slice(OSC5522_PREFIX.length, bodyEnd);
+	const separator = body.indexOf(";");
+	const metadataRaw = separator === -1 ? body : body.slice(0, separator);
+	const payload = separator === -1 ? "" : body.slice(separator + 1);
+	return { metadata: parseMetadata(metadataRaw), payload };
+}
+
+function choosePasteMime(mimes: readonly string[]): { kind: PasteReadKind; mimeType: string } | undefined {
+	for (const mimeType of IMAGE_MIME_PRIORITY) {
+		if (mimes.includes(mimeType)) return { kind: "image", mimeType };
+	}
+	return mimes.includes(TEXT_MIME_TYPE) ? { kind: "text", mimeType: TEXT_MIME_TYPE } : undefined;
+}
+
+export class EnhancedPasteController {
+	#state: PasteState | undefined;
+	#handlers: EnhancedPasteHandlers;
+
+	constructor(handlers: EnhancedPasteHandlers) {
+		this.#handlers = handlers;
+	}
+
+	enable(): void {
+		this.#handlers.write("\x1b[?5522h");
+	}
+
+	disable(): void {
+		this.#handlers.write("\x1b[?5522l");
+		this.#state = undefined;
+	}
+
+	handleInput(data: string): boolean {
+		const packet = parseOsc5522Packet(data);
+		if (!packet) return false;
+		void this.#handlePacket(packet);
+		return true;
+	}
+
+	async #handlePacket(packet: Osc5522Packet): Promise<void> {
+		const type = packet.metadata.get("type");
+		if (type !== "read") return;
+
+		const status = packet.metadata.get("status");
+		if (status === "OK") {
+			this.#handleOk(packet);
+			return;
+		}
+		if (status === "DATA") {
+			this.#handleData(packet);
+			return;
+		}
+		if (status === "DONE") {
+			await this.#handleDone();
+			return;
+		}
+		if (status) {
+			this.#state = undefined;
+			this.#handlers.showStatus(`Enhanced paste failed: ${status}`);
+		}
+	}
+
+	#handleOk(packet: Osc5522Packet): void {
+		if (this.#state?.phase === "reading") return;
+		const loc = packet.metadata.get("loc");
+		this.#state = {
+			phase: "listing",
+			mimes: [],
+			pw: packet.metadata.get("pw"),
+			loc: loc === "primary" ? loc : undefined,
+		};
+	}
+
+	#handleData(packet: Osc5522Packet): void {
+		const state = this.#state;
+		if (!state) return;
+		const encodedMime = packet.metadata.get("mime");
+		if (!encodedMime) return;
+		const mimeType = decodeBase64Utf8(encodedMime);
+		if (!mimeType) return;
+
+		if (state.phase === "listing") {
+			// Kitty (as of writing) implements the "list available MIME types"
+			// response shape by sending a single DATA packet with `mime="."` and
+			// the available types packed into the payload as a whitespace-
+			// separated list (see `fulfill_read_request` in
+			// kovidgoyal/kitty:kitty/clipboard.py). The 5522-mode ancillary
+			// spec instead encodes each type as its own DATA packet with an
+			// empty payload. Support both — fall through to the per-packet
+			// form when the dot sentinel has no payload, or when the packet
+			// already names a concrete MIME type.
+			if (mimeType === MIME_LISTING_TARGET) {
+				if (!packet.payload) return;
+				const listing = decodeBase64Utf8(packet.payload);
+				if (!listing) return;
+				state.kittyDotPayload = true;
+				for (const candidate of listing.split(/\s+/)) {
+					if (candidate && candidate !== MIME_LISTING_TARGET) state.mimes.push(candidate);
+				}
+				return;
+			}
+			state.mimes.push(mimeType);
+			return;
+		}
+
+		if (state.mimeType === mimeType && packet.payload) {
+			state.chunks.push(packet.payload);
+		}
+	}
+
+	async #handleDone(): Promise<void> {
+		const state = this.#state;
+		if (!state) return;
+		if (state.phase === "listing") {
+			this.#finishListing(state);
+			return;
+		}
+		this.#state = undefined;
+		const bytes = Buffer.concat(state.chunks.map(chunk => Buffer.from(chunk, "base64")));
+		if (bytes.byteLength === 0) {
+			this.#handlers.showStatus("Clipboard paste was empty");
+			return;
+		}
+		if (state.kind === "text") {
+			this.#handlers.pasteText(bytes.toString("utf8"));
+			return;
+		}
+		await this.#handlers.pasteImage({
+			type: "image",
+			data: bytes.toString("base64"),
+			mimeType: state.mimeType,
+		});
+	}
+
+	#finishListing(state: PasteListingState): void {
+		const selected = choosePasteMime(state.mimes);
+		if (!selected) {
+			this.#state = undefined;
+			this.#handlers.showStatus("Clipboard paste has no supported text or image data");
+			return;
+		}
+
+		this.#state = {
+			phase: "reading",
+			kind: selected.kind,
+			mimeType: selected.mimeType,
+			chunks: [],
+		};
+
+		const encodedMime = Buffer.from(selected.mimeType, "utf8").toString("base64");
+		const metadata = ["type=read"];
+		if (state.loc) metadata.push(`loc=${state.loc}`);
+		if (state.pw) {
+			metadata.push(`pw=${state.pw}`, `name=${PASTE_EVENT_NAME_BASE64}`);
+		}
+		if (state.kittyDotPayload) {
+			this.#handlers.write(`${OSC5522_PREFIX}${metadata.join(":")};${encodedMime}${OSC_TERMINATOR_BEL}`);
+			return;
+		}
+		metadata.push(`mime=${encodedMime}`);
+		this.#handlers.write(`${OSC5522_PREFIX}${metadata.join(":")}${OSC_TERMINATOR_BEL}`);
+	}
+}

package/src/utils/file-mentions.ts

@@ -5,12 +5,14 @@
  * we automatically inject the file contents as a FileMentionMessage
  * so the agent doesn't need to read them manually.
  */
+
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import type { AgentMessage } from "@prometheus-ai/agent-core";
 import type { ImageContent } from "@prometheus-ai/ai";
 import { formatHashlineHeader, formatNumberedLines, type SnapshotStore } from "@prometheus-ai/hashline";
 import { formatAge, formatBytes, readImageMetadata } from "@prometheus-ai/utils";
+import { canonicalSnapshotKey } from "../edit/file-snapshot-store";
 import { normalizeToLF } from "../edit/normalize";
 import type { FileMentionMessage } from "../session/messages";
 import {
@@ -259,7 +261,7 @@ export async function generateFileMentionMessages(
 			const normalized = snapshotStore ? normalizeToLF(content) : content;
 			let { output, lineCount } = buildTextOutput(normalized);
 			if (snapshotStore) {
-				const tag = snapshotStore.record(absolutePath, normalized);
+				const tag = snapshotStore.record(canonicalSnapshotKey(absolutePath), normalized);
 				output = `${formatHashlineHeader(resolvedPath, tag)}\n${formatNumberedLines(output)}`;
 			}
 			files.push({ path: resolvedPath, content: output, lineCount });

package/src/utils/git.ts

@@ -27,6 +27,7 @@ export interface GitRepository {
 	gitEntryPath: string;
 	headPath: string;
 	repoRoot: string;
+	isReftable?: boolean;
 }
 
 export interface GitStatusSummary {
@@ -45,6 +46,10 @@ export interface StageHunksOptions {
 	readonly rawDiff?: string;
 	readonly signal?: AbortSignal;
 }
+export interface HunkSelectionValidationError {
+	readonly path: string;
+	readonly message: string;
+}
 
 export interface DiffOptions {
 	readonly allowFailure?: boolean;
@@ -472,6 +477,31 @@ async function resolveCommonDir(gitDir: string): Promise<string> {
 	if (!relative) return gitDir;
 	return path.resolve(gitDir, relative);
 }
+function isLinkedWorktree(repository: GitRepository): boolean {
+	return (
+		repository.gitDir !== repository.commonDir &&
+		getEntryTypeSync(path.join(repository.gitDir, "commondir")) === "file"
+	);
+}
+
+async function isLinkedWorktreeAsync(repository: GitRepository): Promise<boolean> {
+	return (
+		repository.gitDir !== repository.commonDir &&
+		(await getEntryType(path.join(repository.gitDir, "commondir"))) === "file"
+	);
+}
+
+function primaryRootFromRepositorySync(repository: GitRepository): string {
+	if (path.basename(repository.commonDir) === ".git") return path.dirname(repository.commonDir);
+	if (isLinkedWorktree(repository)) return repository.commonDir;
+	return repository.repoRoot;
+}
+
+async function primaryRootFromRepository(repository: GitRepository): Promise<string> {
+	if (path.basename(repository.commonDir) === ".git") return path.dirname(repository.commonDir);
+	if (await isLinkedWorktreeAsync(repository)) return repository.commonDir;
+	return repository.repoRoot;
+}
 
 function resolveRepoFromEntrySync(repoRoot: string, gitEntryPath: string, entryType: EntryType): GitRepository | null {
 	const gitDir = resolveGitDirSync(gitEntryPath, entryType);
@@ -556,7 +586,174 @@ function parsePackedRefs(content: string | null, targetRef: string): string | nu
 	return null;
 }
 
+function stripGitConfigComments(line: string): string {
+	let clean = "";
+	let inQuotes = false;
+	for (let i = 0; i < line.length; i++) {
+		const char = line[i];
+		if (char === '"') {
+			inQuotes = !inQuotes;
+			clean += char;
+		} else if (!inQuotes && (char === ";" || char === "#")) {
+			break;
+		} else {
+			clean += char;
+		}
+	}
+	return clean.trim();
+}
+
+function parseGitConfigHasReftable(content: string): boolean {
+	let inExtensions = false;
+	for (const line of content.split("\n")) {
+		const trimmed = stripGitConfigComments(line);
+		if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+			const section = trimmed.slice(1, -1).trim().toLowerCase();
+			inExtensions = section === "extensions";
+		} else if (inExtensions) {
+			const eqIndex = trimmed.indexOf("=");
+			if (eqIndex !== -1) {
+				const key = trimmed.slice(0, eqIndex).trim().toLowerCase();
+				let value = trimmed.slice(eqIndex + 1).trim();
+				if (key === "refstorage") {
+					if (value.startsWith('"') && value.endsWith('"')) {
+						value = value.slice(1, -1).trim();
+					}
+					const lowerValue = value.toLowerCase();
+					if (lowerValue === "reftable" || lowerValue.startsWith("reftable:")) {
+						return true;
+					}
+				}
+			}
+		}
+	}
+	return false;
+}
+
+function isReftableRepoSync(repository: GitRepository): boolean {
+	if (repository.isReftable !== undefined) return repository.isReftable;
+	const configPath = path.join(repository.commonDir, "config");
+	const content = readOptionalTextSync(configPath);
+	repository.isReftable = content ? parseGitConfigHasReftable(content) : false;
+	return repository.isReftable;
+}
+
+async function isReftableRepo(repository: GitRepository): Promise<boolean> {
+	if (repository.isReftable !== undefined) return repository.isReftable;
+	const configPath = path.join(repository.commonDir, "config");
+	const content = await readOptionalText(configPath);
+	repository.isReftable = content ? parseGitConfigHasReftable(content) : false;
+	return repository.isReftable;
+}
+
+async function resolveHeadStateReftable(repository: GitRepository, signal?: AbortSignal): Promise<GitHeadState | null> {
+	throwIfAborted(signal);
+	const symResult = await git(repository.repoRoot, ["symbolic-ref", "HEAD"], { readOnly: true, signal }).catch(err => {
+		if (signal?.aborted || (err instanceof Error && (err.name === "AbortError" || err.name === "ToolAbortError"))) {
+			throw err;
+		}
+		return null;
+	});
+	throwIfAborted(signal);
+	const revResult = await git(repository.repoRoot, ["rev-parse", "--verify", "HEAD"], {
+		readOnly: true,
+		signal,
+	}).catch(err => {
+		if (signal?.aborted || (err instanceof Error && (err.name === "AbortError" || err.name === "ToolAbortError"))) {
+			throw err;
+		}
+		return null;
+	});
+	const commit = revResult && revResult.exitCode === 0 ? revResult.stdout.trim() || null : null;
+
+	if (symResult && symResult.exitCode === 0) {
+		const ref = symResult.stdout.trim();
+		const branchName = ref.startsWith(LOCAL_BRANCH_PREFIX) ? ref.slice(LOCAL_BRANCH_PREFIX.length) : null;
+		return {
+			...repository,
+			kind: "ref",
+			ref,
+			branchName,
+			commit,
+			headContent: `${HEAD_REF_PREFIX} ${ref}`,
+		};
+	}
+
+	return {
+		...repository,
+		kind: "detached",
+		commit,
+		headContent: commit || "",
+	};
+}
+
+function resolveHeadStateReftableSync(repository: GitRepository): GitHeadState | null {
+	ensureAvailable();
+	const symArgs = withShortLivedGitConfig(withNoOptionalLocks(["symbolic-ref", "HEAD"]));
+	const symResult = Bun.spawnSync(["git", ...symArgs], {
+		cwd: repository.repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+		windowsHide: true,
+	});
+
+	const revArgs = withShortLivedGitConfig(withNoOptionalLocks(["rev-parse", "--verify", "HEAD"]));
+	const revResult = Bun.spawnSync(["git", ...revArgs], {
+		cwd: repository.repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+		windowsHide: true,
+	});
+	const commit = revResult.exitCode === 0 ? new TextDecoder().decode(revResult.stdout).trim() || null : null;
+
+	if (symResult.exitCode === 0) {
+		const ref = new TextDecoder().decode(symResult.stdout).trim();
+		const branchName = ref.startsWith(LOCAL_BRANCH_PREFIX) ? ref.slice(LOCAL_BRANCH_PREFIX.length) : null;
+		return {
+			...repository,
+			kind: "ref",
+			ref,
+			branchName,
+			commit,
+			headContent: `${HEAD_REF_PREFIX} ${ref}`,
+		};
+	}
+
+	return {
+		...repository,
+		kind: "detached",
+		commit,
+		headContent: commit || "",
+	};
+}
+
 function readRefSync(repository: GitRepository, targetRef: string): string | null {
+	if (isReftableRepoSync(repository)) {
+		ensureAvailable();
+		const symArgs = withShortLivedGitConfig(withNoOptionalLocks(["symbolic-ref", targetRef]));
+		const symResult = Bun.spawnSync(["git", ...symArgs], {
+			cwd: repository.repoRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+			windowsHide: true,
+		});
+		if (symResult.exitCode === 0) {
+			const stdoutText = new TextDecoder().decode(symResult.stdout).trim();
+			return `${HEAD_REF_PREFIX} ${stdoutText}`;
+		}
+		const revArgs = withShortLivedGitConfig(withNoOptionalLocks(["rev-parse", "--verify", targetRef]));
+		const revResult = Bun.spawnSync(["git", ...revArgs], {
+			cwd: repository.repoRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+			windowsHide: true,
+		});
+		if (revResult.exitCode === 0) {
+			return new TextDecoder().decode(revResult.stdout).trim() || null;
+		}
+		return null;
+	}
+
 	for (const dir of getRefLookupDirs(repository)) {
 		const value = normalizeRefValue(readOptionalTextSync(path.join(dir, targetRef)));
 		if (value) return value;
@@ -568,7 +765,42 @@ function readRefSync(repository: GitRepository, targetRef: string): string | nul
 	return null;
 }
 
-async function readRef(repository: GitRepository, targetRef: string): Promise<string | null> {
+async function readRef(repository: GitRepository, targetRef: string, signal?: AbortSignal): Promise<string | null> {
+	if (await isReftableRepo(repository)) {
+		throwIfAborted(signal);
+		const symResult = await git(repository.repoRoot, ["symbolic-ref", targetRef], { readOnly: true, signal }).catch(
+			err => {
+				if (
+					signal?.aborted ||
+					(err instanceof Error && (err.name === "AbortError" || err.name === "ToolAbortError"))
+				) {
+					throw err;
+				}
+				return null;
+			},
+		);
+		if (symResult && symResult.exitCode === 0) {
+			return `${HEAD_REF_PREFIX} ${symResult.stdout.trim()}`;
+		}
+		throwIfAborted(signal);
+		const revResult = await git(repository.repoRoot, ["rev-parse", "--verify", targetRef], {
+			readOnly: true,
+			signal,
+		}).catch(err => {
+			if (
+				signal?.aborted ||
+				(err instanceof Error && (err.name === "AbortError" || err.name === "ToolAbortError"))
+			) {
+				throw err;
+			}
+			return null;
+		});
+		if (revResult && revResult.exitCode === 0) {
+			return revResult.stdout.trim() || null;
+		}
+		return null;
+	}
+
 	for (const dir of getRefLookupDirs(repository)) {
 		const value = normalizeRefValue(await readOptionalText(path.join(dir, targetRef)));
 		if (value) return value;
@@ -678,6 +910,43 @@ function selectHunks(file: FileHunks, selector: HunkSelection["hunks"]): FileHun
 	return file.hunks;
 }
 
+export function createHunkSelectionValidator(
+	rawDiff: string,
+): (selections: readonly HunkSelection[]) => HunkSelectionValidationError[] {
+	const fileDiffMap = new Map(parseFileDiffs(rawDiff).map(entry => [entry.filename, entry]));
+	return selections => validateHunkSelectionsFromMap(fileDiffMap, selections);
+}
+
+function validateHunkSelectionsFromMap(
+	fileDiffMap: ReadonlyMap<string, FileDiff>,
+	selections: readonly HunkSelection[],
+): HunkSelectionValidationError[] {
+	const errors: HunkSelectionValidationError[] = [];
+
+	for (const selection of selections) {
+		const fileDiff = fileDiffMap.get(selection.path);
+		if (!fileDiff) continue;
+		if (selection.hunks.type === "all") continue;
+		if (fileDiff.isBinary) {
+			errors.push({ path: selection.path, message: `Cannot select hunks for binary file ${selection.path}` });
+			continue;
+		}
+		const selected = selectHunks(parseFileHunks(fileDiff), selection.hunks);
+		if (selected.length === 0) {
+			errors.push({ path: selection.path, message: `No hunks selected for ${selection.path}` });
+		}
+	}
+
+	return errors;
+}
+
+export function validateHunkSelections(
+	rawDiff: string,
+	selections: readonly HunkSelection[],
+): HunkSelectionValidationError[] {
+	return createHunkSelectionValidator(rawDiff)(selections);
+}
+
 function parseStatusPorcelain(text: string): GitStatusSummary {
 	let staged = 0;
 	let unstaged = 0;
@@ -857,9 +1126,14 @@ export async function commit(cwd: string, message: string, options: CommitOption
 	return runChecked(cwd, args, { signal: options.signal, stdin: message });
 }
 
-/** Push the current branch. */
+/** Push the current branch (branch-scoped: never follows tags). */
 export async function push(cwd: string, options: PushOptions = {}): Promise<void> {
-	const args = ["push"];
+	// `--no-follow-tags` overrides a user's `push.followTags = true`, which
+	// would otherwise ride every reachable annotated tag along with the
+	// branch — rejected refs ("permission denied") on remotes the user
+	// cannot tag (e.g. PR-head forks), failing the call after the branch
+	// itself already updated. Tool pushes push exactly the named refspec.
+	const args = ["push", "--no-follow-tags"];
 	if (options.forceWithLease) args.push("--force-with-lease");
 	if (options.remote) args.push(options.remote);
 	if (options.refspec) args.push(options.refspec);
@@ -956,7 +1230,7 @@ export const branch = {
 		const repository = await resolveRepository(cwd);
 		if (repository) {
 			for (const refPath of DEFAULT_BRANCH_REFS) {
-				const target = await readRef(repository, refPath);
+				const target = await readRef(repository, refPath, signal);
 				const branchName = parseDefaultBranchRef(refPath, target);
 				if (branchName) return branchName;
 			}
@@ -1054,7 +1328,7 @@ export const ref = {
 	async exists(cwd: string, refName: string, signal?: AbortSignal): Promise<boolean> {
 		if (refName === "HEAD") return (await head.sha(cwd, signal)) !== null;
 		const repository = await resolveRepository(cwd);
-		if (repository && refName.startsWith("refs/")) return (await readRef(repository, refName)) !== null;
+		if (repository && refName.startsWith("refs/")) return (await readRef(repository, refName, signal)) !== null;
 		const result = await git(cwd, ["show-ref", "--verify", "--quiet", refName], { readOnly: true, signal });
 		return result.exitCode === 0;
 	},
@@ -1063,7 +1337,7 @@ export const ref = {
 	async resolve(cwd: string, refName: string, signal?: AbortSignal): Promise<string | null> {
 		if (refName === "HEAD") return head.sha(cwd, signal);
 		const repository = await resolveRepository(cwd);
-		if (repository && refName.startsWith("refs/")) return readRef(repository, refName);
+		if (repository && refName.startsWith("refs/")) return readRef(repository, refName, signal);
 		const result = await git(cwd, ["rev-parse", refName], { readOnly: true, signal });
 		if (result.exitCode !== 0) return null;
 		return result.stdout.trim() || null;
@@ -1356,9 +1630,12 @@ export const ls = {
 
 export const head = {
 	/** Full HEAD state (branch, commit, repo info). */
-	async resolve(cwd: string): Promise<GitHeadState | null> {
+	async resolve(cwd: string, signal?: AbortSignal): Promise<GitHeadState | null> {
 		const repository = await resolveRepository(cwd);
 		if (!repository) return null;
+		if (await isReftableRepo(repository)) {
+			return resolveHeadStateReftable(repository, signal);
+		}
 		const content = await readOptionalText(repository.headPath);
 		if (content === null) return null;
 		return parseHeadState(repository, content);
@@ -1368,6 +1645,9 @@ export const head = {
 	resolveSync(cwd: string): GitHeadState | null {
 		const repository = resolveRepositorySync(cwd);
 		if (!repository) return null;
+		if (isReftableRepoSync(repository)) {
+			return resolveHeadStateReftableSync(repository);
+		}
 		const content = readOptionalTextSync(repository.headPath);
 		if (content === null) return null;
 		return parseHeadStateSync(repository, content);
@@ -1375,7 +1655,7 @@ export const head = {
 
 	/** Current HEAD commit SHA. */
 	async sha(cwd: string, signal?: AbortSignal): Promise<string | null> {
-		const headState = await head.resolve(cwd);
+		const headState = await head.resolve(cwd, signal);
 		if (headState?.commit) return headState.commit;
 		const result = await git(cwd, ["rev-parse", "HEAD"], { readOnly: true, signal });
 		if (result.exitCode !== 0) return null;
@@ -1404,13 +1684,10 @@ export const repo = {
 		return result.stdout.trim() || null;
 	},
 
-	/** Resolve the primary repository root (not a worktree — the main checkout). */
+	/** Resolve the primary checkout root, or the shared common dir for bare-repo worktrees. */
 	async primaryRoot(cwd: string, signal?: AbortSignal): Promise<string | null> {
 		const repository = await resolveRepository(cwd);
-		if (repository) {
-			if (path.basename(repository.commonDir) === ".git") return path.dirname(repository.commonDir);
-			return repository.repoRoot;
-		}
+		if (repository) return primaryRootFromRepository(repository);
 		const repoRoot = await repo.root(cwd, signal);
 		if (!repoRoot) return null;
 		const commonDir = await runText(repoRoot, ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
@@ -1421,6 +1698,19 @@ export const repo = {
 		return repoRoot;
 	},
 
+	/**
+	 * Sync sibling of {@link primaryRoot}. Resolves only via on-disk `.git`/
+	 * `commondir` walking — no subprocess fallback — so it stays usable from
+	 * paths where async I/O is impractical (e.g. `computeBankScope`). Returns
+	 * `null` when `cwd` is outside a repository. Bare-repo worktrees resolve to
+	 * the shared common dir (`foo.git`) because they have no primary checkout.
+	 */
+	primaryRootSync(cwd: string): string | null {
+		const repository = resolveRepositorySync(cwd);
+		if (!repository) return null;
+		return primaryRootFromRepositorySync(repository);
+	},
+
 	/** Full GitRepository metadata (sync). */
 	resolveSync(cwd: string): GitRepository | null {
 		return resolveRepositorySync(cwd);
@@ -1430,11 +1720,21 @@ export const repo = {
 	resolve(cwd: string): Promise<GitRepository | null> {
 		return resolveRepository(cwd);
 	},
+
+	/** Check if the repository uses the reftable reference storage format (sync). */
+	isReftableSync(repository: GitRepository): boolean {
+		return isReftableRepoSync(repository);
+	},
+
+	/** Check if the repository uses the reftable reference storage format. */
+	isReftable(repository: GitRepository): Promise<boolean> {
+		return isReftableRepo(repository);
+	},
 };
 
 // Helper used during head resolution — defined here to reference `head` namespace.
-async function resolveHead(cwd: string): Promise<GitHeadState | null> {
-	return head.resolve(cwd);
+async function resolveHead(cwd: string, signal?: AbortSignal): Promise<GitHeadState | null> {
+	return head.resolve(cwd, signal);
 }
 
 // ════════════════════════════════════════════════════════════════════════════