@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/lib/platform/pull-requests.ts

@@ -7,6 +7,7 @@ import { extractSection } from '../task/sections.ts';
 import { captureTaskWriteMetadata, writeTask } from '../task/write.ts';
 import {
   inspectPlatformChangeRequest,
+  inspectPlatformIssueClosingChangeRequests,
   registerPlatformCapabilities
 } from './adapters.ts';
 import type { PlatformChangeRequestSnapshot } from './adapters.ts';
@@ -17,6 +18,7 @@ import { inspectPlatformIssue } from './issues.ts';
 import { planPullRequestMetadata } from './pull-request-metadata.ts';
 import { platformResult } from './types.ts';
 import type { PlatformOperation, PlatformResult } from './types.ts';
+import { inspectCompletionArtifacts } from '../task/finalization-artifacts.ts';
 
 type PullRequestSnapshot = PlatformChangeRequestSnapshot;
 
@@ -37,6 +39,18 @@ type CreateOptions = SharedOptions & {
 };
 type BindOptions = SharedOptions & { agent: string; pr: number; dryRun?: boolean };
 type SyncOptions = SharedOptions & { agent: string; metadata?: boolean; closingIssue?: boolean; dryRun?: boolean };
+type ResolveExternalOptions = SharedOptions & { agent: string; pr?: number; dryRun?: boolean };
+type ExternalPullRequestSelection =
+  | { status: 'normal'; candidates: PullRequestSnapshot[]; eligible: [] }
+  | { status: 'selected'; source: 'unique' | 'explicit'; selected: PullRequestSnapshot; candidates: PullRequestSnapshot[]; eligible: PullRequestSnapshot[] }
+  | { status: 'failed'; code: string; message: string; candidates: PullRequestSnapshot[]; eligible: PullRequestSnapshot[] };
+type ExternalPullRequestResult = PullRequestResult & {
+  mode: 'normal' | 'external' | null;
+  authorization: 'unique' | 'explicit' | null;
+  candidates: PullRequestSnapshot[];
+  eligible: PullRequestSnapshot[];
+  selected: PullRequestSnapshot | null;
+};
 
 type RemotePullRequest = {
   number?: number;
@@ -54,6 +68,36 @@ type RemotePullRequest = {
   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 result(
@@ -71,12 +115,33 @@ function result(
   };
 }
 
+function externalResult(
+  base: PullRequestResult,
+  overrides: Partial<ExternalPullRequestResult> = {}
+): ExternalPullRequestResult {
+  return {
+    ...base,
+    mode: null,
+    authorization: null,
+    candidates: [],
+    eligible: [],
+    selected: null,
+    ...overrides
+  };
+}
+
 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,
@@ -92,8 +157,149 @@ function normalizePullRequest(remote: RemotePullRequest, repository: string): Pu
     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
+    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();
+}
+
+function identitySignature(pullRequest: PullRequestSnapshot): string {
+  return [
+    pullRequest.repository, pullRequest.number, pullRequest.nodeId, pullRequest.url,
+    pullRequest.head.repository, pullRequest.head.ref, pullRequest.head.sha,
+    pullRequest.base.repository, pullRequest.base.ref, pullRequest.base.sha,
+    pullRequest.mergedAt || '', pullRequest.mergeCommitSha || ''
+  ].join('|');
+}
+
+function hasCompleteExternalIdentity(pullRequest: PullRequestSnapshot): boolean {
+  const required = [
+    pullRequest.repository, pullRequest.nodeId, pullRequest.url,
+    pullRequest.head.repository, pullRequest.head.ref, pullRequest.head.sha,
+    pullRequest.base.repository, pullRequest.base.ref, pullRequest.base.sha
+  ];
+  return Number.isInteger(pullRequest.number) && pullRequest.number > 0 &&
+    required.every((value) => Boolean(value?.trim())) &&
+    Boolean(pullRequest.mergedAt) === Boolean(pullRequest.mergeCommitSha);
+}
+
+function selectExternalPullRequest(
+  candidates: PullRequestSnapshot[],
+  repository: string,
+  existingPrNumber: number | null,
+  explicitPrNumber: number | null
+): ExternalPullRequestSelection {
+  const invalid = candidates.find((candidate) => !hasCompleteExternalIdentity(candidate));
+  if (invalid) return {
+    status: 'failed', code: 'PR_IDENTITY_INVALID',
+    message: `Closing PR #${invalid.number} lacks required identity`, candidates, eligible: []
+  };
+  const byNumber = new Map<number, string>();
+  for (const candidate of candidates) {
+    const signature = identitySignature(candidate);
+    const prior = byNumber.get(candidate.number);
+    if (prior && prior !== signature) return {
+      status: 'failed', code: 'PR_IDENTITY_INVALID',
+      message: `Closing PR #${candidate.number} has conflicting identities`, candidates, eligible: []
+    };
+    byNumber.set(candidate.number, signature);
+  }
+  const unique = candidates.filter((candidate, index) =>
+    candidates.findIndex((other) => other.number === candidate.number) === index
+  );
+  const wantedRepository = repositoryKey(repository);
+  const eligible = unique.filter((candidate) =>
+    repositoryKey(candidate.repository) === wantedRepository &&
+    repositoryKey(candidate.base.repository) === wantedRepository &&
+    Boolean(candidate.mergedAt && candidate.mergeCommitSha)
+  );
+  if (explicitPrNumber !== null) {
+    const selected = unique.find((candidate) => candidate.number === explicitPrNumber);
+    if (!selected) return { status: 'failed', code: 'PR_NOT_FOUND', message: `PR #${explicitPrNumber} is not a closing PR`, candidates, eligible };
+    if (!eligible.some((candidate) => candidate.number === explicitPrNumber)) {
+      return { status: 'failed', code: 'PR_IDENTITY_INVALID', message: `PR #${explicitPrNumber} is not an eligible merged PR`, candidates, eligible };
+    }
+    if (existingPrNumber !== null && existingPrNumber !== explicitPrNumber) {
+      return { status: 'failed', code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${existingPrNumber}`, candidates, eligible };
+    }
+    return { status: 'selected', source: 'explicit', selected, candidates, eligible };
+  }
+  if (existingPrNumber !== null && eligible.length === 1 && existingPrNumber !== eligible[0]!.number) {
+    return { status: 'failed', code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${existingPrNumber}`, candidates, eligible };
+  }
+  if (eligible.length === 0) return { status: 'normal', candidates, eligible: [] };
+  if (eligible.length > 1) return {
+    status: 'failed', code: 'PR_IDENTITY_AMBIGUOUS',
+    message: 'Multiple eligible merged closing pull requests were found', candidates, eligible
+  };
+  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 } {
@@ -246,6 +452,11 @@ registerPlatformCapabilities('github', {
   inspectChangeRequest({ client, repository, number, cwd }) {
     return inspectGitHubPullRequest((client as GitHubClient | undefined) || createGitHubClient(), repository, number, cwd);
   },
+  inspectIssueClosingChangeRequests({ client, repository, issueNumber, cwd }) {
+    return inspectGitHubIssueClosingChangeRequests(
+      (client as GitHubClient | undefined) || createGitHubClient(), repository, issueNumber, cwd
+    );
+  },
   resolveChangeRequestGitEvidence(context) {
     return resolveGitHubChangeRequestGitEvidence(context);
   }
@@ -297,6 +508,44 @@ function inspectPlatformPullRequest(taskRef: string, options: InspectionOptions
   });
 }
 
+function inspectPlatformPullRequestByNumber(prNumber: number, options: InspectionOptions = {}): PullRequestResult {
+  const client = (options.client as GitHubClient | undefined) || createGitHubClient();
+  const context = resolvePlatformContext({ cwd: options.cwd || process.cwd(), client });
+  const usable = (context.status === 'no-op' || context.status === 'degraded') && context.platform.repository;
+  if (!usable) {
+    return result(context.status, null, null, null, {
+      platform: context.platform, capabilities: context.capabilities, operations: context.operations, error: context.error
+    });
+  }
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    return result('failed', null, null, null, {
+      platform: context.platform, capabilities: context.capabilities,
+      error: { code: 'PR_NUMBER_INVALID', message: 'PR number must be positive', retryable: false }
+    });
+  }
+  const fetched = inspectPlatformChangeRequest(context.platform.type, {
+    cwd: options.cwd || process.cwd(),
+    repository: context.platform.repository!,
+    number: prNumber,
+    client
+  });
+  if (!fetched.ok || !fetched.value) {
+    const error = fetched.error || {
+      code: 'PR_INSPECTION_INVALID',
+      message: 'Platform adapter returned no change-request snapshot',
+      retryable: false
+    };
+    return result(error.retryable ? 'blocked' : 'failed', null, null, prNumber, {
+      platform: context.platform, capabilities: context.capabilities,
+      resource: { kind: 'pull-request', number: prNumber }, error
+    });
+  }
+  return result('no-op', null, null, prNumber, {
+    platform: context.platform, capabilities: context.capabilities,
+    resource: { kind: 'pull-request', number: prNumber }, pullRequest: fetched.value, error: null
+  });
+}
+
 function appendActivity(content: string, line: string): string {
   const body = extractSection(content, ['活动日志', 'Activity Log']);
   return `${body.replace(/\s+$/, '')}${body.trim() ? '\n' : ''}${line}`;
@@ -358,6 +607,146 @@ function bindPlatformPullRequest(taskRef: string, options: BindOptions): PullReq
   });
 }
 
+function externalEvidenceNote(
+  issueNumber: number,
+  source: 'unique' | 'explicit',
+  pullRequest: PullRequestSnapshot
+): string {
+  return [
+    `authorization=${source}`,
+    externalIdentityEvidenceNote(issueNumber, pullRequest)
+  ].join('; ');
+}
+
+function externalIdentityEvidenceNote(
+  issueNumber: number,
+  pullRequest: PullRequestSnapshot
+): string {
+  return [
+    `issue=#${issueNumber}`,
+    `pr=#${pullRequest.number}`,
+    `url=${pullRequest.url}`,
+    `base=${pullRequest.base.repository}:${pullRequest.base.ref}@${pullRequest.base.sha}`,
+    `head=${pullRequest.head.repository}:${pullRequest.head.ref}@${pullRequest.head.sha}`,
+    `mergedAt=${pullRequest.mergedAt}`,
+    `mergeCommitSha=${pullRequest.mergeCommitSha}`
+  ].join('; ');
+}
+
+function resolveExternalPullRequest(taskRef: string, options: ResolveExternalOptions): ExternalPullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return externalResult(base.output);
+  const inventory = inspectCompletionArtifacts(base.resolved.taskId, { repoRoot: base.resolved.repoRoot });
+  if (inventory.status === 'failed') return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform,
+    capabilities: base.context.capabilities,
+    error: { code: inventory.error?.code || 'ARTIFACT_TOPOLOGY_CONFLICT', message: inventory.error?.message || 'Completion artifact inventory failed', retryable: false }
+  }));
+  if (inventory.artifacts.length > 0) {
+    if (options.pr !== undefined) return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+      platform: base.context.platform,
+      capabilities: base.context.capabilities,
+      error: { code: 'EXTERNAL_DELIVERY_NOT_APPLICABLE', message: 'External PR selection is only valid when the completion inventory is empty', retryable: false }
+    }), { mode: 'normal' });
+    return externalResult(result('no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+      platform: base.context.platform,
+      capabilities: base.context.capabilities,
+      operations: [{ name: 'external-pr:inventory', status: 'no-op', reasonCode: 'CANONICAL_ARTIFACTS_PRESENT' }],
+      error: null
+    }), { mode: 'normal' });
+  }
+  if (!base.issueNumber) 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 }
+  }));
+  const inspected = inspectPlatformIssueClosingChangeRequests(base.context.platform.type, {
+    cwd: base.resolved.repoRoot,
+    repository: base.context.platform.repository!,
+    issueNumber: base.issueNumber,
+    client: base.client
+  });
+  if (!inspected.ok || !inspected.value) {
+    const error = inspected.error || { code: 'PR_IDENTITY_INVALID', message: 'Closing PR inspection returned no candidates', retryable: false };
+    return externalResult(result(error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+      platform: base.context.platform, capabilities: base.context.capabilities, error
+    }));
+  }
+  const selected = selectExternalPullRequest(
+    inspected.value,
+    base.context.platform.repository!,
+    base.prNumber,
+    options.pr ?? null
+  );
+  if (selected.status === 'normal') return externalResult(result('no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform,
+    capabilities: base.context.capabilities,
+    operations: [{ name: 'external-pr:select', status: 'no-op', reasonCode: 'NO_ELIGIBLE_CANDIDATE' }],
+    error: null
+  }), { mode: 'normal', candidates: selected.candidates, eligible: selected.eligible });
+  if (selected.status === 'failed') return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform,
+    capabilities: base.context.capabilities,
+    error: { code: selected.code, message: selected.message, retryable: false }
+  }), { candidates: selected.candidates, eligible: selected.eligible });
+
+  const note = externalEvidenceNote(base.issueNumber, selected.source, selected.selected);
+  const identityNote = externalIdentityEvidenceNote(base.issueNumber, selected.selected);
+  const activityEntry = `**Bind External PR** by ${options.agent} — ${note}`;
+  const auditLines = base.content.split(/\r?\n/).filter((line) => line.includes('**Bind External PR**'));
+  const alreadyAudited = auditLines.some((line) => line.endsWith(identityNote));
+  if (auditLines.length > 0 && !alreadyAudited) return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform,
+    capabilities: base.context.capabilities,
+    pullRequest: selected.selected,
+    error: { code: 'PR_BIND_CONFLICT', message: 'Existing external PR audit evidence conflicts with the selected identity', retryable: false }
+  }), { candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+  if (alreadyAudited && base.prNumber !== selected.selected.number) return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform,
+    capabilities: base.context.capabilities,
+    pullRequest: selected.selected,
+    error: { code: 'PR_BIND_CONFLICT', message: 'External PR audit evidence does not match the task binding', retryable: false }
+  }), { candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+  if (base.prNumber === selected.selected.number && alreadyAudited) {
+    return externalResult(result('no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+      platform: base.context.platform,
+      capabilities: base.context.capabilities,
+      resource: { kind: 'pull-request', number: selected.selected.number },
+      pullRequest: selected.selected,
+      operations: [{ name: 'task:bind-external-pr', status: 'no-op', reasonCode: 'EVIDENCE_ALREADY_RECORDED' }],
+      error: null
+    }), { mode: 'external', authorization: selected.source, candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+  }
+  const metadata = captureTaskWriteMetadata();
+  const write = writeTask({
+    taskRef: base.resolved.taskId,
+    expectedState: 'active',
+    dryRun: options.dryRun,
+    mutations: [
+      { kind: 'frontmatter', set: { pr_number: selected.selected.number, pr_status: 'created', assigned_to: options.agent } },
+      { kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: '活动日志', body: appendActivity(
+        base.content, `- ${metadata.timestamp} — ${activityEntry}`
+      ) }
+    ]
+  }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
+  if (write.status === 'failed') return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform,
+    capabilities: base.context.capabilities,
+    pullRequest: selected.selected,
+    error: { code: write.error.code, message: write.error.message, retryable: false }
+  }), { candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+  const operationStatus = options.dryRun ? 'planned' : write.status === 'applied' ? 'applied' : 'no-op';
+  return externalResult(result(operationStatus, base.resolved.taskId, base.issueNumber, options.dryRun ? base.prNumber : selected.selected.number, {
+    changed: !options.dryRun && write.changed,
+    platform: base.context.platform,
+    capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: selected.selected.number },
+    pullRequest: selected.selected,
+    operations: [{ name: 'task:bind-external-pr', status: operationStatus, reasonCode: null }],
+    error: null
+  }), { mode: 'external', authorization: selected.source, candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+}
+
 function createPlatformPullRequest(taskRef: string, options: CreateOptions): PullRequestResult {
   const base = resolvedContext(taskRef, options);
   if (!base.ok) return base.output;
@@ -486,10 +875,14 @@ export {
   bindPlatformPullRequest,
   createPlatformPullRequest,
   inspectGitHubPullRequest,
+  inspectGitHubIssueClosingChangeRequests,
   inspectPlatformPullRequest,
+  inspectPlatformPullRequestByNumber,
   normalizePullRequest,
   resolveGitHubChangeRequestGitEvidence,
+  resolveExternalPullRequest,
+  selectExternalPullRequest,
   selectPullRequest,
   syncPlatformPullRequest
 };
-export type { BindOptions, CreateOptions, PullRequestResult, PullRequestSnapshot, SyncOptions };
+export type { BindOptions, CreateOptions, ExternalPullRequestResult, ExternalPullRequestSelection, PullRequestResult, PullRequestSnapshot, ResolveExternalOptions, SyncOptions };

package/lib/platform/release-notes.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 
 import { resolvePlatformContext } from './context.ts';
 import {
@@ -24,6 +25,86 @@ const unsupportedError = {
   retryable: false
 };
 
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+function releaseNoteFailure(code: string, message: string) {
+  return {
+    status: 'failed' as const,
+    changed: false,
+    operation: null,
+    url: null,
+    error: { code, message, retryable: false }
+  };
+}
+
+function normalizeReleaseNoteBytes(input: Uint8Array): Buffer {
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(input);
+  const normalized = text.replace(/\r\n?/g, '\n').replace(/\n*$/, '') + '\n';
+  return Buffer.from(normalized, 'utf8');
+}
+
+function releaseNoteSha256(bytes: Uint8Array): string {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function isWithin(parent: string, candidate: string): boolean {
+  const relative = path.relative(parent, candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function stageReleaseNotes(
+  input: { notesFile: string },
+  options: Pick<ReleaseNoteOptions, 'cwd'> = {}
+) {
+  if (!input.notesFile || input.notesFile === '-') {
+    return { status: 'failed' as const, changed: false, notesFile: null, sha256: null, byteLength: null, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'notes-file must identify an existing external file', retryable: false } };
+  }
+  const requestedPath = path.resolve(input.notesFile);
+  let notesFile: string;
+  let sourceStat: fs.Stats;
+  try {
+    if (fs.lstatSync(requestedPath).isSymbolicLink()) throw new Error('symbolic links are not allowed');
+    notesFile = fs.realpathSync(requestedPath);
+    sourceStat = fs.statSync(notesFile);
+    const worktree = fs.realpathSync(path.resolve(options.cwd || process.cwd()));
+    if (!sourceStat.isFile() || isWithin(worktree, notesFile)) throw new Error('path is not an external regular file');
+  } catch {
+    return { status: 'failed' as const, changed: false, notesFile: null, sha256: null, byteLength: null, error: { code: 'RELEASE_NOTES_PATH_INVALID', message: 'notes-file must be a regular file outside the current worktree and must not be a symbolic link', retryable: false } };
+  }
+
+  let original: Buffer;
+  let normalized: Buffer;
+  try {
+    original = fs.readFileSync(notesFile);
+    normalized = normalizeReleaseNoteBytes(original);
+  } catch {
+    return { status: 'failed' as const, changed: false, notesFile, sha256: null, byteLength: null, error: { code: 'RELEASE_NOTES_CONTENT_INVALID', message: 'notes-file must contain valid UTF-8', retryable: false } };
+  }
+
+  const changed = !original.equals(normalized);
+  if (changed) {
+    const temporary = path.join(
+      path.dirname(notesFile),
+      `.${path.basename(notesFile)}.${process.pid}.${Date.now()}.tmp`
+    );
+    try {
+      fs.writeFileSync(temporary, normalized, { flag: 'wx', mode: sourceStat.mode });
+      fs.renameSync(temporary, notesFile);
+    } catch {
+      fs.rmSync(temporary, { force: true });
+      return { status: 'failed' as const, changed: false, notesFile, sha256: null, byteLength: null, error: { code: 'RELEASE_NOTES_STAGE_FAILED', message: 'notes-file could not be staged atomically', retryable: false } };
+    }
+  }
+  return {
+    status: changed ? 'applied' as const : 'no-op' as const,
+    changed,
+    notesFile,
+    sha256: releaseNoteSha256(normalized),
+    byteLength: normalized.byteLength,
+    error: null
+  };
+}
+
 function baseResult(status: 'no-op' | 'failed' | 'blocked') {
   return {
     status,
@@ -148,11 +229,20 @@ function releaseNoteContext(
 }
 
 function publishReleaseNotes(
-  input: { tag: string; title: string; notesFile: string; dryRun?: boolean },
+  input: { tag: string; title: string; notesFile: string; expectedSha256: string; dryRun?: boolean },
   options: ReleaseNoteOptions = {}
 ) {
-  if (!input.tag || !input.title || !input.notesFile) {
-    return { status: 'failed' as const, changed: false, operation: null, url: null, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'tag, title, and notes-file are required', retryable: false } };
+  if (!input.tag || !input.title || !input.notesFile || !SHA256_PATTERN.test(input.expectedSha256)) {
+    return releaseNoteFailure('RELEASE_NOTES_INPUT_INVALID', 'tag, title, notes-file, and expected-sha256 are required');
+  }
+  let actualSha256: string;
+  try {
+    actualSha256 = releaseNoteSha256(fs.readFileSync(input.notesFile));
+  } catch {
+    return releaseNoteFailure('RELEASE_NOTES_FILE_UNREADABLE', 'notes-file could not be read');
+  }
+  if (actualSha256 !== input.expectedSha256) {
+    return releaseNoteFailure('RELEASE_NOTES_DIGEST_MISMATCH', 'notes-file does not match the confirmed SHA-256 digest');
   }
   const cwd = path.resolve(options.cwd || process.cwd());
   const platformType = options.platformType ?? configuredPlatform(cwd);
@@ -164,4 +254,10 @@ function publishReleaseNotes(
   return publishGitHubReleaseNotes({ ...input, repository: context.platform.repository }, { cwd, client: options.client });
 }
 
-export { publishReleaseNotes, releaseNoteContext };
+export {
+  normalizeReleaseNoteBytes,
+  publishReleaseNotes,
+  releaseNoteContext,
+  releaseNoteSha256,
+  stageReleaseNotes
+};