baxian 1.0.3 → 1.2.0

package/dist/agent/manager.js

@@ -12,6 +12,7 @@ import { TmuxManager, ReplNotReadyError, detectStartupDialog, detectRuntimeMenu,
 import { WorktreeManager } from './worktree.js';
 import { RepoStore, createRepoStoreCache } from './repo-store.js';
 import { PhaseSignalWatcher } from './phase-signal-watcher.js';
+import { ReviewTransport } from './review-transport.js';
 import { buildPromptInline, buildPostMergeCleanupPrompt, PromptSizeError, RequiredSkillsMissingError, MAX_PROMPT_BYTES_ROUTE_LIMIT, } from './prompt.js';
 import { ApiError } from '../errors.js';
 export class EnsureSessionError extends Error {
@@ -73,7 +74,7 @@ function agentRuntimeKindFor(agent) {
 const DEFAULT_DISPATCH_ACK_TIMEOUT_MS = 30_000;
 const DEFAULT_DISPATCH_SETTLE_TIMEOUT_MS = 3_000;
 // Dev-facing deliverable phases that weave the task's uploaded image paths into the prompt (task-055).
-const IMAGE_DISPATCH_PHASES = new Set(['develop', 'code', 'fix', 'spec-fix']);
+const IMAGE_DISPATCH_PHASES = new Set(['develop', 'code', 'fix', 'server-feedback']);
 export function canDispatchWithBinding(binding) {
     return !binding?.taskId && !binding?.creationToken && binding?.status !== 'awaiting_human';
 }
@@ -115,6 +116,8 @@ export class AgentManager {
     postApproveStore;
     phaseSignalWatcher;
     errorRecordStore;
+    reviewStore;
+    reviewTransportInstance;
     dispatchAckTimeoutMs;
     dispatchSettleTimeoutMs;
     // Re-send Enter after this long of continuous post-paste idle — recovers a swallowed first Enter
@@ -129,6 +132,7 @@ export class AgentManager {
     runtimeMenuPollIntervalMs = 10_000;
     compactIdleWaitMs = 5 * 60_000;
     compactIdlePollMs = 2_000;
+    manualCompactWaitMs = 5_000;
     postMergeFetchTimeoutMs = 60_000;
     postMergeBranchTimeoutMs = 10_000;
     // taskIds with in-flight manual review — second concurrent POST gets 409.
@@ -140,6 +144,7 @@ export class AgentManager {
     // agentIds with in-flight DELETE — 第二个 DELETE 撞 awaiting_human stale-lock takeover 路径会
     // 把第一个 DELETE 持有的占位也当 stale 接管，导致并发 cleanupRemovedAgentRuntime。
     deletionInFlight = new Set();
+    compactInFlight = new Set();
     constructor(deps) {
         this.config = deps.config;
         this.agentStore = deps.agentStore;
@@ -160,6 +165,7 @@ export class AgentManager {
                     resolveAgent: (id) => this.getAgentConfig(id),
                 })
                 : undefined);
+        this.reviewStore = deps.reviewStore;
         this.dispatchAckTimeoutMs = deps.dispatchAckTimeoutMs ?? DEFAULT_DISPATCH_ACK_TIMEOUT_MS;
         this.dispatchSettleTimeoutMs = deps.dispatchSettleTimeoutMs ?? DEFAULT_DISPATCH_SETTLE_TIMEOUT_MS;
         this.agentIndex = buildAgentIndex(deps.config);
@@ -176,6 +182,36 @@ export class AgentManager {
         this.taskMutationQueue = next.catch(() => undefined);
         return next;
     }
+    getReviewStore() {
+        return this.reviewStore;
+    }
+    // Snapshot-aware afterDone read: an EXPLICIT null snapshot must win over hot
+    // config — `??` would swallow it and reroute an already-decided task (PR #288).
+    resolveAfterDone(task) {
+        if (task.afterDone !== undefined)
+            return task.afterDone;
+        return this.config.review.afterDone ?? null;
+    }
+    getReviewTransport() {
+        this.reviewTransportInstance ??= new ReviewTransport({
+            createRunnerFor: (agent) => this.createRunnerFor(agent),
+            resolveWorktree: (agentId) => this.bindingWorktreeCache.get(agentId),
+        });
+        return this.reviewTransportInstance;
+    }
+    // ReviewTransport resolves worktrees synchronously; agentStore reads are async.
+    // The cache is refreshed by callers (server handlers) before transport use via
+    // refreshWorktreeCacheFor — a stale entry only costs one refresh round-trip.
+    bindingWorktreeCache = new Map();
+    async refreshWorktreeCacheFor(agentId) {
+        const state = await this.agentStore.get(agentId);
+        if (state?.worktreePath) {
+            this.bindingWorktreeCache.set(agentId, state.worktreePath);
+            return state.worktreePath;
+        }
+        this.bindingWorktreeCache.delete(agentId);
+        return undefined;
+    }
     async safeEmit(event) {
         try {
             await this.eventBus.emit(event);
@@ -940,7 +976,10 @@ export class AgentManager {
             throw new Error(`Unknown agent: ${agentId}`);
         const state = await this.agentStore.get(agentId);
         const sameTaskLocked = state?.taskId === taskId && (await this.lockManager.isLocked(agentId));
-        const reentryPhases = new Set(['fix', 'post-approve', 'spec-fix', 'code']);
+        const reentryPhases = new Set([
+            'fix', 'post-approve', 'code',
+            'server-feedback', 'server-after-done',
+        ]);
         const sameTaskReentry = state?.taskId === taskId &&
             !state.creationToken &&
             state.status !== 'awaiting_human' &&
@@ -1178,6 +1217,28 @@ export class AgentManager {
                 console.warn(`[AgentManager] resumeAgent: agent ${agentId} dialog resolved but bound task ${state.taskId} still active (crash window) — prompt was never injected; refusing Resume. Operator should cancel the task or DELETE the agent.`);
                 return { resumed: false, releasedBinding: false };
             }
+            // code-dispatch-failed: the code-phase prompt never reached the pane (spec
+            // approval already transitioned the task). Resume = clear the hold AND
+            // redispatch the code prompt (outside this lock) — without the redispatch
+            // the task would stay in_progress with nothing running (PR #288).
+            if (state.awaitingPhase === 'code-dispatch-failed'
+                && boundTask && ACTIVE_TASK_STATUSES.has(boundTask.status)
+                && state.taskId) {
+                const now2 = new Date().toISOString();
+                await this.agentStore.update(agentId, (existing) => {
+                    if (!existing)
+                        return AGENT_STORE_NOOP;
+                    return {
+                        ...existing,
+                        status: 'ok',
+                        awaitingPhase: undefined,
+                        awaitingReason: undefined,
+                        awaitingSince: undefined,
+                        updatedAt: now2,
+                    };
+                });
+                return { resumed: true, releasedBinding: false, redispatchCodeTaskId: state.taskId };
+            }
             // signal-arm-failed: the prompt was already dispatched but its pane-signal watcher never
             // armed. Resume here would only flip status→ok WITHOUT rebuilding the watcher (Resume has no
             // re-arm path), so the prompt's signal would still have no consumer — silent deadlock again.
@@ -1243,7 +1304,20 @@ export class AgentManager {
             });
             return { resumed: true, releasedBinding: shouldReleaseBinding };
         });
-        return result;
+        // Outside the task lock: continueSession takes it internally.
+        if (result.redispatchCodeTaskId) {
+            try {
+                const resumed = await this.continueSession(result.redispatchCodeTaskId, agentId, 'code');
+                if (!resumed) {
+                    await this.markAwaitingHuman(agentId, 'code-dispatch-failed', 'Code-phase redispatch on Resume was not delivered; Resume again to retry or cancel the task.', { expectedTaskId: result.redispatchCodeTaskId }).catch(() => undefined);
+                }
+            }
+            catch (err) {
+                console.error(`[AgentManager] resumeAgent code redispatch failed for ${agentId}:`, err);
+                await this.markAwaitingHuman(agentId, 'code-dispatch-failed', 'Code-phase redispatch on Resume failed; Resume again to retry or cancel the task.', { expectedTaskId: result.redispatchCodeTaskId }).catch(() => undefined);
+            }
+        }
+        return { resumed: result.resumed, releasedBinding: result.releasedBinding };
     }
     async interruptPaneAndWaitReady(state, cfg) {
         const runner = this.createRunnerFor(cfg);
@@ -1337,6 +1411,11 @@ export class AgentManager {
             const out = [];
             for (const t of tasks) {
                 const bound = t.agentId === agentId || t.qaAgentId === agentId;
+                // Human gates are decision states, not running work: an absent agent
+                // session must not terminally fail a task whose published PR/branch
+                // would then be orphaned — Confirm/Cancel remain the only exits (PR #288).
+                if (t.status === 'ready' || t.status === 'merge-ready')
+                    continue;
                 if (ACTIVE_TASK_STATUSES.has(t.status) && bound) {
                     t.status = 'failed';
                     t.updatedAt = new Date().toISOString();
@@ -1667,6 +1746,7 @@ export class AgentManager {
                     expectedKinds: 'pr-merge-ready',
                     token: completion.token,
                     skipSnapshot,
+                    recovered: true,
                 });
             }
             catch (err) {
@@ -1674,8 +1754,8 @@ export class AgentManager {
             }
         }
     }
-    // skipSnapshot=true: 旧 scrollback 里的 signal 重启后不应再触发。
-    // 只对 spec verdict / spec-fixed emit intervention — spec-created 在 develop
+    // snapshot 扫描按协议族决定：server 协议（含全模式 spec 阶段）恢复时必扫，github code 阶段仅 review/fixing 扫。
+    // 只对 spec verdict / spec-fixed emit intervention — spec-done 在 develop
     // prompt 里是 optional, 报警会让所有 in_progress task 噪音化。
     // expectedKinds 必须覆盖 dispatch 时实际 set up 的 kind 集，否则真信号无法匹配。
     async setupRecoveredSpecSignals() {
@@ -1690,20 +1770,26 @@ export class AgentManager {
                 continue;
             const { expectedKinds, agentId } = mapped;
             // Only spec verdict / spec-fixed / PR verdict warrant an intervention —
-            // optional kinds (spec-created, pr-created in develop) would spam every
+            // optional kinds (spec-done, pr-created in develop) would spam every
             // in_progress task on restart.
-            const interventionKindLabel = task.phase === 'spec' && task.status === 'review' ? 'spec-approved|spec-changes-requested'
+            const interventionKindLabel = task.phase === 'spec' && task.status === 'review' ? 'spec-reviewed'
                 : task.phase === 'spec' && task.status === 'fixing' ? 'spec-fixed'
                     : task.phase !== 'spec' && task.status === 'review' ? 'pr-approved|pr-changes-requested'
                         : task.phase !== 'spec' && task.status === 'fixing' ? 'pr-fixed'
                             : undefined;
-            // Scan the pane snapshot for one-shot completion signals the agent may have
-            // echoed before the server persisted/consumed it (lost on restart otherwise,
-            // since the agent does not re-emit): PR verdict (review) and pr-fixed (code
-            // fixing). Both handlers are idempotent under replay (token + status gates),
-            // and token rotation still rejects stale ones. Other phases keep
-            // skipSnapshot=true — their handlers aren't as cleanly replay-safe.
-            const scanSnapshotOnRecover = task.phase !== 'spec' && (task.status === 'review' || task.status === 'fixing');
+            // spec 阶段恒为 server 协议（无 poller 兜底）；code 阶段才按 reviewMode 区分。
+            // Scan pane snapshot on recover for signals the agent emitted before the
+            // server consumed them (lost on restart; agent won't re-emit).
+            // github code states (review/fixing): replay-safe handlers — token + status
+            // gates reject duplicates; PR verdict & pr-fixed covered.
+            // github pre-spec (phase undefined, in_progress): spec-done has only the pane
+            // channel (pr-created has a poller backstop, scanning it is idempotent).
+            // server protocol incl. all-mode spec phase: no poller backstop, pane is the
+            // only signal channel; handlers equally replay-safe via same gates.
+            const isServerProtocol = task.reviewMode === 'server' || task.phase === 'spec';
+            const scanSnapshotOnRecover = isServerProtocol
+                || (task.phase === undefined && task.status === 'in_progress')
+                || (task.phase !== 'spec' && (task.status === 'review' || task.status === 'fixing'));
             try {
                 await this.phaseSignalWatcher.start({
                     taskId: task.id,
@@ -1712,6 +1798,10 @@ export class AgentManager {
                     expectedKinds,
                     token: task.signalToken,
                     skipSnapshot: !scanSnapshotOnRecover,
+                    recovered: true,
+                    ...(isServerProtocol && task.status === 'review'
+                        ? { onReadFile: (req) => { void this.handleReadFileRequest(task.id, agentId, req); } }
+                        : {}),
                 });
                 if (interventionKindLabel) {
                     await this.safeEmit({
@@ -1987,6 +2077,7 @@ export class AgentManager {
                     reviewRound: 0,
                     status: 'pending',
                     branch: BRANCH_PREFIX + taskId,
+                    reviewMode: this.config.review.mode ?? 'github',
                     createdAt: now,
                     updatedAt: now,
                     ...(imageFilenames ? { images: imageFilenames } : {}),
@@ -2015,6 +2106,7 @@ export class AgentManager {
                     reviewRound: 0,
                     status: 'pending',
                     branch: BRANCH_PREFIX + taskId,
+                    reviewMode: this.config.review.mode ?? 'github',
                     createdAt: now,
                     updatedAt: now,
                     ...(qa ? { qaAgentId: qa.id } : {}),
@@ -2047,6 +2139,7 @@ export class AgentManager {
                     reviewRound: 0,
                     status: 'pending',
                     branch: BRANCH_PREFIX + taskId,
+                    reviewMode: this.config.review.mode ?? 'github',
                     createdAt: now,
                     updatedAt: now,
                     ...(qa ? { qaAgentId: qa.id } : {}),
@@ -2078,6 +2171,7 @@ export class AgentManager {
                 reviewRound: 0,
                 status: 'in_progress',
                 branch: BRANCH_PREFIX + taskId,
+                reviewMode: this.config.review.mode ?? 'github',
                 createdAt: now,
                 updatedAt: now,
                 ...(imageFilenames ? { images: imageFilenames } : {}),
@@ -2161,13 +2255,16 @@ export class AgentManager {
                 return null;
             }
             // 后台路径吞掉 reject（void start.catch）：arm 抛异常时也要显式 hold agent，否则会留下一个没有
-            // spec-created/pr-created 消费者的常驻任务（同步 caller 仍由上游收到异常）。
+            // spec-done/pr-created 消费者的常驻任务（同步 caller 仍由上游收到异常）。
+            // Kinds derive from the task's frozen reviewMode — a hot mode flip during the
+            // startSession window must not desync the armed kinds from the sent prompt.
+            const initialKinds = this.devInitialSignalKinds(fresh.reviewMode);
             try {
-                await this.armPostDispatchSignalOrHold(taskId, agentId, ['spec-created', 'pr-created'], signalToken);
+                await this.armPostDispatchSignalOrHold(taskId, agentId, initialKinds, signalToken);
             }
             catch (armErr) {
                 console.error(`[AgentManager] createAndStartTask arm failed for task=${taskId}:`, armErr);
-                await this.holdAgentForUnarmedSignal(taskId, agentId, ['spec-created', 'pr-created'])
+                await this.holdAgentForUnarmedSignal(taskId, agentId, initialKinds)
                     .catch((holdErr) => {
                     console.error(`[AgentManager] createAndStartTask hold-after-arm-failure failed for task=${taskId}:`, holdErr);
                 });
@@ -2206,12 +2303,83 @@ export class AgentManager {
         const paneId = state?.paneId;
         if (!paneId)
             throw new ApiError(409, `Agent ${agentId} has no live session`);
-        const runner = this.createRunnerFor(cfg);
-        const path = agentHostPath(agentId, imageFilename(ext));
-        await writeImageToHost(runner, path, bytes);
-        const tmux = new TmuxManager(runner);
-        await tmux.injectPrompt(paneId, `${path} `, agentId);
-        return { path };
+        // 写文件→粘贴全程持有 pane 互斥：写文件可能卡住，恢复后的粘贴若落进
+        // compact 的 C-c→/compact 窗口会把路径拼进指令提交。
+        if (!this.tryAcquireCompactGuard(agentId)) {
+            throw new ApiError(409, `Agent ${agentId} compact or upload in progress; retry shortly`);
+        }
+        try {
+            const runner = this.createRunnerFor(cfg);
+            const path = agentHostPath(agentId, imageFilename(ext));
+            await writeImageToHost(runner, path, bytes);
+            const tmux = new TmuxManager(runner);
+            await tmux.injectPrompt(paneId, `${path} `, agentId);
+            return { path };
+        }
+        finally {
+            this.compactInFlight.delete(agentId);
+        }
+    }
+    // busy 时注入会把指令拼进正在运行的回合，宁可 409。
+    async compactAgent(agentId) {
+        const cfg = this.getAgentConfig(agentId);
+        if (!cfg)
+            throw new ApiError(404, `Unknown agent: ${agentId}`);
+        if (!this.tryAcquireCompactGuard(agentId)) {
+            throw new ApiError(409, `Agent ${agentId} compact or upload already in progress`);
+        }
+        let guardHandedOff = false;
+        try {
+            const state = await this.agentStore.get(agentId);
+            const paneId = state?.paneId;
+            if (!paneId)
+                throw new ApiError(409, `Agent ${agentId} has no live session`);
+            const taskIdAtStart = state.taskId;
+            const updatedAtAtStart = state.updatedAt;
+            // updatedAt 拦同任务 phase 派发（paneId/taskId 均不变，派发 paste 前必写 state）；
+            // 快照变了决不注入——C-c 会打断刚注入的 prompt。
+            const assertSessionUnchanged = async () => {
+                const now = await this.agentStore.get(agentId);
+                if (!now
+                    || now.paneId !== paneId
+                    || now.taskId !== taskIdAtStart
+                    || now.updatedAt !== updatedAtAtStart) {
+                    throw new ApiError(409, `Agent ${agentId} session changed while waiting; compact aborted`);
+                }
+            };
+            const tmux = new TmuxManager(this.createRunnerFor(cfg));
+            const waitReady = async () => {
+                try {
+                    await this.waitForReplPromptReady(tmux, paneId, cfg.runtime, this.manualCompactWaitMs);
+                }
+                catch (err) {
+                    const detail = err instanceof Error ? err.message : String(err);
+                    throw new ApiError(409, `Agent ${agentId} runtime is not at an idle REPL prompt: ${detail}`);
+                }
+            };
+            await waitReady();
+            await assertSessionUnchanged();
+            // 残留草稿会被「草稿/compact」连带提交；C-c 清线后再发。
+            await tmux.sendKeysToPane(paneId, 'C-c');
+            await waitReady();
+            await assertSessionUnchanged();
+            await tmux.sendKeysLiteral(paneId, '/compact');
+            await tmux.sendEnter(paneId);
+            // 压缩仍在运行：guard 交给后台尾随等待，runtime 回到 idle 才释放，
+            // 否则紧随的上传/派发会粘进压缩中的 pane。
+            guardHandedOff = true;
+            void this.waitForReplPromptReady(tmux, paneId, cfg.runtime, this.compactIdleWaitMs)
+                .catch(err => {
+                console.warn(`[AgentManager] compactAgent(${agentId}) post-/compact idle wait failed:`, err);
+            })
+                .finally(() => {
+                this.compactInFlight.delete(agentId);
+            });
+        }
+        finally {
+            if (!guardHandedOff)
+                this.compactInFlight.delete(agentId);
+        }
     }
     async persistTaskImages(taskId, images) {
         const dir = join(this.imageStagingRoot, taskId);
@@ -2263,12 +2431,10 @@ export class AgentManager {
         }
         return hostPaths;
     }
-    // Dev-facing deliverable phases (initial + rework) all carry the task's uploaded images, since
-    // the image is a persistent task input the dev needs while producing or revising the spec/code —
-    // and a fresh runtime (restart/recovery) loses the original context. `develop` flows through
-    // startSession; `code`/`fix`/`spec-fix` through continueSession — both call this. Excluded:
-    // QA phases (review/recheck/spec-review) and post-approve (feedback-processing; if it needs
-    // changes baxian routes to `fix`, which carries the image) (task-055).
+    // Dev-facing deliverable phases all carry the task's uploaded images, since the image is a
+    // persistent task input the dev needs while producing or revising the spec/code — and a fresh
+    // runtime (restart/recovery) loses the original context. IMAGE_DISPATCH_PHASES 中的后续阶段经
+    // continueSession 触发此方法；QA 阶段和 post-approve 不传图（task-055）。
     async imagePathsForDispatch(runner, task, phase) {
         if (!IMAGE_DISPATCH_PHASES.has(phase))
             return [];
@@ -2365,7 +2531,7 @@ export class AgentManager {
             console.error(`[AgentManager] dispatchPendingTask startSession hard error for task=${claimed.id}:`, err);
         }
         if (started) {
-            await this.armPostDispatchSignalOrHold(claimed.id, claimed.agentId, ['spec-created', 'pr-created'], signalToken);
+            await this.armPostDispatchSignalOrHold(claimed.id, claimed.agentId, this.devInitialSignalKinds(claimed.reviewMode), signalToken);
             const refreshed = await this.taskStore.get(claimed.id);
             return { task: refreshed ?? claimed };
         }
@@ -2454,9 +2620,12 @@ export class AgentManager {
         const baseRef = agent.workdir
             ? undefined
             : await this.resolveAutoBaseRef(runner, workdir);
-        const worktreePath = phase === 'review' || phase === 'recheck' || phase === 'spec-review'
-            ? await worktree.createDetached(workdir, taskId, task.branch)
-            : await worktree.create(workdir, taskId, baseRef);
+        const isServerQaPhase = phase === 'server-review' || phase === 'server-recheck' || phase === 'server-spec-review';
+        const worktreePath = isServerQaPhase
+            ? await worktree.createDetachedAtBase(workdir, taskId)
+            : phase === 'review' || phase === 'recheck'
+                ? await worktree.createDetached(workdir, taskId, task.branch)
+                : await worktree.create(workdir, taskId, baseRef);
         // Persist worktreePath now so a crash before set-running leaves a recoverable trail.
         await this.agentStore.update(agentId, (stateNow) => {
             if (!stateNow || stateNow.taskId !== taskId)
@@ -2480,6 +2649,8 @@ export class AgentManager {
         const reuseInjectedSkills = ensure.freshRuntime
             ? null
             : reuseSkillsIfContextValid(beforeInjectAgent, taskId, paneId);
+        // develop prompt 按 QA 有无裁剪 spec 路线（qaAgentId 快照优先，与 review 派发同一解析）。
+        const hasQaPartner = !!(task.qaAgentId ?? this.findQaPartner(agentId)?.id);
         let prompt;
         try {
             const imagePaths = await this.imagePathsForDispatch(runner, task, phase);
@@ -2489,11 +2660,17 @@ export class AgentManager {
                 agent,
                 worktreePath,
                 skillRegistry: this.skillRegistry,
+                hasQaPartner,
                 ...(promptSignalToken ? { signalToken: promptSignalToken } : {}),
                 ...(promptSpecRound !== undefined ? { currentSpecRound: promptSpecRound } : {}),
-                ...(opts.specFindings ? { specFindings: opts.specFindings } : {}),
                 ...(reuseInjectedSkills ? { excludeSkills: reuseInjectedSkills } : {}),
                 ...(imagePaths.length ? { imagePaths } : {}),
+                ...(opts.serverContent !== undefined ? { serverContent: opts.serverContent } : {}),
+                ...(opts.serverDiffstat !== undefined ? { serverDiffstat: opts.serverDiffstat } : {}),
+                ...(opts.serverBatch ? { serverBatch: opts.serverBatch } : {}),
+                ...(opts.serverPriorFindings ? { serverPriorFindings: opts.serverPriorFindings } : {}),
+                ...(opts.serverPriorResponse ? { serverPriorResponse: opts.serverPriorResponse } : {}),
+                ...(opts.contentTruncated ? { contentTruncated: true } : {}),
             });
         }
         catch (err) {
@@ -2658,7 +2835,27 @@ export class AgentManager {
             throw err;
         }
     }
-    async injectAndAwaitAck(tmux, paneId, prompt, agentId, _runtime) {
+    // 注入方必须持有 pane 互斥：compact 侧的快照校验关不死「校验→按键」
+    // 之间的 async 边界，竞态只能在这里关死。
+    async injectAndAwaitAck(tmux, paneId, prompt, agentId, runtime) {
+        const before = await this.agentStore.get(agentId);
+        await this.acquireCompactGuard(agentId);
+        try {
+            // guard 等待期间任务可能被 Cancel（释放绑定）或会话重建；过期派发
+            // 决不落 pane。无快照（direct 调用）时跳过——真实派发必有绑定。
+            if (before) {
+                const now = await this.agentStore.get(agentId);
+                if (!now || now.paneId !== before.paneId || now.taskId !== before.taskId) {
+                    throw new Error(`dispatch aborted: agent ${agentId} binding changed while waiting for pane mutex`);
+                }
+            }
+            return await this.injectAndAwaitAckSteps(tmux, paneId, prompt, agentId, runtime);
+        }
+        finally {
+            this.compactInFlight.delete(agentId);
+        }
+    }
+    async injectAndAwaitAckSteps(tmux, paneId, prompt, agentId, _runtime) {
         await tmux.injectPrompt(paneId, prompt, agentId);
         let baseline;
         try {
@@ -2844,9 +3041,15 @@ export class AgentManager {
                     ? { postApproveRedispatchCount: opts.postApproveRedispatchCount }
                     : {}),
                 ...(promptSpecRound !== undefined ? { currentSpecRound: promptSpecRound } : {}),
-                ...(opts.specFindings ? { specFindings: opts.specFindings } : {}),
                 ...(reuseInjectedSkills ? { excludeSkills: reuseInjectedSkills } : {}),
                 ...(imagePaths.length ? { imagePaths } : {}),
+                ...(opts.serverContent !== undefined ? { serverContent: opts.serverContent } : {}),
+                ...(opts.serverDiffstat !== undefined ? { serverDiffstat: opts.serverDiffstat } : {}),
+                ...(opts.serverBatch ? { serverBatch: opts.serverBatch } : {}),
+                ...(opts.serverPriorFindings ? { serverPriorFindings: opts.serverPriorFindings } : {}),
+                ...(opts.serverPriorResponse ? { serverPriorResponse: opts.serverPriorResponse } : {}),
+                ...(opts.serverAfterDone ? { serverAfterDone: opts.serverAfterDone } : {}),
+                ...(opts.contentTruncated ? { contentTruncated: opts.contentTruncated } : {}),
             });
         }
         catch (err) {
@@ -3235,6 +3438,13 @@ export class AgentManager {
     async cancelTask(taskId) {
         let devToRelease;
         let qaToRelease;
+        // Server-mode ready gate may have already published remote artifacts
+        // (pushed branch / open PR). Capture before flipping to cancelled so the
+        // post-lock cleanup can retire them instead of orphaning (PR #288).
+        // mayBeInFlight: approved+marker means the publish prompt may STILL be
+        // running — retirement must wait for the dev interrupt or the in-flight
+        // push/pr-create would recreate the artifacts right after cleanup.
+        let publishedCleanup;
         this.phaseSignalWatcher?.stop(taskId);
         const result = await this.withTaskLock(async () => {
             const task = await this.taskStore.get(taskId);
@@ -3252,6 +3462,37 @@ export class AgentManager {
                 devToRelease = task.agentId;
             if (task.qaAgentId)
                 qaToRelease = task.qaAgentId;
+            // approved + publishDispatchedAt = the publish prompt reached the pane, so
+            // remote artifacts may already exist even though code-ready never landed
+            // (dispatch crash, or the reviewed-head mismatch gate refused ready —
+            // whose documented exit is exactly this Cancel).
+            // Truthy (not !== undefined): sanitizeTask passes hand-edited nulls through.
+            const publishedAtGate = task.status === 'ready'
+                || (task.status === 'approved' && !!task.publishDispatchedAt);
+            if (task.reviewMode === 'server' && publishedAtGate && task.agentId) {
+                const afterDone = this.resolveAfterDone(task);
+                if (afterDone !== null && task.branch) {
+                    publishedCleanup = {
+                        afterDone,
+                        branch: task.branch,
+                        ...(task.prNumber !== undefined ? { prNumber: task.prNumber } : {}),
+                        devAgentId: task.agentId,
+                        // ready = code-ready consumed, publish finished; approved = no
+                        // completion signal yet, the publish may still be running.
+                        mayBeInFlight: task.status === 'approved',
+                    };
+                }
+            }
+            else if (task.status === 'merge-ready' && task.prNumber !== undefined && task.branch && task.agentId) {
+                // GitHub-mode gate cancel leaves the same orphaned PR/branch (PR #288).
+                publishedCleanup = {
+                    afterDone: 'pr',
+                    branch: task.branch,
+                    prNumber: task.prNumber,
+                    devAgentId: task.agentId,
+                    mayBeInFlight: false,
+                };
+            }
             const now = new Date().toISOString();
             task.status = 'cancelled';
             task.updatedAt = now;
@@ -3266,7 +3507,13 @@ export class AgentManager {
             });
             return task;
         });
-        // 唯一允许打断 agent 会话的入口（用户主动 Cancel）。
+        // 唯一允许打断 agent 会话的入口（用户主动 Cancel）。Interrupt BEFORE remote
+        // retirement: an in-flight publish prompt would re-push the branch / re-open
+        // the PR right after cleanup, and a cancelled task gets no second pass.
+        // Only a successful interrupt PROVES the pane stopped — skipped paths
+        // (config hot-removed: the pane outlives the config; state gone; rebound)
+        // leave an in-flight publish possible.
+        let devStopConfirmed = false;
         for (const id of [devToRelease, qaToRelease]) {
             if (!id)
                 continue;
@@ -3285,6 +3532,8 @@ export class AgentManager {
                 await this.markAwaitingHuman(id, 'cancel-interrupt-failed', 'Task marked cancelled but C-c / REPL ready check failed; agent may still be running. Attach via web terminal to verify, then Resume or Delete.');
                 continue;
             }
+            if (id === publishedCleanup?.devAgentId)
+                devStopConfirmed = true;
             try {
                 // allowAwaitingHuman: cancelTask 是显式回收入口，agent 之前可能因 ack_unknown 等被标 Held，
                 // 用户主动 Cancel 应允许跨过 awaiting_human gate 清理 binding；release 默认 gate 是为了
@@ -3295,6 +3544,65 @@ export class AgentManager {
                 console.error(`[AgentManager] cancelTask releaseAgentForTask(${id}) failed:`, err);
             }
         }
+        // Best-effort remote retirement for a cancelled published gate: close the PR
+        // and delete the pushed branch so they don't outlive the task. Failures only
+        // warn + intervene — cancel must not be blocked by remote faults.
+        if (publishedCleanup) {
+            if (publishedCleanup.mayBeInFlight && !devStopConfirmed) {
+                // No proof the publish prompt stopped; cleaning now would race its
+                // push/pr-create. Leave the artifacts to the operator.
+                await this.safeEmit({
+                    id: '',
+                    type: 'human.intervention',
+                    timestamp: new Date().toISOString(),
+                    projectId: result.projectId,
+                    taskId,
+                    data: {
+                        phase: 'cancel-published-artifact-cleanup-skipped',
+                        afterDone: publishedCleanup.afterDone,
+                        branch: publishedCleanup.branch,
+                        ...(publishedCleanup.prNumber !== undefined ? { prNumber: publishedCleanup.prNumber } : {}),
+                        reason: 'dev pane stop unconfirmed; the publish prompt may still be running and would recreate the remote artifacts',
+                    },
+                });
+                return result;
+            }
+            const project = this.getProjectConfig(result.projectId);
+            try {
+                if (publishedCleanup.afterDone === 'pr' && publishedCleanup.prNumber !== undefined && project) {
+                    const close = await this.platformRunner.exec(`gh pr close ${publishedCleanup.prNumber} --repo ${shellQuote(project.repo)} ` +
+                        `--comment ${shellQuote('Task cancelled in baxian; closing the published PR.')} --delete-branch`);
+                    if (close.exitCode !== 0)
+                        throw new Error(close.stderr.trim() || close.stdout.trim());
+                }
+                else {
+                    const dev = this.getAgentConfig(publishedCleanup.devAgentId);
+                    const state = await this.agentStore.get(publishedCleanup.devAgentId);
+                    if (dev && state?.repoPath) {
+                        const del = await this.createRunnerFor(dev).exec(`cd ${shellQuote(state.repoPath)} && git push origin --delete ${shellQuote(publishedCleanup.branch)}`);
+                        if (del.exitCode !== 0)
+                            throw new Error(del.stderr.trim() || del.stdout.trim());
+                    }
+                }
+            }
+            catch (err) {
+                console.warn(`[AgentManager] cancelTask remote retirement failed for ${taskId}:`, err);
+                await this.safeEmit({
+                    id: '',
+                    type: 'human.intervention',
+                    timestamp: new Date().toISOString(),
+                    projectId: result.projectId,
+                    taskId,
+                    data: {
+                        phase: 'cancel-published-artifact-cleanup-failed',
+                        afterDone: publishedCleanup.afterDone,
+                        branch: publishedCleanup.branch,
+                        ...(publishedCleanup.prNumber !== undefined ? { prNumber: publishedCleanup.prNumber } : {}),
+                        error: err instanceof Error ? err.message : String(err),
+                    },
+                });
+            }
+        }
         return result;
     }
     // task-044 重构：create-time 不再校验 awaiting_human / creating / bound —— 这些都是"忙"，
@@ -3342,6 +3650,11 @@ export class AgentManager {
             const task = await this.taskStore.get(taskId);
             if (!task)
                 throw new ApiError(404, `Task ${taskId} not found`);
+            // Server-mode tasks review via the exchange protocol; routing one into the
+            // legacy GitHub review flow would cross-contaminate the state machines.
+            if (task.reviewMode === 'server') {
+                throw new ApiError(409, `Task ${taskId} uses server review mode; legacy Call review is not applicable`);
+            }
             // spec-phase max_rounds escapes via Retry/Cancel only. Call review dispatches the
             // CODE-review protocol, but review.submitted early-returns for spec phase — so a direct
             // /tasks/:id/review here would transition the task to review + bind QA, yet its verdict
@@ -3554,6 +3867,55 @@ export class AgentManager {
         if (task.phase === 'spec') {
             throw new ApiError(409, `Continue one round is only supported for code-phase tasks`);
         }
+        // Server-mode continue: grant one round past the cap, then re-run the server
+        // fix protocol from the stored findings — no PR exists at this point (PR #288).
+        if (task.reviewMode === 'server') {
+            if (!task.agentId) {
+                throw new ApiError(400, `Task ${taskId} has no dev agent; cannot continue`);
+            }
+            const stored = await this.reviewStore?.getRound(taskId, 'code', Math.max(task.reviewRound, 1));
+            if (!stored?.findings) {
+                throw new ApiError(409, `Task ${taskId} has no stored findings to continue from; cancel instead`);
+            }
+            // Re-check + grant under the task lock: the entry checks above ran lock-free,
+            // so a concurrent mark-complete may have claimed the gate since (the
+            // claimCompleteGate comment promises Continue re-checks under the same lock).
+            await this.withTaskLock(async () => {
+                if (this.markCompleteInFlight.has(taskId)) {
+                    throw new ApiError(409, `Task ${taskId} is being completed (merge in progress); try again shortly`);
+                }
+                const fresh = await this.taskStore.get(taskId);
+                if (!fresh || fresh.status !== 'max_rounds') {
+                    throw new ApiError(409, `Task ${taskId} is not at max_rounds (status=${fresh?.status ?? 'gone'})`);
+                }
+                fresh.maxRoundsContinues = (fresh.maxRoundsContinues ?? 0) + 1;
+                fresh.updatedAt = new Date().toISOString();
+                await this.taskStore.set(fresh);
+            });
+            let dispatched = null;
+            try {
+                dispatched = await this.dispatchServerFixToDev(taskId, JSON.stringify(stored.findings));
+            }
+            finally {
+                // The grant is only spent when the fix prompt actually reached the dev.
+                // Decrement (not restore-snapshot): a snapshot write-back would also
+                // erase a concurrent Continue's grant.
+                if (!dispatched) {
+                    await this.withTaskLock(async () => {
+                        const fresh = await this.taskStore.get(taskId);
+                        if (!fresh)
+                            return;
+                        fresh.maxRoundsContinues = Math.max(0, (fresh.maxRoundsContinues ?? 0) - 1);
+                        fresh.updatedAt = new Date().toISOString();
+                        await this.taskStore.set(fresh);
+                    }).catch(() => undefined);
+                }
+            }
+            if (!dispatched) {
+                throw new ApiError(500, `Failed to dispatch server fix round for task ${taskId}`);
+            }
+            return dispatched;
+        }
         if (!task.prNumber || !task.branch) {
             throw new ApiError(400, `Task ${taskId} has no PR/branch; cannot continue`);
         }
@@ -3667,7 +4029,7 @@ export class AgentManager {
         }
         // General case: rolled-back task may still want a watcher matching its
         // current (restored) state — develop dispatch still waiting on
-        // spec-created/pr-created, recheck still waiting on verdict, etc.
+        // spec-done/pr-created, recheck still waiting on verdict, etc.
         const restored = await this.taskStore.get(taskId);
         if (!restored || !restored.signalToken)
             return;
@@ -3690,9 +4052,19 @@ export class AgentManager {
     // Single source of truth for "what watcher should this task have, given its
     // current state". Used by both setupRecoveredSpecSignals (restart recovery)
     // and rollbackDispatchReviewPhase1 (manual dispatch failure).
+    // Dev's first prompt offers the spec-first or straight-to-code path; the arm
+    // must accept both completion signals for the task's protocol family.
+    devInitialSignalKinds(reviewMode) {
+        const mode = reviewMode ?? this.config.review.mode ?? 'github';
+        return mode === 'server'
+            ? ['spec-done', 'code-done']
+            : ['spec-done', 'pr-created'];
+    }
     mapTaskStateToExpectedWatcher(task) {
+        if (task.reviewMode === 'server')
+            return this.mapServerTaskToExpectedWatcher(task);
         if (task.phase === 'spec' && task.status === 'review' && task.qaAgentId) {
-            return { expectedKinds: ['spec-approved', 'spec-changes-requested'], agentId: task.qaAgentId };
+            return { expectedKinds: ['spec-reviewed'], agentId: task.qaAgentId };
         }
         if (task.phase === 'spec' && task.status === 'fixing' && task.agentId) {
             return { expectedKinds: ['spec-fixed'], agentId: task.agentId };
@@ -3702,7 +4074,7 @@ export class AgentManager {
             return { expectedKinds: ['pr-fixed'], agentId: task.agentId };
         }
         if (task.phase === undefined && task.status === 'in_progress' && task.agentId) {
-            return { expectedKinds: ['spec-created', 'pr-created'], agentId: task.agentId };
+            return { expectedKinds: ['spec-done', 'pr-created'], agentId: task.agentId };
         }
         if (task.phase === 'code' && task.status === 'in_progress' && task.agentId) {
             return { expectedKinds: ['pr-created'], agentId: task.agentId };
@@ -3714,14 +4086,35 @@ export class AgentManager {
         }
         return undefined;
     }
+    // Recovery mapping for server-mode tasks: the watcher is the ONLY verdict
+    // channel (no poller backstop), so every awaiting state must re-arm on restart.
+    mapServerTaskToExpectedWatcher(task) {
+        const isSpec = task.phase === 'spec';
+        if (task.status === 'review' && task.qaAgentId) {
+            return { expectedKinds: [isSpec ? 'spec-reviewed' : 'code-reviewed'], agentId: task.qaAgentId };
+        }
+        if (task.status === 'fixing' && task.agentId) {
+            return { expectedKinds: [isSpec ? 'spec-fixed' : 'code-fixed'], agentId: task.agentId };
+        }
+        if (task.status === 'in_progress' && task.agentId) {
+            if (task.phase === 'code')
+                return { expectedKinds: ['code-done'], agentId: task.agentId };
+            return { expectedKinds: ['spec-done', 'code-done'], agentId: task.agentId };
+        }
+        if (task.status === 'approved' && task.agentId) {
+            return { expectedKinds: ['code-ready'], agentId: task.agentId };
+        }
+        return undefined;
+    }
     // Public re-establish helper for in-band recoveries that don't rotate the token
     // (e.g. handler reject path: agent's next emit must still match current
-    // task.signalToken, so rotating would strand it).
+    // task.signalToken, so rotating would strand it). Returns whether a watcher
+    // armed; callers that consumed a signal must hold on false or it has no consumer.
     async setupPhaseSignal(taskId, agentId, expectedKinds, opts = {}) {
         const task = await this.taskStore.get(taskId);
         if (!task?.signalToken)
-            return;
-        await this.setupPhaseSignalWatcher(taskId, agentId, expectedKinds, task.signalToken, opts.skipSnapshot);
+            return false;
+        return this.setupPhaseSignalWatcher(taskId, agentId, expectedKinds, task.signalToken, opts.skipSnapshot);
     }
     async emitManualReviewDevParkedQaFailedIntervention(agentId, expectedTaskId) {
         if (!agentId)
@@ -3838,28 +4231,83 @@ export class AgentManager {
     // cleanup chain (pr.merged handler → transition merged + post-merge worktree/branch
     // cleanup + /compact + release). Same path the poller drives when it detects the merge.
     async markTaskComplete(taskId) {
-        const task = await this.taskStore.get(taskId);
-        if (!task)
+        const peek = await this.taskStore.get(taskId);
+        if (!peek)
             throw new ApiError(404, `Task ${taskId} not found`);
-        if (task.status !== 'max_rounds') {
-            throw new ApiError(409, `Task ${taskId} is not at max_rounds (status=${task.status})`);
-        }
-        // spec-phase max_rounds escapes via Retry/Cancel only (the UI hides complete). Guard the
-        // endpoint too so a direct API call / older client can't merge a spec cap through here.
-        if (task.phase === 'spec') {
-            throw new ApiError(409, `Mark complete is only supported for code-phase tasks`);
-        }
-        if (!task.prNumber || !task.branch) {
-            throw new ApiError(400, `Task ${taskId} has no PR/branch; cannot mark complete`);
-        }
-        // Claim the task for the whole merge window. markCompleteInFlight blocks Cancel /
-        // Call review / Continue (all re-check it under the task lock) so they can't act on
-        // the same max_rounds snapshot and interleave with the irreversible `gh pr merge`.
-        if (this.markCompleteInFlight.has(taskId)) {
-            throw new ApiError(409, `Task ${taskId} is already being completed`);
-        }
-        this.markCompleteInFlight.add(taskId);
+        // Human gate (spec §10): ready / merge-ready confirm runs its own completion
+        // matrix (with its own lock-claimed gate); the legacy max_rounds path below
+        // is untouched.
+        if (peek.status === 'ready' || peek.status === 'merge-ready') {
+            return this.confirmHumanGate(taskId);
+        }
+        // Claim under the task lock — the whole merge window. markCompleteInFlight
+        // blocks Cancel / Call review / Continue (all re-check it under the same
+        // lock) so they can't act on the same snapshot and interleave with the
+        // irreversible `gh pr merge` (or, server mode, the publish dispatch).
+        const task = await this.claimCompleteGate(taskId, ['max_rounds', 'approved']);
         try {
+            // Server-mode publish retry: a failed afterDone dispatch leaves the task
+            // 'approved' with dev released — mark-complete re-runs the publish (PR #288).
+            const serverApprovedRetry = task.status === 'approved' && task.reviewMode === 'server';
+            if (!serverApprovedRetry && task.status !== 'max_rounds') {
+                throw new ApiError(409, `Task ${taskId} is not at max_rounds (status=${task.status})`);
+            }
+            // spec-phase max_rounds escapes via Retry/Cancel only (the UI hides complete). Guard the
+            // endpoint too so a direct API call / older client can't merge a spec cap through here.
+            if (task.phase === 'spec') {
+                throw new ApiError(409, `Mark complete is only supported for code-phase tasks`);
+            }
+            if (task.reviewMode !== 'server' && (!task.prNumber || !task.branch)) {
+                throw new ApiError(400, `Task ${taskId} has no PR/branch; cannot mark complete`);
+            }
+            if (serverApprovedRetry) {
+                // A live code-ready watcher armed by a real dispatch means the publish
+                // prompt IS running — a retry would inject a second prompt and rotate
+                // the token under it. A RECOVERED watcher is weaker evidence, but
+                // publishDispatchedAt persists delivery across restarts: set = the
+                // prompt reached the pane before the restart (still in flight, 409);
+                // cleared = the dispatch failed and this approved state is retryable —
+                // stop the recovered watch and let the retry own the dispatch (PR #288).
+                if (this.phaseSignalWatcher?.expectedKindsFor(taskId).has('code-ready')) {
+                    if (!this.phaseSignalWatcher.isRecovered(taskId) || task.publishDispatchedAt) {
+                        throw new ApiError(409, `Task ${taskId} publish is in flight; retry only after it fails`);
+                    }
+                    this.phaseSignalWatcher.stop(taskId);
+                }
+                else if (task.publishDispatchedAt) {
+                    throw new ApiError(409, `Task ${taskId} publish was delivered and is awaiting code-ready; ` +
+                        `retry only after it fails (if the publish is verifiably dead, Cancel the task)`);
+                }
+                // task.afterDone was snapshotted when the approve verdict routed it.
+                const afterDone = this.resolveAfterDone(task);
+                if (afterDone === null) {
+                    throw new ApiError(409, `Task ${taskId} is approved with no afterDone step; nothing to retry`);
+                }
+                await this.dispatchServerAfterDone(taskId, afterDone);
+                return (await this.taskStore.get(taskId));
+            }
+            // Server-mode capped task, human accepts as-is: no PR exists yet — run the
+            // afterDone flow (or finish directly) instead of the legacy PR merge (PR #288).
+            // Inside the in-flight claim so a concurrent Continue can't act on the same
+            // max_rounds snapshot and release dev mid-publish.
+            if (task.reviewMode === 'server') {
+                // Max_rounds never routed an approve verdict — snapshot afterDone NOW so
+                // the eventual ready-confirm uses this decision, not future hot config.
+                const afterDone = this.config.review.afterDone ?? null;
+                await this.updateTask(taskId, { afterDone });
+                if (afterDone === null) {
+                    const done = await this.transitionTaskStatus(taskId, 'done', { fromStatus: ['max_rounds'] });
+                    if (!done)
+                        throw new ApiError(409, `Task ${taskId} changed status during mark-complete; aborted`);
+                    await this.releaseTaskAgents(taskId);
+                    return (await this.taskStore.get(taskId));
+                }
+                const approved = await this.transitionTaskStatus(taskId, 'approved', { fromStatus: ['max_rounds'] });
+                if (!approved)
+                    throw new ApiError(409, `Task ${taskId} changed status during mark-complete; aborted`);
+                await this.dispatchServerAfterDone(taskId, afterDone);
+                return (await this.taskStore.get(taskId));
+            }
             // Held-agent check AFTER claiming (the claim blocks a new continueDevRound from starting),
             // and re-reading agent state here catches a continue that Held an agent in the window just
             // before our claim. dispatchPostMergeCleanup early-returns on awaiting_human, so merging with
@@ -4060,6 +4508,28 @@ export class AgentManager {
         }
     }
     async runPostMergeCompaction(tmux, paneId, agentId, originalTaskId, runtime, prompt) {
+        // 等待获取（而非无条件 add）：手动 compact 持锁时直接进入会并发注入，
+        // 且 finally 会误删对方的 guard 放穿后续请求。
+        await this.acquireCompactGuard(agentId);
+        try {
+            await this.runPostMergeCompactionSteps(tmux, paneId, agentId, originalTaskId, runtime, prompt);
+        }
+        finally {
+            this.compactInFlight.delete(agentId);
+        }
+    }
+    async acquireCompactGuard(agentId) {
+        while (!this.tryAcquireCompactGuard(agentId)) {
+            await new Promise(r => setTimeout(r, this.compactIdlePollMs));
+        }
+    }
+    tryAcquireCompactGuard(agentId) {
+        if (this.compactInFlight.has(agentId))
+            return false;
+        this.compactInFlight.add(agentId);
+        return true;
+    }
+    async runPostMergeCompactionSteps(tmux, paneId, agentId, originalTaskId, runtime, prompt) {
         const bindingStillOurs = async () => {
             const s = await this.agentStore.get(agentId);
             return !!s && s.taskId === originalTaskId && s.paneId === paneId;
@@ -4132,18 +4602,12 @@ export class AgentManager {
     stopPhaseSignalWatcher(taskId) {
         this.phaseSignalWatcher?.stop(taskId);
     }
-    // Backwards-compat alias for spec-only call sites (recovery, transitions
-    // that already named the kind). New callers should use setupPhaseSignalWatcher
-    // directly with the right expectedKinds.
-    stopSpecSignalWatcher(taskId) {
-        this.stopPhaseSignalWatcher(taskId);
-    }
     // Prompt build (via task.signalToken) and watcher must share the same token.
     // Returns whether dispatch may safely proceed. False ONLY when a configured watcher failed
     // to arm — the dangerous case where a same-identity verdict would have no consumer. When no
     // watcher subsystem is configured at all (poller-only deployment) the poller is the verdict
     // path, so this returns true and does not block. Best-effort callers ignore the result.
-    async setupPhaseSignalWatcher(taskId, agentId, expectedKinds, token, skipSnapshot = false) {
+    async setupPhaseSignalWatcher(taskId, agentId, expectedKinds, token, skipSnapshot = false, onReadFile) {
         if (!this.phaseSignalWatcher)
             return true;
         const task = await this.taskStore.get(taskId);
@@ -4157,6 +4621,7 @@ export class AgentManager {
                 expectedKinds,
                 token,
                 skipSnapshot,
+                ...(onReadFile ? { onReadFile } : {}),
             });
         }
         catch (err) {
@@ -4167,8 +4632,8 @@ export class AgentManager {
     // Arm a watcher for a signal the just-dispatched prompt will emit, then hold the agent if it
     // could not arm. Used by post-dispatch arms (develop/spec/code phases) whose pane only exists
     // after dispatch, so they can't gate before sending the prompt the way verdict dispatch does.
-    async armPostDispatchSignalOrHold(taskId, agentId, expectedKinds, token, skipSnapshot = false) {
-        const armed = await this.setupPhaseSignalWatcher(taskId, agentId, expectedKinds, token, skipSnapshot);
+    async armPostDispatchSignalOrHold(taskId, agentId, expectedKinds, token, skipSnapshot = false, onReadFile) {
+        const armed = await this.setupPhaseSignalWatcher(taskId, agentId, expectedKinds, token, skipSnapshot, onReadFile);
         if (!armed)
             await this.holdAgentForUnarmedSignal(taskId, agentId, expectedKinds);
     }
@@ -4220,56 +4685,125 @@ export class AgentManager {
         if (mapped)
             await this.setupPhaseSignal(taskId, mapped.agentId, mapped.expectedKinds);
     }
-    async readSpecReviewFile(taskId, fileName) {
+    async transitionToCodePhase(taskId) {
         const task = await this.taskStore.get(taskId);
         if (!task)
             return null;
-        if (!task.branch) {
-            throw new Error(`readSpecReviewFile: task ${taskId} has no branch`);
-        }
-        const project = this.getProjectConfig(task.projectId);
-        if (!project) {
-            throw new Error(`readSpecReviewFile: unknown project ${task.projectId}`);
-        }
-        const dev = this.getAgentConfig(task.agentId);
-        if (!dev) {
-            throw new Error(`readSpecReviewFile: task ${taskId} has no dev agent bound`);
+        const devAgentId = task.agentId;
+        if (!devAgentId)
+            return null;
+        // Rotate token for the code phase so dev's pr-created signal is fresh; old
+        // spec token must not survive into a different expected-kind set.
+        const newToken = createSignalToken();
+        // Atomic transition + persist: 旧版先 transition 再 updateTask, 中间崩溃 task 卡在
+        // (phase='spec', status='in_progress') — setupRecoveredSpecSignals 三个 case 都不匹配,
+        // freshness gate 也拒所有 spec.* event, 任务 stranded 无 auto-recovery。
+        const transition = await this.transitionTaskStatus(taskId, 'in_progress', { fromStatus: ['review', 'fixing'] }, { phase: 'code', signalToken: newToken });
+        if (!transition)
+            return null;
+        this.stopPhaseSignalWatcher(taskId);
+        // Best-effort arm (NOT hold-on-failure): this runs before the code prompt is dispatched
+        // (acquire + continueSession below), so holding here would block that reentry. And pr-created
+        // is authoritatively detected by the GitHub poller (PR creation isn't same-identity-gated), so
+        // a missed pane watcher only costs one poll cycle of latency, never a stuck task.
+        // Server mode has NO poller backstop: an unarmed code-done watcher means the
+        // dev's completion signal would have no consumer — fail closed and hold.
+        const codeKind = task.reviewMode === 'server' ? 'code-done' : 'pr-created';
+        const codeArmed = await this.setupPhaseSignalWatcher(taskId, devAgentId, codeKind, newToken);
+        if (!codeArmed && task.reviewMode === 'server') {
+            await this.holdAgentForUnarmedSignal(taskId, devAgentId, codeKind);
+            return null;
         }
-        const runner = this.createRunnerFor(dev);
-        const store = this.createRepoStore(dev, project, runner);
-        const workdir = await this.resolveWorkdir(dev, await this.agentStore.get(dev.id))
-            ?? await store.ensure();
-        const filePath = `.baxian/spec-review/${fileName}`;
-        return store.readFileFromBranch(workdir, task.branch, filePath);
-    }
-    async dispatchSpecReviewToQa(taskId) {
-        // Phase 1 (lock): validate + decide qa + compute newToken/newRound (无 mutation, 无 park)。
-        // 关键约束：task 不能在 startSession 之前被改 — startSession 内部调用
-        // buildPromptInline，prompt 必须看到的是新 token 和新 round；这里只 *计算*，
-        // 真正写回 task 放到 Phase 3。
-        const claim = await this.withTaskLock(async () => {
-            const task = await this.taskStore.get(taskId);
-            if (!task)
-                throw new Error(`dispatchSpecReviewToQa: task ${taskId} not found`);
-            if (!task.branch)
-                throw new Error(`dispatchSpecReviewToQa: task ${taskId} has no branch`);
-            // Stale spec-created guard: 一旦 task 离开 pre-spec 阶段 (phase='code' 或其他
-            // 非 'spec'/undefined 值)，迟到的 spec-created signal 不应再 dispatch review。
-            // 允许 phase==='spec' 是预留 dev 在 fix-complete 后再 emit spec-created 的扩展点。
-            if (task.phase !== undefined && task.phase !== 'spec') {
+        if (task.qaAgentId) {
+            // release 失败留 stale qa binding → emit intervention 让其可见。
+            const released = await this.releaseAgentForTask(task.qaAgentId, taskId, 'idle')
+                .catch(() => false);
+            if (!released) {
                 await this.safeEmit({
                     id: '',
                     type: 'human.intervention',
                     timestamp: new Date().toISOString(),
                     projectId: task.projectId,
-                    agentId: task.agentId,
+                    agentId: task.qaAgentId,
                     taskId,
-                    data: { phase: 'spec-created-stale-after-code', taskPhase: task.phase },
+                    data: { phase: 'code-phase-qa-release-failed', qaAgentId: task.qaAgentId },
                 });
-                return null;
             }
-            const qa = this.findQaPartner(task.agentId);
-            if (!qa) {
+        }
+        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'code');
+        if (!acquired) {
+            // Task already shows phase='code' in_progress with the code-done watcher
+            // armed, and server mode has no poller backstop — without a hold the dev
+            // never receives the code prompt and the task dead-ends. The
+            // code-dispatch-failed hold gives Resume a redispatch path.
+            await this.markAwaitingHuman(devAgentId, 'code-dispatch-failed', 'Dev could not be acquired for the code phase after spec approval; the task looks in_progress but the code prompt was never dispatched. Resume the agent to redispatch or cancel the task.', { expectedTaskId: taskId }).catch(() => undefined);
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId: task.projectId,
+                agentId: devAgentId,
+                taskId,
+                data: { phase: 'code-dev-acquire-failed', devAgentId },
+            });
+            return null;
+        }
+        let resumed = false;
+        try {
+            resumed = await this.continueSession(taskId, devAgentId, 'code');
+        }
+        catch (err) {
+            // 同 dispatchServerReviewToQa/dispatchServerFixToDev：DispatchTerminalError 委托给 failTaskForDispatchError
+            // （ack_unknown → markAwaitingHuman；其他 reason → release + task failed）。
+            if (err instanceof DispatchTerminalError) {
+                await this.failTaskForDispatchError(taskId, 'code', devAgentId, err);
+            }
+            else if (!(err instanceof EnsureSessionError && err.partial.handled)) {
+                // Task already shows phase='code' in_progress but the prompt never landed
+                // and there is no retry entry — hold explicitly instead of dead-ending.
+                await this.markAwaitingHuman(devAgentId, 'code-dispatch-failed', 'Code-phase prompt was not delivered after spec approval; the task looks in_progress but the dev never received it. Resume/restart the agent or cancel the task.', { expectedTaskId: taskId }).catch(() => undefined);
+            }
+            console.error(`[AgentManager] transitionToCodePhase continueSession(dev=${devAgentId}) failed:`, err);
+            throw err;
+        }
+        if (!resumed) {
+            await this.markAwaitingHuman(devAgentId, 'code-dispatch-failed', 'Code-phase prompt was not delivered after spec approval; the task looks in_progress but the dev never received it. Resume/restart the agent or cancel the task.', { expectedTaskId: taskId }).catch(() => undefined);
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId: task.projectId,
+                agentId: devAgentId,
+                taskId,
+                data: { phase: 'code-resume-failed', devAgentId },
+            });
+            return null;
+        }
+        return await this.taskStore.get(taskId);
+    }
+    // ── Server review mode (spec: docs/spec/server-review-mode.md) ──────────────
+    async dispatchServerReviewToQa(taskId, opts) {
+        const dispatchPhase = opts.phase === 'spec'
+            ? 'server-spec-review'
+            : (opts.recheck ? 'server-recheck' : 'server-review');
+        const expectedKind = opts.phase === 'spec' ? 'spec-reviewed' : 'code-reviewed';
+        const claim = await this.withTaskLock(async () => {
+            const task = await this.taskStore.get(taskId);
+            if (!task)
+                throw new Error(`dispatchServerReviewToQa: task ${taskId} not found`);
+            // spec 阶段恒为 server 中转；code 阶段仍 server-only。
+            if (task.reviewMode !== 'server' && opts.phase !== 'spec') {
+                throw new Error(`dispatchServerReviewToQa: task ${taskId} is not in server review mode`);
+            }
+            const qaId = task.qaAgentId ?? this.findQaPartner(task.agentId)?.id;
+            if (!qaId) {
+                // Config validation rejects qa-less server pairs, but a hot-removed QA
+                // can still land here — re-arm the consumed entry signal so the task
+                // is recoverable once a QA is configured again.
+                const entryKind = task.status === 'fixing'
+                    ? (opts.phase === 'spec' ? 'spec-fixed' : 'code-fixed')
+                    : (opts.phase === 'spec' ? 'spec-done' : 'code-done');
+                await this.setupPhaseSignal(taskId, task.agentId, entryKind, { skipSnapshot: true });
                 await this.safeEmit({
                     id: '',
                     type: 'human.intervention',
@@ -4277,83 +4811,103 @@ export class AgentManager {
                     projectId: task.projectId,
                     agentId: task.agentId,
                     taskId,
-                    data: { phase: 'spec-review-no-qa-partner', devAgentId: task.agentId },
+                    data: { phase: 'server-review-no-qa-partner', devAgentId: task.agentId },
                 });
                 return null;
             }
-            // 记录入口 status — fix-then-review 重派 (fromStatus 含 'fixing') 时,
-            // spawn 失败 rollback 不能无差别回 in_progress；必须回到原 status 以保留 spec phase。
-            // transitionTaskStatus 的 fromStatus 守门已限定为这三种之一; 其他 status 不会走到这里。
-            const isReviewEntry = task.status === 'in_progress'
-                || task.status === 'fixing'
-                || task.status === 'pending';
-            if (!isReviewEntry)
-                return null;
+            const roundField = opts.phase === 'spec' ? (task.specReviewRound ?? 0) : task.reviewRound;
             return {
-                qaId: qa.id,
+                qaId,
                 devAgentId: task.agentId,
                 projectId: task.projectId,
                 newToken: createSignalToken(),
-                newRound: (task.specReviewRound ?? 0) + 1,
+                newRound: opts.continuation ? Math.max(roundField, 1) : roundField + 1,
                 originalStatus: task.status,
-                // 记录原 spec-created token — pre-spec entry rollback 时 restore,
-                // 让 dev 后续 spec-created signal (with 原 token) 经 handler freshness gate 通过 → auto retry。
                 originalToken: task.signalToken,
-                // 回滚时 restore — round 是 "已完成轮次" 计数, 累计失败不应吃 round 配额。
-                originalRound: task.specReviewRound,
+                originalRound: roundField,
+                originalBatchIndex: task.batchIndex,
+                originalBatchTotal: task.batchTotal,
+                originalPhase: task.phase,
             };
         });
         if (!claim)
             return null;
-        const { qaId, devAgentId, projectId, newToken, newRound, originalStatus, originalToken, originalRound } = claim;
-        // Phase 2a: 先 acquire QA — 失败时 dev 还未 park，直接 return 即可。
-        const acquired = await this.acquireAgentForTask(qaId, taskId, 'spec-review');
-        if (!acquired) {
-            await this.safeEmit({
-                id: '',
-                type: 'human.intervention',
-                timestamp: new Date().toISOString(),
-                projectId,
-                agentId: qaId,
-                taskId,
-                data: { phase: 'spec-review-qa-acquire-failed', qaAgentId: qaId },
-            });
-            return null;
-        }
-        // Phase 2b: dev gate — park dev so it stops editing the spec while QA reviews。
-        // 顺序在 acquireQA 之后：避免 QA 失败时 dev 已 parked 但 task 仍 in_progress，
-        // 无任何后续 dispatch 把 dev 拉出 waiting (即 dev 永久挂起)。
-        if (devAgentId) {
-            const devOk = await this.markAgentWaiting(devAgentId, taskId);
-            if (!devOk) {
-                await this.releaseAgentForTask(qaId, taskId, 'idle')
-                    .catch(() => undefined);
+        const { qaId, devAgentId, projectId, newToken, newRound } = claim;
+        // continueSession failure after the transition would otherwise strand the
+        // task in 'review' with a fresh token nobody will ever signal (PR #288).
+        const rollback = async () => {
+            await this.transitionTaskStatus(taskId, claim.originalStatus, { fromStatus: ['review'] }, {
+                signalToken: claim.originalToken,
+                batchIndex: claim.originalBatchIndex,
+                batchTotal: claim.originalBatchTotal,
+                // spec transition 写入 phase:'spec'；github 首轮失败若不还原，dev 直发
+                // pr-created 会被 legacy freshness gate 拒（设计 §2）。
+                phase: claim.originalPhase,
+                ...(opts.phase === 'spec'
+                    ? { specReviewRound: claim.originalRound }
+                    : { reviewRound: claim.originalRound }),
+            }).catch(() => undefined);
+        };
+        // The entry signal (code/spec-done|fixed) was already consumed by the
+        // watcher; a pre-transition failure must re-arm it with the unrotated token
+        // or the agent's re-emit after the operator fixes availability has no
+        // consumer (PR #288).
+        const rearmEntrySignal = async () => {
+            const entryKind = claim.originalStatus === 'fixing'
+                ? (opts.phase === 'spec' ? 'spec-fixed' : 'code-fixed')
+                : (opts.phase === 'spec' ? 'spec-done' : 'code-done');
+            await this.setupPhaseSignal(taskId, devAgentId, entryKind, { skipSnapshot: true });
+        };
+        if (!opts.continuation) {
+            const acquired = await this.acquireAgentForTask(qaId, taskId, dispatchPhase);
+            if (!acquired) {
+                await rearmEntrySignal();
                 await this.safeEmit({
                     id: '',
                     type: 'human.intervention',
                     timestamp: new Date().toISOString(),
                     projectId,
-                    agentId: devAgentId,
+                    agentId: qaId,
                     taskId,
-                    data: { phase: 'spec-review-dev-park-failed', devAgentId },
+                    data: { phase: 'server-review-qa-acquire-failed', qaAgentId: qaId },
                 });
                 return null;
             }
+            if (devAgentId) {
+                const devOk = await this.markAgentWaiting(devAgentId, taskId);
+                if (!devOk) {
+                    await this.releaseAgentForTask(qaId, taskId, 'idle').catch(() => undefined);
+                    await rearmEntrySignal();
+                    await this.safeEmit({
+                        id: '',
+                        type: 'human.intervention',
+                        timestamp: new Date().toISOString(),
+                        projectId,
+                        agentId: devAgentId,
+                        taskId,
+                        data: { phase: 'server-review-dev-park-failed', devAgentId },
+                    });
+                    return null;
+                }
+            }
         }
-        // Phase 2c (lock): atomic transition + persist newToken/newRound/phase/qaAgentId.
-        // 必须在 startSession 之前；若顺序反过来，startSession 之后崩溃但 transition 没做时，
-        // setupRecoveredSpecSignals 会读旧 status/token 推断错 kind/token，新 signal 无法匹配 → 链路死。
-        const transition = await this.transitionTaskStatus(taskId, 'review', { fromStatus: ['in_progress', 'fixing', 'pending'] }, {
-            specReviewRound: newRound,
+        const roundPatch = opts.phase === 'spec'
+            ? { specReviewRound: newRound, phase: 'spec' }
+            : { reviewRound: newRound };
+        const transition = await this.transitionTaskStatus(taskId, 'review', { fromStatus: ['in_progress', 'fixing', 'review'] }, {
             signalToken: newToken,
-            phase: 'spec',
             qaAgentId: qaId,
+            reviewDispatchedAt: new Date().toISOString(),
+            ...(opts.reviewHeadAnchorSha ? { reviewHeadAnchorSha: opts.reviewHeadAnchorSha } : {}),
+            ...(opts.batch
+                ? { batchIndex: opts.batch.index, batchTotal: opts.batch.total }
+                : { batchIndex: undefined, batchTotal: undefined }),
+            ...roundPatch,
         });
         if (!transition) {
-            await this.releaseAgentForTask(qaId, taskId, 'idle')
-                .catch(() => undefined);
-            // 不 re-acquire dev: markAgentWaiting (mode='waiting') 仅 bump updatedAt,
-            // dev 仍 bound 到 task; develop phase 不在 reentry 集合, 重 acquire 必返回 false (dead code)。
+            if (!opts.continuation) {
+                await this.releaseAgentForTask(qaId, taskId, 'idle').catch(() => undefined);
+            }
             await this.safeEmit({
                 id: '',
                 type: 'human.intervention',
@@ -4361,45 +4915,63 @@ export class AgentManager {
                 projectId,
                 agentId: qaId,
                 taskId,
-                data: { phase: 'spec-review-transition-failed', qaAgentId: qaId },
+                data: { phase: 'server-review-transition-failed', qaAgentId: qaId },
             });
             return null;
         }
-        // Phase 2d: startSession 用显式 newToken/newRound 透传到 prompt。
-        // 失败时回滚 transition + 清新 persist 字段，避免 task 留在 review 但 qa 无 session 的 stuck。
-        // 不调 acquireAgentForTask(dev, 'develop')：markAgentWaiting 走 mode='waiting' 仅 bump updatedAt
-        // (不清 binding 也不真正 park REPL)，dev 仍 bound 到 task；且 develop phase 不在
-        // canDispatchWithBinding 的 reentry 集合，重 acquire 必返回 false — 是 dead code。
+        // First dispatch creates the QA's base-detached worktree (startSession);
+        // batch continuations reuse the live session + worktree (continueSession).
+        const sessionOpts = {
+            bypassTaskStatusGate: true,
+            signalToken: newToken,
+            serverContent: opts.content,
+            ...(opts.diffstat !== undefined ? { serverDiffstat: opts.diffstat } : {}),
+            ...(opts.contentTruncated ? { contentTruncated: true } : {}),
+            ...(opts.batch ? { serverBatch: opts.batch } : {}),
+            ...(opts.priorFindingsJson ? { serverPriorFindings: opts.priorFindingsJson } : {}),
+            ...(opts.priorResponseJson ? { serverPriorResponse: opts.priorResponseJson } : {}),
+            ...(opts.phase === 'spec' ? { currentSpecRound: newRound } : {}),
+        };
+        // A continuation consumed the QA's reviewed signal (not the dev's entry
+        // signal): rollback restores the prior slice's review/token, so re-arm the
+        // reviewed watcher — the QA's re-emit replays the stored batch findings and
+        // resumes the next-slice dispatch (PR #288).
+        const rearmConsumedSignal = async () => {
+            if (opts.continuation) {
+                await this.setupPhaseSignal(taskId, qaId, expectedKind, { skipSnapshot: true });
+            }
+            else {
+                await rearmEntrySignal();
+            }
+        };
         let started = false;
         try {
-            started = await this.startSession(taskId, qaId, 'spec-review', {
-                bypassTaskStatusGate: true,
-                signalToken: newToken,
-                currentSpecRound: newRound,
-            });
+            started = opts.continuation
+                ? await this.continueSession(taskId, qaId, dispatchPhase, sessionOpts)
+                : await this.startSession(taskId, qaId, dispatchPhase, sessionOpts);
         }
         catch (err) {
-            // DispatchTerminalError 都委托给 failTaskForDispatchError：ack_unknown 会保留绑定走
-            // markAwaitingHuman，其他 reason（prompt_too_large 等非 transient）让 task 进 failed
-            // 而不是 rollback 让 cron 反复 retry。其他异常（瞬时 / 不明）才走 rollback + release。
             if (err instanceof DispatchTerminalError) {
-                await this.failTaskForDispatchError(taskId, 'spec-review', qaId, err);
+                await this.failTaskForDispatchError(taskId, dispatchPhase, qaId, err);
             }
             else if (err instanceof EnsureSessionError && err.partial.handled) {
-                // handleDialogPendingFromRuntime 已 Held + fail task + release partners；跳过 rollback + release，
-                // 否则 boundTask terminal 让 release gate 放行清掉仍卡 dialog 的 pane lock。
+                // handleDialogPendingFromRuntime already held + failed + released.
             }
             else {
-                await this.rollbackSpecReviewTransition(taskId, originalStatus, originalToken, originalRound);
-                await this.releaseAgentForTask(qaId, taskId, 'idle')
-                    .catch(() => undefined);
+                await rollback();
+                if (!opts.continuation) {
+                    await this.releaseAgentForTask(qaId, taskId, 'idle').catch(() => undefined);
+                }
+                await rearmConsumedSignal();
             }
             throw err;
         }
         if (!started) {
-            await this.rollbackSpecReviewTransition(taskId, originalStatus, originalToken, originalRound);
-            await this.releaseAgentForTask(qaId, taskId, 'idle')
-                .catch(() => undefined);
+            await rollback();
+            if (!opts.continuation) {
+                await this.releaseAgentForTask(qaId, taskId, 'idle').catch(() => undefined);
+            }
+            await rearmConsumedSignal();
             await this.safeEmit({
                 id: '',
                 type: 'human.intervention',
@@ -4407,75 +4979,75 @@ export class AgentManager {
                 projectId,
                 agentId: qaId,
                 taskId,
-                data: { phase: 'spec-review-start-failed', qaAgentId: qaId },
+                data: { phase: 'server-review-start-failed', qaAgentId: qaId },
             });
             return null;
         }
-        // Phase 3: set up watcher。spec-created 已被消费，先 tear down 防止 dev 之后无关 signal 误触发。
-        // QA echoes exactly one verdict signal — set up both kinds, the first match wins.
-        this.stopSpecSignalWatcher(taskId);
-        await this.armPostDispatchSignalOrHold(taskId, qaId, ['spec-approved', 'spec-changes-requested'], newToken);
+        this.stopPhaseSignalWatcher(taskId);
+        await this.armPostDispatchSignalOrHold(taskId, qaId, expectedKind, newToken, false, (req) => { void this.handleReadFileRequest(taskId, qaId, req); });
         return await this.taskStore.get(taskId);
     }
-    // startSession 失败回滚：
-    // - pre-spec entry: restore originalToken 让 dev 后续 spec-created signal 经 freshness gate 通过 → auto retry。
-    // - fixing entry: 保留 phase='spec' + qaAgentId（否则 spec.* freshness gate 全 fail），清 token 防 stale。
-    // round 必须 restore — round 是 "已完成轮次" 计数, 累计失败不应吃 round 配额。
-    async rollbackSpecReviewTransition(taskId, originalStatus, originalToken, originalRound) {
-        if (originalStatus === 'fixing') {
-            await this.transitionTaskStatus(taskId, 'fixing', { fromStatus: ['review'] }, { signalToken: undefined, specReviewRound: originalRound });
-            return;
-        }
-        await this.transitionTaskStatus(taskId, originalStatus, { fromStatus: ['review'] }, {
-            signalToken: originalToken,
-            phase: undefined,
-            qaAgentId: undefined,
-            specReviewRound: originalRound,
-        });
-    }
-    async dispatchSpecFixToDev(taskId, findings) {
-        // Phase 1 (lock): validate + phase guard + decide newToken。
-        // fix 是同 round 的 dev 处理 QA findings，round 不递增；只刷新 token 让 prompt + watcher 唯一识别本轮 fix。
+    async dispatchServerFixToDev(taskId, findingsJson) {
         const claim = await this.withTaskLock(async () => {
             const task = await this.taskStore.get(taskId);
             if (!task)
-                throw new Error(`dispatchSpecFixToDev: task ${taskId} not found`);
-            const devAgentId = task.agentId;
-            if (!devAgentId) {
-                throw new Error(`dispatchSpecFixToDev: task ${taskId} has no dev agent`);
-            }
-            // 离开 spec 阶段的 task 不应再被 spec-fix dispatch 击中 (defense in depth — handler 也 gate)。
-            if (task.phase !== 'spec') {
-                await this.safeEmit({
-                    id: '',
-                    type: 'human.intervention',
-                    timestamp: new Date().toISOString(),
-                    projectId: task.projectId,
-                    agentId: devAgentId,
-                    taskId,
-                    data: { phase: 'spec-fix-stale-phase', taskPhase: task.phase },
-                });
-                return null;
+                throw new Error(`dispatchServerFixToDev: task ${taskId} not found`);
+            if (task.reviewMode !== 'server' && task.phase !== 'spec') {
+                throw new Error(`dispatchServerFixToDev: task ${taskId} is not in server review mode`);
             }
+            if (!task.agentId)
+                throw new Error(`dispatchServerFixToDev: task ${taskId} has no dev agent`);
             return {
-                devAgentId,
+                devAgentId: task.agentId,
                 qaAgentId: task.qaAgentId,
                 projectId: task.projectId,
                 newToken: createSignalToken(),
-                currentRound: task.specReviewRound ?? 1,
+                taskPhase: (task.phase ?? 'code'),
+                currentSpecRound: task.specReviewRound,
+                // Continue-one-round enters from max_rounds — failure must restore THAT,
+                // not silently demote the human's pause decision to 'review' (PR #288).
+                originalStatus: task.status,
+                originalToken: task.signalToken,
             };
         });
         if (!claim)
             return null;
-        const { devAgentId, qaAgentId, projectId, newToken, currentRound } = claim;
+        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 expectedKind = taskPhase === 'spec' ? 'spec-fixed' : 'code-fixed';
+        // The QA's reviewed signal was consumed before this dispatch; pre-transition
+        // failures must re-arm it (unrotated token) so a later re-emit is consumed.
+        const rearmReviewedSignal = async () => {
+            if (!qaAgentId)
+                return;
+            const reviewedKind = taskPhase === 'spec' ? 'spec-reviewed' : 'code-reviewed';
+            await this.setupPhaseSignal(taskId, qaAgentId, reviewedKind, { skipSnapshot: true });
+        };
+        // Dev BEFORE QA: releasing the QA first is irreversible (binding cleared,
+        // worktree removed, schedulable elsewhere) — a dev acquire failure after it
+        // would leave the review-parked task with no stably-bound agent to retry
+        // from. With the dev secured first, both failure exits keep the QA bound.
+        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'server-feedback');
+        if (!acquired) {
+            await rearmReviewedSignal();
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId,
+                agentId: devAgentId,
+                taskId,
+                data: { phase: 'server-fix-dev-acquire-failed', devAgentId },
+            });
+            return null;
+        }
         if (qaAgentId) {
-            // release 失败留 stale qa binding，下一轮 acquireAgentForTask(qa) 必拒；abort + emit intervention。
             const released = await this.releaseAgentForTask(qaAgentId, taskId, 'idle')
-                .catch(err => {
-                console.warn(`[AgentManager] dispatchSpecFixToDev release qa=${qaAgentId} failed:`, err);
-                return false;
-            });
+                .catch(() => false);
             if (!released) {
+                await rearmReviewedSignal();
                 await this.safeEmit({
                     id: '',
                     type: 'human.intervention',
@@ -4483,32 +5055,18 @@ export class AgentManager {
                     projectId,
                     agentId: qaAgentId,
                     taskId,
-                    data: { phase: 'spec-fix-qa-release-failed', qaAgentId },
+                    data: { phase: 'server-fix-qa-release-failed', qaAgentId },
                 });
                 return null;
             }
         }
-        // Phase 2a: acquire dev。
-        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'spec-fix');
-        if (!acquired) {
-            await this.safeEmit({
-                id: '',
-                type: 'human.intervention',
-                timestamp: new Date().toISOString(),
-                projectId,
-                agentId: devAgentId,
-                taskId,
-                data: { phase: 'spec-fix-dev-acquire-failed', devAgentId },
-            });
-            return null;
-        }
-        // Phase 2b (lock): atomic transition + persist newToken/phase。
-        // 必须在 continueSession 之前；否则崩溃后 setupRecoveredSpecSignals 读旧 token,
-        // 与 dev 输出的 newToken signal 不匹配 → 链路死。
-        const transition = await this.transitionTaskStatus(taskId, 'fixing', { fromStatus: ['review'] }, { signalToken: newToken, phase: 'spec' });
+        // max_rounds entry = human "continue one round" via continueDevRound.
+        const transition = await this.transitionTaskStatus(taskId, 'fixing', { fromStatus: ['review', 'max_rounds'] }, { signalToken: newToken, fixDispatchedAt: new Date().toISOString() });
         if (!transition) {
-            await this.releaseAgentForTask(devAgentId, taskId, 'idle')
-                .catch(() => undefined);
+            // Refusal = the task left review/max_rounds concurrently (cancel / fail /
+            // mark-complete publish). Ownership moved with it — releasing dev here
+            // would strip a binding the winning chain may be actively using (e.g. a
+            // publish prompt running in the pane); its own cleanup releases the dev.
             await this.safeEmit({
                 id: '',
                 type: 'human.intervention',
@@ -4516,42 +5074,42 @@ export class AgentManager {
                 projectId,
                 agentId: devAgentId,
                 taskId,
-                data: { phase: 'spec-fix-transition-failed', devAgentId },
+                data: { phase: 'server-fix-transition-failed', devAgentId },
             });
             return null;
         }
-        // Phase 2c: continueSession 透传 newToken + currentRound 给 prompt。
-        // 失败时回滚 transition + 清新 token，避免 task 留在 fixing 但 dev 无 spec-fix prompt 的 stuck。
         let resumed = false;
         try {
-            resumed = await this.continueSession(taskId, devAgentId, 'spec-fix', {
-                specFindings: findings,
-                signalToken: newToken,
-                currentSpecRound: currentRound,
+            resumed = await this.continueSession(taskId, devAgentId, 'server-feedback', {
                 bypassTaskStatusGate: true,
+                signalToken: newToken,
+                serverPriorFindings: findingsJson,
+                ...(taskPhase === 'spec' && currentSpecRound !== undefined
+                    ? { currentSpecRound }
+                    : {}),
             });
         }
         catch (err) {
-            // 同 spec-review：DispatchTerminalError 走 failTaskForDispatchError 统一处理
-            // （ack_unknown → markAwaitingHuman，其他 reason → release + task failed）。
             if (err instanceof DispatchTerminalError) {
-                await this.failTaskForDispatchError(taskId, 'spec-fix', devAgentId, err);
+                await this.failTaskForDispatchError(taskId, 'server-feedback', devAgentId, err);
             }
             else if (err instanceof EnsureSessionError && err.partial.handled) {
-                // handleDialogPendingFromRuntime 已 Held + fail task + release partners；跳过 rollback + release。
+                // handled upstream
             }
             else {
-                await this.rollbackSpecFixTransition(taskId);
-                await this.releaseAgentForTask(devAgentId, taskId, 'idle')
-                    .catch(() => undefined);
+                await rollbackToEntry();
+                await this.releaseAgentForTask(devAgentId, taskId, 'idle').catch(() => undefined);
+                // Rollback restored review/old-token, but the QA's reviewed signal was
+                // consumed — without a subscriber its re-emit can never retry the fix
+                // dispatch (PR #288).
+                await rearmReviewedSignal();
             }
-            console.error(`[AgentManager] dispatchSpecFixToDev continueSession(dev=${devAgentId}) failed:`, err);
             throw err;
         }
         if (!resumed) {
-            await this.rollbackSpecFixTransition(taskId);
-            await this.releaseAgentForTask(devAgentId, taskId, 'idle')
-                .catch(() => undefined);
+            await rollbackToEntry();
+            await this.releaseAgentForTask(devAgentId, taskId, 'idle').catch(() => undefined);
+            await rearmReviewedSignal();
             await this.safeEmit({
                 id: '',
                 type: 'human.intervention',
@@ -4559,59 +5117,34 @@ export class AgentManager {
                 projectId,
                 agentId: devAgentId,
                 taskId,
-                data: { phase: 'spec-fix-resume-failed', devAgentId },
+                data: { phase: 'server-fix-resume-failed', devAgentId },
             });
             return null;
         }
-        // Phase 3: set up watcher。
-        await this.armPostDispatchSignalOrHold(taskId, devAgentId, 'spec-fixed', newToken);
+        await this.armPostDispatchSignalOrHold(taskId, devAgentId, expectedKind, newToken);
         return await this.taskStore.get(taskId);
     }
-    // continueSession 失败回滚：fixing → review + 清新 token。
-    // 保留 phase='spec' 与 qaAgentId — 失败后 review 状态需要人工 retry 或重新 dispatch。
-    async rollbackSpecFixTransition(taskId) {
-        await this.transitionTaskStatus(taskId, 'review', { fromStatus: ['fixing'] }, { signalToken: undefined });
-    }
-    async transitionToCodePhase(taskId) {
+    async dispatchServerAfterDone(taskId, kind) {
         const task = await this.taskStore.get(taskId);
         if (!task)
-            return null;
+            throw new Error(`dispatchServerAfterDone: task ${taskId} not found`);
         const devAgentId = task.agentId;
         if (!devAgentId)
-            return null;
-        // Rotate token for the code phase so dev's pr-created signal is fresh; old
-        // spec token must not survive into a different expected-kind set.
+            throw new Error(`dispatchServerAfterDone: task ${taskId} has no dev agent`);
+        const branch = task.branch ?? BRANCH_PREFIX + taskId;
+        const originalToken = task.signalToken;
         const newToken = createSignalToken();
-        // Atomic transition + persist: 旧版先 transition 再 updateTask, 中间崩溃 task 卡在
-        // (phase='spec', status='in_progress') — setupRecoveredSpecSignals 三个 case 都不匹配,
-        // freshness gate 也拒所有 spec.* event, 任务 stranded 无 auto-recovery。
-        const transition = await this.transitionTaskStatus(taskId, 'in_progress', { fromStatus: ['review', 'fixing'] }, { phase: 'code', signalToken: newToken });
-        if (!transition)
-            return null;
-        this.stopPhaseSignalWatcher(taskId);
-        // Best-effort arm (NOT hold-on-failure): this runs before the code prompt is dispatched
-        // (acquire + continueSession below), so holding here would block that reentry. And pr-created
-        // is authoritatively detected by the GitHub poller (PR creation isn't same-identity-gated), so
-        // a missed pane watcher only costs one poll cycle of latency, never a stuck task.
-        await this.setupPhaseSignalWatcher(taskId, devAgentId, 'pr-created', newToken);
-        if (task.qaAgentId) {
-            // release 失败留 stale qa binding → emit intervention 让其可见。
-            const released = await this.releaseAgentForTask(task.qaAgentId, taskId, 'idle')
-                .catch(() => false);
-            if (!released) {
-                await this.safeEmit({
-                    id: '',
-                    type: 'human.intervention',
-                    timestamp: new Date().toISOString(),
-                    projectId: task.projectId,
-                    agentId: task.qaAgentId,
-                    taskId,
-                    data: { phase: 'code-phase-qa-release-failed', qaAgentId: task.qaAgentId },
-                });
-            }
-        }
-        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'code');
+        await this.updateTask(taskId, { signalToken: newToken });
+        // The publish prompt never reached the pane — restore the pre-rotation token
+        // (so recovery still matches the pre-dispatch arm) and clear the delivery
+        // marker so retry knows this approved state is preemptible (PR #288).
+        const rollbackToken = async () => {
+            await this.updateTask(taskId, { signalToken: originalToken, publishDispatchedAt: undefined })
+                .catch(() => undefined);
+        };
+        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'server-after-done');
         if (!acquired) {
+            await rollbackToken();
             await this.safeEmit({
                 id: '',
                 type: 'human.intervention',
@@ -4619,24 +5152,37 @@ export class AgentManager {
                 projectId: task.projectId,
                 agentId: devAgentId,
                 taskId,
-                data: { phase: 'code-dev-acquire-failed', devAgentId },
+                data: { phase: 'server-after-done-dev-acquire-failed', devAgentId },
             });
             return null;
         }
+        // Pessimistic delivery marker BEFORE the irreversible paste: every failure
+        // path below clears it. The remaining crash window (marker written, paste
+        // never ran) fails CLOSED — retry 409s on a publish that never started and
+        // the operator escapes via Cancel — instead of the old window's fail-open
+        // double publish (paste ran, marker missing, retry re-pastes) (PR #288).
+        await this.updateTask(taskId, { publishDispatchedAt: new Date().toISOString() });
         let resumed = false;
         try {
-            resumed = await this.continueSession(taskId, devAgentId, 'code');
+            resumed = await this.continueSession(taskId, devAgentId, 'server-after-done', {
+                bypassTaskStatusGate: true,
+                signalToken: newToken,
+                serverAfterDone: { kind, branch },
+            });
         }
         catch (err) {
-            // 同 spec-review/spec-fix：DispatchTerminalError 委托给 failTaskForDispatchError
-            // （ack_unknown → markAwaitingHuman；其他 reason → release + task failed）。
             if (err instanceof DispatchTerminalError) {
-                await this.failTaskForDispatchError(taskId, 'code', devAgentId, err);
+                await this.failTaskForDispatchError(taskId, 'server-after-done', devAgentId, err);
+            }
+            else if (!(err instanceof EnsureSessionError && err.partial.handled)) {
+                // Keep dev BOUND — its worktree holds the reviewed (unpushed) commits.
+                // mark-complete retries the publish via server-after-done same-task reentry.
+                await rollbackToken();
             }
-            console.error(`[AgentManager] transitionToCodePhase continueSession(dev=${devAgentId}) failed:`, err);
             throw err;
         }
         if (!resumed) {
+            await rollbackToken();
             await this.safeEmit({
                 id: '',
                 type: 'human.intervention',
@@ -4644,12 +5190,267 @@ export class AgentManager {
                 projectId: task.projectId,
                 agentId: devAgentId,
                 taskId,
-                data: { phase: 'code-resume-failed', devAgentId },
+                data: {
+                    phase: 'server-after-done-resume-failed',
+                    devAgentId,
+                    note: 'Publish prompt was not delivered; mark-complete retries the publish dispatch.',
+                },
             });
             return null;
         }
+        await this.armPostDispatchSignalOrHold(taskId, devAgentId, 'code-ready', newToken);
         return await this.taskStore.get(taskId);
     }
+    // QA asked for file context during a server-mode review. Read from the DEV
+    // worktree (the QA worktree sits on the base branch) and paste into QA's pane.
+    async handleReadFileRequest(taskId, qaAgentId, req) {
+        const task = await this.taskStore.get(taskId);
+        if (!task)
+            return;
+        const dev = this.getAgentConfig(task.agentId);
+        if (!dev)
+            return;
+        await this.refreshWorktreeCacheFor(task.agentId);
+        let body;
+        try {
+            const text = await this.getReviewTransport().readFileRange(dev, req.file, req.startLine, req.endLine);
+            body = `=== baxian read-file ${req.file}:${req.startLine}-${req.endLine} ===\n${text}\n=== end read-file ===`;
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            body = `=== baxian read-file ${req.file}:${req.startLine}-${req.endLine} REFUSED: ${reason} ===`;
+        }
+        // The read ran async — QA may have submitted its verdict and been released
+        // or rebound meanwhile. Never paste old-task content into a new task's pane.
+        const qaState = await this.agentStore.get(qaAgentId);
+        if (qaState?.taskId !== taskId) {
+            console.warn(`[AgentManager] read-file response dropped: qa=${qaAgentId} no longer bound to ${taskId} (got ${qaState?.taskId})`);
+            return;
+        }
+        try {
+            await this.injectTextToAgent(qaAgentId, body, { expectedTaskId: taskId });
+        }
+        catch (err) {
+            console.warn(`[AgentManager] read-file injection to ${qaAgentId} failed:`, err);
+        }
+    }
+    // Plain text paste + submit into a live agent pane (no skills, no ack protocol).
+    async injectTextToAgent(agentId, text, opts = {}) {
+        const cfg = this.getAgentConfig(agentId);
+        if (!cfg)
+            throw new Error(`injectTextToAgent: unknown agent ${agentId}`);
+        await this.acquireCompactGuard(agentId);
+        try {
+            // 锁内重读：guard 等待期间绑定可能已易主，过期文本决不落 pane。
+            const state = await this.agentStore.get(agentId);
+            if (opts.expectedTaskId !== undefined && state?.taskId !== opts.expectedTaskId) {
+                throw new Error(`injectTextToAgent: agent ${agentId} no longer bound to ${opts.expectedTaskId}`);
+            }
+            const paneId = state?.paneId;
+            if (!paneId)
+                throw new Error(`injectTextToAgent: agent ${agentId} has no live pane`);
+            const tmux = new TmuxManager(this.createRunnerFor(cfg));
+            await tmux.injectPrompt(paneId, text, agentId);
+            await tmux.sendEnter(paneId);
+        }
+        finally {
+            this.compactInFlight.delete(agentId);
+        }
+    }
+    // Human gate confirm (spec §10): executes the configured completion for
+    // ready (server mode) / merge-ready (github mode) tasks.
+    async confirmHumanGate(taskId) {
+        // Claim under the task lock: a Cancel racing this read can no longer flip the
+        // task to cancelled (and retire its artifacts) while we proceed on a stale
+        // gate snapshot — cancelTask checks the in-flight flag inside the same lock.
+        const task = await this.claimCompleteGate(taskId, ['ready', 'merge-ready']);
+        try {
+            const project = this.getProjectConfig(task.projectId);
+            const mergeAuto = project?.merge === 'auto';
+            // Snapshot from verdict time — a hot config flip between publish and
+            // confirm must not reroute an already-published artifact (PR #288).
+            const afterDone = this.resolveAfterDone(task);
+            if (task.status === 'merge-ready') {
+                if (mergeAuto && task.prNumber) {
+                    // Guard on the post-approve head persisted at the merge-ready transition.
+                    if (!task.latestHeadSha) {
+                        throw new ApiError(409, `Task ${taskId} has no approved head recorded; cannot safely merge`);
+                    }
+                    await this.executeConfirmMerge(task, () => this.mergePr(taskId, {
+                        matchHeadSha: task.latestHeadSha,
+                    }));
+                    await this.eventBus.emit({
+                        id: '',
+                        type: 'pr.merged',
+                        timestamp: new Date().toISOString(),
+                        projectId: task.projectId,
+                        agentId: task.agentId,
+                        taskId: task.id,
+                        data: { prNumber: task.prNumber, ...(task.prUrl ? { prUrl: task.prUrl } : {}) },
+                    });
+                    return (await this.taskStore.get(taskId));
+                }
+                return this.finishTaskAsDone(taskId);
+            }
+            // status === 'ready' (server mode)
+            if (afterDone === 'pr' && mergeAuto && task.prNumber) {
+                // Reviewed-head guard is mandatory here — publish fail-closes on capture,
+                // so a missing sha means tampered/legacy state, not a soft fallback.
+                if (!task.latestHeadSha) {
+                    throw new ApiError(409, `Task ${taskId} has no reviewed head recorded; cannot safely merge`);
+                }
+                await this.executeConfirmMerge(task, () => this.mergePr(taskId, {
+                    matchHeadSha: task.latestHeadSha,
+                }));
+                // pr.merged's fromStatus now includes 'ready' — let the handler own the
+                // merged transition + full cleanup chain (branch delete, /compact, release).
+                await this.eventBus.emit({
+                    id: '',
+                    type: 'pr.merged',
+                    timestamp: new Date().toISOString(),
+                    projectId: task.projectId,
+                    agentId: task.agentId,
+                    taskId: task.id,
+                    data: { prNumber: task.prNumber, ...(task.prUrl ? { prUrl: task.prUrl } : {}) },
+                });
+                return (await this.taskStore.get(taskId));
+            }
+            if (afterDone === 'branch' && mergeAuto && task.branch) {
+                await this.executeConfirmMerge(task, () => this.ffMergeBranch(task));
+                const merged = await this.transitionTaskStatus(taskId, 'merged', { fromStatus: ['ready'] });
+                if (merged)
+                    await this.releaseTaskAgents(taskId);
+                return (await this.taskStore.get(taskId));
+            }
+            return this.finishTaskAsDone(taskId);
+        }
+        finally {
+            this.markCompleteInFlight.delete(taskId);
+        }
+    }
+    // Atomic gate claim: re-read + status check + markCompleteInFlight.add under
+    // the task lock, so confirm and cancel serialize on the same snapshot.
+    async claimCompleteGate(taskId, statuses) {
+        return this.withTaskLock(async () => {
+            const fresh = await this.taskStore.get(taskId);
+            if (!fresh)
+                throw new ApiError(404, `Task ${taskId} not found`);
+            if (!statuses.includes(fresh.status)) {
+                throw new ApiError(409, `Task ${taskId} is not awaiting confirmation (status=${fresh.status})`);
+            }
+            if (this.markCompleteInFlight.has(taskId)) {
+                throw new ApiError(409, `Task ${taskId} is already being completed`);
+            }
+            this.markCompleteInFlight.add(taskId);
+            return fresh;
+        });
+    }
+    // Merge failures keep the gate: transient gh/network errors retry via another
+    // Confirm, a stale head resolves via Cancel or an external decision — terminal
+    // 'failed' would orphan the published PR/branch outside the task flow (PR #288).
+    async executeConfirmMerge(task, merge) {
+        try {
+            await merge();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId: task.projectId,
+                taskId: task.id,
+                data: {
+                    phase: 'confirm-merge-failed',
+                    gate: task.status,
+                    error: message,
+                    note: 'Task stays at the gate: Confirm again to retry, or Cancel to retire the published artifact.',
+                },
+            });
+            throw new ApiError(409, `Merge failed for task ${task.id}: ${message}`);
+        }
+    }
+    async finishTaskAsDone(taskId) {
+        const done = await this.transitionTaskStatus(taskId, 'done', { fromStatus: ['ready', 'merge-ready'] });
+        if (!done)
+            throw new ApiError(409, `Task ${taskId} changed status during confirm; aborted`);
+        await this.releaseTaskAgents(taskId);
+        return (await this.taskStore.get(taskId));
+    }
+    // Terminal-state resource release shared by done/merged(branch)/failed confirm
+    // paths: stop the watcher, release dev+qa (worktree removal rides releaseAgentForTask).
+    async releaseTaskAgents(taskId) {
+        this.phaseSignalWatcher?.stop(taskId);
+        const task = await this.taskStore.get(taskId);
+        if (!task)
+            return;
+        for (const id of [task.agentId, task.qaAgentId]) {
+            if (!id)
+                continue;
+            const state = await this.agentStore.get(id);
+            if (!state || state.taskId !== taskId)
+                continue;
+            await this.releaseAgentForTask(id, taskId, 'idle', { allowAwaitingHuman: true })
+                .catch(err => {
+                console.warn(`[AgentManager] confirm release ${id} failed:`, err);
+            });
+        }
+    }
+    // afterDone:'branch' + merge:'auto' — fast-forward the remote default branch
+    // to the reviewed branch ref-to-ref (`git push origin origin/bx/X:main`).
+    // Never touches the repo working tree, and a plain push is ff-only by default:
+    // a non-ff base is rejected by the remote and a human must rebase/decide (spec §6).
+    repoMergeQueue = new Map();
+    async ffMergeBranch(task) {
+        const dev = this.getAgentConfig(task.agentId);
+        if (!dev)
+            throw new Error(`ffMergeBranch: no dev agent for task ${task.id}`);
+        const state = await this.agentStore.get(task.agentId);
+        const repoPath = state?.repoPath;
+        if (!repoPath)
+            throw new Error(`ffMergeBranch: no repoPath for agent ${task.agentId}`);
+        const branch = task.branch ?? BRANCH_PREFIX + task.id;
+        const runner = this.createRunnerFor(dev);
+        const prev = this.repoMergeQueue.get(task.projectId) ?? Promise.resolve();
+        const run = prev.then(async () => {
+            const cd = `cd ${shellQuote(repoPath)} && `;
+            const db = await runner.exec(`${cd}git symbolic-ref --short refs/remotes/origin/HEAD`);
+            const defaultBranch = db.stdout.trim().replace(/^origin\//, '');
+            if (db.exitCode !== 0 || defaultBranch === '') {
+                // A silent 'main' fallback would push the reviewed branch onto the wrong
+                // ref for repos whose default branch differs (PR #288).
+                throw new Error(`ffMergeBranch: cannot resolve default branch: ${db.stderr.trim() || 'empty origin/HEAD'}`);
+            }
+            const fetch = await runner.exec(`${cd}git fetch origin`);
+            if (fetch.exitCode !== 0) {
+                throw new Error(`ffMergeBranch [git fetch] failed: ${fetch.stderr.trim()}`);
+            }
+            // Reviewed-head guard (branch path): refuse if origin/<branch> moved after
+            // the gate — symmetric with the pr path's --match-head-commit (PR #288).
+            if (task.latestHeadSha) {
+                const remoteHead = await runner.exec(`${cd}git rev-parse ${shellQuote(`origin/${branch}`)}`);
+                if (remoteHead.exitCode !== 0 || remoteHead.stdout.trim() !== task.latestHeadSha) {
+                    throw new Error(`ffMergeBranch: origin/${branch} head ${remoteHead.stdout.trim() || '<unresolved>'} ` +
+                        `!= reviewed head ${task.latestHeadSha}; refusing to merge un-reviewed commits`);
+                }
+            }
+            else {
+                throw new Error(`ffMergeBranch: no reviewed head recorded for task ${task.id}; cannot safely merge`);
+            }
+            const push = await runner.exec(`${cd}git push origin ${shellQuote(`origin/${branch}`)}:${shellQuote(defaultBranch)}`);
+            if (push.exitCode !== 0) {
+                throw new Error(`ffMergeBranch [push] failed: ${push.stderr.trim() || push.stdout.trim()}`);
+            }
+            // The merge has landed; branch deletion is cleanup — a transient failure
+            // here must not flip an already-merged task to failed (PR #288).
+            const del = await runner.exec(`${cd}git push origin --delete ${shellQuote(branch)}`);
+            if (del.exitCode !== 0) {
+                console.warn(`[AgentManager] ffMergeBranch: post-merge branch delete failed for ${branch}: ${del.stderr.trim() || del.stdout.trim()}`);
+            }
+        });
+        this.repoMergeQueue.set(task.projectId, run.catch(() => undefined));
+        await run;
+    }
 }
 function buildAgentIndex(config) {
     const index = new Map();