baxian 0.0.1 → 0.2.0

package/dist/agent/manager.js

@@ -0,0 +1,3666 @@
+import { createMarkerToken } from './marker-protocol.js';
+import { BRANCH_PREFIX, PHASE_EXPECTED_STATUS, PHASE_REQUIRES_AGENT_BOUND_TO_TASK, TASK_TERMINAL_STATUSES as TERMINAL_STATUSES, } from '../shared/index.js';
+import { AGENT_STORE_NOOP } from '../state/agent-store.js';
+import { PostApproveStore } from '../state/post-approve-store.js';
+import { SkillRegistry } from '../skill/registry.js';
+import { createRunner, LocalRunner, shellQuote } from './runner.js';
+import { TmuxManager, ReplNotReadyError, detectStartupDialog, detectRuntimeMenu, detectReplActiveBusy, hasReplReadyAnchor, hasReplProcTitle, } from './tmux.js';
+import { WorktreeManager } from './worktree.js';
+import { RepoStore, createRepoStoreCache } from './repo-store.js';
+import { PostApproveMarkerWatcher } from './post-approve-marker-watcher.js';
+import { SpecReviewMarkerWatcher } from './spec-review-marker-watcher.js';
+import { buildPromptInline, buildPostMergeCleanupPrompt, PromptSizeError, RequiredSkillsMissingError, MAX_PROMPT_BYTES_ROUTE_LIMIT, } from './prompt.js';
+import { ApiError } from '../errors.js';
+export class EnsureSessionError extends Error {
+    partial;
+    constructor(partial, message) {
+        super(message);
+        this.partial = partial;
+        this.name = 'EnsureSessionError';
+    }
+}
+export class CleanupFailedError extends Error {
+    failures;
+    constructor(message, failures) {
+        super(message);
+        this.failures = failures;
+        this.name = 'CleanupFailedError';
+    }
+}
+export class DispatchTransientError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DispatchTransientError';
+    }
+}
+export class DispatchTerminalError extends Error {
+    reason;
+    replDrained;
+    constructor(reason, message, replDrained = false) {
+        super(message);
+        this.reason = reason;
+        this.replDrained = replDrained;
+        this.name = 'DispatchTerminalError';
+    }
+}
+// shellQuote model/addDirs: spliced into a tmux command line; unquoted values allow injection.
+export function buildLaunchCommand(agent) {
+    const segments = [];
+    switch (agent.runtime) {
+        case 'claude-code':
+            segments.push('env CLAUDE_CODE_NO_FLICKER=1 claude --permission-mode bypassPermissions');
+            break;
+        case 'codex':
+            segments.push('codex --dangerously-bypass-approvals-and-sandbox');
+            break;
+    }
+    if (agent.model) {
+        segments.push(`--model ${shellQuote(agent.model)}`);
+    }
+    if (agent.addDirs && agent.addDirs.length > 0) {
+        for (const dir of agent.addDirs) {
+            segments.push(`--add-dir ${shellQuote(dir)}`);
+        }
+    }
+    return segments.join(' ');
+}
+function agentRuntimeKindFor(agent) {
+    return agent.runtime;
+}
+const DEFAULT_DISPATCH_ACK_TIMEOUT_MS = 30_000;
+const ACTIVE_TASK_STATUSES = new Set(['in_progress', 'review', 'fixing', 'approved']);
+export function canDispatchWithBinding(binding) {
+    return !binding?.taskId && !binding?.creationToken && binding?.status !== 'awaiting_human';
+}
+// 部分 awaiting phase 表示 agent 这一轮 turn 已跑完，绑定是 stale 的——即使 task 不 terminal
+// 也应 release 让 agent 被下一轮 acquire。outcome handler (review.submitted) 走 allowAwaitingHuman 即可。
+//
+// 当前集合为空：先前包含的 'dev-wait-gate-failed-after-qa-started' 和 'dispatch-failed:ack_unknown'
+// 语义都是"QA prompt 已粘贴，可能仍在 pane 中跑"——任何在 outcome 到达前的 release（含 resumeAgent /
+// recover 路径）都可能让第二个 prompt 派进同 pane 与旧 turn 混在一起。outcome handler 通过显式
+// allowAwaitingHuman:true release，gate 单点放行。
+const TURN_COMPLETED_AWAITING_PHASES = new Set();
+// Resume / recover 共用：决定 Held agent 的 binding 是否随状态恢复一起清掉。
+export function shouldReleaseHeldBinding(state, boundTask) {
+    const taskIsTerminal = !!boundTask && TERMINAL_STATUSES.includes(boundTask.status);
+    const turnCompleted = state.awaitingPhase != null && TURN_COMPLETED_AWAITING_PHASES.has(state.awaitingPhase);
+    return !boundTask || taskIsTerminal || turnCompleted;
+}
+// null 表示 context 已无效（换 task / 换 pane），调用方应回退到完整注入。
+// 返回数组（含空数组）则代表当前 REPL session 已有的 skill 名集合，可作 excludeSkills 入参。
+function reuseSkillsIfContextValid(state, taskId, paneId) {
+    const rec = state?.injectedSkills;
+    if (!rec)
+        return null;
+    if (rec.taskId !== taskId || rec.paneId !== paneId)
+        return null;
+    return rec.skills;
+}
+export class AgentManager {
+    config;
+    agentStore;
+    taskStore;
+    lockManager;
+    eventBus;
+    skillRegistry;
+    runnerFactory;
+    repoStoreFactory;
+    repoCache;
+    paneStreamerManager;
+    postApproveStore;
+    postApproveMarkerWatcher;
+    specReviewMarkerWatcher;
+    errorRecordStore;
+    dispatchAckTimeoutMs;
+    taskMutationQueue = Promise.resolve();
+    agentIndex;
+    platformRunner;
+    bootstrapTimeoutsMs;
+    warnedStaleQueueDispatch = new Set();
+    runtimeMenuWatchers = new Map();
+    runtimeMenuPollIntervalMs = 10_000;
+    compactIdleWaitMs = 5 * 60_000;
+    compactIdlePollMs = 2_000;
+    postMergeFetchTimeoutMs = 60_000;
+    postMergeBranchTimeoutMs = 10_000;
+    // taskIds with in-flight manual review — second concurrent POST gets 409.
+    manualReviewInFlight = new Set();
+    // agentIds with in-flight DELETE — 第二个 DELETE 撞 awaiting_human stale-lock takeover 路径会
+    // 把第一个 DELETE 持有的占位也当 stale 接管，导致并发 cleanupRemovedAgentRuntime。
+    deletionInFlight = new Set();
+    constructor(deps) {
+        this.config = deps.config;
+        this.agentStore = deps.agentStore;
+        this.taskStore = deps.taskStore;
+        this.lockManager = deps.lockManager;
+        this.eventBus = deps.eventBus;
+        this.skillRegistry = deps.skillRegistry ?? new SkillRegistry('');
+        this.runnerFactory = deps.runnerFactory;
+        this.repoStoreFactory = deps.repoStoreFactory;
+        this.paneStreamerManager = deps.paneStreamerManager;
+        this.postApproveStore = deps.postApproveStore ?? new PostApproveStore();
+        this.errorRecordStore = deps.errorRecordStore;
+        this.postApproveMarkerWatcher = deps.postApproveMarkerWatcher
+            ?? (deps.paneStreamerManager
+                ? new PostApproveMarkerWatcher({
+                    paneStreamerManager: deps.paneStreamerManager,
+                    eventBus: deps.eventBus,
+                    resolveAgent: (id) => this.getAgentConfig(id),
+                })
+                : undefined);
+        this.specReviewMarkerWatcher = deps.specReviewMarkerWatcher
+            ?? (deps.paneStreamerManager
+                ? new SpecReviewMarkerWatcher({
+                    paneStreamerManager: deps.paneStreamerManager,
+                    eventBus: deps.eventBus,
+                    resolveAgent: (id) => this.getAgentConfig(id),
+                })
+                : undefined);
+        this.dispatchAckTimeoutMs = deps.dispatchAckTimeoutMs ?? DEFAULT_DISPATCH_ACK_TIMEOUT_MS;
+        this.agentIndex = buildAgentIndex(deps.config);
+        this.platformRunner = deps.platformRunner ?? new LocalRunner();
+        this.repoCache = createRepoStoreCache();
+        this.bootstrapTimeoutsMs = {
+            trustDialog: deps.bootstrapTimeoutsMs?.trustDialog ?? 10_000,
+            waitReplReady: deps.bootstrapTimeoutsMs?.waitReplReady ?? 30_000,
+        };
+    }
+    withTaskLock(fn) {
+        const next = this.taskMutationQueue.then(fn);
+        this.taskMutationQueue = next.catch(() => undefined);
+        return next;
+    }
+    async safeEmit(event) {
+        try {
+            await this.eventBus.emit(event);
+        }
+        catch (err) {
+            console.warn(`[AgentManager] safeEmit ${event.type} failed (audit log loss; state machine unaffected):`, err);
+        }
+    }
+    async recordError(input) {
+        if (!this.errorRecordStore)
+            return;
+        try {
+            await this.errorRecordStore.append(input);
+        }
+        catch (err) {
+            console.warn(`[AgentManager] ErrorRecordStore.append failed (${input.operation}/${input.reason}):`, err);
+        }
+    }
+    replaceConfig(validated) {
+        this.config = validated;
+        this.agentIndex = buildAgentIndex(validated);
+    }
+    getAgentConfig(agentId) {
+        return this.agentIndex.get(agentId);
+    }
+    // DELETE phase1 (withConfigLock 内) 先调；返回冲突 id 表示另一 DELETE 已在跑此 agent，caller 应 409。
+    // 成功 claim 后所有出口（含 phase1 reply / phase2/3 完成 / rollback / throw）必须调
+    // releaseDeletionClaim 释放，否则 agent 永久卡在 "delete-in-flight" 状态。
+    tryClaimDeletion(agentIds) {
+        for (const id of agentIds) {
+            if (this.deletionInFlight.has(id))
+                return id;
+        }
+        for (const id of agentIds)
+            this.deletionInFlight.add(id);
+        return null;
+    }
+    releaseDeletionClaim(agentIds) {
+        for (const id of agentIds)
+            this.deletionInFlight.delete(id);
+    }
+    isDeletionInFlight(agentId) {
+        return this.deletionInFlight.has(agentId);
+    }
+    async ensureSession(agentId, mode) {
+        const agent = this.getAgentConfig(agentId);
+        if (!agent) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `Unknown agent: ${agentId}`);
+        }
+        const project = this.getProjectConfig(agent.projectId);
+        if (!project) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `Unknown project: ${agent.projectId}`);
+        }
+        const runner = this.createRunnerFor(agent);
+        const tmux = new TmuxManager(runner);
+        let workdir;
+        try {
+            const resolved = await this.ensureWorkdir(agent, project, runner);
+            workdir = resolved.workdir;
+            if (resolved.repoStore) {
+                await this.agentStore.update(agentId, (existing) => {
+                    if (!existing)
+                        return AGENT_STORE_NOOP;
+                    return {
+                        ...existing,
+                        repoPath: workdir,
+                        updatedAt: new Date().toISOString(),
+                    };
+                });
+            }
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `ensureWorkdir failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        let alive;
+        try {
+            alive = await tmux.hasSession(agentId);
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `tmux probe failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (mode === 'create' && alive) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `tmux session "${agentId}" already exists on host; baxian only manages sessions ` +
+                `it creates itself — kill it manually or pick a different agent id`);
+        }
+        if (alive && (mode === 'runtime' || mode === 'recover')) {
+            return this.adoptOrRestartSession(tmux, agent, agentId, workdir);
+        }
+        return this.buildFreshSession(tmux, agent, agentId, workdir);
+    }
+    async pinRuntimeSessionOptions(tmux, agentId) {
+        await tmux.setOption(agentId, 'prefix', 'C-b');
+        await tmux.setOption(agentId, 'prefix2', 'None');
+        await tmux.setOption(agentId, 'mouse', 'on');
+    }
+    // New sessions start in latest mode; adopted sessions keep their current size owner.
+    async pinFreshSessionOptions(tmux, agentId) {
+        await tmux.setOption(agentId, 'window-size', 'latest');
+        await this.pinRuntimeSessionOptions(tmux, agentId);
+    }
+    async buildFreshSession(tmux, agent, agentId, workdir) {
+        let createdSession = false;
+        try {
+            await tmux.createSession(agentId, workdir);
+            // Mark BEFORE setOption — failure here must trigger caller's rollback.
+            createdSession = true;
+            await tmux.setOption(agentId, '@baxian-agent-id', agentId);
+            await tmux.setOption(agentId, '@baxian-runtime', agent.runtime);
+            await tmux.setOption(agentId, 'allow-passthrough', 'on');
+            await tmux.setOption(agentId, 'set-titles', 'on');
+            await this.pinFreshSessionOptions(tmux, agentId);
+            await tmux.setOption(agentId, 'status-right', '');
+            await tmux.setServerOption('extended-keys', 'on');
+            await tmux.appendServerOptionIfMissing('terminal-features', 'xterm*:extkeys');
+            const paneId = await tmux.getSinglePaneId(agentId);
+            await tmux.sendKeysToPane(paneId, `${buildLaunchCommand(agent)}\n`);
+            await tmux.handleTrustDialog(paneId, agentRuntimeKindFor(agent), {
+                timeoutMs: this.bootstrapTimeoutsMs.trustDialog,
+            });
+            await tmux.waitReplReady(paneId, agentRuntimeKindFor(agent), {
+                timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
+                scrollback: 0,
+            });
+            return { ok: true, createdSession: true, freshRuntime: true, paneId, workdir };
+        }
+        catch (err) {
+            const partial = { createdSession, agentId };
+            if (err instanceof ReplNotReadyError) {
+                partial.lastScreen = err.lastScreen;
+                if (createdSession && detectStartupDialog(err.lastScreen)) {
+                    partial.dialogPending = true;
+                }
+            }
+            throw new EnsureSessionError(partial, `buildFreshSession failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Never throws — failures land in agentStore.
+    async startBootstrapAsync(agentId, creationToken) {
+        const cfgAtStart = this.getAgentConfig(agentId);
+        if (!cfgAtStart) {
+            console.warn(`[bootstrap] ${agentId} not in config at bootstrap start — aborting`);
+            return;
+        }
+        const tryKillOrphanSession = async (reason) => {
+            try {
+                const runner = this.createRunnerFor(cfgAtStart);
+                await new TmuxManager(runner).killSession(agentId);
+            }
+            catch (cleanupErr) {
+                console.warn(`[bootstrap] orphan killSession (${reason}) failed for ${agentId}:`, cleanupErr);
+            }
+        };
+        try {
+            const result = await this.ensureSession(agentId, 'create');
+            let resolvedExisting = null;
+            const now = new Date().toISOString();
+            await this.agentStore.update(agentId, (existing) => {
+                if (!existing || existing.creationToken !== creationToken)
+                    return AGENT_STORE_NOOP;
+                resolvedExisting = existing;
+                return {
+                    ...existing,
+                    paneId: result.paneId,
+                    creationToken: undefined,
+                    updatedAt: now,
+                };
+            });
+            if (!resolvedExisting) {
+                console.warn(`[bootstrap] ${agentId} creationToken mismatch on success — killing orphan session`);
+                await tryKillOrphanSession('post-success token mismatch');
+                return;
+            }
+            await this.safeEmit({
+                id: '',
+                type: 'agent.bootstrap_succeeded',
+                timestamp: now,
+                projectId: resolvedExisting.projectId,
+                agentId,
+                data: { paneId: result.paneId, phase: 'session' },
+            });
+            return;
+        }
+        catch (err) {
+            if (err instanceof EnsureSessionError && err.partial.dialogPending) {
+                if (err.partial.createdSession) {
+                    const fresh = await this.agentStore.get(agentId);
+                    if (!fresh || fresh.creationToken !== creationToken) {
+                        console.warn(`[bootstrap] ${agentId} dialog-path token mismatch — killing orphan session`);
+                        await tryKillOrphanSession('dialog-path token mismatch');
+                        return;
+                    }
+                }
+                await this.markDialogPending(agentId, creationToken);
+                void this.slowPollDialogPending(agentId, creationToken).catch((pollErr) => {
+                    console.warn(`[bootstrap] slowPoll for ${agentId} crashed:`, pollErr);
+                });
+                return;
+            }
+            if (err instanceof EnsureSessionError && err.partial.createdSession) {
+                await tryKillOrphanSession('hard-failure rollback');
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            await this.markBootstrapFailed(agentId, creationToken, message);
+        }
+    }
+    async markDialogPending(agentId, creationToken, opts = {}) {
+        const existing = await this.agentStore.get(agentId);
+        if (!existing)
+            return;
+        // runtime path snapshot 全空时直接拒绝——既无 paneId 也无 taskId 作 generation 证据，
+        // 旧 callback 通过 guard 污染同样 idle 的新 agent 的风险无法排除。
+        if (opts.runtimePath && opts.expectedPaneId === undefined && opts.expectedTaskId === undefined) {
+            console.warn(`[AgentManager] markDialogPending runtime path: refusing to write without paneId/taskId snapshot (no generation guard available for ${agentId})`);
+            return;
+        }
+        // Pre-check（early exit；下面 closure 内会再 atomic 校验一次）
+        if (opts.runtimePath) {
+            if (existing.creationToken !== undefined)
+                return;
+            if (opts.expectedPaneId !== undefined && existing.paneId !== opts.expectedPaneId)
+                return;
+            if (existing.taskId !== opts.expectedTaskId)
+                return;
+        }
+        else if (creationToken !== undefined && existing.creationToken !== creationToken) {
+            return;
+        }
+        const cfg = this.getAgentConfig(agentId);
+        let paneId = existing.paneId;
+        if (cfg && !paneId) {
+            try {
+                const runner = this.createRunnerFor(cfg);
+                paneId = await new TmuxManager(runner).getSinglePaneId(agentId);
+            }
+            catch {
+                // best-effort; slowPoll skips iterations without paneId
+            }
+        }
+        // 原子写入：guard + paneId + awaiting fields 一次性，避免 get→update 中间 race。
+        const now = new Date().toISOString();
+        let wrote = false;
+        let projectIdForEmit = '';
+        let taskIdForEmit;
+        await this.agentStore.update(agentId, (fresh) => {
+            if (!fresh)
+                return AGENT_STORE_NOOP;
+            if (opts.runtimePath) {
+                if (fresh.creationToken !== undefined)
+                    return AGENT_STORE_NOOP;
+                if (opts.expectedPaneId !== undefined && fresh.paneId !== opts.expectedPaneId)
+                    return AGENT_STORE_NOOP;
+                if (fresh.taskId !== opts.expectedTaskId)
+                    return AGENT_STORE_NOOP;
+            }
+            else if (creationToken !== undefined && fresh.creationToken !== creationToken) {
+                return AGENT_STORE_NOOP;
+            }
+            projectIdForEmit = fresh.projectId;
+            taskIdForEmit = fresh.taskId;
+            wrote = true;
+            return {
+                ...fresh,
+                ...(paneId !== undefined ? { paneId } : {}),
+                status: 'awaiting_human',
+                awaitingPhase: 'agent_dialog_pending',
+                awaitingReason: 'Agent REPL launched but blocked on a startup dialog (e.g. CLI update notice). Operator should attach via web terminal and dismiss it; baxian will auto-detect ready and resume.',
+                awaitingSince: now,
+                updatedAt: now,
+            };
+        });
+        if (!wrote)
+            return;
+        await this.safeEmit({
+            id: '',
+            type: 'human.intervention',
+            timestamp: now,
+            projectId: projectIdForEmit,
+            agentId,
+            ...(taskIdForEmit ? { taskId: taskIdForEmit } : {}),
+            data: {
+                phase: 'agent_dialog_pending',
+                reason: 'Agent REPL launched but blocked on a startup dialog (e.g. CLI update notice). Operator should attach via web terminal and dismiss it; baxian will auto-detect ready and resume.',
+            },
+        });
+    }
+    async markBootstrapFailed(agentId, creationToken, errorMessage) {
+        const existing = await this.agentStore.get(agentId);
+        if (!existing)
+            return;
+        // generational guard: token mismatch means a newer create-recreate already won.
+        if (creationToken !== undefined && existing.creationToken !== creationToken)
+            return;
+        const now = new Date().toISOString();
+        await this.agentStore.update(agentId, (fresh) => {
+            if (!fresh)
+                return AGENT_STORE_NOOP;
+            if (creationToken !== undefined && fresh.creationToken !== creationToken)
+                return AGENT_STORE_NOOP;
+            return {
+                ...fresh,
+                paneId: undefined,
+                creationToken: undefined,
+                updatedAt: now,
+            };
+        });
+        await this.safeEmit({
+            id: '',
+            type: 'agent.bootstrap_failed',
+            timestamp: now,
+            projectId: existing.projectId,
+            agentId,
+            data: { error: errorMessage, phase: 'session' },
+        });
+    }
+    // Returns true when handled — caller skips its own kill cleanup.
+    // expectedFromStatuses: fail-task transition 的允许 fromStatus 集合。caller (startSession/continueSession)
+    // 已根据 phase + opts.dialogFailFromStatuses 计算好；并发 outcome 已把 task 推到此集合外的状态时
+    // transitionTaskStatus skip → 不覆盖已接受的 outcome。未传时退化为 [...ACTIVE_TASK_STATUSES] (retry
+    // endpoint 等无 phase 路径，且这些路径不绑 task，fail task 分支本就不进入)。
+    async handleDialogPendingFromRuntime(agentId, err, opts = {}) {
+        if (!(err instanceof EnsureSessionError) || !err.partial.dialogPending) {
+            return false;
+        }
+        let state = await this.agentStore.get(agentId);
+        if (!state)
+            return false;
+        // retry path（state.paneId 未写入但 ensureSession 刚 createSession）：从 tmux 取 paneId
+        // 写入 state 作 generation 证据，否则 markDialogPending 的 snapshot 全空 refuse 会 no-op
+        // → return true 让 caller 释放锁 202 返回 → agent 留 idle 但 tmux dialog 在跑 → 下一个
+        // dispatch 撞进 dialog pane。tmux 探 paneId 失败时返回 false，让 caller 走 killSession 回滚。
+        if (state.paneId === undefined && err.partial.createdSession) {
+            const cfg = this.getAgentConfig(agentId);
+            if (!cfg)
+                return false;
+            let discoveredPaneId;
+            try {
+                const runner = this.createRunnerFor(cfg);
+                discoveredPaneId = await new TmuxManager(runner).getSinglePaneId(agentId);
+            }
+            catch (probeErr) {
+                console.warn(`[AgentManager] handleDialogPendingFromRuntime: tmux probe paneId failed for ${agentId}:`, probeErr);
+                return false;
+            }
+            if (!discoveredPaneId)
+                return false;
+            const probeNow = new Date().toISOString();
+            // 撤销 updatedAt guard（round-13 codex review）：updatedAt 太宽，正常 background updates
+            // (repoPath refresh / poller bump 等) 也会触发假阳性让合法 retry dialog 路径误拒。
+            // race ("DELETE+recreate 后旧回调写新 agent") 在持锁路径下是 theoretical (retry endpoint 持锁
+            // 全程到 handleDialogPendingFromRuntime 返回；startSession/continueSession 由 acquireAgentForTask
+            // 持锁)，且 `fresh.paneId !== undefined` 已挡住新 agent 已写 paneId 的情况。
+            await this.agentStore.update(agentId, (fresh) => {
+                if (!fresh)
+                    return AGENT_STORE_NOOP;
+                if (fresh.paneId !== undefined)
+                    return AGENT_STORE_NOOP;
+                return { ...fresh, paneId: discoveredPaneId, updatedAt: probeNow };
+            });
+            state = await this.agentStore.get(agentId);
+            if (!state?.paneId)
+                return false;
+        }
+        if (state.paneId === undefined && state.taskId === undefined) {
+            console.warn(`[AgentManager] handleDialogPendingFromRuntime: ${agentId} has no paneId/taskId snapshot (no generation guard); refusing — caller should rollback`);
+            return false;
+        }
+        // runtime path: 显式 guard，不传 state.creationToken（race window 内可能已是新 generation）。
+        // 同时 snapshot paneId / taskId 作 atomic check，挡住"DELETE+recreate + 新 bootstrap 完成"的 race。
+        await this.markDialogPending(agentId, undefined, {
+            runtimePath: true,
+            ...(state.paneId !== undefined ? { expectedPaneId: state.paneId } : {}),
+            expectedTaskId: state.taskId,
+        });
+        // runtime path (agent 已绑 active task + 无 creationToken)：dialog 在 ensureSession 阶段抛错，
+        // prompt 还没 inject——直接 fail task 让 UI Retry 通路打开（无工作丢失）。
+        // 若不 fail：task 卡 in_progress、agent Held、operator Resume 后仍无人重发 prompt（owner 评审 #6
+        // 指出 transitionToCodePhase 会死锁）。task fail 后 Resume / recover 走 terminal-release 路径。
+        // 用 transitionTaskStatus（内含 withTaskLock + fromStatus guard）避免与 Cancel / merge /
+        // review outcome 等并发 mutation race，否则 stale 'failed' 会覆盖已经到达的 terminal 状态。
+        if (state.taskId && state.creationToken === undefined) {
+            // fromStatus 来自 caller 显式计算：startSession/continueSession 用 opts.dialogFailFromStatuses ??
+            // PHASE_EXPECTED_STATUS[phase]，dispatchReviewToQa 走 bypassTaskStatusGate 时显式传 [taskStatusAtClaim]
+            // (manual review 入口可能是 approved/fixing/in_progress，但 phase='review' 的 default 只接受 'review' →
+            // 不传就 skip → task 卡 active 死锁，见 owner round-15 评审)。
+            const expectedFromStatuses = opts.expectedFromStatuses ?? [...ACTIVE_TASK_STATUSES];
+            const transitioned = await this.transitionTaskStatus(state.taskId, 'failed', { fromStatus: expectedFromStatuses });
+            if (transitioned) {
+                await this.safeEmit({
+                    id: '',
+                    type: 'task.updated',
+                    timestamp: new Date().toISOString(),
+                    projectId: transitioned.task.projectId,
+                    taskId: state.taskId,
+                    data: { status: 'failed', reason: 'agent_dialog_pending_runtime' },
+                });
+                // 同步释放 partner agent 的 binding。task 已 terminal 不会再走 cancel 清理，否则 partner
+                // 永远指向 terminal task → retryTask 走 validateTaskDispatch 看 dev 仍 bound → 409。
+                await this.releasePartnersAndDrain(agentId, [state.taskId], [transitioned.task.projectId]);
+            }
+        }
+        // 通知 caller (startSession / continueSession catch) 不要再调 releaseAgentForTask 清理——
+        // task 已 terminal + agent Held 时，shouldReleaseHeldBinding 第一条规则会放行 release，
+        // 把仍卡 dialog 的 pane 解锁让下个 dispatch 派进来。set partial.handled 让 caller 跳过 release。
+        err.partial.handled = true;
+        // slowPoll 是 fire-and-forget，在 caller 释放锁后继续运行。runtime path 下 creationToken=undefined
+        // 不足以挡 DELETE+recreate 后旧 poll 撞新 agent（新 agent ack_unknown/dev-wait-gate-failed 时
+        // creationToken 也 undefined）→ 旧 poll 会把新 agent phase 覆为 resolved_runtime → Resume 不再拒。
+        // 传入当前 paneId/taskId snapshot 作 generation 证据，atomic update 校验匹配才写。
+        const snapshotPaneId = state.paneId;
+        const snapshotTaskId = state.taskId;
+        void this.slowPollDialogPending(agentId, state.creationToken, {
+            ...(snapshotPaneId !== undefined ? { expectedPaneId: snapshotPaneId } : {}),
+            expectedTaskId: snapshotTaskId,
+        }).catch((pollErr) => {
+            console.warn(`[runtime] slowPoll for ${agentId} crashed:`, pollErr);
+        });
+        return true;
+    }
+    async waitForBootstrapSettled(agentId, timeoutMs = 5_000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const state = await this.agentStore.get(agentId);
+            if (!state)
+                return;
+            if (!state.creationToken)
+                return;
+            await new Promise(r => setTimeout(r, 25));
+        }
+        throw new Error(`waitForBootstrapSettled(${agentId}) timed out after ${timeoutMs}ms`);
+    }
+    // 无硬上限——配合 markDialogPending 的 human.intervention emit 让 operator 来；
+    // DELETE/recreate 通过 creationToken 失配让循环自然退出。
+    // runtime path（creationToken=undefined）下旧 poll 会撞 DELETE+recreate 后的新 agent（也无 token），
+    // 需要 opts.expectedPaneId/expectedTaskId 作 generation 证据，loop top + atomic update 双重校验。
+    async slowPollDialogPending(agentId, creationToken, opts = {}) {
+        const POLL_INTERVAL_MS = 5_000;
+        const cfg = this.getAgentConfig(agentId);
+        if (!cfg)
+            return;
+        const runner = this.createRunnerFor(cfg);
+        const tmux = new TmuxManager(runner);
+        const runtime = agentRuntimeKindFor(cfg);
+        const generationMismatch = (state) => {
+            if (state.creationToken !== creationToken)
+                return true;
+            // runtime path: 校验 paneId/taskId snapshot 匹配
+            if (creationToken === undefined) {
+                if (opts.expectedPaneId !== undefined && state.paneId !== opts.expectedPaneId)
+                    return true;
+                if (state.taskId !== opts.expectedTaskId)
+                    return true;
+            }
+            return false;
+        };
+        while (true) {
+            await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+            const state = await this.agentStore.get(agentId);
+            if (!state)
+                return;
+            if (generationMismatch(state))
+                return;
+            let paneId = state.paneId;
+            if (!paneId) {
+                try {
+                    paneId = await tmux.getSinglePaneId(agentId);
+                    const discoveredPaneId = paneId;
+                    await this.agentStore.update(agentId, (s) => {
+                        if (!s)
+                            return AGENT_STORE_NOOP;
+                        if (generationMismatch(s))
+                            return AGENT_STORE_NOOP;
+                        return {
+                            ...s,
+                            paneId: discoveredPaneId,
+                            updatedAt: new Date().toISOString(),
+                        };
+                    });
+                }
+                catch {
+                    continue;
+                }
+            }
+            try {
+                await tmux.waitReplReady(paneId, runtime, {
+                    timeoutMs: 1_000,
+                    intervalMs: 200,
+                    scrollback: 0,
+                });
+            }
+            catch {
+                continue;
+            }
+            const preFresh = await this.agentStore.get(agentId);
+            if (!preFresh)
+                return;
+            if (generationMismatch(preFresh))
+                return;
+            const now = new Date().toISOString();
+            let projectIdForEmit = '';
+            let wrote = false;
+            // bootstrap path: creationToken set，agent 未绑 task；ready 后自动清 Held（无需 operator）。
+            // runtime path: creationToken undefined，agent 仍绑 task（已被 handleDialogPendingFromRuntime
+            // 推 failed）+ lock 在；ready 后切到 'agent_dialog_resolved_runtime' phase，让 resumeAgent 放行
+            // 让 operator 显式确认。仍保留 awaiting_human + lock 防止"dialog ready 自动派下一 task 撞 pane"。
+            const isBootstrapPath = creationToken !== undefined;
+            await this.agentStore.update(agentId, (fresh) => {
+                if (!fresh)
+                    return AGENT_STORE_NOOP;
+                if (generationMismatch(fresh))
+                    return AGENT_STORE_NOOP;
+                projectIdForEmit = fresh.projectId;
+                wrote = true;
+                if (isBootstrapPath) {
+                    return {
+                        ...fresh,
+                        creationToken: undefined,
+                        status: 'ok',
+                        awaitingPhase: undefined,
+                        awaitingReason: undefined,
+                        awaitingSince: undefined,
+                        updatedAt: now,
+                    };
+                }
+                return {
+                    ...fresh,
+                    awaitingPhase: 'agent_dialog_resolved_runtime',
+                    awaitingReason: 'Runtime dialog resolved; agent REPL ready. Click Resume to release the binding and let baxian pick the next task.',
+                    updatedAt: now,
+                };
+            });
+            if (!wrote)
+                return;
+            if (isBootstrapPath) {
+                await this.safeEmit({
+                    id: '',
+                    type: 'agent.bootstrap_succeeded',
+                    timestamp: now,
+                    projectId: projectIdForEmit,
+                    agentId,
+                    data: { paneId, phase: 'session_dialog_resolved' },
+                });
+            }
+            else {
+                // runtime dialog 解决，phase 切到 resolved_runtime；emit 通知 operator 现在可以 Resume。
+                await this.safeEmit({
+                    id: '',
+                    type: 'human.intervention',
+                    timestamp: now,
+                    projectId: projectIdForEmit,
+                    agentId,
+                    data: {
+                        phase: 'agent_dialog_resolved_runtime',
+                        note: 'Runtime dialog resolved; agent REPL ready. Click Resume to continue.',
+                    },
+                });
+            }
+            return;
+        }
+    }
+    // Idempotent; self-exits when taskId clears, so callers never need a paired stop.
+    startRuntimeMenuWatch(agentId) {
+        if (this.runtimeMenuWatchers.has(agentId))
+            return;
+        const controller = new AbortController();
+        this.runtimeMenuWatchers.set(agentId, controller);
+        void this.runtimeMenuWatchLoop(agentId, controller.signal)
+            .catch((err) => {
+            console.warn(`[runtimeMenuWatch] ${agentId} loop crashed:`, err);
+        })
+            .finally(() => {
+            const current = this.runtimeMenuWatchers.get(agentId);
+            if (current === controller)
+                this.runtimeMenuWatchers.delete(agentId);
+        });
+    }
+    stopRuntimeMenuWatch(agentId) {
+        const c = this.runtimeMenuWatchers.get(agentId);
+        if (c)
+            c.abort();
+    }
+    async runtimeMenuWatchLoop(agentId, signal) {
+        const cfg = this.getAgentConfig(agentId);
+        if (!cfg)
+            return;
+        const tmux = new TmuxManager(this.createRunnerFor(cfg));
+        let pendingMenu = false;
+        while (!signal.aborted) {
+            await this.sleep(this.runtimeMenuPollIntervalMs, signal);
+            if (signal.aborted)
+                return;
+            const state = await this.agentStore.get(agentId);
+            if (!state)
+                return;
+            if (!state.taskId) {
+                return;
+            }
+            if (!state.paneId)
+                continue;
+            let stripped;
+            try {
+                stripped = await tmux.capturePaneById(state.paneId, { ansi: false, scrollback: 0 });
+            }
+            catch {
+                continue;
+            }
+            // Re-fetch after the async capture; release/reassign may have rewritten state.
+            const fresh = await this.agentStore.get(agentId);
+            if (!fresh)
+                return;
+            if (!fresh.taskId) {
+                return;
+            }
+            if (fresh.taskId !== state.taskId ||
+                fresh.paneId !== state.paneId) {
+                continue;
+            }
+            const onMenu = detectRuntimeMenu(stripped);
+            if (onMenu && !pendingMenu) {
+                pendingMenu = true;
+                const now = new Date().toISOString();
+                await this.safeEmit({
+                    id: '',
+                    type: 'human.intervention',
+                    timestamp: now,
+                    projectId: fresh.projectId,
+                    agentId,
+                    taskId: fresh.taskId,
+                    data: {
+                        phase: 'agent_runtime_menu_pending',
+                        note: 'Agent paused on an interactive menu mid-task. Attach via web terminal and respond; baxian will auto-clear once the menu closes.',
+                    },
+                });
+            }
+            else if (!onMenu && pendingMenu) {
+                pendingMenu = false;
+            }
+        }
+    }
+    sleep(ms, signal) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                signal.removeEventListener('abort', onAbort);
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    async adoptOrRestartSession(tmux, agent, agentId, workdir) {
+        let marker;
+        try {
+            marker = await tmux.getOption(agentId, '@baxian-agent-id');
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `getOption(@baxian-agent-id) failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (marker !== agentId) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `tmux session "${agentId}" exists but @baxian-agent-id marker mismatch ` +
+                `(got "${marker ?? 'null'}"); baxian will not adopt foreign session — operator must intervene`);
+        }
+        try {
+            await this.pinRuntimeSessionOptions(tmux, agentId);
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `pinRuntimeSessionOptions failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        let paneId;
+        try {
+            paneId = await tmux.getSinglePaneId(agentId);
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `getSinglePaneId failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const runtime = agentRuntimeKindFor(agent);
+        let state;
+        try {
+            state = await tmux.classifyPaneForAdopt(paneId, runtime);
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `classifyPaneForAdopt failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        switch (state.kind) {
+            case 'live-runtime':
+                // 复用既有 REPL，上下文未中断——dedup 仍可沿用。
+                return { ok: true, createdSession: false, freshRuntime: false, paneId, workdir };
+            case 'startup-dialog':
+                throw new EnsureSessionError({
+                    createdSession: false,
+                    agentId,
+                    dialogPending: true,
+                    lastScreen: state.lastScreen,
+                }, `adoptOrRestartSession: REPL blocked on startup dialog`);
+            case 'other':
+                // Refuse send-keys — would land as input inside vim/make/etc instead of spawning REPL.
+                throw new EnsureSessionError({ createdSession: false, agentId }, `pane foreground "${state.paneCurrentCommand}" is neither runtime ` +
+                    `(${runtime}) nor shell; refusing to send launch keys — operator ` +
+                    `must reset the pane manually`);
+            case 'trust-dialog':
+                try {
+                    await tmux.handleTrustDialog(paneId, runtime, {
+                        timeoutMs: this.bootstrapTimeoutsMs.trustDialog,
+                    });
+                    await tmux.waitReplReady(paneId, runtime, {
+                        timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
+                        // scrollback>0 risks matching a stale ready anchor from before trust prompt.
+                        scrollback: 0,
+                    });
+                    // 信任弹窗刚被答完，REPL 从启动态进入可用——上下文是新的。
+                    return { ok: true, createdSession: false, freshRuntime: true, paneId, workdir };
+                }
+                catch (trustErr) {
+                    if (trustErr instanceof ReplNotReadyError && detectStartupDialog(trustErr.lastScreen)) {
+                        throw new EnsureSessionError({
+                            createdSession: false,
+                            agentId,
+                            dialogPending: true,
+                            lastScreen: trustErr.lastScreen,
+                        }, `adoptOrRestartSession: REPL blocked on startup dialog after trust auto-answer`);
+                    }
+                    throw new EnsureSessionError({ createdSession: false, agentId }, `adoptOrRestartSession: trust dialog handling failed: ` +
+                        `${trustErr instanceof Error ? trustErr.message : String(trustErr)}`);
+                }
+            case 'shell':
+                break;
+        }
+        try {
+            await tmux.sendKeysToPane(paneId, `${buildLaunchCommand(agent)}\n`);
+            await tmux.handleTrustDialog(paneId, runtime, {
+                timeoutMs: this.bootstrapTimeoutsMs.trustDialog,
+            });
+            await tmux.waitReplReady(paneId, runtime, {
+                timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
+                scrollback: 0,
+            });
+            // shell 路径：在原 pane 里重新启动了 REPL，新进程没有旧 prompt 上下文。
+            return { ok: true, createdSession: false, freshRuntime: true, paneId, workdir };
+        }
+        catch (relErr) {
+            if (relErr instanceof ReplNotReadyError && detectStartupDialog(relErr.lastScreen)) {
+                throw new EnsureSessionError({
+                    createdSession: false,
+                    agentId,
+                    dialogPending: true,
+                    lastScreen: relErr.lastScreen,
+                }, `adoptOrRestartSession: REPL relaunch blocked on startup dialog`);
+            }
+            throw new EnsureSessionError({ createdSession: false, agentId }, `REPL relaunch failed: ${relErr instanceof Error ? relErr.message : String(relErr)}`);
+        }
+    }
+    async acquireAgentForTask(agentId, taskId, phase) {
+        const cfg = this.getAgentConfig(agentId);
+        if (!cfg)
+            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 sameTaskReentry = state?.taskId === taskId &&
+            !state.creationToken &&
+            state.status !== 'awaiting_human' &&
+            reentryPhases.has(phase);
+        const reuseLock = sameTaskLocked && reentryPhases.has(phase);
+        if (!sameTaskReentry && !canDispatchWithBinding(state)) {
+            return false;
+        }
+        if (!reuseLock) {
+            const ok = await this.lockManager.acquire(agentId);
+            if (!ok)
+                return false;
+        }
+        const now = new Date().toISOString();
+        await this.agentStore.update(agentId, (existing) => ({
+            ...(existing ?? { id: agentId, projectId: cfg.projectId, updatedAt: now }),
+            id: agentId,
+            projectId: cfg.projectId,
+            taskId,
+            updatedAt: now,
+        }));
+        return true;
+    }
+    // waiting: dev keeps lock across review/fix. idle: terminal release.
+    // 纯状态更新——REPL 是否 ready 不在此处守门，dispatch 路径自己处理就绪问题。
+    // awaiting_human 状态拒释：避免上游 catch（如 EnsureSessionError(dialogPending) 的 generic
+    // fallback）撕掉 markAwaitingHuman 已标的 await 标记。resumeAgent 用 allowAwaitingHuman 接管。
+    async releaseAgentForTask(agentId, expectedTaskId, mode, opts = {}) {
+        return this.withTaskLock(async () => {
+            const state = await this.agentStore.get(agentId);
+            if (!state)
+                return false;
+            if (state.taskId !== expectedTaskId) {
+                console.warn(`[AgentManager] releaseAgentForTask: agent ${agentId} taskId mismatch ` +
+                    `(expected ${expectedTaskId}, got ${state.taskId}); skipping`);
+                return false;
+            }
+            const boundTask = await this.taskStore.get(expectedTaskId);
+            if (state.status === 'awaiting_human' && !opts.allowAwaitingHuman) {
+                // gate 例外：bound task 已 terminal / turn-completed phase 都属于正常 cleanup 路径，
+                // 必须能清绑定，否则 stale binding 永久指向终态 task → 后续 acquire 全卡。
+                // shouldReleaseHeldBinding 和 Resume 共享同一规则。
+                if (!shouldReleaseHeldBinding(state, boundTask)) {
+                    console.warn(`[AgentManager] releaseAgentForTask: agent ${agentId} is awaiting_human (${state.awaitingPhase}); refusing to release`);
+                    return false;
+                }
+            }
+            if (mode === 'waiting' && (!boundTask || !ACTIVE_TASK_STATUSES.has(boundTask.status))) {
+                console.warn(`[AgentManager] releaseAgentForTask: task ${expectedTaskId} is not active; skipping waiting transition`);
+                return false;
+            }
+            const cfg = this.getAgentConfig(agentId);
+            if (!cfg)
+                return false;
+            const now = new Date().toISOString();
+            if (mode === 'waiting') {
+                await this.agentStore.update(agentId, (latest) => {
+                    if (!latest)
+                        return AGENT_STORE_NOOP;
+                    // clearAwaitingHuman: restart-repl/retry 显式 operator op 已确认 REPL 重启，前面的
+                    // ack_unknown/dialog_pending Held 不再成立——清掉 awaiting_human 字段让 agent 可派遣。
+                    if (opts.clearAwaitingHuman && latest.status === 'awaiting_human') {
+                        const cleared = {
+                            id: latest.id,
+                            projectId: latest.projectId,
+                            updatedAt: now,
+                            ...(latest.taskId !== undefined ? { taskId: latest.taskId } : {}),
+                            ...(latest.paneId !== undefined ? { paneId: latest.paneId } : {}),
+                            ...(latest.repoPath !== undefined ? { repoPath: latest.repoPath } : {}),
+                            ...(latest.worktreePath !== undefined ? { worktreePath: latest.worktreePath } : {}),
+                            ...(latest.startedAt !== undefined ? { startedAt: latest.startedAt } : {}),
+                            ...(latest.creationToken !== undefined ? { creationToken: latest.creationToken } : {}),
+                        };
+                        return cleared;
+                    }
+                    return {
+                        ...latest,
+                        updatedAt: now,
+                    };
+                });
+                return true;
+            }
+            if (state.worktreePath) {
+                const cleanupDir = this.resolveWorkdir(cfg, state);
+                if (cleanupDir) {
+                    const runner = this.createRunnerFor(cfg);
+                    const worktree = new WorktreeManager(runner);
+                    try {
+                        await worktree.remove(cleanupDir, state.worktreePath);
+                    }
+                    catch (err) {
+                        console.warn(`[AgentManager] releaseAgentForTask worktree.remove failed for ${state.worktreePath}:`, err);
+                    }
+                }
+            }
+            await this.agentStore.update(agentId, (existing) => {
+                if (!existing)
+                    return AGENT_STORE_NOOP;
+                if (existing.taskId !== expectedTaskId)
+                    return AGENT_STORE_NOOP;
+                return {
+                    id: existing.id,
+                    projectId: existing.projectId,
+                    ...(existing.repoPath !== undefined ? { repoPath: existing.repoPath } : {}),
+                    ...(existing.paneId !== undefined ? { paneId: existing.paneId } : {}),
+                    ...(existing.creationToken !== undefined ? { creationToken: existing.creationToken } : {}),
+                    updatedAt: now,
+                };
+            });
+            await this.lockManager.release(agentId);
+            return true;
+        });
+    }
+    // baxian 把 agent 标为"自动调度走不通，等 operator 显式 resume"。
+    // 唯一禁区入口：cancel C-c 失败 / dispatch ack_unknown / dialog 卡住等场景。
+    // 保留绑定 + 锁，靠 canDispatchWithBinding 的 status 检查拦住自动派遣。
+    // generation guard 防 DELETE+recreate race：
+    //   - expectedCreationToken: 'tok' → store 当前 token 必须等于 'tok'
+    //   - expectedCreationToken: null   → store 当前必须仍 *无* token（runtime path 用）
+    //   - 不传                         → 不校验 generation
+    async markAwaitingHuman(agentId, phase, reason, opts = {}) {
+        const now = new Date().toISOString();
+        let projectId = '';
+        let taskId;
+        let wrote = false;
+        await this.agentStore.update(agentId, (existing) => {
+            if (!existing)
+                return AGENT_STORE_NOOP;
+            if (opts.expectedCreationToken !== undefined) {
+                const expected = opts.expectedCreationToken; // string | null
+                const actual = existing.creationToken ?? null;
+                if (actual !== expected)
+                    return AGENT_STORE_NOOP;
+            }
+            // taskId guard：迟到 mark 撞已 release+reassign 的 binding 时 noop
+            // (caller 观察到 expectedTaskId 时 binding 还是它，update 时已变 = race lost)。
+            if (opts.expectedTaskId !== undefined) {
+                const expectedTask = opts.expectedTaskId; // string | null
+                const actualTask = existing.taskId ?? null;
+                if (actualTask !== expectedTask)
+                    return AGENT_STORE_NOOP;
+            }
+            projectId = existing.projectId;
+            taskId = existing.taskId;
+            wrote = true;
+            return {
+                ...existing,
+                status: 'awaiting_human',
+                awaitingPhase: phase,
+                awaitingReason: reason,
+                awaitingSince: now,
+                updatedAt: now,
+            };
+        });
+        if (!wrote)
+            return;
+        await this.safeEmit({
+            id: '',
+            type: 'human.intervention',
+            timestamp: now,
+            projectId,
+            agentId,
+            ...(taskId ? { taskId } : {}),
+            data: {
+                phase,
+                reason,
+            },
+        });
+    }
+    // dispatch catch helper：caller 调 startSession/continueSession 抛 DispatchTerminalError
+    // 时统一区分 ack_unknown vs 其他 reason。返回 true 表示已 markAwaitingHuman（caller
+    // 应跳过 release / rollback），返回 false 表示其他错误（caller 走常规清理）。
+    // expectedTaskId: caller 当时观察到的 binding；mark 在 lock 释放后才执行的话，binding 可能
+    // 已被 outcome/cancel release 给新任务，传 taskId 用作 atomic guard 避免污染无关 binding。
+    async markAwaitingIfAckUnknown(agentId, err, expectedTaskId) {
+        if (err instanceof DispatchTerminalError && err.reason === 'ack_unknown') {
+            await this.markAwaitingHuman(agentId, `dispatch-failed:${err.reason}`, `${err.message}. Prompt may still be running in the pane; verify before resuming.`, { expectedTaskId });
+            return true;
+        }
+        return false;
+    }
+    // operator 显式恢复 awaiting_human 的 agent。
+    // 如果 taskId 指向已 terminal 的 task，连带清掉绑定 + 锁——回归 idle 可派遣。
+    // 如果 taskId 指向仍 active 的 task（罕见，比如 dialog_pending 期间 task 没 fail），保留绑定。
+    async resumeAgent(agentId) {
+        // drainQueue 内部对每个 pending task 走 withTaskLock —— 不能在 outer withTaskLock 内调，
+        // 否则形成等待环。捕获 projectId 出 lock 后再 drain（同 cancelTask 模式）。
+        let projectIdToDrain;
+        const result = await this.withTaskLock(async () => {
+            const state = await this.agentStore.get(agentId);
+            if (!state)
+                return { resumed: false, releasedBinding: false };
+            if (state.status !== 'awaiting_human') {
+                return { resumed: false, releasedBinding: false };
+            }
+            // creationToken 仍 set = bootstrap dialog 仍未解决。Resume 不能让它"继续"——
+            // dialog 在 pane 里需要 operator 通过 web terminal 处理，slowPoll 解决后自动清状态。
+            // 如果 operator 想放弃这个 agent，应该走 DELETE 路径。
+            if (state.creationToken) {
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} still has creationToken (bootstrap dialog unresolved); refusing Resume — operator should resolve dialog via web terminal or DELETE the agent.`);
+                return { resumed: false, releasedBinding: false };
+            }
+            const boundTask = state.taskId ? await this.taskStore.get(state.taskId) : null;
+            // "prompt 可能仍在 pane 中跑"类 phase + bound task 仍 active 时 refuse：Resume 让
+            // shouldReleaseHeldBinding 放行清 binding 后 drainQueue 会把第二个 prompt 派进同 pane
+            // 与旧 turn 混在一起。outcome 到达时 review.submitted handler 通过 allowAwaitingHuman:true
+            // 显式 release；这里不必再走 Resume。task terminal/missing 时则放行 — failTaskForDispatchError
+            // 的 ack_unknown 分支会把 task 推 failed 后保留 Held，此时唯一恢复路径就是 Resume。
+            const PROMPT_MAYBE_RUNNING_PHASES = new Set([
+                'dispatch-failed:ack_unknown',
+                'dev-wait-gate-failed-after-qa-started',
+            ]);
+            if (state.awaitingPhase != null
+                && PROMPT_MAYBE_RUNNING_PHASES.has(state.awaitingPhase)
+                && boundTask && ACTIVE_TASK_STATUSES.has(boundTask.status)) {
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} ${state.awaitingPhase} with active task ${state.taskId} — prompt may still be running; refusing Resume until outcome arrives or operator cancels the task / deletes the agent.`);
+                return { resumed: false, releasedBinding: false };
+            }
+            // agent_dialog_pending: pane 仍卡 startup dialog，REPL 未 ready。Resume 让
+            // shouldReleaseHeldBinding 看 task terminal/missing 放行后会清 binding/lock 并 drainQueue
+            // 把新 prompt 派进仍卡 dialog 的 pane。dialog 的恢复路径只能是 operator 通过 web terminal
+            // dismiss → slowPollDialogPending 转 phase 到 agent_dialog_resolved_runtime（Resume 放行）
+            // 或 bootstrap path 直接清 Held → status='ok'，或 DELETE agent。
+            if (state.awaitingPhase === 'agent_dialog_pending') {
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} dialog still pending; refusing Resume — operator should dismiss dialog via web terminal (slowPoll will mark agent_dialog_resolved_runtime, then Resume) or DELETE the agent.`);
+                return { resumed: false, releasedBinding: false };
+            }
+            // agent_dialog_resolved_runtime + active task：正常路径下 handleDialogPendingFromRuntime
+            // 已 fail task → boundTask 应 terminal。bound task 仍 active 表示 crash window
+            // (handleDialogPendingFromRuntime 写 awaiting_human 后 transitionTaskStatus 前 crash)；
+            // Resume 走 release path 会切 status=ok 但保留 binding + lock，prompt 从未发送 → task 静默卡死。
+            // refuse Resume，提示 operator 显式 cancel task 或 DELETE agent。
+            if (state.awaitingPhase === 'agent_dialog_resolved_runtime'
+                && boundTask && ACTIVE_TASK_STATUSES.has(boundTask.status)) {
+                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 };
+            }
+            const now = new Date().toISOString();
+            const shouldReleaseBinding = shouldReleaseHeldBinding(state, boundTask);
+            const cfg = this.getAgentConfig(agentId);
+            if (shouldReleaseBinding && state.worktreePath && cfg) {
+                const cleanupDir = this.resolveWorkdir(cfg, state);
+                if (cleanupDir) {
+                    const runner = this.createRunnerFor(cfg);
+                    const worktree = new WorktreeManager(runner);
+                    try {
+                        await worktree.remove(cleanupDir, state.worktreePath);
+                    }
+                    catch (err) {
+                        console.warn(`[AgentManager] resumeAgent worktree.remove failed for ${state.worktreePath}:`, err);
+                    }
+                }
+            }
+            await this.agentStore.update(agentId, (existing) => {
+                if (!existing)
+                    return AGENT_STORE_NOOP;
+                const next = {
+                    id: existing.id,
+                    projectId: existing.projectId,
+                    updatedAt: now,
+                    ...(existing.repoPath !== undefined ? { repoPath: existing.repoPath } : {}),
+                    ...(existing.paneId !== undefined ? { paneId: existing.paneId } : {}),
+                    ...(existing.creationToken !== undefined ? { creationToken: existing.creationToken } : {}),
+                    status: 'ok',
+                };
+                if (!shouldReleaseBinding) {
+                    if (existing.taskId !== undefined)
+                        next.taskId = existing.taskId;
+                    if (existing.worktreePath !== undefined)
+                        next.worktreePath = existing.worktreePath;
+                    if (existing.startedAt !== undefined)
+                        next.startedAt = existing.startedAt;
+                }
+                return next;
+            });
+            if (shouldReleaseBinding) {
+                await this.lockManager.release(agentId);
+                projectIdToDrain = state.projectId;
+            }
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: now,
+                projectId: state.projectId,
+                agentId,
+                ...(state.taskId ? { taskId: state.taskId } : {}),
+                data: {
+                    phase: 'resumed',
+                    previousPhase: state.awaitingPhase,
+                    releasedBinding: shouldReleaseBinding,
+                },
+            });
+            return { resumed: true, releasedBinding: shouldReleaseBinding };
+        });
+        // 出 withTaskLock 后再 drain——drainQueue 内对每个 pending 走 withTaskLock，自我嵌套会死锁。
+        if (projectIdToDrain) {
+            try {
+                await this.drainQueue(projectIdToDrain);
+            }
+            catch (err) {
+                console.warn(`[AgentManager] resumeAgent drainQueue(${projectIdToDrain}) failed:`, err);
+            }
+        }
+        return result;
+    }
+    async interruptPaneAndWaitReady(state, cfg) {
+        const runner = this.createRunnerFor(cfg);
+        const tmux = new TmuxManager(runner);
+        let paneId = state.paneId;
+        if (!paneId) {
+            try {
+                paneId = await tmux.getSinglePaneId(cfg.id);
+            }
+            catch (err) {
+                console.warn(`[AgentManager] interruptPaneAndWaitReady: getSinglePaneId failed for ${cfg.id}:`, err);
+                return false;
+            }
+        }
+        try {
+            await tmux.sendKeysToPane(paneId, 'C-c');
+            await new Promise(r => setTimeout(r, 200));
+        }
+        catch (err) {
+            console.warn(`[AgentManager] interruptPaneAndWaitReady: send C-c failed for pane ${paneId}:`, err);
+            return false;
+        }
+        try {
+            await tmux.waitReplReady(paneId, agentRuntimeKindFor(cfg), {
+                timeoutMs: 10_000,
+                scrollback: 0,
+            });
+            return true;
+        }
+        catch (err) {
+            console.warn(`[AgentManager] interruptPaneAndWaitReady: waitReplReady failed for pane ${paneId}:`, err);
+            return false;
+        }
+    }
+    async failTaskForDispatchError(taskId, phase, agentId, err) {
+        const expected = PHASE_EXPECTED_STATUS[phase] ?? [];
+        const transitioned = await this.transitionTaskStatus(taskId, 'failed', { fromStatus: expected.length > 0 ? expected : ['in_progress', 'review', 'fixing', 'approved'] });
+        if (!transitioned) {
+            console.warn(`[AgentManager] failTaskForDispatchError: task ${taskId} not in expected ` +
+                `fromStatus for phase=${phase}; skipping task transition`);
+        }
+        await this.recordError({
+            agentId,
+            projectId: transitioned?.task.projectId ?? '',
+            taskId,
+            operation: 'dispatch',
+            reason: `DISPATCH_${err.reason.toUpperCase()}`,
+            message: err.message,
+            observation: {
+                phase,
+                replDrained: err.replDrained,
+            },
+            recommendation: 'Inspect the runtime pane, then retry or cancel the task.',
+        });
+        // ack_unknown: sendEnter 已发，prompt 可能已被 REPL 接收并正在执行——
+        // 不能 release 让下一任务排队进同一 pane。pre-Enter 错误（prompt_too_large /
+        // required_skills_missing / gate_failed）则正常 release。
+        if (err.reason === 'ack_unknown') {
+            await this.markAwaitingHuman(agentId, `dispatch-failed:${err.reason}`, `${err.message}. Prompt may still be running in the pane; verify before resuming.`, { expectedTaskId: taskId });
+            // task 已 terminal: 同步释放 partner agent binding，否则 partner（如 dev）永远绑 terminal task，
+            // retryTask 走 validateTaskDispatch 时会看 dev 仍 bound → 409，UI Retry 通路被堵。
+            if (transitioned) {
+                await this.releasePartnersAndDrain(agentId, [taskId], [transitioned.task.projectId]);
+            }
+            return;
+        }
+        try {
+            await this.releaseAgentForTask(agentId, taskId, 'idle');
+        }
+        catch (releaseErr) {
+            console.warn(`[AgentManager] failTaskForDispatchError: releaseAgentForTask(${agentId}) failed:`, releaseErr);
+        }
+        await this.safeEmit({
+            id: '',
+            type: 'human.intervention',
+            timestamp: new Date().toISOString(),
+            projectId: transitioned?.task.projectId ?? '',
+            agentId,
+            taskId,
+            data: {
+                phase: `dispatch-failed:${err.reason}`,
+                reason: err.reason,
+                message: err.message,
+                replDrained: err.replDrained,
+            },
+        });
+    }
+    async failTasksForAgent(agentId, reason, opts = {}) {
+        const failed = await this.withTaskLock(async () => {
+            const tasks = await this.taskStore.list({});
+            const out = [];
+            for (const t of tasks) {
+                const active = ['in_progress', 'review', 'fixing', 'approved'];
+                const bound = t.agentId === agentId || t.qaAgentId === agentId;
+                if (active.includes(t.status) && bound) {
+                    t.status = 'failed';
+                    t.updatedAt = new Date().toISOString();
+                    await this.taskStore.set(t);
+                    out.push(t);
+                }
+            }
+            return out;
+        });
+        for (const t of failed) {
+            await this.safeEmit({
+                id: '',
+                type: 'task.updated',
+                timestamp: new Date().toISOString(),
+                projectId: t.projectId,
+                taskId: t.id,
+                data: { status: 'failed', reason },
+            });
+        }
+        const failedTaskIds = failed.map(t => t.id);
+        const projectIds = [...new Set(failed.map(t => t.projectId))];
+        if (!opts.deferPartnerCleanup) {
+            await this.releasePartnersAndDrain(agentId, failedTaskIds, projectIds);
+        }
+        return { failedTaskIds, projectIds };
+    }
+    async releasePartnersAndDrain(excludeAgentId, failedTaskIds, projectIds) {
+        for (const taskId of failedTaskIds) {
+            const t = await this.taskStore.get(taskId);
+            if (!t)
+                continue;
+            for (const partnerId of [t.agentId, t.qaAgentId]) {
+                if (!partnerId || partnerId === excludeAgentId)
+                    continue;
+                try {
+                    // allowAwaitingHuman: task 已 terminal 必须能完整清理；partner 即使被标 Held（罕见）
+                    // 也应释放，否则 partner stale binding 永远指向 terminal task → 后续 acquire 全卡。
+                    const ok = await this.releaseAgentForTask(partnerId, taskId, 'idle', { allowAwaitingHuman: true });
+                    if (!ok) {
+                        console.warn(`[AgentManager] failTasksForAgent: partner ${partnerId} release returned false ` +
+                            `for failed task ${taskId}; operator must use restart-repl / retry if cleanup is still needed.`);
+                    }
+                }
+                catch (err) {
+                    console.warn(`[AgentManager] failTasksForAgent: releaseAgentForTask(partner=${partnerId}, task=${taskId}) failed:`, err);
+                }
+            }
+        }
+        for (const projectId of projectIds) {
+            try {
+                await this.drainQueue(projectId);
+            }
+            catch (err) {
+                console.error(`[AgentManager] failTasksForAgent: drainQueue(${projectId}) failed:`, err);
+            }
+        }
+    }
+    // 100ms poll: fixed 200ms races runtimes that take >200ms to ack SIGINT.
+    async pollPaneCommandStable(tmux, paneId, opts) {
+        const deadline = Date.now() + opts.timeoutMs;
+        const SHELL = /^(?:zsh|bash|sh|fish)$/;
+        let last = '';
+        while (Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, 100));
+            const raw = await tmux.displayMessage(paneId, '#{pane_current_command}');
+            last = raw.trim();
+            if (opts.expectShell ? SHELL.test(last) : last !== '')
+                return last;
+        }
+        return last;
+    }
+    async restartReplOnly(agentId) {
+        const cfg = this.getAgentConfig(agentId);
+        if (!cfg)
+            throw new Error(`Unknown agent: ${agentId}`);
+        const runner = this.createRunnerFor(cfg);
+        const tmux = new TmuxManager(runner);
+        const alive = await tmux.hasSession(agentId);
+        if (!alive) {
+            throw new Error(`restart-repl: tmux session ${agentId} does not exist; use retry to rebuild`);
+        }
+        const marker = await tmux.getOption(agentId, '@baxian-agent-id');
+        if (marker !== agentId) {
+            throw new Error(`restart-repl: marker mismatch (got "${marker ?? 'null'}"); refusing to touch foreign session`);
+        }
+        const paneId = await tmux.getSinglePaneId(agentId);
+        await tmux.sendKeysToPane(paneId, 'C-c');
+        const cmd = await this.pollPaneCommandStable(tmux, paneId, { timeoutMs: 2_000 });
+        const RUNTIME = /^(?:claude|codex|node|\d+\.\d+\.\d+)$/;
+        const SHELL = /^(?:zsh|bash|sh|fish)$/;
+        if (RUNTIME.test(cmd)) {
+            await tmux.sendKeysToPane(paneId, 'exit', 'Enter');
+            await this.pollPaneCommandStable(tmux, paneId, { timeoutMs: 2_000, expectShell: true });
+        }
+        else if (!SHELL.test(cmd)) {
+            throw new Error(`restart-repl precondition failed: unexpected pane state "${cmd}"`);
+        }
+        const runtime = agentRuntimeKindFor(cfg);
+        await tmux.sendKeysToPane(paneId, `${buildLaunchCommand(cfg)}\n`);
+        await tmux.handleTrustDialog(paneId, runtime, {
+            timeoutMs: this.bootstrapTimeoutsMs.trustDialog,
+        });
+        await tmux.waitReplReady(paneId, runtime, {
+            timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
+            scrollback: 0,
+        });
+        await this.agentStore.update(agentId, (state) => {
+            if (!state)
+                return AGENT_STORE_NOOP;
+            return {
+                ...state,
+                paneId,
+                updatedAt: new Date().toISOString(),
+            };
+        });
+    }
+    prepareRemoveTargets(agentId) {
+        const cfg = this.getAgentConfig(agentId);
+        if (!cfg)
+            throw new Error(`Unknown agent: ${agentId}`);
+        const project = this.getProjectConfig(cfg.projectId);
+        if (!project)
+            throw new Error(`Unknown project: ${cfg.projectId}`);
+        if (cfg.role === 'qa')
+            return { targets: [agentId] };
+        for (const pair of project.agent) {
+            if (pair[0]?.id === agentId) {
+                const qa = pair[1];
+                return { targets: qa ? [agentId, qa.id] : [agentId] };
+            }
+        }
+        return { targets: [agentId] };
+    }
+    // Aggregates failures so DELETE rolls back the marker on remote IO error.
+    async cleanupRemovedAgentRuntime(targets) {
+        const failures = [];
+        for (const id of targets) {
+            const cfg = this.getAgentConfig(id);
+            if (!cfg)
+                continue;
+            const runner = this.createRunnerFor(cfg);
+            const tmux = new TmuxManager(runner);
+            const worktree = new WorktreeManager(runner);
+            this.stopRuntimeMenuWatch(id);
+            // Streamer first so subscribers see session_gone.
+            if (this.paneStreamerManager) {
+                try {
+                    await this.paneStreamerManager.destroy(id);
+                }
+                catch (err) {
+                    console.warn(`[AgentManager] cleanupRemovedAgentRuntime: paneStreamerManager.destroy(${id}) failed:`, err);
+                }
+            }
+            try {
+                const alive = await tmux.hasSession(id);
+                if (alive) {
+                    const marker = await tmux.getOption(id, '@baxian-agent-id');
+                    if (marker === id) {
+                        await tmux.killSession(id);
+                    }
+                    else {
+                        console.warn(`[AgentManager] cleanupRemovedAgentRuntime: skipping kill for ${id} ` +
+                            `(marker=${marker ?? 'null'}; not baxian-managed)`);
+                    }
+                }
+            }
+            catch (err) {
+                failures.push({ agentId: id, step: 'tmux', error: err });
+            }
+            const state = await this.agentStore.get(id);
+            if (state?.worktreePath) {
+                const cleanupDir = this.resolveWorkdir(cfg, state);
+                if (cleanupDir) {
+                    try {
+                        await worktree.remove(cleanupDir, state.worktreePath);
+                    }
+                    catch (err) {
+                        failures.push({ agentId: id, step: 'worktree.remove', error: err });
+                    }
+                }
+            }
+        }
+        if (failures.length > 0) {
+            const summary = failures
+                .map(f => `${f.agentId}/${f.step}: ${f.error instanceof Error ? f.error.message : String(f.error)}`)
+                .join('; ');
+            throw new CleanupFailedError(`cleanupRemovedAgentRuntime: ${failures.length} step(s) failed: ${summary}`, failures);
+        }
+    }
+    // IO-free preview; caller compares vs MAX_PROMPT_BYTES_ROUTE_LIMIT before allocating worktree.
+    previewPromptBytesForTaskInput(projectId, input) {
+        const cfg = this.getAgentConfig(input.preferredAgentId);
+        if (!cfg)
+            throw new Error(`Unknown agent: ${input.preferredAgentId}`);
+        if (cfg.projectId !== projectId) {
+            throw new Error(`Agent ${input.preferredAgentId} not in project ${projectId}`);
+        }
+        const workdirGuess = cfg.workdir ?? '/'.padEnd(64, 'x');
+        const worktreePathBound = `${workdirGuess}/.baxian-worktrees/task-9999999999_ffffffffffffffff`;
+        const now = new Date().toISOString();
+        const fakeTask = {
+            id: 'task-9999999999',
+            projectId,
+            title: input.title,
+            description: input.description,
+            preferredAgentId: input.preferredAgentId,
+            agentId: cfg.id,
+            branch: `${BRANCH_PREFIX}task-9999999999`,
+            reviewRound: 0,
+            status: 'in_progress',
+            createdAt: now,
+            updatedAt: now,
+        };
+        const fullPrompt = buildPromptInline({
+            task: fakeTask,
+            phase: 'develop',
+            agent: cfg,
+            worktreePath: worktreePathBound,
+            skillRegistry: this.skillRegistry,
+        });
+        return Buffer.byteLength(fullPrompt, 'utf8');
+    }
+    listAgents() {
+        return [...this.agentIndex.values()];
+    }
+    getProjectConfig(projectId) {
+        return this.config.project.find(p => p.id === projectId);
+    }
+    getProjectByRepo(repo) {
+        return this.config.project.find(p => p.repo === repo);
+    }
+    findQaPartner(devAgentId) {
+        for (const project of this.config.project) {
+            for (const pair of project.agent) {
+                if (pair[0]?.id === devAgentId) {
+                    return pair[1];
+                }
+            }
+        }
+        return undefined;
+    }
+    async getTask(taskId) {
+        return this.taskStore.get(taskId);
+    }
+    async getAgentState(agentId) {
+        return this.agentStore.get(agentId);
+    }
+    async getPostApproveCompletion(taskId) {
+        return this.postApproveStore.get(taskId);
+    }
+    async setPostApproveCompletion(taskId, value) {
+        // Store write + watcher.start under one lock — otherwise concurrent clear zombies the sub.
+        await this.withTaskLock(async () => {
+            await this.postApproveStore.set(taskId, value);
+            if (!this.postApproveMarkerWatcher)
+                return;
+            const task = await this.taskStore.get(taskId);
+            if (!task)
+                return;
+            await this.postApproveMarkerWatcher.start({
+                taskId,
+                projectId: task.projectId,
+                agentId: task.agentId,
+                token: value.token,
+            });
+        });
+    }
+    async clearPostApproveCompletion(taskId) {
+        await this.withTaskLock(async () => {
+            await this.postApproveStore.clear(taskId);
+            this.postApproveMarkerWatcher?.stop(taskId);
+        });
+    }
+    async clearPostApproveCompletionIfMatches(taskId, token) {
+        return this.withTaskLock(async () => {
+            const cleared = await this.postApproveStore.clearIfMatches(taskId, token);
+            if (cleared)
+                this.postApproveMarkerWatcher?.stop(taskId);
+            return cleared;
+        });
+    }
+    // manual-merge skips snapshot — a stale scrollback marker would re-fire every restart.
+    async armRecoveredPostApproveMarkers() {
+        if (!this.postApproveMarkerWatcher)
+            return;
+        const tasks = await this.taskStore.list({ status: 'approved' });
+        for (const task of tasks) {
+            const completion = await this.postApproveStore.get(task.id);
+            if (!completion)
+                continue;
+            const project = this.getProjectConfig(task.projectId);
+            const skipSnapshot = project?.merge !== 'auto';
+            try {
+                await this.postApproveMarkerWatcher.start({
+                    taskId: task.id,
+                    projectId: task.projectId,
+                    agentId: task.agentId,
+                    token: completion.token,
+                    skipSnapshot,
+                });
+            }
+            catch (err) {
+                console.warn(`[AgentManager] armRecoveredPostApproveMarkers: failed to arm task=${task.id}:`, err);
+            }
+        }
+    }
+    // skipSnapshot=true: 旧 scrollback 里的 marker 重启后不应再触发。
+    // 只对 spec-review-complete / spec-fix-complete emit intervention — spec-ready 在 develop
+    // prompt 里是 optional, 报警会让所有 in_progress task 噪音化。
+    async armRecoveredSpecMarkers() {
+        if (!this.specReviewMarkerWatcher)
+            return;
+        const tasks = await this.taskStore.list();
+        for (const task of tasks) {
+            if (!task.specMarkerToken)
+                continue;
+            let kind;
+            let agentId;
+            if (task.phase === 'spec' && task.status === 'review') {
+                kind = 'spec-review-complete';
+                agentId = task.qaAgentId;
+            }
+            else if (task.phase === 'spec' && task.status === 'fixing') {
+                kind = 'spec-fix-complete';
+                agentId = task.agentId;
+            }
+            else if (task.phase === undefined && task.status === 'in_progress') {
+                kind = 'spec-ready';
+                agentId = task.agentId;
+            }
+            if (!kind || !agentId)
+                continue;
+            try {
+                await this.specReviewMarkerWatcher.start({
+                    taskId: task.id,
+                    projectId: task.projectId,
+                    agentId,
+                    kind,
+                    token: task.specMarkerToken,
+                    skipSnapshot: true,
+                });
+                if (kind !== 'spec-ready') {
+                    await this.safeEmit({
+                        id: '',
+                        type: 'human.intervention',
+                        timestamp: new Date().toISOString(),
+                        projectId: task.projectId,
+                        agentId,
+                        taskId: task.id,
+                        data: {
+                            phase: 'spec-marker-armed-during-recovery',
+                            kind,
+                            note: 'Task is waiting for a spec marker after server recovery; if no marker arrives, the prompt may not have been fully delivered before the previous crash. Inspect the agent pane and consider manual retry or transition.',
+                        },
+                    });
+                }
+            }
+            catch (err) {
+                console.warn(`[AgentManager] armRecoveredSpecMarkers: failed to arm task=${task.id} kind=${kind}:`, err);
+            }
+        }
+    }
+    async fetchPrHeadSha(taskId) {
+        const task = await this.taskStore.get(taskId);
+        if (!task || !task.prNumber) {
+            throw new Error(`fetchPrHeadSha: no PR number for task ${taskId}`);
+        }
+        const project = this.getProjectConfig(task.projectId);
+        if (!project) {
+            throw new Error(`fetchPrHeadSha: unknown project ${task.projectId}`);
+        }
+        const result = await this.platformRunner.exec(`gh pr view ${task.prNumber} --repo ${shellQuote(project.repo)} --json headRefOid --jq .headRefOid`);
+        if (result.exitCode !== 0) {
+            throw new Error(`gh pr view failed for PR #${task.prNumber}: ${result.stderr || result.stdout}`);
+        }
+        const headSha = result.stdout.trim();
+        if (!/^[0-9a-f]{40}$/i.test(headSha)) {
+            throw new Error(`gh pr view returned invalid headRefOid for PR #${task.prNumber}`);
+        }
+        return headSha;
+    }
+    async listTasksByPrNumber(prNumber, projectId) {
+        const all = await this.taskStore.list({ projectId });
+        return all.filter(t => t.prNumber === prNumber);
+    }
+    async updateTaskStatus(taskId, status) {
+        const task = await this.taskStore.get(taskId);
+        if (!task)
+            return;
+        task.status = status;
+        task.updatedAt = new Date().toISOString();
+        await this.taskStore.set(task);
+    }
+    async updateTask(taskId, updates) {
+        await this.withTaskLock(async () => {
+            const task = await this.taskStore.get(taskId);
+            if (!task)
+                return;
+            Object.assign(task, updates, { updatedAt: new Date().toISOString() });
+            await this.taskStore.set(task);
+        });
+    }
+    async transitionTaskStatus(taskId, toStatus, guard, patch) {
+        return this.withTaskLock(async () => {
+            const task = await this.taskStore.get(taskId);
+            if (!task)
+                return null;
+            const previousStatus = task.status;
+            if (TERMINAL_STATUSES.includes(previousStatus))
+                return null;
+            if (!guard.fromStatus.includes(previousStatus))
+                return null;
+            Object.assign(task, patch ?? {}, {
+                status: toStatus,
+                updatedAt: new Date().toISOString(),
+            });
+            await this.taskStore.set(task);
+            return { task, previousStatus };
+        });
+    }
+    createRunnerFor(agent) {
+        if (this.runnerFactory) {
+            return this.runnerFactory(agent);
+        }
+        return createRunner(agent.mode, agent.host);
+    }
+    createRepoStore(agent, project, runner) {
+        if (this.repoStoreFactory) {
+            return this.repoStoreFactory(runner, project.repo, agent.mode, agent.host, this.repoCache);
+        }
+        return new RepoStore(runner, project.repo, agent.mode, agent.host, this.repoCache);
+    }
+    async ensureWorkdir(agent, project, runner) {
+        if (agent.workdir)
+            return { workdir: agent.workdir, repoStore: null };
+        const repoStore = this.createRepoStore(agent, project, runner);
+        const workdir = await repoStore.ensure();
+        return { workdir, repoStore };
+    }
+    resolveWorkdir(agent, agentState) {
+        if (agent.workdir)
+            return agent.workdir;
+        return agentState?.repoPath ?? null;
+    }
+    // Empty repos lack origin/HEAD; undefined makes git use base repo HEAD.
+    async resolveAutoBaseRef(runner, workdir) {
+        const result = await runner.exec(`git -C ${shellQuote(workdir)} rev-parse --verify --quiet origin/HEAD`);
+        return result.exitCode === 0 ? 'origin/HEAD' : undefined;
+    }
+    getRepoCache() {
+        return this.repoCache;
+    }
+    async rollbackFailedDispatch(taskId, agentId) {
+        await this.withTaskLock(async () => {
+            const task = await this.taskStore.get(taskId);
+            if (!task)
+                return;
+            if (task.status !== 'in_progress')
+                return;
+            task.agentId = '';
+            task.status = 'pending';
+            task.updatedAt = new Date().toISOString();
+            await this.taskStore.set(task);
+        });
+        const existing = await this.agentStore.get(agentId);
+        if (existing && existing.taskId !== taskId) {
+            console.warn(`[AgentManager] rollback: agent ${agentId} taskId mismatch (expected ${taskId}, got ${existing.taskId}); ` +
+                `skipping agent cleanup — agent already reassigned`);
+            return;
+        }
+        const projectId = existing?.projectId ?? this.getAgentConfig(agentId)?.projectId;
+        if (!projectId) {
+            console.error(`[AgentManager] CRITICAL: cannot resolve projectId for agent ${agentId} during rollback; deleting agent state.`);
+            await this.agentStore.delete(agentId);
+        }
+        else {
+            const now = new Date().toISOString();
+            await this.agentStore.update(agentId, (latest) => ({
+                ...(latest ?? existing ?? { id: agentId, projectId, updatedAt: now }),
+                id: agentId,
+                projectId,
+                taskId: undefined,
+                worktreePath: undefined,
+                updatedAt: now,
+            }));
+        }
+        await this.lockManager.release(agentId);
+    }
+    async pickAgent(projectId, preferredAgentId) {
+        const cfg = this.getAgentConfig(preferredAgentId);
+        if (!cfg)
+            throw new ApiError(400, `Unknown agent: ${preferredAgentId}`);
+        if (cfg.projectId !== projectId) {
+            throw new ApiError(400, `Agent ${preferredAgentId} not in project ${projectId}`);
+        }
+        if (cfg.role !== 'dev') {
+            throw new ApiError(400, `Agent ${preferredAgentId} is not dev role`);
+        }
+        const state = await this.agentStore.get(preferredAgentId);
+        if (!canDispatchWithBinding(state))
+            return null;
+        const { projectId: _projectId, ...rest } = cfg;
+        return rest;
+    }
+    async createTask(projectId, input) {
+        return this.withTaskLock(async () => {
+            const taskId = await this.taskStore.nextId();
+            const now = new Date().toISOString();
+            const dev = await this.pickAgent(projectId, input.preferredAgentId);
+            const qa = this.findQaPartner(input.preferredAgentId);
+            if (!dev) {
+                const queued = {
+                    id: taskId,
+                    projectId,
+                    title: input.title,
+                    description: input.description,
+                    preferredAgentId: input.preferredAgentId,
+                    agentId: '',
+                    reviewRound: 0,
+                    status: 'pending',
+                    branch: BRANCH_PREFIX + taskId,
+                    createdAt: now,
+                    updatedAt: now,
+                    ...(qa ? { qaAgentId: qa.id } : {}),
+                };
+                await this.taskStore.set(queued);
+                await this.safeEmit({
+                    id: '',
+                    type: 'task.created',
+                    timestamp: now,
+                    projectId,
+                    taskId,
+                    data: {
+                        queued: true,
+                        queueReason: 'preferred_agent_busy',
+                        agentId: input.preferredAgentId,
+                    },
+                });
+                return queued;
+            }
+            const acquired = await this.lockManager.acquire(dev.id);
+            if (!acquired) {
+                const queued = {
+                    id: taskId,
+                    projectId,
+                    title: input.title,
+                    description: input.description,
+                    preferredAgentId: input.preferredAgentId,
+                    agentId: '',
+                    reviewRound: 0,
+                    status: 'pending',
+                    branch: BRANCH_PREFIX + taskId,
+                    createdAt: now,
+                    updatedAt: now,
+                    ...(qa ? { qaAgentId: qa.id } : {}),
+                };
+                await this.taskStore.set(queued);
+                await this.safeEmit({
+                    id: '',
+                    type: 'task.created',
+                    timestamp: now,
+                    projectId,
+                    taskId,
+                    data: {
+                        queued: true,
+                        queueReason: 'agent_locked',
+                        agentId: input.preferredAgentId,
+                    },
+                });
+                return queued;
+            }
+            const task = {
+                id: taskId,
+                projectId,
+                title: input.title,
+                description: input.description,
+                preferredAgentId: input.preferredAgentId,
+                agentId: dev.id,
+                ...(qa ? { qaAgentId: qa.id } : {}),
+                reviewRound: 0,
+                status: 'in_progress',
+                branch: BRANCH_PREFIX + taskId,
+                createdAt: now,
+                updatedAt: now,
+            };
+            await this.taskStore.set(task);
+            await this.agentStore.update(dev.id, (existing) => ({
+                id: dev.id,
+                projectId,
+                taskId,
+                updatedAt: now,
+                ...(existing?.paneId !== undefined ? { paneId: existing.paneId } : {}),
+                ...(existing?.repoPath !== undefined ? { repoPath: existing.repoPath } : {}),
+                ...(existing?.creationToken !== undefined ? { creationToken: existing.creationToken } : {}),
+            }));
+            await this.safeEmit({
+                id: '',
+                type: 'task.assigned',
+                timestamp: now,
+                projectId,
+                agentId: dev.id,
+                taskId,
+                data: { agentId: dev.id },
+            });
+            return task;
+        });
+    }
+    async createAndStartTask(projectId, input) {
+        const task = await this.createTask(projectId, input);
+        if (task.status === 'in_progress' && task.agentId) {
+            // Persist token first — prompt build 和 watcher 验证共用 task.specMarkerToken。
+            const specMarkerToken = createMarkerToken();
+            await this.updateTask(task.id, { specMarkerToken });
+            let started = false;
+            let dispatchErr = null;
+            try {
+                started = await this.startSession(task.id, task.agentId, 'develop');
+            }
+            catch (err) {
+                dispatchErr = err;
+                console.error(`[AgentManager] createAndStartTask startSession hard error for task=${task.id}:`, err);
+            }
+            if (started) {
+                await this.armSpecMarkerWatcher(task.id, task.agentId, 'spec-ready', specMarkerToken);
+            }
+            if (!started) {
+                if (dispatchErr instanceof DispatchTerminalError) {
+                    await this.failTaskForDispatchError(task.id, 'develop', task.agentId, dispatchErr);
+                }
+                else if (dispatchErr instanceof EnsureSessionError && dispatchErr.partial.handled) {
+                    // handleDialogPendingFromRuntime 已标 Held + fail task + release partners；rollback 会清 taskId/lock
+                    // 让仍卡 dialog 的 pane 在 status='awaiting_human' 被清后可被新 dispatch 撞进——必须跳过。
+                }
+                else {
+                    await this.rollbackFailedDispatch(task.id, task.agentId);
+                }
+                const refreshed = await this.taskStore.get(task.id);
+                if (refreshed)
+                    return refreshed;
+            }
+        }
+        return task;
+    }
+    async drainQueue(projectId) {
+        const pending = await this.taskStore.list({ projectId, status: 'pending' });
+        pending.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        for (const task of pending) {
+            const taken = await this.withTaskLock(async () => {
+                const fresh = await this.taskStore.get(task.id);
+                if (!fresh || fresh.status !== 'pending')
+                    return null;
+                const cfg = this.getAgentConfig(fresh.preferredAgentId);
+                if (!cfg || cfg.projectId !== projectId || cfg.role !== 'dev') {
+                    if (!this.warnedStaleQueueDispatch.has(fresh.id)) {
+                        this.warnedStaleQueueDispatch.add(fresh.id);
+                        const reason = !cfg
+                            ? 'agent not configured'
+                            : cfg.projectId !== projectId
+                                ? `agent.projectId=${cfg.projectId} ≠ task.projectId=${projectId}`
+                                : `agent.role=${cfg.role} ≠ 'dev'`;
+                        console.warn(`[AgentManager] drainQueue: task ${fresh.id} preferredAgentId=${fresh.preferredAgentId} ` +
+                            `cannot be dispatched (${reason}); task will stay pending until config is fixed or task is edited / cancelled`);
+                    }
+                    return null;
+                }
+                const state = await this.agentStore.get(cfg.id);
+                if (!canDispatchWithBinding(state))
+                    return null;
+                const acquired = await this.lockManager.acquire(cfg.id);
+                if (!acquired)
+                    return null;
+                const { projectId: _projectId, ...dev } = cfg;
+                const now = new Date().toISOString();
+                fresh.agentId = dev.id;
+                fresh.status = 'in_progress';
+                fresh.updatedAt = now;
+                await this.taskStore.set(fresh);
+                await this.agentStore.update(dev.id, (existing) => ({
+                    id: dev.id,
+                    projectId,
+                    taskId: fresh.id,
+                    updatedAt: now,
+                    ...(existing?.paneId !== undefined ? { paneId: existing.paneId } : {}),
+                    ...(existing?.repoPath !== undefined ? { repoPath: existing.repoPath } : {}),
+                    ...(existing?.creationToken !== undefined ? { creationToken: existing.creationToken } : {}),
+                }));
+                await this.safeEmit({
+                    id: '',
+                    type: 'task.assigned',
+                    timestamp: now,
+                    projectId,
+                    agentId: dev.id,
+                    taskId: fresh.id,
+                    data: { agentId: dev.id, dequeued: true },
+                });
+                return fresh;
+            });
+            if (!taken)
+                continue;
+            const specMarkerToken = createMarkerToken();
+            await this.updateTask(taken.id, { specMarkerToken });
+            let started = false;
+            let dispatchErr = null;
+            try {
+                started = await this.startSession(taken.id, taken.agentId, 'develop');
+            }
+            catch (err) {
+                dispatchErr = err;
+                console.error(`[AgentManager] drainQueue startSession hard error for task=${taken.id}:`, err);
+            }
+            if (started) {
+                await this.armSpecMarkerWatcher(taken.id, taken.agentId, 'spec-ready', specMarkerToken);
+            }
+            if (!started) {
+                if (dispatchErr instanceof DispatchTerminalError) {
+                    await this.failTaskForDispatchError(taken.id, 'develop', taken.agentId, dispatchErr);
+                }
+                else if (dispatchErr instanceof EnsureSessionError && dispatchErr.partial.handled) {
+                    // handleDialogPendingFromRuntime 已 Held + fail task + release partners；跳过 rollback。
+                }
+                else {
+                    await this.rollbackFailedDispatch(taken.id, taken.agentId);
+                }
+            }
+        }
+    }
+    async startSession(taskId, agentId, phase, opts = {}) {
+        const agent = this.getAgentConfig(agentId);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentId}`);
+        const task = await this.taskStore.get(taskId);
+        if (!task)
+            throw new Error(`Unknown task: ${taskId}`);
+        const project = this.getProjectConfig(agent.projectId);
+        if (!project)
+            throw new Error(`Unknown project: ${agent.projectId}`);
+        const expectedStatuses = PHASE_EXPECTED_STATUS[phase] ?? [];
+        const preTask = await this.taskStore.get(taskId);
+        if (!preTask) {
+            console.warn(`[AgentManager] startSession[${phase}]: pre-create task=${taskId} not found; aborting`);
+            return false;
+        }
+        // bypassTaskStatusGate 只放过 expected gate，不放过 terminal。
+        if (TERMINAL_STATUSES.includes(preTask.status)) {
+            console.warn(`[AgentManager] startSession[${phase}]: pre-create task=${taskId} status=${preTask.status} ` +
+                `is terminal; aborting`);
+            return false;
+        }
+        if (!opts.bypassTaskStatusGate && !expectedStatuses.includes(preTask.status)) {
+            console.warn(`[AgentManager] startSession[${phase}]: pre-create task=${taskId} status=${preTask.status} ` +
+                `not in expected ${expectedStatuses.join('/')}; aborting`);
+            return false;
+        }
+        const preAgent = await this.agentStore.get(agentId);
+        if (PHASE_REQUIRES_AGENT_BOUND_TO_TASK[phase]) {
+            if (!preAgent || preAgent.taskId !== taskId) {
+                console.warn(`[AgentManager] startSession[${phase}]: pre-create agent=${agentId} not bound to ${taskId} ` +
+                    `(got ${preAgent?.taskId}); aborting`);
+                return false;
+            }
+        }
+        else if (preAgent && preAgent.taskId && preAgent.taskId !== taskId) {
+            console.warn(`[AgentManager] startSession[${phase}]: pre-create agent=${agentId} already bound to ` +
+                `${preAgent.taskId} (request ${taskId}); aborting`);
+            return false;
+        }
+        const dialogFailFromStatuses = opts.dialogFailFromStatuses ?? PHASE_EXPECTED_STATUS[phase] ?? [...ACTIVE_TASK_STATUSES];
+        let ensure;
+        try {
+            ensure = await this.ensureSession(agentId, 'runtime');
+        }
+        catch (err) {
+            if (await this.handleDialogPendingFromRuntime(agentId, err, { expectedFromStatuses: dialogFailFromStatuses })) {
+                throw err;
+            }
+            if (err instanceof EnsureSessionError && err.partial.createdSession) {
+                try {
+                    const runner = this.createRunnerFor(agent);
+                    await new TmuxManager(runner).killSession(agentId);
+                }
+                catch (cleanupErr) {
+                    console.warn(`[AgentManager] startSession ensureSession rollback killSession failed:`, cleanupErr);
+                }
+            }
+            throw err;
+        }
+        const { paneId, workdir } = ensure;
+        const runner = this.createRunnerFor(agent);
+        const worktree = new WorktreeManager(runner);
+        const tmux = new TmuxManager(runner);
+        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);
+        // Persist worktreePath now so a crash before set-running leaves a recoverable trail.
+        await this.agentStore.update(agentId, (stateNow) => {
+            if (!stateNow || stateNow.taskId !== taskId)
+                return AGENT_STORE_NOOP;
+            return {
+                ...stateNow,
+                paneId,
+                worktreePath,
+                repoPath: workdir,
+                updatedAt: new Date().toISOString(),
+            };
+        });
+        // Caller-transmitted token/round take precedence — task fields are stale during dispatch.
+        const promptSpecMarkerToken = opts.specMarkerToken ?? task.specMarkerToken;
+        const promptSpecRound = opts.currentSpecRound ?? task.specReviewRound;
+        const beforeInjectAgent = await this.agentStore.get(agentId);
+        // freshRuntime=true 覆盖两种场景：(a) buildFreshSession 全新 tmux session；
+        // (b) adoptOrRestartSession 的 shell 重启 / trust-dialog 答完——pane 仍在但 REPL
+        // 是新进程。两种情况下旧上下文都没了，必须重置 dedup baseline，决不能因为
+        // paneId 字符串恰好相同就沿用旧 skill 集。
+        const reuseInjectedSkills = ensure.freshRuntime
+            ? null
+            : reuseSkillsIfContextValid(beforeInjectAgent, taskId, paneId);
+        let prompt;
+        try {
+            prompt = buildPromptInline({
+                task,
+                phase,
+                agent,
+                worktreePath,
+                skillRegistry: this.skillRegistry,
+                ...(promptSpecMarkerToken ? { specMarkerToken: promptSpecMarkerToken } : {}),
+                ...(promptSpecRound !== undefined ? { currentSpecRound: promptSpecRound } : {}),
+                ...(opts.specFindings ? { specFindings: opts.specFindings } : {}),
+                ...(reuseInjectedSkills ? { excludeSkills: reuseInjectedSkills } : {}),
+            });
+        }
+        catch (err) {
+            try {
+                await worktree.remove(workdir, worktreePath);
+            }
+            catch { }
+            // Terminal — rolling back to pending would loop on the same misconfiguration.
+            if (err instanceof PromptSizeError) {
+                throw new DispatchTerminalError('prompt_too_large', err.message);
+            }
+            if (err instanceof RequiredSkillsMissingError) {
+                throw new DispatchTerminalError('required_skills_missing', err.message);
+            }
+            throw err;
+        }
+        // Last cancellable boundary before paste.
+        const taskFresh = await this.taskStore.get(taskId);
+        if (!taskFresh) {
+            console.warn(`[AgentManager] startSession: task ${taskId} disappeared mid-dispatch; cleaning up worktree before paste`);
+            try {
+                await worktree.remove(workdir, worktreePath);
+            }
+            catch { }
+            return false;
+        }
+        if (TERMINAL_STATUSES.includes(taskFresh.status)) {
+            console.warn(`[AgentManager] startSession: task ${taskId} status=${taskFresh.status} is terminal ` +
+                `for phase=${phase}; cleaning up worktree before paste`);
+            try {
+                await worktree.remove(workdir, worktreePath);
+            }
+            catch { }
+            return false;
+        }
+        if (!opts.bypassTaskStatusGate && !expectedStatuses.includes(taskFresh.status)) {
+            console.warn(`[AgentManager] startSession: task ${taskId} status=${taskFresh.status} not in ` +
+                `expected ${expectedStatuses.join('/')} for phase=${phase}; cleaning up worktree before paste`);
+            try {
+                await worktree.remove(workdir, worktreePath);
+            }
+            catch { }
+            return false;
+        }
+        const agentFresh = await this.agentStore.get(agentId);
+        if (PHASE_REQUIRES_AGENT_BOUND_TO_TASK[phase]) {
+            if (!agentFresh || agentFresh.taskId !== taskId) {
+                console.warn(`[AgentManager] startSession[${phase}]: agent ${agentId} not bound to ${taskId} ` +
+                    `(got taskId=${agentFresh?.taskId}); cleaning up worktree before paste`);
+                try {
+                    await worktree.remove(workdir, worktreePath);
+                }
+                catch { }
+                return false;
+            }
+        }
+        else if (agentFresh && agentFresh.taskId && agentFresh.taskId !== taskId) {
+            console.warn(`[AgentManager] startSession[${phase}]: agent ${agentId} reassigned to ${agentFresh.taskId} ` +
+                `(was ${taskId}); cleaning up worktree before paste`);
+            try {
+                await worktree.remove(workdir, worktreePath);
+            }
+            catch { }
+            return false;
+        }
+        const now = new Date().toISOString();
+        let agentMarkedRunning = false;
+        try {
+            await this.agentStore.update(agentId, (existing) => ({
+                id: agentId,
+                projectId: agent.projectId,
+                paneId,
+                taskId,
+                worktreePath,
+                repoPath: workdir,
+                startedAt: now,
+                updatedAt: now,
+                ...(existing?.creationToken !== undefined ? { creationToken: existing.creationToken } : {}),
+                ...(reuseInjectedSkills
+                    ? { injectedSkills: { taskId, paneId, skills: reuseInjectedSkills } }
+                    : {}),
+            }));
+            agentMarkedRunning = true;
+            const ackResult = await this.injectAndAwaitAck(tmux, paneId, prompt, agentId, agent.runtime);
+            // ack-timeout 路径下 REPL 未确认接收，prompt 可能仍在排队——把 phase skills 记成 resident
+            // 等于让下一轮 dedup 在事实尚未确认时短路，operator 复盘后重新 dispatch 会发空 <skills/>，
+            // 必须只在 acked 通路上落盘。
+            if (ackResult.acked) {
+                await this.persistInjectedSkills(agentId, taskId, paneId, agent.role, phase, reuseInjectedSkills);
+            }
+            await this.eventBus.emit({
+                id: '',
+                type: 'session.started',
+                timestamp: now,
+                projectId: agent.projectId,
+                agentId,
+                taskId,
+                data: { phase, worktreePath },
+            });
+            this.startRuntimeMenuWatch(agentId);
+            return true;
+        }
+        catch (err) {
+            // ack_unknown 表示 sendEnter 已发，prompt 可能正在 REPL 中执行。
+            // 清绑定/lock/worktree 会让下一任务复用仍在跑旧 prompt 的 pane——保留所有 state，
+            // 由上游 failTaskForDispatchError → markAwaitingHuman 接手等人。
+            const isAckUnknown = err instanceof DispatchTerminalError && err.reason === 'ack_unknown';
+            if (!isAckUnknown) {
+                try {
+                    await worktree.remove(workdir, worktreePath);
+                }
+                catch { }
+                if (agentMarkedRunning) {
+                    try {
+                        let released = false;
+                        await this.agentStore.update(agentId, (agentNow) => {
+                            if (!agentNow || agentNow.taskId !== taskId) {
+                                console.warn(`[AgentManager] startSession cleanup agentStore: agent ${agentId} already reassigned ` +
+                                    `(taskId=${agentNow?.taskId}, expected ${taskId}); skipping`);
+                                return AGENT_STORE_NOOP;
+                            }
+                            released = true;
+                            void err;
+                            return {
+                                id: agentId,
+                                projectId: agent.projectId,
+                                paneId,
+                                repoPath: workdir,
+                                updatedAt: new Date().toISOString(),
+                                ...(agentNow.creationToken !== undefined ? { creationToken: agentNow.creationToken } : {}),
+                            };
+                        });
+                        if (released) {
+                            await this.lockManager.release(agentId);
+                        }
+                    }
+                    catch (cleanupErr) {
+                        console.warn(`[AgentManager] startSession cleanup agentStore failed:`, cleanupErr);
+                    }
+                }
+            }
+            throw err;
+        }
+    }
+    async injectAndAwaitAck(tmux, paneId, prompt, agentId, _runtime) {
+        await tmux.injectPrompt(paneId, prompt, agentId);
+        const baseline = await tmux.capturePaneSnapshot(paneId);
+        await tmux.sendEnter(paneId);
+        try {
+            await tmux.waitAck(paneId, baseline, { timeoutMs: this.dispatchAckTimeoutMs });
+            return { acked: true };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // 仅 ack 超时走 intervention（REPL 排队 OK 等人查看）；其他错误（capturePaneSnapshot
+            // 等基础设施失败）当 dispatch 终态错误抛出，由上游标 task failed。
+            if (!(err instanceof Error && /runtime ack timeout/.test(err.message))) {
+                throw new DispatchTerminalError('ack_unknown', `ack_unknown for pane ${paneId}: ${message}`);
+            }
+            console.warn(`[AgentManager] dispatch ack timeout for pane ${paneId} agent ${agentId}: ${message}`);
+            const state = await this.agentStore.get(agentId).catch(() => null);
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId: state?.projectId ?? '',
+                agentId,
+                ...(state?.taskId ? { taskId: state.taskId } : {}),
+                data: {
+                    phase: 'dispatch-ack-timeout',
+                    paneId,
+                    message,
+                    note: 'REPL did not acknowledge the pasted prompt within timeout. ' +
+                        'baxian intentionally did NOT send C-c — the input may still be queued. ' +
+                        'Attach via web terminal to verify and resolve.',
+                },
+            });
+            return { acked: false };
+        }
+    }
+    // Snapshot which skills are now resident in the REPL's context, union of
+    // the pre-dispatch baseline (when context was still valid) and the phase's
+    // declared skills. Guarded by (taskId, paneId) so a concurrent rebind never
+    // overwrites a freshly-bound agent.
+    async persistInjectedSkills(agentId, taskId, paneId, role, phase, reuseInjectedSkills) {
+        const phaseSkills = this.skillRegistry.skillsForPhase(role, phase);
+        const baseList = reuseInjectedSkills ?? [];
+        // 已有有效 context 记录，且本 phase 没有引入新 skill → 写盘无信息增益，short-circuit。
+        // reuseInjectedSkills === null 时缺基线记录，仍需建一份初始档。
+        if (reuseInjectedSkills !== null && phaseSkills.every(s => baseList.includes(s)))
+            return;
+        const merged = Array.from(new Set([...baseList, ...phaseSkills]));
+        const now = new Date().toISOString();
+        await this.agentStore.update(agentId, (latest) => {
+            if (!latest || latest.taskId !== taskId || latest.paneId !== paneId)
+                return AGENT_STORE_NOOP;
+            return {
+                ...latest,
+                injectedSkills: { taskId, paneId, skills: merged },
+                updatedAt: now,
+            };
+        });
+    }
+    // Ready gate prevents mid-paste webhook from flipping to 'waiting' on a busy REPL.
+    async markAgentWaiting(agentId, expectedTaskId, opts = {}) {
+        return this.releaseAgentForTask(agentId, expectedTaskId, 'waiting', opts);
+    }
+    async continueSession(taskId, agentId, phase, opts = {}) {
+        const agent = this.getAgentConfig(agentId);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentId}`);
+        const task = await this.taskStore.get(taskId);
+        if (!task)
+            throw new Error(`Unknown task: ${taskId}`);
+        const postApproveToken = opts.postApproveToken
+            ?? (phase === 'post_approve'
+                ? (await this.getPostApproveCompletion(taskId))?.token
+                : undefined);
+        if (phase === 'post_approve') {
+            const completion = await this.getPostApproveCompletion(taskId);
+            if (!completion || !postApproveToken || completion.token !== postApproveToken) {
+                console.warn(`[AgentManager] continueSession[post_approve]: token missing or stale for task ${taskId}; skipping`);
+                return false;
+            }
+        }
+        const agentState = await this.agentStore.get(agentId);
+        if (!agentState)
+            throw new Error(`No agent state found for: ${agentId}`);
+        if (PHASE_REQUIRES_AGENT_BOUND_TO_TASK[phase] && agentState.taskId !== taskId) {
+            console.warn(`[AgentManager] continueSession[${phase}]: agent ${agentId} not bound to ${taskId} ` +
+                `(pre-paste taskId=${agentState.taskId}); skipping`);
+            return false;
+        }
+        if (!PHASE_REQUIRES_AGENT_BOUND_TO_TASK[phase]
+            && agentState.taskId
+            && agentState.taskId !== taskId) {
+            console.warn(`[AgentManager] continueSession[${phase}]: agent ${agentId} reassigned ` +
+                `(pre-paste taskId=${agentState.taskId} !== ${taskId}); skipping`);
+            return false;
+        }
+        const worktreePath = agentState.worktreePath;
+        const dialogFailFromStatuses = opts.dialogFailFromStatuses ?? PHASE_EXPECTED_STATUS[phase] ?? [...ACTIVE_TASK_STATUSES];
+        let ensure;
+        try {
+            ensure = await this.ensureSession(agentId, 'runtime');
+        }
+        catch (err) {
+            if (await this.handleDialogPendingFromRuntime(agentId, err, { expectedFromStatuses: dialogFailFromStatuses })) {
+                throw err;
+            }
+            if (err instanceof EnsureSessionError && err.partial.createdSession) {
+                try {
+                    const runner = this.createRunnerFor(agent);
+                    await new TmuxManager(runner).killSession(agentId);
+                }
+                catch (cleanupErr) {
+                    console.warn(`[AgentManager] continueSession ensureSession rollback killSession failed:`, cleanupErr);
+                }
+            }
+            throw err;
+        }
+        const { paneId } = ensure;
+        const runner = this.createRunnerFor(agent);
+        const tmux = new TmuxManager(runner);
+        const promptSpecMarkerToken = opts.specMarkerToken ?? task.specMarkerToken;
+        const promptSpecRound = opts.currentSpecRound ?? task.specReviewRound;
+        // 与 startSession 同步：任何 REPL 启动 / 重启路径（freshRuntime=true）都视为新上下文，
+        // 强制重新注入完整 skill 集——既覆盖 fresh tmux session，也覆盖同 pane 里的 shell 重启
+        // 与 trust-dialog 完成两种 adopt 场景。
+        const reuseInjectedSkills = ensure.freshRuntime
+            ? null
+            : reuseSkillsIfContextValid(agentState, taskId, paneId);
+        let prompt;
+        try {
+            prompt = buildPromptInline({
+                task,
+                phase,
+                agent,
+                worktreePath,
+                skillRegistry: this.skillRegistry,
+                ...(postApproveToken ? { postApproveToken } : {}),
+                ...(promptSpecMarkerToken ? { specMarkerToken: promptSpecMarkerToken } : {}),
+                ...(promptSpecRound !== undefined ? { currentSpecRound: promptSpecRound } : {}),
+                ...(opts.specFindings ? { specFindings: opts.specFindings } : {}),
+                ...(reuseInjectedSkills ? { excludeSkills: reuseInjectedSkills } : {}),
+            });
+        }
+        catch (err) {
+            if (err instanceof PromptSizeError) {
+                throw new DispatchTerminalError('prompt_too_large', err.message);
+            }
+            if (err instanceof RequiredSkillsMissingError) {
+                throw new DispatchTerminalError('required_skills_missing', err.message);
+            }
+            throw err;
+        }
+        // Final state re-check before the irreversible paste — guards against IO-window races.
+        const expectedStatuses = PHASE_EXPECTED_STATUS[phase] ?? [];
+        const taskFresh = await this.taskStore.get(taskId);
+        if (!taskFresh || TERMINAL_STATUSES.includes(taskFresh.status)) {
+            console.warn(`[AgentManager] continueSession: task ${taskId} status=${taskFresh?.status} terminal/missing; skipping paste`);
+            return false;
+        }
+        if (!opts.bypassTaskStatusGate && !expectedStatuses.includes(taskFresh.status)) {
+            console.warn(`[AgentManager] continueSession: task ${taskId} status=${taskFresh.status} not in ` +
+                `expected ${expectedStatuses.join('/')} for phase=${phase}; skipping paste`);
+            return false;
+        }
+        const agentFresh = await this.agentStore.get(agentId);
+        if (PHASE_REQUIRES_AGENT_BOUND_TO_TASK[phase]) {
+            if (!agentFresh || agentFresh.taskId !== taskId) {
+                console.warn(`[AgentManager] continueSession[${phase}]: agent ${agentId} not bound to ${taskId} ` +
+                    `(got ${agentFresh?.taskId}); skipping`);
+                return false;
+            }
+        }
+        else if (agentFresh && agentFresh.taskId && agentFresh.taskId !== taskId) {
+            console.warn(`[AgentManager] continueSession[${phase}]: agent ${agentId} reassigned ` +
+                `(taskId=${agentFresh.taskId} !== ${taskId}); skipping`);
+            return false;
+        }
+        if (phase === 'post_approve') {
+            const completionFresh = await this.getPostApproveCompletion(taskId);
+            if (!completionFresh || completionFresh.token !== postApproveToken) {
+                console.warn(`[AgentManager] continueSession[post_approve]: token changed before paste for task ${taskId}; skipping`);
+                return false;
+            }
+        }
+        const now = new Date().toISOString();
+        await this.agentStore.update(agentId, (latest) => {
+            if (!latest)
+                return AGENT_STORE_NOOP;
+            return {
+                ...latest,
+                paneId,
+                worktreePath,
+                updatedAt: now,
+                ...(reuseInjectedSkills
+                    ? { injectedSkills: { taskId, paneId, skills: reuseInjectedSkills } }
+                    : { injectedSkills: undefined }),
+            };
+        });
+        const ackResult = await this.injectAndAwaitAck(tmux, paneId, prompt, agentId, agent.runtime);
+        if (ackResult.acked) {
+            await this.persistInjectedSkills(agentId, taskId, paneId, agent.role, phase, reuseInjectedSkills);
+        }
+        return true;
+    }
+    async recover() {
+        const states = await this.agentStore.list();
+        const deferredCleanups = [];
+        for (const state of states) {
+            const agentConfig = this.getAgentConfig(state.id);
+            if (!agentConfig)
+                continue;
+            try {
+                const result = await this.ensureSession(state.id, 'recover');
+                // recover 成功 = server 重启前 dialog_pending 的 agent 现在 REPL ready。
+                // 处理 Held：与 resumeAgent 共用 shouldReleaseHeldBinding 规则（task terminal/无 task /
+                // turn-completed phase → 同步清 binding；task active 且 phase 不在 completed 集合 → 保留 binding）。
+                const boundTask = state.taskId ? await this.taskStore.get(state.taskId) : null;
+                const shouldReleaseBinding = shouldReleaseHeldBinding(state, boundTask);
+                // 释放 binding 时同步清 worktree（与 resumeAgent 一致）——否则跨重启恢复后
+                // worktreePath 在下面 update 中被丢弃，磁盘上的 worktree 永远无人回收。
+                if (shouldReleaseBinding && state.worktreePath) {
+                    const cleanupDir = this.resolveWorkdir(agentConfig, state);
+                    if (cleanupDir) {
+                        const runner = this.createRunnerFor(agentConfig);
+                        const worktree = new WorktreeManager(runner);
+                        try {
+                            await worktree.remove(cleanupDir, state.worktreePath);
+                        }
+                        catch (worktreeErr) {
+                            console.warn(`[recover] worktree.remove failed for ${state.worktreePath}:`, worktreeErr);
+                        }
+                    }
+                }
+                // 所有 awaiting_human + non-releasable binding 都保留 Held。包括 agent_dialog_pending +
+                // active task 这个 crash window 场景：handleDialogPendingFromRuntime 已写 awaiting_human
+                // 但 transitionTaskStatus 之前 crash 重启 → task 仍 active；recover 切到 ok 会丢失 Resume
+                // 入口、binding 仍指向 active task → 新 dispatch 撞 stale binding。
+                // 注意：agent_dialog_pending + 无 taskId（最 common 的 dialog_pending） → shouldReleaseBinding=true
+                // → preserveHeld=false → 走 release path 清 Held（recover 视为 dialog dismissed 的正常出口）。
+                const preserveHeld = !shouldReleaseBinding
+                    && state.status === 'awaiting_human';
+                await this.agentStore.update(state.id, (latest) => {
+                    if (!latest)
+                        return AGENT_STORE_NOOP;
+                    const base = {
+                        id: latest.id,
+                        projectId: latest.projectId,
+                        paneId: result.paneId,
+                        updatedAt: new Date().toISOString(),
+                        ...(latest.repoPath !== undefined ? { repoPath: latest.repoPath } : {}),
+                        status: 'ok',
+                    };
+                    if (shouldReleaseBinding) {
+                        return base;
+                    }
+                    const withBinding = {
+                        ...base,
+                        ...(latest.taskId !== undefined ? { taskId: latest.taskId } : {}),
+                        ...(latest.worktreePath !== undefined ? { worktreePath: latest.worktreePath } : {}),
+                        ...(latest.startedAt !== undefined ? { startedAt: latest.startedAt } : {}),
+                    };
+                    if (!preserveHeld)
+                        return withBinding;
+                    // 保留 awaiting_human 整套字段：operator 仍需干预（Resume / cancel task / DELETE agent）。
+                    return {
+                        ...withBinding,
+                        status: 'awaiting_human',
+                        ...(latest.awaitingPhase !== undefined ? { awaitingPhase: latest.awaitingPhase } : {}),
+                        ...(latest.awaitingReason !== undefined ? { awaitingReason: latest.awaitingReason } : {}),
+                        ...(latest.awaitingSince !== undefined ? { awaitingSince: latest.awaitingSince } : {}),
+                    };
+                });
+                if (shouldReleaseBinding) {
+                    await this.lockManager.release(state.id);
+                }
+                if (state.taskId && !shouldReleaseBinding) {
+                    this.startRuntimeMenuWatch(state.id);
+                }
+            }
+            catch (err) {
+                if (err instanceof EnsureSessionError && err.partial.dialogPending) {
+                    await this.markDialogPending(state.id, state.creationToken);
+                    // runtime path (creationToken=undefined) 时传 paneId/taskId snapshot 作 generation guard，
+                    // 否则 generationMismatch 看 expectedTaskId 默认 undefined 与 state.taskId 不匹配会立即退出。
+                    void this.slowPollDialogPending(state.id, state.creationToken, {
+                        ...(state.paneId !== undefined ? { expectedPaneId: state.paneId } : {}),
+                        expectedTaskId: state.taskId,
+                    }).catch((pollErr) => {
+                        console.warn(`[recover] slowPoll for ${state.id} crashed:`, pollErr);
+                    });
+                    continue;
+                }
+                if (err instanceof EnsureSessionError && err.partial.createdSession) {
+                    try {
+                        const runner = this.createRunnerFor(agentConfig);
+                        await new TmuxManager(runner).killSession(state.id);
+                    }
+                    catch (cleanupErr) {
+                        console.warn(`[recover] killSession rollback failed for agent=${state.id}:`, cleanupErr);
+                    }
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                console.warn(`[recover] ensureSession failed for agent=${state.id}: ${message}`);
+                await this.agentStore.update(state.id, (latest) => {
+                    if (!latest)
+                        return AGENT_STORE_NOOP;
+                    return {
+                        ...latest,
+                        paneId: undefined,
+                        creationToken: undefined,
+                        updatedAt: new Date().toISOString(),
+                    };
+                });
+                await this.lockManager.release(state.id);
+                const cleanup = await this.failTasksForAgent(state.id, `recovery: ${message}`, { deferPartnerCleanup: true });
+                deferredCleanups.push({
+                    failingAgentId: state.id,
+                    failedTaskIds: cleanup.failedTaskIds,
+                    projectIds: cleanup.projectIds,
+                });
+                await this.recordError({
+                    agentId: state.id,
+                    projectId: state.projectId,
+                    ...(state.taskId ? { taskId: state.taskId } : {}),
+                    operation: 'recovery',
+                    reason: 'RECOVERY_ENSURE_SESSION_FAILED',
+                    message,
+                    observation: { phase: 'recovery-failed' },
+                    recommendation: 'Inspect or recreate the tmux session, then retry the affected task.',
+                });
+                await this.safeEmit({
+                    id: '',
+                    type: 'human.intervention',
+                    timestamp: new Date().toISOString(),
+                    projectId: state.projectId,
+                    agentId: state.id,
+                    taskId: state.taskId ?? '',
+                    data: { phase: 'recovery-failed', error: message },
+                });
+            }
+        }
+        for (const c of deferredCleanups) {
+            await this.releasePartnersAndDrain(c.failingAgentId, c.failedTaskIds, c.projectIds);
+        }
+    }
+    async reconcileFailedAgent(agentId) {
+        const reconciled = await this.withTaskLock(async () => {
+            let projectId = '';
+            let timestamp = '';
+            let hadBinding = false;
+            let changed = false;
+            let taskId;
+            await this.agentStore.update(agentId, (existing) => {
+                if (!existing)
+                    return AGENT_STORE_NOOP;
+                if (existing.creationToken)
+                    return AGENT_STORE_NOOP;
+                timestamp = new Date().toISOString();
+                projectId = existing.projectId;
+                hadBinding = !!existing.taskId;
+                taskId = existing.taskId;
+                if (!existing.taskId
+                    && !existing.worktreePath
+                    && !existing.startedAt
+                    && !existing.paneId
+                    && !existing.creationToken) {
+                    return AGENT_STORE_NOOP;
+                }
+                changed = true;
+                return {
+                    id: existing.id,
+                    projectId: existing.projectId,
+                    ...(existing.repoPath !== undefined ? { repoPath: existing.repoPath } : {}),
+                    updatedAt: timestamp,
+                };
+            });
+            if (!projectId || !changed)
+                return null;
+            await this.lockManager.release(agentId);
+            return { projectId, timestamp, hadBinding, taskId };
+        });
+        if (!reconciled)
+            return false;
+        if (reconciled.hadBinding) {
+            await this.failTasksForAgent(agentId, 'tmux-probe=absent');
+        }
+        await this.recordError({
+            agentId,
+            projectId: reconciled.projectId,
+            ...(reconciled.taskId ? { taskId: reconciled.taskId } : {}),
+            operation: 'recovery',
+            reason: 'TMUX_SESSION_ABSENT',
+            message: 'tmux probe reported the agent session absent',
+            occurredAt: reconciled.timestamp,
+            observation: { tmuxSessionStatus: 'absent' },
+            recommendation: 'Restart the agent runtime before assigning more work.',
+        });
+        await this.safeEmit({
+            id: '',
+            type: 'agent.recovered',
+            timestamp: reconciled.timestamp,
+            projectId: reconciled.projectId,
+            agentId,
+            data: { reason: 'tmux-probe=absent' },
+        });
+        return true;
+    }
+    async cancelTask(taskId) {
+        let devToRelease;
+        let qaToRelease;
+        let projectIdToDrain;
+        this.specReviewMarkerWatcher?.stop(taskId);
+        const result = await this.withTaskLock(async () => {
+            const task = await this.taskStore.get(taskId);
+            if (!task)
+                throw new ApiError(404, 'Task not found');
+            if (TERMINAL_STATUSES.includes(task.status))
+                return task;
+            if (task.agentId)
+                devToRelease = task.agentId;
+            if (task.qaAgentId)
+                qaToRelease = task.qaAgentId;
+            const now = new Date().toISOString();
+            task.status = 'cancelled';
+            task.updatedAt = now;
+            await this.taskStore.set(task);
+            await this.safeEmit({
+                id: '',
+                type: 'task.updated',
+                timestamp: now,
+                projectId: task.projectId,
+                taskId,
+                data: { status: 'cancelled' },
+            });
+            projectIdToDrain = task.projectId;
+            return task;
+        });
+        // 唯一允许打断 agent 会话的入口（用户主动 Cancel）。
+        for (const id of [devToRelease, qaToRelease]) {
+            if (!id)
+                continue;
+            const cfg = this.getAgentConfig(id);
+            const state = await this.agentStore.get(id);
+            if (!cfg || !state)
+                continue;
+            // 重校验绑定：lock 释放后另一路 release+acquire 可能已把 agent 绑给新任务，
+            // 此时不能 C-c 打到新会话上、也不能继续 idle release。
+            if (state.taskId !== taskId) {
+                console.warn(`[AgentManager] cancelTask: ${id} no longer bound to ${taskId} (got ${state.taskId}); skipping`);
+                continue;
+            }
+            const ok = await this.interruptPaneAndWaitReady(state, cfg);
+            if (!ok) {
+                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;
+            }
+            try {
+                // allowAwaitingHuman: cancelTask 是显式回收入口，agent 之前可能因 ack_unknown 等被标 Held，
+                // 用户主动 Cancel 应允许跨过 awaiting_human gate 清理 binding；release 默认 gate 是为了
+                // 拦住非显式路径（如 generic catch）的意外清理，cancelTask 不属于那类。
+                await this.releaseAgentForTask(id, taskId, 'idle', { allowAwaitingHuman: true });
+            }
+            catch (err) {
+                console.error(`[AgentManager] cancelTask releaseAgentForTask(${id}) failed:`, err);
+            }
+        }
+        if (projectIdToDrain) {
+            try {
+                await this.drainQueue(projectIdToDrain);
+            }
+            catch (err) {
+                console.error(`[AgentManager] drainQueue failed for ${projectIdToDrain}:`, err);
+            }
+        }
+        return result;
+    }
+    async validateTaskDispatch(projectId, input) {
+        const agentState = await this.agentStore.get(input.preferredAgentId);
+        if (agentState?.status === 'awaiting_human') {
+            throw new ApiError(409, `agent "${input.preferredAgentId}" is awaiting human (${agentState.awaitingPhase ?? 'unknown phase'}); resume or delete before dispatching new tasks`);
+        }
+        if (agentState?.creationToken || agentState?.taskId) {
+            const reason = agentState.creationToken ? 'being created' : `bound to task ${agentState.taskId}`;
+            throw new ApiError(409, `agent "${input.preferredAgentId}" is ${reason}; please retry later`);
+        }
+        let previewBytes;
+        try {
+            previewBytes = this.previewPromptBytesForTaskInput(projectId, input);
+        }
+        catch (err) {
+            // RequiredSkillsMissingError is a server config / sync failure, not a
+            // bad client request — bubble as 500 so operators retry registry repair,
+            // not callers retrying the same request.
+            if (err instanceof RequiredSkillsMissingError) {
+                throw new ApiError(500, err.message);
+            }
+            throw new ApiError(400, err instanceof Error ? err.message : String(err));
+        }
+        if (previewBytes > MAX_PROMPT_BYTES_ROUTE_LIMIT) {
+            throw new ApiError(400, `estimated prompt size ${previewBytes} bytes exceeds ${MAX_PROMPT_BYTES_ROUTE_LIMIT} limit; ` +
+                `reduce task description or remove some skills from AGENT_PHASES[develop]`);
+        }
+    }
+    // Force a fresh QA review pass; bumps reviewRound only after startSession succeeds.
+    async dispatchReviewToQa(taskId) {
+        const claim = await this.withTaskLock(async () => {
+            if (this.manualReviewInFlight.has(taskId)) {
+                throw new ApiError(409, `Manual review already in progress for task ${taskId}`);
+            }
+            const task = await this.taskStore.get(taskId);
+            if (!task)
+                throw new ApiError(404, `Task ${taskId} not found`);
+            if (!task.prNumber) {
+                throw new ApiError(400, `Task ${taskId} has no PR yet; cannot dispatch review`);
+            }
+            if (!task.branch) {
+                throw new ApiError(400, `Task ${taskId} has no branch; cannot dispatch review`);
+            }
+            // Stale qaAgentId (deleted + recreated QA) → fall back to current partner.
+            let qaId = task.qaAgentId;
+            if (qaId && !this.getAgentConfig(qaId)) {
+                console.warn(`[dispatchReviewToQa] task ${taskId}.qaAgentId="${qaId}" no longer in config; ` +
+                    `falling back to findQaPartner(${task.agentId})`);
+                qaId = undefined;
+            }
+            if (!qaId) {
+                const qa = this.findQaPartner(task.agentId);
+                if (!qa) {
+                    throw new ApiError(400, `Dev ${task.agentId} has no QA partner configured; cannot dispatch review`);
+                }
+                qaId = qa.id;
+            }
+            this.manualReviewInFlight.add(taskId);
+            return { qaId, devAgentId: task.agentId, taskStatusAtClaim: task.status };
+        });
+        try {
+            const { qaId, devAgentId, taskStatusAtClaim } = claim;
+            const isTerminal = TERMINAL_STATUSES.includes(taskStatusAtClaim);
+            const qaPhase = taskStatusAtClaim === 'pending' || taskStatusAtClaim === 'in_progress'
+                ? 'review'
+                : 'recheck';
+            const prevQa = await this.agentStore.get(qaId);
+            if (prevQa?.taskId === taskId) {
+                await this.releaseAgentForTask(qaId, taskId, 'idle');
+            }
+            const acquired = await this.acquireAgentForTask(qaId, taskId, qaPhase);
+            if (!acquired) {
+                throw new ApiError(409, `QA agent ${qaId} is busy or unavailable`);
+            }
+            // dev 被 parked 到 waiting (mode='waiting' 仅 bump updatedAt 不发 C-c 不清 binding)；旧实现
+            // approved/其他状态走两条不同分支，但 release(waiting) 和 markAgentWaiting 实际都走相同的
+            // releaseAgentForTask(waiting) — 现在统一调 markAgentWaiting，devParked 仅作 QA 失败时
+            // emit dev-parked intervention 的旗标。
+            // .catch→false: 旧 approved 分支已有此模式，markAgentWaiting reject (store/lock IO 异常) 时
+            // 不能直接跳出 try/finally — QA 已 acquire (binding+lock) 必须先 release 清理才能 throw。
+            let devParked = false;
+            if (!isTerminal && devAgentId) {
+                const devOk = await this.markAgentWaiting(devAgentId, taskId)
+                    .catch(err => {
+                    console.warn(`[dispatchReviewToQa] markAgentWaiting(dev=${devAgentId}) threw:`, err);
+                    return false;
+                });
+                if (!devOk) {
+                    await this.releaseAgentForTask(qaId, taskId, 'idle')
+                        .catch(() => undefined);
+                    throw new ApiError(500, `Cannot park dev ${devAgentId} into waiting for manual QA review (task status=${taskStatusAtClaim}); QA released`);
+                }
+                devParked = true;
+            }
+            // Start QA before any task mutation so failures don't leave a half-bumped state.
+            let started = false;
+            try {
+                // bypassTaskStatusGate 路径下先 startSession 后 transition；dialog 抛时 task 仍是
+                // taskStatusAtClaim (manual review 入口可能是 approved/fixing/in_progress/pending/review)。
+                // 默认 PHASE_EXPECTED_STATUS[qaPhase]=['review'] 不匹配 → fail-task skip → QA Held + task active
+                // 死锁。显式传 [taskStatusAtClaim] 让 handleDialogPendingFromRuntime 能正确 fail task。
+                started = await this.startSession(taskId, qaId, qaPhase, {
+                    bypassTaskStatusGate: true,
+                    dialogFailFromStatuses: [taskStatusAtClaim],
+                });
+            }
+            catch (err) {
+                // ack_unknown: QA prompt 已发，保留绑定让 operator 接管；其他错误正常 release。
+                if (await this.markAwaitingIfAckUnknown(qaId, err, taskId)) {
+                    // prompt 已发 → QA 可能仍在跑 review → outcome (review.submitted) 会到来。
+                    // 必须先完成"推 task 到 review + 写 qaAgentId + 增 reviewRound"，否则
+                    // review.submitted handler 看 fromStatus 不匹配会丢弃 outcome。
+                    // 严格 fromStatus = [taskStatusAtClaim]：outcome 已被接受导致 task 离开 claim 状态时
+                    // (例如 approved → REQUEST_CHANGES 推到 fixing)，迟到的 cleanup 跳过 transition + bump，
+                    // 避免把已接受的 outcome 回滚到 review。
+                    this.stopSpecMarkerWatcher(taskId);
+                    const transitioned = await this.transitionTaskStatus(taskId, 'review', { fromStatus: [taskStatusAtClaim] });
+                    if (transitioned) {
+                        await this.withTaskLock(async () => {
+                            const fresh = await this.taskStore.get(taskId);
+                            if (!fresh)
+                                return;
+                            await this.taskStore.set({
+                                ...fresh,
+                                reviewRound: fresh.reviewRound + 1,
+                                qaAgentId: qaId,
+                                updatedAt: new Date().toISOString(),
+                            });
+                        });
+                    }
+                }
+                else if (err instanceof EnsureSessionError && err.partial.handled) {
+                    // handleDialogPendingFromRuntime 已 Held QA + fail task + release partners；不能再 release
+                    // 否则 boundTask terminal 让 shouldReleaseHeldBinding 放行清掉仍卡 dialog 的 pane lock。
+                }
+                else {
+                    await this.releaseAgentForTask(qaId, taskId, 'idle')
+                        .catch(() => undefined);
+                    if (devParked)
+                        await this.emitManualReviewDevParkedQaFailedIntervention(devAgentId, taskId);
+                }
+                throw err;
+            }
+            if (!started) {
+                await this.releaseAgentForTask(qaId, taskId, 'idle')
+                    .catch(() => undefined);
+                if (devParked)
+                    await this.emitManualReviewDevParkedQaFailedIntervention(devAgentId, taskId);
+                throw new ApiError(500, `Failed to start QA review session for ${taskId}`);
+            }
+            this.stopSpecMarkerWatcher(taskId);
+            await this.withTaskLock(async () => {
+                const fresh = await this.taskStore.get(taskId);
+                if (!fresh)
+                    return;
+                await this.taskStore.set({
+                    ...fresh,
+                    reviewRound: fresh.reviewRound + 1,
+                    qaAgentId: qaId,
+                    updatedAt: new Date().toISOString(),
+                });
+            });
+            await this.transitionTaskStatus(taskId, 'review', { fromStatus: ['pending', 'in_progress', 'review', 'fixing', 'approved'] });
+            const final = await this.taskStore.get(taskId);
+            return final;
+        }
+        finally {
+            this.manualReviewInFlight.delete(taskId);
+        }
+    }
+    async emitManualReviewDevParkedQaFailedIntervention(agentId, expectedTaskId) {
+        if (!agentId)
+            return;
+        const cur = await this.agentStore.get(agentId);
+        if (!cur || cur.taskId !== expectedTaskId)
+            return;
+        await this.safeEmit({
+            id: '',
+            type: 'human.intervention',
+            timestamp: new Date().toISOString(),
+            projectId: cur.projectId,
+            agentId,
+            taskId: expectedTaskId,
+            data: {
+                phase: 'manual-review-dev-parked-qa-failed',
+                note: 'Manual QA dispatch parked the dev agent into waiting; QA then failed to start. ' +
+                    'Dev binding is kept but no new prompt is running — re-dispatch the manual review or cancel the task.',
+            },
+        });
+    }
+    async retryTask(taskId) {
+        const old = await this.withTaskLock(async () => {
+            const t = await this.taskStore.get(taskId);
+            if (!t)
+                throw new ApiError(404, 'Task not found');
+            if (!TERMINAL_STATUSES.includes(t.status)) {
+                throw new ApiError(409, `Task ${taskId} cannot be retried in status "${t.status}"; cancel it first or wait for completion`);
+            }
+            return t;
+        });
+        const input = {
+            title: old.title,
+            description: old.description,
+            preferredAgentId: old.preferredAgentId,
+        };
+        await this.validateTaskDispatch(old.projectId, input);
+        return this.createAndStartTask(old.projectId, input);
+    }
+    async editTask(taskId, patch) {
+        let projectIdToDrain;
+        const result = await this.withTaskLock(async () => {
+            const task = await this.taskStore.get(taskId);
+            if (!task)
+                throw new ApiError(404, 'Task not found');
+            if (task.status !== 'pending') {
+                throw new ApiError(409, `Task not editable in status ${task.status}`);
+            }
+            let preferredChanged = false;
+            if (patch.title !== undefined)
+                task.title = patch.title;
+            if (patch.description !== undefined)
+                task.description = patch.description;
+            if (patch.preferredAgentId !== undefined && patch.preferredAgentId !== task.preferredAgentId) {
+                const cfg = this.getAgentConfig(patch.preferredAgentId);
+                if (!cfg)
+                    throw new ApiError(400, `Unknown agent: ${patch.preferredAgentId}`);
+                if (cfg.projectId !== task.projectId) {
+                    throw new ApiError(400, `Agent not in project ${task.projectId}`);
+                }
+                if (cfg.role !== 'dev')
+                    throw new ApiError(400, `Agent is not dev role`);
+                task.preferredAgentId = patch.preferredAgentId;
+                task.qaAgentId = this.findQaPartner(patch.preferredAgentId)?.id;
+                preferredChanged = true;
+            }
+            task.updatedAt = new Date().toISOString();
+            await this.taskStore.set(task);
+            if (preferredChanged)
+                projectIdToDrain = task.projectId;
+            return task;
+        });
+        if (projectIdToDrain) {
+            try {
+                await this.drainQueue(projectIdToDrain);
+            }
+            catch (err) {
+                console.error(`[AgentManager] drainQueue failed for ${projectIdToDrain}:`, err);
+            }
+            const refreshed = await this.taskStore.get(taskId);
+            if (refreshed)
+                return refreshed;
+        }
+        return result;
+    }
+    async mergePr(taskId, opts = {}) {
+        const task = await this.taskStore.get(taskId);
+        if (!task || !task.prNumber) {
+            throw new Error(`mergePr: no PR number for task ${taskId}`);
+        }
+        const project = this.getProjectConfig(task.projectId);
+        if (!project) {
+            throw new Error(`mergePr: unknown project ${task.projectId}`);
+        }
+        const matchHead = opts.matchHeadSha
+            ? ` --match-head-commit ${shellQuote(opts.matchHeadSha)}`
+            : '';
+        const result = await this.platformRunner.exec(`gh pr merge ${task.prNumber} --repo ${shellQuote(project.repo)}${matchHead} --squash --delete-branch`);
+        if (result.exitCode !== 0) {
+            throw new Error(`gh pr merge failed for PR #${task.prNumber}: ${result.stderr || result.stdout}`);
+        }
+    }
+    async cleanupAfterMerge(taskId) {
+        const task = await this.taskStore.get(taskId);
+        if (!task || !task.agentId)
+            return;
+        const dev = this.getAgentConfig(task.agentId);
+        if (!dev)
+            return;
+        this.specReviewMarkerWatcher?.stop(taskId);
+        // Release BEFORE dispatch: 'idle' release removes the worktree, and the cleanup
+        // must work in the stable post-release state (server-side git ops use the main
+        // repo clone, not the worktree). dispatch reads state again so it survives this.
+        try {
+            await this.releaseAgentForTask(task.agentId, taskId, 'idle');
+        }
+        catch (err) {
+            console.warn(`[AgentManager] cleanupAfterMerge: releaseAgentForTask(${task.agentId}, ${taskId}) failed:`, err);
+        }
+        if (task.prNumber && task.branch) {
+            const ctx = {
+                prNumber: task.prNumber,
+                taskId: task.id,
+                branch: task.branch,
+            };
+            await this.dispatchPostMergeCleanup(task.agentId, ctx).catch(err => console.warn(`[AgentManager] cleanupAfterMerge: dispatchPostMergeCleanup(${task.agentId}) failed:`, err));
+        }
+    }
+    // Server-side branch delete + pane notification + /compact slash command. Server-side
+    // path is required: the caller's releaseAgentForTask('idle') just removed the worktree,
+    // so the agent itself cannot reliably cd + run git from inside the pane.
+    async dispatchPostMergeCleanup(agentId, ctx) {
+        const state = await this.agentStore.get(agentId);
+        if (!state?.paneId)
+            return;
+        // Late-arriving pr.merged guard: APPROVE may have already released QA, drainQueue may have
+        // re-assigned this pane to a new review. Refuse to dispatch into a pane bound to a different task.
+        if (state.taskId && state.taskId !== ctx.taskId)
+            return;
+        const agent = this.getAgentConfig(agentId);
+        if (!agent)
+            return;
+        const paneId = state.paneId;
+        const runner = this.createRunnerFor(agent);
+        const cleanupResult = state.repoPath
+            ? await this.deleteLocalBranchInRepo(runner, state.repoPath, ctx.branch, agentId)
+            : { outcome: 'skipped', detail: 'agent has no repoPath in binding' };
+        // deleteLocalBranchInRepo opens a long await window. drainQueue / createTask can rebind
+        // this pane in the meantime — re-validate before any pane write. The lock makes re-check
+        // + inject mutually exclusive with startSession, so a binding cannot land between them.
+        const tmux = new TmuxManager(runner);
+        const prompt = buildPostMergeCleanupPrompt(ctx, cleanupResult);
+        const acquired = await this.lockManager.acquire(agentId);
+        if (!acquired)
+            return;
+        try {
+            const after = await this.agentStore.get(agentId);
+            if (!after || after.paneId !== paneId)
+                return;
+            if (after.taskId && after.taskId !== ctx.taskId)
+                return;
+            await tmux.injectPrompt(paneId, prompt, agentId);
+            await tmux.sendEnter(paneId);
+        }
+        finally {
+            await this.lockManager.release(agentId);
+        }
+        const runtime = agentRuntimeKindFor(agent);
+        void this.sendCompactWhenIdle(tmux, paneId, agentId, ctx.taskId, runtime).catch(err => console.warn(`[AgentManager] sendCompactWhenIdle(${agentId}) failed:`, err));
+    }
+    // shellQuote prevents injection. Three outcomes the caller must distinguish so the
+    // notification prompt to the agent doesn't lie about a deletion that actually failed:
+    //   - deleted: branch ref was removed (or no longer exists at the end of the call).
+    //   - absent:  branch wasn't there at all (auto-delete-head-branches, never landed locally).
+    //   - failed:  worktree still occupies the ref, permissions, etc. — agent must NOT be told "cleaned".
+    async deleteLocalBranchInRepo(runner, repoPath, branch, agentId) {
+        // --expire=now: bare `git worktree prune` honors gc.worktreePruneExpire (default 3 months),
+        // so a worktree that the release just removed could still be tracked as occupying the ref.
+        const fetchCmd = `cd ${shellQuote(repoPath)} && git fetch --prune origin && git worktree prune --expire=now`;
+        try {
+            const fetchResult = await runner.exec(fetchCmd, { timeout: this.postMergeFetchTimeoutMs });
+            if (fetchResult.exitCode !== 0) {
+                console.warn(`[AgentManager] deleteLocalBranchInRepo(${agentId}, ${branch}): fetch/prune exit=${fetchResult.exitCode} ` +
+                    `stderr=${fetchResult.stderr.trim()}`);
+            }
+        }
+        catch (err) {
+            console.warn(`[AgentManager] deleteLocalBranchInRepo(${agentId}, ${branch}) fetch/prune threw:`, err);
+        }
+        const delCmd = `cd ${shellQuote(repoPath)} && git branch -D ${shellQuote(branch)}`;
+        try {
+            const delResult = await runner.exec(delCmd, { timeout: this.postMergeBranchTimeoutMs });
+            if (delResult.exitCode === 0) {
+                return { outcome: 'deleted', detail: delResult.stdout.trim() };
+            }
+            if (/not found|not a valid|no such branch/i.test(delResult.stderr)) {
+                return { outcome: 'absent', detail: delResult.stderr.trim() };
+            }
+            console.warn(`[AgentManager] deleteLocalBranchInRepo(${agentId}, ${branch}): branch -D exit=${delResult.exitCode} ` +
+                `stderr=${delResult.stderr.trim()}`);
+            return { outcome: 'failed', detail: delResult.stderr.trim() || `exit ${delResult.exitCode}` };
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            console.warn(`[AgentManager] deleteLocalBranchInRepo(${agentId}, ${branch}) branch -D threw:`, err);
+            return { outcome: 'failed', detail };
+        }
+    }
+    async sendCompactWhenIdle(tmux, paneId, agentId, originalTaskId, runtime) {
+        await this.waitForReplPromptReady(tmux, paneId, runtime, this.compactIdleWaitMs);
+        // Atomic check + send: lockManager.acquire makes "read binding + sendKeys" mutually
+        // exclusive with startSession (which is what drainQueue uses to re-bind this pane).
+        // Failing to acquire means a dispatch is already in flight — let it own the pane.
+        const acquired = await this.lockManager.acquire(agentId);
+        if (!acquired)
+            return;
+        try {
+            const latest = await this.agentStore.get(agentId);
+            if (!latest || latest.paneId !== paneId)
+                return;
+            if (latest.taskId && latest.taskId !== originalTaskId)
+                return;
+            await tmux.sendKeysLiteral(paneId, '/compact');
+            await tmux.sendEnter(paneId);
+        }
+        finally {
+            await this.lockManager.release(agentId);
+        }
+    }
+    // pane_current_command 是 runtime 是否仍活的权威信号（不被 viewport stale frame 骗）。
+    // anchor 在 codex busy 屏（`Working on it…\n  esc to interrupt`）不存在，所以 busy 状态只看
+    // procTitle；只有准备返回 idle 时才用 anchor 作双重证据，挡 stale-frame + shell 误报。
+    // 入口先等一拍：上一步刚 sendEnter，给 runtime 时间进入 busy，避免观察到假 idle。
+    async waitForReplPromptReady(tmux, paneId, runtime, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        await tmux.waitReplReady(paneId, runtime, {
+            timeoutMs,
+            intervalMs: this.compactIdlePollMs,
+        });
+        await new Promise(r => setTimeout(r, this.compactIdlePollMs));
+        while (true) {
+            const current = await tmux.displayMessage(paneId, '#{pane_current_command}');
+            if (!hasReplProcTitle(current, runtime)) {
+                throw new Error(`waitForReplPromptReady: pane ${paneId} pane_current_command=${current.trim()} (not runtime, REPL may have exited)`);
+            }
+            const cap = await tmux.capturePaneById(paneId, { ansi: false, scrollback: 0 });
+            if (detectRuntimeMenu(cap) || detectStartupDialog(cap)) {
+                throw new Error(`waitForReplPromptReady: pane ${paneId} shows menu/dialog, not a ready REPL prompt`);
+            }
+            if (!detectReplActiveBusy(cap)) {
+                if (!hasReplReadyAnchor(cap, runtime)) {
+                    throw new Error(`waitForReplPromptReady: pane ${paneId} observed idle but no ready anchor (stale frame?)`);
+                }
+                return;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`waitForReplPromptReady: pane ${paneId} stayed busy past ${timeoutMs}ms`);
+            }
+            await new Promise(r => setTimeout(r, this.compactIdlePollMs));
+        }
+    }
+    stopSpecMarkerWatcher(taskId) {
+        this.specReviewMarkerWatcher?.stop(taskId);
+    }
+    // Prompt build (via task.specMarkerToken) and watcher must share the same token.
+    async armSpecMarkerWatcher(taskId, agentId, kind, token) {
+        if (!this.specReviewMarkerWatcher)
+            return;
+        const task = await this.taskStore.get(taskId);
+        if (!task)
+            return;
+        try {
+            await this.specReviewMarkerWatcher.start({
+                taskId,
+                projectId: task.projectId,
+                agentId,
+                kind,
+                token,
+            });
+        }
+        catch (err) {
+            console.warn(`[AgentManager] armSpecMarkerWatcher(task=${taskId}, kind=${kind}) failed:`, err);
+        }
+    }
+    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-ready guard: 一旦 task 离开 pre-spec 阶段 (phase='code' 或其他
+            // 非 'spec'/undefined 值)，迟到的 spec-ready marker 不应再 dispatch review。
+            // 允许 phase==='spec' 是预留 dev 在 fix-complete 后再 emit spec-ready 的扩展点。
+            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-ready-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: createMarkerToken(),
+                newRound: (task.specReviewRound ?? 0) + 1,
+                originalStatus: task.status,
+                // 记录原 spec-ready token — pre-spec entry rollback 时 restore,
+                // 让 dev 后续 spec-ready marker (with 原 token) 经 handler freshness gate 通过 → auto retry。
+                originalToken: task.specMarkerToken,
+                // 回滚时 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 没做时，
+        // armRecoveredSpecMarkers 会读旧 status/token 推断错 kind/token，新 marker 无法匹配 → 链路死。
+        const transition = await this.transitionTaskStatus(taskId, 'review', { fromStatus: ['in_progress', 'fixing', 'pending'] }, {
+            specReviewRound: newRound,
+            specMarkerToken: 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,
+                specMarkerToken: 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: arm watcher。spec-ready 已被消费，先 disarm 防止 dev 之后无关 marker 误触发。
+        this.stopSpecMarkerWatcher(taskId);
+        await this.armSpecMarkerWatcher(taskId, qaId, 'spec-review-complete', newToken);
+        return await this.taskStore.get(taskId);
+    }
+    // startSession 失败回滚：
+    // - pre-spec entry: restore originalToken 让 dev 后续 spec-ready marker 经 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'] }, { specMarkerToken: undefined, specReviewRound: originalRound });
+            return;
+        }
+        await this.transitionTaskStatus(taskId, originalStatus, { fromStatus: ['review'] }, {
+            specMarkerToken: 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: createMarkerToken(),
+                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 之前；否则崩溃后 armRecoveredSpecMarkers 读旧 token,
+        // 与 dev 输出的 newToken marker 不匹配 → 链路死。
+        const transition = await this.transitionTaskStatus(taskId, 'fixing', { fromStatus: ['review'] }, { specMarkerToken: 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,
+                specMarkerToken: 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: arm watcher。
+        await this.armSpecMarkerWatcher(taskId, devAgentId, 'spec-fix-complete', 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'] }, { specMarkerToken: undefined });
+    }
+    async transitionToCodePhase(taskId) {
+        const task = await this.taskStore.get(taskId);
+        if (!task)
+            return null;
+        const devAgentId = task.agentId;
+        if (!devAgentId)
+            return null;
+        // Atomic transition + persist: 旧版先 transition 再 updateTask, 中间崩溃 task 卡在
+        // (phase='spec', status='in_progress') — armRecoveredSpecMarkers 三个 case 都不匹配,
+        // freshness gate 也拒所有 spec.* event, 任务 stranded 无 auto-recovery。
+        const transition = await this.transitionTaskStatus(taskId, 'in_progress', { fromStatus: ['review', 'fixing'] }, { phase: 'code', specMarkerToken: undefined });
+        if (!transition)
+            return null;
+        this.stopSpecMarkerWatcher(taskId);
+        if (task.qaAgentId) {
+            // release 失败留 stale qa binding → emit intervention 让其可见。
+            const released = await this.releaseAgentForTask(task.qaAgentId, taskId, 'idle')
+                .catch(() => false);
+            if (!released) {
+                await this.safeEmit({
+                    id: '',
+                    type: 'human.intervention',
+                    timestamp: new Date().toISOString(),
+                    projectId: task.projectId,
+                    agentId: task.qaAgentId,
+                    taskId,
+                    data: { phase: 'code-phase-qa-release-failed', qaAgentId: task.qaAgentId },
+                });
+            }
+        }
+        const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'code');
+        if (!acquired) {
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId: task.projectId,
+                agentId: devAgentId,
+                taskId,
+                data: { phase: 'code-dev-acquire-failed', devAgentId },
+            });
+            return null;
+        }
+        let resumed = false;
+        try {
+            resumed = await this.continueSession(taskId, devAgentId, 'code');
+        }
+        catch (err) {
+            // 同 spec-review/spec-fix：DispatchTerminalError 委托给 failTaskForDispatchError
+            // （ack_unknown → markAwaitingHuman；其他 reason → release + task failed）。
+            if (err instanceof DispatchTerminalError) {
+                await this.failTaskForDispatchError(taskId, 'code', devAgentId, err);
+            }
+            console.error(`[AgentManager] transitionToCodePhase continueSession(dev=${devAgentId}) failed:`, err);
+            throw err;
+        }
+        if (!resumed) {
+            await this.safeEmit({
+                id: '',
+                type: 'human.intervention',
+                timestamp: new Date().toISOString(),
+                projectId: task.projectId,
+                agentId: devAgentId,
+                taskId,
+                data: { phase: 'code-resume-failed', devAgentId },
+            });
+            return null;
+        }
+        return await this.taskStore.get(taskId);
+    }
+}
+function buildAgentIndex(config) {
+    const index = new Map();
+    for (const project of config.project) {
+        for (const pair of project.agent) {
+            for (const agent of pair) {
+                index.set(agent.id, { ...agent, projectId: project.id });
+            }
+        }
+    }
+    return index;
+}
+//# sourceMappingURL=manager.js.map