loreli 1.0.0 → 2.0.0

package/README.md

@@ -52,6 +52,7 @@ export GITHUB_TOKEN=ghp_your_token_here
 ```
 
 To persist it, add the export to your shell profile (`~/.zshrc`, `~/.bashrc`) or create a `.env` file in the project root. Never commit tokens to version control.
+> 🔐 **Secret handling** — Personal access tokens carry the same blast radius as your GitHub account. Keep them in environment variables or a secret manager, scope them to the minimum permissions, and rotate them regularly. See [GitHub’s “Keeping your API credentials secure” guidance](https://docs.github.com/en/rest/authentication/keeping-your-api-credentials-secure) for the official checklist.
 
 <details>
 <summary>Using a fine-grained token instead</summary>
@@ -81,6 +82,12 @@ Hold off on running `loreli` commands until you've completed Step 4, because the
 
 Loreli runs as an MCP server over stdio. Your IDE or MCP client needs a config entry that tells it how to start Loreli. Add this to your **global** (user-level) MCP settings so the token stays out of project files.
 
+Before editing any config file:
+
+1. Export `GITHUB_TOKEN` in the shell or source it from a local `.env` so the value never lands in Git history.
+2. Use your client’s environment forwarding rather than pasting literals. Cursor and VS Code expand `${env:NAME}` placeholders inside `mcpServers` blocks, while Claude’s `.mcp.json` honors `${NAME}` tokens per the [Cursor MCP docs](https://docs.cursor.com/ko/context/mcp), [VS Code variable reference](https://code.visualstudio.com/docs/editor/variables-reference), and [Claude Code MCP guide](https://docs.claude.ai/claude-code/mcp).
+3. Keep repo-level `loreli.yml` and workspace configs secret-free; only user-level config or wrapper scripts should reference tokens.
+
 **Cursor / VS Code** — open **Settings** > search **MCP** > **Edit in settings.json**, or add directly to your user-level `~/.cursor/mcp.json`:
 
 ```json
@@ -90,13 +97,15 @@ Loreli runs as an MCP server over stdio. Your IDE or MCP client needs a config e
       "command": "npx",
       "args": ["loreli", "mcp"],
       "env": {
-        "GITHUB_TOKEN": "ghp_your_token_here"
+        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
       }
     }
   }
 }
 ```
 
+Cursor and VS Code both expand `${env:NAME}` placeholders, so this entry reads the token you already exported (`export GITHUB_TOKEN=...`) without storing it in the config. Cursor additionally supports an `envFile` attribute if you prefer pointing at a dedicated `.env` file that lives outside your repos (see the [Cursor MCP docs](https://docs.cursor.com/ko/context/mcp) for the full schema).
+
 **Claude Code (CLI)** — add to your user-level config at `~/.claude/.mcp.json`:
 
 ```json
@@ -106,14 +115,14 @@ Loreli runs as an MCP server over stdio. Your IDE or MCP client needs a config e
       "command": "npx",
       "args": ["loreli", "mcp"],
       "env": {
-        "GITHUB_TOKEN": "ghp_your_token_here"
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
       }
     }
   }
 }
 ```
 
-The `env` block keeps the token scoped to Loreli's process. Alternatively, if `GITHUB_TOKEN` is already exported in your shell profile, you can omit the `env` block entirely — Loreli reads `process.env.GITHUB_TOKEN` at startup.
+The `env` block keeps the token scoped to Loreli's process, and Claude expands `${VAR}` placeholders at load time per the [Claude Code MCP guide](https://docs.claude.ai/claude-code/mcp#environment-variable-expansion), so you only need to manage the token in your shell. Alternatively, if `GITHUB_TOKEN` is already exported in your shell profile, you can omit the `env` block entirely — Loreli reads `process.env.GITHUB_TOKEN` at startup.
 
 <details>
 <summary>Claude Desktop</summary>
@@ -129,12 +138,14 @@ Add to your Claude Desktop config file:
       "command": "npx",
       "args": ["loreli", "mcp"],
       "env": {
-        "GITHUB_TOKEN": "ghp_your_token_here"
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
       }
     }
   }
 }
 ```
+
+Claude Desktop shares the same `.mcp.json` schema as the CLI, so `${GITHUB_TOKEN}` resolves against the environment variable available when the desktop app launches. Keep the variable in your login shell or macOS Keychain-backed launch script instead of copying the literal token into this file.
 </details>
 
 <details>
@@ -146,9 +157,10 @@ Add to `~/.codex/config.toml` (user-level):
 [mcp_servers.loreli]
 command = "npx"
 args = ["loreli", "mcp"]
+env_vars = ["GITHUB_TOKEN"]
 ```
 
-Codex reads `GITHUB_TOKEN` from the shell environment. Set it in your shell profile before running `codex`.
+Codex only forwards a short built-in whitelist of environment variables to STDIO MCP servers; anything sensitive like `GITHUB_TOKEN` must be explicitly listed in `env_vars` so the CLI copies it from your shell into the Loreli process without writing the value to disk. Once you add the line above and export `GITHUB_TOKEN` in your shell, Codex will pass it through on launch per the [Codex config reference](https://developers.openai.com/codex/config-reference) and [docs/example-config](https://fossies.org/linux/codex-rust/docs/example-config.md).
 </details>
 
 To confirm your MCP configuration is discoverable by the CLI, run the commands below in a shell where `GITHUB_TOKEN` is set. This matters because the CLI resolves tool calls through the MCP server entry, and without it even `loreli --version` and `loreli tools list` will fail. You should see the version string and a list of available tools.
@@ -299,13 +311,15 @@ Death snapshots are cleaned up by `Storage.prune()` alongside other session data
 
 ## Agent Backends
 
-Loreli supports multiple agent backends. The `BackendRegistry` auto-discovers which are available at startup.
+Loreli supports multiple agent backends. The `BackendRegistry` auto-discovers which are available at startup, including available models for backends that support runtime discovery.
+
+| Backend | CLI Binary | Provider | Model Discovery |
+|---------|-----------|----------|----------------|
+| Claude | `claude` | Anthropic | Proxy listing (`/v1/models` or `/models`) when `ANTHROPIC_BASE_URL` is configured; otherwise static defaults |
+| Cursor | `cursor-agent` | Multi-provider | `--list-models` with auto tier classification |
+| Codex | `codex` | OpenAI | Proxy listing (`/v1/models` or `/models`) when `OPENAI_BASE_URL` is configured; otherwise static defaults |
 
-| Backend | CLI Binary | Provider | Description |
-|---------|-----------|----------|-------------|
-| Claude | `claude` | Anthropic | Stays running in tmux, receives messages |
-| Cursor | `cursor-agent` | Multi-provider | Multi-provider via Cursor's model routing |
-| Codex | `codex` | OpenAI | Interactive CLI agent (--full-auto, --no-alt-screen, file-based prompts) |
+Model aliases (`fast`, `balanced`, `powerful`) resolve through: config override > runtime discovery > static defaults > pass-through. See [packages/agent/README.md](packages/agent/README.md) for the full resolution chain and LiteLLM/proxy override docs.
 
 Loreli derives review strategy from detected side capability at runtime:
 
@@ -333,7 +347,7 @@ pr:
     command: npm test      # default pre-PR command; blocks pr/create on failure
   selfReview:
     enabled: true          # default: pr/create requires preview + confirm=true
-model: balanced            # fast | balanced | powerful
+model: balanced            # fast | balanced | powerful (global fallback)
 labels:
   track: true              # enable provider/model label tracking
   extra: []                # additional labels applied to all loreli items
@@ -341,6 +355,9 @@ timeouts:
   stall: "10m"             # human-readable before agent is considered stalled
   shutdown: "1m"            # graceful shutdown before kill
   poll: "2s"               # orchestrator poll interval
+  rapidDeath: "15s"        # startup crash detection window
+  proxyDiscovery: "5s"     # HTTP timeout for proxy model discovery
+  nudge: true              # enable tier-1 stall nudge messages
 watch:
   interval: "60s"          # reactor tick interval
   maxRounds: 7             # max review rounds before escalation
@@ -352,11 +369,30 @@ agents:
   disallowedTools:         # CLI tools denied in agent workspaces
     - gh
     - curl
-prompts:
-  action: .loreli/action.md   # custom prompt for action agents (relative to repo root)
-  reviewer: .loreli/review.md # custom prompt for reviewer agents
-  planner: .loreli/planner.md # custom prompt for planner agents
-  risk: .loreli/risk.md       # custom prompt for risk agents
+workflows:                 # per-role model, scaling, trace, prompt
+  action:
+    model: balanced
+    maxAgents: 3
+    # prompt: .loreli/action.md   # optional custom prompt per role
+  reviewer:
+    model: balanced
+    maxAgents: 2
+    trace:
+      enabled: true
+      maxOutputChars: 4000
+  risk:
+    model: fast
+    maxAgents: 3
+    skip: false
+    trace:
+      enabled: true
+      maxOutputChars: 2000
+  planner:
+    model: powerful
+    maxAgents: 1
+    trace:
+      enabled: true
+      maxOutputChars: 4000
 ```
 
 `pr.validation.command` and `pr.selfReview.enabled` harden PR creation quality gates and are enabled by default:
@@ -403,7 +439,7 @@ See [packages/config/README.md](packages/config/README.md#configurable-base-bran
 
 ## Custom Prompt Extensions
 
-Projects can inject custom instructions into agent prompts by setting `prompts.{role}` in `loreli.yml`. Each key maps to a role (`action`, `reviewer`, `planner`, `risk`) and the value is a file path relative to the repository root. Loreli reads the file from the target repo (via the GitHub API) once per session and prepends its content to the rendered prompt — after the built-in autonomous preamble, before the role-specific template.
+Projects can inject custom instructions into agent prompts by setting `workflows.{role}.prompt` in `loreli.yml`. Each role (`action`, `reviewer`, `planner`, `risk`) can have a `prompt` key whose value is a file path relative to the repository root. Loreli reads the file from the target repo (via the GitHub API) once per session and prepends its content to the rendered prompt — after the built-in autonomous preamble, before the role-specific template.
 
 This mechanism addresses a common need: different repositories have different coding standards, architectural constraints, or domain knowledge that agents should follow. Per-role prompts let you tailor instructions to each role — action agents might need coding standards and API constraints, while reviewers need quality gates and review checklists.
 
@@ -434,24 +470,28 @@ Create prompt files in your repository — for example under `.loreli/`:
 </review-standards>
 ```
 
-Then reference them in `loreli.yml`:
+Then reference them in `loreli.yml` under `workflows`:
 
 ```yaml
-prompts:
-  action: .loreli/action.md
-  reviewer: .loreli/review.md
-  planner: .loreli/planner.md
-  risk: .loreli/risk.md        # optional — omit roles that don't need custom prompts
+workflows:
+  action:
+    prompt: .loreli/action.md
+  reviewer:
+    prompt: .loreli/review.md
+  planner:
+    prompt: .loreli/planner.md
+  risk:
+    prompt: .loreli/risk.md    # optional — omit roles that don't need custom prompts
 ```
 
 After the next `start()`, each agent role receives only its own custom instructions at the top of its prompt, before the role-specific template content. Roles without a configured prompt file are unaffected.
 
 ### How It Works
 
-The custom prompt flows through the same rendering pipeline as the autonomous preamble — `Workflow.render()` and `Workflow.renderFrom()` resolve `prompts.{role}` from config and prepend the content automatically. The injection order is:
+The custom prompt flows through the same rendering pipeline as the autonomous preamble — `Workflow.render()` and `Workflow.renderFrom()` resolve `workflows.{role}.prompt` from config and prepend the content automatically. The injection order is:
 
 1. **Autonomous preamble** — built-in headless operation directives (always present)
-2. **Custom prompt** — role-specific project instructions from `prompts.{role}` (when configured)
+2. **Custom prompt** — role-specific project instructions from `workflows.{role}.prompt` (when configured)
 3. **Role template** — the action/planner/reviewer prompt
 
 The file is read once from GitHub when the first prompt for that role is rendered and cached for the remainder of the session. If the file is missing or unreadable, rendering continues normally without it — agents are never blocked by a missing custom prompt.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loreli",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "Agentic team orchestration via GitHub — an MCP server that coordinates AI agents using issues, PRs, and reviews as the communication layer.",
   "exports": {
@@ -21,23 +21,13 @@
     "./marker": "./packages/marker/src/index.js",
     "./knowledge": "./packages/knowledge/src/index.js",
     "./context": "./packages/context/src/index.js",
+    "./classify": "./packages/classify/src/index.js",
     "./test-utils": "./packages/test-utils/src/index.js",
     "./mcp": "./packages/mcp/src/index.js"
   },
   "bin": {
     "loreli": "./bin/loreli.js"
   },
-  "scripts": {
-    "pretest": "node --env-file-if-exists=.env scripts/clean-test-repo.js",
-    "test": "node --env-file-if-exists=.env --test --test-concurrency=1 --experimental-test-coverage --test-coverage-branches=90 --test-coverage-functions=90 --test-coverage-lines=90 packages/*/test/*.test.js",
-    "test:ci": "LORELI_TEST_MODE=unit node --env-file-if-exists=.env --test --test-concurrency=1 packages/*/test/*.test.js",
-    "e2e": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/single/*.test.js e2e/multi/*.test.js",
-    "e2e:single": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/single/*.test.js",
-    "e2e:multi": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/multi/*.test.js",
-    "lint:secrets": "npx secretlint \"**/*\"",
-    "prepublishOnly": "pnpm lint:secrets",
-    "prepare": "node node_modules/pre-commit/install.js && node node_modules/pre-push/install.js"
-  },
   "pre-commit": [
     "lint:secrets"
   ],
@@ -45,7 +35,7 @@
     "lint:secrets"
   ],
   "dependencies": {
-    "@mcp-layer/cli": "^1.0.0",
+    "@mcp-layer/cli": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@octokit/rest": "^21.1.1",
     "@secretlint/secretlint-rule-preset-recommend": "^11.3.1",
@@ -77,7 +67,20 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "@changesets/cli": "^2.29.2",
     "pre-commit": "^1.2.2",
     "pre-push": "^0.1.4"
+  },
+  "scripts": {
+    "pretest": "node --env-file-if-exists=.env scripts/clean-test-repo.js",
+    "test": "node --env-file-if-exists=.env --test --test-concurrency=1 --experimental-test-coverage --test-coverage-branches=90 --test-coverage-functions=90 --test-coverage-lines=90 packages/*/test/*.test.js",
+    "test:ci": "LORELI_TEST_MODE=unit node --env-file-if-exists=.env --test --test-concurrency=1 packages/*/test/*.test.js",
+    "e2e": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/single/*.test.js e2e/multi/*.test.js",
+    "e2e:single": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/single/*.test.js",
+    "e2e:multi": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/multi/*.test.js",
+    "lint:secrets": "npx secretlint \"**/*\"",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:publish": "changeset publish"
   }
-}
+}

package/packages/action/prompts/action.md

@@ -0,0 +1,172 @@
+You are **{{name}}**, an action agent for the repository **{{{repo}}}**.
+
+<instructions>
+
+## Objective
+
+Claim open issues, implement the work, and create pull requests for review.
+
+### Claiming
+
+1. Find an unclaimed issue (no claim comment yet).
+2. Use the **comment** tool with `claim: true` to claim it.
+3. First-comment-wins — if someone claimed before you, move to the next issue.
+
+### Tools
+
+Use these Loreli MCP tools for all GitHub operations:
+
+- **pr** (action: `create`) — Open a pull request. Provide `title`, `body`, `head` (branch name), and `reasoning`. Your claimed issue is auto-referenced with "Closes #N". Agent stamp and labels are applied automatically.
+- **read** — Read any issue, PR, or discussion by number. Use this to look up acceptance criteria, understand linked issues, or review discussion context.
+- **comment** — Post a comment on your current work item. Use for progress updates or responding to reviewer feedback. Set `claim: true` to claim an issue.
+- **comment** (abandon: `true`) — Abandon the current issue as fundamentally impossible. Requires `reason`. Posts an abandon comment, labels the issue, closes it, and notifies human reviewers. Use ONLY when the issue describes work that cannot be done (e.g., "remove a directory that doesn't exist", "implement an API that conflicts with existing architecture"). Do NOT use for "this is hard" or "I need more time."
+- **refactor** — Flag a bug, code smell, or tech debt you encounter during implementation. Call **immediately on discovery** — do not wait until your PR is complete. Provide `kind`, `title`, `description` with stable identifiers, and optionally `files` (with `#R<start>-R<end>` range hints) and `impact`. The tool deduplicates and creates a planning discussion automatically.
+- **plan** (action: `escalate`) — Flag a process, architecture, or scope coordination concern as a new discussion. Provide `title` and `body`. Use this for concerns about the overall approach, not for code-level issues (use **refactor** for those).
+
+### Working
+
+Your workspace is already a checkout of **{{{repo}}}** with git fully configured.
+
+**Trust the workspace git setup:**
+- Do NOT clone the repository again, run `git init`, create alternate `.git` directories, or modify git internals.
+- If `ls -la` shows `@` flags on files, that is a macOS extended attribute (harmless). Verify with `git status`, not `ls`.
+- Git credentials and push URLs are pre-configured.
+
+You are on branch `{{{branch}}}`. Use this branch for all your work — do not create other branches.
+
+### Policy Preflight
+
+Before implementation, check whether `AGENTS.md` exists at the repository root. If present, read it and treat it as the authoritative repository policy for coding style, testing, docs, and validation expectations.
+
+### Implementation
+
+1. Read the issue's acceptance criteria and testing strategy.
+2. Write tests first, following the TDD approach described in the issue.
+3. Implement the code to make the tests pass.
+4. Verify your work (see Verification below).
+5. Use the **pr** tool (action: `create`) with `head` as `{{{branch}}}` only after verification is complete. The tool automatically stages, commits, and pushes your changes before creating the PR.
+
+### Verification
+
+Before creating a PR, verify your work passes quality checks. Unverified PRs waste the reviewer's session and delay the entire pipeline:
+
+1. Run the test suite and confirm all tests pass.
+2. If the repo has a linter or type checker, run it and fix any errors you introduced.
+3. Review your own diff — check for debug statements, commented-out code, or unintended changes.
+
+Only create the PR after verification succeeds.
+Your PR `reasoning` must explicitly list the verification commands you ran and confirm they passed.
+
+### Completion Gate
+
+You are **not done until** exactly one terminal outcome is reached:
+
+1. **PR path**: the **pr** tool with `action: create` succeeds for `head: {{{branch}}}` and returns a PR number.
+2. **Abandon path**: the **comment** tool with `abandon: true` is posted with a concrete reason.
+
+Do **not** end your turn with only a local summary, passing tests, or `git status`.
+Do **not stop** at the Codex idle prompt before one terminal outcome above is complete.
+If PR creation fails, diagnose and retry with corrected arguments instead of stopping.
+
+### Documentation
+
+When your changes touch these areas, documentation is mandatory:
+
+- **Architectural changes** (new packages, new modules, changed data flow): create or update architecture diagrams in `docs/` and explain the decision rationale.
+- **Error handling** (new error classes, try/catch blocks, error responses): document each error with resolution steps that anyone can follow regardless of skill level.
+- **New APIs** (exported functions, REST endpoints, tool definitions): document parameters, return shapes, and error behavior in JSDoc and the package README.
+
+### PR Reasoning
+
+When creating a PR, include a `reasoning` parameter summarizing your approach. This is included in the PR body as a collapsible trace for human review.
+
+### Rules
+
+- Stay within the scope defined in the issue's acceptance criteria. Scope creep in a multi-agent system cascades — your unplanned changes can conflict with parallel agents working on adjacent issues.
+- Do not add features or fixes beyond the issue scope. When you encounter bugs, code smells, or tech debt during your work, use **refactor** immediately to flag them — then continue your assigned task. For process, architecture, or scope coordination concerns, use **plan** (action: `escalate`) instead.
+- Commit with descriptive messages following the repo's conventions.
+- When review comments arrive, address them promptly and use **comment** to request re-review.
+- If approaching context limits, commit and push your progress, then post a comment documenting remaining work before stopping.
+
+</instructions>
+
+<output_format>
+
+Structure your PR `reasoning` parameter with:
+
+- **Approach**: What strategy you chose and why.
+- **Key decisions**: Any trade-offs or alternatives you considered.
+- **Verification**: What you tested and how you confirmed correctness.
+
+</output_format>
+
+<examples>
+
+<example title="Well-formed PR reasoning">
+**Approach**: Implemented exponential backoff using a recursive retry wrapper around the existing `fetch` call. Chose composition over modifying `fetch` directly to keep the retry logic testable in isolation.
+
+**Key decisions**: Used jitter via `Math.random() * baseDelay * 0.5` to avoid thundering herd. Capped at 3 retries based on the acceptance criteria. Classified 429 and 5xx as retryable; all other 4xx propagate immediately.
+
+**Verification**: All 5 test scenarios from the issue pass. Ran `pnpm test` — 47/47 passing. Ran `pnpm lint` — no new warnings. Reviewed diff for debug artifacts — clean.
+</example>
+
+</examples>
+
+{{#issue}}
+<context>
+
+## Assigned Issue
+
+You have been assigned the following issue. It is already claimed on your behalf — proceed directly to implementation.
+
+{{{issue}}}
+
+</context>
+{{/issue}}
+
+{{#reviewFeedback}}
+<context>
+
+## Review Feedback
+
+The reviewer **{{reviewer}}** ({{reviewerProvider}}) has requested changes on **PR #{{number}}**:
+
+{{#comments}}
+- {{body}}
+{{/comments}}
+
+Address each item:
+
+1. Make the requested changes.
+2. Run verification again to confirm nothing is broken.
+3. Push your commits.
+4. Use the **comment** tool to post: "@{{reviewer}} Changes addressed, ready for re-review."
+
+</context>
+{{/reviewFeedback}}
+
+{{#hitl}}
+<context>
+
+## Human In The Loop Feedback
+
+A human reviewer has provided feedback on your PR. Their comments are below:
+
+{{#feedback}}
+- **@{{author}}**: {{body}}
+{{/feedback}}
+
+Address each comment carefully:
+
+1. Make the requested changes.
+2. Run verification again to confirm nothing is broken.
+3. Push your commits.
+4. Use the **comment** tool to post: "@{{reviewer}} Changes addressed, ready for re-review."
+5. Do **not** merge — the human reviewer will merge when satisfied.
+
+</context>
+{{/hitl}}
+
+<agent_metadata>
+Faction: {{faction}} | Provider: {{provider}}
+</agent_metadata>

package/packages/action/src/index.js

@@ -313,7 +313,8 @@ export class ActionWorkflow extends Workflow {
         try {
           await reset(cwd, agent.identity.name, issue.number, base, options);
         } catch (err) {
-          log.warn(`dispatch: workspace reset failed for ${agent.identity.name}: ${err.message}`);
+          log.warn(`dispatch: workspace reset failed for ${agent.identity.name}: ${err.message} — skipping issue`);
+          continue;
         }
 
         // Dormant agents need respawning; spawned agents are already alive.
@@ -391,7 +392,8 @@ export class ActionWorkflow extends Workflow {
     let agent = null;
     for (const c of allComments) {
       if (has(c.body, 'claim')) {
-        agent = parse(c.body, 'claim')?.agent ?? c.author;
+        const parsed = parse(c.body, 'claim')?.agent;
+        if (parsed) agent = parsed;
       }
       if (has(c.body, 'release') || has(c.body, 'restart')) {
         agent = null;
@@ -476,6 +478,23 @@ export class ActionWorkflow extends Workflow {
    * @throws {Error} When no action agents are available.
    */
   async work(repo) {
+    if (this._dispatching) return [];
+    this._dispatching = true;
+
+    try {
+      return await this._work(repo);
+    } finally {
+      this._dispatching = false;
+    }
+  }
+
+  /**
+   * Internal work implementation, guarded by _dispatching in work().
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{issue: number, agent: string, reviewer: string|null}>>}
+   */
+  async _work(repo) {
     log.info(`work cycle: ${repo}`);
     const actions = this.agents().filter(function active(a) {
       return a.state !== 'dormant' && this._stale(a.identity?.name) !== true;
@@ -544,7 +563,8 @@ export class ActionWorkflow extends Workflow {
       try {
         await reset(cwd, agent.identity.name, issue.number, base, options);
       } catch (err) {
-        log.warn(`work: branch reset failed for ${agent.identity.name}: ${err.message}`);
+        log.warn(`work: branch reset failed for ${agent.identity.name}: ${err.message} — skipping issue`);
+        continue;
       }
 
       const issueBranch = `${agent.identity.name}/issue-${issue.number}`;
@@ -621,15 +641,23 @@ export class ActionWorkflow extends Workflow {
 
       agent = await this.enlist(provider, 'action', {
         theme: pick(cfg?.get?.('theme')),
-        model: cfg?.get?.('model'),
         config: cfg
       });
     }
 
-    // Build a prompt with the human feedback and dispatch
+    // Fetch PR details so the rework prompt includes branch context.
+    // Without this, the agent cannot identify which branch to work on.
+    let prDetails;
+    try {
+      prDetails = await this.hub.pull(repo, pr);
+    } catch (err) {
+      log.warn(`rework: failed to fetch PR #${pr}: ${err.message}`);
+    }
+
     await this.dispatch(agent, {
       name: agent.identity.name,
       repo,
+      branch: prDetails?.head ?? `${agent.identity.name}/work`,
       faction: agent.identity.faction,
       provider: agent.identity.provider,
       model: agent.identity.model,