@neriros/ralphy 2.13.6 → 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.6",
+  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 {
@@ -72109,6 +72143,26 @@ function fmtElapsed(ms) {
 function trunc(s, max2) {
   return s.length > max2 ? s.slice(0, max2 - 1) + "\u2026" : s;
 }
+function prLabel(prUrl) {
+  const m = prUrl.match(/\/pull\/(\d+)/);
+  return m ? `#${m[1]}` : "PR";
+}
+var ANSI_STRIP_RE = /\x1b(?:\[[0-9;]*[A-Za-z]|\][^\x07\x1b]*(?:\x07|\x1b\\)|.)/g;
+var BOX_ONLY_RE = /^[\s\u2500\u2502\u256D\u256E\u2570\u256F\u254C\u2504\u2501\u2503]+$/;
+var STATUS_BAR_LINE_RE = /^[\u280B\u2819\u2839\u2838\u283C\u2834\u2826\u2827\u2807\u280F\u2713\u2717]\s+iter\s+\d+/;
+var ITER_HEADER_LINE_RE = /^\u2500\u2500/;
+function cleanOutputLine(raw) {
+  const clean = raw.replace(ANSI_STRIP_RE, "").trim();
+  if (!clean)
+    return null;
+  if (BOX_ONLY_RE.test(clean))
+    return null;
+  if (STATUS_BAR_LINE_RE.test(clean))
+    return null;
+  if (ITER_HEADER_LINE_RE.test(clean))
+    return null;
+  return clean;
+}
 function priorityBadge(p) {
   switch (p) {
     case 1:
@@ -72194,14 +72248,6 @@ function displayTailLines(activeCount) {
     return 8;
   return 5;
 }
-function parseFilterParts(filterDesc) {
-  return filterDesc.split(", ").map((part) => {
-    const eq = part.indexOf("=");
-    if (eq < 0)
-      return { key: part, val: "" };
-    return { key: part.slice(0, eq), val: part.slice(eq + 1) };
-  });
-}
 function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
   const { exit } = use_app_default();
   const { stdout } = use_stdout_default();
@@ -72273,7 +72319,10 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
           const m = workerMetaRef.current.get(changeName);
           if (!m)
             return;
-          m.tail.push(line);
+          const clean = cleanOutputLine(line);
+          if (!clean)
+            return;
+          m.tail.push(clean);
           if (m.tail.length > TAIL_BUFFER_SIZE)
             m.tail.splice(0, m.tail.length - TAIL_BUFFER_SIZE);
         },
@@ -72379,7 +72428,6 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
   const activeCount = coord?.activeCount ?? 0;
   const termWidth = (stdout?.columns ?? 100) - 2;
   const termHeight = stdout?.rows ?? 40;
-  const filterParts = pollStatus.filterDesc ? parseFilterParts(pollStatus.filterDesc) : [];
   const safeFocusedIdx = activeCount > 0 ? Math.min(focusedIdx, activeCount - 1) : 0;
   use_input_default((input, key) => {
     if (activeCount === 0)
@@ -72421,14 +72469,16 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
             paddingX: 1,
             width: termWidth,
             children: [
-              /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Box_default, {
-                gap: 2,
+              /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                 children: [
                   /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                     bold: true,
                     color: "cyan",
-                    children: "\u25C8 RALPH AGENT"
-                  }, undefined, false, undefined, this),
+                    children: [
+                      "\u25C8 RALPH AGENT",
+                      " "
+                    ]
+                  }, undefined, true, undefined, this),
                   /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                     dimColor: true,
                     children: [
@@ -72436,15 +72486,11 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
                       VERSION
                     ]
                   }, undefined, true, undefined, this),
-                  cfg && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(jsx_dev_runtime9.Fragment, {
+                  cfg && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                     children: [
                       /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                         dimColor: true,
-                        children: "\u2502"
-                      }, undefined, false, undefined, this),
-                      /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                        dimColor: true,
-                        children: "ENGINE"
+                        children: " \u2502 "
                       }, undefined, false, undefined, this),
                       /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                         color: "cyan",
@@ -72457,133 +72503,61 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
                       }, undefined, true, undefined, this),
                       /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                         dimColor: true,
-                        children: "\u2502"
-                      }, undefined, false, undefined, this),
-                      /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                        dimColor: true,
-                        children: "CONCURRENCY"
-                      }, undefined, false, undefined, this),
-                      /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                        color: "white",
-                        bold: true,
-                        children: cfg.concurrency
-                      }, undefined, false, undefined, this),
-                      /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                        dimColor: true,
-                        children: "\u2502"
-                      }, undefined, false, undefined, this),
+                        children: [
+                          " \u2502 \xD7",
+                          cfg.concurrency
+                        ]
+                      }, undefined, true, undefined, this),
                       /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                         dimColor: true,
-                        children: "POLL"
-                      }, undefined, false, undefined, this),
-                      /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                        color: "white",
                         children: [
+                          " \u2502 poll ",
                           cfg.pollIntervalSeconds,
                           "s"
                         ]
                       }, undefined, true, undefined, this),
-                      cfg.maxIterationsPerTask > 0 && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(jsx_dev_runtime9.Fragment, {
+                      cfg.maxIterationsPerTask > 0 && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
+                        color: "yellow",
                         children: [
-                          /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                            dimColor: true,
-                            children: "\u2502"
-                          }, undefined, false, undefined, this),
-                          /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                            dimColor: true,
-                            children: "MAX ITER"
-                          }, undefined, false, undefined, this),
-                          /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                            color: "yellow",
-                            children: cfg.maxIterationsPerTask
-                          }, undefined, false, undefined, this)
+                          " \u2502 iter \u2264",
+                          cfg.maxIterationsPerTask
                         ]
                       }, undefined, true, undefined, this),
-                      cfg.maxCostUsdPerTask > 0 && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(jsx_dev_runtime9.Fragment, {
+                      cfg.maxCostUsdPerTask > 0 && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
+                        color: "yellow",
                         children: [
-                          /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                            dimColor: true,
-                            children: "\u2502"
-                          }, undefined, false, undefined, this),
-                          /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                            dimColor: true,
-                            children: "MAX COST"
-                          }, undefined, false, undefined, this),
-                          /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                            color: "yellow",
-                            children: [
-                              "$",
-                              cfg.maxCostUsdPerTask
-                            ]
-                          }, undefined, true, undefined, this)
+                          " \u2502 cost \u2264$",
+                          cfg.maxCostUsdPerTask
                         ]
                       }, undefined, true, undefined, this),
-                      cfg.maxRuntimeMinutesPerTask > 0 && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(jsx_dev_runtime9.Fragment, {
+                      args.maxTickets > 0 && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
+                        color: "yellow",
                         children: [
-                          /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                            dimColor: true,
-                            children: "\u2502"
-                          }, undefined, false, undefined, this),
-                          /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                            dimColor: true,
-                            children: "MAX TIME"
-                          }, undefined, false, undefined, this),
-                          /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                            color: "yellow",
-                            children: [
-                              cfg.maxRuntimeMinutesPerTask,
-                              "m"
-                            ]
-                          }, undefined, true, undefined, this)
+                          " \u2502 tickets \u2264",
+                          args.maxTickets
                         ]
-                      }, undefined, true, undefined, this)
+                      }, undefined, true, undefined, this),
+                      cfg.createPrOnSuccess && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
+                        color: "green",
+                        children: " \u25CF PR"
+                      }, undefined, false, undefined, this),
+                      cfg.fixCiOnFailure && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
+                        color: "green",
+                        children: " \u25CF fixCI"
+                      }, undefined, false, undefined, this),
+                      cfg.useWorktree && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
+                        color: "green",
+                        children: " \u25CF worktree"
+                      }, undefined, false, undefined, this)
                     ]
                   }, undefined, true, undefined, this)
                 ]
               }, undefined, true, undefined, this),
-              cfg && (cfg.createPrOnSuccess || cfg.fixCiOnFailure || cfg.useWorktree) && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Box_default, {
-                gap: 2,
-                marginTop: 0,
-                children: [
-                  /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                    dimColor: true,
-                    children: "FEATURES"
-                  }, undefined, false, undefined, this),
-                  cfg.createPrOnSuccess && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                    color: "green",
-                    children: "\u25CF create-pr"
-                  }, undefined, false, undefined, this),
-                  cfg.fixCiOnFailure && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                    color: "green",
-                    children: "\u25CF fix-ci"
-                  }, undefined, false, undefined, this),
-                  cfg.useWorktree && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                    color: "green",
-                    children: "\u25CF worktree"
-                  }, undefined, false, undefined, this)
-                ]
-              }, undefined, true, undefined, this),
-              filterParts.length > 0 && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Box_default, {
-                gap: 3,
-                marginTop: 0,
+              pollStatus.filterDesc && /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
+                dimColor: true,
                 children: [
-                  /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                    dimColor: true,
-                    children: "LINEAR"
-                  }, undefined, false, undefined, this),
-                  filterParts.map(({ key, val }) => /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Box_default, {
-                    gap: 1,
-                    children: [
-                      /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                        dimColor: true,
-                        children: key
-                      }, undefined, false, undefined, this),
-                      /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
-                        color: "magenta",
-                        children: val
-                      }, undefined, false, undefined, this)
-                    ]
-                  }, key, true, undefined, this))
+                  "Linear  ",
+                  trunc(pollStatus.filterDesc.replace(/, /g, "  \xB7  "), termWidth - 12)
                 ]
               }, undefined, true, undefined, this)
             ]
@@ -72959,7 +72933,7 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
                         }, undefined, false, undefined, this),
                         /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                           color: "blue",
-                          children: w.issue.url
+                          children: w.issueIdentifier
                         }, undefined, false, undefined, this)
                       ]
                     }, undefined, true, undefined, this),
@@ -72972,7 +72946,7 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
                         }, undefined, false, undefined, this),
                         /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(Text, {
                           color: "green",
-                          children: prUrl
+                          children: prLabel(prUrl)
                         }, undefined, false, undefined, this)
                       ]
                     }, undefined, true, undefined, this)

package/package.json

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