@fitlab-ai/agent-infra 0.11.3 → 0.11.5

package/lib/task/events.ts

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 
+import { resolveBranchWorktree } from '../git/branch-worktree.ts';
+
 import { appendActivityEntry, locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
 import {
   buildArtifactLinkSection,
@@ -32,17 +34,17 @@ import type { OrchestrationStageCompletion } from './orchestration.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskOperationSummary, TaskWriteErrorCode, TaskWriteOptions } from './write.ts';
-import { allowsManualOverride } from './guard-override.ts';
 import { validateLocalArtifact } from './local-artifact-finalization.ts';
 import type { LocalArtifactFamily } from './local-artifact-finalization.ts';
-import { buildLifecycleFacts, canStart } from './capabilities.ts';
+import { buildLifecycleFacts, canStart, effectiveReworkTarget } 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 { reconcileTaskInvalidation } from './invalidation-command.ts';
 import { consumeReworkIntents, parseReworkIntentDocument, reworkIntentMutation, supersedeReworkIntents } from './rework-intent.ts';
-import { ARTIFACT_FAMILIES, expectedQualificationRelations, parseQualificationAudit, parseTaskQualification, upstreamArtifactDigest, validateQualificationAudit } from './qualification-audit.ts';
-import type { QualificationAudit, UpstreamRelation } from './qualification-audit.ts';
+import type { ReworkTarget } from './rework-intent.ts';
+import { ARTIFACT_FAMILIES, parseQualificationAudit, parseTaskQualification, upstreamArtifactDigest } from './qualification-audit.ts';
+import type { QualificationAudit } from './qualification-audit.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
 import { canonicalSemanticDigest, inspectArtifactContract } from './artifact-operations.ts';
 import {
@@ -52,6 +54,7 @@ import {
   type LifecycleRecoveryAttestationV1
 } from './control-authority.ts';
 import { readManualValidationCompletion } from './manual-validation-completion.ts';
+import { parseLifecyclePathDecision } from './lifecycle-path.ts';
 
 const eventCatalog = [
   'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
@@ -79,7 +82,6 @@ type TaskEventErrorCode =
   | ArtifactErrorCode | TaskWriteErrorCode;
 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;
@@ -107,24 +109,31 @@ type TaskEventResult = {
   operations: readonly TaskOperationSummary[]; error: TaskEventError | null;
 };
 
-function approvedCleanReviewedCommit(reviewContent: string, verdict: Verdict | undefined, repoRoot: string): string | null {
+function branchWorktree(repoRoot: string, branch: string): string | null {
+  if (!branch) return repoRoot;
+  return resolveBranchWorktree(repoRoot, branch);
+}
+
+function approvedCleanReviewedCommit(reviewContent: string, verdict: Verdict | undefined, repoRoot: string, branch: string): string | null {
   if (verdict !== 'approved') return null;
   const reviewedHead = extractReviewedHead(reviewContent) || extractReviewBaseline(reviewContent);
   const reviewedTree = extractReviewedSnapshotTree(reviewContent);
   if (!/^[a-f0-9]{40}$/.test(reviewedHead) || !/^[a-f0-9]{40}$/.test(reviewedTree)) return null;
+  const worktree = branchWorktree(repoRoot, branch);
+  if (!worktree) return null;
   try {
-    const currentHead = execFileSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+    const currentHead = execFileSync('git', ['-C', worktree, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
     if (currentHead !== reviewedHead) return null;
-    const currentTree = execFileSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD^{tree}'], { encoding: 'utf8' }).trim();
+    const currentTree = execFileSync('git', ['-C', worktree, 'rev-parse', 'HEAD^{tree}'], { encoding: 'utf8' }).trim();
     if (currentTree !== reviewedTree) return null;
-    execFileSync('git', ['-C', repoRoot, 'diff-index', '--quiet', 'HEAD', '--']);
+    execFileSync('git', ['-C', worktree, 'diff-index', '--quiet', 'HEAD', '--']);
     return reviewedHead;
   } catch {
     return null;
   }
 }
 
-const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope', 'initiator', 'requestId', 'reasonCode', 'sourceFinding', 'sourceArtifact', 'sourceSha256']);
+const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun', 'initiator', 'requestId', 'reasonCode', 'sourceFinding', 'sourceArtifact', 'sourceSha256']);
 const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[] }> = {
   'analyze.started': { optional: ['round'] },
   'analyze.awaiting-input': { required: ['question'] },
@@ -329,7 +338,13 @@ function failed(request: TaskEventRequest, error: TaskEventError, extra: Partial
 
 function normalizeStarted(request: TaskEventRequest, repoRoot: string): { request: TaskEventRequest; context: ArtifactContextResult } | { error: TaskEventError; context: ArtifactContextResult } {
   const family = eventParts(request.event).family;
-  const context = resolveArtifactContext(request.taskRef, FAMILY[family].artifact, { repoRoot });
+  const context = resolveArtifactContext(request.taskRef, FAMILY[family].artifact, {
+    repoRoot,
+    reasonCode: request.reasonCode,
+    sourceFinding: request.sourceFinding,
+    sourceArtifact: request.sourceArtifact,
+    sourceSha256: request.sourceSha256
+  });
   if (context.status !== 'ready' || !context.next) {
     return { error: { code: context.error?.code ?? 'EVENT_ARTIFACT_CONFLICT', message: context.error?.message ?? context.codeMode?.message ?? 'artifact context is not writable' }, context };
   }
@@ -386,25 +401,6 @@ function reviewInputFamily(family: EventFamily): ArtifactFamily {
   return family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code';
 }
 
-function relationForStartedInput(family: EventFamily, input: ArtifactIdentity): UpstreamRelation['relation'] {
-  if (family.startsWith('review-')) {
-    return input.family === reviewInputFamily(family) ? 'reviewed-input' : 'approval-context';
-  }
-  const consumer = family === 'analyze' ? 'analysis' : family;
-  if ((consumer === 'plan' && input.family === 'analysis') || (consumer === 'code' && input.family === 'plan')) return 'required-input';
-  return 'review-context';
-}
-
-function qualificationRelationsForStarted(family: EventFamily, inputs: readonly ArtifactIdentity[]): UpstreamRelation[] {
-  return inputs.map((input) => ({
-    upstreamFamily: input.family as UpstreamRelation['upstreamFamily'],
-    upstreamArtifact: input.name,
-    upstreamRound: input.round,
-    upstreamSha256: sha256File(input.path),
-    relation: relationForStartedInput(family, input)
-  }));
-}
-
 function lifecycleAction(family: EventFamily): LifecycleAction {
   return family === 'analyze' ? 'analysis' : family;
 }
@@ -586,7 +582,20 @@ function reworkIntentMutationForCompletion(
       try { return [[name, sha256File(path.join(taskDir, name))]]; }
       catch { return []; }
     }));
-    next = consumeReworkIntents(next, family === 'analyze' ? 'analysis' : family, hashes, timestamp).intents;
+    const action = family === 'analyze' ? 'analysis' : family;
+    let target: ReworkTarget = action;
+    if (family === 'analyze') {
+      const previousAnalysis = fs.readdirSync(taskDir)
+        .map((name) => parseArtifactName(name))
+        .filter((identity) => identity?.family === 'analysis' && identity.name !== artifact.name)
+        .sort((left, right) => right!.round - left!.round || left!.name.localeCompare(right!.name))[0];
+      const pathState = previousAnalysis
+        ? parseLifecyclePathDecision(fs.readFileSync(path.join(taskDir, previousAnalysis.name), 'utf8'))
+        : undefined;
+      const pending = next.find((intent) => intent.status === 'pending');
+      if (pending && effectiveReworkTarget(pending.target, pathState) === action) target = pending.target;
+    }
+    next = consumeReworkIntents(next, target, hashes, timestamp).intents;
   }
   if (family === 'review-analysis' || family === 'review-plan' || family === 'review-code') {
     next = supersedeReworkIntents(next, artifact.name, hash, timestamp).intents;
@@ -614,13 +623,15 @@ function buildCompletionReceipt(
       ? frontmatter.code_input_artifact : existing?.input ?? '';
     const startedSha256 = typeof frontmatter.code_input_sha256 === 'string'
       ? frontmatter.code_input_sha256 : existing?.inputSha256 ?? '';
-    if (!startedInput || !startedSha256) return { ok: false, message: 'code.started plan input context is missing' };
-    const plan = inspectArtifactDirectory(taskDir, 'plan');
-    if (plan.status !== 'ready' || !plan.latest || plan.latest.name !== startedInput) {
-      return { ok: false, message: `code input '${startedInput}' is not the latest plan artifact` };
+    if (!startedInput || !startedSha256) return { ok: false, message: 'code.started lifecycle input context is missing' };
+    const inputIdentity = parseArtifactName(startedInput);
+    if (!inputIdentity || !['analysis', 'plan'].includes(inputIdentity.family)) return { ok: false, message: `code input '${startedInput}' has an invalid family` };
+    const lifecycleInput = inspectArtifactDirectory(taskDir, inputIdentity.family);
+    if (lifecycleInput.status !== 'ready' || !lifecycleInput.latest || lifecycleInput.latest.name !== startedInput) {
+      return { ok: false, message: `code input '${startedInput}' is not the latest ${inputIdentity.family} artifact` };
     }
     try {
-      const inputSha256 = sha256File(plan.latest.path);
+      const inputSha256 = sha256File(lifecycleInput.latest.path);
       if (inputSha256 !== startedSha256) return { ok: false, message: `code input ${startedInput} changed after code.started` };
       return {
         ok: true,
@@ -630,7 +641,7 @@ function buildCompletionReceipt(
         }
       };
     } catch (error) {
-      return { ok: false, message: `cannot hash code input plan: ${error instanceof Error ? error.message : String(error)}` };
+      return { ok: false, message: `cannot hash code lifecycle input: ${error instanceof Error ? error.message : String(error)}` };
     }
   }
   if (!family.startsWith('review-')) return null;
@@ -732,8 +743,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   if (invalid) return failed(request, invalid);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(request, { code: resolved.code, message: resolved.message }, { taskId: resolved.taskId });
-  const stateOverride = allowsManualOverride(options.manualOverride, 'task-event', 'TASK_STATE_MISMATCH');
-  if (resolved.state !== 'active' && !stateOverride) return failed(request, { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected active` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+  if (resolved.state !== 'active') return failed(request, { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected active` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
   let content: string;
   try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
   catch (error) { return failed(request, { code: 'TASK_READ_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
@@ -774,6 +784,12 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
       normalized = { ...request, round: openIdentity.round, artifact: artifactName(FAMILY[initialParts.family].artifact, openIdentity.round), fixFor: openIdentity.fixFor, implementationInput: openIdentity.implementationInput };
       return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, typeof frontmatter.current_step === 'string' ? frontmatter.current_step : '', identity(normalized), openIdentity.row.started, frontmatter, null);
     }
+    if (rows.some((item) => item.started && !item.done)) {
+      return failed(request, {
+        code: 'EVENT_TRANSITION_INVALID',
+        message: 'EXECUTION_BUSY: another lifecycle execution is open'
+      }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    }
     const result = normalizeStarted(request, resolved.repoRoot);
     artifactContext = result.context;
     if ('error' in result) return failed(request, result.error, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, artifactContext });
@@ -819,7 +835,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     }
     return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, row.started, frontmatter, artifactContext);
   }
-  if (eventIdentity.phase === 'completed' && !row?.started && completedRows.length === 0 && !allowsManualOverride(options.manualOverride, 'task-event', 'EVENT_START_MISSING')) return failed(normalized, { code: 'EVENT_START_MISSING', message: 'completion requires a started event or an earlier completed attempt' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  if (eventIdentity.phase === 'completed' && !row?.started && completedRows.length === 0) return failed(normalized, { code: 'EVENT_START_MISSING', message: 'completion requires a started event or an earlier completed attempt' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
   if (eventIdentity.phase === 'completed') {
     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 });
@@ -836,25 +852,13 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     if (eventIdentity.family.startsWith('review-')) {
       try { reviewContent = fs.readFileSync(completedArtifact.path, 'utf8'); }
       catch (error) {
-        return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot read qualification audit from ${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 });
+        return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot read ${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 });
       }
       const schema = getArtifactSchema(eventIdentity.family);
       const structure = schema ? inspectArtifactContract(reviewContent, schema) : null;
       if (structure && !structure.ok) {
         return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `shared artifact structure invalid: ${structure.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 expected = expectedQualificationRelations(content, eventIdentity.family as 'review-analysis' | 'review-plan' | 'review-code');
-      if (!expected.ok) {
-        return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `${expected.code}: ${expected.message}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
-      }
-      const qualification = validateQualificationAudit(content, reviewContent, {
-        family: eventIdentity.family as 'review-analysis' | 'review-plan' | 'review-code',
-        artifact: completedArtifact.name,
-        expectedUpstreamRelations: expected.relations
-      });
-      if (!qualification.ok) {
-        return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `${qualification.code}: ${qualification.message}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
-      }
     }
     if (eventIdentity.family === 'analyze' || eventIdentity.family === 'plan' || eventIdentity.family === 'code') {
       const localFamily = eventIdentity.family === 'analyze'
@@ -866,9 +870,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
         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 local = validateLocalArtifact(artifactContent, {
-        family: localFamily,
-        taskContent: content,
-        artifact: completedArtifact.name
+        family: localFamily
       });
       if (!local.ok) {
         return failed(normalized, {
@@ -900,10 +902,9 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     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 safetyFailure = capability.reasonCode === 'TASK_NOT_ACTIVE'
+      || capability.reasonCode === 'LIFECYCLE_EXECUTION_OPEN';
+    if (!capability.allowed && (normalized.initiator === 'orchestrator' || safetyFailure)) {
       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 });
     }
@@ -916,10 +917,11 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   );
   if (findingCountError) return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
   let orchestrationCompletion: OrchestrationStageCompletion | null = null;
-  if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation' && eventIdentity.family !== 'validation-run') {
+  if (eventIdentity.phase === 'completed' && normalized.orchestrated
+    && eventIdentity.family !== 'manual-validation' && eventIdentity.family !== 'validation-run') {
     const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
     const execution = validateLifecycleExecution(normalized.taskRef, {
-      mode: normalized.orchestrated ? 'orchestrated' : 'standalone',
+      mode: 'orchestrated',
       identity: {
         stage: orchestrationStage,
         round: normalized.round!,
@@ -984,16 +986,9 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   const frontmatterSet: Record<string, string> = { current_step: step, assigned_to: normalized.agent };
   if (currentFact) frontmatterSet.completion_facts = JSON.stringify(replaceCompletionFact(completionFacts(frontmatter), currentFact));
   let frontmatterRemove: string[] | undefined;
-  if (eventIdentity.phase === 'started' && artifactContext) {
-    try {
-      frontmatterSet.qualification_input_relations = JSON.stringify(qualificationRelationsForStarted(eventIdentity.family, artifactContext.inputs));
-    } catch (error) {
-      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot capture qualification input relations: ${error instanceof Error ? error.message : String(error)}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
-    }
-  }
   if (eventIdentity.phase === 'started' && eventIdentity.family === 'code') {
-    const planInput = artifactContext?.inputs.find((input) => input.family === 'plan');
-    if (!planInput) return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: 'code.started plan input context is unavailable' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    const planInput = artifactContext?.inputs.find((input) => input.family === 'plan' || input.family === 'analysis');
+    if (!planInput) return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: 'code.started lifecycle input context is unavailable' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
     try {
       frontmatterSet.code_input_artifact = planInput.name;
       frontmatterSet.code_input_sha256 = sha256File(planInput.path);
@@ -1016,11 +1011,15 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     frontmatterRemove = ['review_input_artifact', 'review_input_sha256'];
   }
   if (eventIdentity.phase === 'completed' && eventIdentity.family === 'review-code' && reviewContent !== null) {
-    const reviewedCommit = approvedCleanReviewedCommit(reviewContent, normalized.verdict, resolved.repoRoot);
+    const reviewedCommit = approvedCleanReviewedCommit(
+      reviewContent,
+      normalized.verdict,
+      resolved.repoRoot,
+      typeof frontmatter.branch === 'string' ? frontmatter.branch : ''
+    );
     if (reviewedCommit) frontmatterSet.last_reviewed_commit = reviewedCommit;
     else if (normalized.verdict === 'approved') frontmatterSet.last_reviewed_commit = '';
   }
-  if (eventIdentity.phase === 'completed') frontmatterRemove = [...(frontmatterRemove ?? []), 'qualification_input_relations'];
   if (eventIdentity.phase === 'started' && normalized.implementationInput) frontmatterSet.last_reviewed_commit = '';
   const mutations: Parameters<typeof writeTask>[0]['mutations'][number][] = [
     { kind: 'frontmatter', set: frontmatterSet, remove: frontmatterRemove }
@@ -1060,7 +1059,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body });
   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 });
+  const result = writeTask({ taskRef: normalized.taskRef, expectedState: '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-handoff.ts

@@ -0,0 +1,104 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { TaskFinalizationReceipt } from './finalization.ts';
+
+const HANDOFF_VERSION = 1 as const;
+
+type TaskFinalizationHandoff = Readonly<{
+  version: typeof HANDOFF_VERSION;
+  taskId: string;
+  binding: Readonly<{ generation: string; requestId: string }>;
+  receipt: TaskFinalizationReceipt;
+  receiptSha256: string;
+}>;
+type ReadHandoff = Readonly<{ receipt: TaskFinalizationReceipt; cleanup: () => void }>;
+const MAX_HANDOFF_BYTES = 1024 * 1024;
+
+function digest(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+export function finalizationHandoffPath(directory: string, taskId: string): string {
+  return path.join(directory, '.agent-infra', 'task-finalization', `${taskId}.json`);
+}
+
+export function publishTaskFinalizationHandoff(
+  directory: string,
+  receipt: TaskFinalizationReceipt,
+  binding: Readonly<{ generation: string; requestId: string }>
+): string {
+  if (receipt.taskId === '' || receipt.controlBinding?.generation !== binding.generation
+    || receipt.controlBinding.requestId !== binding.requestId) {
+    throw new Error('TASK_FINALIZATION_HANDOFF_BINDING_INVALID');
+  }
+  const envelope: TaskFinalizationHandoff = {
+    version: HANDOFF_VERSION, taskId: receipt.taskId, binding, receipt, receiptSha256: digest(receipt)
+  };
+  const target = finalizationHandoffPath(directory, receipt.taskId);
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(envelope)}\n`, { mode: 0o600, flag: 'wx' });
+  try { fs.renameSync(temporary, target); } catch (error) {
+    try { fs.unlinkSync(temporary); } catch { /* preserve the primary error */ }
+    throw error;
+  }
+  return digest(envelope);
+}
+
+export function readTaskFinalizationHandoff(
+  directory: string,
+  taskId: string,
+  binding: Readonly<{ generation: string; requestId: string }>,
+  handoffSha256: string
+): ReadHandoff {
+  const file = finalizationHandoffPath(directory, taskId);
+  const initial = fs.lstatSync(file);
+  if (!initial.isFile() || initial.isSymbolicLink() || initial.size > MAX_HANDOFF_BYTES) {
+    throw new Error('TASK_FINALIZATION_HANDOFF_INVALID');
+  }
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  let content: string;
+  try {
+    const opened = fs.fstatSync(descriptor);
+    if (!opened.isFile() || opened.dev !== initial.dev || opened.ino !== initial.ino
+      || opened.size > MAX_HANDOFF_BYTES) throw new Error('TASK_FINALIZATION_HANDOFF_INVALID');
+    const bytes = Buffer.alloc(MAX_HANDOFF_BYTES + 1);
+    const length = fs.readSync(descriptor, bytes, 0, bytes.length, 0);
+    if (length !== opened.size || length > MAX_HANDOFF_BYTES) throw new Error('TASK_FINALIZATION_HANDOFF_INVALID');
+    content = bytes.toString('utf8', 0, length);
+    const after = fs.fstatSync(descriptor);
+    if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size) {
+      throw new Error('TASK_FINALIZATION_HANDOFF_INVALID');
+    }
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  const envelope = JSON.parse(content) as Partial<TaskFinalizationHandoff>;
+  if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)
+    || Object.keys(envelope).sort().join('\0') !== ['binding', 'receipt', 'receiptSha256', 'taskId', 'version'].join('\0')
+    || envelope.version !== HANDOFF_VERSION || envelope.taskId !== taskId
+    || !envelope.binding || typeof envelope.binding !== 'object' || Array.isArray(envelope.binding)
+    || Object.keys(envelope.binding).sort().join('\0') !== ['generation', 'requestId'].join('\0')
+    || envelope.binding.generation !== binding.generation
+    || envelope.binding.requestId !== binding.requestId || !envelope.receipt
+    || envelope.receipt.controlBinding?.generation !== binding.generation
+    || envelope.receipt.controlBinding.requestId !== binding.requestId
+    || typeof envelope.receiptSha256 !== 'string' || envelope.receiptSha256 !== digest(envelope.receipt)
+    || digest(envelope) !== handoffSha256) {
+    throw new Error('TASK_FINALIZATION_HANDOFF_INVALID');
+  }
+  return {
+    receipt: envelope.receipt,
+    cleanup: () => {
+      try {
+        const current = fs.lstatSync(file);
+        if (current.isFile() && !current.isSymbolicLink()
+          && current.dev === initial.dev && current.ino === initial.ino) fs.unlinkSync(file);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+    }
+  };
+}