baxian 1.2.55 → 1.2.56

package/dist/agent/manager.js

@@ -1,13 +1,13 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+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';
@@ -137,7 +137,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 +269,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 +311,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 +361,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;
@@ -1282,6 +1320,7 @@ export class AgentManager {
             projectId: cfg.projectId,
             taskId,
             lockToken: token,
+            ...(phase === 'code' && !sameTaskReentry ? { bootstrappingTaskId: taskId } : {}),
             updatedAt: now,
         }));
         return true;
@@ -1345,10 +1384,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 +1423,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 +1499,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 +1513,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 +1539,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 +1958,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 +1998,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)
@@ -2207,6 +2338,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 +2381,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 = [];
@@ -2305,6 +2467,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 +2480,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 +2491,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 +2509,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 +2612,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 +2902,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 +2911,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 +2950,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 +2964,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 +3024,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 +3052,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 +3090,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 +3104,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 +3323,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 +3342,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 +3398,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) {
         }
@@ -3437,6 +3589,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`);
@@ -3499,16 +3654,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 +3801,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;
@@ -3884,6 +4043,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 +4064,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 +4111,7 @@ export class AgentManager {
                 task,
                 phase,
                 agent,
-                workdir: taskWorkdir,
+                workdir: verifiedWorkdir,
                 skillRegistry: this.skillRegistry,
                 ...(signalToken ? { signalToken } : {}),
                 ...(useIncrementalNudge
@@ -3980,6 +4160,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 +4180,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 +4219,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 +4271,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);
@@ -4493,8 +4734,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 +4770,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 +4801,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 +4892,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 +4974,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 +5170,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 +5211,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 +5247,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 +5282,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 +5295,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 +5357,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 +5777,6 @@ export class AgentManager {
                 signalToken: restore.signalToken,
                 reviewHeadAnchorSha: restore.reviewHeadAnchorSha,
                 reviewDispatchedAt: restore.reviewDispatchedAt,
-                qaAgentId: undefined,
                 updatedAt: new Date().toISOString(),
             });
             return true;
@@ -5543,11 +5804,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 +5838,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 +5862,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 +5940,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 +6033,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 +6117,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 +6142,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 +6151,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 +6235,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 +6335,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 +6345,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 +6371,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();