@neriros/ralphy 2.18.0 → 2.20.0

package/README.md

@@ -169,6 +169,10 @@ A default `ralphy.config.json` is written on first run with every defaulted sett
     "assignee": "me",
     "postComments": true,
     "updateEveryIterations": 10,
+    "mentionTrigger": true,
+    "mentionHandle": "@ralphy",
+    "codeReviewTrigger": true,
+    "codeReviewStaleHours": 24,
     "indicators": {
       "getTodo": { "filter": [{ "type": "status", "value": "Todo" }] },
       "getInProgress": { "filter": [{ "type": "status", "value": "In Progress" }] },
@@ -213,6 +217,10 @@ Linear is the source of truth for which issues Ralph has touched. Each `linear.i
 
 **Review follow-ups.** When a Linear issue is in a "done" state and a reviewer adds the `getReview` marker (typically a label like `ralph:review` after leaving comments), Ralph picks it up, applies `setInProgress`, removes the `clearReview` label so the same trigger doesn't re-fire, fetches the comment thread, filters out Ralph's own comments, and prepends those reviewer comments as a new task at the top of `tasks.md`. The worker addresses them in the same change branch and `setDone` is re-applied on success.
 
+**`@ralphy` mention trigger.** Set `linear.mentionTrigger: true` (default `false`) to scan done-issue comments on both Linear and their linked GitHub PR for `@ralphy` mentions (configurable via `linear.mentionHandle`). New mentions enqueue the issue as a review run with the mention text used verbatim as the prepended task. Idempotency: a mention is considered processed when its `createdAt` is older than the most recent Ralph `🔁 picked up` comment on the Linear issue, so the same comment never re-fires across polls. Requires the `gh` CLI authenticated for the GitHub side.
+
+**Code-review iteration.** Set `linear.codeReviewTrigger: true` (or pass `--code-review`) to watch open, unmerged, unapproved tracked PRs for unresolved review-thread comments. When any unresolved thread has activity newer than Ralph's last `🔁 picked up` ack, the issue is queued as a review run whose prepended task is a digest of every unresolved thread plus instructions: fix-and-push for comments Ralph agrees with (resolve the thread after the commit lands), or reply on GitHub with reasoning for ones it disagrees with. The cycle repeats every poll until the PR is approved or merged. If the reviewer has been silent for more than `linear.codeReviewStaleHours` (default 24) while Ralph is the last actor, a one-shot `@`-mention ping comment is posted on the GitHub PR.
+
 Marker types are `"label"` or `"status"`. Combine markers under `apply` when one event needs to set multiple — e.g. `setDone` flipping a status _and_ adding a "shipped" label.
 
 #### Per-task git worktrees
@@ -256,17 +264,18 @@ Failed workers (non-zero exit) are not marked processed, so they'll be retried o
 
 ### Agent mode flags
 
-| Option                    | Description                                                                   |
-| ------------------------- | ----------------------------------------------------------------------------- |
-| `--linear-team <key>`     | Linear team key (e.g. `ENG`)                                                  |
-| `--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`)  |
+| Option                    | Description                                                                          |
+| ------------------------- | ------------------------------------------------------------------------------------ |
+| `--linear-team <key>`     | Linear team key (e.g. `ENG`)                                                         |
+| `--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`)         |
+| `--code-review`           | Watch open tracked PRs for unresolved review comments and prepend a code-review task |
 
 #### `--max-tickets`
 

package/dist/cli/index.js

@@ -35029,8 +35029,8 @@ import { readFileSync as readFileSync2 } from "fs";
 import { resolve } from "path";
 function getVersion() {
   try {
-    if ("2.18.0")
-      return "2.18.0";
+    if ("2.20.0")
+      return "2.20.0";
   } catch {}
   const dirsToTry = [];
   try {
@@ -35130,6 +35130,7 @@ async function parseArgs(argv) {
     indicators: {},
     createPr: false,
     fixCi: false,
+    codeReview: false,
     maxTickets: 0,
     projectRoot: undefined,
     jsonOutput: false
@@ -35323,6 +35324,9 @@ async function parseArgs(argv) {
       case "--fix-ci":
         result2.fixCi = true;
         break;
+      case "--code-review":
+        result2.codeReview = true;
+        break;
       case "--json-output":
         result2.jsonOutput = true;
         break;
@@ -35417,6 +35421,7 @@ var init_cli = __esm(() => {
     "                          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)",
+    "  --code-review           Watch open tracked PRs for unresolved review comments and prepend a code-review task",
     "  --max-tickets <n>       Stop picking up new issues after N have been started (0 = unlimited)",
     "  --json-output           Emit JSONL to stdout instead of the Ink dashboard (for scripting/CI)",
     "",
@@ -59621,6 +59626,18 @@ var MarkerSchema, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, Ralp
     // Post a progress update every N iterations. 0 disables. Requires postComments.
     "updateEveryIterations": 10,
 
+    // Watch done-issue Linear comments AND their linked GitHub PR comments
+    // for "@ralphy" mentions. New mentions enqueue the issue as a review run
+    // with the mention text as the prepended task.
+    "mentionTrigger": false,
+    // "mentionHandle": "@ralphy",
+
+    // Watch open tracked PRs for unresolved review-thread comments and
+    // prepend a code-review task. Pings the reviewer on the GitHub PR
+    // when stalled for more than codeReviewStaleHours.
+    "codeReviewTrigger": false,
+    "codeReviewStaleHours": 24,
+
     // Indicators map Ralph lifecycle events to Linear labels/statuses.
     // WARNING: activating indicators will query AND mutate your Linear workspace.
     // Uncomment each entry after confirming the label/status names match your workspace.
@@ -59730,8 +59747,20 @@ var init_config = __esm(() => {
       assignee: exports_external.string().optional(),
       postComments: exports_external.boolean().default(true),
       updateEveryIterations: exports_external.number().int().nonnegative().default(10),
+      mentionTrigger: exports_external.boolean().default(false),
+      mentionHandle: exports_external.string().default("@ralphy"),
+      codeReviewTrigger: exports_external.boolean().default(false),
+      codeReviewStaleHours: exports_external.number().nonnegative().default(24),
       indicators: IndicatorsSchema.default({})
-    }).strict().default({ postComments: true, updateEveryIterations: 10, indicators: {} })
+    }).strict().default({
+      postComments: true,
+      updateEveryIterations: 10,
+      mentionTrigger: false,
+      mentionHandle: "@ralphy",
+      codeReviewTrigger: false,
+      codeReviewStaleHours: 24,
+      indicators: {}
+    })
   }).default({
     concurrency: 1,
     pollIntervalSeconds: 60,
@@ -59740,7 +59769,15 @@ var init_config = __esm(() => {
     enableManualTest: false,
     engine: "claude",
     model: "opus",
-    linear: { postComments: true, updateEveryIterations: 10, indicators: {} }
+    linear: {
+      postComments: true,
+      updateEveryIterations: 10,
+      mentionTrigger: false,
+      mentionHandle: "@ralphy",
+      codeReviewTrigger: false,
+      codeReviewStaleHours: 24,
+      indicators: {}
+    }
   });
 });
 
@@ -60070,20 +60107,22 @@ class AgentCoordinator {
     let inProgress = [];
     let conflicted = [];
     let review = [];
+    let mentions = [];
     try {
-      [todo, inProgress, conflicted, review] = await Promise.all([
+      [todo, inProgress, conflicted, review, mentions] = await Promise.all([
         this.deps.fetchTodo(),
         this.deps.fetchInProgress(),
         this.deps.fetchConflicted(),
-        this.deps.fetchReview()
+        this.deps.fetchReview(),
+        this.deps.fetchMentions()
       ]);
     } catch (err) {
       this.deps.onLog(`! Linear poll failed: ${err.message}`, "red");
       capture("agent_linear_poll_failed", { error: err.message });
       return { found: 0, added: 0 };
     }
-    if (todo.length + inProgress.length + conflicted.length + review.length > 0) {
-      this.deps.onLog(`  poll: ${todo.length} todo, ${inProgress.length} in-progress, ${conflicted.length} conflicted, ${review.length} review`, "gray");
+    if (todo.length + inProgress.length + conflicted.length + review.length + mentions.length > 0) {
+      this.deps.onLog(`  poll: ${todo.length} todo, ${inProgress.length} in-progress, ${conflicted.length} conflicted, ${review.length} review, ${mentions.length} mention`, "gray");
     }
     const queuedIds = new Set(this.queue.map((q) => q.issue.id));
     const activeIds = new Set(this.workers.map((w) => w.issueId));
@@ -60128,6 +60167,16 @@ class AgentCoordinator {
       added += 1;
       this.deps.onLog(`  \u21B3 ${issue.identifier} queued (review)`, "gray");
     }
+    for (const { issue, trigger } of mentions) {
+      if (atTicketLimit())
+        break;
+      if (!eligible(issue.id))
+        continue;
+      this.queue.push({ issue, mode: "review", trigger });
+      queuedIds.add(issue.id);
+      added += 1;
+      this.deps.onLog(`  \u21B3 ${issue.identifier} queued (review via ${trigger.source} mention)`, "gray");
+    }
     for (const issue of todo) {
       if (atTicketLimit())
         break;
@@ -60158,7 +60207,7 @@ class AgentCoordinator {
     this.spawnNext();
     await this.scanDoneForConflicts();
     await this.reportProgress();
-    const found = todo.length + inProgress.length + conflicted.length + review.length;
+    const found = todo.length + inProgress.length + conflicted.length + review.length + mentions.length;
     return { found, added };
   }
   dependenciesResolved(issue) {
@@ -60267,13 +60316,13 @@ class AgentCoordinator {
     while (this.workers.length + this.pendingIds.size < this.opts.concurrency && this.queue.length > 0) {
       const next = this.queue.shift();
       this.pendingIds.add(next.issue.id);
-      this.launchWorker(next.issue, next.mode);
+      this.launchWorker(next.issue, next.mode, next.trigger);
     }
   }
-  async launchWorker(issue, mode) {
+  async launchWorker(issue, mode, trigger) {
     let prep;
     try {
-      prep = await this.deps.prepare(issue, mode);
+      prep = await this.deps.prepare(issue, mode, trigger);
     } catch (err) {
       this.pendingIds.delete(issue.id);
       this.deps.onLog(`! prepare(${mode}) failed for ${issue.identifier}: ${err.message}`, "red");
@@ -60316,8 +60365,9 @@ class AgentCoordinator {
       }
     }
     if (mode === "review" && this.opts.postComments !== false) {
+      const sourceTag = trigger ? trigger.source === "github" ? " (GitHub @mention)" : trigger.source === "github-review" ? " (GitHub code review)" : " (Linear @mention)" : "";
       try {
-        await this.deps.postComment(issue, `\uD83D\uDD01 Ralph picked up new review comments. Tracking change: \`${prep.changeName}\``);
+        await this.deps.postComment(issue, `\uD83D\uDD01 Ralph picked up new review comments${sourceTag}. Tracking change: \`${prep.changeName}\``);
       } catch (err) {
         this.deps.onLog(`! Linear review comment failed for ${issue.identifier}: ${err.message}`, "yellow");
       }
@@ -61108,6 +61158,45 @@ ${c.body.trim()}`;
   ].join(`
 `);
 }
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildMentionTaskBody(trigger, issueUrl) {
+  if (trigger.source === "github-review") {
+    return [
+      `Open code-review on ${trigger.url ?? issueUrl} has unresolved comments:`,
+      "",
+      trigger.body.trim(),
+      "",
+      "For every comment above, decide:",
+      "- If you agree, fix the code, commit, and push. The push will surface",
+      "  the new commit on the PR; the worker should then resolve the thread",
+      "  via `gh api graphql` (`resolveReviewThread`) \u2014 see GitHub docs.",
+      "- If you disagree, post a polite reply on the thread explaining your",
+      "  reasoning via `gh api repos/{owner}/{repo}/pulls/{num}/comments/{id}/replies`,",
+      "  and leave the thread unresolved.",
+      "",
+      "When this round is done the loop exits; the agent will re-poll the",
+      "PR on the next cycle and pick up any new reviewer activity until the",
+      "PR is approved or merged."
+    ].join(`
+`);
+  }
+  const sourceLabel = trigger.source === "github" ? "GitHub PR" : "Linear issue";
+  const permalink = trigger.url ?? issueUrl;
+  const header = `${trigger.author ?? "unknown"} \u2014 ${trigger.createdAt} (${sourceLabel})`;
+  return [
+    `An @ralphy mention was left on ${sourceLabel} (${permalink}):`,
+    "",
+    `**${header}**`,
+    "",
+    trigger.body.trim(),
+    "",
+    "Treat this comment as the next concrete request. If it's ambiguous,",
+    "note your interpretation in proposal.md `## Steering` before acting."
+  ].join(`
+`);
+}
 function unionMarkers(...sets) {
   const out = [];
   const seen = new Set;
@@ -61268,6 +61357,7 @@ function buildAgentCoordinator(input) {
   const issueByChange = new Map;
   const prByChange = new Map;
   const prUnavailable = new Set;
+  const stalePingedAt = new Map;
   const useWorktree = args.worktree || cfg.useWorktree;
   const scriptRunner = input.runners?.runScript ?? (async (cmd, cwd2) => {
     const proc = Bun.spawn({
@@ -61318,7 +61408,7 @@ function buildAgentCoordinator(input) {
     }
     return { workerCwd, scaffoldTasksDir, scaffoldStatesDir, branch };
   }
-  async function prepare(issue, mode) {
+  async function prepare(issue, mode, trigger) {
     const { workerCwd, scaffoldTasksDir, scaffoldStatesDir, branch } = await setupWorktree(issue);
     let changeName;
     const isFresh = mode === "fresh";
@@ -61345,16 +61435,24 @@ function buildAgentCoordinator(input) {
     if (mode === "review") {
       const wtLayout = projectLayout(workerCwd);
       const tasksFile = join16(wtLayout.changeDir(changeName), "tasks.md");
-      let comments = [];
-      try {
-        comments = await fetchIssueComments(apiKey, issue.id);
-      } catch (err) {
-        onLog(`! Linear comment fetch failed for ${issue.identifier}: ${err.message}`, "yellow");
+      let body;
+      let heading;
+      if (trigger) {
+        heading = trigger.source === "github" ? "Address GitHub @ralphy mention" : "Address Linear @ralphy mention";
+        body = buildMentionTaskBody(trigger, issue.url);
+      } else {
+        heading = "Address reviewer comments";
+        let comments = [];
+        try {
+          comments = await fetchIssueComments(apiKey, issue.id);
+        } catch (err) {
+          onLog(`! Linear comment fetch failed for ${issue.identifier}: ${err.message}`, "yellow");
+        }
+        const reviewerComments = comments.filter((c) => !isRalphComment(c.body));
+        body = buildReviewTaskBody(reviewerComments, issue.url);
       }
-      const reviewerComments = comments.filter((c) => !isRalphComment(c.body));
-      const body = buildReviewTaskBody(reviewerComments, issue.url);
       try {
-        await prependFixTask(tasksFile, "Address reviewer comments", body);
+        await prependFixTask(tasksFile, heading, body);
       } catch (err) {
         onLog(`! could not prepend review task: ${err.message}`, "red");
       }
@@ -61630,11 +61728,288 @@ PR: ${prUrl}` : ""
       return [];
     return fetchOpenIssues(apiKey, { team, assignee, include, exclude });
   }
+  async function fetchMentions() {
+    const wantMention = cfg.linear.mentionTrigger;
+    const wantCodeReview = args.codeReview || cfg.linear.codeReviewTrigger;
+    if (!wantMention && !wantCodeReview)
+      return [];
+    const handle = cfg.linear.mentionHandle;
+    let candidates = [];
+    try {
+      candidates = await fetchDoneCandidates();
+    } catch (err) {
+      onLog(`! mention scan: fetchDoneCandidates failed: ${err.message}`, "yellow");
+      return [];
+    }
+    const out = [];
+    const queued = new Set;
+    for (const issue of candidates) {
+      let comments = [];
+      try {
+        comments = await fetchIssueComments(apiKey, issue.id);
+      } catch (err) {
+        onLog(`! mention scan: Linear comments failed for ${issue.identifier}: ${err.message}`, "yellow");
+        continue;
+      }
+      const lastRalphPickup = findLastRalphPickupISO(comments);
+      if (wantMention) {
+        for (const c of comments) {
+          if (isRalphComment(c.body))
+            continue;
+          if (!containsHandle(c.body, handle))
+            continue;
+          if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+            continue;
+          out.push({
+            issue,
+            trigger: {
+              source: "linear",
+              body: c.body,
+              createdAt: c.createdAt,
+              ...c.user?.name ? { author: c.user.name } : {},
+              url: issue.url
+            }
+          });
+          queued.add(issue.id);
+          break;
+        }
+        if (queued.has(issue.id))
+          continue;
+      }
+      const prUrl = await resolvePrUrlForIssue(issue);
+      if (!prUrl)
+        continue;
+      if (wantMention) {
+        const ghComments = await fetchPrIssueComments(prUrl);
+        for (const c of ghComments) {
+          if (!containsHandle(c.body, handle))
+            continue;
+          if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+            continue;
+          out.push({
+            issue,
+            trigger: {
+              source: "github",
+              body: c.body,
+              createdAt: c.createdAt,
+              ...c.author ? { author: c.author } : {},
+              url: c.url
+            }
+          });
+          queued.add(issue.id);
+          break;
+        }
+        if (queued.has(issue.id))
+          continue;
+      }
+      if (wantCodeReview) {
+        const trigger = await scanCodeReview(issue, prUrl, lastRalphPickup);
+        if (trigger) {
+          out.push({ issue, trigger });
+          queued.add(issue.id);
+        }
+      }
+    }
+    return out;
+  }
+  async function scanCodeReview(issue, prUrl, lastRalphPickup) {
+    const state = await fetchPrReviewState(prUrl);
+    if (!state || !state.isOpen || state.merged || state.approved)
+      return null;
+    const unresolved = state.threads.filter((t) => !t.isResolved && t.comments.length > 0);
+    if (unresolved.length === 0)
+      return null;
+    const newestReviewerActivity = unresolved.reduce((acc, t) => {
+      const last2 = t.comments[t.comments.length - 1].createdAt;
+      return last2 > acc ? last2 : acc;
+    }, "");
+    if (!lastRalphPickup || newestReviewerActivity > lastRalphPickup) {
+      const body = unresolved.map((t) => {
+        const head3 = t.path ? `_${t.path}${t.line ? `:${t.line}` : ""}_` : "_(general)_";
+        const lines = t.comments.map((c) => `> **${c.author ?? "reviewer"}** (${c.createdAt})
+>
+> ${c.body.trim().replace(/\n/g, `
+> `)}`);
+        return [head3, "", ...lines].join(`
+`);
+      }).join(`
+
+---
+
+`);
+      return {
+        source: "github-review",
+        body,
+        createdAt: newestReviewerActivity || new Date().toISOString(),
+        ...state.lastReviewer ? { author: state.lastReviewer } : {},
+        url: prUrl
+      };
+    }
+    await maybePingStaleReviewer(issue, prUrl, state, newestReviewerActivity);
+    return null;
+  }
+  async function maybePingStaleReviewer(issue, prUrl, state, newestReviewerActivity) {
+    const staleHours = cfg.linear.codeReviewStaleHours;
+    if (staleHours <= 0)
+      return;
+    const reviewer = state.requestedReviewer ?? state.lastReviewer;
+    if (!reviewer)
+      return;
+    const lastPinged = stalePingedAt.get(prUrl);
+    const now2 = Date.now();
+    if (lastPinged && now2 - lastPinged < staleHours * 3600000)
+      return;
+    const elapsedH = newestReviewerActivity ? (now2 - Date.parse(newestReviewerActivity)) / 3600000 : Infinity;
+    if (elapsedH < staleHours)
+      return;
+    const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/.exec(prUrl);
+    if (!m)
+      return;
+    const [, owner, repo, num] = m;
+    const body = `\uD83D\uDD14 @${reviewer} \u2014 Ralph has been waiting ${elapsedH.toFixed(0)}h on a re-review for ${prUrl}. Could you take another look when you have a moment?`;
+    try {
+      await cmdRunner.run(["gh", "api", `repos/${owner}/${repo}/issues/${num}/comments`, "-f", `body=${body}`], projectRoot);
+      stalePingedAt.set(prUrl, now2);
+      onLog(`  ${issue.identifier}: pinged reviewer @${reviewer} on ${prUrl}`, "gray");
+    } catch (err) {
+      onLog(`! reviewer ping failed for ${prUrl}: ${err.message}`, "yellow");
+    }
+  }
+  async function fetchPrReviewState(prUrl) {
+    const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/.exec(prUrl);
+    if (!m)
+      return null;
+    const [, owner, repo, num] = m;
+    const query = `query($owner:String!,$repo:String!,$num:Int!){
+      repository(owner:$owner,name:$repo){
+        pullRequest(number:$num){
+          state merged reviewDecision
+          reviewRequests(first:5){nodes{requestedReviewer{... on User{login}}}}
+          latestReviews(first:5){nodes{author{login} state submittedAt}}
+          reviewThreads(first:50){nodes{
+            isResolved path line
+            comments(first:20){nodes{body author{login} createdAt url}}
+          }}
+        }
+      }
+    }`;
+    try {
+      const res = await cmdRunner.run([
+        "gh",
+        "api",
+        "graphql",
+        "-f",
+        `query=${query}`,
+        "-F",
+        `owner=${owner}`,
+        "-F",
+        `repo=${repo}`,
+        "-F",
+        `num=${num}`
+      ], projectRoot);
+      const parsed = JSON.parse(res.stdout);
+      const pr = parsed.data?.repository?.pullRequest;
+      if (!pr)
+        return null;
+      const requested = pr.reviewRequests?.nodes.map((n) => n.requestedReviewer?.login).filter((x) => !!x)[0];
+      const latestReviews = pr.latestReviews?.nodes ?? [];
+      const lastReviewer = latestReviews.slice().sort((a, b) => b.submittedAt > a.submittedAt ? 1 : -1).map((n) => n.author?.login).filter((x) => !!x)[0];
+      return {
+        isOpen: pr.state === "OPEN",
+        merged: pr.merged,
+        approved: pr.reviewDecision === "APPROVED",
+        threads: (pr.reviewThreads?.nodes ?? []).map((t) => ({
+          isResolved: t.isResolved,
+          ...t.path ? { path: t.path } : {},
+          ...t.line != null ? { line: t.line } : {},
+          comments: t.comments.nodes.map((c) => ({
+            ...c.author?.login ? { author: c.author.login } : {},
+            body: c.body,
+            createdAt: c.createdAt,
+            ...c.url ? { url: c.url } : {}
+          }))
+        })),
+        ...requested ? { requestedReviewer: requested } : {},
+        ...lastReviewer ? { lastReviewer } : {}
+      };
+    } catch (err) {
+      onLog(`! gh graphql review-state failed for ${prUrl}: ${err.message}`, "yellow");
+      return null;
+    }
+  }
+  function findLastRalphPickupISO(comments) {
+    let latest = null;
+    for (const c of comments) {
+      if (!/^\uD83D\uDD01\s*Ralph picked up/.test(c.body.trimStart()))
+        continue;
+      if (latest === null || c.createdAt > latest)
+        latest = c.createdAt;
+    }
+    return latest;
+  }
+  function containsHandle(body, handle) {
+    const re = new RegExp(`(^|\\s|[^A-Za-z0-9_])${escapeRegex(handle)}\\b`, "i");
+    return re.test(body);
+  }
+  async function resolvePrUrlForIssue(issue) {
+    const changeName = changeNameForIssue(issue);
+    if (prUnavailable.has(changeName))
+      return null;
+    const cached = prByChange.get(changeName);
+    if (cached)
+      return cached;
+    const branch = branchForChange(changeName);
+    try {
+      const res = await cmdRunner.run([
+        "gh",
+        "pr",
+        "list",
+        "--head",
+        branch,
+        "--state",
+        "all",
+        "--json",
+        "url",
+        "--jq",
+        ".[0].url // empty"
+      ], projectRoot);
+      const found = res.stdout.trim();
+      if (!found) {
+        prUnavailable.add(changeName);
+        return null;
+      }
+      prByChange.set(changeName, found);
+      return found;
+    } catch {
+      return null;
+    }
+  }
+  async function fetchPrIssueComments(prUrl) {
+    const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/.exec(prUrl);
+    if (!m)
+      return [];
+    const [, owner, repo, num] = m;
+    try {
+      const res = await cmdRunner.run([
+        "gh",
+        "api",
+        `repos/${owner}/${repo}/issues/${num}/comments`,
+        "--jq",
+        "[.[] | {body: .body, createdAt: .created_at, author: .user.login, url: .html_url}]"
+      ], projectRoot);
+      const parsed = JSON.parse(res.stdout || "[]");
+      return parsed;
+    } catch (err) {
+      onLog(`! mention scan: gh comments failed for ${prUrl}: ${err.message}`, "yellow");
+      return [];
+    }
+  }
   const coord = new AgentCoordinator({
     fetchTodo: () => fetchByGet(indicators.getTodo, excludeFromTodo),
     fetchInProgress: () => fetchByGet(indicators.getInProgress, []),
     fetchConflicted: () => fetchByGet(indicators.getConflicted, []),
     fetchReview: () => fetchByGet(indicators.getReview, excludeFromReview),
+    fetchMentions,
     fetchDoneCandidates,
     prepare,
     spawnWorker,

package/package.json

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