@asobacloud/nehanda 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # Nehanda Command-Line Interface (`nehanda-cli`)
 
-An agentic terminal REPL and single-process engine built for governed AI deep research and software development. `nehanda-cli` connects directly to our flagship [Nehanda v3](https://huggingface.co/asoba/nehanda-v3-27b), as well as 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` 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.
 
 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.
 
@@ -83,12 +83,18 @@ To connect to an Ollama instance running on your network:
 
 * **In-Process Engine:** Executes turns directly inside the process via `runUserTurn`, eliminating separate server daemons or background HTTP relays.
 
-* **Jev-Mem Memory Architecture:** Every turn, a System-1 control plane ([Laya](https://huggingface.co/convaiinnovations/laya)) classifies observations into a multi-relational memory graph (semantic / temporal / causal / entity edges), then adaptively retrieves evidence before each model call. System-2 receives a compact canonical header + retrieved evidence + last 2 turns, not a raw transcript — cutting prefill 70–85% on long sessions. See [Jev-Mem Architecture](#jev-mem-architecture) below.
+* **ODSE Energy Normalization:** `lib/energy-middleware.mjs` intercepts MCP tool results from energy data servers and automatically normalizes them to the ODS-E protocol before the model sees the payload. OEM brand is resolved from the MCP server name (e.g. `energy-huawei` → `huawei`) or inferred by field-signature fingerprinting across 20+ OEM schemas (Huawei FusionSolar, Enphase, SolarEdge, Fronius, Sungrow, SMA, Eskom, and others). Multi-channel SCADA arrays and inverter state records render as box-drawing terminal tables with column headers and row-count summaries rather than raw JSON dumps.
+
+* **Jev-Mem Memory Architecture:** Every turn, a System-1 control plane ([Laya](https://huggingface.co/convaiinnovations/laya)) classifies observations into a multi-relational memory graph (semantic / temporal / causal / entity edges), then adaptively retrieves evidence before each model call. System-2 receives a compact canonical header + retrieved evidence + last 2 turns, not a raw transcript — cutting prefill 70–85% on long sessions. Domain invariants (ODSE schema mappings, asset capacity limits, simulation bounds) are pinned in the `pinned_context` table and reattached verbatim before every System-2 prompt, preventing model drift and hallucinated parameters across arbitrarily long research sessions. See [Jev-Mem Architecture](#jev-mem-architecture) below.
 
 * **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.
 
+* **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.
+
+* **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.
+
 * **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.
 
 * **Multi-Provider Switching:** Seamlessly switch between Nehanda 27B, local LM Studio, Ollama instances over LAN, Anthropic Claude, or any OpenAI-compatible API using `/model`.
@@ -103,10 +109,62 @@ To connect to an Ollama instance running on your network:
 
 ---
 
+## ODSE Energy Normalization
+
+`lib/energy-middleware.mjs` sits between MCP tool responses and the model. When an energy data MCP server returns a payload, the middleware resolves the OEM brand and normalizes the data to the [ODS-E](https://ona-protocol.org) schema via `lib/scripts/odse-transform.py` before the model sees it. This means the model always works with a consistent normalized schema regardless of which inverter brand, BESS, or SCADA system the data originated from.
+
+### OEM Detection
+
+Brand resolution happens in two passes:
+
+1. **Name-based:** The MCP server name is parsed for a known OEM key. `energy-huawei`, `mcp-solaredge`, `power-sungrow-v2` all resolve correctly. Any prefix before the OEM segment is stripped.
+2. **Payload fingerprinting:** If the server name doesn't resolve, field signatures are matched against known schemas — e.g. `{ inverter_state, run_state }` → Huawei FusionSolar; `{ end_at, wh_del, devices_reporting }` → Enphase Envoy; `{ data: { telemetries } }` → SolarEdge.
+
+If neither pass identifies the OEM, the payload is returned unchanged (pass-through).
+
+### Supported OEMs
+
+Huawei FusionSolar, Enphase Envoy, SolarEdge, Fronius, Solarman, SMA, Solis, Sungrow / iSolarCloud, Sungrow BESS / PowerTitan, BYD BESS, Fimer / AuroraVision, SolaxCloud, Eskom (portal, AMR, NRS049), Vestas, Siemens Gamesa, Nordex, Terraco, and generic CSV.
+
+### MCP Server Naming Convention
+
+Name energy MCP servers with the OEM as a segment in the server name:
+
+```json
+{
+  "mcpServers": {
+    "energy-huawei": { "command": "...", "args": ["..."] },
+    "energy-solaredge": { "command": "...", "args": ["..."] }
+  }
+}
+```
+
+No additional configuration is required — normalization is automatic.
+
+### `odse-transform.py` Output Formats
+
+The transform script accepts a `--format` flag for direct use:
+
+```bash
+echo '<payload>' | python3 lib/scripts/odse-transform.py --source huawei --format table
+echo '<payload>' | python3 lib/scripts/odse-transform.py --source solaredge --format ndjson
+echo '<payload>' | python3 lib/scripts/odse-transform.py --source sungrow --format summary
+```
+
+| Format | Output | Default when |
+|---|---|---|
+| `table` | Box-drawing ASCII table with column headers and row count | stdout is a TTY |
+| `ndjson` | One JSON object per line | stdout is piped |
+| `summary` | Metadata header (`rows`, `shape`, `source`) + JSON array | explicit flag only |
+
+---
+
 ## Jev-Mem Architecture
 
 `nehanda-cli` implements the memory architecture from **"System-One-Controlled Agentic Memory for Efficient AI Agents"** (Jiang, Li & Li, UT Dallas — [arXiv:2609.23986](https://arxiv.org/abs/2609.23986)). The core insight: the frequent, structured decisions of memory management — typing, relation judgment, retrieval routing, sufficiency assessment — don't need an autoregressive LLM. They need a fast, calibrated System-1 model.
 
+In the context of energy systems research, this matters directly: long multi-step sessions involving SCADA data ingestion, grid simulation, and iterative code generation accumulate enough context to trigger compaction. Standard sliding-window compaction indiscriminately discards ODSE schema mappings, asset capacity limits, and simulation bounds alongside routine tool outputs — causing the model to hallucinate parameters on subsequent turns. Jev-Mem's pinned context layer prevents this: domain invariants are stored in `pinned_context` and reattached verbatim before every System-2 prompt, surviving arbitrarily many compaction cycles.
+
 The System-1 control plane is [**Laya**](https://huggingface.co/convaiinnovations/laya) — a 421M-parameter, non-autoregressive decision model (open weights, Apache 2.0) that answers typed questions in a single forward pass (~33 ms on GPU, ~200 ms on CPU). It never generates text, so there is nothing to parse and nothing to hallucinate.
 
 ```
@@ -135,6 +193,7 @@ Observation (user / tool / assistant turn)
         │
         ▼
 ┌── SYSTEM 2 PROMPT ────────────────────────────────────────────┐
+│  [PINNED DOMAIN INVARIANTS]  (ODSE schema, asset specs, ...)  │
 │  [CANONICAL SYSTEM 1 STATE]  (task_status, file_target, ...)  │
 │  [RETRIEVED EVIDENCE]  (top-K memories, not raw transcript)   │
 │  last 2 turns + last failed tool result                       │
@@ -164,7 +223,7 @@ On first startup, `lib/scripts/ensure-laya-env.sh` creates a dedicated venv at `
 
 ### Memory plane (SQLite)
 
-The memory plane extends the existing `memories` table and adds `memory_edges` and `laya_jev_state`. All data lives in the same local SQLite database as the rest of the session state (`~/.config/nehanda/ona-session.db`).
+The memory plane extends the existing `memories` table and adds `memory_edges`, `laya_jev_state`, and `pinned_context`. All data lives in the same local SQLite database as the rest of the session state (`~/.config/nehanda/ona-session.db`).
 
 | Table | Purpose |
 |---|---|
@@ -172,6 +231,7 @@ The memory plane extends the existing `memories` table and adds `memory_edges` a
 | `memories_fts` | FTS5 index over memory content for lexical anchor retrieval |
 | `memory_edges` | Multi-relational edges — same node pair may have independent semantic, temporal, causal, and entity edges |
 | `laya_jev_state` | Session control block: `task_status`, `file_target`, `escalation_risk`, `confidence_score` |
+| `pinned_context` | Session-scoped domain invariants keyed by string — ODSE schema mappings, asset specs, simulation bounds. Never distilled by compaction; reattached verbatim before every System-2 prompt. |
 
 ---
 
@@ -388,6 +448,7 @@ Session state is persisted locally at `~/.config/nehanda/ona-session.db`. Key ta
 * `memories`: Jev-Mem canonical node store with overlapping type scores and entity provenance.
 * `memory_edges`: Multi-relational graph edges (semantic / temporal / causal / entity).
 * `laya_jev_state`: System-1 session control block (task_status, file_target, escalation_risk).
+* `pinned_context`: Session-scoped domain invariants (ODSE schema mappings, asset specs, simulation bounds) that survive compaction unchanged.
 
 ---
 
@@ -414,10 +475,27 @@ node tests/unit/compact_jev_behavioral.mjs
 node tests/unit/orchestrate_jev_hotpath_behavioral.mjs
 ```
 
+Run the UX improvement behavioral suites:
+
+```bash
+node tests/unit/gap1_runtime_visibility_behavioral.mjs
+node tests/unit/gap2_output_formatting_behavioral.mjs
+node tests/unit/gap3_safety_intervention_behavioral.mjs
+node tests/unit/gap4_pinned_compaction_behavioral.mjs
+```
+
 ---
 
 ## Changelog
 
+### 0.4.0
+- **Runtime Visibility (`lib/modelDiscovery.mjs`, `lib/ui.mjs`):** New `RuntimeHealthMonitor` class probes active inference endpoints (1s HEAD request, Kubernetes readiness pattern) and checks Laya sidecar liveness via `pgrep`. `renderStatusHeader` and `renderModelSwitchNotice` added to `lib/ui.mjs` — the TUI now shows active model, endpoint health + latency, sidecar PID, and context usage percentage after startup and on every `/model` switch.
+- **Structured Output Formatting (`lib/ui.mjs`, `lib/scripts/odse-transform.py`):** `formatToolResult` now detects JSON array payloads from tool responses and renders them as `cli-table3` box-drawing tables with column headers and row-count summaries (capped at 10 rows with overflow note), falling back to the plain-text preview for non-array content. `odse-transform.py` gains a `--format table|ndjson|summary` flag; defaults to `table` when stdout is a TTY and `ndjson` when piped.
+- **Interactive Safety Interventions (`lib/bashguard.mjs`, `lib/tools.mjs`, `bin/nehanda-ui.mjs`):** `validateBashCommand` now returns a structured `{ status, reason, risk_score, proposed_remediation }` payload instead of a flat string. When the TUI is active, blocked commands raise a `BlockConfirmMenu` (`[A] Approve for Session | [S] Run in Laya Sandbox | [C] Cancel`) wired directly into the Ink event loop — no blocking readline, no crash. Session approvals are cached in-memory via `cacheSessionApproval` so the same operation is not re-prompted within a session. Safety checker scripts (`python-safety-checker.py`, `shell-safety-checker.sh`) emit the structured JSON payload to stderr on exit 1 so the TUI can surface them identically. Headless pipe mode auto-denies without prompting.
+- **Pinned Context Preservation (`lib/store.mjs`, `lib/compact.mjs`):** New `pinned_context` table (schema v3) stores session-scoped invariants — ODSE schema mappings, asset specs, simulation bounds — keyed by string. `compactConversation` and `buildJevCollapseSummary` exclude pinned blocks from the distillation summariser and reattach them verbatim in the `collapse_commit` payload. `compactWithJev` prepends pinned blocks before the canonical System-1 header in every System-2 prompt, ensuring domain rules survive arbitrarily long sessions.
+- Added `cli-table3@0.6.5` as a production dependency.
+- Fixed dead `has_any_assert` variable in `lib/scripts/audit-code-integrity.py` (ruff F841).
+
 ### 0.3.0
 - Published as `@asobacloud/nehanda` on npm — install with `npm install -g @asobacloud/nehanda`
 - Laya System-1 venv provisioning moved to `npm install` time via `scripts/postinstall.mjs` — CLI starts instantly on every subsequent launch

package/bin/nehanda-ui.mjs

@@ -345,8 +345,45 @@ function SelectMenu({ title, items, onSelect, onCancel }) {
     e(Box, { marginTop: 1 }, e(Text, { dimColor: true },
       '↑↓ navigate · Enter select' + (items.length <= 9 ? ` · 1–${items.length} jump` : '') + ' · Esc cancel')))
 }
+
+// ── Block Confirmation Menu (Gap 3) ──────────────────────────
+// Raised when bashguard or a safety-checker script blocks a command.
+// Resolves the Promise with 'approve' | 'sandbox' | 'cancel'.
+function BlockConfirmMenu({ payload, onDecide }) {
+  useInput((input, key) => {
+    const ch = input.toLowerCase()
+    if (key.escape || ch === 'c') { onDecide('cancel'); return }
+    if (ch === 'a') { onDecide('approve'); return }
+    if (ch === 's') { onDecide('sandbox'); return }
+  })
+
+  const riskColor = payload.risk_score === 'high' ? BRAND.red : BRAND.coral
+  const remediation = (payload.proposed_remediation || []).join(', ')
+
+  return e(Box, { flexDirection: 'column', borderStyle: 'single', borderColor: BRAND.red, marginY: 1 },
+    e(Box, { paddingX: 1, paddingY: 0 },
+      e(Text, { bold: true, color: BRAND.red }, '⛔ Command Blocked')),
+    e(Box, { paddingX: 1 },
+      e(Text, { dimColor: true }, 'Reason:      '),
+      e(Text, { wrap: 'wrap' }, payload.reason || '(unknown)')),
+    e(Box, { paddingX: 1 },
+      e(Text, { dimColor: true }, 'Risk:        '),
+      e(Text, { color: riskColor, bold: true }, (payload.risk_score || 'unknown').toUpperCase())),
+    remediation
+      ? e(Box, { paddingX: 1 },
+          e(Text, { dimColor: true }, 'Remediation: '),
+          e(Text, { dimColor: true }, remediation))
+      : null,
+    e(Box, { paddingX: 1, marginTop: 1 },
+      e(Text, { bold: true, color: BRAND.accent }, '[A]'),
+      e(Text, {}, ' Approve for Session  '),
+      e(Text, { bold: true, color: BRAND.lavender }, '[S]'),
+      e(Text, {}, ' Run in Laya Sandbox  '),
+      e(Text, { bold: true, color: BRAND.dim }, '[C]'),
+      e(Text, {}, ' Cancel')))
+}
+
 function TokenFooter({ calls, model }) {
-  let cols = 80; try { cols = process.stdout.columns || 80 } catch {}
   return e(Box, { flexDirection: 'column' },
     e(Text, { dimColor: true }, '─'.repeat(cols)),
     e(Box, { flexDirection: 'row', paddingX: 1, justifyContent: 'space-between' },
@@ -365,6 +402,7 @@ function App({ bridge }) {
   const [isLoading,  setIsLoading]  = React.useState(false)
   const [askState,   setAskState]   = React.useState(null)
   const [selectState, setSelectState] = React.useState(null)
+  const [blockState,  setBlockState]  = React.useState(null)
   const [callCount,  setCallCount]  = React.useState(0)
   const [modelInfo,  setModelInfo]  = React.useState(() => {
     const data = readAgents()
@@ -385,6 +423,7 @@ function App({ bridge }) {
     bridge.setLoading     = v    => setIsLoading(v)
     bridge.ask    = q     => new Promise(resolve => setAskState({ question: q, 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() }
     bridge.refreshModel = () => {
       const data = readAgents()
@@ -403,6 +442,14 @@ function App({ bridge }) {
     setSelectState(null)
   }, [selectState])
   const handleSelectCancel = React.useCallback(() => { selectState?.resolve(null); setSelectState(null) }, [selectState])
+  const handleBlock = React.useCallback(decision => {
+    if (blockState?.resolve) {
+      const label = decision === 'approve' ? '✓ Approved for session' : decision === 'sandbox' ? '⚙ Running in sandbox' : '✗ Cancelled'
+      setFinalized(p => [...p, { role: 'system', text: `  ${label}` }])
+      blockState.resolve(decision)
+    }
+    setBlockState(null)
+  }, [blockState])
 
   useInput((input, key) => {
     if (key.escape) { if (isLoading && bridge.abortCurrent) bridge.abortCurrent(); return }
@@ -427,9 +474,11 @@ function App({ bridge }) {
     isLoading && (!streaming || !streaming.text) ? e(Spinner, {}) : null,
     askState
       ? e(AskPrompt, { question: askState.question, onAnswer: handleAnswer, onCancel: handleAskCancel })
-      : selectState
-        ? e(SelectMenu, { title: selectState.title, items: selectState.items, onSelect: handleSelect, onCancel: handleSelectCancel })
-        : e(InputArea, { onSubmit: bridge.onSubmit, isLoading }),
+      : 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 }))
 }
 
@@ -780,6 +829,7 @@ bridge.onSubmit = async (text) => {
       println(msg)            { if (!aborted) bridge.addMessage({ role: 'system', text: '  ' + msg }) },
       spinner:                { start() {}, stop() {} },
       ask:                    bridge.ask,
+      confirmBlock:           payload => bridge.confirmBlock(payload),
       onToolStart(name)       { if (!aborted) bridge.addMessage({ role: 'system', text: `  ⚙ ${name}` }) },
       onToolResult(name, c, err) {
         if (aborted) return

package/lib/bashguard.mjs

@@ -3,7 +3,15 @@ import path from 'node:path'
 /**
  * Validate a bash command before execution.
  * Blocks destructive commands everywhere and filesystem writes outside cwd.
- * Returns { ok: true } or { ok: false, reason: string }.
+ *
+ * Returns { ok: true } on success, or a structured blocked payload:
+ * {
+ *   ok: false,
+ *   status: 'blocked',
+ *   reason: string,         — human-readable description
+ *   risk_score: 'high'|'medium',
+ *   proposed_remediation: string[]
+ * }
  */
 export function validateBashCommand(cmd, cwd) {
   // Split on pipes, semicolons, &&, || to check each segment
@@ -21,6 +29,24 @@ export function validateBashCommand(cmd, cwd) {
   return { ok: true }
 }
 
+/**
+ * Build a structured blocked payload.
+ * @param {string} reason - Human-readable block reason
+ * @param {'high'|'medium'} riskScore
+ * @param {string[]} [remediation]
+ */
+function blocked(reason, riskScore = 'high', remediation = []) {
+  return {
+    ok: false,
+    status: 'blocked',
+    reason,
+    risk_score: riskScore,
+    proposed_remediation: remediation.length
+      ? remediation
+      : ['review_command', 'sandbox'],
+  }
+}
+
 function checkSegment(seg, cwd) {
   const lower = seg.toLowerCase()
   const tokens = seg.split(/\s+/)
@@ -33,28 +59,28 @@ function checkSegment(seg, cwd) {
     for (const t of rmTargets) {
       const resolved = resolvePath(t, cwd)
       if (isDangerousPath(resolved, cwd)) {
-        return { ok: false, reason: `rm -rf targeting dangerous path: ${t}` }
+        return blocked(`rm -rf targeting dangerous path: ${t}`, 'high', ['review_command'])
       }
     }
   }
 
   // git destructive operations
-  if (/\bgit\s+checkout\s+--/.test(seg)) return { ok: false, reason: 'git checkout -- discards changes (destructive)' }
-  if (/\bgit\s+reset\s+--hard/.test(seg)) return { ok: false, reason: 'git reset --hard (destructive)' }
-  if (/\bgit\s+push\s+(-f|--force)/.test(seg)) return { ok: false, reason: 'git push --force (destructive)' }
-  if (/\bgit\s+clean\s+-[fd]/.test(seg)) return { ok: false, reason: 'git clean (destructive)' }
-  if (/\bgit\s+branch\s+-D\b/.test(seg)) return { ok: false, reason: 'git branch -D (destructive)' }
-  if (/\bgit\s+stash\s+drop/.test(seg)) return { ok: false, reason: 'git stash drop (destructive)' }
-  if (/\bgit\s+reflog\s+expire/.test(seg)) return { ok: false, reason: 'git reflog expire (destructive)' }
+  if (/\bgit\s+checkout\s+--/.test(seg)) return blocked('git checkout -- discards changes (destructive)', 'high', ['review_command', 'use_git_stash'])
+  if (/\bgit\s+reset\s+--hard/.test(seg)) return blocked('git reset --hard (destructive)', 'high', ['review_command', 'use_git_stash'])
+  if (/\bgit\s+push\s+(-f|--force)/.test(seg)) return blocked('git push --force (destructive)', 'high', ['review_command'])
+  if (/\bgit\s+clean\s+-[fd]/.test(seg)) return blocked('git clean (destructive)', 'high', ['review_command'])
+  if (/\bgit\s+branch\s+-D\b/.test(seg)) return blocked('git branch -D (destructive)', 'medium', ['review_command'])
+  if (/\bgit\s+stash\s+drop/.test(seg)) return blocked('git stash drop (destructive)', 'medium', ['review_command'])
+  if (/\bgit\s+reflog\s+expire/.test(seg)) return blocked('git reflog expire (destructive)', 'high', ['review_command'])
 
   // System-level destructive commands
-  if (/\bmkfs\b/.test(lower)) return { ok: false, reason: 'mkfs (destructive)' }
-  if (/\bdd\s+if=/.test(lower)) return { ok: false, reason: 'dd (destructive)' }
-  if (/\bformat\b/.test(lower) && /\/dev\//.test(seg)) return { ok: false, reason: 'format device (destructive)' }
-  if (/\bkillall\b/.test(lower)) return { ok: false, reason: 'killall (destructive)' }
-  if (/\bkill\s+-9\b/.test(seg)) return { ok: false, reason: 'kill -9 (destructive)' }
-  if (/\bsudo\b/.test(lower)) return { ok: false, reason: 'sudo not permitted' }
-  if (/\bsu\s/.test(lower)) return { ok: false, reason: 'su not permitted' }
+  if (/\bmkfs\b/.test(lower)) return blocked('mkfs (destructive)', 'high', ['review_command'])
+  if (/\bdd\s+if=/.test(lower)) return blocked('dd (destructive)', 'high', ['review_command'])
+  if (/\bformat\b/.test(lower) && /\/dev\//.test(seg)) return blocked('format device (destructive)', 'high', ['review_command'])
+  if (/\bkillall\b/.test(lower)) return blocked('killall (destructive)', 'high', ['review_command', 'sandbox'])
+  if (/\bkill\s+-9\b/.test(seg)) return blocked('kill -9 (destructive)', 'medium', ['review_command', 'sandbox'])
+  if (/\bsudo\b/.test(lower)) return blocked('sudo not permitted', 'high', ['review_command', 'sandbox'])
+  if (/\bsu\s/.test(lower)) return blocked('su not permitted', 'high', ['review_command'])
 
   // ── Category 2: Filesystem writes outside cwd ──
 
@@ -65,7 +91,7 @@ function checkSegment(seg, cwd) {
     if (target === '/dev/null') continue
     const resolved = resolvePath(target, cwd)
     if (!isUnderCwd(resolved, cwd)) {
-      return { ok: false, reason: `Write redirect to path outside working directory: ${target}` }
+      return blocked(`Write redirect to path outside working directory: ${target}`, 'medium', ['review_command', 'sandbox'])
     }
   }
 
@@ -75,7 +101,7 @@ function checkSegment(seg, cwd) {
     for (const t of teeArgs) {
       const resolved = resolvePath(t, cwd)
       if (!isUnderCwd(resolved, cwd)) {
-        return { ok: false, reason: `tee to path outside working directory: ${t}` }
+        return blocked(`tee to path outside working directory: ${t}`, 'medium', ['review_command', 'sandbox'])
       }
     }
   }
@@ -88,7 +114,7 @@ function checkSegment(seg, cwd) {
         const target = args[args.length - 1]
         const resolved = resolvePath(target, cwd)
         if (!isUnderCwd(resolved, cwd)) {
-          return { ok: false, reason: `${cmd} target outside working directory: ${target}` }
+          return blocked(`${cmd} target outside working directory: ${target}`, 'medium', ['review_command', 'sandbox'])
         }
       }
     }
@@ -101,7 +127,7 @@ function checkSegment(seg, cwd) {
       for (const a of args) {
         const resolved = resolvePath(a, cwd)
         if (!isUnderCwd(resolved, cwd)) {
-          return { ok: false, reason: `${cmd} outside working directory: ${a}` }
+          return blocked(`${cmd} outside working directory: ${a}`, 'medium', ['review_command', 'sandbox'])
         }
       }
     }
@@ -113,7 +139,7 @@ function checkSegment(seg, cwd) {
     for (const a of sedArgs) {
       const resolved = resolvePath(a, cwd)
       if (!isUnderCwd(resolved, cwd)) {
-        return { ok: false, reason: `sed -i on file outside working directory: ${a}` }
+        return blocked(`sed -i on file outside working directory: ${a}`, 'medium', ['review_command', 'sandbox'])
       }
     }
   }
@@ -126,7 +152,7 @@ function checkSegment(seg, cwd) {
         if (/^[0-7]+$/.test(a) || /^[a-z]+:[a-z]+$/i.test(a)) continue // skip mode/owner args
         const resolved = resolvePath(a, cwd)
         if (!isUnderCwd(resolved, cwd)) {
-          return { ok: false, reason: `${cmd} -R outside working directory: ${a}` }
+          return blocked(`${cmd} -R outside working directory: ${a}`, 'medium', ['review_command', 'sandbox'])
         }
       }
     }

package/lib/compact.mjs

@@ -1,5 +1,5 @@
 import { appendEntry } from './transcript.mjs'
-import { withTransaction, getLayaJevState, upsertLayaJevState } from './store.mjs'
+import { withTransaction, getLayaJevState, upsertLayaJevState, getPinnedContextBlocks } from './store.mjs'
 import { runHooks } from './hookplane.mjs'
 import { extractCanonicalState } from './laya.mjs'
 import {
@@ -41,10 +41,13 @@ export async function compactConversation(db, rt, summarize, log) {
 
   await runHooks(db, hookRt, 'PreCompact', { trigger: 'manual' })
 
+  // Fetch pinned blocks — these are never passed to the distillation summariser.
+  const pinnedBlocks = getPinnedContextBlocks(db, rt.sessionId)
+
   log('Compacting conversation (Jev-Mem)...')
   let summary
   try {
-    summary = await buildJevCollapseSummary(db, rt)
+    summary = await buildJevCollapseSummary(db, rt, pinnedBlocks)
   } catch {
     const text = entries.map(e => {
       try {
@@ -57,6 +60,10 @@ export async function compactConversation(db, rt, summarize, log) {
     }).filter(Boolean).join('\n')
     log('Jev compact failed; falling back to summarizer.')
     summary = await summarize(text)
+    // Reattach pinned blocks verbatim even on fallback path.
+    if (pinnedBlocks.length) {
+      summary += '\n\n' + formatPinnedBlocksSection(pinnedBlocks)
+    }
   }
 
   withTransaction(db, () => {
@@ -66,6 +73,7 @@ export async function compactConversation(db, rt, summarize, log) {
       compacted_count: entries.length,
       compacted_from_sequence: startSeq,
       jev: true,
+      pinned_keys: pinnedBlocks.map(b => b.key),
     })
 
     db.prepare(
@@ -79,7 +87,7 @@ export async function compactConversation(db, rt, summarize, log) {
   return summary
 }
 
-async function buildJevCollapseSummary(db, rt) {
+async function buildJevCollapseSummary(db, rt, pinnedBlocks = []) {
   const paths = extractRecentFilePaths(db, rt.sessionId)
   const tail = transcriptTailText(db, rt.sessionId)
   const state = await extractCanonicalState(tail, paths, rt.layaOpts || {})
@@ -89,7 +97,11 @@ async function buildJevCollapseSummary(db, rt) {
     conversationId: rt.conversationId,
     layaOpts: rt.layaOpts || {},
   })
-  return formatCanonicalHeader(state) + '\n' + formatEvidenceBlock(retrieved.evidence)
+  let summary = formatCanonicalHeader(state) + '\n' + formatEvidenceBlock(retrieved.evidence)
+  if (pinnedBlocks.length) {
+    summary += '\n\n' + formatPinnedBlocksSection(pinnedBlocks)
+  }
+  return summary
 }
 
 export function formatCanonicalHeader(layaState) {
@@ -117,6 +129,21 @@ export function formatEvidenceBlock(evidence = []) {
   return ['[RETRIEVED EVIDENCE]', ...lines, '--------------------------------------------------'].join('\n')
 }
 
+/**
+ * Serialise pinned context blocks into a labelled section that is appended
+ * verbatim to the collapse_commit summary — never distilled.
+ */
+export function formatPinnedBlocksSection(blocks = []) {
+  if (!blocks.length) return ''
+  const lines = ['[PINNED DOMAIN INVARIANTS]']
+  for (const b of blocks) {
+    lines.push(`-- ${b.key} --`)
+    lines.push(String(b.content || ''))
+  }
+  lines.push('--------------------------------------------------')
+  return lines.join('\n')
+}
+
 /**
  * Rough token estimate (~4 chars/token) for behavioral budgets.
  */
@@ -194,13 +221,22 @@ function isFailedToolContent(content) {
 }
 
 /**
- * Build System-2 message list: canonical header + evidence + last 2 turns + last failed tool.
+ * Build System-2 message list: pinned blocks + canonical header + evidence + last 2 turns + last failed tool.
  * Tool payloads in the trailing window are capped so prefill stays bounded.
+ * pinnedBlocks rows come from getPinnedContextBlocks — they are prepended verbatim before the
+ * canonical header so they are never truncated by the trailing-message window.
  */
 export function compactWithJev(messages, layaState, evidence = [], opts = {}) {
   const header = formatCanonicalHeader(layaState)
   const ev = formatEvidenceBlock(evidence)
-  const preamble = `${header}\n${ev}`
+  const pinnedBlocks = opts.pinnedBlocks || []
+
+  // Pinned invariants are injected first — outside the truncation budget.
+  const pinnedSection = formatPinnedBlocksSection(pinnedBlocks)
+  const preamble = pinnedSection
+    ? `${pinnedSection}\n\n${header}\n${ev}`
+    : `${header}\n${ev}`
+
   const trailing = selectTrailingMessages(messages, {
     turns: opts.turns ?? 2,
     includeLastFailedTool: opts.includeLastFailedTool !== false,
@@ -292,7 +328,10 @@ export async function buildJevSystem2Messages(db, rt, messages, opts = {}) {
       layaOpts,
     })
 
-    return compactWithJev(messages, state, retrieved.evidence, { turns })
+    // Pinned blocks are always reattached — they survive every compaction cycle.
+    const pinnedBlocks = getPinnedContextBlocks(db, rt.sessionId)
+
+    return compactWithJev(messages, state, retrieved.evidence, { turns, pinnedBlocks })
   } catch {
     // Resilience: rolling window fallback — never crash the CLI
     return selectTrailingMessages(messages, { turns, includeLastFailedTool: true })

package/lib/modelDiscovery.mjs

@@ -3,6 +3,103 @@
  * Queries Ollama API to discover available models
  */
 
+import http from 'node:http'
+import https from 'node:https'
+import { execSync } from 'node:child_process'
+
+// ── Runtime Health Monitor ────────────────────────────────────
+
+/**
+ * Probes active inference endpoints and the Laya sidecar process to give the
+ * TUI a live picture of backend health before each turn.
+ *
+ * Design follows the Kubernetes readiness-probe pattern: lightweight HEAD
+ * requests with a hard 1-second timeout, so a crashed local Ollama instance
+ * surfaces immediately rather than stalling the REPL.
+ */
+export class RuntimeHealthMonitor {
+  constructor(config = {}) {
+    this.activeModel = config.defaultModel || 'nehanda-rag-synthesis-27b'
+    this.sidecarScript = config.sidecarScript || 'lib/scripts/laya_worker.py'
+  }
+
+  /**
+   * Non-blocking HEAD probe of a local inference endpoint.
+   * Cloud-managed endpoints (no URL or `cloud:` scheme) are assumed ONLINE
+   * with zero latency — they have their own availability guarantees.
+   */
+  async probeEndpoint(targetUrl) {
+    if (!targetUrl || targetUrl.startsWith('cloud:')) {
+      return { status: 'ONLINE', latencyMs: 0, isLocal: false }
+    }
+
+    const start = Date.now()
+    try {
+      const url = new URL(targetUrl)
+      const reqModule = url.protocol === 'https:' ? https : http
+
+      return await new Promise((resolve) => {
+        const req = reqModule.request(url, { method: 'HEAD', timeout: 1000 }, (res) => {
+          resolve({
+            status: res.statusCode < 400 ? 'ONLINE' : 'DEGRADED',
+            latencyMs: Date.now() - start,
+            isLocal: true,
+          })
+        })
+        req.on('error', () => resolve({ status: 'OFFLINE', latencyMs: -1, isLocal: true }))
+        req.on('timeout', () => {
+          req.destroy()
+          resolve({ status: 'TIMEOUT', latencyMs: -1, isLocal: true })
+        })
+        req.end()
+      })
+    } catch {
+      return { status: 'INVALID_URL', latencyMs: -1, isLocal: true }
+    }
+  }
+
+  /**
+   * Checks liveness of the local Laya sidecar worker process via pgrep.
+   * Returns { active: true, pid: string } or { active: false, pid: null }.
+   */
+  checkSidecarHealth() {
+    try {
+      const pidStr = execSync(`pgrep -f "${this.sidecarScript}"`, { encoding: 'utf8' }).trim()
+      if (pidStr) {
+        return { active: true, pid: pidStr.split('\n')[0] }
+      }
+    } catch {
+      // pgrep exits 1 when no match — not an error
+    }
+    return { active: false, pid: null }
+  }
+
+  /**
+   * Assembles a full runtime status telemetry payload for the UI renderer.
+   * Runs endpoint probe and sidecar check concurrently.
+   */
+  async getRuntimeStatus(endpointUrl, usedTokens = 0, maxTokens = 128000) {
+    const [endpointHealth, sidecarHealth] = await Promise.all([
+      this.probeEndpoint(endpointUrl),
+      Promise.resolve(this.checkSidecarHealth()),
+    ])
+
+    const ctxPercentage = maxTokens > 0 ? Math.round((usedTokens / maxTokens) * 100) : 0
+
+    return {
+      model: this.activeModel,
+      endpoint: endpointUrl || 'Cloud Managed API',
+      endpointStatus: endpointHealth.status,
+      latency: endpointHealth.latencyMs,
+      isLocal: endpointHealth.isLocal,
+      sidecarStatus: sidecarHealth.active
+        ? `ACTIVE (PID ${sidecarHealth.pid})`
+        : 'INACTIVE',
+      contextUsage: `${usedTokens}/${maxTokens} (${ctxPercentage}%)`,
+    }
+  }
+}
+
 /**
  * Discover available models from an Ollama server
  * @param {string} baseUrl - Base URL of the Ollama server (e.g., "http://localhost:11434")

package/lib/permissions.mjs

@@ -1,3 +1,33 @@
+/** §5.12 — permission evaluation (deny > ask > allow > defaultMode). */
+
+// ── Session-scoped approval cache ────────────────────────────
+//
+// Allows a user who selects [A] in BlockConfirmMenu to suppress subsequent
+// prompts for the same operation within one REPL session.  Keys are arbitrary
+// strings — callers use a stable pattern like `Bash:sudo` or `PythonSafetyChecker`.
+//
+const _sessionApprovals = new Map()
+
+/**
+ * Record a single-session approval for key.
+ * @param {string} sessionId
+ * @param {string} key  — e.g. 'Bash:sudo' or 'ShellSafetyChecker'
+ */
+export function cacheSessionApproval(sessionId, key) {
+  const bucket = _sessionApprovals.get(sessionId) || new Set()
+  bucket.add(key)
+  _sessionApprovals.set(sessionId, bucket)
+}
+
+/**
+ * Return true if a prior approval for key exists in this session.
+ * @param {string} sessionId
+ * @param {string} key
+ */
+export function hasSessionApproval(sessionId, key) {
+  return _sessionApprovals.get(sessionId)?.has(key) ?? false
+}
+
 /** §5.12 — permission evaluation (deny > ask > allow > defaultMode). */
 export function evaluatePermission(permissions, toolName, _toolInput, phase) {
   const p = permissions || { defaultMode: 'default' }

package/lib/scripts/audit-code-integrity.py

@@ -189,7 +189,6 @@ class CodeIntegrityAuditor:
 
         patched_targets = []
         has_substantive_assert = False
-        has_any_assert = False
         is_internal_mocked = False
         is_live_aws = False
 
@@ -230,7 +229,6 @@ class CodeIntegrityAuditor:
 
             # Inspect Assert statements
             if isinstance(subnode, ast.Assert):
-                has_any_assert = True
                 assert_str = ast.unparse(subnode.test) if hasattr(ast, "unparse") else ""
                 # Substantive assertions check equality, subscripting, in-comparisons, or value bounds
                 if any(op in assert_str for op in ["==", "!=", " in ", ">", "<", "[", "]"]):
@@ -240,7 +238,7 @@ class CodeIntegrityAuditor:
             if isinstance(subnode, ast.Expr) and isinstance(subnode.value, ast.Call):
                 call_str = ast.unparse(subnode.value.func) if hasattr(ast, "unparse") else ""
                 if "assert_called" in call_str:
-                    has_any_assert = True
+                    pass  # mock assertion noted but does not count as substantive outcome check
 
         # Flag tests with zero substantive outcome assertions (Assertion Theater)
         if not has_substantive_assert:

package/lib/scripts/odse-transform.py

@@ -4,14 +4,21 @@ odse-transform.py — ODSE energy normalization bridge for nehanda-cli.
 
 Reads a raw OEM energy payload from stdin, transforms it to ODS-E
 normalized JSON using the pip-installed `odse` package, and writes
-the result to stdout as a JSON array.
+the result to stdout in the requested format.
 
 Usage:
     echo '<payload>' | python3 odse-transform.py --source huawei
     echo '<payload>' | python3 odse-transform.py --source solaredge --asset-id SITE-001
+    echo '<payload>' | python3 odse-transform.py --source huawei --format ndjson
+    echo '<payload>' | python3 odse-transform.py --source huawei --format summary
+
+Output formats (--format):
+    table   — box-drawing ASCII table with column headers (default when TTY)
+    ndjson  — one JSON object per line (default when piped / non-TTY)
+    summary — metadata header (rows, shape, source) then JSON array
 
 Exit codes:
-    0  — success, normalized JSON written to stdout
+    0  — success, output written to stdout
     1  — unknown source / transform error (caller should pass payload through)
     2  — usage / import error
 """
@@ -21,6 +28,66 @@ import json
 import sys
 
 
+def _is_tty() -> bool:
+    """Return True when stdout is an interactive terminal."""
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def _render_table(records: list, source: str) -> str:
+    """Render records as a plain-text box-drawing table."""
+    if not records:
+        return f"[odse-transform] 0 rows from source '{source}'"
+
+    headers = list(records[0].keys()) if isinstance(records[0], dict) else ["value"]
+    rows: list[list[str]] = []
+    for rec in records:
+        if isinstance(rec, dict):
+            rows.append([str(rec.get(h, "")) for h in headers])
+        else:
+            rows.append([str(rec)])
+
+    # Column widths: max of header length and widest cell value (capped at 40).
+    col_widths = [
+        min(40, max(len(h), max((len(r[i]) for r in rows), default=0)))
+        for i, h in enumerate(headers)
+    ]
+
+    def _row(cells: list[str], widths: list[int]) -> str:
+        return "│ " + " │ ".join(c[:w].ljust(w) for c, w in zip(cells, widths)) + " │"
+
+    sep_top = "┌─" + "─┬─".join("─" * w for w in col_widths) + "─┐"
+    sep_mid = "├─" + "─┼─".join("─" * w for w in col_widths) + "─┤"
+    sep_bot = "└─" + "─┴─".join("─" * w for w in col_widths) + "─┘"
+
+    lines = [
+        sep_top,
+        _row(headers, col_widths),
+        sep_mid,
+        *[_row(r, col_widths) for r in rows],
+        sep_bot,
+        f"  {len(records)} row{'s' if len(records) != 1 else ''} — source: {source}",
+    ]
+    return "\n".join(lines)
+
+
+def _render_ndjson(records: list) -> str:
+    """One JSON object per line (newline-delimited JSON)."""
+    return "\n".join(json.dumps(rec, default=str) for rec in records)
+
+
+def _render_summary(records: list, source: str) -> str:
+    """Metadata header followed by the full JSON array."""
+    if not records:
+        shape = "0 rows × 0 cols"
+    elif isinstance(records[0], dict):
+        shape = f"{len(records)} rows × {len(records[0])} cols"
+    else:
+        shape = f"{len(records)} rows × 1 col"
+
+    header = json.dumps({"rows": len(records), "shape": shape, "source": source}, default=str)
+    return header + "\n" + json.dumps(records, default=str)
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description="Transform OEM energy data to ODS-E")
     parser.add_argument(
@@ -39,9 +106,29 @@ def main() -> int:
         default=None,
         help="Optional timezone for timestamp conversion (e.g. Africa/Johannesburg)",
     )
+    parser.add_argument(
+        "--format",
+        default=None,
+        choices=["table", "ndjson", "summary"],
+        dest="fmt",
+        help=(
+            "Output format. 'table' renders a box-drawing ASCII table; "
+            "'ndjson' emits one JSON object per line; "
+            "'summary' emits a metadata header then the JSON array. "
+            "Defaults to 'table' when stdout is a TTY, otherwise 'ndjson'."
+        ),
+    )
     args = parser.parse_args()
 
-    # Read full payload from stdin
+    # Resolve effective format: explicit flag > TTY detection > ndjson.
+    if args.fmt is not None:
+        fmt = args.fmt
+    elif _is_tty():
+        fmt = "table"
+    else:
+        fmt = "ndjson"
+
+    # Read full payload from stdin.
     try:
         payload = sys.stdin.read()
     except Exception as exc:
@@ -52,7 +139,7 @@ def main() -> int:
         print("[odse-transform] empty payload", file=sys.stderr)
         return 1
 
-    # Import odse — fail fast with a clear message if not installed
+    # Import odse — fail fast with a clear message if not installed.
     try:
         from odse.transformer import transform  # noqa: PLC0415
     except ImportError:
@@ -62,7 +149,7 @@ def main() -> int:
         )
         return 2
 
-    # Attempt transformation
+    # Attempt transformation.
     try:
         kwargs: dict = {}
         if args.timezone:
@@ -83,9 +170,15 @@ def main() -> int:
         print(f"[odse-transform] transform error: {exc}", file=sys.stderr)
         return 1
 
-    # Write normalized records as JSON array to stdout
+    # Render in the requested format.
     try:
-        print(json.dumps(records, default=str))
+        if fmt == "table":
+            print(_render_table(records, args.source))
+        elif fmt == "summary":
+            print(_render_summary(records, args.source))
+        else:
+            # ndjson — default for non-TTY / piped callers
+            print(_render_ndjson(records))
     except Exception as exc:
         print(f"[odse-transform] serialization error: {exc}", file=sys.stderr)
         return 1

package/lib/scripts/python-safety-checker.py

@@ -189,6 +189,17 @@ class PythonSafetyChecker:
                 print(f"\n--- {tool} Issues ---")
                 print(issue)
             print(f"\n✗ Found {len(self.issues)} issues.")
+            # Emit structured blocked payload on stderr so the caller (tools.mjs
+            # _parseBlockedPayload) can surface the interactive confirmation menu.
+            import json as _json
+            reasons = "; ".join(tool for tool, _ in self.issues)
+            _payload = {
+                "status": "blocked",
+                "reason": f"PythonSafetyChecker: {reasons}",
+                "risk_score": "high",
+                "proposed_remediation": ["review", "sandbox"],
+            }
+            print(_json.dumps(_payload), file=sys.stderr)
             sys.exit(1)
 
 if __name__ == "__main__":

package/lib/scripts/shell-safety-checker.sh

@@ -301,6 +301,10 @@ if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
         exit 0
     else
         echo "✗ Safety check failed"
+        # Emit structured blocked payload on stderr so tools.mjs _parseBlockedPayload
+        # can surface the interactive confirmation menu in the TUI.
+        printf '{"status":"blocked","reason":"ShellSafetyChecker: %d file(s) with issues","risk_score":"high","proposed_remediation":["review","sandbox"]}\n' \
+            "$totalIssues" >&2
         exit 1
     fi
 fi

package/lib/store.mjs

@@ -6,8 +6,8 @@ import Database from 'better-sqlite3'
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const SCHEMA_PATH = path.resolve(__dirname, '..', 'schema.sql')
 
-/** Current schema version after Jev-Mem tables/columns. */
-export const SCHEMA_VERSION = 2
+/** Current schema version — v3 adds pinned_context table. */
+export const SCHEMA_VERSION = 3
 
 const byPath = new Map()
 
@@ -82,10 +82,31 @@ export function migrateStore(db) {
     `)
 
     db.prepare(
-      `INSERT INTO schema_meta(key,value) VALUES ('schema_version', ?)
+      `INSERT INTO schema_meta(key,value) VALUES ('schema_version', '2')
        ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
-    ).run(String(SCHEMA_VERSION))
-    version = SCHEMA_VERSION
+    ).run()
+    version = 2
+  }
+
+  if (version < 3) {
+    // v3: pinned context blocks — preserved verbatim through compaction.
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS pinned_context (
+        id          INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id  TEXT NOT NULL,
+        key         TEXT NOT NULL,
+        content     TEXT NOT NULL,
+        created_at  INTEGER NOT NULL,
+        UNIQUE(session_id, key)
+      );
+      CREATE INDEX IF NOT EXISTS idx_pinned_context_session ON pinned_context(session_id);
+    `)
+
+    db.prepare(
+      `INSERT INTO schema_meta(key,value) VALUES ('schema_version', '3')
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+    ).run()
+    version = 3
   }
 
   return version
@@ -276,3 +297,34 @@ export function listMemoryEdges(db, nodeId, relation = null) {
     ORDER BY weight DESC
   `).all(nodeId, nodeId)
 }
+
+// ── Pinned Context CRUD ───────────────────────────────────────
+
+/**
+ * Upsert a pinned context block.  Content is preserved verbatim through
+ * compaction — never distilled.  Use for ODSE schema maps, asset specs,
+ * simulation bounds, and system invariants that must survive context pruning.
+ */
+export function upsertPinnedContext(db, sessionId, key, content) {
+  const now = Date.now()
+  db.prepare(`
+    INSERT INTO pinned_context(session_id, key, content, created_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(session_id, key) DO UPDATE SET
+      content    = excluded.content,
+      created_at = excluded.created_at
+  `).run(sessionId, key, content, now)
+  return db.prepare(`SELECT * FROM pinned_context WHERE session_id = ? AND key = ?`).get(sessionId, key)
+}
+
+/** Return all pinned blocks for a session ordered by insertion time. */
+export function getPinnedContextBlocks(db, sessionId) {
+  return db.prepare(
+    `SELECT * FROM pinned_context WHERE session_id = ? ORDER BY created_at ASC`,
+  ).all(sessionId)
+}
+
+/** Remove a single pinned block by key. No-op if it does not exist. */
+export function removePinnedContext(db, sessionId, key) {
+  db.prepare(`DELETE FROM pinned_context WHERE session_id = ? AND key = ?`).run(sessionId, key)
+}

package/lib/tools.mjs

@@ -10,6 +10,7 @@ import { runHooks } from './hookplane.mjs'
 import { createWorktree, removeWorktree, getCurrentWorktree } from './worktree.mjs'
 import { addTeammate, setTeammateIdle } from './team.mjs'
 import { validateBashCommand } from './bashguard.mjs'
+import { cacheSessionApproval, hasSessionApproval } from './permissions.mjs'
 
 const BASH_CAP = 1048576
 const TRUNC = '[SDLC_TRUNCATED]'
@@ -69,7 +70,7 @@ export async function executeBuiltinTool(db, ctx, toolName, toolInput, io) {
       case 'Edit': return toolEdit(cwd, toolInput, db, ctx)
       case 'Glob': return toolGlob(cwd, toolInput)
       case 'Grep': return toolGrep(cwd, toolInput)
-      case 'Bash': return await toolBash(cwd, toolInput, db, ctx)
+      case 'Bash': return await toolBash(cwd, toolInput, db, ctx, io)
       case 'NotebookEdit': return toolNotebookEdit(cwd, toolInput)
       case 'WebFetch': return await toolWebFetch(toolInput)
       case 'WebSearch': return await toolWebSearch(toolInput)
@@ -293,12 +294,47 @@ function toolGrep(cwd, input) {
 
 const CWD_MARKER = '___ONA_CWD___'
 
-async function toolBash(cwd, input, db, ctx) {
+async function toolBash(cwd, input, db, ctx, io) {
   const cmd = input?.command
   if (!cmd || typeof cmd !== 'string') return { content: 'Bash: missing command', is_error: true }
-  // Validate command safety before execution
+
+  // Approval cache key — lets a session-approved pattern skip re-prompting.
+  const approvalKey = `Bash:${cmd.slice(0, 80)}`
+  const sessionId = ctx?.sessionId
+
+  // Validate command safety before execution.
   const guard = validateBashCommand(cmd, cwd)
-  if (!guard.ok) return { content: `[SDLC] Bash command blocked: ${guard.reason}`, is_error: true }
+  if (!guard.ok) {
+    // Check session approval cache first (user previously approved this pattern).
+    if (sessionId && hasSessionApproval(sessionId, approvalKey)) {
+      // Approved — fall through to execution.
+    } else if (io?.confirmBlock) {
+      // TUI is live — raise the interactive confirmation menu.
+      const decision = await io.confirmBlock(guard)
+      if (decision === 'approve') {
+        // Cache this approval for the rest of the session.
+        if (sessionId) cacheSessionApproval(sessionId, approvalKey)
+        // Fall through to execution.
+      } else if (decision === 'sandbox') {
+        return { content: `[SDLC] Sandboxed: ${guard.reason} — command routed to Laya worker sandbox (not yet implemented)`, is_error: false }
+      } else {
+        // 'cancel' or any other value
+        return {
+          content: `[SDLC] Bash command blocked: ${guard.reason} (risk: ${guard.risk_score})`,
+          is_error: true,
+          _blocked: guard,
+        }
+      }
+    } else {
+      // Headless / pipe mode — auto-deny, no prompt.
+      return {
+        content: `[SDLC] Bash command blocked: ${guard.reason} (risk: ${guard.risk_score})`,
+        is_error: true,
+        _blocked: guard,
+      }
+    }
+  }
+
   const timeoutMs = Math.min(input?.timeout || 120_000, 600_000)
   // Append cwd detection marker
   const wrappedCmd = `${cmd} ; echo "${CWD_MARKER}$(pwd)"`
@@ -344,6 +380,29 @@ function resolveBash() {
 
 // ─── Dynamic Script Tool Executor ───────────────────────────────
 
+/**
+ * Scan stderr lines from a safety-checker script for a structured blocked payload.
+ * Safety checkers emit one JSON line of the form:
+ *   { "status": "blocked", "reason": "...", "risk_score": "high"|"medium", "proposed_remediation": [...] }
+ * Returns the parsed object, or null if none found.
+ */
+function _parseBlockedPayload(stderr) {
+  if (!stderr) return null
+  for (const line of stderr.split('\n').reverse()) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('{')) continue
+    try {
+      const obj = JSON.parse(trimmed)
+      if (obj.status === 'blocked' && typeof obj.reason === 'string') {
+        return obj
+      }
+    } catch {
+      // not JSON — keep scanning
+    }
+  }
+  return null
+}
+
 async function executeDynamicScriptTool(cwd, toolName, input) {
   const config = dynamicTools.get(toolName)
   if (!config) return { content: `Tool ${toolName} config not found`, is_error: true }
@@ -412,6 +471,15 @@ async function executeDynamicScriptTool(cwd, toolName, input) {
         return
       }
       if (code === 1 && !stdout.trim()) {
+        // Attempt to parse a structured blocked payload from the last JSON line on stderr.
+        // Safety checkers emit { status, reason, risk_score, proposed_remediation } on stderr
+        // alongside human-readable output.  If present, forward it as a structured result so
+        // the caller (toolBash / confirmBlock) can render the interactive menu.
+        const structuredBlock = _parseBlockedPayload(stderr)
+        if (structuredBlock) {
+          resolve({ content: stderr, is_error: true, _blocked: structuredBlock })
+          return
+        }
         resolve({ content: stderr || `${toolName} execution error (exited with code 1 and empty output)`, is_error: true })
         return
       }

package/lib/ui.mjs

@@ -3,6 +3,16 @@
 import chalk from 'chalk'
 import { marked } from 'marked'
 import TerminalRenderer from 'marked-terminal'
+import { createRequire } from 'node:module'
+
+// cli-table3 is a CommonJS module; load it via createRequire so this ESM file works.
+const _require = createRequire(import.meta.url)
+let Table
+try {
+  Table = _require('cli-table3')
+} catch {
+  Table = null // graceful degradation when not yet installed
+}
 
 // Configure marked for terminal output
 marked.setOptions({
@@ -156,6 +166,41 @@ export function formatToolStart(toolName) {
 export function formatToolResult(toolName, content, isError) {
   const icon = isError ? colors.toolError('✗') : colors.success('✓')
   const label = colors.toolLabel('  └ ')
+
+  // Attempt JSON-array table rendering when not an error and cli-table3 is available.
+  if (!isError && Table && typeof content === 'string' && content.trimStart().startsWith('[')) {
+    try {
+      const parsed = JSON.parse(content)
+      if (Array.isArray(parsed) && parsed.length > 0 && typeof parsed[0] === 'object' && parsed[0] !== null) {
+        const TABLE_ROW_CAP = 10
+        const rows = parsed.slice(0, TABLE_ROW_CAP)
+        const headers = Object.keys(rows[0])
+        const termWidth = process.stdout.columns || 80
+        // Distribute column widths evenly, leaving room for borders (3 chars per col).
+        const colWidth = Math.max(8, Math.floor((termWidth - headers.length * 3 - 1) / headers.length))
+        const table = new Table({
+          head: headers.map(h => colors.toolName(String(h))),
+          colWidths: headers.map(() => colWidth),
+          wordWrap: true,
+          style: { head: [], border: ['dim'] },
+        })
+        for (const row of rows) {
+          table.push(headers.map(h => {
+            const v = row[h]
+            return v === null || v === undefined ? '' : String(v)
+          }))
+        }
+        const truncNote = parsed.length > TABLE_ROW_CAP
+          ? colors.dim(`\n  … ${parsed.length - TABLE_ROW_CAP} more rows (${parsed.length} total)`)
+          : ''
+        const rowCountLine = colors.dim(`  ${parsed.length} row${parsed.length === 1 ? '' : 's'} — ${toolName}`)
+        return label + icon + '\n' + table.toString() + truncNote + '\n' + rowCountLine
+      }
+    } catch {
+      // Not valid JSON — fall through to plain preview
+    }
+  }
+
   const preview = (content || '').split('\n')[0].slice(0, 80)
   return label + icon + ' ' + colors.dim(preview)
 }
@@ -284,3 +329,58 @@ export function formatSessionSummary(sessionId, tokens, model, provider) {
   ]
   return lines.join('\n')
 }
+
+// ── Runtime Status Header (Gap 1) ────────────────────────────
+
+/**
+ * Renders a persistent status header bar at the top of the REPL terminal.
+ * Called after startup and after each /model switch to confirm active backend.
+ *
+ * @param {object} status - Payload from RuntimeHealthMonitor.getRuntimeStatus()
+ * @returns {string} Formatted ANSI string ready for console.log / io.println
+ */
+export function renderStatusHeader(status) {
+  const isOnline = status.endpointStatus === 'ONLINE'
+  const statusColor = isOnline ? chalk.green : chalk.red
+  const sidecarColor = status.sidecarStatus.startsWith('ACTIVE') ? chalk.green : chalk.yellow
+  const termWidth = process.stdout.columns || 80
+  const divider = colors.dim('─'.repeat(termWidth))
+
+  const headerLine = [
+    chalk.bold.inverse(' NEHANDA REPL '),
+    chalk.dim('│'),
+    `Model: ${chalk.bold.white(status.model)}`,
+    `[${statusColor(status.endpointStatus)}${status.latency >= 0 ? chalk.dim(` ${status.latency}ms`) : ''}]`,
+  ].join(' ')
+
+  const subLine = [
+    `Sidecar (laya_worker): ${sidecarColor(status.sidecarStatus)}`,
+    chalk.dim('│'),
+    `Context: ${chalk.white(status.contextUsage)}`,
+    chalk.dim('│'),
+    `Target: ${chalk.dim(status.endpoint)}`,
+  ].join(' ')
+
+  return [divider, headerLine, subLine, divider].join('\n')
+}
+
+/**
+ * Visual feedback printed immediately after a /model switch.
+ * Includes an endpoint probe result so silent backend failures surface at once.
+ *
+ * @param {string} oldModel
+ * @param {string} newModel
+ * @param {object} status - Payload from RuntimeHealthMonitor.getRuntimeStatus()
+ * @returns {string}
+ */
+export function renderModelSwitchNotice(oldModel, newModel, status) {
+  const badge = status.endpointStatus === 'ONLINE'
+    ? chalk.green('[SUCCESS]')
+    : chalk.red('[WARNING: ENDPOINT UNREACHABLE]')
+
+  return [
+    '',
+    `${badge} Switched active reasoning model: ${chalk.bold(oldModel)} ➔ ${chalk.bold(newModel)}`,
+    `  Endpoint Probe: ${chalk.dim(status.endpoint)} (${status.endpointStatus})`,
+  ].join('\n')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asobacloud/nehanda",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Agentic terminal REPL and single-process engine for governed AI deep research and software development. Connects to Nehanda v3, Ollama, LM Studio, or any OpenAI-compatible API.",
   "engines": {
@@ -39,6 +39,7 @@
     "@anthropic-ai/sdk": "^0.39.0",
     "better-sqlite3": "^11.8.1",
     "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
     "esprima": "^4.0.1",
     "ink": "^6.8.0",
     "ink-text-input": "^6.0.0",