@tarcisiopgs/lisa 0.9.2 → 0.9.4

package/dist/index.js

@@ -2,16 +2,21 @@
 
 // src/cli.ts
 import { execSync as execSync4 } from "child_process";
-import { existsSync as existsSync4, readFileSync as readFileSync3, readdirSync } from "fs";
-import { join as join5, resolve as resolvePath } from "path";
-import { defineCommand, runMain } from "citty";
+import { existsSync as existsSync7, readdirSync, readFileSync as readFileSync6 } from "fs";
+import { join as join8, resolve as resolvePath } from "path";
 import * as clack from "@clack/prompts";
+import { defineCommand, runMain } from "citty";
 import pc2 from "picocolors";
 
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { resolve } from "path";
 import { parse, stringify } from "yaml";
+var DEFAULT_OVERSEER_CONFIG = {
+  enabled: false,
+  check_interval: 30,
+  stuck_threshold: 300
+};
 var CONFIG_DIR = ".lisa";
 var CONFIG_FILE = "config.yaml";
 var DEFAULT_CONFIG = {
@@ -37,7 +42,8 @@ var DEFAULT_CONFIG = {
   logs: {
     dir: "",
     format: ""
-  }
+  },
+  overseer: { ...DEFAULT_OVERSEER_CONFIG }
 };
 function getConfigPath(cwd = process.cwd()) {
   return resolve(cwd, CONFIG_DIR, CONFIG_FILE);
@@ -69,12 +75,19 @@ function loadConfig(cwd = process.cwd()) {
     ...parsed,
     source_config: sourceConfig,
     loop: { ...DEFAULT_CONFIG.loop, ...parsed.loop ?? {} },
-    logs: { ...DEFAULT_CONFIG.logs, ...parsed.logs ?? {} }
+    logs: { ...DEFAULT_CONFIG.logs, ...parsed.logs ?? {} },
+    overseer: {
+      ...DEFAULT_OVERSEER_CONFIG,
+      ...parsed.overseer ?? {}
+    }
   };
   if (!config2.base_branch) config2.base_branch = "main";
   for (const repo of config2.repos) {
     if (!repo.base_branch) repo.base_branch = config2.base_branch;
   }
+  if (!config2.models && config2.provider) {
+    config2.models = [config2.provider];
+  }
   return config2;
 }
 function saveConfig(config2, cwd = process.cwd()) {
@@ -84,7 +97,20 @@ function saveConfig(config2, cwd = process.cwd()) {
     mkdirSync(dir, { recursive: true });
   }
   const sc = config2.source_config;
-  const sourceYaml = config2.source === "trello" ? { board: sc.team, pick_from: sc.pick_from || sc.project, label: sc.label, in_progress: sc.in_progress, done: sc.done } : { team: sc.team, project: sc.project, label: sc.label, pick_from: sc.pick_from, in_progress: sc.in_progress, done: sc.done };
+  const sourceYaml = config2.source === "trello" ? {
+    board: sc.team,
+    pick_from: sc.pick_from || sc.project,
+    label: sc.label,
+    in_progress: sc.in_progress,
+    done: sc.done
+  } : {
+    team: sc.team,
+    project: sc.project,
+    label: sc.label,
+    pick_from: sc.pick_from,
+    in_progress: sc.in_progress,
+    done: sc.done
+  };
   const output = { ...config2, source_config: sourceYaml };
   writeFileSync(configPath, stringify(output), "utf-8");
 }
@@ -97,6 +123,101 @@ function mergeWithFlags(config2, flags) {
   return merged;
 }
 
+// src/github.ts
+import { execa } from "execa";
+var API_URL = "https://api.github.com";
+var REQUEST_TIMEOUT_MS = 3e4;
+async function isGhCliAvailable() {
+  try {
+    await execa("gh", ["auth", "status"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getToken() {
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) throw new Error("GITHUB_TOKEN is not set");
+  return token;
+}
+async function createPullRequest(opts, method = "cli") {
+  if (method === "cli" && await isGhCliAvailable()) {
+    return createPullRequestWithGhCli(opts);
+  }
+  const res = await fetch(`${API_URL}/repos/${opts.owner}/${opts.repo}/pulls`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${getToken()}`,
+      Accept: "application/vnd.github+json",
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      title: opts.title,
+      body: opts.body,
+      head: opts.head,
+      base: opts.base
+    }),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!res.ok) {
+    const text2 = await res.text();
+    throw new Error(`GitHub API error (${res.status}): ${text2}`);
+  }
+  const data = await res.json();
+  return { number: data.number, html_url: data.html_url };
+}
+async function createPullRequestWithGhCli(opts) {
+  const result = await execa("gh", [
+    "pr",
+    "create",
+    "--repo",
+    `${opts.owner}/${opts.repo}`,
+    "--head",
+    opts.head,
+    "--base",
+    opts.base,
+    "--title",
+    opts.title,
+    "--body",
+    opts.body
+  ]);
+  const url = result.stdout.trim();
+  const prNumberMatch = url.match(/\/pull\/(\d+)/);
+  const number = prNumberMatch ? Number.parseInt(prNumberMatch[1] ?? "0", 10) : 0;
+  return { number, html_url: url };
+}
+async function getRepoInfo(cwd) {
+  const { stdout: remoteUrl } = await execa("git", ["remote", "get-url", "origin"], { cwd });
+  let owner;
+  let repo;
+  const sshMatch = remoteUrl.match(/git@github\.com:(.+?)\/(.+?)(?:\.git)?$/);
+  const httpsMatch = remoteUrl.match(/github\.com\/(.+?)\/(.+?)(?:\.git)?$/);
+  if (sshMatch) {
+    owner = sshMatch[1] ?? "";
+    repo = sshMatch[2] ?? "";
+  } else if (httpsMatch) {
+    owner = httpsMatch[1] ?? "";
+    repo = httpsMatch[2] ?? "";
+  } else {
+    throw new Error(`Cannot parse GitHub owner/repo from remote URL: ${remoteUrl}`);
+  }
+  const { stdout: branch } = await execa("git", ["branch", "--show-current"], { cwd });
+  const { stdout: defaultBranch } = await execa(
+    "git",
+    ["symbolic-ref", "refs/remotes/origin/HEAD", "--short"],
+    { cwd, reject: false }
+  ).then(
+    (r) => r,
+    () => ({ stdout: "origin/main" })
+  );
+  return {
+    owner,
+    repo,
+    branch: branch.trim(),
+    defaultBranch: defaultBranch.replace("origin/", "").trim()
+  };
+}
+
 // src/logger.ts
 import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
 import { dirname } from "path";
@@ -131,26 +252,38 @@ function emitJson(level, message) {
   console.log(JSON.stringify(event));
 }
 function log(message) {
-  if (outputMode === "json") return emitJson("info", message);
+  if (outputMode === "json") {
+    emitJson("info", message);
+    return;
+  }
   if (outputMode !== "quiet") {
     console.log(`${pc.cyan("[lisa]")} ${pc.dim(timestamp())} ${message}`);
   }
   writeToFile("info", message);
 }
 function warn(message) {
-  if (outputMode === "json") return emitJson("warn", message);
+  if (outputMode === "json") {
+    emitJson("warn", message);
+    return;
+  }
   if (outputMode !== "quiet") {
     console.error(`${pc.yellow("[lisa]")} ${pc.dim(timestamp())} ${message}`);
   }
   writeToFile("warn", message);
 }
 function error(message) {
-  if (outputMode === "json") return emitJson("error", message);
+  if (outputMode === "json") {
+    emitJson("error", message);
+    return;
+  }
   console.error(`${pc.red("[lisa]")} ${pc.dim(timestamp())} ${message}`);
   writeToFile("error", message);
 }
 function ok(message) {
-  if (outputMode === "json") return emitJson("ok", message);
+  if (outputMode === "json") {
+    emitJson("ok", message);
+    return;
+  }
   if (outputMode !== "quiet") {
     console.log(`${pc.green("[lisa]")} ${pc.dim(timestamp())} ${message}`);
   }
@@ -188,7 +321,7 @@ function banner() {
                 @%@+=#@==@#:+@##@
                    @@@@%%@##%
 `;
-  const title = " lisa \u2014 autonomous issue resolver ";
+  const title = " Lisa \u2014 deterministic autonomous issue resolver ";
   const border = "\u2500".repeat(title.length);
   console.log(pc.yellow(art));
   console.log(pc.cyan(`  \u250C${border}\u2510`));
@@ -198,18 +331,322 @@ function banner() {
 }
 
 // src/loop.ts
-import { resolve as resolve4 } from "path";
-import { appendFileSync as appendFileSync6 } from "fs";
+import { appendFileSync as appendFileSync6, existsSync as existsSync6, readFileSync as readFileSync5, unlinkSync as unlinkSync4 } from "fs";
+import { join as join7, resolve as resolve5 } from "path";
+import { execa as execa3 } from "execa";
 
-// src/prompt.ts
+// src/lifecycle.ts
+import { spawn } from "child_process";
+import { createConnection } from "net";
 import { resolve as resolve2 } from "path";
-function buildImplementPrompt(issue, config2) {
+var managedResources = [];
+var cleanupRegistered = false;
+function isPortInUse(port) {
+  return new Promise((resolve6) => {
+    const socket = createConnection({ port }, () => {
+      socket.destroy();
+      resolve6(true);
+    });
+    socket.on("error", () => {
+      socket.destroy();
+      resolve6(false);
+    });
+  });
+}
+function waitForPort(port, timeoutMs) {
+  return new Promise((resolve6) => {
+    const deadline = Date.now() + timeoutMs;
+    const check = () => {
+      if (Date.now() > deadline) {
+        resolve6(false);
+        return;
+      }
+      isPortInUse(port).then((inUse) => {
+        if (inUse) {
+          resolve6(true);
+        } else {
+          setTimeout(check, 500);
+        }
+      });
+    };
+    check();
+  });
+}
+function spawnResource(config2, baseCwd) {
+  const cwd = config2.cwd ? resolve2(baseCwd, config2.cwd) : baseCwd;
+  const child = spawn("sh", ["-c", config2.up], {
+    cwd,
+    stdio: "ignore",
+    detached: true
+  });
+  child.unref();
+  return child;
+}
+function runSetupCommand(command, cwd) {
+  return new Promise((resolve6, reject) => {
+    const child = spawn("sh", ["-c", command], {
+      cwd,
+      stdio: "inherit"
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve6();
+      } else {
+        reject(new Error(`Setup command failed with exit code ${code}: ${command}`));
+      }
+    });
+    child.on("error", (err) => {
+      reject(new Error(`Setup command error: ${err.message}`));
+    });
+  });
+}
+async function startResources(repo, baseCwd) {
+  const lifecycle = repo.lifecycle;
+  if (!lifecycle) return true;
+  registerCleanup();
+  for (const resource of lifecycle.resources) {
+    const alreadyRunning = await isPortInUse(resource.check_port);
+    if (alreadyRunning) {
+      ok(`Resource "${resource.name}" already running on port ${resource.check_port}`);
+      continue;
+    }
+    log(`Starting resource "${resource.name}" on port ${resource.check_port}...`);
+    const child = spawnResource(resource, baseCwd);
+    managedResources.push({
+      name: resource.name,
+      config: resource,
+      process: child
+    });
+    const timeoutMs = (resource.startup_timeout || 30) * 1e3;
+    const ready = await waitForPort(resource.check_port, timeoutMs);
+    if (!ready) {
+      error(
+        `Resource "${resource.name}" failed to start within ${resource.startup_timeout}s`
+      );
+      await stopResources();
+      return false;
+    }
+    ok(`Resource "${resource.name}" is ready on port ${resource.check_port}`);
+  }
+  for (const command of lifecycle.setup) {
+    log(`Running setup: ${command}`);
+    try {
+      await runSetupCommand(command, baseCwd);
+      ok(`Setup complete: ${command}`);
+    } catch (err) {
+      error(`Setup failed: ${err instanceof Error ? err.message : String(err)}`);
+      await stopResources();
+      return false;
+    }
+  }
+  return true;
+}
+async function stopResources() {
+  for (const managed of managedResources) {
+    const { name, config: config2, process: child } = managed;
+    log(`Stopping resource "${name}"...`);
+    try {
+      if (config2.down === "auto") {
+        if (child?.pid) {
+          try {
+            process.kill(-child.pid, "SIGTERM");
+          } catch {
+          }
+        }
+      } else {
+        await new Promise((resolve6) => {
+          const down = spawn("sh", ["-c", config2.down], {
+            stdio: "ignore"
+          });
+          down.on("close", () => resolve6());
+          down.on("error", () => resolve6());
+        });
+      }
+      ok(`Resource "${name}" stopped`);
+    } catch (err) {
+      warn(
+        `Failed to stop resource "${name}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  managedResources.length = 0;
+}
+function registerCleanup() {
+  if (cleanupRegistered) return;
+  cleanupRegistered = true;
+  const cleanup = () => {
+    for (const managed of managedResources) {
+      const { config: config2, process: child } = managed;
+      try {
+        if (config2.down === "auto") {
+          if (child?.pid) {
+            process.kill(-child.pid, "SIGTERM");
+          }
+        }
+      } catch {
+      }
+    }
+  };
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(130);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(143);
+  });
+}
+
+// src/prompt.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { join, resolve as resolve3 } from "path";
+function detectTestRunner(cwd) {
+  const packageJsonPath = join(cwd, "package.json");
+  if (!existsSync3(packageJsonPath)) return null;
+  try {
+    const content = JSON.parse(readFileSync2(packageJsonPath, "utf-8"));
+    const deps = { ...content.dependencies, ...content.devDependencies };
+    if ("vitest" in deps) return "vitest";
+    if ("jest" in deps) return "jest";
+    return null;
+  } catch {
+    return null;
+  }
+}
+function buildImplementPrompt(issue, config2, testRunner) {
   if (config2.workflow === "worktree") {
-    return buildWorktreePrompt(issue);
+    return buildWorktreePrompt(issue, testRunner);
   }
-  return buildBranchPrompt(issue, config2);
+  return buildBranchPrompt(issue, config2, testRunner);
 }
-function buildWorktreePrompt(issue) {
+function buildTestInstructions(testRunner) {
+  if (!testRunner) return "";
+  return `
+**MANDATORY \u2014 Unit Tests:**
+This project uses **${testRunner}** as its test runner.
+- You MUST write unit tests (\`*.test.ts\`) for every new file or module you create.
+- Tests should cover the main functionality, edge cases, and error scenarios.
+- Run \`npm run test\` and ensure ALL tests pass before committing.
+- Do NOT skip writing tests \u2014 the PR will be blocked if tests are missing or failing.
+`;
+}
+function buildReadmeInstructions() {
+  return `
+**README.md Evaluation:**
+After implementing, review the diff of all changed files and check if README.md needs updating.
+
+Update README.md if the changes include:
+- New or removed CLI commands or flags
+- New or removed providers or sources
+- Configuration schema changes (new fields, renamed fields, removed fields)
+- Pipeline or workflow stage changes
+- New or removed environment variables
+- Architectural changes
+
+Do NOT update README.md for:
+- Internal refactors that don't change documented behavior
+- Bug fixes that don't change documented behavior
+- Test-only changes
+- Logging or formatting changes
+- Dependency updates
+
+If an update is needed, keep the existing README style and structure. Include the README change in the same commit as the implementation.
+`;
+}
+function buildWorktreeMultiRepoPrompt(issue, config2) {
+  const workspace = resolve3(config2.workspace);
+  const repoBlock = config2.repos.map((r) => {
+    const absPath = resolve3(workspace, r.path);
+    return [
+      `- **${r.name}**: \`${absPath}\``,
+      `  - Base branch: \`${r.base_branch}\``,
+      `  - Worktrees dir: \`${join(absPath, ".worktrees")}\``
+    ].join("\n");
+  }).join("\n\n");
+  const readmeBlock = buildReadmeInstructions();
+  const manifestPath = join(workspace, ".lisa-manifest.json");
+  return `You are an autonomous implementation agent working in a multi-repository workspace.
+Your job is to determine the correct repository, create an English-named branch, implement the issue, commit, and write a manifest file.
+
+You are in the workspace: \`${workspace}\`
+
+## Issue
+
+- **ID:** ${issue.id}
+- **Title:** ${issue.title}
+- **URL:** ${issue.url}
+
+### Description
+
+${issue.description}
+
+## Available Repositories
+
+${repoBlock}
+
+## Instructions
+
+1. **Identify the correct repository**: Read the issue title and description carefully.
+   Determine which single repository above is the right target. Consider:
+   - File paths or module names mentioned in the description
+   - Technologies and frameworks referenced
+   - The nature of the change (e.g., API endpoint \u2192 api repo, UI component \u2192 frontend repo)
+
+2. **Choose an English branch name**: Create a slug in English following:
+   \`feat/${issue.id.toLowerCase()}-short-english-description\`
+   The description part MUST be in English regardless of the issue title language.
+   Example: for "${issue.id} Implementar rate limiting na API" \u2192 \`feat/${issue.id.toLowerCase()}-add-rate-limiting-to-api\`
+
+3. **Set up the worktree**: In the chosen repo, run:
+   \`\`\`
+   git fetch origin <base_branch>
+   git worktree add -b <your-english-branch> <repoPath>/.worktrees/<your-english-branch> origin/<base_branch>
+   cd <repoPath>/.worktrees/<your-english-branch>
+   \`\`\`
+
+4. **Implement**: Work inside the worktree. Follow the issue description exactly:
+   - Read all relevant files listed in the description first (if present)
+   - Follow the implementation instructions exactly
+   - Verify each acceptance criteria (if present)
+   - Respect any stack or technical constraints (if present)
+${readmeBlock}
+5. **Validate**: Run the project's linter/typecheck/tests if available:
+   - Check \`package.json\` for lint, typecheck, check, or test scripts.
+   - Run whichever validation scripts exist (e.g., \`npm run lint\`, \`npm run typecheck\`, \`npm run test\`).
+   - Fix any errors before proceeding.
+
+6. **Commit (do NOT push)**: Make atomic commits with conventional commit messages.
+   Do NOT run \`git push\` \u2014 the caller handles pushing.
+   **IMPORTANT \u2014 Language rules:**
+   - All commit messages MUST be in English.
+   - Use conventional commits format: \`feat: ...\`, \`fix: ...\`, \`refactor: ...\`, \`chore: ...\`
+
+7. **Write the manifest**: After committing, create \`${manifestPath}\` with JSON:
+   \`\`\`json
+   {
+     "repoPath": "<absolute path to the chosen repo>",
+     "branch": "<your English branch name>",
+     "prTitle": "<PR title in English, conventional commit format>"
+   }
+   \`\`\`
+   Do NOT commit this file.
+
+## Rules
+
+- **ALL git commits, branch names, PR titles, and PR descriptions MUST be in English.**
+- The issue description may be in any language \u2014 read it for context but write all code artifacts in English.
+- Do NOT push \u2014 the caller handles that.
+- Do NOT create pull requests \u2014 the caller handles that.
+- Do NOT update the issue tracker \u2014 the caller handles that.
+- Do NOT install new dependencies unless the issue explicitly requires it.
+- If you get stuck or the issue is unclear, STOP and explain why.
+- One issue only. Do not pick up additional issues.
+- If the repo has a CLAUDE.md, read it first and follow its conventions.`;
+}
+function buildWorktreePrompt(issue, testRunner) {
+  const testBlock = buildTestInstructions(testRunner ?? null);
+  const readmeBlock = buildReadmeInstructions();
   return `You are an autonomous implementation agent. Your job is to implement a single
 issue, validate it, commit, and push the branch.
 
@@ -233,22 +670,32 @@ ${issue.description}
    - Follow the implementation instructions exactly
    - Verify each acceptance criteria (if present)
    - Respect any stack or technical constraints (if present)
-
+${testBlock}${readmeBlock}
 2. **Validate**: Run the project's linter/typecheck/tests if available:
    - Check \`package.json\` (or equivalent) for lint, typecheck, check, or test scripts.
    - Run whichever validation scripts exist (e.g., \`npm run lint\`, \`npm run typecheck\`).
    - Fix any errors before proceeding.
 
-3. **Commit & Push**: Make atomic commits with conventional commit messages.
-   Push the branch to origin.
+3. **Commit**: Make atomic commits with conventional commit messages.
+   **Branch name must be in English.** The branch was pre-created with an auto-generated name.
+   If that name contains non-English words, rename it before committing:
+   \`git branch -m <current-name> feat/${issue.id.toLowerCase()}-short-english-slug\`
+   Do NOT push \u2014 the caller handles pushing.
    **IMPORTANT \u2014 Language rules:**
    - All commit messages MUST be in English.
    - Use conventional commits format: \`feat: ...\`, \`fix: ...\`, \`refactor: ...\`, \`chore: ...\`
 
+4. **Write manifest**: Create \`.lisa-manifest.json\` in the **current directory** with JSON:
+   \`\`\`json
+   {"branch": "<final English branch name>", "prTitle": "<English PR title, conventional commit format>"}
+   \`\`\`
+   Do NOT commit this file.
+
 ## Rules
 
-- **ALL git commits MUST be in English.**
+- **ALL git commits, branch names, PR titles, and PR descriptions MUST be in English.**
 - The issue description may be in any language \u2014 read it for context but write all code artifacts in English.
+- Do NOT push \u2014 the caller handles that.
 - Do NOT install new dependencies unless the issue explicitly requires it.
 - If you get stuck or the issue is unclear, STOP and explain why.
 - One issue only. Do not pick up additional issues.
@@ -256,10 +703,15 @@ ${issue.description}
 - Do NOT create pull requests \u2014 the caller handles that.
 - Do NOT update the issue tracker \u2014 the caller handles that.`;
 }
-function buildBranchPrompt(issue, config2) {
-  const workspace = resolve2(config2.workspace);
-  const repoEntries = config2.repos.map((r) => `   - If it says "Repo: ${r.name}" or title starts with "${r.match}" \u2192 \`${resolve2(workspace, r.path)}\` (base branch: \`${r.base_branch}\`)`).join("\n");
+function buildBranchPrompt(issue, config2, testRunner) {
+  const workspace = resolve3(config2.workspace);
+  const repoEntries = config2.repos.map(
+    (r) => `   - If it says "Repo: ${r.name}" or title starts with "${r.match}" \u2192 \`${resolve3(workspace, r.path)}\` (base branch: \`${r.base_branch}\`)`
+  ).join("\n");
   const baseBranchInstruction = config2.repos.length > 0 ? "From the repo's base branch (listed above)" : `From \`${config2.base_branch}\``;
+  const testBlock = buildTestInstructions(testRunner ?? null);
+  const readmeBlock = buildReadmeInstructions();
+  const manifestPath = join(workspace, ".lisa-manifest.json");
   return `You are an autonomous implementation agent. Your job is to implement a single
 issue, validate it, commit, and push the branch.
 
@@ -279,15 +731,17 @@ ${issue.description}
 ${repoEntries}
    - If it references multiple repos, pick the PRIMARY one (the one with the most files listed).
 
-2. **Create a branch**: ${baseBranchInstruction}, create a branch named after the issue
-   (e.g., \`feat/${issue.id.toLowerCase()}-short-description\`).
+2. **Create a branch**: ${baseBranchInstruction}, create a branch with an **English** slug:
+   \`feat/${issue.id.toLowerCase()}-short-english-description\`
+   The description MUST be in English \u2014 translate or summarize the issue title if it's in another language.
+   Example: "Implementar rate limiting na API" \u2192 \`feat/${issue.id.toLowerCase()}-add-rate-limiting-to-api\`
 
 3. **Implement**: Follow the issue description exactly:
    - Read all relevant files listed in the description first (if present)
    - Follow the implementation instructions exactly
    - Verify each acceptance criteria (if present)
    - Respect any stack or technical constraints (if present)
-
+${testBlock}${readmeBlock}
 4. **Validate**: Run the project's linter/typecheck/tests if available:
    - Check \`package.json\` (or equivalent) for lint, typecheck, check, or test scripts.
    - Run whichever validation scripts exist (e.g., \`npm run lint\`, \`npm run typecheck\`).
@@ -299,9 +753,15 @@ ${repoEntries}
    - All commit messages MUST be in English.
    - Use conventional commits format: \`feat: ...\`, \`fix: ...\`, \`refactor: ...\`, \`chore: ...\`
 
+6. **Write manifest**: Before finishing, create \`${manifestPath}\` with JSON:
+   \`\`\`json
+   {"repoPath": "<absolute path to this repo>", "branch": "<branch name>", "prTitle": "<English PR title, conventional commit format>"}
+   \`\`\`
+   Do NOT commit this file.
+
 ## Rules
 
-- **ALL git commits, branch names MUST be in English.**
+- **ALL git commits, branch names, PR titles, and PR descriptions MUST be in English.**
 - The issue description may be in any language \u2014 read it for context but write all code artifacts in English.
 - Do NOT modify files outside the target repo.
 - Do NOT install new dependencies unless the issue explicitly requires it.
@@ -312,11 +772,175 @@ ${repoEntries}
 - Do NOT update the issue tracker \u2014 the caller handles that.`;
 }
 
+// src/guardrails.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+var GUARDRAILS_FILE = ".lisa/guardrails.md";
+var MAX_ENTRIES = 20;
+var CONTEXT_LINES = 20;
+function guardrailsPath(dir) {
+  return join2(dir, GUARDRAILS_FILE);
+}
+function readGuardrails(dir) {
+  const path = guardrailsPath(dir);
+  if (!existsSync4(path)) return "";
+  try {
+    return readFileSync3(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+function buildGuardrailsSection(dir) {
+  const content = readGuardrails(dir);
+  if (!content.trim()) return "";
+  return `
+## Guardrails \u2014 Avoid these known pitfalls
+
+${content}
+`;
+}
+function extractContext(output) {
+  const lines = output.trim().split("\n");
+  return lines.slice(-CONTEXT_LINES).join("\n");
+}
+function extractErrorType(output) {
+  if (/429|rate.?limit|quota/i.test(output)) return "Rate limit / quota exceeded";
+  if (/ETIMEDOUT|ECONNREFUSED|ECONNRESET|ENOTFOUND/.test(output)) return "Network error";
+  if (/timeout|timed?\s*out/i.test(output)) return "Timeout";
+  const exitMatch = output.match(/exit code[:\s]+(\d+)/i);
+  if (exitMatch) return `Exit code ${exitMatch[1]}`;
+  if (/exit(?:ed)? with/i.test(output)) return "Non-zero exit code";
+  return "Unknown error";
+}
+function appendEntry(dir, entry) {
+  const path = guardrailsPath(dir);
+  const guardrailsDir = dirname2(path);
+  if (!existsSync4(guardrailsDir)) {
+    mkdirSync3(guardrailsDir, { recursive: true });
+  }
+  const existing = existsSync4(path) ? readFileSync3(path, "utf-8") : "";
+  const newEntryText = formatEntry(entry);
+  let content;
+  if (!existing.trim()) {
+    content = `# Guardrails \u2014 Li\xE7\xF5es aprendidas
+
+${newEntryText}`;
+  } else {
+    const header = extractHeader(existing);
+    const entries = splitEntries(existing);
+    entries.push(newEntryText);
+    const rotated = entries.length > MAX_ENTRIES ? entries.slice(-MAX_ENTRIES) : entries;
+    content = `${header}
+
+${rotated.join("\n\n")}`;
+  }
+  writeFileSync3(path, content, "utf-8");
+}
+function formatEntry(entry) {
+  return [
+    `## Issue ${entry.issueId} (${entry.date})`,
+    `- Provider: ${entry.provider}`,
+    `- Erro: ${entry.errorType}`,
+    `- Contexto:`,
+    "```",
+    entry.context,
+    "```"
+  ].join("\n");
+}
+function extractHeader(content) {
+  const firstEntry = content.search(/^## /m);
+  if (firstEntry === -1) return content.trim();
+  return content.slice(0, firstEntry).trim();
+}
+function splitEntries(content) {
+  const positions = [];
+  const regex = /^## /gm;
+  for (const match of content.matchAll(regex)) {
+    positions.push(match.index);
+  }
+  return positions.map((start, i) => {
+    const end = positions[i + 1] ?? content.length;
+    return content.slice(start, end).trim();
+  });
+}
+
 // src/providers/claude.ts
-import { spawn, execSync } from "child_process";
-import { appendFileSync as appendFileSync2, writeFileSync as writeFileSync3, unlinkSync, mkdtempSync } from "fs";
-import { join } from "path";
+import { execSync, spawn as spawn2 } from "child_process";
+import { appendFileSync as appendFileSync2, mkdtempSync, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
 import { tmpdir } from "os";
+import { join as join3 } from "path";
+
+// src/overseer.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var STUCK_MESSAGE = "\n[lisa-overseer] Provider killed: no git changes detected within the stuck threshold. Eligible for fallback.\n";
+async function getGitSnapshot(cwd) {
+  try {
+    const { stdout } = await execFileAsync("git", ["status", "--porcelain"], {
+      cwd,
+      timeout: 1e4
+    });
+    return stdout;
+  } catch {
+    return "";
+  }
+}
+function startOverseer(proc, cwd, config2, getSnapshot = getGitSnapshot) {
+  if (!config2.enabled) {
+    return {
+      stop() {
+      },
+      wasKilled() {
+        return false;
+      }
+    };
+  }
+  let killed = false;
+  let lastSnapshot;
+  let lastChangeTime = Date.now();
+  let timer = null;
+  const check = async () => {
+    if (killed) return;
+    try {
+      const snapshot = await getSnapshot(cwd);
+      if (lastSnapshot === void 0) {
+        lastSnapshot = snapshot;
+        lastChangeTime = Date.now();
+        return;
+      }
+      if (snapshot !== lastSnapshot) {
+        lastSnapshot = snapshot;
+        lastChangeTime = Date.now();
+        return;
+      }
+      const idleMs = Date.now() - lastChangeTime;
+      if (idleMs >= config2.stuck_threshold * 1e3) {
+        killed = true;
+        if (timer) {
+          clearInterval(timer);
+          timer = null;
+        }
+        proc.kill("SIGTERM");
+      }
+    } catch {
+    }
+  };
+  timer = setInterval(check, config2.check_interval * 1e3);
+  return {
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+    wasKilled() {
+      return killed;
+    }
+  };
+}
+
+// src/providers/claude.ts
 var ClaudeProvider = class {
   name = "claude";
   async isAvailable() {
@@ -329,11 +953,11 @@ var ClaudeProvider = class {
   }
   async run(prompt, opts) {
     const start = Date.now();
-    const tmpDir = mkdtempSync(join(tmpdir(), "lisa-"));
-    const promptFile = join(tmpDir, "prompt.md");
-    writeFileSync3(promptFile, prompt, "utf-8");
+    const tmpDir = mkdtempSync(join3(tmpdir(), "lisa-"));
+    const promptFile = join3(tmpDir, "prompt.md");
+    writeFileSync4(promptFile, prompt, "utf-8");
     try {
-      const proc = spawn(
+      const proc = spawn2(
         "sh",
         ["-c", `claude -p --dangerously-skip-permissions "$(cat '${promptFile}')"`],
         {
@@ -342,6 +966,7 @@ var ClaudeProvider = class {
           env: { ...process.env, CLAUDECODE: void 0 }
         }
       );
+      const overseer = opts.overseer?.enabled ? startOverseer(proc, opts.cwd, opts.overseer) : null;
       const chunks = [];
       proc.stdout.on("data", (chunk) => {
         const text2 = chunk.toString();
@@ -360,11 +985,17 @@ var ClaudeProvider = class {
         } catch {
         }
       });
-      const exitCode = await new Promise((resolve5) => {
-        proc.on("close", (code) => resolve5(code ?? 1));
+      const exitCode = await new Promise((resolve6) => {
+        proc.on("close", (code) => {
+          overseer?.stop();
+          resolve6(code ?? 1);
+        });
       });
+      if (overseer?.wasKilled()) {
+        chunks.push(STUCK_MESSAGE);
+      }
       return {
-        success: exitCode === 0,
+        success: exitCode === 0 && !overseer?.wasKilled(),
         output: chunks.join(""),
         duration: Date.now() - start
       };
@@ -384,10 +1015,10 @@ var ClaudeProvider = class {
 };
 
 // src/providers/gemini.ts
-import { spawn as spawn2, execSync as execSync2 } from "child_process";
-import { appendFileSync as appendFileSync3, writeFileSync as writeFileSync4, unlinkSync as unlinkSync2, mkdtempSync as mkdtempSync2 } from "fs";
-import { join as join2 } from "path";
+import { execSync as execSync2, spawn as spawn3 } from "child_process";
+import { appendFileSync as appendFileSync3, mkdtempSync as mkdtempSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync5 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
+import { join as join4 } from "path";
 var GeminiProvider = class {
   name = "gemini";
   async isAvailable() {
@@ -400,18 +1031,15 @@ var GeminiProvider = class {
   }
   async run(prompt, opts) {
     const start = Date.now();
-    const tmpDir = mkdtempSync2(join2(tmpdir2(), "lisa-"));
-    const promptFile = join2(tmpDir, "prompt.md");
-    writeFileSync4(promptFile, prompt, "utf-8");
+    const tmpDir = mkdtempSync2(join4(tmpdir2(), "lisa-"));
+    const promptFile = join4(tmpDir, "prompt.md");
+    writeFileSync5(promptFile, prompt, "utf-8");
     try {
-      const proc = spawn2(
-        "sh",
-        ["-c", `gemini --yolo -p "$(cat '${promptFile}')"`],
-        {
-          cwd: opts.cwd,
-          stdio: ["ignore", "pipe", "pipe"]
-        }
-      );
+      const proc = spawn3("sh", ["-c", `gemini --yolo -p "$(cat '${promptFile}')"`], {
+        cwd: opts.cwd,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      const overseer = opts.overseer?.enabled ? startOverseer(proc, opts.cwd, opts.overseer) : null;
       const chunks = [];
       proc.stdout.on("data", (chunk) => {
         const text2 = chunk.toString();
@@ -430,11 +1058,17 @@ var GeminiProvider = class {
         } catch {
         }
       });
-      const exitCode = await new Promise((resolve5) => {
-        proc.on("close", (code) => resolve5(code ?? 1));
+      const exitCode = await new Promise((resolve6) => {
+        proc.on("close", (code) => {
+          overseer?.stop();
+          resolve6(code ?? 1);
+        });
       });
+      if (overseer?.wasKilled()) {
+        chunks.push(STUCK_MESSAGE);
+      }
       return {
-        success: exitCode === 0,
+        success: exitCode === 0 && !overseer?.wasKilled(),
         output: chunks.join(""),
         duration: Date.now() - start
       };
@@ -454,10 +1088,10 @@ var GeminiProvider = class {
 };
 
 // src/providers/opencode.ts
-import { spawn as spawn3, execSync as execSync3 } from "child_process";
-import { appendFileSync as appendFileSync4, writeFileSync as writeFileSync5, unlinkSync as unlinkSync3, mkdtempSync as mkdtempSync3 } from "fs";
-import { join as join3 } from "path";
+import { execSync as execSync3, spawn as spawn4 } from "child_process";
+import { appendFileSync as appendFileSync4, mkdtempSync as mkdtempSync3, unlinkSync as unlinkSync3, writeFileSync as writeFileSync6 } from "fs";
 import { tmpdir as tmpdir3 } from "os";
+import { join as join5 } from "path";
 var OpenCodeProvider = class {
   name = "opencode";
   async isAvailable() {
@@ -470,18 +1104,15 @@ var OpenCodeProvider = class {
   }
   async run(prompt, opts) {
     const start = Date.now();
-    const tmpDir = mkdtempSync3(join3(tmpdir3(), "lisa-"));
-    const promptFile = join3(tmpDir, "prompt.md");
-    writeFileSync5(promptFile, prompt, "utf-8");
+    const tmpDir = mkdtempSync3(join5(tmpdir3(), "lisa-"));
+    const promptFile = join5(tmpDir, "prompt.md");
+    writeFileSync6(promptFile, prompt, "utf-8");
     try {
-      const proc = spawn3(
-        "sh",
-        ["-c", `opencode run "$(cat '${promptFile}')"`],
-        {
-          cwd: opts.cwd,
-          stdio: ["ignore", "pipe", "pipe"]
-        }
-      );
+      const proc = spawn4("sh", ["-c", `opencode run "$(cat '${promptFile}')"`], {
+        cwd: opts.cwd,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      const overseer = opts.overseer?.enabled ? startOverseer(proc, opts.cwd, opts.overseer) : null;
       const chunks = [];
       proc.stdout.on("data", (chunk) => {
         const text2 = chunk.toString();
@@ -500,11 +1131,17 @@ var OpenCodeProvider = class {
         } catch {
         }
       });
-      const exitCode = await new Promise((resolve5) => {
-        proc.on("close", (code) => resolve5(code ?? 1));
+      const exitCode = await new Promise((resolve6) => {
+        proc.on("close", (code) => {
+          overseer?.stop();
+          resolve6(code ?? 1);
+        });
       });
+      if (overseer?.wasKilled()) {
+        chunks.push(STUCK_MESSAGE);
+      }
       return {
-        success: exitCode === 0,
+        success: exitCode === 0 && !overseer?.wasKilled(),
         output: chunks.join(""),
         duration: Date.now() - start
       };
@@ -543,24 +1180,126 @@ function createProvider(name) {
   }
   return factory();
 }
+var ELIGIBLE_ERROR_PATTERNS = [
+  /429/i,
+  /quota/i,
+  /rate.?limit/i,
+  /too many requests/i,
+  /resource.?exhausted/i,
+  /overloaded/i,
+  /unavailable/i,
+  /not.?found.*model/i,
+  /model.*not.?found/i,
+  /does not exist/i,
+  /ETIMEDOUT/,
+  /ECONNREFUSED/,
+  /ECONNRESET/,
+  /ENOTFOUND/,
+  /timeout/i,
+  /timed?\s*out/i,
+  /network.?error/i,
+  /not installed/i,
+  /not in PATH/i,
+  /command not found/i,
+  /lisa-overseer/i
+];
+function isEligibleForFallback(output) {
+  return ELIGIBLE_ERROR_PATTERNS.some((pattern) => pattern.test(output));
+}
+async function runWithFallback(models, prompt, opts) {
+  const attempts = [];
+  for (const model of models) {
+    const provider = createProvider(model);
+    const available = await provider.isAvailable();
+    if (!available) {
+      attempts.push({
+        provider: model,
+        success: false,
+        error: `Provider "${model}" is not installed or not in PATH`,
+        duration: 0
+      });
+      continue;
+    }
+    const guardrailsSection = opts.guardrailsDir ? buildGuardrailsSection(opts.guardrailsDir) : "";
+    const fullPrompt = guardrailsSection ? `${prompt}${guardrailsSection}` : prompt;
+    const result = await provider.run(fullPrompt, opts);
+    if (result.success) {
+      attempts.push({
+        provider: model,
+        success: true,
+        duration: result.duration
+      });
+      return {
+        success: true,
+        output: result.output,
+        duration: result.duration,
+        providerUsed: model,
+        attempts
+      };
+    }
+    if (opts.guardrailsDir && opts.issueId) {
+      appendEntry(opts.guardrailsDir, {
+        issueId: opts.issueId,
+        date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+        provider: model,
+        errorType: extractErrorType(result.output),
+        context: extractContext(result.output)
+      });
+    }
+    const eligible = isEligibleForFallback(result.output);
+    attempts.push({
+      provider: model,
+      success: false,
+      error: eligible ? "Eligible error (quota/unavailable/timeout)" : "Non-eligible error",
+      duration: result.duration
+    });
+    if (!eligible) {
+      return {
+        success: false,
+        output: result.output,
+        duration: result.duration,
+        providerUsed: model,
+        attempts
+      };
+    }
+  }
+  const totalDuration = attempts.reduce((sum, a) => sum + a.duration, 0);
+  return {
+    success: false,
+    output: formatAttemptsReport(attempts),
+    duration: totalDuration,
+    providerUsed: attempts[attempts.length - 1]?.provider ?? models[0] ?? "claude",
+    attempts
+  };
+}
+function formatAttemptsReport(attempts) {
+  const lines = ["All models exhausted. Attempt history:"];
+  for (const [i, a] of attempts.entries()) {
+    const status2 = a.success ? "OK" : "FAILED";
+    const error2 = a.error ? ` \u2014 ${a.error}` : "";
+    const duration = a.duration > 0 ? ` (${Math.round(a.duration / 1e3)}s)` : "";
+    lines.push(`  ${i + 1}. ${a.provider}: ${status2}${error2}${duration}`);
+  }
+  return lines.join("\n");
+}
 
 // src/sources/linear.ts
-var API_URL = "https://api.linear.app/graphql";
-var REQUEST_TIMEOUT_MS = 3e4;
+var API_URL2 = "https://api.linear.app/graphql";
+var REQUEST_TIMEOUT_MS2 = 3e4;
 function getApiKey() {
   const key = process.env.LINEAR_API_KEY;
   if (!key) throw new Error("LINEAR_API_KEY is not set");
   return key;
 }
 async function gql(query, variables) {
-  const res = await fetch(API_URL, {
+  const res = await fetch(API_URL2, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: getApiKey()
     },
     body: JSON.stringify({ query, variables }),
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS2)
   });
   if (!res.ok) {
     const text2 = await res.text();
@@ -584,7 +1323,7 @@ var LinearSource = class {
 						labels: { name: { eq: $labelName } }
 						state: { name: { eq: $statusName } }
 					}
-					first: 20
+					first: 50
 				) {
 					nodes {
 						id
@@ -593,6 +1332,15 @@ var LinearSource = class {
 						description
 						url
 						priority
+						inverseRelations(first: 50) {
+							nodes {
+								type
+								issue {
+									identifier
+									state { type }
+								}
+							}
+						}
 					}
 				}
 			}`,
@@ -605,12 +1353,32 @@ var LinearSource = class {
     );
     const issues = data.issues.nodes;
     if (issues.length === 0) return null;
-    issues.sort((a, b) => {
+    const unblocked = [];
+    const blocked = [];
+    for (const issue2 of issues) {
+      const activeBlockers = issue2.inverseRelations.nodes.filter((r) => r.type === "blocks").filter((r) => r.issue.state.type !== "completed" && r.issue.state.type !== "canceled").map((r) => r.issue.identifier);
+      if (activeBlockers.length === 0) {
+        unblocked.push(issue2);
+      } else {
+        blocked.push({ identifier: issue2.identifier, blockers: activeBlockers });
+      }
+    }
+    if (unblocked.length === 0) {
+      if (blocked.length > 0) {
+        warn("No unblocked issues found. Blocked issues:");
+        for (const entry of blocked) {
+          warn(`  ${entry.identifier} \u2014 blocked by: ${entry.blockers.join(", ")}`);
+        }
+      }
+      return null;
+    }
+    unblocked.sort((a, b) => {
       const pa = a.priority === 0 ? 5 : a.priority;
       const pb = b.priority === 0 ? 5 : b.priority;
       return pa - pb;
     });
-    const issue = issues[0];
+    const issue = unblocked[0];
+    if (!issue) return null;
     return {
       id: issue.identifier,
       title: issue.title,
@@ -618,6 +1386,28 @@ var LinearSource = class {
       url: issue.url
     };
   }
+  async fetchIssueById(id) {
+    const identifier = parseLinearIdentifier(id);
+    const data = await gql(
+      `query($identifier: String!) {
+				issue(id: $identifier) {
+					id
+					identifier
+					title
+					description
+					url
+				}
+			}`,
+      { identifier }
+    );
+    if (!data.issue) return null;
+    return {
+      id: data.issue.identifier,
+      title: data.issue.title,
+      description: data.issue.description || "",
+      url: data.issue.url
+    };
+  }
   async updateStatus(issueId, statusName) {
     const issueData = await gql(
       `query($identifier: String!) {
@@ -643,7 +1433,7 @@ var LinearSource = class {
       const available = statesData.workflowStates.nodes.map((s) => s.name).join(", ");
       throw new Error(`Status "${statusName}" not found. Available: ${available}`);
     }
-    await gql(
+    const mutationResult = await gql(
       `mutation($issueId: String!, $stateId: String!) {
 				issueUpdate(id: $issueId, input: { stateId: $stateId }) {
 					success
@@ -651,6 +1441,11 @@ var LinearSource = class {
 			}`,
       { issueId: issueData.issue.id, stateId: state.id }
     );
+    if (!mutationResult.issueUpdate.success) {
+      throw new Error(
+        `issueUpdate returned success=false for ${issueId} (stateId: ${state.id}, stateName: ${state.name})`
+      );
+    }
   }
   async attachPullRequest(_issueId, _prUrl) {
   }
@@ -665,11 +1460,9 @@ var LinearSource = class {
       { identifier: issueId }
     );
     const currentLabels = issueData.issue.labels.nodes;
-    const filtered = currentLabels.filter(
-      (l) => l.name.toLowerCase() !== labelName.toLowerCase()
-    );
+    const filtered = currentLabels.filter((l) => l.name.toLowerCase() !== labelName.toLowerCase());
     if (filtered.length === currentLabels.length) return;
-    await gql(
+    const mutationResult = await gql(
       `mutation($issueId: String!, $labelIds: [String!]!) {
 				issueUpdate(id: $issueId, input: { labelIds: $labelIds }) {
 					success
@@ -680,12 +1473,22 @@ var LinearSource = class {
         labelIds: filtered.map((l) => l.id)
       }
     );
+    if (!mutationResult.issueUpdate.success) {
+      throw new Error(
+        `issueUpdate returned success=false when removing label "${labelName}" from ${issueId}`
+      );
+    }
   }
 };
+function parseLinearIdentifier(input) {
+  const urlMatch = input.match(/\/issue\/([A-Z]+-\d+)/);
+  if (urlMatch?.[1]) return urlMatch[1];
+  return input;
+}
 
 // src/sources/trello.ts
-var API_URL2 = "https://api.trello.com/1";
-var REQUEST_TIMEOUT_MS2 = 3e4;
+var API_URL3 = "https://api.trello.com/1";
+var REQUEST_TIMEOUT_MS3 = 3e4;
 function getAuthHeaders() {
   const key = process.env.TRELLO_API_KEY;
   const token = process.env.TRELLO_TOKEN;
@@ -696,11 +1499,11 @@ function getAuthHeaders() {
 }
 async function trelloFetch(method, path, params = "") {
   const sep = params ? "?" : "";
-  const url = `${API_URL2}${path}${sep}${params}`;
+  const url = `${API_URL3}${path}${sep}${params}`;
   const res = await fetch(url, {
     method,
     headers: getAuthHeaders(),
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS2)
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS3)
   });
   if (!res.ok) {
     const text2 = await res.text();
@@ -755,6 +1558,7 @@ var TrelloSource = class {
     const matching = cards.filter((c) => c.idLabels.includes(label.id));
     if (matching.length === 0) return null;
     const card = matching[0];
+    if (!card) return null;
     return {
       id: card.id,
       title: card.name,
@@ -762,150 +1566,96 @@ var TrelloSource = class {
       url: card.url
     };
   }
+  async fetchIssueById(id) {
+    const shortLink = parseTrelloIdentifier(id);
+    try {
+      const card = await trelloGet(
+        `/cards/${shortLink}`,
+        "fields=name,desc,url,idLabels,idList"
+      );
+      return {
+        id: card.id,
+        title: card.name,
+        description: card.desc || "",
+        url: card.url
+      };
+    } catch {
+      return null;
+    }
+  }
   async updateStatus(cardId, listName) {
     const card = await trelloGet(`/cards/${cardId}`, "fields=idBoard");
     const list = await findListByName(card.idBoard, listName);
-    await trelloPut(`/cards/${cardId}`, `idList=${list.id}`);
-  }
-  async attachPullRequest(cardId, prUrl) {
-    await trelloPost(`/cards/${cardId}/attachments`, `url=${encodeURIComponent(prUrl)}`);
-  }
-  async removeLabel(cardId, labelName) {
-    const card = await trelloGet(
-      `/cards/${cardId}`,
-      "fields=idBoard,idLabels"
-    );
-    const label = await findLabelByName(card.idBoard, labelName);
-    if (!card.idLabels.includes(label.id)) return;
-    await trelloDelete(`/cards/${cardId}/idLabels/${label.id}`);
-  }
-};
-
-// src/sources/index.ts
-var sources = {
-  linear: () => new LinearSource(),
-  trello: () => new TrelloSource()
-};
-function createSource(name) {
-  const factory = sources[name];
-  if (!factory) {
-    throw new Error(`Unknown source: ${name}. Available: ${Object.keys(sources).join(", ")}`);
-  }
-  return factory();
-}
-
-// src/github.ts
-import { execa } from "execa";
-var API_URL3 = "https://api.github.com";
-var REQUEST_TIMEOUT_MS3 = 3e4;
-async function isGhCliAvailable() {
-  try {
-    await execa("gh", ["auth", "status"]);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function getToken() {
-  const token = process.env.GITHUB_TOKEN;
-  if (!token) throw new Error("GITHUB_TOKEN is not set");
-  return token;
-}
-async function createPullRequest(opts, method = "cli") {
-  if (method === "cli" && await isGhCliAvailable()) {
-    return createPullRequestWithGhCli(opts);
-  }
-  const res = await fetch(`${API_URL3}/repos/${opts.owner}/${opts.repo}/pulls`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${getToken()}`,
-      Accept: "application/vnd.github+json",
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify({
-      title: opts.title,
-      body: opts.body,
-      head: opts.head,
-      base: opts.base
-    }),
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS3)
-  });
-  if (!res.ok) {
-    const text2 = await res.text();
-    throw new Error(`GitHub API error (${res.status}): ${text2}`);
-  }
-  const data = await res.json();
-  return { number: data.number, html_url: data.html_url };
-}
-async function createPullRequestWithGhCli(opts) {
-  const result = await execa("gh", [
-    "pr",
-    "create",
-    "--repo",
-    `${opts.owner}/${opts.repo}`,
-    "--head",
-    opts.head,
-    "--base",
-    opts.base,
-    "--title",
-    opts.title,
-    "--body",
-    opts.body
-  ]);
-  const url = result.stdout.trim();
-  const prNumberMatch = url.match(/\/pull\/(\d+)/);
-  const number = prNumberMatch ? Number.parseInt(prNumberMatch[1], 10) : 0;
-  return { number, html_url: url };
+    await trelloPut(`/cards/${cardId}`, `idList=${list.id}`);
+  }
+  async attachPullRequest(cardId, prUrl) {
+    await trelloPost(`/cards/${cardId}/attachments`, `url=${encodeURIComponent(prUrl)}`);
+  }
+  async removeLabel(cardId, labelName) {
+    const card = await trelloGet(
+      `/cards/${cardId}`,
+      "fields=idBoard,idLabels"
+    );
+    const label = await findLabelByName(card.idBoard, labelName);
+    if (!card.idLabels.includes(label.id)) return;
+    await trelloDelete(`/cards/${cardId}/idLabels/${label.id}`);
+  }
+};
+function parseTrelloIdentifier(input) {
+  const urlMatch = input.match(/\/c\/([a-zA-Z0-9]+)/);
+  if (urlMatch?.[1]) return urlMatch[1];
+  return input;
 }
-async function getRepoInfo(cwd) {
-  const { stdout: remoteUrl } = await execa("git", ["remote", "get-url", "origin"], { cwd });
-  let owner;
-  let repo;
-  const sshMatch = remoteUrl.match(/git@github\.com:(.+?)\/(.+?)(?:\.git)?$/);
-  const httpsMatch = remoteUrl.match(/github\.com\/(.+?)\/(.+?)(?:\.git)?$/);
-  if (sshMatch) {
-    owner = sshMatch[1];
-    repo = sshMatch[2];
-  } else if (httpsMatch) {
-    owner = httpsMatch[1];
-    repo = httpsMatch[2];
-  } else {
-    throw new Error(`Cannot parse GitHub owner/repo from remote URL: ${remoteUrl}`);
+
+// src/sources/index.ts
+var sources = {
+  linear: () => new LinearSource(),
+  trello: () => new TrelloSource()
+};
+function createSource(name) {
+  const factory = sources[name];
+  if (!factory) {
+    throw new Error(`Unknown source: ${name}. Available: ${Object.keys(sources).join(", ")}`);
   }
-  const { stdout: branch } = await execa("git", ["branch", "--show-current"], { cwd });
-  const { stdout: defaultBranch } = await execa(
-    "git",
-    ["symbolic-ref", "refs/remotes/origin/HEAD", "--short"],
-    { cwd, reject: false }
-  ).then(
-    (r) => r,
-    () => ({ stdout: "origin/main" })
-  );
-  return {
-    owner,
-    repo,
-    branch: branch.trim(),
-    defaultBranch: defaultBranch.replace("origin/", "").trim()
-  };
+  return factory();
 }
 
 // src/worktree.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2, appendFileSync as appendFileSync5 } from "fs";
-import { join as join4, resolve as resolve3 } from "path";
+import { appendFileSync as appendFileSync5, existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { join as join6, resolve as resolve4 } from "path";
 import { execa as execa2 } from "execa";
 var WORKTREES_DIR = ".worktrees";
 function generateBranchName(issueId, title) {
   const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").substring(0, 40);
   return `feat/${issueId.toLowerCase()}-${slug}`;
 }
+async function cleanupOrphanedWorktree(repoRoot, branchName) {
+  const { stdout: branchList } = await execa2("git", ["branch", "--list", branchName], {
+    cwd: repoRoot,
+    reject: false
+  });
+  if (!branchList.trim()) {
+    return false;
+  }
+  const worktreePath = join6(repoRoot, WORKTREES_DIR, branchName);
+  const { stdout: worktreeList } = await execa2("git", ["worktree", "list", "--porcelain"], {
+    cwd: repoRoot,
+    reject: false
+  });
+  if (worktreeList.includes(worktreePath)) {
+    await execa2("git", ["worktree", "remove", worktreePath, "--force"], { cwd: repoRoot });
+    await execa2("git", ["worktree", "prune"], { cwd: repoRoot });
+  }
+  await execa2("git", ["branch", "-D", branchName], { cwd: repoRoot });
+  return true;
+}
 async function createWorktree(repoRoot, branchName, baseBranch) {
-  const worktreePath = join4(repoRoot, WORKTREES_DIR, branchName);
+  const worktreePath = join6(repoRoot, WORKTREES_DIR, branchName);
+  await cleanupOrphanedWorktree(repoRoot, branchName);
   await execa2("git", ["fetch", "origin", baseBranch], { cwd: repoRoot });
-  await execa2(
-    "git",
-    ["worktree", "add", "-b", branchName, worktreePath, `origin/${baseBranch}`],
-    { cwd: repoRoot }
-  );
+  await execa2("git", ["worktree", "add", "-b", branchName, worktreePath, `origin/${baseBranch}`], {
+    cwd: repoRoot
+  });
   return worktreePath;
 }
 async function removeWorktree(repoRoot, worktreePath) {
@@ -915,13 +1665,13 @@ async function removeWorktree(repoRoot, worktreePath) {
   await execa2("git", ["worktree", "prune"], { cwd: repoRoot });
 }
 function ensureWorktreeGitignore(repoRoot) {
-  const gitignorePath = join4(repoRoot, ".gitignore");
-  if (!existsSync3(gitignorePath)) {
+  const gitignorePath = join6(repoRoot, ".gitignore");
+  if (!existsSync5(gitignorePath)) {
     appendFileSync5(gitignorePath, `${WORKTREES_DIR}
 `);
     return;
   }
-  const content = readFileSync2(gitignorePath, "utf-8");
+  const content = readFileSync4(gitignorePath, "utf-8");
   if (!content.split("\n").some((line) => line.trim() === WORKTREES_DIR)) {
     const separator = content.endsWith("\n") ? "" : "\n";
     appendFileSync5(gitignorePath, `${separator}${WORKTREES_DIR}
@@ -930,27 +1680,23 @@ function ensureWorktreeGitignore(repoRoot) {
 }
 async function findBranchByIssueId(repoRoot, issueId) {
   const needle = issueId.toLowerCase();
-  const { stdout: local } = await execa2("git", [
-    "for-each-ref",
-    "--sort=-committerdate",
-    "--format=%(refname:short)",
-    "refs/heads/"
-  ], { cwd: repoRoot });
+  const { stdout: local } = await execa2(
+    "git",
+    ["for-each-ref", "--sort=-committerdate", "--format=%(refname:short)", "refs/heads/"],
+    { cwd: repoRoot }
+  );
   const localMatch = local.split("\n").map((b) => b.trim()).filter(Boolean).find((b) => b.toLowerCase().includes(needle));
   if (localMatch) return localMatch;
-  const { stdout: remote } = await execa2("git", [
-    "for-each-ref",
-    "--sort=-committerdate",
-    "--format=%(refname:short)",
-    "refs/remotes/origin/"
-  ], { cwd: repoRoot });
+  const { stdout: remote } = await execa2(
+    "git",
+    ["for-each-ref", "--sort=-committerdate", "--format=%(refname:short)", "refs/remotes/origin/"],
+    { cwd: repoRoot }
+  );
   const remoteMatch = remote.split("\n").map((b) => b.trim()).filter(Boolean).find((b) => b.toLowerCase().includes(needle));
   if (remoteMatch) return remoteMatch.replace("origin/", "");
-  const { stdout: lsRemote } = await execa2("git", [
-    "ls-remote",
-    "--heads",
-    "origin"
-  ], { cwd: repoRoot });
+  const { stdout: lsRemote } = await execa2("git", ["ls-remote", "--heads", "origin"], {
+    cwd: repoRoot
+  });
   const lsMatch = lsRemote.split("\n").map((l) => l.trim()).filter(Boolean).map((l) => l.split("	")[1]?.replace("refs/heads/", "") ?? "").find((b) => b.toLowerCase().includes(needle));
   if (lsMatch) return lsMatch;
   return void 0;
@@ -959,17 +1705,18 @@ function determineRepoPath(repos, issue, workspace) {
   if (repos.length === 0) return void 0;
   if (issue.repo) {
     const match = repos.find((r) => r.name === issue.repo);
-    if (match) return join4(workspace, match.path);
+    if (match) return join6(workspace, match.path);
   }
   for (const r of repos) {
     if (r.match && issue.title.startsWith(r.match)) {
-      return join4(workspace, r.path);
+      return join6(workspace, r.path);
     }
   }
-  return join4(workspace, repos[0].path);
+  const first = repos[0];
+  return first ? join6(workspace, first.path) : void 0;
 }
 async function detectFeatureBranches(repos, issueId, workspace, globalBaseBranch) {
-  const entries = repos.length > 0 ? repos.map((r) => ({ path: resolve3(workspace, r.path), baseBranch: r.base_branch })) : [{ path: workspace, baseBranch: globalBaseBranch }];
+  const entries = repos.length > 0 ? repos.map((r) => ({ path: resolve4(workspace, r.path), baseBranch: r.base_branch })) : [{ path: workspace, baseBranch: globalBaseBranch }];
   const needle = issueId.toLowerCase();
   const results = [];
   const matched = /* @__PURE__ */ new Set();
@@ -979,7 +1726,7 @@ async function detectFeatureBranches(repos, issueId, workspace, globalBaseBranch
       const { stdout } = await execa2("git", ["branch", "--show-current"], { cwd: entry.path });
       const current = stdout.trim();
       currentBranches.push({ ...entry, current });
-      if (current && current.toLowerCase().includes(needle)) {
+      if (current?.toLowerCase().includes(needle)) {
         results.push({ repoPath: entry.path, branch: current });
         matched.add(entry.path);
       }
@@ -1003,17 +1750,121 @@ async function detectFeatureBranches(repos, issueId, workspace, globalBaseBranch
 }
 
 // src/loop.ts
-async function runLoop(config2, opts) {
-  const provider = createProvider(config2.provider);
-  const source = createSource(config2.source);
-  const available = await provider.isAvailable();
-  if (!available) {
-    error(`Provider "${config2.provider}" is not installed or not in PATH.`);
+var activeCleanup = null;
+var shuttingDown = false;
+function resolveModels(config2) {
+  if (config2.models && config2.models.length > 0) return config2.models;
+  return [config2.provider];
+}
+function buildPrBody(issue, providerUsed) {
+  return `Closes ${issue.url}
+
+Implemented by [lisa](https://github.com/tarcisiopgs/lisa) using **${providerUsed}**.`;
+}
+var PR_TITLE_FILE = ".pr-title";
+function readPrTitle(cwd) {
+  try {
+    const title = readFileSync5(join7(cwd, PR_TITLE_FILE), "utf-8").trim().split("\n")[0]?.trim();
+    return title || null;
+  } catch {
+    return null;
+  }
+}
+function cleanupPrTitle(cwd) {
+  try {
+    unlinkSync4(join7(cwd, PR_TITLE_FILE));
+  } catch {
+  }
+}
+var MANIFEST_FILE = ".lisa-manifest.json";
+function readLisaManifest(dir) {
+  const manifestPath = join7(dir, MANIFEST_FILE);
+  if (!existsSync6(manifestPath)) return null;
+  try {
+    return JSON.parse(readFileSync5(manifestPath, "utf-8").trim());
+  } catch {
+    return null;
+  }
+}
+function cleanupManifest(dir) {
+  try {
+    unlinkSync4(join7(dir, MANIFEST_FILE));
+  } catch {
+  }
+}
+function installSignalHandlers() {
+  const cleanup = async (signal) => {
+    if (shuttingDown) {
+      warn("Force exiting...");
+      process.exit(1);
+    }
+    shuttingDown = true;
+    warn(`Received ${signal}. Reverting active issue...`);
+    if (activeCleanup) {
+      const { issueId, previousStatus, source } = activeCleanup;
+      try {
+        await Promise.race([
+          source.updateStatus(issueId, previousStatus),
+          new Promise(
+            (_, reject) => setTimeout(() => reject(new Error("Revert timed out")), 5e3)
+          )
+        ]);
+        ok(`Reverted ${issueId} to "${previousStatus}"`);
+      } catch (err) {
+        error(
+          `Failed to revert ${issueId}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
     process.exit(1);
+  };
+  process.on("SIGINT", () => {
+    cleanup("SIGINT");
+  });
+  process.on("SIGTERM", () => {
+    cleanup("SIGTERM");
+  });
+}
+async function recoverOrphanIssues(source, config2) {
+  const orphanConfig = {
+    ...config2.source_config,
+    pick_from: config2.source_config.in_progress
+  };
+  while (true) {
+    let orphan;
+    try {
+      orphan = await source.fetchNextIssue(orphanConfig);
+    } catch (err) {
+      warn(
+        `Failed to check for orphan issues: ${err instanceof Error ? err.message : String(err)}`
+      );
+      break;
+    }
+    if (!orphan) break;
+    warn(
+      `Found orphan issue ${orphan.id} stuck in "${config2.source_config.in_progress}". Reverting to "${config2.source_config.pick_from}".`
+    );
+    try {
+      await source.updateStatus(orphan.id, config2.source_config.pick_from);
+      ok(`Recovered orphan ${orphan.id}`);
+    } catch (err) {
+      error(
+        `Failed to recover orphan ${orphan.id}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      break;
+    }
   }
+}
+async function runLoop(config2, opts) {
+  const source = createSource(config2.source);
+  const models = resolveModels(config2);
+  installSignalHandlers();
   log(
-    `Starting loop (provider: ${config2.provider}, source: ${config2.source}, label: ${config2.source_config.label}, workflow: ${config2.workflow})`
+    `Starting loop (models: ${models.join(" \u2192 ")}, source: ${config2.source}, label: ${config2.source_config.label}, workflow: ${config2.workflow})`
   );
+  if (!opts.dryRun) {
+    await recoverOrphanIssues(source, config2);
+  }
   let session = 0;
   while (true) {
     session++;
@@ -1022,18 +1873,29 @@ async function runLoop(config2, opts) {
       break;
     }
     const timestamp2 = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").substring(0, 19);
-    const logFile = resolve4(config2.logs.dir, `session_${session}_${timestamp2}.log`);
+    const logFile = resolve5(config2.logs.dir, `session_${session}_${timestamp2}.log`);
     divider(session);
-    log(`Fetching next '${config2.source_config.label}' issue from ${config2.source}...`);
+    if (opts.issueId) {
+      log(`Fetching issue '${opts.issueId}' from ${config2.source}...`);
+    } else {
+      log(`Fetching next '${config2.source_config.label}' issue from ${config2.source}...`);
+    }
     if (opts.dryRun) {
-      log(`[dry-run] Would fetch issue from ${config2.source} (${config2.source_config.team}/${config2.source_config.project})`);
+      if (opts.issueId) {
+        log(`[dry-run] Would fetch issue '${opts.issueId}' from ${config2.source}`);
+      } else {
+        log(
+          `[dry-run] Would fetch issue from ${config2.source} (${config2.source_config.team}/${config2.source_config.project})`
+        );
+      }
       log(`[dry-run] Workflow mode: ${config2.workflow}`);
+      log(`[dry-run] Models priority: ${models.join(" \u2192 ")}`);
       log("[dry-run] Then implement, push, create PR, and update issue status");
       break;
     }
     let issue;
     try {
-      issue = await source.fetchNextIssue(config2.source_config);
+      issue = opts.issueId ? await source.fetchIssueById(opts.issueId) : await source.fetchNextIssue(config2.source_config);
     } catch (err) {
       error(`Failed to fetch issues: ${err instanceof Error ? err.message : String(err)}`);
       if (opts.once) break;
@@ -1041,10 +1903,15 @@ async function runLoop(config2, opts) {
       continue;
     }
     if (!issue) {
-      ok(`No more issues with label '${config2.source_config.label}'. Done.`);
+      if (opts.issueId) {
+        error(`Issue '${opts.issueId}' not found.`);
+      } else {
+        ok(`No more issues with label '${config2.source_config.label}'. Done.`);
+      }
       break;
     }
     ok(`Picked up: ${issue.id} \u2014 ${issue.title}`);
+    const previousStatus = config2.source_config.pick_from;
     try {
       const inProgress = config2.source_config.in_progress;
       await source.updateStatus(issue.id, inProgress);
@@ -1052,8 +1919,71 @@ async function runLoop(config2, opts) {
     } catch (err) {
       warn(`Failed to update status: ${err instanceof Error ? err.message : String(err)}`);
     }
-    const prUrls = config2.workflow === "worktree" ? await runWorktreeSession(config2, issue, logFile, session) : await runBranchSession(config2, issue, logFile, session);
-    for (const prUrl of prUrls) {
+    activeCleanup = { issueId: issue.id, previousStatus, source };
+    let sessionResult;
+    try {
+      sessionResult = config2.workflow === "worktree" ? await runWorktreeSession(config2, issue, logFile, session, models) : await runBranchSession(config2, issue, logFile, session, models);
+    } catch (err) {
+      error(
+        `Unhandled error in session for ${issue.id}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      try {
+        await source.updateStatus(issue.id, previousStatus);
+        ok(`Reverted ${issue.id} to "${previousStatus}"`);
+      } catch (revertErr) {
+        error(
+          `Failed to revert status: ${revertErr instanceof Error ? revertErr.message : String(revertErr)}`
+        );
+      }
+      activeCleanup = null;
+      if (opts.once) break;
+      log(`Cooling down ${config2.loop.cooldown}s before next issue...`);
+      await sleep(config2.loop.cooldown * 1e3);
+      continue;
+    }
+    if (!sessionResult.success) {
+      error(`All models failed for ${issue.id}. Reverting to "${previousStatus}".`);
+      logAttemptHistory(sessionResult);
+      try {
+        await source.updateStatus(issue.id, previousStatus);
+        ok(`Reverted ${issue.id} to "${previousStatus}"`);
+      } catch (err) {
+        error(
+          `Failed to revert status: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+      activeCleanup = null;
+      if (opts.once) {
+        log("Single iteration mode. Exiting.");
+        break;
+      }
+      log(`Cooling down ${config2.loop.cooldown}s before next issue...`);
+      await sleep(config2.loop.cooldown * 1e3);
+      continue;
+    }
+    ok(`Completed with provider: ${sessionResult.providerUsed}`);
+    if (sessionResult.prUrls.length === 0) {
+      warn(
+        `Session succeeded but no PRs created for ${issue.id}. Reverting to "${previousStatus}".`
+      );
+      try {
+        await source.updateStatus(issue.id, previousStatus);
+        ok(`Reverted ${issue.id} to "${previousStatus}"`);
+      } catch (err) {
+        error(
+          `Failed to revert status: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+      activeCleanup = null;
+      if (opts.once) {
+        log("Single iteration mode. Exiting.");
+        break;
+      }
+      log(`Cooling down ${config2.loop.cooldown}s before next issue...`);
+      await sleep(config2.loop.cooldown * 1e3);
+      continue;
+    }
+    for (const prUrl of sessionResult.prUrls) {
       try {
         await source.attachPullRequest(issue.id, prUrl);
         ok(`Attached PR to ${issue.id}`);
@@ -1061,19 +1991,24 @@ async function runLoop(config2, opts) {
         warn(`Failed to attach PR: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
+    let statusUpdated = false;
     try {
       const doneStatus = config2.source_config.done;
       await source.updateStatus(issue.id, doneStatus);
       ok(`Updated ${issue.id} status to "${doneStatus}"`);
+      statusUpdated = true;
     } catch (err) {
       error(`Failed to update status: ${err instanceof Error ? err.message : String(err)}`);
     }
-    try {
-      await source.removeLabel(issue.id, config2.source_config.label);
-      ok(`Removed label "${config2.source_config.label}" from ${issue.id}`);
-    } catch (err) {
-      error(`Failed to remove label: ${err instanceof Error ? err.message : String(err)}`);
+    if (statusUpdated && !opts.issueId) {
+      try {
+        await source.removeLabel(issue.id, config2.source_config.label);
+        ok(`Removed label "${config2.source_config.label}" from ${issue.id}`);
+      } catch (err) {
+        error(`Failed to remove label: ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
+    activeCleanup = null;
     if (opts.once) {
       log("Single iteration mode. Exiting.");
       break;
@@ -1083,14 +2018,49 @@ async function runLoop(config2, opts) {
   }
   ok(`lisa finished. ${session} session(s) run.`);
 }
+function logAttemptHistory(result) {
+  for (const [i, attempt] of result.fallback.attempts.entries()) {
+    const status2 = attempt.success ? "OK" : "FAILED";
+    const error2 = attempt.error ? ` \u2014 ${attempt.error}` : "";
+    const duration = attempt.duration > 0 ? ` (${Math.round(attempt.duration / 1e3)}s)` : "";
+    warn(`  Attempt ${i + 1}: ${attempt.provider} ${status2}${error2}${duration}`);
+  }
+}
 function resolveBaseBranch(config2, repoPath) {
-  const workspace = resolve4(config2.workspace);
-  const repo = config2.repos.find((r) => resolve4(workspace, r.path) === repoPath);
+  const workspace = resolve5(config2.workspace);
+  const repo = config2.repos.find((r) => resolve5(workspace, r.path) === repoPath);
   return repo?.base_branch ?? config2.base_branch;
 }
-async function runWorktreeSession(config2, issue, logFile, session) {
-  const provider = createProvider(config2.provider);
-  const workspace = resolve4(config2.workspace);
+function findRepoConfig(config2, issue) {
+  if (config2.repos.length === 0) return void 0;
+  if (issue.repo) {
+    const match = config2.repos.find((r) => r.name === issue.repo);
+    if (match) return match;
+  }
+  for (const r of config2.repos) {
+    if (r.match && issue.title.startsWith(r.match)) return r;
+  }
+  return config2.repos[0];
+}
+async function runTestValidation(cwd) {
+  const testRunner = detectTestRunner(cwd);
+  if (!testRunner) return true;
+  log(`Running test validation (${testRunner} detected)...`);
+  try {
+    await execa3("npm", ["run", "test"], { cwd, stdio: "pipe" });
+    ok("Tests passed.");
+    return true;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    error(`Tests failed: ${message}`);
+    return false;
+  }
+}
+async function runWorktreeSession(config2, issue, logFile, session, models) {
+  if (config2.repos.length > 1) {
+    return runWorktreeMultiRepoSession(config2, issue, logFile, session, models);
+  }
+  const workspace = resolve5(config2.workspace);
   const repoPath = determineRepoPath(config2.repos, issue, workspace) ?? workspace;
   const defaultBranch = resolveBaseBranch(config2, repoPath);
   const branchName = generateBranchName(issue.id, issue.title);
@@ -1100,39 +2070,121 @@ async function runWorktreeSession(config2, issue, logFile, session) {
     worktreePath = await createWorktree(repoPath, branchName, defaultBranch);
   } catch (err) {
     error(`Failed to create worktree: ${err instanceof Error ? err.message : String(err)}`);
-    return [];
+    return {
+      success: false,
+      providerUsed: models[0] ?? "claude",
+      prUrls: [],
+      fallback: {
+        success: false,
+        output: "",
+        duration: 0,
+        providerUsed: models[0] ?? "claude",
+        attempts: []
+      }
+    };
   }
   ok(`Worktree created at ${worktreePath}`);
-  const prompt = buildImplementPrompt(issue, config2);
+  const repo = findRepoConfig(config2, issue);
+  if (repo?.lifecycle) {
+    const started = await startResources(repo, worktreePath);
+    if (!started) {
+      error(`Lifecycle startup failed for ${issue.id}. Aborting session.`);
+      await cleanupWorktree(repoPath, worktreePath);
+      return {
+        success: false,
+        providerUsed: models[0] ?? "claude",
+        prUrls: [],
+        fallback: {
+          success: false,
+          output: "",
+          duration: 0,
+          providerUsed: models[0] ?? "claude",
+          attempts: []
+        }
+      };
+    }
+  }
+  const testRunner = detectTestRunner(worktreePath);
+  if (testRunner) {
+    log(`Detected test runner: ${testRunner}`);
+  }
+  const prompt = buildImplementPrompt(issue, config2, testRunner);
   log(`Implementing in worktree... (log: ${logFile})`);
   initLogFile(logFile);
-  const result = await provider.run(prompt, { logFile, cwd: worktreePath });
+  const result = await runWithFallback(models, prompt, {
+    logFile,
+    cwd: worktreePath,
+    guardrailsDir: repoPath,
+    issueId: issue.id,
+    overseer: config2.overseer
+  });
   try {
-    appendFileSync6(logFile, `
+    appendFileSync6(
+      logFile,
+      `
 ${"=".repeat(80)}
+Provider used: ${result.providerUsed}
 Full output:
 ${result.output}
-`);
+`
+    );
   } catch {
   }
+  if (repo?.lifecycle) {
+    await stopResources();
+  }
   if (!result.success) {
     error(`Session ${session} failed for ${issue.id}. Check ${logFile}`);
     await cleanupWorktree(repoPath, worktreePath);
-    return [];
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  const testsPassed = await runTestValidation(worktreePath);
+  if (!testsPassed) {
+    error(`Tests failed for ${issue.id}. Blocking PR creation.`);
+    await cleanupWorktree(repoPath, worktreePath);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  const manifest = readLisaManifest(worktreePath);
+  let effectiveBranch = branchName;
+  if (manifest?.branch && manifest.branch !== branchName) {
+    log(`Renaming branch to English name: ${manifest.branch}`);
+    try {
+      await execa3("git", ["branch", "-m", branchName, manifest.branch], { cwd: worktreePath });
+      effectiveBranch = manifest.branch;
+      ok(`Branch renamed to ${effectiveBranch}`);
+    } catch (err) {
+      warn(
+        `Branch rename failed, using original: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  try {
+    await execa3("git", ["push", "-u", "origin", effectiveBranch], { cwd: worktreePath });
+  } catch (err) {
+    error(
+      `Failed to push branch to remote: ${err instanceof Error ? err.message : String(err)}`
+    );
+    cleanupManifest(worktreePath);
+    await cleanupWorktree(repoPath, worktreePath);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
   }
+  const prTitle = manifest?.prTitle ?? readPrTitle(worktreePath) ?? issue.title;
+  cleanupPrTitle(worktreePath);
+  cleanupManifest(worktreePath);
   const prUrls = [];
   try {
     const repoInfo = await getRepoInfo(worktreePath);
-    const pr = await createPullRequest({
-      owner: repoInfo.owner,
-      repo: repoInfo.repo,
-      head: branchName,
-      base: defaultBranch,
-      title: issue.title,
-      body: `Closes ${issue.url}
-
-Implemented by [lisa](https://github.com/tarcisiopgs/lisa).`
-    }, config2.github);
+    const pr = await createPullRequest(
+      {
+        owner: repoInfo.owner,
+        repo: repoInfo.repo,
+        head: effectiveBranch,
+        base: defaultBranch,
+        title: prTitle,
+        body: buildPrBody(issue, result.providerUsed)
+      },
+      config2.github
+    );
     ok(`PR created: ${pr.html_url}`);
     prUrls.push(pr.html_url);
   } catch (err) {
@@ -1140,49 +2192,190 @@ Implemented by [lisa](https://github.com/tarcisiopgs/lisa).`
   }
   await cleanupWorktree(repoPath, worktreePath);
   ok(`Session ${session} complete for ${issue.id}`);
-  return prUrls;
+  return { success: true, providerUsed: result.providerUsed, prUrls, fallback: result };
+}
+async function runWorktreeMultiRepoSession(config2, issue, logFile, session, models) {
+  const workspace = resolve5(config2.workspace);
+  cleanupManifest(workspace);
+  const prompt = buildWorktreeMultiRepoPrompt(issue, config2);
+  log(`Multi-repo worktree session for ${issue.id} (agent selects repo and branch name)`);
+  log(`Implementing (agent selects repo)... (log: ${logFile})`);
+  initLogFile(logFile);
+  const result = await runWithFallback(models, prompt, {
+    logFile,
+    cwd: workspace,
+    guardrailsDir: workspace,
+    issueId: issue.id,
+    overseer: config2.overseer
+  });
+  try {
+    appendFileSync6(
+      logFile,
+      `
+${"=".repeat(80)}
+Provider used: ${result.providerUsed}
+Full output:
+${result.output}
+`
+    );
+  } catch {
+  }
+  if (!result.success) {
+    error(`Session ${session} failed for ${issue.id}. Check ${logFile}`);
+    cleanupManifest(workspace);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  const manifest = readLisaManifest(workspace);
+  if (!manifest?.repoPath || !manifest.branch) {
+    error(
+      `Agent did not produce a valid .lisa-manifest.json (requires repoPath + branch) for ${issue.id}. Aborting.`
+    );
+    cleanupManifest(workspace);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  ok(`Provider chose repo: ${manifest.repoPath}, branch: ${manifest.branch}`);
+  const worktreePath = join7(manifest.repoPath, ".worktrees", manifest.branch);
+  const baseBranch = resolveBaseBranch(config2, manifest.repoPath);
+  const testsPassed = await runTestValidation(worktreePath);
+  if (!testsPassed) {
+    error(`Tests failed for ${issue.id}. Blocking PR creation.`);
+    await cleanupWorktree(manifest.repoPath, worktreePath);
+    cleanupManifest(workspace);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  try {
+    await execa3("git", ["push", "-u", "origin", manifest.branch], { cwd: worktreePath });
+  } catch (err) {
+    error(
+      `Failed to push branch to remote: ${err instanceof Error ? err.message : String(err)}`
+    );
+    await cleanupWorktree(manifest.repoPath, worktreePath);
+    cleanupManifest(workspace);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  const prTitle = manifest.prTitle ?? issue.title;
+  const prUrls = [];
+  try {
+    const repoInfo = await getRepoInfo(worktreePath);
+    const pr = await createPullRequest(
+      {
+        owner: repoInfo.owner,
+        repo: repoInfo.repo,
+        head: manifest.branch,
+        base: baseBranch,
+        title: prTitle,
+        body: buildPrBody(issue, result.providerUsed)
+      },
+      config2.github
+    );
+    ok(`PR created: ${pr.html_url}`);
+    prUrls.push(pr.html_url);
+  } catch (err) {
+    error(`Failed to create PR: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  cleanupManifest(workspace);
+  await cleanupWorktree(manifest.repoPath, worktreePath);
+  ok(`Session ${session} complete for ${issue.id}`);
+  return { success: true, providerUsed: result.providerUsed, prUrls, fallback: result };
 }
-async function runBranchSession(config2, issue, logFile, session) {
-  const provider = createProvider(config2.provider);
-  const prompt = buildImplementPrompt(issue, config2);
-  const workspace = resolve4(config2.workspace);
+async function runBranchSession(config2, issue, logFile, session, models) {
+  const workspace = resolve5(config2.workspace);
+  cleanupManifest(workspace);
+  const testRunner = detectTestRunner(workspace);
+  if (testRunner) {
+    log(`Detected test runner: ${testRunner}`);
+  }
+  const prompt = buildImplementPrompt(issue, config2, testRunner);
+  const repo = findRepoConfig(config2, issue);
+  if (repo?.lifecycle) {
+    const cwd = resolve5(workspace, repo.path);
+    const started = await startResources(repo, cwd);
+    if (!started) {
+      error(`Lifecycle startup failed for ${issue.id}. Aborting session.`);
+      return {
+        success: false,
+        providerUsed: models[0] ?? "claude",
+        prUrls: [],
+        fallback: {
+          success: false,
+          output: "",
+          duration: 0,
+          providerUsed: models[0] ?? "claude",
+          attempts: []
+        }
+      };
+    }
+  }
   log(`Implementing... (log: ${logFile})`);
   initLogFile(logFile);
-  const result = await provider.run(prompt, { logFile, cwd: workspace });
+  const result = await runWithFallback(models, prompt, {
+    logFile,
+    cwd: workspace,
+    guardrailsDir: workspace,
+    issueId: issue.id,
+    overseer: config2.overseer
+  });
   try {
-    appendFileSync6(logFile, `
+    appendFileSync6(
+      logFile,
+      `
 ${"=".repeat(80)}
+Provider used: ${result.providerUsed}
 Full output:
 ${result.output}
-`);
+`
+    );
   } catch {
   }
+  if (repo?.lifecycle) {
+    await stopResources();
+  }
   if (!result.success) {
     error(`Session ${session} failed for ${issue.id}. Check ${logFile}`);
-    return [];
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  const testsPassed = await runTestValidation(workspace);
+  if (!testsPassed) {
+    error(`Tests failed for ${issue.id}. Blocking PR creation.`);
+    cleanupManifest(workspace);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  const manifest = readLisaManifest(workspace);
+  let detected;
+  if (manifest?.repoPath && manifest.branch) {
+    ok(`Using manifest: repo=${manifest.repoPath}, branch=${manifest.branch}`);
+    detected = [{ repoPath: manifest.repoPath, branch: manifest.branch }];
+  } else {
+    if (manifest) {
+      warn(`Manifest found but missing repoPath or branch \u2014 falling back to detection`);
+    }
+    detected = await detectFeatureBranches(config2.repos, issue.id, workspace, config2.base_branch);
   }
-  const detected = await detectFeatureBranches(config2.repos, issue.id, workspace, config2.base_branch);
+  cleanupManifest(workspace);
   if (detected.length === 0) {
     error(`Could not detect feature branch for ${issue.id} \u2014 skipping PR creation`);
     ok(`Session ${session} complete for ${issue.id}`);
-    return [];
+    return { success: true, providerUsed: result.providerUsed, prUrls: [], fallback: result };
   }
+  const prTitle = manifest?.prTitle ?? readPrTitle(workspace) ?? issue.title;
+  cleanupPrTitle(workspace);
   const prUrls = [];
   for (const { repoPath, branch } of detected) {
     const baseBranch = resolveBaseBranch(config2, repoPath);
     if (branch === baseBranch) continue;
     try {
       const repoInfo = await getRepoInfo(repoPath);
-      const pr = await createPullRequest({
-        owner: repoInfo.owner,
-        repo: repoInfo.repo,
-        head: branch,
-        base: baseBranch,
-        title: issue.title,
-        body: `Closes ${issue.url}
-
-Implemented by [lisa](https://github.com/tarcisiopgs/lisa).`
-      }, config2.github);
+      const pr = await createPullRequest(
+        {
+          owner: repoInfo.owner,
+          repo: repoInfo.repo,
+          head: branch,
+          base: baseBranch,
+          title: prTitle,
+          body: buildPrBody(issue, result.providerUsed)
+        },
+        config2.github
+      );
       ok(`PR created: ${pr.html_url}`);
       prUrls.push(pr.html_url);
     } catch (err) {
@@ -1190,7 +2383,7 @@ Implemented by [lisa](https://github.com/tarcisiopgs/lisa).`
     }
   }
   ok(`Session ${session} complete for ${issue.id}`);
-  return prUrls;
+  return { success: true, providerUsed: result.providerUsed, prUrls, fallback: result };
 }
 async function cleanupWorktree(repoRoot, worktreePath) {
   try {
@@ -1201,7 +2394,7 @@ async function cleanupWorktree(repoRoot, worktreePath) {
   }
 }
 function sleep(ms) {
-  return new Promise((resolve5) => setTimeout(resolve5, ms));
+  return new Promise((resolve6) => setTimeout(resolve6, ms));
 }
 
 // src/cli.ts
@@ -1211,6 +2404,7 @@ var run = defineCommand({
     once: { type: "boolean", description: "Run a single iteration", default: false },
     limit: { type: "string", description: "Max number of issues to process", default: "0" },
     "dry-run": { type: "boolean", description: "Preview without executing", default: false },
+    issue: { type: "string", description: "Run a specific issue by identifier or URL" },
     provider: { type: "string", description: "AI provider (claude, gemini, opencode)" },
     source: { type: "string", description: "Issue source (linear, trello)" },
     label: { type: "string", description: "Label to filter issues" },
@@ -1236,16 +2430,21 @@ var run = defineCommand({
     const missingVars = await getMissingEnvVars(merged.source);
     if (missingVars.length > 0) {
       const shell = process.env.SHELL?.includes("zsh") ? "~/.zshrc" : "~/.bashrc";
-      console.error(pc2.red(`Missing required environment variables:
-${missingVars.map((v) => `  ${v}`).join("\n")}`));
+      console.error(
+        pc2.red(
+          `Missing required environment variables:
+${missingVars.map((v) => `  ${v}`).join("\n")}`
+        )
+      );
       console.error(pc2.dim(`
 Add them to your ${shell} and run: source ${shell}`));
       process.exit(1);
     }
     await runLoop(merged, {
-      once: args.once,
+      once: args.once || !!args.issue,
       limit: Number.parseInt(args.limit, 10),
-      dryRun: args["dry-run"]
+      dryRun: args["dry-run"],
+      issueId: args.issue
     });
   }
 });
@@ -1281,7 +2480,9 @@ var init = defineCommand({
   meta: { name: "init", description: "Initialize lisa configuration" },
   async run() {
     if (!process.stdin.isTTY) {
-      console.error(pc2.red("Interactive mode requires a TTY. Cannot run init in non-interactive environments."));
+      console.error(
+        pc2.red("Interactive mode requires a TTY. Cannot run init in non-interactive environments.")
+      );
       process.exit(1);
     }
     if (configExists()) {
@@ -1315,8 +2516,8 @@ var status = defineCommand({
     console.log(`  In progress: ${pc2.bold(config2.source_config.in_progress)}`);
     console.log(`  Done:        ${pc2.bold(config2.source_config.done)}`);
     console.log(`  Logs:        ${pc2.dim(config2.logs.dir)}`);
-    const { readdirSync: readdirSync2, existsSync: existsSync5 } = await import("fs");
-    if (existsSync5(config2.logs.dir)) {
+    const { readdirSync: readdirSync2, existsSync: existsSync8 } = await import("fs");
+    if (existsSync8(config2.logs.dir)) {
       const logs = readdirSync2(config2.logs.dir).filter((f) => f.endsWith(".log"));
       console.log(`
 ${pc2.cyan("Sessions:")} ${logs.length} log file(s) found`);
@@ -1329,7 +2530,7 @@ ${pc2.dim("No sessions yet.")}`);
 function getVersion() {
   try {
     const pkgPath = resolvePath(new URL(".", import.meta.url).pathname, "../package.json");
-    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync6(pkgPath, "utf-8"));
     return pkg.version;
   } catch {
     return "0.0.0";
@@ -1339,7 +2540,7 @@ var main = defineCommand({
   meta: {
     name: "lisa",
     version: getVersion(),
-    description: "Autonomous issue resolver \u2014 AI agent loop for Linear/Trello"
+    description: "Deterministic autonomous issue resolver \u2014 structured AI agent loop for Linear/Trello"
   },
   subCommands: { run, config, init, status }
 });
@@ -1365,7 +2566,7 @@ After installing, run ${pc2.cyan("lisa init")} again.`
     return process.exit(1);
   }
   let providerName;
-  if (available.length === 1) {
+  if (available.length === 1 && available[0]) {
     providerName = available[0].name;
     clack.log.info(`Found provider: ${pc2.bold(providerLabels[providerName])}`);
   } else {
@@ -1551,12 +2752,12 @@ async function detectGitHubMethod() {
 }
 async function detectGitRepos() {
   const cwd = process.cwd();
-  if (existsSync4(join5(cwd, ".git"))) {
+  if (existsSync7(join8(cwd, ".git"))) {
     clack.log.info(`Detected git repository in current directory.`);
     return [];
   }
   const entries = readdirSync(cwd, { withFileTypes: true });
-  const gitDirs = entries.filter((e) => e.isDirectory() && existsSync4(join5(cwd, e.name, ".git"))).map((e) => e.name);
+  const gitDirs = entries.filter((e) => e.isDirectory() && existsSync7(join8(cwd, e.name, ".git"))).map((e) => e.name);
   if (gitDirs.length === 0) {
     return [];
   }
@@ -1566,7 +2767,7 @@ async function detectGitRepos() {
   });
   if (clack.isCancel(selected)) return process.exit(0);
   return selected.map((dir) => ({
-    name: getGitRepoName(join5(cwd, dir)) ?? dir,
+    name: getGitRepoName(join8(cwd, dir)) ?? dir,
     path: `./${dir}`,
     match: "",
     base_branch: ""