@fitlab-ai/agent-infra 0.11.4 → 0.11.6

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,7 +34,6 @@ 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, effectiveReworkTarget } from './capabilities.ts';
@@ -81,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;
@@ -111,22 +111,7 @@ type TaskEventResult = {
 
 function branchWorktree(repoRoot: string, branch: string): string | null {
   if (!branch) return repoRoot;
-  try {
-    const records = execFileSync('git', ['worktree', 'list', '--porcelain'], {
-      cwd: repoRoot,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe']
-    }).trim().split(/\r?\n\r?\n/);
-    const expectedRef = `refs/heads/${branch}`;
-    for (const record of records) {
-      const worktree = /^worktree (.+)$/m.exec(record)?.[1];
-      const branchRef = /^branch (.+)$/m.exec(record)?.[1];
-      if (worktree && branchRef === expectedRef) return worktree;
-    }
-  } catch {
-    // A missing worktree must not anchor a review to an unrelated repository.
-  }
-  return null;
+  return resolveBranchWorktree(repoRoot, branch);
 }
 
 function approvedCleanReviewedCommit(reviewContent: string, verdict: Verdict | undefined, repoRoot: string, branch: string): string | null {
@@ -148,7 +133,7 @@ function approvedCleanReviewedCommit(reviewContent: string, verdict: Verdict | u
   }
 }
 
-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'] },
@@ -758,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 }); }
@@ -851,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 });
@@ -918,12 +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');
     const safetyFailure = capability.reasonCode === 'TASK_NOT_ACTIVE'
       || capability.reasonCode === 'LIFECYCLE_EXECUTION_OPEN';
-    if (!capability.allowed && (normalized.initiator === 'orchestrator' || safetyFailure) && !capabilityOverride) {
+    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 });
     }
@@ -1078,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;
+      }
+    }
+  };
+}

package/lib/task/finalization.ts

@@ -10,6 +10,7 @@ import { taskIssueIdentity } from '../platform/task-identities.ts';
 import { parseTaskFrontmatter } from './frontmatter.ts';
 import {
   applyTaskLifecycle,
+  inspectTaskLifecycleProgress,
   type TaskLifecycleOptions,
   type TaskLifecycleRequest,
   type TaskLifecycleResult
@@ -25,6 +26,9 @@ import {
   type OperationWarning,
   type OperationWarningSeverity
 } from './operation-outcome.ts';
+import { readTaskFinalizationHandoff } from './finalization-handoff.ts';
+import { readSandboxControlManifest } from '../sandbox/control/lifecycle.ts';
+import { validateSandboxControlIdentity } from '../sandbox/control/identity-sentinel.ts';
 
 const RECEIPT_VERSION = 4 as const;
 const FINALIZATION_STEPS = ['lifecycle', 'task-comment', 'verification', 'summary'] as const;
@@ -55,11 +59,14 @@ type TaskFinalizationRequest = Readonly<{
   taskRef: string;
   intent: 'complete';
   agent: string;
+  handoffSha256?: string;
 }>;
 
 type TaskFinalizationOptions = Readonly<{
   repoRoot: string;
   controlBinding?: Readonly<{ generation: string; requestId: string }>;
+  handoffDirectory?: string;
+  manifestPath?: string;
   metadataProvider?: TaskLifecycleOptions['metadataProvider'];
   lifecycle?: typeof applyTaskLifecycle;
   backfill?: typeof backfillCompletionComments;
@@ -198,20 +205,32 @@ function validateReceipt(value: unknown, taskId: string): TaskFinalizationReceip
   const receipt = value as Record<string, unknown>;
   const controlBinding = receipt.controlBinding as Record<string, unknown> | null | undefined;
   const states = ['pending', 'done', 'skipped'];
+  const requiredKeys = [
+    'version', 'taskId', 'intent', 'receiptId', 'revision', 'lifecycle', 'taskComment',
+    'verification', 'summary', 'warningProjection', 'warnings', 'updatedAt', 'lastError'
+  ];
+  if (receipt.controlBinding !== undefined) requiredKeys.push('controlBinding');
   if (
+    Object.keys(receipt).sort().join('\0') !== requiredKeys.sort().join('\0')
+    ||
     receipt.version !== RECEIPT_VERSION || receipt.taskId !== taskId || receipt.intent !== 'complete'
     || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
     || !Number.isSafeInteger(receipt.revision) || Number(receipt.revision) < 0
-    || !states.includes(String(receipt.lifecycle))
-    || !states.includes(String(receipt.taskComment))
-    || !states.includes(String(receipt.verification))
-    || !states.includes(String(receipt.summary))
-    || !['pending', 'done'].includes(String(receipt.warningProjection))
+    || !states.includes(receipt.lifecycle as string)
+    || !states.includes(receipt.taskComment as string)
+    || !states.includes(receipt.verification as string)
+    || !states.includes(receipt.summary as string)
+    || !['pending', 'done'].includes(receipt.warningProjection as string)
     || !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)))
+    || typeof receipt.updatedAt !== 'string' || receipt.updatedAt.length === 0
+    || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)
+      || Object.keys(receipt.lastError).sort().join('\0') !== ['code', 'message', 'retryable'].join('\0')
+      || typeof (receipt.lastError as Record<string, unknown>).code !== 'string'
+      || typeof (receipt.lastError as Record<string, unknown>).message !== 'string'
+      || typeof (receipt.lastError as Record<string, unknown>).retryable !== 'boolean'))
     || (receipt.controlBinding !== undefined && (!controlBinding || typeof controlBinding !== 'object'
       || Array.isArray(controlBinding)
+      || Object.keys(controlBinding).sort().join('\0') !== ['generation', 'requestId'].join('\0')
       || 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');
@@ -243,6 +262,14 @@ function writeReceipt(repoRoot: string, receipt: TaskFinalizationReceipt): void
   }
 }
 
+export function bindTaskFinalizationReceipt(
+  repoRoot: string, taskId: string, controlBinding: Readonly<{ generation: string; requestId: string }>
+): TaskFinalizationReceipt {
+  const receipt = readReceipt(path.resolve(repoRoot), taskId);
+  if (!receipt) throw new Error('TASK_FINALIZATION_PREPARATION_REQUIRED');
+  return updateReceipt(path.resolve(repoRoot), receipt, { controlBinding, lastError: null });
+}
+
 function updateReceipt(
   repoRoot: string,
   receipt: TaskFinalizationReceipt,
@@ -798,10 +825,16 @@ async function prepareUnderLock(
   } catch (error) {
     return failed(taskId, errorOf(error, 'TASK_FINALIZATION_RECEIPT_INVALID'));
   }
-  if (options.controlBinding && (
-    receipt.controlBinding?.generation !== options.controlBinding.generation
-    || receipt.controlBinding.requestId !== options.controlBinding.requestId
-  )) receipt = updateReceipt(repoRoot, receipt, { controlBinding: options.controlBinding });
+  if (options.controlBinding && (receipt.controlBinding?.generation !== options.controlBinding.generation
+    || receipt.controlBinding.requestId !== options.controlBinding.requestId)) {
+    const state = resolveTaskRef(taskId, { repoRoot });
+    if (!(receipt.lifecycle === 'done' && state.ok && state.state === 'completed')) {
+      return failed(taskId, {
+        code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+        message: 'canonical receipt is not bound to the current sandbox request', retryable: false
+      });
+    }
+  }
 
   const preflightState = resolveTaskRef(taskId, { repoRoot });
   if (options.preflight && preflightState.ok && preflightState.state === 'active') {
@@ -1043,13 +1076,88 @@ async function commitPreparedTaskFinalization(request: TaskFinalizationRequest,
   if (!resolved.ok) return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
   try {
     return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.commit', () => {
-      const receipt = readReceipt(repoRoot, resolved.taskId);
+      if (options.controlBinding && options.manifestPath) {
+        try {
+          const manifest = readSandboxControlManifest(options.manifestPath);
+          const identity = validateSandboxControlIdentity({
+            publicStatusDir: manifest.publicStatusDir,
+            root: path.dirname(path.resolve(options.manifestPath)),
+            mode: manifest.mode,
+            taskId: manifest.taskId,
+            generation: manifest.generation,
+            controlRootId: manifest.controlRootId
+          });
+          if (identity.state !== 'valid' || manifest.taskId !== resolved.taskId
+            || manifest.generation !== options.controlBinding.generation
+            || fs.realpathSync.native(manifest.repoRoot) !== fs.realpathSync.native(repoRoot)) {
+            throw new Error('current sandbox manifest does not match finalization request');
+          }
+        } catch (error) {
+          return failed(resolved.taskId, {
+            code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+            message: error instanceof Error ? error.message : String(error), retryable: false
+          });
+        }
+      }
+      let receipt = readReceipt(repoRoot, resolved.taskId);
+      if (!receipt && options.controlBinding && options.handoffDirectory && request.handoffSha256) {
+        try {
+          const handoff = readTaskFinalizationHandoff(
+            options.handoffDirectory, resolved.taskId, options.controlBinding, request.handoffSha256
+          );
+          receipt = validateReceipt(handoff.receipt, resolved.taskId);
+          if (receipt.lifecycle !== 'pending') throw new Error('handoff lifecycle must be pending');
+          if (inspectTaskLifecycleProgress(repoRoot, resolved.taskId, request.agent) === 'unknown') {
+            throw new Error('TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE');
+          }
+          writeReceipt(repoRoot, receipt);
+          try { handoff.cleanup(); } catch { /* keep the persisted canonical receipt usable */ }
+        } catch (error) {
+          return failed(resolved.taskId, {
+            code: 'TASK_FINALIZATION_HANDOFF_INVALID',
+            message: error instanceof Error ? error.message : String(error), retryable: false
+          });
+        }
+      }
       if (!receipt) return failed(resolved.taskId, {
         code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation receipt is unavailable', retryable: true
       });
       if (receipt.lifecycle === 'done' && resolved.state === 'completed') {
         return terminalResult(resolved.taskId, receipt, { lifecycle: { status: 'no-op', changed: false, error: null } }, false);
       }
+      if (options.controlBinding) {
+        const proof = inspectTaskLifecycleProgress(repoRoot, resolved.taskId, request.agent);
+        const oldBinding = receipt.controlBinding;
+        if (!oldBinding || oldBinding.generation !== options.controlBinding.generation || proof === 'unknown') {
+          return failed(resolved.taskId, {
+            code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+            message: 'canonical receipt has no valid host recovery proof', retryable: false
+          });
+        }
+        if (oldBinding.requestId !== options.controlBinding.requestId && proof === 'not-started') {
+          if (receipt.lifecycle !== 'pending' || !options.handoffDirectory || !request.handoffSha256) {
+            return failed(resolved.taskId, {
+              code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+              message: 'pending receipt cannot be rebound without a current handoff', retryable: false
+            });
+          }
+          try {
+            const handoff = readTaskFinalizationHandoff(
+              options.handoffDirectory, resolved.taskId, options.controlBinding, request.handoffSha256
+            );
+            const nextReceipt = validateReceipt(handoff.receipt, resolved.taskId);
+            if (nextReceipt.receiptId !== receipt.receiptId || nextReceipt.intent !== receipt.intent
+              || nextReceipt.lifecycle !== 'pending') throw new Error('handoff is not continuous with canonical receipt');
+            receipt = updateReceipt(repoRoot, receipt, { controlBinding: options.controlBinding });
+            try { handoff.cleanup(); } catch { /* keep the persisted canonical receipt usable */ }
+          } catch (error) {
+            return failed(resolved.taskId, {
+              code: 'TASK_FINALIZATION_HANDOFF_INVALID',
+              message: error instanceof Error ? error.message : String(error), retryable: false
+            });
+          }
+        }
+      }
       if (receipt.taskComment === 'pending' || receipt.verification === 'pending' || receipt.summary === 'pending' || receipt.warningProjection === 'pending') {
         return failed(resolved.taskId, {
           code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation has pending external steps', retryable: true

package/lib/task/intermediate-cleanup.ts

@@ -14,26 +14,14 @@ import {
   readTaskFinalizationReceipt,
   type TaskFinalizationReceipt
 } from './finalization.ts';
-import {
-  semanticDigest,
-  sha256Content
-} from './local-artifact-finalization.ts';
-import { artifactRecoveryRoot, readArtifactRecoveryIntent } from './artifact-repair-intent.ts';
-import type { ArtifactRecoveryIntent } from './artifact-repair-intent.ts';
-import { parseArtifactName } from './artifact-name.ts';
-import type { ArtifactSchemaFamily } from './artifact-schema.ts';
 import { enumerateAllTaskDirs, type TaskWorkspaceState } from './resolve-ref.ts';
 import type { TaskControlBindingEvidence } from './finalization-state.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
-const LOCAL_INTENT_RE = /^(TASK-\d{8}-\d{6})-(analysis|review-analysis|plan|review-plan|code|review-code)-(.+\.md)\.json$/;
 const COMMIT_INTENT_RE = /^(TASK-\d{8}-\d{6})\.json$/;
-const AUXILIARY_ROOTS = [
-  '.local-artifact-finalization-intents',
-  '.task-commit-intents'
-] as const;
+const AUXILIARY_ROOTS = ['.task-commit-intents'] as const;
 
-type CleanupKind = 'LFAI-CONSUMED' | 'COMMIT-SYNCED' | 'EMPTY-AUX-PARENT';
+type CleanupKind = 'COMMIT-SYNCED' | 'EMPTY-AUX-PARENT';
 type CleanupDisposition = 'planned' | 'protected' | 'skipped' | 'deleted' | 'failed';
 type FileIdentity = Readonly<{ dev: string; ino: string; size: number; mtimeMs: number }>;
 
@@ -153,47 +141,6 @@ function receiptGate(
   return null;
 }
 
-function canonicalLocalIntentPath(taskId: string, family: string, artifact: string): string {
-  return `${taskId}-${family}-${artifact}.json`;
-}
-
-function localIntentCandidate(
-  repoRoot: string,
-  task: TaskRecord | undefined,
-  filePath: string,
-  taskId: string,
-  family: ArtifactSchemaFamily,
-  artifact: string,
-  identity: FileIdentity,
-  options: ScanOptions
-): IntermediateCleanupItem {
-  const protectedReason = taskGate(task);
-  if (protectedReason) return item('LFAI-CONSUMED', taskId, filePath, 'protected', protectedReason, identity);
-  if (path.basename(filePath) !== canonicalLocalIntentPath(taskId, family, artifact)
-    || !parseArtifactName(artifact)?.family || parseArtifactName(artifact)!.family !== family) {
-    return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'PATH_IDENTITY_MISMATCH', identity);
-  }
-  let intent: ArtifactRecoveryIntent | null;
-  try { intent = readArtifactRecoveryIntent(repoRoot, taskId, family, artifact); }
-  catch { return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'LFAI_SCHEMA_INVALID', identity); }
-  if (!intent || intent.state !== 'consumed') {
-    return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'LFAI_STATE_PROTECTED', identity);
-  }
-  const artifactPath = path.join(task!.taskDir, artifact);
-  if (safeLstat(task!.taskDir, artifactPath, 'file') === null) {
-    return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'ARTIFACT_IDENTITY_MISMATCH', identity);
-  }
-  let content: string;
-  try { content = fs.readFileSync(artifactPath, 'utf8'); }
-  catch { return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'ARTIFACT_UNREADABLE', identity); }
-  if (intent.finalArtifactSha256 !== sha256Content(content) || intent.finalSemanticDigest !== semanticDigest(content)) {
-    return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'ARTIFACT_DIGEST_MISMATCH', identity);
-  }
-  const receiptReason = receiptGate(repoRoot, task!, options);
-  if (receiptReason) return item('LFAI-CONSUMED', taskId, filePath, 'protected', receiptReason, identity);
-  return item('LFAI-CONSUMED', taskId, filePath, 'planned', 'LFAI_CONSUMED_AND_VERIFIED', identity);
-}
-
 function commitIntentCandidate(
   repoRoot: string,
   task: TaskRecord | undefined,
@@ -258,23 +205,12 @@ function readAuxiliaryCandidates(
         candidates.push(item('AUXILIARY-UNKNOWN', null, filePath, 'protected', 'PATH_IDENTITY_MISMATCH'));
         continue;
       }
-      if (rootName === '.local-artifact-finalization-intents') {
-        const match = LOCAL_INTENT_RE.exec(entry.name);
-        if (!match || (selected && !selected.has(match[1]!))) {
-          if (!selected || !match) candidates.push(item('AUXILIARY-UNKNOWN', null, filePath, 'protected', 'PATH_IDENTITY_MISMATCH', identity));
-          continue;
-        }
-        candidates.push(localIntentCandidate(
-          repoRoot, tasks.get(match[1]!), filePath, match[1]!, match[2] as 'analysis' | 'plan' | 'code', match[3]!, identity, options
-        ));
-      } else {
-        const match = COMMIT_INTENT_RE.exec(entry.name);
-        if (!match || (selected && !selected.has(match[1]!))) {
-          if (!selected || !match) candidates.push(item('AUXILIARY-UNKNOWN', null, filePath, 'protected', 'PATH_IDENTITY_MISMATCH', identity));
-          continue;
-        }
-        candidates.push(commitIntentCandidate(repoRoot, tasks.get(match[1]!), filePath, match[1]!, identity, options));
+      const match = COMMIT_INTENT_RE.exec(entry.name);
+      if (!match || (selected && !selected.has(match[1]!))) {
+        if (!selected || !match) candidates.push(item('AUXILIARY-UNKNOWN', null, filePath, 'protected', 'PATH_IDENTITY_MISMATCH', identity));
+        continue;
       }
+      candidates.push(commitIntentCandidate(repoRoot, tasks.get(match[1]!), filePath, match[1]!, identity, options));
     }
     if (entries.length === 0) {
       candidates.push(item('EMPTY-AUX-PARENT', null, root, 'planned', 'EMPTY_CANONICAL_AUXILIARY_ROOT', rootIdentity));
@@ -307,56 +243,7 @@ function scanIntermediateCleanup(repoRoot: string, options: ScanOptions = {}): I
   return buildIntermediateCleanupReport(candidates, true);
 }
 
-function cleanupConsumedRecoveryFiles(repoRoot: string, task: TaskRecord | undefined, candidate: IntermediateCleanupItem): boolean {
-  if (candidate.kind !== 'LFAI-CONSUMED' || !candidate.taskId) return true;
-  if (!task) return false;
-  const match = LOCAL_INTENT_RE.exec(path.basename(candidate.path));
-  if (!match) return false;
-  let intent: ReturnType<typeof readArtifactRecoveryIntent>;
-  try { intent = readArtifactRecoveryIntent(repoRoot, candidate.taskId, match[2] as ArtifactSchemaFamily, match[3]!); }
-  catch { return false; }
-  if (!intent || intent.state !== 'consumed') return false;
-
-  const recovery = artifactRecoveryRoot(task.taskDir, intent.recoveryOperationId);
-  let stat: fs.Stats | null = null;
-  try { stat = fs.lstatSync(recovery); } catch (error) {
-    if (errorCode(error) === 'ENOENT') return true;
-    return false;
-  }
-  if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
-  let entries: fs.Dirent[];
-  try { entries = fs.readdirSync(recovery, { withFileTypes: true }); } catch { return false; }
-  for (const entry of entries) {
-    if (entry.isSymbolicLink()) return false;
-    if (entry.isFile()) {
-      if (!['baseline.md', 'candidate.md', 'final.md', 'publish.md'].includes(entry.name)) return false;
-      continue;
-    }
-    if (!entry.isDirectory() || entry.name !== 'generations') return false;
-    let generations: fs.Dirent[];
-    try { generations = fs.readdirSync(path.join(recovery, entry.name), { withFileTypes: true }); } catch { return false; }
-    if (generations.some((generation) => generation.isSymbolicLink()
-      || !generation.isFile() || !/^[a-f0-9]{64}\.md$/u.test(generation.name))) return false;
-  }
-  try {
-    for (const entry of entries) {
-      const target = path.join(recovery, entry.name);
-      if (entry.isFile()) fs.unlinkSync(target);
-      else {
-        for (const generation of fs.readdirSync(target, { withFileTypes: true })) fs.unlinkSync(path.join(target, generation.name));
-        fs.rmdirSync(target);
-      }
-    }
-    fs.rmdirSync(recovery);
-    const recoveryRoot = path.dirname(recovery);
-    if (fs.readdirSync(recoveryRoot).length === 0) fs.rmdirSync(recoveryRoot);
-    return true;
-  } catch (error) {
-    return errorCode(error) === 'ENOENT';
-  }
-}
-
-function removeCandidate(repoRoot: string, candidate: IntermediateCleanupItem, task?: TaskRecord): IntermediateCleanupItem {
+function removeCandidate(repoRoot: string, candidate: IntermediateCleanupItem): IntermediateCleanupItem {
   if (candidate.disposition !== 'planned') return candidate;
   const root = candidate.kind === 'EMPTY-AUX-PARENT'
     ? path.dirname(path.dirname(candidate.path))
@@ -373,9 +260,6 @@ function removeCandidate(repoRoot: string, candidate: IntermediateCleanupItem, t
   const actual = safeLstat(root, candidate.path, candidate.kind === 'EMPTY-AUX-PARENT' ? 'directory' : 'file');
   if (!actual) return { ...candidate, disposition: 'protected', reason: 'PATH_IDENTITY_CHANGED' };
   if (!sameFileIdentity(expected, actual)) return { ...candidate, disposition: 'protected', reason: 'PATH_IDENTITY_CHANGED' };
-  if (!cleanupConsumedRecoveryFiles(repoRoot, task, candidate)) {
-    return { ...candidate, disposition: 'protected', reason: 'RECOVERY_STAGING_NOT_SAFE_TO_REMOVE' };
-  }
   try {
     if (candidate.kind === 'EMPTY-AUX-PARENT') {
       if (fs.readdirSync(candidate.path).length !== 0) return { ...candidate, disposition: 'protected', reason: 'AUXILIARY_ROOT_NOT_EMPTY' };
@@ -434,7 +318,7 @@ function cleanupIntermediateUnderRemovalCoordinator(
         if (initialCandidate.disposition !== 'planned') continue;
         const current = refreshedByKey.get(intermediateCleanupKey(initialCandidate));
         items[index] = current
-          ? removeCandidate(repoRoot, current, tasks.get(taskId))
+          ? removeCandidate(repoRoot, current)
           : { ...initialCandidate, disposition: 'protected', reason: 'CANDIDATE_NO_LONGER_ELIGIBLE' };
       }
     };

package/lib/task/ledger-intents.ts

@@ -14,7 +14,6 @@ import type { LedgerRow, ReviewStage } from './ledger.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { writeTask } from './write.ts';
 import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
-import { allowsManualOverride } from './guard-override.ts';
 import { parseLegacyReworkIntentDocument, parseReworkIntentDocument, reworkIntentMutation, upsertReworkIntent } from './rework-intent.ts';
 import type { ReworkClassification, ReworkIntent, ReworkTarget } from './rework-intent.ts';
 import { extractSection, extractSubSection } from './sections.ts';
@@ -149,8 +148,7 @@ function mapWrite(intent: LedgerIntent, entityId: string, before: LedgerRow | nu
 function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {}): LedgerIntentResult {
   const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(intent, resolved.code, resolved.message, resolved.taskId);
-  const stateOverride = allowsManualOverride(options.manualOverride, 'ledger-intent', 'TASK_STATE_MISMATCH');
-  if (resolved.state !== 'active' && !stateOverride) return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  if (resolved.state !== 'active') return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   let content: string;
   let rows: LedgerRow[];
   try {
@@ -353,8 +351,7 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
             ? new Set(['confirmed', 'open', 'needs-human-decision'])
             : before.status === 'cannot-judge' ? new Set(['open', 'needs-human-decision']) : new Set<string>();
         const sameRoundMinorClose = before.status === 'open' && before.severity === 'minor' && intent.status === 'closed';
-        if ((!sameRoundMinorClose && !allowed.has(intent.status))
-          && !allowsManualOverride(options.manualOverride, 'ledger-intent', 'LEDGER_TRANSITION_INVALID')) {
+        if (!sameRoundMinorClose && !allowed.has(intent.status)) {
           return failed(intent, 'LEDGER_TRANSITION_INVALID', `finding '${intent.id}' cannot transition from ${before.status} to ${intent.status}`, resolved.taskId, intent.id);
         }
         after = { ...before, status: intent.status, evidence };
@@ -388,7 +385,7 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
   }
 
   const result = writeTask({
-    taskRef: intent.taskRef, expectedState: stateOverride ? resolved.state : 'active',
+    taskRef: intent.taskRef, expectedState: 'active',
     mutations: [rowMutation(after), ...(implementationMutation ? [implementationMutation] : [])],
     dryRun: 'dryRun' in intent ? intent.dryRun : false
   }, { ...options, taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state } });