@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/lib/platform/issues.ts

@@ -1,3 +1,5 @@
+import type { PlatformIssueSnapshot as IssueSnapshot } from './snapshots.ts';
+import type { IssueFieldSchema } from './github-data.ts';
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
@@ -38,26 +40,7 @@ import {
 import { resourceIdentityEquals, resourceIdentityNumber, resourceIdentityString, serializeResourceIdentity } from './resource-identity.ts';
 import { taskIssueIdentity, taskIssueIdentityError } from './task-identities.ts';
 import type { ResourceIdentity } from './resource-identity.ts';
-
-type GitHubClient = PlatformClient;
 import type { IssueSnapshot as ProviderIssueSnapshot, RepositoryMetadataSnapshot } from './provider-contract.ts';
-
-type IssueSnapshot = {
-  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>;
-};
 type IssueResult = PlatformResult & {
   task: { id: string | null; issueNumber: number | null };
   issue: IssueSnapshot | null;
@@ -80,33 +63,6 @@ type SyncOptions = SharedOptions & {
   dryRun?: boolean;
 };
 
-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_TYPES_QUERY = `query($owner:String!){organization(login:$owner){issueTypes(first:20){nodes{id name pinnedFields{__typename ... on IssueFieldSingleSelect{id name options{id name}} ... on IssueFieldDate{id name} ... on IssueFieldText{id name} ... on IssueFieldNumber{id name}}}}}}`;
-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 result(
   status: PlatformResult['status'],
   taskId: string | null,
@@ -235,118 +191,6 @@ async function inspectExternalIssue(
   });
 }
 
-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 normalizeIssueTypes(value: unknown): IssueTypeSchema[] {
-  const nodes = (value as { data?: { organization?: { issueTypes?: { nodes?: unknown[] } } } })?.data?.organization?.issueTypes?.nodes;
-  return (nodes || []).flatMap((raw) => {
-    const item = raw as { id?: string; name?: string; pinnedFields?: unknown[] };
-    return item.id && item.name ? [{ id: item.id, name: item.name, fields: normalizeFieldSchemas(item.pinnedFields) }] : [];
-  });
-}
-
-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 } };
-}
-
-function inspectGitHubIssueMetadata(client: GitHubClient, repository: string, issue: number, cwd: string) {
-  const fetched = fetchIssue(client, repository, issue, cwd);
-  if (!fetched.ok) return fetched;
-  const remote = fetched.value;
-  return {
-    ok: true as const,
-    value: {
-      state: String(remote.state || '').toLowerCase() === 'closed' ? 'closed' as const : 'open' as const,
-      labels: (remote.labels || []).map((label: string | { name?: string }) => typeof label === 'string' ? label : label.name || '').filter(Boolean).sort(),
-      body: remote.body || '',
-      milestone: remote.milestone?.title || null
-    }
-  };
-}
-
 async function inspectPlatformIssue(taskRef: string, options: SharedOptions = {}): Promise<IssueResult> {
   const base = await resolvedContext(taskRef, options);
   if (!base.ok) return base.output;
@@ -543,14 +387,6 @@ function requirementsFromTask(content: string): Requirement[] {
   }));
 }
 
-function flattenPages(value: unknown): unknown[] {
-  return Array.isArray(value) ? value.flatMap((item) => Array.isArray(item) ? item : [item]) : [];
-}
-
-function listNames(value: unknown): string[] {
-  return flattenPages(value).map((item) => typeof item === 'string' ? item : String((item as { name?: string }).name || '')).filter(Boolean);
-}
-
 function milestoneBasis(repoRoot: string, current: string | null): string | null {
   if (!current || !/^\d+\.\d+\.x$/.test(current)) return current;
   try {
@@ -642,73 +478,6 @@ function desiredFieldValues(frontmatter: Record<string, string>, fields: IssueFi
   return desired;
 }
 
-function planGraphMetadata(
-  client: GitHubClient,
-  repository: string,
-  issue: number,
-  cwd: string,
-  frontmatter: Record<string, string>,
-  options: Pick<SyncOptions, 'issueType' | 'fields'>,
-  capabilities: PlatformResult['capabilities']
-): { operations: PlannedOperation[]; issueId: string | null } {
-  if (!options.issueType && !options.fields) return { operations: [], issueId: null };
-  if (!capabilities.push) return {
-    operations: [
-      ...(options.issueType ? [{ name: 'issue-type', status: 'skipped' as const, reasonCode: 'PUSH_REQUIRED' }] : []),
-      ...(options.fields ? [{ name: 'fields', status: 'skipped' as const, reasonCode: 'PUSH_REQUIRED' }] : [])
-    ], issueId: null
-  };
-  const [owner] = repository.split('/');
-  const typesResult = client.json<unknown>(['api', 'graphql', '-f', `query=${ISSUE_TYPES_QUERY}`, '-F', `owner=${owner}`], { cwd });
-  if (!typesResult.ok) return { operations: [{ name: 'issue-schema', status: 'failed', reasonCode: typesResult.error.code }], issueId: null };
-  const types = normalizeIssueTypes(typesResult.value);
-  if (types.length === 0) return {
-    operations: [
-      ...(options.issueType ? [{ name: 'issue-type', status: 'skipped' as const, reasonCode: 'ISSUE_TYPES_UNSUPPORTED' }] : []),
-      ...(options.fields ? [{ name: 'fields', status: 'skipped' as const, reasonCode: 'ISSUE_TYPES_UNSUPPORTED' }] : [])
-    ], issueId: null
-  };
-  const current = graphState(client, repository, issue, cwd);
-  if (!current?.issueId) return { operations: [{ name: 'issue-schema', status: 'failed', reasonCode: 'ISSUE_GRAPH_IDENTITY_INVALID' }], issueId: null };
-  const target = types.find((type) => type.name === desiredIssueType(frontmatter.type || ''));
-  if (!target) return { operations: [{ name: 'issue-type', status: 'failed', reasonCode: 'ISSUE_TYPE_NOT_FOUND' }], issueId: current.issueId };
-  const operations: PlannedOperation[] = [];
-  if (options.issueType) operations.push(current.type?.id === target.id
-    ? { name: 'issue-type', status: 'no-op', reasonCode: null }
-    : { name: 'issue-type', status: 'planned', reasonCode: null, value: { issueTypeId: target.id } });
-  if (options.fields) {
-    const desired = desiredFieldValues(frontmatter, target.fields);
-    const inputs = desired.filter((field) => current.values.find((value) => value.name === field.name)?.value !== field.value).map((field) => field.input);
-    if (current.type?.id !== target.id) {
-      const targetNames = new Set(target.fields.map((field) => field.name));
-      for (const old of current.values) if (!targetNames.has(old.name)) inputs.push({ fieldId: old.id, delete: true });
-    }
-    operations.push(inputs.length === 0
-      ? { name: 'fields', status: 'no-op', reasonCode: null }
-      : { name: 'fields', status: 'planned', reasonCode: null, value: inputs });
-  }
-  return { operations, issueId: current.issueId };
-}
-
-function executeGraphOperation(
-  client: GitHubClient,
-  cwd: string,
-  issueId: string,
-  operation: PlannedOperation
-) {
-  if (operation.name === 'issue-type') {
-    const query = 'mutation($issueId:ID!,$issueTypeId:ID){updateIssueIssueType(input:{issueId:$issueId,issueTypeId:$issueTypeId}){issue{id}}}';
-    const typeId = (operation.value as { issueTypeId: string }).issueTypeId;
-    return client.json(['api', 'graphql', '--input', '-'], {
-      cwd, method: 'POST', input: JSON.stringify({ query, variables: { issueId, issueTypeId: typeId } })
-    });
-  }
-  const query = 'mutation($issueId:ID!,$issueFields:[IssueFieldCreateOrUpdateInput!]!){setIssueFieldValue(input:{issueId:$issueId,issueFields:$issueFields}){issue{id}}}';
-  return client.json(['api', 'graphql', '--input', '-'], {
-    cwd, method: 'POST', input: JSON.stringify({ query, variables: { issueId, issueFields: operation.value } })
-  });
-}
-
 async function syncPlatformIssue(taskRef: string, options: SyncOptions): Promise<IssueResult> {
   const base = await resolvedContext(taskRef, options);
   if (!base.ok) return base.output;
@@ -849,15 +618,5 @@ async function syncPlatformIssue(taskRef: string, options: SyncOptions): Promise
   });
 }
 
-export {
-  bindPlatformIssue,
-  createPlatformIssue,
-  graphState,
-  inspectGitHubIssue,
-  inspectGitHubIssueMetadata,
-  inspectPlatformIssue,
-  normalizeIssue,
-  requirementSectionAnchors,
-  syncPlatformIssue
-};
-export type { BindOptions, CreateOptions, IssueResult, IssueSnapshot, SyncOptions };
+export { bindPlatformIssue, createPlatformIssue, inspectPlatformIssue, requirementSectionAnchors, syncPlatformIssue };
+export type { BindOptions, CreateOptions, IssueResult, SyncOptions };

package/lib/platform/pr-checks.ts

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 
 import { parseTypedTaskFrontmatter } from '../task/frontmatter.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
-import type { PlatformCheckSnapshot } from './adapters.ts';
+import type { PlatformCheckSnapshot } from './snapshots.ts';
+import { checkStatusBucket } from './check-status.ts';
 import { resolvePlatformProviderContext } from './context.ts';
 import type { PlatformClient } from './context.ts';
 import { inspectPlatformPullRequest } from './pull-requests.ts';
@@ -33,7 +34,6 @@ type ChecksResult = PlatformResult & {
   resolution?: { status: 'resolved' | 'missing' | 'ambiguous'; runId: number | null; jobId: number | null };
   logs?: { runId: number; jobId?: number; text: string };
 };
-type GitHubClient = PlatformClient;
 type InspectionOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string };
 type SharedOptions = { cwd?: string; client?: PlatformClient };
 
@@ -56,18 +56,6 @@ function classifyPullRequestReadiness(input: {
   return { state: 'ready', headSha: input.headSha };
 }
 
-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 resolveRunCandidate(candidates: RunCandidate[], headSha: string, checkName: string):
   | { status: 'resolved'; runId: number; jobId: number | null }
   | { status: 'missing' | 'ambiguous'; runId: null; jobId: null } {
@@ -85,41 +73,6 @@ function checksResult(status: PlatformResult['status'], overrides: Partial<Check
   };
 }
 
-function normalizeBucket(value: { bucket?: string; status?: string; state?: string; conclusion?: string }): CheckBucket {
-  const raw = String(value.bucket || value.status || value.conclusion || value.state || '').toLowerCase();
-  if (['pass', 'success', 'successful', 'neutral'].includes(raw)) return 'pass';
-  if (['fail', 'failure', 'failed', 'error', 'timed_out', 'action_required'].includes(raw)) return 'fail';
-  if (['cancel', 'cancelled', 'canceled', 'skipped', 'stale'].includes(raw)) return 'cancel';
-  return 'pending';
-}
-
-function normalizeChecks(value: unknown): CheckSnapshot[] {
-  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,
-      bucket: normalizeBucket(item as { bucket?: string; state?: string; conclusion?: string }),
-      workflow: item.workflow ? String(item.workflow) : null,
-      conclusion: item.conclusion ? String(item.conclusion) : item.state ? String(item.state) : null,
-      detailsUrl: item.link ? String(item.link) : item.detailsUrl ? String(item.detailsUrl) : null,
-      startedAt: item.startedAt ? String(item.startedAt) : null,
-      completedAt: item.completedAt ? String(item.completedAt) : 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: normalizeChecks(inspected.value) }
-    : { ok: false as const, error: inspected.error };
-}
-
 async 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 } }) };
@@ -141,14 +94,12 @@ async function resolvedTask(taskRef: string, options: InspectionOptions) {
 async function inspectRequiredChecks(taskRef: string, options: InspectionOptions = {}): Promise<ChecksResult> {
   const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
-  return inspectChecksForResolvedTask(base, options);
+  return inspectChecksForResolvedTask(base);
 }
 
 async function inspectChecksForResolvedTask(
-  base: Extract<Awaited<ReturnType<typeof resolvedTask>>, { ok: true }>,
-  options: InspectionOptions
+  base: Extract<Awaited<ReturnType<typeof resolvedTask>>, { ok: true }>
 ): Promise<ChecksResult> {
-  const repository = base.context.platform.repository!;
   {
     const inspected = base.provider.checks?.inspectRequired
       ? await base.provider.checks.inspectRequired({
@@ -164,7 +115,13 @@ async function inspectChecksForResolvedTask(
       pullRequest: base.pullRequest,
       error: providerError(inspected.error, 'PLATFORM_PROVIDER_OPERATION_FAILED')
     });
-    const required = normalizeChecks(inspected.value);
+    const required = inspected.value.map((check): CheckSnapshot => ({
+      name: check.name,
+      bucket: checkStatusBucket(check.status),
+      conclusion: check.conclusion || null,
+      detailsUrl: check.detailsUrl || null,
+      workflow: null, startedAt: null, completedAt: null
+    }));
     const classified = classifyRequiredChecks(required);
     const status = classified.state === 'passed' || classified.state === 'no-required'
       ? 'no-op'
@@ -184,7 +141,7 @@ async function inspectChecksForResolvedTask(
 async function inspectPullRequestReadiness(taskRef: string, options: InspectionOptions = {}): Promise<ChecksResult> {
   const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
-  const checked = await inspectChecksForResolvedTask(base, options);
+  const checked = await inspectChecksForResolvedTask(base);
   const classifiedCodes = new Set(['REQUIRED_CHECKS_PENDING', 'REQUIRED_CHECKS_FAILED', 'REQUIRED_CHECKS_CANCELLED']);
   if (checked.error && !classifiedCodes.has(checked.error.code)) return checked;
   const readiness = classifyPullRequestReadiness({
@@ -271,15 +228,6 @@ async function resolvePlatformCheckRun(taskRef: string, options: SharedOptions &
   }
 }
 
-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 });
-}
-
 async function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions & { run: number; job?: number }): Promise<ChecksResult> {
   const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
@@ -308,17 +256,5 @@ async function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions &
   }
 }
 
-export {
-  classifyPullRequestReadiness,
-  classifyRequiredChecks,
-  fetchCheckLogText,
-  fetchPlatformCheckLogs,
-  inspectGitHubRequiredChecks,
-  inspectRequiredChecks,
-  inspectPullRequestReadiness,
-  parseRunJobIdentity,
-  resolvePlatformCheckRun,
-  resolveRunCandidate,
-  watchPullRequestReadiness
-};
+export { classifyPullRequestReadiness, classifyRequiredChecks, fetchPlatformCheckLogs, inspectRequiredChecks, inspectPullRequestReadiness, resolvePlatformCheckRun, resolveRunCandidate, watchPullRequestReadiness };
 export type { CheckBucket, CheckSnapshot, ChecksResult, ChecksSnapshot, CheckState, ReadinessSnapshot, ReadinessState, RunCandidate };

package/lib/platform/pr-summary.ts

@@ -16,7 +16,7 @@ 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 type { PlatformChangeRequestSnapshot } from './snapshots.ts';
 import type { ChangeRequestSnapshot } from './provider-contract.ts';
 import {
   buildPrChangeReport,
@@ -33,6 +33,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 +52,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 -->`;
@@ -354,6 +368,23 @@ async function summaryContext(taskRef: string, options: SummaryOptions = {}): Pr
   };
 }
 
+async function summaryCommentState(taskRef: string, options: SummaryOptions = {}): Promise<SummaryCommentStateResult> {
+  const context = await summaryContext(taskRef, options);
+  if (!context.task.prNumber || !context.pullRequest) 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: providerResourceToken(loaded.value.provider, 'pull-request', String(context.task.prNumber))
+  });
+  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;
@@ -450,7 +481,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,7 +534,7 @@ async function syncPullRequestSummary(
     return preserveFailure(context);
   }
   try {
-    return await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, options.agent, async () => {
+    const execute = async (): Promise<PullRequestSummaryResult> => {
       const { taskContent, boundFact } = readBoundTaskSnapshot(resolved.taskMdPath);
       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 } }),
@@ -519,6 +550,27 @@ async function syncPullRequestSummary(
       const prNumber = boundPrNumber;
       const initial = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, 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 (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 });
@@ -651,7 +703,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 +719,10 @@ export {
   buildPullRequestSummary,
   reconcileSummaryComment,
   reportWrite,
+  summaryCommentState,
   summaryContext,
   summaryMarker,
   syncPullRequestSummary,
   warningResultForPrimary
 };
-export type { PullRequestSummaryResult, ReportWriteOptions, ReportWriteResult, SummaryContextResult };
+export type { ManualValidationSummaryOptions, PullRequestSummaryResult, ReportWriteOptions, ReportWriteResult, SummaryCommentStateResult, SummaryContextResult };