baxian 1.0.2 → 1.1.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 {
@@ -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
@@ -160,6 +163,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 +180,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 +974,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', 'spec-fix', 'code',
+            'server-feedback', 'server-after-done',
+        ]);
         const sameTaskReentry = state?.taskId === taskId &&
             !state.creationToken &&
             state.status !== 'awaiting_human' &&
@@ -1178,6 +1215,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 +1302,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 +1409,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 +1744,8 @@ export class AgentManager {
                     expectedKinds: 'pr-merge-ready',
                     token: completion.token,
                     skipSnapshot,
+                    reviewMode: task.reviewMode ?? 'github',
+                    recovered: true,
                 });
             }
             catch (err) {
@@ -1703,7 +1782,11 @@ export class AgentManager {
             // 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');
+            // Server mode scans on EVERY recovered state: the pane signal is the only
+            // verdict channel (no poller backstop) and all server handlers are
+            // replay-safe (token/status gates + stored-data resumption).
+            const scanSnapshotOnRecover = task.reviewMode === 'server'
+                || (task.phase !== 'spec' && (task.status === 'review' || task.status === 'fixing'));
             try {
                 await this.phaseSignalWatcher.start({
                     taskId: task.id,
@@ -1712,6 +1795,11 @@ export class AgentManager {
                     expectedKinds,
                     token: task.signalToken,
                     skipSnapshot: !scanSnapshotOnRecover,
+                    reviewMode: task.reviewMode ?? 'github',
+                    recovered: true,
+                    ...(task.reviewMode === 'server' && task.status === 'review'
+                        ? { onReadFile: (req) => { void this.handleReadFileRequest(task.id, agentId, req); } }
+                        : {}),
                 });
                 if (interventionKindLabel) {
                     await this.safeEmit({
@@ -1987,6 +2075,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 +2104,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 +2137,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 +2169,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 } : {}),
@@ -2162,12 +2254,15 @@ export class AgentManager {
             }
             // 后台路径吞掉 reject（void start.catch）：arm 抛异常时也要显式 hold agent，否则会留下一个没有
             // spec-created/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);
                 });
@@ -2365,7 +2460,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 +2549,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' || phase === 'spec-review'
+                ? 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)
@@ -2494,6 +2592,12 @@ export class AgentManager {
                 ...(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) {
@@ -2847,6 +2951,13 @@ export class AgentManager {
                 ...(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 +3346,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 +3370,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 +3415,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 +3440,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 +3452,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 +3558,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 +3775,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`);
         }
@@ -3690,7 +3960,17 @@ 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-created', '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 };
         }
@@ -3714,14 +3994,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 +4139,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
@@ -4143,7 +4499,7 @@ export class AgentManager {
     // 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 +4513,10 @@ export class AgentManager {
                 expectedKinds,
                 token,
                 skipSnapshot,
+                // Mode routing rides every arm automatically: the snapshot lives on the
+                // task, so github-mode tasks keep their legacy event types untouched.
+                reviewMode: task.reviewMode ?? 'github',
+                ...(onReadFile ? { onReadFile } : {}),
             });
         }
         catch (err) {
@@ -4167,8 +4527,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);
     }
@@ -4593,7 +4953,14 @@ export class AgentManager {
         // (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);
+        // 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;
+        }
         if (task.qaAgentId) {
             // release 失败留 stale qa binding → emit intervention 让其可见。
             const released = await this.releaseAgentForTask(task.qaAgentId, taskId, 'idle')
@@ -4612,6 +4979,11 @@ export class AgentManager {
         }
         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',
@@ -4633,10 +5005,16 @@ export class AgentManager {
             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',
@@ -4650,6 +5028,661 @@ export class AgentManager {
         }
         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`);
+            if (task.reviewMode !== 'server') {
+                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',
+                    timestamp: new Date().toISOString(),
+                    projectId: task.projectId,
+                    agentId: task.agentId,
+                    taskId,
+                    data: { phase: 'server-review-no-qa-partner', devAgentId: task.agentId },
+                });
+                return null;
+            }
+            const roundField = opts.phase === 'spec' ? (task.specReviewRound ?? 0) : task.reviewRound;
+            return {
+                qaId,
+                devAgentId: task.agentId,
+                projectId: task.projectId,
+                newToken: createSignalToken(),
+                newRound: opts.continuation ? Math.max(roundField, 1) : roundField + 1,
+                originalStatus: task.status,
+                originalToken: task.signalToken,
+                originalRound: roundField,
+                originalBatchIndex: task.batchIndex,
+                originalBatchTotal: task.batchTotal,
+            };
+        });
+        if (!claim)
+            return null;
+        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,
+                ...(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: qaId,
+                    taskId,
+                    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;
+                }
+            }
+        }
+        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,
+            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) {
+            if (!opts.continuation) {
+                await this.releaseAgentForTask(qaId, taskId, 'idle').catch(() => undefined);
+            }
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId,
+                agentId: qaId,
+                taskId,
+                data: { phase: 'server-review-transition-failed', qaAgentId: qaId },
+            });
+            return null;
+        }
+        // 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 = opts.continuation
+                ? await this.continueSession(taskId, qaId, dispatchPhase, sessionOpts)
+                : await this.startSession(taskId, qaId, dispatchPhase, sessionOpts);
+        }
+        catch (err) {
+            if (err instanceof DispatchTerminalError) {
+                await this.failTaskForDispatchError(taskId, dispatchPhase, qaId, err);
+            }
+            else if (err instanceof EnsureSessionError && err.partial.handled) {
+                // handleDialogPendingFromRuntime already held + failed + released.
+            }
+            else {
+                await rollback();
+                if (!opts.continuation) {
+                    await this.releaseAgentForTask(qaId, taskId, 'idle').catch(() => undefined);
+                }
+                await rearmConsumedSignal();
+            }
+            throw err;
+        }
+        if (!started) {
+            await rollback();
+            if (!opts.continuation) {
+                await this.releaseAgentForTask(qaId, taskId, 'idle').catch(() => undefined);
+            }
+            await rearmConsumedSignal();
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId,
+                agentId: qaId,
+                taskId,
+                data: { phase: 'server-review-start-failed', qaAgentId: qaId },
+            });
+            return null;
+        }
+        this.stopPhaseSignalWatcher(taskId);
+        await this.armPostDispatchSignalOrHold(taskId, qaId, expectedKind, newToken, false, (req) => { void this.handleReadFileRequest(taskId, qaId, req); });
+        return await this.taskStore.get(taskId);
+    }
+    async dispatchServerFixToDev(taskId, findingsJson) {
+        const claim = await this.withTaskLock(async () => {
+            const task = await this.taskStore.get(taskId);
+            if (!task)
+                throw new Error(`dispatchServerFixToDev: task ${taskId} not found`);
+            if (task.reviewMode !== 'server') {
+                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: task.agentId,
+                qaAgentId: task.qaAgentId,
+                projectId: task.projectId,
+                newToken: createSignalToken(),
+                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, 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) {
+            const released = await this.releaseAgentForTask(qaAgentId, taskId, 'idle')
+                .catch(() => false);
+            if (!released) {
+                await rearmReviewedSignal();
+                await this.safeEmit({
+                    id: '',
+                    type: 'human.intervention',
+                    timestamp: new Date().toISOString(),
+                    projectId,
+                    agentId: qaAgentId,
+                    taskId,
+                    data: { phase: 'server-fix-qa-release-failed', qaAgentId },
+                });
+                return null;
+            }
+        }
+        // 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) {
+            // 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',
+                timestamp: new Date().toISOString(),
+                projectId,
+                agentId: devAgentId,
+                taskId,
+                data: { phase: 'server-fix-transition-failed', devAgentId },
+            });
+            return null;
+        }
+        let resumed = false;
+        try {
+            resumed = await this.continueSession(taskId, devAgentId, 'server-feedback', {
+                bypassTaskStatusGate: true,
+                signalToken: newToken,
+                serverPriorFindings: findingsJson,
+                ...(taskPhase === 'spec' && currentSpecRound !== undefined
+                    ? { currentSpecRound }
+                    : {}),
+            });
+        }
+        catch (err) {
+            if (err instanceof DispatchTerminalError) {
+                await this.failTaskForDispatchError(taskId, 'server-feedback', devAgentId, err);
+            }
+            else if (err instanceof EnsureSessionError && err.partial.handled) {
+                // handled upstream
+            }
+            else {
+                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();
+            }
+            throw err;
+        }
+        if (!resumed) {
+            await rollbackToEntry();
+            await this.releaseAgentForTask(devAgentId, taskId, 'idle').catch(() => undefined);
+            await rearmReviewedSignal();
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId,
+                agentId: devAgentId,
+                taskId,
+                data: { phase: 'server-fix-resume-failed', devAgentId },
+            });
+            return null;
+        }
+        await this.armPostDispatchSignalOrHold(taskId, devAgentId, expectedKind, newToken);
+        return await this.taskStore.get(taskId);
+    }
+    async dispatchServerAfterDone(taskId, kind) {
+        const task = await this.taskStore.get(taskId);
+        if (!task)
+            throw new Error(`dispatchServerAfterDone: task ${taskId} not found`);
+        const devAgentId = task.agentId;
+        if (!devAgentId)
+            throw new Error(`dispatchServerAfterDone: task ${taskId} has no dev agent`);
+        const branch = task.branch ?? BRANCH_PREFIX + taskId;
+        const originalToken = task.signalToken;
+        const newToken = createSignalToken();
+        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',
+                timestamp: new Date().toISOString(),
+                projectId: task.projectId,
+                agentId: devAgentId,
+                taskId,
+                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, 'server-after-done', {
+                bypassTaskStatusGate: true,
+                signalToken: newToken,
+                serverAfterDone: { kind, branch },
+            });
+        }
+        catch (err) {
+            if (err instanceof DispatchTerminalError) {
+                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();
+            }
+            throw err;
+        }
+        if (!resumed) {
+            await rollbackToken();
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId: task.projectId,
+                agentId: devAgentId,
+                taskId,
+                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);
+        }
+        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) {
+        const cfg = this.getAgentConfig(agentId);
+        if (!cfg)
+            throw new Error(`injectTextToAgent: unknown agent ${agentId}`);
+        const state = await this.agentStore.get(agentId);
+        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);
+    }
+    // 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();