ralphctl 0.1.0 → 0.1.2

package/dist/chunk-LOR7QBXX.mjs

@@ -0,0 +1,3683 @@
+#!/usr/bin/env node
+import {
+  escapableSelect
+} from "./chunk-NTWO2LXB.mjs";
+import {
+  IssueFetchError,
+  allRequirementsApproved,
+  fetchIssueFromUrl,
+  formatIssueContext,
+  formatTicketDisplay,
+  formatTicketId,
+  getPendingRequirements,
+  groupTicketsByProject,
+  listTickets
+} from "./chunk-MNMQC36F.mjs";
+import {
+  EXIT_ALL_BLOCKED,
+  EXIT_ERROR,
+  EXIT_INTERRUPTED,
+  EXIT_NO_TASKS,
+  EXIT_SUCCESS,
+  exitWithCode
+} from "./chunk-7TG3EAQ2.mjs";
+import {
+  ProjectNotFoundError,
+  getProject,
+  listProjects
+} from "./chunk-WGHJI3OI.mjs";
+import {
+  SprintNotFoundError,
+  SprintStatusError,
+  activateSprint,
+  assertSprintStatus,
+  closeSprint,
+  generateUuid8,
+  getAiProvider,
+  getProgress,
+  getSprint,
+  listSprints,
+  logProgress,
+  resolveSprintId,
+  saveSprint,
+  setAiProvider,
+  summarizeProgressForContext,
+  withFileLock
+} from "./chunk-EKMZZRWI.mjs";
+import {
+  ImportTasksSchema,
+  RefinedRequirementsSchema,
+  TasksSchema,
+  assertSafeCwd,
+  ensureDir,
+  fileExists,
+  getPlanningDir,
+  getProgressFilePath,
+  getRefinementDir,
+  getSchemaPath,
+  getSprintDir,
+  getTasksFilePath,
+  readValidatedJson,
+  writeValidatedJson
+} from "./chunk-6PYTKGB5.mjs";
+import {
+  colors,
+  createSpinner,
+  emoji,
+  error,
+  field,
+  fieldMultiline,
+  formatSprintStatus,
+  formatTaskStatus,
+  highlight,
+  icons,
+  info,
+  log,
+  muted,
+  printHeader,
+  printSeparator,
+  progressBar,
+  renderCard,
+  renderTable,
+  showError,
+  showInfo,
+  showNextStep,
+  showRandomQuote,
+  showSuccess,
+  showTip,
+  showWarning,
+  success,
+  terminalBell,
+  warning
+} from "./chunk-QBXHAXHI.mjs";
+
+// src/commands/sprint/refine.ts
+import { mkdir, readFile } from "fs/promises";
+import { join as join4 } from "path";
+import { confirm } from "@inquirer/prompts";
+
+// src/ai/prompts/index.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function getPromptDir() {
+  const bundled = join(__dirname, "prompts");
+  if (existsSync(bundled)) return bundled;
+  return __dirname;
+}
+var promptDir = getPromptDir();
+function loadTemplate(name) {
+  return readFileSync(join(promptDir, `${name}.md`), "utf-8");
+}
+function buildPlanPrompt(template, context, schema) {
+  const common = loadTemplate("plan-common");
+  return template.replace("{{COMMON}}", common).replace("{{CONTEXT}}", context).replace("{{SCHEMA}}", schema);
+}
+function buildInteractivePrompt(context, outputFile, schema) {
+  const template = loadTemplate("plan-interactive");
+  return buildPlanPrompt(template, context, schema).replace("{{OUTPUT_FILE}}", outputFile);
+}
+function buildAutoPrompt(context, schema) {
+  const template = loadTemplate("plan-auto");
+  return buildPlanPrompt(template, context, schema);
+}
+function buildTaskExecutionPrompt(progressFilePath, noCommit, contextFileName) {
+  const template = loadTemplate("task-execution");
+  const commitStep = noCommit ? "" : "\n> **Before continuing:** Create a git commit with a descriptive message for the changes made.\n";
+  const commitConstraint = noCommit ? "" : "- **Must commit** \u2014 Create a git commit before signaling completion.\n";
+  return template.replace("{{PROGRESS_FILE}}", progressFilePath).replace("{{COMMIT_STEP}}", commitStep).replace("{{COMMIT_CONSTRAINT}}", commitConstraint).replaceAll("{{CONTEXT_FILE}}", contextFileName);
+}
+function buildTicketRefinePrompt(ticketContent, outputFile, schema, issueContext = "") {
+  const template = loadTemplate("ticket-refine");
+  return template.replace("{{TICKET}}", ticketContent).replace("{{OUTPUT_FILE}}", outputFile).replace("{{SCHEMA}}", schema).replace("{{ISSUE_CONTEXT}}", issueContext);
+}
+function buildIdeatePrompt(ideaTitle, ideaDescription, projectName, repositories, outputFile, schema) {
+  const template = loadTemplate("ideate");
+  const common = loadTemplate("plan-common");
+  return template.replace("{{IDEA_TITLE}}", ideaTitle).replace("{{IDEA_DESCRIPTION}}", ideaDescription).replace("{{PROJECT_NAME}}", projectName).replace("{{REPOSITORIES}}", repositories).replace("{{OUTPUT_FILE}}", outputFile).replace("{{SCHEMA}}", schema).replace("{{COMMON}}", common);
+}
+function buildIdeateAutoPrompt(ideaTitle, ideaDescription, projectName, repositories, schema) {
+  const template = loadTemplate("ideate-auto");
+  const common = loadTemplate("plan-common");
+  return template.replace("{{IDEA_TITLE}}", ideaTitle).replace("{{IDEA_DESCRIPTION}}", ideaDescription).replace("{{PROJECT_NAME}}", projectName).replace("{{REPOSITORIES}}", repositories).replace("{{SCHEMA}}", schema).replace("{{COMMON}}", common);
+}
+
+// src/utils/requirements-export.ts
+import { writeFile } from "fs/promises";
+import { dirname as dirname2 } from "path";
+function formatRequirementsMarkdown(sprint) {
+  const lines = [];
+  lines.push(`# Sprint Requirements: ${sprint.name}`);
+  lines.push("");
+  lines.push(`Sprint ID: ${sprint.id}`);
+  lines.push(`Generated: ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  lines.push(`Status: ${sprint.status}`);
+  if (sprint.tickets.length === 0) {
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push("_No tickets in this sprint._");
+    return lines.join("\n") + "\n";
+  }
+  for (const ticket of sprint.tickets) {
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push(formatTicketSection(ticket));
+  }
+  return lines.join("\n") + "\n";
+}
+function formatTicketSection(ticket) {
+  const lines = [];
+  lines.push(`## ${ticket.projectName} - ${ticket.title}`);
+  lines.push("");
+  lines.push(`**Ticket ID:** ${ticket.id}`);
+  lines.push(`**Status:** ${ticket.requirementStatus}`);
+  if (ticket.link) {
+    lines.push(`**Link:** ${ticket.link}`);
+  }
+  lines.push("");
+  lines.push("### Requirements");
+  lines.push("");
+  lines.push(ticket.requirements ?? "_No requirements defined_");
+  return lines.join("\n");
+}
+async function exportRequirementsToMarkdown(sprint, outputPath) {
+  const content = formatRequirementsMarkdown(sprint);
+  await ensureDir(dirname2(outputPath));
+  await writeFile(outputPath, content, "utf-8");
+}
+
+// src/utils/provider.ts
+import { select } from "@inquirer/prompts";
+async function resolveProvider() {
+  const stored = await getAiProvider();
+  if (stored) return stored;
+  const choice = await select({
+    message: `${emoji.donut} Which AI buddy should help with my homework?`,
+    choices: [
+      { name: "Claude Code", value: "claude" },
+      { name: "GitHub Copilot", value: "copilot" }
+    ]
+  });
+  await setAiProvider(choice);
+  return choice;
+}
+function providerDisplayName(provider) {
+  return provider === "claude" ? "Claude" : "Copilot";
+}
+
+// src/commands/ticket/refine-utils.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import { join as join3 } from "path";
+
+// src/ai/session.ts
+import { spawn, spawnSync } from "child_process";
+
+// src/ai/process-manager.ts
+var GRACEFUL_SHUTDOWN_TIMEOUT_MS = 5e3;
+var FORCE_QUIT_WINDOW_MS = 5e3;
+var ProcessManager = class _ProcessManager {
+  static instance = null;
+  /** All active AI child processes */
+  children = /* @__PURE__ */ new Set();
+  /** Cleanup callbacks (for stopping spinners, removing temp files) */
+  cleanupCallbacks = /* @__PURE__ */ new Set();
+  /** Whether we're currently shutting down */
+  exiting = false;
+  /** Whether signal handlers have been installed */
+  handlersInstalled = false;
+  /** Timestamp of first SIGINT (for double-signal detection) */
+  firstSigintAt = null;
+  constructor() {
+  }
+  /**
+   * Get the singleton instance.
+   */
+  static getInstance() {
+    _ProcessManager.instance ??= new _ProcessManager();
+    return _ProcessManager.instance;
+  }
+  /**
+   * Reset the singleton for testing.
+   * @internal
+   */
+  static resetForTesting() {
+    if (_ProcessManager.instance) {
+      _ProcessManager.instance.dispose();
+      _ProcessManager.instance = null;
+    }
+  }
+  /**
+   * Register a child process for tracking.
+   * Automatically installs signal handlers on first registration.
+   * Throws an error if called during shutdown.
+   *
+   * @throws Error if called during shutdown
+   */
+  registerChild(child) {
+    if (this.exiting) {
+      throw new Error("Cannot register child process during shutdown");
+    }
+    this.children.add(child);
+    child.once("close", () => {
+      this.children.delete(child);
+    });
+    if (!this.handlersInstalled) {
+      this.installSignalHandlers();
+      this.handlersInstalled = true;
+    }
+  }
+  /**
+   * Eagerly install signal handlers without requiring a child registration.
+   * Call this at the top of execution loops so Ctrl+C works even before
+   * the first AI process is spawned (e.g. while the spinner is visible).
+   * Idempotent — safe to call multiple times.
+   */
+  ensureHandlers() {
+    if (!this.handlersInstalled) {
+      this.installSignalHandlers();
+      this.handlersInstalled = true;
+    }
+  }
+  /**
+   * Check if a shutdown is in progress.
+   * Used by execution loops to break immediately on Ctrl+C.
+   */
+  isShuttingDown() {
+    return this.exiting;
+  }
+  /**
+   * Manually unregister a child process.
+   * Normally not needed - children auto-unregister via event listeners.
+   */
+  unregisterChild(child) {
+    this.children.delete(child);
+  }
+  /**
+   * Register a cleanup callback (for spinners, temp files, etc.).
+   * Returns a deregister function.
+   */
+  registerCleanup(callback) {
+    this.cleanupCallbacks.add(callback);
+    return () => {
+      this.cleanupCallbacks.delete(callback);
+    };
+  }
+  /**
+   * Kill all tracked child processes with the given signal.
+   * Catches errors (ESRCH = already dead, EPERM = permission denied).
+   */
+  killAll(signal) {
+    for (const child of this.children) {
+      try {
+        child.kill(signal);
+      } catch (err) {
+        const error2 = err;
+        if (error2.code === "ESRCH") {
+          this.children.delete(child);
+        } else if (error2.code === "EPERM") {
+          console.warn(`Warning: Permission denied killing process ${String(child.pid)}`);
+        } else {
+          console.error(`Error killing process ${String(child.pid)}:`, error2.message);
+        }
+      }
+    }
+  }
+  /**
+   * Graceful shutdown sequence:
+   * 1. Run all cleanup callbacks (stop spinners)
+   * 2. Send SIGINT to all children (what AI CLI processes expect)
+   * 3. Wait up to 5 seconds for children to exit
+   * 4. Send SIGKILL to any remaining children (force)
+   * 5. Exit with code 130 (SIGINT) or 1 (force-quit)
+   *
+   * Double Ctrl+C: immediate SIGKILL + exit(1)
+   */
+  async shutdown(signal) {
+    if (signal === "SIGINT" && this.firstSigintAt) {
+      const now = Date.now();
+      if (now - this.firstSigintAt < FORCE_QUIT_WINDOW_MS) {
+        console.log("\n\nForce quit (double signal) \u2014 killing all processes immediately...");
+        this.killAll("SIGKILL");
+        process.exit(1);
+        return;
+      }
+    }
+    if (this.exiting) {
+      return;
+    }
+    this.exiting = true;
+    if (signal === "SIGINT") {
+      this.firstSigintAt = Date.now();
+    }
+    console.log("\n\nShutting down gracefully... (press Ctrl+C again to force-quit)");
+    for (const callback of this.cleanupCallbacks) {
+      try {
+        callback();
+      } catch (err) {
+        const error2 = err;
+        console.error("Error in cleanup callback:", error2.message);
+      }
+    }
+    this.cleanupCallbacks.clear();
+    this.killAll("SIGINT");
+    const waitStart = Date.now();
+    while (this.children.size > 0 && Date.now() - waitStart < GRACEFUL_SHUTDOWN_TIMEOUT_MS) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (this.children.size > 0) {
+      console.log(`Force-killing ${String(this.children.size)} remaining process(es)...`);
+      this.killAll("SIGKILL");
+    }
+    process.exit(signal === "SIGINT" ? EXIT_INTERRUPTED : 1);
+  }
+  /**
+   * Clean up all resources (for testing).
+   * @internal
+   */
+  dispose() {
+    this.children.clear();
+    this.cleanupCallbacks.clear();
+    this.exiting = false;
+    this.handlersInstalled = false;
+    this.firstSigintAt = null;
+  }
+  /**
+   * Install signal handlers for SIGINT and SIGTERM.
+   * Uses process.on() (persistent) not process.once() (one-shot).
+   */
+  installSignalHandlers() {
+    process.on("SIGINT", () => {
+      void this.shutdown("SIGINT");
+    });
+    process.on("SIGTERM", () => {
+      void this.shutdown("SIGTERM");
+    });
+  }
+};
+
+// src/providers/claude.ts
+var claudeAdapter = {
+  name: "claude",
+  displayName: "Claude",
+  binary: "claude",
+  baseArgs: ["--permission-mode", "acceptEdits"],
+  experimental: false,
+  buildInteractiveArgs(prompt, extraArgs = []) {
+    return [...this.baseArgs, ...extraArgs, "--", prompt];
+  },
+  buildHeadlessArgs(extraArgs = []) {
+    return ["-p", "--output-format", "json", ...this.baseArgs, ...extraArgs];
+  },
+  parseJsonOutput(stdout) {
+    try {
+      const parsed = JSON.parse(stdout);
+      return {
+        result: parsed.result ?? stdout,
+        sessionId: parsed.session_id ?? null
+      };
+    } catch {
+      return { result: stdout, sessionId: null };
+    }
+  },
+  detectRateLimit(stderr) {
+    const patterns = [/rate.?limit/i, /\b429\b/, /too many requests/i, /overloaded/i, /\b529\b/];
+    const isRateLimited = patterns.some((p) => p.test(stderr));
+    if (!isRateLimited) {
+      return { rateLimited: false, retryAfterMs: null };
+    }
+    const retryMatch = /retry.?after:?\s*(\d+)/i.exec(stderr);
+    const retryAfterMs = retryMatch?.[1] ? parseInt(retryMatch[1], 10) * 1e3 : null;
+    return { rateLimited: true, retryAfterMs };
+  },
+  getSpawnEnv() {
+    return { CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: "1" };
+  }
+};
+
+// src/providers/copilot.ts
+import { lstat, readdir, unlink } from "fs/promises";
+import { join as join2 } from "path";
+var copilotAdapter = {
+  name: "copilot",
+  displayName: "Copilot",
+  binary: "copilot",
+  experimental: true,
+  baseArgs: ["--allow-all-tools"],
+  buildInteractiveArgs(prompt, extraArgs = []) {
+    return [...this.baseArgs, ...extraArgs, "-i", prompt];
+  },
+  buildHeadlessArgs(extraArgs = []) {
+    return ["-p", "-s", "--autopilot", "--no-ask-user", "--share", ...this.baseArgs, ...extraArgs];
+  },
+  parseJsonOutput(stdout) {
+    return { result: stdout.trim(), sessionId: null };
+  },
+  async extractSessionId(cwd) {
+    try {
+      const files = await readdir(cwd);
+      const shareFile = files.find((f) => /^copilot-session-[a-zA-Z0-9_][a-zA-Z0-9_-]*\.md$/.test(f));
+      if (!shareFile) return null;
+      const match = /^copilot-session-([a-zA-Z0-9_][a-zA-Z0-9_-]{0,127})\.md$/.exec(shareFile);
+      if (!match?.[1]) return null;
+      const filePath = join2(cwd, shareFile);
+      const stat = await lstat(filePath).catch(() => null);
+      if (stat?.isFile()) {
+        await unlink(filePath).catch(() => {
+        });
+      }
+      return match[1];
+    } catch {
+      return null;
+    }
+  },
+  detectRateLimit(stderr) {
+    const patterns = [/rate.?limit/i, /\b429\b/, /too many requests/i, /overloaded/i, /\b529\b/];
+    const isRateLimited = patterns.some((p) => p.test(stderr));
+    if (!isRateLimited) {
+      return { rateLimited: false, retryAfterMs: null };
+    }
+    const retryMatch = /retry.?after:?\s*(\d+)/i.exec(stderr);
+    const retryAfterMs = retryMatch?.[1] ? parseInt(retryMatch[1], 10) * 1e3 : null;
+    return { rateLimited: true, retryAfterMs };
+  },
+  getSpawnEnv() {
+    return {};
+  }
+};
+
+// src/providers/index.ts
+function getProvider(provider) {
+  switch (provider) {
+    case "claude":
+      return claudeAdapter;
+    case "copilot":
+      return copilotAdapter;
+  }
+}
+async function getActiveProvider() {
+  const provider = await resolveProvider();
+  const adapter = getProvider(provider);
+  if (adapter.experimental) {
+    showWarning(`${adapter.displayName} provider is in public preview \u2014 some features may not work as expected.`);
+  }
+  return adapter;
+}
+
+// src/ai/session.ts
+var SpawnError = class extends Error {
+  stderr;
+  exitCode;
+  rateLimited;
+  retryAfterMs;
+  /** Session ID if available (for resume after rate limit) */
+  sessionId;
+  constructor(message, stderr, exitCode, sessionId, provider) {
+    super(message);
+    this.name = "SpawnError";
+    this.stderr = stderr;
+    this.exitCode = exitCode;
+    this.sessionId = sessionId ?? null;
+    const rl = provider ? provider.detectRateLimit(stderr) : detectRateLimitFallback(stderr);
+    this.rateLimited = rl.rateLimited;
+    this.retryAfterMs = rl.retryAfterMs;
+  }
+};
+function detectRateLimitFallback(stderr) {
+  const patterns = [/rate.?limit/i, /\b429\b/, /too many requests/i, /overloaded/i, /\b529\b/];
+  const isRateLimited = patterns.some((p) => p.test(stderr));
+  if (!isRateLimited) {
+    return { rateLimited: false, retryAfterMs: null };
+  }
+  const retryMatch = /retry.?after:?\s*(\d+)/i.exec(stderr);
+  const retryAfterMs = retryMatch?.[1] ? parseInt(retryMatch[1], 10) * 1e3 : null;
+  return { rateLimited: true, retryAfterMs };
+}
+function spawnInteractive(prompt, options, provider) {
+  assertSafeCwd(options.cwd);
+  const p = provider ?? {
+    binary: "claude",
+    baseArgs: ["--permission-mode", "acceptEdits"],
+    buildInteractiveArgs: (pr, extra = []) => [
+      ...["--permission-mode", "acceptEdits"],
+      ...extra,
+      "--",
+      pr
+    ]
+  };
+  const args = prompt ? p.buildInteractiveArgs(prompt, options.args ?? []) : [...p.baseArgs, ...options.args ?? []];
+  const env = options.env ? { ...process.env, ...options.env } : void 0;
+  const result = spawnSync(p.binary, args, {
+    cwd: options.cwd,
+    stdio: "inherit",
+    env
+  });
+  if (result.error) {
+    return { code: 1, error: `Failed to spawn ${p.binary} CLI: ${result.error.message}` };
+  }
+  return { code: result.status ?? 1 };
+}
+async function spawnHeadless(options, provider) {
+  const result = await spawnHeadlessRaw(options, provider);
+  return result.stdout;
+}
+async function spawnHeadlessRaw(options, provider) {
+  assertSafeCwd(options.cwd);
+  const p = provider ?? await getActiveProvider();
+  return new Promise((resolve, reject) => {
+    const allArgs = p.buildHeadlessArgs(options.args ?? []);
+    if (options.resumeSessionId) {
+      if (!/^[a-zA-Z0-9_][a-zA-Z0-9_-]{0,127}$/.test(options.resumeSessionId)) {
+        reject(new SpawnError("Invalid session ID format", "", 1, null, p));
+        return;
+      }
+      allArgs.push("--resume", options.resumeSessionId);
+    }
+    const child = spawn(p.binary, allArgs, {
+      cwd: options.cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: options.env ? { ...process.env, ...options.env } : void 0
+    });
+    const manager = ProcessManager.getInstance();
+    try {
+      manager.registerChild(child);
+    } catch {
+      reject(new SpawnError("Cannot spawn during shutdown", "", 1, null, p));
+      return;
+    }
+    const MAX_PROMPT_SIZE = 1e6;
+    if (options.prompt) {
+      if (options.prompt.length > MAX_PROMPT_SIZE) {
+        reject(new SpawnError("Prompt exceeds maximum size (1MB)", "", 1, null, p));
+        return;
+      }
+      child.stdin.write(options.prompt);
+    }
+    child.stdin.end();
+    let rawStdout = "";
+    let stderr = "";
+    child.stdout.on("data", (data) => {
+      rawStdout += data.toString();
+    });
+    child.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    child.on("close", (code) => {
+      void (async () => {
+        const exitCode = code ?? 1;
+        const { result, sessionId: parsedSessionId } = p.parseJsonOutput(rawStdout);
+        const sessionId = parsedSessionId ?? await p.extractSessionId?.(options.cwd) ?? null;
+        if (exitCode !== 0) {
+          reject(
+            new SpawnError(
+              `${p.displayName} CLI exited with code ${String(exitCode)}: ${stderr}`,
+              stderr,
+              exitCode,
+              sessionId,
+              p
+            )
+          );
+        } else {
+          resolve({ stdout: result, stderr, exitCode: 0, sessionId });
+        }
+      })().catch((err) => {
+        reject(new SpawnError(`Unexpected error in close handler: ${String(err)}`, "", 1, null, p));
+      });
+    });
+    child.on("error", (err) => {
+      reject(new SpawnError(`Failed to spawn ${p.binary} CLI: ${err.message}`, "", 1, null, p));
+    });
+  });
+}
+var DEFAULT_MAX_RETRIES = 5;
+var BASE_DELAY_MS = 2e3;
+var MAX_DELAY_MS = 12e4;
+var DEFAULT_TOTAL_TIMEOUT_MS = 6e5;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function jitter() {
+  return Math.floor(Math.random() * 1e3);
+}
+async function spawnWithRetry(options, retryOptions, provider) {
+  const p = provider ?? await getActiveProvider();
+  const maxRetries = retryOptions?.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const totalTimeoutMs = retryOptions?.totalTimeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS;
+  const startTime = Date.now();
+  let resumeSessionId = options.resumeSessionId;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const elapsed = Date.now() - startTime;
+    if (attempt > 0 && elapsed >= totalTimeoutMs) {
+      throw new SpawnError(`Total retry timeout exceeded (${String(totalTimeoutMs)}ms)`, "", 1, resumeSessionId, p);
+    }
+    try {
+      return await spawnHeadlessRaw({ ...options, resumeSessionId }, p);
+    } catch (err) {
+      if (!(err instanceof SpawnError) || !err.rateLimited) {
+        throw err;
+      }
+      if (err.sessionId) {
+        resumeSessionId = err.sessionId;
+      }
+      if (attempt >= maxRetries) {
+        throw err;
+      }
+      const delay = Math.min(err.retryAfterMs ?? BASE_DELAY_MS * Math.pow(2, attempt), MAX_DELAY_MS) + jitter();
+      retryOptions?.onRetry?.(attempt + 1, delay, err);
+      await sleep(delay);
+    }
+  }
+  throw new Error("Max retries exceeded");
+}
+
+// src/utils/json-extract.ts
+function extractJsonStructure(output, open, close, typeName) {
+  const start = output.indexOf(open);
+  if (start === -1) {
+    throw new Error(`No JSON ${typeName} found in output`);
+  }
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  for (let i = start; i < output.length; i++) {
+    const ch = output[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (ch === "\\" && inString) {
+      escape = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === open) depth++;
+    if (ch === close) {
+      depth--;
+      if (depth === 0) {
+        return output.slice(start, i + 1);
+      }
+    }
+  }
+  throw new Error(`No complete JSON ${typeName} found in output`);
+}
+function extractJsonArray(output) {
+  return extractJsonStructure(output, "[", "]", "array");
+}
+function extractJsonObject(output) {
+  return extractJsonStructure(output, "{", "}", "object");
+}
+
+// src/commands/ticket/refine-utils.ts
+function formatTicketForPrompt(ticket) {
+  const lines = [];
+  lines.push(`### ${formatTicketDisplay(ticket)}`);
+  lines.push(`Project: ${ticket.projectName}`);
+  if (ticket.description) {
+    lines.push("");
+    lines.push("**Description:**");
+    lines.push(ticket.description);
+  }
+  if (ticket.link) {
+    lines.push("");
+    lines.push(`**Link:** ${ticket.link}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function parseRequirementsFile(content) {
+  const jsonStr = extractJsonArray(content);
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonStr);
+  } catch (err) {
+    throw new Error(`Invalid JSON: ${err instanceof Error ? err.message : "parse error"}`, { cause: err });
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error("Expected JSON array");
+  }
+  const result = RefinedRequirementsSchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues.map((issue) => {
+      const path = issue.path.length > 0 ? `[${issue.path.join(".")}]` : "";
+      return `  ${path}: ${issue.message}`;
+    }).join("\n");
+    throw new Error(`Invalid requirements format:
+${issues}`);
+  }
+  return result.data;
+}
+async function runAiSession(workingDir, prompt, ticketTitle) {
+  const contextFile = join3(workingDir, "refine-context.md");
+  await writeFile2(contextFile, prompt, "utf-8");
+  const provider = await getActiveProvider();
+  const startPrompt = `I need help refining the requirements for "${ticketTitle}". The full context is in refine-context.md. Please read that file now and follow the instructions to help refine the ticket requirements.`;
+  const result = spawnInteractive(
+    startPrompt,
+    {
+      cwd: workingDir
+    },
+    provider
+  );
+  if (result.error) {
+    throw new Error(result.error);
+  }
+}
+
+// src/commands/sprint/refine.ts
+function parseArgs(args) {
+  const options = {};
+  let sprintId;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const nextArg = args[i + 1];
+    if (arg === "--project") {
+      options.project = nextArg;
+      i++;
+    } else if (!arg?.startsWith("-")) {
+      sprintId = arg;
+    }
+  }
+  return { sprintId, options };
+}
+async function sprintRefineCommand(args) {
+  const { sprintId, options } = parseArgs(args);
+  let id;
+  try {
+    id = await resolveSprintId(sprintId);
+  } catch {
+    showWarning("No sprint specified and no current sprint set.");
+    showTip("Specify a sprint ID or create one first.");
+    log.newline();
+    return;
+  }
+  const sprint = await getSprint(id);
+  try {
+    assertSprintStatus(sprint, ["draft"], "refine");
+  } catch (err) {
+    if (err instanceof Error) {
+      showError(err.message);
+      log.newline();
+    }
+    return;
+  }
+  if (sprint.tickets.length === 0) {
+    showWarning("No tickets in sprint.");
+    showTip("Add tickets first: ralphctl ticket add --project <project-name>");
+    log.newline();
+    return;
+  }
+  let pendingTickets = getPendingRequirements(sprint.tickets);
+  if (options.project) {
+    pendingTickets = pendingTickets.filter((t) => t.projectName === options.project);
+    if (pendingTickets.length === 0) {
+      showWarning(`No pending tickets for project: ${options.project}`);
+      log.newline();
+      return;
+    }
+  }
+  if (pendingTickets.length === 0) {
+    showSuccess("All tickets already have approved requirements!");
+    showTip('Run "ralphctl sprint plan" to generate tasks.');
+    log.newline();
+    return;
+  }
+  printHeader("Requirements Refinement", icons.ticket);
+  console.log(field("Sprint", sprint.name));
+  console.log(field("ID", sprint.id));
+  console.log(field("Pending", `${String(pendingTickets.length)} ticket(s)`));
+  log.newline();
+  const schemaPath = getSchemaPath("requirements-output.schema.json");
+  const schema = await readFile(schemaPath, "utf-8");
+  const providerName = providerDisplayName(await resolveProvider());
+  let approved = 0;
+  let skipped = 0;
+  for (let i = 0; i < pendingTickets.length; i++) {
+    const ticket = pendingTickets[i];
+    if (!ticket) continue;
+    const ticketNum = i + 1;
+    const totalTickets = pendingTickets.length;
+    printSeparator(60);
+    console.log("");
+    console.log(`  ${icons.ticket}  ${info(`Ticket ${String(ticketNum)} of ${String(totalTickets)}`)}`);
+    console.log(
+      `  ${progressBar(i, totalTickets, {
+        width: 15,
+        showPercent: false
+      })} ${colors.muted(`${String(ticketNum)}/${String(totalTickets)}`)}`
+    );
+    console.log("");
+    console.log(field("Title", ticket.title, 14));
+    console.log(field("Project", ticket.projectName, 14));
+    if (ticket.link) {
+      console.log(field("Link", ticket.link, 14));
+    }
+    if (ticket.description) {
+      console.log(fieldMultiline("Description", ticket.description, 14));
+    }
+    log.newline();
+    try {
+      await getProject(ticket.projectName);
+    } catch {
+      showWarning(`Project '${ticket.projectName}' not found.`);
+      log.dim("Skipping this ticket.");
+      log.newline();
+      skipped++;
+      continue;
+    }
+    const proceed = await confirm({
+      message: `${emoji.donut} Start ${providerName} refinement session for this ticket?`,
+      default: true
+    });
+    if (!proceed) {
+      log.dim("Skipped. You can refine this ticket later.");
+      log.newline();
+      skipped++;
+      continue;
+    }
+    let issueContext = "";
+    if (ticket.link) {
+      const fetchSpinner = createSpinner("Fetching issue data...");
+      fetchSpinner.start();
+      try {
+        const issueData = fetchIssueFromUrl(ticket.link);
+        if (issueData) {
+          issueContext = formatIssueContext(issueData);
+          fetchSpinner.succeed(`Issue data fetched (${String(issueData.comments.length)} comment(s))`);
+        } else {
+          fetchSpinner.stop();
+        }
+      } catch (err) {
+        fetchSpinner.fail("Could not fetch issue data");
+        if (err instanceof IssueFetchError) {
+          showWarning(`${err.message} \u2014 continuing without issue context`);
+        } else if (err instanceof Error) {
+          showWarning(`${err.message} \u2014 continuing without issue context`);
+        }
+      }
+    }
+    const refineDir = getRefinementDir(id, ticket.id);
+    await mkdir(refineDir, { recursive: true });
+    const outputFile = join4(refineDir, "requirements.json");
+    const ticketContent = formatTicketForPrompt(ticket);
+    const prompt = buildTicketRefinePrompt(ticketContent, outputFile, schema, issueContext);
+    log.dim(`Working directory: ${refineDir}`);
+    log.dim(`Requirements output: ${outputFile}`);
+    log.newline();
+    const spinner = createSpinner(`Starting ${providerName} session...`);
+    spinner.start();
+    try {
+      await runAiSession(refineDir, prompt, ticket.title);
+      spinner.succeed(`${providerName} session completed`);
+    } catch (err) {
+      spinner.fail(`${providerName} session failed`);
+      if (err instanceof Error) {
+        showError(err.message);
+      }
+      log.newline();
+      skipped++;
+      continue;
+    }
+    log.newline();
+    if (await fileExists(outputFile)) {
+      let content;
+      try {
+        content = await readFile(outputFile, "utf-8");
+      } catch {
+        showError(`Failed to read requirements file: ${outputFile}`);
+        log.newline();
+        skipped++;
+        continue;
+      }
+      let refinedRequirements;
+      try {
+        refinedRequirements = parseRequirementsFile(content);
+      } catch (err) {
+        if (err instanceof Error) {
+          showError(`Failed to parse requirements file: ${err.message}`);
+        }
+        log.newline();
+        skipped++;
+        continue;
+      }
+      if (refinedRequirements.length === 0) {
+        showWarning("No requirements found in output file.");
+        log.newline();
+        skipped++;
+        continue;
+      }
+      const matchingRequirements = refinedRequirements.filter((r) => r.ref === ticket.id || r.ref === ticket.title);
+      if (matchingRequirements.length === 0) {
+        showWarning("Requirement reference does not match this ticket.");
+        log.newline();
+        skipped++;
+        continue;
+      }
+      const requirement = matchingRequirements.length === 1 ? {
+        ref: matchingRequirements[0]?.ref ?? "",
+        requirements: matchingRequirements[0]?.requirements ?? ""
+      } : {
+        ref: matchingRequirements[0]?.ref ?? "",
+        requirements: matchingRequirements.map((r, idx) => {
+          const text = r.requirements.trim();
+          if (/^#\s/.test(text)) return text;
+          return `# ${String(idx + 1)}. Section ${String(idx + 1)}
+
+${text}`;
+        }).join("\n\n---\n\n")
+      };
+      const reqLines = requirement.requirements.split("\n");
+      console.log(renderCard(`${icons.ticket} Refined Requirements`, reqLines));
+      log.newline();
+      const approveRequirement = await confirm({
+        message: `${emoji.donut} Approve these requirements?`,
+        default: true
+      });
+      if (approveRequirement) {
+        const ticketIdx = sprint.tickets.findIndex((t) => t.id === ticket.id);
+        const ticketToSave = sprint.tickets[ticketIdx];
+        if (ticketIdx !== -1 && ticketToSave) {
+          ticketToSave.requirements = requirement.requirements;
+          ticketToSave.requirementStatus = "approved";
+        }
+        await saveSprint(sprint);
+        showSuccess("Requirements approved and saved!");
+        approved++;
+      } else {
+        log.dim("Requirements not approved. You can refine this ticket later.");
+        skipped++;
+      }
+    } else {
+      showWarning("No requirements file found from AI session.");
+      log.dim("You can refine this ticket later.");
+      skipped++;
+    }
+    log.newline();
+  }
+  printSeparator(60);
+  log.newline();
+  printHeader("Summary", icons.success);
+  console.log(field("Approved", String(approved)));
+  console.log(field("Skipped", String(skipped)));
+  console.log(field("Total", String(pendingTickets.length)));
+  log.newline();
+  const updatedSprint = await getSprint(id);
+  const remainingPending = getPendingRequirements(updatedSprint.tickets);
+  if (remainingPending.length === 0) {
+    showSuccess("All requirements approved!");
+    const sprintDir = getSprintDir(id);
+    const outputPath = join4(sprintDir, "requirements.md");
+    try {
+      await exportRequirementsToMarkdown(updatedSprint, outputPath);
+      log.dim(`Requirements saved to: ${outputPath}`);
+    } catch (err) {
+      if (err instanceof Error) {
+        showError(`Failed to write requirements: ${err.message}`);
+      } else {
+        showError("Failed to write requirements: Unknown error");
+      }
+    }
+    showTip('Run "ralphctl sprint plan" to generate tasks.');
+  } else {
+    log.info(`${String(remainingPending.length)} ticket(s) still pending.`);
+    showTip("Continue refinement with: ralphctl sprint refine");
+  }
+  log.newline();
+}
+
+// src/commands/sprint/plan.ts
+import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { join as join5 } from "path";
+import { confirm as confirm3 } from "@inquirer/prompts";
+
+// src/store/task.ts
+var TaskNotFoundError = class extends Error {
+  taskId;
+  constructor(taskId) {
+    super(`Task not found: ${taskId}`);
+    this.name = "TaskNotFoundError";
+    this.taskId = taskId;
+  }
+};
+var DependencyCycleError = class extends Error {
+  cycle;
+  constructor(cycle) {
+    super(`Dependency cycle detected: ${cycle.join(" \u2192 ")}`);
+    this.name = "DependencyCycleError";
+    this.cycle = cycle;
+  }
+};
+async function getTasks(sprintId) {
+  const id = await resolveSprintId(sprintId);
+  return readValidatedJson(getTasksFilePath(id), TasksSchema);
+}
+async function saveTasks(tasks, sprintId) {
+  const id = await resolveSprintId(sprintId);
+  await writeValidatedJson(getTasksFilePath(id), tasks, TasksSchema);
+}
+async function getTask(taskId, sprintId) {
+  const tasks = await getTasks(sprintId);
+  const task = tasks.find((t) => t.id === taskId);
+  if (!task) {
+    throw new TaskNotFoundError(taskId);
+  }
+  return task;
+}
+async function addTask(input3, sprintId) {
+  const id = await resolveSprintId(sprintId);
+  const sprint = await getSprint(id);
+  assertSprintStatus(sprint, ["draft"], "add tasks");
+  const tasksFilePath = getTasksFilePath(id);
+  return withFileLock(tasksFilePath, async () => {
+    const tasks = await getTasks(id);
+    const maxOrder = tasks.reduce((max, t) => Math.max(max, t.order), 0);
+    const task = {
+      id: generateUuid8(),
+      name: input3.name,
+      description: input3.description,
+      steps: input3.steps ?? [],
+      status: "todo",
+      order: maxOrder + 1,
+      ticketId: input3.ticketId,
+      blockedBy: input3.blockedBy ?? [],
+      projectPath: input3.projectPath,
+      verified: false
+    };
+    tasks.push(task);
+    await saveTasks(tasks, id);
+    return task;
+  });
+}
+async function removeTask(taskId, sprintId) {
+  const id = await resolveSprintId(sprintId);
+  const sprint = await getSprint(id);
+  assertSprintStatus(sprint, ["draft"], "remove tasks");
+  const tasksFilePath = getTasksFilePath(id);
+  await withFileLock(tasksFilePath, async () => {
+    const tasks = await getTasks(id);
+    const index = tasks.findIndex((t) => t.id === taskId);
+    if (index === -1) {
+      throw new TaskNotFoundError(taskId);
+    }
+    tasks.splice(index, 1);
+    await saveTasks(tasks, id);
+  });
+}
+async function updateTaskStatus(taskId, status, sprintId) {
+  const id = await resolveSprintId(sprintId);
+  const sprint = await getSprint(id);
+  assertSprintStatus(sprint, ["active"], "update task status");
+  const tasksFilePath = getTasksFilePath(id);
+  return withFileLock(tasksFilePath, async () => {
+    const tasks = await getTasks(id);
+    const task = tasks.find((t) => t.id === taskId);
+    if (!task) {
+      throw new TaskNotFoundError(taskId);
+    }
+    task.status = status;
+    await saveTasks(tasks, id);
+    return task;
+  });
+}
+async function updateTask(taskId, updates, sprintId) {
+  const id = await resolveSprintId(sprintId);
+  const sprint = await getSprint(id);
+  assertSprintStatus(sprint, ["active"], "update task");
+  const tasksFilePath = getTasksFilePath(id);
+  return withFileLock(tasksFilePath, async () => {
+    const tasks = await getTasks(id);
+    const task = tasks.find((t) => t.id === taskId);
+    if (!task) {
+      throw new TaskNotFoundError(taskId);
+    }
+    if (updates.verified !== void 0) {
+      task.verified = updates.verified;
+    }
+    if (updates.verificationOutput !== void 0) {
+      task.verificationOutput = updates.verificationOutput;
+    }
+    await saveTasks(tasks, id);
+    return task;
+  });
+}
+async function isTaskBlocked(taskId, sprintId) {
+  const tasks = await getTasks(sprintId);
+  const task = tasks.find((t) => t.id === taskId);
+  if (!task) return false;
+  if (task.blockedBy.length === 0) return false;
+  const doneIds = new Set(tasks.filter((t) => t.status === "done").map((t) => t.id));
+  return !task.blockedBy.every((id) => doneIds.has(id));
+}
+async function getNextTask(sprintId) {
+  const tasks = await getTasks(sprintId);
+  const inProgress = tasks.find((t) => t.status === "in_progress");
+  if (inProgress) {
+    return inProgress;
+  }
+  const ready = getReadyTasksFromList(tasks);
+  return ready[0] ?? null;
+}
+function getReadyTasksFromList(tasks) {
+  const doneIds = new Set(tasks.filter((t) => t.status === "done").map((t) => t.id));
+  return tasks.filter((t) => t.status === "todo").filter((t) => t.blockedBy.every((id) => doneIds.has(id))).sort((a, b) => a.order - b.order);
+}
+async function getReadyTasks(sprintId) {
+  const tasks = await getTasks(sprintId);
+  return getReadyTasksFromList(tasks);
+}
+async function reorderTask(taskId, newOrder, sprintId) {
+  const id = await resolveSprintId(sprintId);
+  const sprint = await getSprint(id);
+  assertSprintStatus(sprint, ["draft"], "reorder tasks");
+  const tasksFilePath = getTasksFilePath(id);
+  return withFileLock(tasksFilePath, async () => {
+    const tasks = await getTasks(id);
+    const task = tasks.find((t) => t.id === taskId);
+    if (!task) {
+      throw new TaskNotFoundError(taskId);
+    }
+    const oldOrder = task.order;
+    task.order = newOrder;
+    for (const t of tasks) {
+      if (t.id === taskId) continue;
+      if (oldOrder < newOrder) {
+        if (t.order > oldOrder && t.order <= newOrder) {
+          t.order--;
+        }
+      } else {
+        if (t.order >= newOrder && t.order < oldOrder) {
+          t.order++;
+        }
+      }
+    }
+    await saveTasks(tasks, id);
+    return task;
+  });
+}
+async function listTasks(sprintId) {
+  const tasks = await getTasks(sprintId);
+  return tasks.sort((a, b) => a.order - b.order);
+}
+async function getRemainingTasks(sprintId) {
+  const tasks = await getTasks(sprintId);
+  return tasks.filter((t) => t.status !== "done").sort((a, b) => a.order - b.order);
+}
+async function areAllTasksDone(sprintId) {
+  const tasks = await getTasks(sprintId);
+  return tasks.length > 0 && tasks.every((t) => t.status === "done");
+}
+function topologicalSort(tasks) {
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const result = [];
+  function visit(taskId, path) {
+    if (visited.has(taskId)) return;
+    if (visiting.has(taskId)) {
+      const cycleStart = path.indexOf(taskId);
+      throw new DependencyCycleError([...path.slice(cycleStart), taskId]);
+    }
+    const task = taskMap.get(taskId);
+    if (!task) return;
+    visiting.add(taskId);
+    for (const blockedById of task.blockedBy) {
+      visit(blockedById, [...path, taskId]);
+    }
+    visiting.delete(taskId);
+    visited.add(taskId);
+    result.push(task);
+  }
+  for (const task of tasks) {
+    visit(task.id, []);
+  }
+  return result;
+}
+async function reorderByDependencies(sprintId) {
+  const id = await resolveSprintId(sprintId);
+  const tasksFilePath = getTasksFilePath(id);
+  await withFileLock(tasksFilePath, async () => {
+    const tasks = await getTasks(id);
+    if (tasks.length === 0) return;
+    const sorted = topologicalSort(tasks);
+    sorted.forEach((task, index) => {
+      task.order = index + 1;
+    });
+    await saveTasks(sorted, id);
+  });
+}
+function validateImportTasks(importTasks2, existingTasks, ticketIds) {
+  const errors = [];
+  if (ticketIds) {
+    for (const task of importTasks2) {
+      if (task.ticketId && !ticketIds.has(task.ticketId)) {
+        errors.push(`Task "${task.name}": ticketId "${task.ticketId}" does not match any ticket in the sprint`);
+      }
+    }
+  }
+  const localIds = new Set(importTasks2.map((t) => t.id).filter((id) => !!id));
+  const existingIds = new Set(existingTasks.map((t) => t.id));
+  const allKnownIds = /* @__PURE__ */ new Set([...localIds, ...existingIds]);
+  const localIdToIndex = /* @__PURE__ */ new Map();
+  importTasks2.forEach((task, i) => {
+    if (task.id) {
+      localIdToIndex.set(task.id, i);
+    }
+  });
+  importTasks2.forEach((task, taskIndex) => {
+    for (const depId of task.blockedBy ?? []) {
+      if (!allKnownIds.has(depId)) {
+        errors.push(`Task "${task.name}": blockedBy "${depId}" does not exist`);
+      } else if (localIds.has(depId)) {
+        const depIndex = localIdToIndex.get(depId);
+        if (depIndex !== void 0 && depIndex >= taskIndex) {
+          errors.push(`Task "${task.name}": blockedBy "${depId}" must reference an earlier task in the import`);
+        }
+      }
+    }
+  });
+  if (errors.length > 0) {
+    return errors;
+  }
+  const tempRealIds = importTasks2.map(() => generateUuid8());
+  const localToTempReal = /* @__PURE__ */ new Map();
+  importTasks2.forEach((task, i) => {
+    if (task.id) {
+      localToTempReal.set(task.id, tempRealIds[i] ?? "");
+    }
+  });
+  const combinedTasks = [
+    ...existingTasks,
+    ...importTasks2.map((t, i) => ({
+      id: tempRealIds[i] ?? generateUuid8(),
+      name: t.name,
+      description: void 0,
+      steps: [],
+      status: "todo",
+      order: existingTasks.length + i + 1,
+      ticketId: void 0,
+      blockedBy: (t.blockedBy ?? []).map((depId) => {
+        return localToTempReal.get(depId) ?? depId;
+      }),
+      projectPath: "/tmp",
+      // Placeholder for validation only
+      verified: false
+    }))
+  ];
+  try {
+    topologicalSort(combinedTasks);
+  } catch (err) {
+    if (err instanceof DependencyCycleError) {
+      errors.push(err.message);
+    } else {
+      throw err;
+    }
+  }
+  return errors;
+}
+
+// src/interactive/selectors.ts
+import { checkbox, confirm as confirm2, input } from "@inquirer/prompts";
+async function selectProject(message = "Select project:") {
+  const projects = await listProjects();
+  if (projects.length === 0) {
+    console.log(muted("\nNo projects found."));
+    const create = await confirm2({
+      message: "Create one now?",
+      default: true
+    });
+    if (create) {
+      const { projectAddCommand } = await import("./add-MRGCS3US.mjs");
+      await projectAddCommand({ interactive: true });
+      const updated = await listProjects();
+      if (updated.length === 0) return null;
+      if (updated.length === 1 && updated[0]) return updated[0].name;
+      return escapableSelect({
+        message: `${emoji.donut} ${message}`,
+        choices: updated.map((p) => ({
+          name: p.displayName,
+          value: p.name,
+          description: p.description
+        }))
+      });
+    }
+    return null;
+  }
+  return escapableSelect({
+    message: `${emoji.donut} ${message}`,
+    choices: projects.map((p) => ({
+      name: p.displayName,
+      value: p.name,
+      description: p.description
+    }))
+  });
+}
+async function selectProjectRepository(message = "Select repository:") {
+  const projects = await listProjects();
+  if (projects.length === 0) {
+    console.log(muted("\nNo projects found.\n"));
+    return null;
+  }
+  let projectName;
+  const firstProject = projects[0];
+  if (projects.length === 1 && firstProject) {
+    projectName = firstProject.name;
+  } else {
+    projectName = await escapableSelect({
+      message: `${emoji.donut} Select project:`,
+      choices: projects.map((p) => ({
+        name: p.displayName,
+        value: p.name,
+        description: `${String(p.repositories.length)} repo(s)`
+      }))
+    });
+  }
+  if (!projectName) return null;
+  const project = projects.find((p) => p.name === projectName);
+  if (!project) {
+    return null;
+  }
+  const firstRepo = project.repositories[0];
+  if (project.repositories.length === 1 && firstRepo) {
+    return firstRepo.path;
+  }
+  return escapableSelect({
+    message: `${emoji.donut} ${message}`,
+    choices: project.repositories.map((r) => ({
+      name: r.name,
+      value: r.path,
+      description: r.path
+    }))
+  });
+}
+async function selectSprint(message = "Select sprint:", filter) {
+  const sprints = await listSprints();
+  const filtered = filter ? sprints.filter((s) => filter.includes(s.status)) : sprints;
+  if (filtered.length === 0) {
+    console.log(muted("\nNo sprints found."));
+    const create = await confirm2({
+      message: "Create one now?",
+      default: true
+    });
+    if (create) {
+      const { sprintCreateCommand } = await import("./create-MG7E7PLQ.mjs");
+      await sprintCreateCommand({ interactive: true });
+      const updated = await listSprints();
+      const refiltered = filter ? updated.filter((s) => filter.includes(s.status)) : updated;
+      if (refiltered.length === 0) return null;
+      if (refiltered.length === 1 && refiltered[0]) return refiltered[0].id;
+      return escapableSelect({
+        message: `${emoji.donut} ${message}`,
+        choices: refiltered.map((s) => ({
+          name: `${s.id} - ${s.name} (${formatSprintStatus(s.status)})`,
+          value: s.id
+        }))
+      });
+    }
+    return null;
+  }
+  return escapableSelect({
+    message: `${emoji.donut} ${message}`,
+    choices: filtered.map((s) => ({
+      name: `${s.id} - ${s.name} (${formatSprintStatus(s.status)})`,
+      value: s.id
+    }))
+  });
+}
+async function selectTicket(message = "Select ticket:", filter) {
+  const tickets = await listTickets();
+  const filtered = filter ? tickets.filter(filter) : tickets;
+  if (filtered.length === 0) {
+    if (tickets.length === 0) {
+      console.log(muted("\nNo tickets found."));
+      const create = await confirm2({
+        message: "Add one now?",
+        default: true
+      });
+      if (create) {
+        const { ticketAddCommand } = await import("./add-HGJCLWED.mjs");
+        await ticketAddCommand({ interactive: true });
+        const updated = await listTickets();
+        const refiltered = filter ? updated.filter(filter) : updated;
+        if (refiltered.length === 0) return null;
+        if (refiltered.length === 1 && refiltered[0]) return refiltered[0].id;
+        return escapableSelect({
+          message: `${emoji.donut} ${message}`,
+          choices: refiltered.map((t) => ({
+            name: formatTicketDisplay(t),
+            value: t.id
+          }))
+        });
+      }
+      return null;
+    }
+    console.log(muted("\nNo matching tickets found.\n"));
+    return null;
+  }
+  return escapableSelect({
+    message: `${emoji.donut} ${message}`,
+    choices: filtered.map((t) => ({
+      name: formatTicketDisplay(t),
+      value: t.id
+    }))
+  });
+}
+async function selectTask(message = "Select task:", filter) {
+  const tasks = await listTasks();
+  const filtered = filter ? tasks.filter((t) => filter.includes(t.status)) : tasks;
+  if (filtered.length === 0) {
+    console.log(muted('\nNo tasks found. Use "sprint plan" to generate tasks.\n'));
+    return null;
+  }
+  return escapableSelect({
+    message: `${emoji.donut} ${message}`,
+    choices: filtered.map((t) => ({
+      name: `${formatTaskStatus(t.status)} ${t.name}`,
+      value: t.id
+    }))
+  });
+}
+async function selectTaskStatus(message = "Select status:") {
+  const statuses = ["todo", "in_progress", "done"];
+  return escapableSelect({
+    message: `${emoji.donut} ${message}`,
+    choices: statuses.map((s) => ({
+      name: formatTaskStatus(s),
+      value: s
+    }))
+  });
+}
+async function inputPositiveInt(message) {
+  const value = await input({
+    message: `${emoji.donut} ${message}`,
+    validate: (v) => {
+      const n = parseInt(v, 10);
+      if (isNaN(n) || n < 1) return "Must be a positive integer";
+      return true;
+    }
+  });
+  return parseInt(value, 10);
+}
+async function selectProjectPaths(reposByProject, message = "Select paths to explore:", preSelected) {
+  const choices = [];
+  const preSelectedSet = preSelected ? new Set(preSelected) : null;
+  for (const [projectName, repos] of reposByProject) {
+    repos.forEach((repo, i) => {
+      choices.push({
+        name: `[${projectName}] ${repo.name} (${repo.path})`,
+        value: repo.path,
+        checked: preSelectedSet ? preSelectedSet.has(repo.path) : i === 0
+      });
+    });
+  }
+  return checkbox({ message: `${emoji.donut} ${message}`, choices });
+}
+
+// src/commands/sprint/plan-utils.ts
+import { readFile as readFile2 } from "fs/promises";
+async function getTaskImportSchema() {
+  const schemaPath = getSchemaPath("task-import.schema.json");
+  return readFile2(schemaPath, "utf-8");
+}
+function parsePlanningBlocked(output) {
+  const match = /<planning-blocked>([\s\S]*?)<\/planning-blocked>/.exec(output);
+  return match?.[1]?.trim() ?? null;
+}
+function parseTasksJson(output) {
+  const jsonStr = extractJsonArray(output);
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonStr);
+  } catch (err) {
+    throw new Error(`Invalid JSON: ${err instanceof Error ? err.message : "parse error"}`, { cause: err });
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error("Expected JSON array");
+  }
+  const result = ImportTasksSchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues.map((issue) => {
+      const path = issue.path.length > 0 ? `[${issue.path.join(".")}]` : "";
+      return `  ${path}: ${issue.message}`;
+    }).join("\n");
+    throw new Error(`Invalid task format:
+${issues}`);
+  }
+  return result.data;
+}
+function renderParsedTasksTable(parsedTasks) {
+  const rows = parsedTasks.map((task, i) => {
+    const deps = task.blockedBy?.length ? task.blockedBy.join(", ") : "";
+    return [String(i + 1), task.name, task.projectPath, deps];
+  });
+  return renderTable(
+    [{ header: "#", align: "right" }, { header: "Name" }, { header: "Path" }, { header: "Blocked By" }],
+    rows
+  );
+}
+async function importTasks(tasks, sprintId, options) {
+  if (options?.replace) {
+    return importTasksReplace(tasks, sprintId);
+  }
+  return importTasksAppend(tasks, sprintId);
+}
+async function importTasksAppend(tasks, sprintId) {
+  const localToRealId = /* @__PURE__ */ new Map();
+  const createdTasks = [];
+  for (const taskInput of tasks) {
+    try {
+      const projectPath = taskInput.projectPath;
+      const task = await addTask(
+        {
+          name: taskInput.name,
+          description: taskInput.description,
+          steps: taskInput.steps ?? [],
+          ticketId: taskInput.ticketId,
+          blockedBy: [],
+          // Set later
+          projectPath
+        },
+        sprintId
+      );
+      if (taskInput.id) {
+        localToRealId.set(taskInput.id, task.id);
+      }
+      createdTasks.push({ task: taskInput, realId: task.id });
+      log.itemSuccess(`${task.id}: ${task.name}`);
+    } catch (err) {
+      log.itemError(`Failed to add: ${taskInput.name}`);
+      if (err instanceof Error) {
+        console.log(muted(`    ${err.message}`));
+      }
+    }
+  }
+  const tasksFilePath = getTasksFilePath(sprintId);
+  await withFileLock(tasksFilePath, async () => {
+    const allTasks = await getTasks(sprintId);
+    for (const { task: taskInput, realId } of createdTasks) {
+      const blockedBy = (taskInput.blockedBy ?? []).map((localId) => localToRealId.get(localId) ?? "").filter((id) => id !== "");
+      if (blockedBy.length > 0) {
+        const taskToUpdate = allTasks.find((t) => t.id === realId);
+        if (taskToUpdate) {
+          taskToUpdate.blockedBy = blockedBy;
+        }
+      }
+    }
+    await saveTasks(allTasks, sprintId);
+  });
+  return createdTasks.length;
+}
+async function importTasksReplace(tasks, sprintId) {
+  const localToRealId = /* @__PURE__ */ new Map();
+  const newTasks = [];
+  for (const taskInput of tasks) {
+    const realId = generateUuid8();
+    if (taskInput.id) {
+      localToRealId.set(taskInput.id, realId);
+    }
+    newTasks.push({
+      id: realId,
+      name: taskInput.name,
+      description: taskInput.description,
+      steps: taskInput.steps ?? [],
+      status: "todo",
+      order: newTasks.length + 1,
+      ticketId: taskInput.ticketId,
+      blockedBy: [],
+      // Set in second pass
+      projectPath: taskInput.projectPath,
+      verified: false
+    });
+    log.itemSuccess(`${realId}: ${taskInput.name}`);
+  }
+  for (let i = 0; i < tasks.length; i++) {
+    const taskInput = tasks[i];
+    const newTask = newTasks[i];
+    if (!taskInput || !newTask) continue;
+    const blockedBy = (taskInput.blockedBy ?? []).map((localId) => localToRealId.get(localId) ?? "").filter((id) => id !== "");
+    newTask.blockedBy = blockedBy;
+  }
+  await saveTasks(newTasks, sprintId);
+  return newTasks.length;
+}
+
+// src/commands/sprint/plan.ts
+function parseArgs2(args) {
+  const options = {
+    auto: false,
+    allPaths: false
+  };
+  let sprintId;
+  for (const arg of args) {
+    if (arg === "--auto") {
+      options.auto = true;
+    } else if (arg === "--all-paths") {
+      options.allPaths = true;
+    } else if (!arg.startsWith("-")) {
+      sprintId = arg;
+    }
+  }
+  return { sprintId, options };
+}
+async function getSprintContext(sprintName, ticketsByProject, existingTasks) {
+  const lines = [];
+  lines.push(`# Sprint: ${sprintName}`);
+  for (const [projectName, tickets] of ticketsByProject) {
+    lines.push("");
+    lines.push(`## Project: ${projectName}`);
+    try {
+      const project = await getProject(projectName);
+      lines.push("");
+      lines.push("### Repositories");
+      for (const repo of project.repositories) {
+        lines.push(`- **${repo.name}**: ${repo.path}`);
+        if (repo.checkScript) {
+          lines.push(`  - Check: \`${repo.checkScript}\``);
+        }
+      }
+    } catch {
+      lines.push("Repositories: (project not found)");
+    }
+    lines.push("");
+    lines.push("### Tickets");
+    for (const ticket of tickets) {
+      lines.push("");
+      lines.push(`#### ${formatTicketDisplay(ticket)}`);
+      if (ticket.description) {
+        lines.push("");
+        lines.push("**Original Description:**");
+        lines.push(ticket.description);
+      }
+      if (ticket.link) {
+        lines.push("");
+        lines.push(`Link: ${ticket.link}`);
+      }
+      if (ticket.requirements) {
+        lines.push("");
+        lines.push("**Refined Requirements:**");
+        lines.push("");
+        lines.push(ticket.requirements);
+      }
+    }
+  }
+  if (existingTasks.length > 0) {
+    lines.push("");
+    lines.push("## Existing Tasks");
+    lines.push("");
+    lines.push(
+      "> These are tasks from a previous planning run. Your output will replace all existing tasks entirely. You may reuse, modify, or drop existing tasks, and add new ones. Generate a complete task set covering ALL tickets."
+    );
+    lines.push("");
+    for (const task of existingTasks) {
+      const desc = task.description ? ` \u2014 ${task.description}` : "";
+      const ticket = task.ticketId ? ` ticket:${task.ticketId}` : "";
+      lines.push(`- ${task.id}: ${task.name} [${task.status}] (${task.projectPath})${ticket}${desc}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function invokeAiInteractive(prompt, repoPaths, planDir) {
+  const contextFile = join5(planDir, "planning-context.md");
+  await writeFile3(contextFile, prompt, "utf-8");
+  const provider = await getActiveProvider();
+  const ticketCount = (prompt.match(/^####/gm) ?? []).length;
+  const startPrompt = `I need help planning tasks for a sprint. The full planning context is in planning-context.md (${String(ticketCount)} tickets). Please read that file now and follow the instructions to help me plan implementation tasks.`;
+  const args = ["--add-dir", ...repoPaths];
+  const result = spawnInteractive(
+    startPrompt,
+    {
+      cwd: planDir,
+      args,
+      env: provider.getSpawnEnv()
+    },
+    provider
+  );
+  if (result.error) {
+    throw new Error(result.error);
+  }
+}
+async function invokeAiAuto(prompt, repoPaths, planDir) {
+  const provider = await getActiveProvider();
+  const args = ["--permission-mode", "plan", "--print"];
+  for (const path of repoPaths) {
+    args.push("--add-dir", path);
+  }
+  args.push("-p", prompt);
+  return spawnHeadless(
+    {
+      cwd: planDir,
+      args,
+      env: provider.getSpawnEnv()
+    },
+    provider
+  );
+}
+async function sprintPlanCommand(args) {
+  const { sprintId, options } = parseArgs2(args);
+  let id;
+  try {
+    id = await resolveSprintId(sprintId);
+  } catch {
+    showWarning("No sprint specified and no current sprint set.");
+    showNextStep("ralphctl sprint create", "create a new sprint");
+    log.newline();
+    return;
+  }
+  const sprint = await getSprint(id);
+  try {
+    assertSprintStatus(sprint, ["draft"], "plan");
+  } catch (err) {
+    if (err instanceof Error) {
+      showError(err.message);
+      log.newline();
+    }
+    return;
+  }
+  if (sprint.tickets.length === 0) {
+    showWarning("No tickets in sprint.");
+    showNextStep("ralphctl ticket add --project <project-name>", "add tickets first");
+    log.newline();
+    return;
+  }
+  const ticketsToProcess = sprint.tickets;
+  if (!allRequirementsApproved(ticketsToProcess)) {
+    const pendingTickets = getPendingRequirements(ticketsToProcess);
+    showWarning("Not all tickets have approved requirements.");
+    log.dim(`Pending: ${String(pendingTickets.length)} ticket(s)`);
+    for (const ticket of pendingTickets) {
+      log.item(muted(formatTicketDisplay(ticket)));
+    }
+    showNextStep("ralphctl sprint refine", "refine requirements first");
+    log.newline();
+    return;
+  }
+  const existingTasks = await listTasks(id);
+  const isReplan = existingTasks.length > 0;
+  if (isReplan) {
+    if (options.auto) {
+      showInfo(`Re-plan: ${String(existingTasks.length)} existing task(s) will be replaced with a fresh plan.`);
+      log.newline();
+    } else {
+      const proceed = await confirm3({
+        message: `${emoji.donut} ${String(existingTasks.length)} task(s) already exist. Re-planning will replace all tasks. Continue?`,
+        default: true
+      });
+      if (!proceed) {
+        log.dim("Cancelled.");
+        log.newline();
+        return;
+      }
+    }
+  }
+  const ticketsByProject = groupTicketsByProject(ticketsToProcess);
+  const providerName = providerDisplayName(await resolveProvider());
+  const modeLabel = options.auto ? "Auto (headless)" : "Interactive";
+  printHeader("Sprint Planning", icons.sprint);
+  console.log(field("Sprint", sprint.name));
+  console.log(field("ID", sprint.id));
+  console.log(field("Tickets", String(ticketsToProcess.length)));
+  console.log(field("Projects", String(ticketsByProject.size)));
+  console.log(field("Mode", modeLabel));
+  console.log(field("Provider", providerName));
+  for (const [proj, tickets] of ticketsByProject) {
+    console.log(muted(`  - ${proj}: ${String(tickets.length)} ticket(s)`));
+  }
+  console.log("");
+  const reposByProject = /* @__PURE__ */ new Map();
+  const defaultPaths = [];
+  for (const ticket of ticketsToProcess) {
+    if (reposByProject.has(ticket.projectName)) continue;
+    try {
+      const project = await getProject(ticket.projectName);
+      reposByProject.set(ticket.projectName, project.repositories);
+      if (project.repositories[0]) defaultPaths.push(project.repositories[0].path);
+    } catch {
+    }
+  }
+  const savedPaths = /* @__PURE__ */ new Set();
+  for (const ticket of ticketsToProcess) {
+    if (ticket.affectedRepositories) {
+      for (const path of ticket.affectedRepositories) {
+        savedPaths.add(path);
+      }
+    }
+  }
+  const hasSavedSelection = savedPaths.size > 0;
+  let selectedPaths;
+  const totalRepos = [...reposByProject.values()].reduce((n, repos) => n + repos.length, 0);
+  if (options.allPaths) {
+    selectedPaths = [...reposByProject.values()].flatMap((repos) => repos.map((r) => r.path));
+  } else if (options.auto) {
+    selectedPaths = hasSavedSelection ? [...savedPaths] : defaultPaths;
+  } else if (totalRepos === defaultPaths.length) {
+    selectedPaths = defaultPaths;
+  } else {
+    selectedPaths = await selectProjectPaths(
+      reposByProject,
+      "Select paths to explore:",
+      hasSavedSelection ? [...savedPaths] : void 0
+    );
+  }
+  for (const ticket of ticketsToProcess) {
+    const projectRepos = reposByProject.get(ticket.projectName);
+    if (projectRepos) {
+      const projectRepoPaths = new Set(projectRepos.map((r) => r.path));
+      ticket.affectedRepositories = selectedPaths.filter((p) => projectRepoPaths.has(p));
+    } else {
+      ticket.affectedRepositories = [];
+    }
+  }
+  await saveSprint(sprint);
+  if (selectedPaths.length > 1) {
+    console.log(muted(`Paths: ${selectedPaths.join(", ")}`));
+  } else {
+    console.log(muted(`Path: ${selectedPaths[0] ?? process.cwd()}`));
+  }
+  const context = await getSprintContext(
+    sprint.name,
+    ticketsByProject,
+    existingTasks.map((t) => ({
+      id: t.id,
+      name: t.name,
+      description: t.description,
+      status: t.status,
+      ticketId: t.ticketId,
+      projectPath: t.projectPath
+    }))
+  );
+  const schema = await getTaskImportSchema();
+  const contextLines = context.split("\n").length;
+  const contextChars = context.length;
+  console.log(muted(`Context: ${String(contextLines)} lines, ${String(contextChars)} chars`));
+  const planDir = getPlanningDir(id);
+  await mkdir2(planDir, { recursive: true });
+  const ticketIds = new Set(sprint.tickets.map((t) => t.id));
+  if (options.auto) {
+    const prompt = buildAutoPrompt(context, schema);
+    const spinner = createSpinner(`${providerName} is planning tasks...`);
+    spinner.start();
+    let output;
+    try {
+      output = await invokeAiAuto(prompt, selectedPaths, planDir);
+      spinner.succeed(`${providerName} finished planning`);
+    } catch (err) {
+      spinner.fail(`${providerName} planning failed`);
+      if (err instanceof Error) {
+        showError(`Failed to invoke ${providerName}: ${err.message}`);
+        showTip(`Make sure the ${providerName.toLowerCase()} CLI is installed and configured.`);
+        log.newline();
+      }
+      return;
+    }
+    const blockedReason = parsePlanningBlocked(output);
+    if (blockedReason) {
+      showWarning(`Planning blocked: ${blockedReason}`);
+      log.newline();
+      return;
+    }
+    console.log(muted("Parsing response..."));
+    let parsedTasks;
+    try {
+      parsedTasks = parseTasksJson(output);
+    } catch (err) {
+      if (err instanceof Error) {
+        showError(`Failed to parse ${providerName} output: ${err.message}`);
+        log.dim("Raw output:");
+        console.log(output);
+        log.newline();
+      }
+      return;
+    }
+    if (parsedTasks.length === 0) {
+      showWarning("No tasks generated.");
+      log.newline();
+      return;
+    }
+    showSuccess(`Generated ${String(parsedTasks.length)} task(s):`);
+    log.newline();
+    console.log(renderParsedTasksTable(parsedTasks));
+    console.log("");
+    const validationExistingTasks = isReplan ? [] : await getTasks(id);
+    const validationErrors = validateImportTasks(parsedTasks, validationExistingTasks, ticketIds);
+    if (validationErrors.length > 0) {
+      showError("Validation failed");
+      for (const err of validationErrors) {
+        log.item(error(err));
+      }
+      log.newline();
+      return;
+    }
+    showInfo("Importing tasks...");
+    const imported = await importTasks(parsedTasks, id, isReplan ? { replace: true } : void 0);
+    await reorderByDependencies(id);
+    log.dim("Tasks reordered by dependencies.");
+    terminalBell();
+    showSuccess(`Imported ${String(imported)}/${String(parsedTasks.length)} tasks.`);
+    log.newline();
+  } else {
+    const outputFile = join5(planDir, "tasks.json");
+    const prompt = buildInteractivePrompt(context, outputFile, schema);
+    showInfo(`Starting interactive ${providerName} session...`);
+    console.log(
+      muted(
+        `  Planning ${String(ticketsToProcess.length)} ticket(s) across ${String(ticketsByProject.size)} project(s)`
+      )
+    );
+    console.log(muted(`  Exploring: ${selectedPaths.join(", ")}`));
+    console.log(muted(`
+  ${providerName} will read planning-context.md and explore the repos.`));
+    console.log(muted(`  When done, ask ${providerName} to write tasks to: ${outputFile}
+`));
+    try {
+      await invokeAiInteractive(prompt, selectedPaths, planDir);
+    } catch (err) {
+      if (err instanceof Error) {
+        showError(`Failed to invoke ${providerName}: ${err.message}`);
+        showTip(`Make sure the ${providerName.toLowerCase()} CLI is installed and configured.`);
+        log.newline();
+      }
+      return;
+    }
+    console.log("");
+    if (await fileExists(outputFile)) {
+      showInfo("Task file found. Processing...");
+      let content;
+      try {
+        content = await readFile3(outputFile, "utf-8");
+      } catch {
+        showError(`Failed to read task file: ${outputFile}`);
+        log.newline();
+        return;
+      }
+      let parsedTasks;
+      try {
+        parsedTasks = parseTasksJson(content);
+      } catch (err) {
+        if (err instanceof Error) {
+          showError(`Failed to parse task file: ${err.message}`);
+          log.newline();
+        }
+        return;
+      }
+      if (parsedTasks.length === 0) {
+        showWarning("No tasks in file.");
+        log.newline();
+        return;
+      }
+      showSuccess(`Found ${String(parsedTasks.length)} task(s):`);
+      log.newline();
+      console.log(renderParsedTasksTable(parsedTasks));
+      console.log("");
+      const validationExistingTasks = isReplan ? [] : await getTasks(id);
+      const validationErrors = validateImportTasks(parsedTasks, validationExistingTasks, ticketIds);
+      if (validationErrors.length > 0) {
+        showError("Validation failed");
+        for (const err of validationErrors) {
+          log.item(error(err));
+        }
+        log.newline();
+        return;
+      }
+      showInfo("Importing tasks...");
+      const imported = await importTasks(parsedTasks, id, isReplan ? { replace: true } : void 0);
+      await reorderByDependencies(id);
+      log.dim("Tasks reordered by dependencies.");
+      terminalBell();
+      showSuccess(`Imported ${String(imported)}/${String(parsedTasks.length)} tasks.`);
+      log.newline();
+    } else {
+      showWarning("No task file found.");
+      showTip(`Expected: ${outputFile}`);
+      showNextStep("ralphctl sprint plan", "run planning again to create tasks");
+      log.newline();
+    }
+  }
+}
+
+// src/ai/runner.ts
+import { confirm as confirm5, input as input2, select as select2 } from "@inquirer/prompts";
+
+// src/ai/executor.ts
+import { confirm as confirm4 } from "@inquirer/prompts";
+import { readFile as readFile4, unlink as unlink2 } from "fs/promises";
+
+// src/ai/parser.ts
+function parseExecutionResult(output) {
+  const verifiedMatch = /<task-verified>([\s\S]*?)<\/task-verified>/.exec(output);
+  const verified = verifiedMatch !== null;
+  const verificationOutput = verifiedMatch?.[1]?.trim();
+  if (output.includes("<task-complete>")) {
+    if (!verified) {
+      return {
+        success: false,
+        output,
+        blockedReason: "Task marked complete without verification. Output <task-verified> with verification results before <task-complete>."
+      };
+    }
+    return { success: true, output, verified, verificationOutput };
+  }
+  const blockedMatch = /<task-blocked>([\s\S]*?)<\/task-blocked>/.exec(output);
+  if (blockedMatch) {
+    return { success: false, output, blockedReason: blockedMatch[1]?.trim(), verified, verificationOutput };
+  }
+  return { success: false, output, blockedReason: "No completion signal received", verified, verificationOutput };
+}
+
+// src/ai/rate-limiter.ts
+var RateLimitCoordinator = class {
+  resumeAt = null;
+  waiters = [];
+  timer = null;
+  onPauseCallback;
+  onResumeCallback;
+  constructor(options) {
+    this.onPauseCallback = options?.onPause;
+    this.onResumeCallback = options?.onResume;
+  }
+  /** Whether the coordinator is currently paused due to a rate limit. */
+  get isPaused() {
+    return this.resumeAt !== null && Date.now() < this.resumeAt;
+  }
+  /** Milliseconds remaining until resume, or 0 if not paused. */
+  get remainingMs() {
+    if (this.resumeAt === null) return 0;
+    return Math.max(0, this.resumeAt - Date.now());
+  }
+  /**
+   * Pause new task launches for a given duration.
+   * If already paused, extends the pause if the new duration is longer.
+   */
+  pause(delayMs) {
+    const newResumeAt = Date.now() + delayMs;
+    if (this.resumeAt !== null && newResumeAt <= this.resumeAt) {
+      return;
+    }
+    this.resumeAt = newResumeAt;
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+    }
+    this.onPauseCallback?.(delayMs);
+    this.timer = setTimeout(() => {
+      this.resume();
+    }, delayMs);
+  }
+  /**
+   * Wait until the rate limit pause is lifted.
+   * Returns immediately if not paused.
+   */
+  async waitIfPaused() {
+    if (!this.isPaused) return;
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+  /**
+   * Clean up timers. Call when execution is complete.
+   */
+  dispose() {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.resume();
+  }
+  resume() {
+    this.resumeAt = null;
+    this.timer = null;
+    this.onResumeCallback?.();
+    const waiters = this.waiters;
+    this.waiters = [];
+    for (const resolve of waiters) {
+      resolve();
+    }
+  }
+};
+
+// src/ai/task-context.ts
+import { execSync } from "child_process";
+import { writeFile as writeFile4 } from "fs/promises";
+import { join as join7 } from "path";
+
+// src/ai/permissions.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join6 } from "path";
+import { homedir } from "os";
+function getProviderPermissions(projectPath, provider) {
+  const permissions = {
+    allow: [],
+    deny: []
+  };
+  if (provider === "copilot") {
+    return permissions;
+  }
+  const projectSettingsPath = join6(projectPath, ".claude", "settings.local.json");
+  if (existsSync2(projectSettingsPath)) {
+    try {
+      const content = readFileSync2(projectSettingsPath, "utf-8");
+      const settings = JSON.parse(content);
+      if (settings.permissions?.allow) {
+        permissions.allow.push(...settings.permissions.allow);
+      }
+      if (settings.permissions?.deny) {
+        permissions.deny.push(...settings.permissions.deny);
+      }
+    } catch {
+    }
+  }
+  const userSettingsPath = join6(homedir(), ".claude", "settings.json");
+  if (existsSync2(userSettingsPath)) {
+    try {
+      const content = readFileSync2(userSettingsPath, "utf-8");
+      const settings = JSON.parse(content);
+      if (settings.permissions?.allow) {
+        permissions.allow.push(...settings.permissions.allow);
+      }
+      if (settings.permissions?.deny) {
+        permissions.deny.push(...settings.permissions.deny);
+      }
+    } catch {
+    }
+  }
+  return permissions;
+}
+function isToolAllowed(permissions, tool, specifier) {
+  for (const pattern of permissions.deny) {
+    if (matchesPattern(pattern, tool, specifier)) {
+      return false;
+    }
+  }
+  for (const pattern of permissions.allow) {
+    if (matchesPattern(pattern, tool, specifier)) {
+      return true;
+    }
+  }
+  return "ask";
+}
+function matchesPattern(pattern, tool, specifier) {
+  const parenIdx = pattern.indexOf("(");
+  if (parenIdx === -1) {
+    return pattern === tool;
+  }
+  const patternTool = pattern.slice(0, parenIdx);
+  if (patternTool !== tool) {
+    return false;
+  }
+  const specPattern = pattern.slice(parenIdx + 1, -1);
+  if (specPattern === "*") {
+    return true;
+  }
+  if (!specifier) {
+    return false;
+  }
+  if (specPattern.endsWith(":*")) {
+    const prefix = specPattern.slice(0, -2);
+    return specifier.startsWith(prefix);
+  }
+  if (specPattern.endsWith("*")) {
+    const prefix = specPattern.slice(0, -1);
+    return specifier.startsWith(prefix);
+  }
+  return specPattern === specifier;
+}
+function checkTaskPermissions(projectPath, options) {
+  const warnings = [];
+  const permissions = getProviderPermissions(projectPath, options.provider);
+  if (options.needsCommit !== false) {
+    const commitAllowed = isToolAllowed(permissions, "Bash", "git commit");
+    if (commitAllowed !== true) {
+      warnings.push({
+        tool: "Bash",
+        specifier: "git commit",
+        message: "Git commits may require manual approval"
+      });
+    }
+  }
+  if (options.checkScript) {
+    const checkAllowed = isToolAllowed(permissions, "Bash", options.checkScript);
+    if (checkAllowed !== true) {
+      warnings.push({
+        tool: "Bash",
+        specifier: options.checkScript,
+        message: `Check script "${options.checkScript}" may require approval`
+      });
+    }
+  }
+  return warnings;
+}
+
+// src/ai/task-context.ts
+function getRecentGitHistory(projectPath, count = 20) {
+  try {
+    assertSafeCwd(projectPath);
+    const result = execSync(`git log -${String(count)} --oneline --no-decorate`, {
+      cwd: projectPath,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return result.trim();
+  } catch {
+    return "(Unable to retrieve git history)";
+  }
+}
+function getEffectiveCheckScript(project, projectPath) {
+  if (project) {
+    const repo = project.repositories.find((r) => r.path === projectPath);
+    if (repo?.checkScript) {
+      return repo.checkScript;
+    }
+  }
+  return null;
+}
+function formatTask(ctx) {
+  const lines = [];
+  lines.push("## Task Directive");
+  lines.push("");
+  lines.push(`**Task:** ${ctx.task.name}`);
+  lines.push(`**ID:** ${ctx.task.id}`);
+  lines.push(`**Project:** ${ctx.task.projectPath}`);
+  lines.push("");
+  lines.push("**ONE TASK ONLY.** Complete THIS task and nothing else. Do not continue to other tasks.");
+  if (ctx.task.description) {
+    lines.push("");
+    lines.push(ctx.task.description);
+  }
+  if (ctx.task.steps.length > 0) {
+    lines.push("");
+    lines.push("## Implementation Steps");
+    lines.push("");
+    lines.push("Follow these steps precisely and in order:");
+    lines.push("");
+    ctx.task.steps.forEach((step, i) => {
+      lines.push(`${String(i + 1)}. ${step}`);
+    });
+  }
+  return lines.join("\n");
+}
+function buildFullTaskContext(ctx, progressSummary, gitHistory, checkScript, checkStatus) {
+  const lines = [];
+  lines.push(formatTask(ctx));
+  if (ctx.sprint.branch) {
+    lines.push("");
+    lines.push("## Branch");
+    lines.push("");
+    lines.push(
+      `You are working on branch \`${ctx.sprint.branch}\`. All commits go to this branch. Do not switch branches.`
+    );
+  }
+  lines.push("");
+  lines.push("## Check Script");
+  lines.push("");
+  if (checkScript) {
+    lines.push("The harness runs this command at sprint start and after every task as a post-task gate:");
+    lines.push("");
+    lines.push("```bash");
+    lines.push(checkScript);
+    lines.push("```");
+    lines.push("");
+    lines.push("Your task is NOT marked done unless this command passes after completion.");
+  } else {
+    lines.push("No check script is configured. Read CLAUDE.md in the project root to find verification commands.");
+  }
+  if (checkStatus) {
+    lines.push("");
+    lines.push("## Environment Status");
+    lines.push("");
+    if (checkStatus.ran) {
+      lines.push("The check script ran successfully at sprint start. Dependencies are current.");
+      lines.push("Do not re-run the install portion unless you encounter dependency errors.");
+    } else {
+      lines.push(
+        "No check script is configured for this repository. Read CLAUDE.md or project configuration files (package.json, pyproject.toml, etc.) to discover build, test, and lint commands."
+      );
+    }
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  if (progressSummary) {
+    lines.push("## Prior Task Learnings");
+    lines.push("");
+    lines.push("_Reference \u2014 consult when relevant to your implementation._");
+    lines.push("");
+    lines.push(progressSummary);
+    lines.push("");
+  }
+  if (ctx.task.ticketId) {
+    const ticket = ctx.sprint.tickets.find((t) => t.id === ctx.task.ticketId);
+    if (ticket?.requirements) {
+      lines.push("## Ticket Requirements");
+      lines.push("");
+      lines.push(
+        "_Reference \u2014 these describe the full ticket scope. This task implements a specific part. Use to validate your work and understand constraints, but follow the Implementation Steps above. Do not expand scope beyond declared steps._"
+      );
+      lines.push("");
+      lines.push(ticket.requirements);
+      lines.push("");
+    }
+  }
+  lines.push("## Git History (recent commits)");
+  lines.push("");
+  lines.push("```");
+  lines.push(gitHistory);
+  lines.push("```");
+  return lines.join("\n");
+}
+function getContextFileName(sprintId, taskId) {
+  return `.ralphctl-sprint-${sprintId}-task-${taskId}-context.md`;
+}
+async function writeTaskContextFile(projectPath, taskContent, instructions, sprintId, taskId) {
+  const contextFile = join7(projectPath, getContextFileName(sprintId, taskId));
+  const warning2 = `<!-- TEMPORARY FILE - DO NOT COMMIT -->
+<!-- This file is auto-generated by ralphctl for task execution context -->
+<!-- It will be automatically cleaned up after task completion -->
+
+`;
+  const fullContent = `${warning2}${taskContent}
+
+---
+
+## Instructions
+
+${instructions}`;
+  await writeFile4(contextFile, fullContent, { encoding: "utf-8", mode: 384 });
+  return contextFile;
+}
+async function getProjectForTask(task, sprint) {
+  if (!task.ticketId) return void 0;
+  const ticket = sprint.tickets.find((t) => t.id === task.ticketId);
+  if (!ticket) return void 0;
+  try {
+    return await getProject(ticket.projectName);
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      return void 0;
+    }
+    throw err;
+  }
+}
+function runPermissionCheck(ctx, noCommit, provider) {
+  const checkScript = getEffectiveCheckScript(ctx.project, ctx.task.projectPath);
+  const warnings = checkTaskPermissions(ctx.task.projectPath, {
+    checkScript,
+    needsCommit: !noCommit,
+    provider
+  });
+  if (warnings.length > 0) {
+    console.log(warning("\n  Permission warnings:"));
+    for (const w of warnings) {
+      console.log(muted(`    - ${w.message}`));
+    }
+    console.log(muted("  Consider adjusting tool permissions for your AI provider\n"));
+  }
+}
+
+// src/ai/lifecycle.ts
+import { spawnSync as spawnSync2 } from "child_process";
+var DEFAULT_HOOK_TIMEOUT_MS = 5 * 60 * 1e3;
+function getHookTimeoutMs() {
+  const envVal = process.env["RALPHCTL_SETUP_TIMEOUT_MS"];
+  if (envVal) {
+    const parsed = Number(envVal);
+    if (!Number.isNaN(parsed) && parsed > 0) return parsed;
+  }
+  return DEFAULT_HOOK_TIMEOUT_MS;
+}
+function runLifecycleHook(projectPath, script, event) {
+  assertSafeCwd(projectPath);
+  const timeoutMs = getHookTimeoutMs();
+  const result = spawnSync2(script, {
+    cwd: projectPath,
+    shell: true,
+    stdio: ["pipe", "pipe", "pipe"],
+    encoding: "utf-8",
+    timeout: timeoutMs,
+    env: { ...process.env, RALPHCTL_LIFECYCLE_EVENT: event }
+  });
+  const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+  return { passed: result.status === 0, output };
+}
+
+// src/ai/executor.ts
+async function executeTask(ctx, options, sprintId, resumeSessionId, provider, checkStatus) {
+  const p = provider ?? await getActiveProvider();
+  const label = p.displayName;
+  const projectPath = ctx.task.projectPath;
+  const sprintDir = getSprintDir(sprintId);
+  if (options.session) {
+    const contextFileName = getContextFileName(sprintId, ctx.task.id);
+    const gitHistory = getRecentGitHistory(projectPath, 20);
+    const checkScript = getEffectiveCheckScript(ctx.project, projectPath);
+    const allProgress = await getProgress(sprintId);
+    const progressSummary = summarizeProgressForContext(allProgress, projectPath, 3);
+    const fullTaskContent = buildFullTaskContext(ctx, progressSummary || null, gitHistory, checkScript, checkStatus);
+    const progressFilePath = getProgressFilePath(sprintId);
+    const instructions = buildTaskExecutionPrompt(progressFilePath, options.noCommit, contextFileName);
+    const contextFile = await writeTaskContextFile(projectPath, fullTaskContent, instructions, sprintId, ctx.task.id);
+    try {
+      const result = spawnInteractive(
+        `Read ${contextFileName} and follow the instructions`,
+        {
+          cwd: projectPath,
+          args: ["--add-dir", sprintDir]
+        },
+        p
+      );
+      if (result.error) {
+        return { success: false, output: "", blockedReason: result.error, sessionId: null };
+      }
+      if (result.code === 0) {
+        return { success: true, output: "", verified: true, sessionId: null };
+      }
+      return {
+        success: false,
+        output: "",
+        blockedReason: `${label} exited with code ${String(result.code)}`,
+        sessionId: null
+      };
+    } finally {
+      try {
+        await unlink2(contextFile);
+      } catch {
+      }
+    }
+  }
+  let spawnResult;
+  if (resumeSessionId) {
+    const spinner = createSpinner(`Resuming ${label} session for: ${ctx.task.name}`).start();
+    const manager = ProcessManager.getInstance();
+    const deregister = manager.registerCleanup(() => {
+      spinner.stop();
+    });
+    try {
+      spawnResult = await spawnWithRetry(
+        {
+          cwd: projectPath,
+          args: ["--add-dir", sprintDir],
+          prompt: "Continue where you left off. Complete the task and signal completion.",
+          resumeSessionId
+        },
+        {
+          maxRetries: options.maxRetries,
+          onRetry: (attempt, delayMs) => {
+            spinner.text = `Rate limited, retrying in ${String(Math.round(delayMs / 1e3))}s (attempt ${String(attempt)})...`;
+          }
+        },
+        p
+      );
+      spinner.succeed(`${label} completed: ${ctx.task.name}`);
+    } catch (err) {
+      spinner.fail(`${label} failed: ${ctx.task.name}`);
+      throw err;
+    } finally {
+      deregister();
+    }
+  } else {
+    const contextFileName = getContextFileName(sprintId, ctx.task.id);
+    const gitHistory = getRecentGitHistory(projectPath, 20);
+    const checkScript = getEffectiveCheckScript(ctx.project, projectPath);
+    const allProgress = await getProgress(sprintId);
+    const progressSummary = summarizeProgressForContext(allProgress, projectPath, 3);
+    const fullTaskContent = buildFullTaskContext(ctx, progressSummary || null, gitHistory, checkScript, checkStatus);
+    const progressFilePath = getProgressFilePath(sprintId);
+    const instructions = buildTaskExecutionPrompt(progressFilePath, options.noCommit, contextFileName);
+    const contextFile = await writeTaskContextFile(projectPath, fullTaskContent, instructions, sprintId, ctx.task.id);
+    const spinner = createSpinner(`${label} is working on: ${ctx.task.name}`).start();
+    const manager = ProcessManager.getInstance();
+    const deregister = manager.registerCleanup(() => {
+      spinner.stop();
+    });
+    try {
+      const contextContent = await readFile4(contextFile, "utf-8");
+      spawnResult = await spawnWithRetry(
+        {
+          cwd: projectPath,
+          args: ["--add-dir", sprintDir],
+          prompt: contextContent
+        },
+        {
+          maxRetries: options.maxRetries,
+          onRetry: (attempt, delayMs) => {
+            spinner.text = `Rate limited, retrying in ${String(Math.round(delayMs / 1e3))}s (attempt ${String(attempt)})...`;
+          }
+        },
+        p
+      );
+      spinner.succeed(`${label} completed: ${ctx.task.name}`);
+    } catch (err) {
+      spinner.fail(`${label} failed: ${ctx.task.name}`);
+      throw err;
+    } finally {
+      deregister();
+      try {
+        await unlink2(contextFile);
+      } catch {
+      }
+    }
+  }
+  const parsed = parseExecutionResult(spawnResult.stdout);
+  return { ...parsed, sessionId: spawnResult.sessionId };
+}
+async function areAllRemainingBlocked(sprintId) {
+  const remaining = await getRemainingTasks(sprintId);
+  if (remaining.length === 0) return false;
+  for (const task of remaining) {
+    if (task.status === "in_progress") return false;
+    const blocked = await isTaskBlocked(task.id, sprintId);
+    if (!blocked) return false;
+  }
+  return true;
+}
+async function executeTaskLoop(sprintId, options, checkResults) {
+  ProcessManager.getInstance().ensureHandlers();
+  const provider = await getActiveProvider();
+  const label = provider.displayName;
+  const sprint = await getSprint(sprintId);
+  let completedCount = 0;
+  const targetCount = options.count ?? Infinity;
+  const firstTask = await getNextTask(sprintId);
+  if (firstTask?.status === "in_progress") {
+    console.log(warning(`
+Resuming from: ${firstTask.id} - ${firstTask.name}`));
+  }
+  while (completedCount < targetCount) {
+    const manager = ProcessManager.getInstance();
+    if (manager.isShuttingDown()) {
+      const remaining2 = await getRemainingTasks(sprintId);
+      return {
+        completed: completedCount,
+        remaining: remaining2.length,
+        stopReason: "task_blocked",
+        blockedTask: null,
+        blockedReason: "Interrupted by user",
+        exitCode: EXIT_ERROR
+      };
+    }
+    const task = await getNextTask(sprintId);
+    if (!task) {
+      if (await areAllRemainingBlocked(sprintId)) {
+        const remaining3 = await getRemainingTasks(sprintId);
+        return {
+          completed: completedCount,
+          remaining: remaining3.length,
+          stopReason: "all_blocked",
+          blockedTask: null,
+          blockedReason: "All remaining tasks are blocked by dependencies",
+          exitCode: EXIT_ALL_BLOCKED
+        };
+      }
+      const remaining2 = await getRemainingTasks(sprintId);
+      if (remaining2.length === 0 && completedCount === 0) {
+        return {
+          completed: 0,
+          remaining: 0,
+          stopReason: "no_tasks",
+          blockedTask: null,
+          blockedReason: null,
+          exitCode: EXIT_NO_TASKS
+        };
+      }
+      console.log(success("\nAll tasks completed!"));
+      return {
+        completed: completedCount,
+        remaining: 0,
+        stopReason: "all_completed",
+        blockedTask: null,
+        blockedReason: null,
+        exitCode: EXIT_SUCCESS
+      };
+    }
+    console.log(info(`
+--- Task ${String(task.order)}: ${task.name} ---`));
+    console.log(info("ID:      ") + task.id);
+    console.log(info("Project: ") + task.projectPath);
+    console.log(info("Status:  ") + formatTaskStatus(task.status));
+    if (task.status !== "in_progress") {
+      await updateTaskStatus(task.id, "in_progress", sprintId);
+      console.log(muted("Status updated to: in_progress"));
+    }
+    const project = await getProjectForTask(task, sprint);
+    const ctx = { sprint, task, project };
+    const taskPrompt = formatTask(ctx);
+    if (completedCount === 0) {
+      runPermissionCheck(ctx, options.noCommit, provider.name);
+    }
+    if (sprint.branch) {
+      if (!verifySprintBranch(task.projectPath, sprint.branch)) {
+        console.log(warning(`
+Branch verification failed: expected '${sprint.branch}' in ${task.projectPath}`));
+        console.log(muted(`Task ${task.id} remains in_progress.`));
+        const remaining2 = await getRemainingTasks(sprintId);
+        return {
+          completed: completedCount,
+          remaining: remaining2.length,
+          stopReason: "task_blocked",
+          blockedTask: task,
+          blockedReason: `Repository ${task.projectPath} is not on expected branch '${sprint.branch}'`,
+          exitCode: EXIT_ERROR
+        };
+      }
+    }
+    if (options.session) {
+      console.log(highlight(`
+[Task Context for ${label}]`));
+      console.log(muted("\u2500".repeat(50)));
+      console.log(taskPrompt);
+      console.log(muted("\u2500".repeat(50)));
+      console.log(muted(`
+Starting ${label} in ${task.projectPath} (session)...
+`));
+    } else {
+      console.log(muted(`Starting ${label} in ${task.projectPath} (headless)...`));
+    }
+    const result = await executeTask(ctx, options, sprintId, void 0, provider, checkResults?.get(task.projectPath));
+    if (!result.success) {
+      console.log(warning("\nTask not completed."));
+      if (result.blockedReason) {
+        console.log(warning(`Reason: ${result.blockedReason}`));
+      }
+      console.log(muted("\nExecution paused. Task remains in_progress."));
+      console.log(muted(`Resume with: ralphctl sprint start ${sprintId}
+`));
+      const remaining2 = await getRemainingTasks(sprintId);
+      return {
+        completed: completedCount,
+        remaining: remaining2.length,
+        stopReason: "task_blocked",
+        blockedTask: task,
+        blockedReason: result.blockedReason ?? "Unknown reason",
+        exitCode: EXIT_ERROR
+      };
+    }
+    if (result.verified) {
+      await updateTask(
+        task.id,
+        {
+          verified: true,
+          verificationOutput: result.verificationOutput
+        },
+        sprintId
+      );
+      console.log(success("Verification: passed"));
+    }
+    const checkScript = getEffectiveCheckScript(project, task.projectPath);
+    if (checkScript) {
+      console.log(muted(`Running post-task check: ${checkScript}`));
+      const hookResult = runLifecycleHook(task.projectPath, checkScript, "taskComplete");
+      if (!hookResult.passed) {
+        console.log(warning(`
+Post-task check failed for: ${task.name}`));
+        console.log(muted("Task remains in_progress. Execution paused."));
+        console.log(muted(`Resume with: ralphctl sprint start ${sprintId}
+`));
+        const remaining2 = await getRemainingTasks(sprintId);
+        return {
+          completed: completedCount,
+          remaining: remaining2.length,
+          stopReason: "task_blocked",
+          blockedTask: task,
+          blockedReason: `Post-task check failed: ${hookResult.output.slice(0, 500)}`,
+          exitCode: EXIT_ERROR
+        };
+      }
+      console.log(success("Post-task check: passed"));
+    }
+    await updateTaskStatus(task.id, "done", sprintId);
+    console.log(success("Status updated to: done"));
+    await logProgress(
+      `Completed task: ${task.id} - ${task.name}
+
+` + (task.description ? `Description: ${task.description}
+` : "") + (task.steps.length > 0 ? `Steps:
+${task.steps.map((s, i) => `  ${String(i + 1)}. ${s}`).join("\n")}` : ""),
+      { sprintId, projectPath: task.projectPath }
+    );
+    completedCount++;
+    if (options.step && completedCount < targetCount) {
+      const remaining2 = await getRemainingTasks(sprintId);
+      if (remaining2.length > 0) {
+        console.log(info(`
+${String(remaining2.length)} task(s) remaining.`));
+        const continueLoop = await confirm4({
+          message: "Continue to next task?",
+          default: true
+        });
+        if (!continueLoop) {
+          console.log(muted("\nExecution paused."));
+          console.log(muted(`Resume with: ralphctl sprint start ${sprintId}
+`));
+          return {
+            completed: completedCount,
+            remaining: remaining2.length,
+            stopReason: "user_paused",
+            blockedTask: null,
+            blockedReason: null,
+            exitCode: EXIT_SUCCESS
+          };
+        }
+      }
+    }
+  }
+  const remaining = await getRemainingTasks(sprintId);
+  return {
+    completed: completedCount,
+    remaining: remaining.length,
+    stopReason: remaining.length === 0 ? "all_completed" : "count_reached",
+    blockedTask: null,
+    blockedReason: null,
+    exitCode: EXIT_SUCCESS
+  };
+}
+function pickTasksToLaunch(readyTasks, inFlightPaths, concurrencyLimit, currentInFlight) {
+  const available = readyTasks.filter((t) => !inFlightPaths.has(t.projectPath));
+  const byPath = /* @__PURE__ */ new Map();
+  for (const task of available) {
+    if (!byPath.has(task.projectPath)) {
+      byPath.set(task.projectPath, task);
+    }
+  }
+  const candidates = [...byPath.values()];
+  const slotsAvailable = concurrencyLimit - currentInFlight;
+  return candidates.slice(0, Math.max(0, slotsAvailable));
+}
+async function executeTaskLoopParallel(sprintId, options, checkResults) {
+  ProcessManager.getInstance().ensureHandlers();
+  const provider = await getActiveProvider();
+  const label = provider.displayName;
+  const sprint = await getSprint(sprintId);
+  let completedCount = 0;
+  const targetCount = options.count ?? Infinity;
+  const failFast = options.failFast ?? true;
+  let hasFailed = false;
+  let firstBlockedTask = null;
+  let firstBlockedReason = null;
+  const MAX_CONCURRENCY = 10;
+  const allTasks = await getTasks(sprintId);
+  const uniqueRepoPaths = new Set(allTasks.map((t) => t.projectPath));
+  const concurrencyLimit = Math.min(options.concurrency ?? uniqueRepoPaths.size, MAX_CONCURRENCY);
+  console.log(muted(`Parallel mode: up to ${String(concurrencyLimit)} concurrent task(s)`));
+  const coordinator = new RateLimitCoordinator({
+    onPause: (delayMs) => {
+      console.log(warning(`
+Rate limited. Pausing new launches for ${String(Math.round(delayMs / 1e3))}s...`));
+    },
+    onResume: () => {
+      console.log(success("Rate limit cooldown ended. Resuming launches."));
+    }
+  });
+  const inFlightPaths = /* @__PURE__ */ new Set();
+  const running = /* @__PURE__ */ new Map();
+  const taskSessionIds = /* @__PURE__ */ new Map();
+  const branchRetries = /* @__PURE__ */ new Map();
+  const MAX_BRANCH_RETRIES = 3;
+  let permissionCheckDone = false;
+  try {
+    const inProgressTasks = allTasks.filter((t) => t.status === "in_progress");
+    if (inProgressTasks.length > 0) {
+      console.log(warning(`
+Resuming ${String(inProgressTasks.length)} in-progress task(s):`));
+      for (const t of inProgressTasks) {
+        console.log(warning(`  - ${t.id}: ${t.name}`));
+      }
+    }
+    while (completedCount < targetCount) {
+      const manager = ProcessManager.getInstance();
+      if (manager.isShuttingDown()) {
+        break;
+      }
+      await coordinator.waitIfPaused();
+      const readyTasks = await getReadyTasks(sprintId);
+      const currentTasks = await getTasks(sprintId);
+      const inProgress = currentTasks.filter((t) => t.status === "in_progress" && !running.has(t.id));
+      const launchCandidates = [...inProgress, ...readyTasks.filter((t) => !inProgress.some((ip) => ip.id === t.id))];
+      if (launchCandidates.length === 0 && running.size === 0) {
+        const remaining = await getRemainingTasks(sprintId);
+        if (remaining.length === 0) {
+          if (completedCount === 0) {
+            return {
+              completed: 0,
+              remaining: 0,
+              stopReason: "no_tasks",
+              blockedTask: null,
+              blockedReason: null,
+              exitCode: EXIT_NO_TASKS
+            };
+          }
+          console.log(success("\nAll tasks completed!"));
+          return {
+            completed: completedCount,
+            remaining: 0,
+            stopReason: "all_completed",
+            blockedTask: null,
+            blockedReason: null,
+            exitCode: EXIT_SUCCESS
+          };
+        }
+        return {
+          completed: completedCount,
+          remaining: remaining.length,
+          stopReason: hasFailed ? "task_blocked" : "all_blocked",
+          blockedTask: firstBlockedTask,
+          blockedReason: firstBlockedReason ?? "All remaining tasks are blocked by dependencies",
+          exitCode: hasFailed ? EXIT_ERROR : EXIT_ALL_BLOCKED
+        };
+      }
+      if (!hasFailed || !failFast) {
+        const toStart = pickTasksToLaunch(launchCandidates, inFlightPaths, concurrencyLimit, running.size);
+        for (const task of toStart) {
+          if (completedCount + running.size >= targetCount) break;
+          const project = await getProjectForTask(task, sprint);
+          if (!permissionCheckDone) {
+            const ctx = { sprint, task, project };
+            runPermissionCheck(ctx, options.noCommit, provider.name);
+            permissionCheckDone = true;
+          }
+          if (sprint.branch) {
+            if (!verifySprintBranch(task.projectPath, sprint.branch)) {
+              const attempt = (branchRetries.get(task.id) ?? 0) + 1;
+              branchRetries.set(task.id, attempt);
+              if (attempt < MAX_BRANCH_RETRIES) {
+                console.log(
+                  warning(
+                    `
+  Branch verification failed (attempt ${String(attempt)}/${String(MAX_BRANCH_RETRIES)}): expected '${sprint.branch}' in ${task.projectPath}`
+                  )
+                );
+                console.log(muted(`  Task ${task.id} will retry on next loop iteration.`));
+                continue;
+              }
+              console.log(
+                warning(
+                  `
+  Branch verification failed after ${String(MAX_BRANCH_RETRIES)} attempts: expected '${sprint.branch}' in ${task.projectPath}`
+                )
+              );
+              console.log(muted(`  Task ${task.id} not started \u2014 wrong branch.`));
+              hasFailed = true;
+              if (!firstBlockedTask) {
+                firstBlockedTask = task;
+                firstBlockedReason = `Repository ${task.projectPath} is not on expected branch '${sprint.branch}'`;
+              }
+              if (failFast) {
+                console.log(muted("Fail-fast: waiting for running tasks to finish..."));
+              }
+              continue;
+            }
+          }
+          if (task.status !== "in_progress") {
+            await updateTaskStatus(task.id, "in_progress", sprintId);
+          }
+          const resumeId = taskSessionIds.get(task.id);
+          const action = resumeId ? "Resuming" : "Starting";
+          console.log(info(`
+--- ${action} task ${String(task.order)}: ${task.name} ---`));
+          console.log(info("ID:      ") + task.id);
+          console.log(info("Project: ") + task.projectPath);
+          if (resumeId) {
+            console.log(muted(`Resuming ${label} session ${resumeId.slice(0, 8)}...`));
+          } else {
+            console.log(muted(`Starting ${label} in ${task.projectPath} (headless)...`));
+          }
+          inFlightPaths.add(task.projectPath);
+          const taskPromise = (async () => {
+            try {
+              const ctx = { sprint, task, project };
+              const result = await executeTask(
+                ctx,
+                options,
+                sprintId,
+                resumeId,
+                provider,
+                checkResults?.get(task.projectPath)
+              );
+              if (result.sessionId) {
+                taskSessionIds.set(task.id, result.sessionId);
+              }
+              return { task, result, error: null, isRateLimited: false };
+            } catch (err) {
+              if (err instanceof SpawnError && err.rateLimited) {
+                if (err.sessionId) {
+                  taskSessionIds.set(task.id, err.sessionId);
+                }
+                const delay = err.retryAfterMs ?? 6e4;
+                coordinator.pause(delay);
+                return {
+                  task,
+                  result: null,
+                  error: err,
+                  isRateLimited: true
+                };
+              }
+              return {
+                task,
+                result: null,
+                error: err instanceof Error ? err : new Error(String(err)),
+                isRateLimited: false
+              };
+            } finally {
+              inFlightPaths.delete(task.projectPath);
+            }
+          })();
+          running.set(task.id, taskPromise);
+        }
+      }
+      if (running.size === 0) {
+        const hasPendingBranchRetry = [...branchRetries.entries()].some(([, count]) => count < MAX_BRANCH_RETRIES);
+        if (hasPendingBranchRetry) {
+          await new Promise((resolve) => setTimeout(resolve, 1e3));
+          continue;
+        }
+        break;
+      }
+      const settled = await Promise.race([...running.values()]);
+      running.delete(settled.task.id);
+      if (settled.error) {
+        if (settled.isRateLimited) {
+          const sessionId = taskSessionIds.get(settled.task.id);
+          console.log(warning(`
+Rate limited: ${settled.task.name}`));
+          if (sessionId) {
+            console.log(muted(`Session saved for resume: ${sessionId.slice(0, 8)}...`));
+          }
+          console.log(muted("Will retry after cooldown."));
+          continue;
+        }
+        console.log(warning(`
+Task failed: ${settled.task.name}`));
+        console.log(warning(`Error: ${settled.error.message}`));
+        console.log(muted(`Task ${settled.task.id} remains in_progress for resumption.`));
+        hasFailed = true;
+        if (!firstBlockedTask) {
+          firstBlockedTask = settled.task;
+          firstBlockedReason = settled.error.message;
+        }
+        if (failFast) {
+          console.log(muted("Fail-fast: waiting for running tasks to finish..."));
+        }
+        continue;
+      }
+      if (settled.result && !settled.result.success) {
+        console.log(warning(`
+Task not completed: ${settled.task.name}`));
+        if (settled.result.blockedReason) {
+          console.log(warning(`Reason: ${settled.result.blockedReason}`));
+        }
+        console.log(muted(`Task ${settled.task.id} remains in_progress.`));
+        hasFailed = true;
+        if (!firstBlockedTask) {
+          firstBlockedTask = settled.task;
+          firstBlockedReason = settled.result.blockedReason ?? "Unknown reason";
+        }
+        if (failFast) {
+          console.log(muted("Fail-fast: waiting for running tasks to finish..."));
+        }
+        continue;
+      }
+      if (settled.result) {
+        if (settled.result.verified) {
+          await updateTask(
+            settled.task.id,
+            {
+              verified: true,
+              verificationOutput: settled.result.verificationOutput
+            },
+            sprintId
+          );
+          console.log(success(`Verification passed: ${settled.task.name}`));
+        }
+        const taskProject = await getProjectForTask(settled.task, sprint);
+        const taskCheckScript = getEffectiveCheckScript(taskProject, settled.task.projectPath);
+        if (taskCheckScript) {
+          const hookResult = runLifecycleHook(settled.task.projectPath, taskCheckScript, "taskComplete");
+          if (!hookResult.passed) {
+            console.log(warning(`
+Post-task check failed for: ${settled.task.name}`));
+            console.log(muted(`Task ${settled.task.id} remains in_progress.`));
+            hasFailed = true;
+            if (!firstBlockedTask) {
+              firstBlockedTask = settled.task;
+              firstBlockedReason = `Post-task check failed: ${hookResult.output.slice(0, 500)}`;
+            }
+            if (failFast) {
+              console.log(muted("Fail-fast: waiting for running tasks to finish..."));
+            }
+            continue;
+          }
+          console.log(success(`Post-task check passed: ${settled.task.name}`));
+        }
+        await updateTaskStatus(settled.task.id, "done", sprintId);
+        console.log(success(`Completed: ${settled.task.name}`));
+        taskSessionIds.delete(settled.task.id);
+        await logProgress(
+          `Completed task: ${settled.task.id} - ${settled.task.name}
+
+` + (settled.task.description ? `Description: ${settled.task.description}
+` : "") + (settled.task.steps.length > 0 ? `Steps:
+${settled.task.steps.map((s, i) => `  ${String(i + 1)}. ${s}`).join("\n")}` : ""),
+          { sprintId, projectPath: settled.task.projectPath }
+        );
+        completedCount++;
+      }
+    }
+    if (running.size > 0) {
+      console.log(muted(`
+Waiting for ${String(running.size)} remaining task(s)...`));
+      const remaining = await Promise.allSettled([...running.values()]);
+      for (const r of remaining) {
+        if (r.status === "fulfilled" && r.value.result?.success) {
+          if (r.value.result.verified) {
+            await updateTask(
+              r.value.task.id,
+              { verified: true, verificationOutput: r.value.result.verificationOutput },
+              sprintId
+            );
+          }
+          const drainProject = await getProjectForTask(r.value.task, sprint);
+          const drainCheckScript = getEffectiveCheckScript(drainProject, r.value.task.projectPath);
+          if (drainCheckScript) {
+            const hookResult = runLifecycleHook(r.value.task.projectPath, drainCheckScript, "taskComplete");
+            if (!hookResult.passed) {
+              console.log(warning(`Post-task check failed for: ${r.value.task.name}`));
+              continue;
+            }
+          }
+          await updateTaskStatus(r.value.task.id, "done", sprintId);
+          console.log(success(`Completed: ${r.value.task.name}`));
+          await logProgress(`Completed task: ${r.value.task.id} - ${r.value.task.name}`, {
+            sprintId,
+            projectPath: r.value.task.projectPath
+          });
+          completedCount++;
+        }
+      }
+    }
+  } finally {
+    coordinator.dispose();
+  }
+  const remainingTasks = await getRemainingTasks(sprintId);
+  if (hasFailed) {
+    return {
+      completed: completedCount,
+      remaining: remainingTasks.length,
+      stopReason: "task_blocked",
+      blockedTask: firstBlockedTask,
+      blockedReason: firstBlockedReason,
+      exitCode: EXIT_ERROR
+    };
+  }
+  return {
+    completed: completedCount,
+    remaining: remainingTasks.length,
+    stopReason: remainingTasks.length === 0 ? "all_completed" : "count_reached",
+    blockedTask: null,
+    blockedReason: null,
+    exitCode: EXIT_SUCCESS
+  };
+}
+
+// src/utils/git.ts
+import { spawnSync as spawnSync3 } from "child_process";
+var BRANCH_NAME_RE = /^[a-zA-Z0-9/_.-]+$/;
+var BRANCH_NAME_INVALID_PATTERNS = [/\.\./, /\.$/, /\/$/, /\.lock$/, /^-/, /\/\//];
+function isValidBranchName(name) {
+  if (!name || name.length > 250) return false;
+  if (!BRANCH_NAME_RE.test(name)) return false;
+  for (const pattern of BRANCH_NAME_INVALID_PATTERNS) {
+    if (pattern.test(name)) return false;
+  }
+  return true;
+}
+function getCurrentBranch(cwd) {
+  assertSafeCwd(cwd);
+  const result = spawnSync3("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (result.status !== 0) {
+    throw new Error(`Failed to get current branch in ${cwd}: ${result.stderr.trim()}`);
+  }
+  return result.stdout.trim();
+}
+function branchExists(cwd, name) {
+  assertSafeCwd(cwd);
+  if (!isValidBranchName(name)) {
+    throw new Error(`Invalid branch name: ${name}`);
+  }
+  const result = spawnSync3("git", ["show-ref", "--verify", `refs/heads/${name}`], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  return result.status === 0;
+}
+function createAndCheckoutBranch(cwd, name) {
+  assertSafeCwd(cwd);
+  if (!isValidBranchName(name)) {
+    throw new Error(`Invalid branch name: ${name}`);
+  }
+  const current = getCurrentBranch(cwd);
+  if (current === name) {
+    return;
+  }
+  if (branchExists(cwd, name)) {
+    const result = spawnSync3("git", ["checkout", name], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    if (result.status !== 0) {
+      throw new Error(`Failed to checkout branch '${name}' in ${cwd}: ${result.stderr.trim()}`);
+    }
+  } else {
+    const result = spawnSync3("git", ["checkout", "-b", name], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    if (result.status !== 0) {
+      throw new Error(`Failed to create branch '${name}' in ${cwd}: ${result.stderr.trim()}`);
+    }
+  }
+}
+function verifyCurrentBranch(cwd, expected) {
+  const current = getCurrentBranch(cwd);
+  return current === expected;
+}
+function getDefaultBranch(cwd) {
+  assertSafeCwd(cwd);
+  const result = spawnSync3("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (result.status === 0) {
+    const ref = result.stdout.trim();
+    const parts = ref.split("/");
+    return parts[parts.length - 1] ?? "main";
+  }
+  const stderr = result.stderr.trim();
+  if (stderr.includes("is not a symbolic ref") || stderr.includes("No such ref")) {
+    if (branchExists(cwd, "main")) return "main";
+    if (branchExists(cwd, "master")) return "master";
+    return "main";
+  }
+  throw new Error(`Failed to detect default branch in ${cwd}: ${stderr}`);
+}
+function hasUncommittedChanges(cwd) {
+  assertSafeCwd(cwd);
+  const result = spawnSync3("git", ["status", "--porcelain"], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (result.status !== 0) {
+    throw new Error(`Failed to check git status in ${cwd}: ${result.stderr.trim()}`);
+  }
+  return result.stdout.trim().length > 0;
+}
+function generateBranchName(sprintId) {
+  return `ralphctl/${sprintId}`;
+}
+function isGhAvailable() {
+  const result = spawnSync3("gh", ["--version"], {
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  return result.status === 0;
+}
+function isGlabAvailable() {
+  const result = spawnSync3("glab", ["--version"], {
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  return result.status === 0;
+}
+
+// src/ai/runner.ts
+async function promptBranchStrategy(sprintId) {
+  const autoBranch = generateBranchName(sprintId);
+  const strategy = await select2({
+    message: "How should this sprint manage branches?",
+    choices: [
+      {
+        name: `Create sprint branch: ${autoBranch} (Recommended)`,
+        value: "auto"
+      },
+      {
+        name: "Keep current branch (no branch management)",
+        value: "keep"
+      },
+      {
+        name: "Custom branch name",
+        value: "custom"
+      }
+    ]
+  });
+  if (strategy === "keep") return null;
+  if (strategy === "auto") return autoBranch;
+  const customName = await input2({
+    message: "Enter branch name:",
+    validate: (value) => {
+      if (!value.trim()) return "Branch name cannot be empty";
+      if (!isValidBranchName(value.trim())) {
+        return "Invalid branch name. Use alphanumeric characters, hyphens, underscores, dots, and slashes.";
+      }
+      return true;
+    }
+  });
+  return customName.trim();
+}
+async function resolveBranch(sprintId, sprint, options) {
+  if (options.branchName) return options.branchName;
+  if (options.branch) return generateBranchName(sprintId);
+  if (sprint.branch) return sprint.branch;
+  return promptBranchStrategy(sprintId);
+}
+async function ensureSprintBranches(sprintId, sprint, branchName) {
+  if (!isValidBranchName(branchName)) {
+    throw new Error(`Invalid branch name: ${branchName}`);
+  }
+  const tasks = await getTasks(sprintId);
+  const remainingTasks = tasks.filter((t) => t.status !== "done");
+  const uniquePaths = [...new Set(remainingTasks.map((t) => t.projectPath))];
+  if (uniquePaths.length === 0) return;
+  for (const projectPath of uniquePaths) {
+    try {
+      if (hasUncommittedChanges(projectPath)) {
+        throw new Error(
+          `Repository at ${projectPath} has uncommitted changes. Commit or stash them before starting the sprint.`
+        );
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("uncommitted changes")) {
+        throw err;
+      }
+      log.dim(`  Skipping ${projectPath} \u2014 not a git repository`);
+      continue;
+    }
+  }
+  for (const projectPath of uniquePaths) {
+    try {
+      const currentBranch = getCurrentBranch(projectPath);
+      if (currentBranch === branchName) {
+        log.dim(`  Already on branch '${branchName}' in ${projectPath}`);
+      } else {
+        createAndCheckoutBranch(projectPath, branchName);
+        log.success(`  Branch '${branchName}' ready in ${projectPath}`);
+      }
+    } catch (err) {
+      throw new Error(
+        `Failed to create branch '${branchName}' in ${projectPath}: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err }
+      );
+    }
+  }
+  if (sprint.branch !== branchName) {
+    sprint.branch = branchName;
+    await saveSprint(sprint);
+  }
+}
+function verifySprintBranch(projectPath, expectedBranch) {
+  try {
+    if (verifyCurrentBranch(projectPath, expectedBranch)) {
+      return true;
+    }
+    log.dim(`  Branch mismatch in ${projectPath} \u2014 checking out '${expectedBranch}'`);
+    createAndCheckoutBranch(projectPath, expectedBranch);
+    return verifyCurrentBranch(projectPath, expectedBranch);
+  } catch {
+    return false;
+  }
+}
+async function runCheckScripts(sprintId, sprint, refreshCheck = false) {
+  const results = /* @__PURE__ */ new Map();
+  const tasks = await getTasks(sprintId);
+  const remainingTasks = tasks.filter((t) => t.status !== "done");
+  const uniquePaths = [...new Set(remainingTasks.map((t) => t.projectPath))];
+  if (uniquePaths.length === 0) {
+    return { success: true, results };
+  }
+  for (const projectPath of uniquePaths) {
+    const taskForPath = remainingTasks.find((t) => t.projectPath === projectPath);
+    if (!taskForPath) continue;
+    const project = await getProjectForTask(taskForPath, sprint);
+    const checkScript = getEffectiveCheckScript(project, projectPath);
+    const repo = project?.repositories.find((r) => r.path === projectPath);
+    const repoName = repo?.name ?? projectPath;
+    if (!checkScript) {
+      log.dim(`  No check script for ${repoName} \u2014 configure via 'project add'`);
+      results.set(projectPath, { ran: false, reason: "no-script" });
+      continue;
+    }
+    const previousRun = sprint.checkRanAt[projectPath];
+    if (previousRun && !refreshCheck) {
+      log.dim(`  Check already ran for ${repoName} at ${previousRun} \u2014 skipping`);
+      results.set(projectPath, { ran: true, script: checkScript });
+      continue;
+    }
+    log.info(`
+Running check for ${repoName}: ${checkScript}`);
+    const hookResult = runLifecycleHook(projectPath, checkScript, "sprintStart");
+    if (!hookResult.passed) {
+      return {
+        success: false,
+        error: `Check failed for ${repoName}: ${checkScript}
+${hookResult.output}`
+      };
+    }
+    sprint.checkRanAt[projectPath] = (/* @__PURE__ */ new Date()).toISOString();
+    await saveSprint(sprint);
+    log.success(`Check complete: ${repoName}`);
+    results.set(projectPath, { ran: true, script: checkScript });
+  }
+  return { success: true, results };
+}
+function shouldRunParallel(options) {
+  if (options.session) return false;
+  if (options.step) return false;
+  if (options.concurrency === 1) return false;
+  return true;
+}
+async function runSprint(sprintId, options) {
+  const id = await resolveSprintId(sprintId);
+  let sprint = await getSprint(id);
+  if (sprint.status === "draft" && !options.force) {
+    const unrefinedTickets = getPendingRequirements(sprint.tickets);
+    if (unrefinedTickets.length > 0) {
+      showWarning(
+        `Sprint has ${String(unrefinedTickets.length)} unrefined ticket${unrefinedTickets.length !== 1 ? "s" : ""}:`
+      );
+      for (const ticket of unrefinedTickets) {
+        log.item(`${formatTicketId(ticket)} \u2014 ${ticket.title}`);
+      }
+      log.newline();
+      const shouldContinue = await confirm5({
+        message: "Start anyway without refining?",
+        default: false
+      });
+      if (!shouldContinue) {
+        log.dim("Run 'sprint refine' first, or use --force to skip this check.");
+        log.newline();
+        return void 0;
+      }
+    }
+  }
+  if (sprint.status === "draft" && !options.force) {
+    const tasks = await getTasks(id);
+    const ticketIdsWithTasks = new Set(tasks.map((t) => t.ticketId).filter(Boolean));
+    const unplannedTickets = sprint.tickets.filter(
+      (t) => t.requirementStatus === "approved" && !ticketIdsWithTasks.has(t.id)
+    );
+    if (unplannedTickets.length > 0) {
+      showWarning("Sprint has refined tickets with no planned tasks:");
+      for (const ticket of unplannedTickets) {
+        log.item(`${formatTicketId(ticket)} \u2014 ${ticket.title}`);
+      }
+      log.newline();
+      const shouldContinue = await confirm5({
+        message: "Start anyway without planning?",
+        default: false
+      });
+      if (!shouldContinue) {
+        log.dim("Run 'sprint plan' first, or use --force to skip this check.");
+        log.newline();
+        return void 0;
+      }
+    }
+  }
+  const branchName = await resolveBranch(id, sprint, options);
+  if (sprint.status === "draft") {
+    sprint = await activateSprint(id);
+  }
+  assertSprintStatus(sprint, ["active"], "start");
+  printHeader("Sprint Start");
+  log.info(`Sprint: ${sprint.name}`);
+  log.info(`ID:     ${sprint.id}`);
+  const modes = [];
+  if (options.session) {
+    modes.push("session");
+  } else {
+    modes.push("headless");
+  }
+  if (options.step) {
+    modes.push("step-by-step");
+  }
+  if (options.noCommit) {
+    modes.push("no-commit");
+  }
+  const parallel = shouldRunParallel(options);
+  if (parallel) {
+    modes.push("parallel");
+  }
+  log.dim(`Mode: ${modes.join(", ")}`);
+  if (options.count) {
+    log.dim(`Limit: ${String(options.count)} task(s)`);
+  }
+  if (branchName) {
+    log.info(`Branch: ${branchName}`);
+  }
+  if (branchName) {
+    try {
+      await ensureSprintBranches(id, sprint, branchName);
+    } catch (err) {
+      log.newline();
+      showError(err instanceof Error ? err.message : String(err));
+      log.newline();
+      return void 0;
+    }
+  }
+  try {
+    await reorderByDependencies(id);
+    log.dim("Tasks reordered by dependencies");
+  } catch (err) {
+    if (err instanceof DependencyCycleError) {
+      log.newline();
+      showWarning(err.message);
+      log.dim("Fix the dependency cycle before starting.");
+      log.newline();
+      return void 0;
+    }
+    throw err;
+  }
+  const checkResult = await runCheckScripts(id, sprint, options.refreshCheck);
+  if (!checkResult.success) {
+    log.newline();
+    showError(checkResult.error);
+    log.newline();
+    return void 0;
+  }
+  const summary = parallel ? await executeTaskLoopParallel(id, options, checkResult.results) : await executeTaskLoop(id, options, checkResult.results);
+  printHeader("Summary");
+  log.info(`Completed: ${String(summary.completed)} task(s)`);
+  log.info(`Remaining: ${String(summary.remaining)} task(s)`);
+  if (await areAllTasksDone(id)) {
+    terminalBell();
+    showSuccess("All tasks in sprint are done!");
+    showRandomQuote();
+    const shouldClose = await confirm5({
+      message: "Close the sprint?",
+      default: true
+    });
+    if (shouldClose) {
+      await closeSprint(id);
+      showSuccess(`Sprint closed: ${id}`);
+    }
+  } else if (summary.stopReason === "all_blocked") {
+    log.newline();
+    showWarning("All remaining tasks are blocked by dependencies.");
+    const remaining = await getRemainingTasks(id);
+    const blockedTasks = remaining.filter((t) => t.blockedBy.length > 0);
+    if (blockedTasks.length > 0) {
+      log.dim("Blocked tasks:");
+      for (const t of blockedTasks.slice(0, 5)) {
+        log.item(`${t.name} (blocked by: ${t.blockedBy.join(", ")})`);
+      }
+      if (blockedTasks.length > 5) {
+        log.dim(`  ... and ${String(blockedTasks.length - 5)} more`);
+      }
+    }
+  }
+  log.newline();
+  return summary;
+}
+
+// src/commands/sprint/start.ts
+function parseArgs3(args) {
+  const options = {
+    step: false,
+    count: null,
+    session: false,
+    noCommit: false
+  };
+  let sprintId;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-t" || arg === "--step") {
+      options.step = true;
+    } else if (arg === "-s" || arg === "--session") {
+      options.session = true;
+    } else if (arg === "--no-commit") {
+      options.noCommit = true;
+    } else if (arg === "-c" || arg === "--count") {
+      const countStr = args[++i];
+      if (!countStr) {
+        throw new Error("--count requires a number");
+      }
+      const count = parseInt(countStr, 10);
+      if (isNaN(count) || count < 1 || count > 1e4) {
+        throw new Error("--count must be an integer between 1 and 10000");
+      }
+      options.count = count;
+    } else if (arg === "--concurrency") {
+      const concStr = args[++i];
+      if (!concStr) {
+        throw new Error("--concurrency requires a number");
+      }
+      const conc = parseInt(concStr, 10);
+      if (isNaN(conc) || conc < 1 || conc > 10) {
+        throw new Error("--concurrency must be an integer between 1 and 10");
+      }
+      options.concurrency = conc;
+    } else if (arg === "--max-retries") {
+      const retryStr = args[++i];
+      if (!retryStr) {
+        throw new Error("--max-retries requires a number");
+      }
+      const retries = parseInt(retryStr, 10);
+      if (isNaN(retries) || retries < 0 || retries > 20) {
+        throw new Error("--max-retries must be an integer between 0 and 20");
+      }
+      options.maxRetries = retries;
+    } else if (arg === "--fail-fast") {
+      options.failFast = true;
+    } else if (arg === "--no-fail-fast") {
+      options.failFast = false;
+    } else if (arg === "-f" || arg === "--force") {
+      options.force = true;
+    } else if (arg === "--refresh-check") {
+      options.refreshCheck = true;
+    } else if (arg === "-b" || arg === "--branch") {
+      options.branch = true;
+    } else if (arg === "--branch-name") {
+      const nameStr = args[++i];
+      if (!nameStr) {
+        throw new Error("--branch-name requires a value");
+      }
+      options.branchName = nameStr;
+    } else if (!arg?.startsWith("-")) {
+      sprintId = arg;
+    }
+  }
+  return { sprintId, options };
+}
+async function sprintStartCommand(args) {
+  let sprintId;
+  let options;
+  try {
+    const parsed = parseArgs3(args);
+    sprintId = parsed.sprintId;
+    options = parsed.options;
+  } catch (err) {
+    if (err instanceof Error) {
+      showError(err.message);
+      log.newline();
+    }
+    exitWithCode(EXIT_ERROR);
+  }
+  try {
+    const summary = await runSprint(sprintId, options);
+    if (summary) {
+      exitWithCode(summary.exitCode);
+    }
+  } catch (err) {
+    if (err instanceof SprintNotFoundError) {
+      showError(`Sprint not found: ${sprintId ?? "unknown"}`);
+      log.newline();
+      exitWithCode(EXIT_ERROR);
+    } else if (err instanceof SprintStatusError) {
+      showError(err.message);
+      log.newline();
+      exitWithCode(EXIT_ERROR);
+    } else if (err instanceof Error && err.message.includes("No sprint specified")) {
+      showWarning("No sprint specified and no active sprint set.");
+      showNextStep("ralphctl sprint start <id>", "specify a sprint ID");
+      log.newline();
+      exitWithCode(EXIT_NO_TASKS);
+    } else {
+      throw err;
+    }
+  }
+}
+
+export {
+  TaskNotFoundError,
+  getTasks,
+  saveTasks,
+  getTask,
+  addTask,
+  removeTask,
+  updateTaskStatus,
+  getNextTask,
+  reorderTask,
+  listTasks,
+  areAllTasksDone,
+  validateImportTasks,
+  selectProject,
+  selectProjectRepository,
+  selectSprint,
+  selectTicket,
+  selectTask,
+  selectTaskStatus,
+  inputPositiveInt,
+  selectProjectPaths,
+  buildTicketRefinePrompt,
+  buildIdeatePrompt,
+  buildIdeateAutoPrompt,
+  exportRequirementsToMarkdown,
+  resolveProvider,
+  providerDisplayName,
+  getActiveProvider,
+  spawnInteractive,
+  spawnHeadless,
+  extractJsonObject,
+  formatTicketForPrompt,
+  parseRequirementsFile,
+  runAiSession,
+  sprintRefineCommand,
+  getTaskImportSchema,
+  parsePlanningBlocked,
+  parseTasksJson,
+  renderParsedTasksTable,
+  importTasks,
+  sprintPlanCommand,
+  getCurrentBranch,
+  branchExists,
+  getDefaultBranch,
+  isGhAvailable,
+  isGlabAvailable,
+  sprintStartCommand
+};