@fitlab-ai/agent-infra 0.9.15 → 0.10.0

package/dist/lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.js

@@ -22,13 +22,14 @@ function copyRegular(source, destination, mode) {
 function controlFromEnvironment() {
     const token = process.env.AGENT_INFRA_CONTROL_TOKEN;
     const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+    const rootId = process.env.AGENT_INFRA_CONTROL_ROOT_ID;
     const channelDir = process.env.AGENT_INFRA_CONTROL_DIR;
     const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
     const runtimeDir = process.env.AGENT_INFRA_RUNTIME_DIR;
-    if (!token || !generation || !channelDir || !statusDir || !runtimeDir) {
+    if (!token || !generation || !rootId || !channelDir || !statusDir || !runtimeDir) {
         throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_MISSING');
     }
-    return { token, generation, channelDir, statusDir, runtimeDir };
+    return { token, generation, rootId, channelDir, statusDir, runtimeDir };
 }
 function verifyRuntime(runtimeDir) {
     let stat;
@@ -188,6 +189,9 @@ function isolatedEnvironment(home, shimDir, contextPath, taskId, control, provid
         AGENT_INFRA_TASK_ID: taskId,
         AGENT_INFRA_CONTROL_TOKEN: control.token,
         AGENT_INFRA_CONTROL_GENERATION: control.generation,
+        ...(control.rootId || sourceEnvironment.AGENT_INFRA_CONTROL_ROOT_ID
+            ? { AGENT_INFRA_CONTROL_ROOT_ID: control.rootId ?? sourceEnvironment.AGENT_INFRA_CONTROL_ROOT_ID }
+            : {}),
         AGENT_INFRA_CONTROL_DIR: control.channelDir,
         AGENT_INFRA_CONTROL_STATUS_DIR: control.statusDir,
         AGENT_INFRA_RUNTIME_DIR: control.runtimeDir,

package/dist/lib/agent-clients/adapters/codex-lifecycle/store.js

@@ -6,9 +6,19 @@ import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.js'
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 1_000;
 const LOCK_STALE_MS = 30_000;
+const RECOVERY_CONSUMER_RE = /^lifecycle-recovery:([^:\r\n]+):([^:\r\n]+)$/u;
 function digest(value) {
     return crypto.createHash('sha256').update(value).digest('hex');
 }
+function isRecoveryConsumer(value) {
+    return RECOVERY_CONSUMER_RE.test(value);
+}
+function recoveryConsumer(taskId, receiptId) {
+    if (!/^[^:\r\n]+$/u.test(taskId) || !/^[^:\r\n]+$/u.test(receiptId)) {
+        throw new Error('Codex lifecycle recovery claim identity is invalid');
+    }
+    return `lifecycle-recovery:${taskId}:${receiptId}`;
+}
 function readRecord(file) {
     const value = JSON.parse(fs.readFileSync(file, 'utf8'));
     if (value.schemaVersion !== 1
@@ -202,11 +212,13 @@ function createCodexLifecycleStore(options) {
     }
     function read(childThreadId) {
         const matches = findByChild(childThreadId);
-        if (matches.length !== 1)
+        if (matches.length === 0)
             throw new Error(`Codex lifecycle child '${childThreadId}' was not found uniquely`);
+        if (matches.length > 1)
+            throw new Error(`Codex lifecycle child '${childThreadId}' is ambiguous`);
         return readRecord(matches[0]);
     }
-    function consume(childThreadId, consumer, expectedHookDefinitionHash) {
+    function consumeInternal(childThreadId, consumer, expectedHookDefinitionHash) {
         if (!consumer.trim())
             throw new Error('Codex lifecycle consumer is required');
         return withWriteLock(() => {
@@ -240,6 +252,32 @@ function createCodexLifecycleStore(options) {
             return next;
         });
     }
+    function consume(childThreadId, consumer, expectedHookDefinitionHash) {
+        if (!consumer.trim())
+            throw new Error('Codex lifecycle consumer is required');
+        if (consumer.startsWith('lifecycle-recovery:')) {
+            throw new Error('Codex lifecycle recovery claims require claimRecovery');
+        }
+        return consumeInternal(childThreadId, consumer, expectedHookDefinitionHash);
+    }
+    function claimRecovery(childThreadId, taskId, receiptId, expectedHookDefinitionHash) {
+        return consumeInternal(childThreadId, recoveryConsumer(taskId, receiptId), expectedHookDefinitionHash);
+    }
+    function releaseRecovery(childThreadId, consumer) {
+        if (!/^lifecycle-recovery:[^:\r\n]+:[^:\r\n]+$/.test(consumer))
+            return false;
+        return withWriteLock(() => {
+            const matches = findByChild(childThreadId);
+            if (matches.length !== 1)
+                return false;
+            const file = matches[0];
+            const current = readRecord(file);
+            if (current.state.status !== 'stop-ready' || current.consumer !== consumer || !current.consumedAt)
+                return false;
+            fs.unlinkSync(file);
+            return true;
+        });
+    }
     function expireBefore(cutoff) {
         return withWriteLock(() => {
             let changed = 0;
@@ -247,6 +285,8 @@ function createCodexLifecycleStore(options) {
                 const current = readRecord(file);
                 if (current.updatedAt >= cutoff)
                     continue;
+                if (current.consumer && isRecoveryConsumer(current.consumer))
+                    continue;
                 if (current.consumer || ['invalid', 'expired', 'stop-ready'].includes(current.state.status)) {
                     fs.unlinkSync(file);
                     changed += 1;
@@ -266,7 +306,7 @@ function createCodexLifecycleStore(options) {
             return changed;
         });
     }
-    return Object.freeze({ root, apply, applyToSpawn, consume, expireBefore, findByParent, read });
+    return Object.freeze({ root, apply, applyToSpawn, consume, claimRecovery, releaseRecovery, expireBefore, findByParent, read });
 }
 export { createCodexLifecycleStore, hasActiveCodexLifecycleEvidence };
 //# sourceMappingURL=store.js.map

package/dist/lib/fs/durable-write.js

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 export function fsyncDirectory(directory) {
+    if (process.platform === 'win32')
+        return;
     const descriptor = fs.openSync(directory, 'r');
     try {
         fs.fsyncSync(descriptor);

package/dist/lib/internal/cli-route-inventory.js

@@ -54,7 +54,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
     'task-ledger': ['decision-next-id', 'stage-status', 'finding-upsert', 'finding-respond', 'finding-review', 'decision-upsert', 'rework-intent-upsert'],
     'task-warning': ['list', 'add', 'set-status'],
     'task-activity': ['pr-review-inspect', 'pr-review-start', 'pr-review-complete', 'pr-review-terminate'],
-    'task-artifact': ['inspect', 'init', 'repair', 'finalize-local'],
+    'task-artifact': ['inspect', 'init', 'finalize-local'],
     'task-orchestration': ['status', 'progress'],
     'task-review': ['finalize-summary'],
     'task-event': ['event'],

package/dist/lib/internal/manual-validation.js

@@ -22,15 +22,24 @@ function printFailure(format, error) {
         process.stderr.write(`${error.code}: ${error.message}\n`);
     process.exitCode = 1;
 }
+const MANUAL_VALIDATION_STATUS_SECTION = /^###\s+(?:⚠️\s+(?:需人工校验|Manual Validation Required)|✅\s+(?:人工验证已通过|无需人工校验|Manual Validation Passed|No Manual Validation Required)|⏳\s+(?:人工验证待收尾|Manual Validation Pending))\s*$[\s\S]*?(?=^#{1,3}\s|(?![\s\S]))/gmu;
 function manualSummaryBody(body, phase, transactionId, receiptDigest = '', evidenceDigest = '', prHeadSha = '') {
-    const withoutPrevious = body
-        .replace(/^###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)\s*$/gmu, '')
-        .replace(/^###\s+⏳\s+(?:Manual Validation Pending|人工验证待收尾)\s*$/gmu, '')
-        .replace(/Manual validation passed(?:\s+→)?/giu, 'Manual validation pending');
+    const chinese = /###\s+(?:⚠️\s+需人工校验|✅\s+(?:人工验证已通过|无需人工校验)|⏳\s+人工验证待收尾)\s*$/mu.test(body);
     const section = phase === 'pending'
-        ? `### ⏳ Manual Validation Pending\n\nManual validation evidence is staged; transaction ${transactionId} is awaiting final promotion.`
-        : `### ✅ Manual Validation Passed\n\nManual validation passed; transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`;
-    return `${withoutPrevious.replace(/\s+$/u, '')}\n\n${section}\n`;
+        ? chinese
+            ? `### ⏳ 人工验证待收尾\n\n人工验证证据已暂存；事务 ${transactionId} 正在等待最终完成。`
+            : `### ⏳ Manual Validation Pending\n\nManual validation evidence is staged; transaction ${transactionId} is awaiting final promotion.`
+        : chinese
+            ? `### ✅ 人工验证已通过\n\n人工验证已通过；transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`
+            : `### ✅ Manual Validation Passed\n\nManual validation passed; transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`;
+    let inserted = false;
+    const updated = body.replace(MANUAL_VALIDATION_STATUS_SECTION, () => {
+        if (inserted)
+            return '';
+        inserted = true;
+        return `${section}\n\n`;
+    });
+    return inserted ? `${updated.replace(/\s+$/u, '')}\n` : `${body.replace(/\s+$/u, '')}\n\n${section}\n`;
 }
 function openManualValidationStarted(taskMdPath) {
     let content;
@@ -242,7 +251,7 @@ async function executeManualValidationTransactionLocked(taskRef, values, cwd, re
         if (!['applied', 'no-op'].includes(promoted.status))
             transactionFailure(promoted.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'final summary promotion failed' });
         const postWrite = await summaryCommentState(taskRef, { cwd, client: options.client });
-        if (!postWrite.comment?.body.includes('### ✅ Manual Validation Passed') || postWrite.pullRequest?.head.sha !== receipt.prHeadSha || !manualValidationFinalSummaryProjectionMatches(postWrite.comment.body, receipt))
+        if (!/^###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)\s*$/mu.test(postWrite.comment?.body ?? '') || postWrite.pullRequest?.head.sha !== receipt.prHeadSha || !manualValidationFinalSummaryProjectionMatches(postWrite.comment?.body ?? '', receipt))
             transactionFailure({ code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'final summary post-write verification failed' });
         transitionAndPersist('committed', { postWriteVerified: true });
         return result('applied', null, { transaction, receipt, idempotent: false });

package/dist/lib/internal/task-artifact.js

@@ -1,6 +1,6 @@
 import { parseArtifactCommand, executeArtifactCommand } from '../task/artifact-command.js';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.js';
-const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> repair --family <family> --artifact <artifact> --expected-sha256 <sha256> --expected-semantic-digest <digest>\n       agent-infra-internal task-artifact <N | TASK-id> finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, repair, or finalize a workflow artifact without changing task state.\n`;
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> finalize-local --family <analysis|plan|code> --artifact <artifact> [--recovery-id <id>]\n\nInspect, initialize, or finalize a workflow artifact without changing task state.\n`;
 function taskArtifact(args = []) {
     if (!ensureInternalHandlerRoute('task-artifact', args))
         return;

package/dist/lib/internal/task-lifecycle.js

@@ -2,7 +2,7 @@ import { createDirectHostExecutionContext, dispatchTaskControlOperation, parseTa
 import { lifecycleIntentCatalog } from '../task/lifecycle.js';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
-const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nOverride: --override-ticket <ticket> --override-target <target> --override-scope <scope>\n`;
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nrecover-started: --stage <stage> --round <round> --artifact <artifact> --reason <reason>\nOverride: --override-ticket <ticket> --override-target <target> --override-scope <scope>\n`;
 function usageFailure(message) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);
     process.stderr.write(USAGE);
@@ -54,7 +54,7 @@ async function taskLifecycle(args = []) {
     }
     const result = await dispatchTaskControlOperation(createDirectHostExecutionContext({ repoRoot }), operation);
     process.stdout.write(`${JSON.stringify(result)}\n`);
-    if (result.status === 'failed')
+    if (result.status === 'failed' || result.status === 'owner-unknown' || result.status === 'conflict')
         process.exitCode = 1;
 }
 export { taskLifecycle };

package/dist/lib/internal/task-operation-registry.js

@@ -96,7 +96,6 @@ function internalTaskRoutes() {
         descriptor('internal', 'task-activity', 'pr-review-terminate', 'task-bound', 'progress'),
         descriptor('internal', 'task-artifact', 'inspect', 'task-bound', 'diagnostic'),
         descriptor('internal', 'task-artifact', 'init', 'task-bound', 'artifact-write'),
-        descriptor('internal', 'task-artifact', 'repair', 'task-bound', 'artifact-write'),
         descriptor('internal', 'task-artifact', 'finalize-local', 'task-bound', 'artifact-write'),
         descriptor('internal', 'task-orchestration', 'status', 'task-bound', 'diagnostic'),
         descriptor('internal', 'task-orchestration', 'progress', 'task-bound', 'progress'),

package/dist/lib/internal/task-review.js

@@ -4,7 +4,7 @@ import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.js';
-const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--orchestrated] [--dry-run] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
+const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--recovery-id <id>] [--orchestrated] [--dry-run] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 function failUsage(message) {
     process.stdout.write(`${JSON.stringify({
         status: 'failed',
@@ -30,7 +30,7 @@ async function taskReview(args = []) {
         failUsage(error instanceof Error ? error.message : String(error));
         return;
     }
-    const { stage, artifact, dryRun, orchestrated, overrideTicket, overrideTarget, overrideScope } = request;
+    const { stage, artifact, recoveryId, dryRun, orchestrated, overrideTicket, overrideTarget, overrideScope } = request;
     const dryRunConflict = overrideDryRunConflict({ dryRun, overrideTicket, overrideTarget, overrideScope });
     if (dryRunConflict) {
         failUsage(dryRunConflict.message);
@@ -45,7 +45,7 @@ async function taskReview(args = []) {
     let humanOverride = null;
     try {
         result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', async () => {
-            let current = finalizeReviewSummary({ taskRef: args[0], stage, artifact, orchestrated, dryRun }, { lockAlreadyHeld: true });
+            let current = finalizeReviewSummary({ taskRef: args[0], stage, artifact, recoveryId, orchestrated, dryRun }, { lockAlreadyHeld: true });
             if (current.status !== 'failed' || !overrideTicket)
                 return current;
             if (!overrideTarget || !overrideScope) {
@@ -58,7 +58,7 @@ async function taskReview(args = []) {
                 target: overrideTarget, scope: overrideScope
             }, {
                 effectExecutor: (capability) => {
-                    const retried = finalizeReviewSummary({ taskRef: args[0], stage, artifact, orchestrated, dryRun }, { lockAlreadyHeld: true, manualOverride: capability });
+                    const retried = finalizeReviewSummary({ taskRef: args[0], stage, artifact, recoveryId, orchestrated, dryRun }, { lockAlreadyHeld: true, manualOverride: capability });
                     current = retried;
                     return retried.status === 'failed' || retried.status === 'planned'
                         ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no review effect was committed' : `${retried.error?.code ?? 'REVIEW_FAILED'}: ${retried.error?.message ?? 'manual review effect failed'}` }

package/dist/lib/platform/issue-comments.js

@@ -18,6 +18,7 @@ const MARKERS = {
     summary: (taskId) => `<!-- sync-issue:${taskId}:summary -->`,
     cancel: (taskId) => `<!-- sync-issue:${taskId}:cancel -->`
 };
+const COMMENT_BYTE_LIMIT = 60_000;
 const ARTIFACT_TITLES = {
     analysis: '需求分析',
     'review-analysis': '需求分析审查',
@@ -32,6 +33,9 @@ const ARTIFACT_TITLES = {
 function normalizeCommentContent(content) {
     return content.replace(/\r\n/g, '\n').replace(/\n+$/, '\n');
 }
+function isTaskCommentTooLarge(content) {
+    return Buffer.byteLength(content, 'utf8') > COMMENT_BYTE_LIMIT;
+}
 function splitFrontmatter(content) {
     const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
     if (!match)
@@ -219,7 +223,7 @@ function buildArtifactChunk(taskId, stem, title, agent, content, part, total, ch
     return { marker, body, content, part, total };
 }
 function chunkArtifactComment(input) {
-    const byteLimit = input.byteLimit || 60_000;
+    const byteLimit = input.byteLimit || COMMENT_BYTE_LIMIT;
     const identity = artifactIdentity(input.artifact);
     const safeBody = sanitizeCommentBody(input.body, 'artifact body');
     const single = buildArtifactChunk(input.taskId, identity.stem, identity.title, input.agent, safeBody, 1, 1, false, Boolean(input.backfill));
@@ -257,11 +261,6 @@ function flattenComments(value) {
     const flattened = value.flatMap((entry) => Array.isArray(entry) ? entry : [entry]);
     return flattened.filter((entry) => Boolean(entry && typeof entry === 'object' && (typeof entry.id === 'number' || typeof entry.id === 'string') && typeof entry.body === 'string'));
 }
-function issueNumberFromTask(content) {
-    const value = parseTaskFrontmatter(content).issue_number;
-    const number = Number(value);
-    return Number.isInteger(number) && number > 0 ? number : null;
-}
 function listRemoteComments(client, repo, issue, cwd) {
     const result = client.json([
         'api', '--paginate', '--slurp', `repos/${repo}/issues/${issue}/comments?per_page=100`
@@ -374,14 +373,21 @@ async function syncPlatformComment(taskRef, options) {
     const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
     let issueIdentityFromTask;
     try {
-        issueIdentityFromTask = taskIssueIdentity(parseTaskFrontmatter(taskContent), undefined, options.runtimeVersion);
+        issueIdentityFromTask = taskIssueIdentity(parseTaskFrontmatter(taskContent));
     }
     catch (error) {
         return platformResult('failed', { error: { ...taskIssueIdentityError(error), retryable: false } });
     }
     if (!issueIdentityFromTask) {
         return platformResult('no-op', {
-            error: { code: 'ISSUE_NOT_LINKED', message: 'Task has no valid issue_number', retryable: false }
+            error: { code: 'ISSUE_NOT_LINKED', message: 'Task has no valid platform issue identity', retryable: false }
+        });
+    }
+    if (options.kind === 'task' && isTaskCommentTooLarge(taskContent)) {
+        return platformResult('no-op', {
+            resource: { kind: 'issue', number: resourceIdentityNumber(issueIdentityFromTask), identity: issueIdentityFromTask },
+            operations: [{ name: `comment:${MARKERS.task(resolved.taskId)}`, status: 'skipped', reasonCode: 'COMMENT_PAYLOAD_TOO_LARGE' }],
+            error: null
         });
     }
     let desired;
@@ -541,7 +547,7 @@ async function checkPlatformCommentOwner(taskRef, options = {}) {
     const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
     let issueIdentity;
     try {
-        issueIdentity = taskIssueIdentity(parseTaskFrontmatter(content), undefined, options.runtimeVersion);
+        issueIdentity = taskIssueIdentity(parseTaskFrontmatter(content));
     }
     catch (error) {
         return platformResult('failed', { error: { ...taskIssueIdentityError(error), retryable: false } });
@@ -572,5 +578,5 @@ async function checkPlatformCommentOwner(taskRef, options = {}) {
     }
     return platformResult('no-op', { ...contextFields(context), resource: { kind: 'issue', number: resourceIdentityNumber(issueIdentity), identity: issueIdentity }, error: null });
 }
-export { MARKERS, chunkArtifactComment, findMarkerComments, listRemoteComments, checkPlatformCommentOwner, listPlatformComments, normalizeCommentContent, renderTaskComment, syncPlatformComment, validateRelatedMarkerSet, writeComment };
+export { COMMENT_BYTE_LIMIT, MARKERS, chunkArtifactComment, findMarkerComments, listRemoteComments, checkPlatformCommentOwner, listPlatformComments, normalizeCommentContent, renderTaskComment, isTaskCommentTooLarge, syncPlatformComment, validateRelatedMarkerSet, writeComment };
 //# sourceMappingURL=issue-comments.js.map

package/dist/lib/platform/issues.js

@@ -32,7 +32,7 @@ async function resolvedContext(taskRef, options) {
     const frontmatter = parseTaskFrontmatter(content);
     let issueIdentity;
     try {
-        issueIdentity = taskIssueIdentity(frontmatter, undefined, options.runtimeVersion);
+        issueIdentity = taskIssueIdentity(frontmatter);
     }
     catch (error) {
         return { ok: false, output: result('failed', resolved.taskId, null, { error: { ...taskIssueIdentityError(error), retryable: false } }) };

package/dist/lib/platform/pr-change-report.js

@@ -3,8 +3,9 @@ import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { escapeHtmlText } from './comment-safety.js';
+import { isResourceIdentity } from './resource-identity.js';
 const REPORT_FILE_NAME = 'pr-change-report.json';
-const REPORT_VERSION = 1;
+const REPORT_VERSION = 2;
 const CANONICAL_REPORT_PLACEHOLDER = '<!-- canonical-pr-change-report -->';
 const CANONICAL_REPORT_HEADING = '### PR 代码增减';
 const PRECHECK_IDS = [
@@ -211,8 +212,8 @@ function validatePrChangeReport(value) {
     }
     const identity = value.identity;
     const identityRepository = identity.repository;
-    const identityNumber = identity.number;
-    if (!isNonEmptyString(identityRepository) || typeof identityNumber !== 'number' || !Number.isSafeInteger(identityNumber) || identityNumber <= 0)
+    const identityResource = identity.resource;
+    if (!isNonEmptyString(identityRepository) || !isResourceIdentity(identityResource))
         return invalid('change report identity is invalid');
     const parseIdentityPart = (part, name) => {
         if (!isRecord(part) || !isNonEmptyString(part.repository) || !isNonEmptyString(part.ref) || !isSha(part.sha))
@@ -259,7 +260,7 @@ function validatePrChangeReport(value) {
             version: REPORT_VERSION,
             identity: {
                 repository: identityRepository,
-                number: identityNumber,
+                resource: identityResource,
                 base: base.value,
                 head: head.value
             },

package/dist/lib/platform/pr-summary.js

@@ -11,6 +11,7 @@ import { normalizeCommentContent } from './issue-comments.js';
 import { CONTROL_MARKER_PATTERN, escapeHtmlText, sanitizeMarkdownDocument, splitDocumentPlaceholder } from './comment-safety.js';
 import { platformResult } from './types.js';
 import { providerError, providerOperationContext, providerStatus, providerResourceToken, resourceIdentityNumber, unsupportedProviderOperation } from './provider-bridge.js';
+import { resourceIdentityEquals } from './resource-identity.js';
 import { buildPrChangeReport, CANONICAL_REPORT_PLACEHOLDER, readPrChangeReport, replaceCanonicalReportPlaceholder, runMechanicalChangeReport, taskIntentDigest, validateMechanicalReport, validatePrecheckCandidate, writePrChangeReportAtomic } from './pr-change-report.js';
 import { manualValidationFinalSummaryProjectionMatches } from '../task/manual-validation-receipt.js';
 import { readManualValidationCompletion } from '../task/manual-validation-completion.js';
@@ -48,7 +49,8 @@ function readBoundTaskSnapshot(taskMdPath) {
     const frontmatter = parseTypedTaskFrontmatter(taskContent);
     const fact = readPrDeliveryFact(frontmatter);
     const boundFact = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact : null;
-    return { taskContent, boundFact };
+    const factError = fact.status === 'invalid' ? { code: fact.error.code, message: fact.error.message } : null;
+    return { taskContent, boundFact, factError };
 }
 function boundPrNumberForWarning(taskMdPath) {
     try {
@@ -117,7 +119,7 @@ function isHardSummaryFailure(error) {
 function inspectionError(error) {
     return error.retryable ? 'blocked' : 'failed';
 }
-async function inspectBoundPullRequest(context, repoRoot, prNumber, loadedContext) {
+async function inspectBoundPullRequest(context, repoRoot, prIdentity, loadedContext) {
     if (!context.platform.repository) {
         return { ok: false, status: context.status, error: context.error };
     }
@@ -126,16 +128,15 @@ async function inspectBoundPullRequest(context, repoRoot, prNumber, loadedContex
         : await resolvePlatformProviderContext({ cwd: repoRoot });
     if (!loaded.ok)
         return { ok: false, status: loaded.context.status, error: loaded.context.error };
-    const target = providerResourceToken(loaded.value.provider, 'pull-request', String(prNumber));
     const inspected = loaded.value.provider.changeRequests?.inspect
-        ? await loaded.value.provider.changeRequests.inspect({ context: providerOperationContext(loaded.value), target })
+        ? await loaded.value.provider.changeRequests.inspect({ context: providerOperationContext(loaded.value), target: prIdentity })
         : unsupportedProviderOperation(loaded.value.provider, 'changeRequests.inspect');
     if (!inspected.ok) {
         const error = providerError(inspected.error, 'PLATFORM_PROVIDER_OPERATION_FAILED');
         return { ok: false, status: inspectionError(error), error };
     }
     const remote = inspected.value;
-    const number = remote.number ?? resourceIdentityNumber(remote.identity) ?? prNumber;
+    const number = remote.number ?? resourceIdentityNumber(remote.identity) ?? resourceIdentityNumber(prIdentity) ?? 0;
     const head = remote.head || { repository: context.platform.repository, ref: '', sha: remote.headSha || '' };
     const base = remote.base || { repository: context.platform.repository, ref: '', sha: remote.baseSha || '' };
     return {
@@ -143,6 +144,7 @@ async function inspectBoundPullRequest(context, repoRoot, prNumber, loadedContex
         value: {
             repository: context.platform.repository,
             number,
+            identity: remote.identity ?? prIdentity,
             nodeId: remote.id,
             url: remote.displayUrl || '',
             state: remote.state === 'closed' ? 'closed' : 'open',
@@ -163,20 +165,22 @@ async function inspectBoundPullRequest(context, repoRoot, prNumber, loadedContex
 function sameIdentity(left, right) {
     return JSON.stringify({
         repository: left.repository,
-        number: left.number,
+        identity: left.identity ?? null,
         base: left.base,
         head: left.head
     }) === JSON.stringify({
         repository: right.repository,
-        number: right.number,
+        identity: right.identity ?? null,
         base: right.base,
         head: right.head
     });
 }
 function identityFromSnapshot(snapshot) {
+    if (!snapshot.identity)
+        throw new Error('pull-request snapshot has no canonical identity');
     return {
         repository: snapshot.repository,
-        number: snapshot.number,
+        resource: snapshot.identity,
         base: { ...snapshot.base },
         head: { ...snapshot.head }
     };
@@ -205,7 +209,7 @@ function currentReportCheck(report, snapshot, taskContent, repoRoot) {
     if (!digest.ok)
         return { ok: false, error: platformError(digest.error) };
     const reportIdentity = report.identity;
-    if (reportIdentity.repository !== snapshot.repository || reportIdentity.number !== snapshot.number ||
+    if (reportIdentity.repository !== snapshot.repository || !resourceIdentityEquals(reportIdentity.resource, snapshot.identity) ||
         JSON.stringify(reportIdentity.base) !== JSON.stringify(snapshot.base) || JSON.stringify(reportIdentity.head) !== JSON.stringify(snapshot.head))
         return {
             ok: false,
@@ -263,14 +267,23 @@ async function summaryContext(taskRef, options = {}) {
         };
     const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
     const frontmatter = parseTypedTaskFrontmatter(taskContent);
-    const fact = readPrDeliveryFact(frontmatter, options.runtimeVersion);
-    const prNumber = fact.status === 'valid' && fact.fact.state === 'bound' ? resourceIdentityNumber(fact.fact.identity.resource) : null;
     const reportPath = taskReportPath(resolved.taskDir);
+    const fact = readPrDeliveryFact(frontmatter, options.runtimeVersion);
+    if (fact.status === 'invalid')
+        return {
+            ...platformResult('failed', { error: { code: fact.error.code, message: fact.error.message, retryable: false } }),
+            task: { id: resolved.taskId, prNumber: null },
+            pullRequest: null,
+            changeReport: { status: 'invalid', path: reportPath, taskIntentSha256: null, reason: fact.error.message },
+            artifacts: []
+        };
+    const prIdentity = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
+    const prNumber = resourceIdentityNumber(prIdentity);
     const loaded = await resolvePlatformProviderContext({ cwd: resolved.repoRoot, client: options.client });
     const context = loaded.ok ? loaded.value.context : loaded.context;
     let pullRequest = null;
-    if (loaded.ok && prNumber && context.platform.repository && ['no-op', 'degraded'].includes(context.status)) {
-        const inspected = await inspectBoundPullRequest(context, resolved.repoRoot, prNumber, loaded.value);
+    if (loaded.ok && prIdentity && context.platform.repository && ['no-op', 'degraded'].includes(context.status)) {
+        const inspected = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
         if (inspected.ok)
             pullRequest = inspected.value;
     }
@@ -290,14 +303,15 @@ async function summaryContext(taskRef, options = {}) {
 }
 async function summaryCommentState(taskRef, options = {}) {
     const context = await summaryContext(taskRef, options);
-    if (!context.task.prNumber || !context.pullRequest)
+    const prIdentity = context.pullRequest?.identity;
+    if (!prIdentity)
         return { ...context, comment: null };
     const loaded = await resolvePlatformProviderContext({ cwd: options.cwd, client: options.client });
     if (!loaded.ok || !loaded.value.provider.comments?.list)
         return { ...context, comment: null };
     const listed = await loaded.value.provider.comments.list({
         context: providerOperationContext(loaded.value),
-        parent: providerResourceToken(loaded.value.provider, 'pull-request', String(context.task.prNumber))
+        parent: prIdentity
     });
     if (!listed.ok)
         return { ...context, comment: null };
@@ -311,6 +325,21 @@ async function reportWrite(taskRef, options) {
     const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
     if (!resolved.ok)
         return { ...platformResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }), report: null };
+    let preflight;
+    try {
+        preflight = readBoundTaskSnapshot(resolved.taskMdPath);
+    }
+    catch (error) {
+        return {
+            ...platformResult('failed', { error: { code: 'PR_CHANGE_REPORT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false } }),
+            report: null
+        };
+    }
+    if (preflight.factError)
+        return {
+            ...platformResult('failed', { error: { code: preflight.factError.code, message: preflight.factError.message, retryable: false } }),
+            report: null
+        };
     const loaded = await resolvePlatformProviderContext({ cwd: resolved.repoRoot, client: options.client });
     const context = loaded.ok ? loaded.value.context : loaded.context;
     if (!loaded.ok || !context.platform.repository || !['no-op', 'degraded'].includes(context.status))
@@ -318,20 +347,21 @@ async function reportWrite(taskRef, options) {
     let knownPrNumber = null;
     try {
         return await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, options.agent, async () => {
-            const { taskContent, boundFact } = readBoundTaskSnapshot(resolved.taskMdPath);
-            if (!boundFact)
+            const { taskContent, boundFact, factError } = readBoundTaskSnapshot(resolved.taskMdPath);
+            if (factError)
                 return {
-                    ...basePlatformResult('failed', context, resolved.taskId, null, { code: 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false }),
+                    ...basePlatformResult('failed', context, resolved.taskId, null, { code: factError.code, message: factError.message, retryable: false }),
                     report: null
                 };
-            const boundPrNumber = resourceIdentityNumber(boundFact.identity.resource);
-            if (!boundPrNumber)
+            if (!boundFact)
                 return {
-                    ...basePlatformResult('failed', context, resolved.taskId, null, { code: 'PR_NUMBER_INVALID', message: 'Bound pull request has no numeric identifier', retryable: false }),
+                    ...basePlatformResult('failed', context, resolved.taskId, null, { code: 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false }),
                     report: null
                 };
+            const boundPrIdentity = boundFact.identity.resource;
+            const boundPrNumber = resourceIdentityNumber(boundPrIdentity);
             knownPrNumber = boundPrNumber;
-            const initial = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
+            const initial = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrIdentity, loaded.value);
             if (!initial.ok)
                 return { ...basePlatformResult(initial.status, context, resolved.taskId, boundPrNumber, initial.error), report: null };
             const digest = taskIntentDigest(taskContent);
@@ -364,7 +394,7 @@ async function reportWrite(taskRef, options) {
             const built = buildPrChangeReport(identityFromSnapshot(initial.value), digest.value.sha256, mechanical.value, candidate.value);
             if (!built.ok)
                 return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, platformError(built.error)), report: null };
-            const final = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
+            const final = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrIdentity, loaded.value);
             if (!final.ok)
                 return { ...basePlatformResult(final.status, context, resolved.taskId, boundPrNumber, final.error), report: null };
             if (!sameIdentity(initial.value, final.value))
@@ -466,7 +496,12 @@ async function syncPullRequestSummary(taskRef, options) {
     }
     try {
         const execute = async () => {
-            const { taskContent, boundFact } = readBoundTaskSnapshot(resolved.taskMdPath);
+            const { taskContent, boundFact, factError } = readBoundTaskSnapshot(resolved.taskMdPath);
+            if (factError)
+                return {
+                    ...platformResult('failed', { resource: { kind: 'pull-request', number: null }, error: { code: factError.code, message: factError.message, retryable: false } }),
+                    result: null, warnings: []
+                };
             if (!boundFact)
                 return {
                     ...platformResult('failed', { resource: { kind: 'pull-request', number: null }, error: { code: 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false } }),
@@ -474,14 +509,9 @@ async function syncPullRequestSummary(taskRef, options) {
                 };
             const prIdentity = boundFact.identity.resource;
             const boundPrNumber = resourceIdentityNumber(prIdentity);
-            if (!boundPrNumber)
-                return {
-                    ...platformResult('failed', { resource: { kind: 'pull-request', number: null }, error: { code: 'PR_NUMBER_INVALID', message: 'Bound pull request has no numeric identifier', retryable: false } }),
-                    result: null, warnings: []
-                };
             knownPrNumber = boundPrNumber;
             const prNumber = boundPrNumber;
-            const initial = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
+            const initial = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
             if (!initial.ok)
                 return fail(initial.status, context, initial.error);
             const manual = options.manualValidation;
@@ -491,6 +521,8 @@ async function syncPullRequestSummary(taskRef, options) {
             if (manual && (manual.phase === 'pending' ? hasFinalManualValidation : !hasFinalManualValidation))
                 return fail('failed', context, { code: 'MANUAL_VALIDATION_SUMMARY_PHASE_INVALID', message: 'manual-validation summary phase does not match the requested writer phase', retryable: false }, prNumber);
             if (manual) {
+                if (prNumber === null)
+                    return fail('failed', context, { code: 'MANUAL_VALIDATION_PR_NUMBER_REQUIRED', message: 'manual-validation summary requires a numeric pull-request identity', retryable: false }, prNumber);
                 if (manual.phase === 'final' && (!manual.transactionId || !manual.receiptDigest || !manual.prHeadSha || manual.prHeadSha !== initial.value.head.sha))
                     return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'final manual-validation summary requires transaction, receipt, and current head identity', retryable: false }, prNumber);
                 if (manual.phase === 'final') {
@@ -570,7 +602,7 @@ async function syncPullRequestSummary(taskRef, options) {
                 ? listed.value.find((comment) => comment.id === reconciliation.commentId)?.body ?? null
                 : null;
             const info = { precheckVerdict: report.value.precheck.verdict, nextAction: report.value.precheck.route };
-            const beforeWrite = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
+            const beforeWrite = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
             if (!beforeWrite.ok)
                 return fail(beforeWrite.status, context, beforeWrite.error, prNumber);
             if (!sameIdentity(initial.value, beforeWrite.value))
@@ -605,7 +637,7 @@ async function syncPullRequestSummary(taskRef, options) {
                 : unsupportedProviderOperation(loaded.value.provider, 'comments.write');
             if (!written.ok)
                 return fail(providerStatus(written.error) === 'blocked' ? 'blocked' : 'failed', context, providerError(written.error, 'PLATFORM_PROVIDER_OPERATION_FAILED'), prNumber);
-            const after = await inspectBoundPullRequest(context, resolved.repoRoot, prNumber, loaded.value);
+            const after = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
             const id = /^\d+$/.test(written.value.remoteId) ? Number(written.value.remoteId) : written.value.remoteId;
             const compensateWrittenSummary = async () => reconciliation.action === 'create'
                 ? written.value.remoteId && loaded.value.provider.comments?.delete