@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/cli.py

@@ -1,13 +1,16 @@
 """The `omega` command-line interface.
 
 A thin entry point. The installer's doctor step calls `omega doctor`; operators
-use `omega status` to see every task's derived state.
+use `omega status` to see every task's derived state. `omega account ...` and
+`omega billing` give visibility into the Claude Code Max account pool — see
+`docs/ACCOUNT-AND-BILLING.md` for the design.
 """
 from __future__ import annotations
 
 import argparse
 import os
 import sys
+import time
 from pathlib import Path
 
 from omega_engine import __version__
@@ -22,24 +25,612 @@ def cmd_version(_args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_doctor(_args: argparse.Namespace) -> int:
-    """Validate an Omega OS deployment: the 8-block tree + the event store."""
+def cmd_doctor(args: argparse.Namespace) -> int:
+    """Validate an Omega OS deployment end-to-end.
+
+    Sections checked in order:
+      1. The 8-block tree (structural — fatal if missing)
+      2. The event store
+      3. The vault (backend + counts)
+      4. Provider router config + per-provider credentials
+      5. MCP catalog + installed tools
+      6. Account pool entries vs vault entries
+      7. Educator subsystem — the 8 self-improving educators load
+      8. Autonomous charters parseable
+      9. 24/7 services (systemd active state on Linux; launchctl on macOS)
+     10. Telegram bridge reachable (if a token is in the vault)
+
+    Each line is `[ok]`, `[warn]`, or `[FAIL]`. Exit code is 0 iff nothing
+    FAILed. `warn` does not flip the exit; it surfaces upgrade opportunities.
+
+    With ``--json``, prints a single JSON object instead of pretty text —
+    suitable for monitors and CI.
+    """
+    import os as _os
+    import shutil as _sh
+    import subprocess as _sp
+
+    json_mode: bool = bool(getattr(args, "json", False))
     home = _omega_home()
+    results: list[dict[str, str]] = []
+    if not json_mode:
+        print(f"omega doctor — OMEGA_HOME={home}")
+    any_fail = False
+    any_warn = False
+    current_section = "general"
+
+    def section(name: str) -> None:
+        nonlocal current_section
+        current_section = name
+        if not json_mode:
+            print(f"  -- {name} --")
+
+    def line(status: str, msg: str) -> None:
+        nonlocal any_fail, any_warn
+        if status == "FAIL":
+            any_fail = True
+        elif status == "warn":
+            any_warn = True
+        results.append({"section": current_section, "status": status, "msg": msg})
+        if not json_mode:
+            print(f"  [{status}] {msg}")
+
+    # 1. 8-block structure
+    section("structure")
     blocks = [
         "Agentik_SSOT", "Agentik_Engine", "Agentik_Orchestration",
         "Agentik_Providers", "Agentik_Coding", "Agentik_Tools",
         "Agentik_Runtime", "Agentik_Extra",
     ]
-    ok = True
-    print(f"omega doctor — OMEGA_HOME={home}")
     for b in blocks:
-        present = (home / b).is_dir()
-        print(f"  [{'ok' if present else 'MISSING'}] {b}")
-        ok = ok and present
+        line("ok" if (home / b).is_dir() else "FAIL", f"block {b}")
+
+    # 2. Event store
+    section("event store")
     store = home / "Agentik_Runtime" / "eventlog" / "omega.db"
-    print(f"  [{'ok' if store.exists() else 'pending'}] event store: {store}")
-    print("doctor: PASS" if ok else "doctor: FAIL")
-    return 0 if ok else 1
+    line("ok" if store.exists() else "warn",
+         f"event store: {store}{' (none yet — run a mission)' if not store.exists() else ''}")
+
+    # 3. Vault
+    section("vault")
+    try:
+        from omega_engine.vault import vault_status
+        vs = vault_status(home)
+        if vs["backend"] == "age":
+            line("ok", f"vault backend: age ({vs['encrypted_count']} encrypted)")
+        else:
+            line("warn",
+                 f"vault backend: plain ({vs['plaintext_count']} files in chmod 600)"
+                 + (" — install `age` for encryption" if not vs.get("age_installed") else ""))
+        if vs.get("plaintext_count", 0) > 0 and vs["backend"] == "age":
+            line("warn",
+                 f"vault has {vs['plaintext_count']} unencrypted secret(s) left over — "
+                 "re-write them through `omega account login` / `omega tool install`")
+        placeholders = vs.get("placeholder_count", 0)
+        if placeholders:
+            line("ok",
+                 f"{placeholders} placeholder dotenv(s) await operator input (no leak)")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"vault status unavailable: {exc}")
+
+    # 4. Providers router + credentials
+    section("providers")
+    router_path = home / "Agentik_SSOT" / "providers" / "router.yaml"
+    if router_path.exists():
+        try:
+            import yaml as _yaml
+            cfg = _yaml.safe_load(router_path.read_text()) or {}
+            for p in cfg.get("providers") or []:
+                pid = p.get("id", "?")
+                roles = p.get("roles") or []
+                secret_ref = p.get("secret_ref") or f"{pid.upper()}_API_KEY"
+                has_env = bool(_os.environ.get(secret_ref))
+                try:
+                    from omega_engine.vault import vault_read
+                    has_vault = bool(vault_read(home, secret_ref))
+                except Exception:
+                    has_vault = False
+                creds = "env" if has_env else ("vault" if has_vault else "missing")
+                stat = "ok" if creds != "missing" else "warn"
+                line(stat, f"provider {pid} (roles={roles}, creds={creds})")
+        except Exception as exc:  # noqa: BLE001
+            line("FAIL", f"provider router unreadable: {exc}")
+    else:
+        line("warn", f"no provider router at {router_path} (none in manifest, or step 35 skipped)")
+
+    # 5. MCP catalog + installed tools
+    section("mcp")
+    catalog = home / "Agentik_SSOT" / "mcp" / "mcp-catalog.yaml"
+    config = home / "Agentik_SSOT" / "mcp" / "mcp-config.yaml"
+    line("ok" if catalog.exists() else "FAIL", f"MCP catalog: {catalog.name}")
+    if config.exists():
+        try:
+            import yaml as _yaml
+            cfg = _yaml.safe_load(config.read_text()) or {}
+            entries = cfg.get("mcp") or cfg.get("servers") or []
+            line("ok", f"MCP config: {len(entries)} server(s) registered")
+        except Exception as exc:  # noqa: BLE001
+            line("warn", f"MCP config unreadable: {exc}")
+    else:
+        line("warn", "no MCP config yet (run `omega tool install <id>` or re-run step 40)")
+
+    # 6. Account pool vs vault
+    section("accounts")
+    try:
+        from omega_engine.account import AccountPool
+        from omega_engine.vault import vault_read
+        pool = AccountPool.load(home)
+        if not pool.accounts:
+            line("warn", "account pool is empty (run `omega account login`)")
+        for a in pool.accounts:
+            ref = a.secret_ref
+            has_token = False
+            try:
+                has_token = bool(vault_read(home, f"{ref}_TOKEN") or vault_read(home, ref))
+            except Exception:
+                has_token = False
+            # `disabled` accounts shouldn't be expected to have a token; for
+            # `active`/`resting` ones, missing token is a soft warning — the
+            # operator just hasn't run `omega account login` yet.
+            if has_token:
+                line("ok", f"account {a.id} ({a.status}) — token in vault")
+            else:
+                line("warn",
+                     f"account {a.id} ({a.status}) — no token yet "
+                     f"(run `omega account login --id {a.id}`)")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"account pool unreadable: {exc}")
+
+    # 6b. Agentik OS native skills (replacements for /goal + /loop on Max)
+    section("agentik skills")
+    skills_dir = home / "Agentik_SSOT" / "skills"
+    expected_skills = {"pursue", "cadence", "dispatch"}
+    found_skills: set[str] = set()
+    if skills_dir.is_dir():
+        for child in skills_dir.iterdir():
+            if child.is_dir() and (child / "SKILL.md").exists():
+                found_skills.add(child.name)
+            elif child.suffix == ".md":
+                found_skills.add(child.stem)
+    missing = expected_skills - found_skills
+    if missing:
+        line("warn", f"missing Agentik OS skills: {sorted(missing)}")
+    else:
+        line("ok", f"Agentik OS native skills present: {sorted(expected_skills)}")
+    if found_skills - expected_skills:
+        extras = sorted(found_skills - expected_skills)
+        line("ok", f"plus operator skills: {extras[:5]}{' (+more)' if len(extras) > 5 else ''}")
+
+    # 6b2. Semantic memory + learning loop
+    section("memory + learning")
+    try:
+        from omega_engine import memory as _mem
+        stats = _mem.index_stats(home)
+        if stats["indexed"]:
+            line("ok", f"semantic memory: {stats['total']:,d} docs indexed")
+        else:
+            line("warn",
+                 "semantic memory not indexed — run `omega memory reindex`")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"memory stats failed: {exc}")
+    # Learning loop — count proposals on disk
+    try:
+        staging = home / "Agentik_Extra" / "staging" / "promotion"
+        if staging.is_dir():
+            proposals = list(staging.glob("smith-*.json"))
+            if proposals:
+                line("ok",
+                     f"{len(proposals)} Smith reflection(s) pending in staging")
+            else:
+                line("ok",
+                     "no Smith reflections pending "
+                     "(run `omega learn reflect --write`)")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"learning scan failed: {exc}")
+
+    # 6b3. Tmux orchestration — categorised session population
+    section("tmux")
+    try:
+        from omega_engine import tmux as _tx
+        report = _tx.health_report(home)
+        if not report.get("tmux_installed"):
+            line("FAIL", "tmux not on PATH — run `omega upgrade` to reinstall")
+        else:
+            n = report["sessions"]
+            cats = report.get("by_category", {})
+            if n == 0:
+                line("ok", "tmux installed, no sessions yet "
+                     "(omega tmux spawn ...)")
+            else:
+                line("ok", f"tmux: {n} session(s), categories: "
+                     + ", ".join(f"{c}={len(v)}"
+                                  for c, v in cats.items() if v))
+            if report.get("stale"):
+                line("warn",
+                     f"{len(report['stale'])} stale worker session(s) >6h "
+                     "detached — run `omega tmux cleanup`")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"tmux health check failed: {exc}")
+
+    # 6c0. Provider authentication mode — Max OAuth via `claude` CLI vs API key
+    section("llm authentication")
+    try:
+        from omega_engine.provider import ClaudeMaxProvider
+        if ClaudeMaxProvider.is_available():
+            line("ok",
+                 "Claude Code Max — using OAuth via `claude` CLI subprocess "
+                 "(no API key needed; cost tracked in $)")
+        elif os.environ.get("ANTHROPIC_API_KEY"):
+            line("warn",
+                 "ANTHROPIC_API_KEY set — falling back to API (paid per call). "
+                 "Install `claude` CLI + `claude /login` to use your Max subscription instead.")
+        else:
+            line("warn",
+                 "No `claude` CLI and no ANTHROPIC_API_KEY — engine will use "
+                 "the MockProvider. Install Claude Code + log in to use Max.")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"provider auth check failed: {exc}")
+
+    # 6c1. LLM CLIs installed on the host
+    section("llm clis")
+    import shutil as _shu
+    import subprocess as _sup
+    _cli_specs = [
+        ("claude_code", "claude", ["claude", "--version"]),
+        ("gemini_cli",  "gemini", ["gemini", "--version"]),
+        ("codex",       "codex",  ["codex", "--version"]),
+        ("aider",       "aider",  ["aider", "--version"]),
+    ]
+    any_cli = False
+    for cli_id, bin_name, ver_cmd in _cli_specs:
+        if _shu.which(bin_name):
+            any_cli = True
+            try:
+                proc = _sup.run(ver_cmd, check=False, capture_output=True,
+                                text=True, timeout=15)
+                v = (proc.stdout or proc.stderr or "(unknown)").strip().splitlines()[0][:60]
+            except Exception:  # noqa: BLE001
+                v = "(version check failed)"
+            line("ok", f"{cli_id:<14} {v}")
+        else:
+            line("warn", f"{cli_id:<14} (not on PATH)")
+    # GLM SDK is a Python import, not a binary
+    try:
+        import importlib
+        importlib.import_module("zhipuai")
+        line("ok", "glm_sdk        (zhipuai Python SDK importable)")
+        any_cli = True
+    except ImportError:
+        line("warn", "glm_sdk        (not installed — `uv tool install zhipuai`)")
+    if not any_cli:
+        line("warn", "no LLM CLI installed — `omega upgrade` or re-run "
+             "install.sh with the llm_clis: block")
+
+    # 6c2. Claude Code settings — Agent Teams + bypass + Stop hook
+    section("claude code settings")
+    import json as _json
+    settings_path = Path.home() / ".claude" / "settings.json"
+    if not settings_path.exists():
+        line("warn",
+             f"no settings.json at {settings_path} — Agent Teams + audit gate not active "
+             "(re-run install step 33-claude-code-settings)")
+    else:
+        try:
+            data = _json.loads(settings_path.read_text())
+            env_at = (data.get("env") or {}).get("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS")
+            line("ok" if env_at == "1" else "warn",
+                 f"Agent Teams flag: {env_at or 'unset'}")
+            dm = (data.get("permissions") or {}).get("defaultMode")
+            line("ok" if dm == "bypassPermissions" else "warn",
+                 f"permissions.defaultMode: {dm or 'default'}")
+            stop_hooks = (data.get("hooks") or {}).get("Stop") or []
+            has_gate = any(
+                isinstance(e, dict) and e.get("tag") == "omega-audit-gate"
+                for e in stop_hooks
+            )
+            line("ok" if has_gate else "warn",
+                 f"Stop-hook audit gate: {'wired' if has_gate else 'not wired'}")
+        except Exception as exc:  # noqa: BLE001
+            line("warn", f"settings.json unreadable: {exc}")
+
+    # 6c5. Inbound webhooks — gate ready?
+    section("webhooks")
+    try:
+        from omega_engine.webhooks import load_registry
+        reg = load_registry(home)
+        if not reg.specs:
+            line("ok", "no webhooks configured (optional)")
+        else:
+            for s in reg.specs:
+                from omega_engine.webhooks import _load_secret
+                has_secret = bool(_load_secret(home, s.secret_ref))
+                stat = "ok" if has_secret else "warn"
+                line(stat,
+                     f"{s.id:<20} path={s.path} source={s.source} "
+                     f"secret={'set' if has_secret else 'MISSING'}")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"webhook registry unreadable: {exc}")
+
+    # 6d. Audit health — last score + trend per audit
+    section("audit history")
+    try:
+        from omega_engine.audit_arsenal import AuditRegistry
+        from omega_engine.audits.history import latest_score, trend
+        registry = AuditRegistry.load(home / "Agentik_SSOT" / "audits")
+        any_run = False
+        for audit in registry.all():
+            score = latest_score(home, audit.id)
+            if score is None:
+                continue
+            any_run = True
+            t = trend(home, audit.id)
+            stat = "ok" if score >= audit.threshold else "warn"
+            line(stat,
+                 f"{audit.id:<18} latest={score:>3} {t}  "
+                 f"(threshold {audit.threshold})")
+        if not any_run:
+            line("ok", "no audit runs recorded yet "
+                 "(run `omega audit all` to seed history)")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"audit history check failed: {exc}")
+
+    # 6c. Cadence charters scheduled
+    try:
+        from omega_engine.cadence import list_cadences
+        cads = list_cadences(home)
+        if cads:
+            on = [c for c in cads if c["enabled"]]
+            line("ok", f"{len(on)}/{len(cads)} cadence(s) scheduled and enabled")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"cadence scan failed: {exc}")
+
+    # 7a. AISB agent suite
+    section("aisb suite")
+    try:
+        from omega_engine.prompts import list_available_agents
+        suites = list_available_agents(home)
+        if not suites:
+            line("warn",
+                 f"no agent suites at {home}/Agentik_SSOT/agents/ — "
+                 "step 25-aisb-suite may have been skipped")
+        else:
+            for suite, roles in suites.items():
+                line("ok", f"suite '{suite}': {len(roles)} agents ({', '.join(roles[:5])}{'...' if len(roles) > 5 else ''})")
+            # Specifically check the 13 AISB agents we expect.
+            expected_aisb = {
+                "architect", "construct", "keymaker", "link", "merovingian",
+                "morpheus", "neo", "niobe", "oracle", "pythia", "seraph",
+                "smith", "zion",
+            }
+            actual_aisb = set(suites.get("aisb", []))
+            missing = expected_aisb - actual_aisb
+            if missing:
+                line("warn", f"AISB suite incomplete — missing: {sorted(missing)}")
+            else:
+                line("ok", "AISB suite complete (13/13 agents)")
+    except Exception as exc:  # noqa: BLE001
+        line("FAIL", f"agent suite check failed: {exc}")
+
+    # 7b. Per-project vaults
+    section("project vaults")
+    try:
+        from omega_engine.vault import list_project_vaults
+        vaults = list_project_vaults(home)
+        if not vaults:
+            line("ok", "no per-project vaults yet (none required)")
+        for v in vaults:
+            backend = v.get("backend", "?")
+            ec = v.get("encrypted_count", 0)
+            pc = v.get("plaintext_count", 0)
+            stat = "ok"
+            if backend != "age" and (ec + pc) > 0:
+                stat = "warn"
+            line(stat,
+                 f"project '{v.get('project')}': backend={backend}, "
+                 f"encrypted={ec}, plaintext={pc}")
+    except Exception as exc:  # noqa: BLE001
+        line("warn", f"project vault scan failed: {exc}")
+
+    # 7. Educators
+    section("educators")
+    try:
+        from omega_engine import educators as _edu
+        expected = [
+            "PromptEducator", "ArtifactEducator", "SkillEducator",
+            "CoworkerEducator", "ConnectionEducator", "AutomationEducator",
+            "ClaudecodeEducator", "LoopEducator",
+        ]
+        missing = [c for c in expected if not hasattr(_edu, c)]
+        if missing:
+            line("FAIL", f"missing educator classes: {missing}")
+        else:
+            line("ok", f"{len(expected)} educators loadable")
+        staging = home / "Agentik_Extra" / "staging" / "promotion"
+        if staging.is_dir():
+            line("ok", f"staging pipeline at {staging}")
+        else:
+            line("warn", f"no staging pipeline dir at {staging}")
+    except Exception as exc:  # noqa: BLE001
+        line("FAIL", f"educators module unloadable: {exc}")
+
+    # 8. Autonomous charters
+    section("autonomous charters")
+    chdir = home / "Agentik_Orchestration" / "autonomous"
+    if chdir.is_dir():
+        charters = sorted(chdir.glob("*.yaml"))
+        if not charters:
+            line("warn", f"no charters at {chdir}")
+        else:
+            import yaml as _yaml
+            for c in charters:
+                try:
+                    data = _yaml.safe_load(c.read_text()) or {}
+                    cid = data.get("id") or c.stem
+                    enabled = bool(data.get("enabled", True))
+                    trigger = (data.get("trigger") or {}).get("type", "?")
+                    line("ok", f"charter {cid} (trigger={trigger}, enabled={enabled})")
+                except Exception as exc:  # noqa: BLE001
+                    line("FAIL", f"charter {c.name} unparseable: {exc}")
+    else:
+        line("warn", f"no autonomous dir at {chdir}")
+
+    # 9. 24/7 services
+    section("24/7 services")
+    import platform as _platform
+    if _platform.system() == "Linux":
+        unitdir = Path.home() / ".config" / "systemd" / "user"
+        units_installed = (unitdir / "omega-engine.service").exists()
+        if _sh.which("systemctl") is None:
+            line("warn", "systemctl not on PATH — services step skipped")
+        elif not units_installed:
+            line("warn",
+                 f"no service units at {unitdir} — re-run install.sh "
+                 "with a non-minimal profile to enable the 24/7 layer")
+        else:
+            for unit in ("omega-engine", "omega-telegram", "omega-autonomous"):
+                proc = _sp.run(
+                    ["systemctl", "--user", "is-active", unit],
+                    check=False, capture_output=True, text=True, timeout=10,
+                )
+                state = (proc.stdout or proc.stderr or "").strip()
+                if state == "active":
+                    line("ok", f"systemd: {unit} (active)")
+                elif state in {"inactive", "failed"}:
+                    line("FAIL", f"systemd: {unit} ({state}) — unit exists, "
+                                 "start with `systemctl --user start omega-*`")
+                else:
+                    line("warn", f"systemd: {unit} ({state or 'unknown'})")
+    elif _platform.system() == "Darwin":
+        agentdir = Path.home() / "Library" / "LaunchAgents"
+        plists_installed = (agentdir / "com.agentikos.omega.engine.plist").exists()
+        if _sh.which("launchctl") is None:
+            line("warn", "launchctl not on PATH")
+        elif not plists_installed:
+            line("warn",
+                 f"no LaunchAgent plists at {agentdir} — re-run install.sh "
+                 "with a non-minimal profile to enable the 24/7 layer")
+        else:
+            for label in ("com.agentikos.omega.engine",
+                          "com.agentikos.omega.telegram",
+                          "com.agentikos.omega.autonomous"):
+                proc = _sp.run(
+                    ["launchctl", "list", label],
+                    check=False, capture_output=True, text=True, timeout=10,
+                )
+                if proc.returncode == 0:
+                    line("ok", f"launchd: {label} (loaded)")
+                else:
+                    line("FAIL", f"launchd: {label} (plist present but not loaded) "
+                                 "— `launchctl bootstrap gui/$(id -u) <plist>`")
+    else:
+        line("warn", f"unsupported OS for services check: {_platform.system()}")
+
+    # 10. Telegram bridge
+    section("telegram")
+    try:
+        from omega_engine.vault import vault_read
+        token = vault_read(home, "TELEGRAM_TOKEN") or None
+    except Exception:
+        token = None
+    if not token:
+        # Backward compat: read from the legacy telegram.env file.
+        legacy = home / "Agentik_Extra" / "etc" / "secrets" / "telegram.env"
+        if legacy.exists():
+            for ln in legacy.read_text().splitlines():
+                if ln.startswith("TELEGRAM_TOKEN="):
+                    token = ln.split("=", 1)[1].strip()
+                    break
+    if not token:
+        line("warn", "no Telegram token in vault (skip if minimal profile)")
+    else:
+        try:
+            import urllib.request as _ur
+            req = _ur.Request(f"https://api.telegram.org/bot{token}/getMe")
+            with _ur.urlopen(req, timeout=10) as resp:  # noqa: S310
+                body = resp.read().decode("utf-8", errors="replace")
+                if '"ok":true' in body:
+                    line("ok", "telegram bot reachable (getMe → ok)")
+                else:
+                    line("FAIL", f"telegram getMe returned: {body[:120]}")
+        except Exception as exc:  # noqa: BLE001
+            line("FAIL", f"telegram bot unreachable: {exc}")
+
+    # ────────────────────────────────────────────────────────────────────
+    # Ready / Partial / Not Ready verdict.
+    #
+    # CRITICAL: blocks block_count > 0 in these sections → NOT READY
+    #   structure, event store, vault, providers, accounts, aisb suite,
+    #   educators
+    # IMPORTANT: warns in these sections → PARTIAL (engine works but
+    #   surfaces missing — usually just a profile thing)
+    #   24/7 services, telegram, llm clis, claude code settings,
+    #   audit history
+    # OPTIONAL: anything else — flag but never demote
+    # ────────────────────────────────────────────────────────────────────
+    CRITICAL_SECTIONS = {
+        "structure", "event store", "vault", "providers",
+        "accounts", "aisb suite", "educators",
+    }
+    IMPORTANT_SECTIONS = {
+        "24/7 services", "telegram", "llm clis",
+        "claude code settings", "audit history", "mcp",
+    }
+    critical_fails: list[str] = []
+    important_warns: list[str] = []
+    for r in results:
+        if r["status"] == "FAIL" and r["section"] in CRITICAL_SECTIONS:
+            critical_fails.append(f"{r['section']}: {r['msg']}")
+        elif r["status"] == "FAIL":
+            # A FAIL outside CRITICAL still demotes to NOT READY — a real
+            # FAIL is a real FAIL.
+            critical_fails.append(f"{r['section']}: {r['msg']}")
+        elif r["status"] == "warn" and r["section"] in IMPORTANT_SECTIONS:
+            important_warns.append(r["section"])
+
+    if critical_fails:
+        readiness = "NOT_READY"
+        readiness_msg = (
+            f"{len(critical_fails)} critical failure(s) — engine cannot "
+            f"reliably run missions. First: {critical_fails[0][:200]}"
+        )
+    elif important_warns:
+        readiness = "PARTIAL"
+        unique = sorted(set(important_warns))
+        readiness_msg = (
+            f"engine ready, but surfaces missing: {', '.join(unique)}. "
+            "Re-run install to fill them in."
+        )
+    else:
+        readiness = "READY"
+        readiness_msg = "every surface healthy — ready to run missions."
+
+    verdict = "FAIL" if any_fail else ("warnings" if any_warn else "PASS")
+
+    if json_mode:
+        import json as _json
+        payload = {
+            "omega_home": str(home),
+            "verdict": verdict,
+            "readiness": readiness,
+            "readiness_msg": readiness_msg,
+            "any_fail": any_fail,
+            "any_warn": any_warn,
+            "results": results,
+        }
+        print(_json.dumps(payload, indent=2))
+        return 1 if any_fail else 0
+
+    print()
+    if any_fail:
+        print("doctor: FAIL")
+    elif any_warn:
+        print("doctor: PASS with warnings")
+    else:
+        print("doctor: PASS")
+    print()
+    icon = {"READY": "✓", "PARTIAL": "~", "NOT_READY": "✗"}[readiness]
+    print(f"  {icon} {readiness}  —  {readiness_msg}")
+    return 1 if any_fail else 0
 
 
 def cmd_status(_args: argparse.Namespace) -> int:
@@ -62,43 +653,237 @@ def cmd_status(_args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_account(_args: argparse.Namespace) -> int:
-    """Show the Claude Code Max account pool and the selection strategy.
+# ──── account subcommands ─────────────────────────────────────────────────
+
+
+def _print_pool(pool) -> None:
+    print(f"Claude Max account pool — selection: {pool.selection}")
+    if not pool.accounts:
+        print("  (empty)")
+        print("  add an account:  omega account login")
+        return
+    for a in pool.accounts:
+        used = f"{a.tokens_used:>9,d} tok" if a.tokens_used else "         -"
+        print(f"  [{a.status:<9}] {a.id:<16} {used}  {a.label}")
+    print("  add an account:  omega account login")
+
+
+def cmd_account_list(_args: argparse.Namespace) -> int:
+    """Show the Claude Code Max account pool and the selection strategy."""
+    from omega_engine.account import AccountPool
+
+    pool = AccountPool.load(_omega_home())
+    _print_pool(pool)
+    return 0
+
+
+def cmd_account_login(args: argparse.Namespace) -> int:
+    """Add an account: run the OAuth flow, store the token in the vault,
+    and add a pool entry.
 
-    Omega OS runs one engine, not N tmux sessions — so an account is not
-    "switched" globally. The Claude provider holds a POOL and distributes agent
-    calls across accounts. Add one with `omega account login`.
-    See docs/ACCOUNT-AND-BILLING.md.
+    Strategy: try the RFC 8628 device-code flow first; if it's unavailable
+    (Anthropic does not currently publish those endpoints), fall back to a
+    manual paste flow — the user logs in via browser elsewhere, copies the
+    token, and pastes it. Either way ends with the token in the vault and
+    a new account in `accounts.yaml`.
     """
-    cfg = _omega_home() / "Agentik_Providers" / "claude" / "accounts.yaml"
-    if not cfg.exists():
-        cfg = cfg.with_name("accounts.example.yaml")
-    if not cfg.exists():
-        print("no Claude Max account pool configured — see docs/ACCOUNT-AND-BILLING.md")
-        return 0
+    from omega_engine.account import (
+        AccountPool,
+        ClaudeAccount,
+        claude_device_code_flow,
+        claude_oauth_login_url,
+        write_token,
+    )
+
+    account_id = (args.id or "").strip()
+    if not account_id:
+        account_id = input("account id (e.g. max-primary): ").strip()
+    if not account_id:
+        print("account id is required — aborting")
+        return 2
+    label = (args.label or "").strip() or f"Claude Max account ({account_id})"
+    secret_ref = f"CLAUDE_OAUTH_{account_id}"
+
+    token: str | None = None
+    if not args.manual:
+        print("attempting OAuth device-code flow...")
+        try:
+            result = claude_device_code_flow()
+            instruction = result.get("raw", {}).get("_human_instruction") \
+                or result.get("_human_instruction") or ""
+            if instruction:
+                print(instruction)
+            token = result.get("access_token")
+        except RuntimeError as exc:
+            print(f"device-code flow unavailable: {exc}")
+            print("falling back to manual paste...")
+
+    if not token:
+        # manual fallback — this is the path that always works
+        print()
+        print("MANUAL LOGIN")
+        print(f"  1. open in a browser:  {claude_oauth_login_url()}")
+        print("  2. complete login on the Claude account you want to add")
+        print("  3. copy the OAuth token from the dashboard or developer panel")
+        print()
+        try:
+            token = input("paste the OAuth token here: ").strip()
+        except EOFError:
+            token = ""
+    if not token:
+        print("no token provided — aborting (vault not modified)")
+        return 2
+
+    home = _omega_home()
+    path = write_token(home, secret_ref, token)
+    pool = AccountPool.load(home)
+    pool.add(ClaudeAccount(
+        id=account_id, label=label, secret_ref=secret_ref,
+        weight=1, status="active",
+    ))
+    cfg = pool.save(home)
+    print(f"  vault:  {path}  (chmod 600)")
+    print(f"  pool:   {cfg}")
+    _print_pool(pool)
+    return 0
+
+
+def cmd_account_use(args: argparse.Namespace) -> int:
+    """Set an account's status: active | resting | disabled."""
+    from omega_engine.account import AccountPool
+
+    home = _omega_home()
+    pool = AccountPool.load(home)
+    if pool.get(args.id) is None:
+        print(f"no account '{args.id}' in the pool")
+        return 2
     try:
-        import yaml
-    except ImportError:
-        print(f"account pool config: {cfg}  (install pyyaml to render it)")
-        return 0
-    data = yaml.safe_load(cfg.read_text()) or {}
-    pool = data.get("pool", [])
-    print(f"Claude Max account pool — selection: {data.get('selection', 'least-used')}")
-    for a in pool or [{"status": "(empty)", "id": "", "label": ""}]:
-        print(f"  [{str(a.get('status', '?')):<9}] {str(a.get('id', '')):<16} {a.get('label', '')}")
-    print("  add an account:  omega account login   (docs/ACCOUNT-AND-BILLING.md)")
+        pool.set_status(args.id, args.status)
+    except ValueError as exc:
+        print(str(exc))
+        return 2
+    pool.save(home)
+    _print_pool(pool)
     return 0
 
 
+def cmd_account_pool(args: argparse.Namespace) -> int:
+    """Edit pool-wide knobs: selection strategy and per-account weights.
+
+    Non-interactive flags drive scripted edits; with no flags, it prints the
+    current pool for inspection.
+    """
+    from omega_engine.account import AccountPool
+
+    home = _omega_home()
+    pool = AccountPool.load(home)
+    changed = False
+    if args.selection:
+        if args.selection not in ("round-robin", "least-used", "by-quota"):
+            print(
+                f"invalid selection '{args.selection}' — "
+                "must be round-robin|least-used|by-quota"
+            )
+            return 2
+        pool.selection = args.selection
+        changed = True
+    if args.weight:
+        # each --weight ID=N — parse and apply
+        for spec in args.weight:
+            if "=" not in spec:
+                print(f"weight spec '{spec}' must be of the form id=N")
+                return 2
+            ident, _, val = spec.partition("=")
+            ident, val = ident.strip(), val.strip()
+            acc = pool.get(ident)
+            if acc is None:
+                print(f"no account '{ident}' — skipping")
+                continue
+            try:
+                acc.weight = max(int(val), 0)
+            except ValueError:
+                print(f"weight for '{ident}' must be an integer, got {val!r}")
+                return 2
+            changed = True
+    if changed:
+        pool.save(home)
+    _print_pool(pool)
+    return 0
+
+
+def cmd_account(args: argparse.Namespace) -> int:
+    """Account dispatcher — keeps `omega account` (no subcommand) working as a
+    list view, matches the original surface area."""
+    sub = getattr(args, "account_cmd", None) or "list"
+    fns = {
+        "list": cmd_account_list,
+        "login": cmd_account_login,
+        "use": cmd_account_use,
+        "pool": cmd_account_pool,
+    }
+    if sub not in fns:
+        print(f"unknown account subcommand: {sub}")
+        return 2
+    return fns[sub](args)
+
+
+# ──── billing ─────────────────────────────────────────────────────────────
+
+
 def cmd_billing(_args: argparse.Namespace) -> int:
     """Show usage and cost per Claude Max account.
 
-    Per-account billing reads token usage recorded on the event log against the
-    provider cost model — so you see which account is near its weekly limit.
+    Sources: token usage on `task.*` events (live aggregation via
+    `BillingAggregator`) plus the cached counter in `accounts.yaml`. The event
+    log is the source of truth; the cached counter is the convenience view.
     """
+    from omega_engine.account import AccountPool, BillingAggregator
+    from omega_engine.store import SQLiteStore
+
+    home = _omega_home()
+    pool = AccountPool.load(home)
     print("omega billing — usage per Claude Max account")
-    print("  source: token usage on task.* events + the provider cost model")
-    print("  build-out: live per-account aggregation — see docs/ACCOUNT-AND-BILLING.md")
+    print()
+    print(f"  pool selection: {pool.selection}")
+    print(f"  accounts in pool: {len(pool.accounts)}")
+    print()
+
+    db = home / "Agentik_Runtime" / "eventlog" / "omega.db"
+    if not db.exists():
+        print("  no event store yet — nothing to aggregate")
+        return 0
+    store = SQLiteStore(db)
+    totals = BillingAggregator.from_event_log(store)
+    if not totals:
+        print("  no per-account usage recorded in the event log yet")
+        print("  (events emit `usage.account_id` once the Claude provider "
+              "is wired)")
+        store.close()
+        return 0
+
+    pool_ids = {a.id for a in pool.accounts}
+    header = f"  {'account':<16} {'calls':>7} {'input_tok':>12} {'output_tok':>12} {'total_tok':>12}"
+    print(header)
+    print(f"  {'-' * 64}")
+    grand_in = grand_out = grand_calls = 0
+    for account_id, t in sorted(totals.items()):
+        marker = "" if account_id in pool_ids else "  (unknown)"
+        total_tok = t["input_tokens"] + t["output_tokens"]
+        print(
+            f"  {account_id:<16} {t['total_calls']:>7,d} "
+            f"{t['input_tokens']:>12,d} {t['output_tokens']:>12,d} "
+            f"{total_tok:>12,d}{marker}"
+        )
+        grand_in += t["input_tokens"]
+        grand_out += t["output_tokens"]
+        grand_calls += t["total_calls"]
+    print(f"  {'-' * 64}")
+    print(
+        f"  {'TOTAL':<16} {grand_calls:>7,d} "
+        f"{grand_in:>12,d} {grand_out:>12,d} "
+        f"{grand_in + grand_out:>12,d}"
+    )
+    store.close()
     return 0
 
 
@@ -107,7 +892,15 @@ def cmd_run(args: argparse.Namespace) -> int:
     verifies, and a whitepaper PDF report is produced."""
     from omega_engine.mission import run_mission
 
-    outcome = run_mission(args.intent)
+    # Reject empty / whitespace-only intents — they used to "succeed" silently
+    # with a 100%-complete result, masking the bug where the operator's prompt
+    # was lost mid-pipeline.
+    intent = (args.intent or "").strip()
+    if not intent:
+        print("error: intent is empty — supply a non-blank mission description",
+              file=sys.stderr)
+        return 2
+    outcome = run_mission(intent)
     print(f"mission {outcome.result.mission_id}: "
           f"{outcome.result.final_state.value}  ({outcome.progress_pct}%)")
     if outcome.report_pdf:
@@ -118,10 +911,15 @@ def cmd_run(args: argparse.Namespace) -> int:
 def cmd_project(args: argparse.Namespace) -> int:
     """Create a project — folder, registry entry, and (if configured) a bound
     Telegram topic."""
+    # Subcommand: `omega project secret ...`
+    sub = getattr(args, "project_cmd", None)
+    if sub == "secret":
+        return cmd_project_secret(args)
+
     from omega_engine.project import create_project
 
     telegram = None
-    if not args.no_telegram:
+    if not getattr(args, "no_telegram", False):
         try:
             from omega_engine.telegram import TelegramBridge
             telegram = TelegramBridge.from_vault()
@@ -134,23 +932,3733 @@ def cmd_project(args: argparse.Namespace) -> int:
     return 0
 
 
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="omega", description="Omega OS control CLI")
-    sub = parser.add_subparsers(dest="cmd", required=True)
-    sub.add_parser("version", help="print the engine version").set_defaults(fn=cmd_version)
-    sub.add_parser("doctor", help="validate the deployment").set_defaults(fn=cmd_doctor)
-    sub.add_parser("status", help="show all tasks and their derived state").set_defaults(fn=cmd_status)
-    sub.add_parser("account", help="show the Claude Max account pool").set_defaults(fn=cmd_account)
-    sub.add_parser("billing", help="show usage/cost per Claude Max account").set_defaults(fn=cmd_billing)
-    p_run = sub.add_parser("run", help="run a mission end-to-end")
-    p_run.add_argument("intent", help="the mission, in natural language")
-    p_run.set_defaults(fn=cmd_run)
-    p_proj = sub.add_parser("project", help="create a project")
-    p_proj.add_argument("name", help="the project name")
-    p_proj.add_argument("--no-telegram", action="store_true",
-                        help="skip Telegram topic creation")
-    p_proj.set_defaults(fn=cmd_project)
-    args = parser.parse_args(argv)
+def cmd_project_secret(args: argparse.Namespace) -> int:
+    """Per-project secret CLI: ``omega project secret {set|get|list} <slug> ...``
+
+    Secrets land under ``Agentik_Coding/projects/<slug>/.secrets/`` and are
+    encrypted with the same age recipient as the global vault when age is
+    available. Reads succeed only with the global key (so backups can't be
+    used to exfiltrate without the key).
+    """
+    from omega_engine.vault import vault_read, vault_status, vault_write
+
+    home = _omega_home()
+    op = args.op
+    slug = args.slug
+    if op == "list":
+        status = vault_status(home, project=slug)
+        sec = Path(status["secrets_dir"])
+        if not sec.exists():
+            print(f"no secrets yet for project '{slug}'")
+            return 0
+        print(f"project '{slug}' vault — backend: {status['backend']}")
+        print(f"  encrypted: {status['encrypted_count']}, "
+              f"plaintext: {status['plaintext_count']}, "
+              f"placeholders: {status['placeholder_count']}")
+        for p in sorted(sec.iterdir()):
+            if not p.is_file() or p.name.startswith("."):
+                continue
+            print(f"  - {p.name}")
+        return 0
+    if op == "set":
+        ref = args.ref
+        if not ref:
+            print("error: --ref required for set")
+            return 2
+        value = args.value
+        if value is None:
+            try:
+                value = input(f"value for {slug}/{ref}: ")
+            except EOFError:
+                value = ""
+        if not value:
+            print("no value provided — aborting")
+            return 2
+        try:
+            path = vault_write(home, ref, value, project=slug)
+        except Exception as exc:  # noqa: BLE001
+            print(f"error: {exc}")
+            return 1
+        print(f"wrote {path}")
+        return 0
+    if op == "get":
+        ref = args.ref
+        if not ref:
+            print("error: --ref required for get")
+            return 2
+        try:
+            value = vault_read(home, ref, project=slug)
+        except Exception as exc:  # noqa: BLE001
+            print(f"error: {exc}")
+            return 1
+        if value is None:
+            print(f"no secret '{ref}' for project '{slug}'")
+            return 1
+        print(value)
+        return 0
+    print(f"unknown project secret op: {op}")
+    return 2
+
+
+# --------------------------------------------------------------------------
+# `omega tool ...` — the registry of third-party tools (incl. installed MCPs).
+# --------------------------------------------------------------------------
+
+
+def _tool_install_npm(name: str, package: str, home: Path) -> dict[str, str]:
+    """Install one npm package into Agentik_Tools/<name>/ and return locator info."""
+    import shutil as _sh
+    import subprocess
+
+    tool_dir = home / "Agentik_Tools" / name
+    tool_dir.mkdir(parents=True, exist_ok=True)
+    npm = _sh.which("npm")
+    if npm is None:
+        raise RuntimeError("npm not found on PATH — install Node.js first")
+    subprocess.run(
+        [npm, "install", "-g", "--prefix", str(tool_dir), package],
+        check=True, capture_output=True, text=True, timeout=600,
+    )
+    bin_dir = tool_dir / "bin"
+    invoke = ""
+    if bin_dir.is_dir():
+        bins = sorted(p for p in bin_dir.iterdir() if p.is_file())
+        if bins:
+            invoke = str(bins[0].relative_to(home))
+    return {"path": f"Agentik_Tools/{name}/", "invoke": invoke}
+
+
+def cmd_tool_list(_args: argparse.Namespace) -> int:
+    from omega_engine.tools import ToolRegistry
+    reg = ToolRegistry.load(_omega_home())
+    tools = reg.list()
+    if not tools:
+        print("(no tools installed)")
+        return 0
+    print(f"{len(tools)} tool(s) installed:")
+    for t in tools:
+        ver = f"@{t.version}" if t.version else ""
+        print(f"  {t.name}{ver}  source={t.source or '-'}  invoke={t.invoke or '-'}")
+    return 0
+
+
+def cmd_tool_install(args: argparse.Namespace) -> int:
+    """Install a tool — either an MCP id from the catalog OR an npm package."""
+    home = _omega_home()
+    name = args.name
+    from omega_engine.tools import (
+        CatalogError,
+        Tool,
+        ToolRegistry,
+        install_from_catalog,
+        load_catalog,
+    )
+
+    if args.npm is None:
+        # Default path: treat <name> as an MCP catalog id.
+        try:
+            catalog = load_catalog(home)
+            tool = install_from_catalog(home, name, catalog=catalog)
+            print(f"installed {tool.name} (source={tool.source})")
+            return 0
+        except CatalogError as exc:
+            print(f"error: {exc}")
+            return 1
+        except Exception as exc:  # noqa: BLE001
+            print(f"error: {exc}")
+            return 1
+
+    # --npm given: install a bare npm package under Agentik_Tools/<name>/.
+    try:
+        loc = _tool_install_npm(name, args.npm, home)
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}")
+        return 1
+    reg = ToolRegistry.load(home)
+    reg.install(Tool(name=name, path=loc["path"], invoke=loc["invoke"],
+                     source=f"npm:{args.npm}"))
+    reg.save(home)
+    print(f"installed {name} (npm:{args.npm})")
+    return 0
+
+
+def cmd_tool_remove(args: argparse.Namespace) -> int:
+    import shutil as _sh
+    from omega_engine.tools import ToolRegistry
+    home = _omega_home()
+    reg = ToolRegistry.load(home)
+    tool = reg.get(args.name)
+    if tool is None:
+        print(f"not installed: {args.name}")
+        return 1
+    tool_dir = home / tool.path
+    if tool_dir.exists():
+        _sh.rmtree(tool_dir, ignore_errors=True)
+    reg.remove(args.name)
+    reg.save(home)
+    print(f"removed {args.name}")
+    return 0
+
+
+def cmd_tool_update(args: argparse.Namespace) -> int:
+    """Re-install the tool from its recorded source."""
+    from omega_engine.tools import (
+        CatalogError,
+        Tool,
+        ToolRegistry,
+        install_from_catalog,
+        load_catalog,
+    )
+    home = _omega_home()
+    reg = ToolRegistry.load(home)
+    tool = reg.get(args.name)
+    if tool is None:
+        print(f"not installed: {args.name}")
+        return 1
+    if tool.source.startswith("mcp:") or tool.source.startswith("catalog:"):
+        try:
+            catalog = load_catalog(home)
+            install_from_catalog(home, args.name, catalog=catalog, registry=reg)
+            print(f"updated {args.name}")
+            return 0
+        except CatalogError as exc:
+            print(f"error: {exc}")
+            return 1
+    if tool.source.startswith("npm:"):
+        pkg = tool.source.split(":", 1)[1]
+        try:
+            loc = _tool_install_npm(args.name, pkg, home)
+        except Exception as exc:  # noqa: BLE001
+            print(f"error: {exc}")
+            return 1
+        reg.install(Tool(name=args.name, path=loc["path"], invoke=loc["invoke"],
+                         source=tool.source))
+        reg.save(home)
+        print(f"updated {args.name}")
+        return 0
+    print(f"cannot update — unknown source: {tool.source}")
+    return 1
+
+
+def cmd_tool(args: argparse.Namespace) -> int:
+    """`omega tool` dispatcher."""
+    sub = getattr(args, "tool_cmd", None) or "list"
+    fns = {
+        "list":    cmd_tool_list,
+        "install": cmd_tool_install,
+        "remove":  cmd_tool_remove,
+        "update":  cmd_tool_update,
+    }
+    if sub not in fns:
+        print(f"unknown tool subcommand: {sub}")
+        return 2
+    return fns[sub](args)
+
+
+def cmd_sync(_args: argparse.Namespace) -> int:
+    """Project the SSOT into every active provider's native shape."""
+    from omega_engine.sync import SyncEngine
+    outcomes = SyncEngine().sync_all(_omega_home())
+    for o in outcomes:
+        if o.get("projected"):
+            print(
+                f"  [ok] {o['provider']}: skills={o['skills_written']} "
+                f"commands={o['commands_written']} "
+                f"agents={o.get('agents_written', 0)} "
+                f"mcp={o['mcp_servers']} hooks={len(o.get('hooks', []))}"
+            )
+        else:
+            print(f"  [-]  {o['provider']}: {o.get('reason', 'skipped')}")
+    return 0
+
+
+def cmd_graph(args: argparse.Namespace) -> int:
+    """Consume a graphify-built knowledge graph and (optionally) load it
+    into the engine's Graph RAG.
+
+    Graphify is a **Claude Code skill** — the graph itself is built inside
+    Claude Code by typing ``/graphify .`` in the target project. This
+    command reads the resulting ``<path>/graphify-out/graph.json`` and
+    merges its nodes + edges into the engine's GraphRetriever so the
+    multi-RAG router can answer relational queries about the code.
+
+    Workflow:
+      1. ``omega graph install`` — register the /graphify skill into ~/.claude/
+         (or wherever your Claude Code skills live).
+      2. Open Claude Code at <path>, run ``/graphify .`` — it produces
+         ``<path>/graphify-out/graph.json`` + the report + html.
+      3. ``omega graph <path> --rag`` — merge that graph into the engine's
+         Graph RAG memory.
+    """
+    from omega_engine.integrations import (
+        GraphifyError,
+        GraphifyGraphMissing,
+        GraphifyNotInstalled,
+        graphify_install_skill,
+        graphify_into_rag,
+        graphify_load_graph,
+        graphify_version,
+        is_graphify_installed,
+    )
+
+    # Subcommand: `omega graph install [--platform claude]`
+    if args.path == "install":
+        if not is_graphify_installed():
+            print(
+                "graphify is not installed. Install with:\n"
+                "  pip install graphifyy\n"
+                "Then re-run `omega graph install`."
+            )
+            return 1
+        try:
+            result = graphify_install_skill(platform=args.platform)
+        except (GraphifyNotInstalled, GraphifyError) as exc:
+            print(f"graphify install failed: {exc}")
+            return 1
+        print(f"graphify skill installed (platform={result['platform']})")
+        if result.get("stdout"):
+            print(result["stdout"])
+        print("Open Claude Code in any project and type `/graphify .`")
+        return 0
+
+    # Default: load a built graph from <path>/graphify-out/graph.json
+    version = graphify_version() or "(graphify CLI not on PATH — only graph.json needed)"
+    print(f"graphify: {version}")
+
+    try:
+        report = graphify_load_graph(args.path, json_path=args.json)
+    except GraphifyGraphMissing as exc:
+        print(f"{exc}")
+        print(
+            "Open Claude Code at the project and run `/graphify .` to build "
+            "the graph, then re-run `omega graph <path>`."
+        )
+        return 1
+    except GraphifyError as exc:
+        print(f"graphify load failed: {exc}")
+        return 1
+
+    print(f"  output:  {report.output_dir}")
+    print(f"  nodes:   {len(report.nodes):,d}")
+    print(f"  edges:   {len(report.edges):,d}")
+    if report.html_path.exists():
+        print(f"  html:    {report.html_path}")
+    if report.report_path.exists():
+        print(f"  report:  {report.report_path}")
+
+    if args.rag:
+        from omega_engine.rag import GraphRetriever
+
+        home = _omega_home()
+        rag_path = home / "Agentik_Runtime" / "memory" / "graph.json"
+        rag_path.parent.mkdir(parents=True, exist_ok=True)
+        retriever = GraphRetriever(json_path=str(rag_path))
+        counts = graphify_into_rag(report, retriever)
+        print(
+            f"  rag:     merged {counts['nodes']:,d} nodes and "
+            f"{counts['edges']:,d} edges into {rag_path}"
+        )
+    return 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    """`omega validate providers` — round-trip every wired provider."""
+    from omega_engine.validate import validate_all, validate_one
+    home = _omega_home()
+    sub = getattr(args, "validate_cmd", None) or "providers"
+    if sub != "providers":
+        print(f"unknown validate subcommand: {sub}")
+        return 2
+    if args.provider:
+        result = validate_one(home, args.provider)
+        results = [result]
+    else:
+        results = validate_all(home)
+    if not results:
+        print("(no providers configured — see manifest providers:)")
+        return 0
+    fail = False
+    for r in results:
+        mark = "ok" if r.ok else "FAIL"
+        print(f"  [{mark}] {r.provider:<12} {r.detail[:100]} ({r.elapsed_ms}ms)")
+        if not r.ok:
+            fail = True
+    return 1 if fail else 0
+
+
+def cmd_completions(args: argparse.Namespace) -> int:
+    """`omega completions` — write + install shell completion scripts."""
+    from omega_engine.completions import (
+        extract_tree, install_for_shell, write_all,
+    )
+    home = _omega_home()
+    sub = args.completions_cmd or "write"
+    if sub == "write":
+        parser = _build_parser()
+        tree = extract_tree(parser)
+        paths = write_all(home, tree)
+        for shell, p in paths.items():
+            print(f"  {shell:<5} → {p}")
+        return 0
+    if sub == "install":
+        result = install_for_shell(home, args.shell)
+        if result.get("status") == "ok":
+            print(f"  installed {args.shell} completion: {result['link']} → {result['src']}")
+            print(f"  source the file in your shell rc or restart your terminal")
+            return 0
+        print(f"  error: {result.get('detail', '?')}")
+        return 1
+    print(f"unknown completions subcommand: {sub}")
+    return 2
+
+
+def cmd_update(args: argparse.Namespace) -> int:
+    """`omega update {check,apply,banner,auto}` — auto-update lifecycle.
+
+    Subcommands:
+      * ``check``  query npm for the latest @agentikos/omega-os (default; legacy)
+      * ``apply``  backup → npm install → migrate → upgrade → verify (rollback on fail)
+      * ``banner`` print the one-line banner if outdated (used by autostart hooks)
+      * ``auto``   enable/disable the daily auto-apply charter
+    """
+    from omega_engine import __version__
+    from omega_engine import auto_update as AU
+    sub = getattr(args, "update_cmd", None)
+    home = _omega_home()
+
+    # Legacy flag — `omega update --check`
+    if sub is None:
+        sub = "check" if getattr(args, "check", False) else None
+    if sub == "apply":
+        force_no_npm = getattr(args, "no_npm", False)
+        res = AU.apply_update(
+            home,
+            skip_backup=getattr(args, "no_backup", False),
+            skip_verify=getattr(args, "no_verify", False),
+            npm_global=not force_no_npm,
+        )
+        import json as _json
+        if getattr(args, "json", False):
+            print(_json.dumps({
+                "ok": res.ok, "from": res.from_version,
+                "to": res.to_version, "rolled_back": res.rolled_back,
+                "bundle": res.bundle, "duration_s": res.duration_s,
+                "error": res.error, "steps": res.steps,
+            }, indent=2))
+        else:
+            mark = "✓" if res.ok else "✗"
+            print(f"  {mark}  {res.from_version} → {res.to_version}  "
+                  f"({res.duration_s}s)")
+            if res.bundle:
+                print(f"     backup: {res.bundle}")
+            if res.rolled_back:
+                print(f"     ROLLED BACK — restored from backup")
+            if res.error:
+                print(f"     {res.error}")
+            for st in res.steps:
+                rc = st.get("rc", "?")
+                tag = "ok" if rc == 0 else f"FAIL({rc})"
+                print(f"       [{tag:8s}] {st.get('label')}")
+        return 0 if res.ok else 1
+
+    if sub == "banner":
+        # Called by shell autostart; prints to stderr, never blocks.
+        printed = AU.maybe_emit_banner(home)
+        return 0
+
+    if sub == "auto":
+        # Manage the auto-apply charter (writes to Agentik_Orchestration/autonomous/).
+        op = getattr(args, "auto_op", "status")
+        charters = (
+            home / "Agentik_Orchestration" / "autonomous"
+        )
+        charter = charters / "auto-update.yaml"
+        if op == "enable":
+            charters.mkdir(parents=True, exist_ok=True)
+            charter.write_text(
+                "# Daily auto-apply of @agentikos/omega-os updates.\n"
+                "id: auto-update\n"
+                "description: Check npm + apply any available update at 04:00 UTC.\n"
+                "enabled: true\n"
+                "trigger:\n"
+                "  type: cron\n"
+                "  config:\n"
+                "    cron: \"0 4 * * *\"\n"
+                "intent: |\n"
+                "  Run `omega update apply --json` and report the result.\n"
+                "  If rolled_back=true, send the operator a Telegram alert.\n"
+            )
+            print(f"auto-update charter enabled at {charter}")
+            return 0
+        if op == "disable":
+            if charter.exists():
+                charter.unlink()
+                print("auto-update charter removed")
+            else:
+                print("auto-update was not enabled")
+            return 0
+        # status
+        if charter.exists():
+            print(f"auto-update: ENABLED ({charter})")
+        else:
+            print("auto-update: disabled  (use `omega update auto enable`)")
+        return 0
+
+    # `omega update check` (default) — same legacy behaviour.
+    from omega_engine.updater import check_for_updates
+    info = check_for_updates(__version__)
+    if info.error:
+        print(f"  (update check failed: {info.error})")
+        return 1
+    if info.is_outdated:
+        print(f"  current:  {info.current}")
+        print(f"  latest:   {info.latest}  (update available)")
+        print(f"  run:      omega update apply")
+        return 0
+    print(f"  up to date — current {info.current} == latest {info.latest}")
+    return 0
+
+
+def cmd_smoke(args: argparse.Namespace) -> int:
+    """`omega smoke` — synthetic mission to verify the orchestration stack."""
+    from omega_engine.smoke import run_smoke
+    result = run_smoke()
+    mark = "ok" if result.passed else "FAIL"
+    print(f"  [{mark}] smoke ({result.elapsed_ms}ms): {result.detail}")
+    if result.mission_id:
+        print(f"        mission_id={result.mission_id} "
+              f"final_state={result.final_state} "
+              f"events={result.events_recorded} "
+              f"done_files={result.done_files_written}")
+    return 0 if result.passed else 1
+
+
+def cmd_prune(args: argparse.Namespace) -> int:
+    """`omega prune` — bound the SQLite stores' growth."""
+    from omega_engine import prune as P
+    home = _omega_home()
+    target = args.target
+    days = args.days
+    dry = not args.yes
+    if target == "all":
+        reports = P.prune_all(home, older_than_days=days, dry_run=dry)
+    elif target == "events":
+        reports = [P.prune_events(home, older_than_days=days, dry_run=dry)]
+    elif target == "audits":
+        reports = [P.prune_audits(home, older_than_days=days, dry_run=dry)]
+    elif target == "telegram":
+        reports = [P.prune_telegram(home, older_than_days=days, dry_run=dry)]
+    elif target == "sessions":
+        reports = [P.prune_sessions(home, older_than_days=days, dry_run=dry)]
+    else:
+        print(f"unknown target: {target}")
+        return 2
+    for r in reports:
+        if r.target == "sessions":
+            verb = "would remove" if r.dry_run else "removed"
+            print(f"  {r.target:<10} {verb} {r.files_deleted} session(s), "
+                  f"{r.bytes_freed:,d} bytes  ({r.detail})")
+        else:
+            verb = "would delete" if r.dry_run else "deleted"
+            print(f"  {r.target:<10} {verb} {r.rows_deleted} row(s)  ({r.detail})")
+    if dry:
+        print("  (dry-run — re-run with --yes to apply)")
+    return 0
+
+
+def cmd_backup(args: argparse.Namespace) -> int:
+    """`omega backup` — tarball of the recoverable subset, optionally age-encrypted."""
+    from omega_engine.backup import backup, restore, verify
+    home = _omega_home()
+    sub = args.backup_cmd
+    if sub == "create" or sub is None:
+        try:
+            result = backup(
+                home, out_dir=args.out, encrypt=args.encrypt,
+                recipient_path=args.recipient,
+            )
+        except Exception as exc:  # noqa: BLE001
+            print(f"  error: {exc}")
+            return 1
+        print(f"  bundle: {result.bundle}")
+        print(f"  size: {result.bytes:,d} bytes encrypted={result.encrypted}")
+        print(f"  duration: {result.duration_s}s")
+        return 0
+    if sub == "restore":
+        if not args.bundle:
+            print("usage: omega backup restore <bundle> [--target DIR] [--identity FILE]")
+            return 2
+        try:
+            result = restore(
+                args.bundle,
+                target=(args.target or home),
+                age_identity=args.identity,
+            )
+        except Exception as exc:  # noqa: BLE001
+            print(f"  error: {exc}")
+            return 1
+        print(f"  restored {result.files} file(s) into {result.target}")
+        return 0
+    if sub == "verify":
+        if not args.bundle:
+            print("usage: omega backup verify <bundle> [--identity FILE]")
+            return 2
+        try:
+            result = verify(args.bundle, age_identity=args.identity)
+        except Exception as exc:  # noqa: BLE001
+            print(f"  error: {exc}")
+            return 1
+        mark = "ok" if result["ok"] else "FAIL"
+        print(f"  [{mark}] {result['detail']} ({result['files']} files)")
+        return 0 if result["ok"] else 1
+    print(f"unknown backup subcommand: {sub}")
+    return 2
+
+
+def cmd_costs(args: argparse.Namespace) -> int:
+    """`omega costs` — project usage into USD per provider/account."""
+    from omega_engine.account import AccountPool, BillingAggregator
+    from omega_engine.costs import (
+        RATE_CARD_DATE, estimate_cost, rate_card_summary,
+    )
+    from omega_engine.store import SQLiteStore
+    home = _omega_home()
+    print(f"omega costs — rate card from {RATE_CARD_DATE}")
+    print(f"  providers covered: {', '.join(rate_card_summary()['providers'])}")
+    print()
+    store_path = home / "Agentik_Runtime" / "eventlog" / "omega.db"
+    if not store_path.exists():
+        print("  (no event store yet)")
+        return 0
+    store = SQLiteStore(store_path)
+    totals = BillingAggregator.from_event_log(store)
+    pool = AccountPool.load(home)
+    if not totals:
+        print("  (no per-account usage recorded)")
+        store.close()
+        return 0
+    pool_ids = {a.id: a for a in pool.accounts}
+    grand = 0.0
+    print(f"  {'account':<18} {'provider':<10} {'in_tok':>12} {'out_tok':>12} {'USD':>8}")
+    print(f"  {'-' * 64}")
+    for acc_id, t in sorted(totals.items()):
+        # Assume Claude unless the operator overrode in accounts.yaml later.
+        provider = "claude"
+        cost = estimate_cost(
+            provider,
+            input_tokens=int(t["input_tokens"]),
+            output_tokens=int(t["output_tokens"]),
+        )
+        grand += cost
+        print(f"  {acc_id:<18} {provider:<10} {t['input_tokens']:>12,d} "
+              f"{t['output_tokens']:>12,d} {cost:>7.2f}")
+    print(f"  {'-' * 64}")
+    print(f"  {'TOTAL':<29} {grand:>40.2f} USD")
+    store.close()
+    return 0
+
+
+def cmd_audit_diff(args: argparse.Namespace) -> int:
+    """`omega audit diff <run-id-1> <run-id-2>` — structural diff of two runs."""
+    from omega_engine.audit_diff import diff_runs
+    home = _omega_home()
+    try:
+        d = diff_runs(home, args.run1, args.run2)
+    except KeyError as exc:
+        print(f"error: {exc}")
+        return 2
+    print(f"audit diff: {d.audit_id}")
+    print(f"  {d.run1} → {d.run2}")
+    print(f"  score: {d.score1} → {d.score2}  (delta {d.delta:+d})")
+    print(f"  fixed:     {len(d.fixed)}")
+    print(f"  new:       {len(d.new)}")
+    print(f"  persist:   {len(d.persist)}")
+    print(f"  regressed: {len(d.regressed)}")
+    if d.new:
+        print(f"  NEW findings:")
+        for f in d.new[:5]:
+            print(f"    [{f.get('severity', '?')}] {f.get('location', '?')} "
+                  f"— {str(f.get('message', f.get('claim', '')))[:60]}")
+    if d.regressed:
+        print(f"  REGRESSED:")
+        for f in d.regressed[:5]:
+            print(f"    [{f.get('severity', '?')}] {f.get('location', '?')}")
+    return 0
+
+
+def cmd_mission(args: argparse.Namespace) -> int:
+    """`omega mission rerun <id>` — re-dispatch a past mission with fresh state."""
+    from omega_engine.reducer import reduce_task
+    from omega_engine.store import SQLiteStore
+    home = _omega_home()
+    sub = args.mission_cmd
+    if sub == "rerun":
+        store_path = home / "Agentik_Runtime" / "eventlog" / "omega.db"
+        if not store_path.exists():
+            print("no event store yet")
+            return 1
+        store = SQLiteStore(store_path)
+        # Find the root task for this mission_id by scanning created events.
+        events = store.all_events() if hasattr(store, "all_events") else []
+        if not events:
+            # Fall back: load events for each task and find one with matching mission_id.
+            for tid in store.task_ids():
+                for evt in store.events_for(tid):
+                    if (evt.payload.get("mission_id") == args.id
+                            and evt.payload.get("role") == "oracle"):
+                        events.append(evt)
+                        break
+        # Extract intent from the first created event with that mission_id.
+        intent = None
+        for tid in store.task_ids():
+            for evt in store.events_for(tid):
+                if (evt.payload.get("mission_id") == args.id
+                        and evt.type.value == "task.created"
+                        and evt.payload.get("role") == "oracle"):
+                    # The original intent is in the spec; we don't have it directly
+                    # on the event. Best-effort: use the description from the
+                    # store if we can find it. Otherwise fall back to a hint.
+                    spec = evt.payload.get("spec") or {}
+                    intent = spec.get("intent") or spec.get("task")
+                    break
+            if intent:
+                break
+        store.close()
+        if not intent:
+            print(f"could not find original intent for mission {args.id}")
+            return 1
+        print(f"re-running mission with intent: {intent[:100]}")
+        from omega_engine.mission import run_mission
+        outcome = run_mission(intent)
+        print(f"new mission: {outcome.result.mission_id}  "
+              f"final={outcome.result.final_state.value}")
+        return 0 if outcome.result.verified else 1
+    print(f"unknown mission subcommand: {sub}")
+    return 2
+
+
+def cmd_precommit(args: argparse.Namespace) -> int:
+    """`omega project precommit install <slug>` — wire audit into pre-commit."""
+    import shutil as _sh
+    home = _omega_home()
+    sub = args.precommit_cmd or "install"
+    proj_dir = home / "Agentik_Coding" / "projects" / args.slug
+    if not proj_dir.is_dir():
+        print(f"project not found: {proj_dir}")
+        return 1
+    if sub == "install":
+        hooks_dir = proj_dir / ".git" / "hooks"
+        if not hooks_dir.is_dir():
+            print(f"  not a git repo: {proj_dir}/.git missing")
+            return 1
+        hook = hooks_dir / "pre-commit"
+        if hook.exists():
+            backup = hook.with_suffix(".pre-omega.bak")
+            _sh.copy(hook, backup)
+            print(f"  backed up existing hook → {backup}")
+        omega_bin = home / "Agentik_Tools" / "bin" / "omega"
+        hook.write_text(f"""#!/usr/bin/env bash
+# omega pre-commit — audit before code lands.
+set -e
+"{omega_bin}" audit run codeaudit --scope . || {{
+  echo "omega: codeaudit failed — commit blocked. Run: omega audit run codeaudit --fix"
+  exit 1
+}}
+""")
+        hook.chmod(0o755)
+        print(f"  pre-commit hook installed at {hook}")
+        return 0
+    if sub == "uninstall":
+        hook = proj_dir / ".git" / "hooks" / "pre-commit"
+        if hook.exists():
+            hook.unlink()
+            print(f"  removed {hook}")
+            backup = hook.with_suffix(".pre-omega.bak")
+            if backup.exists():
+                _sh.move(backup, hook)
+                print(f"  restored prior hook from {backup}")
+        return 0
+    print(f"unknown precommit subcommand: {sub}")
+    return 2
+
+
+def cmd_webhook(args: argparse.Namespace) -> int:
+    """Inbound-webhook CLI: list, show, test.
+
+    Webhooks live in ``Agentik_SSOT/webhooks/webhooks.yaml``. The engine
+    daemon's HTTP server listens at ``127.0.0.1:OMEGA_ENGINE_PORT/webhook/<id>``
+    — pair with a reverse proxy / tunnel for the public face. The auth
+    is HMAC-SHA256 signature verification per source (GitHub / Linear /
+    generic).
+    """
+    from omega_engine.webhooks import (
+        WebhookSpec,
+        generate_test_signature,
+        handle_webhook,
+        load_registry,
+    )
+    home = _omega_home()
+    sub = args.webhook_cmd
+    reg = load_registry(home)
+
+    if sub is None or sub == "list":
+        if not reg.specs:
+            print("(no webhooks configured — see manifest.example.yaml `webhooks:` block)")
+            return 0
+        for s in reg.specs:
+            print(f"  [{s.source:<7}] {s.id:<20} {s.path}  (secret_ref={s.secret_ref})")
+            if s.description:
+                print(f"            {s.description}")
+        return 0
+
+    if sub == "show":
+        s = reg.by_id(args.id)
+        if s is None:
+            print(f"no webhook with id {args.id!r}")
+            return 1
+        import json as _json
+        print(_json.dumps(s.__dict__, indent=2))
+        return 0
+
+    if sub == "test":
+        s = reg.by_id(args.id)
+        if s is None:
+            print(f"no webhook with id {args.id!r}")
+            return 1
+        # Load the secret + build a signed payload + run the gate locally.
+        from omega_engine.webhooks import _load_secret
+        secret = _load_secret(home, s.secret_ref)
+        if not secret:
+            print(
+                f"error: secret {s.secret_ref!r} is not in the vault — "
+                f"set it with `omega project secret set` or write to the vault first"
+            )
+            return 2
+        body = (args.body or '{"intent": "synthetic test"}').encode("utf-8")
+        sig = generate_test_signature(s.source, body, secret)
+        from omega_engine.webhooks import signature_header_for
+        headers = {signature_header_for(s.source): sig}
+        result = handle_webhook(
+            home, path=s.path, headers=headers, body=body, supervisor=None,
+        )
+        print(f"  gate: status={result['status']} ok={result['ok']} "
+              f"reason={result['reason']}")
+        return 0 if result["ok"] else 1
+
+    print(f"unknown webhook subcommand: {sub}")
+    return 2
+
+
+def cmd_uninstall(args: argparse.Namespace) -> int:
+    """Clean removal of OmegaOS from this machine.
+
+    What we touch (with confirmations):
+
+      * the 8-block tree at ``$OMEGA_HOME`` (the SSOT + engine + runtime)
+      * the symlink ``Agentik_Tools/bin/omega``
+      * the OmegaOS-specific keys in ``~/.claude/settings.json``
+        (env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, the Stop-hook entry
+        tagged ``omega-audit-gate``)
+      * the systemd user units / launchd plists
+      * optionally the LLM CLIs (``--include-llm-clis``)
+
+    What we DON'T touch unless asked:
+
+      * the encrypted vault — without ``--purge``, we move it to
+        ``$HOME/.omega-vault-backup-<timestamp>/`` so the operator can
+        decrypt later
+      * the LLM CLIs (need ``--include-llm-clis``)
+    """
+    import json as _json
+    import shutil as _sh
+    import subprocess
+    import time
+
+    home = _omega_home()
+    print(f"omega uninstall — OMEGA_HOME={home}")
+    if not home.exists():
+        print("  (nothing to remove — directory does not exist)")
+        return 0
+
+    if not args.yes:
+        try:
+            resp = input(f"  remove {home} and related files? [y/N] ").strip()
+        except EOFError:
+            resp = ""
+        if resp.lower() not in {"y", "yes"}:
+            print("  aborted")
+            return 1
+
+    # 1. Stop + disable services first (best effort).
+    import platform
+    if platform.system() == "Linux" and _sh.which("systemctl"):
+        for unit in ("omega-engine", "omega-telegram", "omega-autonomous"):
+            subprocess.run(
+                ["systemctl", "--user", "disable", "--now", f"{unit}.service"],
+                check=False, capture_output=True, timeout=30,
+            )
+        unitdir = Path.home() / ".config" / "systemd" / "user"
+        for unit in ("omega-engine", "omega-telegram", "omega-autonomous"):
+            (unitdir / f"{unit}.service").unlink(missing_ok=True)
+        subprocess.run(["systemctl", "--user", "daemon-reload"],
+                       check=False, capture_output=True, timeout=15)
+        print("  removed systemd user services")
+    elif platform.system() == "Darwin" and _sh.which("launchctl"):
+        agentdir = Path.home() / "Library" / "LaunchAgents"
+        for label in ("com.agentikos.omega.engine",
+                      "com.agentikos.omega.telegram",
+                      "com.agentikos.omega.autonomous"):
+            p = agentdir / f"{label}.plist"
+            if p.exists():
+                subprocess.run(["launchctl", "bootout", f"gui/{os.getuid()}",
+                                str(p)], check=False, capture_output=True,
+                               timeout=15)
+                p.unlink(missing_ok=True)
+        print("  removed launchd LaunchAgent plists")
+
+    # 2. Settings.json — strip our keys, keep operator changes.
+    settings_path = Path.home() / ".claude" / "settings.json"
+    if settings_path.exists():
+        try:
+            data = _json.loads(settings_path.read_text())
+            changed = False
+            env_block = data.get("env") or {}
+            if "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" in env_block:
+                env_block.pop("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS")
+                data["env"] = env_block
+                changed = True
+            hooks = data.get("hooks") or {}
+            stop_entries = hooks.get("Stop") or []
+            cleaned = [
+                e for e in stop_entries
+                if not (isinstance(e, dict) and e.get("tag") == "omega-audit-gate")
+            ]
+            if len(cleaned) != len(stop_entries):
+                hooks["Stop"] = cleaned
+                data["hooks"] = hooks
+                changed = True
+            if changed:
+                settings_path.write_text(_json.dumps(data, indent=2) + "\n")
+                print(f"  cleaned OmegaOS keys from {settings_path}")
+        except Exception as exc:  # noqa: BLE001
+            print(f"  (could not edit settings.json: {exc})")
+
+    # 3. Vault — back up unless --purge.
+    secrets = home / "Agentik_Extra" / "etc" / "secrets"
+    if secrets.is_dir():
+        if args.purge:
+            print(f"  purging vault at {secrets}")
+        else:
+            backup = (Path.home() /
+                      f".omega-vault-backup-{int(time.time())}")
+            _sh.move(str(secrets), str(backup))
+            print(f"  vault backed up to {backup} (move back if you reinstall)")
+
+    # 4. Remove the 8-block tree.
+    print(f"  removing {home}")
+    try:
+        _sh.rmtree(home)
+    except OSError as exc:
+        print(f"  WARNING: removal incomplete: {exc}")
+        return 1
+
+    # 5. Optional: LLM CLIs.
+    if args.include_llm_clis:
+        helper = (Path(os.environ.get("OMEGA_REPO", ".")) /
+                  "bootstrap" / "lib" / "llm-clis.py")
+        if helper.exists():
+            print("  uninstalling LLM CLIs...")
+            subprocess.run(
+                ["python3", str(helper), "uninstall",
+                 "claude_code", "gemini_cli", "codex", "glm_sdk", "aider"],
+                check=False, timeout=600,
+            )
+        else:
+            print("  (llm-clis helper unavailable — skipped)")
+
+    print("uninstall complete")
+    return 0
+
+
+def cmd_upgrade(args: argparse.Namespace) -> int:
+    """Smart re-install: detect existing tree, run install.sh in-place.
+
+    Idempotent. Use to pick up new install steps without losing the
+    runtime tree (event log, vault, account pool). Equivalent to running
+    ``bash $OMEGA_REPO/install.sh --force`` from inside.
+    """
+    import subprocess
+    repo = os.environ.get("OMEGA_REPO")
+    if not repo:
+        # Try to infer from the engine's location.
+        engine_path = Path(__file__).resolve().parent.parent.parent
+        candidate = engine_path.parent
+        if (candidate / "install.sh").exists():
+            repo = str(candidate.parent)
+        else:
+            print("error: OMEGA_REPO is not set and install.sh cannot be located")
+            print("       set OMEGA_REPO=<path-to-OmegaOS-clone> and retry")
+            return 1
+    install_sh = Path(repo) / "install.sh"
+    if not install_sh.exists():
+        print(f"error: install.sh not found at {install_sh}")
+        return 1
+    cmd = ["bash", str(install_sh), "--force"]
+    if args.profile:
+        cmd += ["--profile", args.profile]
+    if args.manifest:
+        cmd += ["--manifest", args.manifest]
+    if args.non_interactive:
+        cmd += ["--non-interactive"]
+    print(f"upgrading via {' '.join(cmd)}")
+    # 30 minutes — install steps can be slow (apt-get + npm + venv build).
+    proc = subprocess.run(cmd, check=False, timeout=1800)
+    return proc.returncode
+
+
+def cmd_skill(args: argparse.Namespace) -> int:
+    """Skill discovery + safety audit CLI.
+
+    Subcommands:
+      * ``find [<query>]``           — list curated catalog entries
+      * ``audit <path>``             — run static safety auditor on a SKILL.md
+      * ``install <name> --from github:<org>/<repo>[/<path>]``
+                                       — git-clone + audit + place in SSOT
+      * ``marketplaces``             — show the catalog with trust levels
+    """
+    sub = args.skill_cmd
+    home = _omega_home()
+    if sub is None:
+        print("usage: omega skill {find|audit|install|marketplaces} ...")
+        return 2
+
+    if sub == "marketplaces":
+        from omega_engine.skill_discovery import load_marketplaces
+        for m in load_marketplaces(home):
+            mark = " (builtin)" if m.builtin else ""
+            print(f"  [{m.trust:<6}] {m.id:<25} {m.source}{mark}")
+            if m.description:
+                print(f"             {m.description}")
+        return 0
+
+    if sub == "find":
+        from omega_engine.skill_discovery import discover_skills
+        hits = discover_skills(
+            home, query=args.query, min_trust=args.min_trust,
+            recommended_only=args.recommended,
+        )
+        if not hits:
+            print("(no skills match)")
+            return 0
+        for s in hits:
+            rec = " ★" if s.recommended else "  "
+            print(
+                f"{rec}[{s.marketplace_trust:<6}] {s.name:<22} "
+                f"({s.marketplace_id})"
+            )
+            if s.description:
+                print(f"          {s.description}")
+        return 0
+
+    if sub == "audit":
+        from omega_engine.skill_discovery import audit_skill_file
+        v = audit_skill_file(args.path)
+        print(f"audit: {v.skill_name}  score={v.score}  "
+              f"verified={v.verified}")
+        if v.issues:
+            for i in v.issues:
+                print(f"  [{i.severity:<5}] {i.rule}: {i.message}")
+                if i.excerpt:
+                    print(f"          excerpt: {i.excerpt}")
+        return 0 if v.verified else 1
+
+    if sub == "recommend":
+        from omega_engine.skill_routing import (
+            POWER_SKILLS, catalog_for_home, recommend,
+        )
+        role = args.role
+        recs = recommend(role)
+        catalog = set(catalog_for_home(home))
+        if not recs:
+            print(f"no curated recommendation for role '{role}'")
+            print(f"power skills: {', '.join(POWER_SKILLS)}")
+            return 0
+        print(f"## Recommended skills for role '{role}'")
+        for s in recs:
+            present = "✓" if s in catalog else "✗"
+            print(f"  {present} {s}")
+        missing = [s for s in recs if s not in catalog]
+        if missing:
+            print()
+            print(
+                f"missing from SSOT: {', '.join(missing)}  "
+                "(run `omega sync` to project, or `omega skill install …`)"
+            )
+        return 0
+
+    if sub == "catalog":
+        from omega_engine.skill_routing import catalog_for_home
+        cat = catalog_for_home(home)
+        if not cat:
+            print(f"no skills under {home}/Agentik_SSOT/skills/")
+            return 0
+        print(f"## {len(cat)} skills in $OMEGA_HOME/Agentik_SSOT/skills/")
+        for s in cat:
+            print(f"  /{s}")
+        return 0
+
+    if sub == "link":
+        # Bridge the projected SSOT skills into ~/.claude/skills/ so they
+        # become real slash commands in Claude Code. Idempotent.
+        from omega_engine.sync import ClaudeCodeAdapter
+        adapter = ClaudeCodeAdapter()
+        # Make sure the provider tree exists first.
+        adapter.project(home)
+        info = adapter.link_to_user_claude(home)
+        print(f"linked → {info['user_claude']}")
+        print(f"  skills:   +{info['linked_skills']}")
+        print(f"  commands: +{info['linked_commands']}")
+        print(f"  agents:   +{info['linked_agents']}")
+        if info["removed"]:
+            print(f"  removed stale links: {len(info['removed'])}")
+        return 0
+
+    if sub == "workflows":
+        # Show canonical workflow chains so operators can SEE how skills
+        # compose. This is documentation surfaced via the CLI — no I/O.
+        from omega_engine.skill_routing import WORKFLOWS
+        if args.name:
+            wf = WORKFLOWS.get(args.name)
+            if not wf:
+                print(f"unknown workflow: {args.name}")
+                print(f"available: {', '.join(WORKFLOWS.keys())}")
+                return 2
+            print(f"## {args.name}")
+            print()
+            print(wf)
+            return 0
+        print("## Canonical skill workflows")
+        print()
+        for name, body in WORKFLOWS.items():
+            first_line = body.strip().splitlines()[0]
+            print(f"  {name:24s}  {first_line}")
+        print()
+        print("Run `omega skill workflows <name>` for the full chain.")
+        return 0
+
+    if sub == "install":
+        if not args.from_:
+            print("usage: omega skill install <name> --from github:<org>/<repo>[/<path>]")
+            return 2
+        if not args.from_.startswith("github:"):
+            print("only github:<org>/<repo>[/<path>] sources are supported "
+                  "in CLI install; use `claude plugin install` for marketplace plugins")
+            return 2
+        repo_and_path = args.from_.split(":", 1)[1]
+        if "/" in repo_and_path:
+            parts = repo_and_path.split("/")
+            if len(parts) >= 3:
+                repo = "/".join(parts[:2])
+                sub_path = "/".join(parts[2:])
+            else:
+                repo = repo_and_path; sub_path = ""
+        else:
+            repo = repo_and_path; sub_path = ""
+        from omega_engine.skill_discovery import install_skill_from_github
+        result = install_skill_from_github(
+            home, args.name, repo=repo, sub_path=sub_path,
+            allow_blocked=args.allow_blocked,
+        )
+        if result.audit:
+            print(f"audit: score={result.audit.score} verified={result.audit.verified}")
+            for i in result.audit.issues:
+                print(f"  [{i.severity:<5}] {i.rule}: {i.message}")
+        if result.installed:
+            print(f"installed: {result.skill_path}")
+            print("run `omega sync` to project into ~/.claude/skills/")
+            return 0
+        print(f"NOT installed — {result.reason}")
+        return 1
+
+    print(f"unknown skill subcommand: {sub}")
+    return 2
+
+
+def cmd_agent(args: argparse.Namespace) -> int:
+    """Inspect or list the resolved agent prompts.
+
+    ``omega agent list``           → every loadable role under
+                                      Agentik_SSOT/agents/.
+    ``omega agent prompt <role>``  → print the system prompt that the
+                                      envelope builds for that role
+                                      (agent file + LMC protocol +
+                                      orchestration contract).
+    """
+    sub = args.agent_cmd
+    home = _omega_home()
+    if sub is None or sub == "list":
+        from omega_engine.prompts import list_available_agents
+        suites = list_available_agents(home)
+        if not suites:
+            print(f"(no agents in {home}/Agentik_SSOT/agents/)")
+            return 0
+        for suite, roles in suites.items():
+            print(f"suite '{suite}': {len(roles)} agent(s)")
+            for r in roles:
+                print(f"  - {r}")
+        return 0
+    if sub == "prompt":
+        from omega_engine.envelope import EnvelopeContext, build_envelope
+        ctx = EnvelopeContext(
+            role=args.role,
+            intent=args.intent or "(no intent — preview only)",
+            task_id="preview",
+        )
+        env = build_envelope(home, ctx)
+        print("=== SYSTEM ===")
+        print(env["system"])
+        print()
+        print("=== USER ===")
+        print(env["user"])
+        return 0
+    print(f"unknown agent subcommand: {sub}")
+    return 2
+
+
+def cmd_audit(args: argparse.Namespace) -> int:
+    """The unified audit CLI.
+
+    Subcommands:
+      * ``run <id>``       — run one audit (gather + analyse).
+      * ``run <id> --fix`` — also batch + dispatch fix workers + re-audit.
+      * ``all``            — run every applicable audit (read-only).
+      * ``history <id>``   — show past scores for one audit.
+      * ``batch <id>``     — show what batches the last run would form
+                              (dry-run; no dispatch).
+      * ``gen``            — regenerate every SKILL.md from the YAMLs.
+    """
+    sub = args.audit_cmd
+    home = _omega_home()
+    if sub is None:
+        print("usage: omega audit {run|all|history|batch|gen} ...")
+        return 2
+
+    if sub == "gen":
+        from omega_engine.audits.generator import write_all
+        result = write_all(home / "Agentik_SSOT" / "audits")
+        print(f"audit SKILL.md generation: "
+              f"{result['written']} written, {result['skipped']} unchanged")
+        return 0
+
+    if sub == "gate":
+        # Called by the Claude Code Stop hook — reads JSON on stdin and
+        # emits the permission decision on stdout. See omega_engine.audit_gate.
+        from omega_engine.audit_gate import gate
+        return gate()
+
+    if sub == "history":
+        from omega_engine.audits.history import list_runs, trend
+        runs = list_runs(home, audit_id=args.audit_id, limit=args.limit)
+        if not runs:
+            print(f"no runs recorded for {args.audit_id!r}")
+            return 0
+        symbol = trend(home, args.audit_id) if args.audit_id else "→"
+        print(f"history for {args.audit_id} (trend: {symbol})")
+        for r in runs:
+            from datetime import datetime, timezone
+            t = datetime.fromtimestamp(r.timestamp, tz=timezone.utc).isoformat()
+            ra = (f" → {r.reaudit_score}"
+                  if r.reaudit_score is not None else "")
+            mark = "ok" if r.verified else "FAIL"
+            print(
+                f"  [{mark}] {r.run_id}  score={r.score}{ra}  "
+                f"findings={r.finding_count}  workers={r.fix_workers_dispatched}  "
+                f"({t})"
+            )
+        return 0
+
+    if sub in ("run", "all"):
+        from omega_engine.audit_arsenal import AuditRegistry
+        from omega_engine.audits.pipeline import AuditPipeline
+        from omega_engine.router import ModelRouter
+        from omega_engine.provider import MockProvider
+
+        audits_dir = home / "Agentik_SSOT" / "audits"
+        if not audits_dir.is_dir():
+            print(f"error: audits dir missing: {audits_dir}")
+            return 1
+        registry = AuditRegistry.load(audits_dir)
+        # MockProvider when no real provider is configured — keeps the CLI
+        # usable on dev machines without an API key. The doctor flags the
+        # provider state separately.
+        router = ModelRouter.single(MockProvider())
+        executor = None
+        if args.fix:
+            from omega_engine.audit import AuditGate
+            from omega_engine.bus import EventBus
+            from omega_engine.executor import Executor
+            from omega_engine.store import SQLiteStore
+            store = SQLiteStore(
+                home / "Agentik_Runtime" / "eventlog" / "omega.db"
+            )
+            bus = EventBus(store)
+            executor = Executor(store, bus, router, AuditGate(),
+                                partial_policy="accept_partial")
+
+        pipeline = AuditPipeline(registry, router, omega_home=home,
+                                  executor=executor)
+
+        if sub == "run":
+            try:
+                outcome = pipeline.run(
+                    args.audit_id, scope=args.scope or ".",
+                    role=args.role, read_only=not args.fix,
+                    max_batches=args.max_workers,
+                    min_severity=args.min_severity,
+                )
+            except KeyError as exc:
+                print(f"error: {exc}")
+                return 2
+            _print_outcome(outcome)
+            return 0 if outcome.verdict.verified else 1
+
+        # sub == "all"
+        outcomes = pipeline.run_all_applicable(
+            scope=args.scope or ".", role=args.role,
+            read_only=not args.fix,
+        )
+        any_fail = False
+        for o in outcomes:
+            _print_outcome(o, compact=True)
+            if not o.verdict.verified:
+                any_fail = True
+        return 1 if any_fail else 0
+
+    if sub == "batch":
+        from omega_engine.audit_arsenal import AuditRegistry
+        from omega_engine.audits.batcher import Finding, batch_findings
+        from omega_engine.audits.history import list_runs
+
+        runs = list_runs(home, audit_id=args.audit_id, limit=1)
+        if not runs:
+            print(f"no run recorded for {args.audit_id!r} — run it first")
+            return 1
+        run = runs[0]
+        findings = [
+            Finding.from_dict(f)
+            for f in run.verdict.get("findings", [])
+        ]
+        plan = batch_findings(
+            findings, audit_id=args.audit_id,
+            max_batches=args.max_workers,
+            min_severity=args.min_severity,
+        )
+        print(f"batch plan for {args.audit_id} run {run.run_id}:")
+        for b in plan.batches:
+            print(f"  {b.id}: {len(b.findings)} finding(s) across "
+                  f"{len(b.files)} file(s) — score={b.score}")
+            for f in b.findings[:5]:
+                print(f"     - [{f.severity}] {f.file or '(global)'} — "
+                      f"{f.message[:70]}")
+            if len(b.findings) > 5:
+                print(f"     ... and {len(b.findings) - 5} more")
+        if plan.deferred:
+            print(f"  deferred: {len(plan.deferred)} finding(s) "
+                  "(over batch cap)")
+        return 0
+
+    print(f"unknown audit subcommand: {sub}")
+    return 2
+
+
+def _print_outcome(outcome, *, compact: bool = False) -> None:
+    v = outcome.verdict
+    mark = "ok" if v.verified else "FAIL"
+    head = (f"[{mark}] {outcome.audit_id:<18} score={v.score:>3}  "
+            f"findings={len(v.findings):>3}  "
+            f"({outcome.elapsed_s}s)")
+    if outcome.reaudit:
+        head += f"  reaudit={outcome.reaudit.score:>3}"
+    if compact:
+        print(f"  {head}")
+        return
+    print(head)
+    print(f"  run_id: {outcome.run_id}")
+    if v.summary:
+        print(f"  summary: {v.summary[:200]}")
+    if outcome.plan:
+        for b in outcome.plan.batches:
+            print(f"  batch {b.id}: {len(b.findings)} findings, "
+                  f"{len(b.files)} file(s)")
+    for d in outcome.dispatches:
+        print(f"  dispatch {d.batch_id}: {d.status} "
+              + (f"mission={d.mission_id}" if d.mission_id else d.reason))
+
+
+def cmd_pursue(args: argparse.Namespace) -> int:
+    """Drive an agent toward a verifiable goal via the engine's pursue loop.
+
+    Agentik OS native equivalent of goal-driven workers (replaces /goal).
+    Uses the Max subscription path: any registered provider (Mock for tests,
+    Claude for real). Writes per-iteration logs and a structured .done.json.
+    """
+    from omega_engine.pursue import pursue
+    result = pursue(
+        intent=args.intent,
+        verify_cmd=args.verify_cmd,
+        omega_home=_omega_home(),
+        max_iterations=args.max_iters,
+        project=args.project,
+        role=args.role,
+        cwd=args.cwd,
+    )
+    print(f"pursue {result.task_id}: {result.status} "
+          f"after {result.iterations} iter(s) (verify_exit={result.final_verify_exit})")
+    print(f"  log:  {result.log_path}")
+    print(f"  done: {result.done_path}")
+    return 0 if result.status == "done_clean" else 1
+
+
+def cmd_cadence(args: argparse.Namespace) -> int:
+    """Schedule, list, disable, or remove a recurring beat.
+
+    Agentik OS native equivalent of /loop — uses the AutonomousSupervisor
+    so the schedule survives Claude Code sessions and editor restarts.
+    """
+    from omega_engine.cadence import (
+        disable_cadence,
+        list_cadences,
+        remove_cadence,
+        schedule_cadence,
+    )
+    sub = args.cadence_cmd
+    home = _omega_home()
+
+    if sub is None:
+        print("usage: omega cadence {schedule|list|disable|remove} ...")
+        return 2
+    if sub == "schedule":
+        if not (args.trigger and args.schedule and args.intent):
+            print("usage: omega cadence schedule <cron|delay|self> <schedule> <intent>")
+            return 2
+        try:
+            path = schedule_cadence(
+                intent=args.intent,
+                trigger_type=args.trigger,
+                schedule=args.schedule,
+                omega_home=home,
+            )
+        except ValueError as exc:
+            print(f"error: {exc}")
+            return 2
+        print(f"scheduled: {path}")
+        return 0
+    if sub == "list":
+        entries = list_cadences(home)
+        if not entries:
+            print("(no cadences scheduled)")
+            return 0
+        print(f"{len(entries)} cadence(s):")
+        for e in entries:
+            tr = e["trigger"]
+            mark = "ok" if e["enabled"] else "off"
+            print(f"  [{mark}] {e['id']} ({tr.get('type', '?')}/{tr.get('schedule', '?')}) → {e['intent'][:60]}")
+        return 0
+    if sub == "disable":
+        if not args.id:
+            print("usage: omega cadence disable <id>")
+            return 2
+        if disable_cadence(args.id, omega_home=home):
+            print(f"disabled {args.id}")
+            return 0
+        print(f"no enabled cadence with id {args.id!r}")
+        return 1
+    if sub == "remove":
+        if not args.id:
+            print("usage: omega cadence remove <id>")
+            return 2
+        if remove_cadence(args.id, omega_home=home):
+            print(f"removed {args.id}")
+            return 0
+        print(f"no cadence with id {args.id!r}")
+        return 1
+    print(f"unknown cadence subcommand: {sub}")
+    return 2
+
+
+def cmd_daemon(args: argparse.Namespace) -> int:
+    """Run one of the 24/7 service daemons.
+
+    ``omega daemon engine``      — the event-store keeper + local HTTP API.
+    ``omega daemon telegram``    — long-polls Telegram, routes inbound messages.
+    ``omega daemon autonomous``  — runs the autonomous-agent supervisor.
+
+    The installer's systemd user units invoke these.
+    """
+    name = args.name
+    if name == "engine":
+        from omega_engine.daemons import engine as d
+        return d.main()
+    if name == "telegram":
+        from omega_engine.daemons import telegram as d
+        return d.main()
+    if name == "autonomous":
+        from omega_engine.daemons import autonomous as d
+        return d.main()
+    print(f"unknown daemon: {name!r} — expected engine|telegram|autonomous")
+    return 2
+
+
+def cmd_classify(args: argparse.Namespace) -> int:
+    """`omega classify "<task>"` — show how the router would classify it."""
+    from omega_engine.classifier import classify
+    c = classify(args.task, role=args.role)
+    print(f"  bucket:     {c.bucket}")
+    print(f"  confidence: {c.confidence}")
+    print(f"  suggested:  {c.suggested_model}")
+    print(f"  reason:     {c.reason}")
+    return 0
+
+
+def cmd_memory(args: argparse.Namespace) -> int:
+    """`omega memory {reindex,search,stats}` — semantic memory across sources."""
+    from omega_engine import memory
+    home = _omega_home()
+    sub = args.memory_cmd or "stats"
+    if sub == "reindex":
+        counts = memory.reindex(home)
+        print(f"  total:     {counts['total']}")
+        print(f"  telegram:  {counts['telegram']}")
+        print(f"  done_json: {counts['done_json']}")
+        print(f"  audit:     {counts['audit']}")
+        return 0
+    if sub == "search":
+        hits = memory.search(home, args.query, k=args.k)
+        if not hits:
+            print("  (no matches — try `omega memory reindex` first)")
+            return 0
+        from datetime import datetime, timezone
+        for h in hits:
+            t = (datetime.fromtimestamp(h.timestamp, tz=timezone.utc)
+                 .strftime("%Y-%m-%d %H:%M")
+                 if h.timestamp else "?")
+            print(f"  [{h.source:<10}] {h.ref}  ({t})  score={h.score:.3f}")
+            for line in h.text.splitlines()[:3]:
+                print(f"      {line[:120]}")
+        return 0
+    if sub == "stats":
+        stats = memory.index_stats(home)
+        if not stats["indexed"]:
+            print("  no index yet — run `omega memory reindex`")
+            return 0
+        print(f"  indexed:    {stats['total']:,d} documents")
+        print(f"  size:       {stats['size_bytes']:,d} bytes")
+        return 0
+    print(f"unknown memory subcommand: {sub}")
+    return 2
+
+
+def cmd_learn(args: argparse.Namespace) -> int:
+    """`omega learn {reflect,report}` — Smith reflection."""
+    from omega_engine.learning import reflect
+    home = _omega_home()
+    sub = args.learn_cmd or "reflect"
+    if sub == "reflect":
+        report = reflect(home, write_proposals=args.write)
+        print(f"  insights: {len(report.insights)}")
+        for ins in report.insights:
+            print(f"\n  [{ins.severity:<4}] {ins.kind}")
+            print(f"  ─ {ins.title}")
+            print(f"    {ins.detail[:200]}")
+            if ins.proposed_action:
+                print(f"    → {ins.proposed_action[:200]}")
+        if args.write and report.insights:
+            print(f"\n  proposals written to "
+                  f"{home}/Agentik_Extra/staging/promotion/")
+        return 0
+    if sub == "report":
+        # Print the last report (just the structured form).
+        import json as _json
+        report = reflect(home, write_proposals=False)
+        print(_json.dumps(report.to_dict(), indent=2))
+        return 0
+    print(f"unknown learn subcommand: {sub}")
+    return 2
+
+
+def cmd_message(args: argparse.Namespace) -> int:
+    """`omega message {send,read,wait,open}` — worker ↔ oracle messaging."""
+    from omega_engine import agent_messages as am
+    home = _omega_home()
+    sub = args.message_cmd or "open"
+    if sub == "send":
+        try:
+            msg = am.send(home, args.task_id,
+                          from_=args.from_, to=args.to,
+                          type=args.type, text=args.text)
+        except ValueError as exc:
+            print(f"  error: {exc}")
+            return 2
+        print(f"  sent: {msg.from_} → {msg.to} ({msg.type})")
+        return 0
+    if sub == "read":
+        msgs = am.read(home, args.task_id, for_recipient=args.to)
+        for m in msgs:
+            from datetime import datetime, timezone
+            t = datetime.fromtimestamp(m.ts, tz=timezone.utc).strftime("%H:%M:%S")
+            print(f"  [{t}] {m.from_} → {m.to} ({m.type}): {m.text[:200]}")
+        return 0
+    if sub == "wait":
+        msg = am.wait_for_reply(home, args.task_id,
+                                 for_recipient=args.to,
+                                 timeout_s=args.timeout)
+        if msg is None:
+            print(f"  timeout after {args.timeout}s")
+            return 1
+        print(f"  reply: {msg.from_} → {msg.to} ({msg.type}): {msg.text}")
+        return 0
+    if sub == "open":
+        opens = am.list_open_questions(home)
+        if not opens:
+            print("  (no open questions)")
+            return 0
+        for task_id, m in opens:
+            from datetime import datetime, timezone
+            t = datetime.fromtimestamp(m.ts, tz=timezone.utc).strftime("%H:%M")
+            print(f"  [{task_id}] {t} {m.from_} → {m.to}: {m.text[:120]}")
+        return 0
+    print(f"unknown message subcommand: {sub}")
+    return 2
+
+
+def cmd_tmux(args: argparse.Namespace) -> int:
+    """`omega tmux` — categorised tmux orchestration.
+
+    Mirrors the live VPS pattern: AISB / oracle / worker / dev / linear /
+    home / other. Spawn sessions via the right convention, attach without
+    blocking the shell, kill cleanly, and run a popup picker bound to
+    prefix+Z in the recommended tmux.conf.
+    """
+    from omega_engine import tmux
+    sub = args.tmux_cmd or "list"
+    home = _omega_home()
+
+    if sub == "list":
+        sessions = tmux.list_sessions(home)
+        if not sessions:
+            print("(no tmux sessions — run `omega tmux spawn <type> <name>` to start one)")
+            return 0
+        for cat, lst in tmux.grouped(sessions).items():
+            if not lst:
+                continue
+            print(f"  ── {cat} ────────────────────────────")
+            for s in lst:
+                star = "*" if s.attached else " "
+                proj = f"  [{s.project}]" if s.project else ""
+                print(f"  {star} {s.name:<50} {s.windows}w{proj}")
+        return 0
+
+    if sub == "count":
+        print(len(tmux.list_sessions(home)))
+        return 0
+
+    if sub == "attach":
+        if not tmux.is_alive(args.name):
+            print(f"no session: {args.name}")
+            return 1
+        cmd = tmux.attach_command(args.name)
+        print(cmd)
+        return 0
+
+    if sub == "kill":
+        if tmux.kill(args.name):
+            print(f"killed: {args.name}")
+            return 0
+        print(f"no such session: {args.name}")
+        return 1
+
+    if sub == "spawn":
+        kind = args.kind
+        name = args.name
+        cwd = args.cwd or os.getcwd()
+        if kind == "oracle":
+            real = tmux.spawn_oracle(name, cwd=cwd)
+        elif kind == "worker":
+            real = tmux.spawn_worker(name, args.task or "task", cwd=cwd)
+        elif kind == "aisb-chat":
+            real = tmux.spawn_aisb_chat(home)
+        else:
+            ok = tmux.spawn(name, cwd=cwd)
+            if not ok:
+                print(f"session already exists: {name}")
+                return 1
+            real = name
+        print(f"spawned: {real}")
+        print(f"attach:  {tmux.attach_command(real)}")
+        return 0
+
+    if sub == "health":
+        report = tmux.health_report(home)
+        if not report.get("tmux_installed"):
+            print("  tmux NOT installed — `omega upgrade` or apt install tmux")
+            return 1
+        print(f"  tmux installed: yes")
+        print(f"  sessions:       {report['sessions']} "
+              f"({report.get('attached', 0)} attached)")
+        for cat, names in report["by_category"].items():
+            print(f"    {cat:<8} {len(names):>3}")
+        if report["stale"]:
+            print(f"  STALE workers (>6h detached): {report['stale']}")
+        return 0
+
+    if sub == "cleanup":
+        result = tmux.cleanup_stale(home, older_than_hours=args.hours,
+                                     dry_run=not args.yes)
+        verb = "would kill" if result["dry_run"] else "killed"
+        print(f"  {verb} {len(result['candidates'])} stale worker session(s)")
+        for n in result["candidates"][:10]:
+            print(f"    - {n}")
+        return 0
+
+    if sub == "menu":
+        # Interactive whiptail picker. Designed to be invoked from a
+        # tmux popup (prefix+Z): we print "exec tmux switch-client -t <name>"
+        # which the popup can pipe through.
+        from omega_engine.menu import _have, _whiptail_menu
+        if not _have("whiptail"):
+            print("whiptail required for `omega tmux menu`")
+            return 2
+        sessions = tmux.list_sessions(home)
+        if not sessions:
+            print("(no sessions)")
+            return 0
+        items = []
+        for cat, lst in tmux.grouped(sessions).items():
+            for s in lst:
+                marker = "*" if s.attached else " "
+                items.append((s.name, f"[{cat}]{marker} {s.name[:50]}"))
+        if not items:
+            return 0
+        choice = _whiptail_menu(
+            "Tmux sessions", "Pick a session to attach:", items=items,
+        )
+        if choice is None:
+            return 0
+        # When invoked from a tmux popup, switch-client transitions cleanly.
+        if os.environ.get("TMUX"):
+            subprocess.run(["tmux", "switch-client", "-t", choice], timeout=5)
+        else:
+            print(tmux.attach_command(choice))
+        return 0
+
+    if sub == "config":
+        profile = getattr(args, "profile", "minimal")
+        path = tmux.write_default_config(profile=profile)
+        print(f"  wrote tmux config ({profile}): {path}")
+        print()
+        print("  To use it, either:")
+        print(f"     source {path}     # add this line to your ~/.tmux.conf")
+        print(f"     cp {path} ~/.tmux.conf")
+        print()
+        print("  OR run `omega tmux install` to write ~/.tmux.conf "
+              "directly (with backup).")
+        return 0
+
+    if sub == "install":
+        profile = getattr(args, "profile", "pro")
+        backup = not getattr(args, "no_backup", False)
+        res = tmux.install_into_home_tmux_conf(
+            profile=profile, backup=backup,
+        )
+        print(f"  ✓ ~/.tmux.conf installed (profile: {res['profile']})")
+        if res["backup_path"]:
+            print(f"     backup → {res['backup_path']}")
+        print(f"     bundled → {res['bundled_copy']}")
+        print()
+        print("  Reload tmux NOW:")
+        print("     - In a running tmux: prefix+r  (or tmux source-file ~/.tmux.conf)")
+        print("     - Or just: tmux kill-server  and start fresh")
+        print()
+        print("  Try the picker: tmux  →  prefix+Z  (or `omega tmux menu`)")
+        return 0
+
+    print(f"unknown tmux subcommand: {sub}")
+    return 2
+
+
+def cmd_aisb(args: argparse.Namespace) -> int:
+    """`omega aisb` — talk to the AISB master agent without Telegram.
+
+    Two sub-commands:
+      chat       — spawn (or attach to) the AISB-chat tmux session
+      chat-loop  — the REPL loop itself (run inside the tmux session)
+    """
+    from omega_engine import tmux
+    sub = args.aisb_cmd or "chat"
+    home = _omega_home()
+    if sub == "chat":
+        name = "AISB-chat"
+        if tmux.is_alive(name):
+            print(f"  session already exists: {name}")
+        else:
+            tmux.spawn_aisb_chat(home)
+            print(f"  spawned: {name}")
+        print(f"  attach:  {tmux.attach_command(name)}")
+        return 0
+    if sub == "chat-loop":
+        from omega_engine.aisb_chat import run_chat_loop
+        return run_chat_loop()
+    print(f"unknown aisb subcommand: {sub}")
+    return 2
+
+
+def cmd_menu(_args: argparse.Namespace) -> int:
+    """`omega` with no args → interactive whiptail menu (the on-ramp)."""
+    from omega_engine.menu import run_menu
+    return run_menu()
+
+
+def cmd_hermes_desktop(args: argparse.Namespace) -> int:
+    """`omega hermes-desktop {install,serve,profile,status}` — expose this
+    VPS as a remote backend for the Hermes Desktop Electron app."""
+    import json as _json
+    from omega_engine import hermes_desktop as HD
+    sub = getattr(args, "hd_cmd", None)
+    home = _omega_home()
+
+    if sub == "install" or sub is None:
+        tok = HD.generate_token(home)
+        prof = HD.build_profile(
+            public_url=getattr(args, "public_url", None),
+            port=args.port, omega_home=home,
+        )
+        print(f"  ✓ token generated: {HD.token_path(home)}")
+        print()
+        print("  Paste this profile into Hermes Desktop:")
+        print(f"     Name:    {prof.name}")
+        print(f"     URL:     {prof.base_url}")
+        print(f"     API key: {prof.api_key}")
+        print()
+        print("  Then start the server on the VPS:")
+        print(f"     omega hermes-desktop serve --port {args.port}")
+        print()
+        print("  Recommended deployment: tmux session (survives SSH disconnect)")
+        print(f"     tmux new -d -s omega-hd 'omega hermes-desktop serve --port {args.port}'")
+        return 0
+
+    if sub == "profile":
+        prof = HD.build_profile(
+            public_url=getattr(args, "public_url", None),
+            port=args.port, omega_home=home,
+        )
+        print(prof.to_json())
+        return 0
+
+    if sub == "status":
+        tok = HD.read_token(home)
+        free = HD.is_port_free(args.port)
+        print(f"  token:     {'✓ present' if tok else '✗ run install first'}"
+              f"  ({HD.token_path(home)})")
+        print(f"  port {args.port}: {'free (server not running)' if free else 'in use (server up)'}")
+        return 0
+
+    if sub == "serve":
+        host = "0.0.0.0" if getattr(args, "unsafe_public", False) \
+               else "127.0.0.1"
+        print(f"  serving Hermes-Desktop adapter on {host}:{args.port}")
+        if host == "127.0.0.1":
+            print("     (loopback only — use `ssh -L 8642:127.0.0.1:8642 ...` "
+                  "for desktop access)")
+        print(f"     token: {HD.token_path(home)}")
+        print("  press Ctrl-C to stop")
+        HD.serve_forever(
+            host=host, port=args.port, omega_home=home,
+            quiet=False,
+            unsafe_public=getattr(args, "unsafe_public", False),
+        )
+        return 0
+
+    print("usage: omega hermes-desktop {install|serve|profile|status}",
+          file=sys.stderr)
+    return 2
+
+
+def cmd_hermes(args: argparse.Namespace) -> int:
+    """`omega hermes {install,link,status,ask,env}` — Layer-2 Hermes bridge.
+
+    Hermes is the Nous Research autonomous agent runtime. We bridge it
+    so it uses the SAME Claude Max OAuth as ``claude`` CLI — no API key,
+    no separate auth, no extra credential to manage. Token rotates
+    server-side; bridge reads ``~/.claude/.credentials.json`` live on
+    every call so refreshes propagate naturally.
+    """
+    from omega_engine import hermes as H
+    import json as _json
+    sub = getattr(args, "hermes_cmd", None)
+
+    if sub == "status":
+        st = H.status()
+        if getattr(args, "json", False):
+            print(_json.dumps({
+                "installed": st.installed,
+                "hermes_bin": st.hermes_bin,
+                "hermes_version": st.hermes_version,
+                "hermes_home": st.hermes_home,
+                "omega_env_present": st.omega_env_present,
+                "oauth_token_present": st.oauth_token_present,
+                "oauth_subscription": st.oauth_subscription,
+                "oauth_expires_at_ms": st.oauth_expires_at_ms,
+                "oauth_expires_in_s": st.oauth_expires_in_s,
+            }, indent=2))
+            return 0
+        marks = {"ok": "✓", "no": "✗"}
+        print(f"  hermes installed:    {marks['ok'] if st.installed else marks['no']}  "
+              f"{st.hermes_bin or '(not on PATH)'}")
+        if st.hermes_version:
+            print(f"  hermes version:      {st.hermes_version}")
+        print(f"  hermes home:         {st.hermes_home}")
+        print(f"  omega.env linked:    {marks['ok'] if st.omega_env_present else marks['no']}")
+        print(f"  Claude OAuth token:  {marks['ok'] if st.oauth_token_present else marks['no']}"
+              f"  ({st.oauth_subscription or 'unknown sub'})")
+        if st.oauth_expires_in_s is not None:
+            hours = st.oauth_expires_in_s / 3600
+            print(f"  token expires in:    {hours:.1f} h")
+        if not st.installed:
+            print()
+            print("  next: omega hermes install")
+        elif not st.omega_env_present:
+            print()
+            print("  next: omega hermes link")
+        return 0 if st.installed and st.omega_env_present and st.oauth_token_present else 1
+
+    if sub == "install":
+        res = H.install(
+            skip_browser=not getattr(args, "with_browser", False),
+            skip_setup=True,
+            yes=getattr(args, "yes", False),
+            dry_run=getattr(args, "dry_run", False),
+            timeout_s=args.timeout,
+        )
+        if getattr(args, "json", False):
+            print(_json.dumps({
+                "ok": res.ok, "method": res.method,
+                "elapsed_s": res.elapsed_s, "detail": res.detail,
+                "error": res.error,
+            }, indent=2))
+            return 0 if res.ok else 1
+        mark = "✓" if res.ok else "✗"
+        print(f"  {mark} {res.method}  ({res.elapsed_s}s)")
+        if res.detail:
+            print(f"     {res.detail}")
+        if res.error:
+            print(f"     {res.error}")
+        return 0 if res.ok else 1
+
+    if sub == "link":
+        res = H.link(
+            provider=args.provider, model=args.model,
+            dry_run=getattr(args, "dry_run", False),
+        )
+        if getattr(args, "json", False):
+            print(_json.dumps({
+                "ok": res.ok, "config_path": res.config_path,
+                "provider": res.provider, "model": res.model,
+                "expires_at_ms": res.expires_at_ms,
+                "subscription": res.subscription,
+                "error": res.error,
+            }, indent=2))
+            return 0 if res.ok else 1
+        mark = "✓" if res.ok else "✗"
+        print(f"  {mark} linked  provider={res.provider}  model={res.model}")
+        if res.config_path:
+            print(f"     wrote {res.config_path}")
+        if res.subscription:
+            print(f"     Claude subscription: {res.subscription}")
+        if res.error:
+            print(f"     {res.error}")
+        return 0 if res.ok else 1
+
+    if sub == "ask":
+        try:
+            rc, stdout, stderr = H.ask(args.prompt, timeout_s=args.timeout)
+        except H.HermesError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        if stdout:
+            print(stdout, end="" if stdout.endswith("\n") else "\n")
+        if rc != 0 and stderr:
+            print(stderr, file=sys.stderr)
+        return rc
+
+    if sub == "env":
+        # Print the env we'd hand to hermes — useful for `eval $(...)`
+        try:
+            env = H.build_env()
+        except H.HermesError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        for k in ("CLAUDE_CODE_OAUTH_TOKEN", "HERMES_PROVIDER", "HERMES_MODEL"):
+            if k in env:
+                if k == "CLAUDE_CODE_OAUTH_TOKEN":
+                    print(f"export {k}=<live-from-{H._CLAUDE_CREDS}>")
+                else:
+                    print(f"export {k}={env[k]!r}")
+        return 0
+
+    if sub == "brief":
+        # Teach Hermès what OmegaOS is + observe outcomes for the
+        # self-improvement loop. Writes a SKILL.md inside ~/.hermes/.
+        from omega_engine import hermes_bootstrap as HB
+        op = getattr(args, "brief_op", "status")
+        if op == "write":
+            res = HB.write_brief()
+            print(f"  ✓ wrote OmegaOS brief to {res.path}")
+            print(f"     {res.bytes_written} bytes — Hermès reads it "
+                  f"on next invocation")
+            print(f"     omega_home: {res.omega_home}")
+            return 0
+        if op == "status":
+            st = HB.status()
+            mark = lambda b: "✓" if b else "✗"
+            print(f"  {mark(st['brief_present'])}  brief at {st['brief_path']}"
+                  f"  ({st['brief_size']} bytes)")
+            print(f"  {mark(st['memory_log_present'])}  memory log "
+                  f"({st['observation_count']} observations)")
+            if st["last_observed_at"]:
+                import time as _t
+                age = _t.time() - st["last_observed_at"]
+                print(f"     last observation: {age/60:.1f} min ago")
+            return 0 if st["brief_present"] else 1
+        if op == "observe":
+            res = HB.observe_outcome(args.slug, args.task_id)
+            if res is None:
+                print(f"  no .done.json yet for task {args.task_id}",
+                      file=sys.stderr)
+                return 1
+            print(f"  ✓ recorded {res.task_id} → {res.status}")
+            return 0
+        print(f"unknown brief op: {op}", file=sys.stderr)
+        return 2
+
+    print("usage: omega hermes {status|install|link|ask|env|brief} ...",
+          file=sys.stderr)
+    return 2
+
+
+def cmd_ua(args: argparse.Namespace) -> int:
+    """`omega ua {install,run,consume}` — Understand-Anything bridge.
+
+    Claude Code plugin that builds an interactive knowledge graph of a
+    codebase. We bridge install (uses Claude Max OAuth) + the
+    ``/understand`` run + a consumer that lands the resulting graph
+    into OmegaOS's GraphRetriever.
+    """
+    from omega_engine import understand_anything as UA
+    import json as _json
+    sub = getattr(args, "ua_cmd", None)
+
+    if sub == "install":
+        res = UA.install_plugin(
+            timeout_s=args.timeout,
+            dry_run=getattr(args, "dry_run", False),
+        )
+        if getattr(args, "json", False):
+            print(_json.dumps({
+                "ok": res.ok, "method": res.method,
+                "detail": res.detail, "error": res.error,
+            }, indent=2))
+            return 0 if res.ok else 1
+        mark = "✓" if res.ok else "✗"
+        print(f"  {mark} {res.detail or res.error}")
+        return 0 if res.ok else 1
+
+    if sub == "run":
+        res = UA.run(args.project, timeout_s=args.timeout,
+                     language=getattr(args, "language", None))
+        if getattr(args, "json", False):
+            print(_json.dumps({
+                "ok": res.ok, "output_path": res.output_path,
+                "nodes": res.nodes, "edges": res.edges,
+                "elapsed_s": res.elapsed_s, "error": res.error,
+            }, indent=2))
+            return 0 if res.ok else 1
+        mark = "✓" if res.ok else "✗"
+        print(f"  {mark} /understand on {args.project}  ({res.elapsed_s}s)")
+        if res.ok:
+            print(f"     graph: {res.output_path}")
+            print(f"     {res.nodes} nodes, {res.edges} edges")
+            print(f"     next: omega ua consume {args.project}")
+        else:
+            print(f"     {res.error}")
+        return 0 if res.ok else 1
+
+    if sub == "consume":
+        try:
+            info = UA.consume_graph(args.project)
+        except UA.UnderstandAnythingError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(f"  ✓ consumed {info['nodes']} nodes, {info['edges']} edges")
+        print(f"     written to {info['written_to']}")
+        return 0
+
+    print("usage: omega ua {install|run|consume} ...", file=sys.stderr)
+    return 2
+
+
+def cmd_genesis(args: argparse.Namespace) -> int:
+    """`omega genesis {new,run,status,resume,stack,reset}` — project genesis pipeline.
+
+    Programmatic 7-phase walker: stack → vision → market (5 files) →
+    branding (3) → PRD (9) → features (N with depends_on) → handoff to plan.
+    Strict isolation per project; resume-safe; no cross-project leakage.
+    """
+    import json as _json
+    from omega_engine.genesis import (
+        GenesisOrchestrator, PHASES, init_project, load_state, pick_stack,
+        stack_questions, project_root,
+    )
+    from omega_engine.genesis.state import StackConfig, delete_project
+
+    sub = getattr(args, "genesis_cmd", None)
+    home = _omega_home()
+
+    if sub == "new":
+        # Build a StackConfig from --stack-* flags if any, else use defaults.
+        answers: dict[str, str] = {}
+        for k in ("type", "frontend", "backend", "deploy", "payments",
+                  "ui_kit", "auth"):
+            v = getattr(args, f"stack_{k}", None)
+            if v:
+                answers[k] = v
+        cfg = pick_stack(
+            answers=answers, intent=args.intent or "",
+            accept_defaults=getattr(args, "accept_defaults", False)
+                            and not answers,
+        )
+        try:
+            state = init_project(
+                args.slug,
+                name=args.name or args.slug,
+                intent=args.intent or "",
+                stack=cfg,
+                force=getattr(args, "force", False),
+            )
+        except (FileExistsError, ValueError) as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        if getattr(args, "json", False):
+            print(_json.dumps({
+                "slug": state.slug, "name": state.name,
+                "root": str(project_root(state.slug)),
+                "phase": state.phase,
+                "stack": state.stack.to_dict(),
+            }, indent=2))
+        else:
+            print(f"  ✓ project '{state.slug}' initialised")
+            print(f"     root:  {project_root(state.slug)}")
+            print(f"     stack: {state.stack.type} · "
+                  f"{state.stack.frontend} · {state.stack.backend} · "
+                  f"{state.stack.deploy} · {state.stack.ui_kit}")
+            print(f"     next:  omega genesis run {state.slug}")
+        return 0
+
+    if sub == "questions":
+        # Print the picker's question list (for the Telegram bot / Claude
+        # Code skill to render an interactive form).
+        qs = stack_questions(intent=args.intent or "")
+        if getattr(args, "json", False):
+            print(_json.dumps([{
+                "key": q.key, "header": q.header,
+                "question": q.question, "options": q.options,
+                "recommended": q.recommended, "why": q.why,
+            } for q in qs], indent=2))
+        else:
+            for q in qs:
+                print(f"  [{q.header}] {q.question}")
+                print(f"     options: {', '.join(q.options)}")
+                print(f"     recommended: {q.recommended}  — {q.why}")
+                print()
+        return 0
+
+    if sub == "status":
+        orch = GenesisOrchestrator(args.slug)
+        st = orch.status()
+        if getattr(args, "json", False):
+            print(_json.dumps(st, indent=2))
+            return 0
+        if not st["exists"]:
+            print(f"  no genesis state for {args.slug!r} — "
+                  f"run `omega genesis new {args.slug}`")
+            return 1
+        print(f"  {st['slug']}  ·  {st['name']}")
+        print(f"  phase: {st['phase']}    "
+              f"({len(st['completed_phases'])}/{len(PHASES)} complete)")
+        print(f"  done : {', '.join(st['completed_phases']) or '—'}")
+        print(f"  next : {', '.join(st['remaining_phases']) or '(complete)'}")
+        print(f"  stack: {st['stack']['type']} · "
+              f"{st['stack']['frontend']} · {st['stack']['backend']}")
+        print(f"  root : {st['root']}")
+        return 0
+
+    if sub == "run":
+        orch = GenesisOrchestrator(args.slug)
+        # `run` by default advances to completion. `--phase X` runs only
+        # phase X. `--max N` caps iterations.
+        if getattr(args, "phase", None):
+            res = orch.run(only=args.phase)
+            mark = "✓" if res.ok else "✗"
+            print(f"  {mark} {res.phase:10s}  "
+                  f"{len(res.files_written)} files  {res.elapsed_s}s  "
+                  f"{res.error or ''}")
+            return 0 if res.ok else 1
+        results = orch.run_all(max_phases=args.max)
+        if not results:
+            print("  (pipeline already complete)")
+            return 0
+        for r in results:
+            mark = "✓" if r.ok else "✗"
+            print(f"  {mark} {r.phase:10s}  "
+                  f"{len(r.files_written)} files  {r.elapsed_s}s  "
+                  f"{r.error or ''}")
+        return 0 if all(r.ok for r in results) else 1
+
+    if sub == "delete":
+        if not getattr(args, "yes", False):
+            print(f"error: pass --yes to confirm deletion of {args.slug!r}",
+                  file=sys.stderr)
+            return 2
+        ok = delete_project(args.slug)
+        print(f"  {'✓ deleted' if ok else '(nothing to delete)'} "
+              f"{args.slug}")
+        return 0
+
+    print("usage: omega genesis {new|run|status|questions|delete} ...",
+          file=sys.stderr)
+    return 2
+
+
+def cmd_plan(args: argparse.Namespace) -> int:
+    """`omega plan {build,next,status,advance,run,retry,list}` — FSM-enforced
+    sequential plan executor. Replaces v6 ``/planner`` which skipped tasks.
+
+    Every state transition goes through the reducer, which refuses to mark
+    a task in-progress / verified if any of its ``depends_on`` aren't yet
+    VERIFIED. The agent CAN'T jump from T-005 to T-090 because the
+    engine returns IllegalTransition.
+    """
+    import json as _json
+    from omega_engine import plan as P
+
+    sub = getattr(args, "plan_cmd", None)
+
+    if sub == "build":
+        try:
+            res = P.build_plan(args.slug,
+                               reset_failed=getattr(args, "reset_failed", False))
+        except P.PlanError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(f"  ✓ plan built  inserted={res['inserted']}  "
+              f"updated={res['updated']}  total={res['total']}")
+        return 0
+
+    if sub == "next":
+        t = P.next_eligible(args.slug)
+        if t is None:
+            print(f"  (no eligible task — plan may be complete or blocked)")
+            return 0
+        if getattr(args, "json", False):
+            print(_json.dumps(t.to_dict(), indent=2))
+            return 0
+        print(f"  {t.id}  ·  {t.title}")
+        print(f"     wave: {t.wave}  ·  estimated: {t.estimated_minutes}min")
+        print(f"     deps: {', '.join(t.depends_on) or '(none — root task)'}")
+        print(f"     files: {', '.join(t.files_owned[:3])}"
+              + (f" + {len(t.files_owned)-3} more"
+                 if len(t.files_owned) > 3 else ""))
+        print(f"     verify: {t.verify_cmd}")
+        print(f"     skill: {t.skill}")
+        return 0
+
+    if sub == "status":
+        st = P.status(args.slug)
+        if getattr(args, "json", False):
+            print(_json.dumps(st, indent=2))
+            return 0
+        c = st["counts"]
+        print(f"  {st['slug']}  ·  {st['completion_pct']}%  complete")
+        print(f"  total: {st['total']}  ·  verified: {c['verified']}  ·  "
+              f"in_progress: {c['in_progress']}  ·  pending: {c['pending']}  ·  "
+              f"failed: {c['failed']}")
+        if st["active"]:
+            print(f"  active: {st['active']['id']}  ·  {st['active']['title']}")
+        return 0
+
+    if sub == "list":
+        tasks = P.list_tasks(args.slug, state=getattr(args, "state", None))
+        if getattr(args, "json", False):
+            print(_json.dumps([t.to_dict() for t in tasks], indent=2))
+            return 0
+        for t in tasks:
+            mark = {"verified": "✓", "failed": "✗",
+                    "in_progress": "▶", "claimed_done": "?",
+                    "pending": "·"}.get(t.state, "?")
+            print(f"  {mark} {t.id}  [{t.state:13s}] "
+                  f"w={t.wave}  deps={t.depends_on or '[]'}  {t.title[:50]}")
+        return 0
+
+    if sub in ("start", "in-progress", "in_progress"):
+        try:
+            t = P.mark_in_progress(args.slug, args.task_id)
+        except P.PlanError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(f"  ▶ {t.id} → {t.state}")
+        return 0
+
+    if sub == "claimed":
+        try:
+            t = P.mark_claimed_done(args.slug, args.task_id)
+        except P.PlanError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(f"  ? {t.id} → {t.state}  (verify pending)")
+        return 0
+
+    if sub == "done":
+        try:
+            t = P.mark_done(args.slug, args.task_id,
+                            verify=not getattr(args, "no_verify", False))
+        except P.PlanError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        mark = "✓" if t.state == P.VERIFIED else "✗"
+        print(f"  {mark} {t.id} → {t.state}"
+              + (f"  ({t.last_error[:200]})" if t.last_error else ""))
+        return 0 if t.state == P.VERIFIED else 1
+
+    if sub == "fail":
+        try:
+            t = P.mark_failed(args.slug, args.task_id, reason=args.reason or "")
+        except P.PlanError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(f"  ✗ {t.id} → {t.state}  ({t.last_error})")
+        return 0
+
+    if sub == "retry":
+        try:
+            t = P.retry(args.slug, args.task_id)
+        except P.PlanError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(f"  ↻ {t.id} → {t.state}")
+        return 0
+
+    if sub == "run":
+        # Multi-day autonomous loop. The engine walks next_eligible →
+        # in_progress → dispatch → claimed_done → verify → verified.
+        # Reducer enforces ordering; failed tasks naturally cascade-block
+        # their dependants (the right behaviour — operator decides via
+        # retry / fail).
+        spawn = None
+        if args.spawn_cmd:
+            import shlex
+            spawn = shlex.split(args.spawn_cmd)
+        def _print_progress(task, result):
+            if args.json:
+                import json as _j
+                print(_j.dumps({"task_id": task.id, "result": result}))
+            else:
+                mark = {"verified": "✓"}.get(result.split(":")[0], "✗")
+                print(f"  {mark} {task.id}  {result}")
+        try:
+            result = P.run(
+                args.slug,
+                max_iterations=args.max,
+                spawn_cmd=spawn,
+                on_iteration=_print_progress,
+                sleep_between_s=args.sleep,
+            )
+        except P.PlanError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        if args.json:
+            print(_json.dumps(result.to_dict(), indent=2))
+        else:
+            print()
+            print(f"  loop done — {result.iterations} iterations in "
+                  f"{result.elapsed_s}s")
+            print(f"  verified: {len(result.verified)}  "
+                  f"failed: {len(result.failed)}")
+            fs = result.final_status["counts"]
+            print(f"  status: verified={fs['verified']}  "
+                  f"pending={fs['pending']}  failed={fs['failed']}  "
+                  f"({result.final_status['completion_pct']}% complete)")
+        return 0 if not result.failed else 1
+
+    print("usage: omega plan {build|next|status|list|start|claimed|"
+          "done|fail|retry|run} ...", file=sys.stderr)
+    return 2
+
+
+def cmd_ma(args: argparse.Namespace) -> int:
+    """`omega ma {agent,env,session,run}` — Anthropic Managed Agents lifecycle.
+
+    OPT-IN provider. Requires ANTHROPIC_API_KEY. NOT a substitute for
+    ClaudeMax (Max OAuth, no API key); rather a complement for
+    server-side / long-running / async workloads.
+    """
+    import json as _json
+    sub = getattr(args, "ma_cmd", None)
+
+    # Guard: every subcommand needs an API key.
+    api_key = os.environ.get("ANTHROPIC_API_KEY", "")
+    if not api_key and sub != "info":
+        print("error: ANTHROPIC_API_KEY not set — Managed Agents requires an API key",
+              file=sys.stderr)
+        print("       see: https://platform.claude.com/docs/en/managed-agents/overview",
+              file=sys.stderr)
+        return 2
+
+    if sub == "info":
+        print("Managed Agents (Anthropic beta) integration")
+        print("  api key present:", "yes" if api_key else "no  (export ANTHROPIC_API_KEY)")
+        print("  beta header:    ", "managed-agents-2026-04-01")
+        print("  docs:           ",
+              "https://platform.claude.com/docs/en/managed-agents/overview")
+        from omega_engine.managed_agent import ManagedAgentCache
+        cache = ManagedAgentCache(_omega_home())
+        d = cache._load()
+        print(f"  cached agents:  {len(d['agents'])}  {list(d['agents'].keys())}")
+        print(f"  cached envs:    {len(d['environments'])}  {list(d['environments'].keys())}")
+        return 0
+
+    from omega_engine.managed_agent import ManagedAgentClient, ManagedAgentCache
+    client = ManagedAgentClient(api_key=api_key)
+    cache = ManagedAgentCache(_omega_home())
+
+    # ----- agent subcommands -----
+    if sub == "agent":
+        op = getattr(args, "agent_op", "list")
+        if op == "create":
+            agent = client.create_agent(
+                name=args.name, model=args.model,
+                system=args.system or "",
+            )
+            cache.set_agent(args.name, agent["id"])
+            print(_json.dumps({
+                "id": agent["id"], "name": agent.get("name", args.name),
+                "model": agent.get("model"),
+                "version": agent.get("version"),
+                "cached_as": args.name,
+            }, indent=2))
+            return 0
+        if op == "get":
+            print(_json.dumps(client.get_agent(args.id), indent=2))
+            return 0
+        if op == "list":
+            data = client.list_agents(limit=args.limit)
+            if args.json:
+                print(_json.dumps(data, indent=2))
+                return 0
+            rows = data.get("data", []) if isinstance(data, dict) else []
+            print(f"## {len(rows)} agents")
+            for a in rows:
+                print(f"  {a.get('id'):42s}  {a.get('name')}  ({a.get('model')})")
+            return 0
+        if op == "delete":
+            client.delete_agent(args.id)
+            print(f"deleted {args.id}")
+            return 0
+        print(f"unknown agent op: {op}", file=sys.stderr)
+        return 2
+
+    # ----- environment subcommands -----
+    if sub == "env":
+        op = getattr(args, "env_op", "list")
+        if op == "create":
+            env = client.create_environment(name=args.name)
+            cache.set_environment(args.name, env["id"])
+            print(_json.dumps({
+                "id": env["id"], "name": env.get("name", args.name),
+                "cached_as": args.name,
+            }, indent=2))
+            return 0
+        if op == "get":
+            print(_json.dumps(client.get_environment(args.id), indent=2))
+            return 0
+        if op == "list":
+            data = client.list_environments(limit=args.limit)
+            if args.json:
+                print(_json.dumps(data, indent=2))
+                return 0
+            rows = data.get("data", []) if isinstance(data, dict) else []
+            print(f"## {len(rows)} environments")
+            for e in rows:
+                print(f"  {e.get('id'):42s}  {e.get('name')}")
+            return 0
+        if op == "delete":
+            client.delete_environment(args.id)
+            print(f"deleted {args.id}")
+            return 0
+        print(f"unknown env op: {op}", file=sys.stderr)
+        return 2
+
+    # ----- session subcommands -----
+    if sub == "session":
+        op = getattr(args, "session_op", "list")
+        if op == "create":
+            agent_id = cache.get_agent(args.agent) or args.agent
+            env_id = cache.get_environment(args.env) or args.env
+            s = client.create_session(
+                agent_id=agent_id, environment_id=env_id,
+                title=args.title or "",
+            )
+            print(_json.dumps({
+                "id": s["id"], "agent_id": agent_id,
+                "environment_id": env_id, "title": args.title,
+            }, indent=2))
+            return 0
+        if op == "send":
+            client.send_user_message(args.id, args.text)
+            print("sent")
+            return 0
+        if op == "stream":
+            for ev in client.stream_events(args.id, timeout_s=args.timeout):
+                t = ev.get("type", "?")
+                if t == "agent.message":
+                    for b in ev.get("content", []):
+                        if b.get("type") == "text":
+                            print(b.get("text", ""), end="", flush=True)
+                elif t == "agent.tool_use":
+                    print(f"\n[tool: {ev.get('name')}]", flush=True)
+                elif t == "session.status_idle":
+                    print("\n[idle]")
+                    return 0
+            return 0
+        if op == "list":
+            data = client.list_sessions(limit=args.limit)
+            if args.json:
+                print(_json.dumps(data, indent=2))
+                return 0
+            rows = data.get("data", []) if isinstance(data, dict) else []
+            print(f"## {len(rows)} sessions")
+            for s in rows:
+                print(f"  {s.get('id'):42s}  {s.get('title','')}")
+            return 0
+        if op == "get":
+            print(_json.dumps(client.get_session(args.id), indent=2))
+            return 0
+        if op == "delete":
+            client.delete_session(args.id)
+            print(f"deleted {args.id}")
+            return 0
+        print(f"unknown session op: {op}", file=sys.stderr)
+        return 2
+
+    # ----- run (the convenience path) -----
+    if sub == "run":
+        # Fast path: create-or-reuse agent + env, create session,
+        # send prompt, stream until idle, print aggregated text.
+        from omega_engine.managed_agent import ManagedAgentProvider
+        provider = ManagedAgentProvider(
+            api_key=api_key,
+            agent_name=args.agent_name,
+            env_name=args.env_name,
+            model=args.model,
+            system=args.system or "You are an Omega OS managed agent.",
+            omega_home=_omega_home(),
+            timeout_s=args.timeout,
+        )
+        # Build a minimal AgentRequest manually (no full envelope needed).
+        from omega_engine.provider import AgentRequest
+        req = AgentRequest(
+            role=args.role, prompt=args.intent,
+            system="", context={"mission_id": ""},
+        )
+        result = provider.run(req)
+        if args.json:
+            print(_json.dumps({
+                "text": result.text,
+                "artifacts": result.artifacts,
+            }, indent=2))
+        else:
+            print(result.text)
+            ma = result.artifacts.get("managed_agent", {})
+            print()
+            print(f"  session: {ma.get('session_id','?')}")
+            tools = ma.get("tool_uses") or []
+            if tools:
+                print(f"  tools used: {', '.join(tools)}")
+        return 0
+
+    print("usage: omega ma {info|agent|env|session|run} ...", file=sys.stderr)
+    return 2
+
+
+def cmd_handoff(args: argparse.Namespace) -> int:
+    """`omega handoff {write,read,list,template,from-done}` — session-end memo.
+
+    Five-section markdown that the next agent reads when picking up:
+      1. Mission       — one sentence
+      2. State         — works vs broken (concrete, runtime-observed)
+      3. Files touched — exact paths
+      4. Dead ends     — what NOT to retry
+      5. Next          — first concrete action
+    """
+    import json as _json
+    from omega_engine import handoff as H
+
+    sub = getattr(args, "handoff_cmd", None)
+    home = _omega_home()
+
+    if sub == "template":
+        print(H.TEMPLATE)
+        return 0
+
+    if sub == "read":
+        ho = H.read_handoff(
+            home,
+            project=getattr(args, "project", None),
+            task_id=getattr(args, "task_id", None),
+        )
+        if ho is None:
+            target = args.project or args.task_id or "?"
+            print(f"no handoff found for {target}", file=sys.stderr)
+            return 1
+        if getattr(args, "json", False):
+            print(ho.to_json())
+        else:
+            print(ho.to_markdown())
+        return 0
+
+    if sub == "list":
+        rows = H.list_handoffs(home, args.project)
+        if not rows:
+            print(f"no archived handoffs for project '{args.project}'")
+            return 0
+        if getattr(args, "json", False):
+            print(_json.dumps(rows, indent=2))
+            return 0
+        print(f"## handoff history for '{args.project}'  ({len(rows)} entries)")
+        for r in rows:
+            print(f"  {r['created_at']}  —  {r['mission']}")
+            if r["next_first"]:
+                print(f"      next: {r['next_first']}")
+        return 0
+
+    if sub == "from-done":
+        draft = H.from_done_signal(home, args.task_id, cwd=args.cwd or os.getcwd())
+        if args.project:
+            draft.project = args.project
+        # Write under task target by default; both if --project also given.
+        target = "both" if args.project else "task"
+        result = H.write_handoff(home, draft, target=target)
+        print(f"wrote handoff:")
+        for p in result["written"]:
+            print(f"  {p}")
+        if args.print:
+            print()
+            print(draft.to_markdown())
+        return 0
+
+    if sub == "write":
+        # Two paths: --file <path> reads markdown to import,
+        # else interactive prompt mode for the 5 fields.
+        if args.file:
+            text = Path(args.file).read_text()
+            ho = H.Handoff.from_markdown(text)
+            ho.project = args.project or ho.project
+            ho.task_id = args.task_id or ho.task_id
+            ho.mission_id = args.mission_id or ho.mission_id
+            ho.author = args.author or ho.author or "human"
+        else:
+            print("interactive handoff (Ctrl-D when done with multi-line fields):")
+            mission = input("Mission (one sentence): ").strip()
+            print("State (multi-line, end with empty line):")
+            state_lines: list[str] = []
+            try:
+                while True:
+                    line = input()
+                    if line == "":
+                        break
+                    state_lines.append(line)
+            except EOFError:
+                pass
+            state = "\n".join(state_lines)
+            print("Files touched (one per line, empty to end):")
+            files: list[str] = []
+            try:
+                while True:
+                    line = input().strip()
+                    if not line:
+                        break
+                    files.append(line)
+            except EOFError:
+                pass
+            print("Dead ends (one per line, empty to end):")
+            dead: list[str] = []
+            try:
+                while True:
+                    line = input().strip()
+                    if not line:
+                        break
+                    dead.append(line)
+            except EOFError:
+                pass
+            print("Next steps (one per line, empty to end):")
+            nxt: list[str] = []
+            try:
+                while True:
+                    line = input().strip()
+                    if not line:
+                        break
+                    nxt.append(line)
+            except EOFError:
+                pass
+            ho = H.Handoff(
+                mission=mission, state=state, files_touched=files,
+                dead_ends=dead, next_steps=nxt,
+                author=args.author or "human",
+                project=args.project or "",
+                task_id=args.task_id or "",
+                mission_id=args.mission_id or "",
+            )
+        target = "project" if args.project else ("task" if args.task_id else None)
+        if target is None:
+            print("error: --project or --task-id required to know where to write",
+                  file=sys.stderr)
+            return 2
+        result = H.write_handoff(home, ho, target=target)
+        for p in result["written"]:
+            print(f"wrote {p}")
+        return 0
+
+    print("usage: omega handoff {write|read|list|template|from-done} ...",
+          file=sys.stderr)
+    return 2
+
+
+def cmd_worker(args: argparse.Namespace) -> int:
+    """`omega worker {spawn,run,status,wait,list}` — persistent-tmux workers.
+
+    Each worker runs as its own `claude -p` invocation inside a detached tmux
+    session. Survives parent crashes. Smart model defaults per role.
+    """
+    import json
+    from omega_engine import worker as W
+
+    sub = getattr(args, "worker_cmd", None) or "list"
+    home = _omega_home()
+
+    if sub == "spawn":
+        intent = args.intent
+        role = args.role
+        # Resolve skills: --skills wins, else role default.
+        skills_list: list[str] = []
+        if getattr(args, "skills", None):
+            skills_list = [s.strip() for s in args.skills.split(",") if s.strip()]
+        brief = W.WorkerBrief(
+            task_id=args.task_id or f"t-{int(time.time())}-{os.urandom(2).hex()}",
+            role=role,
+            intent=intent,
+            user_prompt=args.user_prompt or intent,
+            system_prompt=args.system_prompt or "",
+            model=args.model or "",
+            verify_cmd=args.verify_cmd,
+            project=args.project,
+            cwd=args.cwd or os.getcwd(),
+            mission_id=args.mission_id or "",
+            skills=skills_list,
+        )
+        name = W.spawn_worker(brief, home=home, worker_id=args.worker_id)
+        print(json.dumps({
+            "task_id": brief.task_id, "session": name,
+            "model": brief.resolved_model(), "role": brief.role,
+            "skills": brief.resolved_skills(),
+        }, indent=2))
+        return 0
+
+    if sub == "run":
+        return W.run_brief(home, args.task_id)
+
+    if sub == "status":
+        s = W.worker_status(home, args.task_id)
+        print(json.dumps(s, indent=2))
+        return 0 if s.get("state") in ("done_clean", "pending", "running") else 1
+
+    if sub == "wait":
+        s = W.wait_for_done(
+            home, args.task_id,
+            timeout_s=args.timeout, poll_s=args.poll,
+        )
+        print(json.dumps(s, indent=2))
+        return 0 if s.get("state") == "done_clean" else 1
+
+    if sub == "list":
+        rows = W.list_workers(home)
+        if args.json:
+            print(json.dumps(rows, indent=2))
+            return 0
+        if not rows:
+            print("no workers (Agentik_Runtime/sessions empty)")
+            return 0
+        print(f"{'task_id':24s}  {'role':10s}  {'model':28s}  {'state':12s}  intent")
+        for r in rows:
+            print(
+                f"{r['task_id']:24s}  {r['role']:10s}  "
+                f"{r['model']:28s}  {r['state']:12s}  {r['intent']}"
+            )
+        return 0
+
+    print(f"unknown worker subcommand: {sub}", file=sys.stderr)
+    return 2
+
+
+def cmd_cleanup(args: argparse.Namespace) -> int:
+    """`omega cleanup` — OmegaOS-adapted disk cleanup pipeline."""
+    from omega_engine import cleanup as C
+
+    home = _omega_home()
+    reports = C.cleanup(
+        home,
+        dry_run=not args.yes,
+        deep=args.deep,
+        target_pct=args.target,
+        idle_days=args.idle_days,
+        runtime_days=args.runtime_days,
+        tmux_hours=args.tmux_hours,
+    )
+    if args.json:
+        import json
+        print(json.dumps([{
+            "tier": r.tier, "items": r.items_removed,
+            "bytes_freed": r.bytes_freed, "dry_run": r.dry_run,
+            "detail": r.detail,
+        } for r in reports], indent=2))
+    else:
+        print(C.format_summary(reports, Path(home)))
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="omega", description="Omega OS control CLI")
+    # When no subcommand is given, drop into the interactive menu instead of
+    # erroring. The cmd_menu function reads the whiptail menus and dispatches.
+    parser.set_defaults(fn=cmd_menu)
+    sub = parser.add_subparsers(dest="cmd")
+    sub.add_parser("version", help="print the engine version").set_defaults(fn=cmd_version)
+    p_doc = sub.add_parser("doctor", help="validate the deployment")
+    p_doc.add_argument("--json", action="store_true",
+                       help="emit a single JSON object instead of pretty text")
+    p_doc.set_defaults(fn=cmd_doctor)
+    sub.add_parser("status", help="show all tasks and their derived state").set_defaults(fn=cmd_status)
+
+    p_acc = sub.add_parser("account", help="manage the Claude Max account pool")
+    p_acc.set_defaults(fn=cmd_account)
+    acc_sub = p_acc.add_subparsers(dest="account_cmd")
+    acc_sub.add_parser("list", help="show the pool (default)")
+    p_login = acc_sub.add_parser("login", help="add an account via OAuth (or manual paste)")
+    p_login.add_argument("--id", help="account id (e.g. max-primary)", default=None)
+    p_login.add_argument("--label", help="human label", default=None)
+    p_login.add_argument("--manual", action="store_true",
+                         help="skip the device-code attempt; paste a token directly")
+    p_use = acc_sub.add_parser("use", help="set an account's status")
+    p_use.add_argument("id", help="account id")
+    p_use.add_argument("status", choices=["active", "resting", "disabled"])
+    p_pool = acc_sub.add_parser("pool", help="edit weights and selection strategy")
+    p_pool.add_argument("--selection", choices=["round-robin", "least-used", "by-quota"],
+                        help="set the pool-wide selection strategy")
+    p_pool.add_argument("--weight", action="append", default=[],
+                        metavar="ID=N",
+                        help="set an account weight; repeatable")
+
+    sub.add_parser("billing", help="show usage/cost per Claude Max account").set_defaults(fn=cmd_billing)
+    p_run = sub.add_parser("run", help="run a mission end-to-end")
+    p_run.add_argument("intent", help="the mission, in natural language")
+    p_run.set_defaults(fn=cmd_run)
+    p_proj = sub.add_parser("project", help="create a project or manage its secrets")
+    p_proj.set_defaults(fn=cmd_project)
+    proj_sub = p_proj.add_subparsers(dest="project_cmd")
+    # `omega project <name>` keeps working — the positional is bound at the
+    # top level. The `secret` subcommand opens the per-project vault CLI.
+    p_proj.add_argument("name", nargs="?", help="the project name (create mode)")
+    p_proj.add_argument("--no-telegram", action="store_true",
+                        help="skip Telegram topic creation")
+    p_sec = proj_sub.add_parser("secret",
+                                help="per-project secret vault (set|get|list)")
+    p_sec.add_argument("op", choices=["set", "get", "list"])
+    p_sec.add_argument("slug", help="project slug (the dir under Agentik_Coding/projects/)")
+    p_sec.add_argument("--ref", help="secret reference name (for set / get)")
+    p_sec.add_argument("--value", help="secret value (set; omit to prompt)")
+
+    # `omega classify` — task complexity classifier
+    p_cls = sub.add_parser("classify", help="show how the router would classify a task")
+    p_cls.add_argument("task", help="task description")
+    p_cls.add_argument("--role", default="worker")
+    p_cls.set_defaults(fn=cmd_classify)
+
+    # `omega memory` — semantic memory across all sources
+    p_mem = sub.add_parser("memory", help="semantic memory across all conversations + missions")
+    p_mem.set_defaults(fn=cmd_memory)
+    mem_sub = p_mem.add_subparsers(dest="memory_cmd")
+    mem_sub.add_parser("stats", help="show index stats")
+    mem_sub.add_parser("reindex", help="rebuild the semantic index")
+    p_msearch = mem_sub.add_parser("search", help="ranked search across sources")
+    p_msearch.add_argument("query")
+    p_msearch.add_argument("-k", type=int, default=10)
+
+    # `omega learn` — Smith reflection
+    p_lrn = sub.add_parser("learn", help="Smith reflection on audits + worker outcomes")
+    p_lrn.set_defaults(fn=cmd_learn)
+    lrn_sub = p_lrn.add_subparsers(dest="learn_cmd")
+    p_lref = lrn_sub.add_parser("reflect", help="run reflection + write proposals")
+    p_lref.add_argument("--write", action="store_true",
+                         help="write proposals to staging (default: print only)")
+    lrn_sub.add_parser("report", help="JSON dump of the latest reflection")
+
+    # `omega message` — worker ↔ oracle messaging
+    p_msg = sub.add_parser("message", help="worker ↔ oracle messaging primitive")
+    p_msg.set_defaults(fn=cmd_message)
+    msg_sub = p_msg.add_subparsers(dest="message_cmd")
+    p_msend = msg_sub.add_parser("send", help="send a message on a task")
+    p_msend.add_argument("task_id")
+    p_msend.add_argument("--from", dest="from_", required=True)
+    p_msend.add_argument("--to", required=True)
+    p_msend.add_argument("--type",
+                          choices=["question", "answer", "proposal", "decision"],
+                          required=True)
+    p_msend.add_argument("--text", required=True)
+    p_mread = msg_sub.add_parser("read", help="read messages on a task")
+    p_mread.add_argument("task_id")
+    p_mread.add_argument("--to", default=None,
+                          help="filter to messages addressed to this recipient")
+    p_mwait = msg_sub.add_parser("wait", help="block until a message addressed to <to> arrives")
+    p_mwait.add_argument("task_id")
+    p_mwait.add_argument("--to", required=True)
+    p_mwait.add_argument("--timeout", type=int, default=600)
+    msg_sub.add_parser("open", help="list every unanswered question across all tasks")
+
+    # `omega tmux` — categorised tmux orchestration
+    p_tx = sub.add_parser("tmux", help="tmux orchestration — list/attach/kill/spawn/menu")
+    p_tx.set_defaults(fn=cmd_tmux)
+    tx_sub = p_tx.add_subparsers(dest="tmux_cmd")
+    tx_sub.add_parser("list", help="all sessions, grouped by category")
+    tx_sub.add_parser("count", help="just the session count (for status line)")
+    p_tatt = tx_sub.add_parser("attach", help="print attach command for a session")
+    p_tatt.add_argument("name")
+    p_tkil = tx_sub.add_parser("kill", help="kill a session")
+    p_tkil.add_argument("name")
+    p_tspw = tx_sub.add_parser("spawn", help="spawn a new categorised session")
+    p_tspw.add_argument("kind",
+                        choices=["session", "oracle", "worker", "aisb-chat"])
+    p_tspw.add_argument("name")
+    p_tspw.add_argument("--task", default=None,
+                        help="task name (worker only)")
+    p_tspw.add_argument("--cwd", default=None,
+                        help="working directory for the new session")
+    tx_sub.add_parser("health", help="population summary + stale workers")
+    p_tcl = tx_sub.add_parser("cleanup", help="kill stale detached worker sessions")
+    p_tcl.add_argument("--hours", type=int, default=24,
+                       help="age threshold in hours (default 24)")
+    p_tcl.add_argument("--yes", action="store_true",
+                       help="apply (default is dry-run)")
+    tx_sub.add_parser("menu", help="interactive whiptail picker (use under tmux for prefix+Z)")
+    p_tcfg = tx_sub.add_parser("config",
+        help="write the recommended tmux.conf to Agentik_Tools/")
+    p_tcfg.add_argument("--profile", choices=["minimal", "pro"],
+                        default="minimal",
+                        help="minimal (~30 lines) or pro (paste-fix, "
+                        "kill forensics, smart scroll — for 24/7 agent VPS)")
+    p_tins = tx_sub.add_parser(
+        "install",
+        help="install the OmegaOS tmux.conf into ~/.tmux.conf "
+        "(with timestamped backup of the existing one)",
+    )
+    p_tins.add_argument("--profile", choices=["minimal", "pro"],
+                        default="pro",
+                        help="default 'pro' — paste-fix, kill forensics, "
+                        "smart scroll. Use 'minimal' for the lighter version.")
+    p_tins.add_argument("--no-backup", action="store_true",
+                        help="skip the backup of the existing ~/.tmux.conf "
+                        "(NOT recommended)")
+
+    # `omega worker` — persistent-tmux workers (smart model per role)
+    p_wk = sub.add_parser(
+        "worker",
+        help="spawn / run / inspect persistent-tmux workers (smart model per role)",
+    )
+    p_wk.set_defaults(fn=cmd_worker)
+    wk_sub = p_wk.add_subparsers(dest="worker_cmd")
+    # spawn
+    p_wsp = wk_sub.add_parser(
+        "spawn",
+        help="write a brief + dispatch a detached tmux session running `omega worker run`",
+    )
+    p_wsp.add_argument("intent", help="natural-language task")
+    p_wsp.add_argument("--role", default="worker",
+                       help="provider role (default 'worker' → opus 1M context)")
+    p_wsp.add_argument("--task-id", default=None,
+                       help="explicit task id (default: auto-generated t-...)")
+    p_wsp.add_argument("--model", default="",
+                       help="override the role default (e.g. 'sonnet', 'opus', 'haiku')")
+    p_wsp.add_argument("--system-prompt", default="",
+                       help="envelope system prompt (--append-system-prompt)")
+    p_wsp.add_argument("--user-prompt", default="",
+                       help="explicit user prompt (default: same as intent)")
+    p_wsp.add_argument("--verify-cmd", default=None,
+                       help="shell command that proves completion")
+    p_wsp.add_argument("--project", default=None,
+                       help="project slug (used in tmux session name)")
+    p_wsp.add_argument("--cwd", default=None,
+                       help="working directory for the worker (default: $PWD)")
+    p_wsp.add_argument("--mission-id", default="",
+                       help="parent mission id (for traceability)")
+    p_wsp.add_argument("--worker-id", type=int, default=1,
+                       help="worker # within the mission (default 1)")
+    p_wsp.add_argument("--skills", default=None,
+                       help="comma-separated skill ids (overrides role default; "
+                       "e.g. 'pursue,codeaudit')")
+    # run
+    p_wrn = wk_sub.add_parser(
+        "run",
+        help="entry point inside the spawned tmux session — reads brief.json + runs claude",
+    )
+    p_wrn.add_argument("task_id", help="task id whose brief.json to execute")
+    # status
+    p_wst = wk_sub.add_parser("status", help="show the worker's state (.done.json + tmux)")
+    p_wst.add_argument("task_id", help="task id")
+    # wait
+    p_wwt = wk_sub.add_parser("wait", help="block until .done.json appears (or timeout)")
+    p_wwt.add_argument("task_id", help="task id")
+    p_wwt.add_argument("--timeout", type=int, default=3600,
+                       help="max seconds to wait (default 3600)")
+    p_wwt.add_argument("--poll", type=int, default=5,
+                       help="poll interval in seconds (default 5)")
+    # list
+    p_wls = wk_sub.add_parser("list", help="every worker on disk (Agentik_Runtime/sessions)")
+    p_wls.add_argument("--json", action="store_true", help="emit JSON instead of a table")
+
+    # `omega hermes` — Layer-2 Hermes companion (Nous Research, OAuth bridge)
+    p_he = sub.add_parser(
+        "hermes",
+        help="Hermes (Nous Research) Layer-2 companion — uses the SAME "
+        "Claude Max OAuth as `claude`. install / link / status / ask.",
+    )
+    p_he.set_defaults(fn=cmd_hermes)
+    he_sub = p_he.add_subparsers(dest="hermes_cmd")
+    p_hest = he_sub.add_parser("status",
+        help="installed + linked + OAuth token + expiry snapshot")
+    p_hest.add_argument("--json", action="store_true")
+    p_hein = he_sub.add_parser("install",
+        help="run upstream install.sh (idempotent; --yes to re-install)")
+    p_hein.add_argument("--yes", action="store_true",
+                        help="re-install even if hermes is already on PATH")
+    p_hein.add_argument("--with-browser", action="store_true",
+                        help="also install Playwright/Chromium (~150 MB)")
+    p_hein.add_argument("--dry-run", action="store_true",
+                        help="print the command without running it")
+    p_hein.add_argument("--timeout", type=int, default=900,
+                        help="install timeout in seconds (default 900)")
+    p_hein.add_argument("--json", action="store_true")
+    p_hel = he_sub.add_parser("link",
+        help="wire Hermes to use the live Claude OAuth token")
+    p_hel.add_argument("--provider", default="anthropic",
+                       help="Hermes provider id (default: anthropic)")
+    p_hel.add_argument("--model", default="claude-opus-4-7",
+                       help="Hermes default model (default: claude-opus-4-7)")
+    p_hel.add_argument("--dry-run", action="store_true")
+    p_hel.add_argument("--json", action="store_true")
+    p_heask = he_sub.add_parser("ask",
+        help="one-shot prompt → hermes → stdout (uses Claude OAuth)")
+    p_heask.add_argument("prompt", help="natural-language prompt")
+    p_heask.add_argument("--timeout", type=int, default=600)
+    he_sub.add_parser("env",
+        help="print the env vars the bridge would inject (debug helper)")
+    p_hebr = he_sub.add_parser(
+        "brief",
+        help="teach Hermès what OmegaOS is + record outcome observations "
+        "for the self-improvement loop",
+    )
+    p_hebr.add_argument("brief_op", nargs="?", default="status",
+                        choices=["status", "write", "observe"],
+                        help="status (default) | write | observe")
+    p_hebr.add_argument("slug", nargs="?", default=None,
+                        help="(observe) project slug")
+    p_hebr.add_argument("task_id", nargs="?", default=None,
+                        help="(observe) task id whose .done.json to ingest")
+
+    # `omega hermes-desktop` — Hermes Desktop remote backend
+    p_hd = sub.add_parser(
+        "hermes-desktop",
+        help="Expose this VPS as a remote backend for the Hermes Desktop "
+        "Electron app (https://github.com/fathah/hermes-desktop).",
+    )
+    p_hd.set_defaults(fn=cmd_hermes_desktop)
+    hd_sub = p_hd.add_subparsers(dest="hd_cmd")
+    p_hdi = hd_sub.add_parser("install",
+        help="generate the token + print the desktop profile to paste")
+    p_hdi.add_argument("--port", type=int, default=8642)
+    p_hdi.add_argument("--public-url", default=None,
+                        help="public URL the desktop will connect to "
+                        "(default: http://127.0.0.1:<port>)")
+    p_hdp = hd_sub.add_parser("profile",
+        help="print the desktop profile as JSON")
+    p_hdp.add_argument("--port", type=int, default=8642)
+    p_hdp.add_argument("--public-url", default=None)
+    p_hds = hd_sub.add_parser("status",
+        help="snapshot — token present + port free?")
+    p_hds.add_argument("--port", type=int, default=8642)
+    p_hdsv = hd_sub.add_parser("serve",
+        help="bind + serve the HTTP adapter (blocking — run inside tmux)")
+    p_hdsv.add_argument("--port", type=int, default=8642)
+    p_hdsv.add_argument("--unsafe-public", action="store_true",
+                        help="bind 0.0.0.0 (NOT recommended; use SSH tunnel)")
+
+    # `omega ua` — Understand-Anything (Claude Code plugin) bridge
+    p_ua = sub.add_parser(
+        "ua",
+        help="Understand-Anything plugin bridge — install + /understand "
+        "+ consume the knowledge graph into GraphRetriever",
+    )
+    p_ua.set_defaults(fn=cmd_ua)
+    ua_sub = p_ua.add_subparsers(dest="ua_cmd")
+    p_uain = ua_sub.add_parser("install",
+        help="install the Claude Code plugin (uses Max OAuth)")
+    p_uain.add_argument("--timeout", type=int, default=120)
+    p_uain.add_argument("--dry-run", action="store_true")
+    p_uain.add_argument("--json", action="store_true")
+    p_uar = ua_sub.add_parser("run",
+        help="trigger /understand on a project (produces "
+        ".understand-anything/knowledge-graph.json)")
+    p_uar.add_argument("project", help="project directory")
+    p_uar.add_argument("--language", default=None,
+                       help="output language (e.g. fr, ja)")
+    p_uar.add_argument("--timeout", type=int, default=1800)
+    p_uar.add_argument("--json", action="store_true")
+    p_uac = ua_sub.add_parser("consume",
+        help="merge the produced graph into OmegaOS's GraphRetriever")
+    p_uac.add_argument("project", help="project directory containing the output")
+
+    # `omega ma` — Anthropic Managed Agents (opt-in, API key required)
+    p_ma = sub.add_parser(
+        "ma",
+        help="Anthropic Managed Agents lifecycle "
+        "(opt-in; requires ANTHROPIC_API_KEY). Complement to claude-max, "
+        "NOT a replacement.",
+    )
+    p_ma.set_defaults(fn=cmd_ma)
+    ma_sub = p_ma.add_subparsers(dest="ma_cmd")
+    ma_sub.add_parser("info",
+        help="show API-key status + cached agent/env IDs + docs link")
+    # agent
+    p_maag = ma_sub.add_parser("agent", help="manage Managed-Agents Agents (templates)")
+    maag_sub = p_maag.add_subparsers(dest="agent_op")
+    p_maagc = maag_sub.add_parser("create", help="create + cache a new agent")
+    p_maagc.add_argument("name", help="local cache name (e.g. omega-default-agent)")
+    p_maagc.add_argument("--model", default="claude-opus-4-7")
+    p_maagc.add_argument("--system", default="",
+                          help="system prompt baked into the agent template")
+    p_maagg = maag_sub.add_parser("get", help="get an agent by id")
+    p_maagg.add_argument("id")
+    p_maagl = maag_sub.add_parser("list", help="list agents from the org")
+    p_maagl.add_argument("--limit", type=int, default=20)
+    p_maagl.add_argument("--json", action="store_true")
+    p_maagd = maag_sub.add_parser("delete", help="delete an agent by id")
+    p_maagd.add_argument("id")
+    # env
+    p_maen = ma_sub.add_parser("env", help="manage Managed-Agents Environments (sandboxes)")
+    maen_sub = p_maen.add_subparsers(dest="env_op")
+    p_maenc = maen_sub.add_parser("create", help="create + cache a new environment (cloud)")
+    p_maenc.add_argument("name", help="local cache name")
+    p_maeng = maen_sub.add_parser("get", help="get an environment by id")
+    p_maeng.add_argument("id")
+    p_maenl = maen_sub.add_parser("list", help="list environments from the org")
+    p_maenl.add_argument("--limit", type=int, default=20)
+    p_maenl.add_argument("--json", action="store_true")
+    p_maend = maen_sub.add_parser("delete", help="delete an environment by id")
+    p_maend.add_argument("id")
+    # session
+    p_mase = ma_sub.add_parser("session", help="manage Managed-Agents Sessions (running instances)")
+    mase_sub = p_mase.add_subparsers(dest="session_op")
+    p_masec = mase_sub.add_parser("create", help="create a session")
+    p_masec.add_argument("--agent", required=True,
+                          help="agent id OR cache name")
+    p_masec.add_argument("--env", required=True,
+                          help="environment id OR cache name")
+    p_masec.add_argument("--title", default=None)
+    p_masese = mase_sub.add_parser("send", help="send a user message into a session")
+    p_masese.add_argument("id", help="session id")
+    p_masese.add_argument("text", help="user message text")
+    p_masest = mase_sub.add_parser("stream", help="stream SSE events from a session")
+    p_masest.add_argument("id", help="session id")
+    p_masest.add_argument("--timeout", type=int, default=600)
+    p_masel = mase_sub.add_parser("list")
+    p_masel.add_argument("--limit", type=int, default=20)
+    p_masel.add_argument("--json", action="store_true")
+    p_maseg = mase_sub.add_parser("get")
+    p_maseg.add_argument("id")
+    p_masedd = mase_sub.add_parser("delete")
+    p_masedd.add_argument("id")
+    # run (convenience)
+    p_mar = ma_sub.add_parser(
+        "run",
+        help="convenience: create-or-reuse agent + env, start session, "
+        "send the intent, stream until idle, return the aggregated text",
+    )
+    p_mar.add_argument("intent", help="natural-language task")
+    p_mar.add_argument("--agent-name", default="omega-default-agent",
+                       help="cached agent name (created on first use)")
+    p_mar.add_argument("--env-name", default="omega-default-env",
+                       help="cached environment name (created on first use)")
+    p_mar.add_argument("--model", default="claude-opus-4-7")
+    p_mar.add_argument("--system", default="",
+                       help="system prompt for the agent (if creating)")
+    p_mar.add_argument("--role", default="worker",
+                       help="OmegaOS role tag (informational only)")
+    p_mar.add_argument("--timeout", type=int, default=600)
+    p_mar.add_argument("--json", action="store_true")
+
+    # `omega genesis` — programmatic project genesis pipeline
+    p_gen = sub.add_parser(
+        "genesis",
+        help="Project genesis: vision → market (5) → branding (3) → "
+        "PRD (9) → features (N with depends_on) → handoff to plan. "
+        "Strict per-project isolation.",
+    )
+    p_gen.set_defaults(fn=cmd_genesis)
+    gen_sub = p_gen.add_subparsers(dest="genesis_cmd")
+    p_gnew = gen_sub.add_parser("new", help="initialise a new project")
+    p_gnew.add_argument("slug", help="project slug (kebab-case, no spaces)")
+    p_gnew.add_argument("--name", default=None, help="display name")
+    p_gnew.add_argument("--intent", default=None,
+                        help="one-line intent (operator brief)")
+    p_gnew.add_argument("--accept-defaults", action="store_true",
+                        help="use the OmegaOS canonical stack without prompts")
+    p_gnew.add_argument("--force", action="store_true",
+                        help="overwrite PROJECT.yaml if it already exists")
+    p_gnew.add_argument("--json", action="store_true")
+    for k, opts in (
+        ("type", ["web", "mobile", "desktop", "iphone", "mac", "cli",
+                   "library", "mixed"]),
+        ("frontend", ["nextjs", "astro", "remix", "vite-react", "expo",
+                       "tauri", "electron", "swiftui"]),
+        ("backend", ["convex", "supabase", "postgres+drizzle",
+                      "trpc+prisma", "firebase", "none"]),
+        ("deploy", ["vercel", "cloudflare", "fly", "render",
+                     "self-hosted", "aws-amplify", "none", "eas"]),
+        ("payments", ["stripe", "lemonsqueezy", "paddle", "none"]),
+        ("ui_kit", ["shadcn", "radix", "mantine", "mui",
+                     "tailwind-only", "custom"]),
+        ("auth", ["clerk", "better-auth", "next-auth",
+                   "supabase-auth", "custom"]),
+    ):
+        p_gnew.add_argument(f"--stack-{k.replace('_','-')}", dest=f"stack_{k}",
+                            choices=opts, default=None,
+                            help=f"override stack.{k}")
+    p_gquest = gen_sub.add_parser(
+        "questions",
+        help="print the stack-picker question list (for the bot / skill UI)",
+    )
+    p_gquest.add_argument("--intent", default=None)
+    p_gquest.add_argument("--json", action="store_true")
+    p_gstat = gen_sub.add_parser("status", help="phase + completed + stack snapshot")
+    p_gstat.add_argument("slug")
+    p_gstat.add_argument("--json", action="store_true")
+    p_grun = gen_sub.add_parser(
+        "run",
+        help="advance the pipeline (default: to completion; --phase to run one)",
+    )
+    p_grun.add_argument("slug")
+    p_grun.add_argument("--phase", default=None,
+                        help="run only this phase (vision/market/branding/prd/features/plan)")
+    p_grun.add_argument("--max", type=int, default=None,
+                        help="cap the number of phases this call advances")
+    p_gdel = gen_sub.add_parser("delete",
+                                 help="destroy the project tree (requires --yes)")
+    p_gdel.add_argument("slug")
+    p_gdel.add_argument("--yes", action="store_true")
+
+    # `omega plan` — FSM-enforced sequential plan executor
+    p_pl = sub.add_parser(
+        "plan",
+        help="Plan v7 — FSM-enforced sequential plan executor (fixes the "
+        "v6 task-skipping bug by construction, not by prompt).",
+    )
+    p_pl.set_defaults(fn=cmd_plan)
+    pl_sub = p_pl.add_subparsers(dest="plan_cmd")
+    p_pb = pl_sub.add_parser("build",
+                              help="load plan/DAG.json into the per-project store")
+    p_pb.add_argument("slug")
+    p_pb.add_argument("--reset-failed", action="store_true",
+                      help="re-set every FAILED task to PENDING")
+    p_pn = pl_sub.add_parser("next",
+                              help="show the next eligible task (deps all VERIFIED)")
+    p_pn.add_argument("slug")
+    p_pn.add_argument("--json", action="store_true")
+    p_ps = pl_sub.add_parser("status",
+                              help="completion %% + per-state counts + active task")
+    p_ps.add_argument("slug")
+    p_ps.add_argument("--json", action="store_true")
+    p_pl_ls = pl_sub.add_parser("list", help="every task (filter with --state)")
+    p_pl_ls.add_argument("slug")
+    p_pl_ls.add_argument("--state",
+                          choices=["pending", "in_progress", "claimed_done",
+                                   "verified", "failed"], default=None)
+    p_pl_ls.add_argument("--json", action="store_true")
+    p_pst = pl_sub.add_parser("start",
+                                help="PENDING → IN_PROGRESS (requires deps VERIFIED)")
+    p_pst.add_argument("slug"); p_pst.add_argument("task_id")
+    p_pcd = pl_sub.add_parser("claimed",
+                                help="IN_PROGRESS → CLAIMED_DONE (verify next)")
+    p_pcd.add_argument("slug"); p_pcd.add_argument("task_id")
+    p_pdn = pl_sub.add_parser(
+        "done",
+        help="CLAIMED_DONE → VERIFIED via verify_cmd (rejects on non-zero)",
+    )
+    p_pdn.add_argument("slug"); p_pdn.add_argument("task_id")
+    p_pdn.add_argument("--no-verify", action="store_true",
+                        help="skip the verify_cmd (operator override)")
+    p_pfa = pl_sub.add_parser("fail",
+                               help="force-fail a task (operator action)")
+    p_pfa.add_argument("slug"); p_pfa.add_argument("task_id")
+    p_pfa.add_argument("--reason", default=None)
+    p_prt = pl_sub.add_parser("retry",
+                                help="FAILED → PENDING (operator action)")
+    p_prt.add_argument("slug"); p_prt.add_argument("task_id")
+    p_prn = pl_sub.add_parser(
+        "run",
+        help="autonomous multi-day loop: next → in_progress → dispatch "
+        "→ claimed → verify → verified (FSM-enforced; reducer rejects "
+        "any task whose deps aren't VERIFIED).",
+    )
+    p_prn.add_argument("slug")
+    p_prn.add_argument("--max", type=int, default=None,
+                       help="stop after N iterations (default: until no eligible task)")
+    p_prn.add_argument("--spawn-cmd", default=None,
+                       help="shell command to dispatch each task; supports "
+                       "{task_id}/{slug}/{title}/{verify}/{skill}/{files} substitution")
+    p_prn.add_argument("--sleep", type=float, default=0.0,
+                       help="seconds to sleep between iterations (rate limit)")
+    p_prn.add_argument("--json", action="store_true")
+
+    # `omega handoff` — 5-section session handoff memo
+    p_ho = sub.add_parser(
+        "handoff",
+        help="5-section session handoff memo "
+        "(mission / state / files / dead-ends / next)",
+    )
+    p_ho.set_defaults(fn=cmd_handoff)
+    ho_sub = p_ho.add_subparsers(dest="handoff_cmd")
+    ho_sub.add_parser("template",
+                       help="print the canonical 5-section template")
+    p_horead = ho_sub.add_parser("read",
+        help="print the latest handoff for a project or task")
+    p_horead.add_argument("--project", help="project slug")
+    p_horead.add_argument("--task-id", help="task id")
+    p_horead.add_argument("--json", action="store_true",
+                          help="emit JSON instead of markdown")
+    p_holist = ho_sub.add_parser("list",
+        help="chronological list of archived handoffs for a project")
+    p_holist.add_argument("project", help="project slug")
+    p_holist.add_argument("--json", action="store_true",
+                          help="emit JSON instead of pretty text")
+    p_howrite = ho_sub.add_parser("write",
+        help="write a handoff (interactive prompts unless --file is given)")
+    p_howrite.add_argument("--project", default=None, help="project slug")
+    p_howrite.add_argument("--task-id", default=None, help="task id")
+    p_howrite.add_argument("--mission-id", default=None, help="mission id")
+    p_howrite.add_argument("--author", default=None,
+                            help="who wrote this (default: 'human')")
+    p_howrite.add_argument("--file", default=None,
+                            help="markdown file to import (skips prompts)")
+    p_hofd = ho_sub.add_parser("from-done",
+        help="auto-draft a handoff from a worker's .done.json + git diff")
+    p_hofd.add_argument("task_id", help="task id whose .done.json to read")
+    p_hofd.add_argument("--project", default=None,
+                        help="also write under the project (slug)")
+    p_hofd.add_argument("--cwd", default=None,
+                        help="git repo for `git diff --name-only` (default: $PWD)")
+    p_hofd.add_argument("--print", action="store_true",
+                        help="also print the rendered markdown after writing")
+
+    # `omega cleanup` — OmegaOS-adapted disk cleanup
+    p_cln = sub.add_parser(
+        "cleanup",
+        help="OmegaOS-adapted disk cleanup (tiers 1-6 + optional --deep). "
+        "Default is dry-run; pass --yes to actually free space.",
+    )
+    p_cln.add_argument("--yes", action="store_true",
+                       help="actually delete (default is dry-run)")
+    p_cln.add_argument("--deep", action="store_true",
+                       help="also run the deep tiers (staging, transcripts, VACUUM, opensrc, git gc)")
+    p_cln.add_argument("--target", type=int, default=None,
+                       help="stop early once disk usage drops below TARGET%%")
+    p_cln.add_argument("--idle-days", type=int, default=7,
+                       help="node_modules pruning idle threshold (default 7d)")
+    p_cln.add_argument("--runtime-days", type=int, default=30,
+                       help="runtime DB / sessions retention (default 30d)")
+    p_cln.add_argument("--tmux-hours", type=int, default=24,
+                       help="stale tmux worker threshold (default 24h)")
+    p_cln.add_argument("--json", action="store_true",
+                       help="emit per-tier JSON instead of pretty text")
+    p_cln.set_defaults(fn=cmd_cleanup)
+
+    # `omega aisb` — Telegram-fallback chat with the AISB master agent
+    p_ai = sub.add_parser("aisb", help="talk to AISB outside Telegram (tmux fallback)")
+    p_ai.set_defaults(fn=cmd_aisb)
+    ai_sub = p_ai.add_subparsers(dest="aisb_cmd")
+    ai_sub.add_parser("chat", help="spawn (or attach to) the AISB-chat tmux session")
+    ai_sub.add_parser("chat-loop", help="the REPL itself (called by the tmux session)")
+
+    # `omega validate providers` — 1-token API key validation
+    p_val = sub.add_parser("validate", help="validate provider credentials with a 1-token round-trip")
+    p_val.set_defaults(fn=cmd_validate)
+    val_sub = p_val.add_subparsers(dest="validate_cmd")
+    p_vprov = val_sub.add_parser("providers", help="validate every wired provider")
+    p_vprov.add_argument("--provider", default=None,
+                          help="validate only this provider id (claude|glm|openai|deepseek)")
+
+    # `omega completions` — write + install shell completion scripts
+    p_comp = sub.add_parser("completions", help="generate + install shell completion scripts")
+    p_comp.set_defaults(fn=cmd_completions)
+    comp_sub = p_comp.add_subparsers(dest="completions_cmd")
+    comp_sub.add_parser("write", help="(re)write completion scripts under Agentik_Tools/completions/")
+    p_cinst = comp_sub.add_parser("install", help="symlink the completion into the operator's shell")
+    p_cinst.add_argument("shell", choices=["bash", "zsh", "fish"])
+
+    # `omega update {check,apply,banner,auto}` — full auto-update lifecycle
+    p_upd = sub.add_parser(
+        "update",
+        help="auto-update lifecycle: check / apply / banner / auto",
+    )
+    p_upd.add_argument("--check", action="store_true",
+                       help="(legacy) same as `omega update check`")
+    p_upd.set_defaults(fn=cmd_update)
+    upd_sub = p_upd.add_subparsers(dest="update_cmd")
+    upd_sub.add_parser("check",
+                       help="print current + latest from npm (no install)")
+    p_uapp = upd_sub.add_parser(
+        "apply",
+        help="backup → npm install → migrate → upgrade → verify; rollback on fail",
+    )
+    p_uapp.add_argument("--no-backup", action="store_true",
+                        help="skip the pre-update backup (NOT recommended)")
+    p_uapp.add_argument("--no-verify", action="store_true",
+                        help="skip the post-update doctor + smoke")
+    p_uapp.add_argument("--no-npm", action="store_true",
+                        help="don't run `npm install` (assume already on disk)")
+    p_uapp.add_argument("--json", action="store_true",
+                        help="emit JSON instead of pretty text")
+    upd_sub.add_parser(
+        "banner",
+        help="emit the one-line outdated banner to stderr "
+        "(invoked by every omega CLI startup; opt-out via OMEGA_NO_UPDATE_BANNER=1)",
+    )
+    p_uauto = upd_sub.add_parser(
+        "auto",
+        help="enable / disable / inspect the daily auto-apply charter",
+    )
+    p_uauto.add_argument("auto_op", nargs="?", default="status",
+                         choices=["status", "enable", "disable"],
+                         help="status (default) / enable / disable")
+
+    # `omega smoke` — synthetic mission
+    p_smk = sub.add_parser("smoke", help="synthetic mission post-install verification")
+    p_smk.set_defaults(fn=cmd_smoke)
+
+    # `omega prune` — bound SQLite growth
+    p_pr = sub.add_parser("prune", help="prune old rows from events / audits / telegram / sessions")
+    p_pr.add_argument("target", choices=["events", "audits", "telegram", "sessions", "all"])
+    p_pr.add_argument("--days", type=int, default=90,
+                      help="prune rows older than DAYS (default 90)")
+    p_pr.add_argument("--yes", action="store_true",
+                      help="apply (default is dry-run)")
+    p_pr.set_defaults(fn=cmd_prune)
+
+    # `omega backup` — tarball + optional age-encrypt
+    p_bk = sub.add_parser("backup", help="backup + restore + verify the recoverable subset of $OMEGA_HOME")
+    p_bk.set_defaults(fn=cmd_backup)
+    bk_sub = p_bk.add_subparsers(dest="backup_cmd")
+    p_bcr = bk_sub.add_parser("create", help="create a backup tarball")
+    p_bcr.add_argument("--out", default=None, help="output directory (default ~/)")
+    p_bcr.add_argument("--encrypt", action="store_true",
+                       help="age-encrypt the tarball (recipient = .vault-pub)")
+    p_bcr.add_argument("--recipient", default=None,
+                       help="path to age recipient public key (default .vault-pub)")
+    p_brst = bk_sub.add_parser("restore", help="restore a backup tarball")
+    p_brst.add_argument("bundle", help="path to the backup tarball")
+    p_brst.add_argument("--target", default=None,
+                        help="destination tree (default $OMEGA_HOME)")
+    p_brst.add_argument("--identity", default=None,
+                        help="age identity file (default .vault-key)")
+    p_bv = bk_sub.add_parser("verify", help="extract the bundle into a temp dir + check shape")
+    p_bv.add_argument("bundle", help="path to the backup tarball")
+    p_bv.add_argument("--identity", default=None)
+
+    # `omega costs` — per-account USD projections
+    p_co = sub.add_parser("costs", help="project per-account usage into USD via the built-in rate card")
+    p_co.set_defaults(fn=cmd_costs)
+
+    # `omega mission rerun <id>`
+    p_mi = sub.add_parser("mission", help="manage past missions (rerun, ...)")
+    p_mi.set_defaults(fn=cmd_mission)
+    mi_sub = p_mi.add_subparsers(dest="mission_cmd")
+    p_mrer = mi_sub.add_parser("rerun", help="re-dispatch a past mission with fresh state")
+    p_mrer.add_argument("id", help="mission id (m-...)")
+
+    # `omega project precommit install <slug>`
+    p_pc = sub.add_parser("precommit", help="install / uninstall pre-commit hook in a project")
+    p_pc.set_defaults(fn=cmd_precommit)
+    pc_sub = p_pc.add_subparsers(dest="precommit_cmd")
+    p_pcin = pc_sub.add_parser("install", help="write a pre-commit hook running codeaudit")
+    p_pcin.add_argument("slug", help="project slug")
+    p_pcun = pc_sub.add_parser("uninstall", help="remove the pre-commit hook (restore backup if any)")
+    p_pcun.add_argument("slug", help="project slug")
+
+    # `omega webhook` — inbound webhook registry + test gate
+    p_wh = sub.add_parser(
+        "webhook",
+        help="inbound webhooks (GitHub/Linear/generic) — list, show, test",
+    )
+    p_wh.set_defaults(fn=cmd_webhook)
+    wh_sub = p_wh.add_subparsers(dest="webhook_cmd")
+    wh_sub.add_parser("list", help="show every configured webhook")
+    p_whshow = wh_sub.add_parser("show", help="full spec for one webhook")
+    p_whshow.add_argument("id")
+    p_whtest = wh_sub.add_parser("test", help="fire a synthetic signed POST through the gate")
+    p_whtest.add_argument("id")
+    p_whtest.add_argument("--body", default=None,
+                          help="raw JSON body (default: {\"intent\":\"synthetic test\"})")
+
+    # `omega uninstall` — clean removal of the deployment
+    p_uns = sub.add_parser(
+        "uninstall",
+        help="cleanly remove OmegaOS from this machine "
+        "(strips settings.json keys, removes services, optionally LLM CLIs)",
+    )
+    p_uns.add_argument("--yes", action="store_true",
+                       help="skip the confirmation prompt")
+    p_uns.add_argument("--purge", action="store_true",
+                       help="also delete the encrypted vault "
+                       "(default: back it up to ~/.omega-vault-backup-*)")
+    p_uns.add_argument("--include-llm-clis", action="store_true",
+                       help="also npm/uv uninstall the LLM CLIs")
+    p_uns.set_defaults(fn=cmd_uninstall)
+
+    # `omega upgrade` — re-run the installer in place
+    p_upg = sub.add_parser(
+        "upgrade",
+        help="re-run the installer (preserves the runtime tree); pulls "
+        "in new install steps",
+    )
+    p_upg.add_argument("--profile", default=None,
+                       choices=["vps", "workstation", "minimal"])
+    p_upg.add_argument("--manifest", default=None)
+    p_upg.add_argument("--non-interactive", action="store_true")
+    p_upg.set_defaults(fn=cmd_upgrade)
+
+    # `omega skill` — discover + audit + install skills (safe-by-default)
+    p_skl = sub.add_parser("skill", help="discover, audit, install Claude Code skills")
+    p_skl.set_defaults(fn=cmd_skill)
+    skl_sub = p_skl.add_subparsers(dest="skill_cmd")
+    skl_sub.add_parser("marketplaces", help="show catalog of marketplaces")
+    p_sfind = skl_sub.add_parser("find", help="search the curated catalog")
+    p_sfind.add_argument("query", nargs="?", default=None)
+    p_sfind.add_argument("--min-trust", default="low",
+                         choices=["low", "medium", "high"])
+    p_sfind.add_argument("--recommended", action="store_true",
+                         help="only the curated picks")
+    p_saud = skl_sub.add_parser("audit", help="safety-audit a SKILL.md")
+    p_saud.add_argument("path", help="path to SKILL.md")
+    p_sins = skl_sub.add_parser("install", help="install a skill from a GitHub source")
+    p_sins.add_argument("name", help="local name for the skill (becomes the dir)")
+    p_sins.add_argument("--from", dest="from_", required=True,
+                        help="source — github:<org>/<repo>[/<subpath>]")
+    p_sins.add_argument("--allow-blocked", action="store_true",
+                        help="install even if the auditor blocked it (NOT recommended)")
+    p_srec = skl_sub.add_parser(
+        "recommend",
+        help="show the curated skill palette for a role "
+        "(used by `omega worker spawn`)",
+    )
+    p_srec.add_argument("role",
+                        help="role id (worker, oracle, audit, classifier, ...)")
+    skl_sub.add_parser(
+        "catalog",
+        help="every skill present under $OMEGA_HOME/Agentik_SSOT/skills/",
+    )
+    skl_sub.add_parser(
+        "link",
+        help="symlink projected SSOT skills into ~/.claude/skills/ so they "
+        "become real slash commands (idempotent; run after `omega sync`)",
+    )
+    p_swf = skl_sub.add_parser(
+        "workflows",
+        help="show canonical skill-chain workflows (dispatch→pursue→audit→fix→re-audit, …)",
+    )
+    p_swf.add_argument("name", nargs="?", default=None,
+                       help="workflow id (omitted → list all)")
+
+    # `omega agent` — inspect resolved agent prompts (debugging)
+    p_ag = sub.add_parser("agent", help="list or inspect agent prompts")
+    p_ag.set_defaults(fn=cmd_agent)
+    ag_sub = p_ag.add_subparsers(dest="agent_cmd")
+    ag_sub.add_parser("list", help="every role under Agentik_SSOT/agents/")
+    p_apr = ag_sub.add_parser("prompt", help="print the resolved system + user prompt")
+    p_apr.add_argument("role", help="role name (oracle, worker, architect, ...)")
+    p_apr.add_argument("--intent", default=None,
+                       help="example intent to embed in the user message (optional)")
+
+    # `omega audit` — the Quality Arsenal CLI (run, all, history, batch, gen)
+    p_aud = sub.add_parser("audit", help="run a forensic audit or browse history")
+    p_aud.set_defaults(fn=cmd_audit)
+    aud_sub = p_aud.add_subparsers(dest="audit_cmd")
+    p_arun = aud_sub.add_parser("run", help="run one audit (gather + analyse)")
+    p_arun.add_argument("audit_id", help="audit id (e.g. codeaudit)")
+    p_arun.add_argument("--scope", default=None, help="path to audit")
+    p_arun.add_argument("--role", default="worker")
+    p_arun.add_argument("--fix", action="store_true",
+                        help="also batch + dispatch fix workers + re-audit")
+    p_arun.add_argument("--max-workers", type=int, default=3,
+                        help="cap fix-worker parallelism (default 3)")
+    p_arun.add_argument("--min-severity", default=None,
+                        choices=["low", "medium", "high", "critical"],
+                        help="ignore findings below this severity in --fix mode")
+    p_aall = aud_sub.add_parser("all", help="run every applicable audit (read-only by default)")
+    p_aall.add_argument("--scope", default=None)
+    p_aall.add_argument("--role", default="worker")
+    p_aall.add_argument("--fix", action="store_true")
+    p_aall.add_argument("--max-workers", type=int, default=3)
+    p_aall.add_argument("--min-severity", default=None,
+                        choices=["low", "medium", "high", "critical"])
+    p_ahist = aud_sub.add_parser("history", help="past runs for an audit")
+    p_ahist.add_argument("audit_id", nargs="?", default=None)
+    p_ahist.add_argument("--limit", type=int, default=20)
+    p_abatch = aud_sub.add_parser("batch",
+                                   help="show what batches the last run would form")
+    p_abatch.add_argument("audit_id")
+    p_abatch.add_argument("--max-workers", type=int, default=3)
+    p_abatch.add_argument("--min-severity", default=None,
+                          choices=["low", "medium", "high", "critical"])
+    aud_sub.add_parser("gen", help="regenerate every SKILL.md from the YAMLs")
+    aud_sub.add_parser("gate",
+                       help="Stop-hook gatekeeper: reads JSON on stdin, "
+                       "denies the Stop if the latest .done.json or audit "
+                       "verdict says not done")
+    p_adiff = aud_sub.add_parser("diff", help="diff findings between two audit runs")
+    p_adiff.add_argument("run1", help="older run id")
+    p_adiff.add_argument("run2", help="newer run id")
+    p_adiff.set_defaults(fn=cmd_audit_diff)
+
+    # `omega pursue` — goal-driven loop (Agentik OS native /goal replacement)
+    p_pursue = sub.add_parser(
+        "pursue",
+        help="loop Read/Edit/Bash until a verify_cmd exits 0 "
+        "(Agentik OS goal-driven worker)",
+    )
+    p_pursue.add_argument("verify_cmd", help="shell command that proves the goal is met (exit 0)")
+    p_pursue.add_argument("intent", help="natural-language goal")
+    p_pursue.add_argument("--max-iters", type=int, default=20,
+                          help="hard cap on iterations (default 20)")
+    p_pursue.add_argument("--project", default=None,
+                          help="project slug — cwd defaults to that project's dir")
+    p_pursue.add_argument("--role", default="worker", help="provider role (default 'worker')")
+    p_pursue.add_argument("--cwd", default=None,
+                          help="working directory for verify_cmd")
+    p_pursue.set_defaults(fn=cmd_pursue)
+
+    # `omega cadence` — scheduled recurring execution (Agentik OS native /loop)
+    p_cad = sub.add_parser(
+        "cadence",
+        help="schedule a recurring beat via the AutonomousSupervisor "
+        "(Agentik OS /loop equivalent)",
+    )
+    p_cad.set_defaults(fn=cmd_cadence)
+    cad_sub = p_cad.add_subparsers(dest="cadence_cmd")
+    p_csched = cad_sub.add_parser("schedule", help="schedule a new cadence")
+    p_csched.add_argument("trigger", choices=["cron", "delay", "self"])
+    p_csched.add_argument("schedule",
+                          help="cron expr, delay-seconds, or literal 'self'")
+    p_csched.add_argument("intent",
+                          help="what to do at each beat (natural language)")
+    cad_sub.add_parser("list", help="show every scheduled cadence")
+    p_cdis = cad_sub.add_parser("disable", help="set a cadence to enabled=false")
+    p_cdis.add_argument("id", help="charter id (cadence-...)")
+    p_crm = cad_sub.add_parser("remove", help="delete a cadence charter")
+    p_crm.add_argument("id", help="charter id (cadence-...)")
+
+    p_dae = sub.add_parser("daemon", help="run a 24/7 service daemon")
+    p_dae.add_argument("name", choices=["engine", "telegram", "autonomous"],
+                       help="which daemon to run")
+    p_dae.set_defaults(fn=cmd_daemon)
+
+    p_tool = sub.add_parser("tool", help="manage installed tools (incl. MCP servers)")
+    p_tool.set_defaults(fn=cmd_tool)
+    tool_sub = p_tool.add_subparsers(dest="tool_cmd")
+    tool_sub.add_parser("list", help="list installed tools (default)")
+    p_tinst = tool_sub.add_parser("install", help="install from the MCP catalog (default) or via --npm")
+    p_tinst.add_argument("name", help="tool name (an MCP catalog id, or a free name when --npm is given)")
+    p_tinst.add_argument("--npm", default=None, metavar="PACKAGE",
+                         help="install a bare npm package under Agentik_Tools/<name>/")
+    p_trm = tool_sub.add_parser("remove", help="remove a tool + unregister")
+    p_trm.add_argument("name", help="tool name")
+    p_tup = tool_sub.add_parser("update", help="re-install a tool from its recorded source")
+    p_tup.add_argument("name", help="tool name")
+
+    sub.add_parser(
+        "sync",
+        help="project Agentik_SSOT/ into each provider's native shape",
+    ).set_defaults(fn=cmd_sync)
+
+    p_graph = sub.add_parser(
+        "graph",
+        help="consume a graphify-built graph.json into Graph RAG "
+        "(graphify itself is a Claude Code skill)",
+    )
+    p_graph.add_argument(
+        "path",
+        help="repo / directory containing graphify-out/graph.json, "
+        "OR the literal word 'install' to register the /graphify skill",
+    )
+    p_graph.add_argument(
+        "--json", default=None,
+        help="override the graph.json path (default: <path>/graphify-out/graph.json)",
+    )
+    p_graph.add_argument(
+        "--rag", action="store_true",
+        help="merge nodes + edges into the engine's GraphRetriever "
+        "(Agentik_Runtime/memory/graph.json)",
+    )
+    p_graph.add_argument(
+        "--platform", default="claude",
+        help="when path=install, which Claude-compatible platform to target "
+        "(default: claude)",
+    )
+    p_graph.set_defaults(fn=cmd_graph)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    # Auto-update banner: fast cached check (no network unless stale,
+    # < 5 ms). Skipped for the `update` and `doctor --json` commands so
+    # neither auto-update nor machine-readable output get polluted by it.
+    cmd = getattr(args, "cmd", None)
+    skip_banner = (
+        cmd in ("update", "completions", "version")
+        or (cmd == "doctor" and getattr(args, "json", False))
+    )
+    if not skip_banner:
+        try:
+            from omega_engine.auto_update import maybe_emit_banner
+            maybe_emit_banner(_omega_home())
+        except Exception:  # noqa: BLE001
+            # Banner failure must NEVER block the actual command.
+            pass
     return args.fn(args)