@fitlab-ai/agent-infra 0.8.4 → 0.9.0

package/lib/platform/pull-requests.ts

@@ -0,0 +1,380 @@
+import fs from 'node:fs';
+
+import { parseTaskFrontmatter } 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 { resolvePlatformContext } from './context.ts';
+import { createGitHubClient } from './github-client.ts';
+import type { GitHubClient } from './github-client.ts';
+import { inspectPlatformIssue } from './issues.ts';
+import { planPullRequestMetadata } from './pull-request-metadata.ts';
+import { platformResult } from './types.ts';
+import type { PlatformOperation, PlatformResult } from './types.ts';
+
+type PullRequestSnapshot = {
+  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 };
+  labels: string[];
+  assignees: string[];
+  milestone: string | null;
+};
+
+type PullRequestResult = PlatformResult & {
+  task: { id: string | null; issueNumber: number | null; prNumber: number | null };
+  pullRequest: PullRequestSnapshot | null;
+};
+type SharedOptions = { cwd?: string; client?: GitHubClient };
+type CreateOptions = SharedOptions & {
+  agent: string;
+  base: string;
+  head: string;
+  title: string;
+  body: string;
+  draft?: boolean;
+  dryRun?: boolean;
+};
+type BindOptions = SharedOptions & { agent: string; pr: number; dryRun?: boolean };
+type SyncOptions = SharedOptions & { agent: string; metadata?: boolean; closingIssue?: boolean; dryRun?: boolean };
+
+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; repo?: { full_name?: string } | null };
+  labels?: Array<string | { name?: string }>;
+  assignees?: Array<{ login?: string }>;
+  milestone?: { title?: string } | null;
+};
+
+function result(
+  status: PlatformResult['status'],
+  taskId: string | null,
+  issueNumber: number | null,
+  prNumber: number | null,
+  overrides: Partial<PullRequestResult> = {}
+): PullRequestResult {
+  return {
+    ...platformResult(status),
+    task: { id: taskId, issueNumber, prNumber },
+    pullRequest: 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;
+  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 },
+    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
+  };
+}
+
+function expectedHead(repository: string, head: string): { repository: string; ref: string } {
+  const colon = head.indexOf(':');
+  if (colon === -1) return { repository, ref: head };
+  const repoName = repository.split('/')[1] || '';
+  return { repository: `${head.slice(0, colon)}/${repoName}`, ref: head.slice(colon + 1) };
+}
+
+function selectPullRequest(remotes: RemotePullRequest[], repository: string, head: string, base: string):
+  | { status: 'resolved'; pullRequest: PullRequestSnapshot }
+  | { status: 'missing' | 'ambiguous'; pullRequest: null } {
+  const wanted = expectedHead(repository, head);
+  const matches = remotes.flatMap((remote) => {
+    const normalized = normalizePullRequest(remote, repository);
+    return normalized && normalized.state === 'open' && normalized.head.repository === wanted.repository &&
+      normalized.head.ref === wanted.ref && normalized.base.repository === repository && normalized.base.ref === base
+      ? [normalized] : [];
+  });
+  if (matches.length === 1) return { status: 'resolved', pullRequest: matches[0]! };
+  return { status: matches.length === 0 ? 'missing' : 'ambiguous', pullRequest: null };
+}
+
+function resolvedContext(taskRef: string, options: SharedOptions) {
+  const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+  if (!resolved.ok) return { ok: false as const, output: result('failed', resolved.taskId, null, null, {
+    error: { code: resolved.code, message: resolved.message, retryable: false }
+  }) };
+  const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  const frontmatter = parseTaskFrontmatter(content);
+  const issue = Number(frontmatter.issue_number);
+  const pr = Number(frontmatter.pr_number);
+  const issueNumber = Number.isInteger(issue) && issue > 0 ? issue : null;
+  const prNumber = Number.isInteger(pr) && pr > 0 ? pr : null;
+  const client = options.client || createGitHubClient();
+  const context = resolvePlatformContext({ cwd: resolved.repoRoot, client });
+  const usable = (context.status === 'no-op' || context.status === 'degraded') && context.platform.repository;
+  if (!usable) return { ok: false as const, output: result(context.status, resolved.taskId, issueNumber, prNumber, {
+    platform: context.platform, capabilities: context.capabilities, operations: context.operations, error: context.error
+  }) };
+  return { ok: true as const, resolved, content, frontmatter, issueNumber, prNumber, client, context };
+}
+
+function inspectGitHubPullRequest(client: GitHubClient, repository: string, number: number, cwd: string) {
+  const fetched = client.json<RemotePullRequest>(['api', `repos/${repository}/pulls/${number}`], { cwd });
+  if (!fetched.ok) return fetched;
+  const pullRequest = normalizePullRequest(fetched.value, repository);
+  return pullRequest
+    ? { ok: true as const, value: pullRequest }
+    : { ok: false as const, error: { code: 'PR_IDENTITY_INVALID', message: 'Remote resource is not a valid pull request', retryable: false } };
+}
+
+function locatePullRequest(base: ReturnType<typeof resolvedContext> & { ok: true }, head: string, target: string) {
+  const repository = base.context.platform.repository!;
+  const listed = base.client.json<RemotePullRequest[]>([
+    'api', `repos/${repository}/pulls?state=open&base=${encodeURIComponent(target)}&per_page=100`
+  ], { cwd: base.resolved.repoRoot });
+  if (!listed.ok) return listed;
+  const selected = selectPullRequest(listed.value, repository, head, target);
+  return selected.status === 'resolved'
+    ? { ok: true as const, value: selected.pullRequest }
+    : { ok: false as const, error: {
+      code: selected.status === 'ambiguous' ? 'PR_IDENTITY_AMBIGUOUS' : 'PR_NOT_FOUND',
+      message: selected.status === 'ambiguous' ? 'Multiple pull requests match the exact head/base identity' : 'No pull request matches the exact head/base identity',
+      retryable: false
+    } };
+}
+
+function inspectPlatformPullRequest(taskRef: string, options: SharedOptions = {}): PullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return base.output;
+  if (!base.prNumber) return result('no-op', base.resolved.taskId, base.issueNumber, null, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false }
+  });
+  const fetched = inspectGitHubPullRequest(base.client, base.context.platform.repository!, base.prNumber, base.resolved.repoRoot);
+  if (!fetched.ok) return result(fetched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: base.prNumber }, error: fetched.error
+  });
+  return result('no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: base.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}`;
+}
+
+function writeCreateStarted(base: ReturnType<typeof resolvedContext> & { ok: true }, agent: string) {
+  const starts = (base.content.match(/\*\*Create PR \[started\]\*\*/g) || []).length;
+  const dones = (base.content.match(/\*\*Create PR\*\*/g) || []).length;
+  if (starts > dones) return { status: 'no-op' as const };
+  const metadata = captureTaskWriteMetadata();
+  return writeTask({
+    taskRef: base.resolved.taskId,
+    expectedState: 'active',
+    mutations: [{ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: '活动日志', body: appendActivity(
+      base.content, `- ${metadata.timestamp} — **Create PR [started]** by ${agent} — started`
+    ) }]
+  }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
+}
+
+function bindIdentity(base: ReturnType<typeof resolvedContext> & { ok: true }, pullRequest: PullRequestSnapshot, agent: string, dryRun = false) {
+  if (base.prNumber && base.prNumber !== pullRequest.number) return { status: 'failed' as const, error: {
+    code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${base.prNumber}`
+  } };
+  if (base.prNumber === pullRequest.number) return { status: 'no-op' as const, error: null };
+  const current = fs.readFileSync(base.resolved.taskMdPath, 'utf8');
+  const metadata = captureTaskWriteMetadata();
+  return writeTask({
+    taskRef: base.resolved.taskId,
+    expectedState: 'active',
+    dryRun,
+    mutations: [
+      { kind: 'frontmatter', set: { pr_number: pullRequest.number, pr_status: 'created', assigned_to: agent } },
+      { kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: '活动日志', body: appendActivity(
+        current, `- ${metadata.timestamp} — **Create PR** by ${agent} — PR #${pullRequest.number} created → ${pullRequest.url}`
+      ) }
+    ]
+  }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
+}
+
+function bindPlatformPullRequest(taskRef: string, options: BindOptions): PullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return base.output;
+  if (!Number.isInteger(options.pr) || options.pr <= 0) return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    error: { code: 'PR_NUMBER_INVALID', message: 'PR number must be positive', retryable: false }
+  });
+  if (base.prNumber && base.prNumber !== options.pr) return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    error: { code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${base.prNumber}`, retryable: false }
+  });
+  const fetched = inspectGitHubPullRequest(base.client, base.context.platform.repository!, options.pr, base.resolved.repoRoot);
+  if (!fetched.ok) return result(fetched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { error: fetched.error });
+  const written = bindIdentity(base, fetched.value, options.agent, options.dryRun);
+  if (written.status === 'failed') return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    pullRequest: fetched.value, error: { code: written.error.code, message: written.error.message, retryable: false }
+  });
+  return result(options.dryRun ? 'planned' : written.status === 'no-op' ? 'no-op' : 'applied', base.resolved.taskId, base.issueNumber, options.dryRun ? base.prNumber : fetched.value.number, {
+    changed: !options.dryRun && written.status === 'applied', platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: fetched.value.number }, pullRequest: fetched.value,
+    operations: [{ name: 'task:bind-pr', status: options.dryRun ? 'planned' : written.status === 'no-op' ? 'no-op' : 'applied', reasonCode: null }], error: null
+  });
+}
+
+function createPlatformPullRequest(taskRef: string, options: CreateOptions): PullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return base.output;
+  if (!options.base || !options.head || !options.title.trim() || !options.body.trim()) return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    error: { code: 'PR_PAYLOAD_INVALID', message: 'base, head, title and body are required', retryable: false }
+  });
+  if (base.prNumber) return inspectPlatformPullRequest(taskRef, options);
+  const located = locatePullRequest(base, options.head, options.base);
+  if (!located.ok && located.error.code === 'PR_IDENTITY_AMBIGUOUS') return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    platform: base.context.platform, capabilities: base.context.capabilities, error: located.error
+  });
+  if (options.dryRun) return result('planned', base.resolved.taskId, base.issueNumber, null, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    operations: [{ name: located.ok ? 'pr:reuse' : 'pr:create', status: 'planned', reasonCode: null }], error: null
+  });
+  const started = writeCreateStarted(base, options.agent);
+  if (started.status === 'failed') return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    error: { code: started.error.code, message: started.error.message, retryable: false }
+  });
+  let pullRequest = located.ok ? located.value : null;
+  let created = false;
+  if (!pullRequest) {
+    const repository = base.context.platform.repository!;
+    const response = base.client.json<RemotePullRequest>(['api', `repos/${repository}/pulls`, '-X', 'POST', '--input', '-'], {
+      cwd: base.resolved.repoRoot,
+      method: 'POST',
+      input: JSON.stringify({ title: options.title, body: options.body, head: options.head, base: options.base, draft: Boolean(options.draft) })
+    });
+    if (response.ok) pullRequest = normalizePullRequest(response.value, repository);
+    else if (response.error.retryable) {
+      const recovered = locatePullRequest(base, options.head, options.base);
+      if (recovered.ok) pullRequest = recovered.value;
+      else return result('blocked', base.resolved.taskId, base.issueNumber, null, {
+        platform: base.context.platform, capabilities: base.context.capabilities,
+        operations: [{ name: 'pr:create', status: 'failed', reasonCode: 'PR_CREATE_OUTCOME_UNKNOWN' }],
+        error: { code: 'PR_CREATE_OUTCOME_UNKNOWN', message: response.error.message, retryable: true }
+      });
+    } else return result('failed', base.resolved.taskId, base.issueNumber, null, {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      operations: [{ name: 'pr:create', status: 'failed', reasonCode: response.error.code }], error: response.error
+    });
+    if (!pullRequest) return result('failed', base.resolved.taskId, base.issueNumber, null, {
+      error: { code: 'PR_CREATE_RESPONSE_INVALID', message: 'PR create response lacks validated identity', retryable: false }
+    });
+    created = true;
+  }
+  const refreshed = resolvedContext(taskRef, options);
+  if (!refreshed.ok) return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    pullRequest, error: { code: 'PR_CREATED_BIND_FAILED', message: pullRequest.url, retryable: false }
+  });
+  const bound = bindIdentity(refreshed, pullRequest, options.agent);
+  if (bound.status === 'failed') return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: pullRequest.number }, pullRequest,
+    operations: [{ name: created ? 'pr:create' : 'pr:reuse', status: 'applied', reasonCode: null }, { name: 'task:bind-pr', status: 'failed', reasonCode: bound.error.code }],
+    error: { code: 'PR_CREATED_BIND_FAILED', message: `${pullRequest.url}: ${bound.error.message}`, retryable: false }
+  });
+  return result('applied', base.resolved.taskId, base.issueNumber, pullRequest.number, {
+    changed: true, platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: pullRequest.number }, pullRequest,
+    operations: [{ name: created ? 'pr:create' : 'pr:reuse', status: created ? 'applied' : 'no-op', reasonCode: null }, { name: 'task:bind-pr', status: 'applied', reasonCode: null }], error: null
+  });
+}
+
+function syncPlatformPullRequest(taskRef: string, options: SyncOptions): PullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return base.output;
+  if (!base.prNumber) return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false }
+  });
+  const fetched = inspectGitHubPullRequest(base.client, base.context.platform.repository!, base.prNumber, base.resolved.repoRoot);
+  if (!fetched.ok) return result(fetched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { error: fetched.error });
+  if (!options.metadata && !options.closingIssue) return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    error: { code: 'PR_PAYLOAD_INVALID', message: 'sync requires a desired-state option', retryable: false }
+  });
+  if (!base.issueNumber) return result('degraded', base.resolved.taskId, null, base.prNumber, {
+    pullRequest: fetched.value, error: { code: 'ISSUE_NOT_LINKED', message: 'Task has no linked Issue to copy metadata from', retryable: false }
+  });
+  const issue = inspectPlatformIssue(taskRef, { cwd: base.resolved.repoRoot, client: base.client });
+  if (!issue.issue) return result(issue.status, base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities, pullRequest: fetched.value, error: issue.error
+  });
+  const planned = planPullRequestMetadata({
+    pullRequest: fetched.value,
+    issue: issue.issue,
+    taskType: base.frontmatter.type || 'task',
+    issueNumber: base.issueNumber,
+    capabilities: base.context.capabilities
+  }).operations.filter((operation) => options.metadata || operation.name === 'closing-issue')
+    .filter((operation) => options.closingIssue || operation.name !== 'closing-issue');
+  const operations: PlatformOperation[] = planned.map(({ name, status, reasonCode }) => ({ name, status, reasonCode }));
+  if (options.dryRun) return result(planned.some((operation) => operation.status === 'planned') ? 'planned' : 'no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities, pullRequest: fetched.value, operations, error: null
+  });
+  const payload: Record<string, unknown> = {};
+  for (const operation of planned) {
+    if (operation.status !== 'planned') continue;
+    if (operation.name === 'labels') payload.labels = operation.value;
+    if (operation.name === 'assignees') payload.assignees = operation.value;
+    if (operation.name === 'closing-issue') payload.body = operation.value;
+    if (operation.name === 'milestone') {
+      const milestones = base.client.json<unknown[]>(['api', '--paginate', '--slurp', `repos/${base.context.platform.repository}/milestones?state=open&per_page=100`], { cwd: base.resolved.repoRoot });
+      if (!milestones.ok) return result(milestones.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { pullRequest: fetched.value, operations, error: milestones.error });
+      const flat = milestones.value.flatMap((entry) => Array.isArray(entry) ? entry : [entry]) as Array<{ title?: string; number?: number }>;
+      payload.milestone = flat.find((entry) => entry.title === operation.value)?.number ?? null;
+    }
+  }
+  if (Object.keys(payload).length === 0) {
+    const degraded = planned.some((operation) => operation.status === 'skipped');
+    return result(degraded ? 'degraded' : 'no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+      platform: base.context.platform, capabilities: base.context.capabilities, resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: fetched.value, operations, error: null
+    });
+  }
+  const patched = base.client.json<RemotePullRequest>(['api', `repos/${base.context.platform.repository}/issues/${base.prNumber}`, '-X', 'PATCH', '--input', '-'], {
+    cwd: base.resolved.repoRoot, method: 'PATCH', input: JSON.stringify(payload)
+  });
+  if (!patched.ok) return result(patched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { pullRequest: fetched.value, operations, error: patched.error });
+  return result(planned.some((operation) => operation.status === 'skipped') ? 'degraded' : 'applied', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    changed: true, platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: fetched.value,
+    operations: operations.map((operation) => operation.status === 'planned' ? { ...operation, status: 'applied' } : operation), error: null
+  });
+}
+
+export {
+  bindPlatformPullRequest,
+  createPlatformPullRequest,
+  inspectGitHubPullRequest,
+  inspectPlatformPullRequest,
+  normalizePullRequest,
+  selectPullRequest,
+  syncPlatformPullRequest
+};
+export type { BindOptions, CreateOptions, PullRequestResult, PullRequestSnapshot, SyncOptions };

package/lib/platform/releases.ts

@@ -0,0 +1,71 @@
+import { createGitHubClient } from './github-client.ts';
+import type { GitHubClient } from './github-client.ts';
+import { resolvePlatformContext } from './context.ts';
+import { platformResult } from './types.ts';
+
+type ReleaseSnapshot = { tag: string; published: boolean; draft: boolean; url: string | null };
+type ReleaseOptions = { cwd?: string; client?: GitHubClient };
+
+function flattenPages(value: unknown): Array<Record<string, unknown>> {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => Array.isArray(entry) ? entry : [entry]).filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object');
+}
+
+function inspectPlatformRelease(tag: string, options: ReleaseOptions = {}) {
+  const client = options.client ?? createGitHubClient();
+  const context = resolvePlatformContext({ cwd: options.cwd, client });
+  if (!context.platform.repository) return { ...platformResult(context.status), platform: context.platform, release: null, workflows: [], error: context.error };
+  const result = client.json<Record<string, unknown>>(['release', 'view', tag, '--repo', context.platform.repository, '--json', 'tagName,isDraft,url'], { cwd: options.cwd });
+  if (!result.ok) {
+    if (result.error.code === 'RESOURCE_NOT_FOUND') return { ...platformResult('no-op'), platform: context.platform, release: null, workflows: [], error: null };
+    return { ...platformResult(result.error.retryable ? 'blocked' : 'failed'), platform: context.platform, release: null, workflows: [], error: result.error };
+  }
+  const release: ReleaseSnapshot = { tag: String(result.value.tagName || tag), published: !Boolean(result.value.isDraft), draft: Boolean(result.value.isDraft), url: result.value.url ? String(result.value.url) : null };
+  const runs = client.json<unknown[]>(['run', 'list', '--repo', context.platform.repository, '--limit', '100', '--json', 'name,headBranch,status,conclusion,url'], { cwd: options.cwd });
+  return { ...platformResult(runs.ok ? 'no-op' : runs.error.retryable ? 'blocked' : 'degraded'), platform: context.platform, release, workflows: runs.ok ? runs.value : [], error: runs.ok ? null : runs.error };
+}
+
+function upsertPlatformRelease(input: { tag: string; title?: string; notesFile?: string }, options: ReleaseOptions = {}) {
+  const inspected = inspectPlatformRelease(input.tag, options);
+  if (inspected.release?.published) return { ...inspected, status: 'no-op' as const, changed: false, operations: [] };
+  if (inspected.status === 'blocked' || inspected.status === 'failed') return { ...inspected, changed: false, operations: [] };
+  if (!inspected.platform.repository) return { ...inspected, status: 'no-op' as const, changed: false, operations: [] };
+  const client = options.client ?? createGitHubClient();
+  const args = ['release', 'create', input.tag, '--repo', inspected.platform.repository!, '--title', input.title ?? input.tag];
+  if (input.notesFile) args.push('--notes-file', input.notesFile); else args.push('--generate-notes');
+  const created = client.text(args, { cwd: options.cwd, method: 'POST' });
+  if (!created.ok) return { ...inspected, status: created.error.retryable ? 'blocked' as const : 'failed' as const, changed: false, operations: [{ name: 'create-release', status: 'failed' }], error: created.error };
+  return { ...inspectPlatformRelease(input.tag, options), status: 'applied' as const, changed: true, operations: [{ name: 'create-release', status: 'applied' }] };
+}
+
+function reconcileReleaseMilestones(version: string, options: ReleaseOptions = {}) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!match) return { status: 'failed' as const, changed: false, operations: [], error: { code: 'RELEASE_VERSION_INVALID', message: `Invalid version '${version}'` } };
+  const client = options.client ?? createGitHubClient();
+  const context = resolvePlatformContext({ cwd: options.cwd, client });
+  if (!context.platform.repository) return { ...platformResult(context.status), changed: false, operations: [], error: context.error };
+  const listed = client.json<unknown>(['api', '--paginate', '--slurp', `repos/${context.platform.repository}/milestones?state=all&per_page=100`], { cwd: options.cwd });
+  if (!listed.ok) return { ...platformResult(listed.error.retryable ? 'blocked' : 'failed'), changed: false, operations: [], error: listed.error };
+  const milestones = flattenPages(listed.value).map((item) => ({ title: String(item.title || ''), number: Number(item.number), state: String(item.state || '') }));
+  const major = Number(match[1]); const minor = Number(match[2]); const patch = Number(match[3]);
+  const ensure = [`${major}.${minor}.${patch + 1}`, `${major}.${minor}.x`];
+  if (patch === 0) ensure.push(`${major}.${minor + 1}.0`, `${major}.${minor + 1}.x`);
+  const operations: Array<{ name: string; title: string; status: 'applied' | 'no-op' | 'failed' }> = [];
+  const current = milestones.find((item) => item.title === version);
+  if (current && current.state !== 'closed') {
+    const closed = client.json(['api', '--method', 'PATCH', `repos/${context.platform.repository}/milestones/${current.number}`, '-f', 'state=closed'], { cwd: options.cwd });
+    operations.push({ name: 'close-milestone', title: version, status: closed.ok ? 'applied' : 'failed' });
+  } else operations.push({ name: 'close-milestone', title: version, status: 'no-op' });
+  for (const title of ensure) {
+    if (milestones.some((item) => item.title === title)) operations.push({ name: 'ensure-milestone', title, status: 'no-op' });
+    else {
+      const created = client.json(['api', '--method', 'POST', `repos/${context.platform.repository}/milestones`, '-f', `title=${title}`], { cwd: options.cwd });
+      operations.push({ name: 'ensure-milestone', title, status: created.ok ? 'applied' : 'failed' });
+    }
+  }
+  const failed = operations.some((operation) => operation.status === 'failed');
+  const changed = operations.some((operation) => operation.status === 'applied');
+  return { status: failed ? 'failed' as const : changed ? 'applied' as const : 'no-op' as const, changed, operations, error: failed ? { code: 'MILESTONE_RECONCILE_FAILED', message: 'One or more milestone operations failed' } : null };
+}
+
+export { inspectPlatformRelease, reconcileReleaseMilestones, upsertPlatformRelease };

package/lib/platform/types.ts

@@ -0,0 +1,74 @@
+type PlatformStatus = 'planned' | 'applied' | 'no-op' | 'degraded' | 'failed' | 'blocked';
+
+type PlatformError = {
+  code: string;
+  message: string;
+  retryable: boolean;
+};
+
+type PlatformCapabilities = {
+  authenticated: boolean;
+  comment: boolean;
+  triage: boolean;
+  push: boolean;
+  admin: boolean;
+};
+
+type PlatformOperation = {
+  name: string;
+  status: 'planned' | 'applied' | 'no-op' | 'skipped' | 'failed';
+  reasonCode: string | null;
+};
+
+type CommentIdentity = {
+  kind: 'task' | 'artifact' | 'summary' | 'cancel';
+  marker: string;
+  ids: number[];
+  parts: number;
+};
+
+type PlatformResult = {
+  status: PlatformStatus;
+  changed: boolean;
+  platform: { type: string | null; repository: string | null; currentUser: string | null };
+  resource: { kind: 'repository' | 'issue' | 'pull-request'; number: number | null };
+  capabilities: PlatformCapabilities;
+  operations: PlatformOperation[];
+  comment: CommentIdentity | null;
+  error: PlatformError | null;
+};
+
+const EMPTY_CAPABILITIES: PlatformCapabilities = {
+  authenticated: false,
+  comment: false,
+  triage: false,
+  push: false,
+  admin: false
+};
+
+function platformResult(
+  status: PlatformStatus,
+  overrides: Partial<PlatformResult> = {}
+): PlatformResult {
+  return {
+    status,
+    changed: status === 'applied',
+    platform: { type: null, repository: null, currentUser: null },
+    resource: { kind: 'repository', number: null },
+    capabilities: { ...EMPTY_CAPABILITIES },
+    operations: [],
+    comment: null,
+    error: null,
+    ...overrides
+  };
+}
+
+export { EMPTY_CAPABILITIES, platformResult };
+export type {
+  CommentIdentity,
+  PlatformCapabilities,
+  PlatformError,
+  PlatformOperation,
+  PlatformResult,
+  PlatformStatus
+};

package/lib/platform/verification-required.ts

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+import { inspectRequiredChecks } from "./pr-checks.ts";
+import { resolvePlatformContext } from "./context.ts";
+
+const CHECK_TYPE = "required-checks";
+const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+
+function validPrNumber(value: any): any {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0;
+}
+
+function readPrFlow(repoRoot: any): any {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(repoRoot, ".agents", ".airc.json"), "utf8"));
+    return config.prFlow;
+  } catch {
+    return undefined;
+  }
+}
+
+function readHead(repoRoot: any): any {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoRoot, encoding: "utf8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function evaluateRequiredChecks(context: any, shared: any): any {
+  const { metadata, localHead, inspection, prFlow } = context;
+  if (prFlow === "disabled" || metadata.pr_status === "skipped" || !validPrNumber(metadata.pr_number)) {
+    return shared.passResult(CHECK_TYPE, "Skipped: required checks are not applicable to this task");
+  }
+
+  const reviewedHead = String(metadata.last_reviewed_commit || "");
+  if (!localHead || !SHA_PATTERN.test(localHead)) {
+    return shared.blockedResult(CHECK_TYPE, "Unable to resolve the local HEAD", "dependency_error");
+  }
+  if (!SHA_PATTERN.test(reviewedHead)) {
+    return shared.failResult(CHECK_TYPE, "Task has no valid last_reviewed_commit", "check_failed");
+  }
+  if (!inspection || inspection.status === "blocked") {
+    return shared.blockedResult(CHECK_TYPE, inspection?.error?.message || "Required checks are unavailable", "network_error");
+  }
+  if (inspection.status === "failed") {
+    return shared.failResult(CHECK_TYPE, inspection.error?.message || "Required checks are unavailable", "check_failed");
+  }
+
+  const prHead = inspection.pullRequest?.headSha;
+  if (!prHead || localHead !== reviewedHead || localHead !== prHead) {
+    return shared.failResult(CHECK_TYPE, "Local HEAD, last reviewed commit, and PR head must match", "check_failed");
+  }
+
+  const state = inspection.checks?.state;
+  if (state === "passed" || state === "no-required") {
+    return shared.passResult(CHECK_TYPE, `Required checks are ${state} for PR head ${prHead}`);
+  }
+  if (state === "pending") {
+    return shared.blockedResult(CHECK_TYPE, inspection.error?.message || "Required checks are pending", "check_pending");
+  }
+  return shared.failResult(CHECK_TYPE, inspection.error?.message || `Required checks are ${state || "unavailable"}`, "check_failed");
+}
+
+export function check({ taskDir }: any, shared: any): any {
+  const task = shared.loadTask(taskDir);
+  if (!task.ok) return shared.failResult(CHECK_TYPE, task.message);
+  const platform = resolvePlatformContext({ cwd: shared.repoRoot });
+  if (platform.platform.type !== "github") {
+    return shared.passResult(CHECK_TYPE, "Skipped: this code platform does not provide required checks");
+  }
+  const prFlow = readPrFlow(shared.repoRoot);
+  if (prFlow === "disabled" || task.metadata.pr_status === "skipped" || !validPrNumber(task.metadata.pr_number)) {
+    return evaluateRequiredChecks({ metadata: task.metadata, localHead: null, inspection: null, prFlow }, shared);
+  }
+  const localHead = readHead(shared.repoRoot);
+  if (!localHead) return evaluateRequiredChecks({ metadata: task.metadata, localHead, inspection: null, prFlow }, shared);
+  const inspection = inspectRequiredChecks(task.metadata.id, { cwd: shared.repoRoot });
+  return evaluateRequiredChecks({ metadata: task.metadata, localHead, inspection, prFlow }, shared);
+}