omegon 0.6.0

package/.gitattributes

@@ -0,0 +1,3 @@
+# Memory sync: keep all lines from both sides on merge.
+# importFromJsonl deduplicates by content_hash, so redundant lines are harmless.
+.pi/memory/facts.jsonl merge=union

package/AGENTS.md

@@ -0,0 +1,16 @@
+# Omegon Project Directives
+
+> Global directives (attribution, completion standards, memory sync, branch hygiene) are deployed automatically to `~/.pi/agent/AGENTS.md` by the defaults extension on first session start. They apply to all projects. To customize, edit that file — but remove the `<!-- managed by Omegon -->` marker or your changes will be overwritten on update.
+
+## Contributing
+
+This repo follows trunk-based development on `main`. The full policy is in `CONTRIBUTING.md` — read it with the `read` tool if you need branch naming conventions, the memory sync architecture details, or scaling guidance.
+
+Key points for working on Omegon itself:
+
+- **Direct commits to `main`** for single-file fixes, typos, config tweaks
+- **Feature branches** (`feature/<name>`, `refactor/<name>`) for multi-file or multi-session work
+- **Conventional commits** required — see `skills/git/SKILL.md` for the spec
+- The `.gitattributes` in this repo declares `merge=union` for `.pi/memory/facts.jsonl`
+- The `.pi/.gitignore` excludes `memory/*.db` files — only `facts.jsonl` is tracked
+- **Type checking**: `npx tsc --noEmit` must pass before committing TypeScript changes. Run `npm run typecheck` or `npm run check` (typecheck + tests).

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Chris Wilson
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# Omegon
+
+A batteries-included extension package for the pi coding agent. Adds persistent project memory, spec-driven development, local LLM inference, image generation, web search, parallel task decomposition, a live dashboard, and quality-of-life tools — all loadable with a single install.
+
+## Installation
+
+Omegon runs on top of a patched fork of the pi coding agent (`@cwilson613/pi-coding-agent`). The fork is published to npm and tracks upstream [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono) daily, adding targeted fixes for OAuth login reliability and bracketed-paste input handling.
+
+**Step 1 — Install the pi binary from the patched fork:**
+
+```bash
+npm install -g @cwilson613/pi-coding-agent
+```
+
+**Step 2 — Install Omegon extensions:**
+
+```bash
+pi install https://github.com/cwilson613/omegon
+```
+
+**Step 3 — First-time setup:**
+
+```bash
+pi          # start pi in any project directory
+/bootstrap  # check deps, install missing tools, configure preferences
+```
+
+### Keeping up to date
+
+| What to update | How |
+|----------------|-----|
+| **Omegon extensions** | `/update` or `pi update` (tracks `main` branch) |
+| **pi binary** | `/update-pi` — checks npm for latest `@cwilson613/pi-coding-agent`, prompts before installing |
+
+> The patched fork syncs from upstream daily via GitHub Actions. Bug fixes and new AI provider support land automatically. If a sync PR has conflicts, they are surfaced for manual review before merging — upstream changes are never silently dropped.
+
+> **Note:** `pi install` and `pi update` track the `main` branch. The version-check extension notifies you when a new Omegon release is available.
+
+## Architecture
+
+![Omegon Architecture](docs/img/architecture.png)
+
+Omegon extends `@cwilson613/pi-coding-agent` with **27 extensions**, **12 skills**, and **4 prompt templates** — loaded automatically on session start.
+
+### Development Methodology
+
+Omegon enforces **spec-first development** for non-trivial changes:
+
+![Spec-Driven Pipeline](docs/img/spec-pipeline.png)
+
+The full lifecycle: **design → propose → spec → plan → implement → verify → archive**. Given/When/Then scenarios are the source of truth for correctness — code implements the specs, not the reverse.
+
+## Extensions
+
+### 📋 OpenSpec
+
+Spec-driven development lifecycle — proposal → specs → design → tasks workflow with delta-spec merge on archive.
+
+- **Tool**: `openspec_manage`
+- **Commands**: `/opsx:propose`, `/opsx:spec`, `/opsx:ff`, `/opsx:status`, `/opsx:verify`, `/opsx:archive`, `/opsx:sync`
+- **Lifecycle stages**: proposed → specified → planned → implementing → verifying → archived
+- **API contracts**: When a change involves a network API, derives an OpenAPI 3.1 spec from Given/When/Then scenarios; `/assess spec` validates implementation against it
+- Integrates with [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec) profiles
+
+### 🪓 Cleave
+
+Parallel task decomposition with dependency-ordered wave dispatch in isolated git worktrees.
+
+- **Tools**: `cleave_assess` (complexity evaluation), `cleave_run` (parallel dispatch)
+- **Commands**: `/cleave <directive>`, `/assess cleave`, `/assess diff`, `/assess spec`
+- **OpenSpec integration**: Uses `tasks.md` as the split plan when `openspec/` exists, enriches child tasks with design decisions and spec acceptance criteria, reconciles task completion on merge, guides through verify → archive
+- **Skill-aware dispatch**: Auto-matches skill files to children based on file scope patterns (e.g. `*.py` → python, `Containerfile` → oci). Annotations (`<!-- skills: python, k8s -->`) override auto-matching
+- **Model tier routing**: Each child resolves an execution tier — explicit annotation > skill-based hint > default. Provider-neutral tier labels resolve to concrete models through the session routing policy
+- **Adversarial review loop** (opt-in via `review: true`): After each child completes, an opus-tier reviewer checks for bugs, security issues, and spec compliance. Severity-gated: nits→accept, warnings→1 fix iteration, criticals→2 fixes then escalate, security→immediate escalate. Churn detection bails when >50% of issues reappear between rounds
+- **Large-run preflight**: Asks which provider to favor before expensive dispatches, preventing mid-run subscription exhaustion
+
+### 🌲 Design Tree
+
+Structured design exploration with persistent markdown documents — the upstream of OpenSpec.
+
+- **Tools**: `design_tree` (query), `design_tree_update` (create/mutate nodes)
+- **Commands**: `/design list`, `/design new`, `/design update`, `/design branch`, `/design decide`, `/design implement`
+- **Document structure**: Frontmatter (status, tags, dependencies, priority, issue_type, open questions) + sections (Overview, Research, Decisions, Open Questions, Implementation Notes)
+- **Work triage**: `design_tree(action="ready")` returns all decided, dependency-resolved nodes sorted by priority — the session-start "what next?" query
+- **Blocked audit**: `design_tree(action="blocked")` returns all stalled nodes with each blocking dependency's id, title, and status
+- **Priority**: `set_priority` (1 = critical → 5 = trivial) on any node; `ready` auto-sorts by it
+- **Issue types**: `set_issue_type` classifies nodes as `epic | feature | task | bug | chore` — bugs and chores are now first-class tracked work
+- **OpenSpec bridge**: `design_tree_update` with `action: "implement"` scaffolds `openspec/changes/<node-id>/` from a decided node's content; `/cleave` executes it
+- **Full pipeline**: design → decide → implement → `/cleave` → `/assess spec` → archive
+
+### 🧠 Project Memory
+
+Persistent, cross-session knowledge stored in SQLite. Accumulates architectural decisions, constraints, patterns, and known issues — retrieved semantically each session.
+
+- **11 tools**: `memory_store`, `memory_recall`, `memory_query`, `memory_supersede`, `memory_archive`, `memory_connect`, `memory_compact`, `memory_episodes`, `memory_focus`, `memory_release`, `memory_search_archive`
+- **Semantic retrieval**: Embedding-based search via Ollama (`qwen3-embedding`), falls back to FTS5 keyword search
+- **Background extraction**: Auto-discovers facts from tool output without interrupting work
+- **Episodic memory**: Generates session narratives at shutdown for "what happened last time" context
+- **Global knowledge base**: Cross-project facts at `~/.pi/memory/global.db`
+- **Git sync**: Exports to JSONL for version-controlled knowledge sharing across machines
+
+![Memory Lifecycle](docs/img/memory-lifecycle.png)
+
+### 📊 Dashboard
+
+Live status panel showing design tree, OpenSpec changes, cleave dispatch, and git branches at a glance.
+
+- **Commands**: `/dash` (toggle compact ↔ raised), `/dashboard` (open side panel)
+- **Compact mode**: Single footer line — design/openspec/cleave summaries + context gauge
+- **Raised mode**: Full-width expanded view (toggle with `/dash`)
+  - Git branch tree rooted at repo name, annotated with linked design nodes
+  - Two-column split at ≥120 terminal columns: design tree + cleave left, OpenSpec right
+  - Context gauge · model · thinking level in shared footer zone
+  - No line cap — renders as much content as needed
+- **Keyboard**: `Ctrl+Shift+B` toggles raised/compact
+
+### 🌐 Web UI
+
+Localhost-only, read-only HTTP dashboard that exposes live control-plane state as JSON. It binds to `127.0.0.1`, is not started automatically, and serves no mutation endpoints in the MVP.
+
+- **Command**: `/web-ui [start|stop|status|open]`
+- **Shell**: polling-first HTML dashboard
+- **Endpoints**: `GET /api/state`, plus slice routes `/api/session`, `/api/dashboard`, `/api/design-tree`, `/api/openspec`, `/api/cleave`, `/api/models`, `/api/memory`, `/api/health`
+- **State contract**: versioned `ControlPlaneState` (schema v1)
+
+### ⚔️ Effort Tiers
+
+Single global knob controlling the inference intensity across the entire harness. Seven named tiers using provider-neutral labels — tier labels resolve to concrete model IDs from whichever provider (Anthropic or OpenAI) the session routing policy prefers.
+
+| Tier | Name | Driver | Thinking | Review |
+|------|------|--------|----------|--------|
+| 1 | **Servitor** | local | off | local |
+| 2 | **Average** | local | minimal | local |
+| 3 | **Substantial** | sonnet | low | sonnet |
+| 4 | **Ruthless** | sonnet | medium | sonnet |
+| 5 | **Lethal** | sonnet | high | opus |
+| 6 | **Absolute** | opus | high | opus |
+| 7 | **Omnissiah** | opus | high | opus |
+
+- `/effort <name>` — switch tier mid-session
+- `/effort cap` — lock current tier as ceiling; agent cannot self-upgrade past it
+- `/effort uncap` — remove ceiling lock
+- Affects: driver model, thinking level, extraction, compaction, cleave child floor, review model
+
+### 🤖 Local Inference
+
+Delegate sub-tasks to locally running LLMs via Ollama — zero API cost.
+
+- **Tools**: `ask_local_model`, `list_local_models`
+- **Commands**: `/local-models`, `/local-status`
+- Auto-discovers available models on session start
+
+### 🔌 Offline Driver
+
+Switch the driving model from cloud to a local Ollama model when connectivity drops or for fully offline operation.
+
+- **Tool**: `switch_to_offline_driver`
+- Auto-selects best available model from a hardware-aware preference list
+- Model registry in `extensions/lib/local-models.ts` — one file to update when new models land
+- Covers: 64GB (70B), 32GB (32B), 24GB (14B/MoE-30B), 16GB (8B), 8GB (4B)
+
+### 💰 Model Budget
+
+Switch model tiers to match task complexity and conserve API spend. Tier labels are provider-neutral — resolved at runtime through the session routing policy.
+
+- **Tool**: `set_model_tier` — `opus` / `sonnet` / `haiku` / `local`
+- **Tool**: `set_thinking_level` — `off` / `minimal` / `low` / `medium` / `high`
+- Downgrade for routine edits, upgrade for architecture decisions
+- Respects effort tier cap — cannot upgrade past a locked ceiling
+
+### 🎨 Render
+
+Generate images and diagrams directly in the terminal.
+
+- **FLUX.1 image generation** via MLX on Apple Silicon — `generate_image_local`
+- **D2 diagrams** rendered inline — `render_diagram`
+- **Native SVG/PNG diagrams** for canonical motifs (pipeline, fanout, panel-split) — `render_native_diagram`
+- **Excalidraw** JSON-to-PNG rendering — `render_excalidraw`
+
+### 🔍 Web Search
+
+Multi-provider web search with deduplication.
+
+- **Tool**: `web_search`
+- **Providers**: Brave, Tavily, Serper (Google)
+- **Modes**: `quick` (single provider, fastest), `deep` (more results), `compare` (all providers, best for research)
+
+### 🗂️ Tool Profiles
+
+Enable or disable tools and switch named profiles to keep the context window lean.
+
+- **Tool**: `manage_tools`
+- **Command**: `/profile [name|reset]`
+- Pre-built profiles for common workflows; per-tool enable/disable for fine-grained control
+
+### 📖 Vault
+
+Markdown viewport for project documentation — serves docs with wikilink navigation and graph view.
+
+- **Command**: `/vault`
+
+### 🔐 Secrets
+
+Resolve secrets from environment variables, shell commands, or system keychains — without storing values in config.
+
+- Declarative `@secret` annotations in extension headers
+- Sources: `env:`, `cmd:`, `keychain:`
+
+### 🌐 MCP Bridge
+
+Connect external MCP (Model Context Protocol) servers as native pi tools.
+
+- Bridges MCP tool schemas into pi's tool registry
+- Stdio transport for local MCP servers
+
+### 🔧 Utilities
+
+| Extension | Description |
+|-----------|-------------|
+| `bootstrap` | First-time setup — check/install dependencies, capture operator preferences (`/bootstrap`, `/refresh`, `/update-pi`) |
+| `chronos` | Authoritative date/time from system clock — eliminates AI date math errors |
+| `01-auth` | Auth status, diagnosis, and refresh across git, GitHub, GitLab, AWS, k8s, OCI (`/auth`, `/whoami`) |
+| `view` | Inline file viewer — images, PDFs, docs, syntax-highlighted code |
+| `distill` | Context distillation for session handoff (`/distill`) |
+| `session-log` | Append-only structured session tracking |
+| `auto-compact` | Context pressure monitoring with automatic compaction |
+| `defaults` | Deploys `AGENTS.md` and theme on first install; content-hash guard prevents overwriting customizations |
+| `terminal-title` | Dynamic tab titles showing active cleave runs and git branch |
+| `spinner-verbs` | Warhammer 40K-themed loading messages |
+| `style` | Alpharius design system reference (`/style`) |
+| `version-check` | Polls GitHub releases hourly, notifies when a new Omegon release is available |
+| `web-ui` | Localhost-only read-only HTTP dashboard and JSON control-plane endpoints (`/web-ui [start|stop|status|open]`) |
+
+## Skills
+
+Skills provide specialized instructions the agent loads on-demand when a task matches.
+
+| Skill | Description |
+|-------|-------------|
+| `openspec` | OpenSpec lifecycle — writing specs, deriving API contracts, generating tasks, verifying implementations |
+| `cleave` | Task decomposition, code assessment, OpenSpec lifecycle integration |
+| `git` | Conventional commits, semantic versioning, branch naming, changelogs |
+| `oci` | Container and artifact best practices — Containerfile authoring, multi-arch builds, registry auth |
+| `python` | Project setup (src/ layout, pyproject.toml), pytest, ruff, mypy, packaging, venv |
+| `rust` | Cargo, clippy, rustfmt, Zellij WASM plugin development |
+| `typescript` | Strict typing, async patterns, error handling, node:test conventions for Omegon |
+| `pi-extensions` | pi extension API — `registerCommand`, `registerTool`, event handlers, TUI context, common pitfalls |
+| `pi-tui` | TUI component patterns — `Component` interface, overlays, keyboard handling, theming, footer/widget APIs |
+| `security` | Input escaping, injection prevention, path traversal, process safety, secrets management |
+| `style` | Alpharius color system, typography, spacing — shared across TUI, D2 diagrams, and generated images |
+| `vault` | Obsidian-compatible markdown conventions — wikilinks, frontmatter, vault-friendly file organization |
+
+## Prompt Templates
+
+Pre-built prompts for common workflows:
+
+| Template | Description |
+|----------|-------------|
+| `new-repo` | Scaffold a new repository with conventions |
+| `init` | First-session environment check — orient to a new project directory |
+| `status` | Session orientation — load project state and show what's active |
+| `oci-login` | OCI registry authentication |
+
+## Requirements
+
+**Required:**
+- `@cwilson613/pi-coding-agent` ≥ 0.57 — patched fork of [badlogic/pi-mono](https://github.com/badlogic/pi-mono). Install via `npm install -g @cwilson613/pi-coding-agent`. Fork source: [cwilson613/pi-mono](https://github.com/cwilson613/pi-mono)
+
+**Optional (installed by `/bootstrap`):**
+- [Ollama](https://ollama.ai) — local inference, offline mode, semantic memory search
+- [d2](https://d2lang.com) — diagram rendering
+- [mflux](https://github.com/filipstrand/mflux) — FLUX.1 image generation on Apple Silicon
+- API keys for web search (Brave, Tavily, or Serper)
+
+Run `/bootstrap` after install to check dependencies and configure preferences.
+
+## Why a Patched Fork?
+
+Upstream [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono) is the canonical pi coding agent. Omegon depends on a fork rather than the upstream package for two reasons:
+
+1. **OAuth login reliability** — upstream had no fetch timeout on OAuth token exchange calls. A slow or unreachable endpoint would hang the login UI indefinitely with no recovery path. Fixed in [`packages/ai/src/utils/oauth/`](https://github.com/cwilson613/pi-mono/tree/main/packages/ai/src/utils/oauth).
+
+2. **Bracketed-paste stuck state** — a missing end-marker (e.g. from a large paste that split across chunks) would leave `isInPaste = true` permanently, silently swallowing all subsequent keystrokes including Enter. Fixed with a 500ms watchdog timer and Escape-to-clear in [`packages/tui/src/components/input.ts`](https://github.com/cwilson613/pi-mono/blob/main/packages/tui/src/components/input.ts).
+
+Both fixes are submitted as PRs to upstream ([#2060](https://github.com/badlogic/pi-mono/pull/2060), [#2061](https://github.com/badlogic/pi-mono/pull/2061)). Once merged, the fork becomes a pass-through and the dependency can revert to `@mariozechner/pi-coding-agent`.
+
+## License
+
+ISC

package/bin/pi.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Omegon pi entry point.
+ *
+ * Sets PI_CODING_AGENT_DIR to the omegon package root so pi loads all agent
+ * configuration (extensions, themes, skills, AGENTS.md) from omegon rather
+ * than from ~/.pi/agent/.
+ *
+ * Resolution order for pi core:
+ *   1. vendor/pi-mono (dev mode — git submodule present)
+ *   2. node_modules/@cwilson613/pi-coding-agent (installed via npm)
+ */
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const omegonRoot = dirname(dirname(__filename));
+
+// Only set if not already overridden
+if (!process.env.PI_CODING_AGENT_DIR) {
+  process.env.PI_CODING_AGENT_DIR = omegonRoot;
+}
+
+// Resolve pi core: prefer vendor/ (dev), fall back to node_modules/ (installed)
+const vendorCli = join(omegonRoot, "vendor/pi-mono/packages/coding-agent/dist/cli.js");
+const npmCli = join(omegonRoot, "node_modules/@cwilson613/pi-coding-agent/dist/cli.js");
+
+const cli = existsSync(vendorCli) ? vendorCli : npmCli;
+await import(cli);