@fitlab-ai/agent-infra 0.9.12 → 0.9.14

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,

package/lib/task/human-override.ts

@@ -15,7 +15,7 @@ import { inspectLifecycleExecution } from './lifecycle-execution.ts';
 import { applyLedgerIntent } from './ledger-intents.ts';
 import { bindPlatformIssue } from '../platform/issues.ts';
 import { bindPlatformPullRequest } from '../platform/pull-requests.ts';
-import type { GitHubClient } from '../platform/github-client.ts';
+import type { PlatformClient } from '../platform/context.ts';
 import { finalizeReviewSummary } from './review-finalization.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { DocumentMutationError, parseTable } from './sections.ts';
@@ -25,6 +25,9 @@ import { verifyInProcess } from './verification-engine.ts';
 import { canonicalTimestamp, writeTask } from './write.ts';
 import type { TaskFileSystem, TaskWriteMetadata, TaskWriteResult } from './write.ts';
 import { readPrDeliveryFact } from './pr-delivery-fact.ts';
+import { resourceIdentity, resourceIdentityNumber } from '../platform/provider-bridge.ts';
+import type { ResourceIdentity } from '../platform/resource-identity.ts';
+import { taskIssueIdentity } from '../platform/task-identities.ts';
 
 type Eligibility = 'eligible' | 'repair-only' | 'runtime-recovery-only' | 'never-overridable';
 type OutcomeEffect = 'apply-target' | 'retry-same-intent' | 'record-only' | 'no-write';
@@ -96,8 +99,8 @@ type HumanOverrideOptions = Readonly<{
   probeIssueNumber?: number;
   probePullRequestNumber?: number;
   probeStagingDir?: string;
-  platformClient?: GitHubClient;
-  effectExecutor?: (capability: ManualOverrideCapability) => OverrideError | null;
+  platformClient?: PlatformClient;
+  effectExecutor?: (capability: ManualOverrideCapability) => OverrideError | null | Promise<OverrideError | null>;
 }>;
 
 type FailureSnapshot = Readonly<{
@@ -584,7 +587,7 @@ function snapshotEvidence(
   content: string,
   frontmatter: Record<string, unknown> | null,
   producer: ProducerFailure,
-  resource: Readonly<{ kind: 'issue' | 'pull-request'; number: number }> | null
+  resource: Readonly<{ kind: 'issue' | 'pull-request'; identity: ResourceIdentity; number: number | null }> | null
 ): string {
   const stableFrontmatter = frontmatter
     ? Object.fromEntries(Object.entries(frontmatter).filter(([key]) => !['updated_at', 'agent_infra_version', 'status', 'blocked_at', 'completed_at', 'cancelled_at'].includes(key)))
@@ -609,15 +612,22 @@ function resourceForSnapshot(
   policy: FailurePolicy,
   options: HumanOverrideOptions,
   frontmatter: Record<string, unknown> | null
-): Readonly<{ kind: 'issue' | 'pull-request'; number: number }> | null {
+): Readonly<{ kind: 'issue' | 'pull-request'; identity: ResourceIdentity; number: number | null }> | null {
   if (policy.producerId === 'platform.issue') {
-    const number = options.probeIssueNumber ?? toPositiveInteger(frontmatter?.issue_number);
-    return number === null ? null : { kind: 'issue', number };
+    const identity = options.probeIssueNumber !== undefined
+      ? resourceIdentity(options.probeIssueNumber)
+      : taskIssueIdentity((frontmatter || {}) as Record<string, string | number | boolean | null>) || (() => {
+        const number = toPositiveInteger(frontmatter?.issue_number);
+        return number === null ? null : resourceIdentity(number);
+      })();
+    return identity ? { kind: 'issue', identity, number: resourceIdentityNumber(identity) } : null;
   }
   if (policy.producerId === 'platform.pull-request') {
     const fact = frontmatter ? readPrDeliveryFact(frontmatter) : null;
-    const number = options.probePullRequestNumber ?? (fact?.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null);
-    return number === null ? null : { kind: 'pull-request', number };
+    const identity = options.probePullRequestNumber !== undefined
+      ? resourceIdentity(options.probePullRequestNumber)
+      : fact?.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
+    return identity ? { kind: 'pull-request', identity, number: resourceIdentityNumber(identity) } : null;
   }
   return null;
 }
@@ -694,41 +704,52 @@ function probeNotObserved(policy: FailurePolicy): OverrideError {
   return error('OVERRIDE_FAILURE_NOT_PRESENT', `producer ${policy.producerId} did not produce ${policy.code}`);
 }
 
-function probePlatformFailure(
+async function probePlatformFailure(
   taskRef: string,
   policy: FailurePolicy,
   resolved: ProbeTask,
   options: HumanOverrideOptions
-): ProducerFailure | OverrideError {
+): Promise<ProducerFailure | OverrideError> {
   let frontmatter: ReturnType<typeof parseTypedTaskFrontmatter>;
   try {
     frontmatter = parseTypedTaskFrontmatter(fs.readFileSync(path.join(resolved.taskDir, 'task.md'), 'utf8'));
   } catch (cause) {
     return error('OVERRIDE_DOCUMENT_INVALID', cause instanceof Error ? cause.message : String(cause));
   }
-  const issueNumber = options.probeIssueNumber ?? toPositiveInteger(frontmatter.issue_number);
+  const issueIdentity = options.probeIssueNumber !== undefined
+    ? resourceIdentity(options.probeIssueNumber)
+    : taskIssueIdentity(frontmatter) || (() => {
+      const number = toPositiveInteger(frontmatter.issue_number);
+      return number === null ? null : resourceIdentity(number);
+    })();
   const fact = readPrDeliveryFact(frontmatter);
-  const pullRequestNumber = options.probePullRequestNumber ?? (fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null);
-  const operation = policy.producerId === 'platform.issue'
-    ? issueNumber === null
+  const pullRequestIdentity = options.probePullRequestNumber !== undefined
+    ? resourceIdentity(options.probePullRequestNumber)
+    : fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
+  const token = (identity: ResourceIdentity | null): string | null => identity ? String(identity.value) : null;
+  const issueToken = token(issueIdentity);
+  const pullRequestToken = token(pullRequestIdentity);
+  const operation = await (policy.producerId === 'platform.issue'
+    ? issueToken === null
       ? null
       : bindPlatformIssue(taskRef, {
-        issue: issueNumber,
+        issue: issueToken,
         agent: options.probeOperator ?? 'local-operator',
         dryRun: true,
         cwd: resolved.repoRoot,
         ...(options.platformClient ? { client: options.platformClient } : {})
       })
-    : pullRequestNumber === null
+    : pullRequestToken === null
       ? null
       : bindPlatformPullRequest(taskRef, {
-        pr: pullRequestNumber,
+        pr: pullRequestToken,
         agent: options.probeOperator ?? 'local-operator',
         dryRun: true,
         cwd: resolved.repoRoot,
         ...(options.platformClient ? { client: options.platformClient } : {})
-      });
-  if (!operation) return error('OVERRIDE_PROBE_INPUT_MISSING', `${policy.producerId} requires a bound issue or pull request number`);
+      })
+  );
+  if (!operation) return error('OVERRIDE_PROBE_INPUT_MISSING', `${policy.producerId} requires a bound issue or pull request identity`);
   if (operation.status !== 'failed' && operation.status !== 'blocked') return probeNotObserved(policy);
   if (!operation.error) return error('OVERRIDE_PROBE_INPUT_MISSING', `${policy.producerId} returned no platform error evidence`);
   return {
@@ -766,6 +787,9 @@ function probeTaskEventFailure(taskRef: string, policy: FailurePolicy, resolved:
       event: candidate.event,
       agent: 'codex',
       dryRun: true,
+      initiator: 'model',
+      requestId: `override-probe:${taskRef}:${candidate.event}`,
+      reasonCode: 'user-request',
       ...(candidate.artifact ? { artifact: candidate.artifact } : {})
     }, { repoRoot: resolved.repoRoot, lockAlreadyHeld: true });
     const matched = probeResult(policy, result, resolved.state);
@@ -774,8 +798,8 @@ function probeTaskEventFailure(taskRef: string, policy: FailurePolicy, resolved:
   return probeNotObserved(policy);
 }
 
-function probeVerificationFailure(taskRef: string, policy: FailurePolicy, resolved: ProbeTask): ProducerFailure | OverrideError {
-  const result = verifyTaskEvent(
+async function probeVerificationFailure(taskRef: string, policy: FailurePolicy, resolved: ProbeTask): Promise<ProducerFailure | OverrideError> {
+  const result = await verifyTaskEvent(
     {
       taskRef,
       event: 'review-code.completed',
@@ -795,12 +819,12 @@ function latestArtifact(taskDir: string, family: string): string | undefined {
   ));
   candidates.sort((a, b) => {
     const round = (name: string) => Number(/-r(\d+)\.md$/.exec(name)?.[1] ?? 1);
-    return round(b) - round(a);
-  });
+      return round(b) - round(a);
+    });
   return candidates[0];
 }
 
-function probeVerificationEngineFailure(policy: FailurePolicy, resolved: ProbeTask): ProducerFailure | OverrideError {
+async function probeVerificationEngineFailure(policy: FailurePolicy, resolved: ProbeTask): Promise<ProducerFailure | OverrideError> {
   const candidates = [
     { skillName: 'review-code', family: 'review-code' },
     { skillName: 'review-plan', family: 'review-plan' },
@@ -814,7 +838,7 @@ function probeVerificationEngineFailure(policy: FailurePolicy, resolved: ProbeTa
     const artifactFile = candidate.family ? latestArtifact(resolved.taskDir, candidate.family) : undefined;
     if (candidate.family && !artifactFile) continue;
     try {
-      const payload = verifyInProcess({
+      const payload = await verifyInProcess({
         mode: 'gate',
         skillName: candidate.skillName,
         taskDir: resolved.taskDir,
@@ -838,12 +862,12 @@ function probeVerificationEngineFailure(policy: FailurePolicy, resolved: ProbeTa
   return probeNotObserved(policy);
 }
 
-function probeGenericFailure(
+async function probeGenericFailure(
   taskRef: string,
   policy: FailurePolicy,
   resolved: ProbeTask,
   options: HumanOverrideOptions = {}
-): ProducerFailure | OverrideError {
+): Promise<ProducerFailure | OverrideError> {
   switch (policy.producerId) {
     case 'task.resolve':
       return probeNotObserved(policy);
@@ -852,9 +876,9 @@ function probeGenericFailure(
     case 'task-event':
       return probeTaskEventFailure(taskRef, policy, resolved);
     case 'task-verify':
-      return probeVerificationFailure(taskRef, policy, resolved);
+      return await probeVerificationFailure(taskRef, policy, resolved);
     case 'verification-engine':
-      return probeVerificationEngineFailure(policy, resolved);
+      return await probeVerificationEngineFailure(policy, resolved);
     case 'activity-intent':
       return probeResult(policy, applyPrReviewActivityIntent({
         kind: 'pr-review-start', taskRef, agent: 'codex', artifact: 'pr-review.md', head: '0'.repeat(40), dryRun: true
@@ -889,7 +913,7 @@ function probeGenericFailure(
     }
     case 'platform.issue':
     case 'platform.pull-request':
-      return probePlatformFailure(taskRef, policy, resolved, options);
+      return await probePlatformFailure(taskRef, policy, resolved, options);
     default:
       return error('OVERRIDE_PROBE_INPUT_MISSING', `no producer probe is registered for ${policy.producerId}`);
   }
@@ -899,7 +923,7 @@ function isProducerFailure(value: ProducerFailure | OverrideError): value is Pro
   return 'observedFacts' in value && 'state' in value && Array.isArray(value.observedFacts);
 }
 
-function captureFailureSnapshot(taskRef: string, failureIdValue: string, target: string, options: HumanOverrideOptions = {}): FailureSnapshot | OverrideError {
+async function captureFailureSnapshot(taskRef: string, failureIdValue: string, target: string, options: HumanOverrideOptions = {}): Promise<FailureSnapshot | OverrideError> {
   const policy = policyFor(failureIdValue);
   if (!policy) return error('OVERRIDE_FAILURE_UNKNOWN', `failure policy '${failureIdValue}' is not registered`);
   if (!policy.targets.includes(target)) return error('OVERRIDE_TARGET_INVALID', `target '${target}' is not registered for ${failureIdValue}`);
@@ -915,7 +939,7 @@ function captureFailureSnapshot(taskRef: string, failureIdValue: string, target:
   try { frontmatter = parseTypedTaskFrontmatter(content); } catch { /* probe reports an unconfirmed identity */ }
   const producer: ProducerFailure | OverrideError = policy.producerId === LIFECYCLE_PRODUCER
     ? probeLifecycleFailure(taskRef, policy, resolved, options)
-    : probeGenericFailure(taskRef, policy, resolved, options);
+    : await probeGenericFailure(taskRef, policy, resolved, options);
   if (!isProducerFailure(producer)) return producer;
   const digest = computeFailureDigest(snapshotEvidence(
     resolved.taskId,
@@ -984,7 +1008,7 @@ function validateResourceNumbers(request: HumanOverrideRequest): OverrideError |
   return null;
 }
 
-function issueHumanOverride(request: HumanOverrideRequest, options: HumanOverrideOptions = {}): HumanOverrideIssueResult {
+async function issueHumanOverride(request: HumanOverrideRequest, options: HumanOverrideOptions = {}): Promise<HumanOverrideIssueResult> {
   const invalid = validateCommon(request);
   if (invalid) return failedIssue(invalid.code, invalid.message);
   const policy = policyFor(request.failureId);
@@ -1005,7 +1029,7 @@ function issueHumanOverride(request: HumanOverrideRequest, options: HumanOverrid
   const document = readTask(resolved.taskMdPath);
   if ('code' in document) return failedIssue(document.code, document.message, resolved.taskId);
   if (document.frontmatter.id !== resolved.taskId) return failedIssue('OVERRIDE_DOCUMENT_INVALID', 'task frontmatter id does not match resolved task', resolved.taskId);
-  const snapshotResult = captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
+  const snapshotResult = await captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
     ...options,
     probeIntent: request.intent,
     probeOperator: request.operator,
@@ -1127,18 +1151,18 @@ function lifecycleRequestFor(
   return { taskRef, intent: 'restore', agent: operator, stagingDir, issueNumber };
 }
 
-function applyOutcomeEffect(
+async function applyOutcomeEffect(
   request: ConsumeHumanOverrideRequest,
   row: Readonly<Record<string, string>>,
   snapshot: FailureSnapshot,
   outcome: Outcome,
   options: HumanOverrideOptions
-): OverrideError | null {
+): Promise<OverrideError | null> {
   if (outcome.effect === 'no-write' || outcome.effect === 'record-only') return null;
   const intent = outcome.target === 'safe-close' ? 'cancel' : row.intent || request.intent;
   if (!intent && outcome.target === 'continue-local') {
     if (!options.effectExecutor) return error('OVERRIDE_EFFECT_EXECUTOR_MISSING', 'the producer must supply an effect executor for a continue-local outcome');
-    return options.effectExecutor({
+    return await options.effectExecutor({
       failureId: request.failureId,
       operator: row.operator ?? 'local-operator',
       reason: row.reason ?? snapshot.message
@@ -1242,7 +1266,7 @@ function snapshotFromTicket(taskId: string, row: Readonly<Record<string, string>
   };
 }
 
-function consumeHumanOverride(request: ConsumeHumanOverrideRequest, options: HumanOverrideOptions = {}): HumanOverrideConsumeResult {
+async function consumeHumanOverride(request: ConsumeHumanOverrideRequest, options: HumanOverrideOptions = {}): Promise<HumanOverrideConsumeResult> {
   const values = [request.taskRef, request.ticketId, request.failureId, request.target, request.scope];
   if (values.some((value) => !singleLine(value))) {
     return failedConsume('OVERRIDE_PAYLOAD_INVALID', 'consume fields must be non-empty single-line values', request.ticketId || null);
@@ -1278,7 +1302,7 @@ function consumeHumanOverride(request: ConsumeHumanOverrideRequest, options: Hum
     if (isOverrideError(recoverySnapshot)) return failedConsume(recoverySnapshot.code, recoverySnapshot.message, request.ticketId, resolved.taskId);
     snapshot = recoverySnapshot;
   } else {
-    const snapshotResult = captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
+    const snapshotResult = await captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
       ...options,
       probeIntent: row.values.intent ? row.values.intent as TaskLifecycleIntent : request.intent,
       probeOperator: row.values.operator,
@@ -1323,7 +1347,7 @@ function consumeHumanOverride(request: ConsumeHumanOverrideRequest, options: Hum
     if (staged.status === 'planned') return failedConsume('OVERRIDE_WRITE_INVALID', 'override writes cannot be planned', request.ticketId, resolved.taskId);
     effectRow = { ...row.values, status: 'consuming', effect: outcome.effect, result: outcome.result, context_id: outcome.contextId, residual: `effect pending: ${outcome.residual}` };
   }
-  const effectError = applyOutcomeEffect(request, effectRow, snapshot, outcome, options);
+  const effectError = await applyOutcomeEffect(request, effectRow, snapshot, outcome, options);
   if (effectError) return failedConsume(effectError.code, effectError.message, request.ticketId, resolved.taskId);
   const after = resolveTask(request.taskRef, options);
   if (!after.ok) return failedConsume(after.code, after.message, request.ticketId, after.taskId);
@@ -1359,7 +1383,7 @@ function diagnoseHumanOverride(failure: string, target?: string) {
   };
 }
 
-function diagnoseHumanOverrideForTask(
+async function diagnoseHumanOverrideForTask(
   taskRef: string,
   failure?: string,
   target?: string,
@@ -1403,12 +1427,12 @@ function diagnoseHumanOverrideForTask(
       error: error('OVERRIDE_FAILURE_UNKNOWN', `failure policy '${failure}' is not registered`)
     };
   }
-  const probes = policies
+  const probes = await Promise.all(policies
     .filter((policy) => !target || policy.targets.includes(target))
-    .map((policy) => {
+    .map(async (policy) => {
       const producer = policy.producerId === LIFECYCLE_PRODUCER
         ? probeLifecycleFailure(taskRef, policy, resolved, options)
-    : probeGenericFailure(taskRef, policy, resolved, options);
+        : await probeGenericFailure(taskRef, policy, resolved, options);
       const observed = isProducerFailure(producer);
       return {
         failureId: policy.id,
@@ -1422,7 +1446,7 @@ function diagnoseHumanOverrideForTask(
         message: observed ? producer.message : producer.message,
         errorCode: observed ? null : producer.code
       };
-    });
+    }));
   const blockedBy = probes.filter((probe) => probe.status === 'observed');
   return {
     status: 'ready' as const,

package/lib/task/index.ts

@@ -1,3 +1,8 @@
+import {
+  PUBLIC_CLI_ROUTE_SELECTORS,
+  PUBLIC_CLI_SELECTOR_ALIASES
+} from '../internal/cli-route-inventory.ts';
+
 const USAGE = `Usage: ai task <command> [options]
 
 Commands:
@@ -30,6 +35,7 @@ Examples:
   ai task status --task 11
 
 Run 'ai task <command> --help' for details.`;
+const TASK_OPERATIONS = PUBLIC_CLI_ROUTE_SELECTORS.task;
 
 export async function runTask(args: string[]): Promise<void> {
   const [subcommand, ...rest] = args;
@@ -45,14 +51,21 @@ export async function runTask(args: string[]): Promise<void> {
     return;
   }
 
-  switch (subcommand) {
+  const routeSelector: string = PUBLIC_CLI_SELECTOR_ALIASES.task[subcommand as keyof typeof PUBLIC_CLI_SELECTOR_ALIASES.task] ?? subcommand;
+  if (!TASK_OPERATIONS.includes(routeSelector as typeof TASK_OPERATIONS[number])) {
+    process.stderr.write(`Unknown task command: ${subcommand}\n\n`);
+    process.stdout.write(`${USAGE}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  switch (routeSelector) {
     case 'cat': {
       const { cat } = await import('./commands/cat.ts');
       cat(rest);
       break;
     }
-    case 'decisions':
-    case 'd': {
+    case 'decisions': {
       const { decisions } = await import('./commands/decisions.ts');
       decisions(rest);
       break;

package/lib/task/invalidation-command.ts

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { parseArtifactReceipts, sha256File } from './artifact-receipts.ts';
+import { invalidationMutation, parseInvalidationDocument, reconcileInvalidation } from './invalidation.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { writeTask } from './write.ts';
+import type { TaskWriteOptions } from './write.ts';
+
+type InvalidationCommandOptions = TaskWriteOptions & { now?: () => string; maxTargets?: number; dryRun?: boolean };
+type InvalidationCommandResult = {
+  status: 'applied' | 'planned' | 'no-op' | 'failed';
+  changed: boolean;
+  taskId: string | null;
+  processed: number;
+  remaining: number;
+  error: { code: string; message: string } | null;
+};
+
+function reconcileTaskInvalidation(taskRef: string, options: InvalidationCommandOptions = {}): InvalidationCommandResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return { status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: 0, error: { code: resolved.code, message: resolved.message } };
+  let content: string;
+  try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
+  catch (error) { return { status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: 0, error: { code: 'TASK_READ_FAILED', message: error instanceof Error ? error.message : String(error) } }; }
+  const parsed = parseInvalidationDocument(content);
+  if (!parsed.ok) return { status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: 0, error: { code: parsed.code, message: parsed.message } };
+  if (!parsed.present) return { status: 'no-op', changed: false, taskId: resolved.taskId, processed: 0, remaining: 0, error: null };
+  const beforePending = parsed.document.targets.filter((target) => target.status !== 'completed').length;
+  let receipts;
+  try { receipts = parseArtifactReceipts(content).rows; }
+  catch (error) {
+    if (parsed.document.targets.some((target) => target.status !== 'completed' && target.targetKind === 'receipt')) {
+      return {
+        status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending,
+        error: { code: 'INVALIDATION_TARGET_HASH_CONFLICT', message: error instanceof Error ? error.message : String(error) }
+      };
+    }
+    receipts = [];
+  }
+  for (const target of parsed.document.targets) {
+    if (target.status === 'completed') continue;
+    if (target.targetKind === 'receipt') {
+      const receipt = receipts.find((candidate) => candidate.output === target.targetArtifact);
+      if (!receipt || receipt.inputSha256 !== target.targetSha256) {
+        return {
+          status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending,
+          error: { code: 'INVALIDATION_TARGET_HASH_CONFLICT', message: `invalidation receipt target '${target.targetArtifact}' changed before reconcile` }
+        };
+      }
+      continue;
+    }
+    const targetPath = path.join(resolved.taskDir, target.targetArtifact);
+    try {
+      const stat = fs.lstatSync(targetPath);
+      if (!stat.isFile() || stat.isSymbolicLink() || sha256File(targetPath) !== target.targetSha256) {
+        return {
+          status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending,
+          error: { code: 'INVALIDATION_TARGET_HASH_CONFLICT', message: `invalidation target '${target.targetArtifact}' changed before reconcile` }
+        };
+      }
+    } catch {
+      return {
+        status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending,
+        error: { code: 'INVALIDATION_TARGET_HASH_CONFLICT', message: `invalidation target '${target.targetArtifact}' is unavailable before reconcile` }
+      };
+    }
+  }
+  const reconciled = reconcileInvalidation(parsed.document, (options.now ?? (() => new Date().toISOString()))(), options.maxTargets);
+  if (!reconciled.ok) return { status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending, error: { code: reconciled.code, message: reconciled.message } };
+  if (!reconciled.changed) return { status: 'no-op', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending, error: null };
+  const result = writeTask({
+    taskRef, expectedState: resolved.state, dryRun: options.dryRun,
+    mutations: [invalidationMutation(content, reconciled.document)]
+  }, { ...options, invalidationContext: 'reconcile', taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state } });
+  if (result.status === 'failed') return { status: 'failed', changed: false, taskId: resolved.taskId, processed: beforePending - reconciled.document.targets.filter((target) => target.status !== 'completed').length, remaining: reconciled.document.targets.filter((target) => target.status !== 'completed').length, error: result.error };
+  return {
+    status: result.status, changed: result.changed, taskId: resolved.taskId,
+    processed: beforePending - reconciled.document.targets.filter((target) => target.status !== 'completed').length,
+    remaining: reconciled.document.targets.filter((target) => target.status !== 'completed').length,
+    error: null
+  };
+}
+
+export { reconcileTaskInvalidation };
+export type { InvalidationCommandOptions, InvalidationCommandResult };