@fitlab-ai/agent-infra 0.11.1 → 0.11.2

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

@@ -43,7 +43,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
     'platform-security': ['read', 'dismiss'],
     'platform-metadata': ['init-labels', 'init-milestones'],
     'platform-context': ['resolve'],
-    'platform-comment': ['list', 'recover', 'owner', 'backfill', 'sync'],
+    'platform-comment': ['list', 'recover', 'owner', 'backfill', 'stage-summary', 'sync'],
     'platform-issue': ['inspect', 'create', 'bind', 'sync'],
     'platform-pr': ['inspect', 'summary-context', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'change-report', 'summary-sync', 'sync-in-labels'],
     'platform-pr-review': ['inspect', 'list', 'publish-pr', 'publish-task'],

package/dist/lib/internal/platform-comment.js

@@ -1,14 +1,19 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { checkPlatformCommentOwner, listPlatformComments, syncPlatformComment } from '../platform/issue-comments.js';
+import { canonicalizeSummaryBody } from '../platform/comment-safety.js';
+import { platformResult } from '../platform/types.js';
 import { recoverTaskFromComments } from '../platform/task-recovery.js';
 import { backfillCompletionComments } from '../platform/completion-backfill.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
 const USAGE = `Usage: agent-infra-internal platform-comment list --issue <token> [--cwd <path>]
        agent-infra-internal platform-comment recover --issue <token> --task-id <TASK-id> --output <staging-task.md> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
        agent-infra-internal platform-comment backfill <task-ref> --agent <agent> [--cwd <path>]
+       agent-infra-internal platform-comment stage-summary <task-ref> --body-file <path|-> [--cwd <path>]
        agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
 `;
 function fail(message) {
@@ -63,6 +68,7 @@ async function platformComment(args = []) {
         internalHandlerRoute('platform-comment', 'recover', operation),
         internalHandlerRoute('platform-comment', 'owner', operation),
         internalHandlerRoute('platform-comment', 'backfill', operation),
+        internalHandlerRoute('platform-comment', 'stage-summary', operation),
         internalHandlerRoute('platform-comment', 'sync', operation)
     ].some(Boolean)) {
         fail('a valid operation is required');
@@ -177,6 +183,59 @@ async function platformComment(args = []) {
         finish(await backfillCompletionComments(taskRef, { cwd, agent: normalizedAgent }));
         return;
     }
+    if (internalHandlerRoute('platform-comment', 'stage-summary', operation)) {
+        const unexpected = Object.keys(parsed.values).find((key) => !['cwd', 'bodyFile'].includes(key));
+        if (unexpected) {
+            fail(`stage-summary does not accept '--${unexpected}'`);
+            return;
+        }
+        if (typeof parsed.values.bodyFile !== 'string') {
+            fail('stage-summary requires --body-file');
+            return;
+        }
+        let body;
+        try {
+            body = readBodyFile(parsed.values.bodyFile, cwd);
+        }
+        catch (error) {
+            fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
+        const canonical = canonicalizeSummaryBody(body);
+        if (!canonical.ok) {
+            fail(`unable to stage summary: ${canonical.error.code}: ${canonical.error.message}`);
+            return;
+        }
+        body = canonical.value;
+        const resolved = resolveTaskRef(taskRef, { repoRoot: cwd });
+        if (!resolved.ok || resolved.state !== 'active') {
+            fail('stage-summary requires an active task');
+            return;
+        }
+        const target = path.join(resolved.taskDir, '.delivery-summary.json');
+        const value = { taskId: resolved.taskId, body, sha256: createHash('sha256').update(body).digest('hex') };
+        const previous = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+        const next = `${JSON.stringify(value)}\n`;
+        if (previous === next) {
+            finish(platformResult('no-op'));
+            return;
+        }
+        const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            fs.writeFileSync(temporary, next, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+            fs.renameSync(temporary, target);
+        }
+        catch (error) {
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch { /* preserve primary error */ }
+            fail(`unable to stage summary: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
+        finish(platformResult('applied', { operations: [{ name: 'delivery-summary', status: 'applied', reasonCode: null }] }));
+        return;
+    }
     if (!internalHandlerRoute('platform-comment', 'sync', operation)) {
         fail('operation is not registered');
         return;

package/dist/lib/internal/sandbox-control.js

@@ -1,118 +1,10 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import path from 'node:path';
-import { recoverSandboxControl, requestSandboxControl, requestSandboxTaskFinalization, requestSandboxTaskControl, requestSandboxTaskWorkflow, resolveVisibleActiveShortId, SandboxControlClientError } from '../sandbox/control/client.js';
+import { recoverSandboxControl, requestSandboxControl, requestSandboxTaskFinalization, requestSandboxTaskWorkflow, resolveVisibleActiveShortId, SandboxControlClientError } from '../sandbox/control/client.js';
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { serveSandboxControl } from '../sandbox/control/server.js';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.js';
-import { controllerProofFromContext, verifyCodexSandboxControllerContextWithWarnings } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 import { parseTaskCreateResult, taskCreateExitCode } from '../task/create-service.js';
 import { createTaskWorkflowRequest } from '../sandbox/control/task-workflow.js';
-import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.js';
-import { routeOrchestration } from '../task/orchestration.js';
-import { parseArtifactName } from '../task/artifact-name.js';
-function valueAfter(args, flag) {
-    for (let index = 0; index < args.length; index += 1) {
-        if (args[index] === flag)
-            return args[index + 1];
-        if (args[index]?.startsWith(`${flag}=`))
-            return args[index].slice(flag.length + 1);
-    }
-    return undefined;
-}
-function withoutValue(args, flag) {
-    const result = [];
-    for (let index = 0; index < args.length; index += 1) {
-        if (args[index] === flag) {
-            index += 1;
-            continue;
-        }
-        if (args[index]?.startsWith(`${flag}=`))
-            continue;
-        result.push(args[index]);
-    }
-    return result;
-}
-function lifecycleIds(authorityRef, taskId) {
-    const digest = (label) => createHash('sha256')
-        .update(`${label}\0${taskId}\0${authorityRef}`, 'utf8')
-        .digest('hex');
-    return { operationId: digest('operation'), lifecycleRequestId: digest('lifecycle-request') };
-}
-function lifecycleAuthorityIdentity(authorityRef, taskId, requestId, phase, family, artifact, round) {
-    const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
-    if (!authorityRef || !contextPath)
-        return undefined;
-    const routed = verifyCodexSandboxControllerContextWithWarnings(contextPath, { repoRoot: process.cwd() });
-    const buildIdentity = computeLifecycleBuildIdentity(process.cwd());
-    const hookDefinitionHash = createHash('sha256')
-        .update(readFileSync(path.join(process.cwd(), '.codex', 'hooks.json')))
-        .digest('hex');
-    const ids = lifecycleIds(authorityRef, taskId);
-    return {
-        version: 1,
-        requestId,
-        operationId: ids.operationId,
-        phase,
-        taskId,
-        family,
-        artifact,
-        round,
-        lifecycleRequestId: ids.lifecycleRequestId,
-        authorityRef,
-        expectedControlGeneration: routed.context.controlGeneration,
-        expectedControllerInstanceDigest: routed.context.controllerInstanceDigest,
-        expectedBuildIdentityDigest: createHash('sha256').update(JSON.stringify(buildIdentity)).digest('hex'),
-        expectedHookDefinitionHash: hookDefinitionHash
-    };
-}
-function lifecycleAuthoritySelector(args) {
-    if (!isCanonicalCodexPrepare(args))
-        return undefined;
-    const authorityRef = valueAfter(args, '--capability-ref');
-    const taskId = args[0];
-    if (!authorityRef || !taskId)
-        return undefined;
-    const routed = routeOrchestration(taskId);
-    if (!routed.next || !['analysis', 'plan', 'code'].includes(routed.next.stage))
-        return undefined;
-    return lifecycleAuthorityIdentity(authorityRef, taskId, randomUUID(), 'orchestration.prepare', routed.next.stage === 'analysis' ? 'analysis' : routed.next.stage === 'plan' ? 'plan' : 'code', routed.next.artifact, routed.next.round);
-}
-function lifecycleWorkflowAuthoritySelector(originalArgs, workflow) {
-    const authorityRef = valueAfter(originalArgs, '--capability-ref');
-    if (!authorityRef)
-        return undefined;
-    if (workflow.operation === 'artifact-finalize-local') {
-        const family = valueAfter(workflow.args, '--family');
-        const artifact = valueAfter(workflow.args, '--artifact');
-        const parsed = artifact ? parseArtifactName(artifact) : null;
-        if ((family !== 'analysis' && family !== 'plan' && family !== 'code')
-            || !parsed || parsed.family !== family)
-            return undefined;
-        return lifecycleAuthorityIdentity(authorityRef, workflow.taskId, workflow.id, 'artifact.finalize-local', family, artifact, parsed.round);
-    }
-    if (workflow.operation !== 'event')
-        return undefined;
-    const completed = /^(analysis|plan|code)\.completed$/u.exec(workflow.args[1] ?? '');
-    const artifact = valueAfter(workflow.args, '--artifact');
-    const parsed = artifact ? parseArtifactName(artifact) : null;
-    if (!completed || !parsed || parsed.family !== completed[1])
-        return undefined;
-    return lifecycleAuthorityIdentity(authorityRef, workflow.taskId, workflow.id, 'task-event.completed', completed[1], artifact, parsed.round);
-}
-function isCanonicalCodexPrepare(args) {
-    if (args[1] !== 'prepare')
-        return false;
-    const clients = [];
-    for (let index = 2; index < args.length; index += 1) {
-        if (args[index] === '--client')
-            clients.push(args[index + 1] ?? '');
-        else if (args[index]?.startsWith('--client='))
-            clients.push(args[index].slice('--client='.length));
-    }
-    return clients.length === 1 && clients[0] === 'codex';
-}
 function writeFinalizationEnvelope(status, accepted, error, changed = false, result = null) {
     process.stdout.write(`${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`);
 }
@@ -251,7 +143,7 @@ async function sandboxControl(args) {
             }
             let workflow;
             try {
-                const args = withoutValue(commandArgs.slice(1), '--capability-ref');
+                const args = commandArgs.slice(1);
                 if (/^\d+$/.test(args[0] ?? '')) {
                     const resolved = resolveVisibleActiveShortId(args[0]);
                     if (resolved !== taskId)
@@ -267,11 +159,7 @@ async function sandboxControl(args) {
             }
             let response;
             try {
-                const authority = lifecycleWorkflowAuthoritySelector(commandArgs, workflow);
-                response = requestSandboxTaskWorkflow({
-                    workflow,
-                    ...(authority ? { authority } : {})
-                });
+                response = requestSandboxTaskWorkflow({ workflow });
             }
             catch (error) {
                 if (!(error instanceof SandboxControlClientError))
@@ -287,22 +175,7 @@ async function sandboxControl(args) {
         }
         let response;
         try {
-            if (family === 'task-orchestration' && isCanonicalCodexPrepare(commandArgs)) {
-                const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
-                const proof = contextPath
-                    ? controllerProofFromContext(verifyCodexSandboxControllerContextWithWarnings(contextPath).context)
-                    : null;
-                const authority = lifecycleAuthoritySelector(commandArgs);
-                response = requestSandboxTaskControl({
-                    family,
-                    args: commandArgs,
-                    controllerProof: authority ? null : proof,
-                    ...(authority ? { authority } : {})
-                });
-            }
-            else {
-                response = requestSandboxControl({ family, args: commandArgs });
-            }
+            response = requestSandboxControl({ family, args: commandArgs });
         }
         catch (error) {
             if (!(error instanceof SandboxControlClientError))

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

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

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

@@ -50,6 +50,7 @@ function internalTaskRoutes() {
         descriptor('internal', 'platform-comment', 'recover', 'non-task', 'recovery', 'none'),
         descriptor('internal', 'platform-comment', 'owner', 'task-bound', 'diagnostic'),
         descriptor('internal', 'platform-comment', 'backfill', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-comment', 'stage-summary', 'task-bound', 'artifact-write'),
         descriptor('internal', 'platform-comment', 'sync', 'task-bound', 'remote-write'),
         descriptor('internal', 'platform-issue', 'inspect', 'task-bound', 'diagnostic'),
         descriptor('internal', 'platform-issue', 'create', 'task-bound', 'remote-write'),

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

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

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

@@ -135,12 +135,6 @@ function snapshotValidation(repoRoot, commit, options) {
                 cleanupError = error;
             }
         }
-        try {
-            git(repoRoot, ['worktree', 'prune']);
-        }
-        catch (error) {
-            cleanupError ??= error;
-        }
         try {
             fs.rmSync(tempRoot, { recursive: true, force: true });
         }

package/dist/lib/platform/comment-safety.js

@@ -171,6 +171,12 @@ function sanitizeMarkdownDocument(value, options = {}) {
 function canonicalizeCommentBody(value) {
     return sanitizeMarkdownDocument(value, { reservedMarkers: [CONTROL_MARKER_PATTERN] });
 }
+function canonicalizeSummaryBody(value) {
+    const sanitized = canonicalizeCommentBody(value);
+    return sanitized.ok
+        ? ok(`${sanitized.value.replace(/\n+$/, '')}\n`)
+        : sanitized;
+}
 function renderSafeCodeFence(value, language = '', reservedMarkers = [CONTROL_MARKER_PATTERN]) {
     const content = markerSafe(normalized(value), reservedMarkers);
     const longestRun = Math.max(0, ...(content.match(/`+/g) || []).map((run) => run.length));
@@ -225,5 +231,5 @@ function splitDocumentPlaceholder(value, placeholder) {
     }
     return ok({ prefix: source.slice(0, position), suffix: source.slice(position + placeholder.length) });
 }
-export { CONTROL_MARKER_PATTERN, escapeHtmlAttribute, escapeHtmlText, escapeMarkdownLiteral, fenceRanges, renderSafeCodeFence, canonicalizeCommentBody, sanitizeMarkdownDocument, splitDocumentPlaceholder };
+export { CONTROL_MARKER_PATTERN, escapeHtmlAttribute, escapeHtmlText, escapeMarkdownLiteral, fenceRanges, renderSafeCodeFence, canonicalizeCommentBody, canonicalizeSummaryBody, sanitizeMarkdownDocument, splitDocumentPlaceholder };
 //# sourceMappingURL=comment-safety.js.map

package/dist/lib/platform/github-provider.js

@@ -278,13 +278,14 @@ function issueSnapshot(value, graph) {
         displayUrl: value.url
     };
 }
-function commentSnapshot(value) {
+function commentSnapshot(value, createdSequence = null) {
     return {
         id: String(value.id),
         author: value.user?.login ? { id: String(value.user.login), name: String(value.user.login) } : null,
         body: String(value.body || ''),
         createdAt: String(value.created_at || ''),
-        updatedAt: String(value.updated_at || value.created_at || '')
+        updatedAt: String(value.updated_at || value.created_at || ''),
+        createdSequence
     };
 }
 function createReceipt(remoteId) {
@@ -555,7 +556,16 @@ function createGitHubOperations(client) {
             if (!response.ok)
                 return response;
             const values = Array.isArray(response.value) ? response.value.flatMap((entry) => Array.isArray(entry) ? entry : [entry]) : [];
-            return { ok: true, value: values.filter((entry) => entry && entry.id !== undefined).map(commentSnapshot) };
+            const comments = values.filter((entry) => entry && typeof entry === 'object');
+            let previous = 0;
+            const ordered = comments.length === values.length && comments.every((entry) => {
+                const id = Number(entry.id);
+                if (!Number.isSafeInteger(id) || id <= previous)
+                    return false;
+                previous = id;
+                return true;
+            });
+            return { ok: true, value: comments.map((comment) => commentSnapshot(comment, ordered ? Number(comment.id) : null)) };
         },
         async write({ context, parent, body, existingComment }) {
             const number = resourceIdentityNumber(parent);

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

@@ -10,7 +10,7 @@ import { resourceIdentityNumber } from './resource-identity.js';
 import { taskIssueIdentity, taskIssueIdentityError } from './task-identities.js';
 import { recordForArtifact, recordForCancel, recordForSummary, recordForTask, renderActivityRecoveryMetadata } from './activity-recovery.js';
 import { projectTaskComment } from './task-comment-projection.js';
-import { canonicalizeCommentBody, escapeHtmlText, fenceRanges, renderSafeCodeFence } from './comment-safety.js';
+import { canonicalizeCommentBody, canonicalizeSummaryBody, escapeHtmlText, fenceRanges, renderSafeCodeFence } from './comment-safety.js';
 function providerCommentId(id, provider) {
     return provider.identity?.comment === 'number' && /^\d+$/.test(id) ? Number(id) : id;
 }
@@ -373,6 +373,46 @@ 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] };
+}
+function summaryDigest(comment) {
+    const body = normalizeCommentContent(comment.body)
+        .replace(/^<!-- sync-issue:[^\n]+:summary -->\n## [^\n]+\n\n> [^\n]+\n\n/u, '')
+        .replace(/^<details><summary>恢复元数据<\/summary>[\s\S]*?<\/details>\n\n/u, '')
+        .replace(/\n---\n\*[^\n]*\*$/u, '');
+    const canonical = canonicalizeSummaryBody(body);
+    return canonical.ok ? createHash('sha256').update(canonical.value).digest('hex') : '';
+}
+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)
+        : unsupportedProviderOperation(provider, 'comments.list');
+}
 function validateRelatedMarkerSet(comments, prefix) {
     const markers = comments.map((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] || '');
     if (new Set(markers).size !== markers.length)
@@ -442,18 +482,7 @@ async function syncPlatformComment(taskRef, options) {
     if (!hasResolvedPlatformContext(context) || !loaded.ok)
         return context;
     const issue = resourceIdentityNumber(issueIdentityFromTask);
-    const listed = loaded.value.provider.comments?.list
-        ? await loaded.value.provider.comments.list({
-            context: providerOperationContext(loaded.value),
-            parent: issueIdentityFromTask
-        }).then((response) => response.ok
-            ? { ok: true, value: response.value.map((comment) => ({
-                    id: providerCommentId(comment.id, loaded.value.provider),
-                    body: comment.body,
-                    user: comment.author?.name ? { login: comment.author.name } : undefined
-                })) }
-            : response)
-        : unsupportedProviderOperation(loaded.value.provider, 'comments.list');
+    const listed = await listedComments(loaded.value.provider, loaded.value, issueIdentityFromTask);
     if (!listed.ok) {
         return platformResult(listed.error.retryable ? 'blocked' : 'failed', {
             ...contextFields(context), resource: { kind: 'issue', number: issue }, error: listed.error
@@ -481,6 +510,25 @@ async function syncPlatformComment(taskRef, options) {
             });
         }
     }
+    if (options.verifyOnly) {
+        if (options.kind !== 'summary' || !options.summaryAuthorization) {
+            return platformResult('failed', {
+                ...contextFields(context), resource: { kind: 'issue', number: issue },
+                error: { code: 'SUMMARY_VERIFICATION_INVALID', message: 'summary verification requires durable authorization', retryable: false }
+            });
+        }
+        const position = summaryPosition(listed.value, resolved.taskId);
+        if (!position.ok || !position.summary || summaryDigest(position.summary) !== options.summaryAuthorization.sha256) {
+            return platformResult('failed', {
+                ...contextFields(context), resource: { kind: 'issue', number: issue },
+                error: { code: 'SUMMARY_VERIFICATION_FAILED', message: 'summary marker, body digest, or managed comment order is invalid', retryable: true }
+            });
+        }
+        return platformResult('no-op', {
+            ...contextFields(context), changed: false, resource: { kind: 'issue', number: issue },
+            comment: { kind: options.kind, marker: desired[0].marker, ids: [position.summary.id], parts: 1 }, error: null
+        });
+    }
     // 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) => ({
@@ -555,6 +603,65 @@ async function syncPlatformComment(taskRef, options) {
         }
         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(refreshed.error.retryable ? '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(deleted.error.retryable ? '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(written.error.retryable ? '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(error.retryable ? 'blocked' : 'failed', {
+                    ...contextFields(context), resource: { kind: 'issue', number: issue }, operations, error
+                });
+            }
+        }
+    }
     const changed = operations.some((operation) => operation.status === 'applied');
     const result = platformResult(changed ? 'applied' : 'no-op', {
         ...contextFields(context),

package/dist/lib/platform/provider-contract.d.ts

@@ -87,6 +87,8 @@ type RemoteCommentSnapshot = {
     body: string;
     createdAt: string;
     updatedAt: string;
+    /** Strict creation order when the provider can prove it for this list snapshot. */
+    createdSequence: number | null;
 };
 type ChangeRequestSnapshot = {
     id: string;

package/dist/lib/platform/provider-validation.js

@@ -189,13 +189,18 @@ function issueType(value, label) {
 }
 function validateComment(value) {
     const item = record(value, 'comment');
-    exactKeys(item, ['id', 'author', 'body', 'createdAt', 'updatedAt'], 'comment');
+    exactKeys(item, ['id', 'author', 'body', 'createdAt', 'updatedAt', 'createdSequence'], 'comment');
     return {
         id: stringValue(item.id, 'comment.id'),
         author: author(item.author, 'comment.author'),
         body: stringValue(item.body, 'comment.body', true),
         createdAt: utcTimestamp(item.createdAt, 'comment.createdAt'),
-        updatedAt: utcTimestamp(item.updatedAt, 'comment.updatedAt')
+        updatedAt: utcTimestamp(item.updatedAt, 'comment.updatedAt'),
+        createdSequence: item.createdSequence === null ? null : (() => {
+            if (!Number.isSafeInteger(item.createdSequence) || Number(item.createdSequence) < 1)
+                throw new Error('comment.createdSequence must be a positive safe integer or null');
+            return Number(item.createdSequence);
+        })()
     };
 }
 function validateChangeRequest(value, expectedKind, requireIdentity = false) {

package/dist/lib/platform/verification-sync.js

@@ -11,7 +11,7 @@ import { planInLabelUpdate, validateInLabelMapping } from "./in-label-sync.js";
 import { readPrDeliveryFact } from "../task/pr-delivery-fact.js";
 import { providerError, providerOperationContext, resourceIdentityNumber, unsupportedProviderOperation } from "./provider-bridge.js";
 import { taskIssueIdentity } from "./task-identities.js";
-import { renderTaskCommentResult } from "./issue-comments.js";
+import { MARKERS, renderTaskCommentResult } from "./issue-comments.js";
 import { CONTROL_MARKER_PATTERN, canonicalizeCommentBody, renderSafeCodeFence, sanitizeMarkdownDocument } from "./comment-safety.js";
 const CHECK_TYPE = "platform-sync";
 const VERSION_LINE_REGEX = /^[0-9]+\.[0-9]+\.x$/;
@@ -258,7 +258,9 @@ async function fetchRemoteData(context, shared) {
     }
     return {
         issue,
-        comments: facts.value.comments.map((comment) => ({ id: comment.id, body: comment.body })),
+        comments: facts.value.comments.map((comment) => ({
+            id: comment.id, body: comment.body, createdSequence: comment.createdSequence
+        })),
         prComments,
         prLabels: changeRequest?.labels || null,
         issueType: issueSnapshot
@@ -320,6 +322,21 @@ function checkCommentMarker(context, remoteData, shared) {
     }
     const comment = findCommentByMarker(remoteData.comments, context.marker);
     if (comment) {
+        if (context.marker === MARKERS.summary(context.task.metadata.id)) {
+            const managed = remoteData.comments.filter((candidate) => {
+                const first = String(candidate.body || '').replace(/\r\n/g, '\n').split('\n', 1)[0] || '';
+                return first === MARKERS.task(context.task.metadata.id)
+                    || first === MARKERS.summary(context.task.metadata.id)
+                    || first.startsWith(`<!-- sync-issue:${context.task.metadata.id}:`);
+            });
+            if (managed.some((candidate) => !Number.isSafeInteger(candidate.createdSequence) || candidate.createdSequence < 1)) {
+                return shared.failResult(CHECK_TYPE, `Issue #${context.issueNumber} summary comment ordering is not provable`, "check_failed");
+            }
+            const summarySequence = comment.createdSequence;
+            if (!managed.every((candidate) => summarySequence >= candidate.createdSequence)) {
+                return shared.failResult(CHECK_TYPE, `Issue #${context.issueNumber} summary comment is not last among task-managed comments`, "check_failed");
+            }
+        }
         return shared.passResult(CHECK_TYPE, `Issue #${context.issueNumber} has expected comment marker`);
     }
     return shared.failResult(CHECK_TYPE, `Expected comment marker '${context.marker}' not found on Issue #${context.issueNumber}`, "check_failed");