baxian 2.0.1 → 2.0.3

package/dist/event/handlers.js

@@ -3,15 +3,21 @@ import { BODY_DIGEST_SOURCE } from '../platform/body-digest.js';
 import { ackRevisionKey } from '../platform/markers.js';
 import { LINE_SAFE_ID_RE } from '../platform/row-schema.js';
 import { SHA_HEX_SOURCE, SOURCE_KEY_PATTERN } from '../platform/types.js';
-import { BRANCH_PREFIX, isRecord, isSpecStagePhase, isValidBranchName, } from '../shared/index.js';
+import { BRANCH_PREFIX, effectiveTaskReviewRound, isRecord, isValidBranchName, taskGenerationGuard, taskReviewRound, } from '../shared/index.js';
 import { DispatchTerminalError, isRecoverableQaDispatchHold, } from '../agent/manager.js';
-import { ReplNotReadyError } from '../agent/tmux.js';
-import { DirtyWorkdirError } from '../agent/branch.js';
 const HEAD_SHA_RE = new RegExp(`^${SHA_HEX_SOURCE}$`);
 const BODY_DIGEST_RE = new RegExp(`^${BODY_DIGEST_SOURCE}$`);
 const PR_UPDATED_REVIEW_FROM_STATUSES = [
-    'in_progress', 'fixing', 'review', 'approved', 'merge-ready',
+    'in_progress', 'fixing', 'review', 'spec-ready', 'approved', 'merge-ready',
 ];
+const PREMATURE_MERGE_BLOCKABLE_STATUSES = [
+    'pending', 'in_progress', 'review', 'fixing', 'spec-ready', 'approved', 'max_rounds',
+];
+function requireTaskQaAgentId(task, operation) {
+    if (!task.qaAgentId)
+        throw new Error(`${operation}: task ${task.id} has no QA participant`);
+    return task.qaAgentId;
+}
 function validHeadSha(value) {
     return typeof value === 'string' && HEAD_SHA_RE.test(value) ? value : undefined;
 }
@@ -96,11 +102,9 @@ function parseGitFeedbackRevision(value) {
     };
 }
 async function reArmDevelopWatcher(manager, task, agentId, opts = {}) {
-    const kinds = task.phase === 'research'
-        ? ['spec-done']
-        : task.phase === 'code'
-            ? ['pr-created']
-            : ['spec-done', 'pr-created'];
+    const kinds = task.phase === 'code'
+        ? ['pr-created']
+        : ['spec-done', 'pr-created'];
     await manager.setupPhaseSignal(task.id, agentId, kinds, { skipSnapshot: opts.skipSnapshot ?? true });
 }
 async function emitIntervention(bus, projectId, agentId, taskId, data) {
@@ -120,9 +124,49 @@ async function emitIntervention(bus, projectId, agentId, taskId, data) {
         console.warn(`[EventHandler] human.intervention emit failed (phase=${data.phase}):`, emitErr);
     }
 }
+async function cleanupPrematureMergeParticipants(bus, manager, task) {
+    const participantIds = [...new Set([task.agentId, task.qaAgentId]
+            .filter((id) => typeof id === 'string' && id !== ''))];
+    const errors = [];
+    try {
+        await manager.cancelTask(task.id);
+    }
+    catch (err) {
+        errors.push(err instanceof Error ? err.message : String(err));
+    }
+    const remainingParticipants = new Set();
+    for (const participantId of participantIds) {
+        try {
+            if ((await manager.getAgentState(participantId))?.taskId === task.id) {
+                remainingParticipants.add(participantId);
+            }
+        }
+        catch (err) {
+            remainingParticipants.add(participantId);
+            errors.push(`${participantId}: binding probe failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            if (await manager.getAgentLockOwner(participantId) === task.id) {
+                remainingParticipants.add(participantId);
+                errors.push(`${participantId}: exclusive lock still owned by task ${task.id}`);
+            }
+        }
+        catch (err) {
+            remainingParticipants.add(participantId);
+            errors.push(`${participantId}: lock probe failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (errors.length === 0 && remainingParticipants.size === 0)
+        return;
+    await emitIntervention(bus, task.projectId, task.agentId, task.id, {
+        phase: 'premature-merge-participant-cleanup-failed',
+        participants: participantIds,
+        remainingParticipants: [...remainingParticipants],
+        ...(errors.length > 0 ? { errors } : {}),
+    });
+}
 const POST_APPROVE_REDISPATCH_CAP = 10;
 const POST_APPROVE_RECOVERY_MIN_AGE_MS = 60_000;
-// 损坏值不可自愈，每周期 sweep 会重踩同一分支：按 task+值去重，值变化或修复后允许重报
 const unparseableUpdatedAtWarned = new Map();
 const VERDICT_FRESHNESS_SKEW_MS = 5000;
 function postApproveEpisodeKey(task) {
@@ -144,7 +188,7 @@ async function dispatchGitDevPostApproveCheck(bus, manager, snapshot, approvedHe
         return;
     }
     const live = await manager.getTask(snapshot.id);
-    if (!live || live.status !== 'approved' || live.reviewMode !== 'git')
+    if (!live || live.status !== 'approved')
         return;
     let key = postApproveEpisodeKey(live);
     if (!key || key.headSha !== approvedHeadSha || live.postApprovePhase === undefined) {
@@ -222,7 +266,7 @@ async function dispatchGitDevPostApproveCheck(bus, manager, snapshot, approvedHe
 async function handlePrMergeReady(bus, manager, event) {
     const taskId = event.taskId;
     const taskNow = await manager.getTask(taskId);
-    if (!taskNow || taskNow.reviewMode !== 'git')
+    if (!taskNow)
         return;
     const eventPrNumber = event.data.prNumber;
     const eventPrUrl = event.data.prUrl;
@@ -260,7 +304,6 @@ async function handlePrMergeReady(bus, manager, event) {
     ]);
     if (!freshTask
         || freshTask.status !== 'approved'
-        || freshTask.reviewMode !== 'git'
         || freshTask.agentId !== taskNow.agentId
         || freshTask.postApproveRevoked !== undefined
         || entryCompletion?.token !== signalToken) {
@@ -308,14 +351,15 @@ async function handlePrMergeReady(bus, manager, event) {
             patch: { latestHeadSha: gitEpisodeKey.headSha },
         });
         if (begun?.task.reviewDispatch) {
+            const qaAgentId = requireTaskQaAgentId(begun.task, 'handlePostApproveMergeReady');
             try {
                 await manager.dispatchGitReviewLease(freshTask.id, {
                     expectedGeneration: begun.task.reviewDispatch.generation,
                 });
             }
             catch (err) {
-                if (err instanceof DispatchTerminalError && begun.task.qaAgentId) {
-                    await manager.failTaskForDispatchError(freshTask.id, 'recheck', begun.task.qaAgentId, err, { expectedReviewDispatch: begun.task.reviewDispatch });
+                if (err instanceof DispatchTerminalError) {
+                    await manager.failTaskForDispatchError(freshTask.id, 'recheck', qaAgentId, err, { expectedReviewDispatch: begun.task.reviewDispatch });
                     return;
                 }
                 await emitIntervention(bus, freshTask.projectId, freshTask.agentId, freshTask.id, {
@@ -347,7 +391,6 @@ async function handlePrMergeReady(bus, manager, event) {
                     expectedHeadSha: gitEpisodeKey.headSha,
                 });
                 if (!revoked) {
-                    // The pass rotated after the entry re-validation; this merge-ready and its cap decision are stale.
                     await emitIntervention(bus, taskNow.projectId, taskNow.agentId, taskNow.id, {
                         phase: 'post-approve-merge-skipped-stale-task',
                     });
@@ -382,7 +425,7 @@ async function handlePrMergeReady(bus, manager, event) {
 async function handlePrFeedback(bus, manager, event) {
     const taskId = event.taskId;
     const taskNow = await manager.getTask(taskId);
-    if (!taskNow || taskNow.reviewMode !== 'git')
+    if (!taskNow)
         return;
     const revision = parseGitFeedbackRevision(event.data.revision);
     if (!revision) {
@@ -447,7 +490,7 @@ export async function recoverGitPostApprovePending(bus, manager) {
 async function recoverOneGitPendingTask(bus, manager, task) {
     {
         const live = await manager.getTask(task.id);
-        if (!live || live.reviewMode !== 'git' || live.status !== 'approved' || live.pendingRedispatch !== true)
+        if (!live || live.status !== 'approved' || live.pendingRedispatch !== true)
             return;
         if (live.postApproveRevoked)
             return;
@@ -516,8 +559,19 @@ async function handlePrCodePush(bus, manager, event) {
     const eventKind = event.data.kind;
     const eventHeadSha = validHeadSha(event.data.headSha);
     const task = await manager.getTask(taskId);
-    if (!task || task.reviewMode !== 'git')
+    if (!task)
+        return;
+    if (task.status === 'in_progress'
+        && (task.phase === undefined || task.deliveryConfirmation?.phase !== task.phase)) {
+        if (eventPrNumber !== undefined && eventHeadSha !== undefined) {
+            await manager.recordGitPrObservation(taskId, {
+                prNumber: eventPrNumber,
+                ...(eventPrUrl !== undefined ? { prUrl: eventPrUrl } : {}),
+                headSha: eventHeadSha,
+            });
+        }
         return;
+    }
     if (eventKind === 'push' && eventHeadSha
         && event.data.source !== 'pr-fixed'
         && task.reviewDispatch === undefined
@@ -529,6 +583,16 @@ async function handlePrCodePush(bus, manager, event) {
         console.warn(`[EventHandler] pr.updated: task ${taskId} in_progress but neither task nor event has prNumber; deferring catch-up`);
         return;
     }
+    if (task.status === 'max_rounds') {
+        if (eventPrNumber !== undefined && eventHeadSha !== undefined) {
+            await manager.recordGitPrObservation(taskId, {
+                prNumber: eventPrNumber,
+                ...(eventPrUrl !== undefined ? { prUrl: eventPrUrl } : {}),
+                headSha: eventHeadSha,
+            });
+        }
+        return;
+    }
     if (!PR_UPDATED_REVIEW_FROM_STATUSES.includes(task.status))
         return;
     let reviewHead = eventHeadSha ?? validHeadSha(task.latestHeadSha);
@@ -545,6 +609,7 @@ async function handlePrCodePush(bus, manager, event) {
         return;
     }
     const bumpRound = task.status === 'in_progress'
+        || task.status === 'spec-ready'
         || task.status === 'approved'
         || task.status === 'merge-ready'
         || (task.status === 'review' && task.reviewRoundPending === true);
@@ -573,6 +638,7 @@ async function handlePrCodePush(bus, manager, event) {
         return;
     }
     const qaPhase = begun.task.reviewDispatch.qaPhase;
+    const qaAgentId = requireTaskQaAgentId(begun.task, 'handlePrUpdated');
     try {
         await manager.dispatchGitReviewLease(taskId, {
             expectedGeneration: begun.task.reviewDispatch.generation,
@@ -587,8 +653,8 @@ async function handlePrCodePush(bus, manager, event) {
                 error: err.message,
             });
         }
-        else if (err instanceof DispatchTerminalError && begun.task.qaAgentId) {
-            await manager.failTaskForDispatchError(taskId, qaPhase, begun.task.qaAgentId, err, {
+        else if (err instanceof DispatchTerminalError) {
+            await manager.failTaskForDispatchError(taskId, qaPhase, qaAgentId, err, {
                 expectedReviewDispatch: begun.task.reviewDispatch,
             });
         }
@@ -604,28 +670,22 @@ async function handlePrCodePush(bus, manager, event) {
 async function redispatchReviewForStaleVerdict(manager, task) {
     if (task.status !== 'review')
         return false;
-    if (task.qaAgentId) {
-        // 当前 pass 的 QA 会话还在跑时，迟到的旧 verdict 只是噪音，不能重派打断；
-        // 派发期 hold（checkout 未备好）意味着从未开工，等同无会话，可安全重派
-        let qaState;
-        try {
-            qaState = await manager.getAgentState(task.qaAgentId);
-        }
-        catch (err) {
-            // 无状态证据时 fail closed：不自动重派，让调用方落 stale-verdict 兜底介入
-            console.warn(`[EventHandler] stale-verdict QA state read failed for ${task.qaAgentId}; not redispatching:`, err);
-            return false;
-        }
-        if (qaState?.taskId === task.id && !isRecoverableQaDispatchHold(qaState))
-            return false;
+    const qaAgentId = requireTaskQaAgentId(task, 'redispatchReviewForStaleVerdict');
+    let qaState;
+    try {
+        qaState = await manager.getAgentState(qaAgentId);
     }
+    catch (err) {
+        console.warn(`[EventHandler] stale-verdict QA state read failed for ${qaAgentId}; not redispatching:`, err);
+        return false;
+    }
+    if (qaState?.taskId === task.id && !isRecoverableQaDispatchHold(qaState))
+        return false;
     try {
-        // fromStatus/expectSignalToken 在 dispatch 锁内复核：本地快照到这里的窗口里任务可能已离开 review
-        // 或被并发 dispatcher 换代 pass，不能靠上面的预检
         const entry = manager.getPendingDispatchRetry(task.id);
         const qaPhase = entry?.kind === 'qa-recheck' && entry.signalToken === task.signalToken && entry.qaPhase !== undefined
             ? entry.qaPhase
-            : (task.reviewRound === 0 ? 'review' : undefined);
+            : (taskReviewRound(task) === 0 ? 'review' : undefined);
         await manager.dispatchReviewToQa(task.id, {
             fromStatus: ['review'],
             bumpRound: task.reviewRoundPending === true,
@@ -653,6 +713,7 @@ async function handleReviewApproval(bus, manager, task, reviewedHeadSha, current
     }
     if (task.failToken === undefined || task.signalToken === undefined)
         return;
+    const expectedSignalToken = task.signalToken;
     const provenance = {
         sourceKey: gitVerdict.carrier.sourceKey,
         id: gitVerdict.carrier.id,
@@ -661,9 +722,67 @@ async function handleReviewApproval(bus, manager, task, reviewedHeadSha, current
         failToken: task.failToken,
         anchorSha: reviewedHeadSha,
     };
-    const reviewedRound = Math.max(1, task.reviewRound + (task.reviewRoundPending === true ? 1 : 0));
+    const reviewedRound = effectiveTaskReviewRound(task);
+    if (task.phase === 'spec') {
+        const humanApproval = manager.getProjectConfig(task.projectId)?.specApproval === 'human';
+        if (!humanApproval) {
+            let verified;
+            try {
+                verified = await manager.platformVerifyPrBinding(task.id, gitVerdict.prNumber);
+            }
+            catch (err) {
+                await emitIntervention(bus, task.projectId, task.agentId, task.id, {
+                    phase: 'git-spec-auto-approve-head-verify-failed',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                throw err;
+            }
+            if (!verified.ok) {
+                await emitIntervention(bus, task.projectId, task.agentId, task.id, {
+                    phase: 'git-spec-auto-approve-binding-invalid',
+                    reason: verified.reason,
+                });
+                throw new Error(`automatic spec approval binding is invalid: ${verified.reason}`);
+            }
+            if (verified.headSha.toLowerCase() !== reviewedHeadSha.toLowerCase()) {
+                await emitIntervention(bus, task.projectId, task.agentId, task.id, {
+                    phase: 'git-spec-auto-approve-head-mismatch',
+                    reviewedHeadSha,
+                    currentHeadSha: verified.headSha,
+                    source: 'platform-live-read',
+                });
+                return;
+            }
+        }
+        const expectedTask = taskGenerationGuard(task);
+        const approval = {
+            specReviewRound: reviewedRound,
+            expectedSignalToken,
+            ...(prPatch.prNumber !== undefined ? { prNumber: prPatch.prNumber } : {}),
+            ...(prPatch.prUrl !== undefined ? { prUrl: prPatch.prUrl } : {}),
+            headSha: reviewedHeadSha,
+            passProvenance: provenance,
+        };
+        const transitioned = humanApproval
+            ? await manager.parkTaskAtSpecReady(task.id, {
+                specReviewRound: reviewedRound,
+                expectedTask,
+                expectedSignalToken,
+                ...(prPatch.prNumber !== undefined ? { prNumber: prPatch.prNumber } : {}),
+                ...(prPatch.prUrl !== undefined ? { prUrl: prPatch.prUrl } : {}),
+                headSha: reviewedHeadSha,
+                passProvenance: provenance,
+            })
+            : await manager.transitionToCodePhase(task.id, expectedTask, approval);
+        if (!transitioned) {
+            await emitIntervention(bus, task.projectId, task.agentId, task.id, {
+                phase: 'git-spec-approve-transition-failed',
+            });
+        }
+        return;
+    }
     const transitioned = await manager.approveGitReviewPass(task.id, {
-        expectedSignalToken: task.signalToken,
+        expectedSignalToken,
         headSha: reviewedHeadSha,
         reviewRound: reviewedRound,
         ...(prPatch.prNumber !== undefined ? { prNumber: prPatch.prNumber } : {}),
@@ -673,10 +792,9 @@ async function handleReviewApproval(bus, manager, task, reviewedHeadSha, current
     if (!transitioned)
         return;
     manager.stopPhaseSignalWatcher(transitioned.id);
-    if (transitioned.qaAgentId) {
-        await manager.releaseAgentForTask(transitioned.qaAgentId, transitioned.id, 'idle', { allowAwaitingHuman: true })
-            .catch(err => console.error(`[EventHandler] APPROVE releaseAgentForTask(QA=${transitioned.qaAgentId}) failed:`, err));
-    }
+    const qaAgentId = requireTaskQaAgentId(transitioned, 'handleReviewApproval');
+    await manager.releaseAgentForTask(qaAgentId, transitioned.id, 'idle', { allowAwaitingHuman: true })
+        .catch(err => console.error(`[EventHandler] APPROVE releaseAgentForTask(QA=${qaAgentId}) failed:`, err));
     await dispatchGitDevPostApproveCheck(bus, manager, transitioned, reviewedHeadSha);
 }
 function gitHeadPatch(task, headSha) {
@@ -694,9 +812,10 @@ async function handleReviewRequestChanges(bus, manager, task, reviewedHeadSha, c
         });
         return;
     }
-    const reviewedRound = Math.max(1, task.reviewRound + (task.reviewRoundPending === true ? 1 : 0));
+    const reviewedRound = effectiveTaskReviewRound(task);
     const nextRound = reviewedRound + 1;
-    if (nextRound > manager.getConfig().review.rounds) {
+    const cap = manager.getConfig().review.rounds + (task.maxRoundsContinues ?? 0);
+    if (nextRound > cap) {
         return handleMaxRounds(bus, manager, task, prPatch, reviewedRound);
     }
     const result = await manager.transitionTaskStatus(task.id, 'fixing', {
@@ -705,7 +824,9 @@ async function handleReviewRequestChanges(bus, manager, task, reviewedHeadSha, c
     }, {
         ...prPatch,
         ...gitHeadPatch(task, currentHeadSha),
-        reviewRound: nextRound,
+        ...(task.phase === 'spec'
+            ? { specReviewRound: nextRound }
+            : { reviewRound: nextRound }),
         reviewRoundPending: undefined,
         reviewDispatch: undefined,
         fixDispatchedAt: new Date().toISOString(),
@@ -715,80 +836,7 @@ async function handleReviewRequestChanges(bus, manager, task, reviewedHeadSha, c
     const { task: transitioned } = result;
     await manager.clearPostApproveCompletion(transitioned.id);
     manager.stopPhaseSignalWatcher(transitioned.id);
-    if (transitioned.qaAgentId) {
-        const qaReleased = await manager
-            .releaseAgentForTask(transitioned.qaAgentId, transitioned.id, 'idle', { allowAwaitingHuman: true })
-            .catch(err => {
-            console.error(`[EventHandler] REQUEST_CHANGES releaseAgentForTask(QA=${transitioned.qaAgentId}) failed:`, err);
-            return false;
-        });
-        if (!qaReleased) {
-            await emitIntervention(bus, transitioned.projectId, transitioned.agentId, transitioned.id, {
-                phase: 'qa-release-failed-but-dev-dispatched',
-                qaAgentId: transitioned.qaAgentId,
-            });
-        }
-    }
-    const acquired = await manager.acquireAgentForTask(transitioned.agentId, transitioned.id, 'fix');
-    if (!acquired) {
-        await emitIntervention(bus, transitioned.projectId, transitioned.agentId, transitioned.id, {
-            phase: 'dev-acquire-failed-fix',
-            devAgentId: transitioned.agentId,
-        });
-        return;
-    }
-    const { token: fixToken, armed } = await manager.rotateAndSetupPhaseSignal(transitioned.id, transitioned.agentId, 'pr-fixed', { expectedStatus: 'fixing', expectedToken: transitioned.signalToken });
-    if (!armed) {
-        console.warn(`[EventHandler] REQUEST_CHANGES pr-fixed watcher failed to arm for task=${transitioned.id}; holding dev (not dispatching fix)`);
-        await manager.markAwaitingHuman(transitioned.agentId, 'signal-arm-failed:pr-fixed', 'pr-fixed watcher failed to arm; the fix was not dispatched (its completion signal would have no consumer). Cancel the task or delete the agent to retry.', { expectedTaskId: transitioned.id });
-        return;
-    }
-    let resumed = false;
-    let dispatchErr = null;
-    try {
-        resumed = await manager.continueSession(transitioned.id, transitioned.agentId, 'fix', {
-            signalToken: fixToken,
-            guardBeforeInject: async () => {
-                const freshTask = await manager.getTask(transitioned.id);
-                return freshTask?.status === 'fixing' && freshTask.signalToken === fixToken;
-            },
-        });
-    }
-    catch (err) {
-        dispatchErr = err;
-        console.error(`[EventHandler] REQUEST_CHANGES continueSession(dev=${transitioned.agentId}, fix) failed:`, err);
-    }
-    if (!resumed) {
-        console.warn(`[EventHandler] REQUEST_CHANGES dev=${transitioned.agentId} not resumable for task=${transitioned.id}; ` +
-            `task remains in 'fixing' but no dev session is attached`);
-        if (dispatchErr instanceof DispatchTerminalError) {
-            await manager.failTaskForDispatchError(transitioned.id, 'fix', transitioned.agentId, dispatchErr);
-        }
-        else {
-            const parked = await manager.markAgentWaiting(transitioned.agentId, transitioned.id)
-                .catch(err => {
-                console.error(`[EventHandler] REQUEST_CHANGES markAgentWaiting(dev=${transitioned.agentId}) rollback failed:`, err);
-                return false;
-            });
-            if (parked && (dispatchErr instanceof ReplNotReadyError || dispatchErr instanceof DirtyWorkdirError)) {
-                // dev 回合在途（忙碌/未提交改动）是常态而非故障：登记待补派，回合结束后由对账 re-continue。
-                // 停驻失败说明绑定/锁已不受控，pending 无法证明还有可承接的 session，必须走人工告警
-                manager.registerPendingDispatchRetry(transitioned.id, {
-                    kind: 'dev-fix',
-                    agentId: transitioned.agentId,
-                    signalToken: fixToken,
-                });
-                console.warn(`[EventHandler] REQUEST_CHANGES fix deferred for task=${transitioned.id}: dev pane busy or workdir dirty ` +
-                    `(${dispatchErr.name}); reconciler will re-continue when idle`);
-            }
-            else {
-                await emitIntervention(bus, transitioned.projectId, transitioned.agentId, transitioned.id, {
-                    phase: 'fix-resume-failed',
-                    reviewRound: transitioned.reviewRound,
-                });
-            }
-        }
-    }
+    await manager.dispatchGitFixToDev(transitioned.id);
 }
 async function handleMaxRounds(bus, manager, task, prPatch, reviewedRound) {
     const result = await manager.transitionTaskStatus(task.id, 'max_rounds', {
@@ -796,7 +844,9 @@ async function handleMaxRounds(bus, manager, task, prPatch, reviewedRound) {
         expectSignalToken: task.signalToken,
     }, {
         ...prPatch,
-        reviewRound: reviewedRound,
+        ...(task.phase === 'spec'
+            ? { specReviewRound: reviewedRound }
+            : { reviewRound: reviewedRound }),
         reviewRoundPending: undefined,
         reviewDispatch: undefined,
     });
@@ -805,16 +855,15 @@ async function handleMaxRounds(bus, manager, task, prPatch, reviewedRound) {
     const { task: transitioned } = result;
     await manager.clearPostApproveCompletion(transitioned.id);
     manager.stopPhaseSignalWatcher(transitioned.id);
-    if (transitioned.qaAgentId) {
-        const qaState = await manager.getAgentState(transitioned.qaAgentId);
-        if (qaState?.taskId === transitioned.id) {
-            await manager
-                .releaseAgentForTask(transitioned.qaAgentId, transitioned.id, 'idle', { allowAwaitingHuman: true })
-                .catch(err => {
-                console.error(`[EventHandler] max_rounds releaseAgentForTask(QA=${transitioned.qaAgentId}) failed:`, err);
-                return false;
-            });
-        }
+    const qaAgentId = requireTaskQaAgentId(transitioned, 'handleMaxRounds');
+    const qaState = await manager.getAgentState(qaAgentId);
+    if (qaState?.taskId === transitioned.id) {
+        await manager
+            .releaseAgentForTask(qaAgentId, transitioned.id, 'idle', { allowAwaitingHuman: true })
+            .catch(err => {
+            console.error(`[EventHandler] max_rounds releaseAgentForTask(QA=${qaAgentId}) failed:`, err);
+            return false;
+        });
     }
     try {
         await bus.emit({
@@ -824,7 +873,10 @@ async function handleMaxRounds(bus, manager, task, prPatch, reviewedRound) {
             projectId: transitioned.projectId,
             agentId: transitioned.agentId,
             taskId: transitioned.id,
-            data: { reviewRound: transitioned.reviewRound },
+            data: {
+                phase: transitioned.phase,
+                reviewRound: taskReviewRound(transitioned),
+            },
         });
     }
     catch (emitErr) {
@@ -832,37 +884,17 @@ async function handleMaxRounds(bus, manager, task, prPatch, reviewedRound) {
     }
 }
 export function registerEventHandlers(bus, manager) {
-    bus.on('pr.created', async (event) => {
+    const handleGitPrDelivery = async (event, deliveryPhase) => {
         if (!event.taskId || !event.agentId)
             return;
         const taskAtEntry = await manager.getTask(event.taskId);
         if (!taskAtEntry)
             return;
-        if (taskAtEntry.reviewMode === 'server') {
-            const prNumber = event.data.prNumber;
-            if (!Number.isInteger(prNumber) || prNumber < 1)
-                return;
-            const adopted = await manager.adoptServerPr(event.taskId, {
-                prNumber: prNumber,
-                ...(typeof event.data.prUrl === 'string' ? { prUrl: event.data.prUrl } : {}),
-                ...(validHeadSha(event.data.headSha) !== undefined ? { headSha: validHeadSha(event.data.headSha) } : {}),
-                ...(typeof event.data.targetBranch === 'string' ? { targetBranch: event.data.targetBranch } : {}),
-            });
-            if (!adopted) {
-                await emitIntervention(bus, taskAtEntry.projectId, taskAtEntry.agentId, taskAtEntry.id, {
-                    phase: 'server-pr-adoption-refused',
-                    prNumber,
-                });
-            }
-            return;
-        }
-        if (isSpecStagePhase(taskAtEntry.phase)) {
-            console.warn(`[EventHandler] pr.created ignored for task ${event.taskId}: task in spec phase`);
-            return;
-        }
         if (event.data.source === 'pane-signal'
             && taskAtEntry.prNumber !== undefined && taskAtEntry.prNumber === event.data.prNumber
             && taskAtEntry.status !== 'in_progress') {
+            if (taskAtEntry.phase !== deliveryPhase)
+                return;
             if (taskAtEntry.pendingPrSignalToken === undefined
                 || event.data.token !== taskAtEntry.pendingPrSignalToken) {
                 return;
@@ -948,8 +980,8 @@ export function registerEventHandlers(bus, manager) {
                 return;
             }
         }
-        const task = await manager.getTask(event.taskId);
-        if (!task || task.reviewMode !== 'git')
+        let task = await manager.getTask(event.taskId);
+        if (!task)
             return;
         if (event.data.source !== 'pane-signal'
             && task.branch !== BRANCH_PREFIX + event.taskId
@@ -958,26 +990,9 @@ export function registerEventHandlers(bus, manager) {
                 `for task ${event.taskId} (untracked; custom-branch PRs adopt via the pane signal)`);
             return;
         }
-        const adoption = {};
         const target = event.data.source === 'pane-signal'
             ? verifiedTargetBranch
             : (typeof event.data.targetBranch === 'string' ? event.data.targetBranch : undefined);
-        if (target !== undefined && task.baseBranch === undefined)
-            adoption.baseBranch = target;
-        if (event.data.source === 'pane-signal') {
-            const actorId = typeof event.data.actorB64 === 'string'
-                ? decodeSignalActorId(event.data.actorB64)
-                : undefined;
-            if (actorId !== undefined) {
-                adoption.replyActorId = actorId;
-                adoption.replyActorStatus = 'verified';
-                adoption.pendingPrSignalToken = undefined;
-            }
-        }
-        else if (typeof event.data.prAuthorId === 'string' && task.replyActorStatus !== 'verified') {
-            adoption.replyActorId = event.data.prAuthorId;
-            adoption.replyActorStatus = 'provisional';
-        }
         let reviewHead = validHeadSha(event.data.headSha) ?? paneVerifiedHeadSha;
         if (reviewHead === undefined && typeof event.data.prNumber === 'number') {
             const verified = await manager.platformVerifyPrBinding(event.taskId, event.data.prNumber);
@@ -990,6 +1005,54 @@ export function registerEventHandlers(bus, manager) {
             });
             return;
         }
+        if (deliveryPhase === undefined) {
+            if (typeof event.data.prNumber !== 'number')
+                return;
+            await manager.recordGitPrObservation(event.taskId, {
+                prNumber: event.data.prNumber,
+                ...(typeof event.data.prUrl === 'string' ? { prUrl: event.data.prUrl } : {}),
+                headSha: reviewHead,
+                ...(target !== undefined ? { targetBranch: target } : {}),
+                ...(typeof event.data.prAuthorId === 'string' ? { prAuthorId: event.data.prAuthorId } : {}),
+            });
+            return;
+        }
+        const actorId = typeof event.data.actorB64 === 'string'
+            ? decodeSignalActorId(event.data.actorB64)
+            : undefined;
+        if (actorId === undefined || typeof event.data.prNumber !== 'number') {
+            await reArmDevelopWatcher(manager, task, event.agentId);
+            await emitIntervention(bus, task.projectId, event.agentId, event.taskId, {
+                phase: 'git-pr-delivery-actor-missing',
+                deliveryPhase,
+                claimedPrNumber: event.data.prNumber,
+            });
+            return;
+        }
+        const confirmed = await manager.confirmGitDelivery(event.taskId, {
+            phase: deliveryPhase,
+            source: 'signal',
+            prNumber: event.data.prNumber,
+            ...(typeof event.data.prUrl === 'string' ? { prUrl: event.data.prUrl } : {}),
+            headSha: reviewHead,
+            ...(target !== undefined ? { targetBranch: target } : {}),
+            ...(reconciledBranch !== undefined ? { branch: reconciledBranch } : {}),
+            actorId,
+            expectedSignalToken: typeof event.data.token === 'string' ? event.data.token : undefined,
+        });
+        if (!confirmed) {
+            const current = await manager.getTask(event.taskId);
+            if (current?.status === 'in_progress') {
+                await reArmDevelopWatcher(manager, current, event.agentId);
+                await emitIntervention(bus, current.projectId, event.agentId, event.taskId, {
+                    phase: 'pane-pr-delivery-transition-failed',
+                    deliveryPhase,
+                    claimedPrNumber: event.data.prNumber,
+                });
+            }
+            return;
+        }
+        task = confirmed;
         if (task.status !== 'in_progress' && task.status !== 'fixing')
             return;
         const begun = await manager.beginGitReviewPass(event.taskId, {
@@ -1000,11 +1063,7 @@ export function registerEventHandlers(bus, manager) {
             expectPhase: task.phase,
             expectSignalToken: task.signalToken,
             patch: {
-                ...(event.data.prNumber !== undefined ? { prNumber: event.data.prNumber } : {}),
-                ...(event.data.prUrl !== undefined ? { prUrl: event.data.prUrl } : {}),
                 latestHeadSha: reviewHead,
-                ...(reconciledBranch ? { branch: reconciledBranch } : {}),
-                ...adoption,
             },
         });
         if (!begun?.task.reviewDispatch) {
@@ -1025,18 +1084,7 @@ export function registerEventHandlers(bus, manager) {
         if (reconciledBranch) {
             console.log(`[EventHandler] pr.created reconciled branch for task ${event.taskId}: ${task.branch} → ${reconciledBranch}`);
         }
-        if (!begun.task.qaAgentId) {
-            const parked = await manager.markAgentWaiting(event.agentId, begun.task.id);
-            if (!parked) {
-                await emitIntervention(bus, begun.task.projectId, begun.task.agentId, begun.task.id, {
-                    phase: 'dev-wait-gate-failed-no-qa',
-                });
-            }
-            await emitIntervention(bus, begun.task.projectId, begun.task.agentId, begun.task.id, {
-                phase: 'git-review-no-qa-partner',
-            });
-            return;
-        }
+        const qaAgentId = requireTaskQaAgentId(begun.task, 'pr.created');
         try {
             await manager.dispatchGitReviewLease(begun.task.id, {
                 expectedGeneration: begun.task.reviewDispatch.generation,
@@ -1052,7 +1100,7 @@ export function registerEventHandlers(bus, manager) {
                 });
             }
             else if (err instanceof DispatchTerminalError) {
-                await manager.failTaskForDispatchError(begun.task.id, 'review', begun.task.qaAgentId, err, {
+                await manager.failTaskForDispatchError(begun.task.id, 'review', qaAgentId, err, {
                     expectedReviewDispatch: begun.task.reviewDispatch,
                 });
             }
@@ -1064,16 +1112,20 @@ export function registerEventHandlers(bus, manager) {
                 });
             }
         }
+    };
+    bus.on('pr.created', async (event) => {
+        await handleGitPrDelivery(event, event.data.source === 'pane-signal' ? 'code' : undefined);
+    });
+    bus.on('spec.ready', async (event) => {
+        const task = event.taskId ? await manager.getTask(event.taskId) : null;
+        if (!task)
+            return;
+        await handleGitPrDelivery(event, 'spec');
     });
     bus.on('pr.updated', async (event) => {
         if (!event.taskId)
             return;
-        const taskAtEntry = await manager.getTask(event.taskId);
         const eventKind = event.data.kind;
-        if (taskAtEntry && isSpecStagePhase(taskAtEntry.phase)) {
-            console.warn(`[EventHandler] pr.updated (kind=${eventKind ?? 'push'}) ignored for task ${event.taskId}: task in spec phase`);
-            return;
-        }
         if (eventKind === 'pr-merge-ready')
             return handlePrMergeReady(bus, manager, event);
         if (eventKind === 'closed-unmerged' || eventKind === 'reopened') {
@@ -1089,8 +1141,6 @@ export function registerEventHandlers(bus, manager) {
         }
         if (!event.agentId)
             return;
-        if (taskAtEntry?.reviewMode === 'server')
-            return;
         if (eventKind === 'comment' || eventKind === 'review-comment') {
             return handlePrFeedback(bus, manager, event);
         }
@@ -1100,43 +1150,125 @@ export function registerEventHandlers(bus, manager) {
     bus.on('pr.merged', async (event) => {
         if (!event.taskId)
             return;
+        const taskId = event.taskId;
         const eventPrNumber = event.data.prNumber;
         const eventPrUrl = event.data.prUrl;
-        // The poller surfaces every merged PR on a managed branch — including a stale one whose number
-        // this task never tracked (e.g. a reused custom branch name). bx/<taskId> is unique to this task,
-        // so its merge is definitively ours even if pr.created was missed and prNumber was never recorded;
-        // for any other branch require the tracked PR number to match, else a foreign/stale merge on a
-        // reused custom branch name could prematurely finish an active task.
-        const taskBefore = await manager.getTask(event.taskId);
+        const taskBefore = await manager.getTask(taskId);
         if (!taskBefore)
             return;
-        if (isSpecStagePhase(taskBefore.phase))
+        const mergedOwnBxBranch = event.data.branch === BRANCH_PREFIX + taskId;
+        const sameBoundPr = eventPrNumber !== undefined
+            && (taskBefore.prNumber === eventPrNumber || (taskBefore.prNumber === undefined && mergedOwnBxBranch));
+        if (eventPrNumber !== undefined && !sameBoundPr) {
+            await emitIntervention(bus, taskBefore.projectId, taskBefore.agentId, taskBefore.id, {
+                phase: 'pr-merged-status-race',
+                status: taskBefore.status,
+                reason: taskBefore.prNumber === undefined ? 'pr-binding-unconfirmed' : 'pr-binding-changed',
+                boundPrNumber: taskBefore.prNumber,
+                prNumber: eventPrNumber,
+            });
             return;
-        const mergedOwnBxBranch = event.data.branch === BRANCH_PREFIX + event.taskId;
-        if (!mergedOwnBxBranch && typeof eventPrNumber === 'number' && taskBefore.prNumber !== eventPrNumber)
+        }
+        if ((taskBefore.status === 'merged' || taskBefore.status === 'done') && sameBoundPr)
             return;
+        let mergeExpectedPrNumber = taskBefore.prNumber;
+        let mergeBindingConfirmed = sameBoundPr;
         const prPatch = {
             ...(eventPrNumber !== undefined ? { prNumber: eventPrNumber } : {}),
             ...(eventPrUrl !== undefined ? { prUrl: eventPrUrl } : {}),
         };
-        const result = await manager.transitionTaskStatus(event.taskId, 'merged', { fromStatus: ['in_progress', 'fixing', 'review', 'approved', 'merge-ready', 'ready', 'max_rounds'] }, prPatch);
-        if (!result)
+        if (taskBefore.status !== 'merge-ready') {
+            if (!sameBoundPr || !PREMATURE_MERGE_BLOCKABLE_STATUSES.includes(taskBefore.status)) {
+                await emitIntervention(bus, taskBefore.projectId, taskBefore.agentId, taskBefore.id, {
+                    phase: 'pr-merged-outside-merge-ready',
+                    status: taskBefore.status,
+                    taskPhase: taskBefore.phase,
+                    ...(eventPrNumber !== undefined ? { prNumber: eventPrNumber } : {}),
+                });
+                return;
+            }
+            const blocked = await manager.transitionTaskStatus(taskId, 'failed', {
+                fromStatus: PREMATURE_MERGE_BLOCKABLE_STATUSES,
+                expectPrNumber: taskBefore.prNumber,
+            }, prPatch);
+            if (blocked) {
+                manager.stopPhaseSignalWatcher(taskId);
+                await emitIntervention(bus, blocked.task.projectId, blocked.task.agentId, blocked.task.id, {
+                    phase: 'pr-merged-outside-merge-ready',
+                    status: blocked.previousStatus,
+                    taskPhase: blocked.task.phase,
+                    ...(eventPrNumber !== undefined ? { prNumber: eventPrNumber } : {}),
+                });
+                await cleanupPrematureMergeParticipants(bus, manager, blocked.task);
+                return;
+            }
+            const current = await manager.getTask(taskId);
+            if (!current)
+                return;
+            const currentSameBoundPr = eventPrNumber !== undefined
+                && (current.prNumber === eventPrNumber || (current.prNumber === undefined && mergedOwnBxBranch));
+            if ((current.status === 'merged' || current.status === 'done') && currentSameBoundPr)
+                return;
+            if (!currentSameBoundPr) {
+                await emitIntervention(bus, current.projectId, current.agentId, current.id, {
+                    phase: 'pr-merged-status-race',
+                    status: current.status,
+                    reason: 'pr-binding-changed',
+                    boundPrNumber: current.prNumber,
+                    ...(eventPrNumber !== undefined ? { prNumber: eventPrNumber } : {}),
+                });
+                return;
+            }
+            if (current.status !== 'merge-ready') {
+                await emitIntervention(bus, current.projectId, current.agentId, current.id, {
+                    phase: 'pr-merged-status-race',
+                    status: current.status,
+                    ...(eventPrNumber !== undefined ? { prNumber: eventPrNumber } : {}),
+                });
+                return;
+            }
+            mergeExpectedPrNumber = current.prNumber;
+            mergeBindingConfirmed = true;
+        }
+        if (!mergeBindingConfirmed) {
+            await emitIntervention(bus, taskBefore.projectId, taskBefore.agentId, taskBefore.id, {
+                phase: 'pr-merged-status-race',
+                status: taskBefore.status,
+                reason: 'pr-binding-unconfirmed',
+                boundPrNumber: taskBefore.prNumber,
+                ...(eventPrNumber !== undefined ? { prNumber: eventPrNumber } : {}),
+            });
+            return;
+        }
+        const result = await manager.transitionTaskStatus(taskId, 'merged', { fromStatus: ['merge-ready'], expectPrNumber: mergeExpectedPrNumber }, prPatch);
+        if (!result) {
+            const current = await manager.getTask(event.taskId);
+            if (current && (current.status === 'merged' || current.status === 'done')
+                && eventPrNumber !== undefined && current.prNumber === eventPrNumber)
+                return;
+            if (current) {
+                await emitIntervention(bus, current.projectId, current.agentId, current.id, {
+                    phase: 'pr-merged-status-race',
+                    status: current.status,
+                    ...(eventPrNumber !== undefined ? { prNumber: eventPrNumber } : {}),
+                });
+            }
             return;
+        }
         const { task: transitioned } = result;
-        if (transitioned.qaAgentId) {
-            if (transitioned.prNumber && transitioned.branch) {
-                await manager.dispatchPostMergeCleanup(transitioned.qaAgentId, {
-                    taskId: transitioned.id,
-                    branch: transitioned.branch,
-                }).catch(err => console.warn(`[EventHandler] pr.merged dispatchPostMergeCleanup(QA=${transitioned.qaAgentId}) failed:`, err));
+        const qaAgentId = requireTaskQaAgentId(transitioned, 'pr.merged');
+        if (transitioned.prNumber && transitioned.branch) {
+            await manager.dispatchPostMergeCleanup(qaAgentId, {
+                taskId: transitioned.id,
+                branch: transitioned.branch,
+            }).catch(err => console.warn(`[EventHandler] pr.merged dispatchPostMergeCleanup(QA=${qaAgentId}) failed:`, err));
+        }
+        else {
+            try {
+                await manager.releaseAgentForTask(qaAgentId, transitioned.id, 'idle');
             }
-            else {
-                try {
-                    await manager.releaseAgentForTask(transitioned.qaAgentId, transitioned.id, 'idle');
-                }
-                catch (err) {
-                    console.error(`[EventHandler] pr.merged releaseAgentForTask(QA=${transitioned.qaAgentId}) failed:`, err);
-                }
+            catch (err) {
+                console.error(`[EventHandler] pr.merged releaseAgentForTask(QA=${qaAgentId}) failed:`, err);
             }
         }
         try {
@@ -1152,8 +1284,6 @@ export function registerEventHandlers(bus, manager) {
         const task = await manager.getTask(event.taskId);
         if (!task)
             return;
-        if (task.reviewMode === 'server')
-            return;
         if (event.data.source === 'pane-signal') {
             console.log(`[EventHandler] review.submitted pane verdict ignored for task ${task.id} (comment-token protocol is the sole authority)`);
             return;
@@ -1199,10 +1329,6 @@ export function registerEventHandlers(bus, manager) {
             await rejectGitPayload(new GitVerdictPayloadError('verdict token is not current'));
             return;
         }
-        if (isSpecStagePhase(task.phase)) {
-            console.warn(`[EventHandler] review.submitted (action=${action}) ignored for task ${task.id}: task in spec phase`);
-            return;
-        }
         const verdictSubmittedAt = typeof event.data.submittedAt === 'string' ? event.data.submittedAt : undefined;
         if (verdictSubmittedAt && task.reviewDispatchedAt) {
             const submittedMs = Date.parse(verdictSubmittedAt);
@@ -1241,7 +1367,7 @@ export function registerEventHandlers(bus, manager) {
         if (!event.taskId || !event.agentId)
             return;
         const task = await manager.getTask(event.taskId);
-        if (!task || task.reviewMode === 'server' || task.status !== 'fixing' || isSpecStagePhase(task.phase))
+        if (!task || task.status !== 'fixing')
             return;
         const { projectId, agentId } = task;
         const stayFixing = async (data) => {
@@ -1279,7 +1405,6 @@ export function registerEventHandlers(bus, manager) {
             return;
         }
         if (!verify.ok) {
-            // PR 在修复期间被关闭/转 draft/retarget：推进 recheck 只会造出无裁决入口的评审轮
             await stayFixing({ phase: 'fix-verify-binding-mismatch', reason: verify.reason });
             return;
         }
@@ -1309,12 +1434,9 @@ export function registerEventHandlers(bus, manager) {
                 return;
             }
         }
-        // head fetch / 回复检查是秒级网络等待，期间真 push / verdict 可能已换代 pass；旧信号不得再驱动派发
         const preEmit = await manager.getTask(task.id);
         if (!preEmit || preEmit.status !== 'fixing' || preEmit.signalToken !== token)
             return;
-        // head 前进时不能指望 poller：push 事件已被消费（cursor 不回退），若那次派发失败回滚，
-        // 这里的合成 push 是唯一重试入口；宁可与迟到的真 push 竞态重派一轮，也不静默滞留 fixing
         await bus.emit({
             id: '',
             type: 'pr.updated',