@kinqs/brainrouter-cli 0.3.4 → 0.3.6

package/.env.example

@@ -1,77 +1,81 @@
-# BrainRouter CLI agent — environment
+# BrainRouter CLI agent — environment template
 #
-# Copy to brainrouter-cli/.env. Loaded by the CLI at startup.
+# Copy to `brainrouter-cli/.env`. Loaded by the CLI at startup.
 #
 # This file is for CLI-AGENT concerns only:
-#   - chat LLM the terminal agent talks to
-#   - tool runtime knobs (loop limit, result clamp, MCP timeout)
-#   - auto-compaction trigger
-#   - sandbox configuration for run_command
-#   - web search backend
-#   - trace logging
-#   - workspace override
+#   1. Chat LLM                  (the model the terminal agent talks to)
+#   2. Tool runtime              (loop limit, result clamp, MCP timeout, auto-compact)
+#   3. Sandbox                   (run_command wrapping)
+#   4. Workspace                 (root override + shared state root)
+#   5. Web search                (custom backend for the web_search tool)
+#   6. Observability             (trace log path)
 #
-# MCP-server concerns (cognitive extraction, embeddings, reranker, memory
-# engine knobs, server auth) live in brainrouter/.env.example.
+# MCP-server concerns (cognitive extraction, embeddings, reranker, judge,
+# memory engine knobs, server auth) live in `brainrouter/.env.example`.
 #
 # Why split: the MCP and the CLI are separate processes with different
 # concerns. The CLI's chat LLM can be a smart cloud model while the MCP's
 # cognitive extractor is a cheap local one. Their concurrency caps differ
 # too (CLI default 4, MCP default 2). Keep them independent.
+#
+# All values in this template are blank placeholders. Fill in only what
+# you actually need — most settings have sensible defaults.
+
 
-# ==========================================
-# Chat LLM (for the agent's own conversation)
-# ==========================================
+# =============================================================================
+# 1. Chat LLM (for the agent's own conversation)
+# =============================================================================
 # Same var names as the MCP, but a separate process — set them here for the
 # CLI's chat model. Falls back to OPENAI_API_KEY.
 #
 # If you don't set BRAINROUTER_LLM_API_KEY here, the CLI also reads it from
-# brainrouter/.env as a transitional fallback. Setting it here makes the
+# `brainrouter/.env` as a transitional fallback. Setting it here makes the
 # CLI's choice explicit and lets you use a different chat model than the
 # MCP's extractor (e.g. gpt-4o for chat, gpt-4o-mini for extraction).
-BRAINROUTER_LLM_API_KEY=your_api_key_here
+BRAINROUTER_LLM_API_KEY=
 
 # OpenAI-compatible chat-completions endpoint.
 # Examples:
-#   OpenAI:     https://api.openai.com/v1/chat/completions
-#   OpenRouter: https://openrouter.ai/api/v1/chat/completions
-#   Anthropic via OpenRouter: anthropic/claude-sonnet-4
-#   LM Studio:  http://localhost:1234/v1/chat/completions
+#   OpenAI:                   https://api.openai.com/v1/chat/completions
+#   OpenRouter:               https://openrouter.ai/api/v1/chat/completions
+#   Anthropic via OpenRouter: model id "anthropic/claude-sonnet-4"
+#   LM Studio:                http://localhost:1234/v1/chat/completions
 BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
-
 BRAINROUTER_LLM_MODEL=gpt-4o-mini
 
-# Per-call timeout for the CLI's chat LLM. Default: 120000.
+# Per-call timeout for the CLI's chat LLM. Default 120000 (2 min).
 # BRAINROUTER_LLM_TIMEOUT_MS=120000
 
 # Cap on concurrent in-flight chat LLM calls FROM THE CLI PROCESS.
-# Default: 4 (separate from the MCP's own cap). Set to 1 for consumer-grade
-# local backends; crank to 16+ for cloud APIs.
+# Default 4 (separate from the MCP's own cap). Set to 1 for consumer-grade
+# local backends; raise to 16+ for cloud APIs.
 # BRAINROUTER_LLM_MAX_CONCURRENT=4
 
-# ==========================================
-# Tool runtime
-# ==========================================
-# Per-tool timeout for CLI → MCP requests. Default: 60000.
+
+# =============================================================================
+# 2. Tool runtime
+# =============================================================================
+# Per-tool timeout for CLI → MCP requests. Default 60000.
 # BRAINROUTER_MCP_TIMEOUT_MS=60000
 
 # LLM-visible clamp on a single tool-result body (full text still recorded
-# in the transcript on disk). Default: 8000.
+# in the transcript on disk). Default 8000.
 # BRAINROUTER_MAX_TOOL_RESULT_CHARS=8000
 
-# Hard ceiling on tool-call iterations per turn. Default: 60.
+# Hard ceiling on tool-call iterations per turn. Default 60.
 # BRAINROUTER_MAX_TOOL_LOOPS=60
 
-# Estimated history-size trigger for auto-`/compact`. Default: 80000 tokens.
+# Estimated history-size trigger for auto-`/compact`. Default 80000 tokens.
 # BRAINROUTER_AUTO_COMPACT_TOKENS=80000
 
-# ==========================================
-# Sandbox (run_command)
-# ==========================================
+
+# =============================================================================
+# 3. Sandbox (run_command)
+# =============================================================================
 # Wrap shell commands in the platform sandbox:
 #   macOS: sandbox-exec
 #   Linux: bwrap (preferred) or firejail
-# Set 'on' to enable. Off by default.
+# Set `on` to enable. Off by default.
 # BRAINROUTER_SANDBOX=on
 
 # Allow outbound network from sandboxed commands. Off by default.
@@ -81,29 +85,32 @@ BRAINROUTER_LLM_MODEL=gpt-4o-mini
 # BRAINROUTER_SANDBOX_READ_PATHS=/usr/local:/opt
 # BRAINROUTER_SANDBOX_WRITE_PATHS=/tmp
 
-# ==========================================
-# Workspace
-# ==========================================
-# Override workspace root the CLI uses for file tools + session key.
-# Most users let the CLI auto-detect via git/closest package.json.
+
+# =============================================================================
+# 4. Workspace
+# =============================================================================
+# Override the workspace root the CLI uses for file tools + session key.
+# Most users let the CLI auto-detect via git / closest package.json.
 # BRAINROUTER_WORKSPACE=/path/to/project
 
 # Override per-user state root. Default: ~/.brainrouter.
 # Both the CLI and MCP honor this — set it once and both processes use it.
 # BRAINROUTER_HOME=/path/to/state
 
-# ==========================================
-# Web search
-# ==========================================
+
+# =============================================================================
+# 5. Web search
+# =============================================================================
 # Custom search backend for the web_search tool. Must accept
-#   POST { query, maxResults } → { results: [{ title, url, snippet }] }.
+#   POST { query, maxResults } → { results: [{ title, url, snippet }] }
 # Falls back to DuckDuckGo's Instant Answer API when unset.
-# Compatible with Brave Search API wrappers, Tavily, SerpAPI proxies.
+# Compatible with Brave Search API wrappers, Tavily, SerpAPI proxies, etc.
 # BRAINROUTER_WEB_SEARCH_ENDPOINT=https://your-search-proxy.example.com/search
 
-# ==========================================
-# Observability
-# ==========================================
+
+# =============================================================================
+# 6. Observability
+# =============================================================================
 # Path for OTEL-style JSONL turn traces. One line per turn/tool span.
 # Toggle at runtime with /trace on|off.
 # BRAINROUTER_TRACE_LOG=/path/to/trace.jsonl

package/README.md

@@ -1,185 +1,145 @@
-# 🧠 BrainRouter Terminal Agent CLI
+# `@kinqs/brainrouter-cli`
 
-A premium, autonomous terminal-based AI coding assistant and REPL that acts as your local agent. It leverages **BrainRouter's memory engine** for cognitive persistence (System 1/2 loops) and provides standard filesystem/terminal tools to solve complex coding tasks autonomously.
+A memory-native terminal agent. Edits files, runs shell commands,
+spawns child agents, and talks to a BrainRouter MCP server for long-term
+recall, skills, and capture.
+
+Ships the `brainrouter` binary.
 
 ---
 
-## Features
-- **Dual-Tier Connection**: Connects to local MCP servers via standard I/O (stdio) or hosted multi-tenant servers over Streamable HTTP/SSE.
-- **Double-Tier Memory Architecture**:
-  - **System 1 (Heuristic Recall)**: Automatically retrieves active focus scenes, codebase facts, and skills *before* each LLM reasoning cycle.
-  - **System 2 (Memory Consolidation)**: Autonomously extracts learning points, updates facts, and saves evidence via turn-by-turn memory capture.
-- **Local Execution Harness**: Autonomous execution of files editing, directory listing, regex/string grep, and terminal command invocation (safely prompted for user verification).
-- **Obsidian Dark / Midnight Ledger Aesthetics**: High-end command line styling, loader animations, and formatted terminal markdown output.
+## Install
 
----
+```bash
+npm install -g @kinqs/brainrouter-cli
+```
 
-## Installation & Setup
-
-1. **Build the Monorepo**:
-   From the repository root:
-   ```bash
-   npm install
-   npm run build
-   ```
-
-2. **Configure Provider and Server Profiles**:
-   Run the interactive configurator to set up your LLM settings (OpenAI, local endpoints like Ollama/LM Studio) and active server profile.
-   From the repository root:
-   ```bash
-   npm run cli config
-   ```
-   Or from the `brainrouter` package subdirectory:
-   ```bash
-   node dist/index.js config
-   ```
-   This generates and modifies settings stored in `~/.config/brainrouter/config.json`.
+**The `-g` flag is critical.** Without it, npm installs into the current
+directory's `node_modules/` and the `brainrouter` binary ends up at
+`./node_modules/.bin/brainrouter` — not on `$PATH`. Symptom: `brainrouter:
+command not found`.
 
----
+**Sudo caveat.** Whether you need `sudo` depends on your Node install:
+
+| How Node is installed | Use `sudo`? |
+|---|---|
+| Homebrew (`brew install node`) | ❌ No — global prefix is user-writable |
+| nvm / asdf / fnm | ❌ No — same reason |
+| System Node on macOS / Linux | ✅ Yes — global prefix is `/usr/local/...` |
+
+Check yours:
 
-## CLI Usage
-
-### Start Interactive Agent Session (REPL)
-Starts the agent loop. It will automatically load the active server connection and prime the agent with active codebase memories.
-From the repository root:
-   ```bash
-   npm run cli
-   ```
-   Or to run a specific command:
-   ```bash
-   npm run cli chat
-   ```
-   Or from the `brainrouter` package subdirectory:
-   ```bash
-   node dist/index.js chat
-   ```
-*Tip: You can override the active LLM model via `--model <name>` or profile via `--profile <name>`.*
-
-Workspace detection:
-- By default, BrainRouter uses the nearest project root with `AGENT.md`, `AGENTS.md`, or `.git`.
-- If you run from this package directory during BrainRouter development, the CLI promotes the workspace to the monorepo root so tools see the whole project, not only `brainrouter/`.
-- Override manually with `--workspace /absolute/path/to/project` or `BRAINROUTER_WORKSPACE=/absolute/path/to/project`.
-- In the REPL, run `/workspace` to confirm the active root and session key.
-
-### Host Login / Setup Connection
-Interactively log in to a hosted HTTP/SSE BrainRouter deployment and test latency/connectivity:
-From the repository root:
 ```bash
-npm run cli login
+npm config get prefix
+```
+
+If the path is under `/Users/...`, `/opt/homebrew/...`, or your home dir
+→ no sudo. If it's `/usr/local/...` → use sudo.
+
+Verify the install:
+
+```bash
+which brainrouter           # prints the path to the binary
+brainrouter --version       # prints 0.3.5
 ```
 
 ---
 
-## Interactive REPL Slash Commands
+## Configure
+
+Two configuration surfaces, both one-time:
 
-Within the chat session, type `/` to access commands:
-- `/help` — List all available directive commands.
-- `/status` — Display active server profile details, LLM model, server latency check, and database size stats.
-- `/workspace` — Show active workspace root, launch directory, and BrainRouter session key.
-- `/tools` — Show local workspace tools and MCP tools exposed to the LLM.
-- `/doctor` — Check active profile, MCP connectivity, plan + session store health, and orchestration tool availability.
-- `/skills` — Visualize all loaded BrainRouter skills and categories.
-- `/plan` — Show the durable CLI task plan persisted under `.brainrouter/cli/tasks.json`.
-- `/transcript [main|sessionKey]` — Show recent persisted transcript entries.
-- `/roles` — List built-in agent roles (`explorer`, `architect`, `reviewer`, `worker`, `verifier`) with default access modes.
-- `/agents` — List child agent sessions with status, role, label, and elapsed time.
-- `/agent <id>` — Show child detail, prompt, final output, and recent transcript.
-- `/spawn <role> <prompt>` — Spawn a child agent (parent narrates via the LLM tool call).
-- `/wait <id> [timeoutMs]` — Wait for a child agent to finish.
-- `/spec <title>` — Runs the **spec-driven-skill** and writes a full `spec.md` to `<workspace>/.brainrouter/cli/workflows/<slug>/spec.md`. Stops for approval before generating tasks.
-- `/approve [slug]` — Approves the current (or named) workflow and kicks off the worker + verifier implementation phase, one task at a time, appending to `walkthrough.md`.
-- `/workflows` — List durable workflow folders with per-artifact status (`spec.md`, `tasks.md`, `walkthrough.md`).
-- `/feature-dev <feature>` — Runs the catalogued **agentic-engineering-workflow** skill with explorer + architect orchestration. Writes `spec.md` and `tasks.md` to the workflow folder, then stops for user approval before worker implementation.
-- `/review [scope]` — Runs the catalogued **code-review-and-quality** skill with 3 parallel reviewer agents (correctness, maintainability, conventions).
-- `/implement-plan` — Runs the catalogued **incremental-skill** with a worker + verifier loop on the next pending plan item.
-- `/skill <name> [input]` — Generic invoker for any skill in your `skills/` catalogue. The CLI fetches the skill body via the MCP `get_skill` tool, falls back to filesystem (`skills/**/SKILL.md`), and hands the agent a structured prompt that embeds the skill instructions plus orchestration affordances (`spawn_agent`, `update_plan`).
+### 1. The chat LLM and MCP server profile
 
-### Skill-driven workflows
+```bash
+brainrouter config          # interactive — set LLM provider, model, key, endpoint
+brainrouter login           # interactive — set MCP server URL + API key
+```
 
-The CLI ships with a thin slash → skill mapping (see `brainrouter-cli/src/prompt/skillRunner.ts`). Slash commands do **not** carry monolithic hard-coded prompts; they delegate to the SKILL.md authored under `skills/`. This means improving a workflow is a documentation edit, not a code change. Add a new mapping in `SLASH_TO_SKILL` to expose a new slash command, or use `/skill <name>` to invoke any skill ad-hoc.
+Both write to `~/.config/brainrouter/config.json`.
 
-#### How the skill catalogue is discovered
+For local-model setups (LM Studio / Ollama), point the LLM endpoint at
+`http://localhost:1234/v1/chat/completions` or `http://localhost:11434/v1/chat/completions`.
 
-The CLI resolves a skill body in this order:
+### 2. (Optional) Runtime knobs — `~/.config/brainrouter/cli.env` or `./brainrouter-cli.env`
 
-1. **MCP `get_skill` tool** — the connected MCP server merges *global* skills (the canonical BrainRouter catalogue) with *local* skills the user authored under `<workspace>/skills/` or `<workspace>/projects/*/skills/`. Local skills shadow global ones on name conflict. This is the path used in normal operation.
-2. **Filesystem fallback** (used only when MCP is unreachable) searches, in order:
-   - `<workspace>/skills/**/SKILL.md`
-   - `<workspace>/.brainrouter/skills/**/SKILL.md`
-   - The installed `@kinqs/brainrouter-mcp-server` package directory (resolved via `require.resolve`). This works because the MCP package bundles the canonical catalogue at publish time (see below).
-3. Otherwise the CLI hands the agent a benign placeholder and asks it to use general judgement.
+Only needed if you want to tune sandbox, tool-loop limits, trace logging,
+or web-search backend. See the [`.env.example`](.env.example) bundled with
+this package for the full list. LLM credentials do **not** go here — they
+live in `config.json`.
 
-#### Catalogue bundling at publish time
+---
 
-The `@kinqs/brainrouter-mcp-server` package ships with the full BrainRouter skill catalogue baked in, so a user who only runs `npm install @kinqs/brainrouter-mcp-server @kinqs/brainrouter-cli` in their own workspace gets all 70+ canonical skills out of the box — no monorepo checkout required.
+## Run
 
-This is done via two lifecycle scripts in `brainrouter/scripts/`:
+```bash
+brainrouter                 # starts the interactive REPL
+brainrouter chat            # same — `chat` is the default subcommand
+brainrouter run "summarize the changes in src/"   # one-shot non-interactive
+brainrouter agents          # list child agent sessions in this workspace
+```
 
-- `prepack.mjs` — runs before `npm pack`/`npm publish`. Copies `skills/`, `agents/`, `references/`, and `docs/` from the monorepo root into the package directory and records what it copied in `.bundled-content.json`.
-- `postpack.mjs` — runs after pack. Reads the marker and removes exactly what `prepack` added, leaving the working tree clean.
+Inside the REPL, type `/help` for the full slash-command list (60+
+commands across session / memory / workflow / orchestration / observability
+surfaces).
 
-The MCP server's resolver ([brainrouter/src/resolver.ts](../brainrouter/src/resolver.ts)) prefers the package's own `skills/` when present (installed-package mode) and otherwise walks up to the monorepo root (development mode). Both layouts work identically from the CLI's point of view.
+### Offline mode
 
-### Durable workflow artifacts (one folder per workflow)
+If the MCP server isn't reachable, the CLI still boots — but only local
+tools (file edits, shell, web fetch, `spawn_agent`) work. Memory recall,
+capture, and skills are disabled until the server is back. The startup
+banner shows `⚠️  OFFLINE MODE` when this happens. Pass `--strict-mcp` to
+make the CLI exit instead of degrading.
 
-All multi-step commands (`/spec`, `/feature-dev`, `/review`, `/implement-plan`) anchor to a workflow slug and write their outputs to:
+### Stdio mode
 
-```
-<workspace>/.brainrouter/cli/workflows/<slug>/
-  meta.json        # { slug, title, kind, createdAt, updatedAt, status }
-  spec.md          # produced by /spec or /feature-dev phase 3
-  tasks.md         # produced by /feature-dev phase 3
-  walkthrough.md   # appended by /implement-plan as items ship
-  review.md        # produced by /review
-```
+If you'd rather have the CLI spawn the MCP server as a child process
+instead of running it separately, use `brainrouter config` → "Set Active
+Server Profile" → `default` (the bundled stdio profile). You don't need
+to run anything else — the CLI manages the server's lifecycle.
 
-The orchestration prompts for these commands **require** the agent to call `write_file` with the exact workspace-relative path — no chat-only plans. Use `/workflows` to inspect what's on disk. `getCurrentWorkflow` tracks the most recent one so `/implement-plan` appends to it automatically.
+---
 
-The system prompt also directs the agent to redirect free-form spec/plan requests to `/spec` or `/feature-dev` instead of producing inline monoliths, so the "one place" rule survives even when you don't type a slash command.
+## Workspace detection
 
-### Memory-native flow
+By default, the CLI uses the nearest project root with `AGENT.md`,
+`AGENTS.md`, or `.git`. Override with:
 
-Each parent turn runs three memory queries in parallel before the LLM sees the user prompt:
+```bash
+brainrouter --workspace /absolute/path/to/project
+# or
+BRAINROUTER_WORKSPACE=/absolute/path/to/project brainrouter
+```
 
-1. **`memory_recall`** — cognitive memory most relevant to the prompt.
-2. **`memory_working_context`** — current working canvas, so resumed sessions don't reset.
-3. **`memory_task_state`** — open tasks / handover notes for this workspace.
+Inside the REPL, run `/workspace` to confirm the active root and session key.
 
-The merged briefing (secrets redacted via `redactText`) is injected as a system message and the recalled record IDs are tracked through the whole turn. At end-of-turn, `selectCitedRecordIds` heuristically picks the records that actually informed the answer (by ID mention or distinctive content match) and reports them via `memory_mark_cited` — replacing the previous always-empty citation list, so System-1 recall actually learns.
+---
 
-Child agents (`spawn_agent`) skip the full briefing for speed but accept a `seedRecordIds: string[]` parameter so the parent can hand over what it already recalled. Long child outputs (≥ 6,000 chars) are automatically offloaded to `memory_working_offload` and only a preview + ref handle is returned to the parent — the main context-saving win when synthesizing multiple child reports.
+## What you also probably want
 
-After every turn, the CLI also asks `memory_contradictions` and surfaces a one-line warning in the REPL when newly-captured beliefs disagree with prior ones, so drift gets caught instead of silently accumulating.
+A BrainRouter MCP server for the cognitive memory. The CLI works without
+it (offline mode) but you lose recall, capture, and skills:
 
-Inspection commands:
+```bash
+npm install -g @kinqs/brainrouter-mcp-server
+brainrouter-mcp init                              # one-time: scaffold ~/.config/brainrouter/server.env
+$EDITOR ~/.config/brainrouter/server.env          # set BRAINROUTER_LLM_API_KEY, embeddings, etc.
+brainrouter-mcp --http --port 3747                # in a separate terminal
+```
 
-- `/memory <query>` — search long-term cognitive memory (`memory_search`).
-- `/recall <query>` — explicit `memory_recall`, no LLM turn.
-- `/briefing` — what was recalled before the most recent turn.
-- `/scenes` — list active focus scenes.
-- `/working` — current working-memory canvas.
-- `/forget <recordId>` — archive an obsolete memory.
+Then `brainrouter login` and point at `http://localhost:3747/mcp`.
 
-The workflow commands `/feature-dev`, `/review`, and `/implement-plan` are now required to open with `memory_search` (plus `memory_graph_query` / `memory_file_history` / `memory_task_state` depending on the workflow) and pass `seedRecordIds` to children, so no exploration is ever duplicated across sessions.
+---
 
-### Child agent permissions
+## Docs
 
-Child agents default to the safest mode for their role: `explorer`, `architect`, `reviewer` are `read`; `worker` is `write`; `verifier` is `shell`. Override with `access: "read" | "write" | "shell"` when calling `spawn_agent`. Shell execution from children runs unattended — only grant `shell` to trusted roles like `verifier`.
-- `/config` — Output active configuration details (with security sanitization for API keys).
-- `/compact` — Clear the active chat context while keeping the session identity.
-- `/clear` — Wipe the chat history of the active session.
-- `/exit` — Close connections and exit.
+- **Repo**: <https://github.com/kinqsradiollc/BrainRouter>
+- **Memory engine deep-dive**: [BRAINROUTER.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/BRAINROUTER.md)
+- **Maintainer runbook**: [SETUP.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/SETUP.md)
+- **Bugs / requests**: <https://github.com/kinqsradiollc/BrainRouter/issues>
 
 ---
 
-## Autonomous Tool Execution
-
-The agent coordinates two scopes of tools:
-1. **BrainRouter Memory Tools** (loaded dynamically via the MCP connection): `memory_recall`, `memory_capture_turn`, `list_skills`, etc.
-2. **Local Workspace Tools**:
-   - `read_file` — Reads content of a workspace file.
-   - `write_file` — Overwrites or writes a new file.
-   - `edit_file` — Performs safe single-match string search-and-replace.
-   - `list_dir` — Lists directory paths.
-   - `grep_search` — Platform-independent recursive search of code patterns.
-   - `run_command` — Runs a shell command on your host (always requests manual confirmation first for safety).
+## License
+
+MIT

package/bin/cli.cjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * Thin CommonJS shim that runs BEFORE the real ESM CLI entrypoint.
+ *
+ * Why CJS for the bin: ESM hoists all `import` statements above any
+ * top-level code in the module that owns them. The CLI imports
+ * `node:sqlite` transitively via `config/config.ts`, which triggers
+ * Node's `ExperimentalWarning` the FIRST time the module is touched —
+ * and that happens during import resolution, before any line of code
+ * in `src/index.ts` runs. So a warning filter installed inside that
+ * file always fires too late.
+ *
+ * This shim does three things synchronously, with zero ESM imports
+ * blocking it, and only then hands off:
+ *
+ *   1. Remove Node's default "warning" printer.
+ *   2. Install a filtered listener that drops `ExperimentalWarning`
+ *      (sqlite, ESM in older Node) and dotenv self-promotion lines.
+ *   3. Override `process.emitWarning` so future direct callers also
+ *      route through the same filter.
+ *
+ * Anything BrainRouter itself emits via `process.emitWarning('…',
+ * 'BrainRouterWarning')` (or any non-suppressible type) flows through
+ * unchanged. NODE_NO_WARNINGS=1 would silence those too, which is why
+ * we don't just set that env.
+ *
+ * The shim then dynamically imports the ESM entry. Dynamic `import()`
+ * is the only way to load ESM from CJS; it returns a promise we await
+ * so an unhandled rejection during boot still surfaces as an error.
+ */
+
+function isSuppressibleWarning(message, type) {
+  const looksExperimental =
+    type === 'ExperimentalWarning' ||
+    /experimental feature|SQLite is an experimental/i.test(message);
+  const looksDotenvNoise = /dotenv@\d|dotenvx|dotenv\.org/i.test(message);
+  return looksExperimental || looksDotenvNoise;
+}
+
+for (const listener of process.listeners('warning')) {
+  process.removeListener('warning', listener);
+}
+process.on('warning', (warning) => {
+  const message = (warning && warning.message) || '';
+  const type = (warning && warning.name) || '';
+  if (isSuppressibleWarning(message, type)) return;
+  process.stderr.write(`(node:${process.pid}) ${type || 'Warning'}: ${message || warning}\n`);
+});
+
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = function emitWarning(warning, ...rest) {
+  const message = typeof warning === 'string' ? warning : (warning && warning.message) || '';
+  const type =
+    typeof rest[0] === 'string' ? rest[0] :
+    (rest[0] && typeof rest[0] === 'object' && 'type' in rest[0]) ? rest[0].type :
+    (warning && warning.name) || '';
+  if (isSuppressibleWarning(message, type)) return;
+  return originalEmitWarning(warning, ...rest);
+};
+
+// Path to the compiled ESM entry, resolved relative to this shim.
+const path = require('node:path');
+const url = require('node:url');
+const entry = path.resolve(__dirname, '..', 'dist', 'index.js');
+import(url.pathToFileURL(entry).href).catch((err) => {
+  // Surface boot-time errors verbatim — a silent exit would just look like
+  // the CLI never started.
+  process.stderr.write(`brainrouter: failed to load CLI entrypoint: ${(err && err.stack) || err}\n`);
+  process.exit(1);
+});