@neriros/ralphy 3.10.16 → 3.10.17

package/dist/shell/index.js

@@ -18928,8 +18928,8 @@ import { readFileSync } from "fs";
 import { resolve } from "path";
 function getVersion() {
   try {
-    if ("3.10.16")
-      return "3.10.16";
+    if ("3.10.17")
+      return "3.10.17";
   } catch {}
   const dirsToTry = [];
   try {
@@ -19395,7 +19395,7 @@ function modelOptionValues() {
   const field = findField("model");
   return field && field.spec.kind === "select" ? field.spec.options.map((o) => o.value) : [];
 }
-var PROMPT_BODY_FIELD_ID = "promptBody", REPO_LINK_FIELD_ID = "repo.link", yes = () => ({ kind: "confirm", defaultChoice: "confirm" }), no = () => ({ kind: "confirm", defaultChoice: "cancel" }), PROJECT_NAME, LINEAR_TEAM, REPO_LINK, LINEAR_ASSIGNEE_CHOICE_FIELD_ID = "linear.assigneeChoice", LINEAR_ASSIGNEE_VALUE_FIELD_ID = "linear.assigneeValue", LINEAR_FILTER_DESCRIPTION, LINEAR_ASSIGNEE_CHOICE, LINEAR_ASSIGNEE_VALUE, QUICK_FIELDS, isOn = (id) => (answers) => answers[id] === true, concurrencyForcesWorktree = (answers) => {
+var PROMPT_BODY_FIELD_ID = "promptBody", REPO_LINK_FIELD_ID = "repo.link", yes = () => ({ kind: "confirm", defaultChoice: "confirm" }), no = () => ({ kind: "confirm", defaultChoice: "cancel" }), PROJECT_NAME, LINEAR_TEAM, REPO_LINK, LINEAR_ASSIGNEE_CHOICE_FIELD_ID = "linear.assigneeChoice", LINEAR_ASSIGNEE_VALUE_FIELD_ID = "linear.assigneeValue", LINEAR_FILTER_DESCRIPTION, LINEAR_ASSIGNEE_CHOICE, LINEAR_ASSIGNEE_VALUE, QUICK_FIELDS, isOn = (id) => (answers) => answers[id] === true, trackerIsGithub = (answers) => answers["tracker.kind"] === "github", concurrencyForcesWorktree = (answers) => {
   const value = answers["concurrency"];
   return typeof value === "number" && value > 1;
 }, worktreeEnabled = (answers) => answers["useWorktree"] === true || concurrencyForcesWorktree(answers), HIDDEN_FIELD_IDS, CUSTOMIZED_FIELDS, COMMON_CLI_OPTIONS, FIELD_DESCRIPTIONS;
@@ -19537,6 +19537,66 @@ var init_fields = __esm(() => {
       description: "Show detailed per-task output (passes --verbose to the task sub-process) for extra diagnostics.",
       spec: no()
     },
+    {
+      id: "tracker.kind",
+      label: "Issue tracker",
+      description: "Which issue tracker drives the loop: 'linear' (the default) or 'github' (GitHub Issues, via the gh CLI).",
+      spec: {
+        kind: "select",
+        options: [
+          { label: "Linear", value: "linear" },
+          { label: "GitHub", value: "github" }
+        ]
+      }
+    },
+    {
+      id: "github.issues.repo",
+      label: "GitHub repository (owner/name)",
+      hint: "blank = detected from origin",
+      description: "The owner/name of the GitHub repo whose issues drive the loop. Leave blank to use the repo detected from the git 'origin' remote.",
+      emptyLabel: "detected from origin",
+      spec: { kind: "text", placeholder: "owner/name" },
+      when: trackerIsGithub
+    },
+    {
+      id: "github.issues.label",
+      label: "Todo label",
+      hint: "blank = any open issue",
+      description: "Only pick up GitHub issues carrying this label. Leave blank to consider every open issue.",
+      emptyLabel: "any open issue",
+      spec: { kind: "text", placeholder: "ralph:todo" },
+      when: trackerIsGithub
+    },
+    {
+      id: "github.issues.assignee",
+      label: "Assignee filter",
+      hint: "blank = any assignee; @me = you",
+      description: "Only pick up GitHub issues assigned to this login. Use '@me' for yourself; leave blank to ignore the assignee.",
+      emptyLabel: "any assignee",
+      spec: { kind: "text", placeholder: "@me" },
+      when: trackerIsGithub
+    },
+    {
+      id: "github.issues.statusLabels.inProgress",
+      label: "In-progress label",
+      description: "GitHub label applied to an issue while Ralphy is actively working on it (and removed from the todo label).",
+      spec: { kind: "text", placeholder: "ralph:in-progress" },
+      when: trackerIsGithub
+    },
+    {
+      id: "github.issues.statusLabels.done",
+      label: "Done label",
+      description: "GitHub label applied to an issue when its work completes; the issue is also closed.",
+      spec: { kind: "text", placeholder: "ralph:done" },
+      when: trackerIsGithub
+    },
+    {
+      id: "github.issues.statusLabels.error",
+      label: "Error label",
+      description: "GitHub label applied to an issue when Ralphy quarantines it after repeated failures.",
+      spec: { kind: "text", placeholder: "ralph:error" },
+      when: trackerIsGithub
+    },
     {
       id: "concurrency",
       label: "Concurrency (parallel tasks)",
@@ -81255,7 +81315,7 @@ function foldLegacyAssignee(v) {
   }
   return rest2;
 }
-var CURRENT_WORKFLOW_VERSION = 6, MarkerSchema, FilterMarkerSchema, LinearFilterSchema, SET_INDICATOR_KEYS, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, ProjectSchema, CommandsSchema, DEFAULT_META_ONLY_FILES, BoundariesSchema, WorkflowConfigSchema;
+var CURRENT_WORKFLOW_VERSION = 7, MarkerSchema, FilterMarkerSchema, LinearFilterSchema, SET_INDICATOR_KEYS, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, ProjectSchema, CommandsSchema, DEFAULT_META_ONLY_FILES, BoundariesSchema, WorkflowConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   MarkerSchema = exports_external.discriminatedUnion("type", [
@@ -81401,6 +81461,9 @@ var init_schema = __esm(() => {
     finalizeNoOpAsDone: exports_external.boolean().default(true),
     engine: exports_external.enum(["claude", "codex"]).default("claude"),
     model: exports_external.enum(["haiku", "sonnet", "opus"]).default("opus"),
+    tracker: exports_external.object({
+      kind: exports_external.enum(["linear", "github"]).default("linear")
+    }).strict().default({ kind: "linear" }),
     linear: exports_external.preprocess(foldLegacyAssignee, exports_external.object({
       team: exports_external.string().optional(),
       filter: LinearFilterSchema,
@@ -81445,7 +81508,21 @@ var init_schema = __esm(() => {
     }),
     github: exports_external.object({
       base_branch: exports_external.string().optional(),
-      auto_merge_strategy: exports_external.enum(["squash", "merge", "rebase"]).optional()
+      auto_merge_strategy: exports_external.enum(["squash", "merge", "rebase"]).optional(),
+      issues: exports_external.object({
+        repo: exports_external.string().optional(),
+        label: exports_external.string().optional(),
+        assignee: exports_external.string().optional(),
+        statusLabels: exports_external.object({
+          inProgress: exports_external.string().default("ralph:in-progress"),
+          done: exports_external.string().default("ralph:done"),
+          error: exports_external.string().default("ralph:error")
+        }).strict().default({
+          inProgress: "ralph:in-progress",
+          done: "ralph:done",
+          error: "ralph:error"
+        })
+      }).strict().optional()
     }).strict().optional(),
     agent: exports_external.object({
       engine: exports_external.enum(["claude", "codex"]).optional(),
@@ -81514,7 +81591,7 @@ var init_schema = __esm(() => {
 var FRONTMATTER_RE, DEFAULT_WORKFLOW_MD = `---
 # WORKFLOW.md schema version \u2014 managed by \`ralphy init\`. When a newer version
 # ships, re-running init migrates this file and fills in the new settings.
-version: 6
+version: 7
 
 project:
   name: ralphy
@@ -81581,6 +81658,16 @@ preExistingErrorCheck:
   label: "ralph:pre-existing-error"
   outputCharLimit: 4000
 
+tracker:
+  kind: linear
+
+github:
+  issues:
+    statusLabels:
+      inProgress: "ralph:in-progress"
+      done: "ralph:done"
+      error: "ralph:error"
+
 linear:
   # Global filter ANDed into every Linear query (and the GitHub PR searches
   # rooted at those issues). A marker list of \`assignee\` and \`label\` clauses;
@@ -83405,6 +83492,12 @@ function buildFromAnswers(mode, answers, build = buildWorkflowMarkdown) {
       }
     }
   }
+  if (values2["tracker.kind"] !== "github") {
+    for (const id of Object.keys(values2)) {
+      if (id.startsWith("github.issues."))
+        delete values2[id];
+    }
+  }
   const linkRepo = values2[REPO_LINK_FIELD_ID] === true;
   delete values2[REPO_LINK_FIELD_ID];
   if (!linkRepo) {
@@ -84585,6 +84678,19 @@ var init_migrations = __esm(() => {
       version: 6,
       description: "PR recovery is unified under one `prRecovery` block (replacing " + "`prTracker`, `fixCiOnFailure`, `maxCiFixAttempts`, `ciPollIntervalSeconds`, " + "and `ignoreCiChecks`). Workers now open the PR and leave the ticket " + "in-review; a single background watcher advances it to done once the PR is " + "mergeable (CI green, no conflicts) and recovers red PRs \u2014 resolving merge " + "conflicts AND fixing failing CI (both `prRecovery.fixConflicts` and " + "`prRecovery.fixCi` default on; tune them in WORKFLOW.md). " + "`prRecovery.enabled: false` turns the watcher off everywhere and marks the " + "ticket done immediately on PR open. Your old values are migrated " + "automatically; review them here or keep them.",
       fields: ["prRecovery.enabled", "prRecovery.maxRecoverySessions", "prRecovery.ignoreChecks"]
+    },
+    {
+      version: 7,
+      description: "Pick your issue tracker: Linear (default) or GitHub Issues. The new " + "`tracker.kind` switch selects the provider; choosing GitHub drives the " + "loop off `gh` issues, filtered by `github.issues.label`/`assignee` and " + "moved through the `github.issues.statusLabels` (in-progress / done / " + "error). Existing files default to Linear, so nothing changes unless you " + "switch.",
+      fields: [
+        "tracker.kind",
+        "github.issues.repo",
+        "github.issues.label",
+        "github.issues.assignee",
+        "github.issues.statusLabels.inProgress",
+        "github.issues.statusLabels.done",
+        "github.issues.statusLabels.error"
+      ]
     }
   ];
   LATEST_MIGRATION_VERSION = MIGRATIONS.reduce((max2, migration) => Math.max(max2, migration.version), 0);
@@ -100164,7 +100270,7 @@ function normalizeNewlyAppendedSectionWithReport(previous, current) {
   });
   return { text: count > 0 ? out.join("") : current, headings, count };
 }
-var MISSION_TASKS_FILENAME = "tasks.md", AGENT_TASKS_FILENAME = "agent-tasks.md", FLOW_TASK_HEADING_PREFIXES;
+var MISSION_TASKS_FILENAME = "tasks.md", AGENT_TASKS_FILENAME = "agent-tasks.md", HANDOFF_FILENAME = "handoff.md", FLOW_TASK_HEADING_PREFIXES;
 var init_tasks_md = __esm(() => {
   FLOW_TASK_HEADING_PREFIXES = [
     "Fix failing CI checks",
@@ -100417,6 +100523,20 @@ function buildTaskPrompt(state, taskDir, reviewPhase) {
 `;
     }
   }
+  const handoffContent = storage.read(join15(taskDir, HANDOFF_FILENAME));
+  if (handoffContent !== null && handoffContent.trim()) {
+    prompt += `---
+`;
+    prompt += `# Previous Iteration Handoff (context from the last iteration)
+
+`;
+    prompt += handoffContent.trim() + `
+
+`;
+    prompt += `---
+
+`;
+  }
   const agentTasksPath = join15(taskDir, AGENT_TASKS_FILENAME);
   const missionTasksPath = join15(taskDir, MISSION_TASKS_FILENAME);
   const agentTasksContent = storage.read(agentTasksPath);
@@ -100564,6 +100684,22 @@ When all tasks are complete and all files are committed, push your branch and op
     prompt += `Use the change name as the PR title and write a concise summary of the implementation in the body.
 `;
   }
+  const handoffPath = join15(taskDir, HANDOFF_FILENAME);
+  prompt += `
+---
+
+## Write Handoff (do this LAST, before you finish)
+`;
+  prompt += `Before ending this iteration, record a handoff for the next iteration:
+`;
+  prompt += `- If a \`handoff\` skill is available, invoke it; otherwise write the document yourself.
+`;
+  prompt += `- Save it to \`${handoffPath}\` (OVERWRITE the existing file \u2014 do NOT append, do NOT save to a temp dir).
+`;
+  prompt += `- Keep it compact: what you did this iteration, what remains, key decisions, and any blockers/gotchas. Reference artifacts by path instead of duplicating them.
+`;
+  prompt += `- This file is loop scratch \u2014 do NOT commit it.
+`;
   return prompt;
 }
 function buildSteeringBlock(taskDir) {
@@ -102600,13 +102736,91 @@ class PollContext {
   }
 }
 
-// apps/agent/src/shared/utils/ralph-comment.ts
-function isRalphComment(body) {
+// packages/comms/src/index.ts
+function sanitizeMarkerValue(value) {
+  return value.replace(/--+>?/g, "-").replace(/\s+/g, "_").trim();
+}
+function buildRalphyMarker(type, fields) {
+  const pairs = [`v=${RALPHY_MARKER_VERSION}`, `type=${type}`];
+  for (const [key, raw] of Object.entries(fields ?? {})) {
+    if (raw === undefined || raw === null || raw === "")
+      continue;
+    pairs.push(`${key}=${sanitizeMarkerValue(String(raw))}`);
+  }
+  return `<!-- ralphy:${pairs.join(" ")} -->`;
+}
+function parseRalphyMarker(body) {
+  const match = /<!--\s*ralphy:([^>]*?\btype=[^>]*?)\s*-->/.exec(body);
+  if (!match)
+    return null;
+  const fields = {};
+  let type = "";
+  let version3 = 0;
+  for (const token of match[1].trim().split(/\s+/)) {
+    const eq = token.indexOf("=");
+    if (eq < 0)
+      continue;
+    const key = token.slice(0, eq);
+    const value = token.slice(eq + 1);
+    if (key === "v")
+      version3 = Number(value) || 0;
+    else if (key === "type")
+      type = value;
+    else
+      fields[key] = value;
+  }
+  if (!type)
+    return null;
+  return { version: version3, type, fields };
+}
+function buildRalphyComment(input) {
+  const lines = [`${RALPHY_TITLE_PREFIX}${input.action}`];
+  const body = input.body?.trim();
+  if (body)
+    lines.push("", body);
+  lines.push("", buildRalphyMarker(input.type, input.fields));
+  return lines.join(`
+`);
+}
+function isRalphyComment(body) {
   const trimmed = body.trimStart();
-  if (/^(\uD83E\uDD16|\uD83D\uDD04|\u2705|\u2717|\u274C|\u26A0|\uD83D\uDD01|\uD83D\uDCCB|\u23F0)\s*Ralphy?\b/.test(trimmed))
+  if (trimmed.startsWith(RALPHY_BRAND))
+    return true;
+  if (parseRalphyMarker(body))
+    return true;
+  if (LEGACY_RALPH_LEAD.test(trimmed))
+    return true;
+  return LEGACY_MENTION_ACK.test(trimmed);
+}
+function isPickupComment(body) {
+  if (parseRalphyMarker(body)?.type === "review-pickup")
+    return true;
+  return /^\uD83D\uDD01\s*Ralph picked up/u.test(body.trimStart());
+}
+function isStartedComment(body) {
+  if (parseRalphyMarker(body)?.type === "started")
+    return true;
+  return /^\uD83E\uDD16\s*Ralph started working/u.test(body.trimStart());
+}
+function isMentionAckComment(body) {
+  if (parseRalphyMarker(body)?.type === "mention-ack")
     return true;
-  return /^\uD83D\uDC40\s*(Got it\b|Acknowledged\b)/.test(trimmed);
+  return LEGACY_MENTION_ACK.test(body.trimStart());
+}
+var RALPHY_BRAND = "\uD83E\uDD16 Ralphy", RALPHY_TITLE_PREFIX, RALPHY_MARKER_VERSION = 1, LEGACY_RALPH_LEAD, LEGACY_MENTION_ACK;
+var init_src8 = __esm(() => {
+  RALPHY_TITLE_PREFIX = `${RALPHY_BRAND} \xB7 `;
+  LEGACY_RALPH_LEAD = /^(\uD83E\uDD16|\uD83D\uDD04|\u2705|\u2717|\u274C|\u26A0\uFE0F?|\uD83D\uDD01|\uD83D\uDCCB|\u23F0|\u2139\uFE0F)\s*Ralphy?\b/u;
+  LEGACY_MENTION_ACK = /^\uD83D\uDC40\s*(Got it\b|Acknowledged\b)/u;
+});
+
+// apps/agent/src/shared/utils/ralph-comment.ts
+function isRalphComment(body) {
+  return isRalphyComment(body);
 }
+var init_ralph_comment = __esm(() => {
+  init_src8();
+});
 
 // apps/agent/src/shared/capabilities/linear-client.ts
 var exports_linear_client = {};
@@ -103543,6 +103757,7 @@ async function removeLabelFromIssue(apiKey, issueId, labelId) {
 var LINEAR_API = "https://api.linear.app/graphql", TICKET_IDENTIFIER_RE, TICKET_BARE_NUMBER_RE, RALPHY_ATTACHMENT_TITLE_FILTER = "Ralphy", linearRequestInternals, MAX_LINEAR_ATTEMPTS = 3, MAX_RETRY_AFTER_MS = 2000, BODY_TRUNCATE_CHARS = 512, RALPHY_ATTACHMENT_TITLE = "Ralphy", BRANCH_LABEL_PREFIX = "ralph:branch:";
 var init_linear_client = __esm(() => {
   init_types2();
+  init_ralph_comment();
   TICKET_IDENTIFIER_RE = /^([A-Za-z]+)-(\d+)(?:-.*)?$/;
   TICKET_BARE_NUMBER_RE = /^(\d+)$/;
   linearRequestInternals = {
@@ -103885,7 +104100,7 @@ function stackedOnLine(stackedOn) {
   return `> \uD83E\uDD5E Stacked on ${prRef}${ticket} \u2014 review/merge that PR first. Base is its branch, not the default branch.`;
 }
 function defaultBody(issue2, branch, stackedOn) {
-  return [
+  const detail = [
     `Auto-generated by Ralph for ${issue2.identifier}.`,
     stackedOn ? stackedOnLine(stackedOn) : "",
     `Source: ${issue2.url}`,
@@ -103896,6 +104111,12 @@ function defaultBody(issue2, branch, stackedOn) {
 ${issue2.description.trim()}` : ""
   ].filter(Boolean).join(`
 `);
+  return buildRalphyComment({
+    type: "pr-body",
+    action: "opened PR",
+    body: detail,
+    fields: { issue: issue2.identifier }
+  });
 }
 async function diffFilesAgainstBase(runner, cwd2, base2) {
   let raw = "";
@@ -104015,7 +104236,9 @@ async function createPullRequest(input, runner) {
 `).pop() ?? "";
   return { url: url2, created: true };
 }
-var init_pr = () => {};
+var init_pr = __esm(() => {
+  init_src8();
+});
 
 // apps/agent/src/shared/pr/ci-classify.ts
 async function runGhWithRetry(cmd, runner, cwd2, onRetry, sleep2 = (ms) => new Promise((r) => setTimeout(r, ms))) {
@@ -105126,6 +105349,25 @@ async function runPostTask(input, deps) {
   }
   if (input.mode === "conflict-fix" && effectiveCode === 0) {
     const identifier = issue2?.identifier ?? changeName;
+    if (branch) {
+      let aheadCount = 0;
+      let checked = true;
+      try {
+        const r = await cmd.run(["git", "rev-list", "--count", `origin/${branch}..HEAD`], cwd2);
+        aheadCount = Number.parseInt(r.stdout.trim(), 10) || 0;
+      } catch (err) {
+        checked = false;
+        log3(`! ${identifier}: could not check for unpushed conflict-fix commits: ${err.message}`, "yellow");
+      }
+      if (checked && aheadCount > 0) {
+        log3(`! ${identifier}: conflict-fix worker left ${aheadCount} unpushed commit(s) ahead of ` + `origin/${branch} \u2014 the resolution never reached the PR. Failing the iteration so it ` + `is retried instead of reported as resolved.`, "red");
+        emit3("gave-up", "unpushed conflict resolution");
+        await recordGaveUp(stateFilePath, log3, changeName);
+        await runWorktreeCleanupPhase({ changeName, cwd: cwd2, projectRoot, useWorktree, effectiveCode: PR_FAILED_EXIT, cfg }, { git: git2, log: log3, emit: emit3 });
+        await runTeardownPhase({ cwd: cwd2, teardownScript: cfg.teardownScript }, { runScript, log: log3, emit: emit3 });
+        return PR_FAILED_EXIT;
+      }
+    }
     let prUrl = input.prUrl ?? null;
     if (!prUrl && branch) {
       prUrl = await findExistingOpenPrUrl(cmd, cwd2, branch);
@@ -105500,19 +105742,37 @@ function emitCapture(bus, event, properties) {
 function completionCommentBody(args) {
   const { noChanges, ok, trigger, changeName, code } = args;
   if (noChanges) {
-    return `\u2139\uFE0F Ralph completed all tasks for this issue but produced no code changes \u2014 ` + `the requested work appears to already be present on the base branch (or was a ` + `no-op). No PR was opened. Change: \`${changeName}\`
+    return buildRalphyComment({
+      type: "completed-noop",
+      action: "completed \u2014 no code changes",
+      body: `Completed all tasks for this issue but produced no code changes \u2014 the requested ` + `work appears to already be present on the base branch (or was a no-op). No PR was ` + `opened. Change: \`${changeName}\`
 
-` + `Marking this done; please verify the work is genuinely in place. If it is not, ` + `reopen the issue with more specifics.`;
+` + `Marking this done; please verify the work is genuinely in place. If it is not, ` + `reopen the issue with more specifics.`,
+      fields: { change: changeName }
+    });
   }
   if (!ok) {
-    return `\u2717 Ralph exited with code ${code} on this issue. Change: \`${changeName}\`
-
-` + `This issue has been quarantined and will not be auto-resumed on the next poll. ` + `Inspect the worktree at \`~/.ralph/<project>/worktrees/${changeName}\`, fix the ` + `underlying failure, then remove the error marker on this Linear issue (or run ` + `\`ralph clean --name ${changeName}\`) to clear the quarantine.`;
+    return buildRalphyComment({
+      type: "exited",
+      action: `exited with code ${code}`,
+      body: `This issue has been quarantined and will not be auto-resumed on the next poll. ` + `Inspect the worktree at \`~/.ralph/<project>/worktrees/${changeName}\`, fix the ` + `underlying failure, then remove the error marker on this Linear issue (or run ` + `\`ralph clean --name ${changeName}\`) to clear the quarantine. Change: \`${changeName}\``,
+      fields: { change: changeName, code }
+    });
   }
   if (trigger === "conflict-fix") {
-    return `\u2705 Ralph resolved merge conflicts on this issue. Change: \`${changeName}\``;
+    return buildRalphyComment({
+      type: "conflicts-resolved",
+      action: "resolved merge conflicts",
+      body: `Change: \`${changeName}\``,
+      fields: { change: changeName }
+    });
   }
-  return `\u2705 Ralph completed work on this issue. Change: \`${changeName}\``;
+  return buildRalphyComment({
+    type: "completed",
+    action: "completed work",
+    body: `Change: \`${changeName}\``,
+    fields: { change: changeName }
+  });
 }
 function extractPrNumber(url2) {
   const m = /\/pull\/(\d+)(?:[/?#]|$)/.exec(url2);
@@ -105811,7 +106071,12 @@ class AgentCoordinator {
       const prNum = extractPrNumber(pr.url);
       const ref = prNum !== null ? `PR #${prNum}` : `PR ${pr.url}`;
       try {
-        await this.deps.postComment(issue2, `\u26A0\uFE0F ${ref} is ${stateLabel} \u2014 promoted to ${trigger} flow.`);
+        await this.deps.postComment(issue2, buildRalphyComment({
+          type: "promoted",
+          action: `promoted to ${trigger} flow`,
+          body: `${ref} is ${stateLabel} \u2014 promoted to ${trigger} flow.`,
+          fields: { trigger, pr: extractPrNumber(pr.url) ?? pr.url }
+        }));
         this.deps.onLog(`  ${issue2.identifier}: posted ${trigger}-promotion comment`, "gray");
       } catch (err) {
         this.deps.onLog(`! Linear ${trigger}-promotion comment failed for ${issue2.identifier}: ${err.message}`, "yellow");
@@ -105864,7 +106129,12 @@ class AgentCoordinator {
       if (currMilestone <= lastMilestone)
         continue;
       try {
-        await this.deps.postComment(w.issue, `\uD83D\uDD04 Ralph progress update: iteration ${count} on \`${w.changeName}\``);
+        await this.deps.postComment(w.issue, buildRalphyComment({
+          type: "progress",
+          action: `progress update \u2014 iteration ${count}`,
+          body: `Iteration ${count} on \`${w.changeName}\``,
+          fields: { change: w.changeName, iter: count }
+        }));
         w.lastReportedIteration = count;
         this.deps.onLog(`  ${w.issueIdentifier}: posted progress comment (iteration ${count})`, "gray");
       } catch (err) {
@@ -106004,7 +106274,12 @@ class AgentCoordinator {
         this.deps.onLog(`  ${issue2.identifier}: PR ${pr.url} conflicting \u2014 queued (conflict-fix)`, "yellow");
         if (this.opts.postComments !== false) {
           try {
-            await this.deps.postComment(issue2, `\u26A0 Ralph detected merge conflicts on this PR (${pr.url}) \u2014 re-running to resolve`);
+            await this.deps.postComment(issue2, buildRalphyComment({
+              type: "conflict-detected",
+              action: "detected merge conflicts",
+              body: `Detected merge conflicts on this PR (${pr.url}) \u2014 re-running to resolve.`,
+              fields: { pr: extractPrNumber(pr.url) ?? pr.url }
+            }));
           } catch (err) {
             this.deps.onLog(`! Linear conflict comment failed for ${issue2.identifier}: ${err.message}`, "yellow");
           }
@@ -106039,7 +106314,12 @@ class AgentCoordinator {
         this.deps.onLog(`  ${issue2.identifier}: PR ${pr.url} CI failing \u2014 queued (ci-fix)`, "yellow");
         if (this.opts.postComments !== false) {
           try {
-            await this.deps.postComment(issue2, `\u26A0 Ralph detected failing CI on this PR (${pr.url}) \u2014 re-running to fix`);
+            await this.deps.postComment(issue2, buildRalphyComment({
+              type: "ci-failed",
+              action: "detected failing CI",
+              body: `Detected failing CI on this PR (${pr.url}) \u2014 re-running to fix.`,
+              fields: { pr: extractPrNumber(pr.url) ?? pr.url }
+            }));
           } catch (err) {
             this.deps.onLog(`! Linear ci-failed comment failed for ${issue2.identifier}: ${err.message}`, "yellow");
           }
@@ -106105,7 +106385,12 @@ class AgentCoordinator {
     }
     if (this.opts.postComments !== false) {
       try {
-        await this.deps.postComment(issue2, `\u2705 Ralph verified this PR (${prUrl}) is mergeable (CI green, no conflicts) \u2014 moving to done`);
+        await this.deps.postComment(issue2, buildRalphyComment({
+          type: "verified",
+          action: "verified PR mergeable",
+          body: `Verified this PR (${prUrl}) is mergeable (CI green, no conflicts) \u2014 moving to done.`,
+          fields: { pr: extractPrNumber(prUrl) ?? prUrl }
+        }));
       } catch (err) {
         this.deps.onLog(`! Linear done comment failed for ${issue2.identifier}: ${err.message}`, "yellow");
       }
@@ -106151,7 +106436,12 @@ class AgentCoordinator {
       if (this.opts.postComments !== false) {
         const human = reason === "conflicting" ? "merge conflicts" : "failing CI";
         try {
-          await this.deps.postComment(issue2, `\u274C Ralph gave up auto-recovering this PR (${prUrl}) after ${decision.attempts} attempts \u2014 last failure: ${human}. The \`ralph:error\` label has been applied; clear it (or merge the PR) once a human has looked at it.`);
+          await this.deps.postComment(issue2, buildRalphyComment({
+            type: "recovery-gaveup",
+            action: "gave up auto-recovering PR",
+            body: `Gave up auto-recovering this PR (${prUrl}) after ${decision.attempts} attempts \u2014 last failure: ${human}. The \`ralph:error\` label has been applied; clear it (or merge the PR) once a human has looked at it.`,
+            fields: { pr: extractPrNumber(prUrl) ?? prUrl, attempts: decision.attempts }
+          }));
         } catch (err) {
           this.deps.onLog(`! Linear bail comment failed for ${issue2.identifier}: ${err.message}`, "yellow");
         }
@@ -106238,7 +106528,12 @@ class AgentCoordinator {
     if (trigger === "review" && this.opts.postComments !== false) {
       const sourceTag = mention ? mention.source === "github" ? " (GitHub @mention)" : mention.source === "github-review" ? " (GitHub code review)" : " (Linear @mention)" : "";
       try {
-        await this.deps.postComment(issue2, `\uD83D\uDD01 Ralph picked up new review comments${sourceTag}. Tracking change: \`${prep.changeName}\``);
+        await this.deps.postComment(issue2, buildRalphyComment({
+          type: "review-pickup",
+          action: "picked up review comments",
+          body: `Picked up new review comments${sourceTag}. Tracking change: \`${prep.changeName}\``,
+          fields: { change: prep.changeName }
+        }));
       } catch (err) {
         this.deps.onLog(`! Linear review comment failed for ${issue2.identifier}: ${err.message}`, "yellow");
       }
@@ -106247,13 +106542,18 @@ class AgentCoordinator {
       let alreadyPosted = false;
       try {
         const comments = await this.deps.fetchComments(issue2.id);
-        alreadyPosted = comments.some((c) => c.body.startsWith("\uD83E\uDD16 Ralph started working"));
+        alreadyPosted = comments.some((c) => isStartedComment(c.body));
       } catch (err) {
         this.deps.onLog(`! Linear comment fetch failed for ${issue2.identifier}: ${err.message}`, "yellow");
       }
       if (!alreadyPosted) {
         try {
-          await this.deps.postComment(issue2, `\uD83E\uDD16 Ralph started working on this issue. Tracking change: \`${prep.changeName}\``);
+          await this.deps.postComment(issue2, buildRalphyComment({
+            type: "started",
+            action: "started working",
+            body: `Tracking change: \`${prep.changeName}\``,
+            fields: { change: prep.changeName }
+          }));
           this.deps.onLog(`  ${issue2.identifier}: posted "started" comment`, "gray");
         } catch (err) {
           this.deps.onLog(`! Linear comment failed for ${issue2.identifier}: ${err.message}`, "red");
@@ -106568,6 +106868,7 @@ var init_coordinator = __esm(() => {
   init_registry();
   init_run_feature();
   init_machines();
+  init_src8();
 });
 
 // apps/agent/src/agent/coordinator.ts
@@ -106575,11 +106876,38 @@ var init_coordinator2 = __esm(() => {
   init_coordinator();
 });
 
+// apps/agent/src/shared/capabilities/gh-client.ts
+var init_gh_client = () => {};
+
+// apps/agent/src/shared/capabilities/github/github-client.ts
+var STARTED_LABEL_NAMES, ISSUE_FIELDS = "id,number,title,body,state,stateReason,labels,assignees,author,createdAt,url", ISSUE_FIELDS_WITH_COMMENTS;
+var init_github_client = __esm(() => {
+  init_worktree();
+  init_gh_client();
+  STARTED_LABEL_NAMES = new Set(["in progress", "in-progress", "started"]);
+  ISSUE_FIELDS_WITH_COMMENTS = `${ISSUE_FIELDS},comments`;
+});
+
+// apps/agent/src/shared/capabilities/github/identifier-strategy.ts
+function linearChangeName(issue2) {
+  const slug = issue2.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40).replace(/^-+|-+$/g, "");
+  return slug ? `${issue2.identifier.toLowerCase()}-${slug}` : issue2.identifier.toLowerCase();
+}
+var linearIdentifierStrategy;
+var init_identifier_strategy = __esm(() => {
+  init_worktree();
+  init_github_client();
+  linearIdentifierStrategy = {
+    scopeKey: (issue2) => issue2.identifier.split("-")[0],
+    changeName: linearChangeName,
+    branchName: (issue2) => branchForChange(linearChangeName(issue2))
+  };
+});
+
 // apps/agent/src/agent/scaffold.ts
 import { join as join24 } from "path";
 function changeNameForIssue(issue2) {
-  const slug = issue2.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40).replace(/^-+|-+$/g, "");
-  return slug ? `${issue2.identifier.toLowerCase()}-${slug}` : issue2.identifier.toLowerCase();
+  return linearIdentifierStrategy.changeName(issue2);
 }
 async function scaffoldChangeForIssue(tasksDir, statesDir, issue2, comments = [], appendPrompt = "", attachments = []) {
   const name = changeNameForIssue(issue2);
@@ -106661,6 +106989,7 @@ async function scaffoldChangeForIssue(tasksDir, statesDir, issue2, comments = []
 }
 var init_scaffold = __esm(() => {
   init_fs_change();
+  init_identifier_strategy();
 });
 
 // packages/core/src/detections/tasks.ts
@@ -106704,19 +107033,21 @@ function gateActive(inputs) {
 }
 
 // packages/core/src/detections/mention.ts
-function buildMentionAckComment(body, author) {
-  const firstLine = body.split(`
-`)[0];
-  const truncated = firstLine.slice(0, 200);
-  const excerpt = truncated + (truncated.length < firstLine.length ? "\u2026" : "");
-  const greeting = author ? `\uD83D\uDC40 Got it, ${author}! I've picked up your mention and queued a review pass.` : `\uD83D\uDC40 Acknowledged! I've picked up your mention and queued a review pass.`;
-  return `${greeting}
-
-> ${excerpt}`;
+function buildMentionAckComment(_body, author) {
+  const greeting = author ? `Got it, ${author} \u2014 picked up your mention and queued a review pass.` : `Acknowledged \u2014 picked up your mention and queued a review pass.`;
+  return buildRalphyComment({
+    type: "mention-ack",
+    action: "picked up your mention",
+    body: greeting
+  });
 }
+var init_mention2 = __esm(() => {
+  init_src8();
+});
 // packages/core/src/detections/index.ts
 var init_detections = __esm(() => {
   init_phase2();
+  init_mention2();
 });
 
 // apps/agent/src/features/confirmation/state.ts
@@ -106839,7 +107170,17 @@ function buildMentionTaskBody(trigger, issueUrl) {
 function findLastRalphPickupISO(comments) {
   let latest = null;
   for (const c of comments) {
-    if (!/^\uD83D\uDD01\s*Ralph picked up/.test(c.body.trimStart()))
+    if (!isPickupComment(c.body))
+      continue;
+    if (latest === null || c.createdAt > latest)
+      latest = c.createdAt;
+  }
+  return latest;
+}
+function findLastMentionAckISO(comments) {
+  let latest = null;
+  for (const c of comments) {
+    if (!isMentionAckComment(c.body))
       continue;
     if (latest === null || c.createdAt > latest)
       latest = c.createdAt;
@@ -106875,7 +107216,10 @@ function githubReactionSlug(emoji3) {
       return emoji3;
   }
 }
-var init_task_bodies = () => {};
+var init_task_bodies = __esm(() => {
+  init_src8();
+  init_ralph_comment();
+});
 
 // apps/agent/src/features/confirmation/inspect.ts
 function buildReviseRegex(handle) {
@@ -106902,7 +107246,12 @@ async function inspectAwaitingTicket(state, cfg, deps) {
     if (!next.stuckPostedAt) {
       if (cfg.postComments) {
         try {
-          await deps.postComment(`\u26A0 Ralphy: confirmation gate stuck after ${next.rounds} revise round(s) ` + `(max ${cfg.maxConfirmationRounds}). Applying \`ralph:stuck\` \u2014 ` + `clear the label to retry, or apply the approval marker to proceed.`);
+          await deps.postComment(buildRalphyComment({
+            type: "confirmation-stuck",
+            action: "confirmation gate stuck",
+            body: `Confirmation gate stuck after ${next.rounds} revise round(s) ` + `(max ${cfg.maxConfirmationRounds}). Applying \`ralph:stuck\` \u2014 ` + `clear the label to retry, or apply the approval marker to proceed.`,
+            fields: { rounds: next.rounds }
+          }));
         } catch (err) {
           deps.log(`! plan-stuck comment failed: ${err.message}`, "yellow");
         }
@@ -106947,7 +107296,12 @@ ${revise.reason}`);
     }
     if (cfg.postComments) {
       try {
-        await deps.postComment(`\uD83D\uDD01 Ralphy: revise request acknowledged \u2014 restarting at design (round ${next.rounds + 1}/${cfg.maxConfirmationRounds}).`);
+        await deps.postComment(buildRalphyComment({
+          type: "revise-ack",
+          action: "revise request acknowledged",
+          body: `Revise request acknowledged \u2014 restarting at design (round ${next.rounds + 1}/${cfg.maxConfirmationRounds}).`,
+          fields: { round: next.rounds + 1 }
+        }));
       } catch (err) {
         deps.log(`! revise ack comment failed: ${err.message}`, "yellow");
       }
@@ -106976,7 +107330,12 @@ ${revise.reason}`);
     const limitMs = cfg.timeoutHours * 60 * 60 * 1000;
     if (elapsedMs >= limitMs && cfg.postComments) {
       try {
-        await deps.postComment(`\u23F0 Ralphy: still awaiting confirmation on this plan (round ${next.rounds + 1}/${cfg.maxConfirmationRounds}). ` + `Approve to continue or reply \`${cfg.mentionHandle} revise: <reason>\` to send it back.`);
+        await deps.postComment(buildRalphyComment({
+          type: "confirmation-reminder",
+          action: "awaiting confirmation",
+          body: `Still awaiting confirmation on this plan (round ${next.rounds + 1}/${cfg.maxConfirmationRounds}). ` + `Approve to continue or reply \`${cfg.mentionHandle} revise: <reason>\` to send it back.`,
+          fields: { round: next.rounds + 1 }
+        }));
         next.lastReminderAt = nowIso;
       } catch (err) {
         deps.log(`! reminder comment failed: ${err.message}`, "yellow");
@@ -106986,6 +107345,7 @@ ${revise.reason}`);
   return { outcome: "stay-awaiting", next };
 }
 var init_inspect = __esm(() => {
+  init_src8();
   init_task_bodies();
 });
 
@@ -107028,7 +107388,12 @@ async function postPlanReadyCommentOnce(issue2, statePath, changeName, deps) {
     return;
   const approvalSentence = describeApprovalMarker(deps.cfg.linear.indicators.getApproved);
   const handle = deps.cfg.linear.mentionHandle;
-  const body = `\uD83D\uDCCB Ralphy plan ready for \`${changeName}\` \u2014 review proposal.md / design.md / tasks.md ` + `and ${approvalSentence} to continue, ` + `or reply with \`${handle} revise: <reason>\` to send it back to design.`;
+  const body = buildRalphyComment({
+    type: "plan-ready",
+    action: "plan ready",
+    body: `Plan ready for \`${changeName}\` \u2014 review proposal.md / design.md / tasks.md ` + `and ${approvalSentence} to continue, ` + `or reply with \`${handle} revise: <reason>\` to send it back to design.`,
+    fields: { change: changeName }
+  });
   try {
     await addIssueComment(deps.apiKey, issue2.id, body);
   } catch (err) {
@@ -107307,11 +107672,13 @@ async function processAwaitingForIssue(issue2, deps) {
 }
 var init_awaiting = __esm(() => {
   init_layout();
+  init_src8();
   init_detections();
   init_phase();
   init_worktree();
   init_scaffold();
   init_linear();
+  init_ralph_comment();
   init_types2();
   init_workflow();
   init_state2();
@@ -107538,10 +107905,13 @@ function unionMarkers(...sets) {
   }
   return out;
 }
-function describeIndicators(indicators, team, assignee, anyAssignee) {
+function describeIndicators(indicators, team, assignee, anyAssignee, requireAllLabels) {
   const parts = [];
   parts.push(`team=${team ?? "*"}`);
   parts.push(`assignee=${anyAssignee ? "any" : assignee ?? "*"}`);
+  if (requireAllLabels && requireAllLabels.length > 0) {
+    parts.push(`labels=[${requireAllLabels.join(",")}]`);
+  }
   if (indicators.getTodo) {
     parts.push(`todo=[${indicators.getTodo.filter.map((m) => `${m.type}:${m.value}`).join(",")}]`);
   }
@@ -107561,7 +107931,7 @@ function createLinearResolvers(input) {
   const stateCache = new Map;
   const labelCache = new Map;
   const teamIdCache = new Map;
-  const teamKeyOf = (issue2) => issue2.identifier.split("-")[0];
+  const teamKeyOf = (issue2) => linearIdentifierStrategy.scopeKey(issue2);
   async function resolveStateId(issue2, name) {
     const t = teamKeyOf(issue2);
     let map3 = stateCache.get(t);
@@ -107757,6 +108127,201 @@ async function fetchDoneCandidatesWith(apiKey, team, assignee, anyAssignee, requ
 var init_linear_resolvers = __esm(() => {
   init_types2();
   init_linear();
+  init_identifier_strategy();
+});
+
+// apps/agent/src/agent/wire/tracker/github.ts
+function identifierForNumber(n) {
+  return `issue-${n}`;
+}
+function toLinearIssue(gh) {
+  const open = (gh.state ?? "OPEN").toUpperCase() === "OPEN";
+  return {
+    id: String(gh.number),
+    identifier: identifierForNumber(gh.number),
+    title: gh.title,
+    description: gh.body ?? null,
+    url: gh.url,
+    state: { name: open ? "Open" : "Closed", type: open ? "started" : "completed" },
+    assignee: null,
+    project: null,
+    labels: (gh.labels ?? []).map((l) => l.name),
+    priority: 0,
+    createdAt: gh.createdAt ?? "",
+    blockedByIds: []
+  };
+}
+function labelValues(markers) {
+  return markers.filter((m) => m.type === "label").map((m) => m.value);
+}
+function createGithubTrackerProvider(input) {
+  const { cmdRunner, projectRoot, diag } = input;
+  const statusLabels = input.issues?.statusLabels ?? DEFAULT_STATUS_LABELS;
+  const todoLabel = input.issues?.label;
+  const assignee = input.issues?.assignee;
+  const configuredRepo = input.issues?.repo;
+  let repoPromise = null;
+  async function repo() {
+    if (configuredRepo && configuredRepo.trim() !== "")
+      return configuredRepo.trim();
+    if (!repoPromise) {
+      repoPromise = (async () => {
+        try {
+          const { stdout } = await cmdRunner.run(["gh", "repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"], projectRoot);
+          const detected = stdout.trim();
+          if (!detected)
+            throw new Error("empty");
+          diag("github-tracker", `  using detected GitHub repo ${detected}`, "gray");
+          return detected;
+        } catch (err) {
+          throw new Error("github tracker: could not determine the repository \u2014 set " + "`github.issues.repo` (owner/name) in WORKFLOW.md or run inside a " + `repo with a GitHub 'origin' remote (${err.message})`);
+        }
+      })();
+    }
+    return repoPromise;
+  }
+  async function listIssues(args) {
+    const r = await repo();
+    const { stdout } = await cmdRunner.run([
+      "gh",
+      "issue",
+      "list",
+      "--repo",
+      r,
+      "--state",
+      "open",
+      "--json",
+      "number,title,url,body,state,createdAt,labels",
+      "--limit",
+      "100",
+      ...args
+    ], projectRoot);
+    const parsed = JSON.parse(stdout.trim() || "[]");
+    return parsed.map(toLinearIssue);
+  }
+  async function fetchByGet(inc, excl) {
+    if (!inc)
+      return [];
+    const include = !Array.isArray(inc) && "filter" in inc ? inc.filter : [];
+    const wantLabels = labelValues(include);
+    const args = [];
+    for (const label of wantLabels)
+      args.push("--label", label);
+    if (assignee && assignee.trim() !== "")
+      args.push("--assignee", assignee.trim());
+    const issues = await listIssues(args);
+    const excludeLabels = new Set(labelValues(excl));
+    if (excludeLabels.size === 0)
+      return issues;
+    return issues.filter((issue2) => !issue2.labels.some((l) => excludeLabels.has(l)));
+  }
+  async function ghIssue(issueNumber, ...args) {
+    const r = await repo();
+    await cmdRunner.run(["gh", "issue", ...args, issueNumber, "--repo", r], projectRoot);
+  }
+  async function applyMarker(issue2, m) {
+    if (m.type === "comment") {
+      await ghIssue(issue2.id, "comment", "--body", m.value);
+      diag("github-marker", `  \u2192 ${issue2.identifier} comment`, "gray");
+      return;
+    }
+    if (m.type !== "label") {
+      diag("github-marker", `! ${issue2.identifier}: '${m.type}' markers are not supported by the GitHub tracker \u2014 skipped`, "yellow");
+      return;
+    }
+    await ghIssue(issue2.id, "edit", "--add-label", m.value);
+    diag("github-marker", `  \u2192 ${issue2.identifier} +label='${m.value}'`, "gray");
+    if (m.value === statusLabels.inProgress && todoLabel && todoLabel.trim() !== "") {
+      await ghIssue(issue2.id, "edit", "--remove-label", todoLabel.trim());
+      diag("github-marker", `  \u2192 ${issue2.identifier} -label='${todoLabel.trim()}'`, "gray");
+    }
+    if (m.value === statusLabels.done) {
+      await ghIssue(issue2.id, "close");
+      diag("github-marker", `  \u2192 ${issue2.identifier} closed`, "gray");
+    }
+  }
+  async function applyIndicator(issue2, ind) {
+    for (const m of markersOf(ind))
+      await applyMarker(issue2, m);
+  }
+  async function removeIndicator(issue2, ind) {
+    for (const m of markersOf(ind)) {
+      if (m.type !== "label")
+        continue;
+      await ghIssue(issue2.id, "edit", "--remove-label", m.value);
+      diag("github-marker", `  \u2192 ${issue2.identifier} -label='${m.value}'`, "gray");
+    }
+  }
+  async function fetchDoneCandidates() {
+    return listIssues(["--label", statusLabels.inProgress]);
+  }
+  async function resolveLabelIdForTeam() {
+    return null;
+  }
+  return {
+    fetchByGet,
+    applyIndicator,
+    removeIndicator,
+    applyMarker,
+    fetchDoneCandidates,
+    resolveLabelIdForTeam
+  };
+}
+function githubIndicators(issues) {
+  const statusLabels = issues?.statusLabels ?? DEFAULT_STATUS_LABELS;
+  const todoLabel = issues?.label?.trim();
+  return {
+    getTodo: { filter: todoLabel ? [{ type: "label", value: todoLabel }] : [] },
+    getInProgress: { filter: [{ type: "label", value: statusLabels.inProgress }] },
+    setInProgress: { type: "label", value: statusLabels.inProgress },
+    setDone: { type: "label", value: statusLabels.done },
+    setError: { type: "label", value: statusLabels.error }
+  };
+}
+var DEFAULT_STATUS_LABELS;
+var init_github = __esm(() => {
+  init_types2();
+  DEFAULT_STATUS_LABELS = {
+    inProgress: "ralph:in-progress",
+    done: "ralph:done",
+    error: "ralph:error"
+  };
+});
+
+// apps/agent/src/agent/wire/tracker/linear-tracker-provider.ts
+function createLinearTrackerProvider(input) {
+  const {
+    apiKey,
+    team,
+    assignee,
+    anyAssignee,
+    requireAllLabels,
+    indicators,
+    resolvers,
+    fetchMentions,
+    ticketNumbers
+  } = input;
+  const excludeFromTodo = unionMarkers(indicators.setDone, indicators.setError);
+  const excludeFromInProgress = unionMarkers(indicators.setError);
+  return {
+    fetchTodo: () => resolvers.fetchByGet(indicators.getTodo, excludeFromTodo),
+    fetchInProgress: () => resolvers.fetchByGet(indicators.getInProgress, excludeFromInProgress),
+    fetchReview: () => resolvers.fetchByGet(indicators.getReview, []),
+    fetchMentions,
+    fetchDoneCandidates: () => fetchDoneCandidatesWith(apiKey, team, assignee, anyAssignee, requireAllLabels, indicators, ticketNumbers && ticketNumbers.length > 0 ? ticketNumbers : undefined),
+    applyIndicator: resolvers.applyIndicator,
+    removeIndicator: resolvers.removeIndicator,
+    postComment: (issue2, body) => addIssueComment(apiKey, issue2.id, body),
+    fetchComments: async (issueId) => {
+      const c = await fetchIssueComments(apiKey, issueId);
+      return c.map((x) => ({ body: x.body }));
+    }
+  };
+}
+var init_linear_tracker_provider = __esm(() => {
+  init_linear();
+  init_indicators();
+  init_linear_resolvers();
 });
 
 // apps/agent/src/agent/wire/prepare.ts
@@ -108371,7 +108936,12 @@ async function maybePingStaleReviewer(issue2, prUrl, state, newestReviewerActivi
   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?`;
+  const body = buildRalphyComment({
+    type: "reviewer-ping",
+    action: "nudging reviewer",
+    body: `@${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?`,
+    fields: { reviewer }
+  });
   try {
     await deps.cmdRunner.run(["gh", "api", `repos/${owner}/${repo}/issues/${num}/comments`, "-f", `body=${body}`], deps.projectRoot);
     deps.stalePingedAt.set(prUrl, now2);
@@ -108437,6 +109007,7 @@ async function scanCodeReview(issue2, prUrl, lastRalphPickup, deps) {
 var init_scan = __esm(() => {
   init_layout();
   init_store();
+  init_src8();
   init_scaffold();
   init_worktree();
 });
@@ -108486,7 +109057,7 @@ async function fetchPrIssueComments(cmdRunner, projectRoot, prUrl, onLog) {
     return [];
   }
 }
-var init_github = __esm(() => {
+var init_github2 = __esm(() => {
   init_linear();
   init_task_bodies();
 });
@@ -108494,6 +109065,19 @@ var init_github = __esm(() => {
 // apps/agent/src/agent/wire/mention-scan.ts
 import { readdir as readdir2 } from "fs/promises";
 import { join as join29 } from "path";
+function latestIso(...values2) {
+  let latest = null;
+  for (const value of values2) {
+    if (value && (latest === null || value > latest))
+      latest = value;
+  }
+  return latest;
+}
+function isAlreadyReactedError(err) {
+  const e = err;
+  const text = [...e?.messages ?? [], e?.message ?? ""].join(" ").toLowerCase();
+  return text.includes("conflict on insert of reaction") || text.includes("already exists") || text.includes("already reacted");
+}
 function createMentionScanner(input) {
   const {
     apiKey,
@@ -108555,13 +109139,14 @@ function createMentionScanner(input) {
     for (const issue2 of candidates) {
       const comments = issue2.comments ?? [];
       const lastRalphPickup = findLastRalphPickupISO(comments);
+      const linearMentionGate = latestIso(lastRalphPickup, findLastMentionAckISO(comments));
       if (wantMention) {
         for (const c of comments) {
           if (isRalphComment(c.body))
             continue;
           if (!containsHandle(c.body, handle))
             continue;
-          if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+          if (linearMentionGate && c.createdAt <= linearMentionGate)
             continue;
           out.push({
             issue: issue2,
@@ -108581,7 +109166,9 @@ function createMentionScanner(input) {
               queued.add(issue2.id);
               break;
             }
-            diag("mention", `! mention scan: Linear reaction failed for ${issue2.identifier}: ${formatLinearError(err)}`, "yellow");
+            if (!isAlreadyReactedError(err)) {
+              diag("mention", `! mention scan: Linear reaction failed for ${issue2.identifier}: ${formatLinearError(err)}`, "yellow");
+            }
           }
           if (cfg.linear.postComments !== false) {
             try {
@@ -108605,11 +109192,14 @@ function createMentionScanner(input) {
         continue;
       if (wantMention) {
         const ghComments = await fetchPrIssueComments(cmdRunner, projectRoot, prUrl, onLog);
+        const ghMentionGate = latestIso(lastRalphPickup, findLastMentionAckISO(ghComments));
         const prMatch = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/\d+/.exec(prUrl);
         for (const c of ghComments) {
+          if (isRalphComment(c.body))
+            continue;
           if (!containsHandle(c.body, handle))
             continue;
-          if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+          if (ghMentionGate && c.createdAt <= ghMentionGate)
             continue;
           out.push({
             issue: issue2,
@@ -108626,7 +109216,9 @@ function createMentionScanner(input) {
             try {
               await addGithubReactionToComment(cmdRunner, projectRoot, { owner, repo, kind: "issue" }, c.id, "\uD83D\uDC40");
             } catch (err) {
-              diag("mention", `! mention scan: GitHub reaction failed for ${prUrl}: ${formatLinearError(err)}`, "yellow");
+              if (!isAlreadyReactedError(err)) {
+                diag("mention", `! mention scan: GitHub reaction failed for ${prUrl}: ${formatLinearError(err)}`, "yellow");
+              }
             }
             if (cfg.linear.postComments !== false) {
               await postGithubPrComment(cmdRunner, projectRoot, prUrl, buildMentionAckComment(c.body, c.author), onLog);
@@ -108680,7 +109272,7 @@ var init_mention_scan = __esm(() => {
   init_detections();
   init_scaffold();
   init_scan();
-  init_github();
+  init_github2();
   init_task_bodies();
 });
 
@@ -109688,7 +110280,12 @@ async function readTasksMd(changeDir, log3) {
   }
 }
 function renderTasksCommentBody(tasksMd, changeName, iteration) {
-  return renderTasksBlock(tasksMd, { changeName, iteration });
+  return buildRalphyComment({
+    type: "tasks",
+    action: "task progress",
+    body: renderTasksBlock(tasksMd, { changeName, iteration }),
+    fields: { change: changeName, iter: iteration }
+  });
 }
 async function postOrUpdateTasksComment(deps) {
   const tasksMd = await readTasksMd(deps.changeDir, deps.log);
@@ -109799,8 +110396,13 @@ async function postPlanCommentOnce(deps) {
   if (designSummary) {
     parts.push("", "**Design**", "", designSummary);
   }
-  const body = parts.join(`
-`);
+  const body = buildRalphyComment({
+    type: "plan",
+    action: "plan",
+    body: parts.join(`
+`),
+    fields: { change: deps.changeName }
+  });
   let id;
   try {
     id = await deps.mutations.createIssueComment(deps.apiKey, deps.issueId, body);
@@ -109817,9 +110419,14 @@ async function postPlanCommentOnce(deps) {
 }
 async function postSteeringAndRefreshTasks(deps) {
   const firstLine = deps.message.split(/\r?\n/, 1)[0].trim() || deps.message.trim();
-  const steeringBody = `### ${STEERING_COMMENT_TITLE}
+  const steeringBody = buildRalphyComment({
+    type: "steering",
+    action: "steering",
+    body: `### ${STEERING_COMMENT_TITLE}
 
-${deps.message.trim()}`;
+${deps.message.trim()}`,
+    fields: { change: deps.changeName }
+  });
   try {
     await deps.mutations.createIssueComment(deps.apiKey, deps.issueId, steeringBody);
     deps.log(`  comment-sync: posted steering comment (${firstLine})`, "gray");
@@ -109852,6 +110459,7 @@ ${deps.message.trim()}`;
 var PLAN_COMMENT_TITLE = "\uD83D\uDCCB Ralph plan", STEERING_COMMENT_TITLE = "\uD83E\uDDED Ralph steering";
 var init_comment_sync = __esm(() => {
   init_store();
+  init_src8();
   init_linear_sync();
 });
 
@@ -262718,11 +263326,12 @@ function buildAgentCoordinator(input) {
   };
   const concurrency = args.concurrency || cfg.concurrency;
   const pollInterval = args.pollInterval || cfg.pollIntervalSeconds;
-  const indicators = mergeIndicators(cfg.linear.indicators, args.indicators);
+  const isGithubTracker = cfg.tracker.kind === "github";
+  const indicators = isGithubTracker ? githubIndicators(cfg.github?.issues) : mergeIndicators(cfg.linear.indicators, args.indicators);
   const team = args.linearTeam || cfg.linear.team;
   const { assignee, anyAssignee, requireAllLabels } = resolveLinearFilter(applyAssigneeOverride(cfg.linear.filter, args.linearAssignee));
   const ticketNumbers = resolveTicketNumbers(args.ticketTokens, team);
-  const excludeFromTodo = unionMarkers(indicators.setDone, indicators.setError);
+  const excludeFromTodo = isGithubTracker ? unionMarkers(indicators.setDone, indicators.setError, indicators.setInProgress) : unionMarkers(indicators.setDone, indicators.setError);
   const gitRunner = input.runners?.git ?? bunGitRunner;
   const cmdRunner = input.runners?.cmd ?? bunCmdRunner;
   const cwdByChange = new Map;
@@ -262757,7 +263366,7 @@ function buildAgentCoordinator(input) {
     }
     return code;
   });
-  const resolvers = createLinearResolvers({
+  const resolvers = isGithubTracker ? null : createLinearResolvers({
     apiKey,
     team,
     assignee,
@@ -262766,6 +263375,15 @@ function buildAgentCoordinator(input) {
     diag,
     ...ticketNumbers.length > 0 ? { ticketNumbers } : {}
   });
+  const provider = isGithubTracker ? createGithubTrackerProvider({
+    issues: cfg.github?.issues,
+    cmdRunner,
+    projectRoot,
+    diag
+  }) : {
+    ...resolvers,
+    fetchDoneCandidates: () => fetchDoneCandidatesWith(apiKey, team, assignee, anyAssignee, requireAllLabels, indicators, ticketNumbers.length > 0 ? ticketNumbers : undefined)
+  };
   if (ticketNumbers.length > 0) {
     const hasGetIndicator = [indicators.getTodo, indicators.getInProgress].some((ind) => ind && ind.filter.length > 0);
     if (!hasGetIndicator) {
@@ -262796,7 +263414,7 @@ function buildAgentCoordinator(input) {
     scriptRunner,
     ...input.runners?.worktree ? { worktreeProvider: input.runners.worktree } : {}
   });
-  const fetchMentions = createMentionScanner({
+  const fetchMentions = isGithubTracker ? async () => [] : createMentionScanner({
     apiKey,
     args,
     cfg,
@@ -262816,6 +263434,27 @@ function buildAgentCoordinator(input) {
     lastHandledReviewActivity,
     resolvePrUrlForIssue: prDiscovery.resolvePrUrlForIssue
   });
+  const tracker = isGithubTracker ? {
+    fetchTodo: () => provider.fetchByGet(indicators.getTodo, excludeFromTodo),
+    fetchInProgress: () => provider.fetchByGet(indicators.getInProgress, unionMarkers(indicators.setError)),
+    fetchReview: async () => [],
+    fetchMentions,
+    fetchDoneCandidates: () => provider.fetchDoneCandidates(),
+    applyIndicator: provider.applyIndicator,
+    removeIndicator: provider.removeIndicator,
+    postComment: (issue2, body) => provider.applyMarker(issue2, { type: "comment", value: body }),
+    fetchComments: async () => []
+  } : createLinearTrackerProvider({
+    apiKey,
+    team,
+    assignee,
+    anyAssignee,
+    requireAllLabels,
+    indicators,
+    resolvers,
+    fetchMentions,
+    ...ticketNumbers.length > 0 ? { ticketNumbers } : {}
+  });
   const spawnWorker = createSpawnWorker({
     args,
     cfg,
@@ -262827,7 +263466,7 @@ function buildAgentCoordinator(input) {
     indicators,
     cmdRunner,
     gitRunner,
-    applyIndicator: resolvers.applyIndicator,
+    applyIndicator: provider.applyIndicator,
     bus,
     onLog,
     diag,
@@ -262871,8 +263510,8 @@ function buildAgentCoordinator(input) {
       cwdOf: (cn) => cwdByChange.get(cn),
       awaitingChangeSet,
       reapForAwaiting: (cn) => coordRef.current?.reapForAwaiting(cn),
-      applyIndicator: resolvers.applyIndicator,
-      applyMarker: resolvers.applyMarker,
+      applyIndicator: provider.applyIndicator,
+      applyMarker: provider.applyMarker,
       openDraftPr,
       ...onAwaitingTicket ? { onAwaitingTicket } : {},
       onLog
@@ -262902,7 +263541,7 @@ function buildAgentCoordinator(input) {
     projectRoot,
     maxRecoveryAttempts: cfg.prRecovery.maxRecoverySessions
   }) : null;
-  const commentSync = createCommentSyncHooks({
+  const commentSync = isGithubTracker ? { enabled: false } : createCommentSyncHooks({
     apiKey,
     cfg,
     projectRoot,
@@ -262915,20 +263554,18 @@ function buildAgentCoordinator(input) {
     beforePoll: () => {
       pollContext = new PollContext;
     },
-    fetchTodo: () => resolvers.fetchByGet(indicators.getTodo, excludeFromTodo),
-    fetchInProgress: () => resolvers.fetchByGet(indicators.getInProgress, unionMarkers(indicators.setError)),
-    fetchMentions,
-    fetchDoneCandidates: () => fetchDoneCandidatesWith(apiKey, team, assignee, anyAssignee, requireAllLabels, indicators, ticketNumbers.length > 0 ? ticketNumbers : undefined),
+    fetchTodo: tracker.fetchTodo,
+    fetchInProgress: tracker.fetchInProgress,
+    fetchMentions: tracker.fetchMentions,
+    fetchDoneCandidates: tracker.fetchDoneCandidates,
+    fetchReview: tracker.fetchReview,
     prepare: prep.prepare,
     prepareTaskForTrigger: prep.prepareTaskForTrigger,
     spawnWorker,
-    applyIndicator: resolvers.applyIndicator,
-    removeIndicator: resolvers.removeIndicator,
-    postComment: (issue2, body) => addIssueComment(apiKey, issue2.id, body),
-    fetchComments: async (issueId) => {
-      const c = await fetchIssueComments(apiKey, issueId);
-      return c.map((x2) => ({ body: x2.body }));
-    },
+    applyIndicator: tracker.applyIndicator,
+    removeIndicator: tracker.removeIndicator,
+    postComment: tracker.postComment,
+    fetchComments: tracker.fetchComments,
     checkPrStatus: prDiscovery.checkPrStatus,
     hasPrForChange: (changeName) => prByChange.has(changeName),
     isChangeArchivedForIssue: (issue2) => isChangeArchivedForIssue(issue2, cwdByChange, projectRoot),
@@ -262976,7 +263613,7 @@ function buildAgentCoordinator(input) {
     }
   });
   coordRef.current = coord;
-  const filterDesc = describeIndicators(indicators, team, assignee, anyAssignee);
+  const filterDesc = describeIndicators(indicators, team, assignee, anyAssignee, requireAllLabels);
   const runBaselineGateOnce = createBaselineGateRunner({
     args,
     cfg,
@@ -262987,7 +263624,7 @@ function buildAgentCoordinator(input) {
     gitRunner,
     coord,
     onLog,
-    resolveLabelIdForTeam: resolvers.resolveLabelIdForTeam
+    resolveLabelIdForTeam: provider.resolveLabelIdForTeam
   });
   return {
     coord,
@@ -263015,7 +263652,6 @@ var init_wire = __esm(() => {
   init_workflow();
   init_src2();
   init_coordinator2();
-  init_linear();
   init_layout();
   init_scaffold();
   init_awaiting();
@@ -263024,6 +263660,8 @@ var init_wire = __esm(() => {
   init_indicators();
   init_task_bodies();
   init_linear_resolvers();
+  init_github();
+  init_linear_tracker_provider();
   init_linear_client();
   init_prepare();
   init_pr_discovery();
@@ -266187,7 +266825,7 @@ async function main3(argv) {
   return typeof process.exitCode === "number" ? process.exitCode : 0;
 }
 var import_react64;
-var init_src8 = __esm(async () => {
+var init_src9 = __esm(async () => {
   init_context();
   init_layout();
   init_paths();
@@ -266245,7 +266883,7 @@ async function dispatch(subcommand, rest2) {
     return main4(rest2);
   }
   if (subcommand === "agent") {
-    const { main: main4 } = await init_src8().then(() => exports_src3);
+    const { main: main4 } = await init_src9().then(() => exports_src3);
     return main4(rest2);
   }
   if (subcommand === "task") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neriros/ralphy",
-  "version": "3.10.16",
+  "version": "3.10.17",
   "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   "keywords": [
     "agent",
@@ -51,7 +51,7 @@
     "check:circular:ci": "depcruise packages/*/src apps/*/src --config .dependency-cruiser.cjs",
     "check:unused:ci": "knip",
     "check:outdated:ci": "bun scripts/check-outdated.ts",
-    "check:structure": "bun scripts/check-prop-drilling.ts && bun scripts/check-hooks-location.ts && bun scripts/check-folder-size.ts && bun scripts/check-filename-case.ts && bun scripts/check-single-component.ts && bun scripts/check-no-reexport-tsx.ts && bun scripts/check-test-location.ts && bun scripts/check-static-error-messages.ts && bash scripts/check-no-unsafe-casts.sh",
+    "check:structure": "bun scripts/check-prop-drilling.ts && bun scripts/check-hooks-location.ts && bun scripts/check-folder-size.ts && bun scripts/check-filename-case.ts && bun scripts/check-single-component.ts && bun scripts/check-no-reexport-tsx.ts && bun scripts/check-test-location.ts && bun scripts/check-static-error-messages.ts && bash scripts/check-no-unsafe-casts.sh && bun scripts/check-tracker-seam.ts",
     "check:shell": "bash scripts/check-shell.sh",
     "check:duplicates": "bun scripts/check-duplicate-declarations.ts --diff",
     "check:duplicates:all": "bun scripts/check-duplicate-declarations.ts --all",