@fitlab-ai/agent-infra 0.9.12 → 0.9.13

package/lib/task/capabilities.ts

@@ -0,0 +1,262 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { InvalidationDocument } from './invalidation.ts';
+import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from './invalidation.ts';
+import { receiptForOutput } from './artifact-receipts.ts';
+import { parseTypedTaskFrontmatter } from './frontmatter.ts';
+import { parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.ts';
+import { parseReworkIntentDocument } from './rework-intent.ts';
+import type { ReworkIntent } from './rework-intent.ts';
+import { sha256File } from './artifact-receipts.ts';
+import { hasOpenLifecycleExecution } from './activity-log.ts';
+
+type LifecycleAction =
+  | 'analysis' | 'review-analysis' | 'plan' | 'review-plan'
+  | 'code' | 'review-code' | 'manual-validation' | 'validation-run';
+type TriggerInitiator = 'human' | 'model' | 'orchestrator';
+type TriggerReason = 'user-request' | 'new-requirement' | 'upstream-fact-doubt' | 'review-finding' | 'retry' | 'validation-rerun';
+type ExplicitTrigger = {
+  initiator: TriggerInitiator;
+  requestId: string;
+  requestedAction: LifecycleAction;
+  reasonCode: TriggerReason;
+  sourceFinding?: string;
+  sourceArtifact?: string;
+  sourceSha256?: string;
+  implementationInput?: string;
+  /** False marks the ordinary recommended workflow event; it is not an authorization fact. */
+  explicitRequest?: boolean;
+};
+type LifecycleFacts = {
+  taskState: string;
+  currentStep: string;
+  artifacts: Partial<Record<LifecycleAction, readonly string[]>>;
+  staleArtifacts?: Partial<Record<LifecycleAction, readonly string[]>>;
+  reviewedInputs?: Partial<Record<'review-analysis' | 'review-plan' | 'review-code', string>>;
+  artifactHashes: Readonly<Record<string, string>>;
+  reviews: Partial<Record<'review-analysis' | 'review-plan' | 'review-code', 'approved' | 'changes-requested' | 'rejected'>>;
+  invalidation: InvalidationDocument;
+  reworkIntents?: readonly ReworkIntent[];
+  unresolvedLedger: Record<'analysis' | 'plan' | 'code', number>;
+  executionBusy: boolean;
+  recommendedAction?: LifecycleAction | null;
+};
+type CapabilityResult = {
+  allowed: boolean;
+  reasonCode: string;
+  evidence: readonly string[];
+};
+type LifecycleRecommendation = {
+  action: LifecycleAction | null;
+  reasonCode: string;
+  evidence: readonly string[];
+};
+type LifecycleFactsResult =
+  | { ok: true; facts: LifecycleFacts }
+  | { ok: false; code: 'TASK_CAPABILITY_FACTS_INVALID'; message: string };
+
+const REASONS = new Set<TriggerReason>([
+  'user-request', 'new-requirement', 'upstream-fact-doubt', 'review-finding', 'retry', 'validation-rerun'
+]);
+
+function deny(reasonCode: string, ...evidence: string[]): CapabilityResult {
+  return { allowed: false, reasonCode, evidence };
+}
+
+function allow(...evidence: string[]): CapabilityResult {
+  return { allowed: true, reasonCode: 'CAPABILITY_ALLOWED', evidence };
+}
+
+function hasArtifact(facts: LifecycleFacts, action: LifecycleAction): boolean {
+  return (facts.artifacts[action]?.length ?? 0) > 0;
+}
+
+function canStart(action: LifecycleAction, facts: LifecycleFacts, trigger: ExplicitTrigger): CapabilityResult {
+  if (!trigger || trigger.requestedAction !== action) return deny('TRIGGER_ACTION_MISMATCH', `requested=${trigger?.requestedAction ?? 'missing'}`);
+  if (!trigger.requestId || !trigger.requestId.trim()) return deny('TRIGGER_REQUEST_ID_REQUIRED');
+  if (!REASONS.has(trigger.reasonCode)) return deny('TRIGGER_REASON_INVALID');
+  if (trigger.sourceArtifact && !trigger.sourceSha256) return deny('SOURCE_ARTIFACT_HASH_REQUIRED');
+  if (trigger.sourceSha256 && !trigger.sourceArtifact) return deny('SOURCE_ARTIFACT_REQUIRED');
+  if (trigger.sourceArtifact && trigger.sourceSha256) {
+    const actual = facts.artifactHashes[trigger.sourceArtifact];
+    if (!actual) return deny('SOURCE_ARTIFACT_MISSING', trigger.sourceArtifact);
+    if (actual !== trigger.sourceSha256) return deny('SOURCE_ARTIFACT_HASH_MISMATCH', trigger.sourceArtifact);
+  }
+  if (facts.taskState !== 'active') return deny('TASK_NOT_ACTIVE', `state=${facts.taskState}`);
+  if (invalidationBlocks(facts.invalidation)) return deny('INVALIDATION_INCOMPLETE');
+  if (facts.executionBusy) return deny('EXECUTION_BUSY');
+
+  const implicit = trigger.explicitRequest === false;
+  if (action === 'analysis') {
+    if (!implicit || hasArtifact(facts, 'analysis') || facts.recommendedAction === 'analysis') return allow('analysis-capability');
+    return deny('ANALYSIS_REQUEST_REQUIRES_EXPLICIT_TRIGGER');
+  }
+  if (action === 'review-analysis') {
+    return hasArtifact(facts, 'analysis') ? allow('analysis-artifact') : deny('ANALYSIS_ARTIFACT_REQUIRED');
+  }
+  if (action === 'plan') {
+    if (!hasArtifact(facts, 'review-analysis')) return deny('ANALYSIS_REVIEW_REQUIRED');
+    if (!reviewMatchesLatest(facts, 'analysis', 'review-analysis')) return deny('ANALYSIS_REVIEW_NOT_LATEST');
+    if (facts.reviews['review-analysis'] !== 'approved') return deny('ANALYSIS_REVIEW_NOT_APPROVED');
+    if (facts.unresolvedLedger.analysis > 0) return deny('ANALYSIS_LEDGER_BLOCKED', `unresolved=${facts.unresolvedLedger.analysis}`);
+    return allow('analysis-review-approved');
+  }
+  if (action === 'review-plan') {
+    return hasArtifact(facts, 'plan') ? allow('plan-artifact') : deny('PLAN_ARTIFACT_REQUIRED');
+  }
+  if (action === 'code') {
+    if (trigger.implementationInput) {
+      if (!hasArtifact(facts, 'review-code')) return deny('CODE_REVIEW_REQUIRED');
+      if (!reviewMatchesLatest(facts, 'code', 'review-code')) return deny('CODE_REVIEW_NOT_LATEST');
+      if (facts.reviews['review-code'] !== 'approved') return deny('CODE_REVIEW_NOT_APPROVED');
+      return allow('implementation-input');
+    }
+    if (!hasArtifact(facts, 'review-plan')) return deny('PLAN_REVIEW_REQUIRED');
+    if (!reviewMatchesLatest(facts, 'plan', 'review-plan')) return deny('PLAN_REVIEW_NOT_LATEST');
+    if (facts.reviews['review-plan'] !== 'approved') return deny('PLAN_REVIEW_NOT_APPROVED');
+    if (facts.unresolvedLedger.plan > 0) return deny('PLAN_LEDGER_BLOCKED', `unresolved=${facts.unresolvedLedger.plan}`);
+    return allow('plan-review-approved');
+  }
+  if (action === 'review-code') {
+    return hasArtifact(facts, 'code') ? allow('code-artifact') : deny('CODE_ARTIFACT_REQUIRED');
+  }
+  if (action === 'manual-validation' || action === 'validation-run') {
+    if (!hasArtifact(facts, 'review-code')) return deny('CODE_REVIEW_REQUIRED');
+    if (!reviewMatchesLatest(facts, 'code', 'review-code')) return deny('CODE_REVIEW_NOT_LATEST');
+    if (facts.reviews['review-code'] !== 'approved') return deny('CODE_REVIEW_NOT_APPROVED');
+    if (facts.unresolvedLedger.code > 0) return deny('CODE_LEDGER_BLOCKED', `unresolved=${facts.unresolvedLedger.code}`);
+    return allow('code-review-approved');
+  }
+  return deny('CAPABILITY_ACTION_UNKNOWN');
+}
+
+function artifactRound(name: string): number {
+  const match = /-r(\d+)\.md$/.exec(name);
+  return match ? Number(match[1]) : 1;
+}
+
+function latestArtifact(names: readonly string[]): string | null {
+  return [...names].sort((left, right) => artifactRound(right) - artifactRound(left) || left.localeCompare(right))[0] ?? null;
+}
+
+function reviewedInputName(content: string, expectedFamily: 'analysis' | 'plan' | 'code'): string | null {
+  const header = content.split(/\r?\n/).findIndex((line) => /\*\*(?:审查输入|Review Input)\*\*[:：]/.test(line));
+  if (header < 0) return null;
+  const referenceBlock = content.split(/\r?\n/).slice(header, header + 12).join('\n');
+  const expected = new RegExp('`' + expectedFamily + '(?:-r[2-9]|-r[1-9]\\d+)?\\.md`');
+  return expected.exec(referenceBlock)?.[0].slice(1, -1) ?? null;
+}
+
+function reviewMatchesLatest(facts: LifecycleFacts, source: 'analysis' | 'plan' | 'code', review: 'review-analysis' | 'review-plan' | 'review-code'): boolean {
+  const latestSource = latestArtifact(facts.artifacts[source] ?? []);
+  return Boolean(latestSource && facts.reviewedInputs?.[review] === latestSource);
+}
+
+function recommendNext(facts: LifecycleFacts): LifecycleRecommendation {
+  if (invalidationBlocks(facts.invalidation)) return { action: null, reasonCode: 'INVALIDATION_INCOMPLETE', evidence: ['reconcile task invalidation before routing'] };
+  const pendingIntent = (facts.reworkIntents ?? []).find((intent) => intent.status === 'pending');
+  if (pendingIntent) return { action: pendingIntent.target, reasonCode: 'REWORK_INTENT_PENDING', evidence: [pendingIntent.intentId, pendingIntent.findingId] };
+  if (!hasArtifact(facts, 'analysis')) return { action: 'analysis', reasonCode: 'ANALYSIS_ARTIFACT_MISSING', evidence: ['analysis artifact is absent'] };
+  if (!hasArtifact(facts, 'review-analysis') || !reviewMatchesLatest(facts, 'analysis', 'review-analysis')) {
+    return { action: 'review-analysis', reasonCode: 'ANALYSIS_REVIEW_MISSING', evidence: ['analysis review does not bind the latest analysis artifact'] };
+  }
+  if (facts.reviews['review-analysis'] !== 'approved' || facts.unresolvedLedger.analysis > 0) {
+    return { action: 'analysis', reasonCode: 'ANALYSIS_REWORK_REQUIRED', evidence: ['analysis review or ledger is not clear'] };
+  }
+  if (!hasArtifact(facts, 'plan')) return { action: 'plan', reasonCode: 'PLAN_ARTIFACT_MISSING', evidence: ['plan artifact is absent'] };
+  if (!hasArtifact(facts, 'review-plan') || !reviewMatchesLatest(facts, 'plan', 'review-plan')) {
+    return { action: 'review-plan', reasonCode: 'PLAN_REVIEW_MISSING', evidence: ['plan review does not bind the latest plan artifact'] };
+  }
+  if (facts.reviews['review-plan'] !== 'approved' || facts.unresolvedLedger.plan > 0) {
+    return { action: 'plan', reasonCode: 'PLAN_REWORK_REQUIRED', evidence: ['plan review or ledger is not clear'] };
+  }
+  if (!hasArtifact(facts, 'code')) return { action: 'code', reasonCode: 'CODE_ARTIFACT_MISSING', evidence: ['code artifact is absent'] };
+  if (!hasArtifact(facts, 'review-code') || !reviewMatchesLatest(facts, 'code', 'review-code')) {
+    return { action: 'review-code', reasonCode: 'CODE_REVIEW_MISSING', evidence: ['code review does not bind the latest code artifact'] };
+  }
+  if (facts.reviews['review-code'] !== 'approved') {
+    return { action: 'code', reasonCode: 'CODE_REWORK_REQUIRED', evidence: ['code review or ledger is not clear'] };
+  }
+  return { action: null, reasonCode: 'LIFECYCLE_REVIEWED', evidence: ['latest code review is approved'] };
+}
+
+function buildLifecycleFacts(taskDir: string, content: string, taskState = 'active', executionBusy = false): LifecycleFactsResult {
+  try {
+    const metadata = parseTypedTaskFrontmatter(content);
+    const invalidation = parseInvalidationDocument(content);
+    if (!invalidation.ok) return { ok: false, code: 'TASK_CAPABILITY_FACTS_INVALID', message: invalidation.message };
+    const rework = parseReworkIntentDocument(content);
+    if (!rework.ok) return { ok: false, code: 'TASK_CAPABILITY_FACTS_INVALID', message: rework.message };
+    const ledger = parseLedgerDocument(content);
+    if (ledger.present) {
+      const invalid = validateLedgerRows(ledger.rows);
+      if (invalid) return { ok: false, code: 'TASK_CAPABILITY_FACTS_INVALID', message: invalid.message };
+    }
+    const files = fs.readdirSync(taskDir).filter((name) => {
+      if (!name.endsWith('.md')) return false;
+      const stat = fs.lstatSync(path.join(taskDir, name));
+      return stat.isFile() && !stat.isSymbolicLink();
+    });
+    const artifactFamilies = {
+      analysis: /^analysis(?:-r\d+)?\.md$/,
+      'review-analysis': /^review-analysis(?:-r\d+)?\.md$/,
+      plan: /^plan(?:-r\d+)?\.md$/,
+      'review-plan': /^review-plan(?:-r\d+)?\.md$/,
+      code: /^code(?:-r\d+)?\.md$/,
+      'review-code': /^review-code(?:-r\d+)?\.md$/
+    } as const;
+    const familyFor = (name: string): keyof typeof artifactFamilies | null =>
+      (Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>)
+        .find((family) => artifactFamilies[family].test(name)) ?? null;
+    const activeFiles = files.filter((name) => {
+      const family = familyFor(name);
+      return !family || !isArtifactInvalidated(invalidation.document, family, name);
+    });
+    const artifactHashes: Record<string, string> = {};
+    for (const name of activeFiles) artifactHashes[name] = sha256File(path.join(taskDir, name));
+    const artifacts: Partial<Record<LifecycleAction, readonly string[]>> = Object.fromEntries(
+      (Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>).map((family) => [
+        family, activeFiles.filter((name) => artifactFamilies[family].test(name))
+      ])
+    ) as Partial<Record<LifecycleAction, readonly string[]>>;
+    const staleArtifacts: Partial<Record<LifecycleAction, readonly string[]>> = Object.fromEntries(
+      (Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>).map((family) => [
+        family, files.filter((name) => artifactFamilies[family].test(name) && isArtifactInvalidated(invalidation.document, family, name))
+      ])
+    ) as Partial<Record<LifecycleAction, readonly string[]>>;
+    const reviews: LifecycleFacts['reviews'] = {};
+    const reviewedInputs: NonNullable<LifecycleFacts['reviewedInputs']> = {};
+    for (const family of ['review-analysis', 'review-plan', 'review-code'] as const) {
+      const latest = latestArtifact(artifacts[family] ?? []);
+      if (!latest) continue;
+      const reviewContent = fs.readFileSync(path.join(taskDir, latest), 'utf8');
+      const expectedFamily = family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code';
+      const input = reviewedInputName(reviewContent, expectedFamily);
+      const receipt = input ? receiptForOutput(content, latest) : null;
+      if (input && receipt?.input === input && artifactHashes[input] === receipt.inputSha256) reviewedInputs[family] = input;
+      const parsed = parseReviewSummary(reviewContent);
+      if (!parsed.ok) continue;
+      const verdict = resolveCanonicalVerdict(parsed.summary);
+      if (verdict.ok) reviews[family] = verdict.verdict === 'Approved' ? 'approved' : verdict.verdict === 'Changes Requested' ? 'changes-requested' : 'rejected';
+    }
+    const unresolvedLedger = { analysis: 0, plan: 0, code: 0 };
+    if (ledger.present) {
+      for (const stage of ['analysis', 'plan', 'code'] as const) unresolvedLedger[stage] = summarizeLedgerStage(ledger.rows, stage).unresolved.length;
+    }
+    const facts: LifecycleFacts = {
+      taskState, currentStep: String(metadata.current_step ?? ''), artifacts, reviews,
+      staleArtifacts, reviewedInputs, artifactHashes,
+      invalidation: invalidation.document, reworkIntents: rework.intents,
+      unresolvedLedger, executionBusy: executionBusy || hasOpenLifecycleExecution(content), recommendedAction: null
+    };
+    facts.recommendedAction = recommendNext(facts).action;
+    return { ok: true, facts };
+  } catch (error) {
+    return { ok: false, code: 'TASK_CAPABILITY_FACTS_INVALID', message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export { buildLifecycleFacts, canStart, recommendNext };
+export type { CapabilityResult, ExplicitTrigger, LifecycleAction, LifecycleFacts, LifecycleFactsResult, LifecycleRecommendation, TriggerInitiator, TriggerReason };

package/lib/task/commands/status.ts

@@ -12,6 +12,9 @@ import { parseActivityLog, pairEntries, startedBackedRows } from '../activity-lo
 import { readRun, type OrchestrationRun } from '../orchestration.ts';
 import type { DelegationReceipt } from '../delegation-receipts.ts';
 import { statusCard, type DisplayMessage } from '../../server/display.ts';
+import { invalidationBlocks, parseInvalidationDocument } from '../invalidation.ts';
+import { parseReworkIntentDocument } from '../rework-intent.ts';
+import { buildLifecycleFacts, recommendNext } from '../capabilities.ts';
 
 const USAGE = `Usage: ai task status [--task <ref> | -t <ref>]
 
@@ -381,6 +384,8 @@ type StatusModel = {
   workflow: WorkflowInfo;
   runtime: RuntimeInfo;
   orchestration: OrchestrationInfo;
+  invalidation?: { status: string; processed: number; total: number; pendingIntents: number };
+  recommendation?: string;
   git: GitInfo;
 };
 
@@ -429,6 +434,18 @@ function renderStatus(model: StatusModel): string[] {
     lines.push(...renderPairs(model.artifacts.groups.map((group) => [group.stage, group.files.join(', ')])));
   }
 
+  lines.push(
+    '',
+    'Invalidation',
+    ...renderPairs([
+      ['status', model.invalidation?.status ?? 'unknown'],
+      ['processed', `${model.invalidation?.processed ?? 0}/${model.invalidation?.total ?? 0}`],
+      ['pending_intents', String(model.invalidation?.pendingIntents ?? 0)]
+    ])
+  );
+
+  lines.push('', 'Recommendation', ...renderPairs([['action', model.recommendation ?? DASH]]));
+
   lines.push(
     '',
     'Orchestration',
@@ -494,6 +511,8 @@ function renderStatus(model: StatusModel): string[] {
 }
 
 function modelTone(model: StatusModel): 'info' | 'success' | 'warning' | 'danger' | 'running' {
+  if (model.invalidation?.status === 'invalid') return 'danger';
+  if (model.invalidation?.status === 'pending' || model.invalidation?.status === 'in-progress') return 'warning';
   if (model.orchestration.status === 'paused') return 'warning';
   if (model.orchestration.status === 'running') return 'running';
   if (model.orchestration.status === 'completed') return 'success';
@@ -511,6 +530,23 @@ function buildFromResolved(input: BuildStatusModelInput): StatusModel {
   const run = input.run ?? makeRunner(input.repoRoot);
   const artifacts = enumerateArtifacts(input.taskDir);
   const workflow = collectWorkflow(content, input.now);
+  const invalidation = parseInvalidationDocument(content);
+  const rework = parseReworkIntentDocument(content);
+  const pendingIntents = rework.ok ? rework.intents.filter((intent) => intent.status === 'pending').length : 0;
+  const invalidationInfo = !invalidation.ok
+    ? { status: 'invalid', processed: 0, total: 0, pendingIntents }
+    : {
+        status: invalidation.present
+          ? invalidationBlocks(invalidation.document)
+            ? invalidation.document.operations.some((operation) => operation.status === 'in-progress') ? 'in-progress' : 'pending'
+            : 'completed'
+          : 'none',
+        processed: invalidation.document.operations.reduce((sum, operation) => sum + operation.processed, 0),
+        total: invalidation.document.operations.reduce((sum, operation) => sum + operation.total, 0),
+        pendingIntents
+      };
+  const facts = buildLifecycleFacts(input.taskDir, content, fm.status ?? 'active');
+  const recommendation = facts.ok ? (recommendNext(facts.facts).action ?? DASH) : DASH;
 
   return {
     taskId: input.taskId,
@@ -522,6 +558,8 @@ function buildFromResolved(input: BuildStatusModelInput): StatusModel {
     workflow,
     runtime: collectRuntime(input.taskDir, workflow, run),
     orchestration: collectOrchestration(input.taskDir),
+    invalidation: invalidationInfo,
+    recommendation,
     git: collectGit(fm.branch ?? '', run)
   };
 }

package/lib/task/commit-operation.ts

@@ -210,7 +210,18 @@ function syncTaskCommit(
     );
     const metadata = captureTaskWriteMetadata();
     const commitNote = gitText(task.repoRoot, ['show', '-s', '--format=%h %s', committedHead]);
-    const alreadyLogged = activity.entries.some((entry) => entry.step === 'Commit' && entry.note === commitNote);
+    let matchingCommitIndex = -1;
+    for (let index = activity.entries.length - 1; index >= 0; index -= 1) {
+      const entry = activity.entries[index]!;
+      if (entry.step === 'Commit' && entry.note === commitNote) {
+        matchingCommitIndex = index;
+        break;
+      }
+    }
+    const reviewedAfterCommit = matchingCommitIndex >= 0 && activity.entries
+      .slice(matchingCommitIndex + 1)
+      .some((entry) => /^Review Code \(Round \d+\)$/.test(entry.step));
+    const alreadyLogged = matchingCommitIndex >= 0 && !reviewedAfterCommit;
     const mutations: TaskMutation[] = [];
     if (!alreadyLogged) mutations.push({
       kind: 'section',

package/lib/task/control-authority.ts

@@ -206,15 +206,15 @@ function lifecycleTaskId(request: TaskLifecycleControlRequest, repoRoot: string)
   }
 }
 
-function applyLifecycleWithAuthority(
+async function applyLifecycleWithAuthority(
   context: TaskControlExecutionContext,
   request: TaskLifecycleControlRequest
-): TaskLifecycleResult & { humanOverride?: unknown } {
+): Promise<TaskLifecycleResult & { humanOverride?: unknown }> {
   const conflict = overrideDryRunConflict(request as unknown as Record<string, unknown>);
   if (conflict) {
     return taskLifecycleFailure(request, { code: 'LIFECYCLE_PAYLOAD_INVALID', message: conflict.message });
   }
-  const execute = (): TaskLifecycleResult & { humanOverride?: unknown } => {
+  const execute = async (): Promise<TaskLifecycleResult & { humanOverride?: unknown }> => {
     const lifecycleResult = applyTaskLifecycle(request, { repoRoot: context.repoRoot });
     if (lifecycleResult.status !== 'failed' || !request.overrideTicket) return lifecycleResult;
     if (!request.overrideTarget || !request.overrideScope) {
@@ -223,7 +223,7 @@ function applyLifecycleWithAuthority(
         error: { code: 'OVERRIDE_PAYLOAD_INVALID', message: 'override ticket requires --override-target and --override-scope' }
       };
     }
-    const override = consumeHumanOverride({
+    const override = await consumeHumanOverride({
       taskRef: request.taskRef,
       ticketId: request.overrideTicket,
       failureId: failureId('lifecycle.apply', lifecycleResult.error?.code ?? 'LIFECYCLE_FAILED'),
@@ -238,9 +238,9 @@ function applyLifecycleWithAuthority(
     return { ...lifecycleResult, ...override, humanOverride: override, error: null };
   };
   const taskId = lifecycleTaskId(request, context.repoRoot);
-  if (!taskId) return execute();
+  if (!taskId) return await execute();
   try {
-    return withTaskExecutionLock(
+    return await withTaskExecutionLock(
       context.repoRoot,
       taskId,
       `task-lifecycle.${request.intent}`,
@@ -322,11 +322,11 @@ function orchestrationFailure(error: unknown): OrchestrationResult {
 export function dispatchTaskControlOperation(
   context: TaskControlExecutionContext,
   operation: Extract<TaskControlOperation, { family: 'task-lifecycle' }>
-): TaskLifecycleResult;
+): Promise<TaskLifecycleResult & { humanOverride?: unknown }>;
 export function dispatchTaskControlOperation(
   context: TaskControlExecutionContext,
   operation: Extract<TaskControlOperation, { family: 'task-finalization' }>
-): TaskFinalizationResult;
+): Promise<TaskFinalizationResult>;
 export function dispatchTaskControlOperation(
   context: TaskControlExecutionContext,
   operation: Extract<TaskControlOperation, { family: 'task-orchestration' }>
@@ -345,6 +345,9 @@ export function dispatchTaskControlOperation(
     operationTaskId(context, operation.request.taskRef);
     return applyTaskFinalization(operation.request, {
       repoRoot: context.repoRoot,
+      ...(context.source === 'sandbox-executor' ? {
+        controlBinding: { generation: context.generation, requestId: context.requestId }
+      } : {}),
       preflight: (request, options) => verifyTaskEvent(
         { ...request, event: 'complete-task.hard-preflight' }, options
       )

package/lib/task/create-service.ts

@@ -42,8 +42,8 @@ const DEFAULT_DEPENDENCIES: TaskCreateDependencies = {
   addWarning: applyWorkflowWarningIntent
 };
 
-function verifyCreatedTask(repoRoot: string, taskId: string): { operation: TaskCreateOperation; error: TaskCreateResult['error'] } {
-  const verification = verifyTaskEvent(
+async function verifyCreatedTask(repoRoot: string, taskId: string): Promise<{ operation: TaskCreateOperation; error: TaskCreateResult['error'] }> {
+  const verification = await verifyTaskEvent(
     { taskRef: taskId, event: 'create-task.completed' },
     { repoRoot }
   );
@@ -78,7 +78,7 @@ function issueFromTask(repoRoot: string, taskId: string): { number: number; url:
   return match ? { number: Number(match[1]), url: '' } : null;
 }
 
-function createTask(value: unknown, options: CreateTaskOptions): TaskCreateResult {
+async function createTask(value: unknown, options: CreateTaskOptions): Promise<TaskCreateResult> {
   const dependencies = { ...DEFAULT_DEPENDENCIES, ...options.dependencies };
   let candidate: TaskCreateCandidateV1;
   let local;
@@ -101,13 +101,13 @@ function createTask(value: unknown, options: CreateTaskOptions): TaskCreateResul
     name: 'task:local', status: local.status, reasonCode: null
   }];
   let issue = issueFromTask(options.repoRoot, local.task.id);
-  const created = dependencies.createIssue(local.task.id, { cwd: options.repoRoot, agent: candidate.agent });
+  const created = await dependencies.createIssue(local.task.id, { cwd: options.repoRoot, agent: candidate.agent });
   operations.push(...platformOperations('platform-create', created.operations));
   if (created.issue) issue = { number: created.issue.number, url: created.issue.url };
 
   let platformFailure: PlatformResult | null = created.status === 'failed' || created.status === 'blocked' ? created : null;
   if (!platformFailure && (created.task.issueNumber || issue)) {
-    const synced = dependencies.syncIssue(local.task.id, {
+    const synced = await dependencies.syncIssue(local.task.id, {
       cwd: options.repoRoot,
       agent: candidate.agent,
       status: 'waiting-for-triage',
@@ -120,7 +120,7 @@ function createTask(value: unknown, options: CreateTaskOptions): TaskCreateResul
     if (synced.issue) issue = { number: synced.issue.number, url: synced.issue.url };
     if (synced.status === 'failed' || synced.status === 'blocked') platformFailure = synced;
     if (!platformFailure) {
-      const commented = dependencies.syncComment(local.task.id, { cwd: options.repoRoot, kind: 'task', agent: candidate.agent });
+      const commented = await dependencies.syncComment(local.task.id, { cwd: options.repoRoot, kind: 'task', agent: candidate.agent });
       operations.push(...platformOperations('platform-comment', commented.operations));
       if (commented.status === 'failed' || commented.status === 'blocked') platformFailure = commented;
     }
@@ -133,7 +133,7 @@ function createTask(value: unknown, options: CreateTaskOptions): TaskCreateResul
       code: 'ISSUE_CREATE_FAILED', target: 'issue', message: `${error.code}: ${error.message}`,
       action: 'Fix platform authentication or connectivity, then retry Issue creation for this task.'
     }, { repoRoot: options.repoRoot });
-    const verified = verifyCreatedTask(options.repoRoot, local.task.id);
+    const verified = await verifyCreatedTask(options.repoRoot, local.task.id);
     operations.push(verified.operation);
     if (verified.error) return {
       status: verified.error.retryable ? 'blocked' : 'failed', changed: local.changed,
@@ -150,7 +150,7 @@ function createTask(value: unknown, options: CreateTaskOptions): TaskCreateResul
     };
   }
 
-  const verified = verifyCreatedTask(options.repoRoot, local.task.id);
+  const verified = await verifyCreatedTask(options.repoRoot, local.task.id);
   operations.push(verified.operation);
   if (verified.error) return {
     status: verified.error.retryable ? 'blocked' : 'failed', changed: local.changed,

package/lib/task/current-contract.ts

@@ -2,6 +2,8 @@ import { isValidAgentInfraVersion } from '../version.ts';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, validateLedgerRows } from './ledger.ts';
 import type { LedgerDocument } from './ledger.ts';
+import { parseInvalidationDocument } from './invalidation.ts';
+import type { InvalidationDocument } from './invalidation.ts';
 
 type CurrentTaskContractErrorCode = 'TASK_DOCUMENT_INVALID' | 'TASK_CURRENT_CONTRACT_INVALID';
 type CurrentTaskContractResult =
@@ -9,6 +11,7 @@ type CurrentTaskContractResult =
       ok: true;
       metadata: ReturnType<typeof parseTypedTaskFrontmatter>;
       ledger: LedgerDocument;
+      invalidation: InvalidationDocument;
     }
   | {
       ok: false;
@@ -42,7 +45,9 @@ function validateCurrentTaskContract(content: string): CurrentTaskContractResult
   }
   const invalid = validateLedgerRows(ledger.rows);
   if (invalid) return { ok: false, code: 'TASK_CURRENT_CONTRACT_INVALID', message: `${invalid.code}: ${invalid.message}` };
-  return { ok: true, metadata, ledger };
+  const invalidation = parseInvalidationDocument(content);
+  if (!invalidation.ok) return { ok: false, code: 'TASK_CURRENT_CONTRACT_INVALID', message: `${invalidation.code}: ${invalidation.message}` };
+  return { ok: true, metadata, ledger, invalidation: invalidation.document };
 }
 
 export { validateCurrentTaskContract };

package/lib/task/decision-details.ts

@@ -270,11 +270,15 @@ export {
   normalizeDecisionDetailForDisplay,
   parseDecisionDetailBlocks,
   parseDecisionEvidence,
-  resolveDecisionDetail
+  resolveDecisionDetail,
+  scanVisibleMarkdown
 };
 export type {
   DecisionDetailBlock,
   DecisionDetailDuplicate,
   DecisionDetailInspection,
-  DecisionDetailResolution
+  DecisionDetailResolution,
+  SourceLine,
+  VisibleHeading,
+  VisibleMarkdown
 };