baxian 2.0.31 → 2.0.33

package/dist/agent/manager.js

@@ -1,11 +1,11 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { join, normalize } from 'node:path';
-import { tmpdir } from 'node:os';
+import { hostname, tmpdir } from 'node:os';
 import { createSignalToken, PASSIVE_VERDICT_WATCH } 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, TASK_OWNER_ROLES, TERMINAL_INTERVENTION_PHASES, effectiveTaskReviewRound, isSpecStagePhase, isTaskOpen, taskAttentionGeneration, taskGenerationGuard, taskReviewRound, taskMatchesGeneration, } from '../shared/index.js';
+import { BRANCH_PREFIX, isValidBranchName, retainedUntrackedFilesWithinLimit, 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, TERMINAL_INTERVENTION_PHASES, effectiveTaskReviewRound, isSpecStagePhase, isTaskOpen, taskAttentionGeneration, taskGenerationGuard, taskReviewRound, taskMatchesGeneration, } from '../shared/index.js';
 import { buildProjectDriver, buildProjectPromptContext, makeDriverExec, repoIdentityKey, } from '../platform/driver-host.js';
 import { DriverOpError, safeDriverErrorText, validateCommentBody, } from '../platform/types.js';
 import { versionTimeOf } from '../platform/row-schema.js';
@@ -22,6 +22,7 @@ import { imageFilename, agentHostPath, writeImageToHost } from './image-input.js
 import { TmuxManager, TmuxOutcomeUnknownError, ReplNotReadyError, isBlockedOnStartupDialog, hasRuntimeReadyView, hasReplProcTitle, isShellProcTitle, PaneGoneError, } from './tmux.js';
 import { BranchManager, DirtyWorkdirError, ReviewHeadMismatchError, isAutoDeletableTaskBranch, } from './branch.js';
 import { RepoStore, createRepoStoreCache } from './repo-store.js';
+import { inspectUntrackedFiles } from './untracked-files.js';
 import { PhaseSignalWatcher, } from './phase-signal-watcher.js';
 import { buildPromptInline, buildGreetingPrompt, PromptSizeError, MAX_PROMPT_BYTES_ROUTE_LIMIT, } from './prompt.js';
 import { ApiError } from '../errors.js';
@@ -182,9 +183,9 @@ const RUNTIME_LIVENESS_SAMPLES = 3;
 export function canDispatchWithBinding(binding) {
     return !binding?.taskId && !binding?.creationToken && binding?.status !== 'awaiting_human';
 }
+const CHECKOUT_PREPARATION_HOLD_PHASES = new Set(['checkout-preparation-failed', 'dirty-workdir']);
 const RECOVERABLE_QA_DISPATCH_HOLD_PHASES = new Set([
-    'checkout-preparation-failed',
-    'dirty-workdir',
+    ...CHECKOUT_PREPARATION_HOLD_PHASES,
     'branch-cleanup-pending',
 ]);
 export function isRecoverableQaDispatchHold(binding) {
@@ -211,6 +212,30 @@ function cancelPhaseDowngrades(prev, next) {
     return cancelPhaseRank(next) < cancelPhaseRank(prev);
 }
 const REGREET_REQUIRED_HOLD_PHASES = new Set(['greeting_failed']);
+const TASK_REPLAY_FAILED_RUNBOOK = 'Resolve the cause, then retry the current step from the task page. '
+    + 'If the task branch was never created, cancel the task and run it again. '
+    + 'Resume does not resend the task prompt.';
+const DELIVERED_BOOTSTRAP_RUNBOOK = 'The initial prompt was already delivered; replaying would dispatch the task twice. '
+    + 'Verify the task outcome in the terminal, or cancel the task.';
+const PROMPT_MAYBE_RUNNING_PHASES = new Set([
+    'dispatch-failed:ack_unknown',
+    'dev-wait-gate-failed-after-qa-started',
+]);
+function taskReplayFailure(error) {
+    const dirty = error instanceof DirtyWorkdirError;
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof DispatchTerminalError && error.reason === 'ack_unknown') {
+        return {
+            phase: 'dispatch-failed:ack_unknown',
+            reason: `Task prompt delivery requires verification: ${message}. The prompt may already be running. Verify the task outcome in the terminal, or cancel the task.`,
+        };
+    }
+    const preparation = dirty ? 'Save the Workdir changes by committing or stashing them first. ' : '';
+    return {
+        phase: dirty ? 'dirty-workdir' : 'restart-redispatch-failed',
+        reason: `Task prompt replay failed: ${message}. ${preparation}${TASK_REPLAY_FAILED_RUNBOOK}`,
+    };
+}
 const RECOVERY_FAILED_AGENT_RUNBOOK = 'Fix the agent Workdir (or wait for the transient failure to clear), then Resume the agent.';
 const RECOVERY_FAILED_TASK_RUNBOOK = 'Fix the agent Workdir (or wait for the transient failure to clear), '
     + 'then Resume the agent and use the recommended action on the task page.';
@@ -1856,14 +1881,14 @@ export class AgentManager {
                         }
                     }
                     if (cfg.role === 'dev' && boundTask) {
-                        const branches = new BranchManager(runner);
+                        const branches = this.taskBranchManager(runner, agentId, expectedTaskId);
                         const cleanup = await branches.cleanupTaskBranch(releaseWorkdir, this.cleanupIdentityFor(boundTask), () => this.assertTaskGeneration(agentId, expectedTaskId, lockToken, releaseWorkdir).then(() => undefined));
                         await this.persistBranchCleanupOutcome(boundTask, agentId, cleanup);
                         if (cleanup.status !== 'deleted')
                             await branches.parkOnDefaultDetached(releaseWorkdir);
                     }
                     else {
-                        await new BranchManager(runner).parkOnDefaultDetached(releaseWorkdir);
+                        await this.taskBranchManager(runner, agentId, expectedTaskId).parkOnDefaultDetached(releaseWorkdir);
                     }
                     await this.assertTaskGeneration(agentId, expectedTaskId, lockToken, releaseWorkdir);
                 }
@@ -2066,7 +2091,7 @@ export class AgentManager {
                 if (!(await this.lockManager.isOwner(cfg.id, owner, token)))
                     continue;
                 for (const task of targets) {
-                    const cleanup = await branches.cleanupTaskBranch(workdir, this.cleanupIdentityFor(task), () => this.assertTaskLockOwner(cfg.id, owner, token));
+                    const cleanup = await this.taskBranchManager(runner, cfg.id, task.id).cleanupTaskBranch(workdir, this.cleanupIdentityFor(task), () => this.assertTaskLockOwner(cfg.id, owner, token));
                     cleanupResults.push({ task, cleanup });
                 }
             }
@@ -2711,16 +2736,25 @@ export class AgentManager {
                 return { resumed: false, releasedBinding: false, reason };
             }
             const boundTask = state.taskId ? await this.taskStore.get(state.taskId) : null;
-            const PROMPT_MAYBE_RUNNING_PHASES = new Set([
-                'dispatch-failed:ack_unknown',
-                'dev-wait-gate-failed-after-qa-started',
-            ]);
+            if (boundTask && ((state.awaitingPhase === 'restart-redispatch-failed'
+                && (boundTask.status === 'in_progress' || boundTask.status === 'fixing' || boundTask.status === 'approved'))
+                || (state.awaitingPhase === 'bootstrap-marker-clear-failed' && boundTask.status === 'in_progress'))) {
+                const runbook = state.awaitingPhase === 'bootstrap-marker-clear-failed'
+                    ? DELIVERED_BOOTSTRAP_RUNBOOK : TASK_REPLAY_FAILED_RUNBOOK;
+                const reason = `Resume is blocked for active task ${boundTask.id} (${state.awaitingPhase}). ${runbook}`;
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} — ${reason}`);
+                return { resumed: false, releasedBinding: false, reason };
+            }
             if (state.awaitingPhase != null
                 && PROMPT_MAYBE_RUNNING_PHASES.has(state.awaitingPhase)
-                && boundTask && ACTIVE_TASK_STATUSES.has(boundTask.status)) {
+                && boundTask && ACTIVE_TASK_STATUSES.has(boundTask.status)
+                && !(state.awaitingPhase === 'dispatch-failed:ack_unknown'
+                    && boundTask.devAgentId === agentId && boundTask.qaAgentId !== agentId
+                    && ['spec-ready', 'review', 'merge-ready', 'max_rounds'].includes(boundTask.status))) {
                 const uncertainRecovery = state.awaitingPhase === 'dispatch-failed:ack_unknown'
+                    && boundTask.status === 'review' && boundTask.qaAgentId === agentId
                     ? ' Confirm the uncertain review dispatch as not delivered, cancel the task,'
-                    : ` Cancel task ${state.taskId}`;
+                    : ` Verify the task outcome in the terminal, cancel task ${state.taskId},`;
                 const reason = `Prompt may still be running (${state.awaitingPhase}); Resume is blocked until the task outcome arrives.${uncertainRecovery} or DELETE the agent to recover.`;
                 console.warn(`[AgentManager] resumeAgent: agent ${agentId} — ${reason}`);
                 return { resumed: false, releasedBinding: false, reason };
@@ -3430,7 +3464,7 @@ export class AgentManager {
         await tmux.clearComposerDraft(pane, runtime);
         // 退出文本与 Enter 分两次守卫写:前台在两者之间换了进程,回车就不发,/exit 留在草稿里等下一次清稿,而不会打进 shell 或别的进程
         try {
-            if (!await this.reachedRuntime(() => tmux.submitToRuntime(pane, runtime, REPL_EXIT_COMMAND[cfg.runtime])))
+            if (!await this.reachedRuntime(() => tmux.submitToRuntime(pane, runtime, REPL_EXIT_COMMAND[cfg.runtime], { expectRuntimeExit: true })))
                 return;
         }
         catch (err) {
@@ -3643,7 +3677,8 @@ export class AgentManager {
                 retireOldOnce();
             if (!(await args.stillCurrent(newToken)))
                 return false;
-            const held = await args.holdFailure(newToken, `REPL restarted but replaying the task prompt failed: ${err.message}. Resume to retry, or cancel the task.`);
+            const failure = taskReplayFailure(err);
+            const held = await args.holdFailure(newToken, failure.phase, failure.reason);
             if (held)
                 return true;
             if (!(await args.stillCurrent(newToken)))
@@ -3703,7 +3738,13 @@ export class AgentManager {
             };
             const resumed = await args.continueWith(newToken, fence);
             if (resumed) {
-                await args.afterDelivered?.(newToken);
+                try {
+                    await args.afterDelivered?.(newToken);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    throw new DispatchTerminalError('ack_unknown', `The prompt for task ${taskId} was already delivered, but saving its delivery status failed: ${message}`);
+                }
                 return true;
             }
             releaseClaimOnce();
@@ -3758,14 +3799,17 @@ export class AgentManager {
         });
         const holdReplayFailure = (phase, reason) => this.holdReplayFailureIfCurrent(agentId, task, phase, reason, entryHold);
         try {
+            const mapped = this.mapTaskStateToExpectedWatcher(task);
+            if (entryHold.phase && PROMPT_MAYBE_RUNNING_PHASES.has(entryHold.phase)
+                && ((task.status === 'approved' && agent.role === 'dev') || mapped?.agentId === agentId))
+                return true;
             if (task.status === 'approved' && agent.role === 'dev') {
                 return await this.replayApprovedHolderAfterReplRestart(agentId, task, entryHold, { clearEntryHold, holdReplayFailure });
             }
-            const mapped = this.mapTaskStateToExpectedWatcher(task);
             if (!mapped || mapped.agentId !== agentId)
                 return false;
             if (!task.signalToken) {
-                return await holdReplayFailure('restart-redispatch-failed', 'REPL restarted mid-pass but the task has no signal token to replay the prompt with; cancel the task or re-dispatch it.');
+                return await holdReplayFailure('restart-redispatch-failed', 'The task has no signal token to replay its prompt with; cancel the task and run it again.');
             }
             const signalToken = task.signalToken;
             const replayTask = (phase, opts = {}, afterDelivered) => this.runRotatedReplay({
@@ -3788,7 +3832,7 @@ export class AgentManager {
                     return true;
                 },
                 stillCurrent: taskStillCurrent,
-                holdFailure: (newToken, reason) => this.holdReplayFailureIfCurrent(agentId, { ...task, signalToken: newToken }, 'restart-redispatch-failed', reason, entryHold),
+                holdFailure: (newToken, phase, reason) => this.holdReplayFailureIfCurrent(agentId, { ...task, signalToken: newToken }, phase, reason, entryHold),
                 continueWith: (newToken, fence) => this.continueSession(taskId, agentId, phase, {
                     ...opts,
                     signalToken: newToken,
@@ -3799,7 +3843,7 @@ export class AgentManager {
             });
             const replayInitialBootstrap = async (phase, opts) => {
                 if (entryHold.phase === 'bootstrap-marker-clear-failed') {
-                    return holdReplayFailure('restart-redispatch-failed', 'REPL restarted while the initial prompt was already delivered (its bootstrap marker clear had failed); replaying would dispatch the task twice. Resume and verify the Workdir, or cancel the task.');
+                    return holdReplayFailure('bootstrap-marker-clear-failed', DELIVERED_BOOTSTRAP_RUNBOOK);
                 }
                 const bindingBefore = await this.agentStore.get(agentId);
                 if (!(await clearEntryHold()))
@@ -3845,8 +3889,8 @@ export class AgentManager {
             return false;
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            if (await holdReplayFailure('restart-redispatch-failed', `REPL restarted but replaying the task prompt failed: ${message}. Resume to retry, or cancel the task.`)) {
+            const failure = taskReplayFailure(err);
+            if (await holdReplayFailure(failure.phase, failure.reason)) {
                 return true;
             }
             throw err;
@@ -3915,7 +3959,7 @@ export class AgentManager {
                 return true;
             },
             stillCurrent: completionStillCurrent,
-            holdFailure: (newToken, reason) => this.holdReplayFailureIfCurrent(agentId, task, 'restart-redispatch-failed', reason, entryHold, async (fresh) => episodeMatches(fresh) && completionTokenMatches(fresh, newToken)),
+            holdFailure: (newToken, phase, reason) => this.holdReplayFailureIfCurrent(agentId, task, phase, reason, entryHold, async (fresh) => episodeMatches(fresh) && completionTokenMatches(fresh, newToken)),
             continueWith: (newToken, fence) => this.continueSession(taskId, agentId, 'post-approve', {
                 signalToken: newToken,
                 postApproveEpisode: {
@@ -4212,6 +4256,10 @@ export class AgentManager {
             else {
                 recommendedActions = ['advance', 'cancel'];
             }
+            if (reason === 'bootstrap-marker-clear-failed'
+                || (reason === 'dispatch-failed:ack_unknown' && task.status !== 'review')) {
+                recommendedActions = recommendedActions.filter(action => action !== 'advance');
+            }
             if (task.attention
                 && Date.parse(task.attention.occurredAt) > Date.parse(occurredAt))
                 return;
@@ -6013,6 +6061,204 @@ export class AgentManager {
             return guarded.ran ? guarded.value : null;
         });
     }
+    untrackedFilesHost(agent) {
+        return hostGroupKey(agent.mode, resolveAgentHost(this.config.host, agent.host));
+    }
+    taskBranchManager(runner, agentId, taskId) {
+        return new BranchManager(runner, async (workdir) => {
+            const agent = this.getAgentConfig(agentId);
+            const task = await this.taskStore.get(taskId);
+            return task?.retainedUntrackedFiles?.find(entry => entry.agentId === agentId
+                && entry.workdir === workdir && agent && entry.host === this.untrackedFilesHost(agent))?.pathsBase64 ?? [];
+        });
+    }
+    supportsUntrackedFiles(binding, agent) {
+        return binding?.status === 'awaiting_human' && !!agent
+            && (RECOVERABLE_QA_DISPATCH_HOLD_PHASES.has(binding.awaitingPhase ?? '')
+                || (agent.role === 'dev' && binding.awaitingPhase === 'restart-redispatch-failed'));
+    }
+    async untrackedFilesContext(taskId, agentId) {
+        const task = await this.taskStore.get(taskId);
+        const binding = await this.agentStore.get(agentId);
+        const agent = this.getAgentConfig(agentId);
+        if (!task || !agent || binding?.taskId !== taskId || !binding.workdir || agent.projectId !== task.projectId) {
+            throw new ApiError(409, 'Task or agent binding changed; refresh the task');
+        }
+        if (this.isDeletionInFlight(agentId) || this.cancelCleanupInFlight.has(taskId)) {
+            throw new ApiError(409, 'Task cancellation or agent removal is in progress; wait for it to finish');
+        }
+        if (this.compactInFlight.has(agentId) || this.maintenanceInFlight.has(agentId)) {
+            throw new ApiError(409, 'Agent maintenance is in progress; refresh the file list when it finishes');
+        }
+        if (this.resolveWorkdir(agent, binding) !== binding.workdir)
+            throw new ApiError(409, 'Agent working directory changed; check its configuration');
+        if (task.reviewDispatch?.phase === 'uncertain' || task.reviewDispatch?.phase === 'claimed') {
+            throw new ApiError(409, 'Review delivery is pending or uncertain; verify its outcome before handling files');
+        }
+        if (!this.supportsUntrackedFiles(binding, agent))
+            throw new ApiError(409, 'This agent hold cannot be resumed by handling files');
+        const claim = await this.lockManager.claimOf(agentId);
+        if (claim?.taskId !== taskId || (binding.lockToken && binding.lockToken !== claim.token)) {
+            throw new ApiError(409, 'Agent ownership changed; refresh the task');
+        }
+        const host = this.untrackedFilesHost(agent);
+        const retained = task.retainedUntrackedFiles?.find(entry => entry.agentId === agentId
+            && entry.workdir === binding.workdir && entry.host === host)?.pathsBase64 ?? [];
+        let recovery;
+        if (agent.role === 'qa' && task.status === 'review') {
+            if (task.qaAgentId !== agentId || !task.phase || task.deliveryConfirmation?.phase !== task.phase || !task.prNumber) {
+                throw new ApiError(409, 'Review delivery must be verified in the task before handling files');
+            }
+            recovery = 'qa';
+        }
+        else if (binding.awaitingPhase === 'branch-cleanup-pending' || agent.role === 'qa'
+            || task.status === 'review' || TERMINAL_STATUSES.includes(task.status)) {
+            recovery = 'release';
+        }
+        else if (['in_progress', 'fixing', 'approved'].includes(task.status)) {
+            if (task.status === 'approved' && task.postApproveRevoked)
+                throw new ApiError(409, 'Post-approval work was revoked; confirm recovery in the task before handling files');
+            recovery = 'dev';
+        }
+        else {
+            throw new ApiError(409, `Task cannot continue from ${task.status}; use the task actions before handling files`);
+        }
+        const devFallback = task.branchLocalCleaned?.remoteTipSha
+            ?? (binding.bootstrappingTaskId === taskId && CHECKOUT_PREPARATION_HOLD_PHASES.has(binding.awaitingPhase ?? '') ? 'origin/HEAD' : undefined);
+        const targetRefs = recovery === 'release' ? ['origin/HEAD'] : recovery === 'qa'
+            ? ['origin/HEAD', task.reviewHeadAnchorSha ?? task.latestHeadSha ?? `refs/remotes/origin/${task.branch}`]
+            : [[`refs/heads/${task.branch}`, ...(devFallback ? [devFallback] : [])]];
+        return { task, binding: { ...binding, lockToken: claim.token }, agent, host, retained, recovery, targetRefs,
+            workdir: binding.workdir, runner: this.createRunnerFor(agent) };
+    }
+    untrackedFilesToken(context, fingerprint) {
+        return createHash('sha256').update(JSON.stringify({
+            taskId: context.task.id, generation: taskAttentionGeneration(context.task),
+            head: context.task.reviewHeadAnchorSha, latestHead: context.task.latestHeadSha,
+            branch: context.task.branch, agentId: context.agent.id, host: context.host,
+            workdir: context.workdir, lockToken: context.binding.lockToken,
+            hold: context.binding.awaitingPhase, nonce: context.binding.awaitingNonce,
+            pane: context.binding.paneId, creation: context.binding.creationToken,
+            bootstrap: context.binding.bootstrappingTaskId, reviewDispatch: context.task.reviewDispatch,
+            branchLocalCleaned: context.task.branchLocalCleaned, recovery: context.recovery,
+            runtime: context.agent.runtime, fingerprint, retained: context.retained,
+        })).digest('hex');
+    }
+    retainedUntrackedSelection(context, pathsBase64) {
+        return [
+            ...(context.task.retainedUntrackedFiles ?? []).filter(entry => entry.agentId !== context.agent.id
+                || entry.workdir !== context.workdir || entry.host !== context.host),
+            { agentId: context.agent.id, host: context.host, workdir: context.workdir, pathsBase64: [...new Set([...context.retained, ...pathsBase64])] },
+        ];
+    }
+    async getUntrackedFiles(taskId, agentId) {
+        if (!this.supportsUntrackedFiles(await this.agentStore.get(agentId), this.getAgentConfig(agentId)))
+            return null;
+        const context = await this.untrackedFilesContext(taskId, agentId);
+        const snapshot = await inspectUntrackedFiles(context.runner, context.workdir, undefined, context.targetRefs);
+        return this.withTaskLock(async () => {
+            const fresh = await this.untrackedFilesContext(taskId, agentId);
+            if (this.untrackedFilesToken(context, snapshot.fingerprint) !== this.untrackedFilesToken(fresh, snapshot.fingerprint)) {
+                throw new ApiError(409, 'Task changed during file inspection; refresh the file list');
+            }
+            const files = snapshot.files.filter(file => !fresh.retained.includes(file.pathBase64));
+            const pending = new Set(files.map(file => file.pathBase64));
+            return {
+                agentId, host: fresh.agent.mode === 'remote' ? fresh.agent.host : hostname(),
+                workdir: fresh.workdir, token: this.untrackedFilesToken(fresh, snapshot.fingerprint), files,
+                trackedChanges: snapshot.trackedChanges, conflicts: snapshot.conflicts,
+                manualCleanupRequired: snapshot.conflicts.some(file => !pending.has(file.pathBase64)),
+                keepLimitExceeded: !retainedUntrackedFilesWithinLimit(this.retainedUntrackedSelection(fresh, [...pending])),
+            };
+        });
+    }
+    async resolveUntrackedFiles(taskId, agentId, action, token) {
+        let filesHandled = false;
+        try {
+            const current = await this.untrackedFilesContext(taskId, agentId);
+            const tmux = new TmuxManager(current.runner);
+            const runtime = await this.inspectReleaseRuntime(tmux, agentId, agentRuntimeKindFor(current.agent));
+            if (runtime.kind === 'hold')
+                throw new ApiError(409, runtime.reason);
+            if (runtime.kind === 'pane') {
+                await this.waitForReplPromptReady(tmux, runtime.pane, current.agent.runtime, this.cleanComposerWaitMs, { stableIdle: true });
+            }
+            const snapshot = await inspectUntrackedFiles(current.runner, current.workdir, undefined, current.targetRefs);
+            const prepared = await this.withTaskLock(async () => {
+                let context = await this.untrackedFilesContext(taskId, agentId);
+                if (this.untrackedFilesToken(context, snapshot.fingerprint) !== token) {
+                    throw new ApiError(409, 'Files or task changed; refresh the list and choose again');
+                }
+                if (this.agentOperationQueues.has(agentId))
+                    throw new ApiError(409, 'Agent operation is in progress; refresh the list when it finishes');
+                const pathsBase64 = snapshot.files.filter(file => !context.retained.includes(file.pathBase64)).map(file => file.pathBase64);
+                if (snapshot.conflicts.some(file => action === 'keep' || !pathsBase64.includes(file.pathBase64))) {
+                    throw new ApiError(409, 'Checkout would overwrite local files; move, rename or remove the conflicting files in the terminal');
+                }
+                if (action === 'continue' && pathsBase64.length > 0)
+                    throw new ApiError(409, 'Untracked files need a decision; refresh the list and choose Keep or Discard');
+                if (action !== 'continue' && pathsBase64.length === 0)
+                    throw new ApiError(409, 'No untracked files remain to handle; refresh the list and continue the task');
+                if (snapshot.trackedChanges)
+                    throw new ApiError(409, 'Tracked changes must be saved before continuing');
+                if (action === 'keep') {
+                    const retainedUntrackedFiles = this.retainedUntrackedSelection(context, pathsBase64);
+                    if (!retainedUntrackedFilesWithinLimit(retainedUntrackedFiles))
+                        throw new ApiError(409, 'Retained file limit exceeded (1000 paths or 64 KiB per task); reduce the list in the terminal or discard the listed files');
+                    await this.taskStore.set({ ...context.task, retainedUntrackedFiles, updatedAt: new Date().toISOString() });
+                    filesHandled = true;
+                    context = await this.untrackedFilesContext(taskId, agentId);
+                }
+                // Register the agent lease before releasing the task lock; never reacquire the task lock inside it.
+                const processing = this.outsideTaskMutationScope(() => this.withAgentOperationLease(agentId, async () => {
+                    if (action !== 'discard')
+                        return;
+                    await inspectUntrackedFiles(context.runner, context.workdir, { fingerprint: snapshot.fingerprint, pathsBase64 }, context.targetRefs);
+                    filesHandled = true;
+                }));
+                return { context, pathsBase64, processing };
+            });
+            await prepared.processing;
+            return await this.withTaskLock(async () => {
+                const context = await this.withAgentOperationLease(agentId, async () => {
+                    const refreshed = await this.untrackedFilesContext(taskId, agentId);
+                    if (this.untrackedFilesToken(refreshed, snapshot.fingerprint) !== this.untrackedFilesToken(prepared.context, snapshot.fingerprint)) {
+                        throw new ApiError(409, 'Task changed during file handling; refresh the task before continuing');
+                    }
+                    await this.auditHumanTaskOperation(refreshed.task, 'advance', `untracked-files:${action}`, undefined, { agentId, pathsBase64: prepared.pathsBase64 });
+                    if (refreshed.recovery === 'dev' && refreshed.binding.bootstrappingTaskId === taskId
+                        && refreshed.task.branch && CHECKOUT_PREPARATION_HOLD_PHASES.has(refreshed.binding.awaitingPhase ?? '')) {
+                        await this.taskBranchManager(refreshed.runner, agentId, taskId).switchToTaskBranch(refreshed.workdir, taskId, refreshed.task.branch, refreshed.task.branchCreatedByBaxian === true, refreshed.task.branchLocalCleaned ? { restorableRemoteTip: refreshed.task.branchLocalCleaned.remoteTipSha } : {});
+                        if (refreshed.task.branchLocalCleaned)
+                            await this.clearBranchLocalCleaned(taskId);
+                    }
+                    return refreshed;
+                });
+                if (context.recovery === 'qa') {
+                    return this.dispatchReviewToQa(taskId, { fromStatus: ['review'], expectedTask: taskGenerationGuard(context.task) });
+                }
+                if (context.recovery === 'release') {
+                    const released = await this.releaseAgentForTask(agentId, taskId, 'idle', {
+                        allowAwaitingHuman: true, expectedTask: taskGenerationGuard(context.task),
+                        expectedLockToken: context.binding.lockToken,
+                        expectedHold: { phase: context.binding.awaitingPhase, since: context.binding.awaitingSince, nonce: context.binding.awaitingNonce },
+                    });
+                    if (!released)
+                        throw new ApiError(409, 'Workdir release is still blocked; inspect the task');
+                    await this.emitIntervention(context.task.projectId, agentId, taskId, { phase: 'resumed', previousPhase: context.binding.awaitingPhase });
+                }
+                else {
+                    await this.advanceTask(taskId, { executor: 'dev', agentId });
+                }
+                return (await this.taskStore.get(taskId));
+            });
+        }
+        catch (error) {
+            if (!filesHandled)
+                throw error;
+            throw new ApiError(error instanceof ApiError ? error.status : 500, `${action === 'keep' ? 'Files were kept' : 'Listed files were discarded'}, but continuing the task failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     createRunnerFor(agent) {
         if (this.runnerFactory) {
             return this.runnerFactory(agent);
@@ -7078,7 +7324,7 @@ export class AgentManager {
         const { paneId, pane, workdir } = ensure;
         const runner = this.createRunnerFor(agent);
         const tmux = new TmuxManager(runner);
-        const branchManager = new BranchManager(runner);
+        const branchManager = this.taskBranchManager(runner, agentId, taskId);
         const lockState = await this.agentStore.get(agentId);
         if (!lockState || lockState.taskId !== taskId || lockState.lockToken !== lockToken)
             return false;
@@ -7294,8 +7540,7 @@ export class AgentManager {
             }
             catch (clearErr) {
                 console.warn(`[AgentManager] startSession: clearing bootstrap marker for task=${taskId} failed:`, clearErr);
-                await this.markAwaitingHuman(agentId, 'bootstrap-marker-clear-failed', 'Prompt was delivered but clearing the in-flight bootstrap marker failed; held so recovery does ' +
-                    'not re-dispatch an already-running task. Verify the agent via web terminal, then Resume.', { expectedTaskId: taskId }).catch((holdErr) => {
+                await this.markAwaitingHuman(agentId, 'bootstrap-marker-clear-failed', `Clearing the in-flight bootstrap marker failed. ${DELIVERED_BOOTSTRAP_RUNBOOK}`, { expectedTaskId: taskId }).catch((holdErr) => {
                     console.warn(`[AgentManager] startSession: hold after marker-clear failure for task=${taskId} failed:`, holdErr);
                 });
             }
@@ -7687,7 +7932,7 @@ export class AgentManager {
             return false;
         }
         if (agent.role === 'dev' && task.branch) {
-            const branches = new BranchManager(runner);
+            const branches = this.taskBranchManager(runner, agentId, taskId);
             if (!opts.allowDirtyWorkdir)
                 await branches.assertClean(verifiedWorkdir);
             const actualRef = await branches.currentRef(verifiedWorkdir);
@@ -7862,7 +8107,8 @@ export class AgentManager {
     async rollbackUndeliveredBootstrap(state) {
         if (!state.taskId
             || state.bootstrappingTaskId !== state.taskId
-            || state.awaitingPhase === 'bootstrap-marker-clear-failed') {
+            || state.awaitingPhase === 'bootstrap-marker-clear-failed'
+            || (state.awaitingPhase !== undefined && PROMPT_MAYBE_RUNNING_PHASES.has(state.awaitingPhase))) {
             return false;
         }
         const boundTask = await this.taskStore.get(state.taskId);
@@ -7973,8 +8219,7 @@ export class AgentManager {
         }
         catch (err) {
             console.warn(`[AgentManager] replay: clearing bootstrap marker for task=${taskId} failed:`, err);
-            await this.markAwaitingHuman(agentId, 'bootstrap-marker-clear-failed', 'Prompt was replayed but clearing the in-flight bootstrap marker failed; held so recovery does ' +
-                'not roll back an already-running task. Verify the agent via web terminal, then Resume.', { expectedTaskId: taskId }).catch((holdErr) => {
+            await this.markAwaitingHuman(agentId, 'bootstrap-marker-clear-failed', `Clearing the in-flight bootstrap marker failed. ${DELIVERED_BOOTSTRAP_RUNBOOK}`, { expectedTaskId: taskId }).catch((holdErr) => {
                 console.warn(`[AgentManager] replay: hold after marker-clear failure for task=${taskId} failed:`, holdErr);
             });
             return;
@@ -8141,9 +8386,11 @@ export class AgentManager {
                     return {
                         ...withBinding,
                         status: 'awaiting_human',
+                        ...(latest.bootstrappingTaskId !== undefined ? { bootstrappingTaskId: latest.bootstrappingTaskId } : {}),
                         ...(latest.awaitingPhase !== undefined ? { awaitingPhase: latest.awaitingPhase } : {}),
                         ...(latest.awaitingReason !== undefined ? { awaitingReason: latest.awaitingReason } : {}),
                         ...(latest.awaitingSince !== undefined ? { awaitingSince: latest.awaitingSince } : {}),
+                        ...(latest.awaitingNonce !== undefined ? { awaitingNonce: latest.awaitingNonce } : {}),
                     };
                 });
                 if (state.taskId && !shouldReleaseBinding && !cancelHold) {
@@ -8786,6 +9033,24 @@ export class AgentManager {
             return dispatched;
         }
     }
+    async replayDevTaskForAdvance(task) {
+        const taskId = task.id;
+        if (!task.devAgentId)
+            throw new ApiError(409, `Task ${taskId} has no Dev participant`);
+        const entryBinding = await this.agentStore.get(task.devAgentId);
+        if (entryBinding?.taskId === taskId && entryBinding.status === 'awaiting_human'
+            && entryBinding.awaitingPhase && PROMPT_MAYBE_RUNNING_PHASES.has(entryBinding.awaitingPhase)) {
+            throw new ApiError(409, `Task ${taskId}: Prompt may still be running (${entryBinding.awaitingPhase}). Verify the outcome in the terminal, or cancel the task.`);
+        }
+        const replayed = await this.redispatchTaskPromptAfterReplRestart(task.devAgentId, taskId);
+        if (!replayed)
+            throw new ApiError(409, `Task ${taskId} changed or its Dev prompt could not be replayed`);
+        const binding = await this.agentStore.get(task.devAgentId);
+        if (binding?.taskId === taskId && binding.status === 'awaiting_human') {
+            throw new ApiError(409, `Task ${taskId} is blocked (${binding.awaitingPhase ?? 'awaiting_human'}): ${binding.awaitingReason ?? 'Inspect the task and its agent before retrying.'}`);
+        }
+        return (await this.taskStore.get(taskId)) ?? task;
+    }
     async advanceTask(taskId, opts = {}) {
         let task = await this.taskStore.get(taskId);
         if (!task)
@@ -8817,12 +9082,7 @@ export class AgentManager {
             throw new ApiError(409, 'Review cannot advance to Dev without a request-changes verdict');
         }
         else if (task.status === 'in_progress' || task.status === 'fixing') {
-            if (!task.devAgentId)
-                throw new ApiError(409, `Task ${taskId} has no Dev participant`);
-            const replayed = await this.redispatchTaskPromptAfterReplRestart(task.devAgentId, taskId);
-            if (!replayed)
-                throw new ApiError(409, `Task ${taskId} changed or its Dev prompt could not be replayed`);
-            updated = (await this.taskStore.get(taskId)) ?? task;
+            updated = await this.replayDevTaskForAdvance(task);
         }
         else if (task.status === 'approved') {
             if (!task.devAgentId)
@@ -8833,10 +9093,7 @@ export class AgentManager {
                 }
                 task = await this.restoreRevokedPostApprove(task);
             }
-            const replayed = await this.redispatchTaskPromptAfterReplRestart(task.devAgentId, taskId);
-            if (!replayed)
-                throw new ApiError(409, `Task ${taskId} changed or its post-approve prompt could not be replayed`);
-            updated = (await this.taskStore.get(taskId)) ?? task;
+            updated = await this.replayDevTaskForAdvance(task);
         }
         else {
             throw new ApiError(409, `Task ${taskId} cannot be advanced from ${task.status}`);