tmux-ide 2.6.1 → 2.7.0

package/packages/daemon/src/tui/mirror/settings-model.ts

@@ -0,0 +1,345 @@
+/**
+ * Settings as COMMANDS (M22.4) — the PURE model behind the app's settings
+ * surface. There is NO settings screen: every setting is a palette command
+ * executed through the dialog primitives ({@link ./dialog-model.ts} /
+ * {@link ./dialog-stack.ts}); this module builds the dialog ITEM LISTS from the
+ * real typed config ({@link ../../lib/app-config.ts}) and the real notification
+ * prefs ({@link ../chrome/notify.ts}), plus the config PATCHES each choice
+ * persists. app.tsx owns the async flows (sequential awaits over the one-shots).
+ *
+ * Copy is plain language throughout; each dialog's footer says WHERE a change
+ * lands ("takes effect immediately" vs "after re-adopt") so non-technicals are
+ * never left guessing.
+ */
+import type { AppConfig, AppConfigPatch, AppKeys } from "../../lib/app-config.ts";
+import { parseHHMM, type NotificationPrefs } from "../chrome/notify.ts";
+import type { DialogSelectItem } from "./dialog-model.ts";
+
+// ── Command registry (what the palette offers) ───────────────────────────────
+
+export type SettingsCommandId =
+  | "settings"
+  | "settings-theme"
+  | "settings-notifications"
+  | "settings-quiet-hours"
+  | "settings-updates"
+  | "settings-restore"
+  | "settings-keys"
+  | "settings-reset";
+
+/** The palette entries, one per settings command (+ the umbrella first). The
+ *  "Settings" category prefix is how the palette's flat fuzzy list reads as a
+ *  category — typing "set" narrows to all of them. */
+export const SETTINGS_PALETTE_COMMANDS: ReadonlyArray<{
+  id: SettingsCommandId;
+  label: string;
+}> = [
+  { id: "settings", label: "Settings…" },
+  { id: "settings-theme", label: "Settings: Accent color" },
+  { id: "settings-notifications", label: "Settings: Notifications" },
+  { id: "settings-quiet-hours", label: "Settings: Quiet hours" },
+  { id: "settings-updates", label: "Settings: Updates & background refresh" },
+  { id: "settings-restore", label: "Settings: Crash restore" },
+  { id: "settings-keys", label: "Settings: Keyboard shortcuts (view)" },
+  { id: "settings-reset", label: "Settings: Reset to defaults" },
+];
+
+// ── Where changes land (footer copy) ─────────────────────────────────────────
+
+/** Notifications are read fresh per event — honest "immediately". */
+export const HINT_LIVE = "takes effect immediately";
+/** The tmux chrome + widget panels read the theme when they (re)build. */
+export const HINT_READOPT = "applies after re-adopt — run: tmux-ide adopt <session>";
+/** The background chrome loads its config at start. */
+export const HINT_CHROME_RESTART = "applies when the background chrome restarts";
+
+// ── Theme presets ────────────────────────────────────────────────────────────
+
+export interface ThemePreset {
+  /** The `theme.accent` value persisted (a tmux `colourN` token). */
+  accent: string;
+  /** Plain name shown in the picker. */
+  label: string;
+  /** The same color as RGB for the in-dialog swatch / live preview. */
+  rgb: [number, number, number];
+}
+
+/** Curated accents (default first). RGB values are the xterm-256 values of the
+ *  `colourN` tokens, so the in-app preview shows exactly what tmux will. */
+export const THEME_PRESETS: readonly ThemePreset[] = [
+  { accent: "colour75", label: "Sky blue (default)", rgb: [95, 175, 255] },
+  { accent: "colour114", label: "Soft green", rgb: [135, 215, 135] },
+  { accent: "colour80", label: "Aqua", rgb: [95, 215, 215] },
+  { accent: "colour111", label: "Periwinkle", rgb: [135, 175, 255] },
+  { accent: "colour183", label: "Lavender", rgb: [215, 175, 255] },
+  { accent: "colour216", label: "Peach", rgb: [255, 175, 135] },
+  { accent: "colour221", label: "Amber", rgb: [255, 215, 95] },
+  { accent: "colour203", label: "Coral", rgb: [255, 95, 95] },
+];
+
+/** PURE — the theme picker rows: every preset (● on the saved accent). A saved
+ *  accent that is not a preset (hand-edited config) keeps its place as a
+ *  "Custom" first row so the picker never lies about the current value. */
+export function themeItems(cfg: AppConfig): DialogSelectItem[] {
+  const current = cfg.theme.accent;
+  const rows: DialogSelectItem[] = THEME_PRESETS.map((p) => ({
+    id: p.accent,
+    label: p.label,
+    detail: p.accent,
+    current: p.accent === current,
+    swatch: p.rgb,
+  }));
+  if (!THEME_PRESETS.some((p) => p.accent === current)) {
+    rows.unshift({ id: current, label: "Custom", detail: current, current: true });
+  }
+  return rows;
+}
+
+/** PURE — the RGB swatch for an accent value, when it is a known preset. */
+export function presetRgb(accent: string): [number, number, number] | null {
+  return THEME_PRESETS.find((p) => p.accent === accent)?.rgb ?? null;
+}
+
+/** PURE — the patch persisting a picked accent. */
+export function themePatch(accent: string): AppConfigPatch {
+  return { theme: { accent } };
+}
+
+// ── Notifications ────────────────────────────────────────────────────────────
+
+export type NotificationToggleId = "enabled" | "toast" | "macos" | "onBlocked" | "onDone";
+
+const onOff = (v: boolean) => (v ? "on" : "off");
+
+/** PURE — the notification toggle rows (the REAL fields notify.ts reads: the
+ *  typed toast/macos plus the polish-era raw fields), and a quiet-hours row
+ *  that descends into its own flow. Enter toggles in place. */
+export function notificationItems(prefs: NotificationPrefs): DialogSelectItem[] {
+  return [
+    { id: "enabled", label: "All notifications", detail: onOff(prefs.enabled) },
+    { id: "toast", label: "In-terminal toasts", detail: onOff(prefs.toast) },
+    { id: "macos", label: "macOS banners", detail: onOff(prefs.macos) },
+    { id: "onBlocked", label: "Alert when an agent needs you", detail: onOff(prefs.onBlocked) },
+    { id: "onDone", label: "Alert when an agent finishes", detail: onOff(prefs.onDone) },
+    { id: "quietHours", label: "Quiet hours…", detail: quietHoursSummary(prefs) },
+  ];
+}
+
+/** PURE — flip one notification toggle. */
+export function notificationTogglePatch(
+  id: NotificationToggleId,
+  prefs: NotificationPrefs,
+): AppConfigPatch {
+  return { notifications: { [id]: !prefs[id] } };
+}
+
+/** PURE — "22:00–08:00" or "off". */
+export function quietHoursSummary(prefs: NotificationPrefs): string {
+  return prefs.quietHours ? `${prefs.quietHours.start}–${prefs.quietHours.end}` : "off";
+}
+
+/** PURE — the quiet-hours chooser rows. */
+export function quietHoursItems(prefs: NotificationPrefs): DialogSelectItem[] {
+  return [
+    { id: "off", label: "Off — always notify", current: prefs.quietHours === null },
+    {
+      id: "window",
+      label: "Silence banners during a daily window…",
+      detail: prefs.quietHours ? quietHoursSummary(prefs) : undefined,
+      current: prefs.quietHours !== null,
+    },
+  ];
+}
+
+/** PURE — HH:MM validation with a plain error. */
+export function validateQuietTime(value: string): string | null {
+  return parseHHMM(value.trim()) === null ? "Use 24-hour HH:MM — for example 22:00" : null;
+}
+
+/** PURE — persist a quiet window (times already validated). */
+export function quietHoursPatch(start: string, end: string): AppConfigPatch {
+  return { notifications: { quietHours: { start: start.trim(), end: end.trim() } } };
+}
+
+/** PURE — remove the quiet window. */
+export function quietHoursOffPatch(): AppConfigPatch {
+  return { notifications: { quietHours: undefined } };
+}
+
+// ── Updates & updater cadence ────────────────────────────────────────────────
+
+/** PURE — the updates dialog rows: the check toggle + the two cadence numbers. */
+export function updatesItems(cfg: AppConfig): DialogSelectItem[] {
+  return [
+    { id: "check", label: "Check for tmux-ide updates", detail: onOff(cfg.updates.check) },
+    {
+      id: "tickMs",
+      label: "Background refresh interval…",
+      detail: `${cfg.updater.tickMs} ms`,
+    },
+    {
+      id: "snapshotEvery",
+      label: "Save a crash snapshot every…",
+      detail: `${cfg.updater.snapshotEvery} refreshes`,
+    },
+  ];
+}
+
+export function updatesCheckPatch(cfg: AppConfig): AppConfigPatch {
+  return { updates: { check: !cfg.updates.check } };
+}
+
+/** PURE — 250–60000 ms, whole numbers (guards a config that would spin or
+ *  starve the chrome). */
+export function validateTickMs(value: string): string | null {
+  const n = Number(value.trim());
+  if (!Number.isInteger(n) || n < 250 || n > 60_000) {
+    return "Use a whole number of milliseconds between 250 and 60000";
+  }
+  return null;
+}
+
+/** PURE — 1–1000 refreshes. */
+export function validateSnapshotEvery(value: string): string | null {
+  const n = Number(value.trim());
+  if (!Number.isInteger(n) || n < 1 || n > 1000) {
+    return "Use a whole number between 1 and 1000";
+  }
+  return null;
+}
+
+export function tickMsPatch(value: string): AppConfigPatch {
+  return { updater: { tickMs: Number(value.trim()) } };
+}
+
+export function snapshotEveryPatch(value: string): AppConfigPatch {
+  return { updater: { snapshotEvery: Number(value.trim()) } };
+}
+
+// ── Crash restore ────────────────────────────────────────────────────────────
+
+/** PURE — the restore On/Off rows. */
+export function restoreItems(cfg: AppConfig): DialogSelectItem[] {
+  return [
+    {
+      id: "on",
+      label: "Revive agents automatically",
+      detail: "restore resumes claude conversations",
+      current: cfg.restore.resumeAgents,
+    },
+    {
+      id: "off",
+      label: "Rebuild sessions only",
+      detail: "agents stay stopped",
+      current: !cfg.restore.resumeAgents,
+    },
+  ];
+}
+
+export function restorePatch(id: string): AppConfigPatch {
+  return { restore: { resumeAgents: id === "on" } };
+}
+
+// ── Keyboard shortcut viewer (read-only) ─────────────────────────────────────
+
+/** Mirrors {@link ../chrome/statusline.ts}'s prefix-twin derivation — the
+ *  letters tmux binds by default (never clobbered) and the documented remaps.
+ *  A drift test asserts agreement with `prefixKeyBinds` for the defaults. */
+const PREFIX_TAKEN = new Set([..."cdfilmnopqrstwxz"]);
+const PREFIX_REMAP: Record<string, string> = { "M-m": "u", "M-p": "j", "M-,": "v" };
+
+/** PURE — the reliable `prefix <letter>` twin for an Alt key, or null when the
+ *  letter is taken by a stock tmux bind and has no documented remap. */
+export function prefixTwinFor(altKey: string): string | null {
+  const remapped = PREFIX_REMAP[altKey];
+  if (remapped) return remapped;
+  const letter = /^M-([a-z])$/.exec(altKey)?.[1];
+  if (!letter || PREFIX_TAKEN.has(letter)) return null;
+  return letter;
+}
+
+/** PURE — the read-only shortcut rows: the chrome actions from the LIVE config
+ *  (prefix-first, the Alt fast path second — the prefix form is the one that
+ *  survives every keyboard protocol) and then the app's fixed keys. */
+export function keybindingItems(keys: AppKeys): DialogSelectItem[] {
+  const chrome: Array<{ label: string; altKey: string }> = [
+    { label: "Home cockpit", altKey: keys.home },
+    { label: "Session switcher", altKey: keys.popup },
+    { label: "Cheat sheet", altKey: keys.cheatsheet },
+    { label: "Actions menu", altKey: keys.menu },
+    { label: "Sidebar", altKey: keys.sidebar },
+    { label: "Explorer panel", altKey: keys.panels.explorer },
+    { label: "Git changes panel", altKey: keys.panels.changes },
+    { label: "Config panel", altKey: keys.panels.config },
+  ];
+  const rows: DialogSelectItem[] = chrome.map(({ label, altKey }) => {
+    const twin = prefixTwinFor(altKey);
+    return {
+      id: `chrome:${label}`,
+      label,
+      detail: twin ? `prefix ${twin} · ${altKey}` : altKey,
+    };
+  });
+  const app: Array<[string, string]> = [
+    ["Command palette", "F5 · ^p"],
+    ["Home / Terminal / Files / Diff tabs", "F1–F4"],
+    ["Back to Home", "^g"],
+    ["Toggle editor", "^e"],
+    ["Detach from the app", "^q"],
+  ];
+  for (const [label, detail] of app) rows.push({ id: `app:${label}`, label, detail });
+  return rows;
+}
+
+// ── The umbrella + reset ─────────────────────────────────────────────────────
+
+/** PURE — the "Settings…" umbrella rows: one per command, categorized by a
+ *  `Category · name` label (flat list, fuzzy-friendly), each showing its
+ *  current value as the detail. Reset is the one destructive row. */
+export function settingsRootItems(cfg: AppConfig, prefs: NotificationPrefs): DialogSelectItem[] {
+  const accent = cfg.theme.accent;
+  const preset = THEME_PRESETS.find((p) => p.accent === accent);
+  return [
+    {
+      id: "settings-theme",
+      label: "Appearance · Accent color",
+      detail: preset?.label.replace(" (default)", "") ?? accent,
+    },
+    {
+      id: "settings-notifications",
+      label: "Notifications · Alerts & channels",
+      detail: prefs.enabled ? "on" : "off",
+    },
+    {
+      id: "settings-quiet-hours",
+      label: "Notifications · Quiet hours",
+      detail: quietHoursSummary(prefs),
+    },
+    {
+      id: "settings-updates",
+      label: "Updates · Checks & refresh",
+      detail: cfg.updates.check ? "checking" : "off",
+    },
+    {
+      id: "settings-restore",
+      label: "Sessions · Crash restore",
+      detail: cfg.restore.resumeAgents ? "revives agents" : "sessions only",
+    },
+    { id: "settings-keys", label: "Keyboard · Shortcuts", detail: "view" },
+    { id: "settings-reset", label: "Reset · All settings to defaults", danger: true },
+  ];
+}
+
+/** PURE — the reset patch: DELETE the blocks the settings surface manages so
+ *  the parser's defaults take over. Key binds and unknown user fields are
+ *  deliberately preserved — reset returns the LOOK and BEHAVIOR to stock
+ *  without silently unbinding the user's keys. */
+export function resetSettingsPatch(): AppConfigPatch {
+  return {
+    theme: undefined,
+    notifications: undefined,
+    updater: undefined,
+    updates: undefined,
+    restore: undefined,
+  };
+}

package/packages/daemon/src/tui/mirror/size-truth.ts

@@ -0,0 +1,77 @@
+/**
+ * Size truth (M22.8) — is tmux's window the size we pinned, or did a co-attached
+ * terminal shrink it out from under us?
+ *
+ * The mirror pins its virtual control client to the render area
+ * (`refresh-client -C`), so when we are the only (or the latest-active) client
+ * the window matches our canvas. But tmux's default `window-size latest` lets a
+ * second, smaller terminal attached to the same session dictate the window size
+ * — and our canvas then renders letterboxed. These PURE helpers detect that
+ * mismatch from the pane layout, center the grid inside the canvas, and format
+ * the quiet honest hint. No tmux, no render loop — unit-tested in isolation; the
+ * app reads the pane geometry and the pinned canvas size and wires the rest.
+ */
+
+export interface Size {
+  cols: number;
+  rows: number;
+}
+
+/** The minimal pane rectangle the bounding box needs (LivePane is assignable). */
+export interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * PURE — the effective window size implied by the pane layout: the bounding box
+ * of all pane rects. tmux tiles panes to fill the whole window (edge panes sit
+ * flush to the edges, borders live between them), so the maximum right edge
+ * (`left + width`) is the window width and the maximum bottom edge
+ * (`top + height`) is the window height. Null when there are no panes yet.
+ */
+export function effectiveWindowSize(panes: readonly Rect[]): Size | null {
+  if (panes.length === 0) return null;
+  let cols = 0;
+  let rows = 0;
+  for (const p of panes) {
+    cols = Math.max(cols, p.left + p.width);
+    rows = Math.max(rows, p.top + p.height);
+  }
+  return { cols, rows };
+}
+
+/**
+ * PURE — the actual window size when it DIFFERS from what we pinned (another
+ * terminal is dictating it), else null. Any difference on either axis counts;
+ * equal sizes mean we own the window and there is nothing to surface.
+ */
+export function detectSizeMismatch(pinned: Size, effective: Size): Size | null {
+  if (effective.cols === pinned.cols && effective.rows === pinned.rows) return null;
+  return { cols: effective.cols, rows: effective.rows };
+}
+
+/**
+ * PURE — the letterbox offset that centers a `content`-sized grid inside a
+ * `canvas`-sized area. Never negative (a window LARGER than the canvas pins to
+ * the origin and clips rather than shifting off-screen), floored so cells stay
+ * aligned to the grid.
+ */
+export function letterboxOffset(canvas: Size, content: Size): { x: number; y: number } {
+  return {
+    x: Math.max(0, Math.floor((canvas.cols - content.cols) / 2)),
+    y: Math.max(0, Math.floor((canvas.rows - content.rows) / 2)),
+  };
+}
+
+/**
+ * PURE — the quiet, plain-language hint for a size mismatch: the honest answer
+ * ("here is the size another terminal chose"), dimensions in the terminal-native
+ * `cols×rows` form. Dismiss-free — the app shows it only while the mismatch
+ * exists, so it disappears the moment the sizes agree.
+ */
+export function formatSizeHint(effective: Size): string {
+  return `window sized by another terminal — ${effective.cols}×${effective.rows}`;
+}

package/packages/daemon/src/tui/mirror/spans.ts

@@ -0,0 +1,46 @@
+/** Pure horizontal-span geometry shared by the two clickable tab rows — the
+ *  surface tab bar (F1..F4, startX=0, gap=0) and the per-window strip inside the
+ *  Terminal surface (startX=SIDEBAR_W+1, gap=1). Both render a row of labels
+ *  laid out left-to-right and both resolve clicks in the central `route` by
+ *  x-span math; keeping that math in one tested place is the whole point (the
+ *  window strip's old inline math drifted from its render and hit the late-mount
+ *  landmine). Index `i` of the returned array maps to `labels[i]`. */
+export interface Span {
+  /** First column (inclusive) this label occupies. */
+  start: number;
+  /** Cell width — the label's string length (labels are single display-width). */
+  width: number;
+}
+
+/** Lay `labels` out from `startX`, each `label.length` cells wide, separated by
+ *  `gap` blank cells. Pure. */
+export function spans(labels: string[], startX: number, gap: number): Span[] {
+  const out: Span[] = [];
+  let x = startX;
+  for (const label of labels) {
+    out.push({ start: x, width: label.length });
+    x += label.length + gap;
+  }
+  return out;
+}
+
+/** Lay `labels` out left-to-right anchored to the RIGHT: the last label ends
+ *  flush at `rightEdge` (its final cell is `rightEdge - 1`), separated by `gap`.
+ *  For right-aligned header affordance buttons whose PRECEDING content is
+ *  variable-width — the layout is pinned to the (fixed) right edge, not a left
+ *  origin, so the render (a flexGrow spacer then the buttons) and the router
+ *  agree cell-for-cell. Pure. */
+export function spansFromRight(labels: string[], rightEdge: number, gap: number): Span[] {
+  const total = labels.reduce((n, l) => n + l.length, 0) + gap * Math.max(0, labels.length - 1);
+  return spans(labels, rightEdge - total, gap);
+}
+
+/** Index of the span containing column `x`, or -1. Gap cells between spans and
+ *  columns past the last span resolve to -1 (no hit). */
+export function spanHit(list: Span[], x: number): number {
+  for (let i = 0; i < list.length; i++) {
+    const s = list[i]!;
+    if (x >= s.start && x < s.start + s.width) return i;
+  }
+  return -1;
+}

package/packages/daemon/src/tui/mirror/status-grammar.ts

@@ -0,0 +1,32 @@
+/**
+ * The unified app's status glyph + color grammar — PURE declarative data, hoisted
+ * out of app.tsx (M22.2) so every mirror surface shares ONE source of truth: the
+ * sidebar fleet tree, the home rollup chips, the AGENTS section, and (post-merge)
+ * the pane-chrome agent chips. Keyed by {@link AgentStatus}.
+ *
+ * This is the MIRROR app's grammar — deliberately distinct from the cockpit's
+ * (whose idle glyph is a filled ●) and from chrome's color tokens. Do not swap
+ * in either of those: keep every mirror surface in one visual family.
+ */
+import { RGBA } from "@opentui/core";
+import type { AgentStatus } from "../detect/classify.ts";
+
+/** Per-state foreground color: blocked red, working amber, done blue, idle
+ *  green, unknown grey. */
+export const STATUS_COLOR: Record<AgentStatus, RGBA> = {
+  blocked: RGBA.fromInts(240, 100, 100, 255),
+  working: RGBA.fromInts(235, 200, 100, 255),
+  done: RGBA.fromInts(120, 170, 250, 255),
+  idle: RGBA.fromInts(120, 200, 140, 255),
+  unknown: RGBA.fromInts(110, 110, 130, 255),
+};
+
+/** Per-state glyph: working/blocked/done share the filled dot (color carries the
+ *  distinction), idle is hollow, unknown a middot. */
+export const STATUS_GLYPH: Record<AgentStatus, string> = {
+  blocked: "●",
+  working: "●",
+  done: "●",
+  idle: "○",
+  unknown: "·",
+};

package/packages/daemon/src/tui/team/entry.ts

@@ -1,11 +1,38 @@
 /**
- * Front-door decision for bare `tmux-ide` / `tmux-ide start`: open the team
- * cockpit (the multi-project TUI) instead of launching a single project.
+ * Front-door decision for bare `tmux-ide` / `tmux-ide start`: what does running
+ * the command with no subcommand land on?
  *
- * The cockpit is the default entry when there's no single-project `ide.yml` to
- * launch here, or when `--team` forces it. When an `ide.yml` is present, bare
- * invocation still launches that project (backward compatible).
+ * Three outcomes:
+ *  - `"project"` — a single-project `ide.yml` is present here (and `--team`
+ *    wasn't passed): launch that project, exactly as always (backward compatible).
+ *  - `"app"` — the M22.6 front-door flip: when there's no project to launch and
+ *    the user opted in (`app.frontDoor`), bare `tmux-ide` opens the unified app
+ *    (`tmux-ide app`) — the VS-Code-style "starts anywhere" entry.
+ *  - `"cockpit"` — the classic team cockpit: the default no-project entry while
+ *    the flip is off, and always the target of an explicit `--team`.
+ *
+ * `--team` ALWAYS means the classic cockpit (an explicit request for it), so it
+ * overrides both a present `ide.yml` and the front-door flip.
+ */
+export type EntryTarget = "project" | "cockpit" | "app";
+
+export interface ResolveEntryOptions {
+  /** Whether an `ide.yml` is present in the target directory. */
+  hasIdeYml: boolean;
+  /** Whether `--team` forced the cockpit. */
+  teamFlag: boolean;
+  /** The `app.frontDoor` config flag — flip the default no-project entry to the app. */
+  frontDoor: boolean;
+}
+
+/**
+ * PURE — resolve the bare-invocation target. `--team` wins (always the classic
+ * cockpit); otherwise a present `ide.yml` launches the project; otherwise the
+ * front-door flag decides between the unified app (opted in) and the classic
+ * cockpit (default).
  */
-export function shouldOpenCockpit(hasIdeYml: boolean, teamFlag: boolean): boolean {
-  return teamFlag || !hasIdeYml;
+export function resolveEntry(opts: ResolveEntryOptions): EntryTarget {
+  if (opts.teamFlag) return "cockpit";
+  if (opts.hasIdeYml) return "project";
+  return opts.frontDoor ? "app" : "cockpit";
 }

package/packages/daemon/src/tui/team/report.ts

@@ -10,7 +10,7 @@
  */
 import type { AgentStatus } from "../detect/classify.ts";
 import type { TeamProject } from "./projects.ts";
-import type { TeamSession } from "./sessions.ts";
+import type { PaneAgentEntry, TeamSession } from "./sessions.ts";
 
 /** The stable JSON shape emitted by `tmux-ide team --json`. */
 export interface FleetJson {
@@ -32,6 +32,13 @@ export interface FleetJson {
         panes: number;
         status: AgentStatus;
       }>;
+      /**
+       * Per-pane agent detail — one entry per pane the detection layer resolves
+       * to a real agent, flat across the session's windows (each entry carries
+       * its `windowIndex`). ADDITIVE: always present (possibly empty); existing
+       * consumers that ignore it are unaffected.
+       */
+      agents: PaneAgentEntry[];
     }>;
   }>;
 }
@@ -57,6 +64,9 @@ export function toFleetJson(projects: TeamProject[]): FleetJson {
           panes: w.panes,
           status: w.status,
         })),
+        // A pre-agents TeamSession (older constructor/test) yields `[]` — the
+        // contract always exposes the array.
+        agents: s.agents ?? [],
       })),
     })),
   };