@neriros/ralphy 2.13.7 → 2.13.8

package/README.md

@@ -82,12 +82,15 @@ ralph status --name fix-auth  # Detailed view of one task
 ```bash
 export LINEAR_API_KEY=lin_api_xxx
 ralph agent --linear-team ENG --linear-assignee me --concurrency 3 --poll-interval 60
+
+# Limit the number of tickets processed in this run
+ralph agent --max-tickets 5 --linear-team ENG --linear-assignee me
 ```
 
 What it does on each tick:
 
 1. Polls Linear for open issues matching the filter (team / assignee / status / labels)
-2. Dedupes against `.ralph/agent-state.json` (already processed) plus any in-flight workers
+2. Dedupes against in-flight workers and any already-active issues
 3. For each new issue: fetches existing comments, scaffolds `openspec/changes/<id-slug>/{proposal.md,tasks.md,design.md}` (with the comments embedded so the worker sees prior discussion), then spawns `ralph task --name <id-slug>` up to the concurrency cap
 4. Posts a "🤖 started" comment on the Linear issue and applies the `setInProgress` indicator (if configured)
 5. On worker exit, posts a success/failure comment and applies the `setDone` indicator on success or `setError` on failure (if configured)
@@ -196,11 +199,41 @@ Failed workers (non-zero exit) are not marked processed, so they'll be retried o
 | `--linear-assignee <id>`  | Filter by assignee (user id, email, or `me`)                                  |
 | `--poll-interval <s>`     | Seconds between Linear polls (default: 60)                                    |
 | `--concurrency <n>`       | Max concurrent task loops (default: 1)                                        |
+| `--max-tickets <n>`       | Stop picking up new issues after N have been started this run (0 = unlimited) |
 | `--worktree`              | Run each task in its own git worktree                                         |
 | `--indicator <k>:<t>:<v>` | Override a `linear.indicators` entry; repeatable (e.g. `setDone:status:Done`) |
 | `--create-pr`             | Push worker branch + open a GitHub PR on success (needs `--worktree`)         |
 | `--fix-ci`                | After PR opens, re-run task on CI failures until green (needs `--create-pr`)  |
 
+#### `--max-tickets`
+
+Use `--max-tickets N` to cap how many issues ralph picks up in a single agent run. Once N issues have been started (across fresh, resume, and conflict-fix modes), the coordinator stops enqueuing new work. In-flight workers continue to completion. The limit resets each time you restart `ralph agent`.
+
+```bash
+# Process at most 3 issues this session, then idle
+ralph agent --max-tickets 3 --linear-team ENG
+```
+
+When the limit is reached, ralph logs a yellow notice and the dashboard header shows `│ tickets ≤N`. Polling continues (to handle conflict re-fixes on already-started issues), but no new issues are queued.
+
+#### Dashboard
+
+The `ralph agent` terminal dashboard shows a full-terminal layout with three always-visible panels:
+
+- **RALPH AGENT** (blue box): engine/model, concurrency, poll interval, active limits (`iter ≤N`, `cost ≤$N`, `tickets ≤N`), feature flags (● PR ● fixCI ● worktree), and the Linear filter on the second line
+- **POLL STATUS + WORKERS** (side-by-side): last-poll counts and next-poll countdown; active/queued worker totals with colored counts
+- **TASKS tab bar** (when multiple workers run): numbered worker tabs with priority glyph and phase — Tab/← → to switch, 1-9 to jump
+
+Each worker card shows:
+
+- Priority badge (`▲ URGENT` / `↑ HIGH` / `· MED` / `↓ LOW`) + issue identifier + title + mode badge (`[NEW]` / `[RESUME]` / `[FIX]`)
+- `↗ LINEAR  ISSUE-ID` and `↗ PR  #N` (short labels, not full URLs)
+- `▶ TASK` — first unchecked task from `tasks.md`, updated every second
+- `PHASE` with color (cyan = working, yellow = git ops, blue = CI, green = done, red = gave-up) + time in phase
+- `⏵ CMD` when a shell command is in flight (shows the command and how long it's been running)
+- `LOG` — path to the worker's log file for `tail -f`
+- `─ OUTPUT ─` section with live stdout/stderr (scales to fill remaining terminal height for the focused worker)
+
 ## OpenSpec Flow
 
 There are no phases. One loop, one prompt, one `tasks.md` checklist.

package/dist/cli/index.js

@@ -56409,7 +56409,7 @@ function log(msg) {
 // package.json
 var package_default = {
   name: "@neriros/ralphy",
-  version: "2.13.7",
+  version: "2.13.8",
   description: "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   keywords: [
     "agent",
@@ -56559,6 +56559,7 @@ var HELP_TEXT = [
   "                          Types: label, status",
   "  --create-pr             Push the worker branch and open a GitHub PR on success (needs --worktree)",
   "  --fix-ci                After opening the PR, re-run on CI failures until green (needs --create-pr)",
+  "  --max-tickets <n>       Stop picking up new issues after N have been started (0 = unlimited)",
   "",
   "  --help, -h              Show this help message",
   "",
@@ -56643,7 +56644,8 @@ async function parseArgs(argv) {
     worktree: false,
     indicators: {},
     createPr: false,
-    fixCi: false
+    fixCi: false,
+    maxTickets: 0
   };
   let expectModel = false;
   let expectModelFlag = false;
@@ -56659,6 +56661,7 @@ async function parseArgs(argv) {
   let expectLinearAssignee = false;
   let expectPollInterval = false;
   let expectConcurrency = false;
+  let expectMaxTickets = false;
   let expectIndicator = false;
   for (const arg of argv) {
     if (expectModel) {
@@ -56737,6 +56740,11 @@ async function parseArgs(argv) {
       expectConcurrency = false;
       continue;
     }
+    if (expectMaxTickets) {
+      result2.maxTickets = parseInt(arg, 10);
+      expectMaxTickets = false;
+      continue;
+    }
     if (expectIndicator) {
       const { key, marker } = parseIndicatorArg(arg);
       mergeIndicator(result2.indicators, key, marker);
@@ -56807,6 +56815,9 @@ async function parseArgs(argv) {
       case "--concurrency":
         expectConcurrency = true;
         break;
+      case "--max-tickets":
+        expectMaxTickets = true;
+        break;
       case "--worktree":
         result2.worktree = true;
         break;
@@ -70562,6 +70573,7 @@ class AgentCoordinator {
   queue = [];
   stopped = false;
   conflictNotified = new Set;
+  ticketsStarted = 0;
   constructor(deps, opts) {
     this.deps = deps;
     this.opts = opts;
@@ -70575,6 +70587,9 @@ class AgentCoordinator {
   get activeWorkers() {
     return this.workers;
   }
+  get ticketsStartedCount() {
+    return this.ticketsStarted;
+  }
   async init() {}
   async pollOnce() {
     if (this.stopped)
@@ -70596,8 +70611,17 @@ class AgentCoordinator {
     const queuedIds = new Set(this.queue.map((q) => q.issue.id));
     const activeIds = new Set(this.workers.map((w) => w.issueId));
     const eligible = (id) => !queuedIds.has(id) && !activeIds.has(id) && !this.pendingIds.has(id);
+    const maxT = this.opts.maxTickets ?? 0;
+    const atTicketLimit = () => {
+      if (maxT === 0)
+        return false;
+      const inFlight = this.ticketsStarted + this.queue.length + this.workers.length + this.pendingIds.size;
+      return inFlight >= maxT;
+    };
     let added = 0;
     for (const issue of inProgress) {
+      if (atTicketLimit())
+        break;
       if (!eligible(issue.id))
         continue;
       if (!this.dependenciesResolved(issue))
@@ -70607,6 +70631,8 @@ class AgentCoordinator {
       added += 1;
     }
     for (const issue of conflicted) {
+      if (atTicketLimit())
+        break;
       if (!eligible(issue.id))
         continue;
       this.queue.push({ issue, mode: "conflict-fix" });
@@ -70614,6 +70640,8 @@ class AgentCoordinator {
       added += 1;
     }
     for (const issue of todo) {
+      if (atTicketLimit())
+        break;
       if (!eligible(issue.id))
         continue;
       if (!this.dependenciesResolved(issue))
@@ -70808,6 +70836,11 @@ class AgentCoordinator {
     };
     this.workers.push(worker);
     this.pendingIds.delete(issue.id);
+    this.ticketsStarted += 1;
+    const maxT = this.opts.maxTickets ?? 0;
+    if (maxT > 0 && this.ticketsStarted >= maxT) {
+      this.deps.onLog(`  ticket limit reached (${maxT}) \u2014 no new issues will be picked up`, "yellow");
+    }
     capture("agent_worker_spawned", {
       spawn_mode: mode,
       issue_identifier: issue.identifier
@@ -72054,7 +72087,8 @@ PR: ${prUrl}` : ""
     ...indicators.setConflicted !== undefined ? { setConflicted: indicators.setConflicted } : {},
     ...indicators.clearConflicted !== undefined ? { clearConflicted: indicators.clearConflicted } : {},
     postComments: cfg.linear.postComments,
-    commentEveryIterations: cfg.linear.updateEveryIterations
+    commentEveryIterations: cfg.linear.updateEveryIterations,
+    ...args.maxTickets > 0 ? { maxTickets: args.maxTickets } : {}
   });
   const filterDesc = describeIndicators(indicators, team, assignee);
   return {
@@ -72496,6 +72530,13 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
                           cfg.maxCostUsdPerTask
                         ]
                       }, undefined, true, undefined, this),
+                      args.maxTickets > 0 && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
+                        color: "yellow",
+                        children: [
+                          " \u2502 tickets \u2264",
+                          args.maxTickets
+                        ]
+                      }, undefined, true, undefined, this),
                       cfg.createPrOnSuccess && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                         color: "green",
                         children: " \u25CF PR"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neriros/ralphy",
-  "version": "2.13.7",
+  "version": "2.13.8",
   "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   "keywords": [
     "agent",