codex-workflow-v2 2.0.0-beta.13.7 → 2.0.0-beta.13.8

package/dist/src/workflow.js

@@ -1,3 +1,4 @@
+import { explainChange } from './change-explanation.js';
 import { pendingReviewRunnerFingerprint, PENDING_REVIEW_UPDATE_SIDECAR, preparePendingReviewUpdateEvent, PENDING_REVIEW_SOURCE_VERSION, pendingReviewSourceBinding, pendingReviewBindingHash, assertPendingReviewTransport, verifiedPendingReviewTransport } from './pending-review-update.js';
 import { appendFileSync, existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
@@ -411,7 +412,7 @@ export class WorkflowService {
             discoveries: this.store.listDiscoveries(identity.projectId),
             tasks,
             milestones: this.listMilestonesObserved(identity.projectId, rawMilestones, adoption.currentPosture),
-            delegations: this.store.listDelegations(identity.projectId),
+            delegations: this.listDelegations(identity.projectId),
             adoption,
         };
     }
@@ -428,7 +429,7 @@ export class WorkflowService {
         if (confirmationCode.trim() !== gate.confirmationCode) {
             throw new WorkflowError('TRANSITION_BLOCKED', 'Delegation confirmation does not match the exact project and policy.', { projectId: identity.projectId, policyHash: gate.policyHash });
         }
-        const duplicate = this.store.listDelegations(identity.projectId)
+        const duplicate = this.listDelegations(identity.projectId)
             .find((grant) => grant.policyHash === gate.policyHash);
         if (duplicate) {
             throw new WorkflowError('TRANSITION_BLOCKED', 'This exact delegation policy was already issued.', {
@@ -458,26 +459,35 @@ export class WorkflowService {
         }, null);
     }
     revokeDelegation(repository, grantId, expectedRevision, actor, reason) {
-        const { identity } = this.#mutationContext(repository);
-        const grant = this.store.readDelegation(identity.projectId, grantId);
-        assertExpectedRevision(grant, expectedRevision);
-        if (grant.status !== 'active') {
-            throw new WorkflowError('TRANSITION_BLOCKED', `Delegation ${grantId} is already ${grant.status}.`);
-        }
-        if (actor.trim() !== grant.principal) {
-            throw new WorkflowError('TRANSITION_BLOCKED', 'Only the recorded principal may revoke a delegation.', {
-                principal: grant.principal,
-            });
+        const { identity, locks } = this.#mutationContext(repository);
+        const before = this.store.readDelegation(identity.projectId, grantId);
+        const lease = before.scope.kind === 'milestone'
+            ? locks.acquire(before.scope.id, 'workflow-core:delegation-revocation') : null;
+        try {
+            const grant = this.store.readDelegation(identity.projectId, grantId);
+            assertExpectedRevision(grant, expectedRevision);
+            if (grant.status !== 'active') {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Delegation ${grantId} is already ${grant.status}.`);
+            }
+            if (actor.trim() !== grant.principal) {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'Only the recorded principal may revoke a delegation.', {
+                    principal: grant.principal,
+                });
+            }
+            if (!reason.trim())
+                throw new WorkflowError('INVALID_ARGUMENT', 'Delegation revocation requires a reason.');
+            return this.store.writeDelegation({
+                ...grant,
+                status: 'revoked',
+                revokedAt: this.now().toISOString(),
+                revokedBy: grant.principal,
+                revokeReason: reason.trim(),
+            }, expectedRevision);
+        }
+        finally {
+            if (lease)
+                locks.release(lease.entityId, lease.token);
         }
-        if (!reason.trim())
-            throw new WorkflowError('INVALID_ARGUMENT', 'Delegation revocation requires a reason.');
-        return this.store.writeDelegation({
-            ...grant,
-            status: 'revoked',
-            revokedAt: this.now().toISOString(),
-            revokedBy: grant.principal,
-            revokeReason: reason.trim(),
-        }, expectedRevision);
     }
     startDiscovery(repository, input) {
         if (!input.goal.trim())
@@ -1359,34 +1369,53 @@ export class WorkflowService {
         };
     }
     applyMilestoneScopeChange(repository, milestoneId, expectedRevision, plan, actor, confirmationCode) {
-        const { identity } = this.#mutationContext(repository);
-        const milestone = this.readMilestoneScopeChangeCurrent(identity.projectId, milestoneId);
-        assertExpectedRevision(milestone, expectedRevision);
-        assertMilestoneScopeChangeStatusAllowed(milestone);
-        const prepared = this.prepareMilestoneScopeChangeCandidate(identity.projectId, milestone, plan, actor);
-        if (confirmationCode.trim() !== prepared.confirmationCode) {
-            throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone scope-change confirmation does not match the current Milestone state and requested scope.', {
-                milestoneId,
-                revision: milestone.revision,
-                actor: prepared.actor,
-                confirmationCodeBindingHash: prepared.confirmationCodeBindingHash,
+        const { identity, locks } = this.#mutationContext(repository);
+        const authorityLease = locks.acquire(milestoneId, 'workflow-core:milestone-authority');
+        try {
+            const milestone = this.readMilestoneScopeChangeCurrent(identity.projectId, milestoneId);
+            assertExpectedRevision(milestone, expectedRevision);
+            assertMilestoneScopeChangeStatusAllowed(milestone);
+            const prepared = this.prepareMilestoneScopeChangeCandidate(identity.projectId, milestone, plan, actor);
+            if (confirmationCode.trim() !== prepared.confirmationCode) {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone scope-change confirmation does not match the current Milestone state and requested scope.', {
+                    milestoneId,
+                    revision: milestone.revision,
+                    actor: prepared.actor,
+                    confirmationCodeBindingHash: prepared.confirmationCodeBindingHash,
+                });
+            }
+            return applyMilestoneScopeChangeTransaction({
+                store: this.store,
+                milestone,
+                expectedRevision,
+                prepared,
+                now: this.now(),
+                readTask: (taskId) => this.store.readTask(identity.projectId, taskId),
             });
         }
-        return applyMilestoneScopeChangeTransaction({
-            store: this.store,
-            milestone,
-            expectedRevision,
-            prepared,
-            now: this.now(),
-            readTask: (taskId) => this.store.readTask(identity.projectId, taskId),
-        });
+        finally {
+            locks.release(milestoneId, authorityLease.token);
+        }
+    }
+    listDelegations(projectId) {
+        // Valid append-only issuance events can precede publication of their grant.
+        // Such missing state conveys no authority, even if mkdir already succeeded.
+        const issuedIds = new Set(this.store.listMilestones(projectId).flatMap(milestone => readMilestoneAutonomyEvents(this.store, projectId, milestone.id).map(event => event.delegationGrantId)));
+        return this.store.listDelegations(projectId, issuedIds);
     }
     prepareMilestoneAutonomy(repository, milestoneId, expectedRevision, principal, delegate, expiresAt) {
-        const { identity } = this.#mutationContext(repository);
-        const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
+        const snapshot = this.observationSnapshot(repository);
+        if (snapshot.observation.kind !== 'assessment') {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Autonomy preparation requires a coherent observation boundary.', {
+                observation: snapshot.observation,
+            });
+        }
+        const identity = resolveRepositoryIdentity(repository);
+        const milestone = inspectMilestoneWithIntegrity(this.store, identity.projectId, milestoneId, (taskId) => this.store.readTask(identity.projectId, taskId), () => this.store.listTasks(identity.projectId));
         assertExpectedRevision(milestone, expectedRevision);
         this.requireActiveKnowledgeMap(identity.repositoryRoot, identity.projectId);
         return prepareMilestoneAutonomyContract({
+            store: this.store,
             projectId: identity.projectId,
             milestone,
             principal,
@@ -1396,208 +1425,244 @@ export class WorkflowService {
         });
     }
     grantMilestoneAutonomy(repository, milestoneId, expectedRevision, principal, delegate, expiresAt, confirmationCode) {
-        const { identity } = this.#mutationContext(repository);
-        const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
-        assertExpectedRevision(milestone, expectedRevision);
-        this.requireActiveKnowledgeMap(identity.repositoryRoot, identity.projectId);
-        return applyMilestoneAutonomyContract({
-            store: this.store,
-            projectId: identity.projectId,
-            milestone,
-            principal,
-            delegate,
-            expiresAt,
-            confirmationCode,
-            now: this.now(),
-        });
+        const { identity, locks } = this.#mutationContext(repository);
+        const lease = locks.acquire(milestoneId, 'workflow-core:autonomy-issuance');
+        try {
+            const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
+            assertExpectedRevision(milestone, expectedRevision);
+            this.requireActiveKnowledgeMap(identity.repositoryRoot, identity.projectId);
+            return applyMilestoneAutonomyContract({
+                store: this.store,
+                projectId: identity.projectId,
+                milestone,
+                principal,
+                delegate,
+                expiresAt,
+                confirmationCode,
+                now: this.now(),
+            });
+        }
+        finally {
+            locks.release(milestoneId, lease.token);
+        }
     }
     evolveMilestonePlanAutonomously(repository, milestoneId, expectedRevision, plan, actor) {
-        const { identity } = this.#mutationContext(repository);
-        const milestone = this.readMilestoneScopeChangeCurrent(identity.projectId, milestoneId);
-        assertExpectedRevision(milestone, expectedRevision);
-        assertMilestoneScopeChangeStatusAllowed(milestone);
-        const autonomy = requireActiveMilestoneAutonomy({
-            store: this.store,
-            projectId: identity.projectId,
-            milestone,
-            actor,
-            now: this.now(),
-        });
-        validateMilestonePlan(plan);
-        assertAutonomousPlanEvolution(milestone, plan, autonomy.contract);
-        const prepared = prepareMilestoneScopeChangeCandidate({
-            milestone,
-            plan,
-            readTask: (taskId) => this.store.readTask(identity.projectId, taskId),
-            actor,
-            autonomyContractEventHash: autonomy.contract.eventHash,
-        });
-        return applyMilestoneScopeChangeTransaction({
-            store: this.store,
-            milestone,
-            expectedRevision,
-            prepared,
-            now: this.now(),
-            readTask: (taskId) => this.store.readTask(identity.projectId, taskId),
-        });
+        const { identity, locks } = this.#mutationContext(repository);
+        const authorityLease = locks.acquire(milestoneId, 'workflow-core:milestone-authority');
+        try {
+            const milestone = this.readMilestoneScopeChangeCurrent(identity.projectId, milestoneId);
+            assertExpectedRevision(milestone, expectedRevision);
+            assertMilestoneScopeChangeStatusAllowed(milestone);
+            const autonomy = requireActiveMilestoneAutonomy({
+                store: this.store,
+                projectId: identity.projectId,
+                milestone,
+                actor,
+                now: this.now(),
+            });
+            validateMilestonePlan(plan);
+            assertAutonomousPlanEvolution(milestone, plan, autonomy.contract);
+            const prepared = prepareMilestoneScopeChangeCandidate({
+                milestone,
+                plan,
+                readTask: (taskId) => this.store.readTask(identity.projectId, taskId),
+                actor,
+                autonomyContractEventHash: autonomy.contract.eventHash,
+            });
+            return applyMilestoneScopeChangeTransaction({
+                store: this.store,
+                milestone,
+                expectedRevision,
+                prepared,
+                now: this.now(),
+                readTask: (taskId) => this.store.readTask(identity.projectId, taskId),
+            });
+        }
+        finally {
+            locks.release(milestoneId, authorityLease.token);
+        }
     }
     authorizeMilestone(repository, milestoneId, expectedRevision, actor, reason = '', delegationGrantId = null) {
-        const { identity } = this.#mutationContext(repository);
-        const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
-        assertExpectedRevision(milestone, expectedRevision);
-        if (milestone.status !== 'awaiting_execution_authorization' || !milestone.planHash) {
-            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is not awaiting authorization.`);
+        const { identity, locks } = this.#mutationContext(repository);
+        const authorityLease = locks.acquire(milestoneId, 'workflow-core:milestone-authority');
+        try {
+            const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
+            assertExpectedRevision(milestone, expectedRevision);
+            if (milestone.status !== 'awaiting_execution_authorization' || !milestone.planHash) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is not awaiting authorization.`);
+            }
+            assertMilestoneDependenciesDeclared(milestone);
+            this.requireActiveKnowledgeMap(identity.repositoryRoot, identity.projectId);
+            const root = this.store.milestoneRoot(identity.projectId, milestoneId);
+            const planHash = this.store.hashArtifact(root, 'plan.json');
+            if (planHash !== milestone.planHash) {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone Plan changed after it was recorded.');
+            }
+            const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'milestone.execution_authorize', actor, milestone);
+            const event = {
+                kind: 'execution',
+                decision: 'approved',
+                actor: actor.trim() || 'user',
+                recordedAt: this.now().toISOString(),
+                briefHash: null,
+                planHash,
+                resultHash: null,
+                evidenceHash: null,
+                headCommit: runGit(identity.repositoryRoot, ['rev-parse', milestone.baseBranch]),
+                reason,
+                authorizationMode: delegation ? 'delegated' : 'human',
+                ...(delegation ? { delegation } : {}),
+            };
+            return this.store.writeMilestone({ ...milestone, status: 'active', planHash, authorizations: [...milestone.authorizations, event] }, expectedRevision);
         }
-        assertMilestoneDependenciesDeclared(milestone);
-        this.requireActiveKnowledgeMap(identity.repositoryRoot, identity.projectId);
-        const root = this.store.milestoneRoot(identity.projectId, milestoneId);
-        const planHash = this.store.hashArtifact(root, 'plan.json');
-        if (planHash !== milestone.planHash) {
-            throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone Plan changed after it was recorded.');
+        finally {
+            locks.release(milestoneId, authorityLease.token);
         }
-        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'milestone.execution_authorize', actor, milestone);
-        const event = {
-            kind: 'execution',
-            decision: 'approved',
-            actor: actor.trim() || 'user',
-            recordedAt: this.now().toISOString(),
-            briefHash: null,
-            planHash,
-            resultHash: null,
-            evidenceHash: null,
-            headCommit: runGit(identity.repositoryRoot, ['rev-parse', milestone.baseBranch]),
-            reason,
-            authorizationMode: delegation ? 'delegated' : 'human',
-            ...(delegation ? { delegation } : {}),
-        };
-        return this.store.writeMilestone({ ...milestone, status: 'active', planHash, authorizations: [...milestone.authorizations, event] }, expectedRevision);
     }
     validateMilestone(repository, milestoneId, expectedRevision) {
-        const { identity } = this.#mutationContext(repository);
-        const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
-        assertExpectedRevision(milestone, expectedRevision);
-        if (!['active', 'awaiting_final_acceptance'].includes(milestone.status)) {
-            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} cannot be validated while ${milestone.status}.`);
-        }
-        this.assertMilestoneAuthorizationFresh(milestone);
-        if (currentBranch(identity.repositoryRoot) !== milestone.baseBranch || !isClean(identity.repositoryRoot)) {
-            throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Milestone validation requires a clean base branch checkout.', {
-                expectedBranch: milestone.baseBranch,
-                actualBranch: currentBranch(identity.repositoryRoot),
-                changedFiles: changedFiles(identity.repositoryRoot),
-            });
-        }
-        const incomplete = milestone.memberships.filter((membership) => {
-            if (membership.disposition !== 'required')
-                return false;
-            return this.store.readTask(identity.projectId, membership.taskId).status !== 'merged';
-        });
-        if (incomplete.length > 0) {
-            throw new WorkflowError('TRANSITION_BLOCKED', 'Required Milestone Tasks are not merged.', {
-                taskIds: incomplete.map((membership) => membership.taskId),
+        const { identity, locks } = this.#mutationContext(repository);
+        const authorityLease = locks.acquire(milestoneId, 'workflow-core:milestone-authority');
+        try {
+            const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
+            assertExpectedRevision(milestone, expectedRevision);
+            if (!['active', 'awaiting_final_acceptance'].includes(milestone.status)) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} cannot be validated while ${milestone.status}.`);
+            }
+            this.assertMilestoneAuthorizationFresh(milestone);
+            if (currentBranch(identity.repositoryRoot) !== milestone.baseBranch || !isClean(identity.repositoryRoot)) {
+                throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Milestone validation requires a clean base branch checkout.', {
+                    expectedBranch: milestone.baseBranch,
+                    actualBranch: currentBranch(identity.repositoryRoot),
+                    changedFiles: changedFiles(identity.repositoryRoot),
+                });
+            }
+            const incomplete = milestone.memberships.filter((membership) => {
+                if (membership.disposition !== 'required')
+                    return false;
+                return this.store.readTask(identity.projectId, membership.taskId).status !== 'merged';
             });
-        }
-        const checks = runChecks(identity.repositoryRoot, milestone.checks);
-        const baseHead = headCommit(identity.repositoryRoot);
-        const root = this.store.milestoneRoot(identity.projectId, milestoneId);
-        const stagedEvidence = this.store.stageArtifact(root, 'evidence.json', JSON.stringify({
-            milestoneId,
-            baseBranch: milestone.baseBranch,
-            headCommit: baseHead,
-            generatedAt: this.now().toISOString(),
-            membershipRevision: milestone.membershipRevision,
-            memberships: milestone.memberships,
-            checks,
-        }, null, 2));
-        if (checks.some((check) => !check.passed)) {
-            const saved = this.store.writeMilestone({ ...milestone, status: 'blocked', evidenceHash: stagedEvidence.hash }, expectedRevision);
+            if (incomplete.length > 0) {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'Required Milestone Tasks are not merged.', {
+                    taskIds: incomplete.map((membership) => membership.taskId),
+                });
+            }
+            const checks = runChecks(identity.repositoryRoot, milestone.checks);
+            const baseHead = headCommit(identity.repositoryRoot);
+            const root = this.store.milestoneRoot(identity.projectId, milestoneId);
+            const stagedEvidence = this.store.stageArtifact(root, 'evidence.json', JSON.stringify({
+                milestoneId,
+                baseBranch: milestone.baseBranch,
+                headCommit: baseHead,
+                generatedAt: this.now().toISOString(),
+                membershipRevision: milestone.membershipRevision,
+                memberships: milestone.memberships,
+                checks,
+            }, null, 2));
+            if (checks.some((check) => !check.passed)) {
+                const saved = this.store.writeMilestone({ ...milestone, status: 'blocked', evidenceHash: stagedEvidence.hash }, expectedRevision);
+                this.store.publishArtifact(stagedEvidence);
+                return saved;
+            }
+            const result = [
+                `# Milestone result: ${milestone.title}`,
+                '',
+                `Outcome: ${milestone.outcome}`,
+                '',
+                `Validated base: ${milestone.baseBranch}@${baseHead}`,
+                '',
+                'All required memberships are merged and all Milestone checks passed.',
+                '',
+            ].join('\n');
+            const stagedResult = this.store.stageArtifact(root, 'result.md', result);
+            const saved = this.store.writeMilestone({
+                ...milestone,
+                status: 'awaiting_final_acceptance',
+                evidenceHash: stagedEvidence.hash,
+                resultHash: stagedResult.hash,
+            }, expectedRevision);
             this.store.publishArtifact(stagedEvidence);
+            this.store.publishArtifact(stagedResult);
             return saved;
         }
-        const result = [
-            `# Milestone result: ${milestone.title}`,
-            '',
-            `Outcome: ${milestone.outcome}`,
-            '',
-            `Validated base: ${milestone.baseBranch}@${baseHead}`,
-            '',
-            'All required memberships are merged and all Milestone checks passed.',
-            '',
-        ].join('\n');
-        const stagedResult = this.store.stageArtifact(root, 'result.md', result);
-        const saved = this.store.writeMilestone({
-            ...milestone,
-            status: 'awaiting_final_acceptance',
-            evidenceHash: stagedEvidence.hash,
-            resultHash: stagedResult.hash,
-        }, expectedRevision);
-        this.store.publishArtifact(stagedEvidence);
-        this.store.publishArtifact(stagedResult);
-        return saved;
+        finally {
+            locks.release(milestoneId, authorityLease.token);
+        }
     }
     acceptMilestone(repository, milestoneId, expectedRevision, actor, confirmationCode, delegationGrantId = null) {
-        const { identity } = this.#mutationContext(repository);
-        const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
-        assertExpectedRevision(milestone, expectedRevision);
-        if (milestone.status !== 'awaiting_final_acceptance' || !milestone.resultHash || !milestone.evidenceHash) {
-            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is not ready for acceptance.`);
-        }
-        if (currentBranch(identity.repositoryRoot) !== milestone.baseBranch || !isClean(identity.repositoryRoot)) {
-            throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Milestone acceptance requires a clean base branch checkout.');
-        }
-        const root = this.store.milestoneRoot(identity.projectId, milestoneId);
-        const evidence = JSON.parse(readFileSync(path.join(root, 'evidence.json'), 'utf8'));
-        const currentHead = headCommit(identity.repositoryRoot);
-        const resultHash = this.store.hashArtifact(root, 'result.md');
-        const evidenceHash = this.store.hashArtifact(root, 'evidence.json');
-        if (evidence.headCommit !== currentHead || resultHash !== milestone.resultHash || evidenceHash !== milestone.evidenceHash) {
-            throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone validation evidence is stale.');
-        }
-        const normalizedActor = actor.trim();
-        if (!normalizedActor) {
-            throw new WorkflowError('INVALID_ARGUMENT', 'Milestone final acceptance requires an explicit actor.');
+        const { identity, locks } = this.#mutationContext(repository);
+        const authorityLease = locks.acquire(milestoneId, 'workflow-core:milestone-authority');
+        try {
+            const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
+            assertExpectedRevision(milestone, expectedRevision);
+            if (milestone.status !== 'awaiting_final_acceptance' || !milestone.resultHash || !milestone.evidenceHash) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is not ready for acceptance.`);
+            }
+            if (currentBranch(identity.repositoryRoot) !== milestone.baseBranch || !isClean(identity.repositoryRoot)) {
+                throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Milestone acceptance requires a clean base branch checkout.');
+            }
+            const root = this.store.milestoneRoot(identity.projectId, milestoneId);
+            const evidence = JSON.parse(readFileSync(path.join(root, 'evidence.json'), 'utf8'));
+            const currentHead = headCommit(identity.repositoryRoot);
+            const resultHash = this.store.hashArtifact(root, 'result.md');
+            const evidenceHash = this.store.hashArtifact(root, 'evidence.json');
+            if (evidence.headCommit !== currentHead || resultHash !== milestone.resultHash || evidenceHash !== milestone.evidenceHash) {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone validation evidence is stale.');
+            }
+            const normalizedActor = actor.trim();
+            if (!normalizedActor) {
+                throw new WorkflowError('INVALID_ARGUMENT', 'Milestone final acceptance requires an explicit actor.');
+            }
+            const gate = milestoneFinalAcceptanceGate(milestone, currentHead);
+            if (confirmationCode.trim() !== gate.confirmationCode) {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone final acceptance confirmation does not match the current validated state.', {
+                    milestoneId,
+                    revision: milestone.revision,
+                });
+            }
+            const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'milestone.final_accept', normalizedActor, milestone);
+            const event = {
+                kind: 'final_acceptance',
+                decision: 'approved',
+                actor: normalizedActor,
+                recordedAt: this.now().toISOString(),
+                briefHash: null,
+                planHash: milestone.planHash,
+                resultHash,
+                evidenceHash,
+                headCommit: currentHead,
+                reason: 'Milestone final acceptance confirmed against the current validated state.',
+                authorizationMode: delegation ? 'delegated' : 'human',
+                ...(delegation ? { delegation } : {}),
+            };
+            return this.store.writeMilestone({
+                ...milestone,
+                status: 'accepted',
+                resultHash,
+                evidenceHash,
+                acceptedHead: currentHead,
+                authorizations: [...milestone.authorizations, event],
+            }, expectedRevision);
         }
-        const gate = milestoneFinalAcceptanceGate(milestone, currentHead);
-        if (confirmationCode.trim() !== gate.confirmationCode) {
-            throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone final acceptance confirmation does not match the current validated state.', {
-                milestoneId,
-                revision: milestone.revision,
-            });
+        finally {
+            locks.release(milestoneId, authorityLease.token);
         }
-        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'milestone.final_accept', normalizedActor, milestone);
-        const event = {
-            kind: 'final_acceptance',
-            decision: 'approved',
-            actor: normalizedActor,
-            recordedAt: this.now().toISOString(),
-            briefHash: null,
-            planHash: milestone.planHash,
-            resultHash,
-            evidenceHash,
-            headCommit: currentHead,
-            reason: 'Milestone final acceptance confirmed against the current validated state.',
-            authorizationMode: delegation ? 'delegated' : 'human',
-            ...(delegation ? { delegation } : {}),
-        };
-        return this.store.writeMilestone({
-            ...milestone,
-            status: 'accepted',
-            resultHash,
-            evidenceHash,
-            acceptedHead: currentHead,
-            authorizations: [...milestone.authorizations, event],
-        }, expectedRevision);
     }
     cancelMilestone(repository, milestoneId, expectedRevision, reason) {
         if (!reason.trim())
             throw new WorkflowError('INVALID_ARGUMENT', 'Milestone cancellation requires a reason.');
-        const { identity } = this.#mutationContext(repository);
-        const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
-        assertExpectedRevision(milestone, expectedRevision);
-        if (['accepted', 'cancelled'].includes(milestone.status)) {
-            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is ${milestone.status}.`);
+        const { identity, locks } = this.#mutationContext(repository);
+        const authorityLease = locks.acquire(milestoneId, 'workflow-core:milestone-authority');
+        try {
+            const milestone = this.readMilestoneCurrent(identity.projectId, milestoneId);
+            assertExpectedRevision(milestone, expectedRevision);
+            if (['accepted', 'cancelled'].includes(milestone.status)) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is ${milestone.status}.`);
+            }
+            return this.store.writeMilestone({ ...milestone, status: 'cancelled', cancellationReason: reason.trim() }, expectedRevision);
+        }
+        finally {
+            locks.release(milestoneId, authorityLease.token);
         }
-        return this.store.writeMilestone({ ...milestone, status: 'cancelled', cancellationReason: reason.trim() }, expectedRevision);
     }
     setTaskPlan(repository, taskId, expectedRevision, plan, correctiveAudit = null, planRiskAudit = null) {
         validatePlan(plan);
@@ -4231,7 +4296,7 @@ export class WorkflowService {
             throw new WorkflowError('NOT_FOUND', `Task ${taskId} was not found in this repository.`);
         const versions = inspectWorkflowVersions(snapshot.identity.repositoryRoot, [task.baseBranch]);
         const sourceVersion = '2.0.0-beta.13.6';
-        const targetVersion = '2.0.0-beta.13.7';
+        const targetVersion = '2.0.0-beta.13.8';
         const sourceSurfaces = {
             declared: versions.declared,
             locked: versions.locked,
@@ -4330,7 +4395,7 @@ export class WorkflowService {
     consumedCarryoverSourceRecoveryPreflight(snapshot, task, sourceSurfaces, candidate) {
         const repositoryRoot = snapshot.identity.repositoryRoot;
         const sourceVersion = '2.0.0-beta.13.6';
-        const targetVersion = '2.0.0-beta.13.7';
+        const targetVersion = '2.0.0-beta.13.8';
         const c1 = readTaskC1Posture(this.store, task);
         const recorded = [...(task.dependencyProvenanceRecoveries ?? [])].reverse().find((record) => record.rootCauseReplan && task.systemCommits.includes(record.commitSha))?.rootCauseReplan;
         const currentHead = headCommit(repositoryRoot);
@@ -5337,6 +5402,18 @@ export class WorkflowService {
         const existing = this.readGraphBindingOrNull(identity.projectId, graphKind);
         return this.store.writeGraphBinding(fallbackGraphBinding(identity.projectId, request, reason, existing, this.now()), expectedRevision);
     }
+    explainChange(repository, taskId, input) {
+        const status = this.statusFromSnapshot(this.observationSnapshot(repository));
+        const task = status.tasks.find(candidate => candidate.id === taskId);
+        if (!task && status.observation.kind === 'assessment') {
+            throw new WorkflowError('INVALID_ARGUMENT', 'The requested Task is not present in the current observation.');
+        }
+        const navigation = this.nextFromStatus(repository, taskId, status);
+        const step = task?.steps.find(candidate => candidate.id === navigation.stepId)
+            ?? task?.steps.find(candidate => candidate.status === 'in_progress' || candidate.status === 'failed');
+        const effectiveTask = task && step ? taskWithEffectiveStepAllowedWrites(this.store, task, step.id) : task;
+        return explainChange(input, repository, effectiveTask, navigation);
+    }
     next(repository, taskId = null) {
         return withObservedRouteMetadata(this.nextFromStatus(repository, taskId, this.statusFromSnapshot(this.observationSnapshot(repository))));
     }
@@ -5448,6 +5525,37 @@ export class WorkflowService {
         }
         const withAdoption = (value) => ({
             ...value,
+            ...(status.milestones.some((milestone) => milestone.status === 'active' && milestone.planHash)
+                ? { activeMilestoneAutonomyOptions: status.milestones
+                        .filter((milestone) => milestone.status === 'active' && milestone.planHash)
+                        .filter((milestone) => {
+                        const event = readMilestoneAutonomyEvents(this.store, status.projectId, milestone.id).at(-1);
+                        if (!event)
+                            return true;
+                        try {
+                            requireActiveMilestoneAutonomy({
+                                store: this.store, projectId: status.projectId, milestone,
+                                actor: event.delegate, now: this.now(),
+                            });
+                            return false;
+                        }
+                        catch (error) {
+                            if (error instanceof WorkflowError && error.code === 'TRANSITION_BLOCKED')
+                                return true;
+                            if (error instanceof WorkflowError && error.code === 'NOT_FOUND')
+                                return true;
+                            throw error;
+                        }
+                    })
+                        .map((milestone) => ({
+                        action: 'milestone autonomy-prepare',
+                        milestoneId: milestone.id,
+                        expectedRevision: milestone.revision,
+                        requiresExactHumanConfirmation: true,
+                        maximumDurationHours: 72,
+                        preparationRequired: true,
+                        meaning: 'Optional human-requested preparation; existing valid contracts cannot be replaced. Knowledge must be active.',
+                    })) } : {}),
             adoption: adoptionInfo,
             observation: status.observation,
         });
@@ -7119,12 +7227,50 @@ export class WorkflowService {
                 }
                 : {}),
         };
+        // A later independent audit may discover an obstruction absent from the sealed
+        // fix review. Advertise the existing append-only decision route without turning
+        // every ordinary repair into a mandatory replan or rewriting that review.
+        const correctiveDecisionOrdinal = failedStepRemediations.length + 1;
+        const optionalCorrectiveDecision = result.action === 'task run'
+            && ['needs_fix', 'ready'].includes(task.status)
+            && failedStep && task.planHash && planRiskAudit
+            && planRiskAudit.reviewRequiredStepIds.includes(failedStep.id)
+            && !task.steps.some(step => step.status === 'in_progress')
+            && failedStepRemediations.length >= 2
+            && handoffPosture.state !== 'pending'
+            && !readCorrectiveDecisionEvents(this.store, task).some(event => event.stepId === failedStep.id && event.triggeringAttemptCount === correctiveDecisionOrdinal)
+            && currentBranch(repositoryRoot) === task.taskBranch && isClean(repositoryRoot)
+            ? {
+                command: 'task corrective-decision',
+                state: 'eligible',
+                optional: true,
+                taskId: task.id,
+                stepId: failedStep.id,
+                expectedRevision: task.revision,
+                expectedBriefHash: task.briefHash,
+                expectedPlanHash: task.planHash,
+                expectedHeadCommit: headCommit(repositoryRoot),
+                triggeringAttemptCount: correctiveDecisionOrdinal,
+                coveredRemediationEvents: failedStepRemediations.map(event => ({ eventId: event.eventId, eventHash: event.eventHash })),
+                recommendedAuditor: defaultCorrectiveAuditorActor(task.id),
+                auditorMustDifferFromLatestStrictReviewer: true,
+                requiredActor: handoffPosture.state === 'claimed' ? handoffPosture.claimant : null,
+                decisions: ['continue-fix', 'replan-required', 'split-required', 'stop-escalate'],
+                authority: 'none',
+                preservesOriginalReview: true,
+                humanApprovalRequiredForDecision: false,
+                replanRequiresExistingHumanGate: true,
+                requiredAction: 'Only for newly assessed evidence: obtain an independent corrective audit, refresh next and existing writer authority, then record the decision. This option does not authorize Plan replacement or extra writes.',
+            }
+            : null;
+        const resultWithCorrectiveOption = optionalCorrectiveDecision
+            ? { ...result, correctiveDecisionOption: optionalCorrectiveDecision } : result;
         const rootCauseAllowsPendingClaim = !rootCauseReplanDirtyCarryover?.applicable
             || (rootCauseReplanDirtyCarryover.blockers.length === 1
                 && rootCauseReplanDirtyCarryover.blockers[0]?.startsWith('Corrective carryover requires the retained claimed C1'));
         if (handoffPosture.state === 'pending' && rootCauseAllowsPendingClaim) {
             return this.withTaskNavigationContracts(task, {
-                ...result,
+                ...resultWithCorrectiveOption,
                 action: 'task claim',
                 blockedAction: next.action,
             });
@@ -7132,10 +7278,10 @@ export class WorkflowService {
         const navigableResult = ['task plan-set']
             .includes(String(result.action))
             ? {
-                ...result,
+                ...resultWithCorrectiveOption,
                 taskPlanContract: this.taskPlanContract(projectId, task),
             }
-            : result;
+            : resultWithCorrectiveOption;
         return this.withTaskNavigationContracts(task, navigableResult);
     }
     taskPlanContract(projectId, task) {
@@ -7245,7 +7391,7 @@ export class WorkflowService {
         }
     }
     delegatedApprovalOptions(projectId, transition, target) {
-        return this.store.listDelegations(projectId)
+        return this.listDelegations(projectId)
             .filter((grant) => {
             try {
                 return Boolean(this.delegatedAuthorization(projectId, grant.id, transition, grant.delegate, target));
@@ -7267,7 +7413,7 @@ export class WorkflowService {
         }));
     }
     delegatedContextRefreshOptions(projectId, task, knowledgeMap, mode) {
-        return this.store.listDelegations(projectId)
+        return this.listDelegations(projectId)
             .filter((grant) => {
             try {
                 if (mode === 'delegated-plan-bounded-supporting-source') {