@fitlab-ai/agent-infra 0.9.7 → 0.9.8

package/dist/lib/task/ledger-intents.js

@@ -4,6 +4,7 @@ import { declareImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplemen
 import { LEDGER_COLUMNS, LEDGER_HEADINGS, nextHdId, parseLedger, validateLedgerRows } from './ledger.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { writeTask } from './write.js';
+import { allowsManualOverride } from './guard-override.js';
 const PREFIX = { analysis: 'AN', plan: 'PL', code: 'CD' };
 const RESPONSE = new Set(['accepted', 'adjusted', 'refuted', 'cannot-judge']);
 const DISPOSITION = new Set(['confirmed', 'closed', 'open', 'needs-human-decision']);
@@ -84,7 +85,8 @@ function applyLedgerIntent(intent, options = {}) {
     const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(intent, resolved.code, resolved.message, resolved.taskId);
-    if (resolved.state !== 'active')
+    const stateOverride = allowsManualOverride(options.manualOverride, 'ledger-intent', 'TASK_STATE_MISMATCH');
+    if (resolved.state !== 'active' && !stateOverride)
         return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
     let content;
     let rows;
@@ -176,7 +178,8 @@ function applyLedgerIntent(intent, options = {}) {
                         ? new Set(['confirmed', 'open', 'needs-human-decision'])
                         : before.status === 'cannot-judge' ? new Set(['open', 'needs-human-decision']) : new Set();
                 const sameRoundMinorClose = before.status === 'open' && before.severity === 'minor' && intent.status === 'closed';
-                if ((!sameRoundMinorClose && !allowed.has(intent.status)) || (intent.status === 'open' && Number(before.round) >= maxHandshakeRounds(resolved.repoRoot))) {
+                if (((!sameRoundMinorClose && !allowed.has(intent.status)) || (intent.status === 'open' && Number(before.round) >= maxHandshakeRounds(resolved.repoRoot)))
+                    && !allowsManualOverride(options.manualOverride, 'ledger-intent', 'LEDGER_TRANSITION_INVALID')) {
                     return failed(intent, 'LEDGER_TRANSITION_INVALID', `finding '${intent.id}' cannot transition from ${before.status} to ${intent.status}`, resolved.taskId, intent.id);
                 }
                 after = { ...before, status: intent.status, evidence };
@@ -209,7 +212,7 @@ function applyLedgerIntent(intent, options = {}) {
         }
     }
     const result = writeTask({
-        taskRef: intent.taskRef, expectedState: 'active',
+        taskRef: intent.taskRef, expectedState: stateOverride ? resolved.state : 'active',
         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 } });

package/dist/lib/task/lifecycle.js

@@ -10,6 +10,36 @@ import { captureTaskWriteMetadata, writeTask } from './write.js';
 const lifecycleIntentCatalog = [
     'block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore'
 ];
+const lifecycleFailureCatalog = [
+    'LIFECYCLE_DIRECTORY_RENAME_FAILED',
+    'LIFECYCLE_DOCUMENT_INVALID',
+    'LIFECYCLE_FINAL_STATE_INVALID',
+    'LIFECYCLE_IDENTITY_CONFLICT',
+    'LIFECYCLE_IDENTITY_INVALID',
+    'LIFECYCLE_INTENT_CONFLICT',
+    'LIFECYCLE_JOURNAL_CLEANUP_FAILED',
+    'LIFECYCLE_JOURNAL_INVALID',
+    'LIFECYCLE_JOURNAL_WRITE_FAILED',
+    'LIFECYCLE_LOG_MISSING',
+    'LIFECYCLE_METADATA_FAILED',
+    'LIFECYCLE_PAYLOAD_INVALID',
+    'LIFECYCLE_SHORT_ID_FAILED',
+    'LIFECYCLE_SHORT_ID_PRECONDITION',
+    'LIFECYCLE_SOURCE_INVALID',
+    'LIFECYCLE_STAGING_IDENTITY_INVALID',
+    'LIFECYCLE_STAGING_INVALID',
+    'LIFECYCLE_TARGET_CONFLICT',
+    'LIFECYCLE_TASK_NOT_FOUND',
+    'SHORT_ID_CAPACITY_EXCEEDED'
+];
+const lifecycleProducerCatalog = lifecycleFailureCatalog.map((code) => ({
+    producerId: 'lifecycle.apply',
+    guardId: 'G-03',
+    code
+}));
+function allowsManualOverride(options, code) {
+    return options.manualOverride?.failureId === `lifecycle.apply:${code}`;
+}
 const STEPS = ['task-written', 'directory-moved', 'registry-committed'];
 const DEFAULT_IO = {
     renameSync: (source, target) => fs.renameSync(source, target),
@@ -121,10 +151,17 @@ function matchingCompletion(content, request, restoredFiles = 0) {
     return section.entries.some((entry) => entry.step === identity.action && entry.agent === request.agent && entry.note === identity.note);
 }
 function validateRestoreStaging(request, repoRoot, taskId) {
-    const workspace = path.resolve(repoRoot, '.agents', 'workspace');
-    const stagingDir = path.resolve(request.stagingDir);
+    let workspace;
+    let stagingDir;
+    try {
+        workspace = fs.realpathSync.native(path.resolve(repoRoot, '.agents', 'workspace'));
+        stagingDir = fs.realpathSync.native(path.resolve(request.stagingDir));
+    }
+    catch (error) {
+        return { code: 'LIFECYCLE_STAGING_INVALID', message: String(error) };
+    }
     const relative = path.relative(workspace, stagingDir);
-    if (!relative || relative.startsWith('..') || path.isAbsolute(relative) || path.basename(stagingDir) === taskId) {
+    if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || path.basename(stagingDir) === taskId) {
         return { code: 'LIFECYCLE_STAGING_INVALID', message: 'restore staging must be a non-final directory inside .agents/workspace' };
     }
     let entries;
@@ -168,8 +205,8 @@ function validateRestoreStaging(request, repoRoot, taskId) {
     }
     return { stagingDir, fileCount: entries.filter((entry) => !entry.name.startsWith('.')).length };
 }
-function mutationsFor(request, content, metadata, restoredFiles) {
-    const section = locateActivityLog(content);
+function mutationsFor(request, content, metadata, restoredFiles, allowMissingActivityLog = false) {
+    const section = locateActivityLog(content) ?? (allowMissingActivityLog ? { heading: 'Activity Log', body: '', entries: [] } : null);
     if (!section)
         return { code: 'LIFECYCLE_LOG_MISSING', message: 'task has no unique Activity Log section' };
     const identity = actionAndNote(request, restoredFiles);
@@ -230,6 +267,14 @@ function writeJournal(file, journal, io, create = false) {
         throw error;
     }
 }
+function rememberJournalFailure(file, journal, io, failure) {
+    try {
+        writeJournal(file, { ...journal, failure }, io);
+    }
+    catch {
+        // Preserve the original lifecycle failure when the diagnostic receipt cannot be updated.
+    }
+}
 function parseJournal(content) {
     const value = JSON.parse(content);
     if (value.version !== 1 || typeof value.taskId !== 'string' ||
@@ -303,7 +348,7 @@ function applyTaskLifecycle(requestInput, options = {}) {
         }
         return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: `task ${taskId} is already ${spec.target} with a different lifecycle intent` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
     }
-    if (!spec.sources.includes(sourceState) && !existingJournal) {
+    if (!spec.sources.includes(sourceState) && !existingJournal && !allowsManualOverride(options, 'LIFECYCLE_SOURCE_INVALID')) {
         return failed(request, { code: 'LIFECYCLE_SOURCE_INVALID', message: `${request.intent} is not allowed from ${sourceState}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
     }
     if (sourcePath !== targetPath && fs.existsSync(targetPath)) {
@@ -319,7 +364,7 @@ function applyTaskLifecycle(requestInput, options = {}) {
     }
     if (frontmatter.id !== taskId)
         return failed(request, { code: 'LIFECYCLE_IDENTITY_INVALID', message: 'task.md id does not match its lifecycle task id' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
-    if (!locateActivityLog(content))
+    if (!locateActivityLog(content) && !allowsManualOverride(options, 'LIFECYCLE_LOG_MISSING'))
         return failed(request, { code: 'LIFECYCLE_LOG_MISSING', message: 'task has no unique Activity Log section' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
     const registryRequest = executeShortIdCommand({
         operation: 'list', activeDir: path.join(repoRoot, '.agents', 'workspace', 'active'),
@@ -330,10 +375,10 @@ function applyTaskLifecycle(requestInput, options = {}) {
     }
     const registry = JSON.parse(registryRequest.output || '{"version":1,"ids":{}}');
     const registeredKey = Object.entries(registry.ids).find(([, candidate]) => candidate === taskId)?.[0];
-    if (spec.registry === 'release' && sourceState === 'active' && !registeredKey) {
+    if (spec.registry === 'release' && sourceState === 'active' && !registeredKey && !allowsManualOverride(options, 'LIFECYCLE_SHORT_ID_PRECONDITION')) {
         return failed(request, { code: 'LIFECYCLE_SHORT_ID_PRECONDITION', message: 'active source has no short-id registry entry' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
     }
-    if (spec.registry === 'alloc' && !registeredKey && Object.keys(registry.ids).length >= 10 ** configuredShortIdLength(repoRoot) - 1) {
+    if (spec.registry === 'alloc' && !registeredKey && Object.keys(registry.ids).length >= 10 ** configuredShortIdLength(repoRoot) - 1 && !allowsManualOverride(options, 'SHORT_ID_CAPACITY_EXCEEDED')) {
         return failed(request, { code: 'SHORT_ID_CAPACITY_EXCEEDED', message: 'short-id registry has no free slot' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
     }
     const digest = intentIdentity(request, taskId);
@@ -347,7 +392,15 @@ function applyTaskLifecycle(requestInput, options = {}) {
         catch (error) {
             return failed(request, { code: 'LIFECYCLE_JOURNAL_INVALID', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
         }
-        if (journal.intentDigest !== digest || journal.taskId !== taskId)
+        if (journal.taskId !== taskId || journal.intent !== request.intent)
+            return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: 'an in-progress lifecycle journal belongs to a different request' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
+        if (request.dryRun) {
+            if (!journal.failure)
+                return failed(request, { code: 'LIFECYCLE_JOURNAL_INVALID', message: 'existing lifecycle journal has no durable failure evidence for a read-only probe' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
+            return failed(request, journal.failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath, completedSteps: journal.completedSteps, pendingSteps: STEPS.filter((step) => !journal.completedSteps.includes(step)) });
+        }
+        const overrideResumesRecordedFailure = journal.failure && allowsManualOverride(options, journal.failure.code);
+        if (journal.intentDigest !== digest && !overrideResumesRecordedFailure)
             return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: 'an in-progress lifecycle journal belongs to a different request' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
     }
     else {
@@ -360,7 +413,7 @@ function applyTaskLifecycle(requestInput, options = {}) {
         }
         journal = { version: 1, taskId, intent: request.intent, intentDigest: digest, sourceState, targetState: spec.target, metadata, completedSteps: [] };
         if (request.dryRun) {
-            const plannedMutations = mutationsFor(request, content, metadata, restoredFiles);
+            const plannedMutations = mutationsFor(request, content, metadata, restoredFiles, allowsManualOverride(options, 'LIFECYCLE_LOG_MISSING'));
             if ('code' in plannedMutations)
                 return failed(request, plannedMutations, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
             const taskPlan = writeTask({ taskRef: taskId, expectedState: sourceState === 'blocked' ? 'blocked' : 'active', mutations: plannedMutations, dryRun: true }, {
@@ -402,7 +455,7 @@ function applyTaskLifecycle(requestInput, options = {}) {
         completed.add('task-written');
     if (!completed.has('task-written')) {
         const current = io.readFileSync(path.join(sourcePath, 'task.md'));
-        const mutations = mutationsFor(request, current, journal.metadata, restoredFiles);
+        const mutations = mutationsFor(request, current, journal.metadata, restoredFiles, allowsManualOverride(options, 'LIFECYCLE_LOG_MISSING'));
         if ('code' in mutations)
             return failed(request, mutations, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, completedSteps: [...completed], changed: completed.size > 0 });
         const writeResult = writeTask({ taskRef: taskId, expectedState: sourceState === 'blocked' ? 'blocked' : 'active', mutations }, {
@@ -432,7 +485,9 @@ function applyTaskLifecycle(requestInput, options = {}) {
             (options.directoryRenameSync ?? io.renameSync)(sourcePath, targetPath);
         }
         catch (error) {
-            return failed(request, { code: 'LIFECYCLE_DIRECTORY_RENAME_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
+            const failure = { code: 'LIFECYCLE_DIRECTORY_RENAME_FAILED', message: String(error) };
+            rememberJournalFailure(journalPath, journal, io, failure);
+            return failed(request, failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
         }
         completed.add('directory-moved');
         journal.completedSteps = [...completed];
@@ -480,5 +535,5 @@ function applyTaskLifecycle(requestInput, options = {}) {
         journalPath, completedSteps: [...completed], pendingSteps: []
     };
 }
-export { lifecycleIntentCatalog, applyTaskLifecycle };
+export { lifecycleIntentCatalog, lifecycleFailureCatalog, lifecycleProducerCatalog, applyTaskLifecycle };
 //# sourceMappingURL=lifecycle.js.map

package/dist/lib/task/orchestration.js

@@ -7,8 +7,9 @@ import { parseReviewSummary } from './review-artifacts.js';
 import { inspectArtifactDirectory } from './artifact-lifecycle.js';
 import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { resolveTaskRef } from './resolve-ref.js';
-import { activateDelegation, abortPreparedDelegation, completeDelegationStage, consumeDelegation, dispatchDelegation, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
+import { activateDelegation, abortPreparedDelegation, completeDelegationStage, consumeDelegation, dispatchDelegation, foldBlankToNull, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
 import { normalizeAgentClients } from '../agent-clients/config.js';
+import { resolveAgentRuntimeStoreRoot } from '../runtime/agent-runtime.js';
 import { inspectPlatformPullRequest } from '../platform/pull-requests.js';
 import { getAgentClientCapability, getAgentClientDelegationEvidence, getAgentClientModelSelection } from '../agent-clients/registry.js';
 import { isAgentClientId } from '../agent-clients/types.js';
@@ -176,6 +177,22 @@ function canRecoverCodexUnsupportedPause(run, taskDir) {
         && !fs.existsSync(commitIntentPath(taskDir))
         && (run.recoveryHistory ?? []).every((entry) => entry.code === 'MODEL_POLICY_SUPPLEMENTED');
 }
+function canRecoverClaudeCodeUnsupportedPause(run, taskDir) {
+    return run.schemaVersion === 3
+        && run.status === 'paused'
+        && run.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+        && run.modelPolicySource?.client === 'claude-code'
+        && run.stepCount === 0
+        && run.nextStage === null
+        && run.baseline === ''
+        && run.pendingDelegation === null
+        && run.receipts.length === 0
+        && run.commitAuthorization?.issuedAt === null
+        && run.commitAuthorization?.consumedAt === null
+        && run.completionEvidence == null
+        && !fs.existsSync(commitIntentPath(taskDir))
+        && (run.recoveryHistory ?? []).length === 0;
+}
 function canMigrateRecoverableV2Pause(run, taskDir) {
     return run.schemaVersion === 2
         && run.status === 'paused'
@@ -239,6 +256,39 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
                 }
             }
             if (existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED') {
+                if (existing.modelPolicySource.client === 'claude-code') {
+                    if (!canRecoverClaudeCodeUnsupportedPause(existing, resolved.taskDir)) {
+                        return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+                    }
+                    const now = (options.now ?? (() => new Date().toISOString()))();
+                    const previousPause = existing.pause;
+                    const recovery = {
+                        code: 'CLIENT_CAPABILITY_ENABLED_NO_MIGRATION',
+                        recoveredAt: now,
+                        previousSchemaVersion: 3,
+                        previousStatus: 'paused',
+                        previousPause,
+                        client: 'claude-code',
+                        guards: {
+                            stepCount: 0,
+                            nextStage: null,
+                            baselineEmpty: true,
+                            receiptCount: 0,
+                            pendingDelegation: false,
+                            commitAuthorizationUnused: true,
+                            completionEvidenceAbsent: true,
+                            commitIntentAbsent: true
+                        },
+                        resultingStatus: 'running'
+                    };
+                    const resumed = withUpdatedRun(existing, {
+                        status: 'running',
+                        pause: null,
+                        recoveryHistory: Object.freeze([...(existing.recoveryHistory ?? []), recovery])
+                    }, () => now);
+                    saveRun(resolved.taskDir, resumed);
+                    return { status: 'running', changed: true, taskId: resolved.taskId, run: resumed, next: null, error: null };
+                }
                 if (!canRecoverCodexUnsupportedPause(existing, resolved.taskDir)) {
                     return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
                 }
@@ -1240,9 +1290,9 @@ function activateMatchingOrchestrationDelegation(client, event, options = {}) {
             return matched;
         const receipt = replay.run.pendingDelegation;
         const sameEvidence = receipt.parentId === event.parentId
-            && receipt.spawnMode === event.spawnMode
-            && receipt.actualModel === event.actualModel
-            && receipt.actualReasoningEffort === event.actualReasoningEffort
+            && (receipt.spawnMode ?? null) === (event.spawnMode ?? null)
+            && (receipt.actualModel ?? null) === foldBlankToNull(event.actualModel)
+            && (receipt.actualReasoningEffort ?? null) === foldBlankToNull(event.actualReasoningEffort)
             && receipt.modelFallbackReason === (event.modelFallbackReason ?? null)
             && receipt.reasoningEffortFallbackReason === (event.reasoningEffortFallbackReason ?? null)
             && receipt.hostEvidence?.hookDefinitionHash === event.hostEvidence?.hookDefinitionHash;
@@ -1287,7 +1337,11 @@ function sealMatchingOrchestrationDelegation(client, event, options = {}) {
             childId: event.childId,
             exitCode: 0,
             afterFingerprint,
-            changedPaths
+            changedPaths,
+            actualModel: event.actualModel,
+            actualReasoningEffort: event.actualReasoningEffort,
+            modelFallbackReason: event.modelFallbackReason,
+            reasoningEffortFallbackReason: event.reasoningEffortFallbackReason
         }, options);
     }
     catch (error) {
@@ -1440,7 +1494,7 @@ function recoverPreparedOrchestrationDelegation(taskRef, options = {}) {
             const activeLifecycleEvidence = options.hasActiveLifecycleEvidence?.(receipt)
                 ?? (receipt.client === 'codex'
                     && receipt.lifecycleProvenance
-                    && hasActiveCodexLifecycleEvidence(path.join(resolved.repoRoot, '.agents', 'workspace', '.runtime', 'codex-lifecycle'), {
+                    && hasActiveCodexLifecycleEvidence(resolveAgentRuntimeStoreRoot({ repoRoot: resolved.repoRoot, store: 'lifecycle' }), {
                         nativeAgent: `agent-infra-lifecycle-${receipt.role}`,
                         hookDefinitionHash: receipt.lifecycleProvenance.hookDefinitionHash
                     }));

package/dist/lib/task/review-finalization.js

@@ -8,6 +8,7 @@ import { finalizeReviewSummaryContent } from './review-artifacts.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { validateLifecycleExecution } from './lifecycle-execution.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
+import { allowsManualOverride } from './guard-override.js';
 const STAGES = {
     analysis: { family: 'review-analysis', action: 'Review Analysis' },
     plan: { family: 'review-plan', action: 'Review Plan' },
@@ -60,7 +61,7 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(request, resolved.code, resolved.message, resolved.taskId);
-    if (resolved.state !== 'active') {
+    if (resolved.state !== 'active' && !allowsManualOverride(options.manualOverride, 'review-finalization', 'TASK_STATE_MISMATCH')) {
         return failed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
     }
     const parsedArtifact = parseArtifactName(request.artifact);
@@ -168,7 +169,7 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
     };
 }
 function finalizeReviewSummary(request, options = {}) {
-    if (request.dryRun)
+    if (request.dryRun || options.lockAlreadyHeld)
         return finalizeReviewSummaryUnlocked(request, options);
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)

package/dist/lib/task/verification-engine.js

@@ -261,7 +261,22 @@ function checkOrchestrationEvidence({ taskDir }) {
             && guards?.commitAuthorizationUnused === true
             && guards?.completionEvidenceAbsent === true
             && guards?.commitIntentAbsent === true;
-        if (!validModelRecovery && !validCapabilityRecovery) {
+        const validClaudeCodeRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED_NO_MIGRATION'
+            && recovery.previousSchemaVersion === 3
+            && recovery.previousStatus === 'paused'
+            && recovery.previousPause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+            && recovery.client === 'claude-code'
+            && recovery.resultingStatus === 'running'
+            && exactText(recovery.recoveredAt)
+            && guards?.stepCount === 0
+            && guards?.nextStage === null
+            && guards?.baselineEmpty === true
+            && guards?.receiptCount === 0
+            && guards?.pendingDelegation === false
+            && guards?.commitAuthorizationUnused === true
+            && guards?.completionEvidenceAbsent === true
+            && guards?.commitIntentAbsent === true;
+        if (!validModelRecovery && !validCapabilityRecovery && !validClaudeCodeRecovery) {
             return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
         }
     }
@@ -292,26 +307,37 @@ function checkOrchestrationEvidence({ taskDir }) {
         }
         const activated = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
         if (activated) {
-            if (!exactText(receipt.actualModel)) {
-                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+            const isClaudeCode = receipt.client === 'claude-code';
+            if (!isClaudeCode) {
+                if (!exactText(receipt.actualModel)) {
+                    return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+                }
+                if (!exactText(receipt.actualReasoningEffort)) {
+                    return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+                }
             }
-            if (!exactText(receipt.actualReasoningEffort)) {
-                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+            // parentId/childId 校验对所有 client 保持统一（不新增分支）；spawnMode 检查按 client 判断
+            if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId) {
+                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid delegation identity`);
             }
-            if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId || receipt.spawnMode !== 'fresh') {
+            if (!isClaudeCode && receipt.spawnMode !== 'fresh') {
                 return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid fresh delegation identity`);
             }
-            if (receipt.actualModel !== receipt.requestedModel && !exactText(receipt.modelFallbackReason)) {
-                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
+            if (receipt.actualModel != null && receipt.actualModel !== receipt.requestedModel) {
+                if (!isClaudeCode && !exactText(receipt.modelFallbackReason)) {
+                    return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
+                }
             }
-            if (receipt.actualModel === receipt.requestedModel && receipt.modelFallbackReason !== null) {
+            if ((receipt.actualModel == null || receipt.actualModel === receipt.requestedModel)
+                && receipt.modelFallbackReason !== null) {
                 return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
             }
-            if (receipt.actualReasoningEffort !== receipt.requestedReasoningEffort
-                && !exactText(receipt.reasoningEffortFallbackReason)) {
-                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+            if (receipt.actualReasoningEffort != null && receipt.actualReasoningEffort !== receipt.requestedReasoningEffort) {
+                if (!isClaudeCode && !exactText(receipt.reasoningEffortFallbackReason)) {
+                    return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+                }
             }
-            if (receipt.actualReasoningEffort === receipt.requestedReasoningEffort
+            if ((receipt.actualReasoningEffort == null || receipt.actualReasoningEffort === receipt.requestedReasoningEffort)
                 && receipt.reasoningEffortFallbackReason !== null) {
                 return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated reasoning-effort fallback reason`);
             }
@@ -774,7 +800,7 @@ function checkReviewLedger({ taskDir, config }) {
         return passResult("review-ledger", "Disagreement ledger has no entries");
     }
     const stageScope = Array.isArray(config.stage_scope) ? config.stage_scope : null;
-    const maxRounds = Number(resolveReviewSetting(config, "max_handshake_rounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
+    const maxRounds = Number(resolveReviewSetting(config, "maxHandshakeRounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
     const problems = [];
     let inScopeCount = 0;
     for (const cells of rows) {

package/dist/lib/task/verification.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { verifyInProcess } from './verification-engine.js';
 import { parseArtifactName } from './artifact-lifecycle.js';
 import { resolveTaskRef } from './resolve-ref.js';
+import { allowsManualOverride } from './guard-override.js';
 const gate = (skill, expectedState, artifactFamily) => ({
     skill, expectedState, mode: 'gate', ...(artifactFamily ? { artifactFamily } : {})
 });
@@ -47,7 +48,7 @@ function verifyTaskEvent(request, options = {}) {
     if (!resolved.ok)
         return failure(request, resolved.code, resolved.message, { taskId: resolved.taskId, skill: spec.skill, mode: spec.mode });
     const identity = { taskId: resolved.taskId, taskDir: resolved.taskDir, taskState: resolved.state, skill: spec.skill, mode: spec.mode };
-    if (resolved.state !== spec.expectedState) {
+    if (resolved.state !== spec.expectedState && !allowsManualOverride(options.manualOverride, 'task-verify', 'VERIFY_TASK_STATE_MISMATCH')) {
         return failure(request, 'VERIFY_TASK_STATE_MISMATCH', `event '${request.event}' requires workspace '${spec.expectedState}', received '${resolved.state}'`, identity);
     }
     if (spec.artifactFamily) {
@@ -66,12 +67,23 @@ function verifyTaskEvent(request, options = {}) {
     if (spec.mode === 'gate') {
         const payload = engine({ mode: 'gate', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [], repositoryRoot: resolved.repoRoot });
         const status = payload.gate;
+        if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+            invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, gate: 'pass', humanOverride: 'human-approved', originalGate: status } });
+            return {
+                status: 'pass', changed: false, event: request.event, requestRef: request.taskRef,
+                ...identity, artifact: request.artifact ?? null, invocations, error: null
+            };
+        }
         invocations.push({ status, exitCode: { pass: 0, fail: 1, blocked: 2 }[status], payload });
     }
     else {
         for (const check of spec.checks ?? []) {
             const payload = engine({ mode: 'checks', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [check], repositoryRoot: resolved.repoRoot });
             const status = payload.status;
+            if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+                invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, status: 'pass', humanOverride: 'human-approved', originalStatus: status } });
+                break;
+            }
             invocations.push({ status, exitCode: { pass: 0, fail: 1, blocked: 2 }[status], payload });
             if (status !== 'pass')
                 break;

package/dist/lib/task/workflow-warning-intents.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import { resolveTaskRef } from './resolve-ref.js';
 import { WORKFLOW_WARNING_COLUMNS, WORKFLOW_WARNING_HEADINGS, WORKFLOW_WARNING_SEVERITIES, WORKFLOW_WARNING_STATUSES, parseWorkflowWarnings } from './workflow-warnings.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
+import { allowsManualOverride } from './guard-override.js';
 function failed(intent, code, message, taskId = null, entityId = null) {
     return { status: 'failed', changed: false, intent: intent.kind, taskId, entityId, before: null, after: null, warnings: [], operations: [], error: { code, message } };
 }
@@ -54,7 +55,8 @@ function applyWorkflowWarningIntent(intent, options = {}) {
     const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(intent, resolved.code, resolved.message, resolved.taskId);
-    if (resolved.state !== 'active')
+    const stateOverride = allowsManualOverride(options.manualOverride, 'workflow-warning', 'TASK_STATE_MISMATCH');
+    if (resolved.state !== 'active' && !stateOverride)
         return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
     let content;
     let rows;
@@ -114,7 +116,7 @@ function applyWorkflowWarningIntent(intent, options = {}) {
             after = { ...before, status: intent.status, resolvedAt: metadata.timestamp, resolution };
     }
     const writeResult = writeTask({
-        taskRef: intent.taskRef, expectedState: 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
+        taskRef: intent.taskRef, expectedState: stateOverride ? resolved.state : 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
     }, {
         ...options,
         taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state },

package/dist/lib/task/write.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { VERSION } from '../version.js';
 import { parseTypedTaskFrontmatter, updateTaskFrontmatter } from './frontmatter.js';
 import { resolveTaskRef } from './resolve-ref.js';
+import { allowsManualOverride } from './guard-override.js';
 import { mutateTableRow, upsertSection } from './sections.js';
 const DEFAULT_FILE_SYSTEM = {
     readFileSync: (file) => fs.readFileSync(file, 'utf8'),
@@ -70,7 +71,7 @@ function writeTask(request, options = {}) {
         taskMdPath: resolved.taskMdPath,
         actualState: resolved.state
     };
-    if (resolved.state !== request.expectedState) {
+    if (resolved.state !== request.expectedState && !allowsManualOverride(options.manualOverride, 'task.write', 'TASK_STATE_MISMATCH')) {
         return failure(request, identity, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected ${request.expectedState}`);
     }
     const io = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.9.7",
-  "sourceInputHash": "ee12d1ec7a586eeaba04deb4253ccd7f5d16552915ca141e493248c0728459a9",
-  "internalExecutableBuildHash": "0eceb914e6c1cb9937b86d34bfbf933d1010f499b9976813556146d2e6fa0132"
+  "packageVersion": "0.9.8",
+  "sourceInputHash": "fb481e6579519b3fd10c9ca9bf284d65498f935c034a14c047d023345abeb87c",
+  "internalExecutableBuildHash": "d8dcdf602b61001ba9829aa2027cccadcc9c371ccf9e29c3d681fd02d5a3a5af"
 }

package/lib/agent-clients/adapters/claude-code.ts

@@ -16,7 +16,7 @@ const claudeCodeAdapter = defineAgentClientAdapter({
     commands: { level: 'integrated' },
     hooks: { level: 'integrated' },
     subagents: { level: 'experimental' },
-    orchestration: { level: 'unsupported' },
+    orchestration: { level: 'experimental' },
     sandbox: { level: 'integrated' },
     verification: { level: 'compatible' }
   },
@@ -26,8 +26,8 @@ const claudeCodeAdapter = defineAgentClientAdapter({
     guidance: 'Use the host model picker for the complete model and reasoning-effort catalog.'
   },
   delegationEvidence: {
-    actualModel: 'unavailable',
-    actualReasoningEffort: 'unavailable'
+    actualModel: 'host-event',
+    actualReasoningEffort: 'spawn-ack'
   },
   project: {
     ownedPathPrefixes: ['.claude/'],

package/lib/agent-clients/adapters/codex-lifecycle/app-server.ts

@@ -7,6 +7,7 @@ import semver from 'semver';
 
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 import type { CodexLifecycleEvent } from './evidence.ts';
+import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.ts';
 
 type JsonObject = Record<string, unknown>;
 type ThreadResolution = Readonly<{
@@ -558,7 +559,7 @@ async function preflightCodexLifecycleEvidence(
   }
 
   const hookDefinitionHash = crypto.createHash('sha256').update(hooksRaw).digest('hex');
-  const runtimeRoot = path.join(repoRoot, '.agents', 'workspace', '.runtime', 'codex-lifecycle');
+  const runtimeRoot = resolveAgentRuntimeStoreRoot({ repoRoot, store: 'lifecycle' });
   const runtimeLiveness = hasCodexRuntimeLiveness(runtimeRoot, hookDefinitionHash, runtimeIdentity);
 
   const transport = new CodexAppServerTransport();

package/lib/agent-clients/adapters/codex-lifecycle/capability-store.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 
 import { verifyLifecycleBuildIdentity } from './build-identity.ts';
 import type { LifecycleBuildIdentity } from './build-identity.ts';
+import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.ts';
 
 type CapabilityStatus = 'armed' | 'attested' | 'consumed' | 'expired';
 type CodexControllerBinding = Readonly<{
@@ -65,7 +66,7 @@ function sameController(
 
 function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
   const root = options.root
-    ?? path.join(process.cwd(), '.agents', 'workspace', '.runtime', 'codex-capabilities');
+    ?? resolveAgentRuntimeStoreRoot({ store: 'capabilities' });
   const now = options.now ?? Date.now;
   const createToken = options.token ?? (() => crypto.randomBytes(32).toString('base64url'));
   const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;