@axplusb/kepler 2.0.0 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axplusb/kepler",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Kepler — AI coding agent with operating brief, preflight planning, and sub-agents. SWE-bench Lite evaluated.",
   "type": "module",
   "bin": {

package/pulse/app/api/benchmark/route.ts

@@ -0,0 +1,113 @@
+import { NextResponse } from 'next/server'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+export const dynamic = 'force-dynamic'
+
+interface BenchmarkResult {
+  instance_id: string
+  repo: string
+  base_commit: string
+  test_patch: string
+  resolved: boolean
+  test_result: {
+    result: string[]
+    exit_code: number
+  }
+  metadata: {
+    agent_class: string
+    model_name: string
+    max_iterations: number
+    eval_history: Array<{
+      timestamp: string
+      action: string
+      observation: string
+    }>
+    submission: string
+    instance_id: string
+    predict_output: string
+    model_patch: string
+    test_result: {
+      result: string[]
+      exit_code: number
+    }
+  }
+}
+
+interface BenchmarkData {
+  results: BenchmarkResult[]
+}
+
+export async function GET(request: Request) {
+  try {
+    const { searchParams } = new URL(request.url)
+    const run = searchParams.get('run') || 'swebench-v4-flash-300'
+    const limit = parseInt(searchParams.get('limit') || '50', 10)
+    const offset = parseInt(searchParams.get('offset') || '0', 10)
+
+    // Load benchmark results from file
+    const resultsPath = join(
+      process.cwd(),
+      '..',
+      'benchmark',
+      'results',
+      'runs',
+      run,
+      'harness-results.json'
+    )
+
+    let data: BenchmarkData
+    try {
+      const fileContent = readFileSync(resultsPath, 'utf-8')
+      data = JSON.parse(fileContent)
+    } catch (error) {
+      return NextResponse.json(
+        { error: `Benchmark run "${run}" not found` },
+        { status: 404 }
+      )
+    }
+
+    // Calculate statistics
+    const results = data.results || []
+    const totalTests = results.length
+    const resolvedTests = results.filter((r) => r.resolved).length
+    const passRate = totalTests > 0 ? (resolvedTests / totalTests) * 100 : 0
+
+    // Group by repo
+    const byRepo = new Map<string, number>()
+    const byRepoResolved = new Map<string, number>()
+    for (const result of results) {
+      const repo = result.repo || 'unknown'
+      byRepo.set(repo, (byRepo.get(repo) || 0) + 1)
+      if (result.resolved) {
+        byRepoResolved.set(repo, (byRepoResolved.get(repo) || 0) + 1)
+      }
+    }
+
+    // Paginate results
+    const paginatedResults = results.slice(offset, offset + limit)
+
+    return NextResponse.json({
+      run,
+      stats: {
+        totalTests,
+        resolvedTests,
+        passRate: parseFloat(passRate.toFixed(2)),
+        byRepo: Object.fromEntries(byRepo),
+        byRepoResolved: Object.fromEntries(byRepoResolved),
+      },
+      pagination: {
+        limit,
+        offset,
+        total: totalTests,
+      },
+      results: paginatedResults,
+    })
+  } catch (error) {
+    console.error('Benchmark API error:', error)
+    return NextResponse.json(
+      { error: 'Failed to load benchmark data' },
+      { status: 500 }
+    )
+  }
+}

package/pulse/app/api/benchmarks/route.ts

@@ -0,0 +1,195 @@
+import { NextResponse } from 'next/server'
+import fs from 'fs'
+import path from 'path'
+
+export const dynamic = 'force-dynamic'
+
+interface BenchmarkResult {
+  instance_id: string
+  repo: string
+  model: string
+  timestamp: string
+  kepler: {
+    status: string
+    exit_code: number
+    duration_seconds: number
+    tokens_used: number
+    cost: number
+    tool_calls: number
+    sub_agents: string[]
+  }
+  patch_lines: number
+  model_patch: string
+  status: string
+}
+
+interface BenchmarkStats {
+  total_runs: number
+  passed: number
+  failed: number
+  error: number
+  success_rate: number
+  avg_duration: number
+  total_cost: number
+  total_tokens: number
+  avg_tokens_per_run: number
+  by_status: Record<string, number>
+  by_repo: Record<string, { count: number; passed: number; success_rate: number }>
+  by_model: Record<string, { count: number; passed: number; success_rate: number }>
+}
+
+async function loadBenchmarkResults(): Promise<BenchmarkResult[]> {
+  try {
+    const resultsPath = path.join(
+      process.cwd(),
+      'benchmark/results/runs/swebench-v4-flash-300/harness-results.json'
+    )
+
+    if (!fs.existsSync(resultsPath)) {
+      return []
+    }
+
+    const data = JSON.parse(fs.readFileSync(resultsPath, 'utf-8'))
+    return data.results || []
+  } catch (error) {
+    console.error('Error loading benchmark results:', error)
+    return []
+  }
+}
+
+function calculateStats(results: BenchmarkResult[]): BenchmarkStats {
+  if (results.length === 0) {
+    return {
+      total_runs: 0,
+      passed: 0,
+      failed: 0,
+      error: 0,
+      success_rate: 0,
+      avg_duration: 0,
+      total_cost: 0,
+      total_tokens: 0,
+      avg_tokens_per_run: 0,
+      by_status: {},
+      by_repo: {},
+      by_model: {},
+    }
+  }
+
+  const by_status: Record<string, number> = {}
+  const by_repo: Record<string, { count: number; passed: number }> = {}
+  const by_model: Record<string, { count: number; passed: number }> = {}
+
+  let total_cost = 0
+  let total_tokens = 0
+  let total_duration = 0
+  let passed = 0
+
+  results.forEach((result) => {
+    // Count by status
+    by_status[result.status] = (by_status[result.status] || 0) + 1
+
+    // Count by repo
+    if (!by_repo[result.repo]) {
+      by_repo[result.repo] = { count: 0, passed: 0 }
+    }
+    by_repo[result.repo].count++
+
+    // Count by model
+    if (!by_model[result.model]) {
+      by_model[result.model] = { count: 0, passed: 0 }
+    }
+    by_model[result.model].count++
+
+    // Aggregate metrics
+    if (result.kepler) {
+      total_cost += result.kepler.cost || 0
+      total_tokens += result.kepler.tokens_used || 0
+      total_duration += result.kepler.duration_seconds || 0
+
+      if (result.kepler.status === 'success') {
+        passed++
+        by_repo[result.repo].passed++
+        by_model[result.model].passed++
+      }
+    }
+  })
+
+  // Calculate success rates
+  const by_repo_with_rates = Object.entries(by_repo).reduce(
+    (acc, [repo, data]) => {
+      acc[repo] = {
+        ...data,
+        success_rate: data.count > 0 ? (data.passed / data.count) * 100 : 0,
+      }
+      return acc
+    },
+    {} as Record<string, { count: number; passed: number; success_rate: number }>
+  )
+
+  const by_model_with_rates = Object.entries(by_model).reduce(
+    (acc, [model, data]) => {
+      acc[model] = {
+        ...data,
+        success_rate: data.count > 0 ? (data.passed / data.count) * 100 : 0,
+      }
+      return acc
+    },
+    {} as Record<string, { count: number; passed: number; success_rate: number }>
+  )
+
+  return {
+    total_runs: results.length,
+    passed,
+    failed: by_status['failed'] || 0,
+    error: by_status['error'] || 0,
+    success_rate: (passed / results.length) * 100,
+    avg_duration: total_duration / results.length,
+    total_cost,
+    total_tokens,
+    avg_tokens_per_run: total_tokens / results.length,
+    by_status,
+    by_repo: by_repo_with_rates,
+    by_model: by_model_with_rates,
+  }
+}
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url)
+  const format = searchParams.get('format') || 'summary'
+  const repo = searchParams.get('repo')
+  const model = searchParams.get('model')
+  const status = searchParams.get('status')
+
+  const results = await loadBenchmarkResults()
+
+  // Filter results
+  let filtered = results
+  if (repo) {
+    filtered = filtered.filter((r) => r.repo === repo)
+  }
+  if (model) {
+    filtered = filtered.filter((r) => r.model === model)
+  }
+  if (status) {
+    filtered = filtered.filter((r) => r.status === status)
+  }
+
+  if (format === 'detailed') {
+    return NextResponse.json({
+      results: filtered,
+      count: filtered.length,
+    })
+  }
+
+  // Default: summary format
+  const stats = calculateStats(filtered)
+
+  return NextResponse.json({
+    stats,
+    filters: {
+      repo: repo || null,
+      model: model || null,
+      status: status || null,
+    },
+  })
+}

package/pulse/app/benchmarks/page.tsx

@@ -0,0 +1,224 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import { Badge } from '@/components/ui/badge'
+
+interface BenchmarkStats {
+  total_runs: number
+  passed: number
+  failed: number
+  error: number
+  success_rate: number
+  avg_duration: number
+  total_cost: number
+  total_tokens: number
+  avg_tokens_per_run: number
+  by_status: Record<string, number>
+  by_repo: Record<string, { count: number; passed: number; success_rate: number }>
+  by_model: Record<string, { count: number; passed: number; success_rate: number }>
+}
+
+interface BenchmarkResponse {
+  stats: BenchmarkStats
+  filters: {
+    repo: string | null
+    model: string | null
+    status: string | null
+  }
+}
+
+export default function BenchmarksPage() {
+  const [data, setData] = useState<BenchmarkResponse | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    const fetchBenchmarks = async () => {
+      try {
+        const response = await fetch('/api/benchmarks')
+        if (!response.ok) {
+          throw new Error('Failed to fetch benchmarks')
+        }
+        const json = await response.json()
+        setData(json)
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Unknown error')
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    fetchBenchmarks()
+  }, [])
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center min-h-screen">
+        <p className="text-muted-foreground">Loading benchmarks...</p>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className="flex items-center justify-center min-h-screen">
+        <p className="text-destructive">Error: {error}</p>
+      </div>
+    )
+  }
+
+  if (!data) {
+    return (
+      <div className="flex items-center justify-center min-h-screen">
+        <p className="text-muted-foreground">No benchmark data available</p>
+      </div>
+    )
+  }
+
+  const stats = data.stats
+
+  return (
+    <div className="space-y-6 p-6">
+      <div>
+        <h1 className="text-3xl font-bold tracking-tight">Benchmarks</h1>
+        <p className="text-muted-foreground mt-2">SWE-Bench v4 Flash 300 Results</p>
+      </div>
+
+      {/* Key Metrics */}
+      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium">Total Runs</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-2xl font-bold">{stats.total_runs}</div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium">Success Rate</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-2xl font-bold">{stats.success_rate.toFixed(1)}%</div>
+            <p className="text-xs text-muted-foreground mt-1">
+              {stats.passed} passed, {stats.failed} failed
+            </p>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium">Total Cost</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-2xl font-bold">${stats.total_cost.toFixed(2)}</div>
+            <p className="text-xs text-muted-foreground mt-1">
+              {stats.avg_tokens_per_run.toFixed(0)} tokens/run
+            </p>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium">Avg Duration</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-2xl font-bold">{stats.avg_duration.toFixed(1)}s</div>
+            <p className="text-xs text-muted-foreground mt-1">
+              {(stats.total_tokens / 1000).toFixed(1)}K tokens total
+            </p>
+          </CardContent>
+        </Card>
+      </div>
+
+      {/* Status Breakdown */}
+      <Card>
+        <CardHeader>
+          <CardTitle>Status Breakdown</CardTitle>
+          <CardDescription>Distribution of run statuses</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="space-y-3">
+            {Object.entries(stats.by_status).map(([status, count]) => (
+              <div key={status} className="flex items-center justify-between">
+                <div className="flex items-center gap-2">
+                  <Badge
+                    variant={
+                      status === 'success'
+                        ? 'default'
+                        : status === 'failed'
+                          ? 'destructive'
+                          : 'secondary'
+                    }
+                  >
+                    {status}
+                  </Badge>
+                  <span className="text-sm text-muted-foreground">{count} runs</span>
+                </div>
+                <span className="text-sm font-medium">
+                  {((count / stats.total_runs) * 100).toFixed(1)}%
+                </span>
+              </div>
+            ))}
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* By Repository */}
+      <Card>
+        <CardHeader>
+          <CardTitle>Performance by Repository</CardTitle>
+          <CardDescription>Success rate and run count per repository</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="space-y-4">
+            {Object.entries(stats.by_repo)
+              .sort((a, b) => b[1].count - a[1].count)
+              .map(([repo, data]) => (
+                <div key={repo} className="flex items-center justify-between border-b pb-3 last:border-0">
+                  <div>
+                    <p className="font-medium text-sm">{repo}</p>
+                    <p className="text-xs text-muted-foreground">
+                      {data.count} runs, {data.passed} passed
+                    </p>
+                  </div>
+                  <div className="text-right">
+                    <p className="font-bold text-sm">{data.success_rate.toFixed(1)}%</p>
+                  </div>
+                </div>
+              ))}
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* By Model */}
+      <Card>
+        <CardHeader>
+          <CardTitle>Performance by Model</CardTitle>
+          <CardDescription>Success rate and run count per model</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="space-y-4">
+            {Object.entries(stats.by_model)
+              .sort((a, b) => b[1].count - a[1].count)
+              .map(([model, data]) => (
+                <div key={model} className="flex items-center justify-between border-b pb-3 last:border-0">
+                  <div>
+                    <p className="font-medium text-sm">{model}</p>
+                    <p className="text-xs text-muted-foreground">
+                      {data.count} runs, {data.passed} passed
+                    </p>
+                  </div>
+                  <div className="text-right">
+                    <p className="font-bold text-sm">{data.success_rate.toFixed(1)}%</p>
+                  </div>
+                </div>
+              ))}
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}

package/pulse/components/layout/bottom-nav.tsx

@@ -4,7 +4,7 @@ import Link from 'next/link'
 import { usePathname } from 'next/navigation'
 import {
   LayoutDashboard, MessageSquare, DollarSign,
-  FolderOpen, Activity, Moon, Sun,
+  FolderOpen, Activity, Moon, Sun, Zap,
 } from 'lucide-react'
 import { useTheme } from '@/components/theme-provider'
 import { cn } from '@/lib/utils'
@@ -15,6 +15,7 @@ const NAV = [
   { href: '/costs',    label: 'Costs',     icon: DollarSign      },
   { href: '/projects', label: 'Projects',  icon: FolderOpen      },
   { href: '/activity', label: 'Activity',  icon: Activity        },
+  { href: '/benchmarks', label: 'Benchmarks', icon: Zap          },
 ]
 
 export function BottomNav() {

package/pulse/components/layout/sidebar.tsx

@@ -5,7 +5,7 @@ import { usePathname } from 'next/navigation'
 import {
   LayoutDashboard, FolderOpen, MessageSquare, DollarSign,
   Wrench, Activity, History, CheckSquare, FileText,
-  Brain, Settings, Download, HelpCircle, Moon, Sun, PanelLeftClose, PanelLeft,
+  Brain, Settings, Download, HelpCircle, Moon, Sun, PanelLeftClose, PanelLeft, Zap,
 } from 'lucide-react'
 import { useTheme } from '@/components/theme-provider'
 import { useSidebar } from '@/components/layout/sidebar-context'
@@ -24,6 +24,7 @@ const NAV = [
   { href: '/todos',    label: 'Todos',     icon: CheckSquare     },
   { href: '/plans',    label: 'Plans',     icon: FileText        },
   { href: '/memory',   label: 'Memory',    icon: Brain           },
+  { href: '/benchmarks', label: 'Benchmarks', icon: Zap          },
   { href: '/settings', label: 'Settings',  icon: Settings        },
   { href: '/help',     label: 'Help',      icon: HelpCircle      },
   { href: '/export',   label: 'Export',    icon: Download        },

package/src/core/risk-tier.mjs

@@ -73,8 +73,14 @@ const NETWORK_TOOLS = new Set([
 // ── Shell sub-classifier ────────────────────────────────────────────────
 
 const SHELL_SAFE_RE = [
-  // Inspection / read-only
-  /^\s*(ls|cat|head|tail|less|more|wc|file|stat|tree|find|grep|rg|ag|fd|echo|printf|pwd|whoami|date|which|type|env|printenv|uname|hostname|id|df|du|uptime|free|top|ps|lsof)\b/i,
+  // Inspection / read-only + harmless shell navigation built-ins.
+  // `cd` / `pushd` / `popd` only change the process working directory; if
+  // chained with something dangerous, the multi-segment classifier still
+  // catches the danger (`cd /x && rm -rf .` → SHELL_DANGEROUS).
+  /^\s*(cd|pushd|popd|ls|cat|head|tail|less|more|wc|file|stat|tree|find|grep|rg|ag|fd|echo|printf|pwd|whoami|date|which|type|env|printenv|uname|hostname|id|df|du|uptime|free|top|ps|lsof)\b/i,
+  // mkdir -p / touch are creation primitives but harmless in scope.
+  /^\s*mkdir\s+-p\b/i,
+  /^\s*touch\s/i,
   /^\s*git\s+(status|log|diff|show|branch|tag|remote|stash\s+list|blame|shortlog|describe|rev-parse|ls-files|ls-tree|config\s+--get)\b/i,
   // Test-only invocations
   /^\s*(npm|pnpm|yarn)\s+(test|run\s+test|run\s+lint|list|ls|view|info|outdated)\b/i,

package/src/core/stream-client.mjs

@@ -93,14 +93,23 @@ export class TarangStreamClient {
         };
         if (this.token) headers['Authorization'] = `Bearer ${this.token}`;
 
+        // Abort controller so cancel() can break out of a stalled reader
+        // instead of waiting for the next SSE event to notice _cancelled.
+        this._abort = new AbortController();
+
         let response;
         try {
             response = await fetch(url, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify(body),
+                signal: this._abort.signal,
             });
         } catch (err) {
+            if (err.name === 'AbortError') {
+                yield { type: EVENT_TYPES.STATUS, data: { message: 'Cancelled by user.' } };
+                return;
+            }
             yield { type: EVENT_TYPES.ERROR, data: { message: `Network error: ${err.message}. Check your connection or use --local mode.`, fatal: true } };
             return;
         }
@@ -175,7 +184,15 @@ export class TarangStreamClient {
 
         try {
             while (true) {
-                const { done, value } = await reader.read();
+                let read;
+                try {
+                    read = await reader.read();
+                } catch (err) {
+                    // Aborted via cancel() — treat as a clean end-of-stream.
+                    if (err && (err.name === 'AbortError' || this._cancelled)) break;
+                    throw err;
+                }
+                const { done, value } = read;
                 if (done) break;
 
                 buffer += decoder.decode(value, { stream: true });
@@ -335,6 +352,7 @@ export class TarangStreamClient {
     /** Cancel the current stream. */
     async cancel() {
         this._cancelled = true;
+        // Best-effort backend POST — the stream may already be torn down.
         if (this.currentTaskId) {
             try {
                 await fetch(`${this.baseUrl}/api/cancel/${this.currentTaskId}`, {
@@ -343,6 +361,11 @@ export class TarangStreamClient {
                 });
             } catch { /* best effort */ }
         }
+        // Force the in-flight SSE reader to abort so the REPL returns to the
+        // prompt immediately instead of waiting on a parked reader.read().
+        if (this._abort) {
+            try { this._abort.abort(); } catch {}
+        }
     }
 
     /** Pause the current stream. */

package/src/core/tool-executor.mjs

@@ -91,6 +91,12 @@ export function createToolExecutor({
         '.rs':  (file) => `rustfmt --check "${file}" 2>&1`,
     };
 
+    // tsc --pretty and eslint emit ANSI codes (including background-red
+    // highlights) which bleed when our renderer slices the first 80 chars.
+    // Strip color codes so the stored lint string is always plain text.
+    const ANSI_RE = /\x1b\[[0-9;]*[a-zA-Z]/g;
+    function stripAnsi(s) { return String(s || '').replace(ANSI_RE, ''); }
+
     function autoLint(filePath) {
         const ext = path.extname(filePath);
         const cmdFn = LINT_COMMANDS[ext];
@@ -102,13 +108,14 @@ export function createToolExecutor({
                 timeout: 15_000,
                 cwd: process.cwd(),
                 stdio: ['pipe', 'pipe', 'pipe'],
+                env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1', TERM: 'dumb' },
             });
-            const trimmed = output.trim();
+            const trimmed = stripAnsi(output).trim();
             if (!trimmed) return null;
             return trimmed;
         } catch (err) {
             // Non-zero exit means lint errors found
-            const output = (err.stderr || err.stdout || '').trim();
+            const output = stripAnsi(err.stderr || err.stdout || '').trim();
             if (!output) return null;
             return output;
         }

package/src/onboarding/preflight.mjs

@@ -37,31 +37,44 @@ const FAIL = (s) => `${paint.state.danger('[✗]')} ${s}`;
 
 // ── Individual checks (each returns { status, label, hint? }) ──────────
 
-function checkAuthToken(auth) {
+async function checkAuthAndBackend(auth, { timeoutMs = 2500 } = {}) {
   const creds = auth.loadCredentials();
-  if (creds.token) return { status: 'ok', label: `Auth token` };
-  return { status: 'warn', label: 'Auth token missing', hint: '/login to sign in' };
-}
+  const hasToken = !!creds.token;
+  const url = creds.backendUrl;
 
-function checkProviderKey(auth) {
-  const creds = auth.loadCredentials();
-  if (creds.openRouterKey) return { status: 'ok', label: 'OpenRouter key' };
-  if (creds.anthropicKey)  return { status: 'ok', label: 'Anthropic key' };
-  if (creds.openaiKey)     return { status: 'ok', label: 'OpenAI key' };
-  if (creds.googleKey)     return { status: 'ok', label: 'Google key' };
-  return { status: 'warn', label: 'No model provider key configured', hint: 'set OPENROUTER_API_KEY or run /config' };
-}
+  // No token: just probe whether the backend is reachable so we can hint
+  // /login when it makes sense.
+  if (!hasToken) {
+    const reachable = url ? await ping(url, timeoutMs).catch(() => false) : false;
+    return reachable
+      ? { status: 'warn', label: 'Not signed in · backend ready', hint: '/login to sign in' }
+      : { status: 'warn', label: 'Not signed in · backend offline', hint: '/login once the network is back' };
+  }
 
-async function checkBackend(auth, { timeoutMs = 1500 } = {}) {
-  const creds = auth.loadCredentials();
-  const url = creds.backendUrl;
-  if (!url) return { status: 'warn', label: 'Backend not configured' };
+  // Token present: real authenticated round-trip against /api/user/me.
+  // Three outcomes: valid (200), expired (401/403), unreachable (network).
   try {
-    const reachable = await ping(url, timeoutMs);
-    if (reachable) return { status: 'ok', label: `Backend  ${shorten(url, 48)}` };
-    return { status: 'warn', label: `Backend  ${shorten(url, 48)}`, hint: 'unreachable — check network or start backend' };
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    let resp;
+    try {
+      resp = await fetch(`${url}/api/user/me`, {
+        headers: { 'Authorization': `Bearer ${creds.token}` },
+        signal: ctrl.signal,
+      });
+    } finally { clearTimeout(t); }
+
+    if (resp.ok) {
+      const user = await resp.json().catch(() => null);
+      const who = user?.github_username || user?.email || 'user';
+      return { status: 'ok', label: `Signed in as ${who} · connected` };
+    }
+    if (resp.status === 401 || resp.status === 403) {
+      return { status: 'warn', label: 'Token expired · connected', hint: '/login again to refresh' };
+    }
+    return { status: 'warn', label: `Backend returned ${resp.status}`, hint: 'try again shortly' };
   } catch {
-    return { status: 'warn', label: `Backend  ${shorten(url, 48)}`, hint: 'unreachable' };
+    return { status: 'warn', label: 'Signed in · backend offline', hint: 'check network or try again shortly' };
   }
 }
 
@@ -83,25 +96,32 @@ function checkGit(cwd) {
 function checkLinters(cwd) {
   const present = [];
   const missing = [];
-  for (const [name, kind] of LINTERS) {
-    if (which(name)) present.push({ name, kind });
-    else if (projectUses(cwd, kind)) missing.push({ name, kind });
+  for (const linter of LINTERS) {
+    if (which(linter.bin)) present.push(linter);
+    else if (projectUses(cwd, linter.kind)) missing.push(linter);
   }
   if (present.length === 0 && missing.length === 0) {
     return { status: 'ok', label: 'Linters  none required' };
   }
   if (missing.length === 0) {
-    return { status: 'ok', label: `Linters  ${present.map(p => p.name).join(', ')}` };
+    return { status: 'ok', label: `Linters  ${present.map(p => p.bin).join(', ')}` };
   }
-  const hint = missing.map(m => `/install ${m.name} to enable lint_check for ${m.kind}`).join(' · ');
-  return { status: 'warn', label: `Linter (${missing.map(m => m.name).join(', ')}) not found`, hint };
+  // Honest install command per linter. Falls back to "install via your
+  // package manager" when there is no clean one-liner (e.g. cargo).
+  const hint = missing.map(m => m.install
+    ? `${m.bin}: ${m.install}`
+    : `install ${m.bin} for ${m.kind} support`
+  ).join(' · ');
+  return { status: 'warn', label: `Linter (${missing.map(m => m.bin).join(', ')}) not found`, hint };
 }
 
 const LINTERS = [
-  ['ruff',    'python'],
-  ['eslint',  'javascript'],
-  ['tsc',     'typescript'],
-  ['cargo',   'rust'],
+  { bin: 'ruff',    kind: 'python',     install: 'pip install ruff' },
+  { bin: 'eslint',  kind: 'javascript', install: 'npm i -g eslint' },
+  { bin: 'tsc',     kind: 'typescript', install: 'npm i -g typescript' },
+  // cargo ships with rustup; no clean one-liner — surface the warning
+  // without a misleading "/install" command.
+  { bin: 'cargo',   kind: 'rust',       install: null },
 ];
 
 function projectUses(cwd, kind) {
@@ -252,9 +272,7 @@ export async function runPreflight({ auth, cwd, version, silent = false } = {})
   write('\n' + header + '\n\n');
 
   const checks = [];
-  checks.push(checkAuthToken(auth));
-  checks.push(checkProviderKey(auth));
-  checks.push(await checkBackend(auth));
+  checks.push(await checkAuthAndBackend(auth));
   checks.push(checkGit(cwd));
   checks.push(checkLinters(cwd));
   checks.push(checkProjectMap(cwd));

package/src/terminal/repl.mjs

@@ -24,6 +24,7 @@ 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,
@@ -121,6 +122,7 @@ const session = {
   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 ──
@@ -165,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 ──
@@ -212,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(' · '));
 
@@ -264,7 +255,7 @@ 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`);
   }
@@ -281,6 +272,14 @@ function updateStatusBar() {
  * 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 args = data?.args || {};
@@ -296,6 +295,7 @@ function renderToolCall(data) {
   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 };
 }
 
 /**
@@ -333,10 +333,32 @@ function renderToolResult(data, eventType = 'tool_result') {
                                   : paint.text.dim;
   const duration = formatToolDuration(data);
   const tail = duration ? paint.text.dim(` · ${duration}`) : '';
-  process.stderr.write(`${gutter}${arrow} ${painter(text || 'done')}${tail}\n`);
+  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;
+
+  // Default two-line shape.
+  process.stderr.write(`${gutter}${outcome}\n`);
 
   // Lint warnings stay visible alongside writes.
-  if ((tool === 'write_file' || tool === 'edit_file') && data.lint) {
+  if (hasLint) {
     process.stderr.write(`${gutter}${paint.state.warn('⚠ ' + String(data.lint).split('\n')[0].slice(0, 80))}\n`);
   }
 }
@@ -436,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;
 
@@ -621,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() });
@@ -636,6 +662,7 @@ function renderEvent(event) {
 
     case 'sub_agent_start': {
       stopSpinner();
+      clearPendingHead();
       const agentType = data?.type || 'sub-agent';
       const model = data?.model || '';
       const query = data?.query || '';
@@ -657,6 +684,7 @@ function renderEvent(event) {
 
     case 'sub_agent_complete': {
       stopSpinner();
+      clearPendingHead();
       const agentType = data?.type || 'sub-agent';
       const usage = data?.usage || {};
       const tokens = (usage.input_tokens || 0) + (usage.output_tokens || 0);
@@ -697,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;
     }
 
@@ -773,8 +804,9 @@ function renderEvent(event) {
           success: successOverall,
           filesChanged: session.filesChanged,
           toolCounts: session.toolCounts,
-          subAgents: { ...session.subAgentCounts, savedUsd: session.savedUsd },
-          costUsd: turnCost || session.totalCost,
+          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 }
@@ -873,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
@@ -941,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)')}`);
@@ -1065,8 +1109,8 @@ async function handleCommand(input, ctx) {
         success: true,
         filesChanged: session.filesChanged,
         toolCounts: session.toolCounts,
-        subAgents: { ...session.subAgentCounts, savedUsd: session.savedUsd },
-        costUsd: session.totalCost,
+        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'],
       };
@@ -1378,19 +1422,9 @@ export async function startTerminalRepl() {
 
   const ctx = { auth, toolExecutor, approval, jsonlWriter, sessionMgr, checkpoints };
 
-  // ── Mission Control orbit + status bar ──
-  // Opt-out via KEPLER_STATUS_BAR=0 (debugging) or KEPLER_PLAIN=1 (PRD-055).
-  // status-bar.mjs already no-ops when stdout is not a TTY, but the explicit
-  // env opt-out is useful for debugging escape-sequence noise.
-  const statusBarEnabled = process.env.KEPLER_STATUS_BAR !== '0' && term().isTTY && !term().plain;
-  if (statusBarEnabled) {
-    _orbit = createOrbit();
-    attachOrbit(_orbit);
-    // Always unmount before exit so the terminal scroll region is restored.
-    process.on('beforeExit', unmountStatusBar);
-    process.on('exit',       unmountStatusBar);
-  }
-
+  // ── 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
@@ -1437,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));
@@ -1461,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();
   }
 
@@ -1555,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;
         }

package/src/tools/project-overview.mjs

@@ -8,6 +8,35 @@ import { buildProjectSkeleton } from '../context/skeleton.mjs';
 import { indexDir as getIndexDir } from '../core/paths.mjs';
 
 const RESOURCE_FILE = 'project-resource.json';
+
+/**
+ * Expand "~" and trim surrounding quotes/whitespace. Does NOT unescape shell
+ * meta characters — that is a separate, last-resort step done only if the
+ * literal path does not resolve.
+ */
+function normalizePathInput(p) {
+    let s = String(p || '').trim();
+    // Trim balanced surrounding quotes.
+    if ((s.startsWith('"') && s.endsWith('"')) ||
+        (s.startsWith("'") && s.endsWith("'"))) {
+        s = s.slice(1, -1);
+    }
+    // Tilde expansion (~ or ~/...).
+    if (s === '~' || s.startsWith('~/')) {
+        s = path.join(os.homedir(), s.slice(1));
+    }
+    return s;
+}
+
+/**
+ * Replace common shell escape sequences with their literal characters. Used
+ * as a fallback when the literal path does not resolve — the agent may have
+ * pasted a copy of what they would type at a shell prompt.
+ */
+function unescapeShellPath(p) {
+    return String(p || '').replace(/\\([ \t()&$;'"])/g, '$1');
+}
+
 const LANGUAGE_EXTENSIONS = new Map([
     ['.py', 'Python'],
     ['.js', 'JavaScript'],
@@ -280,6 +309,12 @@ export class ProjectRegistry {
         if (!rawPath) {
             throw new Error('get_project_overview requires a project path');
         }
+
+        // LLM sometimes passes shell-escaped paths ("Tarang\ Orca") or paths
+        // beginning with "~". Normalize defensively so the tool does not bounce
+        // back a "not found" error on a path that's correct apart from quoting.
+        rawPath = normalizePathInput(rawPath);
+
         if (!path.isAbsolute(rawPath)) {
             rawPath = path.resolve(process.cwd(), rawPath);
         }
@@ -288,7 +323,15 @@ export class ProjectRegistry {
         try {
             root = fs.realpathSync(rawPath);
         } catch {
-            throw new Error(`Project path not found: ${rawPath}`);
+            // Try the unescaped variant explicitly so the error message can
+            // tell the agent what it actually attempted.
+            const unescaped = unescapeShellPath(rawPath);
+            if (unescaped !== rawPath) {
+                try { root = fs.realpathSync(unescaped); }
+                catch { throw new Error(`Project path not found: ${rawPath} (also tried ${unescaped})`); }
+            } else {
+                throw new Error(`Project path not found: ${rawPath}`);
+            }
         }
         if (!fs.statSync(root).isDirectory()) {
             throw new Error(`Project path is not a directory: ${root}`);
@@ -377,25 +420,64 @@ export class ProjectRegistry {
         if (!rawPath) {
             if (root) return root;
             if (this.projects.size === 1) return this.resources()[0].root;
-            throw new Error('Path requires project_id when multiple or no projects are registered');
+            // Fall back to the first registered project when the model omits
+            // both path and project_id. Beats throwing on an inferable case.
+            const first = this.resources()[0];
+            if (first) return first.root;
+            throw new Error('No projects registered. Call get_project_overview first.');
         }
 
-        let candidate;
-        if (path.isAbsolute(rawPath)) {
-            candidate = canonicalizeCandidate(path.resolve(rawPath));
-        } else {
+        // LLM frequently passes shell-quoted paths copied from a terminal,
+        // e.g. "Tarang\ Orca/src/app/\(kepler\)/page.tsx". Normalize here so
+        // every tool benefits, not just get_project_overview.
+        rawPath = normalizePathInput(rawPath);
+
+        const buildCandidate = (input) => {
+            if (path.isAbsolute(input)) {
+                return canonicalizeCandidate(path.resolve(input));
+            }
             if (!root) {
-                if (this.projects.size !== 1) {
-                    throw new Error('Relative path requires project_id when multiple or no projects are registered');
+                if (this.projects.size === 1) {
+                    return canonicalizeCandidate(path.resolve(this.resources()[0].root, input));
                 }
-                root = this.resources()[0].root;
+                if (this.projects.size > 1) {
+                    throw new Error('Relative path requires project_id when multiple projects are registered. Pass project_id or use an absolute path.');
+                }
+                throw new Error('No projects registered. Call get_project_overview first.');
             }
-            candidate = canonicalizeCandidate(path.resolve(root, rawPath));
-        }
+            return canonicalizeCandidate(path.resolve(root, input));
+        };
 
-        const containingProject = [...this.projects.values()].find(({ resource }) =>
-            isWithin(resource.root, candidate)
+        let candidate = buildCandidate(rawPath);
+
+        const findContaining = (cand) => [...this.projects.values()].find(({ resource }) =>
+            isWithin(resource.root, cand)
         );
+
+        let containingProject = findContaining(candidate);
+
+        // Two reasons to try the unescaped variant:
+        //   (1) candidate is outside every project root (literal "Tarang\ Orca"
+        //       does not contain a real project), or
+        //   (2) candidate is inside a root but does not exist on disk because
+        //       a path segment like "\(kepler\)" only resolves once unescaped.
+        // We retry once on the unescaped form before raising.
+        const needsRetry = !containingProject ||
+                           (!allowMissing && !fs.existsSync(candidate));
+        if (needsRetry) {
+            const unescaped = unescapeShellPath(rawPath);
+            if (unescaped !== rawPath) {
+                try {
+                    const altCandidate = buildCandidate(unescaped);
+                    const altProject = findContaining(altCandidate);
+                    if (altProject && (allowMissing || fs.existsSync(altCandidate))) {
+                        candidate = altCandidate;
+                        containingProject = altProject;
+                    }
+                } catch { /* fall through to the original error */ }
+            }
+        }
+
         if (!containingProject) {
             throw new Error(`Path is outside registered project roots: ${rawPath}`);
         }
@@ -406,10 +488,21 @@ export class ProjectRegistry {
     }
 
     projectForPath(filePath) {
-        const candidate = canonicalizeCandidate(path.resolve(filePath));
-        return [...this.projects.values()].find(({ resource }) =>
+        const normalized = normalizePathInput(filePath);
+        const candidate = canonicalizeCandidate(path.resolve(normalized));
+        const direct = [...this.projects.values()].find(({ resource }) =>
             isWithin(resource.root, candidate)
-        ) || null;
+        );
+        if (direct) return direct;
+        // Same unescape fallback used in resolvePath.
+        const unescaped = unescapeShellPath(normalized);
+        if (unescaped !== normalized) {
+            const altCandidate = canonicalizeCandidate(path.resolve(unescaped));
+            return [...this.projects.values()].find(({ resource }) =>
+                isWithin(resource.root, altCandidate)
+            ) || null;
+        }
+        return null;
     }
 
     reset() {

package/src/ui/tool-card.mjs

@@ -129,12 +129,20 @@ export function summarizeResult(tool, data) {
       return { text: head || 'ok', tone: 'success' };
     }
 
+    case 'analyze_code': {
+      // Backend returns "filename (N lines, ext)" — the filename already
+      // appears in the card head, so strip it and keep just the metadata.
+      const head = firstOutputLine(data);
+      const m = head.match(/\((\d+)\s+lines?,?\s+([^)]+)\)/);
+      if (m) return { text: `${m[1]} lines · ${m[2].trim()}`, tone: 'success' };
+      return { text: head.slice(0, 80) || 'done', tone: 'success' };
+    }
+
     case 'plan':
     case 'explore':
     case 'verify':
     case 'debug':
-    case 'refactor':
-    case 'analyze_code': {
+    case 'refactor': {
       const head = firstOutputLine(data).slice(0, 100);
       return { text: head || 'done', tone: 'success' };
     }