--- status: draft created: 2026-08-11 owner: tbd --- # GitLab MR Status Chip ## Why A task whose work lives on GitHub shows its pull request's CI, review and automation state as a chip in the chat status bar, so the user sees it without leaving the conversation. A task whose work lives on GitLab shows nothing there. GitLab users have to look up at the topbar button, or open the MR detail panel, to answer "did my pipeline pass". The GitLab merge-request equivalent of that chip does not exist. ## What - A task with at least one **open** linked GitLab merge request SHALL render an `MRStatusChip` in the chat status bar and in the passthrough status row, beside the existing GitHub and Azure DevOps chips. - The chip SHALL show, at a glance: a GitLab merge glyph, a status glyph whose colour matches the MR's existing status colour everywhere else in the product, an MR count when more than one open MR is linked, and auto-fix / auto-merge badges when task MR automation is enabled. - Hovering the chip on a fine-pointer device SHALL open the existing `MRCIPopover` body (pass rate, pipeline stage groups, approval row, unresolved discussions, automation controls, merge action, footer). Tapping it on a coarse-pointer device SHALL open that same body inside a bottom-sheet drawer. - The chip SHALL derive its status from the one shared GitLab MR status derivation, not a new private copy. `getMRStatusColor` in `apps/web/components/gitlab/mr-task-icon.tsx` remains the single source of MR status colour, and its output for every input SHALL be byte-identical before and after this feature. - The chip SHALL NOT own any recurring fetch, polling, cache-warming or background-sync responsibility. It issues exactly **four** kinds of request, all of them existing behaviour it inherits rather than invents: 1. the lazy read of the task's MR automation options, on mount; 2. the GitLab connection-status read that `useGitLabAvailable()` performs on mount, which the chip needs to source `canLink`. This one has a cross-surface side effect and is stated in full under Sync and freshness; 3. the MR feedback read that `MRCIPopover` already owns, **only while a disclosure is open** (this is what the popover's `enabled` prop gates; see API surface); 4. the link and unlink the user explicitly triggers. Nothing else: no polling, no interval, no warmer, and specifically no `useWorkspaceMRs`. See Sync and freshness. - No file under `apps/web/components/github/` changes. `PRStatusChip`'s rendered output SHALL be identical before and after. - All chip copy SHALL go through `t()` into `apps/web/src/locales/en/gitlab.json`, including accessible labels. ## Data model No new persistent state. The chip reads the existing `TaskMR` rows (`gitlab_task_mrs`, typed at `apps/web/lib/types/gitlab.ts`) already cached in the store at `taskMRs.byWorkspaceId[workspaceId][taskId]`, and the existing `TaskMRAutomationOptions` cached at `taskMRAutomation.byTaskId[taskId]`. Fields the chip's own status derivation reads, and only these: | Field | Type | Used for | |---|---|---| | `id` | string | React key, unlink target, final selection tiebreak | | `state` | `open \| closed \| merged \| locked \| string` | terminal filtering, `merged` / `closed` status | | `pipeline_state` | `"" \| success \| failure \| pending \| string` | `failed` / `ready` / `running` status | | `approval_state` | `"" \| approved \| pending \| string` | `ready` / `awaiting_approval` status | | `draft` | boolean | `draft` status | | `mr_iid` | number | display, `data-mr-iid`, primary selection tiebreak | | `project_path` | string | secondary selection tiebreak, automation-state lookup | | `repository_id` | string? | automation-state lookup | The chip SHALL NOT read `unresolved_discussions` for status. That field is documented as populated only for automation-subscribed MRs, so using it would make the chip report a different status for two otherwise identical MRs depending on whether automation happens to be on. The popover body's own live discussion fetch continues to render the unresolved count, unchanged. The chip SHALL NOT read `merge_status` / `detailed_merge_status` for status. See Out of scope. Separately from status, the trigger's `data-mr-ready-to-merge` attribute and the popover's merge button both come from the existing `isMRReadyToMerge`, which does read `unresolved_discussions` and `detailed_merge_status` by design and carries its own documented rationale. That helper is reused unchanged; the restriction above applies to chip status only, and the two must not be reconciled by editing `isMRReadyToMerge`. ## API surface No new endpoints, no new store actions, no new WS events. Consumed, all existing: - `useTaskMRs(taskId)` (`apps/web/hooks/domains/gitlab/use-task-mr.ts`) for the linked MR list. - `useGitLabAvailable()` for whether "link another merge request" is offered. - `useTaskMRAutomationOptions(taskId)` (`apps/web/hooks/domains/gitlab/use-task-mr-automation.ts`) for automation flags and `mr_states`. - `findMRAutomationStateForMR` / `autoFixRoundForState` (`apps/web/lib/gitlab/mr-automation.ts`) for round badges. - `MRCIPopover` (`apps/web/components/gitlab/mr-ci-popover.tsx`) as the popover and drawer body, reused as-is with no new variant and no signature change. Its full prop contract is specified below; every prop it declares gets a named source, because one of them (`enabled`) decides whether the chip fetches. - `TaskMRLinkDialog` (`apps/web/components/gitlab/task-mr-link-dialog.tsx`) for the link flow, with its existing `{open, onOpenChange, taskId, workspaceId, taskRepositories, repositories}` signature unchanged. - `DELETE` task-MR association via `deleteTaskMR` + the `removeTaskMR` store action, for the unlink control the popover header already renders. ### `MRCIPopover` prop contract `MRCIPopover`'s declared signature is `{mr, taskId, enabled, canLink, onOpenDetailPanel?, onLink, onUnlink}`. The chip supplies every one of them from a named source: | Prop | Type | Source | |---|---|---| | `mr` | `TaskMR` | the **acted-on** MR: the live selected MR while the disclosure is closed, the frozen MR while it is open. Always the live store row for that id, never a snapshot. See Selection and ordering. | | `taskId` | `string` | the chip's own `taskId` | | `enabled` | `boolean` | **the chip's own disclosure-open state** (`popoverOpen` for the hover variant, `drawerOpen` for the drawer variant). `false` whenever the disclosure is closed. | | `canLink` | `boolean` | `useGitLabAvailable()` | | `onOpenDetailPanel` | `(() => void)?` | **omitted.** See Out of scope; the popover title then renders as static text. | | `onLink` | `() => void` | opens this chip's own `TaskMRLinkDialog`. See Link and unlink from the chip. | | `onUnlink` | `() => void` | a zero-argument closure that calls `useUnlinkTaskMR(workspaceId)` with the **acted-on MR's association `id`** captured from the enclosing render. See Link and unlink from the chip. | **`enabled` is the load-bearing one.** `MRCIPopover` gates its live MR feedback read on it (`useMRFeedbackGated(mr, enabled)`), which is the only reason the "only network effect" clause in What can be stated at all. `MRTopbarButton` passes `enabled={popoverOpen}` and the chip SHALL do the same for its own disclosure. Passing a constant `true` is specifically forbidden: it would make every mounted chip fetch MR feedback on mount, for every session view with a linked open MR, and the What clause would be false. Note the arity: the component declares `onUnlink: () => void`, not `onUnlink(associationId)`. The association id is closed over, not passed as an argument, and which id gets closed over is fixed by the freeze rule rather than left to the call site. New exported helpers in `apps/web/components/gitlab/mr-task-icon.tsx` alongside `getMRStatusColor` (the file the repo already designates as the single source of GitLab MR status): ``` type MRChipStatus = | "merged" | "closed" | "failed" | "draft" | "ready" | "awaiting_approval" | "running" | "neutral" mrChipStatus(mr: TaskMR): MRChipStatus selectChipMR(mrs: TaskMR[]): TaskMR | null aggregateMRChipStatus(mrs: TaskMR[]): MRChipStatus ``` `getMRStatusColor(mr)` SHALL be re-expressed as a lookup from `mrChipStatus(mr)`, so exactly one priority table exists. `aggregateMRChipStatus(mrs)` SHALL be defined as the composition `mrChipStatus(selectChipMR(mrs))`, returning `neutral` when `selectChipMR` returns null. It is not an independent derivation and SHALL NOT have a tiebreak rule of its own. This is what makes the trigger internally consistent: the status the chip reports is, by construction, the status of the MR the chip identifies and acts on. See Selection and ordering. One extraction, in `apps/web/hooks/domains/gitlab/use-task-mr.ts` alongside the other task-MR hooks: ``` useUnlinkTaskMR(workspaceId: string): (associationId: string) => Promise ``` This is the unlink closure that today lives privately inside `MRTopbarButton` (`deleteTaskMR` -> `removeTaskMR`, error toast using the existing `gitlab:failedToUnlinkMergeRequest` and `gitlab:theMergeRequestIsStillLinked` keys), moved verbatim. Both `MRTopbarButton` and the chip SHALL call it, and `MRTopbarButton`'s observable unlink behaviour SHALL be unchanged. The chip SHALL NOT re-implement the closure: `apps/web/eslint.config.mjs` forbids identical functions and 4+ duplicated strings, so a second copy is a lint failure, not a style preference. New testids, forming the chip's observable contract: | testid | Element | |---|---| | `mr-status-chip` | the trigger button (both single and multi) | | `mr-status-chip-drawer` | coarse-pointer drawer content | | `mr-status-chip-drawer-close` | drawer close button | | `mr-status-auto-fix-chip` | auto-fix round badge | | `mr-status-auto-merge-chip` | auto-merge badge | | `mr-status-glyph` | the status glyph, carrying `data-status` | Trigger attributes, and which MR each one describes. This distinction is load-bearing while the disclosure is open; see Selection and ordering. | Attribute | Value | Which MR | |---|---|---| | `data-status` | the `MRChipStatus` | the **live** selected MR, always | | `data-mr-count` | number of **open** linked MRs | n/a | | `data-mr-iid` | `mr_iid` | the **acted-on** MR | | `data-mr-state` | `state` | the **acted-on** MR | | `data-mr-ready-to-merge` | `"true"` / `"false"` from the existing `isMRReadyToMerge` | the **acted-on** MR | | `data-selection-frozen` | `"true"` while the disclosure is open, `"false"` otherwise | n/a | The **acted-on MR** is the live selected MR while the disclosure is closed, and the frozen MR while it is open. `data-selection-frozen` exists so that the two regimes are distinguishable from the DOM rather than inferred; without it a test cannot tell a frozen attribute from a stale one. All three per-MR attributes switch regime together, so they always describe the same single MR as each other and as the popover body. `data-mr-ready-to-merge` is present on the single and the multi trigger alike, always describing the acted-on MR. This is a deliberate divergence from `PRStatusChip`, whose multi trigger omits the attribute: GitLab's chip always has exactly one acted-on MR, because it has no multi-MR surface, so there is always a well-defined MR for the attribute to describe. Badge attributes. These sit on `mr-status-auto-fix-chip`, not on the trigger, and they complete the observable contract — the tables above are the full attribute inventory and nothing outside them is asserted by an AC: | Attribute | Element | Value | Which MR | |---|---|---|---| | `data-auto-fix-exhausted` | `mr-status-auto-fix-chip` | `"true"` / `"false"`, from `autoFixRoundForState(...).exhausted` | the **badge-selected** MR | The **badge-selected MR** is a third selection, distinct from both the live and the frozen selection: it is the most attention-worthy auto-fix round across the open MRs (exhausted beats non-exhausted, then higher `current`, then the same `mr_iid` / `project_path` / `id` order — see Selection and ordering). On a single-MR chip all three coincide. On a multi-MR chip they need not. ## State machine `mrChipStatus(mr)` is a total function evaluated in this exact priority order, first match wins. The colour column is what `getMRStatusColor` returns for that MR today and MUST continue to return. | # | Status | Condition | Colour | Glyph | |---|---|---|---|---| | 1 | `merged` | `state === "merged"` | `text-purple-500` | filled merge glyph | | 2 | `closed` | `state === "closed"` or `state === "locked"` | `text-muted-foreground` | filled dot | | 3 | `failed` | `pipeline_state === "failure"` | `text-red-500` | filled circle-X | | 4 | `draft` | `draft === true` | `text-muted-foreground` | filled dot | | 5 | `ready` | `approval_state === "approved"` and `pipeline_state === "success"` | `text-emerald-400` | filled circle-check | | 6 | `awaiting_approval` | `approval_state === "pending"` | `text-sky-400` | clock | | 7 | `running` | `pipeline_state === "pending"` | `text-yellow-500` | spinner, 3s per rotation | | 8 | `neutral` | otherwise | `text-muted-foreground` | filled dot | The ordering is deliberate and load-bearing. Stated exactly, because the neighbouring rows are easy to get backwards: - A failed pipeline outranks `draft` (row 3 before row 4), so a draft MR whose pipeline broke reads `failed`, not `draft`. - `ready` requires **both** an approved review and a succeeded pipeline (row 5). - A pending approval outranks a running pipeline (row 6 before row 7). Row 6 carries **no pipeline condition at all**: an MR with `approval_state: "pending"` and `pipeline_state: "pending"` is `awaiting_approval`, not `running`. This is exactly the order `getMRStatusColor` already evaluates, row for row. The refactor SHALL NOT reorder it, and where this prose and the table above could be read as disagreeing, the table governs. ### Rank, and why aggregation has no tiebreak of its own `MR_CHIP_STATUS_RANK` orders the statuses by how much attention they deserve: | Status | Rank | |---|---| | `failed` | 5 | | `running` | 4 | | `awaiting_approval` | 3 | | `ready` | 2 | | `merged` | 0 | | `closed` | 0 | | `draft` | 0 | | `neutral` | 0 | Four statuses share rank 0, so **rank alone does not identify a winner**. The chip therefore never aggregates by rank directly. `aggregateMRChipStatus(mrs)` is defined as `mrChipStatus(selectChipMR(mrs))` (`neutral` when `selectChipMR` returns null), and `selectChipMR` breaks every tie by named field. Two consequences, both intended: 1. There is no rank-tie ambiguity to resolve, because ties are resolved on MRs by `mr_iid` / `project_path` / `id`, not on statuses. 2. The trigger's `data-status` cannot disagree with its `data-mr-iid` **while `data-selection-frozen` is `"false"`**: the reported status is read off the identified MR. This qualifier is load-bearing and is not a hedge. While a disclosure is open the freeze rule deliberately holds `data-mr-iid` on the frozen MR while `data-status` keeps tracking the live selection, so the two may name different MRs for exactly that window. See "Freezing while the disclosure is open", which governs. A test asserting the invariant SHALL scope itself to `data-selection-frozen="false"`. **`aggregateMRStatusColor` is NOT re-expressed and its body SHALL NOT be touched.** This is a deliberate decision, not an omission: - Its existing loop (`bestRank = -1`, strict `>` over colour ranks) is **first-in-input-order wins** on a tie, so `[merged, closed]` returns purple while `[closed, merged]` returns muted. That array-order dependence is observable today on the multi-MR kanban badge. - The chip requires the opposite property: a selection that does not depend on array order. The two cannot share one implementation without either changing `aggregateMRStatusColor`'s output for all-terminal lists, or importing array ordering into the chip. - Changing that behaviour is re-tuning the GitLab MR colour priority, which this spec already excludes (see Out of scope). Leaving the function byte-identical makes the mandated parity scenario a regression guard rather than a coin flip. `MR_CHIP_STATUS_RANK` and the existing colour-keyed `STATUS_RANK` therefore remain two separate tables, keyed on different things and serving different callers. They are not permitted to drift: a test SHALL assert they are **order-equivalent** under the status-to-colour map from the table above, i.e. for any two statuses `a` and `b`, `MR_CHIP_STATUS_RANK[a] < MR_CHIP_STATUS_RANK[b]` if and only if `STATUS_RANK[colour(a)] < STATUS_RANK[colour(b)]`. The single-derivation invariant this spec protects is the **priority table** (`mrChipStatus`, which `getMRStatusColor` now reads from); it was never a claim that one rank table serves both callers. ## Selection and ordering The chip renders one MR inside its popover even when several are linked. That MR is the **selected MR**, `selectChipMR(mrs)`, chosen deterministically: 1. Restrict to open MRs (the chip only renders when at least one exists). If none are open, return null. **"Open" means `state === "open"` exactly.** It is a positive equality test, never "not one of the terminal states". `TaskMR.state` is typed `open | closed | merged | locked | string`, so the two readings diverge for `locked` and for any unrecognised string the backend may emit: under the equality test a locked MR is not selectable and does not count toward `data-mr-count`, and an unknown state behaves the same way. This matches the test `aggregateMRStatusColor` and `isMRReadyToMerge` already apply, so all three agree on what "open" means. A consequence worth stating: rows 1 and 2 of the status table (`merged`, `closed`) are therefore unreachable through `selectChipMR`, and remain live only for `getMRStatusColor`'s other callers and for the rank-parity test. 2. Keep those whose `mrChipStatus` has the maximum `MR_CHIP_STATUS_RANK`. 3. Tiebreak, in order, by **`mr_iid` ascending**, then **`project_path` ascending** (byte-wise, `<`), then **`id` ascending**. `id` is the association primary key, so the ordering is total and the selection is unique for any input. Array position is explicitly NOT the tiebreak. The store's array order comes from the backend response order and is not a stable, named property. (This rule governs the chip only. It does not apply to `aggregateMRStatusColor`, which keeps its existing array-order behaviour untouched; see State machine.) ### Freezing while the disclosure is open **Selection is frozen while the popover or drawer is open.** The popover carries destructive and irreversible actions (unlink, merge), and an action target that swaps under the pointer mid-interaction is a hazard the aggregate status is not worth. What is captured is the **association `id` only, never a copy of the `TaskMR` object.** The popover body renders the live store row for that id on every render. So while frozen: - Which MR the popover acts on does not change. - That MR's own fields DO stay live: a pipeline that goes from pending to failed while the popover is open updates the body, and `isMRReadyToMerge` and the merge button are evaluated against current data, never a snapshot taken at open. Merging or unlinking on stale fields is the failure this rule exists to prevent, so a value snapshot is specifically forbidden. - The trigger's `data-mr-iid`, `data-mr-state` and `data-mr-ready-to-merge` describe the frozen MR, and `data-selection-frozen` is `"true"`. - The trigger's `data-status` and glyph continue to track the **live** selected MR, so a change on a different MR is still visible at a glance. This is the one window in which `data-status` and `data-mr-iid` may describe different MRs; it is bounded by `data-selection-frozen="true"` and is the deliberate cost of not swapping the action target. - **The automation badges do NOT freeze.** `mr-status-auto-fix-chip` (its text and its `data-auto-fix-exhausted`) and `mr-status-auto-merge-chip` continue to track the live badge-selected MR, on the same side of the line as `data-status` and the glyph. The rule that decides this is what each surface is *for*, not which MR it happens to name. The freeze exists to stop an **action target** moving under the pointer: unlink and merge are destructive, so the MR they operate on is pinned. The badges are **informational** — nothing in the popover acts on the badge-selected MR, and no control's meaning changes when the badge changes. A frozen badge would instead hide exactly the event it exists to report: an MR exhausting its auto-fix rounds while the user has the popover open. This means a multi-MR chip may briefly show three different MRs at once — `data-mr-iid` (frozen, acted-on), `data-status` (live selection), and the badge (live badge-selection). That is accepted and is bounded by `data-selection-frozen="true"`. It is not a new hazard: none of the three is an action target except the frozen one, which is the whole point. If the held `id` leaves the store, or its row stops being open, the popover or drawer closes. On close the freeze is released and all attributes return to the live selection in the same render. DOM ordering inside both status rows SHALL be: `PRStatusChip`, then `MRStatusChip`, then `AzureDevOpsTaskPullRequestChip`, then the existing banners and right-hand controls. This matches the topbar's existing `PRTopbarButton` then `MRTopbarButton` provider order, so a task linked to both a PR and an MR presents the two providers in the same order in both places. Both chips render; neither suppresses the other. How each leg of that ordering is verified differs, and the difference is deliberate. The `PRStatusChip` -> `MRStatusChip` leg has an AC, because both elements carry testids. The `MRStatusChip` -> `AzureDevOpsTaskPullRequestChip` leg has **no AC** and is a source-order requirement checked by reading the two mount points. The reason is a choice, not an impossibility, and an earlier draft overstated it. It is true that the Azure chip exposes no `data-testid` and that adding one is outside this card's permitted files. It does **not** follow that the leg is unobservable: the chip renders a link whose `aria-label` is a hardcoded, untranslated `` `Azure PR ${pullRequestId}: ...` ``, inside rows that do carry testids, so a role-and-name locator could reach it without touching any Azure file. This spec still declines to assert on it, for a different and narrower reason: that label is an implementation detail of a component this card is forbidden to modify, so an AC built on it could be broken by an unrelated Azure change that this card's owner would be unable to fix. Coupling our ACs to another team's untranslated internal string buys less than it costs. See Scenarios. The auto-fix round shown on a multi-MR chip is the most attention-worthy round across the open MRs: an exhausted round beats a non-exhausted one, then a higher `current` wins, and remaining ties resolve by the same `mr_iid` / `project_path` / `id` order above. ## Link and unlink from the chip `MRCIPopover` requires both `onLink` and `onUnlink`. What activating them does is part of this contract, not an implementation detail. **`onUnlink`** — a zero-argument closure over the acted-on MR's association `id`, matching `MRCIPopover`'s declared `onUnlink: () => void`. It calls the extracted `useUnlinkTaskMR(workspaceId)` described under API surface, passing the id it closed over. (An earlier draft wrote this heading as `onUnlink(associationId)`, which is the exact form the prop contract above says is wrong; the prop contract governs.) Behaviour is the topbar's, unchanged: on success the row leaves the store; on failure an error toast is shown and the row stays. **`onLink()`** opens the existing `TaskMRLinkDialog`, which the chip mounts itself as a sibling of its trigger. Its props come from the same places `MRTopbarButton` sources them: | Prop | Source | |---|---| | `open` | the chip's own dialog open state, which it owns per mounted instance | | `onOpenChange` | sets that same state | | `taskId` | the chip's own `taskId` | | `workspaceId` | the active workspace | | `taskRepositories` | `useTaskById(taskId)?.repositories`, defaulting to a module-level shared empty array | | `repositories` | `state.repositories.itemsByWorkspaceId[workspaceId]`, defaulting to a module-level shared empty array | Both defaults MUST be module-level constants, not a fresh `[]` per render, or the dialog re-renders on every parent render. Both props are required and non-nullable on `TaskMRLinkDialog`, and the workspace bucket can legitimately be absent before repositories hydrate, so the fallback is reachable rather than defensive. A dialog opened with an empty `repositories` list is the existing component's own behaviour and this spec does not change it. Ordering when the user activates "link another merge request": 1. The chip closes its own disclosure (popover or drawer) first. 2. Then `TaskMRLinkDialog` opens. Closing first is required, not cosmetic: the drawer variant is itself a focus-trapping dialog, and opening a second one inside it strands focus. The dialog's own lifecycle is unchanged, so a successful link adds the association to the store and the chip re-renders with the new MR in its input; if that MR outranks the current selection the trigger updates, subject to the freeze rule only while a disclosure is open, which by step 1 it is not. Each mounted chip owns its own dialog instance and its own open state, like its disclosure. Two chips mounted at once therefore have two dialog instances, both closed until the user activates link on one of them; activating it opens only that chip's dialog. The dialog is idempotent with respect to which chip opened it, because both pass the same `taskId` and `workspaceId`. **The dialog does not outlive its chip.** Because each chip mounts its own dialog as a sibling of its trigger, a chip that unmounts takes its dialog with it. So if the task's last open MR is unlinked from another surface, or goes terminal, while this chip's link dialog is open, the dialog unmounts mid-edit and any URL the user had typed is lost. That is the accepted behaviour, not an oversight: the alternative is hoisting the dialog above the chip's own render gate, which would leave a dialog on screen belonging to a chip that no longer exists. The window is small (it needs a concurrent change on another surface) and the user can reopen the dialog from `MRTopbarButton`, which is not gated on an open MR existing. ## Failure modes - **Task MR list never hydrated.** `useTaskMRs` returns the shared empty array and the chip renders nothing. There is no skeleton and no loading state: an absent chip and a not-yet-fetched chip are indistinguishable by design, which is the same contract `PRStatusChip` and `MRTaskIcon` already have. - **Store holds a non-array value for the task** (possible during partial hydration). The chip guards with `Array.isArray` and renders nothing, matching `MRTaskIcon` and `PRStatusChip`. - **No active workspace, or `taskId` is null.** The chip renders nothing. - **Popover feedback fetch fails.** `useMRFeedback` already resolves with partial data and an error string; the popover degrades exactly as it does from the topbar button. The chip's own trigger status is unaffected, because it is derived from `TaskMR` fields rather than from the feedback response. - **Unlink fails.** The existing behaviour is preserved: an error toast is shown and the association stays in the store. A successful unlink removes the row; if that was the task's last open MR the chip unmounts on the next render. - **Two surfaces unlink the same association.** The chip and the topbar read the same store row. Whichever request succeeds first removes the row; the other surface's request fails and toasts. The end state is identical either way, so the outcome does not depend on ordering. The chip does not retry. - **An open MR transitions to merged/closed while its popover is open.** On the next store update the chip re-evaluates. If the transitioned MR is the frozen one, the popover or drawer closes; if another open MR remains the trigger re-selects it, and if none does the chip unmounts. No stale MR is left rendered either way. - **The GitLab connection status has not resolved yet.** `useGitLabAvailable()` returns `false` until the mount-time `fetchGitLabStatus` resolves (and it actively clears any cached value first — see Sync and freshness). So `canLink` is `false` on the chip's first render and may become `true` a moment later **without a remount**. The chip SHALL treat this as ordinary prop change, not as a terminal "GitLab unavailable" state: it renders normally, and the popover's link control simply appears when the status resolves. The chip SHALL NOT cache the first value, gate its own render on it, or show an error. If the status request fails, `useGitLabStatus` stores `null`, `canLink` stays `false`, and the popover renders without the link control — the same as a workspace with GitLab genuinely not configured, which is the existing behaviour of every other consumer. - **The automation-options fetch fails.** `useTaskMRAutomationOptions` stores the error and its lazy effect is gated on `error`, so it does not retry for the life of the mount. The chip treats this exactly as options-not-loaded: status glyph renders, no badges, no error text and no retry affordance on the chip itself. The topbar's `MRAutomationControls` remains the surface that reports and retries automation errors. ## Sync and freshness (explicit non-responsibility) GitHub's `PRStatusChip` is load-bearing for refresh. It calls `usePRFeedbackBackgroundSync`, and `pr-topbar-button.tsx:162` documents the topbar button relying on the chip being mounted for that warming. GitLab's refresh does not work that way and this chip SHALL NOT copy the responsibility: - MR list hydration is a one-shot `useWorkspaceMRs(workspaceId)` fetch whose "already fetched" guard is a per-hook-instance ref, so each additional call site issues its own `GET /task-mrs` per workspace. There are already **four** production call sites, and the chip SHALL NOT become a fifth: | Call site | Mounted by | |---|---| | `components/gitlab/mr-topbar-button.tsx` | the task topbar | | `components/kanban-board.tsx` | the kanban board | | `hooks/domains/gitlab/use-mr-key-to-tasks.ts` | `app/gitlab/gitlab-page-client.tsx` | | `hooks/domains/workspace/use-external-vcs-file-link.ts` | `useExternalVcsFileLinkHydration` in `components/task/task-page-content.tsx`, gated on the task having a GitLab-provider repository | The chip SHALL NOT call `useWorkspaceMRs`. - There is no shared MR feedback cache. `useMRFeedback` is a per-instance reducer with no store slice, so there is nothing for the chip to warm and nothing the topbar would inherit from it. The chip SHALL NOT add a warmer. **Two** fetch triggers are genuinely new, and both are accepted rather than hidden. **New trigger 1: the automation options.** The chip calls `useTaskMRAutomationOptions(taskId)` to render its badges, and that hook lazily issues a `GET` when the store holds no options for the task. Before this feature those options were fetched only when the topbar dropdown or popover mounted `MRAutomationControls`; now they are fetched for any session view that has a linked open MR. **New trigger 2: the GitLab connection status, which also has a cross-surface side effect.** The chip calls `useGitLabAvailable()` to source `canLink`. That helper (`hooks/domains/gitlab/use-task-mr.ts`) wraps `useGitLabStatus()`, whose effect (`hooks/domains/gitlab/use-gitlab-status.ts`) runs on **every mount** and unconditionally does `setStatus(workspaceId, null)` and then `void loadStatus(workspaceId)` -> `fetchGitLabStatus`. Two consequences, both stated rather than discovered at Build time: 1. **It is a request, not a cache read.** Despite the hook's "store-cached" doc comment, the guard is per-hook-instance: a populated store does not short-circuit the effect. Every chip mount issues one `GET`, and two mounted chips issue two. 2. **It transiently blanks a value other surfaces read.** Because the effect clears the status to `null` before refetching, every other `useGitLabAvailable()` consumer — `hooks/use-nav-availability.ts`, `components/kanban-external-link-availability.ts`, `components/task/task-session-sidebar-task-linking.ts`, and `components/app-sidebar/sections/settings/workspaces-group.tsx` — reads `false` for the duration of the in-flight request. Mounting the chip therefore has a brief, observable effect on unrelated navigation UI. This is **accepted, not fixed here.** The chip is not the first consumer to do it (`MRTopbarButton` already calls `useGitLabAvailable()` on the same task route), the window is one request long, and the recovery is automatic when the status resolves. Removing the blanking means changing `useGitLabStatus` for every caller, which is its own card (see Out of scope). The chip SHALL NOT work around it with a local cache, a mount-order guard, or a debounce, and SHALL NOT read the status slice directly to dodge the hook. What the chip owes here is only that `canLink` is allowed to be `false` on the first render and become `true` without a remount — see Failure modes. The popover's MR feedback read is **not** a new trigger in this sense. It is `MRCIPopover`'s own existing fetch, it stays gated on that component's `enabled` prop, and the chip passes its disclosure-open state there (see the prop table under API surface). So it fires when a user opens the chip's popover or drawer, exactly as it already fires when a user opens the topbar's, and never on mount. What that does and does not buy across two mounted chips, stated precisely because the obvious argument is invalid: - **Guaranteed.** A chip whose disclosure is closed passes `enabled: false` and issues no feedback read. A chip that is never opened never fetches feedback. - **NOT guaranteed.** Two chips mounted for one task may each have an open disclosure at the same time, and then each issues its own feedback read. An earlier draft argued they "do not double it, because at most one disclosure is open per chip" — that is a **non-sequitur** and is retracted: per-*chip* exclusivity gives no cross-*chip* exclusivity, and one open disclosure on each of two chips is exactly two concurrent `enabled: true`. **Simultaneous open across two chips IS permitted.** This is a decision, not an omission. Each mounted chip owns its own disclosure state (see Accessibility) and this spec adds **no cross-chip coordinator**, no shared "currently open chip" context, and no global registry. The state is reachable in practice because the fine-pointer chip opens on **focus** as well as hover: a keyboard user can focus chip A open and then hover chip B, leaving both open. Two doubled feedback reads is the accepted cost. The alternative — a global mutual-exclusion coordinator — would be new shared state that neither mount point nor `MRTopbarButton` has today, would have to decide which chip loses, and would make each chip's behaviour depend on what else is mounted. That is a worse contract than an occasional duplicate idempotent `GET`. `useMRFeedback` is per-instance with no store slice, so two concurrent reads cannot corrupt each other; they resolve independently into their own popovers. The dedupe this buys, stated precisely rather than optimistically: - **Guaranteed.** Once options for a task are in the store, any number of further chip mounts for that task issue **zero** requests. The hook's effect is gated on `options || loading || error`, and a populated store short-circuits it on the first render. - **Guaranteed.** A single chip mount issues at most one request. - **NOT guaranteed, and not fixed by this card.** Two chips mounted for the same task in the **same React commit**, with no cached options, may each issue one request. The hook's guard reads render-captured values, so both effects run before either re-render observes `loading === true`. This is reachable: `PassthroughToolbar` has five mount sites and `ChatInputArea` three, several of them dockview-driven, so nothing structurally prevents two chips for one task existing at once. The duplicate is a `GET` with no side effect, and the hook's own request-id check (`isCurrentAndUnchangedExternally`) means the store converges to one options object regardless of which response lands last, so the outcome does not depend on ordering. Adding a shared in-flight guard to `useTaskMRAutomationOptions` would fix it, but that hook is also used by `MRAutomationControls` from the topbar, so the change belongs to a card that can test both callers; it is named in Out of scope. The chip SHALL NOT work around the gap with a module-level cache of its own. The same render-captured pattern is present in `useTaskCIAutomationOptions`, so `PRStatusChip` does not deliver cross-mount dedupe either. Parity with GitHub is recorded here as an observation, not as evidence that the property holds. **Hydration ownership, and why this spec pins no outcome for it.** An earlier draft claimed `MRTopbarButton` was the only mount point for `useWorkspaceMRs` and derived from that a specific consequence: that an archived task never hydrates the MR store, so the chip renders nothing there. **Both halves were wrong** and the claim is retracted. There are four call sites (table above), and one of them — `useExternalVcsFileLinkHydration` at `components/task/task-page-content.tsx` — runs on the `/tasks/:id` task page for any task with a GitLab-provider repository, independently of the topbar and independently of archived state. So whether the MR store is hydrated for a given task depends on which surfaces the session has visited and which route rendered the chip, not on a single owner. This spec therefore states no archived-task rendering outcome and **no AC depends on one.** What the chip guarantees is only the conditional already in Failure modes: if the task's MR list is not hydrated, `useTaskMRs` returns the shared empty array and the chip renders nothing, exactly as it does for a task with no MRs. Tests SHALL seed the store rather than rely on any ambient hydration path, which the E2E decision already requires. Giving GitLab MR hydration a single provider-level owner is its own card (see Out of scope). That card is what would make a hydration outcome specifiable; until it lands, asserting one here would pin a route-history-dependent flake. ## Responsive behaviour - Disclosure is chosen by pointer precision only, via `useTouchDrawer()` (`!isFinePointer`): coarse pointer renders the `Drawer` variant, fine pointer renders the hover `Popover` variant. - The chip SHALL NOT gate any part of itself on a Tailwind width class (`sm:`, `md:`, ...). Pairing a width-gated class with the pointer-gated hook is what leaves 640-767px rendered by neither branch, and the chip has no width-dependent behaviour to justify the risk. - The drawer variant carries a translated title, a screen-reader description, and a close button, and its body scrolls independently. - **Hover-popover placement is pinned by value**, so two builders cannot diverge visually while passing every scenario: `align="end"`, `sideOffset={4}`, and a `w-80` content width — the values `MRTopbarButton` already uses. `side` is left to Radix's default collision handling, which is what keeps the content on screen for a chip sitting at the bottom of the viewport; the "bounding box `y` is greater than or equal to 0" scenario below is the observable consequence of that and SHALL NOT be satisfied by hard-coding a `side`. ## Accessibility, focus, and duplicate mounts - The trigger is a `