@jameslovespancakes/pi-plus 1.0.11 → 1.0.13

package/src/domains/workflows/runtime/review/review-snapshot.ts

@@ -0,0 +1,294 @@
+import { createHash } from "node:crypto";
+import { throwIfAborted } from "../cancellation.ts";
+import { captureDiffTarget, type DiffCaptureFailure } from "../diff-capture.ts";
+import {
+  reviewGitDiffBaseline,
+  type GitReviewDiffTarget,
+  type PullRequestReviewDiffTarget,
+  type ReviewDiffTarget,
+} from "../review-diff-target.ts";
+import { runBoundedProcess } from "../process-runner.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
+import type { WorktreeBaseline } from "../worktree.ts";
+import type { ReviewContext, ReviewSnapshotIdentity } from "./review-report.ts";
+
+const REVIEW_SNAPSHOT_TIMEOUT_MS = 30_000;
+const REVIEW_SNAPSHOT_MAX_BYTES = 16 << 20;
+const REVIEW_COMMAND_MAX_BYTES = 1 << 20;
+
+export interface VerifiedReviewSnapshot {
+  readonly status: "verified";
+  readonly identity: ReviewSnapshotIdentity;
+  readonly baseline: WorktreeBaseline;
+}
+
+export interface UnavailableReviewSnapshot {
+  readonly status: "unavailable";
+  readonly reason: string;
+}
+
+export type ReviewSnapshotCapture = VerifiedReviewSnapshot | UnavailableReviewSnapshot;
+
+export interface CapturedReviewMaterial {
+  readonly ok: true;
+  /** The already-captured diff used by the review, even when its baseline cannot be verified. */
+  readonly diff: string;
+  readonly snapshot: ReviewSnapshotCapture;
+}
+
+export interface ReviewMaterialCaptureFailure {
+  readonly ok: false;
+  readonly error: string;
+  readonly failure: DiffCaptureFailure;
+}
+
+export type ReviewMaterialCaptureResult = CapturedReviewMaterial | ReviewMaterialCaptureFailure;
+
+export class ReviewSnapshotUnavailableError extends Error {
+  override readonly name = "ReviewSnapshotUnavailableError";
+}
+
+/**
+ * Capture one review diff and, when possible, an atomic identity for its exact
+ * reconstructable post-change state. A baseline failure never discards or
+ * recaptures a diff that was already captured successfully.
+ */
+export async function captureReviewMaterial(
+  target: ReviewDiffTarget,
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<ReviewMaterialCaptureResult> {
+  let latestDiff: string | undefined;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const before = await captureReviewDiff(target, cwd, signal);
+    if (!before.ok) {
+      throwIfAborted(signal);
+      return latestDiff === undefined
+        ? { ok: false, error: before.error, failure: before.failure }
+        : capturedWithoutSnapshot(latestDiff, `review diff could not be recaptured: ${before.error}`);
+    }
+    latestDiff = before.diff;
+
+    let baseline: WorktreeBaseline;
+    try {
+      baseline = await captureReviewWorktreeBaseline(target, cwd, signal);
+    } catch (error) {
+      throwIfAborted(signal);
+      return capturedWithoutSnapshot(before.diff, `review baseline could not be captured: ${unknownErrorMessage(error)}`);
+    }
+
+    const after = await captureReviewDiff(target, cwd, signal);
+    if (!after.ok) {
+      throwIfAborted(signal);
+      return capturedWithoutSnapshot(before.diff, `review diff could not be recaptured: ${after.error}`);
+    }
+    latestDiff = after.diff;
+
+    const beforeFingerprint = fingerprintReviewDiff(before.diff);
+    const afterFingerprint = fingerprintReviewDiff(after.diff);
+    if (beforeFingerprint === afterFingerprint) {
+      return {
+        ok: true,
+        diff: after.diff,
+        snapshot: {
+          status: "verified",
+          identity: {
+            diffFingerprint: afterFingerprint,
+            baselineFingerprint: fingerprintReviewWorktreeBaseline(baseline),
+          },
+          baseline,
+        },
+      };
+    }
+  }
+
+  if (latestDiff === undefined) throw new Error("review snapshot retry loop completed without a captured diff");
+  return capturedWithoutSnapshot(latestDiff, "review target changed while its snapshot was being captured");
+}
+
+/** Revalidate the reviewed diff and reconstruct its exact post-change snapshot. */
+export async function resolveReviewWorktreeBaseline(
+  context: ReviewContext | undefined,
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<WorktreeBaseline> {
+  if (!context?.snapshot) {
+    throw new ReviewSnapshotUnavailableError("the review was not captured with a verifiable snapshot identity.");
+  }
+
+  const material = await captureReviewMaterial(context.diffTarget, cwd, signal);
+  if (!material.ok) {
+    throw new ReviewSnapshotUnavailableError(`the review diff could not be captured: ${material.error}`);
+  }
+  if (material.snapshot.status === "unavailable") {
+    throw new ReviewSnapshotUnavailableError(`the reviewed snapshot could not be verified: ${material.snapshot.reason}`);
+  }
+  if (material.snapshot.identity.diffFingerprint !== context.snapshot.diffFingerprint) {
+    throw new ReviewSnapshotUnavailableError("the reviewed diff changed after the findings were generated.");
+  }
+  if (material.snapshot.identity.baselineFingerprint !== context.snapshot.baselineFingerprint) {
+    throw new ReviewSnapshotUnavailableError("the reviewed snapshot changed after the findings were generated.");
+  }
+  return material.snapshot.baseline;
+}
+
+export function fingerprintReviewWorktreeBaseline(baseline: WorktreeBaseline): string {
+  return createHash("sha256")
+    .update(JSON.stringify({ ref: baseline.ref, patch: baseline.patch ?? null }))
+    .digest("hex");
+}
+
+async function captureReviewDiff(
+  target: ReviewDiffTarget,
+  cwd: string,
+  signal: AbortSignal | undefined,
+): Promise<{ readonly ok: true; readonly diff: string } | { readonly ok: false; readonly error: string; readonly failure: DiffCaptureFailure }> {
+  const captured = await captureDiffTarget(target, {
+    cwd,
+    signal,
+    timeoutMs: REVIEW_SNAPSHOT_TIMEOUT_MS,
+    maxBufferBytes: REVIEW_SNAPSHOT_MAX_BYTES,
+  });
+  return captured.ok
+    ? { ok: true, diff: captured.stdout }
+    : { ok: false, error: captured.error, failure: captured.failure };
+}
+
+async function captureReviewWorktreeBaseline(
+  target: ReviewDiffTarget,
+  cwd: string,
+  signal: AbortSignal | undefined,
+): Promise<WorktreeBaseline> {
+  return target.kind === "pull-request"
+    ? await resolvePullRequestBaseline(target, cwd, signal)
+    : await resolveGitDiffBaseline(target, cwd, signal);
+}
+
+async function resolvePullRequestBaseline(
+  target: PullRequestReviewDiffTarget,
+  cwd: string,
+  signal: AbortSignal | undefined,
+): Promise<WorktreeBaseline> {
+  const number = String(target.number);
+  const viewed = await runReviewCommand("gh", ["pr", "view", number, "--json", "headRefOid,headRefName,headRepository"], cwd, signal);
+  const details = viewed.ok ? parsePullRequestHead(viewed.stdout) : undefined;
+  if (!details) {
+    throw new Error(`pull request head could not be resolved: ${viewed.error ?? (viewed.stderr.trim() || "invalid head commit")}`);
+  }
+
+  if (!(await commitExists(details.head, cwd, signal))) {
+    const fetched = await runReviewCommand(
+      "git",
+      ["fetch", "--no-tags", "--quiet", `https://github.com/${details.repository}.git`, details.branch],
+      cwd,
+      signal,
+    );
+    if (!fetched.ok || !(await commitExists(details.head, cwd, signal))) {
+      throw new Error(
+        `pull request ${number} head ${details.head} is not available locally: ${fetched.error ?? (fetched.stderr.trim() || "fetch did not provide the commit")}`,
+      );
+    }
+  }
+  return { ref: details.head };
+}
+
+function parsePullRequestHead(value: string): { readonly head: string; readonly branch: string; readonly repository: string } | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null) return undefined;
+  const candidate = parsed as {
+    readonly headRefOid?: unknown;
+    readonly headRefName?: unknown;
+    readonly headRepository?: { readonly nameWithOwner?: unknown } | null;
+  };
+  if (typeof candidate.headRefOid !== "string" || !/^[0-9a-f]{40,64}$/i.test(candidate.headRefOid)) return undefined;
+  if (typeof candidate.headRefName !== "string" || candidate.headRefName.length === 0 || candidate.headRefName.includes("\0")) return undefined;
+  const repository = candidate.headRepository?.nameWithOwner;
+  if (typeof repository !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) return undefined;
+  return { head: candidate.headRefOid, branch: candidate.headRefName, repository };
+}
+
+async function resolveGitDiffBaseline(
+  target: GitReviewDiffTarget,
+  cwd: string,
+  signal: AbortSignal | undefined,
+): Promise<WorktreeBaseline> {
+  const baseline = reviewGitDiffBaseline(target);
+  switch (baseline.kind) {
+    case "range":
+      return { ref: await resolveCommit(baseline.ref, cwd, signal) };
+    case "index":
+      return await captureMutableGitBaseline(true, cwd, signal);
+    case "working-tree":
+      return await captureMutableGitBaseline(false, cwd, signal);
+  }
+}
+
+async function captureMutableGitBaseline(
+  staged: boolean,
+  cwd: string,
+  signal: AbortSignal | undefined,
+): Promise<WorktreeBaseline> {
+  const head = await tryResolveCommit("HEAD", cwd, signal);
+  if (!head) throw new Error("the reviewed repository has no committed HEAD baseline");
+
+  const args = staged
+    ? ["diff", "--no-ext-diff", "--binary", "--cached", "HEAD"]
+    : ["diff", "--no-ext-diff", "--binary", "HEAD"];
+  const snapshot = await runReviewCommand("git", args, cwd, signal, REVIEW_SNAPSHOT_MAX_BYTES);
+  if (!snapshot.ok) {
+    throw new Error(`the reviewed working state could not be captured: ${snapshot.error}`);
+  }
+  return { ref: head, patch: snapshot.stdout };
+}
+
+async function resolveCommit(ref: string, cwd: string, signal: AbortSignal | undefined): Promise<string> {
+  const resolved = await tryResolveCommit(ref, cwd, signal);
+  if (!resolved) throw new Error(`review target ${ref} is not a local commit`);
+  return resolved;
+}
+
+async function tryResolveCommit(ref: string, cwd: string, signal: AbortSignal | undefined): Promise<string | undefined> {
+  const result = await runReviewCommand("git", ["rev-parse", "--verify", `${ref}^{commit}`], cwd, signal);
+  const commit = result.stdout.trim();
+  return result.ok && /^[0-9a-f]{40,64}$/i.test(commit) ? commit : undefined;
+}
+
+async function commitExists(ref: string, cwd: string, signal: AbortSignal | undefined): Promise<boolean> {
+  const result = await runReviewCommand("git", ["cat-file", "-e", `${ref}^{commit}`], cwd, signal);
+  return result.ok;
+}
+
+async function runReviewCommand(
+  file: "git" | "gh",
+  args: readonly string[],
+  cwd: string,
+  signal: AbortSignal | undefined,
+  maxBufferBytes = REVIEW_COMMAND_MAX_BYTES,
+) {
+  return await runBoundedProcess({
+    file,
+    args,
+    cwd,
+    env: { ...process.env, GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" },
+    signal,
+    timeoutMs: REVIEW_SNAPSHOT_TIMEOUT_MS,
+    maxBufferBytes,
+    abortError: `${file} review snapshot command aborted`,
+    timeoutError: `${file} review snapshot command timed out after ${REVIEW_SNAPSHOT_TIMEOUT_MS}ms`,
+    maxBufferError: `${file} review snapshot command exceeded output limit`,
+    exitError: (stderr, code, processSignal) => stderr.trim() || `${file} exited with code ${code ?? `signal ${processSignal ?? "unknown"}`}`,
+  });
+}
+
+function capturedWithoutSnapshot(diff: string, reason: string): CapturedReviewMaterial {
+  return { ok: true, diff, snapshot: { status: "unavailable", reason } };
+}
+
+function fingerprintReviewDiff(diff: string): string {
+  return createHash("sha256").update(diff).digest("hex");
+}

package/src/domains/workflows/runtime/review-diff-target.ts

@@ -0,0 +1,130 @@
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+export type GitDiffBaselineTarget =
+  | { readonly kind: "working-tree" }
+  | { readonly kind: "index" }
+  | { readonly kind: "range"; readonly ref: string };
+
+export const GitReviewDiffTargetSchema = Type.Object({
+  kind: Type.Literal("git"),
+  args: Type.Array(Type.String()),
+});
+
+export const PullRequestReviewDiffTargetSchema = Type.Object({
+  kind: Type.Literal("pull-request"),
+  number: Type.Integer({ minimum: 1 }),
+});
+
+export const ReviewDiffTargetSchema = Type.Union([GitReviewDiffTargetSchema, PullRequestReviewDiffTargetSchema]);
+
+export type GitReviewDiffTarget = Static<typeof GitReviewDiffTargetSchema>;
+export type PullRequestReviewDiffTarget = Static<typeof PullRequestReviewDiffTargetSchema>;
+
+/** Serializable semantic identity of the diff being reviewed. */
+export type ReviewDiffTarget = Static<typeof ReviewDiffTargetSchema>;
+
+const SAFE_REF_OR_PATH = /^[A-Za-z0-9_./:@~+=,-]+$/;
+const SAFE_GH_DIFF_FLAGS = new Set(["--color=never"]);
+const SAFE_GIT_DIFF_FLAGS = new Set(["--binary", "--cached", "--staged", "--no-color", "--color=never", "--no-ext-diff"]);
+
+export function parseAllowedDiffCommand(command: string): ReviewDiffTarget | { error: string } {
+  const tokens = command.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length < 2) return { error: "empty or incomplete diff command" };
+  if (tokens[0] === "git" && tokens[1] === "diff") {
+    const parsed = parseGitDiff(tokens);
+    return "error" in parsed ? parsed : parsed.target;
+  }
+  if (tokens[0] === "gh" && tokens[1] === "pr" && tokens[2] === "diff" && /^\d+$/.test(tokens[3] ?? "")) {
+    const number = Number(tokens[3]);
+    if (!Number.isSafeInteger(number) || number <= 0) return { error: "pull-request number must be a positive safe integer" };
+    const flags = tokens.slice(4);
+    if (flags.includes("--patch")) return { error: "gh pr diff --patch is not supported because reviews require the cumulative pull-request diff" };
+    const unsupported = flags.find((token) => !SAFE_GH_DIFF_FLAGS.has(token));
+    if (unsupported) return { error: `unsupported gh pr diff option: ${unsupported}` };
+    return { kind: "pull-request", number };
+  }
+  return { error: "diff command is not in the git/gh allowlist" };
+}
+
+function parseGitDiff(
+  tokens: readonly string[],
+): { readonly target: GitReviewDiffTarget; readonly baseline: GitDiffBaselineTarget } | { readonly error: string } {
+  const args = tokens.slice(2);
+  const safeArgs = ["diff", "--no-ext-diff"];
+  const operands: string[] = [];
+  let staged = false;
+  let pathMode = false;
+
+  for (const token of args) {
+    if (!SAFE_REF_OR_PATH.test(token)) return { error: `unsupported git diff token: ${token}` };
+    if (token === "--") {
+      pathMode = true;
+      safeArgs.push(token);
+      continue;
+    }
+    if (!pathMode && token.startsWith("-")) {
+      if (!isAllowedGitDiffFlag(token)) return { error: `unsupported git diff option: ${token}` };
+      staged ||= token === "--cached" || token === "--staged";
+      if (token !== "--no-ext-diff") safeArgs.push(token);
+      continue;
+    }
+    if (!pathMode) operands.push(token);
+    safeArgs.push(token);
+  }
+
+  const baseline = classifyGitDiffBaseline(staged, operands);
+  return "error" in baseline ? baseline : { target: { kind: "git", args: safeArgs }, baseline };
+}
+
+function classifyGitDiffBaseline(staged: boolean, operands: readonly string[]): GitDiffBaselineTarget | { readonly error: string } {
+  if (operands.length > 1) {
+    return { error: "ambiguous git diff operands; use A..B or A...B for revisions, or -- before multiple paths" };
+  }
+  if (staged) return { kind: "index" };
+
+  const range = operands.find((operand) => operand.includes(".."));
+  if (range) {
+    const separator = range.includes("...") ? "..." : "..";
+    return { kind: "range", ref: range.slice(range.indexOf(separator) + separator.length) || "HEAD" };
+  }
+
+  return { kind: "working-tree" };
+}
+
+function isAllowedGitDiffFlag(token: string): boolean {
+  return SAFE_GIT_DIFF_FLAGS.has(token) || /^-U\d+$/.test(token) || /^--unified=\d+$/.test(token) || /^--inter-hunk-context=\d+$/.test(token);
+}
+
+export function reviewDiffCommand(target: ReviewDiffTarget): { readonly file: "git" | "gh"; readonly args: readonly string[] } {
+  return target.kind === "pull-request"
+    ? { file: "gh", args: ["pr", "diff", String(target.number), "--color=never"] }
+    : { file: "git", args: target.args };
+}
+
+/** Canonical display form. Never execute this string directly; use reviewDiffCommand(). */
+export function formatReviewDiffTarget(target: ReviewDiffTarget): string {
+  const command = reviewDiffCommand(target);
+  return [command.file, ...command.args].join(" ");
+}
+
+/** Derive reconstruction semantics from the canonical git command instead of persisting duplicate state. */
+export function reviewGitDiffBaseline(target: GitReviewDiffTarget): GitDiffBaselineTarget {
+  const parsed = parseGitDiff(["git", ...target.args]);
+  if ("error" in parsed) throw new Error(`Invalid persisted git review target: ${parsed.error}`);
+  return parsed.baseline;
+}
+
+/** Validate persisted targets by round-tripping through the single command allowlist parser. */
+export function isReviewDiffTarget(value: unknown): value is ReviewDiffTarget {
+  if (!Value.Check(ReviewDiffTargetSchema, value)) return false;
+  const parsed = parseAllowedDiffCommand(formatReviewDiffTarget(value));
+  return !("error" in parsed) && sameReviewDiffTarget(parsed, value);
+}
+
+function sameReviewDiffTarget(left: ReviewDiffTarget, right: ReviewDiffTarget): boolean {
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "pull-request") return right.kind === "pull-request" && left.number === right.number;
+  if (right.kind !== "git" || left.args.length !== right.args.length) return false;
+  return left.args.every((arg, index) => arg === right.args[index]);
+}

package/src/domains/workflows/runtime/session-identity.ts

@@ -0,0 +1,6 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Stable identity for state retained for the lifetime of a pi session. */
+export function sessionKey(ctx: Pick<ExtensionContext, "sessionManager">): string {
+  return ctx.sessionManager.getSessionFile() ?? ctx.sessionManager.getSessionId();
+}

package/src/domains/workflows/runtime/structured-output.ts

@@ -0,0 +1,32 @@
+export const MAX_SCHEMA_REPAIR_ATTEMPTS = 2;
+export const STRUCTURED_OUTPUT_ERROR_CODE = "WORKFLOW_STRUCTURED_OUTPUT_NONCOMPLIANCE";
+
+export interface StructuredOutputErrorDetails {
+  readonly agentLabel: string;
+  readonly promptAttempts: number;
+  readonly repairAttempts: number;
+}
+
+/** Recoverable failure raised when a schema agent never calls `final_answer`. */
+export class WorkflowStructuredOutputError extends Error {
+  readonly name = "WorkflowStructuredOutputError";
+  readonly code = STRUCTURED_OUTPUT_ERROR_CODE;
+  readonly details: StructuredOutputErrorDetails;
+
+  constructor(agentLabel: string, repairAttempts: number) {
+    const promptAttempts = repairAttempts + 1;
+    super(
+      `Schema agent "${agentLabel}" did not call final_answer after ${promptAttempts} prompt attempts (${repairAttempts} repairs).`,
+    );
+    this.details = { agentLabel, promptAttempts, repairAttempts };
+  }
+
+  toJSON(): {
+    readonly name: string;
+    readonly message: string;
+    readonly code: string;
+    readonly details: StructuredOutputErrorDetails;
+  } {
+    return { name: this.name, message: this.message, code: this.code, details: this.details };
+  }
+}

package/src/domains/workflows/runtime/tool-capabilities.ts

@@ -0,0 +1,44 @@
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { AgentToolHint } from "./types.ts";
+
+/** Raised before prompting when required semantic tool capabilities are unavailable. */
+export class WorkflowToolHintUnavailableError extends Error {
+  readonly code = "WORKFLOW_TOOL_HINT_UNAVAILABLE";
+  readonly hints: readonly AgentToolHint[];
+
+  constructor(hints: readonly AgentToolHint[]) {
+    super(`Required workflow tool capability unavailable: ${hints.join(", ")}`);
+    this.name = "WorkflowToolHintUnavailableError";
+    this.hints = [...hints];
+  }
+}
+
+export function matchesAgentToolHint(tool: ToolInfo, hint: AgentToolHint): boolean {
+  return hint === "search" ? isSearchLikeTool(tool) : isExternalSearchLikeTool(tool);
+}
+
+function isExternalSearchLikeTool(tool: ToolInfo): boolean {
+  if (isMutationLikeToolName(tool.name) || tool.sourceInfo.source === "builtin") return false;
+  const name = tool.name.toLowerCase();
+  const description = [tool.description, ...(tool.promptGuidelines ?? [])].join(" ").toLowerCase();
+  const text = `${name} ${description}`;
+  const hasResearchAction = /\b(?:browse|browser|search|fetch|extract|open|read|get)\b/.test(text)
+    || /(?:^|[-_])(?:browse|browser|search|fetch|extract)(?:$|[-_])/.test(name)
+    || /(?:^|[^a-z0-9])web(?:$|[^a-z0-9])/.test(name);
+  const hasExternalMedium = /(?:^|[-_])(?:web|browser|url|http|https|tavily|exa|firecrawl|brave|serper|parallel|perplexity)(?:$|[-_])/.test(name)
+    || /\b(?:search|browse)\s+(?:the\s+)?(?:web|internet)\b/.test(description)
+    || /\b(?:internet|web) search(?: engine)?\b/.test(description)
+    || /\b(?:fetch|extract|open|read|get)\s+(?:(?:the|a|an)\s+)?(?:url|web\s?page|website|https? page)\b/.test(description);
+  return hasResearchAction && hasExternalMedium;
+}
+
+function isSearchLikeTool(tool: ToolInfo): boolean {
+  if (isMutationLikeToolName(tool.name)) return false;
+  const name = tool.name.toLowerCase();
+  if (name.includes("grep") || name.includes("find") || name.includes("search") || name === "rg" || name.includes("ripgrep")) return true;
+  return /\b(?:grep|find|search|ripgrep|rg|structural search|code search)\b/.test(tool.description.toLowerCase());
+}
+
+function isMutationLikeToolName(name: string): boolean {
+  return /(?:edit|write|replace|patch|apply|delete|remove|move|rename|create|commit|push)/.test(name.toLowerCase());
+}

package/src/domains/workflows/runtime/tool-source-identity.ts

@@ -0,0 +1,150 @@
+import { lstat } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { isMissingPathError } from "./filesystem-error.ts";
+import { hashIdentity } from "./identity-fingerprint.ts";
+import { logicalWorkspacePath, portableRelativePath } from "./replay-path-identity.ts";
+import { captureTreeFingerprint, isPathWithin, validateTreeFile, type FingerprintCapture } from "./tree-fingerprint.ts";
+
+export interface EffectiveToolSourceInfoLike {
+  readonly path: string;
+  readonly source: string;
+  readonly scope: string;
+  readonly origin: string;
+  readonly baseDir?: string;
+}
+
+export interface EffectiveToolSourceIdentity {
+  readonly path: string;
+  readonly source: string;
+  readonly scope: string;
+  readonly origin: string;
+  readonly baseDir?: string;
+  readonly fingerprint: string;
+}
+
+export type ToolSourceFingerprintCache = Map<string, Promise<FingerprintCapture>>;
+
+export interface ToolSourceIdentityOptions {
+  readonly runtimeVersion: string;
+  readonly sessionCwd: string;
+  readonly workspaceRoot: string;
+  readonly cache: ToolSourceFingerprintCache;
+  readonly signal?: AbortSignal;
+}
+
+const SOURCE_FINGERPRINT_MAX_BYTES = 32 << 20;
+const SOURCE_FINGERPRINT_MAX_FILES = 4096;
+const SOURCE_FINGERPRINT_EXCLUSIONS = new Set([".git", ".pi/.workflow-runs"]);
+
+export async function captureEffectiveToolSourceIdentity(
+  sourceInfo: EffectiveToolSourceInfoLike,
+  options: ToolSourceIdentityOptions,
+): Promise<EffectiveToolSourceIdentity> {
+  const path = nonEmptyString(sourceInfo.path, "tool source path");
+  const source = nonEmptyString(sourceInfo.source, `source type for tool source "${path}"`);
+  const scope = nonEmptyString(sourceInfo.scope, `scope for tool source "${path}"`);
+  const origin = nonEmptyString(sourceInfo.origin, `origin for tool source "${path}"`);
+  const declaredBaseDir = sourceInfo.baseDir === undefined ? undefined : nonEmptyString(sourceInfo.baseDir, `base directory for tool source "${path}"`);
+
+  if (isSyntheticSource(path, source)) {
+    const baseDir =
+      declaredBaseDir === undefined
+        ? undefined
+        : normalizeUnresolvedBaseDir(declaredBaseDir, options.sessionCwd, options.workspaceRoot);
+    const synthetic = { path, source, scope, origin, ...(baseDir === undefined ? {} : { baseDir }) };
+    return {
+      ...synthetic,
+      fingerprint: hashIdentity({ runtimeVersion: options.runtimeVersion, source: synthetic }),
+    };
+  }
+
+  const baseDir = declaredBaseDir === undefined ? undefined : resolveDeclaredPath(declaredBaseDir, options.sessionCwd);
+  const sourcePath = await resolveExistingSourcePath(path, baseDir, options.sessionCwd, options.workspaceRoot);
+  const sourceRoot = baseDir && isPathWithin(baseDir, sourcePath) ? baseDir : dirname(sourcePath);
+  const validation = await validateTreeFile({
+    root: sourceRoot,
+    path: sourcePath,
+    excludedRelativePaths: SOURCE_FINGERPRINT_EXCLUSIONS,
+    signal: options.signal,
+  });
+  if (validation.kind === "unverifiable") throw new Error(`tool source "${path}" is not fingerprintable: ${validation.reason}`);
+
+  let capture = options.cache.get(sourceRoot);
+  if (!capture) {
+    capture = captureTreeFingerprint({
+      root: sourceRoot,
+      excludedRelativePaths: SOURCE_FINGERPRINT_EXCLUSIONS,
+      maxBytes: SOURCE_FINGERPRINT_MAX_BYTES,
+      maxFiles: SOURCE_FINGERPRINT_MAX_FILES,
+      signal: options.signal,
+    });
+    options.cache.set(sourceRoot, capture);
+  }
+  const fingerprint = await capture;
+  if (fingerprint.kind === "unverifiable") throw new Error(`tool source "${path}" is not fingerprintable: ${fingerprint.reason}`);
+
+  return {
+    path: logicalSourcePath(sourcePath, sourceRoot, options.sessionCwd, options.workspaceRoot),
+    source,
+    scope,
+    origin,
+    ...(baseDir === undefined
+      ? {}
+      : { baseDir: logicalSourcePath(baseDir, sourceRoot, options.sessionCwd, options.workspaceRoot) }),
+    fingerprint: fingerprint.fingerprint,
+  };
+}
+
+async function resolveExistingSourcePath(
+  path: string,
+  baseDir: string | undefined,
+  sessionCwd: string,
+  workspaceRoot: string,
+): Promise<string> {
+  const candidates = isAbsolute(path)
+    ? [resolve(path)]
+    : uniquePaths([
+        ...(baseDir ? [resolve(baseDir, path), resolve(baseDir, path.split(/[\\/]/).at(-1) ?? path)] : []),
+        resolve(sessionCwd, path),
+        resolve(workspaceRoot, path),
+      ]);
+
+  for (const candidate of candidates) {
+    try {
+      if ((await lstat(candidate)).isFile()) return candidate;
+    } catch (error) {
+      if (!isMissingPathError(error)) throw error;
+    }
+  }
+  throw new Error(`tool source path does not identify a regular file: ${path}`);
+}
+
+function resolveDeclaredPath(path: string, sessionCwd: string): string {
+  return isAbsolute(path) ? resolve(path) : resolve(sessionCwd, path);
+}
+
+function normalizeUnresolvedBaseDir(path: string, sessionCwd: string, workspaceRoot: string): string {
+  const resolvedPath = resolveDeclaredPath(path, sessionCwd);
+  return logicalWorkspacePath(resolvedPath, { sessionCwd, workspaceRoot }) ?? "source-root:.";
+}
+
+function logicalSourcePath(path: string, sourceRoot: string, sessionCwd: string, workspaceRoot: string): string {
+  const workspacePath = logicalWorkspacePath(path, { sessionCwd, workspaceRoot });
+  if (workspacePath) return workspacePath;
+  if (isPathWithin(sourceRoot, path)) return `source-root:${portableRelativePath(sourceRoot, path)}`;
+  throw new Error("tool source path is outside its fingerprint roots");
+}
+
+function isSyntheticSource(path: string, source: string): boolean {
+  return (path.startsWith("<") && path.endsWith(">")) || source === "builtin" || source === "sdk" || /^(?:builtin|sdk):/.test(path);
+}
+
+function uniquePaths(paths: readonly string[]): readonly string[] {
+  return [...new Set(paths)];
+}
+
+function nonEmptyString(value: string, label: string): string {
+  if (typeof value !== "string") throw new Error(`${label} is not a string`);
+  if (value.length === 0) throw new Error(`${label} is empty`);
+  return value;
+}