@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/dist/lib/task/orchestration.js

@@ -7,8 +7,18 @@ 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';
+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');
 }
@@ -16,7 +26,22 @@ function readRun(taskDir) {
     const file = orchestrationPath(taskDir);
     if (!fs.existsSync(file))
         return null;
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
+    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`;
@@ -29,36 +54,209 @@ function saveRun(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 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);
-    const existing = readRun(resolved.taskDir);
+    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 (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 };
+        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);
         }
-        return { status: existing.status, changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
     }
+    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: 1,
+        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
     };
@@ -146,24 +344,29 @@ function routeOrchestration(taskRef, options = {}) {
     catch (error) {
         return failed('ORCHESTRATION_TASK_READ_FAILED', String(error), resolved.taskId);
     }
+    let metadata;
     try {
-        parseTypedTaskFrontmatter(content);
+        metadata = 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)
+    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);
         }
-        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)
@@ -171,8 +374,107 @@ function routeOrchestration(taskRef, options = {}) {
         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: readRun(resolved.taskDir), next, 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 });
@@ -183,17 +485,18 @@ function statusOrchestration(taskRef, options = {}) {
         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 = {}) {
+function prepareOrchestrationDelegationUnlocked(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') {
+    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']
@@ -207,9 +510,22 @@ function prepareOrchestrationDelegation(taskRef, input, 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);
+        beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(resolved.repoRoot, resolved.taskId);
     }
     catch (error) {
         return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
@@ -222,7 +538,9 @@ function prepareOrchestrationDelegation(taskRef, input, options = {}) {
         round: next.round,
         artifact: next.artifact,
         client: input.client,
-        requestedModel: input.requestedModel ?? null,
+        requestedModel: input.requestedModel,
+        requestedReasoningEffort: input.requestedReasoningEffort,
+        workspaceSnapshotScope: 'task',
         beforeFingerprint
     }, { id: options.id, now: options.now });
     const updated = withUpdatedRun(run, {
@@ -235,6 +553,19 @@ function prepareOrchestrationDelegation(taskRef, input, options = {}) {
     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');
@@ -285,7 +616,8 @@ function sealMatchingOrchestrationDelegation(client, event, options = {}) {
     }
     const repoRoot = options.repoRoot ?? process.cwd();
     try {
-        const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(repoRoot);
+        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,
@@ -331,6 +663,56 @@ function completeOrchestrationStage(taskRef, event, options = {}) {
     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)
@@ -349,24 +731,6 @@ function completeCommitOrchestrationStage(taskRef, agent, options = {}) {
         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)
@@ -416,5 +780,5 @@ function pauseOrchestration(taskRef, code, message, recoverable, options = {}) {
     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 };
+export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, advanceOrchestration, beginOrResumeOrchestration, commitOrchestrationStageCompletion, completeCommitOrchestrationStage, completeOrchestrationStage, inspectOrchestrationStage, orchestrationPath, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, routeOrchestration, sealMatchingOrchestrationDelegation, sealOrchestrationDelegation, statusOrchestration };
 //# sourceMappingURL=orchestration.js.map

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

@@ -6,7 +6,8 @@ import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecyc
 import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { finalizeReviewSummaryContent } from './review-artifacts.js';
 import { resolveTaskRef } from './resolve-ref.js';
-import { validateOrchestrationStage } from './orchestration.js';
+import { validateLifecycleExecution } from './lifecycle-execution.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 const STAGES = {
     analysis: { family: 'review-analysis', action: 'Review Analysis' },
     plan: { family: 'review-plan', action: 'Review Plan' },
@@ -48,7 +49,7 @@ function cleanupTemp(fileSystem, tempPath) {
         // Best-effort cleanup preserves the primary failure.
     }
 }
-function finalizeReviewSummary(request, options = {}) {
+function finalizeReviewSummaryUnlocked(request, options = {}) {
     const stage = request.stage;
     const spec = STAGES[stage];
     if (!spec)
@@ -86,14 +87,18 @@ function finalizeReviewSummary(request, options = {}) {
     if (!openReviewRound(taskContent, spec.action, parsedArtifact.round)) {
         return failed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`, resolved.taskId);
     }
-    const provenance = validateOrchestrationStage(request.taskRef, {
-        stage: spec.family,
-        round: parsedArtifact.round,
-        artifact: request.artifact,
-        role: 'reviewer'
+    const execution = validateLifecycleExecution(request.taskRef, {
+        mode: request.orchestrated ? 'orchestrated' : 'standalone',
+        identity: {
+            stage: spec.family,
+            round: parsedArtifact.round,
+            artifact: request.artifact,
+            role: 'reviewer'
+        },
+        dryRun: request.dryRun
     }, { repoRoot: options.repoRoot });
-    if (provenance.status === 'failed' || provenance.status === 'paused') {
-        return failed(request, 'REVIEW_PROVENANCE_INVALID', provenance.error?.message ?? provenance.run?.pause?.message ?? 'orchestration provenance validation failed', resolved.taskId);
+    if (!execution.ok) {
+        return failed(request, 'REVIEW_PROVENANCE_INVALID', `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`, resolved.taskId);
     }
     let rows;
     try {
@@ -162,5 +167,20 @@ function finalizeReviewSummary(request, options = {}) {
         error: null
     };
 }
+function finalizeReviewSummary(request, options = {}) {
+    if (request.dryRun)
+        return finalizeReviewSummaryUnlocked(request, options);
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return finalizeReviewSummaryUnlocked(request, options);
+    try {
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', () => finalizeReviewSummaryUnlocked(request, options));
+    }
+    catch (error) {
+        if (!(error instanceof TaskExecutionLockError))
+            throw error;
+        return failed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
+    }
+}
 export { finalizeReviewSummary };
 //# sourceMappingURL=review-finalization.js.map