@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/agent-runtime/dispatch.js

@@ -12,9 +12,15 @@
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 import { ulid } from "ulid";
-import { initContext, loadAllTasks, loadMetaContext, } from "../parser/index.js";
-import { runInvocation } from "./invocation.js";
+import { initContext, loadAllTasks, loadMetaContext, areDependenciesMet, loadReviewRecords, } from "../parser/index.js";
+import { DEFAULT_KSPEC_CLI_PATH, runInvocation } from "./invocation.js";
+import { loadProjectConfig } from "../parser/config.js";
+import { SessionEventAccumulator } from "./session-event-accumulator.js";
+import { interpolateTemplate, rewriteSkillReferencesForAdapter, } from "./prompts.js";
 import { getAdapter } from "../agents/adapters.js";
+import { provisionDispatchWorkspace, DispatchWorkspaceError, getDispatchShadowMutationLockPath, markDispatchWorkspaceActive, markDispatchWorkspaceIdle, reconcileDispatchWorkspaceRegistry, getDispatchWorkspaceHealth, reconcileDispatchWorkspaceLifecycle, cleanupReviewerDispatchWorkspace, reconcileDispatchWorkspaceArtifacts, discoverWorkspaceForReviewOrFixCycle, } from "./workspace.js";
+import { ensureWorkspaceBootstrap, DispatchBootstrapError, } from "./bootstrap.js";
+import { getSessionCache } from "../sessions/cache.js";
 // ─── Simple Mutex ─────────────────────────────────────────────────────────────
 /**
  * A minimal promise-based mutex for serializing async operations.
@@ -79,22 +85,16 @@ const STATUS_TO_EVENT = {
 const STATUS_PRECEDENCE = {
     in_progress: 0,
     needs_work: 1,
-    pending: 2,
-    pending_review: 3,
+    pending_review: 2,
+    pending: 3,
     blocked: 4,
     completed: 5,
     cancelled: 6,
 };
-// ─── Prompt Helpers (exported for testing) ───────────────────────────────────
-/**
- * Interpolate {{variable}} placeholders in a prompt template.
- * Unresolved variables pass through unchanged.
- *
- * AC: @agent-dispatch-engine ac-16
- */
-export function interpolateTemplate(template, vars) {
-    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => vars[key] ?? match);
-}
+const CONTINUITY_STARVATION_THRESHOLD = 2;
+// ─── Prompt Helpers ──────────────────────────────────────────────────────────
+// AC: @agent-dispatch-engine ac-16 — re-exported from prompts.ts for backwards compat
+export { interpolateTemplate };
 /**
  * Human-readable trigger description for orientation context.
  */
@@ -112,6 +112,21 @@ function triggerDescription(trigger) {
             return `Trigger: ${trigger}`;
     }
 }
+function focusDescription(trigger, role) {
+    if (role === "reviewer") {
+        return "Review the submitted changes in this snapshot and decide whether the task should advance or return for fixes.";
+    }
+    if (trigger === "task.needs_work") {
+        return "Resume the canonical worker branch, address review findings, and move the task back toward review.";
+    }
+    if (trigger === "task.in_progress") {
+        return "Resume the existing canonical worker branch and continue the in-flight implementation.";
+    }
+    return "Work the assigned task in this mutable workspace and move it to the next appropriate state.";
+}
+function shortSha(commit) {
+    return commit ? commit.slice(0, 12) : "(unavailable)";
+}
 /**
  * Format recent notes for inclusion in dispatch prompts.
  * Takes last N notes, truncates each to maxLen characters, strips newlines.
@@ -128,19 +143,224 @@ function formatRecentNotes(notes, count = 3, maxLen = 200) {
     });
     return lines.join("\n");
 }
+class DispatchPromptError extends Error {
+    suggestion;
+    constructor(message, suggestion) {
+        super(message);
+        this.name = "DispatchPromptError";
+        this.suggestion = suggestion;
+    }
+}
+function resolveDispatchRole(trigger) {
+    return trigger === "task.pending_review" ? "reviewer" : "worker";
+}
+async function renderEntrypointForAdapter(entrypoint, adapterId, projectDir) {
+    const trimmed = entrypoint.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    const portableResolved = await rewriteSkillReferencesForAdapter(trimmed, projectDir, adapterId);
+    if (portableResolved !== trimmed) {
+        return portableResolved.trim();
+    }
+    switch (adapterId) {
+        case "codex-acp":
+            return trimmed
+                .replace(/^\/kspec:([a-z0-9][a-z0-9-]*)$/i, "$kspec-$1")
+                .replace(/^\/([a-z0-9][a-z0-9-]*)$/i, "$$$1");
+        case "claude-agent-acp":
+        case "claude-code-acp":
+            return trimmed
+                .replace(/^\$kspec-([a-z0-9][a-z0-9-]*)$/i, "/kspec:$1")
+                .replace(/^\$([a-z0-9][a-z0-9-]*)$/i, "/$1");
+        default:
+            return trimmed;
+    }
+}
+async function resolveRoleEntrypoint(role, adapterId, projectDir, config) {
+    const rawEntrypoint = role === "reviewer"
+        ? config.ralph.skills.pr_review
+        : config.ralph.skills.task_work;
+    const rendered = await renderEntrypointForAdapter(rawEntrypoint, adapterId, projectDir);
+    if (!rendered) {
+        throw new DispatchPromptError(`No valid ${role} entrypoint is configured for adapter "${adapterId}".`, `Set ralph.skills.${role === "reviewer" ? "pr_review" : "task_work"} in kspec.config.yaml to a non-empty workflow or skill entrypoint.`);
+    }
+    return rendered;
+}
+function buildPublicationInstructions(role, metadata) {
+    const lines = [
+        `Publication mode: \`${metadata.publicationMode}\``,
+        `Publish target: \`${metadata.mergeTargetBranch}\``,
+        `Canonical branch: \`${metadata.canonicalBranch}\``,
+    ];
+    if (metadata.publicationMode === "pull_request") {
+        if (role === "reviewer") {
+            lines.push(`Review and merge the PR that targets \`${metadata.mergeTargetBranch}\`; do not retarget it to a different base branch.`, "If you push fixes during review, re-run the required verification on the new HEAD before merging.");
+        }
+        else {
+            lines.push(`After submitting the task, create or update a PR from \`${metadata.canonicalBranch}\` into \`${metadata.mergeTargetBranch}\` using the recorded base branch as the PR target.`);
+        }
+        return lines;
+    }
+    if (metadata.publicationMode === "manual_merge") {
+        if (role === "reviewer") {
+            lines.push(`If review is clean, merge \`${metadata.canonicalBranch}\` back into \`${metadata.mergeTargetBranch}\` manually against the recorded base branch.`, `If conflicts appear, stop, run \`git merge --abort\`, and move the task to \`needs_work\` or \`blocked\` with a note describing the conflict. Do not guess at conflict resolution.`);
+        }
+        else {
+            lines.push(`Manual merge-back is recorded for this workspace. Submit the task for review; do not open a PR against \`${metadata.mergeTargetBranch}\`.`, `If you must prepare the merge path, keep the work on \`${metadata.canonicalBranch}\` and hand review a clean branch lineage back to \`${metadata.mergeTargetBranch}\`.`);
+        }
+        return lines;
+    }
+    throw new DispatchPromptError(`Workspace publication mode "${metadata.publicationMode}" is invalid.`, "Re-provision the dispatch workspace or repair its metadata so publicationMode is pull_request or manual_merge.");
+}
+async function buildRoleEntryContext(projectDir, adapterId, trigger, metadata) {
+    const role = resolveDispatchRole(trigger);
+    const { config } = await loadProjectConfig(projectDir, projectDir);
+    const entrypoint = await resolveRoleEntrypoint(role, adapterId, projectDir, config);
+    const publication = buildPublicationInstructions(role, metadata);
+    return [
+        "## Role Entry",
+        `Role: ${role}`,
+        `Workflow entrypoint: \`${entrypoint}\``,
+        `Start by executing the ${role === "reviewer" ? "review" : "work"} flow defined by \`${entrypoint}\`.`,
+        ...publication,
+    ].join("\n");
+}
+/**
+ * Find the examined commit from the most recent closed review for a task.
+ * Returns null when no prior examined commit exists.
+ *
+ * AC: @review-fix-cycle-diff ac-2 — find prior review's examined commit
+ */
+export function findPriorExaminedCommit(reviews, taskRef) {
+    const cleanRef = taskRef.startsWith("@") ? taskRef.slice(1) : taskRef;
+    const taskReviews = reviews.filter((r) => r.related_refs.includes(cleanRef)
+        || (r.subject.type === "task" && "ref" in r.subject && r.subject.ref === cleanRef));
+    const closedWithCommit = taskReviews
+        .filter((r) => r.lifecycle_state === "closed" && r.examined_commit)
+        .sort((a, b) => (b.created_at ?? "").localeCompare(a.created_at ?? ""));
+    if (closedWithCommit.length === 0)
+        return null;
+    return closedWithCommit[0].examined_commit;
+}
+/**
+ * Compute a git diff --stat between two commits. Returns null on any error.
+ *
+ * AC: @review-fix-cycle-diff ac-3 — graceful omission on unreachable commits
+ */
+export function computeDiffStat(fromCommit, toCommit, cwd) {
+    try {
+        const result = spawnSync("git", ["diff", "--stat", fromCommit, toCommit], { cwd, encoding: "utf-8", stdio: "pipe", timeout: 10_000 });
+        if (result.status !== 0)
+            return null;
+        const stat = result.stdout?.trim();
+        if (!stat)
+            return null;
+        return [
+            `Changes since prior review (${shortSha(fromCommit)}..${shortSha(toCommit)}):`,
+            stat,
+        ].join("\n");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute a diff summary between the prior review's examined commit and the
+ * current canonical branch head. Returns null when no prior examined commit
+ * exists or when the diff cannot be computed (unreachable commits, etc.).
+ *
+ * AC: @review-fix-cycle-diff ac-2 — diff summary for reviewer orientation
+ * AC: @review-fix-cycle-diff ac-3 — graceful omission on unreachable commits
+ */
+export async function getFixCycleDiffSummary(projectDir, taskRef, canonicalBranchHead, workspaceCwd) {
+    if (!canonicalBranchHead)
+        return null;
+    try {
+        const ctx = await initContext(projectDir);
+        const reviews = await loadReviewRecords(ctx);
+        const priorCommit = findPriorExaminedCommit(reviews, taskRef);
+        if (!priorCommit)
+            return null;
+        return computeDiffStat(priorCommit, canonicalBranchHead, workspaceCwd ?? projectDir);
+    }
+    catch {
+        // AC: @review-fix-cycle-diff ac-3 — graceful omission on any error
+        return null;
+    }
+}
 /**
  * Build orientation context block for a dispatch prompt.
  * Provides the agent with task title, trigger meaning, and relevant context.
  *
  * AC: @agent-dispatch-engine ac-13, ac-14, ac-15
  */
-export function buildOrientationContext(taskRef, trigger, task) {
+export function buildOrientationContext(taskRef, trigger, workspaceOrTask, taskOrMetadata, metadataOrRole, explicitRole, options) {
+    const usingProvisionedWorkspace = typeof workspaceOrTask === "object"
+        && workspaceOrTask !== null
+        && "cwd" in workspaceOrTask
+        && "metadata" in workspaceOrTask;
+    const role = explicitRole
+        ?? (usingProvisionedWorkspace
+            ? (trigger === "task.pending_review" ? "reviewer" : "worker")
+            : (metadataOrRole
+                ?? (trigger === "task.pending_review" ? "reviewer" : "worker")));
+    const workspace = usingProvisionedWorkspace
+        ? workspaceOrTask
+        : null;
+    const task = usingProvisionedWorkspace
+        ? taskOrMetadata
+        : workspaceOrTask;
+    const metadata = (usingProvisionedWorkspace
+        ? workspaceOrTask.metadata
+        : taskOrMetadata) ?? null;
     const title = task?.title ?? "(unavailable)";
+    const bootstrapRoleState = metadata?.bootstrap?.roleStates?.[role];
+    const workspacePath = workspace?.cwd
+        ?? (role === "reviewer" ? metadata?.reviewerWorktreeDir : metadata?.workerWorktreeDir)
+        ?? "(unavailable)";
+    const workspaceMode = role === "reviewer" ? "detached review snapshot" : "mutable worker branch";
+    const bootstrapSummary = !bootstrapRoleState
+        ? "not available"
+        : bootstrapRoleState.status === "succeeded"
+            ? role === "reviewer" && bootstrapRoleState.steps.length === 0
+                ? "reused worker bootstrap"
+                : "prepared"
+            : bootstrapRoleState.status === "failed"
+                ? `failed${bootstrapRoleState.failureMessage ? ` (${bootstrapRoleState.failureMessage})` : ""}`
+                : "not run";
+    const dependencyStatus = bootstrapRoleState && bootstrapRoleState.invalidationReasons.length > 0
+        ? bootstrapRoleState.invalidationReasons.join("; ")
+        : "satisfied";
+    const healthSummary = metadata?.healthStatus === "healthy"
+        ? "ready"
+        : metadata?.healthReason
+            ? `${metadata.healthStatus} (${metadata.healthReason})`
+            : (metadata?.healthStatus ?? "unknown");
+    const canonicalHeadContext = role === "reviewer"
+        ? `${shortSha(metadata?.canonicalBranchHead)} (snapshot under review)`
+        : `${shortSha(metadata?.canonicalBranchHead)} (canonical branch head to resume)`;
     const lines = [
         "## Task Context",
         `Task: ${taskRef} \u2014 "${title}"`,
-        `Trigger: ${triggerDescription(trigger)}`,
+        `Selection reason: ${triggerDescription(trigger)}`,
+        `Role: ${role}`,
+        `Focus: ${focusDescription(trigger, role)}`,
+        `Workspace (your working directory): ${workspacePath}`,
+        `Workspace mode: ${workspaceMode}`,
+        `Canonical branch: ${metadata?.canonicalBranch ?? "(unavailable)"}`,
+        `Integration target: ${metadata?.integrationTargetBranch ?? metadata?.mergeTargetBranch ?? "(unavailable)"}`,
+        `Canonical head: ${canonicalHeadContext}`,
+        `Bootstrap state: ${bootstrapSummary}`,
+        `Workspace health: ${healthSummary}`,
+        `Dependency status: ${dependencyStatus}`,
     ];
+    if (role === "reviewer") {
+        lines.push(`Prepared state: Detached reviewer snapshot at ${shortSha(metadata?.canonicalBranchHead)}. The mutable worker branch remains ${metadata?.canonicalBranch ?? "(unavailable)"}.`);
+    }
+    else {
+        lines.push(`Prepared state: Mutable worker worktree attached to ${metadata?.canonicalBranch ?? "(unavailable)"} under ${metadata?.worktreeRoot ?? "(unavailable)"}.`);
+    }
     // AC: @agent-dispatch-engine ac-14 - Include recent notes for fix cycles
     if (trigger === "task.needs_work" && task?.notes && task.notes.length > 0) {
         const noteText = formatRecentNotes(task.notes);
@@ -152,9 +372,35 @@ export function buildOrientationContext(taskRef, trigger, task) {
     if (trigger === "task.pending_review") {
         const url = task?.review_url ?? "Not provided \u2014 find PR via task notes or git log.";
         lines.push(`Review URL: ${url}`);
+        lines.push(`Cycle context: Review cycle on a detached snapshot. If changes are kicked back, the follow-up worker resumes ${metadata?.canonicalBranch ?? "(unavailable)"} and still publishes against ${metadata?.integrationTargetBranch ?? metadata?.mergeTargetBranch ?? "(unavailable)"}.`);
+        // AC: @review-fix-cycle-diff ac-2 — Include fix-cycle diff summary for reviewer
+        if (options?.fixCycleDiffSummary) {
+            lines.push("", "## Fix-Cycle Diff", options.fixCycleDiffSummary);
+        }
+    }
+    if (trigger === "task.needs_work") {
+        lines.push(`Cycle context: Fix cycle after review. You are resuming ${metadata?.canonicalBranch ?? "(unavailable)"}; publication still targets ${metadata?.integrationTargetBranch ?? metadata?.mergeTargetBranch ?? "(unavailable)"}.`);
     }
+    const publicationGuidance = metadata?.publicationMode === "pull_request"
+        ? `- Publish via PR: create or update a pull request from ${metadata.canonicalBranch} into ${metadata.integrationTargetBranch}.`
+        : `- Publish via manual merge: merge ${metadata?.canonicalBranch ?? "(unavailable)"} back into ${metadata?.integrationTargetBranch ?? metadata?.mergeTargetBranch ?? "(unavailable)"}; if conflicts occur, stop and escalate with the conflict details instead of improvising.`;
+    lines.push("", "Dispatch Branch Context:", `- Canonical branch: ${metadata?.canonicalBranch ?? "(unavailable)"}`, `- Integration target: ${metadata?.integrationTargetBranch ?? metadata?.mergeTargetBranch ?? "(unavailable)"} @ ${metadata?.integrationTargetCommit ?? metadata?.baseBranchPoint ?? "(unavailable)"}`, `- Publication mode: ${metadata?.publicationMode ?? "manual_merge"}`, role === "reviewer"
+        ? `- Snapshot under review: ${metadata?.canonicalBranchHead ?? "(unavailable)"}`
+        : `- Canonical head: ${metadata?.canonicalBranchHead ?? "(unavailable)"}`, publicationGuidance);
     return lines.join("\n");
 }
+function resolveCleanupStateForTaskChange(change) {
+    if (change.toStatus === "completed") {
+        return { integrationState: "merged", taskStatus: "completed" };
+    }
+    if (change.toStatus === "cancelled") {
+        return { integrationState: "abandoned", taskStatus: "cancelled" };
+    }
+    if (change.fromStatus === "completed" || change.fromStatus === "cancelled") {
+        return { integrationState: "reset", taskStatus: change.toStatus };
+    }
+    return null;
+}
 // ─── DispatchEngine ───────────────────────────────────────────────────────────
 /**
  * The core dispatch runtime.
@@ -172,9 +418,14 @@ export class DispatchEngine {
     specDir;
     cwd;
     dedupWindowMs;
+    reconcileIntervalMs;
+    /** AC: @per-task-dispatch-drain-coalescing ac-4 */
+    coalesceWindowMs;
     kspecCliPath;
     onInvocationEvent;
-    onTextChunk;
+    onSessionEvent;
+    /** Per-session text accumulator for newline-boundary streaming. */
+    accumulator = new SessionEventAccumulator();
     /** Queue of pending dispatch entries, per agent id */
     queues = new Map();
     /** Count of active (running) invocations per agent id */
@@ -193,16 +444,35 @@ export class DispatchEngine {
     invocationAbortControllers = new Set();
     /** Per-invocation tracking records for status display */
     activeInvocationDetails = new Map();
+    /** Task refs currently between queue removal and active tracking registration */
+    inFlightTaskKeys = new Set();
     /** Monotonic enqueue sequence for deterministic queue ordering */
     nextQueueSequence = 0;
+    /** Last task selected/completed, used as continuity affinity signal. */
+    recentTaskAffinityRef = null;
+    /** Timer handle for periodic reconciliation. AC: @agent-dispatch-engine ac-20 */
+    reconcileTimer = null;
+    /** All in-flight reconciliation promises so stop() can await every one. */
+    inFlightReconciles = new Set();
+    /** Per-task coalescing timers. AC: @per-task-dispatch-drain-coalescing ac-1 */
+    coalesceTimers = new Map();
+    /** Whether a drain is currently in progress. AC: @per-task-dispatch-drain-coalescing ac-8 */
+    drainInProgress = false;
+    /** Whether another drain was requested while one is already running. AC: @per-task-dispatch-drain-coalescing ac-8 */
+    drainPending = false;
     constructor(options) {
         this.projectDir = options.projectDir;
         this.specDir = options.specDir ?? path.join(options.projectDir, ".kspec");
         this.cwd = options.cwd ?? options.projectDir;
         this.dedupWindowMs = options.dedupWindowMs ?? 2000;
+        this.reconcileIntervalMs = (options.reconcileIntervalMs === null || options.reconcileIntervalMs === 0)
+            ? 0
+            : (options.reconcileIntervalMs ?? 60_000);
+        // AC: @per-task-dispatch-drain-coalescing ac-4
+        this.coalesceWindowMs = options.coalesceWindowMs ?? 5000;
         this.kspecCliPath = options.kspecCliPath;
         this.onInvocationEvent = options.onInvocationEvent;
-        this.onTextChunk = options.onTextChunk;
+        this.onSessionEvent = options.onSessionEvent;
     }
     // ─── Public API ─────────────────────────────────────────────────────────────
     /**
@@ -213,8 +483,36 @@ export class DispatchEngine {
      */
     async start() {
         this.running = true;
+        try {
+            const ctx = await initContext(this.projectDir);
+            const tasks = await loadAllTasks(ctx);
+            const taskStatusByRef = new Map(tasks.map((task) => [`@${task._ulid}`, task.status]));
+            await this.shadowMutex.runExclusive(async () => {
+                await reconcileDispatchWorkspaceRegistry(this.projectDir, taskStatusByRef);
+            });
+        }
+        catch (err) {
+            console.error("[dispatch] Workspace registry reconciliation error:", err);
+        }
+        await reconcileDispatchWorkspaceArtifacts(this.projectDir, {
+            activeTaskRefs: this._activeTaskRefs(),
+        });
         // AC: @agent-dispatch-engine ac-8 - Bootstrap: evaluate existing task states
         await this._bootstrap();
+        // AC: @agent-dispatch-engine ac-19, ac-20 - Start periodic reconciliation
+        if (this.reconcileIntervalMs > 0) {
+            this.reconcileTimer = setInterval(() => {
+                if (this.running) {
+                    const p = this._reconcile().catch((err) => {
+                        console.error("[dispatch] Reconciliation error:", err);
+                    }).finally(() => {
+                        this.inFlightReconciles.delete(p);
+                    });
+                    this.inFlightReconciles.add(p);
+                }
+            }, this.reconcileIntervalMs);
+            this.reconcileTimer.unref();
+        }
     }
     /**
      * Handle a task state change event from any source (file watcher or API).
@@ -229,21 +527,54 @@ export class DispatchEngine {
             return;
         }
         this._recordEvent(change);
+        const cleanupState = resolveCleanupStateForTaskChange(change);
+        if (cleanupState) {
+            try {
+                await this.shadowMutex.runExclusive(async () => {
+                    await reconcileDispatchWorkspaceLifecycle({
+                        projectDir: this.projectDir,
+                        taskRef: change.taskRef,
+                        task: change.task
+                            ? {
+                                title: change.task.title,
+                                slugs: change.task.slugs,
+                            }
+                            : undefined,
+                        cleanupState,
+                    });
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`[dispatch] Failed to reconcile workspace lifecycle for ${change.taskRef}: ${message}`);
+            }
+        }
         // AC: @agent-dispatch-engine ac-1 - Match against dispatch rules
         const agents = await this._loadAgents();
         const eventType = STATUS_TO_EVENT[change.toStatus];
         if (!eventType)
             return;
-        // Load task data for filter evaluation if not provided
+        // Load all tasks for filter evaluation (needed for dependency checks)
+        let allTasks;
         let taskData = change.task;
         if (!taskData && change.taskId) {
             try {
                 const ctx = await initContext(this.projectDir);
-                const tasks = await loadAllTasks(ctx);
-                taskData = tasks.find((t) => t._ulid === change.taskId);
+                allTasks = await loadAllTasks(ctx);
+                taskData = allTasks.find((t) => t._ulid === change.taskId);
+            }
+            catch {
+                // Can't load tasks, filter evaluation will be lenient
+            }
+        }
+        // Load allTasks for dependency checking even when task data was provided
+        if (!allTasks && taskData) {
+            try {
+                const ctx = await initContext(this.projectDir);
+                allTasks = await loadAllTasks(ctx);
             }
             catch {
-                // Can't load task, filter evaluation will be lenient
+                // Can't load tasks, dependency check will be skipped
             }
         }
         // Make loaded task available for prompt building (AC: @agent-dispatch-engine ac-13)
@@ -255,14 +586,22 @@ export class DispatchEngine {
                 if (rule.on !== eventType)
                     continue;
                 // AC: @agent-dispatch-engine ac-6 - Apply filters
-                if (!this._matchesFilter(change, rule, taskData))
+                if (!this._matchesFilter(change, rule, taskData, allTasks))
                     continue;
                 // AC: @agent-dispatch-engine ac-2 - Each matching agent queued independently
                 this._enqueue(agent, change);
             }
         }
-        // Drain queues after enqueuing
-        await this._drainQueues(agents);
+        // AC: @per-task-dispatch-drain-coalescing ac-1, ac-4, ac-6
+        // Schedule a per-task coalescing timer instead of draining immediately.
+        // If coalesceWindowMs is 0, drain immediately for backward compatibility.
+        // AC: @agent-dispatch-engine ac-27 — all drains go through _serializedDrain()
+        if (this.coalesceWindowMs <= 0) {
+            await this._serializedDrain();
+        }
+        else {
+            this._scheduleCoalescedDrain(change.taskId);
+        }
     }
     /**
      * Handle file watcher notification: diff previous vs current task states.
@@ -310,15 +649,39 @@ export class DispatchEngine {
      */
     async stop() {
         this.running = false;
+        // AC: @per-task-dispatch-drain-coalescing ac-5 - Cancel all pending coalescing timers
+        for (const timer of this.coalesceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.coalesceTimers.clear();
+        // AC: @agent-dispatch-engine ac-20 - Stop periodic reconciliation
+        if (this.reconcileTimer !== null) {
+            clearInterval(this.reconcileTimer);
+            this.reconcileTimer = null;
+        }
+        // Wait for ALL in-flight reconciliations to finish so none
+        // write files after stop() returns (prevents ENOTEMPTY in test teardown).
+        if (this.inFlightReconciles.size > 0) {
+            await Promise.allSettled(Array.from(this.inFlightReconciles));
+            this.inFlightReconciles.clear();
+        }
+        // Clear queues BEFORE awaiting invocations so completion handlers
+        // that call _drainQueues find nothing to spawn. This prevents
+        // second-generation invocations from being added to runningInvocations
+        // after our snapshot, eliminating the need for a while loop (which
+        // risks hanging indefinitely if an invocation never resolves).
+        this.queues.clear();
         // AC: @agent-dispatch-engine ac-11 - Send graceful cancel to all active invocations
         for (const controller of this.invocationAbortControllers) {
             controller.abort();
         }
-        // Wait for all running invocations to complete (or abort)
+        // Wait for all running invocations to complete (or abort).
+        // Safe as a single pass: queues are already cleared above, and
+        // _spawnInvocation guards with !this.running, so no new promises
+        // can be added to runningInvocations during this await.
         if (this.runningInvocations.size > 0) {
             await Promise.allSettled(Array.from(this.runningInvocations));
         }
-        this.queues.clear();
         this.activeCount.clear();
         this.recentEvents.clear();
         this.invocationAbortControllers.clear();
@@ -331,6 +694,9 @@ export class DispatchEngine {
     getShadowMutex() {
         return this.shadowMutex;
     }
+    getCwd() {
+        return this.cwd;
+    }
     /**
      * Returns current engine status info including per-invocation details.
      * AC: @cli-agent-commands ac-6
@@ -365,44 +731,148 @@ export class DispatchEngine {
      * AC: @agent-dispatch-engine ac-8
      */
     async _bootstrap() {
+        try {
+            const enqueued = await this._evaluateAllTasks({ skipIfActive: false });
+            if (enqueued > 0) {
+                // AC: @agent-dispatch-engine ac-27 — all drains go through _serializedDrain()
+                await this._serializedDrain();
+            }
+        }
+        catch (err) {
+            console.error("[dispatch] Bootstrap error:", err);
+        }
+    }
+    /**
+     * Periodic reconciliation: re-evaluate all task states against dispatch rules.
+     * Enqueues tasks that match but have no active or queued invocation.
+     * AC: @agent-dispatch-engine ac-19
+     */
+    async _reconcile() {
         try {
             const ctx = await initContext(this.projectDir);
             const tasks = await loadAllTasks(ctx);
-            const agents = await this._loadAgents();
-            const now = Date.now();
-            // Seed prevTaskStates so subsequent file watcher diffs work correctly
-            for (const task of tasks) {
-                this.prevTaskStates.set(task._ulid, task.status);
-            }
-            // Evaluate each task against each agent's dispatch rules
-            for (const task of tasks) {
-                const currentStatus = task.status;
-                const eventType = STATUS_TO_EVENT[currentStatus];
-                if (!eventType)
-                    continue;
-                for (const agent of agents) {
-                    for (const rule of (agent.dispatch ?? [])) {
-                        if (rule.on !== eventType)
-                            continue;
-                        const change = {
-                            taskId: task._ulid,
-                            taskRef: `@${task._ulid}`,
-                            fromStatus: currentStatus, // bootstrap: treated as "just entered"
-                            toStatus: currentStatus,
-                            timestamp: now,
-                            task,
-                        };
-                        if (!this._matchesFilter(change, rule, task))
-                            continue;
-                        this._enqueue(agent, change);
-                    }
+            const taskStatusByRef = new Map(tasks.map((task) => [`@${task._ulid}`, task.status]));
+            await this.shadowMutex.runExclusive(async () => {
+                await reconcileDispatchWorkspaceRegistry(this.projectDir, taskStatusByRef, this._activeRoleByTaskRef());
+            });
+        }
+        catch (err) {
+            console.error("[dispatch] Workspace registry reconciliation error:", err);
+        }
+        await reconcileDispatchWorkspaceArtifacts(this.projectDir, {
+            activeTaskRefs: this._activeTaskRefs(),
+        });
+        const enqueued = await this._evaluateAllTasks({ skipIfActive: true });
+        if (enqueued > 0) {
+            console.log(`[dispatch] Reconciliation enqueued ${enqueued} task(s)`);
+            // AC: @agent-dispatch-engine ac-27 — all drains go through _serializedDrain()
+            await this._serializedDrain();
+        }
+    }
+    /**
+     * Shared logic for bootstrap and reconciliation: load all tasks, seed
+     * prevTaskStates, and enqueue tasks matching agent dispatch rules.
+     *
+     * When skipIfActive is true (reconciliation), tasks with an existing
+     * active or queued invocation are skipped.
+     *
+     * AC: @agent-dispatch-engine ac-8, ac-19
+     */
+    async _evaluateAllTasks(opts) {
+        const ctx = await initContext(this.projectDir);
+        const tasks = await loadAllTasks(ctx);
+        const agents = await this._loadAgents();
+        const now = Date.now();
+        let enqueued = 0;
+        // Seed/update prevTaskStates so file watcher diffs work correctly
+        for (const task of tasks) {
+            this.prevTaskStates.set(task._ulid, task.status);
+        }
+        for (const task of tasks) {
+            const currentStatus = task.status;
+            const eventType = STATUS_TO_EVENT[currentStatus];
+            if (!eventType)
+                continue;
+            for (const agent of agents) {
+                for (const rule of (agent.dispatch ?? [])) {
+                    if (rule.on !== eventType)
+                        continue;
+                    const change = {
+                        taskId: task._ulid,
+                        taskRef: `@${task._ulid}`,
+                        fromStatus: currentStatus,
+                        toStatus: currentStatus,
+                        timestamp: now,
+                        task,
+                    };
+                    if (!this._matchesFilter(change, rule, task, tasks))
+                        continue;
+                    if (opts.skipIfActive && this._hasActiveOrQueuedInvocation(agent.id, task._ulid))
+                        continue;
+                    this._enqueue(agent, change);
+                    enqueued++;
                 }
             }
-            await this._drainQueues(agents);
         }
-        catch (err) {
-            console.error("[dispatch] Bootstrap error:", err);
+        return enqueued;
+    }
+    /**
+     * Check if an agent already has an active or queued invocation for a task.
+     * AC: @agent-dispatch-engine ac-19
+     */
+    _hasActiveOrQueuedInvocation(agentId, taskId) {
+        if (this.inFlightTaskKeys.has(`${agentId}:@${taskId}`)) {
+            return true;
+        }
+        // Check active invocations
+        for (const record of this.activeInvocationDetails.values()) {
+            if (record.agentId === agentId && record.taskRef === `@${taskId}`) {
+                return true;
+            }
+        }
+        // Check queued entries
+        const queue = this.queues.get(agentId) ?? [];
+        return queue.some((entry) => entry.change.taskId === taskId);
+    }
+    _activeRoleByTaskRef() {
+        const roles = new Map();
+        for (const record of this.activeInvocationDetails.values()) {
+            if (record.taskRef) {
+                roles.set(record.taskRef, record.role);
+            }
+        }
+        return roles;
+    }
+    _activeTaskRefs() {
+        const refs = new Set();
+        for (const record of this.activeInvocationDetails.values()) {
+            if (record.taskRef) {
+                refs.add(record.taskRef);
+            }
+        }
+        return refs;
+    }
+    /**
+     * Check whether any agent has an active or in-flight invocation for a task.
+     * Considers both registered active invocations (activeInvocationDetails) and
+     * tasks that are between queue removal and active registration (inFlightTaskKeys).
+     *
+     * AC: @agent-dispatch-engine ac-26
+     */
+    _hasActiveInvocationForTask(taskRef) {
+        // Check active invocations across all agents
+        for (const record of this.activeInvocationDetails.values()) {
+            if (record.taskRef === taskRef) {
+                return true;
+            }
+        }
+        // Check in-flight keys (format: "agentId:taskRef") across all agents
+        for (const key of this.inFlightTaskKeys) {
+            if (key.endsWith(`:${taskRef}`)) {
+                return true;
+            }
         }
+        return false;
     }
     /**
      * Load agent definitions from meta context.
@@ -419,19 +889,42 @@ export class DispatchEngine {
     }
     /**
      * Check if a state change matches a dispatch rule's filters.
+     * Base readiness (deps, blocked_by) is checked before consumer filters
+     * per @trait-task-readiness ac-composable.
+     *
      * AC: @agent-dispatch-engine ac-6
+     * AC: @agent-dispatch-engine ac-21
+     * AC: @trait-task-readiness ac-deps
+     * AC: @trait-task-readiness ac-not-blocked
+     * AC: @trait-task-readiness ac-composable
      */
-    _matchesFilter(change, rule, task) {
-        if (!rule.filter)
-            return true;
+    _matchesFilter(change, rule, task, allTasks) {
+        // AC: @agent-dispatch-engine ac-21 — default to automation: eligible for
+        // task.ready and task.needs_work when no filter is specified
+        const defaultsToEligible = rule.on === "task.ready" || rule.on === "task.needs_work";
         // We need the task to evaluate filters — if not provided, reject to avoid
         // enqueuing non-matching tasks (AC-6: all filters must match)
         if (!task)
+            return !rule.filter && !defaultsToEligible;
+        // Any unresolved blocker excludes the candidate from scheduling.
+        if ((task.blocked_by ?? []).length > 0) {
             return false;
-        const { filter } = rule;
+        }
+        // Any unresolved dependency excludes the candidate from scheduling.
+        if (allTasks && (task.depends_on ?? []).length > 0) {
+            if (!areDependenciesMet(task, allTasks)) {
+                return false;
+            }
+        }
+        if (!rule.filter && !defaultsToEligible)
+            return true;
+        // AC: @trait-task-readiness ac-composable — consumer filters applied after base readiness
+        const filter = rule.filter ?? {};
+        // Apply default automation filter for task.ready/task.needs_work
+        const effectiveAutomation = filter.automation ?? (defaultsToEligible ? "eligible" : undefined);
         // Automation filter
-        if (filter.automation !== undefined) {
-            if (task.automation !== filter.automation) {
+        if (effectiveAutomation !== undefined) {
+            if (task.automation !== effectiveAutomation) {
                 return false;
             }
         }
@@ -442,9 +935,11 @@ export class DispatchEngine {
                 return false;
             }
         }
-        // Priority filter
+        // Priority filter — threshold semantics: task priority at or above (numerically <=)
+        // AC: @ui-agent-dispatch ac-8
         if (filter.priority !== undefined) {
-            if (task.priority !== filter.priority) {
+            const taskPriority = task.priority;
+            if (taskPriority === undefined || taskPriority > filter.priority) {
                 return false;
             }
         }
@@ -497,6 +992,7 @@ export class DispatchEngine {
             nextRetryAt: 0,
             enqueuedAtMs: Date.now(),
             sequence: this.nextQueueSequence++,
+            starvationDeferrals: 0,
         };
         this._insertQueueEntry(queue, entry);
         this.queues.set(agent.id, queue);
@@ -514,90 +1010,320 @@ export class DispatchEngine {
         queue.splice(insertAt, 0, entry);
     }
     /**
-     * Compare queue entries by dispatch precedence, then by enqueue sequence.
+     * Compare queue entries by dispatch precedence, numeric task priority, then FIFO.
      * AC: @dispatch-in-progress-priority ac-1
      */
     _compareQueueEntries(a, b) {
         const statusDelta = STATUS_PRECEDENCE[a.change.toStatus] - STATUS_PRECEDENCE[b.change.toStatus];
         if (statusDelta !== 0)
             return statusDelta;
+        const priorityDelta = this._taskPriorityForEntry(a) - this._taskPriorityForEntry(b);
+        if (priorityDelta !== 0)
+            return priorityDelta;
         return a.sequence - b.sequence;
     }
-    /**
-     * Drain queues, spawning invocations up to each agent's max_concurrent limit.
-     * AC: @agent-dispatch-engine ac-3, ac-17
-     */
-    async _drainQueues(agents) {
-        // Prevent new invocation starts during/after shutdown.
-        if (!this.running)
+    _taskPriorityForEntry(entry) {
+        return entry.change.task?.priority ?? 3;
+    }
+    _hasContinuityAffinity(entry) {
+        if (!this.recentTaskAffinityRef)
+            return false;
+        return entry.change.taskRef === this.recentTaskAffinityRef;
+    }
+    _compareSchedulerCandidates(a, b) {
+        const statusDelta = STATUS_PRECEDENCE[a.entry.change.toStatus] - STATUS_PRECEDENCE[b.entry.change.toStatus];
+        if (statusDelta !== 0) {
+            return statusDelta;
+        }
+        const priorityDelta = this._taskPriorityForEntry(a.entry) - this._taskPriorityForEntry(b.entry);
+        if (priorityDelta !== 0) {
+            return priorityDelta;
+        }
+        const sameBand = STATUS_PRECEDENCE[a.entry.change.toStatus] === STATUS_PRECEDENCE[b.entry.change.toStatus];
+        const samePriority = this._taskPriorityForEntry(a.entry) === this._taskPriorityForEntry(b.entry);
+        if (sameBand && samePriority) {
+            const aAffinity = this._hasContinuityAffinity(a.entry);
+            const bAffinity = this._hasContinuityAffinity(b.entry);
+            if (aAffinity !== bAffinity) {
+                if (aAffinity && b.entry.starvationDeferrals < CONTINUITY_STARVATION_THRESHOLD) {
+                    return -1;
+                }
+                if (bAffinity && a.entry.starvationDeferrals < CONTINUITY_STARVATION_THRESHOLD) {
+                    return 1;
+                }
+            }
+        }
+        return a.entry.sequence - b.entry.sequence;
+    }
+    _recordContinuityDeferrals(selected, candidates) {
+        const selectedAffinity = this._hasContinuityAffinity(selected.entry);
+        if (!selectedAffinity) {
+            selected.entry.starvationDeferrals = 0;
             return;
-        // AC: @agent-dispatch-engine ac-17 - Load current task states once for staleness checks
-        let currentTaskStates;
-        try {
-            const ctx = await initContext(this.projectDir);
-            const tasks = await loadAllTasks(ctx);
-            currentTaskStates = new Map(tasks.map((t) => [t._ulid, t.status]));
         }
-        catch {
-            // If we can't load tasks, skip staleness checks (best effort)
+        const selectedBand = STATUS_PRECEDENCE[selected.entry.change.toStatus];
+        const selectedPriority = this._taskPriorityForEntry(selected.entry);
+        for (const candidate of candidates) {
+            if (candidate.entry === selected.entry)
+                continue;
+            const sameBand = STATUS_PRECEDENCE[candidate.entry.change.toStatus] === selectedBand;
+            const samePriority = this._taskPriorityForEntry(candidate.entry) === selectedPriority;
+            if (!sameBand || !samePriority)
+                continue;
+            if (this._hasContinuityAffinity(candidate.entry))
+                continue;
+            candidate.entry.starvationDeferrals += 1;
         }
+        selected.entry.starvationDeferrals = 0;
+    }
+    // AC: @review-and-fix-cycle-workspace-discovery-before-discard ac-1, ac-2, ac-3, ac-4
+    async _workspaceCandidateHealth(entry) {
+        const role = entry.change.toStatus === "pending_review" ? "reviewer" : "worker";
+        const taskInfo = entry.change.task
+            ? {
+                title: entry.change.task.title,
+                slugs: entry.change.task.slugs,
+            }
+            : undefined;
+        const health = await getDispatchWorkspaceHealth({
+            projectDir: this.projectDir,
+            taskRef: entry.change.taskRef,
+            task: taskInfo,
+            role,
+        });
+        // AC: @adopt-existing-task-branch-lineage ac-1 — when workspace doesn't exist
+        // but the task has submission linkage, allow provisioning to adopt the branch.
+        const hasSubmissionLinkage = Boolean(entry.change.task?.submission_linkage?.branch);
+        const eligible = !health.exists
+            ? (entry.change.toStatus !== "in_progress" && entry.change.toStatus !== "pending_review") || hasSubmissionLinkage
+            : health.healthy;
+        // For pending_review and needs_work tasks, attempt workspace discovery
+        // before discarding the queue entry as missing or ineligible.
+        if (!eligible &&
+            (entry.change.toStatus === "pending_review" || entry.change.toStatus === "needs_work")) {
+            const discoveryResult = await discoverWorkspaceForReviewOrFixCycle({
+                projectDir: this.projectDir,
+                taskRef: entry.change.taskRef,
+                role,
+                task: entry.change.task
+                    ? {
+                        title: entry.change.task.title,
+                        slugs: entry.change.task.slugs,
+                        submission_linkage: entry.change.task.submission_linkage ?? undefined,
+                        review_url: entry.change.task.review_url,
+                    }
+                    : undefined,
+            });
+            // Emit diagnostics for failed discovery (AC-3) or conflicting signals (AC-4).
+            for (const diagnostic of discoveryResult.diagnostics) {
+                console.log(`[dispatch] Workspace discovery diagnostic for ${diagnostic.taskRef}: [${diagnostic.code}] ${diagnostic.message}`);
+                console.log(`[dispatch]   Suggestion: ${diagnostic.suggestion}`);
+            }
+            if (discoveryResult.recovered) {
+                // AC-2: Recovery succeeded — re-evaluate eligibility with recovered workspace.
+                return {
+                    eligible: true,
+                    exists: discoveryResult.health.exists,
+                    reason: discoveryResult.health.reason,
+                };
+            }
+            // Discovery failed — return ineligible with diagnostic-enriched reason.
+            const diagnosticReason = discoveryResult.diagnostics[0]?.code
+                ?? (health.exists ? health.reason : "workspace-missing-no-recovery");
+            return {
+                eligible: false,
+                exists: health.exists || discoveryResult.health.exists,
+                reason: diagnosticReason,
+            };
+        }
+        return {
+            eligible,
+            exists: health.exists,
+            reason: health.reason,
+        };
+    }
+    async _pruneIneligibleQueueEntries(agents, currentTasks, currentTaskStates) {
+        const tasksById = new Map((currentTasks ?? []).map((task) => [task._ulid, task]));
         for (const agent of agents) {
-            const maxConcurrent = agent.concurrency?.max_concurrent ?? 1;
-            const active = this.activeCount.get(agent.id) ?? 0;
             const queue = this.queues.get(agent.id) ?? [];
-            // AC: @agent-dispatch-engine ac-17 - Discard stale entries before spawning.
-            // Only discard when we have positive evidence the task moved: either the task
-            // exists on disk with a different status, or the task was previously tracked
-            // (in prevTaskStates) but is no longer found (deleted).
-            if (currentTaskStates) {
-                const before = queue.length;
-                for (let i = queue.length - 1; i >= 0; i--) {
-                    const entry = queue[i];
-                    const currentStatus = currentTaskStates.get(entry.change.taskId);
-                    const expectedEvent = STATUS_TO_EVENT[entry.change.toStatus];
-                    if (!expectedEvent)
-                        continue; // No event mapping — skip check
+            const before = queue.length;
+            const discardedDetails = [];
+            for (let i = queue.length - 1; i >= 0; i--) {
+                const entry = queue[i];
+                const currentStatus = currentTaskStates?.get(entry.change.taskId);
+                const expectedEvent = STATUS_TO_EVENT[entry.change.toStatus];
+                if (expectedEvent) {
                     if (currentStatus === undefined) {
-                        // Task not on disk — only discard if we previously knew about it
-                        // (it was deleted). Tasks from pure handleStateChange events without
-                        // on-disk presence should still be processed.
                         if (this.prevTaskStates.has(entry.change.taskId)) {
+                            discardedDetails.push(`${entry.change.taskRef} for agent "${agent.id}": task no longer exists on disk`);
                             queue.splice(i, 1);
+                            continue;
                         }
                     }
                     else {
                         const currentEvent = STATUS_TO_EVENT[currentStatus];
                         if (currentEvent !== expectedEvent) {
+                            discardedDetails.push(`${entry.change.taskRef} for agent "${agent.id}": task state changed to ${currentStatus}`);
                             queue.splice(i, 1);
+                            continue;
                         }
                     }
                 }
-                if (before > queue.length) {
-                    console.log(`[dispatch] Discarded ${before - queue.length} stale queue entries for agent "${agent.id}"`);
+                const currentTask = tasksById.get(entry.change.taskId);
+                if (currentTask) {
+                    entry.change.task = currentTask;
+                    if (currentTask.blocked_by.length > 0) {
+                        discardedDetails.push(`${entry.change.taskRef} for agent "${agent.id}": task is blocked by ${currentTask.blocked_by.join(", ")}`);
+                        queue.splice(i, 1);
+                        continue;
+                    }
+                    if (currentTask.depends_on.length > 0 &&
+                        currentTasks &&
+                        !areDependenciesMet(currentTask, currentTasks)) {
+                        discardedDetails.push(`${entry.change.taskRef} for agent "${agent.id}": dependencies are no longer satisfied`);
+                        queue.splice(i, 1);
+                        continue;
+                    }
                 }
-            }
-            let slots = maxConcurrent - active;
-            while (slots > 0 && queue.length > 0) {
-                const now = Date.now();
-                const nextReadyIndex = queue.findIndex((entry) => entry.nextRetryAt <= now);
-                if (nextReadyIndex === -1) {
-                    break;
+                const workspaceHealth = await this._workspaceCandidateHealth(entry);
+                if (!workspaceHealth.eligible) {
+                    discardedDetails.push(`${entry.change.taskRef} for agent "${agent.id}": workspace ${workspaceHealth.exists ? "is unhealthy" : "is missing"}${workspaceHealth.reason ? ` (${workspaceHealth.reason})` : ""}`);
+                    queue.splice(i, 1);
                 }
-                const [entry] = queue.splice(nextReadyIndex, 1);
-                const spawned = this._spawnInvocation(agent, entry);
-                if (spawned)
-                    slots--;
+            }
+            for (const detail of discardedDetails) {
+                console.log(`[dispatch] Discarded queue entry ${detail}`);
+            }
+            if (before > queue.length) {
+                console.log(`[dispatch] Discarded ${before - queue.length} ineligible queue entr${before - queue.length === 1 ? "y" : "ies"} for agent "${agent.id}"`);
             }
             this.queues.set(agent.id, queue);
         }
     }
+    _selectNextCandidate(agents) {
+        const now = Date.now();
+        const candidates = [];
+        for (const agent of agents) {
+            const maxConcurrent = agent.concurrency?.max_concurrent ?? 1;
+            const active = this.activeCount.get(agent.id) ?? 0;
+            if (active >= maxConcurrent)
+                continue;
+            const queue = this.queues.get(agent.id) ?? [];
+            for (let index = 0; index < queue.length; index++) {
+                const entry = queue[index];
+                if (entry.nextRetryAt > now)
+                    continue;
+                // AC: @agent-dispatch-engine ac-26 — cross-agent task exclusivity:
+                // skip candidates whose task already has an active invocation by any
+                // agent. The entry stays queued and will be picked up after the active
+                // invocation completes (post-invocation drain via ac-24).
+                if (this._hasActiveInvocationForTask(entry.change.taskRef))
+                    continue;
+                candidates.push({ agent, queue, queueIndex: index, entry });
+            }
+        }
+        if (candidates.length === 0) {
+            return null;
+        }
+        candidates.sort((a, b) => this._compareSchedulerCandidates(a, b));
+        const selected = candidates[0];
+        this._recordContinuityDeferrals(selected, candidates);
+        return selected;
+    }
+    /**
+     * Schedule a per-task coalesced drain. If a timer already exists for this
+     * task, it is cleared and reset to the full coalescing window.
+     *
+     * AC: @per-task-dispatch-drain-coalescing ac-1, ac-3
+     */
+    _scheduleCoalescedDrain(taskId) {
+        // Clear any existing timer for this task (reset window)
+        const existing = this.coalesceTimers.get(taskId);
+        if (existing !== undefined) {
+            clearTimeout(existing);
+        }
+        const timer = setTimeout(() => {
+            this.coalesceTimers.delete(taskId);
+            if (!this.running)
+                return;
+            // AC: @per-task-dispatch-drain-coalescing ac-8 — serialize drain execution
+            this._serializedDrain().catch((err) => {
+                console.error("[dispatch] Coalesced drain error:", err);
+            });
+        }, this.coalesceWindowMs);
+        // Unref so it doesn't keep the process alive
+        if (timer && typeof timer === "object" && "unref" in timer) {
+            timer.unref();
+        }
+        this.coalesceTimers.set(taskId, timer);
+    }
+    /**
+     * Serialize drain execution: if a drain is already running, mark that another
+     * drain is pending and return. When the current drain finishes, it runs the
+     * follow-up drain. This prevents concurrent _drainQueues() calls from
+     * racing on queue state.
+     *
+     * AC: @per-task-dispatch-drain-coalescing ac-8
+     */
+    async _serializedDrain() {
+        if (this.drainInProgress) {
+            this.drainPending = true;
+            return;
+        }
+        this.drainInProgress = true;
+        try {
+            const agents = await this._loadAgents();
+            await this._drainQueues(agents);
+        }
+        finally {
+            this.drainInProgress = false;
+        }
+        // If another drain was requested while we were running, do one follow-up.
+        if (this.drainPending) {
+            this.drainPending = false;
+            await this._serializedDrain();
+        }
+    }
+    /**
+     * Drain queues, spawning invocations up to each agent's max_concurrent limit.
+     * AC: @agent-dispatch-engine ac-3, ac-17
+     */
+    async _drainQueues(agents) {
+        // Prevent new invocation starts during/after shutdown.
+        if (!this.running)
+            return;
+        // AC: @agent-dispatch-engine ac-17 - Load current tasks once for staleness + readiness checks
+        let currentTasks;
+        let currentTaskStates;
+        try {
+            const ctx = await initContext(this.projectDir);
+            currentTasks = await loadAllTasks(ctx);
+            currentTaskStates = new Map(currentTasks.map((t) => [t._ulid, t.status]));
+        }
+        catch {
+            // If we can't load tasks, skip staleness checks (best effort)
+        }
+        await this._pruneIneligibleQueueEntries(agents, currentTasks, currentTaskStates);
+        while (this.running) {
+            const candidate = this._selectNextCandidate(agents);
+            if (!candidate) {
+                break;
+            }
+            const [entry] = candidate.queue.splice(candidate.queueIndex, 1);
+            this.queues.set(candidate.agent.id, candidate.queue);
+            const spawned = await this._spawnInvocation(candidate.agent, entry);
+            if (!spawned) {
+                continue;
+            }
+        }
+    }
     /**
      * Build dispatch-mode prompt guardrails to keep autonomous agents from
      * stopping with handoff text instead of performing required actions.
      *
      * AC: @agent-dispatch-engine ac-13, ac-14, ac-15, ac-16
      */
-    _buildDispatchPrompt(agent, change) {
+    async _buildDispatchPrompt(agent, change, workspace) {
         const trigger = (STATUS_TO_EVENT[change.toStatus] ?? "task.ready");
         const taskRef = change.taskRef;
         // AC: @agent-dispatch-engine ac-16 - Interpolate prompt_template variables
@@ -609,8 +1335,13 @@ export class DispatchEngine {
         };
         const rawTemplate = agent.prompt_template ?? `Work on task ${taskRef}`;
         const basePrompt = interpolateTemplate(rawTemplate, templateVars);
-        // AC: @agent-dispatch-engine ac-13 - Orientation context
-        const orientation = buildOrientationContext(taskRef, trigger, change.task);
+        // AC: @review-fix-cycle-diff ac-2 — Compute fix-cycle diff for reviewer orientation
+        let fixCycleDiffSummary = null;
+        if (trigger === "task.pending_review") {
+            fixCycleDiffSummary = await getFixCycleDiffSummary(this.projectDir, taskRef, workspace.metadata.canonicalBranchHead, workspace.cwd);
+        }
+        const orientation = buildOrientationContext(taskRef, trigger, workspace, change.task, undefined, undefined, { fixCycleDiffSummary });
+        const roleEntry = await buildRoleEntryContext(this.projectDir, agent.adapter ?? "claude-agent-acp", trigger, workspace.metadata);
         const autonomousPreamble = [
             "AUTONOMOUS DISPATCH MODE (no interactive user is available).",
             "- Do not ask for confirmation, approval, or next-step handoff.",
@@ -618,6 +1349,7 @@ export class DispatchEngine {
             "- Do not end your turn with a recommendations-only summary. Perform the next required action yourself.",
             "- Do not end your turn until the expected task transition is complete, or you have explicitly blocked the task with `kspec task block <task> --reason \"...\"`.",
             "- If you find an open PR/branch from a different task, create or switch to a dedicated branch for this task before committing to avoid PR conflation.",
+            `- CRITICAL: Your working directory is your assigned workspace (${workspace.cwd}). Run ALL commands (tests, builds, git, kspec, etc.) from this directory. Do NOT cd to the project root or any other directory. The workspace is a full git worktree with the correct branch and project configuration.`,
         ];
         const triggerSpecific = trigger === "task.pending_review"
             ? [
@@ -632,160 +1364,432 @@ export class DispatchEngine {
                 `- Perform the required commands to move ${taskRef} to the next appropriate state in this same invocation.`,
                 "- If your workflow includes git or PR steps, execute them directly instead of deferring to a human.",
             ];
-        return `${basePrompt}\n\n${orientation}\n\n${autonomousPreamble.join("\n")}\n\n${triggerSpecific.join("\n")}`;
+        return `${basePrompt}\n\n${orientation}\n\n${roleEntry}\n\n${autonomousPreamble.join("\n")}\n\n${triggerSpecific.join("\n")}`;
+    }
+    _runKspecCommand(args) {
+        const result = spawnSync(process.execPath, [this.kspecCliPath ?? DEFAULT_KSPEC_CLI_PATH, ...args], {
+            cwd: this.cwd,
+            encoding: "utf-8",
+            stdio: "pipe",
+        });
+        return {
+            status: result.status,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+        };
+    }
+    _taskCommandError(args, result) {
+        const exitDetail = result.status === null ? "terminated by signal" : `exited with status ${result.status}`;
+        const details = [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join(" ");
+        return new Error(`Failed to run \`kspec ${args.join(" ")}\`: ${exitDetail}${details ? `. ${details}` : ""}`);
+    }
+    _addTaskNote(taskRef, note) {
+        const args = ["task", "note", taskRef, note];
+        const result = this._runKspecCommand(args);
+        if (result.status !== 0) {
+            console.warn(`[dispatch] Failed to add task note for ${taskRef}: ${this._taskCommandError(args, result).message}`);
+        }
+    }
+    _blockTask(taskRef, reason) {
+        const args = ["task", "block", taskRef, "--reason", reason];
+        const result = this._runKspecCommand(args);
+        if (result.status !== 0) {
+            throw this._taskCommandError(args, result);
+        }
     }
     /**
      * Spawn a single invocation for a queue entry.
      * Returns true if an invocation was actually started, false if skipped.
      * AC: @agent-dispatch-engine ac-9, ac-10, ac-11, ac-12
      */
-    _spawnInvocation(agent, entry) {
+    async _spawnInvocation(agent, entry) {
+        // Bail out during shutdown — don't provision workspaces or add to
+        // runningInvocations for invocations that will never complete.
+        if (!this.running)
+            return false;
         const agentId = agent.id;
-        // Increment active count
-        this.activeCount.set(agentId, (this.activeCount.get(agentId) ?? 0) + 1);
-        // AC: @agent-dispatch-engine ac-10 - Check adapter resolvability before spawn
-        const adapterId = agent.adapter ?? "claude-agent-acp";
-        const adapter = getAdapter(adapterId);
-        if (!adapter) {
-            console.error(`[dispatch] Cannot resolve adapter "${adapterId}" for agent "${agentId}". Skipping invocation.`);
-            // Decrement active count since we're not actually running
-            const currentActive = this.activeCount.get(agentId) ?? 1;
-            this.activeCount.set(agentId, Math.max(0, currentActive - 1));
-            // AC: @agent-dispatch-engine ac-10 - Add task note for unresolvable adapter
-            if (this.kspecCliPath) {
-                spawnSync(process.execPath, [
-                    this.kspecCliPath,
-                    "task", "note", entry.change.taskRef,
-                    `[AGENT-SKIP] Cannot resolve adapter "${adapterId}" for agent "${agentId}". Invocation skipped.`,
-                ], { cwd: this.cwd });
+        const inFlightKey = `${agentId}:${entry.change.taskRef}`;
+        this.inFlightTaskKeys.add(inFlightKey);
+        let invocationRegistered = false;
+        let workspace;
+        const role = entry.change.toStatus === "pending_review" ? "reviewer" : "worker";
+        try {
+            try {
+                workspace = await provisionDispatchWorkspace({
+                    projectDir: this.projectDir,
+                    taskRef: entry.change.taskRef,
+                    role,
+                    cleanupState: {
+                        taskStatus: entry.change.task?.status ?? entry.change.toStatus,
+                    },
+                    task: entry.change.task
+                        ? {
+                            title: entry.change.task.title,
+                            slugs: entry.change.task.slugs,
+                        }
+                        : undefined,
+                    // AC: @adopt-existing-task-branch-lineage ac-1, ac-2, ac-4
+                    // Pass submission linkage so provisioning can adopt an existing branch
+                    // when no workspace record exists for review/fix-cycle tasks.
+                    submissionLinkage: entry.change.task?.submission_linkage ?? undefined,
+                    taskStatus: entry.change.task?.status ?? entry.change.toStatus,
+                });
             }
-            return false;
-        }
-        // AC: @agent-dispatch-engine ac-11 - Create abort controller for graceful cancellation
-        const abortController = new AbortController();
-        this.invocationAbortControllers.add(abortController);
-        // AC: @cli-agent-commands ac-6 - Pre-assign session ID for status tracking
-        const preSessionId = ulid();
-        const invocationId = ulid();
-        const trackingRecord = {
-            invocationId,
-            sessionId: preSessionId,
-            agentId,
-            agentName: agent.name,
-            taskRef: entry.change.taskRef,
-            startedAtMs: Date.now(),
-        };
-        this.activeInvocationDetails.set(invocationId, trackingRecord);
-        // AC: @daemon-agent-dispatch ac-3, ac-4 - Emit started event
-        this.onInvocationEvent?.({
-            type: "started",
-            session_id: preSessionId,
-            agent_id: agentId,
-            task_id: entry.change.taskRef,
-            status: "started",
-            timestamp: Date.now(),
-        });
-        // AC: @cli-agent-commands ac-13, @daemon-agent-dispatch ac-8 - stream text chunks to watchers
-        const taskId = entry.change.taskRef ?? null;
-        const onUpdate = this.onTextChunk
-            ? (update) => {
-                if (update.sessionUpdate === "agent_message_chunk" &&
-                    update.content.type === "text") {
-                    this.onTextChunk(preSessionId, agentId, taskId, update.content.text);
-                    return;
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                const guidance = err instanceof DispatchWorkspaceError ? err.suggestion : "Inspect dispatch workspace configuration and git worktree state.";
+                console.error(`[dispatch] Failed to provision workspace for ${entry.change.taskRef}: ${message}`);
+                this._addTaskNote(entry.change.taskRef, `[DISPATCH-WORKSPACE] ${message} Suggested action: ${guidance}`);
+                this._blockTask(entry.change.taskRef, `Dispatch workspace provisioning failed: ${message}. Suggested action: ${guidance}`);
+                return false;
+            }
+            const dispatchEnv = {
+                KSPEC_DISPATCH_BASE_BRANCH: workspace.metadata.baseBranch,
+                KSPEC_DISPATCH_MERGE_TARGET: workspace.metadata.mergeTargetBranch,
+                KSPEC_DISPATCH_CANONICAL_BRANCH: workspace.metadata.canonicalBranch,
+                KSPEC_DISPATCH_WORKTREE_ROOT: workspace.metadata.worktreeRoot,
+                KSPEC_DISPATCH_WORKSPACE_FILE: workspace.metadataPath,
+            };
+            try {
+                const bootstrap = await ensureWorkspaceBootstrap({
+                    projectDir: this.projectDir,
+                    workspaceDir: workspace.cwd,
+                    metadataPath: workspace.metadataPath,
+                    metadata: workspace.metadata,
+                    role,
+                    agent,
+                    env: dispatchEnv,
+                });
+                workspace = {
+                    ...workspace,
+                    metadata: bootstrap.metadata,
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                const guidance = err instanceof DispatchBootstrapError
+                    ? err.suggestion
+                    : "Inspect dispatch bootstrap configuration, dependency prerequisites, and workspace health.";
+                console.error(`[dispatch] Failed to bootstrap workspace for ${entry.change.taskRef}: ${message}`);
+                if (this.kspecCliPath) {
+                    spawnSync(process.execPath, [
+                        this.kspecCliPath,
+                        "task", "note", entry.change.taskRef,
+                        `[DISPATCH-BOOTSTRAP] ${message} Suggested action: ${guidance}`,
+                    ], { cwd: this.cwd });
+                    spawnSync(process.execPath, [
+                        this.kspecCliPath,
+                        "task", "block", entry.change.taskRef,
+                        "--reason", `Dispatch bootstrap failed: ${message}`,
+                    ], { cwd: this.cwd });
                 }
-                // Non-text updates (especially tool events) delimit logical message runs.
-                // Emit an empty sentinel so watch renderers can end the current line
-                // without needing to infer boundaries from prose punctuation.
-                this.onTextChunk(preSessionId, agentId, taskId, "");
+                return false;
             }
-            : undefined;
-        const options = {
-            agent,
-            specDir: this.specDir,
-            cwd: this.cwd,
-            taskRef: entry.change.taskRef,
-            prompt: this._buildDispatchPrompt(agent, entry.change),
-            trigger: (STATUS_TO_EVENT[entry.change.toStatus] ?? "task.ready"),
-            kspecCliPath: this.kspecCliPath,
-            abortSignal: abortController.signal,
-            sessionId: preSessionId,
-            onUpdate,
-        };
-        // AC: @agent-dispatch-engine ac-12 - Wrap invocation in shadow mutex
-        const invocationPromise = this.shadowMutex
-            .runExclusive(async () => {
-            // AC: @agent-dispatch-engine ac-9 - Retry on transient errors
+            let prompt;
             try {
-                await runInvocation(options);
-                // Reset retry count on success
-                entry.retryCount = 0;
-                // AC: @daemon-agent-dispatch ac-3, ac-4 - Emit completed event
+                prompt = await this._buildDispatchPrompt(agent, entry.change, workspace);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                const guidance = err instanceof DispatchPromptError
+                    ? err.suggestion
+                    : "Inspect dispatch role-entry configuration and workspace metadata.";
+                console.error(`[dispatch] Failed to build prompt for ${entry.change.taskRef}: ${message}`);
+                if (this.kspecCliPath) {
+                    spawnSync(process.execPath, [
+                        this.kspecCliPath,
+                        "task", "note", entry.change.taskRef,
+                        `[DISPATCH-PROMPT] ${message} Suggested action: ${guidance}`,
+                    ], { cwd: this.cwd });
+                }
+                return false;
+            }
+            // Increment active count
+            this.activeCount.set(agentId, (this.activeCount.get(agentId) ?? 0) + 1);
+            // AC: @agent-dispatch-engine ac-10 - Check adapter resolvability before spawn
+            const adapterId = agent.adapter ?? "claude-agent-acp";
+            const adapter = getAdapter(adapterId);
+            if (!adapter) {
+                console.error(`[dispatch] Cannot resolve adapter "${adapterId}" for agent "${agentId}". Skipping invocation.`);
+                // Decrement active count since we're not actually running
+                const currentActive = this.activeCount.get(agentId) ?? 1;
+                this.activeCount.set(agentId, Math.max(0, currentActive - 1));
+                // AC: @agent-dispatch-engine ac-10 - Add task note for unresolvable adapter
+                if (this.kspecCliPath) {
+                    spawnSync(process.execPath, [
+                        this.kspecCliPath,
+                        "task", "note", entry.change.taskRef,
+                        `[AGENT-SKIP] Cannot resolve adapter "${adapterId}" for agent "${agentId}". Invocation skipped.`,
+                    ], { cwd: this.cwd });
+                }
+                return false;
+            }
+            // AC: @agent-dispatch-engine ac-11 - Create abort controller for graceful cancellation
+            const abortController = new AbortController();
+            this.invocationAbortControllers.add(abortController);
+            // AC: @cli-agent-commands ac-6 - Pre-assign session ID for status tracking
+            const preSessionId = ulid();
+            const invocationId = ulid();
+            const trackingRecord = {
+                invocationId,
+                sessionId: preSessionId,
+                agentId,
+                agentName: agent.name,
+                taskRef: entry.change.taskRef,
+                role,
+                startedAtMs: Date.now(),
+            };
+            this.activeInvocationDetails.set(invocationId, trackingRecord);
+            this.recentTaskAffinityRef = entry.change.taskRef;
+            let startedEventEmitted = false;
+            const emitStartedEvent = () => {
+                if (startedEventEmitted)
+                    return;
+                startedEventEmitted = true;
                 this.onInvocationEvent?.({
-                    type: "completed",
+                    type: "started",
                     session_id: preSessionId,
                     agent_id: agentId,
                     task_id: entry.change.taskRef,
-                    status: "completed",
+                    task_title: entry.change.task?.title ?? null,
+                    status: "started",
                     timestamp: Date.now(),
                 });
-            }
-            catch (err) {
-                const retryLimit = agent.budget?.max_tasks ?? 3;
-                if (entry.retryCount < retryLimit) {
-                    entry.retryCount++;
-                    const backoffMs = Math.min(1000 * Math.pow(2, entry.retryCount - 1), 30_000);
-                    entry.nextRetryAt = Date.now() + backoffMs;
-                    console.warn(`[dispatch] Invocation for agent "${agentId}" failed (attempt ${entry.retryCount}/${retryLimit}), retrying in ${backoffMs}ms`, err);
-                    // Re-enqueue for retry while preserving status precedence ordering.
-                    const queue = this.queues.get(agentId) ?? [];
-                    this._insertQueueEntry(queue, entry);
-                    this.queues.set(agentId, queue);
-                    // AC: @agent-dispatch-engine ac-9 - Schedule wake-up to drain retry
-                    setTimeout(() => {
-                        if (this.running) {
-                            this._loadAgents()
-                                .then((agents) => this._drainQueues(agents))
-                                .catch(() => { });
-                        }
-                    }, backoffMs);
+            };
+            // AC: @session-event-broadcast ac-newline-streaming, ac-boundary-flush, ac-per-session-state
+            // AC: @cli-agent-commands ac-13, @daemon-agent-dispatch ac-8 - stream session events to watchers
+            const taskId = entry.change.taskRef ?? null;
+            const taskTitle = entry.change.task?.title ?? null;
+            const sessionCtx = {
+                sessionId: preSessionId,
+                agentId,
+                taskId,
+                taskTitle,
+            };
+            const onUpdate = this.onSessionEvent
+                ? (update) => {
+                    emitStartedEvent();
+                    this.accumulator.handleUpdate(sessionCtx, update, this.onSessionEvent);
                 }
-                else {
-                    console.error(`[dispatch] Agent "${agentId}" exceeded retry limit. Dropping invocation.`, err);
-                    // AC: @daemon-agent-dispatch ac-3, ac-4 - Emit failed event when retry limit exceeded
-                    this.onInvocationEvent?.({
-                        type: "failed",
+                : undefined;
+            const options = {
+                agent,
+                specDir: this.specDir,
+                sessionsDir: path.join(this.projectDir, ".kspec-sessions"),
+                cwd: workspace.cwd,
+                taskRef: entry.change.taskRef,
+                prompt,
+                trigger: (STATUS_TO_EVENT[entry.change.toStatus] ?? "task.ready"),
+                kspecCliPath: this.kspecCliPath,
+                abortSignal: abortController.signal,
+                sessionId: preSessionId,
+                mutationLockFile: getDispatchShadowMutationLockPath(this.projectDir),
+                env: {
+                    KSPEC_DISPATCH_BASE_BRANCH: workspace.metadata.baseBranch,
+                    KSPEC_DISPATCH_MERGE_TARGET: workspace.metadata.mergeTargetBranch,
+                    KSPEC_DISPATCH_CANONICAL_BRANCH: workspace.metadata.canonicalBranch,
+                    KSPEC_DISPATCH_CANONICAL_HEAD: workspace.metadata.canonicalBranchHead,
+                    KSPEC_DISPATCH_INTEGRATION_TARGET: workspace.metadata.integrationTargetBranch,
+                    KSPEC_DISPATCH_INTEGRATION_COMMIT: workspace.metadata.integrationTargetCommit,
+                    KSPEC_DISPATCH_PUBLICATION_MODE: workspace.metadata.publicationMode,
+                    KSPEC_DISPATCH_INTEGRATION_STATE: workspace.metadata.integrationState,
+                    KSPEC_DISPATCH_INTEGRATION_OUTCOME: workspace.metadata.integrationOutcome,
+                    KSPEC_DISPATCH_WORKTREE_ROOT: workspace.metadata.worktreeRoot,
+                    KSPEC_DISPATCH_WORKSPACE_FILE: workspace.metadataPath,
+                    KSPEC_DISPATCH_WORKSPACE_ID: workspace.metadata.workspaceId,
+                    KSPEC_DISPATCH_BOOTSTRAP_STATUS: workspace.metadata.bootstrap.status,
+                    KSPEC_DISPATCH_BOOTSTRAP_LAST_ROLE: workspace.metadata.bootstrap.lastRole ?? "",
+                },
+                onUpdate,
+                // AC: @session-summary-cache ac-live-counter — increment cache counter on each event append
+                onEventAppended: (sid) => {
+                    const sessionsDir = path.join(this.projectDir, ".kspec-sessions");
+                    const cache = getSessionCache(sessionsDir);
+                    cache.incrementEventCount(sid);
+                },
+            };
+            let resolveInvocationStarted;
+            const invocationStarted = new Promise((resolve) => {
+                resolveInvocationStarted = resolve;
+            });
+            let invocationStartedResolved = false;
+            const markInvocationStarted = () => {
+                if (invocationStartedResolved)
+                    return;
+                invocationStartedResolved = true;
+                resolveInvocationStarted();
+            };
+            let terminalEvent = null;
+            let releasedInFlightKey = false;
+            const markActivePromise = this.shadowMutex.runExclusive(async () => {
+                try {
+                    const activeWorkspace = await markDispatchWorkspaceActive({
+                        projectDir: this.projectDir,
+                        taskRef: entry.change.taskRef,
+                        role: entry.change.toStatus === "pending_review" ? "reviewer" : "worker",
+                    });
+                    if (activeWorkspace) {
+                        workspace = activeWorkspace;
+                        options.env = {
+                            ...options.env,
+                            KSPEC_DISPATCH_WORKSPACE_FILE: activeWorkspace.metadataPath,
+                            KSPEC_DISPATCH_WORKSPACE_ID: activeWorkspace.metadata.workspaceId,
+                        };
+                    }
+                }
+                catch (err) {
+                    console.error(`[dispatch] Failed to mark workspace active for ${entry.change.taskRef}:`, err);
+                }
+            });
+            const invocationPromise = Promise.resolve()
+                .then(async () => {
+                // AC: @agent-dispatch-engine ac-9 - Retry on transient errors
+                try {
+                    markInvocationStarted();
+                    emitStartedEvent();
+                    await markActivePromise;
+                    await runInvocation(options);
+                    // Reset retry count on success
+                    entry.retryCount = 0;
+                    entry.starvationDeferrals = 0;
+                    this.recentTaskAffinityRef = entry.change.taskRef;
+                    terminalEvent = {
+                        type: "completed",
                         session_id: preSessionId,
                         agent_id: agentId,
                         task_id: entry.change.taskRef,
-                        status: "failed",
+                        task_title: entry.change.task?.title ?? null,
+                        status: "completed",
                         timestamp: Date.now(),
+                    };
+                }
+                catch (err) {
+                    markInvocationStarted();
+                    const retryLimit = agent.budget?.max_retries ?? 3;
+                    if (entry.retryCount < retryLimit) {
+                        entry.retryCount++;
+                        const backoffMs = Math.min(1000 * Math.pow(2, entry.retryCount - 1), 30_000);
+                        entry.nextRetryAt = Date.now() + backoffMs;
+                        console.warn(`[dispatch] Invocation for agent "${agentId}" failed (attempt ${entry.retryCount}/${retryLimit}), retrying in ${backoffMs}ms`, err);
+                        // Re-enqueue for retry while preserving status precedence ordering.
+                        const queue = this.queues.get(agentId) ?? [];
+                        this._insertQueueEntry(queue, entry);
+                        this.queues.set(agentId, queue);
+                        // AC: @agent-dispatch-engine ac-9, ac-27 - Schedule wake-up to drain retry
+                        // All drains go through _serializedDrain() to prevent concurrent races.
+                        setTimeout(() => {
+                            if (this.running) {
+                                this._serializedDrain()
+                                    .catch(() => { });
+                            }
+                        }, backoffMs);
+                    }
+                    else {
+                        console.error(`[dispatch] Agent "${agentId}" exceeded retry limit. Dropping invocation.`, err);
+                        terminalEvent = {
+                            type: "failed",
+                            session_id: preSessionId,
+                            agent_id: agentId,
+                            task_id: entry.change.taskRef,
+                            task_title: entry.change.task?.title ?? null,
+                            status: "failed",
+                            timestamp: Date.now(),
+                        };
+                    }
+                }
+                // AC: @session-summary-cache ac-live-counter — discard live counter after session closes
+                // and invalidate cache entry so next list picks up persisted stats
+                {
+                    const sessionsDir = path.join(this.projectDir, ".kspec-sessions");
+                    const cache = getSessionCache(sessionsDir);
+                    cache.discardLiveCounter(preSessionId);
+                    cache.invalidate(preSessionId);
+                }
+                try {
+                    await this.shadowMutex.runExclusive(async () => {
+                        await markDispatchWorkspaceIdle({
+                            projectDir: this.projectDir,
+                            taskRef: entry.change.taskRef,
+                            taskStatus: entry.change.toStatus,
+                        });
                     });
                 }
+                catch (err) {
+                    console.error(`[dispatch] Failed to mark workspace idle for ${entry.change.taskRef}:`, err);
+                }
+                // Clean up active tracking before queue drain runs so completed
+                // invocations do not linger in the active fleet snapshot.
+                const currentActive = this.activeCount.get(agentId) ?? 1;
+                this.activeCount.set(agentId, Math.max(0, currentActive - 1));
+                this.activeInvocationDetails.delete(invocationId);
+                if (entry.change.toStatus === "pending_review") {
+                    try {
+                        await this.shadowMutex.runExclusive(async () => {
+                            await cleanupReviewerDispatchWorkspace(this.projectDir, entry.change.taskRef, entry.change.task
+                                ? {
+                                    title: entry.change.task.title,
+                                    slugs: entry.change.task.slugs,
+                                }
+                                : undefined);
+                        });
+                    }
+                    catch (cleanupErr) {
+                        const cleanupMessage = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
+                        console.warn(`[dispatch] Failed to clean reviewer snapshot for ${entry.change.taskRef}: ${cleanupMessage}`);
+                    }
+                }
+                // Flush any remaining buffered text before emitting terminal event
+                if (this.onSessionEvent) {
+                    this.accumulator.endSession(sessionCtx, this.onSessionEvent);
+                }
+                if (terminalEvent) {
+                    this.onInvocationEvent?.(terminalEvent);
+                }
+            })
+                .then(async () => {
+                if (!this.running)
+                    return;
+                // Release the in-flight marker before re-evaluating tasks from disk so
+                // follow-up reviewer/fix-cycle work for the same task can be requeued
+                // immediately after the prior invocation completes.
+                this.inFlightTaskKeys.delete(inFlightKey);
+                releasedInFlightKey = true;
+                // AC: @agent-dispatch-engine ac-23, ac-24
+                // Re-evaluate all tasks from disk so the drain loop sees tasks that
+                // reached a dispatchable state during the prior invocation (e.g.
+                // pending_review tasks submitted by a worker).
+                try {
+                    await this._evaluateAllTasks({ skipIfActive: true });
+                }
+                catch (err) {
+                    // AC: @agent-dispatch-engine ac-25
+                    console.warn("[dispatch] Post-invocation re-evaluation failed, proceeding with existing queue:", err);
+                }
+                // AC: @agent-dispatch-engine ac-27 — all drains go through _serializedDrain()
+                try {
+                    await this._serializedDrain();
+                }
+                catch {
+                    // Best effort drain
+                }
+            })
+                .finally(() => {
+                if (!releasedInFlightKey) {
+                    this.inFlightTaskKeys.delete(inFlightKey);
+                }
+                this.runningInvocations.delete(invocationPromise);
+                this.invocationAbortControllers.delete(abortController);
+            });
+            invocationRegistered = true;
+            this.runningInvocations.add(invocationPromise);
+            await invocationStarted;
+            return true;
+        }
+        finally {
+            if (!invocationRegistered) {
+                this.inFlightTaskKeys.delete(inFlightKey);
             }
-        })
-            .then(async () => {
-            // Decrement active count and drain again
-            const currentActive = this.activeCount.get(agentId) ?? 1;
-            this.activeCount.set(agentId, Math.max(0, currentActive - 1));
-            if (!this.running)
-                return;
-            // Try to drain more items
-            try {
-                const agents = await this._loadAgents();
-                await this._drainQueues(agents);
-            }
-            catch {
-                // Best effort
-            }
-        })
-            .finally(() => {
-            this.runningInvocations.delete(invocationPromise);
-            this.invocationAbortControllers.delete(abortController);
-            this.activeInvocationDetails.delete(invocationId);
-        });
-        this.runningInvocations.add(invocationPromise);
-        return true;
+        }
     }
 }
 //# sourceMappingURL=dispatch.js.map