From 1b28ef85d73c3269abca3cbc8db2c86ea48bdbb3 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Sun, 26 Jul 2026 21:00:06 +0200
Subject: [PATCH 1/5] docs(color-flags): plan the session-header flag surface

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../2026-07-26-session-header-color-flag.md   | 489 ++++++++++++++++++
 1 file changed, 489 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-26-session-header-color-flag.md

diff --git a/docs/superpowers/plans/2026-07-26-session-header-color-flag.md b/docs/superpowers/plans/2026-07-26-session-header-color-flag.md
new file mode 100644
index 00000000..975b7f79
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-26-session-header-color-flag.md
@@ -0,0 +1,489 @@
+# Session Header Color Flag Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A color-flagged agent shows that color as a chunk on the right end of its pane's session header, overlapping the status strip, so a flagged agent is spottable in the grid and not only in the Dispatch list.
+
+**Architecture:** The flag state already exists — `Settings.dispatchColorFlags` (sessionId → palette id), shipped in #603/#605. This adds a second *reader* of that state. The per-session lookup that `DispatchColorFlagStrip` performs inline is extracted into a `useColorFlag(sessionId)` hook so both surfaces resolve a flag identically; each surface keeps its own geometry, because a 10px alignment column and a 25% header chunk are different visual contracts. `PaneHeader` gains a `sessionId` prop and renders `PaneHeaderColorFlag` as a trailing flex child of its status row.
+
+**Tech Stack:** React 18, Zustand (`useAppStore`), Tailwind 4, Vitest + Testing Library (happy-dom `renderer` project).
+
+## Global Constraints
+
+- **Do not rename `Settings.dispatchColorFlags`.** It is a persisted settings key; renaming needs a `PERSIST_VERSION` migration for a purely cosmetic gain.
+- **Do not rename the command id `dispatch.color-flag.set`.** Command ids key `Settings.commandVisibilityOverrides`; renaming silently drops a user's saved overrides.
+- **Do not change the palette** (`DISPATCH_COLOR_FLAGS`) — ids, labels, and hex values stay exactly as they are. Persisted values are these ids.
+- **No new test files.** Extend `src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx`, which already owns this feature's coverage.
+- **No absolute positioning, no negative margins, no painting over padding** for the chunk. `docs/plans_and_ideas/2026-07-23-color-flag-layout-follow-up.md` established that flags participate in flex layout; this plan follows the same rule.
+- **Thick WHY comments** per `CLAUDE.md`, especially wherever this deviates from the Dispatch strip's contract.
+- Renderer tests run with `NODE_ENV=test`. A leaked `NODE_ENV=production` loads prod React and breaks `act()`.
+
+---
+
+## File Structure
+
+**Create:**
+- `src/renderer/src/app-state/settings/useColorFlag.ts` — the one place that turns a `sessionId` into a `ColorFlag | undefined`. No geometry, no JSX.
+- `src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx` — the header chunk: geometry + the unflagged-renders-nothing decision.
+
+**Modify:**
+- `src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx` — consume the shared hook instead of selecting inline.
+- `src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx` — `sessionId` prop, padding move, trailing chunk.
+- `src/renderer/src/workspace/tile-tree/TileLeaf.tsx:620` — pass `sessionId`.
+- `src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts` — command description now names both surfaces.
+- `src/renderer/src/app-state/settings/dispatchColorFlags.ts` — module header comment now names both surfaces.
+- `src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx` — new `describe` block for the header.
+
+**Why one shared hook and two components:** the *state* question ("is this session flagged, and in what color?") is identical everywhere and must never fork. The *layout* question is genuinely different per surface. Sharing the first and splitting the second is what keeps a future third surface from copy-pasting a store selector.
+
+---
+
+### Task 1: Extract the shared flag lookup
+
+Pure refactor. Behavior identical; the existing three color-flag tests are the regression net and must stay green without modification.
+
+**Files:**
+- Create: `src/renderer/src/app-state/settings/useColorFlag.ts`
+- Modify: `src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx`
+- Test: `src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx` (existing cases, unchanged)
+
+**Interfaces:**
+- Consumes: `colorFlagById(id: string | undefined): ColorFlag | undefined` and `type ColorFlag` from `@renderer/app-state/settings/dispatchColorFlags`; `useAppStore` from `@renderer/app-state/hooks`.
+- Produces: `useColorFlag(sessionId: SessionId): ColorFlag | undefined` — consumed by Task 2.
+
+- [ ] **Step 1: Create the hook**
+
+```tsx
+// src/renderer/src/app-state/settings/useColorFlag.ts
+import { useAppStore } from '@renderer/app-state/hooks'
+import { colorFlagById, type ColorFlag } from '@renderer/app-state/settings/dispatchColorFlags'
+import type { SessionId } from '@renderer/workspace/types'
+
+/**
+ * Resolve a session's color flag, or `undefined` when it has none.
+ *
+ * WHY this is a hook and not each surface selecting inline: color flags now
+ * have more than one reader (the Dispatch trailing column and the pane header
+ * chunk), and the thing that must NEVER fork between them is the state
+ * question — which settings key is read, and how an unknown/stale persisted id
+ * degrades. Geometry deliberately stays with each surface, because a 10px
+ * alignment column and a 25% header chunk are different visual contracts that
+ * should be free to diverge.
+ *
+ * Returning the resolved `ColorFlag` rather than the raw id means every caller
+ * gets the same "unknown id → no flag" degradation for free: a palette entry
+ * deleted in a future version stops rendering everywhere at once instead of
+ * throwing at one call site and rendering `undefined` at another.
+ */
+export function useColorFlag(sessionId: SessionId): ColorFlag | undefined {
+  return useAppStore(state => colorFlagById(state.settings.dispatchColorFlags[sessionId]))
+}
+```
+
+- [ ] **Step 2: Point the Dispatch strip at the hook**
+
+Replace the body of `DispatchColorFlagStrip.tsx` (keep the existing WHY comment block above the component verbatim — it documents the always-mounted-column decision, which is unchanged):
+
+```tsx
+import { memo } from 'react'
+
+import { useColorFlag } from '@renderer/app-state/settings/useColorFlag'
+import type { SessionId } from '@renderer/workspace/types'
+
+// WHY this is a real, always-mounted flex child rather than conditional
+// absolute decoration:
+//
+// Color flags are an index column. Rows must reserve the same trailing 10px
+// whether they are flagged or not so titles and compact labels align while the
+// user scans vertically. The first implementation painted over right padding,
+// which made the rich list look correct in isolation but gave Tiled Dispatch no
+// reusable width contract at all. Keeping the settings lookup and the geometry
+// in one component makes every Dispatch selector opt into the same invariant.
+//
+// The settings lookup itself now lives in `useColorFlag` because the pane
+// header reads the same state with different geometry; only the geometry below
+// is Dispatch-specific.
+export const DispatchColorFlagStrip = memo(function DispatchColorFlagStrip({
+  sessionId,
+}: {
+  sessionId: SessionId
+}) {
+  const colorFlag = useColorFlag(sessionId)
+
+  return (
+    <span
+      aria-hidden="true"
+      data-dispatch-color-flag={colorFlag?.id ?? 'none'}
+      className="pointer-events-none w-[10px] flex-none self-stretch"
+      style={colorFlag ? { backgroundColor: colorFlag.color } : undefined}
+    />
+  )
+})
+```
+
+- [ ] **Step 3: Run the existing color-flag tests — they must still pass unmodified**
+
+Run: `NODE_ENV=test npx vitest run --project renderer src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx`
+Expected: PASS, 3/3. If any fail, the refactor changed behavior — fix the refactor, not the tests.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/renderer/src/app-state/settings/useColorFlag.ts src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx
+git commit -m "refactor(color-flags): extract the per-session flag lookup into useColorFlag"
+```
+
+---
+
+### Task 2: The header chunk
+
+**Files:**
+- Create: `src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx`
+- Modify: `src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx`
+- Modify: `src/renderer/src/workspace/tile-tree/TileLeaf.tsx:620-630`
+- Test: `src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx`
+
+**Interfaces:**
+- Consumes: `useColorFlag(sessionId)` from Task 1.
+- Produces: `PaneHeaderColorFlag({ sessionId }: { sessionId: SessionId })`; `PaneHeader` gains a required `sessionId: SessionId` prop. DOM contract for tests: the chunk carries `data-pane-color-flag="<flagId>"` and is absent entirely when unflagged.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append this block to `DispatchColorFlags.renderer.test.tsx`, after the existing `describe`. The file's existing `vi.mock('@renderer/app-state/hooks', …)` and `setColorFlags` helper cover this block too — `useColorFlag` reads through that same mocked boundary.
+
+```tsx
+// WHY the pane-header cases live in this file rather than a new one: this file
+// is the color-flag feature's coverage, not the Dispatch list's. The flag is
+// one piece of state with several renderers, and keeping every renderer's
+// contract in one place is what caught the tiled-lane gap that #605 had to fix.
+describe('Session header color flag', () => {
+  function renderHeader(sessionId: string, statusMode: boolean) {
+    return render(
+      <PaneHeader
+        sessionId={sessionId}
+        paneLabel="A2"
+        projectDir="/Users/dev/agent-code"
+        statusMode={statusMode}
+        isSessionLive
+      />,
+    )
+  }
+
+  it('paints a trailing chunk of the flag color over the status strip', () => {
+    setColorFlags({ [FLAGGED_SESSION_ID]: 'red' })
+    const { container } = renderHeader(FLAGGED_SESSION_ID, true)
+
+    const chunk = container.querySelector<HTMLElement>('[data-pane-color-flag]')
+    expect(chunk).toHaveAttribute('data-pane-color-flag', 'red')
+    expect(chunk).toHaveClass('w-1/4', 'flex-none', 'self-stretch')
+    expect(chunk).not.toHaveClass('absolute')
+    expect(chunk).toHaveStyle({ backgroundColor: '#ef4444' })
+  })
+
+  it('renders no chunk at all for an unflagged session', () => {
+    setColorFlags({ [FLAGGED_SESSION_ID]: 'red' })
+    const { container } = renderHeader(UNFLAGGED_SESSION_ID, true)
+
+    // WHY absence rather than a transparent placeholder — the deliberate
+    // difference from the Dispatch column. Nothing sits to the right of this
+    // chunk, so there is no cross-row alignment to preserve, and reserving a
+    // quarter of every header would permanently squeeze the project dir for a
+    // signal that is switched off.
+    expect(container.querySelector('[data-pane-color-flag]')).toBeNull()
+  })
+
+  it('keeps the row padding on the label group so the chunk can bleed to the pane edge', () => {
+    setColorFlags({ [FLAGGED_SESSION_ID]: 'purple' })
+    const { container } = renderHeader(FLAGGED_SESSION_ID, false)
+
+    const row = container.querySelector<HTMLElement>('[data-pane-header-row="true"]')
+    expect(row).toHaveClass('pl-3')
+    expect(row).not.toHaveClass('px-3')
+    expect(row).not.toHaveClass('py-1')
+    // The vertical padding still exists — it moved one level down, so the
+    // header's rendered height is unchanged while the chunk stretches full-bleed.
+    expect(row?.firstElementChild).toHaveClass('py-1')
+  })
+})
+```
+
+Add `PaneHeader` to the file's imports:
+
+```tsx
+import { PaneHeader } from '@renderer/workspace/tile-tree/TileLeaf/PaneHeader'
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `NODE_ENV=test npx vitest run --project renderer src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx`
+Expected: FAIL — TypeScript/runtime error that `PaneHeader` has no `sessionId` prop, and no element matches `[data-pane-color-flag]`.
+
+- [ ] **Step 3: Create the chunk component**
+
+```tsx
+// src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx
+import { memo } from 'react'
+
+import { useColorFlag } from '@renderer/app-state/settings/useColorFlag'
+import type { SessionId } from '@renderer/workspace/types'
+
+// The session-header half of the color-flag feature: a flagged agent paints a
+// chunk of its pane header in the flag color, so it is spottable while scanning
+// the grid and not only while scanning the Dispatch list.
+//
+// WHY 25% of the header width rather than a fixed pixel chunk: panes in a tiled
+// grid vary enormously in width, and a fixed chunk reads as a huge slab in a
+// narrow lane and a rounding error in a wide one. A proportional chunk keeps
+// the same visual weight in every pane, which is the whole point of a signal
+// meant to be recognized peripherally.
+//
+// WHY nothing is rendered when unflagged — and why that DIFFERS from
+// DispatchColorFlagStrip, which always mounts a transparent 10px column:
+// that column exists to hold Dispatch labels in vertical alignment across rows.
+// Nothing sits to the right of this chunk, so there is no alignment invariant
+// to protect here, and permanently reserving a quarter of the header would
+// squeeze the project-dir text for a signal that is switched off. If a future
+// header ever grows content to the RIGHT of this chunk, that reasoning
+// inverts — mount it always and make it transparent, like the Dispatch column.
+//
+// `self-stretch` (not a fixed height) is what makes it overlap the status
+// strip: in Status Mode the header row collapses to ~5px, and the chunk paints
+// over the right quarter of the accent fill. `flex-none` keeps it at exactly
+// 25% instead of letting the truncating label group push it around.
+export const PaneHeaderColorFlag = memo(function PaneHeaderColorFlag({
+  sessionId,
+}: {
+  sessionId: SessionId
+}) {
+  const colorFlag = useColorFlag(sessionId)
+  if (!colorFlag) return null
+
+  return (
+    <span
+      aria-hidden="true"
+      data-pane-color-flag={colorFlag.id}
+      className="pointer-events-none w-1/4 flex-none self-stretch"
+      style={{ backgroundColor: colorFlag.color }}
+    />
+  )
+})
+```
+
+- [ ] **Step 4: Wire it into `PaneHeader`**
+
+In `PaneHeader.tsx`: add the imports, add `sessionId` to the props type and destructuring, move the row's vertical padding down onto the label group, and render the chunk as the row's trailing child.
+
+Imports to add:
+
+```tsx
+import { PaneHeaderColorFlag } from '@renderer/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag'
+import type { SessionId } from '@renderer/workspace/types'
+```
+
+Props — add as the first entry in both the destructuring and the type:
+
+```tsx
+  sessionId,
+```
+
+```tsx
+  sessionId: SessionId
+```
+
+Replace the status row (the `<div>` at `PaneHeader.tsx:36-55`) with:
+
+```tsx
+      <div
+        data-pane-header-row="true"
+        className={`flex items-center justify-between pl-3 text-[10px] ${
+          statusMode
+            ? isSessionLive
+              ? 'bg-accent text-accent-fg'
+              : 'bg-surface text-muted'
+            : 'bg-surface text-muted'
+        } ${statusMode ? 'min-h-[5px]' : ''}`}
+      >
+        {/* WHY the vertical padding sits on this group instead of on the row:
+            the color-flag chunk uses `self-stretch`, which fills the row's
+            CONTENT box — with `py-1` on the row the chunk would float with a
+            4px gap above and below and read as a floating pill rather than a
+            slice of the header. Pushing the padding one level down keeps the
+            header's rendered height byte-for-byte identical (the same 4px still
+            exists, just inside this child) while letting the chunk bleed from
+            the top edge of the header to the bottom. The row also drops its
+            right padding — `px-3` became `pl-3` — so the chunk reaches the pane
+            edge without an absolute overlay or a negative margin, per the
+            layout contract in
+            docs/plans_and_ideas/2026-07-23-color-flag-layout-follow-up.md. */}
+        <div className={`flex items-center gap-2 min-w-0 ${statusMode ? 'py-0' : 'py-1'}`}>
+          {paneLabel && (
+            <span className="flex-shrink-0 rounded-[3px] border border-current/30 px-1 leading-[14px] text-[9px] font-semibold tabular-nums">
+              {paneLabel}
+            </span>
+          )}
+          <span className="truncate" title={projectDir ?? 'no project dir'}>
+            {shortenCwd(projectDir)}
+          </span>
+        </div>
+        <PaneHeaderColorFlag sessionId={sessionId} />
+      </div>
+```
+
+Also extend the component's existing header comment — it currently describes only the accent/absence status signal, and a second color source in the same strip is exactly the kind of thing that confuses a future reader:
+
+```tsx
+// Pane header: compact status strip.
+//
+// In status mode, working panes paint with the theme accent;
+// idle/exited panes get no fill — the absence of color is the
+// signal, so a glance across the grid highlights only the
+// panes that still want attention. Previous design used
+// green/red, but red read as "error" for merely idle panes.
+//
+// The right quarter of the strip is owned by the session's color flag when one
+// is set (PaneHeaderColorFlag). The two signals are deliberately allowed to
+// overlap: liveness is automatic and transient, the flag is manual and sticky,
+// so a user who flagged a pane red wants that red regardless of whether the
+// agent happens to be running right now. The flag always wins its slice.
+```
+
+- [ ] **Step 5: Pass `sessionId` from `TileLeaf`**
+
+At `TileLeaf.tsx:620`, add the prop to the existing `<PaneHeader … />` call:
+
+```tsx
+      <PaneHeader
+        sessionId={sessionId}
+        paneLabel={paneLabel}
+        projectDir={runtime.projectDir}
+        statusMode={showStatusMode}
+        isSessionLive={isSessionLive}
+        relatedAgentTabs={relatedAgentTabs}
+        selectedRelatedSessionId={selectedRelatedSessionId ?? sessionId}
+        runtimes={workspace.runtimes}
+        ownerSessionId={ownerSessionId ?? sessionId}
+        onSelectRelatedSession={onSelectRelatedSession}
+      />
+```
+
+All three providers share this `TileLeaf` (`src/providers/registry.renderer.ts` maps Claude, Codex, and OpenCode to the same component), so this single call site covers every provider, the classic grid, and tiled Dispatch lanes.
+
+- [ ] **Step 6: Run the tests to verify they pass**
+
+Run: `NODE_ENV=test npx vitest run --project renderer src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx`
+Expected: PASS, 6/6 (3 pre-existing Dispatch cases + 3 new header cases).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx \
+        src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx \
+        src/renderer/src/workspace/tile-tree/TileLeaf.tsx \
+        src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx
+git commit -m "feat(color-flags): paint the flag color into the session header"
+```
+
+---
+
+### Task 3: Retire the Dispatch-only copy
+
+The command description and the palette module both tell the user this feature marks a Dispatch row. That is now half the truth, and stale user-facing copy is worse than none.
+
+**Files:**
+- Modify: `src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts`
+- Modify: `src/renderer/src/app-state/settings/dispatchColorFlags.ts`
+
+- [ ] **Step 1: Update the command description**
+
+In `dispatchColorFlagCommands.ts`, replace the `description` field and extend the comment above the export:
+
+```ts
+    description:
+      '**What it does:** Marks the focused agent with a color — a chunk of its ' +
+      '**session header** in the grid, and a strip on the right edge of its ' +
+      '**Dispatch row**.\n\n' +
+      '**Use when:** You are juggling several agents and want to flag one ' +
+      '(e.g. red) to find it fast.',
+```
+
+Add to the comment block above `dispatchColorFlagCommands`:
+
+```ts
+// The export, the command id, and the settings key all still say "dispatch"
+// even though the flag now renders in the pane header too. Both names are
+// persisted identifiers, not descriptions: the command id keys
+// `Settings.commandVisibilityOverrides` and the settings key holds the flags
+// themselves, so renaming either costs a migration and can silently drop a
+// user's saved command-visibility choices. The name is historical — the
+// feature was born in Dispatch. Treat "dispatch color flag" as the concept's
+// proper noun, not as a claim about where it renders.
+```
+
+- [ ] **Step 2: Update the palette module header**
+
+In `dispatchColorFlags.ts`, replace the first paragraph of the module comment (the sentence describing where the flag paints) with:
+
+```ts
+// Dispatch color flags — the fixed swatch palette + coercion.
+//
+// A "color flag" is a per-agent marker the user sets from the "Set color flag"
+// command. It renders in two places: a thick strip on the right edge of that
+// agent's Dispatch row, and a chunk of the right end of its pane's session
+// header in the grid. See docs/plans_and_ideas/2026-07-23-dispatch-color-flags.md
+// for the original feature and docs/superpowers/plans/2026-07-26-session-header-color-flag.md
+// for the header surface.
+```
+
+- [ ] **Step 3: Verify nothing else claims Dispatch-only**
+
+Run: `grep -rn "Dispatch row" src/renderer/src --include='*.ts' --include='*.tsx'`
+Expected: only matches that are genuinely about Dispatch rows. Any remaining color-flag copy claiming the flag renders *only* in Dispatch should be corrected in this task.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts \
+        src/renderer/src/app-state/settings/dispatchColorFlags.ts
+git commit -m "docs(color-flags): copy now describes both flag surfaces"
+```
+
+---
+
+### Task 4: Full verification
+
+**Files:** none — this task only runs gates.
+
+- [ ] **Step 1: Type-check both projects**
+
+Run: `npm run typecheck`
+Expected: exit 0, no output. This is the real gate — `electron-vite build` and Vitest do not type-check.
+
+- [ ] **Step 2: Run the renderer project**
+
+Run: `NODE_ENV=test npx vitest run --project renderer`
+Expected: all pass, including the 6 color-flag cases.
+
+- [ ] **Step 3: Run the full suite**
+
+Run: `NODE_ENV=test npx vitest run`
+Expected: all pass. One known environment flake exists outside this change: `packages/claude-code-headless` `JsonlTailer.test.ts` "second tailer survives first closing" (fs.watch timing). If only that fails, it is pre-existing — note it, do not chase it.
+
+- [ ] **Step 4: Manual check**
+
+Run: `npm run dev`. Then:
+1. Command palette → **Set color flag** → red, on a focused grid agent.
+2. Confirm the right quarter of that pane's header is red, flush to the pane's right edge and the full height of the header strip.
+3. Toggle Status Mode off and confirm the chunk still fills the taller header edge-to-edge, and the header did not change height.
+4. Confirm the flagged agent's Dispatch row strip still renders (Task 1 must not have regressed it).
+5. **Clear flag** → the header chunk disappears with no leftover gap.
+6. Restart the app → the flag is still there (it is persisted settings).
+
+---
+
+## Self-Review
+
+**Spec coverage:** placement inside the existing header row (Task 2 Step 4), right end (`justify-between` + trailing child), overlapping the status strip (`self-stretch` + the flag-wins comment), proportional 25% width (Task 2 Step 3), shared lookup (Task 1), `sessionId` plumbing (Task 2 Step 5), stale copy (Task 3). All covered.
+
+**Placeholders:** none — every code step carries the literal code.
+
+**Type consistency:** `useColorFlag(sessionId: SessionId): ColorFlag | undefined` is defined in Task 1 and consumed with that exact signature in Task 2. `SessionId` is `string` (`src/renderer/src/workspace/types.ts:27`), so the existing tests' plain string session ids type-check against the new `PaneHeader` prop. The DOM hooks `data-pane-color-flag` and `data-pane-header-row` are asserted in Task 2 Step 1 and emitted in Steps 3-4 under the same names.

From 386e2f5795341add5acaa1841108ab22e533a4ff Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Sun, 26 Jul 2026 21:00:46 +0200
Subject: [PATCH 2/5] refactor(color-flags): extract the per-session flag
 lookup into useColorFlag

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/app-state/settings/useColorFlag.ts    | 23 +++++++++++++++++++
 .../dispatch/DispatchColorFlagStrip.tsx       | 11 +++++----
 2 files changed, 29 insertions(+), 5 deletions(-)
 create mode 100644 src/renderer/src/app-state/settings/useColorFlag.ts

diff --git a/src/renderer/src/app-state/settings/useColorFlag.ts b/src/renderer/src/app-state/settings/useColorFlag.ts
new file mode 100644
index 00000000..ab1cb69a
--- /dev/null
+++ b/src/renderer/src/app-state/settings/useColorFlag.ts
@@ -0,0 +1,23 @@
+import { useAppStore } from '@renderer/app-state/hooks'
+import { colorFlagById, type ColorFlag } from '@renderer/app-state/settings/dispatchColorFlags'
+import type { SessionId } from '@renderer/workspace/types'
+
+/**
+ * Resolve a session's color flag, or `undefined` when it has none.
+ *
+ * WHY this is a hook and not each surface selecting inline: color flags now
+ * have more than one reader (the Dispatch trailing column and the pane header
+ * chunk), and the thing that must NEVER fork between them is the state
+ * question — which settings key is read, and how an unknown/stale persisted id
+ * degrades. Geometry deliberately stays with each surface, because a 10px
+ * alignment column and a 25% header chunk are different visual contracts that
+ * should be free to diverge.
+ *
+ * Returning the resolved `ColorFlag` rather than the raw id means every caller
+ * gets the same "unknown id → no flag" degradation for free: a palette entry
+ * deleted in a future version stops rendering everywhere at once instead of
+ * throwing at one call site and rendering `undefined` at another.
+ */
+export function useColorFlag(sessionId: SessionId): ColorFlag | undefined {
+  return useAppStore(state => colorFlagById(state.settings.dispatchColorFlags[sessionId]))
+}
diff --git a/src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx b/src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx
index d0c5fc03..da2bbb26 100644
--- a/src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx
+++ b/src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx
@@ -1,7 +1,6 @@
 import { memo } from 'react'
 
-import { useAppStore } from '@renderer/app-state/hooks'
-import { colorFlagById } from '@renderer/app-state/settings/dispatchColorFlags'
+import { useColorFlag } from '@renderer/app-state/settings/useColorFlag'
 import type { SessionId } from '@renderer/workspace/types'
 
 // WHY this is a real, always-mounted flex child rather than conditional
@@ -13,14 +12,16 @@ import type { SessionId } from '@renderer/workspace/types'
 // which made the rich list look correct in isolation but gave Tiled Dispatch no
 // reusable width contract at all. Keeping the settings lookup and the geometry
 // in one component makes every Dispatch selector opt into the same invariant.
+//
+// The settings lookup itself now lives in `useColorFlag` because the pane
+// header reads the same state with different geometry; only the geometry below
+// is Dispatch-specific.
 export const DispatchColorFlagStrip = memo(function DispatchColorFlagStrip({
   sessionId,
 }: {
   sessionId: SessionId
 }) {
-  const colorFlag = useAppStore(state =>
-    colorFlagById(state.settings.dispatchColorFlags[sessionId]),
-  )
+  const colorFlag = useColorFlag(sessionId)
 
   return (
     <span

From 36846eb34f7d61ed11bf5c76f7f72b592d483812 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Sun, 26 Jul 2026 21:04:22 +0200
Subject: [PATCH 3/5] feat(color-flags): paint the flag color into the session
 header
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The flag now renders in the pane header's right quarter, overlapping the
status strip, so a flagged agent is spottable while scanning the grid and
not only while scanning the Dispatch list.

The header row's vertical padding moved onto its label group so the chunk
can bleed edge-to-edge without an absolute overlay; rendered height is
unchanged. The remote client renders the same header, so it passes
sessionId too — it resolves to "no flag" through the frozen settings stub.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/remote-client/src/ui/SessionView.tsx      | 12 +++-
 .../DispatchColorFlags.renderer.test.tsx      | 55 +++++++++++++++++++
 .../src/workspace/tile-tree/TileLeaf.tsx      |  1 +
 .../tile-tree/TileLeaf/PaneHeader.tsx         | 30 +++++++++-
 .../TileLeaf/PaneHeaderColorFlag.tsx          | 45 +++++++++++++++
 5 files changed, 139 insertions(+), 4 deletions(-)
 create mode 100644 src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx

diff --git a/src/remote-client/src/ui/SessionView.tsx b/src/remote-client/src/ui/SessionView.tsx
index f5494827..92ff4652 100644
--- a/src/remote-client/src/ui/SessionView.tsx
+++ b/src/remote-client/src/ui/SessionView.tsx
@@ -296,8 +296,18 @@ export function SessionView({
             phone's Back/conn nav — on desktop this IS the pane's top bar.
             statusMode off (a multi-pane-grid glance affordance, meaningless on
             a single phone screen) and related-agent chips empty (the v1 wire
-            emits no sub-agent data). */}
+            emits no sub-agent data).
+
+            sessionId feeds the header's color-flag chunk. On the phone that
+            always resolves to "no flag": the store is the frozen
+            DEFAULT_SETTINGS snapshot from src/stubs/appStateHooks, whose
+            dispatchColorFlags is `{}`, and the v1 wire carries no settings.
+            It is still passed honestly rather than stubbed out, so that if the
+            phone ever syncs real settings the flag appears with no edit here —
+            and so a reader does not have to wonder which sessionId the header
+            would have used. */}
         <PaneHeader
+          sessionId={sessionId}
           paneLabel={provider}
           projectDir={cwd}
           statusMode={false}
diff --git a/src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx b/src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx
index 1ca260d5..3e72cbae 100644
--- a/src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx
+++ b/src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx
@@ -8,6 +8,7 @@ import type {
   DispatchAgentRow,
   DispatchTabGroup,
 } from '@renderer/workspace/dispatch/dispatchSelectors'
+import { PaneHeader } from '@renderer/workspace/tile-tree/TileLeaf/PaneHeader'
 
 const appState = vi.hoisted(() => ({
   settings: {
@@ -141,3 +142,57 @@ describe('Dispatch color-flag layout', () => {
     expect(screen.getByRole('button', { name: 'Purple' })).toHaveAttribute('aria-pressed', 'false')
   })
 })
+
+// WHY the pane-header cases live in this file rather than a new one: this file
+// is the color-flag feature's coverage, not the Dispatch list's. The flag is
+// one piece of state with several renderers, and keeping every renderer's
+// contract in one place is what caught the tiled-lane gap that #605 had to fix.
+describe('Session header color flag', () => {
+  function renderHeader(sessionId: string, statusMode: boolean) {
+    return render(
+      <PaneHeader
+        sessionId={sessionId}
+        paneLabel="A2"
+        projectDir="/Users/dev/agent-code"
+        statusMode={statusMode}
+        isSessionLive
+      />,
+    )
+  }
+
+  it('paints a trailing chunk of the flag color over the status strip', () => {
+    setColorFlags({ [FLAGGED_SESSION_ID]: 'red' })
+    const { container } = renderHeader(FLAGGED_SESSION_ID, true)
+
+    const chunk = container.querySelector<HTMLElement>('[data-pane-color-flag]')
+    expect(chunk).toHaveAttribute('data-pane-color-flag', 'red')
+    expect(chunk).toHaveClass('w-1/4', 'flex-none', 'self-stretch')
+    expect(chunk).not.toHaveClass('absolute')
+    expect(chunk).toHaveStyle({ backgroundColor: '#ef4444' })
+  })
+
+  it('renders no chunk at all for an unflagged session', () => {
+    setColorFlags({ [FLAGGED_SESSION_ID]: 'red' })
+    const { container } = renderHeader(UNFLAGGED_SESSION_ID, true)
+
+    // WHY absence rather than a transparent placeholder — the deliberate
+    // difference from the Dispatch column. Nothing sits to the right of this
+    // chunk, so there is no cross-row alignment to preserve, and reserving a
+    // quarter of every header would permanently squeeze the project dir for a
+    // signal that is switched off.
+    expect(container.querySelector('[data-pane-color-flag]')).toBeNull()
+  })
+
+  it('keeps the row padding on the label group so the chunk can bleed to the pane edge', () => {
+    setColorFlags({ [FLAGGED_SESSION_ID]: 'purple' })
+    const { container } = renderHeader(FLAGGED_SESSION_ID, false)
+
+    const row = container.querySelector<HTMLElement>('[data-pane-header-row="true"]')
+    expect(row).toHaveClass('pl-3')
+    expect(row).not.toHaveClass('px-3')
+    expect(row).not.toHaveClass('py-1')
+    // The vertical padding still exists — it moved one level down, so the
+    // header's rendered height is unchanged while the chunk stretches full-bleed.
+    expect(row?.firstElementChild).toHaveClass('py-1')
+  })
+})
diff --git a/src/renderer/src/workspace/tile-tree/TileLeaf.tsx b/src/renderer/src/workspace/tile-tree/TileLeaf.tsx
index 32d6802d..3fa7a460 100644
--- a/src/renderer/src/workspace/tile-tree/TileLeaf.tsx
+++ b/src/renderer/src/workspace/tile-tree/TileLeaf.tsx
@@ -618,6 +618,7 @@ export function TileLeaf({
       onMouseDown={onFocusRequest}
     >
       <PaneHeader
+        sessionId={sessionId}
         paneLabel={paneLabel}
         projectDir={runtime.projectDir}
         statusMode={showStatusMode}
diff --git a/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx
index 703bccc0..76b1bd77 100644
--- a/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx
+++ b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx
@@ -1,6 +1,8 @@
 import { shortenCwd } from '@renderer/workspace/tile-tree/TileLeaf/labels'
+import { PaneHeaderColorFlag } from '@renderer/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag'
 import type { GridRelatedAgentTab } from '@renderer/workspace/gridRelatedAgents'
 import { dispatchAttentionLabelFromConditions } from '@renderer/workspace/conditions/selectors'
+import type { SessionId } from '@renderer/workspace/types'
 import type { SessionRuntime } from '@renderer/workspace/workspaceStore'
 
 // Pane header: compact status strip.
@@ -10,7 +12,14 @@ import type { SessionRuntime } from '@renderer/workspace/workspaceStore'
 // signal, so a glance across the grid highlights only the
 // panes that still want attention. Previous design used
 // green/red, but red read as "error" for merely idle panes.
+//
+// The right quarter of the strip is owned by the session's color flag when one
+// is set (PaneHeaderColorFlag). The two signals are deliberately allowed to
+// overlap: liveness is automatic and transient, the flag is manual and sticky,
+// so a user who flagged a pane red wants that red regardless of whether the
+// agent happens to be running right now. The flag always wins its slice.
 export function PaneHeader({
+  sessionId,
   paneLabel,
   projectDir,
   statusMode,
@@ -21,6 +30,7 @@ export function PaneHeader({
   ownerSessionId,
   onSelectRelatedSession,
 }: {
+  sessionId: SessionId
   paneLabel?: string
   projectDir: string | null
   statusMode: boolean
@@ -34,15 +44,28 @@ export function PaneHeader({
   return (
     <div className="border-b border-border bg-surface text-muted font-code select-none">
       <div
-        className={`flex items-center justify-between px-3 text-[10px] ${
+        data-pane-header-row="true"
+        className={`flex items-center justify-between pl-3 text-[10px] ${
           statusMode
             ? isSessionLive
               ? 'bg-accent text-accent-fg'
               : 'bg-surface text-muted'
             : 'bg-surface text-muted'
-        } ${statusMode ? 'py-0 min-h-[5px]' : 'py-1'}`}
+        } ${statusMode ? 'min-h-[5px]' : ''}`}
       >
-        <div className="flex items-center gap-2 min-w-0">
+        {/* WHY the vertical padding sits on this group instead of on the row:
+            the color-flag chunk uses `self-stretch`, which fills the row's
+            CONTENT box — with `py-1` on the row the chunk would float with a
+            4px gap above and below and read as a floating pill rather than a
+            slice of the header. Pushing the padding one level down keeps the
+            header's rendered height byte-for-byte identical (the same 4px still
+            exists, just inside this child) while letting the chunk bleed from
+            the top edge of the header to the bottom. The row also drops its
+            right padding — `px-3` became `pl-3` — so the chunk reaches the pane
+            edge without an absolute overlay or a negative margin, per the
+            layout contract in
+            docs/plans_and_ideas/2026-07-23-color-flag-layout-follow-up.md. */}
+        <div className={`flex items-center gap-2 min-w-0 ${statusMode ? 'py-0' : 'py-1'}`}>
           {paneLabel && (
             <span className="flex-shrink-0 rounded-[3px] border border-current/30 px-1 leading-[14px] text-[9px] font-semibold tabular-nums">
               {paneLabel}
@@ -52,6 +75,7 @@ export function PaneHeader({
             {shortenCwd(projectDir)}
           </span>
         </div>
+        <PaneHeaderColorFlag sessionId={sessionId} />
       </div>
       {relatedAgentTabs.length > 0 && (
         <div className="flex items-center gap-1 overflow-x-auto border-t border-border/70 px-2 py-1 text-[10px]">
diff --git a/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx
new file mode 100644
index 00000000..75f30e41
--- /dev/null
+++ b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx
@@ -0,0 +1,45 @@
+import { memo } from 'react'
+
+import { useColorFlag } from '@renderer/app-state/settings/useColorFlag'
+import type { SessionId } from '@renderer/workspace/types'
+
+// The session-header half of the color-flag feature: a flagged agent paints a
+// chunk of its pane header in the flag color, so it is spottable while scanning
+// the grid and not only while scanning the Dispatch list.
+//
+// WHY 25% of the header width rather than a fixed pixel chunk: panes in a tiled
+// grid vary enormously in width, and a fixed chunk reads as a huge slab in a
+// narrow lane and a rounding error in a wide one. A proportional chunk keeps
+// the same visual weight in every pane, which is the whole point of a signal
+// meant to be recognized peripherally.
+//
+// WHY nothing is rendered when unflagged — and why that DIFFERS from
+// DispatchColorFlagStrip, which always mounts a transparent 10px column:
+// that column exists to hold Dispatch labels in vertical alignment across rows.
+// Nothing sits to the right of this chunk, so there is no alignment invariant
+// to protect here, and permanently reserving a quarter of the header would
+// squeeze the project-dir text for a signal that is switched off. If a future
+// header ever grows content to the RIGHT of this chunk, that reasoning
+// inverts — mount it always and make it transparent, like the Dispatch column.
+//
+// `self-stretch` (not a fixed height) is what makes it overlap the status
+// strip: in Status Mode the header row collapses to ~5px, and the chunk paints
+// over the right quarter of the accent fill. `flex-none` keeps it at exactly
+// 25% instead of letting the truncating label group push it around.
+export const PaneHeaderColorFlag = memo(function PaneHeaderColorFlag({
+  sessionId,
+}: {
+  sessionId: SessionId
+}) {
+  const colorFlag = useColorFlag(sessionId)
+  if (!colorFlag) return null
+
+  return (
+    <span
+      aria-hidden="true"
+      data-pane-color-flag={colorFlag.id}
+      className="pointer-events-none w-1/4 flex-none self-stretch"
+      style={{ backgroundColor: colorFlag.color }}
+    />
+  )
+})

From 47756c3a1fa658c94cf75c06bf7328084496c24a Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Sun, 26 Jul 2026 21:05:17 +0200
Subject: [PATCH 4/5] docs(color-flags): copy now describes both flag surfaces

The command description, palette module, and picker modal all claimed the
flag renders only on a Dispatch row. Also records why the "dispatch"-prefixed
command id and settings key keep their historical names.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../app-state/settings/dispatchColorFlags.ts  | 10 ++++--
 .../commands/dispatchColorFlagCommands.ts     | 33 ++++++++++++++-----
 .../workspace/ui/ColorFlagPickerModal.tsx     |  9 ++---
 3 files changed, 36 insertions(+), 16 deletions(-)

diff --git a/src/renderer/src/app-state/settings/dispatchColorFlags.ts b/src/renderer/src/app-state/settings/dispatchColorFlags.ts
index b209d2f9..38a753a6 100644
--- a/src/renderer/src/app-state/settings/dispatchColorFlags.ts
+++ b/src/renderer/src/app-state/settings/dispatchColorFlags.ts
@@ -1,9 +1,13 @@
 // Dispatch color flags — the fixed swatch palette + coercion.
 //
 // A "color flag" is a per-agent marker the user sets from the "Set color flag"
-// command to paint a thick strip on the right edge of that agent's Dispatch
-// row, so a flagged agent is instantly spottable when scanning many running
-// workflows. See docs/plans_and_ideas/2026-07-23-dispatch-color-flags.md.
+// command, so a flagged agent is instantly spottable when scanning many running
+// workflows. It renders in two places: a thick strip on the right edge of that
+// agent's Dispatch row, and a chunk of the right end of its pane's session
+// header in the grid. See docs/plans_and_ideas/2026-07-23-dispatch-color-flags.md
+// for the original feature and
+// docs/superpowers/plans/2026-07-26-session-header-color-flag.md for the header
+// surface. `useColorFlag` is the shared reader both surfaces go through.
 //
 // WHY a fixed palette rather than a free RGB/hex picker: the whole point is
 // fast visual triage of a list, and a small set of high-contrast, distinct
diff --git a/src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts b/src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts
index 6f6e2458..e4ec95d2 100644
--- a/src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts
+++ b/src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts
@@ -1,17 +1,31 @@
 import type { CommandDef } from '@renderer/features/command-palette/types'
 import { commandTargetSessionId } from '@renderer/workspace/hook/selectors/commandTargetSessionId'
 
-// "Set color flag" — mark the currently-commanded agent with a colored strip on
-// the right edge of its Dispatch row, so it's easy to spot while scanning many
-// running workflows. See docs/plans_and_ideas/2026-07-23-dispatch-color-flags.md.
+// "Set color flag" — mark the currently-commanded agent with a color, so it's
+// easy to spot while scanning many running workflows. It renders as a strip on
+// the right edge of the agent's Dispatch row and as a chunk of its pane's
+// session header. See docs/plans_and_ideas/2026-07-23-dispatch-color-flags.md
+// and docs/superpowers/plans/2026-07-26-session-header-color-flag.md.
 //
-// `surface: 'session'` (not 'dispatch') so a flag can be set from any mode; the
-// strip is a Dispatch-list affordance, but the act of flagging an agent isn't
-// mode-specific and shouldn't disappear the moment you leave Dispatch. Targets
+// `surface: 'session'` (not 'dispatch') so a flag can be set from any mode.
+// That choice predates the header surface and was already right for a different
+// reason — flagging an agent isn't mode-specific and shouldn't disappear the
+// moment you leave Dispatch — but the header makes it load-bearing: the flag is
+// now visible in the grid, so a grid-only user must be able to set one. Targets
 // `commandTargetSessionId` (Dispatch-aware focus), so it needs no separate row
 // selection. No keybind by design — a low-frequency, list-management action.
 //
-// No getState chip: the current flag is already visible on the row itself, and
+// The export, the command id, and the settings key all still say "dispatch"
+// even though the flag now renders in the pane header too. Both names are
+// persisted identifiers, not descriptions: the command id keys
+// `Settings.commandVisibilityOverrides` and the settings key holds the flags
+// themselves, so renaming either costs a migration and can silently drop a
+// user's saved command-visibility choices. The name is historical — the feature
+// was born in Dispatch. Treat "dispatch color flag" as the concept's proper
+// noun, not as a claim about where it renders.
+//
+// No getState chip: the current flag is already visible on the row and in the
+// pane header, and
 // the command context does not carry the settings store, so surfacing it here
 // would mean threading settings into every command's context for one label.
 export const dispatchColorFlagCommands: CommandDef[] = [
@@ -20,8 +34,9 @@ export const dispatchColorFlagCommands: CommandDef[] = [
     surface: 'session',
     title: 'Set color flag',
     description:
-      '**What it does:** Marks the focused agent with a colored strip on the ' +
-      'right edge of its **Dispatch row**, so you can spot it in a long list.\n\n' +
+      '**What it does:** Marks the focused agent with a color — a chunk of its ' +
+      '**session header** in the grid, and a strip on the right edge of its ' +
+      '**Dispatch row**.\n\n' +
       '**Use when:** You are juggling several agents and want to flag one ' +
       '(e.g. red) to find it fast.',
     keywords: ['color', 'colour', 'flag', 'highlight', 'mark', 'tag', 'dispatch', 'spot'],
diff --git a/src/renderer/src/features/workspace/ui/ColorFlagPickerModal.tsx b/src/renderer/src/features/workspace/ui/ColorFlagPickerModal.tsx
index 4a831d42..804bd6ba 100644
--- a/src/renderer/src/features/workspace/ui/ColorFlagPickerModal.tsx
+++ b/src/renderer/src/features/workspace/ui/ColorFlagPickerModal.tsx
@@ -14,10 +14,11 @@ import {
 } from '@renderer/app-state/settings/dispatchColorFlags'
 import type { SessionId } from '@renderer/workspace/types'
 
-// The swatch picker for Dispatch color flags. Picking a swatch sets the flag and
-// closes; "Clear flag" removes it. The strip itself renders on the Dispatch row
-// (see DispatchAgentList). Kept intentionally tiny — this is a one-tap triage
-// affordance, not a color editor.
+// The swatch picker for color flags. Picking a swatch sets the flag and closes;
+// "Clear flag" removes it. The flag itself renders in two places: the Dispatch
+// row's trailing strip (see DispatchColorFlagStrip) and the pane's session
+// header (see PaneHeaderColorFlag). Kept intentionally tiny — this is a one-tap
+// triage affordance, not a color editor.
 export function ColorFlagPickerModal({
   open,
   sessionId,

From d2ad43848bc2b22b63ae04b1641d9f11ebe2a73f Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Sun, 26 Jul 2026 21:25:45 +0200
Subject: [PATCH 5/5] fix(color-flags): address two-agent review of the header
 surface

- pl-3 deleted the header's right inset for unflagged panes, since the
  chunk that was to stand in for it does not mount without a flag
  (measured 12px -> 0px at a 100px pane). All row padding now lives on
  the label group, which also makes w-1/4 a true quarter.
- Add a 1px canvas seam: every accent preset shares a hue family with a
  flag color, so a matching accent swallowed the flag on live panes.
- Drop pointer-events-none and add a title on the header chunk; color
  alone is unreadable for a colorblind user. DispatchColorFlagStrip
  keeps both, since its row button already owns a richer tooltip.
- Cover the two mutations the original tests missed (justify-between,
  Status Mode group padding) plus a stale persisted flag id.
- Set Color Flag... per command-style.md rules 8 and 9.
- Document the idle-pane tension and the do-not-rename constraint.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../2026-07-26-session-header-color-flag.md   | 88 +++++++++++++++++++
 .../app-state/settings/dispatchColorFlags.ts  |  9 ++
 .../commands/dispatchColorFlagCommands.ts     | 30 ++++---
 .../dispatch/DispatchColorFlagStrip.tsx       | 11 +++
 .../DispatchColorFlags.renderer.test.tsx      | 66 ++++++++++++--
 .../tile-tree/TileLeaf/PaneHeader.tsx         | 54 +++++++++---
 .../TileLeaf/PaneHeaderColorFlag.tsx          | 31 ++++++-
 7 files changed, 254 insertions(+), 35 deletions(-)

diff --git a/docs/superpowers/plans/2026-07-26-session-header-color-flag.md b/docs/superpowers/plans/2026-07-26-session-header-color-flag.md
index 975b7f79..9b717e72 100644
--- a/docs/superpowers/plans/2026-07-26-session-header-color-flag.md
+++ b/docs/superpowers/plans/2026-07-26-session-header-color-flag.md
@@ -1,5 +1,10 @@
 # Session Header Color Flag Implementation Plan
 
+> **Status: SHIPPED**, with corrections from a two-agent review — see
+> "Review outcome" at the bottom. Where a task body below disagrees with that
+> section, that section is what the code does. In particular Task 2's `pl-3`
+> is wrong: **all** the row's padding moved onto the label group.
+
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Goal:** A color-flagged agent shows that color as a chunk on the right end of its pane's session header, overlapping the status strip, so a flagged agent is spottable in the grid and not only in the Dispatch list.
@@ -487,3 +492,86 @@ Run: `npm run dev`. Then:
 **Placeholders:** none — every code step carries the literal code.
 
 **Type consistency:** `useColorFlag(sessionId: SessionId): ColorFlag | undefined` is defined in Task 1 and consumed with that exact signature in Task 2. `SessionId` is `string` (`src/renderer/src/workspace/types.ts:27`), so the existing tests' plain string session ids type-check against the new `PaneHeader` prop. The DOM hooks `data-pane-color-flag` and `data-pane-header-row` are asserted in Task 2 Step 1 and emitted in Steps 3-4 under the same names.
+
+---
+
+## Review outcome
+
+Two orchestrated reviewers went over the branch: one on correctness and
+regression risk, one on design and repo conventions. Six findings were accepted
+and fixed; two were declined with reasons. This section is the record of what
+the code actually does, since several corrections contradict the task bodies
+above.
+
+### Accepted and fixed
+
+1. **The `pl-3` was a real bug.** Moving only the vertical padding and changing
+   `px-3` → `pl-3` deleted the header's right inset for *unflagged* panes,
+   because the chunk that was supposed to stand in for it doesn't mount when
+   there's no flag. Measured in Chromium at a 100px pane width: the truncated
+   project dir sat 12px off the pane edge before, 0px after. Flagged panes were
+   affected too — the text butted against the chunk with a 0.83px gap at 180px.
+   **Fix:** the row is now bare and the label group carries `px-3 py-*`. The
+   inset survives with or without a flag, and as a side effect the chunk's
+   `w-1/4` became a true quarter (percentages resolve against the row's content
+   box, so `pl-3` had been making it 25% of `W − 12px` — 20% at a 60px pane).
+
+2. **The tests were near-tautological.** Two mutations passed green against the
+   original three cases: deleting `justify-between` (chunk renders mid-header
+   instead of at the right edge) and making the group's padding an
+   unconditional `py-1` (Status Mode's 5px strip grows to a 24px bar). Both are
+   now covered, plus a stale-persisted-id case for `useColorFlag`'s headline
+   justification, which had no coverage at either surface. All three mutations
+   were re-run against the fixed tests and each fails exactly one case.
+
+3. **Accent/flag hue collision.** The flag colors are raw hex; the strip behind
+   them is `bg-accent`, a *user-chosen* token. Every shipped accent preset
+   shares a hue family with at least one flag color (coral/red, gold/yellow,
+   amber/orange, sky/blue, lavender/purple, lime/green), so a user whose accent
+   matched their flag got no signal at all on a live pane — the exact moment the
+   flag matters most. **Fix:** a 1px `border-l border-canvas` seam, which
+   separates the chunk from both the accent fill and `bg-surface` in either
+   theme and costs no layout width.
+
+4. **Color was the only channel.** `aria-hidden` + `pointer-events-none` + no
+   tooltip meant a deuteranope could not separate red from green from orange,
+   with no recovery short of reopening the picker. **Fix:** the header chunk
+   drops `pointer-events-none` (a tooltip needs hover; click-to-focus still
+   works, the mousedown bubbles to the pane container) and gains
+   `title="<Label> flag"`. `aria-hidden` stays, now with a stated reason.
+
+5. **The idle-pane contradiction.** The "flag always wins its slice" paragraph
+   justified the overlap for live panes but left a red chunk sitting on idle
+   panes — exactly the false-error read that `PaneHeader`'s own comment, four
+   lines earlier, says the green/red design was abandoned for. The comment now
+   names the idle case and grounds the difference in authorship (a flag is
+   user-set, the old red was automatic), and states what would expire that
+   reasoning: flags ever being assigned automatically.
+
+6. **Command-style violations.** `Set color flag` broke `docs/command-style.md`
+   rule 9 (title case) and rule 8 (ellipsis when the command needs more input —
+   `run` always opens the picker). Now `Set Color Flag…`. Pre-existing, fixed
+   here because this PR was already rewriting the command's copy.
+
+### Declined, with reasons
+
+- **`max-w-[96px]` cap on the chunk.** The design reviewer argued 25% of a
+  maximized 2000px header is a 500px slab rather than a peripheral marker, and
+  recommended capping it. The proportional width is what the product owner
+  specified from a mock, so changing it is their call, not a defect fix — it is
+  flagged for them rather than applied. (The same finding claimed the WHY
+  comment states its rationale backwards; it does not. A *fixed* chunk really
+  is proportionally huge in a narrow lane and negligible in a wide one, which
+  is what the comment says.)
+- **Tooltip on `DispatchColorFlagStrip`.** Recommended for parity with the
+  header chunk. Declined: that strip sits inside the Dispatch row's `<button>`,
+  which already carries a richer tooltip (agent label, title, detached state).
+  A `title` there would *replace* it for the 10px the strip covers, so hovering
+  the row's right edge would tell you less than hovering anywhere else. The
+  divergence is now documented in both components.
+
+### Not this PR
+
+`dispatchColorFlags` entries are never deleted when a session closes, so the
+persisted map accumulates dead session ids forever. Pre-existing, outside this
+diff, worth its own issue.
diff --git a/src/renderer/src/app-state/settings/dispatchColorFlags.ts b/src/renderer/src/app-state/settings/dispatchColorFlags.ts
index 38a753a6..c6948171 100644
--- a/src/renderer/src/app-state/settings/dispatchColorFlags.ts
+++ b/src/renderer/src/app-state/settings/dispatchColorFlags.ts
@@ -9,6 +9,15 @@
 // docs/superpowers/plans/2026-07-26-session-header-color-flag.md for the header
 // surface. `useColorFlag` is the shared reader both surfaces go through.
 //
+// DO NOT RENAME the `Settings.dispatchColorFlags` key to drop the now-misleading
+// "dispatch" prefix. The key name is itself persisted — it is what the flags are
+// stored under in the zustand-persisted settings blob — so renaming it silently
+// orphans every flag a user has already set unless it comes with a
+// PERSIST_VERSION bump and a migration. The prefix is historical (the feature
+// shipped in Dispatch first) and is not a claim about where the flag renders;
+// the same applies to the `dispatch.color-flag.set` command id, which keys
+// `Settings.commandVisibilityOverrides`.
+//
 // WHY a fixed palette rather than a free RGB/hex picker: the whole point is
 // fast visual triage of a list, and a small set of high-contrast, distinct
 // hues is both quicker to pick and easier to tell apart at a 10px strip than
diff --git a/src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts b/src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts
index e4ec95d2..796684a4 100644
--- a/src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts
+++ b/src/renderer/src/features/workspace/commands/dispatchColorFlagCommands.ts
@@ -1,7 +1,7 @@
 import type { CommandDef } from '@renderer/features/command-palette/types'
 import { commandTargetSessionId } from '@renderer/workspace/hook/selectors/commandTargetSessionId'
 
-// "Set color flag" — mark the currently-commanded agent with a color, so it's
+// "Set Color Flag…" — mark the currently-commanded agent with a color, so it's
 // easy to spot while scanning many running workflows. It renders as a strip on
 // the right edge of the agent's Dispatch row and as a chunk of its pane's
 // session header. See docs/plans_and_ideas/2026-07-23-dispatch-color-flags.md
@@ -15,24 +15,28 @@ import { commandTargetSessionId } from '@renderer/workspace/hook/selectors/comma
 // `commandTargetSessionId` (Dispatch-aware focus), so it needs no separate row
 // selection. No keybind by design — a low-frequency, list-management action.
 //
-// The export, the command id, and the settings key all still say "dispatch"
-// even though the flag now renders in the pane header too. Both names are
-// persisted identifiers, not descriptions: the command id keys
-// `Settings.commandVisibilityOverrides` and the settings key holds the flags
-// themselves, so renaming either costs a migration and can silently drop a
-// user's saved command-visibility choices. The name is historical — the feature
-// was born in Dispatch. Treat "dispatch color flag" as the concept's proper
-// noun, not as a claim about where it renders.
+// The command id and the settings key both still say "dispatch" even though
+// the flag now renders in the pane header too. Neither is a description — both
+// are persisted identifiers: the id keys `Settings.commandVisibilityOverrides`,
+// so renaming it silently drops a user's saved show/hide choices, and the key
+// holds the flags themselves, so renaming it costs a PERSIST_VERSION migration.
+// The name is historical — the feature was born in Dispatch. Treat "dispatch
+// color flag" as the concept's proper noun, not as a claim about where it
+// renders. (The exported symbol below shares the prefix for consistency only;
+// it is not persisted and can be renamed freely.)
 //
 // No getState chip: the current flag is already visible on the row and in the
-// pane header, and
-// the command context does not carry the settings store, so surfacing it here
-// would mean threading settings into every command's context for one label.
+// pane header, and the command context does not carry the settings store, so
+// surfacing it here would mean threading settings into every command's context
+// for one label.
 export const dispatchColorFlagCommands: CommandDef[] = [
   {
     id: 'dispatch.color-flag.set',
     surface: 'session',
-    title: 'Set color flag',
+    // Title case + ellipsis per docs/command-style.md rules 8 and 9: `run`
+    // always opens the swatch picker, so the command needs more input after
+    // invocation and must advertise that.
+    title: 'Set Color Flag…',
     description:
       '**What it does:** Marks the focused agent with a color — a chunk of its ' +
       '**session header** in the grid, and a strip on the right edge of its ' +
diff --git a/src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx b/src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx
index da2bbb26..656c4fb5 100644
--- a/src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx
+++ b/src/renderer/src/workspace/dispatch/DispatchColorFlagStrip.tsx
@@ -16,6 +16,17 @@ import type { SessionId } from '@renderer/workspace/types'
 // The settings lookup itself now lives in `useColorFlag` because the pane
 // header reads the same state with different geometry; only the geometry below
 // is Dispatch-specific.
+//
+// WHY this one keeps `pointer-events-none` and gets no `title`, while its pane
+// header counterpart takes the opposite choice: this strip sits INSIDE the
+// Dispatch row's <button>, which already carries a richer tooltip (the agent
+// label, title, and detached state — DispatchAgentList.tsx / DispatchMiniList.tsx).
+// A `title` here would not add information, it would REPLACE that tooltip for
+// the 10px the strip covers, so hovering the right edge of a row would tell you
+// less than hovering anywhere else in it. Swallowing pointer events keeps the
+// row's own hover and tooltip intact across its full width. The pane header has
+// no such competing tooltip on its right edge, which is why the chunk there can
+// afford one.
 export const DispatchColorFlagStrip = memo(function DispatchColorFlagStrip({
   sessionId,
 }: {
diff --git a/src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx b/src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx
index 3e72cbae..67c37bc6 100644
--- a/src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx
+++ b/src/renderer/src/workspace/dispatch/DispatchColorFlags.renderer.test.tsx
@@ -169,6 +169,27 @@ describe('Session header color flag', () => {
     expect(chunk).toHaveClass('w-1/4', 'flex-none', 'self-stretch')
     expect(chunk).not.toHaveClass('absolute')
     expect(chunk).toHaveStyle({ backgroundColor: '#ef4444' })
+    // The seam that keeps the chunk legible when the user's accent shares a hue
+    // with their flag color — without it a live pane can swallow the flag whole.
+    expect(chunk).toHaveClass('border-l', 'border-canvas')
+    // Hoverable on purpose: the tooltip is the only way to tell red from green
+    // apart for a colorblind user, and `pointer-events-none` would kill it.
+    expect(chunk).toHaveAttribute('title', 'Red flag')
+    expect(chunk).not.toHaveClass('pointer-events-none')
+  })
+
+  it('puts the chunk at the far right of the header, not beside the label', () => {
+    setColorFlags({ [FLAGGED_SESSION_ID]: 'red' })
+    const { container } = renderHeader(FLAGGED_SESSION_ID, true)
+
+    // WHY assert `justify-between` explicitly: it is the ONLY thing placing the
+    // chunk at the right edge. Every other assertion in this block passes with
+    // the chunk sitting in the middle of the header, immediately after the
+    // label group — which is the single most likely way to break this feature
+    // while keeping it looking implemented.
+    const row = container.querySelector<HTMLElement>('[data-pane-header-row="true"]')
+    expect(row).toHaveClass('justify-between')
+    expect(row?.lastElementChild).toHaveAttribute('data-pane-color-flag', 'red')
   })
 
   it('renders no chunk at all for an unflagged session', () => {
@@ -180,19 +201,54 @@ describe('Session header color flag', () => {
     // chunk, so there is no cross-row alignment to preserve, and reserving a
     // quarter of every header would permanently squeeze the project dir for a
     // signal that is switched off.
+    //
+    // Note this renders the UNFLAGGED session while a different session is
+    // flagged, so it also proves the chunk is keyed by session id rather than
+    // rendering for whatever flag happens to exist in settings.
     expect(container.querySelector('[data-pane-color-flag]')).toBeNull()
   })
 
-  it('keeps the row padding on the label group so the chunk can bleed to the pane edge', () => {
+  it('drops a stale persisted flag id instead of rendering a broken chunk', () => {
+    // The headline justification for routing both surfaces through
+    // `useColorFlag`: a palette entry removed in a future version leaves this
+    // id behind in persisted settings, and every reader must degrade to "no
+    // flag" rather than throwing or painting `undefined`.
+    setColorFlags({ [FLAGGED_SESSION_ID]: 'chartreuse' })
+    const { container } = renderHeader(FLAGGED_SESSION_ID, true)
+
+    expect(container.querySelector('[data-pane-color-flag]')).toBeNull()
+  })
+
+  it('carries all header padding on the label group so the chunk can bleed to every edge', () => {
     setColorFlags({ [FLAGGED_SESSION_ID]: 'purple' })
     const { container } = renderHeader(FLAGGED_SESSION_ID, false)
 
+    // The row must stay bare: `self-stretch` fills the row's CONTENT box, so
+    // any padding here becomes a gap the chunk cannot cross. `pl-3` in
+    // particular also shrinks the chunk, since `w-1/4` resolves against the
+    // content box.
     const row = container.querySelector<HTMLElement>('[data-pane-header-row="true"]')
-    expect(row).toHaveClass('pl-3')
     expect(row).not.toHaveClass('px-3')
+    expect(row).not.toHaveClass('pl-3')
     expect(row).not.toHaveClass('py-1')
-    // The vertical padding still exists — it moved one level down, so the
-    // header's rendered height is unchanged while the chunk stretches full-bleed.
-    expect(row?.firstElementChild).toHaveClass('py-1')
+    // ...and the padding must still exist one level down, so the header's
+    // rendered height and the label's insets are unchanged from before the
+    // chunk existed. `px-3` is what keeps the project dir off the pane edge on
+    // UNFLAGGED panes, where no chunk mounts to stand in for it.
+    expect(row?.firstElementChild).toHaveClass('px-3', 'py-1')
+  })
+
+  it('keeps Status Mode compact by dropping the label group to zero vertical padding', () => {
+    // Status Mode's whole point is a ~5px glance strip. An unconditional `py-1`
+    // on the group silently grows it to a 24px bar, which no other assertion in
+    // this block would catch — the padding case above runs with statusMode off,
+    // where `py-1` is correct.
+    setColorFlags({ [FLAGGED_SESSION_ID]: 'purple' })
+    const { container } = renderHeader(FLAGGED_SESSION_ID, true)
+
+    const row = container.querySelector<HTMLElement>('[data-pane-header-row="true"]')
+    expect(row).toHaveClass('min-h-[5px]')
+    expect(row?.firstElementChild).toHaveClass('py-0')
+    expect(row?.firstElementChild).not.toHaveClass('py-1')
   })
 })
diff --git a/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx
index 76b1bd77..aaa3efe1 100644
--- a/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx
+++ b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx
@@ -18,6 +18,16 @@ import type { SessionRuntime } from '@renderer/workspace/workspaceStore'
 // overlap: liveness is automatic and transient, the flag is manual and sticky,
 // so a user who flagged a pane red wants that red regardless of whether the
 // agent happens to be running right now. The flag always wins its slice.
+//
+// That does put color back onto idle panes, which is in tension with the
+// paragraph above — a red chunk on an idle pane is exactly the shape of the
+// green/red design we abandoned. It is accepted here, and the difference is
+// authorship: the old red was assigned automatically and therefore had to be
+// read as a status claim ("something is wrong with this pane"), while a flag
+// is one the user set by hand for their own reason and is self-explanatory to
+// the only person who can see it. If flags ever become automatic — assigned by
+// a rule, a provider, or an agent — this reasoning expires and the overlap
+// must be revisited.
 export function PaneHeader({
   sessionId,
   paneLabel,
@@ -45,7 +55,7 @@ export function PaneHeader({
     <div className="border-b border-border bg-surface text-muted font-code select-none">
       <div
         data-pane-header-row="true"
-        className={`flex items-center justify-between pl-3 text-[10px] ${
+        className={`flex items-center justify-between text-[10px] ${
           statusMode
             ? isSessionLive
               ? 'bg-accent text-accent-fg'
@@ -53,19 +63,35 @@ export function PaneHeader({
             : 'bg-surface text-muted'
         } ${statusMode ? 'min-h-[5px]' : ''}`}
       >
-        {/* WHY the vertical padding sits on this group instead of on the row:
-            the color-flag chunk uses `self-stretch`, which fills the row's
-            CONTENT box — with `py-1` on the row the chunk would float with a
-            4px gap above and below and read as a floating pill rather than a
-            slice of the header. Pushing the padding one level down keeps the
-            header's rendered height byte-for-byte identical (the same 4px still
-            exists, just inside this child) while letting the chunk bleed from
-            the top edge of the header to the bottom. The row also drops its
-            right padding — `px-3` became `pl-3` — so the chunk reaches the pane
-            edge without an absolute overlay or a negative margin, per the
-            layout contract in
-            docs/plans_and_ideas/2026-07-23-color-flag-layout-follow-up.md. */}
-        <div className={`flex items-center gap-2 min-w-0 ${statusMode ? 'py-0' : 'py-1'}`}>
+        {/* WHY ALL of the row's padding moved down onto this group — the row
+            used to be `px-3 py-1` and is now bare:
+
+            The color-flag chunk is a sibling flex child that must bleed to all
+            three outer edges of the header. `self-stretch` fills the row's
+            CONTENT box, so any padding left on the ROW becomes a gap the chunk
+            cannot cross — `py-1` would float it 4px off the top and bottom
+            (reading as a pill, not a slice of the header) and `pr-3` would hold
+            it 12px short of the pane edge. Moving the padding one level down
+            satisfies the layout contract in
+            docs/plans_and_ideas/2026-07-23-color-flag-layout-follow-up.md
+            (flags participate in flex layout; no absolute overlay, no negative
+            margin, no painting over padding) while keeping the header's
+            rendered height and the label's insets byte-for-byte identical to
+            before — the same 12px and 4px still exist, just inside this child.
+
+            The first pass moved only `py` and changed `px-3` to `pl-3`, which
+            silently deleted the right inset for UNFLAGGED panes, since the
+            chunk that was supposed to stand in for it does not mount when
+            there is no flag. Measured on a 100px-wide pane, the truncated
+            project dir went from 12px off the pane edge to 0px. Keeping `px-3`
+            here instead means the inset survives with or without a flag, and
+            the text keeps a real gap from the chunk rather than butting
+            against it. Do not move padding back onto the row.
+
+            It also makes the chunk's `w-1/4` a true quarter of the header:
+            percentage widths resolve against the row's content box, so with
+            `pl-3` still on the row the chunk was 25% of (W − 12px). */}
+        <div className={`flex items-center gap-2 min-w-0 px-3 ${statusMode ? 'py-0' : 'py-1'}`}>
           {paneLabel && (
             <span className="flex-shrink-0 rounded-[3px] border border-current/30 px-1 leading-[14px] text-[9px] font-semibold tabular-nums">
               {paneLabel}
diff --git a/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx
index 75f30e41..c8bdc794 100644
--- a/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx
+++ b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeaderColorFlag.tsx
@@ -24,8 +24,32 @@ import type { SessionId } from '@renderer/workspace/types'
 //
 // `self-stretch` (not a fixed height) is what makes it overlap the status
 // strip: in Status Mode the header row collapses to ~5px, and the chunk paints
-// over the right quarter of the accent fill. `flex-none` keeps it at exactly
-// 25% instead of letting the truncating label group push it around.
+// over the right quarter of the accent fill. `flex-none` stops the truncating
+// label group from squeezing it — without it the chunk is a shrinkable flex
+// item and a long project dir would eat into it. The quarter is a true quarter
+// of the header only because PaneHeader keeps its row unpadded; percentage
+// widths resolve against the parent's content box, so padding on the row would
+// silently shrink this.
+//
+// WHY the 1px `border-l border-canvas` seam: the flag colors are raw hex while
+// the strip behind them is `bg-accent`, a USER-CHOSEN theme token — and every
+// shipped accent preset shares a hue family with at least one flag color
+// (coral/red, gold/yellow, amber/orange, sky/blue, lavender/purple,
+// lime/green). Without a seam, a user whose accent matches their flag gets no
+// signal at all on a live pane, which is the exact moment the flag matters
+// most. `canvas` is near-black in dark and near-white in light, so the seam
+// separates the chunk from both the accent fill and `bg-surface` in either
+// theme. It is 1px inside the chunk's own box, so it costs no layout width.
+//
+// WHY `title` but still `aria-hidden`: the chunk is a redundant view of state
+// the user set themselves and can re-read in the picker, so exposing it to a
+// screen reader on every pane header would be noise. The tooltip is for a
+// different user — someone who can see the color but cannot name it (red and
+// green are the same hue to a deuteranope), for whom "Red flag" on hover is
+// the only way to tell two flagged panes apart. That is also why this element,
+// unlike DispatchColorFlagStrip, does NOT set `pointer-events-none`: a tooltip
+// requires hover. Click-to-focus still works — the mousedown bubbles to the
+// pane container's onFocusRequest in TileLeaf.
 export const PaneHeaderColorFlag = memo(function PaneHeaderColorFlag({
   sessionId,
 }: {
@@ -37,8 +61,9 @@ export const PaneHeaderColorFlag = memo(function PaneHeaderColorFlag({
   return (
     <span
       aria-hidden="true"
+      title={`${colorFlag.label} flag`}
       data-pane-color-flag={colorFlag.id}
-      className="pointer-events-none w-1/4 flex-none self-stretch"
+      className="w-1/4 flex-none self-stretch border-l border-canvas"
       style={{ backgroundColor: colorFlag.color }}
     />
   )