@fitlab-ai/agent-infra 0.11.2 → 0.11.3

package/lib/task/lifecycle-recovery.ts

@@ -1,691 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.ts';
-import type { StoredCodexLifecycle } from '../agent-clients/adapters/codex-lifecycle/store.ts';
-import { managedDelegationRole } from './delegation-receipts.ts';
-import type { DelegationReceipt } from './delegation-receipts.ts';
-import { normalizeAgentToken } from '../agent-clients/tokens.ts';
-import { artifactName, parseArtifactName } from './artifact-name.ts';
-import { locateActivityLog, pairEntries } from './activity-log.ts';
-import type { LogEntry, StepRow } from './activity-log.ts';
-import { captureTaskWriteMetadata, writeTask } from './write.ts';
-import { parseTypedTaskFrontmatter } from './frontmatter.ts';
-import { resolveTaskRef, TASK_ID_RE } from './resolve-ref.ts';
-import { resolveAgentRuntimeStoreRoot } from '../runtime/agent-runtime.ts';
-import {
-  recoverActivatedOrchestrationDelegationUnderLock,
-  readRun
-} from './orchestration.ts';
-import type { OrchestrationOptions, OrchestrationRun } from './orchestration.ts';
-import { isRecoveryWarning, sameRecoveryWarning } from './recovery-warning.ts';
-import type { RecoveryWarning } from './recovery-warning.ts';
-
-const RECOVERY_NOTE_PREFIX = 'lifecycle-recovery:v1 ';
-const RECOVERY_STAGES = ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'] as const;
-const ACTIONS: Readonly<Record<typeof RECOVERY_STAGES[number], string>> = {
-  analysis: 'Analyze Task',
-  'review-analysis': 'Review Analysis',
-  plan: 'Plan Task',
-  'review-plan': 'Review Plan',
-  code: 'Code Task',
-  'review-code': 'Review Code'
-};
-const RECOVERY_NOTE_KEYS = [
-  'version', 'taskId', 'stage', 'round', 'artifact', 'startedAgent', 'receiptId', 'childId',
-  'stopRevision', 'consumer', 'consumedAt', 'owner', 'reason'
-] as const;
-
-type RecoveryStage = (typeof RECOVERY_STAGES)[number];
-type LifecycleRecoveryRequest = Readonly<{
-  taskRef: string;
-  intent: 'recover-started';
-  agent: string;
-  stage: RecoveryStage;
-  round: number;
-  artifact: string;
-  reason: string;
-}>;
-type RecoveryCommitVerification = { ok: true; receipt: DelegationReceipt } | { ok: false; message: string };
-type LifecycleRecoveryResult = Readonly<{
-  status: 'applied' | 'no-op' | 'owner-unknown' | 'conflict';
-  changed: boolean;
-  targetState: 'active';
-  requestRef: string;
-  intent: 'recover-started';
-  taskId: string | null;
-  stage: RecoveryStage | null;
-  round: number | null;
-  artifact: string | null;
-  receiptId: string | null;
-  childId: string | null;
-  warning: RecoveryWarning | null;
-  error: Readonly<{ code: string; message: string }> | null;
-}>;
-type LifecycleRecoveryOptions = Readonly<{
-  repoRoot?: string;
-  now?: () => string;
-  orchestration?: Pick<OrchestrationOptions, 'diagnosticLog' | 'now'>;
-  lifecycleStore?: ReturnType<typeof createCodexLifecycleStore>;
-  releaseRecovery?: (childThreadId: string, consumer: string) => boolean;
-  writeTask?: typeof writeTask;
-  verifyRecoveryCommit?: (
-    taskMdPath: string,
-    taskDir: string,
-    taskId: string,
-    request: LifecycleRecoveryRequest,
-    note: RecoveryNote,
-    options: LifecycleRecoveryOptions
-  ) => RecoveryCommitVerification;
-}>;
-
-type RecoveryNote = Readonly<{
-  version: 1;
-  taskId: string;
-  stage: RecoveryStage;
-  round: number;
-  artifact: string;
-  startedAgent: string;
-  receiptId: string;
-  childId: string;
-  stopRevision: number;
-  consumer: string;
-  consumedAt: string;
-  owner: 'terminated';
-  reason: string;
-}>;
-type RecoveryTerminalFacts = Readonly<{
-  note: RecoveryNote;
-  receipt: DelegationReceipt;
-  consumer: string;
-  stored: StoredCodexLifecycle | null;
-}>;
-type RecoveryTerminalFactsResult =
-  | { ok: true; facts: RecoveryTerminalFacts }
-  | { ok: false; code: string; message: string };
-
-const RECOVERY_RELEASE_RETRY_WARNING: RecoveryWarning = Object.freeze({
-  code: 'RECOVERY_RELEASE_RETRY_REQUIRED',
-  message: 'recovery receipt and Activity Log are complete but the protected lifecycle claim could not be released',
-  action: 'retry recover-started with the same selector and reason'
-});
-
-function text(value: unknown): value is string {
-  return typeof value === 'string' && value.length > 0 && value.trim() === value && !/[\r\n]/u.test(value);
-}
-
-function isReleaseRetryWarning(value: unknown): value is RecoveryWarning {
-  return sameRecoveryWarning(value, RECOVERY_RELEASE_RETRY_WARNING);
-}
-
-function timestamp(value: unknown): value is string {
-  return text(value) && Number.isFinite(Date.parse(value));
-}
-
-function recoveryConsumer(taskId: string, receiptId: string): string {
-  return `lifecycle-recovery:${taskId}:${receiptId}`;
-}
-
-function actionPattern(stage: RecoveryStage, round: number): RegExp {
-  const escaped = ACTIONS[stage].replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-  return new RegExp(`^${escaped} \\(Round ${round}(?:, (?:fix for review-code(?:-r[2-9]|-r[1-9]\\d+)?.md|decision II-[1-9]\\d*))?\\)$`, 'u');
-}
-
-function baseStep(step: string): string {
-  return step.replace(/\s*\[(?:started|aborted)\]\s*$/u, '');
-}
-
-function isRecoveryStage(value: unknown): value is RecoveryStage {
-  return (RECOVERY_STAGES as readonly string[]).includes(value as string);
-}
-
-function parseRecoveryNote(note: string): RecoveryNote | null {
-  if (!note.startsWith(RECOVERY_NOTE_PREFIX)) return null;
-  let value: unknown;
-  try { value = JSON.parse(note.slice(RECOVERY_NOTE_PREFIX.length)); }
-  catch { return null; }
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-  const record = value as Record<string, unknown>;
-  if (Object.keys(record).sort().join(',') !== [...RECOVERY_NOTE_KEYS].sort().join(',')) return null;
-  if (
-    record.version !== 1
-    || typeof record.taskId !== 'string' || !TASK_ID_RE.test(record.taskId)
-    || !isRecoveryStage(record.stage)
-    || !Number.isSafeInteger(record.round) || (record.round as number) < 1
-    || !text(record.artifact)
-    || !text(record.startedAgent)
-    || !text(record.receiptId)
-    || !text(record.childId)
-    || !Number.isSafeInteger(record.stopRevision) || (record.stopRevision as number) < 1
-    || !text(record.consumer)
-    || !timestamp(record.consumedAt)
-    || record.owner !== 'terminated'
-    || !text(record.reason)
-  ) return null;
-  const parsedArtifact = parseArtifactName(record.artifact);
-  if (!parsedArtifact || parsedArtifact.family !== record.stage || parsedArtifact.round !== record.round) return null;
-  if (record.consumer !== recoveryConsumer(record.taskId, record.receiptId)) return null;
-  return record as RecoveryNote;
-}
-
-function renderRecoveryNote(note: RecoveryNote): string {
-  return `${RECOVERY_NOTE_PREFIX}${JSON.stringify(note)}`;
-}
-
-function result(
-  request: LifecycleRecoveryRequest,
-  status: LifecycleRecoveryResult['status'],
-  extra: Partial<LifecycleRecoveryResult> = {}
-): LifecycleRecoveryResult {
-  return {
-    status,
-    changed: status === 'applied',
-    targetState: 'active',
-    requestRef: request.taskRef,
-    intent: request.intent,
-    taskId: null,
-    stage: request.stage,
-    round: request.round,
-    artifact: request.artifact,
-    receiptId: null,
-    childId: null,
-    warning: null,
-    error: null,
-    ...extra
-  };
-}
-
-function failure(
-  request: LifecycleRecoveryRequest,
-  status: 'owner-unknown' | 'conflict',
-  code: string,
-  message: string,
-  extra: Partial<LifecycleRecoveryResult> = {}
-): LifecycleRecoveryResult {
-  return result(request, status, { error: { code, message }, ...extra });
-}
-
-function recoveryFailure(
-  request: LifecycleRecoveryRequest,
-  status: 'owner-unknown' | 'conflict',
-  code: string,
-  message: string
-): LifecycleRecoveryResult {
-  return failure(request, status, code, message);
-}
-
-function normalizeRequest(request: LifecycleRecoveryRequest): LifecycleRecoveryRequest | { code: string; message: string } {
-  if (
-    !request || typeof request !== 'object'
-    || request.intent !== 'recover-started'
-    || typeof request.taskRef !== 'string' || !request.taskRef.trim()
-    || typeof request.agent !== 'string'
-    || !isRecoveryStage(request.stage)
-    || !Number.isSafeInteger(request.round) || request.round < 1
-    || typeof request.artifact !== 'string'
-    || typeof request.reason !== 'string' || !request.reason.trim() || /[\r\n]/u.test(request.reason)
-  ) return { code: 'RECOVERY_PAYLOAD_INVALID', message: 'recover-started requires a task, agent, stage, round, artifact, and single-line reason' };
-  const agent = normalizeAgentToken(request.agent);
-  if (!agent) return { code: 'RECOVERY_PAYLOAD_INVALID', message: 'recovery agent is not a recognized agent token' };
-  const expectedArtifact = artifactName(request.stage, request.round);
-  if (request.artifact !== expectedArtifact) {
-    return { code: 'RECOVERY_PAYLOAD_INVALID', message: `artifact must be ${expectedArtifact} for ${request.stage} round ${request.round}` };
-  }
-  return { ...request, agent, reason: request.reason.trim() };
-}
-
-function targetRows(sectionEntries: readonly LogEntry[], stage: RecoveryStage, round: number): {
-  rows: StepRow[];
-  recoveryEntries: LogEntry[];
-} {
-  const pattern = actionPattern(stage, round);
-  const rows = pairEntries([...sectionEntries]).filter((row) => pattern.test(row.step));
-  const recoveryEntries = sectionEntries.filter((entry) => entry.step.endsWith(' [aborted]') && pattern.test(baseStep(entry.step)));
-  return { rows, recoveryEntries };
-}
-
-function validateStopRecord(
-  record: StoredCodexLifecycle,
-  receipt: DelegationReceipt,
-  consumer: string
-): { ok: true; stopRevision: number; consumedAt: string } | { ok: false; code: string; message: string } {
-  const start = record.state.startEvidence;
-  const stop = record.state.stopEvidence;
-  const provenance = receipt.lifecycleProvenance;
-  const host = receipt.hostEvidence;
-  if (
-    receipt.client !== 'codex'
-    || !provenance
-    || host?.kind !== 'codex-lifecycle-v2'
-    || !start
-    || !stop
-    || record.state.status !== 'stop-ready'
-    || stop.terminalStatus !== 'completed'
-    || stop.hookStopObserved !== true
-    || start.childThreadId !== receipt.childId
-    || start.parentThreadId !== receipt.parentId
-    || managedDelegationRole(start.nativeAgent) !== receipt.role
-    || start.hookDefinitionHash !== provenance.hookDefinitionHash
-    || host.hookDefinitionHash !== provenance.hookDefinitionHash
-    || host.capabilitySessionId !== provenance.capabilitySessionId
-    || host.capabilityTurnId !== provenance.capabilityTurnId
-    || host.capabilityToolUseId !== provenance.capabilityToolUseId
-    || host.spawnToolUseId !== start.spawnToolUseId
-    || !host.spawnObservedAt
-    || !record.spawnObservedAt
-    || host.spawnObservedAt !== record.spawnObservedAt
-    || host.controllerInstanceDigest !== provenance.controllerInstanceDigest
-    || host.controlGeneration !== provenance.controlGeneration
-    || typeof host.controllerInstanceDigest !== 'string'
-    || typeof host.controlGeneration !== 'string'
-    || host.startRevision < 1
-    || record.revision <= host.startRevision
-  ) return { ok: false, code: 'RECOVERY_STOP_EVIDENCE_INVALID', message: 'Codex stop evidence does not match the managed activated receipt' };
-  if (record.state.child?.childThreadId !== receipt.childId || record.state.stop?.childThreadId !== receipt.childId) {
-    return { ok: false, code: 'RECOVERY_STOP_EVIDENCE_INVALID', message: 'Codex stop evidence child identity is inconsistent' };
-  }
-  if (record.consumer !== null && record.consumer !== consumer) {
-    return { ok: false, code: 'RECOVERY_CONSUMER_CONFLICT', message: `Codex lifecycle evidence was consumed by '${record.consumer}'` };
-  }
-  if (record.consumer === null) return { ok: true, stopRevision: record.revision, consumedAt: '' };
-  if (receipt.status === 'activated' && record.consumer === consumer && record.consumedAt) {
-    return { ok: true, stopRevision: record.revision, consumedAt: record.consumedAt };
-  }
-  if (
-    record.consumer !== consumer
-    || !record.consumedAt
-    || receipt.hostEvidence?.stopRevision !== record.revision
-    || receipt.hostEvidence.consumer !== consumer
-    || receipt.hostEvidence.consumedAt !== record.consumedAt
-  ) return { ok: false, code: 'RECOVERY_REFERENCE_CONFLICT', message: 'recovery receipt references do not match the protected lifecycle claim' };
-  return { ok: true, stopRevision: record.revision, consumedAt: record.consumedAt };
-}
-
-function readLifecycleStore(
-  options: LifecycleRecoveryOptions,
-  repoRoot: string
-): ReturnType<typeof createCodexLifecycleStore> {
-  if (options.lifecycleStore) return options.lifecycleStore;
-  return createCodexLifecycleStore({
-    root: resolveAgentRuntimeStoreRoot({ repoRoot, store: 'lifecycle' }),
-    cliVersion: 'recovery',
-    now: options.now
-  });
-}
-
-function readStoredEvidence(
-  store: ReturnType<typeof createCodexLifecycleStore>,
-  childId: string
-): StoredCodexLifecycle | { missing: true } | { error: Error } {
-  try {
-    return store.read(childId);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (message.includes('was not found uniquely')) return { missing: true };
-    return { error: error instanceof Error ? error : new Error(message) };
-  }
-}
-
-function taskNote(
-  taskId: string,
-  request: LifecycleRecoveryRequest,
-  receipt: DelegationReceipt,
-  stopRevision: number,
-  consumer: string,
-  consumedAt: string
-): RecoveryNote {
-  return {
-    version: 1,
-    taskId,
-    stage: request.stage,
-    round: request.round,
-    artifact: request.artifact,
-    startedAgent: request.agent,
-    receiptId: receipt.id,
-    childId: receipt.childId!,
-    stopRevision,
-    consumer,
-    consumedAt,
-    owner: 'terminated',
-    reason: request.reason
-  };
-}
-
-function releaseResult(
-  request: LifecycleRecoveryRequest,
-  taskId: string,
-  receipt: DelegationReceipt,
-  released: boolean,
-  previousChange: boolean
-): LifecycleRecoveryResult {
-  if (released) return result(request, 'applied', { taskId, receiptId: receipt.id, childId: receipt.childId });
-  return result(request, 'applied', {
-    changed: previousChange,
-    taskId,
-    receiptId: receipt.id,
-    childId: receipt.childId,
-    warning: RECOVERY_RELEASE_RETRY_WARNING
-  });
-}
-
-function isPostActivationAbortedReceipt(
-  receipt: DelegationReceipt,
-  taskId: string,
-  request: LifecycleRecoveryRequest
-): boolean {
-  return receipt.status === 'aborted'
-    && receipt.activatedAt !== null
-    && receipt.agent === null
-    && receipt.taskId === taskId
-    && receipt.stage === request.stage
-    && receipt.round === request.round
-    && receipt.artifact === request.artifact;
-}
-
-function matchingPostActivationAbortedReceipts(
-  run: OrchestrationRun,
-  taskId: string,
-  request: LifecycleRecoveryRequest
-): DelegationReceipt[] {
-  return run.receipts.filter((receipt) => isPostActivationAbortedReceipt(receipt, taskId, request));
-}
-
-function sameRecoveryNote(left: RecoveryNote, right: RecoveryNote): boolean {
-  return left.version === right.version
-    && left.taskId === right.taskId
-    && left.stage === right.stage
-    && left.round === right.round
-    && left.artifact === right.artifact
-    && left.startedAgent === right.startedAgent
-    && left.receiptId === right.receiptId
-    && left.childId === right.childId
-    && left.stopRevision === right.stopRevision
-    && left.consumer === right.consumer
-    && left.consumedAt === right.consumedAt
-    && left.owner === right.owner
-    && left.reason === right.reason;
-}
-
-function recoveryNoteMatchesRequest(
-  note: RecoveryNote,
-  taskId: string,
-  request: LifecycleRecoveryRequest
-): boolean {
-  return note.taskId === taskId
-    && note.stage === request.stage
-    && note.round === request.round
-    && note.artifact === request.artifact
-    && note.startedAgent === request.agent
-    && note.reason === request.reason;
-}
-
-function recoveryReferencesMatch(
-  receipt: DelegationReceipt,
-  note: RecoveryNote,
-  consumer: string
-): boolean {
-  return receipt.childId === note.childId
-    && note.consumer === consumer
-    && receipt.hostEvidence?.stopRevision === note.stopRevision
-    && receipt.hostEvidence.consumer === consumer
-    && receipt.hostEvidence.consumedAt === note.consumedAt;
-}
-
-function recoveryRunIsStable(run: OrchestrationRun | null): run is OrchestrationRun {
-  return run !== null && run.status === 'running' && run.pendingDelegation === null;
-}
-
-function recoveryTerminalFailureStatus(code: string): 'owner-unknown' | 'conflict' {
-  switch (code) {
-    case 'RECOVERY_LOG_CONFLICT':
-    case 'RECOVERY_NOTE_INVALID':
-    case 'RECOVERY_ORCHESTRATION_INVALID':
-    case 'RECOVERY_RECEIPT_INVALID':
-    case 'RECOVERY_REFERENCE_CONFLICT':
-    case 'RECOVERY_CONSUMER_CONFLICT':
-      return 'conflict';
-    default:
-      return 'owner-unknown';
-  }
-}
-
-function readRecoveryTerminalFacts(
-  section: Readonly<{ entries: readonly LogEntry[] }>,
-  taskId: string,
-  request: LifecycleRecoveryRequest,
-  run: OrchestrationRun | null,
-  store: ReturnType<typeof createCodexLifecycleStore>
-): RecoveryTerminalFactsResult {
-  const targets = targetRows(section.entries, request.stage, request.round);
-  const paired = targets.rows.filter((row) => row.started !== '' && row.done !== '');
-  if (targets.recoveryEntries.length !== 1 || paired.length !== 1
-    || paired[0]!.done !== targets.recoveryEntries[0]!.time) {
-    return { ok: false, code: 'RECOVERY_LOG_CONFLICT', message: 'recovery Activity Log does not contain one completed started/aborted pair' };
-  }
-  const note = parseRecoveryNote(targets.recoveryEntries[0]!.note);
-  if (!note || !recoveryNoteMatchesRequest(note, taskId, request)) {
-    return { ok: false, code: 'RECOVERY_NOTE_INVALID', message: 'recovery Activity Log note does not match the selector' };
-  }
-  if (!recoveryRunIsStable(run)) {
-    return { ok: false, code: 'RECOVERY_ORCHESTRATION_INVALID', message: 'completed recovery state must be running with no pending delegation' };
-  }
-  const receipts = matchingPostActivationAbortedReceipts(run, taskId, request);
-  if (receipts.length !== 1 || receipts[0]!.id !== note.receiptId) {
-    return { ok: false, code: 'RECOVERY_RECEIPT_INVALID', message: 'there is not one matching post-activation aborted receipt' };
-  }
-  const receipt = receipts[0]!;
-  const consumer = recoveryConsumer(taskId, receipt.id);
-  if (!recoveryReferencesMatch(receipt, note, consumer)) {
-    return { ok: false, code: 'RECOVERY_REFERENCE_CONFLICT', message: 'recovery receipt and Activity Log references do not match' };
-  }
-  const stored = readStoredEvidence(store, note.childId);
-  if ('error' in stored) return { ok: false, code: 'RECOVERY_STORE_UNKNOWN', message: stored.error.message };
-  if ('missing' in stored) return { ok: true, facts: { note, receipt, consumer, stored: null } };
-  const evidence = validateStopRecord(stored, receipt, consumer);
-  if (!evidence.ok) return evidence;
-  if (stored.consumer !== consumer || !stored.consumedAt
-    || evidence.stopRevision !== note.stopRevision || evidence.consumedAt !== note.consumedAt) {
-    return { ok: false, code: 'RECOVERY_REFERENCE_CONFLICT', message: 'complete recovery facts do not reference the protected recovery claim' };
-  }
-  return { ok: true, facts: { note, receipt, consumer, stored } };
-}
-
-function verifyRecoveryCommit(
-  taskMdPath: string,
-  taskDir: string,
-  taskId: string,
-  request: LifecycleRecoveryRequest,
-  note: RecoveryNote,
-  options: LifecycleRecoveryOptions
-): RecoveryCommitVerification {
-  try {
-    const content = fs.readFileSync(taskMdPath, 'utf8');
-    parseTypedTaskFrontmatter(content);
-    const section = locateActivityLog(content);
-    if (!section) return { ok: false, message: 'recovery Activity Log cannot be reread uniquely' };
-    const run = readRun(taskDir, options.orchestration);
-    const store = readLifecycleStore(options, options.repoRoot ?? path.resolve(taskDir, '../../../..'));
-    const facts = readRecoveryTerminalFacts(section, taskId, request, run, store);
-    if (!facts.ok) return { ok: false, message: facts.message };
-    if (!sameRecoveryNote(facts.facts.note, note)) {
-      return { ok: false, message: 'recovery Activity Log note changed during commit verification' };
-    }
-    if (!facts.facts.stored) return { ok: false, message: 'protected lifecycle claim disappeared before release' };
-    return { ok: true, receipt: facts.facts.receipt };
-  } catch (error) {
-    return { ok: false, message: error instanceof Error ? error.message : String(error) };
-  }
-}
-
-function recoveryDomainFailure(): Readonly<Record<string, unknown>> {
-  return { consistent: false, recovery: true, targetState: 'active' };
-}
-
-export function readLifecycleRecoveryDomainEvidence(
-  repoRoot: string,
-  requestInput: LifecycleRecoveryRequest,
-  terminalResult: Readonly<{ status: string; changed: boolean | null; targetState: string | null; warning?: unknown | null }>,
-  options: Pick<LifecycleRecoveryOptions, 'lifecycleStore' | 'now'> = {}
-): Readonly<Record<string, unknown>> {
-  const terminalStateValid = terminalResult.status === 'no-op'
-    ? terminalResult.changed === false
-    : terminalResult.status === 'applied'
-      && (terminalResult.changed === true || (terminalResult.changed === false && isReleaseRetryWarning(terminalResult.warning)));
-  const normalized = normalizeRequest(requestInput);
-  if ('code' in normalized || terminalResult.targetState !== 'active'
-    || !terminalStateValid) return recoveryDomainFailure();
-  const request = normalized;
-  const resolved = resolveTaskRef(request.taskRef, { repoRoot });
-  if (!resolved.ok) return recoveryDomainFailure();
-  try {
-    const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
-    parseTypedTaskFrontmatter(content);
-    const section = locateActivityLog(content);
-    if (!section) return recoveryDomainFailure();
-    const run = readRun(resolved.taskDir);
-    const store = readLifecycleStore(options, repoRoot);
-    const facts = readRecoveryTerminalFacts(section, resolved.taskId, request, run, store);
-    if (!facts.ok) return recoveryDomainFailure();
-    if (!facts.facts.stored) return { consistent: true, recovery: true, targetState: 'active', recoveryState: 'released' };
-    if (!isReleaseRetryWarning(terminalResult.warning)) return recoveryDomainFailure();
-    return {
-      consistent: true,
-      recovery: true,
-      targetState: 'active',
-      recoveryState: 'retry-required',
-      warning: terminalResult.warning
-    };
-  } catch {
-    return recoveryDomainFailure();
-  }
-}
-
-function recoverStartedLifecycleUnderLock(
-  requestInput: LifecycleRecoveryRequest,
-  options: LifecycleRecoveryOptions = {}
-): LifecycleRecoveryResult {
-  const normalized = normalizeRequest(requestInput);
-  if ('code' in normalized) return failure(requestInput, 'conflict', normalized.code, normalized.message);
-  const request = normalized;
-  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
-  if (!resolved.ok) return failure(request, 'conflict', resolved.code, resolved.message);
-  const taskId = resolved.taskId;
-  let content: string;
-  try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
-  catch (error) { return failure(request, 'owner-unknown', 'RECOVERY_TASK_READ_FAILED', String(error), { taskId }); }
-  try { parseTypedTaskFrontmatter(content); }
-  catch (error) { return failure(request, 'conflict', 'RECOVERY_TASK_INVALID', error instanceof Error ? error.message : String(error), { taskId }); }
-  const section = locateActivityLog(content);
-  if (!section) return failure(request, 'conflict', 'RECOVERY_LOG_INVALID', 'task has no unique Activity Log section', { taskId });
-  const targets = targetRows(section.entries, request.stage, request.round);
-  const open = targets.rows.filter((row) => row.started !== '' && row.done === '');
-  if (open.length > 1 || targets.recoveryEntries.length > 1) {
-    return failure(request, 'conflict', 'RECOVERY_SELECTOR_AMBIGUOUS', 'recovery selector does not identify one lifecycle attempt', { taskId });
-  }
-  let run: OrchestrationRun | null;
-  try { run = readRun(resolved.taskDir, options.orchestration); }
-  catch (error) { return failure(request, 'owner-unknown', 'RECOVERY_ORCHESTRATION_UNKNOWN', String(error), { taskId }); }
-  if (!run) return failure(request, 'owner-unknown', 'RECOVERY_ORCHESTRATION_MISSING', 'no orchestration run exists for the open lifecycle execution', { taskId });
-
-  if (open.length === 0) {
-    if (targets.recoveryEntries.length !== 1) {
-      return failure(request, 'conflict', 'RECOVERY_TERMINAL_MISSING', 'there is no matching open or structured recovery lifecycle row', { taskId });
-    }
-    const store = readLifecycleStore(options, resolved.repoRoot);
-    const facts = readRecoveryTerminalFacts(section, taskId, request, run, store);
-    if (!facts.ok) {
-      return failure(request, recoveryTerminalFailureStatus(facts.code), facts.code, facts.message, { taskId });
-    }
-    const { note, receipt, consumer, stored } = facts.facts;
-    if (!stored) return result(request, 'no-op', { taskId, receiptId: receipt.id, childId: receipt.childId });
-    let released = false;
-    try { released = (options.releaseRecovery ?? store.releaseRecovery)(note.childId, consumer); }
-    catch (error) {
-      return releaseResult(request, taskId, receipt, false, false);
-    }
-    return releaseResult(request, taskId, receipt, released, false);
-  }
-
-  const started = open[0]!;
-  if (normalizeAgentToken(started.agent) !== request.agent || started.note !== 'started') {
-    return failure(request, 'conflict', 'RECOVERY_SELECTOR_MISMATCH', 'open started lifecycle row does not match the recovery selector', { taskId });
-  }
-  if (targets.recoveryEntries.length > 0) {
-    return failure(request, 'conflict', 'RECOVERY_LOG_CONFLICT', 'open lifecycle execution already has a recovery terminal row', { taskId });
-  }
-  const pending = run.pendingDelegation;
-  const recovered = run.receipts.filter((candidate) => isPostActivationAbortedReceipt(candidate, taskId, request));
-  if (pending && recovered.length > 0) {
-    return failure(request, 'conflict', 'RECOVERY_RECEIPT_INVALID', 'open lifecycle execution has both a pending and an aborted matching delegation', { taskId });
-  }
-  const receipt = pending ?? (recovered.length === 1 ? recovered[0]! : null);
-  if (!receipt || (pending && (receipt.status !== 'activated' || receipt.client !== 'codex')) || (!pending && receipt.status !== 'aborted')) {
-    return failure(request, 'owner-unknown', 'RECOVERY_DELEGATION_UNAVAILABLE', 'open lifecycle execution is not backed by one matching activated Codex delegation', { taskId });
-  }
-  if (normalizeAgentToken(started.agent) !== normalizeAgentToken(receipt.client)) {
-    return failure(request, 'conflict', 'RECOVERY_SELECTOR_MISMATCH', 'started agent does not match the delegation client', { taskId, receiptId: receipt.id, childId: receipt.childId });
-  }
-  const consumer = recoveryConsumer(taskId, receipt.id);
-  const store = readLifecycleStore(options, resolved.repoRoot);
-  const stored = readStoredEvidence(store, receipt.childId ?? '');
-  if ('error' in stored) return failure(request, 'owner-unknown', 'RECOVERY_STORE_UNKNOWN', stored.error.message, { taskId, receiptId: receipt.id, childId: receipt.childId });
-  if ('missing' in stored) return failure(request, 'owner-unknown', 'RECOVERY_STOP_EVIDENCE_MISSING', 'matching Codex lifecycle stop evidence is missing', { taskId, receiptId: receipt.id, childId: receipt.childId });
-  const evidence = validateStopRecord(stored, receipt, consumer);
-  if (!evidence.ok) return failure(request, evidence.code === 'RECOVERY_CONSUMER_CONFLICT' ? 'conflict' : 'owner-unknown', evidence.code, evidence.message, { taskId, receiptId: receipt.id, childId: receipt.childId });
-  let claimed = stored;
-  if (stored.consumer === null) {
-    try { claimed = store.claimRecovery(receipt.childId!, taskId, receipt.id, receipt.hostEvidence?.hookDefinitionHash); }
-    catch (error) { return failure(request, 'owner-unknown', 'RECOVERY_CLAIM_FAILED', error instanceof Error ? error.message : String(error), { taskId, receiptId: receipt.id, childId: receipt.childId }); }
-  }
-  const stopRevision = claimed.revision;
-  const consumedAt = claimed.consumedAt;
-  if (!consumedAt) return failure(request, 'owner-unknown', 'RECOVERY_CLAIM_INVALID', 'protected lifecycle claim has no consumed timestamp', { taskId, receiptId: receipt.id, childId: receipt.childId });
-  if (receipt.status === 'activated') {
-    const recoveredRun = recoverActivatedOrchestrationDelegationUnderLock(taskId, {
-      receiptId: receipt.id,
-      stage: request.stage,
-      round: request.round,
-      artifact: request.artifact,
-      startedAgent: request.agent,
-      childId: receipt.childId!,
-      stopRevision,
-      consumer,
-      consumedAt
-    }, { ...options.orchestration, repoRoot: resolved.repoRoot, now: options.now });
-    if (recoveredRun.status === 'failed' || !recoveredRun.run) {
-      return failure(request, 'owner-unknown', recoveredRun.error?.code ?? 'RECOVERY_ORCHESTRATION_FAILED', recoveredRun.error?.message ?? 'orchestration recovery failed', { taskId, receiptId: receipt.id, childId: receipt.childId });
-    }
-  }
-  const note = taskNote(taskId, request, receipt, stopRevision, consumer, consumedAt);
-  const metadata = captureTaskWriteMetadata();
-  const updatedBody = `${section.body ? `${section.body}\n` : ''}- ${metadata.timestamp} — **${baseStep(started.step)} [aborted]** by ${request.agent} — ${renderRecoveryNote(note)}`;
-  const written = (options.writeTask ?? writeTask)({
-    taskRef: taskId,
-    expectedState: 'active',
-    mutations: [{ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body: updatedBody }]
-  }, { repoRoot: resolved.repoRoot, metadataProvider: () => metadata });
-  if (written.status === 'failed') {
-    return failure(request, 'owner-unknown', 'RECOVERY_LOG_WRITE_FAILED', written.error.message, { taskId, receiptId: receipt.id, childId: receipt.childId });
-  }
-  const verified = (options.verifyRecoveryCommit ?? verifyRecoveryCommit)(resolved.taskMdPath, resolved.taskDir, taskId, request, note, options);
-  if (!verified.ok) {
-    return failure(request, 'owner-unknown', 'RECOVERY_COMMIT_VERIFY_FAILED', verified.message, { taskId, receiptId: receipt.id, childId: receipt.childId });
-  }
-  let released = false;
-  try { released = (options.releaseRecovery ?? store.releaseRecovery)(receipt.childId!, consumer); }
-  catch { released = false; }
-  if (!released) {
-    return releaseResult(request, taskId, receipt, false, true);
-  }
-  return result(request, 'applied', { taskId, receiptId: receipt.id, childId: receipt.childId });
-}
-
-export {
-  RECOVERY_NOTE_PREFIX,
-  parseRecoveryNote,
-  recoveryFailure,
-  recoveryConsumer,
-  recoverStartedLifecycleUnderLock,
-  renderRecoveryNote
-};
-export type { LifecycleRecoveryOptions, LifecycleRecoveryRequest, LifecycleRecoveryResult, RecoveryNote, RecoveryStage };