@pruddiman/dispatch 0.0.1 → 1.2.1

package/dist/cli.js

@@ -11,39 +11,64 @@ var __export = (target, all) => {
 
 // src/helpers/logger.ts
 import chalk from "chalk";
-var MAX_CAUSE_CHAIN_DEPTH, log;
+function resolveLogLevel() {
+  const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+  if (envLevel && Object.hasOwn(LOG_LEVEL_SEVERITY, envLevel)) {
+    return envLevel;
+  }
+  if (process.env.DEBUG) {
+    return "debug";
+  }
+  return "info";
+}
+function shouldLog(level) {
+  return LOG_LEVEL_SEVERITY[level] >= LOG_LEVEL_SEVERITY[currentLevel];
+}
+var LOG_LEVEL_SEVERITY, currentLevel, MAX_CAUSE_CHAIN_DEPTH, log;
 var init_logger = __esm({
   "src/helpers/logger.ts"() {
     "use strict";
+    LOG_LEVEL_SEVERITY = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3
+    };
+    currentLevel = resolveLogLevel();
     MAX_CAUSE_CHAIN_DEPTH = 5;
     log = {
-      /** When true, `debug()` messages are printed. Set by `--verbose`. */
       verbose: false,
       info(msg) {
+        if (!shouldLog("info")) return;
         console.log(chalk.blue("\u2139"), msg);
       },
       success(msg) {
+        if (!shouldLog("info")) return;
         console.log(chalk.green("\u2714"), msg);
       },
       warn(msg) {
-        console.log(chalk.yellow("\u26A0"), msg);
+        if (!shouldLog("warn")) return;
+        console.error(chalk.yellow("\u26A0"), msg);
       },
       error(msg) {
+        if (!shouldLog("error")) return;
         console.error(chalk.red("\u2716"), msg);
       },
       task(index, total, msg) {
+        if (!shouldLog("info")) return;
         console.log(chalk.cyan(`[${index + 1}/${total}]`), msg);
       },
       dim(msg) {
+        if (!shouldLog("info")) return;
         console.log(chalk.dim(msg));
       },
       /**
-       * Print a debug/verbose message. Only visible when `log.verbose` is true.
-       * Messages are prefixed with a dim arrow to visually nest them under the
-       * preceding info/error line.
+       * Print a debug/verbose message. Only visible when the log level is
+       * `"debug"`. Messages are prefixed with a dim arrow to visually nest
+       * them under the preceding info/error line.
        */
       debug(msg) {
-        if (!this.verbose) return;
+        if (!shouldLog("debug")) return;
         console.log(chalk.dim(`  \u2937 ${msg}`));
       },
       /**
@@ -83,6 +108,26 @@ var init_logger = __esm({
         return "";
       }
     };
+    Object.defineProperty(log, "verbose", {
+      get() {
+        return currentLevel === "debug";
+      },
+      set(value) {
+        currentLevel = value ? "debug" : "info";
+      },
+      enumerable: true,
+      configurable: true
+    });
+  }
+});
+
+// src/helpers/guards.ts
+function hasProperty(value, key) {
+  return typeof value === "object" && value !== null && Object.prototype.hasOwnProperty.call(value, key);
+}
+var init_guards = __esm({
+  "src/helpers/guards.ts"() {
+    "use strict";
   }
 });
 
@@ -183,6 +228,7 @@ async function boot(opts) {
     },
     async prompt(sessionId, text) {
       log.debug(`Sending async prompt to session ${sessionId} (${text.length} chars)...`);
+      let controller;
       try {
         const { error: promptError } = await client.session.promptAsync({
           path: { id: sessionId },
@@ -195,11 +241,11 @@ async function boot(opts) {
           throw new Error(`OpenCode promptAsync failed: ${JSON.stringify(promptError)}`);
         }
         log.debug("Async prompt accepted, subscribing to events...");
-        const controller = new AbortController();
-        const { stream } = await client.event.subscribe({
-          signal: controller.signal
-        });
+        controller = new AbortController();
         try {
+          const { stream } = await client.event.subscribe({
+            signal: controller.signal
+          });
           for await (const event of stream) {
             if (!isSessionEvent(event, sessionId)) continue;
             if (event.type === "message.part.updated" && event.properties.part.type === "text") {
@@ -221,7 +267,7 @@ async function boot(opts) {
             }
           }
         } finally {
-          controller.abort();
+          if (controller && !controller.signal.aborted) controller.abort();
         }
         const { data: messages } = await client.session.messages({
           path: { id: sessionId }
@@ -235,7 +281,7 @@ async function boot(opts) {
           log.debug("No assistant message found in session");
           return null;
         }
-        if (lastAssistant.info.role === "assistant" && "error" in lastAssistant.info && lastAssistant.info.error) {
+        if (hasProperty(lastAssistant.info, "error") && lastAssistant.info.error) {
           throw new Error(
             `OpenCode assistant error: ${JSON.stringify(lastAssistant.info.error)}`
           );
@@ -265,11 +311,14 @@ async function boot(opts) {
 }
 function isSessionEvent(event, sessionId) {
   const props = event.properties;
-  if (props.sessionID === sessionId) return true;
-  if (props.info && typeof props.info === "object" && props.info.sessionID === sessionId) {
+  if (!hasProperty(props, "sessionID") && !hasProperty(props, "info") && !hasProperty(props, "part")) {
+    return false;
+  }
+  if (hasProperty(props, "sessionID") && props.sessionID === sessionId) return true;
+  if (hasProperty(props, "info") && hasProperty(props.info, "sessionID") && props.info.sessionID === sessionId) {
     return true;
   }
-  if (props.part && typeof props.part === "object" && props.part.sessionID === sessionId) {
+  if (hasProperty(props, "part") && hasProperty(props.part, "sessionID") && props.part.sessionID === sessionId) {
     return true;
   }
   return false;
@@ -278,6 +327,52 @@ var init_opencode = __esm({
   "src/providers/opencode.ts"() {
     "use strict";
     init_logger();
+    init_guards();
+  }
+});
+
+// src/helpers/timeout.ts
+function withTimeout(promise, ms, label) {
+  const p = new Promise((resolve4, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      reject(new TimeoutError(ms, label));
+    }, ms);
+    promise.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve4(value);
+      },
+      (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+  p.catch(() => {
+  });
+  return p;
+}
+var TimeoutError;
+var init_timeout = __esm({
+  "src/helpers/timeout.ts"() {
+    "use strict";
+    TimeoutError = class extends Error {
+      /** Optional label identifying the operation that timed out. */
+      label;
+      constructor(ms, label) {
+        const suffix = label ? ` [${label}]` : "";
+        super(`Timed out after ${ms}ms${suffix}`);
+        this.name = "TimeoutError";
+        this.label = label;
+      }
+    };
   }
 });
 
@@ -354,18 +449,25 @@ async function boot2(opts) {
       try {
         await session.send({ prompt: text });
         log.debug("Async prompt accepted, waiting for session to become idle...");
-        await new Promise((resolve2, reject) => {
-          const unsubIdle = session.on("session.idle", () => {
-            unsubIdle();
-            unsubErr();
-            resolve2();
-          });
-          const unsubErr = session.on("session.error", (event) => {
-            unsubIdle();
-            unsubErr();
-            reject(new Error(`Copilot session error: ${event.data.message}`));
-          });
-        });
+        let unsubIdle;
+        let unsubErr;
+        try {
+          await withTimeout(
+            new Promise((resolve4, reject) => {
+              unsubIdle = session.on("session.idle", () => {
+                resolve4();
+              });
+              unsubErr = session.on("session.error", (event) => {
+                reject(new Error(`Copilot session error: ${event.data.message}`));
+              });
+            }),
+            3e5,
+            "copilot session ready"
+          );
+        } finally {
+          unsubIdle?.();
+          unsubErr?.();
+        }
         log.debug("Session went idle, fetching result...");
         const events = await session.getMessages();
         const last = [...events].reverse().find((e) => e.type === "assistant.message");
@@ -396,6 +498,7 @@ var init_copilot = __esm({
   "src/providers/copilot.ts"() {
     "use strict";
     init_logger();
+    init_timeout();
   }
 });
 
@@ -502,7 +605,8 @@ async function boot4(opts) {
           model,
           config: { model, instructions: "" },
           approvalPolicy: "full-auto",
-          additionalWritableRoots: opts?.cwd ? [opts.cwd] : [],
+          ...opts?.cwd ? { rootDir: opts.cwd } : {},
+          additionalWritableRoots: [],
           getCommandConfirmation: async () => ({ approved: true }),
           onItem: () => {
           },
@@ -685,7 +789,7 @@ async function detectTestCommand(cwd) {
   }
 }
 function runTestCommand(command, cwd) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve4) => {
     const [cmd, ...args] = command.split(" ");
     execFileCb(
       cmd,
@@ -693,7 +797,7 @@ function runTestCommand(command, cwd) {
       { cwd, maxBuffer: 10 * 1024 * 1024 },
       (error, stdout, stderr) => {
         const exitCode = error && "code" in error ? error.code ?? 1 : error ? 1 : 0;
-        resolve2({ exitCode, stdout, stderr, command });
+        resolve4({ exitCode, stdout, stderr, command });
       }
     );
   });
@@ -777,7 +881,6 @@ async function runFixTestsPipeline(opts) {
   } catch (err) {
     const message = log.extractMessage(err);
     log.error(`Fix-tests pipeline failed: ${log.formatErrorChain(err)}`);
-    log.debug(log.formatErrorChain(err));
     return { mode: "fix-tests", success: false, error: message };
   }
 }
@@ -791,7 +894,7 @@ var init_fix_tests_pipeline = __esm({
 });
 
 // src/cli.ts
-import { resolve, join as join11 } from "path";
+import { resolve as resolve3, join as join11 } from "path";
 
 // src/spec-generator.ts
 import { cpus, freemem } from "os";
@@ -814,6 +917,13 @@ function slugify(input2, maxLength) {
 // src/datasources/github.ts
 init_logger();
 var exec = promisify(execFile);
+var InvalidBranchNameError = class extends Error {
+  constructor(branch, reason) {
+    const detail = reason ? ` (${reason})` : "";
+    super(`Invalid branch name: "${branch}"${detail}`);
+    this.name = "InvalidBranchNameError";
+  }
+};
 async function git(args, cwd) {
   const { stdout } = await exec("git", args, { cwd });
   return stdout;
@@ -822,16 +932,35 @@ async function gh(args, cwd) {
   const { stdout } = await exec("gh", args, { cwd });
   return stdout;
 }
+var VALID_BRANCH_NAME_RE = /^[a-zA-Z0-9._\-/]+$/;
+function isValidBranchName(name) {
+  if (name.length === 0 || name.length > 255) return false;
+  if (!VALID_BRANCH_NAME_RE.test(name)) return false;
+  if (name.startsWith("/") || name.endsWith("/")) return false;
+  if (name.includes("..")) return false;
+  if (name.endsWith(".lock")) return false;
+  if (name.includes("@{")) return false;
+  if (name.includes("//")) return false;
+  return true;
+}
 function buildBranchName(issueNumber, title, username = "unknown") {
   const slug = slugify(title, 50);
   return `${username}/dispatch/${issueNumber}-${slug}`;
 }
 async function getDefaultBranch(cwd) {
+  const PREFIX = "refs/remotes/origin/";
   try {
     const ref = await git(["symbolic-ref", "refs/remotes/origin/HEAD"], cwd);
-    const parts = ref.trim().split("/");
-    return parts[parts.length - 1];
-  } catch {
+    const trimmed = ref.trim();
+    const branch = trimmed.startsWith(PREFIX) ? trimmed.slice(PREFIX.length) : trimmed;
+    if (!isValidBranchName(branch)) {
+      throw new InvalidBranchNameError(branch, "from symbolic-ref output");
+    }
+    return branch;
+  } catch (err) {
+    if (err instanceof InvalidBranchNameError) {
+      throw err;
+    }
     try {
       await git(["rev-parse", "--verify", "main"], cwd);
       return "main";
@@ -842,6 +971,9 @@ async function getDefaultBranch(cwd) {
 }
 var datasource = {
   name: "github",
+  supportsGit() {
+    return true;
+  },
   async list(opts = {}) {
     const cwd = opts.cwd || process.cwd();
     const { stdout } = await exec(
@@ -1043,6 +1175,9 @@ async function detectWorkItemType(opts = {}) {
 }
 var datasource2 = {
   name: "azdevops",
+  supportsGit() {
+    return true;
+  },
   async list(opts = {}) {
     const wiql = "SELECT [System.Id] FROM workitems WHERE [System.State] <> 'Closed' AND [System.State] <> 'Removed' ORDER BY [System.CreatedDate] DESC";
     const args = ["boards", "query", "--wiql", wiql, "--output", "json"];
@@ -1336,6 +1471,20 @@ import { execFile as execFile3 } from "child_process";
 import { readFile, writeFile, readdir, mkdir, rename } from "fs/promises";
 import { join, parse as parsePath } from "path";
 import { promisify as promisify3 } from "util";
+
+// src/helpers/errors.ts
+var UnsupportedOperationError = class extends Error {
+  /** The name of the operation that is not supported. */
+  operation;
+  constructor(operation, message) {
+    const msg = message ?? `Operation not supported: ${operation}`;
+    super(msg);
+    this.name = "UnsupportedOperationError";
+    this.operation = operation;
+  }
+};
+
+// src/datasources/md.ts
 var exec3 = promisify3(execFile3);
 var DEFAULT_DIR = ".dispatch/specs";
 function resolveDir(opts) {
@@ -1372,6 +1521,9 @@ function toIssueDetails(filename, content, dir) {
 }
 var datasource3 = {
   name: "md",
+  supportsGit() {
+    return false;
+  },
   async list(opts) {
     const dir = resolveDir(opts);
     let entries;
@@ -1436,15 +1588,19 @@ var datasource3 = {
     return `${username}/dispatch/${issueNumber}-${slug}`;
   },
   async createAndSwitchBranch(_branchName, _opts) {
+    throw new UnsupportedOperationError("createAndSwitchBranch");
   },
   async switchBranch(_branchName, _opts) {
+    throw new UnsupportedOperationError("switchBranch");
   },
   async pushBranch(_branchName, _opts) {
+    throw new UnsupportedOperationError("pushBranch");
   },
   async commitAllChanges(_message, _opts) {
+    throw new UnsupportedOperationError("commitAllChanges");
   },
   async createPullRequest(_branchName, _issueNumber, _title, _body, _opts) {
-    return "";
+    throw new UnsupportedOperationError("createPullRequest");
   }
 };
 
@@ -1824,7 +1980,12 @@ async function runInteractiveConfigWizard(configDir) {
 }
 
 // src/config.ts
-var CONFIG_KEYS = ["provider", "model", "source", "testTimeout"];
+var CONFIG_BOUNDS = {
+  testTimeout: { min: 1, max: 120 },
+  planTimeout: { min: 1, max: 120 },
+  concurrency: { min: 1, max: 64 }
+};
+var CONFIG_KEYS = ["provider", "model", "source", "testTimeout", "planTimeout", "concurrency"];
 function getConfigPath(configDir) {
   const dir = configDir ?? join3(process.cwd(), ".dispatch");
   return join3(dir, "config.json");
@@ -1852,7 +2013,9 @@ var CONFIG_TO_CLI = {
   provider: "provider",
   model: "model",
   source: "issueSource",
-  testTimeout: "testTimeout"
+  testTimeout: "testTimeout",
+  planTimeout: "planTimeout",
+  concurrency: "concurrency"
 };
 function setCliField(target, key, value) {
   target[key] = value;
@@ -1913,7 +2076,7 @@ init_providers();
 
 // src/agents/spec.ts
 import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile4, unlink } from "fs/promises";
-import { join as join5 } from "path";
+import { join as join5, resolve, sep } from "path";
 import { randomUUID as randomUUID3 } from "crypto";
 init_logger();
 async function boot5(opts) {
@@ -1925,8 +2088,19 @@ async function boot5(opts) {
     name: "spec",
     async generate(genOpts) {
       const { issue, filePath, fileContent, inlineText, cwd: workingDir, outputPath } = genOpts;
+      const startTime = Date.now();
       try {
-        const tmpDir = join5(workingDir, ".dispatch", "tmp");
+        const resolvedCwd = resolve(workingDir);
+        const resolvedOutput = resolve(outputPath);
+        if (resolvedOutput !== resolvedCwd && !resolvedOutput.startsWith(resolvedCwd + sep)) {
+          return {
+            data: null,
+            success: false,
+            error: `Output path "${outputPath}" escapes the working directory "${workingDir}"`,
+            durationMs: Date.now() - startTime
+          };
+        }
+        const tmpDir = join5(resolvedCwd, ".dispatch", "tmp");
         await mkdir3(tmpDir, { recursive: true });
         const tmpFilename = `spec-${randomUUID3()}.md`;
         const tmpPath = join5(tmpDir, tmpFilename);
@@ -1939,10 +2113,10 @@ async function boot5(opts) {
           prompt = buildFileSpecPrompt(filePath, fileContent, workingDir, tmpPath);
         } else {
           return {
-            content: "",
+            data: null,
             success: false,
             error: "Either issue, inlineText, or filePath+fileContent must be provided",
-            valid: false
+            durationMs: Date.now() - startTime
           };
         }
         const sessionId = await provider.createSession();
@@ -1950,10 +2124,10 @@ async function boot5(opts) {
         const response = await provider.prompt(sessionId, prompt);
         if (response === null) {
           return {
-            content: "",
+            data: null,
             success: false,
             error: "AI agent returned no response",
-            valid: false
+            durationMs: Date.now() - startTime
           };
         }
         log.debug(`Spec agent response (${response.length} chars)`);
@@ -1962,10 +2136,10 @@ async function boot5(opts) {
           rawContent = await readFile4(tmpPath, "utf-8");
         } catch {
           return {
-            content: "",
+            data: null,
             success: false,
             error: `Spec agent did not write the file to ${tmpPath}. Agent response: ${response.slice(0, 300)}`,
-            valid: false
+            durationMs: Date.now() - startTime
           };
         }
         const cleanedContent = extractSpecContent(rawContent);
@@ -1974,25 +2148,28 @@ async function boot5(opts) {
         if (!validation.valid) {
           log.warn(`Spec validation warning for ${outputPath}: ${validation.reason}`);
         }
-        await writeFile4(outputPath, cleanedContent, "utf-8");
-        log.debug(`Wrote cleaned spec to ${outputPath}`);
+        await writeFile4(resolvedOutput, cleanedContent, "utf-8");
+        log.debug(`Wrote cleaned spec to ${resolvedOutput}`);
         try {
           await unlink(tmpPath);
         } catch {
         }
         return {
-          content: cleanedContent,
+          data: {
+            content: cleanedContent,
+            valid: validation.valid,
+            validationReason: validation.reason
+          },
           success: true,
-          valid: validation.valid,
-          validationReason: validation.reason
+          durationMs: Date.now() - startTime
         };
       } catch (err) {
         const message = log.extractMessage(err);
         return {
-          content: "",
+          data: null,
           success: false,
           error: message,
-          valid: false
+          durationMs: Date.now() - startTime
         };
       }
     },
@@ -2000,24 +2177,8 @@ async function boot5(opts) {
     }
   };
 }
-function buildSpecPrompt(issue, cwd, outputPath) {
-  const sections = [
-    `You are a **spec agent**. Your job is to explore the codebase, understand the issue below, and write a high-level **markdown spec file** to disk that will drive an automated implementation pipeline.`,
-    ``,
-    `**Important:** This file will be consumed by a two-stage pipeline:`,
-    `1. A **planner agent** reads each task together with the prose context in this file, then explores the codebase to produce a detailed, line-level implementation plan.`,
-    `2. A **coder agent** follows that detailed plan to make the actual code changes.`,
-    ``,
-    `Because the planner agent handles low-level details, your spec must stay **high-level and strategic**. Focus on the WHAT, WHY, and HOW \u2014 not exact code or line numbers.`,
-    ``,
-    `**CRITICAL \u2014 Output constraints (read carefully):**`,
-    `The file you write must contain ONLY the structured spec content described below. You MUST NOT include:`,
-    `- **No preamble:** Do not add any text before the H1 heading (e.g., "Here's the spec:", "I've written the spec file to...")`,
-    `- **No postamble:** Do not add any text after the last spec section (e.g., "Let me know if you'd like changes", "Here's a summary of...")`,
-    `- **No summaries:** Do not append a summary or recap of what you wrote`,
-    `- **No code fences:** Do not wrap the spec content in \`\`\`markdown ... \`\`\` or any other code fence`,
-    `- **No conversational text:** Do not include any explanations, commentary, or dialogue \u2014 the file is consumed by an automated pipeline, not a human`,
-    `The file content must start with \`# \` (the H1 heading) and contain nothing before or after the structured spec sections.`,
+function buildIssueSourceSection(issue) {
+  const lines = [
     ``,
     `## Issue Details`,
     ``,
@@ -2027,120 +2188,60 @@ function buildSpecPrompt(issue, cwd, outputPath) {
     `- **URL:** ${issue.url}`
   ];
   if (issue.labels.length > 0) {
-    sections.push(`- **Labels:** ${issue.labels.join(", ")}`);
+    lines.push(`- **Labels:** ${issue.labels.join(", ")}`);
   }
   if (issue.body) {
-    sections.push(``, `### Description`, ``, issue.body);
+    lines.push(``, `### Description`, ``, issue.body);
   }
   if (issue.acceptanceCriteria) {
-    sections.push(``, `### Acceptance Criteria`, ``, issue.acceptanceCriteria);
+    lines.push(``, `### Acceptance Criteria`, ``, issue.acceptanceCriteria);
   }
   if (issue.comments.length > 0) {
-    sections.push(``, `### Discussion`, ``);
+    lines.push(``, `### Discussion`, ``);
     for (const comment of issue.comments) {
-      sections.push(comment, ``);
+      lines.push(comment, ``);
     }
   }
-  sections.push(
-    ``,
-    `## Working Directory`,
-    ``,
-    `\`${cwd}\``,
-    ``,
-    `## Instructions`,
-    ``,
-    `1. **Explore the codebase** \u2014 read relevant files, search for symbols, understand the project structure, language, frameworks, conventions, and patterns. Identify the tech stack (languages, package managers, frameworks, test runners) so your spec aligns with the project's actual standards.`,
-    ``,
-    `2. **Understand the issue** \u2014 analyze the issue description, acceptance criteria, and discussion comments to fully understand what needs to be done and why.`,
-    ``,
-    `3. **Research the approach** \u2014 look up relevant documentation, libraries, and patterns. Consider how the change integrates with the existing architecture, standards, and technologies already in use. For example, if the project is TypeScript, do not propose a Python solution; if it uses Vitest, do not suggest Jest.`,
-    ``,
-    `4. **Identify integration points** \u2014 determine which existing modules, interfaces, patterns, and conventions the implementation must align with. Note the key files and modules involved, but do NOT prescribe exact code changes \u2014 the planner agent will handle that.`,
-    ``,
-    `5. **DO NOT make any code changes** \u2014 you are only producing a spec, not implementing.`,
-    ``,
-    `## Output`,
-    ``,
-    `Write the complete spec as a markdown file to this exact path:`,
-    ``,
-    `\`${outputPath}\``,
-    ``,
-    `Use your Write tool to save the file. The file content MUST begin with the H1 heading \u2014 no preamble, no code fences, no conversational text before it. Do not add any text after the final spec section \u2014 no postamble, no summary, no commentary. The file must follow this structure exactly:`,
-    ``,
-    `# <Issue title> (#<number>)`,
-    ``,
-    `> <One-line summary: what this issue achieves and why it matters>`,
-    ``,
-    `## Context`,
-    ``,
-    `<Describe the relevant parts of the codebase: key modules, directory structure,`,
-    `language/framework, and architectural patterns. Name specific files and modules`,
-    `that are involved so the planner agent knows where to look, but do not include`,
-    `code snippets or line-level details.>`,
-    ``,
-    `## Why`,
-    ``,
-    `<Explain the motivation \u2014 why this change is needed, what problem it solves,`,
-    `what user or system benefit it provides. Pull from the issue description,`,
-    `acceptance criteria, and discussion.>`,
-    ``,
-    `## Approach`,
-    ``,
-    `<High-level description of the implementation strategy. Explain the overall`,
-    `approach, which patterns to follow, what to extend vs. create new, and how`,
-    `the change fits into the existing architecture. Mention relevant standards,`,
-    `technologies, and conventions the implementation MUST align with.>`,
-    ``,
-    `## Integration Points`,
-    ``,
-    `<List the specific modules, interfaces, configurations, and conventions that`,
-    `the implementation must integrate with. For example: existing provider`,
-    `interfaces to implement, CLI argument patterns to follow, test framework`,
-    `and conventions to match, build system requirements, etc.>`,
-    ``,
-    `## Tasks`,
-    ``,
-    `Each task MUST be prefixed with an execution-mode tag:`,
-    ``,
-    `- \`(P)\` \u2014 **Parallel-safe.** This task has no dependency on the output of a prior task and can run concurrently with other \`(P)\` tasks.`,
-    `- \`(S)\` \u2014 **Serial / dependent.** This task depends on a prior task's output or modifies shared state that conflicts with concurrent work. It acts as a barrier: all preceding tasks complete before it starts, and it completes before subsequent tasks begin.`,
-    `- \`(I)\` \u2014 **Isolated / barrier.** This task must run alone after all preceding tasks complete and before any subsequent tasks begin. Use for validation tasks like running tests, linting, or builds that read the output of prior tasks.`,
-    ``,
-    `**Default to \`(P)\`.** Most tasks are independent (e.g., adding a function in one module, writing tests in another). Only use \`(S)\` when a task genuinely depends on the result of a prior task (e.g., "refactor module X" followed by "update callers of module X"). Use \`(I)\` for validation or barrier tasks that must run alone after all prior work completes (e.g., "run tests", "run linting", "build the project").`,
-    ``,
-    `If a task has no \`(P)\`, \`(S)\`, or \`(I)\` prefix, the system treats it as serial, so always tag explicitly.`,
-    ``,
-    `Example:`,
+  return lines;
+}
+function buildFileSourceSection(filePath, content, title) {
+  const lines = [
     ``,
-    `- [ ] (P) Add validation helper to the form utils module`,
-    `- [ ] (P) Add unit tests for the new validation helper`,
-    `- [ ] (S) Refactor the form component to use the new validation helper`,
-    `- [ ] (P) Update documentation for the form utils module`,
-    `- [ ] (I) Run the full test suite to verify all changes pass`,
+    `## File Details`,
     ``,
+    `- **Title:** ${title}`,
+    `- **Source file:** ${filePath}`
+  ];
+  if (content) {
+    lines.push(``, `### Content`, ``, content);
+  }
+  return lines;
+}
+function buildInlineTextSourceSection(title, text) {
+  return [
     ``,
-    `## References`,
+    `## Inline Text`,
     ``,
-    `- <Links to relevant docs, related issues, or external resources>`,
+    `- **Title:** ${title}`,
     ``,
-    `## Key Guidelines`,
+    `### Description`,
     ``,
-    `- **Stay high-level.** Do NOT include code snippets, exact line numbers, diffs, or step-by-step coding instructions. A dedicated planner agent will produce those details for each task at execution time.`,
-    `- **Respect the project's stack.** Your spec must align with the languages, frameworks, libraries, test tools, and conventions already in use. Never suggest technologies that conflict with the existing project.`,
-    `- **Explain WHAT, WHY, and HOW (strategically).** Each task should say what needs to happen, why it's needed, and which part of the codebase it touches \u2014 but leave the tactical "how" to the planner agent.`,
-    `- **Detail integration points.** The prose sections (Context, Approach, Integration Points) are critical \u2014 they tell the planner agent where to look and what constraints to respect.`,
-    `- **Keep tasks atomic and ordered.** Each \`- [ ]\` task must be a single, clear unit of work. Order them so dependencies come first.`,
-    `- **Tag every task with \`(P)\`, \`(S)\`, or \`(I)\`.** Default to \`(P)\` (parallel) unless the task depends on a prior task's output. Use \`(I)\` for validation/barrier tasks. Group related serial dependencies together and prefer parallelism to maximize throughput.`,
-    `- **Embed commit instructions within task descriptions.** You control when commits happen. Instead of creating standalone commit tasks (which would fail \u2014 each task runs in an isolated agent session), include commit instructions at the end of implementation task descriptions at logical boundaries. For example: "Implement the validation helper and commit with a conventional commit message." Group related changes into a single commit where it makes logical sense, and use the project's conventional commit types: \`feat\`, \`fix\`, \`docs\`, \`refactor\`, \`test\`, \`chore\`, \`style\`, \`perf\`, \`ci\`. Not every task needs a commit instruction \u2014 use your judgment to place them at logical boundaries.`,
-    `- **Keep the markdown clean** \u2014 it will be parsed by an automated tool.`
-  );
-  return sections.join("\n");
+    text
+  ];
 }
-function buildFileSpecPrompt(filePath, content, cwd, outputPath) {
-  const title = extractTitle(content, filePath);
-  const writePath = outputPath ?? filePath;
-  const sections = [
-    `You are a **spec agent**. Your job is to explore the codebase, understand the content below, and write a high-level **markdown spec file** to disk that will drive an automated implementation pipeline.`,
+function buildCommonSpecInstructions(params) {
+  const {
+    subject,
+    sourceSection,
+    cwd,
+    outputPath,
+    understandStep,
+    titleTemplate,
+    summaryTemplate,
+    whyLines
+  } = params;
+  return [
+    `You are a **spec agent**. Your job is to explore the codebase, understand ${subject}, and write a high-level **markdown spec file** to disk that will drive an automated implementation pipeline.`,
     ``,
     `**Important:** This file will be consumed by a two-stage pipeline:`,
     `1. A **planner agent** reads each task together with the prose context in this file, then explores the codebase to produce a detailed, line-level implementation plan.`,
@@ -2156,16 +2257,7 @@ function buildFileSpecPrompt(filePath, content, cwd, outputPath) {
     `- **No code fences:** Do not wrap the spec content in \`\`\`markdown ... \`\`\` or any other code fence`,
     `- **No conversational text:** Do not include any explanations, commentary, or dialogue \u2014 the file is consumed by an automated pipeline, not a human`,
     `The file content must start with \`# \` (the H1 heading) and contain nothing before or after the structured spec sections.`,
-    ``,
-    `## File Details`,
-    ``,
-    `- **Title:** ${title}`,
-    `- **Source file:** ${filePath}`
-  ];
-  if (content) {
-    sections.push(``, `### Content`, ``, content);
-  }
-  sections.push(
+    ...sourceSection,
     ``,
     `## Working Directory`,
     ``,
@@ -2175,7 +2267,7 @@ function buildFileSpecPrompt(filePath, content, cwd, outputPath) {
     ``,
     `1. **Explore the codebase** \u2014 read relevant files, search for symbols, understand the project structure, language, frameworks, conventions, and patterns. Identify the tech stack (languages, package managers, frameworks, test runners) so your spec aligns with the project's actual standards.`,
     ``,
-    `2. **Understand the content** \u2014 analyze the file content to fully understand what needs to be done and why.`,
+    understandStep,
     ``,
     `3. **Research the approach** \u2014 look up relevant documentation, libraries, and patterns. Consider how the change integrates with the existing architecture, standards, and technologies already in use. For example, if the project is TypeScript, do not propose a Python solution; if it uses Vitest, do not suggest Jest.`,
     ``,
@@ -2187,13 +2279,13 @@ function buildFileSpecPrompt(filePath, content, cwd, outputPath) {
     ``,
     `Write the complete spec as a markdown file to this exact path:`,
     ``,
-    `\`${writePath}\``,
+    `\`${outputPath}\``,
     ``,
     `Use your Write tool to save the file. The file content MUST begin with the H1 heading \u2014 no preamble, no code fences, no conversational text before it. Do not add any text after the final spec section \u2014 no postamble, no summary, no commentary. The file must follow this structure exactly:`,
     ``,
-    `# <Title>`,
+    titleTemplate,
     ``,
-    `> <One-line summary: what this achieves and why it matters>`,
+    summaryTemplate,
     ``,
     `## Context`,
     ``,
@@ -2205,7 +2297,7 @@ function buildFileSpecPrompt(filePath, content, cwd, outputPath) {
     `## Why`,
     ``,
     `<Explain the motivation \u2014 why this change is needed, what problem it solves,`,
-    `what user or system benefit it provides. Pull from the file content.>`,
+    ...whyLines,
     ``,
     `## Approach`,
     ``,
@@ -2256,130 +2348,53 @@ function buildFileSpecPrompt(filePath, content, cwd, outputPath) {
     `- **Tag every task with \`(P)\`, \`(S)\`, or \`(I)\`.** Default to \`(P)\` (parallel) unless the task depends on a prior task's output. Use \`(I)\` for validation/barrier tasks. Group related serial dependencies together and prefer parallelism to maximize throughput.`,
     `- **Embed commit instructions within task descriptions.** You control when commits happen. Instead of creating standalone commit tasks (which would fail \u2014 each task runs in an isolated agent session), include commit instructions at the end of implementation task descriptions at logical boundaries. For example: "Implement the validation helper and commit with a conventional commit message." Group related changes into a single commit where it makes logical sense, and use the project's conventional commit types: \`feat\`, \`fix\`, \`docs\`, \`refactor\`, \`test\`, \`chore\`, \`style\`, \`perf\`, \`ci\`. Not every task needs a commit instruction \u2014 use your judgment to place them at logical boundaries.`,
     `- **Keep the markdown clean** \u2014 it will be parsed by an automated tool.`
-  );
-  return sections.join("\n");
+  ];
+}
+function buildSpecPrompt(issue, cwd, outputPath) {
+  return buildCommonSpecInstructions({
+    subject: "the issue below",
+    sourceSection: buildIssueSourceSection(issue),
+    cwd,
+    outputPath,
+    understandStep: `2. **Understand the issue** \u2014 analyze the issue description, acceptance criteria, and discussion comments to fully understand what needs to be done and why.`,
+    titleTemplate: `# <Issue title> (#<number>)`,
+    summaryTemplate: `> <One-line summary: what this issue achieves and why it matters>`,
+    whyLines: [
+      `what user or system benefit it provides. Pull from the issue description,`,
+      `acceptance criteria, and discussion.>`
+    ]
+  }).join("\n");
+}
+function buildFileSpecPrompt(filePath, content, cwd, outputPath) {
+  const title = extractTitle(content, filePath);
+  const writePath = outputPath ?? filePath;
+  return buildCommonSpecInstructions({
+    subject: "the content below",
+    sourceSection: buildFileSourceSection(filePath, content, title),
+    cwd,
+    outputPath: writePath,
+    understandStep: `2. **Understand the content** \u2014 analyze the file content to fully understand what needs to be done and why.`,
+    titleTemplate: `# <Title>`,
+    summaryTemplate: `> <One-line summary: what this achieves and why it matters>`,
+    whyLines: [
+      `what user or system benefit it provides. Pull from the file content.>`
+    ]
+  }).join("\n");
 }
 function buildInlineTextSpecPrompt(text, cwd, outputPath) {
   const title = text.length > 80 ? text.slice(0, 80).trimEnd() + "\u2026" : text;
-  const sections = [
-    `You are a **spec agent**. Your job is to explore the codebase, understand the request below, and write a high-level **markdown spec file** to disk that will drive an automated implementation pipeline.`,
-    ``,
-    `**Important:** This file will be consumed by a two-stage pipeline:`,
-    `1. A **planner agent** reads each task together with the prose context in this file, then explores the codebase to produce a detailed, line-level implementation plan.`,
-    `2. A **coder agent** follows that detailed plan to make the actual code changes.`,
-    ``,
-    `Because the planner agent handles low-level details, your spec must stay **high-level and strategic**. Focus on the WHAT, WHY, and HOW \u2014 not exact code or line numbers.`,
-    ``,
-    `**CRITICAL \u2014 Output constraints (read carefully):**`,
-    `The file you write must contain ONLY the structured spec content described below. You MUST NOT include:`,
-    `- **No preamble:** Do not add any text before the H1 heading (e.g., "Here's the spec:", "I've written the spec file to...")`,
-    `- **No postamble:** Do not add any text after the last spec section (e.g., "Let me know if you'd like changes", "Here's a summary of...")`,
-    `- **No summaries:** Do not append a summary or recap of what you wrote`,
-    `- **No code fences:** Do not wrap the spec content in \`\`\`markdown ... \`\`\` or any other code fence`,
-    `- **No conversational text:** Do not include any explanations, commentary, or dialogue \u2014 the file is consumed by an automated pipeline, not a human`,
-    `The file content must start with \`# \` (the H1 heading) and contain nothing before or after the structured spec sections.`,
-    ``,
-    `## Inline Text`,
-    ``,
-    `- **Title:** ${title}`,
-    ``,
-    `### Description`,
-    ``,
-    text
-  ];
-  sections.push(
-    ``,
-    `## Working Directory`,
-    ``,
-    `\`${cwd}\``,
-    ``,
-    `## Instructions`,
-    ``,
-    `1. **Explore the codebase** \u2014 read relevant files, search for symbols, understand the project structure, language, frameworks, conventions, and patterns. Identify the tech stack (languages, package managers, frameworks, test runners) so your spec aligns with the project's actual standards.`,
-    ``,
-    `2. **Understand the request** \u2014 analyze the inline text to fully understand what needs to be done and why. Since this is a brief description rather than a detailed issue or document, you may need to infer details from the codebase.`,
-    ``,
-    `3. **Research the approach** \u2014 look up relevant documentation, libraries, and patterns. Consider how the change integrates with the existing architecture, standards, and technologies already in use. For example, if the project is TypeScript, do not propose a Python solution; if it uses Vitest, do not suggest Jest.`,
-    ``,
-    `4. **Identify integration points** \u2014 determine which existing modules, interfaces, patterns, and conventions the implementation must align with. Note the key files and modules involved, but do NOT prescribe exact code changes \u2014 the planner agent will handle that.`,
-    ``,
-    `5. **DO NOT make any code changes** \u2014 you are only producing a spec, not implementing.`,
-    ``,
-    `## Output`,
-    ``,
-    `Write the complete spec as a markdown file to this exact path:`,
-    ``,
-    `\`${outputPath}\``,
-    ``,
-    `Use your Write tool to save the file. The file content MUST begin with the H1 heading \u2014 no preamble, no code fences, no conversational text before it. Do not add any text after the final spec section \u2014 no postamble, no summary, no commentary. The file must follow this structure exactly:`,
-    ``,
-    `# <Title>`,
-    ``,
-    `> <One-line summary: what this achieves and why it matters>`,
-    ``,
-    `## Context`,
-    ``,
-    `<Describe the relevant parts of the codebase: key modules, directory structure,`,
-    `language/framework, and architectural patterns. Name specific files and modules`,
-    `that are involved so the planner agent knows where to look, but do not include`,
-    `code snippets or line-level details.>`,
-    ``,
-    `## Why`,
-    ``,
-    `<Explain the motivation \u2014 why this change is needed, what problem it solves,`,
-    `what user or system benefit it provides. Pull from the inline text description.>`,
-    ``,
-    `## Approach`,
-    ``,
-    `<High-level description of the implementation strategy. Explain the overall`,
-    `approach, which patterns to follow, what to extend vs. create new, and how`,
-    `the change fits into the existing architecture. Mention relevant standards,`,
-    `technologies, and conventions the implementation MUST align with.>`,
-    ``,
-    `## Integration Points`,
-    ``,
-    `<List the specific modules, interfaces, configurations, and conventions that`,
-    `the implementation must integrate with. For example: existing provider`,
-    `interfaces to implement, CLI argument patterns to follow, test framework`,
-    `and conventions to match, build system requirements, etc.>`,
-    ``,
-    `## Tasks`,
-    ``,
-    `Each task MUST be prefixed with an execution-mode tag:`,
-    ``,
-    `- \`(P)\` \u2014 **Parallel-safe.** This task has no dependency on the output of a prior task and can run concurrently with other \`(P)\` tasks.`,
-    `- \`(S)\` \u2014 **Serial / dependent.** This task depends on a prior task's output or modifies shared state that conflicts with concurrent work. It acts as a barrier: all preceding tasks complete before it starts, and it completes before subsequent tasks begin.`,
-    `- \`(I)\` \u2014 **Isolated / barrier.** This task must run alone after all preceding tasks complete and before any subsequent tasks begin. Use for validation tasks like running tests, linting, or builds that read the output of prior tasks.`,
-    ``,
-    `**Default to \`(P)\`.** Most tasks are independent (e.g., adding a function in one module, writing tests in another). Only use \`(S)\` when a task genuinely depends on the result of a prior task (e.g., "refactor module X" followed by "update callers of module X"). Use \`(I)\` for validation or barrier tasks that must run alone after all prior work completes (e.g., "run tests", "run linting", "build the project").`,
-    ``,
-    `If a task has no \`(P)\`, \`(S)\`, or \`(I)\` prefix, the system treats it as serial, so always tag explicitly.`,
-    ``,
-    `Example:`,
-    ``,
-    `- [ ] (P) Add validation helper to the form utils module`,
-    `- [ ] (P) Add unit tests for the new validation helper`,
-    `- [ ] (S) Refactor the form component to use the new validation helper`,
-    `- [ ] (P) Update documentation for the form utils module`,
-    `- [ ] (I) Run the full test suite to verify all changes pass`,
-    ``,
-    ``,
-    `## References`,
-    ``,
-    `- <Links to relevant docs, related issues, or external resources>`,
-    ``,
-    `## Key Guidelines`,
-    ``,
-    `- **Stay high-level.** Do NOT include code snippets, exact line numbers, diffs, or step-by-step coding instructions. A dedicated planner agent will produce those details for each task at execution time.`,
-    `- **Respect the project's stack.** Your spec must align with the languages, frameworks, libraries, test tools, and conventions already in use. Never suggest technologies that conflict with the existing project.`,
-    `- **Explain WHAT, WHY, and HOW (strategically).** Each task should say what needs to happen, why it's needed, and which part of the codebase it touches \u2014 but leave the tactical "how" to the planner agent.`,
-    `- **Detail integration points.** The prose sections (Context, Approach, Integration Points) are critical \u2014 they tell the planner agent where to look and what constraints to respect.`,
-    `- **Keep tasks atomic and ordered.** Each \`- [ ]\` task must be a single, clear unit of work. Order them so dependencies come first.`,
-    `- **Tag every task with \`(P)\`, \`(S)\`, or \`(I)\`.** Default to \`(P)\` (parallel) unless the task depends on a prior task's output. Use \`(I)\` for validation/barrier tasks. Group related serial dependencies together and prefer parallelism to maximize throughput.`,
-    `- **Embed commit instructions within task descriptions.** You control when commits happen. Instead of creating standalone commit tasks (which would fail \u2014 each task runs in an isolated agent session), include commit instructions at the end of implementation task descriptions at logical boundaries. For example: "Implement the validation helper and commit with a conventional commit message." Group related changes into a single commit where it makes logical sense, and use the project's conventional commit types: \`feat\`, \`fix\`, \`docs\`, \`refactor\`, \`test\`, \`chore\`, \`style\`, \`perf\`, \`ci\`. Not every task needs a commit instruction \u2014 use your judgment to place them at logical boundaries.`,
-    `- **Keep the markdown clean** \u2014 it will be parsed by an automated tool.`
-  );
-  return sections.join("\n");
+  return buildCommonSpecInstructions({
+    subject: "the request below",
+    sourceSection: buildInlineTextSourceSection(title, text),
+    cwd,
+    outputPath,
+    understandStep: `2. **Understand the request** \u2014 analyze the inline text to fully understand what needs to be done and why. Since this is a brief description rather than a detailed issue or document, you may need to infer details from the codebase.`,
+    titleTemplate: `# <Title>`,
+    summaryTemplate: `> <One-line summary: what this achieves and why it matters>`,
+    whyLines: [
+      `what user or system benefit it provides. Pull from the inline text description.>`
+    ]
+  }).join("\n");
 }
 
 // src/orchestrator/spec-pipeline.ts
@@ -2435,146 +2450,134 @@ async function withRetry(fn, maxRetries, options) {
 }
 
 // src/orchestrator/spec-pipeline.ts
-async function runSpecPipeline(opts) {
-  const {
-    issues,
-    provider,
-    model,
-    serverUrl,
-    cwd: specCwd,
-    outputDir = join6(specCwd, ".dispatch", "specs"),
-    org,
-    project,
-    workItemType,
-    concurrency = defaultConcurrency(),
-    dryRun,
-    retries = 2
-  } = opts;
-  const pipelineStart = Date.now();
-  const source = await resolveSource(issues, opts.issueSource, specCwd);
-  if (!source) {
-    return { total: 0, generated: 0, failed: 0, files: [], issueNumbers: [], durationMs: Date.now() - pipelineStart, fileDurationsMs: {} };
-  }
+init_timeout();
+var FETCH_TIMEOUT_MS = 3e4;
+async function resolveDatasource(issues, issueSource, specCwd, org, project, workItemType) {
+  const source = await resolveSource(issues, issueSource, specCwd);
+  if (!source) return null;
   const datasource4 = getDatasource(source);
   const fetchOpts = { cwd: specCwd, org, project, workItemType };
-  const isTrackerMode = isIssueNumbers(issues);
-  const isInlineText = !isTrackerMode && !isGlobOrFilePath(issues);
-  let items;
-  if (isTrackerMode) {
-    const issueNumbers2 = issues.split(",").map((s) => s.trim()).filter(Boolean);
-    if (issueNumbers2.length === 0) {
-      log.error("No issue numbers provided. Use --spec 1,2,3");
-      return { total: 0, generated: 0, failed: 0, files: [], issueNumbers: [], durationMs: 0, fileDurationsMs: {} };
-    }
-    const fetchStart = Date.now();
-    log.info(`Fetching ${issueNumbers2.length} issue(s) from ${source} (concurrency: ${concurrency})...`);
-    items = [];
-    const fetchQueue = [...issueNumbers2];
-    while (fetchQueue.length > 0) {
-      const batch = fetchQueue.splice(0, concurrency);
-      log.debug(`Fetching batch of ${batch.length}: #${batch.join(", #")}`);
-      const batchResults = await Promise.all(
-        batch.map(async (id) => {
-          try {
-            const details = await datasource4.fetch(id, fetchOpts);
-            log.success(`Fetched #${id}: ${details.title}`);
-            log.debug(`Body: ${details.body?.length ?? 0} chars, Labels: ${details.labels.length}, Comments: ${details.comments.length}`);
-            return { id, details };
-          } catch (err) {
-            const message = log.extractMessage(err);
-            log.error(`Failed to fetch #${id}: ${log.formatErrorChain(err)}`);
-            log.debug(log.formatErrorChain(err));
-            return { id, details: null, error: message };
-          }
-        })
-      );
-      items.push(...batchResults);
-    }
-    log.debug(`Issue fetching completed in ${elapsed(Date.now() - fetchStart)}`);
-  } else if (isInlineText) {
-    const text = Array.isArray(issues) ? issues.join(" ") : issues;
-    const title = text.length > 80 ? text.slice(0, 80).trimEnd() + "\u2026" : text;
-    const slug = slugify(text, MAX_SLUG_LENGTH);
-    const filename = `${slug}.md`;
-    const filepath = join6(outputDir, filename);
-    const details = {
-      number: filepath,
-      title,
-      body: text,
-      labels: [],
-      state: "open",
-      url: filepath,
-      comments: [],
-      acceptanceCriteria: ""
-    };
-    log.info(`Inline text spec: "${title}"`);
-    items = [{ id: filepath, details }];
-  } else {
-    const files = await glob(issues, { cwd: specCwd, absolute: true });
-    if (files.length === 0) {
-      log.error(`No files matched the pattern "${Array.isArray(issues) ? issues.join(", ") : issues}".`);
-      return { total: 0, generated: 0, failed: 0, files: [], issueNumbers: [], durationMs: 0, fileDurationsMs: {} };
-    }
-    log.info(`Matched ${files.length} file(s) for spec generation (concurrency: ${concurrency})...`);
-    items = [];
-    for (const filePath of files) {
-      try {
-        const content = await readFile5(filePath, "utf-8");
-        const title = extractTitle(content, filePath);
-        const details = {
-          number: filePath,
-          title,
-          body: content,
-          labels: [],
-          state: "open",
-          url: filePath,
-          comments: [],
-          acceptanceCriteria: ""
-        };
-        items.push({ id: filePath, details });
-      } catch (err) {
-        items.push({ id: filePath, details: null, error: log.extractMessage(err) });
-      }
+  return { source, datasource: datasource4, fetchOpts };
+}
+async function fetchTrackerItems(issues, datasource4, fetchOpts, concurrency, source) {
+  const issueNumbers = issues.split(",").map((s) => s.trim()).filter(Boolean);
+  if (issueNumbers.length === 0) {
+    log.error("No issue numbers provided. Use --spec 1,2,3");
+    return [];
+  }
+  const fetchStart = Date.now();
+  log.info(`Fetching ${issueNumbers.length} issue(s) from ${source} (concurrency: ${concurrency})...`);
+  const items = [];
+  const fetchQueue = [...issueNumbers];
+  while (fetchQueue.length > 0) {
+    const batch = fetchQueue.splice(0, concurrency);
+    log.debug(`Fetching batch of ${batch.length}: #${batch.join(", #")}`);
+    const batchResults = await Promise.all(
+      batch.map(async (id) => {
+        try {
+          const details = await withTimeout(datasource4.fetch(id, fetchOpts), FETCH_TIMEOUT_MS, "datasource fetch");
+          log.success(`Fetched #${id}: ${details.title}`);
+          log.debug(`Body: ${details.body?.length ?? 0} chars, Labels: ${details.labels.length}, Comments: ${details.comments.length}`);
+          return { id, details };
+        } catch (err) {
+          const message = log.extractMessage(err);
+          log.error(`Failed to fetch #${id}: ${log.formatErrorChain(err)}`);
+          log.debug(log.formatErrorChain(err));
+          return { id, details: null, error: message };
+        }
+      })
+    );
+    items.push(...batchResults);
+  }
+  log.debug(`Issue fetching completed in ${elapsed(Date.now() - fetchStart)}`);
+  return items;
+}
+function buildInlineTextItem(issues, outputDir) {
+  const text = Array.isArray(issues) ? issues.join(" ") : issues;
+  const title = text.length > 80 ? text.slice(0, 80).trimEnd() + "\u2026" : text;
+  const slug = slugify(text, MAX_SLUG_LENGTH);
+  const filename = `${slug}.md`;
+  const filepath = join6(outputDir, filename);
+  const details = {
+    number: filepath,
+    title,
+    body: text,
+    labels: [],
+    state: "open",
+    url: filepath,
+    comments: [],
+    acceptanceCriteria: ""
+  };
+  log.info(`Inline text spec: "${title}"`);
+  return [{ id: filepath, details }];
+}
+async function resolveFileItems(issues, specCwd, concurrency) {
+  const files = await glob(issues, { cwd: specCwd, absolute: true });
+  if (files.length === 0) {
+    log.error(`No files matched the pattern "${Array.isArray(issues) ? issues.join(", ") : issues}".`);
+    return null;
+  }
+  log.info(`Matched ${files.length} file(s) for spec generation (concurrency: ${concurrency})...`);
+  const items = [];
+  for (const filePath of files) {
+    try {
+      const content = await readFile5(filePath, "utf-8");
+      const title = extractTitle(content, filePath);
+      const details = {
+        number: filePath,
+        title,
+        body: content,
+        labels: [],
+        state: "open",
+        url: filePath,
+        comments: [],
+        acceptanceCriteria: ""
+      };
+      items.push({ id: filePath, details });
+    } catch (err) {
+      items.push({ id: filePath, details: null, error: log.extractMessage(err) });
     }
   }
+  return items;
+}
+function filterValidItems(items, isTrackerMode, isInlineText) {
   const validItems = items.filter(
     (i) => i.details !== null
   );
   if (validItems.length === 0) {
     const noun = isTrackerMode ? "issues" : isInlineText ? "inline specs" : "files";
     log.error(`No ${noun} could be loaded. Aborting spec generation.`);
-    return { total: items.length, generated: 0, failed: items.length, files: [], issueNumbers: [], durationMs: Date.now() - pipelineStart, fileDurationsMs: {} };
+    return null;
   }
-  if (dryRun) {
-    const mode = isTrackerMode ? "tracker" : isInlineText ? "inline" : "file";
-    log.info(`[DRY RUN] Would generate ${validItems.length} spec(s) (mode: ${mode}):
+  return validItems;
+}
+function previewDryRun(validItems, items, isTrackerMode, isInlineText, outputDir, pipelineStart) {
+  const mode = isTrackerMode ? "tracker" : isInlineText ? "inline" : "file";
+  log.info(`[DRY RUN] Would generate ${validItems.length} spec(s) (mode: ${mode}):
 `);
-    for (const { id, details } of validItems) {
-      let filepath;
-      if (isTrackerMode) {
-        const slug = slugify(details.title, 60);
-        filepath = join6(outputDir, `${id}-${slug}.md`);
-      } else {
-        filepath = id;
-      }
-      const label = isTrackerMode ? `#${id}` : filepath;
-      log.info(`[DRY RUN] Would generate spec for ${label}: "${details.title}"`);
-      log.dim(`    \u2192 ${filepath}`);
+  for (const { id, details } of validItems) {
+    let filepath;
+    if (isTrackerMode) {
+      const slug = slugify(details.title, 60);
+      filepath = join6(outputDir, `${id}-${slug}.md`);
+    } else {
+      filepath = id;
     }
-    return {
-      total: items.length,
-      generated: 0,
-      failed: items.filter((i) => i.details === null).length,
-      files: [],
-      issueNumbers: [],
-      durationMs: Date.now() - pipelineStart,
-      fileDurationsMs: {}
-    };
-  }
-  const confirmed = await confirmLargeBatch(validItems.length);
-  if (!confirmed) {
-    return { total: 0, generated: 0, failed: 0, files: [], issueNumbers: [], durationMs: Date.now() - pipelineStart, fileDurationsMs: {} };
+    const label = isTrackerMode ? `#${id}` : filepath;
+    log.info(`[DRY RUN] Would generate spec for ${label}: "${details.title}"`);
+    log.dim(`    \u2192 ${filepath}`);
   }
+  return {
+    total: items.length,
+    generated: 0,
+    failed: items.filter((i) => i.details === null).length,
+    files: [],
+    issueNumbers: [],
+    durationMs: Date.now() - pipelineStart,
+    fileDurationsMs: {}
+  };
+}
+async function bootPipeline(provider, serverUrl, specCwd, model, source) {
   const bootStart = Date.now();
   log.info(`Booting ${provider} provider...`);
   log.debug(serverUrl ? `Using server URL: ${serverUrl}` : "No --server-url, will spawn local server");
@@ -2593,6 +2596,9 @@ async function runSpecPipeline(opts) {
   console.log(chalk5.dim("  \u2500".repeat(24)));
   console.log("");
   const specAgent = await boot5({ provider: instance, cwd: specCwd });
+  return { specAgent, instance };
+}
+async function generateSpecsBatch(validItems, items, specAgent, instance, isTrackerMode, isInlineText, datasource4, fetchOpts, outputDir, specCwd, concurrency, retries) {
   await mkdir4(outputDir, { recursive: true });
   const generatedFiles = [];
   const issueNumbers = [];
@@ -2638,7 +2644,7 @@ async function runSpecPipeline(opts) {
             throw new Error(result.error ?? "Spec generation failed");
           }
           if (isTrackerMode || isInlineText) {
-            const h1Title = extractTitle(result.content, filepath);
+            const h1Title = extractTitle(result.data.content, filepath);
             const h1Slug = slugify(h1Title, MAX_SLUG_LENGTH);
             const finalFilename = isTrackerMode ? `${id}-${h1Slug}.md` : `${h1Slug}.md`;
             const finalFilepath = join6(outputDir, finalFilename);
@@ -2653,14 +2659,14 @@ async function runSpecPipeline(opts) {
           let identifier = filepath;
           try {
             if (isTrackerMode) {
-              await datasource4.update(id, details.title, result.content, fetchOpts);
+              await datasource4.update(id, details.title, result.data.content, fetchOpts);
               log.success(`Updated issue #${id} with spec content`);
               await unlink2(filepath);
               log.success(`Deleted local spec ${filepath} (now tracked as issue #${id})`);
               identifier = id;
               issueNumbers.push(id);
             } else if (datasource4.name !== "md") {
-              const created = await datasource4.create(details.title, result.content, fetchOpts);
+              const created = await datasource4.create(details.title, result.data.content, fetchOpts);
               log.success(`Created issue #${created.number} from ${filepath}`);
               await unlink2(filepath);
               log.success(`Deleted local spec ${filepath} (now tracked as issue #${created.number})`);
@@ -2692,6 +2698,9 @@ async function runSpecPipeline(opts) {
       modelLoggedInBanner = true;
     }
   }
+  return { generatedFiles, issueNumbers, dispatchIdentifiers, failed, fileDurationsMs };
+}
+async function cleanupPipeline(specAgent, instance) {
   try {
     await specAgent.cleanup();
   } catch (err) {
@@ -2702,7 +2711,8 @@ async function runSpecPipeline(opts) {
   } catch (err) {
     log.warn(`Provider cleanup failed: ${log.formatErrorChain(err)}`);
   }
-  const totalDuration = Date.now() - pipelineStart;
+}
+function logSummary(generatedFiles, dispatchIdentifiers, failed, totalDuration) {
   log.info(
     `Spec generation complete: ${generatedFiles.length} generated, ${failed} failed in ${elapsed(totalDuration)}`
   );
@@ -2718,19 +2728,89 @@ async function runSpecPipeline(opts) {
 `);
     }
   }
+}
+async function runSpecPipeline(opts) {
+  const {
+    issues,
+    provider,
+    model,
+    serverUrl,
+    cwd: specCwd,
+    outputDir = join6(specCwd, ".dispatch", "specs"),
+    org,
+    project,
+    workItemType,
+    concurrency = defaultConcurrency(),
+    dryRun,
+    retries = 2
+  } = opts;
+  const pipelineStart = Date.now();
+  const resolved = await resolveDatasource(issues, opts.issueSource, specCwd, org, project, workItemType);
+  if (!resolved) {
+    return { total: 0, generated: 0, failed: 0, files: [], issueNumbers: [], durationMs: Date.now() - pipelineStart, fileDurationsMs: {} };
+  }
+  const { source, datasource: datasource4, fetchOpts } = resolved;
+  const isTrackerMode = isIssueNumbers(issues);
+  const isInlineText = !isTrackerMode && !isGlobOrFilePath(issues);
+  let items;
+  if (isTrackerMode) {
+    items = await fetchTrackerItems(issues, datasource4, fetchOpts, concurrency, source);
+    if (items.length === 0) {
+      return { total: 0, generated: 0, failed: 0, files: [], issueNumbers: [], durationMs: Date.now() - pipelineStart, fileDurationsMs: {} };
+    }
+  } else if (isInlineText) {
+    items = buildInlineTextItem(issues, outputDir);
+  } else {
+    const fileItems = await resolveFileItems(issues, specCwd, concurrency);
+    if (!fileItems) {
+      return { total: 0, generated: 0, failed: 0, files: [], issueNumbers: [], durationMs: Date.now() - pipelineStart, fileDurationsMs: {} };
+    }
+    items = fileItems;
+  }
+  const validItems = filterValidItems(items, isTrackerMode, isInlineText);
+  if (!validItems) {
+    return { total: items.length, generated: 0, failed: items.length, files: [], issueNumbers: [], durationMs: Date.now() - pipelineStart, fileDurationsMs: {} };
+  }
+  if (dryRun) {
+    return previewDryRun(validItems, items, isTrackerMode, isInlineText, outputDir, pipelineStart);
+  }
+  const confirmed = await confirmLargeBatch(validItems.length);
+  if (!confirmed) {
+    return { total: 0, generated: 0, failed: 0, files: [], issueNumbers: [], durationMs: Date.now() - pipelineStart, fileDurationsMs: {} };
+  }
+  const { specAgent, instance } = await bootPipeline(provider, serverUrl, specCwd, model, source);
+  const results = await generateSpecsBatch(
+    validItems,
+    items,
+    specAgent,
+    instance,
+    isTrackerMode,
+    isInlineText,
+    datasource4,
+    fetchOpts,
+    outputDir,
+    specCwd,
+    concurrency,
+    retries
+  );
+  await cleanupPipeline(specAgent, instance);
+  const totalDuration = Date.now() - pipelineStart;
+  logSummary(results.generatedFiles, results.dispatchIdentifiers, results.failed, totalDuration);
   return {
     total: items.length,
-    generated: generatedFiles.length,
-    failed,
-    files: generatedFiles,
-    issueNumbers,
-    identifiers: dispatchIdentifiers,
+    generated: results.generatedFiles.length,
+    failed: results.failed,
+    files: results.generatedFiles,
+    issueNumbers: results.issueNumbers,
+    identifiers: results.dispatchIdentifiers,
     durationMs: totalDuration,
-    fileDurationsMs
+    fileDurationsMs: results.fileDurationsMs
   };
 }
 
 // src/orchestrator/dispatch-pipeline.ts
+import { execFile as execFile9 } from "child_process";
+import { promisify as promisify9 } from "util";
 import { readFile as readFile7 } from "fs/promises";
 
 // src/parser.ts
@@ -2837,25 +2917,26 @@ async function boot6(opts) {
   }
   return {
     name: "planner",
-    async plan(task, fileContext, cwdOverride) {
+    async plan(task, fileContext, cwdOverride, worktreeRoot) {
+      const startTime = Date.now();
       try {
         const sessionId = await provider.createSession();
-        const prompt = buildPlannerPrompt(task, cwdOverride ?? cwd, fileContext);
+        const prompt = buildPlannerPrompt(task, cwdOverride ?? cwd, fileContext, worktreeRoot);
         const plan = await provider.prompt(sessionId, prompt);
         if (!plan?.trim()) {
-          return { prompt: "", success: false, error: "Planner returned empty plan" };
+          return { data: null, success: false, error: "Planner returned empty plan", durationMs: Date.now() - startTime };
         }
-        return { prompt: plan, success: true };
+        return { data: { prompt: plan }, success: true, durationMs: Date.now() - startTime };
       } catch (err) {
         const message = log.extractMessage(err);
-        return { prompt: "", success: false, error: message };
+        return { data: null, success: false, error: message, durationMs: Date.now() - startTime };
       }
     },
     async cleanup() {
     }
   };
 }
-function buildPlannerPrompt(task, cwd, fileContext) {
+function buildPlannerPrompt(task, cwd, fileContext, worktreeRoot) {
   const sections = [
     `You are a **planning agent**. Your job is to explore the codebase, understand the task below, and produce a detailed execution prompt that another agent will follow to implement the changes.`,
     ``,
@@ -2879,6 +2960,21 @@ function buildPlannerPrompt(task, cwd, fileContext) {
       `\`\`\``
     );
   }
+  if (worktreeRoot) {
+    sections.push(
+      ``,
+      `## Worktree Isolation`,
+      ``,
+      `You are operating inside a git worktree. All file operations MUST be confined`,
+      `to the following directory tree:`,
+      ``,
+      `    ${worktreeRoot}`,
+      ``,
+      `- Do NOT read, write, or execute commands that access files outside this directory.`,
+      `- Do NOT reference or modify files in the main repository working tree or other worktrees.`,
+      `- All relative paths must resolve within the worktree root above.`
+    );
+  }
   sections.push(
     ``,
     `## Instructions`,
@@ -2914,11 +3010,11 @@ function buildPlannerPrompt(task, cwd, fileContext) {
 
 // src/dispatcher.ts
 init_logger();
-async function dispatchTask(instance, task, cwd, plan) {
+async function dispatchTask(instance, task, cwd, plan, worktreeRoot) {
   try {
     log.debug(`Dispatching task: ${task.file}:${task.line} \u2014 ${task.text.slice(0, 80)}`);
     const sessionId = await instance.createSession();
-    const prompt = plan ? buildPlannedPrompt(task, cwd, plan) : buildPrompt(task, cwd);
+    const prompt = plan ? buildPlannedPrompt(task, cwd, plan, worktreeRoot) : buildPrompt(task, cwd, worktreeRoot);
     log.debug(`Prompt built (${prompt.length} chars, ${plan ? "with plan" : "no plan"})`);
     const response = await instance.prompt(sessionId, prompt);
     if (response === null) {
@@ -2933,7 +3029,7 @@ async function dispatchTask(instance, task, cwd, plan) {
     return { task, success: false, error: message };
   }
 }
-function buildPrompt(task, cwd) {
+function buildPrompt(task, cwd, worktreeRoot) {
   return [
     `You are completing a task from a markdown task file.`,
     ``,
@@ -2945,10 +3041,11 @@ function buildPrompt(task, cwd) {
     `- Complete ONLY this specific task \u2014 do not work on other tasks.`,
     `- Make the minimal, correct changes needed.`,
     buildCommitInstruction(task.text),
+    ...buildWorktreeIsolation(worktreeRoot),
     `- When finished, confirm by saying "Task complete."`
   ].join("\n");
 }
-function buildPlannedPrompt(task, cwd, plan) {
+function buildPlannedPrompt(task, cwd, plan, worktreeRoot) {
   return [
     `You are an **executor agent** completing a task that has been pre-planned by a planner agent.`,
     `The planner has already explored the codebase and produced detailed instructions below.`,
@@ -2973,6 +3070,7 @@ function buildPlannedPrompt(task, cwd, plan) {
     `- Do NOT re-plan, question, or revise the plan. Trust it as given and execute it faithfully.`,
     `- Do NOT search for additional context using grep, find, or similar tools unless the plan explicitly instructs you to.`,
     buildCommitInstruction(task.text),
+    ...buildWorktreeIsolation(worktreeRoot),
     `- When finished, confirm by saying "Task complete."`
   ].join("\n");
 }
@@ -2985,6 +3083,12 @@ function buildCommitInstruction(taskText) {
   }
   return `- Do NOT commit changes \u2014 the orchestrator handles commits.`;
 }
+function buildWorktreeIsolation(worktreeRoot) {
+  if (!worktreeRoot) return [];
+  return [
+    `- **Worktree isolation:** You are operating inside a git worktree at \`${worktreeRoot}\`. You MUST NOT read, write, or execute commands that access files outside this directory. All file paths must resolve within \`${worktreeRoot}\`.`
+  ];
+}
 
 // src/agents/executor.ts
 init_logger();
@@ -2996,27 +3100,18 @@ async function boot7(opts) {
   return {
     name: "executor",
     async execute(input2) {
-      const { task, cwd, plan } = input2;
+      const { task, cwd, plan, worktreeRoot } = input2;
       const startTime = Date.now();
       try {
-        const result = await dispatchTask(provider, task, cwd, plan ?? void 0);
+        const result = await dispatchTask(provider, task, cwd, plan ?? void 0, worktreeRoot);
         if (result.success) {
           await markTaskComplete(task);
+          return { data: { dispatchResult: result }, success: true, durationMs: Date.now() - startTime };
         }
-        return {
-          dispatchResult: result,
-          success: result.success,
-          error: result.error,
-          elapsedMs: Date.now() - startTime
-        };
+        return { data: null, success: false, error: result.error, durationMs: Date.now() - startTime };
       } catch (err) {
         const message = log.extractMessage(err);
-        return {
-          dispatchResult: { task, success: false, error: message },
-          success: false,
-          error: message,
-          elapsedMs: Date.now() - startTime
-        };
+        return { data: null, success: false, error: message, durationMs: Date.now() - startTime };
       }
     },
     async cleanup() {
@@ -3027,7 +3122,7 @@ async function boot7(opts) {
 // src/agents/commit.ts
 init_logger();
 import { mkdir as mkdir5, writeFile as writeFile6 } from "fs/promises";
-import { join as join7 } from "path";
+import { join as join7, resolve as resolve2 } from "path";
 import { randomUUID as randomUUID4 } from "crypto";
 async function boot8(opts) {
   const { provider } = opts;
@@ -3040,7 +3135,8 @@ async function boot8(opts) {
     name: "commit",
     async generate(genOpts) {
       try {
-        const tmpDir = join7(genOpts.cwd, ".dispatch", "tmp");
+        const resolvedCwd = resolve2(genOpts.cwd);
+        const tmpDir = join7(resolvedCwd, ".dispatch", "tmp");
         await mkdir5(tmpDir, { recursive: true });
         const tmpFilename = `commit-${randomUUID4()}.md`;
         const tmpPath = join7(tmpDir, tmpFilename);
@@ -3220,6 +3316,7 @@ init_cleanup();
 import { join as join8, basename } from "path";
 import { execFile as execFile7 } from "child_process";
 import { promisify as promisify7 } from "util";
+import { randomUUID as randomUUID5 } from "crypto";
 init_logger();
 var exec7 = promisify7(execFile7);
 var WORKTREE_DIR = ".dispatch/worktrees";
@@ -3230,13 +3327,16 @@ async function git2(args, cwd) {
 function worktreeName(issueFilename) {
   const base = basename(issueFilename);
   const withoutExt = base.replace(/\.md$/i, "");
-  return slugify(withoutExt);
+  const match = withoutExt.match(/^(\d+)/);
+  return match ? `issue-${match[1]}` : slugify(withoutExt);
 }
-async function createWorktree(repoRoot, issueFilename, branchName) {
+async function createWorktree(repoRoot, issueFilename, branchName, startPoint) {
   const name = worktreeName(issueFilename);
   const worktreePath = join8(repoRoot, WORKTREE_DIR, name);
   try {
-    await git2(["worktree", "add", worktreePath, "-b", branchName], repoRoot);
+    const args = ["worktree", "add", worktreePath, "-b", branchName];
+    if (startPoint) args.push(startPoint);
+    await git2(args, repoRoot);
     log.debug(`Created worktree at ${worktreePath} on branch ${branchName}`);
   } catch (err) {
     const message = log.extractMessage(err);
@@ -3268,6 +3368,11 @@ async function removeWorktree(repoRoot, issueFilename) {
     log.warn(`Could not prune worktrees: ${log.formatErrorChain(err)}`);
   }
 }
+function generateFeatureBranchName() {
+  const uuid = randomUUID5();
+  const octet = uuid.split("-")[0];
+  return `dispatch/feature-${octet}`;
+}
 
 // src/tui.ts
 import chalk6 from "chalk";
@@ -3675,48 +3780,50 @@ async function buildPrTitle(issueTitle, defaultBranch, cwd) {
   }
   return `${commits[commits.length - 1]} (+${commits.length - 1} more)`;
 }
-
-// src/helpers/timeout.ts
-var TimeoutError = class extends Error {
-  /** Optional label identifying the operation that timed out. */
-  label;
-  constructor(ms, label) {
-    const suffix = label ? ` [${label}]` : "";
-    super(`Timed out after ${ms}ms${suffix}`);
-    this.name = "TimeoutError";
-    this.label = label;
+function buildFeaturePrTitle(featureBranchName, issues) {
+  if (issues.length === 1) {
+    return issues[0].title;
   }
-};
-function withTimeout(promise, ms, label) {
-  const p = new Promise((resolve2, reject) => {
-    let settled = false;
-    const timer = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      reject(new TimeoutError(ms, label));
-    }, ms);
-    promise.then(
-      (value) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        resolve2(value);
-      },
-      (err) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        reject(err);
-      }
-    );
-  });
-  p.catch(() => {
+  const issueRefs = issues.map((d) => `#${d.number}`).join(", ");
+  return `feat: ${featureBranchName} (${issueRefs})`;
+}
+function buildFeaturePrBody(issues, tasks, results, datasourceName) {
+  const sections = [];
+  sections.push("## Issues\n");
+  for (const issue of issues) {
+    sections.push(`- #${issue.number}: ${issue.title}`);
+  }
+  sections.push("");
+  const taskResults = new Map(results.map((r) => [r.task, r]));
+  const completedTasks = tasks.filter((t) => taskResults.get(t)?.success);
+  const failedTasks = tasks.filter((t) => {
+    const r = taskResults.get(t);
+    return r && !r.success;
   });
-  return p;
+  if (completedTasks.length > 0 || failedTasks.length > 0) {
+    sections.push("## Tasks\n");
+    for (const task of completedTasks) {
+      sections.push(`- [x] ${task.text}`);
+    }
+    for (const task of failedTasks) {
+      sections.push(`- [ ] ${task.text}`);
+    }
+    sections.push("");
+  }
+  for (const issue of issues) {
+    if (datasourceName === "github") {
+      sections.push(`Closes #${issue.number}`);
+    } else if (datasourceName === "azdevops") {
+      sections.push(`Resolves AB#${issue.number}`);
+    }
+  }
+  return sections.join("\n");
 }
 
 // src/orchestrator/dispatch-pipeline.ts
+init_timeout();
 import chalk7 from "chalk";
+var exec9 = promisify9(execFile9);
 var DEFAULT_PLAN_TIMEOUT_MIN = 10;
 var DEFAULT_PLAN_RETRIES = 1;
 async function runDispatchPipeline(opts, cwd) {
@@ -3728,6 +3835,7 @@ async function runDispatchPipeline(opts, cwd) {
     noPlan,
     noBranch,
     noWorktree,
+    feature,
     provider = "opencode",
     model,
     source,
@@ -3820,7 +3928,7 @@ async function runDispatchPipeline(opts, cwd) {
       list.push(task);
       tasksByFile.set(task.file, list);
     }
-    const useWorktrees = !noWorktree && !noBranch && tasksByFile.size > 1;
+    const useWorktrees = !noWorktree && (feature || !noBranch && tasksByFile.size > 1);
     tui.state.phase = "booting";
     if (verbose) log.info(`Booting ${provider} provider...`);
     if (serverUrl) {
@@ -3848,6 +3956,30 @@ async function runDispatchPipeline(opts, cwd) {
     let completed = 0;
     let failed = 0;
     const lifecycleOpts = { cwd };
+    let featureBranchName;
+    let featureDefaultBranch;
+    if (feature) {
+      try {
+        featureDefaultBranch = await datasource4.getDefaultBranch(lifecycleOpts);
+        await datasource4.switchBranch(featureDefaultBranch, lifecycleOpts);
+        featureBranchName = generateFeatureBranchName();
+        await datasource4.createAndSwitchBranch(featureBranchName, lifecycleOpts);
+        log.debug(`Created feature branch ${featureBranchName} from ${featureDefaultBranch}`);
+        registerCleanup(async () => {
+          try {
+            await datasource4.switchBranch(featureDefaultBranch, lifecycleOpts);
+          } catch {
+          }
+        });
+        await datasource4.switchBranch(featureDefaultBranch, lifecycleOpts);
+        log.debug(`Switched back to ${featureDefaultBranch} for worktree creation`);
+      } catch (err) {
+        log.error(`Feature branch creation failed: ${log.extractMessage(err)}`);
+        tui.state.phase = "done";
+        tui.stop();
+        return { total: allTasks.length, completed: 0, failed: allTasks.length, skipped: 0, results: [] };
+      }
+    }
     let username = "";
     try {
       username = await datasource4.getUsername(lifecycleOpts);
@@ -3862,10 +3994,10 @@ async function runDispatchPipeline(opts, cwd) {
       let issueCwd = cwd;
       if (!noBranch && details) {
         try {
-          defaultBranch = await datasource4.getDefaultBranch(lifecycleOpts);
+          defaultBranch = feature ? featureBranchName : await datasource4.getDefaultBranch(lifecycleOpts);
           branchName = datasource4.buildBranchName(details.number, details.title, username);
           if (useWorktrees) {
-            worktreePath = await createWorktree(cwd, file, branchName);
+            worktreePath = await createWorktree(cwd, file, branchName, ...feature && featureBranchName ? [featureBranchName] : []);
             registerCleanup(async () => {
               await removeWorktree(cwd, file);
             });
@@ -3876,7 +4008,7 @@ async function runDispatchPipeline(opts, cwd) {
               const tuiTask = tui.state.tasks.find((t) => t.task === task);
               if (tuiTask) tuiTask.worktree = wtName;
             }
-          } else {
+          } else if (datasource4.supportsGit()) {
             await datasource4.createAndSwitchBranch(branchName, lifecycleOpts);
             log.debug(`Switched to branch ${branchName}`);
           }
@@ -3895,6 +4027,7 @@ async function runDispatchPipeline(opts, cwd) {
           return;
         }
       }
+      const worktreeRoot = useWorktrees ? worktreePath : void 0;
       const issueLifecycleOpts = { cwd: issueCwd };
       let localInstance;
       let localPlanner;
@@ -3937,7 +4070,7 @@ async function runDispatchPipeline(opts, cwd) {
                 for (let attempt = 1; attempt <= maxPlanAttempts; attempt++) {
                   try {
                     planResult = await withTimeout(
-                      localPlanner.plan(task, fileContext, issueCwd),
+                      localPlanner.plan(task, fileContext, issueCwd, worktreeRoot),
                       planTimeoutMs,
                       "planner.plan()"
                     );
@@ -3952,9 +4085,10 @@ async function runDispatchPipeline(opts, cwd) {
                       }
                     } else {
                       planResult = {
-                        prompt: "",
+                        data: null,
                         success: false,
-                        error: log.extractMessage(err)
+                        error: log.extractMessage(err),
+                        durationMs: 0
                       };
                       break;
                     }
@@ -3963,9 +4097,10 @@ async function runDispatchPipeline(opts, cwd) {
                 if (!planResult) {
                   const timeoutMin = planTimeout ?? 10;
                   planResult = {
-                    prompt: "",
+                    data: null,
                     success: false,
-                    error: `Planning timed out after ${timeoutMin}m (${maxPlanAttempts} attempts)`
+                    error: `Planning timed out after ${timeoutMin}m (${maxPlanAttempts} attempts)`,
+                    durationMs: 0
                   };
                 }
                 if (!planResult.success) {
@@ -3976,7 +4111,7 @@ async function runDispatchPipeline(opts, cwd) {
                   failed++;
                   return { task, success: false, error: tuiTask.error };
                 }
-                plan = planResult.prompt;
+                plan = planResult.data.prompt;
               }
               tuiTask.status = "running";
               if (verbose) log.info(`Task #${tui.state.tasks.indexOf(tuiTask) + 1}: executing \u2014 "${task.text}"`);
@@ -3986,7 +4121,8 @@ async function runDispatchPipeline(opts, cwd) {
                   const result = await localExecutor.execute({
                     task,
                     cwd: issueCwd,
-                    plan: plan ?? null
+                    plan: plan ?? null,
+                    worktreeRoot
                   });
                   if (!result.success) {
                     throw new Error(result.error ?? "Execution failed");
@@ -3996,10 +4132,10 @@ async function runDispatchPipeline(opts, cwd) {
                 execRetries,
                 { label: `executor "${task.text}"` }
               ).catch((err) => ({
-                dispatchResult: { task, success: false, error: log.extractMessage(err) },
+                data: null,
                 success: false,
                 error: log.extractMessage(err),
-                elapsedMs: 0
+                durationMs: 0
               }));
               if (execResult.success) {
                 try {
@@ -4025,7 +4161,12 @@ async function runDispatchPipeline(opts, cwd) {
                 if (verbose) log.error(`Task #${tui.state.tasks.indexOf(tuiTask) + 1}: failed \u2014 "${task.text}" (${elapsed(tuiTask.elapsed)})${tuiTask.error ? `: ${tuiTask.error}` : ""}`);
                 failed++;
               }
-              return execResult.dispatchResult;
+              const dispatchResult = execResult.success ? execResult.data.dispatchResult : {
+                task,
+                success: false,
+                error: execResult.error ?? "Executor failed without returning a dispatch result."
+              };
+              return dispatchResult;
             })
           );
           issueResults.push(...batchResults);
@@ -4035,7 +4176,7 @@ async function runDispatchPipeline(opts, cwd) {
         }
       }
       results.push(...issueResults);
-      if (!noBranch && branchName && defaultBranch && details) {
+      if (!noBranch && branchName && defaultBranch && details && datasource4.supportsGit()) {
         try {
           await datasource4.commitAllChanges(
             `chore: stage uncommitted changes for issue #${details.number}`,
@@ -4047,7 +4188,7 @@ async function runDispatchPipeline(opts, cwd) {
         }
       }
       let commitAgentResult;
-      if (!noBranch && branchName && defaultBranch && details) {
+      if (!noBranch && branchName && defaultBranch && details && datasource4.supportsGit()) {
         try {
           const branchDiff = await getBranchDiff(defaultBranch, issueCwd);
           if (branchDiff) {
@@ -4055,7 +4196,8 @@ async function runDispatchPipeline(opts, cwd) {
               branchDiff,
               issue: details,
               taskResults: issueResults,
-              cwd: issueCwd
+              cwd: issueCwd,
+              worktreeRoot
             });
             if (result.success) {
               commitAgentResult = result;
@@ -4074,47 +4216,97 @@ async function runDispatchPipeline(opts, cwd) {
         }
       }
       if (!noBranch && branchName && defaultBranch && details) {
-        try {
-          await datasource4.pushBranch(branchName, issueLifecycleOpts);
-          log.debug(`Pushed branch ${branchName}`);
-        } catch (err) {
-          log.warn(`Could not push branch ${branchName}: ${log.formatErrorChain(err)}`);
-        }
-        try {
-          const prTitle = commitAgentResult?.prTitle || await buildPrTitle(details.title, defaultBranch, issueLifecycleOpts.cwd);
-          const prBody = commitAgentResult?.prDescription || await buildPrBody(
-            details,
-            fileTasks,
-            issueResults,
-            defaultBranch,
-            datasource4.name,
-            issueLifecycleOpts.cwd
-          );
-          const prUrl = await datasource4.createPullRequest(
-            branchName,
-            details.number,
-            prTitle,
-            prBody,
-            issueLifecycleOpts
-          );
-          if (prUrl) {
-            log.success(`Created PR for issue #${details.number}: ${prUrl}`);
+        if (feature && featureBranchName) {
+          if (worktreePath) {
+            try {
+              await removeWorktree(cwd, file);
+            } catch (err) {
+              log.warn(`Could not remove worktree for issue #${details.number}: ${log.formatErrorChain(err)}`);
+            }
           }
-        } catch (err) {
-          log.warn(`Could not create PR for issue #${details.number}: ${log.formatErrorChain(err)}`);
-        }
-        if (useWorktrees && worktreePath) {
           try {
-            await removeWorktree(cwd, file);
+            await datasource4.switchBranch(featureBranchName, lifecycleOpts);
+            await exec9("git", ["merge", branchName, "--no-ff", "-m", `merge: issue #${details.number}`], { cwd });
+            log.debug(`Merged ${branchName} into ${featureBranchName}`);
           } catch (err) {
-            log.warn(`Could not remove worktree for issue #${details.number}: ${log.formatErrorChain(err)}`);
+            const mergeError = `Could not merge ${branchName} into feature branch: ${log.formatErrorChain(err)}`;
+            log.warn(mergeError);
+            try {
+              await exec9("git", ["merge", "--abort"], { cwd });
+            } catch {
+            }
+            for (const task of fileTasks) {
+              const tuiTask = tui.state.tasks.find((t) => t.task === task);
+              if (tuiTask) {
+                tuiTask.status = "failed";
+                tuiTask.error = mergeError;
+              }
+              const existingResult = results.find((r) => r.task === task);
+              if (existingResult) {
+                existingResult.success = false;
+                existingResult.error = mergeError;
+              }
+            }
+            return;
           }
-        } else if (!useWorktrees) {
           try {
-            await datasource4.switchBranch(defaultBranch, lifecycleOpts);
-            log.debug(`Switched back to ${defaultBranch}`);
+            await exec9("git", ["branch", "-d", branchName], { cwd });
+            log.debug(`Deleted local branch ${branchName}`);
           } catch (err) {
-            log.warn(`Could not switch back to ${defaultBranch}: ${log.formatErrorChain(err)}`);
+            log.warn(`Could not delete local branch ${branchName}: ${log.formatErrorChain(err)}`);
+          }
+          try {
+            await datasource4.switchBranch(featureDefaultBranch, lifecycleOpts);
+          } catch (err) {
+            log.warn(`Could not switch back to ${featureDefaultBranch}: ${log.formatErrorChain(err)}`);
+          }
+        } else {
+          if (datasource4.supportsGit()) {
+            try {
+              await datasource4.pushBranch(branchName, issueLifecycleOpts);
+              log.debug(`Pushed branch ${branchName}`);
+            } catch (err) {
+              log.warn(`Could not push branch ${branchName}: ${log.formatErrorChain(err)}`);
+            }
+          }
+          if (datasource4.supportsGit()) {
+            try {
+              const prTitle = commitAgentResult?.prTitle || await buildPrTitle(details.title, defaultBranch, issueLifecycleOpts.cwd);
+              const prBody = commitAgentResult?.prDescription || await buildPrBody(
+                details,
+                fileTasks,
+                issueResults,
+                defaultBranch,
+                datasource4.name,
+                issueLifecycleOpts.cwd
+              );
+              const prUrl = await datasource4.createPullRequest(
+                branchName,
+                details.number,
+                prTitle,
+                prBody,
+                issueLifecycleOpts
+              );
+              if (prUrl) {
+                log.success(`Created PR for issue #${details.number}: ${prUrl}`);
+              }
+            } catch (err) {
+              log.warn(`Could not create PR for issue #${details.number}: ${log.formatErrorChain(err)}`);
+            }
+          }
+          if (useWorktrees && worktreePath) {
+            try {
+              await removeWorktree(cwd, file);
+            } catch (err) {
+              log.warn(`Could not remove worktree for issue #${details.number}: ${log.formatErrorChain(err)}`);
+            }
+          } else if (!useWorktrees && datasource4.supportsGit()) {
+            try {
+              await datasource4.switchBranch(defaultBranch, lifecycleOpts);
+              log.debug(`Switched back to ${defaultBranch}`);
+            } catch (err) {
+              log.warn(`Could not switch back to ${defaultBranch}: ${log.formatErrorChain(err)}`);
+            }
           }
         }
       }
@@ -4124,7 +4316,7 @@ async function runDispatchPipeline(opts, cwd) {
         await localInstance.cleanup();
       }
     };
-    if (useWorktrees) {
+    if (useWorktrees && !feature) {
       await Promise.all(
         Array.from(tasksByFile).map(
           ([file, fileTasks]) => processIssueFile(file, fileTasks)
@@ -4135,6 +4327,43 @@ async function runDispatchPipeline(opts, cwd) {
         await processIssueFile(file, fileTasks);
       }
     }
+    if (feature && featureBranchName && featureDefaultBranch) {
+      try {
+        await datasource4.switchBranch(featureBranchName, lifecycleOpts);
+        log.debug(`Switched to feature branch ${featureBranchName}`);
+      } catch (err) {
+        log.warn(`Could not switch to feature branch: ${log.formatErrorChain(err)}`);
+      }
+      try {
+        await datasource4.pushBranch(featureBranchName, lifecycleOpts);
+        log.debug(`Pushed feature branch ${featureBranchName}`);
+      } catch (err) {
+        log.warn(`Could not push feature branch: ${log.formatErrorChain(err)}`);
+      }
+      try {
+        const allIssueDetails = Array.from(issueDetailsByFile.values());
+        const prTitle = buildFeaturePrTitle(featureBranchName, allIssueDetails);
+        const prBody = buildFeaturePrBody(allIssueDetails, allTasks, results, source);
+        const primaryIssue = allIssueDetails[0]?.number ?? "";
+        const prUrl = await datasource4.createPullRequest(
+          featureBranchName,
+          primaryIssue,
+          prTitle,
+          prBody,
+          lifecycleOpts
+        );
+        if (prUrl) {
+          log.success(`Created feature PR: ${prUrl}`);
+        }
+      } catch (err) {
+        log.warn(`Could not create feature PR: ${log.formatErrorChain(err)}`);
+      }
+      try {
+        await datasource4.switchBranch(featureDefaultBranch, lifecycleOpts);
+      } catch (err) {
+        log.warn(`Could not switch back to ${featureDefaultBranch}: ${log.formatErrorChain(err)}`);
+      }
+    }
     try {
       await closeCompletedSpecIssues(taskFiles, results, cwd, source, org, project, workItemType);
     } catch (err) {
@@ -4233,12 +4462,17 @@ async function boot9(opts) {
       const modeFlags = [
         m.spec !== void 0 && "--spec",
         m.respec !== void 0 && "--respec",
-        m.fixTests && "--fix-tests"
+        m.fixTests && "--fix-tests",
+        m.feature && "--feature"
       ].filter(Boolean);
       if (modeFlags.length > 1) {
         log.error(`${modeFlags.join(" and ")} are mutually exclusive`);
         process.exit(1);
       }
+      if (m.feature && m.noBranch) {
+        log.error("--feature and --no-branch are mutually exclusive");
+        process.exit(1);
+      }
       if (m.fixTests && m.issueIds.length > 0) {
         log.error("--fix-tests cannot be combined with issue IDs");
         process.exit(1);
@@ -4320,7 +4554,8 @@ async function boot9(opts) {
         planTimeout: m.planTimeout,
         planRetries: m.planRetries,
         retries: m.retries,
-        force: m.force
+        force: m.force,
+        feature: m.feature
       });
     }
   };
@@ -4331,7 +4566,7 @@ async function boot9(opts) {
 init_logger();
 init_cleanup();
 init_providers();
-var MAX_CONCURRENCY = 64;
+var MAX_CONCURRENCY = CONFIG_BOUNDS.concurrency.max;
 var HELP = `
   dispatch \u2014 AI agent orchestration CLI
 
@@ -4350,8 +4585,9 @@ var HELP = `
     --no-plan              Skip the planner agent, dispatch directly
     --no-branch            Skip branch creation, push, and PR lifecycle
     --no-worktree          Skip git worktree isolation for parallel issues
+    --feature              Group issues into a single feature branch and PR
     --force              Ignore prior run state and re-run all tasks
-    --concurrency <n>      Max parallel dispatches (default: min(cpus, freeMB/500), max: 64)
+    --concurrency <n>      Max parallel dispatches (default: min(cpus, freeMB/500), max: ${MAX_CONCURRENCY})
     --provider <name>      Agent backend: ${PROVIDER_NAMES.join(", ")} (default: opencode)
     --server-url <url>     URL of a running provider server
     --plan-timeout <min>   Planning timeout in minutes (default: 10)
@@ -4433,6 +4669,9 @@ function parseArgs(argv) {
     } else if (arg === "--no-worktree") {
       args.noWorktree = true;
       explicitFlags.add("noWorktree");
+    } else if (arg === "--feature") {
+      args.feature = true;
+      explicitFlags.add("feature");
     } else if (arg === "--force") {
       args.force = true;
       explicitFlags.add("force");
@@ -4483,7 +4722,7 @@ function parseArgs(argv) {
       explicitFlags.add("project");
     } else if (arg === "--output-dir") {
       i++;
-      args.outputDir = resolve(argv[i]);
+      args.outputDir = resolve3(argv[i]);
       explicitFlags.add("outputDir");
     } else if (arg === "--concurrency") {
       i++;
@@ -4514,10 +4753,14 @@ function parseArgs(argv) {
     } else if (arg === "--plan-timeout") {
       i++;
       const val = parseFloat(argv[i]);
-      if (isNaN(val) || val <= 0) {
+      if (isNaN(val) || val < CONFIG_BOUNDS.planTimeout.min) {
         log.error("--plan-timeout must be a positive number (minutes)");
         process.exit(1);
       }
+      if (val > CONFIG_BOUNDS.planTimeout.max) {
+        log.error(`--plan-timeout must not exceed ${CONFIG_BOUNDS.planTimeout.max}`);
+        process.exit(1);
+      }
       args.planTimeout = val;
       explicitFlags.add("planTimeout");
     } else if (arg === "--retries") {
@@ -4549,7 +4792,7 @@ function parseArgs(argv) {
       explicitFlags.add("testTimeout");
     } else if (arg === "--cwd") {
       i++;
-      args.cwd = resolve(argv[i]);
+      args.cwd = resolve3(argv[i]);
       explicitFlags.add("cwd");
     } else if (!arg.startsWith("-")) {
       args.issueIds.push(arg);
@@ -4567,7 +4810,7 @@ async function main() {
     let cwd = process.cwd();
     for (let i = 1; i < rawArgv.length; i++) {
       if (rawArgv[i] === "--cwd" && i + 1 < rawArgv.length) {
-        cwd = resolve(rawArgv[i + 1]);
+        cwd = resolve3(rawArgv[i + 1]);
         break;
       }
     }
@@ -4592,7 +4835,7 @@ async function main() {
     process.exit(0);
   }
   if (args.version) {
-    console.log(`dispatch v${"0.0.1"}`);
+    console.log(`dispatch v${"1.2.1"}`);
     process.exit(0);
   }
   const orchestrator = await boot9({ cwd: args.cwd });