@fitlab-ai/agent-infra 0.9.2 → 0.9.4

package/lib/task/delegation-receipts.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 
 import type { AgentClientId } from '../agent-clients/types.ts';
+import { normalizeAgentToken } from '../agent-clients/tokens.ts';
 
 type DelegationRole = 'executor' | 'reviewer';
 type DelegationStage = 'analysis' | 'review-analysis' | 'plan' | 'review-plan' | 'code' | 'review-code' | 'commit';
@@ -16,13 +17,17 @@ type DelegationReceipt = Readonly<{
   artifact: string;
   client: AgentClientId;
   requestedModel: string | null;
+  requestedReasoningEffort: string | null;
   actualModel: string | null;
+  actualReasoningEffort: string | null;
   modelFallbackReason: string | null;
+  reasoningEffortFallbackReason: string | null;
   parentId: string | null;
   childId: string | null;
   spawnMode: string | null;
   agent: string | null;
   status: DelegationStatus;
+  workspaceSnapshotScope?: 'task';
   beforeFingerprint: string;
   afterFingerprint: string | null;
   changedPaths: readonly string[];
@@ -50,14 +55,16 @@ function fail(code: string, message: string): ReceiptFailure {
 }
 
 function prepareDelegation(
-  input: Omit<DelegationReceipt, 'id' | 'actualModel' | 'modelFallbackReason' | 'parentId' | 'childId' | 'spawnMode' | 'agent' | 'status' | 'afterFingerprint' | 'changedPaths' | 'createdAt' | 'activatedAt' | 'sealedAt' | 'consumedAt'>,
+  input: Omit<DelegationReceipt, 'id' | 'requestedModel' | 'requestedReasoningEffort' | 'actualModel' | 'actualReasoningEffort' | 'modelFallbackReason' | 'reasoningEffortFallbackReason' | 'parentId' | 'childId' | 'spawnMode' | 'agent' | 'status' | 'afterFingerprint' | 'changedPaths' | 'createdAt' | 'activatedAt' | 'sealedAt' | 'consumedAt'> & Readonly<{ requestedModel: string; requestedReasoningEffort: string }>,
   options: { id?: () => string; now?: () => string } = {}
 ): DelegationReceipt {
   return Object.freeze({
     ...input,
     id: (options.id ?? randomUUID)(),
     actualModel: null,
+    actualReasoningEffort: null,
     modelFallbackReason: null,
+    reasoningEffortFallbackReason: null,
     parentId: null,
     childId: null,
     spawnMode: null,
@@ -80,7 +87,9 @@ function activateDelegation(
     parentId: string;
     spawnMode: string;
     actualModel?: string;
+    actualReasoningEffort?: string;
     modelFallbackReason?: string;
+    reasoningEffortFallbackReason?: string;
   }>,
   options: { now?: () => string } = {}
 ): ReceiptResult {
@@ -92,10 +101,29 @@ function activateDelegation(
     return fail('DELEGATION_IDENTITY_INVALID', 'native parent/child identity does not match the prepared delegation');
   }
   if (event.spawnMode !== 'fresh') return fail('DELEGATION_FORK_FORBIDDEN', `spawn mode '${event.spawnMode}' is not fresh`);
-  const actualModel = event.actualModel ?? null;
-  if (actualModel && receipt.requestedModel && actualModel !== receipt.requestedModel && !event.modelFallbackReason) {
+  const actualModel = event.actualModel;
+  if (!actualModel || actualModel.trim() !== actualModel) {
+    return fail('DELEGATION_MODEL_IDENTITY_MISSING', 'native start event must provide a non-empty actual model identity');
+  }
+  if (actualModel !== receipt.requestedModel && (!event.modelFallbackReason || event.modelFallbackReason.trim() === '')) {
     return fail('DELEGATION_MODEL_FALLBACK_UNRECORDED', 'actual model differs from requested model without a fallback reason');
   }
+  const actualReasoningEffort = event.actualReasoningEffort;
+  if (!actualReasoningEffort || actualReasoningEffort.trim() !== actualReasoningEffort) {
+    return fail('DELEGATION_REASONING_EFFORT_MISSING', 'native start event must provide a non-empty actual reasoning effort');
+  }
+  if (
+    actualReasoningEffort !== receipt.requestedReasoningEffort
+    && (!event.reasoningEffortFallbackReason || event.reasoningEffortFallbackReason.trim() === '')
+  ) {
+    return fail('DELEGATION_REASONING_EFFORT_FALLBACK_UNRECORDED', 'actual reasoning effort differs from requested effort without a fallback reason');
+  }
+  if (actualModel === receipt.requestedModel && event.modelFallbackReason) {
+    return fail('DELEGATION_MODEL_FALLBACK_INVALID', 'model fallback reason is only valid when actual model differs');
+  }
+  if (actualReasoningEffort === receipt.requestedReasoningEffort && event.reasoningEffortFallbackReason) {
+    return fail('DELEGATION_REASONING_EFFORT_FALLBACK_INVALID', 'reasoning-effort fallback reason is only valid when actual effort differs');
+  }
   return { ok: true, receipt: Object.freeze({
     ...receipt,
     status: 'activated',
@@ -103,7 +131,9 @@ function activateDelegation(
     childId: event.childId,
     spawnMode: event.spawnMode,
     actualModel,
+    actualReasoningEffort,
     modelFallbackReason: event.modelFallbackReason ?? null,
+    reasoningEffortFallbackReason: event.reasoningEffortFallbackReason ?? null,
     activatedAt: (options.now ?? (() => new Date().toISOString()))()
   }) };
 }
@@ -116,8 +146,7 @@ function completeDelegationStage(
   if (event.stage !== receipt.stage || event.round !== receipt.round || event.artifact !== receipt.artifact) {
     return fail('DELEGATION_STAGE_MISMATCH', 'stage completion identity does not match the active delegation');
   }
-  const acceptedAgents = receipt.client === 'claude-code' ? ['claude', 'claude-code'] : [receipt.client];
-  if (!acceptedAgents.includes(event.agent)) {
+  if (normalizeAgentToken(event.agent) !== normalizeAgentToken(receipt.client)) {
     return fail('DELEGATION_AGENT_MISMATCH', `stage agent '${event.agent}' does not match client '${receipt.client}'`);
   }
   return { ok: true, receipt: Object.freeze({ ...receipt, status: 'stage-completed', agent: event.agent }) };

package/lib/task/events.ts

@@ -21,7 +21,10 @@ import type { ReviewStage } from './ledger.ts';
 import { parseReviewSummary } from './review-artifacts.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { findSectionHeading } from './sections.ts';
-import { completeOrchestrationStage, validateOrchestrationStage } from './orchestration.ts';
+import { validateLifecycleExecution } from './lifecycle-execution.ts';
+import { commitOrchestrationStageCompletion } from './orchestration.ts';
+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';
 
@@ -40,15 +43,19 @@ type TaskEventErrorCode =
   | 'EVENT_UNKNOWN' | 'EVENT_PAYLOAD_INVALID' | 'EVENT_TRANSITION_INVALID'
   | 'EVENT_LOG_MISSING' | 'EVENT_START_MISSING' | 'EVENT_ALREADY_COMPLETED'
   | 'EVENT_LOG_CONFLICT' | 'EVENT_ARTIFACT_CONFLICT' | 'EVENT_FINDING_COUNT_MISMATCH'
+  | 'EVENT_ORCHESTRATION_COMMIT_FAILED'
   | ArtifactErrorCode | TaskWriteErrorCode;
 type TaskEventRequest = {
-  taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean;
+  taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean; orchestrated?: boolean;
   round?: number; question?: number; artifact?: string; fixFor?: string; implementationInput?: string;
   verdict?: Verdict; blockers?: number; major?: number; minor?: number;
   manualValidation?: number; filesModified?: number; testsPassed?: number;
   summaryResult?: string;
 };
 type TaskEventError = { code: TaskEventErrorCode; message: string };
+type TaskEventOptions = TaskWriteOptions & {
+  commitOrchestrationCompletion?: (plan: OrchestrationStageCompletion) => void;
+};
 type TaskEventResult = {
   status: 'planned' | 'applied' | 'no-op' | 'failed'; changed: boolean;
   event: string; requestRef: string; taskId: string | null; taskMdPath: string | null;
@@ -64,17 +71,17 @@ const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun']);
 const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[] }> = {
   'analyze.started': { optional: ['round'] },
   'analyze.awaiting-input': { required: ['question'] },
-  'analyze.completed': { required: ['artifact'], optional: ['round'] },
+  'analyze.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
   'review-analysis.started': { optional: ['round'] },
-  'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+  'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'plan.started': { optional: ['round'] },
-  'plan.completed': { required: ['artifact'], optional: ['round'] },
+  'plan.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
   'review-plan.started': { optional: ['round'] },
-  'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+  'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'code.started': { optional: ['round', 'fixFor', 'implementationInput'] },
-  'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation'] },
+  'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation', 'orchestrated'] },
   'review-code.started': { optional: ['round'] },
-  'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+  'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'manual-validation.started': { optional: ['round'] },
   'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] }
 };
@@ -261,7 +268,7 @@ function openStartedIdentity(rows: ReturnType<typeof pairEntries>, family: Event
   return matches.length === 1 ? matches[0] : matches.length > 1 ? { conflict: true as const } : null;
 }
 
-function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {}): TaskEventResult {
+function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOptions = {}): TaskEventResult {
   const invalid = validateTaskEventRequest(request);
   if (invalid) return failed(request, invalid);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
@@ -334,20 +341,27 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {
     completedArtifact?.path ?? null
   );
   if (findingCountError) return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
-  if (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
+  let orchestrationCompletion: OrchestrationStageCompletion | null = null;
+  if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation') {
     const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
-    const provenance = validateOrchestrationStage(normalized.taskRef, {
-      stage: orchestrationStage,
-      round: normalized.round!,
-      artifact: normalized.artifact!,
-      role: eventIdentity.family.startsWith('review-') ? 'reviewer' : 'executor'
+    const execution = validateLifecycleExecution(normalized.taskRef, {
+      mode: normalized.orchestrated ? 'orchestrated' : 'standalone',
+      identity: {
+        stage: orchestrationStage,
+        round: normalized.round!,
+        artifact: normalized.artifact!,
+        role: eventIdentity.family.startsWith('review-') ? 'reviewer' : 'executor'
+      },
+      agent: normalized.agent,
+      dryRun: normalized.dryRun
     }, { repoRoot: options.repoRoot });
-    if (provenance.status === 'failed' || provenance.status === 'paused') {
+    if (!execution.ok) {
       return failed(normalized, {
         code: 'EVENT_TRANSITION_INVALID',
-        message: provenance.error?.message ?? provenance.run?.pause?.message ?? 'orchestration provenance validation failed'
+        message: `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`
       }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
     }
+    orchestrationCompletion = execution.completionPlan;
   }
   let metadata;
   try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
@@ -384,19 +398,25 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {
   mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body });
   const result = writeTask({ taskRef: normalized.taskRef, expectedState: 'active', dryRun: normalized.dryRun, mutations }, { ...options, 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 (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
-    const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
-    const orchestration = completeOrchestrationStage(normalized.taskRef, {
-      stage: orchestrationStage,
-      round: normalized.round!,
-      artifact: normalized.artifact!,
-      agent: normalized.agent
-    }, { repoRoot: options.repoRoot });
-    if (orchestration.status === 'failed' || orchestration.status === 'paused') {
+  if (!normalized.dryRun && orchestrationCompletion) {
+    try {
+      (options.commitOrchestrationCompletion ?? commitOrchestrationStageCompletion)(orchestrationCompletion);
+    } catch (error) {
       return failed(normalized, {
-        code: 'EVENT_TRANSITION_INVALID',
-        message: orchestration.error?.message ?? orchestration.run?.pause?.message ?? 'orchestration provenance validation failed'
-      }, { 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 });
+        code: 'EVENT_ORCHESTRATION_COMMIT_FAILED',
+        message: `task.md was written but orchestration completion could not be persisted; manual recovery is required: ${error instanceof Error ? error.message : String(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
+      });
     }
   }
   return {
@@ -410,6 +430,31 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {
   };
 }
 
+function applyTaskEvent(request: TaskEventRequest, options: TaskEventOptions = {}): TaskEventResult {
+  const invalid = validateTaskEventRequest(request);
+  if (invalid) return failed(request, invalid);
+  const parts = eventParts(request.event);
+  if (request.dryRun || parts.phase !== 'completed' || parts.family === 'manual-validation') {
+    return applyTaskEventUnlocked(request, options);
+  }
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return applyTaskEventUnlocked(request, options);
+  try {
+    return withTaskExecutionLock(
+      resolved.repoRoot,
+      resolved.taskId,
+      `task-event.${request.event}`,
+      () => applyTaskEventUnlocked(request, options)
+    );
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    return failed(request, {
+      code: 'EVENT_TRANSITION_INVALID',
+      message: `${error.code}: ${error.message}`
+    }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+  }
+}
+
 function successNoOp(
   request: TaskEventRequest, taskId: string, taskMdPath: string, currentStep: string,
   eventIdentity: ReturnType<typeof identity>, timestamp: string,
@@ -425,4 +470,4 @@ function successNoOp(
 }
 
 export { eventCatalog, validateTaskEventRequest, applyTaskEvent };
-export type { TaskEventName, TaskEventRequest, TaskEventResult, TaskEventError, TaskEventErrorCode, Verdict };
+export type { TaskEventName, TaskEventRequest, TaskEventResult, TaskEventError, TaskEventErrorCode, TaskEventOptions, Verdict };

package/lib/task/finalization-artifacts.ts

@@ -0,0 +1,58 @@
+import {
+  assertWritableInventory,
+  inspectTaskArtifacts
+} from './artifact-lifecycle.ts';
+import type {
+  ArtifactError,
+  ArtifactFamily,
+  ArtifactIdentity,
+  InspectOptions
+} from './artifact-lifecycle.ts';
+
+const COMPLETION_BACKFILL_FAMILIES = [
+  'analysis',
+  'review-analysis',
+  'plan',
+  'review-plan',
+  'code',
+  'review-code',
+  'manual-validation'
+] as const satisfies readonly ArtifactFamily[];
+
+type CompletionArtifactResult = {
+  status: 'ready' | 'failed';
+  changed: false;
+  taskId: string | null;
+  taskDir: string | null;
+  artifacts: readonly ArtifactIdentity[];
+  error: ArtifactError | null;
+};
+
+function inspectCompletionArtifacts(
+  taskRef: string,
+  options: InspectOptions = {}
+): CompletionArtifactResult {
+  const artifacts: ArtifactIdentity[] = [];
+  let taskId: string | null = null;
+  let taskDir: string | null = null;
+  for (const family of COMPLETION_BACKFILL_FAMILIES) {
+    const inventory = inspectTaskArtifacts(taskRef, family, options);
+    taskId = inventory.taskId ?? taskId;
+    taskDir = inventory.taskDir ?? taskDir;
+    if (inventory.status === 'failed') {
+      return { status: 'failed', changed: false, taskId, taskDir, artifacts: [], error: inventory.error };
+    }
+    const writableError = assertWritableInventory(inventory);
+    const brokenReference = inventory.diagnostics.find((item) => item.code === 'BROKEN_REFERENCE');
+    const error = writableError ?? (brokenReference ? {
+      code: 'ARTIFACT_REFERENCE_INVALID' as const,
+      message: brokenReference.message
+    } : null);
+    if (error) return { status: 'failed', changed: false, taskId, taskDir, artifacts: [], error };
+    artifacts.push(...inventory.artifacts);
+  }
+  return { status: 'ready', changed: false, taskId, taskDir, artifacts, error: null };
+}
+
+export { COMPLETION_BACKFILL_FAMILIES, inspectCompletionArtifacts };
+export type { CompletionArtifactResult };

package/lib/task/implementation-inputs.ts

@@ -8,7 +8,7 @@ const COLUMNS = [
 const TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}$/;
 const ARTIFACT_RE = /^code(?:-r(?:[2-9]|[1-9]\d+))?\.md$/;
 
-type ImplementationInputStatus = 'pending' | 'not-required' | 'consumed';
+type ImplementationInputStatus = 'declared' | 'pending' | 'not-required' | 'consumed';
 type ImplementationInput = {
   id: string;
   ledgerId: string;
@@ -25,18 +25,18 @@ type ImplementationInputDraft = {
   needsImplementation: boolean;
   decidedAt: string;
 };
+type ImplementationInputDeclaration = Omit<ImplementationInputDraft, 'decidedAt'>;
 
 function validateInput(row: ImplementationInput): void {
   if (!/^II-[1-9]\d*$/.test(row.id)) throw new Error(`implementation input id '${row.id}' is invalid`);
   if (!row.ledgerId || !row.decisionEvidence || /[\r\n]/.test(row.ledgerId) || /[\r\n]/.test(row.decisionEvidence)) throw new Error(`implementation input ${row.id} has incomplete decision identity`);
   if (row.stage !== 'code') throw new Error(`implementation input ${row.id} has invalid stage`);
-  if (!TIMESTAMP_RE.test(row.decidedAt) || !Number.isFinite(Date.parse(row.decidedAt.replace(' ', 'T')))) {
-    throw new Error(`implementation input ${row.id} has invalid decided_at`);
-  }
+  const hasValidTimestamp = TIMESTAMP_RE.test(row.decidedAt) && Number.isFinite(Date.parse(row.decidedAt.replace(' ', 'T')));
   const valid =
-    (row.needsImplementation && row.status === 'pending' && row.consumedBy === '') ||
-    (!row.needsImplementation && row.status === 'not-required' && row.consumedBy === '') ||
-    (row.needsImplementation && row.status === 'consumed' && ARTIFACT_RE.test(row.consumedBy));
+    (row.status === 'declared' && row.decidedAt === '' && row.consumedBy === '') ||
+    (hasValidTimestamp && row.needsImplementation && row.status === 'pending' && row.consumedBy === '') ||
+    (hasValidTimestamp && !row.needsImplementation && row.status === 'not-required' && row.consumedBy === '') ||
+    (hasValidTimestamp && row.needsImplementation && row.status === 'consumed' && ARTIFACT_RE.test(row.consumedBy));
   if (!valid) throw new Error(`implementation input ${row.id} has an invalid state combination`);
 }
 
@@ -79,6 +79,57 @@ function createImplementationInput(rows: readonly ImplementationInput[], draft:
   return row;
 }
 
+function declareImplementationInput(
+  rows: readonly ImplementationInput[], draft: ImplementationInputDeclaration
+): ImplementationInput {
+  const existing = rows.filter((row) => row.ledgerId === draft.ledgerId && row.status === 'declared');
+  if (existing.length > 1) throw new Error(`implementation input declaration for '${draft.ledgerId}' conflicts with existing rows`);
+  if (existing.length === 1) {
+    const row = existing[0]!;
+    if (row.decisionEvidence !== draft.decisionEvidence || row.needsImplementation !== draft.needsImplementation) {
+      throw new Error(`implementation input declaration for '${draft.ledgerId}' conflicts with the existing row`);
+    }
+    return row;
+  }
+  const row: ImplementationInput = {
+    id: nextId(rows), ledgerId: draft.ledgerId, decisionEvidence: draft.decisionEvidence,
+    stage: 'code', needsImplementation: draft.needsImplementation, decidedAt: '',
+    status: 'declared', consumedBy: ''
+  };
+  validateInput(row);
+  return row;
+}
+
+function selectDeclaredImplementationInput(
+  rows: readonly ImplementationInput[], ledgerId: string, decisionEvidence: string
+): ImplementationInput | null {
+  const forLedger = rows.filter((row) => row.ledgerId === ledgerId && row.status === 'declared');
+  if (forLedger.length > 1) throw new Error(`implementation input declaration for '${ledgerId}' is ambiguous`);
+  if (forLedger.length === 0) return null;
+  if (forLedger[0]!.decisionEvidence !== decisionEvidence) {
+    throw new Error(`implementation input declaration for '${ledgerId}' has conflicting evidence`);
+  }
+  return forLedger[0]!;
+}
+
+function finalizeImplementationInput(
+  rows: readonly ImplementationInput[], id: string, decisionEvidence: string, decidedAt: string
+): ImplementationInput[] {
+  let found = false;
+  const next = rows.map((row) => {
+    if (row.id !== id) return row;
+    found = true;
+    if (row.status !== 'declared') throw new Error(`implementation input ${id} is not declared`);
+    return {
+      ...row, decisionEvidence, decidedAt,
+      status: row.needsImplementation ? 'pending' as const : 'not-required' as const
+    };
+  });
+  if (!found) throw new Error(`implementation input ${id} was not found`);
+  next.forEach(validateInput);
+  return next;
+}
+
 function selectPendingImplementationInput(
   rows: readonly ImplementationInput[], reviewCompletedAt: string
 ): ImplementationInput | null {
@@ -130,8 +181,11 @@ export {
   SECTION_ALIASES as IMPLEMENTATION_INPUT_ALIASES,
   createImplementationInput,
   consumeImplementationInput,
+  declareImplementationInput,
+  finalizeImplementationInput,
   parseImplementationInputs,
   renderImplementationInputs,
+  selectDeclaredImplementationInput,
   selectPendingImplementationInput
 };
-export type { ImplementationInput, ImplementationInputDraft, ImplementationInputStatus };
+export type { ImplementationInput, ImplementationInputDeclaration, ImplementationInputDraft, ImplementationInputStatus };

package/lib/task/ledger-intents.ts

@@ -1,6 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import {
+  declareImplementationInput,
+  IMPLEMENTATION_INPUT_ALIASES,
+  parseImplementationInputs,
+  renderImplementationInputs
+} from './implementation-inputs.ts';
 import { LEDGER_COLUMNS, LEDGER_HEADINGS, nextHdId, parseLedger, validateLedgerRows } from './ledger.ts';
 import type { LedgerRow, ReviewStage } from './ledger.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
@@ -13,9 +19,9 @@ type ReviewDisposition = 'confirmed' | 'closed' | 'open' | 'needs-human-decision
 type LedgerIntent =
   | { kind: 'finding-upsert'; taskRef: string; stage: ReviewStage; reviewArtifact: string; ordinal: number; severity: ReviewSeverity; evidence: string; dryRun?: boolean }
   | { kind: 'finding-respond'; taskRef: string; id: string; round: number; status: ExecutorResponse; evidence: string; dryRun?: boolean }
-  | { kind: 'finding-review'; taskRef: string; id: string; status: ReviewDisposition; evidence: string; dryRun?: boolean }
+  | { kind: 'finding-review'; taskRef: string; id: string; status: ReviewDisposition; evidence: string; needsImplementation?: boolean; dryRun?: boolean }
   | { kind: 'decision-next-id'; taskRef: string }
-  | { kind: 'decision-upsert'; taskRef: string; id: string; stage: ReviewStage; artifact: string; dryRun?: boolean };
+  | { kind: 'decision-upsert'; taskRef: string; id: string; stage: ReviewStage; artifact: string; needsImplementation?: boolean; dryRun?: boolean };
 
 type LedgerIntentError = { code: string; message: string };
 type LedgerIntentResult = {
@@ -97,6 +103,15 @@ function ledgerSectionMutation(content: string): TaskMutation[] {
   }];
 }
 
+function implementationInputMutation(content: string, rows: Parameters<typeof renderImplementationInputs>[0]): TaskMutation {
+  const english = /^##\s+Activity Log\s*$/m.test(content);
+  return {
+    kind: 'section', aliases: IMPLEMENTATION_INPUT_ALIASES,
+    heading: english ? 'Implementation Inputs' : '实现输入',
+    body: renderImplementationInputs(rows)
+  };
+}
+
 function mapWrite(intent: LedgerIntent, entityId: string, before: LedgerRow | null, after: LedgerRow, result: ReturnType<typeof writeTask>): LedgerIntentResult {
   if (result.status === 'failed') return failed(intent, result.error.code, result.error.message, result.taskId, entityId);
   return { status: result.status, changed: result.changed, intent: intent.kind, taskId: result.taskId, entityId, before, after, operations: result.operations, error: null };
@@ -189,9 +204,34 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
     }
   }
 
+  let implementationMutation: TaskMutation | null = null;
+  if (intent.kind === 'decision-upsert' || intent.kind === 'finding-review') {
+    const stage = intent.kind === 'decision-upsert' ? intent.stage : after.stage;
+    const escalates = intent.kind === 'decision-upsert' || intent.status === 'needs-human-decision';
+    if (stage === 'code' && escalates && intent.needsImplementation === undefined) {
+      return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'code-stage decisions require --needs-implementation true|false', resolved.taskId, after.id);
+    }
+    if ((stage !== 'code' || !escalates) && intent.needsImplementation !== undefined) {
+      return failed(intent, 'LEDGER_PAYLOAD_INVALID', '--needs-implementation is only valid for code-stage escalation', resolved.taskId, after.id);
+    }
+    if (stage === 'code' && escalates) {
+      try {
+        const parsed = parseImplementationInputs(content);
+        const declaration = declareImplementationInput(parsed.rows, {
+          ledgerId: after.id, decisionEvidence: after.evidence,
+          needsImplementation: intent.needsImplementation!
+        });
+        const nextRows = parsed.rows.includes(declaration) ? parsed.rows : [...parsed.rows, declaration];
+        implementationMutation = implementationInputMutation(content, nextRows);
+      } catch (error) {
+        return failed(intent, 'LEDGER_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId, after.id);
+      }
+    }
+  }
+
   const result = writeTask({
     taskRef: intent.taskRef, expectedState: 'active',
-    mutations: [...ledgerSectionMutation(content), rowMutation(after)],
+    mutations: [...ledgerSectionMutation(content), 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 } });
   return mapWrite(intent, after.id, before, after, result);

package/lib/task/lifecycle-execution.ts

@@ -0,0 +1,106 @@
+import {
+  inspectOrchestrationStage,
+  pauseOrchestration,
+  planOrchestrationStageCompletion,
+  readRun
+} from './orchestration.ts';
+import type {
+  OrchestrationStageCompletion,
+  OrchestrationStageIdentity
+} from './orchestration.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+
+type LifecycleExecutionMode = 'standalone' | 'orchestrated';
+type LifecycleExecutionRequest = Readonly<{
+  mode: LifecycleExecutionMode;
+  identity: OrchestrationStageIdentity;
+  agent?: string;
+  dryRun?: boolean;
+}>;
+type LifecycleExecutionResult = Readonly<{
+  ok: boolean;
+  mode: LifecycleExecutionMode;
+  completionPlan: OrchestrationStageCompletion | null;
+  error: Readonly<{ code: string; message: string }> | null;
+}>;
+
+function failure(mode: LifecycleExecutionMode, code: string, message: string): LifecycleExecutionResult {
+  return { ok: false, mode, completionPlan: null, error: { code, message } };
+}
+
+function inspectLifecycleExecution(
+  taskRef: string,
+  request: LifecycleExecutionRequest,
+  options: Readonly<{ repoRoot?: string }> = {}
+): LifecycleExecutionResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failure(request.mode, resolved.code, resolved.message);
+  if (request.mode === 'standalone') {
+    try {
+      const run = readRun(resolved.taskDir);
+      if (run?.pendingDelegation) {
+        return failure(
+          request.mode,
+          'ORCHESTRATION_STANDALONE_BUSY',
+          'standalone lifecycle execution is blocked by a pending orchestration delegation'
+        );
+      }
+      return { ok: true, mode: request.mode, completionPlan: null, error: null };
+    } catch (error) {
+      return failure(
+        request.mode,
+        'ORCHESTRATION_STATE_INVALID',
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+
+  if (request.agent) {
+    const planned = planOrchestrationStageCompletion(taskRef, {
+      ...request.identity,
+      agent: request.agent
+    }, options);
+    if (planned.plan) {
+      return { ok: true, mode: request.mode, completionPlan: planned.plan, error: null };
+    }
+    return failure(
+      request.mode,
+      planned.result.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH',
+      planned.result.error?.message ?? 'orchestration provenance validation failed'
+    );
+  }
+
+  const inspected = inspectOrchestrationStage(taskRef, request.identity, options);
+  if (inspected.status !== 'failed') {
+    return { ok: true, mode: request.mode, completionPlan: null, error: null };
+  }
+  return failure(
+    request.mode,
+    inspected.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH',
+    inspected.error?.message ?? 'orchestration provenance validation failed'
+  );
+}
+
+function validateLifecycleExecution(
+  taskRef: string,
+  request: LifecycleExecutionRequest,
+  options: Readonly<{ repoRoot?: string }> = {}
+): LifecycleExecutionResult {
+  const inspected = inspectLifecycleExecution(taskRef, request, options);
+  if (inspected.ok || request.mode === 'standalone' || request.dryRun) return inspected;
+  const paused = pauseOrchestration(
+    taskRef,
+    inspected.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH',
+    inspected.error?.message ?? 'orchestration provenance validation failed',
+    true,
+    options
+  );
+  return failure(
+    request.mode,
+    paused.run?.pause?.code ?? inspected.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH',
+    paused.run?.pause?.message ?? inspected.error?.message ?? 'orchestration provenance validation failed'
+  );
+}
+
+export { inspectLifecycleExecution, validateLifecycleExecution };
+export type { LifecycleExecutionMode, LifecycleExecutionRequest, LifecycleExecutionResult };