@fitlab-ai/agent-infra 0.11.0 → 0.11.2

package/lib/internal/manual-validation.ts

@@ -44,6 +44,7 @@ function printFailure(format: OutputFormat, error: { code: string; message: stri
 }
 
 const MANUAL_VALIDATION_STATUS_SECTION = /^###\s+(?:⚠️\s+(?:需人工校验|Manual Validation Required)|✅\s+(?:人工验证已通过|无需人工校验|Manual Validation Passed|No Manual Validation Required)|⏳\s+(?:人工验证待收尾|Manual Validation Pending))\s*$[\s\S]*?(?=^#{1,3}\s|(?![\s\S]))/gmu;
+const TRAILING_CANONICAL_REPORT_PLACEHOLDER = /\n*<!--\s*canonical-pr-change-report\s*-->\s*$/u;
 
 function manualSummaryBody(body: string, phase: 'pending' | 'final', transactionId: string, receiptDigest = '', evidenceDigest = '', prHeadSha = ''): string {
   const chinese = /###\s+(?:⚠️\s+需人工校验|✅\s+(?:人工验证已通过|无需人工校验)|⏳\s+人工验证待收尾)\s*$/mu.test(body);
@@ -55,10 +56,13 @@ function manualSummaryBody(body: string, phase: 'pending' | 'final', transaction
       ? `### ✅ 人工验证已通过\n\n人工验证已通过；transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`
       : `### ✅ Manual Validation Passed\n\nManual validation passed; transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`;
   let inserted = false;
-  const updated = body.replace(MANUAL_VALIDATION_STATUS_SECTION, () => {
+  const updated = body.replace(MANUAL_VALIDATION_STATUS_SECTION, (matched) => {
     if (inserted) return '';
     inserted = true;
-    return `${section}\n\n`;
+    const trailingPlaceholder = TRAILING_CANONICAL_REPORT_PLACEHOLDER.exec(matched)?.[0];
+    return trailingPlaceholder
+      ? `${trailingPlaceholder.trim()}\n\n${section}\n\n`
+      : `${section}\n\n`;
   });
   return inserted ? `${updated.replace(/\s+$/u, '')}\n` : `${body.replace(/\s+$/u, '')}\n\n${section}\n`;
 }

package/lib/internal/platform-comment.ts

@@ -1,5 +1,6 @@
 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.ts';
 import {
@@ -8,15 +9,19 @@ import {
   syncPlatformComment
 } from '../platform/issue-comments.ts';
 import type { CommentKind } from '../platform/issue-comments.ts';
+import { canonicalizeSummaryBody } from '../platform/comment-safety.ts';
+import { platformResult } from '../platform/types.ts';
 import type { PlatformResult } from '../platform/types.ts';
 import { recoverTaskFromComments } from '../platform/task-recovery.ts';
 import { backfillCompletionComments } from '../platform/completion-backfill.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
 
 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>]
 `;
 
@@ -64,6 +69,7 @@ async function platformComment(args: string[] = []): Promise<void> {
     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'); return; }
   const hasTaskRef = operation !== 'list' && operation !== 'recover';
@@ -144,6 +150,38 @@ async function platformComment(args: string[] = []): Promise<void> {
     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: string;
+    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; }
   const kind = parsed.values.kind;
   const agent = parsed.values.agent;

package/lib/internal/sandbox-control.ts

@@ -1,11 +1,7 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import path from 'node:path';
 import {
   recoverSandboxControl,
   requestSandboxControl,
   requestSandboxTaskFinalization,
-  requestSandboxTaskControl,
   requestSandboxTaskWorkflow,
   resolveVisibleActiveShortId,
   SandboxControlClientError
@@ -13,129 +9,9 @@ import {
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import { serveSandboxControl } from '../sandbox/control/server.ts';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.ts';
-import {
-  controllerProofFromContext,
-  verifyCodexSandboxControllerContextWithWarnings
-} from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 import { parseTaskCreateResult, taskCreateExitCode } from '../task/create-service.ts';
 import { createTaskWorkflowRequest } from '../sandbox/control/task-workflow.ts';
-import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
-import { routeOrchestration } from '../task/orchestration.ts';
-import { parseArtifactName } from '../task/artifact-name.ts';
-import type { LifecycleAuthorityRequestV1 } from '../task/control-authority.ts';
-
-function valueAfter(args: readonly string[], flag: string): string | undefined {
-  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: readonly string[], flag: string): string[] {
-  const result: string[] = [];
-  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: string, taskId: string): Readonly<{ operationId: string; lifecycleRequestId: string }> {
-  const digest = (label: string) => createHash('sha256')
-    .update(`${label}\0${taskId}\0${authorityRef}`, 'utf8')
-    .digest('hex');
-  return { operationId: digest('operation'), lifecycleRequestId: digest('lifecycle-request') };
-}
-
-function lifecycleAuthorityIdentity(
-  authorityRef: string,
-  taskId: string,
-  requestId: string,
-  phase: LifecycleAuthorityRequestV1['phase'],
-  family: LifecycleAuthorityRequestV1['family'],
-  artifact: string,
-  round: number
-): LifecycleAuthorityRequestV1 | undefined {
-  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: readonly string[]): LifecycleAuthorityRequestV1 | undefined {
-  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: readonly string[],
-  workflow: ReturnType<typeof createTaskWorkflowRequest>
-): LifecycleAuthorityRequestV1 | undefined {
-  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] as LifecycleAuthorityRequestV1['family'], artifact!, parsed.round);
-}
-
-function isCanonicalCodexPrepare(args: readonly string[]): boolean {
-  if (args[1] !== 'prepare') return false;
-  const clients: string[] = [];
-  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';
-}
 
 type FinalizationStatus = 'completed' | 'failed' | 'blocked' | 'unknown';
 
@@ -274,7 +150,7 @@ async function sandboxControl(args: string[]): Promise<void> {
       }
       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) throw new Error('SANDBOX_TASK_REF_MISMATCH');
@@ -289,11 +165,7 @@ async function sandboxControl(args: string[]): Promise<void> {
       }
       let response;
       try {
-        const authority = lifecycleWorkflowAuthoritySelector(commandArgs, workflow);
-        response = requestSandboxTaskWorkflow({
-          workflow,
-          ...(authority ? { authority } : {})
-        });
+        response = requestSandboxTaskWorkflow({ workflow });
       }
       catch (error) {
         if (!(error instanceof SandboxControlClientError)) throw error;
@@ -308,21 +180,7 @@ async function sandboxControl(args: string[]): Promise<void> {
     }
     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)) throw error;
       writeClientError(error);

package/lib/internal/task-artifact.ts

@@ -1,7 +1,7 @@
 import { parseArtifactCommand, executeArtifactCommand } from '../task/artifact-command.ts';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.ts';
 
-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: string[] = []): void {

package/lib/internal/task-operation-registry.ts

@@ -90,6 +90,7 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     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/lib/internal/task-review.ts

@@ -5,7 +5,7 @@ import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.ts';
 
-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: string): void {
   process.stdout.write(`${JSON.stringify({
@@ -27,7 +27,7 @@ async function taskReview(args: string[] = []): Promise<void> {
   let request;
   try { request = parseReviewCommand(args); }
   catch (error) { 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) { failUsage(dryRunConflict.message); return; }
@@ -38,8 +38,8 @@ async function taskReview(args: string[] = []): Promise<void> {
   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) return current;
       if (!overrideTarget || !overrideScope) { failUsage('override ticket requires target and scope'); return current; }
@@ -49,7 +49,7 @@ async function taskReview(args: string[] = []): Promise<void> {
         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/lib/internal/task-validate.ts

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

package/lib/platform/comment-safety.ts

@@ -189,6 +189,13 @@ function canonicalizeCommentBody(value: string): SanitizationResult<string> {
   return sanitizeMarkdownDocument(value, { reservedMarkers: [CONTROL_MARKER_PATTERN] });
 }
 
+function canonicalizeSummaryBody(value: string): SanitizationResult<string> {
+  const sanitized = canonicalizeCommentBody(value);
+  return sanitized.ok
+    ? ok(`${sanitized.value.replace(/\n+$/, '')}\n`)
+    : sanitized;
+}
+
 function renderSafeCodeFence(value: string, language = '', reservedMarkers: readonly RegExp[] = [CONTROL_MARKER_PATTERN]): string {
   const content = markerSafe(normalized(value), reservedMarkers);
   const longestRun = Math.max(0, ...(content.match(/`+/g) || []).map((run) => run.length));
@@ -249,6 +256,7 @@ export {
   fenceRanges,
   renderSafeCodeFence,
   canonicalizeCommentBody,
+  canonicalizeSummaryBody,
   sanitizeMarkdownDocument,
   splitDocumentPlaceholder
 };

package/lib/platform/github-provider.ts

@@ -331,13 +331,14 @@ function issueSnapshot(value: any, graph?: { type: any; values: Array<{ name: st
   };
 }
 
-function commentSnapshot(value: any): RemoteCommentSnapshot {
+function commentSnapshot(value: any, createdSequence: number | null = null): RemoteCommentSnapshot {
   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 || '')
+    ,createdSequence
   };
 }
 
@@ -603,7 +604,15 @@ function createGitHubOperations(client: GitHubClient): Pick<PlatformProvider, 'i
       const response = client.json<any>(['api', '--paginate', '--slurp', `repos/${repository(context)}/issues/${number}/comments?per_page=100`], { cwd: context.workingDirectory });
       if (!response.ok) return response;
       const values = Array.isArray(response.value) ? response.value.flatMap((entry: any) => Array.isArray(entry) ? entry : [entry]) : [];
-      return { ok: true, value: values.filter((entry: any) => entry && entry.id !== undefined).map(commentSnapshot) };
+      const comments = values.filter((entry: any) => entry && typeof entry === 'object');
+      let previous = 0;
+      const ordered = comments.length === values.length && comments.every((entry: any) => {
+        const id = Number(entry.id);
+        if (!Number.isSafeInteger(id) || id <= previous) return false;
+        previous = id;
+        return true;
+      });
+      return { ok: true, value: comments.map((comment: any) => commentSnapshot(comment, ordered ? Number(comment.id) : null)) };
     },
     async write({ context, parent, body, existingComment }) {
       const number = resourceIdentityNumber(parent);

package/lib/platform/issue-comments.ts

@@ -27,13 +27,19 @@ import {
 import { projectTaskComment } from './task-comment-projection.ts';
 import {
   canonicalizeCommentBody,
+  canonicalizeSummaryBody,
   escapeHtmlText,
   fenceRanges,
   renderSafeCodeFence
 } from './comment-safety.ts';
 import type { FenceRange } from './comment-safety.ts';
 
-type RemoteComment = { id: number | string; body: string; user?: { login?: string } };
+type RemoteComment = {
+  id: number | string;
+  body: string;
+  user?: { login?: string };
+  createdSequence?: number | null;
+};
 type RenderedChunk = { marker: string; body: string; content: string; part: number; total: number };
 type CommentKind = 'task' | 'artifact' | 'summary' | 'cancel';
 type SyncOptions = {
@@ -45,6 +51,8 @@ type SyncOptions = {
   backfill?: boolean;
   client?: PlatformClient;
   runtimeVersion?: string;
+  summaryAuthorization?: { sha256: string };
+  verifyOnly?: boolean;
 };
 
 function providerCommentId(id: string, provider: { identity?: { comment?: string } }): number | string {
@@ -457,6 +465,49 @@ function relatedComments(comments: RemoteComment[], prefix: string): RemoteComme
   });
 }
 
+function taskManagedComment(comment: RemoteComment, taskId: string): boolean {
+  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: RemoteComment[], taskId: string): { ok: boolean; known: boolean; summary: RemoteComment | null } {
+  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: RemoteComment): string {
+  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: any, loaded: any, parent: ReturnType<typeof taskIssueIdentity>): Promise<any> {
+  return provider.comments?.list
+    ? provider.comments.list({ context: providerOperationContext(loaded), parent }).then((response: any) => response.ok
+      ? {
+          ok: true as const,
+          value: response.value.map((comment: any) => ({
+            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: RemoteComment[], prefix: string): { ok: boolean; code: string | null } {
   const markers = comments.map((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] || '');
   if (new Set(markers).size !== markers.length) return { ok: false, code: 'COMMENT_MARKER_CONFLICT' };
@@ -527,18 +578,7 @@ async function syncPlatformComment(taskRef: string, options: SyncOptions): Promi
   const context = loaded.ok ? loaded.value.context : loaded.context;
   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 as const, 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
@@ -569,6 +609,26 @@ async function syncPlatformComment(taskRef: string, options: SyncOptions): Promi
     }
   }
 
+  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) {
@@ -646,6 +706,65 @@ async function syncPlatformComment(taskRef: string, options: SyncOptions): Promi
     }
     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 as { remoteId: string }).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/lib/platform/issues.ts

@@ -574,9 +574,8 @@ async function syncPlatformIssue(taskRef: string, options: SyncOptions): Promise
   const failure = plan.operations.find((operation) => operation.status === 'failed');
   if (failure) return result('failed', base.resolved.taskId, base.issueNumber, { issue: snapshot, operations: plan.operations, error: { code: failure.reasonCode || 'ISSUE_SYNC_FAILED', message: `Operation ${failure.name} failed`, retryable: false } });
   const planned = plan.operations.filter((operation) => operation.status === 'planned');
-  const skipped = plan.operations.some((operation) => operation.status === 'skipped');
-  if (options.dryRun) return result(planned.length ? 'planned' : skipped ? 'degraded' : 'no-op', base.resolved.taskId, base.issueNumber, { issue: snapshot, operations: plan.operations, error: null });
-  if (planned.length === 0) return result(skipped ? 'degraded' : 'no-op', base.resolved.taskId, base.issueNumber, { issue: snapshot, operations: plan.operations, error: null });
+  if (options.dryRun) return result(planned.length ? 'planned' : 'no-op', base.resolved.taskId, base.issueNumber, { issue: snapshot, operations: plan.operations, error: null });
+  if (planned.length === 0) return result('no-op', base.resolved.taskId, base.issueNumber, { issue: snapshot, operations: plan.operations, error: null });
   const payload = applyRestOperations(snapshot, planned) as Partial<{
     title: string; body: string; labels: string[]; assignees: string[];
     milestone: string | null; state: 'open' | 'closed'; fields: Record<string, string | number | null>;
@@ -611,7 +610,7 @@ async function syncPlatformIssue(taskRef: string, options: SyncOptions): Promise
       error: { code: 'IN_LABEL_SYNC_PARTIAL', message: 'Issue labels did not converge after update', retryable: true }
     });
   }
-  return result(skipped ? 'degraded' : 'applied', base.resolved.taskId, base.issueNumber, {
+  return result('applied', base.resolved.taskId, base.issueNumber, {
     changed: updated.value.changed, platform: base.context.platform, capabilities: base.context.capabilities,
     resource: { kind: 'issue', number: base.issueNumber, identity: base.issueIdentity }, issue: finalIssue,
     operations: plan.operations.map((operation) => operation.status === 'planned' ? { ...operation, status: 'applied' } : operation), error: null

package/lib/platform/provider-contract.ts

@@ -84,6 +84,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 = {