@fitlab-ai/agent-infra 0.11.1 → 0.11.3

package/lib/internal/sandbox-control.ts

@@ -1,141 +1,14 @@
-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.ts';
 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';
 
@@ -263,66 +136,9 @@ async function sandboxControl(args: string[]): Promise<void> {
       sandboxFinalizationClient(commandArgs);
       return;
     }
-    if (family === 'task-workflow') {
-      const command = commandArgs[0] as Parameters<typeof createTaskWorkflowRequest>[0] | undefined;
-      const taskId = process.env.AGENT_INFRA_TASK_ID;
-      const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
-      if (!command || !taskId || !generation) {
-        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'SANDBOX_CONTROL_REQUEST_INVALID', message: 'task-workflow requires a bound task and generation' } })}\n`);
-        process.exitCode = 1;
-        return;
-      }
-      let workflow;
-      try {
-        const args = withoutValue(commandArgs.slice(1), '--capability-ref');
-        if (/^\d+$/.test(args[0] ?? '')) {
-          const resolved = resolveVisibleActiveShortId(args[0]!);
-          if (resolved !== taskId) throw new Error('SANDBOX_TASK_REF_MISMATCH');
-          args[0] = resolved;
-        }
-        workflow = createTaskWorkflowRequest(command, args, taskId, generation);
-      }
-      catch (error) {
-        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'SANDBOX_CONTROL_REQUEST_INVALID', message: error instanceof Error ? error.message : String(error) } })}\n`);
-        process.exitCode = 1;
-        return;
-      }
-      let response;
-      try {
-        const authority = lifecycleWorkflowAuthoritySelector(commandArgs, workflow);
-        response = requestSandboxTaskWorkflow({
-          workflow,
-          ...(authority ? { authority } : {})
-        });
-      }
-      catch (error) {
-        if (!(error instanceof SandboxControlClientError)) throw error;
-        writeClientError(error);
-        process.exitCode = error.detail.retryable ? 75 : 1;
-        return;
-      }
-      process.stdout.write(response.stdout);
-      process.stderr.write(response.stderr);
-      process.exitCode = response.phase === 'rejected' ? response.error?.retryable ? 75 : 1 : response.exitCode ?? 1;
-      return;
-    }
     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-lifecycle.ts

@@ -7,10 +7,10 @@ import {
 import { lifecycleIntentCatalog } from '../task/lifecycle.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
 import type { TaskLifecycleResult } from '../task/lifecycle.ts';
-import type { LifecycleRecoveryResult } from '../task/lifecycle-recovery.ts';
+import type { AgentClientLifecycleRecoveryResult as LifecycleRecoveryResult } from '../agent-clients/adapter.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nrecover-started: --stage <stage> --round <round> --artifact <artifact> --reason <reason>\nOverride: --override-ticket <ticket> --override-target <target> --override-scope <scope>\n`;
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nrecover-started: --auto\nOverride: --override-ticket <ticket> --override-target <target> --override-scope <scope>\n`;
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);

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

@@ -22,7 +22,7 @@ export type TaskOperationEffect = TaskViewAccessEffect;
 export type TaskRefSource = 'argv' | 'environment' | 'none' | 'delegated' | 'input';
 
 export type SandboxControlTransportDecision = Readonly<{
-  kind: 'direct-host' | 'broker-client' | 'fail-closed';
+  kind: 'direct-host' | 'sandbox-local' | 'broker-client' | 'fail-closed';
   reasonCode: string | null;
 }>;
 
@@ -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'),
@@ -276,6 +277,7 @@ export function resolveTaskOperation(
 export function resolveDelegatedTaskOperation(args: readonly string[]): TaskOperationDescriptor | null {
   const [operation, ...rest] = args;
   if (operation !== 'client' || !rest[0]) return null;
+  if (rest[0] === 'task-orchestration') return null;
   return resolveTaskOperation('internal', rest[0], rest.slice(1));
 }
 
@@ -339,7 +341,7 @@ function taskMarkerState(env: NodeJS.ProcessEnv): TaskMarkerState {
 
 export function resolveSandboxControlTransport(
   env: NodeJS.ProcessEnv = process.env,
-  options: Readonly<{ statusMountPath?: string }> = {}
+  options: Readonly<{ statusMountPath?: string; localWorkflow?: boolean }> = {}
 ): SandboxControlTransportDecision {
   const hasAnyMarker = TASK_MARKER_KEYS.some((key) => Boolean(env[key]))
     || Boolean(env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING)
@@ -406,13 +408,15 @@ export function resolveSandboxControlTransport(
     if (!hasCompleteConfig) {
       return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
     }
-    return { kind: 'broker-client', reasonCode: null };
+    return { kind: options.localWorkflow ? 'sandbox-local' : 'broker-client', reasonCode: null };
   }
   if (!hasAnyMarker) return { kind: 'direct-host', reasonCode: null };
   if (!hasCompleteConfig || (taskBound && !runtime) || (!taskBound && runtime)) {
     return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
   }
-  return { kind: 'broker-client', reasonCode: null };
+  return options.localWorkflow
+    ? { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_MISSING' }
+    : { kind: 'broker-client', reasonCode: null };
 }
 
 export function hasTaskBoundMarker(env: NodeJS.ProcessEnv = process.env): boolean {

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

@@ -33,7 +33,12 @@ import {
 } 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 +50,7 @@ type SyncOptions = {
   backfill?: boolean;
   client?: PlatformClient;
   runtimeVersion?: string;
+  summaryAuthorization?: { sha256: string };
 };
 
 function providerCommentId(id: string, provider: { identity?: { comment?: string } }): number | string {
@@ -68,8 +74,6 @@ const ARTIFACT_TITLES: Record<string, string> = {
   'review-plan': '技术方案审查',
   code: '实现报告',
   'review-code': '代码审查',
-  'manual-validation': '人工验证报告',
-  'validation-run': '验证运行证据',
   'pr-review': 'PR 审查报告'
 };
 
@@ -146,7 +150,7 @@ function taskCommentLanguage(repoRoot: string): string {
 
 function artifactIdentity(artifact: string): { stem: string; title: string } {
   const stem = path.basename(artifact, '.md');
-  const match = stem.match(/^(analysis|review-analysis|plan|review-plan|code|review-code|manual-validation|validation-run|pr-review)(?:-r(\d+))?$/);
+  const match = stem.match(/^(analysis|review-analysis|plan|review-plan|code|review-code|pr-review)(?:-r(\d+))?$/);
   if (!match) throw new Error(`unsupported artifact '${artifact}'`);
   const base = ARTIFACT_TITLES[match[1]!]!;
   const round = match[2] ? Number(match[2]) : 1;
@@ -457,6 +461,40 @@ 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]! };
+}
+
+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 +565,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,7 +596,6 @@ async function syncPlatformComment(taskRef: string, options: SyncOptions): Promi
     }
   }
 
-
   // 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): PlatformOperation => ({
@@ -646,6 +672,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/pr-summary.ts

@@ -35,7 +35,7 @@ import type {
   MechanicalChangeReport,
   PrChangeReport
 } from './pr-change-report.ts';
-import { manualValidationFinalSummaryProjectionMatches } from '../task/manual-validation-receipt.ts';
+import { MANUAL_VALIDATION_RECEIPT_PLACEHOLDER, manualValidationFinalSummaryProjectionMatches } from '../task/manual-validation-receipt.ts';
 import { readManualValidationCompletion } from '../task/manual-validation-completion.ts';
 
 type SummaryComment = { id: number | string; body: string };
@@ -582,6 +582,7 @@ async function syncPullRequestSummary(
       const initial = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
       if (!initial.ok) return fail(initial.status, context, initial.error);
       const manual = options.manualValidation;
+      let manualEvidenceDigest: string | null = null;
       const hasFinalManualValidation = /###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)/u.test(options.body);
       if (hasFinalManualValidation && (!manual || manual.phase !== 'final')) return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'final manual-validation summary requires the transaction coordinator', retryable: false }, prNumber);
       if (manual && (manual.phase === 'pending' ? hasFinalManualValidation : !hasFinalManualValidation)) return fail('failed', context, { code: 'MANUAL_VALIDATION_SUMMARY_PHASE_INVALID', message: 'manual-validation summary phase does not match the requested writer phase', retryable: false }, prNumber);
@@ -599,6 +600,7 @@ async function syncPullRequestSummary(
           });
           if (!completion.ok) return fail('failed', context, platformError(completion.error), prNumber);
           const { receipt, transaction } = completion.value;
+          manualEvidenceDigest = receipt.evidenceDigest;
           if (transaction.phase !== 'final-promotion-in-progress' || !transaction.eventAppended) return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'final summary requires a receipt-backed promotion intent', retryable: false }, prNumber);
           if (!manualValidationFinalSummaryProjectionMatches(options.body, receipt)) return fail('failed', context, { code: 'MANUAL_VALIDATION_SUMMARY_PROJECTION_INVALID', message: 'final summary body does not match the canonical receipt projection', retryable: false }, prNumber);
         }
@@ -635,7 +637,13 @@ async function syncPullRequestSummary(
       }
       const replaced = replaceCanonicalReportPlaceholder(`${prefix.value}${placeholder}${suffix.value}`, report.value);
       if (!replaced.ok) return fail('failed', context, platformError(replaced.error));
-      const desired = buildPullRequestSummary(resolved.taskId, replaced.value, initial.value.head.sha, renderHumanOverrideAudit(taskContent));
+      const renderedBody = manual?.phase === 'final'
+        ? replaced.value.replace(
+          MANUAL_VALIDATION_RECEIPT_PLACEHOLDER,
+          `<!-- manual-validation-receipt: transaction=${manual.transactionId}; receipt=${manual.receiptDigest}; evidence=${manualEvidenceDigest}; head=${manual.prHeadSha} -->`
+        )
+        : replaced.value;
+      const desired = buildPullRequestSummary(resolved.taskId, renderedBody, initial.value.head.sha, renderHumanOverrideAudit(taskContent));
       if (!isSafeSummaryEnvelope(desired, resolved.taskId)) return fail('failed', context, {
         code: 'PR_SUMMARY_RENDER_INVALID',
         message: 'Summary contains an invalid or duplicated reserved control marker',

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 = {

package/lib/platform/provider-validation.ts

@@ -218,13 +218,17 @@ function issueType(value: unknown, label: string): NonNullable<IssueSnapshot['is
 
 function validateComment(value: unknown): RemoteCommentSnapshot {
   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);
+    })()
   };
 }