@fitlab-ai/agent-infra 0.9.12 → 0.9.13

package/dist/lib/task/verification-engine.js

@@ -21,6 +21,7 @@ import { snapshotReview } from "../git/review-snapshot.js";
 import { OrchestrationStateError, readRun } from "./orchestration.js";
 import { resolveDeliveryTarget } from "./delivery-target.js";
 import { readPrDeliveryFact } from "./pr-delivery-fact.js";
+import { validateLocalArtifact } from "./local-artifact-finalization.js";
 const TASK_ENUMS = {
     type: ["feature", "bugfix", "refactor", "docs", "chore"],
     workflow: ["feature-development", "bug-fix", "refactoring"],
@@ -69,7 +70,7 @@ const scriptPath = fileURLToPath(import.meta.url);
 let repoRoot = path.resolve(path.dirname(scriptPath), "..", "..");
 const PLATFORM_ADAPTERS = {
     "platform-sync": checkPlatformSync,
-    "platform-sync-preflight": (context, shared) => ({ ...checkPlatformSync(context, shared), type: "platform-sync-preflight" }),
+    "platform-sync-preflight": async (context, shared) => ({ ...await checkPlatformSync(context, shared), type: "platform-sync-preflight" }),
     "required-checks": checkRequiredChecks
 };
 const OPTIONAL_PLATFORM_CHECKS = new Set(["platform-sync"]);
@@ -86,7 +87,7 @@ const sharedUtils = {
     parseIssueNumber,
     parsePrNumber
 };
-function runCheck(type, context, shared) {
+async function runCheck(type, context, shared) {
     switch (type) {
         case "task-meta":
             return checkTaskMeta(context);
@@ -124,7 +125,7 @@ function runCheck(type, context, shared) {
                 }
                 return failResult(type, `Unsupported check type '${type}'.`);
             }
-            return adapter(context, shared);
+            return await adapter(context, shared);
         }
     }
 }
@@ -419,7 +420,7 @@ function checkTaskMeta({ taskDir, config }) {
     const warningSuffix = warnings.length > 0 ? `; warnings: ${warnings.join("; ")}` : "";
     return passResult("task-meta", `Task metadata valid (${requiredFields.length} required fields checked${warningSuffix})`, warnings);
 }
-function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }) {
+async function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }) {
     const task = loadTask(taskDir);
     if (!task.ok)
         return failResult('required-pr-delivery', task.message);
@@ -438,10 +439,11 @@ function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }) {
         return failResult('required-pr-delivery', factRead.error.message);
     const fact = factRead.status === 'valid' ? factRead.fact : null;
     const status = fact?.state || 'unbound';
-    const prNumber = fact?.state === 'bound' ? fact.identity.number : null;
+    const prIdentity = fact?.state === 'bound' ? fact.identity.resource : null;
+    const prNumber = prIdentity?.kind === 'number' ? prIdentity.value : null;
     if (flow === 'disabled')
         return passResult('required-pr-delivery', 'Pull request delivery is disabled by project policy');
-    if (flow === 'required' && (status !== 'bound' || prNumber === null)) {
+    if (flow === 'required' && (status !== 'bound' || !prIdentity)) {
         return failResult('required-pr-delivery', 'Project policy requires a bound pull request before completion');
     }
     if (flow !== 'required' && status === 'unbound') {
@@ -451,7 +453,7 @@ function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }) {
         if (mode === 'gate') {
             return passResult('required-pr-delivery', 'Bound pull request shape is valid; merged-state inspection is reserved for hard preflight');
         }
-        const inspected = inspectPlatformPullRequest(task.metadata.id, { cwd: repositoryRoot });
+        const inspected = await inspectPlatformPullRequest(task.metadata.id, { cwd: repositoryRoot });
         if (inspected.status === 'blocked') {
             return blockedResult('required-pr-delivery', inspected.error?.message || 'Unable to inspect the required pull request', inspected.error?.code || 'PR_INSPECTION_BLOCKED');
         }
@@ -459,7 +461,7 @@ function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }) {
         const repository = inspected.platform.repository?.toLowerCase() || '';
         const taskBranch = String(task.metadata.branch || '').trim();
         const deliveryBaseRef = String(task.metadata.delivery_base_ref || projectConfig.delivery?.baseRef || '').trim();
-        if (inspected.status !== 'no-op' || !pullRequest || pullRequest.number !== prNumber) {
+        if (inspected.status !== 'no-op' || !pullRequest) {
             return failResult('required-pr-delivery', 'Bound pull request identity could not be verified');
         }
         if (!repository
@@ -472,7 +474,7 @@ function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }) {
         if (pullRequest.state !== 'closed' || !pullRequest.mergedAt || !pullRequest.mergeCommitSha) {
             return failResult('required-pr-delivery', 'Project policy requires the bound pull request to be merged');
         }
-        return passResult('required-pr-delivery', `Pull request delivery policy satisfied (merged PR #${prNumber})`);
+        return passResult('required-pr-delivery', `Pull request delivery policy satisfied (merged PR ${prNumber === null ? 'identity' : `#${prNumber}`})`);
     }
     return passResult('required-pr-delivery', `Pull request delivery policy satisfied (${status})`);
 }
@@ -504,7 +506,7 @@ function loadProjectName() {
         return "";
     }
 }
-function checkArtifact({ taskDir, config, artifactFile }) {
+function checkArtifact({ taskDir, config, artifactFile, skillName }) {
     const resolvedArtifact = resolveArtifactPath(taskDir, config.file_pattern, artifactFile);
     if (!resolvedArtifact.ok) {
         return failResult("artifact", resolvedArtifact.message);
@@ -519,6 +521,20 @@ function checkArtifact({ taskDir, config, artifactFile }) {
     }
     const content = fs.readFileSync(artifactPath, "utf8");
     const requiredSections = config.required_sections || [];
+    const localFamily = skillName === "analyze-task"
+        ? "analysis"
+        : skillName === "plan-task" ? "plan" : skillName === "code-task" ? "code" : null;
+    if (localFamily) {
+        const local = validateLocalArtifact(content, {
+            family: localFamily,
+            requiredSections: requiredSections.filter((section) => typeof section === "string"),
+            requiredPatterns: (config.required_patterns || []).filter((pattern) => typeof pattern === "string")
+        });
+        if (!local.ok) {
+            return failResult("artifact", `${path.basename(artifactPath)} has local structural errors: ${local.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')}`);
+        }
+        return passResult("artifact", `${path.basename(artifactPath)} passed (${requiredSections.length} sections)`);
+    }
     const missingSections = requiredSections.filter((section) => !new RegExp(`^##\\s+${escapeRegExp(section)}\\s*$`, "m").test(content));
     if (missingSections.length > 0) {
         return failResult("artifact", `${path.basename(artifactPath)} is missing sections: ${missingSections.join(", ")}`);
@@ -902,6 +918,8 @@ function checkManualValidation({ taskDir }) {
     // 1. Latest review-code artifact; none -> pass (no review, check not applicable).
     const review = findAuthoritativeReviewCodeArtifact(taskDir);
     if (!review.ok) {
+        if (review.error)
+            return failResult("manual-validation", `Review-code artifact is unavailable: ${review.error}`);
         return passResult("manual-validation", "No review-code artifact; manual validation not applicable");
     }
     // 2. Parse the numeric manual-validation count; unparseable/null -> fail closed
@@ -953,9 +971,11 @@ function checkManualValidation({ taskDir }) {
     }
     return passResult("manual-validation", `Manual validation completed → ${artifactName}`);
 }
-function checkPostReviewCommit({ taskDir, config }) {
+async function checkPostReviewCommit({ taskDir, config }) {
     const reviewArtifact = findAuthoritativeReviewCodeArtifact(taskDir);
     if (!reviewArtifact.ok) {
+        if (reviewArtifact.error)
+            return failResult("post-review-commit", `Review-code artifact is unavailable: ${reviewArtifact.error}`);
         return passResult("post-review-commit", "No review-code artifact; check inactive");
     }
     let gitRoot;
@@ -977,7 +997,7 @@ function checkPostReviewCommit({ taskDir, config }) {
     const hasPullRequest = fact?.state === 'bound';
     let inspected = null;
     if (hasPullRequest) {
-        inspected = inspectPlatformPullRequest(task.metadata.id, { cwd: gitRoot });
+        inspected = await inspectPlatformPullRequest(task.metadata.id, { cwd: gitRoot });
         if (!inspected.pullRequest) {
             const message = inspected.error?.message || "PR merge snapshot is unavailable";
             const code = inspected.error?.code || "PR_INSPECTION_INVALID";
@@ -988,7 +1008,7 @@ function checkPostReviewCommit({ taskDir, config }) {
         if (inspected.pullRequest.state === "closed" &&
             inspected.pullRequest.mergedAt &&
             inspected.pullRequest.mergeCommitSha) {
-            const relation = resolveMaterializedReviewedHeadRelation({
+            const relation = await resolveMaterializedReviewedHeadRelation({
                 cwd: gitRoot,
                 platformType: inspected.platform.type,
                 lastReviewedCommit,
@@ -1124,6 +1144,13 @@ function checkReviewFact({ taskDir, artifactFile }) {
     if (!resolvedArtifact.ok) {
         return failResult("review-fact", resolvedArtifact.message);
     }
+    const authoritative = findAuthoritativeReviewCodeArtifact(taskDir);
+    if (!authoritative.ok) {
+        return failResult("review-fact", authoritative.error ?? "No active review-code artifact is available");
+    }
+    if (path.basename(resolvedArtifact.path) !== authoritative.fileName) {
+        return failResult("review-fact", `review-code artifact ${path.basename(resolvedArtifact.path)} is not the current active artifact ${authoritative.fileName}; re-run review-code`);
+    }
     const task = loadTask(taskDir);
     if (!task.ok) {
         return failResult("review-fact", task.message);
@@ -1401,7 +1428,7 @@ function escapeRegExp(value) {
 function isBlank(value) {
     return value === undefined || value === null || String(value).trim() === "";
 }
-function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: requestedChecks, repositoryRoot }) {
+async function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: requestedChecks, repositoryRoot }) {
     if (repositoryRoot)
         repoRoot = path.resolve(repositoryRoot);
     else {
@@ -1418,7 +1445,7 @@ function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: reque
         for (const [type, checkConfig] of Object.entries(verifyConfig.checks || {})) {
             if (checkConfig === null)
                 continue;
-            const result = runCheck(type, {
+            const result = await runCheck(type, {
                 mode,
                 skillName,
                 taskDir: path.resolve(taskDir),
@@ -1441,7 +1468,7 @@ function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: reque
         return { skill: skillName, ...passResult(type, `Check '${type}' is disabled for skill '${skillName}'.`) };
     return {
         skill: skillName,
-        ...runCheck(type, {
+        ...await runCheck(type, {
             skillName,
             taskDir: path.resolve(taskDir),
             artifactFile,

package/dist/lib/task/verification.js

@@ -41,7 +41,7 @@ function failure(request, code, message, extra = {}) {
         artifact: request.artifact ?? null, invocations: [], error: { code, message }, ...extra
     };
 }
-function verifyTaskEvent(request, options = {}) {
+async function verifyTaskEvent(request, options = {}) {
     const spec = VERIFICATION_CATALOG[request.event];
     if (!spec)
         return failure(request, 'VERIFY_EVENT_UNKNOWN', `unknown verification event '${request.event}'`);
@@ -66,7 +66,7 @@ function verifyTaskEvent(request, options = {}) {
     const invocations = [];
     const engine = options.engine ?? verifyInProcess;
     if (spec.mode === 'gate') {
-        const payload = engine({ mode: 'gate', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [], repositoryRoot: resolved.repoRoot });
+        const payload = await engine({ mode: 'gate', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [], repositoryRoot: resolved.repoRoot });
         const status = payload.gate;
         if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
             invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, gate: 'pass', humanOverride: 'human-approved', originalGate: status } });
@@ -79,7 +79,7 @@ function verifyTaskEvent(request, options = {}) {
     }
     else {
         for (const check of spec.checks ?? []) {
-            const payload = engine({ mode: 'checks', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [check], repositoryRoot: resolved.repoRoot });
+            const payload = await engine({ mode: 'checks', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [check], repositoryRoot: resolved.repoRoot });
             const status = payload.status;
             if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
                 invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, status: 'pass', humanOverride: 'human-approved', originalStatus: status } });

package/dist/lib/task/workflow-warning-intents.js

@@ -38,7 +38,7 @@ function sectionMutation(content) {
     const english = /^##\s+Activity Log\s*$/m.test(content);
     return [{
             kind: 'section', aliases: WORKFLOW_WARNING_HEADINGS, heading: english ? 'Workflow Warnings' : '工作流告警',
-            body: `| ${WORKFLOW_WARNING_COLUMNS.join(' | ')} |\n|----|------|------|----------|------|--------|--------|---------|--------|-------------|------------|`
+            body: `| ${WORKFLOW_WARNING_COLUMNS.join(' | ')} |\n|----|------|------|----------|------|--------|---------|--------|-------------|------------|------------|`
         }];
 }
 function rowMutation(row) {

package/dist/lib/task/write.js

@@ -6,6 +6,7 @@ import { resolveTaskRef } from './resolve-ref.js';
 import { allowsManualOverride } from './guard-override.js';
 import { mutateTableRow, upsertSection } from './sections.js';
 import { validateCurrentTaskContract } from './current-contract.js';
+import { invalidationBlocks, parseInvalidationDocument } from './invalidation.js';
 const DEFAULT_FILE_SYSTEM = {
     readFileSync: (file) => fs.readFileSync(file, 'utf8'),
     statModeSync: (file) => fs.statSync(file).mode,
@@ -90,6 +91,16 @@ function writeTask(request, options = {}) {
         if (!contract.ok) {
             return failure(request, identity, contract.code, contract.message);
         }
+        if (invalidationBlocks(contract.invalidation)
+            && options.invalidationContext !== 'source-completion'
+            && options.invalidationContext !== 'reconcile') {
+            return failure(request, identity, 'TASK_INVALIDATION_BLOCKED', 'task has an incomplete artifact invalidation operation; reconcile it before writing downstream state');
+        }
+    }
+    else {
+        const invalidation = parseInvalidationDocument(original);
+        if (!invalidation.ok)
+            return failure(request, identity, 'TASK_INVALIDATION_INVALID', invalidation.message);
     }
     let candidate = original;
     const operations = [];

package/dist/lib/version.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
+import semver from 'semver';
 const packageJsonUrl = [
     new URL('../package.json', import.meta.url),
     new URL('../../package.json', import.meta.url),
@@ -9,8 +10,17 @@ if (!packageJsonUrl) {
 const { version } = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
 const VERSION = `v${version}`;
 const AGENT_INFRA_VERSION_PATTERN = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const LEGACY_COMPATIBILITY_CUTOFF_VERSION = '1.0.0';
 function isValidAgentInfraVersion(value) {
     return typeof value === 'string' && AGENT_INFRA_VERSION_PATTERN.test(value);
 }
-export { VERSION, isValidAgentInfraVersion };
+function isLegacyCompatibilityEnabled(runtimeVersion = VERSION) {
+    const normalized = runtimeVersion.startsWith('v') ? runtimeVersion.slice(1) : runtimeVersion;
+    const parsed = semver.valid(normalized);
+    return parsed !== null && semver.lt(parsed, LEGACY_COMPATIBILITY_CUTOFF_VERSION);
+}
+function legacyCompatibilityError(resource, runtimeVersion = VERSION) {
+    return Object.assign(new Error(`PLATFORM_IDENTITY_LEGACY_UNSUPPORTED: ${resource} requires migration to the current schema before v${LEGACY_COMPATIBILITY_CUTOFF_VERSION} runtime ${runtimeVersion}`), { code: 'PLATFORM_IDENTITY_LEGACY_UNSUPPORTED' });
+}
+export { LEGACY_COMPATIBILITY_CUTOFF_VERSION, VERSION, isLegacyCompatibilityEnabled, isValidAgentInfraVersion, legacyCompatibilityError };
 //# sourceMappingURL=version.js.map

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.9.12",
-  "sourceInputHash": "5e1b341aad5fe825884f4dbdbd01d0752ca66107d1ccb4b0fe4d8d3aae49120d",
-  "internalExecutableBuildHash": "39bf2c60e3a9b834d4a24ab3088f108583d15ee2bdc77e6376e517921be47c80"
+  "packageVersion": "0.9.13",
+  "sourceInputHash": "5e4d3ad1c1e7e3c909489ef59ff318ea9cffe5f538ae37d83923773946357afe",
+  "internalExecutableBuildHash": "c8cabf5c6bc776cdcb9621f712172ebda95ff9b12fb6f67213e18bc0159516fd"
 }

package/lib/agent-clients/next-steps.ts

@@ -1,6 +1,7 @@
 import { listEnabledAgentClientAdapters } from './registry.ts';
 import { renderAgentClientInvocation } from './invocation.ts';
 import semver from 'semver';
+import { isTaskScopeSkill } from '../task/skill-scope.ts';
 import type { CustomTUI } from './custom-tuis.ts';
 import type { AgentClientId, AgentClientState } from './types.ts';
 
@@ -45,7 +46,11 @@ function renderNextStepCommands(
   }
 
   const args = [
-    ...(input.taskRef === undefined ? [] : [input.taskRef]),
+    ...(input.taskRef === undefined
+      ? []
+      : isTaskScopeSkill(input.skillName)
+        ? ['--task', input.taskRef]
+        : [input.taskRef]),
     ...(input.version === undefined ? [] : [input.version])
   ];
 

package/lib/decide.ts

@@ -79,11 +79,11 @@ export async function decide(args: string[], options: DecideOptions = {}): Promi
       metadataProvider: () => ({ timestamp: now, agentInfraVersion: options.version ?? VERSION })
     };
     let result;
-    const execute = () => {
+    const execute = async () => {
       let current = applyHumanDecision(request, writeOptions);
       if (current.status !== 'failed' || !parsedDecision.overrideTicket) return current;
       if (!parsedDecision.overrideTarget || !parsedDecision.overrideScope) throw new Error('override ticket requires --override-target and --override-scope');
-      const consumed = consumeHumanOverride({
+      const consumed = await consumeHumanOverride({
         taskRef: resolved.taskId,
         ticketId: parsedDecision.overrideTicket,
         failureId: failureId('decision-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
@@ -102,7 +102,7 @@ export async function decide(args: string[], options: DecideOptions = {}): Promi
       if (consumed.status === 'failed') throw new Error(consumed.error.message);
       return current;
     };
-    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute);
+    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute);
     if (result.error) throw new Error(result.error.message);
     return 0;
   } catch (error) {

package/lib/init.ts

@@ -40,7 +40,7 @@ type AgentConfig = {
   project: string;
   org: string;
   language: string;
-  platform: { type: string };
+  platform: { type: string; providers?: Record<string, unknown> };
   templateVersion: string;
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };

package/lib/internal/platform-checks.ts

@@ -70,17 +70,17 @@ async function platformChecks(args: string[] = []): Promise<void> {
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
-  if (operation === 'inspect') { finish(inspectPullRequestReadiness(taskRef, { cwd })); return; }
+  if (operation === 'inspect') { finish(await inspectPullRequestReadiness(taskRef, { cwd })); return; }
   if (operation === 'resolve-run') {
     if (!values.checkName) { fail('resolve-run requires --check-name'); return; }
-    finish(resolvePlatformCheckRun(taskRef, { cwd, checkName: values.checkName, detailsUrl: values.detailsUrl }));
+    finish(await resolvePlatformCheckRun(taskRef, { cwd, checkName: values.checkName, detailsUrl: values.detailsUrl }));
     return;
   }
   if (operation === 'logs') {
     const run = positive(values.run);
     const job = values.job === undefined ? undefined : positive(values.job);
     if (!run || values.job !== undefined && !job) { fail('logs requires a positive --run and optional positive --job'); return; }
-    finish(fetchPlatformCheckLogs(taskRef, { cwd, run, job: job || undefined }));
+    finish(await fetchPlatformCheckLogs(taskRef, { cwd, run, job: job || undefined }));
     return;
   }
   const intervalSeconds = positive(values.intervalSeconds);

package/lib/internal/platform-comment.ts

@@ -11,7 +11,7 @@ import type { CommentKind } from '../platform/issue-comments.ts';
 import type { PlatformResult } from '../platform/types.ts';
 import { backfillCompletionComments } from '../platform/completion-backfill.ts';
 
-const USAGE = `Usage: agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
+const USAGE = `Usage: agent-infra-internal platform-comment list --issue <token> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
        agent-infra-internal platform-comment backfill <task-ref> --agent <agent> [--cwd <path>]
        agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
@@ -52,7 +52,7 @@ function readBodyFile(value: string, cwd: string): string {
   return fs.readFileSync(path.resolve(cwd, value), 'utf8');
 }
 
-function platformComment(args: string[] = []): void {
+async function platformComment(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
   if (!operation || !['list', 'owner', 'backfill', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
@@ -63,17 +63,17 @@ function platformComment(args: string[] = []): void {
   if (parsed.error) { fail(parsed.error); return; }
   const cwd = path.resolve(typeof parsed.values.cwd === 'string' ? parsed.values.cwd : process.cwd());
   if (operation === 'list') {
-    const issue = Number(parsed.values.issue);
-    if (!Number.isInteger(issue) || issue <= 0) { fail('list requires a positive --issue'); return; }
+    const issue = parsed.values.issue;
+    if (typeof issue !== 'string' || !issue) { fail('list requires --issue <token>'); return; }
     const unexpected = Object.keys(parsed.values).find((key) => !['issue', 'cwd'].includes(key));
     if (unexpected) { fail(`list does not accept '--${unexpected}'`); return; }
-    finish(listPlatformComments(issue, cwd));
+    finish(await listPlatformComments(issue, cwd));
     return;
   }
   if (operation === 'owner') {
     const unexpected = Object.keys(parsed.values).find((key) => key !== 'cwd');
     if (unexpected) { fail(`owner does not accept '--${unexpected}'`); return; }
-    finish(checkPlatformCommentOwner(taskRef!, { cwd }));
+    finish(await checkPlatformCommentOwner(taskRef!, { cwd }));
     return;
   }
   if (operation === 'backfill') {
@@ -83,7 +83,7 @@ function platformComment(args: string[] = []): void {
     if (typeof agent !== 'string' || !agent) { fail('backfill requires --agent'); return; }
     const normalizedAgent = normalizeAgentToken(agent);
     if (!normalizedAgent) { fail(`invalid --agent '${agent}': ${AGENT_USAGE_HINT}`); return; }
-    finish(backfillCompletionComments(taskRef!, { cwd, agent: normalizedAgent }));
+    finish(await backfillCompletionComments(taskRef!, { cwd, agent: normalizedAgent }));
     return;
   }
   const kind = parsed.values.kind;
@@ -101,7 +101,7 @@ function platformComment(args: string[] = []): void {
     fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
     return;
   }
-  finish(syncPlatformComment(taskRef!, {
+  finish(await syncPlatformComment(taskRef!, {
     kind: kind as CommentKind,
     agent: normalizedAgent,
     artifact: typeof parsed.values.artifact === 'string' ? parsed.values.artifact : undefined,

package/lib/internal/platform-context.ts

@@ -10,7 +10,7 @@ function fail(message: string): void {
   process.exitCode = 1;
 }
 
-function platformContext(args: string[] = []): void {
+async function platformContext(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   if (args[0] !== 'resolve') { fail("operation must be 'resolve'"); return; }
   let cwd = process.cwd();
@@ -24,7 +24,7 @@ function platformContext(args: string[] = []): void {
     seen.add(flag);
     cwd = path.resolve(value);
   }
-  const result = resolvePlatformContext({ cwd });
+  const result = await resolvePlatformContext({ cwd });
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'failed') process.exitCode = 1;
   if (result.status === 'blocked') process.exitCode = 2;

package/lib/internal/platform-issue.ts

@@ -11,7 +11,7 @@ import type { IssueResult } from '../platform/issues.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-issue inspect <task-ref> [--cwd <path>]
        agent-infra-internal platform-issue create <task-ref> --agent <agent> [--dry-run] [--cwd <path>]
-       agent-infra-internal platform-issue bind <task-ref> --issue <N> --agent <agent> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-issue bind <task-ref> --issue <token> --agent <agent> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-issue sync <task-ref> --agent <agent> [--status <suffix|none>] [--assignees current|none] [--milestone initial|specific|none] [--issue-type] [--fields] [--requirements] [--in-labels from-diff|none] [--base <branch>] [--state open|closed] [--close-reason completed|not_planned] [--dry-run] [--cwd <path>]
 `;
 
@@ -59,7 +59,7 @@ function oneOf(values: Record<string, string | boolean>, name: string, allowed:
   return value;
 }
 
-function platformIssue(args: string[] = []): void {
+async function platformIssue(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
   if (!operation || !['inspect', 'create', 'bind', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
@@ -75,18 +75,17 @@ function platformIssue(args: string[] = []): void {
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
-  if (operation === 'inspect') { finish(inspectPlatformIssue(taskRef, { cwd })); return; }
+  if (operation === 'inspect') { finish(await inspectPlatformIssue(taskRef, { cwd })); return; }
   if (typeof values.agent !== 'string' || !values.agent) { fail(`${operation} requires --agent`); return; }
   const agent = normalizeAgentToken(values.agent);
   if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
   values.agent = agent;
   if (operation === 'create') {
-    finish(createPlatformIssue(taskRef, { cwd, agent: values.agent, dryRun: values.dryRun === true })); return;
+    finish(await createPlatformIssue(taskRef, { cwd, agent: values.agent, dryRun: values.dryRun === true })); return;
   }
   if (operation === 'bind') {
-    const issue = Number(values.issue);
-    if (!Number.isInteger(issue) || issue <= 0) { fail('bind requires a positive --issue'); return; }
-    finish(bindPlatformIssue(taskRef, { cwd, agent: values.agent, issue, dryRun: values.dryRun === true })); return;
+    if (typeof values.issue !== 'string' || !values.issue) { fail('bind requires --issue <token>'); return; }
+    finish(await bindPlatformIssue(taskRef, { cwd, agent: values.agent, issue: values.issue, dryRun: values.dryRun === true })); return;
   }
   try {
     const assignees = oneOf(values, 'assignees', ['current', 'none']);
@@ -99,7 +98,7 @@ function platformIssue(args: string[] = []): void {
     if (closeReason && state !== 'closed') throw new Error('--close-reason requires --state closed');
     const desiredKeys = ['status', 'assignees', 'milestone', 'issueType', 'fields', 'requirements', 'inLabels', 'state'];
     if (!desiredKeys.some((name) => values[name] !== undefined)) throw new Error('sync requires at least one desired-state option');
-    finish(syncPlatformIssue(taskRef, {
+    finish(await syncPlatformIssue(taskRef, {
       cwd, agent: values.agent, dryRun: values.dryRun === true,
       status: typeof values.status === 'string' ? values.status : undefined,
       assignees: assignees as 'current' | 'none' | undefined,

package/lib/internal/platform-pr-review.ts

@@ -6,9 +6,9 @@ import { listPrReviews, publishPrReview } from '../platform/pr-review.ts';
 import type { PrReviewEvent } from '../platform/pr-review.ts';
 import type { PlatformResult } from '../platform/types.ts';
 
-const USAGE = `Usage: agent-infra-internal platform-pr-review inspect --pr <N> [--cwd <path>]
-       agent-infra-internal platform-pr-review list --pr <N> [--cwd <path>]
-       agent-infra-internal platform-pr-review publish --pr <N> --scope <taskId|pr{N}> --round <N> --commit <sha> --event <COMMENT|APPROVE|REQUEST_CHANGES> --body-file <path|-> [--dry-run] [--cwd <path>]
+const USAGE = `Usage: agent-infra-internal platform-pr-review inspect --pr <token> [--cwd <path>]
+       agent-infra-internal platform-pr-review list --pr <token> [--cwd <path>]
+       agent-infra-internal platform-pr-review publish --pr <token> --scope <taskId|pr{N}> --round <N> --commit <sha> --event <COMMENT|APPROVE|REQUEST_CHANGES> --body-file <path|-> [--dry-run] [--cwd <path>]
 `;
 
 const BOOLEAN_FLAGS = new Set(['--dry-run']);
@@ -50,7 +50,7 @@ function readBodyFile(value: string, cwd: string): string {
   return value === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, value), 'utf8');
 }
 
-function platformPrReview(args: string[] = []): void {
+async function platformPrReview(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
   if (!operation || !['inspect', 'list', 'publish'].includes(operation)) { fail('a valid operation is required'); return; }
@@ -65,14 +65,14 @@ function platformPrReview(args: string[] = []): void {
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
-  const pr = Number(values.pr);
-  if (!Number.isInteger(pr) || pr <= 0) { fail(`${operation} requires a positive --pr`); return; }
+  const pr = values.pr;
+  if (typeof pr !== 'string' || !pr) { fail(`${operation} requires --pr <token>`); return; }
   if (operation === 'inspect') {
-    finish(inspectPlatformPullRequestByNumber(pr, { cwd }));
+    finish(await inspectPlatformPullRequestByNumber(pr, { cwd }));
     return;
   }
   if (operation === 'list') {
-    finish(listPrReviews(pr, { cwd }));
+    finish(await listPrReviews(pr, { cwd }));
     return;
   }
   const scope = typeof values.scope === 'string' ? values.scope : '';
@@ -91,7 +91,7 @@ function platformPrReview(args: string[] = []): void {
     fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
     return;
   }
-  finish(publishPrReview({
+  finish(await publishPrReview({
     cwd,
     prNumber: pr,
     identity: { scope, round, commitSha: commit },