feat(cmux): discover a task's full PR stack for stage sync and sidebar

contrib/cmux/README.md

@@ -53,15 +53,36 @@ Settings → Account → Code & reviews.
 ## PR-stage sync (`cmux.prStages`)
 
 Stage sections, the per-row stage badge color, and the gating-label toggles below all depend on
-`crew` (the watch loop's `pr-stage-sync` step) painting each task workspace with `crew_stage` and
-`crew_labels`, gated on the opt-in [`cmux.prStages.enabled`](../../docs/configuration.md) config
-flag — see `node --run crew -- --help` and `docs/configuration.md` in the repository root. Run a
-pass on demand with `crew stage refresh`, or manage the gating labels directly with
-`crew stage label-add`/`crew stage label-remove`.
+`crew` (the watch loop's `pr-stage-sync` step) painting each task workspace with `crew_stage`,
+`crew_labels`, and `crew_prs`, gated on the opt-in
+[`cmux.prStages.enabled`](../../docs/configuration.md) config flag — see `node --run crew -- --help`
+and `docs/configuration.md` in the repository root. Run a pass on demand with `crew stage refresh`,
+or manage the gating labels directly with `crew stage label-add`/`crew stage label-remove`.
 
 `crew_ticket` is written for every matched cmux task workspace regardless of this flag, so the
 ticket pill and `Cleanup workspace` action work whether or not PR-stage sync is enabled.
 
+### Stacked PRs
+
+A task's PRs are every pull request whose head branch is the task's worktree branch, or starts with
+`<branch>-` (how an agent splits one task into a stack). `pr-stage-sync` discovers them with one
+`gh pr list --state all --author @me` call per repository per tick, not per task, scoped to the
+operator's own PRs (who every agent-created PR is authored by) and capped at the 100 most recent to
+keep that call cheap. A task whose PR falls outside that window — too old, or for any other reason
+missing from the repository-wide list — is recovered by one exact-branch `gh pr list --head <branch>`
+fallback call for that task alone, the same lookup `pr-stage-sync` used before stack discovery
+existed. Either way, `pr-stage-sync` shows every open or merged PR for the task, falling back to its
+closed PRs only when none are open or merged. When the shown PRs chain by base branch into a single
+stack, they're ordered bottom to top; otherwise by PR number.
+
+Each shown PR's stage is encoded into the `crew_prs` status, and a row renders one "PR #&lt;n&gt; ·
+&lt;stage&gt;" line per entry instead of cmux's native PR list. `crew_stage` (the row's section) and
+`crew_labels` both describe whichever shown PR is most urgent, ranked by the same order the sections
+render in (`Your review` first, then `CI failing`, `Changes requested`, `Needs testing`,
+`Ready to merge`, CI running, `Peer review`, merged, closed last) — so a stack with one PR needing
+your review and another still in CI shows the review PR's stage and labels. Workspaces without
+`crew_prs` (PR-stage sync off, or no matched PR) keep rendering from cmux's native single-PR data.
+
 When `cmux.prStages` has never run for any tracked task (no workspace carries a
 `crew_poller_heartbeat` status at all), the sidebar assumes the feature is off rather than broken:
 the "PR stages stale — is crew run --watch running?" caption stays hidden, and PR-bearing rows with no
@@ -71,7 +92,10 @@ least once, a missing or outdated heartbeat goes back to meaning "stale" and the
 ### Label toggles
 
 For a task with a PR, the context menu additionally offers (via `crew stage label-add` /
-`crew stage label-remove`, run from the groundcrew checkout and followed by a `crew stage refresh`):
+`crew stage label-remove`, run from the groundcrew checkout and followed by a `crew stage refresh`).
+When `crew_prs` is present, the toggles act on the same stage-driving PR described above — in a
+stack, that's whichever PR is currently most urgent, not always the task's original PR — so
+right-clicking a stack's row walks the stack naturally as PRs move through review:
 
 - `Self-review done` / `Undo self-review` — toggles the `selfReviewed` gating label
 - `Testing done` / `Undo testing` — toggles the `tested` gating label

contrib/cmux/groundcrew.swift

@@ -414,6 +414,70 @@ func hasCrewLabel(_ w, _ label) -> Bool {
   return crewLabelsRaw(w).contains(label)
 }
 
+func crewPrsRaw(_ w) -> String {
+  if let ss = w.statuses {
+    if let entry = ss.first(where: { e in e.key == "crew_prs" }) {
+      return entry.value
+    }
+  }
+  return ""
+}
+
+// One crew_prs entry is "<number>,<stage>,<url>"; a malformed entry (wrong
+// field count, or a non-numeric number) becomes "number": -1 here and is
+// dropped by crewPrEntries's filter, so one bad entry never breaks the rest.
+func parsedPrEntry(_ entry) -> Any {
+  let fields = entry.split(separator: ",")
+  if fields.count != 3 {
+    return ["number": -1, "stage": "", "url": ""]
+  }
+  if let n = Int(fields[0]) {
+    return ["number": n, "stage": fields[1], "url": fields[2]]
+  }
+  return ["number": -1, "stage": "", "url": ""]
+}
+
+// Every shown PR for the task, from the single crew_prs status pr-stage-sync
+// writes — parsed once per row (called from the row-precompute pass below,
+// not from taskRow itself) so re-parsing never happens once per 1s render.
+func crewPrEntries(_ w) -> Array {
+  let raw = crewPrsRaw(w)
+  if raw == "" {
+    return []
+  }
+  return raw.split(separator: ";").map { e in parsedPrEntry(e) }.filter { r in r.number >= 0 }
+}
+
+// The PR driving crew_stage/crew_labels: the first shown entry whose own
+// stage matches the row's crew_stage status. Falls back to the row's native
+// w.pr when crew_prs is absent (cmux.prStages off, or no PRs at all), so the
+// context-menu label toggles keep working exactly as before this feature.
+func menuPrUrl(_ w, _ prEntries) -> String {
+  let slug = crewStageSlug(w)
+  if slug != "" {
+    if let match = prEntries.first(where: { e in e.stage == slug }) {
+      return match.url
+    }
+  }
+  if let pr = w.pr {
+    return pr.url
+  }
+  return ""
+}
+
+func prStageLabel(_ slug) -> String {
+  if slug == "my_review" { return "Your review" }
+  if slug == "ci_failing" { return "CI failing" }
+  if slug == "ci_running" { return "CI running" }
+  if slug == "changes_requested" { return "Changes requested" }
+  if slug == "needs_testing" { return "Needs testing" }
+  if slug == "ready_to_merge" { return "Ready to merge" }
+  if slug == "peer_review" { return "Peer review" }
+  if slug == "merged" { return "Merged" }
+  if slug == "closed" { return "Closed" }
+  return slug
+}
+
 // Raw existence checks, not identity: whether ANY agent record (including an
 // abandoned duplicate) reports the state, which is what the stage decision
 // needs. Cheaper than distinctAgents (no pid-dedup pass) and behaves the same
@@ -578,6 +642,8 @@ func taskRow(_ r, _ now, _ pulse) -> some View {
   let ticket = r.ticket
   let task = ticket.lowercased()
   let liveAgents = r.agents
+  let prEntries = r.prEntries
+  let rowMenuPrUrl = r.menuPrUrl
   let hasTicketPill = ticket != ""
   HStack(spacing: 0) {
     Rectangle().fill(color).frame(width: 3)
@@ -606,7 +672,16 @@ func taskRow(_ r, _ now, _ pulse) -> some View {
             }
           }
         }
-        if let prs = w.prs {
+        if prEntries.count > 0 {
+          ForEach(prEntries) { entry in
+            Button(action: { openURL(prLink(["url": entry.url])) }) {
+              HStack(spacing: 4) {
+                Image(systemName: "arrow.triangle.branch")
+                Text("PR #" + String(entry.number) + " · " + prStageLabel(entry.stage)).font(.caption)
+              }
+            }
+          }
+        } else if let prs = w.prs {
           ForEach(prs) { pr in
             Button(action: { openURL(prLink(pr)) }) {
               HStack(spacing: 4) {
@@ -635,24 +710,24 @@ func taskRow(_ r, _ now, _ pulse) -> some View {
         Label("Cleanup workspace", systemImage: "trash")
       }
     }
-    if let pr = w.pr {
-      if isSafePrUrl(pr.url) {
+    if rowMenuPrUrl != "" {
+      if isSafePrUrl(rowMenuPrUrl) {
         Divider()
         if hasCrewLabel(w, "self-reviewed") {
-          Button(action: { cmux("workspace.create", initial_command: labelToggleCommand(pr.url, "self-reviewed", false), cwd: crewStagesCwd(), focus: false) }) {
+          Button(action: { cmux("workspace.create", initial_command: labelToggleCommand(rowMenuPrUrl, "self-reviewed", false), cwd: crewStagesCwd(), focus: false) }) {
             Label("Undo self-review", systemImage: "eye.slash")
           }
         } else {
-          Button(action: { cmux("workspace.create", initial_command: labelToggleCommand(pr.url, "self-reviewed", true), cwd: crewStagesCwd(), focus: false) }) {
+          Button(action: { cmux("workspace.create", initial_command: labelToggleCommand(rowMenuPrUrl, "self-reviewed", true), cwd: crewStagesCwd(), focus: false) }) {
             Label("Self-review done", systemImage: "eye")
           }
         }
         if hasCrewLabel(w, "tested") {
-          Button(action: { cmux("workspace.create", initial_command: labelToggleCommand(pr.url, "tested", false), cwd: crewStagesCwd(), focus: false) }) {
+          Button(action: { cmux("workspace.create", initial_command: labelToggleCommand(rowMenuPrUrl, "tested", false), cwd: crewStagesCwd(), focus: false) }) {
             Label("Undo testing", systemImage: "checkmark.circle")
           }
         } else {
-          Button(action: { cmux("workspace.create", initial_command: labelToggleCommand(pr.url, "tested", true), cwd: crewStagesCwd(), focus: false) }) {
+          Button(action: { cmux("workspace.create", initial_command: labelToggleCommand(rowMenuPrUrl, "tested", true), cwd: crewStagesCwd(), focus: false) }) {
             Label("Testing done", systemImage: "checkmark.circle.fill")
           }
         }
@@ -736,7 +811,11 @@ VStack(alignment: .leading, spacing: 8) {
   let rows = tasks.map { w in
     let liveAgents = liveAgentsOf(w, now)
     let stage = rowStage(w, liveAgents, now, stagesFresh)
-    ["w": w, "color": stageBadgeColor(stage), "stage": stage, "ticket": crewTicket(w), "agents": liveAgents]
+    let prEntries = crewPrEntries(w)
+    [
+      "w": w, "color": stageBadgeColor(stage), "stage": stage, "ticket": crewTicket(w),
+      "agents": liveAgents, "prEntries": prEntries, "menuPrUrl": menuPrUrl(w, prEntries),
+    ]
   }
 
   let needsYou = rows.filter { r in r.stage == "needs_you" }

contrib/cmux/tests/GroundcrewSidebarRowLayoutTests.swift

@@ -32,6 +32,10 @@ import Testing
         statusEntry(key: "crew_stage", value: slug, priority: -10)
     }
 
+    private func crewPrs(_ entries: String) -> SwiftValue {
+        statusEntry(key: "crew_prs", value: entries, priority: -14)
+    }
+
     private func pr(url: String, number: Int = 406, status: String = "open") -> SwiftValue {
         .object(["number": .int(number), "status": .string(status), "url": .string(url)])
     }
@@ -269,6 +273,34 @@ import Testing
         #expect(!rendered.contains("·"))
     }
 
+    @Test func rendersCrewPrsEntriesInsteadOfNativePrsWhenPresent() throws {
+        guard try source() != nil else { return }
+        let w = workspace(
+            ticket: "TG-8013",
+            statuses: [
+                crewPrs(
+                    "6195,merged,https://github.com/clipboard-health/clipboard-health/pull/6195;"
+                        + "6196,my_review,https://github.com/clipboard-health/clipboard-health/pull/6196"
+                )
+            ],
+            prs: [pr(url: "https://github.com/clipboard-health/groundcrew/pull/1", number: 1)]
+        )
+        let rendered = texts(try render([w]))
+        #expect(rendered.contains("PR #6195 · Merged"))
+        #expect(rendered.contains("PR #6196 · Your review"))
+        #expect(!rendered.contains { $0.hasPrefix("PR #1 ") })
+    }
+
+    @Test func fallsBackToNativePrsWhenCrewPrsIsAbsent() throws {
+        guard try source() != nil else { return }
+        let w = workspace(
+            ticket: "TG-8014",
+            prs: [pr(url: "https://github.com/clipboard-health/groundcrew/pull/2", number: 2, status: "open")]
+        )
+        let rendered = texts(try render([w]))
+        #expect(rendered.contains("PR #2 · open"))
+    }
+
     @Test func captionLineOmitsMissingTicketPill() throws {
         guard try source() != nil else { return }
         let w = workspace(ticket: "", pr: pr(url: "https://github.com/clipboard-health/groundcrew/pull/8010"))

contrib/cmux/tests/GroundcrewSidebarStageTests.swift

@@ -44,6 +44,10 @@ import Testing
         statusEntry(key: "crew_labels", value: labels, priority: -13)
     }
 
+    private func crewPrs(_ entries: String) -> SwiftValue {
+        statusEntry(key: "crew_prs", value: entries, priority: -14)
+    }
+
     private func pr(url: String, number: Int = 406, status: String = "open") -> SwiftValue {
         .object(["number": .int(number), "status": .string(status), "url": .string(url)])
     }
@@ -447,6 +451,28 @@ import Testing
         #expect(!initialCommands.contains { $0.contains("label-add") && $0.contains(" tested") })
     }
 
+    /// In a stack, the toggles must follow crew_stage's own PR — not the
+    /// workspace's native (checked-out) PR, which may be a different entry
+    /// in the stack entirely once the driving PR moves to a later one.
+    @Test func labelToggleActsOnTheStackDrivingPrWhenCrewPrsIsPresent() throws {
+        guard try source() != nil else { return }
+        let nativeUrl = "https://github.com/clipboard-health/clipboard-health/pull/6195"
+        let drivingUrl = "https://github.com/clipboard-health/clipboard-health/pull/6196"
+        let w = workspace(
+            ticket: "TG-4829",
+            statuses: [
+                crewStage("my_review"),
+                crewLabels(""),
+                crewPrs("6195,ci_failing,\(nativeUrl);6196,my_review,\(drivingUrl)"),
+            ],
+            pr: pr(url: nativeUrl, number: 6195)
+        )
+        let commands = cmuxCommands(try render([w]))
+        let initialCommands = commands.compactMap { $0.params["initial_command"] }
+        #expect(initialCommands.contains { $0.contains("label-add") && $0.contains("self-reviewed") && $0.contains(drivingUrl) })
+        #expect(!initialCommands.contains { $0.contains(nativeUrl) })
+    }
+
     @Test func refreshStagesActionOffersOnAnyPrBearingRow() throws {
         guard try source() != nil else { return }
         let url = "https://github.com/clipboard-health/groundcrew/pull/7005"