@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/dist/lib/task/control-authority.js

@@ -1,4 +1,6 @@
 import path from 'node:path';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
 import { normalizeAgentToken } from '../agent-clients/tokens.js';
 import { isAgentClientId } from '../agent-clients/types.js';
 import { consumeHumanOverride, failureId, overrideDryRunConflict } from './human-override.js';
@@ -6,9 +8,358 @@ import { activateMatchingOrchestrationDelegation, activateOrchestrationDelegatio
 import { prepareCodexOrchestrationDelegation } from './codex-orchestration.js';
 import { applyTaskFinalization } from './finalization.js';
 import { applyTaskLifecycle, taskLifecycleFailure } from './lifecycle.js';
+import { recoverStartedLifecycleUnderLock, recoveryFailure } from './lifecycle-recovery.js';
+import { locateActivityLog } from './activity-log.js';
 import { resolveTaskRef, TASK_ID_RE } from './resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 import { verifyTaskEvent } from './verification.js';
+import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.js';
+import { findArtifactRecoveryIntentsByOperation, writeArtifactRecoveryIntent } from './artifact-repair-intent.js';
+import { computeLifecycleBuildIdentity, verifyLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.js';
+const lifecycleAuthorityPhases = [
+    'orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'
+];
+const lifecycleAuthorityFamilies = ['analysis', 'plan', 'code'];
+const lifecycleAuthorityArtifact = /^(?:analysis|plan|code)(?:-r[1-9]\d*)?\.md$/u;
+const lifecycleAuthorityDigest = (value) => crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+const lifecycleAuthorityBuildDigest = (value) => lifecycleAuthorityDigest(JSON.stringify(value));
+export function lifecycleRecoveryAttestationDigest(value) {
+    return lifecycleAuthorityDigest(JSON.stringify(value));
+}
+function authorityExactKeys(value, keys) {
+    return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+export function validateLifecycleAuthorityRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('LIFECYCLE_AUTHORITY_REQUEST_INVALID');
+    const request = value;
+    if (!authorityExactKeys(request, [
+        'artifact', 'authorityRef', 'expectedBuildIdentityDigest', 'expectedControlGeneration',
+        'expectedControllerInstanceDigest', 'expectedHookDefinitionHash', 'family', 'lifecycleRequestId',
+        'operationId', 'phase', 'requestId', 'round', 'taskId', 'version'
+    ])
+        || request.version !== 1
+        || typeof request.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(request.requestId)
+        || typeof request.operationId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(request.operationId)
+        || !lifecycleAuthorityPhases.includes(request.phase)
+        || typeof request.taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/u.test(request.taskId)
+        || !lifecycleAuthorityFamilies.includes(request.family)
+        || typeof request.artifact !== 'string' || !lifecycleAuthorityArtifact.test(request.artifact)
+        || !Number.isSafeInteger(request.round) || request.round < 1
+        || typeof request.lifecycleRequestId !== 'string' || !request.lifecycleRequestId || /[\r\n]/u.test(request.lifecycleRequestId)
+        || typeof request.authorityRef !== 'string' || !request.authorityRef || /[\r\n]/u.test(request.authorityRef)
+        || typeof request.expectedControlGeneration !== 'string' || !request.expectedControlGeneration
+        || typeof request.expectedControllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(request.expectedControllerInstanceDigest)
+        || typeof request.expectedBuildIdentityDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(request.expectedBuildIdentityDigest)
+        || typeof request.expectedHookDefinitionHash !== 'string' || !/^[a-f0-9]{64}$/u.test(request.expectedHookDefinitionHash)) {
+        throw new Error('LIFECYCLE_AUTHORITY_REQUEST_INVALID');
+    }
+    const expectedArtifactFamily = request.artifact;
+    if (!expectedArtifactFamily.startsWith(request.family))
+        throw new Error('LIFECYCLE_AUTHORITY_REQUEST_INVALID');
+    return request;
+}
+export function validateLifecycleRecoveryAttestation(value, now = Date.now()) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('LIFECYCLE_AUTHORITY_ATTESTATION_INVALID');
+    const attestation = value;
+    if (!authorityExactKeys(attestation, [
+        'artifact', 'attestationId', 'authorityRefDigest', 'buildIdentityDigest', 'controlGeneration',
+        'controllerInstanceDigest', 'expiresAt', 'family', 'hookDefinitionHash', 'issuedAt',
+        'lifecycleRequestId', 'operationId', 'phase', 'requestId', 'round', 'sessionId',
+        'taskId', 'toolUseId', 'turnId', 'version'
+    ])
+        || attestation.version !== 1
+        || typeof attestation.attestationId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(attestation.attestationId)
+        || typeof attestation.authorityRefDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.authorityRefDigest)
+        || typeof attestation.operationId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(attestation.operationId)
+        || !lifecycleAuthorityPhases.includes(attestation.phase)
+        || typeof attestation.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(attestation.requestId)
+        || typeof attestation.lifecycleRequestId !== 'string' || !attestation.lifecycleRequestId
+        || typeof attestation.taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/u.test(attestation.taskId)
+        || !lifecycleAuthorityFamilies.includes(attestation.family)
+        || typeof attestation.artifact !== 'string' || !lifecycleAuthorityArtifact.test(attestation.artifact)
+        || !Number.isSafeInteger(attestation.round) || attestation.round < 1
+        || typeof attestation.controlGeneration !== 'string' || !attestation.controlGeneration
+        || typeof attestation.controllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.controllerInstanceDigest)
+        || typeof attestation.sessionId !== 'string' || !attestation.sessionId
+        || typeof attestation.turnId !== 'string' || !attestation.turnId
+        || typeof attestation.toolUseId !== 'string' || !attestation.toolUseId
+        || typeof attestation.buildIdentityDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.buildIdentityDigest)
+        || typeof attestation.hookDefinitionHash !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.hookDefinitionHash)
+        || !Number.isSafeInteger(attestation.issuedAt) || !Number.isSafeInteger(attestation.expiresAt)
+        || attestation.expiresAt <= attestation.issuedAt
+        || attestation.expiresAt <= now) {
+        throw new Error('LIFECYCLE_AUTHORITY_ATTESTATION_INVALID');
+    }
+    return attestation;
+}
+const authorityOperationMap = new WeakMap();
+const authorityRecords = new Map();
+const consumedAuthorityPhases = new Set();
+export function issueLifecycleRecoveryAttestation(input, options = {}) {
+    let request;
+    try {
+        request = validateLifecycleAuthorityRequest(input);
+    }
+    catch (error) {
+        return { version: 1, requestId: String(input?.requestId ?? ''), operationId: String(input?.operationId ?? ''), phase: input?.phase ?? 'artifact.finalize-local', status: 'rejected', attestation: null, error: { code: 'LIFECYCLE_AUTHORITY_REQUEST_INVALID', message: error instanceof Error ? error.message : String(error) } };
+    }
+    const binding = options.controllerBinding ?? null;
+    if (!binding)
+        return authorityRejected(request, 'LOCAL_EXECUTION_AUTHORITY_UNAVAILABLE', 'current controller authority is unavailable');
+    if (binding.controlGeneration !== request.expectedControlGeneration
+        || binding.instanceDigest !== request.expectedControllerInstanceDigest) {
+        return authorityRejected(request, 'LIFECYCLE_AUTHORITY_CONTROLLER_MISMATCH', 'current controller binding does not match the request');
+    }
+    const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(process.cwd());
+    if (lifecycleAuthorityBuildDigest(buildIdentity) !== request.expectedBuildIdentityDigest) {
+        return authorityRejected(request, 'LIFECYCLE_AUTHORITY_BUILD_MISMATCH', 'current lifecycle build does not match the request');
+    }
+    const store = options.capabilityStore ?? createCodexCapabilityStore();
+    const registry = options.operationAttestations ?? authorityOperationMap.get(store) ?? new Map();
+    authorityOperationMap.set(store, registry);
+    const key = `${request.requestId}\0${request.operationId}\0${request.phase}`;
+    const prior = registry.get(key);
+    if (prior)
+        return { version: 1, requestId: request.requestId, operationId: request.operationId, phase: request.phase, status: 'already-completed', attestation: prior, error: null };
+    try {
+        const expected = {
+            taskId: request.taskId,
+            hookDefinitionHash: request.expectedHookDefinitionHash,
+            buildIdentity,
+            controller: binding
+        };
+        const record = store.reserveReference(request.authorityRef, request.operationId, expected);
+        if (!record.sessionId || !record.turnId || !record.toolUseId)
+            throw new Error('CODEX_CAPABILITY_IDENTITY_INVALID: capability hook attestation is incomplete');
+        const now = (options.now ?? Date.now)();
+        const attestation = validateLifecycleRecoveryAttestation({
+            version: 1,
+            attestationId: crypto.randomUUID(),
+            authorityRefDigest: lifecycleAuthorityDigest(request.authorityRef),
+            operationId: request.operationId,
+            phase: request.phase,
+            requestId: request.requestId,
+            lifecycleRequestId: request.lifecycleRequestId,
+            taskId: request.taskId,
+            family: request.family,
+            artifact: request.artifact,
+            round: request.round,
+            controlGeneration: binding.controlGeneration,
+            controllerInstanceDigest: binding.instanceDigest,
+            sessionId: record.sessionId,
+            turnId: record.turnId,
+            toolUseId: record.toolUseId,
+            buildIdentityDigest: lifecycleAuthorityBuildDigest(buildIdentity),
+            hookDefinitionHash: request.expectedHookDefinitionHash,
+            issuedAt: now,
+            expiresAt: Math.min(record.expiresAt, now + 30_000)
+        }, now);
+        store.reserveRecoveryPhase(request.authorityRef, request.operationId, request.phase, request.requestId, expected);
+        registry.set(key, attestation);
+        authorityRecords.set(attestation.attestationId, { store, capabilityRef: request.authorityRef, expected });
+        return { version: 1, requestId: request.requestId, operationId: request.operationId, phase: request.phase, status: 'issued', attestation, error: null };
+    }
+    catch (error) {
+        return authorityRejected(request, error instanceof Error && error.name.startsWith('CODEX_') ? error.name : 'LIFECYCLE_AUTHORITY_REJECTED', error instanceof Error ? error.message : String(error));
+    }
+}
+export function consumeLifecycleRecoveryAttestation(value, now = Date.now()) {
+    const attestation = validateLifecycleRecoveryAttestation(value, now);
+    if (consumedAuthorityPhases.has(attestation.attestationId))
+        return;
+    const record = authorityRecords.get(attestation.attestationId);
+    if (!record)
+        throw new Error('LIFECYCLE_AUTHORITY_ATTESTATION_UNKNOWN');
+    record.store.consumeRecoveryPhase(record.capabilityRef, attestation.operationId, attestation.phase, attestation.requestId, record.expected);
+    if (attestation.phase === 'task-event.completed') {
+        record.store.consumeReference(record.capabilityRef, attestation.operationId, record.expected);
+    }
+    consumedAuthorityPhases.add(attestation.attestationId);
+}
+export function queryLifecycleRecoveryOperation(operationId, options = {}) {
+    if (!/^[a-f0-9-]{16,64}$/u.test(operationId)) {
+        throw new Error('LIFECYCLE_RECOVERY_OPERATION_INVALID');
+    }
+    const store = options.capabilityStore ?? createCodexCapabilityStore();
+    const registry = authorityOperationMap.get(store);
+    const known = [...(registry?.values() ?? [])].filter((value) => value.operationId === operationId);
+    const intents = options.repoRoot ? findArtifactRecoveryIntentsByOperation(options.repoRoot, operationId) : [];
+    const capabilities = store.findByRecoveryOperation(operationId);
+    const phaseMap = new Map();
+    for (const capability of capabilities) {
+        for (const phase of capability.recoveryPhases) {
+            phaseMap.set(`${phase.phase}\0${phase.requestId}`, {
+                phase: phase.phase,
+                requestId: phase.requestId,
+                attestationId: null,
+                state: phase.state === 'consumed' ? 'consumed' : 'observed'
+            });
+        }
+    }
+    for (const attestation of known) {
+        const key = `${attestation.phase}\0${attestation.requestId}`;
+        const durable = phaseMap.get(key);
+        phaseMap.set(key, {
+            phase: attestation.phase,
+            requestId: attestation.requestId,
+            attestationId: attestation.attestationId,
+            state: durable?.state === 'consumed' || consumedAuthorityPhases.has(attestation.attestationId)
+                ? 'consumed' : 'issued'
+        });
+    }
+    for (const intent of intents) {
+        if (!intent.phase)
+            continue;
+        const key = `${intent.phase}\0${intent.requestId}`;
+        if (phaseMap.has(key))
+            continue;
+        phaseMap.set(key, {
+            phase: intent.phase,
+            requestId: intent.requestId,
+            attestationId: null,
+            state: intent.state === 'consumed' ? 'consumed' : 'observed'
+        });
+    }
+    const capabilityState = capabilities.some((record) => record.recoveryState === 'consumed')
+        ? 'consumed'
+        : capabilities.some((record) => record.recoveryState === 'reserved') ? 'reserved' : 'unknown';
+    const committed = capabilityState === 'consumed' || intents.some((intent) => intent.state === 'consumed');
+    return {
+        version: 1,
+        operationId,
+        status: committed ? 'committed' : capabilityState === 'reserved' || phaseMap.size > 0 ? 'in-progress' : 'unknown',
+        capabilityState,
+        phases: Object.freeze([...phaseMap.values()])
+    };
+}
+function lifecycleRecoveryCompensationError(code, message) {
+    const error = new Error(`${code}: ${message}`);
+    error.name = code;
+    return error;
+}
+function lifecycleRecoveryEventCommitted(selector, repoRoot) {
+    const resolved = resolveTaskRef(selector.taskId, { repoRoot });
+    if (!resolved.ok || resolved.taskId !== selector.taskId)
+        return false;
+    let content;
+    try {
+        content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const section = locateActivityLog(content);
+    if (!section)
+        return false;
+    const labels = { analysis: 'Analyze Task', plan: 'Plan Task', code: 'Code Task' };
+    const prefix = `${labels[selector.family]} (Round ${selector.round}`;
+    return section.entries.some((entry) => {
+        if (entry.step.endsWith(' [started]') || !entry.step.startsWith(prefix))
+            return false;
+        const delimiter = entry.step[prefix.length];
+        return (delimiter === ',' || delimiter === ')') && entry.note.endsWith(`→ ${selector.artifact}`);
+    });
+}
+function lifecycleRecoveryIntentMatches(intent, selector) {
+    return intent.taskId === selector.taskId
+        && intent.family === selector.family
+        && intent.artifact === selector.artifact
+        && (intent.state === 'commit-started' || intent.state === 'consumed');
+}
+/**
+ * Completes only the durable tail of a committed task event after a process
+ * restart. The task event itself is the commit boundary and is never replayed.
+ */
+export function recoverLifecycleRecoveryOperation(input, options) {
+    const selector = validateLifecycleAuthorityRequest(input);
+    if (selector.phase !== 'task-event.completed') {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_PHASE_UNSUPPORTED', 'only task-event.completed supports durable compensation');
+    }
+    const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(options.repoRoot);
+    if (selector.expectedBuildIdentityDigest !== lifecycleAuthorityBuildDigest(buildIdentity)) {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_AUTHORITY_BUILD_MISMATCH', 'current lifecycle build does not match the recovery request');
+    }
+    if (selector.expectedControlGeneration !== options.controllerBinding.controlGeneration
+        || selector.expectedControllerInstanceDigest !== options.controllerBinding.instanceDigest) {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_AUTHORITY_CONTROLLER_MISMATCH', 'current controller binding does not match the recovery request');
+    }
+    const store = options.capabilityStore ?? createCodexCapabilityStore();
+    const expected = {
+        taskId: selector.taskId,
+        hookDefinitionHash: selector.expectedHookDefinitionHash,
+        buildIdentity,
+        controller: options.controllerBinding
+    };
+    const capabilities = store.findByRecoveryOperation(selector.operationId);
+    if (capabilities.length !== 1 || capabilities[0].capabilityRefDigest !== lifecycleAuthorityDigest(selector.authorityRef)) {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_PROVENANCE_INVALID', 'durable capability provenance does not identify this operation');
+    }
+    const capability = capabilities[0];
+    const build = verifyLifecycleBuildIdentity(capability.buildIdentity, buildIdentity);
+    const expiredReserved = capability.status === 'expired' && capability.recoveryState === 'reserved';
+    if (!build.ok
+        || capability.taskId !== selector.taskId
+        || capability.hookDefinitionHash !== selector.expectedHookDefinitionHash
+        || capability.controller?.controlGeneration !== options.controllerBinding.controlGeneration
+        || capability.controller?.instanceDigest !== options.controllerBinding.instanceDigest
+        || capability.recoveryState === 'unreserved'
+        || capability.recoveryOperationId !== selector.operationId
+        || (!['attested', 'consumed'].includes(capability.status) && !expiredReserved)) {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_PROVENANCE_INVALID', 'durable capability provenance does not match the recovery request');
+    }
+    const phase = capability.recoveryPhases.find((entry) => entry.phase === selector.phase);
+    if (!phase) {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_PHASE_MISSING', 'durable task completion phase is missing');
+    }
+    const intents = findArtifactRecoveryIntentsByOperation(options.repoRoot, selector.operationId)
+        .filter((intent) => intent.taskId === selector.taskId
+        && intent.family === selector.family
+        && intent.artifact === selector.artifact);
+    if (intents.length !== 1) {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_INTENT_INVALID', 'durable artifact recovery intent does not identify this task event');
+    }
+    const intent = intents[0];
+    if (!lifecycleRecoveryIntentMatches(intent, selector)
+        || intent.phase !== selector.phase
+        || intent.requestId !== selector.lifecycleRequestId
+        || intent.authorityDigest === null) {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_INTENT_INVALID', 'durable artifact recovery intent does not match the recovery request');
+    }
+    if (!lifecycleRecoveryEventCommitted(selector, options.repoRoot)) {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_COMMIT_UNCONFIRMED', 'task completion is not durably present; compensation is not allowed');
+    }
+    if (capability.recoveryState === 'reserved') {
+        if (phase.state === 'issued') {
+            store.consumeRecoveryPhase(selector.authorityRef, selector.operationId, selector.phase, phase.requestId, expected, { allowExpiredReserved: true });
+        }
+        store.consumeReference(selector.authorityRef, selector.operationId, expected, { allowExpiredReserved: true });
+    }
+    else if (phase.state !== 'consumed') {
+        throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_STATE_INVALID', 'consumed capability has an unconsumed completion phase');
+    }
+    if (intent.state !== 'consumed') {
+        writeArtifactRecoveryIntent(options.repoRoot, {
+            ...intent,
+            state: 'consumed',
+            updatedAt: (options.now ?? Date.now)()
+        }, { expected: intent });
+    }
+    return queryLifecycleRecoveryOperation(selector.operationId, { repoRoot: options.repoRoot, capabilityStore: store });
+}
+function authorityRejected(request, code, message) {
+    return { version: 1, requestId: request.requestId, operationId: request.operationId, phase: request.phase, status: 'rejected', attestation: null, error: { code, message } };
+}
+export function taskControlOperationKey(operation) {
+    if (operation.family === 'task-finalization')
+        return 'complete';
+    if (operation.family === 'task-lifecycle')
+        return operation.request.intent;
+    return operation.intent === 'route'
+        ? operation.input && operation.input.completed === true ? 'route.clean-completion' : 'route.read'
+        : operation.intent;
+}
 function invalidContext(message) {
     throw new Error(`TASK_CONTROL_CONTEXT_INVALID: ${message}`);
 }
@@ -31,7 +382,11 @@ export function createDirectHostExecutionContext(params) {
         mode: 'direct-host',
         repoRoot: absolute('repoRoot', params.repoRoot),
         ...(params.runtimeDir === undefined ? {} : { runtimeDir: absolute('runtimeDir', params.runtimeDir) }),
-        ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) })
+        ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) }),
+        ...(params.lifecycleRecoveryAttestation === undefined ? {} : {
+            lifecycleRecoveryAttestation: params.lifecycleRecoveryAttestation === null
+                ? null : validateLifecycleRecoveryAttestation(params.lifecycleRecoveryAttestation)
+        })
     };
 }
 export function createSandboxExecutorExecutionContext(params) {
@@ -53,7 +408,11 @@ export function createSandboxExecutorExecutionContext(params) {
         manifestPath: absolute('manifestPath', params.manifestPath),
         requestId: params.requestId,
         ...(params.diagnosticLog === undefined ? {} : { diagnosticLog: params.diagnosticLog }),
-        ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) })
+        ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) }),
+        ...(params.lifecycleRecoveryAttestation === undefined ? {} : {
+            lifecycleRecoveryAttestation: params.lifecycleRecoveryAttestation === null
+                ? null : validateLifecycleRecoveryAttestation(params.lifecycleRecoveryAttestation)
+        })
     };
 }
 export function assertTaskControlExecutionContext(context) {
@@ -64,6 +423,8 @@ export function assertTaskControlExecutionContext(context) {
         if (context.runtimeDir !== undefined)
             absolute('runtimeDir', context.runtimeDir);
         binding(context.controllerBinding);
+        if (context.lifecycleRecoveryAttestation)
+            validateLifecycleRecoveryAttestation(context.lifecycleRecoveryAttestation);
         return;
     }
     if (context.mode !== 'task-bound-sandbox' || !/^TASK-\d{8}-\d{6}$/u.test(context.taskId)
@@ -78,6 +439,8 @@ export function assertTaskControlExecutionContext(context) {
         invalidContext('runtimeDir is not bound to the manifest control root');
     }
     binding(context.controllerBinding);
+    if (context.lifecycleRecoveryAttestation)
+        validateLifecycleRecoveryAttestation(context.lifecycleRecoveryAttestation);
 }
 function operationTaskId(context, taskRef) {
     if (context.source === 'sandbox-executor' && taskRef !== context.taskId) {
@@ -111,6 +474,9 @@ async function applyLifecycleWithAuthority(context, request) {
         return taskLifecycleFailure(request, { code: 'LIFECYCLE_PAYLOAD_INVALID', message: conflict.message });
     }
     const execute = async () => {
+        if (request.intent === 'recover-started') {
+            return recoverStartedLifecycleUnderLock(request, { repoRoot: context.repoRoot });
+        }
         const lifecycleResult = applyTaskLifecycle(request, { repoRoot: context.repoRoot });
         if (lifecycleResult.status !== 'failed' || !request.overrideTicket)
             return lifecycleResult;
@@ -144,6 +510,9 @@ async function applyLifecycleWithAuthority(context, request) {
     catch (error) {
         if (!(error instanceof TaskExecutionLockError))
             throw error;
+        if (request.intent === 'recover-started') {
+            return recoveryFailure(request, 'owner-unknown', error.code, error.message);
+        }
         return taskLifecycleFailure(request, { code: error.code, message: error.message }, taskId);
     }
 }
@@ -166,12 +535,16 @@ function orchestration(context, operation) {
                 client: input.client,
                 requestedModel: input.requestedModel,
                 requestedReasoningEffort: input.requestedReasoningEffort,
-                ...(input.capabilityToken === undefined ? {} : { capabilityToken: input.capabilityToken })
+                ...(input.capabilityRef === undefined ? {} : { capabilityRef: input.capabilityRef }),
+                ...(context.lifecycleRecoveryAttestation === undefined
+                    ? {}
+                    : { lifecycleRecoveryAttestation: context.lifecycleRecoveryAttestation })
             };
             if (prepareInput.client === 'codex') {
                 return prepareCodexOrchestrationDelegation(operation.taskRef, prepareInput, {
                     repoRoot: context.repoRoot,
                     orchestrationOptions: options,
+                    deferLifecycleRecoveryConsumption: context.source === 'sandbox-executor',
                     ...(context.controllerBinding ? { controllerBinding: context.controllerBinding } : {})
                 });
             }
@@ -250,13 +623,13 @@ function operationInvalid(message) {
 }
 const LIFECYCLE_FLAGS = new Set([
     '--agent', '--reason', '--unblock-condition', '--note', '--alert-number', '--staging-dir', '--issue-number',
-    '--override-ticket', '--override-target', '--override-scope', '--dry-run'
+    '--stage', '--round', '--artifact', '--override-ticket', '--override-target', '--override-scope', '--dry-run'
 ]);
 const FINALIZATION_FLAGS = new Set(['--agent']);
 const ORCHESTRATION_FLAGS = new Set([
     '--agent', '--max-steps', '--executor-model', '--executor-reasoning-effort', '--reviewer-model',
     '--reviewer-reasoning-effort', '--client', '--requested-model', '--requested-reasoning-effort',
-    '--capability-token', '--parent-id', '--before-fingerprint', '--stage', '--round', '--artifact', '--role',
+    '--capability-ref', '--parent-id', '--before-fingerprint', '--stage', '--round', '--artifact', '--role',
     '--native-agent', '--child-id', '--spawn-mode', '--actual-model', '--actual-reasoning-effort',
     '--model-fallback-reason', '--reasoning-effort-fallback-reason', '--exit-code', '--after-fingerprint',
     '--changed-paths', '--code', '--message', '--recoverable', '--git-worktree-root'
@@ -326,8 +699,32 @@ export function parseTaskControlOperation(family, args) {
             ...(value(values, '--override-scope') ? { overrideScope: value(values, '--override-scope') } : {}),
             ...(value(values, '--alert-number') ? { alertNumber: Number(value(values, '--alert-number')) } : {}),
             ...(value(values, '--issue-number') ? { issueNumber: Number(value(values, '--issue-number')) } : {}),
+            ...(value(values, '--stage') ? { stage: value(values, '--stage') } : {}),
+            ...(value(values, '--round') ? { round: Number(value(values, '--round')) } : {}),
+            ...(value(values, '--artifact') ? { artifact: value(values, '--artifact') } : {}),
             ...(values['--dry-run'] === true ? { dryRun: true } : {})
         };
+        if (intent === 'recover-started') {
+            const recoveryFlags = new Set(['--agent', '--stage', '--round', '--artifact', '--reason']);
+            for (const flag of Object.keys(values)) {
+                if (!recoveryFlags.has(flag))
+                    operationInvalid(`option '${flag}' is not supported for recover-started`);
+            }
+            required(values, ['--stage', '--round', '--artifact', '--reason']);
+            const stage = value(values, '--stage');
+            if (!['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(stage ?? '')) {
+                operationInvalid('--stage must be a supported lifecycle stage');
+            }
+            const round = Number(value(values, '--round'));
+            if (!Number.isSafeInteger(round) || round < 1)
+                operationInvalid('--round must be a positive integer');
+            if (value(values, '--reason').includes('\n') || value(values, '--reason').includes('\r')) {
+                operationInvalid('--reason must be a single line');
+            }
+        }
+        else if (values['--stage'] !== undefined || values['--round'] !== undefined || values['--artifact'] !== undefined) {
+            operationInvalid('--stage, --round, and --artifact are only supported for recover-started');
+        }
         return { family, request: input };
     }
     const values = parseValues(args, 2, ORCHESTRATION_FLAGS);
@@ -372,7 +769,7 @@ export function parseTaskControlOperation(family, args) {
     if (parsedIntent === 'prepare') {
         input.requestedModel = value(values, '--requested-model');
         input.requestedReasoningEffort = value(values, '--requested-reasoning-effort');
-        input.capabilityToken = value(values, '--capability-token');
+        input.capabilityRef = value(values, '--capability-ref');
     }
     if (parsedIntent === 'await-activation') {
         required(values, ['--stage', '--round', '--artifact', '--role']);

package/dist/lib/task/control-recovery.js

@@ -0,0 +1,140 @@
+import { createHash } from 'node:crypto';
+import { isCompletionEvidence } from './orchestration.js';
+import { TASK_WORKFLOW_OPERATIONS } from './workflow-command.js';
+import { sameRecoveryWarning } from './recovery-warning.js';
+/** Normalize the command result once at the control transport boundary. */
+export function parseControlOutput(output) {
+    if (output === null)
+        return null;
+    try {
+        const value = JSON.parse(output);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return null;
+        return value.result && typeof value.result === 'object' && !Array.isArray(value.result) ? value.result : value;
+    }
+    catch {
+        return null;
+    }
+}
+export const SANDBOX_CONTROL_REQUIRED_COMPLETION_PHASES = Object.freeze([
+    'completed', 'evidence-written', 'publish-authorized'
+]);
+const LIFECYCLE_INTENTS = ['block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore', 'recover-started'];
+const ORCHESTRATION_INTENTS = [
+    'begin-or-resume', 'route.read', 'route.clean-completion', 'status', 'prepare', 'dispatch',
+    'await-activation', 'recover-prepared', 'hook-start', 'hook-stop', 'advance', 'pause'
+];
+export const SANDBOX_CONTROL_RECOVERY_OPERATIONS = Object.freeze([
+    ...LIFECYCLE_INTENTS.map((intent) => ({ family: 'task-lifecycle', intent, class: 'lifecycle-mutation' })),
+    { family: 'task-finalization', intent: 'complete', class: 'finalization' },
+    ...ORCHESTRATION_INTENTS.map((intent) => ({
+        family: 'task-orchestration',
+        intent,
+        class: intent === 'route.clean-completion' ? 'route.clean-completion' : intent === 'route.read' || intent === 'status' ? 'read-only' : 'orchestration'
+    })),
+    { family: 'task-create', intent: 'create', class: 'task-create' },
+    ...TASK_WORKFLOW_OPERATIONS.map((intent) => ({ family: 'task-workflow', intent, class: intent === 'artifact-inspect' || intent === 'decision-next-id' ? 'read-only' : 'workflow' })),
+    ...['open', 'close', 'verify'].map((intent) => ({ family: 'codex-controller', intent, class: 'codex-controller' }))
+]);
+export function digestControlRecoveryIntent(family, intent) {
+    return createHash('sha256').update(`${family}\0${intent}`, 'utf8').digest('hex');
+}
+export function findSandboxControlRecoveryOperation(family, intent) {
+    return SANDBOX_CONTROL_RECOVERY_OPERATIONS.find((operation) => operation.family === family && operation.intent === intent) ?? null;
+}
+function bindingMatchesResult(binding, result) {
+    return result.requestId === binding.requestId
+        && result.generation === binding.generation
+        && (result.taskId === undefined || result.taskId === binding.taskId)
+        && (result.intentDigest === undefined || result.intentDigest === binding.intentDigest);
+}
+function domainEvidenceMatches(operation, result, domain) {
+    if (!domain)
+        return false;
+    if (domain.consistent !== true)
+        return false;
+    if (operation.class === 'route.clean-completion') {
+        const completion = domain.completionEvidence;
+        const snapshot = domain.snapshot;
+        const lastReviewedCommit = domain.lastReviewedCommit;
+        return result.status === 'completed'
+            && domain.status === 'completed'
+            && domain.pendingDelegation === null
+            && isCompletionEvidence(completion)
+            && snapshot?.head === completion.head
+            && snapshot.headTree === completion.headTree
+            && snapshot.worktreeTree === completion.worktreeTree
+            && lastReviewedCommit === completion.lastReviewedCommit;
+    }
+    if (operation.family === 'task-lifecycle' && operation.intent === 'recover-started') {
+        const retryRequired = domain.recoveryState === 'retry-required'
+            && sameRecoveryWarning(domain.warning, result.warning);
+        return result.targetState === 'active'
+            && ['applied', 'no-op'].includes(String(result.status))
+            && domain.recovery === true
+            && domain.targetState === 'active'
+            && (domain.recoveryState === 'released' || retryRequired);
+    }
+    if (operation.class === 'read-only')
+        return result.changed === false && domain.snapshotValid === true;
+    return true;
+}
+export function classifySandboxControlRecovery(input) {
+    const result = input.terminalResult ?? null;
+    if (input.evidenceConflict)
+        return { outcome: 'unknown', responseReconstructable: false, reasonCode: 'RECOVERY_EVIDENCE_CONFLICT' };
+    if (input.explicitRejection && !input.startedCommitted) {
+        return { outcome: 'not-executed', responseReconstructable: true, reasonCode: 'RECOVERY_EXPLICIT_REJECTION' };
+    }
+    if (!input.startedCommitted) {
+        return { outcome: 'not-executed', responseReconstructable: false, reasonCode: 'RECOVERY_NOT_STARTED' };
+    }
+    if (!result)
+        return { outcome: 'unknown', responseReconstructable: false, reasonCode: 'RECOVERY_TERMINAL_RESULT_MISSING' };
+    if (!bindingMatchesResult(input.binding, result)) {
+        return { outcome: 'unknown', responseReconstructable: false, reasonCode: 'RECOVERY_RESULT_BINDING_MISMATCH' };
+    }
+    if (!SANDBOX_CONTROL_REQUIRED_COMPLETION_PHASES.every((phase) => input.criticalPhases?.includes(phase))) {
+        return { outcome: 'unknown', responseReconstructable: false, reasonCode: 'RECOVERY_CRITICAL_AUDIT_INCOMPLETE' };
+    }
+    const status = result.status;
+    const failed = status === 'failed' || result.error !== null && result.error !== undefined;
+    if (failed) {
+        if (input.domain && input.domain.consistent === false) {
+            return { outcome: 'failure', responseReconstructable: true, reasonCode: 'RECOVERY_TERMINAL_FAILURE' };
+        }
+        return { outcome: 'unknown', responseReconstructable: false, reasonCode: 'RECOVERY_FAILURE_EVIDENCE_INCOMPLETE' };
+    }
+    if (result.changed === null) {
+        return { outcome: 'unknown', responseReconstructable: false, reasonCode: 'RECOVERY_RESULT_CHANGE_FLAG_MISSING' };
+    }
+    if (!domainEvidenceMatches(input.operation, result, input.domain)) {
+        if (input.journal?.exists && (input.journal.completedSteps?.length ?? 0) > 0) {
+            return { outcome: 'in-progress', responseReconstructable: false, reasonCode: 'RECOVERY_DOMAIN_EVIDENCE_INCOMPLETE' };
+        }
+        return { outcome: 'unknown', responseReconstructable: false, reasonCode: 'RECOVERY_DOMAIN_EVIDENCE_MISSING' };
+    }
+    if (input.operation.family === 'task-lifecycle' && input.journal?.exists) {
+        if (input.journal.failure) {
+            return { outcome: 'failure', responseReconstructable: true, reasonCode: 'RECOVERY_LIFECYCLE_JOURNAL_FAILURE' };
+        }
+        return {
+            outcome: input.journal.completedSteps && input.journal.completedSteps.length > 0 ? 'in-progress' : 'unknown',
+            responseReconstructable: false,
+            reasonCode: 'RECOVERY_LIFECYCLE_JOURNAL_PRESENT'
+        };
+    }
+    return {
+        outcome: 'success',
+        responseReconstructable: true,
+        reasonCode: input.operation.class === 'route.clean-completion' && result.changed === false
+            ? 'RECOVERY_ROUTE_COMPLETION_NOOP'
+            : input.operation.intent === 'recover-started' && input.domain?.recoveryState === 'retry-required'
+                ? 'RECOVERY_RELEASE_RETRY_REQUIRED'
+                : 'RECOVERY_TERMINAL_AND_DOMAIN_MATCH'
+    };
+}
+export function operationRecoveryBinding(requestId, generation, taskId, family, intent) {
+    return { requestId, generation, taskId, intentDigest: digestControlRecoveryIntent(family, intent) };
+}
+//# sourceMappingURL=control-recovery.js.map