@bastani/atomic 0.9.9 → 0.9.10-alpha.1

package/dist/builtin/workflows/src/tui/session-picker.ts

@@ -1,6 +1,6 @@
 /**
  * Workflow session picker — a centred overlay listing runs the user can
- * connect to (open the orchestrator pane) or kill.
+ * connect to (open the orchestrator pane).
  *
  * Visual contract (DESIGN.md §5 Picker Rows + pi-subagents/src/tui/render-helpers.ts):
  *  - Rounded `╭─ Title ─╮` chrome in `border` colour with title in `accent`.
@@ -162,7 +162,6 @@ function renderHintsRow(width: number, theme: GraphTheme, state: SessionPickerSt
     : [
         hint(`${keyText("tui.select.up")}/${keyText("tui.select.down")}`, "Navigate"),
         hint(keyText("tui.select.confirm"), "Connect"),
-        hint("x", "Kill"),
         hint("a", state.includeAll ? "Active Only" : "All"),
         hint("/", "Filter"),
         hint(keyText("tui.select.cancel"), "Close"),
@@ -333,13 +332,11 @@ export function renderSessionPicker(opts: SessionPickerRenderOpts): string[] {
 export type SessionPickerAction =
   | { kind: "noop" }
   | { kind: "close" }
-  | { kind: "connect"; runId: string }
-  | { kind: "kill"; runId: string };
+  | { kind: "connect"; runId: string };
 
 /**
  * Pure key handler — never mutates anything outside `state`. Returns an
- * action describing what the host should do next (mount the GraphView,
- * fire the kill confirmation, etc.).
+ * action describing what the host should do next (for example, mount the GraphView).
  *
  * Filter-focused mode keeps printable characters routed to `state.query`;
  * Enter exits the filter back to navigation mode.
@@ -401,12 +398,6 @@ export function handleSessionPickerInput(
     if (!row) return { kind: "noop" };
     return { kind: "connect", runId: row.run.id };
   }
-  // `x` = kill. Avoids collision with vim's `k` = up.
-  if (matchesKey(data, "x") || matchesKey(data, Key.shift("x"))) {
-    const row = rows[state.selectedIndex];
-    if (!row || row.run.endedAt !== undefined) return { kind: "noop" };
-    return { kind: "kill", runId: row.run.id };
-  }
 
   return { kind: "noop" };
 }

package/dist/builtin/workflows/src/tui/stage-chat-composer-drafts.ts

@@ -0,0 +1,19 @@
+function draftKey(runId: string, stageId: string): string {
+  return `${runId}\u0000${stageId}`;
+}
+
+/** Live-only composer drafts retained while a workflow overlay remains mounted. */
+export class StageChatComposerDrafts {
+  private readonly drafts = new Map<string, string>();
+
+  get(runId: string, stageId: string): string | undefined {
+    return this.drafts.get(draftKey(runId, stageId));
+  }
+
+  capture(runId: string | null, stageId: string | null, draft: string | undefined): void {
+    if (runId === null || stageId === null || draft === undefined) return;
+    const key = draftKey(runId, stageId);
+    if (draft.length > 0) this.drafts.set(key, draft);
+    else this.drafts.delete(key);
+  }
+}

package/dist/builtin/workflows/src/tui/stage-chat-view-archive-history.ts

@@ -13,6 +13,21 @@ import {
 import type { StageChatViewContext } from "./stage-chat-view-types.js";
 import { hexToAnsi, RESET } from "./color-utils.js";
 
+function postMortemUnavailableMessage(reason: StageChatViewContext["postMortemUnavailableReason"]): string | undefined {
+  switch (reason) {
+    case "no_adapter":
+      return "Post-mortem chat is unavailable because no agent session adapter is configured.";
+    case "not_terminal":
+      return "Post-mortem chat is available only after the stage completes.";
+    case "no_session":
+      return "No retained agent session is available for this stage.";
+    case "invalid_session":
+      return "The retained session is missing, unreadable, or invalid. Check that the session file still exists and is readable.";
+    case undefined:
+      return undefined;
+  }
+}
+
 export function renderReadOnlyArchiveBody(
   ctx: StageChatViewContext,
   width: number,
@@ -24,28 +39,33 @@ export function renderReadOnlyArchiveBody(
   }
 
   const t = ctx.theme;
-  const calloutRows = 5;
-  const transcriptBudget = Math.max(1, budget - calloutRows);
-  const lines = ctx.chatHost.renderBody(width, transcriptBudget);
+  const unavailableMessage = postMortemUnavailableMessage(ctx.postMortemUnavailableReason);
   const callout: string[] = [];
   callout.push(blankLine(width));
   callout.push(
     ...bannerLines(
       ctx,
       width,
-      "info",
-      "◌",
-      "READ-ONLY SESSION",
-      stage?.sessionFile ? "archived transcript" : "no live chat session",
+      unavailableMessage === undefined ? "info" : "warning",
+      unavailableMessage === undefined ? "◌" : "!",
+      unavailableMessage === undefined ? "READ-ONLY SESSION" : "SESSION UNAVAILABLE",
+      unavailableMessage === undefined
+        ? stage?.sessionFile ? "archived transcript" : "no live chat session"
+        : "post-mortem chat cannot be reopened",
     ),
   );
   callout.push(
     ...new Text(
-      paint("This node is no longer attached to a live chat session.", t.textMuted),
+      paint(
+        unavailableMessage ?? "This node is no longer attached to a live chat session.",
+        t.textMuted,
+      ),
       2,
       0,
     ).render(width),
   );
+  const transcriptBudget = Math.max(0, budget - callout.length);
+  const lines = transcriptBudget > 0 ? ctx.chatHost.renderBody(width, transcriptBudget) : [];
   lines.push(...callout);
   while (lines.length < budget) lines.push(blankLine(width));
   if (lines.length > budget) lines.length = budget;
@@ -156,7 +176,7 @@ export function renderPausedBody(
   const callout: string[] = [];
   callout.push(blankLine(width));
   callout.push(
-    ...bannerLines(ctx, width, "warning", "❚❚", "PAUSED", "enter resumes · ctrl+d graph"),
+    ...bannerLines(ctx, width, "warning", "❚❚", "PAUSED", "enter resumes · ctrl+x return to graph"),
   );
   callout.push(
     ...new Text(
@@ -198,7 +218,7 @@ export function renderBlockedBody(
   );
   lines.push(
     ...new Text(
-      paint("ctrl+d", t.accent, { bold: true }) + paint(" return to graph", t.textMuted),
+      paint("ctrl+x", t.accent, { bold: true }) + paint(" return to graph", t.textMuted),
       2,
       0,
     ).render(width),

package/dist/builtin/workflows/src/tui/stage-chat-view-footer-status.ts

@@ -102,11 +102,20 @@ export function embedOrchestratorReturnHintInWidget(
   }
   const lines = [...widgetLines];
   const targetIndex = widgetHintTargetLineIndex(lines);
+  const targetLine = lines[targetIndex] ?? "";
+  const trailingBorder = trailingWidgetBorderChar(targetLine);
+  const plainPrefix = stripAnsi(targetLine)
+    .slice(0, trailingBorder.length > 0 ? -trailingBorder.length : undefined)
+    .trimEnd();
   lines[targetIndex] = mergeOrchestratorReturnHintIntoLine(
     ctx,
-    lines[targetIndex] ?? "",
+    targetLine,
     width,
-    { preserveTrailingBorder: true, rightMargin: 2 },
+    {
+      preserveTrailingBorder: true,
+      rightMargin: 2,
+      minimumPrefixWidth: visibleWidth(plainPrefix) + 1,
+    },
   );
   return lines;
 }
@@ -123,18 +132,18 @@ function mergeOrchestratorReturnHintIntoLine(
 ): string {
   const copyModeState = ctx.mouseScrollCaptureEnabled ? "off" : "on";
   const fullHint = {
-    plain: `ctrl+d graph · ${STAGE_CHAT_MOUSE_SCROLL_TOGGLE_LABEL} copy mode ${copyModeState}`,
+    plain: `ctrl+x return to graph · ${STAGE_CHAT_MOUSE_SCROLL_TOGGLE_LABEL} copy mode ${copyModeState}`,
     styled:
-      paint("ctrl+d", ctx.theme.text, { bold: true }) +
-      paint(" graph · ", ctx.theme.textMuted) +
+      paint("ctrl+x", ctx.theme.text, { bold: true }) +
+      paint(" return to graph · ", ctx.theme.textMuted) +
       paint(STAGE_CHAT_MOUSE_SCROLL_TOGGLE_LABEL, ctx.theme.text, { bold: true }) +
       paint(` copy mode ${copyModeState}`, ctx.theme.textMuted),
   };
   const compactHint = {
-    plain: `ctrl+d · ${STAGE_CHAT_MOUSE_SCROLL_TOGGLE_LABEL} ${copyModeState}`,
+    plain: `ctrl+x graph · ${STAGE_CHAT_MOUSE_SCROLL_TOGGLE_LABEL} ${copyModeState}`,
     styled:
-      paint("ctrl+d", ctx.theme.text, { bold: true }) +
-      paint(" · ", ctx.theme.textMuted) +
+      paint("ctrl+x", ctx.theme.text, { bold: true }) +
+      paint(" graph · ", ctx.theme.textMuted) +
       paint(STAGE_CHAT_MOUSE_SCROLL_TOGGLE_LABEL, ctx.theme.text, { bold: true }) +
       paint(` ${copyModeState}`, ctx.theme.textMuted),
   };
@@ -159,7 +168,8 @@ function mergeOrchestratorReturnHintIntoLine(
     Math.max(0, width - suffixWidth - hintWidth),
   );
   const hintStart = Math.max(0, width - suffixWidth - rightMargin - hintWidth);
-  const prefix = truncateToWidth(line, hintStart, "", true);
+  const prefixWidth = Math.max(0, hintStart - 1);
+  const prefix = truncateToWidth(line, prefixWidth, "", true);
   const gap = Math.max(0, hintStart - visibleWidth(prefix));
   return (
     prefix +

package/dist/builtin/workflows/src/tui/stage-chat-view-input.ts

@@ -4,6 +4,10 @@ import {
   isPromptEscapeInput,
 } from "./prompt-card.js";
 import { APP_ACTION, isKeybindingsLike, matchesAction } from "./keybindings-adapter.js";
+import {
+  parseTerminalMouseInput,
+  terminalMouseWheelDirection,
+} from "./mouse-input.js";
 import {
   setComponentFocused,
   setEditorFocused,
@@ -30,12 +34,21 @@ export function handleStageChatInput(
   ctx: StageChatViewContext,
   data: string,
 ): boolean {
+  if (matchesKey(data, Key.ctrl("x"))) {
+    if (ctx.mountedCustomUi) releaseMountedCustomUi(ctx);
+    else {
+      const stage = currentStage(ctx);
+      syncPromptState(ctx, stage?.pendingPrompt);
+      recordCurrentPromptDraft(ctx);
+    }
+    ctx.onDetach();
+    return true;
+  }
   if (matchesKey(data, Key.ctrl("t"))) {
     ctx.mouseScrollCaptureEnabled = !ctx.mouseScrollCaptureEnabled;
     ctx.requestRender?.();
     return true;
   }
-  if (handleToolsExpandInput(ctx, data)) return true;
   if (ctx.mountedCustomUi) {
     return handleMountedCustomUiInput(ctx, data);
   }
@@ -43,17 +56,13 @@ export function handleStageChatInput(
   syncPromptState(ctx, stage?.pendingPrompt);
   const readOnlyArchive = isReadOnlyArchive(ctx, stage);
   const readOnlyPromptArchive = readOnlyArchive && stage?.promptFootprint !== undefined;
-  if (matchesKey(data, Key.ctrl("d"))) {
-    if (!ctx.promptState && ctx.chatHost.hasInputText()) return ctx.chatHost.handleInput(data);
-    recordCurrentPromptDraft(ctx);
-    ctx.onDetach();
-    return true;
-  }
+
   if (ctx.promptState) {
     if (handlePromptScrollInput(ctx, data, ctx.promptEditor === null)) return true;
     handlePromptInput(ctx, data);
     return true;
   }
+  if (handleToolsExpandInput(ctx, data)) return true;
   if (readOnlyPromptArchive && handlePromptScrollInput(ctx, data, true)) {
     return true;
   }
@@ -108,14 +117,7 @@ function handleMountedCustomUiInput(
     ctx.requestRender?.();
     return true;
   }
-  if (matchesKey(data, Key.ctrl("d"))) {
-    // Detach stops *viewing* the stage; it does not cancel a pending human-input
-    // request. Release the local display only — the request stays pending and
-    // is re-displayed when the user re-attaches.
-    releaseMountedCustomUi(ctx);
-    ctx.onDetach();
-    return true;
-  }
+
   if (matchesKey(data, Key.ctrl("c"))) {
     // Close hides the overlay; the background run — and its pending human-input
     // request — keep living. Release the local display only.
@@ -184,12 +186,18 @@ function handlePromptScrollInput(
   data: string,
   includeKeyboard = true,
 ): boolean {
-  const wheelDeltaRows = mouseWheelDeltaRows(data);
+  const mouse = parseTerminalMouseInput(data);
+  const wheelDirection = mouse ? terminalMouseWheelDirection(mouse) : null;
+  const wheelDeltaRows = wheelDirection === "up"
+    ? -PROMPT_SCROLL_STEP_ROWS
+    : wheelDirection === "down"
+      ? PROMPT_SCROLL_STEP_ROWS
+      : 0;
   if (wheelDeltaRows !== 0) {
     scrollPromptBy(ctx, wheelDeltaRows);
     return true;
   }
-  if (isMouseSequence(data)) return true;
+  if (mouse) return true;
   if (!includeKeyboard) return false;
   if (matchesKey(data, "pageUp")) {
     scrollPromptBy(ctx, -promptPageSize(ctx));
@@ -219,24 +227,3 @@ function scrollPromptBy(ctx: StageChatViewContext, deltaRows: number): void {
   );
   ctx.requestRender?.();
 }
-
-function mouseWheelDeltaRows(data: string): number {
-  const sgr = data.match(/^\x1b\[<(\d+);\d+;\d+M$/);
-  if (sgr) return wheelDeltaForButtonCode(Number.parseInt(sgr[1]!, 10));
-  if (data.startsWith("\x1b[M") && data.length >= 6) {
-    return wheelDeltaForButtonCode(data.charCodeAt(3) - 32);
-  }
-  return 0;
-}
-
-function wheelDeltaForButtonCode(code: number): number {
-  if ((code & 64) === 0) return 0;
-  const direction = code & 3;
-  if (direction === 0) return -PROMPT_SCROLL_STEP_ROWS;
-  if (direction === 1) return PROMPT_SCROLL_STEP_ROWS;
-  return 0;
-}
-
-function isMouseSequence(data: string): boolean {
-  return /^\x1b\[<\d+;\d+;\d+[mM]$/.test(data) || data.startsWith("\x1b[M");
-}

package/dist/builtin/workflows/src/tui/stage-chat-view-render-helpers.ts

@@ -146,7 +146,7 @@ export function renderHintsForPrompt(
     return `${paint("enter", theme.textMuted, { bold: true })} Submit · ${paint("ctrl+c", theme.textMuted, { bold: true })} Skip`;
   }
   if (kind === "custom") {
-    return `${paint("ctrl+d", theme.textMuted, { bold: true })} Graph · ${paint("ctrl+c", theme.textMuted, { bold: true })} Close`;
+    return `${paint("ctrl+x", theme.textMuted, { bold: true })} Return to graph · ${paint("ctrl+c", theme.textMuted, { bold: true })} Close`;
   }
   return `${paint("enter", theme.textMuted, { bold: true })} Select · ${paint("ctrl+c", theme.textMuted, { bold: true })} Skip`;
 }

package/dist/builtin/workflows/src/tui/stage-chat-view-state.ts

@@ -45,6 +45,7 @@ export function initializeStageChatView(
   ctx.stageId = opts.stageId;
   ctx.workflowName = opts.workflowName;
   ctx.handle = opts.handle;
+  ctx.postMortemUnavailableReason = opts.postMortemUnavailableReason;
   ctx.onDetach = opts.onDetach;
   ctx.onClose = opts.onClose;
   ctx.requestRender = opts.requestRender;
@@ -77,6 +78,9 @@ export function initializeStageChatView(
   ctx._unregisterStageUiHost = null;
   installFocusHold(ctx);
   ctx.chatHost = createChatHost(ctx, opts);
+  if (opts.initialComposerDraft !== undefined) {
+    ctx.chatHost.setInputText(opts.initialComposerDraft);
+  }
   ctx._unregisterStageUiHost = ctx.stageUiBroker.registerHost(ctx.runId, ctx.stageId, {
     showCustomUi: (request) => {
       void showCustomUi(ctx, request);
@@ -107,11 +111,8 @@ export function initializeStageChatView(
 function installFocusHold(ctx: StageChatViewContext): void {
   if (!ctx.requestFocus) return;
   ctx.focusHoldTimer = setInterval(() => {
-    // Hold focus on the overlay whenever there is something to interact with:
-    // a mounted custom UI (ask_user_question / readiness gate) must stay
-    // answerable even mid-turn, and an idle composer should keep focus. During
-    // a pure streaming continuation (no custom UI mounted) we leave focus alone
-    // so we never reclaim it out from under the agent's live output.
+    // Keep interactive custom UI and idle composer focus without reclaiming it
+    // from a streaming continuation.
     if (ctx.mountedCustomUi !== null || !isStreaming(ctx)) ctx.requestFocus?.();
   }, 150);
 }
@@ -458,7 +459,7 @@ async function handleSlashCommand(ctx: StageChatViewContext, text: string): Prom
       if (!handle) return false;
       await handle.ensureAttached();
       if (!handle.agentSession) return false;
-      await handle.agentSession.compact();
+      try { await handle.agentSession.compact(); } catch { /* compaction_end owns cancellation/failure UI. */ }
       return true;
     }
     case "/quit":

package/dist/builtin/workflows/src/tui/stage-chat-view-types.ts

@@ -6,6 +6,7 @@ import type {
 } from "@bastani/atomic";
 import type { EditorComponent, EditorTheme, TUI } from "@earendil-works/pi-tui";
 import type { StageControlHandle } from "../runs/foreground/stage-control-registry.js";
+import type { PostMortemUnavailableReason } from "../runs/foreground/postmortem-stage-chat.js";
 import type { Store } from "../shared/store.js";
 import type {
   MountedStageCustomUi,
@@ -32,12 +33,16 @@ export interface StageChatViewOpts {
   stageId: string;
   /** The workflow display name, used in the title chrome `<workflow> / <stage>`. */
   workflowName: string;
+  /** Unsent composer draft restored when reattaching to this stage. */
+  initialComposerDraft?: string;
   /**
    * Live stage-control handle when available. When absent the chat is
    * inspect-only (settled stage with no live handle).
    */
   handle?: StageControlHandle;
-  /** Called when the user presses Ctrl+D (back to graph). */
+  /** Why a retained terminal stage could not be reopened for follow-up chat. */
+  postMortemUnavailableReason?: PostMortemUnavailableReason;
+  /** Called when the user presses Ctrl+X (back to graph). */
   onDetach: (reason?: StageChatDetachReason, metadata?: StageChatDetachMetadata) => void;
   /** Called when the user presses Escape (close the whole popup). */
   onClose: () => void;
@@ -127,6 +132,7 @@ export interface StageChatViewContext {
   stageId: string;
   workflowName: string;
   handle: StageControlHandle | undefined;
+  postMortemUnavailableReason: PostMortemUnavailableReason | undefined;
   onDetach: (reason?: StageChatDetachReason, metadata?: StageChatDetachMetadata) => void;
   onClose: () => void;
   requestRender: (() => void) | undefined;

package/dist/builtin/workflows/src/tui/stage-chat-view.ts

@@ -11,7 +11,7 @@
  *  - Idle stage (empty transcript, not streaming, not settled): Enter prompts.
  *  - Running live stages: Enter steers, Ctrl+F queues a follow-up, Escape uses
  *    the host chat interrupt path.
- *  - Paused stages: Enter resumes with composer text; Ctrl+D returns to graph.
+ *  - Paused stages: Enter resumes with composer text; Ctrl+X returns to graph.
  *  - Blocked and read-only archive stages absorb mutation keystrokes.
  *  - Workflow notices and prompt/custom UI panels keep workflow-specific chrome.
  *
@@ -74,6 +74,7 @@ export class StageChatView implements Component, Focusable {
   private stageId!: StageChatViewContext["stageId"];
   private workflowName!: StageChatViewContext["workflowName"];
   private handle!: StageChatViewContext["handle"];
+  private postMortemUnavailableReason!: StageChatViewContext["postMortemUnavailableReason"];
   private onDetach!: StageChatViewContext["onDetach"];
   private onClose!: StageChatViewContext["onClose"];
   private requestRender!: StageChatViewContext["requestRender"];
@@ -208,6 +209,7 @@ export class StageChatView implements Component, Focusable {
     void this.stageId;
     void this.workflowName;
     void this.handle;
+    void this.postMortemUnavailableReason;
     void this.onDetach;
     void this.onClose;
     void this.requestRender;

package/dist/builtin/workflows/src/tui/store-widget-installer.ts

@@ -3,14 +3,13 @@
  * workflow store using a single long-lived component that is updated in
  * place (issue #1109).
  *
- * Placement note (belowEditor, not aboveEditor): the widget renders a live
- * elapsed clock that re-renders every second. pi-tui full-clears the screen +
- * scrollback whenever a changed line is above the viewport fold. An
+ * Placement note (belowEditor, not aboveEditor): pi-tui full-clears the
+ * screen + scrollback whenever a changed line is above the viewport fold. An
  * aboveEditor widget gets pushed above the fold once the bottom region grows
- * tall, so each clock tick repainted the whole screen (the resize flicker in
+ * tall, so each repaint cleared the whole screen (the resize flicker in
  * #1109). belowEditor keeps the widget among the last rendered lines (always
- * within the bottom viewport), so the clock tick is a clean differential
- * redraw. See the `setWidget` call site for the full rationale.
+ * within the bottom viewport), so a repaint is a clean differential redraw.
+ * See the `setWidget` call site for the full rationale.
  *
  * Pattern:
  *   1. The widget mounts once (`ui.setWidget(WIDGET_KEY, factory)`) on the
@@ -21,23 +20,19 @@
  *      container, and redraws — so re-issuing `setWidget` on each store
  *      mutation or clock tick produces a visible flicker. We therefore call
  *      it only on real mount/unmount transitions.
- *   2. For every other refresh — store mutations that change content and
- *      the one-shot clock-refresh timer alike — we call `ui.requestRender()`
- *      only. Pi re-invokes the *same* mounted component's `render(width)`
- *      with no dispose/remount, so the elapsed-time label keeps ticking
- *      smoothly without flicker.
- *   3. The long-lived component reads the *latest* store snapshot through a
- *      live getter (`() => currentSnap`) at render time, so it is never
- *      visually stale — including after `up-arrow` history recall and other
- *      editor events that force a host re-render without a `setWidget` call.
+ *   2. Semantic store mutations, visible elapsed-clock ticks, and the one-shot
+ *      recent-ended expiry call `ui.requestRender()` only. Pi re-invokes the
+ *      *same* mounted component's `render(width)` with no dispose/remount, so
+ *      elapsed labels advance continuously without lifecycle flicker.
+ *   3. The long-lived component reads the *latest* store snapshot and captured
+ *      clock through live getters at render time, so it is never visually
+ *      stale — including after `up-arrow` history recall and other host renders.
  *   4. The mount / unmount / update / none decision is extracted into the
  *      pure, unit-testable `decideWidgetAction`, keeping this module a thin
  *      orchestration layer over a pure policy (SRP).
- *   5. The widget contents are static per snapshot (no spinner), but the
- *      rendered lines include wall-clock labels (`3s`, `complete · 4s ago`)
- *      and recent-ended visibility. We therefore keep one lightweight
- *      one-shot refresh timer while the widget is visible, matching other
- *      live Atomic widgets without reintroducing a high-frequency spinner.
+ *   5. Running workflows schedule the next exact elapsed-second boundary.
+ *      Paused workflows stay timer-free, and terminal cards use only the
+ *      one-shot recent-ended expiry (`nextWidgetRefreshDelayMs`).
  */
 
 import {
@@ -124,6 +119,10 @@ export function installStoreWidget(
     render: (snap, { theme, width, now }) =>
       buildThemedWidgetLines(snap, theme as PiTheme | undefined, width, now),
     getNextRefreshDelayMs: (snap, now) => nextWidgetRefreshDelayMs(snap, now),
+    // #1856: a store mutation that leaves the rendered card byte-identical
+    // must not broadcast a host-wide render (each one becomes terminal
+    // writes that fight native main-chat scrollback).
+    requestRenderOnStateNoop: false,
     isStaleError: isStale,
   });
 

package/dist/builtin/workflows/src/tui/switcher.ts

@@ -4,7 +4,7 @@
  * Visual contract (DESIGN.md §5 Picker Rows):
  *  - Rounded box, `borderActive` border, `backgroundPanel` interior.
  *  - Header row: leading "stages" caption (dim) + right-aligned key·label
- *    hint (`↑↓ select · ↵ attach · esc close`) in dim.
+ *    hint (`↑↓ select · ↵ open stage chat · esc close`) in dim.
  *  - Default row: `paddingLeft: 1`, `paddingRight: 2`, icon + name, status
  *    glyph coloured.
  *  - Selected row: accent pill (blue bg + surface0 fg + bold). Focus is
@@ -36,8 +36,8 @@ export function filterStages(
   return stages.filter((s) => s.name.toLowerCase().includes(q));
 }
 
-const HINT = "↑↓ select · ↵ attach · esc close";
-const COMPACT_HINT = "↵ attach · esc close";
+const HINT = "↑↓ select · ↵ open stage chat · esc close";
+const COMPACT_HINT = "↵ stage chat · esc close";
 
 /** Pad a visible string (ANSI-safe) to exactly `width` cells. */
 function padVisible(s: string, width: number): string {
@@ -94,7 +94,7 @@ export function renderSwitcher(
   // Top border
   lines.push(`${border}╭${"─".repeat(innerWidth)}╮${RESET}`);
 
-  // Header row: "  STAGES  query   …   ↑↓ select · ↵ attach · esc close "
+  // Header row: "  STAGES  query   …   ↑↓ select · ↵ open stage chat · esc close "
   const leftLabelText = "  STAGES";
   const hint = innerWidth >= 44 ? HINT : COMPACT_HINT;
   const queryBudget = Math.max(