@oh-my-pi/pi-coding-agent 15.7.3 → 15.7.6

package/src/tools/find.ts

@@ -192,7 +192,12 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				if (hasGlobPathChars(rawPattern)) {
 					throw new ToolError(`Glob patterns are not supported for internal URLs: ${rawPattern}`);
 				}
-				const resource = await internalRouter.resolve(rawPattern);
+				const resource = await internalRouter.resolve(rawPattern, {
+					cwd: this.session.cwd,
+					settings: this.session.settings,
+					signal,
+					localProtocolOptions: this.session.localProtocolOptions,
+				});
 				if (!resource.sourcePath) {
 					throw new ToolError(`Cannot find internal URL without a backing file: ${rawPattern}`);
 				}
@@ -443,10 +448,14 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 // =============================================================================
 
 interface FindRenderArgs {
-	paths?: string[];
+	paths?: string | string[];
 	limit?: number;
 }
 
+function formatFindRenderPaths(paths: FindRenderArgs["paths"]): string | undefined {
+	return Array.isArray(paths) ? paths.join(", ") : paths;
+}
+
 const COLLAPSED_LIST_LIMIT = PREVIEW_LIMITS.COLLAPSED_ITEMS;
 
 export const findToolRenderer = {
@@ -456,7 +465,7 @@ export const findToolRenderer = {
 		if (args.limit !== undefined) meta.push(`limit:${args.limit}`);
 
 		const text = renderStatusLine(
-			{ icon: "pending", title: "Find", description: args.paths?.join(", ") || "*", meta },
+			{ icon: "pending", title: "Find", description: formatFindRenderPaths(args.paths) || "*", meta },
 			uiTheme,
 		);
 		return new Text(text, 0, 0);
@@ -493,7 +502,7 @@ export const findToolRenderer = {
 				{
 					icon: "success",
 					title: "Find",
-					description: args?.paths?.join(", "),
+					description: formatFindRenderPaths(args?.paths),
 					meta: [formatCount("file", lines.length)],
 				},
 				uiTheme,
@@ -528,7 +537,7 @@ export const findToolRenderer = {
 
 		if (fileCount === 0) {
 			const header = renderStatusLine(
-				{ icon: "warning", title: "Find", description: args?.paths?.join(", "), meta: ["0 files"] },
+				{ icon: "warning", title: "Find", description: formatFindRenderPaths(args?.paths), meta: ["0 files"] },
 				uiTheme,
 			);
 			const lines = [header, formatEmptyMessage("No files found", uiTheme)];
@@ -539,7 +548,12 @@ export const findToolRenderer = {
 		if (details?.scopePath) meta.push(`in ${details.scopePath}`);
 		if (truncated) meta.push(uiTheme.fg("warning", "truncated"));
 		const header = renderStatusLine(
-			{ icon: truncated ? "warning" : "success", title: "Find", description: args?.paths?.join(", "), meta },
+			{
+				icon: truncated ? "warning" : "success",
+				title: "Find",
+				description: formatFindRenderPaths(args?.paths),
+				meta,
+			},
 			uiTheme,
 		);
 

package/src/tools/gh.ts

@@ -75,6 +75,7 @@ const GH_PR_FIELDS = [
 	"labels",
 	"mergeStateStatus",
 	"number",
+	"reviews",
 	"reviewDecision",
 	"state",
 	"title",

package/src/tools/index.ts

@@ -1,7 +1,7 @@
 import type { InMemorySnapshotStore } from "@oh-my-pi/hashline";
 import type { AgentTelemetryConfig, AgentTool } from "@oh-my-pi/pi-agent-core";
 import type { ToolChoice } from "@oh-my-pi/pi-ai";
-import { $env, $flag, logger } from "@oh-my-pi/pi-utils";
+import { logger } from "@oh-my-pi/pi-utils";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
 import { EditTool } from "../edit";
@@ -34,6 +34,7 @@ import { BrowserTool } from "./browser";
 import { type CheckpointState, CheckpointTool, RewindTool } from "./checkpoint";
 import { DebugTool } from "./debug";
 import { EvalTool } from "./eval";
+import { resolveEvalBackends } from "./eval-backends";
 import { FindTool } from "./find";
 import { GithubTool } from "./gh";
 import { InspectImageTool } from "./inspect-image";
@@ -74,6 +75,7 @@ export * from "./browser";
 export * from "./checkpoint";
 export * from "./debug";
 export * from "./eval";
+export * from "./eval-backends";
 export * from "./find";
 export * from "./gh";
 export * from "./image-gen";
@@ -257,6 +259,10 @@ export interface ToolSession {
 	 *  by `getConflictHistory`. */
 	conflictHistory?: import("./conflict-detect").ConflictHistory;
 
+	/** Per-session ledger of post-edit LSP diagnostics already surfaced to the
+	 *  model for each file. Lazily initialized by `getDiagnosticsLedger`. */
+	diagnosticsLedger?: import("../lsp/diagnostics-ledger").DiagnosticsLedger;
+
 	/** Queue a hidden message to be injected at the next agent turn. */
 	queueDeferredMessage?(message: CustomMessage): void;
 	/** Get the active OpenTelemetry config so subagent dispatch can forward
@@ -331,42 +337,6 @@ export const HIDDEN_TOOLS: Record<string, ToolFactory> = {
 
 export type ToolName = keyof typeof BUILTIN_TOOLS;
 
-export interface EvalBackendsAllowance {
-	python: boolean;
-	js: boolean;
-}
-
-/**
- * Parse PI_PY / PI_JS environment variables. Each is a boolean flag; unset
- * means "not specified, defer to settings". Returns null when neither is set
- * so the caller can fall through to `readEvalBackendsAllowance` per key.
- */
-function getEvalBackendsFromEnv(): EvalBackendsAllowance | null {
-	const pyEnv = $env.PI_PY;
-	const jsEnv = $env.PI_JS;
-	if (pyEnv === undefined && jsEnv === undefined) return null;
-	return {
-		python: pyEnv === undefined ? true : $flag("PI_PY"),
-		js: jsEnv === undefined ? true : $flag("PI_JS"),
-	};
-}
-
-/** Read per-backend allowance from settings (defaults true). */
-export function readEvalBackendsAllowance(session: ToolSession): EvalBackendsAllowance {
-	return {
-		python: session.settings.get("eval.py") ?? true,
-		js: session.settings.get("eval.js") ?? true,
-	};
-}
-
-/**
- * Materialize the active eval backend allowance: PI_PY / PI_JS env flags
- * override the per-key settings; otherwise settings (defaults true) win.
- */
-export function resolveEvalBackends(session: ToolSession): EvalBackendsAllowance {
-	return getEvalBackendsFromEnv() ?? readEvalBackendsAllowance(session);
-}
-
 /**
  * Create tools from BUILTIN_TOOLS registry.
  */

package/src/tools/path-utils.ts

@@ -3,7 +3,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import * as url from "node:url";
 import { isEnoent } from "@oh-my-pi/pi-utils";
-import { InternalUrlRouter } from "../internal-urls";
+import { InternalUrlRouter, type LocalProtocolOptions } from "../internal-urls";
 import { ToolError } from "./tool-errors";
 
 const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
@@ -740,6 +740,12 @@ export interface ToolScopeOptions {
 	surfaceExactFilePaths?: boolean;
 	/** Extra hint appended to "Path not found" when stat fails and the user supplied multiple paths. */
 	multipathStatHint?: string;
+	/** Calling session's settings — forwarded to the internal-URL router so caller-aware handlers (issue://, pr://) honor it. */
+	settings?: unknown;
+	/** Caller's abort signal — forwarded to the internal-URL router. */
+	signal?: AbortSignal;
+	/** Calling session's `local://` root mapping — pins resolutions to the calling session. */
+	localProtocolOptions?: LocalProtocolOptions;
 }
 
 export interface ToolScopeResolution {
@@ -778,7 +784,12 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 		if (hasGlobPathChars(rawPath)) {
 			throw new ToolError(`Glob patterns are not supported for internal URLs: ${rawPath}`);
 		}
-		const resource = await internalRouter.resolve(rawPath);
+		const resource = await internalRouter.resolve(rawPath, {
+			cwd,
+			settings: opts.settings,
+			signal: opts.signal,
+			localProtocolOptions: opts.localProtocolOptions,
+		});
 		if (!resource.sourcePath) {
 			throw new ToolError(`Cannot ${internalUrlAction} internal URL without a backing file: ${rawPath}`);
 		}

package/src/tools/read.ts

@@ -2141,6 +2141,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			cwd: this.session.cwd,
 			settings: this.session.settings,
 			signal,
+			localProtocolOptions: this.session.localProtocolOptions,
 		});
 		const details: ReadToolDetails = { resolvedPath: resource.sourcePath, contentType: resource.contentType };
 

package/src/tools/renderers.ts

@@ -17,7 +17,7 @@ import { astGrepToolRenderer } from "./ast-grep";
 import { bashToolRenderer } from "./bash";
 import { browserToolRenderer } from "./browser/render";
 import { debugToolRenderer } from "./debug";
-import { evalToolRenderer } from "./eval";
+import { evalToolRenderer } from "./eval-render";
 import { findToolRenderer } from "./find";
 import { githubToolRenderer } from "./gh-renderer";
 import { inspectImageToolRenderer } from "./inspect-image-renderer";

package/src/tools/search.ts

@@ -10,6 +10,7 @@ import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import { recordFileSnapshot } from "../edit/file-snapshot-store";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { LocalProtocolOptions } from "../internal-urls/local-protocol";
 import { InternalUrlRouter } from "../internal-urls/router";
 import type { InternalResource, ResolveContext } from "../internal-urls/types";
 import type { Theme } from "../modes/theme/theme";
@@ -543,6 +544,7 @@ async function resolveInternalSearchInputs(opts: {
 	settings: unknown;
 	signal?: AbortSignal;
 	archiveDisplayMap: ReadonlyMap<string, string>;
+	localProtocolOptions?: LocalProtocolOptions;
 }): Promise<InternalSearchInputResolution> {
 	const internalRouter = InternalUrlRouter.instance();
 	const paths = opts.resolvedPaths.slice();
@@ -551,7 +553,12 @@ async function resolveInternalSearchInputs(opts: {
 	const virtualInputIndexes = new Set<number>();
 	const immutableSourcePaths = new Set<string>();
 	let virtualScopePath: string | undefined;
-	const context: ResolveContext = { cwd: opts.cwd, settings: opts.settings, signal: opts.signal };
+	const context: ResolveContext = {
+		cwd: opts.cwd,
+		settings: opts.settings,
+		signal: opts.signal,
+		localProtocolOptions: opts.localProtocolOptions,
+	};
 
 	for (let idx = 0; idx < paths.length; idx++) {
 		const rawPath = paths[idx];
@@ -674,6 +681,7 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 					settings: this.session.settings,
 					signal,
 					archiveDisplayMap,
+					localProtocolOptions: this.session.localProtocolOptions,
 				});
 				const searchablePaths = internalResolution.paths;
 				const { virtualResources, virtualPathSet, virtualInputIndexes } = internalResolution;
@@ -738,6 +746,9 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 						trackImmutableSources: true,
 						surfaceExactFilePaths: true,
 						multipathStatHint: " (`paths` entries must each exist relative to cwd)",
+						settings: this.session.settings,
+						signal,
+						localProtocolOptions: this.session.localProtocolOptions,
 					});
 					searchPath = scope.searchPath;
 					isDirectory = scope.isDirectory;

package/src/tools/write.ts

@@ -15,6 +15,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { InternalUrlRouter } from "../internal-urls";
 import { parseInternalUrl } from "../internal-urls/parse";
 import { createLspWritethrough, type FileDiagnosticsResult, type WritethroughCallback, writethroughNoop } from "../lsp";
+import { getDiagnosticsLedger } from "../lsp/diagnostics-ledger";
 import { getLanguageFromPath, highlightCode, type Theme } from "../modes/theme/theme";
 import writeDescription from "../prompts/tools/write.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
@@ -278,8 +279,15 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 		const enableLsp = session.enableLsp ?? true;
 		const enableFormat = enableLsp && session.settings.get("lsp.formatOnWrite");
 		const enableDiagnostics = enableLsp && session.settings.get("lsp.diagnosticsOnWrite");
+		const dedup = enableDiagnostics && session.settings.get("lsp.diagnosticsDeduplicate");
 		this.#writethrough = enableLsp
-			? createLspWritethrough(session.cwd, { enableFormat, enableDiagnostics })
+			? createLspWritethrough(session.cwd, {
+					enableFormat,
+					enableDiagnostics,
+					transformDiagnostics: dedup
+						? (path, result) => getDiagnosticsLedger(session).reduce(path, result)
+						: undefined,
+				})
 			: writethroughNoop;
 		this.description = prompt.render(writeDescription);
 	}

package/src/tui/output-block.ts

@@ -19,55 +19,43 @@ export interface OutputBlockOptions {
 	animate?: boolean;
 }
 
-const BORDER_SHIMMER_TICK_MS = 50;
-/** Duration of one full clockwise lap around the border, in ms. Fixed so a box
- * growing (new output line) or resizing only nudges the segment proportionally
- * instead of teleporting it. */
-const BORDER_LAP_MS = 4000;
+const BORDER_SHIMMER_TICK_MS = 16;
+/** Duration of one full left↔right↔left bounce of the bottom-edge segment, in
+ * ms. Position is derived from the wall clock against this fixed cycle so a
+ * resize only nudges the segment proportionally instead of teleporting it. */
+const BORDER_BOUNCE_MS = 3000;
 /** Length, in border cells, of the moving segment. */
 const BORDER_SEGMENT_LEN = 8;
 
 /**
- * Monotonic frame counter for animated borders. Quantized coarse enough to
- * coalesce multiple render passes inside one frame, fine enough to advance on
- * every spinner interval so cached blocks re-render while the segment travels.
+ * Monotonic frame counter for animated borders, quantized to the TUI's ~16ms
+ * render cap so the cache key advances once per ~60fps frame — fine enough for a
+ * smooth segment sweep, coarse enough to coalesce multiple render passes that
+ * land inside the same frame.
  */
 export function borderShimmerTick(): number {
 	return Math.floor(Date.now() / BORDER_SHIMMER_TICK_MS);
 }
 
-/** Ease-in-out so the segment decelerates into and accelerates out of corners. */
+/** Ease-in-out so the segment decelerates into and accelerates out of each wall. */
 function easeInOutQuad(t: number): number {
 	return t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2;
 }
 
 /**
- * Perimeter index of the moving segment's head for a box of inner width `W` and
- * height `H` at time `now`. The lap is split across the four edges in proportion
- * to their length (so the average speed is uniform) and each edge is eased, for a
- * deliberate, non-linear glide that slows at every corner. Position is derived
- * from the wall clock against a fixed lap duration, so a perimeter change (new
- * row / resize) shifts the head by at most a cell or two — no reset.
+ * Column of the travelling segment's center on the bottom edge for a box of
+ * inner width `W` at time `now`. The segment bounces left → right → left across
+ * the bottom border: a triangle wave over one full there-and-back cycle, eased
+ * per leg so it slows as it nears each wall before reversing. Position is
+ * derived from the wall clock against a fixed cycle, so a resize shifts the
+ * center proportionally — no reset.
  */
-export function borderSegmentHead(W: number, H: number, now: number): number {
-	const P = 2 * W + 2 * H - 4;
-	if (P <= 0) return 0;
-	// Edge cell counts, clockwise from top-left: top, right, bottom, left.
-	const edgeLens = [W, H - 1, W - 1, H - 2];
-	const t = (((now % BORDER_LAP_MS) + BORDER_LAP_MS) % BORDER_LAP_MS) / BORDER_LAP_MS;
-	let acc = 0;
-	let start = 0;
-	for (let i = 0; i < 4; i++) {
-		const len = edgeLens[i]!;
-		const frac = len / P;
-		if (len > 0 && t < acc + frac) {
-			const lf = (t - acc) / frac;
-			return (start + Math.floor(easeInOutQuad(lf) * len)) % P;
-		}
-		acc += frac;
-		start += len;
-	}
-	return P - 1;
+export function borderSegmentHeadCol(W: number, now: number): number {
+	if (W <= 1) return 0;
+	const phase = (((now % BORDER_BOUNCE_MS) + BORDER_BOUNCE_MS) % BORDER_BOUNCE_MS) / BORDER_BOUNCE_MS;
+	// Triangle: 0→1 rightward over the first half, 1→0 leftward over the second.
+	const leg = phase < 0.5 ? phase * 2 : 2 - phase * 2;
+	return easeInOutQuad(leg) * (W - 1);
 }
 
 /**
@@ -164,30 +152,26 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 	const W = lineWidth;
 	const animate = (options.animate ?? false) && (state === "running" || state === "pending") && W >= 2 && H >= 2;
 
-	// ── Segment geometry: one dark run travels the outer edge clockwise,
-	// top → right → bottom → left → top. ──
-	const P = animate ? 2 * W + 2 * H - 4 : 0;
-	const segLen = Math.min(BORDER_SEGMENT_LEN, P);
-	const head = animate ? borderSegmentHead(W, H, Date.now()) : 0;
+	// ── Segment geometry: one dark run bounces left ↔ right along the bottom
+	// edge only. The top, interior separators, and side borders stay the flat
+	// accent color. ──
+	const segLen = animate ? Math.min(BORDER_SEGMENT_LEN, W) : 0;
+	const head = animate ? borderSegmentHeadCol(W, Date.now()) : 0;
+	const segHalf = segLen / 2;
 	const segAnsi = animate ? (darkenFgAnsi(theme.getFgAnsi(borderColor), 0.4) ?? theme.getFgAnsi("borderMuted")) : "";
 	const seg = (text: string) => `${segAnsi}${text}\x1b[39m`;
 
-	// Perimeter index of border cell (row r, col c), clockwise from top-left.
-	const perimIndex = (r: number, c: number): number => {
-		if (r === 0) return c;
-		if (c === W - 1) return W - 1 + r;
-		if (r === H - 1) return W - 1 + (H - 1) + (W - 1 - c);
-		return W - 1 + (H - 1) + (W - 1) + (H - 1 - r);
-	};
-	const isLit = (idx: number): boolean => (((idx - head) % P) + P) % P < segLen;
-	// Color a run of border glyphs starting at (row r, col startCol), grouping
+	// A bottom-edge column is lit when it lies within half a segment of the
+	// travelling center.
+	const isLit = (col: number): boolean => Math.abs(col - head) < segHalf;
+	// Color a run of bottom-edge glyphs starting at column `startCol`, grouping
 	// consecutive same-state cells so each run emits a single escape pair.
-	const colorEdge = (glyphs: string, r: number, startCol: number): string => {
+	const colorEdge = (glyphs: string, startCol: number): string => {
 		let out = "";
 		let runLit: boolean | null = null;
 		let buf = "";
 		for (let i = 0; i < glyphs.length; i++) {
-			const lit = isLit(perimIndex(r, startCol + i));
+			const lit = isLit(startCol + i);
 			if (lit !== runLit) {
 				if (runLit !== null) out += (runLit ? seg : border)(buf);
 				buf = "";
@@ -199,10 +183,7 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 		return out;
 	};
 
-	const renderBar = (
-		row: { leftChar: string; rightChar: string; label?: string; meta?: string },
-		r: number,
-	): string => {
+	const renderBar = (row: { leftChar: string; rightChar: string; label?: string; meta?: string }): string => {
 		const leftGlyphs = `${row.leftChar}${cap}`;
 		const rightGlyph = row.rightChar;
 		if (lineWidth <= 0) return border(leftGlyphs) + border(rightGlyph);
@@ -215,36 +196,22 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 		const labelWidth = visibleWidth(trimmedLabel);
 		const fillCount = Math.max(0, lineWidth - leftWidth - labelWidth - rightWidth);
 		const fillGlyphs = h.repeat(fillCount);
-		if (!animate) {
-			return `${border(leftGlyphs)}${trimmedLabel}${border(fillGlyphs)}${border(rightGlyph)}`;
-		}
-		if (r === 0 || r === H - 1) {
-			// Top/bottom edge: the whole horizontal run lies on the perimeter.
-			const leftStr = colorEdge(leftGlyphs, r, 0);
-			const fillStr = colorEdge(fillGlyphs, r, leftWidth + labelWidth);
-			const rightStr = colorEdge(rightGlyph, r, lineWidth - rightWidth);
-			return `${leftStr}${trimmedLabel}${fillStr}${rightStr}`;
-		}
-		// Interior separator: only the first/last cell sit on the outer edge.
-		return `${colorEdge(row.leftChar, r, 0)}${border(cap)}${trimmedLabel}${border(fillGlyphs)}${colorEdge(rightGlyph, r, lineWidth - rightWidth)}`;
+		return `${border(leftGlyphs)}${trimmedLabel}${border(fillGlyphs)}${border(rightGlyph)}`;
 	};
 
-	const renderBottom = (row: { leftChar: string; rightChar: string }, r: number): string => {
+	const renderBottom = (row: { leftChar: string; rightChar: string }): string => {
 		const leftGlyphs = `${row.leftChar}${cap}`;
 		const rightGlyph = row.rightChar;
 		const fillCount = Math.max(0, lineWidth - visibleWidth(leftGlyphs) - visibleWidth(rightGlyph));
 		const fillGlyphs = h.repeat(fillCount);
 		if (!animate) return `${border(leftGlyphs)}${border(fillGlyphs)}${border(rightGlyph)}`;
-		const leftStr = colorEdge(leftGlyphs, r, 0);
-		const fillStr = colorEdge(fillGlyphs, r, visibleWidth(leftGlyphs));
-		const rightStr = colorEdge(rightGlyph, r, lineWidth - visibleWidth(rightGlyph));
+		const leftStr = colorEdge(leftGlyphs, 0);
+		const fillStr = colorEdge(fillGlyphs, visibleWidth(leftGlyphs));
+		const rightStr = colorEdge(rightGlyph, lineWidth - visibleWidth(rightGlyph));
 		return `${leftStr}${fillStr}${rightStr}`;
 	};
 
-	const renderContent = (inner: string, r: number): string => {
-		if (!animate) return `${border(`${v} `)}${inner}${border(v)}`;
-		return `${colorEdge(v, r, 0)} ${inner}${colorEdge(v, r, lineWidth - 1)}`;
-	};
+	const renderContent = (inner: string): string => `${border(`${v} `)}${inner}${border(v)}`;
 
 	const lines: string[] = [];
 	for (let r = 0; r < H; r++) {
@@ -254,11 +221,7 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 			continue;
 		}
 		const line =
-			row.kind === "bar"
-				? renderBar(row, r)
-				: row.kind === "bottom"
-					? renderBottom(row, r)
-					: renderContent(row.inner, r);
+			row.kind === "bar" ? renderBar(row) : row.kind === "bottom" ? renderBottom(row) : renderContent(row.inner);
 		lines.push(padToWidth(line, lineWidth, bgFn));
 	}
 

package/src/utils/git.ts

@@ -1261,9 +1261,15 @@ export async function clone(url: string, targetDir: string, options: CloneOption
 	const absoluteTarget = path.resolve(targetDir);
 	await fs.promises.mkdir(path.dirname(absoluteTarget), { recursive: true });
 
-	const args = ["clone", "--depth", "1"];
+	// `git clone --depth 1 --single-branch` only fetches the tip of the target
+	// branch, so any subsequent `git checkout <sha>` for a non-tip commit fails
+	// with "reference is not a tree". When the caller pinned a specific SHA we
+	// fall back to a full clone so the object is guaranteed to be present.
+	const shallow = !options.sha;
+	const args = ["clone"];
+	if (shallow) args.push("--depth", "1");
 	if (options.ref) args.push("--branch", options.ref, "--single-branch");
-	else args.push("--single-branch");
+	else if (shallow) args.push("--single-branch");
 	args.push(url, absoluteTarget);
 
 	try {
@@ -1273,7 +1279,7 @@ export async function clone(url: string, targetDir: string, options: CloneOption
 				await checkout(absoluteTarget, options.sha, options.signal);
 			} catch {
 				await fs.promises.rm(absoluteTarget, { force: true, recursive: true });
-				throw new Error(`Failed to checkout SHA ${options.sha} - shallow clone may not contain this commit`);
+				throw new Error(`Failed to checkout SHA ${options.sha} in cloned repository ${url}`);
 			}
 		}
 	} catch (err) {