pi-subagents-lite 1.4.1 → 1.4.3

package/src/config/config-store.ts

@@ -20,10 +20,8 @@ import type { AgentManager } from "../agents/agent-manager.js";
 import { CONFIG_AGENT_NON_MODEL_KEYS } from "./types.js";
 import type { SystemPromptMode } from "../agents/types.js";
 import type { ThinkingLevel } from "../types.js";
-import { DEFAULT_CONFIG, loadConfig, saveConfigAtomic } from "./config-io.js";
+import { VALID_SYSTEM_PROMPT_MODES, DEFAULT_CONCURRENCY, loadConfig, saveConfigAtomic } from "./config-io.js";
 
-/** Valid values for systemPromptMode — checked once at module load. */
-const VALID_SYSTEM_PROMPT_MODES = new Set<string>(["replace", "inherit", "custom"]);
 
 /** Injected persistence adapter. Swap for an in-memory adapter in tests. */
 export interface ConfigIO {
@@ -76,6 +74,8 @@ export interface ResolvedAgentSettings {
   readonly showContext: boolean;
   /** Whether to show elapsed time in widget stats line. */
   readonly showTime: boolean;
+  /** Buffer size for streaming thinking blocks to output file. 0 = disabled. */
+  readonly outputThinkingBufferSize: number;
 }
 
 /** Side-effect targets, injected after construction. */
@@ -106,29 +106,22 @@ export class ConfigStore {
 
   get agent(): ResolvedAgentSettings {
     const a = this.config.agent;
-    const widgetMaxLines = a.widgetMaxLines ?? DEFAULT_CONFIG.agent.widgetMaxLines ?? 12;
+    const widgetMaxLines = a.widgetMaxLines!; // guaranteed by loadConfig default merge
     const widgetMaxLinesCompact = a.widgetMaxLinesCompact ?? Math.floor(widgetMaxLines / 2);
-    const widgetCompact = a.widgetCompact === true;
-    const widgetShortcut = a.widgetShortcut === true;
-    const widgetDescLengthFull = a.widgetDescLengthFull ?? DEFAULT_CONFIG.agent.widgetDescLengthFull ?? 50;
-    const widgetDescLengthCompact = a.widgetDescLengthCompact ?? DEFAULT_CONFIG.agent.widgetDescLengthCompact ?? 30;
-    const rawMode = a.systemPromptMode;
-    const systemPromptMode = VALID_SYSTEM_PROMPT_MODES.has(rawMode as string) ? rawMode as SystemPromptMode : "replace";
-    const includeContextFiles = a.includeContextFiles ?? DEFAULT_CONFIG.agent.includeContextFiles ?? true;
 
     return {
       defaultModel: a.default ?? null,
       forceBackground: a.forceBackground === true,
       showCost: this.sessionShowCost ?? (a.showCost === true),
-      graceTurns: a.graceTurns ?? DEFAULT_CONFIG.agent.graceTurns ?? 6,
+      graceTurns: a.graceTurns ?? 6,
       widgetMaxLines,
       widgetMaxLinesCompact,
-      widgetCompact,
-      widgetShortcut,
-      widgetDescLengthFull,
-      widgetDescLengthCompact,
-      systemPromptMode,
-      includeContextFiles,
+      widgetCompact: a.widgetCompact === true,
+      widgetShortcut: a.widgetShortcut === true,
+      widgetDescLengthFull: a.widgetDescLengthFull ?? 50,
+      widgetDescLengthCompact: a.widgetDescLengthCompact ?? 30,
+      systemPromptMode: VALID_SYSTEM_PROMPT_MODES.has(a.systemPromptMode as string) ? (a.systemPromptMode as SystemPromptMode) : "replace",
+      includeContextFiles: a.includeContextFiles ?? true,
       defaultThinking: a.defaultThinking as ThinkingLevel | undefined,
       defaultMaxTurns: a.defaultMaxTurns,
       loadSkillsImplicitly: a.loadSkillsImplicitly !== false,
@@ -140,6 +133,7 @@ export class ConfigStore {
       showOutput: a.showOutput !== false,
       showContext: a.showContext !== false,
       showTime: a.showTime !== false,
+      outputThinkingBufferSize: a.outputThinkingBufferSize ?? 0,
     };
   }
 
@@ -271,6 +265,10 @@ export class ConfigStore {
       setShowOutput: (enabled: boolean) => this.setAgentVisibility("showOutput", enabled),
       setShowContext: (enabled: boolean) => this.setAgentVisibility("showContext", enabled),
       setShowTime: (enabled: boolean) => this.setAgentVisibility("showTime", enabled),
+      setOutputThinkingBufferSize: (size: number): void => {
+        this.config.agent.outputThinkingBufferSize = size;
+        this.persist();
+      },
     },
     widget: {
       setCompact: (enabled: boolean): void => {
@@ -337,7 +335,7 @@ export class ConfigStore {
         this.applyConcurrency();
       },
       reset: (): void => {
-        this.config.concurrency = { ...DEFAULT_CONFIG.concurrency };
+        this.config.concurrency = { ...DEFAULT_CONCURRENCY };
         this.persist();
         this.applyConcurrency();
       },

package/src/config/types.ts

@@ -23,4 +23,5 @@ export const CONFIG_AGENT_NON_MODEL_KEYS = [
   "loadSkillsImplicitly",
   "loadExtensionsImplicitly",
   "disableDefaultAgents",
+  "outputThinkingBufferSize",
 ];

package/src/events.ts

@@ -39,13 +39,15 @@ export function ensureManagerAndWidget(): void {
     const newManager = new AgentManager(
       undefined, // onComplete wired below
       getStore().concurrency as unknown as ConstructorParameters<typeof AgentManager>[1],
+      undefined,
+      getStore().agent.outputThinkingBufferSize,
     );
     setManager(newManager);
     // Sync the manager as a config side-effect target (concurrency setters call setConcurrency).
     getStore().setDeps({ manager: newManager });
 
     // Now create coordinator with the real manager
-    const coordinator = new SpawnCoordinator(newManager, getPiInstance());
+    const coordinator = new SpawnCoordinator(newManager);
     setCoordinator(coordinator);
 
     // Wire the manager's onComplete to the coordinator

package/src/models/model-precedence.ts

@@ -56,6 +56,8 @@ export interface SubagentsConfig {
     widgetDescLengthFull?: number;
     /** Max description length in widget compact mode. Default: 30. */
     widgetDescLengthCompact?: number;
+    /** When > 0, thinking deltas stream to output file during message_update events. Default: 0 (disabled). */
+    outputThinkingBufferSize?: number;
     [agentType: string]: string | null | undefined | boolean | number;
   };
   concurrency: {

package/src/spawn/spawn-coordinator.ts

@@ -1,4 +1,5 @@
 import { getStatusNote } from "../status-note.js";
+import { getPiInstance, getSessionCtx, getWidget } from "../shell.js";
 /**
  * spawn-coordinator.ts — Spawn-and-track coordination for subagents.
  *
@@ -14,7 +15,6 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { AgentRecord, SpawnConfig, ToolActivity } from "../types.js";
 import type { AgentManager, SpawnOptions } from "../agents/agent-manager.js";
 import { buildAgentDetails } from "../agents/tool-execution.js";
-import { getWidget } from "../shell.js";
 
 // ============================================================================
 // Types
@@ -64,12 +64,10 @@ export class SpawnCoordinator {
   /** Active nudge timer. */
   private nudgeTimer: ReturnType<typeof setTimeout> | null = null;
 
-  /** The pi API reference for sending messages. */
-  private pi: ExtensionAPI | null = null;
+  /** Set during dispose to prevent nudge emission after session replacement. */
+  private disposed = false;
 
-  constructor(private manager: AgentManager, pi?: ExtensionAPI) {
-    if (pi) this.pi = pi;
-  }
+  constructor(private manager: AgentManager) {}
 
   /**
    * Spawn + wire tracking + (foreground) await.
@@ -80,9 +78,6 @@ export class SpawnCoordinator {
     ctx: ExtensionContext,
     intent: SpawnIntent,
   ): Promise<SpawnResult> {
-    // Store pi for nudge emission
-    this.pi = pi;
-
     // Create live view BEFORE spawn so callbacks can close over it
     const liveView: LiveView = {
       activeTools: new Map(),
@@ -116,6 +111,9 @@ export class SpawnCoordinator {
       this.backgroundAgentIds.add(agentId);
     }
 
+    // pi is read from shell at nudge time, not stored here
+    // (avoids stale ctx after session replacement or reload)
+
     const record = this.manager.getRecord(agentId)!;
 
     if (!intent.runInBackground) {
@@ -183,7 +181,7 @@ export class SpawnCoordinator {
     this.pendingNudges.clear();
     this.liveViews.clear();
     this.backgroundAgentIds.clear();
-    this.pi = null;
+    this.disposed = true;
   }
 
   // ── Private ──
@@ -208,25 +206,45 @@ export class SpawnCoordinator {
 
   /** Emit an individual nudge for a completed background agent. */
   private emitIndividualNudge(agentId: string): void {
+    // Skip if disposed — prevents stale pi usage after session replacement
+    if (this.disposed) return;
+
+    // Read pi from shell at call time so we get a fresh reference after reload.
+    const pi = getPiInstance();
+    if (!pi) return;
+
     const record = this.manager.getRecord(agentId);
-    if (!record || !this.pi) return;
+    if (!record) return;
 
     const details = buildAgentDetails(record, {
       includeStats: true,
       includeStatus: true,
     });
 
-    this.pi.sendMessage(
-      {
-        customType: "subagent-result",
-        content: `[Subagent "${record.display.type}" ${record.lifecycle.status}]\n\n${record.result ?? ""} ${getStatusNote(record.lifecycle.status)}`,
-        details,
-        display: true,
-      },
-      {
-        deliverAs: "steer",
-        triggerTurn: true,
-      },
-    );
+    try {
+      // Pick delivery mode based on parent session state:
+      // - steer: queues while running, delivers before next LLM call
+      // - followUp: waits for agent to finish, then delivers
+      const ctx = getSessionCtx();
+      const parentIdle = ctx?.isIdle?.() ?? true;
+      const deliverAs = parentIdle ? "followUp" : "steer";
+
+      pi.sendMessage(
+        {
+          customType: "subagent-result",
+          content: `[Subagent "${record.display.type}" ${record.lifecycle.status}]\n\n${record.result ?? ""} ${getStatusNote(record.lifecycle.status)}`,
+          details,
+          display: true,
+        },
+        {
+          deliverAs,
+          triggerTurn: true,
+        },
+      );
+    } catch (error) {
+      // pi may be stale after session replacement (newSession/fork/switchSession).
+      // PI invalidates the extension runner on session.dispose() and never
+      // clears the stale flag for non-reload replacements. Nothing we can do.
+    }
   }
 }

package/src/spawn/worktree-validator.ts

@@ -10,10 +10,7 @@
 
 import * as path from "node:path";
 import { existsSync, statSync, realpathSync } from "node:fs";
-
-/** Timeout for git commands (ms). */
-const GIT_EXEC_TIMEOUT_MS = 5000;
-
+import { GIT_EXEC_TIMEOUT_MS } from "../utils.js";
 /** Specific error messages returned to the LLM for self-correction. */
 export const WORKTREE_VALIDATION_ERRORS = {
   PATH_DOES_NOT_EXIST: "worktree_path does not exist: the specified path was not found on disk",
@@ -60,6 +57,7 @@ async function getGitCommonDir(
   pi: PiExec,
   cwd: string,
   notInRepoError: string,
+  onWarning?: (msg: string) => void,
 ): Promise<{ ok: true; commonDir: string } | { ok: false; error: string }> {
   try {
     const result = await pi.exec("git", ["rev-parse", "--git-common-dir"], { cwd, timeout: GIT_EXEC_TIMEOUT_MS });
@@ -72,7 +70,11 @@ async function getGitCommonDir(
     if (msg.includes("ENOENT") || msg.includes("not found")) {
       return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_NOT_FOUND };
     }
-    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_TIMEOUT };
+    if (msg.includes("timed out") || msg.includes("timeout")) {
+      return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_TIMEOUT };
+    }
+    onWarning?.(`git rev-parse --git-common-dir failed in ${cwd}: ${msg}`);
+    return { ok: false, error: `worktree_path validation failed: git rev-parse failed: ${msg}` };
   }
 }
 
@@ -97,6 +99,7 @@ export async function validateWorktreePath(
   pi: PiExec,
   worktreePath: string,
   parentCwd: string,
+  onWarning?: (msg: string) => void,
 ): Promise<WorktreeValidationResult> {
   // Step 1: Empty / whitespace → treat as omitted
   if (!worktreePath || worktreePath.trim() === "") {
@@ -128,10 +131,10 @@ export async function validateWorktreePath(
   }
 
   // Step 5: Get and compare git-common-dir for parent and target
-  const parentResult = await getGitCommonDir(pi, parentCwd, WORKTREE_VALIDATION_ERRORS.PARENT_NOT_IN_GIT_REPO);
+  const parentResult = await getGitCommonDir(pi, parentCwd, WORKTREE_VALIDATION_ERRORS.PARENT_NOT_IN_GIT_REPO, onWarning);
   if (!parentResult.ok) return parentResult;
 
-  const targetResult = await getGitCommonDir(pi, realPath, WORKTREE_VALIDATION_ERRORS.NOT_IN_GIT_REPO);
+  const targetResult = await getGitCommonDir(pi, realPath, WORKTREE_VALIDATION_ERRORS.NOT_IN_GIT_REPO, onWarning);
   if (!targetResult.ok) return targetResult;
 
   // Compare common dirs — must share the same repo

package/src/ui/agent-widget.ts

@@ -14,7 +14,7 @@ import {
 import { formatMs, buildStatsParts, getDisplayName, truncateDesc, type StatsVisibility } from "./format.js";
 import type { LiveView } from "../spawn/spawn-coordinator.js";
 
-// Re-export Theme so existing consumers (model-selector, result-viewer) don't break
+// Re-export Theme so existing consumers (searchable-select, result-viewer) don't break
 export type { Theme } from "./types.js";
 
 // ---- Constants ----
@@ -56,7 +56,6 @@ const TOOL_DISPLAY: Record<string, string> = {
   write: "writing",
   grep: "searching",
   find: "finding files",
-  ls: "listing",
 };
 
 // ---- Types ----
@@ -136,6 +135,14 @@ function describeActivity(activeTools: Map<string, string>, responseText?: strin
   return THINKING_TEXT;
 }
 
+/** Build the worktree/output continuation line parts for an agent record. */
+function buildWorktreeOutputParts(a: AgentRecord): string[] {
+  const parts: string[] = [];
+  if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
+  if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+  return parts;
+}
+
 // ---- Widget manager ----
 
 export class AgentWidget {
@@ -375,10 +382,8 @@ export class AgentWidget {
     for (const a of finished) {
       const continuations: string[] = [];
       if (!this.isCompact()) {
-        if (a.display.outputFile || a.display.worktreeLabel) {
-          const parts: string[] = [];
-          if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
-          if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+        const parts = buildWorktreeOutputParts(a);
+        if (parts.length > 0) {
           continuations.push(truncate(theme.fg("dim", `${VLINE}    ${parts.join("  ")}`)));
         }
       }
@@ -418,10 +423,8 @@ export class AgentWidget {
         const fullDesc = truncateDesc(a.display.description, this.descLengthFull);
         const headerLine = `${BRANCH} ${theme.fg("accent", frame)} ${theme.bold(name)}  ${fullDesc}  ${statsLine}`;
         const continuations: string[] = [];
-        if (a.display.outputFile || a.display.worktreeLabel) {
-          const parts: string[] = [];
-          if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
-          if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+        const parts = buildWorktreeOutputParts(a);
+        if (parts.length > 0) {
           continuations.push(truncate(`${VLINE}  ` + theme.fg("dim", `${VLINE} ${parts.join("  ")}`)));
         }
         continuations.push(truncate(`${VLINE}  ` + theme.fg("dim", `└ ${activity}`)));
@@ -571,15 +574,14 @@ export class AgentWidget {
     }
 
     // Overflow summary line
-    const overflowLine = hiddenRunning + hiddenFinished > 0
-      ? (() => {
-          const parts: string[] = [];
-          if (hiddenRunning > 0) parts.push(`${hiddenRunning} running`);
-          if (hiddenFinished > 0) parts.push(`${hiddenFinished} finished`);
-          const summary = `+${hiddenRunning + hiddenFinished} more (${parts.join(", ")})`;
-          return `${theme.fg("dim", CORNER)} ${theme.fg("dim", summary)}`;
-        })()
-      : undefined;
+    let overflowLine: string | undefined;
+    if (hiddenRunning + hiddenFinished > 0) {
+      const parts: string[] = [];
+      if (hiddenRunning > 0) parts.push(`${hiddenRunning} running`);
+      if (hiddenFinished > 0) parts.push(`${hiddenFinished} finished`);
+      const summary = `+${hiddenRunning + hiddenFinished} more (${parts.join(", ")})`;
+      overflowLine = `${theme.fg("dim", CORNER)} ${theme.fg("dim", summary)}`;
+    }
 
     return { visible, overflowLine };
   }

package/src/ui/format.ts

@@ -11,7 +11,7 @@
 import { getConfig } from "../agents/agent-types.js";
 import type { SubagentType } from "../agents/types.js";
 import type { Theme } from "./types.js";
-import { formatTokens, formatTokensCompact, formatCost } from "../agents/usage.js";
+import { formatTokens, formatCost } from "../agents/usage.js";
 
 /** Truncate a description string to `maxLen` characters, appending "..." if truncated. */
 export function truncateDesc(text: string, maxLen: number): string {
@@ -44,8 +44,8 @@ function formatSessionTokens(
   compactions = 0,
 ): string {
   const tokenParts: string[] = [];
-  if (inputTokens > 0) tokenParts.push(`↑${formatTokensCompact(inputTokens)}`);
-  if (outputTokens > 0) tokenParts.push(`↓${formatTokensCompact(outputTokens)}`);
+  if (inputTokens > 0) tokenParts.push(`↑${formatTokens(inputTokens, true)}`);
+  if (outputTokens > 0) tokenParts.push(`↓${formatTokens(outputTokens, true)}`);
   const tokenStr = tokenParts.join("");
   const annot: string[] = [];
   if (percent !== null) {

package/src/ui/menu/helpers.ts

@@ -1,19 +1,19 @@
 /**
  * helpers.ts — Shared helpers for menu modules:
  * theme builders for SettingsList/SelectList, numeric validation,
- * model-option building, and a swappable delegating component.
+ * model-option building, a swappable delegating component, and a
+ * searchable pick-list submenu factory.
  */
-
 import type { Component, SettingsListTheme } from "@earendil-works/pi-tui";
-import type { ModelOption } from "../../models/model-selector.js";
+import type { Theme } from "../types.js";
+import { SearchableSelectDialog, type SelectOption } from "../searchable-select.js";
 import { parseModelKey } from "../../utils.js";
-
 /**
- * Build ModelOption[] from raw "provider/model-id" strings.
+ * Build SelectOption[] from raw "provider/model-id" strings.
  * Includes "(inherits parent)" as the first option.
  */
-export function buildModelOptions(rawOptions: string[]): ModelOption[] {
-  const items: ModelOption[] = [
+export function buildModelOptions(rawOptions: string[]): SelectOption[] {
+  const items: SelectOption[] = [
     { value: "(inherits parent)", label: "(inherits parent)", provider: "" },
   ];
 
@@ -33,7 +33,7 @@ export function buildSettingsListTheme(theme: { fg(color: string, text: string):
   return {
     label: (text, selected) => selected ? theme.fg("accent", text) : text,
     value: (text, selected) => selected ? theme.fg("accent", text) : theme.fg("muted", text),
-    description: (text) => theme.fg("muted", text),
+    description: (text) => theme.fg("dim", text),
     // Use "→ " (2 chars) to match non-selected prefix "  " (2 spaces)
     // This prevents menu items from shifting left/right when cursor moves
     cursor: theme.fg("accent", "→ "),
@@ -91,3 +91,33 @@ export function buildSelectListTheme(theme: { fg(color: string, text: string): s
   };
 }
 
+/**
+ * Build a searchable pick-list submenu backed by SearchableSelectDialog.
+ *
+ * Hides the delegator-forward-declaration dance shared by every menu that
+ * needs "type to filter, Enter to pick" over a flat option list
+ * (provider/model/type/worktree selection). onSelect may return a Component
+ * to chain into next (e.g. a numeric-input submenu); returning void leaves
+ * the submenu as-is so the caller can close it via done().
+ */
+export function createSearchableSelect(
+  items: SelectOption[],
+  callbacks: { onSelect: (value: string) => Component | void; onCancel: () => void },
+  theme: Theme,
+): Component {
+  let delegator: ReturnType<typeof createDelegatingComponent>;
+  const selector = new SearchableSelectDialog(
+    items,
+    null,
+    {
+      onSelect: (value) => {
+        const next = callbacks.onSelect(value);
+        if (next) delegator.setActive(next);
+      },
+      onCancel: callbacks.onCancel,
+    },
+    theme,
+  );
+  delegator = createDelegatingComponent(selector);
+  return delegator;
+}

package/src/ui/menu/menu-concurrency.ts

@@ -11,18 +11,26 @@
 
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { SettingsList, SelectList, type SettingItem } from "@earendil-works/pi-tui";
-import { buildSettingsListTheme, buildSelectListTheme, createDelegatingComponent } from "./helpers.js";
+import {
+  buildSettingsListTheme,
+  buildSelectListTheme,
+  buildModelOptions,
+  createDelegatingComponent,
+  createSearchableSelect,
+} from "./helpers.js";
 import { createNumericSubmenu } from "./submenus/numeric-input.js";
 import { createConfirmSubmenu } from "./submenus/confirm.js";
 import { SettingsListWrapper } from "./wrappers/settings-list.js";
 import { getStore } from "../../shell.js";
+import type { SelectOption } from "../searchable-select.js";
+import type { Theme } from "../types.js";
 
 export async function showConcurrencySettingsMenu(
   ctx: ExtensionCommandContext,
   modelOptions: string[],
 ): Promise<void> {
   // Build menu items from current store state.
-  const buildItems = (store: ReturnType<typeof getStore>, theme: any, modelOptions: string[], onRebuild?: () => void): SettingItem[] => {
+  const buildItems = (store: ReturnType<typeof getStore>, theme: Theme, modelOptions: string[], onRebuild?: () => void): SettingItem[] => {
     const providers = [...new Set(modelOptions.map((m) => m.split("/")[0]))].sort();
     const items: SettingItem[] = [];
 
@@ -52,28 +60,28 @@ export async function showConcurrencySettingsMenu(
       return delegator;
     };
 
-    // Submenu factory: pick a key from `options`, then enter a value.
-    const addLimitSubmenu = (
-      options: string[],
+    // Submenu factory: searchable-pick an option, then enter a numeric value.
+    // Used for both per-provider and per-model limits; items differ by caller.
+    const addPickThenValueSubmenu = (
+      items: SelectOption[],
       onPick: (key: string, parsed: number) => void,
-    ): SettingItem["submenu"] => (_currentValue, subDone) => {
-      const list = new SelectList(
-        options.map((o) => ({ value: o, label: o })),
-        10, buildSelectListTheme(theme),
+    ): SettingItem["submenu"] => (_currentValue, subDone) =>
+      createSearchableSelect(
+        items,
+        {
+          onSelect: (key) =>
+            createNumericSubmenu(ctx, { min: 1 }, (parsed) => onPick(key, parsed))("1", subDone),
+          onCancel: () => subDone(),
+        },
+        theme,
       );
-      const delegator = createDelegatingComponent(list);
-      list.onSelect = (item) => {
-        delegator.setActive(createNumericSubmenu(ctx, { min: 1 }, (parsed) => onPick(item.value, parsed))("1", subDone));
-      };
-      list.onCancel = () => subDone();
-      return delegator;
-    };
 
     // Global default
     items.push({
       id: "defaultConcurrency",
       label: "Default concurrency limit",
       currentValue: String(store.concurrency.default),
+      description: "Concurrent agent slots when no per-provider or per-model limit applies.",
       submenu: createNumericSubmenu(ctx, (parsed) => {
         store.mutate.concurrency.setDefault(parsed);
         ctx.ui.notify(`Default concurrency set to ${parsed}`, "info");
@@ -90,6 +98,7 @@ export async function showConcurrencySettingsMenu(
         id: `provider:${provider}`,
         label: provider,
         currentValue: `${limit} slots`,
+        description: `Concurrent slots reserved for agents using the ${provider} provider.`,
         submenu: editOrRemoveSubmenu(
           limit,
           (parsed) => {
@@ -111,7 +120,8 @@ export async function showConcurrencySettingsMenu(
         id: "addProviderLimit",
         label: "Add per-provider limit...",
         currentValue: "",
-        submenu: addLimitSubmenu(providers, (provider, parsed) => {
+        description: "Cap how many agents run at once for a single provider.",
+        submenu: addPickThenValueSubmenu(providers.map((o) => ({ value: o, label: o })), (provider, parsed) => {
           store.mutate.concurrency.setProvider(provider, parsed);
           ctx.ui.notify(`${provider} concurrency set to ${parsed}`, "info");
         }),
@@ -128,6 +138,7 @@ export async function showConcurrencySettingsMenu(
         id: `model:${modelKey}`,
         label: modelKey,
         currentValue: `${limit} slots`,
+        description: `Concurrent slots reserved for agents using the ${modelKey} model.`,
         submenu: editOrRemoveSubmenu(
           limit,
           (parsed) => {
@@ -149,7 +160,8 @@ export async function showConcurrencySettingsMenu(
         id: "addModelLimit",
         label: "Add per-model limit...",
         currentValue: "",
-        submenu: addLimitSubmenu(modelOptions, (modelKey, parsed) => {
+        description: "Cap how many agents run at once for a single model.",
+        submenu: addPickThenValueSubmenu(buildModelOptions(modelOptions), (modelKey, parsed) => {
           store.mutate.concurrency.setModel(modelKey, parsed);
           ctx.ui.notify(`${modelKey} concurrency set to ${parsed}`, "info");
         }),
@@ -162,6 +174,7 @@ export async function showConcurrencySettingsMenu(
       id: "resetAll",
       label: "Reset all to defaults",
       currentValue: "",
+      description: "Restore the default limit and remove all per-provider and per-model limits.",
       submenu: createConfirmSubmenu({
         message: "Reset all concurrency limits to defaults?",
         theme,