@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/lib/internal/task-review.ts

@@ -0,0 +1,65 @@
+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> [--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;
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!['--stage', '--artifact', '--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;
+    }
+    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, 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,71 @@ type PlatformAdapterContext = {
   client?: unknown;
 };
 
+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;
+};
+
+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 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>;
+  inspectRequiredChecks?(
+    context: RequiredChecksInspectionContext
+  ): PlatformInspectionResult<PlatformCheckSnapshot[]>;
+  resolveChangeRequestGitEvidence?(
+    context: ChangeRequestGitEvidenceContext
+  ): PlatformInspectionResult<PlatformChangeRequestGitEvidenceSpec>;
 };
 
 const adapters = new Map<string, PlatformAdapter>();
@@ -22,9 +84,86 @@ function getPlatformAdapter(type: string | null): PlatformAdapter | null {
   return type ? adapters.get(type) ?? null : null;
 }
 
+function registerPlatformCapabilities(
+  type: string,
+  capabilities: Pick<
+    PlatformAdapter,
+    'inspectChangeRequest' | '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' | 'required-checks' | 'change-request-git-evidence'
+): boolean {
+  const adapter = getPlatformAdapter(type);
+  if (capability === 'change-request') return typeof adapter?.inspectChangeRequest === 'function';
+  if (capability === 'required-checks') return typeof adapter?.inspectRequiredChecks === 'function';
+  return typeof adapter?.resolveChangeRequestGitEvidence === 'function';
+}
+
+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,
+  inspectPlatformRequiredChecks,
+  listPlatformAdapters,
+  registerPlatformAdapter,
+  registerPlatformCapabilities,
+  resolvePlatformChangeRequestGitEvidence
+};
+export type {
+  ChangeRequestGitEvidenceContext,
+  ChangeRequestInspectionContext,
+  PlatformAdapter,
+  PlatformAdapterContext,
+  PlatformChangeRequestGitEvidenceSpec,
+  PlatformChangeRequestSnapshot,
+  PlatformCheckSnapshot,
+  PlatformInspectionResult,
+  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 };

package/lib/platform/merged-pr-equivalence.ts

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 
 import type { PullRequestSnapshot } from "./pull-requests.ts";
 
@@ -6,11 +6,21 @@ const SHA_PATTERN = /^[0-9a-f]{40}$/i;
 
 type ReviewedHeadRelation =
   | { status: "strict"; reviewedHead: string }
-  | { status: "merged-equivalent"; reviewedHead: string; mergeCommit: string }
+  | {
+      status: "merged-equivalent";
+      reviewedHead: string;
+      mergeCommit: string;
+      comparisonHead: string;
+    }
   | { status: "failed" | "blocked"; code: string; message: string };
 
 function git(cwd: string, args: string[]): string {
-  return execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
 }
 
 function commitExists(gitRoot: string, sha: string): boolean {
@@ -22,27 +32,57 @@ function commitExists(gitRoot: string, sha: string): boolean {
   }
 }
 
+function isAncestor(gitRoot: string, ancestor: string, descendant: string):
+  | { status: "yes" | "no" }
+  | { status: "error" } {
+  const result = spawnSync("git", ["merge-base", "--is-ancestor", ancestor, descendant], {
+    cwd: gitRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (result.status === 0) return { status: "yes" };
+  if (result.status === 1) return { status: "no" };
+  return { status: "error" };
+}
+
 export function resolveReviewedHeadRelation(input: {
   gitRoot: string;
-  localHead: string;
+  comparisonHead: string;
   lastReviewedCommit: string;
   pullRequest: PullRequestSnapshot;
-  pathspecs: string[];
 }): ReviewedHeadRelation {
-  const { gitRoot, localHead, lastReviewedCommit, pullRequest, pathspecs } = input;
-  if (localHead === lastReviewedCommit && lastReviewedCommit === pullRequest.head.sha) {
+  const { gitRoot, comparisonHead, lastReviewedCommit, pullRequest } = input;
+  if (
+    comparisonHead === lastReviewedCommit &&
+    lastReviewedCommit === pullRequest.head.sha &&
+    !(pullRequest.state === "closed" && pullRequest.mergedAt && pullRequest.mergeCommitSha)
+  ) {
     return { status: "strict", reviewedHead: lastReviewedCommit };
   }
   if (pullRequest.state !== "closed" || !pullRequest.mergedAt || !pullRequest.mergeCommitSha ||
       lastReviewedCommit !== pullRequest.head.sha) {
     return { status: "failed", code: "PR_MERGE_IDENTITY_INVALID", message: "PR merge identity does not match the reviewed head" };
   }
-  const shas = [pullRequest.base.sha, pullRequest.head.sha, pullRequest.mergeCommitSha, localHead];
+  const shas = [pullRequest.base.sha, pullRequest.head.sha, pullRequest.mergeCommitSha, comparisonHead];
   if (shas.some((sha) => !SHA_PATTERN.test(sha) || !commitExists(gitRoot, sha))) {
     return { status: "blocked", code: "PR_MERGE_OBJECT_MISSING", message: "Required PR merge Git objects are unavailable" };
   }
+  const ancestry = isAncestor(gitRoot, pullRequest.mergeCommitSha, comparisonHead);
+  if (ancestry.status === "no") {
+    return {
+      status: "failed",
+      code: "PR_MERGE_TARGET_MISMATCH",
+      message: "PR merge commit is not in the authoritative target history"
+    };
+  }
+  if (ancestry.status === "error") {
+    return {
+      status: "blocked",
+      code: "PR_MERGE_GIT_EVIDENCE_UNAVAILABLE",
+      message: "Unable to verify PR merge ancestry"
+    };
+  }
   try {
-    git(gitRoot, ["merge-base", "--is-ancestor", pullRequest.mergeCommitSha, localHead]);
     const parents = git(gitRoot, ["rev-list", "--parents", "-n", "1", pullRequest.mergeCommitSha]).trim().split(/\s+/);
     if (parents.length !== 2) {
       return { status: "failed", code: "PR_MERGE_TOPOLOGY_INVALID", message: "PR merge commit is not a single-parent squash commit" };
@@ -53,17 +93,14 @@ export function resolveReviewedHeadRelation(input: {
     if (reviewedDiff !== mergedDiff) {
       return { status: "failed", code: "PR_MERGE_CONTENT_MISMATCH", message: "Squash merge content differs from the reviewed PR changes" };
     }
-    const postMerge = git(gitRoot, ["rev-list", `${pullRequest.mergeCommitSha}..${localHead}`, "--", ...pathspecs]).trim();
-    if (postMerge) {
-      return { status: "failed", code: "POST_MERGE_CHANGES", message: "Protected paths changed after the squash merge" };
-    }
   } catch {
     return { status: "blocked", code: "PR_MERGE_GIT_EVIDENCE_UNAVAILABLE", message: "Unable to verify PR merge topology or content" };
   }
   return {
     status: "merged-equivalent",
     reviewedHead: lastReviewedCommit,
-    mergeCommit: pullRequest.mergeCommitSha
+    mergeCommit: pullRequest.mergeCommitSha,
+    comparisonHead
   };
 }
 

package/lib/platform/pr-checks.ts

@@ -2,6 +2,11 @@ import fs from 'node:fs';
 
 import { parseTaskFrontmatter } from '../task/frontmatter.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
+import {
+  inspectPlatformRequiredChecks,
+  registerPlatformCapabilities
+} from './adapters.ts';
+import type { PlatformCheckSnapshot } from './adapters.ts';
 import { resolvePlatformContext } from './context.ts';
 import { createGitHubClient } from './github-client.ts';
 import type { GitHubClient } from './github-client.ts';
@@ -12,15 +17,7 @@ import type { PullRequestSnapshot } from './pull-requests.ts';
 
 type CheckBucket = 'pass' | 'fail' | 'pending' | 'cancel';
 type CheckState = 'passed' | 'failed' | 'pending' | 'timed-out' | 'cancelled' | 'no-required';
-type CheckSnapshot = {
-  name: string;
-  bucket: CheckBucket;
-  workflow?: string | null;
-  conclusion?: string | null;
-  detailsUrl?: string | null;
-  startedAt?: string | null;
-  completedAt?: string | null;
-};
+type CheckSnapshot = PlatformCheckSnapshot;
 type ChecksSnapshot = { state: Exclude<CheckState, 'timed-out'>; required: CheckSnapshot[] };
 type RunCandidate = { id: number; name: string; headSha: string; jobId?: number | null };
 type ChecksResult = PlatformResult & {
@@ -29,6 +26,7 @@ type ChecksResult = PlatformResult & {
   resolution?: { status: 'resolved' | 'missing' | 'ambiguous'; runId: number | null; jobId: number | null };
   logs?: { runId: number; jobId?: number; text: string };
 };
+type InspectionOptions = { cwd?: string; client?: unknown };
 type SharedOptions = { cwd?: string; client?: GitHubClient };
 
 function classifyRequiredChecks(required: CheckSnapshot[]): ChecksSnapshot {
@@ -114,14 +112,27 @@ function normalizeChecks(value: unknown): CheckSnapshot[] {
   });
 }
 
-function resolvedTask(taskRef: string, options: SharedOptions) {
+registerPlatformCapabilities('github', {
+  inspectRequiredChecks({ client, repository, number, cwd }) {
+    const github = (client as GitHubClient | undefined) || createGitHubClient();
+    const inspected = github.json<unknown>([
+      'pr', 'checks', String(number), '--repo', repository, '--required',
+      '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'
+    ], { cwd });
+    return inspected.ok
+      ? { ok: true, value: normalizeChecks(inspected.value) }
+      : { ok: false, error: inspected.error };
+  }
+});
+
+function resolvedTask(taskRef: string, options: InspectionOptions) {
   const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
   if (!resolved.ok) return { ok: false as const, output: checksResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }) };
   const frontmatter = parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8'));
   const pr = Number(frontmatter.pr_number);
   const prNumber = Number.isInteger(pr) && pr > 0 ? pr : null;
   if (!prNumber) return { ok: false as const, output: checksResult('failed', { error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false } }) };
-  const client = options.client || createGitHubClient();
+  const client = (options.client as GitHubClient | undefined) || createGitHubClient();
   const context = resolvePlatformContext({ cwd: resolved.repoRoot, client });
   if (!context.platform.repository || !['no-op', 'degraded'].includes(context.status)) return { ok: false as const, output: checksResult(context.status, { platform: context.platform, capabilities: context.capabilities, error: context.error }) };
   const inspected = inspectPlatformPullRequest(taskRef, { cwd: resolved.repoRoot, client });
@@ -129,22 +140,30 @@ function resolvedTask(taskRef: string, options: SharedOptions) {
   return { ok: true as const, resolved, prNumber, client, context, pullRequest: inspected.pullRequest };
 }
 
-function inspectRequiredChecks(taskRef: string, options: SharedOptions = {}): ChecksResult {
+function inspectRequiredChecks(taskRef: string, options: InspectionOptions = {}): ChecksResult {
   const base = resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
   const repository = base.context.platform.repository!;
-  const inspected = base.client.json<unknown>([
-    'pr', 'checks', String(base.prNumber), '--repo', repository, '--required',
-    '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'
-  ], { cwd: base.resolved.repoRoot });
-  if (!inspected.ok) {
-    return checksResult(inspected.error.retryable ? 'blocked' : 'failed', {
+  const inspected = inspectPlatformRequiredChecks(base.context.platform.type, {
+    cwd: base.resolved.repoRoot,
+    repository,
+    number: base.prNumber,
+    headSha: base.pullRequest.head.sha,
+    client: options.client || base.client
+  });
+  if (!inspected.ok || !inspected.value) {
+    const error = inspected.error || {
+      code: 'REQUIRED_CHECKS_INSPECTION_INVALID',
+      message: 'Platform adapter returned no required-checks snapshot',
+      retryable: false
+    };
+    return checksResult(error.retryable ? 'blocked' : 'failed', {
       platform: base.context.platform, capabilities: base.context.capabilities,
       resource: { kind: 'pull-request', number: base.prNumber },
-      pullRequest: base.pullRequest, error: inspected.error
+      pullRequest: base.pullRequest, error
     });
   }
-  const classified = classifyRequiredChecks(normalizeChecks(inspected.value));
+  const classified = classifyRequiredChecks(inspected.value);
   const status = classified.state === 'passed' || classified.state === 'no-required'
     ? 'no-op'
     : classified.state === 'failed' || classified.state === 'cancelled' ? 'failed' : 'blocked';
@@ -160,7 +179,7 @@ function inspectRequiredChecks(taskRef: string, options: SharedOptions = {}): Ch
   });
 }
 
-async function watchPlatformChecks(taskRef: string, options: SharedOptions & {
+async function watchPlatformChecks(taskRef: string, options: InspectionOptions & {
   intervalSeconds: number;
   deadlineSeconds: number;
   signal?: AbortSignal;
@@ -218,13 +237,21 @@ function resolvePlatformCheckRun(taskRef: string, options: SharedOptions & { che
   });
 }
 
+function fetchCheckLogText(client: GitHubClient, args: string[], cwd: string) {
+  const fetched = client.text(args, { cwd });
+  if (fetched.ok || args[0] !== 'api' || !/response contains terminal escape sequences/i.test(fetched.error.message)) {
+    return fetched;
+  }
+  return client.text([...args, '--allow-escape-sequences'], { cwd });
+}
+
 function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions & { run: number; job?: number }): ChecksResult {
   const base = resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
   const args = options.job
     ? ['api', `repos/${base.context.platform.repository}/actions/jobs/${options.job}/logs`]
     : ['run', 'view', String(options.run), '--repo', base.context.platform.repository!, '--log-failed'];
-  const fetched = base.client.text(args, { cwd: base.resolved.repoRoot });
+  const fetched = fetchCheckLogText(base.client, args, base.resolved.repoRoot);
   if (!fetched.ok) return checksResult(fetched.error.retryable ? 'blocked' : 'failed', { platform: base.context.platform, capabilities: base.context.capabilities, error: fetched.error });
   if (!fetched.value) return checksResult('failed', { error: { code: 'CHECK_LOGS_MISSING', message: 'No failed logs are available', retryable: false } });
   return checksResult('no-op', {
@@ -236,6 +263,7 @@ function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions & { run:
 
 export {
   classifyRequiredChecks,
+  fetchCheckLogText,
   fetchPlatformCheckLogs,
   inspectRequiredChecks,
   parseRunJobIdentity,