@fitlab-ai/agent-infra 0.12.0 → 0.12.1

package/lib/platform/summary-content-pipeline.ts

@@ -0,0 +1,23 @@
+export type SummaryContentOperations<T> = Readonly<{
+  validate: (value: unknown) => T;
+  correct: (value: unknown) => unknown;
+  render: (value: T) => string;
+}>;
+
+function parse<T>(value: unknown, parser: (value: unknown) => T): T {
+  try {
+    return parser(value);
+  } catch (error) {
+    throw error instanceof Error ? error : new Error(String(error));
+  }
+}
+
+export function runSummaryContentPipeline<T>(
+  value: unknown,
+  operations: SummaryContentOperations<T>
+): Readonly<{ content: T; rendered: string }> {
+  try { parse(value, operations.validate); } catch { /* Source correction gets a chance to repair invalid structure. */ }
+  const corrected = operations.correct(value);
+  const content = parse(corrected, operations.validate);
+  return { content, rendered: operations.render(content) };
+}

package/lib/sandbox/removal.ts

@@ -73,6 +73,41 @@ function isMissingPathError(error: unknown): boolean {
     && (error as { code?: unknown }).code === 'ENOENT');
 }
 
+function removalErrorCode(error: unknown): string | null {
+  return error && typeof error === 'object' && 'code' in error
+    && typeof (error as { code?: unknown }).code === 'string'
+    ? (error as { code: string }).code
+    : null;
+}
+
+function removalErrorMessage(error: unknown): string {
+  const code = removalErrorCode(error);
+  const message = error instanceof Error ? error.message : String(error);
+  return code ? `${code}: ${message}` : message;
+}
+
+function addOwnerWriteToDirectories(root: string): void {
+  const pending = [root];
+  while (pending.length > 0) {
+    const current = pending.pop()!;
+    let stat: fs.Stats;
+    try {
+      stat = fs.lstatSync(current);
+    } catch (error) {
+      if (isMissingPathError(error)) continue;
+      throw error;
+    }
+    if (!stat.isDirectory()) continue;
+
+    fs.chmodSync(current, stat.mode | 0o200);
+    for (const entry of fs.readdirSync(current)) pending.push(path.join(current, entry));
+  }
+}
+
+function isPermissionRemovalError(error: unknown): boolean {
+  return ['EACCES', 'EPERM', 'ENOTEMPTY'].includes(removalErrorCode(error) ?? '');
+}
+
 function canonicalPath(input: string): string {
   try { return fs.realpathSync.native(input); }
   catch { return path.resolve(input); }
@@ -1011,7 +1046,25 @@ async function removeUncheckedSandbox(
     fs.rmSync(root, { recursive: true, force: true });
     removeEmptyManagedParent(path.join(config.workspaceViewBase, config.project), root);
   }
-  for (const candidate of toolCandidates.flatMap(({ candidates }) => candidates)) fs.rmSync(candidate, { recursive: true, force: true });
+  const toolRemovalFailures: string[] = [];
+  for (const candidate of toolCandidates.flatMap(({ candidates }) => candidates)) {
+    try {
+      fs.rmSync(candidate, { recursive: true, force: true });
+      continue;
+    } catch (initialError) {
+      if (isPermissionRemovalError(initialError)) {
+        try {
+          addOwnerWriteToDirectories(candidate);
+          fs.rmSync(candidate, { recursive: true, force: true });
+          continue;
+        } catch (retryError) {
+          toolRemovalFailures.push(`${candidate}: ${removalErrorMessage(initialError)}; retry failed: ${removalErrorMessage(retryError)}`);
+        }
+      } else {
+        toolRemovalFailures.push(`${candidate}: ${removalErrorMessage(initialError)}`);
+      }
+    }
+  }
   for (const shell of shellConfigDirCandidates(config, effectiveBranch)) fs.rmSync(shell, { recursive: true, force: true });
   if (shouldRemoveShare) fs.rmSync(sharePath, { recursive: true, force: true });
   if (shouldRemoveWorktree) {
@@ -1025,6 +1078,9 @@ async function removeUncheckedSandbox(
     assertBranchRemovalIdentity(config, effectiveBranch, worktreePermits);
     runSafe('git', ['-C', config.repoRoot, 'branch', '-D', effectiveBranch]);
   }
+  if (toolRemovalFailures.length > 0) {
+    throw new Error(`SANDBOX_TOOL_CLEANUP_INCOMPLETE:\n${toolRemovalFailures.map((failure) => `  - ${failure}`).join('\n')}`);
+  }
   releaseTaskBoundSandboxIdentity(config.repoRoot, target.workspace);
 
   if (!options.quiet) p.outro('Sandbox removed');

package/lib/task/finalization.ts

@@ -33,6 +33,7 @@ import {
 } from './operation-outcome.ts';
 import { readSandboxControlManifest } from '../sandbox/control/lifecycle.ts';
 import { validateSandboxControlIdentity } from '../sandbox/control/identity-sentinel.ts';
+import { parseDeliverySummaryContent, renderDeliverySummaryContent } from '../platform/issue-summary-content.ts';
 
 const RECEIPT_VERSION = 4 as const;
 const FINALIZATION_STEPS = ['lifecycle', 'task-comment', 'verification', 'summary'] as const;
@@ -730,16 +731,20 @@ function readDeliverySummary(taskDir: string, taskId: string): { body: string; s
   } catch {
     throw Object.assign(new Error('delivery summary staging record is unavailable'), { code: 'SUMMARY_STAGING_INVALID' });
   }
-  if (value.taskId !== taskId || typeof value.body !== 'string' || typeof value.sha256 !== 'string') {
+  if (value.taskId !== taskId || !value.content || typeof value.contentSha256 !== 'string') {
     throw Object.assign(new Error('delivery summary staging record is invalid'), { code: 'SUMMARY_STAGING_INVALID' });
   }
-  const canonical = canonicalizeSummaryBody(value.body);
-  if (!canonical.ok || canonical.value !== value.body) {
-    throw Object.assign(new Error('delivery summary staging body is not canonical'), { code: 'SUMMARY_STAGING_INVALID' });
+  let content;
+  try { content = parseDeliverySummaryContent(value.content); }
+  catch { throw Object.assign(new Error('delivery summary staging payload is invalid'), { code: 'SUMMARY_STAGING_INVALID' }); }
+  if (content.taskId !== taskId || createHash('sha256').update(JSON.stringify(content)).digest('hex') !== value.contentSha256) {
+    throw Object.assign(new Error('delivery summary staging digest does not match payload'), { code: 'SUMMARY_STAGING_INVALID' });
   }
+  const body = renderDeliverySummaryContent(content);
+  const canonical = canonicalizeSummaryBody(body);
+  if (!canonical.ok) throw Object.assign(new Error('delivery summary staging body is not canonical'), { code: 'SUMMARY_STAGING_INVALID' });
   const digest = createHash('sha256').update(canonical.value).digest('hex');
-  if (digest !== value.sha256) throw Object.assign(new Error('delivery summary staging digest does not match body'), { code: 'SUMMARY_STAGING_INVALID' });
-  return { body: canonical.value, sha256: value.sha256 };
+  return { body: canonical.value, sha256: digest };
 }
 
 async function syncPendingSummary(input: {

package/lib/task/platform-operation-recovery.ts

@@ -3,13 +3,15 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 
-import { inspectPlatformCommentOperation, normalizeCommentContent, syncPlatformComment } from '../platform/issue-comments.ts';
+import { inspectPlatformCommentOperation, syncPlatformComment } from '../platform/issue-comments.ts';
+import { parseDeliverySummaryContent, renderDeliverySummaryContent, parseCancelSummaryContent, renderCancelSummaryContent } from '../platform/issue-summary-content.ts';
+import { enumerateArtifacts } from './artifacts.ts';
 import { inspectPlatformIssue, syncPlatformIssue } from '../platform/issues.ts';
 import { resolvePlatformProviderContext } from '../platform/context.ts';
 import { providerOperationContext, providerError, unsupportedProviderOperation } from '../platform/provider-bridge.ts';
 import { inLabelMappingDigest } from '../platform/in-label-sync.ts';
-import { bindPlatformPullRequest, inspectPlatformPullRequest, recoverCreatedPullRequest, syncPlatformPullRequest } from '../platform/pull-requests.ts';
-import { syncPullRequestSummary } from '../platform/pr-summary.ts';
+import { bindPlatformPullRequest, recoverCreatedPullRequest, syncPlatformPullRequest } from '../platform/pull-requests.ts';
+import { replayPullRequestSummary } from '../platform/pr-summary.ts';
 import { publishPrReview, readReviewBodyFile } from '../platform/pr-review.ts';
 import type { PlatformClient } from '../platform/context.ts';
 import { parseTaskFrontmatter } from './frontmatter.ts';
@@ -53,33 +55,57 @@ function result(status: RecoveryResult['status'], recovered: string[], pending:
 function summaryPayload(taskDir: string, taskId: string): { body: string; sha256: string } | null {
   const file = path.join(taskDir, '.delivery-summary.json');
   if (!fs.existsSync(file)) return null;
-  const data = JSON.parse(fs.readFileSync(file, 'utf8')) as { taskId?: unknown; body?: unknown; sha256?: unknown };
-  const canonical = typeof data.body === 'string' ? canonicalizeSummaryBody(data.body) : null;
-  if (data.taskId !== taskId || typeof data.body !== 'string' || typeof data.sha256 !== 'string'
-    || !canonical?.ok || canonical.value !== data.body
-    || createHash('sha256').update(data.body).digest('hex') !== data.sha256) {
+  const data = JSON.parse(fs.readFileSync(file, 'utf8')) as { taskId?: unknown; content?: unknown; contentSha256?: unknown };
+  let content;
+  try { content = parseDeliverySummaryContent(data.content); }
+  catch { content = null; }
+  if (data.taskId !== taskId || !content || content.taskId !== taskId || typeof data.contentSha256 !== 'string'
+    || createHash('sha256').update(JSON.stringify(content)).digest('hex') !== data.contentSha256) {
     throw Object.assign(new Error('delivery summary staging record is invalid'), { code: 'SUMMARY_STAGING_INVALID' });
   }
-  return { body: data.body, sha256: data.sha256 };
+  const canonical = canonicalizeSummaryBody(renderDeliverySummaryContent(content));
+  if (!canonical?.ok) throw Object.assign(new Error('delivery summary staging body is not canonical'), { code: 'SUMMARY_STAGING_INVALID' });
+  return { body: canonical.value, sha256: createHash('sha256').update(canonical.value).digest('hex') };
+}
+
+function cancellationPayload(taskDir: string, taskId: string): string | null {
+  const taskPath = path.join(taskDir, 'task.md');
+  if (!fs.existsSync(taskPath)) return null;
+  const taskContent = fs.readFileSync(taskPath, 'utf8');
+  const frontmatter = parseTaskFrontmatter(taskContent);
+  const title = /^#\s+(.+)$/mu.exec(taskContent)?.[1]?.trim() || taskId;
+  const artifacts = enumerateArtifacts(taskDir).filter((artifact) => artifact.name !== 'task.md').map((artifact) => artifact.name);
+  const content = parseCancelSummaryContent({
+    taskId,
+    title,
+    outcome: 'cancelled',
+    reason: frontmatter.cancel_reason,
+    cancelledAt: frontmatter.cancelled_at,
+    lastCompletedArtifact: artifacts.at(-1) ?? null
+  });
+  return renderCancelSummaryContent(content);
 }
 
 async function replayComment(taskId: string, taskDir: string, operation: ReturnType<typeof readPlatformOperationJournal>['operations'][number], agent: string, cwd: string, client?: PlatformClient): Promise<PlatformResult> {
   if (operation.kind === 'task-comment') {
-    return syncPlatformComment(taskId, { kind: 'task', agent, cwd, client, dependency: operation.dependency, skipQueue: true });
+    return syncPlatformComment(taskId, { kind: 'task', agent, cwd, client, dependency: operation.dependency, queuedOperation: operation });
   }
   if (operation.kind === 'artifact-comment') {
-    return syncPlatformComment(taskId, { kind: 'artifact', artifact: operation.target, agent, cwd, client, dependency: operation.dependency, skipQueue: true });
+    return syncPlatformComment(taskId, { kind: 'artifact', artifact: operation.target, agent, cwd, client, dependency: operation.dependency, queuedOperation: operation });
   }
   if (operation.kind === 'summary-comment') {
-    const summary = summaryPayload(taskDir, taskId);
-    if (!summary) return platformResult('failed', { error: { code: 'SUMMARY_STAGING_MISSING', message: 'delivery summary staging record is unavailable', retryable: false } });
-    return syncPlatformComment(taskId, {
-      kind: 'summary', body: summary.body, agent, cwd,
-      summaryAuthorization: { sha256: summary.sha256 }, dependency: operation.dependency, client, skipQueue: true
-    });
+    let summary;
+    try { summary = summaryPayload(taskDir, taskId); }
+    catch (error) { return platformResult('failed', { error: { code: 'SUMMARY_STAGING_INVALID', message: error instanceof Error ? error.message : String(error), retryable: false } }); }
+    if (!summary) return platformResult('blocked', { error: { code: 'SUMMARY_STAGING_MISSING', message: 'delivery summary staging record is unavailable', retryable: true } });
+    return syncPlatformComment(taskId, { kind: 'summary', body: summary.body, agent, cwd, client, summaryAuthorization: { sha256: summary.sha256 }, dependency: operation.dependency, queuedOperation: operation });
   }
   if (operation.kind === 'cancel-comment') {
-    return syncPlatformComment(taskId, { kind: 'cancel', agent, cwd, client, dependency: operation.dependency, skipQueue: true });
+    let body: string | null;
+    try { body = cancellationPayload(taskDir, taskId); }
+    catch (error) { return platformResult('failed', { error: { code: 'CANCEL_SUMMARY_INVALID', message: error instanceof Error ? error.message : String(error), retryable: false } }); }
+    if (!body) return platformResult('blocked', { error: { code: 'CANCEL_SUMMARY_INVALID', message: 'Cancellation facts are unavailable for recovery', retryable: true } });
+    return syncPlatformComment(taskId, { kind: 'cancel', body, agent, cwd, client, dependency: operation.dependency, queuedOperation: operation });
   }
   return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_UNSUPPORTED', message: `operation kind '${operation.kind}' has no registered recovery handler`, retryable: false } });
 }
@@ -183,55 +209,6 @@ async function verifyIssueCreate(taskId: string, operation: ReturnType<typeof re
   return platformResult('no-op');
 }
 
-async function replayPullRequestSummary(taskId: string, operation: ReturnType<typeof readPlatformOperationJournal>['operations'][number], agent: string, cwd: string, client?: PlatformClient): Promise<PlatformResult> {
-  let identity;
-  try { identity = parseResourceIdentity(JSON.parse(operation.target), 'queued pull-request summary identity'); }
-  catch { return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Queued pull-request summary identity is invalid', retryable: false } }); }
-  const summary = operation.pullRequestSummary;
-  if (!summary) return platformResult('blocked', { error: {
-    code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Pull-request summary recovery content is missing', retryable: false
-  } });
-  const manualValidationHeading = /^###\s+(?:⏳\s+(?:Manual Validation Pending|人工验证待收尾)|✅\s+(?:Manual Validation Passed|人工验证已通过))\s*$/mu.test(summary.body);
-  if (manualValidationHeading && !summary.manualValidation) return platformResult('blocked', { error: {
-    code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'Queued manual-validation summary has no persisted transaction context', retryable: false
-  } });
-  const resolved = await resolvePlatformProviderContext({ cwd, client });
-  if (!resolved.ok) return resolved.context;
-  const listed = resolved.value.provider.comments?.list
-    ? await resolved.value.provider.comments.list({ context: providerOperationContext(resolved.value), parent: identity })
-    : unsupportedProviderOperation(resolved.value.provider, 'comments.list');
-  if (!listed.ok) return platformResult(providerErrorRetryable(listed.error.code) ? 'blocked' : 'failed', { error: providerError(listed.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') });
-  const marker = `<!-- sync-pr:${taskId}:summary -->`;
-  const summaries = listed.value.filter((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] === marker);
-  if (summaries.length > 1) return platformResult('blocked', { error: {
-    code: 'PR_SUMMARY_MARKER_AMBIGUOUS', message: 'Multiple pull-request comments contain the queued summary marker', retryable: false
-  } });
-  if (!summary.manualValidation && summaries.length === 1 && createHash('sha256').update(normalizeCommentContent(summaries[0]!.body)).digest('hex') === operation.expectedDigest) {
-    return platformResult('no-op');
-  }
-  const bound = await inspectPlatformPullRequest(taskId, { cwd, client });
-  if (!bound.pullRequest || !resourceIdentityEquals(bound.pullRequest.identity, identity)) return platformResult('blocked', { error: bound.error ?? {
-    code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Bound pull request differs from the queued summary target', retryable: false
-  } });
-  const replayed = await syncPullRequestSummary(taskId, {
-    agent,
-    cwd,
-    client,
-    body: summary.body,
-    changeReportFile: summary.changeReportFile,
-    ...(summary.manualValidation ? { manualValidation: summary.manualValidation } : {}),
-    primaryResult: 'no_op',
-    strict: true,
-    skipQueue: true
-  });
-  if ((replayed.status === 'applied' || replayed.status === 'no-op') && !replayed.error && replayed.warnings.length === 0) {
-    return platformResult(replayed.status, { changed: replayed.changed });
-  }
-  return platformResult('blocked', { error: replayed.error ?? {
-    code: 'PR_SUMMARY_RECOVERY_UNCONFIRMED', message: 'Pull-request summary replay did not confirm the requested remote state', retryable: true
-  } });
-}
-
 async function replayPullRequestReview(operation: ReturnType<typeof readPlatformOperationJournal>['operations'][number], agent: string, cwd: string, client?: PlatformClient): Promise<PlatformResult> {
   const intent = operation.pullRequestReview;
   if (!intent) return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Pull-request review recovery parameters are missing', retryable: false } });
@@ -280,6 +257,14 @@ async function replayPullRequest(taskId: string, operation: ReturnType<typeof re
   return recoverCreatedPullRequest(taskId, { agent, cwd, base: intent.baseRef || '', head: intent.headRef || '', skipQueue: true });
 }
 
+function isRecoveryEligible(operation: ReturnType<typeof readPlatformOperationJournal>['operations'][number], excludeId?: string): boolean {
+  if (operation.id === excludeId) return false;
+  if (operation.state === 'queued' || operation.state === 'pending' || operation.state === 'unknown') return true;
+  return operation.state === 'failed'
+    && operation.lastCode !== 'PLATFORM_OPERATION_SUPERSEDED'
+;
+}
+
 async function recoverPlatformOperationsOnce(
   taskRef: string,
   selection: 'required' | 'deferred' | 'all',
@@ -293,9 +278,7 @@ async function recoverPlatformOperationsOnce(
     const value = error as { code?: string; message?: string };
     return result('failed', [], [], { code: value.code || 'PLATFORM_OPERATION_JOURNAL_INVALID', message: value.message || String(error), retryable: false });
   }
-  const candidates = journal.operations.filter((operation) => operation.id !== options.excludeId
-    && (operation.state === 'queued' || operation.state === 'pending' || operation.state === 'unknown'
-      || (operation.state === 'failed' && operation.lastCode !== 'PLATFORM_OPERATION_SUPERSEDED')));
+  const candidates = journal.operations.filter((operation) => isRecoveryEligible(operation, options.excludeId));
   if (!candidates.length) return result('no-op', [], []);
   const head = candidates[0]!;
   if (selection !== 'all' && head.dependency !== selection) {
@@ -357,11 +340,18 @@ async function recoverPlatformOperationsOnce(
       const commentOptions = operation.kind === 'task-comment'
         ? { kind: 'task' as const, agent: options.agent, cwd: resolved.repoRoot, dependency: operation.dependency }
           : operation.kind === 'artifact-comment'
-          ? { kind: 'artifact' as const, artifact: operation.target, agent: options.agent, cwd: resolved.repoRoot, dependency: operation.dependency }
-          : operation.kind === 'summary-comment' ? (() => {
-            const summary = summaryPayload(resolved.taskDir, resolved.taskId);
-            return summary ? { kind: 'summary' as const, body: summary.body, agent: options.agent, cwd: resolved.repoRoot, summaryAuthorization: { sha256: summary.sha256 }, dependency: operation.dependency } : null;
-          })() : { kind: 'cancel' as const, agent: options.agent, cwd: resolved.repoRoot, dependency: operation.dependency };
+            ? { kind: 'artifact' as const, artifact: operation.target, agent: options.agent, cwd: resolved.repoRoot, dependency: operation.dependency }
+            : operation.kind === 'summary-comment' ? (() => {
+              try {
+                const summary = summaryPayload(resolved.taskDir, resolved.taskId);
+                return summary ? { kind: 'summary' as const, body: summary.body, agent: options.agent, cwd: resolved.repoRoot, summaryAuthorization: { sha256: summary.sha256 }, dependency: operation.dependency } : null;
+              } catch { return null; }
+            })() : (() => {
+              try {
+                const body = cancellationPayload(resolved.taskDir, resolved.taskId);
+                return body ? { kind: 'cancel' as const, body, agent: options.agent, cwd: resolved.repoRoot, dependency: operation.dependency } : null;
+              } catch { return null; }
+            })();
       const current = commentOptions ? inspectPlatformCommentOperation(resolved.taskId, commentOptions) : null;
       if (!current) {
         pending.push(operation.id);
@@ -383,20 +373,21 @@ async function recoverPlatformOperationsOnce(
       remote = operation.kind === 'issue-create'
         ? await verifyIssueCreate(resolved.taskId, operation, resolved.repoRoot)
         : operation.kind === 'pull-request-summary'
-        ? await replayPullRequestSummary(resolved.taskId, operation, options.agent, resolved.repoRoot, options.client)
+        ? await replayPullRequestSummary(resolved.taskId, targetOperation, { agent: options.agent, cwd: resolved.repoRoot, client: options.client })
         : operation.kind === 'pull-request-review'
         ? await replayPullRequestReview(operation, options.agent, resolved.repoRoot, options.client)
         : operation.kind === 'issue-metadata'
         ? await replayIssueMetadata(resolved.taskId, targetOperation, options.agent, resolved.repoRoot)
         : operation.kind === 'pull-request'
           ? await replayPullRequest(resolved.taskId, targetOperation, options.agent, resolved.repoRoot)
-          : await replayComment(resolved.taskId, resolved.taskDir, operation, options.agent, resolved.repoRoot);
+          : await replayComment(resolved.taskId, resolved.taskDir, targetOperation, options.agent, resolved.repoRoot, options.client);
     }
     catch (error) {
       const value = error as { code?: string; message?: string };
       remote = platformResult('blocked', { error: { code: value.code || 'PLATFORM_OPERATION_RECOVERY_FAILED', message: value.message || String(error), retryable: true } });
     }
     const succeeded = (remote.status === 'applied' || remote.status === 'no-op') && !remote.error;
+    const latestOperation = readPlatformOperationJournal(resolved.taskId, resolved.repoRoot).operations.find((item) => item.id === operation.id);
     try {
       recordPlatformOperation({
         taskRef: resolved.taskId,
@@ -411,7 +402,7 @@ async function recoverPlatformOperationsOnce(
         ...(operation.pullRequestReview ? { pullRequestReview: operation.pullRequestReview } : {}),
         dependency: operation.dependency,
         state: succeeded ? 'succeeded' : 'unknown',
-        lastCode: remote.error?.code ?? null
+        lastCode: remote.error?.code ?? latestOperation?.lastCode ?? null
       });
     } catch (error) {
       const value = error as { code?: string; message?: string };
@@ -441,9 +432,7 @@ async function recoverPlatformOperations(
     const value = error as { code?: string; message?: string };
     return result('failed', [], [], { code: value.code || 'PLATFORM_OPERATION_JOURNAL_INVALID', message: value.message || String(error), retryable: false });
   }
-  const eligible = (operation: typeof initial.operations[number]) => operation.id !== options.excludeId
-    && (operation.state === 'queued' || operation.state === 'pending' || operation.state === 'unknown'
-      || (operation.state === 'failed' && operation.lastCode !== 'PLATFORM_OPERATION_SUPERSEDED'));
+  const eligible = (operation: typeof initial.operations[number]) => isRecoveryEligible(operation, options.excludeId);
   const first = initial.operations.filter(eligible);
   if (!first.length) return result('no-op', [], []);
   const operationLimit = options.limit === undefined ? first.length : Math.max(1, options.limit);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/rules/pr-sync.en.md

@@ -25,7 +25,7 @@ agent-infra-internal platform-pr summary-sync {task-id} \
   --result {primary-result}
 ```
 
-Use only canonical inputs returned by the context command. The precheck must contain file evidence for six fixed checks; `formalReview` is always false and `needs-review` routes to `review-code`. Write the plain body with exactly one `<!-- canonical-pr-change-report -->` placeholder, without a report heading/JSON, marker, or SHA. The core validates the task-intent digest, bound PR identity, complete patch SHA, and mechanical totals before rendering the report, then owns `<!-- sync-pr:{task-id}:summary -->`, authoritative `<!-- last-commit: ... -->`, create/update/no-op behavior, and duplicate-marker conflicts. Missing, stale, invalid, or bypassed report input never publishes; summary failure never rolls back a PR or commit.
+Use only canonical inputs returned by the context command. The precheck must contain file evidence for six fixed checks; `formalReview` is always false and `needs-review` routes to `review-code`. Generate a typed JSON payload with `overview:string`, `tests:{state,detail}`, `review:{state,detail}`, `manualValidation:{state,detail}`, `humanDecisions:{open,resolved,detail}`, and `risks:string`. Detail fields are non-empty, counts are non-negative integers, and structure checks do not assess semantic quality. Use `not-started`/`pending` for tests that have not started, `none`/`not-observed`/`not-published` for absent or unobserved remote Reviews, and `pending` for manual validation that has not run. Human-decision counts come from the task ledger. The renderer supplies fixed sections and the canonical report placeholder. The core validates the task-intent digest, bound PR identity, complete patch SHA, and mechanical totals before rendering the report, then owns markers, HEAD metadata, and create/update/no-op behavior.
 
 The canonical comment envelope produced by the core is:
 
@@ -40,7 +40,9 @@ The canonical comment envelope produced by the core is:
 ### PR Code Changes
 ```
 
-Canonical inputs include `manual-validation.md`. The manual-validation section is one of `### ✅ Manual Validation Passed`, `### ⚠️ Manual Verification Required`, or `### ✅ No Manual Verification Needed`; `complete-manual-validation` refreshes the same summary in place. The PR code-change section uses authoritative base/head facts from `platform-pr inspect` and the complete `git diff --find-renames --numstat base...head`, reconciles runtime, test, skill/rule, template, documentation, and other categories, and explains renames, mechanical mirrors, and potentially unnecessary changes. The caller supplies the placeholder; the core renderer supplies the canonical `### PR Code Changes` section.
+Canonical inputs include `manual-validation.md`. The manual-validation `state` can be `required`, `pending`, `passed`, `none`/`not-required`, or `not-observed`. English headings such as `### ⚠️ Manual Verification Required`, `### ✅ Manual Validation Passed`, and `### ✅ No Manual Verification Needed` are documentation labels; the current renderer emits Chinese headings. `complete-manual-validation` refreshes the same summary in place. The PR code-change section uses authoritative base/head facts from `platform-pr inspect` and the complete `git diff --find-renames --numstat base...head`, reconciles runtime, test, skill/rule, template, documentation, and other categories, and explains renames, mechanical mirrors, and potentially unnecessary changes. The core renderer supplies the canonical `### PR Code Changes` section. After publishing, the core reads comments back and requires one summary marker with a body that exactly matches the canonical rendered body; mismatch or read failure uses the existing coordinator/recovery path.
+
+Examples include `required`, `pending`, `passed`, `none`/`not-required`, and `not-observed`; this list is illustrative, not exhaustive. The renderer also accepts `unavailable` and other non-empty states through its existing fallback. English headings below are documentation labels; the current renderer emits the stated Chinese headings. `required` retains each item, location, and reason under `### ⚠️ 需人工校验`. `pending` means validation has not started or remains incomplete and renders as `### ⏳ 人工验证待收尾`. `passed` (`### ✅ Manual Validation Passed` in this documentation; `### ✅ 人工验证已通过` from the renderer) is publishable only through the final `complete-manual-validation` coordinator after it writes a valid receipt. Preserve the receipt marker bound to the transaction, receipt, evidence, and current PR head; never infer passed status from summary text or another state. `none`/`not-required` renders as `### ✅ 无需人工校验` only when no manual item is required and carries no passed receipt. `not-observed` means the state has not been read and renders as `### ℹ️ 尚未读取人工校验状态`.
 
 ```bash
 agent-infra-internal task-warning {task-id} add --step {step} --severity WARNING \

package/templates/.agents/rules/pr-sync.zh-CN.md

@@ -18,17 +18,14 @@ PR 摘要的语义聚合由模型完成；任务意图 digest、完整三点 dif
 agent-infra-internal platform-pr summary-context {task-id}
 ```
 
-只使用返回的 canonical latest `plan*`、`review-plan*`、`code*`、`review-code*`、`manual-validation*`（包括 `manual-validation.md`）。模型据此生成 reviewer 摘要正文，至少包含：
+只使用返回的 canonical latest `plan*`、`review-plan*`、`code*`、`review-code*`、`manual-validation*`（包括 `manual-validation.md`）。模型生成 PR 专属 JSON payload：`overview:string`、`tests:{state,detail}`、`review:{state,detail}`、`manualValidation:{state,detail}`、`humanDecisions:{open,resolved,detail}`、`risks:string`。说明字段为非空字符串，计数为非负整数；结构校验不评价内容语义。
 
-- 变更摘要与实现范围
-- 测试结果
-- 审查历程与当前结论
-- 人工校验三态：`### ⚠️ 需人工校验`、`### ✅ 人工验证已通过` 或 `### ✅ 无需人工校验`
-- 变更摘要、实现范围、测试结果、审查历程和人工校验三态
-- 一个 `<!-- canonical-pr-change-report -->` 占位符；`### PR 代码增减` 由 core renderer 基于权威 diff 生成，调用方不自行写标题或统计
+测试尚未启动用 `not-started`/`pending`，暂无远端 Review 用 `none`/`not-observed`/`not-published`，待人工校验用 `pending`，不得渲染为通过或零值。决策计数来自当前任务账本。renderer 固定生成完整章节并加入一个 canonical 报告占位符；代码增减仍由现有 report renderer 输出。
 
 保留人工校验项时，每条写明校验内容、定位和只能人工完成的原因。
 
+例如可见状态包括 `required`、`pending`、`passed`、`none`/`not-required` 和 `not-observed`；这些是示例而非穷举。renderer 也接受 `unavailable` 及其他非空状态，并按现有 fallback 渲染。英文标题是文档标签；当前 renderer 输出下列中文标题：`required` 使用 `### ⚠️ 需人工校验` 并保留每项内容、定位和原因；`pending` 使用 `### ⏳ 人工验证待收尾`；`passed` 使用 `### ✅ 人工验证已通过`，但仅允许 `complete-manual-validation` 的 final coordinator 写入有效 receipt 后发布，并保留绑定 transaction、receipt、evidence 和当前 PR head 的凭据标记；不得根据摘要文字或其他状态推断通过。`none`/`not-required` 仅在无需人工校验时使用 `### ✅ 无需人工校验`，不附加通过凭据；`not-observed` 使用 `### ℹ️ 尚未读取人工校验状态`。
+
 core 最终包装出的 canonical 评论结构为：
 
 ```markdown
@@ -54,7 +51,7 @@ precheck 必须覆盖六项固定检查并提供文件证据；`formalReview`
 
 ## 发布
 
-把聚合后的纯正文写入 `{summary-body-file}`，不要自行添加 marker 或 commit SHA：
+把聚合后的 JSON payload 写入 `{summary-body-file}`，不要自行添加 marker 或 commit SHA：
 
 ```bash
 agent-infra-internal platform-pr summary-sync {task-id} \
@@ -63,7 +60,7 @@ agent-infra-internal platform-pr summary-sync {task-id} \
   --result {primary-result}
 ```
 
-正文必须恰好包含一次 `<!-- canonical-pr-change-report -->`，不得自行拼接报告标题/JSON、marker 或 last-commit。core 会重新校验任务意图 digest、绑定 PR identity、完整 patch SHA 和机械统计，由 renderer 生成报告段，再包装唯一 `<!-- sync-pr:{task-id}:summary -->` 和权威 `<!-- last-commit: ... -->`，分页查找 PR 普通评论：不存在则创建、正文变化则原地更新、无差异则 no-op、重复 marker 或报告失配则稳定失败。正文通过文件输入，调用方不得拼 shell/heredoc。
+core 校验结构后插入报告占位符，重新校验任务意图 digest、PR identity、完整 patch SHA 和机械统计，生成报告段，再包装 marker 与权威 HEAD。发布后使用 `comments.list` 回读并要求唯一 marker 和正文完全匹配；不符或读取失败沿用现有 coordinator/recovery。payload 通过文件输入，调用方不得拼 shell/heredoc。
 
 ## 结果回传
 

package/templates/.agents/skills/cancel-task/SKILL.en.md

@@ -83,7 +83,7 @@ If a valid `platform_issue_identity` exists, require `applied` / `no-op` without
 - Write the cancellation body to a temporary file and run `agent-infra-internal platform-comment sync {task-id} --kind cancel --body-file {path} --agent {standard-agent-token}`
 - Run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
 
-The cancellation comment must include at least:
+The cancellation comment JSON fields are `taskId`, `title`, `outcome:"cancelled"`, `reason`, `cancelledAt`, and `lastCompletedArtifact`, sourced from task identity, task.md, the recorded cancellation reason/time, and the current artifact registry (`null` when no completed artifact exists). It must include at least:
 - the cancellation reason
 - the selected `status:` label
 

package/templates/.agents/skills/cancel-task/SKILL.zh-CN.md

@@ -82,7 +82,7 @@ ls <task-workspace>/completed/{task-id}/task.md
 - 将取消正文写入临时文件，调用 `agent-infra-internal platform-comment sync {task-id} --kind cancel --body-file {path} --agent {standard-agent-token}`
 - 调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
 
-取消评论至少包含：
+取消评论 JSON 字段为 `taskId`、`title`、`outcome:"cancelled"`、`reason`、`cancelledAt`、`lastCompletedArtifact`，值来自任务身份、task.md、已记录取消原因与时间和当前 artifact registry；无已完成产物时用 `null`。取消评论至少包含：
 - 取消原因
 - 选定的 `status:` label
 

package/templates/.agents/skills/commit/reference/pr-summary-sync.en.md

@@ -3,7 +3,7 @@
 Run only when `{task-id}` is valid and task.md has a `bound/verified` `pr_delivery_fact`.
 
 1. Run `agent-infra-internal platform-pr summary-context {task-id}` to obtain canonical inputs and report status; rebuild a stale/missing sidecar through the `change-report` flow for the current head.
-2. Generate the plain summary body per `.agents/rules/pr-sync.md`, with exactly one `<!-- canonical-pr-change-report -->` placeholder, and write it to a temporary file.
+2. Generate the complete PR summary JSON payload per `.agents/rules/pr-sync.md` and write it to a temporary file.
 3. Run `agent-infra-internal platform-pr summary-sync {task-id} --agent {standard-agent-token} --body-file {summary-body-file} --change-report-file <task-workspace>/active/{task-id}/pr-change-report.json --result no_op`. The commit path only synchronizes an existing PR summary and neither creates nor reuses a PR, so `no_op` explicitly represents the unchanged PR identity.
 
 Failure records a warning but never blocks or rolls back the completed commit. `no-op` maps to `summary skipped (no diff)`.

package/templates/.agents/skills/commit/reference/pr-summary-sync.zh-CN.md

@@ -3,7 +3,7 @@
 仅当 `{task-id}` 有效且 `task.md` 存在 `bound/verified` 的 `pr_delivery_fact` 时执行；否则跳过。
 
 1. 调用 `agent-infra-internal platform-pr summary-context {task-id}` 获取 canonical 聚合输入和报告状态；sidecar stale/missing 时先按 `change-report` 流程重建当前 head 报告。
-2. 按 `.agents/rules/pr-sync.md` 生成只含一次 `<!-- canonical-pr-change-report -->` 的纯摘要正文并写入临时文件。
+2. 按 `.agents/rules/pr-sync.md` 生成完整 PR 摘要 JSON payload 并写入临时文件；字段和零值状态由内容合同规定。
 3. 调用 `agent-infra-internal platform-pr summary-sync {task-id} --agent {standard-agent-token} --body-file {summary-body-file} --change-report-file <task-workspace>/active/{task-id}/pr-change-report.json --result no_op`。commit 路径只同步已有 PR 摘要，不创建或复用 PR，因此固定使用 `no_op` 表示 PR 身份未变化。
 
 同步失败只记录 warning，不阻塞或回滚已经完成的 commit。`no-op` 回传 `summary skipped (no diff)`。

package/templates/.agents/skills/complete-manual-validation/reference/summary-update.en.md

@@ -4,7 +4,7 @@ Run only for a valid `{task-id}` whose task.md binds a verified `pr_delivery_fac
 
 Follow `.agents/rules/pr-sync.md` for the shared summary structure and failure semantics.
 
-1. Run `agent-infra-internal platform-pr summary-context {task-id}` to obtain the canonical summary body; the maintainer's PR validation comment and validation summary are the human-validation authority.
+1. Run `agent-infra-internal platform-pr summary-context {task-id}` to obtain canonical summary facts. `--summary-file` uses the complete PR summary JSON payload; the maintainer's PR validation comment and validation summary are the human-validation authority.
 2. Before creating the canonical `manual-validation*` artifact, call the transaction coordinator in prepare mode to record `started` before writing the prepared transaction:
 
 ```bash
@@ -13,7 +13,7 @@ agent-infra-internal manual-validation transaction {task-id} --prepare \
   --summary-file {summary-body-file} --agent {standard-agent-token}
 ```
 
-3. After prepare succeeds, write the canonical `manual-validation*` artifact, write the pending plain body with exactly one `<!-- canonical-pr-change-report -->` placeholder to a temporary file, and run the transaction coordinator:
+3. After prepare succeeds, write the canonical `manual-validation*` artifact, set the JSON payload's `manualValidation.state` to `pending` with a non-empty explanation, and run the transaction coordinator:
 
 ```bash
 agent-infra-internal manual-validation transaction {task-id} \

package/templates/.agents/skills/complete-manual-validation/reference/summary-update.zh-CN.md

@@ -4,7 +4,7 @@
 
 摘要结构与失败语义统一遵循 `.agents/rules/pr-sync.md`。
 
-1. 调用 `agent-infra-internal platform-pr summary-context {task-id}`，取得 canonical 摘要正文；维护者提供的 PR 人工验证留言和验证说明作为完成人工校验依据。
+1. 调用 `agent-infra-internal platform-pr summary-context {task-id}`，取得 canonical 摘要事实；`--summary-file` 使用完整 PR 摘要 JSON payload，维护者提供的 PR 人工验证留言和验证说明作为完成人工校验依据。
 2. 在创建 canonical `manual-validation*` artifact 前，调用 transaction coordinator 的 prepare 模式，先登记 started，再写 prepared transaction：
 
 ```bash
@@ -13,7 +13,7 @@ agent-infra-internal manual-validation transaction {task-id} --prepare \
   --summary-file {summary-body-file} --agent {standard-agent-token}
 ```
 
-3. prepare 成功后写入 canonical `manual-validation*` artifact，并把只含一次 `<!-- canonical-pr-change-report -->` 的 pending 正文写入临时文件，调用 transaction coordinator：
+3. prepare 成功后写入 canonical `manual-validation*` artifact，并将 JSON payload 中 `manualValidation` 设置为 `pending`、提供非空说明后写入临时文件，调用 transaction coordinator：
 
 ```bash
 agent-infra-internal manual-validation transaction {task-id} \

package/templates/.agents/skills/complete-task/SKILL.en.md

@@ -18,8 +18,7 @@ Host finalization uses receipt v4 with an immutable `receiptId`, monotonic `revi
 
 Before generating a completion report or synchronized content, read `.agents/rules/evidence-reporting.md`. Successful checks record the command, scope, status or structured result, actual result, and uncovered parts; failures, blocking conditions, or disputes retain a reproducible entry point, exact location, and decisive excerpt.
 
-- This command updates task metadata AND physically moves the task directory
-- Do not move a task that has incomplete workflow steps unless forced
+- Host finalization updates task metadata and atomically moves the task directory
 - The entry point accepts optional `--external-pr <N>` only to select among ambiguous external-delivery candidates; it never bypasses identity or platform gates
 
 Version stamp rule: when creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.
@@ -142,7 +141,7 @@ Check whether task.md has a valid `platform_issue_identity`. If it does not, ski
 When a valid `platform_issue_identity` exists, execute in this exact order:
 
 1. Run `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --requirements --fields`.
-2. Write the business summary to a temporary file and run `agent-infra-internal platform-comment stage-summary {task-id} --body-file {path}`. This stores the body and SHA-256 in the task's durable staging record; it must not publish the summary comment directly.
+2. Write the completion summary as JSON fields `taskId`, `title`, `summary`, `artifacts`, and `verification:{state,detail}`, then run `agent-infra-internal platform-comment stage-summary {task-id} --body-file {path}`. Use the current artifact registry (`[]` when empty). If final verification has not run, use `state:"not-run"` with a non-empty explanation. The command persists the normalized payload; do not publish the summary comment in this step.
 
 The summary body records only delivery results, the associated PR and actual merge facts, verification commands with their scope/results/uncovered areas, and known todo items supported by current task evidence. Include the related commit when it helps explain verification scope. Do not infer unsupported facts; list unfinished work as a todo. This is an Issue closeout summary, not a PR comment.
 
@@ -225,32 +224,18 @@ ai sandbox rm {task-id}  # or use the task's retained short id
 
 ## Completion Checklist
 
-- [ ] Verified all workflow steps are complete
-- [ ] Updated task.md with completed status and timestamp
-- [ ] Moved task directory to `<task-workspace>/completed/`
-- [ ] Verified move succeeded
-- [ ] Informed user of completion
+- [ ] Hard prerequisites are satisfied and the pre-completion gate passes
+- [ ] Host finalization returns `result=completed` or `result=completed_with_warnings`
+- [ ] Completion verification passes
+- [ ] The structured completion result and applicable warnings are reported to the user
 
 ## Notes
 
-1. **Premature completion**: Do not move a task that has incomplete steps. Examples of incomplete situations:
-   - Code is written but not committed
-   - Code is committed but not reviewed
-   - Review found blockers that haven't been fixed
-   - PR is created but not merged
-   - Manual validation items are incomplete
-
-2. **Rollback**: If a task was incorrectly moved:
-   ```bash
-   mv <task-workspace>/completed/{task-id} <task-workspace>/active/{task-id}
-   ```
-   Then update task.md status back to `active`.
-
-3. **Multiple contributors**: If multiple AI agents worked on the task, ensure all contributions are committed before completing.
+- When multiple AI agents contributed, ensure all contributions are included in the local checkpoint.
 
 ## Error Handling
 
 - Task not found: Prompt "Task {task-id} not found in active directory"
-- Already completed: Prompt "Task {task-id} is already in completed directory"
-- Task is blocked: Prompt "Task {task-id} is blocked. Unblock it first by moving to active/"
-- Move failed: Prompt error and suggest manual move
+- Already completed: Enter `finalization-retry` only when a matching Complete Task Activity Log exists; otherwise report incomplete terminal identity and stop
+- Task is blocked: Satisfy the recorded unblock condition, then reactivate it through `task-lifecycle activate` before retrying
+- Finalization failed or blocked: Preserve source data and the receipt, then recover through the same finalization entry point using its structured error; do not manually rewrite terminal state or move the task directory