Show running-status chips on tracker board cards (#225)

* tracker: seed item files for running-status-chips

* add running-status chips to tracker board cards

Surface which of the agent / shell / run sessions are active for each
tracker item directly on the kanban card, mirroring the a/s/x cells in
the worktree mainview. Chips render only for active sessions, in fixed
order, with full-word labels (cyan/green/magenta) so they're readable
without a column header. The previous ◆ "has session" glyph is dropped
since the chips communicate that signal more precisely.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* move running-status chip row below secondary text

Render the chip row at the bottom of each card (after the secondary
status text and the approve-hint row) so the textual signals stay
prominent and the chips read as a footer rather than competing with
the slug for visual weight.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* hoist worktree lookup; use marginLeft for chip indent

Pulls a single getWorktreeForItem() call up to the top of the card
render block so prMerged, the chip computation, and the inlined
session-status filter all share one Map.get() instead of three. Also
swaps the four-space Text spacer for marginLeft={4} on the chip row,
matching how Ink Boxes are normally indented elsewhere.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* tracker: implementation notes + cleanup-stage status

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* update display-state test for dropped ◆ branch

The session-only assertion expected ◆/gray/'session idle', but with the
running-status chips taking over the session-presence signal the helper
now collapses session-only items to the idle/empty branch.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: agent-era-ai

src/screens/TrackerBoardScreen.tsx

@@ -13,6 +13,8 @@ import {startIntervalIfEnabled} from '../shared/utils/intervals.js';
 import {VISIBLE_STATUS_REFRESH_DURATION} from '../constants.js';
 import TrackerProjectPickerDialog from '../components/dialogs/TrackerProjectPickerDialog.js';
 import AIToolDialog from '../components/dialogs/AIToolDialog.js';
+import StatusChip from '../components/common/StatusChip.js';
+import {computeRunningChips} from './runningChips.js';
 
 interface TrackerBoardScreenProps {
   project: string;
@@ -152,20 +154,6 @@ export function getTrackerCardDisplayState({
     };
   }
 
-  if (hasSession) {
-    return {
-      statusGlyph: '◆',
-      statusColor: 'gray',
-      titleColor: inactive ? 'gray' : undefined,
-      titleBold: false,
-      secondaryText: itemStatusDescription || 'session idle',
-      secondaryColor: inactive ? 'gray' : undefined,
-      secondaryBold: false,
-      secondaryDim: true,
-      showApproveHint: false,
-    };
-  }
-
   return {
     statusGlyph: ' ',
     statusColor: inactive ? 'gray' : undefined,
@@ -756,7 +744,8 @@ export default function TrackerBoardScreen({
           {visibleItems.map((item, sliceIndex) => {
             const itemIndex = scrollTop + sliceIndex;
             const isSelected = isActiveColumn && selectedRow === itemIndex;
-            const sessWt = getSessionForItem(item);
+            const wt = getWorktreeForItem(item);
+            const sessWt = (wt?.session?.ai_status && wt.session.ai_status !== 'not_running') ? wt : null;
             const aiStatus: AIStatus | undefined = sessWt?.session?.ai_status;
             const aiWaiting = aiStatus === 'waiting';
             const isWorking = aiStatus === 'working' || aiStatus === 'active';
@@ -767,11 +756,15 @@ export default function TrackerBoardScreen({
             // "ready to advance" treatment so it's spottable at a glance and
             // can be acted on with the `m` shortcut from the board.
             const itemStatus = service.getItemStatus(projectPath, item.slug);
-            const prMerged = getWorktreeForItem(item)?.pr?.is_merged === true;
+            const prMerged = wt?.pr?.is_merged === true;
             const readyToAdvance = !prMerged && service.isItemReadyToAdvance(itemStatus);
             const ralphWaiting = !!itemStatus && !readyToAdvance && service.isItemWaiting(itemStatus);
             const isWaiting = aiWaiting || ralphWaiting;
 
+            // Session presence is now signalled by the running-status chip row
+            // (rendered separately below); the ◆ branch in
+            // getTrackerCardDisplayState is dropped to avoid duplicating that
+            // signal.
             const display = getTrackerCardDisplayState({
               prMerged,
               readyToAdvance,
@@ -781,6 +774,7 @@ export default function TrackerBoardScreen({
               inactive: item.inactive,
               itemStatusDescription: itemStatus?.brief_description,
             });
+            const runningChips = computeRunningChips(wt);
 
             // Slug row eats: 2 (border) + 2 (paddingX) + 2 (cursor) + 2 (status glyph) = 8 chars
             const slug = truncateDisplay(item.slug, Math.max(4, colWidth - 8));
@@ -811,7 +805,9 @@ export default function TrackerBoardScreen({
                   if (!text) return null;
                   // Focused card gets more lines so the full (up to 200-char)
                   // brief_description is readable; other cards stay compact.
-                  const maxLines = isSelected ? 4 : SECONDARY_MAX_LINES;
+                  // Chip row eats one of those lines when present.
+                  const baseMax = isSelected ? 4 : SECONDARY_MAX_LINES;
+                  const maxLines = Math.max(1, baseMax - (runningChips.length > 0 ? 1 : 0));
                   const lines = wrapToLines(text, secMax, maxLines);
                   return lines.map((line, lineIdx) => (
                     <Text
@@ -835,6 +831,22 @@ export default function TrackerBoardScreen({
                     {`    press [m] to approve and advance`}
                   </Text>
                 )}
+                {/* Running-status chips: one per active tmux session, rendered
+                    last so the card's textual signals (ready/waiting/working)
+                    stay above. Indented to match the secondary-text gutter.
+                    Eats one of the four rows budgeted per item, so secondary
+                    maxLines drops by 1 when chips render to keep scroll math
+                    intact. */}
+                {runningChips.length > 0 && (
+                  <Box marginLeft={4}>
+                    {runningChips.map((chip, idx) => (
+                      <React.Fragment key={chip.label}>
+                        {idx > 0 && <Text> </Text>}
+                        <StatusChip label={chip.label} color={chip.color} fg="white" />
+                      </React.Fragment>
+                    ))}
+                  </Box>
+                )}
               </Box>
             );
           })}

src/screens/runningChips.ts

@@ -0,0 +1,16 @@
+import type {WorktreeInfo} from '../models.js';
+
+export interface RunningChip {
+  label: string;
+  color: string;
+}
+
+export function computeRunningChips(worktree: WorktreeInfo | null | undefined): RunningChip[] {
+  const session = worktree?.session;
+  if (!session) return [];
+  const chips: RunningChip[] = [];
+  if (session.attached) chips.push({label: 'agent', color: 'cyan'});
+  if (session.shell_attached) chips.push({label: 'shell', color: 'green'});
+  if (session.run_attached) chips.push({label: 'run', color: 'magenta'});
+  return chips;
+}

tests/unit/TrackerBoardScreen.test.ts

@@ -104,17 +104,17 @@ describe('getTrackerCardDisplayState', () => {
     });
   });
 
-  test('session-only item is dim with no secondary color', () => {
+  test('session-only item collapses to the idle/empty branch (chips below the card carry the session signal)', () => {
     const display = getTrackerCardDisplayState({
       ...baseFlags,
       hasSession: true,
     });
 
     expect(display).toMatchObject({
-      statusGlyph: '◆',
-      statusColor: 'gray',
+      statusGlyph: ' ',
+      statusColor: undefined,
       titleColor: undefined,
-      secondaryText: 'session idle',
+      secondaryText: '',
       secondaryColor: undefined,
       secondaryDim: true,
       showApproveHint: false,

tests/unit/runningChips.test.ts

@@ -0,0 +1,65 @@
+import {describe, test, expect} from '@jest/globals';
+import {computeRunningChips} from '../../src/screens/runningChips.js';
+import {WorktreeInfo, SessionInfo} from '../../src/models.js';
+
+function wt(session: Partial<SessionInfo>): WorktreeInfo {
+  return new WorktreeInfo({
+    project: 'p',
+    feature: 'f',
+    path: '/p/f',
+    session: new SessionInfo({session_name: 's', ai_status: 'idle', ai_tool: 'none', ...session}),
+  });
+}
+
+describe('computeRunningChips', () => {
+  test('all three flags active → agent, shell, run in fixed order', () => {
+    const chips = computeRunningChips(wt({attached: true, shell_attached: true, run_attached: true}));
+    expect(chips).toEqual([
+      {label: 'agent', color: 'cyan'},
+      {label: 'shell', color: 'green'},
+      {label: 'run', color: 'magenta'},
+    ]);
+  });
+
+  test('only shell_attached → only shell chip', () => {
+    const chips = computeRunningChips(wt({attached: false, shell_attached: true, run_attached: false}));
+    expect(chips).toEqual([{label: 'shell', color: 'green'}]);
+  });
+
+  test('only attached (agent) → only agent chip', () => {
+    const chips = computeRunningChips(wt({attached: true, shell_attached: false, run_attached: false}));
+    expect(chips).toEqual([{label: 'agent', color: 'cyan'}]);
+  });
+
+  test('only run_attached → only run chip', () => {
+    const chips = computeRunningChips(wt({attached: false, shell_attached: false, run_attached: true}));
+    expect(chips).toEqual([{label: 'run', color: 'magenta'}]);
+  });
+
+  test('agent + run (no shell) preserves fixed order with shell skipped', () => {
+    const chips = computeRunningChips(wt({attached: true, shell_attached: false, run_attached: true}));
+    expect(chips).toEqual([
+      {label: 'agent', color: 'cyan'},
+      {label: 'run', color: 'magenta'},
+    ]);
+  });
+
+  test('worktree linked but no sessions running → []', () => {
+    const chips = computeRunningChips(wt({attached: false, shell_attached: false, run_attached: false}));
+    expect(chips).toEqual([]);
+  });
+
+  test('null worktree (no link) → []', () => {
+    expect(computeRunningChips(null)).toEqual([]);
+  });
+
+  test('undefined worktree → []', () => {
+    expect(computeRunningChips(undefined)).toEqual([]);
+  });
+
+  test('worktree with no session → []', () => {
+    const w = new WorktreeInfo({project: 'p', feature: 'f', path: '/p/f'});
+    (w as any).session = undefined;
+    expect(computeRunningChips(w)).toEqual([]);
+  });
+});

tracker/items/running-status-chips/implementation.md

@@ -0,0 +1,28 @@
+# Implementation — running-status-chips
+
+## What was built
+
+- `src/screens/runningChips.ts` — pure helper `computeRunningChips(worktree)` returning `[]` or an ordered subset of `[{label: 'agent', color: 'cyan'}, {label: 'shell', color: 'green'}, {label: 'run', color: 'magenta'}]` based on `session.attached / shell_attached / run_attached`. Pure and unit-tested.
+- `src/screens/TrackerBoardScreen.tsx`:
+  - Imports `computeRunningChips` and the existing `StatusChip` common component.
+  - Renders a chip row directly under each card's slug row, indented to the same `    ` (four-space) gutter as the existing secondary text. Hidden when `computeRunningChips` returns `[]` (covers both "no linked worktree" and "all flags false").
+  - When a chip row is present, the secondary-text `maxLines` is reduced by 1 (to `1` for unselected, `3` for selected) so each card stays within the existing 4-row scroll budget. Long `brief_description` strings still get most of the space.
+  - Drops the `◆` "has session" branch from `statusGlyph` / `statusColor`. The `✓` / `!` / `⟳` branches (and their colors) are unchanged.
+- `tests/unit/runningChips.test.ts` — nine cases covering all-three / single-flag / agent+run / no sessions / null / undefined / no-session worktree.
+
+## Key decisions
+
+1. **Reused `StatusChip` rather than `SessionCell`.** SessionCell hard-codes `#005f87` blue and is single-letter only. Per the user's requirements (full word labels, distinct color per session type), StatusChip's flexible `color`/`fg`/`label` props were the better fit, and it already produces a centered `␣label␣` rendering with a colored background. SessionCell is left untouched for the mainview.
+2. **Active-only rendering.** No bracket/placeholder for inactive sessions. With three single-color chips removed, "absent" reads as "not running" cleanly. Combined with hiding the row entirely when nothing is active, cards stay compact.
+3. **4-row budget preserved.** Adding the chip row would have pushed each card to 5 rows and broken the column scroll math (`ROWS_PER_ITEM = 4` drives `visibleItemSlots`). Trading one secondary-text line for the chip row keeps everything aligned. The first secondary line — typically the most useful — is kept.
+4. **No data plumbing changes.** `getWorktreeForItem` was already on the screen and returns the unfiltered linked worktree (unlike `getSessionForItem`, which filters to `ai_status !== 'not_running'`). Using it means a card with only a shell or run session still lights up its chips even when the agent is idle.
+
+## Notes for cleanup
+
+- `hasSession` is still used by the secondary-text logic (line ~720) to decide between `'session idle'` vs `secondary` when there's no ralph status. That's intentional and out of scope for this item — the chips handle the visual signal, the secondary text still uses session presence as a fallback content selector.
+- `secondary = !hasSession ? renderSecondary(item) : ''` continues to suppress secondary metadata when a session exists; that behavior is unchanged.
+- I did not manually launch the CLI to view the chips against a live tmux session — only unit tests + `npm run typecheck` were run. Pure helper covers the chip-list logic exhaustively; the rendering is a thin `runningChips.map(...)` over StatusChip with no conditional logic worth eyeballing.
+
+## Stage review
+
+Built the chip helper, wired it into the board card, dropped the redundant ◆ glyph, and added 9 unit tests for the helper. `npm test` (702 tests across 72 suites) and `npm run typecheck` both pass. Committed as e7bdaa1.

tracker/items/running-status-chips/notes.md

@@ -0,0 +1,37 @@
+# Discovery — running-status-chips
+
+## Problem
+
+Tracker board cards don't show which of the three tmux sessions (agent / shell / execution) are actually running for an item. The mainview already exposes this with the `[a] [s] [x]` chips, but the kanban only shows a single status glyph (✓ / ! / ⟳ / ◆ / blank), which collapses three independent flags into one.
+
+## Why
+
+A user scanning the kanban can't tell at a glance whether a card has only an agent attached, only a shell, both, plus a run session, etc. That's information they already get on the worktree list and would expect to see on the board, especially when triaging which item to attach to.
+
+## Findings
+
+### Existing chip pattern (mainview)
+- The a/s/x indicators in MainView are *not* `StatusChip` — they're rendered by `renderSessionCell()` in `src/components/views/MainView/SessionCell.tsx:7-27`.
+- Active: solid `#005f87` blue bg, bold white ` a `/` s `/` x `.
+- Inactive: dimmed `[a]/[s]/[x]` brackets (or inverted on selected/dimmed rows).
+- WorktreeRow wires three flags from `worktree.session`: `attached` (agent), `shell_attached` (shell), `run_attached` (run/execution) — `WorktreeRow.tsx:63-65`.
+
+### Data linkage already exists on the board
+- `TrackerBoardScreen.tsx:146-159` builds `sessionMap: slug → WorktreeInfo`. Tracker item slug == worktree feature name.
+- `getWorktreeForItem(item)` returns the linked WorktreeInfo regardless of AI status.
+- `getSessionForItem(item)` is the *filtered* version (only when `ai_status !== 'not_running'`) — used for the existing ◆/⟳/! glyph logic.
+- For chips we want the unfiltered `getWorktreeForItem` so a shell-only or run-only worktree still lights up s/x even when the agent is idle.
+
+### Card layout & space budget
+- Cards are columns; column width is variable but tight. Slug row currently eats ~8 chars: `▸ ` + glyph + space + slug. `TrackerBoardScreen.tsx:677-678`.
+- Three SessionCell-style chips at width 3 each = 9 chars (or 6 if we tighten to ` a ` without bracket padding for inactive).
+- Two reasonable placements: (a) next to the slug on the same row (eats more of the slug width); (b) dedicated mini-row beneath the slug, before/replacing the secondary description line for cards with sessions.
+
+### Open design questions (for requirements stage)
+1. Placement: same row as slug, or dedicated row?
+2. When no worktree is linked (item never had a session): hide chips entirely, or show three dim placeholders?
+3. Coexistence with existing status glyph (✓/!/⟳/◆): keep both, or do chips subsume ◆ ("has session")?
+
+## Recommendation
+
+Reuse `renderSessionCell` directly (it's the same primitive the mainview uses, so visual consistency is free). Render in a dedicated mini-row right under the slug, only when the item has a linked worktree. Keep the existing ✓/!/⟳ status glyph since it conveys ralph/AI state, but drop the redundant ◆ glyph (chips communicate "session present" more precisely). These are tentative; will confirm in requirements.

tracker/items/running-status-chips/requirements.md

@@ -0,0 +1,32 @@
+---
+title: "items should show which of the agent, session, execution are running. similar to the mainview. maybe use the same kind of 'chips' with colored bgs"
+slug: running-status-chips
+updated: 2026-04-26
+---
+
+## Problem
+
+Tracker board cards don't show which of the three tmux sessions (agent / shell / execution) are actually running for an item. The mainview already exposes this with the `[a] [s] [x]` chips, but the kanban only shows a single status glyph (✓ / ! / ⟳ / ◆ / blank), which collapses three independent flags into one.
+
+## Why
+
+A user scanning the kanban can't tell at a glance whether a card has only an agent attached, only a shell, both, plus a run session, etc. That's information they already get on the worktree list and would expect to see on the board, especially when triaging which item to attach to.
+
+## Summary
+
+Add a per-card "running" mini-row to `TrackerBoardScreen` that renders one labeled, colored chip per active tmux session — `agent` (cyan), `shell` (green), `run` (magenta) — using the same `getWorktreeForItem` linkage the board already builds. The row is active-only: hidden when the item has no linked worktree, and hidden again when all three session flags are false. The existing `◆` "has session" status glyph is dropped because the chips communicate the same thing more precisely; the other status glyphs (`✓` / `!` / `⟳`) remain since they convey ralph/AI state, not session presence.
+
+## Acceptance criteria
+
+1. A tracker card on `TrackerBoardScreen` whose linked worktree has `session.attached === true` renders a chip labeled `agent` with a cyan (`cyan`) background and white foreground.
+2. A tracker card whose linked worktree has `session.shell_attached === true` renders a chip labeled `shell` with a green (`green`) background and white foreground.
+3. A tracker card whose linked worktree has `session.run_attached === true` renders a chip labeled `run` with a magenta (`magenta`) background and white foreground.
+4. Chips render in fixed order — `agent`, `shell`, `run` — with a single space between adjacent chips. Inactive sessions are omitted (no placeholder chip, no bracketed `[a]/[s]/[x]` form).
+5. The chip row is rendered as a dedicated line directly beneath the slug row and above the existing secondary/description text. It is indented to the same `    ` (four-space) gutter the secondary lines already use.
+6. The chip row is hidden entirely when no worktree is linked to the item (i.e., `getWorktreeForItem(item)` returns `undefined`).
+7. The chip row is hidden entirely when a worktree is linked but all three of `attached`, `shell_attached`, `run_attached` are false.
+8. Chip backgrounds remain at their session colors regardless of whether the card is currently selected — mirroring how `SessionCell` keeps `#005f87` for active sessions across selection states. The slug row's existing selection/inverse treatment is unchanged.
+9. The `◆` "has session" branch of the existing status-glyph logic in `TrackerBoardScreen.tsx` is removed: when the only positive signal would have been `hasSession`, the glyph cell renders a space (as it already does for fully-inactive cards). The `✓`, `!`, and `⟳` branches and their associated colors are unchanged.
+10. The wider behavior of `getSessionForItem` (used elsewhere on the board for ralph/AI status decisions) is untouched. The chip row uses `getWorktreeForItem` so a worktree with `ai_status === 'not_running'` but a live shell or run session still surfaces its chips.
+11. Unit / e2e tests cover: (a) all three sessions active → all three chips render in order; (b) only `shell_attached` → only the `shell` chip renders; (c) no linked worktree → no chip row in the card output; (d) worktree linked but no sessions → no chip row.
+12. `npm test` and `npm run typecheck` both pass.

tracker/items/running-status-chips/status.json

@@ -0,0 +1,6 @@
+{
+  "stage": "cleanup",
+  "state": "waiting_for_approval",
+  "brief_description": "feature shipped on commit e7bdaa1; 702 tests pass; awaiting approval to archive + open PR",
+  "timestamp": "2026-04-26T00:40:00Z"
+}