@fitlab-ai/agent-infra 0.12.0 → 0.12.2

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

@@ -16,6 +16,16 @@ import { canonicalizeCommentBody, escapeHtmlText, fenceRanges, renderSafeCodeFen
 function isRetryable(error) {
     return error.retryable ?? providerErrorRetryable(error.code);
 }
+async function syncCommentPlan(strategy, operation, queuedOperation) {
+    const execute = () => executeCommentPlan(strategy, strategy.client);
+    if (strategy.dryRun)
+        return execute();
+    if (queuedOperation)
+        return execute();
+    return coordinatePlatformWrite({ operation, agent: strategy.agent, client: strategy.client, execute,
+        block: (error) => platformResult('blocked', { error }),
+        persistenceFailure: (error) => platformResult('failed', { error }) });
+}
 function providerCommentId(id, provider) {
     return provider.identity?.comment === 'number' && /^\d+$/.test(id) ? Number(id) : id;
 }
@@ -91,9 +101,6 @@ function renderTaskCommentResult(content, taskId, language = '') {
 function renderTaskComment(content, taskId, _agent, language = '') {
     return renderTaskCommentResult(content, taskId, language).body;
 }
-function isTaskCommentTooLarge(content, taskId = 'TASK-UNKNOWN', _agent = 'codex') {
-    return renderTaskCommentResult(content, taskId).byteLength > COMMENT_BYTE_LIMIT;
-}
 function taskCommentLanguage(repoRoot) {
     try {
         const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
@@ -291,18 +298,6 @@ function chunkArtifactComment(input) {
 function findMarkerComments(comments, marker) {
     return comments.filter((comment) => normalizeCommentContent(String(comment.body || '')).split('\n', 1)[0] === marker);
 }
-function flattenComments(value) {
-    if (!Array.isArray(value))
-        return [];
-    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 listRemoteComments(client, repo, issue, cwd) {
-    const result = client.json([
-        'api', '--paginate', '--slurp', `repos/${repo}/issues/${issue}/comments?per_page=100`
-    ], { cwd });
-    return result.ok ? { ok: true, value: flattenComments(result.value) } : result;
-}
 function contextFields(context) {
     return {
         platform: context.platform,
@@ -378,38 +373,285 @@ function relatedComments(comments, prefix) {
         return first === base || (first.startsWith(chunkNamespace) && first.endsWith(' -->'));
     });
 }
-function taskManagedComment(comment, taskId) {
-    const marker = normalizeCommentContent(comment.body).split('\n', 1)[0] || '';
-    return marker === MARKERS.task(taskId)
-        || marker === MARKERS.summary(taskId)
-        || marker.startsWith(`<!-- sync-issue:${taskId}:`);
-}
-function summaryPosition(comments, taskId) {
-    const managed = comments.filter((comment) => taskManagedComment(comment, taskId));
-    const summary = managed.filter((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] === MARKERS.summary(taskId));
-    if (summary.length !== 1)
-        return { ok: false, known: false, summary: null };
-    if (managed.some((comment) => !Number.isSafeInteger(comment.createdSequence) || Number(comment.createdSequence) < 1)) {
-        return { ok: false, known: false, summary: summary[0] };
-    }
-    const sequence = summary[0].createdSequence;
-    return { ok: managed.every((comment) => sequence >= comment.createdSequence), known: true, summary: summary[0] };
-}
 async function listedComments(provider, loaded, parent) {
     return provider.comments?.list
         ? provider.comments.list({ context: providerOperationContext(loaded), parent }).then((response) => response.ok
-            ? {
-                ok: true,
-                value: response.value.map((comment) => ({
-                    id: providerCommentId(comment.id, provider),
-                    body: comment.body,
-                    user: comment.author?.name ? { login: comment.author.name } : undefined,
-                    createdSequence: comment.createdSequence
-                }))
-            }
-            : response)
+            ? { ok: true, value: response.value.map((comment) => parentComment(comment, provider)) }
+            : { ...response, error: { ...response.error, retryable: isRetryable(response.error) } })
         : unsupportedProviderOperation(provider, 'comments.list');
 }
+function markerSetError(strategy, context, resource, existing) {
+    if (validateRelatedMarkerSet(existing, strategy.markerPrefix).ok)
+        return null;
+    return platformResult('failed', { ...contextFields(context), resource, error: {
+            code: strategy.parentKind === 'pull-request' ? 'PR_SUMMARY_MARKER_AMBIGUOUS' : 'COMMENT_MARKER_CONFLICT',
+            message: strategy.parentKind === 'pull-request' ? 'Multiple PR comments contain the summary marker' : 'Multiple comments use the same registered marker', retryable: false
+        } });
+}
+function taskCommentOwnerError(strategy, context, resource, existing) {
+    if (strategy.kind !== 'task' || existing.length !== 1)
+        return null;
+    const owner = existing[0].user?.login;
+    return owner && context.platform.currentUser && owner === context.platform.currentUser ? null : platformResult('blocked', {
+        ...contextFields(context), resource, error: {
+            code: 'COMMENT_OWNER_CONFLICT', message: owner ? `Task comment is owned by '${owner}'` : 'Task comment owner is unavailable', retryable: false
+        }
+    });
+}
+async function strategyValidationError(strategy, context, resource) {
+    const error = strategy.validate ? await strategy.validate() : null;
+    if (!error)
+        return null;
+    return platformResult(error.retryable ? 'blocked' : 'failed', { ...contextFields(context), resource, error });
+}
+function artifactBackfillResult(strategy, context, resource, existing, desired) {
+    if (!strategy.backfill || strategy.kind !== 'artifact' || existing.length === 0)
+        return null;
+    const operations = existing.map((comment) => ({
+        name: `comment:${normalizeCommentContent(comment.body).split('\n', 1)[0]}`,
+        status: 'no-op',
+        reasonCode: 'BACKFILL_ALREADY_PRESENT'
+    }));
+    return platformResult('no-op', {
+        ...contextFields(context),
+        resource,
+        operations,
+        comment: {
+            kind: strategy.kind,
+            marker: desired[0]?.marker ?? strategy.markerPrefix,
+            ids: existing.map((item) => item.id),
+            parts: existing.length
+        },
+        error: null
+    });
+}
+function repositionAuthorizationError(strategy, context, resource, comments, byMarker, desired) {
+    const marker = desired[0]?.marker;
+    const current = marker ? byMarker.get(marker) : undefined;
+    const position = strategy.summaryPosition && current
+        ? issueSummaryPosition(strategy.taskId, comments, marker)
+        : true;
+    if (position === null)
+        return {
+            error: platformResult('blocked', { ...contextFields(context), resource, error: {
+                    code: 'SUMMARY_POSITION_UNVERIFIED', message: 'Summary comment ordering cannot be proven from the provider snapshot', retryable: true
+                } }),
+            reposition: false
+        };
+    const reposition = Boolean(strategy.summaryPosition && current && !position);
+    if (!reposition || !current)
+        return { error: null, reposition: false };
+    const error = strategy.authorizeReposition
+        ? strategy.authorizeReposition(current, context.platform.currentUser ?? null)
+        : { code: 'SUMMARY_REPOSITION_UNAUTHORIZED', message: 'summary reposition requires current authorization and an owned summary comment', retryable: false };
+    return {
+        error: error ? platformResult(error.retryable ? 'blocked' : 'failed', { ...contextFields(context), resource, error }) : null,
+        reposition: true
+    };
+}
+async function inspectCommentPlan(strategy, context, resource, comments, desired) {
+    const existing = relatedComments(comments, strategy.markerPrefix);
+    const markerError = markerSetError(strategy, context, resource, existing);
+    if (markerError)
+        return { ok: false, result: markerError };
+    const ownerError = taskCommentOwnerError(strategy, context, resource, existing);
+    if (ownerError)
+        return { ok: false, result: ownerError };
+    const validationError = await strategyValidationError(strategy, context, resource);
+    if (validationError)
+        return { ok: false, result: validationError };
+    const backfill = artifactBackfillResult(strategy, context, resource, existing, desired);
+    if (backfill)
+        return { ok: true, value: { existing, byMarker: new Map(), reposition: false }, result: backfill };
+    const byMarker = new Map(existing.map((comment) => [normalizeCommentContent(comment.body).split('\n', 1)[0], comment]));
+    const reposition = repositionAuthorizationError(strategy, context, resource, comments, byMarker, desired);
+    if (reposition.error)
+        return { ok: false, result: reposition.error };
+    return { ok: true, value: { existing, byMarker, reposition: reposition.reposition } };
+}
+async function repositionSummaryComment(strategy, loaded, context, parent, resource, current, operations) {
+    if (!current)
+        return null;
+    const deleted = loaded.provider.comments?.delete
+        ? await loaded.provider.comments.delete({ context: providerOperationContext(loaded), parent,
+            comment: providerResourceToken(loaded.provider, 'comment', String(current.id)),
+            mutation: { idempotencyKey: `comment-reposition-delete:${strategy.taskId}:${current.id}` } })
+        : unsupportedProviderOperation(loaded.provider, 'comments.delete');
+    if (!deleted.ok)
+        return platformResult(isRetryable(deleted.error) ? 'blocked' : 'failed', {
+            ...contextFields(context), resource, error: deleted.error
+        });
+    operations.push({
+        name: `comment:${current.id}`,
+        status: 'applied',
+        reasonCode: 'SUMMARY_REPOSITIONED'
+    });
+    return null;
+}
+async function observeCommentWrite(strategy, loaded, parent, item) {
+    const after = await listedComments(loaded.provider, loaded, parent);
+    const comments = after.ok ? after.value : [];
+    const found = comments.filter((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] === item.marker);
+    const positionOk = !strategy.summaryPosition || issueSummaryPosition(strategy.taskId, comments, item.marker) === true;
+    const validation = strategy.validate ? await strategy.validate() : null;
+    if (after.ok
+        && found.length === 1
+        && normalizeCommentContent(found[0].body) === normalizeCommentContent(item.body)
+        && positionOk
+        && !validation)
+        return { valid: true };
+    const error = validation ?? {
+        code: strategy.kind === 'summary' || strategy.kind === 'cancel' ? 'SUMMARY_BODY_READBACK_FAILED' : 'COMMENT_READBACK_FAILED',
+        message: after.ok ? 'Remote comment did not match the requested body' : after.error.message,
+        retryable: after.ok || isRetryable(after.error)
+    };
+    return { valid: false, error };
+}
+async function verifyIssueSummaryReadback(strategy, loaded, context, parent, resource, desired, operations) {
+    if (strategy.parentKind !== 'issue' || (strategy.kind !== 'summary' && strategy.kind !== 'cancel'))
+        return null;
+    const after = await listedComments(loaded.provider, loaded, parent);
+    if (!after.ok)
+        return platformResult(isRetryable(after.error) ? 'blocked' : 'failed', {
+            ...contextFields(context), resource, operations, error: after.error
+        });
+    const item = desired[0];
+    const matching = item
+        ? after.value.filter((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] === item.marker)
+        : [];
+    if (!item || matching.length !== 1 || normalizeCommentContent(matching[0].body) !== normalizeCommentContent(item.body)) {
+        return platformResult('blocked', { ...contextFields(context), resource, operations, error: {
+                code: 'SUMMARY_BODY_READBACK_FAILED',
+                message: strategy.kind === 'cancel' ? 'Remote cancellation body did not match the rendered cancellation summary' : 'Remote summary body did not match the rendered delivery summary',
+                retryable: true
+            } });
+    }
+    if (strategy.summaryPosition && issueSummaryPosition(strategy.taskId, after.value, item.marker) !== true) {
+        return platformResult('blocked', { ...contextFields(context), resource, operations, error: {
+                code: 'SUMMARY_POSITION_UNVERIFIED', message: 'Summary comment is not provably last among task-managed comments', retryable: true
+            } });
+    }
+    return null;
+}
+async function compensatePullRequestComment(strategy, loaded, parent, current, id, cause) {
+    const compensation = current
+        ? await loaded.provider.comments?.write?.({ context: providerOperationContext(loaded), parent, body: current.body,
+            existingComment: providerResourceToken(loaded.provider, 'comment', String(current.id)),
+            mutation: { idempotencyKey: `pr-summary-restore:${strategy.taskId}` } })
+        : await loaded.provider.comments?.delete?.({ context: providerOperationContext(loaded), parent,
+            comment: providerResourceToken(loaded.provider, 'comment', String(id)),
+            mutation: { idempotencyKey: `pr-summary-delete:${strategy.taskId}:${id}` } });
+    if (!compensation?.ok)
+        return {
+            code: 'PR_SUMMARY_RACE_COMPENSATION_FAILED',
+            message: compensation?.error?.message ?? 'Provider does not support comment compensation',
+            retryable: true
+        };
+    if (cause?.code === 'PR_SUMMARY_HEAD_RACE')
+        return cause;
+    return {
+        code: 'PR_SUMMARY_POSTWRITE_VERIFY_FAILED',
+        message: cause?.message ?? 'Post-write summary verification failed',
+        retryable: true
+    };
+}
+async function verifyCommentWrite(strategy, loaded, parent, item, current, id) {
+    if (!strategy.verifyReadback || strategy.parentKind === 'issue')
+        return null;
+    const observed = await observeCommentWrite(strategy, loaded, parent, item);
+    if (observed.valid)
+        return null;
+    if (strategy.parentKind === 'pull-request') {
+        return compensatePullRequestComment(strategy, loaded, parent, current, id, observed.error);
+    }
+    return observed.error;
+}
+async function writeDesiredComments(strategy, loaded, context, parent, resource, desired, selection, operations) {
+    const ids = [];
+    for (const item of desired) {
+        const current = selection.reposition && item === desired[0] ? undefined : selection.byMarker.get(item.marker);
+        if (current && normalizeCommentContent(current.body) === normalizeCommentContent(item.body)) {
+            ids.push(current.id);
+            operations.push({ name: `comment:${item.marker}`, status: 'no-op', reasonCode: null });
+            continue;
+        }
+        const written = loaded.provider.comments?.write
+            ? await loaded.provider.comments.write({ context: providerOperationContext(loaded), parent, body: item.body,
+                ...(current ? { existingComment: providerResourceToken(loaded.provider, 'comment', String(current.id)) } : {}),
+                mutation: { idempotencyKey: `comment:${strategy.taskId}:${item.marker}` } })
+            : unsupportedProviderOperation(loaded.provider, 'comments.write');
+        if (!written.ok)
+            return { ok: false, result: platformResult(isRetryable(written.error) ? 'blocked' : 'failed', {
+                    ...contextFields(context), resource, operations, error: written.error
+                }) };
+        const id = providerCommentId(written.value.remoteId, loaded.provider);
+        ids.push(id);
+        operations.push({ name: `comment:${item.marker}`, status: 'applied', reasonCode: null });
+        const error = await verifyCommentWrite(strategy, loaded, parent, item, current, id);
+        if (error)
+            return { ok: false, result: platformResult(error.retryable ? 'blocked' : 'failed', {
+                    ...contextFields(context), resource, operations, error
+                }) };
+    }
+    return { ok: true, ids };
+}
+async function deleteStaleComments(strategy, loaded, context, parent, resource, existing, desired, operations) {
+    const markers = new Set(desired.map((item) => item.marker));
+    for (const stale of existing.filter((comment) => !markers.has(normalizeCommentContent(comment.body).split('\n', 1)[0]))) {
+        const deleted = loaded.provider.comments?.delete
+            ? await loaded.provider.comments.delete({ context: providerOperationContext(loaded), parent,
+                comment: providerResourceToken(loaded.provider, 'comment', String(stale.id)),
+                mutation: { idempotencyKey: `comment-delete:${strategy.taskId}:${stale.id}` } })
+            : unsupportedProviderOperation(loaded.provider, 'comments.delete');
+        if (!deleted.ok)
+            return platformResult(isRetryable(deleted.error) ? 'blocked' : 'failed', {
+                ...contextFields(context), resource, operations, error: deleted.error
+            });
+        operations.push({ name: `comment:${stale.id}`, status: 'applied', reasonCode: 'STALE_CHUNK_DELETED' });
+    }
+    return null;
+}
+async function prepareCommentExecution(strategy, client) {
+    const resolved = strategy.resolved
+        ? { ok: true, value: strategy.resolved.loaded }
+        : await resolvePlatformProviderContext({ cwd: strategy.cwd, client });
+    const loaded = resolved;
+    const context = strategy.resolved?.context ?? (loaded.ok ? loaded.value.context : loaded.context);
+    if (!loaded.ok || !hasResolvedPlatformContext(context))
+        return { ok: false, result: context };
+    let parent;
+    let desired;
+    try {
+        ({ parent, items: desired } = await strategy.prepare());
+    }
+    catch (error) {
+        const value = error;
+        return { ok: false, result: platformResult('failed', { ...contextFields(context), error: {
+                    code: value.code || 'COMMENT_PAYLOAD_INVALID', message: value.message || String(error), retryable: false
+                } }) };
+    }
+    const resource = { kind: strategy.parentKind, number: resourceIdentityNumber(parent), identity: parent };
+    const listed = await listedComments(loaded.value.provider, loaded.value, parent);
+    if (!listed.ok)
+        return { ok: false, result: platformResult(isRetryable(listed.error) ? 'blocked' : 'failed', {
+                ...contextFields(context), resource, error: listed.error
+            }) };
+    const selection = await inspectCommentPlan(strategy, context, resource, listed.value, desired);
+    if (!selection.ok)
+        return selection;
+    return {
+        ok: true,
+        value: {
+            loaded: loaded.value,
+            context,
+            parent,
+            desired,
+            resource,
+            selection: selection.value,
+            result: selection.result
+        }
+    };
+}
 function validateRelatedMarkerSet(comments, prefix) {
     const markers = comments.map((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] || '');
     if (new Set(markers).size !== markers.length)
@@ -433,259 +675,108 @@ function validateRelatedMarkerSet(comments, prefix) {
     const complete = total > 0 && parts.length === total && parts.every((part, index) => part === index + 1);
     return complete ? { ok: true, code: null } : { ok: false, code: 'COMMENT_MARKER_CONFLICT' };
 }
-function writeComment(client, repo, issue, cwd, body, id) {
-    const endpoint = id ? `repos/${repo}/issues/comments/${id}` : `repos/${repo}/issues/${issue}/comments`;
-    return client.json(['api', endpoint, '-X', id ? 'PATCH' : 'POST', '--input', '-'], { cwd, method: id ? 'PATCH' : 'POST', input: JSON.stringify({ body }) });
+function parentComment(comment, provider) {
+    return {
+        id: providerCommentId(comment.id, provider), body: comment.body,
+        user: comment.author?.name ? { login: comment.author.name } : undefined,
+        createdSequence: comment.createdSequence
+    };
 }
-async function syncPlatformCommentImpl(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 }
-        });
-    }
-    const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
-    let issueIdentityFromTask;
-    try {
-        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 platform issue identity', retryable: false }
-        });
-    }
-    let desired;
-    try {
-        const projectedContent = options.kind === 'task' && options.taskProjection ? options.taskProjection.content : taskContent;
-        if (options.kind === 'task' && options.taskProjection
-            && createHash('sha256').update(projectedContent).digest('hex') !== options.taskProjection.sha256) {
-            throw Object.assign(new Error('finalization task projection digest does not match content'), { code: 'FINALIZATION_PROJECTION_INVALID' });
-        }
-        desired = expectedComments(resolved.taskId, projectedContent, resolved.taskDir, resolved.repoRoot, options);
-    }
-    catch (error) {
-        return platformResult('failed', {
-            resource: { kind: 'issue', number: resourceIdentityNumber(issueIdentityFromTask) },
-            error: { code: 'COMMENT_PAYLOAD_INVALID', message: error instanceof Error ? error.message : String(error), retryable: false }
-        });
-    }
-    if (options.kind === 'task' && Buffer.byteLength(desired[0].body, 'utf8') > COMMENT_BYTE_LIMIT) {
-        return platformResult('failed', {
-            resource: { kind: 'issue', number: resourceIdentityNumber(issueIdentityFromTask), identity: issueIdentityFromTask },
-            operations: [{ name: `comment:${MARKERS.task(resolved.taskId)}`, status: 'skipped', reasonCode: 'COMMENT_PAYLOAD_TOO_LARGE' }],
-            error: { code: 'COMMENT_PAYLOAD_TOO_LARGE', message: 'Projected task comment exceeds the platform byte limit', retryable: false }
-        });
-    }
-    const loaded = await resolvePlatformProviderContext({ cwd: resolved.repoRoot, client: options.client });
-    const context = loaded.ok ? loaded.value.context : loaded.context;
-    if (!hasResolvedPlatformContext(context) || !loaded.ok)
-        return context;
-    const issue = resourceIdentityNumber(issueIdentityFromTask);
-    const listed = await listedComments(loaded.value.provider, loaded.value, issueIdentityFromTask);
-    if (!listed.ok) {
-        return platformResult(isRetryable(listed.error) ? 'blocked' : 'failed', {
-            ...contextFields(context), resource: { kind: 'issue', number: issue }, error: listed.error
-        });
-    }
-    const existing = relatedComments(listed.value, markerPrefix(resolved.taskId, options));
-    if (!validateRelatedMarkerSet(existing, markerPrefix(resolved.taskId, options)).ok) {
-        return platformResult('failed', {
-            ...contextFields(context),
-            resource: { kind: 'issue', number: issue },
-            error: { code: 'COMMENT_MARKER_CONFLICT', message: 'Multiple comments use the same registered marker', retryable: false }
-        });
-    }
-    if (options.kind === 'task' && existing.length === 1) {
-        const owner = existing[0].user?.login;
-        if (!owner || !context.platform.currentUser || owner !== context.platform.currentUser) {
-            return platformResult('blocked', {
-                ...contextFields(context),
-                resource: { kind: 'issue', number: issue, identity: issueIdentityFromTask },
-                error: {
-                    code: 'COMMENT_OWNER_CONFLICT',
-                    message: owner ? `Task comment is owned by '${owner}'` : 'Task comment owner is unavailable',
-                    retryable: false
-                }
-            });
-        }
-    }
-    // Backfill only supplies missing artifact comments; valid existing marker sets stay untouched.
-    if (options.kind === 'artifact' && options.backfill && existing.length > 0) {
-        const operations = existing.map((comment) => ({
-            name: `comment:${normalizeCommentContent(comment.body).split('\n', 1)[0]}`,
-            status: 'no-op',
-            reasonCode: 'BACKFILL_ALREADY_PRESENT'
-        }));
-        return platformResult('no-op', {
-            ...contextFields(context),
-            changed: false,
-            resource: { kind: 'issue', number: issue },
-            operations,
-            comment: {
-                kind: options.kind,
-                marker: desired[0].marker,
-                ids: existing.map((comment) => comment.id),
-                parts: existing.length
-            },
-            error: null
+function issueSummaryPosition(taskId, comments, marker) {
+    const managed = comments.filter((comment) => comment.body.split('\n', 1)[0]?.startsWith(`<!-- sync-issue:${taskId}:`));
+    const summary = managed.filter((comment) => comment.body.split('\n', 1)[0] === marker);
+    if (summary.length !== 1 || managed.some((comment) => !Number.isSafeInteger(comment.createdSequence) || comment.createdSequence === null))
+        return null;
+    return managed.every((comment) => summary[0].createdSequence >= comment.createdSequence);
+}
+async function executeCommentPlan(strategy, client) {
+    const prepared = await prepareCommentExecution(strategy, client);
+    if (!prepared.ok)
+        return prepared.result;
+    const { loaded, context, parent, desired, resource, selection, result } = prepared.value;
+    if (result)
+        return result;
+    if (strategy.dryRun)
+        return platformResult('planned', {
+            ...contextFields(context), resource,
+            operations: desired.map((item) => ({ name: `comment:${item.marker}`, status: 'planned', reasonCode: null })), error: null
         });
-    }
     const operations = [];
-    const ids = [];
-    for (const item of desired) {
-        const current = existing.find((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] === item.marker);
-        if (current && normalizeCommentContent(current.body) === normalizeCommentContent(item.body)) {
-            ids.push(current.id);
-            operations.push({ name: `comment:${item.marker}`, status: 'no-op', reasonCode: null });
-            continue;
-        }
-        const written = loaded.value.provider.comments?.write
-            ? await loaded.value.provider.comments.write({
-                context: providerOperationContext(loaded.value),
-                parent: issueIdentityFromTask,
-                body: item.body,
-                ...(current ? { existingComment: { kind: 'id', value: String(current.id) } } : {}),
-                mutation: { idempotencyKey: `comment:${resolved.taskId}:${item.marker}` }
-            })
-            : unsupportedProviderOperation(loaded.value.provider, 'comments.write');
-        if (!written.ok) {
-            if (!current && isRetryable(written.error)) {
-                // A provider owns reconciliation because only it knows how to address the resource.
-            }
-            return platformResult(isRetryable(written.error) ? 'blocked' : 'failed', {
-                ...contextFields(context),
-                resource: { kind: 'issue', number: issue },
-                operations,
-                error: written.error
-            });
-        }
-        ids.push(providerCommentId(written.value.remoteId, loaded.value.provider));
-        operations.push({ name: `comment:${item.marker}`, status: 'applied', reasonCode: null });
-    }
-    const desiredMarkers = new Set(desired.map((item) => item.marker));
-    const stale = existing.filter((comment) => !desiredMarkers.has(normalizeCommentContent(comment.body).split('\n', 1)[0]));
-    for (const comment of stale) {
-        const deleted = loaded.value.provider.comments?.delete
-            ? await loaded.value.provider.comments.delete({
-                context: providerOperationContext(loaded.value),
-                parent: issueIdentityFromTask,
-                comment: { kind: 'id', value: String(comment.id) },
-                mutation: { idempotencyKey: `comment-delete:${resolved.taskId}:${comment.id}` }
-            })
-            : unsupportedProviderOperation(loaded.value.provider, 'comments.delete');
-        if (!deleted.ok) {
-            return platformResult(isRetryable(deleted.error) ? 'blocked' : 'failed', {
-                ...contextFields(context),
-                resource: { kind: 'issue', number: issue },
-                operations,
-                error: deleted.error
-            });
-        }
-        operations.push({ name: `comment:${comment.id}`, status: 'applied', reasonCode: 'STALE_CHUNK_DELETED' });
-    }
-    if (options.kind === 'summary') {
-        const refreshed = await listedComments(loaded.value.provider, loaded.value, issueIdentityFromTask);
-        if (!refreshed.ok) {
-            return platformResult(isRetryable(refreshed.error) ? 'blocked' : 'failed', {
-                ...contextFields(context), resource: { kind: 'issue', number: issue }, operations, error: refreshed.error
-            });
-        }
-        const position = summaryPosition(refreshed.value, resolved.taskId);
-        if (!position.ok && !position.known) {
-            return platformResult('blocked', {
-                ...contextFields(context), resource: { kind: 'issue', number: issue }, operations,
-                error: { code: 'SUMMARY_POSITION_UNVERIFIED', message: 'Summary comment ordering cannot be proven from the provider snapshot', retryable: true }
-            });
-        }
-        if (!position.ok && position.summary) {
-            const owner = position.summary.user?.login;
-            if (!options.summaryAuthorization || options.summaryAuthorization.sha256 !== createHash('sha256').update(options.body ?? '').digest('hex')
-                || !owner || owner !== context.platform.currentUser) {
-                return platformResult('failed', {
-                    ...contextFields(context), resource: { kind: 'issue', number: issue }, operations,
-                    error: { code: 'SUMMARY_REPOSITION_UNAUTHORIZED', message: 'summary reposition requires current finalization authorization and an owned durable summary', retryable: false }
-                });
-            }
-            const deleted = loaded.value.provider.comments?.delete
-                ? await loaded.value.provider.comments.delete({
-                    context: providerOperationContext(loaded.value), parent: issueIdentityFromTask,
-                    comment: { kind: 'id', value: String(position.summary.id) },
-                    mutation: { idempotencyKey: `summary-reposition-delete:${resolved.taskId}:${position.summary.id}` }
-                })
-                : unsupportedProviderOperation(loaded.value.provider, 'comments.delete');
-            if (!deleted.ok) {
-                return platformResult(isRetryable(deleted.error) ? 'blocked' : 'failed', {
-                    ...contextFields(context), resource: { kind: 'issue', number: issue }, operations, error: deleted.error
-                });
-            }
-            const written = loaded.value.provider.comments?.write
-                ? await loaded.value.provider.comments.write({
-                    context: providerOperationContext(loaded.value), parent: issueIdentityFromTask, body: desired[0].body,
-                    mutation: { idempotencyKey: `summary-reposition-write:${resolved.taskId}` }
-                })
-                : unsupportedProviderOperation(loaded.value.provider, 'comments.write');
-            if (!written.ok) {
-                return platformResult(isRetryable(written.error) ? 'blocked' : 'failed', {
-                    ...contextFields(context), resource: { kind: 'issue', number: issue }, operations, error: written.error
-                });
-            }
-            ids.splice(0, ids.length, providerCommentId(written.value.remoteId, loaded.value.provider));
-            operations.push({ name: `comment:${desired[0].marker}`, status: 'applied', reasonCode: 'SUMMARY_REPOSITIONED' });
-            const reconciled = await listedComments(loaded.value.provider, loaded.value, issueIdentityFromTask);
-            if (!reconciled.ok || !summaryPosition(reconciled.value, resolved.taskId).ok) {
-                const error = reconciled.ok
-                    ? { code: 'SUMMARY_POSITION_UNVERIFIED', message: 'Summary comment is not provably last among task-managed comments', retryable: true }
-                    : reconciled.error;
-                return platformResult(isRetryable(error) ? 'blocked' : 'failed', {
-                    ...contextFields(context), resource: { kind: 'issue', number: issue }, operations, error
-                });
-            }
-        }
-    }
+    const currentSummary = desired[0] ? selection.byMarker.get(desired[0].marker) : undefined;
+    if (selection.reposition) {
+        const repositioned = await repositionSummaryComment(strategy, loaded, context, parent, resource, currentSummary, operations);
+        if (repositioned)
+            return repositioned;
+    }
+    const written = await writeDesiredComments(strategy, loaded, context, parent, resource, desired, selection, operations);
+    if (!written.ok)
+        return written.result;
+    const deleted = await deleteStaleComments(strategy, loaded, context, parent, resource, selection.existing, desired, operations);
+    if (deleted)
+        return deleted;
+    const readback = await verifyIssueSummaryReadback(strategy, loaded, context, parent, resource, desired, operations);
+    if (readback)
+        return readback;
     const changed = operations.some((operation) => operation.status === 'applied');
-    const result = platformResult(changed ? 'applied' : 'no-op', {
-        ...contextFields(context),
-        changed,
-        resource: { kind: 'issue', number: issue },
-        operations,
-        comment: { kind: options.kind, marker: desired[0]?.marker ?? markerPrefix(resolved.taskId, options), ids, parts: desired.length },
+    return platformResult(changed ? 'applied' : 'no-op', {
+        ...contextFields(context), changed, resource, operations,
+        comment: {
+            kind: strategy.kind,
+            marker: desired[0]?.marker ?? strategy.markerPrefix,
+            ids: written.ids,
+            parts: desired.length
+        },
         error: null
     });
-    return result;
 }
-async function syncPlatformComment(taskRef, options) {
+function syncPlatformComment(taskRef, options) {
     const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
     if (!resolved.ok)
-        return syncPlatformCommentImpl(taskRef, options);
-    const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
-    if (!taskIssueIdentity(parseTaskFrontmatter(taskContent)))
-        return syncPlatformCommentImpl(taskRef, options);
+        return Promise.resolve(platformResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }));
+    const readStrategy = () => {
+        const prefix = markerPrefix(resolved.taskId, options);
+        return {
+            taskId: resolved.taskId, cwd: resolved.repoRoot, agent: options.agent, client: options.client,
+            parentKind: 'issue', kind: options.kind, markerPrefix: prefix,
+            backfill: options.backfill,
+            prepare: async () => {
+                const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+                const parent = taskIssueIdentity(parseTaskFrontmatter(taskContent));
+                if (!parent)
+                    throw Object.assign(new Error('Task has no valid platform issue identity'), { code: 'ISSUE_NOT_LINKED' });
+                const source = options.kind === 'task' && options.taskProjection ? options.taskProjection.content : taskContent;
+                if (options.kind === 'task' && options.taskProjection && createHash('sha256').update(source).digest('hex') !== options.taskProjection.sha256) {
+                    throw Object.assign(new Error('finalization task projection digest does not match content'), { code: 'FINALIZATION_PROJECTION_INVALID' });
+                }
+                const items = expectedComments(resolved.taskId, source, resolved.taskDir, resolved.repoRoot, options);
+                if (options.kind === 'task' && Buffer.byteLength(items[0].body, 'utf8') > COMMENT_BYTE_LIMIT)
+                    throw Object.assign(new Error('Projected task comment exceeds the platform byte limit'), { code: 'COMMENT_PAYLOAD_TOO_LARGE' });
+                return { parent, items };
+            },
+            summaryPosition: options.kind === 'summary',
+            verifyReadback: options.kind === 'summary' || options.kind === 'cancel',
+            authorizeReposition: (comment, currentUser) => options.summaryAuthorization
+                && options.summaryAuthorization.sha256 === createHash('sha256').update(options.body ?? '').digest('hex')
+                && comment.user?.login && currentUser && comment.user.login === currentUser
+                ? null : { code: 'SUMMARY_REPOSITION_UNAUTHORIZED', message: 'summary reposition requires current finalization authorization and an owned durable summary', retryable: false }
+        };
+    };
+    let strategy;
     let operation;
     try {
-        const sourceContent = options.kind === 'task' && options.taskProjection ? options.taskProjection.content : taskContent;
-        const desired = expectedComments(resolved.taskId, sourceContent, resolved.taskDir, resolved.repoRoot, options);
-        const content = desired.map((chunk) => chunk.content).join('\0');
-        const kind = options.kind === 'task' ? 'task-comment' : options.kind === 'summary' ? 'summary-comment'
-            : options.kind === 'cancel' ? 'cancel-comment' : 'artifact-comment';
+        strategy = readStrategy();
+        const source = options.kind === 'task' && options.taskProjection ? options.taskProjection.content : fs.readFileSync(resolved.taskMdPath, 'utf8');
+        const expected = expectedComments(resolved.taskId, source, resolved.taskDir, resolved.repoRoot, options);
+        const digest = createHash('sha256').update(expected.map((item) => item.content).join('\0')).digest('hex');
+        const kind = options.kind === 'task' ? 'task-comment' : options.kind === 'artifact' ? 'artifact-comment' : options.kind === 'summary' ? 'summary-comment' : 'cancel-comment';
         const target = options.kind === 'artifact' ? options.artifact : options.kind;
-        operation = { kind, target, expectedDigest: createHash('sha256').update(content).digest('hex') };
+        operation = { taskRef: resolved.taskId, cwd: resolved.repoRoot, kind, target, expectedDigest: digest, dependency: options.dependency ?? 'deferred' };
     }
-    catch {
-        return syncPlatformCommentImpl(taskRef, options);
+    catch (error) {
+        const value = error;
+        return Promise.resolve(platformResult('failed', { error: { code: value.code || 'COMMENT_PAYLOAD_INVALID', message: value.message || String(error), retryable: false } }));
     }
-    const execute = () => syncPlatformCommentImpl(taskRef, options);
-    if (options.skipQueue)
-        return execute();
-    return coordinatePlatformWrite({
-        operation: { taskRef: resolved.taskId, cwd: resolved.repoRoot, ...operation, dependency: options.dependency ?? 'deferred' },
-        agent: options.agent,
-        execute,
-        block: (error) => platformResult('blocked', { error }),
-        persistenceFailure: (error) => platformResult('failed', { error })
-    });
+    return syncCommentPlan(strategy, operation, options.queuedOperation);
 }
 function inspectPlatformCommentOperation(taskRef, options) {
     const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
@@ -766,5 +857,5 @@ async function checkPlatformCommentOwner(taskRef, options = {}) {
     }
     return platformResult('no-op', { ...contextFields(context), resource: { kind: 'issue', number: resourceIdentityNumber(issueIdentity), identity: issueIdentity }, error: null });
 }
-export { COMMENT_BYTE_LIMIT, MARKERS, chunkArtifactComment, inspectPlatformCommentOperation, findMarkerComments, listRemoteComments, checkPlatformCommentOwner, listPlatformComments, normalizeCommentContent, renderTaskComment, renderTaskCommentResult, isTaskCommentTooLarge, syncPlatformComment, validateRelatedMarkerSet, writeComment };
+export { COMMENT_BYTE_LIMIT, MARKERS, chunkArtifactComment, inspectPlatformCommentOperation, findMarkerComments, checkPlatformCommentOwner, listPlatformComments, normalizeCommentContent, renderTaskComment, renderTaskCommentResult, syncCommentPlan, syncPlatformComment, validateRelatedMarkerSet };
 //# sourceMappingURL=issue-comments.js.map