tmux-ide 2.7.0 → 2.9.0-beta.5

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

@@ -12,26 +12,68 @@
  * to the top when the query looks like a path.
  */
 import { fuzzyFilter } from "../team/fuzzy.ts";
-import type { Tab } from "./app-state.ts";
+import {
+  CANONICAL_SURFACE_REGISTRY,
+  multiplexerVerb,
+  type MultiplexerVerbId,
+  type ProductSurfaceId,
+} from "@tmux-ide/contracts";
+import type { PaletteUsageEntry, Tab } from "./app-state.ts";
 import type { AgentRowInput } from "./agent-rows.ts";
-import { SETTINGS_PALETTE_COMMANDS, type SettingsCommandId } from "./settings-model.ts";
+import type { HostedPanelView } from "./panel-host.ts";
+import { SETTINGS_PALETTE_COMMANDS, type SettingsCommandId } from "./features/settings/catalog.ts";
+import {
+  navigatorEntryMatches,
+  parseNavigatorQuery,
+  type NavigatorEntryScope,
+  type NavigatorStatus,
+} from "@tmux-ide/core";
+
+export interface PalettePaneInput {
+  paneId: string;
+  title: string;
+  session: string;
+  active: boolean;
+}
 
 /** One runnable palette entry. `label` is what the list shows and what the
  *  fuzzy filter scores; `kind` (+ payload) is what the app dispatches on. */
 export type PaletteAction =
+  | { kind: "surface"; surface: ProductSurfaceId; label: string }
   | { kind: "tab"; tab: Tab; label: string }
+  | { kind: "view"; viewId: string; label: string }
   | { kind: "open-folder"; label: string }
   | { kind: "attach"; session: string; label: string }
+  | { kind: "jump-pane"; paneId: string; session: string; label: string }
   | { kind: "jump-agent"; paneId: string; session: string; windowIndex: number; label: string }
+  // The lifecycle verbs (M23.1) — `agentKind` (not `kind`, taken by the action
+  // discriminant) is the manifest id the restart flow resolves a launch
+  // command from. Each fleet agent gets one restart + one stop row; "New
+  // agent…" opens the spawn flow (kind → placement → run) on the dialog stack.
+  | { kind: "new-agent"; label: string }
+  // Repeat the current context's remembered spawn directly — no dialog (M24.1).
+  | { kind: "new-agent-again"; label: string }
+  // The one-surface team console (M24.1): jump/restart/stop + "+ new agent".
+  | { kind: "manage-team"; label: string }
+  | { kind: "restart-agent"; paneId: string; agentKind: string; session: string; label: string }
+  | { kind: "stop-agent"; paneId: string; agentKind: string; session: string; label: string }
   | { kind: "open-file"; path: string; label: string }
+  // "Go to file:" (M24.6) — one row per fuzzy-matched REPO file (workspace-
+  // relative, ignore-respecting, fed by the app via ctx.repoFiles), unlike
+  // open-file whose path is whatever the user typed.
+  | { kind: "go-file"; path: string; label: string }
   | { kind: "save"; label: string }
   | { kind: "refresh-diff"; label: string }
   | { kind: "paste-buffer"; label: string }
+  | { kind: "search-scrollback"; label: string }
   | { kind: "new-window"; label: string }
   | { kind: "rename-window"; name: string; label: string }
   | { kind: "kill-window"; label: string }
   | { kind: "zoom-pane"; label: string }
   | { kind: "swap-pane"; label: string }
+  | { kind: "split-pane-right"; label: string }
+  | { kind: "split-pane-down"; label: string }
+  | { kind: "kill-pane"; label: string }
   | { kind: "break-pane"; label: string }
   | { kind: "rotate-window"; label: string }
   | { kind: "select-layout"; layout: string; label: string }
@@ -39,8 +81,47 @@ export type PaletteAction =
   | { kind: "select-text"; label: string }
   | { kind: "resize-window"; label: string }
   | { kind: "settings"; id: SettingsCommandId; label: string }
+  | { kind: "performance-hud"; label: string }
   | { kind: "quit"; label: string };
 
+/**
+ * Join the OpenTUI palette to the renderer-neutral multiplexer contract.
+ *
+ * The TUI still owns presentation and execution, but it no longer invents the
+ * identity, copy, or availability rules for verbs that the browser also
+ * exposes. TUI-only power-user actions (rotate, layouts, break-pane, sync)
+ * deliberately return null until they become product-wide verbs.
+ */
+export function paletteMultiplexerVerbId(action: PaletteAction): MultiplexerVerbId | null {
+  switch (action.kind) {
+    case "new-window":
+      return "window.new";
+    case "rename-window":
+      return "window.rename";
+    case "kill-window":
+      return "window.kill";
+    case "zoom-pane":
+      return "window.zoom.toggle";
+    case "swap-pane":
+      return "pane.swap";
+    case "split-pane-right":
+      return "pane.split.right";
+    case "split-pane-down":
+      return "pane.split.down";
+    case "kill-pane":
+      return "pane.kill";
+    default:
+      return null;
+  }
+}
+
+function sharedVerbAction<Kind extends PaletteAction["kind"]>(
+  kind: Kind,
+  verbId: MultiplexerVerbId,
+): Extract<PaletteAction, { kind: Kind }> {
+  return { kind, label: multiplexerVerb(verbId).label } as Extract<PaletteAction, { kind: Kind }>;
+}
+
 /** The five tmux `select-layout` presets, offered one palette action each so the
  *  fuzzy filter finds "tiled" / "main-vertical" directly. Shared with the pane
  *  context menu's Layouts submenu (menu-model). */
@@ -61,6 +142,8 @@ export interface PaletteContext {
    *  each, the keyboard twin of the sidebar's clickable agent rows. Already
    *  sorted attention-first by the caller (fleetAgents). */
   agents?: AgentRowInput[];
+  /** Current workspace panes, projected as first-class navigator targets. */
+  panes?: readonly PalettePaneInput[];
   /** A co-attached terminal has sized the tmux window away from our canvas
    *  (M22.8). Only then is the "Resize to fit this window" reclaim action worth
    *  offering — otherwise it is a no-op that clutters the list. */
@@ -69,14 +152,43 @@ export interface PaletteContext {
    *  "Select text in pane" offered (ordinary panes drag-select directly, so the
    *  action would be a no-op that clutters the list). */
   appMousePane?: boolean;
+  /** What the current context's remembered spawn is called (`claude`, a custom
+   *  argv, …) — when set, a direct "New agent: <name> (again)" action is PINNED
+   *  FIRST, so a repeat spawn is F5 → Enter (M24.1's ≤2-Enters bar). */
+  againName?: string | null;
+  /** Palette usage history (M24.4) keyed by {@link paletteActionKey}: drives
+   *  the empty-query "recent" group and the frequency/recency tie-break on a
+   *  typed query. Persisted in app-state. */
+  usage?: Readonly<Record<string, PaletteUsageEntry>>;
+  /** The active surface tab (M24.4) — steers the empty-query "suggested"
+   *  group (Terminal → window/pane verbs + the again spawn; Files → save +
+   *  open-folder). `terminal` above stays THE gate for the window/pane verbs
+   *  so existing callers/tests are untouched. */
+  surface?: Tab;
+  /** Action key → keycap ({@link ../mirror/settings-model.ts}'s
+   *  PALETTE_KEYCAPS) — rows whose action has one right-align it (M24.4).
+   *  app.tsx drops `quit` in HOSTED mode, where ^q detaches instead. */
+  keycaps?: Readonly<Record<string, string>>;
+  /** The workspace's file list (M24.6) — repo-relative paths, gitignore-
+   *  respecting, capped by the caller. A non-empty query offers fuzzy-matched
+   *  "Go to file: <path>" rows via {@link goToFileActions}. */
+  repoFiles?: readonly string[];
+  /** Configured first-class panel views. Only noncanonical custom views are
+   *  appended; the canonical six always come from the product registry. */
+  views?: readonly HostedPanelView[];
 }
 
-const TAB_LABELS: { tab: Tab; label: string }[] = [
-  { tab: "home", label: "Switch tab: Home" },
-  { tab: "terminal", label: "Switch tab: Terminal" },
-  { tab: "files", label: "Switch tab: Files" },
-  { tab: "diff", label: "Switch tab: Diff" },
-];
+const CANONICAL_VIEW_IDS: Readonly<Record<HostedPanelView["panel"], string>> = {
+  home: "home",
+  terminals: "terminals",
+  files: "files",
+  diff: "diff",
+  missions: "missions",
+};
+
+function isNoncanonicalConfiguredView(view: HostedPanelView): boolean {
+  return view.layout !== null || view.id !== CANONICAL_VIEW_IDS[view.panel];
+}
 
 /** PURE — the always-available static actions: the four tab switches, one
  *  attach-session per fleet session, then Save / Refresh diff, the Terminal-only
@@ -85,14 +197,31 @@ export function staticPaletteActions(
   sessions: string[],
   ctx: PaletteContext = {},
 ): PaletteAction[] {
-  const actions: PaletteAction[] = TAB_LABELS.map((t) => ({
-    kind: "tab" as const,
-    tab: t.tab,
-    label: t.label,
-  }));
+  const actions: PaletteAction[] = [];
+  // The repeat spawn (M24.1) — FIRST, above everything: with memory for the
+  // current context, an empty-query Enter repeats the last spawn, making
+  // F5 → Enter the whole gesture (the card's ≤2-Enters acceptance bar).
+  if (ctx.againName) {
+    actions.push({ kind: "new-agent-again", label: `New agent: ${ctx.againName} (again)` });
+  }
+  for (const surface of CANONICAL_SURFACE_REGISTRY) {
+    actions.push({ kind: "surface", surface: surface.id, label: `Open ${surface.label}` });
+  }
+  if (ctx.views) {
+    for (const view of ctx.views.filter(isNoncanonicalConfiguredView)) {
+      actions.push({ kind: "view", viewId: view.id, label: `Switch view: ${view.title}` });
+    }
+  }
   // The non-technicals' front door (M22.5): a filesystem picker → create-or-
   // attach a session in the chosen folder. Offered on every surface.
   actions.push({ kind: "open-folder", label: "Open folder…" });
+  // Spawn an agent (M23.1/M24.1) — offered on every surface; ONE dialog whose
+  // default placement is contextual (split beside a focused pane, else a new
+  // window in the session, else a fresh session).
+  actions.push({ kind: "new-agent", label: "New agent…" });
+  // The team console (M24.1): every fleet agent in one dialog — jump, restart,
+  // stop, spawn. The sidebar agents-header click's keyboard twin.
+  actions.push({ kind: "manage-team", label: "Manage team…" });
   for (const s of sessions) {
     actions.push({ kind: "attach", session: s, label: `Attach session: ${s}` });
   }
@@ -108,33 +237,58 @@ export function staticPaletteActions(
       label: `Agent: ${a.kind} · ${a.session} (${a.state})`,
     });
   }
+  for (const pane of ctx.panes ?? []) {
+    actions.push({
+      kind: "jump-pane",
+      paneId: pane.paneId,
+      session: pane.session,
+      label: `Pane: ${pane.title} · ${pane.session}${pane.active ? " (active)" : ""}`,
+    });
+  }
+  // The per-agent lifecycle verbs (M23.1), grouped after the jumps so an empty
+  // query reads jump-first; the fuzzy filter finds "restart"/"stop" directly.
+  for (const a of ctx.agents ?? []) {
+    const who = `${a.kind} · ${a.session}`;
+    actions.push({
+      kind: "restart-agent",
+      paneId: a.paneId,
+      agentKind: a.kind,
+      session: a.session,
+      label: `Restart agent: ${who}`,
+    });
+    actions.push({
+      kind: "stop-agent",
+      paneId: a.paneId,
+      agentKind: a.kind,
+      session: a.session,
+      label: `Stop agent: ${who}`,
+    });
+  }
   actions.push({ kind: "save", label: "Save file" });
   actions.push({ kind: "refresh-diff", label: "Refresh diff" });
-  // Paste target is the focused surface (a pane, or the editor buffer), so this
-  // is offered on every surface — selecting it opens a second-level list of the
-  // tmux paste buffers rather than dispatching directly.
-  actions.push({ kind: "paste-buffer", label: "Paste buffer…" });
   // The SETTINGS category (M22.4) — every setting is a command; "Settings…" is
   // the categorized umbrella over the same dialogs. Offered on every surface.
   for (const c of SETTINGS_PALETTE_COMMANDS) {
     actions.push({ kind: "settings", id: c.id, label: c.label });
   }
+  actions.push({ kind: "performance-hud", label: "Toggle performance HUD" });
   if (ctx.terminal) {
-    actions.push({ kind: "new-window", label: "New window" });
-    actions.push({ kind: "kill-window", label: "Kill window" });
-    actions.push({ kind: "zoom-pane", label: "Zoom pane" });
-    actions.push({ kind: "swap-pane", label: "Swap pane with next" });
-    actions.push({ kind: "break-pane", label: "Break pane to window" });
-    actions.push({ kind: "rotate-window", label: "Rotate panes" });
-    actions.push({ kind: "sync-toggle", label: "Synchronize panes (toggle)" });
+    // `/` only opens search while scrolled into history (at the live prompt it
+    // belongs to the pane — agents' slash commands); this is the always-there
+    // entry.
+    actions.push({ kind: "search-scrollback", label: "Search scrollback" });
+    actions.push(sharedVerbAction("new-window", "window.new"));
+    actions.push(sharedVerbAction("kill-window", "window.kill"));
+    actions.push(sharedVerbAction("zoom-pane", "window.zoom.toggle"));
+    actions.push(sharedVerbAction("swap-pane", "pane.swap"));
+    actions.push(sharedVerbAction("split-pane-right", "pane.split.right"));
+    actions.push(sharedVerbAction("split-pane-down", "pane.split.down"));
+    actions.push(sharedVerbAction("kill-pane", "pane.kill"));
     // Selection entry on app-mouse panes (M22.9) — the pane menu verb's
     // keyboard twin, offered only where forwarding blocks a direct drag.
     if (ctx.appMousePane) {
       actions.push({ kind: "select-text", label: "Select text in pane" });
     }
-    for (const layout of LAYOUT_PRESETS) {
-      actions.push({ kind: "select-layout", layout, label: `Layout: ${layout}` });
-    }
     // Only when a co-attached terminal is dictating the window size — the reclaim
     // is a no-op otherwise, and we never fight the other terminal unasked.
     if (ctx.sizeMismatch) {
@@ -246,9 +400,135 @@ function looksLikePath(q: string): boolean {
   return /[/.~]/.test(q);
 }
 
+/** Cap on "Go to file:" rows so a big repo never floods the palette. */
+export const GO_FILE_CAP = 8;
+
+/**
+ * PURE (M24.6) — the dynamic "Go to file:" rows for `query`: the repo's
+ * (ignore-respecting) file list fuzzy-filtered against the query, one open
+ * action per match, capped at `cap`. An empty query offers none — the static
+ * list stays uncluttered. Strictly ADDITIVE to the palette: this only CALLS
+ * the shared fuzzy filter, and its rows are appended after the existing
+ * results (see {@link filterPaletteActions}).
+ */
+export function goToFileActions(
+  query: string,
+  repoFiles: readonly string[],
+  cap: number = GO_FILE_CAP,
+): PaletteAction[] {
+  const q = query.trim();
+  if (q.length === 0 || repoFiles.length === 0) return [];
+  return fuzzyFilter(q, [...repoFiles], (p) => p)
+    .slice(0, cap)
+    .map((m) => ({ kind: "go-file" as const, path: m.item, label: `Go to file: ${m.item}` }));
+}
+
+/**
+ * PURE — the STABLE identity of an action for usage history (M24.4): the kind
+ * plus the payload fields that survive restarts (session/layout/settings id/
+ * path — NOT the label, so relabeling never orphans history, and NOT pane ids,
+ * which tmux renumbers). Kinds without a stable payload are keyed by kind
+ * alone (rename-window's typed name is query-dependent, not identity).
+ */
+export function paletteActionKey(a: PaletteAction): string {
+  switch (a.kind) {
+    case "surface":
+      return `surface:${a.surface}`;
+    case "tab":
+      return `tab:${a.tab}`;
+    case "view":
+      return `view:${a.viewId}`;
+    case "attach":
+      return `attach:${a.session}`;
+    case "jump-pane":
+      return `jump-pane:${a.session}:${a.paneId}`;
+    case "jump-agent":
+      return `jump-agent:${a.session}`;
+    case "restart-agent":
+      return `restart-agent:${a.session}:${a.agentKind}`;
+    case "stop-agent":
+      return `stop-agent:${a.session}:${a.agentKind}`;
+    case "select-layout":
+      return `select-layout:${a.layout}`;
+    case "settings":
+      return `settings:${a.id}`;
+    case "open-file":
+      return `open-file:${a.path}`;
+    default:
+      return a.kind;
+  }
+}
+
+export function paletteActionNavigatorScope(action: PaletteAction): NavigatorEntryScope {
+  switch (action.kind) {
+    case "surface":
+    case "tab":
+    case "view":
+    case "open-folder":
+    case "attach":
+      return "workspaces";
+    case "jump-agent":
+    case "new-agent":
+    case "new-agent-again":
+    case "manage-team":
+    case "restart-agent":
+    case "stop-agent":
+      return "agents";
+    case "jump-pane":
+    case "new-window":
+    case "rename-window":
+    case "kill-window":
+    case "zoom-pane":
+    case "swap-pane":
+    case "split-pane-right":
+    case "split-pane-down":
+    case "kill-pane":
+    case "break-pane":
+    case "rotate-window":
+    case "select-layout":
+    case "sync-toggle":
+    case "select-text":
+    case "resize-window":
+      return "panes";
+    default:
+      return "commands";
+  }
+}
+
+function paletteActionNavigatorStatus(
+  action: PaletteAction,
+  agents: readonly AgentRowInput[],
+): NavigatorStatus | null {
+  if (
+    action.kind !== "jump-agent" &&
+    action.kind !== "restart-agent" &&
+    action.kind !== "stop-agent"
+  ) {
+    return null;
+  }
+  const state = agents.find((agent) => agent.paneId === action.paneId)?.state;
+  return state === "blocked" || state === "working" || state === "done" || state === "idle"
+    ? state
+    : null;
+}
+
+/** PURE — the usage comparator (frequency first, then recency): negative when
+ *  `a` should rank before `b`. Unused actions rank last, mutually tied. */
+function compareUsage(
+  a: PaletteAction,
+  b: PaletteAction,
+  usage: Readonly<Record<string, PaletteUsageEntry>> | undefined,
+): number {
+  const ua = usage?.[paletteActionKey(a)];
+  const ub = usage?.[paletteActionKey(b)];
+  return (ub?.count ?? 0) - (ua?.count ?? 0) || (ub?.lastUsed ?? 0) - (ua?.lastUsed ?? 0);
+}
+
 /**
  * PURE — the palette result list for `query`: the static actions fuzzy-filtered
- * and score-sorted, plus (when the query is non-empty) a dynamic
+ * and score-sorted (exact/prefix matches outrank mid-word via the scorer's
+ * label-start weighting; score TIES break by usage — frequency then recency —
+ * M24.4), plus (when the query is non-empty) a dynamic
  * "Open file: <query>" action. That open-file entry is pinned FIRST when the
  * query looks like a path, otherwise appended LAST so it never buries a real
  * match. An empty query returns every static action in natural order.
@@ -258,17 +538,188 @@ export function filterPaletteActions(
   sessions: string[],
   ctx: PaletteContext = {},
 ): PaletteAction[] {
-  const statics = staticPaletteActions(sessions, ctx);
-  const q = query.trim();
+  const parsed = parseNavigatorQuery(query);
+  const statics = staticPaletteActions(sessions, ctx).filter((action) =>
+    navigatorEntryMatches(
+      {
+        scope: paletteActionNavigatorScope(action),
+        status: paletteActionNavigatorStatus(action, ctx.agents ?? []),
+      },
+      parsed,
+    ),
+  );
+  const q = parsed.query.trim();
   const matched =
-    q.length === 0 ? statics : fuzzyFilter(query, statics, (a) => a.label).map((m) => m.item);
+    q.length === 0
+      ? statics
+      : fuzzyFilter(q, statics, (a) => a.label)
+          .sort((x, y) => y.score - x.score || compareUsage(x.item, y.item, ctx.usage))
+          .map((m) => m.item);
   if (q.length === 0) return matched;
-  const dynamic: PaletteAction[] = [{ kind: "open-file", path: q, label: `Open file: ${q}` }];
+  const dynamic: PaletteAction[] =
+    parsed.scope === "all" || parsed.scope === "commands"
+      ? [{ kind: "open-file", path: q, label: `Open file: ${q}` }]
+      : [];
   // On the Terminal surface a non-empty query also offers a rename-to-<query>
   // window verb (there is no way to fuzzy-match a name you are still typing —
   // same reasoning as the open-file entry).
-  if (ctx.terminal) {
+  if (ctx.terminal && (parsed.scope === "all" || parsed.scope === "panes")) {
     dynamic.push({ kind: "rename-window", name: q, label: `Rename window: ${q}` });
   }
-  return looksLikePath(q) ? [...dynamic, ...matched] : [...matched, ...dynamic];
+  // "Go to file:" rows (M24.6) are APPENDED after everything so this addition
+  // cannot disturb the existing result ranking.
+  const goFiles =
+    parsed.scope === "all" || parsed.scope === "commands"
+      ? goToFileActions(q, ctx.repoFiles ?? [])
+      : [];
+  return looksLikePath(q)
+    ? [...dynamic, ...matched, ...goFiles]
+    : [...matched, ...dynamic, ...goFiles];
+}
+
+// ── Grouped rows (M24.4 — the palette's list model) ─────────────────────────
+// The overlay renders ROWS, not bare actions: on an EMPTY query the list opens
+// with a "recent" group (top used actions), a contextual "suggested" group,
+// then everything else under "commands"; a typed query is one flat ranked list
+// (no headers). Headers are real rows — they occupy a screen line, scroll with
+// the list, and are NOT selectable/clickable — so the selection helpers below
+// are what the keyboard/router use to move between action rows.
+
+/** One rendered palette line: a group header, or an action with its optional
+ *  right-aligned keycap (from ctx.keycaps). */
+export type PaletteRow =
+  | { type: "header"; label: string }
+  | { type: "action"; action: PaletteAction; shortcut: string | null };
+
+/** How many actions the empty-query "recent" group shows at most. */
+export const PALETTE_RECENT_LIMIT = 5;
+
+/** The Terminal surface's suggested window/pane verbs, in offer order. */
+const TERMINAL_SUGGESTED_KINDS: ReadonlyArray<PaletteAction["kind"]> = [
+  "new-window",
+  "kill-window",
+  "zoom-pane",
+  "swap-pane",
+  "split-pane-right",
+  "split-pane-down",
+  "kill-pane",
+  "break-pane",
+  "rotate-window",
+];
+
+/**
+ * PURE — the palette rows for `query` (M24.4). A non-empty query is the flat
+ * {@link filterPaletteActions} ranking. An empty query groups:
+ *   1. "recent" — up to {@link PALETTE_RECENT_LIMIT} previously-run actions
+ *      still offerable now (usage keys matched against the current statics),
+ *      most-frequently-used first, recency breaking ties;
+ *   2. "suggested" — BLOCKED agents' jump actions first (ctx.agents arrives
+ *      attention-sorted, so their relative order is the sidebar's), then the
+ *      surface's verbs: Terminal → the again-spawn + window/pane verbs, Files
+ *      → save + open-folder;
+ *   3. "commands" — every remaining action in today's natural order.
+ * With nothing to group (no usage, no suggestions) the list is exactly the
+ * ungrouped statics — no headers, same as before this card.
+ */
+export function paletteRows(
+  query: string,
+  sessions: string[],
+  ctx: PaletteContext = {},
+): PaletteRow[] {
+  const row = (action: PaletteAction): PaletteRow => ({
+    type: "action",
+    action,
+    shortcut: ctx.keycaps?.[paletteActionKey(action)] ?? null,
+  });
+  if (query.trim().length > 0) return filterPaletteActions(query, sessions, ctx).map(row);
+
+  const statics = staticPaletteActions(sessions, ctx);
+  // First static per key — recents resolve through this so a persisted key
+  // finds the action's CURRENT incarnation (relabels don't orphan history).
+  const byKey = new Map<string, PaletteAction>();
+  for (const a of statics) {
+    const k = paletteActionKey(a);
+    if (!byKey.has(k)) byKey.set(k, a);
+  }
+  const taken = new Set<PaletteAction>();
+
+  const recent: PaletteAction[] = [];
+  const usedKeys = Object.entries(ctx.usage ?? {})
+    .sort(([, a], [, b]) => b.count - a.count || b.lastUsed - a.lastUsed)
+    .map(([k]) => k);
+  for (const k of usedKeys) {
+    if (recent.length >= PALETTE_RECENT_LIMIT) break;
+    const a = byKey.get(k);
+    if (a && !taken.has(a)) {
+      recent.push(a);
+      taken.add(a);
+    }
+  }
+
+  const suggested: PaletteAction[] = [];
+  const suggest = (pred: (a: PaletteAction) => boolean): void => {
+    for (const a of statics) {
+      if (!taken.has(a) && pred(a)) {
+        suggested.push(a);
+        taken.add(a);
+      }
+    }
+  };
+  // Blocked agents outrank every other suggestion — they are why the user is
+  // opening the palette (the sidebar's attention-first law, applied here).
+  const blockedPanes = new Set(
+    (ctx.agents ?? []).filter((x) => x.state === "blocked").map((x) => x.paneId),
+  );
+  suggest((a) => a.kind === "jump-agent" && blockedPanes.has(a.paneId));
+  if (ctx.surface === "terminal") {
+    suggest((a) => a.kind === "new-agent-again");
+    suggest((a) => TERMINAL_SUGGESTED_KINDS.includes(a.kind));
+  } else if (ctx.surface === "files") {
+    suggest((a) => a.kind === "save" || a.kind === "open-folder");
+  }
+
+  if (recent.length === 0 && suggested.length === 0) return statics.map(row);
+  const rows: PaletteRow[] = [];
+  if (recent.length > 0) {
+    rows.push({ type: "header", label: "recent" });
+    for (const a of recent) rows.push(row(a));
+  }
+  if (suggested.length > 0) {
+    rows.push({ type: "header", label: "suggested" });
+    for (const a of suggested) rows.push(row(a));
+  }
+  rows.push({ type: "header", label: "commands" });
+  for (const a of statics) if (!taken.has(a)) rows.push(row(a));
+  return rows;
+}
+
+/** PURE — the first selectable (action) row index, or -1 when none. Where the
+ *  selection starts on open/query edits (headers are never selected). */
+export function firstPaletteAction(rows: readonly PaletteRow[]): number {
+  return rows.findIndex((r) => r.type === "action");
+}
+
+/** PURE — the next action row from `cur` in `dir` (±1), skipping headers;
+ *  stays put at the list's ends. The keyboard's up/down. */
+export function stepPaletteRow(rows: readonly PaletteRow[], cur: number, dir: 1 | -1): number {
+  for (let i = cur + dir; i >= 0 && i < rows.length; i += dir) {
+    if (rows[i]!.type === "action") return i;
+  }
+  return cur;
+}
+
+/**
+ * PURE — one action row's text after the selection prefix: the label, then —
+ * when the row has a keycap — right-aligned padding + the keycap inside
+ * `width` cells. The label truncates with an ellipsis so the keycap ALWAYS
+ * fits (min one space between); without a keycap the label just truncates.
+ */
+export function paletteRowText(label: string, shortcut: string | null, width: number): string {
+  if (width <= 0) return "";
+  if (!shortcut || shortcut.length + 2 > width) {
+    return label.length <= width ? label : label.slice(0, Math.max(0, width - 1)) + "…";
+  }
+  const labelMax = width - shortcut.length - 1;
+  const shown = label.length <= labelMax ? label : label.slice(0, Math.max(0, labelMax - 1)) + "…";
+  return shown + " ".repeat(width - shown.length - shortcut.length) + shortcut;
 }