@fitlab-ai/agent-infra 0.9.12 → 0.9.14

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

@@ -1,14 +1,62 @@
 import fs from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import path from 'node:path';
 import { enumerateArtifacts } from '../task/artifacts.js';
 import { parseTypedTaskFrontmatter } from '../task/frontmatter.js';
 import { renderHumanOverrideAudit } from '../task/human-override.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
-import { resolvePlatformContext } from './context.js';
-import { createGitHubClient } from './github-client.js';
-import { listRemoteComments, normalizeCommentContent, writeComment } from './issue-comments.js';
-import { platformResult } from './types.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
 import { readPrDeliveryFact } from '../task/pr-delivery-fact.js';
+import { resolvePlatformProviderContext } from './context.js';
+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 { buildPrChangeReport, CANONICAL_REPORT_PLACEHOLDER, readPrChangeReport, replaceCanonicalReportPlaceholder, runMechanicalChangeReport, taskIntentDigest, validateMechanicalReport, validatePrecheckCandidate, writePrChangeReportAtomic } from './pr-change-report.js';
+function summaryMarker(taskId) {
+    return `<!-- sync-pr:${taskId}:summary -->`;
+}
+function escapeSummaryAuditText(value) {
+    return escapeHtmlText(value).replace(/\r\n?/g, '\n');
+}
+function renderSummaryAuditLine(value) {
+    const safe = escapeSummaryAuditText(value);
+    const longestRun = Math.max(0, ...(safe.match(/`+/g) || []).map((run) => run.length));
+    const delimiter = '`'.repeat(longestRun + 1);
+    return `${delimiter} ${safe} ${delimiter}`;
+}
+function renderSafeHumanOverrideAudit(value) {
+    const normalized = value.trim().replace(/\r\n?/g, '\n');
+    if (!normalized)
+        return '';
+    const [heading, ...rows] = normalized.split('\n');
+    const safeHeading = heading === '## Human Override Audit' ? heading : renderSummaryAuditLine(heading || '');
+    return [safeHeading, ...rows.map((row) => row ? renderSummaryAuditLine(row) : '')].join('\n');
+}
+function isSafeSummaryEnvelope(value, taskId) {
+    return value.includes(summaryMarker(taskId))
+        && (value.match(/<!--\s*sync-pr:/gi) || []).length === 1
+        && (value.match(/<!--\s*last-commit:/gi) || []).length === 1
+        && !/<!--\s*canonical-pr-change-report\b/i.test(value);
+}
+function taskReportPath(taskDir) {
+    return path.join(taskDir, 'pr-change-report.json');
+}
+function readBoundTaskSnapshot(taskMdPath) {
+    const taskContent = fs.readFileSync(taskMdPath, 'utf8');
+    const frontmatter = parseTypedTaskFrontmatter(taskContent);
+    const fact = readPrDeliveryFact(frontmatter);
+    const boundFact = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact : null;
+    return { taskContent, boundFact };
+}
+function boundPrNumberForWarning(taskMdPath) {
+    try {
+        const { boundFact } = readBoundTaskSnapshot(taskMdPath);
+        return boundFact ? resourceIdentityNumber(boundFact.identity.resource) : null;
+    }
+    catch {
+        return null;
+    }
+}
 function warningResultForPrimary(primaryResult) {
     if (primaryResult === 'pr_created')
         return 'pr_created_with_warnings';
@@ -16,11 +64,11 @@ function warningResultForPrimary(primaryResult) {
         return 'pr_reused_with_warnings';
     return 'no_op_with_warnings';
 }
-function summaryMarker(taskId) {
-    return `<!-- sync-pr:${taskId}:summary -->`;
+function platformError(error) {
+    return { code: error.code, message: error.message, retryable: error.retryable ?? false };
 }
 function buildPullRequestSummary(taskId, body, headSha, humanOverrideAudit = '') {
-    const sections = [body.replace(/\s+$/, ''), humanOverrideAudit.trim()].filter(Boolean).join('\n\n');
+    const sections = [body.replace(/\s+$/, ''), renderSafeHumanOverrideAudit(humanOverrideAudit)].filter(Boolean).join('\n\n');
     return normalizeCommentContent(`${summaryMarker(taskId)}\n<!-- last-commit: ${headSha} -->\n\n${sections}\n`);
 }
 function reconcileSummaryComment(comments, taskId, desired) {
@@ -47,26 +95,308 @@ function canonicalArtifacts(taskDir) {
         if (!current || round > current.round)
             byFamily.set(family, { family, name: artifact.name, path: artifact.path, round });
     }
-    return [...byFamily.values()].map(({ family, name, path }) => ({ family, name, path }));
+    return [...byFamily.values()].map(({ family, name, path: artifactPath }) => ({ family, name, path: artifactPath }));
+}
+function basePlatformResult(status, context, taskId, prNumber, error = null) {
+    return platformResult(status, {
+        platform: context.platform,
+        capabilities: context.capabilities,
+        operations: context.operations,
+        resource: { kind: 'pull-request', number: prNumber },
+        error,
+        ...(taskId ? { task: { id: taskId, prNumber } } : {})
+    });
+}
+function isHardSummaryFailure(error) {
+    return error?.code === 'PR_SUMMARY_HEAD_RACE'
+        || error?.code === 'PR_SUMMARY_POSTWRITE_VERIFY_FAILED'
+        || error?.code === 'PR_SUMMARY_RACE_COMPENSATION_FAILED';
+}
+function inspectionError(error) {
+    return error.retryable ? 'blocked' : 'failed';
+}
+async function inspectBoundPullRequest(context, repoRoot, prNumber, loadedContext) {
+    if (!context.platform.repository) {
+        return { ok: false, status: context.status, error: context.error };
+    }
+    const loaded = loadedContext
+        ? { ok: true, value: loadedContext }
+        : 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 })
+        : 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 head = remote.head || { repository: context.platform.repository, ref: '', sha: remote.headSha || '' };
+    const base = remote.base || { repository: context.platform.repository, ref: '', sha: remote.baseSha || '' };
+    return {
+        ok: true,
+        value: {
+            repository: context.platform.repository,
+            number,
+            nodeId: remote.id,
+            url: remote.displayUrl || '',
+            state: remote.state === 'closed' ? 'closed' : 'open',
+            title: remote.title,
+            body: remote.body,
+            draft: remote.draft ?? false,
+            head: { ...head, sha: remote.headSha || head.sha },
+            base: { ...base, sha: remote.baseSha || base.sha },
+            mergedAt: remote.mergedAt ?? null,
+            mergeCommitSha: remote.mergeCommitSha ?? null,
+            labels: [...(remote.labels || [])].sort(),
+            assignees: [...(remote.assignees || [])].sort(),
+            milestone: remote.milestone ?? null,
+            mergeability: remote.mergeability || { state: 'unknown', detail: null }
+        }
+    };
+}
+function sameIdentity(left, right) {
+    return JSON.stringify({
+        repository: left.repository,
+        number: left.number,
+        base: left.base,
+        head: left.head
+    }) === JSON.stringify({
+        repository: right.repository,
+        number: right.number,
+        base: right.base,
+        head: right.head
+    });
+}
+function identityFromSnapshot(snapshot) {
+    return {
+        repository: snapshot.repository,
+        number: snapshot.number,
+        base: { ...snapshot.base },
+        head: { ...snapshot.head }
+    };
+}
+function readJsonInput(file) {
+    try {
+        return { ok: true, value: JSON.parse(fs.readFileSync(file, 'utf8')) };
+    }
+    catch (error) {
+        const errno = error.code;
+        return {
+            ok: false,
+            error: {
+                code: errno === 'ENOENT' ? 'PR_CHANGE_REPORT_INPUT_MISSING' : 'PR_CHANGE_REPORT_INPUT_INVALID',
+                message: error instanceof Error ? error.message : String(error),
+                retryable: false
+            }
+        };
+    }
+}
+function sameMechanical(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function currentReportCheck(report, snapshot, taskContent, repoRoot) {
+    const digest = taskIntentDigest(taskContent);
+    if (!digest.ok)
+        return { ok: false, error: platformError(digest.error) };
+    const reportIdentity = report.identity;
+    if (reportIdentity.repository !== snapshot.repository || reportIdentity.number !== snapshot.number ||
+        JSON.stringify(reportIdentity.base) !== JSON.stringify(snapshot.base) || JSON.stringify(reportIdentity.head) !== JSON.stringify(snapshot.head))
+        return {
+            ok: false,
+            error: { code: 'PR_CHANGE_REPORT_STALE', message: 'Change report identity does not match the authoritative pull request snapshot', retryable: false }
+        };
+    if (report.inputs.taskIntentSha256 !== digest.value.sha256)
+        return {
+            ok: false,
+            error: { code: 'PR_CHANGE_REPORT_STALE', message: 'Change report task intent digest is stale', retryable: false }
+        };
+    let mechanical;
+    try {
+        mechanical = runMechanicalChangeReport(repoRoot, snapshot.base.sha, snapshot.head.sha);
+    }
+    catch (error) {
+        return { ok: false, error: { code: 'PR_CHANGE_REPORT_GIT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false } };
+    }
+    const reportMechanical = {
+        version: 1,
+        base: snapshot.base.sha,
+        head: snapshot.head.sha,
+        mergeBase: report.diff.mergeBase,
+        patchSha256: report.diff.patchSha256,
+        files: report.diff.files,
+        totals: report.diff.totals
+    };
+    if (!sameMechanical(reportMechanical, mechanical))
+        return {
+            ok: false,
+            error: { code: 'PR_CHANGE_REPORT_STALE', message: 'Change report patch or mechanical statistics are stale', retryable: false }
+        };
+    return { ok: true, digest: digest.value.sha256, mechanical };
+}
+function summaryReportStatus(reportPath, snapshot, taskContent, repoRoot) {
+    const digest = taskIntentDigest(taskContent);
+    if (!digest.ok)
+        return { status: 'invalid', taskIntentSha256: null, reason: digest.error.message };
+    const report = readPrChangeReport(reportPath);
+    if (!report.ok)
+        return { status: report.error.code === 'PR_CHANGE_REPORT_MISSING' ? 'missing' : 'invalid', taskIntentSha256: digest.value.sha256, reason: report.error.message };
+    if (!snapshot)
+        return { status: 'stale', taskIntentSha256: digest.value.sha256, reason: 'No bound pull request snapshot is available' };
+    const checked = currentReportCheck(report.value, snapshot, taskContent, repoRoot);
+    return checked.ok
+        ? { status: 'ready', taskIntentSha256: checked.digest }
+        : { status: checked.error.code === 'PR_CHANGE_REPORT_STALE' ? 'stale' : 'invalid', taskIntentSha256: digest.value.sha256, reason: checked.error.message };
 }
-function summaryContext(taskRef, options = {}) {
+async function summaryContext(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 } }), task: { id: resolved.taskId, prNumber: null }, artifacts: [] };
-    const frontmatter = parseTypedTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8'));
-    const fact = readPrDeliveryFact(frontmatter);
-    const prNumber = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null;
-    return { ...platformResult('no-op'), task: { id: resolved.taskId, prNumber }, artifacts: canonicalArtifacts(resolved.taskDir) };
+        return {
+            ...platformResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }),
+            task: { id: resolved.taskId, prNumber: null }, pullRequest: null,
+            changeReport: { status: 'invalid', path: '', taskIntentSha256: null, reason: resolved.message }, artifacts: []
+        };
+    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 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 (inspected.ok)
+            pullRequest = inspected.value;
+    }
+    const report = summaryReportStatus(reportPath, pullRequest, taskContent, resolved.repoRoot);
+    return {
+        ...platformResult(context.status, {
+            platform: context.platform,
+            capabilities: context.capabilities,
+            operations: context.operations,
+            error: context.error
+        }),
+        task: { id: resolved.taskId, prNumber },
+        pullRequest,
+        changeReport: { status: report.status, path: reportPath, taskIntentSha256: report.taskIntentSha256, ...(report.reason ? { reason: report.reason } : {}) },
+        artifacts: canonicalArtifacts(resolved.taskDir)
+    };
 }
-function syncPullRequestSummary(taskRef, options) {
+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 };
+    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))
+        return { ...context, report: null };
+    let knownPrNumber = null;
+    try {
+        return await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, options.agent, async () => {
+            const { taskContent, boundFact } = readBoundTaskSnapshot(resolved.taskMdPath);
+            if (!boundFact)
+                return {
+                    ...basePlatformResult('failed', context, resolved.taskId, null, { code: 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false }),
+                    report: null
+                };
+            const boundPrNumber = resourceIdentityNumber(boundFact.identity.resource);
+            if (!boundPrNumber)
+                return {
+                    ...basePlatformResult('failed', context, resolved.taskId, null, { code: 'PR_NUMBER_INVALID', message: 'Bound pull request has no numeric identifier', retryable: false }),
+                    report: null
+                };
+            knownPrNumber = boundPrNumber;
+            const initial = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
+            if (!initial.ok)
+                return { ...basePlatformResult(initial.status, context, resolved.taskId, boundPrNumber, initial.error), report: null };
+            const digest = taskIntentDigest(taskContent);
+            if (!digest.ok)
+                return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, platformError(digest.error)), report: null };
+            const mechanicalInput = readJsonInput(path.resolve(resolved.repoRoot, options.mechanicalFile));
+            if (!mechanicalInput.ok)
+                return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, mechanicalInput.error), report: null };
+            const mechanical = validateMechanicalReport(mechanicalInput.value);
+            if (!mechanical.ok)
+                return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, platformError(mechanical.error)), report: null };
+            const candidateInput = readJsonInput(path.resolve(resolved.repoRoot, options.precheckFile));
+            if (!candidateInput.ok)
+                return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, candidateInput.error), report: null };
+            const candidate = validatePrecheckCandidate(candidateInput.value);
+            if (!candidate.ok)
+                return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, platformError(candidate.error)), report: null };
+            let recomputed;
+            try {
+                recomputed = runMechanicalChangeReport(resolved.repoRoot, initial.value.base.sha, initial.value.head.sha);
+            }
+            catch (error) {
+                return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, { code: 'PR_CHANGE_REPORT_GIT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false }), report: null };
+            }
+            if (!sameMechanical(mechanical.value, recomputed))
+                return {
+                    ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, { code: 'PR_CHANGE_REPORT_MECHANICAL_MISMATCH', message: 'Mechanical report input does not match the current complete diff', retryable: false }),
+                    report: null
+                };
+            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);
+            if (!final.ok)
+                return { ...basePlatformResult(final.status, context, resolved.taskId, boundPrNumber, final.error), report: null };
+            if (!sameIdentity(initial.value, final.value))
+                return {
+                    ...basePlatformResult('blocked', context, resolved.taskId, boundPrNumber, { code: 'PR_CHANGE_REPORT_HEAD_RACE', message: 'Pull request identity changed while generating the change report', retryable: true }),
+                    report: null
+                };
+            const target = taskReportPath(resolved.taskDir);
+            const existing = readPrChangeReport(target);
+            const reportInfo = {
+                path: target,
+                precheckVerdict: built.value.precheck.verdict,
+                nextAction: built.value.precheck.route
+            };
+            if (existing.ok && JSON.stringify(existing.value) === JSON.stringify(built.value))
+                return {
+                    ...basePlatformResult('no-op', context, resolved.taskId, boundPrNumber),
+                    report: { ...reportInfo, status: 'no-op' }
+                };
+            if (options.dryRun)
+                return {
+                    ...basePlatformResult('planned', context, resolved.taskId, boundPrNumber),
+                    operations: [{ name: 'change-report:write', status: 'planned', reasonCode: null }],
+                    report: { ...reportInfo, status: 'planned' }
+                };
+            try {
+                writePrChangeReportAtomic(target, built.value);
+            }
+            catch (error) {
+                return { ...basePlatformResult('failed', context, resolved.taskId, boundPrNumber, { code: 'PR_CHANGE_REPORT_WRITE_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false }), report: null };
+            }
+            return {
+                ...basePlatformResult('applied', context, resolved.taskId, boundPrNumber),
+                operations: [{ name: 'change-report:write', status: 'applied', reasonCode: null }],
+                report: { ...reportInfo, status: 'written' }
+            };
+        });
+    }
+    catch (error) {
+        const lockError = error instanceof TaskExecutionLockError
+            ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
+            : { code: 'PR_CHANGE_REPORT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false };
+        return { ...basePlatformResult(lockError.retryable ? 'blocked' : 'failed', context, resolved.taskId, knownPrNumber, lockError), report: null };
+    }
+}
+async function syncPullRequestSummary(taskRef, options) {
     const warningResult = warningResultForPrimary(options.primaryResult);
     let knownPrNumber = null;
     const softenFailure = (output) => {
         const prNumber = output.resource.kind === 'pull-request' && output.resource.number
             ? output.resource.number
             : knownPrNumber;
-        const warning = output.error && prNumber
-            && output.error.code !== 'PR_NOT_LINKED'
+        const warning = output.error && prNumber && output.error.code !== 'PR_NOT_LINKED'
             ? {
                 code: output.error.code,
                 message: output.error.message,
@@ -88,45 +418,206 @@ function syncPullRequestSummary(taskRef, options) {
             }
             : { ...output, result: null, warnings: [] };
     };
+    const preserveFailure = (output) => options.strict
+        ? { ...output, result: null, warnings: [] }
+        : softenFailure(output);
     const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
     if (!resolved.ok)
         return softenFailure(platformResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }));
+    const fail = (status, context, error, prNumber = knownPrNumber) => {
+        const output = basePlatformResult(status, context, resolved.taskId, prNumber, error);
+        return options.strict || isHardSummaryFailure(error)
+            ? { ...output, result: null, warnings: [] }
+            : { ...softenFailure(output) };
+    };
     const frontmatter = parseTypedTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8'));
-    const fact = readPrDeliveryFact(frontmatter);
+    const fact = readPrDeliveryFact(frontmatter, options.runtimeVersion);
     if (fact.status === 'invalid')
-        return softenFailure(platformResult('failed', { error: { code: 'PR_DELIVERY_FACT_INVALID', message: fact.error.message, retryable: false } }));
-    const prNumber = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null;
-    if (!prNumber)
-        return softenFailure(platformResult('failed', { error: { code: fact.status === 'missing' ? 'PR_DELIVERY_FACT_MISSING' : 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false } }));
-    knownPrNumber = prNumber;
-    const client = options.client || createGitHubClient();
-    const context = resolvePlatformContext({ cwd: resolved.repoRoot, client });
-    if (!context.platform.repository || !['no-op', 'degraded'].includes(context.status))
-        return softenFailure(context);
-    let headSha;
+        return preserveFailure(platformResult('failed', { error: { code: fact.error.code, message: fact.error.message, retryable: false } }));
+    if (!options.changeReportFile)
+        return preserveFailure(platformResult('failed', { error: { code: 'PR_CHANGE_REPORT_MISSING', message: 'summary-sync requires --change-report-file', retryable: false } }));
+    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)) {
+        // This diagnostic-only read preserves the known PR target when context resolution fails before the execution lock.
+        knownPrNumber = boundPrNumberForWarning(resolved.taskMdPath);
+        return preserveFailure(context);
+    }
     try {
-        headSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: resolved.repoRoot, encoding: 'utf8' }).trim();
+        return await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, options.agent, async () => {
+            const { taskContent, boundFact } = readBoundTaskSnapshot(resolved.taskMdPath);
+            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 } }),
+                    result: null, warnings: []
+                };
+            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);
+            if (!initial.ok)
+                return fail(initial.status, context, initial.error);
+            const expectedReportPath = taskReportPath(resolved.taskDir);
+            const suppliedReportPath = path.resolve(resolved.repoRoot, options.changeReportFile);
+            if (suppliedReportPath !== expectedReportPath)
+                return fail('failed', context, { code: 'PR_CHANGE_REPORT_PATH_INVALID', message: 'summary-sync must consume the task-bound pr-change-report.json', retryable: false });
+            const report = readPrChangeReport(suppliedReportPath);
+            if (!report.ok)
+                return fail('failed', context, platformError(report.error));
+            const checked = currentReportCheck(report.value, initial.value, taskContent, resolved.repoRoot);
+            if (!checked.ok)
+                return fail('failed', context, checked.error);
+            const placeholder = CANONICAL_REPORT_PLACEHOLDER;
+            const split = splitDocumentPlaceholder(options.body, placeholder);
+            if (!split.ok)
+                return fail('failed', context, {
+                    code: 'PR_SUMMARY_BODY_CONTRACT_INVALID',
+                    message: split.error.message,
+                    retryable: false
+                });
+            const prefix = sanitizeMarkdownDocument(split.value.prefix, { reservedMarkers: [CONTROL_MARKER_PATTERN] });
+            const suffix = sanitizeMarkdownDocument(split.value.suffix, { reservedMarkers: [CONTROL_MARKER_PATTERN] });
+            if (!prefix.ok) {
+                return fail('failed', context, {
+                    code: 'PR_SUMMARY_BODY_CONTRACT_INVALID',
+                    message: `${prefix.error.message} at offset ${prefix.error.offset}`,
+                    retryable: false
+                });
+            }
+            if (!suffix.ok) {
+                return fail('failed', context, {
+                    code: 'PR_SUMMARY_BODY_CONTRACT_INVALID',
+                    message: `${suffix.error.message} at offset ${suffix.error.offset}`,
+                    retryable: false
+                });
+            }
+            const replaced = replaceCanonicalReportPlaceholder(`${prefix.value}${placeholder}${suffix.value}`, report.value);
+            if (!replaced.ok)
+                return fail('failed', context, platformError(replaced.error));
+            const desired = buildPullRequestSummary(resolved.taskId, replaced.value, initial.value.head.sha, renderHumanOverrideAudit(taskContent));
+            if (!isSafeSummaryEnvelope(desired, resolved.taskId))
+                return fail('failed', context, {
+                    code: 'PR_SUMMARY_RENDER_INVALID',
+                    message: 'Summary contains an invalid or duplicated reserved control marker',
+                    retryable: false
+                });
+            const listed = loaded.value.provider.comments?.list
+                ? await loaded.value.provider.comments.list({ context: providerOperationContext(loaded.value), parent: prIdentity }).then((response) => response.ok
+                    ? { ok: true, value: response.value.map((comment) => ({ id: /^\d+$/.test(comment.id) ? Number(comment.id) : comment.id, body: comment.body })) }
+                    : response)
+                : unsupportedProviderOperation(loaded.value.provider, 'comments.list');
+            if (!listed.ok)
+                return fail(providerStatus(listed.error) === 'blocked' ? 'blocked' : 'failed', context, providerError(listed.error, 'PLATFORM_PROVIDER_OPERATION_FAILED'));
+            const reconciliation = reconcileSummaryComment(listed.value, resolved.taskId, desired);
+            if (reconciliation.action === 'conflict')
+                return fail('failed', context, { code: 'PR_SUMMARY_MARKER_AMBIGUOUS', message: 'Multiple PR comments contain the summary marker', retryable: false });
+            const previousBody = reconciliation.action === 'update'
+                ? 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);
+            if (!beforeWrite.ok)
+                return fail(beforeWrite.status, context, beforeWrite.error, prNumber);
+            if (!sameIdentity(initial.value, beforeWrite.value))
+                return fail('blocked', context, {
+                    code: 'PR_SUMMARY_HEAD_RACE',
+                    message: 'Pull request head changed before publishing the summary',
+                    retryable: true
+                }, prNumber);
+            if (reconciliation.action === 'no-op')
+                return {
+                    ...basePlatformResult('no-op', context, resolved.taskId, prNumber),
+                    comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: [reconciliation.commentId], parts: 1 },
+                    result: null, warnings: [], ...info
+                };
+            if (options.dryRun)
+                return {
+                    ...basePlatformResult('planned', context, resolved.taskId, prNumber),
+                    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, prNumber, 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_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)
+                    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_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
+            };
+        });
     }
     catch (error) {
-        return softenFailure(platformResult('failed', { platform: context.platform, capabilities: context.capabilities, error: { code: 'GIT_HEAD_UNRESOLVED', message: error instanceof Error ? error.message : String(error), retryable: false } }));
+        const lockError = error instanceof TaskExecutionLockError
+            ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
+            : { code: 'PR_SUMMARY_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false };
+        return fail(lockError.retryable ? 'blocked' : 'failed', context, lockError);
     }
-    const desired = buildPullRequestSummary(resolved.taskId, options.body, headSha, renderHumanOverrideAudit(fs.readFileSync(resolved.taskMdPath, 'utf8')));
-    const listed = listRemoteComments(client, context.platform.repository, prNumber, resolved.repoRoot);
-    if (!listed.ok)
-        return softenFailure(platformResult(listed.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: listed.error }));
-    const reconciliation = reconcileSummaryComment(listed.value, resolved.taskId, desired);
-    if (reconciliation.action === 'conflict')
-        return softenFailure(platformResult('failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: { code: 'PR_SUMMARY_MARKER_AMBIGUOUS', message: 'Multiple PR comments contain the summary marker', retryable: false } }));
-    if (reconciliation.action === 'no-op')
-        return softenFailure(platformResult('no-op', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: [reconciliation.commentId], parts: 1 }, error: null }));
-    if (options.dryRun)
-        return softenFailure(platformResult('planned', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, operations: [{ name: `summary:${reconciliation.action}`, status: 'planned', reasonCode: null }], error: null }));
-    const written = writeComment(client, context.platform.repository, prNumber, resolved.repoRoot, desired, reconciliation.commentId || undefined);
-    if (!written.ok)
-        return softenFailure(platformResult(written.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: written.error }));
-    const id = Number(written.value.id || reconciliation.commentId);
-    return softenFailure(platformResult('applied', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: Number.isInteger(id) ? [id] : [], parts: 1 }, operations: [{ name: `summary:${reconciliation.action}`, status: 'applied', reasonCode: null }], error: null }));
-}
-export { buildPullRequestSummary, reconcileSummaryComment, summaryContext, summaryMarker, syncPullRequestSummary };
-export { warningResultForPrimary };
+}
+export { buildPullRequestSummary, reconcileSummaryComment, reportWrite, summaryContext, summaryMarker, syncPullRequestSummary, warningResultForPrimary };
 //# sourceMappingURL=pr-summary.js.map