@oh-my-pi/pi-coding-agent 15.10.11 → 15.11.0

package/src/tools/job.ts

@@ -3,7 +3,7 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { prompt } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
-import { type AsyncJob, type AsyncJobManager, isBackgroundJobSupportEnabled } from "../async";
+import type { AsyncJob, AsyncJobManager } from "../async";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import jobDescription from "../prompts/tools/job.md" with { type: "text" };
@@ -65,6 +65,19 @@ export interface JobToolDetails {
 	cancelled?: { id: string; status: CancelStatus }[];
 }
 
+/**
+ * A poll snapshot where every watched job is still running and nothing was
+ * cancelled — pure "still waiting" noise once a newer poll exists. The TUI
+ * keeps such a block un-finalized (displaceable) so a follow-up `job` call
+ * replaces it instead of stacking another waiting frame in the transcript.
+ */
+export function isWaitingPollDetails(details: unknown): boolean {
+	const d = details as JobToolDetails | undefined;
+	if (!d || !Array.isArray(d.jobs) || d.jobs.length === 0) return false;
+	if (d.cancelled?.length) return false;
+	return d.jobs.every(job => job?.status === "running");
+}
+
 export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 	readonly name = "job";
 	readonly approval = "read" as const;
@@ -78,11 +91,6 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 		this.description = prompt.render(jobDescription);
 	}
 
-	static createIf(session: ToolSession): JobTool | null {
-		if (!isBackgroundJobSupportEnabled(session.settings)) return null;
-		return new JobTool(session);
-	}
-
 	async execute(
 		_toolCallId: string,
 		params: JobParams,
@@ -378,6 +386,30 @@ function statusToColor(status: JobSnapshot["status"]): ToolUIColor {
 	}
 }
 
+/**
+ * Task job results are delivered in the model-facing `<task-result>` envelope
+ * (prompts/tools/task-summary.md) so the parent agent can parse status and the
+ * `agent://` pointer. The wrapper markup is noise to a human — preview the
+ * inner <output>/<preview> body instead.
+ */
+function stripTaskResultEnvelope(text: string): string {
+	if (!text.startsWith("<task-result")) return text;
+	const body = /<(output|preview)(?:\s[^>]*)?>\n?([\s\S]*?)\n?<\/\1>/.exec(text)?.[2];
+	return body?.trim() || text;
+}
+
+/**
+ * Pretty-printed JSON output wastes the collapsed one-line preview on a lone
+ * "{" — flatten structured-looking bodies onto a single line. Slice first:
+ * downstream truncation keeps at most a few hundred columns, so collapsing
+ * whitespace across a multi-KB body would be pure waste.
+ */
+function flattenStructuredPreview(text: string): string {
+	const first = text[0];
+	if (first !== "{" && first !== "[") return text;
+	return text.slice(0, PREVIEW_LINES_EXPANDED * PREVIEW_LINE_WIDTH * 2).replace(/\s+/g, " ");
+}
+
 function describeTarget(args: JobRenderArgs | undefined): string {
 	const poll = args?.poll ?? [];
 	const cancel = args?.cancel ?? [];
@@ -494,7 +526,9 @@ export const jobToolRenderer = {
 								lines.push(`  ${uiTheme.fg("toolOutput", visibleLabelLines[i]!)}`);
 							}
 
-							const preview = job.errorText?.trim() || job.resultText?.trim();
+							const preview = flattenStructuredPreview(
+								stripTaskResultEnvelope(job.errorText?.trim() || job.resultText?.trim() || ""),
+							);
 							if (preview) {
 								const maxLines = expanded ? PREVIEW_LINES_EXPANDED : PREVIEW_LINES_COLLAPSED;
 								const previewLines = getPreviewLines(preview, maxLines, PREVIEW_LINE_WIDTH, Ellipsis.Unicode);

package/src/tools/read.ts

@@ -736,6 +736,17 @@ interface ResolvedSqliteReadPath {
 /** Per-execute memo of suffix-glob lookups; `null` records a confirmed miss. */
 type SuffixMatchCache = Map<string, { absolutePath: string; displayPath: string } | null>;
 
+/**
+ * Repeated whole-file reads of the same path pin stale copies in context.
+ * From this per-session read count onward, file reads carry a trailing nudge
+ * to prefer narrower re-reads.
+ */
+const REPEAT_READ_NOTICE_THRESHOLD = 3;
+
+function formatRepeatReadNotice(count: number): string {
+	return `[note: read #${count} of this file this session — after edits, prefer the context echoed in the edit result or a narrow range re-read]`;
+}
+
 /**
  * Read tool implementation.
  *
@@ -754,6 +765,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 	readonly #autoResizeImages: boolean;
 	readonly #defaultLimit: number;
 	readonly #inspectImageEnabled: boolean;
+	/** Successful file reads per resolved base path (selector stripped) this session. */
+	readonly #readCounts = new Map<string, number>();
 
 	constructor(private readonly session: ToolSession) {
 		const displayMode = resolveFileDisplayMode(session);
@@ -772,6 +785,19 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		});
 	}
 
+	/**
+	 * Count a file read of `absolutePath` and return the repeat-read nudge once
+	 * the per-session count reaches {@link REPEAT_READ_NOTICE_THRESHOLD}.
+	 * Non-file sources (URLs, internal resources, directories, archives,
+	 * SQLite, images) are never counted.
+	 */
+	#repeatReadNotice(absolutePath: string): string | undefined {
+		const count = (this.#readCounts.get(absolutePath) ?? 0) + 1;
+		this.#readCounts.set(absolutePath, count);
+		if (count < REPEAT_READ_NOTICE_THRESHOLD) return undefined;
+		return formatRepeatReadNotice(count);
+	}
+
 	async #tryReadDelimitedPaths(
 		readPath: string,
 		signal?: AbortSignal,
@@ -948,6 +974,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			ignoreResultLimits?: boolean;
 			raw?: boolean;
 			immutable?: boolean;
+			/** Trailing repeat-read nudge; appended at the very end of the text. */
+			repeatNotice?: string;
 		},
 	): AgentToolResult<ReadToolDetails> {
 		const displayMode = resolveFileDisplayMode(this.session, { raw: options.raw, immutable: options.immutable });
@@ -1092,6 +1120,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					: formatLineEntries(buildLineEntries(endLine), startLineDisplay);
 		}
 
+		if (options.repeatNotice) {
+			outputText += `\n${options.repeatNotice}`;
+		}
 		resultBuilder.text(outputText);
 		if (truncationInfo) {
 			resultBuilder.truncation(truncationInfo.result, truncationInfo.options);
@@ -1117,6 +1148,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			entityLabel: string;
 			raw?: boolean;
 			immutable?: boolean;
+			/** Trailing repeat-read nudge; appended at the very end of the text. */
+			repeatNotice?: string;
 		},
 	): AgentToolResult<ReadToolDetails> {
 		const displayMode = resolveFileDisplayMode(this.session, { raw: options.raw, immutable: options.immutable });
@@ -1177,8 +1210,11 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			const bound = range.endLine !== undefined ? `${range.startLine}-${range.endLine}` : `${range.startLine}`;
 			notices.push(`[Range ${bound} is beyond end of ${options.entityLabel} (${totalLines} lines total); skipped]`);
 		}
-		const finalText =
+		let finalText =
 			notices.length > 0 ? (outputText ? `${outputText}\n${notices.join("\n")}` : notices.join("\n")) : outputText;
+		if (options.repeatNotice) {
+			finalText = finalText ? `${finalText}\n${options.repeatNotice}` : options.repeatNotice;
+		}
 		resultBuilder.text(finalText);
 		return resultBuilder.done();
 	}
@@ -1196,6 +1232,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		parsed: ParsedSelector,
 		displayMode: { hashLines: boolean; lineNumbers: boolean },
 		suffixResolution: { from: string; to: string } | undefined,
+		repeatNotice: string | undefined,
 		signal: AbortSignal | undefined,
 	): Promise<{
 		outputText: string;
@@ -1215,6 +1252,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					sourcePath: absolutePath,
 					entityLabel: "file",
 					raw: rawSelector,
+					repeatNotice,
 				});
 				if (suffixResolution) {
 					const notice = `[Path '${suffixResolution.from}' not found; resolved to '${suffixResolution.to}' via suffix match]`;
@@ -1896,6 +1934,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		let details: ReadToolDetails = {};
 		let sourcePath: string | undefined;
 		let columnTruncated = 0;
+		let repeatNotice: string | undefined;
 		let truncationInfo:
 			| { result: TruncationResult; options: { direction: "head"; startLine?: number; totalFileLines?: number } }
 			| undefined;
@@ -1960,11 +1999,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 		} else if (isNotebookPath(absolutePath) && !isRawSelector(parsed)) {
 			const notebookText = await readEditableNotebookText(absolutePath, localReadPath);
+			repeatNotice = this.#repeatReadNotice(absolutePath);
 			if (isMultiRange(parsed) && parsed.kind === "lines") {
 				return this.#buildInMemoryMultiRangeResult(notebookText, parsed.ranges, {
 					details: { resolvedPath: absolutePath },
 					sourcePath: absolutePath,
 					entityLabel: "notebook",
+					repeatNotice,
 				});
 			}
 			const { offset, limit } = selToOffsetLimit(parsed);
@@ -1972,11 +2013,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				details: { resolvedPath: absolutePath },
 				sourcePath: absolutePath,
 				entityLabel: "notebook",
+				repeatNotice,
 			});
 		} else if (shouldConvertWithMarkit) {
 			// Convert document via markit.
 			const result = await convertFileWithMarkit(absolutePath, signal);
 			if (result.ok) {
+				repeatNotice = this.#repeatReadNotice(absolutePath);
 				// Route the converted markdown through the in-memory text builder
 				// so line-range selectors (`file.pdf:50-100`, `:5-16,40-80`) and
 				// raw mode apply against the converted output. Without this,
@@ -1987,6 +2030,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						details: { resolvedPath: absolutePath },
 						sourcePath: absolutePath,
 						entityLabel: "document",
+						repeatNotice,
 					});
 				}
 				const { offset, limit } = selToOffsetLimit(parsed);
@@ -1995,6 +2039,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					sourcePath: absolutePath,
 					entityLabel: "document",
 					raw: isRawSelector(parsed),
+					repeatNotice,
 				});
 			} else if (result.error) {
 				content = [{ type: "text", text: `[Cannot read ${ext} file: ${result.error || "conversion failed"}]` }];
@@ -2002,6 +2047,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				content = [{ type: "text", text: `[Cannot read ${ext} file: conversion failed]` }];
 			}
 		} else {
+			repeatNotice = this.#repeatReadNotice(absolutePath);
 			if (
 				parsed.kind === "none" &&
 				this.session.settings.get("read.summarize.enabled") &&
@@ -2043,6 +2089,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						parsed,
 						displayMode,
 						suffixResolution,
+						repeatNotice,
 						undefined, // plain-file read: deterministic and fast, never abort mid-read
 					);
 					if (multiResult.bridgeResult) return multiResult.bridgeResult;
@@ -2066,6 +2113,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 								sourcePath: absolutePath,
 								entityLabel: "file",
 								raw: isRawSelector(parsed),
+								repeatNotice,
 							});
 							if (suffixResolution) {
 								const notice = `[Path '${suffixResolution.from}' not found; resolved to '${suffixResolution.to}' via suffix match]`;
@@ -2367,6 +2415,14 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				content = [{ type: "text", text: notice }, ...content];
 			}
 		}
+		if (repeatNotice) {
+			// Trailing nudge goes at the very end of the textual result so it never
+			// disturbs hashline tag headers or inline notices.
+			const lastText = content.findLast((c): c is TextContent => c.type === "text");
+			if (lastText) {
+				lastText.text = `${lastText.text}\n${repeatNotice}`;
+			}
+		}
 		const resultBuilder = toolResult(details).content(content);
 		if (sourcePath) {
 			resultBuilder.sourcePath(sourcePath);

package/src/tools/renderers.ts

@@ -21,6 +21,7 @@ import { evalToolRenderer } from "./eval-render";
 import { findToolRenderer } from "./find";
 import { githubToolRenderer } from "./gh-renderer";
 import { inspectImageToolRenderer } from "./inspect-image-renderer";
+import { ircToolRenderer } from "./irc";
 import { jobToolRenderer } from "./job";
 import { recallToolRenderer, reflectToolRenderer, retainToolRenderer } from "./memory-render";
 import { readToolRenderer } from "./read";
@@ -58,6 +59,7 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	search: searchToolRenderer as ToolRenderer,
 	lsp: lspToolRenderer as ToolRenderer,
 	inspect_image: inspectImageToolRenderer as ToolRenderer,
+	irc: ircToolRenderer as ToolRenderer,
 	read: readToolRenderer as ToolRenderer,
 	job: jobToolRenderer as ToolRenderer,
 	resolve: resolveToolRenderer as ToolRenderer,

package/src/tools/resolve.ts

@@ -241,7 +241,10 @@ export const resolveToolRenderer = {
 		const isApply = action === "apply" && !result.isError;
 		const isFailedApply = action === "apply" && result.isError;
 		const bgColor = result.isError ? "error" : isApply ? "success" : "warning";
-		const icon = isApply ? uiTheme.styledSymbol("tool.resolve", "accent") : uiTheme.status.error;
+		// Bare symbol: the line is wrapped in inverse(fg(...)), so any embedded fg
+		// reset (styledSymbol/status glyphs carry their own \x1b[39m) would drop the
+		// inverse block back to the default background mid-line.
+		const icon = uiTheme.symbol(isApply ? "tool.resolve" : "status.error");
 		const verb = isApply ? "Accept" : isFailedApply ? "Failed" : "Discard";
 		const separator = ": ";
 		const separatorIndex = label.indexOf(separator);

package/src/utils/commit-message-generator.ts

@@ -115,6 +115,7 @@ export async function generateCommitMessage(
 					apiKey: registry.resolver(candidate.model.provider, {
 						sessionId,
 						baseUrl: candidate.model.baseUrl,
+						modelId: candidate.model.id,
 					}),
 					maxTokens,
 					reasoning: toReasoningEffort(candidate.thinkingLevel),

package/src/utils/git.ts

@@ -27,6 +27,7 @@ export interface GitRepository {
 	gitEntryPath: string;
 	headPath: string;
 	repoRoot: string;
+	isReftable?: boolean;
 }
 
 export interface GitStatusSummary {
@@ -476,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);
@@ -560,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;
@@ -572,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;
@@ -997,7 +1225,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;
 			}
@@ -1095,7 +1323,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;
 	},
@@ -1104,7 +1332,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;
@@ -1397,9 +1625,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);
@@ -1409,6 +1640,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);
@@ -1416,7 +1650,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;
@@ -1445,13 +1679,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"], {
@@ -1462,6 +1693,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);
@@ -1471,11 +1715,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);
 }
 
 // ════════════════════════════════════════════════════════════════════════════