@agentikos/omega-os 0.2.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/menu.py

@@ -0,0 +1,1065 @@
+"""`omega` with no args → an interactive whiptail menu.
+
+The user wanted "j'aimerais que quand on a Omega installée, si on fait
+``omega`` dans le terminal, ça ouvre Omega et ça nous permet de rentrer
+dans les différents menus pour configurer ça". This is that menu.
+
+Design:
+
+  * **Zero new deps.** Whiptail is already part of the install (used by
+    step_mcp + step_claude_plugins + step_llm_clis).
+  * **Wraps the existing CLI**, doesn't reimplement. Each menu leaf
+    builds and runs the right ``omega ...`` command, captures output,
+    shows it in a ``--msgbox`` so the user always lands back in the menu.
+  * **Stateless.** No background loops, no daemons. Hit Cancel / Esc to
+    exit any submenu; the main loop runs until "Quit".
+  * **Discoverable.** Every command in the CLI is reachable from a menu
+    — no hidden command surface.
+
+This is intentionally a thin facade. Operators who prefer the CLI keep
+using it; ``omega`` (no args) is the on-ramp for everyone else.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _have(binary: str) -> bool:
+    return shutil.which(binary) is not None
+
+
+def _omega_bin() -> str:
+    """Resolve the omega CLI path. Falls back to ``sys.argv[0]`` so the menu
+    works whether you invoked the venv binary or via the symlink."""
+    from omega_engine import __version__   # noqa: F401 — proves import works
+    cand = (
+        Path(os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")))
+        / "Agentik_Tools" / "bin" / "omega"
+    )
+    if cand.exists():
+        return str(cand)
+    # Fallback to current invocation
+    return sys.argv[0] or "omega"
+
+
+# ---------------------------------------------------------------------------
+# Low-level whiptail wrappers
+# ---------------------------------------------------------------------------
+
+
+def _whiptail_menu(
+    title: str, prompt: str, items: list[tuple[str, str]],
+    *, height: int = 22, width: int = 78, list_height: int = 12,
+) -> str | None:
+    """Show a --menu. Returns the chosen tag or None on cancel/escape."""
+    args = ["whiptail", "--title", title,
+            "--menu", prompt,
+            str(height), str(width), str(list_height)]
+    for tag, label in items:
+        args += [tag, label]
+    proc = subprocess.run(args, capture_output=True, text=True)
+    if proc.returncode != 0:
+        return None
+    return proc.stderr.strip() or None
+
+
+def _whiptail_input(title: str, prompt: str,
+                    default: str = "") -> str | None:
+    """Show an --inputbox. Returns the entered string or None on cancel."""
+    proc = subprocess.run(
+        ["whiptail", "--title", title,
+         "--inputbox", prompt, "12", "78", default],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return None
+    return proc.stderr.strip()
+
+
+def _whiptail_yesno(title: str, prompt: str) -> bool:
+    """Show a --yesno. Returns True if the user confirms."""
+    proc = subprocess.run(
+        ["whiptail", "--title", title, "--yesno", prompt, "10", "78"],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0
+
+
+def _show_output(title: str, body: str, *, height: int = 22, width: int = 100) -> None:
+    """Display long subprocess output back to the user.
+
+    We use --msgbox for short outputs and --textbox (via a temp file) for
+    longer ones so the user can scroll.
+    """
+    if len(body) < 1500 and body.count("\n") < 22:
+        subprocess.run(
+            ["whiptail", "--title", title, "--msgbox", body or "(no output)",
+             str(height), str(width)],
+            capture_output=True, text=True,
+        )
+        return
+    import tempfile
+    with tempfile.NamedTemporaryFile("w", delete=False, suffix=".txt") as fh:
+        fh.write(body or "(no output)\n")
+        path = fh.name
+    try:
+        subprocess.run(
+            ["whiptail", "--title", title, "--scrolltext",
+             "--textbox", path, str(height), str(width)],
+            capture_output=True, text=True,
+        )
+    finally:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+
+
+def _run_capture(*omega_args: str) -> str:
+    """Run an omega CLI invocation and return the combined output."""
+    cmd = [_omega_bin(), *omega_args]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=900)
+    out = (proc.stdout or "") + (proc.stderr or "")
+    return out.rstrip()
+
+
+# ---------------------------------------------------------------------------
+# Sub-menu dispatchers
+# ---------------------------------------------------------------------------
+
+
+def _menu_mission() -> None:
+    intent = _whiptail_input(
+        "Run a mission", "Mission intent (the Oracle will plan it):",
+    )
+    if not intent:
+        return
+    if not _whiptail_yesno("Confirm", f"Dispatch a mission with:\n\n{intent[:200]}\n\nProceed?"):
+        return
+    out = _run_capture("run", intent)
+    _show_output("Mission result", out)
+
+
+def _menu_status() -> None:
+    out = _run_capture("status")
+    _show_output("omega status", out)
+
+
+def _menu_doctor() -> None:
+    out = _run_capture("doctor")
+    _show_output("omega doctor", out)
+
+
+def _menu_smoke() -> None:
+    out = _run_capture("smoke")
+    _show_output("omega smoke", out)
+
+
+def _menu_projects() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Projects", "Project management:",
+            items=[
+                ("new",       "Create a new project (+ Telegram topic)"),
+                ("secret",    "Manage per-project secrets"),
+                ("precommit", "Install/uninstall pre-commit audit hook"),
+                ("back",      "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "new":
+            name = _whiptail_input("New project", "Project name:")
+            if name:
+                _show_output("Project created", _run_capture("project", name))
+        elif choice == "secret":
+            slug = _whiptail_input("Project secret", "Project slug:")
+            if not slug:
+                continue
+            sub = _whiptail_menu(
+                "Project secret", f"Slug: {slug}",
+                items=[("list", "List secrets"),
+                       ("set",  "Set a secret"),
+                       ("get",  "Get a secret"),
+                       ("back", "← Back")],
+            )
+            if sub == "list":
+                _show_output("secrets", _run_capture("project", "secret", "list", slug))
+            elif sub == "set":
+                ref = _whiptail_input("set", "Secret ref:") or ""
+                val = _whiptail_input("set", f"Value for {ref}:") or ""
+                if ref and val:
+                    _show_output("set", _run_capture(
+                        "project", "secret", "set", slug, "--ref", ref, "--value", val,
+                    ))
+            elif sub == "get":
+                ref = _whiptail_input("get", "Secret ref:") or ""
+                if ref:
+                    _show_output("get", _run_capture(
+                        "project", "secret", "get", slug, "--ref", ref,
+                    ))
+        elif choice == "precommit":
+            slug = _whiptail_input("pre-commit", "Project slug:")
+            if not slug:
+                continue
+            sub = _whiptail_menu(
+                "pre-commit", f"Slug: {slug}",
+                items=[("install",   "Install pre-commit audit hook"),
+                       ("uninstall", "Remove the hook"),
+                       ("back",      "← Back")],
+            )
+            if sub in ("install", "uninstall"):
+                _show_output(sub, _run_capture("precommit", sub, slug))
+
+
+def _menu_accounts() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Claude Max accounts",
+            "Manage the OAuth account pool (no API keys — Max only):",
+            items=[
+                ("list",  "List the pool"),
+                ("login", "Add a new Claude Max account"),
+                ("use",   "Change an account's status"),
+                ("pool",  "Edit pool selection / weights"),
+                ("back",  "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "list":
+            _show_output("accounts", _run_capture("account", "list"))
+        elif choice == "login":
+            aid = _whiptail_input("account login", "Account id (e.g. max-primary):")
+            if aid:
+                _show_output("login", _run_capture(
+                    "account", "login", "--id", aid,
+                ))
+        elif choice == "use":
+            aid = _whiptail_input("account use", "Account id:") or ""
+            if not aid:
+                continue
+            status = _whiptail_menu(
+                "account use", f"New status for {aid}:",
+                items=[("active",   "active"),
+                       ("resting",  "resting"),
+                       ("disabled", "disabled")],
+            )
+            if status:
+                _show_output("use", _run_capture(
+                    "account", "use", aid, status,
+                ))
+        elif choice == "pool":
+            sel = _whiptail_menu(
+                "account pool", "Pool selection strategy:",
+                items=[("round-robin", "round-robin"),
+                       ("least-used",  "least-used"),
+                       ("by-quota",    "by-quota")],
+            )
+            if sel:
+                _show_output("pool", _run_capture(
+                    "account", "pool", "--selection", sel,
+                ))
+
+
+def _menu_audit() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Audits", "Quality Arsenal — 18 forensic audits:",
+            items=[
+                ("run",     "Run one audit"),
+                ("all",     "Run every applicable audit"),
+                ("history", "Show audit history + trend"),
+                ("gen",     "Regenerate audit SKILL.md from YAMLs"),
+                ("back",    "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "run":
+            aid = _whiptail_input("audit", "Audit id (e.g. codeaudit):")
+            if aid:
+                fix = _whiptail_yesno("audit", "Also dispatch fix workers + reaudit?")
+                args = ["audit", "run", aid]
+                if fix:
+                    args.append("--fix")
+                _show_output(f"audit {aid}", _run_capture(*args))
+        elif choice == "all":
+            _show_output("audit all", _run_capture("audit", "all"))
+        elif choice == "history":
+            aid = _whiptail_input("audit history",
+                                   "Audit id (blank = all):") or ""
+            args = ["audit", "history"]
+            if aid:
+                args.append(aid)
+            _show_output("audit history", _run_capture(*args))
+        elif choice == "gen":
+            _show_output("audit gen", _run_capture("audit", "gen"))
+
+
+def _menu_skills() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Skills", "Skill discovery + safety audit:",
+            items=[
+                ("find",         "Find skills in the curated catalog"),
+                ("audit",        "Run safety auditor on a SKILL.md"),
+                ("install",      "Install from a GitHub source"),
+                ("marketplaces", "List trusted marketplaces"),
+                ("back",         "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "find":
+            q = _whiptail_input("skill find", "Search query (blank = all):") or ""
+            args = ["skill", "find"]
+            if q:
+                args.append(q)
+            _show_output("skill find", _run_capture(*args))
+        elif choice == "audit":
+            path = _whiptail_input("skill audit", "Path to SKILL.md:")
+            if path:
+                _show_output("skill audit", _run_capture(
+                    "skill", "audit", path,
+                ))
+        elif choice == "install":
+            name = _whiptail_input("skill install", "Local name for the skill:")
+            if not name:
+                continue
+            src = _whiptail_input("skill install",
+                                   "Source (github:<org>/<repo>[/<path>]):")
+            if name and src:
+                _show_output("install", _run_capture(
+                    "skill", "install", name, "--from", src,
+                ))
+        elif choice == "marketplaces":
+            _show_output("marketplaces",
+                          _run_capture("skill", "marketplaces"))
+
+
+def _menu_maintenance() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Maintenance", "System operations:",
+            items=[
+                ("smoke",     "Run synthetic-mission smoke test"),
+                ("cleanup",   "OmegaOS-adapted disk cleanup (6 tiers + --deep)"),
+                ("prune",     "Prune old rows from runtime DBs"),
+                ("backup",    "Create / restore / verify backup"),
+                ("validate",  "Validate provider credentials"),
+                ("upgrade",   "Re-run the installer (preserves runtime)"),
+                ("update",    "Check for a newer omega-os version"),
+                ("billing",   "Per-account token usage"),
+                ("costs",     "Project usage → USD"),
+                ("back",      "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "smoke":
+            _show_output("smoke", _run_capture("smoke"))
+        elif choice == "cleanup":
+            deep = _whiptail_yesno("cleanup", "Run deep tiers (staging, transcripts, VACUUM, opensrc, git gc)?")
+            apply = _whiptail_yesno("cleanup", "Apply (no = dry-run)?")
+            args = ["cleanup"]
+            if deep:
+                args.append("--deep")
+            if apply:
+                args.append("--yes")
+            _show_output("cleanup", _run_capture(*args))
+        elif choice == "prune":
+            target = _whiptail_menu(
+                "prune", "Target:",
+                items=[("events",   "events"),
+                       ("audits",   "audits"),
+                       ("telegram", "telegram"),
+                       ("sessions", "sessions"),
+                       ("all",      "all")],
+            )
+            if not target:
+                continue
+            days = _whiptail_input("prune", "Older than (days):", "90") or "90"
+            apply = _whiptail_yesno("prune", "Apply (no = dry-run)?")
+            args = ["prune", target, "--days", days]
+            if apply:
+                args.append("--yes")
+            _show_output("prune", _run_capture(*args))
+        elif choice == "backup":
+            sub = _whiptail_menu(
+                "backup", "Operation:",
+                items=[("create",  "Create a backup"),
+                       ("restore", "Restore a backup"),
+                       ("verify",  "Verify a backup")],
+            )
+            if sub == "create":
+                enc = _whiptail_yesno("backup", "Encrypt with age?")
+                args = ["backup", "create"]
+                if enc:
+                    args.append("--encrypt")
+                _show_output("backup", _run_capture(*args))
+            elif sub in ("restore", "verify"):
+                p = _whiptail_input(f"backup {sub}", "Path to bundle:")
+                if p:
+                    _show_output(f"backup {sub}",
+                                  _run_capture("backup", sub, p))
+        elif choice == "validate":
+            _show_output("validate providers",
+                          _run_capture("validate", "providers"))
+        elif choice == "upgrade":
+            if _whiptail_yesno("upgrade", "Re-run install.sh --force?"):
+                _show_output("upgrade", _run_capture("upgrade"))
+        elif choice == "update":
+            _show_output("update", _run_capture("update", "--check"))
+        elif choice == "billing":
+            _show_output("billing", _run_capture("billing"))
+        elif choice == "costs":
+            _show_output("costs", _run_capture("costs"))
+
+
+def _menu_settings() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Settings", "OmegaOS-side configuration:",
+            items=[
+                ("agents",      "View resolved agent prompts (debug)"),
+                ("completions", "Install shell completions"),
+                ("tools",       "List installed MCPs / tools"),
+                ("webhooks",    "List inbound webhooks"),
+                ("sync",        "Project SSOT into Claude Code"),
+                ("back",        "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "agents":
+            sub = _whiptail_menu(
+                "agents", "Agents:",
+                items=[("list",   "List all known agents"),
+                       ("prompt", "Print the resolved system+user prompt")],
+            )
+            if sub == "list":
+                _show_output("agents", _run_capture("agent", "list"))
+            elif sub == "prompt":
+                role = _whiptail_input("prompt", "Role (oracle, worker, ...):")
+                if role:
+                    _show_output("prompt",
+                                  _run_capture("agent", "prompt", role))
+        elif choice == "completions":
+            shell = _whiptail_menu(
+                "completions", "Shell:",
+                items=[("bash", "bash"),
+                       ("zsh",  "zsh"),
+                       ("fish", "fish")],
+            )
+            if shell:
+                _run_capture("completions", "write")
+                _show_output("completions",
+                              _run_capture("completions", "install", shell))
+        elif choice == "tools":
+            _show_output("tools", _run_capture("tool", "list"))
+        elif choice == "webhooks":
+            _show_output("webhooks", _run_capture("webhook", "list"))
+        elif choice == "sync":
+            _show_output("sync", _run_capture("sync"))
+
+
+# ---------------------------------------------------------------------------
+# Main menu loop
+# ---------------------------------------------------------------------------
+
+
+_MAIN_ITEMS = [
+    ("mission",     "Run a mission"),
+    ("genesis",     "New project (vision → market → branding → PRD → features → plan)"),
+    ("plan",        "Plan executor — multi-day autonomous (FSM-enforced)"),
+    ("worker",      "Workers — spawn / status / list / wait"),
+    ("handoff",     "Session handoff — 5-section memo for the next agent"),
+    ("hermes",      "Hermès (L2) — install / link / brief / ask"),
+    ("hermes-desktop", "Hermes Desktop remote backend (laptop UI on this VPS)"),
+    ("tmux",        "Tmux sessions (AISB / oracles / workers / install conf)"),
+    ("aisb-chat",   "Talk to AISB (Telegram fallback)"),
+    ("projects",    "Manage projects"),
+    ("accounts",    "Manage Claude Max accounts"),
+    ("audit",       "Quality Arsenal — 17 forensic audits"),
+    ("skills",      "Skill discovery + install + workflows"),
+    ("memory",      "Semantic memory across all sessions"),
+    ("learn",       "Smith reflection (self-improvement loop)"),
+    ("update",      "Auto-update OmegaOS (check / apply / banner / auto)"),
+    ("ua",          "Understand-Anything (knowledge-graph plugin)"),
+    ("ma",          "Managed Agents (Anthropic API; opt-in)"),
+    ("maintenance", "Smoke / prune / backup / cleanup / validate / upgrade"),
+    ("settings",    "Settings & integrations"),
+    ("status",      "Show omega status"),
+    ("doctor",      "Show omega doctor"),
+    ("quit",        "Quit"),
+]
+
+
+def _menu_tmux() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Tmux sessions", "OmegaOS tmux orchestration:",
+            items=[
+                ("list",    "List + browse sessions (categorised)"),
+                ("attach",  "Attach to a session"),
+                ("spawn",   "Spawn a new session (oracle / worker / aisb-chat / shell)"),
+                ("kill",    "Kill a session"),
+                ("health",  "Population summary + stale workers"),
+                ("cleanup", "Clean up stale worker sessions"),
+                ("config",  "Write recommended tmux.conf (Agentik_Tools/)"),
+                ("install", "Install tmux.conf into ~/.tmux.conf (with backup)"),
+                ("back",    "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "list":
+            _show_output("tmux sessions", _run_capture("tmux", "list"))
+        elif choice == "attach":
+            sessions_out = _run_capture("tmux", "list")
+            name = _whiptail_input("attach",
+                                    "Session name (see list below):\n\n" + sessions_out[:300])
+            if name:
+                cmd = _run_capture("tmux", "attach", name)
+                _show_output("attach",
+                              f"Run this in your terminal to attach:\n\n{cmd}")
+        elif choice == "spawn":
+            kind = _whiptail_menu(
+                "spawn", "Session kind:",
+                items=[("session",   "Plain shell session"),
+                       ("oracle",    "Project Oracle session"),
+                       ("worker",    "Worker session (needs --task)"),
+                       ("aisb-chat", "AISB chat fallback")],
+            )
+            if not kind:
+                continue
+            if kind == "aisb-chat":
+                _show_output("spawn", _run_capture("tmux", "spawn", "aisb-chat", "_"))
+                continue
+            name = _whiptail_input("spawn", "Name (project for oracle, project for worker):")
+            if not name:
+                continue
+            args = ["tmux", "spawn", kind, name]
+            if kind == "worker":
+                task = _whiptail_input("spawn", "Task name (worker):") or "task"
+                args += ["--task", task]
+            _show_output("spawn", _run_capture(*args))
+        elif choice == "kill":
+            name = _whiptail_input("kill", "Session name to kill:")
+            if name and _whiptail_yesno("kill", f"Really kill `{name}`?"):
+                _show_output("kill", _run_capture("tmux", "kill", name))
+        elif choice == "health":
+            _show_output("tmux health", _run_capture("tmux", "health"))
+        elif choice == "cleanup":
+            hours = _whiptail_input("cleanup", "Stale threshold (hours):", "24") or "24"
+            apply = _whiptail_yesno("cleanup", "Apply (no = dry-run)?")
+            args = ["tmux", "cleanup", "--hours", hours]
+            if apply:
+                args.append("--yes")
+            _show_output("tmux cleanup", _run_capture(*args))
+        elif choice == "config":
+            profile = _whiptail_menu(
+                "tmux config", "Profile:",
+                items=[("minimal", "Minimal (~30 lines)"),
+                       ("pro",     "Pro (paste-fix, kill forensics, smart scroll)")],
+            ) or "minimal"
+            _show_output("tmux config",
+                          _run_capture("tmux", "config", "--profile", profile))
+        elif choice == "install":
+            profile = _whiptail_menu(
+                "tmux install", "Profile (will be installed to ~/.tmux.conf):",
+                items=[("pro",     "Pro (paste-fix, kill forensics, smart scroll)"),
+                       ("minimal", "Minimal (~30 lines)")],
+            ) or "pro"
+            if _whiptail_yesno(
+                "tmux install",
+                f"Install '{profile}' profile to ~/.tmux.conf?\n\n"
+                "Existing ~/.tmux.conf will be backed up "
+                "(<file>.bak.<timestamp>).",
+            ):
+                _show_output("tmux install",
+                              _run_capture("tmux", "install",
+                                            "--profile", profile))
+
+
+def _menu_aisb_chat() -> None:
+    # Spawning + attach instructions; the actual conversation happens
+    # in the tmux session the operator attaches to.
+    out = _run_capture("aisb", "chat")
+    _show_output("AISB chat",
+                  out + "\n\nAttach with the command above, then talk to AISB. "
+                  "Type /quit to leave, /history to see the last 10 turns.")
+
+
+# ---------------------------------------------------------------------------
+# v0.19+ menus — surface the commands shipped in v0.10–v0.19 that the
+# original 12-entry menu never exposed.
+# ---------------------------------------------------------------------------
+
+
+def _menu_genesis() -> None:
+    """Project genesis pipeline (vision → market → branding → PRD → features → plan)."""
+    while True:
+        choice = _whiptail_menu(
+            "Genesis", "Project genesis pipeline:",
+            items=[
+                ("new",       "Initialise a new project"),
+                ("run",       "Advance the pipeline (resume-safe)"),
+                ("status",    "Phase + completed + stack snapshot"),
+                ("questions", "Stack-picker question list"),
+                ("delete",    "Destroy a project tree (--yes required)"),
+                ("back",      "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "new":
+            slug = _whiptail_input("genesis new", "Project slug (kebab-case):")
+            if not slug:
+                continue
+            intent = _whiptail_input("genesis new",
+                                      "One-line intent:") or ""
+            _show_output("genesis new",
+                          _run_capture("genesis", "new", slug,
+                                        "--intent", intent,
+                                        "--accept-defaults"))
+        elif choice == "run":
+            slug = _whiptail_input("genesis run", "Project slug:")
+            if slug:
+                _show_output(f"genesis run {slug}",
+                              _run_capture("genesis", "run", slug))
+        elif choice == "status":
+            slug = _whiptail_input("genesis status", "Project slug:")
+            if slug:
+                _show_output(f"genesis status {slug}",
+                              _run_capture("genesis", "status", slug))
+        elif choice == "questions":
+            _show_output("genesis questions",
+                          _run_capture("genesis", "questions"))
+        elif choice == "delete":
+            slug = _whiptail_input("genesis delete", "Project slug:")
+            if slug and _whiptail_yesno(
+                "genesis delete",
+                f"Really destroy project tree {slug!r}?",
+            ):
+                _show_output(f"genesis delete {slug}",
+                              _run_capture("genesis", "delete", slug,
+                                            "--yes"))
+
+
+def _menu_plan() -> None:
+    """v7 FSM-enforced plan executor."""
+    while True:
+        choice = _whiptail_menu(
+            "Plan v7", "FSM-enforced sequential plan executor:",
+            items=[
+                ("build",   "Ingest plan/DAG.json → store"),
+                ("next",    "Show the next eligible task"),
+                ("run",     "Autonomous multi-day loop"),
+                ("status",  "Completion % + per-state counts"),
+                ("list",    "List every task (filter by state)"),
+                ("retry",   "FAILED → PENDING (operator action)"),
+                ("back",    "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        slug = _whiptail_input(f"plan {choice}", "Project slug:")
+        if not slug:
+            continue
+        if choice == "list":
+            state = _whiptail_menu(
+                "plan list", "Filter by state (or All):",
+                items=[("all",   "All"),
+                       ("pending", "pending"),
+                       ("in_progress", "in_progress"),
+                       ("claimed_done", "claimed_done"),
+                       ("verified", "verified"),
+                       ("failed", "failed")],
+            )
+            args = ["plan", "list", slug]
+            if state and state != "all":
+                args += ["--state", state]
+            _show_output(f"plan list {slug}", _run_capture(*args))
+        elif choice == "retry":
+            tid = _whiptail_input("plan retry", "Task id (e.g. F-003):")
+            if tid:
+                _show_output(f"plan retry {slug} {tid}",
+                              _run_capture("plan", "retry", slug, tid))
+        else:
+            _show_output(f"plan {choice} {slug}",
+                          _run_capture("plan", choice, slug))
+
+
+def _menu_worker() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Workers", "Persistent-tmux worker lifecycle:",
+            items=[
+                ("list",   "List every worker on disk"),
+                ("spawn",  "Spawn a new worker"),
+                ("status", "Status of a worker by task_id"),
+                ("wait",   "Block until .done.json"),
+                ("back",   "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "list":
+            _show_output("worker list", _run_capture("worker", "list"))
+        elif choice == "spawn":
+            intent = _whiptail_input("worker spawn", "Intent:")
+            if intent:
+                role = _whiptail_input("worker spawn",
+                                        "Role:", "worker") or "worker"
+                _show_output(f"worker spawn",
+                              _run_capture("worker", "spawn", intent,
+                                            "--role", role))
+        elif choice in ("status", "wait"):
+            tid = _whiptail_input(f"worker {choice}", "Task id:")
+            if tid:
+                _show_output(f"worker {choice}",
+                              _run_capture("worker", choice, tid))
+
+
+def _menu_handoff() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Handoff", "5-section session memo:",
+            items=[
+                ("read",     "Print the latest handoff"),
+                ("list",     "Archive history per project"),
+                ("template", "Print the canonical template"),
+                ("from-done","Auto-draft from a task's .done.json"),
+                ("write",    "Write a handoff (interactive)"),
+                ("back",     "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "template":
+            _show_output("handoff template",
+                          _run_capture("handoff", "template"))
+            continue
+        slug = _whiptail_input(f"handoff {choice}", "Project slug:")
+        if not slug:
+            continue
+        if choice == "read":
+            _show_output(f"handoff read", _run_capture("handoff", "read",
+                                                        "--project", slug))
+        elif choice == "list":
+            _show_output(f"handoff list {slug}",
+                          _run_capture("handoff", "list", slug))
+        elif choice == "from-done":
+            tid = _whiptail_input("from-done", "Task id:")
+            if tid:
+                _show_output(f"handoff from-done {tid}",
+                              _run_capture("handoff", "from-done", tid,
+                                            "--project", slug, "--print"))
+        elif choice == "write":
+            _show_output("handoff write",
+                          _run_capture("handoff", "write",
+                                        "--project", slug))
+
+
+def _menu_hermes() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Hermès (Layer 2)", "Autonomous companion bridge:",
+            items=[
+                ("status",       "Installed + linked + OAuth + expiry"),
+                ("install",      "Run upstream install.sh (~1 min)"),
+                ("link",         "Bind to live Claude OAuth"),
+                ("brief-write",  "Teach Hermès what OmegaOS is (self-improvement)"),
+                ("brief-status", "Brief + observation log snapshot"),
+                ("ask",          "One-shot prompt → hermes → stdout"),
+                ("env",          "Print injected env (debug)"),
+                ("back",         "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "status":
+            _show_output("hermes status", _run_capture("hermes", "status"))
+        elif choice == "install":
+            _show_output("hermes install",
+                          _run_capture("hermes", "install", "--yes"))
+        elif choice == "link":
+            _show_output("hermes link", _run_capture("hermes", "link"))
+        elif choice == "brief-write":
+            _show_output("hermes brief write",
+                          _run_capture("hermes", "brief", "write"))
+        elif choice == "brief-status":
+            _show_output("hermes brief status",
+                          _run_capture("hermes", "brief", "status"))
+        elif choice == "ask":
+            prompt = _whiptail_input("hermes ask", "Prompt:")
+            if prompt:
+                _show_output("hermes ask",
+                              _run_capture("hermes", "ask", prompt))
+        elif choice == "env":
+            _show_output("hermes env", _run_capture("hermes", "env"))
+
+
+def _menu_hermes_desktop() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Hermes Desktop", "Remote backend for the desktop app:",
+            items=[
+                ("status",  "Token + port snapshot"),
+                ("install", "Generate token + print desktop profile"),
+                ("profile", "Print profile JSON"),
+                ("serve",   "Bind + serve the HTTP adapter (blocking)"),
+                ("back",    "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice in ("status", "install", "profile"):
+            _show_output(f"hermes-desktop {choice}",
+                          _run_capture("hermes-desktop", choice))
+        elif choice == "serve":
+            _whiptail_msg(
+                "hermes-desktop serve",
+                "This blocks the menu. Run it in a dedicated tmux session:\n\n"
+                "  tmux new -d -s omega-hd 'omega hermes-desktop serve'\n\n"
+                "Then attach with `tmux a -t omega-hd`.",
+            )
+
+
+def _menu_memory() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Semantic memory", "Cross-source memory search:",
+            items=[
+                ("stats",   "Index stats"),
+                ("reindex", "Rebuild the semantic index"),
+                ("search",  "Ranked search across sources"),
+                ("back",    "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice in ("stats", "reindex"):
+            _show_output(f"memory {choice}",
+                          _run_capture("memory", choice))
+        elif choice == "search":
+            q = _whiptail_input("memory search", "Query:")
+            if q:
+                _show_output(f"memory search",
+                              _run_capture("memory", "search", q))
+
+
+def _menu_learn() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Smith reflection", "Self-improvement loop:",
+            items=[
+                ("reflect", "Run reflection + write proposals"),
+                ("report",  "JSON dump of the latest reflection"),
+                ("back",    "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        _show_output(f"learn {choice}", _run_capture("learn", choice))
+
+
+def _menu_update() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Auto-update", "Update lifecycle:",
+            items=[
+                ("check",       "Check npm for a newer version"),
+                ("apply",       "Backup → install → migrate → verify (rollback on fail)"),
+                ("banner",      "Print outdated banner to stderr"),
+                ("auto-status", "Daily auto-apply charter status"),
+                ("auto-enable", "Enable daily auto-apply"),
+                ("auto-disable","Disable daily auto-apply"),
+                ("back",        "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice.startswith("auto-"):
+            op = choice.split("-", 1)[1]
+            _show_output(f"update auto {op}",
+                          _run_capture("update", "auto", op))
+        else:
+            _show_output(f"update {choice}",
+                          _run_capture("update", choice))
+
+
+def _menu_ua() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Understand-Anything", "Knowledge-graph plugin bridge:",
+            items=[
+                ("install", "Install the Claude Code plugin (uses Max OAuth)"),
+                ("run",     "Trigger /understand on a project"),
+                ("consume", "Merge the produced graph into GraphRetriever"),
+                ("back",    "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "install":
+            _show_output("ua install", _run_capture("ua", "install"))
+        else:
+            project = _whiptail_input(f"ua {choice}", "Project path:")
+            if project:
+                _show_output(f"ua {choice}",
+                              _run_capture("ua", choice, project))
+
+
+def _menu_ma() -> None:
+    while True:
+        choice = _whiptail_menu(
+            "Managed Agents", "Anthropic API (opt-in; needs ANTHROPIC_API_KEY):",
+            items=[
+                ("info",    "API key status + cached IDs"),
+                ("agent",   "Manage agents"),
+                ("env",     "Manage environments"),
+                ("session", "Manage sessions"),
+                ("run",     "One-shot: create + send + stream"),
+                ("back",    "← Back"),
+            ],
+        )
+        if choice in (None, "back"):
+            return
+        if choice == "info":
+            _show_output("ma info", _run_capture("ma", "info"))
+        elif choice == "run":
+            intent = _whiptail_input("ma run", "Intent:")
+            if intent:
+                _show_output("ma run", _run_capture("ma", "run", intent))
+        else:
+            _whiptail_msg(
+                f"ma {choice}",
+                f"Use `omega ma {choice} --help` from the shell for the "
+                f"full sub-tree (list/create/get/delete/...). The menu "
+                f"surfaces the top-level routes only.",
+            )
+
+
+def _text_menu() -> int:
+    """Plain-stdin fallback used when whiptail is missing (a fresh Mac
+    that never got `brew install newt`, or any minimal environment).
+
+    Prints a numbered list of the SAME items the whiptail menu would
+    show, reads a number, and dispatches to the same handler. Never
+    silently exits — if the user just hits Enter we re-print the menu.
+    """
+    from omega_engine import __version__
+    handlers: dict[str, callable] = {
+        "mission":      _menu_mission,
+        "genesis":      _menu_genesis,
+        "plan":         _menu_plan,
+        "worker":       _menu_worker,
+        "handoff":      _menu_handoff,
+        "hermes":       _menu_hermes,
+        "hermes-desktop": _menu_hermes_desktop,
+        "tmux":         _menu_tmux,
+        "aisb-chat":    _menu_aisb_chat,
+        "projects":     _menu_projects,
+        "accounts":     _menu_accounts,
+        "audit":        _menu_audit,
+        "skills":       _menu_skills,
+        "memory":       _menu_memory,
+        "learn":        _menu_learn,
+        "update":       _menu_update,
+        "ua":           _menu_ua,
+        "ma":           _menu_ma,
+        "maintenance":  _menu_maintenance,
+        "settings":     _menu_settings,
+        "status":       _menu_status,
+        "doctor":       _menu_doctor,
+    }
+    while True:
+        print()
+        print(f"  Omega OS v{__version__} — text menu")
+        print(f"  (whiptail not on PATH — install it for the rich UI: "
+              f"`brew install newt` on macOS, `apt-get install whiptail` on Linux)")
+        print()
+        for i, (tag, label) in enumerate(_MAIN_ITEMS, 1):
+            if tag == "quit":
+                print(f"   0)  Quit")
+            else:
+                print(f"  {i:2})  {label}")
+        print()
+        try:
+            raw = input("  pick a number (0 to quit, just Enter to refresh): ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+        if raw == "" or raw == "?":
+            continue
+        if raw in ("0", "q", "quit", "exit"):
+            return 0
+        try:
+            n = int(raw)
+        except ValueError:
+            print(f"  not a number: {raw!r}")
+            continue
+        if n < 1 or n > len(_MAIN_ITEMS):
+            print(f"  out of range: {n}")
+            continue
+        tag, _ = _MAIN_ITEMS[n - 1]
+        if tag == "quit":
+            return 0
+        fn = handlers.get(tag)
+        if fn is None:
+            print(f"  no handler bound for {tag}")
+            continue
+        try:
+            fn()
+        except KeyboardInterrupt:
+            print("\n  (interrupted)")
+
+
+def run_menu() -> int:
+    """Entry point — show the main menu and dispatch until quit.
+
+    Whiptail when available (rich UI), text fallback otherwise. Never
+    returns silently — every machine sees SOMETHING the moment they type
+    `omega`.
+    """
+    if not _have("whiptail"):
+        return _text_menu()
+    while True:
+        choice = _whiptail_menu(
+            "Omega OS", "What do you want to do?",
+            items=_MAIN_ITEMS,
+        )
+        if choice in (None, "quit"):
+            return 0
+        try:
+            if choice == "mission":         _menu_mission()
+            elif choice == "genesis":       _menu_genesis()
+            elif choice == "plan":          _menu_plan()
+            elif choice == "worker":        _menu_worker()
+            elif choice == "handoff":       _menu_handoff()
+            elif choice == "hermes":        _menu_hermes()
+            elif choice == "hermes-desktop":_menu_hermes_desktop()
+            elif choice == "tmux":          _menu_tmux()
+            elif choice == "aisb-chat":     _menu_aisb_chat()
+            elif choice == "projects":      _menu_projects()
+            elif choice == "accounts":      _menu_accounts()
+            elif choice == "audit":         _menu_audit()
+            elif choice == "skills":        _menu_skills()
+            elif choice == "memory":        _menu_memory()
+            elif choice == "learn":         _menu_learn()
+            elif choice == "update":        _menu_update()
+            elif choice == "ua":            _menu_ua()
+            elif choice == "ma":            _menu_ma()
+            elif choice == "maintenance":   _menu_maintenance()
+            elif choice == "settings":      _menu_settings()
+            elif choice == "status":        _menu_status()
+            elif choice == "doctor":        _menu_doctor()
+        except KeyboardInterrupt:
+            return 0