@fitlab-ai/agent-infra 0.9.11 → 0.9.13

package/lib/platform/verification-sync.ts

@@ -3,13 +3,16 @@ import path from "node:path";
 import process from "node:process";
 import { execFileSync } from "node:child_process";
 
-import { createGitHubClient } from "./github-client.ts";
-import { resolvePlatformContext } from "./context.ts";
+import { resolvePlatformProviderContext } from "./context.ts";
 import { hasCheckedRequirement, resolveRequirementSection } from "./issue-metadata.ts";
-import { inspectGitHubIssueMetadata, requirementSectionAnchors } from "./issues.ts";
-import { listRemoteComments } from "./issue-comments.ts";
+import { requirementSectionAnchors } from "./issues.ts";
 import { taskTypeLabel } from "./metadata-labels.ts";
+import { planInLabelUpdate, validateInLabelMapping, validateRepositoryLabelPayload } from "./in-label-sync.ts";
 import { inspectGitHubPullRequest } from "./pull-requests.ts";
+import { createGitHubClient } from "./github-client.ts";
+import { readPrDeliveryFact } from "../task/pr-delivery-fact.ts";
+import { providerError, providerOperationContext, resourceIdentityNumber, unsupportedProviderOperation } from "./provider-bridge.ts";
+import { taskIssueIdentity } from "./task-identities.ts";
 
 const CHECK_TYPE = "platform-sync";
 const VERSION_LINE_REGEX = /^[0-9]+\.[0-9]+\.x$/;
@@ -28,7 +31,6 @@ const OPTION_LOCALIZATION: Record<string, string> = {
 
 let activeShared: any = null;
 let repoRoot = "";
-const githubClient = createGitHubClient();
 
 export function getDefaults(): any {
   return {
@@ -94,23 +96,15 @@ function safeStat(...args: any[]): any {
   return getShared().safeStat(...args);
 }
 
-function parseIssueNumber(...args: any[]): any {
-  return getShared().parseIssueNumber(...args);
-}
-
-function parsePrNumber(...args: any[]): any {
-  return getShared().parsePrNumber(...args);
-}
-
-export function check({ taskDir, config, artifactFile }: any, shared: any): any {
+export async function check({ taskDir, config, artifactFile }: any, shared: any): Promise<any> {
   activeShared = shared;
   repoRoot = shared.repoRoot;
-  const context = buildSyncContext({ taskDir, config, artifactFile });
+  const context = await buildSyncContext({ taskDir, config, artifactFile });
   if (context.earlyReturn) {
     return context.earlyReturn;
   }
 
-  const remoteData = fetchRemoteData(context);
+  const remoteData = await fetchRemoteData(context);
   if (remoteData.earlyReturn) {
     return remoteData.earlyReturn;
   }
@@ -141,29 +135,36 @@ export function check({ taskDir, config, artifactFile }: any, shared: any): any
     }
   }
 
-  return passResult(CHECK_TYPE, `GitHub sync checks passed for Issue #${context.issueNumber}`);
+  return passResult(CHECK_TYPE, `Platform sync checks passed for Issue ${context.issueNumber || "identity"}`);
 }
 
-function buildSyncContext({ taskDir, config, artifactFile }: any): any {
+async function buildSyncContext({ taskDir, config, artifactFile }: any): Promise<any> {
   const task = loadTask(taskDir);
   if (!task.ok) {
     return { earlyReturn: failResult(CHECK_TYPE, task.message) };
   }
 
-  const issueNumber = parseIssueNumber(task.metadata.issue_number);
-  const prNumber = parsePrNumber(task.metadata.pr_number);
-  if (config.when === "issue_number_exists" && !issueNumber) {
+  const issueIdentity = taskIssueIdentity(task.metadata);
+  const issueNumber = resourceIdentityNumber(issueIdentity);
+  const fact = readPrDeliveryFact(task.metadata);
+  if (fact.status === "invalid") {
+    return { earlyReturn: failResult(CHECK_TYPE, fact.error.message, "check_failed") };
+  }
+  const prIdentity = fact.status === "valid" && fact.fact.state === "bound" ? fact.fact.identity.resource : null;
+  const prNumber = resourceIdentityNumber(prIdentity);
+  if (config.when === "issue_number_exists" && !issueIdentity) {
     return { earlyReturn: passResult(CHECK_TYPE, "Skipped: task has no issue_number") };
   }
-  if (config.when === "pr_number_exists" && !prNumber) {
-    return { earlyReturn: passResult(CHECK_TYPE, "Skipped: task has no pr_number") };
+  if (config.when === "pr_fact_bound" && !prIdentity) {
+    return { earlyReturn: passResult(CHECK_TYPE, "Skipped: task has no verified bound pull request") };
   }
 
-  if (!issueNumber) {
+  if (!issueIdentity) {
     return { earlyReturn: passResult(CHECK_TYPE, "Skipped: platform-sync not required for this task") };
   }
 
-  const platformContext = resolvePlatformContext({ cwd: repoRoot, client: githubClient });
+  const loaded = await resolvePlatformProviderContext({ cwd: repoRoot });
+  const platformContext = loaded.ok ? loaded.value.context : loaded.context;
   if (platformContext.status === "failed") {
     return { earlyReturn: failResult(CHECK_TYPE, platformContext.error?.message || "Platform context failed", "check_failed") };
   }
@@ -176,7 +177,6 @@ function buildSyncContext({ taskDir, config, artifactFile }: any): any {
     }
     return { earlyReturn: passResult(CHECK_TYPE, `Skipped: ${platformContext.error?.message || "platform unavailable"}`) };
   }
-  const repoOwnerType = detectRepoOwnerType(platformContext.platform.repository, taskDir);
   const expectedValues = resolveExpectedValues(config);
   if (!expectedValues.ok) {
     return { earlyReturn: failResult(CHECK_TYPE, expectedValues.message, "check_failed") };
@@ -196,15 +196,20 @@ function buildSyncContext({ taskDir, config, artifactFile }: any): any {
     config,
     artifactFile,
     artifactPath,
+    issueIdentity,
+    prIdentity,
     issueNumber,
     prNumber,
     upstreamRepo: platformContext.platform.repository,
-    repoOwnerType,
+    repoOwnerType: String(loaded.ok ? loaded.value.snapshot.metadata?.ownerType || "unknown" : "unknown"),
     hasTriage: platformContext.capabilities.triage,
     hasPush: platformContext.capabilities.push,
     expectedStatusLabel: expectedValues.statusLabel,
     marker,
-    prMarker
+    prMarker,
+    provider: loaded.ok ? loaded.value.provider : null,
+    providerType: loaded.ok ? loaded.value.providerType : null,
+    loadedContext: loaded.ok ? loaded.value : null
   };
 }
 
@@ -261,170 +266,68 @@ function resolveDefaultValue({ collection, key, value, configKey }: any): any {
   return { ok: true, value: resolvedValue };
 }
 
-function fetchRemoteData(context: any): any {
-  const sharedIssue = inspectGitHubIssueMetadata(
-    githubClient,
-    context.upstreamRepo,
-    context.issueNumber,
-    context.taskDir
-  );
-  const issueResult = sharedIssue.ok
-    ? {
-        ok: true,
-        value: {
-          state: sharedIssue.value.state.toUpperCase(),
-          labels: sharedIssue.value.labels.map((name) => ({ name })),
-          body: sharedIssue.value.body,
-          milestone: sharedIssue.value.milestone ? { title: sharedIssue.value.milestone } : null
-        }
-      }
-    : {
-        ok: false,
-        type: sharedIssue.error.retryable ? "network_error" : "check_failed",
-        message: sharedIssue.error.message
-      };
-  if (!issueResult.ok) {
-    return {
-      earlyReturn: issueResult.type === "check_failed"
-        ? failResult(CHECK_TYPE, issueResult.message, issueResult.type)
-        : blockedResult(CHECK_TYPE, issueResult.message, issueResult.type)
-    };
-  }
-
-  const issue = issueResult.value;
-  if (context.config.issue_must_exist !== false && !issue) {
+async function fetchRemoteData(context: any): Promise<any> {
+  const provider = context.provider;
+  const operationContext = providerOperationContext(context.loadedContext, context.taskDir);
+  const facts = provider?.verification?.fetchRemoteFacts
+    ? await provider.verification.fetchRemoteFacts({
+      context: operationContext,
+      taskId: context.task?.metadata?.id || context.task?.id || "",
+      ...(context.issueIdentity ? { issue: context.issueIdentity } : {}),
+      ...(context.prIdentity ? { changeRequest: context.prIdentity } : {}),
+      includeComments: shouldFetchComments(context.config),
+      includeFields: Boolean(context.config.verify_issue_fields)
+    })
+    : unsupportedProviderOperation(provider, "verification.fetchRemoteFacts");
+  if (!facts.ok) {
     return {
-      earlyReturn: failResult(CHECK_TYPE, `Issue #${context.issueNumber} not found`, "check_failed")
+      earlyReturn: facts.error.retryable
+        ? blockedResult(CHECK_TYPE, providerError(facts.error, "PLATFORM_PROVIDER_OPERATION_FAILED").message, "network_error")
+        : failResult(CHECK_TYPE, providerError(facts.error, "PLATFORM_PROVIDER_OPERATION_FAILED").message, "check_failed")
     };
   }
-
-  let comments = null;
-  if (shouldFetchComments(context.config)) {
-    const commentsResult = withRetry(() => ghPaginatedJson([
-      "api",
-      "--paginate",
-      "--slurp",
-      `repos/${context.upstreamRepo}/issues/${context.issueNumber}/comments?per_page=100`
-    ], context.taskDir));
-
-    if (!commentsResult.ok) {
-      return {
-        earlyReturn: commentsResult.type === "check_failed"
-          ? failResult(CHECK_TYPE, commentsResult.message, commentsResult.type)
-          : blockedResult(CHECK_TYPE, commentsResult.message, commentsResult.type)
-      };
+  const issueSnapshot = facts.value.issue;
+  const issue = issueSnapshot
+    ? {
+      state: issueSnapshot.state.toUpperCase(),
+      labels: issueSnapshot.labels.map((name: string) => ({ name })),
+      body: issueSnapshot.body,
+      milestone: issueSnapshot.milestone ? { title: issueSnapshot.milestone } : null
     }
-
-    comments = flattenComments(commentsResult.value);
+    : null;
+  let issueFields: any;
+  if (context.config.verify_issue_fields && issueSnapshot?.issueType) {
+    const fieldKinds = new Map(issueSnapshot.issueType.fields.map((field: { name: string; kind: string }) => [field.name, field.kind]));
+    issueFields = {
+      pinnedNames: new Set(issueSnapshot.issueType.fields.map((field: { name: string }) => field.name)),
+      values: new Map(Object.entries(issueSnapshot.fields).map(([name, value]) => [name, { kind: fieldKinds.get(name) || (typeof value === "number" ? "number" : "single-select"), value }]))
+    };
   }
-
   let prComments = null;
-  if (context.prMarker) {
-    if (!context.prNumber) {
-      return {
-        earlyReturn: failResult(CHECK_TYPE, "Expected a valid pr_number for PR comment verification", "check_failed")
-      };
-    }
-
-    const prCommentsResult = listRemoteComments(
-      githubClient,
-      context.upstreamRepo,
-      context.prNumber,
-      context.taskDir
-    );
-
-    if (!prCommentsResult.ok) {
-      return {
-        earlyReturn: prCommentsResult.error.retryable
-          ? blockedResult(CHECK_TYPE, prCommentsResult.error.message, "network_error")
-          : failResult(CHECK_TYPE, prCommentsResult.error.message, "check_failed")
-      };
-    }
-
-    prComments = prCommentsResult.value;
-  }
-
-  let issueType;
-  if (context.config.verify_issue_type && context.hasPush) {
-    const issueTypeResult = withRetry(() => ghText([
-      "api",
-      `repos/${context.upstreamRepo}/issues/${context.issueNumber}`,
-      "--jq",
-      ".type.name // empty"
-    ], context.taskDir));
-
-    if (issueTypeResult.ok) {
-      issueType = issueTypeResult.value || null;
-    }
-  }
-
-  let issueFields;
-  if (context.config.verify_issue_fields && context.hasPush) {
-    const [owner, name] = context.upstreamRepo.split("/");
-    const issueFieldsResult = withRetry(() => ghJson([
-      "api",
-      "graphql",
-      "-f",
-      `query=${ISSUE_FIELDS_QUERY}`,
-      "-F",
-      `owner=${owner}`,
-      "-F",
-      `name=${name}`,
-      "-F",
-      `number=${context.issueNumber}`
-    ], context.taskDir));
-
-    if (issueFieldsResult.ok) {
-      issueFields = normalizeIssueFields(issueFieldsResult.value);
-    }
-  }
-
-  let prLabels = null;
-  let prMilestone;
-  let prAssignees;
-  let prHeadSha;
-  if (((context.config.verify_in_labels_match_pr && context.hasTriage)
-    || (context.config.verify_pr_type_label && context.hasTriage)
-    || (context.config.verify_milestone && context.hasTriage)
-    || (context.config.verify_pr_assignee && context.hasPush)
-    || context.config.verify_pr_comment_last_commit_matches_head) && context.prNumber) {
-    const prResult = inspectGitHubPullRequest(
-      githubClient,
-      context.upstreamRepo,
-      context.prNumber,
-      context.taskDir
-    );
-
-    if (!prResult.ok) {
-      return {
-        earlyReturn: prResult.error.retryable
-          ? blockedResult(CHECK_TYPE, prResult.error.message, "network_error")
-          : failResult(CHECK_TYPE, prResult.error.message, "check_failed")
-      };
-    }
-
-    prLabels = (context.config.verify_in_labels_match_pr || context.config.verify_pr_type_label)
-      ? prResult.value.labels
-      : null;
-    prMilestone = context.config.verify_milestone
-      ? prResult.value.milestone ? { title: prResult.value.milestone } : null
-      : undefined;
-    prAssignees = context.config.verify_pr_assignee
-      ? prResult.value.assignees
-      : undefined;
-    prHeadSha = prResult.value.head.sha;
+  if (context.prMarker && context.prIdentity && shouldFetchComments(context.config) && provider?.comments?.list) {
+    const listed = await provider.comments.list({ context: operationContext, parent: context.prIdentity });
+    if (!listed.ok) return {
+      earlyReturn: listed.error.retryable
+        ? blockedResult(CHECK_TYPE, listed.error.message, "network_error")
+        : failResult(CHECK_TYPE, listed.error.message, "check_failed")
+    };
+    prComments = listed.value.map((comment: { id: string; body: string }) => ({ id: comment.id, body: comment.body }));
   }
-
+  const changeRequest = facts.value.changeRequest;
   return {
     issue,
-    comments,
+    comments: facts.value.comments.map((comment: { id: string; body: string }) => ({ id: comment.id, body: comment.body })),
     prComments,
-    prLabels,
-    issueType,
+    prLabels: changeRequest?.labels || null,
+    issueType: issueSnapshot
+      ? (issueSnapshot.issueType ? issueSnapshot.issueType.name : null)
+      : undefined,
     issueFields,
-    prMilestone,
-    prAssignees,
-    prHeadSha
+    prMilestone: changeRequest
+      ? (changeRequest.milestone ? { title: changeRequest.milestone } : null)
+      : undefined,
+    prAssignees: changeRequest?.assignees,
+    prHeadSha: changeRequest?.headSha
   };
 }
 
@@ -444,14 +347,6 @@ function shouldFetchComments(config: any): any {
   );
 }
 
-function flattenComments(value: any): any {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-
-  return value.flatMap((page) => Array.isArray(page) ? page : []);
-}
-
 function checkStatusLabel(context: any, remoteData: any): any {
   if (!context.expectedStatusLabel || !context.hasTriage) {
     return null;
@@ -710,7 +605,7 @@ function checkInLabelsComputed(context: any, remoteData: any): any {
     return null;
   }
 
-  const expectedInLabels = computeExpectedInLabels(context.taskDir);
+  const expectedInLabels = computeExpectedInLabels(context.taskDir, context.upstreamRepo);
   if (!expectedInLabels.ok) {
     return expectedInLabels.type === "check_failed"
       ? failResult(CHECK_TYPE, expectedInLabels.message, expectedInLabels.type)
@@ -1047,8 +942,6 @@ function mapTaskTypeToIssueType(taskType: any): any {
   return mapping[taskType] || "Task";
 }
 
-const ISSUE_FIELDS_QUERY = `query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){issueType{name pinnedFields{__typename ... on IssueFieldSingleSelect{id name} ... on IssueFieldDate{id name} ... on IssueFieldText{id name} ... on IssueFieldNumber{id name}}} issueFieldValues(first:50){nodes{__typename ... on IssueFieldSingleSelectValue{name optionId field{... on IssueFieldSingleSelect{name}}} ... on IssueFieldDateValue{value field{... on IssueFieldDate{name}}} ... on IssueFieldTextValue{value field{... on IssueFieldText{name}}} ... on IssueFieldNumberValue{value field{... on IssueFieldNumber{name}}}}}}}}`;
-
 function normalizeIssueFields(payload: any): any {
   const issue = payload?.data?.repository?.issue;
   const pinnedFields = Array.isArray(issue?.issueType?.pinnedFields)
@@ -1122,10 +1015,18 @@ function formatLabelList(labels: any): any {
   return labels.length > 0 ? labels.join(", ") : "none";
 }
 
-function computeExpectedInLabels(taskDir: any): any {
-  const changedFilesResult = gitText(["diff", "main...HEAD", "--name-only"], taskDir);
+function computeExpectedInLabels(taskDir: any, repository: any): any {
+  const task = loadTask(taskDir);
+  if (!task.ok) {
+    return task;
+  }
+  const baseRef = String(task.metadata?.delivery_base_ref || "").trim();
+  if (!baseRef) {
+    return { ok: false, type: "check_failed", message: "Task has no delivery_base_ref for in-label evidence" };
+  }
+  const changedFilesResult = gitText(["diff", `${baseRef}...HEAD`, "--name-only"], taskDir);
   if (!changedFilesResult.ok) {
-    return changedFilesResult;
+    return { ...changedFilesResult, type: "network_error" };
   }
 
   const changedFiles = String(changedFilesResult.value || "")
@@ -1138,55 +1039,32 @@ function computeExpectedInLabels(taskDir: any): any {
     return mapping;
   }
 
-  if (Object.keys(mapping.value ?? {}).length > 0) {
-    const labels = new Set();
-
-    for (const file of changedFiles) {
-      for (const [label, prefixes] of Object.entries(mapping.value ?? {}) as Array<[string, string[]]>) {
-        if (prefixes.some((prefix: any) => file.startsWith(prefix))) {
-          labels.add(`in: ${label}`);
-        }
-      }
-    }
-
-    return { ok: true, labels: Array.from(labels).sort(), mode: "mapped" };
+  if (Object.keys(mapping.value ?? {}).length === 0) {
+    return { ok: true, labels: [], mode: "mapped" };
   }
 
-  const repoLabelsResult = withRetry(() => ghJson([
-    "label",
-    "list",
-    "--limit",
-    "200",
-    "--json",
-    "name"
-  ], taskDir));
+  const client = createGitHubClient();
+  const repoLabelsResult = withRetry(() => client.json([
+    "api", "--paginate", "--slurp", `repos/${repository}/labels?per_page=100`
+  ], { cwd: taskDir }));
   if (!repoLabelsResult.ok) {
     return repoLabelsResult;
   }
 
-  const repoInLabels = new Set(
-    extractLabelNames(repoLabelsResult.value)
-      .filter((label: any) => label.startsWith("in:"))
-  );
-
-  if (repoInLabels.size === 0) {
-    return { ok: true, labels: [], mode: "fallback" };
+  const repositoryLabels = validateRepositoryLabelPayload(repoLabelsResult.value);
+  if (!repositoryLabels.ok) {
+    return { ok: false, type: "check_failed", message: repositoryLabels.error.message };
   }
-
-  const labels = new Set();
-  for (const file of changedFiles) {
-    const topLevel = file.split("/")[0];
-    if (!topLevel) {
-      continue;
-    }
-
-    const candidate = `in: ${topLevel}`;
-    if (repoInLabels.has(candidate)) {
-      labels.add(candidate);
-    }
+  const planned = planInLabelUpdate({
+    changedFiles,
+    currentLabels: [],
+    mapping: mapping.value ?? {},
+    repositoryLabels: new Set(repositoryLabels.value)
+  });
+  if (planned.error) {
+    return { ok: false, type: "check_failed", message: planned.error.message };
   }
-
-  return { ok: true, labels: Array.from(labels).sort(), mode: "fallback" };
+  return { ok: true, labels: planned.target, mode: "mapped" };
 }
 
 function loadInLabelMapping(): any {
@@ -1197,26 +1075,10 @@ function loadInLabelMapping(): any {
 
   try {
     const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
-    const mapping = config?.labels?.in;
-    if (!mapping || typeof mapping !== "object" || Array.isArray(mapping)) {
-      return { ok: true, value: {} };
-    }
-
-    const normalized: Record<string, string[]> = {};
-    for (const [label, prefixes] of Object.entries(mapping)) {
-      if (!Array.isArray(prefixes)) {
-        continue;
-      }
-
-      const cleaned = prefixes
-        .map((value) => String(value || "").trim())
-        .filter(Boolean);
-      if (cleaned.length > 0) {
-        normalized[label] = cleaned;
-      }
-    }
-
-    return { ok: true, value: normalized };
+    const mapping = validateInLabelMapping(config?.labels?.in);
+    return mapping.ok
+      ? { ok: true, value: mapping.value }
+      : { ok: false, type: "check_failed", message: mapping.error.message };
   } catch (error: any) {
     return { ok: false, type: "check_failed", message: `Unable to parse .agents/.airc.json: ${error.message}` };
   }
@@ -1224,43 +1086,6 @@ function loadInLabelMapping(): any {
 
 // === GitHub API ===
 
-function detectRepoOwnerType(upstreamRepo: any, taskDir: any): any {
-  const ownerTypeResult = withRetry(() => ghText([
-    "api",
-    `repos/${upstreamRepo}`,
-    "--jq",
-    ".owner.type // empty"
-  ], taskDir));
-
-  if (!ownerTypeResult.ok) {
-    return "unknown";
-  }
-
-  return ownerTypeResult.value || "unknown";
-}
-
-function ghJson(args: any, cwd: any): any {
-  return mapClientResult(githubClient.json(args, { cwd }));
-}
-
-function ghText(args: any, cwd: any): any {
-  return mapClientResult(githubClient.text(args, { cwd }));
-}
-
-function ghPaginatedJson(args: any, cwd: any): any {
-  return ghJson(args, cwd);
-}
-
-function mapClientResult(result: any): any {
-  if (result.ok) return result;
-  const checkFailed = ["RESOURCE_NOT_FOUND", "PERMISSION_DENIED", "PLATFORM_REQUEST_INVALID"].includes(result.error.code);
-  return {
-    ok: false,
-    type: checkFailed ? "check_failed" : "network_error",
-    message: result.error.message
-  };
-}
-
 function gitText(args: any, cwd: any): any {
   try {
     const value = execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });

package/lib/pr-review/evidence-grading.ts

@@ -1,7 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+import { parseTypedTaskFrontmatter } from '../task/frontmatter.ts';
+import { readPrDeliveryFact } from '../task/pr-delivery-fact.ts';
+import { resourceIdentityEquals, resourceIdentityNumber } from '../platform/resource-identity.ts';
+import type { ResourceIdentity } from '../platform/resource-identity.ts';
+import { taskIssueIdentity } from '../platform/task-identities.ts';
 
 // ---------------------------------------------------------------------------
 // Host resolution (PL-4): PR -> unique / ambiguous / none.
@@ -12,10 +16,12 @@ export type HostCandidate = {
   taskDir: string;
   issueNumber: number | null;
   prNumber: number | null;
+  issueIdentity?: ResourceIdentity;
+  prIdentity?: ResourceIdentity;
 };
 
 export type HostResolution =
-  | { kind: 'unique'; taskId: string; taskDir: string; issueNumber: number; prNumber: number }
+  | { kind: 'unique'; taskId: string; taskDir: string; issueNumber: number; prNumber: number; issueIdentity?: ResourceIdentity; prIdentity?: ResourceIdentity }
   | { kind: 'ambiguous'; candidates: Array<{ taskId: string; issueNumber: number }> }
   | { kind: 'none' };
 
@@ -62,10 +68,11 @@ export function extractClosingIssueNumbers(body: string): number[] {
 /**
  * Scan `.agents/workspace/active/{task-id}/task.md` files for tasks bound to the
  * PR number or to one of the PR's closing issues. A task is emitted at most once;
- * a direct `pr_number` hit takes priority over the issue-number reverse lookup.
+ * a verified fact identity hit takes priority over the issue-number reverse lookup.
  */
 export function collectHostCandidates(input: {
-  prNumber: number;
+  prNumber?: number;
+  prIdentity?: ResourceIdentity;
   closingIssues: number[];
   workspaceRoot: string;
 }): HostCandidate[] {
@@ -87,13 +94,24 @@ export function collectHostCandidates(input: {
     } catch {
       continue;
     }
-    const frontmatter = parseTaskFrontmatter(content);
-    const issueNumber = toPositiveNumber(frontmatter.issue_number);
-    const prNumber = toPositiveNumber(frontmatter.pr_number);
-    if (prNumber === input.prNumber) {
-      candidates.push({ taskId: entry.name, taskDir, issueNumber, prNumber });
+    let frontmatter: ReturnType<typeof parseTypedTaskFrontmatter>;
+    try { frontmatter = parseTypedTaskFrontmatter(content); } catch { continue; }
+    const issueIdentity = taskIssueIdentity(frontmatter);
+    const issueNumber = resourceIdentityNumber(issueIdentity) ?? toPositiveNumber(frontmatter.issue_number);
+    const fact = readPrDeliveryFact(frontmatter);
+    const prIdentity = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
+    const prNumber = resourceIdentityNumber(prIdentity);
+    const matchesPr = input.prIdentity
+      ? Boolean(prIdentity && resourceIdentityEquals(prIdentity, input.prIdentity))
+      : input.prNumber !== undefined && prNumber === input.prNumber;
+    const identityDetails = {
+      ...(issueIdentity && issueIdentity.kind !== 'number' ? { issueIdentity } : {}),
+      ...(prIdentity && prIdentity.kind !== 'number' ? { prIdentity } : {})
+    };
+    if (matchesPr) {
+      candidates.push({ taskId: entry.name, taskDir, issueNumber, prNumber, ...identityDetails });
     } else if (issueNumber !== null && input.closingIssues.includes(issueNumber)) {
-      candidates.push({ taskId: entry.name, taskDir, issueNumber, prNumber });
+      candidates.push({ taskId: entry.name, taskDir, issueNumber, prNumber, ...identityDetails });
     }
   }
   return candidates;
@@ -113,7 +131,9 @@ export function resolveHostFromCandidates(candidates: HostCandidate[]): HostReso
       taskId: candidate.taskId,
       taskDir: candidate.taskDir,
       issueNumber: candidate.issueNumber ?? 0,
-      prNumber: candidate.prNumber ?? 0
+      prNumber: candidate.prNumber ?? 0,
+      ...(candidate.issueIdentity ? { issueIdentity: candidate.issueIdentity } : {}),
+      ...(candidate.prIdentity ? { prIdentity: candidate.prIdentity } : {})
     };
   }
   return {