ollama_agent 0.3.0 → 1.0.1

data/containers/ollama_agent-verification-sandbox.Dockerfile

@@ -0,0 +1,16 @@
+# Minimal sandbox for post-condition / isolated validation (array-exec only at the Docker CLI).
+# Build: docker build -f containers/ollama_agent-verification-sandbox.Dockerfile -t ollama-agent-validator:local .
+#
+# ruby:3.3-slim is smaller than the default non-slim image while keeping glibc compatibility.
+FROM ruby:3.3-slim-bookworm
+
+RUN groupadd --system --gid 65532 sandbox \
+  && useradd --system --uid 65532 --gid sandbox --home-dir /workspace --shell /usr/sbin/nologin sandbox
+
+WORKDIR /workspace
+
+# Replace with a concrete argv at `docker run ... image <cmd...>`; this is only a smoke default.
+ENTRYPOINT []
+CMD ["ruby", "-rjson", "-e", "puts JSON.dump({ok: true})"]
+
+USER sandbox

data/db/ollama_agent/migrations/0001_initial.sql

@@ -0,0 +1,102 @@
+-- ### event_store.db
+-- WAL / synchronous PRAGMAs are applied by DatabaseRegistry on each connection.
+
+CREATE TABLE IF NOT EXISTS events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  manifest_id TEXT NOT NULL,
+  logical_stamp TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  payload BLOB NOT NULL,
+  intent_hash TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_manifest_id_id ON events (manifest_id, id);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_events_intent_hash_unique ON events (intent_hash) WHERE intent_hash IS NOT NULL;
+
+-- ### runtime.db
+
+CREATE TABLE IF NOT EXISTS workspace_fingerprints (
+  manifest_id TEXT PRIMARY KEY,
+  fingerprint TEXT NOT NULL,
+  parent_manifest_id TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS fencing_tokens (
+  scope TEXT PRIMARY KEY,
+  last_token INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS integration_queue (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  manifest_id TEXT NOT NULL,
+  payload BLOB NOT NULL,
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS locks (
+  scope TEXT PRIMARY KEY,
+  lease_token INTEGER NOT NULL,
+  holder TEXT NOT NULL,
+  acquired_at TEXT NOT NULL,
+  expires_at_epoch INTEGER NOT NULL,
+  fencing_token INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_locks_expires ON locks (expires_at_epoch);
+
+CREATE TABLE IF NOT EXISTS intent_reservations (
+  intent_hash TEXT PRIMARY KEY,
+  manifest_id TEXT NOT NULL,
+  scopes TEXT NOT NULL,
+  created_at_epoch INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sagas (
+  manifest_id TEXT PRIMARY KEY,
+  state TEXT NOT NULL,
+  intent_hash TEXT,
+  planned_scopes TEXT NOT NULL,
+  supervisor_lease TEXT,
+  last_transition_at_epoch INTEGER NOT NULL,
+  terminal INTEGER NOT NULL DEFAULT 0,
+  metadata TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_sagas_state ON sagas (state) WHERE terminal = 0;
+
+CREATE TABLE IF NOT EXISTS saga_transitions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  manifest_id TEXT NOT NULL,
+  from_state TEXT NOT NULL,
+  to_state TEXT NOT NULL,
+  reason TEXT,
+  logical_stamp TEXT NOT NULL,
+  created_at_epoch INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_saga_transitions_manifest ON saga_transitions (manifest_id, id);
+
+CREATE TABLE IF NOT EXISTS compensations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  manifest_id TEXT NOT NULL,
+  path TEXT NOT NULL,
+  op TEXT NOT NULL,
+  pre_blob_sha TEXT,
+  pre_existed INTEGER NOT NULL,
+  fencing_token INTEGER NOT NULL,
+  logical_stamp TEXT NOT NULL,
+  applied INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_compensations_manifest_unapplied ON compensations (manifest_id) WHERE applied = 0;
+
+CREATE TABLE IF NOT EXISTS recovery_leases (
+  manifest_id TEXT PRIMARY KEY,
+  holder TEXT NOT NULL,
+  acquired_at_epoch INTEGER NOT NULL,
+  expires_at_epoch INTEGER NOT NULL
+);

data/db/ollama_agent/migrations/0002_cost_ledger.sql

@@ -0,0 +1,12 @@
+-- ### runtime.db
+CREATE TABLE IF NOT EXISTS cost_ledger (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  manifest_id TEXT,
+  model TEXT NOT NULL,
+  input_tokens INTEGER NOT NULL,
+  output_tokens INTEGER NOT NULL,
+  cost_usd REAL NOT NULL,
+  created_at_epoch INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_cost_ledger_manifest ON cost_ledger (manifest_id);

data/db/ollama_agent/schema.sql

@@ -0,0 +1 @@
+-- Runtime schema is applied from versioned files in db/ollama_agent/migrations/ (see OllamaAgent::Runtime::SchemaMigrator).

data/docs/CAPABILITIES.md

@@ -0,0 +1,91 @@
+# ollama_agent capabilities (post-kernel)
+
+## Overview
+
+`ollama_agent` is a Ruby gem and CLI that drives a **tool-calling agent** against a chat model (default: local **Ollama**; optional OpenAI / Anthropic providers). The model proposes **function calls**; the runtime validates arguments and executes tools under a **workspace root** (file IO, search, patches, optional shell and delegation). An optional **kernel runtime** (`OLLAMA_AGENT_KERNEL`) adds SQLite-backed sagas, a mutation WAL, ownership gates, replayable mutations, and operator-facing health and cost persistence—without changing the high-level “ask the model, run tools” loop.
+
+---
+
+## Core agent capabilities
+
+| Capability | Status | Primary code | Related docs |
+|------------|--------|--------------|--------------|
+| Multi-turn chat with tool loop | stable | `lib/ollama_agent/agent.rb`, `lib/ollama_agent/agent/turn_loop.rb`, `lib/ollama_agent/agent/chat_coordinator.rb` | `docs/USAGE.md`, `README.md` |
+| Ollama `/api/chat` (blocking + streaming hooks) | stable | `lib/ollama_agent/ollama_connection.rb`, `lib/ollama_agent/providers/ollama.rb` | `README.md` |
+| OpenAI / Anthropic providers + router | stable / opt-in keys | `lib/ollama_agent/providers/*.rb` | `README.md`, `docs/USAGE.md` |
+| Built-in tools: `read_file`, `search_code`, `list_files`, `edit_file`, `write_file`, optional `run_shell` | stable | `lib/ollama_agent/tools/built_in_schemas.rb`, `lib/ollama_agent/sandboxed_tools.rb` | `README.md` |
+| **Prism Ruby index** (`search_code` modes: class, module, constant, method) | stable | `lib/ollama_agent/ruby_index*.rb`, `lib/ollama_agent/ruby_index_tool_support.rb` | `lib/ollama_agent/tools/built_in_schemas.rb` (schema text) |
+| Prompt **skills** (bundled + extra paths) | stable | `lib/ollama_agent/prompt_skills.rb`, `lib/ollama_agent/agent_prompt.rb` | `README.md`, `docs/USAGE.md` |
+| Deterministic **JSON skills** CLI (`skill list|run|pipeline`) | stable | `lib/ollama_agent/cli/skill_command.rb`, `lib/ollama_agent/skills/` | `README.md`, `docs/CLI.md` |
+| **Sessions** (save / resume transcript) | stable | `lib/ollama_agent/session/store.rb`, `lib/ollama_agent/cli.rb` (`sessions`) | `README.md` |
+| **TUI** + line REPL | stable | `lib/ollama_agent/cli/tui_repl.rb`, `lib/ollama_agent/cli/repl.rb` | `README.md`, `docs/CLI.md` |
+| Orchestrator tools + `orchestrate` | opt-in | `lib/ollama_agent/external_agents.rb`, `lib/ollama_agent/cli.rb` | `README.md` |
+| Permissions / policies / approval gate | stable | `lib/ollama_agent/runtime/permissions.rb`, `lib/ollama_agent/runtime/policies.rb`, `lib/ollama_agent/runtime/approval_gate.rb` | `README.md`, `docs/USAGE.md` |
+| Loop detection, budget, context trim | stable | `lib/ollama_agent/core/loop_detector.rb`, `lib/ollama_agent/context/manager.rb` | `README.md` |
+| Self-review / improve (sandbox modes) | stable | `lib/ollama_agent/self_improvement/`, `lib/ollama_agent/cli.rb` | `README.md`, `docs/CLI.md` |
+| Plugins | experimental | `lib/ollama_agent/plugins/loader.rb` | `README.md` |
+
+---
+
+## Kernel runtime capabilities
+
+Enabled when `OLLAMA_AGENT_KERNEL` is `true` or `shadow` (`lib/ollama_agent/runtime/kernel_feature.rb`). Tool subset routed through the pipeline is configurable via `OLLAMA_AGENT_KERNEL_PIPELINE_TOOLS` (see `lib/ollama_agent/runtime/kernel_bridge.rb`).
+
+| Capability | Status | Primary code | Related docs |
+|------------|--------|--------------|--------------|
+| Saga FSM (reserved → locked → mutations_applied → verified → integration_queued → committed / compensated) | stable (flagged) | `lib/ollama_agent/runtime/saga_state.rb`, `lib/ollama_agent/runtime/saga_coordinator.rb`, `lib/ollama_agent/runtime/kernel_pipeline.rb` | `docs/agile/release_rollout_runbook.md`, `docs/OPERATIONS.md` |
+| **Shadow** execution (WAL + saga without real byte swap for configured ops) | opt-in | `lib/ollama_agent/runtime/execution_mode.rb`, `lib/ollama_agent/runtime/kernel_pipeline.rb` | `docs/agile/release_rollout_runbook.md` |
+| Atomic mutations (CAS, blobs, compensation rows) | stable (flagged) | `lib/ollama_agent/runtime/atomic_mutator.rb`, `lib/ollama_agent/runtime/blob_store.rb`, `lib/ollama_agent/runtime/compensation_engine.rb` | `docs/OPERATIONS.md` |
+| Ownership index + compiler (`owners.yml`) | opt-in file | `lib/ollama_agent/security/ownership_compiler.rb`, `lib/ollama_agent/security/ownership_index.rb`, `config/ollama_agent/owners.yml` | `docs/USAGE.md`, `docs/OPERATIONS.md` |
+| Permission bridge (legacy vs kernel) | stable (flagged) | `lib/ollama_agent/runtime/permission_bridge.rb` | `README.md` |
+| Recovery / leases / fencing | stable (flagged) | `lib/ollama_agent/runtime/saga_recovery_daemon.rb`, `lib/ollama_agent/runtime/lock_manager.rb`, `lib/ollama_agent/runtime/fencing_allocator.rb` | `docs/OPERATIONS.md` |
+| Post-mutation validation (isolated validator optional Docker) | experimental / CI-gated | `lib/ollama_agent/runtime/isolated_validator.rb` | `docs/agile/docker_spec_activation.md` |
+| Mutation WAL + global replay | stable (flagged) | `lib/ollama_agent/runtime/wal.rb`, `lib/ollama_agent/runtime/event_store.rb`, `lib/ollama_agent/runtime/workspace_wal_replay.rb` | `docs/USAGE.md`, `docs/OPERATIONS.md` |
+| **LLM boundary** (no wall-clock on saga path; cloud router uses separate clock for breakers only) | stable | `lib/ollama_agent/llm/cloud_fallback_router.rb`, `lib/ollama_agent/llm/anthropic_client.rb` | `docs/USAGE.md` |
+| Topology (IR, symbol graph, linker) | stable library | `lib/ollama_agent/topology/` | `docs/new_features_plan_v2.md` |
+| Integration synthesis | stable library | `lib/ollama_agent/synthesis/` | `docs/new_features_plan_v2.md` |
+| Kernel event JSON logging | stable | `lib/ollama_agent/runtime/kernel_event_logger.rb` | `docs/OPERATIONS.md` |
+
+---
+
+## Operational tooling
+
+| Capability | Status | Primary code | Related docs |
+|------------|--------|--------------|--------------|
+| Feature flag `OLLAMA_AGENT_KERNEL` (`false` / `shadow` / `true`) | stable | `lib/ollama_agent/runtime/kernel_feature.rb` | `docs/agile/release_rollout_runbook.md`, `docs/OPERATIONS.md` |
+| **Kernel health** CLI (`ollama_agent kernel health`) | stable | `lib/ollama_agent/cli/health_command.rb`, `lib/ollama_agent/runtime/kernel_health.rb` | `docs/CLI.md`, `docs/OPERATIONS.md` |
+| **Schema migrations** (versioned SQL under `db/ollama_agent/migrations/`) | stable | `lib/ollama_agent/runtime/schema_migrator.rb`, `lib/ollama_agent/runtime/database_registry.rb` | `docs/OPERATIONS.md` |
+| **Cost ledger** (runtime SQLite `cost_ledger` + `CloudFallbackRouter`) | stable | `lib/ollama_agent/runtime/cost_ledger.rb`, `lib/ollama_agent/llm/cloud_fallback_router.rb` | `docs/USAGE.md` |
+| **RollbackSignals** (in-memory thresholds for operators) | stable | `lib/ollama_agent/runtime/rollback_signals.rb` | `docs/OPERATIONS.md` |
+| Compaction + archive DB | opt-in operator job | `lib/ollama_agent/runtime/compactor.rb`, `lib/ollama_agent/runtime/compactor_runner.rb` | `docs/agile/release_rollout_runbook.md`, `docs/OPERATIONS.md` |
+| Audit / trace hooks | opt-in env | `lib/ollama_agent/resilience/audit_logger.rb`, `lib/ollama_agent/core/trace_logger.rb` | `README.md` |
+
+---
+
+## Test coverage summary (684 examples)
+
+The suite is **RSpec** under `spec/`. Approximate layers:
+
+| Layer | Paths | What is exercised |
+|-------|--------|---------------------|
+| Agent + tools | `spec/ollama_agent/agent_spec.rb`, `spec/ollama_agent/sandboxed_tools_spec.rb`, tool schema specs | Chat loop, tool execution, path sandbox, read-only mode |
+| Providers / LLM | `spec/ollama_agent/providers/`, `spec/ollama_agent/llm/` | Ollama/OpenAI/Anthropic adapters, retry + streaming client, cloud router + cost ledger |
+| Kernel runtime | `spec/ollama_agent/runtime/` | Database registry + migrations, saga, WAL, bridge, pipeline, health, blob store, compactor, permissions |
+| Integration | `spec/integration/` | Legacy path without kernel; optional real-Ollama smoke (`OLLAMA_HOST`) |
+| Self-improvement / CLI | `spec/ollama_agent/self_improvement/`, CLI-related specs where present | Modes, harness behavior |
+
+Counts are from `bundle exec rspec` (includes pending examples for Docker and opt-in real LLM).
+
+---
+
+## Related documentation
+
+| Document | Role |
+|----------|------|
+| `README.md` | Install, quick usage, kernel summary |
+| `docs/CLI.md` | Subcommand and flag reference |
+| `docs/USAGE.md` | End-user workflows |
+| `docs/OPERATIONS.md` | Rollout, incidents, SQL, compaction, health |
+| `docs/agile/release_rollout_runbook.md` | Kernel rollout stages (cross-ref operations) |
+| `docs/new_features_plan_v2.md` | Design backlog and architecture notes |
+| `docs/agile/docker_spec_activation.md` | Isolated validator / Docker |

data/docs/CLI.md

@@ -0,0 +1,212 @@
+# ollama_agent CLI reference
+
+Entry point: `exe/ollama_agent` → `OllamaAgent::CLI` (`lib/ollama_agent/cli.rb`). **Thor** is used; `CLI.exit_on_failure?` is **true**, so uncaught errors typically yield **exit code 1**.
+
+**Default task:** `ask`. Invoking `ollama_agent` with no subcommand runs `ask` (same as `ollama_agent ask`).
+
+**Global behavior:** many commands call `load_plugins!` (see `Plugins::Loader`) when applicable.
+
+**Root resolution:** most commands use `OLLAMA_AGENT_ROOT` or `--root`, else current working directory (see `resolved_root_for_self_review` in `lib/ollama_agent/cli.rb`).
+
+---
+
+## `ask [QUERY]` (default)
+
+**Syntax:** `ollama_agent [options] [QUERY]` or `ollama_agent ask [options] [QUERY]`
+
+**Description:** Run one task with a query string, or enter **interactive** mode when `QUERY` is empty (TUI vs line REPL depends on `--interactive` / `--tui`; see `apply_session_interactive_tui_flags!`).
+
+**Common options** (from `lib/ollama_agent/cli.rb`):
+
+| Option | Alias | Meaning |
+|--------|-------|---------|
+| `--model` | | Model id (default from `OLLAMA_AGENT_MODEL` / client) |
+| `--interactive` | `-i` | Interactive session |
+| `--tui` | | TTY UI when interactive |
+| `--tui-god` | | Auto-pick first TUI choice (dangerous) |
+| `--read-only` | `-R` | No write/patch/delegation tools |
+| `--yes` | `-y` | Skip patch confirmation |
+| `--root` | | Project root |
+| `--timeout` | `-t` | HTTP timeout seconds (default 120) |
+| `--think` | | Thinking / reasoning level (model-specific) |
+| `--no-skills` | | Disable bundled skills (`OLLAMA_AGENT_SKILLS=0` equivalent) |
+| `--skill-paths` | | Colon-separated extra skill paths |
+| `--stream` | | Stream tokens (`OLLAMA_AGENT_STREAM=1` equivalent) |
+| `--audit` | | Audit log under `.ollama_agent/logs/` |
+| `--max-retries` | | HTTP retries (0 disables) |
+| `--session` | | Named session id |
+| `--resume` | | Resume session |
+| `--max-tokens` | | Context budget |
+| `--context-summarize` | | Summarize dropped context |
+| `--provider` | | `ollama` (default) \| `openai` \| `anthropic` \| `auto` |
+| `--permissions` | | `read_only` \| `standard` \| `developer` \| `full` |
+| `--trace` | | Structured trace (`OLLAMA_AGENT_TRACE=1`) |
+
+**Examples:**
+
+```bash
+bundle exec ollama_agent ask "Summarize lib/ for a newcomer"
+bundle exec ollama_agent ask --read-only -R "List risks only"
+bundle exec ollama_agent ask -y --root /path/to/repo "Apply the patch plan"
+bundle exec ollama_agent ask --session myfeat --resume "Continue where we left off"
+```
+
+**Exit codes:** `0` on success; `1` on agent/CLI errors (`run_single_shot_agent!` rescues and `exit 1`).
+
+---
+
+## `orchestrate [QUERY]`
+
+**Syntax:** `ollama_agent orchestrate [options] [QUERY]`
+
+Same interactive / TUI flags as `ask` where declared. Builds an agent with **orchestrator** enabled (`build_orchestrator_agent`). Adds delegation tools (`list_external_agents`, `delegate_to_agent`) per `README.md`.
+
+**Examples:**
+
+```bash
+bundle exec ollama_agent orchestrate "Delegate a subtask to claude if stuck"
+```
+
+**Exit codes:** same pattern as `ask`.
+
+---
+
+## `sessions`
+
+**Syntax:** `ollama_agent sessions [--root PATH]`
+
+Lists saved session ids for the resolved root (`Session::Store.list`).
+
+**Exit codes:** `0`.
+
+---
+
+## `agents` and `doctor`
+
+**Syntax:** `ollama_agent agents` — `ollama_agent doctor` is an **alias** for `agents`.
+
+Prints external CLI agent registry probe table (`ExternalAgents::Registry`, `ExternalAgents::Probe`).
+
+**Exit codes:** `0`.
+
+---
+
+## `self_review`
+
+**Syntax:** `ollama_agent self_review [options]`
+
+**Modes** (`--mode`, normalized in `SelfImprovement::Modes`):
+
+- `analysis` (default, aliases `1`, `readonly`) — read-only tools, report.
+- `interactive` (`2`, `fix`, `confirm`) — full tools, confirm patches (`--yes` / `--semi`).
+- `automated` (`3`, `sandbox`, `full`) — sandbox copy, agent, `bundle exec rspec`, optional `--apply`.
+
+**Notable options:** `--root`, `--timeout`, `--think`, `--yes`, `--semi`, `--apply` (automated), `--verify` (automated), `--no-skills`, `--skill-paths`, `--stream`, `--max-tokens`, `--context-summarize`, `--no-ruby-mastery`.
+
+**Examples:**
+
+```bash
+bundle exec ollama_agent self_review --mode analysis
+bundle exec ollama_agent self_review --mode interactive --root .
+bundle exec ollama_agent self_review --mode automated --apply --yes
+```
+
+**Exit codes:** `1` if improve/verify fails (see `report_improve_result`); `0` on success paths.
+
+---
+
+## `improve`
+
+**Syntax:** `ollama_agent improve [options]`
+
+Shortcut for **`self_review --mode automated`**. Rejects non-automated modes (`ensure_improve_mode_only_automated!`).
+
+**Exit codes:** same as automated self_review.
+
+---
+
+## `skill` (subcommand)
+
+Defined in `lib/ollama_agent/cli/skill_command.rb`, mounted as `CLI.subcommand "skill", CLI::SkillCommand`.
+
+### `skill list`
+
+**Syntax:** `ollama_agent skill list`
+
+Prints registered skill names (`Skills.registry.names`).
+
+**Exit codes:** `0`.
+
+### `skill run NAME`
+
+**Syntax:** `ollama_agent skill run NAME [--code-file PATH] [--requirements TEXT] [--error TEXT] [--model MODEL]`
+
+Runs one skill; prints **JSON** (`JSON.pretty_generate`).
+
+**Exit codes:** `0` on success; Thor raises on missing file / errors (→ process exit `1` with `exit_on_failure?`).
+
+**Example:**
+
+```bash
+ollama_agent skill run architecture_refactor --code-file lib/foo.rb
+```
+
+### `skill pipeline NAME [NAME ...]`
+
+**Syntax:** `ollama_agent skill pipeline SKILL [SKILL ...] [same options as run]`
+
+Runs a deterministic pipeline of skills.
+
+**Example:**
+
+```bash
+ollama_agent skill pipeline architecture_refactor performance_optimizer --code-file lib/foo.rb
+```
+
+---
+
+## `kernel` (subcommand)
+
+Defined in `lib/ollama_agent/cli/health_command.rb` as `CLI::KernelHealthCommand`, mounted `CLI.subcommand "kernel", ...`.
+
+### `kernel health`
+
+**Syntax:** `ollama_agent kernel health [--root PATH]`
+
+Opens kernel SQLite under `<root>/.ollama_agent/kernel/`, runs `KernelHealth#check`, prints **one JSON object** to stdout.
+
+**Exit codes:**
+
+- `0` if top-level `"status"` is `"ok"`.
+- `1` if `"degraded"` or `"unhealthy"` (or any non-ok status).
+
+**Example:**
+
+```bash
+bundle exec ollama_agent kernel health --root /path/to/repo
+```
+
+Interpretation of `checks` keys: see `docs/OPERATIONS.md`.
+
+---
+
+## Thor / invocation notes
+
+- **Subcommand spelling:** use spaces (`ollama_agent kernel health`), not a colon.
+- **Default executable:** after `gem install`, `ollama_agent` on `PATH`; from source often `bundle exec ruby exe/ollama_agent …`.
+- **Help:** `ollama_agent help`, `ollama_agent help ask`, `ollama_agent help skill`, `ollama_agent help kernel`.
+
+---
+
+## Quick reference table
+
+| Command | Purpose |
+|---------|---------|
+| `ask` / (no subcommand) | Main agent |
+| `orchestrate` | Agent + external CLI delegation |
+| `sessions` | List sessions |
+| `agents`, `doctor` | External agent probe |
+| `self_review` | Analysis / interactive / automated improvement |
+| `improve` | Automated self_review only |
+| `skill list\|run\|pipeline` | Deterministic JSON skills |
+| `kernel health` | Kernel DB + blob + schema readiness JSON |