@bahulam/code 2.6.1 → 2.6.3

package/src/onboarding/preflight.mjs

@@ -42,6 +42,20 @@ export async function checkAuthAndBackend(auth, { timeoutMs } = {}) {
   const creds = auth.loadCredentials();
   const hasToken = !!creds.token;
   const url = creds.backendUrl;
+
+  // Bundled runtime mode: the local Python runtime replaces the cloud
+  // backend for agent execution. Probing a remote /api/user/me here would
+  // falsely paint the CLI as "Offline" even though the local runtime
+  // is fully operational. Report bundled state directly.
+  const bundledMode =
+    process.env.BAHULAM_RUNTIME_MODE === 'bundled' ||
+    process.env.TARANG_ENV === 'bundled';
+  if (bundledMode) {
+    return hasToken
+      ? { status: 'ok', label: 'Bundled runtime · authenticated' }
+      : { status: 'warn', label: 'Bundled runtime', hint: '/login to enable metered calls' };
+  }
+
   // Local Docker backends round-trip Supabase and often take 2–4s. Give them
   // more headroom so preflight doesn't falsely report Offline.
   const isLocal = /^https?:\/\/(127\.0\.0\.1|localhost)(:|$|\/)/i.test(url || '');

package/src/terminal/main.mjs

@@ -180,29 +180,29 @@ async function main() {
   \x1b[1m\x1b[36mBahulam Code\x1b[0m — Bahulam's coding agent — bahulam.ai
 
   \x1b[1mUsage:\x1b[0m
-    bahulam-code                        Start interactive REPL
-    bahulam-code "instruction"          Run a single instruction
-    bahulam-code --headless -p "x"      Non-interactive: auto-approve, JSONL output
-    bahulam-code --headless -p "x" --vision screenshot.png
+    bahulam                        Start interactive REPL
+    bahulam "instruction"          Run a single instruction
+    bahulam --headless -p "x"      Non-interactive: auto-approve, JSONL output
+    bahulam --headless -p "x" --vision screenshot.png
                               Attach an image via the vision analysis pipeline
-    bahulam-code --resume               Resume last conversation
-    bahulam-code dashboard              Open analytics dashboard
-    bahulam-code login                  Sign in via browser
-    bahulam-code logout                 Sign out and clear credentials
-    bahulam-code init                   Scaffold .bahulam config, memory, hooks, tasks
-    bahulam-code version                Show version
+    bahulam --resume               Resume last conversation
+    bahulam dashboard              Open analytics dashboard
+    bahulam login                  Sign in via browser
+    bahulam logout                 Sign out and clear credentials
+    bahulam init                   Scaffold .bahulam config, memory, hooks, tasks
+    bahulam version                Show version
 
   \x1b[1mAnalytics:\x1b[0m
-    bahulam-code sessions               List recent local sessions
-    bahulam-code stats                  Show aggregate local session stats
-    bahulam-code history                Show recent prompt history
+    bahulam sessions               List recent local sessions
+    bahulam stats                  Show aggregate local session stats
+    bahulam history                Show recent prompt history
 
   \x1b[1mSkills:\x1b[0m
-    bahulam-code skills list [--all|--project]
-    bahulam-code skills view <name> [resource]
-    bahulam-code skills install <path-or-git-url> [--project] [--force]
-    bahulam-code skills update <name> [--project]
-    bahulam-code skills remove <name> [--project]
+    bahulam skills list [--all|--project]
+    bahulam skills view <name> [resource]
+    bahulam skills install <path-or-git-url> [--project] [--force]
+    bahulam skills update <name> [--project]
+    bahulam skills remove <name> [--project]
 
   \x1b[1mREPL Commands:\x1b[0m
     /help                   Show available commands
@@ -239,7 +239,7 @@ async function main() {
                             Max reconnect window for dropped streams
     KEPLER_BLOCK_SEPARATOR  Tool/content separator: space, dotted, or off
 
-  \x1b[2mDocs: https://0xb0.ai\x1b[0m
+  \x1b[2mDocs: https://bahulam.ai\x1b[0m
 `);
     return;
   }

package/src/terminal/repl-explore.mjs

@@ -10,9 +10,18 @@
 const EXPLORE_TOOL_CATEGORY = new Map([
   ['read_file', 'read'], ['read', 'read'], ['read_files', 'read'],
   ['read_batch', 'read'], ['get_file_info', 'read'],
+  // analyze_code is the "cheap 10x-lighter than read_file" tool the system
+  // prompt tells the agent to prefer for structure lookups. Burst usage is
+  // as common as read bursts, so classify it as a read for collapse.
+  ['analyze_code', 'read'],
   ['list_files', 'list'], ['glob', 'list'], ['ls', 'list'],
   ['search_code', 'search'], ['search_files', 'search'], ['grep', 'search'],
+  // validate_* tools are read-only structure/build checks the agent chains
+  // during post-write verification. They fit naturally in a search-ish bucket
+  // ("checking") rather than opening a discrete card per call.
+  ['validate_file', 'search'], ['validate_structure', 'search'],
   ['index_project', 'index'], ['register_project', 'index'],
+  ['get_project_overview', 'index'],
 ]);
 
 export function exploreCollapseEnabled() {

package/src/terminal/repl.mjs

@@ -19,6 +19,7 @@ import * as readline from 'node:readline';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { execSync as _execSync } from 'node:child_process';
+import { Writable as _WritableStream } from 'node:stream';
 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';
@@ -56,9 +57,13 @@ import { appendTask, ensureTaskFiles, loadTaskBoard, moveTask, removeTask, taskC
 import { applyCompactSummary, localCompactSummary, parseCompactTailCount, prepareCompactHistory } from '../core/compact-history.mjs';
 import {
   appendVisionAnalysisToInstruction,
+  appendDocumentsToInstruction,
   attachmentSummaryLine,
+  documentSummaryLine,
   prepareImageAttachments,
+  prepareDocumentAttachments,
   publicAttachmentMetadata,
+  publicDocumentMetadata,
   resolveAttachmentPath,
   writeClipboardImageToTemp,
 } from '../core/attachments.mjs';
@@ -1259,6 +1264,30 @@ function renderEvent(event) {
       }
       break;
 
+    // Live steering ack events (PRD-081 §5.2). renderEvent is called from
+    // the SSE loop (see `for await ... jsonlWriter.writeKeplerEvent(event)`
+    // in the /execute path) so every event already lands in the transcript.
+    // Here we only render the user-visible surface — no direct jsonlWriter
+    // calls (it's out of scope in this top-level dispatcher anyway).
+    case 'user_intervention_accepted': {
+      // Endpoint response already told the CLI "sent to running agent".
+      // The SSE echo here is durable-replay backup; nothing to render.
+      break;
+    }
+    case 'user_intervention_delivered': {
+      renderBlockBoundary('status', { compactSame: true });
+      const tool = data?.delivered_at_tool ? ` ${c.dim(`(via ${data.delivered_at_tool})`)}` : '';
+      process.stderr.write(`  ${c.green('✓')} ${c.dim('follow-up delivered to agent')}${tool}\n`);
+      runtime.lastRenderedBlock = 'status';
+      break;
+    }
+    case 'user_intervention_queued': {
+      // Task ended before delivery; endpoint returned queued_next_turn to
+      // the submission call and the CLI already rendered that ack. Nothing
+      // more to show; the outer SSE loop persists this event to JSONL.
+      break;
+    }
+
     case 'complete': {
       stopSpinner();
       flushContent();
@@ -2924,9 +2953,28 @@ export async function startTerminalRepl() {
     return 'type any extra context (paths, corrections, follow-ups) · [Enter] send · [Esc] cancel · [Ctrl+P] pause';
   }
 
+  // Proxy stream: swallows writes when the dock owns the input row so
+  // readline's echoes and _refreshLine cursor moves can't fight the dock's
+  // absolute cursor placement (PRD-081 §5.1 — cursor race). When the dock
+  // is not mounted (plain-mode fallback, KEPLER_FIXED_INPUT=0, non-TTY),
+  // writes pass through so history navigation / backspace still redraw.
+  const readlineOutputProxy = new _WritableStream({
+    write(chunk, _enc, cb) {
+      if (!isInputDockMounted()) {
+        try { process.stderr.write(chunk); } catch {}
+      }
+      cb();
+    },
+  });
+  // Preserve enough of stderr's TTY surface so readline still treats us as
+  // a terminal (raw mode, keypress events, history navigation).
+  readlineOutputProxy.isTTY = process.stderr.isTTY;
+  readlineOutputProxy.columns = process.stderr.columns;
+  readlineOutputProxy.rows = process.stderr.rows;
+
   const rl = readline.createInterface({
     input: process.stdin,
-    output: process.stderr,
+    output: readlineOutputProxy,
     prompt: userPrompt(),
     completer: (line) => {
       if (line.startsWith('/')) {
@@ -2973,6 +3021,14 @@ export async function startTerminalRepl() {
   }
 
   function restoreReadlineCursor() {
+    // When the dock owns the input row, delegate to it so INPUT_INDENT +
+    // meta/tips row math stays authoritative. Falling back to
+    // readline.cursorTo(col) here lands INPUT_INDENT chars too far left
+    // and yields the "/-shifts-cursor" bug (PRD-081 §5.1 cursor race).
+    if (isInputDockMounted()) {
+      focusDockInput(userPrompt(), rl.line || '', typeof rl.cursor === 'number' ? rl.cursor : null);
+      return;
+    }
     const col = Math.max(0, promptColumns() + Number(rl.cursor || 0));
     readline.cursorTo(process.stderr, col);
   }
@@ -3080,10 +3136,15 @@ export async function startTerminalRepl() {
 
   function renderIdleDockInput() {
     if (!isInputDockMounted()) return false;
+    // rl.cursor is readline's byte offset within rl.line. Threading it
+    // through to focusDockInput makes arrow-key navigation visually move
+    // the terminal cursor within the buffer instead of always landing at
+    // the end of the string.
     return renderDockInput(userPrompt(), rl.line || '', {
       context: buildContextStrip(),
       meta: buildDockMeta(),
       tips: idleInputTips(),
+      cursor: typeof rl.cursor === 'number' ? rl.cursor : null,
     });
   }
 
@@ -3278,8 +3339,28 @@ export async function startTerminalRepl() {
     }
 
     try {
+      // ── Document attachments (client-side, PRD-091 shape 1) ──
+      // Extract text locally (PDF via pdf-parse, others as UTF-8). We stage
+      // the docs here and inline their text into the user turn LAST, after
+      // vision/image processing, because the image parser normalizes
+      // whitespace and would collapse the doc block's newlines.
+      const docPrep = await prepareDocumentAttachments(originalInput, { cwd: safeCwd() });
+      if (docPrep.documents.length) {
+        process.stderr.write(
+          `  ${c.brand('◇')} ${c.dim(`attached ${docPrep.documents.length} document${docPrep.documents.length === 1 ? '' : 's'}:`)} ` +
+          `${docPrep.documents.map(documentSummaryLine).join(c.dim(' · '))}\n`
+        );
+        jsonlWriter.writeKeplerEvent({
+          type: 'attachments',
+          data: { documents: docPrep.documents.map(publicDocumentMetadata) },
+        });
+      }
+      // Image parser operates on the doc-stripped instruction so @doc.pdf
+      // refs are already gone by the time it sees the text.
+      const imageSourceInput = docPrep.instruction || originalInput;
+
       const pending = pendingVisionPaths(ctx);
-      const prepared = prepareImageAttachments(originalInput, {
+      const prepared = prepareImageAttachments(imageSourceInput, {
         cwd: safeCwd(),
         extraPaths: pending,
       });
@@ -3315,6 +3396,11 @@ export async function startTerminalRepl() {
       } else {
         input = prepared.instruction || originalInput;
       }
+      // Inline documents AFTER image/vision handling so their newlines
+      // survive the image parser's whitespace normalization.
+      if (docPrep.documents.length) {
+        input = appendDocumentsToInstruction(input, docPrep.documents);
+      }
     } catch (err) {
       process.stderr.write(`  ${c.red('Vision error: ' + (err.message || String(err)))}\n`);
       showPrompt();
@@ -3431,16 +3517,41 @@ export async function startTerminalRepl() {
         process.stderr.write('\n');
       }
       executionInputVisible = false;
-      try {
-        await client.resume(instruction);
-        jsonlWriter.writeKeplerEvent({
-          type: 'user_intervention',
-          data: { instruction, task_id: client.currentTaskId || null },
-        });
-        process.stderr.write(`  ${c.green('↳')} ${c.dim('sent follow-up to running agent')}\n`);
-      } catch {
+      // Live steering (PRD-081 §5.2): submit through the dedicated
+      // /api/intervention/{task_id} path, not /resume. The stream client
+      // returns a status object so we render the true backend decision
+      // (accepted vs queued-for-next-turn vs duplicate) instead of guessing.
+      const result = await client.sendIntervention(instruction);
+      const taskId = client.currentTaskId || null;
+      const status = result && result.status;
+      const interventionId = result && result.interventionId;
+
+      // Persist the local record regardless of outcome so the transcript
+      // reflects what the user typed. Delivered/queued follow-ups will
+      // get their SSE ack events written separately by the event handler.
+      jsonlWriter.writeKeplerEvent({
+        type: 'user_intervention',
+        data: {
+          instruction,
+          task_id: taskId,
+          intervention_id: interventionId || null,
+          status: status || 'unknown',
+        },
+      });
+
+      if (status === 'accepted') {
+        process.stderr.write(`  ${c.green('↳')} ${c.dim('sent to running agent')}\n`);
+      } else if (status === 'duplicate') {
+        process.stderr.write(`  ${c.dim('↳ already sent (idempotent)')}\n`);
+      } else if (status === 'queued_next_turn') {
+        _queuedLines.push(instruction);
+        process.stderr.write(`  ${c.yellow('↳')} ${c.dim('task ended — queued for next turn')}\n`);
+      } else {
+        // no_task, error, or unknown — fall back to next-turn queue so the
+        // user's text is never silently lost.
         _queuedLines.push(instruction);
-        process.stderr.write(`  ${c.yellow('↳')} ${c.dim('queued follow-up for the next turn')}\n`);
+        const errBits = result && result.error ? ` ${c.dim(`(${String(result.error).slice(0, 80)})`)}` : '';
+        process.stderr.write(`  ${c.yellow('↳')} ${c.dim('queued for next turn')}${errBits}\n`);
       }
     }
 

package/src/terminal/skills.mjs

@@ -29,7 +29,7 @@ export async function runSkillsCommand(args, { cwd = process.cwd() } = {}) {
     }
     if (action === 'view') {
         const name = rest.find(arg => !arg.startsWith('--'));
-        if (!name) throw new Error('Usage: bahulam-code skills view <name> [resource-path]');
+        if (!name) throw new Error('Usage: bahulam skills view <name> [resource-path]');
         const nameIndex = rest.indexOf(name);
         const resource = rest.slice(nameIndex + 1).find(arg => !arg.startsWith('--')) || null;
         print(loader.view(name, resource));

package/src/tools/project-overview.mjs

@@ -55,6 +55,52 @@ const IGNORED_DIRS = new Set([
     'build', 'dist', 'node_modules', 'venv',
 ]);
 
+// Files or directories whose presence at the root implies this IS a project.
+// One is enough. Kept broad so we accept Node/Python/Rust/Go/Ruby/Java/C++
+// projects, container-only repos, and Bahulam/agent-configured directories.
+const PROJECT_MARKERS = [
+    '.git', '.hg', '.svn',
+    '.bahulam', '.kepler',        // Bahulam project state
+    'package.json',                // Node
+    'pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'Pipfile',
+    'Cargo.toml',                  // Rust
+    'go.mod',                      // Go
+    'Gemfile',                     // Ruby
+    'pom.xml', 'build.gradle', 'build.gradle.kts', 'settings.gradle',  // Java/Kotlin
+    'Makefile', 'CMakeLists.txt',  // C/C++
+    'Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
+    'AGENTS.md', 'CLAUDE.md', 'KEPLER.md',  // Agent config lives at root
+    '.editorconfig',               // Broad but a strong "this is a repo" signal
+];
+
+// System / user-home roots we refuse outright — indexing these would sweep
+// every project the user has ever touched and produce noise, not signal.
+// Compared per-realpath so symlinks don't sneak past.
+function _dangerousRootSet() {
+    const set = new Set([
+        '/', '/tmp', '/var', '/etc', '/usr', '/opt',
+        '/Applications', '/Library', '/System',
+        '/Users', '/home', '/root',
+        '/Volumes', '/mnt', '/media',
+    ]);
+    try { set.add(os.homedir()); } catch {}
+    try { set.add(path.parse(os.homedir()).root); } catch {}
+    return set;
+}
+
+function isDangerousRoot(root) {
+    return _dangerousRootSet().has(root);
+}
+
+function hasProjectMarkers(root) {
+    for (const marker of PROJECT_MARKERS) {
+        try {
+            if (fs.existsSync(path.join(root, marker))) return true;
+        } catch { /* skip unreadable entries */ }
+    }
+    return false;
+}
+
 function projectId(canonicalPath) {
     return crypto.createHash('sha256').update(canonicalPath).digest('hex').slice(0, 12);
 }
@@ -372,7 +418,7 @@ export class ProjectRegistry {
         return resource;
     }
 
-    async register(rawPath, { forceRefresh = false, force_refresh = false } = {}) {
+    async register(rawPath, { forceRefresh = false, force_refresh = false, bypassProjectMarkers = false } = {}) {
         if (!rawPath) {
             throw new Error('get_project_overview requires a project path');
         }
@@ -403,9 +449,25 @@ export class ProjectRegistry {
         if (!fs.statSync(root).isDirectory()) {
             throw new Error(`Project path is not a directory: ${root}`);
         }
-        if (root === path.parse(root).root || root === os.homedir()) {
+        if (isDangerousRoot(root)) {
+            throw new Error(
+                `Refusing to index ${root} — too broad or system-level. ` +
+                `Pass a specific project directory, or answer the user's question ` +
+                `without get_project_overview if it doesn't need project files.`
+            );
+        }
+        // Programmatic file-read registration (registerFileRead) bypasses the
+        // marker check — the user has a specific file in hand and we index its
+        // parent so tool guards don't block the read. The user-facing
+        // get_project_overview tool DOES enforce the check.
+        if (!bypassProjectMarkers && !hasProjectMarkers(root)) {
             throw new Error(
-                `Refusing to index ${root} — too broad. Pass the project directory itself.`
+                `No project markers found at ${root} (checked for .git, package.json, ` +
+                `pyproject.toml, Cargo.toml, go.mod, Gemfile, pom.xml, Makefile, ` +
+                `Dockerfile, AGENTS.md, .bahulam/). If the user's request does not ` +
+                `require this codebase, do NOT call get_project_overview again for ` +
+                `this session — answer the question directly. If it does require code, ` +
+                `ask the user to point at the correct project directory.`
             );
         }
 
@@ -504,7 +566,7 @@ export class ProjectRegistry {
         const dir = path.dirname(filePath);
         if (dir === path.parse(dir).root || dir === os.homedir()) return null;
 
-        const registered = await this.register(dir);
+        const registered = await this.register(dir, { bypassProjectMarkers: true });
         const owner = this.projects.get(registered.resource.project_id);
         if (!owner) return null;
 

package/src/ui/banner.mjs

@@ -60,11 +60,11 @@ export function printBanner(version = '') {
   const vTag = version ? `${dim(' — ')}${dim('v' + version)}` : '';
 
   write('\n');
-  write(`         ${orbit} ${dim('· orbit')}\n`);
+  write(`         ${orbit} ${dim('· bahulam — abundance')}\n`);
   write('\n');
   write(`${wordmarkFrame()}\n`);
   write('\n');
-  write(`              ${dim('the coding agent')}\n`);
+  write(`              ${dim('abundance, in your terminal')}\n`);
   write(`              ${dev}${vTag}\n`);
   write('\n');
 }
@@ -139,7 +139,7 @@ export function printStyledConfig(creds) {
 
   const env = process.env.TARANG_ENV || process.env.NODE_ENV || 'production';
 
-  write(`\n${paint.bold('Bahulam Code Configuration')} ${dim('(~/.bahulam/config.json)')}\n`);
+  write(`\n${paint.bold('Bahulam Code · Abundance')} ${dim('(~/.bahulam/config.json)')}\n`);
   write(`${dim('─'.repeat(50))}\n`);
   write(`  Token:          ${mask(creds.token)}\n`);
   write(`  OpenRouter:     ${mask(creds.openRouterKey)}\n`);
@@ -151,7 +151,7 @@ export function printStyledConfig(creds) {
 }
 
 export function printGoodbye() {
-  write(`\n${paint.bold(paint.brand.primary('Goodbye!'))}\n\n`);
+  write(`\n${paint.bold(paint.brand.primary('until next time — abundance awaits'))}\n\n`);
 }
 
 // ── Git probe ────────────────────────────────────────────────────────────
@@ -204,7 +204,7 @@ export function getLoginSuccessHTML() {
         }
         .dev { color: #3fb950; }
         .bahulam { color: #58a6ff; }
-        .bahulam { color: #7c3aed; letter-spacing: 4px; }
+        .bahulam { color: #06b6d4; letter-spacing: 4px; }
         .check {
             font-size: 64px;
             color: #3fb950;

package/src/ui/input-dock.mjs

@@ -64,7 +64,12 @@ let inputRowsMax = DEFAULT_MAX_INPUT_ROWS;
 let inputRows = MIN_INPUT_ROWS;
 let reservedRows = FIXED_ROWS + MIN_INPUT_ROWS;
 let unsubResize = null;
-let lastFrame = { context: '', meta: '', tips: '' };
+// prefix + value are tracked here so any code path that redraws the dock
+// (renderFrame, applyLayout, redrawDockFrame, resize) can end by parking
+// the cursor at the correct input position. Without this, readline echoes
+// land on rows the dock briefly moved through mid-render and characters
+// appear above/below the input row.
+let lastFrame = { context: '', meta: '', tips: '', prefix: '', value: '', cursor: null };
 let resetting = false;
 
 function write(s) { try { OUT.write(s); } catch {} }
@@ -123,9 +128,26 @@ function computeInputRowsForBuffer(prefix, value) {
 // Resize the input area to a new row count. Moves the scroll region so
 // content above shifts accordingly; the dock frame is redrawn at the
 // new position. No-op if the count didn't change.
+//
+// CRITICAL: when the dock SHRINKS (inputRows decreases), the frame moves
+// down and previously-dock rows become part of the scroll region. Those
+// rows still hold their old dock content (rule chars, prior input text,
+// meta line) which then leaks into the transcript as streamed content
+// scrolls past them. We clear the old dock region BEFORE moving the frame
+// so the freed rows are blank when they enter the scroll region.
 function setInputRowsTo(nextRows) {
   const clamped = Math.max(MIN_INPUT_ROWS, Math.min(inputRowsMax, Math.floor(nextRows)));
   if (clamped === inputRows) return false;
+  const shrinking = clamped < inputRows;
+  if (mounted && shrinking) {
+    // Clear the entire old reserved region — top rule through safety row —
+    // so nothing that lived here leaks into the scroll region after we
+    // move the frame down.
+    for (let row = topRuleRow(); row <= rows(); row++) {
+      moveTo(row, 1);
+      clearLine();
+    }
+  }
   inputRows = clamped;
   reservedRows = FIXED_ROWS + inputRows;
   if (mounted) {
@@ -189,18 +211,40 @@ function bottomRuleLine() {
   return paint.brand.primary(ruleChars(Math.max(0, cols() - 1)));
 }
 
+// Always park the cursor at the tracked (prefix, value) input position.
+// Called at the END of every dock render path so readline echoes land in
+// the input row, not on whichever row a mid-render moveTo left them on.
+// When there is no tracked input (nothing to focus yet), park at the
+// scroll-region bottom so writes at least stay above the dock frame.
+function parkCursorAtInput() {
+  if (!mounted) return;
+  const prefix = lastFrame.prefix || '';
+  const value = lastFrame.value || '';
+  if (!prefix && !value) {
+    moveTo(inputRowStart(), INPUT_INDENT + 1);
+    return;
+  }
+  focusDockInput(prefix, value, lastFrame.cursor);
+}
+
 function applyLayout() {
   if (!mounted) return;
   const bottom = contentBottomRow();
   setScrollRegion(1, bottom);
   renderFrame(lastFrame);
-  moveTo(bottom, 1);
+  // On (re)mount and resize, park at input if we have one; otherwise sit at
+  // the bottom of the content region so any pending content writes flush
+  // above the dock rather than into a stale mid-frame position.
+  if (lastFrame.prefix || lastFrame.value) {
+    parkCursorAtInput();
+  } else {
+    moveTo(bottom, 1);
+  }
 }
 
 function renderFrame(frame = {}) {
   if (!mounted) return;
   lastFrame = { ...lastFrame, ...frame };
-  saveCursor();
 
   moveTo(topRuleRow(), 1);
   clearLine();
@@ -220,7 +264,7 @@ function renderFrame(frame = {}) {
   clearLine();
   write(padLine(bottomRuleLine()));
 
-  // Meta row: model · cwd ⎇ branch · turn N · tokens · elapsed
+  // Meta row: cwd ⎇ branch · turn N · tokens
   moveTo(metaRow(), 1);
   clearLine();
   const metaIndent = ' '.repeat(META_INDENT);
@@ -238,16 +282,19 @@ function renderFrame(frame = {}) {
   // Safety row.
   moveTo(rows(), 1);
   clearLine();
-  restoreCursor();
+
+  // Deliberately NOT using saveCursor/restoreCursor. VT100 has a single
+  // cursor-save slot per terminal; nested calls in drawInputLines /
+  // pinned-status writers clobber the outer save and restore to the wrong
+  // place. Instead, callers that need the cursor parked at the input row
+  // invoke parkCursorAtInput() after renderFrame returns.
 }
 
 function clearInputRows() {
-  saveCursor();
   for (let row = inputRowStart(); row <= inputRowEnd(); row++) {
     moveTo(row, 1);
     clearLine();
   }
-  restoreCursor();
 }
 
 export function clearDockArea({ restore = true } = {}) {
@@ -281,7 +328,6 @@ function layoutInput(prefix, value) {
 }
 
 function drawInputLines(lines) {
-  saveCursor();
   const indent = ' '.repeat(INPUT_INDENT);
   for (let i = 0; i < inputRows; i++) {
     const row = inputRowStart() + i;
@@ -291,7 +337,7 @@ function drawInputLines(lines) {
       write(`${indent}${lines[i]}`);
     }
   }
-  restoreCursor();
+  // No save/restore — caller parks cursor via focusDockInput.
 }
 
 export function isInputDockMounted() {
@@ -378,6 +424,7 @@ export function clearPinnedStatus() {
 export function redrawDockFrame() {
   if (!mounted) return false;
   renderFrame(lastFrame);
+  parkCursorAtInput();
   return true;
 }
 
@@ -385,7 +432,7 @@ export function prepareInputPrompt({ context = '', tips = '', meta = '' } = {})
   if (!mounted) return false;
   setInputRowsTo(MIN_INPUT_ROWS);
   clearInputRows();
-  renderFrame({ context, tips, meta });
+  renderFrame({ context, tips, meta, prefix: '', value: '' });
   moveTo(inputRowStart(), INPUT_INDENT + 1);
   return true;
 }
@@ -393,29 +440,40 @@ export function prepareInputPrompt({ context = '', tips = '', meta = '' } = {})
 export function clearInputPrompt() {
   if (!mounted) return false;
   clearInputRows();
+  lastFrame.value = '';
   renderFrame(lastFrame);
+  parkCursorAtInput();
   return true;
 }
 
-export function renderDockInput(prefix, value, { context = '', tips = '', meta = '' } = {}) {
+export function renderDockInput(prefix, value, { context = '', tips = '', meta = '', cursor = null } = {}) {
   if (!mounted) return false;
   setInputRowsTo(computeInputRowsForBuffer(prefix, value));
-  renderFrame({ context, tips, meta });
+  renderFrame({ context, tips, meta, prefix, value, cursor });
   const layout = layoutInput(prefix, value);
   drawInputLines(layout.lines);
-  focusDockInput(prefix, value);
+  focusDockInput(prefix, value, cursor);
   return true;
 }
 
 /**
- * Move the terminal cursor to the position that corresponds to the logical
- * end of `prefix + value` within the (possibly wrapped and truncated) input
- * area. If the buffer overflowed, the cursor lands on the last visible row.
+ * Move the terminal cursor to the position that corresponds to
+ * `prefix + value[0..cursorInValue]` within the (possibly wrapped and
+ * truncated) input area. When `cursorInValue` is null/undefined, the cursor
+ * lands at the logical end of `value` (append-mode default).
+ *
+ * `cursorInValue` is a char index into the RAW value string (matching
+ * readline's `rl.cursor`), not into the wrapped/rendered output.
  */
-export function focusDockInput(prefix, value = '') {
+export function focusDockInput(prefix, value = '', cursorInValue = null) {
   if (!mounted) return false;
   const layout = layoutInput(prefix, value);
-  const offset = visibleWidth(`${prefix || ''}${value || ''}`);
+  const valueStr = String(value || '');
+  const rawCursor = cursorInValue == null
+    ? valueStr.length
+    : Math.max(0, Math.min(valueStr.length, Math.floor(cursorInValue)));
+  const cursorSlice = valueStr.slice(0, rawCursor);
+  const offset = visibleWidth(`${prefix || ''}${cursorSlice}`);
   const pos = cursorPositionInLines(layout.wrapped, offset);
   const visibleRowIdx = Math.max(
     0,