@fitlab-ai/agent-infra 0.9.12 → 0.9.13

package/lib/task/events.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 
 import { appendActivityEntry, locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
 import {
@@ -12,7 +13,7 @@ import {
   validateCompletedArtifact
 } from './artifact-lifecycle.ts';
 import type { ArtifactContextResult, ArtifactErrorCode, ArtifactFamily, ArtifactIdentity } from './artifact-lifecycle.ts';
-import { ArtifactReceiptError, sha256File, upsertArtifactReceipt } from './artifact-receipts.ts';
+import { ArtifactReceiptError, parseArtifactReceipts, sha256File, upsertArtifactReceipt } from './artifact-receipts.ts';
 import type { ArtifactReceipt } from './artifact-receipts.ts';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
 import {
@@ -33,6 +34,20 @@ import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskOperationSummary, TaskWriteErrorCode, TaskWriteOptions } from './write.ts';
 import { allowsManualOverride } from './guard-override.ts';
+import {
+  LOCAL_ARTIFACT_REQUIRED_PATTERNS,
+  LOCAL_ARTIFACT_REQUIRED_SECTIONS,
+  consumeLocalArtifactFinalizationIntent,
+  readLocalArtifactFinalizationIntent,
+  validateLocalArtifact
+} from './local-artifact-finalization.ts';
+import type { LocalArtifactFamily, LocalArtifactFinalizationIntent } from './local-artifact-finalization.ts';
+import { loadVerificationConfig } from './verification-config.ts';
+import { buildLifecycleFacts, canStart } from './capabilities.ts';
+import type { ExplicitTrigger, LifecycleAction, TriggerInitiator, TriggerReason } from './capabilities.ts';
+import { createInvalidationOperation, invalidationMutation, parseInvalidationDocument, targetIdFor, upsertInvalidation } from './invalidation.ts';
+import type { InvalidationTargetKind } from './invalidation.ts';
+import { consumeReworkIntents, parseReworkIntentDocument, reworkIntentMutation, supersedeReworkIntents } from './rework-intent.ts';
 
 const eventCatalog = [
   'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
@@ -48,6 +63,7 @@ type TaskEventName = (typeof eventCatalog)[number];
 type Verdict = 'approved' | 'changes-requested' | 'rejected';
 type TaskEventErrorCode =
   | 'EVENT_UNKNOWN' | 'EVENT_PAYLOAD_INVALID' | 'EVENT_TRANSITION_INVALID'
+  | 'EVENT_TRIGGER_REQUIRED'
   | 'EVENT_LOG_MISSING' | 'EVENT_START_MISSING' | 'EVENT_ALREADY_COMPLETED'
   | 'EVENT_LOG_CONFLICT' | 'EVENT_ARTIFACT_CONFLICT' | 'EVENT_FINDING_COUNT_MISMATCH'
   | 'EVENT_VERDICT_INVALID'
@@ -56,7 +72,10 @@ type TaskEventErrorCode =
 type TaskEventRequest = {
   taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean; orchestrated?: boolean;
   overrideTicket?: string; overrideTarget?: string; overrideScope?: string;
+  initiator?: TriggerInitiator; requestId?: string; reasonCode?: TriggerReason;
+  sourceFinding?: string; sourceArtifact?: string; sourceSha256?: string;
   round?: number; question?: number; artifact?: string; fixFor?: string; implementationInput?: string;
+  artifactSha256?: string; semanticDigest?: string;
   verdict?: Verdict; blockers?: number; major?: number; minor?: number;
   manualValidation?: number; filesModified?: number; testsPassed?: number;
   summaryResult?: string;
@@ -77,19 +96,19 @@ type TaskEventResult = {
   operations: readonly TaskOperationSummary[]; error: TaskEventError | null;
 };
 
-const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope']);
+const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope', 'initiator', 'requestId', 'reasonCode', 'sourceFinding', 'sourceArtifact', 'sourceSha256']);
 const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[] }> = {
   'analyze.started': { optional: ['round'] },
   'analyze.awaiting-input': { required: ['question'] },
-  'analyze.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
+  'analyze.completed': { required: ['artifact', 'artifactSha256', 'semanticDigest'], optional: ['round', 'orchestrated'] },
   'review-analysis.started': { optional: ['round'] },
   'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'plan.started': { optional: ['round'] },
-  'plan.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
+  'plan.completed': { required: ['artifact', 'artifactSha256', 'semanticDigest'], optional: ['round', 'orchestrated'] },
   'review-plan.started': { optional: ['round'] },
   'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'code.started': { optional: ['round', 'fixFor', 'implementationInput'] },
-  'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation', 'orchestrated'] },
+  'code.completed': { required: ['artifact', 'artifactSha256', 'semanticDigest'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation', 'orchestrated'] },
   'review-code.started': { optional: ['round'] },
   'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'manual-validation.started': { optional: ['round'] },
@@ -98,6 +117,30 @@ const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[]
   'validation-run.completed': { required: ['artifact'], optional: ['round'] }
 };
 
+function localArtifactValidationConfig(repoRoot: string, family: LocalArtifactFamily) {
+  const fallback = {
+    requiredSections: LOCAL_ARTIFACT_REQUIRED_SECTIONS[family],
+    requiredPatterns: LOCAL_ARTIFACT_REQUIRED_PATTERNS
+  };
+  const skillName = family === 'analysis' ? 'analyze-task' : family === 'plan' ? 'plan-task' : 'code-task';
+  try {
+    const artifact = loadVerificationConfig(repoRoot, skillName).checks.artifact;
+    if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) return fallback;
+    const sections = artifact.required_sections;
+    const patterns = artifact.required_patterns;
+    return {
+      requiredSections: Array.isArray(sections)
+        ? sections.filter((value): value is string => typeof value === 'string')
+        : fallback.requiredSections,
+      requiredPatterns: Array.isArray(patterns)
+        ? patterns.filter((value): value is string => typeof value === 'string')
+        : fallback.requiredPatterns
+    };
+  } catch {
+    return fallback;
+  }
+}
+
 function validateTaskEventRequest(request: TaskEventRequest): TaskEventError | null {
   if (!eventCatalog.includes(request.event as TaskEventName)) return { code: 'EVENT_UNKNOWN', message: `unknown task event '${request.event}'` };
   if (!request.taskRef || !request.agent) return { code: 'EVENT_PAYLOAD_INVALID', message: 'taskRef and agent are required' };
@@ -113,6 +156,13 @@ function validateTaskEventRequest(request: TaskEventRequest): TaskEventError | n
     if (value !== undefined && (!Number.isInteger(value) || value < (key === 'round' || key === 'question' ? 1 : 0))) return { code: 'EVENT_PAYLOAD_INVALID', message: `'${key}' must be a ${key === 'round' || key === 'question' ? 'positive' : 'non-negative'} integer` };
   }
   if (request.verdict && !['approved', 'changes-requested', 'rejected'].includes(request.verdict)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'verdict is invalid' };
+  if (request.initiator && !['human', 'model', 'orchestrator'].includes(request.initiator)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'initiator is invalid' };
+  if (request.requestId !== undefined && (!request.requestId.trim() || /[\r\n]/.test(request.requestId))) return { code: 'EVENT_PAYLOAD_INVALID', message: 'requestId must be a non-empty single line' };
+  if (request.reasonCode && !['user-request', 'new-requirement', 'upstream-fact-doubt', 'review-finding', 'retry', 'validation-rerun'].includes(request.reasonCode)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'reasonCode is invalid' };
+  for (const [name, value] of [['sourceFinding', request.sourceFinding], ['sourceArtifact', request.sourceArtifact], ['sourceSha256', request.sourceSha256]] as const) {
+    if (value !== undefined && (!value.trim() || /[\r\n]/.test(value))) return { code: 'EVENT_PAYLOAD_INVALID', message: `${name} must be a non-empty single line` };
+  }
+  if (request.sourceSha256 !== undefined && !/^[a-f0-9]{64}$/.test(request.sourceSha256)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'sourceSha256 must be a sha256 digest' };
   if (request.event === 'code.completed') {
     const fix = request.fixFor !== undefined || ['blockers', 'major', 'minor', 'manualValidation'].some((key) => request[key as keyof TaskEventRequest] !== undefined);
     const modeRequired = fix ? ['fixFor', 'blockers', 'major', 'minor', 'manualValidation'] : ['filesModified', 'testsPassed'];
@@ -121,20 +171,27 @@ function validateTaskEventRequest(request: TaskEventRequest): TaskEventError | n
   }
   if (request.fixFor && !/^review-code(?:-r(?:[2-9]|[1-9]\d+))?\.md$/.test(request.fixFor)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor must reference a canonical review-code artifact' };
   if (request.implementationInput && !/^II-[1-9]\d*$/.test(request.implementationInput)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'implementationInput must be a canonical II-N id' };
+  if (request.artifactSha256 !== undefined && !/^[0-9a-f]{64}$/i.test(request.artifactSha256)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'artifactSha256 must be a 64-character hexadecimal digest' };
+  if (request.semanticDigest !== undefined && !/^[0-9a-f]{64}$/i.test(request.semanticDigest)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'semanticDigest must be a 64-character hexadecimal digest' };
   if (request.fixFor && request.implementationInput) return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor and implementationInput are mutually exclusive' };
   if (request.summaryResult !== undefined && (!request.summaryResult.trim() || /[\r\n]/.test(request.summaryResult))) return { code: 'EVENT_PAYLOAD_INVALID', message: 'summaryResult must be a non-empty single line' };
+  if (request.event !== 'analyze.awaiting-input' && /\.(?:started|completed)$/.test(request.event)) {
+    if (!request.initiator || !request.requestId || !request.reasonCode) {
+      return { code: 'EVENT_TRIGGER_REQUIRED', message: `${request.event} requires --initiator, --request-id, and --reason-code` };
+    }
+  }
   return null;
 }
 
 const FAMILY = {
-  analyze: { artifact: 'analysis', started: ['requirement-analysis', 'requirement-analysis-review', 'code'], completed: ['requirement-analysis', 'requirement-analysis-review', 'code'], target: 'requirement-analysis', label: 'Analyze Task' },
-  'review-analysis': { artifact: 'review-analysis', started: ['requirement-analysis', 'requirement-analysis-review'], completed: ['requirement-analysis', 'requirement-analysis-review'], target: 'requirement-analysis-review', label: 'Review Analysis' },
-  plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review', 'commit'], completed: ['requirement-analysis-review', 'technical-design-review', 'commit'], target: 'technical-design', label: 'Plan Task' },
-  'review-plan': { artifact: 'review-plan', started: ['technical-design', 'technical-design-review'], completed: ['technical-design', 'technical-design-review'], target: 'technical-design-review', label: 'Review Plan' },
-  code: { artifact: 'code', started: ['technical-design-review', 'code-review'], completed: ['technical-design-review', 'code-review'], target: 'code', label: 'Code Task' },
-  'review-code': { artifact: 'review-code', started: ['code', 'code-review', 'commit'], completed: ['code', 'code-review', 'commit'], target: 'code-review', label: 'Review Code' },
-  'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' },
-  'validation-run': { artifact: 'validation-run', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Run Manual Validation' }
+  analyze: { artifact: 'analysis', target: 'requirement-analysis', label: 'Analyze Task' },
+  'review-analysis': { artifact: 'review-analysis', target: 'requirement-analysis-review', label: 'Review Analysis' },
+  plan: { artifact: 'plan', target: 'technical-design', label: 'Plan Task' },
+  'review-plan': { artifact: 'review-plan', target: 'technical-design-review', label: 'Review Plan' },
+  code: { artifact: 'code', target: 'code', label: 'Code Task' },
+  'review-code': { artifact: 'review-code', target: 'code-review', label: 'Review Code' },
+  'manual-validation': { artifact: 'manual-validation', target: null, label: 'Complete Manual Validation' },
+  'validation-run': { artifact: 'validation-run', target: null, label: 'Run Manual Validation' }
 } as const;
 type EventFamily = keyof typeof FAMILY;
 
@@ -290,6 +347,126 @@ function reviewInputFamily(family: EventFamily): ArtifactFamily {
   return family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code';
 }
 
+function lifecycleAction(family: EventFamily): LifecycleAction {
+  return family === 'analyze' ? 'analysis' : family;
+}
+
+function eventTrigger(request: TaskEventRequest, family: EventFamily): ExplicitTrigger {
+  return {
+    initiator: request.initiator ?? (request.orchestrated ? 'orchestrator' : request.agent === 'human' ? 'human' : 'model'),
+    requestId: request.requestId ?? `${request.taskRef}:${request.event}:${request.round ?? 1}`,
+    requestedAction: lifecycleAction(family),
+    reasonCode: request.reasonCode ?? (request.fixFor || request.implementationInput ? 'review-finding' : 'user-request'),
+    ...(request.sourceFinding ? { sourceFinding: request.sourceFinding } : {}),
+    ...(request.sourceArtifact ? { sourceArtifact: request.sourceArtifact } : {}),
+    ...(request.sourceSha256 ? { sourceSha256: request.sourceSha256 } : {}),
+    ...(request.implementationInput ? { implementationInput: request.implementationInput } : {}),
+    explicitRequest: request.requestId !== undefined || request.reasonCode !== undefined || request.initiator !== undefined || request.orchestrated === true
+  };
+}
+
+function invalidationMutationForCompletion(
+  content: string,
+  taskDir: string,
+  family: EventFamily,
+  artifact: ArtifactIdentity,
+  timestamp: string
+): { mutation: ReturnType<typeof invalidationMutation> | null } | { error: string } {
+  if (!['analyze', 'plan', 'code'].includes(family)) return { mutation: null };
+  const parsed = parseInvalidationDocument(content);
+  if (!parsed.ok) return { error: parsed.message };
+  const downstream: Record<'analyze' | 'plan' | 'code', readonly string[]> = {
+    analyze: ['review-analysis', 'plan', 'review-plan', 'code', 'review-code'],
+    plan: ['review-plan', 'code', 'review-code'],
+    code: ['review-code']
+  };
+  const sourceFamily = family as 'analyze' | 'plan' | 'code';
+  let receipts: readonly ArtifactReceipt[] = [];
+  try {
+    receipts = parseArtifactReceipts(content).rows;
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+  const targets = downstream[sourceFamily].flatMap((targetFamily: string) => {
+    const names = fs.readdirSync(taskDir).filter((name) => {
+      const pattern = targetFamily === 'review-analysis' ? /^review-analysis(?:-r\d+)?\.md$/
+        : targetFamily === 'review-plan' ? /^review-plan(?:-r\d+)?\.md$/
+          : targetFamily === 'review-code' ? /^review-code(?:-r\d+)?\.md$/
+            : new RegExp(`^${targetFamily}(?:-r\\d+)?\\.md$`);
+      return pattern.test(name);
+    });
+    return names.flatMap((name) => {
+      try {
+        const stat = fs.lstatSync(path.join(taskDir, name));
+        if (!stat.isFile() || stat.isSymbolicLink()) return [];
+        const targetRound = parseArtifactName(name)?.round ?? 1;
+        const targetSha256 = sha256File(path.join(taskDir, name));
+        const shapes: Array<{ targetKind: InvalidationTargetKind; targetFamily: string; targetArtifact: string; targetRound: number; targetSha256: string }> = [
+          { targetKind: 'artifact', targetFamily, targetArtifact: name, targetRound, targetSha256 }
+        ];
+        const receipt = receipts.find((candidate) => candidate.output === name);
+        if (receipt) shapes.push({
+          targetKind: 'receipt', targetFamily, targetArtifact: name, targetRound,
+          targetSha256: receipt.inputSha256
+        });
+        if (targetFamily.startsWith('review-')) {
+          shapes.push({ targetKind: 'approval', targetFamily, targetArtifact: name, targetRound, targetSha256 });
+        }
+        if (targetFamily === 'review-code') {
+          shapes.push({ targetKind: 'reviewed-snapshot', targetFamily, targetArtifact: name, targetRound, targetSha256 });
+        }
+        return shapes.map((targetShape) => ({
+          ...targetShape,
+          targetId: targetIdFor('pending', targetShape), operationId: 'pending', status: 'pending' as const,
+          reasonCode: 'upstream-replaced', updatedAt: timestamp
+        }));
+      } catch (error) {
+        throw new Error(`cannot inspect invalidation target '${name}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+    });
+  });
+  if (targets.length === 0) return { mutation: null };
+  const source = {
+    sourceFamily: lifecycleAction(family), sourceArtifact: artifact.name,
+    sourceRound: parseArtifactName(artifact.name)?.round ?? 1, sourceSha256: sha256File(artifact.path),
+    createdAt: timestamp, updatedAt: timestamp
+  };
+  const operation = createInvalidationOperation(source);
+  const normalizedTargets = targets.map((target: (typeof targets)[number]) => ({
+    ...target, operationId: operation.operationId,
+    targetId: targetIdFor(operation.operationId, target)
+  }));
+  const operationWithTotal = createInvalidationOperation(source, normalizedTargets);
+  const next = upsertInvalidation(parsed.document, operationWithTotal, normalizedTargets);
+  if (!next.ok) return { error: next.message };
+  return { mutation: next.changed ? invalidationMutation(content, next.document) : null };
+}
+
+function reworkIntentMutationForCompletion(
+  content: string,
+  taskDir: string,
+  family: EventFamily,
+  artifact: ArtifactIdentity,
+  timestamp: string
+): { mutation: ReturnType<typeof reworkIntentMutation> | null } | { error: string } {
+  const parsed = parseReworkIntentDocument(content);
+  if (!parsed.ok) return { error: parsed.message };
+  const hash = sha256File(artifact.path);
+  let next = parsed.intents;
+  if (family === 'analyze' || family === 'plan' || family === 'code') {
+    const hashes = Object.fromEntries(fs.readdirSync(taskDir).flatMap((name) => {
+      if (!/^review-(?:analysis|plan|code)(?:-r\d+)?\.md$/.test(name)) return [];
+      try { return [[name, sha256File(path.join(taskDir, name))]]; }
+      catch { return []; }
+    }));
+    next = consumeReworkIntents(next, family === 'analyze' ? 'analysis' : family, hashes, timestamp).intents;
+  }
+  if (family === 'review-analysis' || family === 'review-plan' || family === 'review-code') {
+    next = supersedeReworkIntents(next, artifact.name, hash, timestamp).intents;
+  }
+  return { mutation: JSON.stringify(next) === JSON.stringify(parsed.intents) ? null : reworkIntentMutation(content, next) };
+}
+
 function buildCompletionReceipt(
   taskDir: string,
   family: EventFamily,
@@ -407,6 +584,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   const completedRows = matchingRows.filter((item) => item.done);
   const row = manual ? openRows.at(-1) : matchingRows[0];
   let completedArtifact: ArtifactIdentity | null = null;
+  let localFinalizationIntent: LocalArtifactFinalizationIntent | null = null;
   if (eventIdentity.phase === 'started' && row) {
     if (row.agent !== normalized.agent) return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'open started event has a different agent' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
     return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, row.started, frontmatter, artifactContext);
@@ -420,13 +598,81 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     const validated = validateCompletedArtifact(resolved.taskDir, FAMILY[eventIdentity.family].artifact, normalized.artifact!, normalized.round);
     if (!validated.ok) return failed(normalized, validated.error, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
     completedArtifact = validated.artifact;
+    if (eventIdentity.family === 'analyze' || eventIdentity.family === 'plan' || eventIdentity.family === 'code') {
+      const localFamily = eventIdentity.family === 'analyze'
+        ? 'analysis'
+        : eventIdentity.family === 'plan' ? 'plan' : 'code';
+      let artifactContent: string;
+      try { artifactContent = fs.readFileSync(completedArtifact.path, 'utf8'); }
+      catch (error) {
+        return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot read ${completedArtifact.name}: ${String(error)}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
+      const validationConfig = localArtifactValidationConfig(resolved.repoRoot, localFamily);
+      const local = validateLocalArtifact(artifactContent, {
+        family: localFamily,
+        requiredSections: validationConfig.requiredSections,
+        requiredPatterns: validationConfig.requiredPatterns
+      });
+      if (!local.ok) {
+        return failed(normalized, {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `LOCAL_ARTIFACT_INVALID: ${local.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
+      const actualSha256 = sha256File(completedArtifact.path);
+      if (actualSha256 !== normalized.artifactSha256) {
+        return failed(normalized, {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `artifact SHA-256 does not match finalizer result for ${completedArtifact.name}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
+      if (local.semanticDigest !== normalized.semanticDigest) {
+        return failed(normalized, {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `semantic digest does not match finalizer result for ${completedArtifact.name}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
+      try {
+        localFinalizationIntent = readLocalArtifactFinalizationIntent(
+          resolved.repoRoot, resolved.taskId, localFamily, completedArtifact.name
+        );
+      } catch (error) {
+        return failed(normalized, {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `cannot read local finalizer provenance for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
+      if (!localFinalizationIntent || !['passed', 'consumed'].includes(localFinalizationIntent.state)) {
+        return failed(normalized, {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `local finalizer provenance is missing or incomplete for ${completedArtifact.name}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
+      if (localFinalizationIntent.artifactSha256 !== actualSha256 || localFinalizationIntent.semanticDigest !== local.semanticDigest) {
+        return failed(normalized, {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `local finalizer provenance does not match ${completedArtifact.name}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
+    }
   }
   if (eventIdentity.phase === 'waiting' && section.entries.some((entry) => entry.step === eventIdentity.action && entry.note === eventIdentity.note)) {
     const existing = section.entries.find((entry) => entry.step === eventIdentity.action && entry.note === eventIdentity.note)!;
     return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, existing.time, frontmatter, artifactContext);
   }
-  const allowed = FAMILY[eventIdentity.family][eventIdentity.phase === 'started' ? 'started' : 'completed'];
-  if (!(allowed as readonly string[]).includes(currentStep) && !allowsManualOverride(options.manualOverride, 'task-event', 'EVENT_TRANSITION_INVALID')) return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${normalized.event} is not allowed from '${currentStep}'` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  if (eventIdentity.phase === 'started') {
+    const trigger = eventTrigger(normalized, eventIdentity.family);
+    const facts = buildLifecycleFacts(resolved.taskDir, content, resolved.state);
+    if (!facts.ok) return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${facts.code}: ${facts.message}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    const capability = canStart(lifecycleAction(eventIdentity.family), facts.facts, trigger);
+    const capabilityOverride = capability.reasonCode === 'TASK_NOT_ACTIVE'
+      ? stateOverride
+      : allowsManualOverride(options.manualOverride, 'task-event', 'EVENT_TRANSITION_INVALID');
+    if (!capability.allowed && !capabilityOverride) {
+      const code = capability.reasonCode === 'INVALIDATION_INCOMPLETE' ? 'TASK_INVALIDATION_BLOCKED' : 'EVENT_TRANSITION_INVALID';
+      return failed(normalized, { code, message: `${capability.reasonCode}: ${capability.evidence.join(', ')}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
+  }
   const findingCountError = validateReviewFindingCounts(
     normalized,
     content,
@@ -460,12 +706,24 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
   catch (error) { return failed(normalized, { code: 'METADATA_CAPTURE_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
   let completionReceipt: ArtifactReceipt | null = null;
+  let completionInvalidation: ReturnType<typeof invalidationMutation> | null = null;
+  let completionRework: ReturnType<typeof reworkIntentMutation> | null = null;
   if (eventIdentity.phase === 'completed' && completedArtifact) {
     const receipt = buildCompletionReceipt(resolved.taskDir, eventIdentity.family, completedArtifact, metadata.timestamp, frontmatter);
     if (receipt && !receipt.ok) {
       return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: receipt.message }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
     }
     completionReceipt = receipt?.receipt ?? null;
+    try {
+      const invalidation = invalidationMutationForCompletion(content, resolved.taskDir, eventIdentity.family, completedArtifact, metadata.timestamp);
+      if ('error' in invalidation) return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: invalidation.error }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      completionInvalidation = invalidation.mutation;
+      const rework = reworkIntentMutationForCompletion(content, resolved.taskDir, eventIdentity.family, completedArtifact, metadata.timestamp);
+      if ('error' in rework) return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: rework.error }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      completionRework = rework.mutation;
+    } catch (error) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: error instanceof Error ? error.message : String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
   }
   const step = eventIdentity.phase === 'started' || eventIdentity.target === null ? currentStep : eventIdentity.target;
   const logStep = eventIdentity.phase === 'started' ? `${eventIdentity.action} [started]` : eventIdentity.action;
@@ -513,6 +771,8 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
       return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
     }
   }
+  if (completionInvalidation) mutations.push(completionInvalidation);
+  if (completionRework) mutations.push(completionRework);
   if (eventIdentity.phase === 'completed' && normalized.implementationInput) {
     let implementationRows;
     try {
@@ -531,7 +791,27 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     });
   }
   mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body });
-  const result = writeTask({ taskRef: normalized.taskRef, expectedState: stateOverride ? resolved.state : 'active', dryRun: normalized.dryRun, mutations }, { ...options, metadataProvider: () => metadata });
+  if (!normalized.dryRun && localFinalizationIntent && completedArtifact && localFinalizationIntent.state === 'passed') {
+    try {
+      localFinalizationIntent = consumeLocalArtifactFinalizationIntent(resolved.repoRoot, localFinalizationIntent);
+    } catch (error) {
+      return failed(normalized, {
+        code: 'EVENT_ARTIFACT_CONFLICT',
+        message: `local finalizer provenance could not be consumed before task write for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
+      }, {
+        taskId: resolved.taskId,
+        taskMdPath: resolved.taskMdPath,
+        fromStep: currentStep,
+        toStep: step,
+        action: eventIdentity.action,
+        phase: eventIdentity.phase,
+        artifactContext
+      });
+    }
+  }
+  const sourceCompletion = eventIdentity.phase === 'completed'
+    && ['analyze', 'plan', 'code'].includes(eventIdentity.family);
+  const result = writeTask({ taskRef: normalized.taskRef, expectedState: stateOverride ? resolved.state : 'active', dryRun: normalized.dryRun, mutations }, { ...options, invalidationContext: sourceCompletion ? 'source-completion' : 'standard', metadataProvider: () => metadata });
   if (result.status === 'failed') return failed(normalized, result.error, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
   if (!normalized.dryRun && orchestrationCompletion) {
     try {

package/lib/task/finalization.ts

@@ -55,6 +55,7 @@ type TaskFinalizationRequest = Readonly<{
 
 type TaskFinalizationOptions = Readonly<{
   repoRoot: string;
+  controlBinding?: Readonly<{ generation: string; requestId: string }>;
   metadataProvider?: TaskLifecycleOptions['metadataProvider'];
   lifecycle?: typeof applyTaskLifecycle;
   commentSync?: typeof syncPlatformComment;
@@ -73,6 +74,7 @@ type TaskFinalizationReceipt = Readonly<{
   verification: FinalizationStepState;
   warningProjection: WarningProjectionState;
   warnings: readonly FinalizationWarning[];
+  controlBinding?: Readonly<{ generation: string; requestId: string }>;
   updatedAt: string;
   lastError: FinalizationError | null;
 }>;
@@ -146,7 +148,7 @@ function failed(
   };
 }
 
-function emptyReceipt(taskId: string): TaskFinalizationReceipt {
+function emptyReceipt(taskId: string, controlBinding?: Readonly<{ generation: string; requestId: string }>): TaskFinalizationReceipt {
   return {
     version: RECEIPT_VERSION,
     taskId,
@@ -158,6 +160,7 @@ function emptyReceipt(taskId: string): TaskFinalizationReceipt {
     verification: 'pending',
     warningProjection: 'done',
     warnings: [],
+    ...(controlBinding ? { controlBinding } : {}),
     updatedAt: now(),
     lastError: null
   };
@@ -182,6 +185,7 @@ function validWarning(value: unknown): value is FinalizationWarning {
 function validateReceipt(value: unknown, taskId: string): TaskFinalizationReceipt {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('receipt must be an object');
   const receipt = value as Record<string, unknown>;
+  const controlBinding = receipt.controlBinding as Record<string, unknown> | null | undefined;
   const states = ['pending', 'done', 'skipped'];
   if (
     receipt.version !== RECEIPT_VERSION || receipt.taskId !== taskId || receipt.intent !== 'complete'
@@ -194,6 +198,10 @@ function validateReceipt(value: unknown, taskId: string): TaskFinalizationReceip
     || !Array.isArray(receipt.warnings) || receipt.warnings.some((warning) => !validWarning(warning))
     || typeof receipt.updatedAt !== 'string'
     || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)))
+    || (receipt.controlBinding !== undefined && (!controlBinding || typeof controlBinding !== 'object'
+      || Array.isArray(controlBinding)
+      || typeof controlBinding.generation !== 'string' || controlBinding.generation.length === 0
+      || typeof controlBinding.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(controlBinding.requestId)))
   ) throw new Error('receipt schema is invalid');
   return receipt as TaskFinalizationReceipt;
 }
@@ -205,6 +213,18 @@ function readReceipt(repoRoot: string, taskId: string): TaskFinalizationReceipt
   return validateReceipt(value, taskId);
 }
 
+function readTaskFinalizationReceipt(repoRoot: string, taskId: string): TaskFinalizationReceipt | null {
+  return readReceipt(path.resolve(repoRoot), taskId);
+}
+
+function controlBindingMatches(
+  receipt: TaskFinalizationReceipt,
+  binding: Readonly<{ generation: string; requestId: string }>
+): boolean {
+  return receipt.controlBinding?.generation === binding.generation
+    && receipt.controlBinding.requestId === binding.requestId;
+}
+
 function writeReceipt(repoRoot: string, receipt: TaskFinalizationReceipt): void {
   const directory = finalizationRoot(repoRoot);
   fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
@@ -486,14 +506,14 @@ function reconcileWarningProjection(repoRoot: string, taskId: string, receipt: T
   catch { return receipt; }
 }
 
-function syncPendingTaskComment(input: {
+async function syncPendingTaskComment(input: {
   repoRoot: string;
   taskId: string;
   agent: string;
   receipt: TaskFinalizationReceipt;
   commentSync: typeof syncPlatformComment;
   consumedCapabilities: Set<string>;
-}): TaskCommentSyncOutcome {
+}): Promise<TaskCommentSyncOutcome> {
   const { repoRoot, taskId, agent, commentSync, consumedCapabilities } = input;
   let receipt = input.receipt;
   if (receipt.taskComment !== 'pending') {
@@ -505,7 +525,7 @@ function syncPendingTaskComment(input: {
     };
   }
   try {
-    const result = commentSync(taskId, { kind: 'task', agent, cwd: repoRoot });
+    const result = await commentSync(taskId, { kind: 'task', agent, cwd: repoRoot });
     const step = commentStep(result);
     if (result.status === 'applied' || result.status === 'no-op') {
       const skipped = result.error?.code === 'ISSUE_NOT_LINKED';
@@ -569,11 +589,11 @@ function terminalResult(
   };
 }
 
-function applyUnderLock(
+async function applyUnderLock(
   request: TaskFinalizationRequest,
   taskId: string,
   options: TaskFinalizationOptions
-): TaskFinalizationResult {
+): Promise<TaskFinalizationResult> {
   const repoRoot = path.resolve(options.repoRoot);
   const lifecycle = options.lifecycle ?? applyTaskLifecycle;
   const commentSync = options.commentSync ?? syncPlatformComment;
@@ -583,16 +603,27 @@ function applyUnderLock(
   try {
     const file = receiptPath(repoRoot, taskId);
     const existed = fs.existsSync(file);
-    receipt = readReceipt(repoRoot, taskId) ?? emptyReceipt(taskId);
+    receipt = readReceipt(repoRoot, taskId) ?? emptyReceipt(taskId, options.controlBinding);
     if (!existed) writeReceipt(repoRoot, receipt);
   } catch (error) {
     return failed(taskId, errorOf(error, 'TASK_FINALIZATION_RECEIPT_INVALID'));
   }
+  if (options.controlBinding && !controlBindingMatches(receipt, options.controlBinding)) {
+    const error: FinalizationError = {
+      code: 'TASK_FINALIZATION_CONTROL_BINDING_CONFLICT',
+      message: 'finalization receipt belongs to a different sandbox request or generation',
+      retryable: false
+    };
+    return failed(taskId, error, {
+      completedSteps: completedSteps(receipt),
+      pendingSteps: pendingSteps(receipt)
+    });
+  }
 
   const preflightState = resolveTaskRef(taskId, { repoRoot });
   if (options.preflight && preflightState.ok && preflightState.state === 'active') {
     try {
-      const preflight = options.preflight(
+      const preflight = await options.preflight(
         { taskRef: taskId, event: 'complete-task.preflight' },
         { repoRoot }
       );
@@ -668,7 +699,7 @@ function applyUnderLock(
 
   let taskComment: TaskFinalizationStep | null = null;
   receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-  const initialComment = syncPendingTaskComment({
+  const initialComment = await syncPendingTaskComment({
     repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
   });
   receipt = initialComment.receipt;
@@ -684,7 +715,7 @@ function applyUnderLock(
     if (receipt.verification !== 'pending') {
       verification = { status: 'no-op', changed: false, error: null };
     } else {
-      const result = verify(
+      const result = await verify(
         { taskRef: taskId, event: 'complete-task.completed' },
         { repoRoot }
       );
@@ -695,7 +726,7 @@ function applyUnderLock(
           scope: 'verification', operation: 'succeeded'
         }, consumedCapabilities);
         receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-        const finalComment = syncPendingTaskComment({
+        const finalComment = await syncPendingTaskComment({
           repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
         });
         receipt = finalComment.receipt;
@@ -729,7 +760,7 @@ function applyUnderLock(
   return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification }, changed);
 }
 
-function applyTaskFinalization(request: TaskFinalizationRequest, options: TaskFinalizationOptions): TaskFinalizationResult {
+async function applyTaskFinalization(request: TaskFinalizationRequest, options: TaskFinalizationOptions): Promise<TaskFinalizationResult> {
   if (request.intent !== 'complete' || !request.taskRef || !request.agent) {
     return failed(null, { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'complete finalization requires taskRef and agent', retryable: false });
   }
@@ -737,7 +768,7 @@ function applyTaskFinalization(request: TaskFinalizationRequest, options: TaskFi
   const resolved = resolveTaskRef(request.taskRef, { repoRoot });
   if (!resolved.ok) return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
   try {
-    return withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.complete', () => applyUnderLock(request, resolved.taskId, options));
+    return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.complete', () => applyUnderLock(request, resolved.taskId, options));
   } catch (error) {
     const detail = error instanceof TaskExecutionLockError
       ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
@@ -746,7 +777,12 @@ function applyTaskFinalization(request: TaskFinalizationRequest, options: TaskFi
   }
 }
 
-export { applyFinalizationReceiptMutation, applyTaskFinalization, issueCapability as createFinalizationCapability };
+export {
+  applyFinalizationReceiptMutation,
+  applyTaskFinalization,
+  issueCapability as createFinalizationCapability,
+  readTaskFinalizationReceipt
+};
 export type {
   FinalizationError,
   FinalizationCapability,