@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/dist/lib/task/orchestration.js

@@ -0,0 +1,784 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parseTypedTaskFrontmatter } from './frontmatter.js';
+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, completeDelegationStage, consumeDelegation, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
+import { normalizeAgentClients } from '../agent-clients/config.js';
+import { inspectPlatformPullRequest } from '../platform/pull-requests.js';
+import { getAgentClientCapability, getAgentClientDelegationEvidence, getAgentClientModelSelection } from '../agent-clients/registry.js';
+import { isAgentClientId } from '../agent-clients/types.js';
+import { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots } from './workspace-snapshot.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.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, 'orchestration.json');
+}
+function readRun(taskDir) {
+    const file = orchestrationPath(taskDir);
+    if (!fs.existsSync(file))
+        return null;
+    const run = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (run.schemaVersion !== 2 || !isV2Policy(run.modelPolicy))
+        return run;
+    return {
+        ...run,
+        modelPolicy: {
+            executor: {
+                model: run.modelPolicy.executor.model,
+                reasoningEffort: run.modelPolicy.executor.reasoningEffort
+            },
+            reviewer: {
+                model: run.modelPolicy.reviewer.model,
+                reasoningEffort: run.modelPolicy.reviewer.reasoningEffort
+            }
+        }
+    };
+}
+function atomicWrite(file, value) {
+    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) {
+    return Object.freeze({ ...run, ...updates, updatedAt: 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 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 isV2Policy(policy) {
+    return typeof policy?.executor === 'object' && typeof policy?.reviewer === 'object';
+}
+function rolePolicy(run, role) {
+    return isV2Policy(run.modelPolicy) ? run.modelPolicy[role] : null;
+}
+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 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);
+    }
+    catch (error) {
+        return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    if (existing) {
+        if (![1, 2].includes(existing.schemaVersion)
+            || !Array.isArray(existing.receipts)
+            || !Object.prototype.hasOwnProperty.call(existing, 'pendingDelegation')) {
+            return failed('ORCHESTRATION_STATE_INVALID', 'orchestration state has an invalid schema', resolved.taskId);
+        }
+        if (existing.status === 'completed' && existing.schemaVersion === 1) {
+            return { status: 'completed', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+        }
+        if (existing.schemaVersion === 2) {
+            const policyError = validateModelPolicy(isV2Policy(existing.modelPolicy) ? existing.modelPolicy : undefined);
+            if (policyError
+                || !existing.modelPolicySource
+                || !isAgentClientId(existing.modelPolicySource.client)
+                || !Array.isArray(existing.recoveryHistory)) {
+                return failed('ORCHESTRATION_STATE_INVALID', 'schemaVersion 2 orchestration state is incomplete', resolved.taskId);
+            }
+            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?.recoverable && existing.pendingDelegation === null) {
+                const resumed = withUpdatedRun(existing, { status: 'running', pause: null });
+                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)
+            });
+        }
+        if (existing.pendingDelegation !== null) {
+            const alreadyPaused = existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_DELEGATION_BUSY';
+            if (alreadyPaused)
+                return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+            const paused = withUpdatedRun(existing, {
+                status: 'paused',
+                pause: { code: 'ORCHESTRATION_DELEGATION_BUSY', message: 'legacy run has a pending delegation', recoverable: false }
+            });
+            saveRun(resolved.taskDir, paused);
+            return { status: 'paused', changed: true, taskId: resolved.taskId, run: paused, next: null, error: null };
+        }
+        if (existing.receipts.length > 0) {
+            const alreadyPaused = existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_HISTORICAL_EFFORT_UNVERIFIED';
+            if (alreadyPaused)
+                return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+            const paused = withUpdatedRun(existing, {
+                status: 'paused',
+                pause: {
+                    code: 'ORCHESTRATION_HISTORICAL_EFFORT_UNVERIFIED',
+                    message: 'legacy receipts do not contain actual reasoning-effort evidence',
+                    recoverable: false
+                }
+            });
+            saveRun(resolved.taskDir, paused);
+            return { status: 'paused', changed: true, taskId: resolved.taskId, run: paused, next: null, error: null };
+        }
+        if (existing.modelPolicy
+            && typeof existing.modelPolicy.executor === 'string'
+            && (existing.modelPolicy.executor !== policy.executor.model
+                || existing.modelPolicy.reviewer !== policy.reviewer.model)) {
+            return failed('ORCHESTRATION_MODEL_POLICY_MISMATCH', 'provided model policy does not match the persisted run policy', resolved.taskId);
+        }
+        const now = (options.now ?? (() => new Date().toISOString()))();
+        const source = { kind: sourceKind, client: options.client, resolvedAt: now };
+        const clearsModelPause = existing.pause?.code === 'ORCHESTRATION_MODEL_EVIDENCE_MISSING';
+        const resultingStatus = clearsModelPause ? 'running' : existing.status;
+        const recovery = {
+            code: 'MODEL_POLICY_SUPPLEMENTED',
+            recoveredAt: now,
+            previousSchemaVersion: 1,
+            previousStatus: existing.status,
+            previousPause: existing.pause,
+            policySource: source,
+            receiptCount: 0,
+            pendingDelegation: false,
+            resultingStatus
+        };
+        const recovered = Object.freeze({
+            ...existing,
+            schemaVersion: 2,
+            status: resultingStatus,
+            modelPolicy: policy,
+            modelPolicySource: source,
+            recoveryHistory: Object.freeze([recovery]),
+            pause: clearsModelPause ? null : existing.pause,
+            updatedAt: now
+        });
+        saveRun(resolved.taskDir, recovered);
+        return { status: resultingStatus, changed: true, taskId: resolved.taskId, run: recovered, 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 = {
+        schemaVersion: 2,
+        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,
+        commitAuthorization: { issuedAt: null, consumedAt: 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 highestRound(taskDir, family) {
+    const pattern = new RegExp(`^${family}(?:-r(\\d+))?\\.md$`);
+    return fs.readdirSync(taskDir).reduce((max, name) => {
+        const match = pattern.exec(name);
+        return match ? Math.max(max, match[1] ? Number(match[1]) : 1) : max;
+    }, 0);
+}
+function artifactName(family, round) {
+    return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
+}
+function hasReviewAfterArtifact(taskDir, family, reviewFamily) {
+    const artifact = inspectArtifactDirectory(taskDir, family);
+    const review = inspectArtifactDirectory(taskDir, reviewFamily);
+    return artifact.status === 'ready'
+        && review.status === 'ready'
+        && artifact.latest !== null
+        && review.reviewedInput?.name === artifact.latest.name;
+}
+function latestReviewApproved(taskDir, family) {
+    const round = highestRound(taskDir, family);
+    if (round === 0)
+        return false;
+    const parsed = parseReviewSummary(fs.readFileSync(path.join(taskDir, artifactName(family, round)), 'utf8'));
+    return parsed.ok && parsed.summary.verdict === 'Approved' && parsed.summary.counts !== null;
+}
+function routeFromFacts(taskDir) {
+    const analysisRound = highestRound(taskDir, 'analysis');
+    const analysisReviewRound = highestRound(taskDir, 'review-analysis');
+    const planRound = highestRound(taskDir, 'plan');
+    const planReviewRound = highestRound(taskDir, 'review-plan');
+    const codeRound = highestRound(taskDir, 'code');
+    const codeReviewRound = highestRound(taskDir, 'review-code');
+    if (analysisRound === 0) {
+        const round = analysisRound + 1;
+        return { action: 'analyze-task', role: 'executor', stage: 'analysis', round, artifact: artifactName('analysis', round) };
+    }
+    if (!hasReviewAfterArtifact(taskDir, 'analysis', 'review-analysis')) {
+        const round = analysisReviewRound + 1;
+        return { action: 'review-analysis', role: 'reviewer', stage: 'review-analysis', round, artifact: artifactName('review-analysis', round) };
+    }
+    if (!latestReviewApproved(taskDir, 'review-analysis')) {
+        const round = analysisRound + 1;
+        return { action: 'analyze-task', role: 'executor', stage: 'analysis', round, artifact: artifactName('analysis', round) };
+    }
+    if (planRound === 0) {
+        const round = planRound + 1;
+        return { action: 'plan-task', role: 'executor', stage: 'plan', round, artifact: artifactName('plan', round) };
+    }
+    if (!hasReviewAfterArtifact(taskDir, 'plan', 'review-plan')) {
+        const round = planReviewRound + 1;
+        return { action: 'review-plan', role: 'reviewer', stage: 'review-plan', round, artifact: artifactName('review-plan', round) };
+    }
+    if (!latestReviewApproved(taskDir, 'review-plan')) {
+        const round = planRound + 1;
+        return { action: 'plan-task', role: 'executor', stage: 'plan', round, artifact: artifactName('plan', round) };
+    }
+    if (codeRound === 0) {
+        const round = codeRound + 1;
+        return { action: 'code-task', role: 'executor', stage: 'code', round, artifact: artifactName('code', round) };
+    }
+    if (!hasReviewAfterArtifact(taskDir, 'code', 'review-code')) {
+        const round = codeReviewRound + 1;
+        return { action: 'review-code', role: 'reviewer', stage: 'review-code', round, artifact: artifactName('review-code', round) };
+    }
+    if (!latestReviewApproved(taskDir, 'review-code')) {
+        const round = codeRound + 1;
+        return { action: 'code-task', role: 'executor', stage: 'code', round, artifact: artifactName('code', round) };
+    }
+    return { action: 'commit', role: 'executor', stage: 'commit', round: 1, artifact: 'commit' };
+}
+function routeOrchestration(taskRef, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message, 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;
+    try {
+        metadata = parseTypedTaskFrontmatter(content);
+    }
+    catch (error) {
+        return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    const routed = routeFromFacts(resolved.taskDir);
+    if (!routed)
+        return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
+    const run = readRun(resolved.taskDir);
+    const policy = run ? rolePolicy(run, routed.role) : null;
+    const next = {
+        ...routed,
+        requestedModel: policy?.model ?? null,
+        requestedReasoningEffort: policy?.reasoningEffort ?? null
+    };
+    if (next.stage === 'commit') {
+        const reviewRound = highestRound(resolved.taskDir, 'review-code');
+        const review = parseReviewSummary(fs.readFileSync(path.join(resolved.taskDir, artifactName('review-code', reviewRound)), '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 rows = parseLedger(content);
+        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 };
+        }
+        let config;
+        try {
+            config = JSON.parse(fs.readFileSync(path.join(resolved.repoRoot, '.agents', '.airc.json'), 'utf8'));
+        }
+        catch (error) {
+            return failed('ORCHESTRATION_CONFIG_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+        }
+        if (!config || typeof config !== 'object' || Array.isArray(config)) {
+            return failed('ORCHESTRATION_CONFIG_INVALID', 'project configuration must be an object', resolved.taskId);
+        }
+        const projectConfig = config;
+        if (!Object.hasOwn(projectConfig, 'prFlow') || projectConfig.prFlow === 'disabled') {
+            return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+        }
+        if (projectConfig.prFlow !== 'required') {
+            return failed('ORCHESTRATION_CONFIG_INVALID', "project configuration 'prFlow' must be 'required' or 'disabled'", resolved.taskId);
+        }
+        const prNumber = Number(metadata.pr_number);
+        if (!Number.isInteger(prNumber) || prNumber <= 0) {
+            return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+        }
+        if (!run) {
+            return { status: 'running', changed: false, taskId: resolved.taskId, run, next, 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(resolved.repoRoot);
+        }
+        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, 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 inspect = options.inspectPullRequest ?? inspectPlatformPullRequest;
+        let inspection;
+        try {
+            inspection = inspect(resolved.taskId, { cwd: resolved.repoRoot });
+        }
+        catch (error) {
+            return failed('ORCHESTRATION_PR_INSPECTION_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+        }
+        if (inspection.status === 'blocked') {
+            return failed('ORCHESTRATION_PR_INSPECTION_BLOCKED', inspection.error?.message ?? 'pull request inspection is blocked', resolved.taskId);
+        }
+        if (inspection.status === 'failed') {
+            return failed('ORCHESTRATION_PR_INSPECTION_FAILED', inspection.error?.message ?? 'pull request inspection failed', resolved.taskId);
+        }
+        const inspectedPrNumber = inspection.task?.prNumber ?? inspection.prNumber;
+        const prHead = inspection.pullRequest?.head?.sha;
+        if (typeof prHead !== 'string') {
+            return failed('ORCHESTRATION_PR_INSPECTION_INVALID', 'pull request inspection returned incomplete identity evidence', resolved.taskId);
+        }
+        if (inspectedPrNumber !== prNumber || prHead !== before.head) {
+            return failed('ORCHESTRATION_PR_HEAD_MISMATCH', 'pull request identity does not match the reviewed local HEAD', resolved.taskId);
+        }
+        let after;
+        try {
+            after = capture(resolved.repoRoot);
+        }
+        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, 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,
+            prHead
+        };
+        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 };
+    }
+    return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+}
+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);
+    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 prepareOrchestrationDelegationUnlocked(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);
+    }
+    const run = readRun(resolved.taskDir);
+    if (!run || run.status !== 'running')
+        return failed('ORCHESTRATION_RUN_NOT_RUNNING', 'a running orchestration is required', resolved.taskId);
+    if (!isV2Policy(run.modelPolicy))
+        return failed('ORCHESTRATION_MODEL_EVIDENCE_MISSING', 'running orchestration has no persisted model policy', resolved.taskId);
+    if (run.pendingDelegation)
+        return failed('ORCHESTRATION_DELEGATION_BUSY', 'the run already has a pending delegation', resolved.taskId);
+    const repositoryPending = ['claude-code', 'codex']
+        .flatMap((client) => matchingDelegations(client, () => true, options));
+    if (repositoryPending.length > 0) {
+        return failed('ORCHESTRATION_DELEGATION_BUSY', 'the repository already has a pending lifecycle delegation', resolved.taskId);
+    }
+    if (run.stepCount >= run.maxSteps)
+        return pauseOrchestration(taskRef, 'ORCHESTRATION_MAX_STEPS', 'maximum orchestration steps reached', true, options);
+    const routed = routeOrchestration(taskRef, options);
+    if (!routed.next)
+        return routed;
+    const next = routed.next;
+    if (!validModel(input.requestedModel)) {
+        return failed('ORCHESTRATION_REQUESTED_MODEL_REQUIRED', 'prepare requires the exact requested model identity', resolved.taskId);
+    }
+    if (!validModel(input.requestedReasoningEffort)) {
+        return failed('ORCHESTRATION_REQUESTED_REASONING_EFFORT_REQUIRED', 'prepare requires the exact requested reasoning effort', resolved.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`, resolved.taskId);
+    }
+    if (input.requestedReasoningEffort !== expectedPolicy.reasoningEffort) {
+        return failed('ORCHESTRATION_REQUESTED_REASONING_EFFORT_MISMATCH', `requested reasoning effort does not match the persisted ${next.role} policy`, resolved.taskId);
+    }
+    let beforeFingerprint;
+    try {
+        beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(resolved.repoRoot, resolved.taskId);
+    }
+    catch (error) {
+        return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    const receipt = prepareDelegation({
+        taskId: resolved.taskId,
+        runId: run.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 });
+    const updated = withUpdatedRun(run, {
+        nextStage: next.stage,
+        pendingDelegation: receipt,
+        commitAuthorization: next.stage === 'commit' && run.commitAuthorization.issuedAt === null
+            ? { issuedAt: (options.now ?? (() => new Date().toISOString()))(), consumedAt: null }
+            : run.commitAuthorization
+    });
+    saveRun(resolved.taskDir, updated);
+    return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next, error: null };
+}
+function prepareOrchestrationDelegation(taskRef, input, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message, resolved.taskId);
+    try {
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-orchestration.prepare', () => prepareOrchestrationDelegationUnlocked(taskRef, input, options));
+    }
+    catch (error) {
+        if (error instanceof TaskExecutionLockError)
+            return failed(error.code, error.message, resolved.taskId);
+        throw error;
+    }
+}
+function matchingDelegations(client, predicate, options) {
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const activeRoot = path.join(repoRoot, '.agents', 'workspace', 'active');
+    if (!fs.existsSync(activeRoot))
+        return [];
+    return fs.readdirSync(activeRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .flatMap((entry) => {
+        const run = readRun(path.join(activeRoot, entry.name));
+        if (!run?.pendingDelegation)
+            return [];
+        const receipt = run.pendingDelegation;
+        return receipt.client === client && predicate(receipt)
+            ? [{ taskId: entry.name, run }]
+            : [];
+    });
+}
+function uniqueMatchingDelegation(client, predicate, options) {
+    const matches = matchingDelegations(client, predicate, options);
+    if (matches.length === 0)
+        return failed('ORCHESTRATION_DELEGATION_MISSING', 'no matching lifecycle delegation exists');
+    if (matches.length > 1)
+        return failed('ORCHESTRATION_DELEGATION_AMBIGUOUS', 'multiple lifecycle delegations match the native hook event');
+    return matches[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)
+        return matched;
+    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 sealMatchingOrchestrationDelegation(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)
+        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 snapshotTaskId = receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null;
+        const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(repoRoot, snapshotTaskId);
+        const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(repoRoot, receipt.beforeFingerprint, afterFingerprint);
+        return sealOrchestrationDelegation(matched.taskId, {
+            childId: event.childId,
+            exitCode: 0,
+            afterFingerprint,
+            changedPaths
+        }, options);
+    }
+    catch (error) {
+        return pauseOrchestration(matched.taskId, 'ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), true, options);
+    }
+}
+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);
+    if (!run?.pendingDelegation)
+        return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
+    const result = activateDelegation(run.pendingDelegation, event, { now: options.now });
+    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 };
+}
+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);
+    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);
+    }
+    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 });
+    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 completeCommitOrchestrationStage(taskRef, agent, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message, resolved.taskId);
+    const run = readRun(resolved.taskDir);
+    if (!run)
+        return { status: 'running', changed: false, taskId: resolved.taskId, run: null, next: null, error: null };
+    const receipt = run.pendingDelegation;
+    if (!receipt || receipt.stage !== 'commit') {
+        return failed('ORCHESTRATION_DELEGATION_MISSING', 'active run has no pending commit delegation', resolved.taskId);
+    }
+    return completeOrchestrationStage(taskRef, {
+        stage: receipt.stage,
+        round: receipt.round,
+        artifact: receipt.artifact,
+        agent
+    }, options);
+}
+function sealOrchestrationDelegation(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);
+    if (!run?.pendingDelegation)
+        return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
+    const result = sealDelegation(run.pendingDelegation, event, { now: options.now });
+    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 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);
+    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);
+    const completed = result.receipt.stage === 'commit';
+    const updated = withUpdatedRun(run, {
+        status: completed ? 'completed' : 'running',
+        nextStage: null,
+        stepCount: run.stepCount + 1,
+        pendingDelegation: null,
+        receipts: Object.freeze([...run.receipts, result.receipt]),
+        commitAuthorization: completed
+            ? { ...run.commitAuthorization, consumedAt: (options.now ?? (() => new Date().toISOString()))() }
+            : run.commitAuthorization
+    });
+    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);
+    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, advanceOrchestration, beginOrResumeOrchestration, commitOrchestrationStageCompletion, completeCommitOrchestrationStage, completeOrchestrationStage, inspectOrchestrationStage, orchestrationPath, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, routeOrchestration, sealMatchingOrchestrationDelegation, sealOrchestrationDelegation, statusOrchestration };
+//# sourceMappingURL=orchestration.js.map