baxian 1.1.0 → 1.2.0

package/dist/agent/manager.js

@@ -74,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';
 }
@@ -132,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.
@@ -143,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;
@@ -975,7 +977,7 @@ export class AgentManager {
         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',
+            'fix', 'post-approve', 'code',
             'server-feedback', 'server-after-done',
         ]);
         const sameTaskReentry = state?.taskId === taskId &&
@@ -1744,7 +1746,6 @@ export class AgentManager {
                     expectedKinds: 'pr-merge-ready',
                     token: completion.token,
                     skipSnapshot,
-                    reviewMode: task.reviewMode ?? 'github',
                     recovered: true,
                 });
             }
@@ -1753,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() {
@@ -1769,23 +1770,25 @@ 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.
-            // 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'
+            // 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({
@@ -1795,9 +1798,8 @@ export class AgentManager {
                     expectedKinds,
                     token: task.signalToken,
                     skipSnapshot: !scanSnapshotOnRecover,
-                    reviewMode: task.reviewMode ?? 'github',
                     recovered: true,
-                    ...(task.reviewMode === 'server' && task.status === 'review'
+                    ...(isServerProtocol && task.status === 'review'
                         ? { onReadFile: (req) => { void this.handleReadFileRequest(task.id, agentId, req); } }
                         : {}),
                 });
@@ -2253,7 +2255,7 @@ 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);
@@ -2301,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);
@@ -2358,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 [];
@@ -2552,7 +2623,7 @@ export class AgentManager {
         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'
+            : 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.
@@ -2578,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);
@@ -2587,9 +2660,9 @@ 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 } : {}),
@@ -2762,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 {
@@ -2948,7 +3041,6 @@ 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 } : {}),
@@ -3937,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;
@@ -3966,13 +4058,13 @@ export class AgentManager {
         const mode = reviewMode ?? this.config.review.mode ?? 'github';
         return mode === 'server'
             ? ['spec-done', 'code-done']
-            : ['spec-created', 'pr-created'];
+            : ['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 };
@@ -3982,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 };
@@ -4416,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;
@@ -4488,12 +4602,6 @@ 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
@@ -4513,9 +4621,6 @@ 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 } : {}),
             });
         }
@@ -4580,358 +4685,6 @@ export class AgentManager {
         if (mapped)
             await this.setupPhaseSignal(taskId, mapped.agentId, mapped.expectedKinds);
     }
-    async readSpecReviewFile(taskId, fileName) {
-        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 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') {
-                await this.safeEmit({
-                    id: '',
-                    type: 'human.intervention',
-                    timestamp: new Date().toISOString(),
-                    projectId: task.projectId,
-                    agentId: task.agentId,
-                    taskId,
-                    data: { phase: 'spec-created-stale-after-code', taskPhase: task.phase },
-                });
-                return null;
-            }
-            const qa = this.findQaPartner(task.agentId);
-            if (!qa) {
-                await this.safeEmit({
-                    id: '',
-                    type: 'human.intervention',
-                    timestamp: new Date().toISOString(),
-                    projectId: task.projectId,
-                    agentId: task.agentId,
-                    taskId,
-                    data: { phase: 'spec-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;
-            return {
-                qaId: qa.id,
-                devAgentId: task.agentId,
-                projectId: task.projectId,
-                newToken: createSignalToken(),
-                newRound: (task.specReviewRound ?? 0) + 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,
-            };
-        });
-        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);
-                await this.safeEmit({
-                    id: '',
-                    type: 'human.intervention',
-                    timestamp: new Date().toISOString(),
-                    projectId,
-                    agentId: devAgentId,
-                    taskId,
-                    data: { phase: 'spec-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,
-            signalToken: newToken,
-            phase: 'spec',
-            qaAgentId: qaId,
-        });
-        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)。
-            await this.safeEmit({
-                id: '',
-                type: 'human.intervention',
-                timestamp: new Date().toISOString(),
-                projectId,
-                agentId: qaId,
-                taskId,
-                data: { phase: 'spec-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。
-        let started = false;
-        try {
-            started = await this.startSession(taskId, qaId, 'spec-review', {
-                bypassTaskStatusGate: true,
-                signalToken: newToken,
-                currentSpecRound: newRound,
-            });
-        }
-        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);
-            }
-            else if (err instanceof EnsureSessionError && err.partial.handled) {
-                // handleDialogPendingFromRuntime 已 Held + fail task + release partners；跳过 rollback + release，
-                // 否则 boundTask terminal 让 release gate 放行清掉仍卡 dialog 的 pane lock。
-            }
-            else {
-                await this.rollbackSpecReviewTransition(taskId, originalStatus, originalToken, originalRound);
-                await this.releaseAgentForTask(qaId, taskId, 'idle')
-                    .catch(() => undefined);
-            }
-            throw err;
-        }
-        if (!started) {
-            await this.rollbackSpecReviewTransition(taskId, originalStatus, originalToken, originalRound);
-            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: 'spec-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);
-        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。
-        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;
-            }
-            return {
-                devAgentId,
-                qaAgentId: task.qaAgentId,
-                projectId: task.projectId,
-                newToken: createSignalToken(),
-                currentRound: task.specReviewRound ?? 1,
-            };
-        });
-        if (!claim)
-            return null;
-        const { devAgentId, qaAgentId, projectId, newToken, currentRound } = claim;
-        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;
-            });
-            if (!released) {
-                await this.safeEmit({
-                    id: '',
-                    type: 'human.intervention',
-                    timestamp: new Date().toISOString(),
-                    projectId,
-                    agentId: qaAgentId,
-                    taskId,
-                    data: { phase: 'spec-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' });
-        if (!transition) {
-            await this.releaseAgentForTask(devAgentId, taskId, 'idle')
-                .catch(() => undefined);
-            await this.safeEmit({
-                id: '',
-                type: 'human.intervention',
-                timestamp: new Date().toISOString(),
-                projectId,
-                agentId: devAgentId,
-                taskId,
-                data: { phase: 'spec-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,
-                bypassTaskStatusGate: true,
-            });
-        }
-        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);
-            }
-            else if (err instanceof EnsureSessionError && err.partial.handled) {
-                // handleDialogPendingFromRuntime 已 Held + fail task + release partners；跳过 rollback + release。
-            }
-            else {
-                await this.rollbackSpecFixTransition(taskId);
-                await this.releaseAgentForTask(devAgentId, taskId, 'idle')
-                    .catch(() => undefined);
-            }
-            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 this.safeEmit({
-                id: '',
-                type: 'human.intervention',
-                timestamp: new Date().toISOString(),
-                projectId,
-                agentId: devAgentId,
-                taskId,
-                data: { phase: 'spec-fix-resume-failed', devAgentId },
-            });
-            return null;
-        }
-        // Phase 3: set up watcher。
-        await this.armPostDispatchSignalOrHold(taskId, devAgentId, 'spec-fixed', 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) {
         const task = await this.taskStore.get(taskId);
         if (!task)
@@ -5000,7 +4753,7 @@ export class AgentManager {
             resumed = await this.continueSession(taskId, devAgentId, 'code');
         }
         catch (err) {
-            // 同 spec-review/spec-fix：DispatchTerminalError 委托给 failTaskForDispatchError
+            // 同 dispatchServerReviewToQa/dispatchServerFixToDev：DispatchTerminalError 委托给 failTaskForDispatchError
             // （ack_unknown → markAwaitingHuman；其他 reason → release + task failed）。
             if (err instanceof DispatchTerminalError) {
                 await this.failTaskForDispatchError(taskId, 'code', devAgentId, err);
@@ -5038,7 +4791,8 @@ export class AgentManager {
             const task = await this.taskStore.get(taskId);
             if (!task)
                 throw new Error(`dispatchServerReviewToQa: task ${taskId} not found`);
-            if (task.reviewMode !== 'server') {
+            // 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;
@@ -5073,6 +4827,7 @@ export class AgentManager {
                 originalRound: roundField,
                 originalBatchIndex: task.batchIndex,
                 originalBatchTotal: task.batchTotal,
+                originalPhase: task.phase,
             };
         });
         if (!claim)
@@ -5085,6 +4840,9 @@ export class AgentManager {
                 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 }),
@@ -5234,7 +4992,7 @@ export class AgentManager {
             const task = await this.taskStore.get(taskId);
             if (!task)
                 throw new Error(`dispatchServerFixToDev: task ${taskId} not found`);
-            if (task.reviewMode !== 'server') {
+            if (task.reviewMode !== 'server' && task.phase !== 'spec') {
                 throw new Error(`dispatchServerFixToDev: task ${taskId} is not in server review mode`);
             }
             if (!task.agentId)
@@ -5470,24 +5228,34 @@ export class AgentManager {
             return;
         }
         try {
-            await this.injectTextToAgent(qaAgentId, body);
+            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) {
+    async injectTextToAgent(agentId, text, opts = {}) {
         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);
+        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.