@axplusb/kepler 1.0.10 → 2.0.2

package/src/terminal/repl.mjs

@@ -16,13 +16,22 @@
  */
 
 import * as readline from 'node:readline';
-import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { c, progressBar, spinner, inPlace, renderMarkdown, renderDiff, formatElapsed, formatCost, stripAnsi } from './ansi.mjs';
 import { calculateCost, formatCostValue, formatTokens, costToCredits, formatCredits } from '../core/pricing.mjs';
 import { TarangStreamClient, EVENT_TYPES } from '../core/stream-client.mjs';
 import { JsonlWriter } from '../core/jsonl-writer.mjs';
 import { createToolExecutor } from '../core/tool-executor.mjs';
+import { CheckpointManager } from '../core/checkpoints.mjs';
+import { runPreflight } from '../onboarding/preflight.mjs';
+import { printBanner as printBrandedBanner } from '../ui/banner.mjs';
+import { renderMissionReport, saveReport, toMarkdown as missionMarkdown } from '../ui/mission-report.mjs';
+import {
+  getVerbosity,
+  setVerbosity,
+  label as verbosityLabel,
+  MODES as V_MODES,
+} from '../state/verbosity.mjs';
 import { persistProjectArtifacts } from '../core/project-artifacts.mjs';
 import { TarangAuth } from '../auth/tarang-auth.mjs';
 import { ApprovalManager } from '../core/approval.mjs';
@@ -30,7 +39,27 @@ import { resolveBackendUrl } from '../core/backend-url.mjs';
 import { BUILTIN_AGENTS, runAgent } from './agents.mjs';
 import { SessionManager } from '../core/session-manager.mjs';
 import { parseArgs } from '../config/cli-args.mjs';
-import { formatShellCommand, toolDisplayLabel, toolDisplaySummary } from './tool-display.mjs';
+import { toolDisplayLabel } from './tool-display.mjs';
+import { createOrbit } from '../state/orbit.mjs';
+import { attachOrbit, unmount as unmountStatusBar } from '../ui/status-bar.mjs';
+import { term } from '../ui/term.mjs';
+import {
+  formatCardHead,
+  summarizeResult,
+  recordCard,
+  lastCard,
+  getCard,
+  allCards,
+} from '../ui/tool-card.mjs';
+import { detailFor } from '../ui/tool-details.mjs';
+import { paint } from '../ui/palette.mjs';
+import {
+  renderSubAgentOpen,
+  renderSubAgentClose,
+  subAgentIndent,
+  inSubAgent as inSubAgentBlock,
+  resetSubAgents,
+} from '../ui/sub-agent.mjs';
 
 import { createRequire } from 'node:module';
 const __require = createRequire(import.meta.url);
@@ -63,6 +92,7 @@ function safeCwd() {
 // ── Session State ──
 
 let _sessionMgr = null; // Set in startTerminalRepl, used by renderEvent
+let _orbit = null;      // Mission Control orbit state machine; set in startTerminalRepl
 
 const session = {
   id: null,                  // set by backend on first turn via session_info event
@@ -82,9 +112,17 @@ const session = {
   inSubAgent: false,   // true while a sub-agent is running (for indented tool display)
   filesChanged: [],    // files modified this session
   lastTurnDuration: 0,
+  toolCounts: {},      // per-tool histogram (mission report)
+  subAgentCounts: {},  // per-sub-agent histogram (mission report)
+  savedUsd: 0,         // total sub-agent cost (for "saved by routing")
+  lastTask: '',        // most recent user prompt (mission report title)
+  lastReasoning: '',   // captured from agent for /why
+  budgetUsd: null,     // /budget cap, null = unlimited
+  budgetExceeded: false,
   costBreakdown: [],   // per-model usage: [{ model, role, input_tokens, output_tokens, cost }]
   totalCost: 0,        // accumulated session cost (USD)
   costAccurate: false, // true if backend provides per-model breakdown
+  isByok: false,       // set from session_info; hides cost + credits when true
 };
 
 // ── Commands ──
@@ -100,6 +138,19 @@ const COMMANDS = {
   '/diff':     'Git diff',
   '/cost':     'Show session cost',
   '/history':  'Show conversation',
+  '/last':     'Expand last tool output',
+  '/expand':   'Expand tool output by index (or "all")',
+  '/fold':     'Hide previously expanded tool output',
+  '/checkpoint':'List recent file checkpoints',
+  '/undo':     'Restore the last file checkpoint',
+  '/preflight':'Re-run the onboarding diagnostic',
+  '/report':   'Save the mission report as markdown',
+  '/why':      'Print the agent reasoning for the last decision',
+  '/map':      'Show the registered project tree',
+  '/budget':   'Set / clear a hard session cost cap',
+  '/quiet':    'Verbosity: hide sub-agent inner tools',
+  '/verbose':  'Verbosity: show sub-agent inner tools',
+  '/surgical': 'Verbosity: show everything (reasoning, expanded tools)',
   '/compact':  'Compact conversation context',
   '/agents':   'List available agents',
   '/explore':  'Code explorer agent',
@@ -116,26 +167,15 @@ const COMMANDS = {
 // ── Banner ──
 
 function printBanner(auth) {
+  // Delegate the visual block to the branded banner module (PRD-055 §4.3,
+  // gradient KEPLER letters in Deep Space Purple → Stellar Magenta → Neon
+  // Cyan). The trailing status line stays here because it needs `auth`.
+  printBrandedBanner();
+
   const creds = auth.loadCredentials();
   const env = process.env.TARANG_ENV || 'production';
   const authStatus = creds.token ? c.green('authenticated') : c.red('/login to start');
-
-  const CYAN = '\x1b[36m';
-  const DIM = '\x1b[2m';
-  const BOLD = '\x1b[1m';
-  const YELLOW = '\x1b[33m';
-  const RST = '\x1b[0m';
-
-  process.stderr.write('\n');
-  process.stderr.write(`${DIM}         ✦${RST}\n`);
-  process.stderr.write(`${DIM}      ╭──────────────────────────╮${RST}\n`);
-  process.stderr.write(`${DIM}      │${RST}  ${BOLD}${CYAN}K · E · P · L · E · R${RST}  ${DIM}│${RST}\n`);
-  process.stderr.write(`${DIM}      ╰──────── ${YELLOW}◯${RST}${DIM} ───────────────╯${RST}\n`);
-  process.stderr.write(`${DIM}            ╱ ╲${RST}\n`);
-  process.stderr.write(`${DIM}       the agentic os${RST}\n`);
-  process.stderr.write('\n');
-  process.stderr.write(`  ${c.gray('v' + VERSION)}  ${c.dim(env)}  ${authStatus}\n`);
-  process.stderr.write('\n');
+  process.stderr.write(`  ${c.gray('v' + VERSION)}  ${c.dim(env)}  ${authStatus}\n\n`);
 }
 
 // ── Prompt Chrome ──
@@ -163,12 +203,12 @@ function printBanner(auth) {
  */
 function buildContextStrip() {
   const totalTokens = session.inputTokens + session.outputTokens;
-  const credits = formatCredits(costToCredits(session.totalCost));
   const elapsed = formatElapsed(session.startTime);
 
+  // BYOK: user pays the provider directly, suppress credits entirely.
   const right = [
     c.dim(`${formatTokens(totalTokens)} tok`),
-    c.dim(credits),
+    ...(session.isByok ? [] : [c.dim(formatCredits(costToCredits(session.totalCost)))]),
     c.dim(elapsed),
   ].join(c.dim(' · '));
 
@@ -195,11 +235,27 @@ function printPromptBlock() {
  * Print a turn summary after a response completes.
  * Shows only when there's something meaningful to report.
  */
+/**
+ * Pull blocker bullet points from the completion payload — used by the
+ * failure variant of the mission report.
+ */
+function extractBlockers(data) {
+  const out = [];
+  if (data?.error) out.push(String(data.error).slice(0, 160));
+  if (Array.isArray(data?.failed_tests)) {
+    for (const t of data.failed_tests.slice(0, 6)) {
+      if (typeof t === 'string') out.push(t);
+      else if (t?.name) out.push(`${t.name}${t.message ? ': ' + t.message : ''}`);
+    }
+  }
+  return out;
+}
+
 function printTurnSummary(toolCount, durationS, turnCost) {
   const parts = [];
   if (toolCount > 0) parts.push(`${toolCount} tools`);
   if (durationS) parts.push(`${Number(durationS).toFixed(1)}s`);
-  if (turnCost > 0) parts.push(formatCredits(costToCredits(turnCost)));
+  if (turnCost > 0 && !session.isByok) parts.push(formatCredits(costToCredits(turnCost)));
   if (parts.length > 0) {
     process.stderr.write(`\n  ${c.green('✓')} ${c.dim(parts.join(' · '))}\n`);
   }
@@ -212,31 +268,34 @@ function updateStatusBar() {
 // ── Tool Display Renderer ──
 
 /**
- * Render a tool call in a transparent, informational way.
- * Shows tool name + key args on one line, no box borders for reads.
+ * Render a tool call as the head of a Mission Control card — icon + label +
+ * args. The result arrives later via `renderToolResult` and is appended as a
+ * gutter line. Sub-agent calls are indented per session.inSubAgent.
  */
+// Set by renderToolCall, consumed by renderToolResult so we can collapse the
+// "head\n  ⎿ → outcome\n" two-line shape into a single line whenever nothing
+// else printed in between. Cleared by any handler that writes interleaving
+// content (content/thinking/sub_agent_*/delegation/etc).
+let _pendingHead = null; // { callId, head }
+
+function clearPendingHead() { _pendingHead = null; }
+
 function renderToolCall(data) {
   const tool = data?.tool || 'unknown';
-  const label = toolDisplayLabel(tool);
   const args = data?.args || {};
-  const indent = session.inSubAgent ? '     ' : '  ';
+  const indent = subAgentIndent();
+  const callId = data?.call_id || data?._callId || `${tool}:${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 
-  const summary = toolDisplaySummary(tool, args, { cwd: safeCwd() });
+  const head = formatCardHead(tool, args, {
+    cwd: safeCwd(),
+    columns: process.stderr.columns || 120,
+    indent,
+  });
 
-  // Render: ⏺ Human-readable action(summary)
-  // Use terminal width minus label and padding, minimum 60
-  const cols = process.stderr.columns || 120;
-  const maxSummary = Math.max(60, cols - label.length - 10);
-  let displaySummary = summary || '';
-  if (displaySummary.length > maxSummary) {
-    displaySummary = '...' + displaySummary.slice(-(maxSummary - 3));
-  }
-  const summaryStr = displaySummary
-    ? c.gray('(') + (tool === 'shell'
-      ? formatShellCommand(displaySummary, c)
-      : c.white(displaySummary)) + c.gray(')')
-    : '';
-  process.stderr.write(`\n${indent}${c.brand('⏺')} ${c.bold(label)}${summaryStr}\n`);
+  recordCard({ id: callId, tool, args, head, startedAt: Date.now() });
+  session.toolCounts[tool] = (session.toolCounts[tool] || 0) + 1;
+  process.stderr.write(`\n${head}\n`);
+  _pendingHead = { callId, head };
 }
 
 /**
@@ -250,77 +309,93 @@ function formatToolDuration(data) {
   return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
 }
 
-function firstOutputLine(data) {
-  const output = data?.output_preview || data?.output || data?.message || '';
-  return String(output).split('\n').map(line => line.trim()).find(Boolean) || '';
-}
-
-function fileTypeLabel(filePath) {
-  const ext = path.extname(filePath || '').toLowerCase();
-  if (ext === '.md' || ext === '.mdx') return 'Markdown';
-  if (ext === '.json' || ext === '.jsonl') return 'JSON';
-  if (ext === '.yaml' || ext === '.yml') return 'YAML';
-  if (ext === '.toml') return 'TOML';
-  if (ext === '.csv' || ext === '.tsv') return 'tabular data';
-  if (['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.rb', '.php', '.swift'].includes(ext)) {
-    return 'source';
-  }
-  return ext ? `${ext.slice(1).toUpperCase()} file` : 'file';
-}
-
 function renderToolResult(data, eventType = 'tool_result') {
   if (!data) return;
-  const indent = session.inSubAgent ? '     ' : '  ';
-  const gutter = `${indent}${c.dim('⎿')}  `;
+  const indent = subAgentIndent();
+  const gutter = `${indent}${paint.text.dim('⎿')}  `;
   const callId = data.call_id || data._callId;
   if (eventType === 'tool_done' && callId && _renderedToolResults.has(callId)) return;
   if (callId) _renderedToolResults.add(callId);
-  const duration = formatToolDuration(data);
-  const suffix = duration ? c.dim(` · ${duration}`) : '';
 
-  if (data._blocked) {
-    session.blockedOps++;
-    process.stderr.write(`${gutter}${c.red(firstOutputLine(data) || 'Blocked by safety guardrails')}${suffix}\n`);
-    return;
-  }
+  const tool = data.tool || data._tool || '';
+  const durationMs = data?.duration_ms ?? (data?.duration_s != null ? data.duration_s * 1000 : null);
 
-  if (data.success === false) {
-    const msg = (data.error || firstOutputLine(data) || 'Failed').slice(0, 140);
-    process.stderr.write(`${gutter}${c.red(msg)}${suffix}\n`);
-    return;
+  // Update the card buffer so /last and `d` can find it.
+  if (callId) recordCard({ id: callId, tool, args: data.args, result: data, durationMs });
+
+  if (data._blocked) session.blockedOps++;
+
+  const { text, tone: t } = summarizeResult(tool, data);
+  const arrow = paint.text.dim('→');
+  const painter = t === 'success' ? paint.state.success
+                : t === 'warn'    ? paint.state.warn
+                : t === 'danger'  ? paint.state.danger
+                                  : paint.text.dim;
+  const duration = formatToolDuration(data);
+  const tail = duration ? paint.text.dim(` · ${duration}`) : '';
+  const outcome = `${arrow} ${painter(text || 'done')}${tail}`;
+
+  // ── Single-line collapse ──
+  // If nothing has interleaved between renderToolCall and this result, rewrite
+  // the head line in-place as "<head>  → outcome · duration" — saves a full
+  // row per tool call. Falls back to the two-line gutter form when the head
+  // is gone (something scrolled it away) or the combined line would not fit.
+  const hasLint = (tool === 'write_file' || tool === 'edit_file') && data.lint;
+  if (_pendingHead && _pendingHead.callId === callId && !hasLint) {
+    const cols = process.stderr.columns || 120;
+    const combined = `${_pendingHead.head}  ${outcome}`;
+    if (stripAnsi(combined).length <= cols) {
+      // Move up one line, clear it, rewrite as one line. No leading newline
+      // because the cursor is already at the start of the (now-cleared) line.
+      process.stderr.write(`\x1b[1A\x1b[2K\r${combined}\n`);
+      _pendingHead = null;
+      return;
+    }
   }
+  _pendingHead = null;
 
-  const tool = data.tool || data._tool || '';
-  let summary = 'Completed';
-  if (tool === 'read_file') {
-    const lines = data._total_lines || String(data.output || '').split('\n').length;
-    const filePath = data.args?.file_path || data.args?.path || '';
-    summary = `Read ${fileTypeLabel(filePath)} · ${lines} line${lines === 1 ? '' : 's'}`;
-  } else if (tool === 'read_files') {
-    summary = 'Files read';
-  } else if (tool === 'search_code' || tool === 'list_files') {
-    const lines = String(data.output || '').split('\n').filter(line => line.trim()).length;
-    summary = lines > 0 ? `${lines} result${lines === 1 ? '' : 's'}` : 'No results';
-  } else if (tool === 'write_file' || tool === 'edit_file' || tool === 'write_project') {
-    summary = 'Updated';
-  } else if (tool === 'delete_file') {
-    summary = 'Deleted';
-  } else if (data.server_side) {
-    summary = firstOutputLine(data).slice(0, 100) || 'Completed server-side';
-  } else if (tool === 'shell') {
-    summary = firstOutputLine(data).slice(0, 100) || 'Command completed';
+  // Default two-line shape.
+  process.stderr.write(`${gutter}${outcome}\n`);
+
+  // Lint warnings stay visible alongside writes.
+  if (hasLint) {
+    process.stderr.write(`${gutter}${paint.state.warn('⚠ ' + String(data.lint).split('\n')[0].slice(0, 80))}\n`);
   }
+}
 
-  const renderedSummary = tool === 'shell' ? c.green(summary) : c.white(summary);
-  process.stderr.write(`${gutter}${renderedSummary}${suffix}\n`);
+// ── Expand handler — `d`, `/last`, `/expand` ───────────────────────────
+//
+// All three call into the same renderer so output is consistent across
+// keypress and slash-command paths. `expandLast` and `expandIndex` write
+// directly to stderr.
+
+function expandLast() {
+  const card = lastCard();
+  if (!card) {
+    process.stderr.write(`  ${paint.text.dim('(no tool to expand yet)')}\n`);
+    return;
+  }
+  process.stderr.write('\n' + detailFor(card) + '\n\n');
+}
 
-  // For writes, show lint warnings
-  if (tool === 'write_file' || tool === 'edit_file') {
-    const lint = data.lint;
-    if (lint) {
-      process.stderr.write(`${gutter}${c.yellow('⚠ ' + lint.split('\n')[0].slice(0, 80))}\n`);
+function expandIndex(idxOrAll) {
+  if (idxOrAll === 'all') {
+    const cards = allCards();
+    if (!cards.length) {
+      process.stderr.write(`  ${paint.text.dim('(no tools to expand yet)')}\n`);
+      return;
     }
+    process.stderr.write('\n');
+    for (const c of cards) process.stderr.write(detailFor(c) + '\n');
+    process.stderr.write('\n');
+    return;
+  }
+  const card = getCard(idxOrAll);
+  if (!card) {
+    process.stderr.write(`  ${paint.text.dim('(no card at index ' + idxOrAll + ')')}\n`);
+    return;
   }
+  process.stderr.write('\n' + detailFor(card) + '\n\n');
 }
 
 /**
@@ -383,6 +458,9 @@ function startContentStream() {
 
 function appendContent(text) {
   if (!text) return;
+  // Any streamed content between renderToolCall and renderToolResult would
+  // scroll the head off "the line above", breaking the in-place collapse.
+  clearPendingHead();
   _streamBuffer += text;
   _streamedPartialText += text;
 
@@ -409,6 +487,11 @@ function flushContent() {
 function renderEvent(event) {
   const { type, data } = event;
 
+  // Push every event into the orbit state machine before rendering so the
+  // bottom status bar reflects what is happening this very moment. The orbit
+  // module is a no-op when status-bar is not mounted (non-TTY, --headless).
+  if (_orbit) _orbit.onEvent(event);
+
   switch (type) {
     case 'status': {
       const msg = data?.message || '';
@@ -421,6 +504,8 @@ function renderEvent(event) {
       const text = data?.message || data?.text || '';
       if (text && !text.startsWith('Processing')) {
         startSpinner(text.slice(0, 80));
+        // Capture reasoning so /why can replay it.
+        session.lastReasoning = text;
       }
       break;
     }
@@ -482,7 +567,7 @@ function renderEvent(event) {
     case 'approval_denied': {
       const reason = data?.reason || 'User denied';
       const toolName = data?.tool || '';
-      const indent = session.inSubAgent ? '     ' : '  ';
+      const indent = subAgentIndent();
       process.stderr.write(`${indent}${c.red('✗')} ${c.dim(`Denied ${toolName}: ${reason}`)}\n`);
       break;
     }
@@ -561,6 +646,7 @@ function renderEvent(event) {
 
     case 'delegation': {
       stopSpinner();
+      clearPendingHead();
       const from = data?.from || '';
       const to = data?.to || '';
       session.delegations.push({ from, to, time: Date.now() });
@@ -576,21 +662,20 @@ function renderEvent(event) {
 
     case 'sub_agent_start': {
       stopSpinner();
-      session.inSubAgent = true;
+      clearPendingHead();
       const agentType = data?.type || 'sub-agent';
       const model = data?.model || '';
       const query = data?.query || '';
-      const icon = agentType === 'explore' ? '🔭' : agentType === 'plan' ? '📐' : '🤖';
-      process.stderr.write(`\n  ${icon} ${c.bold(c.brand(`${agentType} agent`))} ${c.dim('started')}\n`);
-      if (model) process.stderr.write(`     ${c.gray('model:')} ${c.dim(model)}\n`);
-      if (query) process.stderr.write(`     ${c.gray('query:')} ${c.dim(query)}\n`);
+      process.stderr.write(renderSubAgentOpen({ type: agentType, model, query }) + '\n');
+      session.inSubAgent = inSubAgentBlock(); // kept for legacy readers
+      session.subAgentCounts[agentType] = (session.subAgentCounts[agentType] || 0) + 1;
       startSpinner(`${agentType}: working...`);
       break;
     }
 
     case 'sub_agent_tool': {
-      // No separate display — the regular tool_call event shows full detail
-      // indented under the sub-agent block. Just update the spinner text.
+      // The regular tool_call event renders the card, indented by the
+      // sub-agent stack depth. Just update the spinner text here.
       const agentType = data?.type || 'sub-agent';
       const tool = data?.tool || '';
       if (tool) updateSpinner(`${agentType} → ${tool}`);
@@ -599,24 +684,26 @@ function renderEvent(event) {
 
     case 'sub_agent_complete': {
       stopSpinner();
-      session.inSubAgent = false;
+      clearPendingHead();
       const agentType = data?.type || 'sub-agent';
-      const model = data?.model || '';
-      const resultLen = data?.result_length || 0;
       const usage = data?.usage || {};
       const tokens = (usage.input_tokens || 0) + (usage.output_tokens || 0);
-      const parts = [];
-      if (data?.tool_calls > 0) parts.push(`${data.tool_calls} tools`);
-      if (data?.iterations > 0) parts.push(`${data.iterations} iterations`);
-      if (resultLen > 0) parts.push(`${resultLen} chars`);
-      if (tokens > 0) parts.push(`${formatTokens(tokens)} tok`);
-      if (data?.duration_s != null) parts.push(`${Number(data.duration_s).toFixed(1)}s`);
-      const icon = agentType === 'explore' ? '🔭' : agentType === 'plan' ? '📐' : '🤖';
-      const marker = data?.success === false ? c.red('✗') : c.green('✓');
-      const label = data?.success === false ? `${agentType} agent failed` : `${agentType} agent complete`;
-      process.stderr.write(`  ${icon} ${marker} ${c.dim(label)}${parts.length ? '  ' + c.dim(parts.join(' · ')) : ''}\n`);
-      if (data?.error) process.stderr.write(`     ${c.red(String(data.error).slice(0, 140))}\n`);
-      process.stderr.write('\n');
+      const costUsd = usage.cost_usd ?? usage.total_cost_usd ?? data?.cost_usd ?? null;
+      if (typeof costUsd === 'number') session.savedUsd += costUsd;
+      const summary = data?.result_summary
+        || (data?.result_length > 0 ? `${agentType} returned ${data.result_length} chars` : '');
+      process.stderr.write(renderSubAgentClose({
+        type: agentType,
+        success: data?.success !== false,
+        summary,
+        costUsd,
+        tokens,
+        durationS: data?.duration_s,
+        toolCalls: data?.tool_calls,
+        iterations: data?.iterations,
+        error: data?.error,
+      }) + '\n\n');
+      session.inSubAgent = inSubAgentBlock();
       break;
     }
 
@@ -638,6 +725,9 @@ function renderEvent(event) {
       }
       if (data?.model) session.model = data.model;
       if (data?.user) session.user = { ...session.user, ...data.user };
+      // BYOK users pay their model provider directly; the platform does not
+      // charge them credits. Hide cost + credits when this flag is set.
+      if (typeof data?.is_byok === 'boolean') session.isByok = data.is_byok;
       break;
     }
 
@@ -653,6 +743,8 @@ function renderEvent(event) {
     case 'complete': {
       stopSpinner();
       flushContent();
+      resetSubAgents();
+      session.inSubAgent = false;
 
       const summary = data?.summary || '';
       if (summary && !_renderedContentThisTurn) {
@@ -695,9 +787,39 @@ function renderEvent(event) {
 
       session.lastTurnDuration = data?.duration_s || 0;
 
+      // Sync cumulative session cost into the orbit (status bar shows it).
+      if (_orbit) _orbit.onCost(session.totalCost);
+
       // Compact turn summary
       const tools = data?.tool_calls || session.toolCalls || 0;
-      printTurnSummary(tools, data?.duration_s, turnCost);
+
+      // Mission report — replaces the trailing "Done" when the turn did real
+      // work (touched files or invoked tools). Plain chat turns keep the
+      // tight printTurnSummary so the report does not feel ceremonial.
+      const didRealWork = tools > 0 || session.filesChanged.length > 0;
+      if (didRealWork) {
+        const successOverall = data?.success !== false;
+        const report = renderMissionReport({
+          task: session.lastTask,
+          success: successOverall,
+          filesChanged: session.filesChanged,
+          toolCounts: session.toolCounts,
+          subAgents: { ...session.subAgentCounts, savedUsd: session.isByok ? 0 : session.savedUsd },
+          // BYOK users pay their provider directly; suppress cost in the report.
+          costUsd: session.isByok ? null : (turnCost || session.totalCost),
+          durationS: data?.duration_s,
+          testsPass: data?.tests_passed != null
+            ? { passed: data.tests_passed, total: data.tests_total || data.tests_passed }
+            : null,
+          blockers: !successOverall ? (data?.blockers || extractBlockers(data)) : null,
+          nextActions: successOverall
+            ? ['/commit', '/pr', '/undo', '/report']
+            : ['/why', '/undo', '/re-plan'],
+        });
+        process.stderr.write(report + '\n');
+      } else {
+        printTurnSummary(tools, data?.duration_s, turnCost);
+      }
       break;
     }
 
@@ -736,7 +858,8 @@ async function handleCommand(input, ctx) {
         process.stderr.write(`  ${c.brand(name.padEnd(14))} ${desc}\n`);
       }
       process.stderr.write(`\n  ${c.bold('Keyboard')}\n`);
-      process.stderr.write(`  ${c.gray('Ctrl+C')}  exit   ${c.gray('↑↓')}  history   ${c.gray('Tab')}  autocomplete\n\n`);
+      process.stderr.write(`  ${c.gray('Ctrl+C')}  exit   ${c.gray('↑↓')}  history   ${c.gray('Tab')}  autocomplete\n`);
+      process.stderr.write(`  ${c.gray('d')}       expand last tool   ${c.gray('Space')}  pause/resume   ${c.gray('Esc')}  interrupt\n\n`);
       return;
 
     case '/login':
@@ -782,7 +905,11 @@ async function handleCommand(input, ctx) {
       process.stderr.write(`  ${c.dim('Turns')}        ${session.turns}\n`);
       process.stderr.write(`  ${c.dim('Tools')}        ${session.totalToolCalls} total, ${session.toolCalls} last turn\n`);
       process.stderr.write(`  ${c.dim('Duration')}     ${formatElapsed(session.startTime)}\n`);
-      process.stderr.write(`  ${c.dim('Credits')}      ${formatCredits(costToCredits(session.totalCost))}${session.costAccurate ? '' : c.dim(' (est)')}\n`);
+      if (session.isByok) {
+        process.stderr.write(`  ${c.dim('Billing')}      ${c.green('BYOK')} ${c.dim('(provider-billed)')}\n`);
+      } else {
+        process.stderr.write(`  ${c.dim('Credits')}      ${formatCredits(costToCredits(session.totalCost))}${session.costAccurate ? '' : c.dim(' (est)')}\n`);
+      }
       process.stderr.write(`  ${c.dim('CWD')}          ${safeCwd()}\n`);
 
       // Permissions
@@ -850,12 +977,20 @@ async function handleCommand(input, ctx) {
       process.stderr.write(`  ${c.gray('Turns:')}     ${session.turns}\n`);
       process.stderr.write(`  ${c.gray('Tools:')}     ${session.toolCalls}\n`);
       process.stderr.write(`  ${c.gray('Blocked:')}   ${session.blockedOps}\n`);
-      process.stderr.write(`  ${c.gray('Credits:')}   ${formatCredits(costToCredits(session.totalCost))}${session.costAccurate ? '' : c.dim(' (est)')}\n`);
+      if (session.isByok) {
+        process.stderr.write(`  ${c.gray('Billing:')}   ${c.green('BYOK')} ${c.dim('(provider-billed)')}\n`);
+      } else {
+        process.stderr.write(`  ${c.gray('Credits:')}   ${formatCredits(costToCredits(session.totalCost))}${session.costAccurate ? '' : c.dim(' (est)')}\n`);
+      }
       process.stderr.write(`  ${c.gray('Elapsed:')}  ${formatElapsed(session.startTime)}\n\n`);
       return;
     }
 
     case '/cost': {
+      if (session.isByok) {
+        process.stderr.write(`\n  ${c.bold('Billing')}  ${c.green('BYOK')} ${c.dim('— you pay your model provider directly. Kepler does not charge credits for BYOK usage.')}\n\n`);
+        return;
+      }
       process.stderr.write(`\n  ${c.bold('Session Credits')}  ${c.brand(formatCredits(costToCredits(session.totalCost)))}`);
       if (!session.costAccurate) {
         process.stderr.write(`  ${c.yellow('(estimated)')}`);
@@ -908,6 +1043,143 @@ async function handleCommand(input, ctx) {
       process.stderr.write('\n');
       return;
 
+    case '/last':
+      expandLast();
+      return;
+
+    case '/expand': {
+      const arg = rest.trim();
+      if (!arg) { expandLast(); return; }
+      if (arg === 'all') { expandIndex('all'); return; }
+      const n = Number(arg);
+      if (!Number.isFinite(n)) {
+        process.stderr.write(`  ${c.gray('Usage: /expand [n|all] — n is the 1-based index from the start of the session')}\n`);
+        return;
+      }
+      // Users pass 1-based; getCard accepts negative (-1 = last) or positive index.
+      expandIndex(n > 0 ? n - 1 : n);
+      return;
+    }
+
+    case '/fold':
+      process.stderr.write(`  ${c.gray('Output is folded by default — there is nothing to hide. Use /last or d to expand.')}\n`);
+      return;
+
+    case '/undo': {
+      const result = ctx.checkpoints?.undo();
+      if (!result) {
+        process.stderr.write(`  ${c.gray('No checkpoints to undo.')}\n`);
+        return;
+      }
+      if (result.restored) {
+        process.stderr.write(`  ${c.green('↩')} ${c.dim('Restored')} ${result.filePath}\n`);
+      } else {
+        process.stderr.write(`  ${c.red('✗')} ${c.dim('Undo failed: ' + (result.error || 'unknown error'))}\n`);
+      }
+      return;
+    }
+
+    case '/checkpoint': {
+      const list = ctx.checkpoints?.list(10) || [];
+      if (!list.length) {
+        process.stderr.write(`  ${c.gray('No checkpoints recorded yet — they are taken automatically before each edit.')}\n`);
+        return;
+      }
+      process.stderr.write(`\n  ${c.bold('Recent checkpoints')}\n  ${c.gray('─'.repeat(40))}\n`);
+      for (const ckpt of list) {
+        const when = String(ckpt.timestamp).slice(11, 19);
+        process.stderr.write(`  ${c.gray(when)}  ${c.white(ckpt.file)}  ${c.gray(formatTokens(ckpt.size) + ' bytes')}\n`);
+      }
+      process.stderr.write(`\n  ${c.gray('/undo restores the most recent one')}\n\n`);
+      return;
+    }
+
+    case '/preflight': {
+      await runPreflight({ auth: ctx.auth, cwd: safeCwd(), version: VERSION });
+      return;
+    }
+
+    case '/report': {
+      if (Object.keys(session.toolCounts).length === 0 && session.filesChanged.length === 0) {
+        process.stderr.write(`  ${c.gray('Nothing to report yet — run a task first.')}\n`);
+        return;
+      }
+      const state = {
+        task: session.lastTask,
+        success: true,
+        filesChanged: session.filesChanged,
+        toolCounts: session.toolCounts,
+        subAgents: { ...session.subAgentCounts, savedUsd: session.isByok ? 0 : session.savedUsd },
+        costUsd: session.isByok ? null : session.totalCost,
+        durationS: (Date.now() - session.startTime) / 1000,
+        nextActions: ['/commit', '/pr', '/undo'],
+      };
+      const out = saveReport(state, { cwd: safeCwd() });
+      process.stderr.write(`  ${c.green('✓')} ${c.dim('Saved')} ${out}\n`);
+      return;
+    }
+
+    case '/why': {
+      if (!session.lastReasoning) {
+        process.stderr.write(`  ${c.gray('No reasoning captured yet for this session.')}\n`);
+        return;
+      }
+      process.stderr.write(`\n  ${c.bold('Last reasoning')}\n  ${c.gray('─'.repeat(40))}\n`);
+      for (const line of String(session.lastReasoning).split('\n')) {
+        process.stderr.write(`  ${c.dim(line)}\n`);
+      }
+      process.stderr.write('\n');
+      return;
+    }
+
+    case '/map': {
+      try {
+        const resources = ctx.toolExecutor?.getProjectResources?.() || [];
+        if (!resources.length) {
+          process.stderr.write(`  ${c.gray('No project resources registered yet. Use get_project_overview to register one.')}\n`);
+          return;
+        }
+        process.stderr.write(`\n  ${c.bold('Registered projects')}\n  ${c.gray('─'.repeat(40))}\n`);
+        for (const r of resources) {
+          process.stderr.write(`  ${c.brand('•')} ${c.white(r.id || r.name || '?')}  ${c.dim(r.root || r.path || '')}\n`);
+        }
+        process.stderr.write('\n');
+      } catch (err) {
+        process.stderr.write(`  ${c.red('/map failed: ' + err.message)}\n`);
+      }
+      return;
+    }
+
+    case '/budget': {
+      const arg = rest.trim();
+      if (!arg || arg === 'clear' || arg === 'off') {
+        session.budgetUsd = null;
+        session.budgetExceeded = false;
+        process.stderr.write(`  ${c.gray('Budget cap cleared.')}\n`);
+        return;
+      }
+      const n = Number(arg.replace(/^\$/, ''));
+      if (!Number.isFinite(n) || n <= 0) {
+        process.stderr.write(`  ${c.gray('Usage: /budget <amount in USD>  or  /budget clear')}\n`);
+        return;
+      }
+      session.budgetUsd = n;
+      session.budgetExceeded = false;
+      process.stderr.write(`  ${c.green('✓')} ${c.dim('Budget set: ')} $${n.toFixed(2)}\n`);
+      return;
+    }
+
+    case '/quiet':
+    case '/verbose':
+    case '/surgical': {
+      const mode = cmd === '/quiet' ? V_MODES.QUIET
+                : cmd === '/verbose' ? V_MODES.VERBOSE
+                : V_MODES.SURGICAL;
+      setVerbosity(mode);
+      process.stderr.write(`  ${c.green('✓')} ${c.dim('Verbosity: ')} ${c.brand(verbosityLabel(mode))}\n`);
+      return;
+    }
+
     case '/compact': {
       const before = session.history.length;
       if (before <= 4) { process.stderr.write(`  ${c.gray('Nothing to compact.')}\n`); return; }
@@ -1132,7 +1404,9 @@ export async function startTerminalRepl() {
   const auth = new TarangAuth();
 
   // Projects are registered and indexed on demand through get_project_overview.
-  const toolExecutor = createToolExecutor();
+  // CheckpointManager records per-file snapshots before edits so /undo works.
+  const checkpoints = new CheckpointManager(safeCwd());
+  const toolExecutor = createToolExecutor({ checkpoints });
   const skipPerms = cliArgs.freeswim;
   const approval = new ApprovalManager({ autoApprove: skipPerms });
 
@@ -1146,10 +1420,20 @@ export async function startTerminalRepl() {
   // Persistent stream client — session_id captured from backend on first turn
   let streamClient = null;
 
-  const ctx = { auth, toolExecutor, approval, jsonlWriter, sessionMgr };
+  const ctx = { auth, toolExecutor, approval, jsonlWriter, sessionMgr, checkpoints };
 
+  // ── Print banner + preflight + init BEFORE mounting the status bar ──
+  // The status bar shrinks the scroll region; if it mounts first, the
+  // banner scrolls off-screen before the user ever sees it.
   printBanner(auth);
 
+  // Preflight diagnostic (PRD-055 §9). Non-blocking; opt-out via
+  // KEPLER_NO_PREFLIGHT=1 (used by tests / scripted runs).
+  if (process.env.KEPLER_NO_PREFLIGHT !== '1' && !cliArgs.freeswim) {
+    try { await runPreflight({ auth, cwd: safeCwd(), version: VERSION }); }
+    catch { /* preflight is best-effort */ }
+  }
+
   // ── Initialization ──
   process.stderr.write(`  ${c.brand('⠋')} ${c.dim('Initializing...')}\r`);
   await fetchUser(ctx);
@@ -1187,12 +1471,41 @@ export async function startTerminalRepl() {
 
   process.stderr.write(`\n  ${c.dim('Press')} ${c.brand('Enter')} ${c.dim('to start, or type a prompt below.')}\n`);
 
-  const PROMPT = `${c.brand('kepler')} ${c.dim('›')} `;
+  // Mission Control status bar is OPT-IN as of v2.0.1.
+  // Set KEPLER_STATUS_BAR=1 (or KEPLER_MISSION=1) to enable the persistent
+  // bottom-anchored ORBIT bar. Default off because the DECSTBM scroll
+  // region was eating the prompt visibility on some terminals (issue
+  // observed during v2.0.0 testing). The orbit state machine and tool
+  // cards still work without the bar — the bar is just the rendering.
+  const statusBarEnabled = (
+    process.env.KEPLER_STATUS_BAR === '1' || process.env.KEPLER_MISSION === '1'
+  ) && term().isTTY && !term().plain;
+  if (statusBarEnabled) {
+    _orbit = createOrbit();
+    attachOrbit(_orbit);
+    process.on('beforeExit', unmountStatusBar);
+    process.on('exit',       unmountStatusBar);
+  }
+
+  // The prompt label is the USER speaking, not the agent. Use the signed-in
+  // GitHub handle if known, otherwise fall back to "You".
+  //
+  // readline counts every byte of the prompt as a visible column when it
+  // computes cursor position for line-wrapping; ANSI color codes throw the
+  // math off and produce duplicated text on wrap. Wrap each escape sequence
+  // in SOH (\x01) ... STX (\x02) so readline skips it when measuring width.
+  function rlSafe(s) {
+    return String(s || '').replace(/\x1b\[[0-9;]*m/g, '\x01$&\x02');
+  }
+  function userPrompt() {
+    const who = session.user?.github_username || session.user?.email?.split('@')[0] || 'You';
+    return rlSafe(`${c.brand(who)} ${c.dim('›')} `);
+  }
 
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stderr,
-    prompt: PROMPT,
+    prompt: userPrompt(),
     completer: (line) => {
       if (line.startsWith('/')) {
         const hits = Object.keys(COMMANDS).filter(cmd => cmd.startsWith(line));
@@ -1211,6 +1524,7 @@ export async function startTerminalRepl() {
   function showPrompt() {
     printPromptBlock();
     process.stderr.write('\n');  // half-inch vertical gap above input line
+    rl.setPrompt(userPrompt());  // refresh label in case session.user resolved
     rl.prompt();
   }
 
@@ -1230,10 +1544,27 @@ export async function startTerminalRepl() {
       return;
     }
 
+    // Budget cap (PRD-055 §10). Stop before the next paid call when exceeded.
+    if (session.budgetUsd && session.totalCost >= session.budgetUsd) {
+      session.budgetExceeded = true;
+      process.stderr.write(`  ${c.yellow('⏹')} ${c.dim(`Budget reached ($${session.totalCost.toFixed(2)} of $${session.budgetUsd.toFixed(2)}). Use /budget clear to continue.`)}\n`);
+      showPrompt();
+      return;
+    }
+
     // Regular prompt
     session.history.push({ role: 'user', content: input });
     session.turns++;
     session.toolCalls = 0;
+    session.lastTask = input;
+    // Reset per-turn counts so the mission report reflects this turn only.
+    session.toolCounts = {};
+    session.subAgentCounts = {};
+    session.savedUsd = 0;
+
+    // Tell the orbit a new turn started — switches to DISCOVERY and updates
+    // task / turn counters in the status bar.
+    if (_orbit) _orbit.onUserInput(input);
 
     // Start session tracking on first turn
     if (session.turns === 1) {
@@ -1272,6 +1603,7 @@ export async function startTerminalRepl() {
     let executionPaused = false;
     let keypressCleanup = null;
     let execListenerActive = false;
+    let lastCtrlCAt = 0; // PRD-055 §8.4: first Ctrl+C cancels, second exits
 
     if (process.stdin.isTTY) {
       rl.pause();
@@ -1287,7 +1619,10 @@ export async function startTerminalRepl() {
         // Esc key (single byte 0x1b, not part of arrow sequence)
         if (bytes.length === 1 && bytes[0] === 0x1b) {
           stopSpinner();
-          process.stderr.write(`\n  ${c.yellow('⏹')} ${c.dim('Cancelling...')}\n`);
+          process.stderr.write(`\n  ${c.yellow('⏹')} ${c.dim('Cancelled.')}\n`);
+          // cancel() now aborts the in-flight SSE reader; the for-await loop
+          // wakes up immediately and the prompt returns. No more "stuck"
+          // Cancelling… message.
           client.cancel();
           return;
         }
@@ -1298,20 +1633,39 @@ export async function startTerminalRepl() {
             executionPaused = false;
             process.stderr.write(`  ${c.green('▶')} ${c.dim('Resumed')}\n`);
             client.resume();
+            if (_orbit) _orbit.onResume();
           } else {
             executionPaused = true;
             stopSpinner();
             process.stderr.write(`  ${c.yellow('⏸')} ${c.dim('Paused — press Space to resume, Esc to cancel')}\n`);
             client.pause();
+            if (_orbit) _orbit.onPause();
           }
           return;
         }
 
-        // Ctrl+C during execution
+        // Ctrl+C during execution — PRD-055 §8.4 two-step semantics:
+        //   first press → cancel current backend run, stay in REPL
+        //   second press within 2s → exit the CLI
         if (bytes[0] === 0x03) {
           stopSpinner();
-          client.cancel();
-          process.exit(0);
+          const now = Date.now();
+          if (lastCtrlCAt && (now - lastCtrlCAt) < 2000) {
+            process.stderr.write(`\n  ${c.dim('exiting…')}\n`);
+            try { client.cancel(); } catch {}
+            process.exit(0);
+          }
+          lastCtrlCAt = now;
+          process.stderr.write(`\n  ${c.yellow('⏹')} ${c.dim('Cancelled. Press Ctrl+C again within 2s to exit.')}\n`);
+          try { client.cancel(); } catch {}
+          return;
+        }
+
+        // `d` — expand last tool card (Mission Control §6.2)
+        if (bytes.length === 1 && (bytes[0] === 0x64 || bytes[0] === 0x44)) {
+          stopSpinner();
+          expandLast();
+          return;
         }
       };