feat(fleet-pane-health): add KIND column + group-by-kind toggle

openspec/changes/agent-claude-fleet-pane-health-badge-column-2026-05-16-00-22/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-15

openspec/changes/agent-claude-fleet-pane-health-badge-column-2026-05-16-00-22/proposal.md

@@ -0,0 +1,19 @@
+## Why
+
+- `fleet-pane-health` lists every tmux pane in the fleet session but does not surface which agent kind (codex / kiro / claude) owns the pane. The operator has to infer it from the `@panel` label, which is fine for the three present codex panels but breaks down once the fleet runs a mix of all three.
+- A single-glance distinction between codex, kiro and claude is the most-asked-for improvement to the live dashboard — see `scripts/codex-fleet/full-bringup.sh` already spawning all three kinds.
+
+## What Changes
+
+- Add an `AgentKind` classifier (`codex` / `kiro` / `claude` / `unknown`) that derives the kind from the `@panel` label first and falls back to the `/tmp/claude-viz/{codex,kiro,claude}-worker-*.log` filename.
+- Render a new `KIND` column between `PANE` and `PANEL` showing a colored badge (`CODX` blue / `KIRO` purple / `CLAU` orange) on each row.
+- Add a `g` keybinding that toggles a grouped view: rows are sorted by kind and a `── group: <kind> ──` header (in the kind's tint) is injected between groups.
+- Footer reports `g group: on|off` so the current view mode is always visible.
+- Cover the classifier and the grouped/ungrouped renderers with unit tests plus a ratatui `TestBackend` integration test that asserts each kind's badge and group header lands in the rendered buffer.
+
+## Impact
+
+- Surfaces affected: `rust/fleet-pane-health/src/main.rs` only (no schema, no shared crate). Read-only data paths unchanged.
+- Risk: low. The classifier is panel-driven so a stale log file cannot mis-label a pane. The grouping toggle starts off, preserving the existing row order at startup.
+- Rollout: ship in the next PR; no scripts, supervisors, or config need to change.
+- Follow-ups (not in this change): a `f` keybinding to filter to one kind; pulling the badge widget into `fleet-ui` once a second consumer needs it.

openspec/changes/agent-claude-fleet-pane-health-badge-column-2026-05-16-00-22/specs/fleet-pane-health-badge-column/spec.md

@@ -0,0 +1,44 @@
+## ADDED Requirements
+
+### Requirement: AgentKind classification for fleet-pane-health rows
+The `fleet-pane-health` dashboard SHALL classify every pane it lists into one of `codex`, `kiro`, `claude`, or `unknown`. The classifier SHALL derive the kind from the `@panel` label first (substring match on `codex` / `kiro` / `claude`, case-insensitive) and SHALL fall back to the `/tmp/claude-viz/{codex,kiro,claude}-worker-*.log` filename prefix only when the panel label is empty or unrecognised. Panel-derived classification SHALL win over log-derived classification when both are available.
+
+#### Scenario: Panel label drives classification
+- **WHEN** a pane has `@panel = "codex-admin-mite"`
+- **THEN** its kind is `codex`
+- **AND** the row renders with the `CODX` badge in the `KIND` column.
+
+#### Scenario: Log filename fallback when panel is blank
+- **WHEN** a pane has no `@panel` label and the freshest matching log file is named `kiro-worker-foo.log`
+- **THEN** its kind is `kiro`
+- **AND** the row renders with the `KIRO` badge.
+
+#### Scenario: Unknown when neither signal matches
+- **WHEN** a pane has neither a recognised panel label nor a matching worker log
+- **THEN** its kind is `unknown`
+- **AND** the row renders the `—` badge in the `KIND` column.
+
+### Requirement: KIND column rendering
+The dashboard SHALL render a `KIND` column between `PANE` and `PANEL`. The column SHALL show the kind's four-character badge (`CODX`, `KIRO`, `CLAU`, or `—`) in the kind's tint colour (`IOS_TINT`, `IOS_PURPLE`, `IOS_ORANGE`, `IOS_FG_FAINT` respectively).
+
+#### Scenario: Column heading present
+- **WHEN** the dashboard renders any frame
+- **THEN** the column-headings row includes the literal `KIND` between `PANE` and `PANEL`.
+
+### Requirement: Group-by-kind toggle
+The dashboard SHALL support a grouped view, toggled by pressing `g` or `G`. When grouped, rows SHALL be sorted by kind in the order `codex`, `kiro`, `claude`, `unknown`, and a `── group: <kind> ──` header SHALL be inserted before each group of rows. The header SHALL render in the kind's tint colour. The footer SHALL show `g group: on` when grouped and `g group: off` otherwise.
+
+#### Scenario: Toggling grouping injects headers
+- **WHEN** the user presses `g` from the default (ungrouped) view
+- **THEN** the next frame shows `── group: codex ──` (and equivalent headers for any other kinds present) and the footer reads `g group: on`.
+
+#### Scenario: Toggling back removes headers
+- **WHEN** the user presses `g` again from the grouped view
+- **THEN** no `── group: ──` header rows appear in the next frame and the footer reads `g group: off`.
+
+### Requirement: Read-only data flow preserved
+This change SHALL NOT introduce any new writes to `/tmp/claude-viz`, any new tmux commands, or any new external processes. All data sources remain best-effort reads as before.
+
+#### Scenario: No writes to /tmp/claude-viz
+- **WHEN** the dashboard runs for any length of time
+- **THEN** no file under `/tmp/claude-viz` is created, modified, or deleted by `fleet-pane-health`.

openspec/changes/agent-claude-fleet-pane-health-badge-column-2026-05-16-00-22/tasks.md

@@ -0,0 +1,35 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-claude-fleet-pane-health-badge-column-2026-05-16-00-22`; branch=`agent/<your-name>/<branch-slug>`; scope=`TODO`; action=`continue this sandbox or finish cleanup after a usage-limit/manual takeover`.
+- Copy prompt: Continue `agent-claude-fleet-pane-health-badge-column-2026-05-16-00-22` on branch `agent/<your-name>/<branch-slug>`. Work inside the existing sandbox, review `openspec/changes/agent-claude-fleet-pane-health-badge-column-2026-05-16-00-22/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-claude-fleet-pane-health-badge-column-2026-05-16-00-22`.
+- [x] 1.2 Define normative requirements in `specs/fleet-pane-health-badge-column/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Implement scoped behavior changes (AgentKind classifier, KIND column, `g` toggle, footer state).
+- [x] 2.2 Add/update focused regression coverage (5 classifier/grouping unit tests + 2 ratatui `TestBackend` render tests).
+
+## 3. Verification
+
+- [x] 3.1 `cargo test -p fleet-pane-health` → 10 passed, 0 failed.
+- [x] 3.2 Live verification: respawn the `viz` tmux window with the patched binary, confirm `CODX`/`CLAU` badges render and `g` toggles `── group: codex ──` headers.
+- [x] 3.3 Run `openspec validate agent-claude-fleet-pane-health-badge-column-2026-05-16-00-22 --type change --strict` → `Change ... is valid`.
+- [x] 3.4 Run `openspec validate --specs` → `No items found to validate` (no archived specs in this repo yet).
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/README.md

@@ -0,0 +1,30 @@
+# Plan Workspace: agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22
+
+This folder stores durable planning artifacts before implementation changes.
+
+## Shared files
+- `summary.md`
+- `checkpoints.md`
+- `phases.md`
+- `open-questions.md`
+- `coordinator-prompt.md`
+- `kickoff-prompts.md`
+
+## Role folders
+- `planner/`
+- `architect/`
+- `critic/`
+- `executor/`
+- `writer/`
+- `verifier/`
+
+When Codex or Claude hits an unresolved question that should survive chat, add it to `open-questions.md` as an unchecked `- [ ]` item.
+
+Each role folder contains OpenSpec-style artifacts:
+- `.openspec.yaml`
+- `prompt.md` (copy/paste role prompt)
+- `proposal.md`
+- `tasks.md` (Spec / Tests / Implementation / Checkpoints checklists)
+- `specs/<role>/spec.md`
+Planner also gets `plan.md`; executor also gets `checkpoints.md`.
+Planner plans should follow `openspec/plan/PLANS.md`.

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/architect/.openspec.yaml

@@ -0,0 +1,9 @@
+schema: 1
+plan: agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22
+role: architect
+status: draft
+artifacts:
+  prompt: prompt.md
+  proposal: proposal.md
+  tasks: tasks.md
+  spec: specs/architect/spec.md

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/architect/README.md

@@ -0,0 +1,12 @@
+# architect
+
+Role workspace for `architect`.
+
+Default artifacts:
+- `.openspec.yaml`
+- `prompt.md`
+- `proposal.md`
+- `tasks.md`
+- `specs/<role>/spec.md`
+
+Use this folder for role notes, artifacts, and status updates.

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/architect/prompt.md

@@ -0,0 +1,34 @@
+# architect Prompt
+
+You are the `architect` role for OpenSpec plan `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`.
+
+## Objective
+
+Complete only this role's assigned checklist and leave compact evidence for the coordinator.
+
+## Source of truth
+
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/summary.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/checkpoints.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/open-questions.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/architect/tasks.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/architect/proposal.md`
+
+## Before edits
+
+1. Confirm branch/worktree with `git status --short --branch`.
+2. Claim every touched file before editing:
+   - Prefer Colony `task_claim_file` when an active task exists.
+   - Otherwise run `gx locks claim --branch <agent-branch> <file...>`.
+3. Stay inside assigned files/modules; coordinate before touching shared paths.
+
+## Working rules
+
+- Update `architect/tasks.md` as each item completes.
+- Record durable unresolved questions in `open-questions.md`.
+- Keep handoffs short: files changed, behavior touched, verification, risks.
+- Do not revert another agent's edits.
+
+## Cleanup
+
+Only the owner/finalizer lane runs `gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence.

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/architect/proposal.md

@@ -0,0 +1,15 @@
+# Proposal: architect (agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22)
+
+## Why
+
+Summarize why this role's work is required for plan `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`.
+
+## What Changes
+
+- [ ] List the planned role-specific changes
+
+## Impact
+
+- Scope:
+- Risks:
+- Dependencies:

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/architect/specs/architect/spec.md

@@ -0,0 +1,10 @@
+# Capability Spec: architect
+
+## ADDED Requirements
+
+### Requirement: architect responsibilities for `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`
+This role MUST define and deliver its scoped outputs with evidence.
+
+#### Scenario: Role executes assigned scope
+- **WHEN** the role begins execution for `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`
+- **THEN** it follows `tasks.md` and records evidence for completion

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/architect/tasks.md

@@ -0,0 +1,33 @@
+# architect tasks
+
+## 1. Spec
+
+- [ ] 1.1 Define ownership boundaries, interfaces, and artifact responsibilities for `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`
+- [ ] 1.2 Validate architecture constraints and non-functional requirements coverage
+
+## 2. Tests
+
+- [ ] 2.1 Define architectural verification checkpoints (integration boundaries, failure modes, compatibility)
+- [ ] 2.2 Validate that acceptance criteria map to concrete architecture decisions
+
+## 3. Implementation
+
+- [ ] 3.1 Review plan for strongest antithesis/tradeoff tensions
+- [ ] 3.2 Propose synthesis path and guardrails for implementation teams
+- [ ] 3.3 Record architecture sign-off notes for downstream execution
+
+## 4. Checkpoints
+
+- [ ] [A1] READY - Architecture review checkpoint
+
+## 5. Collaboration
+
+- [ ] 5.1 Owner recorded this lane before edits.
+- [ ] 5.2 Record joined agents / handoffs, or mark `N/A` when solo.
+- [ ] 5.3 Record unresolved plan questions in `../open-questions.md`, or mark `N/A` when none.
+
+## 6. Cleanup
+
+- [ ] 6.1 If this lane owns finalization, run `gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup`.
+- [ ] 6.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 6.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/checkpoints.md

@@ -0,0 +1,4 @@
+# Plan Checkpoints: agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22
+
+Chronological checkpoint log for all roles.
+

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/coordinator-prompt.md

@@ -0,0 +1,41 @@
+# Master Coordinator Prompt
+
+You are the coordinator for plan `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`.
+
+## Objective
+
+Drive this plan from draft to execution-ready status with strict checkpoint discipline and no scope drift.
+
+## Source-of-truth artifacts
+
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/summary.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/checkpoints.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/open-questions.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/planner/plan.md`
+- role `prompt.md` files for copy/paste helper startup
+- role `tasks.md` files for planner/architect/critic/executor/writer/verifier
+
+## Coordinator responsibilities
+
+1. Keep checkpoints current in each role `tasks.md` and root `checkpoints.md`.
+2. Route unresolved questions and branching decisions into `open-questions.md`.
+3. Ensure each role has explicit acceptance criteria and verification evidence.
+4. Prevent implementation from starting before planning gates are complete.
+5. Keep handoffs concise: files changed, behavior touched, verification output, risks.
+
+## Wave-splitting decision (optional)
+
+Create wave prompts in `kickoff-prompts.md` only when at least one applies:
+
+- 3+ independent implementation lanes can run in parallel.
+- Runtime cutover/rollback sequencing needs explicit lane ownership.
+- Risk is high enough that bounded execution packets reduce coordination mistakes.
+
+If wave splitting is not needed, keep execution under a single owner with normal role checkpoints.
+
+## Exit criteria
+
+- All role checkpoints required for planning are done.
+- Execution lanes (if any) have clear ownership boundaries.
+- `open-questions.md` captures unresolved decisions that still need answers.
+- Verification plan and rollback expectations are explicit and testable.

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/critic/.openspec.yaml

@@ -0,0 +1,9 @@
+schema: 1
+plan: agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22
+role: critic
+status: draft
+artifacts:
+  prompt: prompt.md
+  proposal: proposal.md
+  tasks: tasks.md
+  spec: specs/critic/spec.md

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/critic/README.md

@@ -0,0 +1,12 @@
+# critic
+
+Role workspace for `critic`.
+
+Default artifacts:
+- `.openspec.yaml`
+- `prompt.md`
+- `proposal.md`
+- `tasks.md`
+- `specs/<role>/spec.md`
+
+Use this folder for role notes, artifacts, and status updates.

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/critic/prompt.md

@@ -0,0 +1,34 @@
+# critic Prompt
+
+You are the `critic` role for OpenSpec plan `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`.
+
+## Objective
+
+Complete only this role's assigned checklist and leave compact evidence for the coordinator.
+
+## Source of truth
+
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/summary.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/checkpoints.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/open-questions.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/critic/tasks.md`
+- `openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/critic/proposal.md`
+
+## Before edits
+
+1. Confirm branch/worktree with `git status --short --branch`.
+2. Claim every touched file before editing:
+   - Prefer Colony `task_claim_file` when an active task exists.
+   - Otherwise run `gx locks claim --branch <agent-branch> <file...>`.
+3. Stay inside assigned files/modules; coordinate before touching shared paths.
+
+## Working rules
+
+- Update `critic/tasks.md` as each item completes.
+- Record durable unresolved questions in `open-questions.md`.
+- Keep handoffs short: files changed, behavior touched, verification, risks.
+- Do not revert another agent's edits.
+
+## Cleanup
+
+Only the owner/finalizer lane runs `gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence.

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/critic/proposal.md

@@ -0,0 +1,15 @@
+# Proposal: critic (agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22)
+
+## Why
+
+Summarize why this role's work is required for plan `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`.
+
+## What Changes
+
+- [ ] List the planned role-specific changes
+
+## Impact
+
+- Scope:
+- Risks:
+- Dependencies:

openspec/plan/agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22/critic/specs/critic/spec.md

@@ -0,0 +1,10 @@
+# Capability Spec: critic
+
+## ADDED Requirements
+
+### Requirement: critic responsibilities for `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`
+This role MUST define and deliver its scoped outputs with evidence.
+
+#### Scenario: Role executes assigned scope
+- **WHEN** the role begins execution for `agent-claude-masterplan-fleet-pane-health-badge-column-2026-05-16-00-22`
+- **THEN** it follows `tasks.md` and records evidence for completion