omegon-pi 0.12.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/.omegon/profile.json

@@ -0,0 +1,7 @@
+{
+  "lastUsedModel": {
+    "provider": "anthropic",
+    "modelId": "claude-opus-4-20250514"
+  },
+  "thinkingLevel": "low"
+}

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/ARCHIVE_NOTE.md

@@ -0,0 +1,28 @@
+# Omegon-Pi (Archived)
+
+This is the legacy TypeScript-based Omegon harness built on the pi coding agent framework.
+
+**This repository is archived.** The active Omegon development continues in the Rust-native binary:
+- **[omegon](https://github.com/styrene-lab/omegon)** — main repo (design docs, skills, specs, Rust binary)
+- **[omegon-core](https://github.com/styrene-lab/omegon-core)** — Rust workspace
+
+## What's Here
+
+- `extensions/` — Pi extensions (secrets, auth, memory, cleave, design-tree, openspec, dashboard, etc.)
+- `vendor/pi-mono` — Fork of the pi coding agent framework
+- `bin/` — Node.js entrypoints (omegon.mjs, pi.mjs)
+- `npm/` — Platform-specific npm packages
+- `skills/` — Markdown skill definitions (shared with Rust repo)
+- `themes/` — Alpharius theme (shared with Rust repo)
+
+## Install (Legacy)
+
+```sh
+npm install -g omegon
+```
+
+Requires Node.js 20+.
+
+## License
+
+BSL 1.1 — © 2024–2026 Black Meridian, LLC

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,296 @@
+# Omegon
+
+An opinionated distribution of [**pi**](https://github.com/badlogic/pi) — the coding agent by [Mario Zechner](https://github.com/badlogic). Omegon bundles pi core with extensions for persistent project memory, spec-driven development, local LLM inference, image generation, web search, parallel task decomposition, a live dashboard, and quality-of-life tools.
+
+> **Relationship to pi:** Omegon is not a fork or replacement. It packages pi as a dependency and layers extensions on top. All credit for the pi coding agent goes to Mario Zechner and the pi contributors. The core pi packages are migrating to the styrene-lab-owned npm scope (`@styrene-lab/pi-coding-agent` and related packages) so package ownership matches the `styrene-lab/omegon` product boundary. Older `@cwilson613/*` package names are compatibility debt during the transition, not the long-term release boundary. If you want standalone pi without Omegon's extensions, install `@mariozechner/pi-coding-agent` directly.
+
+## Installation
+
+```bash
+npm install -g omegon-pi
+```
+
+**Node requirement:** Omegon requires **Node.js 20+**. Node 18 will fail because bundled pi-tui uses modern Unicode regex features unsupported by older runtimes.
+
+This installs the canonical `omegon` command globally. A legacy `pi` alias may remain available for compatibility, but the supported lifecycle entrypoint is `omegon`. If a standalone pi package is already installed, omegon transparently takes ownership of the lifecycle boundary so startup, update, verification, and restart all stay inside Omegon control. To switch back to standalone pi at any time:
+
+```bash
+npm uninstall -g omegon-pi
+npm install -g @mariozechner/pi-coding-agent
+```
+
+**First-time setup:**
+
+```bash
+omegon      # start Omegon in any project directory
+/bootstrap  # check deps, install missing tools, configure preferences
+```
+
+### Keeping up to date
+
+| Context | How |
+|--------|-----|
+| **Installed Omegon (`npm install -g omegon-pi`)** | Run `/update` from inside Omegon. Omegon installs the latest package, verifies the active `omegon` command still resolves to Omegon, clears caches, then asks you to restart Omegon. |
+| **Dev checkout / contributor workflow** | Run `/update` or `./scripts/install-pi.sh`. Both follow the same lifecycle contract: pull/sync, build, refresh dependencies, `npm link --force`, verify the active `omegon` target, then stop at an explicit restart handoff. |
+| **Lightweight cache refresh only** | Run `/refresh`. This clears transient caches and reloads extensions, but it is not equivalent to package/runtime replacement. |
+
+> 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:** `/update` is the authoritative Omegon update path. It intentionally ends at a verified restart boundary rather than hot-swapping the running process after package/runtime mutation.
+
+## Architecture
+
+![Omegon Architecture](docs/img/architecture.png)
+
+Omegon extends `@styrene-lab/pi-coding-agent` with **31 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
+- **Auto-transition**: Adding research or decisions to a `seed` node automatically transitions it to `exploring` and scaffolds the design spec — no manual ceremony
+- **Substance-over-ceremony gates**: `set_status(decided)` checks for open questions and recorded decisions instead of artifact directory existence. Design specs are auto-extracted from doc content and archived
+- **OpenSpec bridge**: `design_tree_update` with `action: "implement"` scaffolds `openspec/changes/<node-id>/` from a decided node's content, auto-checkouts the directive branch, forks a scoped memory mind, and sets design focus; `/cleave` executes it
+- **Full pipeline**: design → decide → implement (auto-checkout + mind fork) → `/cleave` → `/assess spec` → archive (mind merge-back + cleanup)
+
+### 🧠 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
+- **Directive minds**: `implement` forks a scoped memory mind from `default`; all fact reads/writes auto-scope to the directive. `archive` ingests discoveries back to `default` and cleans up. Zero-copy fork with parent-chain inheritance — no fact duplication, parent embeddings and edges are reused
+- **Global knowledge base**: Cross-project facts at `~/.pi/memory/global.db`
+- **Git sync**: Exports to JSONL for version-controlled knowledge sharing across machines; volatile runtime scoring metadata (confidence, reinforcement counts, decay scores) omitted from exports for stable diffs
+
+![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
+  - Directive indicator: shows `▸ directive: name ✓` (branch match) or `▸ directive: name ⚠ main` (mismatch) when a directive mind is active
+  - 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:**
+- `omegon-pi` — install via `npm install -g omegon-pi`; launch via `omegon-pi`
+- `@styrene-lab/pi-coding-agent` ≥ 0.57 underpins Omegon's bundled agent core and tracks a patched fork of [badlogic/pi-mono](https://github.com/badlogic/pi-mono). 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/omegon-pi.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * Omegon entry point.
+ *
+ * Keeps mutable user state in the shared pi-compatible agent directory while
+ * injecting Omegon-packaged resources from the installed package root.
+ *
+ * Resolution order for the underlying agent core:
+ *   1. vendor/pi-mono (dev mode — git submodule present)
+ *   2. node_modules/@styrene-lab/pi-coding-agent (installed via npm)
+ */
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const omegonRoot = dirname(dirname(__filename));
+const defaultStateDir = join(homedir(), ".pi", "agent");
+const stateDir = process.env.PI_CODING_AGENT_DIR || defaultStateDir;
+const usingExplicitStateOverride = Boolean(process.env.PI_CODING_AGENT_DIR);
+
+const vendorCli = join(omegonRoot, "vendor/pi-mono/packages/coding-agent/dist/cli.js");
+const npmCli = join(omegonRoot, "node_modules/@styrene-lab/pi-coding-agent/dist/cli.js");
+const cli = existsSync(vendorCli) ? vendorCli : npmCli;
+const resolutionMode = cli === vendorCli ? "vendor" : "npm";
+
+function migrateLegacyStatePath(relativePath, kind = "file") {
+  if (usingExplicitStateOverride) {
+    return;
+  }
+
+  const legacyPath = join(omegonRoot, relativePath);
+  const targetPath = join(stateDir, relativePath);
+  if (!existsSync(legacyPath) || existsSync(targetPath)) {
+    return;
+  }
+
+  mkdirSync(dirname(targetPath), { recursive: true });
+  if (kind === "directory") {
+    cpSync(legacyPath, targetPath, { recursive: true, force: false });
+    return;
+  }
+  copyFileSync(legacyPath, targetPath);
+}
+
+function injectBundledResourceArgs(argv) {
+  const injected = [...argv];
+  const pushPair = (flag, value) => {
+    if (existsSync(value)) {
+      injected.push(flag, value);
+    }
+  };
+
+  // Omegon is the sole authority for bundled resources.
+  // Suppress pi's auto-discovery of skills, prompts, and themes (which scans
+  // ~/.pi/agent/*, installed packages, and project .pi/ dirs) so only our
+  // manifest-declared resources load. The --no-* flags disable discovery
+  // but still allow CLI-injected paths (our --extension manifest).
+  // Extensions are NOT suppressed — project-local .pi/extensions/ should still work.
+  injected.push("--no-skills", "--no-prompt-templates", "--no-themes");
+  pushPair("--extension", omegonRoot);
+  return injected;
+}
+
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+  const pkg = JSON.parse(readFileSync(join(omegonRoot, "package.json"), "utf8"));
+  process.stdout.write(pkg.version + "\n");
+  process.exit(0);
+}
+
+if (process.argv.includes("--where")) {
+  process.stdout.write(JSON.stringify({
+    omegonRoot,
+    cli,
+    resolutionMode,
+    agentDir: stateDir,
+    stateDir,
+    executable: "omegon-pi",
+  }, null, 2) + "\n");
+  process.exit(0);
+}
+
+process.env.PI_CODING_AGENT_DIR = stateDir;
+
+// Suppress the upstream runtime's version check and changelog display.
+// Omegon has its own /update command and version-check extension —
+// the pi-coding-agent's built-in checks leak upstream version numbers.
+process.env.PI_SKIP_VERSION_CHECK = "1";
+migrateLegacyStatePath("auth.json");
+migrateLegacyStatePath("settings.json");
+migrateLegacyStatePath("sessions", "directory");
+
+// Force quiet startup — the splash extension provides the branded header.
+// This suppresses the built-in keybinding hints, expanded changelog, and
+// resource listing that pi's interactive mode normally renders before
+// extensions have a chance to set a custom header.
+function forceQuietStartup() {
+  try {
+    const settingsPath = join(stateDir, "settings.json");
+    mkdirSync(stateDir, { recursive: true });
+    let settings = {};
+    if (existsSync(settingsPath)) {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    }
+    let changed = false;
+    if (settings.quietStartup === undefined) {
+      settings.quietStartup = true;
+      changed = true;
+    }
+    if (settings.collapseChangelog === undefined) {
+      settings.collapseChangelog = true;
+      changed = true;
+    }
+    // Belt-and-suspenders: force lastChangelogVersion to a sentinel that is always
+    // semver-greater than any upstream changelog entry. This prevents the upstream
+    // "Updated to vX.Y.Z" banner even if PI_SKIP_VERSION_CHECK is somehow not set.
+    const SENTINEL_VERSION = "999.0.0";
+    if (settings.lastChangelogVersion !== SENTINEL_VERSION) {
+      settings.lastChangelogVersion = SENTINEL_VERSION;
+      changed = true;
+    }
+    if (changed) {
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+    }
+  } catch { /* best effort */ }
+}
+forceQuietStartup();
+
+function purgeSelfReferentialPackages() {
+  try {
+    const settingsPath = join(stateDir, "settings.json");
+    if (!existsSync(settingsPath)) return;
+    const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    if (!Array.isArray(settings.packages)) return;
+    const selfPatterns = [
+      /github\.com\/cwilson613\/omegon/i,
+      /github\.com\/cwilson613\/pi-kit/i,
+      /github\.com\/styrene-lab\/omegon/i,
+    ];
+    const filtered = settings.packages.filter(
+      (pkg) => !selfPatterns.some((re) => re.test(String(pkg))),
+    );
+    if (filtered.length === settings.packages.length) return;
+    settings.packages = filtered;
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  } catch { /* graceful failure — do not block startup */ }
+}
+purgeSelfReferentialPackages();
+
+// ---------------------------------------------------------------------------
+// CLI launch — subprocess with restart-loop support.
+//
+// Instead of importing the CLI directly (which makes restart impossible since
+// Node can't replace its own process image), we spawn it as a child process.
+// If the child exits with code 75 (EX_TEMPFAIL), we re-spawn — this is the
+// restart signal from /update and /restart commands.
+//
+// This keeps the wrapper as the foreground process group leader throughout,
+// so the re-spawned CLI always owns the terminal and can receive input.
+// ---------------------------------------------------------------------------
+import { spawn as nodeSpawn } from "node:child_process";
+
+const RESTART_EXIT_CODE = 75;
+
+const cliArgs = injectBundledResourceArgs(process.argv).slice(2);
+
+const isInteractive = process.stdout.isTTY &&
+  !process.argv.includes("-p") &&
+  !process.argv.includes("--print") &&
+  !process.argv.includes("--help") &&
+  !process.argv.includes("-h");
+
+function showPreImportSpinner() {
+  if (!isInteractive) return undefined;
+  const PRIMARY = "\x1b[38;2;42;180;200m";
+  const DIM = "\x1b[38;2;64;88;112m";
+  const RST = "\x1b[0m";
+  const HIDE_CURSOR = "\x1b[?25l";
+  const SHOW_CURSOR = "\x1b[?25h";
+  const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let frame = 0;
+
+  const restoreCursor = () => { try { process.stdout.write(SHOW_CURSOR); } catch {} };
+  process.on("exit", restoreCursor);
+
+  process.stdout.write(HIDE_CURSOR);
+  process.stdout.write(`\n  ${PRIMARY}omegon${RST} ${DIM}loading…${RST}`);
+
+  const spinTimer = setInterval(() => {
+    const s = spinner[frame % spinner.length];
+    process.stdout.write(`\r  ${PRIMARY}${s} omegon${RST} ${DIM}loading…${RST}`);
+    frame++;
+  }, 80);
+
+  return () => {
+    clearInterval(spinTimer);
+    process.removeListener("exit", restoreCursor);
+    process.stdout.write(`\r\x1b[2K${SHOW_CURSOR}`);
+  };
+}
+
+function launchCli() {
+  return new Promise((resolve) => {
+    const cleanup = showPreImportSpinner();
+
+    const child = nodeSpawn(process.execPath, [cli, ...cliArgs], {
+      stdio: "inherit",
+      env: process.env,
+    });
+
+    // Let the child handle SIGINT (Ctrl+C) — the wrapper ignores it.
+    const ignoreInt = () => {};
+    process.on("SIGINT", ignoreInt);
+    // Forward SIGTERM so graceful shutdown works.
+    const fwdTerm = () => child.kill("SIGTERM");
+    process.on("SIGTERM", fwdTerm);
+
+    // Clean up spinner once the child's TUI takes over. The child will
+    // clear the screen on startup anyway, but a brief delay ensures the
+    // spinner doesn't flicker.
+    if (cleanup) {
+      setTimeout(() => cleanup(), 200);
+    }
+
+    child.on("exit", (code, signal) => {
+      process.removeListener("SIGINT", ignoreInt);
+      process.removeListener("SIGTERM", fwdTerm);
+      if (signal) {
+        // Re-raise the signal so the wrapper exits with the right status
+        process.kill(process.pid, signal);
+      }
+      resolve(code ?? 1);
+    });
+  });
+}
+
+// Main loop — restart on exit code 75
+let exitCode;
+do {
+  exitCode = await launchCli();
+} while (exitCode === RESTART_EXIT_CODE);
+
+process.exit(exitCode);

package/bin/pi.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Legacy compatibility shim.
+ *
+ * `pi` remains available temporarily so existing installs are not stranded,
+ * but it immediately re-enters the same Omegon-owned executable boundary as
+ * the canonical `omegon-pi` command.
+ */
+await import("./omegon-pi.mjs");