pi-workflow-engine 0.12.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/src/provider-usage-limit.ts

@@ -1,8 +1,10 @@
 import { WorkflowPauseError } from "./cancellation.ts";
+import { isRecord } from "./guards.ts";
 import {
   WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
   type ResolvedWorkflowRunOptions,
 } from "./options.ts";
+import { truncateText } from "./text.ts";
 import type { WorkflowProviderUsageLimitPause } from "./workflow-run-record.ts";
 
 export const WORKFLOW_PROVIDER_USAGE_LIMIT_CODE = "WORKFLOW_PROVIDER_USAGE_LIMIT";
@@ -43,25 +45,33 @@ export class WorkflowProviderUsageLimitError extends WorkflowPauseError {
   }
 }
 
-export function providerUsageLimitFromMessages(
-  messages: readonly unknown[],
-  now = Date.now(),
-): WorkflowProviderUsageLimitError | undefined {
+/** The last assistant message when it ended its turn with a provider error, its error text ("" if absent), and its non-empty provider metadata. */
+export function lastAssistantError(messages: readonly unknown[]) {
   const message = messages.findLast(isAssistantMessage);
   if (!message || message.stopReason !== "error") return undefined;
-  const providerMessage = typeof message.errorMessage === "string" ? message.errorMessage.trim() : "";
-  if (!providerMessage || !isUsageLimitMessage(providerMessage)) return undefined;
-  const reset = parseProviderResetHint(providerMessage, now);
   const provider = stringDetail(message.provider);
   const model = stringDetail(message.model);
   const api = stringDetail(message.api);
+  return {
+    message,
+    errorMessage: typeof message.errorMessage === "string" ? message.errorMessage : "",
+    details: { ...(provider ? { provider } : {}), ...(model ? { model } : {}), ...(api ? { api } : {}) },
+  };
+}
+
+export function providerUsageLimitFromMessages(
+  messages: readonly unknown[],
+  now = Date.now(),
+): WorkflowProviderUsageLimitError | undefined {
+  const failure = lastAssistantError(messages);
+  if (!failure) return undefined;
+  const providerMessage = failure.errorMessage.trim();
+  if (!providerMessage || !isUsageLimitMessage(providerMessage)) return undefined;
   return new WorkflowProviderUsageLimitError({
     stopReason: "error",
     providerMessage,
-    ...(provider ? { provider } : {}),
-    ...(model ? { model } : {}),
-    ...(api ? { api } : {}),
-    ...reset,
+    ...failure.details,
+    ...parseProviderResetHint(providerMessage, now),
   });
 }
 
@@ -119,8 +129,9 @@ export function parseProviderResetHint(
       : { resetHint: boundedHint(iso) };
   }
 
+  // Units must be whole words on the hint's line ("6m0s" stays compact; "1 month" and "30\nmessage" are not durations).
   const labelled = message.match(
-    /(?:retry[- ]after|try again in|resets? in|available again in|x-ratelimit-reset(?:-[a-z-]+)?)\s*[:=]?\s*((?:\d+(?:\.\d+)?\s*(?:milliseconds?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)\s*)+)/i,
+    /(?:retry[- ]after|try again in|resets? in|available again in|x-ratelimit-reset(?:-[a-z-]+)?)\s*[:=]?\s*((?:\d+(?:\.\d+)?[ \t]*(?:milliseconds?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)(?![a-z])[ \t]*)+)/i,
   );
   if (labelled?.[1]) {
     const delayMs = parseDurationMs(labelled[1]);
@@ -150,27 +161,24 @@ function isUsageLimitMessage(message: string): boolean {
     || /\b(?:usage|rate)\s+limit\s+(?:(?:has\s+been|was)\s+)?(?:reached|exceeded)\b/i.test(message);
 }
 
+/** Sum a duration already captured by parseProviderResetHint's labelled grammar. */
 function parseDurationMs(value: string): number | undefined {
   const unitPattern = /(\d+(?:\.\d+)?)\s*(milliseconds?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)/gi;
   let total = 0;
-  let matched = "";
   for (const part of value.matchAll(unitPattern)) {
     const amount = Number(part[1]);
-    const unit = part[2]?.toLowerCase();
-    if (!Number.isFinite(amount) || !unit) return undefined;
-    matched += part[0];
+    const unit = (part[2] ?? "").toLowerCase();
     if (unit === "ms" || unit.startsWith("millisecond")) total += amount;
     else if (unit === "s" || unit.startsWith("sec")) total += amount * 1_000;
     else if (unit === "m" || unit.startsWith("min")) total += amount * 60_000;
     else if (unit === "h" || unit.startsWith("hr") || unit.startsWith("hour")) total += amount * 3_600_000;
     else total += amount * 86_400_000;
   }
-  if (!matched || value.replace(/\s+/g, "") !== matched.replace(/\s+/g, "")) return undefined;
-  return Number.isFinite(total) && total >= 0 ? total : undefined;
+  return Number.isFinite(total) ? total : undefined;
 }
 
 function boundedHint(value: string): string {
-  return value.length <= MAX_RESET_HINT_LENGTH ? value : `${value.slice(0, MAX_RESET_HINT_LENGTH - 1)}…`;
+  return truncateText(value, MAX_RESET_HINT_LENGTH);
 }
 
 function isAssistantMessage(value: unknown): value is {
@@ -181,7 +189,7 @@ function isAssistantMessage(value: unknown): value is {
   readonly model?: unknown;
   readonly api?: unknown;
 } {
-  return typeof value === "object" && value !== null && "role" in value && value.role === "assistant";
+  return isRecord(value) && value.role === "assistant";
 }
 
 function stringDetail(value: unknown): string | undefined {

package/.pi/extensions/pi-workflow-engine/src/replay-path-identity.ts

@@ -1,5 +1,5 @@
-import { relative, resolve, sep } from "node:path";
-import { isPathWithin } from "./tree-fingerprint.ts";
+import { resolve } from "node:path";
+import { isPathWithin, portableRelativePath } from "./tree-fingerprint.ts";
 
 export interface ReplayWorkspaceRoots {
   readonly sessionCwd: string;
@@ -20,11 +20,6 @@ export function normalizeWorkspaceReferences(value: string, roots: ReplayWorkspa
   return paths.reduce((normalized, path) => replacePathPrefix(normalized, path, "<workspace>"), value);
 }
 
-export function portableRelativePath(root: string, path: string): string {
-  const value = relative(root, path).split(sep).join("/");
-  return value.length === 0 ? "." : value;
-}
-
 function resolvedWorkspaceRoots(roots: ReplayWorkspaceRoots): readonly string[] {
   return [...new Set([resolve(roots.sessionCwd), resolve(roots.workspaceRoot)])];
 }

package/.pi/extensions/pi-workflow-engine/src/research-contract.ts

@@ -39,7 +39,6 @@ export const ResearchEvidenceSchema = Type.Object({
 export type ResearchEvidence = Static<typeof ResearchEvidenceSchema>;
 
 export const ResearchLaneResultSchema = Type.Object({
-  laneId: Type.String({ minLength: 1 }),
   evidence: Type.Array(ResearchEvidenceSchema, { maxItems: MAX_LANE_EVIDENCE }),
   gaps: Type.Array(Type.String()),
 });

package/.pi/extensions/pi-workflow-engine/src/research-evidence.ts

@@ -1,5 +1,4 @@
 import {
-  MAX_RESEARCH_LANES,
   MAX_VERIFICATION_CLAIMS,
   type ResearchClaimCandidate,
   type ResearchEvidence,
@@ -22,31 +21,21 @@ export function normalizeResearchLanes(plan: ResearchPlan): ResearchLane[] {
     const id = normalizedText(lane.id);
     const title = normalizedText(lane.title);
     const objective = normalizedText(lane.objective);
-    const queries = dedupeText(lane.queries).slice(0, 4);
+    const queries = dedupeText(lane.queries);
     if (!id || !title || !objective || queries.length === 0 || seen.has(id.toLowerCase())) continue;
     seen.add(id.toLowerCase());
     lanes.push({ id, title, objective, queries });
-    if (lanes.length >= MAX_RESEARCH_LANES) break;
   }
   return lanes;
 }
 
-export function sanitizeLaneResults(results: readonly ResearchLaneResult[]): ResearchLaneResult[] {
-  return results.map((result) => ({
-    laneId: normalizedText(result.laneId),
-    gaps: dedupeText(result.gaps),
-    evidence: dedupeEvidence(result.evidence.map(sanitizeEvidence).filter(isDefined)),
-  }));
-}
-
 export function buildClaimCandidates(results: readonly ResearchLaneResult[]): ResearchClaimCandidate[] {
   const byClaim = new Map<string, { claim: string; importance: ResearchEvidence["importance"]; evidence: ResearchEvidence[] }>();
-  for (const item of results.flatMap((result) => result.evidence)) {
-    const key = normalizedText(item.claim).toLowerCase();
-    if (!key) continue;
+  for (const item of results.flatMap((result) => result.evidence.map(sanitizeEvidence).filter(isDefined))) {
+    const key = item.claim.toLowerCase();
     const current = byClaim.get(key);
     if (!current) {
-      byClaim.set(key, { claim: normalizedText(item.claim), importance: item.importance, evidence: [item] });
+      byClaim.set(key, { claim: item.claim, importance: item.importance, evidence: [item] });
       continue;
     }
     if (IMPORTANCE_RANK[item.importance] < IMPORTANCE_RANK[current.importance]) current.importance = item.importance;
@@ -142,10 +131,7 @@ function verificationSources(
   return byClaim;
 }
 
-export function fallbackResearchReport(
-  verifications: readonly ResearchVerification[],
-  limitation: string,
-): ResearchReport {
+export function fallbackResearchReport(verifications: readonly ResearchVerification[]): ResearchReport {
   const entry = (verification: ResearchVerification): ResearchReportEntry => ({
     claim: verification.claim,
     explanation: verification.explanation,
@@ -158,22 +144,32 @@ export function fallbackResearchReport(
     uncertainties: verifications.filter((item) => item.verdict === "UNCERTAIN").map(entry),
     inferences: verifications.filter((item) => item.verdict === "INFERENCE").map(entry),
     sources: dedupeSources(verifications.flatMap((verification) => verification.sources)),
-    limitations: [limitation],
+    limitations: ["The synthesis stage failed; verified claims are listed without a narrative answer."],
     nextSteps: ["Review the verified claim groups and rerun synthesis if a narrative answer is required."],
   };
 }
 
-export function unavailableResearchReport(reason: "empty-question" | "missing-capability" | "no-evidence"): ResearchReport {
-  const message = reason === "empty-question"
-    ? "No research question was provided."
-    : reason === "missing-capability"
-      ? "Research could not start because pi exposed no installed external web-search or URL-extraction tool."
-      : "Research completed without enough direct-page evidence to support an answer.";
-  const nextStep = reason === "empty-question"
-    ? "Run `/workflow research <question>` and include any source, date, or geography constraints in the arguments."
-    : reason === "missing-capability"
-      ? "Install or enable a pi tool that can search the web or extract HTTP(S) pages, then rerun the workflow."
-      : "Check the installed external-search tool, narrow the question, or provide preferred source domains.";
+const UNAVAILABLE_RESEARCH = {
+  "empty-question": {
+    message: "No research question was provided.",
+    nextStep: "Run `/workflow research <question>` and include any source, date, or geography constraints in the arguments.",
+  },
+  "missing-capability": {
+    message: "Research could not start because pi exposed no installed external web-search or URL-extraction tool.",
+    nextStep: "Install or enable a pi tool that can search the web or extract HTTP(S) pages, then rerun the workflow.",
+  },
+  "lanes-failed": {
+    message: "Research could not gather direct-page evidence because one or more research lanes failed.",
+    nextStep: "Check the installed external-search tool and its provider, then rerun the workflow.",
+  },
+  "no-evidence": {
+    message: "Research completed without enough direct-page evidence to support an answer.",
+    nextStep: "Check the installed external-search tool, narrow the question, or provide preferred source domains.",
+  },
+} as const;
+
+export function unavailableResearchReport(reason: keyof typeof UNAVAILABLE_RESEARCH): ResearchReport {
+  const { message, nextStep } = UNAVAILABLE_RESEARCH[reason];
   return {
     answer: message,
     supportedClaims: [],

package/.pi/extensions/pi-workflow-engine/src/resume-context.ts

@@ -1,16 +1,21 @@
-import { lstat } from "node:fs/promises";
+import type { Stats } from "node:fs";
+import { lstat, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { throwIfAborted } from "./cancellation.ts";
 import { isMissingPathError } from "./filesystem-error.ts";
+import { isGitObjectId, parseGitTopLevel, runGit } from "./git.ts";
+import { isRecord } from "./guards.ts";
 import type {
   EffectiveAgentSessionIdentity,
   EffectiveToolIdentity,
 } from "./agent-session-identity.ts";
-import { runBoundedProcess, type BoundedProcessResult } from "./process-runner.ts";
+import type { BoundedProcessResult } from "./process-runner.ts";
 import {
   BoundedFingerprint,
   captureDeclaredInputFingerprint,
-  captureTreeFingerprint,
+  captureSourceTreeFingerprint,
+  FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
+  isExcludedDeclaredInput,
   isPathWithin,
   resolveDeclaredInputPaths,
   validateTreeFile,
@@ -57,11 +62,8 @@ export interface AgentResumeBaseContext {
   readonly workflow: WorkflowResumeContext;
 }
 
-export interface VerifiedAgentResumeBaseContext {
+export interface AgentResumeContext {
   readonly workflow: VerifiedWorkflowResumeContext;
-}
-
-export interface AgentResumeContext extends VerifiedAgentResumeBaseContext {
   readonly repository: VerifiedRepositoryResumeContext;
   readonly session: EffectiveAgentSessionIdentity;
   readonly skills: readonly ResolvedSkillIdentity[];
@@ -85,7 +87,6 @@ type BoundedProcessFailureResult = Extract<BoundedProcessResult, { readonly ok:
 const GIT_CONTEXT_TIMEOUT_MS = 15_000;
 const GIT_CONTEXT_MAX_BYTES = 32 << 20;
 const CONTENT_FINGERPRINT_MAX_BYTES = 32 << 20;
-const SOURCE_TREE_MAX_FILES = 4096;
 const REPOSITORY_INPUT_MAX_ENTRIES = 4096;
 const GIT_UNTRACKED_MAX_ENTRIES = 32_768;
 const GIT_VISIBLE_PATHS = [
@@ -93,14 +94,6 @@ const GIT_VISIBLE_PATHS = [
   ":(exclude).pi/.workflow-runs/**",
   ":(glob,exclude)**/.pi/.workflow-runs/**",
 ] as const;
-export const FINGERPRINT_EXCLUDED_RELATIVE_PATHS = new Set([
-  ".git",
-  ".pi/.workflow-runs",
-]);
-
-export function unverifiableRepositoryResumeContext(reason: string): RepositoryResumeContext {
-  return { kind: "unverifiable", reason };
-}
 
 export function unverifiableWorkflowResumeContext(name: string, reason: string): WorkflowResumeContext {
   return { kind: "unverifiable", name, reason };
@@ -151,9 +144,9 @@ export async function captureIsolatedRepositoryContext(
       return { kind: "unverifiable", reason: "isolated baseline is not a full commit object ID" };
     }
     const [commit, tree, entries] = await Promise.all([
-      runGit(cwd, ["rev-parse", "--verify", `${baselineOid}^{commit}`], signal),
-      runGit(cwd, ["rev-parse", "--verify", `${baselineOid}^{tree}`], signal),
-      runGit(cwd, ["ls-tree", "-r", "-z", "--full-tree", baselineOid], signal),
+      runContextGit(cwd, ["rev-parse", "--verify", `${baselineOid}^{commit}`], signal),
+      runContextGit(cwd, ["rev-parse", "--verify", `${baselineOid}^{tree}`], signal),
+      runContextGit(cwd, ["ls-tree", "-r", "-z", "--full-tree", baselineOid], signal),
     ]);
     throwIfAborted(signal);
     if (!commit.ok) return { kind: "unverifiable", reason: processFailureReason("isolated baseline commit probe", commit) };
@@ -188,7 +181,7 @@ async function captureNonGitRepositoryContext(
   const capture = await captureRepositoryInputs(cwd, inputs, signal);
   return capture.kind === "verified"
     ? { kind: "verified", state: "non-git", workingTreeFingerprint: capture.fingerprint }
-    : unverifiableRepositoryResumeContext(capture.reason);
+    : capture;
 }
 
 async function captureRepositoryInputs(
@@ -239,7 +232,7 @@ async function inspectRepository(
   signal: AbortSignal | undefined,
 ): Promise<RepositoryInspection> {
   throwIfAborted(signal);
-  const probe = await runGit(cwd, ["rev-parse", "--is-inside-work-tree"], signal);
+  const probe = await runContextGit(cwd, ["rev-parse", "--is-inside-work-tree"], signal);
   throwIfAborted(signal);
   if (!probe.ok) {
     if (probe.failure.kind === "exit") {
@@ -257,8 +250,8 @@ async function inspectRepository(
   }
 
   const [rootResult, headResult] = await Promise.all([
-    runGit(cwd, ["rev-parse", "--show-toplevel"], signal),
-    runGit(cwd, ["rev-parse", "--verify", "--quiet", "HEAD"], signal),
+    runContextGit(cwd, ["rev-parse", "--show-toplevel"], signal),
+    runContextGit(cwd, ["rev-parse", "--verify", "--quiet", "HEAD"], signal),
   ]);
   throwIfAborted(signal);
   if (!rootResult.ok) {
@@ -282,57 +275,50 @@ async function captureGitVisibleState(
   signal: AbortSignal | undefined,
 ): Promise<FingerprintCapture> {
   try {
-    return await captureGitVisibleStateUnchecked(cwd, signal);
-  } catch (error) {
+    const diffFlags = [
+      "--binary",
+      "--full-index",
+      "--no-ext-diff",
+      "--no-textconv",
+      "--no-color",
+      "--ignore-submodules=none",
+    ] as const;
+    const [unstaged, unstagedRaw, staged, untrackedPaths, indexEntries, trackedFlags] = await Promise.all([
+      runContextGit(cwd, ["diff", ...diffFlags, "--", ...GIT_VISIBLE_PATHS], signal),
+      runContextGit(cwd, ["diff", "--raw", "-z", "--no-abbrev", "--no-renames", ...diffFlags.slice(2), "--", ...GIT_VISIBLE_PATHS], signal),
+      runContextGit(cwd, ["diff", "--cached", ...diffFlags, "--", ...GIT_VISIBLE_PATHS], signal),
+      runContextGit(cwd, ["ls-files", "--others", "--exclude-standard", "-z", "--", ...GIT_VISIBLE_PATHS], signal),
+      runContextGit(cwd, ["ls-files", "--stage", "--full-name", "-z"], signal),
+      runContextGit(cwd, ["ls-files", "-v", "--full-name", "-z"], signal),
+    ]);
     throwIfAborted(signal);
-    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
-  }
-}
 
-async function captureGitVisibleStateUnchecked(
-  cwd: string,
-  signal: AbortSignal | undefined,
-): Promise<FingerprintCapture> {
-  const diffFlags = [
-    "--binary",
-    "--full-index",
-    "--no-ext-diff",
-    "--no-textconv",
-    "--no-color",
-    "--ignore-submodules=none",
-  ] as const;
-  const [unstaged, unstagedRaw, staged, untrackedPaths, indexEntries, trackedFlags] = await Promise.all([
-    runGit(cwd, ["diff", ...diffFlags, "--", ...GIT_VISIBLE_PATHS], signal),
-    runGit(cwd, ["diff", "--raw", "-z", "--no-abbrev", "--no-renames", ...diffFlags.slice(2), "--", ...GIT_VISIBLE_PATHS], signal),
-    runGit(cwd, ["diff", "--cached", ...diffFlags, "--", ...GIT_VISIBLE_PATHS], signal),
-    runGit(cwd, ["ls-files", "--others", "--exclude-standard", "-z", "--", ...GIT_VISIBLE_PATHS], signal),
-    runGit(cwd, ["ls-files", "--stage", "--full-name", "-z"], signal),
-    runGit(cwd, ["ls-files", "-v", "--full-name", "-z"], signal),
-  ]);
-  throwIfAborted(signal);
+    const validated = validateGitVisibleOutputs({ unstaged, unstagedRaw, staged, untrackedPaths, indexEntries, trackedFlags });
+    if (!validated.ok) return { kind: "unverifiable", reason: validated.reason };
 
-  const validated = validateGitVisibleOutputs({ unstaged, unstagedRaw, staged, untrackedPaths, indexEntries, trackedFlags });
-  if (!validated.ok) return { kind: "unverifiable", reason: validated.reason };
+    const untracked = await captureDeclaredInputFingerprint({
+      root: cwd,
+      inputs: validated.untrackedPaths.filter((path) => !isExcludedDeclaredInput(path, FINGERPRINT_EXCLUDED_RELATIVE_PATHS)),
+      excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
+      maxBytes: CONTENT_FINGERPRINT_MAX_BYTES,
+      maxEntries: GIT_UNTRACKED_MAX_ENTRIES,
+      signal,
+    });
+    if (untracked.kind === "unverifiable") return untracked;
 
-  const untracked = await captureDeclaredInputFingerprint({
-    root: cwd,
-    inputs: validated.untrackedPaths.filter((path) => !isFingerprintExcludedPath(path)),
-    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
-    maxBytes: CONTENT_FINGERPRINT_MAX_BYTES,
-    maxEntries: GIT_UNTRACKED_MAX_ENTRIES,
-    signal,
-  });
-  if (untracked.kind === "unverifiable") return untracked;
-
-  return {
-    kind: "verified",
-    fingerprint: combineFingerprints([
-      ["unstaged", validated.unstaged],
-      ["staged", validated.staged],
-      ["index", validated.indexEntries],
-      ["untracked", untracked.fingerprint],
-    ]),
-  };
+    return {
+      kind: "verified",
+      fingerprint: combineFingerprints([
+        ["unstaged", validated.unstaged],
+        ["staged", validated.staged],
+        ["index", validated.indexEntries],
+        ["untracked", untracked.fingerprint],
+      ]),
+    };
+  } catch (error) {
+    throwIfAborted(signal);
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
 }
 
 interface GitVisibleProcessOutputs {
@@ -473,13 +459,7 @@ export async function captureWorkflowResumeContext(
     return unverifiableWorkflowResumeContext(mod.meta.name, `workflow source file is not part of its source tree: ${validation.reason}`);
   }
 
-  const current = await captureTreeFingerprint({
-    root: sourceRoot,
-    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
-    maxBytes: CONTENT_FINGERPRINT_MAX_BYTES,
-    maxFiles: SOURCE_TREE_MAX_FILES,
-    signal,
-  });
+  const current = await captureSourceTreeFingerprint(sourceRoot, signal);
   if (current.kind === "unverifiable") {
     return unverifiableWorkflowResumeContext(mod.meta.name, `workflow source tree could not be verified: ${current.reason}`);
   }
@@ -489,18 +469,20 @@ export async function captureWorkflowResumeContext(
   return { kind: "verified", name: mod.meta.name, sourceFingerprint: mod.source.fingerprint };
 }
 
-export function createAgentResumeContext(
-  base: VerifiedAgentResumeBaseContext,
-  repository: VerifiedRepositoryResumeContext,
-  session: EffectiveAgentSessionIdentity,
-  skills: readonly ResolvedSkillIdentity[],
-): AgentResumeContext {
-  return {
-    ...base,
-    repository,
-    session,
-    skills: [...skills],
-  };
+export function repositoryMismatchReason(
+  stored: VerifiedRepositoryResumeContext,
+  current: VerifiedRepositoryResumeContext,
+): string | undefined {
+  if (stored.state !== current.state) return "repository state changed";
+  if (
+    (stored.state === "git" || stored.state === "isolated") &&
+    (current.state === "git" || current.state === "isolated") &&
+    stored.head !== current.head
+  ) {
+    return stored.state === "git" ? "repository HEAD changed" : "isolated baseline changed";
+  }
+  if (stored.workingTreeFingerprint !== current.workingTreeFingerprint) return "working tree contents changed";
+  return undefined;
 }
 
 export function resumeContextMismatchReason(
@@ -508,17 +490,8 @@ export function resumeContextMismatchReason(
   current: AgentResumeContext,
   options: ResumeContextComparisonOptions = {},
 ): string | undefined {
-  if (stored.repository.state !== current.repository.state) return "repository state changed";
-  if (
-    (stored.repository.state === "git" || stored.repository.state === "isolated") &&
-    (current.repository.state === "git" || current.repository.state === "isolated") &&
-    stored.repository.head !== current.repository.head
-  ) {
-    return stored.repository.state === "git" ? "repository HEAD changed" : "isolated baseline changed";
-  }
-  if (stored.repository.workingTreeFingerprint !== current.repository.workingTreeFingerprint) {
-    return "working tree contents changed";
-  }
+  const repository = repositoryMismatchReason(stored.repository, current.repository);
+  if (repository) return repository;
   if (stored.workflow.name !== current.workflow.name) return "workflow name changed";
   if (
     !options.allowWorkflowSourceMismatch
@@ -559,22 +532,65 @@ export function isAgentResumeContext(value: unknown): value is AgentResumeContex
   );
 }
 
-async function runGit(cwd: string, args: readonly string[], signal: AbortSignal | undefined): Promise<BoundedProcessResult> {
-  return await runBoundedProcess({
-    file: "git",
-    args,
+async function runContextGit(cwd: string, args: readonly string[], signal: AbortSignal | undefined): Promise<BoundedProcessResult> {
+  return await runGit({
     cwd,
-    env: { ...process.env, GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" },
+    args,
+    label: "git resume-context capture",
     signal,
     timeoutMs: GIT_CONTEXT_TIMEOUT_MS,
     maxBufferBytes: GIT_CONTEXT_MAX_BYTES,
-    abortError: "git resume-context capture aborted",
-    timeoutError: `git resume-context capture timed out after ${GIT_CONTEXT_TIMEOUT_MS}ms`,
-    maxBufferError: `git resume-context capture exceeded ${GIT_CONTEXT_MAX_BYTES} bytes`,
-    exitError: (stderr, code, exitSignal) => stderr.trim() || `git exited with code ${code ?? `signal ${exitSignal ?? "unknown"}`}`,
   });
 }
 
+/**
+ * Decide whether a `.git` entry found during the ancestor walk marks a repository
+ * that git may have failed to open, or a stray entry that git's own discovery
+ * also skips.
+ *
+ * The rule mirrors git's discovery loop so that "absent" means git itself would
+ * have walked past every `.git` entry and its "not a repository" answer is
+ * authoritative:
+ *
+ * - A regular file is a gitfile. Git halts on any regular `.git` file, even when
+ *   its content is malformed or its `gitdir:` target is missing, so the entry is
+ *   a marker regardless of content.
+ * - A directory is a repository only when `HEAD`, `objects/`, and `refs/` all
+ *   exist. Git skips a directory that lacks any of them (an empty `.git` is the
+ *   common case), so such a directory is not a marker.
+ * - A symbolic link is resolved first, as git uses `stat`. A dangling link is
+ *   skipped by git and is therefore not a marker.
+ * - Any other entry type (socket, FIFO, device) is skipped by git.
+ *
+ * A missing path (`ENOENT`) is a negative answer, not a failure. Any other
+ * filesystem error propagates so the caller reports the probe as "unknown".
+ */
+async function isRepositoryMarker(entryPath: string, entry: Stats): Promise<boolean> {
+  let target = entry;
+  if (entry.isSymbolicLink()) {
+    const resolved = await statIfPresent(entryPath);
+    if (!resolved) return false;
+    target = resolved;
+  }
+  if (target.isFile()) return true;
+  if (!target.isDirectory()) return false;
+  for (const name of GIT_DIRECTORY_REQUIRED_ENTRIES) {
+    if (!(await statIfPresent(join(entryPath, name)))) return false;
+  }
+  return true;
+}
+
+const GIT_DIRECTORY_REQUIRED_ENTRIES = ["HEAD", "objects", "refs"] as const;
+
+async function statIfPresent(path: string): Promise<Stats | undefined> {
+  try {
+    return await stat(path);
+  } catch (error) {
+    if (isMissingPathError(error)) return undefined;
+    throw error;
+  }
+}
+
 type GitControlPathResult =
   | { readonly kind: "present" | "absent" }
   | { readonly kind: "unknown"; readonly reason: string };
@@ -583,9 +599,10 @@ async function findGitControlPath(cwd: string, signal: AbortSignal | undefined):
   let current = resolve(cwd);
   while (true) {
     throwIfAborted(signal);
+    const entryPath = join(current, ".git");
     try {
-      await lstat(join(current, ".git"));
-      return { kind: "present" };
+      const entry = await lstat(entryPath);
+      if (await isRepositoryMarker(entryPath, entry)) return { kind: "present" };
     } catch (error) {
       if (!isMissingPathError(error)) {
         return { kind: "unknown", reason: `git control-path probe failed: ${unknownErrorMessage(error)}` };
@@ -665,37 +682,6 @@ function parseNullTerminatedRecords(output: string, operation: string): string[]
   return output.slice(0, -1).split("\0");
 }
 
-function parseGitTopLevel(output: string, cwd: string): string | undefined {
-  const withoutLf = output.endsWith("\n") ? output.slice(0, -1) : output;
-  const value = withoutLf.endsWith("\r") ? withoutLf.slice(0, -1) : withoutLf;
-  if (value.length === 0 || value.includes("\n") || value.includes("\0")) return undefined;
-  const root = resolve(cwd, value);
-  return isPathWithin(root, cwd) ? root : undefined;
-}
-
-function isGitObjectId(value: string): boolean {
-  return /^[0-9a-f]{40,64}$/i.test(value);
-}
-
-function isFingerprintExcludedPath(path: string): boolean {
-  const normalized = path.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
-  for (const excluded of FINGERPRINT_EXCLUDED_RELATIVE_PATHS) {
-    if (
-      normalized === excluded ||
-      normalized.startsWith(`${excluded}/`) ||
-      normalized.endsWith(`/${excluded}`) ||
-      normalized.includes(`/${excluded}/`)
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
 function sanitizeProcessMessage(message: string): string {
   return message.trim().replace(/\s+/g, " ").slice(0, 500);
 }