pum-agent 0.1.0-beta.3

package/src/settings-popup.tsx

@@ -0,0 +1,283 @@
+import type { ScrollBoxRenderable } from "@opentui/core";
+import type { Model } from "@earendil-works/pi-ai";
+import { useEffect, useRef } from "react";
+import type { Theme } from "./theme";
+
+/** The seven levels pi accepts. setThinkingLevel() clamps to model capability. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export type SettingRowId =
+  | "theme"
+  | "animations"
+  | "workingRuleAnimation"
+  | "webSearch"
+  | "writingStyle"
+  | "explanationStrength"
+  | "checkMode"
+  | "checkModel"
+  | "thinkingLevel"
+  | "showThinking"
+  | "providers"
+  | "model";
+
+export type SettingRow = {
+  id: SettingRowId;
+  label: string;
+  category: "Appearance" | "Agent" | "Safety";
+  keywords: string;
+  description: string;
+};
+
+export const SETTINGS_ROWS: readonly SettingRow[] = [
+  { id: "theme", label: "Theme", category: "Appearance", keywords: "color palette semantic", description: "Change the semantic color preset. theme.json overrides remain active." },
+  { id: "animations", label: "Animations", category: "Appearance", keywords: "motion global truecolor", description: "Enable interface motion. PUM disables motion when true color is unavailable." },
+  { id: "workingRuleAnimation", label: "Working animation", category: "Appearance", keywords: "rules input header coordinated off motion", description: "Choose how the header and input rules animate while an agent works." },
+  { id: "providers", label: "Providers", category: "Agent", keywords: "login oauth api key custom endpoint", description: "Open provider login or add an OpenAI-compatible custom endpoint." },
+  { id: "model", label: "Model", category: "Agent", keywords: "provider llm active search", description: "Select the model used by the main agent. Search matches provider and model names." },
+  { id: "thinkingLevel", label: "Thinking level", category: "Agent", keywords: "reasoning effort clamp capability", description: "Set reasoning effort. Pi clamps the level to the selected model capability." },
+  { id: "showThinking", label: "Show thinking", category: "Agent", keywords: "reasoning visible transcript trace", description: "Show or hide streamed reasoning traces in the transcript." },
+  { id: "writingStyle", label: "Writing style", category: "Agent", keywords: "response prose ste simplified technical english", description: "Add per-turn response guidance. STE requests concise Simplified Technical English." },
+  { id: "explanationStrength", label: "Explanations", category: "Agent", keywords: "progress updates output none simple detailed rationale", description: "Choose how much regular output explains the agent plan, actions, decisions, and results." },
+  { id: "webSearch", label: "Web search", category: "Agent", keywords: "internet hosted codex provider", description: "Allow hosted web search on supported Codex providers. Other providers are unchanged." },
+  { id: "checkMode", label: "Check mode", category: "Safety", keywords: "verify tools safe fail closed bash edit", description: "Fail-closed safety check for every bash and edit call before execution." },
+  { id: "checkModel", label: "Check model", category: "Safety", keywords: "verifier tools safety model", description: "Select the separate verifier model used by Check mode." },
+];
+
+export function filterSettingsRows(query: string): SettingRow[] {
+  const terms = query.trim().toLocaleLowerCase().split(/\s+/).filter(Boolean);
+  if (terms.length === 0) return [...SETTINGS_ROWS];
+  return SETTINGS_ROWS.filter((row) => {
+    const haystack = `${row.label} ${row.category} ${row.keywords} ${row.description}`.toLocaleLowerCase();
+    return terms.every((term) => haystack.includes(term));
+  });
+}
+
+export function filterModels(
+  models: readonly Model<any>[],
+  query: string,
+  providerName: (providerId: string) => string = () => "",
+): Model<any>[] {
+  const terms = query.trim().toLocaleLowerCase().split(/\s+/).filter(Boolean);
+  if (terms.length === 0) return [...models];
+  return models.filter((model) => {
+    const haystack = `${model.provider} ${providerName(model.provider)} ${model.id} ${model.name ?? ""}`.toLocaleLowerCase();
+    return terms.every((term) => haystack.includes(term));
+  });
+}
+
+export function moveSettingSelection(
+  rows: readonly SettingRow[],
+  selectedId: SettingRowId | null,
+  step: -1 | 1,
+): SettingRowId | null {
+  if (rows.length === 0) return null;
+  const current = rows.findIndex((row) => row.id === selectedId);
+  const start = current < 0 ? (step > 0 ? -1 : 0) : current;
+  return rows[(start + step + rows.length) % rows.length]!.id;
+}
+
+export function isModelSearchShortcut(
+  key: { name: string; sequence: string; ctrl?: boolean; meta?: boolean; option?: boolean },
+  searchFocused: boolean,
+): boolean {
+  return !searchFocused && !key.ctrl && !key.meta && !key.option &&
+    (key.name === "/" || key.sequence === "/");
+}
+
+export function isSettingsSearchShortcut(
+  key: { name: string; sequence: string; ctrl?: boolean; meta?: boolean; option?: boolean },
+  searchFocused: boolean,
+): boolean {
+  return !searchFocused && !key.ctrl && !key.meta && !key.option &&
+    (key.name === "/" || key.sequence === "/");
+}
+
+export type PopupProps = {
+  theme: Theme;
+  page: "main" | "models" | "checkModels";
+  rows: readonly SettingRow[];
+  selectedId: SettingRowId | null;
+  values: Readonly<Record<SettingRowId, string>>;
+  query: string;
+  searchFocused: boolean;
+  terminalWidth: number;
+  terminalHeight: number;
+  models: readonly Model<any>[];
+  modelQuery?: string;
+  modelSearchFocused?: boolean;
+  onSearchChange: (value: string) => void;
+  onModelSearchChange?: (value: string) => void;
+  onSelectModel: (model: Model<any>) => void;
+  onSelectCheckModel: (model: Model<any>) => void;
+};
+
+/**
+ * The popup owns layout only. The keyboard handler in app.tsx owns all menu
+ * navigation and focus transitions.
+ */
+export function SettingsPopup({
+  theme,
+  page,
+  rows,
+  selectedId,
+  values,
+  query,
+  searchFocused,
+  terminalWidth,
+  terminalHeight,
+  models,
+  modelQuery = "",
+  modelSearchFocused = false,
+  onSearchChange,
+  onModelSearchChange = () => {},
+  onSelectModel,
+  onSelectCheckModel,
+}: PopupProps) {
+  const listRef = useRef<ScrollBoxRenderable>(null);
+  const narrow = terminalWidth < 64;
+  const margin = narrow ? 1 : Math.max(2, Math.floor(terminalWidth * 0.1));
+  const popupWidth = Math.max(24, terminalWidth - margin * 2);
+  const popupHeight = Math.max(8, Math.min(terminalHeight - 2, page === "main" ? 20 : 18));
+
+  useEffect(() => {
+    if (selectedId) listRef.current?.scrollChildIntoView(`setting-${selectedId}`);
+  }, [selectedId, rows.length]);
+
+  let lastCategory: SettingRow["category"] | null = null;
+  const selectedRow = rows.find((row) => row.id === selectedId);
+
+  return (
+    <box
+      title={page === "main" ? " Settings " : page === "models" ? " Model " : " Check model "}
+      style={{
+        position: "absolute",
+        top: Math.max(1, Math.floor((terminalHeight - popupHeight) / 2)),
+        left: margin,
+        width: popupWidth,
+        height: popupHeight,
+        zIndex: 100,
+        border: true,
+        borderColor: theme.border,
+        backgroundColor: theme.popupBg,
+        flexDirection: "column",
+        padding: 1,
+      }}
+    >
+      {page === "main" ? (
+        <>
+          <box style={{ height: 1, flexShrink: 0, flexDirection: "row" }}>
+            <box style={{ width: narrow ? 7 : 9, flexShrink: 0 }}>
+              <text content="Search" fg={searchFocused ? theme.accent : theme.dim} bg={theme.popupBg} />
+            </box>
+            <input
+              value={query}
+              placeholder="type to filter"
+              placeholderColor={theme.dim}
+              textColor={theme.fg}
+              cursorColor={theme.accent}
+              focused={searchFocused}
+              onInput={onSearchChange}
+              style={{ flexGrow: 1, minWidth: 0 }}
+            />
+          </box>
+          <box style={{ height: 1, flexShrink: 0 }}>
+            <text content={"─".repeat(Math.max(0, popupWidth - 4))} fg={theme.border} bg={theme.popupBg} />
+          </box>
+          <scrollbox
+            ref={listRef}
+            style={{ flexGrow: 1, minHeight: 1 }}
+            verticalScrollbarOptions={{ visible: true }}
+          >
+            <box style={{ flexDirection: "column", width: "100%", flexShrink: 0 }}>
+              {rows.length === 0 ? (
+                <text content="No matching settings" fg={theme.dim} bg={theme.popupBg} />
+              ) : rows.map((row) => {
+                const showCategory = row.category !== lastCategory;
+                lastCategory = row.category;
+                const selected = selectedId === row.id && !searchFocused;
+                return (
+                  <box key={row.id} style={{ flexDirection: "column", flexShrink: 0 }}>
+                    {showCategory ? (
+                      <text content={row.category} fg={theme.dim} bg={theme.popupBg} />
+                    ) : null}
+                    <box
+                      id={`setting-${row.id}`}
+                      style={{ height: 1, flexShrink: 0, flexDirection: "row" }}
+                    >
+                      <box style={{ width: 2, flexShrink: 0 }}>
+                        {selected ? <text content="› " fg={theme.accent} bg={theme.popupBg} /> : null}
+                      </box>
+                      <text
+                        content={row.label}
+                        fg={selected ? theme.accent : theme.fg}
+                        bg={theme.popupBg}
+                        wrapMode="none"
+                        style={{ width: 18, flexShrink: 0 }}
+                      />
+                      <text
+                        content={values[row.id]}
+                        fg={selected ? theme.accent : theme.fg}
+                        bg={theme.popupBg}
+                        wrapMode="none"
+                        style={{ flexGrow: 1, minWidth: 0 }}
+                      />
+                    </box>
+                  </box>
+                );
+              })}
+            </box>
+          </scrollbox>
+          <box style={{ minHeight: 2, maxHeight: narrow ? 3 : 2, flexShrink: 0 }}>
+            <text
+              content={selectedRow?.description ?? "Type in Search to filter settings."}
+              fg={theme.dim}
+              bg={theme.popupBg}
+              wrapMode="word"
+            />
+          </box>
+          <text
+            content={narrow ? "/ search  ↑↓ move  ←→ change  esc back" : "/ search   ↑↓ move   ←→ change   ⏎ open   esc back"}
+            fg={theme.dim}
+            bg={theme.popupBg}
+            wrapMode="none"
+            style={{ flexShrink: 0 }}
+          />
+        </>
+      ) : (
+        <>
+          <input
+            value={modelQuery}
+            placeholder="Search provider or model"
+            placeholderColor={theme.dim}
+            textColor={theme.fg}
+            cursorColor={theme.accent}
+            focused={modelSearchFocused}
+            onInput={onModelSearchChange}
+            style={{ flexShrink: 0 }}
+          />
+          {models.length === 0 ? <text content="No matching models" fg={theme.dim} bg={theme.popupBg} /> : <select
+          focused={!modelSearchFocused}
+          style={{ flexGrow: 1 }}
+          backgroundColor={theme.popupBg}
+          focusedBackgroundColor={theme.popupBg}
+          textColor={theme.fg}
+          focusedTextColor={theme.fg}
+          selectedBackgroundColor={theme.selectionBg}
+          selectedTextColor={theme.accent}
+          descriptionColor={theme.dim}
+          selectedDescriptionColor={theme.fg}
+          options={models.map((m) => ({ name: m.id, description: m.provider, value: m }))}
+          onSelect={(_index, option) => {
+            if (!option) return;
+            const model = option.value as Model<any>;
+            if (page === "checkModels") onSelectCheckModel(model);
+            else onSelectModel(model);
+          }}
+        />}
+          <text content="/ search   ↑↓ move   enter select   esc back" fg={theme.dim} bg={theme.popupBg} />
+        </>
+      )}
+    </box>
+  );
+}

package/src/settings.ts

@@ -0,0 +1,81 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_DIR } from "./config";
+import { DEFAULT_CHECK_MODEL } from "./check-mode";
+import { isWritingStyle, type WritingStyle } from "./writing-style";
+import {
+  isExplanationStrength,
+  type ExplanationStrength,
+} from "./explanation-strength";
+
+export const WORKING_RULE_ANIMATION_MODES = ["off", "input-only", "coordinated"] as const;
+export type WorkingRuleAnimationMode = (typeof WORKING_RULE_ANIMATION_MODES)[number];
+
+export function isWorkingRuleAnimationMode(value: unknown): value is WorkingRuleAnimationMode {
+  return WORKING_RULE_ANIMATION_MODES.includes(value as WorkingRuleAnimationMode);
+}
+
+/**
+ * PUM's own settings. Model and thinking level are deliberately not here — pi
+ * already persists those to <AGENT_DIR>/settings.json via setModel() and
+ * setThinkingLevel(), and restores them when the session is created.
+ */
+export type PumSettings = {
+  showThinking: boolean;
+  theme: string;
+  animations: boolean;
+  /** Animation used for the rules while an agent works. */
+  workingRuleAnimation: WorkingRuleAnimationMode;
+  webSearch: boolean;
+  writingStyle: WritingStyle;
+  explanationStrength: ExplanationStrength;
+  checkMode: boolean;
+  checkModel: string;
+};
+
+const SETTINGS_PATH = join(AGENT_DIR, "pum.json");
+const DEFAULTS: PumSettings = {
+  showThinking: false,
+  theme: "tokyonight",
+  animations: true,
+  // Preserve the rule-only behavior used before this setting existed.
+  workingRuleAnimation: "input-only",
+  webSearch: true,
+  writingStyle: "none",
+  explanationStrength: "simple",
+  checkMode: false,
+  checkModel: DEFAULT_CHECK_MODEL,
+};
+
+export function normalizeSettings(parsed: unknown): PumSettings {
+  const source = parsed && typeof parsed === "object" ? parsed as Partial<PumSettings> : {};
+  const merged = { ...DEFAULTS, ...source };
+  return {
+    ...merged,
+    animations: typeof merged.animations === "boolean" ? merged.animations : DEFAULTS.animations,
+    workingRuleAnimation: isWorkingRuleAnimationMode(merged.workingRuleAnimation)
+      ? merged.workingRuleAnimation
+      : DEFAULTS.workingRuleAnimation,
+    writingStyle: isWritingStyle(merged.writingStyle) ? merged.writingStyle : DEFAULTS.writingStyle,
+    explanationStrength: isExplanationStrength(merged.explanationStrength)
+      ? merged.explanationStrength
+      : DEFAULTS.explanationStrength,
+    checkMode: typeof merged.checkMode === "boolean" ? merged.checkMode : DEFAULTS.checkMode,
+    checkModel:
+      typeof merged.checkModel === "string" && merged.checkModel.includes("/")
+        ? merged.checkModel
+        : DEFAULTS.checkModel,
+  };
+}
+
+export function loadSettings(): PumSettings {
+  try {
+    return normalizeSettings(JSON.parse(readFileSync(SETTINGS_PATH, "utf8")));
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+export function saveSettings(settings: PumSettings): void {
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+}

package/src/shutdown.ts

@@ -0,0 +1,23 @@
+export type ShutdownActions = {
+  unmount(): void;
+  cleanup(): void;
+  dispose(): Promise<void>;
+  destroy(): void;
+  exit(code: number): void;
+};
+
+export function createShutdown(actions: ShutdownActions): (code: number) => Promise<void> {
+  let exiting = false;
+  return async (code: number): Promise<void> => {
+    if (exiting) return;
+    exiting = true;
+    try {
+      actions.unmount();
+      actions.cleanup();
+      await actions.dispose();
+    } finally {
+      actions.destroy();
+      actions.exit(code);
+    }
+  };
+}

package/src/stash-batch.ts

@@ -0,0 +1,28 @@
+export function selectedRange(anchor: number, cursor: number): Set<number> {
+  const start = Math.min(anchor, cursor);
+  const end = Math.max(anchor, cursor);
+  return new Set(Array.from({ length: end - start + 1 }, (_, offset) => start + offset));
+}
+
+export function buildStashBatchPrompt(prompts: string[]): string {
+  const tasks = prompts.map((prompt, index) => `<task ${index + 1}>\n${prompt}\n</task ${index + 1}>`).join("\n\n");
+  return `Coordinate the following cached tasks with managed worktree subagents.
+
+Rules:
+- Count only starting and running subagents as active. The active limit is five.
+- Use spawn_subagent for implementation work while fewer than five subagents are active.
+- At five active subagents, queue related work to an appropriate running subagent with message_agent.
+- message_agent uses the durable recipient-side message and steering queue.
+- Do not route unrelated work to an arbitrary subagent. Keep it pending when no appropriate recipient is clear.
+- You may group related tasks into one subagent when grouping reduces conflicts or duplicated work.
+- Run independent task groups in parallel.
+- Keep each subagent task complete and self-contained.
+- Track every unfinished task group through completion notifications.
+- Merge each successful subagent with the worktree tool as soon as it settles.
+- Wait to merge only for a concrete dependency, known conflict risk, or required integration order. State that reason explicitly.
+- A successful managed merge closes that subagent and removes its worktree and branch.
+- Do not force-remove an unmerged or failed subagent. Report failures and merge conflicts.
+
+Selected tasks:
+${tasks}`;
+}

package/src/status-bar.tsx

@@ -0,0 +1,143 @@
+import { StyledText, fg, type TextChunk } from "@opentui/core";
+import { useTerminalDimensions } from "@opentui/react";
+import { useShimmerText, useSpinner } from "./animation";
+import {
+  statusMetadataChunks,
+  statusMetadataItems,
+} from "./status-metadata";
+import type { Theme } from "./theme";
+
+export type StatusProps = {
+  theme: Theme;
+  modelId: string;
+  thinkingLevel: string;
+  branch: string | null;
+  outgoingTokens: number;
+  incomingTokens: number;
+  cacheReadTokens: number;
+  cost: number;
+  contextPct: number | null;
+  busy: boolean;
+  elapsedSec: number;
+  agentCount: number;
+  runningAgentCount: number;
+  activeAgentName?: string;
+};
+
+const fmtElapsed = (seconds: number) => {
+  const minutes = Math.floor(seconds / 60);
+  const remaining = seconds % 60;
+  return minutes > 0 ? `${minutes}m ${remaining}s` : `${remaining}s`;
+};
+
+function WorkingPulse({ theme }: { theme: Theme }) {
+  const spinner = useSpinner(true);
+  return <text ref={spinner} fg={theme.accent} />;
+}
+
+function Working({ theme, elapsedSec }: { theme: Theme; elapsedSec: number }) {
+  const label = useShimmerText({
+    text: "working",
+    color: theme.accent,
+    highlight: theme.highlight,
+    active: true,
+  });
+  return (
+    <box style={{ flexDirection: "row" }}>
+      <WorkingPulse theme={theme} />
+      <text content=" " />
+      <text ref={label} />
+      <text content={` ${fmtElapsed(elapsedSec)}  `} fg={theme.dim} />
+    </box>
+  );
+}
+
+export function StatusBar(props: StatusProps) {
+  const {
+    theme,
+    modelId,
+    thinkingLevel,
+    branch,
+    outgoingTokens,
+    incomingTokens,
+    cacheReadTokens,
+    cost,
+    contextPct,
+    busy,
+    agentCount,
+    runningAgentCount,
+    activeAgentName,
+  } = props;
+  const { width } = useTerminalDimensions();
+
+  const left = [
+    fg(theme.accent)(" pum "),
+    fg(theme.dim)("  "),
+    fg(theme.fg)(modelId),
+    fg(theme.dim)(" · "),
+    fg(theme.dim)(thinkingLevel),
+  ];
+  const idleAgentCount = Math.max(0, agentCount - runningAgentCount);
+  const agentPrefix = agentCount > 0 ? " · " : "";
+  const idleAgentText = idleAgentCount > 0 ? `◇ ${idleAgentCount}` : "";
+  const workingAgentText = runningAgentCount > 0 ? `${idleAgentCount > 0 ? " " : ""}• ${runningAgentCount}` : "";
+  const activeAgentText = activeAgentName ? ` · ${activeAgentName}` : "";
+
+  const right: TextChunk[] = statusMetadataChunks(statusMetadataItems({
+    branch,
+    outgoingTokens,
+    incomingTokens,
+    cacheReadTokens,
+    cost,
+    contextPct,
+  }), theme);
+
+  const plainLen = (chunks: { text: string }[]) => chunks.reduce((n, c) => n + c.text.length, 0);
+  // The working indicator is its own element, so allow for it when measuring.
+  const needed = plainLen(left) + agentPrefix.length + idleAgentText.length + workingAgentText.length +
+    activeAgentText.length + plainLen(right) + (busy ? 16 : 0) + 2;
+  const stacked = needed > width;
+
+  const leftRow = (
+    <box style={{ flexDirection: "row", flexGrow: 1, minWidth: 0 }}>
+      <text content={new StyledText(left)} />
+      {agentCount > 0 ? <text content={agentPrefix} fg={theme.dim} /> : null}
+      {idleAgentCount > 0 ? <text content={idleAgentText} fg={theme.success} /> : null}
+      {runningAgentCount > 0 ? (
+        <box style={{ flexDirection: "row" }}>
+          {idleAgentCount > 0 ? <text content=" " /> : null}
+          <WorkingPulse theme={theme} />
+          <text content={` ${runningAgentCount}`} fg={theme.accent} />
+        </box>
+      ) : null}
+      {activeAgentName ? <text content={activeAgentText} fg={theme.dim} /> : null}
+    </box>
+  );
+  const rightRow = (
+    <box style={{ flexDirection: "row", height: 1 }}>
+      {busy ? <Working theme={theme} elapsedSec={props.elapsedSec} /> : null}
+      <text content={new StyledText(right)} />
+      <text content=" " />
+    </box>
+  );
+
+  return (
+    // flexShrink 0: an auto-sized box shrinks by default, and when stacked its
+    // two rows must remain between the explicit header rules in App.
+    <box style={{ flexDirection: "column", flexShrink: 0 }}>
+      {stacked ? (
+        <>
+          <box style={{ flexDirection: "row", height: 1 }}>{leftRow}</box>
+          <box style={{ flexDirection: "row", height: 1, justifyContent: "flex-end" }}>
+            {rightRow}
+          </box>
+        </>
+      ) : (
+        <box style={{ flexDirection: "row", height: 1, justifyContent: "space-between" }}>
+          {leftRow}
+          {rightRow}
+        </box>
+      )}
+    </box>
+  );
+}

package/src/status-metadata.ts

@@ -0,0 +1,110 @@
+import { fg, type TextChunk } from "@opentui/core";
+import type { Theme } from "./theme";
+
+export type StatusMetadataValues = {
+  branch: string | null;
+  outgoingTokens: number;
+  incomingTokens: number;
+  cacheReadTokens: number;
+  cost: number;
+  contextPct: number | null;
+};
+
+export type StatusMetadataItem = {
+  key: "branch" | "outgoing" | "incoming" | "cacheRead" | "cost" | "context";
+  text: string;
+  tone: "branch" | "dim" | "warn";
+  priority: number;
+};
+
+export const formatTokens = (value: number): string => {
+  if (value < 1000) return `${value}`;
+  if (value < 1_000_000) return `${(value / 1000).toFixed(1)}k`;
+  return `${(value / 1_000_000).toFixed(1)}m`;
+};
+
+export const formatCost = (value: number): string =>
+  `$${value < 1 ? value.toFixed(3) : value.toFixed(2)}`;
+
+export function statusMetadataItems(values: StatusMetadataValues): StatusMetadataItem[] {
+  const items: StatusMetadataItem[] = [];
+  if (values.branch) {
+    items.push({ key: "branch", text: values.branch, tone: "branch", priority: 90 });
+  }
+  if (values.outgoingTokens) {
+    items.push({
+      key: "outgoing",
+      text: `↑ ${formatTokens(values.outgoingTokens)}`,
+      tone: "dim",
+      priority: 80,
+    });
+  }
+  if (values.incomingTokens) {
+    items.push({
+      key: "incoming",
+      text: `↓ ${formatTokens(values.incomingTokens)}`,
+      tone: "dim",
+      priority: 70,
+    });
+  }
+  if (values.cacheReadTokens) {
+    items.push({
+      key: "cacheRead",
+      text: `↺ ${formatTokens(values.cacheReadTokens)}`,
+      tone: "dim",
+      priority: 50,
+    });
+  }
+  if (values.cost) {
+    items.push({ key: "cost", text: formatCost(values.cost), tone: "dim", priority: 60 });
+  }
+  if (values.contextPct !== null) {
+    items.push({
+      key: "context",
+      text: `${values.contextPct}%`,
+      tone: values.contextPct > 75 ? "warn" : "dim",
+      priority: 100,
+    });
+  }
+  return items;
+}
+
+export function statusMetadataWidth(items: readonly StatusMetadataItem[]): number {
+  return items.reduce((width, item, index) => width + item.text.length + (index ? 3 : 0), 0);
+}
+
+/** Keep the highest-priority values that fit, then restore StatusBar display order. */
+export function fitStatusMetadata(
+  items: readonly StatusMetadataItem[],
+  maxWidth: number,
+): StatusMetadataItem[] {
+  if (maxWidth <= 0) return [];
+  if (statusMetadataWidth(items) <= maxWidth) return [...items];
+
+  const selected = new Set<StatusMetadataItem>();
+  let used = 0;
+  for (const item of [...items].sort((a, b) => b.priority - a.priority)) {
+    const added = item.text.length + (selected.size ? 3 : 0);
+    if (used + added > maxWidth) continue;
+    selected.add(item);
+    used += added;
+  }
+  return items.filter((item) => selected.has(item));
+}
+
+export function statusMetadataChunks(
+  items: readonly StatusMetadataItem[],
+  theme: Theme,
+): TextChunk[] {
+  const chunks: TextChunk[] = [];
+  for (const item of items) {
+    if (chunks.length) chunks.push(fg(theme.dim)(" · "));
+    const color = item.tone === "branch"
+      ? theme.toolArg
+      : item.tone === "warn"
+        ? theme.warn
+        : theme.dim;
+    chunks.push(fg(color)(item.text));
+  }
+  return chunks;
+}