@bahulam/code 2.6.14 → 2.6.16

package/src/core/safety.mjs

@@ -28,6 +28,18 @@ const PROTECTED_NAMES = new Set([
   'go.sum',
 ]);
 
+const APPROVAL_REQUIRED_WRITE_NAMES = new Set([
+  '.env',
+  '.env.local',
+  '.env.production',
+  'package.json',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'Cargo.lock',
+  'go.sum',
+]);
+
 /** Directory names that indicate a source root — never delete the dir itself. */
 const SOURCE_DIRS = new Set([
   'src',
@@ -80,13 +92,35 @@ const HIGH_RISK_COMMANDS = [
 
 // ── Validation Functions ─────────────────────────────────────
 
+function basenameFor(filePath = '') {
+  return path.basename(String(filePath || '').replace(/\\/g, '/'));
+}
+
+function isEnvLikeName(name = '') {
+  return /^\.env(?:\.|$)/.test(String(name || ''));
+}
+
+function isProtectedName(name = '') {
+  return PROTECTED_NAMES.has(name) || isEnvLikeName(name);
+}
+
+export function isSensitiveConfigPath(filePath = '') {
+  return isEnvLikeName(basenameFor(filePath));
+}
+
+export function isApprovalRequiredWritePath(filePath = '') {
+  const basename = basenameFor(filePath);
+  return isSensitiveConfigPath(filePath) || APPROVAL_REQUIRED_WRITE_NAMES.has(basename);
+}
+
 /**
  * Check if a path is protected (should not be deleted/overwritten entirely).
  * @param {string} filePath - Absolute path
  * @param {string} cwd - Current working directory
- * @returns {{ safe: boolean, reason?: string }}
+ * @param {{ allowApprovalRequiredWrite?: boolean }} options
+ * @returns {{ safe: boolean, reason?: string, requiresApproval?: boolean, sensitive?: boolean, protected?: boolean }}
  */
-export function validatePath(filePath, cwd = process.cwd()) {
+export function validatePath(filePath, cwd = process.cwd(), options = {}) {
   if (!filePath) return { safe: false, reason: 'Empty path' };
 
   const resolved = path.resolve(cwd, filePath);
@@ -100,7 +134,16 @@ export function validatePath(filePath, cwd = process.cwd()) {
   }
 
   // Block protected file names at any level
-  if (PROTECTED_NAMES.has(basename) && !resolved.includes('node_modules/')) {
+  if (isProtectedName(basename) && !resolved.includes('node_modules/')) {
+    if (options.allowApprovalRequiredWrite && isApprovalRequiredWritePath(resolved)) {
+      return {
+        safe: true,
+        reason: `Approval required for protected path: ${basename}`,
+        requiresApproval: true,
+        protected: true,
+        sensitive: isSensitiveConfigPath(resolved),
+      };
+    }
     return { safe: false, reason: `Protected path: ${basename}` };
   }
 
@@ -172,16 +215,29 @@ export function validateShellCommand(command) {
  * @returns {{ safe: boolean, reason?: string }}
  */
 export function validateWrite(filePath, content, cwd = process.cwd()) {
-  const pathCheck = validatePath(filePath, cwd);
+  const pathCheck = validatePath(filePath, cwd, { allowApprovalRequiredWrite: true });
   if (!pathCheck.safe) return pathCheck;
 
   const resolved = path.resolve(cwd, filePath);
+  const basename = path.basename(resolved);
 
   // Don't allow overwriting .git internals
   if (resolved.includes('/.git/')) {
     return { safe: false, reason: 'Cannot write to .git directory' };
   }
 
+  if (pathCheck.requiresApproval) {
+    return {
+      safe: true,
+      reason: pathCheck.sensitive
+        ? `Sensitive config write requires approval: ${basename}`
+        : `Protected file write requires approval: ${basename}`,
+      requiresApproval: true,
+      protected: true,
+      sensitive: pathCheck.sensitive,
+    };
+  }
+
   // Warn if writing a very large file (> 1MB)
   if (content && content.length > 1_000_000) {
     return { safe: true, reason: `Large file write: ${(content.length / 1024).toFixed(0)}KB` };
@@ -196,6 +252,7 @@ export function validateWrite(filePath, content, cwd = process.cwd()) {
 export function getSafetyRules() {
   return {
     protectedNames: [...PROTECTED_NAMES],
+    approvalRequiredWriteNames: [...APPROVAL_REQUIRED_WRITE_NAMES],
     sourceDirs: [...SOURCE_DIRS],
     blockedPatterns: DANGEROUS_SHELL_PATTERNS.length,
     highRiskPatterns: HIGH_RISK_COMMANDS.length,

package/src/core/tool-executor.mjs

@@ -10,7 +10,7 @@
 
 import { createToolRegistry } from '../tools/registry.mjs';
 import { detectCommandType, filterOutput } from './output-filter.mjs';
-import { validatePath, validateDelete, validateShellCommand, validateWrite } from './safety.mjs';
+import { isSensitiveConfigPath, validatePath, validateDelete, validateShellCommand, validateWrite } from './safety.mjs';
 import { classifyCommand, isExitCodeError } from '../permissions/command-classifier.mjs';
 import { analyzeCode } from '../context/ast-parser.mjs';
 import { ProjectRegistry } from '../tools/project-overview.mjs';
@@ -366,18 +366,35 @@ export function createToolExecutor({
         return result;
     }
 
+    function buildResultFileDiff(filePath, before, after) {
+        const diff = buildFileDiff({
+            filePath,
+            before,
+            after,
+            cwd: projectRootFor(filePath),
+        });
+        if (!isSensitiveConfigPath(filePath)) return diff;
+        return {
+            ...diff,
+            hunks: [],
+            unified: '',
+            redacted: true,
+            sensitive: true,
+            redaction_reason: 'Sensitive config diff redacted',
+        };
+    }
+
     function attachFileDiff(result, filePath, before, after) {
         try {
-            const diff = buildFileDiff({
-                filePath,
-                before,
-                after,
-                cwd: projectRootFor(filePath),
-            });
+            const diff = buildResultFileDiff(filePath, before, after);
             result.file_diff = diff;
             result.diff = diff.unified;
             result.lines_added = diff.lines_added;
             result.lines_removed = diff.lines_removed;
+            if (diff.redacted) {
+                result.output = `File updated: ${diff.relative_path || filePath}\nDiff redacted for sensitive config file.`;
+                result.redacted = true;
+            }
         } catch { /* best effort */ }
         return result;
     }
@@ -821,12 +838,7 @@ export function createToolExecutor({
 
                     await occRegistry.call('Write', { file_path: filePath, content });
                     const after = readTextIfExists(filePath);
-                    diffs.push(buildFileDiff({
-                        filePath,
-                        before,
-                        after,
-                        cwd: projectRootFor(filePath),
-                    }));
+                    diffs.push(buildResultFileDiff(filePath, before, after));
                     updateProjectIndex(filePath);
                     results.push(rawPath);
                 } catch (err) {

package/src/core/trust.mjs

@@ -96,11 +96,13 @@ export class TrustStore {
       }
     }
     if ((reask.on_risk_increase ?? this.policy.hitl?.reaskOnRiskIncrease) && rule.tier && tier) {
-      const order = [TIERS.READ, TIERS.SHELL_SAFE, TIERS.LOCAL_EDIT, TIERS.SHELL_MEDIUM, TIERS.NETWORK, TIERS.SHELL_DANGEROUS, TIERS.DESTRUCTIVE];
+      const order = [TIERS.READ, TIERS.SHELL_SAFE, TIERS.LOCAL_EDIT, TIERS.PROTECTED_EDIT, TIERS.SHELL_MEDIUM, TIERS.NETWORK, TIERS.SHELL_DANGEROUS, TIERS.DESTRUCTIVE];
       if (order.indexOf(tier) > order.indexOf(rule.tier)) return 'risk tier increased';
     }
-    if ((this.policy.hitl?.alwaysAskForDangerous ?? true) && (tier === TIERS.SHELL_DANGEROUS || tier === TIERS.DESTRUCTIVE)) {
-      return 'dangerous tier requires fresh approval';
+    if ((this.policy.hitl?.alwaysAskForDangerous ?? true) && (tier === TIERS.SHELL_DANGEROUS || tier === TIERS.DESTRUCTIVE || tier === TIERS.PROTECTED_EDIT)) {
+      return tier === TIERS.PROTECTED_EDIT
+        ? 'protected edit requires fresh approval'
+        : 'dangerous tier requires fresh approval';
     }
     if ((reask.on_command_shape_change ?? this.policy.hitl?.reaskOnCommandShapeChange) && rule.command_shape && args.command) {
       if (rule.command_shape !== commandShape(args.command)) return 'command shape changed';

package/src/index.mjs

@@ -35,7 +35,7 @@ import { printBanner, printProjectInfo, printHints, printAuthStatus, printStyled
 import { ContextRetriever } from './context/retriever.mjs';
 import { loadSettings } from './config/settings.mjs';
 
-const VERSION = '2.6.14';
+const VERSION = '2.6.16';
 
 // ── Arg Parsing (consolidated from index.mjs + cli-args.mjs) ──
 
@@ -50,6 +50,7 @@ function parseArgs(argv) {
         // Config subcommand flags
         showConfig: false, openRouterKey: null, anthropicKey: null,
         backendUrl: null, mode: null,
+        model: null, route: null,
         // Extended flags (from cli-args.mjs)
         permissionMode: null,
         outputFormat: null,
@@ -96,7 +97,8 @@ function parseArgs(argv) {
             case '--google-key': args.googleKey = argv[++i]; break;
             case '--gateway': args.gateway = argv[++i]; break;
             // --backend-url removed: use TARANG_ENV
-            // --model removed: use tarang configure (web settings)
+            case '--model': case '-m': args.model = argv[++i]; break;
+            case '--route': args.route = argv[++i]; break;
             // Extended flags
             case '--permission-mode': args.permissionMode = argv[++i]; break;
             case '--print': case '-p': case '--instruction': case '--input': args.instruction = argv[++i]; break;
@@ -175,9 +177,11 @@ function printUsage() {
     process.stderr.write(`  ${D}(default: auto-select based on task complexity)${R}\n`);
     process.stderr.write('\n');
     process.stderr.write(`${B}MODEL FLAGS${R}\n`);
+    process.stderr.write(`  ${G}--model, -m <id|role=id>${R}     Session model override ${D}(also: fast|thinking|extra|max)${R}\n`);
+    process.stderr.write(`  ${G}--route <platform|byok>${R}      Model route ${D}(platform validates against curated catalog)${R}\n`);
     process.stderr.write(`  ${G}--system-prompt <text>${R}       Override system prompt\n`);
     process.stderr.write(`  ${G}--max-turns <n>${R}              Maximum conversation turns\n`);
-    process.stderr.write(`  ${D}Models are configured via: bahulam configure${R}\n`);
+    process.stderr.write(`  ${D}Persistent defaults are configured via: bahulam configure${R}\n`);
     process.stderr.write('\n');
     process.stderr.write(`${B}PERMISSION FLAGS${R}\n`);
     process.stderr.write(`  ${G}--yes, -y${R}                    Auto-approve all operations\n`);

package/src/permissions/command-classifier.mjs

@@ -132,6 +132,32 @@ function containsUnquotedExpansion(command) {
 /**
  * Detect command substitution patterns.
  */
+/**
+ * Extract the inner text of every `$( … )` (nesting-aware) and
+ * `` ` … ` `` region so each body can be classified on its own.
+ */
+function extractSubstitutionBodies(command) {
+    const bodies = [];
+    const s = String(command || '');
+    for (const m of s.match(/`([^`]*)`/g) || []) {
+        bodies.push(m.slice(1, -1));
+    }
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === '$' && s[i + 1] === '(') {
+            let depth = 1;
+            let j = i + 2;
+            while (j < s.length && depth > 0) {
+                if (s[j] === '(') depth++;
+                else if (s[j] === ')') depth--;
+                j++;
+            }
+            bodies.push(s.slice(i + 2, depth === 0 ? j - 1 : j));
+            i = j - 1;
+        }
+    }
+    return bodies.map(b => b.trim()).filter(Boolean);
+}
+
 function containsCommandSubstitution(command) {
     // Backticks
     if (/`/.test(command)) return true;
@@ -505,9 +531,31 @@ export function classifyCommand(command) {
         }
     }
 
-    // ── Step 2: Check for command substitution / injection ──
+    // ── Step 2: Command substitution → approval-gated, not hard-blocked ──
+    // Backticks / $() are legitimate shell (lsof -ti:8000 | xargs kill,
+    // $(git rev-parse HEAD), etc). Hard-blocking them forced the model
+    // into awkward multi-step workarounds even after the user approved.
+    // The substitution BODY is classified recursively — `echo $(rm -rf /)`
+    // stays hard-blocked because the inner command is; a benign body
+    // surfaces as an explicit HITL approval (contained + highRisk), same
+    // as process cleanup above. (Step 1's whole-string regexes alone are
+    // not enough: `rm -rf /` inside $() terminates with `)` which the
+    // \s|$ terminators never match.)
     if (containsCommandSubstitution(trimmed)) {
-        return { classification: 'blocked', reason: 'Contains command substitution (backticks or $())' };
+        for (const inner of extractSubstitutionBodies(trimmed)) {
+            const innerResult = classifyCommand(inner);
+            if (innerResult.classification === 'blocked') {
+                return {
+                    classification: 'blocked',
+                    reason: `Substitution body is blocked: ${inner.slice(0, 50)}`,
+                };
+            }
+        }
+        return {
+            classification: 'contained',
+            reason: 'Uses command substitution (backticks or $()); requires approval',
+            highRisk: true,
+        };
     }
 
     if (containsUnsafeOutputRedirection(trimmed)) {

package/src/telemetry/index.mjs

@@ -1,96 +1,122 @@
 /**
- * Telemetry Stub — basic telemetry interface (no actual reporting).
+ * Telemetry — Funnel event emitter (PRD-076 W3).
  *
- * Logs events to debug output when CLAUDE_CODE_DEBUG is set.
- * Designed to be a drop-in interface for the full telemetry system.
+ * Buffers funnel events and flushes to {backend}/api/telemetry/funnel
+ * on a timer and on process exit. Device ID is generated once per install
+ * for anon-to-logged-in correlation.
+ *
+ * Opt-out: BAHULAM_DISABLE_TELEMETRY=1 or CLAUDE_CODE_DISABLE_TELEMETRY=1
  */
 
-const events = [];
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { bahulamHome } from '../core/paths.mjs';
+
+const BUF_LIMIT = 500;
+const FLUSH_INTERVAL_MS = 30_000;
+
+let events = [];
 let enabled = true;
+let flushTimer = null;
+let _backendUrl = null;
+let _token = null;
+let _deviceId = null;
 
-/**
- * Track a telemetry event.
- * @param {string} event - event name
- * @param {object} [properties] - event properties
- */
-export function track(event, properties = {}) {
-    if (!enabled) return;
-    if (process.env.CLAUDE_CODE_DISABLE_TELEMETRY === '1') return;
+/* ── Configuration ── */
 
-    const entry = {
-        event,
-        properties,
-        timestamp: Date.now(),
-    };
+export function disable() {
+  enabled = false;
+  if (flushTimer) { clearInterval(flushTimer); flushTimer = null; }
+}
 
-    events.push(entry);
+export function configure(backendUrl, token) {
+  _backendUrl = backendUrl;
+  _token = token;
+}
 
-    // Keep max 1000 events in memory
-    if (events.length > 1000) {
-        events.splice(0, events.length - 1000);
-    }
+/* ── Device ID ── */
 
-    if (process.env.CLAUDE_CODE_DEBUG) {
-        console.error(`[telemetry] ${event}`, JSON.stringify(properties).slice(0, 200));
+function readOrCreateDeviceId() {
+  const dir = bahulamHome();
+  const idPath = path.join(dir, 'device_id');
+  try {
+    if (fs.existsSync(idPath)) {
+      return fs.readFileSync(idPath, 'utf-8').trim();
     }
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const id = crypto.randomUUID();
+    fs.writeFileSync(idPath, id, { mode: 0o600 });
+    return id;
+  } catch { return 'unknown'; }
+}
+
+export function getDeviceId() {
+  if (!_deviceId) _deviceId = readOrCreateDeviceId();
+  return _deviceId;
+}
+
+/* ── Tracking ── */
+
+export function track(event, properties = {}) {
+  if (!enabled) return;
+  if (process.env.BAHULAM_DISABLE_TELEMETRY === '1') return;
+  if (process.env.CLAUDE_CODE_DISABLE_TELEMETRY === '1') return;
+
+  const entry = { event, properties: { ...properties }, device_id: getDeviceId(), timestamp: Date.now() };
+  events.push(entry);
+  if (events.length > BUF_LIMIT) events.splice(0, events.length - BUF_LIMIT);
+
+  if (process.env.BAHULAM_DEBUG_TELEMETRY) {
+    process.stderr.write(`[telemetry] ${event} ${JSON.stringify(properties).slice(0, 200)}\n`);
+  }
+
+  if (!flushTimer) {
+    flushTimer = setInterval(flush, FLUSH_INTERVAL_MS);
+    flushTimer.unref();
+  }
 }
 
-/**
- * Track a timing event.
- * @param {string} event - event name
- * @param {number} durationMs - duration in milliseconds
- * @param {object} [properties] - additional properties
- */
 export function trackTiming(event, durationMs, properties = {}) {
-    track(event, { ...properties, durationMs });
+  track(event, { ...properties, durationMs });
 }
 
-/**
- * Track an error.
- * @param {string} event - error context
- * @param {Error} error - the error
- */
 export function trackError(event, error) {
-    track(`error.${event}`, {
-        message: error.message,
-        stack: error.stack?.split('\n').slice(0, 3).join('\n'),
-    });
+  track(`error.${event}`, { message: error.message, stack: error.stack?.split('\n').slice(0, 3).join('\n') });
 }
 
-/**
- * Get collected events (for debugging).
- * @returns {Array}
- */
-export function getEvents() {
-    return [...events];
-}
+/* ── Transport ── */
 
-/**
- * Clear collected events.
- */
-export function clear() {
-    events.length = 0;
+export async function flush() {
+  if (!enabled || events.length === 0 || !_backendUrl) return;
+  const batch = events.splice(0);
+  const headers = { 'Content-Type': 'application/json' };
+  if (_token) headers['Authorization'] = `Bearer ${_token}`;
+  try {
+    const resp = await fetch(`${_backendUrl}/api/telemetry/funnel`, {
+      method: 'POST', headers,
+      body: JSON.stringify({
+        events: batch,
+        user_id: _token ? undefined : undefined, // backend derives from token if present
+        source: 'cli',
+      }),
+    });
+    if (!resp.ok && resp.status >= 500) events.unshift(...batch);
+  } catch { events.unshift(...batch); if (events.length > BUF_LIMIT * 2) events.splice(0, events.length - BUF_LIMIT); }
 }
 
-/**
- * Enable or disable telemetry.
- * @param {boolean} value
- */
-export function setEnabled(value) {
-    enabled = value;
+export async function shutdown() {
+  if (flushTimer) { clearInterval(flushTimer); flushTimer = null; }
+  await flush();
 }
 
-/**
- * Get telemetry stats.
- */
+/* ── Debug ── */
+
+export function getEvents() { return [...events]; }
+export function clear() { events.length = 0; }
+export function setEnabled(value) { enabled = value; }
 export function getStats() {
-    const counts = {};
-    for (const e of events) {
-        counts[e.event] = (counts[e.event] || 0) + 1;
-    }
-    return {
-        totalEvents: events.length,
-        enabled,
-        eventCounts: counts,
-    };
-}
+  const counts = {};
+  for (const e of events) counts[e.event] = (counts[e.event] || 0) + 1;
+  return { totalEvents: events.length, enabled, eventCounts: counts };
+}

package/src/terminal/main.mjs

@@ -4,6 +4,8 @@
  * Zero React. Zero Ink. Zero flickering.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { startTerminalRepl } from './repl.mjs';
 import {
   runSessionsCommand,
@@ -11,6 +13,9 @@ import {
   runHistoryCommand,
 } from './analytics.mjs';
 import { parseArgs } from '../config/cli-args.mjs';
+import * as telemetry from '../telemetry/index.mjs';
+import { bahulamHome } from '../core/paths.mjs';
+import { TarangAuth as Auth } from '../auth/tarang-auth.mjs';
 
 // ── Subcommands ──
 
@@ -83,7 +88,40 @@ function parseKeplerSubcommandArgs(command, argv) {
   return parsed;
 }
 
+function detectInstallFirstRun() {
+  const markerPath = path.join(bahulamHome(), '.install_marker');
+  try {
+    if (fs.existsSync(markerPath)) return false;
+    fs.writeFileSync(markerPath, String(Date.now()), { mode: 0o600 });
+    return true;
+  } catch { return false; }
+}
+
 async function main() {
+  // ── Telemetry bootstrap ──
+  const _auth = new Auth();
+  const _creds = _auth.loadCredentials();
+  telemetry.configure(_creds.backendUrl, _creds.token);
+
+  // Fire install_first_run on first ever CLI invocation
+  if (detectInstallFirstRun()) {
+    telemetry.track('install_first_run', { version: process.env.npm_package_version || '' });
+  }
+
+  // Check day7_return — fire once per install
+  const configDir_ = bahulamHome();
+  const installMarker_ = path.join(configDir_, '.install_marker');
+  const returnFiredPath_ = path.join(configDir_, '.return_fired');
+  try {
+    if (fs.existsSync(installMarker_) && !fs.existsSync(returnFiredPath_)) {
+      const installTime = parseInt(fs.readFileSync(installMarker_, 'utf-8').trim(), 10);
+      if (!isNaN(installTime) && Date.now() - installTime >= 7 * 24 * 60 * 60 * 1000) {
+        telemetry.track('day7_return', {});
+        fs.writeFileSync(returnFiredPath_, '1', { mode: 0o600 });
+      }
+    }
+  } catch {}
+
   if (subcommand === 'dashboard') {
     // Launch Bahulam Pulse Next.js dashboard
     const { spawn } = await import('node:child_process');
@@ -134,7 +172,9 @@ async function main() {
     const { TarangAuth } = await import('../auth/tarang-auth.mjs');
     const auth = new TarangAuth();
     try {
+      telemetry.track('login_shown', { method: 'cli_subcommand' });
       await auth.login();
+      telemetry.track('login_completed', { method: 'cli_subcommand' });
       process.stderr.write('\x1b[32m✓ Login successful!\x1b[0m\n');
       return;
     } catch (err) {

package/src/terminal/repl-format.mjs

@@ -9,6 +9,58 @@
 
 import * as path from 'node:path';
 import { c, stripAnsi, formatElapsed, inPlace } from './ansi.mjs';
+import * as rqueue from '../ui/render-queue.mjs';
+
+// Transient one-line status writer that is safe under the render queue.
+// Raw inPlace() writes get REDIRECTED into transcript content when the
+// queue is active (cursor codes stripped) — that leaked one line per
+// spinner frame during resume summarization. queue.status() coalesces
+// and overwrites in place; inPlace stays as the no-queue fallback.
+function transientLine(text) {
+  if (rqueue.isActive()) {
+    if (text) rqueue.status(text);
+    else rqueue.clearStatus();
+    return;
+  }
+  inPlace(text);
+}
+
+/**
+ * Atomic repaint writer for raw-stdin overlays (resume picker, /model form).
+ *
+ * While the render queue is active, plain process.stderr.write is REDIRECTED
+ * into transcript content with cursor codes stripped — an overlay's
+ * "cursor-up N + erase" repaint becomes "append another copy" (the form-
+ * replication bug). Each repaint therefore goes through rqueue.raw() as one
+ * frame. On the first paint the frame's rows are reserved with newlines so
+ * painting near the bottom (input dock) scrolls once up-front and the
+ * cursor-relative repaint math stays stable afterwards.
+ */
+export function writeOverlayFrame(erasePrev, lines) {
+  const body = lines.join('\n') + '\n';
+  if (erasePrev > 0) {
+    rqueue.raw(`\x1b[${erasePrev}F\r\x1b[J` + body);
+  } else {
+    rqueue.raw('\n'.repeat(lines.length) + `\x1b[${lines.length}A` + body);
+  }
+}
+
+/**
+ * Erase the previously drawn overlay frame (rows lines tall) so the next
+ * prompt / transcript output starts on a clean line. Call from every
+ * overlay's cleanup path — without this, picker frames stack on screen
+ * when a follow-up prompt (cwd confirm, next overlay) writes below them.
+ */
+export function eraseOverlayFrame(rows, summaryLine = '') {
+  if (!rows || rows <= 0) {
+    if (summaryLine) rqueue.raw(summaryLine + '\n');
+    return;
+  }
+  // Collapse the frame to a compact one-line summary (or nothing). A pure
+  // erase leaves a blank void mid-screen because the input dock parks the
+  // cursor at the bottom before the next plain write lands.
+  rqueue.raw(`\x1b[${rows}F\r\x1b[J` + (summaryLine ? summaryLine + '\n' : ''));
+}
 
 // ── One-liners ───────────────────────────────────────────────────────
 
@@ -182,23 +234,31 @@ export function startResumeProgress(mode = 'full') {
     if (!active) return;
     const glyph = frames[frame % frames.length];
     frame++;
-    inPlace(`  ${c.brand(glyph)} ${c.dim(label)}  ${resumeProgressBar(percent)}  ${c.dim(formatElapsed(started))}`);
+    transientLine(`  ${c.brand(glyph)} ${c.dim(label)}  ${resumeProgressBar(percent)}  ${c.dim(formatElapsed(started))}`);
   };
 
   render();
-  const timer = setInterval(render, 100);
+  let timer = setInterval(render, 100);
   return {
+    // Self-healing: the resume flow stops the progress line to show the
+    // cwd-confirm overlay, then keeps reporting phases ('rebuilding local
+    // session state', …). A dead update() silently dropped every cue after
+    // that prompt — revive the ticker instead (same pattern as
+    // updateSpinner in repl-render.mjs).
     update(nextLabel, nextPercent) {
-      if (!active) return;
       if (nextLabel) label = nextLabel;
       if (Number.isFinite(nextPercent)) percent = Math.max(percent, Math.min(98, nextPercent));
+      if (!active) {
+        active = true;
+        timer = setInterval(render, 100);
+      }
       render();
     },
     stop() {
       if (!active) return;
       active = false;
       clearInterval(timer);
-      inPlace('');
+      transientLine('');
     },
   };
 }