@fitlab-ai/agent-infra 0.8.5 → 0.9.1

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

@@ -0,0 +1,70 @@
+import { execFileSync } from "node:child_process";
+
+import type { PullRequestSnapshot } from "./pull-requests.ts";
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/i;
+
+type ReviewedHeadRelation =
+  | { status: "strict"; reviewedHead: string }
+  | { status: "merged-equivalent"; reviewedHead: string; mergeCommit: string }
+  | { status: "failed" | "blocked"; code: string; message: string };
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+}
+
+function commitExists(gitRoot: string, sha: string): boolean {
+  try {
+    git(gitRoot, ["cat-file", "-e", `${sha}^{commit}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveReviewedHeadRelation(input: {
+  gitRoot: string;
+  localHead: string;
+  lastReviewedCommit: string;
+  pullRequest: PullRequestSnapshot;
+  pathspecs: string[];
+}): ReviewedHeadRelation {
+  const { gitRoot, localHead, lastReviewedCommit, pullRequest, pathspecs } = input;
+  if (localHead === lastReviewedCommit && lastReviewedCommit === pullRequest.head.sha) {
+    return { status: "strict", reviewedHead: lastReviewedCommit };
+  }
+  if (pullRequest.state !== "closed" || !pullRequest.mergedAt || !pullRequest.mergeCommitSha ||
+      lastReviewedCommit !== pullRequest.head.sha) {
+    return { status: "failed", code: "PR_MERGE_IDENTITY_INVALID", message: "PR merge identity does not match the reviewed head" };
+  }
+  const shas = [pullRequest.base.sha, pullRequest.head.sha, pullRequest.mergeCommitSha, localHead];
+  if (shas.some((sha) => !SHA_PATTERN.test(sha) || !commitExists(gitRoot, sha))) {
+    return { status: "blocked", code: "PR_MERGE_OBJECT_MISSING", message: "Required PR merge Git objects are unavailable" };
+  }
+  try {
+    git(gitRoot, ["merge-base", "--is-ancestor", pullRequest.mergeCommitSha, localHead]);
+    const parents = git(gitRoot, ["rev-list", "--parents", "-n", "1", pullRequest.mergeCommitSha]).trim().split(/\s+/);
+    if (parents.length !== 2) {
+      return { status: "failed", code: "PR_MERGE_TOPOLOGY_INVALID", message: "PR merge commit is not a single-parent squash commit" };
+    }
+    const diffArgs = ["diff", "--no-renames", "--binary", "--full-index"];
+    const reviewedDiff = git(gitRoot, [...diffArgs, pullRequest.base.sha, pullRequest.head.sha]);
+    const mergedDiff = git(gitRoot, [...diffArgs, `${pullRequest.mergeCommitSha}^`, pullRequest.mergeCommitSha]);
+    if (reviewedDiff !== mergedDiff) {
+      return { status: "failed", code: "PR_MERGE_CONTENT_MISMATCH", message: "Squash merge content differs from the reviewed PR changes" };
+    }
+    const postMerge = git(gitRoot, ["rev-list", `${pullRequest.mergeCommitSha}..${localHead}`, "--", ...pathspecs]).trim();
+    if (postMerge) {
+      return { status: "failed", code: "POST_MERGE_CHANGES", message: "Protected paths changed after the squash merge" };
+    }
+  } catch {
+    return { status: "blocked", code: "PR_MERGE_GIT_EVIDENCE_UNAVAILABLE", message: "Unable to verify PR merge topology or content" };
+  }
+  return {
+    status: "merged-equivalent",
+    reviewedHead: lastReviewedCommit,
+    mergeCommit: pullRequest.mergeCommitSha
+  };
+}
+
+export type { ReviewedHeadRelation };

package/lib/platform/metadata-labels.ts

@@ -0,0 +1,33 @@
+const TYPE_LABELS: Record<string, string> = {
+  bug: 'type: bug',
+  bugfix: 'type: bug',
+  feature: 'type: feature',
+  enhancement: 'type: enhancement',
+  refactor: 'type: enhancement',
+  refactoring: 'type: enhancement',
+  documentation: 'type: documentation',
+  docs: 'type: documentation',
+  'dependency-upgrade': 'type: dependency-upgrade',
+  task: 'type: task',
+  chore: 'type: task'
+};
+
+function taskTypeLabel(taskType: string): string | null {
+  return TYPE_LABELS[taskType] || null;
+}
+
+function computeInLabels(
+  changedFiles: string[],
+  mapping: Record<string, unknown>,
+  repositoryLabels: Set<string>
+): string[] {
+  return Object.entries(mapping).flatMap(([name, rawPrefixes]) => {
+    if (!Array.isArray(rawPrefixes)) return [];
+    const matches = rawPrefixes.some((prefix) => typeof prefix === 'string' && prefix.length > 0
+      && changedFiles.some((file) => file === prefix.replace(/\/$/, '') || file.startsWith(prefix)));
+    const label = `in: ${name}`;
+    return matches && repositoryLabels.has(label) ? [label] : [];
+  }).sort();
+}
+
+export { computeInLabels, taskTypeLabel };

package/lib/platform/pr-checks.ts

@@ -0,0 +1,247 @@
+import fs from 'node:fs';
+
+import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { resolvePlatformContext } from './context.ts';
+import { createGitHubClient } from './github-client.ts';
+import type { GitHubClient } from './github-client.ts';
+import { inspectPlatformPullRequest } from './pull-requests.ts';
+import { platformResult } from './types.ts';
+import type { PlatformResult } from './types.ts';
+import type { PullRequestSnapshot } from './pull-requests.ts';
+
+type CheckBucket = 'pass' | 'fail' | 'pending' | 'cancel';
+type CheckState = 'passed' | 'failed' | 'pending' | 'timed-out' | 'cancelled' | 'no-required';
+type CheckSnapshot = {
+  name: string;
+  bucket: CheckBucket;
+  workflow?: string | null;
+  conclusion?: string | null;
+  detailsUrl?: string | null;
+  startedAt?: string | null;
+  completedAt?: string | null;
+};
+type ChecksSnapshot = { state: Exclude<CheckState, 'timed-out'>; required: CheckSnapshot[] };
+type RunCandidate = { id: number; name: string; headSha: string; jobId?: number | null };
+type ChecksResult = PlatformResult & {
+  pullRequest: PullRequestSnapshot | null;
+  checks: { state: CheckState; required: CheckSnapshot[] };
+  resolution?: { status: 'resolved' | 'missing' | 'ambiguous'; runId: number | null; jobId: number | null };
+  logs?: { runId: number; jobId?: number; text: string };
+};
+type SharedOptions = { cwd?: string; client?: GitHubClient };
+
+function classifyRequiredChecks(required: CheckSnapshot[]): ChecksSnapshot {
+  if (required.length === 0) return { state: 'no-required', required };
+  if (required.some((check) => check.bucket === 'fail')) return { state: 'failed', required };
+  if (required.some((check) => check.bucket === 'cancel')) return { state: 'cancelled', required };
+  if (required.some((check) => check.bucket === 'pending')) return { state: 'pending', required };
+  return { state: 'passed', required };
+}
+
+async function watchRequiredChecks(options: {
+  inspect: () => Promise<ChecksSnapshot>;
+  intervalMs: number;
+  deadlineMs: number;
+  now?: () => number;
+  sleep?: (delayMs: number) => Promise<void>;
+  signal?: AbortSignal;
+}): Promise<{ state: CheckState; required: CheckSnapshot[] }> {
+  const now = options.now || (() => performance.now());
+  const sleep = options.sleep || ((delay) => new Promise<void>((resolve) => setTimeout(resolve, delay)));
+  const started = now();
+  while (true) {
+    if (options.signal?.aborted) return { state: 'cancelled', required: [] };
+    const snapshot = await options.inspect();
+    if (snapshot.state !== 'pending') return snapshot;
+    const elapsed = now() - started;
+    if (elapsed >= options.deadlineMs) return { state: 'timed-out', required: snapshot.required };
+    await sleep(Math.min(options.intervalMs, options.deadlineMs - elapsed));
+  }
+}
+
+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 } {
+  const matches = candidates.filter((candidate) => candidate.headSha === headSha && candidate.name === checkName);
+  if (matches.length === 1) return { status: 'resolved', runId: matches[0]!.id, jobId: matches[0]!.jobId || null };
+  return { status: matches.length === 0 ? 'missing' : 'ambiguous', runId: null, jobId: null };
+}
+
+function checksResult(status: PlatformResult['status'], overrides: Partial<ChecksResult> = {}): ChecksResult {
+  return {
+    ...platformResult(status),
+    pullRequest: null,
+    checks: { state: 'pending', required: [] },
+    ...overrides
+  };
+}
+
+function normalizeBucket(value: { bucket?: string; state?: string; conclusion?: string }): CheckBucket {
+  const raw = String(value.bucket || 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 resolvedTask(taskRef: string, options: SharedOptions) {
+  const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+  if (!resolved.ok) return { ok: false as const, output: checksResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }) };
+  const frontmatter = parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+  const pr = Number(frontmatter.pr_number);
+  const prNumber = Number.isInteger(pr) && pr > 0 ? pr : null;
+  if (!prNumber) return { ok: false as const, output: checksResult('failed', { error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false } }) };
+  const client = options.client || createGitHubClient();
+  const context = resolvePlatformContext({ cwd: resolved.repoRoot, client });
+  if (!context.platform.repository || !['no-op', 'degraded'].includes(context.status)) return { ok: false as const, output: checksResult(context.status, { platform: context.platform, capabilities: context.capabilities, error: context.error }) };
+  const inspected = inspectPlatformPullRequest(taskRef, { cwd: resolved.repoRoot, client });
+  if (!inspected.pullRequest) return { ok: false as const, output: checksResult(inspected.status, { platform: context.platform, capabilities: context.capabilities, error: inspected.error }) };
+  return { ok: true as const, resolved, prNumber, client, context, pullRequest: inspected.pullRequest };
+}
+
+function inspectRequiredChecks(taskRef: string, options: SharedOptions = {}): ChecksResult {
+  const base = resolvedTask(taskRef, options);
+  if (!base.ok) return base.output;
+  const repository = base.context.platform.repository!;
+  const inspected = base.client.json<unknown>([
+    'pr', 'checks', String(base.prNumber), '--repo', repository, '--required',
+    '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'
+  ], { cwd: base.resolved.repoRoot });
+  if (!inspected.ok) {
+    return checksResult(inspected.error.retryable ? 'blocked' : 'failed', {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      resource: { kind: 'pull-request', number: base.prNumber },
+      pullRequest: base.pullRequest, error: inspected.error
+    });
+  }
+  const classified = classifyRequiredChecks(normalizeChecks(inspected.value));
+  const status = classified.state === 'passed' || classified.state === 'no-required'
+    ? 'no-op'
+    : classified.state === 'failed' || classified.state === 'cancelled' ? 'failed' : 'blocked';
+  return checksResult(status, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: base.prNumber },
+    pullRequest: base.pullRequest, checks: classified,
+    error: status === 'no-op' ? null : {
+      code: classified.state === 'pending' ? 'REQUIRED_CHECKS_PENDING' : `REQUIRED_CHECKS_${classified.state.toUpperCase()}`,
+      message: `Required checks are ${classified.state}`,
+      retryable: classified.state === 'pending'
+    }
+  });
+}
+
+async function watchPlatformChecks(taskRef: string, options: SharedOptions & {
+  intervalSeconds: number;
+  deadlineSeconds: number;
+  signal?: AbortSignal;
+  now?: () => number;
+  sleep?: (delayMs: number) => Promise<void>;
+}): Promise<ChecksResult> {
+  let last: ChecksResult | null = null;
+  const watched = await watchRequiredChecks({
+    intervalMs: options.intervalSeconds * 1000,
+    deadlineMs: options.deadlineSeconds * 1000,
+    signal: options.signal,
+    now: options.now,
+    sleep: options.sleep,
+    inspect: async () => {
+      last = inspectRequiredChecks(taskRef, options);
+      if (last.checks.state === 'pending' && last.error?.code === 'REQUIRED_CHECKS_PENDING') return last.checks as ChecksSnapshot;
+      return last.checks as ChecksSnapshot;
+    }
+  });
+  if (!last) return checksResult('blocked', { checks: watched, error: { code: 'REQUIRED_CHECKS_UNAVAILABLE', message: 'No checks snapshot was produced', retryable: true } });
+  const snapshot = last as ChecksResult;
+  if (watched.state === 'timed-out' || watched.state === 'cancelled') return checksResult('blocked', {
+    ...snapshot,
+    status: 'blocked',
+    changed: false,
+    checks: watched,
+    error: { code: watched.state === 'timed-out' ? 'REQUIRED_CHECKS_TIMEOUT' : 'REQUIRED_CHECKS_CANCELLED', message: `Required checks ${watched.state}`, retryable: watched.state === 'timed-out' }
+  });
+  return { ...snapshot, checks: watched };
+}
+
+function resolvePlatformCheckRun(taskRef: string, options: SharedOptions & { checkName: string; detailsUrl?: string }): ChecksResult {
+  const base = resolvedTask(taskRef, options);
+  if (!base.ok) return base.output;
+  const direct = options.detailsUrl ? parseRunJobIdentity(options.detailsUrl) : null;
+  if (direct) {
+    const run = base.client.json<{ id?: number; head_sha?: string }>(['api', `repos/${base.context.platform.repository}/actions/runs/${direct.runId}`], { cwd: base.resolved.repoRoot });
+    if (!run.ok) return checksResult(run.error.retryable ? 'blocked' : 'failed', { platform: base.context.platform, capabilities: base.context.capabilities, pullRequest: base.pullRequest, error: run.error });
+    if (run.value.head_sha !== base.pullRequest.head.sha) return checksResult('failed', { error: { code: 'CHECK_RUN_HEAD_MISMATCH', message: 'Resolved run does not belong to the PR head SHA', retryable: false } });
+    return checksResult('no-op', { platform: base.context.platform, capabilities: base.context.capabilities, resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest, resolution: { status: 'resolved', ...direct }, error: null });
+  }
+  const listed = base.client.json<{ check_runs?: Array<{ name?: string; details_url?: string }> }>(['api', `repos/${base.context.platform.repository}/commits/${base.pullRequest.head.sha}/check-runs`], { cwd: base.resolved.repoRoot });
+  if (!listed.ok) return checksResult(listed.error.retryable ? 'blocked' : 'failed', { error: listed.error });
+  const candidates = (listed.value.check_runs || []).flatMap((check) => {
+    if (check.name !== options.checkName || !check.details_url) return [];
+    const identity = parseRunJobIdentity(check.details_url);
+    return identity ? [{ id: identity.runId, jobId: identity.jobId, name: check.name, headSha: base.pullRequest.head.sha }] : [];
+  });
+  const resolution = resolveRunCandidate(candidates, base.pullRequest.head.sha, options.checkName);
+  return checksResult(resolution.status === 'resolved' ? 'no-op' : 'failed', {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
+    resolution,
+    error: resolution.status === 'resolved' ? null : { code: resolution.status === 'ambiguous' ? 'CHECK_RUN_AMBIGUOUS' : 'CHECK_RUN_NOT_FOUND', message: `Check run is ${resolution.status}`, retryable: false }
+  });
+}
+
+function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions & { run: number; job?: number }): ChecksResult {
+  const base = resolvedTask(taskRef, options);
+  if (!base.ok) return base.output;
+  const args = options.job
+    ? ['api', `repos/${base.context.platform.repository}/actions/jobs/${options.job}/logs`]
+    : ['run', 'view', String(options.run), '--repo', base.context.platform.repository!, '--log-failed'];
+  const fetched = base.client.text(args, { cwd: base.resolved.repoRoot });
+  if (!fetched.ok) return checksResult(fetched.error.retryable ? 'blocked' : 'failed', { platform: base.context.platform, capabilities: base.context.capabilities, error: fetched.error });
+  if (!fetched.value) return checksResult('failed', { error: { code: 'CHECK_LOGS_MISSING', message: 'No failed logs are available', retryable: false } });
+  return checksResult('no-op', {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
+    logs: { runId: options.run, ...(options.job ? { jobId: options.job } : {}), text: fetched.value }, error: null
+  });
+}
+
+export {
+  classifyRequiredChecks,
+  fetchPlatformCheckLogs,
+  inspectRequiredChecks,
+  parseRunJobIdentity,
+  resolvePlatformCheckRun,
+  resolveRunCandidate,
+  watchPlatformChecks,
+  watchRequiredChecks
+};
+export type { CheckBucket, CheckSnapshot, ChecksResult, ChecksSnapshot, CheckState, RunCandidate };

package/lib/platform/pr-summary.ts

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+import { enumerateArtifacts } from '../task/artifacts.ts';
+import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { resolvePlatformContext } from './context.ts';
+import { createGitHubClient } from './github-client.ts';
+import type { GitHubClient } from './github-client.ts';
+import { listRemoteComments, normalizeCommentContent, writeComment } from './issue-comments.ts';
+import { platformResult } from './types.ts';
+import type { PlatformResult } from './types.ts';
+
+type SummaryComment = { id: number; body: string };
+type SummaryContextResult = PlatformResult & {
+  task: { id: string | null; prNumber: number | null };
+  artifacts: Array<{ family: string; name: string; path: string }>;
+};
+
+function summaryMarker(taskId: string): string {
+  return `<!-- sync-pr:${taskId}:summary -->`;
+}
+
+function buildPullRequestSummary(taskId: string, body: string, headSha: string): string {
+  return normalizeCommentContent(`${summaryMarker(taskId)}\n<!-- last-commit: ${headSha} -->\n\n${body.replace(/\s+$/, '')}\n`);
+}
+
+function reconcileSummaryComment(comments: SummaryComment[], taskId: string, desired: string):
+  { action: 'create' | 'update' | 'no-op' | 'conflict'; commentId: number | null } {
+  const marker = summaryMarker(taskId);
+  const matches = comments.filter((comment) => comment.body.includes(marker));
+  if (matches.length > 1) return { action: 'conflict', commentId: null };
+  if (matches.length === 0) return { action: 'create', commentId: null };
+  return normalizeCommentContent(matches[0]!.body) === normalizeCommentContent(desired)
+    ? { action: 'no-op', commentId: matches[0]!.id }
+    : { action: 'update', commentId: matches[0]!.id };
+}
+
+function canonicalArtifacts(taskDir: string) {
+  const allowed = /^(plan|review-plan|code|review-code|manual-validation)(?:-r\d+)?\.md$/;
+  const byFamily = new Map<string, { family: string; name: string; path: string; round: number }>();
+  for (const artifact of enumerateArtifacts(taskDir)) {
+    if (!allowed.test(artifact.name)) continue;
+    const match = artifact.name.match(/^(plan|review-plan|code|review-code|manual-validation)(?:-r(\d+))?\.md$/)!;
+    const family = match[1]!;
+    const round = match[2] ? Number(match[2]) : 1;
+    const current = byFamily.get(family);
+    if (!current || round > current.round) byFamily.set(family, { family, name: artifact.name, path: artifact.path, round });
+  }
+  return [...byFamily.values()].map(({ family, name, path }) => ({ family, name, path }));
+}
+
+function summaryContext(taskRef: string, options: { cwd?: string; client?: GitHubClient } = {}): SummaryContextResult {
+  const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+  if (!resolved.ok) return { ...platformResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }), task: { id: resolved.taskId, prNumber: null }, artifacts: [] };
+  const frontmatter = parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+  const value = Number(frontmatter.pr_number);
+  const prNumber = Number.isInteger(value) && value > 0 ? value : null;
+  return { ...platformResult('no-op'), task: { id: resolved.taskId, prNumber }, artifacts: canonicalArtifacts(resolved.taskDir) };
+}
+
+function syncPullRequestSummary(taskRef: string, options: { agent: string; body: string; cwd?: string; client?: GitHubClient; dryRun?: boolean }): PlatformResult {
+  const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+  if (!resolved.ok) return platformResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } });
+  const frontmatter = parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+  const prNumber = Number(frontmatter.pr_number);
+  if (!Number.isInteger(prNumber) || prNumber <= 0) return platformResult('failed', { error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false } });
+  const client = options.client || createGitHubClient();
+  const context = resolvePlatformContext({ cwd: resolved.repoRoot, client });
+  if (!context.platform.repository || !['no-op', 'degraded'].includes(context.status)) return context;
+  let headSha: string;
+  try {
+    headSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: resolved.repoRoot, encoding: 'utf8' }).trim();
+  } catch (error) {
+    return platformResult('failed', { platform: context.platform, capabilities: context.capabilities, error: { code: 'GIT_HEAD_UNRESOLVED', message: error instanceof Error ? error.message : String(error), retryable: false } });
+  }
+  const desired = buildPullRequestSummary(resolved.taskId, options.body, headSha);
+  const listed = listRemoteComments(client, context.platform.repository, prNumber, resolved.repoRoot);
+  if (!listed.ok) return platformResult(listed.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: listed.error });
+  const reconciliation = reconcileSummaryComment(listed.value, resolved.taskId, desired);
+  if (reconciliation.action === 'conflict') return platformResult('failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: { code: 'PR_SUMMARY_MARKER_AMBIGUOUS', message: 'Multiple PR comments contain the summary marker', retryable: false } });
+  if (reconciliation.action === 'no-op') return platformResult('no-op', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: [reconciliation.commentId!], parts: 1 }, error: null });
+  if (options.dryRun) return platformResult('planned', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, operations: [{ name: `summary:${reconciliation.action}`, status: 'planned', reasonCode: null }], error: null });
+  const written = writeComment(client, context.platform.repository, prNumber, resolved.repoRoot, desired, reconciliation.commentId || undefined);
+  if (!written.ok) return platformResult(written.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: written.error });
+  const id = Number(written.value.id || reconciliation.commentId);
+  return platformResult('applied', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: Number.isInteger(id) ? [id] : [], parts: 1 }, operations: [{ name: `summary:${reconciliation.action}`, status: 'applied', reasonCode: null }], error: null });
+}
+
+export { buildPullRequestSummary, reconcileSummaryComment, summaryContext, summaryMarker, syncPullRequestSummary };

package/lib/platform/pull-request-metadata.ts

@@ -0,0 +1,69 @@
+import { taskTypeLabel } from './metadata-labels.ts';
+import type { PlatformCapabilities } from './types.ts';
+
+type PullRequestMetadataSnapshot = {
+  labels: string[];
+  assignees: string[];
+  milestone: string | null;
+  body: string;
+};
+
+type IssueMetadataSource = {
+  labels: string[];
+  assignees: string[];
+  milestone: string | null;
+};
+
+type PullRequestMetadataOperation = {
+  name: 'labels' | 'assignees' | 'milestone' | 'closing-issue';
+  status: 'planned' | 'no-op' | 'skipped';
+  reasonCode: string | null;
+  value?: unknown;
+};
+
+function equalStrings(left: string[], right: string[]): boolean {
+  return [...left].sort().join('\0') === [...right].sort().join('\0');
+}
+
+function ensureClosingReference(body: string, issueNumber: number): string {
+  const pattern = new RegExp(`(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\s+#${issueNumber}\\b`, 'i');
+  return pattern.test(body) ? body : `${body.replace(/\s+$/, '')}\n\nCloses #${issueNumber}`;
+}
+
+function planPullRequestMetadata(input: {
+  pullRequest: PullRequestMetadataSnapshot;
+  issue: IssueMetadataSource;
+  taskType: string;
+  issueNumber: number;
+  capabilities: PlatformCapabilities;
+}): { operations: PullRequestMetadataOperation[] } {
+  const typeLabel = taskTypeLabel(input.taskType);
+  const copiedLabels = input.issue.labels.filter((label) => label.startsWith('in:'));
+  const desiredLabels = [...new Set([
+    ...input.pullRequest.labels.filter((label) => !label.startsWith('type:') && !label.startsWith('in:')),
+    ...(typeLabel ? [typeLabel] : []),
+    ...copiedLabels
+  ])].sort();
+  const body = ensureClosingReference(input.pullRequest.body, input.issueNumber);
+  return { operations: [
+    input.capabilities.triage
+      ? equalStrings(input.pullRequest.labels, desiredLabels)
+        ? { name: 'labels', status: 'no-op', reasonCode: null }
+        : { name: 'labels', status: 'planned', reasonCode: null, value: desiredLabels }
+      : { name: 'labels', status: 'skipped', reasonCode: 'TRIAGE_REQUIRED' },
+    equalStrings(input.pullRequest.assignees, input.issue.assignees)
+      ? { name: 'assignees', status: 'no-op', reasonCode: null }
+      : { name: 'assignees', status: 'planned', reasonCode: null, value: [...input.issue.assignees].sort() },
+    input.capabilities.triage
+      ? input.pullRequest.milestone === input.issue.milestone
+        ? { name: 'milestone', status: 'no-op', reasonCode: null }
+        : { name: 'milestone', status: 'planned', reasonCode: null, value: input.issue.milestone }
+      : { name: 'milestone', status: 'skipped', reasonCode: 'TRIAGE_REQUIRED' },
+    body === input.pullRequest.body
+      ? { name: 'closing-issue', status: 'no-op', reasonCode: null }
+      : { name: 'closing-issue', status: 'planned', reasonCode: null, value: body }
+  ] };
+}
+
+export { ensureClosingReference, planPullRequestMetadata };
+export type { IssueMetadataSource, PullRequestMetadataOperation, PullRequestMetadataSnapshot };