@ulpi/cli 0.1.5 → 0.1.6

package/dist/chunk-EJ7TW77N.js

@@ -0,0 +1,1418 @@
+import {
+  getTrackerRegistry
+} from "./chunk-S6ANCSYO.js";
+import {
+  getAgentRegistry
+} from "./chunk-IZPJHSPX.js";
+import {
+  OutputBuffer
+} from "./chunk-SEU7WWNQ.js";
+
+// ../../packages/loop-engine/dist/index.js
+import { execFileSync } from "child_process";
+var DEFAULT_ENGINE_CONFIG = {
+  maxRetries: 3,
+  retryDelayMs: 5e3,
+  timeout: 0,
+  maxIterations: 0,
+  iterationDelayMs: 0,
+  errorStrategy: "retry",
+  rateLimit: {
+    enabled: true,
+    maxRetries: 3,
+    baseBackoffMs: 5e3,
+    recoverPrimaryBetweenIterations: true
+  },
+  agentConfig: {}
+};
+var COMMON_PATTERNS = [
+  // HTTP 429 — must appear in error/HTTP context, not just any "429"
+  {
+    pattern: /(?:HTTP|status|error|code|response)[\s:]*429|429\s*(?:too many|rate limit|error)/i,
+    retryAfterPattern: /retry[- ]?after[:\s]+(\d+)\s*s/i
+  },
+  // Generic rate limit phrases
+  {
+    pattern: /rate[- ]limit/i,
+    retryAfterPattern: /retry[- ]?after[:\s]+(\d+)\s*s/i
+  },
+  // Too many requests
+  {
+    pattern: /too many requests/i,
+    retryAfterPattern: /(\d+)\s*seconds?/i
+  },
+  // Quota exceeded
+  {
+    pattern: /quota[- ]?exceeded/i,
+    retryAfterPattern: /(\d+)\s*seconds?/i
+  },
+  // Overloaded
+  {
+    pattern: /\boverloaded\b/i,
+    retryAfterPattern: /(\d+)\s*seconds?/i
+  }
+];
+var AGENT_SPECIFIC_PATTERNS = {
+  claude: [
+    {
+      pattern: /anthropic.*rate[- ]?limit/i,
+      retryAfterPattern: /retry[- ]?after[:\s]+(\d+)\s*s/i
+    },
+    {
+      pattern: /API rate limit exceeded/i,
+      retryAfterPattern: /wait[:\s]+(\d+)\s*s/i
+    },
+    {
+      pattern: /claude.*is currently overloaded/i,
+      retryAfterPattern: /(\d+)\s*seconds?/i
+    },
+    {
+      pattern: /api[- ]?error.*429/i,
+      retryAfterPattern: /retry[- ]?after[:\s]+(\d+)/i
+    }
+  ],
+  opencode: [
+    {
+      pattern: /openai.*rate[- ]?limit/i,
+      retryAfterPattern: /retry[- ]?after[:\s]+(\d+)\s*s/i
+    },
+    {
+      pattern: /tokens per minute/i,
+      retryAfterPattern: /(\d+)\s*seconds?/i
+    },
+    {
+      pattern: /requests per minute/i,
+      retryAfterPattern: /(\d+)\s*seconds?/i
+    }
+  ],
+  gemini: [
+    {
+      pattern: /google.*rate[- ]?limit/i,
+      retryAfterPattern: /(\d+)\s*seconds?/i
+    },
+    {
+      pattern: /resource[- ]?exhausted/i,
+      retryAfterPattern: /(\d+)\s*seconds?/i
+    }
+  ]
+};
+var RATE_LIMIT_EXIT_CODES = /* @__PURE__ */ new Set([1, 2, 429]);
+function detectRateLimit(input) {
+  const { stderr, exitCode, agentId } = input;
+  if (!stderr.trim() && exitCode === 0) {
+    return { isRateLimit: false };
+  }
+  const patterns = [...COMMON_PATTERNS];
+  if (agentId && AGENT_SPECIFIC_PATTERNS[agentId]) {
+    patterns.push(...AGENT_SPECIFIC_PATTERNS[agentId]);
+  }
+  for (const { pattern, retryAfterPattern } of patterns) {
+    if (pattern.test(stderr)) {
+      const message = extractMessage(stderr, pattern);
+      const retryAfter = retryAfterPattern ? extractRetryAfter(stderr, retryAfterPattern) : void 0;
+      return { isRateLimit: true, message, retryAfter };
+    }
+  }
+  if (exitCode !== void 0 && exitCode !== 0 && RATE_LIMIT_EXIT_CODES.has(exitCode)) {
+    const looseMessage = looseRateLimitCheck(stderr);
+    if (looseMessage) {
+      return {
+        isRateLimit: true,
+        message: looseMessage,
+        retryAfter: extractAnyRetryAfter(stderr)
+      };
+    }
+  }
+  return { isRateLimit: false };
+}
+function calculateBackoff(attempt, baseBackoffMs, retryAfter) {
+  if (retryAfter !== void 0 && retryAfter > 0) {
+    return { delayMs: retryAfter * 1e3, usedRetryAfter: true };
+  }
+  const delayMs = baseBackoffMs * Math.pow(3, attempt);
+  return { delayMs, usedRetryAfter: false };
+}
+function shouldFallback(limitedAgents, fallbackAgents) {
+  for (const agent of fallbackAgents) {
+    if (!limitedAgents.has(agent)) {
+      return agent;
+    }
+  }
+  return null;
+}
+function extractMessage(output, pattern) {
+  const match = output.match(pattern);
+  if (!match) return "Rate limit detected";
+  const matchIndex = match.index ?? 0;
+  const start = Math.max(0, matchIndex - 50);
+  const end = Math.min(output.length, matchIndex + match[0].length + 100);
+  let message = output.slice(start, end).trim().replace(/\s+/g, " ");
+  if (message.length > 200) {
+    message = message.slice(0, 200) + "...";
+  }
+  return message;
+}
+function extractRetryAfter(output, pattern) {
+  const match = output.match(pattern);
+  if (match?.[1]) {
+    const seconds = parseInt(match[1], 10);
+    if (!isNaN(seconds) && seconds > 0 && seconds < 3600) {
+      return seconds;
+    }
+  }
+  return void 0;
+}
+function extractAnyRetryAfter(output) {
+  const patterns = [
+    /retry[- ]?after[:\s]+(\d+)\s*s/i,
+    /wait[:\s]+(\d+)\s*s/i,
+    /try again in[:\s]+(\d+)\s*s/i,
+    /(\d+)\s*seconds?(?:\s*(?:before|until|wait))/i
+  ];
+  for (const pattern of patterns) {
+    const match = output.match(pattern);
+    if (match?.[1]) {
+      const seconds = parseInt(match[1], 10);
+      if (!isNaN(seconds) && seconds > 0 && seconds < 3600) {
+        return seconds;
+      }
+    }
+  }
+  return void 0;
+}
+function looseRateLimitCheck(output) {
+  const loosePatterns = [
+    /throttl/i,
+    /limit.*exceeded/i,
+    /exceeded.*limit/i,
+    /capacity/i,
+    /backoff/i
+  ];
+  for (const pattern of loosePatterns) {
+    if (pattern.test(output)) {
+      return extractMessage(output, pattern);
+    }
+  }
+  return null;
+}
+function hasUncommittedChanges(cwd) {
+  try {
+    const output = execFileSync("git", ["status", "--porcelain"], {
+      cwd,
+      encoding: "utf-8",
+      timeout: 1e4
+    });
+    return output.trim().length > 0;
+  } catch (err) {
+    throw new Error(
+      `git status failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function autoCommitChanges(options) {
+  const { workingDir, taskId, taskTitle } = options;
+  let hasChanges;
+  try {
+    hasChanges = hasUncommittedChanges(workingDir);
+  } catch (err) {
+    return {
+      committed: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+  if (!hasChanges) {
+    return {
+      committed: false,
+      skipReason: "no uncommitted changes"
+    };
+  }
+  try {
+    execFileSync("git", ["add", "-A"], {
+      cwd: workingDir,
+      encoding: "utf-8",
+      timeout: 3e4
+    });
+  } catch (err) {
+    return {
+      committed: false,
+      error: `git add failed: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const commitMessage = `feat: ${taskId} - ${taskTitle}`;
+  try {
+    execFileSync("git", ["commit", "-m", commitMessage], {
+      cwd: workingDir,
+      encoding: "utf-8",
+      timeout: 3e4
+    });
+  } catch (err) {
+    return {
+      committed: false,
+      error: `git commit failed: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  let commitSha;
+  try {
+    commitSha = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: workingDir,
+      encoding: "utf-8",
+      timeout: 5e3
+    }).trim();
+  } catch {
+  }
+  return {
+    committed: true,
+    commitMessage,
+    commitSha
+  };
+}
+async function injectMemories(taskDescription, projectDir) {
+  try {
+    const { searchMemory, formatMemoriesForAgent } = await import("./dist-JLU26AB6.js");
+    const result = await searchMemory(projectDir, {
+      query: taskDescription,
+      limit: 5
+    });
+    if (result.results.length === 0) return "";
+    const entries = result.results.map((r) => r.entry);
+    const formatted = formatMemoriesForAgent(entries);
+    return formatted;
+  } catch {
+    return "";
+  }
+}
+async function captureIterationMemory(iterationResult, projectDir) {
+  if (iterationResult.status !== "completed" || !iterationResult.taskCompleted) {
+    return;
+  }
+  try {
+    const { rememberMemory, generateMemoryId, isMemoryEnabled } = await import("./dist-JLU26AB6.js");
+    if (!isMemoryEnabled(projectDir)) return;
+    const { MemoryEntrySchema } = await import("./dist-KUCI6JFE.js");
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const taskTitle = iterationResult.task.title;
+    const taskId = iterationResult.task.id;
+    const summary = `Task "${taskTitle}" (${taskId}) completed in ${iterationResult.durationMs}ms${iterationResult.commitSha ? ` with commit ${iterationResult.commitSha}` : ""}`;
+    const detail = [
+      `Task: ${taskTitle}`,
+      `Description: ${iterationResult.task.description ?? "N/A"}`,
+      `Duration: ${iterationResult.durationMs}ms`,
+      `Iteration: ${iterationResult.iteration}`,
+      iterationResult.commitSha ? `Commit: ${iterationResult.commitSha}` : null
+    ].filter(Boolean).join("\n");
+    const entry = MemoryEntrySchema.parse({
+      id: generateMemoryId("LESSON", summary),
+      type: "LESSON",
+      summary,
+      detail,
+      importance: "low",
+      tags: ["loop-engine", `task:${taskId}`],
+      relatedFiles: [],
+      source: {
+        type: "explicit",
+        sessionId: `loop-${taskId}`
+      },
+      createdAt: now,
+      updatedAt: now,
+      lastAccessedAt: now,
+      accessCount: 0
+    });
+    await rememberMemory(projectDir, entry);
+  } catch {
+  }
+}
+async function getSemanticContext(taskDescription, projectDir) {
+  try {
+    const { searchCode } = await import("./dist-YFFG2ZD6.js");
+    const result = await searchCode(projectDir, taskDescription, {
+      limit: 8,
+      includeTests: false,
+      includeDocs: false
+    });
+    if (result.results.length === 0) return "";
+    const lines = [];
+    for (const item of result.results) {
+      const lineRange = item.startLine && item.endLine ? ` (L${item.startLine}-${item.endLine})` : "";
+      const scoreStr = item.score ? ` [relevance: ${item.score.toFixed(2)}]` : "";
+      lines.push(`### ${item.filePath}${lineRange}${scoreStr}`);
+      if (item.snippet) {
+        const snippet = item.snippet.length > 500 ? item.snippet.slice(0, 500) + "\n..." : item.snippet;
+        lines.push("```");
+        lines.push(snippet);
+        lines.push("```");
+      }
+      lines.push("");
+    }
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}
+async function getCodemapAvailability(projectDir) {
+  try {
+    const { getCodemapStatus } = await import("./dist-YFFG2ZD6.js");
+    const status = getCodemapStatus(projectDir);
+    return status.initialized && status.totalChunks > 0;
+  } catch {
+    return false;
+  }
+}
+var COMPLETION_SIGNAL = "<completion>DONE</completion>";
+var COMPLETION_SIGNAL_PATTERN = /<completion>\s*DONE\s*<\/completion>/i;
+function buildPrompt(options) {
+  const { task, additionalContext } = options;
+  const lines = [];
+  lines.push("## Task");
+  lines.push(`**ID**: ${task.id}`);
+  lines.push(`**Title**: ${task.title}`);
+  if (task.type) {
+    lines.push(`**Type**: ${task.type}`);
+  }
+  if (task.priority !== void 0) {
+    const priorityLabel = formatPriority(task.priority);
+    lines.push(`**Priority**: ${priorityLabel}`);
+  }
+  if (task.labels && task.labels.length > 0) {
+    lines.push(`**Labels**: ${task.labels.join(", ")}`);
+  }
+  if (task.dependsOn && task.dependsOn.length > 0) {
+    lines.push(`**Depends on**: ${task.dependsOn.join(", ")}`);
+  }
+  if (task.description) {
+    lines.push("");
+    lines.push("## Description");
+    lines.push(task.description);
+  }
+  if (additionalContext) {
+    lines.push("");
+    lines.push("## Context");
+    lines.push(additionalContext);
+  }
+  lines.push("");
+  lines.push("## Completion");
+  lines.push(
+    "When you have completed this task, signal completion by outputting the following on its own line:"
+  );
+  lines.push("");
+  lines.push("```");
+  lines.push(COMPLETION_SIGNAL);
+  lines.push("```");
+  lines.push("");
+  lines.push(
+    "Only emit this signal when the task is fully complete. Do not emit it if you encounter a blocker or need clarification."
+  );
+  return lines.join("\n");
+}
+async function enrichPromptContext(taskDescription, workingDir) {
+  const sections = [];
+  const [memoryContext, codemapContext] = await Promise.allSettled([
+    injectMemories(taskDescription, workingDir),
+    getSemanticContext(taskDescription, workingDir)
+  ]);
+  const memoryStr = memoryContext.status === "fulfilled" ? memoryContext.value : "";
+  const codemapStr = codemapContext.status === "fulfilled" ? codemapContext.value : "";
+  if (memoryStr) {
+    sections.push("## Relevant Learnings from Previous Sessions");
+    sections.push(memoryStr);
+  }
+  if (codemapStr) {
+    sections.push("## Relevant Code Context");
+    sections.push(codemapStr);
+  }
+  return sections.join("\n\n");
+}
+function formatPriority(priority) {
+  switch (priority) {
+    case 0:
+      return "Critical (P0)";
+    case 1:
+      return "High (P1)";
+    case 2:
+      return "Medium (P2)";
+    case 3:
+      return "Low (P3)";
+    case 4:
+      return "Minimal (P4)";
+    default:
+      return `P${priority}`;
+  }
+}
+var COMPLETION_SIGNAL_JSON_SAFE = /<completion>\s*DONE\s*<\\?\/completion>/i;
+function detectCompletionSignal(stdout) {
+  if (COMPLETION_SIGNAL_PATTERN.test(stdout)) return true;
+  if (COMPLETION_SIGNAL_JSON_SAFE.test(stdout)) return true;
+  const extracted = extractTextFromStreamJson(stdout);
+  if (extracted && COMPLETION_SIGNAL_PATTERN.test(extracted)) return true;
+  return false;
+}
+function extractTextFromStreamJson(stdout) {
+  const lines = stdout.split("\n");
+  const texts = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed[0] !== "{") continue;
+    try {
+      const obj = JSON.parse(trimmed);
+      if (obj.type === "result") {
+        if (typeof obj.result === "string") {
+          texts.push(obj.result);
+        } else if (obj.result?.content) {
+          for (const block of obj.result.content) {
+            if (block.type === "text" && typeof block.text === "string") {
+              texts.push(block.text);
+            }
+          }
+        }
+      }
+      if (obj.type === "assistant" && obj.message?.content) {
+        for (const block of obj.message.content) {
+          if (block.type === "text" && typeof block.text === "string") {
+            texts.push(block.text);
+          }
+        }
+      }
+      if (obj.type === "content_block_delta" && typeof obj.delta?.text === "string") {
+        texts.push(obj.delta.text);
+      }
+    } catch {
+    }
+  }
+  return texts.join("\n");
+}
+function detectStreamJsonSuccess(stdout) {
+  if (!stdout.includes('"type":"result"')) return false;
+  const lines = stdout.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line || line[0] !== "{") continue;
+    try {
+      const obj = JSON.parse(line);
+      if (obj.type === "result" && obj.subtype === "success" && !obj.is_error) {
+        return true;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+function isTaskComplete(stdout) {
+  if (detectCompletionSignal(stdout)) return true;
+  if (detectStreamJsonSuccess(stdout)) return true;
+  return false;
+}
+async function evaluateBeforeExecution(taskId, agentType, projectDir) {
+  try {
+    const { loadRulesSync, evaluateRules } = await import("./dist-GTEJUBBT.js");
+    const { projectGuardsFile } = await import("./dist-NUXMDXZ3.js");
+    const rulesPath = projectGuardsFile(projectDir);
+    const rules = loadRulesSync(rulesPath);
+    if (!rules) {
+      return { allowed: true };
+    }
+    const syntheticInput = {
+      session_id: `loop-${taskId}`,
+      transcript_path: "",
+      cwd: projectDir,
+      permission_mode: "default",
+      hook_event_name: "PreToolUse",
+      tool_name: "Bash",
+      tool_input: {
+        command: `ulpi-loop-agent:${agentType}:${taskId}`
+      }
+    };
+    const syntheticState = {
+      sessionId: `loop-${taskId}`,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      projectDir,
+      phase: "active",
+      filesRead: [],
+      filesWritten: [],
+      filesDeleted: [],
+      commandsRun: [],
+      testsRun: false,
+      testsPassed: null,
+      lintRun: false,
+      lintPassed: null,
+      buildRun: false,
+      buildPassed: null,
+      formatterRun: false,
+      branchCreated: false,
+      planApproved: false,
+      rulesEnforced: 0,
+      actionsBlocked: 0,
+      autoActionsRun: 0,
+      consecutiveBlocks: 0,
+      lastNotifications: {}
+    };
+    const result = evaluateRules(
+      syntheticInput,
+      rules,
+      syntheticState,
+      projectDir
+    );
+    if (result.action === "block") {
+      return {
+        allowed: false,
+        reason: result.stderrMessage ?? "Blocked by guards rule"
+      };
+    }
+    return { allowed: true };
+  } catch {
+    return { allowed: true };
+  }
+}
+async function getGovernanceConfig(projectDir) {
+  try {
+    const { loadRulesSync } = await import("./dist-GTEJUBBT.js");
+    const { projectGuardsFile } = await import("./dist-NUXMDXZ3.js");
+    const rulesPath = projectGuardsFile(projectDir);
+    const rules = loadRulesSync(rulesPath);
+    if (!rules) {
+      return {
+        available: false,
+        autoCommitAllowed: true,
+        permissionDefaults: "allow",
+        dangerousCommandBlocking: true
+      };
+    }
+    const hasDenyOnGit = Object.values(rules.permissions).some(
+      (r) => r.enabled && r.decision === "deny" && r.command_pattern && /git\s+(commit|push)/.test(r.command_pattern)
+    );
+    const denyCount = Object.values(rules.permissions).filter(
+      (r) => r.enabled && r.decision === "deny"
+    ).length;
+    const allowCount = Object.values(rules.permissions).filter(
+      (r) => r.enabled && r.decision === "allow"
+    ).length;
+    let permissionDefaults = "allow";
+    if (denyCount > allowCount) permissionDefaults = "deny";
+    return {
+      available: true,
+      autoCommitAllowed: !hasDenyOnGit,
+      permissionDefaults,
+      dangerousCommandBlocking: true
+    };
+  } catch {
+    return {
+      available: false,
+      autoCommitAllowed: true,
+      permissionDefaults: "allow",
+      dangerousCommandBlocking: true
+    };
+  }
+}
+var PRIMARY_RECOVERY_TEST_TIMEOUT_MS = 5e3;
+var PRIMARY_RECOVERY_TEST_PROMPT = 'Reply with just the word "ok".';
+var ExecutionEngine = class {
+  config;
+  agent = null;
+  tracker = null;
+  listeners = [];
+  state;
+  currentExecution = null;
+  shouldStop = false;
+  /** Retry attempts per task (for error handling). */
+  retryCountMap = /* @__PURE__ */ new Map();
+  /** Rate-limit retry attempts per task (separate from generic retries). */
+  rateLimitRetryMap = /* @__PURE__ */ new Map();
+  /** Tasks that were skipped (to avoid retrying). */
+  skippedTasks = /* @__PURE__ */ new Set();
+  /** Agents currently rate-limited for the active task batch. */
+  rateLimitedAgents = /* @__PURE__ */ new Set();
+  /** Primary agent instance — preserved for recovery attempts. */
+  primaryAgentInstance = null;
+  /** Forced task for worker mode — engine only works on this single task. */
+  forcedTask = null;
+  /** Whether the forced task has been processed. */
+  forcedTaskProcessed = false;
+  /** Output buffers for current iteration. */
+  stdoutBuffer = new OutputBuffer();
+  stderrBuffer = new OutputBuffer();
+  constructor(config) {
+    this.config = {
+      ...DEFAULT_ENGINE_CONFIG,
+      ...config
+    };
+    this.state = this.createInitialState();
+  }
+  // ─── Public API ───
+  /**
+   * Initialize the engine: resolve agent and tracker plugins, sync tracker.
+   */
+  async initialize(options) {
+    const agentRegistry = getAgentRegistry();
+    await agentRegistry.initialize();
+    this.agent = await agentRegistry.getInstance({
+      name: this.config.agentName,
+      plugin: this.config.agentName,
+      options: this.config.agentConfig
+    });
+    const detectResult = await this.agent.detect();
+    if (!detectResult.available) {
+      throw new Error(
+        `Agent '${this.config.agentName}' not available: ${detectResult.error}`
+      );
+    }
+    this.primaryAgentInstance = this.agent;
+    this.state.activeAgent = this.config.agentName;
+    this.state.rateLimitState.currentAgent = this.config.agentName;
+    if (options?.tracker && options?.forcedTask) {
+      this.tracker = options.tracker;
+      this.forcedTask = options.forcedTask;
+      this.state.totalTasks = 1;
+      return;
+    }
+    const trackerRegistry = getTrackerRegistry();
+    await trackerRegistry.initialize();
+    this.tracker = await trackerRegistry.getInstance({
+      name: this.config.trackerName,
+      plugin: this.config.trackerName,
+      options: this.config.trackerConfig
+    });
+    await this.tracker.sync();
+    const tasks = await this.tracker.getTasks({
+      status: ["open", "in_progress"]
+    });
+    this.state.totalTasks = tasks.length;
+  }
+  /**
+   * Subscribe to engine events.
+   * Returns an unsubscribe function.
+   */
+  on(listener) {
+    this.listeners.push(listener);
+    return () => {
+      const idx = this.listeners.indexOf(listener);
+      if (idx !== -1) this.listeners.splice(idx, 1);
+    };
+  }
+  /**
+   * Get a read-only snapshot of the current engine state.
+   */
+  getState() {
+    return {
+      ...this.state,
+      elapsedMs: this.state.startedAt ? Date.now() - new Date(this.state.startedAt).getTime() : 0
+    };
+  }
+  /**
+   * Get the current engine status.
+   */
+  getStatus() {
+    return this.state.status;
+  }
+  /**
+   * Get the tracker instance for external operations.
+   */
+  getTracker() {
+    return this.tracker;
+  }
+  /**
+   * Start the execution loop.
+   */
+  async start() {
+    if (this.state.status !== "idle") {
+      throw new Error(`Cannot start engine in '${this.state.status}' state`);
+    }
+    if (!this.agent || !this.tracker) {
+      throw new Error("Engine not initialized. Call initialize() first.");
+    }
+    this.state.status = "running";
+    this.state.startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.shouldStop = false;
+    const allTasks = await this.tracker.getTasks({
+      status: ["open", "in_progress", "done"]
+    });
+    this.emit({
+      type: "engine:started",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      totalTasks: this.state.totalTasks,
+      tasks: allTasks
+    });
+    try {
+      await this.runLoop();
+    } finally {
+      const s = this.state.status;
+      if (s !== "stopped" && s !== "error") {
+        this.state.status = "idle";
+      }
+    }
+  }
+  /**
+   * Request the engine to stop after the current iteration.
+   */
+  async stop() {
+    this.shouldStop = true;
+    this.state.status = "stopping";
+    if (this.currentExecution) {
+      this.currentExecution.interrupt();
+    }
+    this.emit({
+      type: "engine:stopped",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      reason: "interrupted",
+      totalIterations: this.state.currentIteration,
+      tasksCompleted: this.state.completedTasks.length
+    });
+  }
+  /**
+   * Request to pause the execution loop after the current iteration completes.
+   */
+  pause() {
+    if (this.state.status !== "running") return;
+    this.state.status = "pausing";
+  }
+  /**
+   * Resume the execution loop from a paused state.
+   */
+  resume() {
+    if (this.state.status === "pausing") {
+      this.state.status = "running";
+      return;
+    }
+    if (this.state.status !== "paused") return;
+    this.state.status = "running";
+  }
+  /**
+   * Check if the engine is paused.
+   */
+  isPaused() {
+    return this.state.status === "paused";
+  }
+  /**
+   * Reset tasks that were marked in_progress back to open.
+   * Used during graceful shutdown.
+   */
+  async resetTasksToOpen(taskIds) {
+    if (!this.tracker || taskIds.length === 0) return 0;
+    let resetCount = 0;
+    for (const taskId of taskIds) {
+      try {
+        await this.tracker.updateTaskStatus(taskId, "open");
+        resetCount++;
+      } catch {
+      }
+    }
+    return resetCount;
+  }
+  /**
+   * Dispose of engine resources.
+   */
+  async dispose() {
+    await this.stop();
+    this.listeners = [];
+  }
+  // ─── Main Loop ───
+  async runLoop() {
+    while (!this.shouldStop) {
+      if (this.state.status === "pausing") {
+        this.state.status = "paused";
+        this.emit({
+          type: "engine:paused",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          currentIteration: this.state.currentIteration
+        });
+        while (this.state.status === "paused" && !this.shouldStop) {
+          await this.delay(100);
+        }
+        if (this.shouldStop) break;
+        this.emit({
+          type: "engine:resumed",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          fromIteration: this.state.currentIteration
+        });
+      }
+      if (this.shouldRecoverPrimaryAgent()) {
+        await this.attemptPrimaryAgentRecovery();
+      }
+      if (this.config.maxIterations > 0 && this.state.currentIteration >= this.config.maxIterations) {
+        this.emit({
+          type: "engine:stopped",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          reason: "max_iterations",
+          totalIterations: this.state.currentIteration,
+          tasksCompleted: this.state.completedTasks.length
+        });
+        break;
+      }
+      const isComplete = this.forcedTask ? this.state.completedTasks.length >= 1 : await this.tracker.isComplete();
+      if (isComplete) {
+        this.emit({
+          type: "all:complete",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          totalCompleted: this.state.completedTasks.length,
+          totalIterations: this.state.currentIteration
+        });
+        this.emit({
+          type: "engine:stopped",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          reason: "completed",
+          totalIterations: this.state.currentIteration,
+          tasksCompleted: this.state.completedTasks.length
+        });
+        break;
+      }
+      const task = await this.getNextAvailableTask();
+      if (!task) {
+        this.emit({
+          type: "engine:stopped",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          reason: "no_tasks",
+          totalIterations: this.state.currentIteration,
+          tasksCompleted: this.state.completedTasks.length
+        });
+        break;
+      }
+      const result = await this.runIterationWithErrorHandling(task);
+      if (result.status === "failed" && this.config.errorStrategy === "abort") {
+        this.emit({
+          type: "engine:stopped",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          reason: "error",
+          totalIterations: this.state.currentIteration,
+          tasksCompleted: this.state.completedTasks.length
+        });
+        break;
+      }
+      if (this.config.iterationDelayMs > 0 && !this.shouldStop) {
+        await this.delay(this.config.iterationDelayMs);
+      }
+    }
+  }
+  // ─── Task Selection ───
+  async getNextAvailableTask() {
+    if (this.forcedTask) {
+      if (this.state.completedTasks.length >= 1 || this.forcedTaskProcessed) {
+        return null;
+      }
+      return this.forcedTask;
+    }
+    const task = await this.tracker.getNextTask({
+      status: ["open", "in_progress"],
+      excludeIds: this.skippedTasks.size > 0 ? Array.from(this.skippedTasks) : void 0
+    });
+    return task ?? null;
+  }
+  // ─── Iteration with Error Handling ───
+  async runIterationWithErrorHandling(task) {
+    let result = await this.runIteration(task);
+    this.state.iterations.push(result);
+    if (result.status !== "failed") {
+      if (result.taskCompleted) {
+        this.state.completedTasks.push(task.id);
+        this.retryCountMap.delete(task.id);
+      }
+      return result;
+    }
+    const errorMessage = result.error ?? "Unknown error";
+    switch (this.config.errorStrategy) {
+      case "retry": {
+        const currentRetries = this.retryCountMap.get(task.id) ?? 0;
+        if (currentRetries < this.config.maxRetries) {
+          this.emit({
+            type: "iteration:failed",
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            iteration: this.state.currentIteration,
+            error: errorMessage,
+            task,
+            action: "retry"
+          });
+          this.emit({
+            type: "iteration:retrying",
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            iteration: this.state.currentIteration,
+            retryAttempt: currentRetries + 1,
+            maxRetries: this.config.maxRetries,
+            task,
+            previousError: errorMessage,
+            delayMs: this.config.retryDelayMs
+          });
+          this.retryCountMap.set(task.id, currentRetries + 1);
+          if (this.config.retryDelayMs > 0 && !this.shouldStop) {
+            await this.delay(this.config.retryDelayMs);
+          }
+          if (!this.shouldStop) {
+            return this.runIterationWithErrorHandling(task);
+          }
+        } else {
+          const skipReason = `Max retries (${this.config.maxRetries}) exceeded: ${errorMessage}`;
+          this.emit({
+            type: "iteration:failed",
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            iteration: this.state.currentIteration,
+            error: skipReason,
+            task,
+            action: "skip"
+          });
+          this.emitSkipEvent(task, skipReason);
+          this.skippedTasks.add(task.id);
+          this.state.skippedTasks.push(task.id);
+          this.retryCountMap.delete(task.id);
+          if (this.forcedTask?.id === task.id) {
+            this.forcedTaskProcessed = true;
+          }
+        }
+        break;
+      }
+      case "skip": {
+        this.emit({
+          type: "iteration:failed",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          iteration: this.state.currentIteration,
+          error: errorMessage,
+          task,
+          action: "skip"
+        });
+        this.emitSkipEvent(task, errorMessage);
+        this.skippedTasks.add(task.id);
+        this.state.skippedTasks.push(task.id);
+        if (this.forcedTask?.id === task.id) {
+          this.forcedTaskProcessed = true;
+        }
+        break;
+      }
+      case "abort": {
+        this.emit({
+          type: "iteration:failed",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          iteration: this.state.currentIteration,
+          error: errorMessage,
+          task,
+          action: "abort"
+        });
+        this.state.failedTasks.push(task.id);
+        if (this.forcedTask?.id === task.id) {
+          this.forcedTaskProcessed = true;
+        }
+        break;
+      }
+    }
+    return result;
+  }
+  // ─── Single Iteration ───
+  async runIteration(task) {
+    this.state.currentIteration++;
+    this.state.currentTaskId = task.id;
+    this.stdoutBuffer.clear();
+    this.stderrBuffer.clear();
+    const startedAt = /* @__PURE__ */ new Date();
+    const iteration = this.state.currentIteration;
+    this.emit({
+      type: "iteration:started",
+      timestamp: startedAt.toISOString(),
+      iteration,
+      task
+    });
+    this.emit({
+      type: "task:selected",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      task,
+      iteration
+    });
+    try {
+      const governanceResult = await evaluateBeforeExecution(
+        task.id,
+        this.config.agentName,
+        this.config.workingDir
+      );
+      if (!governanceResult.allowed) {
+        this.emit({
+          type: "iteration:failed",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          iteration,
+          error: governanceResult.reason ?? "Blocked by governance rules",
+          task,
+          action: "skip"
+        });
+        return {
+          iteration,
+          status: "skipped",
+          task,
+          taskCompleted: false,
+          completionSignalDetected: false,
+          durationMs: (/* @__PURE__ */ new Date()).getTime() - startedAt.getTime(),
+          error: `Governance blocked: ${governanceResult.reason ?? "unknown"}`,
+          startedAt: startedAt.toISOString(),
+          endedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+      }
+    } catch {
+    }
+    await this.tracker.updateTaskStatus(task.id, "in_progress");
+    let additionalContext;
+    try {
+      const taskDesc = task.description ?? task.title;
+      additionalContext = await enrichPromptContext(
+        taskDesc,
+        this.config.sourceProjectDir ?? this.config.workingDir
+      );
+    } catch {
+    }
+    const prompt = buildPrompt({
+      task,
+      workingDir: this.config.workingDir,
+      templateName: this.config.promptTemplate,
+      additionalContext: additionalContext || void 0
+    });
+    try {
+      const handle = this.agent.execute(prompt, {
+        cwd: this.config.workingDir,
+        timeout: this.config.timeout > 0 ? this.config.timeout : void 0,
+        env: { ULPI_RUN_MODE: this.config.workerMode ? "parallel" : "loop" },
+        onStdout: (data) => {
+          this.stdoutBuffer.append(data);
+          this.emit({
+            type: "agent:output",
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            stream: "stdout",
+            data,
+            iteration
+          });
+        },
+        onStderr: (data) => {
+          this.stderrBuffer.append(data);
+          this.emit({
+            type: "agent:output",
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            stream: "stderr",
+            data,
+            iteration
+          });
+        }
+      });
+      this.currentExecution = handle;
+      const agentResult = await handle.promise;
+      this.currentExecution = null;
+      const rateLimitResult = detectRateLimit({
+        stderr: agentResult.stderr,
+        exitCode: agentResult.exitCode,
+        agentId: this.config.agentName
+      });
+      if (rateLimitResult.isRateLimit) {
+        return this.handleRateLimitInIteration(
+          task,
+          rateLimitResult,
+          iteration,
+          startedAt
+        );
+      }
+      this.rateLimitRetryMap.delete(task.id);
+      const endedAt = /* @__PURE__ */ new Date();
+      const durationMs = endedAt.getTime() - startedAt.getTime();
+      const completionSignalDetected = isTaskComplete(agentResult.stdout);
+      const taskCompleted = completionSignalDetected;
+      if (taskCompleted) {
+        await this.tracker.completeTask(task.id, {
+          taskId: task.id,
+          status: "done",
+          summary: "Completed by agent"
+        });
+        this.emit({
+          type: "task:completed",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          task,
+          iteration
+        });
+        this.rateLimitedAgents.clear();
+      }
+      let commitSha;
+      if (taskCompleted && this.config.autoCommit) {
+        commitSha = await this.handleAutoCommit(task, iteration);
+      }
+      let status;
+      if (agentResult.interrupted) {
+        status = "interrupted";
+      } else if (agentResult.status === "failed" || agentResult.status === "timeout") {
+        status = "failed";
+      } else {
+        status = "completed";
+      }
+      const result = {
+        iteration,
+        status,
+        task,
+        taskCompleted,
+        completionSignalDetected,
+        durationMs,
+        exitCode: agentResult.exitCode,
+        startedAt: startedAt.toISOString(),
+        endedAt: endedAt.toISOString(),
+        commitSha
+      };
+      this.emit({
+        type: "iteration:completed",
+        timestamp: endedAt.toISOString(),
+        result
+      });
+      return result;
+    } catch (error) {
+      const endedAt = /* @__PURE__ */ new Date();
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        iteration,
+        status: "failed",
+        task,
+        taskCompleted: false,
+        completionSignalDetected: false,
+        durationMs: endedAt.getTime() - startedAt.getTime(),
+        error: errorMessage,
+        startedAt: startedAt.toISOString(),
+        endedAt: endedAt.toISOString()
+      };
+    } finally {
+      this.state.currentTaskId = null;
+    }
+  }
+  // ─── Rate Limit Handling ───
+  async handleRateLimitInIteration(task, rateLimitResult, iteration, startedAt) {
+    const currentRetries = this.rateLimitRetryMap.get(task.id) ?? 0;
+    const maxRetries = this.config.rateLimit.maxRetries;
+    if (currentRetries < maxRetries) {
+      const { delayMs, usedRetryAfter } = calculateBackoff(
+        currentRetries,
+        this.config.rateLimit.baseBackoffMs,
+        rateLimitResult.retryAfter
+      );
+      this.rateLimitRetryMap.set(task.id, currentRetries + 1);
+      this.emit({
+        type: "iteration:rate-limited",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        iteration,
+        task,
+        retryAttempt: currentRetries + 1,
+        maxRetries,
+        delayMs,
+        rateLimitMessage: rateLimitResult.message,
+        usedRetryAfter
+      });
+      if (!this.shouldStop) {
+        await this.delay(delayMs);
+      }
+      if (!this.shouldStop) {
+        this.state.currentIteration--;
+        return this.runIteration(task);
+      }
+    }
+    this.rateLimitRetryMap.delete(task.id);
+    this.rateLimitedAgents.add(this.state.activeAgent);
+    const fallbackAgents = this.config.fallbackAgents ?? [];
+    const nextFallback = shouldFallback(this.rateLimitedAgents, fallbackAgents);
+    if (nextFallback) {
+      await this.switchToFallbackAgent(nextFallback);
+      this.state.currentIteration--;
+      return this.runIteration(task);
+    }
+    if (fallbackAgents.length > 0) {
+      this.emit({
+        type: "agent:all-limited",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        task,
+        triedAgents: Array.from(this.rateLimitedAgents)
+      });
+      this.pause();
+      this.rateLimitedAgents.clear();
+    }
+    const endedAt = /* @__PURE__ */ new Date();
+    return {
+      iteration,
+      status: "failed",
+      task,
+      taskCompleted: false,
+      completionSignalDetected: false,
+      durationMs: endedAt.getTime() - startedAt.getTime(),
+      error: `Rate limit exceeded after ${maxRetries} retries: ${rateLimitResult.message}`,
+      startedAt: startedAt.toISOString(),
+      endedAt: endedAt.toISOString()
+    };
+  }
+  // ─── Agent Switching ───
+  async switchToFallbackAgent(agentPlugin) {
+    const previousAgent = this.state.activeAgent;
+    const agentRegistry = getAgentRegistry();
+    const fallbackInstance = await agentRegistry.getInstance({
+      name: agentPlugin,
+      plugin: agentPlugin,
+      options: this.config.agentConfig
+    });
+    const detectResult = await fallbackInstance.detect();
+    if (!detectResult.available) {
+      this.rateLimitedAgents.add(agentPlugin);
+      throw new Error(`Fallback agent '${agentPlugin}' not available: ${detectResult.error}`);
+    }
+    this.agent = fallbackInstance;
+    this.state.activeAgent = agentPlugin;
+    this.state.rateLimitState.currentAgent = agentPlugin;
+    this.state.rateLimitState.isRateLimited = true;
+    this.state.rateLimitState.limitedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.emit({
+      type: "agent:switched",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      previousAgent,
+      newAgent: agentPlugin,
+      reason: "fallback"
+    });
+  }
+  shouldRecoverPrimaryAgent() {
+    if (this.state.activeAgent === this.config.agentName) return false;
+    return this.config.rateLimit.recoverPrimaryBetweenIterations;
+  }
+  async attemptPrimaryAgentRecovery() {
+    if (!this.primaryAgentInstance) return false;
+    const primaryAgent = this.config.agentName;
+    const fallbackAgent = this.state.activeAgent;
+    const startTime = Date.now();
+    try {
+      const handle = this.primaryAgentInstance.execute(
+        PRIMARY_RECOVERY_TEST_PROMPT,
+        { cwd: this.config.workingDir, timeout: PRIMARY_RECOVERY_TEST_TIMEOUT_MS }
+      );
+      const result = await handle.promise;
+      const testDurationMs = Date.now() - startTime;
+      const rateLimitResult = detectRateLimit({
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+        agentId: primaryAgent
+      });
+      const success = !rateLimitResult.isRateLimit && result.status === "completed";
+      this.emit({
+        type: "agent:recovery-attempted",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        primaryAgent,
+        fallbackAgent,
+        success,
+        testDurationMs,
+        rateLimitMessage: rateLimitResult.message
+      });
+      if (success) {
+        this.agent = this.primaryAgentInstance;
+        this.state.activeAgent = primaryAgent;
+        this.state.rateLimitState.currentAgent = primaryAgent;
+        this.state.rateLimitState.isRateLimited = false;
+        this.state.rateLimitState.limitedAt = void 0;
+        this.rateLimitedAgents.clear();
+        this.emit({
+          type: "agent:switched",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          previousAgent: fallbackAgent,
+          newAgent: primaryAgent,
+          reason: "primary"
+        });
+        return true;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+  // ─── Auto-Commit ───
+  async handleAutoCommit(task, iteration) {
+    try {
+      const result = await autoCommitChanges({
+        workingDir: this.config.workingDir,
+        taskId: task.id,
+        taskTitle: task.title
+      });
+      if (result.committed) {
+        this.emit({
+          type: "task:auto-committed",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          task,
+          iteration,
+          commitMessage: result.commitMessage,
+          commitSha: result.commitSha
+        });
+        return result.commitSha;
+      } else if (result.error) {
+        this.emit({
+          type: "task:auto-commit-failed",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          task,
+          iteration,
+          error: result.error
+        });
+      } else if (result.skipReason) {
+        this.emit({
+          type: "task:auto-commit-skipped",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          task,
+          iteration,
+          reason: result.skipReason
+        });
+      }
+    } catch (err) {
+      this.emit({
+        type: "task:auto-commit-failed",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        task,
+        iteration,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+    return void 0;
+  }
+  // ─── Helpers ───
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  emitSkipEvent(task, reason) {
+    this.emit({
+      type: "iteration:skipped",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      iteration: this.state.currentIteration,
+      task,
+      reason
+    });
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  createInitialState() {
+    return {
+      status: "idle",
+      currentTaskId: null,
+      currentIteration: 0,
+      completedTasks: [],
+      failedTasks: [],
+      skippedTasks: [],
+      totalTasks: 0,
+      startedAt: null,
+      elapsedMs: 0,
+      activeAgent: this.config.agentName,
+      rateLimitState: {
+        isRateLimited: false,
+        currentAgent: this.config.agentName,
+        limitedAgents: /* @__PURE__ */ new Set(),
+        backoffMs: 0,
+        attempts: 0
+      },
+      iterations: []
+    };
+  }
+};
+
+export {
+  DEFAULT_ENGINE_CONFIG,
+  detectRateLimit,
+  calculateBackoff,
+  shouldFallback,
+  autoCommitChanges,
+  injectMemories,
+  captureIterationMemory,
+  getSemanticContext,
+  getCodemapAvailability,
+  COMPLETION_SIGNAL,
+  COMPLETION_SIGNAL_PATTERN,
+  buildPrompt,
+  enrichPromptContext,
+  detectCompletionSignal,
+  isTaskComplete,
+  evaluateBeforeExecution,
+  getGovernanceConfig,
+  ExecutionEngine
+};