@tt-a1i/openpi 0.3.1 → 0.5.0

package/extensions/workflows/progress-projection.ts

@@ -0,0 +1,306 @@
+import {
+  calculateContextTokens,
+  type AgentSession,
+  estimateTokens,
+} from "@earendil-works/pi-coding-agent";
+import { type AgentUsage, emptyUsage, type TranscriptEntry } from "./model.ts";
+import { safeStringify, truncateUtf8 } from "./serialization.ts";
+
+const TRANSCRIPT_ENTRY_MAX_BYTES = 16 * 1024;
+const TRANSCRIPT_TOTAL_MAX_BYTES = 256 * 1024;
+const TRANSCRIPT_MAX_ENTRIES = 200;
+
+type AgentMessage = AgentSession["messages"][number];
+export type ProgressAssistantMessage = Extract<
+  AgentMessage,
+  { role: "assistant" }
+>;
+
+export interface ProgressToolTiming {
+  startedAt?: number;
+  finishedAt?: number;
+  durationMs?: number;
+}
+
+type ContextTokens = number | null | undefined;
+
+interface ProjectedTranscriptEntry {
+  role: TranscriptEntry["role"];
+  text: string;
+  sourceTextTruncated: boolean;
+  name?: string;
+  sourceToolCallId?: string;
+  isError?: boolean;
+  timestamp?: number;
+}
+
+export interface AgentProgressProjectionSnapshot {
+  preview: string;
+  usage: AgentUsage;
+  latestAssistant?: ProgressAssistantMessage;
+  transcript: TranscriptEntry[];
+}
+
+function validAssistantContextTokens(message: ProgressAssistantMessage) {
+  if (
+    message.stopReason === "aborted" ||
+    message.stopReason === "error" ||
+    !message.usage
+  ) {
+    return undefined;
+  }
+  const tokens = calculateContextTokens(message.usage);
+  return tokens > 0 ? tokens : undefined;
+}
+
+function boundedSourceText(text: string) {
+  const bounded = truncateUtf8(text, TRANSCRIPT_ENTRY_MAX_BYTES);
+  return { text: bounded, sourceTextTruncated: bounded !== text };
+}
+
+function safeJson(value: unknown) {
+  return safeStringify(value, {
+    maxBytes: TRANSCRIPT_ENTRY_MAX_BYTES,
+    maxDepth: 12,
+    maxNodes: 2_000,
+  });
+}
+
+function messageEntries(message: AgentMessage): ProjectedTranscriptEntry[] {
+  if (message.role === "user") {
+    const source =
+      typeof message.content === "string"
+        ? message.content
+        : message.content
+            .map((part) =>
+              part.type === "text" ? part.text : `[image: ${part.mimeType}]`,
+            )
+            .join("\n");
+    if (!source.trim()) return [];
+    return [
+      {
+        role: "user",
+        ...boundedSourceText(source),
+        timestamp: message.timestamp,
+      },
+    ];
+  }
+
+  if (message.role === "assistant") {
+    const entries: ProjectedTranscriptEntry[] = [];
+    for (const part of message.content) {
+      if (part.type === "text" && part.text.trim()) {
+        entries.push({
+          role: "assistant",
+          ...boundedSourceText(part.text),
+          timestamp: message.timestamp,
+        });
+        continue;
+      }
+      if (part.type === "thinking" && part.thinking.trim()) {
+        entries.push({
+          role: "thinking",
+          ...boundedSourceText(part.thinking),
+          timestamp: message.timestamp,
+        });
+        continue;
+      }
+      if (part.type === "toolCall") {
+        entries.push({
+          role: "tool",
+          ...boundedSourceText(safeJson(part.arguments)),
+          name: part.name,
+          sourceToolCallId: part.id,
+          timestamp: message.timestamp,
+        });
+      }
+    }
+    return entries;
+  }
+
+  if (message.role !== "toolResult") return [];
+  const source = message.content
+    .map((part) =>
+      part.type === "text" ? part.text : `[image: ${part.mimeType}]`,
+    )
+    .join("\n");
+  return [
+    {
+      role: "toolResult",
+      ...boundedSourceText(source),
+      name: message.toolName,
+      sourceToolCallId: message.toolCallId,
+      isError: message.isError,
+      timestamp: message.timestamp,
+    },
+  ];
+}
+
+function assistantText(message: ProgressAssistantMessage) {
+  return message.content
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("\n")
+    .trim();
+}
+
+function addAssistantUsage(
+  usage: AgentUsage,
+  message: ProgressAssistantMessage,
+) {
+  usage.turns++;
+  const current = message.usage;
+  if (!current) return;
+  usage.input += current.input || 0;
+  usage.output += current.output || 0;
+  usage.cacheRead += current.cacheRead || 0;
+  usage.cacheWrite += current.cacheWrite || 0;
+  usage.cost += current.cost?.total || 0;
+}
+
+function toolMetadata(
+  toolCallId: string,
+  timings: ReadonlyMap<string, ProgressToolTiming>,
+) {
+  const timing = timings.get(toolCallId);
+  return {
+    toolCallId: truncateUtf8(toolCallId, 1024),
+    ...(timing?.startedAt === undefined ? {} : { startedAt: timing.startedAt }),
+    ...(timing?.finishedAt === undefined
+      ? {}
+      : { finishedAt: timing.finishedAt }),
+    ...(timing?.durationMs === undefined
+      ? {}
+      : { durationMs: timing.durationMs }),
+  };
+}
+
+/**
+ * Bounded, ephemeral projection of Pi's active child messages.
+ *
+ * Pi remains canonical. Normal finalized messages are folded once; startup,
+ * compaction, and terminal settlement replace this state from Pi's messages.
+ */
+export class AgentProgressProjection {
+  private usage = emptyUsage();
+  private preview = "";
+  private latestAssistant?: ProgressAssistantMessage;
+  private firstEntry?: ProjectedTranscriptEntry;
+  private tailEntries: ProjectedTranscriptEntry[] = [];
+  private totalEntries = 0;
+  private contextTokens: ContextTokens;
+
+  constructor(
+    messages: readonly AgentMessage[] = [],
+    contextTokens?: ContextTokens,
+  ) {
+    this.replace(messages, contextTokens);
+  }
+
+  replace(messages: readonly AgentMessage[], contextTokens?: ContextTokens) {
+    this.usage = emptyUsage();
+    this.preview = "";
+    this.latestAssistant = undefined;
+    this.firstEntry = undefined;
+    this.tailEntries = [];
+    this.totalEntries = 0;
+    this.contextTokens = contextTokens;
+    for (const message of messages) this.ingest(message, false);
+  }
+
+  append(message: AgentMessage) {
+    this.ingest(message, true);
+  }
+
+  private ingest(message: AgentMessage, updateContext: boolean) {
+    if (message.role === "assistant") {
+      addAssistantUsage(this.usage, message);
+      this.latestAssistant = message;
+      const text = assistantText(message);
+      if (text) this.preview = text;
+    }
+
+    if (updateContext && this.contextTokens !== undefined) {
+      const assistantTokens =
+        message.role === "assistant"
+          ? validAssistantContextTokens(message)
+          : undefined;
+      if (assistantTokens !== undefined) {
+        this.contextTokens = assistantTokens;
+      } else if (this.contextTokens !== null) {
+        this.contextTokens += estimateTokens(message);
+      }
+    }
+
+    for (const entry of messageEntries(message)) this.pushEntry(entry);
+  }
+
+  private pushEntry(entry: ProjectedTranscriptEntry) {
+    this.totalEntries++;
+    if (!this.firstEntry) {
+      this.firstEntry = entry;
+      return;
+    }
+    this.tailEntries.push(entry);
+    if (this.tailEntries.length >= TRANSCRIPT_MAX_ENTRIES) {
+      this.tailEntries.shift();
+    }
+  }
+
+  snapshot(
+    toolTimings: ReadonlyMap<string, ProgressToolTiming> = new Map(),
+  ): AgentProgressProjectionSnapshot {
+    const selected = this.firstEntry
+      ? [this.firstEntry, ...this.tailEntries]
+      : [];
+    const transcript: TranscriptEntry[] = [];
+    let totalBytes = 0;
+    for (const entry of selected) {
+      const remaining = TRANSCRIPT_TOTAL_MAX_BYTES - totalBytes;
+      if (remaining <= 0) break;
+      const text = truncateUtf8(
+        entry.text,
+        Math.min(TRANSCRIPT_ENTRY_MAX_BYTES, remaining),
+      );
+      totalBytes += Buffer.byteLength(text, "utf8");
+      const truncated = entry.sourceTextTruncated || text !== entry.text;
+      transcript.push({
+        role: entry.role,
+        text: truncated ? `${text}\n[transcript entry truncated]` : text,
+        ...(entry.name === undefined ? {} : { name: entry.name }),
+        ...(entry.sourceToolCallId === undefined
+          ? {}
+          : toolMetadata(entry.sourceToolCallId, toolTimings)),
+        ...(entry.isError === undefined ? {} : { isError: entry.isError }),
+        ...(entry.timestamp === undefined
+          ? {}
+          : { timestamp: entry.timestamp }),
+      });
+    }
+    if (transcript.length < this.totalEntries) {
+      transcript.push({
+        role: "toolResult",
+        name: "transcript",
+        text: `[transcript truncated: retained ${transcript.length} of ${this.totalEntries} entries]`,
+      });
+    }
+    return {
+      preview: this.preview,
+      usage: {
+        ...this.usage,
+        ...(typeof this.contextTokens === "number"
+          ? { contextTokens: this.contextTokens }
+          : {}),
+      },
+      latestAssistant: this.latestAssistant,
+      transcript,
+    };
+  }
+}
+
+export function transcriptFromMessages(
+  messages: AgentMessage[],
+  toolTimings: ReadonlyMap<string, ProgressToolTiming> = new Map(),
+) {
+  return new AgentProgressProjection(messages).snapshot(toolTimings).transcript;
+}

package/extensions/workflows/prompt.ts

@@ -1,4 +1,9 @@
+import {
+  allocateResultBudgets,
+  type ParentContextUsage,
+} from "../shared/result-budget.ts";
 import { sanitizeTerminalText } from "../shared/terminal-text.ts";
+import { projectText } from "../shared/text-projection.ts";
 import {
   countStates,
   formatElapsed,
@@ -7,20 +12,21 @@ import {
   type WorkflowDetails,
 } from "./model.ts";
 
-/** Model-facing schema descriptions for workflow source, arguments, and background mode. */
+/** Model-facing schema descriptions for workflow source and launch policy. */
 export const WORKFLOW_PARAMETER_DESCRIPTIONS = {
   script:
     "JavaScript workflow script. May start with `export const meta = {...}`, then use phase(), agent(), parallel(), args, and a final `return`.",
   args: "Optional JSON string exposed to the script as `args` (parsed when valid JSON, otherwise passed through as the raw string).",
   background:
-    "Run in the background: the tool returns a run id immediately and you receive a follow-up message when the workflow finishes. Defaults to false (blocking with live progress).",
+    "Deprecated compatibility alias for published callers only; new calls must use wait. Replace true with wait=false and false with wait=true. Do not provide both fields. The alias will be removed in the next announced breaking release.",
+  wait: "Wait for the final result in this tool call. Interactive sessions default to false and deliver completion later; print/automation defaults to true. Interrupting the wait does not cancel the workflow.",
   resumeFromRunId:
     "Optional prior run id or unique suffix for safe read-only replay. See the workflows Skill for matching rules.",
 };
 
-/** Describes stopping a running background workflow, mirroring subagent_cancel/bg_kill. */
+/** Describes stopping a running workflow, mirroring subagent_cancel/bg_kill. */
 export const WORKFLOW_STOP_TOOL_DESCRIPTION =
-  "Cancel a running background workflow by its run id (from the workflow launch result). This aborts its remaining agents and settles the run; partial results and artifacts are preserved. Only background runs need this — a blocking workflow is already cancelled by interrupting the turn.";
+  "Cancel a running workflow by its run id (from the workflow launch result). This aborts its remaining agents and settles the run; partial results and artifacts are preserved.";
 
 /** Model-facing schema description for the workflow run id to stop. */
 export const WORKFLOW_STOP_PARAMETER_DESCRIPTIONS = {
@@ -29,7 +35,7 @@ export const WORKFLOW_STOP_PARAMETER_DESCRIPTIONS = {
 
 /** Describes nonblocking inspection of workflow runs, mirroring subagent_check/subagent_list. */
 export const WORKFLOW_STATUS_TOOL_DESCRIPTION =
-  "Peek at background workflow runs without blocking. With a run id, returns that run's phases, per-agent status, and result if finished; without one, lists this session's active and recently finished runs. Does not wait — use background:false when you need the result inline.";
+  "Peek at workflow runs without blocking. With a run id, returns a bounded status and coverage summary plus the artifact location; without one, lists this session's active and recently finished runs. Does not wait, consume a completion, or repeat the full final result.";
 
 /** Model-facing schema description for the optional workflow run id to inspect. */
 export const WORKFLOW_STATUS_PARAMETER_DESCRIPTIONS = {
@@ -44,9 +50,11 @@ export const WORKFLOW_LIFECYCLE_PROMPT_SNIPPET =
 /** Compact resident contract; the workflows Skill carries the complete guide. */
 export const WORKFLOW_TOOL_DESCRIPTION = [
   "Use the workflow tool when the user explicitly requests a workflow run or when the task clearly requires multi-phase dynamic orchestration.",
-  "Write an async JavaScript body using optional meta, phase(), log(), usage(), agent(), pipeline(), parallel(), args, and a JSON-serializable return.",
+  "Write an async JavaScript body using optional meta, phase(), log(), usage(), agent(), pipeline(), parallel(), args, and a JSON-serializable return. usage().limits reports the resolved concurrency and remaining call capacity.",
   "agent() returns { ok, output, structured?, ref?, error? }; always check `.ok`, use a schema for branching, and surface failed or null results.",
   "Prefer pipeline() for independent multi-stage items. Use parallel() only for a real barrier where the next step needs every prior result.",
+  "Interactive sessions launch in the background by default and deliver completion later. Set wait: true only when this tool call must return the final result inline.",
+  "Derive fan-out from independent verifiable work items and task difficulty. Concurrency is a runtime ceiling, not a target or the total-call limit; user cost, count, model, and effort constraints take precedence.",
   "For concurrent writers use isolation: 'worktree' and tell each agent to commit. Read-only work should normally stay in the shared checkout.",
   "Read the workflows Skill before a nontrivial script; it covers the restricted sandbox, full DSL, acceptance, result refs, replay, background lifecycle, limits, and examples.",
 ].join("\n");
@@ -80,11 +88,11 @@ export function buildWorkflowResultMessage(
   details: WorkflowDetails,
   runDir: string,
 ) {
-  const { done, failed } = countStates(details);
+  const { done, failed, uncertain } = countStates(details);
   const elapsed = formatElapsed(details.startedAt, details.finishedAt);
   const lines = [
     `Workflow ${details.name ? `"${details.name}"` : details.runId} ${details.status} — ` +
-      `${done}/${details.agents.length} agents ok${failed ? `, ${failed} failed` : ""} ` +
+      `${done}/${details.agents.length} agents ok${failed ? `, ${failed} failed` : ""}${uncertain ? `, ${uncertain} uncertain` : ""} ` +
       `across ${details.phases.length} phase(s) in ${elapsed}.`,
     `Run dir: ${shortenHome(runDir)}`,
   ];
@@ -144,7 +152,9 @@ export function buildWorkflowResultMessage(
             : "ok"
           : agent.state === "error"
             ? "FAILED"
-            : "running";
+            : agent.state === "uncertain"
+              ? "UNCERTAIN"
+              : "running";
       lines.push(
         `- [${agent.label}]${agent.phase ? ` (${agent.phase})` : ""} ${status}` +
           (agent.acceptance ? ` · acceptance ${agent.acceptance.status}` : "") +
@@ -157,6 +167,31 @@ export function buildWorkflowResultMessage(
   return sanitizeTerminalText(lines.join("\n"));
 }
 
+/** One bounded model projection; exact run/agent results remain in artifacts. */
+export function buildProjectedWorkflowResultMessage(
+  details: WorkflowDetails,
+  runDir: string,
+  usage?: ParentContextUsage | null,
+) {
+  const full = buildWorkflowResultMessage(details, runDir);
+  const allocation = allocateResultBudgets(
+    [Buffer.byteLength(full, "utf8")],
+    usage,
+    {
+      maxBatchBytes: 48 * 1024,
+      maxResultBytes: 48 * 1024,
+      minResultBytes: 8 * 1024,
+      headroomShare: 0.25,
+      estimatedBytesPerToken: 4,
+    },
+  );
+  return projectText(full, {
+    maxBytes: allocation.budgets[0] ?? 8 * 1024,
+    maxLines: 400,
+    recovery: `Full workflow evidence is available in ${shortenHome(runDir)}.`,
+  });
+}
+
 /** Builds the follow-up message that delivers a settled background workflow to the parent model. */
 export function buildBackgroundWorkflowFollowUp(options: {
   runId: string;
@@ -167,7 +202,107 @@ export function buildBackgroundWorkflowFollowUp(options: {
   // Sentence lead-in matching the subagent/terminal completion messages.
   const label = options.name ? `"${options.name}"` : options.runId;
   const verb = options.status === "completed" ? "finished" : options.status;
-  return `Background workflow ${label} (${options.runId}) ${verb}.\n\n${options.result}`;
+  return `Background workflow ${label} (${options.runId}) ${verb}.\n\n${options.result}\n\n(This result is already shown to the user. Act on it and relay only the decisions or next steps — do not repeat it verbatim.)`;
+}
+
+/** Fairly project one transport batch against the parent's current headroom. */
+export function buildProjectedWorkflowCompletionBatch(
+  entries: readonly {
+    deliveryId: string;
+    details: WorkflowDetails;
+    runDir: string;
+  }[],
+  usage?: ParentContextUsage | null,
+) {
+  const deliveryFacts = JSON.stringify(
+    entries.map(({ deliveryId, details, runDir }) => ({
+      deliveryId,
+      runId: details.runId,
+      evidence: shortenHome(runDir),
+    })),
+  );
+  const manifest =
+    "Workflow completion delivery facts (stable across retries; deduplicate by deliveryId):\n" +
+    deliveryFacts;
+  const full = entries.map(({ deliveryId, details, runDir }) =>
+    buildBackgroundWorkflowFollowUp({
+      runId: details.runId,
+      name: details.name,
+      status: details.status,
+      result: `${buildWorkflowResultMessage(details, runDir)}\n\nDelivery id: ${deliveryId}`,
+    }),
+  );
+  const separatorBytes = Math.max(0, entries.length - 1) * 2;
+  const manifestSeparatorBytes = entries.length > 0 ? 2 : 0;
+  const fixedBytes =
+    Buffer.byteLength(manifest, "utf8") +
+    separatorBytes +
+    manifestSeparatorBytes;
+  const bodyBudget = 48 * 1024 - fixedBytes;
+  if (bodyBudget < 0) {
+    throw new Error(
+      "Workflow completion delivery facts exceed the transport payload limit",
+    );
+  }
+  const allocation = allocateResultBudgets(
+    full.map((message) => Buffer.byteLength(message, "utf8")),
+    usage,
+    {
+      maxBatchBytes: bodyBudget,
+      maxResultBytes: 48 * 1024,
+      minResultBytes: 1024,
+      headroomShare: 0.25,
+      estimatedBytesPerToken: 4,
+      fixedBytes,
+    },
+  );
+  const projected = full
+    .map((message, index) =>
+      projectText(message, {
+        maxBytes: allocation.budgets[index] ?? 1024,
+        maxLines: 400,
+        recovery: `Full workflow evidence is available in ${shortenHome(entries[index]!.runDir)}; duplicate deliveries carry the same delivery id.`,
+      }),
+    )
+    .join("\n\n");
+  return projected ? `${manifest}\n\n${projected}` : manifest;
+}
+
+/** Split transport batches so every manifest and projected body fit together. */
+export function buildProjectedWorkflowCompletionBatches(
+  entries: readonly {
+    deliveryId: string;
+    details: WorkflowDetails;
+    runDir: string;
+  }[],
+  usage?: ParentContextUsage | null,
+) {
+  const batches: Array<{
+    entries: (typeof entries)[number][];
+    content: string;
+  }> = [];
+  let current: (typeof entries)[number][] = [];
+  for (const entry of entries) {
+    const candidate = [...current, entry];
+    try {
+      buildProjectedWorkflowCompletionBatch(candidate, usage);
+      current = candidate;
+    } catch (error) {
+      if (current.length === 0) throw error;
+      batches.push({
+        entries: current,
+        content: buildProjectedWorkflowCompletionBatch(current, usage),
+      });
+      current = [entry];
+    }
+  }
+  if (current.length > 0) {
+    batches.push({
+      entries: current,
+      content: buildProjectedWorkflowCompletionBatch(current, usage),
+    });
+  }
+  return batches;
 }
 
 /** Builds the background-launch result and tells the parent model how to inspect or stop the run. */
@@ -182,3 +317,24 @@ export function buildBackgroundWorkflowLaunchResult(options: {
     `Its result will be delivered to you when it finishes, or use workflow_status(runId: "${options.runId}") to peek and workflow_stop(runId: "${options.runId}") to cancel; /workflows shows progress.`,
   ].join("\n");
 }
+
+/** Pure observation: bounded status/coverage without replaying final output. */
+export function buildWorkflowStatusSummary(
+  details: WorkflowDetails,
+  runDir: string,
+) {
+  const { done, failed, uncertain } = countStates(details);
+  const settled = done + failed;
+  return [
+    `Workflow ${details.name ? `"${details.name}"` : details.runId} ${details.status}.`,
+    details.status === "uncertain"
+      ? "Recovery warning: the prior owner disappeared without terminal evidence; some external effects may have occurred."
+      : undefined,
+    `Coverage: ${settled}/${details.agents.length} agents settled (${done} ok, ${failed} failed)${uncertain ? `; ${uncertain} uncertain` : ""}.`,
+    details.currentPhase ? `Current phase: ${details.currentPhase}` : undefined,
+    details.delivery ? `Delivery: ${details.delivery.state}.` : undefined,
+    `Artifacts: ${shortenHome(runDir)}`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/extensions/workflows/replay-safety.ts

@@ -1,5 +1,5 @@
-import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import { homedir } from "node:os";
 import * as path from "node:path";
@@ -17,6 +17,9 @@ const REPLAY_FILESYSTEM_TOOL_NAMES = new Set([
   "ls",
   "fd",
   "rg",
+  "git_show",
+  "git_diff",
+  "git_log",
 ]);
 const REPLAY_BUILTIN_FILESYSTEM_TOOL_NAMES = new Set([
   "read",
@@ -24,7 +27,13 @@ const REPLAY_BUILTIN_FILESYSTEM_TOOL_NAMES = new Set([
   "find",
   "ls",
 ]);
-const REPLAY_PACKAGE_FILESYSTEM_TOOL_NAMES = new Set(["fd", "rg"]);
+const REPLAY_PACKAGE_FILESYSTEM_TOOL_NAMES = new Set([
+  "fd",
+  "rg",
+  "git_show",
+  "git_diff",
+  "git_log",
+]);
 const GIT_OUTPUT_LIMIT = 32 * 1024 * 1024;
 const REPLAY_IDENTITY_TIMEOUT_MS = 5_000;
 const REPLAY_RESOURCE_FILE_LIMIT = 8 * 1024 * 1024;
@@ -179,12 +188,13 @@ function hasKnownReplayFilesystemImplementation(tool: {
     );
   }
   if (!REPLAY_PACKAGE_FILESYSTEM_TOOL_NAMES.has(tool.name)) return false;
+  // fd/rg come from file-search; the read-only git tools from git-read.
+  const ownerSourceSuffix = tool.name.startsWith("git_")
+    ? "/extensions/git-read/index.ts"
+    : "/extensions/file-search/index.ts";
   return (
     tool.sourceInfo?.origin === "package" &&
-    tool.sourceInfo.path
-      .split(path.sep)
-      .join("/")
-      .endsWith("/extensions/file-search/index.ts")
+    tool.sourceInfo.path.split(path.sep).join("/").endsWith(ownerSourceSuffix)
   );
 }
 
@@ -413,13 +423,44 @@ function canonicalPath(value: string) {
   return fs.realpathSync.native(value);
 }
 
-function repositoryFingerprint(cwd: string) {
+function deadlineBoundGitRunner() {
+  // One budget per fingerprint call: every git invocation shares a single
+  // deadline.
   const deadline = Date.now() + REPLAY_IDENTITY_TIMEOUT_MS;
-  const git = (gitCwd: string, args: readonly string[]) =>
+  return (gitCwd: string, args: readonly string[]) =>
     boundedGit(gitCwd, args, deadline);
-  const root = canonicalPath(git(cwd, ["rev-parse", "--show-toplevel"]).trim());
-  const head = git(root, ["rev-parse", "--verify", "HEAD"]).trim();
-  const diff = git(root, [
+}
+
+export function repositoryFingerprint(
+  cwd: string,
+  runGit: (
+    gitCwd: string,
+    args: readonly string[],
+  ) => string = deadlineBoundGitRunner(),
+) {
+  const root = canonicalPath(
+    runGit(cwd, ["rev-parse", "--show-toplevel"]).trim(),
+  );
+  const assertNoIgnoredFiles = () => {
+    // Ignored files are observable to a read-capable child but are commonly
+    // too large or secret-bearing to hash (node_modules, .env, build output).
+    // A complete identity cannot pretend they do not exist, so disable replay.
+    const ignoredOutput = runGit(root, [
+      "ls-files",
+      "--others",
+      "--ignored",
+      "--exclude-standard",
+      "--directory",
+      "-z",
+    ]);
+    if (ignoredOutput.length > 0) {
+      throw new Error("ignored files make the replay identity incomplete");
+    }
+  };
+  // The common disqualifying case exits before the expensive binary diff.
+  assertNoIgnoredFiles();
+  const head = runGit(root, ["rev-parse", "--verify", "HEAD"]).trim();
+  const diff = runGit(root, [
     "diff",
     "--no-ext-diff",
     "--no-textconv",
@@ -427,7 +468,7 @@ function repositoryFingerprint(cwd: string) {
     "HEAD",
     "--",
   ]);
-  const trackedModes = git(root, ["ls-files", "-s", "-z"]);
+  const trackedModes = runGit(root, ["ls-files", "-s", "-z"]);
   // Tracked symlinks can expose changing content outside Git, while gitlinks
   // can expose submodule state absent from the parent diff. Neither has a
   // complete bounded identity here, so execute instead of replaying.
@@ -440,21 +481,11 @@ function repositoryFingerprint(cwd: string) {
   ) {
     throw new Error("symlinks and gitlinks make replay identity incomplete");
   }
-  // Ignored files are observable to a read-capable child but are commonly too
-  // large or secret-bearing to hash (node_modules, .env, build output). A
-  // complete identity cannot pretend they do not exist, so disable replay.
-  const ignoredOutput = git(root, [
-    "ls-files",
-    "--others",
-    "--ignored",
-    "--exclude-standard",
-    "--directory",
-    "-z",
-  ]);
-  if (ignoredOutput.length > 0) {
-    throw new Error("ignored files make the replay identity incomplete");
-  }
-  const untrackedOutput = git(root, [
+  // Preserve the original post-diff safety observation: an ignored file can
+  // appear while the synchronous diff is running, including from another
+  // process. The early check is only an optimization, never the final gate.
+  assertNoIgnoredFiles();
+  const untrackedOutput = runGit(root, [
     "ls-files",
     "--others",
     "--exclude-standard",