@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/platform/pr-summary.ts

@@ -16,7 +16,9 @@ import { platformResult } from './types.ts';
 import type { PlatformResult } from './types.ts';
 import type { OperationWarning } from '../task/operation-outcome.ts';
 import { providerError, providerOperationContext, providerStatus, providerResourceToken, resourceIdentityNumber, unsupportedProviderOperation } from './provider-bridge.ts';
-import type { PlatformChangeRequestSnapshot } from './adapters.ts';
+import { resourceIdentityEquals } from './resource-identity.ts';
+import type { ResourceIdentity } from './resource-identity.ts';
+import type { PlatformChangeRequestSnapshot } from './snapshots.ts';
 import type { ChangeRequestSnapshot } from './provider-contract.ts';
 import {
   buildPrChangeReport,
@@ -33,6 +35,8 @@ import type {
   MechanicalChangeReport,
   PrChangeReport
 } from './pr-change-report.ts';
+import { manualValidationFinalSummaryProjectionMatches } from '../task/manual-validation-receipt.ts';
+import { readManualValidationCompletion } from '../task/manual-validation-completion.ts';
 
 type SummaryComment = { id: number | string; body: string };
 type ChangeReportState = 'ready' | 'missing' | 'stale' | 'invalid';
@@ -50,9 +54,21 @@ type PullRequestSummaryResult = PlatformResult & {
 };
 type PullRequestPrimaryResult = 'pr_created' | 'pr_reused' | 'no_op';
 type SummaryOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string };
+type ManualValidationSummaryOptions = {
+  phase: 'pending' | 'final';
+  transactionId?: string;
+  receiptDigest?: string;
+  prHeadSha?: string;
+  authority?: 'coordinator';
+};
 type ReportWriteResult = PlatformResult & {
   report: { path: string; status: 'written' | 'no-op' | 'planned'; precheckVerdict: 'clear' | 'needs-review'; nextAction: 'watch-pr' | 'review-code' } | null;
 };
+type SummaryCommentStateResult = Omit<PlatformResult, 'comment'> & {
+  task: { id: string | null; prNumber: number | null };
+  pullRequest: PlatformChangeRequestSnapshot | null;
+  comment: SummaryComment | null;
+};
 
 function summaryMarker(taskId: string): string {
   return `<!-- sync-pr:${taskId}:summary -->`;
@@ -88,12 +104,17 @@ function taskReportPath(taskDir: string): string {
   return path.join(taskDir, 'pr-change-report.json');
 }
 
-function readBoundTaskSnapshot(taskMdPath: string): { taskContent: string; boundFact: Extract<PrDeliveryFact, { state: 'bound' }> | null } {
+function readBoundTaskSnapshot(taskMdPath: string): {
+  taskContent: string;
+  boundFact: Extract<PrDeliveryFact, { state: 'bound' }> | null;
+  factError: { code: string; message: string } | null;
+} {
   const taskContent = fs.readFileSync(taskMdPath, 'utf8');
   const frontmatter = parseTypedTaskFrontmatter(taskContent);
   const fact = readPrDeliveryFact(frontmatter);
   const boundFact = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact : null;
-  return { taskContent, boundFact };
+  const factError = fact.status === 'invalid' ? { code: fact.error.code, message: fact.error.message } : null;
+  return { taskContent, boundFact, factError };
 }
 
 function boundPrNumberForWarning(taskMdPath: string): number | null {
@@ -175,7 +196,7 @@ function inspectionError(error: { code: string; message: string; retryable: bool
 async function inspectBoundPullRequest(
   context: PlatformResult,
   repoRoot: string,
-  prNumber: number,
+  prIdentity: ResourceIdentity,
   loadedContext?: LoadedContext
 ): Promise<{ ok: true; value: PlatformChangeRequestSnapshot } | { ok: false; error: PlatformResult['error']; status: PlatformResult['status'] }> {
   if (!context.platform.repository) {
@@ -185,16 +206,15 @@ async function inspectBoundPullRequest(
     ? { ok: true as const, value: loadedContext }
     : await resolvePlatformProviderContext({ cwd: repoRoot });
   if (!loaded.ok) return { ok: false, status: loaded.context.status, error: loaded.context.error };
-  const target = providerResourceToken(loaded.value.provider, 'pull-request', String(prNumber));
   const inspected = loaded.value.provider.changeRequests?.inspect
-    ? await loaded.value.provider.changeRequests.inspect({ context: providerOperationContext(loaded.value), target })
+    ? await loaded.value.provider.changeRequests.inspect({ context: providerOperationContext(loaded.value), target: prIdentity })
     : unsupportedProviderOperation(loaded.value.provider, 'changeRequests.inspect');
   if (!inspected.ok) {
     const error = providerError(inspected.error, 'PLATFORM_PROVIDER_OPERATION_FAILED');
     return { ok: false, status: inspectionError(error), error };
   }
   const remote: ChangeRequestSnapshot = inspected.value;
-  const number = remote.number ?? resourceIdentityNumber(remote.identity) ?? prNumber;
+  const number = remote.number ?? resourceIdentityNumber(remote.identity) ?? resourceIdentityNumber(prIdentity) ?? 0;
   const head = remote.head || { repository: context.platform.repository, ref: '', sha: remote.headSha || '' };
   const base = remote.base || { repository: context.platform.repository, ref: '', sha: remote.baseSha || '' };
   return {
@@ -202,6 +222,7 @@ async function inspectBoundPullRequest(
     value: {
       repository: context.platform.repository,
       number,
+      identity: remote.identity ?? prIdentity,
       nodeId: remote.id,
       url: remote.displayUrl || '',
       state: remote.state === 'closed' ? 'closed' : 'open',
@@ -223,21 +244,22 @@ async function inspectBoundPullRequest(
 function sameIdentity(left: PlatformChangeRequestSnapshot, right: PlatformChangeRequestSnapshot): boolean {
   return JSON.stringify({
     repository: left.repository,
-    number: left.number,
+    identity: left.identity ?? null,
     base: left.base,
     head: left.head
   }) === JSON.stringify({
     repository: right.repository,
-    number: right.number,
+    identity: right.identity ?? null,
     base: right.base,
     head: right.head
   });
 }
 
 function identityFromSnapshot(snapshot: PlatformChangeRequestSnapshot) {
+  if (!snapshot.identity) throw new Error('pull-request snapshot has no canonical identity');
   return {
     repository: snapshot.repository,
-    number: snapshot.number,
+    resource: snapshot.identity,
     base: { ...snapshot.base },
     head: { ...snapshot.head }
   };
@@ -272,7 +294,7 @@ function currentReportCheck(
   const digest = taskIntentDigest(taskContent);
   if (!digest.ok) return { ok: false, error: platformError(digest.error) };
   const reportIdentity = report.identity;
-  if (reportIdentity.repository !== snapshot.repository || reportIdentity.number !== snapshot.number ||
+  if (reportIdentity.repository !== snapshot.repository || !resourceIdentityEquals(reportIdentity.resource, snapshot.identity) ||
       JSON.stringify(reportIdentity.base) !== JSON.stringify(snapshot.base) || JSON.stringify(reportIdentity.head) !== JSON.stringify(snapshot.head)) return {
     ok: false,
     error: { code: 'PR_CHANGE_REPORT_STALE', message: 'Change report identity does not match the authoritative pull request snapshot', retryable: false }
@@ -329,14 +351,22 @@ async function summaryContext(taskRef: string, options: SummaryOptions = {}): Pr
   };
   const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
   const frontmatter = parseTypedTaskFrontmatter(taskContent);
-  const fact = readPrDeliveryFact(frontmatter, options.runtimeVersion);
-  const prNumber = fact.status === 'valid' && fact.fact.state === 'bound' ? resourceIdentityNumber(fact.fact.identity.resource) : null;
   const reportPath = taskReportPath(resolved.taskDir);
+  const fact = readPrDeliveryFact(frontmatter, options.runtimeVersion);
+  if (fact.status === 'invalid') return {
+    ...platformResult('failed', { error: { code: fact.error.code, message: fact.error.message, retryable: false } }),
+    task: { id: resolved.taskId, prNumber: null },
+    pullRequest: null,
+    changeReport: { status: 'invalid', path: reportPath, taskIntentSha256: null, reason: fact.error.message },
+    artifacts: []
+  };
+  const prIdentity = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
+  const prNumber = resourceIdentityNumber(prIdentity);
   const loaded = await resolvePlatformProviderContext({ cwd: resolved.repoRoot, client: options.client });
   const context = loaded.ok ? loaded.value.context : loaded.context;
   let pullRequest: PlatformChangeRequestSnapshot | null = null;
-  if (loaded.ok && prNumber && context.platform.repository && ['no-op', 'degraded'].includes(context.status)) {
-    const inspected = await inspectBoundPullRequest(context, resolved.repoRoot, prNumber, loaded.value);
+  if (loaded.ok && prIdentity && context.platform.repository && ['no-op', 'degraded'].includes(context.status)) {
+    const inspected = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
     if (inspected.ok) pullRequest = inspected.value;
   }
   const report = summaryReportStatus(reportPath, pullRequest, taskContent, resolved.repoRoot);
@@ -354,6 +384,24 @@ async function summaryContext(taskRef: string, options: SummaryOptions = {}): Pr
   };
 }
 
+async function summaryCommentState(taskRef: string, options: SummaryOptions = {}): Promise<SummaryCommentStateResult> {
+  const context = await summaryContext(taskRef, options);
+  const prIdentity = context.pullRequest?.identity;
+  if (!prIdentity) return { ...context, comment: null };
+  const loaded = await resolvePlatformProviderContext({ cwd: options.cwd, client: options.client });
+  if (!loaded.ok || !loaded.value.provider.comments?.list) return { ...context, comment: null };
+  const listed = await loaded.value.provider.comments.list({
+    context: providerOperationContext(loaded.value),
+    parent: prIdentity
+  });
+  if (!listed.ok) return { ...context, comment: null };
+  const matches = listed.value.filter((comment) => comment.body.includes(summaryMarker(context.task.id!)));
+  return {
+    ...context,
+    comment: matches.length === 1 ? { id: /^\d+$/u.test(matches[0]!.id) ? Number(matches[0]!.id) : matches[0]!.id, body: matches[0]!.body } : null
+  };
+}
+
 type ReportWriteOptions = {
   agent: string;
   mechanicalFile: string;
@@ -366,24 +414,38 @@ type ReportWriteOptions = {
 async function reportWrite(taskRef: string, options: ReportWriteOptions): Promise<ReportWriteResult> {
   const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
   if (!resolved.ok) return { ...platformResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }), report: null };
+  let preflight: ReturnType<typeof readBoundTaskSnapshot>;
+  try {
+    preflight = readBoundTaskSnapshot(resolved.taskMdPath);
+  } catch (error) {
+    return {
+      ...platformResult('failed', { error: { code: 'PR_CHANGE_REPORT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false } }),
+      report: null
+    };
+  }
+  if (preflight.factError) return {
+    ...platformResult('failed', { error: { code: preflight.factError.code, message: preflight.factError.message, retryable: false } }),
+    report: null
+  };
   const loaded = await resolvePlatformProviderContext({ cwd: resolved.repoRoot, client: options.client });
   const context = loaded.ok ? loaded.value.context : loaded.context;
   if (!loaded.ok || !context.platform.repository || !['no-op', 'degraded'].includes(context.status)) return { ...context, report: null };
   let knownPrNumber: number | null = null;
   try {
     return await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, options.agent, async () => {
-      const { taskContent, boundFact } = readBoundTaskSnapshot(resolved.taskMdPath);
-      if (!boundFact) return {
-        ...basePlatformResult('failed', context, resolved.taskId, null, { code: 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false }),
+      const { taskContent, boundFact, factError } = readBoundTaskSnapshot(resolved.taskMdPath);
+      if (factError) return {
+        ...basePlatformResult('failed', context, resolved.taskId, null, { code: factError.code, message: factError.message, retryable: false }),
         report: null
       };
-      const boundPrNumber = resourceIdentityNumber(boundFact.identity.resource);
-      if (!boundPrNumber) return {
-        ...basePlatformResult('failed', context, resolved.taskId, null, { code: 'PR_NUMBER_INVALID', message: 'Bound pull request has no numeric identifier', retryable: false }),
+      if (!boundFact) return {
+        ...basePlatformResult('failed', context, resolved.taskId, null, { code: 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false }),
         report: null
       };
+      const boundPrIdentity = boundFact.identity.resource;
+      const boundPrNumber = resourceIdentityNumber(boundPrIdentity);
       knownPrNumber = boundPrNumber;
-      const initial = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
+      const initial = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrIdentity, loaded.value);
       if (!initial.ok) return { ...basePlatformResult(initial.status, context, resolved.taskId, boundPrNumber, initial.error), report: null };
       const digest = taskIntentDigest(taskContent);
       if (!digest.ok) return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, platformError(digest.error)), report: null };
@@ -407,7 +469,7 @@ async function reportWrite(taskRef: string, options: ReportWriteOptions): Promis
       };
       const built = buildPrChangeReport(identityFromSnapshot(initial.value), digest.value.sha256, mechanical.value, candidate.value);
       if (!built.ok) return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, platformError(built.error)), report: null };
-      const final = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
+      const final = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrIdentity, loaded.value);
       if (!final.ok) return { ...basePlatformResult(final.status, context, resolved.taskId, boundPrNumber, final.error), report: null };
       if (!sameIdentity(initial.value, final.value)) return {
         ...basePlatformResult('blocked', context, resolved.taskId, boundPrNumber, { code: 'PR_CHANGE_REPORT_HEAD_RACE', message: 'Pull request identity changed while generating the change report', retryable: true }),
@@ -450,7 +512,7 @@ async function reportWrite(taskRef: string, options: ReportWriteOptions): Promis
 
 async function syncPullRequestSummary(
   taskRef: string,
-  options: { agent: string; body: string; changeReportFile?: string; cwd?: string; client?: PlatformClient; dryRun?: boolean; strict?: boolean; primaryResult: PullRequestPrimaryResult; runtimeVersion?: string }
+  options: { agent: string; body: string; changeReportFile?: string; cwd?: string; client?: PlatformClient; dryRun?: boolean; strict?: boolean; primaryResult: PullRequestPrimaryResult; runtimeVersion?: string; manualValidation?: ManualValidationSummaryOptions; lockAlreadyHeld?: boolean }
 ): Promise<PullRequestSummaryResult> {
   const warningResult = warningResultForPrimary(options.primaryResult);
   let knownPrNumber: number | null = null;
@@ -503,22 +565,44 @@ async function syncPullRequestSummary(
     return preserveFailure(context);
   }
   try {
-    return await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, options.agent, async () => {
-      const { taskContent, boundFact } = readBoundTaskSnapshot(resolved.taskMdPath);
+    const execute = async (): Promise<PullRequestSummaryResult> => {
+      const { taskContent, boundFact, factError } = readBoundTaskSnapshot(resolved.taskMdPath);
+      if (factError) return {
+        ...platformResult('failed', { resource: { kind: 'pull-request', number: null }, error: { code: factError.code, message: factError.message, retryable: false } }),
+        result: null, warnings: []
+      };
       if (!boundFact) return {
         ...platformResult('failed', { resource: { kind: 'pull-request', number: null }, error: { code: 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false } }),
         result: null, warnings: []
       };
       const prIdentity = boundFact.identity.resource;
       const boundPrNumber = resourceIdentityNumber(prIdentity);
-      if (!boundPrNumber) return {
-        ...platformResult('failed', { resource: { kind: 'pull-request', number: null }, error: { code: 'PR_NUMBER_INVALID', message: 'Bound pull request has no numeric identifier', retryable: false } }),
-        result: null, warnings: []
-      };
       knownPrNumber = boundPrNumber;
       const prNumber = boundPrNumber;
-      const initial = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
+      const initial = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
       if (!initial.ok) return fail(initial.status, context, initial.error);
+      const manual = options.manualValidation;
+      const hasFinalManualValidation = /###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)/u.test(options.body);
+      if (hasFinalManualValidation && (!manual || manual.phase !== 'final')) return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'final manual-validation summary requires the transaction coordinator', retryable: false }, prNumber);
+      if (manual && (manual.phase === 'pending' ? hasFinalManualValidation : !hasFinalManualValidation)) return fail('failed', context, { code: 'MANUAL_VALIDATION_SUMMARY_PHASE_INVALID', message: 'manual-validation summary phase does not match the requested writer phase', retryable: false }, prNumber);
+      if (manual) {
+        if (prNumber === null) return fail('failed', context, { code: 'MANUAL_VALIDATION_PR_NUMBER_REQUIRED', message: 'manual-validation summary requires a numeric pull-request identity', retryable: false }, prNumber);
+        if (manual.phase === 'final' && (!manual.transactionId || !manual.receiptDigest || !manual.prHeadSha || manual.prHeadSha !== initial.value.head.sha)) return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'final manual-validation summary requires transaction, receipt, and current head identity', retryable: false }, prNumber);
+        if (manual.phase === 'final') {
+          if (manual.authority !== 'coordinator') return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'final manual-validation summary requires coordinator authority', retryable: false }, prNumber);
+          const completion = readManualValidationCompletion(resolved.taskDir, {
+            transactionId: manual.transactionId,
+            taskId: resolved.taskId,
+            prNumber,
+            prHeadSha: initial.value.head.sha,
+            receiptDigest: manual.receiptDigest
+          });
+          if (!completion.ok) return fail('failed', context, platformError(completion.error), prNumber);
+          const { receipt, transaction } = completion.value;
+          if (transaction.phase !== 'final-promotion-in-progress' || !transaction.eventAppended) return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'final summary requires a receipt-backed promotion intent', retryable: false }, prNumber);
+          if (!manualValidationFinalSummaryProjectionMatches(options.body, receipt)) return fail('failed', context, { code: 'MANUAL_VALIDATION_SUMMARY_PROJECTION_INVALID', message: 'final summary body does not match the canonical receipt projection', retryable: false }, prNumber);
+        }
+      }
       const expectedReportPath = taskReportPath(resolved.taskDir);
       const suppliedReportPath = path.resolve(resolved.repoRoot, options.changeReportFile!);
       if (suppliedReportPath !== expectedReportPath) return fail('failed', context, { code: 'PR_CHANGE_REPORT_PATH_INVALID', message: 'summary-sync must consume the task-bound pr-change-report.json', retryable: false });
@@ -569,7 +653,7 @@ async function syncPullRequestSummary(
         ? listed.value.find((comment) => comment.id === reconciliation.commentId)?.body ?? null
         : null;
       const info = { precheckVerdict: report.value.precheck.verdict, nextAction: report.value.precheck.route } as const;
-      const beforeWrite = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
+      const beforeWrite = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
       if (!beforeWrite.ok) return fail(beforeWrite.status, context, beforeWrite.error, prNumber);
       if (!sameIdentity(initial.value, beforeWrite.value)) return fail('blocked', context, {
         code: 'PR_SUMMARY_HEAD_RACE',
@@ -599,7 +683,7 @@ async function syncPullRequestSummary(
         })
         : unsupportedProviderOperation(loaded.value.provider, 'comments.write');
       if (!written.ok) return fail(providerStatus(written.error) === 'blocked' ? 'blocked' : 'failed', context, providerError(written.error, 'PLATFORM_PROVIDER_OPERATION_FAILED'), prNumber);
-      const after = await inspectBoundPullRequest(context, resolved.repoRoot, prNumber, loaded.value);
+      const after = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
       const id = /^\d+$/.test(written.value.remoteId) ? Number(written.value.remoteId) : written.value.remoteId;
       const compensateWrittenSummary = async () => reconciliation.action === 'create'
         ? written.value.remoteId && loaded.value.provider.comments?.delete
@@ -651,7 +735,10 @@ async function syncPullRequestSummary(
         operations: [{ name: `summary:${reconciliation.action}`, status: 'applied', reasonCode: null }],
         result: null, warnings: [], ...info
       };
-    });
+    };
+    return await (options.lockAlreadyHeld
+      ? execute()
+      : withTaskExecutionLock(resolved.repoRoot, resolved.taskId, options.agent, execute));
   } catch (error) {
     const lockError = error instanceof TaskExecutionLockError
       ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
@@ -664,9 +751,10 @@ export {
   buildPullRequestSummary,
   reconcileSummaryComment,
   reportWrite,
+  summaryCommentState,
   summaryContext,
   summaryMarker,
   syncPullRequestSummary,
   warningResultForPrimary
 };
-export type { PullRequestSummaryResult, ReportWriteOptions, ReportWriteResult, SummaryContextResult };
+export type { ManualValidationSummaryOptions, PullRequestSummaryResult, ReportWriteOptions, ReportWriteResult, SummaryCommentStateResult, SummaryContextResult };

package/lib/platform/pull-requests.ts

@@ -1,3 +1,4 @@
+import { normalizePullRequest, type RemotePullRequest } from './github-data.ts';
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
@@ -6,7 +7,7 @@ import { parseTypedTaskFrontmatter } from '../task/frontmatter.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { extractSection } from '../task/sections.ts';
 import { captureTaskWriteMetadata, writeTask } from '../task/write.ts';
-import type { PlatformChangeRequestSnapshot } from './adapters.ts';
+import type { PlatformChangeRequestSnapshot } from './snapshots.ts';
 import { resolvePlatformProviderContext } from './context.ts';
 import type { PlatformClient } from './context.ts';
 import { inspectPlatformIssue } from './issues.ts';
@@ -61,7 +62,6 @@ type PullRequestResult = PlatformResult & {
     effect: 'no-op' | 'applied' | 'unknown';
   }>;
 };
-type GitHubClient = PlatformClient;
 type InspectionOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string };
 type SharedOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string };
 type CreateOptions = SharedOptions & {
@@ -93,54 +93,6 @@ type ExternalPullRequestResult = PullRequestResult & {
 
 type CreatePhase = 'before-post' | 'post-dispatched' | 'post-accepted';
 
-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 };
-  } } } };
-};
-
 function warningResultForPrimary(primaryResult: PullRequestPrimaryResult): NonNullable<PullRequestResult['result']> {
   if (primaryResult === 'pr_created') return 'pr_created_with_warnings';
   if (primaryResult === 'pr_reused') return 'pr_reused_with_warnings';
@@ -189,57 +141,6 @@ const PRECONDITION_NOT_CREATED: CreationOutcome = {
   kind: 'not-created', reason: 'precondition-failed', createdByCurrentOperation: false
 };
 
-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 repositoryKey(repository: string): string {
   return repository.trim().toLowerCase();
 }
@@ -329,51 +230,6 @@ function selectExternalPullRequest(
   return { status: 'selected', source: 'unique', selected: eligible[0]!, candidates, eligible };
 }
 
-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 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 expectedHead(repository: string, head: string): { repository: string; ref: string } {
   const colon = head.indexOf(':');
   if (colon === -1) return { repository, ref: head };
@@ -520,7 +376,7 @@ async function resolvedContext(taskRef: string, options: InspectionOptions) {
   }) };
   const fact = factRead.status === 'valid' ? factRead.fact : null;
   let issueIdentity: ResourceIdentity | null;
-  try { issueIdentity = taskIssueIdentity(frontmatter, undefined, options.runtimeVersion); }
+  try { issueIdentity = taskIssueIdentity(frontmatter); }
   catch (error) { return { ok: false as const, output: result('failed', resolved.taskId, null, null, { error: { ...taskIssueIdentityError(error), retryable: false } }) }; }
   const issueNumber = resourceIdentityNumber(issueIdentity);
   const prIdentity = fact?.state === 'bound' ? fact.identity.resource : null;
@@ -606,15 +462,6 @@ async function inspectExternalPullRequest(
   });
 }
 
-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 } };
-}
-
 async function inspectPlatformPullRequest(taskRef: string, options: InspectionOptions = {}): Promise<PullRequestResult> {
   const base = await resolvedContext(taskRef, options);
   if (!base.ok) return base.output;
@@ -1094,7 +941,7 @@ async function resolveExternalPullRequest(taskRef: string, options: ResolveExter
   if (!base.issueIdentity) return externalResult(result('failed', base.resolved.taskId, null, base.prNumber, {
     platform: base.context.platform,
     capabilities: base.context.capabilities,
-    error: { code: 'EXTERNAL_DELIVERY_ISSUE_REQUIRED', message: 'External delivery requires a valid issue_number', retryable: false }
+    error: { code: 'EXTERNAL_DELIVERY_ISSUE_REQUIRED', message: 'External delivery requires a valid platform issue identity', retryable: false }
   }));
   const inspected = base.provider.changeRequests?.listClosing
     ? await base.provider.changeRequests.listClosing({
@@ -1583,7 +1430,7 @@ function skipPlatformPullRequestFactUnlocked(
     });
   }
   let issueIdentity: ResourceIdentity | null;
-  try { issueIdentity = taskIssueIdentity(frontmatter, undefined, options.runtimeVersion); }
+  try { issueIdentity = taskIssueIdentity(frontmatter); }
   catch (error) { return result('failed', resolved.taskId, null, null, { error: { ...taskIssueIdentityError(error), retryable: false } }); }
   const issueNumber = resourceIdentityNumber(issueIdentity);
   const existing = readPrDeliveryFact(frontmatter, options.runtimeVersion);
@@ -1656,20 +1503,6 @@ async function skipPlatformPullRequestFact(taskRef: string, options: SkipFactOpt
   }
 }
 
-export {
-  bindPlatformPullRequest,
-  createPlatformPullRequest,
-  inspectGitHubPullRequest,
-  inspectGitHubIssueClosingChangeRequests,
-  inspectPlatformPullRequest,
-  inspectPlatformPullRequestByNumber,
-  normalizePullRequest,
-  resolveExternalPullRequest,
-  skipPlatformPullRequestFact,
-  selectExternalPullRequest,
-  selectPullRequest,
-  syncPlatformPullRequest,
-  syncPlatformPullRequestInLabels
-};
+export { bindPlatformPullRequest, createPlatformPullRequest, inspectPlatformPullRequest, inspectPlatformPullRequestByNumber, resolveExternalPullRequest, skipPlatformPullRequestFact, selectExternalPullRequest, selectPullRequest, syncPlatformPullRequest, syncPlatformPullRequestInLabels };
 export type { BindOptions, CreateOptions, ExternalPullRequestResult, ExternalPullRequestSelection, PullRequestPrimaryResult, PullRequestResult, PullRequestSnapshot, ResolveExternalOptions, SkipFactOptions, SyncOptions };
 export { warningResultForPrimary };

package/lib/platform/snapshots.ts

@@ -0,0 +1,53 @@
+import type { ResourceIdentity } from './resource-identity.ts';
+
+export type PlatformIssueSnapshot = {
+  repository: string;
+  number: number;
+  identity?: ResourceIdentity;
+  databaseId: number | null;
+  nodeId: string;
+  url: string;
+  state: 'open' | 'closed';
+  title: string;
+  body: string;
+  labels: string[];
+  assignees: string[];
+  milestone: string | null;
+  issueType: string | null;
+  fields: Record<string, string | number | null>;
+};
+
+export type PlatformMergeability = {
+  state: 'mergeable' | 'conflicting' | 'unknown';
+  detail: string | null;
+};
+
+export 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;
+  identity?: ResourceIdentity;
+};
+
+export type PlatformCheckSnapshot = {
+  name: string;
+  bucket: 'pass' | 'fail' | 'pending' | 'cancel';
+  workflow?: string | null;
+  conclusion?: string | null;
+  detailsUrl?: string | null;
+  startedAt?: string | null;
+  completedAt?: string | null;
+};