@fitlab-ai/agent-infra 0.11.6 → 0.11.8

package/dist/lib/platform/issues.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { buildDefaultBody } from '../task/commands/issue-body.js';
 import { extractTitle, parseTaskFrontmatter } from '../task/frontmatter.js';
@@ -10,10 +11,11 @@ import { writeTask } from '../task/write.js';
 import { resolvePlatformProviderContext } from './context.js';
 import { DEFAULT_REQUIREMENT_SECTION_ANCHORS, chooseMilestone, desiredIssueType, normalizeOption, planIssueMetadata } from './issue-metadata.js';
 import { platformResult } from './types.js';
-import { labelDelta, planInLabelUpdate, syncLabelDelta, validateInLabelMapping, validateRepositoryLabelPayload } from './in-label-sync.js';
+import { labelDelta, inLabelMappingDigest, planInLabelUpdate, syncLabelDelta, validateInLabelMapping, validateRepositoryLabelPayload } from './in-label-sync.js';
 import { providerError, providerOperationContext, providerStatus, providerResourceIdentity, providerResourceToken, unsupportedProviderOperation } from './provider-bridge.js';
 import { resourceIdentityEquals, resourceIdentityNumber, resourceIdentityString, serializeResourceIdentity } from './resource-identity.js';
 import { taskIssueIdentity, taskIssueIdentityError } from './task-identities.js';
+import { coordinatePlatformWrite } from './operation-coordinator.js';
 function result(status, taskId, issueNumber, overrides = {}) {
     return {
         ...platformResult(status),
@@ -247,7 +249,7 @@ async function createPlatformIssue(taskRef, options) {
             platform: base.context.platform, capabilities: base.context.capabilities,
             operations: [{ name: 'issue:create', status: 'planned', reasonCode: null }], error: null
         });
-    {
+    const execute = async () => {
         const created = base.provider.issues?.create
             ? await base.provider.issues.create({
                 context: providerOperationContext(base.loadedContext),
@@ -290,7 +292,7 @@ async function createPlatformIssue(taskRef, options) {
             return result('failed', base.resolved.taskId, null, {
                 platform: base.context.platform, capabilities: base.context.capabilities,
                 resource: { kind: 'issue', number: issueNumber, identity: inspected.value.identity || createdIdentity },
-                error: { code: 'ISSUE_CREATED_BIND_FAILED', message: written.error.message, retryable: false }
+                error: { code: 'ISSUE_CREATED_BIND_FAILED', message: written.error.message, retryable: true }
             });
         return result('applied', base.resolved.taskId, issueNumber, {
             changed: true,
@@ -301,7 +303,26 @@ async function createPlatformIssue(taskRef, options) {
             issue: normalizeProviderIssue(inspected.value, repository, issueNumber),
             error: null
         });
-    }
+    };
+    const issueCreate = { title: payload.title, bodyDigest: createHash('sha256').update(payload.body).digest('hex') };
+    const operation = {
+        kind: 'issue-create',
+        target: `task:${base.resolved.taskId}`,
+        expectedDigest: createHash('sha256').update(JSON.stringify({
+            taskId: base.resolved.taskId,
+            title: payload.title,
+            body: createHash('sha256').update(payload.body).digest('hex'),
+            labels: payload.labels || [], assignees: payload.assignees,
+            milestone: typeof payload.milestone === 'string' ? payload.milestone : null
+        })).digest('hex')
+    };
+    return coordinatePlatformWrite({
+        operation: { taskRef: base.resolved.taskId, cwd: base.resolved.repoRoot, ...operation, issueCreate, dependency: 'required' },
+        agent: options.agent,
+        execute,
+        block: (error) => result('blocked', base.resolved.taskId, null, { platform: base.context.platform, capabilities: base.context.capabilities, error }),
+        persistenceFailure: (error) => result('failed', base.resolved.taskId, null, { error })
+    });
 }
 async function bindPlatformIssue(taskRef, options) {
     const base = await resolvedContext(taskRef, options);
@@ -435,7 +456,7 @@ function desiredFieldValues(frontmatter, fields) {
     }
     return desired;
 }
-async function syncPlatformIssue(taskRef, options) {
+async function syncPlatformIssueImpl(taskRef, options) {
     const base = await resolvedContext(taskRef, options);
     if (!base.ok)
         return base.output;
@@ -582,5 +603,84 @@ async function syncPlatformIssue(taskRef, options) {
         operations: plan.operations.map((operation) => operation.status === 'planned' ? { ...operation, status: 'applied' } : operation), error: null
     });
 }
+async function syncPlatformIssue(taskRef, options) {
+    const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+    if (!resolved.ok || options.dryRun)
+        return syncPlatformIssueImpl(taskRef, options);
+    let frontmatter;
+    let taskContent;
+    try {
+        taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+        frontmatter = parseTaskFrontmatter(taskContent);
+    }
+    catch {
+        return syncPlatformIssueImpl(taskRef, options);
+    }
+    const identity = taskIssueIdentity(frontmatter);
+    if (!identity || ![
+        options.requirements, options.issueType, options.fields, options.status !== undefined,
+        options.assignees !== undefined, options.milestone !== undefined,
+        options.inLabels !== undefined, options.state !== undefined
+    ].some(Boolean))
+        return syncPlatformIssueImpl(taskRef, options);
+    let fromDiffFiles;
+    let mappingDigest;
+    if (options.inLabels === 'from-diff') {
+        const taskBase = typeof frontmatter.delivery_base_ref === 'string' ? frontmatter.delivery_base_ref.trim() : '';
+        if (taskBase && (!options.base || options.base === taskBase)) {
+            try {
+                fromDiffFiles = execFileSync('git', ['diff', `${taskBase}...HEAD`, '--name-only'], {
+                    cwd: resolved.repoRoot, encoding: 'utf8'
+                }).trim().split(/\r?\n/).filter(Boolean).sort();
+                const config = JSON.parse(fs.readFileSync(path.join(resolved.repoRoot, '.agents', '.airc.json'), 'utf8'));
+                const mapping = inLabelMappingDigest(config.labels?.in);
+                if (!mapping.ok)
+                    return result('failed', resolved.taskId, resourceIdentityNumber(identity), {
+                        error: { code: mapping.error.code, message: mapping.error.message, retryable: false }
+                    });
+                mappingDigest = mapping.digest;
+            }
+            catch {
+                return result('failed', resolved.taskId, resourceIdentityNumber(identity), {
+                    error: { code: 'IN_LABEL_SYNC_EVIDENCE_UNAVAILABLE', message: 'Unable to derive the current changed-file set for Issue metadata recovery', retryable: false }
+                });
+            }
+        }
+    }
+    const issueMetadata = {
+        requirements: options.requirements === true,
+        issueType: options.issueType === true,
+        fields: options.fields === true,
+        ...(options.status !== undefined ? { status: options.status } : {}),
+        ...(options.assignees !== undefined ? { assignees: options.assignees } : {}),
+        ...(options.milestone !== undefined ? { milestone: options.milestone } : {}),
+        ...(options.inLabels ? { inLabels: options.inLabels } : {}),
+        ...(options.base ? { base: options.base } : {}),
+        ...(fromDiffFiles ? { fromDiffFiles } : {}),
+        ...(mappingDigest ? { inLabelMappingDigest: mappingDigest } : {}),
+        ...(options.state ? { state: options.state } : {}),
+        ...(options.closeReason ? { closeReason: options.closeReason } : {})
+    };
+    const operation = {
+        kind: 'issue-metadata',
+        target: JSON.stringify(identity),
+        expectedDigest: createHash('sha256').update(JSON.stringify({
+            ...issueMetadata,
+            task: resolved.taskId,
+            taskContent: createHash('sha256').update(taskContent).digest('hex')
+        })).digest('hex')
+    };
+    const dependency = options.dependency ?? (options.state === 'closed' && options.closeReason === 'not_planned' ? 'required' : 'deferred');
+    const execute = () => syncPlatformIssueImpl(taskRef, options);
+    if (options.skipQueue)
+        return execute();
+    return coordinatePlatformWrite({
+        operation: { taskRef: resolved.taskId, cwd: resolved.repoRoot, ...operation, issueMetadata, dependency },
+        agent: options.agent,
+        execute,
+        block: (error) => result('blocked', resolved.taskId, resourceIdentityNumber(identity), { error }),
+        persistenceFailure: (error) => result('failed', resolved.taskId, resourceIdentityNumber(identity), { error })
+    });
+}
 export { bindPlatformIssue, createPlatformIssue, inspectPlatformIssue, requirementSectionAnchors, syncPlatformIssue };
 //# sourceMappingURL=issues.js.map

package/dist/lib/platform/operation-coordinator.js

@@ -0,0 +1,74 @@
+import { recoverPlatformOperations } from '../task/platform-operation-recovery.js';
+import { recordPlatformOperation } from '../task/platform-operation-journal.js';
+async function coordinatePlatformWrite(input) {
+    let operationId;
+    try {
+        const queued = recordPlatformOperation({ ...input.operation, state: 'queued' });
+        operationId = queued.id;
+    }
+    catch (error) {
+        const value = error;
+        return input.persistenceFailure({
+            code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED',
+            message: value.message || 'Unable to queue platform operation',
+            retryable: true
+        });
+    }
+    const selection = input.operation.kind === 'issue-metadata' && input.operation.issueMetadata?.state === 'closed'
+        ? 'all' : input.operation.dependency;
+    const drained = input.drain
+        ? await input.drain(input.operation.taskRef, operationId, input.agent, input.operation.cwd)
+        : await recoverPlatformOperations(input.operation.taskRef, selection, {
+            agent: input.agent,
+            client: input.client,
+            cwd: input.operation.cwd,
+            excludeId: operationId
+        });
+    if (drained.status !== 'applied' && drained.status !== 'no-op') {
+        return input.block(drained.error ?? {
+            code: 'PLATFORM_OPERATION_QUEUE_BLOCKED',
+            message: 'A previous platform operation is still unresolved; the current write remains queued',
+            retryable: true
+        });
+    }
+    try {
+        recordPlatformOperation({ ...input.operation, state: 'pending' });
+    }
+    catch (error) {
+        const value = error;
+        return input.persistenceFailure({
+            code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED',
+            message: value.message || 'Unable to mark platform operation as started',
+            retryable: true
+        });
+    }
+    let output;
+    try {
+        output = await input.execute();
+    }
+    catch (error) {
+        const value = error;
+        output = input.block({ code: value.code || 'PLATFORM_WRITE_FAILED', message: value.message || String(error), retryable: true });
+    }
+    const succeeded = (output.status === 'applied' || output.status === 'no-op')
+        && !output.error && !(output.warnings?.length);
+    const state = succeeded ? 'succeeded' : output.status === 'failed' && output.error?.retryable === false ? 'failed' : 'unknown';
+    try {
+        recordPlatformOperation({
+            ...input.operation,
+            state,
+            lastCode: output.error?.code ?? output.warnings?.[0]?.code ?? null
+        });
+    }
+    catch (error) {
+        const value = error;
+        return input.persistenceFailure({
+            code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED',
+            message: value.message || 'Unable to persist platform operation outcome',
+            retryable: true
+        });
+    }
+    return output;
+}
+export { coordinatePlatformWrite };
+//# sourceMappingURL=operation-coordinator.js.map

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

@@ -1,7 +1,12 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { coordinatePlatformWrite } from './operation-coordinator.js';
 import { resolvePlatformProviderContext } from './context.js';
 import { platformResult } from './types.js';
 import { providerError, providerOperationContext, providerStatus, providerResourceToken, unsupportedProviderOperation } from './provider-bridge.js';
-import { isResourceIdentity, resourceIdentityNumber, reviewMarker as resourceReviewMarker } from './resource-identity.js';
+import { isResourceIdentity, resourceIdentityEquals, resourceIdentityNumber, reviewMarker as resourceReviewMarker } from './resource-identity.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
 const REVIEW_EVENTS = ['COMMENT', 'APPROVE', 'REQUEST_CHANGES'];
 // Marker-safe scope: a task id (`TASK-YYYYMMDD-HHMMSS`) or a bare PR number
 // (`pr{N}`). Any other value (e.g. one containing `\r\n` or `-->`) would break
@@ -19,6 +24,34 @@ export function reviewedCommitMarker(sha) {
 function normalizeBody(body) {
     return String(body || '').replace(/\r\n/g, '\n').replace(/\n+$/, '\n');
 }
+function canonicalReviewBody(body) {
+    return normalizeBody(body).replace(/\n$/u, '');
+}
+function reviewArtifactName(round, artifactFile) {
+    return path.basename(artifactFile) === artifactFile
+        && (artifactFile === 'pr-review.md' && round === 1 || artifactFile === `pr-review-r${round}.md`);
+}
+export function readReviewBodyFile(taskRef, round, artifactFile, bodyDigest, cwd) {
+    if (!/^TASK-\d{8}-\d{6}$/u.test(taskRef) || path.basename(artifactFile) !== artifactFile
+        || !reviewArtifactName(round, artifactFile)) {
+        throw Object.assign(new Error('Pull-request review artifact identity is invalid'), { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID' });
+    }
+    const task = resolveTaskRef(taskRef, cwd ? { repoRoot: cwd } : {});
+    if (!task.ok)
+        throw Object.assign(new Error(task.message), { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID' });
+    const bodyFile = artifactFile.replace(/^pr-review/u, 'pr-review-body');
+    const report = fs.readFileSync(path.join(task.taskDir, artifactFile), 'utf8');
+    const bodyReferences = [...report.matchAll(/^\*\*(?:正文文件|Body file)\*\*(?:：|:)\s*`([^`]+)`[^\r\n]*$/gmu)]
+        .map((match) => match[1]);
+    if (bodyReferences.length !== 1 || bodyReferences[0] !== bodyFile) {
+        throw Object.assign(new Error('Pull-request review artifact does not reference its canonical body file'), { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID' });
+    }
+    const body = canonicalReviewBody(fs.readFileSync(path.join(task.taskDir, bodyFile), 'utf8'));
+    if (!body || createHash('sha256').update(body).digest('hex') !== bodyDigest) {
+        throw Object.assign(new Error('Canonical pull-request review body does not match its persisted digest'), { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID' });
+    }
+    return body;
+}
 function firstLine(body) {
     return normalizeBody(String(body || '')).split('\n', 1)[0] || '';
 }
@@ -74,6 +107,13 @@ export async function publishPrReview(options) {
     if (!hasUsableContext(context)) {
         return platformResult(context.status, { platform: context.platform, capabilities: context.capabilities, error: context.error });
     }
+    const providerScopeId = loaded.ok ? loaded.value.snapshot.scope.id : null;
+    if (options.expectedProviderScopeId && providerScopeId !== options.expectedProviderScopeId) {
+        return platformResult('failed', {
+            platform: context.platform, capabilities: context.capabilities,
+            error: { code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Current provider scope differs from the persisted operation target', retryable: false }
+        });
+    }
     const identity = loaded.ok ? (() => { try {
         return providerResourceToken(loaded.value.provider, 'pull-request', String(options.prNumber));
     }
@@ -87,6 +127,13 @@ export async function publishPrReview(options) {
         });
     }
     const identityNumber = resourceIdentityNumber(identity);
+    if (options.expectedResource && !resourceIdentityEquals(identity, options.expectedResource)) {
+        return platformResult('failed', {
+            platform: context.platform, capabilities: context.capabilities,
+            resource: { kind: 'pull-request', number: identityNumber, identity },
+            error: { code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Current pull request identity differs from the persisted operation target', retryable: false }
+        });
+    }
     if (!REVIEW_EVENTS.includes(options.event)) {
         return platformResult('failed', {
             platform: context.platform, capabilities: context.capabilities,
@@ -101,6 +148,65 @@ export async function publishPrReview(options) {
             error: { code: 'REVIEW_IDENTITY_INVALID', message: 'review scope must be a task id or pr{N}; commitSha is required', retryable: false }
         });
     }
+    if (/^TASK-\d{8}-\d{6}$/u.test(options.identity.scope) && !options.skipQueue && !options.dryRun) {
+        if (!options.agent)
+            return platformResult('failed', {
+                platform: context.platform, capabilities: context.capabilities,
+                resource: { kind: 'pull-request', number: identityNumber, identity },
+                error: { code: 'PR_REVIEW_AGENT_REQUIRED', message: 'task-scoped review publication requires an agent token', retryable: false }
+            });
+        if (!options.recoveryArtifact || !reviewArtifactName(options.identity.round, options.recoveryArtifact))
+            return platformResult('failed', {
+                platform: context.platform, capabilities: context.capabilities,
+                resource: { kind: 'pull-request', number: identityNumber, identity },
+                error: { code: 'PR_REVIEW_ARTIFACT_REQUIRED', message: 'task-scoped review publication requires its canonical review artifact', retryable: false }
+            });
+        const body = canonicalReviewBody(options.body);
+        const bodyDigest = createHash('sha256').update(body).digest('hex');
+        try {
+            if (readReviewBodyFile(options.identity.scope, options.identity.round, options.recoveryArtifact, bodyDigest, options.cwd) !== body)
+                throw new Error('body mismatch');
+        }
+        catch {
+            return platformResult('failed', {
+                platform: context.platform, capabilities: context.capabilities,
+                resource: { kind: 'pull-request', number: identityNumber, identity },
+                error: { code: 'PR_REVIEW_ARTIFACT_MISMATCH', message: 'Review body must match the canonical review body file', retryable: false }
+            });
+        }
+        const pullRequestReview = {
+            prNumber: String(options.prNumber),
+            resource: identity,
+            providerScopeId: providerScopeId,
+            scope: options.identity.scope,
+            round: options.identity.round,
+            commitSha: options.identity.commitSha,
+            event: options.event,
+            artifactFile: options.recoveryArtifact,
+            bodyDigest
+        };
+        return coordinatePlatformWrite({
+            operation: {
+                taskRef: options.identity.scope,
+                cwd: options.cwd || process.cwd(),
+                kind: 'pull-request-review',
+                target: JSON.stringify(identity),
+                expectedDigest: createHash('sha256').update(JSON.stringify(pullRequestReview)).digest('hex'),
+                dependency: 'deferred',
+                pullRequestReview
+            },
+            agent: options.agent,
+            execute: () => publishPrReview({ ...options, expectedProviderScopeId: providerScopeId, skipQueue: true }),
+            block: (error) => platformResult('blocked', {
+                platform: context.platform, capabilities: context.capabilities,
+                resource: { kind: 'pull-request', number: identityNumber, identity }, error
+            }),
+            persistenceFailure: (error) => platformResult('failed', {
+                platform: context.platform, capabilities: context.capabilities,
+                resource: { kind: 'pull-request', number: identityNumber, identity }, error
+            })
+        });
+    }
     const marker = reviewMarker({ ...options.identity, resource: identity });
     const listed = await listPrReviews(options.prNumber, { cwd: options.cwd, client: options.client });
     if (listed.status === 'failed' || listed.status === 'blocked')

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

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import { enumerateArtifacts } from '../task/artifacts.js';
 import { parseTypedTaskFrontmatter } from '../task/frontmatter.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
@@ -9,6 +10,7 @@ import { resolvePlatformProviderContext } from './context.js';
 import { normalizeCommentContent } from './issue-comments.js';
 import { CONTROL_MARKER_PATTERN, sanitizeMarkdownDocument, splitDocumentPlaceholder } from './comment-safety.js';
 import { platformResult } from './types.js';
+import { coordinatePlatformWrite } from './operation-coordinator.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';
@@ -609,74 +611,94 @@ async function syncPullRequestSummary(taskRef, options) {
                     operations: [{ name: `summary:${reconciliation.action}`, status: 'planned', reasonCode: null }],
                     result: null, warnings: [], ...info
                 };
-            const existingComment = reconciliation.commentId === null
-                ? undefined
-                : providerResourceToken(loaded.value.provider, 'comment', String(reconciliation.commentId));
-            const written = loaded.value.provider.comments?.write
-                ? await loaded.value.provider.comments.write({
-                    context: providerOperationContext(loaded.value),
-                    parent: prIdentity,
-                    body: desired,
-                    ...(existingComment ? { existingComment } : {}),
-                    mutation: { idempotencyKey: `pr-summary:${resolved.taskId}` }
-                })
-                : 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, 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
-                    ? await loaded.value.provider.comments.delete({
-                        context: providerOperationContext(loaded.value),
-                        parent: prIdentity,
-                        comment: providerResourceToken(loaded.value.provider, 'comment', written.value.remoteId),
-                        mutation: { idempotencyKey: `pr-summary-delete:${resolved.taskId}:${written.value.remoteId}` }
-                    })
-                    : { ok: false, error: { code: 'PR_SUMMARY_RACE_COMPENSATION_FAILED', message: 'Created summary comment has no valid id', retryable: true } }
-                : reconciliation.commentId && previousBody !== null && loaded.value.provider.comments?.write
+            const publish = async () => {
+                const existingComment = reconciliation.commentId === null
+                    ? undefined
+                    : providerResourceToken(loaded.value.provider, 'comment', String(reconciliation.commentId));
+                const written = loaded.value.provider.comments?.write
                     ? await loaded.value.provider.comments.write({
                         context: providerOperationContext(loaded.value),
                         parent: prIdentity,
-                        body: previousBody,
-                        existingComment: providerResourceToken(loaded.value.provider, 'comment', String(reconciliation.commentId)),
-                        mutation: { idempotencyKey: `pr-summary-restore:${resolved.taskId}` }
+                        body: desired,
+                        ...(existingComment ? { existingComment } : {}),
+                        mutation: { idempotencyKey: `pr-summary:${resolved.taskId}` }
                     })
-                    : { ok: false, error: { code: 'PR_SUMMARY_RACE_COMPENSATION_FAILED', message: 'Previous summary body is unavailable for restoration', retryable: true } };
-            if (!after.ok) {
-                const compensated = await compensateWrittenSummary();
-                if (!compensated.ok)
+                    : 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, 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
+                        ? await loaded.value.provider.comments.delete({
+                            context: providerOperationContext(loaded.value),
+                            parent: prIdentity,
+                            comment: providerResourceToken(loaded.value.provider, 'comment', written.value.remoteId),
+                            mutation: { idempotencyKey: `pr-summary-delete:${resolved.taskId}:${written.value.remoteId}` }
+                        })
+                        : { ok: false, error: { code: 'PR_SUMMARY_RACE_COMPENSATION_FAILED', message: 'Created summary comment has no valid id', retryable: true } }
+                    : reconciliation.commentId && previousBody !== null && loaded.value.provider.comments?.write
+                        ? await loaded.value.provider.comments.write({
+                            context: providerOperationContext(loaded.value),
+                            parent: prIdentity,
+                            body: previousBody,
+                            existingComment: providerResourceToken(loaded.value.provider, 'comment', String(reconciliation.commentId)),
+                            mutation: { idempotencyKey: `pr-summary-restore:${resolved.taskId}` }
+                        })
+                        : { ok: false, error: { code: 'PR_SUMMARY_RACE_COMPENSATION_FAILED', message: 'Previous summary body is unavailable for restoration', retryable: true } };
+                if (!after.ok) {
+                    const compensated = await compensateWrittenSummary();
+                    if (!compensated.ok)
+                        return fail('blocked', context, {
+                            code: 'PR_SUMMARY_RACE_COMPENSATION_FAILED',
+                            message: `Summary post-write verification failed and compensation failed: ${compensated.error.message}`,
+                            retryable: true
+                        }, prNumber);
                     return fail('blocked', context, {
-                        code: 'PR_SUMMARY_RACE_COMPENSATION_FAILED',
-                        message: `Summary post-write verification failed and compensation failed: ${compensated.error.message}`,
+                        code: 'PR_SUMMARY_POSTWRITE_VERIFY_FAILED',
+                        message: `Summary was written but pull-request verification failed: ${after.error?.message || 'unknown verification error'}; the previous summary was restored or the new comment was deleted`,
                         retryable: true
                     }, prNumber);
-                return fail('blocked', context, {
-                    code: 'PR_SUMMARY_POSTWRITE_VERIFY_FAILED',
-                    message: `Summary was written but pull-request verification failed: ${after.error?.message || 'unknown verification error'}; the previous summary was restored or the new comment was deleted`,
-                    retryable: true
-                }, prNumber);
-            }
-            if (!sameIdentity(initial.value, after.value)) {
-                const compensated = await compensateWrittenSummary();
-                if (!compensated.ok)
+                }
+                if (!sameIdentity(initial.value, after.value)) {
+                    const compensated = await compensateWrittenSummary();
+                    if (!compensated.ok)
+                        return fail('blocked', context, {
+                            code: 'PR_SUMMARY_RACE_COMPENSATION_FAILED',
+                            message: `Pull-request head changed and summary compensation failed: ${compensated.error.message}`,
+                            retryable: true
+                        }, prNumber);
                     return fail('blocked', context, {
-                        code: 'PR_SUMMARY_RACE_COMPENSATION_FAILED',
-                        message: `Pull-request head changed and summary compensation failed: ${compensated.error.message}`,
+                        code: 'PR_SUMMARY_HEAD_RACE',
+                        message: 'Pull-request head changed while publishing; the previous summary was restored or the new comment was deleted; rerun report and summary sync',
                         retryable: true
                     }, prNumber);
-                return fail('blocked', context, {
-                    code: 'PR_SUMMARY_HEAD_RACE',
-                    message: 'Pull-request head changed while publishing; the previous summary was restored or the new comment was deleted; rerun report and summary sync',
-                    retryable: true
-                }, prNumber);
-            }
-            return {
-                ...basePlatformResult('applied', context, resolved.taskId, prNumber),
-                comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: Number.isInteger(id) ? [id] : [], parts: 1 },
-                operations: [{ name: `summary:${reconciliation.action}`, status: 'applied', reasonCode: null }],
-                result: null, warnings: [], ...info
+                }
+                return {
+                    ...basePlatformResult('applied', context, resolved.taskId, prNumber),
+                    comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: Number.isInteger(id) ? [id] : [], parts: 1 },
+                    operations: [{ name: `summary:${reconciliation.action}`, status: 'applied', reasonCode: null }],
+                    result: null, warnings: [], ...info
+                };
+            };
+            const operation = {
+                taskRef: resolved.taskId,
+                cwd: resolved.repoRoot,
+                kind: 'pull-request-summary',
+                target: JSON.stringify(prIdentity),
+                expectedDigest: createHash('sha256').update(desired).digest('hex'),
+                dependency: 'deferred',
+                pullRequestSummary: { body: options.body, changeReportFile: options.changeReportFile }
             };
+            if (options.skipQueue)
+                return publish();
+            return coordinatePlatformWrite({
+                operation,
+                agent: options.agent,
+                execute: publish,
+                block: (error) => fail('blocked', context, error, prNumber),
+                persistenceFailure: (error) => fail('failed', context, error, prNumber)
+            });
         };
         return await (options.lockAlreadyHeld
             ? execute()