baxian 2.0.0 → 2.0.1

package/dist/agent/manager.js

@@ -4,7 +4,7 @@ import { join, normalize } from 'node:path';
 import { tmpdir } from 'node:os';
 import { createSignalToken, PASSIVE_VERDICT_WATCH } from './phase-signal.js';
 import { tmuxInstallHint } from './preflight.js';
-import { BRANCH_PREFIX, isValidBranchName, PHASE_EXPECTED_STATUS, PHASE_REQUIRES_AGENT_BOUND_TO_TASK, TASK_TERMINAL_STATUSES as TERMINAL_STATUSES, TASK_ACTIVE_STATUS_SET as ACTIVE_TASK_STATUSES, TASK_OWNER_ROLES, isSpecStagePhase, isGitHubRepo, parseGitRemote, repoIdentityKey, repoSlug, } from '../shared/index.js';
+import { BRANCH_PREFIX, isValidBranchName, PHASE_EXPECTED_STATUS, PHASE_REQUIRES_AGENT_BOUND_TO_TASK, TASK_TERMINAL_STATUSES as TERMINAL_STATUSES, TASK_ACTIVE_STATUS_SET as ACTIVE_TASK_STATUSES, TASK_OWNER_ROLES, isSpecStagePhase, isGitHubRepo, parseGitRemote, repoIdentityKey, repoSlug, taskGenerationGuard, taskMatchesGeneration, } from '../shared/index.js';
 import { buildProjectDriver, makeDriverExec } from '../platform/driver-host.js';
 import { DriverOpError, buildDriverRunContext, GitDriver, safeDriverErrorText } from '../platform/git-driver.js';
 import { checkOpenPrBinding, checkPrBinding } from '../platform/pr-binding.js';
@@ -28,6 +28,14 @@ import { ApiError } from '../errors.js';
 import { prepareConfig } from '../config/loader.js';
 import { projectAfterDone, projectReviewMode, resolveProjectTool } from '../config/validator.js';
 import { SHA_HEX_SOURCE } from '../platform/types.js';
+// 这两个入口冲突证明当前调用已被并发 pass 接管，应判 stale 而不是派发失败。
+const BENIGN_DISPATCH_CONFLICT_CODES = new Set(['dispatch-superseded', 'dispatch-in-flight']);
+export function isBenignDispatchConflict(err) {
+    return err instanceof ApiError
+        && err.status === 409
+        && err.code !== undefined
+        && BENIGN_DISPATCH_CONFLICT_CODES.has(err.code);
+}
 export class EnsureSessionError extends Error {
     partial;
     constructor(partial, message) {
@@ -185,6 +193,13 @@ export function isRecoverableQaDispatchHold(binding) {
         && binding.awaitingPhase != null
         && RECOVERABLE_QA_DISPATCH_HOLD_PHASES.has(binding.awaitingPhase);
 }
+function shouldBumpServerReviewRound(requested, task, qaBinding) {
+    if (requested !== undefined)
+        return requested;
+    return !(task.status === 'review'
+        && qaBinding?.taskId === task.id
+        && isRecoverableQaDispatchHold(qaBinding));
+}
 const TURN_COMPLETED_AWAITING_PHASES = new Set();
 const CANCEL_CLEANUP_HOLD_PHASES = new Set(['cancel-clearing', 'cancel-interrupt-failed']);
 function isCancelCleanupHold(binding) {
@@ -366,6 +381,42 @@ export class AgentManager {
     getReviewStore() {
         return this.reviewStore;
     }
+    async putReviewRoundIfCurrent(taskId, data, expectedTask) {
+        return this.withTaskLock(async () => {
+            const task = await this.taskStore.get(taskId);
+            if (!task || !taskMatchesGeneration(task, expectedTask))
+                return false;
+            if (!this.reviewStore)
+                throw new Error('ReviewStore is not configured');
+            await this.reviewStore.putRound(taskId, data.phase, data);
+            return true;
+        });
+    }
+    async deleteReviewExchangeIfCurrent(taskId, agent, artifact, expectedTask, expectedRecovery) {
+        return this.withTaskLock(async () => {
+            const task = await this.taskStore.get(taskId);
+            if (!task || !taskMatchesGeneration(task, expectedTask))
+                return false;
+            const recovery = task.serverSignalRecovery;
+            if (expectedRecovery && (!recovery
+                || recovery.mode !== expectedRecovery.mode
+                || recovery.signalKind !== expectedRecovery.signalKind
+                || recovery.phase !== expectedRecovery.phase
+                || recovery.round !== expectedRecovery.round
+                || recovery.sourceToken !== expectedRecovery.sourceToken
+                || recovery.failureSignature !== expectedRecovery.failureSignature
+                || recovery.createdAt !== expectedRecovery.createdAt))
+                return false;
+            const transport = this.getReviewTransport();
+            if (artifact === 'findings') {
+                await transport.deleteFindings(agent);
+            }
+            else {
+                await transport.deleteResponse(agent);
+            }
+            return true;
+        });
+    }
     setServerReviewDriver(driver) {
         this.serverReviewDriver = driver;
     }
@@ -382,11 +433,14 @@ export class AgentManager {
         const project = this.getProjectConfig(projectId);
         return project ? projectAfterDone(this.config, project) : (this.config.review.afterDone ?? null);
     }
-    async commitServerAfterDone(taskId) {
+    async commitServerAfterDone(taskId, expectedTask) {
         return this.withTaskLock(async () => {
             const task = await this.taskStore.get(taskId);
             if (!task)
                 throw new ApiError(404, `Task ${taskId} not found`);
+            if (expectedTask && !taskMatchesGeneration(task, expectedTask)) {
+                throw new ApiError(409, `Task ${taskId} review generation changed before afterDone was committed`, 'dispatch-superseded');
+            }
             if (task.afterDone === 'pr' && task.platformBinding === undefined) {
                 throw new Error(`platform binding missing for task ${task.id}; refusing to reconstruct it from live config`);
             }
@@ -1814,9 +1868,13 @@ export class AgentManager {
             }
             if (opts.expectedTask
                 && boundTask
-                && (boundTask.status !== opts.expectedTask.status
-                    || boundTask.phase !== opts.expectedTask.phase
-                    || boundTask.signalToken !== opts.expectedTask.signalToken)) {
+                && (('status' in opts.expectedTask && boundTask.status !== opts.expectedTask.status)
+                    || ('phase' in opts.expectedTask && boundTask.phase !== opts.expectedTask.phase)
+                    || ('signalToken' in opts.expectedTask && boundTask.signalToken !== opts.expectedTask.signalToken)
+                    || ('agentId' in opts.expectedTask && boundTask.agentId !== opts.expectedTask.agentId)
+                    || ('reviewRound' in opts.expectedTask && boundTask.reviewRound !== opts.expectedTask.reviewRound)
+                    || ('specReviewRound' in opts.expectedTask
+                        && boundTask.specReviewRound !== opts.expectedTask.specReviewRound))) {
                 console.warn(`[AgentManager] releaseAgentForTask: task ${expectedTaskId} moved past the captured pass; skipping ${mode} transition`);
                 return false;
             }
@@ -2930,6 +2988,9 @@ export class AgentManager {
                             status: boundTask.status,
                             phase: boundTask.phase,
                             signalToken: boundTask.signalToken,
+                            agentId: boundTask.agentId,
+                            reviewRound: boundTask.reviewRound,
+                            specReviewRound: boundTask.specReviewRound,
                         },
                         heldLockToken: state.lockToken,
                         projectId: state.projectId,
@@ -3106,6 +3167,7 @@ export class AgentManager {
                     fromStatus: ['review'],
                     expectPhase: reviewPass.phase,
                     expectSignalToken: reviewPass.signalToken,
+                    expectedTask: reviewPass,
                     ...(resumeQaPhase !== undefined ? { qaPhase: resumeQaPhase } : {}),
                     onQaAcquired: (lockToken) => { recoveryLockToken = lockToken; },
                 });
@@ -3163,9 +3225,7 @@ export class AgentManager {
                 let recoveryReadFailed = false;
                 try {
                     const taskNow = await this.taskStore.get(reviewTaskId);
-                    passSuperseded = taskNow?.status !== reviewPass.status
-                        || taskNow.phase !== reviewPass.phase
-                        || taskNow.signalToken !== reviewPass.signalToken;
+                    passSuperseded = !taskNow || !taskMatchesGeneration(taskNow, reviewPass);
                 }
                 catch (readErr) {
                     recoveryReadFailed = true;
@@ -3386,9 +3446,16 @@ export class AgentManager {
             ...(opts.expectedReviewDispatch !== undefined
                 ? { expectReviewDispatch: opts.expectedReviewDispatch }
                 : {}),
+            ...(opts.expectedTask !== undefined ? { expectTask: opts.expectedTask } : {}),
+            ...(opts.expectedLockToken !== undefined
+                ? { expectAgentLock: { agentId, token: opts.expectedLockToken } }
+                : {}),
         });
         if (!transitioned
-            && (opts.expectedPostApproveEpisode !== undefined || opts.expectedReviewDispatch !== undefined)) {
+            && (opts.expectedPostApproveEpisode !== undefined
+                || opts.expectedReviewDispatch !== undefined
+                || opts.expectedTask !== undefined
+                || opts.expectedLockToken !== undefined)) {
             console.warn(`[AgentManager] failTaskForDispatchError: dispatch generation for ${taskId} was superseded; skipping stale failure`);
             return;
         }
@@ -3732,11 +3799,14 @@ export class AgentManager {
                 retireOldOnce();
         }
     }
-    async redispatchTaskPromptAfterReplRestart(agentId, taskId) {
+    async redispatchTaskPromptAfterReplRestart(agentId, taskId, expected) {
         const agent = this.getAgentConfig(agentId);
         const loadedTask = await this.taskStore.get(taskId);
         if (!agent || !loadedTask || !TASK_OWNER_ROLES.has(agent.role))
             return false;
+        if (expected && !taskMatchesGeneration(loadedTask, expected))
+            return false;
+        const rootGenerationMatches = (fresh, signalToken = expected?.signalToken) => !expected || taskMatchesGeneration(fresh, { ...expected, signalToken });
         let task = loadedTask;
         if (task.agentId !== agentId)
             return false;
@@ -3754,7 +3824,8 @@ export class AgentManager {
             return fresh?.agentId === agentId
                 && fresh.status === task.status
                 && fresh.phase === task.phase
-                && fresh.signalToken === signalToken;
+                && fresh.signalToken === signalToken
+                && rootGenerationMatches(fresh, signalToken);
         };
         const clearEntryHold = async () => this.withTaskLock(async () => {
             if (!(await taskStillCurrent()))
@@ -3765,10 +3836,10 @@ export class AgentManager {
             }
             return this.clearAwaitingHuman(agentId, { expectedHold: entryHold });
         });
-        const holdReplayFailure = (phase, reason) => this.holdReplayFailureIfCurrent(agentId, task, phase, reason, entryHold);
+        const holdReplayFailure = (phase, reason) => this.holdReplayFailureIfCurrent(agentId, task, phase, reason, entryHold, async (fresh) => rootGenerationMatches(fresh, task.signalToken));
         try {
             if (task.status === 'approved' && agent.role === 'dev') {
-                return await this.replayApprovedHolderAfterReplRestart(agentId, task, entryHold, { clearEntryHold, holdReplayFailure });
+                return await this.replayApprovedHolderAfterReplRestart(agentId, task, entryHold, { clearEntryHold, holdReplayFailure, rootGenerationMatches });
             }
             if (task.serverSignalRecovery) {
                 const recovery = task.serverSignalRecovery;
@@ -3809,7 +3880,8 @@ export class AgentManager {
                     if (fresh?.agentId !== agentId
                         || fresh.status !== task.status
                         || fresh.phase !== task.phase
-                        || fresh.signalToken !== signalToken)
+                        || fresh.signalToken !== signalToken
+                        || !rootGenerationMatches(fresh, signalToken))
                         return false;
                     const rotatePendingPr = mapped.expectedKinds.includes('pr-created')
                         && fresh.pendingPrSignalToken === signalToken;
@@ -3822,7 +3894,7 @@ export class AgentManager {
                     return true;
                 },
                 stillCurrent: taskStillCurrent,
-                holdFailure: (newToken, reason) => this.holdReplayFailureIfCurrent(agentId, { ...task, signalToken: newToken }, 'restart-redispatch-failed', reason, entryHold),
+                holdFailure: (newToken, reason) => this.holdReplayFailureIfCurrent(agentId, { ...task, signalToken: newToken }, 'restart-redispatch-failed', reason, entryHold, async (fresh) => rootGenerationMatches(fresh, newToken)),
                 continueWith: (newToken, fence) => this.continueSession(taskId, agentId, phase, {
                     ...opts,
                     signalToken: newToken,
@@ -3921,10 +3993,49 @@ export class AgentManager {
             throw err;
         }
     }
+    async redispatchCurrentTaskPhase(taskId, expected) {
+        const current = await this.taskStore.get(taskId);
+        if (!current || !taskMatchesGeneration(current, expected))
+            return 'stale';
+        if (current.status === 'review') {
+            let changedByRedispatch = false;
+            try {
+                await this.dispatchReviewToQa(taskId, {
+                    fromStatus: ['review'],
+                    bumpRound: false,
+                    expectSignalToken: current.signalToken,
+                    expectPhase: current.phase,
+                    expectedTask: expected,
+                    onSideEffect: () => { changedByRedispatch = true; },
+                });
+                return 'dispatched';
+            }
+            catch (err) {
+                if (!changedByRedispatch && isBenignDispatchConflict(err))
+                    return 'stale';
+                if (!changedByRedispatch
+                    && err instanceof ApiError
+                    && err.code === 'dispatch-unsupported') {
+                    return 'unsupported';
+                }
+                if (changedByRedispatch)
+                    throw err;
+                const fresh = await this.taskStore.get(taskId);
+                if (!fresh || !taskMatchesGeneration(fresh, expected))
+                    return 'stale';
+                throw err;
+            }
+        }
+        const redispatched = await this.redispatchTaskPromptAfterReplRestart(current.agentId, taskId, expected);
+        if (redispatched)
+            return 'dispatched';
+        const fresh = await this.taskStore.get(taskId);
+        return !fresh || !taskMatchesGeneration(fresh, expected) ? 'stale' : 'unsupported';
+    }
     // approved hosts two live holder passes — post-approve and server after-done; a parked pre-publish holder stays on the waiting path.
     async replayApprovedHolderAfterReplRestart(agentId, task, entryHold, holdGen) {
         const taskId = task.id;
-        const { clearEntryHold, holdReplayFailure } = holdGen;
+        const { clearEntryHold, holdReplayFailure, rootGenerationMatches } = holdGen;
         if (task.reviewMode === 'server') {
             if (!task.publishDispatchedAt)
                 return false;
@@ -3954,7 +4065,8 @@ export class AgentManager {
                 return fresh?.agentId === agentId
                     && fresh.status === task.status
                     && fresh.phase === task.phase
-                    && fresh.signalToken === signalToken;
+                    && fresh.signalToken === signalToken
+                    && rootGenerationMatches(fresh, signalToken);
             };
             return this.runRotatedReplay({
                 agentId,
@@ -3966,13 +4078,14 @@ export class AgentManager {
                     if (fresh?.agentId !== agentId
                         || fresh.status !== task.status
                         || fresh.phase !== task.phase
-                        || fresh.signalToken !== token)
+                        || fresh.signalToken !== token
+                        || !rootGenerationMatches(fresh, token))
                         return false;
                     await this.taskStore.set({ ...fresh, signalToken: newToken, updatedAt: new Date().toISOString() });
                     return true;
                 },
                 stillCurrent,
-                holdFailure: (newToken, reason) => this.holdReplayFailureIfCurrent(agentId, { ...task, signalToken: newToken }, 'restart-redispatch-failed', reason, entryHold),
+                holdFailure: (newToken, reason) => this.holdReplayFailureIfCurrent(agentId, { ...task, signalToken: newToken }, 'restart-redispatch-failed', reason, entryHold, async (fresh) => rootGenerationMatches(fresh, newToken)),
                 continueWith: (newToken, fence) => this.continueSession(taskId, agentId, 'server-after-done', {
                     signalToken: newToken,
                     preserveDispatchOutputs: true,
@@ -4014,6 +4127,7 @@ export class AgentManager {
             && fresh.status === task.status
             && fresh.phase === task.phase
             && fresh.signalToken === task.signalToken
+            && rootGenerationMatches(fresh, task.signalToken)
             && fresh.reviewMode === task.reviewMode
             && fresh.postApproveRevoked === undefined
             && fresh.postApproveHeadSha === task.postApproveHeadSha
@@ -4675,6 +4789,8 @@ export class AgentManager {
             const current = await this.taskStore.get(taskId);
             if (!current || current.reviewMode !== 'git' || TERMINAL_STATUSES.includes(current.status))
                 return null;
+            if (opts.expectedTask && !taskMatchesGeneration(current, opts.expectedTask))
+                return null;
             if (!opts.fromStatus.includes(current.status))
                 return null;
             if (current.reviewDispatch?.phase === 'uncertain')
@@ -4726,7 +4842,7 @@ export class AgentManager {
             return { task: next, previousStatus };
         });
     }
-    async claimGitReviewDispatch(taskId, expectedGeneration) {
+    async claimGitReviewDispatch(taskId, expectedGeneration, expectedTask) {
         return this.withTaskLock(async () => {
             if (this.markCompleteInFlight.has(taskId))
                 return null;
@@ -4734,6 +4850,8 @@ export class AgentManager {
             const lease = task?.reviewDispatch;
             if (!task || !lease || lease.phase !== 'pending')
                 return null;
+            if (expectedTask && !taskMatchesGeneration(task, expectedTask))
+                return null;
             if (expectedGeneration !== undefined && lease.generation !== expectedGeneration)
                 return null;
             if (!this.gitReviewLeaseMatches(task, lease))
@@ -5320,7 +5438,9 @@ export class AgentManager {
                 return;
             }
             try {
-                await this.getReviewTransport().deleteResponse(dev);
+                const deleted = await this.deleteReviewExchangeIfCurrent(task.id, dev, 'response', taskGenerationGuard(fresh), current);
+                if (!deleted)
+                    return;
             }
             catch (err) {
                 await hold(`server-${recovery.phase}-feedback-recovery-cleanup-failed`, `The rejected response was archived but could not be removed during recovery: `
@@ -5344,10 +5464,16 @@ export class AgentManager {
             const scanSnapshotOnRecover = isServerProtocol
                 || (task.phase === undefined && task.status === 'in_progress')
                 || (!specStage && (task.status === 'review' || task.status === 'fixing'));
+            // 侧道读 dev workdir，对 head 评审会注入未验证内容——mode 不明时关侧道、发干预交人工。
             const allowRecoveredReadFile = task.status === 'review'
                 && (specStage
                     || (task.reviewMode === 'server' && task.batchTotal !== undefined)
                     || (task.reviewMode === 'server' && task.reviewCheckoutMode === 'base'));
+            const ambiguousCheckout = task.status === 'review'
+                && task.reviewMode === 'server'
+                && !specStage
+                && task.reviewCheckoutMode === undefined
+                && task.batchTotal === undefined;
             try {
                 await this.startPhaseSignalWatch({
                     taskId: task.id,
@@ -5362,12 +5488,29 @@ export class AgentManager {
                         ? { onReadFile: (req) => { void this.handleReadFileRequest(task.id, agentId, req); } }
                         : {}),
                 });
-                if (interventionKindLabel) {
-                    await this.emitIntervention(task.projectId, agentId, task.id, {
-                        phase: 'spec-signal-setup-during-recovery',
-                        kind: interventionKindLabel,
-                        note: 'Task is waiting for a spec signal after server recovery; if no signal arrives, the prompt may not have been fully delivered before the previous crash. Inspect the agent pane and consider manual retry or transition.',
-                    });
+                if (interventionKindLabel || ambiguousCheckout) {
+                    // snapshot 命中完成信号时不发邀请手工 retry 的干预：结算窗口内的人工重派正是要杜绝的入口；
+                    // 结算若推进了任务态（token 轮换/状态离开），该干预已无的放矢。
+                    if (this.phaseSignalWatcher?.isSettling(task.id)) {
+                        await this.phaseSignalWatcher.awaitSettled(task.id);
+                        const fresh = await this.taskStore.get(task.id);
+                        if (!fresh || fresh.status !== task.status || fresh.signalToken !== signalToken) {
+                            return;
+                        }
+                    }
+                    if (ambiguousCheckout) {
+                        await this.emitIntervention(task.projectId, agentId, task.id, {
+                            phase: 'server-review-recovery-ambiguous-checkout',
+                            note: 'The recovered server code review has no persisted checkout mode (crash before persist, or a pre-rename base task rewritten since). The read-file side-channel stays closed because it reads the dev workdir, not the reviewed head. Inspect the QA pane; redispatch the review to converge on a verified head checkout.',
+                        });
+                    }
+                    if (interventionKindLabel) {
+                        await this.emitIntervention(task.projectId, agentId, task.id, {
+                            phase: 'spec-signal-setup-during-recovery',
+                            kind: interventionKindLabel,
+                            note: 'Task is waiting for a spec signal after server recovery; if no signal arrives, the prompt may not have been fully delivered before the previous crash. Inspect the agent pane and consider manual retry or transition.',
+                        });
+                    }
                 }
             }
             catch (err) {
@@ -5796,6 +5939,29 @@ export class AgentManager {
             return;
         }
         if (branch.headSha === undefined) {
+            try {
+                await this.eventBus.emit({
+                    id: `outbox:${task.id}:${intent.prNumber}:remote-branch-deleted:${generation}`,
+                    type: 'task.updated',
+                    timestamp: new Date().toISOString(),
+                    projectId: task.projectId,
+                    taskId: task.id,
+                    data: {
+                        status: task.status,
+                        operation: 'git-branch-delete',
+                        outcome: 'succeeded',
+                        generation,
+                        prNumber: intent.prNumber,
+                        branch: intent.branch,
+                        expectedHeadSha: intent.expectedHeadSha,
+                        remoteProjectId: intent.remoteProjectId,
+                    },
+                });
+            }
+            catch (err) {
+                await this.recordRemoteCleanupFailure(task, generation, 'persist', safeDriverErrorText(err));
+                throw err;
+            }
             await this.mutateRemoteCleanup(taskId, generation, () => undefined);
             return;
         }
@@ -5996,6 +6162,8 @@ export class AgentManager {
                 return false;
             if ('phase' in alsoExpect && task.phase !== alsoExpect.phase)
                 return false;
+            if ('agentId' in alsoExpect && task.agentId !== alsoExpect.agentId)
+                return false;
             if ('reviewRound' in alsoExpect && task.reviewRound !== alsoExpect.reviewRound)
                 return false;
             if ('specReviewRound' in alsoExpect && task.specReviewRound !== alsoExpect.specReviewRound)
@@ -6194,38 +6362,52 @@ export class AgentManager {
     }
     async transitionTaskStatus(taskId, toStatus, guard, patch) {
         return this.withTaskLock(async () => {
-            const task = await this.taskStore.get(taskId);
-            if (!task)
-                return null;
-            const previousStatus = task.status;
-            if (TERMINAL_STATUSES.includes(previousStatus))
-                return null;
-            if (!guard.fromStatus.includes(previousStatus))
-                return null;
-            if (Object.hasOwn(guard, 'expectSignalToken') && task.signalToken !== guard.expectSignalToken)
-                return null;
-            if (Object.hasOwn(guard, 'expectPhase') && task.phase !== guard.expectPhase)
-                return null;
-            if (guard.expectPostApproveEpisode !== undefined
-                && !this.postApproveEpisodeMatches(task, guard.expectPostApproveEpisode))
-                return null;
-            if (guard.expectReviewDispatch !== undefined
-                && !this.gitReviewDispatchMatches(task, guard.expectReviewDispatch))
-                return null;
-            if (patch?.branch && patch.branch !== task.branch) {
-                const existing = await this.findTaskByBranch(patch.branch, task.projectId);
-                if (existing && existing.id !== taskId)
+            const transition = async () => {
+                if (guard.expectAgentLock) {
+                    const binding = await this.agentStore.get(guard.expectAgentLock.agentId);
+                    if (binding?.taskId !== taskId
+                        || binding.lockToken !== guard.expectAgentLock.token)
+                        return null;
+                }
+                const task = await this.taskStore.get(taskId);
+                if (!task)
                     return null;
-            }
-            const next = this.stripGitStatusScopedState(task, toStatus);
-            if (previousStatus !== toStatus)
-                delete next.serverSignalRecovery;
-            Object.assign(next, patch ?? {}, {
-                status: toStatus,
-                updatedAt: new Date().toISOString(),
-            });
-            await this.taskStore.set(next);
-            return { task: next, previousStatus };
+                const previousStatus = task.status;
+                if (TERMINAL_STATUSES.includes(previousStatus))
+                    return null;
+                if (!guard.fromStatus.includes(previousStatus))
+                    return null;
+                if (guard.expectTask && !taskMatchesGeneration(task, guard.expectTask))
+                    return null;
+                if (Object.hasOwn(guard, 'expectSignalToken') && task.signalToken !== guard.expectSignalToken)
+                    return null;
+                if (Object.hasOwn(guard, 'expectPhase') && task.phase !== guard.expectPhase)
+                    return null;
+                if (guard.expectPostApproveEpisode !== undefined
+                    && !this.postApproveEpisodeMatches(task, guard.expectPostApproveEpisode))
+                    return null;
+                if (guard.expectReviewDispatch !== undefined
+                    && !this.gitReviewDispatchMatches(task, guard.expectReviewDispatch))
+                    return null;
+                if (patch?.branch && patch.branch !== task.branch) {
+                    const existing = await this.findTaskByBranch(patch.branch, task.projectId);
+                    if (existing && existing.id !== taskId)
+                        return null;
+                }
+                const next = this.stripGitStatusScopedState(task, toStatus);
+                if (previousStatus !== toStatus)
+                    delete next.serverSignalRecovery;
+                Object.assign(next, patch ?? {}, {
+                    status: toStatus,
+                    updatedAt: new Date().toISOString(),
+                });
+                await this.taskStore.set(next);
+                return { task: next, previousStatus };
+            };
+            if (!guard.expectAgentLock)
+                return transition();
+            const guarded = await this.lockManager.runIfOwner(guard.expectAgentLock.agentId, taskId, guard.expectAgentLock.token, transition);
+            return guarded.ran ? guarded.value : null;
         });
     }
     createRunnerFor(agent) {
@@ -7379,11 +7561,6 @@ export class AgentManager {
                 ...(promptSignalToken ? { signalToken: promptSignalToken } : {}),
                 ...(promptSpecRound !== undefined ? { currentSpecRound: promptSpecRound } : {}),
                 ...(imagePaths.length ? { imagePaths } : {}),
-                ...(reviewCheckout ? { serverReviewCheckout: reviewCheckout.mode } : {}),
-                ...(reviewCheckout?.fallbackReason ? { serverReviewFallbackReason: reviewCheckout.fallbackReason } : {}),
-                ...(opts.serverBaseSha !== undefined ? { serverBaseSha: opts.serverBaseSha } : {}),
-                ...(opts.serverHeadSha !== undefined ? { serverHeadSha: opts.serverHeadSha } : {}),
-                ...(opts.serverHeadTree !== undefined ? { serverHeadTree: opts.serverHeadTree } : {}),
                 ...(opts.serverBatch ? { serverBatch: opts.serverBatch } : {}),
                 ...(opts.serverFindingsDigest ? { serverFindingsDigest: opts.serverFindingsDigest } : {}),
                 ...(opts.serverFeedbackCorrection ? { serverFeedbackCorrection: opts.serverFeedbackCorrection } : {}),
@@ -7933,9 +8110,6 @@ export class AgentManager {
                     await this.assertTaskGeneration(agentId, taskId, lockToken, verifiedWorkdir);
                 },
             });
-            const useIncrementalNudge = typeof opts.postApproveRedispatchCount === 'number'
-                && opts.postApproveRedispatchCount > 0
-                && !ensure.freshRuntime;
             const imagePaths = await this.imagePathsForDispatch(runner, task, phase);
             let payloadOpts = {};
             if (opts.serverContent !== undefined || opts.serverDiffstat !== undefined || opts.serverInterdiff !== undefined || opts.serverPriorFindings || opts.serverPriorResponse) {
@@ -7963,11 +8137,9 @@ export class AgentManager {
                 hasQaPartner: task.qaAgentId !== undefined,
                 ...(platformCli ? { platformCli } : {}),
                 ...(signalToken ? { signalToken } : {}),
-                ...(useIncrementalNudge
-                    ? { postApproveRedispatchCount: opts.postApproveRedispatchCount }
-                    : {}),
                 ...(promptSpecRound !== undefined ? { currentSpecRound: promptSpecRound } : {}),
                 ...(imagePaths.length ? { imagePaths } : {}),
+                ...(opts.serverReviewCheckout ? { serverReviewCheckout: opts.serverReviewCheckout } : {}),
                 ...(opts.serverBatch ? { serverBatch: opts.serverBatch } : {}),
                 ...(opts.serverAfterDone ? { serverAfterDone: opts.serverAfterDone } : {}),
                 ...(opts.serverFindingsDigest ? { serverFindingsDigest: opts.serverFindingsDigest } : {}),
@@ -8732,10 +8904,11 @@ export class AgentManager {
             && this.gitReviewLeaseMatches(task, lease);
     }
     async dispatchGitReviewLease(taskId, opts = {}) {
-        const claimed = await this.claimGitReviewDispatch(taskId, opts.expectedGeneration);
+        const claimed = await this.claimGitReviewDispatch(taskId, opts.expectedGeneration, opts.expectedTask);
         if (!claimed) {
             throw new ApiError(409, `Git review dispatch for ${taskId} was already claimed or superseded`, 'dispatch-superseded');
         }
+        opts.onSideEffect?.();
         const { task, lease } = claimed;
         const qaId = task.qaAgentId;
         if (!qaId || !this.gitReviewQaConfigUsable(task)) {
@@ -8747,7 +8920,7 @@ export class AgentManager {
         if (previousQa?.taskId === taskId) {
             if (previousQa.status === 'awaiting_human' && !isRecoverableQaDispatchHold(previousQa)) {
                 await this.resetGitReviewDispatchClaim(taskId, lease);
-                throw new ApiError(409, `QA agent ${qaId} is awaiting human (${previousQa.awaitingPhase ?? 'unknown phase'})`);
+                throw new ApiError(409, `QA agent ${qaId} is awaiting human (${previousQa.awaitingPhase ?? 'unknown phase'})`, 'dispatch-unsupported');
             }
             const released = await this.releaseAgentForTask(qaId, taskId, 'idle', {
                 expectedTask: { status: 'review', phase: task.phase, signalToken: lease.signalToken },
@@ -8768,11 +8941,13 @@ export class AgentManager {
                 await this.resetGitReviewDispatchClaim(taskId, lease);
                 throw new ApiError(409, `QA agent ${qaId} could not be released for git review dispatch`);
             }
+            opts.onSideEffect?.();
         }
         let acquiredLockToken;
         const acquired = await this.acquireAgentForTask(qaId, taskId, qaPhase, {
             onAcquired: token => {
                 acquiredLockToken = token;
+                opts.onSideEffect?.();
                 opts.onQaAcquired?.(token);
             },
         });
@@ -8867,6 +9042,9 @@ export class AgentManager {
     async dispatchReviewToQa(taskId, opts = {}) {
         let routeTask = await this.taskStore.get(taskId);
         if (routeTask?.reviewMode === 'git' && !isSpecStagePhase(routeTask.phase)) {
+            if (opts.expectedTask && !taskMatchesGeneration(routeTask, opts.expectedTask)) {
+                throw new ApiError(409, `Task ${taskId} review generation changed during redispatch`, 'dispatch-superseded');
+            }
             if (opts.fromStatus && !opts.fromStatus.includes(routeTask.status)) {
                 throw new ApiError(409, `Task ${taskId} status is ${routeTask.status}; review dispatch requires ${opts.fromStatus.join('/')}`, 'dispatch-superseded');
             }
@@ -8876,6 +9054,9 @@ export class AgentManager {
             if (Object.hasOwn(opts, 'expectPhase') && routeTask.phase !== opts.expectPhase) {
                 throw new ApiError(409, `Task ${taskId} review phase changed during redispatch`, 'dispatch-superseded');
             }
+            if (!routeTask.qaAgentId || this.getAgentConfig(routeTask.qaAgentId)?.role !== 'qa') {
+                throw new ApiError(409, `Task ${taskId} has no available QA participant`, 'dispatch-unsupported');
+            }
             let lease = routeTask.reviewDispatch;
             if (lease?.phase === 'uncertain') {
                 if (opts.confirmUncertainNotDelivered !== true) {
@@ -8897,17 +9078,32 @@ export class AgentManager {
                 }
                 routeTask = confirmed;
                 lease = confirmed.reviewDispatch;
+                opts.onSideEffect?.();
+                if (opts.expectedTask && !taskMatchesGeneration(routeTask, opts.expectedTask)) {
+                    throw new ApiError(409, `Task ${taskId} review generation changed during uncertain-delivery confirmation`, 'dispatch-superseded');
+                }
             }
+            const routeQaId = routeTask.qaAgentId;
+            if (!routeQaId || this.getAgentConfig(routeQaId)?.role !== 'qa') {
+                throw new ApiError(409, `Task ${taskId} has no available QA participant`, 'dispatch-unsupported');
+            }
+            const qaBinding = await this.agentStore.get(routeQaId);
+            if (qaBinding?.taskId === taskId
+                && qaBinding.status === 'awaiting_human'
+                && !isRecoverableQaDispatchHold(qaBinding)) {
+                throw new ApiError(409, `QA agent ${routeQaId} is awaiting human (${qaBinding.awaitingPhase ?? 'unknown phase'})`, 'dispatch-unsupported');
+            }
+            let dispatchExpectedTask = opts.expectedTask;
             if (lease === undefined) {
                 if (routeTask.prNumber === undefined) {
-                    throw new ApiError(400, `Task ${taskId} has no PR yet; cannot dispatch review`);
+                    throw new ApiError(400, `Task ${taskId} has no PR yet; cannot dispatch review`, 'dispatch-unsupported');
                 }
                 const verified = await this.platformVerifyPrBinding(taskId, routeTask.prNumber);
                 if (!verified.ok) {
-                    throw new ApiError(409, `Cannot dispatch git review for ${taskId}: binding ${verified.reason}`);
+                    throw new ApiError(409, `Cannot dispatch git review for ${taskId}: binding ${verified.reason}`, 'dispatch-unsupported');
                 }
                 if (!PLATFORM_HEAD_SHA_RE.test(verified.headSha)) {
-                    throw new ApiError(502, `Cannot dispatch git review for ${taskId}: invalid platform head`);
+                    throw new ApiError(502, `Cannot dispatch git review for ${taskId}: invalid platform head`, 'dispatch-unsupported');
                 }
                 const begun = await this.beginGitReviewPass(taskId, {
                     fromStatus: [routeTask.status],
@@ -8916,17 +9112,27 @@ export class AgentManager {
                     ...(opts.qaPhase !== undefined ? { qaPhase: opts.qaPhase } : {}),
                     expectSignalToken: routeTask.signalToken,
                     expectPhase: routeTask.phase,
+                    ...(opts.expectedTask !== undefined ? { expectedTask: opts.expectedTask } : {}),
                     patch: { latestHeadSha: verified.headSha },
                 });
                 if (!begun?.task.reviewDispatch) {
                     throw new ApiError(409, `Task ${taskId} changed before git review pass creation`, 'dispatch-superseded');
                 }
+                opts.onSideEffect?.();
                 lease = begun.task.reviewDispatch;
+                if (opts.expectedTask) {
+                    dispatchExpectedTask = {
+                        ...opts.expectedTask,
+                        signalToken: begun.task.signalToken,
+                    };
+                }
             }
             const dispatched = await this.dispatchGitReviewLease(taskId, {
                 expectedGeneration: lease.generation,
+                ...(dispatchExpectedTask !== undefined ? { expectedTask: dispatchExpectedTask } : {}),
                 ...(opts.pendingBudget !== undefined ? { pendingBudget: opts.pendingBudget } : {}),
                 ...(opts.onQaAcquired !== undefined ? { onQaAcquired: opts.onQaAcquired } : {}),
+                ...(opts.onSideEffect !== undefined ? { onSideEffect: opts.onSideEffect } : {}),
             });
             opts.onPassArmed?.(lease.signalToken);
             return dispatched;
@@ -8938,12 +9144,19 @@ export class AgentManager {
             if (this.markCompleteInFlight.has(taskId)) {
                 throw new ApiError(409, `Task ${taskId} is being completed (merge in progress); try again shortly`, 'dispatch-in-flight');
             }
+            // 早闸在 claim 前零副作用拒绝：driver 的 putRound/删 response 副作用都在终闸之前。
+            if (this.phaseSignalWatcher?.isSettling(taskId)) {
+                throw new ApiError(409, `Task ${taskId} has a review completion settling; retry after it lands`, 'review-settling');
+            }
             const task = await this.taskStore.get(taskId);
             if (!task)
                 throw new ApiError(404, `Task ${taskId} not found`);
             if (task.reviewMode !== 'server' && !isSpecStagePhase(task.phase)) {
                 throw new ApiError(409, `Task ${taskId} review mode changed during dispatch; retry`, 'dispatch-superseded');
             }
+            if (opts.expectedTask && !taskMatchesGeneration(task, opts.expectedTask)) {
+                throw new ApiError(409, `Task ${taskId} review generation changed during redispatch`, 'dispatch-superseded');
+            }
             if (opts.fromStatus && !opts.fromStatus.includes(task.status)) {
                 throw new ApiError(409, `Task ${taskId} status is ${task.status}; review dispatch requires ${opts.fromStatus.join('/')}`, 'dispatch-superseded');
             }
@@ -8954,27 +9167,29 @@ export class AgentManager {
                 throw new ApiError(409, `Task ${taskId} review pass changed during redispatch (phase changed); aborting`, 'dispatch-superseded');
             }
             if (!MANUAL_SERVER_REVIEW_STATUSES.includes(task.status)) {
-                throw new ApiError(409, `Task ${taskId} status is ${task.status}; manual server-side review requires ${MANUAL_SERVER_REVIEW_STATUSES.join('/')}`);
+                throw new ApiError(409, `Task ${taskId} status is ${task.status}; manual server-side review requires ${MANUAL_SERVER_REVIEW_STATUSES.join('/')}`, 'dispatch-unsupported');
             }
             if (!this.serverReviewDriver) {
-                throw new ApiError(409, `Server review pipeline is not configured; cannot dispatch review for ${taskId}`);
+                throw new ApiError(409, `Server review pipeline is not configured; cannot dispatch review for ${taskId}`, 'dispatch-unsupported');
             }
             if (task.status === 'in_progress' && task.phase === undefined) {
-                throw new ApiError(409, `Task ${taskId} has no phase yet (the dev has not delivered spec-done/code-done); wait for the dev signal or use Cancel/Retry`);
+                throw new ApiError(409, `Task ${taskId} has no phase yet (the dev has not delivered spec-done/code-done); wait for the dev signal or use Cancel/Retry`, 'dispatch-unsupported');
             }
             const qaAvailable = task.qaAgentId !== undefined && this.getAgentConfig(task.qaAgentId)?.role === 'qa';
             if (!qaAvailable) {
-                throw new ApiError(400, `Task ${taskId} has no QA partner configured; manual review requires a QA agent`);
+                throw new ApiError(400, `Task ${taskId} has no QA partner configured; manual review requires a QA agent`, 'dispatch-unsupported');
             }
             const isSpec = isSpecStagePhase(task.phase);
+            const qaBinding = await this.agentStore.get(task.qaAgentId);
+            const bumpRound = shouldBumpServerReviewRound(opts.bumpRound, task, qaBinding);
             const cap = this.config.review.rounds + (task.maxRoundsContinues ?? 0);
             const round = isSpec ? (task.specReviewRound ?? 0) : task.reviewRound;
-            const nextRound = opts.bumpRound === false ? round : round + 1;
+            const nextRound = bumpRound ? round + 1 : round;
             if (nextRound < 1) {
-                throw new ApiError(409, `Task ${taskId} has no current review round to redispatch`);
+                throw new ApiError(409, `Task ${taskId} has no current review round to redispatch`, 'dispatch-unsupported');
             }
             if (nextRound > cap) {
-                throw new ApiError(409, `Task ${taskId} reached the review round cap (${cap}); continue or cancel it instead`);
+                throw new ApiError(409, `Task ${taskId} reached the review round cap (${cap}); continue or cancel it instead`, 'dispatch-unsupported');
             }
             this.manualReviewInFlight.add(taskId);
             return {
@@ -8983,35 +9198,45 @@ export class AgentManager {
                     status: task.status,
                     phase: task.phase,
                     signalToken: task.signalToken,
+                    agentId: task.agentId,
+                    reviewRound: task.reviewRound,
+                    specReviewRound: task.specReviewRound,
                 },
-                bumpRound: opts.bumpRound,
+                bumpRound,
+                onSideEffect: opts.onSideEffect,
             };
         });
         return this.runManualServerReview(taskId, claim);
     }
     async runManualServerReview(taskId, claim) {
         try {
-            // 不在此处预释放旧 QA：可失败的准备工作（读 diff/spec、存轮次）失败时旧 pass 必须原样保留；
-            // 同任务的 QA 重新绑定由 dispatchServerReviewToQa 在派发前完成
-            const fresh = await this.taskStore.get(taskId);
-            if (!fresh
-                || fresh.status !== claim.reviewPass.status
-                || fresh.phase !== claim.reviewPass.phase
-                || fresh.signalToken !== claim.reviewPass.signalToken
-                || !MANUAL_SERVER_REVIEW_STATUSES.includes(fresh.status)) {
-                throw new ApiError(409, `Task ${taskId} changed during manual review dispatch; aborting`);
-            }
-            const dispatched = claim.isSpec
-                ? claim.bumpRound === false
-                    ? await this.serverReviewDriver.dispatchSpecReview(fresh, { bumpRound: false })
-                    : await this.serverReviewDriver.dispatchSpecReview(fresh)
-                : claim.bumpRound === false
-                    ? await this.serverReviewDriver.dispatchCodeReview(fresh, { bumpRound: false })
-                    : await this.serverReviewDriver.dispatchCodeReview(fresh);
-            if (!dispatched) {
-                throw new ApiError(500, `Manual review dispatch for ${taskId} did not start; check the event feed for the cause`);
-            }
-            return (await this.taskStore.get(taskId));
+            const run = async (ownerPermit) => {
+                // 不在此处预释放旧 QA：可失败的准备工作（读 diff/spec、存轮次）失败时旧 pass 必须原样保留；
+                // 同任务的 QA 重新绑定由 dispatchServerReviewToQa 在派发前完成。
+                // 先入的结算持互斥跑完后，下面的任务代 CAS 拒绝本次手工；反向由 owner permit 过终闸。
+                const fresh = await this.taskStore.get(taskId);
+                if (!fresh
+                    || !taskMatchesGeneration(fresh, claim.reviewPass)
+                    || !MANUAL_SERVER_REVIEW_STATUSES.includes(fresh.status)) {
+                    throw new ApiError(409, `Task ${taskId} changed during manual review dispatch; aborting`);
+                }
+                const driverOpts = {
+                    bumpRound: claim.bumpRound,
+                    expectedTask: claim.reviewPass,
+                    ...(claim.onSideEffect !== undefined ? { onSideEffect: claim.onSideEffect } : {}),
+                    ...(ownerPermit !== undefined ? { settlePermit: ownerPermit } : {}),
+                };
+                const dispatched = claim.isSpec
+                    ? await this.serverReviewDriver.dispatchSpecReview(fresh, driverOpts)
+                    : await this.serverReviewDriver.dispatchCodeReview(fresh, driverOpts);
+                if (!dispatched) {
+                    throw new ApiError(500, `Manual review dispatch for ${taskId} did not start; check the event feed for the cause`);
+                }
+                return (await this.taskStore.get(taskId));
+            };
+            return this.phaseSignalWatcher
+                ? await this.phaseSignalWatcher.runExclusive(taskId, run)
+                : await run();
         }
         finally {
             this.manualReviewInFlight.delete(taskId);
@@ -9857,27 +10082,49 @@ export class AgentManager {
         const task = await this.taskStore.get(taskId);
         if (!task)
             return null;
-        const transition = await this.transitionTaskStatus(taskId, 'spec-ready', { fromStatus: ['review', 'in_progress', 'fixing'] }, {
+        const transition = await this.transitionTaskStatus(taskId, 'spec-ready', {
+            fromStatus: ['review', 'in_progress', 'fixing'],
+            ...(opts.expectedTask !== undefined ? { expectTask: opts.expectedTask } : {}),
+        }, {
             phase: 'spec',
             ...(opts.specReviewRound !== undefined ? { specReviewRound: opts.specReviewRound } : {}),
         });
         if (!transition)
             return null;
+        const parked = transition.task;
+        const parkedGeneration = {
+            status: parked.status,
+            phase: parked.phase,
+            signalToken: parked.signalToken,
+            agentId: parked.agentId,
+            reviewRound: parked.reviewRound,
+            specReviewRound: parked.specReviewRound,
+        };
         this.stopPhaseSignalWatcher(taskId);
-        if (task.agentId) {
-            const devOk = await this.markAgentWaiting(task.agentId, taskId).catch(() => false);
+        if (parked.agentId) {
+            const devOk = await this.markAgentWaiting(parked.agentId, taskId, {
+                expectedTask: parkedGeneration,
+            }).catch(() => false);
             if (!devOk) {
-                await this.emitIntervention(task.projectId, task.agentId, taskId, { phase: 'spec-ready-dev-park-failed', devAgentId: task.agentId });
+                await this.emitIntervention(parked.projectId, parked.agentId, taskId, {
+                    phase: 'spec-ready-dev-park-failed',
+                    devAgentId: parked.agentId,
+                });
             }
         }
-        if (task.qaAgentId) {
-            const released = await this.releaseAgentForTask(task.qaAgentId, taskId, 'idle')
+        if (parked.qaAgentId) {
+            const released = await this.releaseAgentForTask(parked.qaAgentId, taskId, 'idle', {
+                expectedTask: parkedGeneration,
+            })
                 .catch(() => false);
             if (!released) {
-                await this.emitIntervention(task.projectId, task.qaAgentId, taskId, { phase: 'spec-ready-qa-release-failed', qaAgentId: task.qaAgentId });
+                await this.emitIntervention(parked.projectId, parked.qaAgentId, taskId, {
+                    phase: 'spec-ready-qa-release-failed',
+                    qaAgentId: parked.qaAgentId,
+                });
             }
         }
-        return transition.task;
+        return parked;
     }
     async submitSpecVerdict(taskId, verdict, comments) {
         const trimmed = comments?.trim();
@@ -10217,8 +10464,13 @@ export class AgentManager {
             })
             : this.continueSession(task.id, devAgentId, 'code', dispatchOpts);
     }
-    async transitionToCodePhase(taskId) {
-        const task = await this.taskStore.get(taskId);
+    async transitionToCodePhase(taskId, expectedTask) {
+        const task = await this.withTaskLock(async () => {
+            const current = await this.taskStore.get(taskId);
+            if (expectedTask && current && !taskMatchesGeneration(current, expectedTask))
+                return null;
+            return current;
+        });
         if (!task)
             return null;
         const devAgentId = task.devAgentId;
@@ -10242,7 +10494,10 @@ export class AgentManager {
         const researchAgentId = task.researchAgentId;
         const researchHandoff = this.isResearchHandoff(task, devAgentId);
         const releaseParticipant = async (agentId, failurePhase) => {
-            const released = await this.releaseAgentIfBound(agentId, taskId, { allowAwaitingHuman: true })
+            const released = await this.releaseAgentIfBound(agentId, taskId, {
+                allowAwaitingHuman: true,
+                ...(expectedTask !== undefined ? { expectedTask } : {}),
+            })
                 .catch(() => false);
             if (!released) {
                 await this.emitIntervention(task.projectId, agentId, taskId, { phase: failurePhase, agentId });
@@ -10257,7 +10512,10 @@ export class AgentManager {
             return null;
         }
         const devBoundBefore = (await this.agentStore.get(devAgentId))?.taskId === taskId;
-        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'code');
+        let acquiredLockToken;
+        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'code', {
+            onAcquired: token => { acquiredLockToken = token; },
+        });
         if (!acquired) {
             await this.emitIntervention(task.projectId, devAgentId, taskId, {
                 phase: 'code-dev-acquire-failed',
@@ -10265,13 +10523,25 @@ export class AgentManager {
             });
             return null;
         }
-        const acquiredLockToken = (await this.agentStore.get(devAgentId))?.lockToken;
         const newToken = createSignalToken();
         // spec 阶段的扩轮决策不延续到 code 评审：cap 共享字段，进入编码时归零
-        const transition = await this.transitionTaskStatus(taskId, 'in_progress', { fromStatus: ['review', 'fixing', 'in_progress', 'spec-ready', 'max_rounds'] }, { agentId: devAgentId, phase: 'code', maxRoundsContinues: 0, ...this.dispatchTokenFields({ ...task, phase: 'code' }, newToken) });
+        const transition = await this.transitionTaskStatus(taskId, 'in_progress', {
+            fromStatus: ['review', 'fixing', 'in_progress', 'spec-ready', 'max_rounds'],
+            ...(expectedTask !== undefined ? { expectTask: expectedTask } : {}),
+        }, { agentId: devAgentId, phase: 'code', maxRoundsContinues: 0, ...this.dispatchTokenFields({ ...task, phase: 'code' }, newToken) });
         if (!transition) {
-            await this.releaseAgentForTask(devAgentId, taskId, 'idle', { allowAwaitingHuman: true })
-                .catch(() => undefined);
+            if (!devBoundBefore) {
+                try {
+                    await this.releaseAgentForTask(devAgentId, taskId, 'idle', {
+                        allowAwaitingHuman: true,
+                        ...(expectedTask !== undefined ? { expectedTask } : {}),
+                        ...(acquiredLockToken !== undefined ? { expectedLockToken: acquiredLockToken } : {}),
+                    });
+                }
+                catch (err) {
+                    console.warn(`[AgentManager] transitionToCodePhase(${taskId}): stale-generation acquire rollback failed:`, err);
+                }
+            }
             return null;
         }
         this.stopPhaseSignalWatcher(taskId);
@@ -10337,12 +10607,22 @@ export class AgentManager {
             : (opts.recheck ? 'server-recheck' : 'server-review');
         const expectedKind = opts.phase === 'spec' ? 'spec-reviewed' : 'code-reviewed';
         const claim = await this.withTaskLock(async () => {
+            // 终闸与 newToken 铸发同临界区：settling 中仅结算 handler 链（settle permit）
+            // 或当前互斥 FIFO owner（手工先入者）可开新 pass。
+            if (this.phaseSignalWatcher?.isSettling(taskId)
+                && !this.phaseSignalWatcher.settlePermitMatches(taskId, opts.settlePermit)
+                && !this.phaseSignalWatcher.exclusiveOwnerMatches(taskId, opts.settlePermit)) {
+                throw new ApiError(409, `Task ${taskId} has a review completion settling; retry after it lands`, 'review-settling');
+            }
             const task = await this.taskStore.get(taskId);
             if (!task)
                 throw new Error(`dispatchServerReviewToQa: task ${taskId} not found`);
             if (task.reviewMode !== 'server' && opts.phase !== 'spec') {
                 throw new Error(`dispatchServerReviewToQa: task ${taskId} is not in server review mode`);
             }
+            if (opts.expectedTask && !taskMatchesGeneration(task, opts.expectedTask)) {
+                throw new ApiError(409, `Task ${taskId} review generation changed before server dispatch`, 'dispatch-superseded');
+            }
             const qaId = task.qaAgentId;
             if (!qaId) {
                 if (!opts.callerOwnsConsumedSignalFailure) {
@@ -10371,11 +10651,13 @@ export class AgentManager {
                 return null;
             }
             const roundField = opts.phase === 'spec' ? (task.specReviewRound ?? 0) : task.reviewRound;
+            const qaBinding = await this.agentStore.get(qaId);
+            const bumpRound = shouldBumpServerReviewRound(opts.bumpRound, task, qaBinding);
             const newRound = opts.continuation
                 ? Math.max(roundField, 1)
-                : opts.bumpRound === false
-                    ? roundField
-                    : roundField + 1;
+                : bumpRound
+                    ? roundField + 1
+                    : roundField;
             if (newRound < 1) {
                 throw new Error(`dispatchServerReviewToQa: task ${taskId} has no current ${opts.phase} review round to redispatch`);
             }
@@ -10391,6 +10673,7 @@ export class AgentManager {
                 originalBatchIndex: task.batchIndex,
                 originalBatchTotal: task.batchTotal,
                 originalPhase: task.phase,
+                originalReviewCheckoutMode: task.reviewCheckoutMode,
             };
         });
         if (!claim)
@@ -10402,11 +10685,14 @@ export class AgentManager {
                     fromStatus: [installedPass.status],
                     expectPhase: installedPass.phase,
                     expectSignalToken: installedPass.signalToken,
+                    expectTask: installedPass,
                 }, {
                     signalToken: claim.originalToken,
                     batchIndex: claim.originalBatchIndex,
                     batchTotal: claim.originalBatchTotal,
                     phase: claim.originalPhase,
+                    // fresh 派发在 install 时清过 mode：不还原会把仍在跑的 base pass 降级成 unknown
+                    reviewCheckoutMode: claim.originalReviewCheckoutMode,
                     ...(opts.phase === 'spec'
                         ? { specReviewRound: claim.originalRound }
                         : { reviewRound: claim.originalRound }),
@@ -10448,17 +10734,35 @@ export class AgentManager {
         if (!opts.continuation) {
             const prevQa = await this.agentStore.get(qaId);
             if (prevQa?.taskId === taskId) {
-                // 手工重派：上一 pass 的 QA 仍绑定本任务，先释放再重新 acquire（与 github 手工路径一致）
+                if (prevQa.status === 'awaiting_human' && !isRecoverableQaDispatchHold(prevQa)) {
+                    throw new ApiError(409, `QA agent ${qaId} is awaiting human (${prevQa.awaitingPhase ?? 'unknown phase'}); resolve that hold before redispatching server review`, 'dispatch-unsupported');
+                }
+                // 手工重派：上一 pass 的 QA 仍绑定本任务，先释放再重新 acquire
                 const released = await this.releaseAgentForTask(qaId, taskId, 'idle', {
+                    ...(opts.expectedTask !== undefined ? { expectedTask: opts.expectedTask } : {}),
                     ...(prevQa.lockToken !== undefined ? { expectedLockToken: prevQa.lockToken } : {}),
+                    ...(prevQa.status === 'awaiting_human'
+                        ? {
+                            allowAwaitingHuman: true,
+                            expectedHold: {
+                                phase: prevQa.awaitingPhase,
+                                since: prevQa.awaitingSince,
+                                nonce: prevQa.awaitingNonce,
+                            },
+                        }
+                        : {}),
                 });
                 if (!released) {
                     await rearmEntrySignal();
                     return null;
                 }
+                opts.onSideEffect?.();
             }
             const acquired = await this.acquireAgentForTask(qaId, taskId, dispatchPhase, {
-                onAcquired: (lockToken) => { acquiredLockToken = lockToken; },
+                onAcquired: (lockToken) => {
+                    acquiredLockToken = lockToken;
+                    opts.onSideEffect?.();
+                },
             });
             if (!acquired) {
                 await rearmEntrySignal();
@@ -10471,7 +10775,9 @@ export class AgentManager {
                 return null;
             }
             if (devAgentId) {
-                const devOk = await this.markAgentWaiting(devAgentId, taskId);
+                const devOk = await this.markAgentWaiting(devAgentId, taskId, {
+                    ...(opts.expectedTask !== undefined ? { expectedTask: opts.expectedTask } : {}),
+                });
                 if (!devOk) {
                     await releaseOwnAcquire('dev park failed');
                     await rearmEntrySignal();
@@ -10505,6 +10811,7 @@ export class AgentManager {
             fromStatus: [claim.originalStatus],
             expectPhase: claim.originalPhase,
             expectSignalToken: claim.originalToken,
+            ...(opts.expectedTask !== undefined ? { expectTask: opts.expectedTask } : {}),
         }, {
             signalToken: newToken,
             reviewDispatchedAt: new Date().toISOString(),
@@ -10530,15 +10837,18 @@ export class AgentManager {
             }
             return null;
         }
-        const installedPass = {
-            status: transition.task.status,
-            phase: transition.task.phase,
-            signalToken: transition.task.signalToken,
+        opts.onSideEffect?.();
+        const installedPass = taskGenerationGuard(transition.task);
+        const passStillCurrent = async () => {
+            const current = await this.taskStore.get(taskId);
+            return current !== null && taskMatchesGeneration(current, installedPass);
         };
         let dispatchedCheckoutMode;
         const sessionOpts = {
             bypassTaskStatusGate: true,
             signalToken: newToken,
+            dispatchPassToken: newToken,
+            guardBeforeInject: passStillCurrent,
             serverContent: opts.content,
             ...(opts.interdiff !== undefined ? { serverInterdiff: opts.interdiff } : {}),
             ...(opts.diffstat !== undefined ? { serverDiffstat: opts.diffstat } : {}),
@@ -10549,7 +10859,10 @@ export class AgentManager {
             ...(opts.priorFindingsJson ? { serverPriorFindings: opts.priorFindingsJson } : {}),
             ...(opts.priorResponseJson ? { serverPriorResponse: opts.priorResponseJson } : {}),
             ...(opts.phase === 'spec' ? { currentSpecRound: newRound } : {}),
-            armBeforeInject: (ctx) => {
+            armBeforeInject: (ctx) => this.withTaskLock(async () => {
+                const current = await this.taskStore.get(taskId);
+                if (!current || !taskMatchesGeneration(current, installedPass))
+                    return false;
                 dispatchedCheckoutMode = ctx.serverReviewCheckout;
                 const allowReadFile = opts.phase === 'spec' || opts.continuation || ctx.serverReviewCheckout === 'base';
                 return this.setupPhaseSignalWatcher(taskId, qaId, expectedKind, newToken, {
@@ -10558,7 +10871,7 @@ export class AgentManager {
                         ? { onReadFile: (req) => { void this.handleReadFileRequest(taskId, qaId, req); } }
                         : {}),
                 });
-            },
+            }),
         };
         const rearmConsumedSignal = async () => {
             if (opts.callerOwnsConsumedSignalFailure)
@@ -10572,20 +10885,24 @@ export class AgentManager {
         };
         let started = false;
         try {
+            // 批次轮早于 head 物化且其持久化 mode 不可信（改名丢失/尽力而为），续传恒重发 base。
             started = opts.continuation
-                ? await this.continueSession(taskId, qaId, dispatchPhase, sessionOpts)
+                ? await this.continueSession(taskId, qaId, dispatchPhase, { ...sessionOpts, serverReviewCheckout: 'base' })
                 : await this.startSession(taskId, qaId, dispatchPhase, sessionOpts);
         }
         catch (err) {
-            this.stopPhaseSignalWatcher(taskId);
+            this.phaseSignalWatcher?.stopAgentIfToken(taskId, qaId, newToken);
             if (err instanceof DispatchTerminalError) {
-                await this.failTaskForDispatchError(taskId, dispatchPhase, qaId, err, ownAcquire());
+                await this.failTaskForDispatchError(taskId, dispatchPhase, qaId, err, {
+                    ...ownAcquire(),
+                    expectedTask: installedPass,
+                });
             }
             else if (err instanceof EnsureSessionError && err.partial.handled) {
             }
             else {
                 const rolledBack = await rollback(installedPass);
-                if (!opts.continuation) {
+                if (rolledBack && !opts.continuation) {
                     await releaseOwnAcquire('session dispatch threw');
                 }
                 if (rolledBack)
@@ -10594,14 +10911,14 @@ export class AgentManager {
             throw err;
         }
         if (!started) {
-            this.stopPhaseSignalWatcher(taskId);
+            this.phaseSignalWatcher?.stopAgentIfToken(taskId, qaId, newToken);
             const rolledBack = await rollback(installedPass);
-            if (!opts.continuation) {
+            if (rolledBack && !opts.continuation) {
                 await releaseOwnAcquire('session did not start');
             }
             if (rolledBack)
                 await rearmConsumedSignal();
-            if (!opts.callerOwnsConsumedSignalFailure) {
+            if (rolledBack && !opts.callerOwnsConsumedSignalFailure) {
                 await this.emitIntervention(projectId, qaId, taskId, {
                     phase: 'server-review-start-failed',
                     qaAgentId: qaId,
@@ -10612,7 +10929,11 @@ export class AgentManager {
         // Persist the checkout mode so base-mode recovery can re-arm read-file.
         if (opts.phase !== 'spec' && !opts.continuation) {
             try {
-                await this.updateTask(taskId, { reviewCheckoutMode: dispatchedCheckoutMode });
+                const persisted = await this.updateTaskIfStatus(taskId, installedPass.status, { reviewCheckoutMode: dispatchedCheckoutMode }, installedPass);
+                if (!persisted) {
+                    console.warn(`[AgentManager] review checkout mode for ${taskId} was superseded before persistence; skipping stale write`);
+                    return await this.taskStore.get(taskId);
+                }
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -10634,6 +10955,9 @@ export class AgentManager {
             if (task.reviewMode !== 'server' && !isSpecStagePhase(task.phase)) {
                 throw new Error(`dispatchServerFixToDev: task ${taskId} is not in server review mode`);
             }
+            if (opts.expectedTask && !taskMatchesGeneration(task, opts.expectedTask)) {
+                throw new ApiError(409, `Task ${taskId} review generation changed before server fix dispatch`, 'dispatch-superseded');
+            }
             if (!task.agentId)
                 throw new Error(`dispatchServerFixToDev: task ${taskId} has no dev agent`);
             return {
@@ -10646,34 +10970,51 @@ export class AgentManager {
                 currentSpecRound: task.specReviewRound,
                 originalStatus: task.status,
                 originalToken: task.signalToken,
+                entryGeneration: taskGenerationGuard(task),
             };
         });
         if (!claim)
             return null;
-        const { devAgentId, qaAgentId, projectId, newToken, taskPhase, currentSpecRound } = claim;
-        const rollbackToEntry = async () => {
-            await this.transitionTaskStatus(taskId, claim.originalStatus, { fromStatus: ['fixing'] }, { signalToken: claim.originalToken }).catch(() => undefined);
-        };
+        const { devAgentId, qaAgentId, projectId, newToken, taskPhase, currentSpecRound, entryGeneration, } = claim;
         const expectedKind = taskPhase === 'spec' ? 'spec-fixed' : 'code-fixed';
-        const rearmReviewedSignal = async () => {
+        const rearmReviewedSignal = async (expectedTask = entryGeneration) => {
             if (opts.callerOwnsConsumedSignalFailure)
                 return;
             if (!qaAgentId)
                 return;
             const reviewedKind = taskPhase === 'spec' ? 'spec-reviewed' : 'code-reviewed';
-            await this.setupPhaseSignal(taskId, qaAgentId, reviewedKind, { skipSnapshot: true });
+            await this.withTaskLock(async () => {
+                const current = await this.taskStore.get(taskId);
+                if (!current?.signalToken || !taskMatchesGeneration(current, expectedTask))
+                    return;
+                await this.setupPhaseSignal(taskId, qaAgentId, reviewedKind, {
+                    skipSnapshot: true,
+                });
+            });
         };
         const devBoundBefore = (await this.agentStore.get(devAgentId))?.taskId === taskId;
-        const releaseFreshAcquire = async () => {
+        let acquiredDevLockToken;
+        const releaseFreshAcquire = async (devLockToken) => {
             if (devBoundBefore)
                 return;
-            const released = await this.releaseAgentForTask(devAgentId, taskId, 'idle')
-                .catch(() => false);
-            if (!released) {
-                console.error(`[AgentManager] dispatchServerFixToDev: releasing freshly acquired dev ${devAgentId} for ${taskId} failed`);
+            try {
+                const released = await this.releaseAgentForTask(devAgentId, taskId, 'idle', {
+                    expectedTask: entryGeneration,
+                    expectedLockToken: devLockToken,
+                });
+                if (!released) {
+                    console.error(`[AgentManager] dispatchServerFixToDev: releasing freshly acquired dev `
+                        + `${devAgentId} for ${taskId} was refused`);
+                }
+            }
+            catch (err) {
+                console.error(`[AgentManager] dispatchServerFixToDev: releasing freshly acquired dev `
+                    + `${devAgentId} for ${taskId} failed:`, err);
             }
         };
-        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'server-feedback');
+        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'server-feedback', {
+            onAcquired: (lockToken) => { acquiredDevLockToken = lockToken; },
+        });
         if (!acquired) {
             await rearmReviewedSignal();
             if (!opts.callerOwnsConsumedSignalFailure) {
@@ -10684,11 +11025,18 @@ export class AgentManager {
             }
             return null;
         }
+        const devLockToken = acquiredDevLockToken;
+        if (!devLockToken) {
+            throw new Error(`dispatchServerFixToDev: acquireAgentForTask did not return the Dev lock token for ${devAgentId}`);
+        }
         if (qaAgentId) {
-            const released = await this.releaseAgentIfBound(qaAgentId, taskId)
-                .catch(() => false);
+            const released = await this.releaseAgentIfBound(qaAgentId, taskId, { expectedTask: entryGeneration })
+                .catch((err) => {
+                console.error(`[AgentManager] dispatchServerFixToDev: releasing QA ${qaAgentId} for ${taskId} failed:`, err);
+                return false;
+            });
             if (!released) {
-                await releaseFreshAcquire();
+                await releaseFreshAcquire(devLockToken);
                 await rearmReviewedSignal();
                 if (!opts.callerOwnsConsumedSignalFailure) {
                     await this.emitIntervention(projectId, qaAgentId, taskId, {
@@ -10699,9 +11047,14 @@ export class AgentManager {
                 return null;
             }
         }
-        const transition = await this.transitionTaskStatus(taskId, 'fixing', { fromStatus: ['review', 'max_rounds', 'spec-ready', 'ready'] }, { signalToken: newToken, fixDispatchedAt: new Date().toISOString() });
+        const transition = await this.transitionTaskStatus(taskId, 'fixing', {
+            fromStatus: ['review', 'max_rounds', 'spec-ready', 'ready'],
+            expectSignalToken: claim.originalToken,
+            expectTask: entryGeneration,
+            expectAgentLock: { agentId: devAgentId, token: devLockToken },
+        }, { signalToken: newToken, fixDispatchedAt: new Date().toISOString() });
         if (!transition) {
-            await releaseFreshAcquire();
+            await releaseFreshAcquire(devLockToken);
             if (!opts.callerOwnsConsumedSignalFailure) {
                 await this.emitIntervention(projectId, devAgentId, taskId, {
                     phase: 'server-fix-transition-failed',
@@ -10710,6 +11063,47 @@ export class AgentManager {
             }
             return null;
         }
+        const installedFix = taskGenerationGuard(transition.task);
+        const fixingPassStillCurrent = async () => {
+            const current = await this.taskStore.get(taskId);
+            return current !== null && taskMatchesGeneration(current, installedFix);
+        };
+        const rollbackToEntry = async () => {
+            try {
+                const rolledBack = await this.transitionTaskStatus(taskId, claim.originalStatus, {
+                    fromStatus: ['fixing'],
+                    expectTask: installedFix,
+                    expectAgentLock: { agentId: devAgentId, token: devLockToken },
+                }, { signalToken: claim.originalToken });
+                if (!rolledBack) {
+                    console.warn(`[AgentManager] dispatchServerFixToDev rollback for ${taskId} was superseded `
+                        + `by a newer task or Dev lock generation`);
+                }
+                return rolledBack?.task ?? null;
+            }
+            catch (err) {
+                console.error(`[AgentManager] dispatchServerFixToDev rollback failed for ${taskId}:`, err);
+                return null;
+            }
+        };
+        const cleanupUndeliveredFix = async () => {
+            const rolledBack = await rollbackToEntry();
+            if (!rolledBack)
+                return false;
+            const rolledBackGeneration = taskGenerationGuard(rolledBack);
+            const released = await this.releaseAgentForTask(devAgentId, taskId, 'idle', {
+                expectedTask: rolledBackGeneration,
+                expectedLockToken: devLockToken,
+            }).catch((err) => {
+                console.error(`[AgentManager] dispatchServerFixToDev: releasing dev ${devAgentId} after rollback failed:`, err);
+                return false;
+            });
+            if (!released) {
+                console.error(`[AgentManager] dispatchServerFixToDev: releasing dev ${devAgentId} after rollback was refused`);
+            }
+            await rearmReviewedSignal(rolledBackGeneration);
+            return true;
+        };
         let resumed = false;
         try {
             const feedbackPhase = taskPhase === 'spec' ? 'spec' : 'code';
@@ -10727,29 +11121,39 @@ export class AgentManager {
                 signalToken: newToken,
                 serverPriorFindings: findingsJson,
                 serverFindingsDigest: findingsDigest,
+                armBeforeInject: () => this.withTaskLock(async () => {
+                    const current = await this.taskStore.get(taskId);
+                    if (!current || !taskMatchesGeneration(current, installedFix))
+                        return false;
+                    return this.setupPhaseSignalWatcher(taskId, devAgentId, expectedKind, newToken, {
+                        needInputMode: 'fresh',
+                    });
+                }),
+                guardBeforeInject: fixingPassStillCurrent,
                 ...(taskPhase === 'spec' && currentSpecRound !== undefined
                     ? { currentSpecRound }
                     : {}),
             });
         }
         catch (err) {
+            this.phaseSignalWatcher?.stopAgentIfToken(taskId, devAgentId, newToken);
             if (err instanceof DispatchTerminalError) {
-                await this.failTaskForDispatchError(taskId, 'server-feedback', devAgentId, err);
+                await this.failTaskForDispatchError(taskId, 'server-feedback', devAgentId, err, {
+                    expectedTask: installedFix,
+                    expectedLockToken: devLockToken,
+                });
             }
             else if (err instanceof EnsureSessionError && err.partial.handled) {
             }
             else {
-                await rollbackToEntry();
-                await this.releaseAgentForTask(devAgentId, taskId, 'idle').catch(() => undefined);
-                await rearmReviewedSignal();
+                await cleanupUndeliveredFix();
             }
             throw err;
         }
         if (!resumed) {
-            await rollbackToEntry();
-            await this.releaseAgentForTask(devAgentId, taskId, 'idle').catch(() => undefined);
-            await rearmReviewedSignal();
-            if (!opts.callerOwnsConsumedSignalFailure) {
+            this.phaseSignalWatcher?.stopAgentIfToken(taskId, devAgentId, newToken);
+            const cleaned = await cleanupUndeliveredFix();
+            if (cleaned && !opts.callerOwnsConsumedSignalFailure) {
                 await this.emitIntervention(projectId, devAgentId, taskId, {
                     phase: 'server-fix-resume-failed',
                     devAgentId,
@@ -10757,7 +11161,6 @@ export class AgentManager {
             }
             return null;
         }
-        await this.armPostDispatchSignalOrHold(taskId, devAgentId, expectedKind, newToken);
         return await this.taskStore.get(taskId);
     }
     projectRepoKey(projectId) {