@asobacloud/nehanda 0.8.0 → 0.9.1

package/README.md

@@ -1,6 +1,6 @@
 # Nehanda Command-Line Interface (`nehanda-cli`)
 
-An agentic terminal REPL and single-process engine built for energy systems research and software development. `nehanda-cli` connects directly to our flagship [Nehanda v3](https://huggingface.co/asoba/nehanda-v3-27b), normalizes multi-OEM energy telemetry through the ODSE protocol, and enforces a governed development workflow across the full research-to-production lifecycle. It also connects to local or cloud-based Ollama models, LM Studio instances, or any OpenAI-compatible API.
+An agentic terminal REPL and single-process engine built for energy systems research and software development. `nehanda-cli` works with Ollama, LM Studio, OpenRouter, Anthropic Claude, ZhipuAI, or any OpenAI-compatible API — local or cloud. It normalizes multi-OEM energy telemetry through the ODSE protocol and enforces a governed development workflow across the full research-to-production lifecycle.
 
 Every conversation turn, tool call, phase transition, and permission check is stored in a local, queryable SQLite database you own, ensuring complete transcripts exist for auditing and debugging.
 
@@ -94,7 +94,7 @@ Local Ollama / LM Studio: pick that provider in `/model`, accept or edit the hos
 
 * **Dynamic Tool Rescue (`[TOOL_CALL]`):** Native support for endpoints that strip OpenAI tool schemas (such as `nehandaMlProxy`). The engine dynamically injects active tool schemas directly into system prompts as `[TOOL_CALL]` blocks, parsing and executing tools locally without server-side function-calling support. Uses `[TOOL_CALL]` delimiters instead of `<tool_call>` XML to prevent vLLM's `--tool-call-parser qwen3_xml` stop-token interception.
 
-* **Deterministic SDLC Workflow:** Enforces a 6-phase state machine (`idle` → `plan` → `implement` → `test` → `verify` → `done`) to prevent unapproved code changes, hallucinated test passes, or unverified implementations.
+* **Deterministic SDLC Workflow:** Enforces a 7-phase state machine (`idle` → `explore` → `planning` → `test` → `implement` → `test` → `verify` → `done`) following the AGENTS.md TDD mandate. Transitions are gated: `planning → implement` is blocked until an approved plan exists and at least one RED behavioral test is recorded; `test → verify` requires all tests passing and safety checkers clean.
 
 * **Interactive Safety Interventions:** When execution checkers flag a command — opening local sockets, inspecting HIL testbed hardware paths, or writing outside the working directory — the engine raises a structured `{ status, reason, risk_score, proposed_remediation }` payload rather than crashing. In the TUI, blocked operations surface a `BlockConfirmMenu` (`[A] Approve for Session | [S] Run in Laya Sandbox | [C] Cancel`) wired directly into the Ink event loop. Session approvals are cached so the same operation is not re-prompted within a session. Headless pipe mode auto-denies without prompting.
 
@@ -102,7 +102,7 @@ Local Ollama / LM Studio: pick that provider in `/model`, accept or edit the hos
 
 * **Runtime Visibility:** `RuntimeHealthMonitor` probes active inference endpoints (1s HEAD request) and checks Laya sidecar liveness before each session. The TUI status header shows active model, endpoint health and latency, sidecar PID, and context usage percentage — so researchers have immediate visual confirmation of whether the target backend is an internal local host or an external cloud endpoint before uploading grid telemetry.
 
-* **Process Legibility:** Every tool call is visible while it runs. Tool-start lines show argument summaries (`⚙ Read(ui.mjs)`, `⚙ Bash(git status)`), a live spinner with plain-English verbs tracks activity between outputs (`⠋ Analyzing…`, `⠙ Reading ui.mjs…`), and tool results carry honest context suffixes (`✓ Read: … (N lines)`, `✓ Bash: … (240ms)`, `✓ Write: … (N chars)`) — never fabricated data. A dim `esc to cancel` hint stays available while a turn runs, and result previews are capped at 120 characters so raw output never floods the screen. Backed by `summarizeToolArgs`, `verbForTool`, `formatToolResultSuffix`, and `TOOL_VERBS` in `lib/ui.mjs`, with a live spinner channel (`bridge.updateSpinner`) in the Ink TUI.
+* **Process Legibility:** Every tool call is visible while it runs. Tool-start lines show argument summaries (`⚙ Read(ui.mjs)`, `⚙ Bash(git status)`), a live spinner with plain-English verbs tracks activity between outputs (`⠋ Analyzing…`, `⠙ Reading ui.mjs…`), and tool results carry honest context suffixes (`✓ Read: … (N lines)`, `✓ Bash: … (240ms)`, `✓ Write: … (N chars)`) — never fabricated data. When a reasoning model (Qwen3, Gemma) is thinking, the spinner shows live token progress (`⠋ Thinking (42 tokens)…`) rather than a frozen screen. Pressing Esc immediately updates the spinner to `Cancelling…` before the in-flight request is torn down. A dim `esc to cancel` hint stays available while a turn runs, and result previews are capped at 120 characters so raw output never floods the screen. Backed by `summarizeToolArgs`, `verbForTool`, `formatToolResultSuffix`, and `TOOL_VERBS` in `lib/ui.mjs`, with a live spinner channel (`bridge.updateSpinner`) in the Ink TUI.
 
 * **Interactive TUI & Pipe Support:** Rich Ink-based TUI (`bin/nehanda-ui.mjs`) for interactive development sessions, with headless pipe-mode support (`bin/agent.mjs`) for acceptance testing and automation.
 
@@ -430,19 +430,23 @@ Numeric values are auto-converted. Changes persist in the local settings databas
 
 ## SDLC Workflow
 
-The engine enforces state transitions across six distinct phases:
+The engine enforces state transitions across seven distinct phases, aligned with the AGENTS.md TDD mandate:
 
-1. **`idle`**: Discovery and triage. Mutating file tools are physically masked out. Safety and analysis tools are available on-demand.
+1. **`idle`**: Discovery and triage. Mutating file tools are available. Safety and analysis tools are available on-demand.
 
-2. **`plan`**: Model formulates success criteria and implementation steps (`EnterPlanMode`). No tools available.
+2. **`explore`**: Codebase exploration only. `lib/explore.mjs` drives this phase — the model uses Glob, Grep, and Read to aggregate file summaries before entering planning. Ends when the model outputs `Exploration complete.`
 
-3. **`implement`**: Code changes applied using file editing and shell execution (`ExitPlanMode`).
+3. **`planning`**: Model formulates a plan using exploration summaries (`EnterPlanMode`). Mutating tools are blocked until a plan is approved. No code changes permitted.
 
-4. **`test`**: Automated test generation and execution (`SubmitImplementation`). **After tests pass, all tools marked `mandatory_in: ["test"]` must be run.** The system prompt enforces this — the model cannot declare success until all mandatory safety checkers pass.
+4. **`test`**: Behavioral test creation and RED confirmation. The model writes tests and runs them to confirm they fail for the diagnosed reason. **Gated:** `planning → implement` is blocked until at least one RED test result is recorded here.
 
-5. **`verify`**: Inspection of test outputs and coverage verification (`SubmitTest`).
+5. **`implement`**: Code changes applied using file editing and shell execution (`ExitPlanMode`). Only reachable after a confirmed RED test exists and a plan is approved.
 
-6. **`done`**: Final sign-off and git commit creation.
+6. **`test`**: Automated test execution to verify GREEN (`SubmitImplementation`). **All tools marked `mandatory_in: ["test"]` must run and pass** before this phase can advance — the system prompt enforces this.
+
+7. **`verify`**: Inspection of test outputs and coverage verification (`SubmitTest`). **Gated:** requires all test results passing and at least one safety checker event recorded.
+
+8. **`done`**: Final sign-off and git commit creation.
 
 ---
 
@@ -494,10 +498,37 @@ node tests/unit/gap4_pinned_compaction_behavioral.mjs
 node tests/unit/ui_legibility_behavioral.mjs
 ```
 
+Run the Ollama, spinner, and Laya behavioral suites:
+
+```bash
+node tests/unit/test-ollama-llm-call-behavioral.mjs
+node tests/unit/test-ollama-permission-prompt-behavioral.mjs
+node tests/unit/laya_warm_load_behavioral.mjs
+node tests/unit/issue22_query_context_behavioral.mjs
+```
+
 ---
 
 ## Changelog
 
+### 0.9.0
+
+- **AGENTS.md SDLC workflow + local issue tracking (`lib/workflow.mjs`, `lib/issues.mjs`, `lib/explore.mjs`):** The orchestrator now enforces the full E-P-C-V-D workflow defined in AGENTS.md — Explore, Plan, Confirm, Code, Validate. A local `.issues/` directory tracks open and closed issues with structured metadata (observed behavior, diagnosis, acceptance criteria). `lib/explore.mjs` drives the EXPLORE phase, aggregating file summaries before entering PLANNING. Closes #15.
+
+- **Generic agent config restored to `~/.config/nehanda` (`lib/settings.mjs`, `scripts/postinstall.mjs`):** Removed the `.aimee` dependency and all references to the legacy agent registry. Agent configuration now lives exclusively at `~/.config/nehanda/agents.json`, consistent with the documented config file locations. Closes #16.
+
+- **Working directory in welcome banner and footer (`bin/nehanda-ui.mjs`):** The TUI banner displayed on startup and the status footer both now show the current working directory, giving researchers immediate confirmation of which project root is active before issuing any commands. Closes #17.
+
+- **Spinner stabilization: AskPrompt, spitfire suppression, null-safe `askHuman` (`bin/nehanda-ui.mjs`):** Fixed three related spinner regressions: (1) the spinner was visible and cycling behind interactive `io.ask` permission prompts, obscuring the question; (2) rapid `bridge.updateSpinner` calls between tool results caused visible label flicker (spitfire); (3) `askHuman` threw on a null `io` reference in headless contexts. Closes #18.
+
+- **Ollama LLM call path: behavioral coverage + documentation (`lib/orchestrate.mjs`, `tests/unit/test-ollama-llm-call-behavioral.mjs`, `docs/MAP.md`):** Full behavioral RED/GREEN test suite for the Ollama call path — `detectOllamaToolSupport` probe logic (capabilities, template, modelfile fields, HTTP error fail-open), native vs. manual tool injection dispatch, `Authorization: Bearer ollama` header, `OLLAMA_BASE_URL` env var resolution, and `buildSystemPrompt` injection format. `docs/MAP.md` documents the full call path contract. Closes #19.
+
+- **Turn-start and probe spinner stabilization (`bin/nehanda-ui.mjs`, `lib/orchestrate.mjs`):** Prior to this fix, the spinner had no label during the gap between turn submission and the first model event — cycling generic `TOOL_VERBS` while Laya intent classification and the Ollama `detectOllamaToolSupport` probe (up to 3 s) ran silently. Fixed by pre-seeding `bridge.updateSpinner('Analyzing')` immediately on submit and `io.spinner.start('Analyzing')` at `runSdlcOpenAICompat` entry. Behavioral coverage in `tests/unit/test-ollama-permission-prompt-behavioral.mjs`. Closes #20.
+
+- **Laya sidecar startup warming (`lib/laya_sidecar.mjs`):** `ensureLayaReady()` now calls `loadLaya()` (`method: 'load'`) instead of `pingLaya()` (`method: 'ping'`). The `ping` path responded immediately without loading model weights, leaving the first user-turn `classifyUserIntent` call to cold-load the 322M-parameter checkpoint mid-turn (200–400 ms stall). `load` invokes `_ensure_loaded()` in `laya_worker.py`, priming both `noul` and `choice` criteria into MPS/CPU RAM before the first turn. Behavioral coverage in `tests/unit/laya_warm_load_behavioral.mjs`. Closes #21.
+
+- **Grounded query context, Ollama `think:false`, reasoning token streaming, instant Esc cancel (`lib/orchestrate.mjs`, `lib/openaiCompat.mjs`, `bin/nehanda-ui.mjs`):** Four improvements to reduce reasoning model overhead and improve cancellation UX: (1) `buildSystemPrompt` appends an explicit `[GROUNDED FACTS]` block (date, cwd, platform, shell) to every phase prompt so models never spend tokens debating their own awareness; (2) `streamOpenAIChatCompletion` now parses `delta.reasoning` and `delta.reasoning_content` SSE fields and updates the spinner live — `⠋ Thinking (42 tokens)…` — rather than sitting frozen during the thinking phase; (3) a `think: false` option is forwarded to the Ollama API request body when `model_config.thinking === false`, disabling chain-of-thought for supported models; (4) `detectOllamaToolSupport` now accepts `rt.signal` composed via `AbortSignal.any([signal, AbortSignal.timeout(3000)])` so Esc cancels the capability probe immediately rather than waiting the full 3 s timeout, and `bridge.abortCurrent` updates the spinner to `Cancelling…` before invoking `controller.abort()`. Behavioral coverage in `tests/unit/issue22_query_context_behavioral.mjs`. Closes #22.
+
 ### 0.8.0
 
 - **Full `/help` + explicit MCP env unset (`lib/slashCommands.mjs`, `bin/nehanda-ui.mjs`):** `/help` lists every command and subcommand (`/key` variants, full `/mcp` surface). Omitting a VALUE no longer silently clears env vars — use `/mcp env unset <server> <NAME>` (or `clear`). Autocomplete stays top-level unless you type `/mcp` or `/key`. Behavioral coverage in `tests/unit/help_commands_behavioral.mjs`. Closes #9.
@@ -541,7 +572,7 @@ node tests/unit/ui_legibility_behavioral.mjs
 ### 0.2.0
 - Jev-Mem memory architecture (System-1 Laya control plane)
 - Dynamic Tool Rescue (`[TOOL_CALL]` delimiter path)
-- Deterministic 6-phase SDLC workflow
+- Deterministic SDLC workflow (expanded to 7 phases in 0.9.0)
 - Multi-provider switching
 
 ---

package/bin/agent.mjs

@@ -1081,7 +1081,10 @@ function resolveModelArg(arg) {
   
   // First, try exact match in hardcoded WIRE map (backward compatibility)
   if (arg.includes('/')) {
-    const [p, m] = arg.split('/', 2)
+    // Split on the FIRST "/" only — the model name may itself contain slashes (#12)
+    const slashIdx = arg.indexOf('/')
+    const p = arg.slice(0, slashIdx)
+    const m = arg.slice(slashIdx + 1)
     
     // Validate provider and model_id are non-empty
     if (!p || !p.trim()) {

package/bin/nehanda-ui.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // nehanda-ui — Ink terminal UI for ona-code
 // Connects directly to nehanda-ml.asoba.co via the in-process ona-code engine.
-// No aimee-server, no HTTP daemon, no cross-repo resolution.
+// Standalone terminal UI, no external HTTP daemon, no cross-repo resolution.
 
 if (process.stdout.isTTY) {
   process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
@@ -28,7 +28,14 @@ import { applyMcpConfig, loadMcpConfig, writeGlobalMcpConfig, readGlobalMcpConfi
 import { getMcpServer, closeAllMcpServers, listMcpServers, mcpListResources } from '../lib/mcp.mjs'
 import { invalidateMcpToolCache } from '../lib/tools.mjs'
 import { saveOpenAiCompatKey, resolveOpenAiCompatKey, saveSecureCredentials, resolveZhipuApiKey } from '../lib/auth.mjs'
-import { TOOL_VERBS, verbForTool, summarizeToolArgs, formatToolResultSuffix } from '../lib/ui.mjs'
+import { TOOL_VERBS, verbForTool, summarizeToolArgs, formatToolResultSuffix, maskSecretAnswer } from '../lib/ui.mjs'
+import {
+  PICKER_THRESHOLD,
+  createAskIdSequencer,
+  groupModelsByVendor,
+  filterModelItems,
+  visibleWindow,
+} from '../lib/modelPicker.mjs'
 import Database from 'better-sqlite3'
 import { ensureLayaReady } from '../lib/laya_sidecar.mjs'
 
@@ -46,6 +53,10 @@ const { default: TerminalRenderer }= await import(`${REPO_ROOT}/node_modules/mar
 
 const e = React.createElement
 
+// Per-question id source for AskPrompt React keys (HP-1a, #10). Module scope:
+// ids only need to be unique for the process lifetime.
+const askIdSeq = createAskIdSequencer()
+
 // ── Asoba 3 Visual Identity ───────────────────────────────────
 const BRAND = {
   accent:   '#455BF1',
@@ -58,9 +69,9 @@ const BRAND = {
 // ── Config paths ─────────────────────────────────────────────
 const NEHANDA_DIR   = path.join(os.homedir(), '.config', 'nehanda')
 const NEHANDA_DB    = path.join(NEHANDA_DIR, 'ona-session.db')
-const AIMEE_DIR     = path.join(os.homedir(), '.config', 'aimee')
-const AGENTS_JSON   = path.join(AIMEE_DIR,   'agents.json')
+const AGENTS_JSON   = path.join(NEHANDA_DIR, 'agents.json')
 const SPLASH_SEEN   = path.join(NEHANDA_DIR, '.splash-seen')
+const LAUNCH_CWD    = process.cwd()
 
 function hasSeenSplash() { try { return fs.existsSync(SPLASH_SEEN) } catch { return false } }
 function markSplashSeen() {
@@ -83,8 +94,15 @@ function readApiKey() {
 
 function writeApiKey(key) {
   const data  = readAgents()
-  const agent = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
-  if (agent) { agent.api_key = key; fs.writeFileSync(AGENTS_JSON, JSON.stringify(data, null, 2), 'utf8') }
+  let agent = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
+  if (!agent) {
+    agent = { name: data.default_agent || 'default' }
+    if (!Array.isArray(data.agents)) data.agents = []
+    data.agents.push(agent)
+    data.default_agent = agent.name
+  }
+  agent.api_key = key
+  fs.writeFileSync(AGENTS_JSON, JSON.stringify(data, null, 2), 'utf8')
 }
 
 // ── Session DB bootstrap ─────────────────────────────────────
@@ -213,7 +231,7 @@ function SplashScreen({ onDone }) {
     e(Box, { marginTop: 1 }, e(Text, { dimColor: true }, 'press any key to continue…')),
   )
 }
-function WelcomeBanner({ model, endpoint }) {
+function WelcomeBanner({ model, endpoint, cwd = LAUNCH_CWD }) {
   let cols = 80; try { cols = process.stdout.columns || 80 } catch {}
   const bw = Math.min(cols - 2, 80)
   const lw = Math.floor(bw * 0.42), rw = bw - lw - 3
@@ -225,8 +243,9 @@ function WelcomeBanner({ model, endpoint }) {
       e(Box, { flexDirection: 'column', width: rw, paddingLeft: 1, paddingY: 1 },
         e(Text, { bold: true, color: BRAND.accent }, 'Configuration'),
         e(Box, { marginTop: 1, flexDirection: 'column' },
-          e(Text, {}, e(Text, { dimColor: true }, 'Model:    '), e(Text, { color: BRAND.lavender, bold: true }, model || '—')),
-          e(Text, {}, e(Text, { dimColor: true }, 'Endpoint: '), e(Text, { dimColor: true }, endpoint || '—')),
+          e(Text, {}, e(Text, { dimColor: true }, 'Model:     '), e(Text, { color: BRAND.lavender, bold: true }, model || '—')),
+          e(Text, {}, e(Text, { dimColor: true }, 'Endpoint:  '), e(Text, { dimColor: true }, endpoint || '—')),
+          e(Text, {}, e(Text, { dimColor: true }, 'Directory: '), e(Text, { dimColor: true }, cwd || LAUNCH_CWD)),
         ),
         e(Box, { marginTop: 1 }, e(Text, { dimColor: true }, 'Type /help for commands')),
       ),
@@ -287,6 +306,9 @@ function InputArea({ onSubmit, isLoading }) {
 }
 function AskPrompt({ question, onAnswer, onCancel }) {
   const [value, setValue] = React.useState('')
+  // Defense-in-depth for HP-1a (#10): if this instance ever re-renders with a
+  // new question (fiber reuse), the typed value must not carry over.
+  React.useEffect(() => { setValue('') }, [question])
   useInput((_input, key) => { if (key.escape) onCancel() })
   return e(Box, { flexDirection: 'column' },
     e(Box, { marginLeft: 1 }, e(Text, { dimColor: true }, question)),
@@ -294,7 +316,124 @@ function AskPrompt({ question, onAnswer, onCancel }) {
       e(TextInput, { value, onChange: setValue, onSubmit: React.useCallback(v => onAnswer(v.trim()), [onAnswer]) })),
     e(Box, { marginLeft: 1 }, e(Text, { dimColor: true }, 'Esc cancel')))
 }
+// ── Model Picker (large lists, #10 / HP-2) ───────────────────
+// Three views: vendor GROUPS → windowed BROWSE within a vendor →
+// type-to-filter SEARCH across every discovered model.
+// Digits jump rows, '/' opens search, Esc steps back.
+function ModelPicker({ title, items, onSelect, onCancel }) {
+  const groups = React.useMemo(() => groupModelsByVendor(items), [items])
+  const [view, setView] = React.useState('groups')   // 'groups' | 'browse' | 'search'
+  const [groupIdx, setGroupIdx] = React.useState(0)
+  const [browseIdx, setBrowseIdx] = React.useState(0)
+  const [filter, setFilter] = React.useState('')
+  const [searchIdx, setSearchIdx] = React.useState(0)
+
+  const browseModels = view === 'browse' && groups[groupIdx] ? groups[groupIdx].models : []
+  const searchResults = React.useMemo(() => filterModelItems(items, filter), [items, filter])
+  const prevView = React.useRef('groups')
+
+  const jump = (setter, list, n) => {
+    if (!isNaN(n) && n >= 1 && n <= list.length) setter(n - 1)
+  }
+
+  useInput((input, key) => {
+    if (view === 'search') {
+      // TextInput owns printable chars + Enter (its onSubmit); arrows pass through.
+      if (key.escape) {
+        if (filter) { setFilter(''); setSearchIdx(0) }
+        else { setView(prevView.current); setSearchIdx(0) }
+      } else if (key.upArrow)   { setSearchIdx(i => (i - 1 + searchResults.length) % searchResults.length) }
+      else if (key.downArrow) { setSearchIdx(i => (i + 1) % searchResults.length) }
+      return
+    }
+    if (key.escape) {
+      if (view === 'browse') setView('groups')
+      else onCancel()
+      return
+    }
+    if (input === '/') { prevView.current = view; setView('search'); setFilter(''); setSearchIdx(0); return }
+    if (view === 'groups') {
+      if (key.upArrow)   { setGroupIdx(i => (i - 1 + groups.length) % groups.length); return }
+      if (key.downArrow) { setGroupIdx(i => (i + 1) % groups.length); return }
+      if (key.return) {
+        const g = groups[groupIdx]
+        if (!g) return
+        if (g.isCustom) { onSelect(g.models[0]); return }
+        setBrowseIdx(0); setView('browse')
+        return
+      }
+      jump(setGroupIdx, groups, parseInt(input, 10))
+    } else if (view === 'browse') {
+      if (key.upArrow)   { setBrowseIdx(i => (i - 1 + browseModels.length) % browseModels.length); return }
+      if (key.downArrow) { setBrowseIdx(i => (i + 1) % browseModels.length); return }
+      if (key.return)    { const m = browseModels[browseIdx]; if (m) onSelect(m); return }
+      const win = visibleWindow(browseModels, browseIdx)
+      const shown = win.visible
+      const n = parseInt(input, 10)
+      if (!isNaN(n) && n >= 1 && n <= shown.length) {
+        const item = shown[n - 1]
+        const abs = browseModels.indexOf(item)
+        if (abs !== -1) setBrowseIdx(abs)
+      }
+    }
+  })
+
+  const row = (item, i, cursor) => e(Box, { key: String(item.id ?? i), flexDirection: 'column' },
+    e(Box, {}, e(Text, { color: cursor ? BRAND.accent : undefined }, cursor ? '❯ ' : '  '),
+      e(Text, { color: BRAND.lavender }, `${i + 1}. `),
+      e(Text, { bold: true, color: cursor ? BRAND.accent : undefined }, item.label)),
+    e(Box, { marginLeft: 5 }, e(Text, { dimColor: true }, item.desc)))
+  const hiddenHints = win => e(Box, { key: 'hints', flexDirection: 'column' },
+    win.hiddenAbove ? e(Text, { dimColor: true }, `  ↑ ${win.hiddenAbove} more above`) : null,
+    win.hiddenBelow ? e(Text, { dimColor: true }, `  ↓ ${win.hiddenBelow} more below`) : null)
+
+  let body
+  if (view === 'groups') {
+    body = e(Box, { marginTop: 1, flexDirection: 'column' },
+      ...groups.map((g, i) => row(g, i, i === groupIdx)),
+      e(Box, { marginTop: 1 }, e(Text, { dimColor: true },
+        `↑↓/1–${Math.min(9, groups.length)} vendor · Enter open · / search all · Esc cancel`)))
+  } else if (view === 'browse') {
+    const win = visibleWindow(browseModels, browseIdx)
+    body = e(Box, { marginTop: 1, flexDirection: 'column' },
+      e(Text, { dimColor: true }, `${groups[groupIdx].label} — ${browseModels.length} models`),
+      ...win.visible.map((m, i) => row(m, win.start + i, win.start + i === browseIdx)),
+      hiddenHints(win),
+      e(Box, { marginTop: 1 }, e(Text, { dimColor: true },
+        '↑↓ navigate · Enter select · / search all · Esc back')))
+  } else {
+    const win = visibleWindow(searchResults, searchIdx)
+    const handleSearchSubmit = v => {
+      const item = searchResults[searchIdx]
+      if (item) onSelect(item)
+    }
+    body = e(Box, { marginTop: 1, flexDirection: 'column' },
+      e(Box, { paddingX: 1 }, e(Text, { color: BRAND.accent }, '/'),
+        e(TextInput, { value: filter, onChange: v => { setFilter(v); setSearchIdx(0) }, onSubmit: handleSearchSubmit })),
+      searchResults.length
+        ? e(Box, { marginTop: 1, flexDirection: 'column' },
+            ...win.visible.map((m, i) => row(m, win.start + i, win.start + i === searchIdx)),
+            hiddenHints(win))
+        : e(Text, { dimColor: true }, '  (no matches)'),
+      e(Box, { marginTop: 1 }, e(Text, { dimColor: true },
+        'type to filter · ↑↓ select · Enter confirm · Esc clear/back')))
+  }
+
+  return e(Box, { flexDirection: 'column', marginLeft: 1 },
+    e(Text, { bold: true, color: BRAND.accent }, title),
+    body)
+}
+
+// Wrapper (no hooks): large catalogs (e.g. OpenRouter's hundreds of models)
+// switch to the grouped/filterable picker instead of a flat scroll list (HP-2, #10).
 function SelectMenu({ title, items, onSelect, onCancel }) {
+  if (items.length > PICKER_THRESHOLD) {
+    return e(ModelPicker, { title, items, onSelect, onCancel })
+  }
+  return e(SelectMenuFlat, { title, items, onSelect, onCancel })
+}
+
+function SelectMenuFlat({ title, items, onSelect, onCancel }) {
   const [idx, setIdx] = React.useState(0)
   useInput((input, key) => {
     if (key.escape)    { onCancel(); return }
@@ -356,13 +495,17 @@ function BlockConfirmMenu({ payload, onDecide }) {
       e(Text, {}, ' Cancel')))
 }
 
-function TokenFooter({ calls, model }) {
+function TokenFooter({ calls, model, cwd = LAUNCH_CWD }) {
   const cols = process.stdout.columns || 80
   return e(Box, { flexDirection: 'column' },
     e(Text, { dimColor: true }, '─'.repeat(cols)),
     e(Box, { flexDirection: 'row', paddingX: 1, justifyContent: 'space-between' },
       e(Text, { dimColor: true }, `calls ${calls}`),
-      e(Text, {}, e(Text, { dimColor: true }, 'model: '), e(Text, { color: BRAND.lavender }, model || '—')),
+      e(Box, { flexDirection: 'row' },
+        e(Text, {}, e(Text, { dimColor: true }, 'model: '), e(Text, { color: BRAND.lavender }, model || '—')),
+        e(Text, { dimColor: true }, '  '),
+        e(Text, {}, e(Text, { dimColor: true }, 'dir: '), e(Text, { dimColor: true }, cwd || LAUNCH_CWD)),
+      ),
       e(Text, { dimColor: true }, '? /help  ^C exit')))
 }
 
@@ -384,7 +527,8 @@ function App({ bridge }) {
     const ag = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
     return { model: ag?.model || 'nehanda-rag-synthesis-27b', endpoint: ag?.endpoint || 'https://nehanda-ml.asoba.co/v1' }
   })
-  const lastCtrlCRef = React.useRef(0)
+  const lastCtrlCRef     = React.useRef(0)
+  const lastSpinLabelRef = React.useRef(null)  // #18: retain last explicit label to prevent spitfire between tool calls
   const bannerRef    = React.useRef({ kind: 'banner' })
   const historyItems = React.useMemo(() => [bannerRef.current, ...finalized], [finalized])
 
@@ -396,8 +540,12 @@ function App({ bridge }) {
     bridge.endAssistant   = msg  => { setFinalized(p => [...p, msg]); setStreaming(null); setCallCount(c => c + 1) }
     bridge.clearMessages  = ()   => { setFinalized([]); setStreaming(null); setClearGen(g => g + 1) }
     bridge.setLoading     = v    => setIsLoading(v)
-    bridge.updateSpinner  = text => setSpinLabel(text)
-    bridge.ask    = q     => new Promise(resolve => setAskState({ question: q, resolve }))
+    bridge.updateSpinner  = text => { if (text !== null) lastSpinLabelRef.current = text; setSpinLabel(text) }
+    // HP-1a (#10): unique id per question — AskPrompt is keyed by it, so every
+    // new wizard question remounts with an EMPTY input (no key carry-over).
+    // opts.secret → the persisted transcript line is masked (HP-1b).
+    bridge.ask    = (q, opts) => new Promise(resolve =>
+      setAskState({ id: askIdSeq.next(), question: q, secret: !!(opts && opts.secret), resolve }))
     bridge.select = (t,i) => new Promise(resolve => setSelectState({ title: t, items: i, resolve }))
     bridge.confirmBlock = payload => new Promise(resolve => setBlockState({ payload, resolve }))
     bridge.exit   = ()    => { exit() }
@@ -409,7 +557,10 @@ function App({ bridge }) {
   }, [bridge, exit])
 
   const handleAnswer = React.useCallback(answer => {
-    if (askState?.resolve) { setFinalized(p => [...p, { role: 'system', text: askState.question + ' ' + answer }]); askState.resolve(answer) }
+    // HP-1b (#10): secret answers persist masked to transcript history; the
+    // wizard still receives the raw answer via resolve().
+    const shown = askState?.secret ? maskSecretAnswer(answer) : answer
+    if (askState?.resolve) { setFinalized(p => [...p, { role: 'system', text: `${askState.question} ${shown}`.trim() }]); askState.resolve(answer) }
     setAskState(null)
   }, [askState])
   const handleAskCancel = React.useCallback(() => { askState?.resolve(null); setAskState(null) }, [askState])
@@ -444,18 +595,25 @@ function App({ bridge }) {
   return e(Box, { flexDirection: 'column' },
     e(Static, { items: historyItems, key: clearGen },
       (item, i) => item.kind === 'banner'
-        ? e(WelcomeBanner, { key: 'banner', model: modelInfo.model, endpoint: modelInfo.endpoint })
+        ? e(WelcomeBanner, { key: 'banner', model: modelInfo.model, endpoint: modelInfo.endpoint, cwd: LAUNCH_CWD })
         : e(MessageView,   { key: String(i), msg: item })),
     streaming ? e(MessageView, { msg: { role: 'assistant', ...streaming } }) : null,
-    (isLoading && (!streaming || !streaming.text)) || spinLabel ? e(Spinner, { label: spinLabel || undefined }) : null,
+    // #18 fix 1: !askState hides Spinner while AskPrompt is shown (permission prompt visible).
+    // #18 fix 2: effectiveSpinLabel uses lastSpinLabelRef fallback when spinLabel=null during
+    //   active loading, preventing snap-back to a random rotating verb between tool calls.
+    (() => {
+      const effectiveSpinLabel = spinLabel ?? (isLoading ? lastSpinLabelRef.current : null)
+      return (!askState && ((isLoading && (!streaming || !streaming.text)) || effectiveSpinLabel))
+        ? e(Spinner, { label: effectiveSpinLabel || undefined }) : null
+    })(),
     askState
-      ? e(AskPrompt, { question: askState.question, onAnswer: handleAnswer, onCancel: handleAskCancel })
+      ? e(AskPrompt, { key: askState.id, question: askState.question, onAnswer: handleAnswer, onCancel: handleAskCancel })
       : blockState
         ? e(BlockConfirmMenu, { payload: blockState.payload, onDecide: handleBlock })
         : selectState
           ? e(SelectMenu, { title: selectState.title, items: selectState.items, onSelect: handleSelect, onCancel: handleSelectCancel })
           : e(InputArea, { onSubmit: bridge.onSubmit, isLoading }),
-    e(TokenFooter, { calls: callCount, model: modelInfo.model }))
+    e(TokenFooter, { calls: callCount, model: modelInfo.model, cwd: LAUNCH_CWD }))
 }
 
 // ── Diff executor ─────────────────────────────────────────────
@@ -492,7 +650,7 @@ function stripThink(text) {
 async function runUiConfigureWizard(bridge, opts = {}) {
   try {
     const result = await runConfigureWizard({
-      ask: q => bridge.ask(q),
+      ask: (q, opts) => bridge.ask(q, opts),
       select: (title, items) => bridge.select(title, items),
       notify: msg => bridge.addMessage({ role: 'system', text: `  ${msg}` }),
       resolveExistingKey: async (preset) => {
@@ -508,12 +666,16 @@ async function runUiConfigureWizard(bridge, opts = {}) {
       },
       persist: async (cfg) => {
         const data = readAgents()
-        const ag = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
-        if (ag) {
-          ag.model = cfg.model
-          ag.endpoint = cfg.endpoint
-          if (cfg.provider === 'nehanda' && cfg.apiKey) ag.api_key = cfg.apiKey
+        let ag = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
+        if (!ag) {
+          ag = { name: data.default_agent || 'default' }
+          if (!Array.isArray(data.agents)) data.agents = []
+          data.agents.push(ag)
+          data.default_agent = ag.name
         }
+        ag.model = cfg.model
+        ag.endpoint = cfg.endpoint
+        if (cfg.provider === 'nehanda' && cfg.apiKey) ag.api_key = cfg.apiKey
         fs.writeFileSync(AGENTS_JSON, JSON.stringify(data, null, 2), 'utf8')
         runtimeSettings.model_config = cfg.model_config || modelConfigFromAgent(
           { model: cfg.model, endpoint: cfg.endpoint },
@@ -589,7 +751,7 @@ async function handleCommand(cmd, bridge) {
     }
 
     if (!sub || !KEY_TO_PRESET[sub]) {
-      const answer = await bridge.ask('New Nehanda API key:')
+      const answer = await bridge.ask('New Nehanda API key:', { secret: true })
       if (!answer) return
       try {
         writeApiKey(answer)
@@ -601,7 +763,7 @@ async function handleCommand(cmd, bridge) {
 
     const presetId = KEY_TO_PRESET[sub]
     const inlineValue = parts.slice(2).join(' ').trim()
-    const answer = inlineValue || await bridge.ask(`New ${sub} API key:`)
+    const answer = inlineValue || await bridge.ask(`New ${sub} API key:`, { secret: true })
     if (!answer) return
 
     try {
@@ -833,8 +995,12 @@ bridge.onSubmit = async (text) => {
   if (text.startsWith('/')) { await handleCommand(text, bridge); return }
 
   bridge.setLoading(true)
+  bridge.updateSpinner('Analyzing')
   const controller = new AbortController()
-  bridge.abortCurrent = () => controller.abort()
+  bridge.abortCurrent = () => {
+    bridge.updateSpinner('Cancelling…')   // #22: immediate UI feedback before abort propagates
+    controller.abort()
+  }
   let lastPartial = ''
 
   try {
@@ -861,7 +1027,7 @@ bridge.onSubmit = async (text) => {
       bareMode:        false,
       // Project instructions sourced from nehanda's own loadInstructions() (Ona.md),
       // matching bin/agent.mjs. Does NOT read agents.json exec_system_prompt — that
-      // field belongs to aimee and was silently reintroducing conflicting tool-call
+      // legacy field was silently reintroducing conflicting tool-call
       // syntax (<tool_call><name>...) that fights orchestrate.mjs's [TOOL_CALL] format.
       onaInstructions: onaInstructionsContent || null,
       // Esc/Ctrl+C abort — must reach fetch / Anthropic stream (issue #7).

package/lib/configureProvider.mjs

@@ -107,7 +107,7 @@ export async function discoverModelsForPreset(preset, opts = {}) {
  * Interactive configure wizard.
  *
  * @param {object} deps
- * @param {(q: string) => Promise<string>} deps.ask
+ * @param {(q: string, opts?: { secret?: boolean }) => Promise<string>} deps.ask
  * @param {(title: string, items: object[]) => Promise<object|null>} deps.select
  * @param {(msg: string) => void} [deps.notify]
  * @param {(ctx: {preset, host, apiKey}) => Promise<{success, models?, error?}>} [deps.discover]
@@ -155,7 +155,8 @@ export async function runConfigureWizard(deps, opts = {}) {
       ])
       if (!choice) return null
       if (choice.id === 'replace') {
-        const entered = await ask(`${preset.label} API key:`)
+        // {secret:true} → the TUI masks this answer in transcript history (HP-1b, #10)
+        const entered = await ask(`${preset.label} API key:`, { secret: true })
         if (!entered) return null
         apiKey = entered.trim()
         keyDirty = true
@@ -163,7 +164,7 @@ export async function runConfigureWizard(deps, opts = {}) {
         apiKey = existing
       }
     } else {
-      const entered = await ask(`${preset.label} API key:`)
+      const entered = await ask(`${preset.label} API key:`, { secret: true })
       if (!entered) return null
       apiKey = entered.trim()
       keyDirty = true

package/lib/explore.mjs

@@ -0,0 +1,109 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+// Directories to skip entirely during exploration
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.issues', 'dist', 'build', 'tmp', '.tmp',
+  'coverage', '.nyc_output', '__pycache__', '.venv', 'venv',
+  '.next', '.nuxt', 'out',
+])
+
+// Documentation files receive highest priority (read first)
+const DOC_FILENAMES = new Set([
+  'README.md', 'readme.md', 'README', 'readme',
+  'CONTRIBUTING.md', 'CONTRIBUTING', 'ARCHITECTURE.md', 'ARCHITECTURE',
+  'AGENTS.md', 'GEMINI.md', 'CHANGELOG.md', 'CHANGES.md',
+  'DESIGN.md', 'OVERVIEW.md', 'ONBOARDING.md', 'SETUP.md',
+  'MAP.md', 'RUNBOOK.md', 'OPERATIONS.md', 'SPECIFICATION.md', 'SPEC.md',
+])
+
+// Secondary documentation: anything under docs/ or .docs/
+const DOC_DIRS = new Set(['docs', '.docs', 'documentation', 'doc'])
+
+/**
+ * Scans a repository directory and returns files in documentation-first order.
+ *
+ * Priority order:
+ *   1. Root-level named documentation files (README.md, CONTRIBUTING.md, etc.)
+ *   2. All Markdown files inside docs/ subdirectories
+ *   3. Root-level *.md files not already listed
+ *   4. Configuration files (package.json, pyproject.toml, etc.)
+ *   5. All other source files (alphabetical, depth-first)
+ *
+ * @param {string} cwd - The repository root to scan
+ * @returns {string[]} - Absolute paths in exploration priority order
+ */
+export function getDocPrioritizedFiles(cwd) {
+  const abs = path.resolve(cwd)
+
+  // Tier 1: High-priority named root documentation files
+  const tier1 = []
+  for (const name of DOC_FILENAMES) {
+    const f = path.join(abs, name)
+    if (fs.existsSync(f) && fs.statSync(f).isFile()) {
+      tier1.push(f)
+    }
+  }
+
+  // Collect all files in the repo (excluding SKIP_DIRS)
+  const allFiles = []
+  function walk(dir) {
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) walk(path.join(dir, entry.name))
+      } else if (entry.isFile()) {
+        allFiles.push(path.join(dir, entry.name))
+      }
+    }
+  }
+  walk(abs)
+
+  const tier1Set = new Set(tier1)
+
+  // Tier 2: Markdown files inside docs/ directories
+  const tier2 = allFiles.filter(f => {
+    if (tier1Set.has(f)) return false
+    const rel = path.relative(abs, f)
+    const parts = rel.split(path.sep)
+    return parts.length > 1 && DOC_DIRS.has(parts[0]) && f.endsWith('.md')
+  })
+
+  const tier2Set = new Set(tier2)
+
+  // Tier 3: Remaining root-level *.md files
+  const tier3 = allFiles.filter(f => {
+    if (tier1Set.has(f) || tier2Set.has(f)) return false
+    const rel = path.relative(abs, f)
+    return !rel.includes(path.sep) && f.endsWith('.md')
+  })
+
+  const tier3Set = new Set(tier3)
+
+  // Tier 4: Config files
+  const CONFIG_NAMES = new Set([
+    'package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+    'pyproject.toml', 'setup.py', 'setup.cfg', 'Cargo.toml',
+    '.env.example', '.env.sample', 'tsconfig.json', 'jest.config.js',
+    'jest.config.mjs', 'eslint.config.js', '.eslintrc.js', '.eslintrc.json',
+  ])
+  const tier4 = allFiles.filter(f => {
+    if (tier1Set.has(f) || tier2Set.has(f) || tier3Set.has(f)) return false
+    const base = path.basename(f)
+    return CONFIG_NAMES.has(base)
+  })
+
+  const tier4Set = new Set(tier4)
+
+  // Tier 5: Everything else
+  const tier5 = allFiles.filter(f =>
+    !tier1Set.has(f) && !tier2Set.has(f) && !tier3Set.has(f) && !tier4Set.has(f)
+  )
+
+  return [...tier1, ...tier2, ...tier3, ...tier4, ...tier5]
+}