@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/platform/comment-safety.ts

@@ -0,0 +1,255 @@
+type SanitizationError = { code: 'COMMENT_DOCUMENT_INVALID'; message: string; offset: number };
+type SanitizationResult<T> = { ok: true; value: T } | { ok: false; error: SanitizationError };
+type SanitizationOptions = { reservedMarkers?: readonly RegExp[] };
+type PlaceholderSplit = { prefix: string; suffix: string };
+type FenceRange = {
+  start: number;
+  end: number;
+  openingEnd: number;
+  closingStart: number;
+  character: '`' | '~';
+  opening: string;
+  closing: string;
+};
+type Line = { start: number; end: number; text: string };
+
+const CONTROL_MARKER_PATTERN = /<!--\s*(?:sync-issue|sync-pr|last-commit)\b[\s\S]*?-->|<!--\s*canonical-pr-change-report\s*-->/gi;
+
+function ok<T>(value: T): SanitizationResult<T> {
+  return { ok: true, value };
+}
+
+function invalid(message: string, offset: number): SanitizationResult<never> {
+  return { ok: false, error: { code: 'COMMENT_DOCUMENT_INVALID', message, offset } };
+}
+
+function normalized(value: string): string {
+  return value.replace(/\r\n?/g, '\n');
+}
+
+function linesOf(value: string): Line[] {
+  const lines: Line[] = [];
+  let start = 0;
+  while (start < value.length) {
+    const newline = value.indexOf('\n', start);
+    const end = newline === -1 ? value.length : newline;
+    lines.push({ start, end: newline === -1 ? end : newline + 1, text: value.slice(start, end) });
+    start = newline === -1 ? value.length : newline + 1;
+  }
+  if (value.length === 0) lines.push({ start: 0, end: 0, text: '' });
+  return lines;
+}
+
+function openingFence(line: string): { character: '`' | '~'; length: number } | null | 'invalid' {
+  const match = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+  if (!match) return null;
+  const character = match[1]![0] as '`' | '~';
+  const info = match[2]!;
+  if (character === '`' && info.includes('`')) return 'invalid';
+  return { character, length: match[1]!.length };
+}
+
+function closesFence(line: string, fence: { character: '`' | '~'; length: number }): boolean {
+  const escaped = fence.character === '`' ? '`' : '~';
+  return new RegExp(`^ {0,3}${escaped}{${fence.length},}[ \\t]*$`).test(line);
+}
+
+function fenceRanges(value: string): SanitizationResult<FenceRange[]> {
+  const ranges: FenceRange[] = [];
+  let fence: { character: '`' | '~'; length: number; start: number; openingEnd: number } | null = null;
+  for (const line of linesOf(value)) {
+    if (!fence) {
+      const opening = openingFence(line.text);
+      if (opening === 'invalid') return invalid('fenced code info string is invalid', line.start);
+      if (opening) fence = { ...opening, start: line.start, openingEnd: line.end };
+      continue;
+    }
+    if (closesFence(line.text, fence)) {
+      ranges.push({
+        start: fence.start,
+        end: line.end,
+        openingEnd: fence.openingEnd,
+        closingStart: line.start,
+        character: fence.character,
+        opening: value.slice(fence.start, fence.openingEnd),
+        closing: value.slice(line.start, line.end)
+      });
+      fence = null;
+    }
+  }
+  if (fence) return invalid('fenced code block is not closed', fence.start);
+  return ok(ranges);
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function escapeHtmlText(value: string): string {
+  return escapeHtml(value);
+}
+
+function escapeHtmlAttribute(value: string): string {
+  return escapeHtml(value);
+}
+
+function escapeMarkdownLiteral(value: string): string {
+  return value.replace(/[\\`*_{}\[\]()#+.!|<>-]/g, '\\$&');
+}
+
+function markerSafe(value: string, markers: readonly RegExp[]): string {
+  let result = value;
+  for (const marker of markers) {
+    const flags = marker.flags.includes('g') ? marker.flags : `${marker.flags}g`;
+    const pattern = new RegExp(marker.source, flags);
+    result = result.replace(pattern, (match) => escapeHtmlText(match));
+  }
+  return result;
+}
+
+function tagEnd(value: string, start: number): number {
+  let quote: '"' | "'" | null = null;
+  for (let index = start + 1; index < value.length; index += 1) {
+    const character = value[index]!;
+    if (quote) {
+      if (character === quote) quote = null;
+    } else if (character === '"' || character === "'") {
+      quote = character;
+    } else if (character === '>') {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function isMarkdownAutolink(value: string, start: number): boolean {
+  const end = value.indexOf('>', start + 1);
+  if (end === -1) return false;
+  const target = value.slice(start + 1, end);
+  return /^(?:https?:\/\/|mailto:)[^<>\s]+$/i.test(target)
+    || /^[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+$/.test(target);
+}
+
+function sanitizeOutside(value: string, baseOffset: number): SanitizationResult<string> {
+  let result = '';
+  let index = 0;
+  while (index < value.length) {
+    if (value.startsWith('<!--', index)) {
+      const end = value.indexOf('-->', index + 4);
+      if (end === -1) return invalid('HTML comment is not closed', baseOffset + index);
+      const token = value.slice(index, end + 3);
+      result += escapeHtmlText(token);
+      index = end + 3;
+      continue;
+    }
+    if (value[index] === '<' && isMarkdownAutolink(value, index)) {
+      const end = value.indexOf('>', index + 1);
+      result += value.slice(index, end + 1);
+      index = end + 1;
+      continue;
+    }
+    if (value[index] === '<' && /[\\/!?A-Za-z]/.test(value[index + 1] || '')) {
+      const end = tagEnd(value, index);
+      if (end === -1) return invalid('HTML-like tag is not closed', baseOffset + index);
+      result += escapeHtmlText(value.slice(index, end + 1));
+      index = end + 1;
+      continue;
+    }
+    result += value[index]!;
+    index += 1;
+  }
+  return ok(result);
+}
+
+function sanitizeMarkdownDocument(value: string, options: SanitizationOptions = {}): SanitizationResult<string> {
+  const source = normalized(value);
+  const ranges = fenceRanges(source);
+  if (!ranges.ok) return ranges;
+  const markers = options.reservedMarkers || [];
+  let result = '';
+  let cursor = 0;
+  for (const range of ranges.value) {
+    const outside = sanitizeOutside(source.slice(cursor, range.start), cursor);
+    if (!outside.ok) return outside;
+    result += outside.value;
+    result += markerSafe(source.slice(range.start, range.end), markers);
+    cursor = range.end;
+  }
+  const tail = sanitizeOutside(source.slice(cursor), cursor);
+  if (!tail.ok) return tail;
+  return ok(result + tail.value);
+}
+
+function canonicalizeCommentBody(value: string): SanitizationResult<string> {
+  return sanitizeMarkdownDocument(value, { reservedMarkers: [CONTROL_MARKER_PATTERN] });
+}
+
+function renderSafeCodeFence(value: string, language = '', reservedMarkers: readonly RegExp[] = [CONTROL_MARKER_PATTERN]): string {
+  const content = markerSafe(normalized(value), reservedMarkers);
+  const longestRun = Math.max(0, ...(content.match(/`+/g) || []).map((run) => run.length));
+  const delimiter = '`'.repeat(Math.max(3, longestRun + 1));
+  const suffix = content.endsWith('\n') ? '' : '\n';
+  return `${delimiter}${language}\n${content}${suffix}${delimiter}`;
+}
+
+function commentRangesOutsideFences(source: string, ranges: readonly FenceRange[]): SanitizationResult<Array<{ start: number; end: number }>> {
+  const comments: Array<{ start: number; end: number }> = [];
+  let cursor = 0;
+  for (const fence of [...ranges, { start: source.length, end: source.length }]) {
+    const segment = source.slice(cursor, fence.start);
+    let index = 0;
+    while (index < segment.length) {
+      const opening = segment.indexOf('<!--', index);
+      if (opening === -1) break;
+      const absoluteStart = cursor + opening;
+      const closing = segment.indexOf('-->', opening + 4);
+      if (closing === -1) return invalid('HTML comment is not closed', absoluteStart);
+      comments.push({ start: absoluteStart, end: cursor + closing + 3 });
+      index = closing + 3;
+    }
+    cursor = fence.end;
+  }
+  return ok(comments);
+}
+
+function splitDocumentPlaceholder(value: string, placeholder: string): SanitizationResult<PlaceholderSplit> {
+  const source = normalized(value);
+  const ranges = fenceRanges(source);
+  if (!ranges.ok) return ranges;
+  const positions: number[] = [];
+  let cursor = source.indexOf(placeholder);
+  while (cursor !== -1) {
+    positions.push(cursor);
+    cursor = source.indexOf(placeholder, cursor + placeholder.length);
+  }
+  if (positions.length !== 1) return invalid('document must contain exactly one placeholder', positions[1] ?? positions[0] ?? source.length);
+  const position = positions[0]!;
+  if (ranges.value.some((range) => position >= range.start && position < range.end)) {
+    return invalid('placeholder must be outside fenced code', position);
+  }
+  const comments = commentRangesOutsideFences(source, ranges.value);
+  if (!comments.ok) return comments;
+  const containing = comments.value.find((comment) => position >= comment.start && position < comment.end);
+  if (containing && (containing.start !== position || containing.end !== position + placeholder.length)) {
+    return invalid('placeholder must not be nested in another HTML comment', position);
+  }
+  return ok({ prefix: source.slice(0, position), suffix: source.slice(position + placeholder.length) });
+}
+
+export {
+  CONTROL_MARKER_PATTERN,
+  escapeHtmlAttribute,
+  escapeHtmlText,
+  escapeMarkdownLiteral,
+  fenceRanges,
+  renderSafeCodeFence,
+  canonicalizeCommentBody,
+  sanitizeMarkdownDocument,
+  splitDocumentPlaceholder
+};
+export type { FenceRange, SanitizationError, SanitizationOptions, SanitizationResult };

package/lib/platform/completion-backfill.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { COMPLETION_BACKFILL_FAMILIES, inspectCompletionArtifacts } from '../task/finalization-artifacts.ts';
-import { parseArtifactName } from '../task/artifact-lifecycle.ts';
+import { parseArtifactName } from '../task/artifact-name.ts';
 import { parseTaskFrontmatter } from '../task/frontmatter.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { getOpenWorkflowWarnings } from '../task/workflow-warnings.ts';

package/lib/platform/github-data.ts

@@ -0,0 +1,322 @@
+import type { PlatformClient as GitHubClient } from './context.ts';
+import type { PlatformIssueSnapshot as IssueSnapshot, PlatformChangeRequestSnapshot as PullRequestSnapshot } from './snapshots.ts';
+import type { RequiredCheckSnapshot } from './provider-contract.ts';
+import { checkStatusBucket } from './check-status.ts';
+
+type RemoteIssue = {
+  number?: number;
+  id?: number;
+  node_id?: string;
+  html_url?: string;
+  state?: string;
+  title?: string;
+  body?: string | null;
+  labels?: Array<string | { name?: string }>;
+  assignees?: Array<{ login?: string }>;
+  milestone?: { title?: string } | null;
+  type?: { name?: string } | null;
+  pull_request?: unknown;
+};
+
+type IssueFieldSchema = {
+  id: string;
+  name: string;
+  kind: 'single-select' | 'date' | 'text' | 'number';
+  options: Array<{ id: string; name: string }>;
+};
+
+type IssueTypeSchema = { id: string; name: string; fields: IssueFieldSchema[] };
+
+type CurrentField = { id: string; name: string; kind: IssueFieldSchema['kind']; value: string | number | null };
+
+const ISSUE_FIELDS_QUERY = `query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){id issueType{id name pinnedFields{__typename ... on IssueFieldSingleSelect{id name options{id name}} ... on IssueFieldDate{id name} ... on IssueFieldText{id name} ... on IssueFieldNumber{id name}}} issueFieldValues(first:50){nodes{__typename ... on IssueFieldSingleSelectValue{name optionId field{... on IssueFieldSingleSelect{id name}}} ... on IssueFieldDateValue{value field{... on IssueFieldDate{id name}}} ... on IssueFieldTextValue{value field{... on IssueFieldText{id name}}} ... on IssueFieldNumberValue{value field{... on IssueFieldNumber{id name}}}}}}}}`;
+
+function normalizeIssue(remote: RemoteIssue, repository: string, fallbackNumber?: number): IssueSnapshot | null {
+  const number = Number.isInteger(remote.number) && Number(remote.number) > 0
+    ? Number(remote.number)
+    : fallbackNumber;
+  if (!number || !Number.isSafeInteger(number) || remote.pull_request) return null;
+  return {
+    repository,
+    number,
+    databaseId: Number.isInteger(remote.id) ? Number(remote.id) : null,
+    nodeId: remote.node_id || `issue-${number}`,
+    url: remote.html_url || `https://github.com/${repository}/issues/${number}`,
+    state: String(remote.state || '').toLowerCase() === 'closed' ? 'closed' : 'open',
+    title: remote.title || '',
+    body: remote.body || '',
+    labels: (remote.labels || []).map((label) => typeof label === 'string' ? label : label.name || '').filter(Boolean).sort(),
+    assignees: (remote.assignees || []).map((assignee) => assignee.login || '').filter(Boolean).sort(),
+    milestone: remote.milestone?.title || null,
+    issueType: remote.type?.name || null,
+    fields: {}
+  };
+}
+
+function fieldKind(value: { __typename?: string }): IssueFieldSchema['kind'] | null {
+  if (value.__typename === 'IssueFieldSingleSelect' || value.__typename === 'IssueFieldSingleSelectValue') return 'single-select';
+  if (value.__typename === 'IssueFieldDate' || value.__typename === 'IssueFieldDateValue') return 'date';
+  if (value.__typename === 'IssueFieldText' || value.__typename === 'IssueFieldTextValue') return 'text';
+  if (value.__typename === 'IssueFieldNumber' || value.__typename === 'IssueFieldNumberValue') return 'number';
+  return null;
+}
+
+function normalizeFieldSchemas(value: unknown): IssueFieldSchema[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((raw) => {
+    const item = raw as { id?: string; name?: string; __typename?: string; options?: Array<{ id?: string; name?: string }> };
+    const kind = fieldKind(item);
+    return item.id && item.name && kind ? [{
+      id: item.id,
+      name: item.name,
+      kind,
+      options: (item.options || []).flatMap((option) => option.id && option.name ? [{ id: option.id, name: option.name }] : [])
+    }] : [];
+  });
+}
+
+function normalizeCurrentFields(value: unknown): { issueId: string | null; type: IssueTypeSchema | null; values: CurrentField[] } {
+  const issue = (value as { data?: { repository?: { issue?: {
+    id?: string;
+    issueType?: { id?: string; name?: string; pinnedFields?: unknown[] } | null;
+    issueFieldValues?: { nodes?: unknown[] };
+  } } } })?.data?.repository?.issue;
+  const type = issue?.issueType?.name ? {
+    id: issue.issueType.id || issue.issueType.name,
+    name: issue.issueType.name,
+    fields: normalizeFieldSchemas(issue.issueType.pinnedFields)
+  } : null;
+  const values = (issue?.issueFieldValues?.nodes || []).flatMap((raw) => {
+    const item = raw as { __typename?: string; name?: string; value?: string | number; field?: { id?: string; name?: string } };
+    const kind = fieldKind(item);
+    const value = kind === 'single-select' ? item.name : item.value;
+    return item.field?.name && kind && value !== undefined
+      ? [{ id: item.field.id || item.field.name, name: item.field.name, kind, value: value ?? null }]
+      : [];
+  });
+  return { issueId: issue?.id || null, type, values };
+}
+
+function graphState(client: GitHubClient, repository: string, issue: number, cwd: string) {
+  const [owner, name] = repository.split('/');
+  if (!owner || !name) return null;
+  const current = client.json<unknown>([
+    'api', 'graphql', '-f', `query=${ISSUE_FIELDS_QUERY}`, '-F', `owner=${owner}`, '-F', `name=${name}`, '-F', `number=${issue}`
+  ], { cwd });
+  if (!current.ok) return null;
+  return normalizeCurrentFields(current.value);
+}
+
+function fetchIssue(client: GitHubClient, repository: string, issue: number, cwd: string) {
+  return client.json<RemoteIssue>(['api', `repos/${repository}/issues/${issue}`], { cwd });
+}
+
+function inspectGitHubIssue(client: GitHubClient, repository: string, issue: number, cwd: string) {
+  const fetched = fetchIssue(client, repository, issue, cwd);
+  if (!fetched.ok) return fetched;
+  const snapshot = normalizeIssue(fetched.value, repository, issue);
+  return snapshot
+    ? { ok: true as const, value: snapshot }
+    : { ok: false as const, error: { code: 'ISSUE_IDENTITY_INVALID', message: 'Remote resource is not a valid Issue', retryable: false } };
+}
+
+type RemotePullRequest = {
+  number?: number;
+  node_id?: string;
+  html_url?: string;
+  state?: string;
+  title?: string;
+  body?: string | null;
+  draft?: boolean;
+  pull_request?: unknown;
+  head?: { ref?: string; sha?: string; repo?: { full_name?: string } | null };
+  base?: { ref?: string; sha?: string; repo?: { full_name?: string } | null };
+  merged_at?: string | null;
+  merge_commit_sha?: string | null;
+  labels?: Array<string | { name?: string }>;
+  assignees?: Array<{ login?: string }>;
+  milestone?: { title?: string } | null;
+  mergeable?: boolean | null;
+  mergeable_state?: string | null;
+};
+
+type ClosingPullRequestNode = {
+  number?: number;
+  id?: string;
+  url?: string;
+  state?: string;
+  title?: string;
+  body?: string | null;
+  isDraft?: boolean;
+  headRefName?: string;
+  headRefOid?: string;
+  headRepository?: { nameWithOwner?: string } | null;
+  baseRefName?: string;
+  baseRefOid?: string;
+  baseRepository?: { nameWithOwner?: string } | null;
+  mergedAt?: string | null;
+  mergeCommit?: { oid?: string } | null;
+  labels?: { nodes?: Array<{ name?: string }> };
+  assignees?: { nodes?: Array<{ login?: string }> };
+  milestone?: { title?: string } | null;
+};
+
+type ClosingPullRequestPage = {
+  data?: { repository?: { issue?: { closedByPullRequestsReferences?: {
+    nodes?: ClosingPullRequestNode[];
+    pageInfo?: { hasNextPage?: boolean; endCursor?: string | null };
+  } } } };
+};
+
+const CLOSING_PULL_REQUESTS_QUERY = `query($owner:String!,$name:String!,$issue:Int!,$cursor:String){repository(owner:$owner,name:$name){issue(number:$issue){closedByPullRequestsReferences(first:100,after:$cursor){nodes{number id url state title body isDraft headRefName headRefOid headRepository{nameWithOwner} baseRefName baseRefOid baseRepository{nameWithOwner} mergedAt mergeCommit{oid} labels(first:100){nodes{name}} assignees(first:100){nodes{login}} milestone{title}} pageInfo{hasNextPage endCursor}}}}}`;
+
+function normalizePullRequest(remote: RemotePullRequest, repository: string): PullRequestSnapshot | null {
+  const number = Number(remote.number);
+  const headRepository = remote.head?.repo?.full_name;
+  const baseRepository = remote.base?.repo?.full_name;
+  if (!Number.isInteger(number) || number <= 0 || !remote.node_id || !remote.html_url ||
+      !remote.head?.ref || !remote.head.sha || !headRepository || !remote.base?.ref || !baseRepository) return null;
+  const mergeabilityDetail = remote.mergeable_state?.trim().toLowerCase() || null;
+  const mergeability = remote.mergeable === false
+    ? { state: 'conflicting' as const, detail: mergeabilityDetail }
+    : remote.mergeable === true && mergeabilityDetail !== 'dirty'
+      ? { state: 'mergeable' as const, detail: mergeabilityDetail }
+      : { state: 'unknown' as const, detail: mergeabilityDetail };
+  return {
+    repository,
+    number,
+    nodeId: remote.node_id,
+    url: remote.html_url,
+    state: remote.state === 'closed' ? 'closed' : 'open',
+    title: remote.title || '',
+    body: remote.body || '',
+    draft: Boolean(remote.draft),
+    head: { repository: headRepository, ref: remote.head.ref, sha: remote.head.sha },
+    base: { repository: baseRepository, ref: remote.base.ref, sha: remote.base.sha || '' },
+    mergedAt: remote.merged_at || null,
+    mergeCommitSha: remote.merge_commit_sha || null,
+    labels: (remote.labels || []).map((label) => typeof label === 'string' ? label : label.name || '').filter(Boolean).sort(),
+    assignees: (remote.assignees || []).map((assignee) => assignee.login || '').filter(Boolean).sort(),
+    milestone: remote.milestone?.title || null,
+    mergeability
+  };
+}
+
+function normalizeClosingPullRequest(node: ClosingPullRequestNode, repository: string): PullRequestSnapshot | null {
+  return normalizePullRequest({
+    number: node.number,
+    node_id: node.id,
+    html_url: node.url,
+    state: node.state === 'OPEN' ? 'open' : 'closed',
+    title: node.title,
+    body: node.body,
+    draft: node.isDraft,
+    head: { ref: node.headRefName, sha: node.headRefOid, repo: node.headRepository ? { full_name: node.headRepository.nameWithOwner } : null },
+    base: { ref: node.baseRefName, sha: node.baseRefOid, repo: node.baseRepository ? { full_name: node.baseRepository.nameWithOwner } : null },
+    merged_at: node.mergedAt,
+    merge_commit_sha: node.mergeCommit?.oid,
+    labels: node.labels?.nodes,
+    assignees: node.assignees?.nodes,
+    milestone: node.milestone
+  }, repository);
+}
+
+function inspectGitHubIssueClosingChangeRequests(
+  client: GitHubClient,
+  repository: string,
+  issueNumber: number,
+  cwd: string
+) {
+  const [owner, name] = repository.split('/');
+  if (!owner || !name || !Number.isInteger(issueNumber) || issueNumber <= 0) return {
+    ok: false as const,
+    error: { code: 'PR_IDENTITY_INVALID', message: 'Repository or Issue identity is invalid', retryable: false }
+  };
+  const candidates: PullRequestSnapshot[] = [];
+  let cursor: string | null = null;
+  for (;;) {
+    const args = [
+      'api', 'graphql', '-f', `query=${CLOSING_PULL_REQUESTS_QUERY}`,
+      '-F', `owner=${owner}`, '-F', `name=${name}`, '-F', `issue=${issueNumber}`
+    ];
+    if (cursor) args.push('-F', `cursor=${cursor}`);
+    const response = client.json<ClosingPullRequestPage>(args, { cwd });
+    if (!response.ok) return response;
+    const connection = response.value?.data?.repository?.issue?.closedByPullRequestsReferences;
+    if (!connection || !Array.isArray(connection.nodes) || !connection.pageInfo) return {
+      ok: false as const,
+      error: { code: 'PR_IDENTITY_INVALID', message: 'Closing pull request response is incomplete', retryable: false }
+    };
+    for (const node of connection.nodes) {
+      const normalized = normalizeClosingPullRequest(node, repository);
+      if (!normalized) return {
+        ok: false as const,
+        error: { code: 'PR_IDENTITY_INVALID', message: 'Closing pull request identity is incomplete', retryable: false }
+      };
+      candidates.push(normalized);
+    }
+    if (!connection.pageInfo.hasNextPage) return { ok: true as const, value: candidates };
+    if (!connection.pageInfo.endCursor || connection.pageInfo.endCursor === cursor) return {
+      ok: false as const,
+      error: { code: 'PR_IDENTITY_INVALID', message: 'Closing pull request pagination cursor is invalid', retryable: false }
+    };
+    cursor = connection.pageInfo.endCursor;
+  }
+}
+
+function inspectGitHubPullRequest(client: GitHubClient, repository: string, number: number, cwd: string) {
+  const fetched = client.json<RemotePullRequest>(['api', `repos/${repository}/pulls/${number}`], { cwd });
+  if (!fetched.ok) return fetched;
+  const pullRequest = normalizePullRequest(fetched.value, repository);
+  return pullRequest
+    ? { ok: true as const, value: pullRequest }
+    : { ok: false as const, error: { code: 'PR_IDENTITY_INVALID', message: 'Remote resource is not a valid pull request', retryable: false } };
+}
+
+function normalizeGitHubChecks(value: unknown): RequiredCheckSnapshot[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((raw) => {
+    const item = raw as Record<string, unknown>;
+    const name = String(item.name || item.context || '');
+    return name ? [{
+      name,
+      status: checkStatusBucket(String(item.bucket || item.status || item.conclusion || item.state || '')),
+      conclusion: item.conclusion ? String(item.conclusion) : item.state ? String(item.state) : null,
+      detailsUrl: item.link ? String(item.link) : item.detailsUrl ? String(item.detailsUrl) : null
+    }] : [];
+  });
+}
+
+function inspectGitHubRequiredChecks(client: GitHubClient, repository: string, number: number, cwd: string) {
+  const inspected = client.json<unknown>([
+    'pr', 'checks', String(number), '--repo', repository,
+    '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'
+  ], { cwd });
+  return inspected.ok
+    ? { ok: true as const, value: normalizeGitHubChecks(inspected.value) }
+    : { ok: false as const, error: inspected.error };
+}
+
+function parseRunJobIdentity(detailsUrl: string): { runId: number; jobId: number | null } | null {
+  try {
+    const url = new URL(detailsUrl);
+    if (url.hostname !== 'github.com') return null;
+    const match = url.pathname.match(/\/actions\/runs\/(\d+)(?:\/job\/(\d+))?/);
+    if (!match) return null;
+    return { runId: Number(match[1]), jobId: match[2] ? Number(match[2]) : null };
+  } catch {
+    return null;
+  }
+}
+
+function fetchCheckLogText(client: GitHubClient, args: string[], cwd: string) {
+  if (!client.text) return { ok: false as const, error: { code: 'PLATFORM_CLIENT_TEXT_UNAVAILABLE', message: 'Platform client does not support text responses', retryable: false } };
+  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 });
+}
+
+export { ISSUE_FIELDS_QUERY, graphState, inspectGitHubIssue, normalizePullRequest, inspectGitHubIssueClosingChangeRequests, inspectGitHubPullRequest, inspectGitHubRequiredChecks, parseRunJobIdentity, fetchCheckLogText };
+export type { IssueFieldSchema, RemotePullRequest };