@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/lib/internal/task-orchestration.ts

@@ -0,0 +1,171 @@
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
+import {
+  activateMatchingOrchestrationDelegation,
+  activateOrchestrationDelegation,
+  advanceOrchestration,
+  beginOrResumeOrchestration,
+  completeCommitOrchestrationStage,
+  pauseOrchestration,
+  prepareOrchestrationDelegation,
+  routeOrchestration,
+  sealMatchingOrchestrationDelegation,
+  sealOrchestrationDelegation,
+  statusOrchestration
+} from '../task/orchestration.ts';
+import { isAgentClientId } from '../agent-clients/types.ts';
+import type { AgentClientId } from '../agent-clients/types.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|hook-start|stage-completed|hook-stop|advance|pause|status> [options]\n';
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({
+    status: 'failed', changed: false,
+    error: { code: 'ORCHESTRATION_PAYLOAD_INVALID', message }
+  })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 2;
+}
+
+function taskOrchestration(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (args.length < 2) {
+    usageFailure('task ref and intent are required');
+    return;
+  }
+  const [taskRef, intent] = args;
+  if (!['begin-or-resume', 'route', 'prepare', 'hook-start', 'stage-completed', 'hook-stop', 'advance', 'pause', 'status'].includes(intent!)) {
+    usageFailure(`unknown intent '${intent}'`);
+    return;
+  }
+  const values: Record<string, string> = {};
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (![
+      '--max-steps', '--executor-model', '--executor-reasoning-effort',
+      '--reviewer-model', '--reviewer-reasoning-effort',
+      '--client', '--requested-model', '--requested-reasoning-effort', '--parent-id', '--before-fingerprint',
+      '--native-agent', '--child-id', '--spawn-mode', '--actual-model', '--actual-reasoning-effort',
+      '--model-fallback-reason', '--reasoning-effort-fallback-reason',
+      '--exit-code', '--after-fingerprint', '--changed-paths', '--code', '--message', '--recoverable', '--agent'
+    ].includes(flag)) {
+      usageFailure(`unknown option '${flag}'`);
+      return;
+    }
+    if (seen.has(flag)) {
+      usageFailure(`duplicate option '${flag}'`);
+      return;
+    }
+    seen.add(flag);
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      usageFailure(`option '${flag}' requires a value`);
+      return;
+    }
+    values[flag] = value;
+  }
+  const requireValues = (flags: string[]) => flags.find((flag) => values[flag] === undefined);
+  if (values['--client'] !== undefined && !isAgentClientId(values['--client'])) {
+    usageFailure(`unknown client '${values['--client']}'`);
+    return;
+  }
+  let result;
+  if (intent === 'begin-or-resume') {
+    const missing = requireValues(['--client']);
+    if (missing) { usageFailure(`intent 'begin-or-resume' requires '${missing}'`); return; }
+    const maxSteps = values['--max-steps'] === undefined ? undefined : Number(values['--max-steps']);
+    if (maxSteps !== undefined && (!Number.isInteger(maxSteps) || maxSteps < 1)) {
+      usageFailure('--max-steps must be a positive integer'); return;
+    }
+    const policyFlags = [
+      '--executor-model', '--executor-reasoning-effort',
+      '--reviewer-model', '--reviewer-reasoning-effort'
+    ];
+    const hasAnyPolicy = policyFlags.some((flag) => values[flag] !== undefined);
+    if (hasAnyPolicy && policyFlags.some((flag) => values[flag] === undefined)) {
+      usageFailure('explicit model policy requires executor/reviewer model and reasoning effort');
+      return;
+    }
+    result = beginOrResumeOrchestration(taskRef!, {
+      maxSteps,
+      client: values['--client'] as AgentClientId,
+      modelPolicy: hasAnyPolicy ? {
+        executor: {
+          model: values['--executor-model']!,
+          reasoningEffort: values['--executor-reasoning-effort']!
+        },
+        reviewer: {
+          model: values['--reviewer-model']!,
+          reasoningEffort: values['--reviewer-reasoning-effort']!
+        }
+      } : undefined
+    });
+  } else if (intent === 'route') {
+    result = routeOrchestration(taskRef!);
+  } else if (intent === 'status') {
+    result = statusOrchestration(taskRef!);
+  } else if (intent === 'prepare') {
+    const missing = requireValues(['--client']);
+    if (missing) { usageFailure(`intent 'prepare' requires '${missing}'`); return; }
+    result = prepareOrchestrationDelegation(taskRef!, {
+      client: values['--client'] as AgentClientId,
+      requestedModel: values['--requested-model'],
+      requestedReasoningEffort: values['--requested-reasoning-effort']
+    });
+  } else if (intent === 'hook-start') {
+    const missing = requireValues([
+      ...(taskRef === 'auto' ? ['--client'] : []),
+      '--native-agent', '--child-id', '--parent-id', '--spawn-mode'
+    ]);
+    if (missing) { usageFailure(`intent 'hook-start' requires '${missing}'`); return; }
+    const event = {
+      nativeAgent: values['--native-agent']!, childId: values['--child-id']!,
+      parentId: values['--parent-id']!, spawnMode: values['--spawn-mode']!,
+      actualModel: values['--actual-model'],
+      actualReasoningEffort: values['--actual-reasoning-effort'],
+      modelFallbackReason: values['--model-fallback-reason'],
+      reasoningEffortFallbackReason: values['--reasoning-effort-fallback-reason']
+    };
+    result = taskRef === 'auto'
+      ? activateMatchingOrchestrationDelegation(values['--client'] as AgentClientId, event)
+      : activateOrchestrationDelegation(taskRef!, event);
+  } else if (intent === 'hook-stop') {
+    if (taskRef === 'auto') {
+      const missing = requireValues(['--client', '--native-agent', '--child-id']);
+      if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
+      result = sealMatchingOrchestrationDelegation(values['--client'] as AgentClientId, {
+        nativeAgent: values['--native-agent']!, childId: values['--child-id']!
+      });
+    } else {
+      const missing = requireValues(['--child-id', '--exit-code', '--after-fingerprint']);
+      if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
+      const exitCode = Number(values['--exit-code']);
+      if (!Number.isInteger(exitCode)) { usageFailure('--exit-code must be an integer'); return; }
+      result = sealOrchestrationDelegation(taskRef!, {
+        childId: values['--child-id']!, exitCode,
+        afterFingerprint: values['--after-fingerprint']!,
+        changedPaths: values['--changed-paths'] ? values['--changed-paths']!.split(',').filter(Boolean) : []
+      });
+    }
+  } else if (intent === 'stage-completed') {
+    const missing = requireValues(['--agent']);
+    if (missing) { usageFailure(`intent 'stage-completed' requires '${missing}'`); return; }
+    const agent = normalizeAgentToken(values['--agent']!);
+    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
+    result = completeCommitOrchestrationStage(taskRef!, agent);
+  } else if (intent === 'advance') {
+    result = advanceOrchestration(taskRef!);
+  } else {
+    const missing = requireValues(['--code', '--message', '--recoverable']);
+    if (missing) { usageFailure(`intent 'pause' requires '${missing}'`); return; }
+    if (!['true', 'false'].includes(values['--recoverable']!)) { usageFailure('--recoverable must be true or false'); return; }
+    result = pauseOrchestration(taskRef!, values['--code']!, values['--message']!, values['--recoverable'] === 'true');
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskOrchestration };

package/lib/internal/task-review.ts

@@ -0,0 +1,70 @@
+import { finalizeReviewSummary } from '../task/review-finalization.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--orchestrated] [--dry-run]\n';
+
+function failUsage(message: string): void {
+  process.stdout.write(`${JSON.stringify({
+    status: 'failed',
+    changed: false,
+    intent: 'finalize-summary',
+    error: { code: 'REVIEW_PAYLOAD_INVALID', message }
+  })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 2;
+}
+
+function taskReview(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (args.length < 2) {
+    failUsage('task ref and intent are required');
+    return;
+  }
+  if (args[1] !== 'finalize-summary') {
+    failUsage(`unknown intent '${args[1]}'`);
+    return;
+  }
+  let stage = '';
+  let artifact = '';
+  let dryRun = false;
+  let orchestrated = false;
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!['--stage', '--artifact', '--orchestrated', '--dry-run'].includes(flag)) {
+      failUsage(`unknown option '${flag}'`);
+      return;
+    }
+    if (seen.has(flag)) {
+      failUsage(`duplicate option '${flag}'`);
+      return;
+    }
+    seen.add(flag);
+    if (flag === '--dry-run') {
+      dryRun = true;
+      continue;
+    }
+    if (flag === '--orchestrated') {
+      orchestrated = true;
+      continue;
+    }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      failUsage(`option '${flag}' requires a value`);
+      return;
+    }
+    if (flag === '--stage') stage = value;
+    else artifact = value;
+  }
+  if (!stage || !artifact) {
+    failUsage("options '--stage' and '--artifact' are required");
+    return;
+  }
+  const result = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskReview };

package/lib/merge.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { info, ok } from './log.ts';
+import { removeDirRecursive } from './remove-dir.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
@@ -690,7 +691,7 @@ function mergeMutableSections({ sourceWorkspace, localWorkspace, backupRoot, rep
       if (comparison > 0) {
         backupTaskDir(backupRoot, localMatch.section, localMatch.taskDir, localMatch.taskId);
         report.backupCount += 1;
-        fs.rmSync(localMatch.taskDir, { recursive: true, force: true });
+        removeDirRecursive(localMatch.taskDir);
 
         const destinationDir = copyTaskToSection(sourceTask, localWorkspace);
         localIndex.set(sourceTask.taskId, {

package/lib/platform/adapters.ts

@@ -1,4 +1,4 @@
-import type { PlatformResult } from './types.ts';
+import type { PlatformError, PlatformResult } from './types.ts';
 
 type PlatformAdapterContext = {
   cwd: string;
@@ -6,9 +6,85 @@ type PlatformAdapterContext = {
   client?: unknown;
 };
 
+type PlatformMergeability = {
+  state: 'mergeable' | 'conflicting' | 'unknown';
+  detail: string | null;
+};
+
+type PlatformChangeRequestSnapshot = {
+  repository: string;
+  number: number;
+  nodeId: string;
+  url: string;
+  state: 'open' | 'closed';
+  title: string;
+  body: string;
+  draft: boolean;
+  head: { repository: string; ref: string; sha: string };
+  base: { repository: string; ref: string; sha: string };
+  mergedAt: string | null;
+  mergeCommitSha: string | null;
+  labels: string[];
+  assignees: string[];
+  milestone: string | null;
+  mergeability?: PlatformMergeability;
+};
+
+type PlatformCheckSnapshot = {
+  name: string;
+  bucket: 'pass' | 'fail' | 'pending' | 'cancel';
+  workflow?: string | null;
+  conclusion?: string | null;
+  detailsUrl?: string | null;
+  startedAt?: string | null;
+  completedAt?: string | null;
+};
+
+type PlatformInspectionResult<T> = {
+  ok: boolean;
+  value?: T;
+  error?: PlatformError;
+};
+
+type ChangeRequestInspectionContext = PlatformAdapterContext & {
+  repository: string;
+  number: number;
+};
+
+type IssueClosingChangeRequestsContext = PlatformAdapterContext & {
+  repository: string;
+  issueNumber: number;
+};
+
+type RequiredChecksInspectionContext = ChangeRequestInspectionContext & {
+  headSha: string;
+};
+
+type ChangeRequestGitEvidenceContext = ChangeRequestInspectionContext & {
+  pullRequest: PlatformChangeRequestSnapshot;
+};
+
+type PlatformChangeRequestGitEvidenceSpec = {
+  remoteUrl: string;
+  reviewedHeadRef: string;
+  targetHeadRef: string;
+};
+
 type PlatformAdapter = {
   type: string;
   resolveContext(context: PlatformAdapterContext): PlatformResult;
+  inspectChangeRequest?(
+    context: ChangeRequestInspectionContext
+  ): PlatformInspectionResult<PlatformChangeRequestSnapshot>;
+  inspectIssueClosingChangeRequests?(
+    context: IssueClosingChangeRequestsContext
+  ): PlatformInspectionResult<PlatformChangeRequestSnapshot[]>;
+  inspectRequiredChecks?(
+    context: RequiredChecksInspectionContext
+  ): PlatformInspectionResult<PlatformCheckSnapshot[]>;
+  resolveChangeRequestGitEvidence?(
+    context: ChangeRequestGitEvidenceContext
+  ): PlatformInspectionResult<PlatformChangeRequestGitEvidenceSpec>;
 };
 
 const adapters = new Map<string, PlatformAdapter>();
@@ -22,9 +98,99 @@ function getPlatformAdapter(type: string | null): PlatformAdapter | null {
   return type ? adapters.get(type) ?? null : null;
 }
 
+function registerPlatformCapabilities(
+  type: string,
+  capabilities: Pick<
+    PlatformAdapter,
+    'inspectChangeRequest' | 'inspectIssueClosingChangeRequests' | 'inspectRequiredChecks' | 'resolveChangeRequestGitEvidence'
+  >
+): void {
+  const adapter = adapters.get(type);
+  if (!adapter) throw new Error(`Platform adapter '${type}' must be registered before its capabilities`);
+  adapters.set(type, { ...adapter, ...capabilities });
+}
+
+function hasPlatformCapability(
+  type: string | null,
+  capability: 'change-request' | 'issue-closing-change-requests' | 'required-checks' | 'change-request-git-evidence'
+): boolean {
+  const adapter = getPlatformAdapter(type);
+  if (capability === 'change-request') return typeof adapter?.inspectChangeRequest === 'function';
+  if (capability === 'issue-closing-change-requests') return typeof adapter?.inspectIssueClosingChangeRequests === 'function';
+  if (capability === 'required-checks') return typeof adapter?.inspectRequiredChecks === 'function';
+  return typeof adapter?.resolveChangeRequestGitEvidence === 'function';
+}
+
+function inspectPlatformIssueClosingChangeRequests(
+  type: string | null,
+  context: IssueClosingChangeRequestsContext
+): PlatformInspectionResult<PlatformChangeRequestSnapshot[]> {
+  const adapter = getPlatformAdapter(type);
+  return adapter?.inspectIssueClosingChangeRequests?.(context) ??
+    unsupported(type, 'issue closing change-request inspection');
+}
+
+function unsupported<T>(type: string | null, capability: string): PlatformInspectionResult<T> {
+  return {
+    ok: false,
+    error: {
+      code: 'PLATFORM_CAPABILITY_UNSUPPORTED',
+      message: `Platform '${type || 'none'}' does not provide ${capability}`,
+      retryable: false
+    }
+  };
+}
+
+function inspectPlatformChangeRequest(
+  type: string | null,
+  context: ChangeRequestInspectionContext
+): PlatformInspectionResult<PlatformChangeRequestSnapshot> {
+  const adapter = getPlatformAdapter(type);
+  return adapter?.inspectChangeRequest?.(context) ?? unsupported(type, 'change-request inspection');
+}
+
+function inspectPlatformRequiredChecks(
+  type: string | null,
+  context: RequiredChecksInspectionContext
+): PlatformInspectionResult<PlatformCheckSnapshot[]> {
+  const adapter = getPlatformAdapter(type);
+  return adapter?.inspectRequiredChecks?.(context) ?? unsupported(type, 'required-checks inspection');
+}
+
+function resolvePlatformChangeRequestGitEvidence(
+  type: string | null,
+  context: ChangeRequestGitEvidenceContext
+): PlatformInspectionResult<PlatformChangeRequestGitEvidenceSpec> {
+  const adapter = getPlatformAdapter(type);
+  return adapter?.resolveChangeRequestGitEvidence?.(context) ??
+    unsupported(type, 'change-request Git evidence');
+}
+
 function listPlatformAdapters(): string[] {
   return [...adapters.keys()].sort();
 }
 
-export { getPlatformAdapter, listPlatformAdapters, registerPlatformAdapter };
-export type { PlatformAdapter, PlatformAdapterContext };
+export {
+  getPlatformAdapter,
+  hasPlatformCapability,
+  inspectPlatformChangeRequest,
+  inspectPlatformIssueClosingChangeRequests,
+  inspectPlatformRequiredChecks,
+  listPlatformAdapters,
+  registerPlatformAdapter,
+  registerPlatformCapabilities,
+  resolvePlatformChangeRequestGitEvidence
+};
+export type {
+  ChangeRequestGitEvidenceContext,
+  ChangeRequestInspectionContext,
+  IssueClosingChangeRequestsContext,
+  PlatformAdapter,
+  PlatformAdapterContext,
+  PlatformChangeRequestGitEvidenceSpec,
+  PlatformChangeRequestSnapshot,
+  PlatformCheckSnapshot,
+  PlatformInspectionResult,
+  PlatformMergeability,
+  RequiredChecksInspectionContext
+};

package/lib/platform/change-request-git-evidence.ts

@@ -0,0 +1,159 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+
+import { resolvePlatformChangeRequestGitEvidence } from "./adapters.ts";
+import { resolveReviewedHeadRelation } from "./merged-pr-equivalence.ts";
+import type { ReviewedHeadRelation } from "./merged-pr-equivalence.ts";
+import type { PullRequestSnapshot } from "./pull-requests.ts";
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/i;
+const REVIEWED_HEAD_REF = "refs/agent-infra/reviewed-head";
+const TARGET_HEAD_REF = "refs/agent-infra/target-head";
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+
+function validRef(ref: string): boolean {
+  return spawnSync("git", ["check-ref-format", ref], {
+    encoding: "utf8",
+    stdio: ["ignore", "ignore", "ignore"]
+  }).status === 0;
+}
+
+function blocked(code: string, message: string): ReviewedHeadRelation {
+  return { status: "blocked", code, message };
+}
+
+function failed(code: string, message: string): ReviewedHeadRelation {
+  return { status: "failed", code, message };
+}
+
+function validMergeIdentity(lastReviewedCommit: string, pullRequest: PullRequestSnapshot):
+  ReviewedHeadRelation | null {
+  if (
+    pullRequest.state !== "closed" ||
+    !pullRequest.mergedAt ||
+    !pullRequest.mergeCommitSha ||
+    !SHA_PATTERN.test(lastReviewedCommit) ||
+    lastReviewedCommit !== pullRequest.head.sha
+  ) {
+    return failed(
+      "PR_MERGE_IDENTITY_INVALID",
+      "PR merge identity does not match the reviewed head"
+    );
+  }
+  return null;
+}
+
+function resolveMaterializedReviewedHeadRelation(input: {
+  cwd: string;
+  platformType: string | null;
+  lastReviewedCommit: string;
+  pullRequest: PullRequestSnapshot;
+}): ReviewedHeadRelation {
+  const identityFailure = validMergeIdentity(input.lastReviewedCommit, input.pullRequest);
+  if (identityFailure) return identityFailure;
+
+  const source = resolvePlatformChangeRequestGitEvidence(input.platformType, {
+    cwd: input.cwd,
+    repository: input.pullRequest.repository,
+    number: input.pullRequest.number,
+    pullRequest: input.pullRequest
+  });
+  if (!source.ok || !source.value) {
+    return blocked(
+      source.error?.code || "PR_MERGE_EVIDENCE_SOURCE_UNAVAILABLE",
+      source.error?.message || "Unable to resolve authoritative PR Git evidence"
+    );
+  }
+  if (
+    !source.value.remoteUrl.trim() ||
+    source.value.remoteUrl.trimStart().startsWith("-") ||
+    !validRef(source.value.reviewedHeadRef) ||
+    !validRef(source.value.targetHeadRef)
+  ) {
+    return blocked(
+      "PR_MERGE_EVIDENCE_SOURCE_UNAVAILABLE",
+      "Platform returned an invalid PR Git evidence source"
+    );
+  }
+
+  let evidenceRoot: string | null = null;
+  let phase: "prepare" | "fetch" | "resolve" = "prepare";
+  let result: ReviewedHeadRelation = blocked(
+    "PR_MERGE_GIT_EVIDENCE_UNAVAILABLE",
+    "Unable to prepare isolated PR Git evidence"
+  );
+  try {
+    evidenceRoot = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-pr-evidence-"));
+    execFileSync("git", ["init", "--bare", "-q", evidenceRoot], {
+      cwd: input.cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+
+    phase = "fetch";
+    git(evidenceRoot, [
+      "fetch",
+      "--no-tags",
+      "--no-write-fetch-head",
+      source.value.remoteUrl,
+      `+${source.value.reviewedHeadRef}:${REVIEWED_HEAD_REF}`,
+      `+${source.value.targetHeadRef}:${TARGET_HEAD_REF}`
+    ]);
+
+    phase = "resolve";
+    const fetchedReviewedHead = git(evidenceRoot, ["rev-parse", `${REVIEWED_HEAD_REF}^{commit}`]);
+    const comparisonHead = git(evidenceRoot, ["rev-parse", `${TARGET_HEAD_REF}^{commit}`]);
+    if (fetchedReviewedHead !== input.pullRequest.head.sha) {
+      result = failed(
+        "PR_MERGE_FETCHED_HEAD_MISMATCH",
+        "Fetched PR head does not match the authoritative platform snapshot"
+      );
+    } else {
+      result = resolveReviewedHeadRelation({
+        gitRoot: evidenceRoot,
+        comparisonHead,
+        lastReviewedCommit: input.lastReviewedCommit,
+        pullRequest: input.pullRequest
+      });
+    }
+  } catch {
+    result = phase === "fetch"
+      ? blocked(
+          "PR_MERGE_EVIDENCE_FETCH_FAILED",
+          "Unable to fetch PR Git evidence; verify Git credentials and platform refs"
+        )
+      : phase === "resolve"
+        ? blocked(
+            "PR_MERGE_OBJECT_MISSING",
+            "Fetched PR Git evidence is incomplete"
+          )
+        : blocked(
+            "PR_MERGE_GIT_EVIDENCE_UNAVAILABLE",
+            "Unable to prepare isolated PR Git evidence"
+          );
+  } finally {
+    if (evidenceRoot) {
+      try {
+        fs.rmSync(evidenceRoot, { recursive: true, force: true });
+      } catch {
+        result = blocked(
+          "PR_MERGE_EVIDENCE_CLEANUP_FAILED",
+          "Unable to clean up isolated PR Git evidence"
+        );
+      }
+    }
+  }
+  return result;
+}
+
+export { resolveMaterializedReviewedHeadRelation };