@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/dist/lib/task/events.js

@@ -3,8 +3,11 @@ import { appendActivityEntry, locateActivityLog, pairEntries } from './activity-
 import { buildArtifactLinkSection, artifactName, parseArtifactName, resolveArtifactContext, validateCompletedArtifact } from './artifact-lifecycle.js';
 import { parseTypedTaskFrontmatter } from './frontmatter.js';
 import { consumeImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs } from './implementation-inputs.js';
+import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
+import { parseReviewSummary } from './review-artifacts.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { findSectionHeading } from './sections.js';
+import { completeOrchestrationStage, validateOrchestrationStage } from './orchestration.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
 const eventCatalog = [
     'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
@@ -75,12 +78,75 @@ function validateTaskEventRequest(request) {
 const FAMILY = {
     analyze: { artifact: 'analysis', started: ['requirement-analysis', 'requirement-analysis-review', 'code'], completed: ['requirement-analysis', 'requirement-analysis-review', 'code'], target: 'requirement-analysis', label: 'Analyze Task' },
     'review-analysis': { artifact: 'review-analysis', started: ['requirement-analysis', 'requirement-analysis-review'], completed: ['requirement-analysis', 'requirement-analysis-review'], target: 'requirement-analysis-review', label: 'Review Analysis' },
-    plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review'], completed: ['requirement-analysis-review', 'technical-design-review'], target: 'technical-design', label: 'Plan Task' },
+    plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review', 'commit'], completed: ['requirement-analysis-review', 'technical-design-review', 'commit'], target: 'technical-design', label: 'Plan Task' },
     'review-plan': { artifact: 'review-plan', started: ['technical-design', 'technical-design-review'], completed: ['technical-design', 'technical-design-review'], target: 'technical-design-review', label: 'Review Plan' },
     code: { artifact: 'code', started: ['technical-design-review', 'code-review'], completed: ['technical-design-review', 'code-review'], target: 'code', label: 'Code Task' },
     'review-code': { artifact: 'review-code', started: ['code', 'code-review', 'commit'], completed: ['code', 'code-review', 'commit'], target: 'code-review', label: 'Review Code' },
     'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' }
 };
+const REVIEW_LEDGER_STAGES = {
+    'review-analysis': 'analysis',
+    'review-plan': 'plan',
+    'review-code': 'code'
+};
+function validateReviewFindingCounts(request, content, family, artifactPath) {
+    const stage = REVIEW_LEDGER_STAGES[family];
+    if (!stage || !artifactPath)
+        return null;
+    const rows = parseLedger(content);
+    const invalid = validateLedgerRows(rows);
+    if (invalid)
+        return { code: 'TASK_DOCUMENT_INVALID', message: `${invalid.code}: ${invalid.message}` };
+    const expected = summarizeLedgerStage(rows, stage).unresolvedFindingCounts;
+    const payload = {
+        blocker: request.blockers,
+        major: request.major,
+        minor: request.minor
+    };
+    let reportContent;
+    try {
+        reportContent = fs.readFileSync(artifactPath, 'utf8');
+    }
+    catch (error) {
+        return { code: 'EVENT_FINDING_COUNT_MISMATCH', message: String(error) };
+    }
+    const parsed = parseReviewSummary(reportContent);
+    if (!parsed.ok || !parsed.summary.counts) {
+        return {
+            code: 'EVENT_FINDING_COUNT_MISMATCH',
+            message: parsed.ok ? 'review summary finding counts are not finalized' : parsed.message
+        };
+    }
+    const report = parsed.summary.counts;
+    const reportVerdict = parsed.summary.verdict === 'Approved'
+        ? 'approved'
+        : parsed.summary.verdict === 'Changes Requested' ? 'changes-requested' : 'rejected';
+    const fields = [
+        ['blocker', 'blockers'],
+        ['major', 'major'],
+        ['minor', 'minor']
+    ];
+    const differences = fields.flatMap(([severity, cliField]) => {
+        const values = [
+            expected[severity] === payload[severity]
+                ? null
+                : `${cliField} ledger ${expected[severity]}, payload ${payload[severity]}`,
+            expected[severity] === report[severity]
+                ? null
+                : `${cliField} ledger ${expected[severity]}, report ${report[severity]}`
+        ];
+        return values.filter((value) => value !== null);
+    });
+    if (request.verdict !== reportVerdict) {
+        differences.push(`verdict report ${reportVerdict}, payload ${request.verdict}`);
+    }
+    if (differences.length === 0)
+        return null;
+    return {
+        code: 'EVENT_FINDING_COUNT_MISMATCH',
+        message: `review summary, payload, and ${stage} ledger do not match: ${differences.join('; ')}`
+    };
+}
 function eventParts(event) {
     const [family, suffix] = event.split('.');
     return { family, phase: suffix === 'started' ? 'started' : suffix === 'awaiting-input' ? 'waiting' : 'completed' };
@@ -257,6 +323,24 @@ function applyTaskEvent(request, options = {}) {
     const allowed = FAMILY[eventIdentity.family][eventIdentity.phase === 'started' ? 'started' : 'completed'];
     if (!allowed.includes(currentStep))
         return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${normalized.event} is not allowed from '${currentStep}'` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    const findingCountError = validateReviewFindingCounts(normalized, content, eventIdentity.family, completedArtifact?.path ?? null);
+    if (findingCountError)
+        return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    if (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
+        const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
+        const provenance = validateOrchestrationStage(normalized.taskRef, {
+            stage: orchestrationStage,
+            round: normalized.round,
+            artifact: normalized.artifact,
+            role: eventIdentity.family.startsWith('review-') ? 'reviewer' : 'executor'
+        }, { repoRoot: options.repoRoot });
+        if (provenance.status === 'failed' || provenance.status === 'paused') {
+            return failed(normalized, {
+                code: 'EVENT_TRANSITION_INVALID',
+                message: provenance.error?.message ?? provenance.run?.pause?.message ?? 'orchestration provenance validation failed'
+            }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+        }
+    }
     let metadata;
     try {
         metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
@@ -295,6 +379,21 @@ function applyTaskEvent(request, options = {}) {
     const result = writeTask({ taskRef: normalized.taskRef, expectedState: 'active', dryRun: normalized.dryRun, mutations }, { ...options, metadataProvider: () => metadata });
     if (result.status === 'failed')
         return failed(normalized, result.error, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+    if (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
+        const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
+        const orchestration = completeOrchestrationStage(normalized.taskRef, {
+            stage: orchestrationStage,
+            round: normalized.round,
+            artifact: normalized.artifact,
+            agent: normalized.agent
+        }, { repoRoot: options.repoRoot });
+        if (orchestration.status === 'failed' || orchestration.status === 'paused') {
+            return failed(normalized, {
+                code: 'EVENT_TRANSITION_INVALID',
+                message: orchestration.error?.message ?? orchestration.run?.pause?.message ?? 'orchestration provenance validation failed'
+            }, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+        }
+    }
     return {
         status: result.status, changed: result.changed, event: normalized.event,
         requestRef: normalized.taskRef, taskId: result.taskId, taskMdPath: result.taskMdPath,

package/dist/lib/task/orchestration.js

@@ -0,0 +1,420 @@
+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 { getAgentClientCapability } from '../agent-clients/registry.js';
+import { captureWorkspaceSnapshot, diffWorkspaceSnapshots } from './workspace-snapshot.js';
+function orchestrationPath(taskDir) {
+    return path.join(taskDir, 'orchestration.json');
+}
+function readRun(taskDir) {
+    const file = orchestrationPath(taskDir);
+    if (!fs.existsSync(file))
+        return null;
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+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) {
+    return { status: 'failed', changed: false, taskId, run: null, next: null, error: { code, message } };
+}
+function beginOrResumeOrchestration(taskRef, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message, resolved.taskId);
+    const existing = readRun(resolved.taskDir);
+    if (existing) {
+        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 };
+    }
+    const now = (options.now ?? (() => new Date().toISOString()))();
+    const run = {
+        schemaVersion: 1,
+        taskId: resolved.taskId,
+        runId: (options.id ?? randomUUID)(),
+        status: 'running',
+        nextStage: null,
+        stepCount: 0,
+        maxSteps: options.maxSteps ?? 24,
+        baseline: '',
+        pendingDelegation: null,
+        receipts: [],
+        pause: null,
+        commitAuthorization: { issuedAt: null, consumedAt: 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);
+    }
+    try {
+        parseTypedTaskFrontmatter(content);
+    }
+    catch (error) {
+        return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    const next = routeFromFacts(resolved.taskDir);
+    if (!next)
+        return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
+    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);
+        }
+        if (review.summary.manualValidation > 0) {
+            return failed('ORCHESTRATION_MANUAL_VALIDATION_PENDING', 'manual validation must be completed before commit', 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);
+        }
+    }
+    return { status: 'running', changed: false, taskId: resolved.taskId, run: readRun(resolved.taskDir), 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 prepareOrchestrationDelegation(taskRef, input, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message, resolved.taskId);
+    if (getAgentClientCapability(input.client, 'subagents').level === 'unsupported'
+        || getAgentClientCapability(input.client, 'orchestration').level === 'unsupported') {
+        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 (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;
+    let beforeFingerprint;
+    try {
+        beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(resolved.repoRoot);
+    }
+    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 ?? null,
+        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 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 afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(repoRoot);
+        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 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 validateOrchestrationStage(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 };
+    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 pauseOrchestration(taskRef, 'ORCHESTRATION_PROVENANCE_MISMATCH', 'active run does not have one matching activated delegation', true, options);
+    }
+    return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
+}
+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, completeCommitOrchestrationStage, completeOrchestrationStage, orchestrationPath, pauseOrchestration, prepareOrchestrationDelegation, readRun, routeOrchestration, sealMatchingOrchestrationDelegation, sealOrchestrationDelegation, statusOrchestration, validateOrchestrationStage };
+//# sourceMappingURL=orchestration.js.map