lazyclaw 5.2.0 → 5.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyclaw",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama, orchestrating multi-step LLM workflows, and running multi-agent Slack teams with cross-task memory. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
   "keywords": [
     "claude",

package/tui/editor.mjs

@@ -2,6 +2,14 @@
 //
 // Pure-functional core (makeEditorState, applyKey) so it is testable
 // without ink stdin. The React component <Editor/> wraps useInput().
+//
+// v5.4: slash-popup integration. When the parent passes a non-empty
+// `slashSuggestions` array, ↑/↓ move the popup selection (instead of
+// scrolling history) and Tab/Enter fill the buffer with the highlighted
+// command WITHOUT submitting it (Anthropic's recent UX rule: first
+// Enter fills, second Enter runs). Esc clears the buffer + dismisses.
+// All popup-aware branches are guarded by `slashOpen` so legacy callers
+// see the pre-v5.4 behavior verbatim.
 import React, { useState, useEffect } from 'react';
 import { Box, Text, useInput } from 'ink';
 import { theme } from './theme.mjs';
@@ -63,11 +71,83 @@ export function applyKey(state, evt) {
   return next;
 }
 
-export function Editor({ history, onSubmit }) {
+// Pure helper used by the slash-popup branch in <Editor/>. Replaces the
+// editor buffer with `${cmd} ` (note trailing space so the user can keep
+// typing args without an extra keystroke). Does NOT submit.
+export function fillSlashCommand(state, cmd) {
+  const filled = cmd.endsWith(' ') ? cmd : cmd + ' ';
+  return {
+    ...state,
+    buffer: filled,
+    cursor: filled.length,
+    lastSubmit: null,
+    lastWasPaste: false,
+  };
+}
+
+export function Editor({
+  history,
+  onSubmit,
+  onEscape,
+  onBufferChange,
+  // v5.4 slash-popup wiring (all optional — pre-v5.4 callers pass none):
+  slashSuggestions,      // Array<{cmd,help}> | null
+  slashSelectedIndex,    // number
+  onSlashMove,           // (delta: -1 | +1) => void
+  onSlashDismiss,        // () => void
+}) {
   const [state, setState] = useState(() => makeEditorState({ history }));
+  const slashOpen = Array.isArray(slashSuggestions) && slashSuggestions.length > 0;
+
   useInput((input, key) => {
+    // ─── Slash-popup keyboard contract (highest priority when open) ──
+    if (slashOpen) {
+      // Esc: clear the buffer and dismiss the popup. The host's onEscape
+      // is NOT called in this branch — Esc here is a popup gesture, not
+      // a turn-abort. (Outside of popup mode Esc still aborts streaming.)
+      if (key.escape) {
+        const cleared = { ...state, buffer: '', cursor: 0, lastSubmit: null, lastWasPaste: false };
+        setState(cleared);
+        if (onBufferChange) {
+          try { onBufferChange(''); } catch {}
+        }
+        if (onSlashDismiss) onSlashDismiss();
+        return;
+      }
+      // ↑/↓ navigate the popup instead of history.
+      if (key.upArrow) {
+        if (onSlashMove) onSlashMove(-1);
+        return;
+      }
+      if (key.downArrow) {
+        if (onSlashMove) onSlashMove(+1);
+        return;
+      }
+      // Tab / Enter — fill the buffer with the highlighted command.
+      // First Enter fills, second Enter runs (matches Anthropic's UX).
+      if (key.tab || key.return) {
+        const safeIdx = Math.max(0, Math.min(slashSuggestions.length - 1, slashSelectedIndex || 0));
+        const picked = slashSuggestions[safeIdx];
+        if (picked) {
+          const next = fillSlashCommand(state, picked.cmd);
+          setState(next);
+          if (onBufferChange) {
+            try { onBufferChange(next.buffer); } catch {}
+          }
+        }
+        return;
+      }
+      // Anything else (printable, backspace) falls through to applyKey.
+    }
+
+    // Esc: forward to host (ReplApp uses this to abort an in-flight turn).
+    // Do not mutate the buffer — the user may want to keep typing.
+    if (key.escape) { if (onEscape) onEscape(); return; }
     const next = applyKey(state, { input, key });
     setState(next);
+    if (onBufferChange) {
+      try { onBufferChange(next.buffer); } catch { /* observer is best-effort */ }
+    }
   });
   useEffect(() => {
     if (state.lastSubmit !== null && onSubmit) onSubmit(state.lastSubmit);

package/tui/repl.mjs

@@ -1,18 +1,56 @@
 // tui/repl.mjs — REPL host with mid-stream interrupt-and-redirect
-// (spec §5.8). Pure state functions for testability; the React
-// mount lives at the bottom and is exercised only when stdin isTTY.
-import React, { useState, useEffect } from 'react';
-import { Box, useApp } from 'ink';
-import { Splash } from './splash.mjs';
+// (spec §5.8) AND a sticky-bottom chat layout (v5.3).
+//
+// Layout (top → bottom inside the outer column):
+//   1. <Static items={scrollback}/> — splash item + per-turn user/assistant
+//      blocks. Static renders each item ONCE to terminal scrollback and
+//      never re-renders it, so the splash + history scroll away naturally
+//      as new content appends. This is the Claude CLI / opencode pattern
+//      translated to Ink's idiom — Static IS the scroll buffer.
+//   2. Live region — partial assistant stream (state.liveAssistant) and
+//      optional <SlashHints/> while the input buffer starts with '/'.
+//      This Box re-renders on every chunk; the rest of the tree does not.
+//   3. <StatusBar/> — single row above the input. flexShrink:0.
+//   4. <Editor/> — sticky bottom, content-sized (1 line idle, grows with
+//      multiline). Last sibling in the column so it pins to the bottom.
+//
+// Streaming chunks now flow into React state via an injected writeFn
+// (state.liveAssistant += chunk). On turn completion the accumulated
+// text is committed to scrollback so React stops re-rendering it.
+// This closes the v5.0.10 TODO from cli.mjs:2628-2632.
+//
+// Backward-compat contracts (do not break):
+//   - makeReplState()              — still callable with zero args.
+//   - onUserInput, onEscape, onTurnComplete, consumeNextTurnFirstMessage
+//     keep their pre-v5.3 shapes (tests/phaseC-repl-interrupt.test.mjs).
+//   - ReplApp({ splashProps, runTurn })  — legacy callsite (cli.mjs:2637)
+//     still works; runTurn writes go to wherever its writeFn points.
+//   - ReplApp({ splashProps, runTurnFactory })  — new callsite for the
+//     sticky layout; ReplApp injects writeFn → scrollback.
+//
+import React, { useState, useEffect, useRef, useCallback, useMemo } from 'react';
+import { Box, Static, Text, useApp } from 'ink';
+import { Splash, renderSplashToString } from './splash.mjs';
 import { Editor } from './editor.mjs';
+import { SlashPopup, filterSlashCommands } from './slash_popup.mjs';
+import { SLASH_COMMANDS } from './slash_commands.mjs';
+import { theme } from './theme.mjs';
 
-export function makeReplState() {
+// ─── Pure state ──────────────────────────────────────────────────────────
+//
+// makeReplState stays callable with zero args (existing tests rely on it).
+// The new fields default to empty so legacy callers see no behavior change.
+export function makeReplState(opts) {
+  const splashItem = opts && opts.splashItem ? opts.splashItem : null;
   return {
     streaming: false,
     controller: null,
     pendingPrepend: null,
     nextTurnFirstMessage: null,
     history: [],
+    scrollback: splashItem ? [splashItem] : [],
+    liveAssistant: '',
+    turnCounter: 0,
   };
 }
 
@@ -22,12 +60,16 @@ export function onUserInput(state, { text, controller }) {
     try { state.controller.abort(); } catch {}
     return { ...state, pendingPrepend: text };
   }
-  // idle — start a new turn.
+  // idle — start a new turn. Append a 'user' entry to scrollback so the
+  // sticky-layout caller sees the prompt history above the live stream.
+  const id = `u-${state.turnCounter}`;
   return {
     ...state,
     streaming: true,
     controller,
     history: [...state.history, text],
+    scrollback: [...state.scrollback, { kind: 'user', id, text }],
+    turnCounter: state.turnCounter + 1,
   };
 }
 
@@ -35,18 +77,45 @@ export function onEscape(state) {
   if (state.streaming && state.controller) {
     try { state.controller.abort(); } catch {}
   }
-  return { ...state, streaming: false, controller: null, pendingPrepend: null };
+  // Drop any partial live assistant text on explicit Esc — the user is
+  // telling us to discard, not to keep.
+  return {
+    ...state,
+    streaming: false,
+    controller: null,
+    pendingPrepend: null,
+    liveAssistant: '',
+  };
+}
+
+// New reducer: stream chunk arrives, accumulate in liveAssistant.
+export function onStreamChunk(state, { chunk }) {
+  return { ...state, liveAssistant: state.liveAssistant + chunk };
 }
 
 export function onTurnComplete(state, { reason } = {}) {
-  void reason;
   const promoted = state.pendingPrepend;
+  const suffix = reason === 'aborted' ? ' [aborted]'
+              : reason === 'error'   ? ' [error]'
+              : '';
+  const text = (state.liveAssistant || '') + suffix;
+  // Commit any accumulated live text to scrollback. If the turn produced
+  // nothing AND wasn't an error/abort, skip the empty append.
+  const shouldCommit = text.length > 0 && (state.liveAssistant.length > 0 || suffix.length > 0);
+  const id = `a-${state.turnCounter}`;
+  const kind = reason === 'error' ? 'error' : 'assistant';
+  const nextScrollback = shouldCommit
+    ? [...state.scrollback, { kind, id, text }]
+    : state.scrollback;
   return {
     ...state,
     streaming: false,
     controller: null,
     pendingPrepend: null,
     nextTurnFirstMessage: promoted,
+    liveAssistant: '',
+    scrollback: nextScrollback,
+    turnCounter: state.turnCounter + 1,
   };
 }
 
@@ -56,40 +125,202 @@ export function consumeNextTurnFirstMessage(state) {
 }
 
 // ─── React mount ─────────────────────────────────────────────────────────
-// v5.1 TODO (C7 follow-up): replace direct stdout writes in cli.mjs's
-// _chatRunTurnFactory with a scrollback ref'd via this component. The
-// shape would be an `onOutput` prop that pushes chunks into a `useState`
-// array rendered through Ink's <Static items={scrollback}/>. v5.0.10
-// ships with raw stdout writes interleaved with Ink (acceptable visual
-// jank in exchange for unblocking the chat loop).
-export function ReplApp({ splashProps, runTurn }) {
-  const [state, setState] = useState(makeReplState);
+//
+// Two prop modes:
+//   - runTurnFactory(writeFn) → runTurn(text, signal)   (sticky layout)
+//   - runTurn(text, signal)                              (legacy, stdout)
+// Legacy mode is preserved verbatim for the existing cli.mjs callsite.
+export function ReplApp({ splashProps, runTurn, runTurnFactory, slashCommands }) {
+  // Splash is rendered ONCE as scrollback[0] via <Static>. Build it lazily
+  // so SSR-style imports without a TTY don't crash on process.stdout.
+  const splashItemRef = useRef(null);
+  if (splashItemRef.current === null) {
+    splashItemRef.current = splashProps
+      ? { kind: 'splash', id: 'splash-0', splashProps }
+      : null;
+  }
+  const [state, setState] = useState(() => makeReplState({ splashItem: splashItemRef.current }));
   const { exit } = useApp();
 
-  async function handleSubmit(text) {
-    if (text === '/exit') { exit(); return; }
+  // writeFn for run_turn: route chunks into React state instead of stdout.
+  // Only used when runTurnFactory is provided; the legacy `runTurn` prop
+  // keeps writing wherever its caller wired it.
+  const writeFn = useCallback((chunk) => {
+    setState((s) => onStreamChunk(s, { chunk }));
+  }, []);
+
+  // Build the actual runTurn once. Prefer factory (new); fall back to
+  // the legacy `runTurn` prop (existing cli.mjs callsite).
+  const runTurnRef = useRef(null);
+  if (runTurnRef.current === null) {
+    if (typeof runTurnFactory === 'function') {
+      runTurnRef.current = runTurnFactory(writeFn);
+    } else if (typeof runTurn === 'function') {
+      runTurnRef.current = runTurn;
+    } else {
+      runTurnRef.current = async () => {};
+    }
+  }
+
+  const handleSubmit = useCallback(async (text) => {
+    if (text === '/exit' || text === '/quit') { exit(); return; }
     const controller = new AbortController();
     setState((s) => onUserInput(s, { text, controller }));
     try {
-      await runTurn(text, controller.signal);
+      await runTurnRef.current(text, controller.signal);
       setState((s) => onTurnComplete(s, { reason: 'done' }));
     } catch (err) {
-      setState((s) => onTurnComplete(s, { reason: err.name === 'AbortError' ? 'aborted' : 'error' }));
+      setState((s) => onTurnComplete(s, {
+        reason: err && err.name === 'AbortError' ? 'aborted' : 'error',
+      }));
     }
-  }
+  }, [exit]);
 
+  // Auto-submit queued mid-stream-interrupt message (spec §5.8). Read
+  // state.nextTurnFirstMessage so the effect re-fires when promoted.
   useEffect(() => {
-    const [next, msg] = consumeNextTurnFirstMessage(state);
-    if (msg) {
-      setState(next);
+    if (state.nextTurnFirstMessage) {
+      const msg = state.nextTurnFirstMessage;
+      setState((s) => ({ ...s, nextTurnFirstMessage: null }));
       handleSubmit(msg);
     }
-  }, [state.nextTurnFirstMessage]);
+  }, [state.nextTurnFirstMessage, handleSubmit]);
+
+  // Esc handler — abort streaming turn, drop partial output.
+  const onEscapeKey = useCallback(() => {
+    setState((s) => onEscape(s));
+  }, []);
+
+  // ─── Slash popup state (v5.4) ──────────────────────────────────────
+  // The editor reports its current buffer via onBufferChange; we derive
+  // the filtered command list from that and own the selection index.
+  const catalog = useMemo(
+    () => (Array.isArray(slashCommands) && slashCommands.length > 0
+      ? slashCommands : SLASH_COMMANDS),
+    [slashCommands]
+  );
+  const [bufferPeek, setBufferPeek] = useState('');
+  const [selectedSuggestion, setSelectedSuggestion] = useState(0);
+  const filtered = useMemo(
+    () => filterSlashCommands(bufferPeek, catalog),
+    [bufferPeek, catalog]
+  );
+  // Reset selection whenever the match list changes length (typing
+  // narrows results, so highlight the first row again).
+  const lastLenRef = useRef(0);
+  useEffect(() => {
+    if (filtered.length !== lastLenRef.current) {
+      setSelectedSuggestion(0);
+      lastLenRef.current = filtered.length;
+    } else if (selectedSuggestion >= filtered.length) {
+      setSelectedSuggestion(Math.max(0, filtered.length - 1));
+    }
+  }, [filtered.length, selectedSuggestion]);
+
+  const handleBufferChange = useCallback((buf) => {
+    setBufferPeek(buf || '');
+  }, []);
+  const handleSlashMove = useCallback((delta) => {
+    setSelectedSuggestion((i) => {
+      const max = Math.max(0, filtered.length - 1);
+      const n = i + delta;
+      if (n < 0) return 0;
+      if (n > max) return max;
+      return n;
+    });
+  }, [filtered.length]);
+  const handleSlashDismiss = useCallback(() => {
+    setBufferPeek('');
+    setSelectedSuggestion(0);
+  }, []);
+
+  const showSlashPopup = bufferPeek.startsWith('/') && filtered.length > 0;
 
   return React.createElement(
     Box,
     { flexDirection: 'column' },
-    React.createElement(Splash, splashProps),
-    React.createElement(Editor, { history: state.history, onSubmit: handleSubmit })
+    // 1) Scrollback (write-once via Ink Static)
+    React.createElement(
+      Static,
+      { items: state.scrollback },
+      (item) => React.createElement(ScrollbackItem, { key: item.id, item })
+    ),
+    // 2) Live region — partial assistant stream
+    state.liveAssistant
+      ? React.createElement(
+          Box,
+          { flexDirection: 'column' },
+          React.createElement(Text, { color: theme.fg }, state.liveAssistant)
+        )
+      : null,
+    // 3) Slash popup — flex sibling above the StatusBar; Ink can't
+    //    absolutely position so this is the "just above input" pattern.
+    showSlashPopup
+      ? React.createElement(SlashPopup, {
+          buffer: bufferPeek,
+          commands: filtered,
+          selectedIndex: selectedSuggestion,
+        })
+      : null,
+    // 4) Status bar (sticky, single row above input)
+    React.createElement(StatusBar, {
+      provider: splashProps && splashProps.provider,
+      model: splashProps && splashProps.model,
+      streaming: state.streaming,
+      ctxUsed: splashProps && splashProps.ctxUsed,
+      ctxTotal: splashProps && splashProps.ctxTotal,
+    }),
+    // 5) Editor — sticky bottom, content-sized
+    React.createElement(Editor, {
+      history: state.history,
+      onSubmit: handleSubmit,
+      onEscape: onEscapeKey,
+      onBufferChange: handleBufferChange,
+      slashSuggestions: showSlashPopup ? filtered : null,
+      slashSelectedIndex: selectedSuggestion,
+      onSlashMove: handleSlashMove,
+      onSlashDismiss: handleSlashDismiss,
+    })
   );
 }
+
+// ScrollbackItem renders each <Static/> child. Splash renders via the
+// real <Splash/> component (preserves gradient wordmark colorization);
+// everything else is plain Text.
+export function ScrollbackItem({ item }) {
+  if (item.kind === 'splash') {
+    return React.createElement(Splash, item.splashProps);
+  }
+  if (item.kind === 'user') {
+    return React.createElement(
+      Box,
+      { flexDirection: 'column' },
+      React.createElement(Text, null, theme.accent('› ') + item.text)
+    );
+  }
+  if (item.kind === 'error') {
+    return React.createElement(Text, { color: 'red' }, item.text);
+  }
+  // 'assistant' (default)
+  return React.createElement(Text, { color: theme.fg }, item.text);
+}
+
+// StatusBar — single row, provider · model · ctx · streaming indicator.
+// Kept intentionally minimal in v5.3; token gauges land separately once
+// usage metrics flow into state.
+export function StatusBar({ provider, model, streaming, ctxUsed, ctxTotal }) {
+  const ctx = (ctxUsed != null && ctxTotal != null) ? `${ctxUsed}/${ctxTotal}` : '--';
+  const indicator = streaming ? theme.accent('● streaming') : theme.dim('○ idle');
+  const prov = provider || '?';
+  const mdl = model || '?';
+  return React.createElement(
+    Box,
+    { flexShrink: 0, paddingX: 1 },
+    React.createElement(Text, null, `${indicator}  ${prov} · ${mdl}  ctx ${ctx}`)
+  );
+}
+
+// Exported for tests that want to verify the splash snapshot without a TTY.
+export function _renderSplashToString(splashProps) {
+  return renderSplashToString(splashProps);
+}

package/tui/slash_commands.mjs

@@ -0,0 +1,37 @@
+// tui/slash_commands.mjs — single source of truth for the REPL slash-command
+// catalog. Imported by both cli.mjs (legacy ghost-autocomplete + /help dump)
+// and tui/slash_popup.mjs (Ink popup chooser). Keeping the list here avoids
+// a tui/ → cli.mjs circular import.
+//
+// Schema:
+//   { cmd: string, help: string }
+//
+// Order matters — it is the order shown in the popup and in /help. New
+// commands should be appended unless there is a UX reason to slot them in.
+
+export const SLASH_COMMANDS = [
+  { cmd: '/help',        help: 'list available slash commands' },
+  { cmd: '/status',      help: 'print current provider, model, masked key' },
+  { cmd: '/version',     help: 'print version + node + platform' },
+  { cmd: '/new',         help: 'clear conversation and start over' },
+  { cmd: '/reset',       help: 'alias for /new' },
+  { cmd: '/usage',       help: 'show message count + chars sent so far' },
+  { cmd: '/skills',      help: 'list and activate skills (alias /skill)' },
+  { cmd: '/skill',       help: 'switch active skills: /skill review,style (no arg → clear)' },
+  { cmd: '/tools',       help: 'list available tool registry verbs' },
+  { cmd: '/provider',    help: 'switch provider: /provider openai (no arg → print current)' },
+  { cmd: '/model',       help: 'switch model: /model gpt-4.1 or anthropic/claude-opus-4-7' },
+  { cmd: '/trainer',     help: 'configure trainer provider/model for learning loop' },
+  { cmd: '/personality', help: 'switch agent personality preset' },
+  { cmd: '/loop',        help: 'repeat one prompt: /loop "fix lint" [--max N] [--until "<regex>"]' },
+  { cmd: '/goal',        help: 'register/switch goal: /goal add NAME | /goal list' },
+  { cmd: '/memory',      help: 'show layered memory: /memory [core|recent|episodic [topic]]' },
+  { cmd: '/recall',      help: 'FTS5 recall across sessions and memory' },
+  { cmd: '/dream',       help: 'consolidate recent memory into per-topic episodic files' },
+  { cmd: '/agent',       help: 'spawn or switch agent: /agent NAME' },
+  { cmd: '/team',        help: 'list, create, or join a team' },
+  { cmd: '/task',        help: 'create, list, or manage tasks' },
+  { cmd: '/handoff',     help: 'hand current task off to another agent' },
+  { cmd: '/exit',        help: 'leave the chat' },
+  { cmd: '/quit',        help: 'alias for /exit' },
+];

package/tui/slash_popup.mjs

@@ -0,0 +1,157 @@
+// tui/slash_popup.mjs — Ink popup chooser for slash commands.
+//
+// Renders a bordered, vertically-stacked list of slash-command suggestions
+// just above the input row. Selection state lives in the parent (ReplApp),
+// because the Editor owns the keyboard. This component is purely
+// presentational so it can be snapshotted and rendered without an Ink
+// runtime.
+//
+// Ink has no absolute positioning, so "popup" here means "flex sibling
+// rendered between the live region and the StatusBar". When the popup is
+// visible the live region naturally shrinks by its row count, which is the
+// same trick Claude CLI uses.
+//
+// Two exports:
+//   - filterSlashCommands(buffer, commands)  → pure, unit-testable
+//   - <SlashPopup buffer commands selectedIndex maxRows />  → presentational
+
+import React from 'react';
+import { Box, Text } from 'ink';
+import { theme } from './theme.mjs';
+import { SLASH_COMMANDS as DEFAULT_SLASH_COMMANDS } from './slash_commands.mjs';
+
+export { DEFAULT_SLASH_COMMANDS };
+
+// ─── Pure filter ─────────────────────────────────────────────────────────
+//
+// Returns the subset of `commands` to show in the popup for the current
+// `buffer`. Empty array means "dismiss popup". See the inline cases for
+// the precedence — prefix first, then substring fallback, then space-arg
+// degeneration into a single-row inline hint.
+export function filterSlashCommands(buffer, commands) {
+  if (!buffer || !buffer.startsWith('/')) return [];
+  const space = buffer.indexOf(' ');
+  if (space > 0) {
+    // User has typed args. Popup degenerates into a one-row inline hint
+    // showing only the matched command's help text.
+    const head = buffer.slice(0, space);
+    return commands.filter((c) => c.cmd === head);
+  }
+  if (buffer === '/') return commands.slice();
+  const q = buffer.toLowerCase();
+  const prefix = commands.filter((c) => c.cmd.toLowerCase().startsWith(q));
+  if (prefix.length > 0) return prefix;
+  // Substring fallback: '/em' → /memory. Strip the leading '/' on both
+  // sides so the substring search isn't dominated by the trigger char.
+  const sub = commands.filter((c) =>
+    c.cmd.slice(1).toLowerCase().includes(q.slice(1))
+  );
+  return sub;
+}
+
+// Truncate help text to a column budget, preserving the leading space.
+// Never wraps — the popup is a single row per command.
+function _truncate(s, max) {
+  if (max <= 0) return '';
+  if (s.length <= max) return s;
+  if (max <= 1) return s.slice(0, max);
+  return s.slice(0, max - 1) + '…';
+}
+
+// Window a long match list around the selected row so the popup doesn't
+// grow taller than `maxRows`. Returns `{ visible, windowStart }`.
+export function _computeWindow(matches, selectedIndex, maxRows) {
+  if (matches.length <= maxRows) return { visible: matches, windowStart: 0 };
+  const half = Math.floor(maxRows / 2);
+  let start = Math.max(0, selectedIndex - half);
+  const end = Math.min(matches.length, start + maxRows);
+  // Re-anchor if we overflowed past the end.
+  start = Math.max(0, end - maxRows);
+  return { visible: matches.slice(start, start + maxRows), windowStart: start };
+}
+
+// ─── Component ───────────────────────────────────────────────────────────
+//
+// Props:
+//   buffer        — string, current editor buffer (used for the inline hint)
+//   commands      — Array<{cmd,help}>, already filtered by caller
+//   selectedIndex — number, index into `commands`
+//   maxRows       — number, max visible rows (defaults to 8)
+//   columns       — number, terminal width (defaults to process.stdout.columns)
+//
+// When `columns < 50` the popup collapses to a single column (cmd only).
+export function SlashPopup({
+  buffer = '',
+  commands = [],
+  selectedIndex = 0,
+  maxRows = 8,
+  columns,
+}) {
+  if (!commands || commands.length === 0) return null;
+  const cols = columns
+    || (process.stdout && process.stdout.columns)
+    || 80;
+  const compact = cols < 50;
+  const safeSelected = Math.max(0, Math.min(commands.length - 1, selectedIndex));
+  const { visible, windowStart } = _computeWindow(commands, safeSelected, maxRows);
+
+  // Inline-hint mode: buffer already has args + a single match. Render
+  // the help text on one dimmed line. No border, no chooser.
+  const isInlineHint = buffer.includes(' ') && commands.length === 1;
+  if (isInlineHint) {
+    const c = commands[0];
+    return React.createElement(
+      Box,
+      { paddingX: 1 },
+      React.createElement(Text, { dimColor: true },
+        `${c.cmd} — ${_truncate(c.help, Math.max(10, cols - c.cmd.length - 5))}`
+      )
+    );
+  }
+
+  // Reserve 2 chars border + 2 padding + cmd column (14) + 1 gap.
+  const cmdCol = 14;
+  const helpBudget = Math.max(0, cols - cmdCol - 6);
+
+  return React.createElement(
+    Box,
+    {
+      flexDirection: 'column',
+      borderStyle: 'round',
+      borderColor: 'gray',
+      paddingX: 1,
+    },
+    visible.map((c, i) => {
+      const absIdx = i + windowStart;
+      const isSel = absIdx === safeSelected;
+      const cmdText = c.cmd.padEnd(cmdCol);
+      return React.createElement(
+        Box,
+        { key: c.cmd },
+        React.createElement(
+          Text,
+          {
+            inverse: isSel,
+            color: isSel ? theme.amber : undefined,
+            bold: isSel,
+          },
+          cmdText
+        ),
+        !compact
+          ? React.createElement(
+              Text,
+              { dimColor: true },
+              ' ' + _truncate(c.help, helpBudget)
+            )
+          : null
+      );
+    }),
+    commands.length > maxRows
+      ? React.createElement(
+          Text,
+          { dimColor: true },
+          `  ${safeSelected + 1}/${commands.length}`
+        )
+      : null
+  );
+}

package/tui/splash.mjs

@@ -3,10 +3,10 @@
 //
 // Layout (terminal-width responsive across four tiers):
 //
-//   WIDE     (cols >= 140) — full wordmark + panel + sloth + 2-col right side
-//   MEDIUM   ( 90 <= cols < 140) — compact headline, panel + sloth + wrapped right column
-//   NARROW   ( 60 <= cols <  90) — single column, no sloth/panel, truncated verb lists
-//   MINIMAL  (cols <  60)  — headline + provider + cwd + /help line only
+//   WIDE     (cols >= 140) — full wordmark + panel + sloth side-by-side
+//   MEDIUM   ( 90 <= cols < 140) — compact headline, sloth side-by-side, wrapped right column
+//   NARROW   ( 45 <= cols <  90) — sloth STACKED above full-width panel, wrapped verbs
+//   MINIMAL  (cols <  45)  — headline + provider + cwd + /help line only
 import React from 'react';
 import { Box, Text } from 'ink';
 import stringWidth from 'string-width';
@@ -19,11 +19,12 @@ const TITLE = ' trainer-split · FTS5 recall · 6-backend sandbox ';
 
 // Tier breakpoints. Wordmark is 120 cols wide + LMARGIN(2)*2 = 124 minimum;
 // the user constraint pins WIDE at >=140 to give comfortable slack. Below
-// 90 the sloth (48 cols) leaves <40 cols for the right column, so we drop
-// it and go single-column. Below 60 we emit only a minimal headline.
+// 90 the sloth (48 cols) cannot share a row with a usable right column,
+// so NARROW stacks the sloth ABOVE a full-width wrapped panel. Below 45
+// even a stacked sloth overflows, so MINIMAL absorbs that range.
 const WORDMARK_BREAKPOINT = 140;  // drop wordmark below this
-const PANEL_BREAKPOINT    = 90;   // drop sloth+panel below this
-const MINIMAL_BREAKPOINT  = 60;   // drop everything but headline below this
+const MEDIUM_BREAKPOINT   = 90;   // side-by-side sloth+panel above this; stacked below
+const NARROW_BREAKPOINT   = 45;   // headline-only fallback below this
 
 // Subcommand catalog — grouped for the splash so a new user sees the
 // surface area at a glance. Mirrors SUBCOMMANDS in cli.mjs.
@@ -99,16 +100,6 @@ function wrapVerbs(label, verbs, maxWidth) {
   return rows;
 }
 
-// Crush-style truncation for NARROW tier — take first N verbs, append '…' if more.
-function truncateRow(label, verbs, maxWidth, take = 3) {
-  const head = label.padEnd(12) + ' ';
-  const tail = verbs.slice(0, take).join(' · ');
-  let line = head + tail;
-  if (verbs.length > take) line += ' …';
-  if (stringWidth(line) <= maxWidth) return line;
-  return fit(line, maxWidth).trimEnd();
-}
-
 // Wide tier — original v5.0.9 layout, kept verbatim.
 function renderWide(props, cols) {
   const PANEL_W = cols - LMARGIN.length * 2;
@@ -274,45 +265,76 @@ function renderMedium(props, cols) {
   return lines;
 }
 
-// Narrow tier — single column, no sloth, no panel, truncated verb lists.
+// Narrow tier — sloth STACKED above a full-width panel; verb lists wrap
+// onto multiple rows instead of being truncated. Used for 45 <= cols < 90.
 function renderNarrow(props, cols) {
-  const W = cols - LMARGIN.length * 2;
+  const PANEL_W = cols - LMARGIN.length * 2;
+  const INNER = PANEL_W - 4;
+  const SLOTH_W = banner.width;
   const lines = [];
 
-  // 1) headline
+  // 1) sloth banner CENTERED above panel (stacked layout).
+  //    Only emit if the sloth itself fits within the terminal; otherwise
+  //    skip it (MINIMAL absorbs the truly tiny case below NARROW_BREAKPOINT).
+  if (cols >= SLOTH_W + LMARGIN.length * 2) {
+    const leftPad = ' '.repeat(Math.max(0, Math.floor((cols - SLOTH_W) / 2)));
+    for (const r of banner.rows) lines.push(leftPad + r);
+    lines.push('');
+  }
+
+  // 2) compact headline (no wordmark — too wide).
   lines.push(`${LMARGIN}lazyclaw ${props.version || ''}`.trimEnd());
   lines.push('');
 
-  const { tools = [], skills = [], provider, model, trainer = {}, sessionId, cwd } = props;
+  // 3) panel top — version label only, dashes fill remainder.
+  const versionLabel = ` lazyclaw ${props.version || ''} `;
+  const dashLeft = '─'.repeat(2);
+  const dashRight = '─'.repeat(Math.max(2, PANEL_W - 2 - dashLeft.length - stringWidth(versionLabel)));
+  lines.push(`${LMARGIN}╭${dashLeft}${versionLabel}${dashRight}╮`);
 
-  // 2) subcommands
-  lines.push(`${LMARGIN}Subcommands`);
+  // 4) panel body — full-width single column, wrapped via wrapVerbs.
+  const { tools = [], skills = [] } = props;
+  const body = [];
+  body.push('Subcommands');
   for (const [label, verbs] of SUBCOMMAND_GROUPS) {
-    lines.push(LMARGIN + truncateRow(label, verbs, W));
+    for (const r of wrapVerbs(label, verbs, INNER)) body.push(r);
   }
-  lines.push('');
-
-  // 3) tools
-  lines.push(`${LMARGIN}Available Tools`);
+  body.push('');
+  body.push('Available Tools');
   for (const t of tools.slice(0, 14)) {
     const label = t.sensitive ? `${t.category}*` : t.category;
-    lines.push(LMARGIN + truncateRow(label, t.verbs, W));
+    for (const r of wrapVerbs(label, t.verbs.slice(0, 6), INNER)) body.push(r);
   }
-  if (tools.length > 14) lines.push(`${LMARGIN}(and ${tools.length - 14} more...)`);
-  lines.push('');
-
-  // 4) skills
-  lines.push(`${LMARGIN}Available Skills`);
-  if (skills.length === 0) lines.push(`${LMARGIN}(none installed)`);
+  if (tools.length > 14) body.push(`(and ${tools.length - 14} more...)`);
+  body.push('');
+  body.push('Available Skills');
+  if (skills.length === 0) body.push('(none installed)');
   else {
     for (const s of skills.slice(0, 8)) {
-      lines.push(LMARGIN + truncateRow(s.group, s.names, W));
+      for (const r of wrapVerbs(s.group, s.names.slice(0, 6), INNER)) body.push(r);
     }
-    if (skills.length > 8) lines.push(`${LMARGIN}(and ${skills.length - 8} more skill groups...)`);
+    if (skills.length > 8) body.push(`(and ${skills.length - 8} more skill groups...)`);
   }
+  body.push('');
+  const subcmdCount = SUBCOMMAND_GROUPS.reduce((n, [, v]) => n + v.length, 0);
+  const summary = `${subcmdCount} subcmds · ${tools.length} tools · ${skills.length} skills · /help`;
+  if (stringWidth(summary) > INNER) {
+    body.push(`${subcmdCount} subcmds · ${tools.length} tools · ${skills.length} skills`);
+    body.push('/help for commands');
+  } else {
+    body.push(summary);
+  }
+
+  // 5) emit panel rows (single column, full INNER width, pad with spaces).
+  for (const row of body) {
+    const padded = row + ' '.repeat(Math.max(0, INNER - stringWidth(row)));
+    lines.push(`${LMARGIN}│ ${padded} │`);
+  }
+  lines.push(`${LMARGIN}╰${'─'.repeat(PANEL_W - 2)}╯`);
   lines.push('');
 
-  // 5) provider / session info
+  // 6) provider / session info (single line each, fit-truncated for safety).
+  const { provider, model, trainer = {}, sessionId, cwd } = props;
   const tProv = trainer.provider || provider;
   const tModel = trainer.model || model;
   lines.push(fit(`${LMARGIN}${provider} · ${model}  ·  trainer ${tProv} · ${tModel}`, cols).trimEnd());
@@ -322,7 +344,7 @@ function renderNarrow(props, cols) {
   lines.push(fit(`${LMARGIN}Welcome to lazyclaw. /help for commands.`, cols).trimEnd());
   lines.push('');
 
-  // 6) compact status — single line, no separator dashes
+  // 7) compact status — single line, no separator dashes.
   const ctx = props.ctxUsed != null && props.ctxTotal != null
     ? `${props.ctxUsed}/${props.ctxTotal}`
     : '--';
@@ -331,7 +353,7 @@ function renderNarrow(props, cols) {
   return lines;
 }
 
-// Minimal tier — bare-bones fallback for cols < 60.
+// Minimal tier — bare-bones fallback for cols < 45.
 function renderMinimal(props) {
   const { version, provider, model, sessionId, cwd } = props;
   const lines = [];
@@ -346,8 +368,8 @@ function renderMinimal(props) {
 export function renderSplashToString(props, opts = {}) {
   const cols = opts.columns || process.stdout.columns || 100;
   let lines;
-  if (cols < MINIMAL_BREAKPOINT) lines = renderMinimal(props);
-  else if (cols < PANEL_BREAKPOINT) lines = renderNarrow(props, cols);
+  if (cols < NARROW_BREAKPOINT) lines = renderMinimal(props);
+  else if (cols < MEDIUM_BREAKPOINT) lines = renderNarrow(props, cols);
   else if (cols < WORDMARK_BREAKPOINT) lines = renderMedium(props, cols);
   else lines = renderWide(props, cols);
   return lines.join('\n');