@tarcisiopgs/lisa 0.9.6 → 1.0.1

package/README.md

@@ -6,7 +6,7 @@
 
 While the Ralphs of the world flooded GitHub with mindless agent loops — brute-forcing their way through issues with no context, no workflow awareness, and no regard for the mess they leave behind — Lisa takes a different approach. She reads the issue, understands the workspace, picks the right repo, creates the branch, validates her work, and opens the PR. Then she moves on to the next one. When there's nothing left to do, she stops.
 
-Named after the smartest Simpson, Lisa is an autonomous issue resolver that connects your project tracker (Linear or Trello) to an AI coding agent (Claude Code, Gemini CLI, or OpenCode) and delivers pull requests via the GitHub API. No MCP servers. No prompt chains. No blind retries. Just structured, end-to-end execution.
+Named after the smartest Simpson, Lisa is an autonomous issue resolver that connects your project tracker (Linear or Trello) to an AI coding agent (Claude Code, Gemini CLI, or OpenCode) and delivers pull requests via GitHub. No MCP servers. No prompt chains. No blind retries. Just structured, end-to-end execution.
 
 ## Why Lisa?
 
@@ -14,10 +14,12 @@ Most AI agent loops work like Ralph — they grab an issue, throw it at a model,
 
 Lisa is deterministic. She follows a structured pipeline with clear stages (fetch, activate, implement, validate, PR, update) and stops when the work is done. This means:
 
-- **Token efficiency** — Each issue gets one focused prompt with full context (description, acceptance criteria, repo conventions). No wasted retries, no speculative exploration, no idle polling burning API calls.
-- **Multi-repo awareness** — Lisa detects which repos the agent actually touched and creates a PR for each. No guessing, no hardcoded paths.
-- **Workflow integration** — Issues move through your board in real time (Todo, In Progress, In Review). Your team always knows what's being worked on.
-- **Predictable cost** — One issue = one agent session = one set of PRs. You can estimate cost per issue instead of hoping the loop eventually converges.
+- **Token efficiency** — Each issue gets one focused prompt with full context. No wasted retries, no speculative exploration, no idle polling.
+- **Multi-repo awareness** — Lisa detects which repos the agent touched and creates one PR per repo. Monorepos with multiple packages just work.
+- **Model fallback** — Configure a chain of models (`claude → gemini → opencode`). Transient errors (429, quota, timeout) trigger the next model; non-transient errors stop the chain.
+- **Workflow integration** — Issues move through your board in real time (Backlog → In Progress → In Review). Your team always knows what's being worked on.
+- **Self-healing** — Orphan issues (stuck in "In Progress" from interrupted runs) are automatically recovered on startup. Pre-push hook failures trigger the agent to fix and retry.
+- **Guardrails** — Past failures are logged and injected into future prompts so the agent avoids repeating mistakes.
 
 ## Install
 
@@ -27,11 +29,9 @@ npm install -g @tarcisiopgs/lisa
 
 ## Environment Variables
 
-Lisa calls external APIs directly. Set these in your shell profile (`~/.zshrc` or `~/.bashrc`):
-
 ```bash
-# Required (always)
-export GITHUB_TOKEN=""
+# Required (at least one)
+export GITHUB_TOKEN=""    # or have `gh` CLI authenticated
 
 # Required when source = linear
 export LINEAR_API_KEY=""
@@ -41,24 +41,28 @@ export TRELLO_API_KEY=""
 export TRELLO_TOKEN=""
 ```
 
-The CLI will warn you if any required variable is missing.
-
 ## Quick Start
 
 ```bash
 # Interactive setup
 lisa init
 
-# Run continuously
+# Run continuously until all labeled issues are done
 lisa run
 
 # Single issue
 lisa run --once
 
+# Specific issue by identifier or URL
+lisa run --issue INT-150
+
+# Process up to N issues
+lisa run --limit 5
+
 # Preview without executing
 lisa run --dry-run
 
-# Override provider
+# Override provider for a single run
 lisa run --provider gemini --once
 ```
 
@@ -68,8 +72,13 @@ lisa run --provider gemini --once
 |---------|-------------|
 | `lisa run` | Run the agent loop |
 | `lisa run --once` | Process a single issue |
+| `lisa run --issue ID` | Process a specific issue by identifier or URL |
 | `lisa run --limit N` | Process up to N issues |
 | `lisa run --dry-run` | Preview without executing |
+| `lisa run --provider NAME` | Override AI provider |
+| `lisa run --label NAME` | Override label filter |
+| `lisa run --json` | Output as JSON lines |
+| `lisa run --quiet` | Suppress non-essential output |
 | `lisa config` | Interactive config wizard |
 | `lisa config --show` | Show current config |
 | `lisa config --set key=value` | Set a config value |
@@ -86,106 +95,137 @@ lisa run --provider gemini --once
 
 At least one provider must be installed and available in your PATH.
 
-All providers stream output to stdout and to the session log file in real time. Prompts are written to a temp file and passed via shell expansion (`$(cat file)`) to avoid argument length limits.
+All providers use `child_process.spawn` with `sh -c`. Prompts are written to a temp file and passed via `$(cat file)` to avoid argument length limits. Output streams to both stdout and the session log file in real time.
 
-## Workflow Modes
+### Fallback Chain
+
+Configure multiple models in the `models` array. Lisa tries them in order — transient errors (429, quota, timeout, network) trigger the next model. Non-transient errors stop the chain immediately.
+
+```yaml
+models:
+  - claude
+  - gemini
+```
+
+If `models` is not set, Lisa uses the single `provider` field.
 
-Lisa supports two workflow modes, configured during `lisa init`:
+## Workflow Modes
 
-### Branch (default)
+### Branch
 
 The AI agent creates a branch directly in your current checkout, implements the changes, and pushes. Simple setup, works everywhere.
 
 ### Worktree
 
-Lisa creates an isolated [git worktree](https://git-scm.com/docs/git-worktree) for each issue under `.worktrees/`. The AI agent works inside the worktree without touching your main checkout. After the PR is created, the worktree is cleaned up automatically.
+Lisa creates an isolated [git worktree](https://git-scm.com/docs/git-worktree) for each issue under `.worktrees/`. The agent works inside the worktree without touching your main checkout. After the PR is created, the worktree is cleaned up automatically.
+
+In multi-repo workspaces, the agent selects the correct repository, creates the worktree, implements, and writes a `.lisa-manifest.json` with the repo path, branch name, and PR title. Lisa reads the manifest to push and create the PR.
 
 Worktree mode is ideal when you want to keep working in the repo while Lisa resolves issues in the background.
 
 ## Configuration
 
-Config lives in `.lisa/config.yaml`:
+Config lives in `.lisa/config.yaml`. Run `lisa init` to create it interactively.
 
-**Linear:**
 ```yaml
 provider: claude
+models:
+  - claude
+  - gemini
 source: linear
-workflow: branch
+workflow: worktree
 
 source_config:
   team: Engineering
   project: Web App
   label: ready
-  pick_from: Todo
+  pick_from: Backlog
   in_progress: In Progress
   done: In Review
 
-github: cli
+github: cli          # "cli" (gh) or "token" (GITHUB_TOKEN)
 workspace: .
+base_branch: main
+
 repos:
-  - name: app
+  - name: my-api
+    path: ./api
+    base_branch: main
+  - name: my-app
     path: ./app
-    match: "App:"
+    base_branch: main
 
 loop:
-  cooldown: 10
-  max_sessions: 0
+  cooldown: 10       # seconds between issues
+  max_sessions: 0    # 0 = unlimited
 
 logs:
   dir: .lisa/logs
-  format: text
-```
+  format: text       # "text" or "json"
 
-**Trello:**
-```yaml
-provider: claude
-source: trello
-workflow: branch
-
-source_config:
-  board: Product
-  pick_from: Backlog
-  label: ready
-  in_progress: In Progress
-  done: Code Review
-
-github: cli
-workspace: .
-
-loop:
-  cooldown: 10
-  max_sessions: 0
-
-logs:
-  dir: .lisa/logs
-  format: text
+# Optional — kill stuck providers
+overseer:
+  enabled: true
+  check_interval: 30     # seconds between git status checks
+  stuck_threshold: 300   # seconds without git changes before killing
 ```
 
-### Source-specific fields
+### Source-Specific Fields
 
 | Field | Linear | Trello |
 |-------|--------|--------|
-| `team` / `board` | Team name | Board name |
+| `team` | Team name | Board name |
 | `project` | Project name | — |
-| `pick_from` | Status to pick issues from (e.g. Todo) | List to pick cards from (e.g. Backlog) |
+| `pick_from` | Status to pick issues from | List to pick cards from |
 | `label` | Label to filter issues | Label to filter cards |
-| `in_progress` | In-progress status (e.g. In Progress) | In-progress column |
-| `done` | Destination status (e.g. In Review) | Destination column (e.g. Code Review) |
+| `in_progress` | In-progress status | In-progress column |
+| `done` | Destination status after PR | Destination column after PR |
 
-CLI flags override config values:
+### Lifecycle Resources
 
-```bash
-lisa run --provider gemini --label "urgent"
+For repos that need services running during implementation (databases, dev servers):
+
+```yaml
+repos:
+  - name: my-api
+    path: ./api
+    base_branch: main
+    lifecycle:
+      resources:
+        - name: postgres
+          check_port: 5432
+          up: "docker compose up -d postgres"
+          down: "docker compose down"
+          startup_timeout: 30
+      setup:
+        - "npx prisma generate"
+        - "npx prisma db push"
 ```
 
+Lisa starts resources before the agent runs, waits for the port to be ready, runs setup commands, then stops everything after the session.
+
 ## How It Works
 
-1. **Fetch** — Pulls the next issue from Linear or Trello matching the configured label, team, and project. Issues are sorted by priority.
-2. **Activate** — Moves the issue to the `in_progress` status so your team knows it's being worked on.
-3. **Implement** — Builds a structured prompt with full issue context and sends it to the AI agent. The agent creates a branch, implements, validates (lint, typecheck, tests), commits, and pushes.
-4. **PR** — Detects every repo the agent touched and creates a pull request for each, referencing the original issue. Multi-repo workspaces are handled automatically.
-5. **Update** — Moves the issue to the `done` status and removes the pickup label.
-6. **Next** — Picks the next issue. When there are no more issues, Lisa stops. No idle polling, no wasted cycles.
+```
+┌─────────┐    ┌──────────┐    ┌───────────┐    ┌──────────┐    ┌────┐    ┌────────┐
+│  Fetch   │───▶│ Activate │───▶│ Implement │───▶│ Validate │───▶│ PR │───▶│ Update │
+└─────────┘    └──────────┘    └───────────┘    └──────────┘    └────┘    └────────┘
+```
+
+1. **Fetch** — Pulls the next issue from Linear or Trello matching the configured label, team, and project. Issues are sorted by priority. Blocked issues (with unresolved dependencies) are skipped.
+2. **Activate** — Moves the issue to `in_progress` so your team knows it's being worked on.
+3. **Implement** — Builds a structured prompt with full issue context and sends it to the AI agent. The agent works in a worktree or branch, implements the change, runs validation, and commits.
+4. **Validate** — Runs the project's test suite. If tests fail, the session is aborted and the issue reverts.
+5. **PR** — Pushes the branch and creates a pull request referencing the original issue. If pre-push hooks fail, Lisa re-invokes the agent to fix the errors and retries (up to 2 recovery attempts).
+6. **Update** — Moves the issue to the `done` status and removes the pickup label in a single atomic operation.
+7. **Next** — Picks the next issue. When there are no more matching issues, Lisa stops.
+
+### Recovery Mechanisms
+
+- **Orphan recovery** — On startup, Lisa scans for issues stuck in `in_progress` from previous interrupted runs and reverts them to `pick_from`.
+- **Push recovery** — If `git push` fails due to pre-push hooks (linter, typecheck, tests), Lisa re-invokes the agent with the error output and retries the push.
+- **Signal handling** — SIGINT/SIGTERM gracefully revert the active issue to its previous status before exiting.
+- **Guardrails** — Failed sessions are logged to `.lisa/guardrails.md` and injected into future prompts so the agent avoids repeating the same mistakes.
 
 ## License
 

package/dist/index.js

@@ -1488,6 +1488,56 @@ var LinearSource = class {
   }
   async attachPullRequest(_issueId, _prUrl) {
   }
+  async completeIssue(issueId, statusName, labelToRemove) {
+    const issueData = await gql(
+      `query($identifier: String!) {
+				issue(id: $identifier) {
+					id
+					team { id }
+					labels { nodes { id name } }
+				}
+			}`,
+      { identifier: issueId }
+    );
+    const statesData = await gql(
+      `query($teamId: ID!) {
+				workflowStates(filter: { team: { id: { eq: $teamId } } }) {
+					nodes { id name }
+				}
+			}`,
+      { teamId: issueData.issue.team.id }
+    );
+    const state = statesData.workflowStates.nodes.find(
+      (s) => s.name.toLowerCase() === statusName.toLowerCase()
+    );
+    if (!state) {
+      const available = statesData.workflowStates.nodes.map((s) => s.name).join(", ");
+      throw new Error(`Status "${statusName}" not found. Available: ${available}`);
+    }
+    const input = { stateId: state.id };
+    if (labelToRemove) {
+      const currentLabels = issueData.issue.labels.nodes;
+      const filtered = currentLabels.filter(
+        (l) => l.name.toLowerCase() !== labelToRemove.toLowerCase()
+      );
+      if (filtered.length !== currentLabels.length) {
+        input.labelIds = filtered.map((l) => l.id);
+      }
+    }
+    const mutationResult = await gql(
+      `mutation($issueId: String!, $input: IssueUpdateInput!) {
+				issueUpdate(id: $issueId, input: $input) {
+					success
+				}
+			}`,
+      { issueId: issueData.issue.id, input }
+    );
+    if (!mutationResult.issueUpdate.success) {
+      throw new Error(
+        `issueUpdate returned success=false for ${issueId} (stateId: ${state.id}, stateName: ${state.name})`
+      );
+    }
+  }
   async removeLabel(issueId, labelName) {
     const issueData = await gql(
       `query($identifier: String!) {
@@ -1630,6 +1680,12 @@ var TrelloSource = class {
   async attachPullRequest(cardId, prUrl) {
     await trelloPost(`/cards/${cardId}/attachments`, `url=${encodeURIComponent(prUrl)}`);
   }
+  async completeIssue(cardId, listName, labelToRemove) {
+    await this.updateStatus(cardId, listName);
+    if (labelToRemove) {
+      await this.removeLabel(cardId, labelToRemove);
+    }
+  }
   async removeLabel(cardId, labelName) {
     const card = await trelloGet(
       `/cards/${cardId}`,
@@ -2082,22 +2138,16 @@ 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);
+      const labelToRemove = opts.issueId ? void 0 : config2.source_config.label;
+      await source.completeIssue(issue.id, doneStatus, labelToRemove);
       ok(`Updated ${issue.id} status to "${doneStatus}"`);
-      statusUpdated = true;
-    } catch (err) {
-      error(`Failed to update status: ${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)}`);
+      if (labelToRemove) {
+        ok(`Removed label "${labelToRemove}" from ${issue.id}`);
       }
+    } catch (err) {
+      error(`Failed to complete issue: ${err instanceof Error ? err.message : String(err)}`);
     }
     activeCleanup = null;
     if (opts.once) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tarcisiopgs/lisa",
-	"version": "0.9.6",
+	"version": "1.0.1",
 	"description": "Deterministic autonomous issue resolver — structured AI agent loop for Linear/Trello",
 	"license": "MIT",
 	"type": "module",