@fitlab-ai/agent-infra 0.12.1 → 0.12.2

package/dist/lib/task/orchestration.js

@@ -1,1233 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { createHash, randomUUID } from 'node:crypto';
-import { inspectArtifactDirectory } from './artifact-lifecycle.js';
-import { parseTypedTaskFrontmatter } from './frontmatter.js';
-import { validateCurrentTaskContract } from './current-contract.js';
-import { parseReviewSummary } from './review-artifacts.js';
-import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
-import { resolveTaskRef, TASK_ID_RE } from './resolve-ref.js';
-import { resolveProjectTaskWorkspaceRoot } from './workspace-root.js';
-import { activateDelegation, abortActivatedDelegation, abortPreparedDelegation, completeDelegationStage, consumeDelegation, dispatchDelegation, foldBlankToNull, isDelegationReceipt, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
-import { normalizeAgentClients } from '../agent-clients/config.js';
-import { getAgentClientAdapter, getAgentClientCapability, getAgentClientDelegationEvidence, getAgentClientModelSelection } from '../agent-clients/registry.js';
-import { isAgentClientId } from '../agent-clients/types.js';
-import { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots } from './workspace-snapshot.js';
-import { assertGitRepositoryBinding } from '../git/worktree-identity.js';
-import { extractReviewBaseline, extractReviewDiffBase, extractReviewTargetHead, extractReviewedHead } from './review-fingerprint.js';
-import { resolveDeliveryTarget, resolveDiffBase, resolveTargetHead } from './delivery-target.js';
-import { buildLifecycleFacts, canStart, recommendNext } from './capabilities.js';
-import { hasOpenLifecycleExecution } from './activity-log.js';
-import { normalizeAgentToken } from '../agent-clients/tokens.js';
-import { resolveArtifactContextForResolvedTask } from './artifact-lifecycle.js';
-function supportsLifecycleDelegation(client) {
-    return getAgentClientCapability(client, 'subagents').level !== 'unsupported'
-        && getAgentClientCapability(client, 'orchestration').level !== 'unsupported'
-        && getAgentClientDelegationEvidence(client).actualModel !== 'unavailable'
-        && getAgentClientDelegationEvidence(client).actualReasoningEffort !== 'unavailable';
-}
-function orchestrationPath(taskDir) {
-    return path.join(taskDir, '.runtime', 'orchestration.json');
-}
-const ORCHESTRATION_STATE_INVALID_MESSAGE = 'orchestration.json does not match the current runtime structure; the file was left unchanged; rebuild the sandbox or manually repair the state before retrying';
-class OrchestrationStateError extends Error {
-    code = 'ORCHESTRATION_STATE_INVALID';
-    taskId;
-    reasonCodes;
-    constructor(taskId = null, reasonCodes = []) {
-        super(ORCHESTRATION_STATE_INVALID_MESSAGE);
-        this.name = 'OrchestrationStateError';
-        this.taskId = taskId;
-        this.reasonCodes = Object.freeze([...reasonCodes]);
-    }
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function hasExactKeys(value, keys) {
-    if (!isRecord(value))
-        return false;
-    const actual = Object.keys(value);
-    return actual.length === keys.length && keys.every((key) => Object.prototype.hasOwnProperty.call(value, key));
-}
-function exactText(value) {
-    return typeof value === 'string' && value.length > 0 && value.trim() === value;
-}
-function nullableText(value) {
-    return value === null || exactText(value);
-}
-function isPause(value) {
-    return hasExactKeys(value, ['code', 'message', 'recoverable'])
-        && exactText(value.code)
-        && exactText(value.message)
-        && typeof value.recoverable === 'boolean';
-}
-function isModelPolicySource(value) {
-    return hasExactKeys(value, ['kind', 'client', 'resolvedAt'])
-        && ['explicit', 'project-config'].includes(value.kind)
-        && isAgentClientId(value.client)
-        && exactText(value.resolvedAt);
-}
-function isModelPolicy(value) {
-    if (!hasExactKeys(value, ['executor', 'reviewer']))
-        return false;
-    return [value.executor, value.reviewer].every((role) => hasExactKeys(role, ['model', 'reasoningEffort'])
-        && exactText(role.model)
-        && exactText(role.reasoningEffort));
-}
-const RECOVERY_GUARD_KEYS = [
-    'stepCount', 'nextStage', 'baselineEmpty', 'receiptCount', 'pendingDelegation',
-    'completionEvidenceAbsent'
-];
-function isRecovery(value) {
-    if (!hasExactKeys(value, [
-        'code', 'recoveredAt', 'previousStatus', 'previousPause', 'client', 'guards', 'resultingStatus'
-    ]))
-        return false;
-    const guards = value.guards;
-    return value.code === 'CLIENT_CAPABILITY_ENABLED'
-        && exactText(value.recoveredAt)
-        && value.previousStatus === 'paused'
-        && isPause(value.previousPause)
-        && value.previousPause.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
-        && isAgentClientId(value.client)
-        && hasExactKeys(guards, RECOVERY_GUARD_KEYS)
-        && guards.stepCount === 0
-        && guards.nextStage === null
-        && guards.baselineEmpty === true
-        && guards.receiptCount === 0
-        && guards.pendingDelegation === false
-        && guards.completionEvidenceAbsent === true
-        && value.resultingStatus === 'running';
-}
-export function isCompletionEvidence(value) {
-    return hasExactKeys(value, [
-        'kind', 'observedAt', 'head', 'headTree', 'worktreeTree', 'lastReviewedCommit', 'prNumber', 'prHead'
-    ])
-        && value.kind === 'reviewed-head-clean'
-        && exactText(value.observedAt)
-        && exactText(value.head)
-        && exactText(value.headTree)
-        && exactText(value.worktreeTree)
-        && exactText(value.lastReviewedCommit)
-        && (value.prNumber === null || (Number.isSafeInteger(value.prNumber) && value.prNumber > 0))
-        && (value.prHead === null || exactText(value.prHead));
-}
-const ORCHESTRATION_RUN_KEYS = [
-    'taskId', 'runId', 'status', 'nextStage', 'stepCount', 'maxSteps', 'modelPolicy',
-    'modelPolicySource', 'recoveryHistory', 'baseline', 'pendingDelegation', 'receipts',
-    'pause', 'completionEvidence', 'createdAt', 'updatedAt'
-];
-function orchestrationStateReasonCodes(value) {
-    if (!hasExactKeys(value, ORCHESTRATION_RUN_KEYS))
-        return ['top-level-keys'];
-    const record = value;
-    const reasons = [];
-    if (!exactText(record.taskId))
-        reasons.push('taskId');
-    if (!exactText(record.runId))
-        reasons.push('runId');
-    if (!['running', 'paused', 'completed'].includes(record.status))
-        reasons.push('status');
-    if (!(record.nextStage === null || ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code', 'commit'].includes(record.nextStage))) {
-        reasons.push('nextStage');
-    }
-    if (!Number.isSafeInteger(record.stepCount) || record.stepCount < 0)
-        reasons.push('stepCount');
-    if (!Number.isSafeInteger(record.maxSteps) || record.maxSteps < 1)
-        reasons.push('maxSteps');
-    if (!isModelPolicy(record.modelPolicy))
-        reasons.push('modelPolicy');
-    if (!isModelPolicySource(record.modelPolicySource))
-        reasons.push('modelPolicySource');
-    if (!Array.isArray(record.recoveryHistory) || !record.recoveryHistory.every(isRecovery))
-        reasons.push('recoveryHistory');
-    if (typeof record.baseline !== 'string')
-        reasons.push('baseline');
-    if (!(record.pendingDelegation === null || isDelegationReceipt(record.pendingDelegation)))
-        reasons.push('pendingDelegation');
-    if (!Array.isArray(record.receipts) || !record.receipts.every(isDelegationReceipt))
-        reasons.push('receipts');
-    if (!(record.pause === null || isPause(record.pause)))
-        reasons.push('pause');
-    if (!(record.completionEvidence === null || isCompletionEvidence(record.completionEvidence)))
-        reasons.push('completionEvidence');
-    if (!exactText(record.createdAt))
-        reasons.push('createdAt');
-    if (!exactText(record.updatedAt))
-        reasons.push('updatedAt');
-    if (Array.isArray(record.receipts) && record.receipts.every(isDelegationReceipt)
-        && (record.pendingDelegation === null || isDelegationReceipt(record.pendingDelegation))) {
-        const receipts = [...record.receipts, ...(record.pendingDelegation ? [record.pendingDelegation] : [])];
-        if (receipts.some((receipt) => receipt.runId !== record.runId)) {
-            reasons.push('receipt-identity');
-        }
-    }
-    return reasons;
-}
-function emitDiagnostic(options, event, fields) {
-    try {
-        options?.diagnosticLog?.(event, fields);
-    }
-    catch {
-        // Diagnostics must never change lifecycle behavior.
-    }
-}
-function fileObservation(file) {
-    try {
-        const stat = fs.lstatSync(file);
-        let realpath = null;
-        try {
-            realpath = fs.realpathSync.native(file);
-        }
-        catch { /* retain the lstat observation */ }
-        return {
-            file,
-            exists: true,
-            fileType: stat.isFile() ? 'file' : stat.isDirectory() ? 'directory' : 'other',
-            symbolicLink: stat.isSymbolicLink(),
-            bytes: stat.isFile() ? stat.size : null,
-            mtimeMs: stat.mtimeMs,
-            device: stat.dev,
-            inode: stat.ino,
-            realpath
-        };
-    }
-    catch (error) {
-        return {
-            file,
-            exists: false,
-            fileType: null,
-            symbolicLink: null,
-            bytes: null,
-            mtimeMs: null,
-            device: null,
-            inode: null,
-            realpath: null,
-            fsError: error instanceof Error && 'code' in error ? String(error.code) : null
-        };
-    }
-}
-function parseOrchestrationRun(value, expectedTaskId) {
-    const reasonCodes = orchestrationStateReasonCodes(value);
-    if (reasonCodes.length > 0)
-        throw new OrchestrationStateError(expectedTaskId ?? null, reasonCodes);
-    return value;
-}
-function readRun(taskDir, options = {}) {
-    const file = orchestrationPath(taskDir);
-    const taskId = path.basename(taskDir);
-    const observed = options.diagnosticLog ? fileObservation(file) : {};
-    if (!fs.existsSync(file)) {
-        emitDiagnostic(options, 'orchestration-state-missing', { taskId, taskDir, ...observed });
-        return null;
-    }
-    emitDiagnostic(options, 'orchestration-state-read-start', { taskId, taskDir, ...observed });
-    let rawBytes = null;
-    let rawSha256 = null;
-    try {
-        const raw = fs.readFileSync(file, 'utf8');
-        if (options.diagnosticLog) {
-            rawBytes = Buffer.byteLength(raw, 'utf8');
-            rawSha256 = createHash('sha256').update(raw, 'utf8').digest('hex');
-        }
-        const run = parseOrchestrationRun(JSON.parse(raw), taskId);
-        emitDiagnostic(options, 'orchestration-state-read-ok', {
-            taskId, taskDir, file, rawBytes, rawSha256, status: run.status, runId: run.runId,
-            stepCount: run.stepCount, pendingDelegation: run.pendingDelegation !== null
-        });
-        return run;
-    }
-    catch (error) {
-        const reasonCodes = error instanceof OrchestrationStateError && error.reasonCodes.length > 0
-            ? error.reasonCodes
-            : [error instanceof SyntaxError ? 'json-parse' : 'file-read'];
-        emitDiagnostic(options, 'orchestration-state-read-failed', {
-            taskId,
-            taskDir,
-            ...observed,
-            rawBytes,
-            rawSha256,
-            reasonCodes: reasonCodes.join(','),
-            errorType: error instanceof Error ? error.name : typeof error,
-        });
-        throw new OrchestrationStateError(taskId, reasonCodes);
-    }
-}
-function findDelegation(run, receiptId) {
-    if (run.pendingDelegation?.id === receiptId)
-        return { receipt: run.pendingDelegation, location: 'pending' };
-    const receipt = run.receipts.find((entry) => entry.id === receiptId);
-    return receipt ? { receipt, location: 'history' } : null;
-}
-function readDelegationAdapterEvidence(taskRef, receiptId, adapterId, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        throw new Error(`${resolved.code}: ${resolved.message}`);
-    const run = readRun(resolved.taskDir, options);
-    const found = run && findDelegation(run, receiptId);
-    if (!found || found.receipt.client !== adapterId)
-        return null;
-    return found.receipt.adapterEvidence?.[adapterId] ?? null;
-}
-function mutateDelegationAdapterEvidence(taskRef, receiptId, adapterId, mutate, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        throw new Error(`${resolved.code}: ${resolved.message}`);
-    return mutateDelegationAdapterEvidenceAtResolved(resolved, receiptId, adapterId, mutate, options);
-}
-function mutateDelegationAdapterEvidenceAtResolved(resolved, receiptId, adapterId, mutate, options) {
-    const update = () => {
-        try {
-            const run = readRun(resolved.taskDir, options);
-            const found = run && findDelegation(run, receiptId);
-            if (!run || !found || found.receipt.client !== adapterId) {
-                throw new Error('ORCHESTRATION_DELEGATION_MISSING: adapter evidence has no matching task receipt');
-            }
-            const current = found.receipt.adapterEvidence?.[adapterId] ?? null;
-            const nextState = mutate(current);
-            const serialized = JSON.stringify(nextState);
-            if (serialized === undefined)
-                throw new Error('Agent adapter evidence must be JSON serializable');
-            if (serialized === JSON.stringify(current))
-                return JSON.parse(serialized);
-            const adapterEvidence = Object.freeze({
-                ...(found.receipt.adapterEvidence ?? {}),
-                [adapterId]: JSON.parse(serialized)
-            });
-            const nextReceipt = Object.freeze({ ...found.receipt, adapterEvidence });
-            const updated = found.location === 'pending'
-                ? withUpdatedRun(run, { pendingDelegation: nextReceipt }, options.now)
-                : withUpdatedRun(run, {
-                    receipts: Object.freeze(run.receipts.map((receipt) => receipt.id === receiptId ? nextReceipt : receipt))
-                }, options.now);
-            saveRun(resolved.taskDir, updated);
-            return JSON.parse(serialized);
-        }
-        catch (error) {
-            mutationError = error;
-            return null;
-        }
-    };
-    let mutationError;
-    const result = update();
-    if (mutationError)
-        throw mutationError;
-    return result;
-}
-function atomicWrite(file, value) {
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
-    fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
-    fs.renameSync(temp, file);
-}
-function saveRun(taskDir, run) {
-    atomicWrite(orchestrationPath(taskDir), run);
-}
-function withUpdatedRun(run, updates, now) {
-    return Object.freeze({ ...run, ...updates, updatedAt: (now ?? (() => new Date().toISOString()))() });
-}
-function failed(code, message, taskId = null, details = {}) {
-    return { status: 'failed', changed: false, taskId, run: null, next: null, error: { code, message, ...details } };
-}
-function gitRootFor(stateRoot, options) {
-    if (!options.gitWorktreeRoot)
-        return stateRoot;
-    return assertGitRepositoryBinding(stateRoot, options.gitWorktreeRoot).worktreeRoot;
-}
-function validModel(value) {
-    return typeof value === 'string' && value.length > 0 && value.trim() === value;
-}
-function validateModelPolicy(policy) {
-    if (!policy
-        || !validModel(policy.executor?.model)
-        || !validModel(policy.executor?.reasoningEffort)
-        || !validModel(policy.reviewer?.model)
-        || !validModel(policy.reviewer?.reasoningEffort)) {
-        return { code: 'ORCHESTRATION_MODEL_POLICY_REQUIRED', message: 'executor and reviewer model and reasoning effort are required' };
-    }
-    return null;
-}
-function sameModelPolicy(left, right) {
-    return left.executor.model === right.executor.model
-        && left.executor.reasoningEffort === right.executor.reasoningEffort
-        && left.reviewer.model === right.reviewer.model
-        && left.reviewer.reasoningEffort === right.reviewer.reasoningEffort;
-}
-function rolePolicy(run, role) {
-    return run.modelPolicy[role];
-}
-function resolveProjectPolicy(repoRoot, client) {
-    const configPath = path.join(repoRoot, '.agents', '.airc.json');
-    if (!fs.existsSync(configPath))
-        return undefined;
-    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    return normalizeAgentClients(raw).state[client].orchestration;
-}
-function canRecoverUnsupportedClientPause(run) {
-    return run.status === 'paused'
-        && run.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
-        && isAgentClientId(run.modelPolicySource?.client)
-        && supportsLifecycleDelegation(run.modelPolicySource.client)
-        && run.stepCount === 0
-        && run.nextStage === null
-        && run.baseline === ''
-        && run.pendingDelegation === null
-        && run.receipts.length === 0
-        && run.completionEvidence == null
-        && run.recoveryHistory.length === 0;
-}
-function beginOrResumeOrchestration(taskRef, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    if (!isAgentClientId(options.client)) {
-        return failed('ORCHESTRATION_PAYLOAD_INVALID', 'begin-or-resume requires a known client', resolved.taskId);
-    }
-    let existing;
-    try {
-        existing = readRun(resolved.taskDir, options);
-    }
-    catch (error) {
-        return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
-    }
-    if (existing) {
-        if (existing.status === 'completed') {
-            return { status: 'completed', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
-        }
-        if (existing.modelPolicySource.client !== options.client) {
-            return failed('ORCHESTRATION_CLIENT_MISMATCH', 'provided client does not match the persisted run policy source', resolved.taskId);
-        }
-        if (options.modelPolicy) {
-            const suppliedError = validateModelPolicy(options.modelPolicy);
-            if (suppliedError)
-                return failed(suppliedError.code, suppliedError.message, resolved.taskId);
-            if (!sameModelPolicy(existing.modelPolicy, options.modelPolicy)) {
-                return failed('ORCHESTRATION_MODEL_POLICY_MISMATCH', 'provided model policy does not match the persisted run policy', resolved.taskId);
-            }
-        }
-        if (existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED') {
-            if (!canRecoverUnsupportedClientPause(existing)) {
-                return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
-            }
-            const now = (options.now ?? (() => new Date().toISOString()))();
-            const recovery = {
-                code: 'CLIENT_CAPABILITY_ENABLED',
-                recoveredAt: now,
-                previousStatus: 'paused',
-                previousPause: existing.pause,
-                client: existing.modelPolicySource.client,
-                guards: {
-                    stepCount: 0,
-                    nextStage: null,
-                    baselineEmpty: true,
-                    receiptCount: 0,
-                    pendingDelegation: false,
-                    completionEvidenceAbsent: 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 (existing.status === 'paused' && existing.pause?.recoverable && existing.pendingDelegation === null) {
-            const resumed = withUpdatedRun(existing, { status: 'running', pause: null }, options.now);
-            saveRun(resolved.taskDir, resumed);
-            return { status: 'running', changed: true, taskId: resolved.taskId, run: resumed, next: null, error: null };
-        }
-        return { status: existing.status, changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
-    }
-    let policy = options.modelPolicy;
-    let sourceKind = 'explicit';
-    if (!policy) {
-        try {
-            policy = resolveProjectPolicy(resolved.repoRoot, options.client);
-            sourceKind = 'project-config';
-        }
-        catch (error) {
-            return failed('ORCHESTRATION_CONFIG_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
-        }
-    }
-    const policyError = validateModelPolicy(policy);
-    if (policyError)
-        return failed(policyError.code, policyError.message, resolved.taskId, {
-            client: options.client,
-            missingFields: ['executor.model', 'executor.reasoningEffort', 'reviewer.model', 'reviewer.reasoningEffort'],
-            modelSelectionContext: getAgentClientModelSelection(options.client)
-        });
-    const now = (options.now ?? (() => new Date().toISOString()))();
-    const source = { kind: sourceKind, client: options.client, resolvedAt: now };
-    const run = {
-        taskId: resolved.taskId,
-        runId: (options.id ?? randomUUID)(),
-        status: 'running',
-        nextStage: null,
-        stepCount: 0,
-        maxSteps: options.maxSteps ?? 24,
-        modelPolicy: policy,
-        modelPolicySource: source,
-        recoveryHistory: [],
-        baseline: '',
-        pendingDelegation: null,
-        receipts: [],
-        pause: null,
-        completionEvidence: null,
-        createdAt: now,
-        updatedAt: now
-    };
-    atomicWrite(orchestrationPath(resolved.taskDir), run);
-    return { status: 'running', changed: true, taskId: resolved.taskId, run, next: null, error: null };
-}
-function validateSavedCurrentDiffBase(repoRoot, metadata, taskDir, reviewedHead) {
-    const reviewInventory = inspectArtifactDirectory(taskDir, 'review-code');
-    if (reviewInventory.status !== 'ready' || !reviewInventory.latest) {
-        return { code: 'ORCHESTRATION_REVIEW_INVALID', message: 'latest completed review-code artifact is unavailable' };
-    }
-    const reviewContent = fs.readFileSync(reviewInventory.latest.path, 'utf8');
-    const savedTargetHead = extractReviewTargetHead(reviewContent);
-    const savedDiffBase = extractReviewDiffBase(reviewContent);
-    const savedReviewedHead = extractReviewedHead(reviewContent) || extractReviewBaseline(reviewContent);
-    if (!savedTargetHead && !savedDiffBase && !savedReviewedHead)
-        return null;
-    if (savedReviewedHead && savedReviewedHead !== reviewedHead) {
-        return { code: 'ORCHESTRATION_REVIEWED_HEAD_MISMATCH', message: 'review-code saved reviewed head does not match last_reviewed_commit' };
-    }
-    if (!savedTargetHead || !savedDiffBase) {
-        return { code: 'ORCHESTRATION_REVIEW_TARGET_INVALID', message: 'review-code must save target head and diff base together' };
-    }
-    const savedBase = resolveDiffBase(repoRoot, reviewedHead, savedTargetHead);
-    if (!savedBase.ok)
-        return { code: 'ORCHESTRATION_REVIEW_TARGET_INVALID', message: savedBase.message };
-    if (savedBase.diffBase !== savedDiffBase) {
-        return { code: 'ORCHESTRATION_REVIEW_DIFF_BASE_MISMATCH', message: 'saved review diff base does not match reviewed head and saved target head' };
-    }
-    const target = resolveDeliveryTarget(repoRoot, {
-        remote: typeof metadata.delivery_remote === 'string' ? metadata.delivery_remote : undefined,
-        baseRef: typeof metadata.delivery_base_ref === 'string' ? metadata.delivery_base_ref : undefined
-    });
-    if (!target.ok)
-        return { code: target.code, message: target.message };
-    const currentTarget = resolveTargetHead(repoRoot, target.value);
-    if (!currentTarget.ok)
-        return { code: currentTarget.code, message: currentTarget.message };
-    const currentBase = resolveDiffBase(repoRoot, reviewedHead, currentTarget.head);
-    if (!currentBase.ok)
-        return { code: currentBase.code, message: currentBase.message };
-    if (currentBase.diffBase !== savedDiffBase) {
-        return { code: 'ORCHESTRATION_REVIEW_TARGET_CHANGED', message: 'current delivery target changed the reviewed diff base; re-run review-code' };
-    }
-    return null;
-}
-function routeFromFacts(facts) {
-    const recommendation = recommendNext(facts);
-    if (!recommendation.action)
-        return recommendation.reasonCode === 'LIFECYCLE_REVIEWED' ? { completion: true } : null;
-    const action = recommendation.action;
-    if (action === 'manual-validation' || action === 'validation-run')
-        return null;
-    const command = action === 'analysis' ? 'analyze-task' : action === 'plan' ? 'plan-task' : action === 'code' ? 'code-task' : action;
-    const role = action.startsWith('review-') ? 'reviewer' : 'executor';
-    return { action: command, role, stage: action };
-}
-function routeResolvedTask(taskRef, resolved, options) {
-    let gitRoot;
-    try {
-        gitRoot = gitRootFor(resolved.repoRoot, options);
-    }
-    catch (error) {
-        return failed('ORCHESTRATION_WORKTREE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
-    }
-    let content;
-    try {
-        content = fs.readFileSync(resolved.taskMdPath, 'utf8');
-    }
-    catch (error) {
-        return failed('ORCHESTRATION_TASK_READ_FAILED', String(error), resolved.taskId);
-    }
-    let metadata;
-    let currentLedger = null;
-    if (resolved.state === 'active') {
-        const contract = validateCurrentTaskContract(content);
-        if (!contract.ok)
-            return failed('ORCHESTRATION_CURRENT_CONTRACT_INVALID', contract.message, resolved.taskId);
-        metadata = contract.metadata;
-        currentLedger = contract.ledger;
-    }
-    else {
-        try {
-            metadata = parseTypedTaskFrontmatter(content);
-        }
-        catch (error) {
-            return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
-        }
-    }
-    let run;
-    try {
-        run = readRun(resolved.taskDir, options);
-    }
-    catch (error) {
-        return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
-    }
-    const facts = buildLifecycleFacts(resolved.taskDir, content, resolved.state, hasOpenLifecycleExecution(content) || Boolean(run?.pendingDelegation), resolved.repoRoot);
-    if (!facts.ok)
-        return failed('ORCHESTRATION_CAPABILITY_FACTS_INVALID', facts.message, resolved.taskId);
-    const routed = routeFromFacts(facts.facts);
-    if (!routed)
-        return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
-    if ('completion' in routed) {
-        if (facts.facts.executionBusy && !run?.pendingDelegation) {
-            return failed('ORCHESTRATION_EXECUTION_BUSY', 'clean completion requires no open lifecycle execution', resolved.taskId);
-        }
-        const reviewInventory = inspectArtifactDirectory(resolved.taskDir, 'review-code');
-        if (reviewInventory.status !== 'ready' || !reviewInventory.latest) {
-            return failed('ORCHESTRATION_REVIEW_INVALID', 'latest completed review-code artifact is unavailable', resolved.taskId);
-        }
-        const review = parseReviewSummary(fs.readFileSync(reviewInventory.latest.path, 'utf8'));
-        if (!review.ok || review.summary.manualValidation === null) {
-            return failed('ORCHESTRATION_REVIEW_INVALID', 'latest code review has no numeric manual-validation count', resolved.taskId);
-        }
-        const ledger = currentLedger ?? parseLedgerDocument(content);
-        if (!ledger.present)
-            return failed('ORCHESTRATION_CURRENT_CONTRACT_INVALID', `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`, resolved.taskId);
-        const rows = ledger.rows;
-        const ledgerError = validateLedgerRows(rows);
-        if (ledgerError)
-            return failed('ORCHESTRATION_LEDGER_INVALID', ledgerError.message, resolved.taskId);
-        if (!summarizeLedgerStage(rows, 'code').canAdvance) {
-            return failed('ORCHESTRATION_LEDGER_BLOCKED', 'code review ledger has unresolved findings or human decisions', resolved.taskId);
-        }
-        if (run?.status === 'completed') {
-            return { status: 'completed', changed: false, taskId: resolved.taskId, run, next: null, error: null };
-        }
-        if (!run) {
-            return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
-        }
-        if (run.status !== 'running' || run.pendingDelegation !== null) {
-            return failed('ORCHESTRATION_RUN_NOT_RUNNING', 'clean completion requires an idle running orchestration', resolved.taskId);
-        }
-        const capture = options.captureRepository ?? captureRepositorySnapshot;
-        let before;
-        try {
-            before = capture(gitRoot);
-        }
-        catch (error) {
-            return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
-        }
-        if (before.headTree !== before.worktreeTree) {
-            return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
-        }
-        const lastReviewedCommit = String(metadata.last_reviewed_commit ?? '');
-        if (before.head !== lastReviewedCommit) {
-            return failed('ORCHESTRATION_REVIEWED_HEAD_MISMATCH', 'local HEAD does not match last_reviewed_commit', resolved.taskId);
-        }
-        const diffBaseError = validateSavedCurrentDiffBase(resolved.repoRoot, metadata, resolved.taskDir, lastReviewedCommit);
-        if (diffBaseError)
-            return failed(diffBaseError.code, diffBaseError.message, resolved.taskId);
-        let after;
-        try {
-            after = capture(gitRoot);
-        }
-        catch (error) {
-            return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
-        }
-        if (after.headTree !== after.worktreeTree) {
-            return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
-        }
-        if (after.head !== before.head || after.headTree !== before.headTree) {
-            return failed('ORCHESTRATION_REPOSITORY_CHANGED', 'repository changed while clean completion evidence was collected', resolved.taskId);
-        }
-        const observedAt = (options.now ?? (() => new Date().toISOString()))();
-        const completionEvidence = {
-            kind: 'reviewed-head-clean',
-            observedAt,
-            head: after.head,
-            headTree: after.headTree,
-            worktreeTree: after.worktreeTree,
-            lastReviewedCommit,
-            prNumber: null,
-            prHead: null
-        };
-        const completed = withUpdatedRun(run, {
-            status: 'completed',
-            nextStage: null,
-            pause: null,
-            completionEvidence
-        });
-        saveRun(resolved.taskDir, completed);
-        return { status: 'completed', changed: true, taskId: resolved.taskId, run: completed, next: null, error: null };
-    }
-    const action = routed.stage;
-    const family = action === 'analysis' ? 'analysis' : action;
-    const artifactContext = resolveArtifactContextForResolvedTask(resolved, family, {
-        repoRoot: resolved.repoRoot
-    });
-    if (artifactContext.status !== 'ready' || !artifactContext.selection) {
-        return failed(artifactContext.error?.code ?? 'ORCHESTRATION_ARTIFACT_SELECTION_FAILED', artifactContext.error?.message ?? 'cannot determine artifact selection', resolved.taskId);
-    }
-    if (artifactContext.selection.disposition === 'reuse') {
-        return failed('ORCHESTRATION_REUSE_STALLED', `lifecycle still routes to ${action} after reusing ${artifactContext.selection.artifact.name}`, resolved.taskId);
-    }
-    const selected = artifactContext.selection.artifact;
-    const capability = canStart(action, facts.facts, {
-        initiator: 'orchestrator', requestId: `orchestration:${resolved.taskId}:${routed.stage}:${selected.round}`,
-        requestedAction: action, reasonCode: 'user-request', explicitRequest: true
-    });
-    if (!capability.allowed)
-        return failed('ORCHESTRATION_CAPABILITY_DENIED', `${capability.reasonCode}: ${capability.evidence.join(', ')}`, resolved.taskId);
-    const policy = run ? rolePolicy(run, routed.role) : null;
-    const next = {
-        ...routed,
-        round: selected.round,
-        artifact: selected.name,
-        requestedModel: policy?.model ?? null,
-        requestedReasoningEffort: policy?.reasoningEffort ?? null
-    };
-    return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
-}
-function routeOrchestration(taskRef, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    return routeResolvedTask(taskRef, resolved, options);
-}
-function statusOrchestration(taskRef, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir, options);
-    if (!run)
-        return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
-    return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
-}
-function validatePreparedModelPolicy(taskId, run, next, input) {
-    if (!validModel(input.requestedModel)) {
-        return failed('ORCHESTRATION_REQUESTED_MODEL_REQUIRED', 'prepare requires the exact requested model identity', taskId);
-    }
-    if (!validModel(input.requestedReasoningEffort)) {
-        return failed('ORCHESTRATION_REQUESTED_REASONING_EFFORT_REQUIRED', 'prepare requires the exact requested reasoning effort', taskId);
-    }
-    const expectedPolicy = run.modelPolicy[next.role];
-    if (input.requestedModel !== expectedPolicy.model) {
-        return failed('ORCHESTRATION_REQUESTED_MODEL_MISMATCH', `requested model does not match the persisted ${next.role} model`, taskId);
-    }
-    if (input.requestedReasoningEffort !== expectedPolicy.reasoningEffort) {
-        return failed('ORCHESTRATION_REQUESTED_REASONING_EFFORT_MISMATCH', `requested reasoning effort does not match the persisted ${next.role} policy`, taskId);
-    }
-    return null;
-}
-function captureTaskSnapshot(taskId, repoRoot, options) {
-    return (options.captureWorkspace ?? captureWorkspaceSnapshot)({
-        gitRoot: gitRootFor(repoRoot, options),
-        stateRoot: repoRoot,
-        taskId
-    });
-}
-function validateDelegationRun(taskRef, taskId, run, options) {
-    if (!run || run.status !== 'running') {
-        return failed('ORCHESTRATION_RUN_NOT_RUNNING', 'a running orchestration is required', taskId);
-    }
-    if (run.pendingDelegation)
-        return failed('ORCHESTRATION_DELEGATION_BUSY', 'the run already has a pending delegation', taskId);
-    if (run.stepCount >= run.maxSteps) {
-        return pauseOrchestration(taskRef, 'ORCHESTRATION_MAX_STEPS', 'maximum orchestration steps reached', true, options);
-    }
-    return null;
-}
-function prepareOrchestrationDelegation(taskRef, input, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    if (!(options.supportsLifecycleDelegation ?? supportsLifecycleDelegation)(input.client)) {
-        return failed('ORCHESTRATION_CLIENT_UNSUPPORTED', `client '${input.client}' does not support lifecycle orchestration`, resolved.taskId);
-    }
-    emitDiagnostic(options, 'orchestration-prepare-start', {
-        taskId: resolved.taskId,
-        taskDir: resolved.taskDir,
-        repoRoot: resolved.repoRoot,
-        client: input.client,
-        requestedModel: input.requestedModel ?? null,
-        requestedReasoningEffort: input.requestedReasoningEffort ?? null
-    });
-    const run = readRun(resolved.taskDir, options);
-    const runFailure = validateDelegationRun(taskRef, resolved.taskId, run, options);
-    if (runFailure)
-        return runFailure;
-    const activeRun = run;
-    const routed = routeResolvedTask(taskRef, resolved, options);
-    if (!routed.next)
-        return routed;
-    const next = routed.next;
-    const policyFailure = validatePreparedModelPolicy(resolved.taskId, activeRun, next, input);
-    if (policyFailure)
-        return policyFailure;
-    let beforeFingerprint;
-    try {
-        beforeFingerprint = captureTaskSnapshot(resolved.taskId, resolved.repoRoot, options);
-    }
-    catch (error) {
-        return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
-    }
-    const receipt = prepareDelegation({
-        taskId: resolved.taskId,
-        runId: activeRun.runId,
-        role: next.role,
-        stage: next.stage,
-        round: next.round,
-        artifact: next.artifact,
-        client: input.client,
-        requestedModel: input.requestedModel,
-        requestedReasoningEffort: input.requestedReasoningEffort,
-        workspaceSnapshotScope: 'task',
-        beforeFingerprint
-    }, { id: options.id, now: options.now, monotonicNow: options.monotonicNow });
-    const updated = withUpdatedRun(activeRun, {
-        nextStage: next.stage,
-        pendingDelegation: receipt
-    });
-    saveRun(resolved.taskDir, updated);
-    return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next, error: null };
-}
-function dispatchOrchestrationDelegation(taskRef, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir, options);
-    if (!run?.pendingDelegation)
-        return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
-    if (run.status !== 'running') {
-        return failed('ORCHESTRATION_STATE_INVALID', 'spawn dispatch requires a running orchestration', resolved.taskId);
-    }
-    const result = dispatchDelegation(run.pendingDelegation, {
-        now: options.now,
-        monotonicNow: options.monotonicNow
-    });
-    if (!result.ok)
-        return pauseOrchestration(taskRef, result.code, result.message, true, options);
-    const updated = withUpdatedRun(run, { pendingDelegation: result.receipt });
-    saveRun(resolved.taskDir, updated);
-    return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
-}
-function matchingDelegations(predicate, options) {
-    const taskId = options.taskId;
-    if (taskId === undefined || taskId === '') {
-        return { ok: false, error: failed('ORCHESTRATION_TASK_ID_REQUIRED', 'taskId is required for lifecycle matching') };
-    }
-    if (typeof taskId !== 'string' || !TASK_ID_RE.test(taskId)) {
-        return { ok: false, error: failed('ORCHESTRATION_TASK_ID_INVALID', 'taskId must be a canonical TASK-id') };
-    }
-    const repoRoot = options.repoRoot ?? process.cwd();
-    const taskDir = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', taskId);
-    const run = readRun(taskDir, options);
-    const matches = run && run.status === 'running' && run.pendingDelegation && predicate(run.pendingDelegation)
-        ? [{ taskId, run }]
-        : [];
-    return { ok: true, matches };
-}
-function uniqueMatchingDelegation(client, predicate, options) {
-    const lookup = matchingDelegations((receipt) => receipt.client === client && predicate(receipt), options);
-    if (!lookup.ok)
-        return lookup.error;
-    const matches = lookup.matches;
-    if (matches.length === 0)
-        return failed('ORCHESTRATION_DELEGATION_MISSING', 'no matching lifecycle delegation exists');
-    return matches[0];
-}
-function hasActivatableOrchestrationDelegation(client, childId, options = {}) {
-    const lookup = matchingDelegations((receipt) => receipt.client === client && (receipt.status === 'prepared'
-        || (receipt.childId === childId && ['activated', 'stage-completed'].includes(receipt.status))), options);
-    return lookup.ok && lookup.matches.length > 0;
-}
-function hasSealableOrchestrationDelegation(client, childId, options = {}) {
-    const lookup = matchingDelegations((receipt) => receipt.client === client
-        && receipt.childId === childId
-        && ['stage-completed', 'sealed'].includes(receipt.status), options);
-    return lookup.ok && lookup.matches.length > 0;
-}
-function activateMatchingOrchestrationDelegation(client, event, options = {}) {
-    const role = managedDelegationRole(event.nativeAgent);
-    if (!role)
-        return failed('DELEGATION_IGNORED', `subagent '${event.nativeAgent}' is not lifecycle-managed`);
-    const matched = uniqueMatchingDelegation(client, (receipt) => receipt.status === 'prepared', options);
-    if ('status' in matched) {
-        if (matched.error?.code !== 'ORCHESTRATION_DELEGATION_MISSING')
-            return matched;
-        const replay = uniqueMatchingDelegation(client, (receipt) => receipt.childId === event.childId && ['activated', 'stage-completed'].includes(receipt.status), options);
-        if ('status' in replay)
-            return matched;
-        const receipt = replay.run.pendingDelegation;
-        const sameEvidence = receipt.parentId === event.parentId
-            && (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)
-            && (event.clientEvidence === undefined
-                || JSON.stringify(receipt.adapterEvidence?.[client]) === JSON.stringify(event.clientEvidence));
-        if (!sameEvidence) {
-            return pauseOrchestration(replay.taskId, 'DELEGATION_REPLAY_CONFLICT', 'replayed native start evidence conflicts with the active receipt', true, options);
-        }
-        return { status: replay.run.status, changed: false, taskId: replay.taskId, run: replay.run, next: null, error: null };
-    }
-    if (matched.run.receipts.some((receipt) => receipt.childId === event.childId)) {
-        return pauseOrchestration(matched.taskId, 'DELEGATION_IDENTITY_REUSED', 'native child identity was already used by this run', true, options);
-    }
-    return activateOrchestrationDelegation(matched.taskId, event, options);
-}
-function pauseMatchingOrchestrationDelegation(client, code, message, options = {}) {
-    const matched = uniqueMatchingDelegation(client, () => true, options);
-    if ('status' in matched)
-        return matched;
-    return pauseOrchestration(matched.taskId, code, message, true, options);
-}
-function sealMatchingOrchestrationDelegation(client, event, options = {}, beforeSeal) {
-    const role = managedDelegationRole(event.nativeAgent);
-    if (!role)
-        return failed('DELEGATION_IGNORED', `subagent '${event.nativeAgent}' is not lifecycle-managed`);
-    const matched = uniqueMatchingDelegation(client, (receipt) => receipt.status !== 'prepared', options);
-    if ('status' in matched)
-        return matched;
-    const receipt = matched.run.pendingDelegation;
-    if (receipt.role !== role) {
-        return pauseOrchestration(matched.taskId, 'DELEGATION_ROLE_MISMATCH', `managed role ${role} does not match ${receipt.role}`, true, options);
-    }
-    const repoRoot = options.repoRoot ?? process.cwd();
-    try {
-        const gitRoot = gitRootFor(repoRoot, options);
-        const snapshotTaskId = receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null;
-        const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
-            gitRoot,
-            stateRoot: repoRoot,
-            taskId: snapshotTaskId
-        });
-        const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(gitRoot, receipt.beforeFingerprint, afterFingerprint);
-        return sealOrchestrationDelegation(matched.taskId, {
-            childId: event.childId,
-            exitCode: 0,
-            afterFingerprint,
-            changedPaths,
-            actualModel: event.actualModel,
-            actualReasoningEffort: event.actualReasoningEffort,
-            modelFallbackReason: event.modelFallbackReason,
-            reasoningEffortFallbackReason: event.reasoningEffortFallbackReason
-        }, { runId: receipt.runId, receiptId: receipt.id }, options, beforeSeal);
-    }
-    catch (error) {
-        return pauseOrchestration(matched.taskId, 'ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), true, options);
-    }
-}
-function reconcileMatchingOrchestrationDelegation(client, childId, options = {}) {
-    const matched = uniqueMatchingDelegation(client, (receipt) => receipt.childId === childId, options);
-    if ('status' in matched)
-        return matched;
-    const receipt = matched.run.pendingDelegation;
-    if (receipt.status !== 'sealed' || receipt.childId !== childId) {
-        return pauseOrchestration(matched.taskId, 'ORCHESTRATION_DELEGATION_RECONCILIATION_FAILED', 'native child did not produce one sealed delegation receipt', true, options);
-    }
-    return { status: matched.run.status, changed: false, taskId: matched.taskId, run: matched.run, next: null, error: null };
-}
-function activateOrchestrationDelegation(taskRef, event, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir, options);
-    if (!run?.pendingDelegation)
-        return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
-    if (run.status !== 'running') {
-        return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
-    }
-    const validateAdapterEvidence = getAgentClientAdapter(run.pendingDelegation.client)
-        .orchestrationAdapter?.validateActivationEvidence;
-    if (validateAdapterEvidence && !validateAdapterEvidence(event.clientEvidence, event.parentId)) {
-        return pauseOrchestration(taskRef, 'DELEGATION_ADAPTER_EVIDENCE_REQUIRED', 'native activation lacks valid evidence from the agent adapter', true, options);
-    }
-    const result = activateDelegation(run.pendingDelegation, event, {
-        now: options.now,
-        monotonicNow: options.monotonicNow,
-        evidencePolicy: getAgentClientDelegationEvidence(run.pendingDelegation.client)
-    });
-    if (!result.ok) {
-        if (result.code === 'DELEGATION_IGNORED')
-            return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
-        return pauseOrchestration(taskRef, result.code, result.message, true, options);
-    }
-    const updated = withUpdatedRun(run, { pendingDelegation: result.receipt });
-    saveRun(resolved.taskDir, updated);
-    return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
-}
-async function awaitOrchestrationDelegationActivation(taskRef, event, options = {}) {
-    const sleep = options.sleep
-        ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
-    while (true) {
-        const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-        if (!resolved.ok)
-            return failed(resolved.code, resolved.message, resolved.taskId);
-        const run = readRun(resolved.taskDir, options);
-        if (!run?.pendingDelegation) {
-            return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
-        }
-        const receipt = run.pendingDelegation;
-        const matches = receipt.stage === event.stage
-            && receipt.round === event.round
-            && receipt.artifact === event.artifact
-            && receipt.role === event.role;
-        if (!matches) {
-            return pauseOrchestration(taskRef, 'ORCHESTRATION_PROVENANCE_MISMATCH', 'activation barrier identity does not match the pending delegation', true, options);
-        }
-        if (receipt.status === 'activated' || receipt.status === 'stage-completed') {
-            return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
-        }
-        if (run.status !== 'running') {
-            return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
-        }
-        if (receipt.status !== 'prepared') {
-            return pauseOrchestration(taskRef, 'ORCHESTRATION_ACTIVATION_STATE_INVALID', `activation barrier found receipt status '${receipt.status}'`, true, options);
-        }
-        if (receipt.activationDeadlineAt == null
-            || !Number.isFinite(Date.parse(receipt.activationDeadlineAt))) {
-            return pauseOrchestration(taskRef, 'ORCHESTRATION_DELEGATION_NOT_DISPATCHED', 'activation barrier was entered before the native spawn dispatch boundary', true, options);
-        }
-        if (Date.parse((options.now ?? (() => new Date().toISOString()))()) >= Date.parse(receipt.activationDeadlineAt)) {
-            return pauseOrchestration(taskRef, 'ORCHESTRATION_ACTIVATION_TIMEOUT', 'fresh child did not receive trusted activation evidence before the deadline', true, options);
-        }
-        await sleep(100);
-    }
-}
-function recoverPreparedOrchestrationDelegation(taskRef, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    try {
-        return (() => {
-            const run = readRun(resolved.taskDir, options);
-            const receipt = run?.pendingDelegation;
-            if (!run || !receipt) {
-                return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
-            }
-            if (receipt.status !== 'prepared') {
-                return failed('ORCHESTRATION_PREPARED_RECOVERY_UNSAFE', 'only a never-activated prepared receipt can recover', resolved.taskId);
-            }
-            const wallNow = Date.parse((options.now ?? (() => new Date().toISOString()))());
-            if (receipt.activationDeadlineAt != null
-                && Number.isFinite(Date.parse(receipt.activationDeadlineAt))
-                && wallNow <= Date.parse(receipt.activationDeadlineAt)) {
-                return failed('ORCHESTRATION_PREPARED_RECOVERY_EARLY', 'prepared receipt activation deadline has not elapsed', resolved.taskId);
-            }
-            const activeAdapterEvidence = options.hasActiveLifecycleEvidence?.(receipt)
-                ?? Object.keys(receipt.adapterEvidence ?? {}).length > 0;
-            if (activeAdapterEvidence) {
-                return failed('ORCHESTRATION_PREPARED_RECOVERY_ACTIVE_EVIDENCE', 'active agent adapter evidence blocks prepared receipt recovery', resolved.taskId);
-            }
-            const current = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
-                gitRoot: gitRootFor(resolved.repoRoot, options),
-                stateRoot: resolved.repoRoot,
-                taskId: receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null
-            });
-            if (current !== receipt.beforeFingerprint) {
-                return failed('ORCHESTRATION_PREPARED_RECOVERY_DRIFT', 'workspace changed after delegation preparation', resolved.taskId);
-            }
-            const aborted = abortPreparedDelegation(receipt);
-            if (!aborted.ok)
-                return failed(aborted.code, aborted.message, resolved.taskId);
-            const updated = withUpdatedRun(run, {
-                status: 'running',
-                pause: null,
-                nextStage: null,
-                pendingDelegation: null,
-                receipts: Object.freeze([...run.receipts, aborted.receipt])
-            }, options.now);
-            saveRun(resolved.taskDir, updated);
-            return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
-        })();
-    }
-    catch (error) {
-        return failed('ORCHESTRATION_PREPARED_RECOVERY_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
-    }
-}
-function recoveryReceiptMatches(receipt, event) {
-    return receipt.stage === event.stage
-        && receipt.round === event.round
-        && receipt.artifact === event.artifact
-        && receipt.childId === event.childId
-        && normalizeAgentToken(event.startedAgent) === normalizeAgentToken(receipt.client);
-}
-function recoverActivatedOrchestrationDelegation(taskRef, event, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir, options);
-    if (!run)
-        return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
-    const matches = [
-        ...(run.pendingDelegation ? [run.pendingDelegation] : []),
-        ...run.receipts.filter((receipt) => receipt.id === event.receiptId)
-    ];
-    const receipt = matches.find((candidate) => candidate.id === event.receiptId);
-    if (!receipt)
-        return failed('ORCHESTRATION_DELEGATION_MISSING', 'recovery receipt does not exist', resolved.taskId);
-    if (!recoveryReceiptMatches(receipt, event)) {
-        return failed('ORCHESTRATION_PROVENANCE_MISMATCH', 'recovery selector does not match the delegation receipt', resolved.taskId);
-    }
-    if (receipt.status === 'aborted' && run.pendingDelegation === null) {
-        return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
-    }
-    if (run.pendingDelegation?.id !== receipt.id || receipt.status !== 'activated') {
-        return failed('ORCHESTRATION_RECOVERY_UNSAFE', 'recovery requires one matching activated pending delegation', resolved.taskId);
-    }
-    if (run.receipts.some((candidate) => candidate.id === receipt.id)) {
-        return failed('ORCHESTRATION_RECEIPT_DUPLICATE', 'recovery receipt already exists in the completed receipt history', resolved.taskId);
-    }
-    if (run.status !== 'running' || run.pause !== null) {
-        return failed('ORCHESTRATION_RECOVERY_UNSAFE', 'activated recovery cannot replace an unrelated orchestration pause', resolved.taskId);
-    }
-    const aborted = abortActivatedDelegation(receipt, {
-        childId: event.childId,
-        clientEvidence: event.clientEvidence
-    });
-    if (!aborted.ok)
-        return failed(aborted.code, aborted.message, resolved.taskId);
-    const updated = withUpdatedRun(run, {
-        status: 'running',
-        pause: null,
-        nextStage: null,
-        pendingDelegation: null,
-        receipts: Object.freeze([...run.receipts, aborted.receipt])
-    }, options.now);
-    saveRun(resolved.taskDir, updated);
-    return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
-}
-function completeOrchestrationStage(taskRef, event, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir, options);
-    if (!run)
-        return { status: 'running', changed: false, taskId: resolved.taskId, run: null, next: null, error: null };
-    if (!run.pendingDelegation)
-        return failed('ORCHESTRATION_DELEGATION_MISSING', 'active run has no pending delegation', resolved.taskId);
-    const result = completeDelegationStage(run.pendingDelegation, event);
-    if (!result.ok)
-        return pauseOrchestration(taskRef, result.code, result.message, true, options);
-    const updated = withUpdatedRun(run, { pendingDelegation: result.receipt });
-    saveRun(resolved.taskDir, updated);
-    return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
-}
-function inspectOrchestrationStage(taskRef, event, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    let run;
-    try {
-        run = readRun(resolved.taskDir, options);
-    }
-    catch (error) {
-        return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
-    }
-    if (!run)
-        return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
-    const receipt = run.pendingDelegation;
-    if (!receipt
-        || receipt.status !== 'activated'
-        || receipt.stage !== event.stage
-        || receipt.round !== event.round
-        || receipt.artifact !== event.artifact
-        || receipt.role !== event.role) {
-        return failed('ORCHESTRATION_PROVENANCE_MISMATCH', 'active run does not have one matching activated delegation', resolved.taskId);
-    }
-    return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
-}
-function planOrchestrationStageCompletion(taskRef, event, options = {}) {
-    const inspected = inspectOrchestrationStage(taskRef, event, options);
-    if (inspected.status === 'failed' || !inspected.run?.pendingDelegation) {
-        return { result: inspected, plan: null };
-    }
-    const receipt = inspected.run.pendingDelegation;
-    const completed = completeDelegationStage(receipt, event);
-    if (!completed.ok) {
-        return { result: failed(completed.code, completed.message, inspected.taskId), plan: null };
-    }
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return { result: failed(resolved.code, resolved.message, resolved.taskId), plan: null };
-    const updatedRun = withUpdatedRun(inspected.run, { pendingDelegation: completed.receipt }, options.now);
-    return {
-        result: { status: 'running', changed: true, taskId: resolved.taskId, run: updatedRun, next: null, error: null },
-        plan: {
-            taskId: resolved.taskId,
-            taskDir: resolved.taskDir,
-            updatedRun
-        }
-    };
-}
-function commitOrchestrationStageCompletion(plan) {
-    saveRun(plan.taskDir, plan.updatedRun);
-}
-function sealOrchestrationDelegation(taskRef, event, expected, options = {}, beforeSeal) {
-    const orchestrationOptions = options;
-    const resolved = resolveTaskRef(taskRef, { repoRoot: orchestrationOptions.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    return (() => {
-        const run = readRun(resolved.taskDir, orchestrationOptions);
-        if (!run?.pendingDelegation)
-            return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
-        if (expected && (run.runId !== expected.runId || run.pendingDelegation.id !== expected.receiptId)) {
-            return failed('ORCHESTRATION_DELEGATION_CHANGED', 'pending delegation changed while collecting completion evidence', resolved.taskId);
-        }
-        const preSealFailure = beforeSeal?.();
-        if (preSealFailure)
-            return preSealFailure;
-        const current = beforeSeal ? readRun(resolved.taskDir, orchestrationOptions) : run;
-        if (!current?.pendingDelegation)
-            return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
-        if (expected && (current.runId !== expected.runId || current.pendingDelegation.id !== expected.receiptId)) {
-            return failed('ORCHESTRATION_DELEGATION_CHANGED', 'pending delegation changed before it was sealed', resolved.taskId);
-        }
-        const result = sealDelegation(current.pendingDelegation, event, { now: orchestrationOptions.now });
-        if (!result.ok)
-            return pauseOrchestration(taskRef, result.code, result.message, true, orchestrationOptions);
-        const updated = withUpdatedRun(current, { pendingDelegation: result.receipt });
-        saveRun(resolved.taskDir, updated);
-        return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
-    })();
-}
-function advanceOrchestration(taskRef, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir, options);
-    if (!run?.pendingDelegation)
-        return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
-    const result = consumeDelegation(run.pendingDelegation, { now: options.now });
-    if (!result.ok)
-        return pauseOrchestration(taskRef, result.code, result.message, true, options);
-    if (result.receipt.stage === 'commit') {
-        return failed('ORCHESTRATED_COMMIT_REMOVED', 'Orchestrated commit is no longer a lifecycle stage; use local checkpoint delivery from code-task', resolved.taskId);
-    }
-    const updated = withUpdatedRun(run, {
-        status: 'running',
-        nextStage: null,
-        stepCount: run.stepCount + 1,
-        pendingDelegation: null,
-        receipts: Object.freeze([...run.receipts, result.receipt])
-    });
-    saveRun(resolved.taskDir, updated);
-    return { status: updated.status, changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
-}
-function pauseOrchestration(taskRef, code, message, recoverable, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir, options);
-    if (!run)
-        return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
-    const updated = withUpdatedRun(run, { status: 'paused', pause: { code, message, recoverable } });
-    saveRun(resolved.taskDir, updated);
-    return { status: 'paused', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
-}
-export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, awaitOrchestrationDelegationActivation, advanceOrchestration, beginOrResumeOrchestration, commitOrchestrationStageCompletion, completeOrchestrationStage, dispatchOrchestrationDelegation, inspectOrchestrationStage, hasActivatableOrchestrationDelegation, hasSealableOrchestrationDelegation, OrchestrationStateError, orchestrationPath, readDelegationAdapterEvidence, mutateDelegationAdapterEvidence, pauseMatchingOrchestrationDelegation, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, reconcileMatchingOrchestrationDelegation, recoverPreparedOrchestrationDelegation, recoverActivatedOrchestrationDelegation, routeOrchestration, sealMatchingOrchestrationDelegation, sealOrchestrationDelegation, statusOrchestration, };
-//# sourceMappingURL=orchestration.js.map