baxian 1.2.55 → 1.2.57

package/dist/agent/manager.js

@@ -1,19 +1,20 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { join, normalize } from 'node:path';
 import { tmpdir } from 'node:os';
 import { createSignalToken } from './phase-signal.js';
 import { tmuxInstallHint } from './preflight.js';
-import { BRANCH_PREFIX, isValidBranchName, PHASE_EXPECTED_STATUS, PHASE_REQUIRES_AGENT_BOUND_TO_TASK, TASK_TERMINAL_STATUSES as TERMINAL_STATUSES, TASK_ACTIVE_STATUS_SET as ACTIVE_TASK_STATUSES, isGitHubRepo, parseGitRemote, repoSlug, } from '../shared/index.js';
+import { BRANCH_PREFIX, isValidBranchName, PHASE_EXPECTED_STATUS, PHASE_REQUIRES_AGENT_BOUND_TO_TASK, TASK_TERMINAL_STATUSES as TERMINAL_STATUSES, TASK_ACTIVE_STATUS_SET as ACTIVE_TASK_STATUSES, TASK_OWNER_ROLES, isSpecStagePhase, isGitHubRepo, parseGitRemote, repoSlug, } 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, resolveAgentHost, hostGroupKey } from './runner.js';
+import { createRunner, LocalRunner, shellQuote, resolveAgentHost, hostGroupKey, workdirHostGroupKey, } from './runner.js';
 import { GH_EXEC_TIMEOUT_MS, GIT_NET_ENV, execNetwork } from './net-exec.js';
 import { findForeignTaskTip } from './lineage.js';
 import { imageFilename, agentHostPath, writeImageToHost } from './image-input.js';
 import { TmuxManager, ReplNotReadyError, detectStartupDialog, detectRuntimeMenu, runtimeBusyCheck, hasRuntimeReadyView, hasReplProcTitle, hasOscTitleWorking, hasOscTitleIdle, screenAllowsTitleIdle, } from './tmux.js';
 import { BranchManager, DirtyWorkdirError, ReviewHeadMismatchError } from './branch.js';
-import { RepoStore, createRepoStoreCache } from './repo-store.js';
+import { RepoStore, createRepoStoreCache, moveFileIntoPlace, stageFileGuarded } from './repo-store.js';
 import { PhaseSignalWatcher } from './phase-signal-watcher.js';
 import { ReviewTransport, resolveServerPayloads } from './review-transport.js';
 import { buildPromptInline, buildGreetingPrompt, PromptSizeError, RequiredSkillsMissingError, MAX_PROMPT_BYTES_ROUTE_LIMIT, } from './prompt.js';
@@ -85,6 +86,10 @@ export function buildLaunchCommand(agent) {
     }
     return segments.join(' ');
 }
+// cd re-resolves by pathname: a reused pane shell may sit on a deleted-and-recreated cwd inode.
+export function launchCommandIn(dir, agent) {
+    return `cd ${shellQuote(dir)} && ${buildLaunchCommand(agent)}`;
+}
 function agentRuntimeKindFor(agent) {
     return agent.runtime;
 }
@@ -137,7 +142,7 @@ const DEFAULT_DISPATCH_ACK_TIMEOUT_MS = 30_000;
 const DEFAULT_DISPATCH_SETTLE_TIMEOUT_MS = 3_000;
 const GH_NET = { timeout: GH_EXEC_TIMEOUT_MS, retries: 1 };
 const MANUAL_SERVER_REVIEW_STATUSES = ['in_progress', 'review', 'fixing'];
-const IMAGE_DISPATCH_PHASES = new Set(['develop', 'code', 'fix', 'server-feedback']);
+const IMAGE_DISPATCH_PHASES = new Set(['develop', 'research', 'code', 'fix', 'server-feedback']);
 const RUNTIME_LIVENESS_SAMPLES = 3;
 export function canDispatchWithBinding(binding) {
     return !binding?.taskId && !binding?.creationToken && binding?.status !== 'awaiting_human';
@@ -269,6 +274,17 @@ export class AgentManager {
             throw new Error(`Agent ${agentId} ownership changed for task ${taskId}; operation aborted`);
         }
     }
+    async assertTaskGeneration(agentId, taskId, lockToken, workdir) {
+        const state = await this.agentStore.get(agentId);
+        if (!state
+            || state.taskId !== taskId
+            || state.lockToken !== lockToken
+            || state.workdir !== workdir) {
+            throw new Error(`Agent ${agentId} task generation changed for ${taskId}; operation aborted`);
+        }
+        await this.assertTaskLockOwner(agentId, taskId, lockToken);
+        return state;
+    }
     getReviewStore() {
         return this.reviewStore;
     }
@@ -300,6 +316,14 @@ export class AgentManager {
         });
         return this.reviewTransportInstance;
     }
+    async prepareDispatchArtifacts(agent, workdir, phase, opts) {
+        const transport = this.getReviewTransport();
+        if (!opts.preserveOutputs)
+            await transport.clearDispatchOutputs(agent, workdir, phase);
+        if (opts.specDocuments) {
+            await transport.replaceSpecDocuments(agent, workdir, opts.specDocuments, opts.assertOwner);
+        }
+    }
     bindingWorkdirCache = new Map();
     async refreshWorkdirCacheFor(agentId) {
         const state = await this.agentStore.get(agentId);
@@ -342,9 +366,28 @@ export class AgentManager {
     }
     replaceConfig(validated) {
         const config = prepareConfig(validated);
+        const previousConfig = this.config;
+        const previousIndex = this.agentIndex;
+        const nextIndex = buildAgentIndex(config);
+        for (const [ownerKey, agentId] of this.repoCache.owners) {
+            const previous = previousIndex.get(agentId);
+            const next = nextIndex.get(agentId);
+            const previousHost = previous
+                ? resolveAgentHost(previousConfig.host, previous.host)
+                : undefined;
+            const nextHost = next ? resolveAgentHost(config.host, next.host) : undefined;
+            const previousOwnerConfig = previous
+                ? `${workdirHostGroupKey(previous.mode, previousHost)}\0${previous.workdir ? normalize(previous.workdir) : ''}`
+                : null;
+            const nextOwnerConfig = next
+                ? `${workdirHostGroupKey(next.mode, nextHost)}\0${next.workdir ? normalize(next.workdir) : ''}`
+                : null;
+            if (previousOwnerConfig === null || previousOwnerConfig !== nextOwnerConfig) {
+                this.repoCache.owners.delete(ownerKey);
+            }
+        }
         this.config = config;
-        this.agentIndex = buildAgentIndex(config);
-        this.repoCache.owners.clear();
+        this.agentIndex = nextIndex;
     }
     getConfig() {
         return this.config;
@@ -411,8 +454,11 @@ export class AgentManager {
                 `if tmux is missing, ${tmuxInstallHint(agent.projectId)}`);
         }
         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`);
+            const reclaimed = await this.runUnderSessionLifecycle(agentId, () => this.reclaimHalfCreatedSession(tmux, agentId));
+            if (!reclaimed) {
+                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, runner, agent, agentId, workdir, workdir);
@@ -432,8 +478,77 @@ export class AgentManager {
         // before the skill runs. Message-body payloads are not expanded, so this path is injection-safe.
         await this.runUnderSkillDirLock(this.skillDirLockKey(agent, workdir), async () => {
             await this.ensureSkillDirSafe(runner, workdir, subdir);
-            await this.skillRegistry.materialize((path, content) => this.atomicWriteFile(runner, path, content), destRoot);
+            await this.skillRegistry.materialize((path, content) => this.atomicWriteFile(runner, workdir, path, content), destRoot);
+        });
+    }
+    // A rollback only kills if no adoption bumped the generation since its create.
+    sessionLifecycleChain = new Map();
+    adoptGeneration = new Map();
+    runUnderSessionLifecycle(agentId, fn) {
+        const prev = this.sessionLifecycleChain.get(agentId) ?? Promise.resolve();
+        const cur = prev.then(fn, fn);
+        const settled = cur.then(() => undefined, () => undefined);
+        this.sessionLifecycleChain.set(agentId, settled);
+        void settled.finally(() => {
+            if (this.sessionLifecycleChain.get(agentId) === settled)
+                this.sessionLifecycleChain.delete(agentId);
         });
+        return cur;
+    }
+    // Inside the lifecycle lock, a generation bump since create means handoff — stand down.
+    async rollbackCreatedSession(agentId, partial, reason, opts = {}) {
+        await this.runUnderSessionLifecycle(agentId, async () => {
+            try {
+                const ref = partial.sessionRef;
+                if (!ref) {
+                    console.warn(`[AgentManager] ${agentId} rollback (${reason}) skipped: no session ref recorded`);
+                    return;
+                }
+                if ((this.adoptGeneration.get(agentId) ?? 0) !== (partial.genAtCreate ?? 0)) {
+                    console.warn(`[AgentManager] ${agentId} rollback (${reason}) skipped: session adopted since create — leaving it to its successor`);
+                    return;
+                }
+                if (opts.expectCreationToken !== undefined) {
+                    let fresh;
+                    try {
+                        fresh = await this.agentStore.get(agentId);
+                    }
+                    catch (storeErr) {
+                        console.warn(`[AgentManager] ${agentId} rollback (${reason}) skipped: agent store read failed — session left in place:`, storeErr);
+                        return;
+                    }
+                    if (!fresh) {
+                        console.warn(`[AgentManager] ${agentId} rollback (${reason}) skipped: agent record gone`);
+                        return;
+                    }
+                    if (fresh.creationToken !== opts.expectCreationToken) {
+                        console.warn(`[AgentManager] ${agentId} rollback (${reason}) skipped: creationToken rotated — leaving the session to its successor`);
+                        return;
+                    }
+                }
+                const cfg = this.getAgentConfig(agentId);
+                if (!cfg) {
+                    console.warn(`[AgentManager] ${agentId} rollback (${reason}) skipped: agent no longer in config`);
+                    return;
+                }
+                const runner = this.createRunnerFor(cfg);
+                const outcome = await new TmuxManager(runner).killSessionRef(ref);
+                if (outcome === 'stale-server') {
+                    console.warn(`[AgentManager] ${agentId} rollback (${reason}): tmux server generation changed — leaving session ${ref.sessionId} untouched`);
+                }
+                else if (outcome === 'killed') {
+                    console.warn(`[AgentManager] ${agentId} rollback (${reason}): killed created session ${ref.sessionId}`);
+                }
+            }
+            catch (cleanupErr) {
+                console.warn(`[AgentManager] created-session rollback (${reason}) failed for ${agentId}:`, cleanupErr);
+            }
+        });
+    }
+    async rollbackEnsureSessionFailure(agentId, err, reason) {
+        if (!(err instanceof EnsureSessionError) || !err.partial.createdSession)
+            return;
+        await this.rollbackCreatedSession(agentId, err.partial, reason);
     }
     skillDirChain = new Map();
     skillDirLockKey(agent, workdir) {
@@ -453,19 +568,21 @@ export class AgentManager {
         });
         return run;
     }
-    async atomicWriteFile(runner, finalPath, content) {
-        const tmp = `${finalPath}.baxian-tmp`;
-        await runner.writeFile(tmp, content);
-        const mv = `mv -f ${shellQuote(tmp)} ${shellQuote(finalPath)}`;
-        const res = await runner.exec(`sh -c ${shellQuote(mv)}`);
-        if (res.exitCode !== 0) {
-            throw new Error(`atomic skill write failed (${finalPath}): ${res.stderr || 'unknown error'}`);
+    async atomicWriteFile(runner, workdir, finalPath, content) {
+        const tmp = `${finalPath}.baxian-tmp-${randomBytes(6).toString('hex')}`;
+        try {
+            await stageFileGuarded(runner, workdir, tmp, content);
+            await moveFileIntoPlace(runner, tmp, finalPath, { guardRoot: workdir });
+        }
+        catch (err) {
+            throw new Error(`atomic skill write failed (${finalPath}): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     async ensureSkillDirSafe(runner, workdir, subdir) {
         const top = subdir.split('/')[0];
         const keep = this.skillRegistry.names().map((n) => `! -name ${shellQuote(n)}`).join(' ');
-        const inner = `cd ${shellQuote(workdir)} && ` +
+        const inner = `[ ! -L ${shellQuote(workdir)} ] && [ -d ${shellQuote(workdir)} ] && ` +
+            `cd ${shellQuote(workdir)} && ` +
             `for d in ${top} ${subdir}; do if [ -L "$d" ]; then ` +
             `printf 'baxian: %s is a symlink -> %s; replace it with a real directory\\n' "$d" "$(readlink "$d")" >&2; ` +
             `exit 3; fi; done && ` +
@@ -478,10 +595,12 @@ export class AgentManager {
             throw new Error(`failed to prepare a symlink-safe ${subdir} in ${workdir}: ${res.stderr || 'unknown error'}`);
         }
     }
-    async tagSessionSkillsVersion(tmux, agentId) {
+    async tagSessionSkillsVersion(tmux, agentId, ref) {
         if (this.skillRegistry.names().length === 0)
             return;
-        await tmux.setOption(agentId, '@baxian-skills-version', this.skillRegistry.contentHash());
+        await this.setSessionOptions(tmux, agentId, ref, [
+            ['@baxian-skills-version', this.skillRegistry.contentHash()],
+        ]);
     }
     async replSkillsStale(tmux, agentId) {
         if (this.skillRegistry.names().length === 0)
@@ -490,7 +609,8 @@ export class AgentManager {
         return tagged !== this.skillRegistry.contentHash();
     }
     async excludeInjectedSkills(runner, workdir, subdir) {
-        const inner = `cd ${shellQuote(workdir)} && ` +
+        const inner = `[ ! -L ${shellQuote(workdir)} ] && [ -d ${shellQuote(workdir)} ] && ` +
+            `cd ${shellQuote(workdir)} && ` +
             `if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then echo BX_SKILLS_NON_GIT; exit 0; fi; ` +
             `tracked="$(git ls-files -- ${shellQuote(`${subdir}/baxian-*`)} 2>/dev/null | head -5)"; ` +
             `if [ -n "$tracked" ]; then printf 'BX_SKILLS_TRACKED %s\\n' "$tracked" | head -1; exit 0; fi; ` +
@@ -513,35 +633,46 @@ export class AgentManager {
         }
         throw new Error(`cannot make injected skills invisible to Git in ${workdir}: ${verdict || 'no probe output'}`);
     }
-    async pinRuntimeSessionOptions(tmux, agentId) {
-        await tmux.setOption(agentId, 'prefix', 'C-b');
-        await tmux.setOption(agentId, 'prefix2', 'None');
-        await tmux.setOption(agentId, 'mouse', 'on');
+    runtimePinEntries() {
+        return [
+            ['prefix', 'C-b'],
+            ['prefix2', 'None'],
+            ['mouse', 'on'],
+        ];
     }
-    async pinFreshSessionOptions(tmux, agentId) {
-        await tmux.setOption(agentId, 'window-size', 'latest');
-        await this.pinRuntimeSessionOptions(tmux, agentId);
+    // A name (or even a bare $id) can rebind to a same-name successor mid-flight;
+    // every option write goes through the identity-checked by-ref batch.
+    async setSessionOptions(tmux, agentId, ref, entries) {
+        const outcome = await tmux.setSessionOptionsIfAlive(ref, entries);
+        if (outcome === 'gone') {
+            throw new Error(`tmux session ${ref.sessionId} (${agentId}) vanished before its options could be applied`);
+        }
     }
     async buildFreshSession(tmux, agent, agentId, workdir, sessionDir = workdir) {
         return this.runUnderSkillDirLock(this.skillDirLockKey(agent, sessionDir), () => this.buildFreshSessionLocked(tmux, agent, agentId, workdir, sessionDir));
     }
     async buildFreshSessionLocked(tmux, agent, agentId, workdir, sessionDir) {
         let createdSession = false;
+        let createdRef;
+        const genAtCreate = this.adoptGeneration.get(agentId) ?? 0;
         const runtime = agentRuntimeKindFor(agent);
         try {
-            await tmux.createSession(agentId, sessionDir);
+            createdRef = await tmux.createSession(agentId, sessionDir);
             createdSession = true;
-            await tmux.setOption(agentId, '@baxian-agent-id', agentId);
-            await tmux.setOption(agentId, '@baxian-runtime', agent.runtime);
-            await tmux.setOption(agentId, WORKDIR_SESSION_OPTION, sessionDir);
-            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 this.setSessionOptions(tmux, agentId, createdRef, [
+                ['@baxian-agent-id', agentId],
+                ['@baxian-runtime', agent.runtime],
+                [WORKDIR_SESSION_OPTION, sessionDir],
+                ['allow-passthrough', 'on'],
+                ['set-titles', 'on'],
+                ['window-size', 'latest'],
+                ...this.runtimePinEntries(),
+                ['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`);
+            const paneId = await tmux.getSinglePaneIdByRef(createdRef);
+            await tmux.sendKeysToPane(paneId, `${launchCommandIn(sessionDir, agent)}\n`);
             await tmux.handleTrustDialog(paneId, runtime, {
                 timeoutMs: this.bootstrapTimeoutsMs.trustDialog,
             });
@@ -549,11 +680,13 @@ export class AgentManager {
                 timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
                 scrollback: 0,
             });
-            await this.tagSessionSkillsVersion(tmux, agentId);
-            return { ok: true, createdSession: true, freshRuntime: true, paneId, workdir };
+            await this.tagSessionSkillsVersion(tmux, agentId, createdRef);
+            return { ok: true, createdSession: true, freshRuntime: true, paneId, workdir, sessionRef: createdRef };
         }
         catch (err) {
-            const partial = { createdSession, agentId };
+            const partial = { createdSession, agentId, genAtCreate };
+            if (createdRef)
+                partial.sessionRef = createdRef;
             if (err instanceof ReplNotReadyError) {
                 partial.lastScreen = err.lastScreen;
                 if (createdSession && detectStartupDialog(err.lastScreen, runtime)) {
@@ -569,22 +702,12 @@ export class AgentManager {
             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');
             if (!(await this.runGreetingHandshake(agentId, cfgAtStart, result.paneId))) {
                 const current = await this.agentStore.get(agentId);
                 if (current && current.creationToken !== creationToken) {
-                    console.warn(`[bootstrap] ${agentId} creationToken changed during greeting — killing orphan session`);
-                    await tryKillOrphanSession('greeting-failure token mismatch');
+                    console.warn(`[bootstrap] ${agentId} creationToken changed during greeting — leaving the session to its successor`);
                     return;
                 }
                 await this.markGreetingFailed(agentId, creationToken);
@@ -605,8 +728,7 @@ export class AgentManager {
                 };
             });
             if (!resolvedExisting) {
-                console.warn(`[bootstrap] ${agentId} creationToken mismatch on success — killing orphan session`);
-                await tryKillOrphanSession('post-success token mismatch');
+                console.warn(`[bootstrap] ${agentId} creationToken mismatch on success — leaving the session to its successor`);
                 return;
             }
             await this.safeEmit({
@@ -624,8 +746,7 @@ export class AgentManager {
                 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');
+                        console.warn(`[bootstrap] ${agentId} dialog-path token mismatch — leaving the session to its successor`);
                         return;
                     }
                 }
@@ -636,7 +757,9 @@ export class AgentManager {
                 return;
             }
             if (err instanceof EnsureSessionError && err.partial.createdSession) {
-                await tryKillOrphanSession('hard-failure rollback');
+                await this.rollbackCreatedSession(agentId, err.partial, 'hard-failure rollback', {
+                    expectCreationToken: creationToken,
+                });
             }
             const message = err instanceof Error ? err.message : String(err);
             await this.markBootstrapFailed(agentId, creationToken, message);
@@ -1105,27 +1228,39 @@ export class AgentManager {
             signal.addEventListener('abort', onAbort, { once: true });
         });
     }
+    // Claim snapshot and adoption declaration share one critical section with rollbacks.
     async adoptOrRestartSession(tmux, runner, agent, agentId, workdir, sessionDir) {
-        let claim;
+        return this.runUnderSessionLifecycle(agentId, () => this.adoptOrRestartSessionLocked(tmux, runner, agent, agentId, workdir, sessionDir));
+    }
+    async adoptOrRestartSessionLocked(tmux, runner, agent, agentId, workdir, sessionDir) {
+        let snapshot;
         try {
-            claim = await tmux.getOption(agentId, '@baxian-agent-id');
+            snapshot = await tmux.getSessionSnapshot(agentId);
         }
         catch (err) {
-            throw new EnsureSessionError({ createdSession: false, agentId }, `getOption(@baxian-agent-id) failed: ${err instanceof Error ? err.message : String(err)}`);
+            throw new EnsureSessionError({ createdSession: false, agentId }, `session snapshot failed: ${err instanceof Error ? err.message : String(err)}`);
         }
-        if (claim !== agentId) {
+        if (!snapshot) {
+            return this.buildFreshSession(tmux, agent, agentId, workdir, sessionDir);
+        }
+        const sessionRef = snapshot.ref;
+        if (snapshot.claim !== agentId) {
+            if (snapshot.claim === null && await this.reclaimHalfCreatedSession(tmux, agentId, snapshot)) {
+                return this.buildFreshSession(tmux, agent, agentId, workdir, sessionDir);
+            }
             throw new EnsureSessionError({ createdSession: false, agentId }, `tmux session "${agentId}" exists but @baxian-agent-id session claim mismatch ` +
-                `(got "${claim ?? 'null'}"); baxian will not adopt foreign session — operator must intervene`);
+                `(got "${snapshot.claim ?? 'null'}"); baxian will not adopt foreign session — operator must intervene`);
         }
+        this.adoptGeneration.set(agentId, (this.adoptGeneration.get(agentId) ?? 0) + 1);
         try {
-            await this.pinRuntimeSessionOptions(tmux, agentId);
+            await this.setSessionOptions(tmux, agentId, sessionRef, this.runtimePinEntries());
         }
         catch (err) {
-            throw new EnsureSessionError({ createdSession: false, agentId }, `pinRuntimeSessionOptions failed: ${err instanceof Error ? err.message : String(err)}`);
+            throw new EnsureSessionError({ createdSession: false, agentId }, `pinning runtime session options failed: ${err instanceof Error ? err.message : String(err)}`);
         }
         let paneId;
         try {
-            paneId = await tmux.getSinglePaneId(agentId);
+            paneId = await tmux.getSinglePaneIdByRef(sessionRef);
         }
         catch (err) {
             throw new EnsureSessionError({ createdSession: false, agentId }, `getSinglePaneId failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1164,10 +1299,10 @@ export class AgentManager {
             else if (state.kind !== 'shell') {
                 throw new EnsureSessionError({ createdSession: false, agentId }, `tmux pane path ${currentPath} differs from Workdir ${sessionDir}, but runtime is not safely idle`);
             }
-            await tmux.killSession(agentId);
+            await this.killAdoptTarget(tmux, agentId, sessionRef, 'workdir change');
             return this.buildFreshSession(tmux, agent, agentId, workdir, sessionDir);
         }
-        await tmux.setOption(agentId, WORKDIR_SESSION_OPTION, sessionDir);
+        await this.setSessionOptions(tmux, agentId, sessionRef, [[WORKDIR_SESSION_OPTION, sessionDir]]);
         switch (state.kind) {
             case 'live-runtime': {
                 let stale;
@@ -1185,9 +1320,10 @@ export class AgentManager {
                         skillsStale: true,
                         paneId,
                         workdir,
+                        sessionRef,
                     };
                 }
-                return { ok: true, createdSession: false, freshRuntime: false, paneId, workdir };
+                return { ok: true, createdSession: false, freshRuntime: false, paneId, workdir, sessionRef };
             }
             case 'startup-dialog':
                 throw new EnsureSessionError({
@@ -1209,8 +1345,8 @@ export class AgentManager {
                         timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
                         scrollback: 0,
                     });
-                    await this.tagSessionSkillsVersion(tmux, agentId);
-                    return { ok: true, createdSession: false, freshRuntime: true, paneId, workdir };
+                    await this.tagSessionSkillsVersion(tmux, agentId, sessionRef);
+                    return { ok: true, createdSession: false, freshRuntime: true, paneId, workdir, sessionRef };
                 }
                 catch (trustErr) {
                     if (trustErr instanceof ReplNotReadyError && detectStartupDialog(trustErr.lastScreen, runtime)) {
@@ -1228,7 +1364,7 @@ export class AgentManager {
                 break;
         }
         try {
-            await tmux.sendKeysToPane(paneId, `${buildLaunchCommand(agent)}\n`);
+            await tmux.sendKeysToPane(paneId, `${launchCommandIn(sessionDir, agent)}\n`);
             await tmux.handleTrustDialog(paneId, runtime, {
                 timeoutMs: this.bootstrapTimeoutsMs.trustDialog,
             });
@@ -1236,8 +1372,8 @@ export class AgentManager {
                 timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
                 scrollback: 0,
             });
-            await this.tagSessionSkillsVersion(tmux, agentId);
-            return { ok: true, createdSession: false, freshRuntime: true, paneId, workdir };
+            await this.tagSessionSkillsVersion(tmux, agentId, sessionRef);
+            return { ok: true, createdSession: false, freshRuntime: true, paneId, workdir, sessionRef };
         }
         catch (relErr) {
             if (relErr instanceof ReplNotReadyError && detectStartupDialog(relErr.lastScreen, runtime)) {
@@ -1251,6 +1387,66 @@ export class AgentManager {
             throw new EnsureSessionError({ createdSession: false, agentId }, `REPL relaunch failed: ${relErr instanceof Error ? relErr.message : String(relErr)}`);
         }
     }
+    // Frees a bootstrap blocked on its predecessor's half-created session (nonce
+    // env present but claim never written); anything else is left alone.
+    async reclaimHalfCreatedSession(tmux, agentId, knownSnapshot) {
+        let snapshot;
+        try {
+            snapshot = knownSnapshot ?? await tmux.getSessionSnapshot(agentId);
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `session snapshot failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!snapshot)
+            return true;
+        if (snapshot.claim !== null)
+            return false;
+        let halfCreated;
+        try {
+            halfCreated = await tmux.hasCreationNonce(agentId);
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `creation-nonce probe failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!halfCreated)
+            return false;
+        let outcome;
+        try {
+            // claim-still-empty rides the kill itself — a claim racing the probes makes the server refuse.
+            outcome = await tmux.killSessionRef(snapshot.ref, { onlyIfUnclaimed: true });
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `killSessionRef (half-created leftover) failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (outcome === 'refused' || outcome === 'stale-server') {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `session ${snapshot.ref.sessionId} was claimed (or its server changed) while reclaiming the half-created leftover — retry to observe the new state`);
+        }
+        if (outcome === 'killed') {
+            console.warn(`[AgentManager] ${agentId}: killed half-created leftover session ${snapshot.ref.sessionId} (creation nonce present, claim never written)`);
+        }
+        else {
+            console.warn(`[AgentManager] ${agentId}: half-created leftover session ${snapshot.ref.sessionId} already gone`);
+        }
+        return true;
+    }
+    async killAdoptTarget(tmux, agentId, sessionRef, reason) {
+        let outcome;
+        try {
+            outcome = await tmux.killSessionRef(sessionRef);
+        }
+        catch (err) {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `killSessionRef (${reason}) failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (outcome === 'stale-server') {
+            throw new EnsureSessionError({ createdSession: false, agentId }, `tmux server generation changed while replacing session (${reason}); retry to observe the new state`);
+        }
+        if (outcome === 'killed') {
+            console.warn(`[AgentManager] ${agentId}: killed session ${sessionRef.sessionId} (${reason})`);
+        }
+        else {
+            console.warn(`[AgentManager] ${agentId}: session ${sessionRef.sessionId} already gone (${reason})`);
+        }
+    }
     async acquireAgentForTask(agentId, taskId, phase) {
         const cfg = this.getAgentConfig(agentId);
         if (!cfg)
@@ -1282,6 +1478,7 @@ export class AgentManager {
             projectId: cfg.projectId,
             taskId,
             lockToken: token,
+            ...(phase === 'code' && !sameTaskReentry ? { bootstrappingTaskId: taskId } : {}),
             updatedAt: now,
         }));
         return true;
@@ -1345,10 +1542,19 @@ export class AgentManager {
                 });
                 return true;
             }
+            let sessionConfirmedAbsent = false;
             if (state.workdir) {
+                const releaseWorkdir = state.workdir;
                 const runner = this.createRunnerFor(cfg);
                 const tmux = new TmuxManager(runner);
                 const hold = async (reason) => {
+                    const latest = await this.agentStore.get(agentId);
+                    if (!latest
+                        || latest.taskId !== expectedTaskId
+                        || latest.lockToken !== lockToken
+                        || !await this.lockManager.isOwner(agentId, expectedTaskId, lockToken)) {
+                        return false;
+                    }
                     const pendingAt = new Date().toISOString();
                     if (boundTask && cfg.role === 'dev') {
                         boundTask.branchCleanupPending = { agentId, reason, updatedAt: pendingAt };
@@ -1375,32 +1581,40 @@ export class AgentManager {
                     return false;
                 };
                 try {
-                    await this.assertTaskLockOwner(agentId, expectedTaskId, lockToken);
-                    const paneId = await this.resolvePaneId(state, cfg);
-                    if (paneId) {
-                        await this.waitForReplPromptReady(tmux, paneId, agentRuntimeKindFor(cfg), this.cleanComposerWaitMs);
+                    await this.assertTaskGeneration(agentId, expectedTaskId, lockToken, releaseWorkdir);
+                    const runtime = await this.inspectReleaseRuntime(tmux, agentId);
+                    if (runtime.kind === 'hold')
+                        return hold(runtime.reason);
+                    await this.assertTaskGeneration(agentId, expectedTaskId, lockToken, releaseWorkdir);
+                    if (runtime.kind === 'pane') {
+                        if (state.paneId !== runtime.paneId) {
+                            await this.agentStore.update(agentId, (latest) => {
+                                if (!latest
+                                    || latest.taskId !== expectedTaskId
+                                    || latest.lockToken !== lockToken
+                                    || latest.workdir !== releaseWorkdir) {
+                                    return AGENT_STORE_NOOP;
+                                }
+                                return { ...latest, paneId: runtime.paneId, updatedAt: new Date().toISOString() };
+                            });
+                            const refreshed = await this.assertTaskGeneration(agentId, expectedTaskId, lockToken, releaseWorkdir);
+                            if (refreshed.paneId !== runtime.paneId) {
+                                throw new Error(`Agent ${agentId} runtime pane changed during release; operation aborted`);
+                            }
+                        }
+                        await this.waitForReplPromptReady(tmux, runtime.paneId, agentRuntimeKindFor(cfg), this.cleanComposerWaitMs);
                     }
                     else {
-                        let sessionAlive;
-                        try {
-                            sessionAlive = await tmux.hasSession(agentId);
-                        }
-                        catch (err) {
-                            return hold(`Runtime availability probe failed; refusing checkout cleanup: ` +
-                                `${err instanceof Error ? err.message : String(err)}`);
-                        }
-                        if (sessionAlive) {
-                            return hold('Runtime session still exists but its pane is unavailable; refusing checkout cleanup');
-                        }
+                        sessionConfirmedAbsent = true;
                     }
-                    await this.assertTaskLockOwner(agentId, expectedTaskId, lockToken);
+                    await this.assertTaskGeneration(agentId, expectedTaskId, lockToken, releaseWorkdir);
                     if (cfg.role === 'dev' && boundTask) {
                         const branches = new BranchManager(runner);
-                        const cleanup = await branches.cleanupTaskBranch(state.workdir, {
+                        const cleanup = await branches.cleanupTaskBranch(releaseWorkdir, {
                             taskId: boundTask.id,
                             taskBranch: boundTask.branch,
                             branchCreatedByBaxian: boundTask.branchCreatedByBaxian,
-                        }, () => this.assertTaskLockOwner(agentId, expectedTaskId, lockToken));
+                        }, () => this.assertTaskGeneration(agentId, expectedTaskId, lockToken, releaseWorkdir).then(() => undefined));
                         let cleanupStateChanged = false;
                         if (cleanup.status === 'pending') {
                             if (boundTask.branchCleanupPending?.agentId !== agentId
@@ -1443,11 +1657,12 @@ export class AgentManager {
                             await this.taskStore.set(boundTask);
                         }
                         if (cleanup.status !== 'deleted')
-                            await branches.parkOnDefaultDetached(state.workdir);
+                            await branches.parkOnDefaultDetached(releaseWorkdir);
                     }
                     else {
-                        await new BranchManager(runner).parkOnDefaultDetached(state.workdir);
+                        await new BranchManager(runner).parkOnDefaultDetached(releaseWorkdir);
                     }
+                    await this.assertTaskGeneration(agentId, expectedTaskId, lockToken, releaseWorkdir);
                 }
                 catch (err) {
                     const reason = err instanceof DirtyWorkdirError
@@ -1456,17 +1671,25 @@ export class AgentManager {
                     return hold(reason);
                 }
             }
-            await this.assertTaskLockOwner(agentId, expectedTaskId, lockToken);
+            if (state.workdir) {
+                await this.assertTaskGeneration(agentId, expectedTaskId, lockToken, state.workdir);
+            }
+            else {
+                await this.assertTaskLockOwner(agentId, expectedTaskId, lockToken);
+            }
             await this.agentStore.update(agentId, (existing) => {
                 if (!existing)
                     return AGENT_STORE_NOOP;
-                if (existing.taskId !== expectedTaskId)
+                if (existing.taskId !== expectedTaskId
+                    || existing.lockToken !== lockToken
+                    || (state.workdir !== undefined && existing.workdir !== state.workdir)) {
                     return AGENT_STORE_NOOP;
+                }
                 return {
                     id: existing.id,
                     projectId: existing.projectId,
                     ...(existing.workdir !== undefined ? { workdir: existing.workdir } : {}),
-                    ...(existing.paneId !== undefined ? { paneId: existing.paneId } : {}),
+                    ...(!sessionConfirmedAbsent && existing.paneId !== undefined ? { paneId: existing.paneId } : {}),
                     ...(existing.creationToken !== undefined ? { creationToken: existing.creationToken } : {}),
                     updatedAt: now,
                 };
@@ -1474,6 +1697,17 @@ export class AgentManager {
             return this.lockManager.releaseIfOwner(agentId, expectedTaskId, lockToken);
         });
     }
+    async releaseAgentIfBound(agentId, expectedTaskId, opts) {
+        const state = await this.agentStore.get(agentId);
+        if (state?.taskId !== expectedTaskId)
+            return true;
+        const released = opts
+            ? await this.releaseAgentForTask(agentId, expectedTaskId, 'idle', opts)
+            : await this.releaseAgentForTask(agentId, expectedTaskId, 'idle');
+        if (released)
+            return true;
+        return (await this.agentStore.get(agentId))?.taskId !== expectedTaskId;
+    }
     async reconcileTaskBranches() {
         const tasks = await this.taskStore.list();
         const terminalByBranch = new Map(tasks
@@ -1882,14 +2116,27 @@ export class AgentManager {
         }
         if (result.redispatchCodeTaskId) {
             try {
-                const resumed = await this.continueSession(result.redispatchCodeTaskId, agentId, 'code');
+                const task = await this.taskStore.get(result.redispatchCodeTaskId);
+                const round = task?.specReviewRound;
+                const stored = round === undefined
+                    ? null
+                    : await this.reviewStore?.getRound(result.redispatchCodeTaskId, 'spec', round);
+                if (!task || task.phase !== 'code' || !task.signalToken || !stored || stored.phase !== 'spec') {
+                    await this.markAwaitingHuman(agentId, 'code-dispatch-failed', 'Code-phase redispatch cannot continue because the persisted Spec handoff is missing or invalid. Restore the review record or cancel the task.', { expectedTaskId: result.redispatchCodeTaskId }).catch(() => undefined);
+                    return { resumed: false, releasedBinding: false, reason: 'Persisted Spec handoff is missing or invalid.' };
+                }
+                const resumed = await this.dispatchCodePhasePrompt(task, agentId, task.signalToken, stored.documents, round);
                 if (!resumed) {
-                    await this.markAwaitingHuman(agentId, 'code-dispatch-failed', 'Code-phase redispatch on Resume was not delivered; Resume again to retry or cancel the task.', { expectedTaskId: result.redispatchCodeTaskId }).catch(() => undefined);
+                    const reason = 'Code-phase redispatch on Resume was not delivered; Resume again to retry or cancel the task.';
+                    await this.markAwaitingHuman(agentId, 'code-dispatch-failed', reason, { expectedTaskId: result.redispatchCodeTaskId }).catch(() => undefined);
+                    return { resumed: false, releasedBinding: false, reason };
                 }
             }
             catch (err) {
                 console.error(`[AgentManager] resumeAgent code redispatch failed for ${agentId}:`, err);
-                await this.markAwaitingHuman(agentId, 'code-dispatch-failed', 'Code-phase redispatch on Resume failed; Resume again to retry or cancel the task.', { expectedTaskId: result.redispatchCodeTaskId }).catch(() => undefined);
+                const reason = `Code-phase redispatch on Resume failed: ${err instanceof Error ? err.message : String(err)}`;
+                await this.markAwaitingHuman(agentId, 'code-dispatch-failed', reason, { expectedTaskId: result.redispatchCodeTaskId }).catch(() => undefined);
+                return { resumed: false, releasedBinding: false, reason };
             }
         }
         return {
@@ -1909,6 +2156,48 @@ export class AgentManager {
             return null;
         }
     }
+    async inspectReleaseRuntime(tmux, agentId) {
+        let sessionAlive;
+        try {
+            sessionAlive = await tmux.hasSession(agentId);
+        }
+        catch (err) {
+            return {
+                kind: 'hold',
+                reason: `Runtime availability probe failed; refusing checkout cleanup: ` +
+                    `${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (!sessionAlive)
+            return { kind: 'absent' };
+        let claim;
+        try {
+            claim = await tmux.getOption(agentId, '@baxian-agent-id');
+        }
+        catch (err) {
+            return {
+                kind: 'hold',
+                reason: `Runtime session claim probe failed; refusing checkout cleanup: ` +
+                    `${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (claim !== agentId) {
+            return {
+                kind: 'hold',
+                reason: `Runtime session claim mismatch (got "${claim ?? 'null'}"); refusing checkout cleanup`,
+            };
+        }
+        try {
+            return { kind: 'pane', paneId: await tmux.getSinglePaneId(agentId) };
+        }
+        catch (err) {
+            return {
+                kind: 'hold',
+                reason: `Runtime pane probe failed; refusing checkout cleanup: ` +
+                    `${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
     async interruptPaneAndWaitReady(state, cfg) {
         const paneId = await this.resolvePaneId(state, cfg);
         if (!paneId)
@@ -2153,15 +2442,14 @@ export class AgentManager {
             throw new Error(`Unknown agent: ${agentId}`);
         const runner = this.createRunnerFor(cfg);
         const tmux = new TmuxManager(runner);
-        const alive = await tmux.hasSession(agentId);
-        if (!alive) {
+        const snapshot = await tmux.getSessionSnapshot(agentId);
+        if (!snapshot) {
             throw new Error(`restart-repl: tmux session ${agentId} does not exist; use retry to rebuild`);
         }
-        const claim = await tmux.getOption(agentId, '@baxian-agent-id');
-        if (claim !== agentId) {
-            throw new Error(`restart-repl: session claim mismatch (got "${claim ?? 'null'}"); refusing to touch foreign session`);
+        if (snapshot.claim !== agentId) {
+            throw new Error(`restart-repl: session claim mismatch (got "${snapshot.claim ?? 'null'}"); refusing to touch foreign session`);
         }
-        const paneId = await tmux.getSinglePaneId(agentId);
+        const paneId = await tmux.getSinglePaneIdByRef(snapshot.ref);
         await tmux.sendKeysToPane(paneId, 'C-c');
         const cmd = await this.pollPaneCommandStable(tmux, paneId, { timeoutMs: 2_000 });
         const RUNTIME = /^(?:claude|codex|node|opencode|qodercli(?:-[\d.]+)?|\d+\.\d+\.\d+)$/;
@@ -2183,10 +2471,10 @@ export class AgentManager {
                 'use retry to rebuild the session safely');
         }
         await this.provisionRepoSkills(runner, cfg, workdir);
-        await tmux.setOption(agentId, WORKDIR_SESSION_OPTION, workdir);
+        await this.setSessionOptions(tmux, agentId, snapshot.ref, [[WORKDIR_SESSION_OPTION, workdir]]);
         const runtime = agentRuntimeKindFor(cfg);
         const relaunch = async () => {
-            await tmux.sendKeysToPane(paneId, `${buildLaunchCommand(cfg)}\n`);
+            await tmux.sendKeysToPane(paneId, `${launchCommandIn(workdir, cfg)}\n`);
             await tmux.handleTrustDialog(paneId, runtime, {
                 timeoutMs: this.bootstrapTimeoutsMs.trustDialog,
             });
@@ -2194,7 +2482,7 @@ export class AgentManager {
                 timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
                 scrollback: 0,
             });
-            await this.tagSessionSkillsVersion(tmux, agentId);
+            await this.tagSessionSkillsVersion(tmux, agentId, snapshot.ref);
         };
         await this.runUnderSkillDirLock(this.skillDirLockKey(cfg, workdir), relaunch);
         await this.agentStore.update(agentId, (state) => {
@@ -2207,6 +2495,42 @@ export class AgentManager {
             };
         });
     }
+    async redispatchResearchAfterReplRestart(agentId, taskId) {
+        const agent = this.getAgentConfig(agentId);
+        const task = await this.taskStore.get(taskId);
+        if (!agent || agent.role !== 'research' || !task)
+            return false;
+        if (task.researchAgentId !== agentId || task.agentId !== agentId || !task.signalToken)
+            return false;
+        let phase;
+        let expectedKind;
+        let findings;
+        if (task.phase === 'research' && task.status === 'in_progress') {
+            phase = 'research';
+            expectedKind = 'spec-done';
+        }
+        else if (task.phase === 'spec' && task.status === 'fixing') {
+            const round = task.specReviewRound ?? 1;
+            const stored = await this.reviewStore?.getRound(taskId, 'spec', round);
+            if (!stored?.findings)
+                return false;
+            phase = 'server-feedback';
+            expectedKind = 'spec-fixed';
+            findings = JSON.stringify(stored.findings);
+        }
+        else {
+            return false;
+        }
+        await this.clearAwaitingHuman(agentId);
+        return this.continueSession(taskId, agentId, phase, {
+            bypassTaskStatusGate: true,
+            signalToken: task.signalToken,
+            preserveDispatchOutputs: true,
+            ...(findings ? { serverPriorFindings: findings } : {}),
+            ...(task.specReviewRound !== undefined ? { currentSpecRound: task.specReviewRound } : {}),
+            armBeforeInject: () => this.setupPhaseSignalWatcher(taskId, agentId, expectedKind, task.signalToken),
+        });
+    }
     prepareRemoveTargets(agentId) {
         const cfg = this.getAgentConfig(agentId);
         if (!cfg)
@@ -2214,15 +2538,10 @@ export class AgentManager {
         const project = this.getProjectConfig(cfg.projectId);
         if (!project)
             throw new Error(`Unknown project: ${cfg.projectId}`);
-        if (cfg.role === 'qa')
+        if (cfg.role !== 'dev')
             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] };
+        const group = this.findAgentGroup(agentId);
+        return { targets: group?.map(agent => agent.id) ?? [agentId] };
     }
     async cleanupRemovedAgentRuntime(targets) {
         const failures = [];
@@ -2257,17 +2576,23 @@ export class AgentManager {
                 }
             }
             try {
-                const alive = await tmux.hasSession(id);
-                if (alive) {
-                    const claim = await tmux.getOption(id, '@baxian-agent-id');
-                    if (claim === id) {
-                        await tmux.killSession(id);
-                    }
-                    else {
+                await this.runUnderSessionLifecycle(id, async () => {
+                    const snapshot = await tmux.getSessionSnapshot(id);
+                    if (!snapshot)
+                        return;
+                    if (snapshot.claim !== id) {
                         console.warn(`[AgentManager] cleanupRemovedAgentRuntime: skipping kill for ${id} ` +
-                            `(claim=${claim ?? 'null'}; not baxian-managed)`);
+                            `(claim=${snapshot.claim ?? 'null'}; not baxian-managed)`);
+                        return;
                     }
-                }
+                    const outcome = await tmux.killSessionRef(snapshot.ref);
+                    if (outcome === 'stale-server') {
+                        console.warn(`[AgentManager] cleanupRemovedAgentRuntime: tmux server generation changed for ${id} — leaving session untouched`);
+                    }
+                    else if (outcome === 'killed') {
+                        console.warn(`[AgentManager] cleanupRemovedAgentRuntime: killed session ${snapshot.ref.sessionId} for removed agent ${id}`);
+                    }
+                });
             }
             catch (err) {
                 failures.push({ agentId: id, step: 'tmux', error: err });
@@ -2305,6 +2630,12 @@ export class AgentManager {
         }
         const workdirGuess = workdirForEstimate ?? '/'.padEnd(64, 'x');
         const now = new Date().toISOString();
+        const isResearch = cfg.role === 'research';
+        const group = this.findAgentGroup(cfg.id);
+        const devAgentId = isResearch ? group?.find(agent => agent.role === 'dev')?.id : cfg.id;
+        if (!devAgentId)
+            throw new Error(`Agent ${cfg.id} has no dev agent in its group`);
+        const qaAgentId = group?.find(agent => agent.role === 'qa')?.id;
         const fakeTask = {
             id: 'task-9999999999',
             projectId,
@@ -2312,6 +2643,9 @@ export class AgentManager {
             description: input.description,
             preferredAgentId: input.preferredAgentId,
             agentId: cfg.id,
+            devAgentId,
+            ...(qaAgentId ? { qaAgentId } : {}),
+            ...(isResearch ? { researchAgentId: cfg.id, phase: 'research' } : {}),
             branch: `${BRANCH_PREFIX}task-9999999999`,
             reviewRound: 0,
             status: 'in_progress',
@@ -2320,11 +2654,12 @@ export class AgentManager {
         };
         const fullPrompt = buildPromptInline({
             task: fakeTask,
-            phase: 'develop',
+            phase: isResearch ? 'research' : 'develop',
             agent: cfg,
             workdir: workdirGuess,
             skillRegistry: this.skillRegistry,
             signalToken: 'preview-signal-token',
+            hasQaPartner: qaAgentId !== undefined,
         });
         return Buffer.byteLength(fullPrompt, 'utf8');
     }
@@ -2337,12 +2672,11 @@ export class AgentManager {
     getProjectByRepo(repo) {
         return this.config.project.find(p => repoSlug(p.repo) === repo);
     }
-    findQaPartner(devAgentId) {
+    findAgentGroup(anchorAgentId) {
         for (const project of this.config.project) {
-            for (const pair of project.agent) {
-                if (pair[0]?.id === devAgentId) {
-                    return pair[1];
-                }
+            for (const group of project.agent) {
+                if (group.some(agent => agent.id === anchorAgentId))
+                    return group;
             }
         }
         return undefined;
@@ -2441,17 +2775,18 @@ export class AgentManager {
             if (!mapped)
                 continue;
             const { expectedKinds, agentId } = mapped;
-            const interventionKindLabel = task.phase === 'spec' && task.status === 'review' ? 'spec-reviewed'
-                : task.phase === 'spec' && task.status === 'fixing' ? 'spec-fixed'
-                    : task.phase !== 'spec' && task.status === 'review' ? 'pr-approved|pr-changes-requested'
-                        : task.phase !== 'spec' && task.status === 'fixing' ? 'pr-fixed'
+            const specStage = isSpecStagePhase(task.phase);
+            const interventionKindLabel = specStage && task.status === 'review' ? 'spec-reviewed'
+                : specStage && task.status === 'fixing' ? 'spec-fixed'
+                    : !specStage && task.status === 'review' ? 'pr-approved|pr-changes-requested'
+                        : !specStage && task.status === 'fixing' ? 'pr-fixed'
                             : undefined;
-            const isServerProtocol = task.reviewMode === 'server' || task.phase === 'spec';
+            const isServerProtocol = task.reviewMode === 'server' || specStage;
             const scanSnapshotOnRecover = isServerProtocol
                 || (task.phase === undefined && task.status === 'in_progress')
-                || (task.phase !== 'spec' && (task.status === 'review' || task.status === 'fixing'));
+                || (!specStage && (task.status === 'review' || task.status === 'fixing'));
             const allowRecoveredReadFile = task.status === 'review'
-                && (task.phase === 'spec'
+                && (specStage
                     || (task.reviewMode === 'server' && task.batchTotal !== undefined)
                     || (task.reviewMode === 'server' && task.reviewCheckoutMode === 'base'));
             try {
@@ -2730,8 +3065,8 @@ export class AgentManager {
         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`);
+        if (!TASK_OWNER_ROLES.has(cfg.role)) {
+            throw new ApiError(400, `Agent ${preferredAgentId} is not dev or research role`);
         }
         const state = await this.agentStore.get(preferredAgentId);
         if (!canDispatchWithBinding(state))
@@ -2739,6 +3074,22 @@ export class AgentManager {
         const { projectId: _projectId, ...rest } = cfg;
         return rest;
     }
+    async persistQueuedTask(task, queueReason, agentId) {
+        await this.taskStore.set(task);
+        await this.safeEmit({
+            id: '',
+            type: 'task.created',
+            timestamp: task.createdAt,
+            projectId: task.projectId,
+            taskId: task.id,
+            data: {
+                queued: true,
+                queueReason,
+                ...(agentId ? { agentId } : {}),
+            },
+        });
+        return task;
+    }
     async createTask(projectId, input) {
         return this.withTaskLock(async () => {
             const taskId = await this.taskStore.nextId();
@@ -2762,113 +3113,13 @@ export class AgentManager {
             const imageFilenames = input.images?.length
                 ? await this.persistTaskImages(taskId, input.images)
                 : undefined;
-            if (input.preferredAgentId === '') {
-                const unassigned = {
-                    id: taskId,
-                    projectId,
-                    title: input.title,
-                    description: input.description,
-                    preferredAgentId: '',
-                    agentId: '',
-                    reviewRound: 0,
-                    status: 'pending',
-                    branch: taskBranch,
-                    branchCreatedByBaxian,
-                    reviewMode: this.effectiveReviewMode(projectId),
-                    createdAt: now,
-                    updatedAt: now,
-                    ...(imageFilenames ? { images: imageFilenames } : {}),
-                };
-                await this.taskStore.set(unassigned);
-                await this.safeEmit({
-                    id: '',
-                    type: 'task.created',
-                    timestamp: now,
-                    projectId,
-                    taskId,
-                    data: { queued: true, queueReason: 'unassigned' },
-                });
-                return unassigned;
-            }
-            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: taskBranch,
-                    branchCreatedByBaxian,
-                    reviewMode: this.effectiveReviewMode(projectId),
-                    createdAt: now,
-                    updatedAt: now,
-                    ...(qa ? { qaAgentId: qa.id } : {}),
-                    ...(imageFilenames ? { images: imageFilenames } : {}),
-                };
-                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 lockToken = await this.lockManager.acquire(dev.id, taskId);
-            if (!lockToken) {
-                const queued = {
-                    id: taskId,
-                    projectId,
-                    title: input.title,
-                    description: input.description,
-                    preferredAgentId: input.preferredAgentId,
-                    agentId: '',
-                    reviewRound: 0,
-                    status: 'pending',
-                    branch: taskBranch,
-                    branchCreatedByBaxian,
-                    reviewMode: this.effectiveReviewMode(projectId),
-                    createdAt: now,
-                    updatedAt: now,
-                    ...(qa ? { qaAgentId: qa.id } : {}),
-                    ...(imageFilenames ? { images: imageFilenames } : {}),
-                };
-                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 = {
+            const taskBase = {
                 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: taskBranch,
                 branchCreatedByBaxian,
                 reviewMode: this.effectiveReviewMode(projectId),
@@ -2876,9 +3127,52 @@ export class AgentManager {
                 updatedAt: now,
                 ...(imageFilenames ? { images: imageFilenames } : {}),
             };
+            if (input.preferredAgentId === '') {
+                const unassigned = {
+                    ...taskBase,
+                    agentId: '',
+                    devAgentId: '',
+                    status: 'pending',
+                };
+                return this.persistQueuedTask(unassigned, 'unassigned');
+            }
+            const target = await this.pickAgent(projectId, input.preferredAgentId);
+            const targetConfig = this.getAgentConfig(input.preferredAgentId);
+            const group = this.findAgentGroup(input.preferredAgentId);
+            const dev = group?.find(agent => agent.role === 'dev');
+            if (!dev)
+                throw new ApiError(409, `Agent ${input.preferredAgentId} has no dev agent in its group`);
+            const qa = group?.find(agent => agent.role === 'qa');
+            const research = targetConfig.role === 'research' ? targetConfig : undefined;
+            const researchFields = research
+                ? { researchAgentId: research.id, phase: 'research' }
+                : {};
+            const queued = {
+                ...taskBase,
+                agentId: '',
+                devAgentId: dev.id,
+                ...researchFields,
+                status: 'pending',
+                ...(qa ? { qaAgentId: qa.id } : {}),
+            };
+            if (!target) {
+                return this.persistQueuedTask(queued, 'preferred_agent_busy', input.preferredAgentId);
+            }
+            const lockToken = await this.lockManager.acquire(target.id, taskId);
+            if (!lockToken) {
+                return this.persistQueuedTask(queued, 'agent_locked', input.preferredAgentId);
+            }
+            const task = {
+                ...taskBase,
+                agentId: target.id,
+                devAgentId: dev.id,
+                ...(qa ? { qaAgentId: qa.id } : {}),
+                ...researchFields,
+                status: 'in_progress',
+            };
             await this.taskStore.set(task);
-            await this.agentStore.update(dev.id, (existing) => ({
-                id: dev.id,
+            await this.agentStore.update(target.id, (existing) => ({
+                id: target.id,
                 projectId,
                 taskId,
                 lockToken,
@@ -2893,9 +3187,9 @@ export class AgentManager {
                 type: 'task.assigned',
                 timestamp: now,
                 projectId,
-                agentId: dev.id,
+                agentId: target.id,
                 taskId,
-                data: { agentId: dev.id },
+                data: { agentId: target.id },
             });
             return task;
         });
@@ -2921,10 +3215,15 @@ export class AgentManager {
         return task;
     }
     async startCreatedTaskSession(taskId, agentId, signalToken, dispatchLockToken) {
+        const initialTask = await this.taskStore.get(taskId);
+        if (!initialTask)
+            return null;
+        const initialDispatch = this.resolveInitialDispatch(initialTask);
+        const dispatchPhase = initialDispatch.phase;
         let started = false;
         let dispatchErr = null;
         try {
-            started = await this.startSession(taskId, agentId, 'develop');
+            started = await this.startSession(taskId, agentId, dispatchPhase);
         }
         catch (err) {
             dispatchErr = err;
@@ -2954,7 +3253,7 @@ export class AgentManager {
                 await this.releaseAgentForTask(agentId, taskId, 'idle', { allowAwaitingHuman: true });
                 return null;
             }
-            const initialKinds = this.devInitialSignalKinds(fresh.reviewMode);
+            const initialKinds = this.resolveInitialDispatch(fresh).kinds;
             try {
                 await this.armPostDispatchSignalOrHold(taskId, agentId, initialKinds, signalToken);
             }
@@ -2968,7 +3267,7 @@ export class AgentManager {
             return null;
         }
         if (dispatchErr instanceof DispatchTerminalError) {
-            await this.failTaskForDispatchError(taskId, 'develop', agentId, dispatchErr);
+            await this.failTaskForDispatchError(taskId, dispatchPhase, agentId, dispatchErr);
         }
         else if (dispatchErr instanceof EnsureSessionError && dispatchErr.partial.handled) {
         }
@@ -3187,8 +3486,8 @@ export class AgentManager {
             if (cfg.projectId !== fresh.projectId) {
                 return { task: fresh, errorCode: 400, error: `Agent ${agentId} not in project ${fresh.projectId}` };
             }
-            if (cfg.role !== 'dev') {
-                return { task: fresh, errorCode: 400, error: `Agent ${agentId} is not dev role` };
+            if (!TASK_OWNER_ROLES.has(cfg.role)) {
+                return { task: fresh, errorCode: 400, error: `Agent ${agentId} is not dev or research role` };
             }
             if (fresh.preferredAgentId !== '' && fresh.preferredAgentId !== agentId) {
                 return {
@@ -3206,14 +3505,29 @@ export class AgentManager {
                 return { task: fresh, errorCode: 409, error: `Agent ${agentId} lock acquisition failed` };
             }
             const now = new Date().toISOString();
-            const qaId = fresh.qaAgentId ?? this.findQaPartner(agentId)?.id;
+            const initiallyUnassigned = fresh.preferredAgentId === '';
+            const group = initiallyUnassigned ? this.findAgentGroup(agentId) : undefined;
+            const devId = initiallyUnassigned
+                ? group?.find(agent => agent.role === 'dev')?.id
+                : fresh.devAgentId;
+            if (!devId) {
+                await this.lockManager.releaseIfOwner(agentId, taskId, lockToken);
+                return { task: fresh, errorCode: 409, error: `Agent ${agentId} has no dev agent in its group` };
+            }
+            const qaId = initiallyUnassigned
+                ? group?.find(agent => agent.role === 'qa')?.id
+                : fresh.qaAgentId;
+            const researchId = initiallyUnassigned && cfg.role === 'research' ? cfg.id : fresh.researchAgentId;
             const claimedTask = {
                 ...fresh,
                 preferredAgentId: agentId,
                 agentId,
+                devAgentId: devId,
+                researchAgentId: researchId,
+                qaAgentId: qaId,
+                phase: researchId ? 'research' : undefined,
                 status: 'in_progress',
                 updatedAt: now,
-                ...(qaId ? { qaAgentId: qaId } : {}),
             };
             await this.taskStore.set(claimedTask);
             await this.agentStore.update(agentId, (existing) => ({
@@ -3247,20 +3561,21 @@ export class AgentManager {
         await this.updateTask(claimed.id, { signalToken });
         let started = false;
         let dispatchErr = null;
+        const initialDispatch = this.resolveInitialDispatch(claimed);
         try {
-            started = await this.startSession(claimed.id, claimed.agentId, 'develop');
+            started = await this.startSession(claimed.id, claimed.agentId, initialDispatch.phase);
         }
         catch (err) {
             dispatchErr = err;
             console.error(`[AgentManager] dispatchPendingTask startSession hard error for task=${claimed.id}:`, err);
         }
         if (started) {
-            await this.armPostDispatchSignalOrHold(claimed.id, claimed.agentId, this.devInitialSignalKinds(claimed.reviewMode), signalToken);
+            await this.armPostDispatchSignalOrHold(claimed.id, claimed.agentId, initialDispatch.kinds, signalToken);
             const refreshed = await this.taskStore.get(claimed.id);
             return { task: refreshed ?? claimed };
         }
         if (dispatchErr instanceof DispatchTerminalError) {
-            await this.failTaskForDispatchError(claimed.id, 'develop', claimed.agentId, dispatchErr);
+            await this.failTaskForDispatchError(claimed.id, initialDispatch.phase, claimed.agentId, dispatchErr);
         }
         else if (dispatchErr instanceof EnsureSessionError && dispatchErr.partial.handled) {
         }
@@ -3391,18 +3706,12 @@ export class AgentManager {
                 const stillOwner = stateNow?.taskId === taskId
                     && stateNow.lockToken === lockToken
                     && await this.lockManager.isOwner(agentId, taskId, lockToken);
-                try {
-                    if (stillOwner) {
-                        const runner = this.createRunnerFor(agent);
-                        await new TmuxManager(runner).killSession(agentId);
-                    }
-                    else {
-                        console.warn(`[AgentManager] startSession ensureSession rollback skipped killSession for stale owner ` +
-                            `${agentId}/${taskId}`);
-                    }
+                if (stillOwner) {
+                    await this.rollbackCreatedSession(agentId, err.partial, 'startSession ensure rollback');
                 }
-                catch (cleanupErr) {
-                    console.warn(`[AgentManager] startSession ensureSession rollback killSession failed:`, cleanupErr);
+                else {
+                    console.warn(`[AgentManager] startSession ensureSession rollback skipped for stale owner ` +
+                        `${agentId}/${taskId}`);
                 }
             }
             throw err;
@@ -3437,6 +3746,9 @@ export class AgentManager {
                     throw new Error(`Task ${taskId} has no review branch`);
                 await this.switchToVerifiedReviewHead(branchManager, workdir, task, assertOwner);
             }
+            else if (phase === 'research') {
+                await branchManager.switchToDefaultDetached(workdir);
+            }
             else {
                 if (!task.branch)
                     throw new Error(`Task ${taskId} has no task branch`);
@@ -3446,7 +3758,7 @@ export class AgentManager {
             if (!ensure.freshRuntime) {
                 await this.clearRuntimeForTaskBoundary(tmux, paneId, agentId, agent.runtime, assertOwner);
                 if (ensure.skillsStale)
-                    await this.tagSessionSkillsVersion(tmux, agentId);
+                    await this.tagSessionSkillsVersion(tmux, agentId, ensure.sessionRef);
             }
         }
         catch (err) {
@@ -3499,16 +3811,20 @@ export class AgentManager {
         });
         const promptSignalToken = opts.signalToken ?? task.signalToken;
         const promptSpecRound = opts.currentSpecRound ?? task.specReviewRound;
-        const hasQaPartner = !!(task.qaAgentId ?? this.findQaPartner(agentId)?.id);
+        const hasQaPartner = task.qaAgentId !== undefined;
         let prompt;
         try {
-            await this.getReviewTransport().clearDispatchOutputs(agent, dispatchWorkdir, phase);
+            await this.prepareDispatchArtifacts(agent, dispatchWorkdir, phase, {
+                specDocuments: opts.specDocuments,
+                preserveOutputs: false,
+                assertOwner,
+            });
             const imagePaths = await this.imagePathsForDispatch(runner, task, phase);
             let payloadOpts = {};
             if (opts.serverContent !== undefined || opts.serverDiffstat !== undefined || opts.serverInterdiff !== undefined || opts.serverPriorFindings || opts.serverPriorResponse) {
                 payloadOpts = await resolveServerPayloads(this.getReviewTransport(), agent, dispatchWorkdir, {
                     phase,
-                    ...(task.phase ? { taskPhase: task.phase } : {}),
+                    taskPhase: task.phase,
                     ...(promptSpecRound !== undefined ? { specRound: promptSpecRound } : {}),
                     reviewRound: task.reviewRound,
                     ...(opts.serverBatch ? { batch: opts.serverBatch } : {}),
@@ -3642,7 +3958,7 @@ export class AgentManager {
             const isAckUnknown = err instanceof DispatchTerminalError && err.reason === 'ack_unknown';
             if (!isAckUnknown) {
                 await cleanupCheckoutOrHold();
-                if (agentMarkedRunning) {
+                if (agentMarkedRunning && !opts.preserveBindingOnFailure) {
                     try {
                         let released = false;
                         let releaseToken;
@@ -3859,18 +4175,12 @@ export class AgentManager {
                 const stillOwner = stateNow?.taskId === taskId
                     && stateNow.lockToken === lockToken
                     && await this.lockManager.isOwner(agentId, taskId, lockToken);
-                try {
-                    if (stillOwner) {
-                        const runner = this.createRunnerFor(agent);
-                        await new TmuxManager(runner).killSession(agentId);
-                    }
-                    else {
-                        console.warn(`[AgentManager] continueSession ensureSession rollback skipped killSession for stale owner ` +
-                            `${agentId}/${taskId}`);
-                    }
+                if (stillOwner) {
+                    await this.rollbackCreatedSession(agentId, err.partial, 'continueSession ensure rollback');
                 }
-                catch (cleanupErr) {
-                    console.warn(`[AgentManager] continueSession ensureSession rollback killSession failed:`, cleanupErr);
+                else {
+                    console.warn(`[AgentManager] continueSession ensureSession rollback skipped for stale owner ` +
+                        `${agentId}/${taskId}`);
                 }
             }
             throw err;
@@ -3884,6 +4194,16 @@ export class AgentManager {
             return false;
         }
         await this.assertTaskLockOwner(agentId, taskId, lockToken);
+        const verifiedWorkdir = stateAfterEnsure.workdir;
+        if (!verifiedWorkdir
+            || verifiedWorkdir !== ensure.workdir
+            || verifiedWorkdir !== taskWorkdir) {
+            const reason = `Workdir changed during continueSession: ` +
+                `before=${taskWorkdir}, ensure=${ensure.workdir}, state=${verifiedWorkdir ?? 'missing'}`;
+            console.warn(`[AgentManager] continueSession[${phase}]: ${reason}; holding`);
+            await this.markAwaitingHuman(agentId, 'workdir-changed-during-dispatch', `${reason}. The prompt was not delivered; verify the agent runtime and Workdir before resuming.`, { expectedTaskId: taskId });
+            return false;
+        }
         const expectedStatuses = PHASE_EXPECTED_STATUS[phase] ?? [];
         const taskAfterEnsure = await this.taskStore.get(taskId);
         if (!taskAfterEnsure || TERMINAL_STATUSES.includes(taskAfterEnsure.status)) {
@@ -3895,28 +4215,39 @@ export class AgentManager {
                 `expected ${expectedStatuses.join('/')} for phase=${phase} after ensure; skipping`);
             return false;
         }
-        if (agentState.workdir && agent.role === 'dev' && task.branch) {
+        if (agent.role === 'dev' && task.branch) {
             const branches = new BranchManager(runner);
-            await branches.assertClean(taskWorkdir);
-            const actualRef = await branches.currentRef(taskWorkdir);
+            await branches.assertClean(verifiedWorkdir);
+            const actualRef = await branches.currentRef(verifiedWorkdir);
             if (actualRef !== `refs/heads/${task.branch}`) {
                 throw new Error(`Agent ${agentId} checkout mismatch for task ${taskId}: ` +
                     `expected refs/heads/${task.branch}, got ${actualRef ?? 'detached HEAD'}`);
             }
         }
+        else if (agent.role === 'research') {
+            await this.assertTaskGeneration(agentId, taskId, lockToken, verifiedWorkdir);
+            await new BranchManager(runner).switchToDefaultDetached(verifiedWorkdir);
+            await this.assertTaskGeneration(agentId, taskId, lockToken, verifiedWorkdir);
+        }
         const promptSpecRound = opts.currentSpecRound ?? task.specReviewRound;
         let prompt;
         try {
-            await this.getReviewTransport().clearDispatchOutputs(agent, taskWorkdir, phase);
+            await this.prepareDispatchArtifacts(agent, verifiedWorkdir, phase, {
+                specDocuments: opts.specDocuments,
+                preserveOutputs: opts.preserveDispatchOutputs ?? false,
+                assertOwner: async () => {
+                    await this.assertTaskGeneration(agentId, taskId, lockToken, verifiedWorkdir);
+                },
+            });
             const useIncrementalNudge = typeof opts.postApproveRedispatchCount === 'number'
                 && opts.postApproveRedispatchCount > 0
                 && !ensure.freshRuntime;
             const imagePaths = await this.imagePathsForDispatch(runner, task, phase);
             let payloadOpts = {};
             if (opts.serverContent !== undefined || opts.serverDiffstat !== undefined || opts.serverInterdiff !== undefined || opts.serverPriorFindings || opts.serverPriorResponse) {
-                payloadOpts = await resolveServerPayloads(this.getReviewTransport(), agent, taskWorkdir, {
+                payloadOpts = await resolveServerPayloads(this.getReviewTransport(), agent, verifiedWorkdir, {
                     phase,
-                    ...(task.phase ? { taskPhase: task.phase } : {}),
+                    taskPhase: task.phase,
                     ...(promptSpecRound !== undefined ? { specRound: promptSpecRound } : {}),
                     reviewRound: task.reviewRound,
                     ...(opts.serverBatch ? { batch: opts.serverBatch } : {}),
@@ -3931,7 +4262,7 @@ export class AgentManager {
                 task,
                 phase,
                 agent,
-                workdir: taskWorkdir,
+                workdir: verifiedWorkdir,
                 skillRegistry: this.skillRegistry,
                 ...(signalToken ? { signalToken } : {}),
                 ...(useIncrementalNudge
@@ -3980,6 +4311,13 @@ export class AgentManager {
             console.warn(`[AgentManager] continueSession[${phase}]: ownership token changed; skipping`);
             return false;
         }
+        if (agentFresh.workdir !== verifiedWorkdir) {
+            const reason = `Workdir changed before prompt injection: ` +
+                `verified=${verifiedWorkdir}, current=${agentFresh.workdir ?? 'missing'}`;
+            console.warn(`[AgentManager] continueSession[${phase}]: ${reason}; holding`);
+            await this.markAwaitingHuman(agentId, 'workdir-changed-during-dispatch', `${reason}. The prompt was not delivered; verify the agent runtime and Workdir before resuming.`, { expectedTaskId: taskId });
+            return false;
+        }
         await this.assertTaskLockOwner(agentId, taskId, lockToken);
         if (phase === 'post-approve') {
             const completionFresh = await this.getPostApproveCompletion(taskId);
@@ -3993,18 +4331,35 @@ export class AgentManager {
         }
         const now = new Date().toISOString();
         await this.agentStore.update(agentId, (latest) => {
-            if (!latest)
+            if (!latest
+                || latest.taskId !== taskId
+                || latest.lockToken !== lockToken
+                || latest.workdir !== verifiedWorkdir) {
                 return AGENT_STORE_NOOP;
+            }
             // The continuation prompt supersedes any question asked under the previous one.
             const { needInputAt: _needInputAt, ...rest } = latest;
             return {
                 ...rest,
                 paneId,
-                workdir: taskWorkdir,
+                workdir: verifiedWorkdir,
                 lockToken,
                 updatedAt: now,
             };
         });
+        const stateBeforeInject = await this.agentStore.get(agentId);
+        if (stateBeforeInject?.taskId !== taskId || stateBeforeInject.lockToken !== lockToken) {
+            console.warn(`[AgentManager] continueSession[${phase}]: ownership changed before prompt injection; skipping`);
+            return false;
+        }
+        if (stateBeforeInject.workdir !== verifiedWorkdir) {
+            const reason = `Workdir changed before prompt injection: ` +
+                `verified=${verifiedWorkdir}, current=${stateBeforeInject.workdir ?? 'missing'}`;
+            console.warn(`[AgentManager] continueSession[${phase}]: ${reason}; holding`);
+            await this.markAwaitingHuman(agentId, 'workdir-changed-during-dispatch', `${reason}. The prompt was not delivered; verify the agent runtime and Workdir before resuming.`, { expectedTaskId: taskId });
+            return false;
+        }
+        await this.assertTaskLockOwner(agentId, taskId, lockToken);
         await this.injectAndAwaitAck(tmux, paneId, prompt, agentId, agent.runtime);
         return true;
     }
@@ -4015,13 +4370,47 @@ export class AgentManager {
             return false;
         }
         const boundTask = await this.taskStore.get(state.taskId);
-        if (!boundTask || boundTask.phase || boundTask.status !== 'in_progress' || boundTask.agentId !== state.id) {
+        if (!boundTask)
+            return false;
+        if (boundTask.status === 'spec-ready' && isSpecStagePhase(boundTask.phase)) {
+            if (state.id === boundTask.devAgentId && state.id !== boundTask.agentId) {
+                const lockToken = state.lockToken;
+                await this.agentStore.update(state.id, (latest) => {
+                    if (!latest
+                        || latest.taskId !== state.taskId
+                        || latest.bootstrappingTaskId !== state.taskId
+                        || latest.lockToken !== lockToken) {
+                        return AGENT_STORE_NOOP;
+                    }
+                    return {
+                        id: latest.id,
+                        projectId: latest.projectId,
+                        ...(latest.paneId !== undefined ? { paneId: latest.paneId } : {}),
+                        ...(latest.workdir !== undefined ? { workdir: latest.workdir } : {}),
+                        ...(latest.creationToken !== undefined ? { creationToken: latest.creationToken } : {}),
+                        updatedAt: new Date().toISOString(),
+                    };
+                });
+                if (lockToken)
+                    await this.lockManager.releaseIfOwner(state.id, state.taskId, lockToken);
+                return true;
+            }
+            await this.clearBootstrapMarker(state.id, state.taskId);
             return false;
         }
-        if (await this.bootstrapPromptWasDelivered(state.taskId, boundTask.createdAt)) {
+        if (boundTask.status !== 'in_progress' || boundTask.agentId !== state.id)
+            return false;
+        const dispatchPhase = boundTask.phase === 'research'
+            ? 'research'
+            : boundTask.specReviewRound !== undefined ? 'code' : 'develop';
+        if (await this.bootstrapPromptWasDelivered(state.taskId, boundTask.createdAt, state.id, dispatchPhase)) {
             await this.clearBootstrapMarker(state.id, state.taskId);
             return false;
         }
+        if (dispatchPhase === 'code') {
+            await this.markAwaitingHuman(state.id, 'code-dispatch-failed', 'Code-phase handoff was interrupted before the prompt was delivered. Resume to replay the persisted Spec documents.', { expectedTaskId: state.taskId });
+            return true;
+        }
         console.warn(`[recover] agent ${state.id} was mid-bootstrap for in_progress task ${state.taskId} ` +
             `(prompt never ack'd); rolling the task back to pending`);
         await this.rollbackFailedDispatch(state.taskId, state.id, undefined, state.lockToken);
@@ -4033,12 +4422,15 @@ export class AgentManager {
         });
         return true;
     }
-    async bootstrapPromptWasDelivered(taskId, createdAtIso) {
+    async bootstrapPromptWasDelivered(taskId, createdAtIso, agentId, phase) {
         const today = new Date().toISOString().slice(0, 10);
         const from = createdAtIso.slice(0, 10);
         try {
             const events = await this.eventBus.readRange(from, today);
-            return events.some((e) => e.type === 'session.started' && e.taskId === taskId);
+            return events.some((event) => event.type === 'session.started'
+                && event.taskId === taskId
+                && event.agentId === agentId
+                && event.data.phase === phase);
         }
         catch (err) {
             console.warn(`[recover] bootstrapPromptWasDelivered read failed for task=${taskId}:`, err);
@@ -4222,13 +4614,7 @@ export class AgentManager {
                     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);
-                    }
+                    await this.rollbackCreatedSession(state.id, err.partial, 'recover ensure rollback');
                 }
                 const message = err instanceof Error ? err.message : String(err);
                 console.warn(`[recover] ensureSession failed for agent=${state.id}: ${message}`);
@@ -4493,8 +4879,8 @@ export class AgentManager {
             if (cfg.projectId !== projectId) {
                 throw new ApiError(400, `Agent ${input.preferredAgentId} not in project ${projectId}`);
             }
-            if (cfg.role !== 'dev') {
-                throw new ApiError(400, `Agent ${input.preferredAgentId} is not dev role`);
+            if (!TASK_OWNER_ROLES.has(cfg.role)) {
+                throw new ApiError(400, `Agent ${input.preferredAgentId} is not dev or research role`);
             }
         }
         let previewBytes;
@@ -4529,24 +4915,23 @@ export class AgentManager {
             if (opts.expectSignalToken !== undefined && task.signalToken !== opts.expectSignalToken) {
                 throw new ApiError(409, `Task ${taskId} review pass changed during redispatch (signalToken rotated); aborting`);
             }
-            if (task.reviewMode === 'server' || task.phase === 'spec') {
+            if (task.reviewMode === 'server' || isSpecStagePhase(task.phase)) {
                 if (!MANUAL_SERVER_REVIEW_STATUSES.includes(task.status)) {
                     throw new ApiError(409, `Task ${taskId} status is ${task.status}; manual server-side review requires ${MANUAL_SERVER_REVIEW_STATUSES.join('/')}`);
                 }
                 if (!this.serverReviewDriver) {
                     throw new ApiError(409, `Server review pipeline is not configured; cannot dispatch review for ${taskId}`);
                 }
-                // in_progress 且 phase 未定：dev 既可能交 spec-done 也可能交 code-done，评审对象无从判定
                 if (task.status === 'in_progress' && task.phase === undefined) {
                     throw new ApiError(409, `Task ${taskId} has no phase yet (the dev has not delivered spec-done/code-done); wait for the dev signal or use Cancel/Retry`);
                 }
                 // 手工发起=明确要求跑一次 QA 评审；无 QA 时必须拒绝，不得落入自动通过/停驻兜底
-                const qaAvailable = (task.qaAgentId !== undefined && !!this.getAgentConfig(task.qaAgentId))
-                    || !!this.findQaPartner(task.agentId);
+                const qaAvailable = task.qaAgentId !== undefined
+                    && this.getAgentConfig(task.qaAgentId)?.role === 'qa';
                 if (!qaAvailable) {
                     throw new ApiError(400, `Task ${taskId} has no QA partner configured; manual review requires a QA agent`);
                 }
-                const isSpec = task.phase === 'spec';
+                const isSpec = isSpecStagePhase(task.phase);
                 const cap = this.config.review.rounds + (task.maxRoundsContinues ?? 0);
                 const round = isSpec ? (task.specReviewRound ?? 0) : task.reviewRound;
                 if (round + 1 > cap) {
@@ -4561,18 +4946,12 @@ export class AgentManager {
             if (!task.branch) {
                 throw new ApiError(400, `Task ${taskId} has no branch; cannot dispatch review`);
             }
-            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;
-            }
+            const qaId = task.qaAgentId;
             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;
+                throw new ApiError(400, `Task ${taskId} has no QA participant; cannot dispatch review`);
+            }
+            if (this.getAgentConfig(qaId)?.role !== 'qa') {
+                throw new ApiError(409, `Task ${taskId} QA participant ${qaId} is unavailable`);
             }
             this.manualReviewInFlight.add(taskId);
             return { mode: 'github', qaId, devAgentId: task.agentId, taskStatusAtClaim: task.status };
@@ -4658,7 +5037,6 @@ export class AgentManager {
                 await this.taskStore.set({
                     ...fresh,
                     reviewRound: bumpRound ? fresh.reviewRound + 1 : fresh.reviewRound,
-                    qaAgentId: qaId,
                     signalToken: armedToken,
                     updatedAt: new Date().toISOString(),
                 });
@@ -4741,7 +5119,7 @@ export class AgentManager {
         if (task.status !== 'max_rounds') {
             throw new ApiError(409, `Task ${taskId} is not at max_rounds (status=${task.status})`);
         }
-        if (task.phase === 'spec') {
+        if (isSpecStagePhase(task.phase)) {
             throw new ApiError(409, `Continue one round is only supported for code-phase tasks`);
         }
         if (task.reviewMode === 'server') {
@@ -4937,31 +5315,40 @@ export class AgentManager {
             ? ['spec-done', 'code-done']
             : ['spec-done', 'pr-created'];
     }
+    resolveInitialDispatch(task) {
+        if (task.phase === 'research')
+            return { phase: 'research', kinds: ['spec-done'] };
+        return { phase: 'develop', kinds: this.devInitialSignalKinds(task.reviewMode) };
+    }
     mapTaskStateToExpectedWatcher(task) {
         if (task.reviewMode === 'server')
             return this.mapServerTaskToExpectedWatcher(task);
-        if (task.phase === 'spec' && task.status === 'review' && task.qaAgentId) {
-            return { expectedKinds: ['spec-reviewed'], agentId: task.qaAgentId };
-        }
-        if (task.phase === 'spec' && task.status === 'fixing' && task.agentId) {
-            return { expectedKinds: ['spec-fixed'], agentId: task.agentId };
-        }
-        if (task.phase !== 'spec' && task.status === 'fixing' && task.agentId) {
-            return { expectedKinds: ['pr-fixed'], agentId: task.agentId };
-        }
-        if (task.phase === undefined && task.status === 'in_progress' && task.agentId) {
-            return { expectedKinds: ['spec-done', 'pr-created'], agentId: task.agentId };
+        const specStage = isSpecStagePhase(task.phase);
+        if (task.status === 'review' && task.qaAgentId) {
+            return {
+                expectedKinds: specStage ? ['spec-reviewed'] : ['pr-approved', 'pr-changes-requested'],
+                agentId: task.qaAgentId,
+            };
         }
-        if (task.phase === 'code' && task.status === 'in_progress' && task.agentId) {
-            return { expectedKinds: ['pr-created'], agentId: task.agentId };
+        if (task.status === 'fixing' && task.agentId) {
+            return {
+                expectedKinds: [specStage ? 'spec-fixed' : 'pr-fixed'],
+                agentId: task.agentId,
+            };
         }
-        if (task.phase !== 'spec' && task.status === 'review' && task.qaAgentId) {
-            return { expectedKinds: ['pr-approved', 'pr-changes-requested'], agentId: task.qaAgentId };
+        if (task.status === 'in_progress' && task.agentId) {
+            if (task.phase === 'research')
+                return { expectedKinds: ['spec-done'], agentId: task.agentId };
+            if (task.phase === 'code')
+                return { expectedKinds: ['pr-created'], agentId: task.agentId };
+            if (task.phase === undefined) {
+                return { expectedKinds: ['spec-done', 'pr-created'], agentId: task.agentId };
+            }
         }
         return undefined;
     }
     mapServerTaskToExpectedWatcher(task) {
-        const isSpec = task.phase === 'spec';
+        const isSpec = isSpecStagePhase(task.phase);
         if (task.status === 'review' && task.qaAgentId) {
             return { expectedKinds: [isSpec ? 'spec-reviewed' : 'code-reviewed'], agentId: task.qaAgentId };
         }
@@ -4969,8 +5356,11 @@ export class AgentManager {
             return { expectedKinds: [isSpec ? 'spec-fixed' : 'code-fixed'], agentId: task.agentId };
         }
         if (task.status === 'in_progress' && task.agentId) {
-            if (task.phase === 'code')
+            if (task.phase === 'research')
+                return { expectedKinds: ['spec-done'], agentId: task.agentId };
+            if (task.phase === 'code') {
                 return { expectedKinds: ['code-done'], agentId: task.agentId };
+            }
             return { expectedKinds: ['spec-done', 'code-done'], agentId: task.agentId };
         }
         if (task.status === 'approved' && task.agentId) {
@@ -5002,7 +5392,7 @@ export class AgentManager {
             if (!t)
                 throw new ApiError(404, 'Task not found');
             const retryable = TERMINAL_STATUSES.includes(t.status)
-                || (t.status === 'max_rounds' && t.phase === 'spec');
+                || (t.status === 'max_rounds' && isSpecStagePhase(t.phase));
             if (!retryable) {
                 throw new ApiError(409, `Task ${taskId} cannot be retried in status "${t.status}"; cancel it first or wait for completion`);
             }
@@ -5037,7 +5427,11 @@ export class AgentManager {
             if (patch.preferredAgentId !== undefined && patch.preferredAgentId !== task.preferredAgentId) {
                 if (patch.preferredAgentId === '') {
                     task.preferredAgentId = '';
+                    task.agentId = '';
+                    task.devAgentId = '';
+                    delete task.phase;
                     delete task.qaAgentId;
+                    delete task.researchAgentId;
                 }
                 else {
                     const cfg = this.getAgentConfig(patch.preferredAgentId);
@@ -5046,10 +5440,23 @@ export class AgentManager {
                     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`);
+                    if (!TASK_OWNER_ROLES.has(cfg.role))
+                        throw new ApiError(400, `Agent is not dev or research role`);
+                    const group = this.findAgentGroup(cfg.id);
+                    const dev = group?.find(agent => agent.role === 'dev');
+                    if (!dev)
+                        throw new ApiError(409, `Agent ${cfg.id} has no dev agent in its group`);
                     task.preferredAgentId = patch.preferredAgentId;
-                    const qaId = this.findQaPartner(patch.preferredAgentId)?.id;
+                    task.devAgentId = dev.id;
+                    if (cfg.role === 'research') {
+                        task.phase = 'research';
+                        task.researchAgentId = cfg.id;
+                    }
+                    else {
+                        delete task.phase;
+                        delete task.researchAgentId;
+                    }
+                    const qaId = group?.find(agent => agent.role === 'qa')?.id;
                     if (qaId) {
                         task.qaAgentId = qaId;
                     }
@@ -5095,7 +5502,7 @@ export class AgentManager {
             if (!serverApprovedRetry && task.status !== 'max_rounds') {
                 throw new ApiError(409, `Task ${taskId} is not at max_rounds (status=${task.status})`);
             }
-            if (task.phase === 'spec') {
+            if (isSpecStagePhase(task.phase)) {
                 throw new ApiError(409, `Mark complete is only supported for code-phase tasks`);
             }
             if (task.reviewMode !== 'server' && (!task.prNumber || !task.branch)) {
@@ -5515,7 +5922,6 @@ export class AgentManager {
                 signalToken: restore.signalToken,
                 reviewHeadAnchorSha: restore.reviewHeadAnchorSha,
                 reviewDispatchedAt: restore.reviewDispatchedAt,
-                qaAgentId: undefined,
                 updatedAt: new Date().toISOString(),
             });
             return true;
@@ -5543,11 +5949,8 @@ export class AgentManager {
         const task = await this.taskStore.get(taskId);
         if (!task)
             return null;
-        const transition = await this.transitionTaskStatus(taskId, 'spec-ready', { fromStatus: ['review', 'in_progress', 'fixing'] }, 
-        // QA 在停驻期解绑，残留 qaAgentId 会让后续 approve/打回误发释放；复审经 findQaPartner 回绑
-        {
+        const transition = await this.transitionTaskStatus(taskId, 'spec-ready', { fromStatus: ['review', 'in_progress', 'fixing'] }, {
             phase: 'spec',
-            qaAgentId: undefined,
             ...(opts.specReviewRound !== undefined ? { specReviewRound: opts.specReviewRound } : {}),
         });
         if (!transition)
@@ -5580,6 +5983,9 @@ export class AgentManager {
             if (fresh.status !== 'spec-ready') {
                 throw new ApiError(409, `Task ${taskId} is ${fresh.status}; spec verdict requires spec-ready`);
             }
+            if (verdict === 'archive' && !fresh.researchAgentId) {
+                throw new ApiError(409, `Task ${taskId} is not a Research task; only Research specs can be archived`);
+            }
             if (this.specVerdictInFlight.has(taskId)) {
                 throw new ApiError(409, `Task ${taskId} spec verdict is already being processed`);
             }
@@ -5601,13 +6007,45 @@ export class AgentManager {
         const round = task.specReviewRound ?? 1;
         const at = new Date().toISOString();
         const roundData = await store.getRound(taskId, 'spec', round);
-        // 停驻路径必然已存轮次；缺失时补一条空轮次，保证 userDecision 留痕与 fix 闭环
-        const base = roundData ?? { round, phase: 'spec', content: '', startedAt: at };
+        if (!roundData || roundData.phase !== 'spec') {
+            throw new ApiError(409, `Task ${taskId} has no persisted spec review round ${round}`);
+        }
+        const base = roundData;
+        if (verdict === 'archive') {
+            await store.putRound(taskId, 'spec', {
+                ...base,
+                userDecision: { verdict, ...(trimmed ? { comments: trimmed } : {}), at },
+            });
+            const transition = await this.transitionTaskStatus(taskId, 'done', { fromStatus: ['spec-ready'] });
+            if (!transition)
+                throw new ApiError(409, `Task ${taskId} changed while archiving`);
+            this.stopPhaseSignalWatcher(taskId);
+            const participants = new Set([
+                task.agentId,
+                task.devAgentId,
+                task.qaAgentId,
+                task.researchAgentId,
+            ].filter((id) => typeof id === 'string' && id !== ''));
+            for (const agentId of participants) {
+                const state = await this.agentStore.get(agentId);
+                if (state?.taskId !== taskId)
+                    continue;
+                const released = await this.releaseAgentForTask(agentId, taskId, 'idle', { allowAwaitingHuman: true }).catch(() => false);
+                if (!released) {
+                    await this.emitIntervention(task.projectId, agentId, taskId, {
+                        phase: 'spec-archive-agent-release-failed',
+                        agentId,
+                    });
+                }
+            }
+            return (await this.taskStore.get(taskId));
+        }
         if (verdict === 'approve') {
             await store.putRound(taskId, 'spec', { ...base, userDecision: { verdict, at } });
             const result = await this.transitionToCodePhase(taskId);
-            if (!result)
-                throw new ApiError(500, `Failed to dispatch code phase for task ${taskId}`);
+            if (!result) {
+                throw new ApiError(409, `Dev is unavailable for task ${taskId}; approval was recorded and can be retried`);
+            }
             return result;
         }
         // 打回消耗一轮修订；到达上限时拒绝而非派发注定进 max_rounds 的修订，让用户当场决策
@@ -5647,7 +6085,7 @@ export class AgentManager {
             if (fresh.status !== 'ready') {
                 throw new ApiError(409, `Task ${taskId} is ${fresh.status}; code verdict requires ready`);
             }
-            if (fresh.phase === 'spec') {
+            if (isSpecStagePhase(fresh.phase)) {
                 throw new ApiError(409, `Task ${taskId} is in the spec phase; reject the spec via the spec verdict instead`);
             }
             if (fresh.reviewMode !== 'server') {
@@ -5740,40 +6178,82 @@ export class AgentManager {
             return empty;
         }
     }
+    isResearchHandoff(task, devAgentId) {
+        return task.researchAgentId !== undefined && task.researchAgentId !== devAgentId;
+    }
+    dispatchCodePhasePrompt(task, devAgentId, signalToken, specDocuments, currentSpecRound) {
+        const expectedKind = task.reviewMode === 'server' ? 'code-done' : 'pr-created';
+        const dispatchOpts = {
+            signalToken,
+            specDocuments,
+            ...(currentSpecRound !== undefined ? { currentSpecRound } : {}),
+            armBeforeInject: () => this.setupPhaseSignalWatcher(task.id, devAgentId, expectedKind, signalToken),
+        };
+        return this.isResearchHandoff(task, devAgentId)
+            ? this.startSession(task.id, devAgentId, 'code', {
+                ...dispatchOpts,
+                preserveBindingOnFailure: true,
+            })
+            : this.continueSession(task.id, devAgentId, 'code', dispatchOpts);
+    }
     async transitionToCodePhase(taskId) {
         const task = await this.taskStore.get(taskId);
         if (!task)
             return null;
-        const devAgentId = task.agentId;
-        if (!devAgentId)
-            return null;
-        const newToken = createSignalToken();
-        const transition = await this.transitionTaskStatus(taskId, 'in_progress', { fromStatus: ['review', 'fixing', 'in_progress', 'spec-ready'] }, { phase: 'code', signalToken: newToken });
-        if (!transition)
+        const devAgentId = task.devAgentId;
+        const dev = devAgentId ? this.getAgentConfig(devAgentId) : undefined;
+        if (!devAgentId || dev?.role !== 'dev') {
+            await this.emitIntervention(task.projectId, task.agentId, taskId, {
+                phase: 'code-dev-missing',
+                devAgentId,
+            });
             return null;
-        this.stopPhaseSignalWatcher(taskId);
-        const codeKind = task.reviewMode === 'server' ? 'code-done' : 'pr-created';
-        const codeArmed = await this.setupPhaseSignalWatcher(taskId, devAgentId, codeKind, newToken);
-        if (!codeArmed && task.reviewMode === 'server') {
-            await this.holdAgentForUnarmedSignal(taskId, devAgentId, codeKind);
+        }
+        const round = task.specReviewRound ?? 1;
+        const stored = await this.reviewStore?.getRound(taskId, 'spec', round);
+        if (!stored || stored.phase !== 'spec') {
+            await this.emitIntervention(task.projectId, task.agentId, taskId, {
+                phase: 'code-spec-round-missing',
+                round,
+            });
             return null;
         }
-        if (task.qaAgentId) {
-            const released = await this.releaseAgentForTask(task.qaAgentId, taskId, 'idle')
+        const researchAgentId = task.researchAgentId;
+        const researchHandoff = this.isResearchHandoff(task, devAgentId);
+        const releaseParticipant = async (agentId, failurePhase) => {
+            const released = await this.releaseAgentIfBound(agentId, taskId, { allowAwaitingHuman: true })
                 .catch(() => false);
             if (!released) {
-                await this.emitIntervention(task.projectId, task.qaAgentId, taskId, { phase: 'code-phase-qa-release-failed', qaAgentId: task.qaAgentId });
+                await this.emitIntervention(task.projectId, agentId, taskId, { phase: failurePhase, agentId });
             }
+            return released;
+        };
+        if (researchHandoff && researchAgentId) {
+            if (!await releaseParticipant(researchAgentId, 'code-phase-research-release-failed'))
+                return null;
+        }
+        if (task.qaAgentId && !await releaseParticipant(task.qaAgentId, 'code-phase-qa-release-failed')) {
+            return null;
         }
         const acquired = await this.acquireAgentForTask(devAgentId, taskId, 'code');
         if (!acquired) {
-            await this.markAwaitingHuman(devAgentId, 'code-dispatch-failed', 'Dev could not be acquired for the code phase after spec approval; the task looks in_progress but the code prompt was never dispatched. Resume the agent to redispatch or cancel the task.', { expectedTaskId: taskId }).catch(() => undefined);
-            await this.emitIntervention(task.projectId, devAgentId, taskId, { phase: 'code-dev-acquire-failed', devAgentId });
+            await this.emitIntervention(task.projectId, devAgentId, taskId, {
+                phase: 'code-dev-acquire-failed',
+                devAgentId,
+            });
             return null;
         }
-        let resumed = false;
+        const newToken = createSignalToken();
+        const transition = await this.transitionTaskStatus(taskId, 'in_progress', { fromStatus: ['review', 'fixing', 'in_progress', 'spec-ready'] }, { agentId: devAgentId, phase: 'code', signalToken: newToken });
+        if (!transition) {
+            await this.releaseAgentForTask(devAgentId, taskId, 'idle', { allowAwaitingHuman: true })
+                .catch(() => undefined);
+            return null;
+        }
+        this.stopPhaseSignalWatcher(taskId);
+        let started = false;
         try {
-            resumed = await this.continueSession(taskId, devAgentId, 'code');
+            started = await this.dispatchCodePhasePrompt(task, devAgentId, newToken, stored.documents);
         }
         catch (err) {
             if (err instanceof DispatchTerminalError) {
@@ -5782,12 +6262,15 @@ export class AgentManager {
             else if (!(err instanceof EnsureSessionError && err.partial.handled)) {
                 await this.markAwaitingHuman(devAgentId, 'code-dispatch-failed', 'Code-phase prompt was not delivered after spec approval; the task looks in_progress but the dev never received it. Resume/restart the agent or cancel the task.', { expectedTaskId: taskId }).catch(() => undefined);
             }
-            console.error(`[AgentManager] transitionToCodePhase continueSession(dev=${devAgentId}) failed:`, err);
+            console.error(`[AgentManager] transitionToCodePhase dispatch(dev=${devAgentId}) failed:`, err);
             throw err;
         }
-        if (!resumed) {
+        if (!started) {
             await this.markAwaitingHuman(devAgentId, 'code-dispatch-failed', 'Code-phase prompt was not delivered after spec approval; the task looks in_progress but the dev never received it. Resume/restart the agent or cancel the task.', { expectedTaskId: taskId }).catch(() => undefined);
-            await this.emitIntervention(task.projectId, devAgentId, taskId, { phase: 'code-resume-failed', devAgentId });
+            await this.emitIntervention(task.projectId, devAgentId, taskId, {
+                phase: researchHandoff ? 'code-start-failed' : 'code-resume-failed',
+                devAgentId,
+            });
             return null;
         }
         return await this.taskStore.get(taskId);
@@ -5804,13 +6287,7 @@ export class AgentManager {
             if (task.reviewMode !== 'server' && opts.phase !== 'spec') {
                 throw new Error(`dispatchServerReviewToQa: task ${taskId} is not in server review mode`);
             }
-            let recordedQaId = task.qaAgentId;
-            if (recordedQaId && !this.getAgentConfig(recordedQaId)) {
-                console.warn(`[dispatchServerReviewToQa] task ${taskId}.qaAgentId="${recordedQaId}" no longer in config; ` +
-                    `falling back to findQaPartner(${task.agentId})`);
-                recordedQaId = undefined;
-            }
-            const qaId = recordedQaId ?? this.findQaPartner(task.agentId)?.id;
+            const qaId = task.qaAgentId;
             if (!qaId) {
                 const entryKind = task.status === 'fixing'
                     ? (opts.phase === 'spec' ? 'spec-fixed' : 'code-fixed')
@@ -5819,6 +6296,17 @@ export class AgentManager {
                 await this.emitIntervention(task.projectId, task.agentId, taskId, { phase: 'server-review-no-qa-partner', devAgentId: task.agentId });
                 return null;
             }
+            if (this.getAgentConfig(qaId)?.role !== 'qa') {
+                const entryKind = task.status === 'fixing'
+                    ? (opts.phase === 'spec' ? 'spec-fixed' : 'code-fixed')
+                    : (opts.phase === 'spec' ? 'spec-done' : 'code-done');
+                await this.setupPhaseSignal(taskId, task.agentId, entryKind, { skipSnapshot: true });
+                await this.emitIntervention(task.projectId, task.agentId, taskId, {
+                    phase: 'server-review-qa-unavailable',
+                    qaAgentId: qaId,
+                });
+                return null;
+            }
             const roundField = opts.phase === 'spec' ? (task.specReviewRound ?? 0) : task.reviewRound;
             return {
                 qaId,
@@ -5892,7 +6380,6 @@ export class AgentManager {
             : { reviewRound: newRound };
         const transition = await this.transitionTaskStatus(taskId, 'review', { fromStatus: ['in_progress', 'fixing', 'review'] }, {
             signalToken: newToken,
-            qaAgentId: qaId,
             reviewDispatchedAt: new Date().toISOString(),
             ...(opts.reviewHeadAnchorSha ? { reviewHeadAnchorSha: opts.reviewHeadAnchorSha } : {}),
             ...(opts.batch
@@ -5993,7 +6480,7 @@ export class AgentManager {
             const task = await this.taskStore.get(taskId);
             if (!task)
                 throw new Error(`dispatchServerFixToDev: task ${taskId} not found`);
-            if (task.reviewMode !== 'server' && task.phase !== 'spec') {
+            if (task.reviewMode !== 'server' && !isSpecStagePhase(task.phase)) {
                 throw new Error(`dispatchServerFixToDev: task ${taskId} is not in server review mode`);
             }
             if (!task.agentId)
@@ -6003,7 +6490,7 @@ export class AgentManager {
                 qaAgentId: task.qaAgentId,
                 projectId: task.projectId,
                 newToken: createSignalToken(),
-                taskPhase: (task.phase ?? 'code'),
+                taskPhase: task.phase,
                 currentSpecRound: task.specReviewRound,
                 originalStatus: task.status,
                 originalToken: task.signalToken,
@@ -6029,7 +6516,7 @@ export class AgentManager {
             return null;
         }
         if (qaAgentId) {
-            const released = await this.releaseAgentForTask(qaAgentId, taskId, 'idle')
+            const released = await this.releaseAgentIfBound(qaAgentId, taskId)
                 .catch(() => false);
             if (!released) {
                 await rearmReviewedSignal();