pi-extended-teams 2.1.16

package/extensions/ui/favorite-models-command.ts

@@ -0,0 +1,423 @@
+import { Key, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import {
+  clearGlobalFavoriteModels,
+  FAVORITE_MODEL_SLOTS,
+  globalSettingsPath,
+  loadSettings,
+  normalizeFavoriteModelSlot,
+  replaceGlobalFavoriteModels,
+  setGlobalFavoriteModel,
+  THINKING_LEVEL_NAMES,
+  type CanonicalFavoriteModelSlot,
+  type FavoriteModelConfig,
+  type ThinkingLevelName,
+} from "../../src/utils/settings";
+import { normalizeQualifiedModel } from "../../src/utils/model-resolution";
+import { clampThinkingLevel, getSupportedThinkingLevels } from "../../src/utils/thinking-levels";
+import { getAvailableModels, type AvailableRegisteredModel } from "../internal/model-selection";
+
+interface AvailableModelOption extends AvailableRegisteredModel {
+  qualified: string;
+}
+
+type FavoriteModelsDraft = Partial<Record<CanonicalFavoriteModelSlot, FavoriteModelConfig>>;
+type PickerColumn = "slots" | "models" | "thinking";
+
+const DEFAULT_THINKING_BY_SLOT: Record<CanonicalFavoriteModelSlot, ThinkingLevelName> = {
+  "read-collect": "high",
+  "read-review": "xhigh",
+  "read-analyze": "medium",
+  "read-critical": "xhigh",
+  "write-patch": "max",
+  "write-feature": "medium",
+  "write-system": "high",
+  "write-critical": "max",
+};
+
+const COLUMNS: PickerColumn[] = ["slots", "models", "thinking"];
+
+function formatSlot(slot: CanonicalFavoriteModelSlot, config?: FavoriteModelConfig): string {
+  if (!config?.model || !config.thinking) return `- ${slot}: (empty)`;
+  return `- ${slot}: ${config.model} · ${config.thinking}`;
+}
+
+function usage(): string {
+  return [
+    "Usage:",
+    "  /agents-favorite-models",
+    "  /agents-favorite-models set <slot> <provider/model> <thinking>",
+    "  /agents-favorite-models clear <slot>",
+    "  /agents-favorite-models clear",
+    "",
+    `Slots: ${FAVORITE_MODEL_SLOTS.join(", ")}`,
+    `Thinking: ${THINKING_LEVEL_NAMES.join(", ")}`,
+  ].join("\n");
+}
+
+function formatCurrentSettings(homeDir?: string): string {
+  const settings = loadSettings({ homeDir });
+  return [
+    "Agent favorite models:",
+    ...FAVORITE_MODEL_SLOTS.map((slot) => formatSlot(slot, settings.favoriteModels[slot])),
+    "",
+    usage(),
+    "",
+    `Saved in: ${globalSettingsPath(homeDir)}`,
+  ].join("\n");
+}
+
+function normalizeSlot(raw: string | undefined): CanonicalFavoriteModelSlot {
+  const slot = normalizeFavoriteModelSlot(raw);
+  if (!slot) {
+    throw new Error(`Unknown slot "${raw ?? ""}". Use one of: ${FAVORITE_MODEL_SLOTS.join(", ")}.`);
+  }
+  return slot;
+}
+
+function normalizeThinking(raw: string | undefined): ThinkingLevelName {
+  if (!raw || !(THINKING_LEVEL_NAMES as readonly string[]).includes(raw)) {
+    throw new Error(`Invalid thinking level "${raw ?? ""}". Use one of: ${THINKING_LEVEL_NAMES.join(", ")}.`);
+  }
+  return raw as ThinkingLevelName;
+}
+
+function normalizeModel(raw: string | undefined): string {
+  const normalized = raw ? normalizeQualifiedModel(raw) : null;
+  if (!normalized) {
+    throw new Error("Model must be a fully qualified provider/model string.");
+  }
+  return normalized;
+}
+
+function formatQualifiedModel(model: { provider: string; model: string }): string {
+  return `${model.provider}/${model.model}`;
+}
+
+function sortAvailableModels(models: AvailableRegisteredModel[]): AvailableModelOption[] {
+  return models
+    .map((model) => ({ ...model, qualified: formatQualifiedModel(model) }))
+    .sort((a, b) => a.qualified.localeCompare(b.qualified));
+}
+
+function cloneFavoriteModels(input: FavoriteModelsDraft): FavoriteModelsDraft {
+  const draft: FavoriteModelsDraft = {};
+  for (const slot of FAVORITE_MODEL_SLOTS) {
+    const config = input[slot];
+    if (!config?.model || !config.thinking) continue;
+    draft[slot] = { model: config.model, thinking: config.thinking };
+  }
+  return draft;
+}
+
+function padToWidth(value: string, width: number): string {
+  const truncated = truncateToWidth(value, width, "…", true);
+  return `${truncated}${" ".repeat(Math.max(0, width - visibleWidth(truncated)))}`;
+}
+
+function styledTitle(theme: any, label: string, active: boolean): string {
+  const title = active ? `▶ ${label}` : `  ${label}`;
+  return active ? theme.fg("accent", theme.bold(title)) : theme.fg("muted", title);
+}
+
+function defaultTheme(theme: any) {
+  return {
+    accent: (value: string) => theme.fg("accent", value),
+    dim: (value: string) => theme.fg("dim", value),
+    warning: (value: string) => theme.fg("warning", value),
+    success: (value: string) => theme.fg("success", value),
+    bold: (value: string) => theme.bold(value),
+  };
+}
+
+async function loadScopedModels(ctx: any): Promise<AvailableModelOption[]> {
+  return sortAvailableModels(await getAvailableModels(ctx));
+}
+
+async function showFavoriteModelsPicker(ctx: any): Promise<"saved" | "cancelled" | undefined> {
+  const availableModels = await loadScopedModels(ctx);
+  const availableSet = new Set(availableModels.map((model) => model.qualified));
+  const draft = cloneFavoriteModels(loadSettings().favoriteModels);
+
+  return ctx.ui.custom((tui: any, theme: any, _keybindings: any, done: (value: "saved" | "cancelled") => void) => {
+    const colors = defaultTheme(theme);
+    let selectedSlotIndex = 0;
+    let activeColumnIndex = 0;
+    let modelFilter = "";
+    let modelScroll = 0;
+    let notice: string | undefined;
+
+    const activeColumn = () => COLUMNS[activeColumnIndex];
+    const selectedSlot = () => FAVORITE_MODEL_SLOTS[selectedSlotIndex];
+    const selectedConfig = () => draft[selectedSlot()];
+    const selectedModel = () => availableModels.find((model) => model.qualified === selectedConfig()?.model);
+    const selectedThinkingLevels = () => {
+      const model = selectedModel();
+      return model ? getSupportedThinkingLevels(model) : [];
+    };
+    const filteredModels = () => {
+      const filter = modelFilter.trim().toLowerCase();
+      if (!filter) return availableModels;
+      return availableModels.filter((model) => model.qualified.toLowerCase().includes(filter));
+    };
+
+    const ensureModelVisible = (modelRows: number) => {
+      const models = filteredModels();
+      const currentModel = selectedConfig()?.model;
+      const selectedModelIndex = Math.max(0, models.findIndex((model) => model.qualified === currentModel));
+      if (selectedModelIndex < modelScroll) modelScroll = selectedModelIndex;
+      if (selectedModelIndex >= modelScroll + modelRows) modelScroll = selectedModelIndex - modelRows + 1;
+      modelScroll = Math.max(0, Math.min(modelScroll, Math.max(0, models.length - modelRows)));
+    };
+
+    const setModelByDelta = (delta: number) => {
+      const models = filteredModels();
+      if (models.length === 0) return;
+      const slot = selectedSlot();
+      const currentModel = draft[slot]?.model;
+      const currentIndex = models.findIndex((model) => model.qualified === currentModel);
+      const nextIndex = Math.max(0, Math.min(models.length - 1, (currentIndex >= 0 ? currentIndex : delta > 0 ? -1 : models.length) + delta));
+      const model = models[nextIndex];
+      const currentThinking = normalizeThinking(draft[slot]?.thinking ?? DEFAULT_THINKING_BY_SLOT[slot]);
+      draft[slot] = {
+        model: model.qualified,
+        thinking: clampThinkingLevel(model, currentThinking),
+      };
+      notice = undefined;
+    };
+
+    const setThinkingByDelta = (delta: number) => {
+      const slot = selectedSlot();
+      if (!draft[slot]?.model) {
+        notice = `Pick a scoped model for ${slot} before choosing thinking.`;
+        return;
+      }
+      const levels = selectedThinkingLevels();
+      if (levels.length === 0) {
+        notice = `The selected model for ${slot} is unavailable.`;
+        return;
+      }
+      const currentThinking = draft[slot]?.thinking ?? DEFAULT_THINKING_BY_SLOT[slot];
+      const currentIndex = Math.max(0, levels.findIndex((thinking) => thinking === currentThinking));
+      const nextIndex = Math.max(0, Math.min(levels.length - 1, currentIndex + delta));
+      draft[slot] = {
+        model: draft[slot]?.model ?? null,
+        thinking: levels[nextIndex],
+      };
+      notice = undefined;
+    };
+
+    const clearSelectedSlot = () => {
+      delete draft[selectedSlot()];
+      notice = undefined;
+    };
+
+    const clearAllSlots = () => {
+      for (const slot of FAVORITE_MODEL_SLOTS) delete draft[slot];
+      notice = undefined;
+    };
+
+    const saveAndClose = () => {
+      replaceGlobalFavoriteModels(draft);
+      done("saved");
+    };
+
+    const moveColumn = (delta: number) => {
+      activeColumnIndex = Math.max(0, Math.min(COLUMNS.length - 1, activeColumnIndex + delta));
+    };
+
+    const moveActiveSelection = (delta: number) => {
+      if (activeColumn() === "slots") {
+        selectedSlotIndex = Math.max(0, Math.min(FAVORITE_MODEL_SLOTS.length - 1, selectedSlotIndex + delta));
+        return;
+      }
+      if (activeColumn() === "models") {
+        setModelByDelta(delta);
+        return;
+      }
+      setThinkingByDelta(delta);
+    };
+
+    const modelRowsForTerminal = () => Math.max(5, Math.min(14, (tui.terminal?.rows ?? 24) - 13));
+
+    const buildSlotRows = (): string[] => {
+      return FAVORITE_MODEL_SLOTS.map((slot, index) => {
+        const config = draft[slot];
+        const selected = index === selectedSlotIndex;
+        const pointer = selected ? "›" : " ";
+        const model = config?.model ?? "empty";
+        const thinking = config?.thinking ?? "unset";
+        const unavailable = config?.model && !availableSet.has(config.model) ? " !unavailable" : "";
+        return `${pointer} ${slot}  ${model} · ${thinking}${unavailable}`;
+      });
+    };
+
+    const buildModelRows = (rowCount: number): string[] => {
+      const models = filteredModels();
+      ensureModelVisible(rowCount);
+      if (models.length === 0) return [modelFilter ? "No scoped models match the filter." : "No scoped models available."];
+
+      const currentModel = selectedConfig()?.model;
+      const window = models.slice(modelScroll, modelScroll + rowCount);
+      const rows = window.map((model) => {
+        const selected = model.qualified === currentModel;
+        return `${selected ? "›" : " "} ${model.qualified}`;
+      });
+      if (modelScroll > 0) rows.unshift(`… ${modelScroll} more above`);
+      const below = models.length - modelScroll - window.length;
+      if (below > 0) rows.push(`… ${below} more below`);
+      return rows;
+    };
+
+    const buildThinkingRows = (): string[] => {
+      const config = selectedConfig();
+      if (!config?.model) return ["  Pick a model first."];
+      const levels = selectedThinkingLevels();
+      if (levels.length === 0) return ["  Model unavailable."];
+      return levels.map((thinking) => `${thinking === config.thinking ? "›" : " "} ${thinking}`);
+    };
+
+    const columnRows = (title: string, rows: string[], width: number, active: boolean): string[] => {
+      return [styledTitle(theme, title, active), ...rows].map((row) => padToWidth(row, width));
+    };
+
+    const render = (width: number): string[] => {
+      const innerWidth = Math.max(1, width);
+      const thinkingWidth = 16;
+      const slotWidth = Math.max(28, Math.floor(innerWidth * 0.38));
+      const modelWidth = Math.max(28, innerWidth - slotWidth - thinkingWidth - 6);
+      const modelRowCount = modelRowsForTerminal();
+      const slotRows = columnRows("slots", buildSlotRows(), slotWidth, activeColumn() === "slots");
+      const modelRows = columnRows(
+        `scoped models${modelFilter ? ` /${modelFilter}` : ""}`,
+        buildModelRows(modelRowCount),
+        modelWidth,
+        activeColumn() === "models",
+      );
+      const thinkingRows = columnRows("thinking", buildThinkingRows(), thinkingWidth, activeColumn() === "thinking");
+      const bodyRows = Math.max(slotRows.length, modelRows.length, thinkingRows.length);
+      const lines = [
+        colors.accent(colors.bold("Agent favorite models")),
+        colors.dim(`${availableModels.length} scoped model(s) available from this Pi session · saves to ${globalSettingsPath()}`),
+        colors.dim("←/→ or tab: move columns · ↑/↓: change selection · type while in scoped models to filter"),
+        colors.dim("enter: save · esc: cancel · delete: clear selected slot · ctrl+a: clear all"),
+        "",
+      ];
+
+      for (let index = 0; index < bodyRows; index += 1) {
+        lines.push(`${slotRows[index] ?? " ".repeat(slotWidth)} │ ${modelRows[index] ?? " ".repeat(modelWidth)} │ ${thinkingRows[index] ?? ""}`);
+      }
+
+      const config = selectedConfig();
+      lines.push("");
+      lines.push(colors.dim(`Selected ${selectedSlot()}: ${config?.model ?? "empty"} · ${config?.thinking ?? "unset"}`));
+      if (notice) {
+        lines.push(colors.warning(notice));
+      }
+      if (config?.model && !availableSet.has(config.model)) {
+        lines.push(colors.warning("This saved model is not in the scoped model list for the current session."));
+      }
+      if (activeColumn() === "models" && modelFilter) {
+        lines.push(colors.dim(`Filter: ${modelFilter}  (backspace clears characters)`));
+      }
+
+      return lines.flatMap((line) => wrapTextWithAnsi(line, innerWidth));
+    };
+
+    const handleInput = (data: string) => {
+      if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+        done("cancelled");
+        return;
+      }
+      if (matchesKey(data, Key.enter) || data === "\r" || data === "\n") {
+        saveAndClose();
+        return;
+      }
+      if (activeColumn() !== "models" && (data === "q" || data === "Q")) {
+        done("cancelled");
+        return;
+      }
+      if (matchesKey(data, Key.right) || data === "l" || data === "L" || matchesKey(data, Key.tab)) {
+        moveColumn(1);
+      } else if (matchesKey(data, Key.left) || data === "h" || data === "H" || matchesKey(data, Key.shift("tab"))) {
+        moveColumn(-1);
+      } else if (matchesKey(data, Key.down) || (activeColumn() !== "models" && (data === "j" || data === "J"))) {
+        moveActiveSelection(1);
+      } else if (matchesKey(data, Key.up) || (activeColumn() !== "models" && (data === "k" || data === "K"))) {
+        moveActiveSelection(-1);
+      } else if (matchesKey(data, Key.delete)) {
+        clearSelectedSlot();
+      } else if (matchesKey(data, Key.ctrl("a"))) {
+        clearAllSlots();
+      } else if (activeColumn() === "models" && matchesKey(data, Key.backspace)) {
+        modelFilter = modelFilter.slice(0, -1);
+        modelScroll = 0;
+      } else if (activeColumn() === "models" && data.length === 1 && data.charCodeAt(0) >= 32) {
+        modelFilter += data;
+        modelScroll = 0;
+      }
+      tui.requestRender();
+    };
+
+    return { render, invalidate() {}, handleInput };
+  }, {
+    overlay: true,
+    overlayOptions: { width: "94%", maxHeight: "86%", anchor: "center" },
+  });
+}
+
+export function registerFavoriteModelsCommand(pi: any): void {
+  pi.registerCommand("agents-favorite-models", {
+    description: "View or configure favorite model/thinking slots for spawned agents.",
+    handler: async (args: string, ctx: any) => {
+      const parts = args.trim().split(/\s+/).filter(Boolean);
+      const action = parts[0];
+
+      try {
+        if (!action) {
+          if (ctx.mode === "tui" && typeof ctx.ui.custom === "function") {
+            const result = await showFavoriteModelsPicker(ctx);
+            if (result === "saved") ctx.ui.notify("Agent favorite models saved.", "info");
+            return;
+          }
+          ctx.ui.notify(formatCurrentSettings(), "info");
+          return;
+        }
+
+        if (action === "set") {
+          if (parts.length !== 4) throw new Error(`Expected: set <slot> <provider/model> <thinking>.\n${usage()}`);
+          const slot = normalizeSlot(parts[1]);
+          const model = normalizeModel(parts[2]);
+          const thinking = normalizeThinking(parts[3]);
+          const registeredModel = (await loadScopedModels(ctx)).find((candidate) => candidate.qualified === model);
+          if (!registeredModel) throw new Error(`Model "${model}" is not available in this Pi session.`);
+          const supportedThinking = getSupportedThinkingLevels(registeredModel);
+          if (!supportedThinking.includes(thinking)) {
+            throw new Error(
+              `Thinking level "${thinking}" is not available for ${model}. Use one of: ${supportedThinking.join(", ")}.`,
+            );
+          }
+          setGlobalFavoriteModel(slot, { model, thinking });
+          ctx.ui.notify(`Set ${slot} to ${model} · ${thinking}.`, "info");
+          return;
+        }
+
+        if (action === "clear") {
+          if (parts.length > 2) throw new Error(`Expected: clear [slot].\n${usage()}`);
+          if (parts[1]) {
+            const slot = normalizeSlot(parts[1]);
+            clearGlobalFavoriteModels({ slot });
+            ctx.ui.notify(`Cleared ${slot}.`, "info");
+          } else {
+            clearGlobalFavoriteModels();
+            ctx.ui.notify("Cleared all agent favorite model slots.", "info");
+          }
+          return;
+        }
+
+        throw new Error(`Unknown action "${action}".\n${usage()}`);
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+      }
+    },
+  });
+}

package/extensions/ui/frame.ts

@@ -0,0 +1,77 @@
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+
+const ANSI_RESET = "\x1b[0m";
+const ANSI_PURPLE = "\x1b[38;5;141m";
+const ANSI_PANEL_BG = "\x1b[48;5;235m";
+const SINGLE_COLUMN_FRAME_TEXT = /^[\x20-\x7E\u00B7]*$/;
+
+// Fill a line to `width` visible columns with the dark panel background. Every
+// full reset emitted by pink/purple/dimAnsi/theme.fg is followed by a fresh
+// background code so embedded foreground colors don't punch holes in the fill.
+function panelBgFillMeasured(line: string, lineWidth: number, width: number, background: string): string {
+  const pad = Math.max(0, width - lineWidth);
+  const reasserted = line.includes(ANSI_RESET)
+    ? line.split(ANSI_RESET).join(ANSI_RESET + background)
+    : line;
+  return `${background}${reasserted}${" ".repeat(pad)}${ANSI_RESET}`;
+}
+
+export function panelBgFill(line: string, width: number, background = ANSI_PANEL_BG): string {
+  return panelBgFillMeasured(line, visibleWidth(line), width, background);
+}
+
+function renderFramePanelRow(line: string, innerWidth: number, span: number, background: string, sideBorder: string): string {
+  const singleColumn = SINGLE_COLUMN_FRAME_TEXT.test(line);
+  if (singleColumn && line.length <= innerWidth) {
+    return `${sideBorder}${background} ${line} ${" ".repeat(innerWidth - line.length)}${ANSI_RESET}${sideBorder}`;
+  }
+  const lineWidth = singleColumn ? line.length : visibleWidth(line);
+  const boundedLine = lineWidth > innerWidth ? truncateToWidth(line, innerWidth, "…", true) : line;
+  const boundedWidth = lineWidth > innerWidth ? (singleColumn ? boundedLine.length : visibleWidth(boundedLine)) : lineWidth;
+  return sideBorder + panelBgFillMeasured(` ${boundedLine} `, boundedWidth + 2, span, background) + sideBorder;
+}
+
+export function createFramePanelRowRenderer(innerWidth: number, background = ANSI_PANEL_BG): (line: string) => string {
+  const span = innerWidth + 2;
+  const sideBorder = `${background}${ANSI_PURPLE}│${ANSI_RESET}`;
+  return (line: string) => renderFramePanelRow(line, innerWidth, span, background, sideBorder);
+}
+
+// Wrap content lines in a rounded border with a dark interior. `innerWidth` is
+// the column count between the one-space padding inside each side border.
+export function framePanel(contentLines: string[], innerWidth: number, background = ANSI_PANEL_BG): string[] {
+  const span = innerWidth + 2;
+  const rule = "─".repeat(span);
+  const border = (text: string) => `${background}${ANSI_PURPLE}${text}${ANSI_RESET}`;
+  const sideBorder = border("│");
+  const out: string[] = [border(`╭${rule}╮`)];
+  for (const line of contentLines) {
+    const lineWidth = visibleWidth(line);
+    const boundedLine = lineWidth > innerWidth ? truncateToWidth(line, innerWidth, "…", true) : line;
+    const boundedWidth = lineWidth > innerWidth ? visibleWidth(boundedLine) : lineWidth;
+    out.push(sideBorder + panelBgFillMeasured(` ${boundedLine} `, boundedWidth + 2, span, background) + sideBorder);
+  }
+  out.push(border(`╰${rule}╯`));
+  return out;
+}
+
+// Self-sizing frame for compact panels so each reads as a distinct dark card.
+export function frameWidget(contentLines: string[]): string[] {
+  const innerWidth = contentLines.reduce((max, line) => Math.max(max, visibleWidth(line)), 0);
+  return framePanel(contentLines, innerWidth);
+}
+
+// Full-width frame for belowEditor status widgets. The returned lines consume
+// the whole render width so the bottom bar has no left/right gutters.
+export function frameWidgetFullWidth(contentLines: string[], width: number): string[] {
+  if (width <= 0) return [];
+  if (width < 4) {
+    return contentLines.map((line) => panelBgFill(truncateToWidth(line, width, "", true), width));
+  }
+  return framePanel(contentLines, width - 4);
+}
+
+export function logWindowStart(totalRows: number, viewportRows: number, offsetFromBottom: number): number {
+  const maxStart = Math.max(0, totalRows - viewportRows);
+  return Math.max(0, maxStart - Math.max(0, Math.min(offsetFromBottom, maxStart)));
+}

package/extensions/ui/input.ts

@@ -0,0 +1,17 @@
+import { Key, matchesKey } from "@mariozechner/pi-tui";
+
+export function isDownInput(data: string): boolean {
+  return matchesKey(data, Key.down) || data === "\x1b[B" || data === "j" || data === "J" || data === "\x0e";
+}
+
+export function isUpInput(data: string): boolean {
+  return matchesKey(data, Key.up) || data === "\x1b[A" || data === "k" || data === "K" || data === "\x10";
+}
+
+export function isLeftInput(data: string): boolean {
+  return matchesKey(data, Key.left) || data === "\x1b[D" || data === "h" || data === "H";
+}
+
+export function isRightInput(data: string): boolean {
+  return matchesKey(data, Key.right) || data === "\x1b[C" || data === "l" || data === "L";
+}

package/extensions/ui/read-agent-status.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import { buildReadAgentIdleNudgeMessage, describeReadAgentStatus, shouldNudgeReadAgentIdle, summarizeReadAgentStatuses } from "./read-agent-status.js";
+import type { RunningReadAgent } from "../runtime/types.js";
+
+function makeAgent(overrides: Partial<RunningReadAgent> = {}): RunningReadAgent {
+  const startedAt = Date.UTC(2026, 0, 1, 0, 0, 0);
+  return {
+    runId: "run-1",
+    name: "reader",
+    teamName: "team",
+    startedAt,
+    tokensUsed: 0,
+    status: "thinking",
+    recentEvents: [],
+    lastActivityAt: startedAt,
+    ...overrides,
+  };
+}
+
+describe("read-agent status descriptions", () => {
+  it("describes normal thinking as waiting for model response", () => {
+    const agent = makeAgent({ status: "thinking" });
+
+    expect(describeReadAgentStatus(agent, agent.startedAt + 10_000)).toMatchObject({
+      label: "thinking",
+      detail: "waiting for model response",
+      idleLevel: "none",
+    });
+  });
+
+  it("describes normal working with the active tool name", () => {
+    const agent = makeAgent({ status: "working", activeToolName: "bash" });
+
+    expect(describeReadAgentStatus(agent, agent.startedAt + 10_000)).toMatchObject({
+      label: "working",
+      detail: "using bash",
+      idleLevel: "none",
+    });
+  });
+
+  it("trusts quiet agents for the first few minutes", () => {
+    const agent = makeAgent({ status: "thinking" });
+
+    expect(describeReadAgentStatus(agent, agent.startedAt + 61_000)).toMatchObject({
+      label: "thinking",
+      detail: "waiting for model response",
+      idleLevel: "none",
+    });
+  });
+
+  it("marks idle agents without instructing the lead to ping", () => {
+    const agent = makeAgent({ status: "thinking" });
+
+    expect(describeReadAgentStatus(agent, agent.startedAt + 301_000)).toMatchObject({
+      label: "idle",
+      detail: "no response/token change for 5m01s · visible in live agent view",
+      idleLevel: "soft",
+      idleMs: 301_000,
+    });
+  });
+
+  it("marks hanging agents without instructing the lead to ping", () => {
+    const agent = makeAgent({ status: "working", activeToolName: "read" });
+
+    expect(describeReadAgentStatus(agent, agent.startedAt + 901_000)).toMatchObject({
+      label: "hanging",
+      detail: "no response/token change for 15m01s · visible in live agent view",
+      idleLevel: "hard",
+      idleMs: 901_000,
+    });
+  });
+
+  it("does not wake the lead for idle/hanging read agents", () => {
+    expect(shouldNudgeReadAgentIdle(undefined, "none")).toBe(false);
+    expect(shouldNudgeReadAgentIdle(undefined, "soft")).toBe(false);
+    expect(shouldNudgeReadAgentIdle("soft", "soft")).toBe(false);
+    expect(shouldNudgeReadAgentIdle("soft", "hard")).toBe(false);
+    expect(shouldNudgeReadAgentIdle("hard", "hard")).toBe(false);
+  });
+
+  it("builds passive idle status messages", () => {
+    const agent = makeAgent({ name: "reviewer", teamName: "status-team" });
+
+    expect(buildReadAgentIdleNudgeMessage(agent, {
+      label: "idle",
+      detail: "",
+      idleLevel: "soft",
+      idleMs: 301_000,
+    })).toBe("Read agent reviewer on team status-team has gone quiet: no response or token change for 5m01s. Status is visible in the live agent view; do not ping/check repeatedly.");
+
+    expect(buildReadAgentIdleNudgeMessage(agent, {
+      label: "hanging",
+      detail: "",
+      idleLevel: "hard",
+      idleMs: 901_000,
+    })).toBe("Read agent reviewer on team status-team appears hung: no response or token change for 15m01s. Status is visible in the live agent view; do not ping/check repeatedly.");
+  });
+
+  it("summarizes many agents while limiting detailed status descriptions", () => {
+    const startedAt = Date.UTC(2026, 0, 1, 0, 0, 0);
+    const now = startedAt + 1_000_000;
+    const agents = [
+      makeAgent({ name: "thinking", status: "thinking", lastActivityAt: now - 10_000 }),
+      makeAgent({ name: "idle", status: "thinking", lastActivityAt: now - 301_000 }),
+      makeAgent({ name: "hanging", status: "working", lastActivityAt: now - 901_000 }),
+      makeAgent({ name: "working", status: "working", activeToolName: "bash", lastActivityAt: now - 5_000 }),
+    ];
+
+    const summary = summarizeReadAgentStatuses(agents, { now, maxDetailed: 2 });
+
+    expect(summary.total).toBe(4);
+    expect(summary.counts).toEqual({ thinking: 1, idle: 1, hanging: 1, working: 1 });
+    expect(summary.samples).toHaveLength(2);
+    expect(summary.samples.map(sample => sample.agent.name)).toEqual(["thinking", "idle"]);
+    expect(summary.samples.map(sample => sample.status.label)).toEqual(["thinking", "idle"]);
+  });
+});